minimal-agent 0.6.1 → 0.6.3

package/src/context/reactiveCompact.js

@@ -3,7 +3,7 @@
  *  src/context/reactiveCompact.ts —— 反应式压缩（错误自救）
  * ------------------------------------------------------------
  *  对齐 kakadeai 主项目 services/compact/reactiveCompact.ts：
- *  当 API 返回 "prompt too long" 类错误时，自动触发一次压缩重试。
+ *  当 API 返回 "prompt too long" 类错误时，自动触发压缩重试。
  *
  *  典型场景：
  *    用户灌了一大段上下文 → 调 LLM → 返回 400 prompt_too_long
@@ -11,27 +11,39 @@
  *    → 摘要失败再用 snipCompact 砍头兜底
  *    → 把新上下文交还给调用方，调用方重试一次 chat()
  *
- *  防爆约束：
- *    每个 session 最多自救一次（attemptedThisSession 标志位）。
- *    用户 /new 重启会话后才能再次自救。这避免"压缩→还是太长→再压缩"
- *    的死循环。
+ *  防爆约束（circuit breaker）：
+ *    连续自救失败 MAX_CONSECUTIVE_REACTIVE_FAILURES 次才熔断。
+ *    任意一次自救成功（LLM 压缩或 snip 兜底）→ 计数清零，
+ *    允许后续再次触发。行为：压缩成功→继续→再溢出→再压→正常往复。
+ *    用户 /new 重启会话后 consecutiveFailures 也归零。
  * ============================================================
  */
 import { forceCompact } from './compact.js';
 import { snipCompactIfNeeded } from './snipCompact.js';
 import { countMessagesTokens } from './tokenCounter.js';
 export function createReactiveCompactState() {
-    return { attempted: false };
+    return { consecutiveFailures: 0 };
 }
+/** 连续失败几次触发熔断，拒绝继续自救 */
+export const MAX_CONSECUTIVE_REACTIVE_FAILURES = 3;
 const defaultState = createReactiveCompactState();
 /** /new 时调用，允许下一个 session 再次自救 */
 export function resetReactiveCompactState(state = defaultState) {
-    state.attempted = false;
+    state.consecutiveFailures = 0;
 }
-/** 测试 / 调试用：查询当前是否已尝试 */
+/**
+ * 测试 / 调试用：查询 circuit breaker 是否已熔断（连续失败达上限）。
+ *
+ * 原签名 hasAttemptedReactiveCompact 在新语义下映射为「电路是否已断开」：
+ * 单次成功就清零，只有连续失败 ≥ MAX_CONSECUTIVE_REACTIVE_FAILURES 才返回 true。
+ * 效果等价于原先的 attempted 旗标语义的"超集"（原先=1次，新=N次）。
+ * 别名 isReactiveCircuitOpen 供新代码使用，两者完全等价。
+ */
 export function hasAttemptedReactiveCompact(state = defaultState) {
-    return state.attempted;
+    return state.consecutiveFailures >= MAX_CONSECUTIVE_REACTIVE_FAILURES;
 }
+/** hasAttemptedReactiveCompact 的语义化别名 */
+export const isReactiveCircuitOpen = hasAttemptedReactiveCompact;
 // ==================== 错误识别 ====================
 /**
  * 判断一个错误是否是"提示词太长"类错误。
@@ -63,29 +75,37 @@ function errorMessage(error) {
     return String(error ?? '');
 }
 /**
- * 如果当前错误是 prompt_too_long 且本 session 未尝试过自救，
+ * 如果当前错误是 prompt_too_long 且 circuit breaker 未熔断，
  * 执行一次"先 LLM 压缩、失败兜底 snip"的恢复流程。
  *
+ * circuit breaker 规则：
+ *   - 任意成功（LLM 压缩 or snip 兜底）→ consecutiveFailures 清零
+ *   - 两个步骤都失败 → consecutiveFailures +1
+ *   - consecutiveFailures ≥ MAX_CONSECUTIVE_REACTIVE_FAILURES → 熔断拒绝
+ *
  * @param messages 当前历史（不修改）
  * @param provider 当前 provider（用于 LLM 压缩）
  * @param error    刚刚抛出的错误
+ * @param state    可选的独立状态（默认使用进程级单例）
  */
 export async function reactiveCompactIfApplicable(messages, provider, error, state = defaultState) {
+    // 非 prompt_too_long 错误：直接短路，不消耗计数
     if (!isPromptTooLongError(error)) {
         return { recovered: false, messages, reason: 'not a prompt-too-long error' };
     }
-    if (state.attempted) {
+    // 电路已熔断：连续失败达上限，拒绝继续
+    if (state.consecutiveFailures >= MAX_CONSECUTIVE_REACTIVE_FAILURES) {
         return {
             recovered: false,
             messages,
-            reason: 'already attempted this session — use /new or /compact manually',
+            reason: '反应式压缩已熔断（连续失败达上限）——请 /new 或手动 /compact',
         };
     }
-    // 占位：即使下面失败也算"用过一次"，防止反复触发
-    state.attempted = true;
     // Step 1: 先试 LLM 全量压缩
     try {
         const r = await forceCompact(messages, provider);
+        // 救活成功 → 清零计数，让后续继续可用
+        state.consecutiveFailures = 0;
         return {
             recovered: true,
             messages: r.messages,
@@ -94,16 +114,15 @@ export async function reactiveCompactIfApplicable(messages, provider, error, sta
             after: r.after,
         };
     }
-    catch (compactErr) {
+    catch {
         // 压缩失败 → 走 snip 兜底
     }
     // Step 2: snip 兜底（更激进 40%）
     const beforeSnip = countMessagesTokens(messages);
-    const snipped = snipCompactIfNeeded(messages, {
-        force: true,
-        snipPercent: 0.4,
-    });
+    const snipped = snipCompactIfNeeded(messages, { force: true, snipPercent: 0.4 });
     if (snipped.messagesRemoved > 0) {
+        // snip 也算救活 → 清零计数
+        state.consecutiveFailures = 0;
         const afterSnip = countMessagesTokens(snipped.messages);
         return {
             recovered: true,
@@ -113,6 +132,8 @@ export async function reactiveCompactIfApplicable(messages, provider, error, sta
             after: afterSnip,
         };
     }
+    // 两步都没救活 → 失败计数 +1
+    state.consecutiveFailures++;
     return {
         recovered: false,
         messages,

package/src/context/recentDirs.js

@@ -0,0 +1,66 @@
+/**
+ * ============================================================
+ *  src/context/recentDirs.ts —— 最近工作目录注册表（Web 侧栏用）
+ * ------------------------------------------------------------
+ *  做的事：
+ *    维护 ~/.minimal-agent/recent-dirs.json —— 一个"用过哪些工作目录"的列表。
+ *    每个工作目录 = 一个会话（项目"一 cwd 一 session"约束），Web 前端侧栏据此
+ *    列出会话；每条记录顺带存该目录的会话文件路径，让前端不必复刻哈希命名规则
+ *    即可定位历史。
+ *
+ *  谁写：stream-json 模式每轮开始时 recordRecentDir(cwd, 首条用户消息)。
+ *  谁读：webchat 服务端直接 JSON.parse 本文件（不 import 后端业务模块）。
+ *
+ *  抉择：读失败返回 []；写失败静默 —— 注册表只是 UI 便利，绝不该影响对话本身。
+ * ============================================================
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { sessionFileFor } from './sessionPath.js';
+/** 注册表上限：只留最近 N 个，防文件无限增长。 */
+const MAX_ENTRIES = 50;
+function registryPath() {
+    return join(homedir(), '.minimal-agent', 'recent-dirs.json');
+}
+/** 读注册表，按最近使用倒序；任何异常返回 []。 */
+export async function listRecentDirs() {
+    try {
+        const raw = await readFile(registryPath(), 'utf8');
+        const data = JSON.parse(raw);
+        if (!Array.isArray(data))
+            return [];
+        return data
+            .filter((e) => e && typeof e.path === 'string' && typeof e.sessionFile === 'string')
+            .sort((a, b) => b.lastUsedAt - a.lastUsedAt);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 记录/更新一个工作目录。upsert by path：已存在则更新 lastUsedAt（title 给了才覆盖，
+ * 否则保留旧 title），不存在则插入。写失败静默。
+ */
+export async function recordRecentDir(cwd, title) {
+    try {
+        const abs = resolve(cwd);
+        const list = await listRecentDirs();
+        const prev = list.find((e) => e.path === abs);
+        const rest = list.filter((e) => e.path !== abs);
+        const entry = {
+            path: abs,
+            name: basename(abs) || abs,
+            lastUsedAt: Date.now(),
+            title: title ? title.slice(0, 80) : prev?.title,
+            sessionFile: sessionFileFor(abs),
+        };
+        const next = [entry, ...rest].slice(0, MAX_ENTRIES);
+        const file = registryPath();
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(file, JSON.stringify(next, null, 2), 'utf8');
+    }
+    catch {
+        // 静默：注册失败不影响对话
+    }
+}

package/src/context/tokenCounter.js

@@ -39,6 +39,29 @@ export function countTextTokens(text) {
     }
     return Math.ceil(asciiChars / 4) + nonAsciiChars;
 }
+/**
+ * 估算「工具 schema」本身占的 token。每轮请求都会把 ALL_TOOLS 的
+ * name + description + parameters JSON 发给 LLM，但 countMessagesTokens 只数历史消息、
+ * 漏了这部分 → 系统性低估。自动压缩判定阈值时必须把它加上才准。
+ *
+ * 每个工具的 token 组成：
+ *   - 8 token 固定开销（type/function 包裹等结构体）
+ *   - name 字段的文本 token
+ *   - description 字段的文本 token（支持字符串或函数两种形式）
+ *   - parameters JSON 序列化后的文本 token
+ */
+export function estimateToolsTokens(tools) {
+    let total = 0;
+    for (const t of tools) {
+        total += 8; // 每个工具的结构固定开销（type/function 包裹）
+        total += countTextTokens(t.name);
+        // description 可以是静态字符串，也可以是注入运行时信息的函数
+        const desc = typeof t.description === 'function' ? t.description() : t.description;
+        total += countTextTokens(desc);
+        total += countTextTokens(JSON.stringify(t.parameters));
+    }
+    return total;
+}
 /** 估算整段历史的 token 数（包含 role / 工具调用结构的开销） */
 export function countMessagesTokens(messages) {
     let total = 0;

package/src/llm/client.js

@@ -59,11 +59,16 @@ export async function* chat(args) {
         return rest;
     });
     // 3. 构造请求体
+    // 逃生开关：极个别 provider 不认 stream_options 会 400，可用 MINIMAL_AGENT_DISABLE_USAGE=1 关掉。
+    const includeUsage = process.env.MINIMAL_AGENT_DISABLE_USAGE !== '1';
     const body = {
         model: provider.model,
         messages: cleanedMessages,
         tools: openaiTools.length > 0 ? openaiTools : undefined,
         stream: true,
+        // stream_options.include_usage：让 provider 在流末附带真实 prompt_tokens，
+        // 供上层自动压缩判断用；provider 不支持时 usagePromptTokens 保持 undefined，上层 fallback 本地估算。
+        ...(includeUsage ? { stream_options: { include_usage: true } } : {}),
         // tool_choice: 'auto' 是默认值，可不写；某些 provider 必须显式
         tool_choice: openaiTools.length > 0 ? 'auto' : undefined,
         // ADR-05: structured output；缺省 undefined 不出现在 body（JSON.stringify 自动剥离）
@@ -95,6 +100,8 @@ export async function* chat(args) {
     let buffer = '';
     /** 累积的 stop_reason，最后 yield done 时用 */
     let stopReason = 'unknown';
+    /** 真实 prompt_tokens（从 usage chunk 读取）；provider 不返回时保持 undefined */
+    let usagePromptTokens;
     try {
         while (true) {
             // 每次 read 前检查 abort：用户按 ESC/Ctrl+C 时 signal.aborted 为 true。
@@ -121,8 +128,8 @@ export async function* chat(args) {
                     continue;
                 const dataStr = line.slice(5).trim(); // 去掉 "data:" 前缀
                 if (dataStr === '[DONE]') {
-                    // 流结束标记
-                    yield { type: 'done', stopReason };
+                    // 流结束标记；带出真实 prompt_tokens（provider 不返回时为 undefined，上层 fallback 本地估算）
+                    yield { type: 'done', stopReason, promptTokens: usagePromptTokens };
                     return;
                 }
                 // 解析一个 chunk JSON
@@ -134,6 +141,12 @@ export async function* chat(args) {
                     // 罕见：某些 provider 会发空行或心跳，忽略
                     continue;
                 }
+                // usage chunk：include_usage 开启时，provider 通常在流末单独发一帧，
+                // 此帧 choices 为空（没有 delta），必须在 `if (!delta) continue` 之前读取，
+                // 否则会被 continue 跳过，永远拿不到真实 prompt_tokens。
+                if (chunk.usage && typeof chunk.usage.prompt_tokens === 'number') {
+                    usagePromptTokens = chunk.usage.prompt_tokens;
+                }
                 const delta = chunk.choices?.[0]?.delta;
                 const finish = chunk.choices?.[0]?.finish_reason;
                 if (finish) {
@@ -189,8 +202,8 @@ export async function* chat(args) {
                 }
             }
         }
-        // 如果流没显式发 [DONE]，也补一个 done
-        yield { type: 'done', stopReason };
+        // 如果流没显式发 [DONE]，也补一个 done；同样带出 promptTokens
+        yield { type: 'done', stopReason, promptTokens: usagePromptTokens };
     }
     finally {
         reader.releaseLock?.();

package/src/loop.js

@@ -30,8 +30,16 @@ import crypto from 'node:crypto';
 import { autoCompactIfNeeded } from './context/compact.js';
 import { microCompact, incrementTurn, expireOldEntries } from './context/microCompactLite.js';
 import { isPromptTooLongError, reactiveCompactIfApplicable, } from './context/reactiveCompact.js';
+import { snipCompactIfNeeded } from './context/snipCompact.js';
+import { countMessagesTokens, estimateToolsTokens } from './context/tokenCounter.js';
 import { chat as defaultChat } from './llm/client.js';
-import { ALL_TOOLS, executeTool as defaultExecuteTool } from './tools/index.js';
+import { ALL_TOOLS, executeTool as defaultExecuteTool, getToolByName } from './tools/index.js';
+/**
+ * 工具 schema 的估算 token 数（ALL_TOOLS 固定，模块加载时算一次即可）。
+ * 每轮 LLM 请求都会带上整套工具 schema，但 countMessagesTokens 只数历史消息、
+ * 漏了这部分 → 系统性低估。autoCompact 判定阈值时加上它才准。
+ */
+const TOOLS_SCHEMA_TOKENS = estimateToolsTokens(ALL_TOOLS);
 /**
  * 执行一次"用户输入 → 模型回答完成"的完整流程。
  *
@@ -54,9 +62,13 @@ export async function* runQuery(userInput, options) {
     // 立即通知 UI：用户消息已入栈，触发 bump 让 <Static> 马上把它 commit 进 scrollback，
     // 不必等整轮 assistant 落定（保证用户输入第一时间置顶，符合 T-A-O-R 展示顺序）。
     yield { type: 'user_message_committed' };
-    // 反应式压缩自救：本 runQuery 只允许触发一次，避免压缩失败导致死循环。
-    // 配合 reactiveCompact.ts 的 attempted（session 级）双层防爆。
-    let reactiveAttempted = false;
+    // 反应式压缩自救：本 runQuery 内最多触发 MAX_REACTIVE_PER_QUERY 次（防本轮死循环）；
+    // 跨 runQuery 的连续失败由 reactiveCompact.ts 的 circuit breaker（consecutiveFailures）兜底。
+    let reactiveCount = 0;
+    const MAX_REACTIVE_PER_QUERY = 3;
+    // 上一轮 LLM 返回的真实 prompt token 数（done.promptTokens；provider 开 include_usage 才有）。
+    // 作为 autoCompact 的权威判据，校正本地估算的系统性低估；压缩后清空（历史已变，旧值失真）。
+    let lastPromptTokens;
     let turn = 0;
     while (turn < maxTurns) {
         turn++;
@@ -74,27 +86,45 @@ export async function* runQuery(userInput, options) {
             yield { type: 'error', error: '已被用户中断', code: 'aborted' };
             return;
         }
-        // 2. 自动压缩
+        // 2. 自动压缩（判据 = max(上一轮真实 usage, 历史估算 + 工具 schema)，
+        //    阈值 provider 无关、按 contextWindow × compactRatio 比例触发）
         try {
-            const compact = await autoCompactIfNeeded(history, provider);
+            const compact = await autoCompactIfNeeded(history, provider, {
+                actualPromptTokens: lastPromptTokens,
+                toolsTokens: TOOLS_SCHEMA_TOKENS,
+            });
             if (compact.compacted) {
                 yield { type: 'compact_start' };
                 yield { type: 'stage_change', stage: 'compacting' };
                 // in-place 替换 history（保持调用方持有的引用有效）
                 history.length = 0;
                 history.push(...compact.messages);
+                // 历史已压缩变小，旧的真实 usage 不再代表当前请求 → 清空，下一轮先用估算判据
+                lastPromptTokens = undefined;
                 yield { type: 'compact_done', before: compact.before, after: compact.after };
                 // 压缩完会回到 LLM 调用，stage 退回 thinking
                 yield { type: 'stage_change', stage: 'thinking' };
             }
         }
         catch (e) {
-            // 压缩失败不要让整个对话挂掉。
-            // code='compact_failed'：标记为「非致命」——注意此处 yield error 后**不 return**，
-            // loop 继续往下跑（不压缩硬上）。`-p --output-format json` 据此只 stderr 警告、不退出。
+            // 压缩失败不要让整个对话挂掉：先 snip 砍最老消息释放空间再继续，
+            // 避免下一步 LLM 直接撞 prompt-too-long（code='compact_failed' 非致命，不 return）。
+            try {
+                const before = countMessagesTokens(history);
+                const snipped = snipCompactIfNeeded(history, { force: true, snipPercent: 0.3 });
+                if (snipped.messagesRemoved > 0) {
+                    history.length = 0;
+                    history.push(...snipped.messages);
+                    lastPromptTokens = undefined;
+                    yield { type: 'compact_done', before, after: countMessagesTokens(history) };
+                }
+            }
+            catch {
+                /* snip 也失败 → 真的只能硬上 */
+            }
             yield {
                 type: 'error',
-                error: `自动压缩失败（继续不压缩）：${e.message}`,
+                error: `自动压缩失败（已尝试 snip 兜底后继续）：${e.message}`,
                 code: 'compact_failed',
             };
         }
@@ -111,6 +141,12 @@ export async function* runQuery(userInput, options) {
         const reasoningDetails = [];
         /** 首个 text_delta 时切到 streaming，再来不重复 yield */
         let stageStreamingYielded = false;
+        /**
+         * R2：本轮 LLM 流的终止原因（来自 client 的 done.stopReason）。
+         * 'length' = 被 provider 因 max_tokens 截断 —— 收尾时据此给 warning，
+         * 避免「半截答案」被静默当成正常 end_turn。
+         */
+        let lastFinishReason = 'unknown';
         // 进入 LLM 流前：等首 token / reasoning，本质是 thinking
         yield { type: 'stage_change', stage: 'thinking' };
         try {
@@ -145,7 +181,13 @@ export async function* runQuery(userInput, options) {
                         reasoningDetails.push(...ev.items);
                     }
                 }
-                // ev.type === 'done' 时无需处理：循环自然结束
+                else if (ev.type === 'done') {
+                    // R2：记下流的终止原因。'length'（max_tokens 截断）会在本轮收尾时触发 warning。
+                    lastFinishReason = ev.stopReason;
+                    // 真实 prompt token（provider 开 include_usage 才有）→ 喂给下一轮 autoCompact 做权威判据
+                    if (typeof ev.promptTokens === 'number')
+                        lastPromptTokens = ev.promptTokens;
+                }
             }
         }
         catch (e) {
@@ -163,14 +205,17 @@ export async function* runQuery(userInput, options) {
             // prompt_too_long 反应式自救：压缩历史 → 同 turn 重发 LLM
             // LLM 看到压缩后的 9 段摘要 + 近期 verbatim 消息，能接着干活，
             // 不会丢失中途的工具调用上下文。
-            if (isPromptTooLongError(e) && !reactiveAttempted) {
-                reactiveAttempted = true;
+            if (isPromptTooLongError(e) && reactiveCount < MAX_REACTIVE_PER_QUERY) {
+                reactiveCount++;
                 yield { type: 'compact_start' };
                 yield { type: 'stage_change', stage: 'compacting' };
                 const result = await reactiveCompactIfApplicable(history, provider, e, sessionState?.reactive);
-                if (result.recovered) {
+                // 仅当确实压下去了（after < before）才重试；否则（没压动 / 未恢复）退回错误路径，杜绝死循环。
+                const shrank = (result.after ?? 0) < (result.before ?? 0);
+                if (result.recovered && shrank) {
                     history.length = 0;
                     history.push(...result.messages);
+                    lastPromptTokens = undefined; // 历史已变小，旧真实 usage 失真
                     yield {
                         type: 'compact_done',
                         before: result.before ?? 0,
@@ -181,7 +226,7 @@ export async function* runQuery(userInput, options) {
                     turn--; // 不消耗 turn 配额，本轮重新走
                     continue;
                 }
-                // reactive 也失败 → 退回正常错误路径
+                // reactive 没压动或未恢复 → 退回正常错误路径
             }
             // code='llm_error'：终结性错误，stop_reason='error'
             yield {
@@ -191,6 +236,15 @@ export async function* runQuery(userInput, options) {
             };
             return;
         }
+        // S2 防御：OpenAI 协议保证 tool_call 的 index 连续；万一某 provider 跳号产生稀疏数组，
+        // 这里压实掉空洞，避免后续遍历 / 回填遇到 undefined（assistantMsg.tool_calls 与执行都用它）。
+        {
+            const dense = toolCallsByIndex.filter((tc) => tc != null);
+            if (dense.length !== toolCallsByIndex.length) {
+                toolCallsByIndex.length = 0;
+                toolCallsByIndex.push(...dense);
+            }
+        }
         const assistantMsg = {
             role: 'assistant',
             content: assistantText.length > 0 ? assistantText : null,
@@ -205,100 +259,112 @@ export async function* runQuery(userInput, options) {
         yield { type: 'assistant_message', message: assistantMsg };
         // 4. 没有工具调用 → 整轮交互结束
         if (toolCallsByIndex.length === 0) {
+            // R2：最终回答被 provider 因 max_tokens 截断（finish_reason='length'）时，
+            // 不能静默当正常 end_turn 收尾 —— 否则 -p 宿主会拿到半截答案却以为成功。
+            // 走通用 warning（text/json 都落 stderr，不污染 json 那一行 stdout 契约）。
+            if (lastFinishReason === 'length') {
+                yield {
+                    type: 'warning',
+                    message: '⚠️ 模型回答可能被截断（finish_reason=length，触顶 max_tokens），本轮回答或不完整。' +
+                        '可调大模型的 max_tokens 上限，或让模型分段输出。',
+                };
+            }
             yield { type: 'turn_done' };
             return;
         }
-        // 5. 并行执行所有工具
+        // 5. 执行工具调用
         //
-        // 设计：用 Promise.allSettled 启动 N 个 worker，配合一个简易事件队列
-        // （queue + signalNew）把多个 worker 的 tool_start / tool_end 事件按
-        // 真实完成顺序交错 yield 给 UI；但 history 里的 tool 消息严格按
-        // toolCallsByIndex 索引顺序 push（OpenAI 协议要求 tool 消息和上一条
-        // assistant 的 tool_calls 一一对应）。
+        // R1：按 isConcurrencySafe 决定并发策略 —— 工具早就声明了这个字段，此前却没有
+        // 任何执行路径消费它（全程无条件并行），这里让它真正生效：
+        //   - 本轮工具「全部并发安全」（只读类 Read/Grep/Glob/WebSearch/WebFetch）且不止一个
+        //     → 并行：用事件队列把多个 worker 的 tool_start/tool_end 按真实完成顺序交错 yield。
+        //   - 只要有一个写类/未知工具（Edit/Write/MultiEdit/Bash/WebBrowser）→ 整轮串行：
+        //     彻底杜绝两个写操作并行落到同一文件导致的 lost-update / fileState TOCTOU。
+        // 两种路径下，history 里的 tool 消息都严格按 toolCallsByIndex 索引顺序回填
+        // （OpenAI 协议要求 tool 消息与上一条 assistant 的 tool_calls 一一对应）。
         yield { type: 'stage_change', stage: 'tool_executing' };
-        const queue = [];
-        let signalNew = null;
-        const enqueue = (ev) => {
-            queue.push(ev);
-            signalNew?.();
-            signalNew = null;
-        };
-        const workers = toolCallsByIndex.map(async (tc) => {
-            enqueue({
-                type: 'tool_start',
-                toolCallId: tc.id,
-                toolName: tc.function.name,
-                argsPreview: previewArgs(tc.function.arguments),
-                argsFriendly: friendlyToolDescription(tc.function.name, tc.function.arguments),
-            });
+        // 执行单个 tool call → WorkerOutcome（内部吞掉 abort/异常，永不 reject）。
+        const runOne = async (tc) => {
             try {
                 const result = await executeToolFn(tc.function.name, tc.function.arguments, signal);
-                enqueue({
-                    type: 'tool_end',
-                    toolCallId: tc.id,
-                    toolName: tc.function.name,
-                    ok: result.ok,
-                    content: result.ok ? result.content : `Error: ${result.error}`,
-                });
                 return { tc, result };
             }
             catch (e) {
                 if (e.name === 'AbortError') {
-                    enqueue({
-                        type: 'tool_end',
-                        toolCallId: tc.id,
-                        toolName: tc.function.name,
-                        ok: false,
-                        content: '(已中断)',
-                    });
                     return { tc, result: { ok: false, error: 'aborted' } };
                 }
-                const msg = e.message;
-                enqueue({
-                    type: 'tool_end',
-                    toolCallId: tc.id,
-                    toolName: tc.function.name,
-                    ok: false,
-                    content: msg,
-                });
-                return { tc, result: { ok: false, error: msg } };
+                return { tc, result: { ok: false, error: e.message } };
             }
+        };
+        const startEvent = (tc) => ({
+            type: 'tool_start',
+            toolCallId: tc.id,
+            toolName: tc.function.name,
+            argsPreview: previewArgs(tc.function.arguments),
+            argsFriendly: friendlyToolDescription(tc.function.name, tc.function.arguments),
+        });
+        const endEvent = (o) => ({
+            type: 'tool_end',
+            toolCallId: o.tc.id,
+            toolName: o.tc.function.name,
+            ok: o.result.ok,
+            content: o.result.ok
+                ? o.result.content
+                : o.result.error === 'aborted'
+                    ? '(已中断)'
+                    : `Error: ${o.result.error}`,
         });
-        const allDone = Promise.allSettled(workers);
-        let finished = false;
-        allDone.then(() => {
-            finished = true;
-            signalNew?.();
-            signalNew = null;
+        const allConcurrencySafe = toolCallsByIndex.every((tc) => {
+            const tool = getToolByName(tc.function.name);
+            return tool?.isConcurrencySafe === true;
         });
-        while (!finished || queue.length > 0) {
-            while (queue.length > 0)
-                yield queue.shift();
-            if (finished)
-                break;
-            await new Promise((r) => {
-                signalNew = r;
+        let settled;
+        if (allConcurrencySafe && toolCallsByIndex.length > 1) {
+            // —— 并行：事件队列把各 worker 的 start/end 按真实完成顺序交错 yield 给 UI。
+            const queue = [];
+            let signalNew = null;
+            const enqueue = (ev) => {
+                queue.push(ev);
+                signalNew?.();
+                signalNew = null;
+            };
+            const workers = toolCallsByIndex.map(async (tc) => {
+                enqueue(startEvent(tc));
+                const o = await runOne(tc);
+                enqueue(endEvent(o));
+                return o;
             });
-        }
-        // 严格按 toolCallsByIndex 顺序 push tool 消息进 history（OpenAI 协议要求）
-        const settled = await allDone;
-        let anyAborted = false;
-        for (let i = 0; i < toolCallsByIndex.length; i++) {
-            const tc = toolCallsByIndex[i];
-            const r = settled[i];
-            if (r.status === 'rejected') {
-                // 理论上 worker 已经 catch 了所有异常，这里只是防御
-                const errMsg = r.reason?.message ?? 'unknown';
-                history.push({
-                    role: 'tool',
-                    tool_call_id: tc.id,
-                    content: `Error: ${errMsg}`,
-                    timestamp: Date.now(),
-                    id: crypto.randomUUID(),
+            const allDone = Promise.all(workers);
+            let finished = false;
+            void allDone.then(() => {
+                finished = true;
+                signalNew?.();
+                signalNew = null;
+            });
+            while (!finished || queue.length > 0) {
+                while (queue.length > 0)
+                    yield queue.shift();
+                if (finished)
+                    break;
+                await new Promise((r) => {
+                    signalNew = r;
                 });
-                continue;
             }
-            const { result } = r.value;
+            settled = await allDone;
+        }
+        else {
+            // —— 串行：逐个执行（含写类工具，或只有一个工具）。事件直接顺序 yield，无需队列。
+            settled = [];
+            for (const tc of toolCallsByIndex) {
+                yield startEvent(tc);
+                const o = await runOne(tc);
+                yield endEvent(o);
+                settled.push(o);
+            }
+        }
+        // 严格按 toolCallsByIndex 顺序把 tool 消息回填 history（settled 已保持该顺序）。
+        let anyAborted = false;
+        for (const { tc, result } of settled) {
             if (!result.ok && result.error === 'aborted')
                 anyAborted = true;
             const rawContent = result.ok ? result.content : `Error: ${result.error}`;
@@ -315,7 +381,7 @@ export async function* runQuery(userInput, options) {
             });
         }
         if (anyAborted || signal?.aborted) {
-            // 任一工具抛 AbortError 时，外层 yield interrupted 并 return
+            // 工具被中断时，外层 yield interrupted 并 return
             yield { type: 'interrupted' };
             return;
         }
@@ -375,6 +441,10 @@ function friendlyToolDescription(toolName, rawArgsJson) {
     switch (toolName) {
         case 'Read': return `Reading ${truncate(args.file_path, 60)}`;
         case 'Edit': return `Editing ${truncate(args.file_path, 60)}`;
+        case 'MultiEdit': {
+            const n = Array.isArray(args.edits) ? args.edits.length : 0;
+            return `Editing ${truncate(args.file_path, 50)}${n ? ` (${n} 处)` : ''}`;
+        }
         case 'Write': return `Writing ${truncate(args.file_path, 60)}`;
         case 'Bash': return `Running \`${truncate(args.command, 40)}\``;
         case 'Grep': {