@arnilo/prism 0.0.5 → 0.0.7

package/docs/providers/neuralwatt.md

@@ -9,7 +9,7 @@ and implicit prefix caching.
 
 The package registers a provider, default model metadata for the featured NeuralWatt
 aliases (`glm-5.2`, `glm-5.2-fast`, `glm-5.2-short`, `glm-5.2-short-fast`,
-`kimi-k2.6`, `kimi-k2.6-fast`, `kimi-k2.7-code`, `qwen3.5-397b`,
+`gemma-4-31b`, `kimi-k2.6`, `kimi-k2.6-fast`, `kimi-k2.7-code`, `qwen3.5-397b`,
 `qwen3.5-397b-fast`, `qwen3.6-35b`, `qwen3.6-35b-fast`), and an `api_key` auth
 method through `createExtensionKernel().load([...])`.
 
@@ -79,13 +79,15 @@ The endpoint is rate-limited to **1 request per second per customer** (429 with
 from `generate()` or package setup; the caller owns throttling.
 
 NeuralWatt-specific request fields flow through the generic `ProviderRequestOptions.compat`
-/ `extra` escape hatches: `compat.reasoning_effort` (`"low" | "medium" | "high"`),
-`compat.thinking_token_budget`, `compat.chat_template_kwargs` (including `enable_thinking`),
-`compat.preserve_thinking`, `compat.clear_thinking`, and `compat.tool_choice`.
-`preserve_thinking: true` keeps prior assistant reasoning in request history so
-multi-turn reasoning continues with the earlier chain of thought; `clear_thinking:
-true` drops it for the next turn, resetting the chain. `options.extra` spreads after
-`compat` so per-call values and overrides win.
+/ `extra` escape hatches: `compat.reasoning_effort` (OpenAI-style scale; GLM-5.2 defaults
+unset to `max` per official docs), `compat.thinking_token_budget`,
+`compat.chat_template_kwargs` (including `enable_thinking`, `preserve_thinking`, and
+`clear_thinking` per official gateway docs), and `compat.tool_choice`.
+`preserve_thinking` / `clear_thinking` compat flags are routed into `chat_template_kwargs`
+on the wire (not top-level body fields). Prism also uses these flags for client-side
+message serialization: `preserve_thinking: true` keeps prior assistant reasoning in
+request history; `clear_thinking: true` drops it for the next turn. `options.extra` spreads
+after resolved fields so per-call values and overrides win.
 
 ## Outputs / response / events
 
@@ -112,7 +114,7 @@ Example request body (OpenAI-compatible Chat Completions shape):
   "messages": [{ "role": "user", "content": "Hello" }],
   "stream": true,
   "stream_options": { "include_usage": true },
-  "reasoning_effort": "medium",
+  "reasoning_effort": "max",
   "thinking_token_budget": 8192
 }
 ```
@@ -192,6 +194,7 @@ validation. The caller owns throttling/caching — the helper makes one explicit
 | `glm-5.2-fast` | 1024K | Tools, fast/no reasoning |
 | `glm-5.2-short` | 195K | Tools, reasoning |
 | `glm-5.2-short-fast` | 195K | Tools, fast/no reasoning |
+| `gemma-4-31b` | 256K | Tools, vision, JSON mode |
 | `kimi-k2.6` | 256K | Tools, reasoning, vision, JSON mode |
 | `kimi-k2.6-fast` | 256K | Tools, vision, JSON mode, fast/no reasoning |
 | `kimi-k2.7-code` | 256K | Tools, reasoning, vision, JSON mode |
@@ -255,15 +258,18 @@ so multi-turn sessions continue the earlier chain of thought:
 
 - Prior `thinking` content blocks on an assistant message are serialized under a
   `reasoning_content` field on that message (matching the streaming
-  `delta.reasoning_content` field). They are **not** flattened into text `content`, so
+  `delta.reasoning_content` field; the gateway also accepts `reasoning` as an alias).
+  They are **not** flattened into text `content`, so
   the model sees reasoning and answer as distinct.
 - Preservation is gated on `model.capabilities.reasoning === true` **or**
   `compat.preserve_thinking: true`. Non-reasoning models receive no `reasoning_content`
   field and prior `thinking` blocks are dropped — they never leak into text content for
   providers/models that do not support reasoning.
-- `compat.clear_thinking: true` drops prior reasoning for the next turn even on
-  reasoning-capable models, resetting the chain of thought. `clear_thinking` takes
-  precedence over `preserve_thinking`.
+- `compat.preserve_thinking` / `compat.clear_thinking` map into `chat_template_kwargs`
+  on the request body per official NeuralWatt docs (Kimi K2.6 `preserve_thinking`, GLM
+  `clear_thinking: false` for full-history). Prism also uses `clear_thinking: true` to
+  drop prior reasoning client-side even on reasoning-capable models; `clear_thinking`
+  takes precedence over `preserve_thinking`.
 - The provider only echoes caller-provided `thinking` blocks; it never synthesizes new
   reasoning.
 

package/docs/providers/openai.md

@@ -36,16 +36,22 @@ createOpenAIProviderPackage(options: OpenAIProviderPackageOptions): ProviderPack
 | `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
 | `baseUrl` | `string` | Overrides `https://api.openai.com/v1`. |
 | `codexBaseUrl` | `string` | Overrides `https://chatgpt.com/backend-api/codex`. |
+| `models` | `readonly ModelConfig[]` | Optional override for registered OpenAI Responses models (defaults to featured `openAIModels`). |
+| `codexModels` | `readonly ModelConfig[]` | Optional override for registered Codex models (defaults to featured `openAICodexModels`). |
 
 `ProviderRequest.options.sessionId`, `cacheKey`, `cacheRetention`, `headers`,
-`compat`, and `extra` map to request headers/payload fields.
+`compat`, and `extra` map to request headers/payload fields. Per-turn reasoning
+uses official Responses `reasoning: { effort, summary? }` via
+`ModelConfig.compat.reasoning` defaults merged with
+`ProviderRequestOptions.compat.reasoning` (request wins). Prefer
+`applyThinkingLevel(..., "openai_reasoning")` from `@arnilo/prism`.
 
 ## Outputs / response / events
 
 | Surface | Behavior |
 | --- | --- |
 | Provider stream | Prism text, thinking (downgraded to text), `tool_call` deltas/finals, `usage`, `done`, redacted `error` events. |
-| Block preservation | Text, thinking (downgraded), assistant `tool_call` → `function_call` input items, `tool_result` → `function_call_output` input items, images when `capabilities.input` includes `"image"`. |
+| Block preservation | User/system text → `input_text`; assistant text → `output_text`; assistant `tool_call` → top-level `function_call` with `call_id`; `tool_result` → top-level `function_call_output`; images/files/audio when declared on the model. Bare thinking without an encrypted Responses reasoning item is omitted on replay. |
 | Auth methods | `api_key` for `openai`; `oauth` for `openai-codex`. |
 
 Unsupported block placements or unclaimed images fail before `fetch`.
@@ -56,10 +62,17 @@ Responses request body (Codex subscription shape, abbreviated):
 
 ```json
 {
-  "model": "gpt-5-codex",
-  "instructions": "You are a coding agent.",
-  "input": [{ "type": "message", "role": "user", "content": [{ "type": "input_text", "text": "Hello" }] }],
-  "stream": true
+  "model": "gpt-5.1",
+  "input": [
+    { "role": "user", "content": [{ "type": "input_text", "text": "Hello" }] },
+    { "role": "assistant", "content": [{ "type": "output_text", "text": "Calling lookup" }] },
+    { "type": "function_call", "call_id": "call_1", "name": "lookup", "arguments": "{\"q\":\"x\"}" },
+    { "type": "function_call_output", "call_id": "call_1", "output": "{\"ok\":true}" }
+  ],
+  "reasoning": { "effort": "high" },
+  "prompt_cache_key": "session-1",
+  "stream": true,
+  "store": false
 }
 ```
 
@@ -73,13 +86,13 @@ https://auth.openai.com/authorize?response_type=code&client_id=...&code_challeng
 
 ```ts
 import { createExtensionKernel, createEnvCredentialResolver } from "@arnilo/prism";
-import { createOpenAIProviderPackage } from "@arnilo/prism-provider-openai";
+import { createOpenAIProviderPackage, listOpenAIModels } from "@arnilo/prism-provider-openai";
 
+const apiKey = createEnvCredentialResolver({ OPENAI_API_KEY: "fake" }, { openai: "OPENAI_API_KEY" });
+const models = await listOpenAIModels({ apiKey }); // caller-gated; never runs during setup
 const kernel = createExtensionKernel();
 await kernel.load([
-  createOpenAIProviderPackage({
-    apiKey: createEnvCredentialResolver({ OPENAI_API_KEY: "fake" }, { openai: "OPENAI_API_KEY" }),
-  }),
+  createOpenAIProviderPackage({ apiKey, models }),
 ]);
 ```
 
@@ -115,25 +128,55 @@ const challenge = computeS256Challenge(verifier);
 
 ### Cache behavior
 
+Official: [Prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching).
+
 - `prompt_cache_key` is derived from `ProviderRequestOptions.cacheKey` (falling
   back to `sessionId`) and sanitized + clamped to 64 characters via the shared
   `sanitizeCacheKey()` helper. Cache keys are session/customer identifiers only;
   never credentials or raw prompts.
-- `prompt_cache_retention` accepts only `"24h"` on the OpenAI Responses API
+- `prompt_cache_retention` accepts only `"24h"` on pre-GPT-5.6 Responses models
   (extended caching). Prism `cacheRetention: "short"` and `"none"` omit the field
   so default automatic/implicit caching applies and no invalid literal is sent.
   `cacheRetention: "long"` maps to `prompt_cache_retention: "24h"` only when the
   model declares `ModelConfig.cache.longRetention === true`; models without that
-  metadata omit the field. The catalog `gpt-5.1` model declares
+  metadata omit the field. Featured `gpt-5.1` declares
   `cache: { kind: "openai_key", longRetention: true, maxKeyLength: 64 }`.
+- GPT-5.6+ official docs prefer `prompt_cache_options` / explicit breakpoints;
+  `listOpenAIModels` sets `longRetention: false` for those ids so Prism does not
+  emit deprecated `prompt_cache_retention` for them. Breakpoint helpers are not
+  shipped in this package yet — hosts may pass `prompt_cache_options` through
+  `compat` / `extra` when needed.
 - Cache accounting is preserved in normalized `Usage`: OpenAI
   `input_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`. OpenAI
-  Responses does not report a cache-write token field.
+  Responses does not report a cache-write token field on older models.
 - Provider-owned headers (`content-type`, `authorization`, `x-client-request-id`)
   are applied after caller `ProviderRequestOptions.headers` so caller config
   cannot replace credentials, content type, or the session request id; non-owned
   caller headers are kept.
 
+### Model discovery
+
+- `listOpenAIModels({ apiKey, fetch, baseUrl, signal, headers })` calls official
+  [`GET /models`](https://developers.openai.com/api/reference/resources/models/methods/list)
+  and maps sparse `{ id, created, owned_by }` entries to `ModelConfig` with
+  `cache.kind: "openai_key"` and heuristic `longRetention` / `capabilities.reasoning`.
+- `createOpenAIProviderPackage` never calls discovery; pass results via `models:`.
+- Codex subscription models are **not** listed by `api.openai.com` — keep using
+  featured `openAICodexModels` or `codexModels:` override.
+- Static `openAIModels` / `openAICodexModels` are offline bootstrap / featured aliases only.
+
+### Reasoning
+
+Official: [Reasoning models](https://developers.openai.com/api/docs/guides/reasoning).
+
+- Body field is top-level `reasoning: { effort, summary?, mode?, context? }`.
+- Model defaults: `ModelConfig.compat.reasoning`; per-turn override:
+  `ProviderRequestOptions.compat.reasoning` (shallow-merged; request wins).
+- Portable helper: `applyThinkingLevel(options, level, "openai_reasoning")`.
+- Streaming tool args follow official
+  `response.output_item.added` + `response.function_call_arguments.delta`
+  (string `delta`), not Chat Completions object deltas.
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport` helpers (`readSseData`, `readBoundedResponseText`).

package/docs/providers/opencode-go.md

@@ -2,27 +2,41 @@
 
 ## What it does
 
-`@arnilo/prism-provider-opencode-go` provides explicit, side-effect-free setup for the
-OpenCode Go API-key provider using Prism model metadata and
-OpenAI-compatible/Anthropic-compatible routes with `x-opencode-session`
-cache/session headers.
+`@arnilo/prism-provider-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`:
 
-The package registers a provider, default model metadata, and an `api_key` auth
-method through `createExtensionKernel().load([...])`.
+| Route | Endpoint | Official model families |
+| --- | --- | --- |
+| `"openai"` (default) | `POST {baseUrl}/chat/completions` | Grok, GLM, Kimi, MiMo, DeepSeek |
+| `"anthropic"` | `POST {baseUrl}/messages` | MiniMax, Qwen |
+
+Default base URL is the official Go API root:
+
+```txt
+https://opencode.ai/zen/go/v1
+```
+
+Session stickiness uses the sanitized `x-opencode-session` header. Anthropic-route
+models may emit selected `cache_control` breakpoints; OpenAI-route models use
+implicit caching and never receive Anthropic cache fields.
 
 ## When to use it
 
-Use it when a host app wants to run an OpenAI-compatible or Anthropic-compatible
-OpenCode Go endpoint through Prism's `AgentSession` runtime with per-request
-session/cache headers.
+Use it when a host app wants OpenCode Go models through Prism's `AgentSession`
+runtime with dual-route serialization, per-request session headers, and optional
+caller-gated model discovery.
 
-Do not use it for automatic credential discovery, catalog fetches, or
+Do not use it for automatic credential discovery, setup-time catalog fetches, or
 real-network tests.
 
 ## Inputs / request
 
 ```ts
-import { createOpenCodeGoProviderPackage } from "@arnilo/prism-provider-opencode-go";
+import {
+  createOpenCodeGoProviderPackage,
+  listOpenCodeGoModels,
+} from "@arnilo/prism-provider-opencode-go";
 
 createOpenCodeGoProviderPackage(options: OpenCodeGoProviderPackageOptions): ProviderPackage
 ```
@@ -31,57 +45,126 @@ createOpenCodeGoProviderPackage(options: OpenCodeGoProviderPackageOptions): Prov
 | --- | --- | --- |
 | `apiKey` | `CredentialValueSource` | Direct/callback/resolver API-key source. |
 | `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
-| `baseUrl` | `string` | Overrides the OpenCode Go base URL. |
-| `models` | `readonly ModelConfig[]` | Overrides `openCodeGoModels` defaults. |
+| `baseUrl` | `string` | Overrides official `https://opencode.ai/zen/go/v1`. |
+| `models` | `readonly ModelConfig[]` | Overrides featured `openCodeGoModels` defaults. |
 
 `ProviderRequest.options.cacheKey` (falling back to `sessionId`) maps to the
-`x-opencode-session` header; the Anthropic-compatible route accepts
-`cache_control` breakpoints; `cacheRetention` maps to cache retention.
+`x-opencode-session` header. Anthropic-route `cache_control` breakpoints and
+`cacheRetention` map as documented below.
 
 ## Outputs / response / events
 
 | Surface | Behavior |
 | --- | --- |
 | Provider stream | Prism text, thinking, tool-call delta/final, `usage`, `done`, redacted `error`. |
-| Session/cache | `x-opencode-session` and cache headers added before `generate()`. |
+| OpenAI thinking | `delta.reasoning_content` → thinking deltas; replay via `reasoning_content` when `preserveThinking`. |
+| Anthropic thinking | `thinking_delta` → thinking deltas; replay via Anthropic thinking blocks when `preserveThinking`. |
+| Session/cache | `x-opencode-session` + route-specific cache markers. |
 | Auth method | `api_key` for `opencode-go`, credential name `apiKey`. |
 
 ## Request/response example
 
-Example headers added before fetch:
-
 ```json
 {
   "Authorization": "Bearer <resolved-key>",
+  "content-type": "application/json",
   "x-opencode-session": "<ProviderRequest.options.cacheKey ?? sessionId>"
 }
 ```
 
+OpenAI-route body (thinking passthrough + preserved reasoning):
+
+```json
+{
+  "model": "kimi-k3",
+  "stream": true,
+  "stream_options": { "include_usage": true },
+  "reasoning_effort": "high",
+  "messages": [
+    {
+      "role": "assistant",
+      "content": "calling",
+      "tool_calls": [{ "id": "call_1", "type": "function", "function": { "name": "lookup", "arguments": "{\"q\":\"x\"}" } }],
+      "reasoning_content": "plan the lookup"
+    }
+  ]
+}
+```
+
 ## Implementation example
 
 ```ts
 import { createExtensionKernel } from "@arnilo/prism";
-import { createOpenCodeGoProviderPackage } from "@arnilo/prism-provider-opencode-go";
+import {
+  createOpenCodeGoProviderPackage,
+  listOpenCodeGoModels,
+  openCodeGoModels,
+} from "@arnilo/prism-provider-opencode-go";
 
 const kernel = createExtensionKernel();
-await kernel.load([createOpenCodeGoProviderPackage({ apiKey: "fake-opencode-key" })]);
+await kernel.load([createOpenCodeGoProviderPackage({ apiKey: process.env.OPENCODE_API_KEY })]);
 ```
 
-Override model metadata:
+Caller-gated live catalog (never runs during package setup):
 
 ```ts
-import { createOpenCodeGoProviderPackage, openCodeGoModels } from "@arnilo/prism-provider-opencode-go";
+const models = await listOpenCodeGoModels({ apiKey: process.env.OPENCODE_API_KEY });
+await kernel.load([createOpenCodeGoProviderPackage({ apiKey: process.env.OPENCODE_API_KEY, models })]);
+```
+
+Offline bootstrap with featured docs-verified aliases:
 
+```ts
 await kernel.load([
   createOpenCodeGoProviderPackage({ apiKey: "fake", models: openCodeGoModels }),
 ]);
 ```
 
+## Featured models and routes
+
+Featured `openCodeGoModels` mirrors the official Go docs list (open coding models
+only — **not** Zen GPT/Claude ids). Route selection follows the official endpoint
+table; Pi secondary metadata is used only for context/output limits when docs omit them.
+
+| Model ID | Route | Cache kind |
+| --- | --- | --- |
+| `grok-4.5`, `glm-5.2`, `glm-5.1`, `kimi-k3`, `kimi-k2.7-code`, `kimi-k2.6`, `mimo-v2.5`, `mimo-v2.5-pro`, `deepseek-v4-pro`, `deepseek-v4-flash` | `openai` | `implicit` |
+| `minimax-m3`, `minimax-m2.7`, `minimax-m2.5`, `qwen3.7-max`, `qwen3.7-plus`, `qwen3.6-plus` | `anthropic` | `cache_control` |
+
+## Model discovery
+
+Official list endpoint (sparse OpenAI-compatible shape):
+
+```txt
+GET https://opencode.ai/zen/go/v1/models
+```
+
+`listOpenCodeGoModels({ apiKey?, fetch?, baseUrl?, signal?, headers? })` maps each
+`{ id, owned_by }` entry to `ModelConfig` with route/cache heuristics from the docs
+endpoint table. Featured metadata (pricing/limits/thinking defaults) is applied when
+the id matches `openCodeGoModels`. Discovery is **caller-gated** — setup performs
+zero fetches.
+
+## Thinking / reasoning
+
+OpenCode Go does not document gateway-owned thinking fields; Prism forwards
+upstream-compatible compat and preserves prior reasoning for tool-call continuity:
+
+| Surface | Behavior |
+| --- | --- |
+| OpenAI route stream | `reasoning_content` → thinking deltas |
+| OpenAI route replay | thinking blocks → top-level `reasoning_content` when `preserveThinking` (default for reasoning models); never folded into text |
+| OpenAI route body | optional `thinking` / `reasoning_effort` / `reasoning` from model + per-turn `options.compat` (request wins) |
+| Anthropic route stream | `thinking_delta` → thinking deltas |
+| Anthropic route replay | thinking blocks with optional `signature` when `preserveThinking` |
+
+Owned compat keys (`route`, `thinking`, `reasoning`, `reasoning_effort`,
+`preserveThinking`) 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.
-- The serializer is inherited from the OpenAI-compatible route; Anthropic-compatible
-  routes preserve `tool_use`/`tool_result` blocks.
+- Route selection is explicit via `compat.route` (`"anthropic"` or default `"openai"`).
 - Package contributes models via the extension `api` and an `api_key` auth method.
 
 ### Cache and session behavior
@@ -114,19 +197,24 @@ await kernel.load([
 - 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.
+  redacted from errors (including discovery failures).
 - Caller-supplied `ProviderRequest.options.headers` can add non-owned headers, but
   provider-owned headers (`content-type`, `x-opencode-session`, `authorization`)
   are applied last and cannot be overridden by caller headers.
-- Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus fake-safe
-  provider-specific env names; default tests are network-free.
+- Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus `OPENCODE_API_KEY`;
+  default tests are network-free.
+
+## Official evidence
+
+- [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`
 
 ## Related APIs
 
 - [Provider packages](../provider-packages.md): `defineProviderPackage`,
-  `ModelConfig`, request/cache policies.
+  `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`.
-- [OpenAI-compatible provider](openai-compatible.md): underlying Chat Completions
-  adapter.
+- [Provider caching](../provider-caching.md): route-specific OpenCode Go cache matrix.
 - [Provider conformance](../provider-conformance.md): network-free adapter tests.

package/docs/providers/openrouter.md

@@ -3,12 +3,15 @@
 ## What it does
 
 `@arnilo/prism-provider-openrouter` provides explicit, side-effect-free setup for the
-OpenRouter API-key provider with app-controlled model catalog and per-model cache
-policy/routing overrides.
+OpenRouter API-key provider with **app-controlled** model registration, routing
+passthrough, official `reasoning` controls, and Anthropic-style `cache_control`
+(plus sticky `session_id` routing).
 
 The package registers a provider, caller-supplied model metadata, and an
-`api_key` auth method through `createExtensionKernel().load([...])`. Apps control the model catalog instead of
-accepting a fetched or hard-coded one.
+`api_key` auth method through `createExtensionKernel().load([...])`. There is
+**no bundled mega-catalog**. Optional `listOpenRouterModels()` lets hosts fetch
+the live official catalog and pass a filtered subset via `models:` — setup
+itself never fetches.
 
 ## When to use it
 
@@ -16,16 +19,22 @@ Use it when a host app wants OpenRouter routing passthrough, reasoning controls,
 and per-model cache policy through Prism's `AgentSession` runtime, and needs to
 override cache behavior per model rather than accept a single hard-coded policy.
 
-Do not use it for catalog fetches, automatic credential discovery, or
-real-network tests.
+Do not use it for automatic catalog fetch during setup, automatic credential
+discovery, or real-network tests in CI defaults.
 
 ## Inputs / request
 
 ```ts
-import { createOpenRouterProviderPackage, defineOpenRouterModel } from "@arnilo/prism-provider-openrouter";
+import {
+  createOpenRouterProviderPackage,
+  defineOpenRouterModel,
+  listOpenRouterModels,
+} from "@arnilo/prism-provider-openrouter";
 
 createOpenRouterProviderPackage(options: OpenRouterProviderPackageOptions): ProviderPackage
-defineOpenRouterModel(config: OpenRouterModelConfig): OpenRouterModelConfig
+defineOpenRouterModel(config: OpenRouterModelConfig): ModelConfig
+listOpenRouterModels(options?: ListOpenRouterModelsOptions): Promise<ModelConfig[]>
+mapOpenRouterModel(entry: OpenRouterModelEntry): ModelConfig
 ```
 
 | Field | Type | Purpose |
@@ -37,25 +46,32 @@ defineOpenRouterModel(config: OpenRouterModelConfig): OpenRouterModelConfig
 | `appTitle` | `string` | App title for the `X-Title` attribution header. |
 | `models` | `readonly ModelConfig[]` | App-supplied model catalog (no default fetch). |
 
-`OpenRouterModelConfig.compat.openRouterRouting` controls routing order,
-`data_collection`, reasoning, and per-model cache policy overrides.
+`OpenRouterModelConfig.compat.openRouterRouting` controls routing order /
+`data_collection`. `compat.reasoning` carries the official OpenRouter
+`reasoning` object (`effort`, `max_tokens`, `exclude`, …). Per-turn
+`providerOptions.compat.reasoning` merges over model defaults (request wins
+key-by-key). `compat.preserveThinking` replays assistant thinking as body
+`reasoning` for tool-call continuity.
 
 ## Outputs / response / events
 
 | Surface | Behavior |
 | --- | --- |
-| Provider stream | Prism text, thinking, tool-call delta/final, `usage` (with cache read/write mapped), `done`, redacted `error`. |
+| Provider stream | Prism text, thinking (`delta.reasoning` / `reasoning_content`), tool-call delta/final, `usage` (with cache read/write mapped), `done`, redacted `error`. |
 | Attribution | `HTTP-Referer`/`X-Title` headers sent only when `appUrl`/`appTitle` are supplied. |
 | Auth method | `api_key` for `openrouter`, credential name `apiKey`. |
 
 ## Request/response example
 
-Per-model routing override:
+Per-model routing + reasoning override:
 
 ```json
 {
   "model": "anthropic/claude-sonnet-4",
-  "routing": { "order": ["anthropic"], "data_collection": "deny" }
+  "provider": { "order": ["anthropic"], "data_collection": "deny" },
+  "reasoning": { "effort": "high" },
+  "session_id": "session-with-spaces",
+  "cache_control": { "type": "ephemeral" }
 }
 ```
 
@@ -63,58 +79,107 @@ Per-model routing override:
 
 ```ts
 import { createExtensionKernel } from "@arnilo/prism";
-import { createOpenRouterProviderPackage, defineOpenRouterModel } from "@arnilo/prism-provider-openrouter";
+import {
+  createOpenRouterProviderPackage,
+  defineOpenRouterModel,
+  listOpenRouterModels,
+} from "@arnilo/prism-provider-openrouter";
 
+// App-controlled registration (default — no fetch):
 const sonnet = defineOpenRouterModel({
   model: "anthropic/claude-sonnet-4",
-  compat: { openRouterRouting: { order: ["anthropic"], data_collection: "deny" } },
+  compat: {
+    openRouterRouting: { order: ["anthropic"], data_collection: "deny" },
+    openRouterCache: true,
+    reasoning: { effort: "medium" },
+  },
 });
 
+// Optional live discovery — caller-gated, never run by setup:
+const live = await listOpenRouterModels({ apiKey: process.env.OPENROUTER_API_KEY });
+const filtered = live.filter((m) => m.model.startsWith("anthropic/"));
+
 const kernel = createExtensionKernel();
 await kernel.load([
-  createOpenRouterProviderPackage({ apiKey: "fake-openrouter-key", models: [sonnet] }),
+  createOpenRouterProviderPackage({
+    apiKey: process.env.OPENROUTER_API_KEY,
+    models: filtered.length ? filtered : [sonnet],
+  }),
 ]);
 ```
 
 ## Extension and configuration notes
 
 - Apps supply the model catalog via `models`; no catalog is fetched during setup.
+- `listOpenRouterModels()` is the official `GET https://openrouter.ai/api/v1/models`
+  helper (auth optional for the public catalog). Map pricing/context/modalities/
+  reasoning metadata into `ModelConfig`; hosts still decide what to register.
 - `defineOpenRouterModel` lets apps override cache policy and routing per model.
 - Hosts choose base URL, attribution, credential source, and `fetch` impl.
 - Package contributes models and an `api_key` auth method.
 
+### Reasoning
+
+- Body field is the official OpenRouter `reasoning` object
+  (`effort`: `max`/`xhigh`/`high`/`medium`/`low`/`minimal`/`none`, plus
+  `max_tokens`, `exclude`, `enabled`, `context`, `mode` as documented).
+- Model `compat.reasoning` defaults merge with per-turn `options.compat.reasoning`
+  (request keys win). Task 4 `applyThinkingLevel(..., "openai_reasoning")` writes
+  `{ reasoning: { effort } }` into that path.
+- Owned compat keys (`reasoning`, `openRouterRouting`, `openRouterCache`,
+  `preserveThinking`) are stripped from opaque compat spreads so resolved values
+  cannot be overwritten accidentally.
+- When `preserveThinking` is enabled (default for reasoning-capable models),
+  assistant `thinking` blocks replay as top-level `reasoning` — not folded into
+  text — matching OpenRouter's tool-call continuity guidance.
+
 ### Cache and session behavior
 
 - `session_id` (request body) and the `X-Session-Id` header are derived from
   `ProviderRequestOptions.cacheKey` (falling back to `sessionId`) and sanitized
   + clamped to 256 characters via the shared `sanitizeCacheKey()` helper.
-  Session ids route requests and identify conversations; never credentials or
-  raw prompts.
-- Anthropic-style `cache_control: { type: "ephemeral" }` markers are applied only
-  to the Prism `PromptCacheBreakpoint` locations the caller selects via
-  `ProviderRequestOptions.cache.breakpoints` (resolved with the shared
-  `applyCacheControl()` helper), and only on the last content block of each
-  selected message — not to every content block of every message. With no
-  breakpoints, no markers are emitted and the provider relies on implicit prefix
-  caching where available.
+  OpenRouter uses this for provider sticky routing to maximize cache hits.
+- **Automatic caching** (no breakpoints): when caching is enabled for an
+  explicit `cache_control` model (or `compat.openRouterCache` /
+  `cache.mode: "on"`), Prism emits a top-level
+  `cache_control: { type: "ephemeral" }` per OpenRouter's Anthropic automatic
+  caching docs. Note: top-level `cache_control` can exclude some backends
+  (e.g. Bedrock/Vertex) from routing.
+- **Explicit breakpoints**: Anthropic-style markers are applied only to the
+  Prism `PromptCacheBreakpoint` locations the caller selects via
+  `ProviderRequestOptions.cache.breakpoints` (last content block of each
+  selected message). When breakpoints are present, top-level automatic
+  `cache_control` is omitted.
 - Caching is enabled unless disabled (`cacheRetention: "none"` /
   `cache.mode: "off"`) and the model opts in via `ModelConfig.cache.kind`
   (`"cache_control"`) or the legacy `compat.openRouterCache: true` flag.
 - `cacheRetention: "long"` (or `cache.retention: "long"`) emits
-  `cache_control: { type: "ephemeral", ttl: "1h" }` markers when the model allows
-  long retention (`ModelConfig.cache.longRetention !== false`); otherwise the
-  default 5-minute ephemeral window applies.
-- Usage accounting is preserved: OpenRouter `prompt_tokens_details.cached_tokens`
-  maps to `Usage.cacheReadTokens` and `prompt_tokens_details.cache_write_tokens`
-  maps to `Usage.cacheWriteTokens`.
+  `ttl: "1h"` on markers / top-level automatic control when the model allows
+  long retention (`ModelConfig.cache.longRetention !== false`).
+- Usage accounting: OpenRouter `prompt_tokens_details.cached_tokens` →
+  `Usage.cacheReadTokens`; `prompt_tokens_details.cache_write_tokens` →
+  `Usage.cacheWriteTokens`.
+
+### Model discovery
+
+```ts
+const models = await listOpenRouterModels({ apiKey, fetch, signal, baseUrl });
+createOpenRouterProviderPackage({ apiKey, models: models.filter(...) });
+```
+
+`mapOpenRouterModel` converts official per-token USD pricing to
+`ModelCost` with `unit: "per_million_tokens"`, infers `cache.kind` (`cache_control`
+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.
 
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport` helpers (`readSseData`, `readBoundedResponseText`).
-- No catalog fetch during setup; no automatic environment, file, keychain, or shell
-  credential lookup.
+- No catalog fetch during setup; discovery is caller-gated and bounded.
+- 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.
+  redacted from errors (including discovery failures).
 - Caller-supplied `ProviderRequest.options.headers` can add non-owned headers,
   but OpenRouter-owned headers are applied last: `Authorization`,
   `Content-Type`, `X-Session-Id`, `HTTP-Referer`, and `X-Title` cannot be
@@ -127,9 +192,14 @@ await kernel.load([
 ## Related APIs
 
 - [Provider packages](../provider-packages.md): `defineProviderPackage`,
-  `ModelConfig`/`compat`, cache policy, request policies.
+  `ModelConfig`/`compat`, cache policy, caller-gated discovery.
+- [Thinking and reasoning](../thinking-and-reasoning.md): `applyThinkingLevel`
+  / `openai_reasoning` family for OpenRouter.
 - [Credentials and redaction](../credentials-and-redaction.md):
   `resolveCredentialValue`, `redactSecrets`.
 - [Provider layer](../provider-layer.md): `ProviderRequest.options` and usage
   mapping.
 - [Provider conformance](../provider-conformance.md): network-free adapter tests.
+- Official: [Models API](https://openrouter.ai/docs/api/api-reference/models/get-models),
+  [Prompt caching](https://openrouter.ai/docs/guides/best-practices/prompt-caching),
+  [Reasoning tokens](https://openrouter.ai/docs/guides/best-practices/reasoning-tokens).