@arnilo/prism 0.5.6 → 0.7.0

package/docs/multi-agent-patterns.md

@@ -1,12 +1,13 @@
-# Multi-agent patterns: handoff, hierarchical crew, supervisor delegation, A2A
+# Multi-agent patterns: handoff, crew, supervisor, spawn tool, A2A
 
 ## What it does
 
-Maps the four Prism answers for "more than one agent" onto one decision table. All four compose existing seams — none introduces a new runtime:
+Maps five Prism answers for "more than one agent" onto one decision table. All five compose existing seams — none introduces a new runtime:
 
 - **In-session handoff (swarm)** — agent A transfers control of the ongoing conversation to agent B by calling a host-built `handoff` tool; the host resolves the target `AgentDefinition` with `resolveAgentDefinition` and opens the specialist against the same session (same store + session id, previous run's `leafId`). One transcript, no new session. No helper primitive ships; the tool factory lives in [`examples/handoff-swarm.ts`](../examples/handoff-swarm.ts).
 - **Hierarchical crew** — a manager agent decomposes a goal into typed tasks (`{ tasks: [{ role, instruction }] }`) via structured output ([`Artifact*`](structured-output.md)), fans out to parallel role specialists with bounded `maxFanOut` ([`fanOutNode`](workflows.md)), aggregates deliverables with host reduce ([`joinNode`](workflows.md)), and validates outputs with conditional routing to completion or revision ([`conditionalNode`](workflows.md)). The entire process is a deterministic DAG workflow with zero new runtime primitives. Live demo in [`examples/crew-hierarchy.ts`](../examples/crew-hierarchy.ts).
 - **Supervisor delegation** — `@arnilo/prism-core/runtime/supervisor` `delegate()` invokes allow-listed child agents as bounded runs and returns their result to the parent. Separate child transcripts, hooks, budgets, narrowing.
+- **In-process spawn tool** — `createSpawnAgentTool({ supervisor })` gives a parent model non-exclusive sync or bounded async `spawn_agent` calls over that same host-owned supervisor catalog; `wait_agent` / `cancel_agent` join or abort local handles. It is an API adapter, not a runtime.
 - **A2A 1.0** — cross-service interop over the JSON-RPC/HTTPS binding; the remote peer's lifecycle is host-owned behind `A2ATaskLifecycle`.
 
 ## When to use it
@@ -15,10 +16,11 @@ Maps the four Prism answers for "more than one agent" onto one decision table. A
 | --- | --- | --- | --- | --- |
 | In-session handoff | One host, one ongoing conversation; the model decides **when** to transfer; specialists are alternate definitions of the same app | One continuous transcript chain (same store, session id, `leafId`) | Same session scope; give the specialist its own identity via its definition (`AgentConfig.identity` / `RunOptions.identity`) | Attribution is per-run: each `session.run()`'s events/result belong to the active definition — record the swap in host bookkeeping; no `delegated_agent_step` event exists for in-process swaps |
 | Hierarchical crew | A goal requires dynamic decomposition by a manager LLM, parallel execution by role specialists, host aggregation, and conditional validation/revision loop | Workflow DAG execution — each specialist executes a bounded child task session; final deliverable returns to host | Workflow tenant/ownership scopes propagate; specialists activate only their own narrowed `tools` | Workflow node events (`node_started`/`node_finished`/`agent_event`); task attribution per role in the aggregated deliverable |
-| Supervisor delegation | Parent agent needs a child as a *tool call*: bounded budget, hooks that redact/narrow, nested delegation, durable child approvals | Separate runs; child result returns to the parent transcript | Parent identity/effectStore propagate; child factories receive derived resource/thread ids and AND-composed permission | Dedicated `delegation_started/finished/rejected/error` events, projectable through observability `handleDelegation()`; opt-in `delegation_child_event` passthrough |
+| Supervisor delegation | Host code dynamically selects a bounded child run | Separate runs; child result returns to the host | Parent identity/effectStore propagate; child factories receive derived resource/thread ids and AND-composed permission | Dedicated `delegation_started/finished/rejected/error` events, projectable through observability `handleDelegation()`; opt-in `delegation_child_event` passthrough |
+| In-process spawn tool | Parent model needs an allow-listed child as a non-exclusive tool call | Separate runs; sync result returns through `spawn_agent`, async handle joins through `wait_agent` | Host owns catalog, tools, scopes, limits, and local handles; schema accepts only child ID/input/thread ID/mode | Same supervisor `delegation_*` events |
 | A2A 1.0 | The other agent is owned by a **different service/deployment**; cross-org or cross-cluster; needs durable task lifecycle, push configs, streaming | Protocol boundary (JSON-RPC/HTTPS agent card); replay/reconnect via host-owned task adapter | Exact-origin verified client, `A2AAuthorization` per operation, principal-scoped push configs | Host-owned task adapter records the remote lifecycle; Prism creates no worker/store |
 
-Rule of thumb: same conversation → handoff; dynamic task decomposition + parallel execution → hierarchical crew; same process but a subtask → supervisor delegation; different deployment/trust boundary → A2A.
+Rule of thumb: same conversation → handoff; dynamic task decomposition + parallel execution → hierarchical crew; host-selected same-process subtask → supervisor delegation; model-requested allow-listed subtask → in-process spawn tool; different deployment/trust boundary → A2A.
 
 ## How in-session handoff works
 
@@ -138,6 +140,17 @@ Live demo: [`examples/crew-hierarchy.ts`](../examples/crew-hierarchy.ts) — man
 | **Validation & Quality Review** | Conditional Node ([`conditionalNode`](workflows.md)) | Deterministic branch routing to `complete` or `revise` based on validation criteria. |
 | **Process Revision Loop** | Node Retries / DAG Branching / Loop Node ([`loopNode`](workflows.md)) | Bounded retry/revision path or bounded in-graph loop iteration. |
 
+## How the in-process spawn tool works
+
+`createSpawnAgentTool({ supervisor })` exposes the host's child catalog as one non-exclusive `spawn_agent` tool, so a parent model can request children the host already allows. It is a thin adapter over [`supervisor.delegate()`](supervisors.md) — no new runtime, no discovery:
+
+- The schema carries only `childId` (an enum of `Supervisor.childIds`), `input`, optional `threadId`, and `mode`. Unknown child IDs fail closed as standard tool errors before any delegation, and model arguments can never supply child tools, identity, scopes, or limits.
+- Named tool calls in one tool turn run in parallel under the parent session's `toolConcurrency`, while the supervisor's reservation keeps concurrent children within `maxActiveChildren` — over-cap sync calls fail closed, async calls return handles.
+- `mode: "async"` returns a local `{ delegationId, status: "running" }` handle; `createWaitAgentTool` joins it, `createCancelAgentTool` aborts it, and the parent run's abort propagates to running children. Handles are in-process, ownership-scoped, and do not survive host restart.
+- Children needing repository isolation wrap their factory with `createWorktreeChildFactory` ([Coding workspaces](coding-workspaces.md#spawn-isolation-supervisor-children)); timeline visibility comes from the supervisor `delegation_*` events, optionally bridged to coding `subagent_started` / `subagent_stopped` ([Coding agent tools](coding-agent-tools.md)).
+
+Live demo: [`examples/spawn-agent-tool.ts`](../examples/spawn-agent-tool.ts) — a narrowed read-only explore child spawned twice in parallel, an uncatalogued child refused, and both handles joined.
+
 ## Where Prism is stronger
 
 - **Durable Human-in-the-Loop (HITL)**: Prism workflows support durable pause and resume via [`suspend()`](workflows.md#durable-suspension-and-resumption) and [`resumeWorkflow()`](workflows.md) across worker restarts or approval gates ([Agent durable approval](agent-session-runtime.md)).
@@ -149,7 +162,7 @@ Live demo: [`examples/crew-hierarchy.ts`](../examples/crew-hierarchy.ts) — man
 ## Security and performance notes
 
 - **Transfers are explicit model-initiated, host-authorized.** The `handoff` tool exists on the triage agent's allow-list only; the target name is validated against the host-authored targets map before any definition resolves. Unknown names fail closed as a standard tool error (`Unknown handoff target: <name>`).
-- **No permission escalation through handoff or delegation.** The specialist's capabilities come solely from its own `AgentDefinition` as resolved by `resolveAgentDefinition` (fail-closed for omitted capabilities). Handoff or fan-out grants nothing: tools/identity are what the host put on that definition. The specialist cannot invoke manager tools unless its definition explicitly includes them — the standard `unknown_tool` block applies otherwise.
+- **No permission escalation through handoff, delegation, or spawn.** The specialist's capabilities come solely from its own `AgentDefinition` or host-owned supervisor child factory (fail-closed for omitted capabilities). Handoff, fan-out, and spawn grant nothing: tools/identity are what the host put on that definition. The specialist cannot invoke manager tools unless its definition explicitly includes them — the standard `unknown_tool` block applies otherwise.
 - **Narrowing on transfer, never widening.** If the specialist needs the caller's verified identity, project it through `narrowIdentity` / `assertIdentityPropagation` ([Agent identity](agent-identity.md)) so scopes and tenant cannot widen across the swap. For delegation the same discipline is built in (`narrowIdentity`, AND-composed policies); for A2A the exact-origin client plus per-operation authorization is the boundary.
 - **Manager-generated task plans are untrusted model output.** Manager plan outputs are validated against the typed schema via `ArtifactValidator` before being persisted to workflow state or dispatched to `fan_out`. Malformed or invalid plans trigger the artifact repair loop or fail closed before any specialist is invoked.
 - **Redaction of carried context.** Handoff carries the raw transcript by design — same rows a human replay would read. Apply the session egress seams on the way out: `redactSessionEntry` / `redactMessage` with a host field policy (see [Data classification](data-classification.md)) and `AgentConfig.redactor`; for durable replay across tenants reuse the redacted transcript seam discipline used by ACP `sessions.transcript` ([ACP interop](acp.md)).
@@ -168,7 +181,8 @@ Live demo: [`examples/crew-hierarchy.ts`](../examples/crew-hierarchy.ts) — man
 - [Workflows](workflows.md): `defineWorkflow`, `fanOutNode`, `joinNode`, `conditionalNode`, `runWorkflow`.
 - [Structured output](structured-output.md): `ArtifactParser`, `ArtifactValidator`, `generateValidateReviseLoop`.
 - [Agent definitions](agent-definitions.md): `resolveAgentDefinition` and fail-closed capability activation — the swap seam itself.
-- [Supervisor delegation](supervisors.md): same-process subtasks with budgets, hooks, and durable nested approvals.
+- [Supervisor delegation](supervisors.md): same-process subtasks, model-facing spawn tool, budgets, hooks, and durable nested approvals.
+- [Coding workspaces](coding-workspaces.md): per-child worktree isolation for parallel spawns.
 - [A2A interoperability](a2a.md): the cross-service protocol boundary.
 - [Agent identity](agent-identity.md): verified identity propagation and narrowing (`narrowIdentity`, `assertIdentityPropagation`).
 - [Agent events](agent-events.md): `delegated_agent_step` and delegation event surfaces for timelines.

package/docs/multimodal-content.md

@@ -167,7 +167,7 @@ from `@arnilo/prism/testing/provider-conformance`.
 ## Security and performance notes
 
 - SSRF deny-by-default blocks IPv4/IPv6 loopback, private/unique-local, link-local, unspecified, multicast, IPv4-mapped private, and cloud metadata targets. DNS answers are all classified before one public address is pinned; mixed public/private answers fail closed.
-- `allowedHostnames` is an explicit trust override and may permit a private destination. `denyPrivateHosts: false` is broader and should be reserved for hosts that intentionally own private-network access.
+- `allowedHostnames` is an explicit trust override and may permit a private destination. `allowedCidrs` is the range equivalent (`"10.0.0.0/8"`, `"fd00::/8"`; IPv4 + IPv6): it is checked after the hostname allow-list and the denied-name list, applies to both URL literals and resolved DNS answers, and bypasses **only** the private-IP block — `metadata.google.internal`/localhost-class names, credentials, and every literal outside the listed ranges stay denied, and a malformed entry fails the policy closed. `denyPrivateHosts: false` is broader and should be reserved for hosts that intentionally own private-network access.
 - DNS lookup, connection, and body streaming share `fetchTimeoutMs` and caller abort; more than 32 resolved addresses, redirects, and oversized response bodies are rejected.
 - Media URL fetches (0.2.1) route through the core `pinnedFetch` primitive — DNS-pinned resolution with per-answer SSRF checks (rebinding defense) and outright 3xx rejection — while keeping the `fetch`/`resolveHostname`/`requestUrl` host seams and the existing byte budgets.
 - MIME validation rejects common magic-byte spoofing; extensions alone are never trusted.

package/docs/obscura.md

@@ -1,5 +1,7 @@
 # Obscura browser engine
 
+> **Optional peer install:** `playwright-core@1.63.0` (exact pin) for the CDP leg — see [Optional peer dependencies](peer-dependencies.md).
+
 Optional `@arnilo/prism-web-tools/obscura` support for a host-installed
 [Obscura](https://github.com/h4ckf0r0day/obscura) headless browser. Obscura is never
 bundled — install the binary (or use the `h4ckf0r0day/obscura` Docker image) and point
@@ -99,7 +101,7 @@ await session.close(); // browser first, then the owned process
 - Endpoints are loopback-only unless `allowRemoteEndpoint` is set; credentials in the
   URL are always rejected; remote plain `ws:`/`http:` is refused (no authentication —
   require an authenticated `wss:`/`https:` tunnel).
-- The Playwright import is an optional exact `playwright-core@1.61.0` peer; supply
+- The Playwright import is an optional exact `playwright-core@1.63.0` peer; supply
   `connectObscuraCdp({ playwright })` to inject a host-selected build.
 - The returned browser composes with `createBrowserManager`/`createBrowserTools`:
   snapshots, actions, policy, checkpoints, and artifacts are Prism-owned. Raw CDP

package/docs/observability.md

@@ -13,6 +13,9 @@ APIs:
 - `createOpenTelemetryInstrumentation()`, `wrapOpenTelemetryApi()`, `createInMemoryTelemetry()` in `@arnilo/prism-core/governance/observability`
 - `createRagTelemetry()` in `@arnilo/prism-core/governance/observability` (RAG spans/events; see span tree below)
 - `handleRunFeedback()` / `handleEvaluation()` for explicit safe post-run projection
+- `projectAgentTimeline()`, `projectTraceTimeline()`, `projectWorkflowTimeline()`, `createTimelineFolder()` — [execution timeline projection](execution-timeline.md) for host cockpits and trajectory evals
+- `summarizeTimeline()`, `summarizeSession()` — [cockpit aggregations](#cockpit-aggregations-and-session-summaries) (bounded tool counts, token and cost rollups without double counting)
+- `attachWorkflow()`, `handleWorkflowEvent()` on `OpenTelemetryInstrumentation` for workflow DAG spans and metrics
 
 ## When to use it
 
@@ -67,6 +70,10 @@ const telemetry = createOpenTelemetryInstrumentation({
 
 const detach = telemetry.attachSession(session);
 // or: for await (const event of session.subscribe()) telemetry.handleAgentEvent(event);
+
+// Workflows:
+const detachWorkflow = telemetry.attachWorkflow(eventBus);
+// or: eventBus.subscribe((event) => telemetry.handleWorkflowEvent(event));
 ```
 
 Set `enabled: false` or omit `tracer`/`meter` for a no-op adapter. Feedback handlers accept only `runId`, rating/score, booleans, bounded counts, and fixed status — never comment, tag values, scorer/evaluation IDs, or arbitrary metadata.
@@ -97,6 +104,14 @@ OpenTelemetry mapping (when enabled):
 | `handleRunFeedback` | active-run `prism.run.feedback` event or ended-run span | `prism.run.feedback` |
 | `handleEvaluation` | active-run `gen_ai.evaluation.result` event or ended-run span | `prism.run.evaluation` (`status`) |
 
+Workflow mapping (when enabled via `attachWorkflow` or `handleWorkflowEvent`):
+
+| Workflow event | Span | Metric labels |
+| --- | --- | --- |
+| `workflow_started` / `workflow_finished` | `invoke_workflow {workflowId}` (`INTERNAL`) | `prism.workflow.duration` (`prism.workflow.id`, `prism.workflow.status`) |
+| `node_started` / `node_finished` / `node_failed` / `node_skipped` | `prism.workflow.node {nodeId}` child (`INTERNAL`) | none (span attributes: `prism.node.kind`, `prism.node.status`) |
+| `node_iteration_started` / `finished` | `prism.workflow.iteration` events on node span | none |
+
 RAG span tree (`@arnilo/prism-memory/rag` + `createRagTelemetry()`):
 
 | Span | Parent | Notes |
@@ -171,6 +186,41 @@ const ragTelemetry = createRagTelemetry({ tracer: memory.tracer, meter: memory.m
 const found = await retrieveContext("policy", { embedder, store, scope, telemetry: ragTelemetry }); // rag_request tree
 ```
 
+## Cockpit aggregations and session summaries
+
+Host cockpits and dashboard cards need fast aggregate summaries of an execution without re-walking every raw event or risking prompt/secret leaks:
+
+- `summarizeTimeline(timeline)`: rolls up an `ExecutionTimeline` into a `TimelineSummary` containing duration, turn count, tool call counts, provider attempts, total tokens, cost, error counts, and suspension state.
+- `summarizeSession(timelines)`: rolls up an array of `ExecutionTimeline`s for a session/conversation into a `SessionSummary` with aggregated tokens, costs, run counts, and duration.
+
+```ts
+import { summarizeTimeline, summarizeSession } from "@arnilo/prism-core/governance/observability";
+
+const summary = summarizeTimeline(timeline);
+// summary: TimelineSummary
+// {
+//   durationMs: 1250,
+//   turnCount: 2,
+//   toolCallCount: 3,
+//   toolCounts: { search: 2, lookup: 1 },
+//   providerAttempts: 2,
+//   usage: { totalTokens: 450, promptTokens: 300, completionTokens: 150 },
+//   cost: { amount: 0.0012, currency: "USD" },
+//   errorCount: 0,
+//   blockedToolCount: 0,
+//   suspended: false,
+//   status: "succeeded",
+// }
+
+const sessionSummary = summarizeSession([run1Timeline, run2Timeline]);
+// sessionSummary: SessionSummary
+```
+
+Cardinality and correctness guarantees:
+- **Bounded cardinality**: `toolCounts` is capped to `MAX_SUMMARY_DISTINCT_TOOLS = 64` distinct tool names. If more tools are invoked, lowest-frequency tool names overflow into an `"other"` bucket.
+- **No double counting**: Token usage is derived from the root run's `run_total` (or aggregated across `turn` / `provider` steps if no run-level total exists), avoiding double counting between provider turn steps and run totals. Costs are rounded to 6 decimal places to prevent floating-point drift.
+- **Payload-free**: Summaries contain counts, durations, status codes, and usage metrics only — zero prompt text, tool arguments, or credentials.
+
 ## Extension and configuration notes
 
 - Events flow through `redactAgentEvent` before subscribers and ledger writes — configure `createSecretRedactor` on the agent/run.
@@ -214,11 +264,12 @@ const entries = capture.events(); // oldest-first snapshot; capture.clear() rese
 - Capture middleware follows the same default: `redact: "secrets"` drops message content; buffers are capped and secrets are redacted unconditionally, so a captured buffer can be persisted or replayed without leaking credentials.
 - Use `identityTelemetryAttributes(identity)` when attaching enterprise identity to run metadata or OTel attributes; it emits `prism.identity.*` refs only (tenant/principal/scope counts), never credential secrets or raw tokens.
 - Opt-in content in other event types (`message_delta`, tool `result`) is still subject to `redactAgentEvent`.
-- Metric labels stay low-cardinality (`gen_ai.operation.name`, `gen_ai.provider.name`, token type, controlled outcome/status, feedback rating bucket/link presence); never use session/run/request/call IDs, model output, comments, tag values, scorer/evaluation IDs, or arbitrary metadata as labels. Token usage is recorded once at provider operation scope.
+- Metric labels stay low-cardinality (`gen_ai.operation.name`, `gen_ai.provider.name`, token type, controlled outcome/status, feedback rating bucket/link presence, controlled `prism.workflow.id` names); never use session/run/request/call IDs, dynamic run IDs, model output, comments, tag values, scorer/evaluation IDs, or arbitrary metadata as labels. Token usage is recorded once at provider operation scope.
 - Target overhead when enabled is under 5% excluding exporter I/O; disabled hooks allocate no spans.
 - Provider transport limits and redaction order are documented in [Provider primitives](provider-primitives.md).
 
 ## Related APIs
+- [Execution timeline](execution-timeline.md): cockpit projection — fold `AgentEvent` or `WorkflowEvent` into `ExecutionTimeline`.
 - [Agent identity](agent-identity.md): redacted identity attribute helper for telemetry.
 - [Evaluations](evaluations.md): optional scorers can link scores to run/session/trace IDs from agent events.
 

package/docs/operations.md

@@ -8,6 +8,7 @@ This page is the operator runbook for the high-availability story proven by plan
 
 - Before running any multi-replica deployment of the server, workflow coordinator, saga runner, ACP host, or enterprise dispatcher — read the local-registry limitations and the lease/fence model.
 - When an operator or on-call engineer sees a hung lease, an uncertain commit, or a split-brain suspicion: follow "Failover procedure" and "Uncertain commits" below before touching anything.
+- When background workers share a checkpoint queue across tenants: use `admission` on `createWorkflowCoordinator` and `createPrismOperatorHandler` for inspect/cancel/reconcile. Do not add a second job broker.
 - When sizing leases: the failover ceiling is lease TTL plus the peer's acquisition poll interval; the drill asserts `failoverMs <= ttlMs + 5000`.
 
 ## Inputs / request
@@ -94,6 +95,16 @@ tenant's reads, writes, and lease takeover all fail closed.
   with bounded, jittered acquisition polls (no hot loops) and reports the
   measured numbers in the evidence JSON.
 
+## Fair worker admission and operator intervention
+
+`createWorkflowCoordinator({ admission })` is still checkpoint+lease polling — not a job DSL. Each `pollOnce` walks at most `maxPagesPerPoll` list pages from a wrap cursor so a saturated first page cannot hide later tenants. `perTenant` / `perClass` cap **this worker's** concurrent claims. `deadlineMs` skips (does not auto-fail) stale `createdAt`. While `drain.isDraining`, no new claims; after `snapshot().expired`, in-flight work is aborted if the node honors the run signal. Leases are released only via the holder token — never deleted by hand.
+
+`createPrismOperatorHandler({ authorize, checkpoints, workflows, unknownEffects? })` mounts `/ops/queue|suspended|failed|unknown` and `POST /ops/cancel|reconcile`. `authorize` is required and fail-closed; lists are ownership-scoped; bodies omit workflow input/state. Reconcile accepts only `completed` or `failed_terminal` plus optional evidence. Unknown effects are never retried from this route.
+
+Metric hook labels: `outcome` and allowlisted `class` only.
+
+Network-free composition: [`examples/server-deployment-seams.ts`](../examples/server-deployment-seams.ts).
+
 ## Live probe (plans/064 Task 9)
 
 The outbound webhook notifier has an operator-gated live probe against a receiver you own:
@@ -110,6 +121,7 @@ Probes: one signed delivery to your receiver (verify `x-prism-signature: sha256=
 - `LeaseStore` / `CheckpointStore` — the durable contracts this runbook relies on.
 - `createPostgresPersistence` — the PostgreSQL adapter used by the drill.
 - `ErpOutboxStore` — the idempotent side-effect carrier used to make replay safe.
-- `createWorkflowCoordinator` and `defineSaga`/`runSaga`/`resumeSaga` — higher-level consumers with the same fencing/cursor semantics.
+- `createWorkflowCoordinator` (`admission`) and `createPrismOperatorHandler` — fair claim policy and ownership-scoped cancel/reconcile.
+- `defineSaga`/`runSaga`/`resumeSaga` — higher-level consumers with the same fencing/cursor semantics.
 - `scripts/phase27-ha-worker.mjs` / `scripts/phase27-ha.test.mjs` — the reproducible drill; `docs/_evidence/phase27-ha-evidence.json` — the recorded run.
 - [Signed, hash-chained audit export](audit-export.md) — the cursor/CAS pattern applied to audit exports.

package/docs/options-index.md

@@ -0,0 +1,298 @@
+# Configuration options index
+
+## What it does
+
+Maps every public configuration surface — the `*Options`, `*Limits`, and `*Config` types a host passes into Prism — to the doc page that owns its fields. Prism has one options object per seam rather than a global config tree, so "where do I set this?" is the recurring onboarding question; this page answers it in one hop.
+
+## When to use it
+
+- Wiring a host for the first time and looking for the right seam (`AgentConfig`, `RunOptions`, `ModelConfig`, …).
+- Reviewing which surfaces a run, session, or adapter can override before writing an override.
+- Checking whether a knob is host-tunable at all before assuming a limit is hardcoded.
+
+Field-level detail (defaults, bounds, failure modes) lives on the owning page — this index only routes you there.
+
+## Start here: the surfaces most hosts set
+
+| Surface | Configures | Owning page |
+| --- | --- | --- |
+| `AgentConfig` | The reusable agent: provider, model, tools, skills, stores, retry, compaction, prompts, limits | [Agent/session runtime](agent-session-runtime.md) |
+| `RunOptions` | One run's overrides: model, limits, thinking level, skills, middleware, metadata, signal | [Agent/session runtime](agent-session-runtime.md) |
+| `AgentSessionConfig` | Session creation: id, agent, store, branch leaf, snapshot cache TTL | [Agent/session runtime](agent-session-runtime.md) |
+| `ModelConfig` | A registered model record: capabilities, limits, cost, cache and thinking metadata | [Model registry](model-registry.md) |
+| `ProviderRequestOptions` | Per-request provider hints: session/cache/header/compat/extra, applied after host policies | [Provider layer](provider-layer.md) |
+
+## How options behave
+
+- **Fixed defaults, host overrides.** Every option is optional; the value it replaces is the documented default, and an omitted option is exactly equivalent to passing the default explicitly.
+- **Two-tier caps.** Tunable limits follow the repo convention `DEFAULT_*` (used when the host sets nothing) and `HARD_*` (the ceiling a host value is validated against), exported next to the option that accepts them. A value outside `1..HARD` (or `0..HARD` where zero means "disabled") fails closed with a `TypeError` at construction or assembly — never a silent clamp.
+- **Request-time overrides narrow, never widen.** `RunOptions.limits` can only tighten `AgentConfig.limits`; a configured finite ceiling wins over `null`.
+- **Byte caps are not estimator-dependent.** Token-budget options that accept a host estimator (`tokenEstimator`) affect eviction accounting only; byte caps and redaction stay authoritative.
+
+## Agent/session runtime
+
+**Agent definitions** — [`agent-definitions.md`](agent-definitions.md)  
+`DiscoverAgentBundlesOptions`, `ResolveAgentBundleOptions`
+
+**Agent events** — [`agent-events.md`](agent-events.md)  
+`SubscribeOptions`
+
+**Agent loops** — [`agent-loops.md`](agent-loops.md)  
+`AgentLoopOptions`
+
+**Agent/session runtime** — [`agent-session-runtime.md`](agent-session-runtime.md)  
+`AgentConfig`, `AgentRunResumeOptions`, `AgentRunResumeStreamOptions`, `AgentSessionCloneOptions`, `AgentSessionConfig`, `AgentSessionForkOptions`, `RunOptions`, `SteerOptions`
+
+**Evaluations** — [`evaluations.md`](evaluations.md)  
+`ScoreRunOptions`
+
+**Runs and usage ledger** — [`runs-and-usage.md`](runs-and-usage.md)  
+`RunLimits`
+
+**Structured output** — [`structured-output.md`](structured-output.md)  
+`StructuredOutputOptions`
+
+## Compaction and session memory
+
+**Compaction and retry policies** — [`compaction-and-retry.md`](compaction-and-retry.md)  
+`CompactionOptions`, `DefaultCompactionStrategyOptions`, `DefaultRetryPolicyOptions`, `RetryOptions`
+
+**LLM compaction package** — [`compaction-llm.md`](compaction-llm.md)  
+`LlmCompactionStrategyOptions`
+
+**Conversations** — [`conversations.md`](conversations.md)  
+`ConversationLimits`
+
+**Node JSONL session store** — [`node-jsonl-session-store.md`](node-jsonl-session-store.md)  
+`JsonlSessionStoreOptions`
+
+**PostgreSQL persistence** — [`postgres-persistence.md`](postgres-persistence.md)  
+`AgentEventSourceOptions`, `PostgresPersistenceOptions`
+
+**Session stores** — [`session-stores.md`](session-stores.md)  
+`CreateMemorySessionStoreOptions`, `SessionAppendOptions`
+
+**SQLite persistence** — [`sqlite-persistence.md`](sqlite-persistence.md)  
+`SqlitePersistenceOptions`
+
+**Working and semantic memory** — [`working-and-semantic-memory.md`](working-and-semantic-memory.md)  
+`PostgresVectorStoreOptions`, `RecallScoringOptions`
+
+**Memory fabric** — [`memory-fabric.md`](memory-fabric.md)  
+`CreateMemoryFabricOptions`, `MemoryFabricAttachOptions`, `MemoryFabricToolsOptions`, `MemoryFabricWriteOptions`, `MemoryFabricRecallOptions`, `MemoryFabricConsolidationOptions`, `MemoryFabricLinkerOptions`, `MemoryFabricEvolutionOptions`, `MemoryFabricConversationSearchOptions`, `CreateFabricFileJailOptions`
+
+**Observational memory** — [`compaction-observational-memory.md`](compaction-observational-memory.md)  
+`ObservationalMemoryAppendOptions`, `WorkScopeControllerOptions`
+
+## Provider and model connection
+
+**Model registry** — [`model-registry.md`](model-registry.md)  
+`ModelConfig`, `ModelLimits`
+
+**Provider layer** — [`provider-layer.md`](provider-layer.md)  
+`MockProviderOptions`, `ProviderRequestOptions`
+
+**Provider primitives** — [`provider-primitives.md`](provider-primitives.md)  
+`BoundedStreamLimits`
+
+**Alibaba Cloud provider package** — [`providers/alibaba.md`](providers/alibaba.md)  
+`AlibabaEmbedderOptions`, `AlibabaModelConfig`, `AlibabaProviderOptions`, `AlibabaProviderPackageOptions`, `ListAlibabaModelsOptions`
+
+**Anthropic provider package** — [`providers/anthropic.md`](providers/anthropic.md)  
+`AnthropicProviderPackageOptions`, `ListAnthropicModelsOptions`
+
+**ClinePass provider package** — [`providers/clinepass.md`](providers/clinepass.md)  
+`ClinePassProviderPackageOptions`
+
+**Command Code provider package** — [`providers/commandcode.md`](providers/commandcode.md)  
+`CommandCodeProviderPackageOptions`
+
+**DeepSeek provider package** — [`providers/deepseek.md`](providers/deepseek.md)  
+`DeepSeekModelConfig`, `DeepSeekProviderPackageOptions`, `ListDeepSeekModelsOptions`
+
+**Google provider package** — [`providers/google.md`](providers/google.md)  
+`GoogleProviderPackageOptions`, `ListGoogleModelsOptions`
+
+**Hyper provider package** — [`providers/hyper.md`](providers/hyper.md)  
+`HyperProviderPackageOptions`
+
+**Kimi provider package** — [`providers/kimi.md`](providers/kimi.md)  
+`KimiModelConfig`, `KimiProviderPackageOptions`, `ListKimiModelsOptions`
+
+**NeuralWatt provider package** — [`providers/neuralwatt.md`](providers/neuralwatt.md)  
+`GetNeuralWattQuotaOptions`, `ListNeuralWattModelsOptions`, `NeuralWattModelConfig`, `NeuralWattProviderPackageOptions`
+
+**Ollama Cloud provider package** — [`providers/ollama.md`](providers/ollama.md)  
+`ListOllamaModelsOptions`, `OllamaModelConfig`, `OllamaProviderOptions`, `OllamaProviderPackageOptions`
+
+**OpenAI-compatible provider** — [`providers/openai-compatible.md`](providers/openai-compatible.md)  
+`OpenAICompatibleProviderOptions`
+
+**OpenAI provider package** — [`providers/openai.md`](providers/openai.md)  
+`OpenAICodexOAuthOptions`, `OpenAIProviderPackageOptions`
+
+**OpenCode Go provider package** — [`providers/opencode-go.md`](providers/opencode-go.md)  
+`OpenCodeGoProviderPackageOptions`
+
+**OpenRouter provider package** — [`providers/openrouter.md`](providers/openrouter.md)  
+`ListOpenRouterModelsOptions`, `OpenRouterModelConfig`, `OpenRouterProviderPackageOptions`
+
+**xAI provider package** — [`providers/xai.md`](providers/xai.md)  
+`ListXaiModelsOptions`, `XaiOAuthOptions`, `XaiProviderPackageOptions`
+
+**Z.AI provider package** — [`providers/zai.md`](providers/zai.md)  
+`ListZaiModelsOptions`, `ZaiModelConfig`, `ZaiProviderPackageOptions`
+
+## Input, prompt, and context assembly
+
+**Context and skills** — [`context-and-skills.md`](context-and-skills.md)  
+`ResolveActiveSkillsOptions`, `ResolveContextOptions`
+
+**Attention compiler** — [`attention-compiler.md`](attention-compiler.md)  
+`AttentionCompilerOptions`, `AttentionInputCapOptions`, `AttentionCompileOptions`, `AttentionTruncationTriggerOptions`
+
+**Input and prompt assembly** — [`input-and-prompt-assembly.md`](input-and-prompt-assembly.md)  
+`AssembleProviderInputOptions`, `PromptTemplateOptions`
+
+**Multimodal content** — [`multimodal-content.md`](multimodal-content.md)  
+`ResolveMediaContentOptions`
+
+**Retrieval-augmented generation (RAG)** — [`rag.md`](rag.md)  
+`CreateTeiRerankerOptions`
+
+**System prompts** — [`system-prompts.md`](system-prompts.md)  
+`SystemPromptConfig`
+
+## Tools
+
+**Browser automation** — [`browser-automation.md`](browser-automation.md)  
+`BrowserCdpOptions`
+
+**Coding agent tools (first-party package)** — [`coding-agent-tools.md`](coding-agent-tools.md)  
+`EditToolOptions`, `ReadTextOptions`, `ReadToolOptions`, `RepositoryLimitOptions`, `ShellToolOptions`, `ToolsOptions`, `WriteToolOptions`
+
+**Coding execution approval and sandboxing** — [`coding-security.md`](coding-security.md)  
+`DockerNetworkConfig`
+
+**Device adapters** — [`device-adapters.md`](device-adapters.md)  
+`DevicePolicyOptions`
+
+**GitHub forge integration** — [`forge-integration.md`](forge-integration.md)  
+`CreateGitRunnerOptions`, `ForgeLimits`
+
+**Language intelligence** — [`language-intelligence.md`](language-intelligence.md)  
+`LanguageIntelligenceLimits`
+
+**MCP client bridge and server exposure** — [`mcp-tools.md`](mcp-tools.md)  
+`CreatePrismMcpServerOptions`
+
+**Process sessions** — [`process-sessions.md`](process-sessions.md)  
+`ProcessSessionLimits`
+
+**Tools** — [`tools.md`](tools.md)  
+`DispatchToolCallOptions`
+
+## Documents, sheets, and diagrams
+
+**Diagramming, draw.io embed client, and mxGraph XML validation** — [`diagrams.md`](diagrams.md)  
+`DrawioCanonicalizeOptions`, `DrawioEmbedOptions`, `DrawioExportOptions`, `DrawioLoadOptions`, `DrawioXmlOptions`
+
+**Documents, spreadsheets, and presentations** — [`documents.md`](documents.md)  
+`GenerateDocumentOptions`, `ParseDocumentOptions`, `PatchDocumentOptions`, `PreviewBlocksOptions`, `PreviewHtmlOptions`
+
+**Spreadsheets, CSV parsing, and typed schema inference** — [`sheets.md`](sheets.md)  
+`ParseCsvOptions`, `ParseWorkbookOptions`
+
+## Extensions and plugins
+
+**Contribution discovery (workspace)** — [`contribution-discovery.md`](contribution-discovery.md)  
+`DiscoveryOptions`
+
+**Extension kernel and event bus** — [`extensions.md`](extensions.md)  
+`ExtensionKernelOptions`
+
+**Middleware hooks** — [`middleware-hooks.md`](middleware-hooks.md)  
+`MiddlewareRegistryOptions`
+
+## Configuration and manifests
+
+**Resource loading** — [`resource-loading.md`](resource-loading.md)  
+`LoadBinaryResourceOptions`
+
+## Server/API
+
+**Web-standard server handler** — [`server.md`](server.md)  
+`PrismServerLimits`
+
+## Multi-agent and interoperability
+
+**Agent Client Protocol (ACP) coding-host interop** — [`acp.md`](acp.md)  
+`AcpCapabilitiesOptions`, `CreatePrismAcpAgentOptions`
+
+**Frontend interoperability (AG-UI and ACP)** — [`ag-ui.md`](ag-ui.md)  
+`AgUiLimitOptions`
+
+**Supervisors and subagents** — [`supervisors.md`](supervisors.md)  
+`CreateSupervisorOptions`, `SupervisorLimits`, `ResolvedSupervisorLimits`, `DelegationWaitOptions`, `CreateSpawnAgentToolOptions`, `CreateDelegationControlToolOptions`, `WorktreeChildFactoryOptions`, `ObserveSupervisorLifecycleOptions`
+
+## CLI/RPC
+
+**Workflows** — [`workflows.md`](workflows.md)  
+`RunWorkflowOptions`
+
+## Conformance harnesses
+
+These option objects configure the shipped test doubles a host runs against its own adapters (provider, store, run ledger, compaction, tool, extension). They are host-facing, but only in test code.
+
+**Compaction conformance** — [`compaction-conformance.md`](compaction-conformance.md)  
+`CompactionConformanceOptions`
+
+**Extension conformance** — [`extension-conformance.md`](extension-conformance.md)  
+`ExtensionConformanceOptions`
+
+**Run ledger conformance** — [`run-ledger-conformance.md`](run-ledger-conformance.md)  
+`RunLedgerConformanceOptions`
+
+**Session store conformance** — [`session-store-conformance.md`](session-store-conformance.md)  
+`SessionStoreConformanceOptions`
+
+**Tool conformance** — [`tool-conformance.md`](tool-conformance.md)  
+`ToolConformanceOptions`, `ToolDisclosureConformanceOptions`, `ToolDispatchProbeOptions`
+
+## Implementation example
+
+```ts
+import { createAgent, createMemorySessionStore } from "@arnilo/prism";
+
+// Agent-level: the long-lived defaults.
+const agent = createAgent({
+  provider,
+  model: { id: "gpt-4o", provider: "openai" },
+  limits: { maxTurns: 12, maxToolRounds: 8 },   // AgentConfig.limits
+  store: createMemorySessionStore([], { search: { maxLinearSessions: 5_000 } }),
+});
+
+// Session-level: identity, branch, and snapshot cache.
+const session = agent.createSession({ leafId: "leaf-1", snapshotCacheTtlMs: 0 });
+
+// Run-level: only narrows what the agent configured.
+await session.run("hi", { limits: { maxToolRounds: 2 }, thinkingLevel: "low" });
+```
+
+## Extension and configuration notes
+
+- Options are plain data. A host overrides behavior by passing a *different implementation* to the seam (`store`, `providerSource`, `loop`, policies), not by mutating a shared config object.
+- Layered JSON configuration (`mergeConfigLayers`) resolves to the same option shapes; see [Configuration and manifests](configuration-and-manifests.md).
+- This index is checked against the source tree: every surface named here must exist as a declared `*Options`/`*Limits`/`*Config` type, and every link must resolve. See `scripts/live-doc-check.test.mjs`.
+
+## Security and performance notes
+
+- Credentials never appear in these option objects; secrets resolve through credential providers and are redacted before they reach requests, logs, or events. See [Credentials and redaction](credentials-and-redaction.md).
+- Trust boundaries are options too (`trust`, permission policies, sandbox and egress config). Tightening them is always allowed; loosening one requires the host to pass it explicitly. See [Host security guide](host-security.md).
+- Raising a cap raises resource use. Caps exist to bound memory, sockets, subprocesses, and provider spend; prefer narrowing per run over raising an agent-wide ceiling.
+
+## Related APIs
+
+- [Public contracts](public-contracts.md): the shapes these options produce and the store/tool/provider interfaces they configure.
+- [Optional peer dependencies](peer-dependencies.md): which surfaces need an extra install before their options are reachable.
+- [SDK customization guide](customization.md): a seam-by-seam walkthrough of replacing Prism primitives.

package/docs/peer-dependencies.md

@@ -0,0 +1,96 @@
+# Optional peer dependencies
+
+## What it does
+
+Lists every third-party peer a Prism package declares, what importing that peer unlocks, and the exact install line for it. Prism keeps optional integrations behind peer dependencies so a host installs a browser, a database driver, or a vendor SDK only when it actually uses that surface — and so the host, not Prism, owns the version, the binary, and the supply chain.
+
+## When to use it
+
+- Before installing a subpath: check whether it needs an extra package.
+- Reviewing supply chain: which peers open a network connection, and which are pinned.
+- Debugging a "peer not installed" error from a gated subpath.
+- Auditing which of your already-installed packages a Prism surface will reuse.
+
+Internal `@arnilo/*` peers are not listed here: every first-party package declares a required `@arnilo/prism` peer, and the release gate keeps all internal ranges locked to the cut version. This page covers the **12 third-party declarations across 6 packages**.
+
+## Matrix
+
+One row per declaration. `Unlocks` names the subpath whose import reaches the peer; `Install` is the exact command for a host that has already installed the Prism package.
+
+| Peer | Declared range | Optional | Declared by | Unlocks | Install | Network |
+| --- | --- | --- | --- | --- | --- | --- |
+| `zod` | `^3.25.0 \|\| ^4.0.0` | no | `@arnilo/prism-ag-ui` | `./acp` | `npm i zod` | no |
+| `@nanonets/graft` | `^0.16.0 \|\| ^0.18.0` | yes | `@arnilo/prism-memory` | `./graft` | `npm i @nanonets/graft` | no |
+| `@dietrichgebert/ponytail` | `^4.9.0` | yes | `@arnilo/prism-coding-tools` | `./ponytail` | `npm i @dietrichgebert/ponytail` | no |
+| `mammoth` | `^1.8.0` | yes | `@arnilo/prism-coding-tools` | `./document-reader` | `npm i mammoth` | no |
+| `pdf-parse` | `^2.4.5` | yes | `@arnilo/prism-coding-tools` | `./document-reader` | `npm i pdf-parse` | no |
+| `e2b` | `2.49.1` | yes | `@arnilo/prism-coding-tools` | `./security` | `npm i e2b@2.49.1` | yes |
+| `better-sqlite3` | `^13.0.3` | yes | `@arnilo/prism-core` | `./sessions/sqlite`, `./governance/prompts` | `npm i better-sqlite3` | no |
+| `pg` | `^8.23.0` | yes | `@arnilo/prism-core` | `./sessions/postgres`, `./enterprise/postgres`, `./governance/prompts` | `npm i pg` | yes |
+| `@nats-io/jetstream` | `^3.4.0` | yes | `@arnilo/prism-core` | `./sessions/nats` | `npm i @nats-io/jetstream @nats-io/transport-node` | yes |
+| `@nats-io/transport-node` | `^3.4.0` | yes | `@arnilo/prism-core` | `./sessions/nats` | `npm i @nats-io/transport-node` | yes |
+| `@ai-sdk/provider` | `4.0.13` | yes | `@arnilo/prism-providers` | `./ai-sdk` | `npm i @ai-sdk/provider@4.0.13` | no |
+| `playwright-core` | `1.63.0` | yes | `@arnilo/prism-web-tools` | `./browser`, `./obscura` | `npm i playwright-core@1.63.0` | yes |
+
+## Exact pins and why
+
+Two peers are pinned to an exact version instead of a range, because the pin is a contract rather than a convenience:
+
+- **`playwright-core@1.63.0`** (`@arnilo/prism-web-tools/browser`, `/obscura`). Browser automation rides Playwright's CDP transport and accessibility snapshot shapes, which move between minors. Prism never launches, downloads, or bundles a browser: the host supplies the binary, the image, and the cache, and must match the pinned client. See [Browser automation](browser-automation.md).
+- **`@ai-sdk/provider@4.0.13`** (`@arnilo/prism-providers/ai-sdk`). The adapter consumes deterministic specification-versioned types (`LanguageModelV4`) and gates on an exact supported-version matrix at construction, so an unlisted version fails closed instead of silently mis-mapping. See [AI SDK provider](providers/ai-sdk.md).
+- **`e2b@2.49.1`** (`@arnilo/prism-coding-tools/security`). Pause `keepMemory`, `Sandbox.connect` auto-resume, and `ServiceBusyError` 503 semantics are version-specific. Hosts may inject `{ client }` instead of installing the peer. See [Hosted sandboxes](hosted-sandboxes.md).
+
+`zod` is the only **required** third-party peer. `@agentclientprotocol/sdk` — a hard dependency of `@arnilo/prism-ag-ui` — declares `zod: ^3.25.0 || ^4.0.0` as its own peer, so `@arnilo/prism-ag-ui` re-declares the same range to keep the install tree satisfiable; the range is deliberately identical to the SDK's. Nothing in Prism imports zod directly.
+
+## Peers that touch the network
+
+`pg`, `@nats-io/jetstream`, `@nats-io/transport-node`, `playwright-core`, and `e2b` open sockets. For a supply-chain review of those five:
+
+- **Connection targets are host-owned.** Every one of them is passed a host-supplied connection string, endpoint list, browser instance, API key, or service URL. Prism holds no default endpoint, and no peer is reachable from the root import.
+- **Bytes stay local otherwise.** `better-sqlite3`, `mammoth`, `pdf-parse`, `@nanonets/graft`, and `@dietrichgebert/ponytail` are filesystem/process peers; the remaining two (`zod`, `@ai-sdk/provider`) are pure types/schemas.
+- **No secrets are read by the peers.** Prism resolves credentials through host providers and redacts them at the boundary; peers only ever receive a resolved connection string or model object. See [Credentials and redaction](credentials-and-redaction.md) and [Host security guide](host-security.md).
+- **Nothing is installed implicitly.** Optional peers are never auto-installed by npm; a missing one fails closed at the call site with a typed error naming the peer and the subpath. Required peers (today only `zod`) are installed by npm with the package.
+
+Test-only dependencies are *not* peers. `playwright-core` appears in `@arnilo/prism-office` as a devDependency only, because the office diagrams embed takes a host-supplied iframe and the sole consumer is the gated live draw.io conformance test.
+
+## Implementation example
+
+```bash
+# Browser automation: pinned client, host-owned browser binary
+npm i @arnilo/prism-web-tools playwright-core@1.63.0
+
+# PostgreSQL session store: pool driver only
+npm i @arnilo/prism-core pg
+
+# NATS JetStream event source: transport + jetstream together
+npm i @arnilo/prism-core @nats-io/transport-node @nats-io/jetstream
+
+# Document reader: pick the parser you need (both are independent)
+npm i @arnilo/prism-coding-tools pdf-parse mammoth
+```
+
+```ts
+import { chromium } from "playwright-core"; // host supplies the binary/image
+import { createBrowserTools } from "@arnilo/prism-web-tools/browser";
+
+const browser = await chromium.launch({ headless: true }); // host-owned, never Prism's
+const tools = await createBrowserTools({ browser });
+```
+
+## Extension and configuration notes
+
+- A peer is an *implementation the host owns*. When a peer's default wiring is not what you want, pass your own implementation instead of installing theirs: the document reader accepts host parsers (`createReadTool({ documentReader })`), the memory `/graft` resolver accepts an explicit package root, and the browser surfaces accept a host `Browser`.
+- Subpaths that need a peer isolate that import, so importing another subpath of the same package never evaluates it. The office family is the extreme case: zero peers, because it takes structural inputs.
+- Adding a peer to a Prism package is a release-gated change: the declaration must be optional unless a hard dependency's own peer forces it (the `zod` case), and exact pins must come with a version-gate or compatibility rationale.
+
+## Security and performance notes
+
+- Pinned peers must be updated through the release process, not by a host override: an unpinned browser client or AI SDK type surface is a silent behavior change.
+- Peer installs are host-visible supply-chain additions. Prefer one peer per capability, keep them out of the root import, and audit transitive dependencies of the five network-touching peers in your own policy.
+- Prism adds no runtime cost for an uninstalled peer; the failure is a typed error at first use.
+
+## Related APIs
+
+- [Release and install](release-and-install.md): install profiles that pair with each peer.
+- [Configuration options index](options-index.md): the option surfaces each peer unlocks.
+- Package-level detail: [Coding tools](coding-tools.md), [Core runtime](core.md), [Session stores](session-stores.md), [Browser automation](browser-automation.md), [Document reader](document-reader.md), [Graft](graft.md), [Ponytail](ponytail.md), [Provider packages](provider-packages.md).