@arnilo/prism 0.3.2 → 0.5.0

package/docs/providers/google.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-provider-google` is the first-party Gemini `generateContent` / `streamGenerateContent` provider for Prism (`POST /v1beta/models/{model}:streamGenerateContent?alt=sse`). Setup is side-effect-free: no network, env scan, or keychain lookup during import/setup. Uses native `fetch` + SSE — no `@google/genai` runtime dependency.
+`@arnilo/prism-providers/google` is the first-party Gemini `generateContent` / `streamGenerateContent` provider for Prism (`POST /v1beta/models/{model}:streamGenerateContent?alt=sse`). Setup is side-effect-free: no network, env scan, or keychain lookup during import/setup. Uses native `fetch` + SSE — no `@google/genai` runtime dependency.
 
 ## When to use it
 
@@ -18,7 +18,7 @@ import {
   createGoogleGenerateContentProvider,
   listGoogleModels,
   defineGoogleModel,
-} from "@arnilo/prism-provider-google";
+} from "@arnilo/prism-providers/google";
 
 createGoogleProviderPackage(options?: GoogleProviderPackageOptions): ProviderPackage
 createGoogleGenerateContentProvider(options?): AIProvider
@@ -57,7 +57,7 @@ Featured offline aliases include `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2
 ## Implementation example
 
 ```ts
-import { createGoogleProviderPackage, listGoogleModels } from "@arnilo/prism-provider-google";
+import { createGoogleProviderPackage, listGoogleModels } from "@arnilo/prism-providers/google";
 
 api.registerProviderPackage(createGoogleProviderPackage({ apiKey: hostKey }));
 
@@ -80,10 +80,14 @@ 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).
 - [Provider packages](../provider-packages.md): package setup + discovery contract.
 - [Thinking and reasoning](../thinking-and-reasoning.md): portable thinking helpers.
 - [Provider conformance](../provider-conformance.md): network-free assertions.
-- Package README: [`packages/provider-google/README.md`](../../packages/provider-google/README.md)
+- Package README: [`@arnilo/prism-providers` family README](../../packages/prism-providers/README.md)

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

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-provider-kimi` provides two distinct, side-effect-free routes:
+`@arnilo/prism-providers/kimi` provides two distinct, side-effect-free routes:
 
 1. **Kimi For Coding** (default) — Anthropic-compatible `POST /messages` on
    `https://api.kimi.com/coding` with `User-Agent: KimiCLI/1.5` (unless overridden).
@@ -33,7 +33,7 @@ import {
   createKimiProviderPackage,
   listKimiModels,
   defineKimiModel,
-} from "@arnilo/prism-provider-kimi";
+} from "@arnilo/prism-providers/kimi";
 
 createKimiProviderPackage(options: KimiProviderPackageOptions): ProviderPackage
 listKimiModels(options?: ListKimiModelsOptions): Promise<ModelConfig[]>
@@ -137,7 +137,7 @@ import { createExtensionKernel } from "@arnilo/prism";
 import {
   createKimiProviderPackage,
   listKimiModels,
-} from "@arnilo/prism-provider-kimi";
+} from "@arnilo/prism-providers/kimi";
 
 const kernel = createExtensionKernel();
 await kernel.load([
@@ -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

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-provider-neuralwatt` provides explicit, side-effect-free setup for the
+`@arnilo/prism-providers/neuralwatt` provides explicit, side-effect-free setup for the
 NeuralWatt OpenAI-compatible Chat Completions provider using Prism's OpenAI-compatible
 route with NeuralWatt-specific reasoning/template escape hatches, SSE comment tolerance,
 and implicit prefix caching.
@@ -34,7 +34,7 @@ import {
   neuralWattEventsWithTelemetry,
   neuralWattModels,
   parseNeuralWattComment,
-} from "@arnilo/prism-provider-neuralwatt";
+} from "@arnilo/prism-providers/neuralwatt";
 
 createNeuralWattProviderPackage(options: NeuralWattProviderPackageOptions): ProviderPackage
 defineNeuralWattModel(config: NeuralWattModelConfig): ModelConfig
@@ -123,7 +123,7 @@ Example request body (OpenAI-compatible Chat Completions shape):
 
 ```ts
 import { createExtensionKernel } from "@arnilo/prism";
-import { createNeuralWattProviderPackage } from "@arnilo/prism-provider-neuralwatt";
+import { createNeuralWattProviderPackage } from "@arnilo/prism-providers/neuralwatt";
 
 const kernel = createExtensionKernel();
 await kernel.load([createNeuralWattProviderPackage({ apiKey: "fake-neuralwatt-key" })]);
@@ -132,7 +132,7 @@ await kernel.load([createNeuralWattProviderPackage({ apiKey: "fake-neuralwatt-ke
 Override the provider id and models:
 
 ```ts
-import { createNeuralWattProviderPackage, defineNeuralWattModel, neuralWattModels } from "@arnilo/prism-provider-neuralwatt";
+import { createNeuralWattProviderPackage, defineNeuralWattModel, neuralWattModels } from "@arnilo/prism-providers/neuralwatt";
 
 await kernel.load([
   createNeuralWattProviderPackage({ id: "neuralwatt", apiKey: "fake", models: neuralWattModels }),
@@ -142,7 +142,7 @@ await kernel.load([
 Explicit catalog discovery:
 
 ```ts
-import { listNeuralWattModels } from "@arnilo/prism-provider-neuralwatt";
+import { listNeuralWattModels } from "@arnilo/prism-providers/neuralwatt";
 
 const models = await listNeuralWattModels({ apiKey: "fake-neuralwatt-key", fetch });
 await kernel.load([createNeuralWattProviderPackage({ apiKey: "fake", models })]);
@@ -154,7 +154,7 @@ setup and `generate()` never call model discovery implicitly.
 Account quota:
 
 ```ts
-import { getNeuralWattQuota } from "@arnilo/prism-provider-neuralwatt";
+import { getNeuralWattQuota } from "@arnilo/prism-providers/neuralwatt";
 
 const quota = await getNeuralWattQuota({ apiKey: "fake-neuralwatt-key", fetch });
 console.log(quota.usage?.current_month?.energy_kwh, quota.balance?.balance_usd);
@@ -322,7 +322,7 @@ optional and tolerated when absent; malformed comments yield no telemetry event
 and never crash the stream.
 
 ```ts
-import { neuralWattEventsWithTelemetry } from "@arnilo/prism-provider-neuralwatt";
+import { neuralWattEventsWithTelemetry } from "@arnilo/prism-providers/neuralwatt";
 
 for await (const event of neuralWattEventsWithTelemetry(response.body)) {
   if (event.type === "neuralwatt:telemetry") {
@@ -354,7 +354,7 @@ provider. Classification is O(1) over status/headers/body and makes no extra
 provider calls.
 
 ```ts
-import { classifyNeuralWattError } from "@arnilo/prism-provider-neuralwatt";
+import { classifyNeuralWattError } from "@arnilo/prism-providers/neuralwatt";
 
 const decision = classifyNeuralWattError({ status: 429, headers: { "retry-after": "1" }, body: { error: { code: "concurrent_budget_exceeded", retry_after: 1 } } });
 // { retryable: true, code: 429, retryAfterMs: 1000, errorCode: "concurrent_budget_exceeded", strategy: undefined }
@@ -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

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-provider-ollama` is a side-effect-free adapter for Ollama — both
+`@arnilo/prism-providers/ollama` is a side-effect-free adapter for Ollama — both
 **Ollama Cloud** (`https://ollama.com`) and a **local** `ollama serve`
 (`http://localhost:11434`) — over the OpenAI-compatible
 `POST {base}/chat/completions` endpoint.
@@ -38,7 +38,7 @@ import {
   listOllamaModels,
   defineOllamaModel,
   ollamaBaseUrl,
-} from "@arnilo/prism-provider-ollama";
+} from "@arnilo/prism-providers/ollama";
 
 createOllamaProviderPackage(options: OllamaProviderPackageOptions): ProviderPackage
 createOllamaProvider(options?: OllamaProviderOptions): AIProvider
@@ -106,7 +106,7 @@ import { createExtensionKernel } from "@arnilo/prism";
 import {
   createOllamaProviderPackage,
   listOllamaModels,
-} from "@arnilo/prism-provider-ollama";
+} from "@arnilo/prism-providers/ollama";
 
 const kernel = createExtensionKernel();
 
@@ -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

@@ -137,7 +137,7 @@ 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-provider-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`.
+- 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`.
 
 ## Security and performance notes
 
@@ -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

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-provider-openai` provides explicit, side-effect-free setup for the OpenAI
+`@arnilo/prism-providers/openai` provides explicit, side-effect-free setup for the OpenAI
 Responses API (`createOpenAIResponsesProvider`) and OpenAI Codex
 subscription Responses (`createOpenAICodexProvider`), plus a Codex OAuth provider
 implementing RFC 7636 PKCE browser/device-code login.
@@ -24,7 +24,7 @@ credential discovery, or real-network tests.
 ## Inputs / request
 
 ```ts
-import { createOpenAIProviderPackage } from "@arnilo/prism-provider-openai";
+import { createOpenAIProviderPackage } from "@arnilo/prism-providers/openai";
 
 createOpenAIProviderPackage(options: OpenAIProviderPackageOptions): ProviderPackage
 ```
@@ -81,7 +81,7 @@ Responses request body (Codex subscription shape, abbreviated):
 Realtime session (OpenAI session creation, abbreviated):
 
 ```ts
-import { createOpenAIRealtimeSession } from "@arnilo/prism-provider-openai";
+import { createOpenAIRealtimeSession } from "@arnilo/prism-providers/openai";
 
 const session = createOpenAIRealtimeSession({
   model: { provider: "openai", model: "gpt-realtime-2.1" },
@@ -103,7 +103,7 @@ https://auth.openai.com/authorize?response_type=code&client_id=...&code_challeng
 
 ```ts
 import { createExtensionKernel, createEnvCredentialResolver } from "@arnilo/prism";
-import { createOpenAIProviderPackage, listOpenAIModels } from "@arnilo/prism-provider-openai";
+import { createOpenAIProviderPackage, listOpenAIModels } from "@arnilo/prism-providers/openai";
 
 const apiKey = createEnvCredentialResolver({ OPENAI_API_KEY: "fake" }, { openai: "OPENAI_API_KEY" });
 const models = await listOpenAIModels({ apiKey }); // caller-gated; never runs during setup
@@ -116,7 +116,7 @@ await kernel.load([
 OAuth login (caller-supplied callbacks, mocked in tests):
 
 ```ts
-import { createOpenAICodexOAuthProvider, createPkceVerifier, computeS256Challenge } from "@arnilo/prism-provider-openai";
+import { createOpenAICodexOAuthProvider, createPkceVerifier, computeS256Challenge } from "@arnilo/prism-providers/openai";
 
 const oauth = createOpenAICodexOAuthProvider({
   redirectUri: "http://localhost:1455/auth/callback",
@@ -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

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-provider-opencode-go` provides explicit, side-effect-free setup for
+`@arnilo/prism-providers/opencode-go` provides explicit, side-effect-free setup for
 [OpenCode Go](https://opencode.ai/docs/go/) — a low-cost subscription gateway for
 open coding models. The package dual-routes by `ModelConfig.compat.route`:
 
@@ -36,7 +36,7 @@ real-network tests.
 import {
   createOpenCodeGoProviderPackage,
   listOpenCodeGoModels,
-} from "@arnilo/prism-provider-opencode-go";
+} from "@arnilo/prism-providers/opencode-go";
 
 createOpenCodeGoProviderPackage(options: OpenCodeGoProviderPackageOptions): ProviderPackage
 ```
@@ -106,7 +106,7 @@ import {
   createOpenCodeGoProviderPackage,
   listOpenCodeGoModels,
   openCodeGoModels,
-} from "@arnilo/prism-provider-opencode-go";
+} from "@arnilo/prism-providers/opencode-go";
 
 const kernel = createExtensionKernel();
 await kernel.load([createOpenCodeGoProviderPackage({ apiKey: process.env.OPENCODE_API_KEY })]);
@@ -154,7 +154,7 @@ credential-gated probe:
 
 ```sh
 PRISM_LIVE_PROVIDER_TESTS=1 OPENCODE_API_KEY=... \
-  npm run test --workspace=@arnilo/prism-provider-opencode-go
+  npm run test --workspace=@arnilo/prism-providers/opencode-go
 ```
 
 `live_json_schema_structured_output_succeeds_<model>` must pass for a model
@@ -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

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-provider-openrouter` provides explicit, side-effect-free setup for the
+`@arnilo/prism-providers/openrouter` provides explicit, side-effect-free setup for the
 OpenRouter API-key provider with **app-controlled** model registration, routing
 passthrough, official `reasoning` controls, and Anthropic-style `cache_control`
 (plus sticky `session_id` routing).
@@ -29,7 +29,7 @@ import {
   createOpenRouterProviderPackage,
   defineOpenRouterModel,
   listOpenRouterModels,
-} from "@arnilo/prism-provider-openrouter";
+} from "@arnilo/prism-providers/openrouter";
 
 createOpenRouterProviderPackage(options: OpenRouterProviderPackageOptions): ProviderPackage
 defineOpenRouterModel(config: OpenRouterModelConfig): ModelConfig
@@ -83,7 +83,7 @@ import {
   createOpenRouterProviderPackage,
   defineOpenRouterModel,
   listOpenRouterModels,
-} from "@arnilo/prism-provider-openrouter";
+} from "@arnilo/prism-providers/openrouter";
 
 // App-controlled registration (default — no fetch):
 const sonnet = defineOpenRouterModel({
@@ -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