@armadra/agent 0.0.0-stage → 0.3.0

package/docs/rpc.md

@@ -0,0 +1,253 @@
+# RPC 协议（stdio JSONL）
+
+`ama --mode rpc` 从 stdin 读命令、向 stdout 写响应与事件，每行一个 JSON。类型定义在 `@armadra/agent/rpc`（`src/rpc.ts`），实现在 `src/modes/rpc/`。`ama -p --output-format stream-json` 输出的事件与这里同形状。设计依据见 [design.md](design.md) §13.2。
+
+## 线路
+
+- 读：只按 `\n` 切行（去掉行尾 `\r`，空行跳过），不按 U+2028 / U+2029 切；多字节 UTF-8 跨块拼接；stdin 结束时最后一段不带换行的行也算一行。
+- 写：每行是一个 `JSON.stringify` 结果，U+2028 / U+2029 转义为 `\u2028` / `\u2029`，`Error` 序列化为 `{ name, message }`，bigint 转字符串，图片 base64 不截断。大行按 64 KiB 分片写出并等待背压，行与行不交错。
+- stdout 只有协议行；日志、宿主通知的人读副本写 stderr。
+
+## 握手
+
+启动后先发 `hello`，再发当前会话的 `session_start`：
+
+```json
+{"type":"hello","protocolVersion":1,"agent":"ama","version":"0.1.0","capabilities":["approvals","images","hooks"]}
+{"type":"session_start","sessionId":"…","cwd":"/work","reason":"startup"}
+```
+
+`protocolVersion` 是 `RPC_PROTOCOL_VERSION`（当前 1）。`capabilities` 列出服务端支持的能力；客户端要接审批时用 `set_client_capabilities` 声明（见「审批」）。
+
+## 命令与响应
+
+命令形状 `{ "id"?: string, "type": <命令名>, ...参数 }`。响应：
+
+```json
+{ "id": "1", "type": "response", "command": "prompt", "success": true, "data": { "disposition": "started" } }
+{ "id": "2", "type": "response", "command": "set_model", "success": false, "error": "…", "code": "model_not_found" }
+```
+
+- 响应带回请求的 `id`（字符串才带）。命令并发处理：`prompt` 不阻塞后续命令，所以响应顺序不一定与请求顺序相同，用 `id` 对应。
+- 失败时 `error` 是人读文本，`code` 是 `AmaError.code`（若有）。未知命令 → `code: "invalid_arguments"`。
+- 一行不是合法 JSON 或缺 `type` → `{ "type": "response", "command": "parse", "success": false, "error": … }`，没有 `id`。
+- 需要会话实现扩展方法的命令（下表标 †）在非 `AgentSessionImpl` 会话上返回 `code: "not_implemented"`；CLI 与 SDK 建出的会话都是 `AgentSessionImpl`。
+
+### 提示
+
+| 命令          | 参数                                                                                    | `data`                                                       |
+| ------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `prompt`      | `message: string`、`images?: ImageBlock[]`、`streamingBehavior?: "steer" \| "followUp"` | `{ disposition: "started" \| "queued" \| "handled" }`        |
+| `steer`       | `message`、`images?`                                                                    | 同上                                                         |
+| `follow_up`   | `message`、`images?`                                                                    | 同上                                                         |
+| `abort`       | —                                                                                       | `{}`（回到空闲后应答；不清队列）                             |
+| `clear_queue` | —                                                                                       | `{ steering: string[], followUp: string[] }`（被清掉的文本） |
+
+提示类命令**不等运行结束**：会话开始运行（`before_agent_start` / `agent_start`）、消息入队或被处理（例如斜杠命令、Hook 阻止）后立刻应答，运行进展走事件。运行中发 `prompt` 且不带 `streamingBehavior` → 失败，`code: "busy"`；带上 `steer` / `followUp` 则入队。应答发出之后的运行失败以 `{"type":"notification","level":"error","message":…}` 报告。
+
+### 状态
+
+| 命令                      | 参数 | `data`                                               |
+| ------------------------- | ---- | ---------------------------------------------------- |
+| `get_state`               | —    | `SessionState`（下表）                               |
+| `get_messages`            | —    | `{ messages: AgentMessage[] }`（投影后的上下文消息） |
+| `get_last_assistant_text` | —    | `{ text: string \| null }`                           |
+| `get_session_stats`       | —    | `SessionStats`（见「会话统计」）                     |
+
+`SessionState`：`isStreaming`、`isCompacting`、`isRetrying`、`model`（`{ provider, id, channel? }` 或缺省；`channel` 只在多渠道供应商上出现）、`thinkingLevel`、`permissionMode`、`sessionId`、`sessionFile`、`cwd`、`sessionName`、`messageCount`、`pendingMessageCount`、`steeringMode`、`followUpMode`、`autoCompaction`、`autoRetry`。
+
+### 模型
+
+| 命令                            | 参数                                                      | `data`                                                           |
+| ------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------- |
+| `set_model`                     | `provider: string`、`modelId: string`、`channel?: string` | `{ model: { provider, id, channel? } }`                          |
+| `get_available_models`          | —                                                         | `{ models: RpcModelInfo[] }`                                     |
+| `set_thinking_level`            | `level: off \| minimal \| low \| medium \| high \| xhigh` | `{ level }`                                                      |
+| `get_available_thinking_levels` | —                                                         | `{ levels: string[] }`（当前模型支持的级别；无模型时 `["off"]`） |
+
+`RpcModelInfo`：`provider`、`id`、`name`、`hasKey`、`keySource`（`cli` / `auth-file` / `config` / `env` / `none`）、`contextWindow?`、`maxTokens`、`reasoning`、`input`（`"text"` / `"image"`）。**密钥不离开进程**：只报有无与来源。
+
+### 队列、压缩、重试
+
+| 命令                    | 参数                             | `data`                                                                                      |
+| ----------------------- | -------------------------------- | ------------------------------------------------------------------------------------------- |
+| `set_steering_mode` †   | `mode: "one-at-a-time" \| "all"` | `{ mode }`                                                                                  |
+| `set_follow_up_mode` †  | `mode`                           | `{ mode }`                                                                                  |
+| `compact`               | `customInstructions?: string`    | `CompactionResult`：`summary`、`firstKeptEntryId`、`tokensBefore`、`tokensAfter?`、`usage?` |
+| `set_auto_compaction` † | `enabled: boolean`               | `{ enabled }`                                                                               |
+| `set_auto_retry` †      | `enabled: boolean`               | `{ enabled }`                                                                               |
+| `abort_retry`           | —                                | `{ aborted: boolean }`（正在重试等待时中断本次运行）                                        |
+
+### 会话
+
+| 命令                  | 参数                     | `data`                                                                                      |
+| --------------------- | ------------------------ | ------------------------------------------------------------------------------------------- |
+| `new_session`         | `parentSession?: string` | `{ sessionId, sessionFile }`                                                                |
+| `switch_session`      | `sessionPath: string`    | 同上                                                                                        |
+| `fork`                | `entryId: string`        | 同上（从该条目之前复制出新会话文件）                                                        |
+| `get_entries` †       | `since?: string`         | `{ entries: SessionEntry[], leafId: string \| null }`；`since` 是 entry id 游标，不含它本身 |
+| `get_tree` †          | —                        | `{ tree: SessionTreeNode[] }`（`{ entry, children, label? }`）                              |
+| `set_session_name` †  | `name: string`           | `{ name }`                                                                                  |
+| `get_fork_messages` † | —                        | `{ messages: { entryId, text }[] }`（活动分支上的用户消息，`fork` 的候选）                  |
+
+换会话后服务端重新订阅事件，并为新会话发 `session_start`（`reason` 为 `new` / `resume` / `fork`）。`new_session` 目前不使用 `parentSession` 参数。条目形状见 [session-format.md](session-format.md)。
+
+### 审批
+
+| 命令                      | 参数                                                                  | `data`                                                                         |
+| ------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `set_client_capabilities` | `capabilities: ("approvals" \| "images" \| "hooks")[]`                | `{ 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 路径）                   |
+
+合计 33 条命令，名字即 `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?`                                   |
+
+另有非会话事件 `{"type":"notification","level":"info"|"warn"|"error","message":…}`：宿主 `ui.notify` 与应答之后的运行失败。
+
+`parentToolCallId` 只出现在 codemode 脚本里经 `tools.*` 发起的内层调用上，值是外层 `codemode` 调用的 id；客户端据此折叠显示。内层调用不进转录。
+
+### `message_update` 与消息重建
+
+线上的 `message_update` 去掉了累计消息与 `partial`，只有增量：
+
+```json
+{
+  "type": "message_update",
+  "assistantMessageEvent": { "type": "text_delta", "contentIndex": 0, "delta": "hello" },
+  "usage": { "input": 12, "output": 3, "cacheRead": 0, "cacheWrite": 0, "totalTokens": 15 }
+}
+```
+
+`assistantMessageEvent.type` 取值：`start`、`text_start` / `text_delta` / `text_end`、`thinking_start` / `thinking_delta` / `thinking_end`、`toolcall_start`（带 `id`、`name`）/ `toolcall_delta`（参数 JSON 片段）/ `toolcall_end`（带完整 `toolCall`）、`done`（`reason: stop | length | toolUse`，带最终 `message`）、`error`（`reason: aborted | error`，带最终 `message`）。客户端重建：
+
+1. `message_start` 给出初始助手消息（`content: []`）；
+2. 按 `contentIndex` 维护内容块：`*_start` 建块，`*_delta` 追加文本（工具参数先当字符串拼接），`toolcall_end` 用完整 `toolCall` 替换该块；
+3. `usage` 是该时刻的最新用量，直接覆盖；
+4. 以 `message_end`（或 `done` / `error` 的 `message`）为准替换整条消息——重建结果只用于流式显示。
+
+### 会话统计
+
+`get_session_stats` 的 `data` 是 `SessionStats`：
+
+| 字段                                                               | 说明                                                                        |
+| ------------------------------------------------------------------ | --------------------------------------------------------------------------- |
+| `sessionId` / `sessionFile`                                        | 会话标识                                                                    |
+| `userMessages` / `assistantMessages` / `toolCalls` / `toolResults` | 计数                                                                        |
+| `tokens`                                                           | `{ input, output, cacheRead, cacheWrite, total }`，含保温请求的用量         |
+| `cost`                                                             | 美元；任一条消息缺成本时缺省（界面显示 `$?`）                               |
+| `contextTokens` / `contextWindow` / `contextPercent`               | 当前上下文估算、窗口与占用（0–100）；模型没有窗口时缺省                     |
+| `cacheHitRate`                                                     | 旧口径命中率：cacheRead /（input + cacheRead + cacheWrite），全部请求进分母 |
+| `cache`                                                            | `SessionCacheStats`（下例），会话层缓存控制器接线时才有                     |
+
+```json
+{
+  "type": "response",
+  "command": "get_session_stats",
+  "success": true,
+  "data": {
+    "tokens": { "input": 1177, "output": 64, "cacheRead": 2176, "cacheWrite": 0, "total": 3417 },
+    "cacheHitRate": 0.65,
+    "cache": {
+      "reporting": "reported",
+      "lastHitRate": 0.84,
+      "hitRate": 0.65,
+      "reBilledTokens": 0,
+      "reBilledUsd": 0,
+      "misses": { "count": 0, "byReason": {} },
+      "warming": { "mode": "streaming", "state": "stopped", "reason": "no_ttl" },
+      "contextRemainingTokens": 127077,
+      "estimatedTurnsLeft": 2443
+    }
+  }
+}
+```
+
+| `cache` 字段                                    | 说明                                                                                                                                                                             |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `reporting`                                     | 当前端点（供应商、baseUrl 主机、模型）的三态：`unknown` / `reported` / `silent`；只在内存，同一进程内跨会话复用                                                                  |
+| `lastHitRate` / `hitRate`                       | 最近一次 / 会话累计命中率（0–1）；`unknown` / `silent` 时没有 `lastHitRate`，不报缓存的请求不进 `hitRate` 分母                                                                   |
+| `reBilledTokens` / `reBilledUsd`                | 未命中重计费合计；有无价模型参与时没有 `reBilledUsd`                                                                                                                             |
+| `misses`                                        | `count` 与 `byReason`（`prefix_changed` / `model_changed` / `idle` / `subtask` / `evicted`）；统计计入全部未命中，不受界面提示门槛影响                                           |
+| `warming`                                       | `mode`（`off` / `streaming` / `idle`）、`state`（`inactive` / `scheduled` / `stopped`）、`phase?`、`nextWarmAt?`、停止原因 `reason?`、`sent?`、`costUsd?`、`expectedSavingsUsd?` |
+| `contextRemainingTokens` / `estimatedTurnsLeft` | 上下文余量与按最近 5 回合增量估算的剩余回合                                                                                                                                      |
+| `subagents`                                     | task 子会话汇总：`count`、`hitRate?`、`reBilledTokens`                                                                                                                           |
+| `granularity`                                   | 可选：当前端点推断的缓存读分块粒度（token，非零 cacheRead 的最大公约数，≥ 2 个样本且在 128–8192 才给）；未命中的噪声下限取它与 1024、`minTokens` 中的最大者                      |
+
+`tokens` / `cacheHitRate` 保持旧口径，新客户端用 `cache`。缓存事件示例：
+
+```json
+{"type":"cache_miss","missedTokens":142000,"missedCost":0.1278,"reason":"evicted","idleMs":3}
+{"type":"cache_warm","phase":"scheduled","nextWarmAt":1790000000000}
+{"type":"cache_warm","phase":"sent","usage":{"input":1,"output":1,"cacheRead":12000,"cacheWrite":0,"totalTokens":12002},"cost":0.0012}
+{"type":"cache_warm","phase":"stopped","reason":"no_cache_hits"}
+{"type":"context_pressure","percent":71,"threshold":70,"remainingTokens":57990,"estimatedTurnsLeft":6}
+```
+
+`cache_miss` 的 `detail` 只在 `prefix_changed` 时给出（`system` / `tools`）。`cache_warm{stopped}` 的 `reason` 取值与含义见 [tui.md](tui.md)「缓存与上下文」。`ama -p --output-format json` 的结果对象另有 `cache` 字段，形状同上。
+
+## 审批
+
+1. 工具调用需要确认时，服务端发 `permission_request`。`preview`（可选）是执行前预览：`{ kind: "bash" | "write" | "edit" | "other", lines: string[], severity: "info" | "warn" | "danger", affected?: { path, exists, bytes?, files? }[] }`，`lines` 已排好、不含颜色，可直接显示；预览只读、有上限，算不出时缺省。
+2. 客户端在此之前发过 `set_client_capabilities{capabilities:["approvals"]}` 才会被问到；否则这条 ask 无人作答 → deny。声明里去掉 `approvals` 会撤下客户端并让在等的审批全部按无人作答处理。
+3. 客户端回 `permission_response{requestId, decision}`。`allow_session` 在本会话内记住同一工具与归一化输入前缀，不落盘。先于请求到达的回答会暂存，等请求出现时使用。
+4. 回答者顺序：宿主 broker（`HostApi.approvals.setBroker`）→ RPC 客户端 → 无人作答 deny。审批串行，同一时刻只有一个在等。
+5. 超时：`timeoutMs`（缺省 600 000，即 10 分钟；环境变量 `AMA_APPROVAL_TIMEOUT_MS` 可改）内没有回答 → 服务端按 deny 处理并发 `permission_resolved`。运行被中断时同样 deny，即使客户端已经放行。
+
+## 退出
+
+- stdin 关闭：不再接收命令，撤下审批（之后的 ask 按无人作答 deny），等在途命令与已开始的运行结束、响应写完，退出码 0。所以 `printf '{"type":"prompt","message":"hi"}\n' | ama --mode rpc` 能拿到完整回复；要提前停止，先发 `abort`。
+- SIGINT / SIGTERM：中断当前运行后有序退出，退出码 130 / 143。
+- 启动阶段的失败按 CLI 退出码（[design.md](design.md) §11.3）：配置错误 3、无模型或 key 4、会话错误 5、宿主 / Hook 启动失败 6、宿主 API 版本不匹配 78。
+
+## 示例
+
+`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` 更新并审阅差异。
+
+最小会话（stdin 关闭即撤下审批，所以管道方式只适合不需要审批的提示；要回答审批，保持 stdin 打开并先发 `set_client_capabilities`）：
+
+```sh
+printf '%s\n' '{"id":"1","type":"prompt","message":"hi"}' | ama --mode rpc --model anthropic/<model-id>
+```

package/docs/session-format.md

@@ -0,0 +1,119 @@
+# 会话文件格式（JSONL 条目树）
+
+会话是一个只追加的 JSONL 文件：首行是头，其后每行一个条目（以及可选的 `leaf` 行）。条目经 `parentId` 连成树，「当前分支」是从根到叶子的一条路径；发给模型的上下文由当前分支**投影**得到。类型定义在 `src/session/types.ts`（经 `@armadra/agent` 导出），格式版本 `SESSION_FORMAT_VERSION = 1`。设计依据见 [design.md](design.md) §8、§9。
+
+## 位置与文件
+
+- 目录：`--session-dir` > profile `sessionDir` > `<数据目录>/sessions`（数据目录缺省 `~/.local/share/ama`，`AMA_DATA_DIR` 可改）。
+- 文件：`<sessions>/<编码 cwd>/<ISO 时间>_<uuid>.jsonl`。编码 cwd = 去掉开头的分隔符，`/`、`\`、`:` 换成 `-`；ISO 时间里的 `:` 与 `.` 也换成 `-`。文件名里的 uuid 就是会话 id。
+- 延迟落盘：新会话先在内存里，首次模型请求前才建文件、写头与已缓存的条目；之前退出不留文件。
+- 只追加：每条记录一行 JSON + LF，以 O_APPEND 写入。打开时若末行是半行（写入中途崩溃），截掉半行再继续；中间行损坏 → 拒绝打开（`session_corrupt`，退出码 5），不猜测、不重写文件。
+- 单写者锁：`<file>.lock`（O_EXCL 创建，内容为 pid）；持锁进程已不在时视为陈旧锁并接管。
+- `ama sessions prune [--older-than <天>]`（缺省 30 天）把文件移到 `<sessions>/.trash/`，文件名前缀删除时间；trash 里超过 7 天的再清理。
+
+## 头
+
+```json
+{
+  "type": "session",
+  "version": 1,
+  "id": "0b7f…",
+  "timestamp": "2026-10-02T08:00:00.000Z",
+  "cwd": "/home/me/proj",
+  "agent": { "name": "ama", "version": "0.1.0" },
+  "parentSession": "/…/上一个会话.jsonl"
+}
+```
+
+`parentSession` 只在 fork 与 `task` 子会话里出现，指向来源文件。读取时 `version` 不是 1 → 拒绝并提示升级 ama；缺头、头损坏、条目缺 `id` 或 `type`、出现第二个头 → 拒绝。
+
+## 条目
+
+全部条目都有 `id`、`parentId`（根条目为 `null`）、`timestamp`（ISO 8601）。
+
+| `type`                  | 字段                                                                                                 | 进上下文                     |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------- |
+| `message`               | `message`：`system` / `user` / `assistant` / `toolResult` 四种 LLM 消息                              | 是                           |
+| `compaction`            | `summary`、`firstKeptEntryId`、`tokensBefore`、`usage?`、`details?`（`readFiles` / `modifiedFiles`） | 是，作为摘要消息             |
+| `branch_summary`        | `fromId`、`summary`、`usage?`、`details?`                                                            | 是，作为分支摘要消息         |
+| `context_edit`          | `targetId`、`replacement: string \| null`、`reason: prune \| abort \| retry \| overflow \| manual`   | 改写目标条目                 |
+| `model_change`          | `provider`、`modelId`、可选 `channel`（多渠道供应商的渠道名）                                        | 否（决定续会话时的模型）     |
+| `thinking_level_change` | `thinkingLevel`                                                                                      | 否（决定续会话时的思考级别） |
+| `custom`                | `customType`、`data`                                                                                 | 否                           |
+| `custom_message`        | `customType`、`content`（字符串或内容块）、`display`、`details?`                                     | 是，作为 custom 消息         |
+| `label`                 | `targetId`、`label?`（缺省 = 清除标签）                                                              | 否                           |
+| `session_info`          | `name?`                                                                                              | 否                           |
+| `usage`                 | `kind`、`provider`、`model`（不含 provider 的模型 id）、`usage`                                      | 否                           |
+
+### 消息
+
+- `system`：`{ role: "system", sections, toolsAdded?, toolsRemoved?, timestamp }`。首条是全量：系统提示的命名节（固定顺序 `preamble → tools → rules → project_context → skills → hooks → cwd → host`）与工具声明表；之后只落**补丁**——节名级替换、值为 `null` 表示删除该节，`toolsAdded` / `toolsRemoved` 增删工具。依次重放得到当前系统提示；请求时由协议层重装全量。首条 system 消息在首次请求前落盘，也就是建文件的时刻。
+- `user`：`content`、`origin?`（缺省 = 普通用户输入；`steer` / `followUp` 是运行中插话与排队，`host` 是宿主 `sendUser` 注入，其它字符串原样记录）。
+- `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?`）。
+
+### `usage` 条目
+
+不进上下文的请求用量，计入 `/session` 费用与 RPC 统计，投影时跳过。第一期只有 `kind: "cache_warm"`（缓存保温请求，见 [providers.md](providers.md)「缓存」）：
+
+```json
+{
+  "type": "usage",
+  "kind": "cache_warm",
+  "provider": "anthropic",
+  "model": "<model-id>",
+  "usage": {
+    "input": 1,
+    "output": 1,
+    "cacheRead": 12000,
+    "cacheWrite": 0,
+    "totalTokens": 12002,
+    "cost": { "input": 0, "output": 0, "cacheRead": 0.0036, "cacheWrite": 0, "total": 0.0036 }
+  },
+  "id": "…",
+  "parentId": "…",
+  "timestamp": "…"
+}
+```
+
+### `leaf` 行
+
+`/tree` 在同一文件里换叶子时追加一行 `{"type":"leaf","id":<条目 id 或 null>,"timestamp":…}`。它**不是条目**：没有 `parentId`，`get_entries` 与树不返回它，fork 不复制它。打开文件时，最后一条 `leaf` 行若在最后一条条目之后，就用它的 `id` 作叶子（`null` = 回到根之前的空分支）；之后又追加了条目则作废。
+
+`usage` 条目与 `leaf` 行都是 v1 的可选行，格式版本不升。
+
+## 投影
+
+当前分支 → 上下文消息（`src/session/projection.ts`）：
+
+1. **压缩**：分支上若有 `compaction`，取最新一条。上下文 = 该 compaction（作为摘要消息）+ `firstKeptEntryId` 到它之间的非 system 条目 + 它之后的全部条目。compaction 之前的 system 消息依次重放后折成一条完整的 system **检查点**放在最前（文件里不另存检查点）。
+2. **改写**：对分支上每个目标取最新一条 `context_edit`：`replacement` 为 `null` → 从上下文剔除；字符串 → 只换内容，保留角色与元数据（assistant 换成一个文本块，摘要类换 `summary`，system 不改）。用途：档一裁剪旧工具结果（`prune`）、中断（`abort`）、失败重试的尝试（`retry`）、溢出恢复（`overflow`）、手动（`manual`）。
+3. **映射**：`message` → 原消息；`custom_message` → `{ role: "custom", customType, content, display, details? }`；`compaction` → `{ role: "compactionSummary", summary, tokensBefore }`；`branch_summary` → `{ role: "branchSummary", summary, fromId }`；其余类型（含 `usage` 与未知类型）不进上下文。
+4. **模型与思考级别**：分支上最近的 `model_change` / `thinking_level_change`，续会话时据此恢复。
+
+发给模型前，`convertToLlm` 把三种扩展角色（custom、compactionSummary、branchSummary）转成 user 消息。
+
+## 分支与 fork
+
+- `/tree`：同一文件换叶子（落 `leaf` 行）；从旧位置再发消息就形成新分支。离开的分支可以写 `branch_summary` 带进新分支。
+- fork（`--fork <id>`、`/fork`、RPC `fork`）：把根 → 指定条目的分支复制到新文件，头的 `parentSession` 指回原文件；不复制 `leaf` 行。
+- `task` 子会话：独立文件，头带 `parentSession`，首条条目是 `custom{customType:"ama.task"}`。
+
+## custom 类型
+
+`custom` 不进上下文，`custom_message` 进上下文。ama 自己使用的 `customType`：
+
+| `customType`         | 条目类型         | 内容                                                                                | 写入时机                                                |
+| -------------------- | ---------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `ama.todo`           | `custom`         | `data: { items: { id, text, status: pending \| in_progress \| done }[] }`，整表快照 | `todo` 工具 `set`；`get` 取分支上最近一条               |
+| `ama.task`           | `custom`         | `data: { parentToolCallId, description, parentSession? }`                           | `task` 子会话的首条条目                                 |
+| `ama.codemode-store` | `custom`         | `data: { entries }`，`store()` 的完整快照                                           | codemode 脚本成功结束且写过 store；读取取分支上最近一条 |
+| `ama.aborted`        | `custom_message` | `content`：告诉模型上一条回复被用户中断；`display: false`                           | 用户中断运行                                            |
+| `ama.hook_context`   | `custom_message` | `content`：UserPromptSubmit Hook 的 `additionalContext`；`display: false`           | 随用户提示进上下文                                      |
+
+其它程序（宿主、SDK 工具经 `ToolContext.session.appendCustom`）可以写自己的 `customType`；建议加前缀避免冲突，`ama.` 前缀保留给 ama。
+
+## 读取方
+
+- `ama sessions list|show`、交互模式 `/resume`、RPC `get_entries{since}`（以 entry id 为游标返回 `{ entries, leafId }`）、`get_tree`。
+- 嵌入方可以直接读文件：按行解析，首行为头，跳过 `type: "leaf"` 的行后按 `parentId` 建树；遇到不认识的条目类型保留但不进上下文。

package/docs/tui.md

@@ -0,0 +1,170 @@
+# 终端界面
+
+交互模式的使用说明，以及终端组件库 `@armadra/agent/tui` 的 API。设计依据见 [design.md](design.md) §12。
+
+`ama` 在终端里直接运行（stdin / stdout 都是 TTY、`TERM` 不是 `dumb`、没有 `--no-tui`）时进入交互模式。界面只用**主屏**：对话历史滚进终端回滚，不切备用屏，所以在 tmux 里 `capture-pane` 能读到完整对话，退出后对话也留在屏幕上。
+
+## 布局
+
+```
+ama 0.1.0 · Enter 发送 · Esc 中断 · Ctrl+C 两次退出 · /help 命令    ← 启动画面
+› 读一下 README                                                    ← 用户消息
+思考 · 120 token                                                    ← 思考块（折叠）
+● read  README.md                                                   ← 工具调用
+  …前 3 行结果…
+回答正文（Markdown）
+↳ followUp  之后再提交                                               ← 排队消息
+⠋ 工作中 · Esc 中断 (12s)                                            ← 运行中
+──────────────────────────────────
+输入框
+──────────────────────────────────
+anthropic/claude-sonnet · think:medium · ↑12k ↓1.2k · cache 80% ♨ · $0.12 · rebill $0.11 · ctx 34% · mode:default · preset:default
+```
+
+- **用户消息**：`›` 开头；运行中插话标 `↳ steer`，排到本轮之后的标 `↳ followUp`，宿主（Armadra 画布）注入的标 `↳ host`。
+- **思考块**：`ui.showThinking` = `collapsed`（缺省，一行计数）/ `full`（全文）/ `hidden`。
+- **工具调用**：一行标题，圆点运行中为强调色、成功绿、失败红；折叠显示结果前 3 行，`edit` 显示 diff（前 12 行），`bash` 运行中滚动显示最后 8 行。`Ctrl+O` 展开 / 折叠全部。codemode 脚本里的内层调用挂在外层调用下面。
+- **提示**：压缩摘要卡、`↻ 重试 n/m`、`⛔ Hook 阻止`、宿主通知、审批被拒或超时的说明都进消息区。
+- **状态栏**：模型 · 思考级别 · `↑` 输入（含缓存读写）`↓` 输出 · 缓存 · 费用 · 重计费 · 上下文占用 · 排队数 · 权限模式 · codemode · 工具预设 · 宿主状态。终端太窄时依次丢弃宿主状态、预设、重计费、费用、缓存、token、思考级别、排队数、codemode，模型、上下文与权限模式最后丢。
+
+## 缓存与上下文
+
+状态栏各项：
+
+| 项              | 含义                                                                                                                |
+| --------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `cache 83%`     | **最近一次**请求的命中率（读缓存 /（输入 + 缓存读 + 缓存写））；会话累计在 `/session`                               |
+| `cache —`       | 端点还没报过缓存（`unknown`：还没有足够长的可比请求）                                                               |
+| `cache 未报告`  | 端点不报缓存（`silent`：连续 3 个可比请求读写都是 0，或 `compat.cacheReporting: "silent"`）；这类请求不进命中率分母 |
+| `♨`             | 保温计时中（工具长时间运行时按 TTL 重放前缀，`/cache warm` 可切换）                                                 |
+| `rebill $0.11`  | 本会话缓存未命中导致的重计费金额；模型没有价格时显示 token 数；为 0 不显示                                          |
+| `ctx 72%`       | 上下文占用，≥ 70% 黄色、≥ 90% 红色；`ctx ?` 表示模型没有窗口信息                                                    |
+| `codemode:only` | codemode 生效（`on` / `only`）；运行时 Node 的权限模型不隔离网络（Node 22 / 24）时追加红色 `net!`                   |
+
+消息区（line 模式写 stderr，前缀 `ama: `）只在两种情况下提示一行，`cache.missNotices: false` 可关：
+
+- 一次未命中重计费 ≥ 20k token 或 ≥ $0.10：`缓存未命中（空闲 7 分钟后）：重计费 38.2k token（约 $0.11）`。原因有空闲超时、子任务运行、切换模型、系统提示 / 工具表变化、服务端淘汰；更小的未命中只进统计。
+- 上下文占用跨过 70% / 90%（各一次）：`上下文已用 72%，约剩 9 回合（按最近 5 回合均值）`；回合数估不出时给余量 token。
+- line 模式在 `AMA_LOG=info` 时另写保温成功：`缓存保温已刷新（读 12k token，$0.001）`。
+
+`/session` 在会话信息之后有「缓存」段，`/cache` 只显示这一段：
+
+```
+缓存
+  输入      3.4k = 缓存读 2.2k（65%）+ 未缓存 1.2k
+  报告状态  reported
+  命中率    最近 84% · 会话 65%
+  未命中    0 次
+  保温      streaming · 已停止：模型目录没有缓存 TTL
+  上下文    1%，余量 ≈ 127k token ≈ 2443 回合
+```
+
+未命中行按原因分列（`3 次，重计费 61k token ≈ $0.18（空闲超时 2 · 前缀变化 1）`）；保温行在计时中显示 `streaming · 下次 2m 10s · 期望节省 $0.18 ≥ $0.05`，停止时给原因；有 task 子会话时另有「子任务」行。
+
+- `/cache warm off|streaming|idle`：本会话内切换保温（不写配置；`idle` 在空闲时也保温，适合贵模型）。
+- `/cache fingerprint`：最近一次真实请求的前缀指纹——system 与工具表各一个 16 位哈希加模型名。两次之间哈希变了，就是宿主或 Hook 中途改了系统提示 / 工具表。
+
+取舍：状态栏显示最近一次命中率（会话累计放 `/session`）；`cache.missNotices` 缺省开（门槛下很少触发）；`Meter` 组件不进缺省状态栏。命中率、未命中与保温的判定规则见 [providers.md](providers.md)「缓存」。
+
+`ama models cache-probe <provider/model>` 用一个固定前缀相隔几秒发两次最小请求，判定端点 `reported` / `silent` / `inconclusive` 并给出配置建议（会计费：先打印预估，非交互环境需 `--yes`）。
+
+## 按键
+
+| 按键                 | 作用                                                               |
+| -------------------- | ------------------------------------------------------------------ |
+| Enter                | 发送；运行中 = steer（插到当前轮）                                 |
+| Alt+Enter            | 运行中排到本轮之后（followUp）；空闲时等同 Enter                   |
+| Shift+Enter / Ctrl+J | 换行                                                               |
+| Esc                  | 中断：排队的消息回填到输入框，然后停止当前运行；补全打开时先关补全 |
+| Alt+↑                | 取回最后一条排队消息                                               |
+| Shift+Tab            | 循环权限模式 plan → default → auto-edit → full-auto                |
+| Ctrl+O               | 展开 / 折叠工具输出                                                |
+| Ctrl+L / Ctrl+T      | 选择模型 / 思考级别                                                |
+| Ctrl+C               | 清空输入；输入为空时 1.5 秒内再按一次退出（退出码 130）            |
+| Ctrl+D               | 输入为空时退出                                                     |
+| Tab                  | 补全                                                               |
+| ↑ / ↓                | 单行时浏览历史（`<数据目录>/history`，500 条）                     |
+
+按键可在 `~/.config/ama/keybindings.json` 覆盖，键是动作 id（`app.interrupt`、`app.message.followUp`、`tui.editor.newLine` ……），值是按键或按键数组，空数组表示禁用。
+
+## 命令
+
+`/help` 列出全部命令。交互模式另有：
+
+- `/tree`：列出会话里的全部用户消息（分叉处缩进，`●` 是当前分支）；选中一条后回到它之前，原文回填输入框，修改后发送就形成新分支。
+- `/fork`（无参数）：同样选一条用户消息，从它之前复制出新会话。
+- `/model`、`/resume`、`/permission`、`/thinking` 不带参数时打开选择器；`/permissions` 显示权限判定顺序与已加载规则。
+- `/model` 选择器按「供应商 · 渠道」分组（多渠道模型在每个渠道下各一项，非首选渠道带 `@渠道`），说明里有上下文与 `img`（收图片）；`/model packy/kimi-k2.5@messages` 直接切到指定渠道。
+- 输入里的 `@图片路径`（可加引号，Tab 补全路径）或粘贴 / 拖入的图片文件路径作为图片附件随消息发送；当前模型不收图片时 `@` 附件报错、不发送，未加 `@` 的路径忽略（见 [providers.md](providers.md)「图像输入」）。
+- `/session`、`/cache`：会话用量与缓存统计（见下文「缓存与上下文」）。
+
+## 补全
+
+- 首行行首输入 `/`：命令、提示模板（`/<名字>`）、Skill（`/skill:<名字>`）。
+- `@`（行首或空格之后）：当前目录下的文件与目录（尊重 `.gitignore`），含 `*` `?` `[` `{` 时按 glob 匹配相对路径。
+
+## 审批
+
+工具调用需要确认时，底部弹出对话框：bash 显示完整命令，write 显示路径与行数，edit 显示每处修改的 −/+ 摘要；子 Agent 发起的请求标 `[task]`。`y` 允许、`n` / Esc 拒绝、`a` 本会话内同类不再询问、`v` 查看完整输入。10 分钟不作答按拒绝处理（`AMA_APPROVAL_TIMEOUT_MS` 可改）。
+
+输入摘要之后是**执行前预览**：这一步会碰到什么。
+
+- bash：识别每段命令（含 `sh -c`、`eval`、`xargs`、`find -exec` 里嵌套的命令）中的 `rm` / `rmdir` / `unlink`、`mv`、`git clean`、`git checkout -- <路径>`、`git reset --hard` 与 `>` / `>>` 重定向目标，列出路径是否存在、大小、目录里的文件数；通配符与变量不展开，原样显示并提示实际范围可能更大。
+- write：目标是否存在、现有行数与大小 → 新内容；覆盖本会话没读过的文件标黄。
+- edit：对原文干跑一遍，列出每处 −n/+m 行与总变化；匹配不到或不唯一时提前说明。
+
+预览按严重度着色（危险红、警告黄、其余暗色），只读、有上限：每个目录最多计 2000 项，整次预览 200 ms 预算，超出只给提示、不降低严重度；超过 2 MiB 的文件只报大小。预览失败不影响审批。line 模式在问句之前逐行打印同样的预览；RPC 客户端从 `permission_request.preview` 拿到它（[rpc.md](rpc.md)「审批」）。
+
+## 启动画面
+
+`ui.quietStartup` / `--quiet-startup`：`normal` 显示标题、模型、目录与信任状态、已加载的上下文文件 / Skill / 提示模板 / Hook；`header` 只有标题行（profile 缺省）；`silent` 不显示。`--resume` 不带 id、模型没有 key、会话目录不存在、项目资源需要信任时，界面启动前会先出现一个小的选择 / 输入提示，答完收成一行留在屏幕上。
+
+## 在 tmux / Armadra 终端节点里
+
+- 括号粘贴：启动时开启；粘贴的多行内容整体进入输入框（超过 10 行或 1 000 字符折叠为 `[paste #N +M lines]`），粘贴后紧跟的回车直接发送，适合由外部程序写入。
+- 不查询终端能力、不开鼠标与 Kitty 键盘协议，避免回包混进输入；tmux ≥ 3.4 透传同步输出，旧版本也能正常显示。
+- 窗口尺寸变化时整屏重画最后一屏，回滚里的历史不受影响。
+- 自动降级：非 TTY、`TERM=dumb`、`--no-tui` 或终端初始化失败时使用行式界面，命令与审批问答相同。
+
+## 组件库（`@armadra/agent/tui`）
+
+交互模式用的终端组件单独导出，零依赖，宿主或其它 Node 程序可以直接用来画主屏界面。
+
+```ts
+import { TUI, ProcessTerminal, Text, Editor, createTheme } from "@armadra/agent/tui";
+
+const tui = new TUI(new ProcessTerminal());
+const theme = createTheme("dark");
+const log = new Text("");
+const editor = new Editor({
+  theme,
+  requestRender: () => tui.requestRender(),
+  onSubmit: (text) => {
+    log.setText(`you said: ${text}`);
+    tui.requestRender();
+  },
+});
+tui.addChild(log);
+tui.addChild(editor);
+tui.setFocus(editor);
+tui.start();
+```
+
+| 导出                                                                        | 作用                                                                                                                                 |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `Component`、`Focusable`、`CURSOR_MARKER`                                   | 组件契约：`render(width)` 返回各行（每行可见宽 ≤ width）、`handleInput?(data)`、`invalidate()`；获焦组件在光标处输出 `CURSOR_MARKER` |
+| `TUI`                                                                       | 根容器与差分渲染（主屏、同步输出）：`addChild`、`start` / `stop`、`requestRender`、`setFocus`、`addInputListener`、`showOverlay`     |
+| `ProcessTerminal`、`MemoryTerminal`、`VirtualScreen`                        | 真实终端（raw 模式、括号粘贴）；内存终端与 VT 屏幕（测试、帧黄金）                                                                   |
+| `Container`、`Text`、`TruncatedText`、`Markdown`、`Box`、`Spacer`、`Loader` | 基础组件                                                                                                                             |
+| `Editor`、`EditorBuffer`、`PasteStore`                                      | 多行编辑器（历史、补全接口 `AutocompleteProvider`、粘贴折叠）                                                                        |
+| `SelectList`                                                                | 可过滤的选择列表                                                                                                                     |
+| `KeyValue`、`Meter`                                                         | 两列对齐的键值表；进度条                                                                                                             |
+| `compositeOverlays`、`OverlayOptions`                                       | 覆盖层合成（居中 / 底部锚定）                                                                                                        |
+| `createTheme`、`plainTheme`、`detectCapabilities`、`Theme`                  | 主题与颜色能力探测（`NO_COLOR`、16 / 256 / truecolor）；11 个语义色                                                                  |
+| `Keybindings`、`DEFAULT_KEYBINDINGS`、`loadKeybindingsFile`                 | 动作 id → 按键，`keybindings.json` 覆盖                                                                                              |
+| `parseKey`、`matchesKey`、`StdinBuffer`                                     | 键序列解析与 Esc 超时切分（`AMA_TUI_ESC_TIMEOUT`）                                                                                   |
+| `visibleWidth`、`truncateToWidth`、`wrapTextWithAnsi`、`sliceByColumn` 等   | 带 ANSI 与宽字符的宽度计算与截断                                                                                                     |
+
+## 测试
+
+`src/modes/interactive/interactive-mode.test.ts` 用 `MemoryTerminal`（80x24、40x24）+ fake 供应商跑一次完整的读文件 run，把启动、输入、工具运行中、结束、`Ctrl+O` 展开、退出各帧写进 `test/fixtures/tui/run-*.txt`。改界面后用 `AMA_UPDATE_GOLDEN=1 pnpm vitest run src/modes/interactive` 更新并审阅差异。