@arnilo/prism 0.4.0 → 0.5.0

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

@@ -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`,

package/docs/providers/google.md

@@ -80,6 +80,10 @@ api.registerProviderPackage(createGoogleProviderPackage({ apiKey: hostKey, model
 - Media bounds reuse shared provider media helpers; tool args arrive complete per chunk (no partial JSON reconstruction required).
 - Offline conformance: `@arnilo/prism/testing/provider-conformance`.
 
+## Thinking and reasoning
+
+Google models route through the `google` family: the adapter merges `compat.thinkingLevel` and the provider emits `generationConfig.thinkingConfig`. Gemini 3.x models use `thinkingLevel` with declared per-model sets: 3.6/3.5-flash and 3-flash-preview accept `minimal`–`high`; 3.1-pro accepts `low/medium/high` (default `high`); 3-pro accepts `low/high`. Gemini 2.5 models are budget-only (`compat.thinkingBudgetRange`): 2.5-pro `128–32768` (cannot disable), 2.5-flash/flash-lite `0–24576` (`0` disables). `none` on a budget-only model maps to the range minimum (`thinkingBudget: 0` where disabling is supported, `128` where not); non-none levels are dropped on budget-only models. Declared level sets snap via nearest-declared (ties up), so `none`/`minimal` on 3.1-pro snap up to `low`. See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## Related APIs
 
 - [Google Vertex AI](vertex.md): enterprise ADC/workload-identity package (separate from this consumer API-key package).

package/docs/providers/hyper.md

@@ -0,0 +1,284 @@
+# Hyper provider package
+
+## What it does
+
+`@arnilo/prism-providers/hyper` provides explicit, side-effect-free setup for
+[Charm Hyper](https://hyper.charm.land) — a pay-per-use reasoning-model gateway
+billed in Hypercredits (1 HC = $0.05). The package routes by `ModelConfig.compat.route`:
+
+| Route | Endpoint | Official model families |
+| --- | --- | --- |
+| `"openai"` (default) | `POST {baseUrl}/chat/completions` | most models (DeepSeek, Kimi, GLM, Gemma, …) |
+| `"anthropic"` | `POST {baseUrl}/messages` | `qwen3.6-*` (Anthropic-shaped explicit-write cache pricing) |
+| `"responses"` (explicit opt-in) | `POST {baseUrl}/responses` | OpenAI-standard pass-through; hosts bring Responses-shaped model metadata (Codex-style clients) |
+
+Default base URL is the official API root:
+
+```txt
+https://hyper.charm.land/v1
+```
+
+Authentication is `Authorization: Bearer <key>` on every route; the messages
+route additionally sends provider-owned `x-api-key` + `anthropic-version:
+2023-06-01` headers (Claude Code compatibility). API keys start with
+`sk-hyper-`. The responses route reuses the OpenAI package's Responses
+machinery wholesale — body serialization, stream events, usage mapping,
+continuation cursors, and media handling — with Hyper's base URL and auth, so
+its wire behavior matches the OpenAI-standard pass-through Charm documents.
+Errors on that route are labeled `Hyper …` (e.g. `Hyper request failed: 429 …`).
+
+## When to use it
+
+Use it when a host app wants Hyper models through Prism's `AgentSession`
+runtime with dual-route serialization, reasoning-content replay, cache-hint
+breakpoints, and caller-gated model discovery and credit checks.
+
+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 {
+  createHyperProviderPackage,
+  getHyperCredits,
+  listHyperModels,
+} from "@arnilo/prism-providers/hyper";
+
+createHyperProviderPackage(options: HyperProviderPackageOptions): 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://hyper.charm.land/v1`. |
+| `models` | `readonly ModelConfig[]` | Overrides featured `hyperModels` defaults. |
+
+`ProviderRequest.options.cache.breakpoints` select Anthropic-route
+`cache_control` markers as documented below; `options.compat.reasoning_effort`
+selects the per-request reasoning effort (clamped to the model's documented
+`effortLevels`).
+
+## 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 — OpenAI route: `[DONE]` marker plus terminal `finish_reason`; Anthropic route: `message_stop`; Responses route: `response.completed` (or hop-cap/duplicate-cursor failure). Truncated streams end with terminal `error`; partial output never surfaces as `succeeded`. |
+| 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; `cost.usd`/`cost.hypercredits`/`remaining.hypercredits` available via `parseHyperUsageCost(wireUsage)` (NeuralWatt pattern) for hosts that surface cost telemetry. Cost/remaining fields are chat-route only; the responses route is a standard OpenAI pass-through (`input_tokens`/`output_tokens`/`total_tokens` + `input_tokens_details.cached_tokens`/`cache_write_tokens`) mapped by the shared Responses machinery. |
+| Auth method | `api_key` for `hyper`, credential name `apiKey`. |
+
+## Request/response example
+
+```json
+{
+  "Authorization": "Bearer sk-hyper-…",
+  "content-type": "application/json"
+}
+```
+
+Messages route adds provider-owned `x-api-key: <key>` and
+`anthropic-version: 2023-06-01`; Bearer-only authentication is also accepted
+there (Claude Code compatibility). All provider-owned headers are applied after
+caller headers and cannot be overridden.
+
+Chat-route body shape (thinking passthrough + preserved reasoning):
+
+```json
+{
+  "model": "deepseek-v4-pro",
+  "stream": true,
+  "stream_options": { "include_usage": true },
+  "reasoning_effort": "high",
+  "messages": [
+    {
+      "role": "assistant",
+      "tool_calls": [{ "id": "call_1", "type": "function", "function": { "name": "lookup", "arguments": "{}" } }],
+      "reasoning_content": "plan the lookup"
+    }
+  ]
+}
+```
+
+Responses-route body (OpenAI-standard pass-through, shared Responses machinery):
+
+```json
+{
+  "model": "deepseek-v4-pro",
+  "input": [{ "role": "user", "content": [{ "type": "input_text", "text": "hi" }] }],
+  "tools": [{ "type": "function", "name": "lookup", "parameters": {} }],
+  "stream": true,
+  "store": false,
+  "reasoning": { "effort": "high" }
+}
+```
+Cache hints (`options.cacheKey`/`sessionId`) surface as the OpenAI-standard
+`sanitized prompt_cache_key` on this route only; `prompt_cache_retention`/`prompt_cache_options`
+are never emitted for implicit Hyper models (no documented 24h/`explicitBreakpoints` support).
+
+## Implementation example
+
+```ts
+import { createExtensionKernel } from "@arnilo/prism";
+import {
+  createHyperProviderPackage,
+  getHyperCredits,
+  listHyperModels,
+} from "@arnilo/prism-providers/hyper";
+
+const kernel = createExtensionKernel();
+await kernel.load([createHyperProviderPackage({ apiKey: process.env.HYPER_API_KEY })]);
+```
+
+Caller-gated live catalog (never runs during package setup):
+
+```ts
+const models = await listHyperModels({ fetch }); // public endpoint, no auth needed
+await kernel.load([createHyperProviderPackage({ apiKey: process.env.HYPER_API_KEY, models })]);
+```
+
+Optional credit display (hosts poll on their own schedule; never called from
+`generate()`):
+
+```ts
+const { balance } = await getHyperCredits({ apiKey: process.env.HYPER_API_KEY });
+```
+
+## Featured models and routes
+
+Featured `hyperModels` mirrors the official `/v1/models` catalog (31 models,
+2026-07 snapshot), with limits, vision capability, documented `effort_levels`,
+and per-million-token pricing (input/output/cache-hit) captured in metadata.
+Route selection follows the observed pricing shape: models whose live catalog
+entry prices explicit cache writes (cache_create > 0, with hit pricing) are
+Anthropic-route `cache_control`; models with implicit write pricing
+(cache_create = 0, no read charge) stay chat-route `implicit` with the write
+fee recorded in `cost.cacheWrite`.
+
+| Model family | Route | Cache kind |
+| --- | --- | --- |
+| `deepseek-v4-pro`, `deepseek-v4-pro-0813`, `deepseek-v4-flash` | `openai` | `implicit` |
+| `kimi-k3`, `kimi-k2.7`, `kimi-k2.5`, `glm-5.3-flash`, `glm-5.1`, `gemma-4-fast`, `gpt-oss-120b`, `llama-*`, `minimax-m2.7`, `qwen3-coder`, `qwen3-next`, `qwen3.7-*` | `openai` | `implicit` |
+| `qwen3.6-plus`, `qwen3.6-flash` | `anthropic` | `cache_control` (max 4 breakpoints, no `ttl` — undocumented) |
+
+## Model discovery
+
+```txt
+GET https://hyper.charm.land/v1/models
+```
+
+Public endpoint — works without authentication and emits no auth header when no
+key resolves. `listHyperModels({ fetch?, baseUrl?, apiKey?, signal?, headers? })`
+maps each `{ id, context_window, max_output_tokens, capabilities.vision,
+reasoning.effort_levels, pricing{cache_create, cache_hit} }` entry to
+`ModelConfig` (route from pricing shape via `routeForHyperModel`). 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 |
+| OpenAI route body | `reasoning_effort` from model default or `options.compat` (request wins), clamped to the model's documented `effortLevels`; invalid values are dropped |
+| Anthropic route stream | `thinking_delta` → thinking deltas |
+| Anthropic route replay | thinking blocks when `preserveThinking` |
+
+Owned compat keys (`route`, `preserveThinking`, `reasoning_effort`,
+`effortLevels`) are stripped before opaque compat spread so resolved values win.
+
+## Extension and configuration notes
+
+- Hosts choose base URL, model list, credential source, and `fetch` impl.
+- Route selection is explicit via `compat.route` (`"anthropic"` or `"responses"`; default `"openai"`). The responses route is never auto-derived — hosts opt in with Responses-shaped model metadata (Codex-style clients), and featured models stay `openai`/`anthropic`.
+- Package contributes models via the extension `api` and an `api_key` auth method.
+
+### Cache and session behavior
+
+- The chat route sends **no** Anthropic `cache_control` fields; it relies on
+  OpenAI-style implicit caching. Read tokens map from
+  `prompt_tokens_details.cached_tokens` / `cache_write_tokens` /
+  `prompt_cache_hit_tokens` (the shared OpenAI usage mapping covers both field
+  spellings).
+- The Anthropic route applies `cache_control: { type: "ephemeral" }` markers
+  only to the caller-selected `cache.breakpoints` (shared `applyCacheControl()`
+  helper) on the last content block of each selected message — not to every
+  block. 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"`.
+- The responses route carries OpenAI-standard `prompt_cache_key` only when the
+  caller supplies cache hints (`cacheKey`/`sessionId`, sanitized + clamped to
+  64 chars by the shared helper); no `prompt_cache_retention`/`prompt_cache_options`
+  (implicit models, no documented 24h/explicit modes).
+- **No `ttl` is ever emitted**: Hyper does not document `cache_control` TTL
+  values; `cacheRetention: "long"` must not produce a marker Hyper may reject.
+  Re-verify against live behavior before emitting TTLs.
+- 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 (unlike OpenCode Go).
+
+### Live-verified mapping (findings ledger)
+
+The following claims are encoded as operator-gated probes in
+`packages/prism-providers/src/hyper/__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 (`cached_tokens`/`prompt_cache_hit_tokens` → `cacheReadTokens`) | `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 | `reasoning_effort` from the model's documented `effortLevels` is accepted (HTTP 200) | `live_reasoning_effort_is_accepted_on_chat_route` | pending |
+
+Run the gate:
+
+```sh
+PRISM_LIVE_PROVIDER_TESTS=1 HYPER_API_KEY=sk-hyper-... \
+  npm run test --workspace=@arnilo/prism-providers/hyper
+```
+
+## 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 (including discovery and credits failures).
+- `402` (insufficient Hypercredits) surfaces non-retryable `billing_error`;
+  `429` and `5xx` are retryable with `retry-after` surfaced as
+  `retry_after_ms`; `400/401/403/404` are non-retryable.
+- Caller headers cannot override provider-owned headers (`content-type`,
+  `authorization`, and on the messages route `x-api-key`/`anthropic-version`).
+- Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus
+  `HYPER_API_KEY`; default tests are network-free.
+
+## Official evidence
+
+- Hyper API docs: `https://hyper.charm.land/docs/api/{authentication,list-models,openai-chat-completions,openai-responses,anthropic-messages,credits}.html`
+- Hyper model catalog: `https://hyper.charm.land/docs/models.html`, `https://hyper.charm.land/faq`
+- Live `GET https://hyper.charm.land/v1/models` snapshot (2026-07) — pricing/limits in the static catalog
+- Probe ledger above pending operator-gated live run
+- Intelligent-routing re-check (2026-09): roadmap-only, no documented controls — see
+  `../_evidence/phase55-hyper-intelligent-routing.md`
+
+## Thinking and reasoning
+
+Hyper models derive `capabilities.thinkingLevels` from `compat.effortLevels` (the live `/v1/models` `reasoning.effort_levels` list) and stamp `reasoning_effort`. `hyperReasoningEffort` snaps to the declared set instead of dropping out-of-set values (`max`↔`xhigh` on deepseek-v4-flash); undeclared models and opaque values pass through. The Anthropic route emits resolved `output_config.effort` (snapped) instead of leaking raw `reasoning_effort`. 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/kimi.md

@@ -199,6 +199,10 @@ await kernel.load([
 - Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus provider-specific
   env names; default tests are network-free.
 
+## Thinking and reasoning
+
+Kimi models are family-stamped by id: K3 (`kimiThinkingFamily`) routes through `reasoning_effort` with declared levels `low/high/max` — other portable levels snap (`medium`→`high`, `xhigh`→`max`, `none`/`minimal`→`low`); unknown effort strings pass through for forward compatibility. K2.x models route through `thinking_type` (on/off toggle; K2.7-code thinking is always on). Do not send conflicting `thinking` + `reasoning_effort`. See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## Related APIs
 
 - [Provider packages](../provider-packages.md): `defineProviderPackage`,

package/docs/providers/neuralwatt.md

@@ -380,6 +380,10 @@ const decision = classifyNeuralWattError({ status: 429, headers: { "retry-after"
 - Live tests stay opt-in behind `NEURALWATT_API_KEY` (plus `PRISM_LIVE_PROVIDER_TESTS=1`);
   default tests are network-free.
 
+## Thinking and reasoning
+
+NeuralWatt reasoning models declare `low/medium/high/max` and snap `reasoning_effort` to that set; non-reasoning models (`-fast`, gemma) declare nothing. `thinking_token_budget` and `chat_template_kwargs` (`preserve_thinking`/`clear_thinking`) stay package-local. See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## Related APIs
 
 - [Provider packages](../provider-packages.md): `defineProviderPackage`,

package/docs/providers/ollama.md

@@ -155,6 +155,21 @@ 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.
 
+## Live probe
+
+The only credential-free live suite: points at a real Ollama server (local `ollama serve` or Ollama Cloud):
+
+```bash
+PRISM_LIVE_PROVIDER_TESTS=1 OLLAMA_BASE_URL=http://localhost:11434 \
+  node --test packages/prism-providers/dist/ollama/__tests__/live.test.js
+```
+
+A health gate lists served models and probes the first (`PRISM_LIVE_OLLAMA_MODEL` to pin one). No server or no pulled models → skip.
+
+## Thinking and reasoning
+
+Ollama models stamp `reasoning_effort` and snap to declared levels: `gpt-oss*` declares `low/medium/high`; other ids declare nothing and pass effort through verbatim. The native `think` field has a disjoint value set and is never emitted alongside `reasoning_effort`. See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## Related APIs
 
 - [Provider packages](../provider-packages.md): `defineProviderPackage`,

package/docs/providers/openai-compatible.md

@@ -150,6 +150,10 @@ const provider = createOpenAICompatibleProvider({
 - Tests should use injected `fetch` and never make real network calls.
 - Tool-call arguments are accumulated as streamed text, parsed with `parseJsonObjectArguments` when the final tool call is emitted; empty argument text yields `{}`, malformed JSON yields an `error` event.
 
+## Thinking and reasoning
+
+The shared OpenAI-compatible base (`createOpenAICompatibleProvider`) does **not** spread `compat` onto request bodies — packages that want thinking forwarded wire a `buildBodyExtra`/`transformBody` hook (Azure, Vertex, and Bedrock use the shared sanitized forwarder: `reasoning_effort` + aliases or a `reasoning` object, effort snapped to declared levels). Host-owned adapters should do the same or accept the no-op. See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## Related APIs
 
 - [Provider layer](../provider-layer.md): registries, provider events, tool-call helpers, and mock provider.

package/docs/providers/openai.md

@@ -223,6 +223,10 @@ Official: [Reasoning models](https://developers.openai.com/api/docs/guides/reaso
 - Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus fake-safe
   provider-specific env names; default `npm test` is network-free.
 
+## Thinking and reasoning
+
+OpenAI models route through the `openai_reasoning` family: the adapter merges `compat.reasoning.effort` and Responses bodies carry `reasoning.effort`. Declared levels (`capabilities.thinkingLevels`): gpt-5.1 family `none/low/medium/high` (default `none`); gpt-5.2 family `none`–`xhigh` (default `medium`); gpt-5.x/o1/o3/o4 families `minimal`–`high` (default `medium`). Unknown model ids declare nothing and pass through untouched. `resolveOpenAIReasoning` snaps a merged effort to the declared set (nearest by ladder distance, ties up; below-minimum snaps up); an existing `reasoning.summary` is preserved. There is no upstream API to enumerate effort values — the tables are doc-pinned in [the evidence matrix](../_evidence/thinking-coverage-2026-09-05.md). See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## Related APIs
 
 - [Provider packages](../provider-packages.md): `defineProviderPackage`, auth

package/docs/providers/opencode-go.md

@@ -252,6 +252,10 @@ Owned compat keys (`route`, `thinking`, `reasoning`, `reasoning_effort`,
 - [OpenCode Go](https://opencode.ai/docs/go/) — model list, dual endpoints, pricing/usage, `GET /zen/go/v1/models`
 - Pi secondary (ids/limits only): `packages/ai/src/providers/opencode-go.ts`, `opencode-go.models.ts`
 
+## Thinking and reasoning
+
+OpenCode-Go models carry level tables: `kimi-k3`/`deepseek-v4`/`glm-5.3` → `reasoning_effort` (`low/high/max`), `glm-5.2` → `reasoning_effort` (`low`–`max`), `grok-4.6` → `low/medium/high/xhigh`, `grok-4.5` → `low/medium/high`, Kimi-K2.x/MiniMax/Qwen → `thinking_type`; mimo/unknown declare nothing and pass through. The Anthropic route uses the shared serializer with resolved thinking + `output_config.effort` hooks; the OpenAI route snaps effort to declared sets. See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## Related APIs
 
 - [Provider packages](../provider-packages.md): `defineProviderPackage`,

package/docs/providers/openrouter.md

@@ -189,7 +189,11 @@ cache-read pricing exists), and seeds `compat.reasoning.effort` from
   hidden app identity.
 - Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus fake-safe
   provider-specific env names; default tests are network-free.
-- Enterprise hosts that must gate `compat.openRouterRouting` should wrap selection with `@arnilo/prism-model-router` (`allowOpenRouterRouting`); the OpenRouter adapter itself still passthroughs routing when present on the request.
+- Enterprise hosts that must gate `compat.openRouterRouting` should wrap selection with `@arnilo/prism-core/governance/model-router` (`allowOpenRouterRouting`); the OpenRouter adapter itself still passthroughs routing when present on the request.
+
+## Thinking and reasoning
+
+OpenRouter models route through the `openai_reasoning` family with **API-derived** levels: `mapOpenRouterModel` reads the models API `reasoning.supported_efforts` into `capabilities.thinkingLevels` (a `mandatory` model excludes `none`), and `resolveOpenRouterReasoning` snaps a merged effort to that set. Models without reasoning metadata pass effort through verbatim (OpenRouter accepts the full ladder globally). See [Thinking and reasoning](../thinking-and-reasoning.md).
 
 ## Related APIs