@arnilo/prism 0.0.4 → 0.0.6

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).