@armadra/agent 0.3.0 → 0.5.0

package/docs/rewind-plan.md

@@ -0,0 +1,181 @@
+# 检查点与回滚：设计与实施计划
+
+> 状态：实施设计（2026-10-02）。基线：`main` = `95c0435`（0.4.0）。
+> 设计依据：`docs/design.md` §8 会话树、§9 压缩、§9.1 缓存保证、§13 SDK / RPC；对照同类终端 Agent 的检查点实现（只借鉴行为与边界，不复制代码）。
+> 路径相对仓库根；`[RW-x]` 为本计划的批次编号（§6）。
+
+## §0 结论
+
+| #   | 决定                                                                                                                                                                         | 理由                                                             |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| D1  | 回滚 = 「对话」与「代码」两件事，入口 `/rewind` 与空闲时双击 Esc；选项：对话 + 代码 / 仅对话 / 仅代码 / 从这里摘要 / 摘要到这里 / 取消                                       | 两者独立才能覆盖「代码写坏了但对话想留」「对话跑偏了但代码要留」 |
+| D2  | 检查点粒度 = 开启新回合的用户消息；运行中插话（steer）与排队消息并入当前回合，不单独建                                                                                       | 回合是用户能理解的最小单位                                       |
+| D3  | 代码跟踪 edit / write（含 codemode 内层调用、task 子会话）改过的文件；每次发新回合按**当前磁盘状态**重拍已跟踪文件，所以 bash 或手动对已跟踪文件的改动也会被收进下一个检查点 | bash 任意改动不可完整追踪；已跟踪文件这样处理就不会漏            |
+| D4  | 备份按内容 sha256 存全局目录，多会话、多检查点共用；会话文件只记哈希                                                                                                         | 同内容只存一份；fork 不用迁移备份                                |
+| D5  | 恢复前做冲突检测：磁盘内容既不等于 ama 最后写入的、也不等于最近检查点的 → 冲突，缺省跳过并列出，`onConflict: "overwrite"` 才覆盖                                             | 不冲掉用户在回合外的手动修改                                     |
+| D6  | git 状态不动；检查点记 HEAD，回滚时 HEAD 变了只提示并给命令                                                                                                                  | `reset` 类操作风险高，交给用户                                   |
+| D7  | 对话回滚复用会话树（`navigate` 换叶子），被离开的分支留在文件里                                                                                                              | 现有能力，零迁移                                                 |
+| D8  | 回滚后上下文只发新路径，前缀逐字节不变，缓存照常命中；需要告诉模型的事（文件与对话不一致）以 `custom_message` 追加在末尾                                                     | §9.1 前缀稳定                                                    |
+| D9  | `影子 git` 模式（能覆盖 bash 改动）作为可选 `checkpoints.mode: "shadow-git"`，缺省关，最后一批做                                                                             | 大仓库慢、依赖 git，不适合作缺省                                 |
+
+## §1 数据模型
+
+### §1.1 备份存储
+
+- 目录：`<dataDir>/file-history/blobs/<sha256 前 2 位>/<sha256 全长>`，内容为文件原字节（不压缩、不改换行与 BOM）；先写 `<name>.tmp-<pid>` 再 rename，已存在即跳过。
+- 不备份：超过 `checkpoints.maxFileBytes`（缺省 5 MiB）的文件、非普通文件。记录里标 `skipped: "too_large" | "not_regular"`，回滚时报告「无法恢复」。
+- 内存会话（无会话文件）不建检查点，`/rewind` 只提供「仅对话」。
+
+### §1.2 会话条目（均为 `custom`，不进上下文，不影响前缀）
+
+```ts
+// customType "ama.checkpoint"：新回合的用户消息条目追加之后立即追加
+interface CheckpointData {
+  v: 1;
+  userEntryId: string; // 这个检查点属于哪条用户消息（「这条消息发出前」的状态）
+  files: Record<string, FileRecord>; // 全部已跟踪文件；键 = cwd 内相对路径（/ 分隔），cwd 外为绝对路径
+  git?: { head: string; branch?: string }; // 直接读 .git/HEAD（含 worktree 的 gitdir 文件），不起 git 进程
+}
+
+// customType "ama.checkpoint-track"：回合中途第一次碰某文件时追加，补进本回合的检查点
+interface CheckpointTrackData {
+  v: 1;
+  userEntryId: string;
+  path: string;
+  record: FileRecord;
+}
+
+interface FileRecord {
+  blob: string | null; // sha256；null = 当时文件不存在（回滚时删除）
+  mode?: number; // 普通文件的权限位
+  size?: number;
+  realParentDir?: string; // 记录时父目录的 realpath（恢复时校验没被移动）
+  skipped?: "too_large" | "not_regular";
+}
+```
+
+- 读取：按文件顺序重放全会话（不限活动分支）的两类条目，得到 `Map<userEntryId, CheckpointData>`；`checkpoint-track` 并入对应检查点。
+- 每个文件的第一条记录（最早的 `blob`）永久保留，作为「找不到更近记录时」的回退。
+
+### §1.3 运行时状态（`src/checkpoints/tracker.ts`）
+
+- `trackedFiles: Set<string>`、最近检查点、`lastWritten: Map<路径, sha256>`（ama 最后一次写入后的内容哈希，用于冲突检测；只在内存，恢复会话后以最近检查点为准）。
+- 检查点上限 `checkpoints.keep`（缺省 100）：超出时较早检查点不再列为回滚点；备份由 GC 清理（§1.4）。
+
+### §1.4 清理
+
+- `ama sessions prune` 与删除会话时：标记 —— 扫描所有会话文件里的 `ama.checkpoint*` 引用；清除 —— 删除未被引用且 mtime 超过 1 天的 blob。
+- `ama doctor` 显示 file-history 占用。
+
+## §2 时机
+
+| 时机                                                                    | 动作                                                                                                                                                                               |
+| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 新回合用户消息落盘后（`runPrompt`，steer / 排队并入的不算）             | 对每个已跟踪文件：lstat → 不存在记 `null`；size / mode 与上一条记录一致且 mtime 不晚于记录时间 → 沿用；否则读内容算 sha256，等于上一条则沿用，不等则写 blob。追加 `ama.checkpoint` |
+| edit / write 写文件**之前**（`ctx.checkpoint?.beforeWrite(abs)`）       | 文件在任何检查点里都没出现过 → 备份当前内容（不存在记 `null`），追加 `ama.checkpoint-track`，加入 `trackedFiles`；出现过则什么都不做                                               |
+| edit / write 写文件**之后**（`ctx.checkpoint?.afterWrite(abs, bytes)`） | 记 `lastWritten`                                                                                                                                                                   |
+| task 子会话                                                             | 子会话的 `ctx.checkpoint` 指向父会话的 tracker，记到父会话当前回合                                                                                                                 |
+| codemode 内层调用                                                       | 走同一工具上下文，天然覆盖                                                                                                                                                         |
+
+`beforeWrite` 失败（磁盘满、权限）只记 warn，不阻止写入（与对照实现一致：检查点是辅助，不能让编辑失败）。
+
+## §3 回滚
+
+### §3.1 API（`AgentSession`，SDK 同名，RPC 见 §5）
+
+类型见 `src/checkpoints/types.ts`（`RewindPoint`、`RewindRequest`、`RewindResult`、`CodeRestoreResult`）：
+
+```ts
+rewindPoints(): RewindPoint[];               // 活动路径上的新回合用户消息，从旧到新
+rewind(request: RewindRequest): Promise<RewindResult>;
+```
+
+`dryRun` 的 `code` 字段给出将恢复的文件与 `insertions / deletions`，界面的每行统计与确认预览都用它（懒计算，只对选中项）。
+
+- 运行中调用抛 `AmaError("busy")`。全部失败且无一恢复 → `AmaError("rewind_failed", "没有文件被恢复…")`。
+
+### §3.2 恢复代码（`src/checkpoints/restore.ts`）
+
+对每个已跟踪文件，取目标检查点里的记录，没有则取该文件最早的记录：
+
+1. 记录 `skipped` → 报告 `too_large` / `not_regular`。
+2. 当前内容与记录相同 → 跳过（不计入）。
+3. 冲突检测：当前 sha256 ∉ {`lastWritten`，最近检查点的记录} → 冲突；`skip` 时列入 `conflicts` 不动。
+4. 安全检查（不通过 → `skipped`）：目标是符号链接 / 非普通文件 / `nlink > 1`；父目录 realpath ≠ `realParentDir`。
+5. `blob: null` → 删除文件（只删普通文件）。
+6. 否则写回：Windows 以外用 `O_NOFOLLOW` 打开目标，`fstat` 与路径 `lstat` 的 dev / ino 一致才写；清空后写入 blob 内容，恢复 `mode`；目标不存在时按需创建父目录（再次校验父目录）。
+7. 被恢复 / 删除的文件从 `readFiles` 移除（模型再改前必须重新 read）。
+
+`dryRun` 只做 1–4 并用行级 diff 计 `insertions / deletions`（复用 `tools/edit` 的 diff 实现）。
+
+### §3.3 回滚对话（`src/agent/session-rewind.ts`）
+
+1. `navigate(userEntry.parentId)`（已有：换叶子、重载消息、`cache.onContextChanged()`）。
+2. `readFiles` 按新路径重算：路径上成功的 read 工具调用的绝对路径（不跨分支保留）。
+3. 返回 `draft`：原消息文本与图片，交互界面回填输入框。
+4. 模型、思考级别、权限模式保持当前（文档写明）。
+
+### §3.4 文件与对话不一致时告诉模型
+
+- 仅对话：若有已跟踪文件当前内容 ≠ 目标检查点 → 下一次提示前追加 `custom_message{customType:"ama.rewind-note"}`：「回滚到较早的对话，但以下文件保留了之后的修改：…（最多 20 个，其余计数）」。
+- 仅代码：追加「以下文件已恢复到第 N 条消息之前的状态：…」。
+- 对话 + 代码：两边一致，不追加。
+- 该条目在回滚落点之后、下一条用户消息之前，只追加在末尾，不改前缀。
+
+### §3.5 摘要两项
+
+- 「从这里摘要」= `navigate(parentId, { summarize: true })`（已有 `branch_summary`，走会话前缀续写），并回填原消息。
+- 「摘要到这里」= 以所选用户消息为切点做一次档二压缩（`compaction` 条目的 `firstKeptEntryId` = 该消息），之后的消息原样保留，停在末尾。可附说明（`instructions`）。
+
+### §3.6 中断即撤回
+
+运行中 Esc 中断，且本回合还没有任何 assistant 文本 / 工具调用、输入框为空 → 自动 `rewind(当前回合, "conversation")` 并回填原消息（配置 `ui.restoreOnCancel`，缺省 true）。
+
+## §4 交互
+
+- 空闲且输入框为空：双击 Esc（间隔 ≤ 800 ms，第一次提示「再按 Esc 回滚」）打开回滚列表；输入框有字：双击 Esc 清空输入并存进输入历史（↑ 可取回），第一次提示「再按 Esc 清空」。运行中 Esc 仍为中断。
+- 列表：活动路径上的用户消息，最近在下、缺省选中最后一条；高亮行右侧显示 `N 文件 +x −y` / `无代码改动`（对高亮项做 dryRun，结果缓存）。
+- 选中后：确认面板（左竖条样式，复用 `/session` 面板），显示消息原文与时间、选项（有代码改动才出现两个「恢复代码」项；两个摘要项可在行内输入说明）、预览（「将恢复 N 个文件 +x −y」/「代码不变」/ 冲突与跳过清单）、git HEAD 变化提示（附 `git log --oneline <记录>..HEAD` 与 `git reset --soft <记录>` 两条命令，不执行）。
+- 结果通知：`已恢复 N 个文件，跳过 M 个（原因…）`。
+- line 模式：`/rewind` 列编号；`/rewind <n> [both|conversation|code]`。
+- 文案进 i18n 风格的现有中文常量；字形走主题 glyphs（ASCII 可用）。
+
+## §5 RPC / SDK / Hook / 配置
+
+- RPC：`get_rewind_points` → `{ points }`；`rewind { entryId, mode, dryRun?, onConflict? }` → `RewindResult`；事件 `session_rewound { entryId, mode, restored, deleted, conflicts, skipped }`。写进 `docs/rpc.md`。
+- SDK：`session.rewindPoints()`、`session.rewind()`。
+- Hook：新增命令式事件 `PostRewind`（payload `{ entryId, mode, files }`，不可阻止）；`docs/hooks.md` 同步。
+- 配置（`key-docs.ts` 每项要说明与缺省值）：
+  - `checkpoints.mode`: `"tools"`（缺省）/ `"shadow-git"` / `"off"`；`AMA_CHECKPOINTS=off` 覆盖。
+  - `checkpoints.maxFileBytes`: 5 242 880。
+  - `checkpoints.keep`: 100。
+  - `ui.restoreOnCancel`: true。
+
+## §6 影子 git（`checkpoints.mode: "shadow-git"`）[RW-D]
+
+- 仓库：`<dataDir>/file-history/shadow/<sha256(cwd) 前 16>/`（`--git-dir`），`--work-tree=cwd`；尊重 cwd 的 `.gitignore` 与 `info/exclude`，额外排除 `.git`。
+- 每个新回合：`git add -A` + `write-tree` + `commit-tree`，提交 id 记进 `CheckpointData.shadowCommit`（契约里预留可选字段）。
+- 护栏：cwd 下文件数 > 20 000 或单次快照 > 3 s → 本会话降级为 `tools` 并提示；需要 `git` 在 PATH。
+- 恢复：只处理目标提交与「当前工作区快照」之间的差异文件，逐个按 §3.2 的冲突与安全检查写回或删除；不碰 `.gitignore` 掉的文件。
+- 与 `tools` 模式并存：edit / write 的跟踪照常（冲突检测仍以它为准）。
+
+## §7 缓存与上下文
+
+- 回滚后第一次请求：system + tools + 落点之前的消息与回滚前发过的请求逐字节相同 → 有效期内命中；`onContextChanged()` 使这次请求成为重置点（不做未命中归因、保温作废），与现状一致。
+- `ama.checkpoint*` 是 `custom`，不进上下文；`ama.rewind-note` 是 `custom_message`，只出现在新落点之后。
+- 测试：回滚前后请求体前缀逐字节比较（`src/agent/session-rewind.test.ts`）。
+
+## §8 批次与文件所有权
+
+契约 PR（本计划所在 PR）先合入：`src/checkpoints/types.ts`、`ToolContext.checkpoint?`。配置 `checkpoints.*` 归 RW-A，`ui.restoreOnCancel` 与 `PostRewind` 归 RW-B（各自同步 `config/{types,schema,json-schema,key-docs}.ts` 与 `hooks/types.ts`）。之后：
+
+| 批次            | 内容                                                                                                                                                                      | 文件所有权                                                                                                                                                                                               | 依赖                                          | 验收                                                                                                                                                                              |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| RW-A 检查点核心 | blob 存储、tracker、条目重放、恢复与安全检查、冲突检测、dry-run diff、GC、doctor 占用；edit / write 调 `ctx.checkpoint`                                                   | `src/checkpoints/**`（除 types.ts）、`src/tools/{edit,write}.ts` 的两处调用、`src/cli/subcommands/{sessions,doctor}.ts` 的 GC / 占用                                                                     | 契约                                          | 单测覆盖 §3.2 每条分支（符号链接、硬链接、父目录移动、删除、新建、冲突 skip / overwrite、too_large）；三平台 CI 绿（Windows 无 O_NOFOLLOW 分支）                                  |
+| RW-B 会话与接口 | `session-rewind.ts`（编排、readFiles 重算、rewind-note、摘要两项、中断即撤回）、检查点接线（runPrompt 后建检查点、子会话指向父 tracker）、RPC / SDK / `PostRewind` / 文档 | `src/agent/session-rewind.ts`（新）、`src/agent/{session,session-run,session-tools,session-subagent}.ts` 的接线、`src/modes/rpc/**`、`src/sdk.ts`、`src/hooks/**` 的事件、`docs/{rpc,hooks,sessions}.md` | 契约；RW-A 的实现可先用内存桩，合入顺序 A → B | fake 供应商端到端：edit 两个文件 → rewind both → 文件与对话都回到之前、readFiles 不含被恢复文件、下一请求前缀逐字节不变；仅对话 / 仅代码各自的 note；子会话编辑可回滚；中断即撤回 |
+| RW-C 交互界面   | 双击 Esc、回滚列表、确认面板、预览、git 提示、结果通知、line 模式 `/rewind`                                                                                               | `src/modes/interactive/**`、`src/modes/commands-core.ts`、`docs/tui.md`                                                                                                                                  | RW-B                                          | 帧黄金：列表、面板（有 / 无代码改动、冲突、git 提示）、ASCII；tmux 手测双击 Esc 两种行为                                                                                          |
+| RW-D 影子 git   | §6                                                                                                                                                                        | `src/checkpoints/shadow-git.ts`（新）及其测试                                                                                                                                                            | RW-A                                          | 临时 git 仓库里 bash 改动可回滚；护栏降级；无 git 时提示                                                                                                                          |
+
+- A 与 B 并行开发（B 用桩），A 先合；C 与 D 在 B / A 合入后并行。
+- 每个文件 ≤ 600 行（`src/agent/session.ts` 已 600 行，新逻辑放 `session-rewind.ts`）。
+- 每批次细粒度提交、一个 PR、CI 绿后由主会话合并（merge commit）；不发版。

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"]}
+{"type":"hello","protocolVersion":1,"agent":"ama","version":"0.1.0","capabilities":["approvals","images","hooks","plans"]}
 {"type":"session_start","sessionId":"…","cwd":"/work","reason":"startup"}
 ```
 
@@ -90,65 +90,136 @@
 | `set_session_name` †  | `name: string`           | `{ name }`                                                                                  |
 | `get_fork_messages` † | —                        | `{ messages: { entryId, text }[] }`（活动分支上的用户消息，`fork` 的候选）                  |
 
+### 回滚
+
+详见 [rewind-plan.md](rewind-plan.md) §3。回滚点是活动路径上开启新回合的用户消息（运行中插话、排队消息并入当前回合，不单列）。运行中调用回 `busy`。
+
+| 命令                | 参数                                                                                                      | `data`                                                                                                                                                                          |
+| ------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `get_rewind_points` | —                                                                                                         | `{ points: { entryId, text, timestamp, hasCheckpoint }[] }`，从旧到新；`hasCheckpoint: false`（内存会话、检查点关闭、超出保留数）时只能仅对话                                   |
+| `rewind`            | `entryId`、`mode: both \| conversation \| code`、`dryRun?: boolean`、`onConflict?: "skip" \| "overwrite"` | `RewindResult`：`conversation?: { leafId, draft: { text, images? } }`、`code?: CodeRestoreResult`、`gitHint?: { recordedHead, currentHead }`；`dryRun` 只返回预览，不改任何东西 |
+| `summarize_from`    | `entryId`、`instructions?: string`                                                                        | `{ leafId, draft, summary? }`：回到该消息之前，为离开的分支写 `branch_summary`，并回填原消息                                                                                    |
+| `summarize_up_to`   | `entryId`、`instructions?: string`                                                                        | `CompactionResult`：以该消息为切点压缩之前的上下文（`firstKeptEntryId` = 该消息），停在末尾                                                                                     |
+
+`CodeRestoreResult`：`restored` / `deleted` / `conflicts`（`skip` 时未动，`overwrite` 时已覆盖）/ `skipped: { path, reason }[]`（`symlink` / `hardlink` / `not_regular` / `parent_moved` / `too_large` / `backup_missing`）/ `failed: { path, message }[]` / `insertions` / `deletions`；路径在 cwd 内为相对路径（`/` 分隔）。错误码：没有检查点却要恢复代码 → `no_checkpoint`；全部失败且无一恢复 → `rewind_failed`（对话不动）；条目不是活动路径上的回滚点 → `invalid_arguments`。仅对话或仅代码时，下一次提示前会在上下文末尾追加一条 `custom_message{customType: "ama.rewind-note"}` 告诉模型哪些文件与对话不一致。
+
 换会话后服务端重新订阅事件，并为新会话发 `session_start`（`reason` 为 `new` / `resume` / `fork`）。`new_session` 目前不使用 `parentSession` 参数。条目形状见 [session-format.md](session-format.md)。
 
 ### 审批
 
 | 命令                      | 参数                                                                  | `data`                                                                         |
 | ------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
-| `set_client_capabilities` | `capabilities: ("approvals" \| "images" \| "hooks")[]`                | `{ capabilities }`                                                             |
+| `set_client_capabilities` | `capabilities: ("approvals" \| "images" \| "hooks" \| "plans")[]`     | `{ capabilities }`                                                             |
 | `permission_response`     | `requestId: string`、`decision: "allow" \| "deny" \| "allow_session"` | `{ accepted: boolean }`（false = 当前没在等这个 id，已暂存，稍后被问到时生效） |
 
 ### 工具、权限、发现
 
-| 命令                  | 参数                                              | `data`                                                                                                              |
-| --------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `get_tools`           | —                                                 | `{ tools: { name, description, parameters, permission, active }[] }`（注册表全部工具，`active` 表示模型当前能看到） |
-| `set_active_tools`    | `names: string[]`                                 | `{ names }`（生效后的活动工具名）                                                                                   |
-| `set_permission_mode` | `mode: plan \| default \| auto-edit \| full-auto` | `{ mode }`                                                                                                          |
-| `get_commands`        | —                                                 | `{ commands: { name, description?, source: "builtin" \| "template" \| "skill" }[] }`；Skill 名写作 `skill:<名>`     |
-| `get_skills`          | —                                                 | `{ skills: { name, description, location, … }[] }`（已发现的 Skill；`location` 是 SKILL.md 路径）                   |
+| 命令                  | 参数                                                                   | `data`                                                                                                              |
+| --------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `get_tools`           | —                                                                      | `{ tools: { name, description, parameters, permission, active }[] }`（注册表全部工具，`active` 表示模型当前能看到） |
+| `set_active_tools`    | `names: string[]`                                                      | `{ names }`（生效后的活动工具名）                                                                                   |
+| `set_permission_mode` | `mode: plan \| allowlist \| default \| auto-edit \| auto \| full-auto` | `{ mode }`（未知模式 → `invalid_arguments`）                                                                        |
+| `get_commands`        | —                                                                      | `{ commands: { name, description?, source: "builtin" \| "template" \| "skill" }[] }`；Skill 名写作 `skill:<名>`     |
+| `get_skills`          | —                                                                      | `{ skills: { name, description, location, … }[] }`（已发现的 Skill；`location` 是 SKILL.md 路径）                   |
+
+### 计划与任务（第五波）
+
+| 命令            | 参数                                                                                                                                             | `data`                                                                                                   |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| `plan_response` | `planId`、`decision: approve \| approve_fresh \| revise \| reject`、`mode?`（批准后的执行模式）、`feedback?`（revise 的意见）、`editedMarkdown?` | `{ planId, decision }`；`planId` 不是待审批的计划 → `plan_not_found`。见「计划审批」                     |
+| `get_plan`      | `planId?`                                                                                                                                        | `PlanData \| null`：`{ id, version, status, markdown, steps, sourceEntryId, filePath? }`，缺省取最近一份 |
+| `get_todos`     | —                                                                                                                                                | `{ items: { id, text, status: pending \| in_progress \| done, planStep? }[] }`                           |
+| `get_tasks`     | —                                                                                                                                                | `{ tasks: TaskInfo[] }`（子 Agent 任务注册表的只读视图；未装配时为空表）                                 |
+| `get_agents`    | —                                                                                                                                                | `{ agents: AgentInfo[] }`（可用的子 Agent 类型与外部 Agent；未装配时为空表）                             |
 
-合计 33 条命令，名字即 `RpcCommandMap` 的键。
+合计 42 条命令，名字即 `RpcCommandMap` 的键。
 
 ## 事件
 
 事件就是进程内 `SessionEvent`（`src/agent/types.ts`），只有 `message_update` 在线上换成纯增量。按出现场景分组：
 
-| 事件                                                 | 字段                                                                                                          |
-| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `session_start`                                      | `sessionId`、`sessionFile?`、`cwd`、`reason: startup \| resume \| new \| fork`                                |
-| `session_changed`                                    | `sessionId`、`sessionFile?`                                                                                   |
-| `before_agent_start`                                 | `prompt`（经 UserPromptSubmit Hook 与模板展开之后）                                                           |
-| `agent_start` / `turn_start` / `agent_before_settle` | —                                                                                                             |
-| `turn_end`                                           | `message`（助手消息）、`toolResults`                                                                          |
-| `agent_end`                                          | `stopReason`、`willRetry`                                                                                     |
-| `agent_settled`                                      | `warning?`（运行彻底结束，含重试与 followUp）                                                                 |
-| `message_start` / `message_end`                      | `message`（`AgentMessage`）                                                                                   |
-| `message_update`                                     | `assistantMessageEvent`、`usage?`（见下）                                                                     |
-| `tool_execution_start`                               | `toolCallId`、`toolName`、`args`、`parentToolCallId?`                                                         |
-| `tool_execution_update`                              | `toolCallId`、`toolName`、`partial`（运行中的输出文本）、`parentToolCallId?`                                  |
-| `tool_execution_end`                                 | `toolCallId`、`toolName`、`result`、`isError`、`parentToolCallId?`                                            |
-| `queue_update`                                       | `steering: string[]`、`followUp: string[]`                                                                    |
-| `compaction_start`                                   | `trigger: threshold \| overflow \| manual`                                                                    |
-| `compaction_end`                                     | `trigger`、`result?`、`aborted`、`willRetry`、`error?`                                                        |
-| `auto_retry_start`                                   | `attempt`、`maxAttempts`、`delayMs`、`errorMessage`                                                           |
-| `auto_retry_end`                                     | `success`、`attempt`、`finalError?`                                                                           |
-| `permission_request`                                 | `requestId`、`toolName`、`input`、`reason: mode \| dangerous \| hook`、`hookReason?`、`timeoutMs`、`preview?` |
-| `permission_resolved`                                | `requestId`、`decision`                                                                                       |
-| `permission_mode_changed`                            | `mode`                                                                                                        |
-| `model_changed`                                      | `model: { provider, id, channel? }`                                                                           |
-| `thinking_level_changed`                             | `level`                                                                                                       |
-| `entry_appended`                                     | `entry`（刚落盘的会话条目）                                                                                   |
-| `hook_executed`                                      | `event`、`command`、`exitCode`（超时或被信号杀死为 null）、`durationMs`                                       |
-| `cache_miss`                                         | `missedTokens`、`missedCost?`、`reason`、`detail?`、`idleMs`                                                  |
-| `cache_warm`                                         | `phase: scheduled \| sent \| stopped`、`nextWarmAt?`、`usage?`、`cost?`、`reason?`                            |
-| `context_pressure`                                   | `percent`、`threshold: 70 \| 90`、`remainingTokens?`、`estimatedTurnsLeft?`                                   |
+| 事件                                                 | 字段                                                                                                                                                                                                                                             |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `session_start`                                      | `sessionId`、`sessionFile?`、`cwd`、`reason: startup \| resume \| new \| fork`                                                                                                                                                                   |
+| `session_changed`                                    | `sessionId`、`sessionFile?`                                                                                                                                                                                                                      |
+| `session_rewound`                                    | `entryId`、`mode`、`restored`、`deleted`、`conflicts`、`skipped`（回滚完成；`dryRun` 不发，仅对话时文件清单为空）                                                                                                                                |
+| `before_agent_start`                                 | `prompt`（经 UserPromptSubmit Hook 与模板展开之后）                                                                                                                                                                                              |
+| `agent_start` / `turn_start` / `agent_before_settle` | —                                                                                                                                                                                                                                                |
+| `turn_end`                                           | `message`（助手消息）、`toolResults`                                                                                                                                                                                                             |
+| `agent_end`                                          | `stopReason`、`willRetry`                                                                                                                                                                                                                        |
+| `agent_settled`                                      | `warning?`（运行彻底结束，含重试与 followUp）                                                                                                                                                                                                    |
+| `message_start` / `message_end`                      | `message`（`AgentMessage`）                                                                                                                                                                                                                      |
+| `message_update`                                     | `assistantMessageEvent`、`usage?`（见下）                                                                                                                                                                                                        |
+| `tool_execution_start`                               | `toolCallId`、`toolName`、`args`、`parentToolCallId?`                                                                                                                                                                                            |
+| `tool_execution_update`                              | `toolCallId`、`toolName`、`partial`（运行中的输出文本）、`parentToolCallId?`                                                                                                                                                                     |
+| `tool_execution_end`                                 | `toolCallId`、`toolName`、`result`、`isError`、`parentToolCallId?`、`autoDecision?`（auto 模式：`{ layer: rule \| static \| classifier, decision, reason, cached? }`）、`denied?`（`true`：被权限 / Hook / 审批拒绝而没有执行，原因见 `result`） |
+| `queue_update`                                       | `steering: string[]`、`followUp: string[]`                                                                                                                                                                                                       |
+| `compaction_start`                                   | `trigger: threshold \| overflow \| manual`                                                                                                                                                                                                       |
+| `compaction_end`                                     | `trigger`、`result?`、`aborted`、`willRetry`、`error?`                                                                                                                                                                                           |
+| `auto_retry_start`                                   | `attempt`、`maxAttempts`、`delayMs`、`errorMessage`                                                                                                                                                                                              |
+| `auto_retry_end`                                     | `success`、`attempt`、`finalError?`                                                                                                                                                                                                              |
+| `permission_request`                                 | `requestId`、`toolName`、`input`、`reason: mode \| dangerous \| hook`、`hookReason?`、`timeoutMs`、`preview?`、`autoDecision?`（auto 模式下为什么询问）、`context?`（来源，见「子 Agent 事件」）                                                 |
+| `permission_resolved`                                | `requestId`、`decision`                                                                                                                                                                                                                          |
+| `permission_mode_changed`                            | `mode`                                                                                                                                                                                                                                           |
+| `model_changed`                                      | `model: { provider, id, channel? }`                                                                                                                                                                                                              |
+| `thinking_level_changed`                             | `level`                                                                                                                                                                                                                                          |
+| `entry_appended`                                     | `entry`（刚落盘的会话条目）                                                                                                                                                                                                                      |
+| `hook_executed`                                      | `event`、`command`、`exitCode`（超时或被信号杀死为 null）、`durationMs`                                                                                                                                                                          |
+| `cache_miss`                                         | `missedTokens`、`missedCost?`、`reason`、`detail?`、`idleMs`                                                                                                                                                                                     |
+| `cache_warm`                                         | `phase: scheduled \| sent \| stopped`、`nextWarmAt?`、`usage?`、`cost?`、`reason?`                                                                                                                                                               |
+| `context_pressure`                                   | `percent`、`threshold: 70 \| 90`、`remainingTokens?`、`estimatedTurnsLeft?`                                                                                                                                                                      |
 
 另有非会话事件 `{"type":"notification","level":"info"|"warn"|"error","message":…}`：宿主 `ui.notify` 与应答之后的运行失败。
 
 `parentToolCallId` 只出现在 codemode 脚本里经 `tools.*` 发起的内层调用上，值是外层 `codemode` 调用的 id；客户端据此折叠显示。内层调用不进转录。
 
+### 子 Agent 事件（第五波）
+
+`task` / `task_ctl` 起的子 Agent（ama 子会话与外部 Agent 同一组事件，见 [agents.md](agents.md)「子 Agent」）：
+
+| 事件              | 字段                                                                                                                                                                                     |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subagent_start`  | `taskId`、`parentToolCallId`、`agent`、`runner`（`ama` / `claude` / `codex` / `acp:<程序>`）、`description`、`background`、`model?`、`sessionFile?`、`cwd`；同一 `taskId` 续聊时再发一次 |
+| `subagent_update` | `taskId`、`kind: tool \| text \| turn`、`toolName?`、`textDelta?`（≥ 250 ms 合并）、`turn`、`usage?`                                                                                     |
+| `subagent_end`    | `taskId`、`status: completed \| failed \| aborted \| max_turns \| interrupted`、`usage?`、`cache?`、`outputFile?`、`worktree?: { branch, changed }`                                      |
+
+子会话与外部 Agent 的审批照常以 `permission_request` 发给本连接，`context`（可选，只在不是主会话自己的调用时出现）标出来源：
+`depth`（1 = 来自 task 子 Agent）、`taskId`（来源任务）、`origin`（外部 Agent 发来的权限请求：`agent`、`sessionId`（外部 CLI
+自己的会话 id）、`toolCall: { title, kind, locations?, inputSummary? }`、`options`）。对话框据此标 `[task:<agent>]` 或
+`[claude · 会话 abc1]`。外部 Agent 的请求 `toolName` 是 `agent:<id>`，回答只影响这一次（「本会话允许」交给外部 Agent 自己记）；
+首次在会话里以某个外部 Agent 运行时还有一次 `toolName: "task"`、`input: { agent, mode, note }` 的确认（`context.taskId`）。
+`test/fixtures/rpc/external.out.jsonl` 是 `task(agent="acp:ama")` 的三次审批（task 工具、首次运行、子 ama 的 bash）的黄金记录，
+由 `src/agents/external-rpc.test.ts` 用 `UPDATE_GOLDEN=1` 更新。后台任务完成后父会话收到一条
+`origin: "task"` 的 user 消息（`<task-notification …>…</task-notification>`），随后照常开新回合。任务列表与类型列表由
+`get_tasks` / `get_agents` 返回（形状 `TaskInfo` / `AgentInfo`；没有 task 工具时为空表），数据来自当前会话的
+`taskRegistryView(sessionId)` / `sessionAgents(sessionId)`（`src/agent/subagent-registry.ts`）。`get_agents` 另含外部 Agent
+（`installed` / `version` 来自 PATH 与 `--version` 探测，会话建立时异步缓存、外部任务结束与宿主注入变化时刷新；缓存就绪前
+只有类型目录，见 `cachedAgentInfos`，`src/agents/external.ts`）。
+`test/fixtures/rpc/subagent.out.jsonl` 是一次前台 `task(agent="explore")` 加 `get_tasks` / `get_agents` 的黄金记录（只保留
+响应、`tool_execution_*`、`subagent_*` 与 `agent_settled`），由
+`src/agent/subagent-rpc.test.ts` 用 `UPDATE_GOLDEN=1` 更新。
+
+### 速率遥测（第五波）
+
+主会话装有遥测扩展（`src/agent/session-telemetry.ts`），只统计对话请求（`purpose: "turn"`；压缩摘要、保温、探测、分类器不计）：
+
+- 事件 `{"type":"telemetry_tick"}`：流式中首 token 之后约每 500 ms 一次（≤ 2 Hz，由增量驱动；瞬时完成的短回复不发），
+  `ui.animation: false` 时不发；没有载荷，数据从 `get_session_stats` 的 `telemetry` 取。
+- `SessionStats.telemetry`：`{ sessionStartedAt, last?, live?, avgTps? }`。`last` 是最近一次请求（`requestAt`、`firstTokenAt?`、
+  `ttftMs?`、`doneAt?`、`outputTokens?`、`tps?`；进行中的请求出首 token 后即为 `last`，结束后补齐 `doneAt` 等）；
+  `live` 只在流式中（`tps` 为最近 2 s 窗口的估算、`outputTokens` 按增量字符估算、`elapsedMs` 自首 token 起）；
+  `avgTps` = Σ输出 / Σ(结束 − 首 token)，生成不足 250 ms 的请求不计（`tps` 也留空）。时间都是毫秒时间戳。
+
+### 预算、回退与后台命令事件（第五波 W5-H2）
+
+| 事件             | 字段                                                                                                                                                                                                  |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `limit_reached`  | `kind: turns \| cost`、`value`（本次运行的回合数 / 美元）、`limit`；`limits.*`（config，`-p` 另有 `--max-turns` / `--max-cost`）到限时每次运行每类一次，随后 `agent_settled{warning:"limit_reached"}` |
+| `model_fallback` | `from`、`to`（`{ provider, id, channel? }`）、`reason`（触发的错误文本）；可重试错误在 overloaded 时或重试用尽后切到 `fallbackModel` 重试一次，回复后切回（另有两次 `model_changed`）                 |
+| `background_job` | `jobId`、`phase: started \| exited \| stopped`、`command`、`pid?`、`outputPath?`、`exitCode?`；`bash{background:true}` 启动的后台命令                                                                 |
+
+重复调用检测（同 run 同名同参第 5 次）结束 run 时 `agent_settled{warning:"repeated_tool_call"}`。
+
 ### `message_update` 与消息重建
 
 线上的 `message_update` 去掉了累计消息与 `partial`，只有增量：
@@ -236,6 +307,22 @@
 4. 回答者顺序：宿主 broker（`HostApi.approvals.setBroker`）→ RPC 客户端 → 无人作答 deny。审批串行，同一时刻只有一个在等。
 5. 超时：`timeoutMs`（缺省 600 000，即 10 分钟；环境变量 `AMA_APPROVAL_TIMEOUT_MS` 可改）内没有回答 → 服务端按 deny 处理并发 `permission_resolved`。运行被中断时同样 deny，即使客户端已经放行。
 
+## 计划审批
+
+plan 模式与计划的格式见 [plan.md](plan.md)。
+
+1. 回合在 plan 模式下以纯文本结束、回复里有 `<proposed_plan>` 块时，服务端落盘计划并发 `plan_proposed{ planId, version, markdown, steps, filePath? }`（`steps[]`：`{ id, text, dependsOn?, agent? }`），随后照常 `agent_settled`。
+2. 客户端声明过 `set_client_capabilities{capabilities:["plans"]}` 才由它回答；没声明时按配置 `plan.unattended`：缺省 `stop`（计划留在 proposed，不切模式、不执行，客户端之后仍可用 `plan_response` 作答），`approve` 时同一次运行里自动批准并执行。
+3. `plan_response`：
+   - `approve`：计划标 approved，步骤写成 todo（首项 in_progress，发 `todo_updated`），发 `plan_resolved{ planId, decision, mode }`，权限模式切到 `mode`（缺省进入 plan 前的模式；进入前就是 plan 时用 `default`），随后自动开一个新回合：用户消息 `The plan is approved. Go ahead.`（`origin: "plan"`）+ `custom_message{ama.plan_approved}`（计划全文、文件路径、进度记法：有 todo 工具时按 todo 推进，没有时请模型每完成一步写一行 `[DONE:<步骤>]`，ama 据此推进待办并发 `todo_updated`）。
+   - `approve_fresh`：同上标 approved、切模式，然后新建会话（发 `session_start{reason:"new"}`），在新会话里写 todo，并以计划全文为首条用户消息开回合。
+   - `revise`：留在 plan；`feedback` 非空时作为普通用户消息开回合，模型重写计划后出新版本（旧版标 superseded）。
+   - `reject`：计划标 rejected，留在 plan。
+   - `editedMarkdown`：客户端改过的全文；与原文不同则先落一份新版本（`plan_proposed` 再发一次）再按 `decision` 处理。
+4. `todo_updated{ items }`：todo 清单每次变化（`todo` 工具的 set / update、批准时生成）都发，形状同 `get_todos`。
+
+`test/fixtures/rpc/plan.out.jsonl` 是一次完整审批往返的黄金文件（不含 `entry_appended` 与 `message_update`）：声明 `plans` → `set_permission_mode plan` → 提示 → `ama.plan_mode` 说明 → 带计划块的回复 → `plan_proposed` → `agent_settled` → `get_plan` → `plan_response approve` → `todo_updated`、`plan_resolved`、`permission_mode_changed` → 执行回合（`ama.plan_approved`）→ `get_todos`。由 `src/modes/rpc/rpc-plan.test.ts` 用 `UPDATE_GOLDEN=1` 更新。
+
 ## 退出
 
 - stdin 关闭：不再接收命令，撤下审批（之后的 ask 按无人作答 deny），等在途命令与已开始的运行结束、响应写完，退出码 0。所以 `printf '{"type":"prompt","message":"hi"}\n' | ama --mode rpc` 能拿到完整回复；要提前停止，先发 `abort`。
@@ -244,7 +331,7 @@
 
 ## 示例
 
-`test/fixtures/rpc/prompt.out.jsonl` 是一次完整往返的黄金文件（fake 供应商；`prompt` → `get_last_assistant_text`，会话 id、时间戳与路径已归一化）：`hello` → `session_start` → `entry_appended`（模型、思考级别、首条 system 消息）→ `before_agent_start` → `agent_start` → `turn_start` → `prompt` 的响应 → 用户消息 → 助手消息的 `message_update` 增量 → `turn_end` → `agent_end` → `agent_before_settle` → `agent_settled` → 第二条命令的响应。改协议后由 `src/modes/rpc/rpc-mode.test.ts` 用 `UPDATE_GOLDEN=1` 更新并审阅差异。
+`test/fixtures/rpc/prompt.out.jsonl` 是一次完整往返的黄金文件（fake 供应商；`prompt` → `get_last_assistant_text`，会话 id、时间戳与路径已归一化）：`hello` → `session_start` → `entry_appended`（模型、思考级别、首条 system 消息）→ `before_agent_start` → `agent_start` → `turn_start` → `prompt` 的响应 → 用户消息 → 助手消息的 `message_update` 增量 → `turn_end` → `agent_end` → `agent_before_settle` → `agent_settled` → 第二条命令的响应。改协议后由 `src/modes/rpc/rpc-mode.test.ts` 用 `UPDATE_GOLDEN=1` 更新并审阅差异。`test/fixtures/rpc/rewind.out.jsonl` 记回滚的往返（不含 `entry_appended`；第二回合用 write 新建了 `c.txt`）：`get_rewind_points` → `rewind{mode:"both", dryRun:true}` 只回预览 → `rewind{mode:"both"}` 先发 `session_rewound` 再回 `RewindResult`（`c.txt` 被删除、对话回到第二条消息之前）→ 非回滚点的 `summarize_up_to` 回 `invalid_arguments` → 回滚后的 `get_rewind_points`。
 
 最小会话（stdin 关闭即撤下审批，所以管道方式只适合不需要审批的提示；要回答审批，保持 stdin 打开并先发 `set_client_capabilities`）：