@arnilo/prism 0.0.1 → 0.0.2

package/docs/performance.md

@@ -0,0 +1,127 @@
+# Performance limits
+
+## What it does
+
+This page states Prism runtime limits that keep slow consumers and long sessions from becoming unbounded memory or latency problems.
+
+Current surfaces:
+
+- `SubscribeOptions` for bounded live `AgentEvent` subscriber queues.
+- `SessionStore.readBranchPath(query)` for branch reads that avoid full-session scans.
+- `ProductionPersistenceStore` cursor queries for entries, events, runs, tool calls, and usage.
+- JSONL and memory stores documented as development/local adapters, not production multi-writer stores.
+
+## When to use it
+
+Use these limits when embedding Prism in a UI, API server, job worker, or multi-tenant app that may have slow event consumers or long-lived sessions.
+
+Do not treat Prism's live event subscribers as a durable queue. Use `RunLedger` / database persistence for replay, audit, billing, and timelines.
+
+## Inputs / request
+
+```ts
+import { createAgent, type SubscribeOptions } from "@arnilo/prism";
+
+const options: SubscribeOptions = {
+  maxQueuedEvents: 256,
+  overflow: "close",
+};
+
+const events = session.subscribe(options);
+```
+
+`SubscribeOptions` fields:
+
+| Field | Default | Purpose |
+| --- | --- | --- |
+| `maxQueuedEvents` | `1024` | Maximum events queued for one subscriber while it is not awaiting `next()`. Values below `1` are clamped to `1`. |
+| `overflow` | `"close"` | Overflow policy: `"close"`, `"drop_oldest"`, or `"drop_newest"`. |
+
+## Outputs / response / events
+
+On default overflow, the affected subscriber receives one `event_subscriber_overflow` event and then finishes:
+
+```json
+{
+  "type": "event_subscriber_overflow",
+  "sessionId": "session_1",
+  "droppedEvents": 257,
+  "maxQueuedEvents": 256,
+  "overflow": "close"
+}
+```
+
+`drop_oldest` keeps the newest queued events. `drop_newest` ignores incoming events while the queue is full. These policies are live-view policies only; they do not affect `RunLedger` writes or stored session entries.
+
+## Request/response example
+
+```json
+{
+  "subscribe": { "maxQueuedEvents": 256, "overflow": "close" },
+  "store": "database-backed SessionStore with readBranchPath",
+  "eventLedger": "cursor-paginated by runId and sequence"
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgent, createMockProvider, providerDone, providerTextDelta } from "@arnilo/prism";
+
+const agent = createAgent({
+  model: { provider: "mock", model: "demo" },
+  provider: createMockProvider([providerTextDelta("Hello"), providerDone()]),
+});
+
+const session = agent.createSession();
+const reader = (async () => {
+  for await (const event of session.subscribe({ maxQueuedEvents: 256, overflow: "close" })) {
+    if (event.type === "event_subscriber_overflow") break;
+    render(event);
+  }
+})();
+
+await session.run("Hi");
+await reader;
+
+function render(_event: unknown) {}
+```
+
+For production branch reads, implement `SessionStore.readBranchPath` instead of loading every entry:
+
+```ts
+const store = {
+  async append(entry, options) { /* transaction + parent/idempotency checks */ },
+  async list(sessionId) { /* development fallback only */ return []; },
+  async readBranchPath(query) {
+    // Use one ancestor query / recursive CTE and return a cursor page.
+    return { items: [], nextCursor: undefined };
+  },
+};
+```
+
+## Extension and configuration notes
+
+- `SubscribeOptions` is per subscriber. One slow UI can be closed or dropped without affecting other subscribers, the active run, ledger writes, or session storage.
+- `RunLedger` remains the durable event/timeline surface. Hosts may batch inside their ledger adapter, but Prism awaits ledger writes at safe boundaries; preserve per-run event order before acknowledging a batch.
+- Database-backed stores should implement `readBranchPath` and cursor-paginated `ProductionPersistenceStore` queries. Memory and JSONL stores intentionally use full-session/file reads.
+- Cursor pagination should use indexed keys, not offsets: `(run_id, sequence)` for events, `(session_id, started_at, id)` for runs, `(run_id, recorded_at, id)` for usage, and `(session_id, timestamp, id)` for entries.
+- Hosts own queue sizes, page-size caps, database indexes, connection pools, transaction timeouts, retention jobs, partitioning, and multi-process coordination.
+
+## Security and performance notes
+
+- Overflow events contain only counts and policy, never message text, tool arguments, prompts, provider payloads, or credentials.
+- Runtime event payloads can be large (`Message`, content deltas, tool results, summaries, artifact metadata). Size queues by events and keep payload size in mind.
+- Live subscriber queues are bounded by default. Durable replay belongs to host storage.
+- `SessionStore.list(sessionId)` is a full-session read. It is fine for memory/JSONL development stores, but production adapters should use `readBranchPath` for provider context and branch views.
+- The JSONL store rereads/parses the file for validation/list/get and serializes appends only within one process. It has no cross-process lock, pagination, migrations, tenant isolation, or retention.
+- Recommended database indexes: session id, run id, parent id, branch leaf id, timestamps, tenant/account/user, event type, entry kind, `(run_id, sequence)` for event timelines, and `(run_id, recorded_at, id)` for usage. Allocate event `sequence` per run for stable timeline pagination.
+
+## Related APIs
+
+- [Agent events](agent-events.md): `SubscribeOptions` and `event_subscriber_overflow` event details.
+- [Agent/session runtime](agent-session-runtime.md): `session.subscribe()` and runtime event flow.
+- [Session stores](session-stores.md): `SessionStore.readBranchPath` and dev-vs-production branch reads.
+- [Database persistence](database-persistence.md): cursor queries, reference schema, indexes, and event sequence guidance.
+- [Runs and usage ledger](runs-and-usage.md): durable event, tool-call, and usage persistence.
+- [Node JSONL session store](node-jsonl-session-store.md): development-only JSONL limits.

package/docs/provider-caching.md

@@ -0,0 +1,206 @@
+# Provider caching
+
+## What it does
+
+Provider caching documents Prism's cache intent surface:
+
+- `ProviderRequestOptions.cache?: PromptCacheHints` for structured, provider-agnostic cache hints.
+- Legacy aliases `cacheKey` and `cacheRetention`, still supported for backwards compatibility.
+- `PromptCacheBreakpoint` locations for reusable prompt regions.
+- `ModelCacheCapabilities` for model/provider cache support metadata.
+- Shared helpers: `sanitizeCacheKey`, `mapCacheRetention`, `applyCacheControl`, `cacheHitRate`, `cacheSavings`, and `cacheUsageReport`.
+
+Cache hints are best-effort. They describe intent; providers decide whether their native API can use them. Prism does not guarantee cache hits.
+
+## When to use it
+
+Use this page when a host or provider package needs to:
+
+- Mark stable system prompts, tools, context, or messages as cacheable.
+- Opt into cache-aware default input ordering so stable attachments/resources, summaries, and prior history form a reusable prefix before the current user turn.
+- Carry a stable cache key across turns without putting provider-specific fields in core.
+- Read `ModelConfig.cache` to decide whether to map hints to implicit caching, key-based caching, cache-control breakpoints, provider-specific caching, or no caching.
+- Compute normalized cache diagnostics from `Usage.cacheReadTokens` / `Usage.cacheWriteTokens`, including providers that only report reads.
+
+Do not use cache keys for credentials, bearer tokens, API keys, OAuth tokens, user secrets, or raw private prompts.
+
+## Inputs / request
+
+```ts
+import type {
+  ModelCacheCapabilities,
+  PromptCacheBreakpoint,
+  PromptCacheHints,
+  ProviderRequestOptions,
+} from "@arnilo/prism";
+```
+
+| Type / field | Purpose |
+| --- | --- |
+| `PromptCacheHints.mode?: "auto" | "on" | "off"` | Host intent. Providers may ignore unsupported modes. |
+| `PromptCacheHints.key?: string` | Stable, untrusted cache key. Sanitize before sending to provider APIs. |
+| `PromptCacheHints.retention?: "none" | "short" | "long"` | Desired retention. `mapCacheRetention()` downgrades unsupported long retention. |
+| `PromptCacheHints.breakpoints?: readonly PromptCacheBreakpoint[]` | Stable prompt locations to mark for cache-control style providers. |
+| `PromptCacheBreakpoint.location` | `system_prompt`, `tools`, `stable_context`, `last_stable_message`, `last_user_message`, or `message_id`. |
+| `PromptCacheBreakpoint.messageId?` | Required when `location: "message_id"`. |
+| `PromptCacheBreakpoint.ttl?` | Generic `short` / `long` hint. Provider packages map to native TTL shape. |
+| `ModelConfig.cache?: ModelCacheCapabilities` | Static model/provider cache support metadata. |
+
+`ModelCacheCapabilities.kind` values are generic: `implicit`, `openai_key`, `cache_control`, `provider_specific`, or `none`. Core never branches on provider names; provider packages read the metadata and map it to native requests.
+
+Legacy alias note: `cacheKey` maps to `cache.key`, and `cacheRetention` maps to `cache.retention`. When both are present, structured `cache.key` / `cache.retention` is the authoritative cache intent for providers that read structured hints; legacy fields remain for older adapters.
+
+## Outputs / response / events
+
+Cache helpers return plain data:
+
+| Helper | Output |
+| --- | --- |
+| `sanitizeCacheKey(value, maxLength)` | Safe key string or `undefined`. |
+| `mapCacheRetention(retention, model)` | `"short"`, `"long"`, or `undefined`. |
+| `applyCacheControl(messages, breakpoints, options)` | New message array with `cache_control: { type: "ephemeral" }` on selected message anchors. |
+| `cacheHitRate(usage)` | Cached input ratio or `undefined`. |
+| `cacheSavings(usage, model)` | Estimated read-token savings or `undefined` without pricing. |
+| `cacheUsageReport(usage, model?)` | Normalized read/write tokens, hit rate, estimated savings, and currency when available; `undefined` when no usage is supplied. |
+
+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.
+
+## Request/response example
+
+```json
+{
+  "providerRequest.options": {
+    "sessionId": "sess_123",
+    "cache": {
+      "mode": "on",
+      "key": "sess_123",
+      "retention": "long",
+      "breakpoints": [
+        { "location": "system_prompt" },
+        { "location": "last_user_message" }
+      ]
+    }
+  },
+  "model.cache": {
+    "kind": "cache_control",
+    "maxBreakpoints": 4,
+    "minCacheableTokens": 1024,
+    "longRetention": true
+  }
+}
+```
+
+## Implementation example
+
+```ts
+import {
+  applyCacheControl,
+  cacheHitRate,
+  cacheUsageReport,
+  mapCacheRetention,
+  sanitizeCacheKey,
+  type ModelConfig,
+  type PromptCacheHints,
+} from "@arnilo/prism";
+
+const model: ModelConfig = {
+  provider: "demo",
+  model: "demo-large",
+  cache: { kind: "cache_control", maxBreakpoints: 4, longRetention: true },
+};
+
+const hints: PromptCacheHints = {
+  mode: "on",
+  key: "workspace:agent#1",
+  retention: "long",
+  breakpoints: [{ location: "system_prompt" }, { location: "last_user_message" }],
+};
+
+const key = sanitizeCacheKey(hints.key, model.cache?.maxKeyLength ?? 128);
+const retention = mapCacheRetention(hints.retention, model);
+const stamped = applyCacheControl(messages, hints.breakpoints ?? [], { maxBreakpoints: model.cache?.maxBreakpoints });
+const hitRate = cacheHitRate({ inputTokens: 1000, cacheReadTokens: 800 });
+const report = cacheUsageReport({ inputTokens: 1000, cacheReadTokens: 800 }, model);
+// { cacheReadTokens: 800, cacheWriteTokens: 0, hitRate: 0.8, ... }
+
+await session.run("Explain this", { inputLayout: "cache_aware" });
+```
+
+## Extension and configuration notes
+
+Provider request policies can set `ProviderRequestOptions.cache` or the legacy `cacheKey` / `cacheRetention` aliases. Provider packages decide how to map hints to native payloads:
+
+| `ModelCacheCapabilities.kind` | Typical mapping |
+| --- | --- |
+| `implicit` | No request mutation; provider caches automatically. |
+| `openai_key` | Send sanitized cache key and mapped retention where supported. |
+| `cache_control` | Use `applyCacheControl()` on provider-native message anchors. |
+| `provider_specific` | Provider package uses `compat`/native options intentionally. |
+| `none` | Do not send cache fields. |
+
+### Per-provider cache behavior
+
+| 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-openrouter` | `cache_control` | Applies `cache_control` markers only to caller-selected `cache.breakpoints`; `"long"` may add `ttl: "1h"`. | Breakpoint-stable prefixes can be reused by upstream providers. | Best-effort only; no marker is added to every block. |
+| `@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. |
+
+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. `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).
+- OpenRouter (`@arnilo/prism-provider-openrouter`): `kind: "cache_control"`. Sanitizes/clamps `session_id`/`X-Session-Id` to 256 chars; applies Anthropic-style `cache_control` markers only to caller-selected `cache.breakpoints` (last content block of each selected message), not every block; `"long"` retention adds `ttl: "1h"` when the model allows it. `prompt_tokens_details.cached_tokens`/`cache_write_tokens` map to `Usage.cacheReadTokens`/`cacheWriteTokens`.
+- OpenCode Go (`@arnilo/prism-provider-opencode-go`): `x-opencode-session` from `cacheKey ?? sessionId`, sanitized to 128 chars; the Anthropic route applies `cache_control` markers only to selected breakpoints (`"long"` → `ttl: "1h"`), the OpenAI route sends none. OpenAI route maps `prompt_tokens_details.cached_tokens`/`cache_write_tokens`; Anthropic route maps `cache_read_input_tokens`/`cache_creation_input_tokens`.
+- 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`.
+
+### NeuralWatt cache-aware limiter
+
+NeuralWatt (`@arnilo/prism-provider-neuralwatt`) runs a cache-aware backend rate
+limiter on top of its implicit vLLM prefix cache. This shapes long-running agent
+sessions differently from one-shot chat:
+
+- **Uncached TPM counts cold prefill only.** The tokens-per-minute budget charges the
+  prefix that is not already cached. A request whose prefix is fully cached consumes
+  far less TPM than a cold request of the same total prompt length.
+- **Warm-prefix requests can avoid some `503` fleet-capacity blocks.** Near fleet
+  capacity, requests that reuse a cached prefix are more likely to be admitted than
+  fully cold requests. Prefix reuse is both an availability and a latency lever.
+- **Full prior history is required for multi-turn cache reuse.** The prefix cache is
+  keyed by request content, so each follow-up turn must resend the entire prior
+  transcript (system prompt + all prior turns) unchanged, with only the new turn
+  appended. Use `inputLayout: "cache_aware"` so Prism keeps the stable prefix first.
+- Cache behavior is best-effort and **does not guarantee cache hits**. Admission and
+  eviction are server-side decisions and vary with fleet load. `cacheRetention:
+  "none"` disables Prism cache-control hints only; it does not disable the implicit
+  backend prefix cache.
+
+See [NeuralWatt provider](providers/neuralwatt.md) for the package-level cache,
+usage, and retry details.
+
+## Security and performance notes
+
+- Cache hints are best-effort and do not guarantee cache hits.
+- Cache keys are untrusted input; sanitize and truncate with `sanitizeCacheKey()` before provider I/O.
+- Cache keys must never be credentials or secrets.
+- Provider-owned auth/session/security headers always win over caller headers.
+- Helpers are pure, network-free, and O(messages) at most. `cacheUsageReport()` is O(1).
+- Cache-aware input ordering does not change resource loading: URI attachments/resources still load only through the caller-provided `ResourceLoader`.
+- Cache usage reports contain only usage counts and optional pricing/currency; they do not include prompt text, cache keys, headers, credentials, or provider payloads.
+- `applyCacheControl()` returns new message objects for stamped anchors and does not mutate input messages.
+
+## Related APIs
+
+- [Input and prompt assembly](input-and-prompt-assembly.md): opt-in cache-aware ordering for stable provider payload prefixes.
+- [Provider request policies](provider-request-policies.md): set cache hints before provider calls.
+- [Model registry](model-registry.md): register `ModelConfig.cache` capability metadata.
+- [Provider layer](provider-layer.md): provider/model registries and provider events.
+- [Provider packages](provider-packages.md): package-owned mapping to provider-native cache APIs.
+- [Public contracts](public-contracts.md): public type list for cache contracts and helpers.

package/docs/provider-conformance.md

@@ -12,14 +12,17 @@ Exported from `@arnilo/prism/testing/provider-conformance`:
 - `assertToolCallDeltasReconstruct(events, expected)`
 - `assertUsageAccounting(events, expected)`
 - `assertSerializedRequestCoversContent(request, body, options?)`
+- `assertProviderOwnedHeadersWin(captured, options)`
 - `assertNoSecretLeak(events, secrets)`
 
 ## When to use it
 
-Use these helpers in provider package tests to check event order, terminal events, abort propagation, streamed tool-call deltas, usage/cache accounting, request body content preservation, and secret redaction.
+Use these helpers in provider package tests to check event order, terminal events, abort propagation via `ProviderRequest.signal`, streamed tool-call deltas, usage/cache accounting, request body content preservation, protected header ownership, and secret redaction. Do not treat deprecated `ProviderRequestOptions.timeoutMs`/`maxRetries`/`maxRetryDelayMs` as conformance requirements; first-party providers use runtime abort signals and `AgentConfig.retry`/`RunOptions.retry` instead.
 
 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.
+
 ## Inputs / request
 
 ```ts
@@ -41,10 +44,11 @@ Helpers accept normal `AIProvider`, `ProviderRequest`, `ProviderEvent`, `Usage`,
 
 - `collectProviderEvents()` returns provider events in stream order.
 - `assertProviderStreamConforms()` returns collected events after verifying the stream ends with `done` or `error`, terminal events are last, and optional text/usage expectations match.
-- `assertAbortIsObserved()` passes an already-aborted signal and expects provider generation to reject.
-- `assertToolCallDeltasReconstruct()` rebuilds streamed `tool_call_delta` fragments into tool calls and validates expected id/name/arguments.
-- `assertUsageAccounting()` finds `usage` or `done.usage` and checks selected token fields including `cacheReadTokens` and `cacheWriteTokens`.
-- `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.
+- `assertAbortIsObserved()` passes an already-aborted signal and expects provider generation to reject. This is the supported timeout primitive; use a host abort controller or `RunOptions.signal` rather than deprecated provider-level `timeoutMs`.
+- `assertToolCallDeltasReconstruct()` rebuilds streamed `tool_call_delta` fragments into tool calls and validates expected id/name/arguments. The runtime uses the same reconstruction behavior before tool execution when a provider streams deltas.
+- `assertUsageAccounting()` finds `usage` or `done.usage` and checks selected token fields including `cacheReadTokens` and `cacheWriteTokens`. This is the provider-neutral check for normalized cache read/write token extraction; every first-party provider package exercises it against server-specific fields (`cached_tokens`, `cache_read_input_tokens`, etc.).
+- `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.
 
 ## Request/response example
@@ -56,6 +60,18 @@ Helpers accept normal `AIProvider`, `ProviderRequest`, `ProviderEvent`, `Usage`,
 }
 ```
 
+Tool-call delta reconstruction example:
+
+```ts
+import { assertToolCallDeltasReconstruct } from "@arnilo/prism/testing/provider-conformance";
+
+assertToolCallDeltasReconstruct([
+  { type: "tool_call_delta", index: 0, id: "call_1", name: "lookup", argumentsText: "{\"q\":" },
+  { type: "tool_call_delta", index: 0, argumentsText: "\"prism\"}" },
+  { type: "done" },
+], [{ index: 0, id: "call_1", name: "lookup", arguments: { q: "prism" } }]);
+```
+
 Content-preservation example:
 
 ```ts
@@ -77,6 +93,17 @@ const body = JSON.parse(String(fetchInit.body));
 assertSerializedRequestCoversContent(request, body, { unsupported: ["image"] });
 ```
 
+Protected header-ownership example:
+
+```ts
+import { assertProviderOwnedHeadersWin } from "@arnilo/prism/testing/provider-conformance";
+
+assertProviderOwnedHeadersWin(capturedHeaders, {
+  owned: { authorization: "Bearer provider-key", "content-type": "application/json" },
+  caller: { authorization: "Bearer attacker", "content-type": "text/plain", "x-caller": "kept" },
+});
+```
+
 ## Implementation example
 
 ```ts

package/docs/provider-layer.md

@@ -5,9 +5,10 @@
 The provider layer contains the small runtime pieces Prism already ships for host-owned model access:
 
 - `createProviderRegistry()` / `ProviderRegistry`: register and resolve `AIProvider` instances by id.
-- `createModelRegistry()` / `ModelRegistry`: register and resolve `ModelConfig` values by provider/model key.
-- `ModelConfig` metadata fields for display names, capabilities, limits, cost/cache pricing, opaque provider compat data, and host metadata.
-- Provider event helpers: create normalized `ProviderEvent` values for text, thinking, tool calls, usage, done, and errors, including optional cache read/write usage fields.
+- `createProviderResolver()` / `ProviderResolver`: build a resolver that maps a `ModelConfig` to an `AIProvider` (or `undefined`), from a `ProviderRegistry` or a plain `AIProvider[]`.
+- `createModelRegistry()` / `ModelRegistry`: register and resolve `ModelConfig` values by provider/model key. See [Model registry](model-registry.md).
+- `ModelConfig` metadata fields for display names, capabilities, limits, cost/cache pricing, cache support metadata, opaque provider compat data, and host metadata. See [Provider caching](provider-caching.md).
+- Provider event helpers: create normalized `ProviderEvent` values for text, thinking, streamed tool-call deltas, final tool calls, usage, done, and errors, including optional cache read/write usage fields.
 - `toolCallContent()`: create a `ToolCallContent` block.
 - `createMockProvider()` / `MockProviderOptions`: create a deterministic scripted `AIProvider` for tests and examples.
 - `@arnilo/prism/testing/provider-conformance`: optional network-free assertion helpers for provider adapter tests.
@@ -23,21 +24,21 @@ Use this layer when a host app, extension package, or test needs to:
 - Emit provider events without hand-writing event objects.
 - Test agent/provider flows without timers, credentials, SDKs, or network calls.
 
-Do not use this layer for credential storage, settings loading, tool dispatch, agent loops, package discovery, cache stores, or provider SDK configuration. Those stay host-owned or belong to provider packages.
+Do not use this layer for credential storage, settings loading, tool dispatch, agent loops, package discovery, cache stores, or provider SDK configuration. Those stay host-owned or belong to provider packages. Request option hooks are covered in [Provider request policies](provider-request-policies.md).
 
 ## Inputs / request
 
 ### Provider registry
 
 ```ts
-createProviderRegistry(providers?: readonly AIProvider[]): ProviderRegistry
+createProviderRegistry(providers?: readonly AIProvider[], options?: { duplicate?: "replace" | "error" }): ProviderRegistry
 ```
 
 `ProviderRegistry` methods:
 
 | Method | Input | Result |
 | --- | --- | --- |
-| `register(provider)` | `AIProvider` | Stores provider by `provider.id`. |
+| `register(provider)` | `AIProvider` | Stores/replaces provider by `provider.id`; throws `Duplicate provider: <id>` when `duplicate: "error"`. |
 | `get(id)` | provider id string | Returns provider or `undefined`. |
 | `resolve(model)` | provider id string or `{ provider: string }` | Returns provider or throws `Unknown provider: <id>`. |
 | `list()` | none | Returns registered providers in insertion order. |
@@ -45,14 +46,14 @@ createProviderRegistry(providers?: readonly AIProvider[]): ProviderRegistry
 ### Model registry
 
 ```ts
-createModelRegistry(models?: readonly ModelConfig[]): ModelRegistry
+createModelRegistry(models?: readonly ModelConfig[], options?: { duplicate?: "replace" | "error" }): ModelRegistry
 ```
 
 `ModelRegistry` methods:
 
 | Method | Input | Result |
 | --- | --- | --- |
-| `register(model)` | `ModelConfig` | Stores model by provider/model key, preserving inert metadata. |
+| `register(model)` | `ModelConfig` | Stores/replaces model by provider/model key, preserving inert metadata; throws `Duplicate model: <provider>/<model>` when `duplicate: "error"`. |
 | `get(provider, model)` | provider id and model id | Returns model config or `undefined`. |
 | `resolve(provider, model)` | provider id and model id | Returns model config or throws `Unknown model: <provider>/<model>`. |
 | `list()` | none | Returns registered model configs in insertion order. |
@@ -71,6 +72,8 @@ providerError(error: unknown, secrets?: readonly (string | undefined)[]): Provid
 toolCallContent(id: string, name: string, args?: JsonObject): ToolCallContent
 ```
 
+`tool_call_delta` fragments use the same `{ index, id?, name?, argumentsText? }` shape as live `message_delta` content. Runtime reconstructs final `ToolCallContent` before tool execution; conformance tests use the same reconstruction rules.
+
 ### Mock provider
 
 ```ts
@@ -84,13 +87,49 @@ createMockProvider(events?: readonly ProviderEvent[], options?: MockProviderOpti
 | `id` | `string` | Optional provider id. Defaults to `mock`. |
 | `onRequest` | `(request: ProviderRequest) => void` | Optional request observer for tests. |
 
+### Provider resolver
+
+```ts
+export type ProviderResolver = (model: ModelConfig) => AIProvider | undefined;
+
+createProviderResolver(source: ProviderRegistry | readonly AIProvider[]): ProviderResolver
+```
+
+A `ProviderResolver` maps a `ModelConfig` to an `AIProvider` for the current
+run. `createProviderResolver()` builds one from a `ProviderRegistry` (reuses
+`ProviderRegistry.get`) or a plain `AIProvider[]` (builds an id-keyed lookup
+once at construction; last duplicate id wins). A custom function is the
+zero-helper path for hosts with their own provider map (lazy construction,
+per-request routing).
+
+The resolver returns `undefined` on a miss; the agent runtime fails closed with
+`Unknown provider: ${model.provider}` before any provider turn (see
+[Agent/session runtime](agent-session-runtime.md)).
+
+Wire `providerSource` on `AgentConfig`, override per run with
+`RunOptions.providerSource` (RunOptions wins). When `AgentConfig.provider` is
+set it takes first precedence and the resolver is bypassed. The resolver is
+called once per run with `options.model ?? config.model`; per-turn
+re-resolution is unnecessary.
+
+```ts
+import { createAgent, createProviderResolver, createProviderRegistry } from "@arnilo/prism";
+
+const own = createMyProvider();
+const providerSource = createProviderResolver(createProviderRegistry([own]));
+// or mix first-party + own in one list:
+// const providerSource = createProviderResolver([firstPartyProvider, own]);
+
+const agent = createAgent({ model: { provider: own.id, model: "demo" }, providerSource });
+```
+
 ## Outputs / response / events
 
 - Registry `resolve()` returns the matching provider/model or throws before any provider `generate()` call.
 - Provider event helpers return plain `ProviderEvent` objects.
 - `providerError()` converts unknown errors to redacted `ErrorInfo` through `errorToErrorInfo()` and preserves safe string/number `code` fields for retry classification.
 - `createMockProvider()` returns an `AIProvider` whose `generate()` yields the scripted events in order and checks `request.signal?.aborted` before each event.
-- The agent/session runtime passes its per-run abort signal as `ProviderRequest.signal`.
+- The agent/session runtime passes its per-run abort signal as `ProviderRequest.signal`. `ProviderRequestOptions.timeoutMs`, `maxRetries`, and `maxRetryDelayMs` are deprecated inert hints in first-party providers; use `RunOptions.signal`/host abort controllers for timeouts and `AgentConfig.retry`/`RunOptions.retry` for retry.
 
 ## Request/response example
 
@@ -147,6 +186,7 @@ for await (const event of resolvedProvider.generate({
 ## Extension and configuration notes
 
 - Registries are explicit objects returned by factories. Prism does not create a hidden global provider/model registry.
+- Default duplicate policy is `"replace"` for compatibility. Hosts that load third-party provider/model contributions can pass `duplicate: "error"` to reject silent shadowing.
 - Extension packages can contribute `AIProvider` and `ModelConfig` values by registering them with host-owned registries.
 - Model resolution and provider resolution are separate on purpose: hosts can validate a model exists before selecting a provider.
 - Credential resolvers stay outside these registries; pass credentials directly to the provider adapter or runtime edge that needs them.
@@ -154,7 +194,7 @@ for await (const event of resolvedProvider.generate({
 
 ## Security and performance notes
 
-- Provider/model registries are `Map`-backed and perform O(1) lookup.
+- Provider/model registries are `Map`-backed and perform O(1) lookup. Strict duplicate mode adds one O(1) `Map.has()` check during registration only.
 - Registries store providers and model metadata only. Do not store API keys, credential resolvers, headers, tokens, or secret-bearing settings in them.
 - Unknown provider/model resolution fails before provider execution or network I/O.
 - `createMockProvider()` uses scripted events only: no timers, credentials, SDKs, or network.
@@ -164,7 +204,7 @@ for await (const event of resolvedProvider.generate({
 
 ## Related APIs
 
-- [Agent/session runtime](agent-session-runtime.md): passes abort signals to providers, maps provider errors to session `error` events, and can retry configured transient provider-turn failures before output.
+- [Agent/session runtime](agent-session-runtime.md): passes abort signals to providers, maps provider errors to session `error` events, and can retry configured transient provider-turn failures before output; this is the supported replacement for deprecated provider-level retry options.
 - [Provider packages](provider-packages.md): explicit package primitive for registering providers, models, auth descriptors, request/cache policies, and prompt contributions.
 - [Public contracts](public-contracts.md): `AIProvider`, `ProviderRequest`, `ProviderEvent`, `ModelConfig`, `Usage`, and content/tool-call contracts.
 - [Credentials and redaction](credentials-and-redaction.md): credential and redaction helpers used by provider adapters.