@arnilo/prism 0.0.1 → 0.0.3

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.

package/docs/provider-packages.md

@@ -53,13 +53,70 @@ api.registerProviderRequestPolicy(createSessionCachePolicy({ retention: "short"
 api.registerSystemPromptContribution({ id: "demo-prompt", source: "package", mode: "append", text: "Use demo provider rules." });
 ```
 
-Hosts decide which credential resolvers, env objects, OAuth stores, request policies, and prompt contributions become active. Request policies can set generic `ProviderRequest.options` such as `sessionId`, `cacheRetention`, `headers`, retry/timeouts, and opaque `extra`; provider adapters decide how to map those options to provider payloads.
+Hosts decide which credential resolvers, env objects, OAuth stores, request policies, and prompt contributions become active. Request policies can set generic `ProviderRequest.options` such as `sessionId`, `cacheRetention`, `headers`, `compat`, and opaque `extra`; provider adapters decide how to map those options to provider payloads. Caller headers are extension headers only: provider adapters must apply provider-owned headers (auth, content type, session/cache/security, attribution) after caller headers so requests cannot override credentials or provider policy.
+
+Deprecated provider request options: `timeoutMs`, `maxRetries`, and `maxRetryDelayMs` are inert in first-party providers. Use `RunOptions.signal`/host abort controllers for timeouts and `AgentConfig.retry`/`RunOptions.retry` for retry. Provider packages should not add provider-specific retry loops unless the vendor protocol requires it and runtime retry cannot cover the failure mode.
+
+First-party providers map generic `ModelConfig.parameters.maxTokens` to real output-token request fields instead of sending `maxTokens` on the wire: OpenAI Responses uses `max_output_tokens`; OpenRouter, OpenCode Go OpenAI-compatible, OpenCode Go Anthropic-style, Z.AI, Kimi, and NeuralWatt use `max_tokens`. Other `model.parameters` values pass through unchanged unless the provider docs say otherwise.
 
 ## First-party provider package skeletons
 
-Phase 12 adds explicit npm workspaces for [`@arnilo/prism-provider-openai`](providers/openai.md), [`@arnilo/prism-provider-opencode-go`](providers/opencode-go.md), [`@arnilo/prism-provider-openrouter`](providers/openrouter.md), [`@arnilo/prism-provider-zai`](providers/zai.md), and [`@arnilo/prism-provider-kimi`](providers/kimi.md). Each package starts with a side-effect-free `create*ProviderPackage()` export, README, TypeScript build, network-free default tests, and an env-gated live-test placeholder.
+Phase 12 adds explicit npm workspaces for [`@arnilo/prism-provider-openai`](providers/openai.md), [`@arnilo/prism-provider-opencode-go`](providers/opencode-go.md), [`@arnilo/prism-provider-openrouter`](providers/openrouter.md), [`@arnilo/prism-provider-zai`](providers/zai.md), [`@arnilo/prism-provider-kimi`](providers/kimi.md), and [`@arnilo/prism-provider-neuralwatt`](providers/neuralwatt.md). Each package starts with a side-effect-free `create*ProviderPackage()` export, README, TypeScript build, network-free default tests, and real opt-in live smoke tests.
+
+Provider live tests are real smoke tests gated by `PRISM_LIVE_PROVIDER_TESTS=1` plus the provider-specific API key (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `KIMI_API_KEY`, `ZAI_API_KEY`, `NEURALWATT_API_KEY`, or `OPENCODE_API_KEY`). They cover text generation, tool-call loop behavior, abort/error paths where supported, and no-secret-leak assertions; they skip by default and never run in release verification.
+
+These workspaces still follow the same rule as external packages: no provider SDK dependency, catalog fetch, env scan, keychain/file credential lookup, shell auth command, OAuth login, or live provider call runs by default. `@arnilo/prism-provider-openai` now registers OpenAI Responses and OpenAI Codex providers from caller-supplied credentials only. `@arnilo/prism-provider-opencode-go` now registers static OpenCode Go metadata and package-local OpenAI/Anthropic-compatible routes from caller-supplied credentials only. `@arnilo/prism-provider-openrouter` now registers an app-controlled OpenRouter catalog with routing/reasoning/cache passthrough and no setup catalog fetch. `@arnilo/prism-provider-zai` now registers static GLM metadata with Z.AI thinking/reasoning/tool-stream request mapping. `@arnilo/prism-provider-kimi` now registers Kimi Coding Anthropic-compatible behavior by default and optional Moonshot metadata only when requested. `@arnilo/prism-provider-neuralwatt` now registers static featured model metadata with NeuralWatt reasoning_effort/thinking_token_budget/chat_template_kwargs request mapping, SSE comment tolerance, an opt-in `listNeuralWattModels()` helper for explicit `/v1/models` discovery, `getNeuralWattQuota()` for on-demand account balance/usage/energy, `neuralWattEventsWithTelemetry()`/`mapNeuralWattTelemetry()` for `: energy`/`: cost` telemetry, and `classifyNeuralWattError()` for retry classification. None of these helpers run during package setup or generation.
+
+### First-party cache behavior
+
+Every first-party provider package hardens prompt-cache behavior so it cannot emit invalid cache retention values or over-broad cache-control markers, and so provider-owned `authorization`/session/security headers cannot be overridden by caller `ProviderRequest.options.headers`. Cache behavior is provider-specific and best-effort: OpenAI/OpenRouter use explicit hints, NeuralWatt/Z.AI use implicit caching, and OpenCode Go/Kimi are route/model-dependent. See [Provider caching](provider-caching.md#per-provider-cache-behavior) for the canonical explicit/implicit matrix.
+
+- **OpenAI** (`kind: openai_key`): `prompt_cache_key` is sanitized and clamped to 64 chars; `prompt_cache_retention` is emitted as `24h` only when the model declares `cache.longRetention`, and omitted for `short`/`none` (the API only accepts absent or `24h`). `prompt_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`.
+- **OpenAI-compatible core adapter**: Chat Completions sends no `prompt_cache_key`/`prompt_cache_retention`/`cache_control` fields; endpoints cache implicitly. `prompt_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`.
+- **OpenRouter** (`kind: cache_control`): `session_id`/`x-session-id` sanitized and clamped to 256 chars; `cache_control` markers applied only to caller-selected `cache.breakpoints` (not every block); `cacheRetention: long` adds `ttl: 1h` when allowed. Preserves `cached_tokens`/`cache_write_tokens`.
+- **OpenCode Go**: `x-opencode-session` from `cacheKey ?? sessionId` sanitized to 128 chars; the Anthropic route applies `cache_control` only to selected breakpoints (`long` → `ttl: 1h`), the OpenAI route sends none. Per-route usage mapping.
+- **Z.AI** (`kind: implicit`): GLM context caching is automatic; no explicit cache payload sent regardless of cache options. `prompt_tokens_details.cached_tokens`/`cache_write_tokens` map to cache usage.
+- **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.
+- **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 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 cache usage.
+
+See [Provider caching](provider-caching.md) for the `PromptCacheHints` surface and shared helpers, and [Provider conformance](provider-conformance.md) for the `assertUsageAccounting` and `assertProviderOwnedHeadersWin` checks every first-party package exercises.
+
+## Third-party provider packaging
+
+A third party ships their own providers the same way Prism ships first-party
+provider packages: an `Extension` whose `setup(api)` calls
+`api.registerProvider(provider)` for each provider it owns. First-party
+provider packages (`@arnilo/prism-provider-openai`, `@arnilo/prism-provider-openrouter`,
+`@arnilo/prism-provider-kimi`, `@arnilo/prism-provider-zai`,
+`@arnilo/prism-provider-opencode-go`) are **opt-in and individually installable**;
+`@arnilo/prism` core runs without any first-party provider package (mock-only).
 
-These workspaces still follow the same rule as external packages: no provider SDK dependency, catalog fetch, env scan, keychain/file credential lookup, shell auth command, OAuth login, or live provider call runs by default. `@arnilo/prism-provider-openai` now registers OpenAI Responses and OpenAI Codex providers from caller-supplied credentials only. `@arnilo/prism-provider-opencode-go` now registers static OpenCode Go metadata and package-local OpenAI/Anthropic-compatible routes from caller-supplied credentials only. `@arnilo/prism-provider-openrouter` now registers an app-controlled OpenRouter catalog with routing/reasoning/cache passthrough and no setup catalog fetch. `@arnilo/prism-provider-zai` now registers static GLM metadata with Z.AI thinking/reasoning/tool-stream request mapping. `@arnilo/prism-provider-kimi` now registers Kimi Coding Anthropic-compatible behavior by default and optional Moonshot metadata only when requested.
+A host mixes first-party packages and third-party providers in one resolver.
+The host owns the resolver — declaring a provider does not activate it:
+
+```ts
+import { createExtensionKernel, createProviderResolver, createAgent } from "@arnilo/prism";
+import { createOpenAIProviderPackage } from "@arnilo/prism-provider-openai";
+
+// First-party package, inert until loaded.
+const kernel = createExtensionKernel();
+await kernel.load([createOpenAIProviderPackage({ apiKey: () => process.env.OPENAI_API_KEY })]);
+
+// Third-party own provider (bring your own adapter). Combined with first-party
+// providers in one resolver passed to the agent as `providerSource`.
+const own = createMyProvider(/* credentials */);
+const providerSource = createProviderResolver([...kernel.registries.providers.list(), own]);
+
+const agent = createAgent({ model: { provider: own.id, model: "demo" }, providerSource });
+```
+
+The resolver is the selection mechanism: `model.provider` selects which
+provider runs per turn. Hosts can build the resolver from a `ProviderRegistry`,
+a plain `AIProvider[]`, or implement `ProviderResolver` directly as a one-line
+function over their own map (lazy construction, per-request routing). Declaring
+a provider grants no permissions and forces no activation; the host always has
+final say. See [Provider layer § Provider resolver](provider-layer.md#provider-resolver)
+for the resolver contract.
 
 ## Outputs / response / events
 
@@ -67,7 +124,7 @@ These workspaces still follow the same rule as external packages: no provider SD
 
 ## Request/response example
 
-Provider package manifest contribution and the generic request options a provider request policy can set:
+Provider package manifest contribution and the generic request options a provider request policy can set (see [Provider request policies](provider-request-policies.md) and [Provider caching](provider-caching.md)):
 
 ```json
 {
@@ -83,7 +140,8 @@ Provider package manifest contribution and the generic request options a provide
     "cacheKey": "demo",
     "cacheRetention": "short",
     "headers": { "x-demo": "1" }
-  }
+  },
+  "runOptions.retry": { "maxAttempts": 3, "maxDelayMs": 1000 }
 }
 ```
 
@@ -124,6 +182,7 @@ await kernel.load([pkg]);
   (`provider_request`) that sets generic `ProviderRequest.options`
   (`sessionId`, `cacheKey`, `cacheRetention`, `headers`, opaque `extra`) before
   `AIProvider.generate()`; provider adapters map those options to provider payloads.
+- `ModelConfig.cache` is the generic cache capability metadata documented in [Model registry](model-registry.md); `ModelConfig.compat` remains provider-owned inert JSON for behavior that has no generic field yet.
 - `ModelConfig.compat` is provider-owned inert JSON: cache policy overrides,
   reasoning/thinking formats, and provider-specific usage mapping live there
   rather than in core, so Prism never branches on provider names.
@@ -139,6 +198,7 @@ await kernel.load([pkg]);
 - Registration is in-memory only and does no filesystem, network, env, OAuth refresh, or command access.
 - Provider-specific behavior belongs in provider packages, not Prism core.
 - Adapter serializers should preserve Prism content blocks (text, thinking, tool_call, tool_result, and image when the model declares image input) in provider-native request shape, or fail explicitly when a block is unsupported.
+- Adapter header merging must put caller-supplied `ProviderRequest.options.headers` first and provider-owned headers last. Caller headers may add non-owned headers, but cannot replace resolved credentials, content type, session/cache/security headers, or provider attribution headers.
 
 ## Manifest declarations