@arnilo/prism 0.4.0 → 0.5.1

package/docs/providers/hyper.md

@@ -0,0 +1,296 @@
+# 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
+```
+
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | Responses: `prompt_cache_key`; chat/Anthropic: no session header |
+| Mandatory | no |
+| P2 default cache | Anthropic: `cache_control`; Responses: openai_key rules; chat: implicit |
+
+See [Provider request policies](../provider-request-policies.md).
+
+## 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

@@ -185,6 +185,18 @@ await kernel.load([
 - Coding usage: `cache_read_input_tokens` → `Usage.cacheReadTokens`,
   `cache_creation_input_tokens` → `Usage.cacheWriteTokens`.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none extra |
+| Mandatory | no |
+| P2 default cache | Anthropic/Coding: `cache_control`; Moonshot: none |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport`
@@ -199,6 +211,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

@@ -360,6 +360,18 @@ const decision = classifyNeuralWattError({ status: 429, headers: { "retry-after"
 // { retryable: true, code: 429, retryAfterMs: 1000, errorCode: "concurrent_budget_exceeded", strategy: undefined }
 ```
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none |
+| Mandatory | no |
+| P2 default cache | implicit, no markers |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams, HTTP error bodies, and quota/model-discovery failures use bounded `@arnilo/prism/providers/transport` helpers (`readSseEvents`, `readBoundedResponseText`). NeuralWatt `: energy` / `: cost` comment frames are surfaced via `readSseEvents` `comments` and mapped locally.
@@ -380,6 +392,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

@@ -139,6 +139,18 @@ await kernel.load([
   `Usage.cacheReadTokens` is intentionally left `undefined` (not `0`). If a future
   Ollama release reports cached tokens, map them in `mapOllamaModel`/usage handling.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none |
+| Mandatory | no |
+| P2 default cache | implicit, no markers |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport`
@@ -155,6 +167,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

@@ -139,6 +139,18 @@ const provider = createOpenAICompatibleProvider({
 
 - Cache behavior is intentionally minimal: this Chat Completions adapter sends no `prompt_cache_key`, `prompt_cache_retention`, or `cache_control` fields. Endpoints that cache implicitly do so automatically; hosts needing OpenAI `prompt_cache_key`/`prompt_cache_retention` should use the [`@arnilo/prism-providers/openai`](openai.md) Responses package. The adapter still normalizes cache usage from `prompt_tokens_details.cached_tokens` (and `prompt_cache_hit_tokens`) into `Usage.cacheReadTokens`.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none (factory sends no session/cache wire) |
+| Mandatory | no |
+| P2 default cache | none unless the vendor adapter maps options |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - Credentials are host-owned and resolved only when `generate()` runs.
@@ -150,6 +162,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

@@ -207,6 +207,18 @@ Official: [Reasoning models](https://developers.openai.com/api/docs/guides/reaso
   `response.output_item.added` + `response.function_call_arguments.delta`
   (string `delta`), not Chat Completions object deltas.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | `prompt_cache_key` from `cacheKey??sessionId`; `x-client-request-id` from `sessionId` |
+| Mandatory | no |
+| P2 default cache | GPT-5.6+ `explicitBreakpoints` → `prompt_cache_breakpoint` + `cacheRetention: "short"`; older families none |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport` helpers (`readSseData`, `readBoundedResponseText`).
@@ -223,6 +235,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

@@ -233,6 +233,18 @@ Owned compat keys (`route`, `thinking`, `reasoning`, `reasoning_effort`,
   `Usage.cacheReadTokens`/`cacheWriteTokens`; the Anthropic route maps
   `cache_read_input_tokens`/`cache_creation_input_tokens`.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | `x-opencode-session` from `cacheKey??sessionId` |
+| Mandatory | **yes** — missing id throws `ProviderRequirementError` (`ERR_PRISM_PROVIDER_REQUIREMENT`) before fetch; message has no request body |
+| P2 default cache | Anthropic route: `cache_control` markers; OpenAI route: none |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport` helpers (`readSseData`, `readBoundedResponseText`).
@@ -252,6 +264,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

@@ -174,6 +174,18 @@ for Anthropic/Qwen/Gemini families with cache pricing; otherwise `implicit` when
 cache-read pricing exists), and seeds `compat.reasoning.effort` from
 `reasoning.default_effort` when present.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | `x-session-id` + body `session_id` |
+| Mandatory | no |
+| P2 default cache | kernel defaults → per-message `cache_control` (not top-level automatic) |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport` helpers (`readSseData`, `readBoundedResponseText`).
@@ -189,7 +201,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
 

package/docs/providers/vertex.md

@@ -55,6 +55,18 @@ const provider = createVertexProvider({
 
 `@arnilo/prism-providers/google` remains API-key Gemini (`generativelanguage.googleapis.com`) and must not register Vertex OAuth/ADC. Load this package explicitly for Vertex.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none |
+| Mandatory | no |
+| P2 default cache | host-owned, no Prism cache fields |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - No Google Cloud SDK dependency in the package.
@@ -63,6 +75,22 @@ const provider = createVertexProvider({
 - 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; native Vertex cached-content lifecycle is intentionally unsupported on the OpenAI-compatible route — no cache wire fields are emitted even when the request carries Prism cache hints (use `@arnilo/prism-providers/google`'s `extra.cachedContent` on that package, or manage cache resources host-side).
 - Pair with model-router residency allow-lists on `location`.
 
+## Live probe
+
+Opt-in smoke against Vertex's OpenAI-compatible endpoint. The suite takes a pre-minted bearer token (host ADC/workload identity stays host-owned):
+
+```bash
+PRISM_LIVE_PROVIDER_TESTS=1 GOOGLE_VERTEX_PROJECT=my-project \
+  PRISM_VERTEX_ACCESS_TOKEN=$(gcloud auth print-access-token) \
+  node --test packages/prism-providers/dist/vertex/__tests__/live.test.js
+```
+
+`GOOGLE_VERTEX_LOCATION` (default `us-central1`) and `PRISM_LIVE_VERTEX_MODEL` (default `gemini-2.5-flash`) are optional. Missing project or token → skip.
+
+## Thinking and reasoning
+
+Vertex AI OpenAI-compat chat uses the same sanitized thinking-compat forwarding as Azure: `reasoning_effort` (aliases `effort`/`reasoningEffort`) or a `reasoning` object, snapped to the model's declared levels (Gemini → `low/medium/high`). `reasoning_effort` and `extra_body.google.thinking_config` are mutually exclusive upstream — send one. See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## Related APIs
 
 - [Google Gemini (consumer)](google.md)

package/docs/providers/xai.md

@@ -115,6 +115,18 @@ await kernel.load([
 - Reasoning models replay `reasoning_content` and do not flatten thinking into text.
 - Generate always hits `https://api.x.ai/v1/chat/completions` (same backend for API key and SuperGrok access).
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | `x-grok-conv-id` from `cache.key??cacheKey??sessionId` |
+| Mandatory | no |
+| P2 default cache | implicit; header is the correlation |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - Public client id is documented as not a secret. Device/user/access/refresh codes are redacted.
@@ -123,6 +135,10 @@ await kernel.load([
 - Bounded OAuth and API error bodies. No retry loop. No refresh timer.
 - Live API-key smoke: `PRISM_LIVE_PROVIDER_TESTS=1` + `XAI_API_KEY`. SuperGrok login is operator-only (`PRISM_LIVE_XAI_OAUTH=1`).
 
+## Thinking and reasoning
+
+Reasoning models now send `reasoning_effort` (task-065 change — previously dropped): grok-4.6 declares `low/medium/high/xhigh` (default `high`), grok-4.5 `low/medium/high`, grok-4.3 `none/low/medium/high`. Effort snaps to the declared set (nearest, ties up); `grok-build` declares nothing and passes `reasoning_effort` through verbatim. Reasoning models must still replay `reasoning_content` — Featured Completions flatten nothing. See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## Related APIs
 
 - [Provider packages](../provider-packages.md): OAuth support matrix.

package/docs/providers/zai.md

@@ -139,6 +139,18 @@ await session.prompt("Plan the refactor", {
   and `prompt_tokens_details.cache_write_tokens` → `Usage.cacheWriteTokens` when
   the server reports them.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none |
+| Mandatory | no |
+| P2 default cache | implicit, no markers |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport`
@@ -153,6 +165,10 @@ await session.prompt("Plan the refactor", {
 - Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus `ZAI_API_KEY`;
   default tests are network-free.
 
+## Thinking and reasoning
+
+Z.AI models are family-stamped by id. GLM-5.3/5.3-FLASH: `reasoning_effort` restricted to `low/high/max` (declared; other levels snap, e.g. `medium`→`high`), and thinking can never be disabled — `zaiThinking` forces thinking on and never emits `thinking.type: "disabled"` (upstream rejects it; live-pinned). GLM-5.2: declared `low`–`max`; `none`/`minimal` stop thinking (no effort field), `low`/`medium` snap up to `high`. GLM-4.x and older: `thinking_type` toggle only (`clear_thinking` package-local). See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## Related APIs
 
 - [Provider packages](../provider-packages.md): `defineProviderPackage`,

package/docs/public-contracts.md

@@ -522,4 +522,4 @@ with 0.0.28 (no migration) and the `0.0.17 → 0.1.0` upgrade matrix in
 - `@arnilo/prism/providers/transport`: bounded SSE/event parsing, bounded HTTP error-body reads, and JSON-object tool-argument parsing for provider packages.
 - `@arnilo/prism/providers/openai`: OpenAI Chat Completions message/tool serialization, usage mapping, and indexed message validation helpers.
 
-Phase 10 public helpers include `createStaticSettingsProvider`, `createChainedSettingsProvider`, `createMemoryCredentialStore`, `createChainedCredentialResolver`, `createStaticTrustPolicy`, `assertTrusted`, `createStaticPermissionPolicy`, `assertPermission`, and `createSecretRedactor`. Phase 11 auth/request/prompt helpers include `createExplicitCredentialResolver`, `createEnvCredentialResolver`, `refreshOAuthCredential`, `createProviderRequestPolicyChain`, `createSessionCachePolicy`, `mergeProviderRequestOptions`, `composeSystemPrompt`, and `mergeSystemPromptConfig`; 0.0.16 adds `resolveRedactor(redactor?, secrets?)`, which resolves the active redactor from an explicit redactor plus known secret values (the single survivor of the former per-package copies). They do not read env vars, persist OAuth tokens, create cache stores, discover prompt files, or load packages unless the host supplies that behavior. `@arnilo/prism/testing/provider-conformance` exports network-free provider assertion helpers. Node subpaths `@arnilo/prism/node/settings` and `@arnilo/prism/node/trust` are explicit filesystem/path helpers.
+Phase 10 public helpers include `createStaticSettingsProvider`, `createChainedSettingsProvider`, `createMemoryCredentialStore`, `createChainedCredentialResolver`, `createStaticTrustPolicy`, `assertTrusted`, `createStaticPermissionPolicy`, `assertPermission`, and `createSecretRedactor`. Phase 11 auth/request/prompt helpers include `createExplicitCredentialResolver`, `createEnvCredentialResolver`, `refreshOAuthCredential`, `createProviderRequestPolicyChain`, `createSessionCachePolicy`, `applyDefaultProviderRequestOptions`, `ProviderRequirementError`, `mergeProviderRequestOptions`, `composeSystemPrompt`, and `mergeSystemPromptConfig`; 0.0.16 adds `resolveRedactor(redactor?, secrets?)`, which resolves the active redactor from an explicit redactor plus known secret values (the single survivor of the former per-package copies). They do not read env vars, persist OAuth tokens, create cache stores, discover prompt files, or load packages unless the host supplies that behavior. `@arnilo/prism/testing/provider-conformance` exports network-free provider assertion helpers. Node subpaths `@arnilo/prism/node/settings` and `@arnilo/prism/node/trust` are explicit filesystem/path helpers.