agentflowctl 0.2.0 → 0.4.0

package/README.md

@@ -10,15 +10,33 @@
 
 ## 快速開始
 
-需要 Node.js 22 以上與 git。不需要全域安裝，直接用 `npx` 執行。先讓各家 CLI 完成訂閱登入，再檢查環境：
+需要 Node.js 22 以上與 git。不需要全域安裝，直接用 `npx` 執行。先讓各家 CLI 完成登入：
 
 ```bash
 claude    # 完成登入
 codex     # 完成登入
+```
+
+沒有內建的 agent，只會使用 `flow.config.json` 的 `agents` 裡設定的。用 `agent setup` 互動設定：它會偵測本機的 `claude`、`codex`、`gemini`，逐一詢問要不要加入、名稱與 model，再設定輪替順序；確認後才一次寫入，最後自動跑一次 `doctor`：
+
+```bash
+npx agentflowctl agent setup
+```
+
+也可以不經互動，直接用指令新增：
+
+```bash
+npx agentflowctl agent add claude --adapter claude
+npx agentflowctl agent add codex --adapter codex
+```
+
+之後改了設定或換了環境，用 `doctor` 檢查。它會列出設定的 agent 的 CLI 是否已安裝，並印出即將使用的輪替順序。沒有設定 `cycle` 時，依 `agents` 的順序取已安裝的；一個都沒偵測到就無法執行。
+
+```bash
 npx agentflowctl doctor
 ```
 
-`doctor` 會列出已安裝的 CLI，並印出即將使用的輪替順序。沒有 `flow.config.json` 時，會自動採用偵測到的 CLI。
+從舊版升級：以前沒寫 `agents` 時會自動使用內建的 claude、codex、gemini，現在不會了，要先用 `agent setup` 或 `agent add` 補上。舊設定裡的 `removedAgents` 已不再使用，可以刪掉。
 
 在專案資料夾內開始一次 run：
 
@@ -81,10 +99,13 @@ agentflowctl run --req "..." --manual-plan   # 計畫通過 AI 審查後，仍
 agentflowctl approve f-xxxx        # 搭配 --manual-plan
 agentflowctl status f-xxxx         # 階段、任務進度、各 agent 用量、代打紀錄
 agentflowctl list
-agentflowctl logs f-xxxx --latest
+agentflowctl logs f-xxxx           # 列出每一份 log 的編號、結果、階段、步驟、agent
+agentflowctl logs f-xxxx 7         # 解析第 7 份 log，最後附上錯誤整理（--latest 看最新一份）
+agentflowctl logs f-xxxx 7 --raw   # 原始內容（agent 的 JSON 行）
 agentflowctl resume f-xxxx         # 從暫停、Ctrl-C 或失敗處接續
 agentflowctl cancel f-xxxx
 agentflowctl clean f-xxxx          # 移除 worktree 與 run 紀錄，分支保留
+agentflowctl clean --all           # 清掉所有已結束的 run 與中斷留下的 worktree
 ```
 
 | 選項 | 作用 |
@@ -94,12 +115,110 @@ agentflowctl clean f-xxxx          # 移除 worktree 與 run 紀錄，分支保
 | `--cycle` | 這次 run 的輪替順序，例如 `claude,codex,gemini`；建立後就固定，`resume` 沿用 |
 | `--max-agent-runs` | 這次 run 的 agent 執行次數上限 |
 | `--manual-plan` | 計畫通過審查後進入 `awaiting_approval`，等 `approve` 才開始實作 |
+| `-v` / `--verbose` | 執行時印出 agent 的文字、工具呼叫與專案指令；`run`、`resume`、`approve` 都適用，也可設 `AGENTFLOWCTL_VERBOSE=1` |
 
 `status` 會列出任務。進行中的任務會標出正在寫測試還是正在寫實作。
 
+### 清除 worktree
+
+`run` 建好 worktree 就會寫入 run 紀錄，所以不論在哪一步中斷（包括安裝相依套件時），都能用 `resume` 接續，或用 `clean` 清掉。
+
+- `clean <id>`：移除該 run 的 worktree 與 `.agentflowctl/runs/<id>/`，並清掉 git 裡已失效的 worktree 登記。沒有 run 紀錄的 worktree 也能清，worktree 資料夾被手動刪掉時也一樣。
+- `clean --all`：清掉所有 `done`、`failed` 的 run，以及沒有 run 紀錄的 worktree。進行中、`paused`、`awaiting_approval` 的不動；Ctrl-C 中斷、之後不打算接續的 run，先 `cancel` 再 `clean --all`，或直接 `clean <id>`。
+
+兩者都保留 `flow/<id>` 分支，不需要時用 `git branch -D` 刪除。
+
+### 執行中的終端機輸出
+
+預設是安靜模式，只印出 `[run-id]` 開頭的階段進度（📝 🧐 ✓ ✗ ⚠️ 等）。agent 執行失敗、測試或檢查沒過時，會附上對應 log 的查看指令：
+
+```
+[f-xxxx] 🔍 執行驗證
+[f-xxxx]    ✓ typecheck
+[f-xxxx]    ✗ lint（agentflowctl logs f-xxxx 15）
+    ✗ codex 執行失敗（結束碼 1），可用 agentflowctl logs f-xxxx 16 查看
+```
+
+加上 `-v` 會另外印出 agent 每一段文字的第一行、每次工具呼叫的完整指令或主要參數（不截斷，多行指令的後續行縮排對齊），以及 install、測試、verify 這些以 `$ ` 開頭的專案指令：
+
+```
+    💬 [claude] 先讀現有的表單元件
+    🔧 [claude] Read: /repo/.agentflowctl/worktrees/f-xxxx/src/LoginForm.tsx
+    🔧 [claude] Bash: pnpm vitest run src/LoginForm.test.tsx
+    🔧 [codex] shell: bash -lc 'pnpm test'
+    🔧 [gemini] run_shell_command: npm run lint
+    $ pnpm install
+```
+
+工具參數依序取 command、檔案路徑、path、pattern、url、query，都沒有時印出整包 JSON。
+
+### Log
+
+每次執行 agent 或專案指令都會留一份 log，放在 `.agentflowctl/runs/<id>/logs/`，檔名是「序號-階段-步驟-agent」，專案指令的 agent 欄位是 `cmd`：
+
+```
+001-setup-install-cmd.log
+002-spec-spec-claude.log
+007-implement-T1-tests-codex.log
+008-implement-T1-red-cmd.log
+015-verify-lint-cmd.log
+```
+
+檔案保留 agent 的原始輸出，也就是各家 CLI 的 JSON 行。第一行 `# agentflowctl {...}` 記錄階段、步驟、agent 與開始時間；stderr 接在 `[stderr]` 之後；最後一行 `# exit {...}` 記錄結束碼與是否成功，沒有這行就代表還在執行或被中斷。
+
+`agentflowctl logs <id>` 列出所有 log。結果欄的 ✓ 是成功，✗ 是失敗，… 代表沒有結束紀錄：
+
+```
+  #  結果  階段          步驟                 agent       開始時間
+  1  ✓     setup         install              cmd         2026-09-26 11:29:04
+  2  ✓     spec          spec                 claude      2026-09-26 11:29:05
+  3  ✗     plan          plan                 codex       2026-09-26 11:31:40
+```
+
+`agentflowctl logs <id> <編號>` 會把原始 JSON 解析成易讀的格式：
+
+| 標記 | 內容 |
+|---|---|
+| 💬 | agent 的完整文字，不截斷 |
+| 🔧 | 工具呼叫與完整參數 |
+| 📊 | token 用量 |
+| 🏁 | 最後結果 |
+| ⚠️ | 工具回報的錯誤。agent 通常會自己換方法繼續，所以不列進錯誤整理 |
+| ❌ | adapter 不認得的錯誤事件 |
+| 📄 | 不是 JSON 的輸出行 |
+
+adapter 不認得、也看不出錯誤跡象的 JSON 行不會顯示，只列出行數，要看全部請加 `--raw`。專案指令的 log 本來就是純文字，會原樣顯示。
+
+最後一段「錯誤」整理出結束碼、agent 回報的失敗、錯誤事件與 stderr：
+
+```
+#3  plan / plan / codex
+開始 2026-09-26 11:31:40　結束 2026-09-26 11:31:52　結束碼 1　✗ 失敗
+檔案 /repo/.agentflowctl/runs/f-xxxx/logs/003-plan-plan-codex.log
+
+💬 先讀 spec.md 與 acceptance.json
+🔧 shell: bash -lc 'cat .flow/spec.md'
+🏁 失敗：stream disconnected before completion
+
+── 錯誤 ──
+結束碼 1
+agent 回報失敗：stream disconnected before completion
+stderr：
+   Error: stream disconnected before completion
+```
+
+執行成功時，stderr 會放在「其他輸出」段落，不算錯誤。
+
+### 出錯時怎麼查
+
+1. run 停下時印出的摘要，或 `agentflowctl status <id>`，會列出失敗的階段、原因、最後一份 log，以及最近失敗的那一份。
+2. `agentflowctl logs <id> <編號>` 看那份 log 的錯誤段落。
+3. 解析結果看不出原因時，加 `--raw` 看原始輸出。
+4. 必要時直接在 worktree（`.agentflowctl/worktrees/<id>`）裡修正，再執行 `agentflowctl resume <id>`。
+
 ## 設定
 
-專案根目錄的 `flow.config.json`。完整範例見 `examples/flow.config.json`。未提供的欄位使用內建預設（安裝指令、測試指令、檢查清單預設對應 Vite + TypeScript + Vitest）。
+專案根目錄的 `flow.config.json`。完整範例見 `examples/flow.config.json`。未提供的欄位使用內建預設；`install`、`test`、`checks` 沒寫時，會依專案現況偵測（見下方「專案指令的偵測」）。
 
 ```json
 {
@@ -108,6 +227,7 @@ agentflowctl clean f-xxxx          # 移除 worktree 與 run 紀錄，分支保
   "tddSplit": true,
   "tieBreak": "proceed",
   "agents": {
+    "claude": { "adapter": "claude" },
     "codex": { "adapter": "codex", "model": "你要用的模型" },
     "aider": { "adapter": "command", "command": ["aider", "--yes-always", "--no-auto-commits", "--message", "{prompt}"] }
   }
@@ -116,7 +236,7 @@ agentflowctl clean f-xxxx          # 移除 worktree 與 run 紀錄，分支保
 
 | 設定 | 預設 | 說明 |
 |---|---|---|
-| `cycle` | 自動偵測 | 輪替順序。同一家 CLI 可以登記成不同 agent，例如 `claude-fast` 與 `claude-strong` |
+| `cycle` | 自動偵測 | 輪替順序。未設定時依 `agents` 的順序取已安裝的 CLI。同一家 CLI 可以登記成不同 agent，例如 `claude-fast` 與 `claude-strong` |
 | `fixStrategy` | `ring` | `ring`：審查意見交給審查者的下一位；`author`：交回最後作者 |
 | `tddSplit` | `true` | 測試與實作是否分開 |
 | `reviewQuorum` | `1` | 程式碼需要幾位不同審查者都 `approve` |
@@ -124,17 +244,35 @@ agentflowctl clean f-xxxx          # 移除 worktree 與 run 紀錄，分支保
 | `planArbiter` | `true` | 計畫審查僵持時交付仲裁。關掉之後，僵持會直接讓 run 失敗 |
 | `tieBreak` | `proceed` | 兩家仲裁意見分歧時：`proceed` 繼續並記錄爭議；`stop` 停下 |
 | `maxAgentRuns` | `60` | 單一 run 最多執行幾次 agent |
-| `install` / `test` / `checks` | 見 `src/schemas.ts` | verify 階段實際執行的指令 |
-| `agents` | 內建 claude、codex、gemini | 覆寫內建 agent，或用 `command` adapter 接上其他 CLI |
+| `install` / `test` / `checks` | 依專案偵測 | 安裝、測試與 verify 階段實際執行的指令 |
+| `agents` | `{}` | 可用的 agent，沒有內建的。每個都要指定 adapter（`claude`、`codex`、`gemini`，或用 `command` 接上其他 CLI） |
 
 verify 失敗（型別、lint、建置）一律交回最後作者。審查意見才依 `fixStrategy` 決定修正者。
 
+### 專案指令的偵測
+
+`install`、`test`、`checks` 沒寫在 `flow.config.json` 時，每次讀設定都會依專案現況推出指令，不寫檔。有寫的欄位一律照你的設定。
+
+- 套件管理器：先看 `package.json` 的 `packageManager`，再看 lockfile（`pnpm-lock.yaml`、`yarn.lock`、`bun.lock`／`bun.lockb`、`package-lock.json`），都沒有就用 npm。
+- `install`：`pnpm install`、`yarn install`、`bun install` 或 `npm install --no-audit --no-fund`。不鎖 lockfile，因為實作時 agent 可能新增依賴。
+- `checks`：typecheck、lint、test、build 四項。`package.json` 有對應的 script（`typecheck`／`type-check`、`lint`、`test`、`build`）就用 `<pm> run <script>`，否則用 `tsc --noEmit`、`eslint .`、`vitest run`、`vite build`，前面加上 `npx`、`pnpm exec`、`yarn` 或 `bunx`。
+- `test`：`vitest run`，前綴同上。
+
+`run` 建立 worktree 後會印出這次偵測到的指令：
+
+```
+[f-xxxx] 🔧 依專案偵測指令：pnpm（依 package.json 的 packageManager）
+[f-xxxx]    install：pnpm install
+[f-xxxx]    checks.typecheck：pnpm run type-check
+```
+
 ### 用指令管理 agent
 
 `agents` 與 `cycle` 也可以用 `agent` 指令修改，不必手動編輯 JSON。每次寫入前都會先驗證整份設定：
 
 ```bash
-agentflowctl agent list                                   # 內建與自訂 agent、是否已安裝、輪替位置
+agentflowctl agent setup                                  # 互動設定 claude、codex、gemini 與輪替順序
+agentflowctl agent list                                   # 設定的 agent、是否已安裝、輪替位置
 agentflowctl agent add claude-strong --adapter claude --model opus
 agentflowctl agent add aider --adapter command -- aider --yes-always --message {prompt}
 agentflowctl agent set codex --model 你要用的模型 --extra-arg=--search
@@ -146,8 +284,9 @@ agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯
 修改會連帶更新相關設定，並在終端機列出：
 
 - `set --adapter` 換 adapter 時，會清掉舊 adapter 的 `model`、`extraArgs`、`command`，這次有重新指定的除外。
-- `remove` 刪除自訂 agent 時，會一併從 `cycle` 移除。`cycle` 變空就刪除這個欄位，改回自動偵測。對內建 agent 用 `remove`，只會刪掉覆寫設定。
+- `remove` 會一併從 `cycle` 移除。`cycle` 變空就刪除這個欄位，改回從 `agents` 自動偵測。
 - `--extra-arg` 可以重複指定，會整個取代原本的 `extraArgs`。參數以 `-` 開頭時，寫成 `--extra-arg=--sandbox`。
+- `setup` 遇到已存在的名稱會先問要不要覆寫；不覆寫時保留原設定，但仍放進這次的輪替順序。在非互動式環境（CI、管線）裡請改用 `agent add`。`command` adapter 要自己寫指令，不在 `setup` 裡。
 
 已建立的 run 會沿用建立時的輪替順序，不受這些修改影響。
 
@@ -204,7 +343,7 @@ Agent 的最後回覆要附上 XML 中繼資料：
 </result>
 ```
 
-`blocked` 與 `concerns` 會印在終端機上，完整回覆留在 log。這份中繼資料只給人看；缺少或格式錯誤都不影響流程，是否通過仍由上表的程式檢查決定。
+`blocked` 與 `concerns` 會印在終端機上，完整回覆留在 log，可用 `agentflowctl logs` 查看。這份中繼資料只給人看；缺少或格式錯誤都不影響流程，是否通過仍由上表的程式檢查決定。
 
 ## Adapter
 
@@ -219,11 +358,7 @@ Codex 沙箱預設不能連網，所以建立 worktree 時會先跑 `install`。
 
 各家讀的專案說明檔不同：Claude Code 讀 `CLAUDE.md`，Codex 讀 `AGENTS.md`，Gemini 讀 `GEMINI.md`。把專案慣例寫在 `AGENTS.md`，另外兩個檔案各用一行引用它。agentflowctl 的 prompt 在 `prompts/`，不依賴任何一家的 skills 或 plugins。
 
-## 登入、額度與代打
-
-只支援各家 CLI 的訂閱登入。
-
-執行 agent 時，一律從子程序環境移除 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`CODEX_API_KEY`、`OPENAI_API_KEY`、`GEMINI_API_KEY`、`GOOGLE_API_KEY`，避免環境裡的 key 蓋過訂閱登入。`doctor` 發現這些變數時會提醒。專案指令（install、test、build）不受影響。
+## 額度與代打
 
 上限是執行次數（`maxAgentRuns`，預設 60），不是金額。`status` 會列出各 agent 的執行次數與 token 數。
 
@@ -248,7 +383,7 @@ agentflowctl 本身只依賴 Node.js 與 git。專案指令透過系統 shell
 | 環境 | 適合的用法 |
 |---|---|
 | 自己的電腦 | 自己的專案、自己寫的需求。剛開始可以加 `--manual-plan`，確認審查品質後再拿掉 |
-| 容器、遠端開發機 | 無人值守。先在該環境內完成各家 CLI 的訂閱登入 |
+| 容器、遠端開發機 | 無人值守。先在該環境內完成各家 CLI 的登入 |
 | Claude Code、Codex 裡面 | 讓它們用 shell 執行 `npx agentflowctl` |
 
 沒有容器隔離時，verify 會在你的電腦上執行 agent 寫出來的程式碼。Gemini 在無人值守時是 yolo 模式。處理外部 issue，或需求文字不是你自己寫的，放到可丟棄的環境。AI 審查計畫擋不住夾在需求裡的指示。
@@ -261,8 +396,11 @@ src/
   engine.ts         狀態機與各階段
   roles.ts          輪替規則（含計畫修正者與仲裁者）
   runner.ts         執行 agent、正規化結果、執行專案指令
+  logs.ts           log 檔名、檔頭檔尾、列表與解析
   agents/           claude、codex、gemini、command
+  setup.ts          agent setup 互動精靈
   git.ts            worktree 與 git 操作
+  cleanup.ts        clean：移除 worktree 與 run 紀錄
   store.ts          狀態、用量、代打紀錄
   tasks.ts          任務 DAG
   schemas.ts        zod schema

package/dist/agentConfig.js

@@ -1,12 +1,10 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { z } from "zod";
-import { DEFAULT_CYCLE } from "./agents/index.js";
 import { AgentDef, RepoConfig } from "./schemas.js";
 /** 這些欄位的意義取決於 adapter，換 adapter 時要清掉 */
 const ADAPTER_FIELDS = ["model", "extraArgs", "command"];
-const isBuiltin = (name) => DEFAULT_CYCLE.includes(name);
 const agentsOf = (cfg) => ({ ...(cfg.agents ?? {}) });
-const isDefined = (cfg, name) => isBuiltin(name) || name in agentsOf(cfg);
+const isDefined = (cfg, name) => name in agentsOf(cfg);
 /** 只留下有值的欄位，驗證後回傳 */
 function buildAgent(base, patch) {
     const next = { ...base };
@@ -38,8 +36,7 @@ export function setAgent(cfg, name, patch) {
         throw new Error("沒有要修改的欄位（--adapter、--model、--extra-arg 或 -- <command>）");
     }
     const agents = agentsOf(cfg);
-    // 內建 agent 第一次修改時，新增一筆覆寫設定
-    const base = { ...(agents[name] ?? { adapter: name }) };
+    const base = { ...agents[name] };
     const changes = [];
     if (patch.adapter !== undefined && patch.adapter !== base.adapter) {
         const cleared = ADAPTER_FIELDS.filter((f) => base[f] !== undefined && patch[f] === undefined);
@@ -51,16 +48,14 @@ export function setAgent(cfg, name, patch) {
     return { cfg: { ...cfg, agents: { ...agents, [name]: buildAgent(base, patch) } }, changes };
 }
 export function removeAgent(cfg, name) {
+    if (!isDefined(cfg, name))
+        throw new Error(`未定義的 agent：${name}`);
     const agents = agentsOf(cfg);
-    if (!(name in agents)) {
-        throw new Error(isBuiltin(name) ? `${name} 是內建 agent，沒有覆寫設定可以刪除` : `未定義的 agent：${name}`);
-    }
     delete agents[name];
     const next = { ...cfg, agents };
     const changes = [];
     const cycle = cfg.cycle;
-    // 自訂 agent 刪掉後就不存在了，一併從輪替順序移除；內建 agent 只是恢復預設，仍可留在輪替裡
-    if (cycle?.includes(name) && !isBuiltin(name)) {
+    if (cycle?.includes(name)) {
         const rest = cycle.filter((n) => n !== name);
         if (rest.length) {
             next.cycle = rest;
@@ -68,7 +63,7 @@ export function removeAgent(cfg, name) {
         }
         else {
             delete next.cycle;
-            changes.push("輪替順序因此變空，已刪除 cycle，改回自動偵測已安裝的 CLI");
+            changes.push("輪替順序因此變空，已刪除 cycle，改回從 agents 自動偵測已安裝的 CLI");
         }
     }
     return { cfg: next, changes };

package/dist/agents/claude.js

@@ -1,6 +1,6 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { num, str, tryJson } from "./types.js";
+import { num, str, toolDetail, tryJson } from "./types.js";
 /**
  * Claude Code 的權限設定：acceptEdits 只自動允許工作目錄內的修改，
  * 版本控制交給 agentflowctl，並啟用內建沙箱限制 shell 指令。
@@ -46,7 +46,7 @@ export const claude = {
                 if (b.type === "text" && str(b.text)?.trim())
                     out.push({ kind: "text", text: str(b.text) });
                 if (b.type === "tool_use")
-                    out.push({ kind: "tool", name: str(b.name) ?? "tool" });
+                    out.push({ kind: "tool", name: str(b.name) ?? "tool", detail: toolDetail(b.input) });
             }
         }
         else if (ev.type === "result") {

package/dist/agents/codex.js

@@ -21,9 +21,12 @@ export const codex = {
             if (item.type === "agent_message" && str(item.text)?.trim())
                 out.push({ kind: "text", text: str(item.text) });
             else if (item.type === "command_execution")
-                out.push({ kind: "tool", name: `shell: ${str(item.command) ?? ""}`.slice(0, 80) });
-            else if (item.type === "file_change")
-                out.push({ kind: "tool", name: "edit" });
+                out.push({ kind: "tool", name: "shell", detail: str(item.command) });
+            else if (item.type === "file_change") {
+                const changes = Array.isArray(item.changes) ? item.changes : [];
+                const paths = changes.map((c) => str(c.path)).filter(Boolean);
+                out.push({ kind: "tool", name: "edit", detail: paths.length ? paths.join(", ") : undefined });
+            }
         }
         else if (ev.type === "turn.completed") {
             const usage = (ev.usage ?? {});

package/dist/agents/gemini.js

@@ -1,4 +1,4 @@
-import { num, str, tryJson } from "./types.js";
+import { num, str, toolDetail, tryJson } from "./types.js";
 /**
  * Google Gemini CLI：`gemini -p ... --output-format stream-json`。
  * Gemini CLI 沒有「只允許工作目錄內的 shell 指令」這種細緻權限，
@@ -21,7 +21,7 @@ export const gemini = {
             out.push({ kind: "text", text: str(ev.content) });
         }
         else if (ev.type === "tool_use") {
-            out.push({ kind: "tool", name: str(ev.tool_name) ?? "tool" });
+            out.push({ kind: "tool", name: str(ev.tool_name) ?? "tool", detail: toolDetail(ev.parameters) });
         }
         else if (ev.type === "result") {
             const stats = (ev.stats ?? {});

package/dist/agents/index.js

@@ -3,6 +3,4 @@ import { codex } from "./codex.js";
 import { command } from "./command.js";
 import { gemini } from "./gemini.js";
 export const ADAPTERS = { claude, codex, gemini, command };
-/** 沒有設定時，依序偵測這些已安裝的 CLI 組成輪替順序 */
-export const DEFAULT_CYCLE = ["claude", "codex", "gemini"];
 //# sourceMappingURL=index.js.map

package/dist/agents/types.js

@@ -9,4 +9,18 @@ export function tryJson(line) {
 }
 export const num = (v) => (typeof v === "number" ? v : undefined);
 export const str = (v) => (typeof v === "string" ? v : undefined);
+/** 從工具參數挑出最能代表「正在做什麼」的欄位；都沒有時以 JSON 顯示全部參數 */
+export function toolDetail(input) {
+    if (!input || typeof input !== "object")
+        return undefined;
+    const o = input;
+    for (const key of ["command", "cmd", "file_path", "absolute_path", "path", "pattern", "url", "query"]) {
+        const v = o[key];
+        if (typeof v === "string" && v.trim())
+            return v;
+        if (Array.isArray(v) && v.length)
+            return v.join(" ");
+    }
+    return Object.keys(o).length ? JSON.stringify(o) : undefined;
+}
 //# sourceMappingURL=types.js.map

package/dist/cleanup.js

@@ -0,0 +1,54 @@
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { git, removeWorktree } from "./git.js";
+import { projectRoot, runDir, runsDir, worktreeDir, worktreesDir } from "./paths.js";
+import { getRun } from "./store.js";
+/**
+ * 移除一個 run 的 worktree 與紀錄，分支保留。
+ * 不需要 state.json：中斷在建立 worktree 之後、寫入紀錄之前留下的孤兒也能清。
+ * 回傳是否真的找到並移除了東西。
+ */
+export async function cleanRun(id) {
+    // id 會拼進要遞迴刪除的路徑，擋掉空字串、..、斜線
+    if (!/^[\w-]+$/.test(id))
+        throw new Error(`不合法的 run id：${id}`);
+    const root = projectRoot();
+    const wt = worktreeDir(id);
+    const found = existsSync(wt) || existsSync(runDir(id));
+    if (existsSync(wt)) {
+        // git 不認得這個資料夾時（登記已被 prune、或 worktree add 做到一半）改成直接刪
+        await removeWorktree(root, wt).catch(() => rmSync(wt, { recursive: true, force: true }));
+    }
+    rmSync(runDir(id), { recursive: true, force: true });
+    // 清掉資料夾已不存在的 worktree 登記，否則同名分支之後無法再 checkout
+    const before = await git(root, "worktree", "list", "--porcelain");
+    await git(root, "worktree", "prune");
+    const pruned = before !== (await git(root, "worktree", "list", "--porcelain"));
+    return found || pruned;
+}
+/** 已結束、可以安全清掉的階段；其他階段可能還在跑，或要 resume／approve */
+const FINISHED = ["done", "failed"];
+/**
+ * `clean --all` 要清的 run：已結束的，加上沒有 state.json 的孤兒（stage 為 undefined）。
+ * 讀不懂的 state.json 不算孤兒，保留給使用者自己判斷。
+ */
+export function cleanableRuns() {
+    const ids = new Set();
+    for (const dir of [runsDir(), worktreesDir()])
+        if (existsSync(dir))
+            for (const id of readdirSync(dir))
+                ids.add(id);
+    const out = [];
+    for (const id of [...ids].sort()) {
+        let stage;
+        try {
+            stage = getRun(id)?.stage;
+        }
+        catch {
+            continue;
+        }
+        if (stage === undefined || FINISHED.includes(stage))
+            out.push({ id, stage });
+    }
+    return out;
+}
+//# sourceMappingURL=cleanup.js.map