@arnilo/prism 0.6.0 → 0.7.0

package/docs/history/0.7.0-primitive-review.md

@@ -0,0 +1,254 @@
+# Release 0.7.0 — Primitive, Compatibility, and Integration-Boundary Review
+
+Plan: [073-Release-0-7-0-Host-Completeness.md](../../plans/073-Release-0-7-0-Host-Completeness.md) Task 1  
+Baseline: Released `0.6.0`  
+Target: Release `0.7.0` (Host Completeness, Evidence, and Capability Boundaries)  
+Date: 2026-09-13  
+
+---
+
+## 1. Executive Summary & Review Scope
+
+This review freezes the architectural primitives, compatibility contracts, performance budgets, and security boundaries for Release **0.7.0**.
+
+The release addresses the **three integration traps** identified in 0.6.0 (Traps A, B, C) and delivers the **fourteen P0–P2 host completeness recommendations** (R01–R06, R08–R14), integrating:
+- **R07 / R15** from [Plan 072 — Host Eval and Observability Cockpit](../../plans/072-Host-Eval-And-Observability-Cockpit.md) (frozen in [`docs/_evidence/phase72-primitive-review.md`](../_evidence/phase72-primitive-review.md)),
+- **R16** from [Plan 077 — Work-Scope Memory Index](../../plans/077-Work-Scope-Memory-Index.md) (`WorkScope` / `projectWorkMemory`),
+- **R17** from [Plan 074 — Attention Compiler](../../plans/074-Attention-Compiler.md) (`assembleTurn`, cache-stable attention ratio gate, sticky stubs).
+
+### Universal Invariants Upheld
+
+1. **Fail closed at trust boundaries**: Identity validation, tenant scoping, document authorization, and sandbox isolation fail closed. Never weaken fail-closed assertions.
+2. **No new dependencies without explicit plan authorization**: Root remains zero runtime dependencies. Optional SDKs live strictly as optional peer dependencies within owning integration packages, never loaded at import or module evaluation time.
+3. **No second agent loops or duplicated control planes**: Reuse existing core primitives (`Agent`, `AIProvider`, `ModelRouter`, `CheckpointStore`, `LeaseStore`, `ToolEffectStore`, `RunLedger`, `ProcessSessions`, `DeviceAdapter`).
+4. **Byte hard caps preserved**: All process-safety limits (`maxRequestBytes`, `maxResponseBytes`, `maxEventBytes`, `maxResultBytes`) remain immutable ceilings.
+5. **Truth in capability and state**: No simulated or mock-only claims for production infrastructure. Unobserved or ambiguous external mutations remain explicitly `unknown`, never fabricated as succeeded or zero-cost.
+
+---
+
+## 2. Coverage Ledger & Primitive Mapping
+
+Every review row is mapped below to its reusable baseline primitives, implementation owner, generic capability gap, dependencies, and required release evidence.
+
+| ID | Title | Reusable Baseline Primitives | Implementation Owner | Generic Capability Gap | Dependencies | Release Evidence |
+|---|---|---|---|---|---|---|
+| **Trap A** | Parsed ACP MCP destination allow-list | `packages/acp-agent/src/index.ts`, `selectMcpServers` | `packages/acp-agent/src/` | URL-parsed origin and strict path-segment subtree matching | None (Node `URL`) | Origin lookalike rejection, traversal/separator refusal, port/scheme validation |
+| **Trap B** | Router sync facade fail-loud governance | `createModelRouter`, `providerSource` | `packages/prism-core/src/governance/model-router/` | Fast synchronous check throwing `ERR_PRISM_MODEL_ROUTER_ASYNC_REQUIRED` when budget/circuit/rateLimit configured | None | Sync bypass rejection on budget/circuit, async `resolve` passes |
+| **Trap C** | ACP real model/provider configuration | `PrismAcpAgentConfig`, `createSpawnableAgent` | `packages/acp-agent/src/` | Validated `model` + `credentialRef` config parsing, explicit mock opt-in | `@arnilo/prism-providers` | Direct provider invocation via ACP, unknown provider refusal, credential canary check |
+| **R01** | Governed provider invocation & aggregate accounting | `ModelRouter.resolve`, `recordUsage`, `AIProvider` | `packages/prism-core/src/governance/model-router/` | `GovernedAIProvider` adapter wrapping select, reserve, request policy, invoke, settle | None | Zero-budget denial, stream settlement, duplicate settlement idempotency |
+| **R01** | Aggregate task/tenant accounting | `PostgresModelRouterStateStore`, `stateKey` | `packages/prism-core/src/enterprise/postgres/model-router/` | Cross-call aggregate task/tenant dimensions; reservation renewal & fencing | PostgreSQL driver | Concurrent 32-attempt allocation under cap, non-session tool/embedding charging |
+| **R02** | Durable business-action drafts & review | `WorkIdempotencyStore`, `ArtifactBodyStore` | `packages/prism-core/src/integrations/work/` | Revision-bound draft state machine, payload digest verification, expiry | Persistence backends | Draft edit invalidates prior approval, resume executes exact revision, unknown outcome logged |
+| **R02** | Editable durable approvals (AG-UI/server) | `RunDecision`, `approveWithEdits`, AG-UI handler | `packages/ag-ui/src/`, `packages/prism-core/src/runtime/server/` | `approveWithEdits` protocol capability, CAS expectedVersion validation | `@arnilo/prism-ag-ui` | Edited approval round-trip, invalid schema denial, quorum invalidation |
+| **R03** | Docker process sessions & workspace coherence | `DockerSandboxSession`, `createProcessSessions` | `packages/prism-coding-tools/src/security/`, `agent/process/` | `startProcess` on `DockerSandboxSession`, attested container reattach | Docker CLI | Watcher I/O, kill/signal, registry restart recovery without duplicate spawn |
+| **R03** | Hosted sandbox (E2B) | `DisposableSandbox`, `ProcessSandboxBackend` | `packages/prism-coding-tools/src/security/e2b-sandbox.ts` | E2B adapter implementing `DisposableSandbox` + `startProcess` + snapshot resume | `@e2b/code-interpreter` (optional peer) | E2B execution, pause/resume, snapshot integrity, cleanup on abort |
+| **R04** | Document authorization in RAG | `retrieveContext`, `VectorStore`, `lexicalQuery` | `packages/memory/src/rag/`, `packages/memory/src/postgres.ts` | Principal/group ACL constraint injected into vector/lexical query legs | None / pgvector | Pre-ranking candidate exclusion, post-topK non-starvation, ACL update revocation |
+| **R04** | Incremental enterprise-source sync (Drive) | `RagStore`, `Chunker`, `VectorMemory` | `packages/memory/src/rag/sync.ts`, `connectors/google-drive.ts` | Change-token pagination (`newStartPageToken`), tombstone deletion, ACL sync | Google Drive API / `@googleapis/drive` | Incremental change ingestion, tombstone deletion, stale-token recovery |
+| **R05** | Validated host compositions | `createSecureAgent`, `createAgent` | `templates/personal-assistant/`, `templates/business-worker/` | Validated production wiring templates & static composition inspection | Internal packages | Packed npm install smoke, unredacted secret check, memory-persistence refusal |
+| **R06** | Fair background admission & drain | `createWorkflowCoordinator`, `PrismDrainController` | `packages/prism-core/src/runtime/server/drain.ts`, `workflows/coordinator.ts` | Multi-tenant fair queuing, graceful drain deadline, active run tracking | None | 503 on drain admit, queue fairness across tenants, clean in-flight completion |
+| **R07** | Behavioral & trajectory evaluation | `EvaluationTrace`, `runExperiment` (Plan 072) | `packages/prism-coding-tools/src/dev/` (inspector wiring) | Wiring 072 trajectory & scenario eval into inspector UI and release gates | Plan 072 artifacts | Scenario gate pass, trajectory deviation scoring, inspector run visualization |
+| **R15** | Execution timeline & workflow graph | `ExecutionTimeline`, `serializeWorkflowGraph` (Plan 072) | Plan 072 implementation | Consumed by 0.7.0 release journeys and Dev Inspector | Plan 072 artifacts | Timeline step rendering, node overlay, trace aggregation |
+| **R16** | Work-scope session memory index | `WorkScope`, `projectWorkMemory` (Plan 077) | Plan 077 implementation | Parallel session memory index; task isolation until explicit promote | Plan 077 artifacts | Task isolation test, promotion round-trip, scope boundary enforcement |
+| **R17** | Attention compiler & compaction trigger | `assembleTurn`, ratio gate (Plan 074) | Plan 074 implementation | Cache-stable prompt assembly, sticky stub compaction | Plan 074 artifacts | Ratio gate no-op under ceiling, sticky stubs above ceiling |
+| **R08** | Cross-layer memory correction & provenance | `ObservationalMemory`, `VectorMemory` | `packages/memory/src/memory.ts`, `compaction/observational-memory/` | Point correction, tombstoning, cross-layer provenance lineage, sharing grant | None / Postgres | Correct memory update, tombstone tombstoning in search, lineage query |
+| **R09** | External coding runtime delegation | `Supervisor`, `SubagentTool` | `packages/prism-coding-tools/src/agent/delegated/` | Typed adapters for Codex, Claude, Copilot, Gemini CLI, Cursor | Optional vendor SDKs | Approval interception, tool call containment, session resume |
+| **R10** | Semantic artifact diffs & evidence citations | `ArtifactBodyStore`, `patchDocument` | `packages/office/src/documents/diff.ts`, `packages/web-tools/src/evidence.ts` | Structural document diffs, evidence citation attestation and OCR grounding | None | Semantic diff visualization, citation verification, tampering rejection |
+| **R10** | Scanned document layout & OCR (Mistral) | `DocumentReader`, `parseDocument` | `packages/prism-coding-tools/src/document-reader/mistral-ocr.ts` | External layout analysis and OCR extraction adapter | Mistral AI API | PDF table extraction, layout preservation, fallback handling |
+| **R11** | Per-run tool narrowing & capability invalidation | `createToolRegistry`, `RunOptions` | `src/contracts-protocol.ts`, `src/tools.ts`, `packages/mcp/` | `RunOptions.toolAllowList`, dynamic tool filtering, remote capability cache refresh | None | Hidden tool schema, rejection of unauthorized tool call, MCP change invalidation |
+| **R12** | Native Bedrock Converse & ConverseStream | `bedrockProvider` (0.6.0 wraps `/openai/v1`) | `packages/prism-providers/src/bedrock/` | Native AWS Bedrock Converse & ConverseStream protocol adapter with SigV4 | `@aws-sdk/client-bedrock-runtime` | Native Converse tool round, ConverseStream event decode, token counting |
+| **R13** | Native Vertex Gemini with workload identity | `vertexProvider` (0.6.0 wraps OpenAI-compat) | `packages/prism-providers/src/vertex/` | Native Google Vertex Gemini `generateContent` & `streamGenerateContent` | `@google-cloud/vertexai` | Native content parts, tool round, Google ADC credential rotation |
+| **R13** | Thin Python & .NET remote clients | `PrismServer` HTTP / SSE routes | `clients/python/`, `clients/dotnet/` | Remote typed clients for run execution, SSE stream consumption, and approval | Python stdlib, .NET HttpClient | Stream framing, reconnection with Last-Event-ID, edited approval payload |
+| **R13** | Authenticated Slack & Teams recipes | `PrismServer` webhooks & decision routes | `examples/channels/slack/`, `examples/channels/teams/` | Webhook verification (Slack HMAC, Teams JWT), interactive review cards | Optional Bot SDKs | Forged signature denial, interactive card approval, draft re-review |
+| **R14** | Governed realtime voice orchestration | `RealtimeSession`, `DeviceAdapter` | `packages/prism-core/src/runtime/realtime/`, `packages/prism-providers/src/openai/realtime.ts` | Realtime tool calling bridge, microphone admission, barge-in cancellation | None (WebSocket) | Mic admission check, interruption cancellation, audio privacy retention |
+| **Release** | Integrated journeys, truth & publish | Release tooling, packaging, gates | `scripts/`, `docs/`, `packages/*/` | Lockstep 0.7.0 cut, generated package truth, live matrix evidence | Node 22/24 | Clean build, packaging gate pass, live matrix green, dry-run publish |
+
+---
+
+## 3. Reference Integration Matrix & Version-Selection Rules
+
+Prism adheres strictly to a zero-eager-dependency policy: optional third-party integrations must never bloat package install size or trigger unreviewed imports.
+
+| Domain | Selected Reference Implementation | Vendor / Package Identifier | Pinning & Version Selection Rule | Operational Role & Boundary |
+|---|---|---|---|---|
+| **Hosted Sandbox** | E2B | `@e2b/code-interpreter` | Pinned to `^1.0.0` as optional peer in `@arnilo/prism-coding-tools`. Evaluated only when host passes `createE2bSandbox`. | Untrusted ephemeral execution environment with filesystem snapshotting. Network strictly egress-controlled. |
+| **Enterprise Source** | Google Drive | `@googleapis/drive` (or native fetch REST v3) | Google Drive API v3. Optional peer or direct REST fetch in `@arnilo/prism-memory`. | Document knowledge source. Sync uses `changes.list` with `startPageToken` and ACL sync. |
+| **Layout / OCR** | Mistral OCR | `@mistralai/mistralai` (or native fetch) | Mistral Document AI API (`mistral-ocr-latest`). Optional peer in `@arnilo/prism-coding-tools`. | Scanned PDF / complex image layout parser. Output ingested as structured Markdown blocks. |
+| **Delegation: OpenAI** | OpenAI Codex | `@openai/codex` (or direct app-server) | Official OpenAI Codex thread SDK. Pinned peer in `@arnilo/prism-coding-tools`. | Cloud coding agent delegation via `startThread` / `resumeThread`. Tool execution approvals intercepted. |
+| **Delegation: Anthropic** | Claude Code / Agent SDK | `@anthropic-ai/claude-code` | Stable Agent SDK V1 (`query`, `canUseTool`, `options.resume`). No unstable V2. | Local/cloud coding agent delegation with explicit tool permission callbacks. |
+| **Delegation: GitHub** | GitHub Copilot | `@github/copilot-sdk` | Official Copilot Workspace/CLI SDK. Optional peer in `@arnilo/prism-coding-tools`. | Repo-scoped coding delegation. Enforces GitHub enterprise auth & token boundary. |
+| **Delegation: Google** | Google Gemini CLI | `@google-gemini/gemini-cli` | Official Gemini CLI SDK. Pinned peer in `@arnilo/prism-coding-tools`. | Local workspace CLI agent delegation. |
+| **Delegation: Cursor** | Cursor SDK | `@cursor/sdk` (or local CLI engine) | Cursor TypeScript SDK / local engine. Pinned peer in `@arnilo/prism-coding-tools`. | Editor-bound workspace task delegation. |
+| **Cloud Provider: AWS** | AWS Bedrock | `@aws-sdk/client-bedrock-runtime` | Pinned `^3.700.0` optional peer in `@arnilo/prism-providers`. | Native Converse & ConverseStream endpoints. Uses SigV4 request signing and AWS event streams. |
+| **Cloud Provider: GCP** | Google Vertex AI | `@google-cloud/vertexai` | Pinned `^1.9.0` optional peer in `@arnilo/prism-providers` (or direct REST). | Native Gemini `generateContent` & `streamGenerateContent` with Google ADC credentials. |
+| **Remote Client: Python** | `prism-agent-client` | `clients/python` | Target Python `>= 3.10`. Zero runtime dependencies outside Python standard library (`urllib.request`, `json`). | Remote client for starting runs, streaming SSE events, and submitting edited approvals. |
+| **Remote Client: .NET** | `Prism.Client` | `clients/dotnet` | Target `.NET 8.0+` LTS. Pure `System.Net.Http` and `System.Text.Json`. | Remote C# client for Prism Server communication. |
+| **Channel: Slack** | Slack Webhook Recipe | `examples/channels/slack` | Uses raw Node HTTP HMAC verification or optional `@slack/bolt`. | Webhook receiver verifying `X-Slack-Signature` and rendering Block Kit editable approval cards. |
+| **Channel: Teams** | Teams Bot Recipe | `examples/channels/teams` | Uses Bot Framework JWT verification or `@microsoft/teamsfx`. | Bot Framework webhook receiver validating Microsoft tenant and rendering Adaptive Cards. |
+| **Realtime Voice** | OpenAI Realtime | Native WebSocket | Pinned to OpenAI Realtime API (`gpt-4o-realtime-preview`). Pure WebSocket transport in `@arnilo/prism-providers`. | Governed bidirectional audio streaming with microphone device admission and barge-in cancellation. |
+
+---
+
+## 4. Performance, Startup, and Package Budgets
+
+All implementations in 0.7.0 must adhere to established performance ceilings recorded in `scripts/budgets.json`.
+
+### 4.1 Package Size & File Count Budgets
+
+| Package | Packed Bytes Baseline (±5%) | Unpacked Bytes Baseline (±5%) | File Count Baseline (±5%) | Public Export Count Ceiling |
+|---|---|---|---|---|
+| `@arnilo/prism` (root) | 1,098,881 | 3,690,682 | 441 | 1,287 |
+| `@arnilo/prism-acp-agent` | — | — | — | 11 |
+| `@arnilo/prism-ag-ui` | — | — | — | 312 |
+| `@arnilo/prism-mcp` | — | — | — | 134 |
+| `@arnilo/prism-memory` | — | — | — | 638 |
+| `@arnilo/prism-office` | — | — | — | 230 |
+| `@arnilo/prism-coding-tools` | — | — | — | 955 |
+| `@arnilo/prism-core` | — | — | — | 1,333 |
+| `@arnilo/prism-providers` | — | — | — | 506 |
+| `@arnilo/prism-web-tools` | — | — | — | 303 |
+
+*Rule:* Any increase in root packed bytes or file count must be justified in `scripts/budgets.json`. Export ceilings fail closed under `scripts/budget-gate.test.mjs`.
+
+### 4.2 Startup Time Budgets
+
+- **Cold-Process `import('@arnilo/prism')` Wall Time**:
+  - Baseline: `38 ms`
+  - Hard Ceiling: `250 ms`
+- **Machine-Relative Startup Ratio (`importMs / processStartMs`)**:
+  - Baseline Ratio: `3.3`
+  - Idle Ceiling Ratio: `8.0`
+  - Under-Load Ceiling Ratio (`loadavg >= 1.5` per CPU): `20.0`
+
+*Enforcement:* No optional provider, tool, database, or SDK dependency may evaluate at package import time. All heavy imports are deferred to dynamic `await import()` upon explicit host activation.
+
+### 4.3 Workload Bounds & Hard Caps
+
+- **Request / Response Safety Caps**:
+  - `DEFAULT_MAX_REQUEST_BYTES`: `4 MiB` (hard ceiling `32 MiB`)
+  - `DEFAULT_MAX_RESPONSE_BYTES`: `4 MiB` (hard ceiling `32 MiB`)
+  - `HARD_CHUNK_SIZE_CAP` (RAG): `64 KiB`
+- **Event Streaming Caps**:
+  - Ring buffer size: `100` items default, `10,000` hard max
+  - SSE message size: `64 KiB` max per frame
+- **Concurrency & Conformance Bounds**:
+  - Max concurrent distributed coordinator claims: `4` default, `16` max
+  - Router concurrent reservation stress: `32` concurrent workers across `>= 2` models
+
+---
+
+## 5. Architectural Invariants & Shared Contracts
+
+To maintain code quality and prevent divergence across packages:
+
+### 5.1 No Duplicated Primitives
+- **Agent Loop**: Single execution loop in `src/agent-session/session.ts`. No secondary loop in ACP, supervisor, or delegated wrappers.
+- **Approval Store**: Approvals managed strictly through `RunDecision` and `CheckpointStore`. No standalone approval database.
+- **Scheduler**: Workflow execution managed by `createWorkflowCoordinator` with `LeaseStore`. No secondary cron or background queue daemon.
+- **Tool Registry**: Single `ToolRegistry` implementation in `src/tools.ts`. Per-run narrowing filters the registry dynamically; it does not instantiate a separate registry.
+
+### 5.2 Genuinely Shared Contracts
+1. **Governed Provider Invocation**:
+   ```ts
+   export interface GovernedInvocationOptions {
+     readonly router: ModelRouter;
+     readonly model: ModelConfig;
+     readonly identity: AgentIdentity;
+     readonly maxCostUsd?: number;
+   }
+   ```
+   Wraps `AIProvider.generate()` / `generateStream()` with atomic reservation, request policy injection, response metering, and commit/release.
+2. **Durable Action Draft & Revision Reference**:
+   ```ts
+   export interface ActionDraftRevision {
+     readonly draftId: string;
+     readonly revision: number;
+     readonly payloadDigest: string; // sha256 of canonical payload
+     readonly policyRevision: string;
+     readonly createdAt: string;
+   }
+   ```
+   Ensures that any edit to a draft changes its digest and invalidates prior approvals.
+3. **RAG Access Constraint**:
+   ```ts
+   export interface RagAccessConstraint {
+     readonly principalId: string;
+     readonly groupIds: readonly string[];
+     readonly tenantId: string;
+   }
+   ```
+   Passed down to both vector search and lexical query legs to enforce pre-ranking exclusion.
+
+---
+
+## 6. Threat Model & Security Enforcement
+
+| Threat Domain | Threat Vector | Mitigation & Fail-Closed Enforcement | Visibility & Audit |
+|---|---|---|---|
+| **Identity & Tenant Scope** | Cross-tenant access, spoofed userId in distributed calls | Identity active and ownership matching verified via `assertIdentityMatchesOwnership`. Cross-tenant budget or session access throws `ERR_PRISM_SECURITY_TENANT_MISMATCH`. | OTel trace tenant tag; `AgentEvent.agent_denied` emitted on mismatch. |
+| **Source ACLs (RAG)** | Unauthorized document exposure via vector similarity or lexical search | Predicate pushdown into SQL / vector queries. Unauthorized candidates never enter candidate list or top-K ranking. Revocation invalidates cached candidates. | Audit log records query principal and accessed document IDs. Text is never logged. |
+| **Durable Approvals** | Approval replay, editing payload after approval, unauthorized approver | `expectedVersion` CAS on resume. Approved digest must match current draft digest. Edits invalidate approval and increment revision. Separation-of-duties requires distinct approver. | `RunDecision` records approver identity, timestamp, and payload digest. |
+| **Credentials & Secrets** | Leaked provider tokens in logs, event streams, or process argv | Credential references (`credentialRef`) used in configs. Secrets resolved only at provider edge. `SecretRedactor` scrubs all ledgers and event streams. | Canary strings tested across all event streams, logs, and artifacts. |
+| **Execution Containment** | Malicious shell execution, sandbox breakout, directory traversal | Docker sandbox with `network: "none"` or audited proxy; non-root user; workspace root confinement via realpath traversal checks. E2B uses isolated cloud VMs. | Container ID, image digest, and execution policy audited per session. |
+| **Durable Resume & Fencing** | Split-brain execution, duplicate side-effect replay upon network failure | Distributed lease acquisition with fencing tokens. External mutations record `ToolEffectStore` idempotent keys. Ambiguous outcomes stay `unknown`. | Lease records in PostgreSQL with TTL; unknown effects surfaced in run status. |
+| **Budget & Cost Exhaustion** | Runaway LLM loops, unmetered tool/compaction calls | Atomic budget reservation before model call. Strict budget mode rejects calls without known pricing. Background compaction and embeddings charged against task budget. | Aggregated usage records linked to `taskId` and `tenantId`. |
+| **Remote Runtime Delegation** | Prompt injection via delegated agents (Codex/Claude/Cursor) | All external agent tool requests route through Prism's `ExecutionPolicy`. Approval interception preserves host control. External session state kept isolated. | Delegated agent steps logged as `delegated_agent_step` events with token usage. |
+
+---
+
+## 7. Plan 072, 074, 077 Boundary Freeze
+
+To maintain strict modularity across concurrent plans:
+- **Plan 072 Freeze (Eval & Observability)**:
+  - `ExecutionTimeline`, `projectAgentTimeline`, `projectTraceTimeline`, `projectWorkflowTimeline` are owned by Plan 072.
+  - `WorkflowGraphView` and `serializeWorkflowGraph` are owned by Plan 072.
+  - Trajectory scorers (`createToolCallMatchScorer`) and scenario runners are owned by Plan 072.
+  - Task 15 of Plan 073 strictly wires these surfaces into Dev Inspector and Release Gates; it **does not** create duplicate timeline projectors.
+- **Plan 077 Freeze (Work-Scope Memory Index)**:
+  - `WorkScope`, `projectWorkMemory`, session memory isolation are owned by Plan 077.
+  - Plan 073 assumes work-scope isolation in its coding journeys without reimplementing the index.
+- **Plan 074 Freeze (Attention Compiler)**:
+  - `assembleTurn`, ratio gates, and sticky stub compaction triggers are owned by Plan 074.
+  - Plan 073 does not introduce a competing prompt assembly or compaction trigger.
+
+---
+
+## 8. Resolution of File Lists & Barrels (Tasks 2–29)
+
+Below are the exact resolved file paths and implementation splits for all tasks where tentative or proposed filenames appeared in the plan:
+
+| Task | Capability | Resolved Implementation & Test Files | Export / Barrel Location |
+|---|---|---|---|
+| **Task 4** | Real-provider ACP launcher | `packages/acp-agent/src/config.ts`, `packages/acp-agent/src/index.ts`, `packages/acp-agent/bin/prism-acp-agent.ts`, `packages/acp-agent/src/__tests__/agent.test.ts` | `packages/acp-agent/src/index.ts` |
+| **Task 5** | Host composition templates | `templates/personal-assistant/src/index.ts`, `templates/personal-assistant/package.json`, `templates/business-worker/src/index.ts`, `templates/business-worker/package.json`, `packages/prism-coding-tools/src/dev/inspector.ts` | `templates/README.md`, `packages/prism-coding-tools/src/dev/index.ts` |
+| **Task 6** | Governed provider invocation | `packages/prism-core/src/governance/model-router/invocation.ts`, `packages/prism-core/src/governance/model-router/__tests__/invocation.test.ts` | `packages/prism-core/src/governance/model-router/index.ts` |
+| **Task 7** | Aggregate task accounting | `packages/prism-core/src/enterprise/postgres/model-router/reservations.ts`, `packages/prism-core/src/enterprise/postgres/model-router/state-store.ts`, `packages/prism-core/src/enterprise/postgres/migrations.ts` | `packages/prism-core/src/enterprise/postgres/index.ts` |
+| **Task 8** | Durable draft review | `packages/prism-core/src/integrations/work/drafts.ts`, `packages/prism-core/src/integrations/work/tools.ts`, `packages/prism-core/src/integrations/work/google-workspace.ts`, `packages/prism-core/src/integrations/work/microsoft365.ts`, `packages/prism-core/src/integrations/work/__tests__/drafts.test.ts` | `packages/prism-core/src/integrations/work/index.ts` |
+| **Task 9** | AG-UI editable approvals | `packages/ag-ui/src/handler.ts`, `packages/ag-ui/src/types.ts`, `packages/ag-ui/src/projection.ts`, `packages/prism-core/src/runtime/server/handler/core.ts`, `packages/prism-core/src/runtime/server/handler/readers.ts` | `packages/ag-ui/src/index.ts` |
+| **Task 10** | Docker process sessions | `packages/prism-coding-tools/src/security/docker-sandbox.ts`, `packages/prism-coding-tools/src/security/docker-cli.ts`, `packages/prism-coding-tools/src/agent/process/sessions-spawn.ts`, `packages/prism-coding-tools/src/agent/process/sessions-recovery.ts` | `packages/prism-coding-tools/src/security/index.ts` |
+| **Task 11** | Document authorization in RAG | `packages/memory/src/rag/retrieve.ts`, `packages/memory/src/rag/types.ts`, `packages/memory/src/postgres.ts`, `packages/memory/src/__tests__/rag-acl.test.ts` | `packages/memory/src/rag/index.ts` |
+| **Task 12** | Google Drive incremental sync | `packages/memory/src/rag/sync.ts`, `packages/memory/src/connectors/google-drive.ts`, `packages/memory/src/__tests__/sync.test.ts` | `packages/memory/src/index.ts` |
+| **Task 13** | Hosted sandbox (E2B) | `packages/prism-coding-tools/src/security/e2b-sandbox.ts`, `packages/prism-coding-tools/src/security/__tests__/e2b-sandbox.test.ts` | `packages/prism-coding-tools/src/security/index.ts` |
+| **Task 14** | Fair background admission & drain | `packages/prism-core/src/runtime/server/drain.ts`, `packages/prism-core/src/runtime/workflows/coordinator.ts`, `packages/prism-core/src/runtime/server/__tests__/drain.test.ts` | `packages/prism-core/src/runtime/server/index.ts` |
+| **Task 15** | Inspector eval/journey wiring | `packages/prism-coding-tools/src/dev/ui/inspector.ts`, `packages/prism-coding-tools/src/dev/server.ts`, `packages/prism-coding-tools/src/dev/__tests__/inspector.test.ts` | `packages/prism-coding-tools/src/dev/index.ts` |
+| **Task 16** | Cross-layer memory correction | `packages/memory/src/memory.ts`, `packages/memory/src/lineage.ts`, `packages/memory/src/compaction/observational-memory/runtime.ts`, `packages/memory/src/compaction/observational-memory/ledger.ts` | `packages/memory/src/index.ts` |
+| **Task 17** | Delegated runtimes (Codex/Claude) | `packages/prism-coding-tools/src/agent/delegated/codex.ts`, `packages/prism-coding-tools/src/agent/delegated/claude.ts`, `packages/prism-coding-tools/src/agent/delegated/types.ts`, `packages/prism-coding-tools/src/agent/delegated/index.ts` | `packages/prism-coding-tools/src/index.ts` |
+| **Task 18** | Delegated runtimes (Copilot/Gemini/Cursor) | `packages/prism-coding-tools/src/agent/delegated/copilot.ts`, `packages/prism-coding-tools/src/agent/delegated/gemini-cli.ts`, `packages/prism-coding-tools/src/agent/delegated/cursor.ts` | `packages/prism-coding-tools/src/agent/delegated/index.ts` |
+| **Task 19** | Semantic artifact diffs & evidence | `packages/office/src/documents/diff.ts`, `packages/prism-core/src/runtime/server/artifacts-service.ts`, `packages/web-tools/src/evidence.ts` | `packages/office/src/index.ts`, `packages/web-tools/src/index.ts` |
+| **Task 20** | Scanned document OCR (Mistral) | `packages/office/src/documents/parse.ts`, `packages/prism-coding-tools/src/document-reader/mistral-ocr.ts` | `packages/prism-coding-tools/src/document-reader/index.ts` |
+| **Task 21** | Per-run tool narrowing | `src/contracts-protocol.ts` (`RunOptions.toolAllowList`), `src/tools.ts`, `src/agent-session/session/provider-round.ts`, `packages/mcp/src/bridge.ts`, `packages/mcp/src/capabilities.ts` | `src/index.ts`, `packages/mcp/src/index.ts` |
+| **Task 22** | Native Bedrock Converse | `packages/prism-providers/src/bedrock/converse.ts`, `packages/prism-providers/src/bedrock/converse-stream.ts`, `packages/prism-providers/src/bedrock/provider.ts` | `packages/prism-providers/src/bedrock/index.ts` |
+| **Task 23** | Native Vertex Gemini | `packages/prism-providers/src/vertex/native.ts`, `packages/prism-providers/src/vertex/provider.ts` | `packages/prism-providers/src/vertex/index.ts` |
+| **Task 24** | Python & .NET remote clients | `clients/python/prism_client/{__init__.py,client.py}`, `clients/dotnet/Prism.Client/{PrismClient.cs,Prism.Client.csproj}` | Standalone client directories (excluded from npm root) |
+| **Task 25** | Slack & Teams channel recipes | `examples/channels/slack/{index.ts,package.json}`, `examples/channels/teams/{index.ts,package.json}` | `examples/channels/` |
+| **Task 26** | Governed realtime voice | `packages/prism-core/src/runtime/realtime/index.ts`, `packages/prism-core/src/runtime/realtime/session.ts`, `packages/prism-providers/src/openai/realtime.ts` | `packages/prism-core/src/runtime/index.ts`, `packages/prism-providers/src/index.ts` |
+
+---
+
+## 8. Evidence Checklist
+
+Every capability delivered under 0.7.0 must satisfy this verification matrix:
+
+- [ ] **Positive Verification**: Proves expected behavior on compliant inputs.
+- [ ] **Refusal & Fail-Closed**: Proves rejected state on lookalike, malformed, unauthenticated, or cross-tenant inputs.
+- [ ] **Restart & Recovery**: Proves state durability across process restarts without duplicate execution or state corruption.
+- [ ] **Bounds & Limits**: Proves strict adherence to byte caps, timeout limits, and concurrency ceilings.
+- [ ] **Documentation & Migration**: Proves accurate contract documentation in `/docs` and migration guidance in `docs/migrate-to-0.7.md`.

package/docs/history/migration-0.0.md

@@ -513,7 +513,7 @@ OAuth client behavior is 2026-07-28 conformant: `finishAuth` now takes the full
 
 ### Monolithic SDK 1.x → modular SDK v2 migration table
 
-| v1 (`@modelcontextprotocol/sdk` 1.30.0) | v2 / current Synapta API | Notes |
+| v1 (`@modelcontextprotocol/sdk` 1.30.0) | v2 / current Prism MCP API | Notes |
 | --- | --- | --- |
 | `new Client(...)` from `sdk/client/index.js` | same name from `@modelcontextprotocol/client` | `ClientOptions` gains `versionNegotiation`, `listChanged`, `inputRequired`, `cachePartition`, `listMaxPages` |
 | `InMemoryTransport` / `StdioClientTransport` / `StreamableHTTPClientTransport` | `InMemoryTransport`/`StreamableHTTPClientTransport` from `@modelcontextprotocol/client`; `StdioClientTransport` from `@modelcontextprotocol/client/stdio` | subpath moves only |
@@ -529,7 +529,7 @@ OAuth client behavior is 2026-07-28 conformant: `finishAuth` now takes the full
 
 - **Now (default):** `createPrismMcpWebHandler(factory)` without `sessionIdGenerator` is stateless dual-era — modern 2026-07-28 serving plus the SDK stateless fallback for 2025 clients. No `Mcp-Session-Id`, no sticky routing, `Last-Event-ID` replay not enabled.
 - **Now (opt-in):** configuring `sessionIdGenerator` keeps identity-bound legacy sessions (POST/GET/DELETE/SSE beside the strict modern handler) for hosts that still need them; the pairing requires exact `allowedOrigins` and host `resolveIdentity`.
-- **Planned removal:** the legacy session leg is deprecated once Synapta's clients and documented hosts are modern-era; removal lands as a breaking 0.x cut with a migration note here (the `sessionIdGenerator` option disappears and legacy traffic gets the SDK stateless fallback, which 2025 clients already work against). No date is committed in this release.
+- **Planned removal:** the legacy session leg is deprecated once the package's clients and documented hosts are modern-era; removal lands as a breaking 0.x cut with a migration note here (the `sessionIdGenerator` option disappears and legacy traffic gets the SDK stateless fallback, which 2025 clients already work against). No date is committed in this release.
 
 ## 0.0.7 → 0.0.8 OpenTelemetry adapter
 

package/docs/history/release-handoffs.md

@@ -2,6 +2,42 @@
 
 Operator publish handoffs per release line, kept verbatim. Not read on the hot path.
 
+### 0.7.0 publish handoff (plan 073 Tasks 28–29)
+
+**Decision: GO when the operator prerequisites below are recorded.** Release **0.7.0** is the **six-plan cut** that closed the extended line: [072](../evaluations.md) (execution timeline, workflow graph, trajectory/outcome evals, cockpit aggregations, workflow OTel), [073](../index.md) (host completeness: traps A–C, R01–R06, R08, R10–R14, Tasks 15/30/31 and the cut itself), [074](../attention-compiler.md) (R17 attention compiler and the host-programmable compaction trigger), [075](../memory-fabric.md) (Memory Fabric subpath), [077](../compaction-observational-memory.md) (R16 work-scope memory index) and [078](../supervisors.md) (host-owned subagent spawn, bounded async spawn/wait/cancel, worktree isolation). **Plan 079 (Telegram/Signal channels) was moved to 0.8.0 on 2026-09-15** so the cut stopped waiting on unstarted work; no channel adapter ships in 0.7.0.
+
+The graph is **10 publishable manifests** at exact **0.7.0** with internal caret ranges `^0.7.0`: root `@arnilo/prism` plus 9 workspace packages (3 `prism-*` family packages, 6 capability packages, 19 provider adapter subpaths inside the providers family). The predecessor published release is **0.6.0**.
+
+Host-visible delta (full detail in [migrate-to-0.7.md](../migrate-to-0.7.md)): two **hard refusals** inside existing surfaces — `@arnilo/prism-acp-agent` matches `mcp.allow` by WHATWG origin plus path-segment subtree (lookalike hosts, sibling prefixes, credentials, and ambiguous encodings now fail closed) and no longer silently falls back to a mock provider; `router.providerSource(model)` throws `ERR_PRISM_MODEL_ROUTER_ASYNC_REQUIRED` / `_ASYNC_STATE` instead of bypassing budgets, rate limits, circuits, fallbacks, selection policies, or durable state. Everything else is additive: opt-in attention compiler, `@arnilo/prism-memory/fabric`, the observational-memory work-scope index, supervisor `spawn_agent`/`wait_agent`/`cancel_agent`, plus behavioral tightenings inside R01–R14 surfaces. **No export was removed**: the compat baselines were regenerated and reviewed as **+469 public declarations, zero removals**.
+
+Evidence recorded for the tree under publication. `scripts/release-evidence.json` — **42 surfaces, 11 pass, 31 protected with reasons, `blocked: false`** (`test:postgres durable conformance` is a real pass; the only unavailable leg is the real-phase26 coding journey). `npm test` 5/5 stages; `npm run typecheck` green for root, all workspaces, and `examples/`; coverage core 92.43 lines against the 60/70/75 gate with every non-protected workspace above its recorded lines threshold (acp-agent recovered to 94.72 by exporting and testing its provider resolver); `npm run pack:dry-run` green for all ten packages; `npm run release:check --lockstep --version 0.7.0` reports **10/10 packages available**; `npm run release:publish --dry-run` produces all ten packs deterministically; `npm run security:threat-suites` **83/83**; `npm audit --audit-level=moderate` **0**; tracked+untracked secret scan **2328 files, 0 findings**; SBOM regenerated (172 packages) and `scripts/verify-sbom.mjs` clean against `security/license-policy.json`.
+
+Protected legs actually run here (not just recorded): `PRISM_TEST_POSTGRES_URL=… npm run test:postgres` against `pgvector/pgvector:pg16` — core **72/72**, memory **457/457**, phase conformance **11/11**; `node scripts/drill-migration-rollback.mjs --url …` — Postgres apply → downgrade `009` → verify-compat → re-apply → checksum-fail-closed and the SQLite flow all pass, plus the `--self-test` URL-refusal check. That leg found and closed three real defects hermetic doubles could not see: a `42P08` parameter-type ambiguity on the first task-scoped budget insert, a swallowed serialization failure that issued SQL against an aborted transaction (`25P02`), and a retry policy too small for 16 concurrent serializable writers. The release workflow's `postgres-integration` job must be green on the release commit before publication.
+
+```bash
+# Operator prerequisites (each a named blocked gate — none may be skipped):
+#  1. protected live-canary matrix green (live-canaries.yml, canary-report.json retained)
+#  2. PostgreSQL protected suite green (test:postgres) and CodeQL SAST green on the release commit
+#  3. npm OIDC trusted publishing identity authenticated (NPM_TOKEN with id-token, provenance)
+#  4. branch protection: the compatibility leg is node22-compat
+
+git diff --check
+npm ci
+# sdk:ready phases, as .github/workflows/release.yml runs them (env scoped to release:gate only):
+npm run typecheck && npm run lint && npm run format:check
+npm test && npm run test:coverage && npm run pack:dry-run
+PRISM_TEST_POSTGRES_URL=... npm run release:gate
+npm run security:threat-suites
+
+# Sign the release on the clean tagged tree (operator GPG key):
+git tag -s v0.7.0 -m "0.7.0"
+node scripts/release.mjs publish --lockstep --version 0.7.0
+
+# First-party package tags: push in batches of <=3 per push (tag-push storms; VENT 26-08-29).
+```
+
+Rollback pins the previous published line — `@arnilo/prism@0.6.0` and its siblings, exact pins per package. Persisted shapes are additive across 0.6.0 → 0.7.0 (fabric notes, scope entries, and spawn handles write new records through existing stores; migrations `001`–`006` are forward-only), so a pin rollback is store-safe: a 0.6.0 host ignores entries it cannot read and regains the pre-0.7.0 ACP prefix matching and router facade bypass, which is why those two refusals should be re-checked before rolling back.
+
 ### 0.6.0 publish handoff (plan 071 Task 16)
 
 
@@ -271,7 +307,7 @@ node scripts/release.mjs publish --independent --baseline c600eaa18f65b56764ec2f
 ### 0.3.2 changed-package cut (plan 050 Task 12)
 
 
-**Decision: GO when the operator prerequisites below are recorded.** The plan 050 cut covers the clay-integration-findings remediation and the OKF wiki adoption: baseline `edb4fcf` (the parent of the plan 050 implementation work); five packages publish in dependency order — root `@arnilo/prism` (FEATURE-1 agent-definition model override fallback, FEATURE-3 command driver hooks, FEATURE-2/6 docs+example, DOCS-1 contracts), `@arnilo/prism-coding-agent` (BUG-1 `allowCustom` default + optional `toolCallId`), `@arnilo/prism-supervisor` (BUG-2 child-factory `Agent` guard, FEATURE-4 opt-in child event passthrough), `@arnilo/prism-wiki` (OKF v0.2 bundle emission, 0.0.2 → 0.0.3), and `@arnilo/prism-acp-agent` (sqlite `:memory:` pass-through fix, 0.0.x-style patch 0.3.1 → 0.3.2). Every unchanged package stays byte-identical; docs-only packages (`@arnilo/prism-workflows`, `@arnilo/prism-compaction-observational-memory`) do not bump. Republished packages carry `^0.3.2` root peers; unchanged packages keep their window peers. Docs-only change on the root: none of the deltas are breaking (additive fields and fail-closed guards), compat additive-only, no migration.
+**Decision: GO when the operator prerequisites below are recorded.** The plan 050 cut covers the integration-findings remediation and the OKF wiki adoption: baseline `edb4fcf` (the parent of the plan 050 implementation work); five packages publish in dependency order — root `@arnilo/prism` (FEATURE-1 agent-definition model override fallback, FEATURE-3 command driver hooks, FEATURE-2/6 docs+example, DOCS-1 contracts), `@arnilo/prism-coding-agent` (BUG-1 `allowCustom` default + optional `toolCallId`), `@arnilo/prism-supervisor` (BUG-2 child-factory `Agent` guard, FEATURE-4 opt-in child event passthrough), `@arnilo/prism-wiki` (OKF v0.2 bundle emission, 0.0.2 → 0.0.3), and `@arnilo/prism-acp-agent` (sqlite `:memory:` pass-through fix, 0.0.x-style patch 0.3.1 → 0.3.2). Every unchanged package stays byte-identical; docs-only packages (`@arnilo/prism-workflows`, `@arnilo/prism-compaction-observational-memory`) do not bump. Republished packages carry `^0.3.2` root peers; unchanged packages keep their window peers. Docs-only change on the root: none of the deltas are breaking (additive fields and fail-closed guards), compat additive-only, no migration.
 
 ```bash
 node scripts/release.mjs changed --baseline edb4fcf   # 5 packages

package/docs/host-compositions.md

@@ -0,0 +1,147 @@
+# Host compositions
+
+Prism agents are host-assembled: the host application owns credentials, providers, persistence, permissions, and tool definitions. Prism provides two canonical, maintained host compositions and a zero-network inspection and readiness API to ensure host setups conform to their operational contracts:
+
+- **`personal` (`personal-assistant`)**: Local-personal host composition for single-operator productivity, personal tools, local/memory persistence, and secret redaction.
+- **`business` (`business-worker`)**: Multi-tenant enterprise worker host composition with verified tenant identity, mandatory durable storage, sandbox workspace containment, and strict governance enforcement.
+
+## Profiles
+
+| Profile | Ownership | Identity | Persistence | Sandbox | Governance |
+| --- | --- | --- | --- | --- | --- |
+| `personal` | Single user (`userId`) | Optional unverified operator | Memory or durable storage | Local workspace | Optional |
+| `business` | Tenant + user (`tenantId`, `userId`) | Mandatory verified identity (`verified: true`) matching tenant | Mandatory durable store (`durable: true`); memory rejected | Contained sandbox roots within workspace | Required supported governance |
+
+## Host composition API
+
+Both helper functions and the error class are exported from `@arnilo/prism`:
+
+```ts
+import {
+  inspectHostComposition,
+  assertHostCompositionReadiness,
+  HostCompositionError,
+  type HostCompositionProfile,
+  type HostCompositionOptions,
+  type HostCompositionReport,
+} from "@arnilo/prism";
+```
+
+### `inspectHostComposition(options)`
+
+Inspects an agent configuration and returns a typed `HostCompositionReport`. Inspection is **completely inert and performs zero network calls**. Canary secrets in credentials are never leaked.
+
+```ts
+const report = inspectHostComposition({
+  profile: "personal",
+  agent: personalAgent,
+  store: memoryStore,
+  credentialRefs: ["OPENAI_API_KEY"],
+});
+```
+
+Report structure:
+
+- `profile`: `"personal"` or `"business"`.
+- `effectiveTools`: Readonly list of tool names registered on the agent.
+- `credentialRefs`: Host credential references (sanitized, values never included).
+- `ownership`: Tenant and user ownership identifiers.
+- `storage`: Storage summary with `kind` (`"memory"`, `"postgres"`, `"sqlite"`, etc.) and `durable` boolean. Memory stores are truthfully reported with `durable: false`.
+- `sandbox`: Isolation status and resolved root paths.
+- `governance`: Coverage flags (authorization, trust, and custom policies).
+- `readiness`: Object with `ok: boolean` and list of `reasons` if not ready.
+
+### `assertHostCompositionReadiness(options)`
+
+Validates that the host composition satisfies all profile constraints. Throws `HostCompositionError` on the first violated rule:
+
+| Error Code | Violation |
+| --- | --- |
+| `ERR_PRISM_HOST_COMPOSITION_PROFILE` | Unknown or missing profile. |
+| `ERR_PRISM_HOST_COMPOSITION_OWNERSHIP` | Missing `userId` (personal), missing `tenantId` (business), or identity/ownership mismatch. |
+| `ERR_PRISM_HOST_COMPOSITION_STORAGE` | Non-durable or in-memory persistence passed to a business composition. |
+| `ERR_PRISM_HOST_COMPOSITION_SECRETS` | Agent lacks a configured `SecretRedactor`. |
+| `ERR_PRISM_HOST_COMPOSITION_PROVIDER` | Agent lacks an active `AIProvider` or model selection. |
+| `ERR_PRISM_HOST_COMPOSITION_SANDBOX` | Sandbox roots escape the declared `workspaceRoot`. |
+| `ERR_PRISM_HOST_COMPOSITION_GOVERNANCE` | Governance policy disabled or unsupported. |
+
+### Integration with `createSecureAgent`
+
+`createSecureAgent` accepts an optional `composition` field. When provided, readiness is asserted immediately before the agent is returned:
+
+```ts
+import { createSecureAgent } from "@arnilo/prism";
+
+const agent = createSecureAgent({
+  id: "worker-1",
+  definitionRevision: "1",
+  ownership: { tenantId: "acme-corp", userId: "worker-prod" },
+  identity: {
+    tenantId: "acme-corp",
+    userId: "worker-prod",
+    principal: { kind: "user", id: "worker-prod" },
+    scopes: ["task:execute"],
+    verified: true,
+    issuedAt: new Date().toISOString(),
+  },
+  composition: {
+    profile: "business",
+    store: postgresStore,
+    workspaceRoot: "/data/acme",
+    sandboxRoots: ["/data/acme/scratch"],
+  },
+  // ... other required secure agent options
+});
+```
+
+## Package install vs. import subpaths
+
+Always install containing packages directly. **NPM install never accepts subpaths**:
+
+```bash
+# Correct — install containing published packages:
+npm install @arnilo/prism @arnilo/prism-core @arnilo/prism-providers
+
+# Never install subpaths:
+# npm install @arnilo/prism-core/integrations/work (WRONG: fails with 404 / E404)
+```
+
+In your application code, import from documented subpaths:
+
+```ts
+// Subpaths exported by @arnilo/prism-core:
+import { createWorkTools } from "@arnilo/prism-core/integrations/work";
+import { createJsonSchemaArgumentValidator } from "@arnilo/prism-core/validation/json-schema";
+
+// Subpaths exported by @arnilo/prism-providers:
+import { createOpenAIProvider } from "@arnilo/prism-providers/openai";
+```
+
+## Background workers
+
+Business workers that share a durable checkpoint queue should pass `admission: { perTenant, drain }` into `createWorkflowCoordinator` and mount `createPrismOperatorHandler` beside health/drain. See [Operations runbook](operations.md) and [Workflows](workflows.md). Do not introduce a second scheduler.
+
+## Starter templates
+
+Scaffold fresh host compositions using `prism init`:
+
+```bash
+# Personal assistant composition
+prism init my-assistant --template personal-assistant
+
+# Business worker composition
+prism init my-worker --template business-worker
+```
+
+Each template produces a runnable agent, mock test fixtures, environment templates, and strict typing.
+
+## Dev inspector endpoint
+
+When running `@arnilo/prism-coding-tools/dev`, host compositions can be inspected via HTTP:
+
+```bash
+GET /inspect
+# or GET {basePath}/inspect
+```
+
+Returns the JSON serialized `HostCompositionReport` corresponding to the inspected agent and options.

package/docs/hosted-sandboxes.md

@@ -0,0 +1,94 @@
+# Hosted sandboxes
+
+## What it does
+
+`createE2BSandbox` / `connectE2BSandbox` map one hosted vendor (E2B) onto the existing `DisposableSandbox` contract: `execFile`, optional `startProcess` / `attachProcess`, `pause` / `resume`, and explicit `kill`. Prism does not run hosted compute. The host owns the E2B account, template, API key, and lifecycle. Pause is the snapshot. `keepMemory: false` is filesystem-only: resume reboots and running processes are gone. `Sandbox.connect` auto-resumes a paused sandbox; this adapter never calls it unless the host calls `resume()` or passes `resume: true`.
+
+## When to use it
+
+Use this adapter when coding or process work should run in an E2B cloud sandbox rather than Docker. Use `createDockerSandbox` when you need a local digest-pinned container with `network: none`. Do not assume E2B isolation matches Docker: default capabilities report `networkIsolated` and `egressRestricted` false (E2B sandboxes have internet).
+
+## Inputs / request
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `apiKey` | unless `client` | Resolved at the SDK edge only. Never logged. |
+| `client` | unless `apiKey` | Host-injected `e2b` `Sandbox` surface for tests or a pinned SDK. |
+| `template` | no | Default `base`. Host-owned image/template. |
+| `workdir` | no | Default `/workspace`. |
+| `timeoutMs` / `limits.wallTimeMs` | no | Passed to E2B as sandbox timeout (idle/cost budget). |
+| `onTimeout` | no | `kill` (default) or `pause`. `autoResume` is always false. |
+| `labels` | no | Stored as E2B metadata for reconnect attestation. No secrets. |
+| `expectedLabels` (connect) | no | Fail-closed mismatch → wrong owner. |
+| `resume` (connect) | no | Default false. Paused sandboxes stay paused until `resume()`. |
+| `capabilities` | no | Full host attestation; omitted fields resolve false. |
+
+Optional peer: `e2b@2.49.1` (MIT). Install it or pass `client`.
+
+## Outputs / response / events
+
+`createE2BSandbox` returns a `DisposableSandbox`:
+
+- `id` is the E2B sandbox id (non-secret reconnect identity).
+- `pause({ keepMemory })` → `{ kind: "memory" \| "filesystem", state: "paused" }`. HTTP 503 (`ServiceBusyError`) leaves the sandbox **running**.
+- `resume()` calls `Sandbox.connect` (explicit).
+- `startProcess` refs are `prism-e2b-proc:<base64url>`. Filesystem-only pause makes `attachProcess` return null.
+- `stop()` pauses with memory. `kill()` / `close()` destroy the sandbox. `close({ export })` is unsupported (pause is the snapshot).
+- Default capabilities: workspace coherent, filesystem isolated from the host, process isolated; **not** network/egress/privilege isolated.
+
+## Request/response example
+
+```json
+{
+  "template": "base",
+  "timeoutMs": 600000,
+  "onTimeout": "kill",
+  "labels": { "app.owner": "alice" },
+  "pause": { "keepMemory": false }
+}
+```
+
+## Implementation example
+
+```ts
+import { connectE2BSandbox, createE2BSandbox } from "@arnilo/prism-coding-tools/security";
+
+const sandbox = await createE2BSandbox({
+  apiKey: process.env.E2B_API_KEY,
+  labels: { "app.owner": "alice" },
+  timeoutMs: 10 * 60_000,
+});
+await sandbox.execFile({ file: "/bin/echo", args: ["ok"], cwd: "/workspace" });
+await sandbox.pause!({ keepMemory: false });
+
+const again = await connectE2BSandbox({
+  apiKey: process.env.E2B_API_KEY,
+  sandboxId: sandbox.id,
+  expectedLabels: { "app.owner": "alice" },
+});
+await again.resume!();
+await again.kill();
+```
+
+## Extension and configuration notes
+
+- Detect `pause` / `startProcess` like Docker: `typeof sandbox.pause === "function"`. Absence is not an error on other backends.
+- `createE2BProcessRecoveryBackend(sandbox, { expectedSandboxId, expectedWorkspace, expectedLabels })` is the attested `ProcessRecoveryBackend`. `createProcessSessions({ sandbox })` still auto-wires `attachProcess` when present.
+- `lifecycle.autoResume` is forced false. Activity (exec, file, HTTP) must not resume paused work.
+- Paused E2B sandboxes persist until `kill()`. There is no vendor TTL; the host must delete.
+
+## Security and performance notes
+
+- Attest vendor isolation; do not copy Docker `network: none` claims. Override `capabilities` only when the host actually restricted the template/network.
+- API keys belong in `apiKey` or the injected client, never metadata, refs, labels, argv, or logs. Errors pass through `createSecretRedactor`.
+- Process refs carry sandbox id, pid, command fingerprint, and workspace — no secrets.
+- Pause duration is vendor-bound (about 4s per GiB RAM). Command output, env, and concurrent execs use the same sandbox limit caps as Docker (`maxOutputBytes`, `maxCommands`, `maxConcurrentExecs`).
+- A 503 pause refusal is not success: status stays `running`.
+- Filesystem-only resume is a reboot: in-memory state and processes are gone; do not auto-restart them.
+
+## Related APIs
+
+- [Coding execution approval and sandboxing](coding-security.md)
+- [Process sessions](process-sessions.md)
+- [Optional peer dependencies](peer-dependencies.md)
+- [Live testing](live-testing.md)