@arnilo/prism 0.6.0 → 0.7.0

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

@@ -41,7 +41,7 @@ Field-level detail (defaults, bounds, failure modes) lives on the owning page
 `AgentLoopOptions`
 
 **Agent/session runtime** — [`agent-session-runtime.md`](agent-session-runtime.md)  
-`AgentConfig`, `AgentRunResumeStreamOptions`, `AgentSessionCloneOptions`, `AgentSessionConfig`, `AgentSessionForkOptions`, `RunOptions`, `SteerOptions`
+`AgentConfig`, `AgentRunResumeOptions`, `AgentRunResumeStreamOptions`, `AgentSessionCloneOptions`, `AgentSessionConfig`, `AgentSessionForkOptions`, `RunOptions`, `SteerOptions`
 
 **Evaluations** — [`evaluations.md`](evaluations.md)  
 `ScoreRunOptions`
@@ -78,6 +78,12 @@ Field-level detail (defaults, bounds, failure modes) lives on the owning page
 **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)  
@@ -142,6 +148,9 @@ Field-level detail (defaults, bounds, failure modes) lives on the owning page
 **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`
 
@@ -223,6 +232,9 @@ Field-level detail (defaults, bounds, failure modes) lives on the owning page
 **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)  

package/docs/peer-dependencies.md

@@ -11,7 +11,7 @@ Lists every third-party peer a Prism package declares, what importing that peer
 - 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 **11 third-party declarations across 6 packages**.
+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
 
@@ -24,6 +24,7 @@ One row per declaration. `Unlocks` names the subpath whose import reaches the pe
 | `@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 |
@@ -37,14 +38,15 @@ Two peers are pinned to an exact version instead of a range, because the pin is
 
 - **`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`, and `playwright-core` open sockets. For a supply-chain review of those four:
+`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, or service URL. Prism holds no default endpoint, and no peer is reachable from the root import.
+- **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.
@@ -84,7 +86,7 @@ const tools = await createBrowserTools({ browser });
 ## 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 four network-touching peers in your own policy.
+- 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

package/docs/process-sessions.md

@@ -136,7 +136,8 @@ await sessions.dispose();
 - Host restart: call `reconcile()` on a new registry for in-memory orphans, or listen for `process_unknown` and wire Phase 7 `ToolEffectStore.markUnknown` in the host.
 - Expiry sweep runs on registry/handle access — no timers at import.
 - Command fingerprint is SHA-256 of `[command, ...args]` only (no env).
-- Docker reference adapter does not implement `startProcess` yet — fail closed until a capable runtime is wired.
+- Docker sandbox (`createDockerSandbox`) implements `startProcess` returning a compliant `SandboxProcessHandle` with durable `ref` for attested reconnect. Process operations (`write`, bounded `onData` output, `wait`, `signal`, `kill`, `release`) compose with `ProcessSessions`. The sandbox `attachProcess(ref)` resolves an opaque `prism-docker-proc:` ref to a live in-memory handle with fail-closed validation (container ID, workspace, command fingerprint). `createDockerProcessRecoveryBackend(sandbox, options?)` provides a ready-made `ProcessRecoveryBackend` with optional `expectedContainerId`, `expectedWorkspace`, and `expectedLabels` assertions. When a sandbox is passed to `createProcessSessions` and has `attachProcess`, the recovery backend is wired automatically.
+- Hosted E2B sandbox (`createE2BSandbox`) also implements `startProcess` / `attachProcess` with opaque `prism-e2b-proc:` refs (sandbox id, pid, command fingerprint, workspace). `createE2BProcessRecoveryBackend` mirrors the Docker backend (`expectedSandboxId` / `expectedWorkspace` / `expectedLabels`). Filesystem-only `pause({ keepMemory: false })` reports process loss: `attachProcess` returns null after that snapshot. `connectE2BSandbox` reconnects by sandbox id without auto-resume; call `resume()` explicitly. See [Hosted sandboxes](hosted-sandboxes.md).
 
 ## Durable process recovery (plan 026 Task 5)
 
@@ -199,4 +200,5 @@ optionally `recoveryBackend` + `recoveryLimits`. With durability configured:
 - [Coding agent tools](coding-agent-tools.md): one-shot `shell` vs long-running sessions.
 - [Language intelligence](language-intelligence.md): LSP servers may later register as managed sessions.
 - [Coding security](coding-security.md): `SandboxProcessHandle` / optional `DisposableSandbox.startProcess`.
+- [Hosted sandboxes](hosted-sandboxes.md): E2B `pause`/`resume` and `prism-e2b-proc:` reconnect refs.
 - [Tool effects](tool-effects.md): unknown-outcome vocabulary mirrored by `markUnknown` / `process_unknown` / `reconcile`.

package/docs/prompt-registry.md

@@ -90,7 +90,7 @@ const v = await assertPromptPromotion({
 if (v.verdict === "promote") await store.put({ ...hostInput, body: v.candidate.body, labels: ["production"] });
 ```
 
-The verdict carries `promote`/`hold`, per-scorer `wins/losses/ties/failures`, `winRate`, the raw `ComparisonReport`, a redacted bounded `reportJson` (`serializeEvaluationReport`), and `reasons` on hold. The default gate holds unless the candidate wins strictly more scored comparisons than the baseline; `minimumWinRate` and `thresholds` add stricter gates, and threshold equality passes. Requires the optional peer `@arnilo/prism-core/governance/evals` (install it or the helper fails closed with `ERR_PRISM_PROMPT_EVALS_PEER`). Promotion itself stays a host decision: applying the verdict means `put`-ing a new version with labels — the helper never does.
+The verdict carries `promote`/`hold`, per-scorer `wins/losses/ties/failures`, `winRate`, the raw `ComparisonReport`, a redacted bounded `reportJson` (`serializeEvaluationReport`), and `reasons` on hold. The default gate holds unless the candidate wins strictly more scored comparisons than the baseline; `minimumWinRate` and `thresholds` add stricter gates, and threshold equality passes. Requires the optional peer `@arnilo/prism-core/governance/evals` (install it or the helper fails closed with `ERR_PRISM_PROMPT_EVALS_PEER`). Promotion itself stays a host decision: applying the verdict means `put`-ing a new version with labels — the helper never does. When provenance tracking is required, evaluation experiments bind candidate prompt versions via `EvalManifest.promptId` and `promptVersion`; release evidence also calls `validateReleaseEvalManifest` (see [Evaluations](evaluations.md#repeated-trials-and-manifests)).
 
 ## Limits and security
 

package/docs/provider-caching.md

@@ -166,7 +166,8 @@ Provider request policies can set `ProviderRequestOptions.cache` or the legacy `
 | `@arnilo/prism-providers/xai` | `implicit` | No `prompt_cache_key`. Package-local `x-grok-conv-id` is `sanitizeCacheKey(cache.key ?? cacheKey ?? sessionId, 128)`. | Same server + unchanged message prefix. Replay `reasoning_content` on reasoning models or the prefix breaks. | Conv-id is never a credential or SuperGrok token. Omitted when `cache.mode` is `off` or `cacheRetention` is `none`. `cached_tokens` → `cacheReadTokens` (inclusive or exclusive reports kept as-is). |
 | `@arnilo/prism-providers/clinepass` | `implicit` | No `cache_control` / `prompt_cache_key`. Gateway-owned prefix cache. | Resend unchanged prior history. Stream only. | Best-effort and backend-dependent (`cline-pass/*` slugs). `cached_tokens` / `prompt_cache_hit_tokens` map when present. |
 | `@arnilo/prism-providers/azure` | none | No Prism cache mapping. | Endpoint/model-specific. | Host owns Azure cache policy. |
-| `@arnilo/prism-providers/bedrock` | none | No Prism cache mapping. | Endpoint/model-specific. | Host owns Bedrock cache policy. |
+| `@arnilo/prism-providers/bedrock` (`compatible`) | none | No Prism cache mapping. | Endpoint/model-specific. | Host owns Bedrock cache policy. |
+| `@arnilo/prism-providers/bedrock` (`converse`) | `cache_control` | Prism breakpoints become standalone `cachePoint` blocks in `system`/message content; long retention adds `ttl: "1h"` when the model allows it. `tools` caching stays host-owned. | Stable prefix in the documented order `tools → system → messages`; changing an earlier section invalidates later ones. | `cacheReadInputTokens`/`cacheWriteInputTokens` map to `Usage.cacheReadTokens`/`Usage.cacheWriteTokens`; `inputTokens` is the non-cached remainder and is never folded. |
 | `@arnilo/prism-providers/vertex` | none | No Prism cache mapping. | Endpoint/model-specific. | Host owns Vertex cache policy. |
 
 Detailed first-party provider notes:
@@ -188,7 +189,7 @@ Detailed first-party provider notes:
 - DeepSeek (`@arnilo/prism-providers/deepseek`): `kind: "implicit"`. Official disk prefix cache is automatic (byte-identical prefix from token 0). Adapter sends no cache payload; tool `parameters` use shared `canonicalizeJsonSchema` (object keys + unordered `required` only; `enum`/`prefixItems`/`examples` keep caller order). `prompt_cache_hit_tokens` maps to `Usage.cacheReadTokens`. Caller-gated `listDeepSeekModels`.
 - xAI (`@arnilo/prism-providers/xai`): `kind: "implicit"`. Automatic prefix cache. Sticky `x-grok-conv-id` is a sanitized session/cache key (128 chars), never an OAuth access token. Reasoning models must replay `reasoning_content`. `prompt_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`. Caller-gated `listXaiModels`.
 - ClinePass (`@arnilo/prism-providers/clinepass`): `kind: "implicit"`. No explicit cache payload; multi-backend gateway may report `cached_tokens` or `prompt_cache_hit_tokens`. Static `cline-pass/*` catalog only — no `listClinePassModels`.
-- Azure, Bedrock, and Vertex: their OpenAI-compatible packages intentionally emit no Prism cache fields. Endpoint/model-specific cache controls remain host-owned rather than guessed from another provider family.
+- Azure, Bedrock, and Vertex: their OpenAI-compatible packages intentionally emit no Prism cache fields. Endpoint/model-specific cache controls remain host-owned rather than guessed from another provider family. Bedrock's native `converse` route is the exception: it is a documented cache-control surface (`cachePoint`, shared `applyCacheControl` markers) and maps cache usage fields instead of leaving them host-owned.
 
 ### NeuralWatt cache-aware limiter
 
@@ -303,6 +304,7 @@ for (const sample of report.samples) {
 ## Related APIs
 
 - [Input and prompt assembly](input-and-prompt-assembly.md): opt-in cache-aware ordering for stable provider payload prefixes.
+- [Attention compiler](attention-compiler.md): opt-in per-turn shrink that only rewrites rows *behind* the stable prefix, so cache hits survive.
 - [Provider request policies](provider-request-policies.md): set cache hints before provider calls.
 - [Model registry](model-registry.md): register `ModelConfig.cache` capability metadata.
 - [Provider layer](provider-layer.md): provider/model registries and provider events.

package/docs/provider-conformance.md

@@ -44,7 +44,7 @@ Offline conformance is mandatory for every package; credentialed probes are not
 | Ollama | cloud/local preset, reasoning/image mapping, implicit-cache fixture | Protected cloud or host-local authenticated daemon probe; no daemon starts in tests |
 | NeuralWatt | stream/retry/quota/telemetry fixtures, implicit-cache usage, headers/redaction | Protected `NEURALWATT_API_KEY` smoke |
 | Azure | endpoint preservation, Entra/resource-key header and OpenAI-compatible stream fixture | Protected host workload-identity probe |
-| Bedrock | SigV4/region/PrivateLink and OpenAI-compatible stream fixture | Protected host IAM/IRSA probe |
+| Bedrock | SigV4/region/PrivateLink, OpenAI-compatible stream fixture, and native Converse fixtures: body mapping (messages/system/tools/media/reasoning/structured output/cachePoint), canonical event-stream frame bytes with CRC/limit/truncation refusals, capability refusals before network I/O | Protected host IAM/IRSA probe for both routes |
 | Vertex | location/endpoint preservation, ADC header and OpenAI-compatible stream fixture | Protected host ADC/WIF probe |
 
 All rows must retain bounded request/response fixtures, abort propagation, provider-owned-header precedence, and fake-secret leak assertions where the package surfaces those values. A successful fake transport proves Prism mapping, not account entitlement or vendor availability.

package/docs/provider-packages.md

@@ -25,26 +25,26 @@ Do not use provider packages as a package manager, credential store, env loader,
 
 | adapter package | version |
 | --- | --- |
-| `@arnilo/prism-providers/ai-sdk` | 0.6.0 |
-| `@arnilo/prism-providers/alibaba` | 0.6.0 |
-| `@arnilo/prism-providers/anthropic` | 0.6.0 |
-| `@arnilo/prism-providers/azure` | 0.6.0 |
-| `@arnilo/prism-providers/bedrock` | 0.6.0 |
-| `@arnilo/prism-providers/clinepass` | 0.6.0 |
-| `@arnilo/prism-providers/commandcode` | 0.6.0 |
-| `@arnilo/prism-providers/deepseek` | 0.6.0 |
-| `@arnilo/prism-providers/google` | 0.6.0 |
-| `@arnilo/prism-providers/hyper` | 0.6.0 |
-| `@arnilo/prism-providers/kimi` | 0.6.0 |
-| `@arnilo/prism-providers/model-discovery` | 0.6.0 |
-| `@arnilo/prism-providers/neuralwatt` | 0.6.0 |
-| `@arnilo/prism-providers/ollama` | 0.6.0 |
-| `@arnilo/prism-providers/openai` | 0.6.0 |
-| `@arnilo/prism-providers/opencode-go` | 0.6.0 |
-| `@arnilo/prism-providers/openrouter` | 0.6.0 |
-| `@arnilo/prism-providers/vertex` | 0.6.0 |
-| `@arnilo/prism-providers/xai` | 0.6.0 |
-| `@arnilo/prism-providers/zai` | 0.6.0 |
+| `@arnilo/prism-providers/ai-sdk` | 0.7.0 |
+| `@arnilo/prism-providers/alibaba` | 0.7.0 |
+| `@arnilo/prism-providers/anthropic` | 0.7.0 |
+| `@arnilo/prism-providers/azure` | 0.7.0 |
+| `@arnilo/prism-providers/bedrock` | 0.7.0 |
+| `@arnilo/prism-providers/clinepass` | 0.7.0 |
+| `@arnilo/prism-providers/commandcode` | 0.7.0 |
+| `@arnilo/prism-providers/deepseek` | 0.7.0 |
+| `@arnilo/prism-providers/google` | 0.7.0 |
+| `@arnilo/prism-providers/hyper` | 0.7.0 |
+| `@arnilo/prism-providers/kimi` | 0.7.0 |
+| `@arnilo/prism-providers/model-discovery` | 0.7.0 |
+| `@arnilo/prism-providers/neuralwatt` | 0.7.0 |
+| `@arnilo/prism-providers/ollama` | 0.7.0 |
+| `@arnilo/prism-providers/openai` | 0.7.0 |
+| `@arnilo/prism-providers/opencode-go` | 0.7.0 |
+| `@arnilo/prism-providers/openrouter` | 0.7.0 |
+| `@arnilo/prism-providers/vertex` | 0.7.0 |
+| `@arnilo/prism-providers/xai` | 0.7.0 |
+| `@arnilo/prism-providers/zai` | 0.7.0 |
 <!-- generated:package-truth:providers end -->
 
 
@@ -61,7 +61,7 @@ Do not use provider packages as a package manager, credential store, env loader,
 | `@arnilo/prism-providers/hyper` | `api_key` only | No subscription OAuth — Charm Hyper is pay-per-use Hypercredits; host supplies `HYPER_API_KEY` (keys start `sk-hyper-`). |
 | `@arnilo/prism-providers/commandcode` | `api_key` only | No subscription OAuth — Command Code Go/GOAT/Pro/Max coding plans and the Provider plan all authenticate with the same Studio API key; host supplies `COMMAND_CODE_API_KEY`. |
 | `@arnilo/prism-providers/azure` | host Entra token or Azure resource key | Workload identity via `credential` callback; endpoint host preserved ([docs](providers/azure.md)). |
-| `@arnilo/prism-providers/bedrock` | host IAM/IRSA credentials | SigV4 over OpenAI-compatible Bedrock Runtime; region/PrivateLink preserved ([docs](providers/bedrock.md)). |
+| `@arnilo/prism-providers/bedrock` | host IAM/IRSA credentials | SigV4 over either the OpenAI-compatible Bedrock Runtime route (default) or the native model-agnostic Converse/ConverseStream route (`api: "converse"`); region/PrivateLink preserved ([docs](providers/bedrock.md)). |
 | `@arnilo/prism-providers/vertex` | host ADC / workload token | OpenAPI-compatible Vertex endpoint; separate from consumer Google package ([docs](providers/vertex.md)). |
 
 A future provider-local OAuth package must first have explicit third-party permission and documented authorize/token/refresh flow. Before it registers an OAuth descriptor, it must add bounded request/response, abort, PKCE/state where required, expiry/refresh, secret-redaction, durable-store round-trip, and offline protocol tests. Do not add a generic OAuth framework, CLI credential scanner, automatic refresh timer, or success stub.
@@ -139,7 +139,7 @@ Every package remains explicit, setup-zero-fetch, and late-credential-bound. `Mo
 | xAI | OpenAI-compatible Completions; caller-gated list | text, image | tool deltas, `reasoning_content` replay | implicit + `x-grok-conv-id`; protected API-key smoke; SuperGrok login operator-only |
 | ClinePass | OpenAI-compatible stream-only; static `cline-pass/*` catalog | text | tool deltas, per-model `reasoning_effort` | implicit; protected API-key smoke |
 | Azure | Azure/Foundry OpenAI-compatible; host models | selected endpoint/model capability | normalized OpenAI-compatible tools | no Prism cache mapping; protected host workload-identity probe |
-| Bedrock | Bedrock OpenAI-compatible; host models | selected endpoint/model capability | normalized OpenAI-compatible tools | no Prism cache mapping; protected host IAM/IRSA probe |
+| Bedrock | Bedrock OpenAI-compatible (default) or native Converse/ConverseStream; host models | selected endpoint/model capability; native route refuses denied/unknown capabilities before request | normalized OpenAI-compatible tools or Converse `toolSpec`/`toolUse` deltas | compatible route: no Prism cache mapping; native route maps `cachePoint` breakpoints; protected host IAM/IRSA probe |
 | Vertex | Vertex OpenAPI-compatible; host models | selected endpoint/model capability | normalized OpenAI-compatible tools | no Prism cache mapping; protected host ADC/WIF probe |
 
 ### First-party cache behavior

package/docs/providers/bedrock.md

@@ -2,11 +2,54 @@
 
 ## What it does
 
-`@arnilo/prism-providers/bedrock` registers an Amazon Bedrock Runtime OpenAI-compatible Chat Completions provider. Hosts supply IAM/IRSA/assumed-role credentials; the package signs requests with SigV4 (no AWS SDK). Region and optional PrivateLink endpoint URLs are preserved.
+`@arnilo/prism-providers/bedrock` registers an Amazon Bedrock Runtime provider with two explicit routes:
+
+| Route | Wire API | Select with |
+| --- | --- | --- |
+| `compatible` (default) | OpenAI-compatible Chat Completions at `/openai/v1/chat/completions` | `createBedrockProvider` / `api: "compatible"` |
+| `converse` | Native model-agnostic `Converse` and `ConverseStream` | `createBedrockConverseProvider` / `api: "converse"` |
+
+Hosts supply IAM/IRSA/assumed-role credentials; the package signs requests with SigV4 (no AWS SDK). Region and optional PrivateLink endpoint URLs are preserved.
 
 ## When to use it
 
-Use it for enterprise Bedrock access under workload identity. Do not embed long-lived keys in fixtures. Use model-router residency policy to deny disallowed regions.
+Use it for enterprise Bedrock access under workload identity. Do not embed long-lived keys in fixtures. Use model-router residency policy to deny disallowed regions. Use the `converse` route when the model only exists on Converse (tool use, reasoning, prompt caching, and structured output for Anthropic/Nova/OpenAI families), and keep `compatible` when an OpenAI-shaped gateway is what the deployment standardizes on.
+
+## Route selection
+
+```ts
+import { createBedrockConverseProvider, createBedrockProviderPackage } from "@arnilo/prism-providers/bedrock";
+
+// Package form: one provider id, selected route, optional non-streaming mode.
+createBedrockProviderPackage({
+  region: "eu-west-1",
+  credential: () => hostAwsCredentials(),
+  api: "converse", // or "compatible" (default)
+  stream: true, // native route only: ConverseStream (default) vs one Converse call
+  models: [{ provider: "bedrock", model: "eu.anthropic.claude-haiku-4-5-20251001-v1:0" }],
+});
+
+// Factory form (same options, no registry wiring):
+const provider = createBedrockConverseProvider({ region: "us-east-1", credential });
+```
+
+Routes are mutually exclusive per provider id, so a host that needs both registers the second provider under a different `id` and model bindings. The package records the selected route in `ProviderPackage.metadata.route` and in the registered auth method metadata.
+
+## Capability matrix
+
+| Capability | `compatible` | `converse` |
+| --- | --- | --- |
+| Text streaming | yes (OpenAI SSE) | yes (`ConverseStream` event stream) |
+| Non-streaming | n/a (always streams) | yes (`stream: false`, one `Converse` response mapped to deltas + done) |
+| Images | model-dependent OpenAI image parts | `image` blocks (`png`/`jpeg`/`gif`/`webp`); unknown media types refuse before the request |
+| PDF documents | n/a | `document` blocks (`format` from media type); non-PDF files refuse |
+| Tools | OpenAI `tools` | `toolConfig.tools[].toolSpec`, streamed `toolUse` deltas, `toolResult` in the following user turn |
+| Reasoning/thinking | sanitized `reasoning_effort` / `reasoning` object | Anthropic-family `thinking` (`enabled`/`disabled`/`adaptive`, budget validated) and OpenAI-family `reasoning_effort` in `additionalModelRequestFields`; reasoning deltas map to Prism thinking blocks with signatures |
+| Prompt caching | none (no Prism cache fields emitted) | `cachePoint` blocks from Prism cache breakpoints, `ttl: "1h"` for long retention; usage reports `cacheReadTokens` / `cacheWriteTokens` |
+| Structured output | body passthrough only | `outputConfig.textFormat` JSON schema (requires `capabilities.structuredOutput`) |
+| Usage | OpenAI usage | `inputTokens`/`outputTokens`/`totalTokens` + cache read/write |
+
+Every feature above is tested offline against recorded frame/body fixtures; the live probe below covers text, tools, and usage. Features are not inferred from compatible endpoints.
 
 ## Inputs / request
 
@@ -34,6 +77,8 @@ Default public base: `https://bedrock-runtime.{region}.amazonaws.com` → `/open
 
 OpenAI-compatible SSE mapped to Prism provider events. Missing credentials fail closed before network I/O.
 
+Native route: `ConverseStream` frames are decoded from `application/vnd.amazon.eventstream` (prelude/header lengths and both CRC32 checksums validated, 1 MiB default frame ceiling, 24 MiB hard spec ceiling) and mapped to Prism provider events. `:message-type: exception` frames become `error` events with the exception name and message; a stream that ends without `messageStop` or with an incomplete tool block fails loudly instead of returning partial output as success. Credentials are resolved once per request and redacted from provider errors.
+
 ## Request/response example
 
 ```http
@@ -51,11 +96,26 @@ const provider = createBedrockProvider({
 });
 ```
 
+Native route request:
+
+```http
+POST https://bedrock-runtime.eu-west-1.amazonaws.com/model/eu.anthropic.claude-haiku-4-5-20251001-v1%3A0/converse-stream
+Accept: application/vnd.amazon.eventstream
+Authorization: AWS4-HMAC-SHA256 Credential=…/eu-west-1/bedrock/aws4_request, …
+
+{ "messages": [{ "role": "user", "content": [{ "text": "hi" }] }],
+  "inferenceConfig": { "maxTokens": 4096 } }
+```
+
+The `Converse` and `ConverseStream` operations share one request body; `accept` and the URL suffix select the operation. Inference-profile model ids (`eu.`/`us.` prefixes) are percent-encoded into the path, and region/endpoint policy is unchanged from the compatible route.
+
 Live canaries stay opt-in behind host credentials; default tests are network-free.
 
 ## Extension and configuration notes
 
-Uses Bedrock’s OpenAI-compatible runtime route (not Converse eventstream). Hosts needing Converse-only models should supply a custom provider or AI SDK bridge.
+The compatible route uses Bedrock’s OpenAI-compatible runtime route (not Converse eventstream). The native route (`api: "converse"`) covers Converse-only models and features; both stay explicit, and neither silently falls back to the other.
+
+Model-specific fields (for example `top_k`) come from `ModelConfig.parameters` leftovers plus the sanitized `compat.thinking` / `compat.reasoning_effort` keys; opaque `compat` keys are not spread onto the Converse body, and `toolChoice` is only forwarded when it is `auto`/`any`/`required` or `{ tool: { name } }`.
 
 ## Request construction (0.5.1)
 
@@ -71,12 +131,14 @@ See [Provider request policies](../provider-request-policies.md).
 
 ## Security and performance notes
 
-- No AWS SDK; package-local SigV4 only for `bedrock` service.
+- No AWS SDK; package-local SigV4 only for `bedrock` service on both routes.
 - Input headers are normalized once before signing: names are lowercased and duplicate-case keys merge last-wins, so the canonical request always matches the signed header list (no duplicate-case mismatch); query parameters are canonicalized sorted by encoded key then value.
 - Private endpoint hosts are not rewritten to public DNS.
 - Conformance-proven (Task 6): package `setup()` performs zero fetch and zero credential resolution; an already-aborted signal fails fast; a truncated SSE stream (no `data: [DONE]`) ends in an `error` event; native Bedrock caching (`Converse cachePoint`) is intentionally unsupported on the OpenAI-compatible route — no cache wire fields are emitted even when the request carries Prism cache hints.
+- Native route: `ConverseStream` frames are capped at 1 MiB (24 MiB hard spec ceiling) and a non-streaming `Converse` body is read under a 4 MiB ceiling (`BEDROCK_CONVERSE_RESPONSE_MAX_BYTES`), so a hostile or runaway response cannot exhaust memory.
+- Native route: denied/unknown capabilities (`streaming: false` with the streaming route, `tools: false` with tools, `structuredOutput` undeclared, `reasoning: false` with a thinking/effort request, unsupported media types) refuse before any request is sent; corrupt or oversized event-stream frames terminate the stream rather than resyncing.
 - Credential secrets are redacted from provider errors.
-- No credential prefetch at import.
+- No credential prefetch at import on either route.
 
 ## Live probe
 
@@ -87,11 +149,13 @@ PRISM_LIVE_PROVIDER_TESTS=1 AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... AWS_
   node --test packages/prism-providers/dist/bedrock/__tests__/live.test.js
 ```
 
-`PRISM_LIVE_BEDROCK_MODEL` overrides the probed model (default `us.anthropic.claude-haiku-4-5-20251001-v1:0`). Without credentials the suite skips.
+`PRISM_LIVE_BEDROCK_MODEL` overrides the probed model (default `us.anthropic.claude-haiku-4-5-20251001-v1:0`). The same suite also probes the native route (streaming text/tools/usage and one non-streaming `Converse` call). Without credentials the suite skips.
 
 ## Thinking and reasoning
 
-Bedrock OpenAI-compat chat expects snake_case `reasoning_effort` (with `effort`/`reasoningEffort` aliases) or a sanitized `reasoning` object. OpenAI-family models on Bedrock snap effort to their declared levels (gpt-5.1 → `none/low/medium/high`); non-OpenAI models pass through untouched. See [Thinking and reasoning](../thinking-and-reasoning.md).
+Compatible route: Bedrock OpenAI-compat chat expects snake_case `reasoning_effort` (with `effort`/`reasoningEffort` aliases) or a sanitized `reasoning` object. OpenAI-family models on Bedrock snap effort to their declared levels (gpt-5.1 → `none/low/medium/high`); non-OpenAI models pass through untouched.
+
+Native route: Anthropic-family models take `additionalModelRequestFields.thinking` (`{type: "enabled"|"disabled"|"adaptive", budget_tokens?}`); a bare `enabled` gets a default budget so it can never reach the wire without one, and historical thinking blocks replay with signatures when `compat.preserveThinking` is on (default: when the model declares `capabilities.reasoning`). OpenAI-family models take `additionalModelRequestFields.reasoning_effort`, snapped to declared levels. See [Thinking and reasoning](../thinking-and-reasoning.md).
 
 ## Related APIs
 

package/docs/providers/openai.md

@@ -52,7 +52,7 @@ uses official Responses `reasoning: { effort, summary? }` via
 | --- | --- |
 | Provider stream | Prism text, thinking (downgraded to text), host `tool_call` deltas/finals, provider-hosted `tool_call` events (`authority: "provider-hosted"`), `continuation_required`, `usage`, `done`, and redacted `error` events. |
 | Continuation | An incomplete Responses stream self-resumes at most eight HTTP hops using opaque `previous_response_id`; a cursor is at most 4 KiB, is never replayed, and is observable as `continuation_required`. |
-| Realtime | `createOpenAIRealtimeSession()` exposes server-session creation, audio in/out, transcript deltas, provider-hosted calls, interrupt, and idempotent close through the neutral `RealtimeSession` seam. |
+| Realtime | `createOpenAIRealtimeSession()` exposes server-session creation, audio in/out, transcript deltas, host `function_call` items, provider-hosted calls, `usage`, `completeTool`, interrupt, and idempotent close through the neutral `RealtimeSession` seam. Host orchestration is [Realtime voice](../realtime-voice.md). |
 | Block preservation | User/system text → `input_text`; assistant text → `output_text`; assistant host `tool_call` → top-level `function_call` with `call_id`; provider-hosted calls are not replayed; `tool_result` → top-level `function_call_output`; images/files/audio when declared on the model. Bare thinking without an encrypted Responses reasoning item is omitted on replay. |
 | Auth methods | `api_key` for `openai`; host-invoked subscription `oauth` for `openai-codex`. xAI SuperGrok is the other first-party subscription OAuth flow ([xAI](xai.md)). |