@armadra/agent 0.7.0 → 0.7.2

package/dist/tui/program-status.js

@@ -0,0 +1,259 @@
+/**
+ * 终端程序状态协议 OSC 7501（Program Status Protocol rev 0.3，2026-10-07）：
+ * https://www.superlogical.com/rex/docs/build/program-status
+ *
+ * - 编码（纯函数）：`ESC ] 7501 ; key=value:… ESC \`。state 必填；id 每段 `[A-Za-z0-9_.+-]{1,32}`、
+ *   ≤ 8 层、≤ 128 字节；kind 只随 blocked、progress（0–100 整数）只随 working / blocked；app 同 id 段；
+ *   title / msg 去控制字符、压成一行后按 UTF-8 字节截断（192 / 2048，不切坏字符），再 base64。
+ *   字段不合法就丢掉该字段（state / id 不合法整条不发），不发终端会整条丢弃的坏报告；整条 ≤ 4096 字节。
+ * - 检测：发 `OSC 7501 ; ?` 紧跟 `CSI c`（DA1）；先收到 `?` 回复 = 支持，DA1 回复先到或超时 = 不支持。
+ *   两种回复都在输入解析里吞掉（`handleInput`），不会当成按键进输入框；迟到的回复同样吞掉。
+ * - tmux：缺省丢弃未知 OSC，`on` 时用 DCS passthrough（`ESC P tmux; … ESC \`，内容里 ESC 翻倍）包裹，
+ *   需要 `set -g allow-passthrough on`；tmux 不把外层终端对透传查询的回复转给窗格，所以 tmux 里 `auto`
+ *   不检测、等同 `off`。
+ * - 发射器：每个 id 记最后一次写出的报告，同值不重写；同一 state 下只换 msg / title 的更新按节流合并。
+ */
+export const PROGRAM_STATUS_QUERY = "\x1b]7501;?\x1b\\";
+export const DA1_QUERY = "\x1b[c";
+export const MAX_SEQUENCE_BYTES = 4096;
+export const MAX_TITLE_BYTES = 192;
+export const MAX_MSG_BYTES = 2048;
+const MAX_ID_BYTES = 128;
+const MAX_ID_DEPTH = 8;
+const SEGMENT = /^[A-Za-z0-9_.+-]{1,32}$/;
+const STATES = ["idle", "working", "done", "blocked", "error", "clear"];
+const KINDS = ["permission", "question", "auth"];
+const ELLIPSIS = "…";
+/** 控制字符（C0、DEL、C1）换成空格，空白压成一个，去首尾。 */
+export function sanitizeLine(text) {
+    return text
+        .replace(/[\x00-\x1f\x7f-\x9f]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** 按 UTF-8 字节截断到 maxBytes（按码点切，不出半个字符）；截断时末尾带 `…`。 */
+export function truncateUtf8(text, maxBytes) {
+    if (Buffer.byteLength(text, "utf8") <= maxBytes)
+        return text;
+    const budget = maxBytes - Buffer.byteLength(ELLIPSIS, "utf8");
+    let used = 0;
+    let out = "";
+    for (const ch of text) {
+        const n = Buffer.byteLength(ch, "utf8");
+        if (used + n > budget)
+            break;
+        used += n;
+        out += ch;
+    }
+    return out + ELLIPSIS;
+}
+/** id 是否合法（空串不合法；根记录不带 id）。 */
+export function validId(id) {
+    if (Buffer.byteLength(id, "utf8") > MAX_ID_BYTES)
+        return false;
+    const segments = id.split("/");
+    return segments.length <= MAX_ID_DEPTH && segments.every((s) => SEGMENT.test(s));
+}
+/** 任意字符串 → 合法的单段 id（非法字符换 `_`，截到 n 个字符）；空串给 `x`。 */
+export function idSegment(raw, n = 12) {
+    const s = raw.replace(/[^A-Za-z0-9_.+-]/g, "_").slice(0, n);
+    return s === "" ? "x" : s;
+}
+function encodeText(text, maxBytes) {
+    if (text === undefined)
+        return undefined;
+    const line = sanitizeLine(text);
+    if (line === "")
+        return undefined;
+    return Buffer.from(truncateUtf8(line, maxBytes), "utf8").toString("base64");
+}
+/** 报告 → pairs（不含 OSC 包裹）；state / id 不合法返回 undefined。 */
+export function encodePairs(report) {
+    if (!STATES.includes(report.state))
+        return undefined;
+    if (report.id !== undefined && !validId(report.id))
+        return undefined;
+    const pairs = [`state=${report.state}`];
+    if (report.id !== undefined)
+        pairs.push(`id=${report.id}`);
+    if (report.state === "blocked" && report.kind !== undefined && KINDS.includes(report.kind))
+        pairs.push(`kind=${report.kind}`);
+    const p = report.progress;
+    if ((report.state === "working" || report.state === "blocked") &&
+        p !== undefined &&
+        Number.isInteger(p) &&
+        p >= 0 &&
+        p <= 100)
+        pairs.push(`progress=${p}`);
+    if (report.app !== undefined && SEGMENT.test(report.app))
+        pairs.push(`app=${report.app}`);
+    if (report.state !== "clear") {
+        const title = encodeText(report.title, MAX_TITLE_BYTES);
+        if (title !== undefined)
+            pairs.push(`title=${title}`);
+        const msg = encodeText(report.msg, MAX_MSG_BYTES);
+        if (msg !== undefined)
+            pairs.push(`msg=${msg}`);
+    }
+    // 各字段已有上限，整条最多约 3.2 KB；仍超限就依次丢 msg、title
+    while (osc(pairs.join(":")).length > MAX_SEQUENCE_BYTES) {
+        const last = pairs.at(-1);
+        if (!last.startsWith("msg=") && !last.startsWith("title="))
+            return undefined;
+        pairs.pop();
+    }
+    return pairs.join(":");
+}
+function osc(body) {
+    return `\x1b]7501;${body}\x1b\\`;
+}
+/** 完整的 OSC 7501 序列；报告不合法返回 undefined（不发坏报告）。 */
+export function encodeProgramStatus(report) {
+    const pairs = encodePairs(report);
+    return pairs === undefined ? undefined : osc(pairs);
+}
+/** tmux DCS passthrough：`ESC P tmux; <内容，ESC 翻倍> ESC \`。 */
+export function tmuxPassthrough(sequence) {
+    return `\x1bPtmux;${sequence.replaceAll("\x1b", "\x1b\x1b")}\x1b\\`;
+}
+/** 终端对 `OSC 7501 ; ?` 的回复（`?` 之后的内容忽略）。 */
+export function isProgramStatusReply(sequence) {
+    return /^\x1b\]7501;\?/.test(sequence);
+}
+/** DA1 回复 `CSI ? … c`。 */
+export function isDa1Reply(sequence) {
+    return /^\x1b\[\?[\d;]*c$/.test(sequence);
+}
+/** 发射器：检测、同值去重、节流；只在 `supported` 后写。 */
+export class ProgramStatusEmitter {
+    options;
+    support = "unknown";
+    tmux;
+    desired = new Map();
+    sent = new Map();
+    timers = new Map();
+    probeTimer;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.tmux = Boolean(options.env?.["TMUX"]);
+        this.now = options.now ?? Date.now;
+    }
+    /** 当前是否会写出报告。 */
+    get supported() {
+        return this.support === "yes";
+    }
+    /** 按模式开始：on 直接启用，auto 发检测查询（tmux 里不检测，等同 off），off 什么都不做。 */
+    start() {
+        if (this.support !== "unknown")
+            return;
+        const mode = this.options.mode;
+        if (mode === "off" || (mode === "auto" && this.tmux)) {
+            this.support = "no";
+            return;
+        }
+        if (mode === "on")
+            return this.enable();
+        this.support = "probing";
+        this.options.write(PROGRAM_STATUS_QUERY + DA1_QUERY);
+        this.probeTimer = setTimeout(() => this.settleProbe(false), this.options.timeoutMs ?? 300);
+        this.probeTimer.unref?.();
+    }
+    /** 输入解析里调用：吞掉检测回复（返回 true），其余返回 false。 */
+    handleInput(sequence) {
+        if (isProgramStatusReply(sequence)) {
+            if (this.support === "probing")
+                this.settleProbe(true);
+            return true;
+        }
+        if (isDa1Reply(sequence)) {
+            if (this.support === "probing")
+                this.settleProbe(false);
+            return true;
+        }
+        return false;
+    }
+    /** 设定某个 id（缺省根记录）的状态；`clear` 同时忘掉该 id 及其下层的记录。 */
+    report(report) {
+        const key = report.id ?? "";
+        const full = this.options.app !== undefined ? { ...report, app: this.options.app } : report;
+        if (report.state === "clear") {
+            for (const id of [...this.desired.keys()])
+                if (key === "" || id === key || id.startsWith(`${key}/`))
+                    this.forget(id);
+        }
+        this.desired.set(key, full);
+        if (this.support === "yes")
+            this.flush(key);
+        if (report.state === "clear")
+            this.desired.delete(key);
+    }
+    /** 停止计时器（不再写任何东西）。 */
+    dispose() {
+        if (this.probeTimer !== undefined)
+            clearTimeout(this.probeTimer);
+        this.probeTimer = undefined;
+        for (const timer of this.timers.values())
+            clearTimeout(timer);
+        this.timers.clear();
+        if (this.support === "probing")
+            this.support = "no";
+    }
+    settleProbe(ok) {
+        if (this.probeTimer !== undefined)
+            clearTimeout(this.probeTimer);
+        this.probeTimer = undefined;
+        if (ok)
+            this.enable();
+        else
+            this.support = "no";
+    }
+    enable() {
+        this.support = "yes";
+        for (const key of this.desired.keys())
+            this.flush(key);
+    }
+    forget(id) {
+        this.desired.delete(id);
+        this.sent.delete(id);
+        const timer = this.timers.get(id);
+        if (timer !== undefined)
+            clearTimeout(timer);
+        this.timers.delete(id);
+    }
+    flush(key) {
+        const report = this.desired.get(key);
+        if (report === undefined)
+            return;
+        const body = encodePairs(report);
+        if (body === undefined)
+            return;
+        const last = this.sent.get(key);
+        if (last?.body === body)
+            return;
+        const throttle = this.options.throttleMs ?? 500;
+        const head = `${report.state}:${report.kind ?? ""}`;
+        const wait = last !== undefined && last.head === head ? last.at + throttle - this.now() : 0;
+        if (wait > 0 && report.state !== "clear") {
+            if (!this.timers.has(key)) {
+                const timer = setTimeout(() => {
+                    this.timers.delete(key);
+                    this.flush(key);
+                }, wait);
+                timer.unref?.();
+                this.timers.set(key, timer);
+            }
+            return;
+        }
+        const timer = this.timers.get(key);
+        if (timer !== undefined)
+            clearTimeout(timer);
+        this.timers.delete(key);
+        const sequence = osc(body);
+        this.options.write(this.tmux ? tmuxPassthrough(sequence) : sequence);
+        if (report.state === "clear")
+            this.sent.delete(key);
+        else
+            this.sent.set(key, { body, head, at: this.now() });
+    }
+}

package/docs/acp.md

@@ -60,13 +60,13 @@ ama --mode acp                      # 与 -p 互斥；其余参数（--model、-
 | 工具开始                            | `tool_call_update`（`in_progress`）                                                                                                                                                                                            |
 | 工具结束（含内层）                  | `tool_call_update`（`completed` / `failed`）；`content` 为 `[diff?, 文本]`：edit / write 带 `diff`（`path`、`oldText`、`newText`，新文件 `oldText: null`），文本只带前 4 KB；`locations[].line` 是首个改动行；不发 `rawOutput` |
 | `todo` 更新                         | `plan`                                                                                                                                                                                                                         |
-| 每轮结束                            | `usage_update`（上下文已用、窗口、会话累计美元）                                                                                                                                                                               |
+| 每条助手消息结束、每轮结束          | `usage_update`（上下文已用、窗口、会话累计美元）；与上次同值不重发                                                                                                                                                             |
 | 权限模式变化                        | `current_mode_update`                                                                                                                                                                                                          |
-| 模型 / 思考级别变化                 | `config_option_update`（全部配置项）                                                                                                                                                                                           |
-| 会话开出（new / load / resume）之后 | `available_commands_update` 与 `config_option_update`                                                                                                                                                                          |
+| 模型 / 思考级别变化                 | `config_option_update`（全部配置项）；换模型时另发一条 `usage_update`（窗口可能变了）                                                                                                                                          |
+| 会话开出（new / load / resume）之后 | `available_commands_update`、`config_option_update` 与 `usage_update`（load 在回放之后），客户端不用等第一轮结束                                                                                                               |
 | 回合结束之后                        | `session_info_update`（`updatedAt`；标题与上次不同才带 `title`）                                                                                                                                                               |
 
-diff 的改前 / 改后全文只随实时事件走，不写进会话文件：任一侧超过 256 KiB 不带 diff，`session/load` 回放的工具结果只有前 4 KB 文本。模式列表的 `name` 是显示名（如 `Manual`、`Accept edits`），`description` 随界面语言。`session/prompt` 的结果带本回合 token 用量 `usage`（`inputTokens`、`outputTokens`、`cachedReadTokens`、`cachedWriteTokens`、`totalTokens`）；该字段在 schema 1.24.1 里仍是 UNSTABLE（只在不稳定 schema 中），客户端可以忽略，以 `usage_update` 为准。
+diff 的改前 / 改后全文只随实时事件走，不写进会话文件：任一侧超过 256 KiB 不带 diff，`session/load` 回放的工具结果只有前 4 KB 文本。模式列表的 `name` 是显示名（如 `Manual`、`Accept edits`），`description` 随界面语言。`session/prompt` 的结果带本回合 token 用量 `usage`（`inputTokens`、`outputTokens`、`cachedReadTokens`、`cachedWriteTokens`、`totalTokens`）；该字段在 schema 1.24.1 里仍是 UNSTABLE（只在不稳定 schema 中），客户端可以忽略，以 `usage_update` 为准。模型窗口未知时（如没有 `contextWindow` 的自定义模型）不发 `usage_update`：schema 里 `size` 必填，ama 不编造窗口。
 
 `toolCallId` 在会话内唯一：上游供应商给的 id 若在后续回合重复（个别兼容接口的兜底 id、测试用假模型），线上 id 加 `#2`、`#3`… 区分，之后的状态更新、审批与回放都按这个映射（客户端按 id 合并条目，不区分会把不同调用合成一条）。
 

package/docs/agents.md

@@ -256,7 +256,7 @@ ACP Agent 不给 `modes`、改用 category `mode` 的配置项表达模式时，
 - **信任**：只在 ama 已信任的目录里起外部 Agent（`claude -p` 会跳过目录信任对话框并执行项目 hooks 与配置）；未信任时 `task` 报错并提示 `ama trust`。
 - **并发**：外部 Agent 总共 `agents.maxConcurrent`（缺省 3），每个 Agent 另有上限（`agents.<id>.maxConcurrent`，claude 缺省 2）；超出排队，排队可被中断。与 ama 子会话的并发分开计。
 - **预算**：`task` 的 `budgetUsd`（Claude 透传 `--max-budget-usd`，其余按用量累计、超限中断）；`agents.sessionBudgetUsd` 是本会话外部 Agent 的美元总额，用尽后不再启动。Codex 订阅 token、Copilot premium request 按各自单位记，不换算美元；Claude 的 `total_cost_usd` 是它自己的估算。
-- **记账**：每回合写 `custom{ama.agent-usage}`，会话建立写 `custom{ama.agent-session}`（外部 CLI 自己的会话 id，用于续聊）；`/session` 与 `get_session_stats` 的 `external` 段按 Agent 汇总。ama 会话只存最终文本、工具摘要、用量与引用，外部 Agent 的原始事件只在内存里显示，不落盘。
+- **记账**：每回合写 `custom{ama.agent-usage}`，会话建立写 `custom{ama.agent-session}`（外部 CLI 自己的会话 id，用于续聊）；`/session` 与 `get_session_stats` 的 `external` 段按 Agent 汇总。外部 Agent 报告了上下文占用与窗口（ACP 的 `usage_update`、Codex app-server 的 `tokenUsage`）时，只记这两个数字：任务记录与 `ama.agent-usage` 带 `contextTokens / contextWindow`，`external.byAgent` 取最近一次，`/tasks` 与 Agent 栏的任务行显示 `ctx 34%`（低于 10% 保留一位小数）；回合中途变化也会即时更新。ama 会话只存最终文本、工具摘要、用量与引用，外部 Agent 的原始事件只在内存里显示，不落盘。
 - **看门狗**：单回合缺省 30 分钟；中断后 15 秒内没有回合结束就关 stdin 再结束进程树；空闲 10 分钟关进程，能续接的下次续聊时以 resume 重开。外部 Agent 进程登记在 `<数据目录>/drivers/pids.json`，ama 异常退出留下的孤儿在下次使用时清理（核对命令行，pid 被复用的不杀）。
 
 ### 嵌入宿主

package/docs/en/acp.md

@@ -60,13 +60,13 @@ One `ama --mode acp` process can keep several sessions open (Zed's threads share
 | Tool starts                                 | `tool_call_update` (`in_progress`)                                                                                                                                                                                                                                         |
 | Tool ends (inner calls included)            | `tool_call_update` (`completed` / `failed`); `content` is `[diff?, text]`: edit / write carry a `diff` (`path`, `oldText`, `newText`; `oldText: null` for a new file), the text is limited to the first 4 KB; `locations[].line` is the first changed line; no `rawOutput` |
 | `todo` update                               | `plan`                                                                                                                                                                                                                                                                     |
-| End of each turn                            | `usage_update` (context used, window size, session cost in USD)                                                                                                                                                                                                            |
+| End of each assistant message and each turn | `usage_update` (context used, window size, session cost in USD); not resent when unchanged                                                                                                                                                                                 |
 | Permission mode change                      | `current_mode_update`                                                                                                                                                                                                                                                      |
-| Model / thinking level change               | `config_option_update` (all options)                                                                                                                                                                                                                                       |
-| After a session opens (new / load / resume) | `available_commands_update` and `config_option_update`                                                                                                                                                                                                                     |
+| Model / thinking level change               | `config_option_update` (all options); a model change also sends a `usage_update` (the window may differ)                                                                                                                                                                   |
+| After a session opens (new / load / resume) | `available_commands_update`, `config_option_update` and `usage_update` (for load, after the replay), so clients need not wait for the first turn                                                                                                                           |
 | After a turn                                | `session_info_update` (`updatedAt`; `title` only when it differs from the last one)                                                                                                                                                                                        |
 
-The full before / after text of a diff only travels with live events and is never written to the session file: above 256 KiB on either side there is no diff, and tool results replayed by `session/load` carry only their first 4 KB of text. The `name` of each mode is its display name (such as `Manual` or `Accept edits`); the `description` follows the UI language. The `session/prompt` result carries the turn's token usage `usage` (`inputTokens`, `outputTokens`, `cachedReadTokens`, `cachedWriteTokens`, `totalTokens`); in schema 1.24.1 this field is still UNSTABLE (only in the unstable schema), so clients may ignore it and rely on `usage_update`.
+The full before / after text of a diff only travels with live events and is never written to the session file: above 256 KiB on either side there is no diff, and tool results replayed by `session/load` carry only their first 4 KB of text. The `name` of each mode is its display name (such as `Manual` or `Accept edits`); the `description` follows the UI language. The `session/prompt` result carries the turn's token usage `usage` (`inputTokens`, `outputTokens`, `cachedReadTokens`, `cachedWriteTokens`, `totalTokens`); in schema 1.24.1 this field is still UNSTABLE (only in the unstable schema), so clients may ignore it and rely on `usage_update`. When the model's context window is unknown (such as a custom model without `contextWindow`), no `usage_update` is sent: `size` is required by the schema and ama does not make up a window.
 
 `toolCallId` is unique within a session: when the upstream provider reuses an id in a later turn (fallback ids of a few compatible APIs, the fake test model), the wire id gets `#2`, `#3`, … and later status updates, approvals and replay follow that mapping (clients merge entries by id, so without this different calls would collapse into one).
 

package/docs/en/providers.md

@@ -400,7 +400,7 @@ Inference order: conservative defaults ← inference table (provider id, then ba
 | `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                                       |
+| `supportsMidConvoSystemMessages`              | Later prompt patches go back as system messages in place; off (default): trailing context, see "Caching"                 |
 | `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`                                                                                                      |
@@ -439,6 +439,8 @@ 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.
+
 ### Request fields
 
 | Protocol                                  | Field                                                                                                   | Condition                                                                                                    |
@@ -476,7 +478,7 @@ If any cache field appears in the raw usage (even 0) → `Usage.cacheReported =
 
 ### 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[]`.
+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`; all DeepSeek models `short 3600 / minTokens 2048` (the vendor only says unused cache is cleared after "a few hours to a few days", so the conservative 1 hour is used; cache reads were measured in 2048-token blocks). Zhipu, Qwen, Groq, xAI, Mistral, OpenRouter and Google promise no TTL, so it stays empty: no warming and no early pruning on a guessed lifetime; only miss attribution assumes 10 minutes for implicit caching. You can fill it in yourself in `models[]` / `modelOverrides[]`; DeepSeek models on relays do not inherit the official catalog values, fill them in the same way if needed.
 
 ### Session layer: fingerprints, misses and three states
 
@@ -541,7 +543,7 @@ ama models cache-probe <provider/id> [--tokens 2048] [--gap-ms 3000] [--json] [-
 
 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;
+- `reported`: the second cacheRead ≥ 50% of the prefix; when the catalog has no `promptCache`, it explains that the lifetime is unknown (no warming, no early pruning) and to fill it in only with a lifetime the upstream documents, without suggesting a guessed value — a value that is too short fires warming and early pruning while the cache is still valid;
 - `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.
 

package/docs/en/rpc.md

@@ -285,6 +285,7 @@ The `data` of `get_session_stats` is `SessionStats`:
 | `tokens`                                                           | `{ input, output, cacheRead, cacheWrite, total }`, including warming requests                       |
 | `cost`                                                             | USD; absent when any message lacks a cost (the interface shows `$?`)                                |
 | `contextTokens` / `contextWindow` / `contextPercent`               | Current context estimate, window and usage (0–100); absent when the model has no window             |
+| `context`                                                          | Estimate source and auto-compaction thresholds (fields: sessions.md)                                |
 | `cacheHitRate`                                                     | The legacy hit rate: cacheRead / (input + cacheRead + cacheWrite), every request in the denominator |
 | `cache`                                                            | `SessionCacheStats` (example below), present only when the session-layer cache controller is wired  |
 
@@ -334,6 +335,8 @@ The `data` of `get_session_stats` is `SessionStats`:
 
 `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.
 
+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`.
+
 ## Approvals
 
 1. When a tool call needs confirmation, the server sends `permission_request`. `preview` (optional) is the pre-execution preview: `{ kind: "bash" | "write" | "edit" | "other", lines: string[], severity: "info" | "warn" | "danger", affected?: { path, exists, bytes?, files? }[] }`; `lines` are already laid out without colors and can be shown as is. The preview is read-only and bounded, and absent when it cannot be computed.

package/docs/en/sessions.md

@@ -61,6 +61,29 @@ those notification turns are written to the same session file.
 - A per-file summary is cached in `<data dir>/stats-index.json`, invalidated by file mtime and size; a time-zone change invalidates the whole index; a full scan also drops files that no longer exist. `--no-cache` neither reads nor writes it.
 - Measured (local machine, `src/session/stats-perf.test.ts`): 1000 sessions, 67 MB (12 turns, 24 tool calls and 2 KB tool results each), about 160 ms cold and about 15 ms with the index.
 
+## Context usage of the current session (`getStats()` / `get_session_stats`)
+
+`ama stats` reports historical billed usage; how much context the running session has left is in the context fields of
+`SessionStats` (SDK `session.getStats()`, passed through unchanged by RPC `get_session_stats`; the status bar and `/session` read
+the same fields):
+
+| Field                    | Meaning                                                                                                                                                                                                      |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `contextTokens`          | Estimated tokens of context the next request will carry (see `context.source` for how)                                                                                                                       |
+| `contextWindow`          | The current model's window; **absent** when the model has no window information (fix it with `ama models discover` or by setting `contextWindow` for the model in config)                                    |
+| `contextPercent`         | `contextTokens / contextWindow`, 0–100 with one decimal, capped at 100; **absent** without a window (the UI shows `ctx ?`)                                                                                   |
+| `context.source`         | `usage`: usage of the last valid assistant message + an estimate of the messages after it; `estimate`: no trustworthy usage, the whole context is estimated; `prefix`: the baseline before the first request |
+| `context.usageTokens`    | The part taken from usage; 0 for `estimate` / `prefix`                                                                                                                                                       |
+| `context.trailingTokens` | The estimated part (messages after the usage, or the whole estimate / baseline)                                                                                                                              |
+| `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                                                                                             |
+
+- **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.
+- **An absent field means "unknown"**, not 0: `contextWindow`, `contextPercent`, `context.autoCompactAt` and `context.pruneAt` are left out of the JSON when absent. Older versions or custom session implementations may not have `context`; reading `contextTokens` is enough there.
+- `tokens` (`{ input, output, cacheRead, cacheWrite, total }`) is the **session total** of billed usage, including requests that never enter the context (compaction summaries, cache warming); do not read it as context usage.
+
 ## Search: `ama sessions search`
 
 ```
@@ -178,7 +201,7 @@ Rolling back code (`/rewind`, design in [rewind-plan.md](../rewind-plan.md), Chi
 - **Snapshots**: at the start of a new turn, `git add -A` + `write-tree` + `commit-tree` (parent: the previous shadow commit), with the commit id recorded as the checkpoint's `shadowCommit`. The shadow repository uses a fixed identity and empty global / system config (your signing, hooks, filters and templates are not read), `core.autocrlf=false` with line-ending conversion off, so raw disk bytes are stored; `gc.auto=0`.
 - **Ignores**: `.gitignore` in the working directory applies; when the working directory is inside a git repository, paths your repository ignores (parent `.gitignore` files, `info/exclude`, the global ignore file) stay out of the shadow repository too; `.git` is always excluded.
 - **Restore**: the current working directory is written as a tree and compared with the target commit, so only differing files are processed; conflict and safety checks are the same as in `tools` (symbolic links, hard links, non-regular files and directories on the path replaced by links are skipped). The "known" current content = what is in the latest shadow snapshot, what ama last wrote or what the latest checkpoint recorded; anything else counts as a change outside the turn and is skipped by default. Ignored files are left alone; files changed by edit / write but not in the shadow repository (outside the working directory, ignored) restore from the `tools` records. When the target checkpoint has no shadow commit (after a downgrade, or the shadow repository was deleted) the whole restore follows `tools`.
-- **Guards**: in these cases the session downgrades to `tools` with a one-time notice: `git` is not on PATH; the working directory (ignored files excluded) has more than 20 000 files (checked before the first snapshot); a single snapshot takes longer than 3 seconds (that commit is kept). It is not enabled when the working directory is the home directory or the file-system root.
+- **Guards**: in these cases the session downgrades to `tools` with a one-time notice: `git` is not on PATH; the working directory (ignored files excluded) has more than 20 000 files (checked before the first snapshot); a single snapshot takes longer than 3 seconds (that commit is kept; creating the shadow repository the first time does not count). It is not enabled when the working directory is the home directory or the file-system root.
 - **Limitations**:
   - bash changes in the latest turn enter a snapshot only when the next turn starts; rolling back before that, they cannot be told apart from manual changes and count as conflicts (overwriting is an option).
   - git only records the executable bit: restore only adjusts the executable bit and keeps other permission bits; symbolic links and submodules are not restored.