@armadra/agent 0.7.1 → 0.7.3

package/docs/providers.md

@@ -561,7 +561,7 @@ src/ai/providers/catalog.test.ts` 自动删除并重新生成 `catalog-data.ts`
 | `requiresReasoningContentOnAssistantMessages` | 推理模型的历史助手消息带 `reasoning_content`（DeepSeek）                                                                 |
 | `requiresToolResultName`                      | 工具结果消息带 `name`（Mistral）                                                                                         |
 | `requiresAssistantAfterToolResult`            | 工具结果后紧跟用户消息时插入一条助手消息                                                                                 |
-| `supportsMidConvoSystemMessages`              | 后续系统提示补丁按位置作为 system 消息插回                                                                               |
+| `supportsMidConvoSystemMessages`              | 后续系统提示补丁按位置作为 system 消息插回；关闭（缺省）时作为尾部上下文送达，见「缓存」                                 |
 | `cacheControlFormat`                          | `anthropic`：在 system、最后一个工具、最后一条 user/tool 消息上打 `cache_control`                                        |
 | `supportsStrictTools`                         | 对严格兼容的工具 schema 发 `strict: true`                                                                                |
 | `supportsStore`                               | 发 `store: false`                                                                                                        |
@@ -603,6 +603,8 @@ 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 检查点并回开头。
+
 ### 请求字段
 
 | 协议                                     | 字段                                                                                     | 条件                                                                                     |
@@ -650,9 +652,10 @@ Anthropic 的 `baseUrl` 以 `/v1` 结尾时请求 `{baseUrl}/messages`，不会
 ### 模型目录 `promptCache`
 
 只写有公开依据的值（秒 / token）：Anthropic 全部 `short 300 / long 3600`，`minTokens` 按模型 512–4096；OpenAI
-全部 `short 300 / long 86400 / minTokens 1024`；Kimi 全部 `short 300`。DeepSeek、智谱、通义、Groq、xAI、Mistral、
-OpenRouter、Google 没有承诺的 TTL，留空（不保温，归因按隐式缓存 10 分钟估）。可在 `models[]` /
-`modelOverrides[]` 里自填。
+全部 `short 300 / long 86400 / minTokens 1024`；Kimi 全部 `short 300`；DeepSeek 全部 `short 3600 / minTokens 2048`
+（官方只说未使用的缓存「几小时到几天」后清除，取保守的 1 小时；缓存读实测按 2048 token 一块计）。智谱、通义、Groq、
+xAI、Mistral、OpenRouter、Google 没有承诺的 TTL，留空：不保温、不按猜测的寿命提前裁剪，只有未命中归因按隐式缓存
+10 分钟估。可在 `models[]` / `modelOverrides[]` 里自填；中转上的 DeepSeek 模型不继承官方目录的值，需要时照填。
 
 ### 会话层：指纹、未命中与三态
 
@@ -717,7 +720,7 @@ ama models cache-probe <provider/id> [--tokens 2048] [--gap-ms 3000] [--json] [-
 
 用一个确定性的固定前缀（约 `--tokens` token）+ `Reply with: ok`，`maxTokens: 16`，相隔 `--gap-ms` 发两次，判定：
 
-- `reported`：第二次 cacheRead ≥ 前缀的 50%；目录没有 `promptCache` 时建议自填 `promptCache.short` 以启用保温；
+- `reported`：第二次 cacheRead ≥ 前缀的 50%；目录没有 `promptCache` 时提示寿命未知（不保温、不提前裁剪），只有上游文档写明寿命时才自填，不给猜测值——偏短的值会在缓存仍有效时触发保温和提前裁剪；
 - `silent`：两次读写都是 0；建议设 `compat.cacheReporting: "silent"`。响应里有缓存字段但恒为 0 时另提示可能是写入延迟（同一中转的 kimi-k2.5 间隔 3 秒两次都是 0、间隔 8 秒第二次读满前缀），可加大 `--gap-ms` 重试；
 - `inconclusive`：读到一点或只有写入，多半是缓存粒度或 TTL 问题。
 

package/docs/rpc.md

@@ -292,6 +292,7 @@
 | `tokens`                                                           | `{ input, output, cacheRead, cacheWrite, total }`，含保温请求的用量         |
 | `cost`                                                             | 美元；任一条消息缺成本时缺省（界面显示 `$?`）                               |
 | `contextTokens` / `contextWindow` / `contextPercent`               | 当前上下文估算、窗口与占用（0–100）；模型没有窗口时缺省                     |
+| `context`                                                          | 估算来源与自动压缩阈值（字段与缺省语义见 sessions.md）                      |
 | `cacheHitRate`                                                     | 旧口径命中率：cacheRead /（input + cacheRead + cacheWrite），全部请求进分母 |
 | `cache`                                                            | `SessionCacheStats`（下例），会话层缓存控制器接线时才有                     |
 

package/docs/session-format.md

@@ -47,7 +47,7 @@
 
 ### 消息
 
-- `system`：`{ role: "system", sections, toolsAdded?, toolsRemoved?, timestamp }`。首条是全量：系统提示的命名节（固定顺序 `preamble → tools → rules → project_context → skills → memory → hooks → cwd → host → role`；`memory` 是第六波的记忆索引节，未开启记忆时不出现）与工具声明表；之后只落**补丁**——节名级替换、值为 `null` 表示删除该节，`toolsAdded` / `toolsRemoved` 增删工具。依次重放得到当前系统提示；请求时由协议层重装全量。首条 system 消息在首次请求前落盘，也就是建文件的时刻。
+- `system`：`{ role: "system", sections, toolsAdded?, toolsRemoved?, timestamp }`。首条是全量：系统提示的命名节（固定顺序 `preamble → tools → rules → project_context → skills → memory → hooks → cwd → host → role`；`memory` 是第六波的记忆索引节，未开启记忆时不出现）与工具声明表；之后只落**补丁**——节名级替换、值为 `null` 表示删除该节，`toolsAdded` / `toolsRemoved` 增删工具。依次重放得到当前系统提示；请求时由协议层重装：首条非 system 消息之前的部分折进开头，之后的节补丁作为尾部上下文送达、不改写开头（移除工具的补丁除外，见 [providers.md](providers.md)「缓存」）。首条 system 消息在首次请求前落盘，也就是建文件的时刻。
 - `user`：`content`、`origin?`（缺省 = 普通用户输入；`steer` / `followUp` 是运行中插话与排队，`host` 是宿主 `sendUser` 注入，`interrupt` 是打断并立即发送开的新回合（TUI `Ctrl+X`、line 模式 `/interrupt`、RPC / SDK 的 `interrupt: true`；投影与普通 user 消息相同），`direct` 是用户在子 Agent 视图里直接发给该子 Agent 的消息（第六波 W6-A，写在子会话里；投影与普通 user 消息相同），其它字符串原样记录）。
 - `assistant`：`content`（文本 / 思考 / 工具调用块）、`api`、`provider`、`model`、`usage`、`stopReason`，以及可选的 `responseId`、`thinkingLevel`、`providerThinkingLevel`、`rawStopReason`、`errorMessage`。`usage` 是 `{ input, output, cacheRead, cacheWrite, cacheWrite1h?, reasoning?, totalTokens, cost?, cacheReported? }`：`input` 不含缓存部分，`cost` 是 `{ input, output, cacheRead, cacheWrite, total }`（美元，模型无价格时缺省），`cacheReported` 表示原始响应里出现过缓存字段。
 - `toolResult`：对应工具调用的结果（`toolCallId`、`toolName`、`content`、`isError`、`details?`）。
@@ -114,7 +114,7 @@
 
 `ama.task`（第五波 W5-G）：子会话首条的 `data` 另带 `taskId`、`agent`；父会话在任务开始、每次续聊与结束时各写一条，
 `data` = `TaskInfo`（`taskId, agent, runner, description, background, status, startedAt, endedAt?, turns?, usage?, costUsd?,
-outputFile?, sessionRef?`）+ `parentToolCallId`、`cwd`。同一 `taskId` 取分支上最后一条；resume 时据此重建任务注册表，
+contextTokens?, contextWindow?, outputFile?, sessionRef?`；`contextTokens / contextWindow` 只有外部 Agent 报告时才有）+ `parentToolCallId`、`cwd`。同一 `taskId` 取分支上最后一条；resume 时据此重建任务注册表，
 `status: "running"` 视为 `interrupted`（`taskId` 续聊重开 `sessionRef.sessionFile`）。没有 `status` 的是子会话自己的首条。
 
 第五波登记的类型（docs/wave5-plan.md；括号里是开始写入的批次，之前的版本不会产生，读到未知 `customType` 一律忽略）。`custom_message` 类都是 `display: false`，经扩展点 `beforePrompts` 追加在末尾，不改缓存前缀：
@@ -129,7 +129,7 @@ outputFile?, sessionRef?`）+ `parentToolCallId`、`cwd`。同一 `taskId` 取
 | `ama.post_compact`   | （不单独成条）   | 回注改为 `compaction.summary` 末尾的 `<post-compact-state>` 块（清单与指针，不含正文；见 `compaction/post-compact.ts`）                  | 写 compaction 条目时（W5-H1），模型看到「摘要 → 回注 → 保留区」                                                                 |
 | `ama.reminder`       | `custom_message` | `content`：提醒（todo 复述、外部文件改动、上下文用量、预算余量、后台命令退出），`<system-reminder>` 包起来                               | 新提示之前按 `reminders.*` 追加（W5-H2）；run 进行中的提醒不单独成条，追加在工具批次最后一条 toolResult 的末尾                  |
 | `ama.agent-session`  | `custom`         | `data: { agent, runner, sessionId, cwd?, taskId? }`：外部 Agent 自己的会话引用（不含原始事件与转录）                                     | 外部 Agent 会话建立 / 续聊时（W5-E）                                                                                            |
-| `ama.agent-usage`    | `custom`         | `data: { agent, sessionId, unit: usd \| tokens \| requests, amount, tokens? }`                                                           | 外部 Agent 每个回合结束（W5-E）；`SessionStats.external` 据此汇总                                                               |
+| `ama.agent-usage`    | `custom`         | `data: { agent, sessionId, unit: usd \| tokens \| requests, amount, tokens?, contextTokens?, contextWindow? }`（上下文只记数字）         | 外部 Agent 每个回合结束（W5-E）；`SessionStats.external` 据此汇总                                                               |
 
 第六波登记的类型（docs/wave6-plan.md §2.2；之前的版本不会产生）：
 

package/docs/sessions.md

@@ -55,6 +55,28 @@ packy/deepseek-v4-flash         1     3     1  4.6k   980      2k       0   30.8
 - 每个文件的摘要缓存在 `<数据目录>/stats-index.json`，按文件 mtime 与大小失效；时区变化整份作废；扫描全部时顺带删掉已不存在的文件。`--no-cache` 不读也不写。
 - 实测（本机，`src/session/stats-perf.test.ts`）：1000 个会话、67 MB（每个 12 回合、24 次工具调用、2 KB 工具结果），冷扫描约 160 ms，命中索引约 15 ms。
 
+## 当前会话的上下文用量（`getStats()` / `get_session_stats`）
+
+`ama stats` 统计的是历史计费量；正在进行的会话「上下文还剩多少」看 `SessionStats` 的上下文字段（SDK `session.getStats()`、
+RPC `get_session_stats` 原样输出，状态栏与 `/session` 也读它们）：
+
+| 字段                     | 含义                                                                                                                                     |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `contextTokens`          | 下一次请求要带的上下文 token 估算（口径见 `context.source`）                                                                             |
+| `contextWindow`          | 当前模型的窗口；模型没有窗口信息时**缺省**（`ama models discover` 或在配置里为模型设 `contextWindow` 补上）                              |
+| `contextPercent`         | `contextTokens / contextWindow`，0–100，一位小数，封顶 100；窗口缺省时**缺省**（界面显示 `ctx ?`）                                       |
+| `context.source`         | `usage`：最后一条有效助手消息的 usage + 其后消息的估算；`estimate`：没有可信的 usage，按当前上下文全量估算；`prefix`：第一次请求前的基线 |
+| `context.usageTokens`    | 来自 usage 的部分；`estimate` / `prefix` 时为 0                                                                                          |
+| `context.trailingTokens` | 估算的部分（usage 之后的消息，或全量估算 / 基线本身）                                                                                    |
+| `context.autoCompactAt`  | 自动摘要（档二）的阈值 = 窗口 − `compaction.reserveTokens`；自动压缩关闭、连续失败熔断或窗口缺省时**缺省**                               |
+| `context.pruneAt`        | 工具结果裁剪（档一）的阈值 = 0.7 ×（窗口 − `reserveTokens`）；缺省条件同上                                                               |
+
+- **估算口径**：CJK 表意文字 / 假名 / 谚文每字 1 token，其余字符 / 4，图片每张 1 600；usage 取 `totalTokens`（缺则输入 + 输出 + 缓存读写，含输出）。
+- **第一次请求前**（`prefix`）：系统提示与工具表要到第一次请求时才写进会话，在此之前按「将要发送的那一份」（命名节文本 + 工具声明 JSON）估算，所以新会话一打开就不是 0。只用于统计，不写会话、不改请求体。
+- **压缩 / 上下文编辑之后**（`estimate`）：最后那条 usage 不再代表当前上下文，改为全量估算，直到下一次请求带回新的 usage；界面在数字前加 `≈`。
+- **字段缺省就是「不知道」**，不是 0：`contextWindow`、`contextPercent`、`context.autoCompactAt`、`context.pruneAt` 缺省时 JSON 里没有这个键。旧版本或自定义会话实现可能没有 `context`，按 `contextTokens` 读即可。
+- `tokens`（`{ input, output, cacheRead, cacheWrite, total }`）是**会话累计**计费量，含压缩摘要、保温等不进上下文的请求，不能当上下文用量看。
+
 ## 检索：`ama sessions search`
 
 ```

package/docs/tui-design.md

@@ -2,7 +2,7 @@
 
 > 适用：`src/tui/**`（组件库）与 `src/modes/interactive/**`（交互模式）。基线 main 217017c。
 > 约束不变：主屏模式（不用备用屏，历史进终端回滚，tmux `capture-pane` 可读）、差分渲染、运行时零依赖、`NO_COLOR` / 16 / 256 / truecolor 降级、40 列可用、中文宽字符正确、Windows Terminal 可用、括号粘贴。
-> 参考对象只有两个：Pi 1.0（组件模型、主题 JSON 的角色划分）与 Claude Code（视觉语言：`›` 输入、`⏺` / `⎿` 工具层级、spinner 动词、底部模式提示、编号审批）。
+> 吸收终端 Agent 的常见设计：组件模型、主题 JSON 的角色划分，以及视觉语言（`›` 输入、`⏺` / `⎿` 工具层级、spinner 动词、底部模式提示、编号审批）。
 
 ## 0. 现状诊断（对照 test/fixtures/tui/*.txt）
 
@@ -480,7 +480,7 @@ tmux 节点里宿主要解析最后一行：嵌入缺省 `compact`，字段顺
 
 - 标题由原因决定：`需要确认`（mode）/ `危险命令`（dangerous）/ `Hook 要求确认`；来源标注见下文「来源标注」（第五波 W5-U）。边框颜色随预览严重度：danger `error`、warn `warning`、其余 `border`。
 - 工具名 `tool` 粗体，原因标签 `error` / `warning` / `dim`；命令 `code`；预览行按严重度着色（现有）；Auto 判定行 `warning`。
-- 选项编号列表（Claude Code 风格）：选中行 `›` + `selection` bg；右侧按键提示 `dim`。缺省选中：dangerous → 拒绝；其余 → 允许。按键 `y / a / n / Esc / 1 2 3 / ↑↓ Enter / v` 全部有效（旧按键不废）。edit / write 的输入摘要（`−/+` 摘要、`写入 N 行`、本会话未读过标黄）保留。
+- 选项编号列表：选中行 `›` + `selection` bg；右侧按键提示 `dim`。缺省选中：dangerous → 拒绝；其余 → 允许。按键 `y / a / n / Esc / 1 2 3 / ↑↓ Enter / v` 全部有效（旧按键不废）。edit / write 的输入摘要（`−/+` 摘要、`写入 N 行`、本会话未读过标黄）保留。
 - 覆盖层仍为 `bottom` 锚定全宽；对话框打开时输入框提示符变 `dim`，Loader 动词 `等待确认`。
 
 40 列：

package/docs/tui.md

@@ -33,8 +33,8 @@
 ────────────────────────────────────────────────
 › 输入消息，/ 命令，@ 文件，Shift+Enter 换行        ← 输入框（占位）
 ────────────────────────────────────────────────
-codemode on        tps: 100 tok/s • 546 tok / 5.5s (avg 100 · ttft 1.4s) · ↑12k ↓1.2k · cache 80% ♨ · [-]   ← 速率行（full）
-Accept edits | shift+tab 切换    claude-opus-5-5 medium | Ctx 3.0% | proj ⎇ main 5ae9e54 ↑2 (+12,-3) | $0.26 | 2h24m
+codemode on        tps: 100 tok/s • 546 tok / 5.5s (avg 100 · ttft 1.4s) · Σ↑12k ↓1.2k R9.6k · cache 80% ♨ · [-]   ← 速率行（full）
+Accept edits | shift+tab 切换    claude-opus-5-5 medium | Ctx 3.0% 8.2k/272k auto | proj ⎇ main 5ae9e54 ↑2 (+12,-3) | $0.26 | 2h24m
                                     5 小时：10.0% | 重置：2h 18m | 本周：31.0% | 本周重置：6d 5h   ← 订阅配额行（full，ChatGPT 订阅模型）
 ```
 
@@ -44,16 +44,17 @@ Accept edits | shift+tab 切换    claude-opus-5-5 medium | Ctx 3.0% | proj ⎇
 - **提示**：`✗` 错误、`↻ 重试 n/m`、`!` 警告（缓存未命中、上下文余量）、`⛔ Hook 阻止`、宿主通知、审批被拒或超时的说明；压缩 / 分支摘要是左竖条卡片（`▎ 上下文已压缩  128k → 24k token`）。
 - **运行中**：`⠋ 动词 · 已用时 · …`，动词按当前最深状态取：`等待确认`（审批打开）、`运行 bash` / `运行 3 个工具`、`重试 2/3 · 2s 后`、`压缩上下文`、`回复中 · ↓≈1.2k`（本条输出的估算 token）、`思考中`。有阻塞中的前台子 Agent 任务时加 `Ctrl+B 转后台`，Agent 栏里有任务时加 `↓ Agent 栏`（有停靠的审批时换成 `↓ 处理审批`）：`⠏ 运行 task · 4s · Esc 中断 · Ctrl+B 转后台 · ↓ Agent 栏`，一行放不下时从后往前整项丢掉。输入框有字时最前面加 `Enter 排队 · Ctrl+X 打断并发送`（`ui.enterWhileRunning: "interrupt"` 时是 `Enter 打断并发送 · Ctrl+X 排队`）；有排队的插话时队列末行是 `Alt+↑ 取回 · Ctrl+X 立即发送 · Esc 回填并中断`。
 - **状态栏**：模式永远在最左；`full` 左右分区——左列是状态与开关（权限模式、`shift+tab` 提示、codemode、沙箱、预设、回退），右列是度量与模型（tps、用量、模型、Ctx、git、费用、时长、配额），右列右对齐、左列为空时整行靠右；除 full 布局下的订阅配额行外，状态栏是最后一行（`compact` 永远是最后一行）。`compact` 的分隔符固定为 `·`（嵌入宿主按此解析），`full` 用 `|`。布局由 `ui.statusLine` 决定：独立终端缺省 `full`（两行），有 profile 的嵌入宿主缺省 `compact`（一行，布局与以前相同）；运行时 `Ctrl+G` 或 `/statusline [full|compact]` 切换，只影响本会话。`full` 时输入框在倒数第 4 行（`compact` 仍是倒数第 3 行）。
-  - **`full` 上行（速率行）**：左区是开关类项 `codemode on|only`（网络未隔离时追加 `net!`）· `沙箱` · `preset <名>`（非 default 时）· `→ <回退模型>`（回退中，黄色）· 排队数 · 宿主状态，没有时左区为空。右区 `tps: <速率> tok/s • <输出 token> tok / <耗时> (avg <会话均速> · ttft <首 token 延迟>) · ↑<输入> ↓<输出> · 缓存 · 重计费 · [-]`——速率在流式中是最近 2 s 的瞬时值（`tps:` 强调色），结束后是该请求的平均值，生成不足 0.25 s 的整块回复不算速率、显示 `—`；耗时从首 token 起；`↑` 输入含缓存读写；ASCII 下 `•` 为 `*`、`→` 为 `->`；行尾 `[-]` 提示可折叠。只统计对话请求（压缩摘要、保温、分类器不计）。窄时先丢右区度量（输出量 / 耗时、token、缓存、重计费、avg、ttft），再丢左区开关（宿主状态、排队数、预设、回退、沙箱、codemode）；`tps` 与 `[-]` 不丢。
-  - **`full` 下行**：左区 `权限模式 | shift+tab 切换`，右区 `模型 思考级别 | Ctx 3.0% | <目录名> ⎇ <分支> <短提交> ↑N ↓N (+a,-d) | $费用 | 会话时长`（Ctx 一位小数，宽屏也不换余量表）；窄时依次丢弃切换提示、思考级别、增删行、目录名、分支与提交、时长、费用、上下文、模型。
+  - **`full` 上行（速率行）**：左区是开关类项 `codemode on|only`（网络未隔离时追加 `net!`）· `沙箱` · `preset <名>`（非 default 时）· `→ <回退模型>`（回退中，黄色）· 排队数 · 宿主状态，没有时左区为空。右区 `tps: <速率> tok/s • <输出 token> tok / <耗时> (avg <会话均速> · ttft <首 token 延迟>) · Σ↑<输入> ↓<输出> R<缓存读> W<缓存写> · 缓存 · 重计费 · [-]`——速率在流式中是最近 2 s 的瞬时值（`tps:` 强调色），结束后是该请求的平均值，生成不足 0.25 s 的整块回复不算速率、显示 `—`；耗时从首 token 起；`Σ` 表示**会话累计**计费量（不是上下文占用），`↑` 输入含缓存读写，其中缓存读 / 写另列为 `R` / `W`（为 0 不显示，ASCII 下 `Σ` 为 `sum `）；ASCII 下 `•` 为 `*`、`→` 为 `->`；行尾 `[-]` 提示可折叠。只统计对话请求（压缩摘要、保温、分类器不计）。窄时先丢右区度量（输出量 / 耗时、token、缓存、重计费、avg、ttft），再丢左区开关（宿主状态、排队数、预设、回退、沙箱、codemode）；`tps` 与 `[-]` 不丢。
+  - **`full` 下行**：左区 `权限模式 | shift+tab 切换`，右区 `模型 思考级别 | Ctx 3.0% 8.2k/272k auto | <目录名> ⎇ <分支> <短提交> ↑N ↓N (+a,-d) | $费用 | 会话时长`（Ctx 一位小数，宽屏也不换余量表）。Ctx 段是当前上下文：百分比、已用量 / 窗口，`auto` 表示自动压缩开着（关闭、连续失败熔断或窗口未知时不显示）；数字不是来自模型回传的 usage 时前面加 `≈`（第一次请求前按系统提示 + 工具声明估算的基线，或压缩之后、下一次请求之前的全量估算），窗口未知时是 `Ctx ? 8.2k`。窄时依次丢弃 `auto`、切换提示、思考级别、`/窗口`、增删行、目录名、分支与提交、已用量、时长、费用、上下文百分比、模型。
   - **订阅配额行**（`full` 第三行，在状态栏下方）：当前模型走 ChatGPT 订阅（`chatgpt` 供应商）时显示 `5 小时：<已用%> | 重置：<距重置> | 本周：<已用%> | 本周重置：<距重置>`（英文界面 `Session: … | Reset: … | Weekly: … | Weekly Reset: …`），数据来自最近一次 `quota_update`（codex 方式的 `x-codex-primary/secondary-*` 响应头与 `codex.rate_limits` 事件；siwc 只有超限 429 时才有）。重置时间是相对时长（`2h 18m`、`6d 5h`），每分钟刷新一次。codex 方式在第一次请求前显示「配额：首次请求后显示」（第一次请求就会带回配额，先占住行免得行数跳动）；siwc 没有数据时不占行（只有超限才有配额，占位会一直挂着）；非订阅模型不显示。窄于 80 列时压缩为 `5h 10% ↻2h18m · 周 31% ↻6d5h`，再窄先丢重置时间。配额行在右区右对齐。标签按窗口时长认而不是按 primary / secondary 槽位：300 分钟是「5 小时」、10080 分钟是「本周」，其它时长用实际时长（`1d：`）；缺时长时 primary 当 5 小时、secondary 当本周（与另一个窗口撞名时取另一种）；按时长从短到长排。用量 0、无时长、无重置时间的窗口是服务端的「没有这个窗口」，不显示（有的套餐 codex 只送一个周窗口，放在 primary）。`Ctrl+G` / `/statusline compact` 折叠时配额行与速率行一起收起（`compact` 只保留一行，宿主按「最后一行 = 状态栏」锚定）。
-  - **配色**（`full`）：标签、单位、分隔符与括号暗灰；速率数字紫、输出量 / 耗时 / avg 蓝、ttft 紫；模型与思考级别蓝；Ctx 与配额百分比按阈值绿 / 黄 / 红（≥ 70% 黄、≥ 90% 红）；目录与分支绿、短提交暗灰、`↑N` 领先橙、`↓N` 落后红、`(+a,-d)` 绿 / 红；费用黄；时长与重置时间紫。都取主题语义色，深 / 浅主题与 16 色各有对应；`NO_COLOR` 与 ASCII 不着色、结构不变。`compact` 的着色不变。
+  - **配色**（`full`）：标签、单位、分隔符与括号暗灰；速率数字紫、输出量 / 耗时 / avg 蓝、ttft 紫；模型与思考级别蓝；Ctx 按阈值绿 / 黄 / 红（越过档一裁剪阈值即黄——0.7 ×（窗口 − 预留），比 70% 略低；≥ 90% 红；没有阈值时 ≥ 70% 黄），配额百分比 ≥ 70% 黄、≥ 90% 红；目录与分支绿、短提交暗灰、`↑N` 领先橙、`↓N` 落后红、`(+a,-d)` 绿 / 红；费用黄；时长与重置时间紫。都取主题语义色，深 / 浅主题与 16 色各有对应；`NO_COLOR` 与 ASCII 不着色、结构不变。`compact` 的着色不变。
   - **`compact`**：一行，右区 模型 · 思考级别 · `↑ ↓` · 缓存 · 费用 · 重计费 · 上下文占用 · 目录 ⎇ 分支 提交 +a −b · 会话时长 · 排队数 · codemode · 预设 · 宿主状态 · 订阅配额短项（`5h 10% 周 31%`，只在有配额数据时；项内不含 `·`）；窄时依次丢弃配额短项、切换提示、宿主状态、预设、重计费、费用、缓存、token、思考级别、排队数、codemode、增删行、目录名、分支与提交、时长、上下文、模型。
   - **git**：分支与短提交直接读 `.git/HEAD`（worktree 认；detached 只显示短提交；非 git 目录整段省略，只剩目录名）；`+a −b` 是工作区（含暂存）相对 HEAD 的增删行，回合结束、写类工具结束、回滚、`/tree` 之后在后台跑 `git diff --numstat HEAD`，至多 10 秒一次，超过 2 秒或失败就本会话不再显示增删；`AMA_STATUS_GIT=0` 关闭。`full` 的 `↑N` / `↓N` 是当前分支领先 / 落后上游的提交数：分支在 git 配置里有上游（`branch.<名>.merge`）时，同一节流周期接着跑 `git rev-list --left-right --count @{upstream}...HEAD`（同样 2 秒超时，超时本会话不再统计）；为 0、没有上游或 detached 不显示；ASCII 下为 `^N` / `vN`。
   - **费用**含子任务、保温、分类器与外部 Agent 以美元计的用量（其它单位只在 `/session`）；**时长**从本进程打开当前会话起算（`Ns` / `Nm` / `NhMm`）。
   - bash 命令在操作系统沙箱里跑时（`sandbox.bash: "auto"` 且本机可用，见 [sandbox.md](sandbox.md)）用量类项多一个 `沙箱`，宽度不够时与 codemode 一起先丢。
   - 模型回退中（`fallbackModel`，主模型过载或重试用尽后改用回退模型重试一次）`compact` 的模型项显示 `主模型 → 回退模型`（回退模型黄色），`full` 的模型项只留主模型、速率行左区显示 `→ 回退模型`，回退模型回复、切回主模型后消失；消息区同时有一行说明。
-  - 模型名随宽度缩写（< 100 列去供应商、< 60 去渠道、< 48 去版本后缀）；`compact` ≥ 110 列时上下文显示为余量表 `ctx ▮▮▮▯▯▯▯▯▯▯ 34%`；会变的数字按最宽形状占位，数值变化不会让某项时有时无。ASCII 模式 `⎇` → `git`、`−` → `-`、`♨` → `~`、`↻` → `@`。
+  - **上下文的刷新**：提交消息后立刻更新（新消息按估算计入）；流式中回复带回 usage（有的协议在开头就给输入量）时按每秒至多 2 次换成在途请求的实测值；回复结束、压缩、换模型后回到统计值。
+  - 模型名随宽度缩写（< 100 列去供应商、< 60 去渠道、< 48 去版本后缀）；`compact` ≥ 110 列时上下文显示为余量表 `ctx ▮▮▮▯▯▯▯▯▯▯ 34%`，占用 < 1% 时保留一位小数（`ctx ≈0.4%`，不显示成 0%），估算值同样带 `≈`；会变的数字按最宽形状占位，数值变化不会让某项时有时无。ASCII 模式 `⎇` → `git`、`−` → `-`、`♨` → `~`、`↻` → `@`。
 - **退出**：消息区最后追加一行会话摘要与恢复命令，留在终端回滚里：
 
 ```
@@ -72,7 +73,7 @@ Accept edits | shift+tab 切换    claude-opus-5-5 medium | Ctx 3.0% | proj ⎇
 | `cache 未报告`  | 端点不报缓存（`silent`：连续 3 个可比请求读写都是 0，或 `compat.cacheReporting: "silent"`）；这类请求不进命中率分母 |
 | `♨`             | 保温计时中（工具长时间运行时按 TTL 重放前缀，`/cache warm` 可切换）                                                 |
 | `rebill $0.11`  | 本会话缓存未命中导致的重计费金额；模型没有价格时显示 token 数；为 0 不显示                                          |
-| `ctx 72%`       | 上下文占用，< 70% 绿色、≥ 70% 黄色、≥ 90% 红色；`ctx ?` 表示模型没有窗口信息                                        |
+| `ctx 72%`       | 上下文占用，越过档一裁剪阈值黄色、≥ 90% 红色；`≈` 为估算值；`ctx ?` 为模型没有窗口信息                              |
 | `codemode only` | codemode 生效（`on` / `only`）；网络未隔离（Node 22 / 24 且没有操作系统沙箱，见 sandbox.md）时追加红色 `net!`       |
 
 消息区（line 模式写 stderr，前缀 `ama: `）只在两种情况下提示一行，`cache.missNotices: false` 可关：
@@ -85,10 +86,10 @@ Accept edits | shift+tab 切换    claude-opus-5-5 medium | Ctx 3.0% | proj ⎇
 
 ```
 ▎ 会话 3f2a9c1e  ~/.local/share/ama/sessions/…/3f2a9c1e.jsonl
-▎ 模型    anthropic/claude-sonnet-4-5 · 思考 medium · 权限 Accept edits
-▎ 消息    用户 7 · 助手 9 · 工具调用 23
-▎ 用量    输入 3.4k · 输出 9.4k · 缓存读 118k · 缓存写 6.2k · $0.42
-▎ 上下文  ▮▮▮▯▯▯▯▯▯▯ 34% · 68k / 200k
+▎ 模型      anthropic/claude-sonnet-4-5 · 思考 medium · 权限 Accept edits
+▎ 消息      用户 7 · 助手 9 · 工具调用 23
+▎ 累计用量  输入 3.4k · 输出 9.4k · 缓存读 118k · 缓存写 6.2k · $0.42
+▎ 上下文    ▮▮▮▯▯▯▯▯▯▯ 34% · 68k / 200k · 距自动压缩 ≈ 116k
 ▎
 ▎ 缓存
 ▎   输入      3.4k = 缓存读 2.2k（65%）+ 未缓存 1.2k
@@ -213,6 +214,38 @@ line 模式（`--no-tui`）运行中输入 `/interrupt <文本>` 效果相同（
 - `/plan`：当前计划面板（见下文「Plan 审批」）；`/plan <目标>` 进入 Plan 模式并发出目标；`/plan approve [模式|fresh]`、`/plan reject` 不开对话框直接批准 / 放弃。
 - `/tasks`：聚焦 Agent 栏，`/tasks <id>` 打开子 Agent 视图；`/agents`：可用的子 Agent 类型（见下文「子 Agent」）。
 - `/paste`：同 `Ctrl+V`。
+- `/context`：上下文按类别的明细面板（见下一节）。
+
+### /context
+
+`/context` 回答「上下文被什么占着」。交互模式画左竖条面板，line 模式与无面板时是同样内容的纯文本：
+
+```
+▎ 上下文
+▎ 已用      10.6k / 200k（5.3%）
+▎ 剩余      189k token
+▎ 来源      usage 实测 9k + 估算 1.6k
+▎ 自动压缩  184k 触发，还差 ≈ 173k
+▎ 裁剪      超过 129k 时清理旧工具结果
+▎
+▎ 按类别（估算，5.8k）
+▎   系统提示与工具声明按会话里存的 system 消息计入；全量估算可能与 usage 实测不同。
+▎   系统提示         600  ▮▯▯▯▯▯▯▯▯▯ 10%  rules 500 · preamble 100 · cwd 0
+▎   工具声明         333  ▮▯▯▯▯▯▯▯▯▯ 6%  bash 241 · read 91
+▎   …
+▎   工具结果        3.2k  ▮▮▮▮▮▯▯▯▯▯ 55%  read 3k · bash 203
+▎   附件图片        1.6k  ▮▮▮▯▯▯▯▯▯▯ 27%  1 张 · 用户 1.6k
+▎
+▎ 最大的工具结果（前 5）
+▎   #1      3k  read
+▎   #2     203  bash
+```
+
+- **顶部**：已用 / 窗口与百分比（与 `/session` 同一口径：最后一条可用 usage + 其后消息的估算）、剩余、来源（「usage 实测 X + 估算 Y」；还没有可用 usage，或 usage 之后发生过压缩 / 上下文编辑时为「全量估算」）、自动压缩触发点（窗口 − `compaction.reserveTokens`，关闭时显示「关闭」，没有窗口时「窗口未知」）与档一裁剪的起点。
+- **按类别**：系统提示（按节）、工具声明（按工具）、用户消息、助手文本、推理、工具调用参数（按工具）、工具结果（按工具名汇总）、附件图片（每张按 1 600 计）、摘要（压缩 / 分支）、自定义消息；每类给 token 估算、占比与条形。各类之和等于整个投影的字符估算（CJK 每字 1，其余 / 4），所以标题里的合计可能与顶部的「已用」不同——后者优先采信模型回报的 usage。
+- **系统提示与工具声明**来自会话里存的 system 消息（首条全量、之后的补丁也计入，与估算口径一致）；首次请求前分支上还没有 system 消息，这两类按首次请求将要发送的内容估算（与状态栏的启动基线同一口径），「已用」与状态栏一致，来源标为「首次请求前，只有系统提示与工具声明的估算」。
+- **底部**只列最大的 5 个工具结果的序号（投影里第几个工具结果）、工具名与大小，**不显示正文**。
+- 统计只读：不写会话条目、不改请求体，提示词缓存前缀不受影响。
 
 ## 进入 Bypass
 
@@ -456,10 +489,33 @@ t2 explore · 运行中 1m05s · 3 轮 · ↑12k ↓3.4k · Esc 返回 · /tasks
 
 `ui.quietStartup` / `--quiet-startup`：`normal` 显示「AMA」字符画与信息列——版本、模型与思考级别、目录（`~` 缩写）与信任状态、权限模式 / 预设 / codemode、已加载的上下文文件 / Skill / 提示模板 / Hook、警告数与常用按键；宽 ≥ 72 列字符画在左、信息在右，48–71 列字符画在上，窄于 48 列退回两行简洁头（版本 · 模型 · 思考 / 模式 · 目录 · 信任）；`ui.logo: "off"` 或 `ui.compact` 只显示信息列。字符画按字母取主题的 accent → user → tool 三色，ASCII 模式换成 `_ / \ |` 拼的字形。启动时播放一次约 1 秒的「点亮」扫描（字形先暗后亮，高亮带从左扫到右，结束定格），只在原地重画、不在回滚里留帧；按任意键立即定格，按键照常进入输入框。以下情况直接显示定格帧：`ui.animation: false`、`NO_COLOR` / 无色终端、非 TTY、嵌入宿主（profile.host）、`CI` 环境、启动即带提示（`ama "…"`）、终端矮于 16 行或内容超出一屏；行式界面、`-p`、RPC、ACP 不画启动头。`header` 只有一行 `✻ ama 版本 · 模型 · 模式 · /help`（profile 缺省）；`silent` 不显示。`--resume` 不带 id、模型没有 key、会话目录不存在、项目资源需要信任时，界面启动前会先出现一个小的选择 / 输入提示，答完收成一行留在屏幕上。
 
+## 终端程序状态（OSC 7501）
+
+交互界面用 [OSC 7501 程序状态协议](https://www.superlogical.com/rex/docs/build/program-status)（rev 0.3）把运行状态报告给终端，支持的终端可以在标签页、侧栏或通知里显示「在跑 / 等你确认 / 完成 / 出错」。报告固定带 `app=ama`；每次报告整体替换该记录。
+
+| 时机                                       | 根记录                                                                                         |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------- |
+| 启动、切换会话（`/new` `/resume` `/fork`） | `idle`                                                                                         |
+| 回合开始                                   | `working`，msg 是当前活动（思考中 / 回复中 / 运行 bash / 压缩上下文，节流 500 ms、同值不重发） |
+| 出现待人处理的审批（含子 Agent 发起的）    | `blocked` `kind=permission`，msg 是「工具 · 目标」                                             |
+| 计划待审批                                 | `blocked` `kind=question`                                                                      |
+| 回合因登录失效失败（`auth_expired`）       | `blocked` `kind=auth`，msg 是错误首行；下一回合开始或换模型时解除                              |
+| 审批 / 计划处理完                          | 回到 `working`（或回合结束后的状态）                                                           |
+| 回合正常结束                               | `done`；之后在 ama 里按任意键回到 `idle`                                                       |
+| 回合出错                                   | `error`，msg 是错误首行                                                                        |
+| 用户中断（Esc 等）                         | `idle`                                                                                         |
+| 退出交互模式                               | 不带 id 的 `clear`（清掉本程序的全部记录）                                                     |
+
+- 子 Agent 任务另有子记录 `id=task/<短 id>`、title 为任务描述：`working`（msg 是正在用的工具）→ 审批时 `blocked` → 结束时 `done`，失败 / 到达回合上限为 `error`，被中断为 `idle`；下一个主回合开始时清掉已结束的任务记录。
+- 退出用 `clear` 而不是 `done`：用户主动退出时结果已经在屏幕上，留一条「完成」记录只是噪声。
+- `ui.programStatus`：`auto`（缺省）启动时发 `OSC 7501 ; ?` 与 `CSI c`（DA1），先收到 `?` 回复才发报告，DA1 先到或 300 ms 内没有回复就不发；两种回复（含迟到的）都在输入解析里吞掉，不会进输入框。`on` 不检测直接发（规范允许：不认识的 OSC 合规终端会忽略）。`off` 不发也不检测。改动重启生效。
+- tmux：缺省丢弃不认识的 OSC，规范也没覆盖多路复用器。tmux 不把外层终端对透传查询的回复转给窗格，检测不可靠，所以 tmux 里 `auto` 等同 `off`；要用就设 `on`，并在 tmux 里 `set -g allow-passthrough on`，报告会用 DCS passthrough（`ESC P tmux; … ESC \`）包裹。
+- 只用于交互界面。`-p`、RPC、ACP 的 stdout 是数据或协议，不发；`-p` 即使 stderr 是终端也不发——它是一次性进程，结果看退出码，退出后新提示符本来就会丢掉 working 记录，留下 done / error 对脚本化调用只是噪声。
+
 ## 在 tmux / Armadra 终端节点里
 
 - 括号粘贴：启动时开启；粘贴的多行内容整体进入输入框（超过 10 行或 1 000 字符折叠为 `[粘贴 #N · M 行]`），粘贴后紧跟的回车直接发送，适合由外部程序写入。
-- 不查询终端能力、不开鼠标与 Kitty 键盘协议，避免回包混进输入；tmux ≥ 3.4 透传同步输出，旧版本也能正常显示。
+- 除程序状态检测（见上一节，tmux 里不检测）外不查询终端能力、不开鼠标与 Kitty 键盘协议，避免回包混进输入；tmux ≥ 3.4 透传同步输出，旧版本也能正常显示。
 - tmux 的缺省前缀 `C-b` 会被 tmux 客户端吃掉：转后台按 `C-b C-b`（`send-prefix` 透传），或 `↓` 进 Agent 栏按 `b`；进栏用 `↓`，不受前缀影响。
 - 窗口尺寸变化时整屏重画最后一屏，回滚里的历史不受影响。
 - 自动降级：非 TTY、`TERM=dumb`、`--no-tui` 或终端初始化失败时使用行式界面，命令与审批问答相同。
@@ -468,16 +524,17 @@ t2 explore · 运行中 1m05s · 3 轮 · ↑12k ↓3.4k · Esc 返回 · /tasks
 
 `config.json` 的 `ui` 段（项目级也可设）：
 
-| 键                | 缺省        | 作用                                                                                          |
-| ----------------- | ----------- | --------------------------------------------------------------------------------------------- |
-| `ui.theme`        | `dark`      | `dark` / `light` / `auto`；auto 只看 `COLORFGBG`（不发终端查询），猜不出用 dark，建议显式配置 |
-| `ui.ascii`        | 自动检测    | ASCII 字形（`›` → `>`、`⏺` → `*`、`⎿` → `L`、框线 → `+ - \|`、spinner 4 帧）                  |
-| `ui.compact`      | `false`     | 消息区块间不空行、启动头不画字符画                                                            |
-| `ui.logo`         | `auto`      | 启动头的「AMA」字符画；`off` 只显示信息列                                                     |
-| `ui.animation`    | `true`      | `false`：运行中 spinner 静止为 `·`，只在秒数变化时重绘；启动字符画不播放动画                  |
-| `ui.markdown`     | `true`      | `false`：助手正文不做 Markdown 渲染                                                           |
-| `ui.showThinking` | `collapsed` | 见「布局」                                                                                    |
-| `ui.quietStartup` | `normal`    | 见「启动画面」                                                                                |
+| 键                 | 缺省        | 作用                                                                                          |
+| ------------------ | ----------- | --------------------------------------------------------------------------------------------- |
+| `ui.theme`         | `dark`      | `dark` / `light` / `auto`；auto 只看 `COLORFGBG`（不发终端查询），猜不出用 dark，建议显式配置 |
+| `ui.ascii`         | 自动检测    | ASCII 字形（`›` → `>`、`⏺` → `*`、`⎿` → `L`、框线 → `+ - \|`、spinner 4 帧）                  |
+| `ui.compact`       | `false`     | 消息区块间不空行、启动头不画字符画                                                            |
+| `ui.logo`          | `auto`      | 启动头的「AMA」字符画；`off` 只显示信息列                                                     |
+| `ui.animation`     | `true`      | `false`：运行中 spinner 静止为 `·`，只在秒数变化时重绘；启动字符画不播放动画                  |
+| `ui.markdown`      | `true`      | `false`：助手正文不做 Markdown 渲染                                                           |
+| `ui.showThinking`  | `collapsed` | 见「布局」                                                                                    |
+| `ui.quietStartup`  | `normal`    | 见「启动画面」                                                                                |
+| `ui.programStatus` | `auto`      | 终端程序状态 OSC 7501：`auto` / `on` / `off`，见「终端程序状态」                              |
 
 - **ASCII 模式**：`AMA_ASCII=1`（或 `ui.ascii: true`）强制开启，`AMA_ASCII=0` 强制关闭；自动检测在区域设置（`LC_ALL` > `LC_CTYPE` > `LANG`）已设置但不含 UTF-8、`TERM=linux`、Windows 上既没有 `WT_SESSION` 也没有 `TERM_PROGRAM`（旧 conhost）时开启。Windows Terminal 走 Unicode。
 - **字符错位**：`⏺`（U+23FA）、`⎿`、`▎` 在个别字体（尤其 emoji 回退字体）下画成两格，宽度计算按 wcwidth（一格），会出现列错位或残影——换等宽字体或设 `AMA_ASCII=1`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armadra/agent",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "A coding and coordination agent that runs standalone or embedded in Armadra",
   "type": "module",
   "keywords": [