@arnilo/prism 0.0.96 → 0.1.0

package/docs/policy-and-audit.md

@@ -0,0 +1,171 @@
+# Policy and audit
+
+## What it does
+
+`@arnilo/prism-policy` records redacted allow/deny/modify/approval decisions with policy version, actor refs from verified `AgentIdentity`, target, reason, expiry, and evidence references. Hosts export cursor-paginated pages to append-only/WORM sinks. The package does not embed a mandatory global policy engine, KMS, or cloud WORM SDK.
+
+## When to use it
+
+Use it when enterprise hosts need an attributable audit trail alongside existing guardrails, permission checks, and tool-approval interruptions. Skip it for single-tenant apps that only need `RunLedger` / guardrail events.
+
+Do not store unrestricted prompts, tool argument bodies, JWTs, or credential secrets on decision records. Do not treat the reference memory/file adapters as production WORM.
+
+## Inputs / request
+
+| API / field | Meaning |
+| --- | --- |
+| `createPolicyEvaluator({ policyId, policyVersion, evaluate })` | Host rule callback stamped with immutable id/version |
+| `PolicyEvaluateRequest` | Verified `identity`, `action`, `resource`, optional evaluator-only `context` (never persisted) |
+| `AppendPolicyDecisionInput` | Decision fields + verified identity; ownership from identity or explicit scope |
+| `createMemoryPolicyDecisionStore` / `createFilePolicyDecisionStore` | Append-only reference ledgers |
+| `exportPolicyDecisions({ store, ownership, cursor, limit, sink? })` | Cursor pages; optional host WORM sink |
+| `recordGuardrailDecision` / `recordPermissionDecision` / `recordToolApprovalDecision` | Optional bridges from existing decision points |
+
+Frozen caps (default / hard): decision `8 KiB / 64 KiB`, reason or evidence ref `1 KiB / 8 KiB`, export page `100 / 500`.
+
+## Outputs / response / events
+
+- `PolicyDecisionRecord` — frozen redacted row (`actor` refs, `evidenceRefs`, no payload blob).
+- `evaluateAndAppend` — evaluate then append in one call.
+- Policy version mismatch (`requirePolicyVersion`) and unrestricted payload keys fail closed (`ERR_PRISM_POLICY_VERSION` / `ERR_PRISM_POLICY_PAYLOAD`).
+- Missing/expired/unverified identity fails via core `assertIdentityActive` before append.
+
+## Request/response example
+
+```json
+{
+  "id": "dec-1",
+  "policyId": "mail",
+  "policyVersion": "2026-07-23",
+  "outcome": "approval",
+  "actor": {
+    "tenantId": "tenant-1",
+    "userId": "user-1",
+    "principalId": "agent-42",
+    "principalKind": "agent",
+    "sponsorId": "sponsor-7"
+  },
+  "target": { "kind": "draft", "id": "d1" },
+  "reason": "external send",
+  "evidenceRefs": ["rule:external"],
+  "createdAt": "2026-07-23T12:00:00.000Z",
+  "tenantId": "tenant-1",
+  "userId": "user-1"
+}
+```
+
+## Implementation example
+
+```ts
+import { type AgentIdentity } from "@arnilo/prism";
+import {
+  createFilePolicyDecisionStore,
+  createPolicyEvaluator,
+  evaluateAndAppend,
+  exportPolicyDecisions,
+  recordToolApprovalDecision,
+} from "@arnilo/prism-policy";
+
+const evaluator = createPolicyEvaluator({
+  policyId: "mail",
+  policyVersion: "2026-07-23",
+  evaluate: ({ action }) =>
+    action === "mail.send"
+      ? { outcome: "approval", reason: "external send", evidenceRefs: ["rule:external"] }
+      : { outcome: "allow" },
+});
+
+const store = createFilePolicyDecisionStore({
+  path: "/var/prism/policy-decisions.jsonl",
+  requirePolicyVersion: "2026-07-23",
+});
+
+await evaluateAndAppend(
+  { identity, action: "mail.send", resource: { kind: "draft", id: "d1" } },
+  { store, evaluator, id: crypto.randomUUID() },
+);
+
+await recordToolApprovalDecision({
+  store,
+  evaluator,
+  id: crypto.randomUUID(),
+  identity,
+  toolName: "mail.send",
+  toolCallId: "call-1",
+  evidenceRef: "run:abc/tool:call-1",
+});
+
+for await (const page of exportPolicyDecisions({
+  store,
+  tenantId: identity.tenantId,
+  userId: identity.userId,
+  sink: { async write(records) { await worm.append(records); } },
+})) {
+  void page;
+}
+```
+
+## Extension and configuration notes
+
+Policy is optional. Hosts wire `record*` helpers or `evaluateAndAppend` at permission/guardrail/tool-approval/router/connector boundaries. Model-router and work-connector packages (later Phase 8 tasks) may call the same store when configured. Replace file/memory adapters with host WORM/KMS without changing record shape.
+
+## Security and performance notes
+
+- Approvals require verified `AgentIdentity`; actor fields are refs only.
+- Policy version pin fails closed on mismatch.
+- Unrestricted payload field names (`prompt`, `body`, `toolArguments`, …) are rejected before append.
+- Evaluate/append are O(fields) and network-free in-package; remote WORM I/O stays in the host sink/adapter.
+- Export never full-scans: page size is capped; raise hard caps only with Phase 8 freeze + tests + docs updates.
+
+## OPA external policy adapter (`@arnilo/prism-policy/opa`, 0.0.28)
+
+Optional `createOpaPolicyEvaluator` evaluates `PolicyEvaluateRequest`s against a host-pinned OPA REST endpoint (`POST /v1/data/<path>` with `{"input": <document>}`) and returns a core `PolicyEvaluator` for `evaluateAndAppend`. Native `fetch` only; no OPA SDK dependency.
+
+| Option | Meaning |
+| --- | --- |
+| `url` / `policyId` / `policyVersion` | Pinned decision URL + immutable ledger attribution |
+| `mapInput` | Input builder (default: redacted actor refs — tenant/account/user/principal/sponsor/scopes + action + resource; never prompts, tool args, JWTs, or credentials; `context` omitted by design) |
+| `mapDecision` | Decision mapper (default: boolean, `{allow}`, or `{outcome, reason?, evidenceRefs?, expiresAt?}`) |
+| `onFailure` | `deny` (default) returns a recorded deny result on OPA failures; `escalate` rethrows the `PolicyError` |
+| `requirePolicyVersion` | Sends `provenance=true` and requires a matching OPA bundle revision (stale/missing fails closed) |
+| `timeoutMs` / `maxInputBytes` / `maxResponseBytes` / `maxRetries` | Bounded caps (2 s/30 s, 16/256 KiB, 64 KiB/1 MiB, 0/2 retries — only timeout/transport/5xx retried) |
+| `redactor` | `SecretRedactor` applied to OPA-provided `reason`/`evidenceRefs` before they leave the adapter |
+| `ssrf` | `SsrfPolicy` for the endpoint; denials surface `MediaContentError` (`ssrf_denied`) |
+
+```ts
+import { createOpaPolicyEvaluator } from "@arnilo/prism-policy/opa";
+import { createPostgresEnterpriseState } from "@arnilo/prism-enterprise-postgres";
+import { evaluateAndAppend } from "@arnilo/prism-policy";
+
+const evaluator = createOpaPolicyEvaluator({
+  url: "https://opa.internal:8181/v1/data/prism/allow",
+  policyId: "opa-prism",
+  policyVersion: "2026-08-01",
+});
+const state = await createPostgresEnterpriseState({ pool, schema: "prism" });
+await evaluateAndAppend(request, { store: state.policy, evaluator, id: crypto.randomUUID() });
+```
+
+Fail-closed codes: `ERR_PRISM_OPA_TIMEOUT`, `ERR_PRISM_OPA_TRANSPORT`, `ERR_PRISM_OPA_RESPONSE_PARSE`, `ERR_PRISM_OPA_RESPONSE_BOUNDS`, `ERR_PRISM_OPA_DECISION_MAPPING`, `ERR_PRISM_OPA_VERSION_MISMATCH`. Redirects are never followed; response bodies are read with a hard cap; caller aborts propagate (never converted to a policy outcome); timeout/parse/bounds/version failures record a deny row through `evaluateAndAppend`, so the durable Phase 6 ledger captures them unchanged.
+
+## PostgreSQL enterprise state (0.0.23)
+
+For durable multi-replica policy decisions, construct [`createPostgresEnterpriseState`](enterprise-postgres-state.md) and pass its `policy` store to the existing helpers. PostgreSQL keeps the same append/query contract, requires tenant scope and verified identity at append, binds owner data into opaque cursors, validates record bounds on read, and rejects duplicate ids. Memory and JSONL remain development/reference adapters, not production WORM or cross-replica stores.
+
+```ts
+const state = await createPostgresEnterpriseState({ pool, schema: "prism" });
+await evaluateAndAppend(request, { store: state.policy, evaluator, id: crypto.randomUUID() });
+```
+
+`state.close()` leaves a caller-owned pool open. Run `state.cleanup(...)` from an authorized host schedule only when expiration cleanup is needed; it does not run in the background.
+
+## Related APIs
+
+- [Model routing](model-routing.md)
+- [Agent identity](agent-identity.md)
+- [Guardrails](guardrails.md)
+- [Runs and usage ledger](runs-and-usage.md)
+- [Workflows](workflows.md): proactive schedule capability enable/revoke events bridge here via `onCapability`.
+- [Host security](host-security.md)
+- [Enterprise PostgreSQL state](enterprise-postgres-state.md): durable policy/evaluation/work/router composition.
+- Package README: [`@arnilo/prism-policy`](../packages/policy/README.md)

package/docs/ponytail.md

@@ -0,0 +1,127 @@
+# Ponytail behavior integration
+
+## What it does
+
+`@arnilo/prism-ponytail` is an optional package that wires [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) into Prism contribution contracts.
+
+It registers upstream skills and commands, injects active mode instructions via upstream `getPonytailInstructions` / `filterSkillBodyForMode`, and persists mode as session custom `ponytail-mode` entries. Import is inert; missing upstream fails closed at `setup` with a bounded redacted error.
+
+## When to use it
+
+Use it when a host wants lazy-minimalism coding behavior (`lite`, `full`, `ultra`) with upstream Ponytail skills (`ponytail-audit`, `ponytail-debt`, `ponytail-gain`, `ponytail-help`, `ponytail-review`) in a Prism extension kernel.
+
+Install optional peer `@dietrichgebert/ponytail@^4.8.4` **or** pass `upstreamPath` to a checkout with `skills/` and `hooks/`.
+
+Pair with progressive disclosure: mode slices on the `ponytail-mode` injector; full skill bodies via `load_skill` only.
+
+## Inputs / request
+
+`createPonytailExtension(options)`:
+
+| Field | Type | Required | Purpose |
+| --- | --- | --- | --- |
+| `upstreamPath` | `string` | no | Override path to Ponytail root; default resolves optional peer package. |
+| `defaultMode` | `PonytailMode` | no | Initial mode when no session entry exists (default `full`). |
+| `quietStartup` | `boolean` | no | Suppress startup status events. |
+| `appendEntry` | `(entry, opts?) => Promise<void>` | yes | Host session append (OM `attach` pattern). |
+| `getEntries` | `() => readonly SessionEntry[] \| Promise<...>` | yes | Current branch entries for mode restore. |
+| `configPath` | `string` | no | Bounded local config for `defaultMode` / `quietStartup` / `hideStatus`. |
+
+`PonytailMode`: `off` \| `lite` \| `full` \| `ultra`.
+
+Session custom entry shape:
+
+```json
+{ "kind": "custom", "data": { "type": "ponytail-mode", "mode": "full" } }
+```
+
+Registered skills: `ponytail`, `ponytail-audit`, `ponytail-debt`, `ponytail-gain`, `ponytail-help`, `ponytail-review`.
+
+Registered commands: `ponytail`, `ponytail-review`, `ponytail-audit`, `ponytail-gain`, `ponytail-debt`, `ponytail-help`.
+
+`ponytail` command actions: `lite|full|ultra|off`, `status`, `default <mode>`.
+
+## Outputs / response / events
+
+| Export | Purpose |
+| --- | --- |
+| `createPonytailExtension(options)` | Returns an inert `Extension` until `kernel.load([...])`. |
+| `ponytail-mode` injector | `InstructionInjector` calling upstream `getPonytailInstructions(mode)`. |
+| `ponytail` command | Set mode, report status, or persist default mode to config file. |
+| Alias commands | Dispatch `{ skill, dispatch: "load_skill" }` for companion skills. |
+| `ponytail:status` / `ponytail:loaded` events | Optional host metadata (no statusline shell scripts). |
+
+Deactivation: exact phrases `stop ponytail` and `normal mode`.
+
+## Request/response example
+
+```json
+{ "command": "ponytail", "args": { "mode": "lite" }, "sessionId": "s1" }
+```
+
+```json
+{ "kind": "custom", "data": { "type": "ponytail-mode", "mode": "lite" } }
+```
+
+## Implementation example
+
+```ts
+import { createPonytailExtension } from "@arnilo/prism-ponytail";
+import {
+  createExtensionKernel,
+  createLoadSkillTool,
+  createLoadedSkillSet,
+  createMemorySessionStore,
+  createSkillRegistry,
+} from "@arnilo/prism";
+
+const store = createMemorySessionStore();
+const callbacks = {
+  appendEntry: async (entry, options) => store.append(entry, options),
+  getEntries: async () => store.list("s1"),
+};
+
+const kernel = createExtensionKernel({ errorPolicy: "throw" });
+await kernel.load([
+  createPonytailExtension({
+    upstreamPath: undefined, // optional peer @dietrichgebert/ponytail
+    defaultMode: "full",
+    quietStartup: true,
+    ...callbacks,
+  }),
+]);
+
+const registry = createSkillRegistry(kernel.registries.skills.list());
+const loaded = createLoadedSkillSet();
+const loadSkill = createLoadSkillTool({ registry, loaded });
+
+await kernel.registries.commands.get("ponytail")!.execute({ mode: "lite" }, { sessionId: "s1" });
+// Select instructionInjectors: ["ponytail-mode"] on runs that should receive mode slices.
+```
+
+See `examples/caveman-ponytail.ts` for combined Caveman + Ponytail progressive disclosure demo (network-free fixtures).
+
+## Extension and configuration notes
+
+- Import alone registers nothing (`sideEffects: false`); no timers, watchers, network, or shell scripts.
+- Upstream hook modules load via `createRequire` from resolved root — instruction strings are not forked in Prism.
+- Mode restore scans `getEntries()` for latest `data.type === "ponytail-mode"` (OM attach pattern).
+- `ponytail-subagent` hook is not wired; nested-agent behavior is host responsibility.
+- No TUI statusline scripts; use `ponytail status` command or extension events.
+- Not included in `@arnilo/prism-code` or `@arnilo/prism-sdk` profiles — opt-in install only.
+
+## Security and performance notes
+
+- Upstream text is untrusted; reads bounded (`MAX_SKILL_FILE_BYTES` 256 KiB, `MAX_INJECTED_INSTRUCTION_BYTES` 32 KiB).
+- Config writes only to host `configPath` with size cap (`MAX_CONFIG_FILE_BYTES` 16 KiB).
+- Errors redact absolute paths and home directories.
+- O(skills) setup scan; O(1) mode tracking per turn; no background workers.
+
+## Related APIs
+
+- [Caveman behavior integration](caveman.md): complementary terse-communication mode package.
+- [Extension kernel and event bus](extensions.md): explicit `kernel.load`.
+- [Context and skills](context-and-skills.md): progressive catalog + `load_skill`.
+- [Instruction injection](instruction-injection.md): `ponytail-mode` injector.
+- [Observational memory compaction package](compaction-observational-memory.md): session callback attach pattern.
+- [Migration guide](migration.md): `0.0.21 → 0.0.22` notes.

package/docs/postgres-persistence.md

@@ -4,7 +4,7 @@
 
 The optional `@arnilo/prism-session-store-postgres` package ships a production-oriented PostgreSQL adapter that implements:
 
-- `SessionStore` — atomic `append` / `list` / `get` / `readBranchPath`
+- `SessionStore` — atomic `append` / `list` / `get` / `readBranchPath` / bounded `searchSessions` / bounded `searchSessions`
 - `RunLedger` — durable run, event, tool-call, and usage rows
 - `ProductionPersistenceStore` — cursor-paginated `query*` reads plus generic `checkpoints` and atomic `leases` capabilities
 
@@ -24,7 +24,7 @@ Use this package when you need server-backed persistence with pooled connections
 - managed cloud databases (RDS, Cloud SQL, Neon, Supabase, etc.)
 - CI integration tests against a real PostgreSQL service
 
-Prefer [`@arnilo/prism-session-store-sqlite`](sqlite-persistence.md) for local CLI tools, single-writer workloads, and network-free default tests. This adapter stores sessions/runs, not semantic vectors; use the separate [`@arnilo/prism-memory` pgvector path](working-and-semantic-memory.md), which rejects non-finite vectors before SQL, when vector recall is needed.
+Prefer [`@arnilo/prism-session-store-sqlite`](sqlite-persistence.md) for local CLI tools, single-writer workloads, and network-free default tests. This adapter stores sessions/runs, not semantic vectors; use the separate [`@arnilo/prism-memory` pgvector path](working-and-semantic-memory.md), which rejects non-finite vectors before SQL, when vector recall is needed. For durable policy decisions, evaluations, work mutation idempotency, and model-router state, use the separate [`@arnilo/prism-enterprise-postgres`](enterprise-postgres-state.md) composition; it has its own migration history and does not replace session/run persistence.
 
 ## Inputs / request
 
@@ -40,6 +40,8 @@ import { createPostgresPersistence } from "@arnilo/prism-session-store-postgres"
 | `schema` | `string` | PostgreSQL schema for Prism tables. Defaults to `"prism"`. Validated and double-quoted. |
 | `poolMax` | `number` | Maximum pool size for adapter-owned pools. Defaults to `10`. |
 | `feedbackRedactor` | `SecretRedactor` | Optional redaction for feedback comment/tags/metadata before insert. |
+| `eventSource` | `AgentEventSourceOptions` | Bounds durable event pages, subscribers, polling, reconnects, and cleanup. |
+| `eventCursorSecret` | `string \| Uint8Array` | Stable HMAC secret shared by replicas that resume durable event cursors. |
 | `poolConfig` | `PoolConfig` | Additional `pg` options (TLS, idle timeout, application name, etc.). |
 
 Hosts own TLS (`ssl` in `poolConfig`), credentials, connection limits, and backup/retention enforcement.
@@ -54,12 +56,13 @@ Hosts own TLS (`ssl` in `poolConfig`), credentials, connection limits, and backu
 | `SessionStore.list` / `get` | Indexed reads by `session_id` and primary key. |
 | `SessionStore.readBranchPath` | Recursive ancestor query from `leafId` (or latest leaf) in root→leaf order. |
 | `RunLedger.append*` | Inserts run/event/tool/usage rows; events receive monotonic per-run `sequence` values. |
+| `events` | Durable `AgentEventSource`; `LISTEN`/`NOTIFY` only wakes exact owned indexed reads, while polling remains recovery fallback. |
 | `ProductionPersistenceStore.query*` | Parameterized cursor pagination on indexed columns with tenant/account/user filters. |
 | `checkpoints` | Generic versioned `CheckpointStore` backed by `prism_checkpoints`; ownership, CAS/fencing checks, bounded pagination, and workflow suspended/denied/schedule/state/replay values without a schema migration. |
 | `leases` | Atomic `LeaseStore` backed by `prism_leases`; database-clock expiry, opaque renew/release token, monotonic takeover fence. |
 | `close()` | Ends the pool when the adapter created it from `connectionString`. |
 
-Migrations run automatically on open and are idempotent across reopen. Concurrent setup uses per-schema advisory transaction locks. While holding that lock, startup verifies ordered contract name/version/SHA-256 rows and full schema-v3 `information_schema`/catalog shape (all required tables, columns/types/nullability/defaults, PK/unique/FK keys, and named indexes) before any runtime write. A complete legacy 0.0.5 history with all `checksum` values `NULL` is shape-verified then backfilled transactionally once. Unknown, duplicate, out-of-order, partial-legacy, checksum, or shape drift rejects open; restore or apply reviewed DDL rather than editing migration rows.
+Migrations run automatically on open and are idempotent across reopen. Concurrent setup uses per-schema advisory transaction locks. While holding that lock, startup verifies ordered contract name/version/SHA-256 rows and full schema-v7 `information_schema`/catalog shape (all required tables, columns/types/nullability/defaults, PK/unique/FK keys, and named indexes) before any runtime write. A complete legacy 0.0.5 history with all `checksum` values `NULL` is shape-verified then backfilled transactionally once. Unknown, duplicate, out-of-order, partial-legacy, checksum, or shape drift rejects open; restore or apply reviewed DDL rather than editing migration rows.
 
 ## Request/response example
 
@@ -116,7 +119,7 @@ PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres --workspace @arnil
 - The package is optional and workspace-local; `@arnilo/prism` core has no PostgreSQL dependency.
 - Schema names must match `^[a-zA-Z_][a-zA-Z0-9_]*$`; the adapter quotes them and never interpolates user values into identifier positions.
 - `SessionAppendOptions` idempotency rows are durable in `prism_session_append_idempotency` and survive reopen.
-- Schema version **3** applies `001_init`, additive `002_usage_scope`, and `003_run_feedback`. Migration 003 adds immutable `prism_run_feedback` rows with run FK/cascade deletion and owner/run/trace cursor indexes. `persistence.feedback` validates exact run ownership, bounds/redacts through optional `feedbackRedactor`, queries bounded pages, and deletes only exact-owned IDs. SQLite shares the same model with dialect-local DDL.
+- Schema version **6** applies `001_init`, `002_usage_scope`, `003_run_feedback`, `004_session_search`, `005_lifecycle_hold_quota`, and `006_agent_event_source`. Migration 006 backfills `prism_agent_event_streams`, then replaces the former non-unique run sequence index with unique `(run_id, sequence)` allocation enforced in the event append transaction. `LISTEN` registration commits before initial catch-up; notifications carry only a constant wake token, so dropped/coalesced notifications affect latency rather than delivery. Migration 003 adds immutable `prism_run_feedback` rows with run FK/cascade deletion and owner/run/trace cursor indexes. Migration 004 adds session search FTS (Postgres `tsvector` FTS table dual-written on append) plus `prism_sessions(updated_at, id)` cursor index; existing entries are backfilled once. `persistence.feedback` validates exact run ownership, bounds/redacts through optional `feedbackRedactor`, queries bounded pages, and deletes only exact-owned IDs. Search hits never include credentials; ownership filters apply when present. SQLite shares sequence compatibility only; it does not provide distributed subscriptions.
 - Pass an existing `pg` `Pool` when your host already manages pooling, TLS, and credential rotation.
 
 ## Security and performance notes
@@ -141,4 +144,5 @@ PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres --workspace @arnil
 - [Persistence, credentials, and multimodality primitives](persistence-credentials-multimodality-primitives.md): package matrix and threat model.
 - [Workflows](workflows.md): adapt `persistence.checkpoints` and pass `persistence.leases` to `createWorkflowCoordinator()` and `createWorkflowSchedules()` for durable background execution and schedules.
 - [Working and semantic memory](working-and-semantic-memory.md): optional `@arnilo/prism-memory` PostgreSQL/pgvector working + semantic stores (separate from session/run persistence).
+- [Enterprise PostgreSQL state](enterprise-postgres-state.md): separate durable policy/evaluation/work/router stores and cleanup.
 - [Migration guide](migration.md): moving from JSONL/in-memory to database-backed persistence.

package/docs/process-sessions.md

@@ -0,0 +1,147 @@
+# Process sessions
+
+## What it does
+
+`createProcessSessions` is an optional host-activated registry in `@arnilo/prism-coding-agent` for **long-running** child processes: start, cursor-paged output, input, wait, signal/kill, and release (detach). Sessions have bounded lifetime (sweep on registry access — no import-time timers), ownership/identity attribution, durable metadata (command fingerprint without env/secrets), and typed `CodingProcessEvent`s via a host callback. Reuses `ExecutionPolicy`, `killProcessTree`, and `OutputAccumulator` (including spill + `readRaw` cursor paging). Optional duck-typed `sandbox` backend uses `startProcess` when present; one-shot adapters fail closed. Nothing spawns on import or construction.
+
+| Export | Purpose |
+| --- | --- |
+| `createProcessSessions(options)` | Build a `ProcessSessions` registry bound to one workspace `cwd`. |
+| `ProcessSessions` | `start`, `get`, `cancelOwned`, `markUnknown`, `reconcile`, `dispose`. |
+| `ProcessSession` | Handle: `output` / `input` / `wait` / `signal` / `kill` / `release` / `metadata`. |
+| `ProcessSessionState` | `starting` \| `running` \| `exited` \| `killed` \| `released` \| `expired` \| `unknown`. |
+| `ProcessSandboxBackend` | Duck-typed optional sandbox (`startProcess?`, `status?`); mirrors coding-security `SandboxProcessHandle`. |
+| `CodingProcessEvent` | Host-sink events (`process_started` / `_exited` / `_killed` / `_released` / `_expired` / `_unknown`). |
+| `ProcessSessionError` | Typed fail-closed errors (`ERR_PRISM_PROCESS_*`). |
+| `resolveProcessSessionLimits` / `DEFAULT_MAX_PROCESS_*` / `HARD_MAX_PROCESS_*` | Session count, input bytes, lifetime, chunk/total output caps. |
+
+## When to use it
+
+Use when a host needs attachable long-running processes (watch modes, language servers, interactive CLIs) that one-shot `shell` cannot model. Do not use as a job-control language or PTY emulator — `pty: true` fails closed with `ERR_PRISM_PROCESS_PTY_UNSUPPORTED` until a platform capability is wired. Pass a sandbox with `startProcess` for contained long-running work; omit `sandbox` for native spawn.
+
+```ts
+import { createProcessSessions } from "@arnilo/prism-coding-agent";
+
+const sessions = createProcessSessions({ cwd: workspaceRoot, policy, sandbox, onEvent });
+const p = await sessions.start({ command: "npm", args: ["test", "--", "--watch"] });
+const out = await p.output({ cursor: 0, maxBytes: 8192 });
+await p.input("q\n");
+await p.wait({ timeoutMs: 5000 });
+await sessions.dispose();
+```
+
+## Inputs / request
+
+`createProcessSessions` options:
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `cwd` | `string` | Workspace root; session `cwd` must stay inside. |
+| `policy?` | `ExecutionPolicy` | Gated before spawn and rechecked on input/signal/kill. |
+| `limits?` | `ProcessSessionLimits` | Optional overrides; invalid values fail instead of clamping. |
+| `onEvent?` | `(CodingProcessEvent) => void` | Host-owned sink (core `AgentEvent` unchanged); audit owner + terminal/unknown. |
+| `ownership?` | `OwnershipScope` | Default owner key for sessions. |
+| `identity?` | `AgentIdentity` | When ownership omitted, owner key projects from identity. |
+| `sandbox?` | `ProcessSandboxBackend` | When set: require `startProcess` or fail closed; `status` loss → all running → `unknown`. |
+
+`ProcessStartRequest`:
+
+| Field | Purpose |
+| --- | --- |
+| `command` / `args?` | Executable + argv (not a shell string). |
+| `cwd?` | Relative/absolute path contained under registry `cwd`. |
+| `env?` | Extra env merged onto `process.env` (never in fingerprint). |
+| `pty?` | Default false; unsupported → `ERR_PRISM_PROCESS_PTY_UNSUPPORTED`. |
+| `lifetimeMs?` | Bounded by `maxLifetimeMs`. |
+| `owner?` | Override owner string. |
+| `releaseOnCancel?` | If true, `cancelOwned` releases instead of killing. |
+
+## Outputs / response / events
+
+| Method | Result |
+| --- | --- |
+| `start` | `ProcessSession` in `running`; emits `process_started`. |
+| `output({ cursor, maxBytes })` | `{ data, cursor, eof }` UTF-8 page from byte cursor. |
+| `input` | Writes stdin; capped by `maxInputBytes`; fails if not running / stdin closed. |
+| `wait` | `{ exitCode, state }` — `exitCode` is `null` for killed/released/expired/unknown. |
+| `signal` / `kill` / `release` | Soft signal, hard kill, or detach (no re-attach). |
+| `cancelOwned(owner)` | Kill (default) or release owned running sessions. |
+| `markUnknown` | Backend-loss terminal state; never fabricates `exitCode`. |
+| `reconcile()` | Host resume: mark every running/starting session `unknown` (O(sessions)). |
+
+Events: `process_started`, `process_exited`, `process_killed`, `process_released`, `process_expired`, `process_unknown`.
+
+Errors: `ERR_PRISM_PROCESS_POLICY`, `ERR_PRISM_PROCESS_OWNERSHIP`, `ERR_PRISM_PROCESS_STATE`, `ERR_PRISM_PROCESS_LIMIT`, `ERR_PRISM_PROCESS_PTY_UNSUPPORTED`, `ERR_PRISM_PROCESS_UNSUPPORTED`.
+
+## Request/response example
+
+```json
+{
+  "command": "npm",
+  "args": ["test", "--", "--watch"],
+  "lifetimeMs": 14400000,
+  "releaseOnCancel": false
+}
+```
+
+## Implementation example
+
+```ts
+const sessions = createProcessSessions({
+  cwd: workspaceRoot,
+  ownership: { tenantId: "t1", userId: "u1" },
+  sandbox, // DisposableSandbox with startProcess, or omit for native
+  limits: { maxSessions: 8 },
+  onEvent: (e) => audit.write(e),
+  policy: hostExecutionPolicy,
+});
+
+const p = await sessions.start({
+  command: process.execPath,
+  args: ["server.js"],
+  lifetimeMs: 3_600_000,
+});
+
+let cursor = 0;
+for (;;) {
+  const chunk = await p.output({ cursor, maxBytes: 50_000 });
+  cursor = chunk.cursor;
+  if (chunk.eof) break;
+}
+
+await sessions.cancelOwned(p.owner); // run cancellation
+await sessions.dispose();
+```
+
+## Extension and configuration notes
+
+- Native when `sandbox` omitted; with `sandbox`, capability is `typeof startProcess === "function"` (never assumed).
+- One-shot sandbox (no `startProcess`) → `ERR_PRISM_PROCESS_UNSUPPORTED` (no native fallback).
+- Sandbox `status` not `running` (or throws) → all live sessions → `unknown`; further `start` fails closed.
+- 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.
+
+## Security and performance notes
+
+| Cap | Default | Hard |
+| --- | ---: | ---: |
+| Sessions per registry | 8 | 32 |
+| Input write bytes | 64 KiB | 1 MiB |
+| Session lifetime | 4 h | 24 h |
+| Output chunk | 50 KiB | 1 MiB |
+| Total output / session | 64 MiB | 1 GiB |
+
+- Wrong-owner `get(id, owner)` → `ERR_PRISM_PROCESS_OWNERSHIP`.
+- Released sessions reject all further handle ops.
+- `cwd` outside workspace → `ERR_PRISM_PROCESS_POLICY`.
+- Policy denial before spawn / on mutate → `ERR_PRISM_PROCESS_POLICY`.
+- Unknown outcome never invents an exit code.
+
+## Related APIs
+
+- [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`.
+- [Tool effects](tool-effects.md): unknown-outcome vocabulary mirrored by `markUnknown` / `process_unknown` / `reconcile`.

package/docs/provider-caching.md

@@ -66,7 +66,7 @@ Cache helpers return plain data:
 
 Provider events do not change. Cache accounting stays in normalized `Usage.cacheReadTokens` and `Usage.cacheWriteTokens`.
 
-For stable-prefix payloads, set `inputLayout: "cache_aware"` on the default input builder, `assembleProviderInput()`, `AgentConfig`, or `RunOptions`. The default prompt builder already places context, selected skills, and tool declarations before input messages; cache-aware input ordering then places attachments/resources, summaries, prior history, and pending tool results before the current user suffix. The prefix is byte-stable only when those stable inputs are unchanged; Prism still does not guarantee provider cache hits.
+For stable-prefix payloads, `inputLayout: "cache_aware"` is the default on the default input builder, `assembleProviderInput()`, `AgentConfig`, and `RunOptions`; set `inputLayout: "legacy"` to restore the prior order. The default prompt builder already places context, selected skills, and tool declarations before input messages; cache-aware input ordering then places attachments/resources, summaries, prior history, and pending tool results before the current user suffix. The prefix is byte-stable only when those stable inputs are unchanged; Prism still does not guarantee provider cache hits.
 
 ## Request/response example
 
@@ -146,23 +146,35 @@ Provider request policies can set `ProviderRequestOptions.cache` or the legacy `
 | Provider package | Cache kind | Explicit cache hints | Multi-turn reuse notes | Caveats |
 | --- | --- | --- | --- | --- |
 | `@arnilo/prism-provider-openai` | `openai_key` | Sends sanitized `prompt_cache_key`; `prompt_cache_retention: "24h"` only when the model declares `longRetention`. | Stable cache key + stable prefix can improve reuse. | Best-effort only; `"short"`/`"none"` omit retention. |
+| `@arnilo/prism-provider-anthropic` | `cache_control` | Marks only selected Anthropic message anchors; `"long"` maps to documented `ttl: "1h"`. | Keep selected anchors stable. | Best-effort; never stamp every block. |
+| `@arnilo/prism-provider-google` | none | Sends no Prism cache marker. | Host/model may have upstream behavior. | Gemini cache controls are not mapped in this package. |
 | `@arnilo/prism-provider-openrouter` | `cache_control` | Top-level automatic `cache_control` when enabled without breakpoints; otherwise markers only on caller-selected `cache.breakpoints`; `"long"` may add `ttl: "1h"`. Sticky `session_id` routing. | Breakpoint-stable / automatic prefixes can be reused by upstream providers. | Best-effort only; top-level automatic may exclude some backends from routing. |
 | `@arnilo/prism-provider-opencode-go` | route-specific | Sends sanitized `x-opencode-session`; Anthropic route applies selected `cache_control` breakpoints; OpenAI route sends none. | Session id + unchanged selected anchors can help route-native caches. | Best-effort and route-dependent. |
 | `@arnilo/prism-provider-zai` | `implicit` | No explicit cache payload; GLM context caching is automatic. | Resend unchanged prior history for implicit context-cache reuse. | Best-effort only; cache options do not force hits. |
 | `@arnilo/prism-provider-kimi` | implicit by default, optional `cache_control` | Default catalog models send no `cache_control`; hosts may opt in on Anthropic `/messages` models with `ModelConfig.cache.kind: "cache_control"`. | Keep selected Anthropic anchors and prior history stable. | Best-effort and model/route-dependent. |
 | `@arnilo/prism-provider-neuralwatt` | `implicit` | No `cache_control`, `cacheKey`, `prompt_cache`, or `cacheRetention` payload; NeuralWatt vLLM prefix caching is automatic. | Full prior history must be resent unchanged with only the new turn appended; `inputLayout: "cache_aware"` keeps stable prefixes first. | Best-effort only; does not promise cache hits; `cacheRetention: "none"` disables Prism hints only, not the implicit backend prefix cache. |
 | `@arnilo/prism-provider-ai-sdk` | host-owned | No Prism cache payload; host `LanguageModelV4` owns upstream caching. | Host model/provider decides cache keys, breakpoints, and sticky routing. | Adapter maps `inputTokens.cacheRead`/`cacheWrite` from `finish.usage` only; does not invent cache fields. |
+| `@arnilo/prism-provider-alibaba` | implicit by default, optional `cache_control` | DashScope implicit prefix caching is automatic; opt-in `cache_control: {"type":"ephemeral"}` markers only on caller-selected `cache.breakpoints`, capped at 4. | Keep selected anchors and prior history stable; each cached prefix needs ≥1024 tokens and lives ~5 minutes upstream. | Best-effort and model-dependent; `cached_tokens`→read, `cache_creation_input_tokens`→write. |
+| `@arnilo/prism-provider-ollama` | `implicit` | No `cache_control`, `cacheKey`, `prompt_cache`, or `cacheRetention` payload; Ollama KV/prefix caching is automatic with no request knob. | Resend unchanged prior history for implicit KV reuse. | Best-effort only; Ollama reports no cached-token count, so `Usage.cacheReadTokens` stays `undefined`. |
+| `@arnilo/prism-provider-azure` | none | No Prism cache mapping. | Endpoint/model-specific. | Host owns Azure cache policy. |
+| `@arnilo/prism-provider-bedrock` | none | No Prism cache mapping. | Endpoint/model-specific. | Host owns Bedrock cache policy. |
+| `@arnilo/prism-provider-vertex` | none | No Prism cache mapping. | Endpoint/model-specific. | Host owns Vertex cache policy. |
 
 Detailed first-party provider notes:
 
 - OpenAI Responses (`@arnilo/prism-provider-openai`): `kind: "openai_key"`. Sanitizes/clamps `prompt_cache_key` to 64 chars; `"long"` retention maps to `prompt_cache_retention: "24h"` only when the model declares `cache.longRetention`; `"short"`/`"none"` omit the field. GPT-5.6+ official docs use `prompt_cache_options` / breakpoints instead of retention — `listOpenAIModels` sets `longRetention: false` for those ids. `input_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`.
 - OpenAI-compatible Chat Completions adapter: minimal scope, sends no cache payload; see [OpenAI-compatible provider](providers/openai-compatible.md).
+- Anthropic (`@arnilo/prism-provider-anthropic`): `kind: "cache_control"`; selected Anthropic message anchors receive `cache_control` and eligible long retention maps to `ttl: "1h"`. Cache read/create usage maps to normalized cache read/write tokens.
+- Google (`@arnilo/prism-provider-google`): sends no Prism cache-control payload. Do not infer cache hits or cache token counts from absent Gemini fields.
 - OpenRouter (`@arnilo/prism-provider-openrouter`): `kind: "cache_control"`. Sanitizes/clamps `session_id`/`X-Session-Id` to 256 chars for sticky routing; with no breakpoints emits top-level automatic `cache_control: { type: "ephemeral" }`; with breakpoints applies Anthropic-style markers only to caller-selected locations (last content block of each selected message); `"long"` retention adds `ttl: "1h"` when the model allows it. `prompt_tokens_details.cached_tokens`/`cache_write_tokens` map to `Usage.cacheReadTokens`/`cacheWriteTokens`. Optional `listOpenRouterModels()` may populate `ModelConfig.cache`/`cost` from live pricing.
 - OpenCode Go (`@arnilo/prism-provider-opencode-go`): default base `https://opencode.ai/zen/go/v1`; `x-opencode-session` from `cacheKey ?? sessionId`, sanitized to 128 chars; the Anthropic route (MiniMax/Qwen) applies `cache_control` markers only to selected breakpoints (`"long"` → `ttl: "1h"`), the OpenAI route (Grok/GLM/Kimi/MiMo/DeepSeek) sends none and preserves `reasoning_content`. OpenAI route maps `prompt_tokens_details.cached_tokens`/`cache_write_tokens`; Anthropic route maps `cache_read_input_tokens`/`cache_creation_input_tokens`. Caller-gated `listOpenCodeGoModels` against official `GET /zen/go/v1/models`.
 - Z.AI (`@arnilo/prism-provider-zai`): `kind: "implicit"`. GLM context caching is automatic; sends no explicit cache payload regardless of cache options. `prompt_tokens_details.cached_tokens`/`cache_write_tokens` map to `Usage.cacheReadTokens`/`cacheWriteTokens`.
 - NeuralWatt (`@arnilo/prism-provider-neuralwatt`): `kind: "implicit"`. NeuralWatt prefix caching is automatic; sends no explicit cache payload regardless of cache options. `cacheRetention: "none"` disables Prism cache-control hints only (not the implicit backend prefix cache). `prompt_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`; NeuralWatt does not report a cache-write token, so `Usage.cacheWriteTokens` is never fabricated (stays `undefined`). NeuralWatt's `/v1/models` catalog advertises exact `cached_input_per_million` rates for cache reads and `cached_output_per_million: null`; static curated aliases do not guess those prices.
 - Kimi (`@arnilo/prism-provider-kimi`): default catalog models use implicit caching (no `cache_control`); hosts opt in via `ModelConfig.cache.kind: "cache_control"` on the Anthropic `/messages` route, then `cache_control` markers apply only to selected breakpoints (`"long"` → `ttl: "1h"`); the Moonshot OpenAI route sends none. `cache_read_input_tokens`/`cache_creation_input_tokens` map to `Usage.cacheReadTokens`/`cacheWriteTokens`.
 - AI SDK adapter (`@arnilo/prism-provider-ai-sdk`): **host-owned**. Sends no Prism cache payload; the supplied `LanguageModelV4` and its upstream provider own request caching. Maps AI SDK v4 `finish.usage.inputTokens.cacheRead`/`cacheWrite` to `Usage.cacheReadTokens`/`cacheWriteTokens`. No `list*Models()` export.
+- Alibaba Cloud (`@arnilo/prism-provider-alibaba`): implicit by default, optional `cache_control`. DashScope implicit prefix caching is automatic (no marker); explicit opt-in `cache_control: {"type":"ephemeral"}` markers apply only to selected breakpoints when `ModelConfig.cache.kind: "cache_control"` and the caller supplies breakpoints, capped at 4 (each prefix ≥1024 tokens, ~5 minute TTL). `prompt_tokens_details.cached_tokens`/`cache_creation_input_tokens` map to `Usage.cacheReadTokens`/`cacheWriteTokens`. Caller-gated `listAlibabaModels` against OpenAI-compatible `GET {base}/models`.
+- Ollama (`@arnilo/prism-provider-ollama`): `kind: "implicit"`. Ollama reuses its KV/prompt cache automatically; there is no request knob and no wire marker, so Prism never emits `cache_control`. Ollama reports no cached-token count, so `Usage.cacheReadTokens` is intentionally left `undefined` (not `0`). Caller-gated `listOllamaModels` against OpenAI-compatible `GET {base}/models`.
+- 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.
 
 ### NeuralWatt cache-aware limiter
 

package/docs/provider-conformance.md

@@ -21,7 +21,28 @@ Use these helpers in provider package tests to check event order, terminal event
 
 Do not use them as a live integration runner, provider simulator, retry framework, credential loader, or test framework replacement.
 
-For real network smoke tests, each first-party provider package ships an env-gated `src/__tests__/live.test.ts` that exercises the live API when `PRISM_LIVE_PROVIDER_TESTS=1` and a provider-specific API key are set. These live tests reuse the same conformance helpers (`assertProviderStreamConforms`, `assertAbortIsObserved`, `assertNoSecretLeak`) against the real provider, so offline and live assertions stay consistent. The default `npm test` never sets these gates and stays network-free; see [Release and install](release-and-install.md) for the full env-var list.
+Offline conformance is mandatory for every package; credentialed probes are not uniform. Packages with a checked-in `live.test.ts` use `PRISM_LIVE_PROVIDER_TESTS=1` plus their provider key. Realtime, hosted tools, AI SDK host models, Alibaba/Ollama account or daemon paths, and enterprise workload identities need host-owned protected probes instead of a generic fixture. The default `npm test` never sets these gates and stays network-free; see [Release and install](release-and-install.md#015-protected-live-canary-matrix) for the exact environment/key boundary.
+
+## Phase 10 provider conformance matrix
+
+| Package | Required offline evidence | Restricted live evidence |
+| --- | --- | --- |
+| OpenAI | Responses serialization/stream ordering, provider-hosted authority, continuation cap/cursor, Realtime fake WebSocket caps | Standard API-key smoke; separate protected hosted-tool/Realtime entitlement probe |
+| AI SDK | Exact 4.0.4/V4 gate (`4.0.3` also listed); every mapped stream part; authority, cache usage, redaction, unsupported mapping | Host-created V4 model only; no Prism credential fixture |
+| Anthropic | Messages serialization, cache/thinking/tools, header/redaction/abort assertions | Protected `ANTHROPIC_API_KEY` smoke |
+| Google | `generateContent` serialization, complete tool calls, media/abort/redaction assertions | Protected `GOOGLE_API_KEY` or `GEMINI_API_KEY` smoke |
+| Kimi | Coding/Moonshot route fixtures, thinking/tool reconstruction, headers/redaction | Protected `KIMI_API_KEY` smoke |
+| Z.AI | GLM thinking/tool-stream fixtures, implicit-cache usage, headers/redaction | Protected `ZAI_API_KEY` smoke |
+| OpenRouter | routing/reasoning/cache-control fixture, stream/tool reconstruction, headers/redaction | Protected `OPENROUTER_API_KEY` smoke |
+| OpenCode Go | OpenAI/Anthropic route fixture, completion proof, PDF/media boundary, headers/redaction | Protected `OPENCODE_API_KEY` smoke |
+| Alibaba | DashScope presets, Qwen thinking, image rejection/mapping, cache/usage fixture | Protected account/region host probe; no generic key fixture |
+| 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 |
+| 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.
 
 ## Inputs / request
 
@@ -50,6 +71,7 @@ Helpers accept normal `AIProvider`, `ProviderRequest`, `ProviderEvent`, `Usage`,
 - `assertSerializedRequestCoversContent()` scans a serialized provider request body for primitive canaries from each Prism content block and fails if any supported block type is silently dropped. Provider-valid transcripts place assistant `tool_call` messages before matching role `tool` `tool_result` messages; runtime, cache-aware input layout, and observational-memory worker loops preserve that order before serialization.
 - `assertProviderOwnedHeadersWin()` compares captured request headers against the provider's authoritative owned header values and a caller-supplied header bag; it fails if any owned header (`authorization`, `content-type`, session/security headers) was overridden by caller headers, and also fails if a non-owned caller header was dropped. This is the provider-neutral check that caller `ProviderRequest.options.headers` cannot hijack provider credentials or sessions; every first-party provider package exercises it.
 - `assertNoSecretLeak()` stringifies all collected events and fails if any known secret string is present.
+- Provider-hosted calls must surface as `tool_call` with `authority: "provider-hosted"`; loops record them but never dispatch them or append a host `tool_result`. Bounded continuations must emit an opaque cursor event and end in `done` or redacted `error`, never silent truncation.
 
 ## Request/response example
 
@@ -164,10 +186,12 @@ Canonical contract: [Thinking and reasoning](thinking-and-reasoning.md).
 `@arnilo/prism-provider-ai-sdk` is a host-owned `LanguageModelV4` bridge. It does not participate in the discovery or thinking/reasoning checklists above. Cover instead:
 
 1. **No catalog / no setup fetch** — package exports no `list*Models()`; `createAiSdkProvider` wraps a host model only.
-2. **Specification gate** — rejects non-v4 models (`specificationVersion !== "v4"` or missing `doStream`).
-3. **Cache usage mapping** — `finish.usage.inputTokens.cacheRead`/`cacheWrite` map to `Usage.cacheReadTokens`/`cacheWriteTokens`; adapter does not emit cache request fields.
-4. **Reasoning stream mapping** — `reasoning-delta` → thinking deltas; assistant `thinking` blocks replay as AI SDK `reasoning` prompt parts.
-5. **Host-owned controls** — `options.compat` / `options.extra` forward as `providerOptions.prism`; reasoning effort stays on the host model.
+2. **Version + specification gate** — exact `@ai-sdk/provider` matrix version is verified at setup; rejects version skew, non-v4 models (`specificationVersion !== "v4"`), or missing `doStream`.
+3. **Mapping table** — fixture covers every supported matrix row: response metadata id, text/reasoning/tool deltas, client/provider-hosted tool authority, structured output, cache usage, finish/error/abort; unmappable stream parts and `structuredOutput.strict` fail typed instead of dropping.
+4. **Cache usage mapping** — `finish.usage.inputTokens.cacheRead`/`cacheWrite` map to `Usage.cacheReadTokens`/`cacheWriteTokens`; adapter does not emit cache request fields.
+5. **Reasoning stream mapping** — `reasoning-delta` → thinking deltas; assistant `thinking` blocks replay as AI SDK `reasoning` prompt parts.
+6. **Redaction** — direct adapter errors use its supplied `SecretRedactor`; agent runs use their active redactor; opaque provider metadata is never emitted.
+7. **Host-owned controls** — `options.compat` / `options.extra` forward as `providerOptions.prism`; reasoning effort stays on the host model.
 
 Canonical contract: [AI SDK provider adapter](providers/ai-sdk.md).