@arnilo/prism 0.0.96 → 0.1.0

package/docs/0.1.0-readiness.md

@@ -0,0 +1,202 @@
+# 0.1.0 / 1.0 Readiness Gates
+
+Status: **0.1.0** is the current release line (Phase 12 release-candidate hardening; plan 012); **1.0** readiness remains operator-gated, not automatic.
+
+This page distills runnable readiness gates into one command-per-gate table.
+The **Last evidence** column records the 0.1.0-tree snapshot (plan 012 Tasks
+0–7, Node v24.18.0, Linux x86_64) with the 2026-07-26 **0.0.16** values kept
+as the historical floor where the baseline predates it. Re-run each gate on
+the release tree before cutting 1.0. The decision to cut 1.0 stays with the
+operator after operator-gated legs run in a protected environment and Phase
+12 demand evidence exists.
+
+Evidence trail: [`docs/review-coverage-2026-07-26-phase-11.md`](./review-coverage-2026-07-26-phase-11.md)
+(addenda 0–9), [`docs/release-and-install.md`](./release-and-install.md),
+[`docs/migration.md`](./migration.md), [`docs/performance.md`](./performance.md),
+[`docs/public-contracts.md`](./public-contracts.md) (frozen 0.1.x contract).
+Historical release lines (0.0.16 floor → 0.0.27 Phase 10 ACP interop → 0.1.0)
+keep their per-phase evidence in the pages above; this page records the 0.1.0 snapshot.
+
+## Current line (0.1.0)
+
+| Item | Status |
+|---|---|
+| Published graph | **48** publishable manifests at exact **0.1.0** (root + 48 workspace packages; `docs/release-and-install.md`) |
+| Phase 12 RC hardening | Freeze manifest (`scripts/phase12-freeze-manifest.json`): no new packages/exports/migrations/dependencies, additive-only compat promise vs `scripts/compat-baseline`; compatibility/support matrix machine-checked (Node 20+24 measured, PostgreSQL 16, linux-x64, protocol SDK pins) |
+| Upgrade path | `docs/migration.md` `0.0.28 → 0.1.0` (no migration) + full `0.0.17 → 0.1.0` upgrade matrix (compatible / tested migration / tested refusal per release line) |
+| Packed-install e2e journeys | enterprise + coding journeys install the exact packed 0.1.0 manifest graph into fresh consumers (`scripts/e2e-*-journey.test.mjs`, in `npm test`) |
+| Protected restart-recovery evidence | `npm run test:postgres` includes `scripts/phase12-restart-recovery.test.mjs` (multi-replica kill/resume, unknown-outcome window, DB restart during streaming, reconnect/contention p95 vs frozen ceilings) |
+| Capacity envelopes | `scripts/benchmark-0.1.0.json` — 24 network-free + 16 protected p95 rows under the frozen 0.1.0 contract, re-gated on every `npm test` |
+| Security policy | `npm audit --audit-level=moderate` enforced in workflows; named threat-suites leg (`npm run security:threat-suites`); supply-chain negative fixtures in `scripts/release-gate.test.mjs` |
+| Docs freeze | every public page, package README, and changelog consistent with 0.1.0 behavior; tripwires green (121/121) |
+| Readiness table below | **0.0.16 measured values** remain the historical network-free floor; 0.1.0 evidence is recorded per row |
+
+## Gate table
+
+| Gate | Command | Last evidence (0.1.0 tree; 0.0.16 floor where noted) | Owner |
+|---|---|---|---|
+| Full quality gate | `npm run sdk:ready` | RC=0 at 0.1.0: typecheck (+examples), lint 0, format clean, full test, coverage, pack, release:gate (clean-checkout run is part of the operator release checklist) | CI |
+| Exact version graph | `node scripts/release.mjs check --version 0.1.0` | pass at 0.1.0: exact versions/ranges/lockfile/access + registry-collision check, **49** manifests | CI + operator |
+| Frozen public API surface + compat gate | `node scripts/release.mjs gate` | 0 breaks / 0 errors vs checked-in baselines (`scripts/compat-baseline/`); additive-only delta (empty at the 0.0.28 → 0.1.0 bump) | CI |
+| Migration coverage + docs tripwires | `node --test dist/__tests__/docs.test.js` | 121/121 at 0.1.0; `docs/migration.md` sections tripwired per release line | Maintainer |
+| Deterministic artifact budget | `node --test dist/__tests__/budget-gate.test.mjs` | root 713.5 kB packed / 2.1 MB unpacked / 295 files within +5% of the regenerated 0.1.0 baseline; startup < 250 ms | CI (in `npm test`) |
+| **0.1.0 capacity envelope (frozen performance contract)** | `node --test scripts/benchmark-0.1.0.test.mjs` | **`scripts/benchmark-0.1.0.json`** re-gated on every `npm test`: 24 network-free p95 rows ≤ frozen ceilings, 16 protected PostgreSQL rows ≤ budgets.json ceilings (50/100 ms), startup 41.7 ms < 250 ms, root pack within ±5%; regenerate with `node scripts/benchmark-0.1.0.mjs --out scripts/benchmark-0.1.0.json` (+ `PRISM_TEST_POSTGRES_URL` for protected legs) | CI (in `npm test`) |
+| Performance benchmark medians | `node scripts/benchmark-0.1.0.mjs --out scripts/benchmark-0.1.0.json` (+ `PRISM_TEST_POSTGRES_URL` for the 16 protected rows) | envelope re-recorded at 0.1.0 (see capacity-envelope row above); historical phase medians remain in `docs/performance.md` | On-demand release evidence |
+| Secret scan | `node scripts/scan-secrets.mjs` | 0.1.0 tree: 0 findings (3,095-file 0.0.16 floor) | CI |
+| License / SBOM | `node scripts/verify-sbom.mjs` | 0.1.0 tree: 317 locked packages, allow-listed licenses (227/12 at 0.0.16 floor) | CI |
+| Dependency audit | `npm audit --audit-level=moderate` | rc=0 (0 moderate+, 2 moderate at 0.0.16 baseline); 0 vulns at every severity for the 0.1.0 tree | CI |
+| Whitespace hygiene | `git diff --check` | clean | CI |
+| Publish order + tarball validation | `node scripts/release.mjs publish --version 0.1.0 --dry-run --allow-dirty --allow-untagged` | 49/49 packages `dry-run` twice with byte-identical reports, deterministic dependency order, no failures (Task 7) | Operator (dry-run), CI |
+| Node 20 compatibility | CI `node20-compat` (build + public-import smoke) | all 21 root exports import cleanly on Node 20.20.2 | CI |
+| PostgreSQL suite | `PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres` | 0.1.0: Phase 7 conformance + Phase 12 restart-recovery + 74 workspace checks green against PostgreSQL 16 (Task 4 recording, re-run green at 0.1.0 on 2026-08-09); operator-gated | Operator |
+| Keychain suite | `PRISM_TEST_KEYCHAIN=1 npm test --workspace @arnilo/prism-credentials-node` (protected) | 28/28 green incl. native keychain round-trip against the OS secret-service backend (gnome-keyring, 2026-08-09) | Operator host |
+| Live-provider suites | `npm run test:live` (protected) | **operator-gated** (requires credentials; `live-canaries.yml` blocked gate, `canary-report.json` retained) | Operator |
+| SAST | GitHub CodeQL | **operator-gated** (runs in CI workflow) | CI |
+| Signed, provenance publication | `npm run release:publish` (clean tagged tree, OIDC) | **operator-gated** (see "Remaining for 1.0") | Operator |
+
+## Frozen public API surface
+
+The compat gate diffs every package's generated `.d.ts` export surface against
+checked-in baselines in `scripts/compat-baseline/` (one file per package,
+regenerated at 0.1.0). It fails on any **removed** export or changed
+declaration; additive exports are allowed. `scripts/release-gates.mjs` also
+enforces a tarball deny list (no reviews/plans/maps/tests/binaries/credential
+material in published artifacts) and exact version-range drift. A genuine break
+requires `--allow-break` **and** a `docs/migration.md` entry mentioning the
+version. The frozen 0.1.x contract (declaration/exports, events, protocol
+payloads, migration checksums, patch-release compatibility promise) is
+published in [docs/public-contracts.md](public-contracts.md).
+
+**Baseline maintenance:** `scripts/compat-baseline/` must stay committed.
+Regenerate only after review with `node scripts/release.mjs gate --update-baseline`,
+having first confirmed zero removed exports (the gate's order-sensitive
+signatures can drift on a TypeScript bump without any real API change).
+
+## Migration coverage
+
+`docs/migration.md` carries release migration sections tripwired by
+`docs.test.ts` (headings and key phrases). A missing or gutted section fails
+the suite. **0.0.19** adds observational-memory lifecycle and nested settings in
+`@arnilo/prism-compaction-observational-memory` — see `0.0.18 → 0.0.19 observational memory lifecycle`.
+**0.0.18** adds intentional pre-1.0 breaks (`repo_search` literal-only,
+`cache_aware` default layout, oldest-first history eviction, atomic write/edit
+durability, MCP SDK bump) — see `0.0.17 → 0.0.18 restore integrity`.
+
+## Budget table
+
+Deterministic budgets (CI gate, `scripts/budget-gate.test.mjs`):
+
+| Metric | Baseline | Tolerance | 0.1.0 measured |
+|---|---|---|---|
+| Root packed bytes | 713,454 (regenerated 0.1.0, dev-001) | +5% | 713.5 kB (within) |
+| Root unpacked bytes | 2,388,118 | +5% | within |
+| Root file count | 293 (regenerated 0.1.0, dev-001) | +5% | 295 (within) |
+| Cold-startup import | 41.7 ms | ceiling 250 ms | within |
+
+Baselines are the 0.1.0 snapshot (`scripts/budgets.json`, amended once by
+freeze deviation dev-001 for the Task 1–5 evidence scripts); raise them only
+after a deliberate reviewed performance change.
+
+## Live-suite matrix (operator-gated)
+
+| Suite | Command | Environment |
+|---|---|---|
+| PostgreSQL persistence | `npm run test:postgres` | live PostgreSQL |
+| Keychain credentials | protected live suite | OS keychain |
+| Provider live-canary (OpenAI/Anthropic/Google/Kimi/Ollama/…) | protected live-canary matrix | vendor credentials |
+| RAG / memory / workflows live journeys | protected live-canary matrix | vendor + DB credentials |
+| Enterprise adapters live canary (Phase 11: real OIDC IdP/JWKS, real OPA endpoint, real MCP OAuth authorization server, S3-compatible object store) | protected live-canary matrix | IdP / policy / object-store credentials |
+
+These do not run on a contributor machine; their evidence is recorded in the
+protected environment, never faked. Phase 11 live-endpoint evidence is a
+**blocked release gate, not a passing skip**: `npm test` proves the seams
+against network-free fake servers (`scripts/phase11-conformance.test.mjs`),
+and the live matrix above stays blocked until the protected environment
+records it.
+
+## Packed-install e2e journeys (plan 012 Task 3)
+
+| Journey | Command | Environment |
+|---|---|---|
+| Enterprise: OIDC identity → OPA policy decision → agent run with durable events → batched approval → OpenAPI side effect with idempotency → artifact upload + signed delivery | `npm test` (scripts/e2e-enterprise-journey.test.mjs) | network-free (memory stores, loopback fake servers); PostgreSQL leg when `PRISM_TEST_POSTGRES_URL` is set |
+| Coding: ACP editor session (init capability negotiation, session new + load/resume) → bounded coding tools (git-aware list/search, glob, read-before-write write, delete, move) → sandboxed process session → forge handoff | `npm test` (scripts/e2e-coding-journey.test.mjs) | network-free (fake GitHub + git runner) |
+
+Both install the exact packed manifest graph into a fresh consumer (`npm pack`
+tarballs, never workspace paths) and run the journey against only public
+exports. Each fixture ends with a success marker (`ENTERPRISE JOURNEY OK` /
+`CODING JOURNEY OK`) that the test asserts. Runtime is bounded by
+`e2eJourneyFixtureMsCeiling` in `scripts/phase12-freeze-manifest.json` (120 s
+per fixture).
+
+## Protected restart-recovery evidence (plan 012 Task 4)
+
+| Leg | Command | Environment |
+|---|---|---|
+| Multi-replica kill/resume: replica A runs a durable agent (PostgreSQL checkpoints + durable events), suspends on a batched tool approval, and is SIGKILLed; replica B resumes with no event gap/duplicate, exactly-once durable tool effects, partial-approval re-suspend with CAS, and ownership rechecks | `npm run test:postgres` (scripts/phase12-restart-recovery.test.mjs) | live PostgreSQL 16 |
+| Tool-effect unknown-outcome window: a dispatched-and-expired claim replays as `ERR_PRISM_TOOL_EFFECT_UNKNOWN` (reconciliation demanded), never a silent double-apply | `npm run test:postgres` (same suite) | live PostgreSQL 16 |
+| Database restart during streaming: terminated LISTEN backend recovers by polling (missed event delivered, no gap) | `npm run test:postgres` (Phase 7 + Phase 12 legs) | live PostgreSQL 16 |
+| Reconnect p95 + append contention p95 recorded against frozen ceilings (`reconnectP95Ms`, `pointOpP95Ms` in `scripts/phase12-freeze-manifest.json`) | `npm run test:postgres`; evidence in `scripts/phase12-restart-recovery.json` | live PostgreSQL 16 |
+
+Missing `PRISM_TEST_POSTGRES_URL` is a **named, visible blocked gate**: `npm run
+test:postgres` fails at `scripts/require-postgres-url.mjs`, and running the
+suite directly records a `BLOCKED GATE` failure instead of a passing skip.
+Durable ACP session registries and sandbox process sessions stay host-owned
+by design (Prism provides the durable agent-run lifecycle underneath); the
+coding journey and Phase 9/10 conformance suites cover their in-process
+semantics, and the legs above prove the durable restart classes.
+
+## Security matrix
+
+| Control | Command / source | 0.0.16 baseline |
+|---|---|---|
+| Secret scan | `node scripts/scan-secrets.mjs` | 3095 files / 0 findings |
+| License / SBOM | `node scripts/verify-sbom.mjs` | 227 packages / 12 licenses, allow-listed |
+| Dependency audit | `npm audit --audit-level=moderate` | 0 high (2 moderate) at 0.0.16; **0 vulnerabilities at every severity for the 0.1.0 tree** (317 locked deps; MCP SDK 1.30.0 fix baseline) |
+| SAST | GitHub CodeQL workflow | CI-gated |
+| Sandbox / protocol / tenant threat suites | `npm test` (coding-security, MCP, policy, guardrail suites) | green at 0.0.16 |
+| **0.1.0 threat-suites leg** | `npm run security:threat-suites` (Phase 8–11 conformance) + `npm run test:postgres` (Phase 7 tenant leg, blocked gate without URL) | 28/28 network-free at 0.1.0 recording |
+| **Supply-chain negative fixtures** | `scripts/release-gate.test.mjs` | tampered tarball content, unexpected file types/credential material, and suppressed-provenance-in-CI all detected |
+| Signed deterministic publication | `release.mjs publish` on clean tagged tree | operator-gated |
+
+## Remaining for 1.0 (operator / protected environment)
+
+Exact prerequisites that must be satisfied before cutting 1.0 (the 0.1.0
+publication itself is the same list minus the 1.0-specific items):
+
+1. **Signed tag + commits:** create and sign `v1.0.0` on a clean tree;
+   `release.mjs publish` refuses real publication with `--allow-dirty`
+   or `--allow-untagged` (verified: the 0.1.0 dry-run proceeds only with
+   both flags, the real run always refuses).
+2. **npm authentication + OIDC provenance/attestation:** publish with
+   `--provenance` and `--access public` from the protected registry identity
+   (the 0.1.0 publication is the first exercise of this operator step;
+   `publishArgs` derives `--provenance` from `GITHUB_ACTIONS` and the
+   release workflow holds `id-token: write` + `attestations: write`).
+3. **Protected live-canary matrix green:** provider/RAG/memory/workflows live
+   journeys pass with real credentials (`live-canaries.yml` — blocked gate,
+   never a silent skip).
+4. **PostgreSQL + keychain protected suites green.**
+5. **CodeQL SAST green** on the release commit.
+6. **`scripts/compat-baseline/` committed** (frozen 0.1.x baselines are
+   already checked in).
+7. **Phase 12 demand evidence** (below) recorded for any capability that 1.0
+   is expected to anchor.
+8. **0.1.0 lifecycle gates green** on the release candidate (docs suite,
+   audit at moderate, coding-tool durability, layout/eviction defaults) —
+   recorded in this page at 0.1.0.
+
+## Phase 12 demand-evidence entry criteria
+
+Phase 12 (demand-gated 0.1.x) promotes no capability on comparison-table parity
+alone. Each candidate must present, before it becomes a numbered plan:
+
+- **Named user** (a concrete person/team who will use it),
+- **Concrete integration** (the real system it connects to),
+- **Operational owner** (who runs and pages for it),
+- **Measurable acceptance criteria** (scale/cost/latency/storage budgets that
+  do not expand default core/install/runtime cost),
+- then the pipeline: demand evidence → primitive review → threat model →
+  optional package/service → conformance → release gate.
+
+The readiness gates above are the stable API/compat/budget/security floor that
+Phase 12 capabilities must consume and must not regress.

package/docs/a2a.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-supervisor` implements bounded A2A 1.0 over the JSON-RPC/HTTPS binding. Supported operations: `SendMessage`, `SendStreamingMessage`, `GetTask`, `ListTasks`, `CancelTask`, `SubscribeToTask`, push-notification-config create/get/list/delete, and `GetExtendedAgentCard`. Agent Cards retain explicit ES256 verification. gRPC, HTTP+JSON, discovery registries, automatic JWK/OAuth fetching, and an internal task worker/store are absent.
+`@arnilo/prism-supervisor` implements bounded A2A 1.0 over the JSON-RPC/HTTPS binding. Supported operations: `SendMessage`, `SendStreamingMessage`, `GetTask`, `ListTasks`, `CancelTask`, `SubscribeToTask`, push-notification-config create/get/list/delete, and `GetExtendedAgentCard`. `client.streamMessage()` additionally exposes verified rich task/message events for frontend adapters while legacy `stream()` remains text-compatible. Agent Cards retain explicit ES256 verification. gRPC, HTTP+JSON, discovery registries, automatic JWK/OAuth fetching, and an internal task worker/store are absent.
 
 ## When to use it
 
@@ -39,6 +39,30 @@ const handler = createA2AHandler({
 
 Parts, messages, artifacts, histories, metadata, and aggregate responses are untrusted. Rich content remains in A2A task/message/artifact contracts for host mapping; it is never promoted to system instructions or automatically loaded as a Prism resource.
 
+## AG-UI server-side exposure (Task 13, 0.0.26)
+
+`createAgUiA2AServer()` in `@arnilo/prism-ag-ui` fronts one host-selected **local AG-UI agent** as an A2A 1.0 server, the reverse direction of `createAgUiA2AAdapter()`: remote A2A clients start and stream local runs through the same AG-UI input allow-list and event mapper as the AG-UI SSE path (same projection, redaction, and byte caps). It reuses this package's `createA2AHandler` transport/lifecycle; it creates no second runtime, task store, or worker. Requires the optional `@arnilo/prism-supervisor` peer (imported lazily; plain `@arnilo/prism-ag-ui` imports keep working without it).
+
+```ts
+import { createAgentEventSourceAgUiReplay, createAgUiA2AServer } from "@arnilo/prism-ag-ui";
+
+const server = await createAgUiA2AServer({
+  card: agentCard,                                   // A2A agent card (streaming: true)
+  authorize: (input) => authorizeA2A(input),         // A2A auth → { ownership } (also the AG-UI authorization)
+  sessionFactory: ({ threadId, authorization, signal, input }) =>
+    createAgUiSession(authorization, input),         // same shape as createAgUiHandler
+  input: { project: projectAgUiInput },              // AG-UI full-input allow-list
+  projection, redactor, a2ui, limits,                // AG-UI mapper options
+  durable: {                                         // optional: GetTask/SubscribeToTask after a run finishes
+    source: persistence.events,                      // durable AgentEventSource
+    resolveTask: async ({ id, authorization }) => ({ task, run }), // host-owned task→run correlation
+  },
+});
+// host mounts: new Request(url, init) → server(request)
+```
+
+Semantics: `SendMessage` runs the local agent to completion and returns a terminal task with collected text artifacts; `SendStreamingMessage` (client `returnImmediately: true`) streams text/activity/state as bounded A2A artifact updates, then a terminal task. `agent_suspended` closes the stream with `TASK_STATE_INPUT_REQUIRED`; continuation stays host-owned (AG-UI resume). `GetTask`/`ListTasks`/`CancelTask` cover a bounded in-memory registry of tasks started on this instance; with `durable`, `SubscribeToTask`/`GetTask` also resolve host-correlated runs and replay the durable source with cursor event ids (at-least-once; clients dedupe by `eventId`). Text parts become the AG-UI user message; raw/data/url parts stay disabled unless `parts` selects them, and then arrive only in `forwardedProps.a2a` for `input.project`. Task ids default to `task-<uuid>`; hosts may own them via `selectTaskId`. `tasks` may be supplied to replace the built-in lifecycle entirely. A2A remains separately mounted — no route is added to `createPrismHandler()`.
+
 ## Implementation example
 
 ```ts
@@ -59,12 +83,15 @@ Streams use ordered SSE frames with `id:` and JSON-RPC `result` containing one `
 Client APIs:
 
 - `send()` / `stream()` preserve text-to-`AgentRunResult` compatibility.
+- `streamMessage(message)` exposes bounded verified `A2AStreamEvent` task/message records without discarding artifact/data parts.
 - `sendMessage()` returns rich/durable `A2ATask`.
 - `getTask()`, `listTasks()`, `cancelTask()`, `subscribeToTask()` operate on durable tasks.
 - `createPushConfig()`, `getPushConfig()`, `listPushConfigs()`, `deletePushConfig()` expose declared push config operations.
 
 Every protocol request sends/negotiates `A2A-Version: 1.0`. Client endpoint/card URLs require exact allow-listed HTTPS and `redirect: "error"`. Cards are parsed then optionally verified against host-pinned keys; no key URL is fetched.
 
+`createA2AAgentEventSource({ source, resolveTask, map })` supplies only the durable `subscribe` seam for a host-owned `A2ATaskLifecycle`. It resolves task→exact Prism run under authorization, consumes `AgentEventSource.subscribe()`, and uses each opaque source cursor as stable A2A `eventId`. With no cursor, the first mapped update must be a full Task, matching A2A streaming rules. It creates no task store or worker. Standard `SubscribeToTask` has no `afterEventId`; Prism retains that bounded field as an explicitly documented reconnect extension.
+
 ## Request/response example
 
 ```json
@@ -73,13 +100,14 @@ Every protocol request sends/negotiates `A2A-Version: 1.0`. Client endpoint/card
 
 ## Extension and configuration notes
 
-Handler requires `card.capabilities.pushNotifications` to exactly match supplied `push`; mismatch fails construction, preserving signed-card integrity and preventing false capability claims. Streaming remains available for direct text invocation. Push adapter owns exact-owner persistence, signing/auth credentials, and network transport. Host explicitly calls `deliverA2APushEvent()` from its durable update path; helper bounds event, timeout (10s default/60s hard), attempts (1 default/3 hard), and passes stable event ID as idempotency key to host `A2APushDelivery`. It starts no hidden sender and performs no network itself. Config handling validates IDs/count/bytes and requires same explicit URL policy used for URL parts. Returned push configs omit token and authentication credentials.
+Handler requires `card.capabilities.pushNotifications` to exactly match supplied `push`; mismatch fails construction, preserving signed-card integrity and preventing false capability claims. `createAgUiA2AAdapter({ client, select, correlate, projectPart })` in `@arnilo/prism-ag-ui` fronts one host-selected verified client: host selects new/follow task mode, persists exact run/thread/task correlation before output, and may project non-text/tool/A2UI parts. It never discovers agents, opens a local session, or replaces this direct A2A API. Streaming remains available for direct text invocation. Push adapter owns exact-owner persistence, signing/auth credentials, and network transport. Host explicitly calls `deliverA2APushEvent()` from its durable update path; helper bounds event, timeout (10s default/60s hard), attempts (1 default/3 hard), and passes stable event ID as idempotency key to host `A2APushDelivery`. It starts no hidden sender and performs no network itself. Config handling validates IDs/count/bytes and requires same explicit URL policy used for URL parts. Returned push configs omit token and authentication credentials.
 
 Defaults/hard caps include: request 64 KiB/1 MiB; response 1/8 MiB; event 64 KiB/1 MiB; stream 10/64 MiB and 10k/100k events; replay 1k/10k events; concurrency 16/256; timeout 120s/30m; IDs 256/4096 B; parts 32/256; part/raw 1/8 MiB; data 256 KiB/4 MiB; artifacts 32/256; history/page 100/1000; cursor 4/16 KiB; push configs 10/100. Hosts may narrow limits.
 
 ## Security and performance notes
 
 - Authorize every operation; lifecycle/push adapters enforce exact owner again at durable storage boundary. Missing and foreign tasks/configs share `-32001`.
+- Optional `A2AAuthorization.identity` is host-verified; the handler asserts activity/ownership match and forwards identity into `session.run`. Cross-tenant or widened scopes fail closed.
 - URL policy must reject private, loopback, link-local, rebound, redirected, or otherwise disallowed destinations. Package never fetches file URLs. Host push delivery must repeat equivalent checks for every attempt/redirect and process event IDs idempotently.
 - Push token/auth credentials are accepted only into host adapter input and removed from protocol reads/responses. Keep them out of task parts, events, telemetry, ledgers, and errors.
 - Known-secret redaction applies before handler JSON/SSE output. Client redacts mapped text/errors. Raw/data/url content remains explicitly untrusted.
@@ -88,7 +116,10 @@ Defaults/hard caps include: request 64 KiB/1 MiB; response 1/8 MiB; event 64 KiB
 
 ## Related APIs
 
+- [Agent identity](agent-identity.md)
 - [Supervisor delegation](supervisors.md)
 - [Agent/session runtime](agent-session-runtime.md)
 - [Workflows](workflows.md)
 - [Host security](host-security.md)
+- [Frontend interoperability (AG-UI and ACP)](ag-ui.md): browser/editor protocol adapters over a Prism session; not an A2A card, task lifecycle, or remote-agent transport.
+- [AG-UI adoption evaluation](ag-ui-adoption.md): official AG-UI A2A fronting assessment and shipped explicit adapter.

package/docs/acp.md

@@ -0,0 +1,126 @@
+# Agent Client Protocol (ACP) coding-host interop
+
+## What it does
+
+`@arnilo/prism-ag-ui/acp` (stable ACP **v1**, `@agentclientprotocol/sdk@1.3.0` root exports only) exposes two adapters:
+
+- `createPrismAcpAgent(options)` — serves ACP as an **agent**: an editor/AI client connects through the SDK transport and drives host-owned Prism sessions with `session/new`, `session/load`, `session/resume`, `session/prompt`, `session/set_mode`, `session/set_config_option`, `session/list`, `session/delete`, `session/close`, and `session/cancel`. The agent is a thin protocol adapter: every capability, decision, and byte cap is wired from host seams, and there is **no second policy engine** on the agent side.
+- `createAcpEventMapper(options)` — maps a Prism `AgentEvent` stream (or `CoWorkEvent`) to ACP `SessionUpdate`s for hosts that stream through their own transport.
+
+The adapter builds on the Phase 8/9 shared machinery: redacted event projection (`AgUiProjection`), the durable pending-decision batch model (`allow_once` / `allow_for_run` / `reject_once` / `reject_for_run`), `AgentRunLifecycle` resume, `CodingLifecycleEvent` emission, and the AG-UI/ACP package caps. It never ships experimental ACP v2 or UNSTABLE fields (`providers`, `nes`, `positionEncoding`, `sessionCapabilities.fork`, `mcpCapabilities.acp/auth`, `elicitation` is consumed client-side only and never advertised).
+
+## When to use it
+
+Use `createPrismAcpAgent` when an editor/AI client already speaks ACP and you want it to reach host-owned Prism runs: text streaming, safe tool status, usage, four-outcome approvals, session persistence, modes, config options, and — when the client advertises them — editor-buffer filesystem (`fs/read_text_file`, `fs/write_text_file`) and terminal (`terminal/create` … `terminal/kill`) client methods, plus prompt media (`image`, `audio`, `embeddedContext`) and `elicitation` decisions.
+
+Do **not** use it when the host needs a browser/TUI Web endpoint (use [AG-UI](ag-ui.md)), remote agent-to-agent tasks ([A2A](a2a.md)), or a full editor integration — ACP is a protocol adapter, not an editor, a TUI, or a credential provider.
+
+## Inputs / request
+
+`createPrismAcpAgent(options: CreatePrismAcpAgentOptions)` — every field is host-supplied:
+
+| Option | Shape | Effect |
+|---|---|---|
+| `authorize` | `(input) => AcpAuthorization \| Promise` | **Required.** Ownership/identity gate for every inbound call, scoped by `sessionId`; unknown sessions fail. |
+| `sessionFactory` | `(input) => AcpSessionBinding \| Promise` | **Required.** Builds the Prism `AgentSession` for `session/new`. Input carries `authorization`, `cwd`, `additionalDirectories`, `mcpServers` (policy-checked), `signal`, optional pre-generated `sessionId`, and `coding` (built client fs/terminal adapters when the client advertised them). |
+| `lifecycle` | `AgentRunLifecycle` | **Required.** `status`/`resume`/`resumeStream` for durable `session/load` and `session/resume`. |
+| `sessions?` | `AcpSessionStoreSeams` | `load` (advertises `sessionCapabilities.loadSession`), `list` (list), `delete` (delete), `resume` (resume), `additionalDirectories` (policy narrowing of `additionalDirectories`). `close` is always advertised. |
+| `mcp?` | `AcpMcpSeams` | `transports: ("http" \| "sse")[]` and `select({ servers, signal })` — **required** for any client-supplied MCP server; select must approve before the bridge connects. Advertises `mcpCapabilities.http`/`sse` per transport. |
+| `modes?` | `{ modes: AcpSessionMode[], defaultModeId? }` | `AcpSessionMode { id, name, description?, apply? }`; `apply({ sessionId?, fromModeId?, modeId, signal })` is the host hook run on switch. Advertised in `SessionModeState` on new/load/resume; enables `session/set_mode`. |
+| `configOptions?` | `{ options: AcpConfigOption[], onChange? }` | `boolean`/`select` options with `defaultValue`; enables `session/set_config_option` (requires the client to advertise `session.configOptions.boolean`). |
+| `capabilities?` | `AcpCapabilitiesOptions` | `prompt.media`/`prompt.embedded` policy seams, re-checked **live at prompt time**; presence advertises `promptCapabilities.image`/`audio`/`embeddedContext`. |
+| `coding?` | `AcpCodingSeams` | `filesystem(client, sessionId)` / `processes(client, sessionId)` factories building `AcpClientFilesystem` / `AcpClientTerminals` over client methods; `lifecycle?: CodingLifecycleEmitter` subscribes `CodingLifecycleEvent`s into ACP updates. |
+| `name?` | `string` | `agentInfo.name` (default `"Prism"`). |
+
+Client capabilities are read at `initialize` and gate **client-method use**, not advertisement: `fs.readTextFile`/`writeTextFile` gate the fs seam, `terminal` the processes seam, `session.configOptions.boolean` the config path, `elicitation` the elicitation route.
+
+## Outputs / response / events
+
+`initialize` returns `{ protocolVersion, agentCapabilities, agentInfo }`; `agentInfo.version` comes from the package manifest. Advertised capability = a host seam is wired (pure function, no hand-maintained matrix): `loadSession`/`sessionCapabilities.*` iff the matching `sessions` seam exists (`close` always), `promptCapabilities.*` iff the matching `capabilities.prompt` seam exists, `mcpCapabilities.*` iff `mcp.select` + the transport are wired. Unadvertised agent methods fail naturally with JSON-RPC `-32601`; unadvertised client methods are never called.
+
+In-stream `SessionUpdate`s:
+
+| Prism event | ACP update |
+|---|---|
+| Assistant text | `agent_message_chunk` |
+| Tool lifecycle | `tool_call` / `tool_call_update` (title/status/content) |
+| Tool result, projected | `tool_call_update` with `locations` (≤ `acpLocationsPerUpdate`) and/or a `diff` block (≤ `acpDiffBytes`) — only from `AgUiProjection.toolLocations`/`toolDiff` allow-lists, at `finish()` |
+| Provider usage / errors | `usage_update`, `error` |
+| Durable suspension | `session/request_permission` with the four outcomes `allow_once` / `allow_for_run` / `reject_once` / `reject_for_run`; cancel, unknown options, and request failure deny. Sticky decisions expire at run end. |
+| Elicitation suspension (all-elicitation batch + client advertised `elicitation`) | `elicitation/create` (form mode, bounded schema, redacted reason); `accept` → `allow_once` with the typed payload as `RunDecision.elicitation`, `decline`/`cancel` → `reject_once`. Otherwise falls back to the shared four-option permission path. |
+| `file_changed` lifecycle | `tool_call_update` with `locations: [{ path }]` (needs a `toolCallId`; diff only from `fileDiff` allow-list, capped + redacted) |
+| `worktree_changed` / process events | Projection-gated `agent_message_chunk` (deny-by-default: no `lifecycle` projection hook = no update) |
+| `permission_denied` lifecycle | `tool_call_update` status `failed` (never raw args; synthesized id `prism:denied:<approvalId>` when no `toolCallId`) |
+| `configuration_changed` lifecycle | `config_option_update` with the full current set, per streaming session |
+| Session mode/config switch | `current_mode_update` / `config_option_update` |
+
+Frozen caps (default / hard, from the Phase 10 freeze manifest): sessions 32/128, additional directories 8/32 (path 4 KiB/16 KiB), MCP servers 8/32 (config 16 KiB/256 KiB, header values 4 KiB/64 KiB), modes 16/64, config options 16/64, list page 20/100, diff bytes 64 KiB/1 MiB, locations per update 32/128, prompt media parts 16/64 and media bytes 64 KiB/1 MiB (shared AG-UI caps), terminal output chunks 51200 B/1 MiB (Phase 9 `process.outputChunkBytes`), stream events/bytes per AG-UI budgets. `session/load`/`session/resume` of a still-registered session rejects with `ERR_PRISM_ACP_INPUT` ("ACP session already exists"); model reconnect as resume of a pre-seeded stored session.
+
+Errors surface as `AcpError` with codes `ERR_PRISM_ACP_INPUT` (malformed), `ERR_PRISM_ACP_LIMIT` (caps), `ERR_PRISM_ACP_POLICY` (host denied), `ERR_PRISM_ACP_CAPABILITY` (not advertised), `ERR_PRISM_ACP_MCP` (MCP bridging). Over the wire they become JSON-RPC `-32603` with the message in `data.details` (SDK behavior).
+
+## Request/response example
+
+```json
+// initialize → agentCapabilities (all seams wired)
+{
+  "protocolVersion": 1,
+  "agentCapabilities": {
+    "loadSession": {},
+    "sessionCapabilities": { "list": {}, "delete": {}, "additionalDirectories": {}, "resume": {}, "close": {} },
+    "promptCapabilities": { "image": true, "audio": true, "embeddedContext": true },
+    "mcpCapabilities": { "http": true, "sse": true }
+  },
+  "agentInfo": { "name": "Prism", "version": "0.0.27" }
+}
+
+// session/new response (modes + configOptions wired)
+{ "sessionId": "acp-9f1c…", "modes": { "currentModeId": "edit", "availableModes": [{ "id": "edit", "name": "Edit" }] },
+  "configOptions": [{ "type": "boolean", "id": "verbose", "name": "Verbose", "defaultValue": false, "currentValue": false }] }
+```
+
+## Implementation example
+
+See [`examples/acp-coding-host.ts`](../examples/acp-coding-host.ts) (runs in the demo gate). The host owns all state and policy:
+
+```ts
+import { createPrismAcpAgent } from "@arnilo/prism-ag-ui/acp";
+
+const agent = createPrismAcpAgent({
+  authorize: ({ sessionId }) => (sessionId ? hostSessions.has(sessionId) : true)
+    ? { ownership: { userId: "host-user" } }
+    : false,
+  sessionFactory: (input) => ({ session: hostSessionFor(input) }), // Prism AgentSession
+  lifecycle: { status, resume, resumeStream },                     // durable
+  sessions: { load, list, delete, resume, additionalDirectories }, // capability seams
+  mcp: { transports: ["http", "sse"], select: ({ servers }) => approve(servers) },
+  modes: { modes: [{ id: "edit", name: "Edit" }, { id: "review", name: "Review", apply: narrow }], defaultModeId: "edit" },
+  configOptions: { options: [{ type: "boolean", id: "verbose", name: "Verbose", defaultValue: false }] },
+  capabilities: { prompt: { media: async () => true, embedded: async () => false } },
+  coding: { lifecycle, filesystem: clientFsAdapter, processes: clientTerminalAdapter },
+});
+// serve over the host's ACP transport: agent.connect(stream)
+```
+
+## Extension and configuration notes
+
+- **Seam = capability.** Wiring `sessions.load` advertises `loadSession`; removing it withdraws the method. There is no separate capability flag to keep in sync — the freeze manifest's advertise-when matrix is enforced by construction and asserted by `scripts/phase10-conformance.test.mjs`.
+- **Client fs/terminal are adapters, not a second implementation.** `AcpClientFilesystem` / `AcpClientTerminals` wrap the client's `fs/*` and `terminal/*` methods behind the Phase 9 `ProcessSession`-flavored interfaces; the agent pre-generates the session id so terminal requests can carry it. Host repo operations remain default when the client fs is absent.
+- **Modes and config options are a pure host overlay.** The agent stores only a thin per-session registry; `apply`/`onChange` hooks narrow the host's own behavior. Mode switches can narrow or host-authorized widen — never a parallel policy evaluator, never a client-enabled tool.
+- **Lifecycle wiring.** Pass your `createCodingLifecycleEmitter()` as `coding.lifecycle`; `file_changed` etc. then flow to streaming sessions. `configuration_changed` broadcasts `config_option_update` (agent-message fallback if the SDK rejects the kind).
+- **Stream budgets.** Every lifecycle update counts against the same per-run stream event/byte budget as prompt updates; overflowing closes the update, never the run.
+
+## Security and performance notes
+
+- **Untrusted client input.** Client-supplied paths, `additionalDirectories`, MCP server configs, terminal env/args, and media are validated at the boundary: count/byte caps, ownership-scoped sessions, path policy via the `sessions.additionalDirectories` seam, MCP servers only through host `select` (never auto-connected), UNSTABLE `acp` transport always rejected.
+- **Deny-closed by default.** Unknown mode ids, unadvertised methods, unprojected lifecycle events, oversize diffs/locations/media, thrown projection hooks, and failed elicitation all fail closed. Raw tool arguments/results are never sent unless a projection allow-list says otherwise.
+- **No secrets.** Updates carry no raw file bodies, terminal output is capped by the Phase 9 chunk budget, and the shared redactor is applied before anything leaves the host. `permission_denied` never includes raw args.
+- **Performance.** The adapter is O(1) per update with no unbounded buffering; p95 targets (fs round trip 250 ms, mode switch 250 ms, terminal chunk ack 1000 ms, prompt first update 2000 ms, prompt end 30 s) are recorded by `scripts/benchmark-0.0.27.mjs` and gated in `scripts/budgets.json` `phase10`.
+
+## Related APIs
+
+- [AG-UI](ag-ui.md): sibling frontend protocol; shared projection/redaction/caps and the same pending-decision model. This page is the full ACP reference.
+- [Coding agent tools](coding-agent-tools.md): the `CodingLifecycleEvent` source mapped here; `@arnilo/prism-coding-agent` `process.outputChunkBytes` caps terminal chunks.
+- [Agent events](agent-events.md): the durable `AgentEventSource`/replay story behind `session/load` and `session/resume`.
+- [Host security guide](host-security.md): fail-closed checklist rows for ACP boundaries (authorize, ownership, redaction, untrusted MCP).
+- [Migration guide](migration.md): 0.0.26 → 0.0.27 advertise/surface changes for hosts that parsed the old `initialize`.
+- [AG-UI adoption evaluation](ag-ui-adoption.md): the underlying input/event/capability matrix.

package/docs/ag-ui-adoption.md

@@ -0,0 +1,77 @@
+# AG-UI adoption evaluation
+
+## What it does
+
+This page records Prism's compatibility review against official AG-UI `@ag-ui/core` **0.0.57** and the official repository at commit [`a40b5c0`](https://github.com/ag-ui-protocol/ag-ui/commit/a40b5c0824564eb2f9ab9edf2be43f355f42a3b8). It separates shipped transport/replay support from remaining work needed to claim full AG-UI support, including AG-UI fronting MCP and A2A agents.
+
+Official material reviewed:
+
+- [Events](https://docs.ag-ui.com/concepts/events), [messages](https://docs.ag-ui.com/concepts/messages), [tools](https://docs.ag-ui.com/concepts/tools), [state](https://docs.ag-ui.com/concepts/state), [reasoning](https://docs.ag-ui.com/concepts/reasoning), [interrupts](https://docs.ag-ui.com/concepts/interrupts), [capabilities](https://docs.ag-ui.com/concepts/capabilities), [serialization](https://docs.ag-ui.com/concepts/serialization), [server quickstart](https://docs.ag-ui.com/quickstart/server), and [protocol architecture](https://docs.ag-ui.com/concepts/architecture).
+- Official [MCP/A2A/AG-UI relationship](https://docs.ag-ui.com/agentic-protocols), [integrations](https://docs.ag-ui.com/integrations), [`@ag-ui/mcp-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/mcp-middleware), [`@ag-ui/mcp-apps-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/mcp-apps-middleware), [`@ag-ui/a2ui-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/a2ui-middleware) (Prism ships an in-package opt-in painter with frozen caps; no runtime dependency), [`@ag-ui/a2a`](https://github.com/ag-ui-protocol/ag-ui/tree/main/integrations/a2a/typescript), and [`@ag-ui/a2a-middleware`](https://github.com/ag-ui-protocol/ag-ui/tree/main/middlewares/a2a-middleware).
+- A2A [current specification](https://a2a-protocol.org/latest/specification/) and [streaming rules](https://a2a-protocol.org/latest/topics/streaming-and-async/).
+- MCP Apps [SEP-1865](https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp) and the [`io.modelcontextprotocol/ui` draft specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx).
+
+## When to use it
+
+Use this matrix when selecting Prism for an AG-UI client or planning protocol work. Tasks 3A and 3B complete full AG-UI 0.0.57 request/event compatibility plus explicit hardened MCP, MCP Apps, and remote A2A fronting. These are opt-in adapters over existing Prism clients, not an alternate runtime or discovery path.
+
+## Inputs / request
+
+Official `RunAgentInput` fields—lineage, all message roles/history, state, tools, context, props, media, and resume—are schema/bound checked then have no authority until `input.project` returns host-selected messages. Client tools remain client handoffs; state/props/media never grant identity, ownership, or server tools. Resume is exact `${runId}:${version}` CAS; edited arguments deny.
+
+## Outputs / response / events
+
+Prism emits current standard lifecycle, step, text, tool, state, messages, activity, reasoning, raw, and custom families when its mapper or an explicit projector can prove them. Deprecated `THINKING_*` and convenience chunk output are intentionally absent. SSE is baseline; capabilities truthfully narrow to configured replay/projectors/lifecycle, and source cursors remain bounded `prismCursor` metadata for reconnect.
+
+## Request/response example
+
+```json
+{
+  "type": "TEXT_MESSAGE_CONTENT",
+  "messageId": "message-1",
+  "delta": "hello",
+  "prismEventId": "event-42",
+  "prismCursor": "opaque-owner-run-bound-cursor"
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgentEventSourceAgUiReplay, createAgUiHandler } from "@arnilo/prism-ag-ui";
+
+const replay = createAgentEventSourceAgUiReplay(persistence.events, {
+  resolveRun: hostResolveProtocolRun,
+  ownership: (authorization) => authorization.ownership,
+});
+
+const handle = createAgUiHandler({ authorize, sessionFactory, lifecycle, resolveRun, replay });
+```
+
+## Extension and configuration notes
+
+### A2A adoption
+
+A2A stays separately mounted. `createA2AAgentEventSource()` maps durable runs to task events; `afterEventId` remains Prism-only.
+
+`createAgUiA2AAdapter({ client, select, correlate, projectPart })` fronts one verified host-selected client: task text/status becomes AG-UI text/activity, correlation persists before output, and non-text/tool/A2UI needs a schema-validated projector. It uses streaming when declared; fallback accepts only a terminal task. Client origin/card/auth/bounds/abort checks remain active.
+
+### MCP adoption through AG-UI
+
+Prism adapts its hardened MCP bridge; no official middleware or second runtime. `connectMcpTools({ mcpApps: true })` requires `io.modelcontextprotocol/ui` acknowledgement, retains nested UI metadata over deprecated flat metadata, hides app-only tools, and bounds linked `ui://` HTML through `bridge.apps`. `createAgUiMcpAdapter()` selects model-visible tools for normal core dispatch; `createAgUiMcpAppHandler()` reauthorizes one-bridge initialize/ping/logging/tool/resource calls with approval and visibility; sandbox helper returns fixed iframe/CSP constraints. No generic proxy, cross-server call, raw HTML rendering, or automatic mutation retry.
+
+## Security and performance notes
+
+- Every replay/reconnect reauthorizes, then source access uses exact host ownership and host-resolved internal run IDs. Cursor content never selects ownership.
+- Durable streams are at-least-once. Clients deduplicate `prismEventId`; source cursors resume strictly after a durable record.
+- Client tools, state, context, forwarded properties, media URLs/data, remote A2A parts, MCP metadata, HTML, iframe messages, and reasoning blobs are untrusted. Projectors must use existing Prism media URL/SSRF/MIME policy before any resolution.
+- `input.project` and all output projectors are allow-lists; all generic JSON has byte/depth/property/array caps and prototype-pollution keys fail before host callbacks. Tool handoffs are client-only and cannot widen identity, ownership, permissions, or active server tools.
+- MCP Apps requires sandbox-origin separation, restrictive CSP, declared-domain ceilings, audited JSON-RPC, app/tool visibility checks, and user approval for UI-initiated mutations. The shipped proxy does not retry those mutations; Task 4 adds generic durable effect recovery.
+
+## Related APIs
+
+- [Frontend interoperability](ag-ui.md): shipped Prism AG-UI/ACP API.
+- [Agent events](agent-events.md): source events and durable delivery.
+- [Web-standard server](server.md): SSE `Last-Event-ID` reconnect route.
+- [A2A interoperability](a2a.md): separately mounted A2A lifecycle and durable source adapter.
+- [MCP bridge/server](mcp-tools.md): hardened MCP transport and capability boundary reused by future AG-UI MCP support.