min-agent 0.3.0 → 0.4.0

package/docs/superpowers/plans/2026-08-20-tui-completeness.md

@@ -0,0 +1,873 @@
+# TUI 补齐（第 1 批）— 实现计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 会话内切换并画出历史；`/reload`；输入历史落盘；Home/End 与折行移动；点击斜杠菜单；双击/三击与复制去前缀；Ctrl+B 消息区选择；TUI 中 `task` 可展开子工具。
+
+**Architecture:** 先落地可单测的纯函数（hydrate、历史文件、caret 垂直移动、选区去前缀、点击计数、会话切换守卫），再接到现有 Ink 组件。新 UI 只加 `SessionPicker`。选择模式复用 `selectionRanges`。
+
+**Tech Stack:** TypeScript, React 18 + Ink 5, bun:test
+
+**Spec:** `docs/superpowers/specs/2026-08-20-tui-completeness-design.md`
+
+测试命令（`packages/min-agent` 下）：`bun test tests/<file>`；类型：`npx tsc --noEmit`；仓库根目录：`bun run typecheck`。
+
+---
+
+## 文件结构
+
+| 文件 | 职责 |
+|---|---|
+| `src/tui/hydrate.ts`(新) | `ModelMessage[]` → `TuiMessage[]` |
+| `tests/hydrate.test.ts`(新) | hydrate 映射 |
+| `src/tui/session-switch.ts`(新) | 切换守卫、`lastUserText` |
+| `tests/session-switch.test.ts`(新) | running/current/missing |
+| `src/tui/input-history.ts`(改) | 上限 1000、parse/serialize、load/save |
+| `tests/input-history.test.ts`(改) | 文件格式与坏文件 |
+| `src/tui/caret-pos.ts`(改) | `moveCaretVertical`、Home/End 扫描 |
+| `tests/caret-pos.test.ts`(改) | 折行上下 |
+| `src/tui/selection.ts`(改) | 去前缀、选词范围 |
+| `tests/selection.test.ts`(改) | 去前缀与词界 |
+| `src/tui/click-count.ts`(新) | 双击/三击计数 |
+| `tests/click-count.test.ts`(新) | 400ms / 列差 |
+| `src/tui/SessionPicker.tsx`(新) | 会话选择器 |
+| `src/tui/types.ts` `index.tsx` `App.tsx` `StatusBar.tsx`(改) | picker、selectionMode |
+| `src/tui/slash-commands.ts` `slash-handler.ts` `tui-chat.ts`(改) | `/sessions` `/resume` `/reload` |
+| `src/tui/agent-runner.ts`(改) | `getSystemPrompt`、子 agent 回调 |
+| `src/tui/InputBar.tsx`(改) | 历史落盘、编辑键、点菜单 |
+| `src/tui/MessageList.tsx`(改) | 去前缀复制、双击三击、选择模式、子工具行 |
+| `src/tools/task.ts`(改) | `onSubToolCall` / `onSubToolResult` |
+| `README.md` `/help` `AGENTS.md`(改) | 文案 |
+
+---
+
+## Task 1: hydrate.ts
+
+**Files:**
+- Create: `src/tui/hydrate.ts`
+- Test: `tests/hydrate.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+```ts
+import { expect, test } from "bun:test"
+import type { ModelMessage } from "ai"
+import { hydrateMessages, lastUserText } from "../src/tui/hydrate.js"
+
+test("hydrateMessages maps user string content", () => {
+  const out = hydrateMessages([{ role: "user", content: "hello" }])
+  expect(out).toHaveLength(1)
+  expect(out[0]).toMatchObject({ role: "user", content: "hello" })
+})
+
+test("hydrateMessages uses image placeholder when there is no text", () => {
+  const out = hydrateMessages([{
+    role: "user",
+    content: [{ type: "image", image: "x" }],
+  } as ModelMessage])
+  expect(out[0]!.content).toBe("[📎 图片]")
+})
+
+test("hydrateMessages keeps user text and ignores image parts when both exist", () => {
+  const out = hydrateMessages([{
+    role: "user",
+    content: [
+      { type: "text", text: "看这张" },
+      { type: "image", image: "x" },
+    ],
+  } as ModelMessage])
+  expect(out[0]!.content).toBe("看这张")
+})
+
+test("hydrateMessages keeps assistant text and drops tool-call parts", () => {
+  const out = hydrateMessages([{
+    role: "assistant",
+    content: [
+      { type: "text", text: "ok" },
+      { type: "tool-call", toolCallId: "1", toolName: "bash", input: {} },
+    ],
+  } as ModelMessage])
+  expect(out).toHaveLength(1)
+  expect(out[0]).toMatchObject({ role: "assistant", content: "ok" })
+})
+
+test("hydrateMessages maps tool results", () => {
+  const out = hydrateMessages([{
+    role: "tool",
+    content: [{ type: "tool-result", toolCallId: "1", toolName: "bash", output: "done" }],
+  } as ModelMessage])
+  expect(out).toHaveLength(1)
+  expect(out[0]!.role).toBe("tool")
+  expect(out[0]!.toolName).toBe("bash")
+  expect(out[0]!.content.length).toBeGreaterThan(0)
+})
+
+test("hydrateMessages skips unknown roles and empty assistant", () => {
+  expect(hydrateMessages([
+    { role: "system", content: "nope" } as ModelMessage,
+    { role: "assistant", content: [] } as ModelMessage,
+  ])).toEqual([])
+})
+
+test("lastUserText returns the last user string", () => {
+  expect(lastUserText([
+    { role: "user", content: "one" },
+    { role: "assistant", content: "a" },
+    { role: "user", content: [{ type: "text", text: "two" }] },
+  ] as ModelMessage[])).toBe("two")
+  expect(lastUserText([{ role: "assistant", content: "a" }] as ModelMessage[])).toBeNull()
+})
+```
+
+把 `lastUserText` 放在 `hydrate.ts`（spec 写在 session-switch，同文件或 hydrate 均可；本计划放 hydrate，session-switch 只做守卫）。
+
+- [ ] **Step 2: 运行确认失败**
+
+Run: `bun test tests/hydrate.test.ts`
+Expected: FAIL（模块不存在）
+
+- [ ] **Step 3: 实现 `src/tui/hydrate.ts`**
+
+- `user`：`content` 为 string 用其本身；为数组则拼接所有 `type === "text"` 的 `text`；没有任何文本但有 image/file part → `[📎 图片]`；完全空 → 跳过
+- `assistant`：string 或 text parts 拼接；无文本 → 跳过
+- `tool`：读 `content` 数组里 `tool-result`：`toolName` 缺则跳过；`content` = `summarizeToolCall` 若无 input 则用 `toolName`；`toolResult` / `toolResultSummary` 用 `toolResultText` / `summarizeToolResult`
+- id：`hyd-${index}-${role}`；`timestamp: 0`
+- 其它 role：跳过
+
+`lastUserText`：从后往前找 `role === "user"`，规则与 hydrate 的 user 文本相同；仅图片返回 `null`。
+
+- [ ] **Step 4: 运行确认通过**
+
+Run: `bun test tests/hydrate.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/tui/hydrate.ts tests/hydrate.test.ts
+git commit -m "feat: 将会话消息映射为 TUI 行"
+```
+
+---
+
+## Task 2: session-switch 守卫
+
+**Files:**
+- Create: `src/tui/session-switch.ts`
+- Test: `tests/session-switch.test.ts`
+
+- [ ] **Step 1: 写失败测试**
+
+```ts
+import { expect, test } from "bun:test"
+import { prepareSwitch } from "../src/tui/session-switch.js"
+
+test("prepareSwitch rejects while running", () => {
+  expect(prepareSwitch({ running: true, currentId: "a", targetId: "b", exists: true })).toEqual({
+    ok: false, reason: "running",
+  })
+})
+
+test("prepareSwitch rejects the current session", () => {
+  expect(prepareSwitch({ running: false, currentId: "a", targetId: "a", exists: true })).toEqual({
+    ok: false, reason: "current",
+  })
+})
+
+test("prepareSwitch rejects a missing session", () => {
+  expect(prepareSwitch({ running: false, currentId: "a", targetId: "z", exists: false })).toEqual({
+    ok: false, reason: "missing",
+  })
+})
+
+test("prepareSwitch accepts a different existing session", () => {
+  expect(prepareSwitch({ running: false, currentId: "a", targetId: "b", exists: true })).toEqual({
+    ok: true,
+  })
+})
+```
+
+- [ ] **Step 2: FAIL** — `bun test tests/session-switch.test.ts`
+
+- [ ] **Step 3: 实现**
+
+```ts
+export type SwitchFail = "running" | "current" | "missing"
+
+export function prepareSwitch(opts: {
+  running: boolean
+  currentId: string | undefined
+  targetId: string
+  exists: boolean
+}): { ok: true } | { ok: false; reason: SwitchFail } {
+  if (opts.running) return { ok: false, reason: "running" }
+  if (opts.currentId === opts.targetId) return { ok: false, reason: "current" }
+  if (!opts.exists) return { ok: false, reason: "missing" }
+  return { ok: true }
+}
+
+export function switchFailMessage(reason: SwitchFail): string {
+  if (reason === "running") return "请先等待当前回合结束或按 Esc 取消"
+  if (reason === "current") return "已是当前会话"
+  return "会话不存在"
+}
+```
+
+- [ ] **Step 4: PASS** — `bun test tests/session-switch.test.ts`
+
+- [ ] **Step 5: 提交** `feat: 会话切换守卫`
+
+---
+
+## Task 3: 输入历史文件
+
+**Files:**
+- Modify: `src/tui/input-history.ts`
+- Modify: `tests/input-history.test.ts`
+
+- [ ] **Step 1: 追加测试**
+
+```ts
+import { parseHistoryFile, serializeHistoryFile, HISTORY_LIMIT } from "../src/tui/input-history.js"
+
+test("HISTORY_LIMIT is 1000", () => {
+  expect(HISTORY_LIMIT).toBe(1000)
+})
+
+test("parseHistoryFile reads entries array", () => {
+  expect(parseHistoryFile('{"entries":["a","b"]}')).toEqual(["a", "b"])
+})
+
+test("parseHistoryFile returns null for corrupt payloads", () => {
+  expect(parseHistoryFile("{")).toBeNull()
+  expect(parseHistoryFile("[]")).toBeNull()
+  expect(parseHistoryFile('{"entries":[1]}')).toBeNull()
+})
+
+test("serializeHistoryFile round-trips", () => {
+  expect(parseHistoryFile(serializeHistoryFile(["x"]))).toEqual(["x"])
+})
+
+test("pushInput trims to HISTORY_LIMIT", () => {
+  let h = createHistory()
+  for (let i = 0; i < 1005; i++) h = pushInput(h, `e${i}`)
+  expect(h.entries).toHaveLength(1000)
+  expect(h.entries[0]).toBe("e5")
+  expect(h.entries[999]).toBe("e1004")
+})
+```
+
+现有 `pushInput` 测试仍应通过；把 `const HISTORY_LIMIT = 500` 改为 `export const HISTORY_LIMIT = 1000`。
+
+- [ ] **Step 2: FAIL**（LIMIT 仍是 500 / 无 parse 函数）
+
+- [ ] **Step 3: 实现**
+
+`parseHistoryFile(raw: string): string[] | null`：JSON 对象且 `entries` 为 string[] 才返回，否则 `null`。
+
+`serializeHistoryFile(entries: string[]): string`：`JSON.stringify({ entries }, null, 2)`。
+
+`loadInputHistory(): string[]`：读 `path.join(getConfigDir(), "input-history.json")`；不存在 → `[]`；parse 失败 → 尝试 `renameSync` 到 `input-history.json.corrupt-${Date.now()}`，返回 `[]`。
+
+`saveInputHistory(entries: string[]): void`：目录 `mkdirSync`；写 `*.tmp-${randomUUID()}` 再 `renameSync`；catch 后尽量删 tmp，不抛。
+
+`InputBar` 本 task **先不接** load/save（下一截 InputBar task）。本 task 只把纯函数和 fs 辅助做好并单测 parse/serialize/limit；`load`/`save` 若要用临时目录测，可在测试里传 path 重载：
+
+```ts
+export function loadInputHistoryFrom(file: string): string[]
+export function saveInputHistoryTo(file: string, entries: string[]): void
+export function loadInputHistory(): string[] {
+  return loadInputHistoryFrom(path.join(getConfigDir(), "input-history.json"))
+}
+```
+
+给 `loadInputHistoryFrom` 加一个 bun test：写临时文件、读回、坏文件改名。用 `mkdtempSync`。
+
+- [ ] **Step 4: PASS** — `bun test tests/input-history.test.ts`
+
+- [ ] **Step 5: 提交** `feat: 输入历史上限 1000 并落盘`
+
+---
+
+## Task 4: moveCaretVertical + Home/End 扫描
+
+**Files:**
+- Modify: `src/tui/caret-pos.ts`
+- Modify: `tests/caret-pos.test.ts`
+
+- [ ] **Step 1: 追加测试**
+
+```ts
+import { moveCaretVertical, scanHomeEndKeys } from "../src/tui/caret-pos.js"
+
+test("moveCaretVertical stays on the same display column across wrapped rows", () => {
+  // width 4 → "abcd" / "ef"
+  expect(moveCaretVertical("abcdef", 1, 1, 4)).toBe(5) // 'b' col1 → 'f' col1 of row1
+})
+
+test("moveCaretVertical up from the first row returns the same index", () => {
+  expect(moveCaretVertical("abcdef", 1, -1, 4)).toBe(1)
+})
+
+test("moveCaretVertical down from the last row returns the same index", () => {
+  expect(moveCaretVertical("abcdef", 5, 1, 4)).toBe(5)
+})
+
+test("moveCaretVertical crosses a newline", () => {
+  expect(moveCaretVertical("ab\ncd", 1, 1, 10)).toBe(4) // 'b' → 'd'
+})
+
+test("scanHomeEndKeys finds CSI H/F and 1~/4~", () => {
+  expect(scanHomeEndKeys("", "\x1b[H").actions).toEqual([{ kind: "home" }])
+  expect(scanHomeEndKeys("", "\x1b[F").actions).toEqual([{ kind: "end" }])
+  expect(scanHomeEndKeys("", "\x1b[1~").actions).toEqual([{ kind: "home" }])
+  expect(scanHomeEndKeys("", "\x1b[4~").actions).toEqual([{ kind: "end" }])
+  expect(scanHomeEndKeys("", "hello").actions).toEqual([])
+})
+```
+
+`moveCaretVertical` 语义：用 `visualRows(value, maxWidth)` 找到 caret 所在行与该行内显示列（`displayWidth` of chars before caret in that row）；目标行 = 当前行 ± 1，越界则返回原 `caretIndex`；目标行上用 `caretIndexFromClick` 同类：按显示列落到最近字符边界。`textStartColumn` 对函数无意义，直接在行内 width 上算。
+
+建议实现：
+
+```ts
+export function moveCaretVertical(value: string, caretIndex: number, direction: 1 | -1, maxWidth: number): number {
+  const rows = visualRows(value, maxWidth)
+  // find row containing caretIndex (same loop as InputBar)
+  // col = displayWidth(row.text slice to offset)
+  // next = rowIndex + direction; if out of range return caretIndex
+  // walk next row by charWidth until col is reached
+}
+```
+
+`scanHomeEndKeys` 模仿 `scanDeleteKeys`：匹配 `\x1b\[(?:[HF]|1~|4~|7~|8~)`，拆分跨 chunk。**不要**把 CSI `3~`（Delete）当成 End。
+
+- [ ] **Step 2: FAIL**
+
+- [ ] **Step 3: 实现**
+
+- [ ] **Step 4: PASS** — `bun test tests/caret-pos.test.ts`
+
+- [ ] **Step 5: 提交** `feat: 输入框折行上下移动与 Home/End 解析`
+
+---
+
+## Task 5: 复制去前缀 + 选词
+
+**Files:**
+- Modify: `src/tui/selection.ts`
+- Modify: `tests/selection.test.ts`
+
+- [ ] **Step 1: 追加测试**
+
+```ts
+import { stripCopyDecorations, wordRangeAt, type CopyKind } from "../src/tui/selection.js"
+
+test("stripCopyDecorations drops user and tool prefixes", () => {
+  expect(stripCopyDecorations("> hello", "user-head")).toBe("hello")
+  expect(stripCopyDecorations("⚡ bash ▸ ls", "tool-head")).toBe("ls")
+  expect(stripCopyDecorations("⚡ bash ▾ ls", "tool-head")).toBe("ls")
+  expect(stripCopyDecorations("  output", "tool-body")).toBe("output")
+  expect(stripCopyDecorations("plain", "plain")).toBe("plain")
+  expect(stripCopyDecorations("hello", "user-head")).toBe("hello") // no prefix: unchanged
+})
+
+test("wordRangeAt selects the whitespace-delimited word", () => {
+  // "hello world"  — click col 1 (e) → hello [0,5)
+  expect(wordRangeAt("hello world", 1)).toEqual({ start: 0, end: 5 })
+  expect(wordRangeAt("hello world", 6)).toEqual({ start: 6, end: 11 })
+  expect(wordRangeAt("  hi", 0)).toEqual({ start: 0, end: 0 }) // whitespace: empty
+  expect(wordRangeAt("你好 ab", 1)).toEqual({ start: 0, end: 2 }) // 你 is width 2, col 1 still in 你
+})
+```
+
+`wordRangeAt(line, col)`：`line` 已是剥 ANSI 的显示串；`col` 为显示列。找到包含该列的字符，向两侧扩到空白。落在空白上返回 `{start: col, end: col}`（空选，调用方不当成词）。CJK 按空白切，`你好` 中间无空白则整段一起选。
+
+`stripCopyDecorations`：
+
+- `user-head`：`startsWith("> ")` 则 slice(2)
+- `tool-head`：`/^(⚡ .*?[▸▾] )/` 替换为空
+- `tool-body`：`startsWith("  ")` 则 slice(2)
+- `plain`：原样
+
+- [ ] **Step 2–4: FAIL / 实现 / PASS**
+
+- [ ] **Step 5: 提交** `feat: 复制去装饰前缀与按词取选区`
+
+---
+
+## Task 6: 双击计数纯函数
+
+**Files:**
+- Create: `src/tui/click-count.ts`
+- Test: `tests/click-count.test.ts`
+
+- [ ] **Step 1: 测试**
+
+```ts
+import { expect, test } from "bun:test"
+import { createClickCounter, noteClick } from "../src/tui/click-count.js"
+
+test("first click is count 1", () => {
+  const c = createClickCounter()
+  expect(noteClick(c, { row: 1, col: 3, at: 1000 })).toBe(1)
+})
+
+test("second click within 400ms and 2 cols is a double", () => {
+  const c = createClickCounter()
+  noteClick(c, { row: 1, col: 3, at: 1000 })
+  expect(noteClick(c, { row: 1, col: 4, at: 1300 })).toBe(2)
+})
+
+test("triple click", () => {
+  const c = createClickCounter()
+  noteClick(c, { row: 2, col: 5, at: 0 })
+  noteClick(c, { row: 2, col: 5, at: 100 })
+  expect(noteClick(c, { row: 2, col: 6, at: 200 })).toBe(3)
+})
+
+test("expired or far click resets to 1", () => {
+  const c = createClickCounter()
+  noteClick(c, { row: 1, col: 3, at: 0 })
+  expect(noteClick(c, { row: 1, col: 3, at: 401 })).toBe(1)
+  expect(noteClick(c, { row: 2, col: 3, at: 450 })).toBe(1)
+  noteClick(c, { row: 2, col: 3, at: 500 })
+  expect(noteClick(c, { row: 2, col: 10, at: 600 })).toBe(1)
+})
+```
+
+```ts
+export const DOUBLE_CLICK_MS = 400
+export const DOUBLE_CLICK_COL_SLOP = 2
+
+export interface ClickCounter {
+  row: number
+  col: number
+  at: number
+  count: number
+}
+
+export function createClickCounter(): ClickCounter {
+  return { row: -1, col: -1, at: -Infinity, count: 0 }
+}
+
+export function noteClick(c: ClickCounter, ev: { row: number; col: number; at: number }): number {
+  const same = ev.row === c.row && Math.abs(ev.col - c.col) <= DOUBLE_CLICK_COL_SLOP && ev.at - c.at <= DOUBLE_CLICK_MS
+  c.count = same ? c.count + 1 : 1
+  c.row = ev.row
+  c.col = ev.col
+  c.at = ev.at
+  return c.count
+}
+```
+
+- [ ] **Step 2–5: FAIL / 实现 / PASS / 提交** `feat: 双击三击计数`
+
+---
+
+## Task 7: runner getter + `/reload` + `--resume` 画出历史
+
+**Files:**
+- Modify: `src/tui/agent-runner.ts`
+- Modify: `src/tui-chat.ts`
+- Modify: `src/tui/slash-handler.ts`
+- Modify: `src/tui/slash-commands.ts`
+
+- [ ] **Step 1: 无单独失败测试**（Ink）。`npx tsc --noEmit` 必须过。
+
+- [ ] **Step 2: 实现**
+
+`AgentRunnerDeps`：删除 `codeSystemPrompt: string`，改为 `getSystemPrompt: () => string`。`runOnceWithSystem(..., deps.getSystemPrompt(), ...)`。
+
+`tui-chat.ts`：
+
+```ts
+let systemPrompt = buildCodeSystemPrompt(project, instructions)
+// ...
+createAgentRunner({ ..., getSystemPrompt: () => systemPrompt })
+```
+
+`tui.start()` 之后、首条 prompt 之前：
+
+```ts
+if (messages.length > 0) {
+  const { hydrateMessages } = await import("./tui/hydrate.js")
+  tui.update({ messages: hydrateMessages(messages) })
+}
+```
+
+`SlashState` 增加：
+
+```ts
+isRunning: () => boolean
+reloadSystemPrompt: () => Promise<void>
+applySession: (id: string) => void
+openSessionPicker: () => void
+```
+
+（`applySession` / picker 本 task 可先留空实现或先只接 reload；若 typecheck 需要完整字段，本 task 就把 `applySession` 做成「仅 sysMsg 未实现」**禁止**——必须本 task 把 reload 做完，session 命令放到 Task 8，因此 **本 task 不要改 SlashState 的 session 字段**，只加 `reloadSystemPrompt`。）
+
+`case "reload"`：`await state.reloadSystemPrompt()`。
+
+`tui-chat` 传入：
+
+```ts
+reloadSystemPrompt: async () => {
+  const { loadInstructions } = await import("./instructions.js")
+  const next = await loadInstructions()
+  systemPrompt = buildCodeSystemPrompt(scanProject(), next)
+  sysMsg(tui, `✓ 已重载规则（${next.length} 字符）`)
+}
+```
+
+`SLASH_COMMANDS` 加 `{ name: "reload", description: "重新加载规则" }`。`/help` 加 `/reload`。
+
+- [ ] **Step 3:** `npx tsc --noEmit`
+
+- [ ] **Step 4: 提交** `feat: 恢复会话画出历史并支持 /reload`
+
+---
+
+## Task 8: SessionPicker + `/sessions` `/resume`
+
+**Files:**
+- Create: `src/tui/SessionPicker.tsx`
+- Modify: `src/tui/types.ts` `src/tui/index.tsx` `src/tui/App.tsx`
+- Modify: `src/tui-chat.ts` `src/tui/slash-handler.ts` `src/tui/slash-commands.ts`
+
+- [ ] **Step 1:** 以 `ModelPicker.tsx` 为模板复制为 `SessionPicker.tsx`：
+
+- props：`currentId?: string`、`onSelect(id: string)`、`onCancel()`
+- 数据：`listSessions()`（同步，无需 loading）
+- 过滤：id 或 title 包含 query（大小写不敏感）
+- 行文案：`` `${s.id}  ${date}  ${s.title} (${s.messageCount})` ``，当前加 ` ←`
+- 标题：「选择会话」
+- 空列表：「无已保存的会话」+ Esc 关闭（`tui-chat` 在打开前若 `listSessions().length === 0` 则只 sysMsg，不 `showSessionPicker`）
+- `sessionPickerRows(terminalRows)`：与 `modelPickerRows` 同样公式
+
+`TuiState.sessionPicker?: boolean`。`TuiPrompt` 可不动（现有 modelPicker 也是独立 boolean）。
+
+`TuiCallbacks`：`onSessionPick(id: string)`、`onSessionCancel()`。`TuiRenderer` 构造函数 / `update` / `start` 的 `<App>` 透传。`showSessionPicker` / `hideSessionPicker`。
+
+`App` footer：`sessionPicker` 与 `modelPicker` 同级互斥（先 confirm/question，再 model，再 session，再 input）。`footerRows` 在 sessionPicker 时用 `sessionPickerRows`。消息区：session picker 打开时 **不要**像 model picker 那样藏掉消息区（spec：只替换输入框）。`modelPickerActive` 仍藏消息区；`sessionPickerActive` 不藏。
+
+`InputBar` `disabled`：`isRunning || selectionMode`（selectionMode 下一 task 再加，本 task 先不加）。
+
+`slash-commands.ts`：
+
+```ts
+{ name: "sessions", description: "列出/切换已保存会话", aliases: ["resume"], argHint: "[id]" },
+```
+
+不要再单独一条 `resume`（alias 即可）。`filterSlashCommands` 已支持 aliases。
+
+`tui-chat` `registerSkillCompletion` 旁注册：
+
+```ts
+setSlashArgProvider("sessions", () => listSessions().map((s) => ({ value: s.id, description: s.title })))
+setSlashArgProvider("resume", ...) // 若 parse 用的是 alias 名，alias 走 sessions provider：在 getSlashArgOptions 里 command 可能是 resume。给 resume 也 set 同一 provider，或在 provider map 里两个 key。
+```
+
+`handleSlashCommand`：
+
+```
+case "resume":
+case "sessions": {
+  const id = arg.trim()
+  if (!id) { state.openSessionPicker(); break }
+  state.applySession(id)
+  break
+}
+```
+
+`applySession(id)` 在 `tui-chat`：
+
+```ts
+const { prepareSwitch, switchFailMessage } = await import("./tui/session-switch.js")
+const { loadSession, saveSession, listSessions } = await import("./sessions.js")
+const { hydrateMessages, lastUserText } = await import("./tui/hydrate.js")
+const { clearStack } = await import("./tui/undo-stack.js")
+const ready = prepareSwitch({
+  running: Boolean(runner?.getController()),
+  currentId: sessionId,
+  targetId: id,
+  exists: Boolean(loadSession(id)),
+})
+if (!ready.ok) { sysMsg(tui, switchFailMessage(ready.reason)); return }
+if (messages.length > 0) sessionId = saveSession(messages, sessionId)
+const session = loadSession(id)!
+messages.length = 0
+messages.push(...session.messages)
+sessionId = id
+undoStack = clearStack(undoStack)
+tracker.resetContext()
+lastUserMessage = lastUserText(session.messages)
+tui.update({ messages: hydrateMessages(session.messages) })
+sysMsg(tui, `✓ 已切换到: ${session.meta.title}`)
+```
+
+注意：`sysMsg` 会再 `addMessage` 一条系统提示，所以 `update` 之后再 `sysMsg`，提示出现在历史之后。
+
+`onSessionPick`：`hideSessionPicker()` + `applySession(id)`。`onSessionCancel`：hide。
+
+`openSessionPicker`：若 `listSessions().length === 0` sysMsg「无已保存的会话」；否则 `tui.showSessionPicker()`。
+
+`/help` 把 `/sessions` 改成列出/切换，并写 `/resume` 为别名。
+
+- [ ] **Step 2:** `npx tsc --noEmit`
+
+- [ ] **Step 3: 提交** `feat: TUI 内切换会话`
+
+---
+
+## Task 9: InputBar 接历史、编辑键、点菜单
+
+**Files:**
+- Modify: `src/tui/InputBar.tsx`
+
+- [ ] **Step 1:** 无单元测试（几何依赖终端）。实现后 `npx tsc --noEmit`。
+
+- [ ] **Step 2: 实现**
+
+1. **历史落盘：** 初始 `createHistory()` 后 `entries: loadInputHistory()`。每次 `pushInput` 成功后 `saveInputHistory(next.entries)`。
+2. **Home/End：** `useInput` 里 `key.home` / `key.end`（若 Ink 类型有）调用 `moveToLineStart` / `moveToLineEnd`。raw stdin `scanHomeEndKeys` 与 delete 同通道，避免漏终端。
+3. **↑↓：** 菜单/参数菜单打开时逻辑不变。否则：
+
+```ts
+const maxW = inputTextWidth(columns)
+if (key.upArrow) {
+  const next = moveCaretVertical(value, caret, -1, maxW)
+  if (next !== caret) { applyEdit(() => ({ value, caretIndex: next })); return }
+  browseTo(1)
+  return
+}
+if (key.downArrow) {
+  const next = moveCaretVertical(value, caret, 1, maxW)
+  if (next !== caret) { applyEdit(() => ({ value, caretIndex: next })); return }
+  browseTo(-1)
+  return
+}
+```
+
+用 `editingRef.current` 的 value/caret，不要闭包过期 state。
+
+4. **点菜单：** 在现有 SGR press 处理里，若 `menuOpen`/`argMenuOpen`：
+
+选项行的终端行号（1-based）= `inputTopRow + rows.length + hintRows + 3 + i`  
+（+3 = margin 1 + border 1 + header 1，与 `menuRows = n + 5` 的构成一致：margin+2borders+header+footer）
+
+`argMenuOpen` 同样：header 一行。若点中第 i 项：命令菜单 `acceptCommand(matches[i])`，参数菜单 `acceptArg(argOptions[i])`。点在输入内容行：保持定位光标。点在菜单 chrome（边框/标题）忽略。
+
+`acceptCommand` / `acceptArg` 必须稳定（ref），因为 raw listener 订阅一次。
+
+- [ ] **Step 3:** `npx tsc --noEmit`
+
+- [ ] **Step 4: 提交** `feat: 输入历史持久化与编辑键、点击菜单`
+
+---
+
+## Task 10: MessageList 复制去前缀、双击三击、Ctrl+B
+
+**Files:**
+- Modify: `src/tui/MessageList.tsx` `src/tui/types.ts` `src/tui/App.tsx` `src/tui/index.tsx` `src/tui/StatusBar.tsx` `src/tui/InputBar.tsx`
+
+- [ ] **Step 1:** 纯函数已在 Task 5–6。本 task 接线。
+
+- [ ] **Step 2: 去前缀复制**
+
+构建 `areaRows` 时同时构建平行数组 `areaKinds: CopyKind[]`（与 `rows` 对齐，null 行用 `"plain"`）。根据 `messageLines` 的 role：user 第一条 `"user-head"` 其余 `"plain"`；tool 第一条 `"tool-head"`，展开后续 `"tool-body"`；其它 `"plain"`。
+
+`finalizeCopy` 对每一段 `extractText` 后再 `stripCopyDecorations(text, kind)`。空文本：`onCopyNotice("未选中文本")`（现状）。`writeClipboard` false：`onCopyNotice("复制失败")`（现状；spec：失败不要「已复制」——现状文案已是「复制失败」，保留）。
+
+抽出 `textFromSelection(rows, kinds, sel) => string` 便于选择模式复用。
+
+- [ ] **Step 3: 双击 / 三击**
+
+`noteClick` 在 `outcome.type === "click"` 时调用（`at: Date.now()`，row/col 用事件）。
+
+- count 1：现有 `handleClick(row)`（工具展开）
+- count 2：对该 `areaRows[rowIndex]` 剥 ANSI，`wordRangeAt`；设 `selection` 为该行该列范围（终端坐标）；立刻 `finalizeCopy`
+- count 3：找到该 row 所属 message 的 visible 行起止，设 selection 为整段，`finalizeCopy`
+
+需要 `area` 映射 row → message index。可在现有 `buildArea`/`slice` 里带上。三击选「当前可见的全部行」= 该消息在 `areaRows` 里非 null 的连续行。
+
+- [ ] **Step 4: Ctrl+B 选择模式**
+
+`TuiState.selectionMode?: boolean`。`TuiRenderer.setSelectionMode(on: boolean)`。
+
+`App` `useInput`：
+
+```ts
+if (key.ctrl && input === "b") {
+  if (confirm || question || modelPicker || sessionPicker) return
+  if (initialState.isRunning) return
+  onToggleSelectionMode()
+  return
+}
+```
+
+新增 callback `onToggleSelectionMode`：`tui.setSelectionMode(!state.selectionMode)`。进入时 MessageList 需要起点：用 ref 记下上次 click 的 cell；没有则第一条非空 `areaRows` 的 `{row: index+1, col: 2}`（paddingLeft 后第一字符，与现有 toCell 一致）。
+
+`MessageList` props：`selectionMode: boolean`、`onExitSelectionMode(copy: boolean)`。
+
+当 `selectionMode`：
+
+- `InputBar` `disabled={isRunning || selectionMode}`，placeholder 可仍「输入消息」
+- `useInput` 在 MessageList：**不要**一按键就 `clearDrag`+清 selection（现状会清掉选区）。`selectionMode` 为真时跳过这段 clear。
+- 方向键：只改 `selection.cur`（若 selection 为 null 则用起点作为 anchor 和 cur）
+- Home/End：cur.col 到 1 或行宽
+- Enter：`finalizeCopy` + `onExitSelectionMode` 但 **保留** selection 高亮（spec：与拖拽相同，保持到下次点击）——即 `setSelectionMode(false)` 不清 selection
+- Esc：`setSelection(null)` + 退出模式，不复制
+- 滚轮：现状清 selection；spec：选择模式保持、夹紧 cur。滚动处理里若 `selectionMode` 则不要 `setSelection(null)`，只更新 window 并把 cur.row clamp 到可见区
+
+StatusBar：`selectionMode` 且无 `copyNotice` 时，分隔线右侧（或取代 notice）显示 `选择模式  ↑↓←→扩选  Enter复制  Esc退出`。过长则 `truncate-end`。
+
+Ctrl+C：`onExit` 现有逻辑；`setSelectionMode(false)` 在 `requestExit` 里做。
+
+InputBar 里 `if (key.ctrl || key.meta) return` 会吞掉 Ctrl+B。App 的 `useInput` 与 InputBar 都会收到。Ink 里后挂载的子组件可能先处理。为避免 InputBar 抢：在 InputBar **最前面** `if (key.ctrl && input === "b") return` 让事件继续？Ink 不冒泡。必须在 **App 和 InputBar 都处理**：InputBar 若 disabled（selectionMode）则 `useInput` 可设 `{ isActive: !disabled }`。进入选择模式后 InputBar disabled，App 处理方向键……但方向键在 MessageList。
+
+进入前 Ctrl+B：InputBar 未 disabled。在 InputBar `useInput` 开头：
+
+```ts
+if (key.ctrl && input === "b") {
+  onSelectionMode?.()
+  return
+}
+```
+
+`onSelectionMode` 从 App 传入，调用 `onToggleSelectionMode`。这样不依赖 App 抢先。
+
+- [ ] **Step 5:** `npx tsc --noEmit` 且 `bun test tests/selection.test.ts tests/click-count.test.ts`
+
+- [ ] **Step 6: 提交** `feat: 消息区双击三击、去前缀复制与键盘选择`
+
+---
+
+## Task 11: 子 agent 工具行
+
+**Files:**
+- Modify: `src/tools/task.ts`
+- Modify: `src/tui/types.ts` `src/tui/index.tsx` `src/tui/MessageList.tsx` `src/tui/agent-runner.ts`
+- Test: `tests/task-subagent.test.ts`（回调是否在有 sink 时不写 stderr —— 可抽 `shouldLogSubAgent(sink)` 过重；改为测 `format` 不强制。最小：给 `runSubAgent` 导出测试用的「记录 tool-call 到数组」若难测 streamText 则只测类型与 `appendToolChild` 纯合并：
+
+```ts
+export function appendChild(
+  children: NonNullable<TuiMessage["toolChildren"]>,
+  child: NonNullable<TuiMessage["toolChildren"]>[number],
+  replaceLastSameName = false,
+): ...
+```
+
+不必过度设计。实现回调 + UI；用 bun test 测一个纯 `mergeToolChild(messages, toolCallId, child)`。）
+
+- [ ] **Step 1: `mergeToolChild` 测试**
+
+```ts
+test("mergeToolChild appends to the matching tool row", () => {
+  const msgs: TuiMessage[] = [
+    { id: "tool-abc", role: "tool", content: "task", toolName: "task", toolCallId: "abc", timestamp: 0 },
+  ]
+  const out = mergeToolChild(msgs, "abc", { name: "grep", summary: "foo" })
+  expect(out[0]!.toolChildren).toEqual([{ name: "grep", summary: "foo" }])
+})
+```
+
+放 `src/tui/tool-children.ts`。
+
+- [ ] **Step 2: `task.ts`**
+
+`createTaskTool(..., onUsage?, hooks?: { onSubToolCall, onSubToolResult })`。`runSubAgent` 在 `tool-call` / `tool-result` 事件调 hooks；`if (!hooks)` 才 `console.error` 现有进度。
+
+`execute` 第二参取 `toolCallId`（AI SDK `ToolExecutionOptions`）。agent-runner 不能直接传 per-call hooks 进 `createTools`。用模块级 sink：
+
+```ts
+let subSink: { parentId: string; onCall: ...; onResult: ... } | null = null
+export function setSubAgentSink(sink: typeof subSink) { subSink = sink }
+```
+
+**更干净、符合增量：** 在 `RunOptions` 加可选 `onSubAgent?: { onToolCall, onToolResult }` 太宽。采用与 `setTuiConfirm` 相同的：
+
+```ts
+// task.ts
+type SubListener = (event: { parentToolCallId?: string; name: string; input?: unknown; output?: unknown; isError?: boolean; phase: "call" | "result" }) => void
+let listener: SubListener | null = null
+export function setSubAgentListener(fn: SubListener | null) { listener = fn }
+```
+
+`execute(args, options)` 里 `const parentId = options?.toolCallId`。事件带 `parentToolCallId`。
+
+agent-runner `run()` 开始：`setSubAgentListener((ev) => { if (ev.phase === "call") tui.appendToolChild(...) })`；`finally` 里 `setSubAgentListener(null)`。
+
+`TuiRenderer.appendToolChild(parentToolCallId, child)`：`this.state.messages = mergeToolChild(...)` 然后 rerender。
+
+- [ ] **Step 3: MessageList `messageLines` tool 展开**
+
+若 `msg.toolChildren?.length`：展开时在 call 行之后、result 之前插入：
+
+```
+  ↳ grep foo
+    result preview
+```
+
+用 `wrapByWidth`。未展开不展示 children。`rowCounts` 自动随 `messageLines` 变。
+
+- [ ] **Step 4:** `npx tsc --noEmit`；`bun test tests/tool-children.test.ts`（或 hydrate 旁）
+
+- [ ] **Step 5: 提交** `feat: 子任务工具行展开显示内部调用`
+
+---
+
+## Task 12: 文档
+
+**Files:**
+- Modify: `packages/min-agent/README.md`
+- Modify: `src/tui/slash-handler.ts` `/help`（若 Task 7–8 已改则补快捷键）
+- Modify: `packages/min-agent/AGENTS.md`
+
+- [ ] **Step 1:**
+
+README 交互命令表：
+
+- `/sessions [id]` 列出或切换会话
+- `/resume [id]` 同 `/sessions`
+- `/reload` 重新加载规则
+
+快捷键段（Ctrl+C 旁）：
+
+- **Ctrl+B** 消息区选择模式（方向键扩选，Enter 复制，Esc 退出）
+- **Home / End** 行首 / 行尾
+- **鼠标** 双击选词、三击选段；拖拽选择松手复制（复制时不含 `>` / 工具前缀）
+
+Configuration 区补一行：输入历史 `~/.min-agent/input-history.json`。
+
+AGENTS.md 配置列表加：`~/.min-agent/input-history.json` 全局输入历史（上限 1000）。
+
+用户可见文案不要写 TUI、hydrate、Ink。
+
+- [ ] **Step 2: 全量**
+
+Run: `npx tsc --noEmit` 且 `bun test`（`packages/min-agent`）且仓库根 `bun run typecheck`
+
+Expected: PASS
+
+- [ ] **Step 3: 提交** `docs: 会话切换、选择模式与输入历史说明`
+
+---
+
+## 实现注意事项
+
+- 不要 import `cli.ts` 做测试。
+- `messages` 必须就地 splice/push，不能换新数组引用（runner 闭包持有原数组）。
+- `hydrate` 之后 `sysMsg` 会再插一条，不要把系统提示写进 hydrate。
+- `--resume` 画历史发生在 `tui.start()` 之后，否则 `update` 没有 inkInstance。
+- InputBar 与 MessageList 都开了 SGR；选择模式不要重复 enable/disable 鼠标。
+- `task` 的 sink 必须在 `run()` finally 清掉，避免 exec 路径吃到 TUI listener。
+- 用户可见字符串用中文，与现有 `/help` 一致。
+
+---
+
+## 自检
+
+- 每项有 FAIL 测试或明确「无单测、靠 tsc」
+- 任务按依赖排序：纯函数 → runner/reload/hydrate 启动 → picker → InputBar → MessageList → task → docs
+- 未包含第 2–5 批范围