minimal-agent 0.6.2 → 0.6.3

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': {

package/src/main.js

@@ -20,12 +20,13 @@ const pkg = (() => {
 import { extractCwdArg } from './bootstrap/cwdArg.js';
 import { initWorkingDir, getWorkingDir } from './bootstrap/workingDir.js';
 import { applyToolKeysToEnv, loadProviderLayered } from './config.js';
-import { loadContext } from './context/persistContext.js';
+import { clearContext, loadContext } from './context/persistContext.js';
 import { migrateLegacyContext } from './context/sessionPath.js';
 import { buildFullSystemPrompt } from './prompts/system.js';
 import { ALL_TOOLS } from './tools/index.js';
 import { Root } from './ui/Root.js';
 import { runPrintMode } from './cli/print.js';
+import { runStreamJsonMode } from './cli/streamJson.js';
 import { extractFlagValue } from './cli/args.js';
 // re-export：对外保持「main.tsx 提供 extractFlagValue」的语义；实现住在 cli/args.ts，
 // 这样单测可零副作用 import（main.tsx 顶层 main() 自调用会启动整个 app，不可被测试 import）。
@@ -59,12 +60,23 @@ async function main() {
         console.log(`minimal-agent v${pkg.version}`);
         return;
     }
+    // --clear：清空当前工作目录的会话（归档 + 清空）后退出。供 webchat 的 /new 调用。
+    //   无需 provider；上面 -d/--cwd 已 chdir + initWorkingDir，clearContext() 作用于该目录。
+    if (args.includes('--clear')) {
+        await clearContext();
+        return;
+    }
     const isPrintMode = args.includes('-p') || args.includes('--print');
     if (isPrintMode) {
         // 先把输出格式解析出来——provider 缺失分支也要按 json 契约给信号。
         // 只接受 'text' | 'json'，其它值（含拼错）一律回落 'text'（向后兼容）。
         const rawFormat = extractFlagValue(args, ['--output-format']);
-        const outputFormat = rawFormat === 'json' ? 'json' : 'text';
+        // text（默认，逐字节向后兼容）/ json（一行结局契约）/ stream-json（逐行 LoopEvent，webchat broker 用）
+        const outputFormat = rawFormat === 'json'
+            ? 'json'
+            : rawFormat === 'stream-json'
+                ? 'stream-json'
+                : 'text';
         // --max-turns：parseInt，非法（NaN）→ undefined（走 loop 默认 50）
         const rawMaxTurns = extractFlagValue(args, ['--max-turns']);
         const parsedMaxTurns = rawMaxTurns !== undefined ? Number.parseInt(rawMaxTurns, 10) : Number.NaN;
@@ -85,6 +97,10 @@ async function main() {
                     error: 'provider config not found',
                 }));
             }
+            else if (outputFormat === 'stream-json') {
+                // stream-json：吐一行 error 事件（webchat 前端识别为致命错误）
+                console.log(JSON.stringify({ type: 'error', error: 'provider config not found', code: 'llm_error' }));
+            }
             process.stderr.write(`\n未找到 provider 配置。\n\n` +
                 `请二选一：\n` +
                 `  1. 设置环境变量 MINIMAL_AGENT_BASE_URL / MINIMAL_AGENT_API_KEY / MINIMAL_AGENT_MODEL\n` +
@@ -93,6 +109,14 @@ async function main() {
         }
         const initialHistory = await buildInitialHistory();
         const verbose = args.includes('--verbose') || args.includes('-v');
+        // stream-json 走独立流式模式（webchat broker / 网关用）；text/json 仍走原 runPrintMode（契约不变）。
+        if (outputFormat === 'stream-json') {
+            await runStreamJsonMode(provider, args, initialHistory, {
+                maxTurns,
+                compact: args.includes('--compact'),
+            });
+            return;
+        }
         await runPrintMode(provider, args, initialHistory, { verbose, outputFormat, maxTurns });
         return;
     }
@@ -131,9 +155,12 @@ minimal-agent - 轻量级 AI 编程助手
   -v, --verbose      显示详细输出（工具调用、压缩信息）
   -d, --cwd <dir>    指定工作目录（不存在自动创建）；启动时 chdir 到这里，
                      上下文文件、工具相对路径、.env 加载都以此为基准
-  --output-format <fmt>  text（默认）= 纯文本答案；json = stdout 输出一行结构化
-                         结局契约（ok / result / stop_reason / num_turns / error）
+  --output-format <fmt>  text（默认）= 纯文本答案；json = 一行结局契约
+                         （ok / result / stop_reason / num_turns / error）；
+                         stream-json = 逐行 LoopEvent（webchat / 网关 broker 用）
   --max-turns <n>    最大工具循环轮数（防失控；缺省 50）
+  --clear            清空当前工作目录的会话（归档 + 清空）后退出
+  --compact          与 -p --output-format stream-json 连用：压缩当前会话
   -h, --help         显示帮助信息
 
 会话记忆:

package/src/plugins/transcript.js

@@ -26,7 +26,9 @@ import { randomUUID } from 'node:crypto';
 // 模块级状态：当前会话的 handle（lazy 初始化）
 let current = null;
 function transcriptDir() {
-    return join(homedir(), '.minimal-agent', 'transcripts');
+    // 优先使用环境变量（测试可覆盖；Docker/K8s 也常靠 ENV 定位 home），
+    // fallback 到 os.homedir()（生产环境缺 ENV 时用系统默认值）。
+    return join(process.env.HOME ?? process.env.USERPROFILE ?? homedir(), '.minimal-agent', 'transcripts');
 }
 function generateSessionId() {
     return `${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;