@arnilo/prism 0.0.13 → 0.0.15

package/docs/provider-conformance.md

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

package/docs/provider-packages.md

@@ -80,7 +80,28 @@ Phase 6 also adds optional [`@arnilo/prism-provider-ai-sdk`](providers/ai-sdk.md
 
 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, with optional `models`/`codexModels` overrides and an opt-in `listOpenAIModels()` helper for official `GET /models` discovery. `@arnilo/prism-provider-opencode-go` now registers docs-verified OpenCode Go open coding models with dual OpenAI/Anthropic routes (`compat.route`), official default base `https://opencode.ai/zen/go/v1`, `reasoning_content`/thinking preserve, and an opt-in `listOpenCodeGoModels()` helper for official `GET /zen/go/v1/models`. `@arnilo/prism-provider-openrouter` now registers an app-controlled OpenRouter catalog with routing/`reasoning`/cache passthrough, assistant `reasoning` replay, optional top-level automatic `cache_control`, and an opt-in `listOpenRouterModels()` helper for official `GET /api/v1/models` (setup still never fetches). `@arnilo/prism-provider-zai` now registers featured GLM-5.x/4.x metadata with official `thinking`/`reasoning_effort`/`tool_stream`/`clear_thinking` mapping, Preserved Thinking `reasoning_content` replay, implicit context caching, and an opt-in `listZaiModels()` helper for OpenAI-compatible `GET /models`. `@arnilo/prism-provider-kimi` now registers Kimi Coding Anthropic-compatible behavior by default, optional callable Moonshot Open Platform Chat Completions when `includeMoonshotModels` is requested, official Coding/Open Platform featured ids, thinking/`reasoning_effort` compat mapping, and an opt-in `listKimiModels()` helper for Moonshot `GET /v1/models`. `@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. `@arnilo/prism-provider-anthropic` registers native Anthropic Messages (`createAnthropicProviderPackage` / `listAnthropicModels`). `@arnilo/prism-provider-google` registers native Gemini `generateContent` streaming (`createGoogleProviderPackage` / `listGoogleModels`; Vertex identity deferred). Both follow the same zero-setup-network / host-owned credential / provider-owned-header rules; see [`docs/providers/anthropic.md`](providers/anthropic.md) and [`docs/providers/google.md`](providers/google.md). `@arnilo/prism-provider-anthropic` registers native Anthropic Messages (`createAnthropicProviderPackage` / `listAnthropicModels`). `@arnilo/prism-provider-google` registers native Gemini `generateContent` streaming (`createGoogleProviderPackage` / `listGoogleModels`; Vertex identity deferred). Both follow the same zero-setup-network / host-owned credential / provider-owned-header rules; see [`docs/providers/anthropic.md`](providers/anthropic.md) and [`docs/providers/google.md`](providers/google.md).
+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, with optional `models`/`codexModels` overrides and an opt-in `listOpenAIModels()` helper for official `GET /models` discovery. `@arnilo/prism-provider-opencode-go` now registers docs-verified OpenCode Go open coding models with dual OpenAI/Anthropic routes (`compat.route`), official default base `https://opencode.ai/zen/go/v1`, `reasoning_content`/thinking preserve, and an opt-in `listOpenCodeGoModels()` helper for official `GET /zen/go/v1/models`. `@arnilo/prism-provider-openrouter` now registers an app-controlled OpenRouter catalog with routing/`reasoning`/cache passthrough, assistant `reasoning` replay, optional top-level automatic `cache_control`, and an opt-in `listOpenRouterModels()` helper for official `GET /api/v1/models` (setup still never fetches). `@arnilo/prism-provider-zai` now registers featured GLM-5.x/4.x metadata with official `thinking`/`reasoning_effort`/`tool_stream`/`clear_thinking` mapping, Preserved Thinking `reasoning_content` replay, implicit context caching, and an opt-in `listZaiModels()` helper for OpenAI-compatible `GET /models`. `@arnilo/prism-provider-kimi` now registers Kimi Coding Anthropic-compatible behavior by default, optional callable Moonshot Open Platform Chat Completions when `includeMoonshotModels` is requested, official Coding/Open Platform featured ids, thinking/`reasoning_effort` compat mapping, and an opt-in `listKimiModels()` helper for Moonshot `GET /v1/models`. `@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. `@arnilo/prism-provider-anthropic` registers native Anthropic Messages (`createAnthropicProviderPackage` / `listAnthropicModels`). `@arnilo/prism-provider-google` registers native Gemini `generateContent` streaming (`createGoogleProviderPackage` / `listGoogleModels`; Vertex identity stays in the separate package). Both follow the same zero-setup-network / host-owned credential / provider-owned-header rules; see [`docs/providers/anthropic.md`](providers/anthropic.md) and [`docs/providers/google.md`](providers/google.md).
+
+### Phase 10 compatibility matrix
+
+Every package remains explicit, setup-zero-fetch, and late-credential-bound. `ModelConfig.capabilities.input` is authoritative: a listed wire mapping is usable only when the selected model declares that tag; unsupported blocks reject before provider I/O. “Protected” means an operator/release-environment probe, never default CI; its exact key/command boundary is in [Release and install](release-and-install.md#015-protected-live-canary-matrix).
+
+| 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.3 matrix; 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 |
+| Z.AI | OpenAI-compatible; caller-gated list | text, image | tool deltas, `reasoning_content` | implicit; protected API-key smoke |
+| OpenRouter | OpenAI-compatible; host catalog + caller-gated list | text, image | tool deltas, reasoning replay/routing metadata | `cache_control`; protected API-key smoke |
+| OpenCode Go | OpenAI or Anthropic route; caller-gated list | text/image OpenAI route; PDF document/file Anthropic route | tool deltas, route-native thinking | route-specific; protected API-key smoke |
+| Alibaba | DashScope OpenAI-compatible; caller-gated list | text, image | tool deltas, Qwen thinking | implicit / optional markers; protected host probe |
+| Ollama | Cloud/local OpenAI-compatible; caller-gated list | text, image | tool deltas, reasoning effort | implicit only; protected host/daemon probe |
+| NeuralWatt | OpenAI-compatible; caller-gated list | text, image | tool deltas, reasoning and telemetry | implicit; protected API-key smoke |
+| Azure | Azure/Foundry OpenAI-compatible; host models | selected endpoint/model capability | normalized OpenAI-compatible tools | no Prism cache mapping; protected host workload-identity probe |
+| Bedrock | Bedrock OpenAI-compatible; host models | selected endpoint/model capability | normalized OpenAI-compatible tools | no Prism cache mapping; protected host IAM/IRSA probe |
+| Vertex | Vertex OpenAPI-compatible; host models | selected endpoint/model capability | normalized OpenAI-compatible tools | no Prism cache mapping; protected host ADC/WIF probe |
 
 ### First-party cache behavior
 
@@ -93,6 +114,8 @@ Every first-party provider package hardens prompt-cache behavior so it cannot em
 - **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.
+- **Alibaba Cloud** (implicit by default, optional `cache_control`): DashScope implicit prefix caching is automatic; hosts opt in via `ModelConfig.cache.kind: cache_control`, then `cache_control: {"type":"ephemeral"}` markers apply only to selected breakpoints, capped at 4. `prompt_tokens_details.cached_tokens`/`cache_creation_input_tokens` map to cache usage. Caller-gated `listAlibabaModels`.
+- **Ollama** (`kind: implicit`): Ollama KV/prefix caching is automatic with no request knob; sends no explicit cache payload. Ollama reports no cached-token count, so `Usage.cacheReadTokens` stays `undefined`. Caller-gated `listOllamaModels`.
 
 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.
 
@@ -160,7 +183,8 @@ 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-provider-opencode-go`, `@arnilo/prism-provider-alibaba`,
+`@arnilo/prism-provider-ollama`) are **opt-in and individually installable**;
 `@arnilo/prism` core runs without any first-party provider package (mock-only).
 
 A host mixes first-party packages and third-party providers in one resolver.

package/docs/providers/ai-sdk.md

@@ -4,7 +4,15 @@
 
 `@arnilo/prism-provider-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.
 
-Supported specification: `@ai-sdk/provider` **v4** (`specificationVersion: "v4"`). Core `@arnilo/prism` does not depend on the AI SDK.
+Core `@arnilo/prism` does not depend on the AI SDK.
+
+### Supported-version matrix
+
+| `@ai-sdk/provider` | `LanguageModel` ABI | Status |
+| --- | --- | --- |
+| `4.0.3` | `LanguageModelV4`, `specificationVersion: "v4"` | 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.
 
 ## When to use it
 
@@ -19,6 +27,7 @@ import { createAiSdkProvider } from "@arnilo/prism-provider-ai-sdk";
 
 createAiSdkProvider(options: {
   model: LanguageModelV4;
+  redactor?: SecretRedactor;
   id?: string;
 }): AIProvider
 ```
@@ -26,6 +35,7 @@ createAiSdkProvider(options: {
 | Field | Type | Purpose |
 | --- | --- | --- |
 | `model` | `LanguageModelV4` | Host-owned AI SDK language model. |
+| `redactor` | `SecretRedactor` | Optional direct-provider error redactor; agent runs use their active redactor. |
 | `id` | `string` | Prism provider id. Defaults to `ai-sdk:<model.provider>` or `ai-sdk`. |
 
 Mapped request surfaces:
@@ -34,7 +44,7 @@ Mapped request surfaces:
 | --- | --- |
 | `messages` | `LanguageModelV4Prompt` |
 | `tools` | `LanguageModelV4FunctionTool[]` with JSON Schema `inputSchema` |
-| `options.structuredOutput` | `responseFormat: { type: "json", name, schema }` |
+| `options.structuredOutput` | `responseFormat: { type: "json", name, schema }`; `strict` fails explicitly (V4 has no equivalent) |
 | `model.parameters` | `maxOutputTokens`, `temperature`, `topP`, `topK`, penalties, `seed`, `stopSequences` |
 | `request.signal` | `abortSignal` (always wins over adapter options) |
 | `options.headers` | extension headers only; model owns auth |
@@ -45,16 +55,22 @@ Unsupported content fails before `doStream` (for example unresolved `resourceUri
 
 | AI SDK stream part | Prism event |
 | --- | --- |
+| `response-metadata.id` | `message_start.messageId` |
 | `text-delta` | `content_delta` text |
 | `reasoning-delta` | `content_delta` thinking |
 | `tool-input-start` / `tool-input-delta` | `tool_call_delta` |
-| `tool-call` (client-executed) | `tool_call` |
+| `tool-call` | `tool_call`; `providerExecuted` becomes `authority: "provider-hosted"` |
 | `finish` usage | `usage` then `done` |
 | `error` / thrown / abort | redacted `error` |
+| `stream-start`, boundaries, raw diagnostics | intentionally not emitted: no normalized safe payload |
+| provider-executed `tool-result` | remains provider-side; no host result or dispatch |
+| file / reasoning-file / source / custom / approval request | typed `unsupported_mapping` error |
+
+`response-metadata.modelId`/timestamp and opaque `providerMetadata` have no normalized Prism counterpart and are not emitted, preventing provider-private metadata from entering prompt, event, or telemetry paths.
 
 `finish.usage.inputTokens.cacheRead` / `cacheWrite` map to Prism `Usage.cacheReadTokens` / `cacheWriteTokens`. The adapter does not invent cache request fields; prompt caching is owned by the host `LanguageModelV4` and its upstream provider.
 
-Provider-executed tool calls, files/sources/custom parts, warnings, and raw chunks are ignored rather than silently converted into unsupported Prism content.
+No AI SDK stream part is silently coerced into Prism content: the table above maps safe normalized semantics, deliberately withholds provider-private diagnostics/results, and fails unsupported output types explicitly.
 
 ## Request/response example
 
@@ -127,7 +143,7 @@ Official evidence: [Custom providers / LanguageModelV4](https://ai-sdk.dev/provi
 
 ## Extension and configuration notes
 
-- Peer dependency: `@ai-sdk/provider@^4.0.0`. Upgrade policy tracks one specification major at a time.
+- Peer dependency: `@ai-sdk/provider@4.0.3`. 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, through `@arnilo/prism-providers`, or through `@arnilo/prism-all`. 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.
@@ -137,8 +153,8 @@ Official evidence: [Custom providers / LanguageModelV4](https://ai-sdk.dev/provi
 - Host credentials stay inside the supplied AI SDK model. The adapter never reads env keys or credential stores.
 - Abort and resource limits come from Prism `request.signal`; adapter options cannot replace that bound.
 - Stream parts are translated incrementally with no full-response buffering and no duplicate model call.
-- Unsupported content fails closed before model invocation. Errors use Prism `providerError` redaction.
-- Provider metadata/warnings are not emitted as prompt or tool content.
+- Unsupported content and stream parts fail closed before/at mapping; `structuredOutput.strict` is rejected because V4 cannot carry it.
+- Pass `redactor` for direct use; agent runs apply their active redactor. Provider metadata/warnings never become prompt, tool, event, or telemetry content.
 
 ## Related APIs
 

package/docs/providers/alibaba.md

@@ -0,0 +1,179 @@
+# Alibaba Cloud provider package
+
+## What it does
+
+`@arnilo/prism-provider-alibaba` is a side-effect-free adapter for Alibaba Cloud
+Model Studio / DashScope (including the Coding Plan) over the **OpenAI-compatible**
+`POST {base}/chat/completions` endpoint.
+
+- **Dynamic model discovery** — `listAlibabaModels()` calls the OpenAI-compatible
+  `GET {base}/models`. No model catalog is hard-coded in the package: available
+  models vary by region, workspace, and billing plan, so discovery is the source of
+  truth. Package setup never fetches.
+- **Context cache** — DashScope implicit prefix caching is automatic. Explicit
+  caching is opt-in via Anthropic-style `cache_control: {"type":"ephemeral"}`
+  markers (at most 4 per request). Cache hits are accounted from
+  `usage.prompt_tokens_details.cached_tokens` (read) and
+  `cache_creation_input_tokens` (write).
+- **Qwen thinking** — `enable_thinking` passthrough toggles reasoning on Qwen models.
+
+The API key is region/plan-scoped: it must match the base URL's billing plan
+(pay-as-you-go regional, workspace-dedicated, or Coding Plan).
+
+## When to use it
+
+Use it when a host app wants Alibaba Cloud Qwen models (Model Studio / DashScope or
+the Coding Plan) through Prism's `AgentSession` runtime with OpenAI-compatible
+serialization, dynamic model discovery, and explicit/implicit cache accounting.
+
+Do not use it for automatic credential discovery, setup-time catalog fetches, or
+real-network tests (live tests stay opt-in).
+
+## Inputs / request
+
+```ts
+import {
+  createAlibabaProviderPackage,
+  createAlibabaProvider,
+  listAlibabaModels,
+  defineAlibabaModel,
+  alibabaBaseUrl,
+} from "@arnilo/prism-provider-alibaba";
+
+createAlibabaProviderPackage(options: AlibabaProviderPackageOptions): ProviderPackage
+createAlibabaProvider(options?: AlibabaProviderOptions): AIProvider
+listAlibabaModels(options?: ListAlibabaModelsOptions): Promise<ModelConfig[]>
+defineAlibabaModel(config: AlibabaModelConfig): ModelConfig
+alibabaBaseUrl(options?: { baseUrl?: string; preset?: AlibabaBasePreset }): string
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | DashScope API key (`DASHSCOPE_API_KEY`), region/plan-scoped. |
+| `baseUrl` | `string` | Explicit OpenAI-compatible base URL (wins over `preset`). |
+| `preset` | `AlibabaBasePreset` | `"singapore"` (default) / `"beijing"` / `"us"` / `"coding-plan"`. |
+| `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
+| `id` | `string` | Provider id (default `alibaba`). |
+| `models` | `readonly ModelConfig[]` | Host-supplied models (from `listAlibabaModels`) to register. |
+
+Base URLs resolved by preset:
+
+| Preset | Base URL |
+| --- | --- |
+| `singapore` | `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` |
+| `beijing` | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+| `us` | `https://dashscope-us.aliyuncs.com/compatible-mode/v1` |
+| `coding-plan` | `https://coding-intl.dashscope.aliyuncs.com/v1` |
+
+Workspace-dedicated endpoints
+(`https://{workspaceId}.{region}.maas.aliyuncs.com/compatible-mode/v1`) are supplied
+verbatim via `baseUrl`.
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Stream | Prism text deltas, `delta.reasoning_content` → thinking deltas, tool-call delta/final, `usage`, `done`, redacted `error`. |
+| Usage | `prompt_tokens`/`completion_tokens`/`total_tokens`; `prompt_tokens_details.cached_tokens` → `cacheReadTokens`, `cache_creation_input_tokens` → `cacheWriteTokens`. |
+| Discovery | `listAlibabaModels()` maps `GET {base}/models` entries → `ModelConfig` (reasoning/vision inferred from id). |
+| Auth methods | `api_key` for `alibaba`. |
+
+The stream parser emits `done` only on completion evidence (`[DONE]` plus a terminal
+`finish_reason` with no dangling tool calls). Truncated streams terminate with an
+`error` event instead. Unsupported block placements or unclaimed images fail before
+fetch.
+
+## Request/response example
+
+```bash
+curl 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions' \
+  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "qwen-plus",
+    "messages": [{ "role": "user", "content": "Hello" }],
+    "stream": true,
+    "stream_options": { "include_usage": true }
+  }'
+```
+
+Usage in the final streamed chunk:
+
+```json
+{
+  "usage": {
+    "prompt_tokens": 100,
+    "completion_tokens": 5,
+    "total_tokens": 105,
+    "prompt_tokens_details": { "cached_tokens": 80, "cache_creation_input_tokens": 10 }
+  }
+}
+```
+
+## Implementation example
+
+```ts
+import { createExtensionKernel } from "@arnilo/prism";
+import {
+  createAlibabaProviderPackage,
+  listAlibabaModels,
+} from "@arnilo/prism-provider-alibaba";
+
+const kernel = createExtensionKernel();
+
+// Caller-gated discovery — never runs during setup.
+const models = await listAlibabaModels({ apiKey: process.env.DASHSCOPE_API_KEY });
+
+await kernel.load([
+  createAlibabaProviderPackage({
+    apiKey: process.env.DASHSCOPE_API_KEY,
+    preset: "singapore", // or "coding-plan" with a Coding Plan key
+    models,
+  }),
+]);
+```
+
+## Extension and configuration notes
+
+- Hosts choose base URL/preset, provider id, model list, credential source, and
+  `fetch` impl. Nothing is hard-coded; register discovered models via `models:`.
+- Qwen thinking: `compat.enable_thinking` (request wins over model default) maps to
+  the top-level `enable_thinking` wire field; omitted unless explicitly boolean.
+- Provider-owned compat keys (`route`, `enable_thinking`, `alibaba`) are stripped
+  before the opaque `compat` spread so they never leak into wire bodies.
+
+### Cache behavior
+
+- **Implicit** prefix caching is automatic upstream and sends no markers.
+- **Explicit** caching is opt-in: when `ModelConfig.cache.kind === "cache_control"`
+  (or `cache.mode === "on"`) and the caller supplies
+  `ProviderRequestOptions.cache.breakpoints`, `cache_control: {"type":"ephemeral"}`
+  markers land on the last content block of each selected message, capped at
+  `ALIBABA_MAX_CACHE_BREAKPOINTS` (4). Each cached prefix needs ≥1024 tokens and
+  lives ~5 minutes upstream.
+- Usage accounting: `cached_tokens` → `Usage.cacheReadTokens`,
+  `cache_creation_input_tokens` → `Usage.cacheWriteTokens`.
+
+## Security and performance notes
+
+- SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport`
+  helpers (`readSseData`, `readBoundedResponseText`).
+- No network calls during import, setup, build, or default tests.
+- No automatic environment, file, keychain, or shell credential lookup.
+- The API key is resolved per request via `resolveCredentialValue` and sent only as
+  `Authorization: Bearer`; keys are redacted from all thrown errors (including
+  discovery failures). No local filesystem paths enter request payloads.
+- Caller-supplied `ProviderRequest.options.headers` can add non-owned headers, but
+  provider-owned headers (`content-type`, `authorization`) are applied last and
+  cannot be overridden.
+- Model discovery is caller-gated and never invoked in the provider hot path.
+- Live tests stay opt-in; default tests are network-free.
+
+## Related APIs
+
+- [Provider packages](../provider-packages.md): `defineProviderPackage`,
+  caller-gated discovery, OpenAI-compatible routes.
+- [Provider caching](../provider-caching.md): explicit/implicit matrix.
+- [Credentials and redaction](../credentials-and-redaction.md):
+  `resolveCredentialValue`, `redactSecrets`.
+- [Provider conformance](../provider-conformance.md): network-free adapter tests.

package/docs/providers/ollama.md

@@ -0,0 +1,166 @@
+# Ollama Cloud provider package
+
+## What it does
+
+`@arnilo/prism-provider-ollama` is a side-effect-free adapter for Ollama — both
+**Ollama Cloud** (`https://ollama.com`) and a **local** `ollama serve`
+(`http://localhost:11434`) — over the OpenAI-compatible
+`POST {base}/chat/completions` endpoint.
+
+- **Dynamic model discovery** — `listOllamaModels()` calls the OpenAI-compatible
+  `GET {base}/models`. No model catalog is hard-coded: available models vary by cloud
+  account or local pull, so discovery is the source of truth. Package setup never
+  fetches. (The native `GET {base}/api/tags` endpoint is an alternate catalog source;
+  Prism uses the OpenAI-compatible route for a uniform shape.)
+- **Implicit cache only** — Ollama reuses its KV/prompt cache automatically. There is
+  no request knob and no cached-token count in usage, so `Usage.cacheReadTokens` is
+  intentionally left undefined (documented ceiling below).
+- **Reasoning** — `reasoning_effort` passthrough (e.g. gpt-oss models).
+
+Cloud auth is an ollama.com API key sent as `Authorization: Bearer`; local instances
+are typically unauthenticated (omit the key).
+
+## When to use it
+
+Use it when a host app wants Ollama Cloud or local Ollama models through Prism's
+`AgentSession` runtime with OpenAI-compatible serialization and dynamic model
+discovery.
+
+Do not use it for automatic credential discovery, setup-time catalog fetches, explicit
+cache control (Ollama has none), or real-network tests (live tests stay opt-in).
+
+## Inputs / request
+
+```ts
+import {
+  createOllamaProviderPackage,
+  createOllamaProvider,
+  listOllamaModels,
+  defineOllamaModel,
+  ollamaBaseUrl,
+} from "@arnilo/prism-provider-ollama";
+
+createOllamaProviderPackage(options: OllamaProviderPackageOptions): ProviderPackage
+createOllamaProvider(options?: OllamaProviderOptions): AIProvider
+listOllamaModels(options?: ListOllamaModelsOptions): Promise<ModelConfig[]>
+defineOllamaModel(config: OllamaModelConfig): ModelConfig
+ollamaBaseUrl(options?: { baseUrl?: string; preset?: OllamaBasePreset }): string
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | Ollama Cloud API key; omit for unauthenticated local. |
+| `baseUrl` | `string` | Explicit OpenAI-compatible base URL (wins over `preset`). |
+| `preset` | `OllamaBasePreset` | `"cloud"` (default) / `"local"`. |
+| `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
+| `id` | `string` | Provider id (default `ollama`). |
+| `models` | `readonly ModelConfig[]` | Host-supplied models (from `listOllamaModels`) to register. |
+
+Base URLs resolved by preset (each includes the `/v1` segment):
+
+| Preset | Base URL |
+| --- | --- |
+| `cloud` | `https://ollama.com/v1` |
+| `local` | `http://localhost:11434/v1` |
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Stream | Prism text deltas, `delta.reasoning_content` → thinking deltas, tool-call delta/final, `usage`, `done`, redacted `error`. |
+| Usage | `prompt_tokens` → `inputTokens`, `completion_tokens` → `outputTokens` (native `prompt_eval_count`/`eval_count` are the equivalent). `cacheReadTokens` stays undefined. |
+| Discovery | `listOllamaModels()` maps `GET {base}/models` entries → `ModelConfig` (reasoning/vision inferred from id). |
+| Auth methods | `api_key` for `ollama`. |
+
+The stream parser emits `done` only on completion evidence (`[DONE]` plus a terminal
+`finish_reason` with no dangling tool calls). Truncated streams terminate with an
+`error` event instead. Unsupported block placements or unclaimed images fail before
+fetch.
+
+## Request/response example
+
+```bash
+curl 'https://ollama.com/v1/chat/completions' \
+  -H "Authorization: Bearer $OLLAMA_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "gpt-oss:20b",
+    "messages": [{ "role": "user", "content": "Hello" }],
+    "stream": true,
+    "stream_options": { "include_usage": true }
+  }'
+
+curl 'https://ollama.com/v1/models' -H "Authorization: Bearer $OLLAMA_API_KEY"
+```
+
+Usage in the final streamed chunk:
+
+```json
+{ "usage": { "prompt_tokens": 100, "completion_tokens": 5, "total_tokens": 105 } }
+```
+
+## Implementation example
+
+```ts
+import { createExtensionKernel } from "@arnilo/prism";
+import {
+  createOllamaProviderPackage,
+  listOllamaModels,
+} from "@arnilo/prism-provider-ollama";
+
+const kernel = createExtensionKernel();
+
+// Caller-gated discovery — never runs during setup.
+const models = await listOllamaModels({ apiKey: process.env.OLLAMA_API_KEY });
+
+await kernel.load([
+  createOllamaProviderPackage({
+    apiKey: process.env.OLLAMA_API_KEY, // omit for local
+    preset: "cloud", // or "local"
+    models,
+  }),
+]);
+```
+
+## Extension and configuration notes
+
+- Hosts choose base URL/preset, provider id, model list, credential source, and
+  `fetch` impl. Nothing is hard-coded; register discovered models via `models:`.
+- Reasoning: `compat.reasoning_effort` (request wins over model default) maps to the
+  top-level `reasoning_effort` wire field; omitted unless explicitly a string.
+- Provider-owned compat keys (`route`, `reasoning_effort`, `ollama`) are stripped
+  before the opaque `compat` spread so they never leak into wire bodies.
+
+### Cache behavior
+
+- **Implicit only.** Ollama reuses its KV/prompt cache automatically; there is no
+  request knob and no wire marker. Prism never emits `cache_control` for Ollama.
+- **Documented ceiling:** Ollama exposes no cached-token count, so
+  `Usage.cacheReadTokens` is intentionally left `undefined` (not `0`). If a future
+  Ollama release reports cached tokens, map them in `mapOllamaModel`/usage handling.
+
+## Security and performance notes
+
+- SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport`
+  helpers (`readSseData`, `readBoundedResponseText`).
+- No network calls during import, setup, build, or default tests.
+- No automatic environment, file, keychain, or shell credential lookup.
+- The cloud API key is resolved per request via `resolveCredentialValue` and sent only
+  as `Authorization: Bearer`; keys are redacted from all thrown errors (including
+  discovery failures). Local presets send no auth header when no key is configured.
+  No local filesystem paths enter request payloads.
+- Caller-supplied `ProviderRequest.options.headers` can add non-owned headers, but
+  provider-owned headers (`content-type`, `authorization`) are applied last and
+  cannot be overridden.
+- Model discovery is caller-gated and never invoked in the provider hot path.
+- Live tests stay opt-in; default tests are network-free.
+
+## Related APIs
+
+- [Provider packages](../provider-packages.md): `defineProviderPackage`,
+  caller-gated discovery, OpenAI-compatible routes.
+- [Provider caching](../provider-caching.md): explicit/implicit matrix (Ollama =
+  implicit only).
+- [Credentials and redaction](../credentials-and-redaction.md):
+  `resolveCredentialValue`, `redactSecrets`.
+- [Provider conformance](../provider-conformance.md): network-free adapter tests.

package/docs/providers/openai.md

@@ -50,11 +50,13 @@ uses official Responses `reasoning: { effort, summary? }` via
 
 | Surface | Behavior |
 | --- | --- |
-| Provider stream | Prism text, thinking (downgraded to text), `tool_call` deltas/finals, `usage`, `done`, redacted `error` events. |
-| Block preservation | User/system text → `input_text`; assistant text → `output_text`; assistant `tool_call` → top-level `function_call` with `call_id`; `tool_result` → top-level `function_call_output`; images/files/audio when declared on the model. Bare thinking without an encrypted Responses reasoning item is omitted on replay. |
+| Provider stream | Prism text, thinking (downgraded to text), host `tool_call` deltas/finals, provider-hosted `tool_call` events (`authority: "provider-hosted"`), `continuation_required`, `usage`, `done`, and redacted `error` events. |
+| Continuation | An incomplete Responses stream self-resumes at most eight HTTP hops using opaque `previous_response_id`; a cursor is at most 4 KiB, is never replayed, and is observable as `continuation_required`. |
+| Realtime | `createOpenAIRealtimeSession()` exposes server-session creation, audio in/out, transcript deltas, provider-hosted calls, interrupt, and idempotent close through the neutral `RealtimeSession` seam. |
+| Block preservation | User/system text → `input_text`; assistant text → `output_text`; assistant host `tool_call` → top-level `function_call` with `call_id`; provider-hosted calls are not replayed; `tool_result` → top-level `function_call_output`; images/files/audio when declared on the model. Bare thinking without an encrypted Responses reasoning item is omitted on replay. |
 | Auth methods | `api_key` for `openai`; host-invoked subscription `oauth` for `openai-codex`. This is Prism's only first-party subscription OAuth flow in 0.0.12. |
 
-Unsupported block placements or unclaimed images fail before `fetch`.
+Unsupported block placements or unclaimed images fail before `fetch`. Provider-hosted calls are telemetry only: Prism never dispatches them as host tools or sends a `tool_result`.
 
 ## Request/response example
 
@@ -76,6 +78,21 @@ Responses request body (Codex subscription shape, abbreviated):
 }
 ```
 
+Realtime session (OpenAI session creation, abbreviated):
+
+```ts
+import { createOpenAIRealtimeSession } from "@arnilo/prism-provider-openai";
+
+const session = createOpenAIRealtimeSession({
+  model: { provider: "openai", model: "gpt-realtime-2.1" },
+  ownerId: "hashed-host-user-id",
+  apiKey,
+});
+for await (const event of session.events()) {
+  if (event.type === "audio_delta") play(event.audio);
+}
+```
+
 OAuth authorize URL (PKCE, `S256`):
 
 ```
@@ -125,6 +142,7 @@ const challenge = computeS256Challenge(verifier);
   `expires_in`, honors RFC 8628 `authorization_pending` / `slow_down`, and stops
   on terminal errors or expiry. Pass `signal` on `OAuthLoginCallbacks` to abort
   polling promptly.
+- `createOpenAIRealtimeSession` requires a stable host `ownerId`; it sends that value as OpenAI's safety identifier and binds the stream to the server `session.created` id. An injected `webSocket(url, { headers })` factory supports Node 22 hosts whose global WebSocket does not expose header options.
 
 ### Cache behavior
 
@@ -189,6 +207,7 @@ Official: [Reasoning models](https://developers.openai.com/api/docs/guides/reaso
   access/refresh tokens echoed in token-endpoint failures.
 - The PKCE verifier is exchanged at the token endpoint, never sent on the authorize
   URL.
+- Realtime uses the documented WebSocket `Authorization` header, never a credential query parameter. API keys are redacted from transcript/error events; audio/transcript input is untrusted, realtime queues are bounded, and disconnect, abort, malformed session identity, or audio/byte/wall-time cap breach closes the session.
 - Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus fake-safe
   provider-specific env names; default `npm test` is network-free.