@arnilo/prism 0.5.5 → 0.6.0

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).

package/docs/performance.md

@@ -85,6 +85,16 @@ Recorded 2026-08-31 on Node v24.19.0 / Linux x64: 5 warmups + 20 measured runs,
 node scripts/benchmark.mjs --scenario workflow-loop --out /tmp/prism-workflow-loop.json
 ```
 
+## Secret redaction (plan 070)
+
+`node scripts/benchmark.mjs --scenario redaction` is network-free (in-memory, no credentials). It builds one transcript-scale string (≥ 1 MiB) and one small entry-shaped object, both carrying 16 realistic secret-shaped needles, and measures `redactSecrets` against a local copy of the ordered `needles.reduce(split/join)` loop it replaced for large strings: the two must stay byte-identical and no needle may survive either path. Caps live in `scripts/budgets.json#redaction` (same-process speedup floor 5, transcript p95 ceiling 250 ms, small-entry p95 ceiling 25 ms — sanity bounds, machine-dependent). Schema/caps/network-free gating in `npm test`: `scripts/benchmark-redaction.test.mjs`.
+
+```bash
+node scripts/benchmark.mjs --scenario redaction --out /tmp/prism-redaction.json
+```
+
+Recorded 2026-09-11, Node v24.19.0 / Linux x64: 1 MiB transcript × 16 needles **9.39 ms → 0.69 ms p50 (13.7×, floor 5×)**, small entry 0.15 ms p50 / 0.22 ms p95. Strings below 16 KB keep the ordered loop (`src/redaction.ts`): the equivalence check that guards the single scan costs more than the passes it saves below ~4 KB.
+
 ## Current-line root artifact diet
 
 `npm pack --dry-run --json` on `@arnilo/prism` is gated by `scripts/budget-gate.test.mjs` against `scripts/budgets.json#root` (±5%). Repository-only history stays out of the tarball: `docs/_evidence/**`, `docs/release-*-evidence.md`, `docs/api-page-template.md`, `dist/__tests__`, and `*.map`. Every page linked from shipped `docs/index.md` must be in the pack. Recorded 2026-08-27: **923,045 packed / 3,149,665 unpacked / 375 files** (226 `dist` js+d.ts, 124 index-linked docs, 25 other). 0.1.0 freeze 713,454 / 293 stays historical.
@@ -102,10 +112,32 @@ demand gate.
 **Pass/fail thresholds.** Network-free rows fail above the frozen ceiling in
 the table below; protected PostgreSQL rows fail above their per-phase
 budgets.json ceilings (50/100 ms per the approved budget contract); startup
-import fails above `startupImportMsCeiling` (250 ms); root packed bytes and
+import fails above `startupImportMsCeiling` (250 ms) on a quiet machine — see the
+startup-gate note below for how the in-chain check stays load-tolerant; root
+packed bytes and
 file count fail above baseline × 1.05. Labels: **network-free** = runs in
 `npm test` evidence, no network; **protected** = requires live PostgreSQL.
 
+**Startup gate (plan 071 Task 3).** The in-`npm test` check in
+`scripts/budget-gate.test.mjs` asserts a *machine-relative ratio* rather than a raw
+millisecond bound: cold-process `import('./dist/index.js')` wall time (trimmed mean
+of five spawns, min/max dropped) over the median empty `node -e ''` process start
+measured in the same run. External CPU load inflates both numbers, so the ratio held
+at 3.3 idle, 3.5–4.1 with a full `npm test` running concurrently, and up to 7.2 with
+40 competing processes, while the absolute import alone moved 60 ms → 258 ms — the
+same contention that failed the old fixed 250 ms check (273 ms at plan 070 Task 11,
+1104.8 ms at Task 13, both at load average ~25). Off load
+(loadavg-per-CPU < 1.5) the tight ratio ceiling (`importRatioCeiling` 8) and the
+absolute ceiling (250 ms) are both asserted; under load the ratio ceiling widens to
+`importRatioCeilingUnderLoad` (20) and the absolute bound becomes
+evidence-of-record, still measured by `scripts/benchmark-0.1.0.mjs` (39.79 ms in
+`scripts/benchmark-0.1.0.json`) and re-gated by `scripts/benchmark-0.1.0.test.mjs`;
+the current-line scenario runner `scripts/benchmark.mjs` carries the six scenario
+medians and no startup row. Both ceilings live in
+`scripts/budgets.json#startup` with the calibration recorded in their `$comment`;
+freeze deviation `dev-007` records the enforcement change (the frozen 250 ms number
+itself is unchanged).
+
 | Envelope | Recorded p95 ms | Ceiling ms | Source leg | Label |
 | --- | ---: | ---: | --- | --- |
 | oidcVerifyCacheHitMs | 0.151 | 5 | enterprise adapters (0.0.28) | network-free |
@@ -543,7 +575,7 @@ The ledger percentage overhead is intentionally not a threshold: its no-ledger b
 
 ### 0.0.5 Phase 0 baseline (2026-07-15)
 
-Scope froze at commit `f5128a816ae204c52f3e2f089de71c99bd5de6d4`. Measurement host: Node v24.18.0, npm 11.16.0, Linux 7.1.3 x86_64, AMD Ryzen 9 PRO 7940HS (16 logical CPUs). Supported package runtime remains Node >=20. These are dated local comparison points, not portable CI wall-clock assertions.
+Scope froze at commit `f5128a816ae204c52f3e2f089de71c99bd5de6d4`. Measurement host: Node v24.18.0, npm 11.16.0, Linux 7.1.3 x86_64, AMD Ryzen 9 PRO 7940HS (16 logical CPUs). Supported package runtime is Node >=22 (>=20 at the time of this baseline; raised in 0.6.0) and the host measured above is Node 24. These are dated local comparison points, not portable CI wall-clock assertions.
 
 | Surface | Workload | Result |
 | --- | --- | --- |

package/docs/ponytail.md

@@ -1,5 +1,7 @@
 # Ponytail behavior integration
 
+> **Optional peer install:** `@dietrichgebert/ponytail` — see [Optional peer dependencies](peer-dependencies.md).
+
 ## What it does
 
 `@arnilo/prism-coding-tools/ponytail` is an optional package that wires [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) into Prism contribution contracts.

package/docs/postgres-persistence.md

@@ -1,5 +1,7 @@
 # PostgreSQL persistence
 
+> **Optional peer install:** `pg` — see [Optional peer dependencies](peer-dependencies.md).
+
 ## What it does
 
 The optional `@arnilo/prism-core/sessions/postgres` package ships a production-oriented PostgreSQL adapter that implements:
@@ -14,7 +16,7 @@ Factory:
 - `PostgresPersistenceOptions`
 - `PostgresPersistence.close()` (async; ends adapter-owned pools only)
 
-The adapter uses `pg@^8.22.0`, applies versioned migrations from the shared Plan 056 schema model inside a transaction guarded by `pg_advisory_xact_lock`, validates/quotes schema identifiers, and passes the full session-store and run-ledger conformance suites when `PRISM_TEST_POSTGRES_URL` is set.
+The adapter uses `pg@^8.23.0`, applies versioned migrations from the shared Plan 056 schema model inside a transaction guarded by `pg_advisory_xact_lock`, validates/quotes schema identifiers, and passes the full session-store and run-ledger conformance suites when `PRISM_TEST_POSTGRES_URL` is set.
 
 ## When to use it
 

package/docs/provider-conformance.md

@@ -31,7 +31,7 @@ Offline conformance is mandatory for every package; credentialed probes are not
 | 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.10/V4 gate (`4.0.3` and `4.0.4` also listed); every mapped stream part; authority, cache usage, redaction, unsupported mapping | Host-created V4 model only; no Prism credential fixture |
+| AI SDK | Exact 4.0.13/V4 gate (`4.0.3`, `4.0.4`, `4.0.10` 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 |

package/docs/provider-packages.md

@@ -25,26 +25,26 @@ Do not use provider packages as a package manager, credential store, env loader,
 
 | adapter package | version |
 | --- | --- |
-| `@arnilo/prism-providers/ai-sdk` | 0.5.5 |
-| `@arnilo/prism-providers/alibaba` | 0.5.5 |
-| `@arnilo/prism-providers/anthropic` | 0.5.5 |
-| `@arnilo/prism-providers/azure` | 0.5.5 |
-| `@arnilo/prism-providers/bedrock` | 0.5.5 |
-| `@arnilo/prism-providers/clinepass` | 0.5.5 |
-| `@arnilo/prism-providers/commandcode` | 0.5.5 |
-| `@arnilo/prism-providers/deepseek` | 0.5.5 |
-| `@arnilo/prism-providers/google` | 0.5.5 |
-| `@arnilo/prism-providers/hyper` | 0.5.5 |
-| `@arnilo/prism-providers/kimi` | 0.5.5 |
-| `@arnilo/prism-providers/model-discovery` | 0.5.5 |
-| `@arnilo/prism-providers/neuralwatt` | 0.5.5 |
-| `@arnilo/prism-providers/ollama` | 0.5.5 |
-| `@arnilo/prism-providers/openai` | 0.5.5 |
-| `@arnilo/prism-providers/opencode-go` | 0.5.5 |
-| `@arnilo/prism-providers/openrouter` | 0.5.5 |
-| `@arnilo/prism-providers/vertex` | 0.5.5 |
-| `@arnilo/prism-providers/xai` | 0.5.5 |
-| `@arnilo/prism-providers/zai` | 0.5.5 |
+| `@arnilo/prism-providers/ai-sdk` | 0.6.0 |
+| `@arnilo/prism-providers/alibaba` | 0.6.0 |
+| `@arnilo/prism-providers/anthropic` | 0.6.0 |
+| `@arnilo/prism-providers/azure` | 0.6.0 |
+| `@arnilo/prism-providers/bedrock` | 0.6.0 |
+| `@arnilo/prism-providers/clinepass` | 0.6.0 |
+| `@arnilo/prism-providers/commandcode` | 0.6.0 |
+| `@arnilo/prism-providers/deepseek` | 0.6.0 |
+| `@arnilo/prism-providers/google` | 0.6.0 |
+| `@arnilo/prism-providers/hyper` | 0.6.0 |
+| `@arnilo/prism-providers/kimi` | 0.6.0 |
+| `@arnilo/prism-providers/model-discovery` | 0.6.0 |
+| `@arnilo/prism-providers/neuralwatt` | 0.6.0 |
+| `@arnilo/prism-providers/ollama` | 0.6.0 |
+| `@arnilo/prism-providers/openai` | 0.6.0 |
+| `@arnilo/prism-providers/opencode-go` | 0.6.0 |
+| `@arnilo/prism-providers/openrouter` | 0.6.0 |
+| `@arnilo/prism-providers/vertex` | 0.6.0 |
+| `@arnilo/prism-providers/xai` | 0.6.0 |
+| `@arnilo/prism-providers/zai` | 0.6.0 |
 <!-- generated:package-truth:providers end -->
 
 
@@ -123,7 +123,7 @@ Every package remains explicit, setup-zero-fetch, and late-credential-bound. `Mo
 | Package | Protocol / model source | Content mapping | Stream, tools, and reasoning | Cache / canary |
 | --- | --- | --- | --- | --- |
 | OpenAI | Responses; featured or caller-gated `listOpenAIModels` | text, image, audio, file, document | Host and provider-hosted tools; 8-hop continuation; Realtime seam; Responses reasoning | `openai_key`; checked-in standard smoke + protected hosted/Realtime probe |
-| AI SDK | Host `LanguageModelV4`; no Prism catalog | declared text/image/audio/file/document prompt parts (role-limited) | v4 mapping; provider-executed tool authority; host-owned reasoning | host-owned; exact 4.0.10 matrix (`4.0.3` and `4.0.4` also listed); protected host integration |
+| AI SDK | Host `LanguageModelV4`; no Prism catalog | declared text/image/audio/file/document prompt parts (role-limited) | v4 mapping; provider-executed tool authority; host-owned reasoning | host-owned; exact 4.0.13 matrix (`4.0.3`, `4.0.4`, `4.0.10` also listed); protected host integration |
 | Anthropic | Messages; caller-gated list | text, image, PDF document/file | tool deltas, thinking | `cache_control`; protected API-key smoke |
 | Google | Gemini `generateContent`; caller-gated list | text, image, audio, document/file | complete tool calls, thinking | no Prism cache marker; protected API-key smoke |
 | Kimi | Coding Messages or opt-in Moonshot; caller-gated list | text, image, PDF document/file by route/model | tool deltas, route-native thinking replay | implicit / optional Anthropic markers; protected API-key smoke |

package/docs/provider-primitives.md

@@ -35,9 +35,10 @@ Static scan of root `src/providers/` and `packages/prism-providers/src/*/` befor
 | Runtime retry | `@arnilo/prism` `AgentConfig.retry` / `RunOptions.retry` | Classifies `ErrorInfo.code`; provider packages set numeric HTTP `code` on errors |
 | `ProviderRequestOptions.maxRetries` / `timeoutMs` | Contracts | **Removed in 0.1.5**; use `RunOptions.signal` / `AgentConfig.retry` / `RunOptions.retry` |
 | NeuralWatt `classifyNeuralWattError` | `packages/prism-providers/src/neuralwatt` | Parses `Retry-After`, `error.retry_after`, `retry_strategy`; no extra network calls |
+| Shared retry HTTP plane | `packages/prism-providers/src/shared/retry-http.ts` | **Migrated (plan 070 Task 11)** — `readRetryAfterMs` (header, plus a caller-supplied body field), `parseErrorBody`, the secret-redacting `providerHttpError` builder, and `RETRYABLE_STATUSES`; hyper, NeuralWatt, and Command Code classifiers keep their own status/field decisions |
 | Quota endpoint throttling | `packages/prism-providers/src/neuralwatt/quota.ts` | Documents 1 rps limit; caller-owned cache |
 
-No generic core helper extracts `Retry-After` / `x-request-id` for all providers yet.
+The `Retry-After` HTTP plane is shared inside `@arnilo/prism-providers` (`src/shared/retry-http.ts`, plan 070 Task 11), so the three classifiers cannot drift on header reading or on the redaction of provider error text. `x-request-id` extraction and a *core*-level helper for every provider do not exist yet.
 
 ### Structured output
 

package/docs/providers/ai-sdk.md

@@ -1,5 +1,7 @@
 # AI SDK provider adapter
 
+> **Optional peer install:** `@ai-sdk/provider@4.0.13` (exact pin) — see [Optional peer dependencies](../peer-dependencies.md).
+
 ## What it does
 
 `@arnilo/prism-providers/ai-sdk` adapts a host-supplied AI SDK `LanguageModelV4` into a Prism `AIProvider`. It maps Prism messages, tools, and structured-output options into `doStream` call options, then translates stream parts into Prism provider events incrementally.
@@ -12,7 +14,8 @@ Core `@arnilo/prism` does not depend on the AI SDK.
 | --- | --- | --- |
 | `4.0.3` | `LanguageModelV4`, `specificationVersion: "v4"` | Supported and offline-tested |
 | `4.0.4` | `LanguageModelV4`, `specificationVersion: "v4"` | Supported and offline-tested |
-| `4.0.10` | `LanguageModelV4`, `specificationVersion: "v4"` | Current peer; supported and offline-tested |
+| `4.0.10` | `LanguageModelV4`, `specificationVersion: "v4"` | Supported and offline-tested |
+| `4.0.13` | `LanguageModelV4`, `specificationVersion: "v4"` | Current peer; supported and offline-tested |
 
 The peer dependency is intentionally exact. `createAiSdkProvider()` reads its resolved `@ai-sdk/provider/package.json` version during setup and throws typed `AiSdkProviderError { code: "unsupported_version" }` for an unlisted version; it does not infer compatibility from a matching `"v4"` string.
 
@@ -145,7 +148,7 @@ Official evidence: [Custom providers / LanguageModelV4](https://ai-sdk.dev/provi
 
 ## Extension and configuration notes
 
-- Peer dependency: `@ai-sdk/provider@4.0.10` (matrix also lists `4.0.3` and `4.0.4`). Upgrade policy adds a matrix row and offline conformance fixture before accepting any new version.
+- Peer dependency: `@ai-sdk/provider@4.0.13` (matrix also lists `4.0.3`, `4.0.4`, and `4.0.10`). Upgrade policy adds a matrix row and offline conformance fixture before accepting any new version.
 - First-party HTTP providers remain independent; this adapter is available directly or through `@arnilo/prism-providers`. Installation does not select a model or invoke AI SDK.
 - `options.compat` / `options.extra` pass through as AI SDK `providerOptions.prism`.
 - Export helpers `toAiSdkCallOptions`, `toAiSdkPrompt`, and `mapAiSdkStream` for tests and custom hosts.