min-agent 0.2.0 → 0.3.0

package/dist/agent.js

@@ -1,10 +1,12 @@
 import { streamText, stepCountIs } from "ai";
-import { readFileSync, existsSync } from "fs";
+import { readFileSync, existsSync, statSync } from "fs";
 import path from "path";
 import { resolveModel } from "./provider.js";
+import { loadConfig, getActiveProvider } from "./config.js";
+import { getModelPrice, estimateCost } from "./pricing.js";
 import { createChatTools, createCodeTools } from "./tools/index.js";
 import { initMcp, shutdownMcp, getMcpTools } from "./mcp.js";
-import { discoverSkills, getSkillsTool, getSkillsSystemPrompt, getSkills } from "./skills.js";
+import { discoverSkills, attachSkills, collectLoadedSkillNames } from "./skills.js";
 import { loadInstructions } from "./instructions.js";
 import { getMemorySystemPrompt, getMemoryTools } from "./memory.js";
 import { needsCompaction, compactMessages, estimateTokens, TokenTracker } from "./compaction.js";
@@ -13,19 +15,27 @@ import { MarkdownRenderer } from "./markdown.js";
 import { DoomLoopDetector } from "./doom-loop.js";
 import { ThinkingBodySplitter, stripThinkingFromAssistantText } from "./assistant-stream.js";
 import { printHeader, printDivider, printToolCall, printToolResult, printDone } from "./output.js";
+import { createTodoTool } from "./tools/todo.js";
+import { getContextWindow } from "./context-window.js";
+import { log, logToolCall, logToolResult } from "./logger.js";
+import { markSyntheticMessage } from "./synthetic.js";
 const MAX_STEPS = 30;
-function dimStyle() {
-    if ("NO_COLOR" in process.env)
-        return { dim: "", reset: "" };
-    return { dim: "\x1b[90m", reset: "\x1b[0m" };
-}
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+const IMAGE_MIME_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
+const DIM_STYLE = "NO_COLOR" in process.env ? { dim: "", reset: "" } : { dim: "\x1b[90m", reset: "\x1b[0m" };
 /** Shown immediately so the terminal does not look frozen while MCP / rules load. */
 function printInitLoading() {
-    const { dim, reset } = dimStyle();
+    const { dim, reset } = DIM_STYLE;
     console.log(`${dim}⟳ 正在初始化（MCP、技能、规则）…${reset}`);
 }
 function printInitReady() {
-    const { dim, reset } = dimStyle();
+    const { dim, reset } = DIM_STYLE;
     console.log(`${dim}✓ 就绪${reset}`);
 }
 /** Stream thinking to stderr (dim). Set MIN_AGENT_SHOW_THINKING=0 to hide. */
@@ -34,10 +44,7 @@ function writeThinkingDelta(text) {
         return;
     if (process.env.MIN_AGENT_SHOW_THINKING === "0" || process.env.MIN_AGENT_SHOW_THINKING === "false")
         return;
-    const noColor = "NO_COLOR" in process.env;
-    const dim = noColor ? "" : "\x1b[2m";
-    const reset = noColor ? "" : "\x1b[0m";
-    process.stderr.write(`${dim}${text}${reset}`);
+    process.stderr.write(`${DIM_STYLE.dim}${text}${DIM_STYLE.reset}`);
 }
 function buildSystemPrompt(instructions) {
     const parts = [
@@ -45,7 +52,7 @@ function buildSystemPrompt(instructions) {
         "",
         "Be concise and direct. When you run a command, briefly explain why.",
         "Use the available tools to complete tasks. When multiple independent operations are needed, call tools in parallel.",
-        "When the user asks about current events, news, or anything requiring up-to-date information, use the web_search tool.",
+        "When the user asks about current events, news, or anything requiring up-to-date information, use the search_web tool.",
         "",
         `Working directory: ${process.cwd()}`,
         `Platform: ${process.platform}`,
@@ -53,330 +60,245 @@ function buildSystemPrompt(instructions) {
         "",
         `When the user asks to configure, install, or manage MCP servers, skills, rules, memory, or other min-agent features, use the read tool on the file at ${path.resolve(path.dirname(new URL(import.meta.url).pathname), "../README.md")} first, then follow what it says.`,
     ];
-    const skillsPrompt = getSkillsSystemPrompt();
-    if (skillsPrompt) {
-        parts.push("", skillsPrompt);
-    }
-    const memoryPrompt = getMemorySystemPrompt();
-    if (memoryPrompt) {
-        parts.push("", memoryPrompt);
-    }
     if (instructions.length > 0) {
         parts.push("", "# User Instructions", "");
         parts.push(...instructions);
     }
     return parts.join("\n");
 }
-/** Build user message content, optionally with images */
-export async function buildUserContent(message, imagePaths) {
-    if (!imagePaths || imagePaths.length === 0)
-        return message;
-    const parts = [{ type: "text", text: message }];
+export function loadImageParts(imagePaths, notify) {
+    const parts = [];
     for (const imgPath of imagePaths) {
         const resolved = path.resolve(process.cwd(), imgPath);
         if (!existsSync(resolved)) {
-            console.error(`\x1b[33m  Warning: Image not found: ${imgPath}\x1b[0m`);
+            notify?.("not_found", imgPath);
+            continue;
+        }
+        const size = statSync(resolved).size;
+        if (size > MAX_IMAGE_BYTES) {
+            notify?.("too_large", imgPath, size);
             continue;
         }
         const data = readFileSync(resolved);
         const ext = path.extname(resolved).toLowerCase();
-        const mimeMap = {
-            ".png": "image/png",
-            ".jpg": "image/jpeg",
-            ".jpeg": "image/jpeg",
-            ".gif": "image/gif",
-            ".webp": "image/webp",
-        };
-        const mimeType = mimeMap[ext] ?? "image/png";
-        parts.push({
-            type: "image",
-            image: data,
-            mimeType,
-        });
-        console.log(`\x1b[90m  📎 ${imgPath}\x1b[0m`);
+        parts.push({ type: "image", image: data, mimeType: IMAGE_MIME_TYPES[ext] ?? "image/png" });
+        notify?.("attached", imgPath);
     }
     return parts;
 }
+/** Build user message content, optionally with images */
+export async function buildUserContent(message, imagePaths) {
+    if (!imagePaths || imagePaths.length === 0)
+        return message;
+    const images = loadImageParts(imagePaths, (kind, imgPath, sizeBytes) => {
+        if (kind === "not_found") {
+            console.error(`\x1b[33m  Warning: Image not found: ${imgPath}\x1b[0m`);
+        }
+        else if (kind === "too_large") {
+            console.error(`\x1b[33m  Warning: Image skipped (${((sizeBytes ?? 0) / 1024 / 1024).toFixed(1)} MB exceeds ${MAX_IMAGE_BYTES / 1024 / 1024} MB limit): ${imgPath}\x1b[0m`);
+        }
+        else {
+            console.log(`\x1b[90m  📎 ${imgPath}\x1b[0m`);
+        }
+    });
+    return [{ type: "text", text: message }, ...images];
+}
 /** Single-shot: send one message, get response, exit */
-export async function runAgent(message, modelId, imagePaths) {
+export async function runAgent(message, modelId, imagePaths, providerName) {
     printHeader(modelId);
     printDivider();
     printInitLoading();
     await initMcp();
-    discoverSkills();
-    const instructions = await loadInstructions();
-    printInitReady();
-    console.log(`\x1b[36m> ${message}\x1b[0m\n`);
-    const content = await buildUserContent(message, imagePaths);
-    const messages = [{ role: "user", content }];
-    const tracker = new TokenTracker();
-    await runOnce(messages, instructions, modelId, undefined, undefined, tracker);
-    await shutdownMcp();
+    try {
+        discoverSkills();
+        const instructions = await loadInstructions();
+        printInitReady();
+        console.log(`\x1b[36m> ${message}\x1b[0m\n`);
+        const content = await buildUserContent(message, imagePaths);
+        const messages = [{ role: "user", content }];
+        const tracker = new TokenTracker();
+        await runOnce(messages, instructions, modelId, undefined, undefined, tracker, { providerName });
+    }
+    finally {
+        await shutdownMcp();
+    }
 }
-/** runOnce variant that accepts a pre-built system prompt (for code mode) */
-export async function runOnceWithSystem(messages, systemPrompt, modelId, abortSignal, callbacks, tracker) {
-    const model = resolveModel(modelId);
-    const api = !!callbacks;
-    if (needsCompaction(messages, tracker)) {
-        console.log("\x1b[90m⟳ Compacting context...\x1b[0m");
-        const result = await compactMessages(messages, model);
-        if (result.compacted) {
-            messages.length = 0;
-            messages.push(...result.messages);
-            if (result.shouldContinue) {
-                const continueText = result.replayText || "Continue with your task.";
-                messages.push({ role: "user", content: continueText });
-            }
-            if (tracker)
-                tracker.resetContext();
-            console.log(`\x1b[90m  ✓ Compacted (${estimateTokens(messages)} tokens estimated)\x1b[0m`);
-        }
+/**
+ * Push assistant text + tool call/result history into `messages` so the model
+ * remembers its tool activity across turns and resumed sessions.
+ */
+export function pushTurn(messages, assistantText, toolCalls, toolResults) {
+    const cleaned = stripThinkingFromAssistantText(assistantText);
+    const resultIds = new Set(toolResults.map((r) => r.toolCallId));
+    const parts = [];
+    if (cleaned.trim())
+        parts.push({ type: "text", text: cleaned });
+    for (const c of toolCalls) {
+        if (!resultIds.has(c.toolCallId))
+            continue;
+        parts.push({ type: "tool-call", toolCallId: c.toolCallId, toolName: c.toolName, input: c.input });
+    }
+    if (parts.length > 0) {
+        messages.push({ role: "assistant", content: parts });
+    }
+    for (const r of toolResults) {
+        const text = typeof r.output === "string" ? r.output : JSON.stringify(r.output);
+        messages.push({
+            role: "tool",
+            content: [
+                {
+                    type: "tool-result",
+                    toolCallId: r.toolCallId,
+                    toolName: r.toolName,
+                    output: { type: "text", value: text },
+                },
+            ],
+        });
     }
-    const builtinTools = createCodeTools();
+}
+async function buildTools(mode, modelId, abortSignal, planMode = false, messages = [], tracker) {
+    const builtinTools = mode === "code" ? createCodeTools() : createChatTools();
+    builtinTools["todo"] = createTodoTool();
     const mcpTools = getMcpTools();
     const memoryTools = getMemoryTools();
     const pluginTools = await loadPluginTools();
-    const { createTaskTool } = await import("./tools/task.js");
-    const { createExploreTool } = await import("./tools/explore.js");
-    const skills = getSkills();
     const allTools = { ...builtinTools, ...memoryTools, ...pluginTools };
     for (const [id, t] of Object.entries(mcpTools))
         allTools[id] = t;
-    if (skills.length > 0)
-        allTools["skill"] = getSkillsTool();
-    allTools["task"] = createTaskTool(modelId);
-    allTools["explore"] = createExploreTool(modelId);
-    let stepCount = 0;
-    let hasError = false;
-    const doomLoop = new DoomLoopDetector();
-    const result = streamText({
-        model,
-        system: systemPrompt,
-        messages,
+    const skillsPrompt = attachSkills(allTools, collectLoadedSkillNames(messages));
+    const onUsage = tracker ? (usage) => tracker.add(usage) : undefined;
+    const { createExploreTool } = await import("./tools/explore.js");
+    allTools["explore"] = createExploreTool(modelId, abortSignal, onUsage);
+    if (mode === "code") {
+        const { createTaskTool } = await import("./tools/task.js");
+        allTools["task"] = createTaskTool(modelId, abortSignal, onUsage);
+    }
+    if (planMode) {
+        for (const name of ["bash", "write", "edit", "apply_patch"])
+            delete allTools[name];
+    }
+    return {
         tools: allTools,
-        stopWhen: stepCountIs(MAX_STEPS),
-        maxRetries: 3,
-        abortSignal,
-        onStepFinish() { stepCount++; },
-        onError() { },
-    });
-    Promise.resolve(result.usage).catch(() => { });
-    let rawText = "";
-    let assistantText = "";
-    const md = new MarkdownRenderer();
-    const thinkingSplit = new ThinkingBodySplitter();
+        promptSections: [skillsPrompt, getMemorySystemPrompt()].filter((s) => s.length > 0),
+    };
+}
+function formatErrorMessage(msg) {
+    if (msg.includes("API key") || msg.includes("Unauthorized") || msg.includes("Forbidden")) {
+        return "Authentication error: Check your API key.";
+    }
+    if (msg.includes("429") || msg.includes("rate limit") || msg.includes("Rate limit")) {
+        return "Rate limited after retries. Please wait and try again.";
+    }
+    if (msg.includes("timeout") || msg.includes("ETIMEDOUT") || msg.includes("ECONNRESET")) {
+        return `Network error (retries exhausted): ${msg}`;
+    }
+    return msg;
+}
+async function safeUsage(result) {
     try {
-        for await (const event of result.fullStream) {
-            switch (event.type) {
-                case "text-delta": {
-                    const { display, thinking } = thinkingSplit.feed(event.text);
-                    if (thinking) {
-                        if (callbacks?.onThinkingDelta)
-                            callbacks.onThinkingDelta(thinking);
-                        else
-                            writeThinkingDelta(thinking);
-                    }
-                    if (display) {
-                        rawText += display;
-                        assistantText += display;
-                        if (callbacks?.onAssistantDisplayDelta)
-                            callbacks.onAssistantDisplayDelta(display);
-                        else {
-                            const formatted = md.write(display);
-                            if (formatted)
-                                process.stdout.write(formatted);
-                        }
-                    }
-                    break;
-                }
-                case "tool-call": {
-                    if (doomLoop.record(event.toolName, event.input)) {
-                        const warn = `Doom loop detected: "${event.toolName}" — breaking.`;
-                        if (callbacks?.onStreamError)
-                            callbacks.onStreamError(warn);
-                        else
-                            console.log(`\n\x1b[33m⚠ ${warn}\x1b[0m`);
-                        hasError = true;
-                        break;
-                    }
-                    const flush = thinkingSplit.flush();
-                    if (flush.thinking) {
-                        if (callbacks?.onThinkingDelta)
-                            callbacks.onThinkingDelta(flush.thinking);
-                        else
-                            writeThinkingDelta(flush.thinking);
-                    }
-                    if (flush.display) {
-                        rawText += flush.display;
-                        assistantText += flush.display;
-                        if (callbacks?.onAssistantDisplayDelta)
-                            callbacks.onAssistantDisplayDelta(flush.display);
-                        else {
-                            const extra = md.write(flush.display);
-                            if (extra)
-                                process.stdout.write(extra);
-                        }
-                    }
-                    if (!api) {
-                        const flushed = md.flush();
-                        if (flushed)
-                            process.stdout.write(flushed);
-                        if (rawText.trim())
-                            console.log();
-                    }
-                    rawText = "";
-                    if (callbacks?.onToolCall)
-                        callbacks.onToolCall(event.toolName, event.input);
-                    else
-                        printToolCall(event.toolName, event.input);
-                    break;
-                }
-                case "tool-result":
-                    if (callbacks?.onToolResult)
-                        callbacks.onToolResult(event.toolName, event.output);
-                    else
-                        printToolResult(event.toolName, event.output);
-                    break;
-                case "error":
-                    hasError = true;
-                    if (callbacks?.onStreamError)
-                        callbacks.onStreamError(String(event.error));
-                    else
-                        console.error(`\x1b[31mError: ${event.error}\x1b[0m`);
-                    break;
-                case "finish":
-                    break;
-            }
-        }
-        const end = thinkingSplit.flush();
-        if (end.thinking) {
-            if (callbacks?.onThinkingDelta)
-                callbacks.onThinkingDelta(end.thinking);
-            else
-                writeThinkingDelta(end.thinking);
-        }
-        if (end.display) {
-            assistantText += end.display;
-            if (callbacks?.onAssistantDisplayDelta)
-                callbacks.onAssistantDisplayDelta(end.display);
-            else {
-                const tail = md.write(end.display);
-                if (tail)
-                    process.stdout.write(tail);
-            }
-        }
-        if (!api) {
-            const remaining = md.flush();
-            if (remaining)
-                process.stdout.write(remaining);
-            if (rawText.trim())
-                console.log();
-        }
-        const cleaned = stripThinkingFromAssistantText(assistantText);
-        if (cleaned.trim())
-            messages.push({ role: "assistant", content: cleaned });
-        let usage;
-        try {
-            usage = await result.usage;
-        }
-        catch {
-            usage = undefined;
-        }
-        if (usage && tracker)
-            tracker.update(usage);
-        if (callbacks?.onRunFinish) {
-            callbacks.onRunFinish({ stepCount, usage, hasError, aborted: false });
-        }
-        else {
-            if (!hasError && usage) {
-                printDivider();
-                const { getContextWindow } = await import("./context-window.js");
-                const ctxWindow = await getContextWindow(modelId);
-                printDone(stepCount, usage, ctxWindow);
-            }
-            else {
-                printDivider();
-            }
-        }
+        return await result.usage;
     }
-    catch (err) {
-        if (err.name === "AbortError" || abortSignal?.aborted) {
-            const cleaned = stripThinkingFromAssistantText(assistantText);
-            if (cleaned.trim())
-                messages.push({ role: "assistant", content: cleaned });
-            if (callbacks?.onRunFinish)
-                callbacks.onRunFinish({ stepCount, usage: undefined, hasError: false, aborted: true });
-            return;
-        }
-        if (callbacks?.onStreamError)
-            callbacks.onStreamError(err.message);
-        else {
-            printDivider();
-            console.error(`\x1b[31mError: ${err.message}\x1b[0m`);
-        }
+    catch {
+        return undefined;
     }
 }
-export async function runOnce(messages, instructions, modelId, abortSignal, callbacks, tracker) {
-    const model = resolveModel(modelId);
-    const api = !!callbacks;
+async function runOnceCore(messages, systemPrompt, modelId, abortSignal, callbacks, tracker, mode, options) {
+    const model = resolveModel(modelId, options?.providerName);
+    log("info", `run start mode=${mode} messages=${messages.length} model=${typeof model === "string" ? model : model.modelId}`);
+    const cbs = callbacks ?? {};
+    const sampling = loadConfig().sampling ?? {};
+    const temperature = options?.temperature ?? sampling.temperature;
+    const maxTokens = options?.maxTokens ?? sampling.maxTokens;
+    const topP = options?.topP ?? sampling.topP;
     // Auto-compact if context is getting too large
-    if (needsCompaction(messages, tracker)) {
-        if (api) {
-            callbacks.onCompaction?.("compacting_start");
+    if (await needsCompaction(messages, tracker)) {
+        if (cbs.onCompaction) {
+            cbs.onCompaction("compacting_start");
         }
-        else {
+        else if (!callbacks) {
             console.log("\x1b[90m⟳ Compacting context...\x1b[0m");
         }
-        const result = await compactMessages(messages, model);
+        const result = await compactMessages(messages, model, { abortSignal });
         if (result.compacted) {
+            if (result.usage && tracker)
+                tracker.add(result.usage);
             messages.length = 0;
             messages.push(...result.messages);
             // Auto-continue: inject a message so the agent keeps working
             if (result.shouldContinue) {
                 const continueText = result.replayText ||
                     "Continue if you have next steps, or stop and ask for clarification if you are unsure how to proceed.";
-                messages.push({ role: "user", content: continueText });
+                const continueMsg = { role: "user", content: continueText };
+                messages.push(continueMsg);
+                markSyntheticMessage(continueMsg);
             }
             if (tracker)
                 tracker.resetContext();
-            if (api) {
-                callbacks.onCompaction?.(`compacted_ok estimated_tokens=${estimateTokens(messages)}`);
+            if (cbs.onCompaction) {
+                cbs.onCompaction(`compacted_ok estimated_tokens=${estimateTokens(messages)}`);
             }
-            else {
+            else if (!callbacks) {
                 console.log(`\x1b[90m  ✓ Compacted (${estimateTokens(messages)} tokens estimated)\x1b[0m`);
             }
         }
     }
-    // Merge tools: chat builtin + MCP + skill + memory + plugins (no task/explore in chat mode)
-    const builtinTools = createChatTools();
-    const mcpTools = getMcpTools();
-    const memoryTools = getMemoryTools();
-    const pluginTools = await loadPluginTools();
-    const skills = getSkills();
-    const allTools = { ...builtinTools, ...memoryTools, ...pluginTools };
-    for (const [id, t] of Object.entries(mcpTools)) {
-        allTools[id] = t;
-    }
-    if (skills.length > 0) {
-        allTools["skill"] = getSkillsTool();
-    }
+    const { tools: allTools, promptSections } = await buildTools(mode, modelId, abortSignal, options?.planMode, messages, tracker);
+    const system = [systemPrompt, ...promptSections].join("\n\n");
     let stepCount = 0;
+    let maxStepsReached = false;
     let hasError = false;
+    let budgetExceeded = false;
+    const cfg = loadConfig();
+    const budgetLimit = cfg.budget?.maxCostUSD;
+    let budgetPrice = null;
+    if (budgetLimit != null && budgetLimit > 0) {
+        const provider = options?.providerName
+            ? cfg.providers?.find((p) => p.name === options.providerName)
+            : getActiveProvider(cfg);
+        budgetPrice = await getModelPrice(modelId ?? provider?.defaultModel ?? "");
+    }
+    const checkBudget = () => {
+        if (!tracker || budgetLimit == null || budgetLimit <= 0)
+            return false;
+        const cost = estimateCost({ inputTokens: tracker.totalInputTokens, outputTokens: tracker.totalOutputTokens }, budgetPrice);
+        if (cost != null && cost > budgetLimit) {
+            budgetExceeded = true;
+            return true;
+        }
+        return false;
+    };
+    // Internal controller so the budget limit can abort mid-run; external
+    // abort requests are forwarded to it.
+    const budgetController = new AbortController();
+    const forwardAbort = () => budgetController.abort();
+    abortSignal?.addEventListener("abort", forwardAbort, { once: true });
     const doomLoop = new DoomLoopDetector();
+    const toolCalls = [];
+    const toolResults = [];
     const result = streamText({
         model,
-        system: buildSystemPrompt(instructions),
+        system,
         messages,
         tools: allTools,
         stopWhen: stepCountIs(MAX_STEPS),
         maxRetries: 3,
-        abortSignal,
-        onStepFinish() {
-            stepCount++;
+        abortSignal: budgetController.signal,
+        ...(temperature != null ? { temperature } : {}),
+        ...(maxTokens != null ? { maxTokens } : {}),
+        ...(topP != null ? { topP } : {}),
+        onStepFinish({ stepNumber, usage }) {
+            stepCount = stepNumber;
+            if (usage && tracker)
+                tracker.update(usage);
+            if (stepNumber >= MAX_STEPS)
+                maxStepsReached = true;
+            if (checkBudget())
+                budgetController.abort();
+        },
+        onError({ error }) {
+            log("warn", `step failed (will retry): ${String(error)}`);
         },
-        onError() { },
     });
-    Promise.resolve(result.usage).catch(() => { });
     let rawText = "";
     let assistantText = "";
     const md = new MarkdownRenderer();
@@ -384,13 +306,42 @@ export async function runOnce(messages, instructions, modelId, abortSignal, call
     const emitThinking = (t) => {
         if (!t)
             return;
-        if (callbacks?.onThinkingDelta)
-            callbacks.onThinkingDelta(t);
+        if (cbs.onThinkingDelta)
+            cbs.onThinkingDelta(t);
         else
             writeThinkingDelta(t);
     };
+    const emitDisplay = (delta) => {
+        if (cbs.onAssistantDisplayDelta) {
+            cbs.onAssistantDisplayDelta(delta);
+            return;
+        }
+        const formatted = md.write(delta);
+        if (formatted)
+            process.stdout.write(formatted);
+    };
+    const flushSplit = () => {
+        const out = thinkingSplit.flush();
+        emitThinking(out.thinking);
+        if (out.display) {
+            rawText += out.display;
+            assistantText += out.display;
+            emitDisplay(out.display);
+        }
+    };
+    const flushOutput = () => {
+        flushSplit();
+        if (!callbacks) {
+            const flushed = md.flush();
+            if (flushed)
+                process.stdout.write(flushed);
+            if (rawText.trim())
+                console.log();
+        }
+        rawText = "";
+    };
     try {
-        for await (const event of result.fullStream) {
+        streamLoop: for await (const event of result.fullStream) {
             switch (event.type) {
                 case "text-delta": {
                     const { display, thinking } = thinkingSplit.feed(event.text);
@@ -398,114 +349,65 @@ export async function runOnce(messages, instructions, modelId, abortSignal, call
                     if (display) {
                         rawText += display;
                         assistantText += display;
-                        if (callbacks?.onAssistantDisplayDelta)
-                            callbacks.onAssistantDisplayDelta(display);
-                        else {
-                            const formatted = md.write(display);
-                            if (formatted)
-                                process.stdout.write(formatted);
-                        }
+                        emitDisplay(display);
                     }
                     break;
                 }
                 case "tool-call": {
-                    // Doom loop detection
+                    toolCalls.push({ toolCallId: event.toolCallId, toolName: event.toolName, input: event.input });
                     if (doomLoop.record(event.toolName, event.input)) {
-                        const warning = `\x1b[33m⚠ Doom loop detected: "${event.toolName}" called ${3} times with same args. Breaking loop.\x1b[0m`;
-                        if (callbacks?.onStreamError)
-                            callbacks.onStreamError(warning);
-                        else
-                            console.log(`\n${warning}`);
                         hasError = true;
-                        break;
-                    }
-                    const splitFlush = thinkingSplit.flush();
-                    emitThinking(splitFlush.thinking);
-                    if (splitFlush.display) {
-                        rawText += splitFlush.display;
-                        assistantText += splitFlush.display;
-                        if (callbacks?.onAssistantDisplayDelta)
-                            callbacks.onAssistantDisplayDelta(splitFlush.display);
-                        else {
-                            const extra = md.write(splitFlush.display);
-                            if (extra)
-                                process.stdout.write(extra);
-                        }
-                    }
-                    if (!callbacks) {
-                        const flushed = md.flush();
-                        if (flushed)
-                            process.stdout.write(flushed);
-                        if (rawText.trim())
-                            console.log();
+                        const warning = `Doom loop detected: "${event.toolName}" called 3 times with same args. Breaking loop.`;
+                        if (cbs.onStreamError)
+                            cbs.onStreamError(warning);
+                        else
+                            console.log(`\n\x1b[33m⚠ ${warning}\x1b[0m`);
+                        flushOutput();
+                        break streamLoop;
                     }
-                    rawText = "";
-                    if (callbacks?.onToolCall)
-                        callbacks.onToolCall(event.toolName, event.input);
+                    logToolCall(event.toolName, event.input);
+                    flushOutput();
+                    if (cbs.onToolCall)
+                        cbs.onToolCall(event.toolName, event.input, event.toolCallId);
                     else
                         printToolCall(event.toolName, event.input);
                     break;
                 }
                 case "tool-result":
-                    if (callbacks?.onToolResult)
-                        callbacks.onToolResult(event.toolName, event.output);
+                case "tool-error": {
+                    const isError = event.type === "tool-error";
+                    const output = isError ? event.error : event.output;
+                    const displayed = isError ? `Error: ${event.error}` : event.output;
+                    toolResults.push({ toolCallId: event.toolCallId, toolName: event.toolName, output });
+                    logToolResult(event.toolName, displayed);
+                    if (cbs.onToolResult)
+                        cbs.onToolResult(event.toolName, displayed, { toolCallId: event.toolCallId, isError });
                     else
-                        printToolResult(event.toolName, event.output);
+                        printToolResult(event.toolName, displayed, isError);
                     break;
+                }
                 case "error":
                     hasError = true;
                     const errorMsg = String(event.error);
-                    if (callbacks?.onStreamError) {
-                        callbacks.onStreamError(errorMsg);
-                    }
-                    else if (errorMsg.includes("Forbidden") || errorMsg.includes("Unauthorized") || errorMsg.includes("API key")) {
-                        console.error(`\x1b[31mAuthentication error: Check your API key.\x1b[0m`);
+                    log("error", `stream error: ${errorMsg}`);
+                    if (cbs.onStreamError) {
+                        cbs.onStreamError(errorMsg);
                     }
                     else {
-                        console.error(`\x1b[31mError: ${errorMsg}\x1b[0m`);
+                        console.error(`\x1b[31m${formatErrorMessage(errorMsg)}\x1b[0m`);
                     }
                     break;
-                case "finish":
-                    break;
-            }
-        }
-        const splitEnd = thinkingSplit.flush();
-        emitThinking(splitEnd.thinking);
-        if (splitEnd.display) {
-            rawText += splitEnd.display;
-            assistantText += splitEnd.display;
-            if (callbacks?.onAssistantDisplayDelta)
-                callbacks.onAssistantDisplayDelta(splitEnd.display);
-            else {
-                const tail = md.write(splitEnd.display);
-                if (tail)
-                    process.stdout.write(tail);
             }
         }
-        if (!callbacks) {
-            const remaining = md.flush();
-            if (remaining)
-                process.stdout.write(remaining);
-            if (rawText.trim())
-                console.log();
-        }
-        const cleanedAssistant = stripThinkingFromAssistantText(assistantText);
-        if (cleanedAssistant.trim()) {
-            messages.push({ role: "assistant", content: cleanedAssistant });
-        }
-        let usage;
-        try {
-            usage = await result.usage;
-        }
-        catch {
-            usage = undefined;
+        flushOutput();
+        pushTurn(messages, assistantText, toolCalls, toolResults);
+        const usage = await safeUsage(result);
+        if (maxStepsReached && !callbacks) {
+            console.log(`\x1b[33m⚠ Reached the ${MAX_STEPS}-step limit for this turn. Send a follow-up message to continue.\x1b[0m`);
         }
-        // Update token tracker with real usage from API
-        if (usage && tracker) {
-            tracker.update(usage);
-        }
-        if (callbacks?.onRunFinish) {
-            callbacks.onRunFinish({ stepCount, usage, hasError, aborted: false });
+        log("info", `run end steps=${stepCount} tokens_in=${usage?.inputTokens ?? 0} tokens_out=${usage?.outputTokens ?? 0}`);
+        if (cbs.onRunFinish) {
+            cbs.onRunFinish({ stepCount, usage, hasError, aborted: false, maxStepsReached, budgetExceeded });
         }
         else {
             if (hasError) {
@@ -513,68 +415,51 @@ export async function runOnce(messages, instructions, modelId, abortSignal, call
                 return;
             }
             printDivider();
-            const { getContextWindow } = await import("./context-window.js");
             const ctxWindow = await getContextWindow(modelId);
             printDone(stepCount, usage, ctxWindow);
+            if (budgetExceeded)
+                console.log(`\x1b[33m⚠ 已达到预算上限 ($${budgetLimit})，运行已中断\x1b[0m`);
         }
     }
     catch (err) {
         if (!callbacks && rawText.trim())
             console.log();
-        if (err.name === "AbortError" || abortSignal?.aborted) {
-            const splitAbort = thinkingSplit.flush();
-            emitThinking(splitAbort.thinking);
-            if (splitAbort.display) {
-                assistantText += splitAbort.display;
-                if (callbacks?.onAssistantDisplayDelta)
-                    callbacks.onAssistantDisplayDelta(splitAbort.display);
-                else {
-                    const w = md.write(splitAbort.display);
-                    if (w)
-                        process.stdout.write(w);
-                }
-            }
-            if (!callbacks)
-                process.stdout.write(md.flush());
-            const cleaned = stripThinkingFromAssistantText(assistantText);
-            if (cleaned.trim()) {
-                messages.push({ role: "assistant", content: cleaned });
-            }
-            let usage;
-            try {
-                usage = await result.usage;
-            }
-            catch {
-                usage = undefined;
-            }
-            callbacks?.onRunFinish?.({ stepCount, usage, hasError: false, aborted: true });
+        const aborted = abortSignal?.aborted || (err instanceof Error && err.name === "AbortError");
+        flushSplit();
+        if (!callbacks)
+            process.stdout.write(md.flush());
+        pushTurn(messages, assistantText, toolCalls, toolResults);
+        const usage = await safeUsage(result);
+        if (aborted) {
+            if (budgetExceeded && !callbacks)
+                console.log(`\x1b[33m⚠ 已达到预算上限 ($${budgetLimit})，运行已中断\x1b[0m`);
+            cbs.onRunFinish?.({ stepCount, usage, hasError, aborted: true, maxStepsReached, budgetExceeded });
             return;
         }
         if (!callbacks)
             printDivider();
-        const msg = err.message ?? String(err);
-        if (callbacks?.onStreamError) {
-            callbacks.onStreamError(msg);
-        }
-        else if (msg.includes("API key") || msg.includes("Unauthorized") || msg.includes("Forbidden")) {
-            console.error(`\x1b[31mAuthentication error: Check your API key.\x1b[0m`);
+        const msg = err instanceof Error ? err.message : String(err);
+        log("error", msg);
+        const display = formatErrorMessage(msg);
+        if (cbs.onStreamError) {
+            cbs.onStreamError(msg);
         }
-        else if (msg.includes("429") || msg.includes("rate limit") || msg.includes("Rate limit")) {
-            console.error(`\x1b[31mRate limited after retries. Please wait and try again.\x1b[0m`);
-        }
-        else if (msg.includes("timeout") || msg.includes("ETIMEDOUT") || msg.includes("ECONNRESET")) {
-            console.error(`\x1b[31mNetwork error (retries exhausted): ${msg}\x1b[0m`);
+        else if (display !== msg) {
+            console.error(`\x1b[31m${display}\x1b[0m`);
         }
         else {
             console.error(`\x1b[31mError: ${msg}\x1b[0m`);
         }
-        let usage;
-        try {
-            usage = await result.usage;
-        }
-        catch {
-            usage = undefined;
-        }
-        callbacks?.onRunFinish?.({ stepCount, usage, hasError: true, aborted: false });
+        cbs.onRunFinish?.({ stepCount, usage, hasError: true, aborted: false, maxStepsReached, budgetExceeded });
+    }
+    finally {
+        abortSignal?.removeEventListener("abort", forwardAbort);
     }
 }
+export async function runOnce(messages, instructions, modelId, abortSignal, callbacks, tracker, options) {
+    await runOnceCore(messages, buildSystemPrompt(instructions), modelId, abortSignal, callbacks, tracker, "chat", options);
+}
+/** runOnce variant that accepts a pre-built system prompt (for code mode) */
+export async function runOnceWithSystem(messages, systemPrompt, modelId, abortSignal, callbacks, tracker, options) {
+    await runOnceCore(messages, systemPrompt, modelId, abortSignal, callbacks, tracker, "code", options);
+}