@arnilo/prism 0.3.2 → 0.5.0

package/docs/providers/ai-sdk.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@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.
+`@arnilo/prism-providers/ai-sdk` adapts a host-supplied AI SDK `LanguageModelV4` into a Prism `AIProvider`. It maps Prism messages, tools, and structured-output options into `doStream` call options, then translates stream parts into Prism provider events incrementally.
 
 Core `@arnilo/prism` does not depend on the AI SDK.
 
@@ -12,6 +12,7 @@ Core `@arnilo/prism` does not depend on the AI SDK.
 | --- | --- | --- |
 | `4.0.3` | `LanguageModelV4`, `specificationVersion: "v4"` | Supported and offline-tested |
 | `4.0.4` | `LanguageModelV4`, `specificationVersion: "v4"` | Supported and offline-tested |
+| `4.0.10` | `LanguageModelV4`, `specificationVersion: "v4"` | Current peer; supported and offline-tested |
 
 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.
 
@@ -24,7 +25,7 @@ Do not use it as a credential store, model catalog, or high-level `streamText`/`
 ## Inputs / request
 
 ```ts
-import { createAiSdkProvider } from "@arnilo/prism-provider-ai-sdk";
+import { createAiSdkProvider } from "@arnilo/prism-providers/ai-sdk";
 
 createAiSdkProvider(options: {
   model: LanguageModelV4;
@@ -91,7 +92,7 @@ No AI SDK stream part is silently coerced into Prism content: the table above ma
 
 ```ts
 import { createAgent } from "@arnilo/prism";
-import { createAiSdkProvider } from "@arnilo/prism-provider-ai-sdk";
+import { createAiSdkProvider } from "@arnilo/prism-providers/ai-sdk";
 
 const provider = createAiSdkProvider({ model: hostCreatedLanguageModelV4 });
 
@@ -131,7 +132,7 @@ See [Provider caching](../provider-caching.md) for the cross-provider matrix.
 
 ## Thinking and reasoning
 
-Reasoning effort, budgets, and provider-specific thinking controls are **host-model-owned**. Prism does not map `ThinkingLevel` into AI SDK call options (`thinkingFamilyForModel` → `noop`). Hosts configure reasoning on the AI SDK model (for example OpenAI `reasoning.effort` via AI SDK `providerOptions`) and may pass per-turn overrides through `ProviderRequestOptions.compat` / `extra`, which the adapter forwards as `providerOptions.prism`.
+Reasoning effort, budgets, and provider-specific thinking controls are **host-model-owned**. Prism does not map `ThinkingLevel` into AI SDK call options: the deliberate `noop` compat family (stamped `compat.thinkingFamily: "noop"` on AI SDK models, and the `thinkingFamilyForModel` fallback) leaves the request options unchanged. Hosts configure reasoning on the AI SDK model (for example OpenAI `reasoning.effort` via AI SDK `providerOptions`) and may pass per-turn overrides through `ProviderRequestOptions.compat` / `extra`, which the adapter forwards as `providerOptions.prism`.
 
 Stream mapping:
 
@@ -144,8 +145,8 @@ Official evidence: [Custom providers / LanguageModelV4](https://ai-sdk.dev/provi
 
 ## Extension and configuration notes
 
-- 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.
+- Peer dependency: `@ai-sdk/provider@4.0.10` (matrix also lists `4.0.3` and `4.0.4`). Upgrade policy adds a matrix row and offline conformance fixture before accepting any new version.
+- First-party HTTP providers remain independent; this adapter is available directly or through `@arnilo/prism-providers`. Installation does not select a model or invoke AI SDK.
 - `options.compat` / `options.extra` pass through as AI SDK `providerOptions.prism`.
 - Export helpers `toAiSdkCallOptions`, `toAiSdkPrompt`, and `mapAiSdkStream` for tests and custom hosts.
 
@@ -157,6 +158,17 @@ Official evidence: [Custom providers / LanguageModelV4](https://ai-sdk.dev/provi
 - 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.
 
+## Live probe
+
+Runs the adapter over the real `@ai-sdk/openai` provider package (dev dependency) to prove the `LanguageModelV4` mapping on a genuine AI SDK wire:
+
+```bash
+PRISM_LIVE_PROVIDER_TESTS=1 OPENAI_API_KEY=... \
+  node --test packages/prism-providers/dist/ai-sdk/__tests__/live.test.js
+```
+
+`PRISM_LIVE_AISDK_MODEL` overrides the probed model (default `gpt-5.1`). Without a key the suite skips.
+
 ## Related APIs
 
 - [Provider packages](../provider-packages.md)

package/docs/providers/alibaba.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-provider-alibaba` is a side-effect-free adapter for Alibaba Cloud
+`@arnilo/prism-providers/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.
 
@@ -64,7 +64,7 @@ import {
   listAlibabaModels,
   defineAlibabaModel,
   alibabaBaseUrl,
-} from "@arnilo/prism-provider-alibaba";
+} from "@arnilo/prism-providers/alibaba";
 
 createAlibabaProviderPackage(options: AlibabaProviderPackageOptions): ProviderPackage
 createAlibabaProvider(options?: AlibabaProviderOptions): AIProvider
@@ -104,7 +104,7 @@ verbatim via `baseUrl`.
 dependency-free).
 
 ```ts
-import { createAlibabaEmbedder } from "@arnilo/prism-provider-alibaba";
+import { createAlibabaEmbedder } from "@arnilo/prism-providers/alibaba";
 
 const embedder = createAlibabaEmbedder({
   apiKey: process.env.DASHSCOPE_API_KEY,
@@ -157,7 +157,7 @@ reranker. The verified compatible route is workspace-dedicated only:
 (`qwen3-rerank`, ≤500 documents, 4,000 tokens/item; base path `compatible-api/v1`,
 not `compatible-mode/v1`). A future `createAlibabaReranker` over that route is
 demand-gated: implement when a caller supplies a workspace-dedicated `baseUrl` and
-needs rerank (structural `Reranker` shape from `@arnilo/prism-rag`, no new
+needs rerank (structural `Reranker` shape from `@arnilo/prism-memory/rag`, no new
 dependency). Multimodal rerank (`qwen3-vl-rerank`) is native-only and stays out.
 
 ## Outputs / response / events
@@ -208,7 +208,7 @@ import { createExtensionKernel } from "@arnilo/prism";
 import {
   createAlibabaProviderPackage,
   listAlibabaModels,
-} from "@arnilo/prism-provider-alibaba";
+} from "@arnilo/prism-providers/alibaba";
 
 const kernel = createExtensionKernel();
 
@@ -255,7 +255,7 @@ await kernel.load([
   `Authorization: Bearer`; keys are redacted from all thrown errors (including
   discovery failures). No local filesystem paths enter request payloads.
 - Opt-in live probe (never part of `npm test`/CI):
-  `PRISM_LIVE_DASHSCOPE_KEY=… npm run test:live --workspace @arnilo/prism-provider-alibaba`
+  `PRISM_LIVE_DASHSCOPE_KEY=… npm run test:live --workspace @arnilo/prism-providers/alibaba`
   exercises an embeddings round-trip against the real endpoint (model override via
   `PRISM_LIVE_DASHSCOPE_MODEL`); absent env = documented skip, never a failure.
 - Caller-supplied `ProviderRequest.options.headers` can add non-owned headers, but
@@ -264,6 +264,10 @@ await kernel.load([
 - Model discovery is caller-gated and never invoked in the provider hot path.
 - Live tests stay opt-in; default tests are network-free.
 
+## Thinking and reasoning
+
+Qwen hybrid models route through the `thinking_type` family: `none` maps to `enable_thinking: false`, any other declared level to `true` — there are no effort levels upstream, so declared `capabilities.thinkingLevels` for hybrid models are the on/off set (`none`–`max` used as a toggle vocabulary). Thinking-only models (`qwq*`, `*-thinking`) always think and never receive `enable_thinking: false`; `thinking_budget` stays a package-local passthrough. See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## Related APIs
 
 - [Provider packages](../provider-packages.md): `defineProviderPackage`,

package/docs/providers/anthropic.md

@@ -2,13 +2,13 @@
 
 ## 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).
+`@arnilo/prism-providers/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.
+Do **not** use for OpenCode Go Anthropic *route* hosting (`@arnilo/prism-providers/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
 
@@ -18,7 +18,7 @@ import {
   createAnthropicMessagesProvider,
   listAnthropicModels,
   defineAnthropicModel,
-} from "@arnilo/prism-provider-anthropic";
+} from "@arnilo/prism-providers/anthropic";
 
 createAnthropicProviderPackage(options?: AnthropicProviderPackageOptions): ProviderPackage
 createAnthropicMessagesProvider(options?): AIProvider
@@ -60,7 +60,7 @@ Featured offline aliases: `claude-opus-4-8`, `claude-sonnet-5`, `claude-haiku-4-
 
 ```ts
 import { createProviderRegistry, createModelRegistry } from "@arnilo/prism";
-import { createAnthropicProviderPackage, listAnthropicModels } from "@arnilo/prism-provider-anthropic";
+import { createAnthropicProviderPackage, listAnthropicModels } from "@arnilo/prism-providers/anthropic";
 
 const api = /* ExtensionAPI or host registries */;
 api.registerProviderPackage(createAnthropicProviderPackage({ apiKey: hostKey }));
@@ -73,7 +73,7 @@ api.registerProviderPackage(createAnthropicProviderPackage({ apiKey: hostKey, mo
 ## 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.
+- AI SDK (`@arnilo/prism-providers/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.
 
@@ -84,10 +84,14 @@ api.registerProviderPackage(createAnthropicProviderPackage({ apiKey: hostKey, mo
 - Media/SSRF bounds reuse `@arnilo/prism/providers/media` / transport helpers.
 - Offline conformance: `@arnilo/prism/testing/provider-conformance`.
 
+## Thinking and reasoning
+
+Anthropic models route through the `output_config_effort` family: the adapter merges `compat.output_config.effort` (from `applyThinkingLevelForModel`) and the provider emits `output_config: { effort }` on Messages bodies. Declared levels per generation (from `capabilities.thinkingLevels`): Opus 4.8/4.7, Sonnet 5, Fable/Mythos 5, Opus 5 accept `low`–`max` incl. `xhigh`; Mythos Preview, Opus 4.6, Sonnet 4.6 accept `low/medium/high/max`; Opus 4.5 accepts `low/medium/high`; Haiku 4.5 declares `none`–`high` (upstream effort support undocumented — live-probe pending). Undeclared levels snap to the nearest declared level (ladder distance, ties up); values below the minimum snap up. Thinking type: `adaptive` on 4.6+/Sonnet 5/Fable/Mythos (bare `enabled` maps to `adaptive`); legacy 4.5 models get `enabled` plus a `budget_tokens` default of 10000 when absent. See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## 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 README: [`@arnilo/prism-providers` family README](../../packages/prism-providers/README.md)

package/docs/providers/azure.md

@@ -2,7 +2,7 @@
 
 ## 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).
+`@arnilo/prism-providers/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
 
@@ -11,7 +11,7 @@ Use it for enterprise Azure OpenAI / Foundry deployments with Managed Identity o
 ## Inputs / request
 
 ```ts
-import { createAzureOpenAIProviderPackage } from "@arnilo/prism-provider-azure";
+import { createAzureOpenAIProviderPackage } from "@arnilo/prism-providers/azure";
 
 createAzureOpenAIProviderPackage({
   endpoint: "https://my-resource.openai.azure.com",
@@ -56,7 +56,7 @@ Opt-in live canaries: inject real `fetch` + host credential behind host CI secre
 
 ## Extension and configuration notes
 
-Register via `createExtensionKernel().load([createAzureOpenAIProviderPackage(...)])`. Pair with `@arnilo/prism-model-router` for residency allow-lists on Azure regions/endpoints.
+Register via `createExtensionKernel().load([createAzureOpenAIProviderPackage(...)])`. Pair with `@arnilo/prism-core/governance/model-router` for residency allow-lists on Azure regions/endpoints.
 
 ## Security and performance notes
 
@@ -66,10 +66,26 @@ Register via `createExtensionKernel().load([createAzureOpenAIProviderPackage(...
 - No Azure SDK dependency.
 - Conformance-proven (Task 6): package `setup()` performs zero fetch and zero credential resolution; an already-aborted signal fails fast; a truncated SSE stream (no `data: [DONE]`) ends in an `error` event; Azure cache policy stays host-owned, so no cache wire fields (`cache_control`, `prompt_cache_*`) are emitted even when the request carries Prism cache hints — only upstream-reported `prompt_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`.
 
+## Live probe
+
+Opt-in smoke over your real Azure OpenAI resource:
+
+```bash
+PRISM_LIVE_PROVIDER_TESTS=1 AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com \
+  AZURE_OPENAI_API_KEY=... PRISM_LIVE_AZURE_MODEL=<deployment-name> \
+  node --test packages/prism-providers/dist/azure/__tests__/live.test.js
+```
+
+The deployment name is the model knob (`AZURE_OPENAI_DEPLOYMENT` also works). Without any of these variables the suite skips — it never fails.
+
+## Thinking and reasoning
+
+Azure OpenAI deployments use the OpenAI-compatible wire: the provider forwards sanitized thinking compat (`reasoning_effort` with `effort`/`reasoningEffort` aliases, or a `reasoning` object with `effort` + preserved `summary`) via its body builder, snapping effort to the model's declared levels (gpt-5.1 → `none/low/medium/high`, ties up). Unrecognized compat keys are dropped. See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## 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 README: [`@arnilo/prism-providers` family README](../../packages/prism-providers/README.md)

package/docs/providers/bedrock.md

@@ -2,7 +2,7 @@
 
 ## 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.
+`@arnilo/prism-providers/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
 
@@ -11,7 +11,7 @@ Use it for enterprise Bedrock access under workload identity. Do not embed long-
 ## Inputs / request
 
 ```ts
-import { createBedrockProviderPackage } from "@arnilo/prism-provider-bedrock";
+import { createBedrockProviderPackage } from "@arnilo/prism-providers/bedrock";
 
 createBedrockProviderPackage({
   region: "eu-west-1",
@@ -66,9 +66,24 @@ Uses Bedrock’s OpenAI-compatible runtime route (not Converse eventstream). Hos
 - Credential secrets are redacted from provider errors.
 - No credential prefetch at import.
 
+## Live probe
+
+Opt-in smoke over real AWS Bedrock (package-local SigV4, static keys or session token):
+
+```bash
+PRISM_LIVE_PROVIDER_TESTS=1 AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... AWS_REGION=us-east-1 \
+  node --test packages/prism-providers/dist/bedrock/__tests__/live.test.js
+```
+
+`PRISM_LIVE_BEDROCK_MODEL` overrides the probed model (default `us.anthropic.claude-haiku-4-5-20251001-v1:0`). Without credentials the suite skips.
+
+## Thinking and reasoning
+
+Bedrock OpenAI-compat chat expects snake_case `reasoning_effort` (with `effort`/`reasoningEffort` aliases) or a sanitized `reasoning` object. OpenAI-family models on Bedrock snap effort to their declared levels (gpt-5.1 → `none/low/medium/high`); non-OpenAI models pass through untouched. See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## 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)
+- Package README: [`@arnilo/prism-providers` family README](../../packages/prism-providers/README.md)

package/docs/providers/clinepass.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-provider-clinepass` provides explicit, side-effect-free setup for
+`@arnilo/prism-providers/clinepass` provides explicit, side-effect-free setup for
 the ClinePass OpenAI-compatible Chat Completions API at
 `https://api.cline.bot/api/v1`. Requests always stream. Model ids are official
 `cline-pass/…` slugs from a static featured catalog.
@@ -19,7 +19,7 @@ or caller-gated `GET /models` (no documented OpenAI models endpoint).
 ## Inputs / request
 
 ```ts
-import { createClinePassProviderPackage } from "@arnilo/prism-provider-clinepass";
+import { createClinePassProviderPackage } from "@arnilo/prism-providers/clinepass";
 
 createClinePassProviderPackage(options: ClinePassProviderPackageOptions): ProviderPackage
 ```
@@ -74,7 +74,7 @@ Completion budget is `max_completion_tokens` (not `max_tokens`).
 
 ```ts
 import { createExtensionKernel } from "@arnilo/prism";
-import { createClinePassProviderPackage } from "@arnilo/prism-provider-clinepass";
+import { createClinePassProviderPackage } from "@arnilo/prism-providers/clinepass";
 
 const kernel = createExtensionKernel();
 await kernel.load([createClinePassProviderPackage({ apiKey: "fake-cline-key" })]);
@@ -106,6 +106,10 @@ await session.prompt("Plan the refactor", {
 - Provider-owned headers win. One POST per generate. Bounded error bodies.
 - Live tests: `PRISM_LIVE_PROVIDER_TESTS=1` plus `CLINE_API_KEY`.
 
+## Thinking and reasoning
+
+ClinePass routes through `reasoning_effort` with per-model slot maps (`compat.thinkingLevelMap`) as wire authority; declared `capabilities.thinkingLevels` mirror each map's portable slots (e.g. GLM: `none/low/medium/high/xhigh`). Portable `max` never reaches the wire (upstream 500s) — the map sends `high`; unsupported slots omit the field. See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## Related APIs
 
 - [Provider packages](../provider-packages.md)

package/docs/providers/commandcode.md

@@ -0,0 +1,253 @@
+# Command Code provider package
+
+## What it does
+
+`@arnilo/prism-providers/commandcode` provides explicit, side-effect-free setup
+for the [Command Code Provider API](https://commandcode.ai/docs/provider) — an
+aggregator exposing every top commercial and open model through OpenAI- and
+Anthropic-compatible endpoints, billed at cost with deals auto-applied. The
+package dual-routes by `ModelConfig.compat.route`:
+
+| Route | Endpoint | Official model families |
+| --- | --- | --- |
+| `"openai"` (default) | `POST {baseUrl}/chat/completions` | everything except `claude-*` (GPT-5.6, DeepSeek, Kimi, GLM, MiniMax, Qwen, MiMo, Gemini flash, Grok) |
+| `"anthropic"` | `POST {baseUrl}/messages` | `claude-*` tiers (Opus/Sonnet/Fable/Haiku) |
+
+Default base URL is the official Provider API root:
+
+```txt
+https://api.commandcode.ai/provider/v1
+```
+
+Authentication: `Authorization: Bearer <key>` on the chat route,
+`x-api-key` + `anthropic-version: 2023-06-01` on the messages route (Claude
+Code compatibility). The same key authenticates the CLI and the API.
+
+## When to use it
+
+Use it when a host app wants Command Code models through Prism's `AgentSession`
+runtime: dual-route serialization, `cache_control` breakpoints on Claude
+models, implicit caching elsewhere, reasoning replay, caller-gated model
+discovery, and optional zero-data-retention (`zdr: true` → provider-owned
+`x-cmd-zdr: 1`, which routes only through ZDR-capable upstreams).
+
+Do not use it for automatic credential discovery, setup-time catalog fetches,
+or real-network tests (live probes are operator-gated, see below).
+
+## Inputs / request
+
+```ts
+import {
+  createCommandCodeProviderPackage,
+  listCommandCodeModels,
+} from "@arnilo/prism-providers/commandcode";
+
+createCommandCodeProviderPackage(options: CommandCodeProviderPackageOptions): ProviderPackage
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | Direct/callback/resolver API-key source. |
+| `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
+| `baseUrl` | `string` | Overrides official `https://api.commandcode.ai/provider/v1`. |
+| `models` | `readonly ModelConfig[]` | Overrides featured `commandCodeModels` defaults. |
+| `zdr` | `boolean` | Enforce zero data retention (`x-cmd-zdr: 1`). May route to costlier upstreams or fail `422 cmd_zdr_no_providers`. |
+
+`ProviderRequest.options.cache.breakpoints` select messages-route
+`cache_control` markers for Claude models (max 4, no `ttl`).
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Provider stream | Prism text, thinking, tool-call delta/final, `usage`, `done`, redacted `error`. |
+| Stream completion | `done` only on completion evidence — chat route: `[DONE]` marker plus terminal `finish_reason`; messages route: `message_stop`. Truncated streams end with terminal `error`. |
+| OpenAI thinking | `delta.reasoning_content` → thinking deltas; replay via top-level `reasoning_content` when `preserveThinking` (default), never folded into text. |
+| Anthropic thinking | `thinking_delta` → thinking deltas; replay via Anthropic thinking blocks when `preserveThinking`. |
+| Usage | Standard tokens + cache read/write per route; mapped through the shared OpenAI/Anthropic usage mappings. |
+| Auth method | `api_key` for `commandcode`, credential name `apiKey`. |
+
+## Request/response example
+
+```json
+{
+  "authorization": "Bearer cmd_…",
+  "content-type": "application/json"
+}
+```
+
+Messages route instead sends provider-owned `x-api-key: <key>` and
+`anthropic-version: 2023-06-01`. All provider-owned headers are applied after
+caller headers and cannot be overridden.
+
+Chat-route body (thinking passthrough + preserved reasoning):
+
+```json
+{
+  "model": "Qwen/Qwen3.8-Flash",
+  "stream": true,
+  "stream_options": { "include_usage": true },
+  "max_tokens": 512,
+  "messages": [
+    {
+      "role": "assistant",
+      "tool_calls": [{ "id": "call_1", "type": "function", "function": { "name": "lookup", "arguments": "{}" } }],
+      "reasoning_content": "plan the lookup"
+    }
+  ]
+}
+```
+
+## Implementation example
+
+```ts
+import { createExtensionKernel } from "@arnilo/prism";
+import { createCommandCodeProviderPackage } from "@arnilo/prism-providers/commandcode";
+
+const kernel = createExtensionKernel();
+await kernel.load([createCommandCodeProviderPackage({ apiKey: process.env.COMMAND_CODE_API_KEY })]);
+```
+
+Caller-gated live catalog (never runs during package setup):
+
+```ts
+const models = await listCommandCodeModels({ fetch }); // public endpoint, no auth needed
+await kernel.load([createCommandCodeProviderPackage({ apiKey: process.env.COMMAND_CODE_API_KEY, models })]);
+```
+
+## Featured models and routes
+
+Featured `commandCodeModels` is a curated 38-model bootstrap catalog: ids and
+context windows from the live `GET /provider/v1/models` snapshot (2026-09, 67
+ids), USD-per-million-token pricing from the docs table
+(<https://commandcode.ai/docs/resources/pricing-limits>). `compat.pricing_source`
+records caveats: open-source models bill at the **mean per-provider price**;
+DeepSeek rates are **off-peak** (17h/day; peak 2× during 01–04 & 06–10 UTC);
+deals (MiniMax M3 −50%, MiMo −98/99%) are already applied upstream. Custom
+pricing metadata is always stripped before the wire.
+
+| Model family | Route | Cache kind |
+| --- | --- | --- |
+| `claude-opus-5/4-8/4-7`, `claude-sonnet-5/4-6`, `claude-fable-5-1/5`, `claude-haiku-4-5` | `anthropic` | `cache_control` (max 4 breakpoints, no `ttl` — undocumented) |
+| `gpt-5.6-sol/terra/luna` | `openai` | `implicit` (docs cache-write price recorded in `cost.cacheWrite`; explicit-key upgrade gated on live probe — Task 9) |
+| `deepseek/*`, Kimi, GLM, MiniMax, Qwen, MiMo, Gemini flash, Grok | `openai` | `implicit` |
+
+## Model discovery
+
+```txt
+GET https://api.commandcode.ai/provider/v1/models
+```
+
+Public endpoint — works without authentication and emits no auth header when no
+key resolves. `listCommandCodeModels({ fetch?, baseUrl?, apiKey?, signal?,
+headers? })` maps each `{ id, name, context_length }` entry to `ModelConfig`:
+route from id (`claude-*` → anthropic), context window from the endpoint, and
+featured docs metadata (cost/cache kind) applied when the id matches a curated
+entry. The endpoint carries no pricing or capabilities — unknown ids get
+route-derived cache kind and no cost. Discovery is **caller-gated** — setup
+performs zero fetches.
+
+## Thinking / reasoning
+
+| Surface | Behavior |
+| --- | --- |
+| OpenAI route stream | `reasoning_content` → thinking deltas |
+| OpenAI route replay | thinking blocks → top-level `reasoning_content` when `preserveThinking`; never folded into text |
+| Anthropic route stream | `thinking_delta` → thinking deltas |
+| Anthropic route replay | thinking blocks when `preserveThinking` |
+
+Owned compat keys (`route`, `preserveThinking`, `pricing_source`) are stripped
+before opaque compat spread so resolved values win.
+
+## Extension and configuration notes
+
+- Hosts choose base URL, model list, credential source, `fetch` impl, and ZDR.
+- Route selection is explicit via `compat.route` (`"anthropic"` for `claude-*`
+  ids, default `"openai"`). Sending a model to the wrong endpoint 400s.
+- Package contributes models via the extension `api` and an `api_key` auth method.
+
+### Cache and session behavior
+
+- The chat route sends **no** `cache_control` fields; it relies on OpenAI-style
+  implicit caching (upstream provider behavior, passed through). Read tokens
+  map from `prompt_tokens_details.cached_tokens` / `cache_write_tokens` /
+  `prompt_cache_hit_tokens`.
+- The messages route applies `cache_control: { type: "ephemeral" }` markers
+  only to caller-selected `cache.breakpoints` (shared `applyCacheControl()`
+  helper) on the last content block of each selected message. A
+  `system_prompt` breakpoint serializes `system` as marked text blocks (plain
+  string otherwise). Caching is enabled unless disabled
+  (`cacheRetention: "none"` / `cache.mode: "off"`) and the model opts in via
+  `ModelConfig.cache.kind: "cache_control"`.
+- **No `ttl` is ever emitted**: the upstream TTL window is undocumented on the
+  Provider API; `cacheRetention: "long"` must not produce a marker the gateway
+  may reject.
+- Usage accounting per route: chat route maps
+  `prompt_tokens_details.cached_tokens`/`cache_write_tokens` (and
+  `prompt_cache_hit_tokens`); messages route maps
+  `cache_read_input_tokens`/`cache_creation_input_tokens`.
+- Session identity is simple: no session header is emitted (undocumented).
+
+### Live-verified mapping (findings ledger)
+
+The following claims are encoded as operator-gated probes in
+`packages/prism-providers/src/commandcode/__tests__/live.test.ts`. Each probe's
+assertion encodes the documented claim, so a probe failure **is** the finding;
+record the outcome here and adjust the mapping. Status: **pending operator
+run** (no key in CI):
+
+| # | Claim (documented) | Probe | Status |
+| --- | --- | --- | --- |
+| 1 | Warm chat-route replay reports cached tokens (implicit caching passes through) | `live_chat_route_reports_cached_tokens_on_warm_prefix_replay` | pending |
+| 2 | `cache_control` on messages reports `cache_creation_input_tokens` on the creating call | `live_messages_route_cache_control_reports_creation_and_read_tokens` | pending |
+| 3 | Same-prefix warm replay reads the created cache entry (TTL ≥ one request) | same probe (warm leg) | pending |
+| 4 | OpenAI `prompt_cache_key` is accepted and honored for GPT-5.6 (explicit caching) — decides Task 9 | `live_gpt56_prompt_cache_key_passthrough_probe` | pending — Task 9 closed gated: **pass** → upgrade `gpt-5.6-*` to the OpenAI explicit mapping (`promptCacheKey`/`promptCacheOptions`/`applyPromptCacheBreakpoints` via `@arnilo/prism-providers/openai`, verified exported); **fail** (400/ignored/warm replay shows no cached tokens) → verified-negative, keep `implicit`, record here |
+| 5 | OpenAI `reasoning_effort` is accepted (200) on the chat route | `live_reasoning_effort_is_accepted_on_chat_route` | pending |
+| 6 | ZDR requests route (done) or fail `422 cmd_zdr_no_providers` when no ZDR-capable upstream exists | `live_zdr_route_probe_is_opt_in_and_routable` | pending |
+
+Run the gate:
+
+```sh
+PRISM_LIVE_PROVIDER_TESTS=1 COMMAND_CODE_API_KEY=cmd_... \
+  npm run test --workspace=@arnilo/prism-providers/commandcode
+```
+
+## Security and performance notes
+
+- SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport` helpers.
+- No network calls during import, setup, build, or default tests.
+- No automatic environment, file, keychain, or shell credential lookup.
+- API keys are resolved per request from caller-supplied values or resolvers
+  and redacted from errors (upstream error bodies may carry the upstream
+  provider's message — always redacted).
+- `403 upgrade_required` (Go plan — no API access) and
+  `422 cmd_zdr_no_providers` are non-retryable; `429` and `5xx` are retryable
+  with `retry-after` surfaced as `retry_after_ms`; `400/401/422` are
+  non-retryable.
+- Caller headers cannot override provider-owned headers (`content-type`,
+  `authorization` on chat, `x-api-key`/`anthropic-version` on messages,
+  `x-cmd-zdr` when ZDR is opted in).
+- Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus
+  `COMMAND_CODE_API_KEY`; default tests are network-free.
+
+## Official evidence
+
+- Command Code Provider API docs: `https://commandcode.ai/docs/provider`
+- Pricing & limits (per-model USD, deals, off-peak): `https://commandcode.ai/docs/resources/pricing-limits`
+- Live `GET https://api.commandcode.ai/provider/v1/models` snapshot (2026-09) — 67 ids, context windows
+- Probe ledger above pending operator-gated live run; row 4 decides plan 055 Task 9
+  (explicit GPT-5.6 caching upgrade) — see `plans/055-First-Class-Hyper-And-Command-Code-Providers.md`
+
+## Thinking and reasoning
+
+Command Code models carry provenance-commented level tables: `claude-*` → `output_config_effort` (Anthropic-route effort sets mirroring the native Anthropic package), `gpt-5.6*` → `openai_reasoning` (`none`–`xhigh`), `deepseek-v4`/`kimi-k3`/`glm-5.3` → `reasoning_effort` (`low/high/max`), `glm-5.2` → `reasoning_effort` (`low`–`max`), Kimi-K2.x/MiniMax/Qwen → `thinking_type`, gemini-3.x → `noop` (the gateway chat route has no `thinking_level` wire, so no levels are declared), mimo/unknown → passthrough. Effort snaps to declared sets on both routes. See [Thinking and reasoning](../thinking-and-reasoning.md).
+
+## Related APIs
+
+- [Provider packages](../provider-packages.md): `defineProviderPackage`,
+  `ModelConfig`, discovery contract, request/cache policies.
+- [Thinking and reasoning](../thinking-and-reasoning.md): per-turn `ThinkingLevel` → compat families.
+- [Credentials and redaction](../credentials-and-redaction.md):
+  `resolveCredentialValue`, `redactSecrets`.
+- [Provider caching](../provider-caching.md): per-provider cache behavior matrix.
+- [Provider conformance](../provider-conformance.md): network-free adapter tests.

package/docs/providers/deepseek.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-provider-deepseek` provides explicit, side-effect-free setup for the
+`@arnilo/prism-providers/deepseek` provides explicit, side-effect-free setup for the
 DeepSeek Chat Completions API (`POST /chat/completions`) with official thinking
 mode, reasoning-effort mapping, tool-turn `reasoning_content` replay, and
 implicit prefix caching.
@@ -26,7 +26,7 @@ import {
   createDeepSeekProviderPackage,
   defineDeepSeekModel,
   listDeepSeekModels,
-} from "@arnilo/prism-provider-deepseek";
+} from "@arnilo/prism-providers/deepseek";
 
 createDeepSeekProviderPackage(options: DeepSeekProviderPackageOptions): ProviderPackage
 defineDeepSeekModel(config: DeepSeekModelConfig): ModelConfig
@@ -84,7 +84,7 @@ Unsupported media blocks fail before fetch. Text-only input.
 
 ```ts
 import { createExtensionKernel } from "@arnilo/prism";
-import { createDeepSeekProviderPackage, listDeepSeekModels } from "@arnilo/prism-provider-deepseek";
+import { createDeepSeekProviderPackage, listDeepSeekModels } from "@arnilo/prism-providers/deepseek";
 
 const kernel = createExtensionKernel();
 await kernel.load([createDeepSeekProviderPackage({ apiKey: "fake-deepseek-key" })]);
@@ -129,6 +129,10 @@ await session.prompt("Plan the refactor", {
 - One POST per generate. No provider retry loop.
 - Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus `DEEPSEEK_API_KEY`.
 
+## Thinking and reasoning
+
+DeepSeek models declare `low/high/max` and stamp `reasoning_effort`; the wire table maps `medium`/`xhigh`→`high`, `none`/`minimal` stop thinking. `thinking.type: "enabled"/"disabled"` stays available (thinking on by default, `high`); a request-level `reasoning_effort: none` stops thinking only when no explicit `thinking` switch was sent. Tool turns must replay `reasoning_content` or the API returns 400. See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## Related APIs
 
 - [Provider packages](../provider-packages.md): `defineProviderPackage`,