# 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.**