1552 lines
35 KiB
Markdown
1552 lines
35 KiB
Markdown
|
||
# Zopo Work OS — Technical Architecture
|
||
|
||
> Status: working technical specification
|
||
> Audience: engineering, platform, infrastructure, security, and agent teams
|
||
> Scope: technical architecture, runtime boundaries, data flow, execution, security, scaling, and implementation decisions
|
||
> Assumption: the application begins from an existing Better-T-Stack monorepo with web and Expo applications plus shared packages
|
||
|
||
## 1. Technical objective
|
||
|
||
Build a multi-tenant Work OS that:
|
||
|
||
- Maintains durable organizations, projects, goals, work units, runs, artifacts, and outcomes.
|
||
- Provides one global conversation and scoped work-unit conversations.
|
||
- Extracts candidate work continuously from conversation and connected systems.
|
||
- Runs coding agents inside isolated, reproducible environments.
|
||
- Supports autonomous execution while preserving explicit human approval boundaries.
|
||
- Streams agent progress into durable work-unit state.
|
||
- Produces inspectable artifacts such as commits, pull requests, test reports, previews, documents, and review notes.
|
||
- Scales across many organizations, repositories, concurrent work units, and execution environments.
|
||
- Keeps execution harnesses and model providers replaceable.
|
||
|
||
The central architectural rule is:
|
||
|
||
> Work OS owns intent and durable state. Flow agents own orchestration. AgentOS owns agent runtime coordination. Harnesses own individual agent loops. Sandboxes own full-system execution. Git owns source history. Artifact storage owns generated outputs.
|
||
|
||
---
|
||
|
||
## 2. High-level architecture
|
||
|
||
Separate the system into a **control plane** and an **execution plane**.
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
User[User]
|
||
|
||
subgraph Client[Client applications]
|
||
Web[Web application]
|
||
Mobile[Expo application]
|
||
end
|
||
|
||
subgraph Edge[Application edge]
|
||
API[Application API]
|
||
Realtime[Realtime gateway]
|
||
end
|
||
|
||
subgraph Control[Control plane]
|
||
Auth[Identity and tenancy]
|
||
WorkGraph[Work graph and relational state]
|
||
Conversation[Conversation service]
|
||
Flow[Zopo Flow Agent]
|
||
Context[Context assembler and memory]
|
||
Policy[Policy and approval engine]
|
||
Scheduler[Run scheduler and workflow engine]
|
||
Events[Event and provenance log]
|
||
Notifications[Attention and notification service]
|
||
end
|
||
|
||
subgraph Shared[Shared services]
|
||
Git[Managed or connected Git]
|
||
Gateway[Model gateway]
|
||
Integrations[Executor / integration gateway]
|
||
Secrets[Secrets and workload identity broker]
|
||
Artifact[Artifact and object storage]
|
||
Search[Retrieval and indexing]
|
||
Preview[Preview routing gateway]
|
||
Observability[Logs metrics traces and billing]
|
||
end
|
||
|
||
subgraph Execution[Execution plane]
|
||
Actor[AgentOS run actor]
|
||
Harness[OpenCode or other ACP harness]
|
||
Sandbox[Full Linux sandbox]
|
||
Runtime[Project services browsers tests builds]
|
||
end
|
||
|
||
User --> Web
|
||
User --> Mobile
|
||
Web --> API
|
||
Mobile --> API
|
||
Web <--> Realtime
|
||
Mobile <--> Realtime
|
||
|
||
API --> Auth
|
||
API --> WorkGraph
|
||
API --> Conversation
|
||
API --> Policy
|
||
|
||
Conversation --> Flow
|
||
WorkGraph --> Flow
|
||
Flow --> Context
|
||
Flow --> Scheduler
|
||
Flow --> Policy
|
||
Flow --> Gateway
|
||
Flow --> Integrations
|
||
|
||
Scheduler --> Actor
|
||
Actor <--> Harness
|
||
Actor <--> Sandbox
|
||
Harness --> Gateway
|
||
Harness --> Integrations
|
||
Sandbox --> Git
|
||
Sandbox --> Runtime
|
||
Runtime --> Preview
|
||
|
||
Actor --> Events
|
||
Sandbox --> Events
|
||
Git --> Events
|
||
Events --> WorkGraph
|
||
Events --> Realtime
|
||
Events --> Observability
|
||
Artifact --> WorkGraph
|
||
Context --> Search
|
||
WorkGraph --> Search
|
||
Policy --> Notifications
|
||
```
|
||
|
||
---
|
||
|
||
## 3. System components and ownership
|
||
|
||
## 3.1 Client applications
|
||
|
||
The web and Expo applications are product surfaces only.
|
||
|
||
They should:
|
||
|
||
- Render organization, project, work-unit, run, artifact, and attention state.
|
||
- Send user commands through the application API.
|
||
- Subscribe to realtime updates.
|
||
- Upload attachments through signed or brokered flows.
|
||
- Never connect directly to model providers, Git internals, agent harnesses, or sandboxes.
|
||
|
||
The frontend should issue domain commands such as:
|
||
|
||
- Create work unit.
|
||
- Continue work.
|
||
- Change composer scope.
|
||
- Approve plan.
|
||
- Resolve blocker.
|
||
- Review artifact.
|
||
- Request changes.
|
||
- Pause run.
|
||
- Cancel run.
|
||
- Approve merge.
|
||
- Approve deployment.
|
||
|
||
## 3.2 Application API
|
||
|
||
The application API is the only public backend interface used by product clients.
|
||
|
||
Responsibilities:
|
||
|
||
- Authentication and authorization.
|
||
- Organization and project scoping.
|
||
- CRUD for stable domain entities.
|
||
- Domain command validation.
|
||
- Conversation ingestion.
|
||
- Attachment metadata.
|
||
- Query endpoints for cards, workspaces, activity, and attention.
|
||
- Realtime subscription authorization.
|
||
- Idempotency handling.
|
||
|
||
Avoid exposing internal runtime APIs directly through the application surface.
|
||
|
||
## 3.3 Identity and tenancy
|
||
|
||
A user has one Work OS identity.
|
||
|
||
Organizations are hard tenancy boundaries.
|
||
|
||
Every durable and transient entity must include explicit tenant scope:
|
||
|
||
- `organization_id`
|
||
- `project_id` where applicable
|
||
- `work_unit_id` where applicable
|
||
- `run_id` where applicable
|
||
|
||
Authorization should be deny-by-default and evaluated on every command and query.
|
||
|
||
Cross-organization queries must be explicit portfolio-level operations and must not blend underlying knowledge or execution context.
|
||
|
||
## 3.4 Work graph and relational state
|
||
|
||
The work graph is the canonical product database.
|
||
|
||
Recommended initial implementation:
|
||
|
||
- Relational database for authoritative state.
|
||
- Event table for append-only provenance and replay.
|
||
- Materialized projections for cards, attention, portfolio summaries, and activity feeds.
|
||
- Object storage for large artifacts.
|
||
- Search index for retrieval.
|
||
|
||
Core entities:
|
||
|
||
- User.
|
||
- Organization.
|
||
- Membership.
|
||
- Project.
|
||
- Project source.
|
||
- Goal.
|
||
- Signal.
|
||
- Candidate.
|
||
- Work unit.
|
||
- Work-unit relation.
|
||
- Step.
|
||
- Run.
|
||
- Run attempt.
|
||
- Agent session.
|
||
- Blocker.
|
||
- Decision.
|
||
- Approval.
|
||
- Artifact.
|
||
- Source reference.
|
||
- Result.
|
||
- Learning.
|
||
- Conversation message.
|
||
- Composer scope.
|
||
- Integration connection.
|
||
- Policy.
|
||
- Workload identity.
|
||
|
||
The work-unit record should not be a large agent-authored JSON blob. Store meaningful structured fields and derive summaries through explicit projections.
|
||
|
||
## 3.5 Event and provenance log
|
||
|
||
All meaningful system changes should be represented as events.
|
||
|
||
Example event envelope:
|
||
|
||
```json
|
||
{
|
||
"event_id": "evt_01...",
|
||
"type": "run.verification_completed",
|
||
"organization_id": "org_01...",
|
||
"project_id": "prj_01...",
|
||
"work_unit_id": "wrk_01...",
|
||
"run_id": "run_01...",
|
||
"actor_type": "agent",
|
||
"actor_id": "opencode",
|
||
"source_type": "agentos_session",
|
||
"source_id": "session_01...",
|
||
"sequence": 184,
|
||
"payload": {
|
||
"summary": "All unit and browser tests passed",
|
||
"artifact_ids": ["art_01..."]
|
||
},
|
||
"created_at": "2026-07-23T12:00:00Z"
|
||
}
|
||
```
|
||
|
||
Requirements:
|
||
|
||
- Monotonic sequence per run or actor stream.
|
||
- Idempotent ingestion.
|
||
- Immutable original payload.
|
||
- Normalized derived state.
|
||
- Traceability from card state to supporting events.
|
||
- Explicit distinction between raw evidence, agent interpretation, and human decision.
|
||
|
||
## 3.6 Conversation service
|
||
|
||
The system maintains a persistent conversation per user workspace with scoped context.
|
||
|
||
Messages should contain:
|
||
|
||
- Organization scope.
|
||
- Optional project scope.
|
||
- Optional work-unit scope.
|
||
- Author.
|
||
- Content blocks.
|
||
- Attachments.
|
||
- Source references.
|
||
- Extraction status.
|
||
- Relationship to domain events.
|
||
|
||
The conversation service should:
|
||
|
||
- Persist the exact user message.
|
||
- Publish it for extraction and orchestration.
|
||
- Support global and work-unit scope without creating new sessions.
|
||
- Allow one message to reference several work units.
|
||
- Preserve source links when structured state is extracted.
|
||
|
||
## 3.7 Zopo Flow Agent
|
||
|
||
The Flow Agent is the orchestration layer above specialist agents.
|
||
|
||
Responsibilities:
|
||
|
||
- Interpret user intent.
|
||
- Extract signals and candidate work.
|
||
- Match new information to existing work.
|
||
- Detect duplicates and relationships.
|
||
- Build or update work briefs.
|
||
- Decide whether a human question is required.
|
||
- Select an execution strategy.
|
||
- Create runs.
|
||
- Monitor run events.
|
||
- Handle retry, fallback, or escalation decisions.
|
||
- Summarize results into work-unit state.
|
||
- Create approval requests.
|
||
- Propose follow-up work.
|
||
|
||
The Flow Agent must not be the sole source of durable truth. Its outputs are validated into domain commands and events.
|
||
|
||
It should not directly mutate repositories. Coding work is delegated to a harness running in an isolated execution environment.
|
||
|
||
## 3.8 Context and memory layer
|
||
|
||
Use four memory classes.
|
||
|
||
### Canonical project knowledge
|
||
|
||
Versioned, reviewable documents such as:
|
||
|
||
- `product.md`
|
||
- `design.md`
|
||
- `tech.md`
|
||
- `business.md`
|
||
- `AGENTS.md`
|
||
- README files
|
||
- decision records
|
||
- repository-local conventions
|
||
|
||
Prefer storing project-level canonical knowledge in Git alongside the project when practical.
|
||
|
||
### Structured operational memory
|
||
|
||
Stored in the database:
|
||
|
||
- Goals.
|
||
- Work-unit state.
|
||
- Requirements.
|
||
- Decisions.
|
||
- Approvals.
|
||
- Blockers.
|
||
- Dependencies.
|
||
- Results.
|
||
|
||
### Episodic memory
|
||
|
||
Stored as events and transcripts:
|
||
|
||
- User messages.
|
||
- Agent runs.
|
||
- Tool calls.
|
||
- Errors.
|
||
- Reviews.
|
||
- Deployments.
|
||
- Human interventions.
|
||
|
||
### Retrieval index
|
||
|
||
A derived index over:
|
||
|
||
- Canonical documents.
|
||
- Repository content.
|
||
- Conversation.
|
||
- Work-unit events.
|
||
- Artifacts.
|
||
- Connected external sources.
|
||
|
||
The retrieval index is not authoritative. It returns source references that are assembled into a run-specific context pack.
|
||
|
||
## 3.9 Context assembly
|
||
|
||
Do not inject all available knowledge into every run.
|
||
|
||
Build a **run context pack** using explicit precedence:
|
||
|
||
1. Organization policy.
|
||
2. Project goals and canonical context.
|
||
3. Repository conventions and instructions.
|
||
4. Work-unit objective, requirements, and decisions.
|
||
5. Relevant evidence and artifacts.
|
||
6. Current run instructions.
|
||
7. Runtime and tool constraints.
|
||
|
||
Every context item should retain:
|
||
|
||
- Source.
|
||
- Scope.
|
||
- Timestamp.
|
||
- Confidence or verification status.
|
||
- Revision identifier when applicable.
|
||
|
||
Context assembly should be deterministic enough to audit and reproduce.
|
||
|
||
## 3.10 Policy and approval engine
|
||
|
||
The policy engine sits above harness permissions and runtime capabilities.
|
||
|
||
It determines whether an action is:
|
||
|
||
- Automatically allowed.
|
||
- Allowed under standing policy.
|
||
- Requires human approval.
|
||
- Denied.
|
||
|
||
Policy examples:
|
||
|
||
- Create branch automatically.
|
||
- Push work branch automatically.
|
||
- Create pull request automatically.
|
||
- Merge only with approval.
|
||
- Deploy preview automatically.
|
||
- Deploy production only with approval.
|
||
- Never send customer communication without review.
|
||
- Never access production data from a default coding run.
|
||
|
||
Approval records must include:
|
||
|
||
- Exact requested action.
|
||
- Parameters.
|
||
- Requested capability.
|
||
- Evidence and rationale.
|
||
- Risk level.
|
||
- Expiration.
|
||
- User decision.
|
||
- Resulting action event.
|
||
|
||
## 3.11 Run scheduler and workflow engine
|
||
|
||
The scheduler converts accepted work into bounded execution runs.
|
||
|
||
Responsibilities:
|
||
|
||
- Queue management.
|
||
- Tenant quotas.
|
||
- Priority.
|
||
- Fairness.
|
||
- Concurrency limits.
|
||
- Run leasing.
|
||
- Retry policy.
|
||
- Budget allocation.
|
||
- Cancellation.
|
||
- Workflow checkpoints.
|
||
- Waiting for approvals.
|
||
- Resuming after approval.
|
||
|
||
Run lifecycle:
|
||
|
||
```text
|
||
queued
|
||
→ provisioning
|
||
→ preparing
|
||
→ running
|
||
→ waiting_for_input | verifying | failed | cancelled
|
||
→ succeeded
|
||
```
|
||
|
||
A run should use idempotent steps and persist progress before waiting on human input.
|
||
|
||
## 3.12 AgentOS runtime
|
||
|
||
AgentOS is the durable supervisor and harness runtime for an active run.
|
||
|
||
Recommended scope:
|
||
|
||
- One AgentOS actor per active run or isolated workbox.
|
||
- Durable identity for the run environment.
|
||
- Harness session lifecycle.
|
||
- Event streaming.
|
||
- Permission requests.
|
||
- Lightweight filesystem and process coordination.
|
||
- Sleep and wake when safe.
|
||
|
||
Do not use one giant actor per user or organization.
|
||
|
||
The actor key should include tenant and work scope, for example:
|
||
|
||
```text
|
||
org:{orgId}:project:{projectId}:work:{workUnitId}:run:{runId}
|
||
```
|
||
|
||
The durable work unit must survive destruction or replacement of its execution actor.
|
||
|
||
## 3.13 Agent harness
|
||
|
||
OpenCode is the initial coding harness.
|
||
|
||
The architecture should support other ACP-compatible or adapted harnesses later.
|
||
|
||
The harness owns:
|
||
|
||
- Model interaction loop.
|
||
- Tool selection.
|
||
- Repository inspection.
|
||
- File editing.
|
||
- Shell requests.
|
||
- Local reasoning state.
|
||
- Session-level progress.
|
||
|
||
The harness does not own:
|
||
|
||
- Product work-unit state.
|
||
- Organization policy.
|
||
- Billing.
|
||
- Global memory.
|
||
- Project permissions.
|
||
- Long-term artifact retention.
|
||
|
||
Prefer controlling OpenCode through AgentOS rather than exposing its standalone server directly to product clients.
|
||
|
||
## 3.14 Full Linux sandbox
|
||
|
||
A full sandbox is the compatibility and heavy-execution environment.
|
||
|
||
It provides:
|
||
|
||
- Repository checkout.
|
||
- Writable branch or worktree.
|
||
- Native binaries.
|
||
- Package installation.
|
||
- Language runtimes.
|
||
- Databases.
|
||
- Browser automation.
|
||
- Dev servers.
|
||
- Tests and builds.
|
||
- File watching when required.
|
||
- Preview processes.
|
||
|
||
AgentOS should supervise and communicate with the sandbox through explicit adapters or bindings.
|
||
|
||
Recommended division:
|
||
|
||
```text
|
||
AgentOS
|
||
- durable run identity
|
||
- harness session
|
||
- approvals
|
||
- lightweight coordination
|
||
|
||
Sandbox
|
||
- full repository filesystem
|
||
- native commands
|
||
- services
|
||
- browser
|
||
- tests
|
||
- builds
|
||
```
|
||
|
||
For known first-party templates, some work may run directly in the lighter environment. Imported arbitrary repositories should default to a full sandbox.
|
||
|
||
## 3.15 Workbox
|
||
|
||
A Workbox is the product-neutral internal term for the execution capsule beneath a run.
|
||
|
||
A Workbox contains:
|
||
|
||
- Repository checkout.
|
||
- Isolated branch.
|
||
- Runtime recipe.
|
||
- Harness configuration.
|
||
- Project skills.
|
||
- Temporary credentials.
|
||
- Running services.
|
||
- Preview endpoints.
|
||
- Test outputs.
|
||
|
||
A Workbox is ephemeral or replaceable. The work unit is durable.
|
||
|
||
Default isolation rule:
|
||
|
||
> One writable checkout per active work unit or mutating run.
|
||
|
||
Parallel read-only runs may share immutable snapshots. Parallel mutating runs should use separate branches and separate Workboxes.
|
||
|
||
## 3.16 Managed or connected Git
|
||
|
||
Git is the source history layer.
|
||
|
||
Project creation modes:
|
||
|
||
- Create from a managed template repository.
|
||
- Connect an external repository.
|
||
- Import and mirror an existing repository.
|
||
- Start with managed Git and add an external remote later.
|
||
|
||
Identity model:
|
||
|
||
- One Work OS user identity.
|
||
- Internal service identities for automation.
|
||
- Repository-scoped, short-lived credentials.
|
||
- No requirement for users to manage a second visible Git account.
|
||
|
||
Branching model:
|
||
|
||
```text
|
||
main
|
||
├── work/W-102/oauth-fix
|
||
├── work/W-103/team-invitations
|
||
└── work/W-104/pricing-copy
|
||
```
|
||
|
||
Git may remain hidden in the product surface, but the user must retain portability through export, clone access, patch download, or external remotes.
|
||
|
||
## 3.17 Project templates
|
||
|
||
Initial templates may include:
|
||
|
||
- React web application.
|
||
- Hono service.
|
||
- Express API.
|
||
- Full-stack application.
|
||
- API-only service.
|
||
- Expo application.
|
||
- Monorepo starter.
|
||
|
||
A template should define:
|
||
|
||
- Source files.
|
||
- Runtime versions.
|
||
- Install command.
|
||
- Test command.
|
||
- Verification command.
|
||
- Development command.
|
||
- Service ports.
|
||
- Preview behavior.
|
||
- Project context prompts.
|
||
- Default policies.
|
||
- Agent skills.
|
||
|
||
Templates should generate a reusable base snapshot after successful setup and verification.
|
||
|
||
## 3.18 Project configuration files
|
||
|
||
Recommended repository structure:
|
||
|
||
```text
|
||
/
|
||
├── README.md
|
||
├── AGENTS.md
|
||
├── product.md
|
||
├── design.md
|
||
├── tech.md
|
||
│
|
||
├── .zopo/
|
||
│ ├── project.yaml
|
||
│ ├── services.yaml
|
||
│ ├── policies.yaml
|
||
│ ├── lifecycle/
|
||
│ │ ├── setup
|
||
│ │ ├── resume
|
||
│ │ ├── verify
|
||
│ │ └── preview
|
||
│ └── skills/
|
||
│ ├── testing/
|
||
│ │ └── SKILL.md
|
||
│ ├── reviewing/
|
||
│ │ └── SKILL.md
|
||
│ └── deploying/
|
||
│ └── SKILL.md
|
||
└── apps/
|
||
```
|
||
|
||
Example `project.yaml`:
|
||
|
||
```yaml
|
||
name: example-project
|
||
runtime:
|
||
template: react-hono
|
||
node: "24"
|
||
packageManager: pnpm
|
||
|
||
commands:
|
||
install: pnpm install --frozen-lockfile
|
||
test: pnpm test
|
||
verify: pnpm run verify
|
||
dev: pnpm dev
|
||
|
||
services:
|
||
web:
|
||
port: 3000
|
||
api:
|
||
port: 4000
|
||
|
||
changes:
|
||
workflow: pull_request
|
||
baseBranch: main
|
||
|
||
approvals:
|
||
pushBranch: automatic
|
||
createPullRequest: automatic
|
||
mergePullRequest: required
|
||
deployPreview: automatic
|
||
deployProduction: required
|
||
```
|
||
|
||
## 3.19 Executor integration gateway
|
||
|
||
Executor acts as the shared integration and tool gateway for external systems.
|
||
|
||
It may expose:
|
||
|
||
- GitHub APIs.
|
||
- Slack.
|
||
- Linear.
|
||
- Intercom.
|
||
- Analytics.
|
||
- CRM.
|
||
- Cloud services.
|
||
- Internal APIs.
|
||
- Custom functions.
|
||
|
||
Responsibilities:
|
||
|
||
- Connection management.
|
||
- Tool catalog.
|
||
- Scoped authentication.
|
||
- Tool-level policies.
|
||
- Approval requirements.
|
||
- Auditable invocation.
|
||
|
||
It should not own:
|
||
|
||
- Shell execution.
|
||
- Repository filesystem operations.
|
||
- Work-unit state.
|
||
- Agent session state.
|
||
- Sandbox lifecycle.
|
||
|
||
The Flow Agent may receive broader organization-level tools. OpenCode should receive only the project- and run-scoped tools needed for the current task.
|
||
|
||
## 3.20 Model gateway
|
||
|
||
All model calls should route through a model gateway.
|
||
|
||
Responsibilities:
|
||
|
||
- Provider credentials.
|
||
- Automatic model routing.
|
||
- Tenant attribution.
|
||
- Cost accounting.
|
||
- Budget enforcement.
|
||
- Rate limits.
|
||
- Retries and fallback.
|
||
- Prompt and response logging under policy.
|
||
- Redaction.
|
||
- Run-scoped credentials.
|
||
|
||
The product should not expose model selection by default.
|
||
|
||
A run token should be short-lived and scoped:
|
||
|
||
```json
|
||
{
|
||
"organization_id": "org_01...",
|
||
"project_id": "prj_01...",
|
||
"work_unit_id": "wrk_01...",
|
||
"run_id": "run_01...",
|
||
"model_classes": ["coding-standard", "coding-fast"],
|
||
"budget_usd": 8,
|
||
"expires_in_seconds": 3600
|
||
}
|
||
```
|
||
|
||
## 3.21 Artifact storage
|
||
|
||
Large and durable outputs belong in object storage, not actor state or relational rows.
|
||
|
||
Artifact types include:
|
||
|
||
- Patch.
|
||
- Commit bundle.
|
||
- Test report.
|
||
- Build log.
|
||
- Screenshot.
|
||
- Video.
|
||
- Preview snapshot.
|
||
- Research document.
|
||
- Review report.
|
||
- Generated file.
|
||
|
||
Artifact metadata should include:
|
||
|
||
- Tenant scope.
|
||
- Work-unit scope.
|
||
- Run scope.
|
||
- Type.
|
||
- Content hash.
|
||
- Producer.
|
||
- Source event.
|
||
- Retention policy.
|
||
- Access policy.
|
||
|
||
## 3.22 Preview gateway
|
||
|
||
Preview environments should be exposed through a controlled gateway rather than raw sandbox ports.
|
||
|
||
Requirements:
|
||
|
||
- Authenticated access.
|
||
- Project- and run-scoped routing.
|
||
- Short-lived URLs where appropriate.
|
||
- Service health.
|
||
- Automatic shutdown.
|
||
- Event emission when preview becomes ready or fails.
|
||
- Screenshot or browser verification integration.
|
||
|
||
## 3.23 Observability and billing
|
||
|
||
Every execution path should emit:
|
||
|
||
- Logs.
|
||
- Metrics.
|
||
- Traces.
|
||
- Cost.
|
||
- Token use.
|
||
- Runtime duration.
|
||
- Tool calls.
|
||
- Network use.
|
||
- Artifact size.
|
||
- Retry count.
|
||
- User intervention count.
|
||
|
||
Required correlation dimensions:
|
||
|
||
```text
|
||
organization_id
|
||
project_id
|
||
work_unit_id
|
||
run_id
|
||
actor_id
|
||
session_id
|
||
sandbox_id
|
||
sequence
|
||
timestamp
|
||
```
|
||
|
||
The system should calculate cost per successful outcome, not merely cost per model request.
|
||
|
||
---
|
||
|
||
## 4. Core execution flows
|
||
|
||
## 4.1 Project onboarding
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
actor User
|
||
participant UI as Work OS UI
|
||
participant Project as Project Service
|
||
participant Git as Git Service
|
||
participant Template as Template Builder
|
||
participant Context as Context Service
|
||
participant Snapshot as Snapshot Service
|
||
|
||
User->>UI: Create project
|
||
UI->>Project: Name, organization, template or repository
|
||
Project->>Git: Create, import, or connect repository
|
||
Git-->>Project: Repository identity
|
||
Project->>Template: Apply project template if selected
|
||
Template->>Git: Commit initial files
|
||
Project->>Context: Generate context-document drafts
|
||
Context-->>UI: Ask user to review product, design, and technical context
|
||
User->>UI: Confirm context
|
||
UI->>Git: Commit canonical project documents
|
||
Project->>Template: Run setup and verification
|
||
Template->>Snapshot: Create sanitized base snapshot
|
||
Snapshot-->>Project: Snapshot ready
|
||
Project-->>UI: Project active
|
||
```
|
||
|
||
## 4.2 Prompt to candidate work
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
actor User
|
||
participant UI as Composer
|
||
participant Conversation as Conversation Service
|
||
participant Flow as Flow Agent
|
||
participant Work as Work Graph
|
||
participant Realtime as Realtime Gateway
|
||
|
||
User->>UI: Describe request or problem
|
||
UI->>Conversation: Persist message with scope
|
||
Conversation->>Flow: Publish extraction job
|
||
Flow->>Work: Search related work and sources
|
||
Flow->>Work: Create or update signal
|
||
alt Existing work matches
|
||
Flow->>Work: Attach signal and update understanding
|
||
else New outcome detected
|
||
Flow->>Work: Create candidate work
|
||
end
|
||
Work->>Realtime: Publish materialized update
|
||
Realtime-->>UI: Show updated or new card
|
||
```
|
||
|
||
## 4.3 Accepted work to verified pull request
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
actor User
|
||
participant UI as Work OS UI
|
||
participant Flow as Flow Agent
|
||
participant State as Work Graph
|
||
participant Scheduler as Scheduler
|
||
participant AgentOS as AgentOS Actor
|
||
participant Harness as OpenCode
|
||
participant Box as Workbox Sandbox
|
||
participant Git as Git Service
|
||
participant Artifact as Artifact Store
|
||
|
||
User->>UI: Approve candidate and start work
|
||
UI->>State: Accept work unit
|
||
State->>Flow: Work unit ready
|
||
Flow->>State: Persist objective and acceptance criteria
|
||
Flow->>Scheduler: Create implementation run
|
||
Scheduler->>AgentOS: Provision run actor
|
||
AgentOS->>Box: Create isolated sandbox
|
||
Box->>Git: Clone repository and create work branch
|
||
AgentOS->>Harness: Start OpenCode session
|
||
Flow->>Harness: Send run context pack
|
||
|
||
loop Execution
|
||
Harness->>Box: Inspect, edit, and execute
|
||
Harness-->>AgentOS: Stream events and requests
|
||
AgentOS->>State: Persist meaningful run events
|
||
State-->>UI: Update work card
|
||
end
|
||
|
||
Harness->>Box: Run verification
|
||
Box->>Artifact: Upload reports and screenshots
|
||
Box->>Git: Commit and push branch
|
||
Flow->>Git: Create pull request
|
||
Flow->>State: Attach artifacts and move to Review
|
||
State-->>UI: Show PR, preview, evidence, and human action
|
||
```
|
||
|
||
## 4.4 Approval continuation
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Harness as Agent Harness
|
||
participant AgentOS as AgentOS
|
||
participant Policy as Policy Engine
|
||
participant UI as Attention Queue
|
||
actor User
|
||
|
||
Harness->>AgentOS: Request sensitive action
|
||
AgentOS->>Policy: Evaluate action and scope
|
||
alt Automatically allowed
|
||
Policy-->>AgentOS: Allow
|
||
else Requires human approval
|
||
Policy->>UI: Create approval request
|
||
UI-->>User: Show action, evidence, risk, and impact
|
||
User->>UI: Approve, modify, or reject
|
||
UI->>Policy: Persist decision
|
||
Policy-->>AgentOS: Resume with bounded permission
|
||
else Denied
|
||
Policy-->>AgentOS: Deny with reason
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## 5. State machines
|
||
|
||
Keep product, run, and environment state separate.
|
||
|
||
## 5.1 Work-unit state
|
||
|
||
```text
|
||
proposed
|
||
→ clarifying
|
||
→ ready
|
||
→ active
|
||
→ waiting | review | monitoring
|
||
→ done
|
||
```
|
||
|
||
Possible modifiers:
|
||
|
||
- blocked.
|
||
- waiting_on_user.
|
||
- waiting_on_dependency.
|
||
- approval_required.
|
||
- autonomous.
|
||
- at_risk.
|
||
- scheduled.
|
||
|
||
## 5.2 Run state
|
||
|
||
```text
|
||
queued
|
||
→ provisioning
|
||
→ preparing
|
||
→ running
|
||
→ waiting_for_input | verifying
|
||
→ succeeded | failed | cancelled
|
||
```
|
||
|
||
## 5.3 Workbox state
|
||
|
||
```text
|
||
creating
|
||
→ preparing
|
||
→ ready
|
||
→ busy
|
||
→ sleeping | waking
|
||
→ destroyed
|
||
```
|
||
|
||
The frontend should primarily expose work-unit state. Run state appears as operational detail. Workbox state is usually hidden except during debugging or delayed startup.
|
||
|
||
---
|
||
|
||
## 6. Concurrency model
|
||
|
||
Default rules:
|
||
|
||
- One writable checkout per active mutating run.
|
||
- One branch per independently shippable work unit.
|
||
- Serialize mutating runs against the same branch.
|
||
- Permit parallel read-only analysis against immutable snapshots.
|
||
- Permit parallel child work on separate branches.
|
||
- Treat merge and integration as explicit controlled actions.
|
||
|
||
Example:
|
||
|
||
```text
|
||
Work Unit A → branch work/a → Workbox A
|
||
Work Unit B → branch work/b → Workbox B
|
||
Work Unit C → branch work/c → Workbox C
|
||
```
|
||
|
||
A work unit may use multiple runs:
|
||
|
||
```text
|
||
research
|
||
→ implementation
|
||
→ automated review
|
||
→ verification
|
||
→ human review
|
||
```
|
||
|
||
Do not allow agents to share one writable working directory without deliberate coordination and conflict handling.
|
||
|
||
---
|
||
|
||
## 7. Persistence and recovery
|
||
|
||
The durable source of truth is outside transient agent processes.
|
||
|
||
Persist after every meaningful step:
|
||
|
||
- Work-unit state changes.
|
||
- Decisions.
|
||
- Approval requests.
|
||
- Agent summaries.
|
||
- Tool results required for audit.
|
||
- Repository commit or patch checkpoints.
|
||
- Artifact metadata.
|
||
- Verification results.
|
||
|
||
Do not rely on:
|
||
|
||
- A running shell process.
|
||
- In-memory harness state.
|
||
- Open sockets.
|
||
- An uncommitted working directory surviving indefinitely.
|
||
|
||
Before waiting for human input:
|
||
|
||
- Persist current findings.
|
||
- Save or commit relevant file changes.
|
||
- Upload important artifacts.
|
||
- Record the exact requested decision.
|
||
- Store resumable workflow state.
|
||
|
||
All workflow steps should be idempotent or safely repeatable.
|
||
|
||
---
|
||
|
||
## 8. Security model
|
||
|
||
## 8.1 Trust boundaries
|
||
|
||
Treat as untrusted:
|
||
|
||
- Imported repositories.
|
||
- Repository instructions.
|
||
- External documents.
|
||
- Customer messages.
|
||
- MCP tools.
|
||
- Tool responses.
|
||
- Generated code.
|
||
- Agent-authored summaries.
|
||
|
||
A model recommendation is not an authorization decision.
|
||
|
||
## 8.2 Layered authorization
|
||
|
||
A sensitive action requires all relevant layers to allow it:
|
||
|
||
```text
|
||
Product policy
|
||
AND
|
||
Harness permission
|
||
AND
|
||
Runtime capability
|
||
AND
|
||
Scoped credential
|
||
```
|
||
|
||
The action path is:
|
||
|
||
```text
|
||
Agent requests action
|
||
→ harness permission check
|
||
→ Work OS policy evaluation
|
||
→ human approval when required
|
||
→ runtime capability check
|
||
→ credential minting
|
||
→ action execution
|
||
→ provenance event
|
||
```
|
||
|
||
## 8.3 Workload identity
|
||
|
||
Every run should receive a short-lived identity containing:
|
||
|
||
- organization_id.
|
||
- project_id.
|
||
- work_unit_id.
|
||
- run_id.
|
||
- user or initiating principal.
|
||
- permitted capabilities.
|
||
- expiration.
|
||
|
||
The Workbox exchanges this identity for scoped access to:
|
||
|
||
- Git.
|
||
- Model gateway.
|
||
- Integration tools.
|
||
- Artifact storage.
|
||
- Preview gateway.
|
||
- Optional cloud environments.
|
||
|
||
Avoid injecting long-lived organization credentials into sandboxes.
|
||
|
||
## 8.4 Network policy
|
||
|
||
Network access should be deny-by-default or allowlisted by run type.
|
||
|
||
Examples:
|
||
|
||
- Package registry access during setup.
|
||
- Repository host access.
|
||
- Model gateway access.
|
||
- Approved external APIs.
|
||
- No unrestricted production network access by default.
|
||
|
||
## 8.5 Secrets
|
||
|
||
Secrets should be:
|
||
|
||
- Stored outside repositories and actor state.
|
||
- Scoped to organization and project.
|
||
- Minted or injected only when required.
|
||
- Short-lived where possible.
|
||
- Redacted from logs and transcripts.
|
||
- Rotatable without rebuilding projects.
|
||
- Audited when accessed.
|
||
|
||
## 8.6 Data isolation
|
||
|
||
Every storage query, event, artifact, context lookup, and runtime token must be tenant-scoped.
|
||
|
||
Cross-organization portfolio views may aggregate summaries but must never provide one organization’s raw context to another organization’s agent run.
|
||
|
||
## 8.7 Human approvals
|
||
|
||
Approval should be required for actions such as:
|
||
|
||
- Production deployment.
|
||
- Merging protected branches.
|
||
- Accessing sensitive production data.
|
||
- Sending external communications.
|
||
- Changing billing or financial state.
|
||
- Deleting data.
|
||
- Changing organization-level policy.
|
||
|
||
Approval should be action-specific and expire after use or time.
|
||
|
||
## 8.8 Auditability
|
||
|
||
The system must retain:
|
||
|
||
- Who initiated work.
|
||
- What context was provided.
|
||
- Which agent and model class performed the run.
|
||
- Which tools were called.
|
||
- What files changed.
|
||
- Which approvals were requested and granted.
|
||
- What artifacts were produced.
|
||
- What was published or merged.
|
||
- What outcome was observed.
|
||
|
||
---
|
||
|
||
## 9. Scaling model
|
||
|
||
Scale through many small, isolated actors and queued runs rather than long-lived per-user machines.
|
||
|
||
## 9.1 Tenant scheduler
|
||
|
||
Enforce:
|
||
|
||
- Maximum concurrent runs per organization.
|
||
- Maximum concurrent runs per project.
|
||
- Priority classes.
|
||
- Fair scheduling.
|
||
- Subscription limits.
|
||
- Model budget.
|
||
- Sandbox budget.
|
||
- Retry limits.
|
||
- Runtime duration limits.
|
||
|
||
## 9.2 Work queue
|
||
|
||
Use explicit states:
|
||
|
||
```text
|
||
accepted
|
||
→ queued
|
||
→ leased
|
||
→ running
|
||
→ completed
|
||
```
|
||
|
||
Leases should be idempotent and recoverable to prevent duplicate expensive execution.
|
||
|
||
## 9.3 Resource limits
|
||
|
||
Apply hard and soft limits for:
|
||
|
||
- Tokens per run.
|
||
- Cost per run.
|
||
- Runtime duration.
|
||
- Tool calls.
|
||
- File count and repository size.
|
||
- Network bytes.
|
||
- Process count.
|
||
- Memory and CPU.
|
||
- Artifact size.
|
||
- Subagent depth.
|
||
- Repeated failure count.
|
||
|
||
## 9.4 Artifact offloading
|
||
|
||
Do not store large logs or binaries in actor state or database rows. Store them in object storage and retain references in the work graph.
|
||
|
||
## 9.5 Snapshot strategy
|
||
|
||
Use sanitized reusable snapshots for project setup acceleration.
|
||
|
||
Snapshot layers may include:
|
||
|
||
- Base operating environment.
|
||
- Language and toolchain layer.
|
||
- Template layer.
|
||
- Project dependency layer.
|
||
|
||
Do not snapshot:
|
||
|
||
- Long-lived credentials.
|
||
- User-specific secrets.
|
||
- Active tokens.
|
||
- Unreviewed production data.
|
||
|
||
## 9.6 Multi-region considerations
|
||
|
||
Keep control-plane relational consistency explicit.
|
||
|
||
Potential strategy:
|
||
|
||
- Organization home region.
|
||
- Region-local execution actors.
|
||
- Region-local artifact and cache placement.
|
||
- Global routing to the organization’s control plane.
|
||
- Explicit restrictions for data residency.
|
||
|
||
Do not make multi-region execution an MVP requirement unless customer needs demand it.
|
||
|
||
---
|
||
|
||
## 10. Better-T-Stack monorepo mapping
|
||
|
||
Assuming an existing monorepo with `apps/web`, `apps/expo`, and shared packages, a possible structure is:
|
||
|
||
```text
|
||
apps/
|
||
├── web/
|
||
├── expo/
|
||
├── api/
|
||
├── worker/
|
||
├── agent-runtime/
|
||
└── preview-gateway/
|
||
|
||
packages/
|
||
├── db/
|
||
├── auth/
|
||
├── domain/
|
||
├── api-contract/
|
||
├── events/
|
||
├── realtime/
|
||
├── work-graph/
|
||
├── conversation/
|
||
├── flow-agent/
|
||
├── context/
|
||
├── policy/
|
||
├── scheduler/
|
||
├── integrations/
|
||
├── model-gateway/
|
||
├── git/
|
||
├── artifacts/
|
||
├── sandbox/
|
||
├── agentos/
|
||
├── opencode/
|
||
├── observability/
|
||
├── billing/
|
||
├── ui/
|
||
└── config/
|
||
```
|
||
|
||
Suggested boundaries:
|
||
|
||
### `packages/domain`
|
||
|
||
Pure domain types and state transitions.
|
||
|
||
### `packages/events`
|
||
|
||
Event envelopes, schemas, reducers, and provenance utilities.
|
||
|
||
### `packages/work-graph`
|
||
|
||
Queries and commands for work entities and materialized views.
|
||
|
||
### `packages/conversation`
|
||
|
||
Message persistence, scopes, extraction jobs, and source links.
|
||
|
||
### `packages/flow-agent`
|
||
|
||
Orchestration logic, planning, and run coordination.
|
||
|
||
### `packages/context`
|
||
|
||
Canonical context loading, retrieval, and run context-pack construction.
|
||
|
||
### `packages/policy`
|
||
|
||
Policy evaluation and approval workflows.
|
||
|
||
### `packages/scheduler`
|
||
|
||
Queues, leases, quotas, workflows, retries, and cancellation.
|
||
|
||
### `packages/agentos`
|
||
|
||
AgentOS client, actor naming, session lifecycle, and event translation.
|
||
|
||
### `packages/opencode`
|
||
|
||
Harness configuration, session prompts, tool policy, and result normalization.
|
||
|
||
### `packages/sandbox`
|
||
|
||
Sandbox provider adapters, workspace lifecycle, commands, logs, and previews.
|
||
|
||
### `packages/git`
|
||
|
||
Repository provisioning, branches, commits, pushes, pull requests, and mirrors.
|
||
|
||
### `packages/integrations`
|
||
|
||
Executor connection management and tool scopes.
|
||
|
||
### `packages/model-gateway`
|
||
|
||
Provider routing, budgets, credentials, and cost attribution.
|
||
|
||
---
|
||
|
||
## 11. API and command design
|
||
|
||
Prefer domain commands over generic entity mutation.
|
||
|
||
Examples:
|
||
|
||
```text
|
||
CreateProject
|
||
ImportRepository
|
||
CreateWorkUnit
|
||
AcceptCandidate
|
||
AttachSignal
|
||
MergeCandidates
|
||
StartWork
|
||
UpdateRequirements
|
||
ApprovePlan
|
||
ResolveBlocker
|
||
RequestChanges
|
||
PauseRun
|
||
CancelRun
|
||
ApproveAction
|
||
RejectAction
|
||
ApproveMerge
|
||
ApproveDeployment
|
||
ReopenWorkUnit
|
||
```
|
||
|
||
Each command should:
|
||
|
||
- Validate tenant scope.
|
||
- Validate current state.
|
||
- Be idempotent where practical.
|
||
- Emit one or more domain events.
|
||
- Avoid direct client control of infrastructure details.
|
||
|
||
---
|
||
|
||
## 12. Event translation from harness to product
|
||
|
||
Raw harness events should be preserved for audit but translated into human-meaningful product events.
|
||
|
||
Examples:
|
||
|
||
```text
|
||
Raw: tool_call bash "pnpm test"
|
||
Product: run.verification_started
|
||
|
||
Raw: tool_result exit_code=0
|
||
Product: run.test_suite_passed
|
||
|
||
Raw: permission_request git_push
|
||
Product: approval.requested
|
||
|
||
Raw: file_edit src/auth/callback.ts
|
||
Product: artifact.code_change_updated
|
||
```
|
||
|
||
The primary UI should not expose raw transcripts unless the user opens technical details.
|
||
|
||
---
|
||
|
||
## 13. Initial implementation sequence
|
||
|
||
## Phase 1: Durable product model
|
||
|
||
- Organizations.
|
||
- Projects.
|
||
- Work units.
|
||
- Candidates.
|
||
- Runs.
|
||
- Artifacts.
|
||
- Conversation scopes.
|
||
- Event log.
|
||
- Card projections.
|
||
|
||
## Phase 2: One complete coding loop
|
||
|
||
- One template project.
|
||
- Managed Git.
|
||
- One sandbox provider.
|
||
- One AgentOS actor per run.
|
||
- OpenCode harness.
|
||
- Model gateway.
|
||
- Branch creation.
|
||
- Tests.
|
||
- Artifact upload.
|
||
- Pull request output.
|
||
- Human approval.
|
||
|
||
## Phase 3: Context and memory
|
||
|
||
- Canonical Markdown files.
|
||
- Context-pack construction.
|
||
- Retrieval index.
|
||
- Decision memory.
|
||
- Source provenance.
|
||
|
||
## Phase 4: Autonomous discovery
|
||
|
||
- Continuous signal ingestion.
|
||
- Candidate extraction.
|
||
- Duplicate detection.
|
||
- Existing work matching.
|
||
- Attention queue.
|
||
|
||
## Phase 5: Additional integrations and workflows
|
||
|
||
- External Git.
|
||
- Support.
|
||
- Team communication.
|
||
- Issue trackers.
|
||
- Analytics.
|
||
- Deployment and monitoring.
|
||
|
||
---
|
||
|
||
## 14. MVP success criteria
|
||
|
||
The first release should reliably demonstrate:
|
||
|
||
```text
|
||
Prompt
|
||
→ candidate or work unit
|
||
→ clarified objective
|
||
→ isolated coding run
|
||
→ tested change
|
||
→ preview or evidence
|
||
→ pull request
|
||
→ human review
|
||
→ durable completed work card
|
||
```
|
||
|
||
The work unit must remain understandable and resumable even if the underlying harness session or Workbox is destroyed.
|
||
|
||
---
|
||
|
||
## 15. Technical non-goals for the first release
|
||
|
||
- Supporting every harness.
|
||
- Supporting every sandbox provider.
|
||
- Arbitrary multi-agent swarms.
|
||
- Full replacement of external Git providers.
|
||
- Multi-region active-active control plane.
|
||
- Unlimited imported repository compatibility.
|
||
- Automatic production deployment without approval.
|
||
- A generic low-code workflow builder.
|
||
- Exposing model selection and agent internals to users.
|
||
|
||
---
|
||
|
||
## 16. Architectural principles
|
||
|
||
1. **Durable work state must outlive execution environments.**
|
||
2. **Every execution path is tenant-scoped.**
|
||
3. **Use one writable checkout per mutating unit of work.**
|
||
4. **Persist events before projecting summaries.**
|
||
5. **Treat agent outputs as claims with provenance, not unquestioned truth.**
|
||
6. **Separate product policy, harness permission, and runtime capability.**
|
||
7. **Use short-lived credentials and explicit workload identity.**
|
||
8. **Keep harnesses, models, sandboxes, and Git providers replaceable.**
|
||
9. **Hide infrastructure state from the product surface unless actionable.**
|
||
10. **Measure successful outcomes and human attention, not merely agent activity.**
|