@arnilo/prism 0.0.5 → 0.0.7

package/docs/postgres-persistence.md

@@ -24,7 +24,7 @@ Use this package when you need server-backed persistence with pooled connections
 - managed cloud databases (RDS, Cloud SQL, Neon, Supabase, etc.)
 - CI integration tests against a real PostgreSQL service
 
-Prefer [`@arnilo/prism-session-store-sqlite`](sqlite-persistence.md) for local CLI tools, single-writer workloads, and network-free default tests.
+Prefer [`@arnilo/prism-session-store-sqlite`](sqlite-persistence.md) for local CLI tools, single-writer workloads, and network-free default tests. This adapter stores sessions/runs, not semantic vectors; use the separate [`@arnilo/prism-memory` pgvector path](working-and-semantic-memory.md), which rejects non-finite vectors before SQL, when vector recall is needed.
 
 ## Inputs / request
 
@@ -59,7 +59,7 @@ Hosts own TLS (`ssl` in `poolConfig`), credentials, connection limits, and backu
 | `leases` | Atomic `LeaseStore` backed by `prism_leases`; database-clock expiry, opaque renew/release token, monotonic takeover fence. |
 | `close()` | Ends the pool when the adapter created it from `connectionString`. |
 
-Migrations run automatically on open and are idempotent across reopen. Concurrent setup uses per-schema advisory transaction locks.
+Migrations run automatically on open and are idempotent across reopen. Concurrent setup uses per-schema advisory transaction locks. While holding that lock, startup verifies ordered contract name/version/SHA-256 rows and full schema-v3 `information_schema`/catalog shape (all required tables, columns/types/nullability/defaults, PK/unique/FK keys, and named indexes) before any runtime write. A complete legacy 0.0.5 history with all `checksum` values `NULL` is shape-verified then backfilled transactionally once. Unknown, duplicate, out-of-order, partial-legacy, checksum, or shape drift rejects open; restore or apply reviewed DDL rather than editing migration rows.
 
 ## Request/response example
 
@@ -127,7 +127,7 @@ PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres --workspace @arnil
 - **Redaction upstream.** Event and tool-call payloads may contain secrets; redact before ledger writes. The adapter does not scan or rewrite row contents.
 - **Bounded pool.** Adapter-owned pools default to `max: 10`. Hosts with heavy concurrency should supply their own pool sizing.
 - **Indexed operations.** Append, parent validation, idempotency dedup, branch reads, and pagination use the indexes documented in [Database persistence](database-persistence.md); normal paths avoid sequential scans.
-- **Migration locking.** `pg_advisory_xact_lock` prevents concurrent migration races when multiple processes open the adapter at once.
+- **Migration locking.** `pg_advisory_xact_lock` prevents concurrent migration races when multiple processes open the adapter at once. Startup catalog reads are bounded metadata queries, not application-row scans.
 - **Tenant isolation.** `tenant_id` / `account_id` / `user_id` columns participate in query filters; hosts must still scope writes correctly.
 - **Benchmark target.** Indexed append + paginated branch read on a warm pool should stay under **50 ms p95** for local/CI-sized datasets (≤100k entries per session); measure with your pool size and hardware before production sizing.
 

package/docs/provider-caching.md

@@ -21,6 +21,7 @@ Use this page when a host or provider package needs to:
 - Carry a stable cache key across turns without putting provider-specific fields in core.
 - Read `ModelConfig.cache` to decide whether to map hints to implicit caching, key-based caching, cache-control breakpoints, provider-specific caching, or no caching.
 - Compute normalized cache diagnostics from `Usage.cacheReadTokens` / `Usage.cacheWriteTokens`, including providers that only report reads.
+- Understand when **caller-gated model discovery** may fill `ModelConfig.cache` / `ModelConfig.cost` from a live `/models` response (see [Discovery and live cache/cost metadata](#discovery-and-live-cache-cost-metadata)).
 
 Do not use cache keys for credentials, bearer tokens, API keys, OAuth tokens, user secrets, or raw private prompts.
 
@@ -145,21 +146,23 @@ Provider request policies can set `ProviderRequestOptions.cache` or the legacy `
 | Provider package | Cache kind | Explicit cache hints | Multi-turn reuse notes | Caveats |
 | --- | --- | --- | --- | --- |
 | `@arnilo/prism-provider-openai` | `openai_key` | Sends sanitized `prompt_cache_key`; `prompt_cache_retention: "24h"` only when the model declares `longRetention`. | Stable cache key + stable prefix can improve reuse. | Best-effort only; `"short"`/`"none"` omit retention. |
-| `@arnilo/prism-provider-openrouter` | `cache_control` | Applies `cache_control` markers only to caller-selected `cache.breakpoints`; `"long"` may add `ttl: "1h"`. | Breakpoint-stable prefixes can be reused by upstream providers. | Best-effort only; no marker is added to every block. |
+| `@arnilo/prism-provider-openrouter` | `cache_control` | Top-level automatic `cache_control` when enabled without breakpoints; otherwise markers only on caller-selected `cache.breakpoints`; `"long"` may add `ttl: "1h"`. Sticky `session_id` routing. | Breakpoint-stable / automatic prefixes can be reused by upstream providers. | Best-effort only; top-level automatic may exclude some backends from routing. |
 | `@arnilo/prism-provider-opencode-go` | route-specific | Sends sanitized `x-opencode-session`; Anthropic route applies selected `cache_control` breakpoints; OpenAI route sends none. | Session id + unchanged selected anchors can help route-native caches. | Best-effort and route-dependent. |
 | `@arnilo/prism-provider-zai` | `implicit` | No explicit cache payload; GLM context caching is automatic. | Resend unchanged prior history for implicit context-cache reuse. | Best-effort only; cache options do not force hits. |
 | `@arnilo/prism-provider-kimi` | implicit by default, optional `cache_control` | Default catalog models send no `cache_control`; hosts may opt in on Anthropic `/messages` models with `ModelConfig.cache.kind: "cache_control"`. | Keep selected Anthropic anchors and prior history stable. | Best-effort and model/route-dependent. |
 | `@arnilo/prism-provider-neuralwatt` | `implicit` | No `cache_control`, `cacheKey`, `prompt_cache`, or `cacheRetention` payload; NeuralWatt vLLM prefix caching is automatic. | Full prior history must be resent unchanged with only the new turn appended; `inputLayout: "cache_aware"` keeps stable prefixes first. | Best-effort only; does not promise cache hits; `cacheRetention: "none"` disables Prism hints only, not the implicit backend prefix cache. |
+| `@arnilo/prism-provider-ai-sdk` | host-owned | No Prism cache payload; host `LanguageModelV4` owns upstream caching. | Host model/provider decides cache keys, breakpoints, and sticky routing. | Adapter maps `inputTokens.cacheRead`/`cacheWrite` from `finish.usage` only; does not invent cache fields. |
 
 Detailed first-party provider notes:
 
-- OpenAI Responses (`@arnilo/prism-provider-openai`): `kind: "openai_key"`. Sanitizes/clamps `prompt_cache_key` to 64 chars; `"long"` retention maps to `prompt_cache_retention: "24h"` only when the model declares `cache.longRetention`; `"short"`/`"none"` omit the field. `input_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`.
+- OpenAI Responses (`@arnilo/prism-provider-openai`): `kind: "openai_key"`. Sanitizes/clamps `prompt_cache_key` to 64 chars; `"long"` retention maps to `prompt_cache_retention: "24h"` only when the model declares `cache.longRetention`; `"short"`/`"none"` omit the field. GPT-5.6+ official docs use `prompt_cache_options` / breakpoints instead of retention — `listOpenAIModels` sets `longRetention: false` for those ids. `input_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`.
 - OpenAI-compatible Chat Completions adapter: minimal scope, sends no cache payload; see [OpenAI-compatible provider](providers/openai-compatible.md).
-- OpenRouter (`@arnilo/prism-provider-openrouter`): `kind: "cache_control"`. Sanitizes/clamps `session_id`/`X-Session-Id` to 256 chars; applies Anthropic-style `cache_control` markers only to caller-selected `cache.breakpoints` (last content block of each selected message), not every block; `"long"` retention adds `ttl: "1h"` when the model allows it. `prompt_tokens_details.cached_tokens`/`cache_write_tokens` map to `Usage.cacheReadTokens`/`cacheWriteTokens`.
-- OpenCode Go (`@arnilo/prism-provider-opencode-go`): `x-opencode-session` from `cacheKey ?? sessionId`, sanitized to 128 chars; the Anthropic route applies `cache_control` markers only to selected breakpoints (`"long"` → `ttl: "1h"`), the OpenAI route sends none. OpenAI route maps `prompt_tokens_details.cached_tokens`/`cache_write_tokens`; Anthropic route maps `cache_read_input_tokens`/`cache_creation_input_tokens`.
+- OpenRouter (`@arnilo/prism-provider-openrouter`): `kind: "cache_control"`. Sanitizes/clamps `session_id`/`X-Session-Id` to 256 chars for sticky routing; with no breakpoints emits top-level automatic `cache_control: { type: "ephemeral" }`; with breakpoints applies Anthropic-style markers only to caller-selected locations (last content block of each selected message); `"long"` retention adds `ttl: "1h"` when the model allows it. `prompt_tokens_details.cached_tokens`/`cache_write_tokens` map to `Usage.cacheReadTokens`/`cacheWriteTokens`. Optional `listOpenRouterModels()` may populate `ModelConfig.cache`/`cost` from live pricing.
+- OpenCode Go (`@arnilo/prism-provider-opencode-go`): default base `https://opencode.ai/zen/go/v1`; `x-opencode-session` from `cacheKey ?? sessionId`, sanitized to 128 chars; the Anthropic route (MiniMax/Qwen) applies `cache_control` markers only to selected breakpoints (`"long"` → `ttl: "1h"`), the OpenAI route (Grok/GLM/Kimi/MiMo/DeepSeek) sends none and preserves `reasoning_content`. OpenAI route maps `prompt_tokens_details.cached_tokens`/`cache_write_tokens`; Anthropic route maps `cache_read_input_tokens`/`cache_creation_input_tokens`. Caller-gated `listOpenCodeGoModels` against official `GET /zen/go/v1/models`.
 - Z.AI (`@arnilo/prism-provider-zai`): `kind: "implicit"`. GLM context caching is automatic; sends no explicit cache payload regardless of cache options. `prompt_tokens_details.cached_tokens`/`cache_write_tokens` map to `Usage.cacheReadTokens`/`cacheWriteTokens`.
 - NeuralWatt (`@arnilo/prism-provider-neuralwatt`): `kind: "implicit"`. NeuralWatt prefix caching is automatic; sends no explicit cache payload regardless of cache options. `cacheRetention: "none"` disables Prism cache-control hints only (not the implicit backend prefix cache). `prompt_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`; NeuralWatt does not report a cache-write token, so `Usage.cacheWriteTokens` is never fabricated (stays `undefined`). NeuralWatt's `/v1/models` catalog advertises exact `cached_input_per_million` rates for cache reads and `cached_output_per_million: null`; static curated aliases do not guess those prices.
 - Kimi (`@arnilo/prism-provider-kimi`): default catalog models use implicit caching (no `cache_control`); hosts opt in via `ModelConfig.cache.kind: "cache_control"` on the Anthropic `/messages` route, then `cache_control` markers apply only to selected breakpoints (`"long"` → `ttl: "1h"`); the Moonshot OpenAI route sends none. `cache_read_input_tokens`/`cache_creation_input_tokens` map to `Usage.cacheReadTokens`/`cacheWriteTokens`.
+- AI SDK adapter (`@arnilo/prism-provider-ai-sdk`): **host-owned**. Sends no Prism cache payload; the supplied `LanguageModelV4` and its upstream provider own request caching. Maps AI SDK v4 `finish.usage.inputTokens.cacheRead`/`cacheWrite` to `Usage.cacheReadTokens`/`cacheWriteTokens`. No `list*Models()` export.
 
 ### NeuralWatt cache-aware limiter
 
@@ -185,6 +188,15 @@ sessions differently from one-shot chat:
 See [NeuralWatt provider](providers/neuralwatt.md) for the package-level cache,
 usage, and retry details.
 
+## Discovery and live cache/cost metadata
+
+Caller-gated `list*Models()` helpers (see [Provider packages — Caller-gated model discovery](provider-packages.md#caller-gated-model-discovery)) may map official list-models fields onto `ModelConfig`:
+
+- `cache` — when the provider documents cache kind / long-retention / breakpoint support in model metadata (otherwise keep the package's known default, e.g. NeuralWatt/Z.AI `implicit`, OpenAI `openai_key`).
+- `cost` — when the provider documents per-token or per-million rates, including cache-read rates such as NeuralWatt `cached_input_per_million`.
+
+Static featured catalogs remain offline bootstrap and must **not** invent pricing or cache capabilities the official docs do not state. Discovery is never invoked by `create*ProviderPackage()`; hosts that want live `cost`/`cache` pass the returned models into package `models:` (or register them themselves).
+
 ## Security and performance notes
 
 - Cache hints are best-effort and do not guarantee cache hits.

package/docs/provider-conformance.md

@@ -133,6 +133,44 @@ await assertProviderStreamConforms({
 });
 ```
 
+## Model discovery checklist
+
+Every first-party package that ships (or plans) a `list*Models()` helper must keep setup network-free. Add these assertions in the package suite (pattern from NeuralWatt):
+
+1. **`*_provider_setup_does_not_call_model_discovery`** — inject a counting `fetch` into `create*ProviderPackage({ fetch })`, run `setup`, assert `calls === 0`.
+2. **`list_*_models_maps_fixture_…`** — fixture response maps to `ModelConfig` (`id` → `model`, documented capabilities/limits/cost/cache); no credentials in returned objects.
+3. **`list_*_models_forwards_auth_abort_baseurl`** (as applicable) — Authorization owned by helper when key present; auth omitted when optional and unset; `signal` / `baseUrl` forwarded.
+4. **`list_*_models_redacts_token_in_errors`** — non-OK bodies use `readBoundedResponseText` + `redactSecrets`; secret canaries absent from thrown messages.
+5. **Malformed payload rejects** — missing `data` array (or provider-equivalent) throws a clear discovery error.
+
+OpenRouter stays app-registration-first: an optional list helper must still not run during setup. AI SDK has no discovery export. Packages without a public list API document curated official-doc refresh instead of inventing a fake helper.
+
+Canonical contract: [Provider packages — Caller-gated model discovery](provider-packages.md#caller-gated-model-discovery).
+
+## Thinking / reasoning checklist
+
+Every first-party package that exposes thinking or reasoning controls should cover:
+
+1. **Model default** — `ModelConfig.compat` (or documented capability) sets the official wire field when no per-turn override is present.
+2. **Per-turn override wins** — `ProviderRequestOptions.compat` via `mergeProviderRequestOptions` / `applyThinkingLevel` overrides the model default.
+3. **Shared family mapping** — effort levels from `ThinkingLevel` land in the package's recommended family (`openai_reasoning` / `reasoning_effort` / `thinking_type` / `noop`) per [Thinking and reasoning](thinking-and-reasoning.md).
+4. **Non-reasoning / noop** — applying a level with `noop` (or omitting compat) must not invent unsupported body fields.
+5. **No inert `extra.thinkingLevel`** — package code must not rely on `options.extra.thinkingLevel` for wire mapping.
+
+Canonical contract: [Thinking and reasoning](thinking-and-reasoning.md).
+
+## AI SDK adapter checklist
+
+`@arnilo/prism-provider-ai-sdk` is a host-owned `LanguageModelV4` bridge. It does not participate in the discovery or thinking/reasoning checklists above. Cover instead:
+
+1. **No catalog / no setup fetch** — package exports no `list*Models()`; `createAiSdkProvider` wraps a host model only.
+2. **Specification gate** — rejects non-v4 models (`specificationVersion !== "v4"` or missing `doStream`).
+3. **Cache usage mapping** — `finish.usage.inputTokens.cacheRead`/`cacheWrite` map to `Usage.cacheReadTokens`/`cacheWriteTokens`; adapter does not emit cache request fields.
+4. **Reasoning stream mapping** — `reasoning-delta` → thinking deltas; assistant `thinking` blocks replay as AI SDK `reasoning` prompt parts.
+5. **Host-owned controls** — `options.compat` / `options.extra` forward as `providerOptions.prism`; reasoning effort stays on the host model.
+
+Canonical contract: [AI SDK provider adapter](providers/ai-sdk.md).
+
 ## Extension and configuration notes
 
 The helpers are a testing subpath only. Provider packages can use them with their own mocked fetch/transport or `createMockProvider()`. Live provider tests should stay opt-in and env-gated outside Prism's default test suite.
@@ -148,7 +186,7 @@ The helpers are a testing subpath only. Provider packages can use them with thei
 ## Related APIs
 
 - [Provider layer](provider-layer.md): `AIProvider`, provider events, and mock provider.
-- [Provider packages](provider-packages.md): package authors can use conformance helpers for adapters.
+- [Provider packages](provider-packages.md): package authors can use conformance helpers for adapters; includes the caller-gated discovery contract and setup zero-fetch rule.
 - [AI SDK provider adapter](providers/ai-sdk.md): optional `LanguageModelV4` bridge tested with a fake AI SDK model.
 - [OpenAI-compatible provider](providers/openai-compatible.md): optional provider adapter tested with mocked streams.
 - [Public contracts](public-contracts.md): provider request/event/usage contracts.

package/docs/provider-packages.md

@@ -67,7 +67,7 @@ Phase 6 also adds optional [`@arnilo/prism-provider-ai-sdk`](providers/ai-sdk.md
 
 Provider live tests are real smoke tests gated by `PRISM_LIVE_PROVIDER_TESTS=1` plus the provider-specific API key (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `KIMI_API_KEY`, `ZAI_API_KEY`, `NEURALWATT_API_KEY`, or `OPENCODE_API_KEY`). They cover text generation, tool-call loop behavior, abort/error paths where supported, and no-secret-leak assertions; they skip by default and never run in release verification.
 
-These workspaces still follow the same rule as external packages: no provider SDK dependency, catalog fetch, env scan, keychain/file credential lookup, shell auth command, OAuth login, or live provider call runs by default. `@arnilo/prism-provider-openai` now registers OpenAI Responses and OpenAI Codex providers from caller-supplied credentials only. `@arnilo/prism-provider-opencode-go` now registers static OpenCode Go metadata and package-local OpenAI/Anthropic-compatible routes from caller-supplied credentials only. `@arnilo/prism-provider-openrouter` now registers an app-controlled OpenRouter catalog with routing/reasoning/cache passthrough and no setup catalog fetch. `@arnilo/prism-provider-zai` now registers static GLM metadata with Z.AI thinking/reasoning/tool-stream request mapping. `@arnilo/prism-provider-kimi` now registers Kimi Coding Anthropic-compatible behavior by default and optional Moonshot metadata only when requested. `@arnilo/prism-provider-neuralwatt` now registers static featured model metadata with NeuralWatt reasoning_effort/thinking_token_budget/chat_template_kwargs request mapping, SSE comment tolerance, an opt-in `listNeuralWattModels()` helper for explicit `/v1/models` discovery, `getNeuralWattQuota()` for on-demand account balance/usage/energy, `neuralWattEventsWithTelemetry()`/`mapNeuralWattTelemetry()` for `: energy`/`: cost` telemetry, and `classifyNeuralWattError()` for retry classification. None of these helpers run during package setup or generation.
+These workspaces still follow the same rule as external packages: no provider SDK dependency, catalog fetch, env scan, keychain/file credential lookup, shell auth command, OAuth login, or live provider call runs by default. `@arnilo/prism-provider-openai` now registers OpenAI Responses and OpenAI Codex providers from caller-supplied credentials only, with optional `models`/`codexModels` overrides and an opt-in `listOpenAIModels()` helper for official `GET /models` discovery. `@arnilo/prism-provider-opencode-go` now registers docs-verified OpenCode Go open coding models with dual OpenAI/Anthropic routes (`compat.route`), official default base `https://opencode.ai/zen/go/v1`, `reasoning_content`/thinking preserve, and an opt-in `listOpenCodeGoModels()` helper for official `GET /zen/go/v1/models`. `@arnilo/prism-provider-openrouter` now registers an app-controlled OpenRouter catalog with routing/`reasoning`/cache passthrough, assistant `reasoning` replay, optional top-level automatic `cache_control`, and an opt-in `listOpenRouterModels()` helper for official `GET /api/v1/models` (setup still never fetches). `@arnilo/prism-provider-zai` now registers featured GLM-5.x/4.x metadata with official `thinking`/`reasoning_effort`/`tool_stream`/`clear_thinking` mapping, Preserved Thinking `reasoning_content` replay, implicit context caching, and an opt-in `listZaiModels()` helper for OpenAI-compatible `GET /models`. `@arnilo/prism-provider-kimi` now registers Kimi Coding Anthropic-compatible behavior by default, optional callable Moonshot Open Platform Chat Completions when `includeMoonshotModels` is requested, official Coding/Open Platform featured ids, thinking/`reasoning_effort` compat mapping, and an opt-in `listKimiModels()` helper for Moonshot `GET /v1/models`. `@arnilo/prism-provider-neuralwatt` now registers static featured model metadata with NeuralWatt reasoning_effort/thinking_token_budget/chat_template_kwargs request mapping, SSE comment tolerance, an opt-in `listNeuralWattModels()` helper for explicit `/v1/models` discovery, `getNeuralWattQuota()` for on-demand account balance/usage/energy, `neuralWattEventsWithTelemetry()`/`mapNeuralWattTelemetry()` for `: energy`/`: cost` telemetry, and `classifyNeuralWattError()` for retry classification. None of these helpers run during package setup or generation.
 
 ### First-party cache behavior
 
@@ -75,14 +75,71 @@ Every first-party provider package hardens prompt-cache behavior so it cannot em
 
 - **OpenAI** (`kind: openai_key`): `prompt_cache_key` is sanitized and clamped to 64 chars; `prompt_cache_retention` is emitted as `24h` only when the model declares `cache.longRetention`, and omitted for `short`/`none` (the API only accepts absent or `24h`). `prompt_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`.
 - **OpenAI-compatible core adapter**: Chat Completions sends no `prompt_cache_key`/`prompt_cache_retention`/`cache_control` fields; endpoints cache implicitly. `prompt_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`.
-- **OpenRouter** (`kind: cache_control`): `session_id`/`x-session-id` sanitized and clamped to 256 chars; `cache_control` markers applied only to caller-selected `cache.breakpoints` (not every block); `cacheRetention: long` adds `ttl: 1h` when allowed. Preserves `cached_tokens`/`cache_write_tokens`.
-- **OpenCode Go**: `x-opencode-session` from `cacheKey ?? sessionId` sanitized to 128 chars; the Anthropic route applies `cache_control` only to selected breakpoints (`long` → `ttl: 1h`), the OpenAI route sends none. Per-route usage mapping.
+- **OpenRouter** (`kind: cache_control`): `session_id`/`x-session-id` sanitized and clamped to 256 chars; with no breakpoints, emits top-level automatic `cache_control: { type: ephemeral }`; with breakpoints, markers applied only to caller-selected locations (not every block); `cacheRetention: long` adds `ttl: 1h` when allowed. Preserves `cached_tokens`/`cache_write_tokens`.
+- **OpenCode Go**: default base `https://opencode.ai/zen/go/v1`; `x-opencode-session` from `cacheKey ?? sessionId` sanitized to 128 chars; Anthropic route (MiniMax/Qwen) applies `cache_control` only to selected breakpoints (`long` → `ttl: 1h`); OpenAI route (Grok/GLM/Kimi/MiMo/DeepSeek) sends none and preserves `reasoning_content`. Per-route usage mapping. Caller-gated `listOpenCodeGoModels`.
 - **Z.AI** (`kind: implicit`): GLM context caching is automatic; no explicit cache payload sent regardless of cache options. `prompt_tokens_details.cached_tokens`/`cache_write_tokens` map to cache usage.
 - **NeuralWatt** (`kind: implicit`): NeuralWatt prefix caching is automatic; sends no explicit cache payload regardless of cache options. `cacheRetention: "none"` disables Prism cache-control hints only (not the implicit backend prefix cache). `prompt_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`; NeuralWatt does not report a cache-write token so `Usage.cacheWriteTokens` is never fabricated.
 - **Kimi**: default catalog models use implicit caching (no `cache_control`); hosts opt in via `ModelConfig.cache.kind: cache_control` on the Anthropic `/messages` route, then markers apply only to selected breakpoints (`long` → `ttl: 1h`); the Moonshot OpenAI route sends none. `cache_read_input_tokens`/`cache_creation_input_tokens` map to cache usage.
 
 See [Provider caching](provider-caching.md) for the `PromptCacheHints` surface and shared helpers, and [Provider conformance](provider-conformance.md) for the `assertUsageAccounting` and `assertProviderOwnedHeadersWin` checks every first-party package exercises.
 
+## Caller-gated model discovery
+
+First-party packages keep `create*ProviderPackage()` network-free. Latest models come from **caller-gated** `list*Models()` helpers that hosts invoke explicitly and then pass back via `models:` (or register themselves). Plan 015's "no setup catalog fetch" rule still holds; Plan 067 adds on-demand discovery without hidden latency.
+
+### Contract
+
+```ts
+export async function listExampleModels(options: {
+  apiKey?: CredentialValueSource;
+  fetch?: typeof fetch;
+  baseUrl?: string;
+  signal?: AbortSignal;
+  headers?: Readonly<Record<string, string>>;
+}): Promise<ModelConfig[]> {
+  // GET {baseUrl}/models — never called from create*ProviderPackage()
+}
+```
+
+| Rule | Requirement |
+| --- | --- |
+| Setup | `create*ProviderPackage().setup` performs **zero** fetches / discovery calls |
+| Shape | Package-local `list*Models(options) → Promise<ModelConfig[]>` + optional `map*Model(entry)` |
+| Injectables | `fetch`, `baseUrl`, `signal`, optional `apiKey` / `headers` |
+| Transport | Error bodies via `@arnilo/prism/providers/transport` `readBoundedResponseText`; credentials via `resolveCredentialValue` + `redactSecrets` |
+| Return | `ModelConfig[]` only — never embed API keys, tokens, or auth headers in returned metadata |
+| Static catalog | Featured aliases / offline bootstrap only; may omit live pricing until discovery fills `cost` / `cache` |
+| Core | Prefer package-local helpers. Do **not** add a core model-discovery registry. Extract a shared HTTP/list helper only when ≥2 packages share identical parsing |
+
+Template: [`listNeuralWattModels`](providers/neuralwatt.md) in `@arnilo/prism-provider-neuralwatt`.
+
+### Per-package policy
+
+| Package | Discovery helper | Setup catalog | Notes |
+| --- | --- | --- | --- |
+| OpenAI | **`listOpenAIModels` (exists)** | Featured Responses/Codex aliases; factory accepts `models?` / `codexModels?` | Official `GET /v1/models`; Codex not listed by api.openai.com |
+| Kimi | **`listKimiModels`** (Moonshot `GET /v1/models`) | Featured Coding ids + optional callable Moonshot | Official Moonshot/Kimi list-models; Coding curated |
+| Z.AI | **`listZaiModels`** (OpenAI-compatible `GET /models`) + curated featured refresh | Featured GLM-5.2…4.5 aliases | No first-class docs.z.ai list page; discovery is best-effort; featured set from Chat Completions enum / overview |
+| OpenRouter | **`listOpenRouterModels`** (official `GET /api/v1/models`) | **App-controlled** `models:` only — no bundled mega-catalog | Helper feeds host registration; setup still does not fetch |
+| OpenCode Go | **`listOpenCodeGoModels`** (official `GET /zen/go/v1/models`) | Featured dual-route official Go aliases | Official Go docs endpoint table + sparse list API |
+| NeuralWatt | **`listNeuralWattModels` (exists)** | Featured aliases without guessed pricing | Auth optional for public models |
+| AI SDK | None | Host-owned `LanguageModelV4` | No Prism-side catalog by design |
+
+Host pattern:
+
+```ts
+const models = await listNeuralWattModels({ apiKey, fetch });
+await kernel.load([createNeuralWattProviderPackage({ apiKey, models })]);
+```
+
+Discovery may populate `ModelConfig.cache` and `ModelConfig.cost` from live metadata when the provider documents those fields; see [Provider caching](provider-caching.md#discovery-and-live-cache-cost-metadata). Package authors: include the [setup zero-fetch checklist](provider-conformance.md#model-discovery-checklist) in every first-party suite that ships or plans a `list*Models` helper.
+
+## Per-turn thinking / reasoning
+
+Hosts set effort with portable helpers from `@arnilo/prism` (`applyThinkingLevel`, `thinkingCompatFor`) that write official fields into `ProviderRequestOptions.compat`. Model defaults stay on `ModelConfig.compat`; per-turn patches win via `mergeProviderRequestOptions`. Providers keep reading `options.compat` / `model.compat` — do not invent a parallel options tree or put effort only in `extra`.
+
+Canonical contract: [Thinking and reasoning](thinking-and-reasoning.md). Package-local knobs (NeuralWatt budgets, Z.AI `tool_stream`, Kimi keep/all) remain on `compat` beside the shared families.
+
 ## Third-party provider packaging
 
 A third party ships their own providers the same way Prism ships first-party

package/docs/providers/ai-sdk.md

@@ -52,6 +52,8 @@ Unsupported content fails before `doStream` (for example unresolved `resourceUri
 | `finish` usage | `usage` then `done` |
 | `error` / thrown / abort | redacted `error` |
 
+`finish.usage.inputTokens.cacheRead` / `cacheWrite` map to Prism `Usage.cacheReadTokens` / `cacheWriteTokens`. The adapter does not invent cache request fields; prompt caching is owned by the host `LanguageModelV4` and its upstream provider.
+
 Provider-executed tool calls, files/sources/custom parts, warnings, and raw chunks are ignored rather than silently converted into unsupported Prism content.
 
 ## Request/response example
@@ -89,6 +91,40 @@ const result = await agent.createSession().run("Summarize this");
 console.log(result.text);
 ```
 
+## Model catalog and discovery
+
+There is **no Prism-side model catalog** and **no `list*Models()` export** by design. Hosts supply a ready-made `LanguageModelV4` instance (typically from `@ai-sdk/openai`, `@ai-sdk/anthropic`, AI Gateway, or a custom provider) and register a matching `ModelConfig` for capabilities/limits.
+
+Prism setup remains network-free: `createAiSdkProvider` only wraps the supplied model and never fetches catalogs or credentials.
+
+## Prompt caching
+
+The adapter is **host-owned for request caching**. It does not emit `cache_control`, `prompt_cache_key`, `cacheKey`, or `cacheRetention` on AI SDK call options. Hosts configure caching on the underlying AI SDK model/provider (for example via AI SDK `providerOptions` on the model factory or per-call options forwarded through `options.compat` / `options.extra` → `providerOptions.prism`).
+
+When the host model reports cache accounting on the `finish` stream part, Prism maps official AI SDK v4 usage fields:
+
+| AI SDK `LanguageModelV4Usage` | Prism `Usage` |
+| --- | --- |
+| `inputTokens.cacheRead` | `cacheReadTokens` |
+| `inputTokens.cacheWrite` | `cacheWriteTokens` |
+| `inputTokens.total` | `inputTokens` |
+| `outputTokens.total` | `outputTokens` |
+
+See [Provider caching](../provider-caching.md) for the cross-provider matrix.
+
+## Thinking and reasoning
+
+Reasoning effort, budgets, and provider-specific thinking controls are **host-model-owned**. Prism does not map `ThinkingLevel` into AI SDK call options (`thinkingFamilyForModel` → `noop`). Hosts configure reasoning on the AI SDK model (for example OpenAI `reasoning.effort` via AI SDK `providerOptions`) and may pass per-turn overrides through `ProviderRequestOptions.compat` / `extra`, which the adapter forwards as `providerOptions.prism`.
+
+Stream mapping:
+
+| Direction | Mapping |
+| --- | --- |
+| AI SDK `reasoning-delta` → Prism | `content_delta` thinking |
+| Prism `thinking` blocks → AI SDK prompt | `{ type: "reasoning", text }` on assistant messages |
+
+Official evidence: [Custom providers / LanguageModelV4](https://ai-sdk.dev/providers/community-providers/custom-providers); [Language Model Specification V4](https://github.com/vercel/ai/tree/main/packages/provider/src/language-model/v4); `@ai-sdk/provider` `LanguageModelV4Usage` (`inputTokens.cacheRead` / `cacheWrite`).
+
 ## Extension and configuration notes
 
 - Peer dependency: `@ai-sdk/provider@^4.0.0`. Upgrade policy tracks one specification major at a time.

package/docs/providers/kimi.md

@@ -2,132 +2,195 @@
 
 ## What it does
 
-`@arnilo/prism-provider-kimi` provides explicit, side-effect-free setup for Kimi For
-Coding using an Anthropic-compatible `/messages` endpoint with
-`User-Agent: KimiCLI/1.5` (unless overridden). Moonshot/Open Platform model
-metadata is optional.
+`@arnilo/prism-provider-kimi` provides two distinct, side-effect-free routes:
 
-The package registers the `kimi-coding` provider, default Kimi Coding model
-metadata, and an `api_key` auth method through `createExtensionKernel().load([...])`.
+1. **Kimi For Coding** (default) — Anthropic-compatible `POST /messages` on
+   `https://api.kimi.com/coding` with `User-Agent: KimiCLI/1.5` (unless overridden).
+2. **Moonshot Open Platform** (opt-in) — OpenAI-compatible `POST /chat/completions`
+   on `https://api.moonshot.ai/v1` (or `api.moonshot.cn/v1`), registered only when
+   `includeMoonshotModels: true`.
+
+Official model ids differ by route. Coding uses `kimi-for-coding`,
+`kimi-for-coding-highspeed`, and `k3`. Open Platform uses `kimi-k2.7-code`,
+`kimi-k3`, and related catalog ids. Pi's `k2p7` alias is **not** used.
+
+Caller-gated discovery via `listKimiModels()` hits the official Moonshot
+`GET /v1/models` endpoint. Package setup never fetches.
 
 ## When to use it
 
-Use it when a host app wants the Kimi For Coding endpoint through Prism's
-`AgentSession` runtime with Kimi-specific serializer behavior.
+Use it when a host app wants Kimi For Coding and/or Moonshot Open Platform through
+Prism's `AgentSession` runtime with Kimi-specific serializers, thinking controls,
+and cache policy.
 
-Do not use it for Moonshot Open Platform default registration, automatic
-credential discovery, catalog fetches, or real-network tests.
+Do not use it for automatic credential discovery, setup-time catalog fetches, or
+real-network tests (live tests stay opt-in).
 
 ## Inputs / request
 
 ```ts
-import { createKimiProviderPackage } from "@arnilo/prism-provider-kimi";
+import {
+  createKimiProviderPackage,
+  listKimiModels,
+  defineKimiModel,
+} from "@arnilo/prism-provider-kimi";
 
 createKimiProviderPackage(options: KimiProviderPackageOptions): ProviderPackage
-defineKimiModel(config: KimiModelConfig): KimiModelConfig
+listKimiModels(options?: ListKimiModelsOptions): Promise<ModelConfig[]>
+defineKimiModel(config: KimiModelConfig): ModelConfig
 ```
 
 | Field | Type | Purpose |
 | --- | --- | --- |
-| `kimiApiKey` | `CredentialValueSource` | Direct/callback/resolver API-key source for Kimi. |
+| `kimiApiKey` | `CredentialValueSource` | Kimi For Coding API key. |
+| `moonshotApiKey` | `CredentialValueSource` | Moonshot Open Platform API key (not interchangeable with Coding keys). |
 | `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
-| `baseUrl` | `string` | Overrides the Kimi base URL. |
-| `id` | `string` | Overrides the provider id (default `kimi-coding`). |
-| `userAgent` | `string` | Overrides `User-Agent: KimiCLI/1.5`. |
-| `models` | `readonly ModelConfig[]` | Overrides `kimiCodingModels` defaults. |
-| `includeMoonshotModels` | `boolean` | Registers Moonshot models when `true` (default off). |
-| `moonshotModels` | `readonly ModelConfig[]` | Overrides `moonshotKimiModels` when included. |
+| `baseUrl` | `string` | Overrides the Coding base URL. |
+| `moonshotBaseUrl` | `string` | Overrides Moonshot base URL (default `https://api.moonshot.ai/v1`). |
+| `id` / `moonshotId` | `string` | Provider ids (defaults `kimi-coding` / `moonshot`). |
+| `userAgent` | `string` | Overrides Coding `User-Agent: KimiCLI/1.5`. |
+| `models` | `readonly ModelConfig[]` | Overrides featured Coding models. |
+| `includeMoonshotModels` | `boolean` | Registers callable Moonshot provider + models when `true`. |
+| `moonshotModels` | `readonly ModelConfig[]` | Overrides featured Moonshot models when included. |
 
 ## Outputs / response / events
 
 | Surface | Behavior |
 | --- | --- |
-| Provider stream | Prism text, thinking (preserved only when `model.compat.preserveThinking` is true, otherwise downgraded to text), tool-call delta/final, `usage`, `done`, redacted `error`. |
-| Block preservation | Text, thinking, assistant `tool_call` → `tool_use`, `tool_result` → `tool_result`, images when `capabilities.input` includes `"image"`. |
-| Auth method | `api_key` for `kimi-coding`, credential name `apiKey`. |
+| Coding stream | Prism text, thinking deltas, tool-call delta/final, `usage` (`cache_read_input_tokens` / `cache_creation_input_tokens`), `done`, redacted `error`. |
+| Moonshot stream | Same, with `delta.reasoning_content` → thinking; OpenAI-style usage cache details when present. |
+| Block preservation | Coding: Anthropic `thinking` / `tool_use` / `tool_result`. Moonshot: `reasoning_content` on assistant replay when `preserveThinking`. |
+| Auth methods | `api_key` for `kimi-coding`; also `moonshot` when opted in. |
 
 Unsupported block placements or unclaimed images fail before fetch.
 
+## Route differences
+
+| | Kimi For Coding | Moonshot Open Platform |
+| --- | --- | --- |
+| Base URL | `https://api.kimi.com/coding` | `https://api.moonshot.ai/v1` (or `.cn`) |
+| Wire API | Anthropic `/messages` | OpenAI `/chat/completions` |
+| Featured ids | `kimi-for-coding`, `kimi-for-coding-highspeed`, `k3` | `kimi-k2.7-code`, `kimi-k3` (+ discovery) |
+| Discovery | No public list API — curated featured aliases | Official `GET /v1/models` via `listKimiModels()` |
+| Cache | Implicit by default; opt-in Anthropic `cache_control` | Implicit only — never emits Anthropic `cache_control` |
+| Thinking | Block replay + body `thinking` / `reasoning_effort` | `reasoning_content` replay + body `thinking` / `reasoning_effort` |
+
+The Anthropic `/messages` request/response contract for Kimi remains under-documented
+upstream ([MoonshotAI/Kimi-K2#129](https://github.com/MoonshotAI/Kimi-K2/issues/129));
+Prism treats official Chat Completions thinking fields as best-effort passthrough on
+the Coding route.
+
+## Thinking / reasoning
+
+Official fields (Open Platform docs; Coding docs for `k3` effort mapping):
+
+| Model family | Official control | Prism `compat` |
+| --- | --- | --- |
+| K3 / Coding `k3` | top-level `reasoning_effort` (`max` on Open Platform; Coding also `low`/`high`) | `compat.reasoning_effort` — use Task 4 family `reasoning_effort` |
+| K2.7-code / Coding | thinking always on; Preserved Thinking always on | omit `thinking` by default; `preserveThinking: true` for replay; do not send `disabled` |
+| K2.6 / K2.5 | `thinking.type` enabled/disabled; K2.6 optional `keep: "all"` | `compat.thinking` — Task 4 family `thinking_type` |
+
+Per-turn `ProviderRequestOptions.compat` wins over `ModelConfig.compat`. Helpers:
+`kimiThinking`, `kimiReasoningEffort`, `kimiPreserveThinking`.
+
 ## Request/response example
 
-Example request (Anthropic-compatible `/messages` shape):
+Coding (Anthropic-compatible `/messages`):
 
 ```json
 {
-  "model": "kimi-latest",
-  "messages": [{ "role": "user", "content": "Hello" }],
+  "model": "kimi-for-coding",
+  "messages": [{ "role": "user", "content": [{ "type": "text", "text": "Hello" }] }],
   "stream": true
 }
 ```
 
+Moonshot (Chat Completions):
+
+```json
+{
+  "model": "kimi-k3",
+  "messages": [{ "role": "user", "content": "Hello" }],
+  "stream": true,
+  "reasoning_effort": "max"
+}
+```
+
 ## Implementation example
 
 ```ts
 import { createExtensionKernel } from "@arnilo/prism";
-import { createKimiProviderPackage } from "@arnilo/prism-provider-kimi";
+import {
+  createKimiProviderPackage,
+  listKimiModels,
+} from "@arnilo/prism-provider-kimi";
 
 const kernel = createExtensionKernel();
 await kernel.load([
-  createKimiProviderPackage({ kimiApiKey: "fake-kimi-key", includeMoonshotModels: false }),
+  createKimiProviderPackage({ kimiApiKey: "fake-kimi-key" }),
 ]);
-```
-
-Register Moonshot/Open Platform metadata explicitly:
 
-```ts
-import { createKimiProviderPackage } from "@arnilo/prism-provider-kimi";
+// Opt-in Moonshot Open Platform (callable provider + featured models)
+await kernel.load([
+  createKimiProviderPackage({
+    kimiApiKey: "fake-kimi-key",
+    includeMoonshotModels: true,
+    moonshotApiKey: "fake-moonshot-key",
+  }),
+]);
 
+// Caller-gated discovery — never runs during setup
+const latest = await listKimiModels({ apiKey: "fake-moonshot-key", fetch });
 await kernel.load([
-  createKimiProviderPackage({ kimiApiKey: "fake", includeMoonshotModels: true }),
+  createKimiProviderPackage({
+    includeMoonshotModels: true,
+    moonshotApiKey: "fake-moonshot-key",
+    moonshotModels: latest.filter((m) => m.model.startsWith("kimi-")),
+  }),
 ]);
 ```
 
 ## Extension and configuration notes
 
-- Hosts choose base URL, provider id, `User-Agent`, model list, credential source,
+- Hosts choose base URLs, provider ids, `User-Agent`, model lists, credential sources,
   and `fetch` impl.
-- Moonshot/Open Platform metadata is registered only with
-  `includeMoonshotModels: true`; it is not core behavior.
-- Package contributes models via the extension `api` and an `api_key` auth method.
+- Moonshot is registered only with `includeMoonshotModels: true` (provider + models + auth).
+- Featured catalogs are offline bootstrap only; refresh Open Platform via `listKimiModels()`.
 
 ### Cache behavior
 
-- Default catalog models (e.g. `kimi-k2.7-code` on the Anthropic-compatible
-  `/messages` route) use **implicit caching** and send no explicit `cache_control`
-  fields. `ProviderRequestOptions.cache` / `cacheKey` / `cacheRetention` have no
-  effect on the request body unless the model opts in.
-- Hosts may opt a model into Anthropic-style `cache_control` by declaring
-  `ModelConfig.cache.kind: "cache_control"` on the Anthropic route. When opted in,
-  `cache_control: { type: "ephemeral" }` markers are applied only to the
-  caller-selected `ProviderRequestOptions.cache.breakpoints` (resolved with the
-  shared `applyCacheControl()` helper) on the last content block of each selected
-  message — not to every block. `cacheRetention: "long"` adds `ttl: "1h"` when the
-  model allows long retention (`ModelConfig.cache.longRetention !== false`).
-- The Moonshot Open Platform route (`compat.route: "openai"`) never receives
-  Anthropic `cache_control` fields.
-- Usage accounting is preserved: Anthropic-route `cache_read_input_tokens` maps to
-  `Usage.cacheReadTokens` and `cache_creation_input_tokens` maps to
-  `Usage.cacheWriteTokens`.
+- Default Coding catalog models use **implicit caching** and send no explicit
+  `cache_control` fields unless the model opts in with
+  `ModelConfig.cache.kind: "cache_control"`.
+- When opted in, `cache_control: { type: "ephemeral" }` markers apply only to
+  caller-selected `ProviderRequestOptions.cache.breakpoints` on the last content
+  block of each selected message. `cacheRetention: "long"` adds `ttl: "1h"` when
+  the model allows long retention.
+- The Moonshot Open Platform route never receives Anthropic `cache_control` fields.
+- Coding usage: `cache_read_input_tokens` → `Usage.cacheReadTokens`,
+  `cache_creation_input_tokens` → `Usage.cacheWriteTokens`.
 
 ## Security and performance notes
 
-- SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport` helpers (`readSseData`, `readBoundedResponseText`).
+- SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport`
+  helpers (`readSseData`, `readBoundedResponseText`).
 - No network calls during import, setup, build, or default tests.
 - No automatic environment, file, keychain, or shell credential lookup.
-- Kimi credentials are resolved per request from caller-supplied values or resolvers
-  and redacted from errors.
+- Credentials are resolved per request from caller-supplied values or resolvers
+  and redacted from errors (including discovery failures).
 - Caller-supplied `ProviderRequest.options.headers` can add non-owned headers,
   but provider-owned headers (`content-type`, `user-agent`, `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 provider-specific
+  env names; default tests are network-free.
 
 ## Related APIs
 
 - [Provider packages](../provider-packages.md): `defineProviderPackage`,
-  `ModelConfig`/`compat`, Anthropic-compatible routes.
+  caller-gated discovery, Anthropic/OpenAI routes.
+- [Thinking and reasoning](../thinking-and-reasoning.md): portable `ThinkingLevel`
+  helpers and Kimi family mapping.
 - [Credentials and redaction](../credentials-and-redaction.md):
   `resolveCredentialValue`, `redactSecrets`.
-- [Provider layer](../provider-layer.md): `ProviderRequest.options` and usage
-  mapping.
+- [Provider caching](../provider-caching.md): explicit/implicit matrix.
 - [Provider conformance](../provider-conformance.md): network-free adapter tests.