@armadra/agent 0.7.1 → 0.7.2

package/dist/i18n/messages/interactive.d.ts

@@ -93,6 +93,10 @@ export declare const en: {
         cacheSilent: string;
         sandbox: string;
         cycleHint: string;
+        /** full 本行 Ctx 段末尾：自动压缩开着。 */
+        autoCompact: string;
+        /** 模型没有上下文窗口（状态栏 `ctx ?`）时提示一次。 */
+        noWindow: (model: string) => string;
         /** [W6] 订阅配额行（full 第三行）与窄屏 / compact 短格式；标签自带分隔（英文冒号后空格）。 */
         quota: {
             session: string;
@@ -339,6 +343,8 @@ export declare const zh: {
         cacheSilent: string;
         sandbox: string;
         cycleHint: string;
+        autoCompact: string;
+        noWindow: (model: string) => string;
         quota: {
             session: string;
             reset: string;

package/dist/i18n/messages/interactive.js

@@ -107,6 +107,10 @@ export const en = {
         cacheSilent: "n/a",
         sandbox: "sandbox",
         cycleHint: "shift+tab to cycle",
+        /** full 本行 Ctx 段末尾：自动压缩开着。 */
+        autoCompact: "auto",
+        /** 模型没有上下文窗口（状态栏 `ctx ?`）时提示一次。 */
+        noWindow: (model) => `Context window unknown for ${model}: the status bar shows ctx ? and auto-compaction is off. Run \`ama models discover\` or set contextWindow for this model in the config.`,
         /** [W6] 订阅配额行（full 第三行）与窄屏 / compact 短格式；标签自带分隔（英文冒号后空格）。 */
         quota: {
             session: "Session: ",
@@ -238,6 +242,8 @@ export const zh = {
         cacheSilent: "未报告",
         sandbox: "沙箱",
         cycleHint: "shift+tab 切换",
+        autoCompact: "auto",
+        noWindow: (model) => `${model} 没有上下文窗口信息：状态栏显示 ctx ?，自动压缩关闭。运行 \`ama models discover\`，或在配置里为该模型设置 contextWindow。`,
         quota: {
             session: "5 小时：",
             reset: "重置：",

package/dist/i18n/messages/panels.d.ts

@@ -109,6 +109,8 @@ export declare const en: {
             interrupted: string;
         };
         turns: (n: number) => string;
+        /** 外部 Agent 报告的上下文占用（`34%`、`0.4%`）。 */
+        context: (percent: string) => string;
         agentRunner: (agent: string, runner: string) => string;
         background: string;
         none: string;
@@ -219,6 +221,7 @@ export declare const zh: {
             interrupted: string;
         };
         turns: (n: number) => string;
+        context: (percent: string) => string;
         agentRunner: (agent: string, runner: string) => string;
         background: string;
         none: string;

package/dist/i18n/messages/panels.js

@@ -20,7 +20,7 @@ export const en = {
         user: (n) => `user ${n}`,
         assistant: (n) => `assistant ${n}`,
         toolCalls: (n) => `tool calls ${n}`,
-        usage: "Usage",
+        usage: "Total usage",
         input: (tokens) => `input ${tokens}`,
         output: (tokens) => `output ${tokens}`,
         cacheRead: (tokens) => `cache read ${tokens}`,
@@ -109,6 +109,8 @@ export const en = {
             interrupted: "interrupted",
         },
         turns: (n) => plural(n, "turn"),
+        /** 外部 Agent 报告的上下文占用（`34%`、`0.4%`）。 */
+        context: (percent) => `ctx ${percent}`,
         agentRunner: (agent, runner) => `${agent} (${runner})`,
         background: "background",
         none: "No subagent tasks yet",
@@ -131,7 +133,7 @@ export const zh = {
         user: (n) => `用户 ${n}`,
         assistant: (n) => `助手 ${n}`,
         toolCalls: (n) => `工具调用 ${n}`,
-        usage: "用量",
+        usage: "累计用量",
         input: (tokens) => `输入 ${tokens}`,
         output: (tokens) => `输出 ${tokens}`,
         cacheRead: (tokens) => `缓存读 ${tokens}`,
@@ -219,6 +221,7 @@ export const zh = {
             interrupted: "已中断",
         },
         turns: (n) => `${n} 轮`,
+        context: (percent) => `ctx ${percent}`,
         agentRunner: (agent, runner) => `${agent}（${runner}）`,
         background: "后台",
         none: "还没有子 Agent 任务",

package/dist/i18n/messages/report-context.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 消息目录：report 的 `/context` 部分（键名规范见 docs/i18n.md）。
+ *
+ * 单文件 600 行上限，从 `report.ts` 拆出；经 `msg().report.contextReport` 取用（modes/context-report.ts）。
+ * 只有数字与名字的格式，不含任何正文。en 是形状源；zh 用 `satisfies Messages<typeof en>`。
+ */
+export declare const en: {
+    title: string;
+    keyUsed: string;
+    used: (tokens: string, window: string, percent: string | undefined) => string;
+    keyLeft: string;
+    left: (tokens: string) => string;
+    keySource: string;
+    sourceUsage: (usage: string, estimate: string) => string;
+    sourceEstimate: string;
+    keyAutoCompact: string;
+    autoCompact: (at: string, distance: string) => string;
+    autoCompactReached: (at: string) => string;
+    autoCompactOff: string;
+    windowUnknown: string;
+    keyPrune: string;
+    prune: (at: string) => string;
+    breakdown: (total: string) => string;
+    prefixCounted: string;
+    prefixPending: string;
+    categories: {
+        system: string;
+        tools: string;
+        user: string;
+        assistant: string;
+        reasoning: string;
+        toolCalls: string;
+        toolResults: string;
+        images: string;
+        summaries: string;
+        custom: string;
+    };
+    partNames: {
+        compaction: string;
+        branch: string;
+        user: string;
+        toolResult: string;
+        custom: string;
+    };
+    images: (count: number) => string;
+    more: (count: number) => string;
+    largest: (count: number) => string;
+    noToolResults: string;
+    empty: string;
+};
+export declare const zh: {
+    title: string;
+    keyUsed: string;
+    used: (tokens: string, window: string, percent: string | undefined) => string;
+    keyLeft: string;
+    left: (tokens: string) => string;
+    keySource: string;
+    sourceUsage: (usage: string, estimate: string) => string;
+    sourceEstimate: string;
+    keyAutoCompact: string;
+    autoCompact: (at: string, distance: string) => string;
+    autoCompactReached: (at: string) => string;
+    autoCompactOff: string;
+    windowUnknown: string;
+    keyPrune: string;
+    prune: (at: string) => string;
+    breakdown: (total: string) => string;
+    prefixCounted: string;
+    prefixPending: string;
+    categories: {
+        system: string;
+        tools: string;
+        user: string;
+        assistant: string;
+        reasoning: string;
+        toolCalls: string;
+        toolResults: string;
+        images: string;
+        summaries: string;
+        custom: string;
+    };
+    partNames: {
+        compaction: string;
+        branch: string;
+        user: string;
+        toolResult: string;
+        custom: string;
+    };
+    images: (count: number) => string;
+    more: (count: number) => string;
+    largest: (count: number) => string;
+    noToolResults: string;
+    empty: string;
+};

package/dist/i18n/messages/report-context.js

@@ -0,0 +1,95 @@
+/**
+ * 消息目录：report 的 `/context` 部分（键名规范见 docs/i18n.md）。
+ *
+ * 单文件 600 行上限，从 `report.ts` 拆出；经 `msg().report.contextReport` 取用（modes/context-report.ts）。
+ * 只有数字与名字的格式，不含任何正文。en 是形状源；zh 用 `satisfies Messages<typeof en>`。
+ */
+import { plural } from "../format.js";
+export const en = {
+    title: "Context",
+    keyUsed: "Used",
+    used: (tokens, window, percent) => `${tokens} / ${window}${percent !== undefined ? ` (${percent})` : ""}`,
+    keyLeft: "Left",
+    left: (tokens) => `${tokens} tokens`,
+    keySource: "Source",
+    sourceUsage: (usage, estimate) => `reported usage ${usage} + estimated ${estimate}`,
+    sourceEstimate: "estimated in full (no usable usage yet)",
+    keyAutoCompact: "Auto-compact",
+    autoCompact: (at, distance) => `at ${at}, ≈ ${distance} to go`,
+    autoCompactReached: (at) => `at ${at}, reached`,
+    autoCompactOff: "off",
+    windowUnknown: "window unknown",
+    keyPrune: "Pruning",
+    prune: (at) => `old tool results trimmed from ${at}`,
+    breakdown: (total) => `By category (estimated, ${total})`,
+    prefixCounted: "System prompt and tool declarations are counted from the stored system messages; the full estimate can differ from reported usage.",
+    prefixPending: "System prompt and tool declarations are not counted until the first request.",
+    categories: {
+        system: "System prompt",
+        tools: "Tool declarations",
+        user: "User messages",
+        assistant: "Assistant text",
+        reasoning: "Reasoning",
+        toolCalls: "Tool-call arguments",
+        toolResults: "Tool results",
+        images: "Images",
+        summaries: "Summaries",
+        custom: "Custom messages",
+    },
+    partNames: {
+        compaction: "compaction",
+        branch: "branch",
+        user: "user",
+        toolResult: "tool result",
+        custom: "custom",
+    },
+    images: (count) => plural(count, "image"),
+    more: (count) => `+${count} more`,
+    largest: (count) => `Largest tool results (top ${count})`,
+    noToolResults: "no tool results",
+    empty: "No messages in the context yet.",
+};
+export const zh = {
+    title: "上下文",
+    keyUsed: "已用",
+    used: (tokens, window, percent) => `${tokens} / ${window}${percent !== undefined ? `（${percent}）` : ""}`,
+    keyLeft: "剩余",
+    left: (tokens) => `${tokens} token`,
+    keySource: "来源",
+    sourceUsage: (usage, estimate) => `usage 实测 ${usage} + 估算 ${estimate}`,
+    sourceEstimate: "全量估算（还没有可用的 usage）",
+    keyAutoCompact: "自动压缩",
+    autoCompact: (at, distance) => `${at} 触发，还差 ≈ ${distance}`,
+    autoCompactReached: (at) => `${at} 触发，已达到`,
+    autoCompactOff: "关闭",
+    windowUnknown: "窗口未知",
+    keyPrune: "裁剪",
+    prune: (at) => `超过 ${at} 时清理旧工具结果`,
+    breakdown: (total) => `按类别（估算，${total}）`,
+    prefixCounted: "系统提示与工具声明按会话里存的 system 消息计入；全量估算可能与 usage 实测不同。",
+    prefixPending: "系统提示与工具声明在首次请求后才计入。",
+    categories: {
+        system: "系统提示",
+        tools: "工具声明",
+        user: "用户消息",
+        assistant: "助手文本",
+        reasoning: "推理",
+        toolCalls: "工具调用参数",
+        toolResults: "工具结果",
+        images: "附件图片",
+        summaries: "摘要",
+        custom: "自定义消息",
+    },
+    partNames: {
+        compaction: "压缩",
+        branch: "分支",
+        user: "用户",
+        toolResult: "工具结果",
+        custom: "自定义",
+    },
+    images: (count) => `${count} 张`,
+    more: (count) => `另有 ${count} 项`,
+    largest: (count) => `最大的工具结果（前 ${count}）`,
+    noToolResults: "没有工具结果",
+    empty: "上下文里还没有消息。",
+};

package/dist/i18n/messages/report.d.ts

@@ -29,6 +29,7 @@ export declare const en: {
         tools: string;
         hooks: string;
         session: string;
+        context: string;
         cache: string;
         statusline: string;
         planArgs: string;
@@ -86,6 +87,51 @@ export declare const en: {
         cwdAnswer: string;
         notDirectory: (path: string) => string;
     };
+    /** `/context`：上下文分类明细（report-context.ts）。 */
+    contextReport: {
+        title: string;
+        keyUsed: string;
+        used: (tokens: string, window: string, percent: string | undefined) => string;
+        keyLeft: string;
+        left: (tokens: string) => string;
+        keySource: string;
+        sourceUsage: (usage: string, estimate: string) => string;
+        sourceEstimate: string;
+        keyAutoCompact: string;
+        autoCompact: (at: string, distance: string) => string;
+        autoCompactReached: (at: string) => string;
+        autoCompactOff: string;
+        windowUnknown: string;
+        keyPrune: string;
+        prune: (at: string) => string;
+        breakdown: (total: string) => string;
+        prefixCounted: string;
+        prefixPending: string;
+        categories: {
+            system: string;
+            tools: string;
+            user: string;
+            assistant: string;
+            reasoning: string;
+            toolCalls: string;
+            toolResults: string;
+            images: string;
+            summaries: string;
+            custom: string;
+        };
+        partNames: {
+            compaction: string;
+            branch: string;
+            user: string;
+            toolResult: string;
+            custom: string;
+        };
+        images: (count: number) => string;
+        more: (count: number) => string;
+        largest: (count: number) => string;
+        noToolResults: string;
+        empty: string;
+    };
     /** `/session`、`/cache` 报告与缓存提示行。 */
     cache: {
         unreported: string;
@@ -145,6 +191,9 @@ export declare const en: {
         usage: (input: number, output: number, cacheRead: number, cacheWrite: number, cost: string) => string;
         keyContext: string;
         context: (tokens: string, window: string, percent: string) => string;
+        /** 上下文行末尾：距自动压缩（档二）还有多少 token；自动压缩关闭 / 熔断时换成 autoCompactOff。 */
+        toAutoCompact: (tokens: string) => string;
+        autoCompactOff: string;
         keyAgents: string;
         externalTitle: string;
         noFingerprint: string;
@@ -225,6 +274,7 @@ export declare const zh: {
         tools: string;
         hooks: string;
         session: string;
+        context: string;
         cache: string;
         statusline: string;
         planArgs: string;
@@ -280,6 +330,50 @@ export declare const zh: {
         cwdAnswer: string;
         notDirectory: (path: string) => string;
     };
+    contextReport: {
+        title: string;
+        keyUsed: string;
+        used: (tokens: string, window: string, percent: string | undefined) => string;
+        keyLeft: string;
+        left: (tokens: string) => string;
+        keySource: string;
+        sourceUsage: (usage: string, estimate: string) => string;
+        sourceEstimate: string;
+        keyAutoCompact: string;
+        autoCompact: (at: string, distance: string) => string;
+        autoCompactReached: (at: string) => string;
+        autoCompactOff: string;
+        windowUnknown: string;
+        keyPrune: string;
+        prune: (at: string) => string;
+        breakdown: (total: string) => string;
+        prefixCounted: string;
+        prefixPending: string;
+        categories: {
+            system: string;
+            tools: string;
+            user: string;
+            assistant: string;
+            reasoning: string;
+            toolCalls: string;
+            toolResults: string;
+            images: string;
+            summaries: string;
+            custom: string;
+        };
+        partNames: {
+            compaction: string;
+            branch: string;
+            user: string;
+            toolResult: string;
+            custom: string;
+        };
+        images: (count: number) => string;
+        more: (count: number) => string;
+        largest: (count: number) => string;
+        noToolResults: string;
+        empty: string;
+    };
     cache: {
         unreported: string;
         unknown: string;
@@ -337,6 +431,8 @@ export declare const zh: {
         usage: (input: number, output: number, cacheRead: number, cacheWrite: number, cost: string) => string;
         keyContext: string;
         context: (tokens: string, window: string, percent: string) => string;
+        toAutoCompact: (tokens: string) => string;
+        autoCompactOff: string;
         keyAgents: string;
         externalTitle: string;
         noFingerprint: string;

package/dist/i18n/messages/report.js

@@ -9,6 +9,7 @@
  * `formatTokens` / `formatUsd` / `formatPercent` 的结果、`streaming` / `idle` 之类的枚举值不译。
  */
 import { plural } from "../format.js";
+import * as contextReport from "./report-context.js";
 export const en = {
     /** 内置斜杠命令：`args` 只写需要翻译的占位，说明整句。 */
     commands: {
@@ -29,6 +30,7 @@ export const en = {
         tools: "List / set active tools",
         hooks: "List loaded hooks",
         session: "Session info, usage and cache",
+        context: "Context breakdown by category (estimated), source, window and auto-compact threshold",
         cache: "Cache stats; switch warming for this session; print the prefix fingerprint",
         statusline: "Footer info two lines / one line (Ctrl+G)",
         planArgs: "[goal] | approve [mode|fresh] | reject",
@@ -86,6 +88,8 @@ export const en = {
         cwdAnswer: "Replacement directory (empty line cancels): ",
         notDirectory: (path) => `Not a directory: ${path}\n`,
     },
+    /** `/context`：上下文分类明细（report-context.ts）。 */
+    contextReport: contextReport.en,
     /** `/session`、`/cache` 报告与缓存提示行。 */
     cache: {
         unreported: "not reported",
@@ -186,10 +190,13 @@ export const en = {
         model: (model, thinking, permission) => `${model} · thinking ${thinking} · permission ${permission}`,
         keyMessages: "Messages",
         messages: (user, assistant, tools) => `user ${user} · assistant ${assistant} · tool calls ${tools}`,
-        keyUsage: "Usage",
+        keyUsage: "Total usage",
         usage: (input, output, cacheRead, cacheWrite, cost) => `input ${input} · output ${output} · cache read ${cacheRead} · cache write ${cacheWrite} · ${cost}`,
         keyContext: "Context",
         context: (tokens, window, percent) => `${tokens} / ${window} (${percent}%)`,
+        /** 上下文行末尾：距自动压缩（档二）还有多少 token；自动压缩关闭 / 熔断时换成 autoCompactOff。 */
+        toAutoCompact: (tokens) => `≈ ${tokens} until auto-compaction`,
+        autoCompactOff: "auto-compaction off",
         keyAgents: "Sub-agents",
         externalTitle: "External agents",
         noFingerprint: "This session does not provide a prefix fingerprint",
@@ -276,6 +283,7 @@ export const zh = {
         tools: "列出 / 设置活动工具",
         hooks: "列出已加载的 Hook",
         session: "会话信息、用量与缓存",
+        context: "上下文按类别拆分（估算）、来源、窗口与自动压缩阈值",
         cache: "缓存统计；切换本会话保温；打印前缀指纹",
         statusline: "底部信息行两行 / 一行（Ctrl+G）",
         planArgs: "[目标] | approve [模式|fresh] | reject",
@@ -331,6 +339,7 @@ export const zh = {
         cwdAnswer: "替代目录（空行取消）：",
         notDirectory: (path) => `不是目录：${path}\n`,
     },
+    contextReport: contextReport.zh,
     cache: {
         unreported: "未报告",
         unknown: "未知",
@@ -426,10 +435,12 @@ export const zh = {
         model: (model, thinking, permission) => `${model} · 思考 ${thinking} · 权限 ${permission}`,
         keyMessages: "消息",
         messages: (user, assistant, tools) => `用户 ${user} · 助手 ${assistant} · 工具调用 ${tools}`,
-        keyUsage: "用量",
+        keyUsage: "累计用量",
         usage: (input, output, cacheRead, cacheWrite, cost) => `输入 ${input} · 输出 ${output} · 缓存读 ${cacheRead} · 缓存写 ${cacheWrite} · ${cost}`,
         keyContext: "上下文",
         context: (tokens, window, percent) => `${tokens} / ${window}（${percent}%）`,
+        toAutoCompact: (tokens) => `距自动压缩 ≈ ${tokens}`,
+        autoCompactOff: "自动压缩关闭",
         keyAgents: "子 Agent",
         externalTitle: "外部 Agent",
         noFingerprint: "当前会话不提供前缀指纹",

package/dist/i18n/messages/settings.d.ts

@@ -29,6 +29,7 @@ export declare const en: {
         "ui.statusLine": string;
         "ui.restoreOnCancel": string;
         "ui.enterWhileRunning": string;
+        "ui.programStatus": string;
         "ui.quietStartup": string;
         "ui.ascii": string;
         "ui.language": string;
@@ -207,6 +208,7 @@ export declare const zh: {
         "ui.statusLine": string;
         "ui.restoreOnCancel": string;
         "ui.enterWhileRunning": string;
+        "ui.programStatus": string;
         "ui.quietStartup": string;
         "ui.ascii": string;
         "ui.language": string;

package/dist/i18n/messages/settings.js

@@ -29,6 +29,7 @@ export const en = {
         "ui.statusLine": "Status line",
         "ui.restoreOnCancel": "Restore on cancel",
         "ui.enterWhileRunning": "Enter while running",
+        "ui.programStatus": "Terminal program status",
         "ui.quietStartup": "Startup screen",
         "ui.ascii": "ASCII glyphs",
         "ui.language": "Interface language",
@@ -201,6 +202,7 @@ export const zh = {
         "ui.statusLine": "底部信息行",
         "ui.restoreOnCancel": "中断后放回原消息",
         "ui.enterWhileRunning": "运行中按 Enter",
+        "ui.programStatus": "终端程序状态",
         "ui.quietStartup": "启动画面",
         "ui.ascii": "ASCII 字形",
         "ui.language": "界面语言",

package/dist/i18n/messages/subcommands.js

@@ -206,7 +206,7 @@ export const en = {
                 ? " (the response has cache fields but they stay 0; cache writes may also be delayed, try a larger --gap-ms)"
                 : ""),
         adviceInconclusive: "The second request read only a little cache or only wrote: maybe cache granularity or TTL; retry with a larger --tokens or a shorter --gap-ms",
-        advicePromptCache: (provider, id) => `Fill in promptCache.short yourself to enable warming (providers.${provider}.modelOverrides: [{ "id": "${id}", "promptCache": { "short": 300 } }])`,
+        advicePromptCache: (provider, id) => `The catalog has no cache lifetime for this model, so ama neither warms it nor prunes early. Fill in promptCache only with a lifetime the upstream documents (providers.${provider}.modelOverrides: [{ "id": "${id}", "promptCache": { "short": <seconds> } }]); a guessed short value fires warming and early pruning while the cache is still valid`,
         intAtLeast: (name, min) => `--${name} must be an integer ≥ ${min}`,
         yes: "yes",
         no: "no",
@@ -439,7 +439,7 @@ export const zh = {
                 ? "（响应里有缓存字段但恒为 0；也可能是缓存写入有延迟，可加大 --gap-ms 再测一次）"
                 : ""),
         adviceInconclusive: "第二次只读到少量缓存或只有写入：可能是缓存粒度或 TTL 问题，可加大 --tokens 或缩短 --gap-ms 重试",
-        advicePromptCache: (provider, id) => `可自填 promptCache.short 以启用保温（providers.${provider}.modelOverrides: [{ "id": "${id}", "promptCache": { "short": 300 } }]）`,
+        advicePromptCache: (provider, id) => `目录里没有这个模型的缓存寿命，ama 不保温、也不提前裁剪。只有上游文档写明了寿命时才填 promptCache（providers.${provider}.modelOverrides: [{ "id": "${id}", "promptCache": { "short": <秒数> } }]）；猜一个偏短的值会在缓存仍有效时触发保温和提前裁剪`,
         intAtLeast: (name, min) => `--${name} 应为不小于 ${min} 的整数`,
         yes: "有",
         no: "无",

package/dist/modes/acp/acp-events.d.ts

@@ -12,9 +12,13 @@
  * | permission_resolved（allow / allow_session）| tool_call_update（in_progress）                                |
  * | tool_execution_end                        | tool_call_update（completed / failed，`[diff?, text]`，locations[].line） |
  * | todo_updated                              | plan                                                             |
- * | turn_end                                  | usage_update（上下文用量、窗口、会话累计美元）                   |
+ * | message_end（助手）/ turn_end             | usage_update（上下文用量、窗口、会话累计美元；与上次同值不发）   |
  * | permission_mode_changed                   | current_mode_update + config_option_update                       |
- * | model_changed / thinking_level_changed    | config_option_update                                             |
+ * | model_changed                             | config_option_update + usage_update（窗口可能变了，不去重）      |
+ * | thinking_level_changed                    | config_option_update                                             |
+ *
+ * new / load（回放之后）/ resume 的答复发出后，{@link AcpEventMapper.announce} 另发一条 `usage_update`，
+ * 客户端不用等第一轮结束就能显示用量。模型窗口未知时不发：schema 里 `size` 必填，不编造窗口。
  *
  * 工具结果只回前 4 KB 文本（完整结果在 ama 会话里）；diff 只在实时事件里有（`fileChange` 不落盘）。
  * `session/load` 回放同一套映射（用户消息 → user_message_chunk，工具结果带文本、无 diff）。
@@ -55,13 +59,18 @@ export declare class AcpEventMapper {
     private readonly usedWireIds;
     /** 上次 `session_info_update` 带出的标题。 */
     private lastTitle;
+    /** 上次 `usage_update` 的内容（同值不重发）。 */
+    private lastUsage;
     constructor(cwd: string, emit: (update: AcpSessionUpdate) => void, session: () => AgentSession, 
     /** 会话的配置项与命令表（{@link announce} 与配置变化时取；[ACP-D] 填实际内容）。 */
     extras?: () => {
         configOptions: AcpSessionConfigOption[];
         commands: AcpAvailableCommand[];
     });
-    /** 会话 new / load / resume 的响应发出后由服务端调：`available_commands_update` 与 `config_option_update`。 */
+    /**
+     * 会话 new / load / resume 的响应发出后由服务端调：`available_commands_update`、`config_option_update`
+     * 与 `usage_update`（客户端可能刚重建线程，用量不去重，照发一次）。
+     */
     announce(): void;
     /** 回合结束后由服务端调：`session_info_update`（标题与上次不同才带 title）。 */
     emitSessionInfo(title: string | null, updatedAt: string): void;
@@ -73,7 +82,11 @@ export declare class AcpEventMapper {
     wireId(toolCallId: string): string;
     private claimWireId;
     onEvent(event: SessionEvent): void;
-    emitUsage(): void;
+    /**
+     * 发一条 `usage_update`：上下文用量、窗口与会话累计美元。窗口未知时不发（`size` 必填）；
+     * 与上次内容相同时不发，`force` 时照发。
+     */
+    emitUsage(force?: boolean): void;
     /** `session/load`：按消息回放历史（工具结果带前 4 KB 文本；diff 不落盘，回放没有）。 */
     replay(messages: readonly AgentMessage[]): void;
     private status;