@arnilo/prism 0.5.6 → 0.6.0

package/docs/language-intelligence.md

@@ -167,7 +167,7 @@ try {
 - Server `command`/`args` are host-config only — never taken from model tool arguments.
 - File URIs must be `file:` and resolve inside `workspaceRoot`; escapes fail with `ERR_PRISM_LSP_WORKSPACE`.
 - LSP payloads are untrusted: Content-Length framing is bounded; oversized/malformed frames fail closed; result lists and diagnostics are capped.
-- Crash loop: unexpected exit increments a per-server restart counter; after the freeze budget (`LSP_RESTARTS_PER_SERVER` = 3) further starts fail with `ERR_PRISM_LSP_SERVER`.
+- Crash loop: unexpected exit increments a per-server restart counter; after the freeze budget (`LSP_RESTARTS_PER_SERVER` = 3) further starts fail with `ERR_PRISM_LSP_SERVER`. A write that loses the server's pipe (the process died mid-write) is classified as that same `ERR_PRISM_LSP_SERVER` — a host never sees a raw `EPIPE`/`ECONNRESET`, and the loss still counts against the restart budget through the exit path.
 - Defaults / hard caps (Phase 9 freeze): message 4 MiB / 32 MiB; diagnostics/file 200 / 1000; pending requests 32 / 128; results/query 500 / 5000; timeout 30 s / 120 s; servers/workspace 4 / 8.
 
 ## Related APIs

package/docs/migrate-to-0.5.md

@@ -1,6 +1,6 @@
 # Migrate Prism 0.4 to 0.5
 
-> **Status: 0.5.4** (run-limit HARD split from host policy, plan 067). 0.5.0 covers plans 055–065. 0.5.1 adds kernel provider-request construction. 0.5.2 coalesces stream tokens. 0.5.3 folds content-only tool results.
+> **Status: 0.5.4 line** (run-limit HARD split from host policy). 0.5.0 covers plans 055–065. 0.5.1 adds kernel provider-request construction. 0.5.2 coalesces stream tokens. 0.5.3 folds content-only tool results. 0.5.4 splits run-limit HARD from host policy; 0.5.5 and 0.5.6 shipped as patches (per-frame byte limits, then trusted extension activation, wiki ingest, and graft commands). The planned 0.5.7 remediation was never published — it ships in 0.6.0, whose guide is [migrate-to-0.6.md](migrate-to-0.6.md).
 
 ## What changes
 
@@ -136,6 +136,10 @@ What to do:
 - **Durable state:** runs with `maxWallTimeMs: null` persist checkpoints without `deadlineAt`; older checkpoints with a deadline still resume under it.
 - **Documented ceiling:** vendors that omit usage charge zero to token counters; a configured `maxCost` stays the fail-closed envelope (missing/mixed-currency cost breaches immediately).
 
+## 10. Later lines
+
+The 0.5.x line ends here: the never-published 0.5.7 remediation and the 0.6.0 Node `>=22` floor are documented in [migrate-to-0.6.md](migrate-to-0.6.md), which also carries the folded 0.5.7 deltas (durable concurrent tool rounds, content-less tool results, host-tunable knobs, third-party peer floors, and the removed `@arnilo/prism-office` `playwright-core` peer).
+
 ## Upgrade steps
 
 1. Bump every `@arnilo/*` dependency/peer to `^0.5.1` (0.5.0 hosts: `^0.5.0` still works until you want construction).
@@ -146,9 +150,10 @@ What to do:
 6. If you set thinking levels: prefer `AgentConfig.thinkingLevel` / `RunOptions.thinkingLevel` (section 8); `applyThinkingLevelForModel` remains for custom generate sites (section 7).
 7. Run your suite. No persisted-data migration exists or is needed.
 8. After 0.5.1: drop host-only `createSessionCachePolicy` if it existed only for OpenCode Go / session headers (section 8).
+9. Beyond 0.5: the never-published 0.5.7 content and the Node 22 floor ship in 0.6.0 — use [migrate-to-0.6.md](migrate-to-0.6.md).
 
 ## Rollback
 
-Pin the previous version: `@arnilo/prism@0.4.x` (exact pins per package). Nothing persisted
+Pin the previous version: `@arnilo/prism@0.4.x` (exact pins per package; the last published 0.5.x is 0.5.6). Nothing persisted
 changes under 0.5, so a pin rollback is safe. The MCP module move (section 5) is the only
 migration that touches host import code — keep a 0.4 pin if you need the monolithic SDK.

package/docs/migrate-to-0.6.md

@@ -0,0 +1,89 @@
+# Migrate Prism 0.5 to 0.6
+
+> **Status: 0.6.0** (Node `>=22`, the folded 0.5.7 content, self-describing coverage failures, release-truth gates). 0.6.0 is the first published release after 0.5.6 — the 0.5.7 cut was never published, so everything below is the single 0.5.6 → 0.6.0 delta.
+
+## What changes
+
+Prism 0.6 is a **lockstep cut**: all 10 publishable manifests move `0.5.6` → `0.6.0` and internal first-party ranges move `^0.5.6` → `^0.6.0`. Package names and import subpaths from 0.5 stay valid, no persisted shape changed, and no public signature was removed. The host-visible delta is:
+
+1. the runtime floor: **Node `>=22`** (§1, breaking for a Node 20 host);
+2. third-party version floors and one **removed peer** (§2, §3) — the install-visible part of the never-published 0.5.7;
+3. additive tuning knobs for context assembly, session snapshots, memory-session search, SSRF policy, and browser run lifetime (§4);
+4. behavior fixes that need no host action (§5) and release/CI gates that change no runtime contract (§6).
+
+## 1. Runtime floor: Node `>=22` (breaking for Node 20 hosts)
+
+Every publishable package declares `"engines": { "node": ">=22" }`, and a Node 20 host gets an `EBADENGINE` warning from npm (a hard failure under `engine-strict`) plus an unsupported runtime. Node 20 reached upstream end-of-life on 2026-04-30, so the 0.6 line moves to Node 22 (maintenance LTS to 2027-04-30) while Node 24 stays the CI default (active LTS to 2028-04-30).
+
+What a 0.5.x host must check before upgrading:
+
+- **Host and container images.** Move the host process to Node 22.6+ — the docs/test harness strips TypeScript natively from 22.6 — or to Node 24. `docs/release-and-install.md` carries the support matrix.
+- **CI legs.** The release workflow's compatibility leg is renamed `node20-compat` → `node22-compat` and runs `node-version: "22"`; branch-protection required-check lists that name the old job id must be updated.
+- **Development types.** `@types/node` (dev) moves `^20.19.0` → `^22.20.0` in the root and `@arnilo/prism-coding-tools`, tracking the declared floor. Hosts building Prism from source should not pin their own `@types/node` below 22 while the floor is `>=22`.
+- **No code migration.** No import path, store schema, event shape, or public signature changed for this; the floor is the whole delta (`scripts/phase12-freeze-manifest.json` deviation `dev-006`).
+
+## 2. Third-party floors (folded 0.5.7 content)
+
+Ranges moved in the cut that never shipped; hosts that pin these themselves must move with them.
+
+- `pg` **`^8.22.0` → `^8.23.0`** — driver dependency of `@arnilo/prism-core/sessions/postgres` and `@arnilo/prism-memory`, and core's optional peer. A host on 8.22 sees a peer warning until it upgrades.
+- `playwright-core` optional exact peer **`1.61.0` → `1.63.0`** in `@arnilo/prism-web-tools` (`/browser`, `/obscura`). The exact pin is deliberate — browser control is version-sensitive, and the host still owns the browser binary/image.
+- `@ai-sdk/provider` exact peer **`4.0.10` → `4.0.13`** in `@arnilo/prism-providers/ai-sdk`. The supported-version matrix gained a `4.0.13` row; `4.0.3`, `4.0.4`, and `4.0.10` stay listed. Unlisted versions still fail closed with `AiSdkProviderError { code: "unsupported_version" }`.
+- `@nanonets/graft` optional peer **`^0.16.0` → `^0.16.0 || ^0.18.0`** in `@arnilo/prism-memory/graft` (upstream published no 0.17; both listed floors pass the offline peer-contract smoke).
+- `@agentclientprotocol/sdk` exact pin **`1.3.0` → `1.4.0`** in `@arnilo/prism-ag-ui/acp` and `@arnilo/prism-acp-agent`. The wire protocol stays v1 (`PROTOCOL_VERSION === 1`); 1.4.0 stabilizes elicitation (the SDK's `unstable_*` helpers become `createElicitation`/`completeElicitation`, wire method names unchanged — Prism never called the unstable helpers) and adds `compaction` session-update kinds, which Prism does not advertise or map.
+- `@office-open/*` **`0.13.1` → `0.14.5`** in `@arnilo/prism-office`. Upstream made `parseDocument`/`parsePresentation`/`parseWorkbook` async; Prism's adapters call the new synchronous `parse*Sync` variants, so no Prism signature changed — but the office package requires the 0.14.5 line.
+- `zod` **`^4.4.3` → `^4.6.2`** in `@arnilo/prism-mcp` (AG-UI's `^3.25.0 || ^4.0.0` peer range is unchanged and still admits it).
+- `@biomejs/biome` dev **`2.5.11` → `2.5.13`** (lint/format only; 0 findings on the repo).
+
+## 3. `@arnilo/prism-office` is peer-free
+
+The optional `playwright-core` peer is **removed**. No office subpath ever imported it at runtime — `/diagrams` drives a host-supplied iframe — so the only Browser consumer was a gated live draw.io test, now behind a devDependency. Hosts that added the install for office can drop it; office installs and imports without a browser.
+
+## 4. Additive host knobs
+
+All optional, all defaulting to the previous behavior:
+
+- **Context assembly:** `AssembleProviderInputOptions.tokenEstimator?: (text: string) => number` replaces the built-in UTF-16/4 heuristic for eviction accounting. Hard byte caps stay estimator-independent.
+- **Session snapshot cache:** `AgentSessionConfig.snapshotCacheTtlMs` — default `DEFAULT_SNAPSHOT_CACHE_TTL_MS` (1000), cap `HARD_MAX_SNAPSHOT_CACHE_TTL_MS` (30000), `0` disables the branch-rebuild cache.
+- **Memory-session search:** `createMemorySessionStore(entries, { search: { maxLinearSessions, maxLinearEntries, maxLinearBytes } })`, validated against the same fail-closed bounds as the defaults.
+- **SSRF policy:** `SsrfPolicy.allowedCidrs` takes IPv4/IPv6 CIDR entries for hosts that must reach a private range. Hostname denials (metadata endpoints), credential and redirect checks are unchanged, and an unparseable CIDR still fails closed.
+- **Browser run lifetime:** `BrowserLimitOptions.idleRunTtlMs` (default `0` = never reap, cap `HARD_IDLE_RUN_TTL_MS` 30 min) closes a run with nothing queued after the TTL; any interaction resets the clock, and `manager.closeRun(runId)` stays the explicit close.
+
+## 5. Behavior fixes (no host action)
+
+- **Durable concurrent tool rounds.** With `toolConcurrency > 1`, a failed or aborted call used to throw before the round's results were appended, dropping the successful siblings — the next provider request then carried `tool_use` blocks with no `tool_result`. Successful results and synthetic errors (`tool_execution_failed` for the failing call, `tool_call_not_dispatched` for calls that never started) are now persisted before the round fails or aborts. Run-level control errors (`ERR_PRISM_AGENT_RUN_SUSPENDED`, `ERR_PRISM_DELEGATION_SUSPENDED`, `ERR_PRISM_LOOP_*`) intentionally skip synthetic results: durable recovery re-dispatches them.
+- **Content-less tool results.** A `ToolResult` without `content`/`result` folds to `(tool completed with no output)` (`EMPTY_TOOL_RESULT_TEXT`) instead of an empty payload, so strict OpenAI-compatible providers accept the request.
+- **Memory patch merge.** `packages/memory`'s `mergeJsonObjects` now delegates to core `mergeConfigLayers` (deep copy, strict JSON validation — `undefined`/`Date`/function values fail closed — with the `MemoryValidationError` taxonomy preserved) instead of aliasing the caller's objects.
+- **`redactSecrets` cost.** A guarded single-pass alternation fast path handles large inputs (≥16 KiB, 2–32 non-overlapping needles) with byte-identical output (~13× faster on 1 MiB transcripts); the ordered loop stays the fallback.
+- **Peer manifest resolution.** Upstream resolvers handle packages that do not export `./package.json` (e.g. `@dietrichgebert/ponytail`) by resolving the entry point and walking up to the manifest.
+
+## 6. Test, coverage, and release-gate changes (no runtime contract)
+
+- **`npm test` never short-circuits.** Every stage runs through `scripts/run-all-tests.mjs`, which prints one summary, so a failing stage cannot hide later failures.
+- **Coverage truth.** Discovery finds nested `dist/**/__tests__` in all 9 workspace packages, `coverage-thresholds.json` may no longer name retired packages, and a failing coverage child is self-describing: the summary prints the child's redacted output tail and the artifact row records `status`/`exitCode`/`tail`.
+- **Version-literal gate.** `scripts/version-literal-gate.test.mjs` asserts every release-claim surface (10 manifests, internal ranges, `package-lock.json`, the `src/index.ts` version constant, the `docs/index.md` current line, `release.yml` tag lists, `scripts/package-truth.json`) equals the root manifest version, so a half-finished cut fails the suite instead of shipping.
+- **Workflow liveness.** `scripts/workflow-liveness.test.mjs` resolves every `-w`/`--workspace` target, named npm script, and `uses:` reference in `.github/workflows/*.yml` against the workspace inventory and requires full 40-hex SHA pins for actions.
+- **Startup budget under load.** The root import budget asserts a machine-relative ratio (trimmed mean of imports ÷ process-start cost) and only applies the absolute 250 ms ceiling when the machine is off-load, so a busy CI runner no longer reports a false regression.
+- **Internal ranges at the cut version exactly.** `release.mjs` lockstep mode requires every `@arnilo/*` range to be the cut version (exact `0.6.0` or caret `^0.6.0`); a range that merely *satisfies* it fails closed, because it lets two installs of one release line resolve different first-party minors.
+- **Protected legs fail closed with one convention.** `scripts/blocked-gate.mjs` gives every environment-blocked gate the same shape and message, and `scripts/release-skip-manifest.mjs` records env var **names** only (never values) in the release evidence.
+
+## Upgrade steps
+
+1. Move the host process, containers, and CI legs to Node 22+ (§1) and bump `@types/node` to 22 if you build from source.
+2. Bump every `@arnilo/*` dependency and peer to `^0.6.0` (0.5.x hosts: `^0.5.6` still resolves until you want the new knobs).
+3. Move the third-party ranges your host pins itself (§2).
+4. Remove `playwright-core` from an office install if you added it for `/diagrams` (§3).
+5. Adopt the optional knobs where they matter (§4).
+6. Build and run your suite. No persisted-data migration exists or is needed.
+
+## Rollback
+
+Pin the previous published line: `@arnilo/prism@0.5.6` (exact pins per package). Nothing persisted under 0.5 or 0.6 changes, so a pin rollback is safe; the Node floor, peer ranges, and host knobs listed here are the only deltas a 0.6 host would lose.
+
+## Related APIs
+
+- [Migration guide](migration.md): the era index of migration cuts with replacement tables and rollback notes.
+- [Migrate Prism 0.4 to 0.5](migrate-to-0.5.md): the previous line's guide (plans 055–067).
+- [Release and install](release-and-install.md): packed surfaces, install rules, support matrix, and the offline test budget.
+- [Peer dependencies](peer-dependencies.md): every third-party peer declaration with range, optionality, subpath, and install line.
+- [CHANGELOG](../CHANGELOG.md): the per-release record, including the folded 0.5.7 content.

package/docs/migration.md

@@ -1,5 +1,35 @@
 # Migration guide
 
+## 0.5.6 → 0.6.0 (Node 22 floor; folds the never-published 0.5.7)
+
+**Prism 0.6.0 requires Node `>=22`.** Every publishable package declares `"engines": { "node": ">=22" }`; a Node 20 host gets an `EBADENGINE` warning from npm (a hard failure under `engine-strict`) and an unsupported runtime. Node 20 reached upstream end-of-life on 2026-04-30, so the 0.6.0 line moves to Node 22 (maintenance LTS to 2027-04-30) while Node 24 stays the CI default (active LTS to 2028-04-30). The full 0.5.6 → 0.6.0 guide — third-party floors, the removed office peer, the additive host knobs, and upgrade/rollback steps — lives in [migrate-to-0.6.md](migrate-to-0.6.md).
+
+What a 0.5.x host must check before upgrading:
+
+- **Runtime.** Move the host process and any container image to Node 22.6+ (the docs/test harness strips TypeScript natively from 22.6; Node 22 LTS or later is the supported answer). `engines.node` is now `>=22`, so `npm install` fails closed on older runtimes with `engine-strict` enabled.
+- **CI legs.** The release workflow's compatibility leg is renamed `node20-compat` → `node22-compat` and runs on `node-version: "22"`; branch-protection required-check lists that name the old job id must be updated.
+- **Development types.** `@types/node` (dev) moves `^20.19.0` → `^22.20.0` in the root and `@arnilo/prism-coding-tools`, tracking the declared floor. Hosts building Prism from source should not pin their own `@types/node` below 22 while the floor is `>=22`.
+- **No migration step for Prism itself.** No import path, store schema, event shape, or public signature changed for the floor; it is one of the two host-visible deltas in this cut (`scripts/phase12-freeze-manifest.json` deviation `dev-006`), the other being the third-party peer floors and the removed `@arnilo/prism-office` `playwright-core` peer listed in [migrate-to-0.6.md](migrate-to-0.6.md#3-arniloprim-office-is-peer-free).
+
+### Folded 0.5.7 content (no import, store, or event-shape break)
+
+The 0.5.7 cut was never published, so its content ships in 0.6.0. Third-party ranges moved; hosts that pin these themselves must move with them:
+
+- `pg` **`^8.22.0` → `^8.23.0`** — driver dependency of `@arnilo/prism-core/sessions/postgres` and `@arnilo/prism-memory`, and its optional peer in core. Hosts on 8.22 see a peer warning until they upgrade.
+- `playwright-core` optional exact peer **`1.61.0` → `1.63.0`** in `@arnilo/prism-web-tools` (the exact pin is deliberate — browser control is version-sensitive, and the host still owns the browser binary/image). `@arnilo/prism-office` **drops** its optional `playwright-core` peer: no office subpath ever imported it at runtime (the diagrams embed takes a host-supplied iframe), so it becomes a devDependency behind the gated live draw.io test. Hosts that installed it for office can remove it.
+- `@ai-sdk/provider` exact peer **`4.0.10` → `4.0.13`** in `@arnilo/prism-providers/ai-sdk`. The supported-version matrix gained a `4.0.13` row; `4.0.3`, `4.0.4`, and `4.0.10` stay listed. Unlisted versions still fail closed with `AiSdkProviderError { code: "unsupported_version" }`.
+- `@nanonets/graft` optional peer **`^0.16.0` → `^0.16.0 || ^0.18.0`** in `@arnilo/prism-memory/graft` (upstream published no 0.17; both listed floors pass the offline peer-contract smoke).
+- `@agentclientprotocol/sdk` exact pin **`1.3.0` → `1.4.0`** in `@arnilo/prism-ag-ui/acp` and `@arnilo/prism-acp-agent`. Wire protocol stays v1 (`PROTOCOL_VERSION === 1`); 1.4.0 stabilizes elicitation (the SDK's `unstable_createElicitation`/`unstable_completeElicitation` helpers become `createElicitation`/`completeElicitation`, wire method names unchanged — Prism never called the unstable helpers) and adds `compaction` session-update kinds, which Prism does not advertise or map.
+- `@office-open/*` **`0.13.1` → `0.14.5`** in `@arnilo/prism-office`. Upstream made `parseDocument`/`parsePresentation`/`parseWorkbook` async; Prism's synchronous document adapters now call the new `parse*Sync` variants, so no Prism signature changed — but the office package requires the 0.14.5 line.
+- `zod` **`^4.4.3` → `^4.6.2`** in `@arnilo/prism-mcp` (AG-UI's `^3.25.0 || ^4.0.0` peer range is unchanged and still admits it).
+- `@biomejs/biome` dev **`2.5.11` → `2.5.13`** (lint/format only; 0 findings on the repo).
+
+Dev-tooling and release-gate changes in the same cut (no host action required):
+
+- **`@types/node` dev `^26.1.1` → `^20.19.0` at the 0.5.7 cut, then `^22.20.0` here.** Development types track the declared runtime floor, so a Node-22+-only API fails the build instead of compiling clean against a newer type surface. `docs/release-and-install.md` records the policy: the types package tracks the floor, and raising the floor is a support-matrix change (freeze manifest + CI legs), not a dependency bump. The `^20.19.0` pin immediately caught four runnable examples using `import.meta.main` (Node ≥22.18/≥24.2) on a Node-20 floor — they now use the house `import.meta.url === \`file://${process.argv[1]}\`` guard, so they no longer silently no-op below Node 22.18.
+- **Node 20 floor removed in 0.6.0.** The never-published 0.5.7 deliberately kept `engines.node >=20` because dropping a supported line is a host-breaking support-matrix change that does not belong in a patch release; the 0.6.0 minor is the right vehicle (Node 22 is maintenance LTS to 2027-04-30, Node 24 active LTS to 2028-04-30).
+- **Internal first-party ranges are gated at the cut version exactly.** `release.mjs validateRelease` (lockstep mode, which `release.mjs gate --lockstep --version` and the publish path both use) requires every `@arnilo/*` range to be the cut version (exact `0.6.0` or caret `^0.6.0`). A range that merely *satisfies* it — `^0.5.5` alongside `^0.5.6`, which is what the pre-cut tree carried — now fails the gate closed, because it lets two installs of the same release line resolve different first-party minors.
+
 ## 0.5.3 → 0.5.4 (export-shape break in `@arnilo/prism`)
 
 

package/docs/model-registry.md

@@ -37,7 +37,7 @@ import { createModelRegistry, type ModelConfig } from "@arnilo/prism";
 | `provider` / `model` | Required registry key. |
 | `displayName` | Human-readable label. |
 | `capabilities` | Input/output modes (`text`, `image`, `audio`, `file`, `document`) plus reasoning/tools/streaming booleans and optional `structuredOutput` (`true` or `"json_schema"`) for native JSON-schema requests. |
-| `limits` | Context and output-token limits. |
+| `limits` | Context and output-token limits (`ModelLimits`). |
 | `cost` | Input/output/cache read/cache write pricing. |
 | `cache` | Generic `ModelCacheCapabilities`. |
 | `compat` | Provider-owned inert JSON escape hatch. |

package/docs/multimodal-content.md

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

package/docs/obscura.md

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

package/docs/options-index.md

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

package/docs/peer-dependencies.md

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