docs: align Cowork with ephemeral E2B sessions

Author: Gini

README.md

@@ -27,15 +27,20 @@ flowchart LR
 
   Control --> Store[("Control PostgreSQL")]
   Control --> Controller["Workspace controller"]
-  Controller --> Sandbox["Kasm sandbox"]
+  Controller --> Computer["Kasm Computer sandbox"]
+  Control --> Cowork["Cowork session adapter"]
+  Cowork --> E2B["E2B Firecracker task VM"]
   Control --> Consent["OpenVTC consent service"]
   Control --> Gateway["LiteLLM gateway"]
   Control --> Broker["Channel broker"]
   Scheduler["Scheduler worker"] --> Control
 
-  Sandbox --> Gateway
-  Sandbox --> Control
-  Sandbox --> Egress["Per-workspace egress proxy"]
+  Computer --> Gateway
+  Computer --> Control
+  Computer --> Egress["Per-workspace egress proxy"]
+  E2B --> Gateway
+  E2B --> Control
+  E2B --> Egress
   Gateway --> Models["Model providers"]
   Gateway --> M365["Microsoft 365 MCP"]
   M365 --> Graph["Microsoft Graph"]
@@ -71,7 +76,8 @@ network isolation, policy integrity, and the approval protocol.
 | `workspace-ingress` | Serves the product origin and exchanges short-lived workspace launch links for scoped sessions | `127.0.0.1:4174` |
 | `web` | Static React application and authenticated reverse proxy to Control | Private |
 | `control-api` | Identity, policy, lifecycle orchestration, grants, governance, audit, and connection APIs | Private |
-| `workspace-controller` | Provisions Kasm workspaces through local Docker or the Kasm Developer API | Private |
+| `workspace-controller` | Provisions durable Computer/Kasm workspaces; managed providers are selected by policy | Private |
+| Cowork execution adapter | Creates disposable E2B task sessions for real ACP harnesses and application-scoped VCR | Private |
 | `litellm` | Model routing, per-user OAuth custody, scoped virtual keys, and MCP dispatch | `127.0.0.1:4000` |
 | `ms365-mcp` | Pinned Microsoft 365 MCP connector for Mail, Calendar, OneDrive, and Teams | OAuth bridge on `127.0.0.1:4311` |
 | `openvtc-consent` | OpenVTC executor identity, request signing, and proof verification | Private |

docs/COWORK_E2B_ACP_PLAN.md

@@ -0,0 +1,200 @@
+# Cowork on E2B: canonical architecture and delivery plan
+
+**Status:** implementation contract (2026-08-01)  
+**Branch:** `codex/onevibe-computer`  
+**Owner:** ONEComputer Control + Cowork runtime
+
+This is the single source of truth for the lightweight Cowork runtime. It
+supersedes any earlier plan that describes Cowork as a Kasm workspace or that
+requires KasmVNC parity inside an ephemeral chat sandbox.
+
+## Product boundary
+
+ONEComputer has two deliberately different experiences:
+
+| Experience | User mental model | Runtime | State lifetime | Visual surface |
+| --- | --- | --- | --- | --- |
+| **Computer** | “I am using my governed computer.” | Kasm/KasmVNC (or a later durable provider) | Persistent workspace and home volume | Full desktop, human takeover, clipboard, office apps |
+| **Cowork / ONEVibe** | “An agent is doing this task for me.” | E2B Firecracker microVM per conversation/task | Disposable task session; fixed TTL; destroy by default | Application-scoped evidence (browser/document PNGs), not a desktop login |
+
+Cowork is not a lightweight alias for Computer. It does not create, open, or
+list a Kasm workspace; it does not mount a durable home volume; and it does not
+expose port 6901. If a user needs a persistent desktop, human takeover,
+clipboard, or long-running office state, Control must route them to Computer.
+
+The current `/v1/onevibe/tasks` implementation still uses an internal
+workspace-shaped handle for compatibility with existing task/event tables. That
+handle is transitional and is never a durable workspace or a user-selectable
+Computer resource. New APIs and code must use a first-class Cowork session
+identifier and must not add dependencies on the workspace lifecycle.
+
+## Canonical Cowork session model
+
+The target Control model is an owned `cowork_session` with:
+
+- `sessionId`, tenant, subject, task, agent, policy hash, provider profile;
+- an immutable image/template digest and provider sandbox id;
+- a short creation-anchored deadline, turn budget, byte budget, and state;
+- durable redacted activity, ACP transcript references, VCR frame references,
+  artifact ownership, and cleanup evidence;
+- no durable user home, no provider credential, and no hidden reasoning.
+
+The session is the authorization and retention boundary. The E2B sandbox is an
+implementation detail behind an `EphemeralExecutionAdapter`; it is never
+returned as a launch URL or treated as a workspace by the UI.
+
+### Target endpoints
+
+The compatibility endpoints remain read-only/deprecation paths while the
+following session-scoped endpoints are introduced:
+
+```text
+POST /v1/cowork/sessions
+GET  /v1/cowork/sessions/:sessionId
+POST /v1/cowork/sessions/:sessionId/turns
+GET  /v1/cowork/sessions/:sessionId/events?after=N
+GET  /v1/cowork/sessions/:sessionId/events/stream?after=N
+POST /v1/cowork/sessions/:sessionId/frames
+GET  /v1/cowork/sessions/:sessionId/vcr
+GET  /v1/cowork/sessions/:sessionId/artifacts/:artifactId
+DELETE /v1/cowork/sessions/:sessionId
+```
+
+Every route checks tenant, subject, session, task, policy, and expiry. Expired
+sessions are immutable for audit reads and reject all new turns, captures,
+approvals, and artifact mutations.
+
+## E2B Cowork runtime profile
+
+The first managed profile is `cowork-e2b-ephemeral-v1`:
+
+- pinned `linux/amd64` E2B template built from a minimal single-stage image;
+- Node 22, the official ACP SDK, pinned `codex-acp`, pinned OpenCode, and the
+  `/usr/local/libexec/onecomputer-acp-chat.mjs` bridge;
+- Playwright and a pinned Chromium/Firefox runtime for browser tasks;
+- optional document tooling only when the image explicitly declares it;
+- a task-confined filesystem under `/workspace/task`, with no host mounts;
+- provider-native network allowlist plus the signed external egress proxy;
+- no Kasm daemon, VNC server, desktop login, nested KVM, or durable volume.
+
+The image is promoted by digest, carries SBOM/provenance, and never contains
+model-provider keys, enterprise OAuth tokens, E2B credentials, or registry
+passwords. E2B template build credentials are short-lived and supplied only to
+the build command.
+
+### Application-scoped VCR
+
+Cowork VCR means “what the agent did in the application,” not “a streamed
+desktop.” The capture contract is explicit:
+
+- browser: Playwright captures the actual page/context inside E2B;
+- document: a document-aware capture helper is used only if the profile has
+  that application installed;
+- desktop: unsupported by the Cowork profile and fails closed with a typed
+  capability error; Computer is the correct route.
+
+Each PNG is size-bounded, signature-checked, hash-linked to an activity
+sequence, and stored through Control. A screenshot produced by the browser UI,
+a fixture, or a host process is not evidence.
+
+## ACP and model boundary
+
+Codex and OpenCode run inside E2B as real ACP stdio servers. Control starts the
+allow-listed binary, negotiates the ACP protocol version/capabilities, and
+maps updates to the canonical event stream. Model traffic goes only through
+the governed LiteLLM route using a short-lived broker grant. The E2B guest never
+receives an OpenAI, Anthropic, Kimi, or LiteLLM administrator key.
+
+ACP is not the sandbox, approval, VCR, or model protocol. ACP permission
+requests are converted to an exact Control operation and otherwise cancelled;
+the UI cannot approve an action by itself. Product-facing SSE is Control’s
+ordered replay stream, not a direct unauthenticated ACP socket.
+
+## Lifecycle and failure semantics
+
+1. Authenticate and resolve the signed effective policy.
+2. Create an idempotent Cowork session and reserve its budget.
+3. Create the E2B microVM from the pinned profile and inject scoped grants.
+4. Start Codex or OpenCode ACP in the confined task directory.
+5. Stream redacted canonical events; capture application frames at governed
+   action boundaries; persist artifacts before returning them to the UI.
+6. Pause only as an E2B cost optimization if the session deadline remains
+   authoritative; never extend the deadline because a sandbox resumed.
+7. Destroy the sandbox, revoke grants, and purge task state at completion,
+   cancellation, expiry, budget exhaustion, policy revocation, or provider
+   failure. Preserve only the minimum redacted audit evidence.
+
+Provider, process, SSE, browser, and storage disconnects produce explicit
+failed/expired states. There is no synthetic assistant response, fake VCR
+frame, or “ready” state when a real ACP/model call did not happen.
+
+## Migration sequence
+
+### Phase 0 — contract and documentation (current)
+
+- Adopt this document as the canonical plan.
+- Keep Kasm Computer behavior unchanged.
+- Add `cowork-e2b-ephemeral-v1` capability metadata and an adapter seam that
+  cannot call `open()` or `purgeWorkspace()`.
+- Mark the workspace-shaped task handle as compatibility-only.
+
+**Exit:** architecture tests prove Cowork cannot be exposed through the durable
+workspace list or a Kasm launch route.
+
+### Phase 1 — local image and ACP qualification
+
+- Build the minimal Cowork image locally or on a large-disk builder.
+- Run real Codex and OpenCode ACP against the local LiteLLM route where the
+  binaries are available; assert initialize, streaming, cancellation,
+  permission cancellation, malformed input, and path confinement.
+- Run Playwright in the image and retrieve a real PNG before any UI test.
+
+**Exit:** API qualification is green with no fixture response involved.
+
+### Phase 2 — E2B template and API-first live gate
+
+- Publish the image by digest and create a named E2B template.
+- Configure provider-reachable Control, LiteLLM, and egress HTTPS routes.
+- Prove create/resume/turn/stream/capture/artifact/cleanup with real E2B
+  resources, including owner isolation, budget limits, and zero secret leakage.
+- Record sandbox/template ids, image digest, event hashes, PNG hashes, and
+  final kill/purge evidence without recording credentials.
+
+**Exit:** the real API gate passes for Codex and OpenCode before browser work.
+
+### Phase 3 — browser UX and Manus-like VCR
+
+- Exercise the Cowork page against the same live API session.
+- Render left-side streaming activity and right-side application VCR with
+  previous/next, scrub, jump-to-live, reconnect, and truthful degraded states.
+- Generate and download a real PPTX from a Cowork session; validate the Office
+  package and its evidence links.
+
+**Exit:** browser E2E is a projection of a previously qualified API run.
+
+### Phase 4 — Computer handoff and optional providers
+
+- Add an explicit “open in Computer” handoff that creates/uses a durable Kasm
+  workspace only when the user asks for desktop state or takeover.
+- Qualify Modal/gVisor or another provider against the same ephemeral contract;
+  do not claim Kasm desktop parity for a provider that lacks it.
+
+## Non-negotiable QA gates
+
+- `npm test`, strict TypeScript build, and Playwright regression suite;
+- API E2E: real ACP initialize, ordered stream, terminal event, cancellation,
+  budget/backpressure, owner isolation, PNG signature/hash, PPTX validation,
+  and provider cleanup;
+- negative tests: no workspace listing, no Kasm open route, no desktop capture,
+  expired-session mutation, invalid policy/grant, route rejection, secret
+  leakage, and fabricated/fixture response rejection;
+- browser E2E only after API evidence exists; browser failures cannot be hidden
+  by fixtures or simulated state.
+
+## Done means
+
+ONEComputer reaches Manus-like Cowork parity when a user can submit a task,
+watch a real Codex/OpenCode ACP stream, see truthful browser/document evidence,
+scrub and replay it, receive a real artifact, resume within the fixed session
+deadline, and observe deterministic cleanup—without ever creating or depending
+on a full Kasm workspace.

docs/E2B-MODAL-SANDBOX-IMPLEMENTATION.md

@@ -1,21 +1,25 @@
 # E2B and Modal sandbox implementation
 
-Status: implemented behind the workspace-controller provider contract; automated
-conformance is green. Live cloud qualification is pending provider credentials,
-a published workspace image/template, and a public governed egress endpoint.
+Status: implemented behind the workspace-controller provider contract for the
+durable-provider compatibility path; automated conformance is green. Live cloud
+qualification is pending provider credentials, a published image/template, and
+a public governed egress endpoint. The lightweight Cowork contract is defined
+separately in [COWORK_E2B_ACP_PLAN.md](COWORK_E2B_ACP_PLAN.md).
 
 ## Decision
 
 ONEComputer now supports four controller drivers:
 
 - `kasm-local`: durable local Docker/KasmVNC workspaces.
 - `kasm`: Kasm Developer API sessions.
-- `e2b`: Firecracker microVM sandboxes through the official E2B TypeScript SDK.
+- `e2b`: Firecracker microVM sandboxes through the official E2B TypeScript SDK
+  for the existing durable-provider compatibility path.
 - `modal`: gVisor sandboxes through the official Modal JavaScript SDK.
 
-E2B and Modal run the same reviewed ONEComputer workspace image and KasmVNC
-desktop surface. This preserves the browser/Word/LibreOffice viewing model used
-by VCR instead of substituting a terminal-only sandbox.
+The existing E2B/Modal adapter tests cover the reviewed workspace contract. They
+do **not** define Cowork: Cowork uses a separate minimal image/profile with no
+KasmVNC, no desktop launch, and application-scoped browser/document capture.
+Kasm remains the full Computer visual surface.
 
 ## Contract parity
 
@@ -30,15 +34,16 @@ by VCR instead of substituting a terminal-only sandbox.
 | Restricted/full-web policy proxy | Local sidecar | External TLS proxy | External TLS proxy |
 | Live egress grant rotation | Yes | Yes | Yes |
 | Native provider egress backstop | Docker networks | E2B `allowOut` | Modal domain allowlist |
-| KasmVNC desktop/VCR | Private relay | Authenticated KasmVNC | Modal connect token |
+| Full desktop/VCR | Private relay | Computer-only compatibility path | Computer-only compatibility path |
 | Clipboard policy | Yes | Yes | Yes |
 | Idle suspension | Container stop | Firecracker pause/auto-resume | Timeout/recreate |
 | Nested KVM/Cowork | Optional local KVM | No | No |
 
 Nested KVM is an explicit routing constraint, not a silently degraded feature.
-Cowork workspaces remain on a Kasm-capable node. E2B and Modal are parity
-targets for browser, office, CLI-agent, chat-runtime, persistence, policy,
-egress, and VCR flows.
+Cowork sessions do not remain on a Kasm-capable node. They use the
+`cowork-e2b-ephemeral-v1` profile and are parity targets for ACP, browser
+evidence, policy, egress, artifacts, budgets, and cleanup—not desktop login,
+clipboard, or durable office state.
 
 ## Security behavior
 

docs/ONEVIBE_E2B_ACP_FINAL_PLAN.md

@@ -1,5 +1,12 @@
 # ONEVibe-MonoRepo: E2B + ACP final execution plan
 
+> **Canonical update (2026-08-01):** [COWORK_E2B_ACP_PLAN.md](./COWORK_E2B_ACP_PLAN.md)
+> is now the source of truth for the lightweight Cowork architecture. This
+> document retains the broader provider and ACP sequencing; any reference below
+> to a Cowork “workspace”, KasmVNC parity, or a persistent E2B volume applies
+> only to the durable Computer compatibility path and is not a Cowork
+> requirement.
+
 > Current execution addendum: see [ONEVIBE_EPHEMERAL_COWORK_ACP.md](./ONEVIBE_EPHEMERAL_COWORK_ACP.md) for the task-scoped sandbox philosophy and API-first ACP/VCR qualification order.
 
 **Status:** approved architecture plan  
@@ -9,7 +16,7 @@
 ## Executive decision
 
 Use E2B Firecracker microVMs as the first managed execution provider for
-conversation-scoped Cowork tasks. Run an allow-listed agent harness inside the
+conversation-scoped Cowork sessions. Run an allow-listed agent harness inside the
 microVM through the Agent Client Protocol (ACP), and normalize all output into
 ONEComputer's canonical governed event stream.
 
@@ -25,7 +32,7 @@ User / Cowork UI
 ONEComputer Control + durable coordinator
        │ signed policy, budget, broker grant
        ├── execution provider: E2B (conversation microVM)
-       │       └── workspace image + OpenCode/Claude/Codex ACP harness
+       │       └── minimal Cowork image + OpenCode/Codex ACP harness
        ├── execution provider: Kasm (persistent visual workspace)
        └── execution provider: Modal (later gVisor burst tier)
                │
@@ -61,7 +68,7 @@ merge old `App.jsx`, migrations, or provider routes.
 The R&D evidence has three caveats:
 
 1. E2B/Modal adapters are automated-conformance green but live qualification
-   still requires provider credentials, an immutable workspace image/template,
+   still requires provider credentials, an immutable image/template,
    public governed egress, and provider quotas.
 2. Codex ACP has a qualification lane through LiteLLM. Claude ACP is packaged,
    but intentionally remains disabled until broker-provided governed authority
@@ -82,9 +89,9 @@ Add an explicit execution scope to the task model:
 - `turn`: disposable environment for one request;
 - `conversation`: one E2B microVM per chat session, paused between turns;
 - `task`: environment retained across related Cowork interactions;
-- `workspace`: current Kasm-style durable desktop.
+- `workspace`: current Kasm-style durable Computer desktop.
 
-Default Manus-like web chat to `conversation` + E2B. Route to Kasm when the
+Default Manus-like web chat to `conversation` + E2B. Route to Kasm Computer when the
 user needs a long-lived desktop, durable GUI state, nested virtualization, or
 human takeover that E2B has not yet qualified. The model/agent cannot choose a
 weaker boundary or extend retention.
@@ -125,13 +132,14 @@ forks where policy permits, and usage-based spend controls.
 
 Required qualifications:
 
-- immutable `linux/amd64` workspace image and E2B template;
+- immutable `linux/amd64` minimal Cowork image and E2B template;
 - E2B API key held only by the controller secret boundary;
 - external TLS egress proxy reachable from the provider;
 - default-deny provider network and exact route allowlist;
 - scoped model/control grants injected through the broker;
 - ACP process, filesystem, and terminal confinement;
-- browser/office capability only after KasmVNC/WebSocket/clipboard qualification;
+- application-scoped browser/document capture; desktop/KasmVNC/clipboard remain
+  Computer-only capabilities;
 - frame capture sidecar with no raw prompts, cookies, secrets, or hidden
   reasoning in replay evidence;
 - create/resume/pause/kill reconciliation and explicit volume purge.
@@ -255,9 +263,10 @@ turn, cancellation, resume, owner isolation, spend limit, and destruction.
 **Exit:** harness choice changes runtime implementation only; event, policy,
 approval, VCR, artifact, and budget contracts remain identical.
 
-### Phase 3 — visual E2B/VCR qualification
+### Phase 3 — application-scoped E2B/VCR qualification
 
-- Prove KasmVNC or equivalent read-only computer view inside the E2B image.
+- Prove Playwright/application capture inside the minimal Cowork E2B image;
+  KasmVNC and desktop takeover remain Computer-only.
 - Add capture sidecar at semantic action boundaries and bounded active cadence.
 - Implement live-follow, previous/next, pause/play, scrub, event markers,
   frame availability, jump-to-live, and capture-degraded states.