@armadra/agent 0.5.0 → 0.6.0

package/docs/en/providers.md

@@ -0,0 +1,625 @@
+# Providers and models
+
+English · [简体中文](../providers.md)
+
+> Translated from the Chinese [docs/providers.md](../providers.md) as of commit `e3bde2e`. When the two differ, the
+> Chinese version is authoritative.
+
+Built-in providers, model references, API keys, custom providers and relays, the compat switches of each protocol, and caching. The design rationale is in [design.md](../design.md) §3 and §9.1 (Chinese).
+
+## Config directory
+
+Default `~/.config/ama/` (Windows `%APPDATA%\ama\`; `AMA_CONFIG_DIR` wins, then `XDG_CONFIG_HOME/ama`). Data (sessions, the models.dev refresh override) lives in another directory: `~/.local/share/ama/` (`AMA_DATA_DIR` / `XDG_DATA_HOME`).
+
+```
+~/.config/ama/                 0700
+├── config.json                user-level config: providers, channels, models, permissions, tools, cache… (edit directly)
+├── config.schema.json         JSON Schema of config.json (editor completion and validation; generated by ama, rewritten)
+├── auth.json                  API keys (0600; created only by ama auth set / ama providers add)
+├── config.json.bak            backup made before ama rewrites config.json
+├── hooks.json / trust.json / keybindings.json   (as needed)
+└── skills/ prompts/           (as needed)
+~/.local/share/ama/
+├── sessions/                  sessions
+└── models-dev.json            models.dev refresh override (written only by ama models refresh)
+```
+
+- `ama init`: creates the directory (0700) and fills in a missing `config.json` and `config.schema.json`, printing "created" or "already exists, left unchanged" for each. An existing `config.json` is never overwritten (not even with `--force`); `config.schema.json` is not a user file and every `init` rewrites it for the current version (and the current interface language); an empty `auth.json` is never created.
+- **Automatic initialization on first run**: commands that enter a conversation (interactive, `-p`, `--mode rpc`) and `ama providers add` silently create the directory with a minimal `config.json` and schema when the config directory does not exist (`AMA_NO_INIT=1` disables this; the SDK and tests never trigger it). Read-only subcommands (`config show` / `path`, `doctor`, `models list`, `providers list`, `auth list`, `sessions` …) never create or rewrite the config directory.
+- The minimal `config.json`:
+
+  ```json
+  {
+    "$schema": "./config.schema.json",
+    "version": 1,
+    "providers": {}
+  }
+  ```
+
+  No defaults are written (so default changes apply to old configs too, and `ama config show` shows the source as default), and no `defaultModel` either (see "Default model" below). `ama init` ends by printing next steps (`ama auth set` / `ama providers add` / `ama doctor`). Every key in `config.schema.json` carries a description and default (keys decided at runtime only describe the rule), visible on hover in editors.
+
+- `ama config path`: prints the config directory, the data directory and each file path (marking whether it exists); `ama config edit`: opens `config.json` with `$VISUAL` / `$EDITOR` (running `init` first if it does not exist), printing the path when no editor is available.
+
+Example: a three-channel relay + an image model + an override of a built-in provider.
+
+```json
+{
+  "$schema": "./config.schema.json",
+  "version": 1,
+  "defaultModel": "packy/kimi-k2.5",
+  "providers": {
+    "packy": {
+      "apiKey": "$PACKY_API_KEY",
+      "channels": {
+        "chat": { "api": "openai-completions", "baseUrl": "https://www.packyapi.com/v1" },
+        "responses": { "api": "openai-responses", "baseUrl": "https://www.packyapi.com/v1" },
+        "messages": { "api": "anthropic-messages", "baseUrl": "https://www.packyapi.com" }
+      },
+      "models": [
+        { "id": "kimi-k2.5", "channels": ["chat", "messages"] },
+        { "id": "grok-4.7", "channels": ["responses"] },
+        {
+          "id": "qwen3-vl-flash",
+          "input": ["text", "image"],
+          "modelsDev": "llmgateway/qwen3-vl-flash"
+        }
+      ]
+    },
+    "deepseek": { "modelOverrides": [{ "id": "deepseek-flash", "contextWindow": 131072 }] }
+  }
+}
+```
+
+## Built-in providers
+
+| id           | Channels (**bold** is the default)                                                    | Default address                                    | API key environment variables (in order)                      |
+| ------------ | ------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------- |
+| `anthropic`  | single channel messages                                                               | `https://api.anthropic.com`                        | `ANTHROPIC_API_KEY`, `AMA_API_KEY_ANTHROPIC`                  |
+| `openai`     | **responses**, chat                                                                   | `https://api.openai.com/v1`                        | `OPENAI_API_KEY`, `AMA_API_KEY_OPENAI`                        |
+| `google`     | single channel gemini                                                                 | `https://generativelanguage.googleapis.com/v1beta` | `GEMINI_API_KEY`, `GOOGLE_API_KEY`, `AMA_API_KEY_GOOGLE`      |
+| `deepseek`   | **chat**, messages (`/anthropic`)                                                     | `https://api.deepseek.com`                         | `DEEPSEEK_API_KEY`, `AMA_API_KEY_DEEPSEEK`                    |
+| `moonshot`   | **chat**, messages, responses, chat-intl, messages-intl (`.ai`)                       | `https://api.moonshot.cn/v1`                       | `MOONSHOT_API_KEY`, `KIMI_API_KEY`, `AMA_API_KEY_MOONSHOT`    |
+| `zhipu`      | **chat**, messages (`/api/anthropic`), chat-intl, messages-intl (`api.z.ai`)          | `https://open.bigmodel.cn/api/paas/v4`             | `ZHIPU_API_KEY`, `ZAI_API_KEY`, `AMA_API_KEY_ZHIPU`           |
+| `dashscope`  | **messages** (`/apps/anthropic`), responses, chat, messages-intl, chat-intl           | `https://dashscope.aliyuncs.com/apps/anthropic`    | `DASHSCOPE_API_KEY`, `QWEN_API_KEY`, `AMA_API_KEY_DASHSCOPE`  |
+| `openrouter` | single channel chat                                                                   | `https://openrouter.ai/api/v1`                     | `OPENROUTER_API_KEY`, `AMA_API_KEY_OPENROUTER`                |
+| `groq`       | single channel chat                                                                   | `https://api.groq.com/openai/v1`                   | `GROQ_API_KEY`, `AMA_API_KEY_GROQ`                            |
+| `xai`        | **responses**, chat                                                                   | `https://api.x.ai/v1`                              | `XAI_API_KEY`, `AMA_API_KEY_XAI`                              |
+| `mistral`    | single channel chat                                                                   | `https://api.mistral.ai/v1`                        | `MISTRAL_API_KEY`, `AMA_API_KEY_MISTRAL`                      |
+| `minimax`    | **messages**, responses (M3 only), chat, messages-intl, chat-intl (`api.minimax.io`)  | `https://api.minimax.cn/anthropic`                 | `MINIMAX_API_KEY`, `AMA_API_KEY_MINIMAX`                      |
+| `stepfun`    | **messages**, chat, responses (step-5-preview only), messages-intl, chat-intl (`.ai`) | `https://api.stepfun.com`                          | `STEPFUN_API_KEY`, `STEP_API_KEY`, `AMA_API_KEY_STEPFUN`      |
+| `volcengine` | **responses**, chat                                                                   | `https://ark.cn-beijing.volces.com/api/v3`         | `ARK_API_KEY`, `VOLCENGINE_API_KEY`, `AMA_API_KEY_VOLCENGINE` |
+| `tencent`    | **messages**, chat (`/v1`)                                                            | `https://tokenhub.tencentmaas.com`                 | `TOKENHUB_API_KEY`, `HUNYUAN_API_KEY`, `AMA_API_KEY_TENCENT`  |
+| `chatgpt`    | **siwc**, codex (default follows the signed-in flavor, see "ChatGPT login")           | `https://api.openai.com/v1`                        | none (`ama auth login chatgpt`)                               |
+| `ollama`     | single channel chat                                                                   | `http://127.0.0.1:11434/v1`                        | optional (`OLLAMA_API_KEY`)                                   |
+| `lmstudio`   | single channel chat                                                                   | `http://127.0.0.1:1234/v1`                         | optional                                                      |
+
+There is also the test provider `fake` (models `fake/echo`, `fake/reasoning`), see below.
+
+**Default protocol**: Messages / Responses first, Chat as fallback. Messages endpoints that honor explicit caching (Qwen, MiniMax M2.x, Tencent) and StepFun, which officially recommends Messages, default to messages; OpenAI, xAI and Volcengine Ark default to responses; DeepSeek, Zhipu and Kimi only have implicit caching and **stay on chat by default until their direct official endpoints pass the measurement gate** (see "Channel measurements"); switching is one `defaultChannel` line in `builtin.ts`.
+
+**Built-in channels** (the same mechanism as user [channels](#channels-one-provider-several-endpoints)):
+
+- `provider/model@channel` picks a channel, e.g. `deepseek/deepseek-v4-pro@messages`, `dashscope/qwen3.8-max@chat-intl`; catalog models mount every channel by default, and the catalog can restrict per model (MiniMax M2.x and StepFun step-3.x have no responses).
+- Changing the default: `"providers": { "deepseek": { "defaultChannel": "messages" } }`; or just write the protocol `"api": "anthropic-messages"` to pick the built-in channel with that protocol.
+- Changing one channel: `channels.<built-in channel name>` with only the fields to change (`headers` / `compat` merge one level deep, the rest overrides); channels with new names are appended after them, and catalog models can use them too.
+- **When the provider-level `baseUrl` is changed** (config, auth.json or `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL`) without writing your own `channels`, the built-in channels are dropped and it is handled as a single channel of "provider-level `api` + the new `baseUrl`", as before built-in channels existed: the fallback protocol is Chat (`api` can change it); **catalog models** of OpenAI / xAI / Volcengine Ark still use Responses on a relay, while ids outside the catalog (local services, the relay's own models) use Chat. A baseUrl on any built-in channel host (such as the international site) does not count as a relay.
+- Auth headers per channel: Anthropic-compatible endpoints default to `x-api-key`; the Messages channels of Kimi, MiniMax and StepFun use `Authorization: Bearer` per their docs.
+
+### Coding Plan style subscription endpoints
+
+The Coding Plan / Token Plan quotas of Volcengine Ark, Alibaba Bailian, Zhipu, Kimi, MiniMax, StepFun and others are restricted to coding tools; `ama -p` and RPC embedding are automated calls and risk being judged violations, so **they are not built-in channels**. Once you have confirmed the terms allow it, add a channel yourself (with the key on the channel):
+
+```json
+{
+  "providers": {
+    "volcengine": {
+      "channels": {
+        "coding": {
+          "api": "anthropic-messages",
+          "baseUrl": "https://ark.cn-beijing.volces.com/api/coding",
+          "apiKey": "$ARK_CODING_PLAN_KEY"
+        }
+      }
+    },
+    "zhipu": {
+      "channels": {
+        "coding": {
+          "api": "openai-completions",
+          "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4",
+          "apiKey": "$ZHIPU_CODING_PLAN_KEY"
+        }
+      }
+    },
+    "stepfun": {
+      "channels": {
+        "plan": {
+          "api": "anthropic-messages",
+          "baseUrl": "https://api.stepfun.com/step_plan",
+          "apiKey": "$STEP_PLAN_KEY",
+          "authHeader": "authorization-bearer"
+        }
+      }
+    }
+  }
+}
+```
+
+Then `--model volcengine/<model>@coding` (model ids of subscription endpoints follow each vendor's docs; add ids outside the catalog with `models[]` and `"channels": ["coding"]`).
+
+## ChatGPT login
+
+Drive ama with your own ChatGPT Plus / Pro subscription (built-in provider `chatgpt`, protocol openai-responses). **For your own personal use only**: do not let one login serve several people; embedding hosts (Armadra) must not turn it into a multi-user or hosted service either.
+
+```bash
+ama auth login chatgpt                 # default: official Sign in with ChatGPT (siwc), browser authorization
+ama auth login chatgpt --paste         # no browser (SSH / host): open the printed URL and paste the callback URL back
+ama auth status                        # flavor, plan, masked email, token lifetime; codex also shows quota
+ama --model chatgpt/<model>            # models available to the account: ama models discover chatgpt
+ama auth logout chatgpt                # siwc revokes the refresh token first, then deletes it locally
+```
+
+**Two paths** (`--flavor` or the user-level config `auth.chatgpt.flavor`; siwc by default):
+
+|                    | `siwc` (default, official)                                                                                                                                                                                              | `codex` (opt-in fallback)                                                                                                                                                       |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Login              | OpenAI's official dynamic registration: registers as `dynamic_agent_client` the first time and stores the issued client id in the entry; `agent_name_hint=ama`; the install id is kept in `<dataDir>/chatgpt-host.json` | Borrows the Codex CLI's public client; the first time it asks in the terminal to confirm "unofficial use, personal only, may change at any time" (non-TTY needs `--yes`)        |
+| Verification       | id_token signature checked against JWKS plus iss / aud / nonce / exp; the granted scope must include `chatgpt.tokens.use.direct`                                                                                        | Only decodes the id_token for the account id and plan                                                                                                                           |
+| Callback           | `http://127.0.0.1:1455/auth/callback`, any free port when 1455 is taken                                                                                                                                                 | 1455 → 1457, never takes over a busy port (suggests `--paste` / `--device`)                                                                                                     |
+| Device code        | none (use `--paste`)                                                                                                                                                                                                    | `--device` (may need enabling under ChatGPT → Settings → Security)                                                                                                              |
+| Inference endpoint | channel `siwc`: `https://api.openai.com/v1`                                                                                                                                                                             | channel `codex`: `https://chatgpt.com/backend-api/codex`, also sending `ChatGPT-Account-ID` and `originator` (default `codex_cli_rs`, changeable via `auth.chatgpt.originator`) |
+| Quota              | only known when exceeded (429); set a weekly cap for ama under ChatGPT → Settings → Usage → App limits                                                                                                                  | response headers, `codex.rate_limits` events, `ama auth status` queries `wham/usage`                                                                                            |
+| Logout             | calls `revocation_endpoint`, then deletes locally                                                                                                                                                                       | deletes locally only                                                                                                                                                            |
+
+The default channel of `chatgpt` is chosen at assembly time from the flavor of the auth.json entry; `provider/model@siwc|codex` can name it explicitly but must match the signed-in flavor (otherwise `chatgpt_flavor_mismatch`).
+
+**Credentials**: a `{ "type": "oauth", … }` entry in auth.json (file mode 0600); `ama auth list` only shows `oauth · <flavor> · <plan>`. The access token is refreshed automatically when less than 5 minutes remain or a request returns 401; several ama processes (several nodes on the canvas) share one auth.json, and refreshes are serialized through `auth.json.lock` (re-read after taking the lock; if another process already refreshed, its token is used), so refresh-token rotation never knocks another process out. When refreshing fails permanently the entry is marked `needsLogin` (tokens are not deleted), requests report `auth_expired`, and you sign in again with `ama auth login chatgpt` as prompted. Raw tokens, codes and id_tokens never reach logs, sessions, events or errors. Logins of other applications (Codex CLI and others) are never read or imported.
+
+**Request body**: both backends force `store:false`, `stream:true` and an `input` array, and drop unsupported fields (siwc: 15 including `max_output_tokens`, `temperature`, `top_p`, `metadata`, `user`, `truncation`, `prompt_cache_retention`; codex: `max_output_tokens`, `temperature`, `top_p`, `prompt_cache_retention`, `prompt_cache_options`). Both send `prompt_cache_key = session id`, and `cacheRetention: "long"` is lowered to short automatically. If siwc rejects a field with `subscription_sharing_unsupported_capability`, it is dropped and the request retried once (remembered for the process); if codex reports `Instructions are not valid`, this session moves the system prompt into a leading developer message (the prefix stays stable). With compat `toolsInNamespace: true` tools go into an `additional_tools` input item (shape still to be verified with a real account).
+
+**Error codes** (error messages start with the code; hosts decide by code):
+
+| Code             | Source                                                                                                       | Handling                                                  |
+| ---------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
+| `quota_exceeded` | siwc 429 `subscription_sharing_usage_limit_exceeded`; codex 429 `usage_limit_reached` / `usage_not_included` | no retry; carries the reset time and emits `quota_update` |
+| `auth_expired`   | a 401 still failing after one refresh, a permanently failed refresh, an entry marked `needsLogin`            | no retry; run `ama auth login chatgpt` again              |
+| `not_eligible`   | siwc 403 `subscription_sharing_user_not_eligible`                                                            | no retry, no re-login                                     |
+| (as is)          | 503 and similar                                                                                              | the session layer's existing backoff retries              |
+
+**Usage**: subscription requests record `usage.cost = 0` with `billing: "subscription"`; `/session` lists "subscription usage" separately (requests, tokens, cache hit rate, no USD conversion) together with the latest quota; the `quota_update` event is forwarded as is over RPC and has the same name among host events.
+
+**Overrides** (for tests or a future own client): `auth.chatgpt.clientId` / `issuer` / `originator` / `redirectPorts` (user level and profile only), environment variables `AMA_CHATGPT_CLIENT_ID`, `AMA_CHATGPT_ISSUER`, `AMA_CHATGPT_BASE_URL` (changes the address of the current flavor's channel).
+
+**Embedding hosts**: with a profile ama never starts an interactive login; when `chatgpt` is used and the login has expired the request reports `auth_expired`, and the host guides the user to run `ama auth login chatgpt --paste` in a terminal. Hosts never read, store or forward tokens; they only consume `quota_update` and `auth_expired` / `quota_exceeded`.
+
+**Real-account check** (not run in CI): sign in first, then `AMA_E2E_CHATGPT=1 pnpm vitest run src/auth/chatgpt/chatgpt.e2e.test.ts` (optionally `AMA_E2E_CHATGPT_MODEL=<slug>`); it prints the flavor, the model list, the stop reason and the quota, never tokens.
+
+## Model references
+
+`provider/model-id`, e.g. `deepseek/deepseek-v4-pro`, `openrouter/anthropic/claude-sonnet-5.5`. Without a provider prefix, the id must match uniquely across all catalogs; when several providers share the name, only providers with a configured key are considered, and if it is still ambiguous an error lists the candidates. Providers with an empty model table (ollama, lmstudio, custom providers without `models`) and built-in providers whose baseUrl points to a non-official host (see "Connecting relays") accept any model id.
+
+## API key lookup order
+
+1. `--api-key` (only for the provider given by `--model`)
+2. `--auth-file` / the profile's `authFile`
+3. `~/.config/ama/auth.json` (a warning when its permission is not 0600, but it is still used)
+4. `providers.<id>.apiKey` in `config.json`: supports `$ENV`, `${ENV}`, `!command`; `$$` means a literal `$`
+5. Environment variables (in the order of the table above; skipped with the profile's `authEnv: false`)
+6. Local services (`requiresApiKey: false`) work without a key
+
+An `apiKey` in `auth.json` starting with `!` runs a command for the value (10-second timeout; empty output or a non-zero exit counts as not configured).
+
+## Custom providers
+
+```json
+{
+  "providers": {
+    "my-proxy": {
+      "baseUrl": "https://proxy.example/v1",
+      "apiKey": "$MY_PROXY_KEY",
+      "models": [{ "id": "gpt-x", "contextWindow": 128000, "maxTokens": 16384, "reasoning": true }],
+      "compat": { "maxTokensField": "max_tokens" }
+    },
+    "deepseek": { "modelOverrides": [{ "id": "deepseek-flash", "contextWindow": 131072 }] }
+  }
+}
+```
+
+- `api` defaults to `openai-completions`; custom models default to `maxTokens: 8192`, `reasoning: false`, `input: ["text"]`; `contextWindow` is not guessed (automatic compaction is off by default).
+- `models[]` entries with the same id replace the whole model, new ids are appended; `modelOverrides[]` only changes metadata of existing models.
+
+## Connecting relays
+
+Under one relay, different models often support different protocols (some all three, some only Chat and Messages, some only Responses). One provider is enough: put the protocol on the model.
+
+```sh
+export PACKY_API_KEY=sk-...
+```
+
+```json
+{
+  "providers": {
+    "packy": {
+      "baseUrl": "https://proxy.example/v1",
+      "apiKey": "$PACKY_API_KEY",
+      "models": [
+        { "id": "deepseek-v4-flash" },
+        { "id": "grok-4.7", "api": "openai-responses" },
+        { "id": "MiniMax-M2.7", "api": "anthropic-messages" }
+      ]
+    }
+  }
+}
+```
+
+- A model's `api` defaults to the provider's (here `openai-completions`); `modelOverrides[]` can change `api` too.
+- The three protocols share one `baseUrl`: Completions / Responses append `/chat/completions`, `/responses`; Messages appends `/messages` when the baseUrl ends with `/v1`, otherwise `/v1/messages`.
+- Don't want to write `models` by hand: `ama models discover packy` lists the relay's models (`GET {baseUrl}/models`); `--probe` tries minimal requests per model with the provider's protocol, completions, responses and messages in turn and records the first that succeeds (at most 3 per model; `--limit` caps the number of probed models, default 30; an estimate is printed first; models are probed concurrently with the same rules as `providers add --probe` below); `--write` merges the result into the user-level `config.json` (existing ids are not overwritten; only `id` and an `api` differing from the provider's are written; the original is backed up as `config.json.bak`). Context window and other metadata are filled from the models.dev snapshot at runtime (see "Model metadata" below); entries without a match have no `contextWindow`, so automatic compaction is off for them; add it by hand when needed.
+
+```sh
+ama models discover packy --probe --write --limit 8
+ama -p "hi" --model packy/grok-4.7
+```
+
+Zero config: the built-in `openai` / `anthropic` recognize `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL` (the common convention of the OpenAI SDK and Claude Code), at lower priority than `baseUrl` in config and auth.json, and not read with the profile's `authEnv: false`. When the baseUrl is not an official host, model ids outside the catalog are accepted too, and compat uses conservative defaults (no `prompt_cache_key`). The "Providers" section of `ama config show` and `ama doctor` mark which variable the baseUrl came from; the default model picked by zero config comes from the official catalog and may not exist on the relay, so specify one with `--model` or `defaultModel`.
+
+### Default model
+
+Without `--model`, a resumed session's model or `defaultModel`, ama takes the first provider in provider order (built-ins first, then custom providers from config) that has a key (or a reachable local service), then picks among its models:
+
+- **Built-in providers**: the first catalog entry (catalogs are ordered by recommendation);
+- **Custom providers** (relays, whose model table follows the upstream `/models` order): among models with a models.dev price (input price > 0), tool calling and a context window ≥ 64k, the one with the **lowest input price**; ties go to the larger context, then to the earlier position in the list; only when none qualifies does it fall back to the first entry.
+
+When there is no `defaultModel` yet, `ama providers add` picks one with the same rules and writes it to `defaultModel` (after probing, only among models that passed), stating in the summary which one and why; an existing `defaultModel` is left alone. The "Model" line of `ama config show` and `ama doctor` explains the reason the same way. When no model is usable at all, startup lists the key environment variable names, `ama auth set` and `ama providers add`.
+
+```sh
+OPENAI_BASE_URL=https://proxy.example/v1 OPENAI_API_KEY=$PACKY_API_KEY ama -p "hi" --model openai/qwen3.8-flash
+```
+
+### Channels: one provider, several endpoints
+
+A relay often offers Chat Completions (`/v1/chat/completions`), Responses (`/v1/responses`) and Anthropic Messages (`/v1/messages`) at the same time, with each model available on only some of them. A **channel** is "protocol + address (+ optional key / headers / compat)"; a provider can have several channels, and each model declares which channels it is mounted on:
+
+```json
+{
+  "providers": {
+    "packy": {
+      "name": "Packy",
+      "apiKey": "$PACKY_API_KEY",
+      "channels": {
+        "chat": { "api": "openai-completions", "baseUrl": "https://www.packyapi.com/v1" },
+        "responses": { "api": "openai-responses", "baseUrl": "https://www.packyapi.com/v1" },
+        "messages": { "api": "anthropic-messages", "baseUrl": "https://www.packyapi.com" }
+      },
+      "defaultChannel": "chat",
+      "models": [
+        { "id": "kimi-k2.5", "channels": ["chat", "messages"] },
+        { "id": "grok-4.7", "channels": ["responses"] },
+        { "id": "deepseek-v4-flash", "channels": ["chat", "responses", "messages"] },
+        { "id": "glm-5" }
+      ]
+    }
+  }
+}
+```
+
+- **Channel fields**: `api` and `baseUrl` are required; `apiKey` (same syntax as at provider level, `$ENV` / `!command` / literal; `"<provider>@<channel>"` entries in auth.json work too), `headers`, `compat` and `authHeader` are optional and inherit from the provider by default. Channel names match `[A-Za-z0-9][A-Za-z0-9_-]*`, without `/` or `@`.
+- **Model mounting**: `models[].channels` lists the usable channels, the first being preferred; without it → `defaultChannel` (by default the first key of `channels`). Referencing a channel that does not exist → a config validation error with the path.
+- **Model references**: `provider/model` uses the preferred channel; `provider/model@channel` picks one explicitly (the same in `--model`, `defaultModel`, `/model`, the SDK and RPC `set_model`). A channel not in the model's `channels` → an error listing the available `provider/model@channel`. When the part after `@` is not a channel name of that provider, the whole string is still treated as the model id (compatible with models whose id contains `@`).
+- **Backward compatibility**: providers without `channels` (custom providers and single-protocol built-in providers; built-in channels of multi-protocol providers are described in "Built-in providers") are handled as a single channel: the provider-level `api` + `baseUrl` is the implicit `default` channel; model-level `api` / `baseUrl` still work and override the selected channel (equivalent to an anonymous channel). Existing configs need no changes. Once `channels` is written, the provider-level `api` / `baseUrl` no longer form a channel by themselves.
+- **Runtime**: the selected model carries the channel's protocol, address, key, headers and compat; session records (`model_change`) and `ModelRef` carry the `channel`; the cache endpoint key (three states, misses, granularity inference) is `provider|host|model@channel`, so different channels of the same model are tracked separately. Prices and models.dev metadata are shared per model.
+
+### One-step setup: `ama providers`
+
+With just a baseUrl and a key, one command creates the provider, lists the models and fills in metadata:
+
+```sh
+ama providers add packy --base-url https://www.packyapi.com/v1 --key-env PACKY_API_KEY --probe --limit 8 --yes
+```
+
+```
+ama providers add <id> --base-url <url> [--channel <name>=<api>@<baseUrl> …] [--api <api>|auto]
+                       [--key-env <VAR>] [--probe] [--limit N] [--probe-models a,b,…]
+                       [--max-requests N] [--concurrency N] [--probe-timeout ms]
+                       [--prefer chat,responses,messages] [--include-no-tools] [--yes]
+ama providers list
+ama providers channels <id>
+ama providers remove <id>
+ama providers refresh <id> [--probe …]
+```
+
+- **Key**: read from stdin by default (not echoed in a terminal, never on the command line or in shell history) and stored in `auth.json` (0600); with `--key-env VAR` stdin is not read and `config.json` gets `"apiKey": "$VAR"`. If the provider already has a key, nothing is asked.
+- **Candidate channels**: with `--channel` (repeatable) only those are used; otherwise three are derived from `--base-url`: `chat` (openai-completions, baseUrl as is), `responses` (openai-responses, same), `messages` (anthropic-messages, the host root without a trailing `/v1`); `--api <api>` keeps only the matching one.
+- **Model list**: `GET {baseUrl}/models` (the address of the first OpenAI-family channel; with only a Messages channel it is `/v1/models`, tried with `Authorization: Bearer` first and `x-api-key` on 401 / 403, since relays were measured to accept only the former). new-api style relays give `supported_endpoint_types` (`openai` / `openai-response` / `anthropic`) on entries, used to mount models on the matching channels; without hints a model is mounted on the first candidate channel; with hints but no supporting candidate channel (such as grok when only a messages channel is configured) → not written.
+- **`--probe`**: for the selected models (those listed by `--probe-models`, by default the first `--limit` ids in case-insensitive alphabetical order, default 30) one minimal request is sent per channel (only the hinted channels when hints exist), and **every channel that passes is written into the model's `channels`**, ordered by `--prefer` (default chat, responses, messages); models where everything fails are not written; unprobed models are written per hints and marked "not probed" in the table. The request count and an estimated duration are printed first, and beyond `--max-requests` (default 60) the model count is cut.
+  - **Verdict**: a successful HTTP response whose stream yields a first content event (text / thinking / tool call) counts as usable and is disconnected immediately, without waiting for a reasoning model to finish thinking; when only the start of the stream arrived without content, it waits 1 more second and counts as usable if no error appears (so relays that answer 200 first and report errors inside the stream are not misjudged). HTTP errors, stream errors and timeouts (`--probe-timeout`, default 15000 ms) count as unusable, with the reason recorded.
+  - **Concurrency**: at most `--concurrency` "model × channel" requests in flight (1–16, default 6); results are printed in model and channel order, a terminal shows a single refreshing progress line, and the total time is printed at the end.
+  - **Rate limits**: 401 / 403 stop immediately; on 429 concurrency is halved and the request retried once after 2 s, stopping if it is still 429.
+- **Channel pruning**: before writing, candidate channels with no mounted model are removed; `defaultChannel` is the first remaining one (by `--prefer`).
+- **Writing**: `providers.<id>` in the user-level `config.json` (backed up as `config.json.bak` first). Model entries only get `id` and `channels`; context, output, images, reasoning and prices are **not written to the config** but filled from the models.dev snapshot at runtime (next section), so `refresh` never overwrites hand-edited fields and hand-written values always win. Models that models.dev marks as lacking tool calling are not written by default (an agent cannot work without tool calls); `--include-no-tools` writes them anyway. Running `add` again on an existing provider only appends new channels and new models; existing channel definitions and model entries are left byte-for-byte unchanged.
+- **Confirmation**: a summary is printed before writing the config, with one y/N question in a terminal; non-TTY use requires `--yes` (otherwise exit 2).
+- The printed table: id, channels, context, output, images, reasoning, tool calling, price (the vendor's price from models.dev, $/M input / output; the relay's actual price may differ), match method.
+- `list`: every provider (those in config.json and built-ins with a key) → channels (protocol, address, key source: auth.json / `$VAR` / literal / none; the key is never shown) → model count. `channels <id>`: each channel's protocol, address and mounted model count. `remove`: deletes `providers.<id>` (with a backup) and the provider's entries in auth.json. `refresh`: re-fetches `/models` (models.dev from the local snapshot) and only appends new models (probing like add with `--probe`), leaving existing entries alone; ids removed upstream are only reported, never deleted.
+
+Measured (2026-10-02, a relay offering all three endpoint types, 22 models, 29 requests in total):
+
+- `providers add --probe --probe-models kimi-k2.5,grok-4.7,deepseek-v4-flash` took 8 requests (1 list + 7 probes): kimi-k2.5 → chat, messages (Responses failed); grok-4.7 → responses; deepseek-v4-flash returned `incomplete_details.reason: "length"` on Responses (the relay omits `max_output_tokens` when forwarding to DeepSeek), which is handled as output truncation, so all three endpoints work.
+- models.dev matched 22 / 22: 19 vendor entries (including `qwen3.8-max-0902`, matched to `alibaba/qwen3.8-max` after removing the date suffix), 2 by majority (kimi-k2.5: the vendor entry `moonshotai/kimi-k2.5` is not in the database, so the majority of 11 entries with the same canonical id gives 262k / images; qwen3-coder-next), 1 unique entry (qwen3-vl-flash).
+- `-p` worked through both the chat and `@messages` channels; with `--image`, a four-color square picture was answered correctly as red / green / blue / yellow on kimi-k2.5 (chat, messages) and qwen3-vl-flash; for glm-5 (text-only per models.dev) it exited with 2 without sending a request.
+- A second provider with only a messages channel: 19 models mounted, the 3 Responses-only grok models not written; using a shared model name without a prefix reports the ambiguity and lists both providers.
+
+### Model metadata: models.dev
+
+[models.dev](https://models.dev) aggregates model parameters from over two hundred providers (`https://models.dev/api.json`, about 5 MB, MIT licensed; the notice is in `THIRD_PARTY_NOTICES.md` at the repository root). ama **ships a trimmed snapshot** for the major vendors and uses it to fill in numeric facts such as context window, output limit, input modalities, reasoning and prices for built-in catalogs and custom models. **No network at startup or runtime.**
+
+- **Snapshot**: `src/ai/providers/models-dev/<provider>.json`, one file per vendor, with the list in `_providers.json` in the same directory (22: anthropic, openai, google, xai, deepseek, moonshotai / moonshotai-cn, zhipuai / zai, alibaba / alibaba-cn, minimax / minimax-cn, stepfun / stepfun-ai, volcengine, tencent-tokenhub, mistral, meta, xiaomi, groq, plus openrouter models whose vendor prefix is on an allowlist). `scripts/update-models-dev.mjs` (zero dependencies) fetches, filters (dropping `deprecated` entries, entries whose output lacks text, a context of 0 and `tool_call: false`), trims fields (name, family, knowledge, release_date, reasoning, modalities.input, limit.context / input / output, cost including `context_over_200k` and per-context `tiers`, interleaved, beta status, canonical_model_id) and writes them sorted by key, then generates `models-dev-data.ts`, which is inlined into the bundle; unchanged content stays byte-identical (`fetchedAt` in `_meta.json` only changes with the sha256). To control size (inlined data ≤ 200 KB, guarded by a test), `last_updated` and `reasoning_options` are not included.
+- **Weekly refresh**: `.github/workflows/models-dev.yml` runs the script every Monday at 03:17 UTC (and on manual `workflow_dispatch`), automatically removes catalog overrides identical to the new snapshot, and only opens / updates a PR on the fixed branch `chore/models-dev-refresh` when something changed (the summary lists additions, removals and context / output / price changes; `needs-review` is added when more than 30% is removed). The PR is created with the repository secret `MODELS_DEV_PR_TOKEN` (a GitHub App token or a fine-grained PAT with `contents` + `pull-requests` write access) so that CI triggers; without that secret the workflow runs `pnpm run ci` itself first, then opens the PR with the default token and states the result in the description. A person merges it.
+- **`ama models refresh [--provider <id>[,<id>…]]`**: explicitly fetches the latest `api.json` over the network, trims it with the same list, writes `models-dev.json` into the data directory (default `~/.local/share/ama/`) and prints additions / upstream removals / price changes. From then on the index = the built-in snapshot ⊕ this override: the override applies only when its `fetchedAt` is later than the snapshot's (so an old override expires automatically once an ama upgrade brings a newer snapshot); for the same `provider/model` the override wins, and entries removed upstream keep the snapshot's values. `refresh-catalog` is the old name. `AMA_MODELS_DEV_URL` changes the refresh source. The full cache written by older ama versions (version 1) is no longer read. `ama providers add|refresh` and `ama models discover` only use the local index and no longer fetch models.dev (their `/models` requests are unchanged).
+- **Built-in catalogs (`catalog/*.json`) only hold overrides**: a file-level `"modelsDev": "<snapshot provider id>"` (local services write `false`); entries inherit name, reasoning, contextWindow, maxTokens, input, cost, family, knowledge, releaseDate, inputLimit and status from the snapshot via `<modelsDev>/<id>`, and the catalog only writes ama-specific fields (`api`, `thinkingLevelMap`, `promptCache`, `compat`) plus values deliberately different from the snapshot (such as openai's 272k window or deepseek's prices); `cost` may list only the keys to change. When the id differs from the snapshot the entry writes `"modelsDev": "provider/model"`, and `false` to inherit nothing. Models missing from the snapshot (deprecated etc.) get complete entries. `catalog.test.ts` reports fields equal to the snapshot's value as redundant; `UPDATE_CATALOG=1 pnpm vitest run src/ai/providers/catalog.test.ts` removes them automatically and regenerates `catalog-data.ts` (run prettier afterwards); to pin a value equal to the snapshot on purpose, write `"_reason": "…"` on the entry (a comment ignored at runtime that exempts the entry from the redundancy check). The inherited mapping for catalogs differs slightly from custom models: `maxTokens` is not capped (it is `min(limit.output, contextWindow)`), and missing cache prices count as 0.
+- **Priority**: user config (fields written in `models[]` / `modelOverrides[]`) > built-in catalog (snapshot ⊕ catalog overrides) > the models.dev index > custom defaults (`maxTokens: 8192`, `input: ["text"]`, `reasoning: false`, no guessed `contextWindow`). `ama models list` and `ama config show` mark where each field comes from (`config` / catalog / `models.dev` / default; fields a built-in catalog inherits from the snapshot are marked `models.dev`).
+- **Field mapping** (custom models): `contextWindow = limit.context`; `maxTokens = min(limit.output, 65536, contextWindow)`. `maxTokens` is sent as `max_tokens` on every request, and models.dev gives the vendor's limit (quite a few models list 1M, equal to their context); relays that switched upstreams often reject very large values, the thinking budget of the Anthropic protocol is also derived from it, and 64k is plenty for a coding agent's single-turn output; write it in the config when you need more. `input` becomes `["text","image"]` or `["text"]` depending on whether `modalities.input` contains `image`; `reasoning`; `cost` takes `input` / `output` / `cache_read` / `cache_write` ($/M), using the input price when cache prices are missing (no discount assumed, so warming economics err on the conservative side); `cost.tiers` takes models.dev's per-context tiers, folding to a single 200k tier when only `context_over_200k` exists; plus `family`, `knowledge`, `releaseDate`, `inputLimit` (when it differs from the context) and `status: "beta"`.
+- **Matching rules** (the same id often appears under several resellers with differing values):
+  1. `"modelsDev": "provider/model"` on the model → use that entry directly (`false` disables enrichment);
+  2. an id of the form `vendor/model` that exists exactly as a `provider/model` in the index → use it;
+  3. find all entries with the same id case-insensitively; among those with a `canonical_model_id`, take the one pointing to a model named like the id (otherwise the most voted one); if that can be found under the vendor's own provider → use the vendor entry;
+  4. otherwise prefer vendor providers among the entries (with the same canonical id): anthropic, openai, google, deepseek, moonshotai(-cn), zhipuai, zai, alibaba(-cn), xai, mistral, minimax(-cn), meta, llama, cohere, xiaomi, stepfun(-ai), volcengine, tencent-tokenhub and so on (models.dev has no provider id like `qwen`; Qwen lives under `alibaba`);
+  5. still several entries → take the majority by (context, output, images), with a warning when values disagree; a single entry is used as is;
+  6. when no entry has the same name, try normalized ids in turn: strip the `vendor/` prefix, strip suffixes like `:free`, strip `-latest`, strip date suffixes (`-0902`, `-20250514`, `-2025-05-14`);
+  7. nothing found → "unmatched", keeping the custom defaults (no guessed `contextWindow`, automatic compaction off). The snapshot only covers major vendors, so reseller-specific ids may not match; write `modelsDev` on the model to point at an included entry.
+
+### Image input
+
+- All four protocols put images into user messages: Chat Completions `image_url` (data URL), Responses `input_image`, Anthropic `image` (base64 source), Gemini `inlineData`; images in tool results are mapped the same way.
+- Entry points: `ama -p "describe this picture" --image a.png --image b.jpg`; in the interactive and line UIs write `@image-path`, or paste / drop an image file path (words in the input ending in `.png` / `.jpg` / `.jpeg` / `.gif` / `.webp` whose file exists); in the interactive UI `Ctrl+V` or `/paste` saves the clipboard image to a file and inserts `@<path>` at the cursor (see "Clipboard images" below and [tui.md](tui.md) "Clipboard images"). Images from `--image`, `@image` and pasting are all resized per `images.resize`.
+- MIME detection is shared with the `read` tool (PNG / JPEG / GIF / WebP recognized by file header; when the extension disagrees, the header wins), as is the size limit. The limit is measured **after base64** (`ceil(bytes/3)*4`) and tiered by the current model's endpoint: official Anthropic (`api.anthropic.com`) 10 MB, official Gemini and OpenAI 20 MB, relays (built-in providers with a changed baseUrl) and other hosts 5 MB; either side over 8000 px is refused.
+- Resizing (`images.resize`, default `auto`): when over the limit, `sips` (macOS) and then `magick` / `convert` (ImageMagick) are tried to shrink it within the limit before attaching; without a tool, or with `off`, it is refused per the rules above with a hint. Zero dependencies, no built-in image decoding.
+- The per-request image budget depends on the protocol: `anthropic-messages` 32 MB, others 20 MB (after base64). Earlier images are resent every turn; over budget, images are replaced with the placeholder text `[earlier image omitted to fit request size]` starting from the oldest, in one go down to below 60% of the budget; old images above the current endpoint's per-image limit (after switching model / channel) are replaced directly; with more than 20 images in one request and some longer side > 2000 px, the oldest keep being dropped until at most 20 remain. The newest message with images is never degraded. Degradation is written into the session as `context_edit{reason:"image_budget"}`, so the prefix is stable afterwards, and cache stats treat that request as a reset point.
+- Clipboard images (`Ctrl+V` / `/paste` in the interactive UI): `pasteClipboardImage` tries `osascript` / `pngpaste` (macOS), `wl-paste` (Wayland) / `xclip` (X11) and PowerShell `Get-Clipboard -Format Image` (Windows), writing to `<data dir>/clipboard/<timestamp>.png`; `ama sessions prune` cleans files there older than 7 days.
+- When the model's `input` lacks `image`, the request is refused up front with a hint to switch models (`-p` exits with 2, the UI shows an error, nothing is sent); when the `read` tool reads an image it only returns the path, dimensions and a note that the current model does not accept images.
+
+Once connected: `ama models check packy/<id>` sends one minimal request to confirm connectivity; `ama models cache-probe packy/<id>` shows whether the endpoint reports cache usage (see "Caching" below); for models on a relay that do not report it, set `compat.cacheReporting: "silent"` as suggested, and the status bar shows "not reported" instead of 0%.
+
+## compat for the OpenAI-compatible line
+
+Inference order: conservative defaults ← inference table (provider id, then baseUrl substring) ← `provider.compat` ← `model.compat`.
+
+| Switch                                        | Effect                                                                                                                   |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `maxTokensField`                              | `max_tokens` or `max_completion_tokens`                                                                                  |
+| `supportsDeveloperRole`                       | Use the `developer` role for the system prompt of reasoning models                                                       |
+| `supportsUsageInStreaming`                    | Send `stream_options.include_usage`                                                                                      |
+| `supportsFinishReason`                        | When false, ignore finish_reason and infer the stop reason from content                                                  |
+| `supportsReasoningEffort`                     | Send `reasoning_effort`                                                                                                  |
+| `thinkingFormat`                              | `openai` / `openrouter` (`reasoning.effort`) / `deepseek`, `zai` (`thinking.type`) / `qwen` (`enable_thinking`) / `none` |
+| `thinkingTokenBudgetField`                    | Name of the budget field (DashScope: `thinking_budget`)                                                                  |
+| `requiresReasoningContentOnAssistantMessages` | Earlier assistant messages of reasoning models carry `reasoning_content` (DeepSeek)                                      |
+| `requiresToolResultName`                      | Tool result messages carry `name` (Mistral)                                                                              |
+| `requiresAssistantAfterToolResult`            | Insert an assistant message when a user message directly follows a tool result                                           |
+| `supportsMidConvoSystemMessages`              | Later system prompt patches are inserted back as system messages at their position                                       |
+| `cacheControlFormat`                          | `anthropic`: put `cache_control` on the system prompt, the last tool and the last user/tool message                      |
+| `supportsStrictTools`                         | Send `strict: true` for strictly compatible tool schemas                                                                 |
+| `supportsStore`                               | Send `store: false`                                                                                                      |
+
+compat only records **verified** differences; please attach a docs link or a real sample when adding entries.
+
+## compat for Anthropic Messages
+
+Defaults are inferred from the request host (`src/ai/apis/anthropic-compat.ts`); `providers.<id>.compat` and channel- or model-level `compat` override field by field:
+
+| Switch                        | Effect                                                                    | Default                                                                                                                                       |
+| ----------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sendInterleavedThinkingBeta` | Send the `interleaved-thinking` beta header for budgeted thinking + tools | On for `api.anthropic.com`; off for DeepSeek, Zhipu, Kimi, Qwen, MiniMax, StepFun, Tencent, Volcengine; other hosts only for `claude*` models |
+| `sendCacheControl`            | Place `cache_control` breakpoints                                         | On; off for DeepSeek (documented as ignored)                                                                                                  |
+| `adaptiveThinking`            | `{type:"adaptive"}` + `output_config.effort`                              | Off; enabled per entry in the catalog for new official models                                                                                 |
+| `supportsCacheControlOnTools` | Breakpoint on the last tool definition                                    | On                                                                                                                                            |
+| `maxCacheBreakpoints`         | Maximum number of breakpoints                                             | 4                                                                                                                                             |
+
+OpenRouter's Messages endpoint only gives cache usage in `message_delta`; parsing already merges non-empty fields, so no switch is needed.
+
+## compat for Responses and Gemini
+
+| Protocol               | Switch                          | Effect                                                                                                                                      | Default                                                   |
+| ---------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `openai-responses`     | `supportsReasoningSummary`      | `reasoning.summary: "auto"` (thinking blocks get text)                                                                                      | On for official OpenAI; off for xAI and others            |
+| `openai-responses`     | `supportsStore`                 | Send `store: false`; reasoning models also need `include: ["reasoning.encrypted_content"]` to replay encrypted reasoning items across turns | On for official OpenAI and xAI; off otherwise             |
+| `google-generative-ai` | `supportsThoughtSignature`      | Replay `thoughtSignature` for the same model (thinking, text, functionCall parts)                                                           | On                                                        |
+| `google-generative-ai` | `supportsFunctionResponseParts` | Put images of tool results into `functionResponse.parts`; when off, a separate user turn is started                                         | On from Gemini 3; off for Gemini 2.x and non-Gemini names |
+
+- Responses: the system prompt goes into `instructions`; cache fields are in "Caching" below; thinking off sends `reasoning.effort` only when the mapping table gives a string for off (such as `"none"`), otherwise the server default applies.
+- Gemini: a mapped string value (or the Gemini 3 family without a mapping) → discrete `thinkingLevel` (`LOW` / `HIGH`…); a numeric mapping or other models → `thinkingBudget` (`-1` dynamic); off → `thinkingBudget: 0`. Implicit caching works automatically, and `cachedContentTokenCount` counts towards `cacheRead`.
+
+## Caching
+
+Most usage in long tasks is cache reads: once the prefix changes, every later request re-reads it at full price. ama handles caching in three layers: the **protocol layer** places breakpoints, sends cache keys and retention tiers the way each provider expects, and marks whether a response had cache fields; the **session layer** records each request's prefix fingerprint, detects misses, decides whether the endpoint reports cache usage and warms the cache during long tool runs; the **display layer** is the status bar, `/session`, RPC stats and `ama models cache-probe` (how to read the interface is in [tui.md](tui.md) "Cache and context").
+
+Prefix stability is guaranteed by assembly: the system prompt sections have a fixed order without timestamps, tools are sorted by name, and mid-session changes are only appended at the end as system patches ([session-format.md](../session-format.md), Chinese).
+
+### Request fields
+
+| Protocol                                  | Field                                                                                                   | Condition                                                                                                    |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `anthropic-messages`                      | Three `cache_control` breakpoints (last user message, end of system, last tool)                         | `cacheRetention` is not `none`                                                                               |
+| `anthropic-messages`                      | `ttl: "1h"`                                                                                             | `long` and `supportsLongCacheRetention`; otherwise 5m                                                        |
+| `openai-completions`                      | `prompt_cache_key = sessionId` (cut to 64 characters)                                                   | `sendPromptCacheKey` and not `none`                                                                          |
+| `openai-completions`                      | `prompt_cache_retention: "24h"`                                                                         | `long` and `supportsLongCacheRetention`                                                                      |
+| `openai-completions` (`anthropic/*` etc.) | `cache_control` (`cacheControlFormat: "anthropic"`), with `ttl: "1h"` for `long`                        | Same as Anthropic                                                                                            |
+| `openai-responses`                        | `prompt_cache_key`                                                                                      | Same as Completions                                                                                          |
+| `openai-responses`                        | `prompt_cache_options: { ttl: "30m" }`, otherwise `prompt_cache_retention: "24h"`                       | `long` and `supportsExplicitPromptCacheMode`; otherwise `long` and `supportsLongCacheRetention`              |
+| Both OpenAI lines                         | Affinity header `x-session-affinity` + a per-request `x-client-request-id` (OpenRouter: `x-session-id`) | `sendSessionAffinityHeaders` and a sessionId                                                                 |
+| `google-generative-ai`                    | None (implicit caching)                                                                                 | —                                                                                                            |
+| All                                       | `toolChoice: "none"` → each provider's way of forbidding tool calls                                     | When the request has tools (summary continuation does **not** use it, see "Compaction summary continuation") |
+
+Retention tier: `StreamOptions.cacheRetention` wins; otherwise `AMA_CACHE_RETENTION=none|short|long` is read; with neither it is `short`. The Anthropic request body gets a final TTL order check (if a 1h appears after a 5m across tools → system → messages, everything falls back to 5m). When the Anthropic `baseUrl` ends with `/v1`, requests go to `{baseUrl}/messages`, never `/v1/v1/messages`.
+
+### Compat switches (`providers.<id>.compat` or model-level `compat`)
+
+| Switch                            | Effect                                                                     | Default                                                                                                     |
+| --------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `sendPromptCacheKey`              | Send `prompt_cache_key`                                                    | On for the official hosts of OpenAI, xAI, Mistral, Kimi (`.cn` / `.ai`) and Tencent TokenHub; off otherwise |
+| `sendSessionAffinityHeaders`      | Send affinity headers                                                      | Off (including OpenRouter, not measured)                                                                    |
+| `supportsLongCacheRetention`      | `long` available (Anthropic 1h, OpenAI 24h); otherwise falls back to short | On for `api.openai.com` / `api.anthropic.com` / `tokenhub.tencentmaas.com`                                  |
+| `supportsExplicitPromptCacheMode` | Responses' `prompt_cache_options` (30m)                                    | Off                                                                                                         |
+| `cacheReporting`                  | `auto` / `silent` / `reported`: force the "reports cache" state            | `auto`                                                                                                      |
+
+Inference only looks at the final request's host name (`HOST_CACHE_CAPABILITIES` in `cache-params.ts`, listing only hosts whose official docs state support), never at the provider id: pointing `openai` at a relay with `OPENAI_BASE_URL` or a custom `baseUrl` makes it a relay. Defaults are on only for official endpoints because relays were measured to "accept without visible benefit" or "accept but not apply" (table below).
+
+**Automatic stripping on 400**: when an endpoint rejects with 400 and the error body names `prompt_cache_key` / `prompt_cache_retention` / `prompt_cache_options` / `cache_control`, ama records `provider/model` in an in-process strip table, resends once without those fields (still with a single terminal event), and suggests once which switch to write; later requests in the same process omit them directly.
+
+### usage and `cacheReported`
+
+If any cache field appears in the raw usage (even 0) → `Usage.cacheReported = true`; none → `false`. Completions recognizes `prompt_tokens_details.cached_tokens` / `cache_write_tokens`, `prompt_cache_hit_tokens` / `prompt_cache_miss_tokens` and top-level `cached_tokens`; Responses recognizes `input_tokens_details.cached_tokens`; Anthropic recognizes `cache_read_input_tokens` / `cache_creation_input_tokens`; Google recognizes `cachedContentTokenCount` (often missing on implicit cache misses). Endpoints whose fields exist but stay 0 are judged `silent` by the session layer after 3 in a row.
+
+### Model catalog `promptCache`
+
+Only publicly documented values are written (seconds / tokens): all Anthropic models `short 300 / long 3600`, with `minTokens` 512–4096 by model; all OpenAI models `short 300 / long 86400 / minTokens 1024`; all Kimi models `short 300`. DeepSeek, Zhipu, Qwen, Groq, xAI, Mistral, OpenRouter and Google promise no TTL, so it stays empty (no warming; attribution assumes 10 minutes for implicit caching). You can fill it in yourself in `models[]` / `modelOverrides[]`.
+
+### Session layer: fingerprints, misses and three states
+
+Every real request records an in-memory entry: the prefix fingerprint (the first 16 hex characters of sha256 for the system prompt and the tool table each, plus `provider/model`), `promptTokens` (input + cacheRead + cacheWrite), usage and the send time. The next request is compared with the previous entry:
+
+- **Miss**: `missed = min(previous prefix, current prefix) − current cacheRead`, ignored below the noise floor (`max(1024, promptCache.minTokens, endpoint cache granularity)`). Some endpoints report cache reads in blocks (DeepSeek through a relay uses blocks of 2048); the granularity is the GCD of the non-zero cacheRead values observed for the same endpoint (provider + host + model), trusted only with at least 2 samples and within 128–8192, kept in memory only and reused across sessions in the process. It counts as one miss when the relative share exceeds a scale-adaptive threshold (about `0.10 × √(100k / prefix)`, clamped to 2%–30%) or the absolute value is ≥ 20 000. The re-billing amount is estimated from the difference between the price actually paid and the read price; without model prices there are only tokens.
+- **Cause** (decided in order): the system / tool table fingerprint changed → `prefix_changed` (`detail` says which part; usually the host registering tools mid-session or hook context changes); the model changed → `model_changed`; the gap exceeds the TTL → `idle` (implicit caches without a catalog TTL assume 10 minutes); a `task` sub-task took more than 80% of the gap between the two requests → `subtask`; otherwise → `evicted` (server eviction).
+- **Not a miss**: the first request after compaction, a branch summary or tier-one pruning (the context changed legitimately); prefixes below the minimum cacheable length. A model switch is **not** exempt.
+- **Three states**: maintained in-process per `(provider, baseUrl host name, model)`. `unknown`: no long enough comparable request yet; `reported`: a cacheRead or cacheWrite > 0 has been seen; `silent`: reads and writes were 0 for 3 comparable requests in a row (prefix ≥ minTokens, fingerprint unchanged, gap < TTL), or `compat.cacheReporting: "silent"`. Only `reported` shows a hit rate, detects misses and warms; `unknown` / `silent` requests stay out of the hit-rate denominator, and the interface shows `—` / "not reported" instead of 0%.
+
+`task` sub-sessions have their own record chain and stats, summarized in the "Sub-tasks" line of `/session`; forked sessions keep using the root session id as `prompt_cache_key` (just a routing hint).
+
+### Warming
+
+While a tool runs for a long time (long tests, `task` sub-tasks, codemode scripts), the prefix may expire before the next request. Warming replays the previous real request before the TTL expires (same model, same context, `maxTokens: 1`), paying only one read to keep the cache alive.
+
+| Item          | Rule                                                                                                                                                                                                                                                                       |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Modes         | `off`; `streaming` (default, only while running, i.e. during tool execution); `idle` (also in the idle period after a run, for expensive models)                                                                                                                           |
+| Preconditions | The endpoint is `reported`; the model catalog has `promptCache.short` (TTL > 10 seconds); the request's `cacheRetention` is not `none`; the request body was not replaced by `onPayload`; no warming for Anthropic with thinking whose budget is derived from `max_tokens` |
+| Timing        | Counted from when the previous request was **sent**, fired after `max(1s, min(0.9·TTL, TTL − 10s))`; if the timer fires later than the deadline (sleep, a blocked event loop) it stops                                                                                     |
+| Economics     | Sent only when `p · missCost − warmCost ≥ cache.minSavingsUsd` (default $0.05), with `p` 1 for streaming and 0.15 for idle; not sent without prices                                                                                                                        |
+| Limits        | 60 minutes for streaming, 30 minutes for idle; stops after 2 warmings in a row with zero hits                                                                                                                                                                              |
+| Cancellation  | Cancelled on model switch, thinking level change, compaction, `/tree` and exit; restarts with the next real request                                                                                                                                                        |
+| Accounting    | A successful warming appends a `usage{kind:"cache_warm"}` entry (never in the context), counted in `/session` cost and RPC stats; events `cache_warm{scheduled｜sent｜stopped}`                                                                                            |
+
+Hosts can veto or force every warming through `api.cache.onWarmingDecision` ([host-api.md](host-api.md) "Cache warming"). Sub-sessions do not warm by default (`cache.warmSubagents: true` turns it on). By catalog prices, warming during long tool runs almost always pays off; idle warming only pays off for expensive models with long prefixes.
+
+### Compaction summary continuation
+
+The summary request of tier-two compaction no longer starts a separate conversation; instead it appends a summary instruction after a prefix byte-identical to the last real request (`cacheRetention: "short"`), so the whole history is billed at the read price. The continuation request **does not send `tool_choice`**: relays and Kimi were measured to render the prompt without tool definitions under `tool_choice: "none"`, breaking the prefix at the tools section so the cache is not read; Anthropic also documents that changing tool_choice invalidates the message cache. The tool table is sent as usual, and "do not call tools, only output the summary" is in the final instruction. When the response is empty, truncated, contains tool calls or the request fails, it falls back to a standalone summary request (`cacheRetention: "none"`) with a warning.
+
+### Configuration
+
+```json
+{
+  "cache": {
+    "warming": "streaming",
+    "retention": "short",
+    "minSavingsUsd": 0.05,
+    "missNotices": true,
+    "warmSubagents": false
+  }
+}
+```
+
+| Key             | Default     | Description                                                                                                                       |
+| --------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `warming`       | `streaming` | `off` / `streaming` / `idle`; the environment variable `AMA_CACHE_WARMING` overrides; `/cache warm …` switches it for the session |
+| `retention`     | `short`     | `none` / `short` / `long`; the environment variable `AMA_CACHE_RETENTION` overrides                                               |
+| `minSavingsUsd` | `0.05`      | Minimum expected savings for warming (USD)                                                                                        |
+| `missNotices`   | `true`      | Miss and remaining-context notices in the message area (stats are unaffected)                                                     |
+| `warmSubagents` | `false`     | Also warm `task` sub-sessions                                                                                                     |
+
+The whole section is only honored in user-level and profile `config.json`; at project level it is ignored with a warning. Provider-level switches are in `providers.<id>.compat` ("Compat switches" above), and the TTL in the model's `promptCache`.
+
+### `ama models cache-probe`
+
+```sh
+ama models cache-probe <provider/id> [--tokens 2048] [--gap-ms 3000] [--json] [--yes]
+```
+
+It sends a deterministic fixed prefix (about `--tokens` tokens) + `Reply with: ok`, `maxTokens: 16`, twice `--gap-ms` apart, and decides:
+
+- `reported`: the second cacheRead ≥ 50% of the prefix; when the catalog has no `promptCache`, it suggests filling in `promptCache.short` to enable warming;
+- `silent`: reads and writes were 0 both times; it suggests setting `compat.cacheReporting: "silent"`. When the response has cache fields that stay 0, it also hints at a possible write delay (kimi-k2.5 on the same relay read 0 twice 3 seconds apart, but the full prefix on the second request 8 seconds apart), so retry with a larger `--gap-ms`;
+- `inconclusive`: a small read or only writes, most likely a cache granularity or TTL issue.
+
+It prints input / cacheRead / cacheWrite of both requests and the usage field names that protocol reads. This is a billed action: an estimate is printed first (`$?` without prices), an interactive terminal asks y/N once, and non-interactive use requires `--yes` (otherwise exit 2); with `--json` the estimate goes to stderr and stdout carries only the result object.
+
+### Relay measurements (2026-10-02)
+
+A test relay offering all three of Chat / Responses / Messages, fixed prefixes of about 8.6k–10.9k tokens, the same prefix sent twice 2–3 seconds apart (38 requests in total).
+
+| Endpoint / model                                  | Cache parameters sent                             | Result                  | Second cacheRead / prefix  | Cache fields in usage (raw shape)                                                                     |
+| ------------------------------------------------- | ------------------------------------------------- | ----------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Chat · kimi-k2.5                                  | none                                              | 200                     | 8576 / 8597                | `prompt_tokens_details.cached_tokens` (0 on the first request)                                        |
+| Chat · kimi-k2.5                                  | `prompt_cache_key`; then plus affinity headers    | 200, accepted           | 8576 / 8597 (no gain)      | Same as above                                                                                         |
+| Chat · deepseek-v4-flash                          | `prompt_cache_key` + `x-session-affinity`         | 200, accepted           | 9472 / 9767                | `prompt_tokens_details.cached_tokens`                                                                 |
+| Chat · qwen3.8-flash                              | Same as above                                     | 200, accepted           | 10240 / 10400              | Same as above                                                                                         |
+| Chat · glm-5                                      | Same as above                                     | 200, accepted           | 8704 / 9040                | Same as above                                                                                         |
+| Chat · MiniMax-M2.7                               | Same as above                                     | 200, accepted           | 9389 / 9700                | Same as above                                                                                         |
+| Responses · qwen3.8-flash                         | `prompt_cache_key` + `prompt_cache_retention`     | 200, accepted           | 10240 / 10432              | `input_tokens_details.cached_tokens`                                                                  |
+| Responses · qwen3.8-flash                         | `prompt_cache_options: {ttl:"30m"}`               | 200, accepted           | Same as above              | Same as above                                                                                         |
+| Responses · grok-4.7                              | Both sets above                                   | 200, accepted           | 1152 / 10929               | Same as above                                                                                         |
+| Responses · deepseek-v4-flash                     | `prompt_cache_retention` / `prompt_cache_options` | **400** `unknown field` | —                          | 200 once removed; `input_tokens_details.cached_tokens`                                                |
+| Messages · kimi-k2.5, qwen3.8-flash               | `cache_control` + `ttl:"1h"`                      | 200, accepted           | 9464 / 9476, 10385 / 10400 | `cache_creation.ephemeral_5m_input_tokens` has values, no 1h field: **1h treated as 5m**              |
+| Messages · MiniMax-M2.7, deepseek-v4-flash, glm-5 | Same as above                                     | 200, accepted           | 9403, 8192, 8704           | `cache_creation_input_tokens` always 0, reads hit as usual (implicit caching managed by the endpoint) |
+
+Conclusions and defaults:
+
+- `prompt_cache_key` and affinity headers are accepted on the relay but show no hit improvement → `sendPromptCacheKey` and `sendSessionAffinityHeaders` default to off for non-official endpoints; turn them on yourself when needed (400 stripping is the safety net).
+- 1h retention is accepted on the relay's Messages endpoint but written as 5m, and the long retention fields of Responses return 400 on some upstreams → `supportsLongCacheRetention` defaults to on only for official endpoints, and `supportsExplicitPromptCacheMode` defaults to off.
+- All five measured vendors report cache fields on the Chat endpoint (the zero reports from DeepSeek / GLM in an earlier study did not reproduce this time); the `cached_tokens: 0` on their first request is exactly "the field exists but is 0", so `cacheReported` is true.
+- The `/v1` deduplication and `toolChoice: "none"` were verified by real requests through ama's protocol layer: Messages requests land on `/v1/messages`, and all three endpoints accept `tool_choice: none` without producing tool calls.
+
+## Channel measurements
+
+`scripts/channel-probe.mjs` (run `pnpm build:lib` first) runs the measurement gate on `provider/model@channel`, with ≤ 8 requests per model:
+
+| Item                  | Method                                                                                                   | Pass                                                                                                                                              |
+| --------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ① check               | One minimal call                                                                                         | No error and some text                                                                                                                            |
+| ② tool round trip     | One parallel `read` of two temp files, answering with a passphrase                                       | Tool calls made and the answer contains the passphrase                                                                                            |
+| ③ thinking, two turns | In the same conversation, read another file with thinking=medium (thinking blocks replayed with history) | No error on the second request; no thinking blocks, or thinking blocks without signatures on Messages, are marked ⚠ (signature replay unverified) |
+| ④ cache               | A fixed prefix of about 3k tokens sent twice `--gap-ms` apart                                            | Second cacheRead > 0                                                                                                                              |
+| tool_use.id           | All tool call ids in the same conversation of ②③                                                         | All distinct                                                                                                                                      |
+
+All four items passing with distinct ids = passing the gate; once the official Messages channels of DeepSeek, Zhipu and Kimi pass, their default switches to messages.
+
+### Relay comparison (2026-10-02, messages vs chat)
+
+The same test relay (Chat / Messages endpoints), `--gap-ms 8000`, 84 requests (including one debugging round), conservatively priced at about $0.11:
+
+| Model@channel                      | Protocol · host                       | ① check | ② tool round trip | ③ thinking, two turns          | ④ cache (read / prefix) | ids distinct | Requests | Verdict  |
+| ---------------------------------- | ------------------------------------- | ------- | ----------------- | ------------------------------ | ----------------------- | ------------ | -------- | -------- |
+| `packy/kimi-k2.5@messages`         | anthropic-messages · www.packyapi.com | ✓       | ✓                 | ⚠ 2/2 thinking blocks unsigned | ✓ 2734 / 2738           | ✓            | 7        | fail     |
+| `packy/kimi-k2.5@chat`             | openai-completions · www.packyapi.com | ✓       | ✓                 | ✓                              | ✓ 2688 / 2740           | ✓            | 7        | **pass** |
+| `packy/deepseek-v4-flash@messages` | anthropic-messages · www.packyapi.com | ✓       | ✓                 | ⚠ no thinking blocks           | ✓ 2048 / 2732           | ✓            | 7        | fail     |
+| `packy/deepseek-v4-flash@chat`     | openai-completions · www.packyapi.com | ✓       | ✓                 | ✓                              | ✓ 2048 / 2732           | ✓            | 7        | **pass** |
+| `packy/glm-5@messages`             | anthropic-messages · www.packyapi.com | ✓       | ✓                 | ⚠ 2/2 thinking blocks unsigned | ✓ 2560 / 2733           | ✓            | 7        | fail     |
+| `packy/glm-5@chat`                 | openai-completions · www.packyapi.com | ✓       | ✓                 | ✓                              | ✓ 2560 / 2733           | ✓            | 7        | **pass** |
+| `packy/qwen3.8-flash@messages`     | anthropic-messages · www.packyapi.com | ✓       | ✓                 | ⚠ 2/2 thinking blocks unsigned | ✓ 3053 / 3061           | ✓            | 7        | fail     |
+| `packy/qwen3.8-flash@chat`         | openai-completions · www.packyapi.com | ✓       | ✓                 | ✓                              | ✓ 2048 / 3063           | ✓            | 7        | **pass** |
+| `packy/MiniMax-M2.7@messages`      | anthropic-messages · www.packyapi.com | ✓       | ✓                 | ⚠ 2/2 thinking blocks unsigned | ✓ 2638 / 2743           | ✓            | 7        | fail     |
+| `packy/MiniMax-M2.7@chat`          | openai-completions · www.packyapi.com | ✓       | ✓                 | ✓                              | ✓ 2638 / 2744           | ✓            | 7        | **pass** |
+
+- All five vendors pass ①②④ on both relay endpoints, and tool_use.id never repeats within one conversation (Kimi's ids look like `functions.read:<n>` and increase per conversation; different conversations restart from 0, so ids can only be compared within one conversation).
+- Thinking blocks on the Messages endpoint are **all unsigned** (DeepSeek returned no thinking blocks): the relay converts upstream Chat into Messages without signatures, ama degrades to text replay by rule, and round trips succeed, but signature replay was not verified, so **relay results cannot replace the measurement gate on direct official endpoints**.
+- Cache: Qwen on Messages writes 3053 tokens on the very first request (honoring `cache_control`) and reads the full prefix the second time; the other four read hits as usual with `cache_creation_input_tokens` at 0 (implicit caching managed by the endpoint), consistent with "Caching · relay measurements".
+
+### Direct official endpoints (to be run by the user with their own keys)
+
+≤ 8 requests per vendor; Kimi's cache writes are delayed, so use `--gap-ms 8000`:
+
+```sh
+pnpm build:lib
+node scripts/channel-probe.mjs --model deepseek/deepseek-v4-pro@messages,deepseek/deepseek-v4-pro@chat --json /tmp/probe-deepseek.json
+node scripts/channel-probe.mjs --model zhipu/glm-5.3@messages,zhipu/glm-5.3@chat --json /tmp/probe-zhipu.json
+node scripts/channel-probe.mjs --model moonshot/kimi-k3@messages,moonshot/kimi-k3@chat --gap-ms 8000 --json /tmp/probe-kimi.json
+node scripts/channel-probe.mjs --model dashscope/qwen3.8-max@messages --json /tmp/probe-qwen.json
+node scripts/channel-probe.mjs --model minimax/MiniMax-M3@messages,minimax/MiniMax-M2.7@messages --json /tmp/probe-minimax.json
+node scripts/channel-probe.mjs --model stepfun/step-5-preview@messages --json /tmp/probe-stepfun.json
+node scripts/channel-probe.mjs --model tencent/hy3@messages --json /tmp/probe-tencent.json
+node scripts/channel-probe.mjs --model volcengine/doubao-seed-2-1-pro-260628@responses --json /tmp/probe-volcengine.json
+```
+
+Keys come from each vendor's standard environment variables (table above); a vendor without a key is recorded as "no key" and no request is sent. Results are re-rendered with `--render` and added to this section.
+
+## The fake provider for tests
+
+`--model fake/echo`: echoes the last user message. The zero-config model picker, `ama doctor`, `ama models list`, `ama providers list` and `ama config show` hide fake by default; it is listed with `AMA_SHOW_FAKE=1` or when `AMA_FAKE_SCRIPT` is set, and an explicit `--model fake/…` works at any time. With `AMA_FAKE_SCRIPT=<file.json>` the n-th call produces text, thinking, tool calls, 429s, overflow, dropped streams or delays per the script; the script format is in `src/ai/fake/fake-script.ts`, with examples in `test/fixtures/scripts/`.