@armadra/agent 0.7.2 → 0.7.4

package/docs/en/providers.md

@@ -2,7 +2,7 @@
 
 English · [简体中文](../providers.md)
 
-> Translated from the Chinese [docs/providers.md](../providers.md) as of commit `e3bde2e`. When the two differ, the
+> Translated from the Chinese [docs/providers.md](../providers.md) as of commit `514202f`. 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).
@@ -259,7 +259,7 @@ export PACKY_API_KEY=sk-...
 
 - 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.
+- 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), and ids that line up with an official catalog entry also inherit intrinsic properties such as the thinking map (see "Inheriting from the official catalog" below); entries without a match have no `contextWindow`, so automatic compaction is off for them; add it by hand when needed. `--probe` only verifies the protocol; request formats such as `thinkingFormat` still need testing and an entry in `modelOverrides`.
 
 ```sh
 ama models discover packy --probe --write --limit 8
@@ -361,7 +361,7 @@ Measured (2026-10-02, a relay offering all three endpoint types, 22 models, 29 r
 - **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`).
+- **Priority**: user config (fields written in `models[]` / `modelOverrides[]`) > built-in catalog (snapshot ⊕ catalog overrides) > intrinsic properties inherited from the official catalog by id (next section) > 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 / `catalog (via id)` / `models.dev` / default; fields a built-in catalog inherits from the snapshot are marked `models.dev`), and name the catalog entry when inheriting by id (`catalog deepseek/deepseek-flash`).
 - **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);
@@ -372,6 +372,17 @@ Measured (2026-10-02, a relay offering all three endpoint types, 22 models, 29 r
   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.
 
+### Inheriting from the official catalog
+
+Models of relays and custom providers (`models[]` entries, and models a relay synthesizes by id) whose id lines up with a built-in catalog entry inherit that model's **intrinsic properties**, which travel with the model whoever resells it:
+
+- Inherited: `reasoning`, `input`, `thinkingLevelMap`, `promptCache.minTokens`, `compat.requiresReasoningContentOnAssistantMessages`; fields you wrote are not overwritten, and `modelOverrides` still wins.
+- Not inherited: `cost` (relay prices differ; write the relay's price yourself), `promptCache.short` / `long` (TTLs are promises of the official host), request formats such as `compat.thinkingFormat`, and cache host capabilities.
+- models.dev: on a hit, models.dev explicitly matches that catalog entry's snapshot (e.g. `deepseek/deepseek-flash` rather than a reseller's entry of the same name); window, output limit and price still come from models.dev (the price source stays `models.dev`). Without models.dev the window comes from the catalog and the output limit is capped at 64k.
+- Matching: after lowercasing and stripping one vendor prefix (like `deepseek-ai/`, `moonshotai/`) and `:latest`, the id is compared exactly with first-party catalog ids and their `aliases`; only a **unique hit** inherits (when two catalog entries claim the same key, neither is used); `vendor/model` ids in aggregator catalogs (openrouter etc.) do not take part. When the exact comparison misses, a thinking-tier suffix (`-minimal` / `-low` / `-medium` / `-high` / `-xhigh` / `-tiered`) is stripped and tried once: the relay picks the thinking tier from such a name, so only images, window and cache threshold are inherited, `reasoning` stays off and ama sends no thinking parameters. Example: `gemini-3.8-flash-low` → `google/gemini-3.8-flash`, with image input and a 1M window.
+- Switches: `"catalog": false` on a `models[]` entry turns it off; `"catalog": "deepseek/deepseek-v4-pro"` names the catalog entry explicitly (when the id does not line up). Catalog aliases live in the `aliases` of `catalog/*.json` entries (such as `deepseek-v4-flash` on `deepseek-flash`).
+- A relay that points the same id at another upstream causes a mismatch: the sources column of `ama models list` shows which entry was inherited; turn it off with `catalog: false`. Whether `requiresReasoningContentOnAssistantMessages` holds through a relay depends on the relay passing `reasoning_content` through; if not, set it to `false` in the `compat` of `modelOverrides`.
+
 ### 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.
@@ -439,22 +450,26 @@ Most usage in long tasks is cache reads: once the prefix changes, every later re
 
 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).
 
-Section patches after the conversation has started (AGENTS.md, Skills or SessionStart hook output changed on resume, host instructions refreshed, the memory section re-rendered after compaction) **do not rewrite the leading system prompt**: protocols without `supportsMidConvoSystemMessages` render them as a user message wrapped in `<system-reminder>` at the patch's position, so the previous request stays a byte-for-byte prefix. The only exception is a patch that removes tools: the tool list itself changed and the prefix is lost anyway, so all patches are folded back into the head as before. Measured on DeepSeek, a mid-conversation system message is accepted and the prefix cache holds, but the model still answers from the leading one, so DeepSeek keeps the switch off ([cache-midconvo-2026-10-09](../benchmarks/cache-midconvo-2026-10-09.md), Chinese). At the next compaction these patches are folded into the head together with the system checkpoint.
+**The leading system prompt and the tool declarations are written once per session.** Section patches after the conversation has started (AGENTS.md, Skills or SessionStart hook output changed on resume, host instructions refreshed, the memory section re-rendered after compaction) do not rewrite the head: protocols without `supportsMidConvoSystemMessages` render them as a user message wrapped in `<system-reminder>` at the patch's position, so the previous request stays a byte-for-byte prefix. Measured on DeepSeek, a mid-conversation system message is accepted and the prefix cache holds, but the model still answers from the leading one, so DeepSeek keeps the switch off ([cache-midconvo-2026-10-09](../benchmarks/cache-midconvo-2026-10-09.md), Chinese).
+
+The tool table works the same way: tools added after the conversation started are appended at the end of the table; **removing a tool keeps its declaration**, and the reminder says `Tool "X" is no longer available in this session; calls to it are rejected.` — if the model still calls it, the execution layer rejects the call (`Tool "X" is not available in this session.`); adding it back only says `Tool "X" is available again.` and keeps the declaration that was sent first. The `tools` / `rules` sections of the system prompt are also frozen to the text already sent once the conversation has started.
+
+Compaction does not rewrite the head either: the system checkpoint after compaction replays only the system messages from before the conversation started, and all later patches are merged into one placed after the summary (rendered as a reminder as well); the tool table is rebuilt in the order and version each tool first appeared. So the first request after compaction has the same system + tools bytes as before, also across repeated compactions, and only the messages after the summary are written at full price.
 
 ### 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") |
+| Protocol                                  | Field                                                                                                                                                                                      | Condition                                                                                                    |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `anthropic-messages`                      | Four `cache_control` breakpoints, the first `maxCacheBreakpoints` by priority: last user message, end of system, second-to-last user message (where the previous request wrote), 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`.
 
@@ -472,6 +487,23 @@ Inference only looks at the final request's host name (`HOST_CACHE_CAPABILITIES`
 
 **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.
 
+The second-to-last user breakpoint: when one turn carries many parallel tool results, the last user message can sit beyond the lookback window the official docs describe (about 20 blocks) from where the previous request wrote, and without it the whole stretch is rewritten; breakpoints themselves are free. The lookback window cannot be measured through relays, so this follows the official docs.
+
+### max_tokens
+
+Before each request is sent, its `max_tokens` (Completions' `max_completion_tokens`, Responses' `max_output_tokens`, Gemini's `maxOutputTokens`) goes through two steps:
+
+- **Proactive clamp**: when the model's `contextWindow` is known, it becomes `min(requested, max(1024, window − estimated input − 2048))`, with input estimated as request-body characters / 4 (CJK-heavy contexts are underestimated; the next step covers that). Anthropic budgeted thinking (`thinking.type: "enabled"`) and Gemini with a positive thinking budget are not clamped: the budget is derived from the limit, and changing it would invalidate the message cache.
+- **Reactive fix**: when an endpoint rejects with 400 and states the limit (wordings like `Range of max_tokens should be [1, N]` or `max_tokens … must be / at most / less than or equal to N`), the limit for `provider/model` is recorded in an in-process table and the request is resent once with it (like the automatic stripping above, only before the stream starts and still with a single terminal event); later requests in the same process use the limit directly. Anthropic's `input length and max_tokens exceed context limit: X + Y > Z` is resent once with `Z − X` and not recorded as a model limit; when `Z − X` is below 1024 it is handled as a context overflow (compact, then retry).
+
+Relays often list a catalog `maxTokens` equal to the window; the first request is then rejected once and never again in the same process. For a model you use long term, set `maxTokens` to the endpoint's real limit in `models[]` / `modelOverrides[]` to skip even that first rejection.
+
+### Request timeouts and retries
+
+- **Two timeouts**: `request.idleTimeoutMs` (default 300 000, overridden by `AMA_IDLE_TIMEOUT_MS`) only covers waiting for the response headers; once the stream has started, the gap between two chunks is limited by `request.streamIdleTimeoutMs` (default 180 000, overridden by `AMA_STREAM_IDLE_TIMEOUT_MS`). 0 turns either off, and a timeout is handled as a retryable error. Endpoints that hide thinking may send no bytes for a long time while reasoning, and a false stall would bill the whole output again, so the in-stream limit is not shorter; if you raised `idleTimeoutMs` for a slow endpoint before, `streamIdleTimeoutMs` is now the one to raise.
+- **Retries** (`retry.*`): the wait is `min(maxDelayMs, max(baseDelayMs × 2^(n−1), Retry-After)) × random 0.8–1.2`, so when the endpoint sends `Retry-After` ama waits at least that long (recorded as `retryAfterMs` on the failed message). 429 / 529 / rate-limit wording counts as rate limiting and is retried up to `maxRetries + 2` times; a 5xx only counts when the status code starts the message or follows `status` / `HTTP` ("500 tokens" in the middle of the text does not).
+- **Fallback model**: with `fallbackModel` set, an overloaded error is first retried once quickly (about 1 s) and only then switches to the fallback model.
+
 ### 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.
@@ -482,10 +514,10 @@ Only publicly documented values are written (seconds / tokens): all Anthropic mo
 
 ### 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:
+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`, and a hash per system section that `/cache fingerprint` lists), `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).
+- **Cause** (decided in order): the system / tool table fingerprint changed → `prefix_changed` (`detail` says which part: `tools`, or `system:<section,…>` such as `system:hooks,memory`; with the head written once, this usually means a host or extension changed the first system message directly instead of patching); 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%.
 
@@ -493,7 +525,7 @@ Every real request records an in-memory entry: the prefix fingerprint (the first
 
 ### 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.
+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` at the smallest value the protocol accepts: 16 for `openai-responses`, 1 elsewhere), paying only one read to keep the cache alive.
 
 | Item          | Rule                                                                                                                                                                                                                                                                       |
 | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -509,7 +541,9 @@ Hosts can veto or force every warming through `api.cache.onWarmingDecision` ([ho
 
 ### 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.
+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. For models with thinking enabled (except Anthropic models whose thinking budget derives from `max_tokens`), the output limit of the continuation is the summary limit 4096 plus the thinking budget of the level (capped at the model limit), so thinking cannot use up the allowance and truncate the summary.
+
+Order of tier one and tier two: the threshold check first computes how much tier one (pruning tool results) would save. If pruning brings the context back within budget → prune only; if it is still over budget and continuation is possible (same model, the last request is still a byte-for-byte prefix, the cache is not cold) → **do not prune** and continue straight into the summary — the pruned content goes into the summary anyway, while pruning rewrites history and breaks the continuation prefix, turning it into a full-price standalone request; if the cache is already cold (past the TTL the catalog promises) → prune first as before and summarize with a standalone request, since the prefix is rewritten at full price anyway and the pruned request is smaller.
 
 ### Configuration
 

package/docs/en/rpc.md

@@ -2,7 +2,7 @@
 
 English · [简体中文](../rpc.md)
 
-> Translated from the Chinese [docs/rpc.md](../rpc.md) as of commit `312ddb6`. When the two differ, the Chinese version is
+> Translated from the Chinese [docs/rpc.md](../rpc.md) as of commit `a567833`. When the two differ, the Chinese version is
 > authoritative.
 
 `ama --mode rpc` reads commands from stdin and writes responses and events to stdout, one JSON value per line. The types are defined in `@armadra/agent/rpc` (`src/rpc.ts`) and implemented in `src/modes/rpc/`. The events printed by `ama -p --output-format stream-json` have the same shapes. The design rationale is in [design.md](../design.md) §13.2 (Chinese).
@@ -18,7 +18,7 @@ English · [简体中文](../rpc.md)
 On startup the server first sends `hello`, then the current session's `session_start`:
 
 ```json
-{"type":"hello","protocolVersion":1,"agent":"ama","version":"0.1.0","capabilities":["approvals","images","hooks","plans"]}
+{"type":"hello","protocolVersion":1,"agent":"ama","version":"0.1.0","capabilities":["approvals","images","hooks","plans","compact_events"]}
 {"type":"session_start","sessionId":"…","cwd":"/work","reason":"startup"}
 ```
 
@@ -115,10 +115,12 @@ After a session switch the server re-subscribes to events and sends `session_sta
 
 ### Approvals
 
-| Command                   | Parameters                                                            | `data`                                                                                                           |
-| ------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `set_client_capabilities` | `capabilities: ("approvals" \| "images" \| "hooks" \| "plans")[]`     | `{ capabilities }`                                                                                               |
-| `permission_response`     | `requestId: string`, `decision: "allow" \| "deny" \| "allow_session"` | `{ accepted: boolean }` (false = not currently waiting for this id; kept and applied when that request is asked) |
+| Command                   | Parameters                                                                            | `data`                                                                                                           |
+| ------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `set_client_capabilities` | `capabilities: ("approvals" \| "images" \| "hooks" \| "plans" \| "compact_events")[]` | `{ capabilities }`                                                                                               |
+| `permission_response`     | `requestId: string`, `decision: "allow" \| "deny" \| "allow_session"`                 | `{ accepted: boolean }` (false = not currently waiting for this id; kept and applied when that request is asked) |
+
+`compact_events` (docs/memory-plan.md D9, Chinese): once declared, `turn_end.toolResults`, `message_start` and `entry_appended` no longer repeat the body of tool results and of user messages with images (marked `contentOmitted: true`); the body is sent only in `message_end` and `tool_execution_end`. Without it the event shapes are byte-for-byte unchanged. Shapes are in [Compact events](#compact-events-compact_events). `stream-json` has no such switch and always emits the full shapes.
 
 ### Tools, permissions, discovery
 
@@ -225,6 +227,20 @@ There is also the non-session event `{"type":"notification","level":"info"|"warn
 
 `parentToolCallId` appears only on inner calls made through `tools.*` inside codemode scripts; its value is the id of the outer `codemode` call, which clients use to fold the display. Inner calls do not enter the transcript.
 
+Assistant messages in `message_end`, `turn_end`, `done` / `error` and in replays (`get_messages`, `get_entries`) may carry two optional fields (model efficiency batch, docs/model-efficiency-plan.md §1.10, Chinese): `retryAfterMs` on failed messages (`Retry-After`, in ms) and `rawArguments` on tool-call blocks (the raw argument string the model produced). `subagent_*` events are unchanged; `TaskInfo` from `get_tasks` may carry `context?: "fork" | "fresh"` (the sub-session's actual context mode). All are new optional fields, `RPC_PROTOCOL_VERSION` is unchanged, and clients can ignore fields they do not know.
+
+### Compact events (`compact_events`)
+
+In the full shapes, the result of one tool call appears once each in `message_start`, `message_end`, `tool_execution_end`, `turn_end` and `entry_appended`. After the client declares `compact_events` with `set_client_capabilities`, three of these change:
+
+| Event            | Full (not declared)                         | With `compact_events` declared                                                                                                                    |
+| ---------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `turn_end`       | `toolResults`: complete toolResult messages | each `toolResults[]` item is only `{ toolCallId, toolName, isError, timestamp, contentOmitted: true }` (no `content`, no `details`)               |
+| `message_start`  | `message` as is                             | when `message` is a toolResult or a user message with images: `content: ""`, `contentOmitted: true`, other fields unchanged; other messages as is |
+| `entry_appended` | `entry` as is                               | `message` entries as above (toolResult, user with images); other entries as is                                                                    |
+
+`message_end` and `tool_execution_end` are always full: the former is what clients use to replace the whole message, the latter carries `details`. Replay commands (`get_messages`, `get_entries`) are unaffected. The declaration keeps applying after a session switch; declaring a capability list without `compact_events` restores the full shapes. `RPC_PROTOCOL_VERSION` is unchanged.
+
 ### Sub-agent events (wave 5)
 
 Sub-agents started by `task` / `task_ctl` (ama sub-sessions and external agents share the same events, see [agents.md](../agents.md), Chinese):
@@ -333,7 +349,7 @@ The `data` of `get_session_stats` is `SessionStats`:
 {"type":"context_pressure","percent":71,"threshold":70,"remainingTokens":57990,"estimatedTurnsLeft":6}
 ```
 
-`cache_miss` gives `detail` only for `prefix_changed` (`system` / `tools`). The values and meanings of `reason` for `cache_warm{stopped}` are in [tui.md](tui.md) "Cache and context". The result object of `ama -p --output-format json` also has a `cache` field of the same shape.
+`cache_miss` gives `detail` only for `prefix_changed` (`tools`, `system`, or `system:<section,…>` naming the changed sections, such as `system:hooks,memory`). The values and meanings of `reason` for `cache_warm{stopped}` are in [tui.md](tui.md) "Cache and context". The result object of `ama -p --output-format json` also has a `cache` field of the same shape.
 
 It also carries `context: { tokens, window, percent }` (context used, window size and usage 0–100, defined like `contextTokens` / `contextWindow` / `contextPercent` in the table above); an unknown item is omitted (for a model without a window only `tokens` is present), and when all are unknown there is no `context`.
 

package/docs/en/sessions.md

@@ -2,10 +2,10 @@
 
 English · [简体中文](../sessions.md)
 
-> Translated from the Chinese [docs/sessions.md](../sessions.md) as of commit `9ec9f5a`. When the two differ, the Chinese
+> Translated from the Chinese [docs/sessions.md](../sessions.md) as of commit `e57b54f`. When the two differ, the Chinese
 > version is authoritative. Sample command output below is illustrative; exact wording follows the interface language.
 
-These commands only read the session directory (`<data dir>/sessions`, changeable with `--session-dir`; the file format is in [session-format.md](../session-format.md), Chinese): no locks, no repair of half-written lines, no file changes, so sessions that are still running can be read too. By default the scope is the sessions of the **current directory**; `--all` covers everything.
+These commands only read the session directory (`<data dir>/sessions`, changeable with `--session-dir`; the file format is in [session-format.md](../session-format.md), Chinese): no locks, no repair of half-written lines, no file changes, so sessions that are still running can be read too. Session files are read line by line in chunks rather than loaded whole: `ama sessions list` parses only each file's header, first entry, renames and first prompt and looks at just the type of every other line, so sessions of tens of MB do not make memory grow with file size; `--resume` likewise parses a session line by line. By default the scope is the sessions of the **current directory**; `--all` covers everything.
 
 ## Stats: `ama stats`
 
@@ -78,6 +78,8 @@ the same fields):
 | `context.autoCompactAt`  | Threshold of automatic summarization (tier two) = window − `compaction.reserveTokens`; **absent** when auto-compaction is off, tripped after repeated failures, or there is no window                        |
 | `context.pruneAt`        | Threshold of tool-result pruning (tier one) = 0.7 × (window − `reserveTokens`); absent under the same conditions                                                                                             |
 
+The "window" above is min(model window, `compaction.contextBudget`) when that key is set (≥ 32768): tier one, tier two, the circuit breaker and `context_pressure` all use this soft window, while `contextWindow` and the percentage still show the model's real window. It suits models with a very large window priced by context length — for example `128000` on a 1M-window model makes long sessions compact at a 128k rhythm so the prefix re-read every turn does not grow to hundreds of thousands of tokens; there is no need to set it when the window is small or cache reads are already cheap.
+
 - **Estimation**: CJK ideographs / kana / hangul count 1 token each, other characters / 4, images 1,600 each; usage uses `totalTokens` (or input + output + cache reads / writes, output included).
 - **Before the first request** (`prefix`): the system prompt and tool table are written to the session only at the first request, so until then the estimate is taken from what is about to be sent (section texts + tool declaration JSON); a new session is not at 0 the moment it opens. This is for stats only: nothing is written to the session and the request body does not change.
 - **After compaction / context edits** (`estimate`): the last usage no longer describes the current context, so the whole context is estimated until the next request brings new usage; the UI puts `≈` in front of the number.

package/docs/en/tui.md

@@ -2,7 +2,7 @@
 
 English · [简体中文](../tui.md)
 
-> Translated from the Chinese [docs/tui.md](../tui.md) as of commit `6a7b5eb`. When the two differ, the Chinese version is
+> Translated from the Chinese [docs/tui.md](../tui.md) as of commit `4b85f89`. When the two differ, the Chinese version is
 > authoritative. Screens below are illustrative; the exact interface wording follows the interface language
 > (`ui.language`, `--lang`, `AMA_LANG`).
 
@@ -109,7 +109,7 @@ The message area (stderr with an `ama: ` prefix in line mode) shows one line in
 The misses line is broken down by cause (`3, re-billed 61k tokens ≈ $0.18 (idle timeout 2 · prefix change 1)`); while the warming timer runs, the warming line shows `streaming · next in 2m 10s · expected saving $0.18 ≥ $0.05`, and when stopped it gives the reason; with task sub-sessions there is an extra "Sub-tasks" line.
 
 - `/cache warm off|streaming|idle`: switch warming for this session (the config is not written; `idle` also warms while idle, for expensive models).
-- `/cache fingerprint`: the prefix fingerprint of the latest real request: one 16-character hash each for the system prompt and the tool table, plus the model name. If a hash changed between two requests, the host or a hook modified the system prompt / tool table mid-session.
+- `/cache fingerprint`: the prefix fingerprint of the latest real request: one 16-character hash each for the system prompt and the tool table, plus the model name, with a hash per section listed under system. If a hash changed between two requests, the host or an extension changed the leading system prompt / tool table without a patch; the section hashes show which section.
 
 Trade-offs: the status bar shows the latest hit rate (the session total lives in `/session`); `cache.missNotices` is on by default (the thresholds make it rare); the `Meter` component is not in the default status bar. The rules for hit rate, misses and warming are in [providers.md](providers.md) "Caching".
 
@@ -249,7 +249,7 @@ Design in [rewind-plan.md](../rewind-plan.md) (Chinese). Every user message that
 
 - **Top**: used / window and percentage (the same measure as `/session`: the latest usable usage plus an estimate of the messages after it), tokens left, the source ("reported usage X + estimated Y"; "estimated in full" when there is no usable usage yet, or a compaction / context edit happened after it), the auto-compact trigger (window − `compaction.reserveTokens`; "off" when disabled, "window unknown" without a window) and where tier-one pruning starts.
 - **By category**: system prompt (per section), tool declarations (per tool), user messages, assistant text, reasoning, tool-call arguments (per tool), tool results (summed per tool name), images (1,600 each), summaries (compaction / branch) and custom messages, each with an estimated token count, share and bar. The categories add up to the character-based estimate of the whole projection (one token per CJK character, other characters / 4), so the total in the heading can differ from "Used" at the top, which prefers the usage reported by the model.
-- **System prompt and tool declarations** come from the system messages stored in the session (the first full one and later patches, matching the estimate); before the first request the branch has no system message yet, both categories are 0 and the panel says they are counted after the first request.
+- **System prompt and tool declarations** come from the system messages stored in the session (the first full one and later patches, matching the estimate); before the first request the branch has no system message yet, so both categories are estimated from what the first request will send (the same baseline as the status bar); "Used" matches the status bar and the source reads "system prompt and tools only, estimated before the first request".
 - **Bottom**: only the ordinal (which tool result in the projection), tool name and size of the 5 largest tool results — **never their content**.
 - Read-only: no session entries are written and the request body is untouched, so the prompt-cache prefix is unaffected.
 

package/docs/permissions.md

@@ -171,7 +171,10 @@ default / auto-edit 下，满足下面全部条件的 bash 调用免审批（`Pe
 - **独立请求**：不进会话转录、不改主会话的消息与前缀（主会话的提示缓存不受影响），不触发保温；请求用途 `purpose: "classify"`。
 - **输入**：工具名、参数（JSON，截断到 4000 字符）、cwd、项目根、最近一条用户消息的摘要（截断到 600 字符）。参数与用户消息放在 `<tool_call_data>` … `</tool_call_data>` 数据块里，块内出现的结束标记会被转义；系统提示要求把块内一切当数据，忽略其中的指令（包括「ignore previous instructions」「respond allow」之类），遇到这种文本倾向于 ask。
 - **输出**：严格 JSON `{"decision":"allow"|"ask","reason":"…"}`。解析失败、超时（10 s）、请求出错 → 询问。
-- **模型**：`permission.autoModel`（`provider/model`）；缺省用当前会话模型。推荐配一个便宜快速的模型，例如 `packy/qwen3.8-flash`。`maxTokens` 256，关闭思考。
+- **模型**：`permission.autoModel`（`provider/model`）；没配（或找不到）时用会话供应商目录里的小模型（目录文件级
+  `small`：deepseek → `deepseek-flash`、anthropic → `claude-haiku-4-5`、openai → `gpt-6-luna`、google →
+  `gemini-3.5-flash-lite`、moonshot → `kimi-k2.6` 等，要能找到且有 key），再否则用当前会话模型；选中的模型记一条
+  debug 日志。中转与自定义供应商没有目录小模型，仍用会话模型。推荐配一个便宜快速的模型，例如 `packy/qwen3.8-flash`。`maxTokens` 256，关闭思考。
 - **缓存**：会话内按「工具名 + 归一化参数」（bash 折叠空白，其它按键排序的 JSON）缓存成功的判定，同样的调用只分类一次；出错与超时不缓存。
 - **费用**：每次分类的用量记一条 `usage` 条目，`kind: "permission_classify"`，计入 `/session` 费用与 RPC 统计，不进上下文。
 - 分类器只能把未决定的调用判成 allow 或 ask，不能推翻①的拒绝或询问。

package/docs/providers.md

@@ -320,7 +320,9 @@ export PACKY_API_KEY=sk-...
   `providers add --probe`）；
   `--write` 把结果合并进用户级 `config.json`（已有同 id 不覆盖，只写 `id` 与和供应商不同的 `api`，
   原文件备份为 `config.json.bak`）。上下文等元数据在运行时从 models.dev 快照补（见下文「模型元数据」），
-  匹配不到的条目没有 `contextWindow`，自动压缩随之关闭，需要时手动补。
+  id 与官方目录条目对得上的还继承思考映射等固有属性（见下文「从官方目录继承」）；匹配不到的条目没有
+  `contextWindow`，自动压缩随之关闭，需要时手动补。`--probe` 只验证协议，`thinkingFormat` 这类请求格式仍需
+  实测后写进 `modelOverrides`。
 
 ```sh
 ama models discover packy --probe --write --limit 8
@@ -493,10 +495,11 @@ ama providers refresh <id> [--probe …]
 src/ai/providers/catalog.test.ts` 自动删除并重新生成 `catalog-data.ts`（之后跑 prettier）；确实要钉住与快照相同的
   值时在条目上写 `"_reason": "…"`（注释，运行时忽略，该条目不做冗余检查）。目录继承的映射与自定义模型略有不同：
   `maxTokens` 不封顶（取 `min(limit.output, contextWindow)`），缺的缓存价记 0。
-- **优先级**：用户配置（`models[]` / `modelOverrides[]` 里写了的字段）> 内置目录（快照 ⊕ 目录覆盖）> models.dev
-  索引 > 自定义缺省（`maxTokens: 8192`、`input: ["text"]`、`reasoning: false`、不猜 `contextWindow`）。
-  `ama models list` 与 `ama config show` 标出每个字段来自哪里（`config` / `目录` / `models.dev` / `缺省`；内置目录
-  从快照继承的字段标 `models.dev`）。
+- **优先级**：用户配置（`models[]` / `modelOverrides[]` 里写了的字段）> 内置目录（快照 ⊕ 目录覆盖）> 按 id 继承的
+  官方目录固有属性（下节）> models.dev 索引 > 自定义缺省（`maxTokens: 8192`、`input: ["text"]`、
+  `reasoning: false`、不猜 `contextWindow`）。`ama models list` 与 `ama config show` 标出每个字段来自哪里
+  （`config` / `目录` / `目录（按 id 匹配）` / `models.dev` / `缺省`；内置目录从快照继承的字段标 `models.dev`），
+  按 id 继承时另列出目录条目（`目录 deepseek/deepseek-flash`）。
 - **字段映射**（自定义模型）：`contextWindow = limit.context`；`maxTokens = min(limit.output, 65536, contextWindow)`——
   `maxTokens` 每次请求都作为 `max_tokens` 发出，models.dev 给的是原厂上限（不少模型写的是与上下文相同的
   1M），中转换了上游后常拒收超大值，Anthropic 协议的思考预算也从它推导，64k 对编码 Agent 的单轮输出足够，
@@ -519,6 +522,29 @@ src/ai/providers/catalog.test.ts` 自动删除并重新生成 `catalog-data.ts`
   7. 都没有 → 「未匹配」，保持自定义缺省（不猜 `contextWindow`，自动压缩关闭）。快照只收主流厂商，转售商专有的
      id 可能匹配不到，可在模型上写 `modelsDev` 指向收录的条目。
 
+### 从官方目录继承
+
+中转站与自定义供应商的模型（`models[]` 条目，以及中转上按 id 合成的模型）若 id 能对上内置目录的条目，就继承
+该模型的**固有属性**——它们跟着模型走，换了转售商也不变：
+
+- 继承：`reasoning`、`input`、`thinkingLevelMap`、`promptCache.minTokens`、
+  `compat.requiresReasoningContentOnAssistantMessages`；用户写了的字段不覆盖，`modelOverrides` 仍最高。
+- 不继承：`cost`（中转价不同，要用中转价请自填）、`promptCache.short` / `long`（TTL 是官方主机的承诺）、
+  `compat.thinkingFormat` 等请求格式与缓存主机能力。
+- models.dev：命中时 models.dev 改为显式匹配该目录条目的快照（如 `deepseek/deepseek-flash`，而不是别家转售的同名
+  条目），窗口、输出上限与价格照旧来自 models.dev（价格来源仍标 `models.dev`）；models.dev 不可用时窗口取目录值、
+  输出上限按 64k 封顶。
+- 匹配：小写、去一层厂商前缀（`deepseek-ai/`、`moonshotai/` 一类）与 `:latest` 后，与第一方目录条目的 id 或
+  `aliases` 精确比较，**唯一命中**才继承（两条目录条目撞同一个键时都不用）；聚合商目录（openrouter 等）里
+  `vendor/model` 形式的 id 不参与。精确比较不中时再去掉思考档后缀（`-minimal` / `-low` / `-medium` / `-high` /
+  `-xhigh` / `-tiered`）试一次：这类 id 由中转按名字决定思考档，所以只继承图片、窗口与缓存门槛，`reasoning` 不打开，
+  ama 不再发思考参数。例：`gemini-3.8-flash-low` → `google/gemini-3.8-flash`，带图片输入、1M 窗口。
+- 开关：`models[]` 条目写 `"catalog": false` 关闭；`"catalog": "deepseek/deepseek-v4-pro"` 显式指定目录条目（id
+  对不上时）。目录别名写在 `catalog/*.json` 条目的 `aliases` 里（如 `deepseek-flash` 的 `deepseek-v4-flash`）。
+- 中转把同名 id 指到别的上游时会误配：`ama models list` 的来源列能看出继承了哪条，用 `catalog: false` 关掉。
+  `requiresReasoningContentOnAssistantMessages` 经中转是否成立取决于中转是否透传 `reasoning_content`，不成立时用
+  `modelOverrides` 的 `compat` 写 `false`。
+
 ### 图像输入
 
 - 四条协议都把图片放进用户消息：Chat Completions `image_url`（data URL）、Responses `input_image`、
@@ -603,22 +629,26 @@ OpenRouter 的 Messages 接口只在 `message_delta` 里给缓存 usage，解析
 
 前缀稳定由组装保证：系统提示节顺序固定、不含时间戳，工具按名排序，会话中途的变化只以 system 补丁追加在末尾（[session-format.md](session-format.md)「消息」）。
 
-对话开始之后的节补丁（resume 时 AGENTS.md、Skills 或 SessionStart Hook 输出变了，宿主 instructions 刷新，压缩后记忆节重新渲染）**不改写开头的 system**：没有打开 `supportsMidConvoSystemMessages` 的协议把它渲染成 `<system-reminder>` 包裹的 user 消息，插在补丁所在的位置，之前的请求仍是逐字节前缀。只有移除工具的补丁例外——工具表本身已经变了，前缀必然失效，这时全部补丁照旧折回开头。实测 DeepSeek 接受对话中途的 system 消息、前缀缓存也保持，但模型仍按开头那条回答，所以 DeepSeek 不打开这个开关（[cache-midconvo-2026-10-09](benchmarks/cache-midconvo-2026-10-09.md)）。下一次压缩时，这些补丁随 system 检查点并回开头。
+**开头的 system 与工具声明在会话内只写一次。** 对话开始之后的节补丁（resume 时 AGENTS.md、Skills 或 SessionStart Hook 输出变了，宿主 instructions 刷新，压缩后记忆节重新渲染）不改写开头：没有打开 `supportsMidConvoSystemMessages` 的协议把它渲染成 `<system-reminder>` 包裹的 user 消息，插在补丁所在的位置，之前的请求仍是逐字节前缀。实测 DeepSeek 接受对话中途的 system 消息、前缀缓存也保持，但模型仍按开头那条回答，所以 DeepSeek 不打开这个开关（[cache-midconvo-2026-10-09](benchmarks/cache-midconvo-2026-10-09.md)）。
+
+工具表同理：对话开始后新加的工具追加在工具表末尾；**移除工具不删声明**，提醒里写一句 `Tool "X" is no longer available in this session; calls to it are rejected.`，模型仍去调用时执行层拒绝（`Tool "X" is not available in this session.`）；再加回只提醒 `Tool "X" is available again.`，声明沿用第一次发送的版本。系统提示的 `tools` / `rules` 两节在对话开始后也冻结为已发送的文本。
+
+压缩不重写开头：压缩后的 system 检查点只重放对话开始前的 system 消息，之后的全部补丁合并成一条放在摘要后面（同样渲染为提醒），工具表按第一次出现的顺序与版本重建。所以压缩前后的首个请求 system + tools 逐字节相同，多次压缩也一样，只有摘要之后的消息需要按全价写入。
 
 ### 请求字段
 
-| 协议                                     | 字段                                                                                     | 条件                                                                                     |
-| ---------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `anthropic-messages`                     | 三断点 `cache_control`（最后一条 user、system 末、最后一个工具）                         | `cacheRetention` 不是 `none`                                                             |
-| `anthropic-messages`                     | `ttl: "1h"`                                                                              | `long` 且 `supportsLongCacheRetention`；否则按 5m                                        |
-| `openai-completions`                     | `prompt_cache_key = sessionId`（截 64 字符）                                             | `sendPromptCacheKey` 且不是 `none`                                                       |
-| `openai-completions`                     | `prompt_cache_retention: "24h"`                                                          | `long` 且 `supportsLongCacheRetention`                                                   |
-| `openai-completions`（`anthropic/*` 等） | `cache_control`（`cacheControlFormat: "anthropic"`），`long` 时带 `ttl: "1h"`            | 同 Anthropic                                                                             |
-| `openai-responses`                       | `prompt_cache_key`                                                                       | 同 Completions                                                                           |
-| `openai-responses`                       | `prompt_cache_options: { ttl: "30m" }`，否则 `prompt_cache_retention: "24h"`             | `long` 且 `supportsExplicitPromptCacheMode`；否则 `long` 且 `supportsLongCacheRetention` |
-| OpenAI 两条                              | 亲和头 `x-session-affinity` + 每请求 `x-client-request-id`（OpenRouter：`x-session-id`） | `sendSessionAffinityHeaders` 且有 sessionId                                              |
-| `google-generative-ai`                   | 无（隐式缓存）                                                                           | —                                                                                        |
-| 全部                                     | `toolChoice: "none"` → 各家的「禁止调用工具」写法                                        | 请求带工具时（摘要续写**不用**，见「压缩摘要续写」）                                     |
+| 协议                                     | 字段                                                                                                                                         | 条件                                                                                     |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `anthropic-messages`                     | 四断点 `cache_control`，按优先级取前 `maxCacheBreakpoints` 个：最后一条 user、system 末、倒数第二条 user（上一次请求的写入点）、最后一个工具 | `cacheRetention` 不是 `none`                                                             |
+| `anthropic-messages`                     | `ttl: "1h"`                                                                                                                                  | `long` 且 `supportsLongCacheRetention`；否则按 5m                                        |
+| `openai-completions`                     | `prompt_cache_key = sessionId`（截 64 字符）                                                                                                 | `sendPromptCacheKey` 且不是 `none`                                                       |
+| `openai-completions`                     | `prompt_cache_retention: "24h"`                                                                                                              | `long` 且 `supportsLongCacheRetention`                                                   |
+| `openai-completions`（`anthropic/*` 等） | `cache_control`（`cacheControlFormat: "anthropic"`），`long` 时带 `ttl: "1h"`                                                                | 同 Anthropic                                                                             |
+| `openai-responses`                       | `prompt_cache_key`                                                                                                                           | 同 Completions                                                                           |
+| `openai-responses`                       | `prompt_cache_options: { ttl: "30m" }`，否则 `prompt_cache_retention: "24h"`                                                                 | `long` 且 `supportsExplicitPromptCacheMode`；否则 `long` 且 `supportsLongCacheRetention` |
+| OpenAI 两条                              | 亲和头 `x-session-affinity` + 每请求 `x-client-request-id`（OpenRouter：`x-session-id`）                                                     | `sendSessionAffinityHeaders` 且有 sessionId                                              |
+| `google-generative-ai`                   | 无（隐式缓存）                                                                                                                               | —                                                                                        |
+| 全部                                     | `toolChoice: "none"` → 各家的「禁止调用工具」写法                                                                                            | 请求带工具时（摘要续写**不用**，见「压缩摘要续写」）                                     |
 
 保留层级：`StreamOptions.cacheRetention` 优先；未指定时读 `AMA_CACHE_RETENTION=none|short|long`；都没有为
 `short`。Anthropic 请求体最后做 TTL 顺序校验（tools → system → messages 里 5m 之后出现 1h 则全部降为 5m）。
@@ -641,6 +671,37 @@ Anthropic 的 `baseUrl` 以 `/v1` 结尾时请求 `{baseUrl}/messages`，不会
 `prompt_cache_options` / `cache_control` 时，ama 把 `provider/model` 记入进程内的剥离表，去掉这些字段重发一次
 （仍只有一个终止事件），提示一次建议写哪个开关；同一进程里之后的请求直接不带。
 
+倒数第二条 user 的断点：一次回合里并行工具结果很多时，最后一条 user 离上一次请求的写入点可能超出官方文档说的
+回看窗口（约 20 个块），没有它就要整段重写；断点本身不计费。回看窗口没法经中转实测，这一条按官方文档实现。
+
+### max_tokens
+
+每次请求的 `max_tokens`（Completions 的 `max_completion_tokens`、Responses 的 `max_output_tokens`、Gemini 的
+`maxOutputTokens`）在发出前做两件事：
+
+- **主动收紧**：模型的 `contextWindow` 已知时取 `min(请求值, max(1024, 窗口 − 估算输入 − 2048))`，输入按请求体
+  字符数 / 4 估算（中文多的上下文会估低，由下一条兜底）。Anthropic 预算型思考（`thinking.type: "enabled"`）与带
+  正思考预算的 Gemini 不收紧：预算由上限推导，改它会让消息缓存失效。
+- **被动修正**：端点以 400 拒收并说出上限时（`Range of max_tokens should be [1, N]`、
+  `max_tokens … must be / at most / less than or equal to N` 一类文案），把 `provider/model` 的上限记入进程内的表、
+  以上限重发一次（与上面的 400 自动剥离一样只发生在流开始之前，仍只有一个终止事件），同一进程里之后的请求直接用
+  上限。Anthropic 的 `input length and max_tokens exceed context limit: X + Y > Z` 按 `Z − X` 重发一次、不记为模型
+  上限；`Z − X` 不足 1024 时按上下文溢出处理（压缩后重试）。
+
+中转常把目录里的 `maxTokens` 写成与窗口相同，这时第一次请求会被拒一次，之后同一进程里不再出现；长期用的模型可以
+在 `models[]` / `modelOverrides[]` 里把 `maxTokens` 填成端点实际上限，连第一次也省掉。
+
+### 请求超时与重试
+
+- **超时分两段**：`request.idleTimeoutMs`（缺省 300 000，`AMA_IDLE_TIMEOUT_MS` 覆盖）只管等响应头；流开始后两块数据之间
+  的上限是 `request.streamIdleTimeoutMs`（缺省 180 000，`AMA_STREAM_IDLE_TIMEOUT_MS` 覆盖）。两者都是 0 关闭，超时按
+  可重试错误处理。思考不外露的端点推理阶段可能很久没有字节，误判断流会让整段输出重新计费，所以流中上限不设得更短；
+  以前为慢端点调大 `idleTimeoutMs` 的，现在要调的是 `streamIdleTimeoutMs`。
+- **重试**（`retry.*`）：等待 = `min(maxDelayMs, max(baseDelayMs × 2^(n−1), Retry-After)) × 0.8–1.2 随机`，端点给了
+  `Retry-After` 就至少等那么久（失败消息上记为 `retryAfterMs`）。429 / 529 / rate limit 文案算限流，最多重试
+  `maxRetries + 2` 次；5xx 只认文案开头或 `status` / `HTTP` 之后的状态码（文案中间出现的「500 tokens」不算）。
+- **回退模型**：配了 `fallbackModel` 时，overloaded 先快速重试一次（约 1 s），仍失败才切到回退模型。
+
 ### usage 与 `cacheReported`
 
 原始 usage 里出现任一缓存字段（即使为 0）→ `Usage.cacheReported = true`，都没有 → `false`：Completions 认
@@ -659,10 +720,10 @@ xAI、Mistral、OpenRouter、Google 没有承诺的 TTL，留空：不保温、
 
 ### 会话层：指纹、未命中与三态
 
-每次真实请求在内存里记一条记录：前缀指纹（system 与工具表各取 sha256 前 16 位 hex，加 `provider/model`）、`promptTokens`（input + cacheRead + cacheWrite）、用量与发出时刻。下一次请求与上一条比对：
+每次真实请求在内存里记一条记录：前缀指纹（system 与工具表各取 sha256 前 16 位 hex，加 `provider/model`，另记每个 system 节的哈希，`/cache fingerprint` 逐节列出）、`promptTokens`（input + cacheRead + cacheWrite）、用量与发出时刻。下一次请求与上一条比对：
 
 - **未命中**：`missed = min(上次前缀, 本次前缀) − 本次 cacheRead`，低于噪声下限（`max(1024, promptCache.minTokens, 端点缓存粒度)`）不计——有的端点按块报缓存读（DeepSeek 经中转是 2048 一块），粒度取同一端点（供应商 + 主机 + 模型）观察到的非零 cacheRead 的最大公约数，至少 2 个样本且在 128–8192 之间才采信，只在内存、进程内跨会话复用；相对比例超过随规模自适应的门槛（约 `0.10 × √(100k / 前缀)`，夹在 2%–30%），或绝对值 ≥ 20 000 才记一次。重计费金额按本条实付单价与读价之差估算，模型无价格时只有 token。
-- **原因**（按顺序判定）：system / 工具表指纹变了 → `prefix_changed`（`detail` 说明哪段，多半是宿主中途注册工具或 Hook 上下文变化）；模型变了 → `model_changed`；间隔超过 TTL → `idle`（目录没有 TTL 的隐式缓存按 10 分钟估）；两次请求之间 `task` 子任务占了间隔的 80% 以上 → `subtask`；其余 → `evicted`（服务端淘汰）。
+- **原因**（按顺序判定）：system / 工具表指纹变了 → `prefix_changed`（`detail` 说明哪段：`tools`，或 `system:<节名,…>`，例如 `system:hooks,memory`；开头只写一次之后，这通常意味着宿主或扩展绕过补丁直接改了首条 system）；模型变了 → `model_changed`；间隔超过 TTL → `idle`（目录没有 TTL 的隐式缓存按 10 分钟估）；两次请求之间 `task` 子任务占了间隔的 80% 以上 → `subtask`；其余 → `evicted`（服务端淘汰）。
 - **不算未命中**：压缩、分支摘要、档一裁剪之后的首个请求（上下文合法地变了）；前缀低于最小可缓存长度。切换模型**不**豁免。
 - **三态**：按 `(provider, baseUrl 主机名, model)` 在进程内维护。`unknown`：还没有足够长的可比请求；`reported`：出现过 cacheRead 或 cacheWrite > 0；`silent`：连续 3 个可比请求（前缀 ≥ minTokens、指纹未变、间隔 < TTL）读写都是 0，或 `compat.cacheReporting: "silent"`。只有 `reported` 时显示命中率、检测未命中并保温；`unknown` / `silent` 的请求不进命中率分母，界面显示 `—` / `未报告` 而不是 0%。
 
@@ -670,7 +731,7 @@ xAI、Mistral、OpenRouter、Google 没有承诺的 TTL，留空：不保温、
 
 ### 保温
 
-工具长时间运行（长测试、`task` 子任务、codemode 脚本）时，前缀可能在下一次请求前过期。保温在 TTL 到期前重放上一次真实请求（同模型、同上下文，`maxTokens: 1`），只买一次读价，把缓存续上。
+工具长时间运行（长测试、`task` 子任务、codemode 脚本）时，前缀可能在下一次请求前过期。保温在 TTL 到期前重放上一次真实请求（同模型、同上下文，`maxTokens` 取协议允许的最小值：`openai-responses` 为 16，其余为 1），只买一次读价，把缓存续上。
 
 | 项     | 规则                                                                                                                                                                                       |
 | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -686,7 +747,9 @@ xAI、Mistral、OpenRouter、Google 没有承诺的 TTL，留空：不保温、
 
 ### 压缩摘要续写
 
-档二压缩的摘要请求不再另起一段新对话，而是在与上一次真实请求逐字节相同的前缀后面追加一条摘要指令（`cacheRetention: "short"`），所以整段历史按读价计费。续写请求**不发 `tool_choice`**：实测中转与 Kimi 在 `tool_choice: "none"` 时渲染的提示不带工具定义，前缀在工具段断开、读不到缓存；Anthropic 也写明改动 tool_choice 会让消息缓存失效。工具表照常发，「不要调用工具、只输出摘要」写在末尾指令里。响应为空、被截断、含工具调用或请求出错时，回落为独立的摘要请求（`cacheRetention: "none"`）并记 warning。
+档二压缩的摘要请求不再另起一段新对话，而是在与上一次真实请求逐字节相同的前缀后面追加一条摘要指令（`cacheRetention: "short"`），所以整段历史按读价计费。续写请求**不发 `tool_choice`**：实测中转与 Kimi 在 `tool_choice: "none"` 时渲染的提示不带工具定义，前缀在工具段断开、读不到缓存；Anthropic 也写明改动 tool_choice 会让消息缓存失效。工具表照常发，「不要调用工具、只输出摘要」写在末尾指令里。响应为空、被截断、含工具调用或请求出错时，回落为独立的摘要请求（`cacheRetention: "none"`）并记 warning。开了思考的模型（预算随 `max_tokens` 推导的 Anthropic 除外），续写的输出上限为摘要上限 4096 加上该级别的思考预算（不超过模型上限），免得思考用完额度、摘要被截断。
+
+档一 / 档二的先后：阈值检查先算档一（裁剪工具结果）能省多少。裁完就回到预算内 → 只裁；裁完仍超预算、且可以续写（同一模型、上一次请求仍是逐字节前缀、缓存没冷）→ **不裁**，直接续写摘要——被裁的内容本来就要进摘要，而裁剪会改写历史、让续写的前缀断开，变成一次全价的独立请求；缓存已经冷了（超过目录承诺的 TTL）→ 照旧先裁，摘要走独立请求，因为前缀反正要全价重写，裁剪后的请求更小。
 
 ### 配置
 

package/docs/rpc.md

@@ -13,7 +13,7 @@
 启动后先发 `hello`，再发当前会话的 `session_start`：
 
 ```json
-{"type":"hello","protocolVersion":1,"agent":"ama","version":"0.1.0","capabilities":["approvals","images","hooks","plans"]}
+{"type":"hello","protocolVersion":1,"agent":"ama","version":"0.1.0","capabilities":["approvals","images","hooks","plans","compact_events"]}
 {"type":"session_start","sessionId":"…","cwd":"/work","reason":"startup"}
 ```
 
@@ -110,10 +110,12 @@
 
 ### 审批
 
-| 命令                      | 参数                                                                  | `data`                                                                         |
-| ------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
-| `set_client_capabilities` | `capabilities: ("approvals" \| "images" \| "hooks" \| "plans")[]`     | `{ capabilities }`                                                             |
-| `permission_response`     | `requestId: string`、`decision: "allow" \| "deny" \| "allow_session"` | `{ accepted: boolean }`（false = 当前没在等这个 id，已暂存，稍后被问到时生效） |
+| 命令                      | 参数                                                                                  | `data`                                                                         |
+| ------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `set_client_capabilities` | `capabilities: ("approvals" \| "images" \| "hooks" \| "plans" \| "compact_events")[]` | `{ capabilities }`                                                             |
+| `permission_response`     | `requestId: string`、`decision: "allow" \| "deny" \| "allow_session"`                 | `{ accepted: boolean }`（false = 当前没在等这个 id，已暂存，稍后被问到时生效） |
+
+`compact_events`（docs/memory-plan.md D9）：声明后，`turn_end.toolResults`、`message_start` 与 `entry_appended` 不再重复携带工具结果与带图用户消息的正文（以 `contentOmitted: true` 标记），正文只在 `message_end` 与 `tool_execution_end` 里发；不声明时事件形状逐字节不变。形状见「[精简事件](#精简事件compact_events)」。`stream-json` 没有这个开关，输出始终是全量形状。
 
 ### 工具、权限、发现
 
@@ -212,6 +214,20 @@
 
 `parentToolCallId` 只出现在 codemode 脚本里经 `tools.*` 发起的内层调用上，值是外层 `codemode` 调用的 id；客户端据此折叠显示。内层调用不进转录。
 
+`message_end`、`turn_end`、`done` / `error` 与回放（`get_messages`、`get_entries`）里的助手消息可能带两个可选字段（模型调用效率批次，docs/model-efficiency-plan.md §1.10）：失败消息的 `retryAfterMs`（`Retry-After`，毫秒），工具调用块的 `rawArguments`（模型输出的原始参数字符串）。`subagent_*` 事件不变；`get_tasks` 的 `TaskInfo` 可带 `context?: "fork" | "fresh"`（子会话的实际上下文模式）。都是新增的可选字段，`RPC_PROTOCOL_VERSION` 不变，客户端忽略不认识的字段即可。
+
+### 精简事件（`compact_events`）
+
+一次工具调用的结果在全量形状下会随 `message_start`、`message_end`、`tool_execution_end`、`turn_end`、`entry_appended` 各出现一次。客户端用 `set_client_capabilities` 声明 `compact_events` 之后，其中三类事件改为：
+
+| 事件             | 全量（未声明）                        | 声明 `compact_events` 时                                                                                                     |
+| ---------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `turn_end`       | `toolResults`：完整的 toolResult 消息 | `toolResults[]` 每项只有 `{ toolCallId, toolName, isError, timestamp, contentOmitted: true }`（不带 `content` 与 `details`） |
+| `message_start`  | `message` 原样                        | `message` 是 toolResult 或带图片的 user 消息时 `content: ""`、`contentOmitted: true`，其余字段不变；其它消息原样             |
+| `entry_appended` | `entry` 原样                          | `message` 条目同上（toolResult、带图片的 user）；其它条目原样                                                                |
+
+`message_end` 与 `tool_execution_end` 始终全量：前者是客户端替换整条消息的依据，后者带 `details`。回放命令（`get_messages`、`get_entries`）不受影响。会话切换后仍按当前声明生效；重新声明不含 `compact_events` 的能力列表即恢复全量。`RPC_PROTOCOL_VERSION` 不变。
+
 ### 子 Agent 事件（第五波）
 
 `task` / `task_ctl` 起的子 Agent（ama 子会话与外部 Agent 同一组事件，见 [agents.md](agents.md)「子 Agent」）：
@@ -340,7 +356,7 @@
 {"type":"context_pressure","percent":71,"threshold":70,"remainingTokens":57990,"estimatedTurnsLeft":6}
 ```
 
-`cache_miss` 的 `detail` 只在 `prefix_changed` 时给出（`system` / `tools`）。`cache_warm{stopped}` 的 `reason` 取值与含义见 [tui.md](tui.md)「缓存与上下文」。`ama -p --output-format json` 的结果对象另有 `cache` 字段，形状同上。
+`cache_miss` 的 `detail` 只在 `prefix_changed` 时给出（`tools`、`system`，或带变化节名的 `system:<节名,…>`，如 `system:hooks,memory`）。`cache_warm{stopped}` 的 `reason` 取值与含义见 [tui.md](tui.md)「缓存与上下文」。`ama -p --output-format json` 的结果对象另有 `cache` 字段，形状同上。
 
 ## 审批