@arnilo/prism 0.0.96 → 0.1.0

package/docs/provider-packages.md

@@ -18,6 +18,19 @@ Use provider packages when a host wants to bundle model metadata, provider adapt
 
 Do not use provider packages as a package manager, credential store, env loader, provider-specific cache implementation, or live integration runner.
 
+### Subscription OAuth support matrix
+
+| Package | 0.0.12 auth registration | Subscription OAuth boundary |
+| --- | --- | --- |
+| `@arnilo/prism-provider-openai` | `api_key` for `openai`; `oauth` for `openai-codex` | Existing host-invoked OpenAI Codex PKCE/device-code flow only. |
+| `@arnilo/prism-provider-anthropic` | `api_key` only | No Claude Code/Claude.ai subscription OAuth, credential-file/setup-token import, or routing. [Anthropic requires product developers to use API keys or supported cloud providers](https://docs.anthropic.com/en/docs/claude-code/legal-and-compliance). |
+| `@arnilo/prism-provider-google` | `api_key` only | No Gemini CLI OAuth or credential/token import. [Gemini CLI prohibits third-party OAuth piggybacking](https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/tos-privacy.md); use Google AI Studio API keys. Vertex/ADC uses separate [`@arnilo/prism-provider-vertex`](providers/vertex.md). |
+| `@arnilo/prism-provider-azure` | host Entra token or Azure resource key | Workload identity via `credential` callback; endpoint host preserved ([docs](providers/azure.md)). |
+| `@arnilo/prism-provider-bedrock` | host IAM/IRSA credentials | SigV4 over OpenAI-compatible Bedrock Runtime; region/PrivateLink preserved ([docs](providers/bedrock.md)). |
+| `@arnilo/prism-provider-vertex` | host ADC / workload token | OpenAPI-compatible Vertex endpoint; separate from consumer Google package ([docs](providers/vertex.md)). |
+
+A future provider-local OAuth package must first have explicit third-party permission and documented authorize/token/refresh flow. Before it registers an OAuth descriptor, it must add bounded request/response, abort, PKCE/state where required, expiry/refresh, secret-redaction, durable-store round-trip, and offline protocol tests. Do not add a generic OAuth framework, CLI credential scanner, automatic refresh timer, or success stub.
+
 ## Inputs / request
 
 ```ts
@@ -67,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.
+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.4 matrix (`4.0.3` also listed); protected host integration |
+| Anthropic | Messages; caller-gated list | text, image, PDF document/file | tool deltas, thinking | `cache_control`; protected API-key smoke |
+| Google | Gemini `generateContent`; caller-gated list | text, image, audio, document/file | complete tool calls, thinking | no Prism cache marker; protected API-key smoke |
+| Kimi | Coding Messages or opt-in Moonshot; caller-gated list | text, image, PDF document/file by route/model | tool deltas, route-native thinking replay | implicit / optional Anthropic markers; protected API-key smoke |
+| 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
 
@@ -80,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.
 
@@ -147,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.
@@ -258,6 +295,8 @@ await kernel.load([pkg]);
 - 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.
+- For allow-list/residency/budget/circuit selection before resolve, use optional `@arnilo/prism-model-router` over `createProviderResolver` — do not fork provider packages for governance.
+- Enterprise cloud adapters (`azure` / `bedrock` / `vertex`) stay separate from consumer Anthropic/Google packages and authenticate only through host credential callbacks.
 
 ## Manifest declarations
 
@@ -281,6 +320,8 @@ Manifest declarations are inert. The host must later resolve them through regist
 
 ## Related APIs
 
+- [Model routing](model-routing.md): optional governance router over `ProviderResolver`.
+- [Azure OpenAI / Foundry](providers/azure.md) / [Amazon Bedrock](providers/bedrock.md) / [Google Vertex AI](providers/vertex.md): enterprise workload-identity packages.
 - [Provider layer](provider-layer.md): provider/model registries and provider events.
 - [Provider conformance](provider-conformance.md): reusable network-free checks for provider adapters.
 - [Contribution registries](contribution-registries.md): registry bundle and extension contribution points.

package/docs/provider-request-policies.md

@@ -104,9 +104,11 @@ Policy output should stay generic: use `ProviderRequestOptions.cache`, `headers`
 - Cache keys must never be credentials.
 - Policy chains are O(number of policies) plus option merge cost.
 - Policies should be pure and synchronous unless the host explicitly accepts async work.
+- Optional `@arnilo/prism-model-router` returns a `ProviderRequestPolicy` that strips `openRouterRouting` unless governance allows it — chain it with other policies.
 
 ## Related APIs
 
+- [Model routing](model-routing.md): governance facade that emits a chainable OpenRouter routing gate policy.
 - [Provider caching](provider-caching.md): structured cache hints and helpers.
 - [Provider packages](provider-packages.md): registering policies from extension packages.
 - [Provider layer](provider-layer.md): provider request flow and `AIProvider.generate()`.

package/docs/providers/ai-sdk.md

@@ -4,7 +4,16 @@
 
 `@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 |
+| `4.0.4` | `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 +28,7 @@ import { createAiSdkProvider } from "@arnilo/prism-provider-ai-sdk";
 
 createAiSdkProvider(options: {
   model: LanguageModelV4;
+  redactor?: SecretRedactor;
   id?: string;
 }): AIProvider
 ```
@@ -26,6 +36,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 +45,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 +56,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 +144,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.4` (matrix also lists `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 +154,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/anthropic.md

@@ -0,0 +1,93 @@
+# Anthropic provider package
+
+## What it does
+
+`@arnilo/prism-provider-anthropic` is the first-party Anthropic Messages provider for Prism (`POST /v1/messages`). Setup is side-effect-free: no network, env scan, or keychain lookup during import/setup. Wire format is package-local (OpenCode Go / Kimi Anthropic routes are pattern-only, not a shared core serializer).
+
+## When to use it
+
+Use for native Claude Messages (tools, `cache_control`, thinking/reasoning, media, usage, abort). Prefer this over the AI SDK escape hatch when Anthropic is a primary coding host.
+
+Do **not** use for OpenCode Go Anthropic *route* hosting (`@arnilo/prism-provider-opencode-go`), automatic credential discovery, Claude Code credential-file/setup-token import, or Claude.ai subscription login/routing. This package is API-key-only.
+
+## Inputs / request
+
+```ts
+import {
+  createAnthropicProviderPackage,
+  createAnthropicMessagesProvider,
+  listAnthropicModels,
+  defineAnthropicModel,
+} from "@arnilo/prism-provider-anthropic";
+
+createAnthropicProviderPackage(options?: AnthropicProviderPackageOptions): ProviderPackage
+createAnthropicMessagesProvider(options?): AIProvider
+listAnthropicModels(options?: ListAnthropicModelsOptions): Promise<ModelConfig[]>
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | Host-owned Anthropic API key (late-bound). |
+| `fetch` | `typeof fetch` | Optional fetch for tests/hosts. |
+| `baseUrl` | `string` | Override default `https://api.anthropic.com`. |
+| `id` | `string` | Provider id (default `anthropic`). |
+| `userAgent` | `string` | Optional User-Agent. |
+| `models` | `readonly ModelConfig[]` | Override featured offline models. |
+
+Featured offline aliases: `claude-opus-4-8`, `claude-sonnet-5`, `claude-haiku-4-5`, `claude-fable-5`. Caller-gated discovery: `listAnthropicModels()` — never during setup.
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Stream | Prism text, thinking deltas, tool-call delta/final, usage (incl. cache read/create when present), `done`, redacted `error`. |
+| Cache | Featured models use `cache.kind: "cache_control"`; markers on selected breakpoints (`long` → `ttl: "1h"`). |
+| Thinking | Model-family aware (`adaptive` vs `enabled`+`budget_tokens`); helpers `anthropicThinking` / `anthropicEffort` / `anthropicPreserveThinking`. |
+| Auth | `api_key` for provider id; provider-owned `content-type`, `x-api-key`, `anthropic-version` win over caller headers. No OAuth descriptor or subscription adapter is registered. |
+
+## Request/response example
+
+```json
+{
+  "model": "claude-sonnet-5",
+  "messages": [{ "role": "user", "content": [{ "type": "text", "text": "Hello" }] }],
+  "stream": true,
+  "max_tokens": 1024
+}
+```
+
+## Implementation example
+
+```ts
+import { createProviderRegistry, createModelRegistry } from "@arnilo/prism";
+import { createAnthropicProviderPackage, listAnthropicModels } from "@arnilo/prism-provider-anthropic";
+
+const api = /* ExtensionAPI or host registries */;
+api.registerProviderPackage(createAnthropicProviderPackage({ apiKey: hostKey }));
+
+// Optional: caller-gated catalog refresh
+const models = await listAnthropicModels({ apiKey: hostKey });
+api.registerProviderPackage(createAnthropicProviderPackage({ apiKey: hostKey, models }));
+```
+
+## Extension and configuration notes
+
+- Register via `defineProviderPackage` / host registries; no package auto-discovery.
+- AI SDK (`@arnilo/prism-provider-ai-sdk`) remains an escape hatch, not the primary Anthropic path.
+- Live smoke: `PRISM_LIVE_PROVIDER_TESTS=1` + `ANTHROPIC_API_KEY`.
+- Anthropic says OAuth is for purchasers' ordinary Claude Code/native-app use; developers building products must use Claude Console API keys or a supported cloud provider and may not offer Claude.ai login or route Free/Pro/Max credentials ([legal and compliance](https://docs.anthropic.com/en/docs/claude-code/legal-and-compliance)). Prism therefore has no Anthropic subscription OAuth API or token-import shortcut.
+
+## Security and performance notes
+
+- No network during import/setup/default tests; credentials host-owned and late-bound.
+- Provider-owned auth headers cannot be overridden by caller headers.
+- Media/SSRF bounds reuse `@arnilo/prism/providers/media` / transport helpers.
+- Offline conformance: `@arnilo/prism/testing/provider-conformance`.
+
+## Related APIs
+
+- [Provider packages](../provider-packages.md): package setup + discovery contract.
+- [Provider caching](../provider-caching.md): `cache_control` breakpoints.
+- [Thinking and reasoning](../thinking-and-reasoning.md): portable thinking helpers.
+- [Provider conformance](../provider-conformance.md): network-free assertions.
+- Package README: [`packages/provider-anthropic/README.md`](../../packages/provider-anthropic/README.md)

package/docs/providers/azure.md

@@ -0,0 +1,74 @@
+# Azure OpenAI / Foundry
+
+## What it does
+
+`@arnilo/prism-provider-azure` registers an Azure OpenAI / Foundry Chat Completions provider that uses host-supplied Entra workload identity (Bearer) or Azure resource keys (`api-key`). Deployment URLs keep the configured endpoint host (custom subdomain, private endpoint, or VNet FQDN).
+
+## When to use it
+
+Use it for enterprise Azure OpenAI / Foundry deployments with Managed Identity or host token providers. Do not fold this into consumer OpenAI packages. Do not embed static keys in fixtures.
+
+## Inputs / request
+
+```ts
+import { createAzureOpenAIProviderPackage } from "@arnilo/prism-provider-azure";
+
+createAzureOpenAIProviderPackage({
+  endpoint: "https://my-resource.openai.azure.com",
+  deployment: "gpt-4o",
+  apiVersion: "2024-10-21",
+  credential: hostEntraToken, // late-bound
+  authStyle: "bearer",
+  models: [{ provider: "azure", model: "gpt-4o" }],
+});
+```
+
+| Field | Meaning |
+| --- | --- |
+| `endpoint` | Absolute https resource URL; host preserved |
+| `deployment` | Deployment name (defaults to `model.model`) |
+| `apiVersion` | Query `api-version` (default `2024-10-21`) |
+| `credential` | `CredentialValueSource` — Entra token or resource key |
+| `authStyle` | `bearer` (default) or `api-key` |
+
+## Outputs / response / events
+
+Reuses `@arnilo/prism/providers/openai-compatible` streaming events (text, tool deltas, usage, done, redacted errors). Missing credentials fail closed before `fetch`.
+
+## Request/response example
+
+```http
+POST https://my-resource.privatelink.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-10-21
+Authorization: Bearer <entra-token>
+```
+
+## Implementation example
+
+```ts
+const provider = createAzureOpenAIProvider({
+  endpoint: process.env.AZURE_OPENAI_ENDPOINT!,
+  deployment: "gpt-4o",
+  credential: () => entra.getToken("https://cognitiveservices.azure.com/.default").then((t) => t.token),
+});
+```
+
+Opt-in live canaries: inject real `fetch` + host credential behind host CI secrets — no secrets in repo.
+
+## Extension and configuration notes
+
+Register via `createExtensionKernel().load([createAzureOpenAIProviderPackage(...)])`. Pair with `@arnilo/prism-model-router` for residency allow-lists on Azure regions/endpoints.
+
+## Security and performance notes
+
+- No credential prefetch at import; resolve per request.
+- Endpoint host is never rewritten to public DNS.
+- Errors redact credential values via shared transport helpers.
+- No Azure SDK dependency.
+
+## Related APIs
+
+- [OpenAI-compatible provider](openai-compatible.md)
+- [Provider packages](../provider-packages.md)
+- [Model routing](../model-routing.md)
+- [Credential storage](../credential-storage.md)
+- Package README: [`@arnilo/prism-provider-azure`](../../packages/provider-azure/README.md)

package/docs/providers/bedrock.md

@@ -0,0 +1,72 @@
+# Amazon Bedrock
+
+## What it does
+
+`@arnilo/prism-provider-bedrock` registers an Amazon Bedrock Runtime OpenAI-compatible Chat Completions provider. Hosts supply IAM/IRSA/assumed-role credentials; the package signs requests with SigV4 (no AWS SDK). Region and optional PrivateLink endpoint URLs are preserved.
+
+## When to use it
+
+Use it for enterprise Bedrock access under workload identity. Do not embed long-lived keys in fixtures. Use model-router residency policy to deny disallowed regions.
+
+## Inputs / request
+
+```ts
+import { createBedrockProviderPackage } from "@arnilo/prism-provider-bedrock";
+
+createBedrockProviderPackage({
+  region: "eu-west-1",
+  // endpoint: "https://vpce-….bedrock-runtime.eu-west-1.vpce.amazonaws.com",
+  credential: () => hostAwsCredentials(),
+  models: [{ provider: "bedrock", model: "anthropic.claude-3-haiku-20240307-v1:0" }],
+});
+```
+
+| Field | Meaning |
+| --- | --- |
+| `region` | AWS region for signing + default endpoint |
+| `endpoint` | Optional https PrivateLink / VPC interface base URL |
+| `credential` | `{ accessKeyId, secretAccessKey, sessionToken? }` or async callback |
+| `signRequest` | Optional host SigV4 override |
+
+Default public base: `https://bedrock-runtime.{region}.amazonaws.com` → `/openai/v1/chat/completions`.
+
+## Outputs / response / events
+
+OpenAI-compatible SSE mapped to Prism provider events. Missing credentials fail closed before network I/O.
+
+## Request/response example
+
+```http
+POST https://bedrock-runtime.eu-west-1.amazonaws.com/openai/v1/chat/completions
+Authorization: AWS4-HMAC-SHA256 Credential=…/eu-west-1/bedrock/aws4_request, …
+X-Amz-Security-Token: …
+```
+
+## Implementation example
+
+```ts
+const provider = createBedrockProvider({
+  region: "us-east-1",
+  credential: async () => fromNodeProviderChain()(),
+});
+```
+
+Live canaries stay opt-in behind host credentials; default tests are network-free.
+
+## Extension and configuration notes
+
+Uses Bedrock’s OpenAI-compatible runtime route (not Converse eventstream). Hosts needing Converse-only models should supply a custom provider or AI SDK bridge.
+
+## Security and performance notes
+
+- No AWS SDK; package-local SigV4 only for `bedrock` service.
+- Private endpoint hosts are not rewritten to public DNS.
+- Credential secrets are redacted from provider errors.
+- No credential prefetch at import.
+
+## Related APIs
+
+- [OpenAI-compatible provider](openai-compatible.md)
+- [Model routing](../model-routing.md)
+- [Provider packages](../provider-packages.md)
+- Package README: [`@arnilo/prism-provider-bedrock`](../../packages/provider-bedrock/README.md)