min-agent 0.2.1 → 0.4.0

package/dist/agent.js

@@ -1,31 +1,93 @@
-import { streamText, stepCountIs } from "ai";
-import { readFileSync, existsSync } from "fs";
+import { streamText, stepCountIs, } from "ai";
+import { readFileSync, existsSync, statSync } from "fs";
 import path from "path";
 import { resolveModel } from "./provider.js";
-import { createChatTools, createCodeTools } from "./tools/index.js";
-import { initMcp, shutdownMcp, getMcpTools } from "./mcp.js";
-import { discoverSkills, getSkillsTool, getSkillsSystemPrompt, getSkills } from "./skills.js";
+import { isProviderStallError, describeError } from "./fetch-timeout.js";
+import { getEffectiveConfig, getActiveProvider } from "./config.js";
+import { getModelPrice, estimateCost } from "./pricing.js";
+import { createTools } from "./tools/index.js";
+import { scanProject, buildCodeSystemPrompt } from "./code-mode.js";
+import { initMcp, shutdownMcp, getMcpTools, getMcpCatalogTools, getMcpReadOnlyToolIds } from "./mcp.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";
-import { loadPluginTools } from "./plugins.js";
+import { needsCompaction, compactMessages, estimateTokens, estimateStringTokens, estimateOverheadTokens, TokenTracker, COMPACTION_RATIO, PRUNE_PRESSURE_RATIO, PRUNE_TARGET_RATIO, applyToolPrune, pruneToolOutputs, } from "./compaction.js";
+import { loadPluginTools, getPluginReadOnlyIds } from "./plugins.js";
 import { MarkdownRenderer } from "./markdown.js";
-import { DoomLoopDetector } from "./doom-loop.js";
+import { DoomLoopDetector, STEER_PROMPT, DELIVER_PROMPT, LOOP_HALT_MESSAGE, RESEARCH_STUB_RESULT, WEB_RESEARCH_TOOLS, } from "./doom-loop.js";
 import { ThinkingBodySplitter, stripThinkingFromAssistantText } from "./assistant-stream.js";
+import { XmlSearchSplitter } from "./xml-search.js";
 import { printHeader, printDivider, printToolCall, printToolResult, printDone } from "./output.js";
-const MAX_STEPS = 30;
-function dimStyle() {
-    if ("NO_COLOR" in process.env)
-        return { dim: "", reset: "" };
-    return { dim: "\x1b[90m", reset: "\x1b[0m" };
-}
+import { createTodoTool, captureGoal, copyTaskState, emptyTaskState, formatTaskStatePrompt, } from "./tools/todo.js";
+import { getContextWindowInfo } from "./context-window.js";
+import { log, logToolCall, logToolResult, startRunLog, nextRunPass, endRunLog } from "./logger.js";
+import { markSyntheticMessage, isSyntheticMessage } from "./synthetic.js";
+import { runWithInstructionTracker, resetActiveInstructionTracker } from "./instructions.js";
+const UNBOUNDED_STEP_CAP = 100_000;
+const DEFAULT_MAX_CONTINUES = 40;
+/** Attempts (including the first) allowed when the provider answers with nothing at all. */
+const DEFAULT_MAX_EMPTY_ATTEMPTS = 4;
+const EMPTY_RETRY_BASE_DELAY_MS = 1000;
+const EMPTY_RETRY_MAX_DELAY_MS = 8000;
+/** Wall-clock budget for one turn before the model is asked to wrap up. */
+const DEFAULT_TURN_TIME_LIMIT_MS = 20 * 60 * 1000;
+/** Tool steps in one turn before the model is asked to wrap up. */
+const DEFAULT_SOFT_STEP_LIMIT = 120;
+const KEEP_RECENT_STEPS_BEFORE_PRUNE = 4;
+const CONTINUE_PROMPT = "Continue the task from where you left off. Do not wait for another user message. If the work is complete, give a brief summary and stop.";
+const WRAP_UP_PROMPT = "You are out of time budget for this turn. Stop starting new work: finish or save what is already in progress, then reply with a short summary of what is done, what is not, and the exact next step. Do not call more tools than needed to leave things in a consistent state.";
+/** Exported for tests / callers that want to recognise the injected wrap-up turn. */
+export const WRAP_UP_PROMPT_TEXT = WRAP_UP_PROMPT;
+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 resolveMaxSteps(raw) {
+    if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 1) {
+        return { cap: UNBOUNDED_STEP_CAP, bounded: false };
+    }
+    return { cap: Math.floor(raw), bounded: true };
+}
+/**
+ * Backoff before re-sending a request the provider answered with an empty
+ * stream. The first retry is immediate (most empty replies are one-off), later
+ * ones back off so a stalling gateway is not hammered.
+ */
+export function emptyRetryDelay(attempt, baseMs = EMPTY_RETRY_BASE_DELAY_MS) {
+    if (attempt <= 1 || baseMs <= 0)
+        return 0;
+    return Math.min(EMPTY_RETRY_MAX_DELAY_MS, baseMs * 2 ** (attempt - 2));
+}
+function sleep(ms) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** User-facing note when the provider kept answering with an empty stream. */
+export function emptyResponseMessage(attempts) {
+    return `模型连续 ${attempts} 次返回空响应（provider 可能超时或被限流），本轮已停止。发送消息可重试`;
+}
+/** User-facing note when a turn hit its time / step budget. */
+export const WRAP_UP_MESSAGE = "本轮已达时间或步数预算，已让模型收尾并停止。发送消息可继续";
+function resolveLimit(...values) {
+    for (const value of values) {
+        if (typeof value === "number" && Number.isFinite(value) && value >= 0)
+            return value;
+    }
+    return undefined;
+}
 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,547 +96,1233 @@ 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}`);
-}
-function buildSystemPrompt(instructions) {
-    const parts = [
-        `You are a helpful coding agent. You can read files, write files, run shell commands, search the web, and search the codebase to help the user with software engineering tasks.`,
-        "",
-        "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.",
-        "",
-        `Working directory: ${process.cwd()}`,
-        `Platform: ${process.platform}`,
-        `Date: ${new Date().toDateString()}`,
-        "",
-        `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");
+    process.stderr.write(`${DIM_STYLE.dim}${text}${DIM_STYLE.reset}`);
 }
-/** 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, resumeSessionId) {
     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();
-}
-/** 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`);
+    try {
+        discoverSkills();
+        const instructions = await loadInstructions();
+        const { loadExecHistory, saveSession } = await import("./sessions.js");
+        const history = loadExecHistory(resumeSessionId);
+        if (!history.ok) {
+            console.error(history.error);
+            return true;
         }
+        printInitReady();
+        console.log(`\x1b[36m> ${message}\x1b[0m\n`);
+        const content = await buildUserContent(message, imagePaths);
+        const messages = [...history.messages, { role: "user", content }];
+        const tracker = new TokenTracker();
+        const taskState = emptyTaskState();
+        if (history.taskState)
+            copyTaskState(history.taskState, taskState);
+        // Persist as the run progresses so a crash keeps the work done so far.
+        const { createSaveThrottle } = await import("./save-throttle.js");
+        let sessionId = history.sessionId;
+        const persist = () => {
+            try {
+                sessionId = saveSession(messages, sessionId, undefined, undefined, taskState);
+            }
+            catch { }
+        };
+        const saveThrottle = createSaveThrottle(persist);
+        const { hasError } = await runOnce(messages, instructions, modelId, undefined, undefined, tracker, {
+            providerName,
+            taskState,
+            onStepPersist: () => saveThrottle.request(),
+        });
+        saveThrottle.cancel();
+        persist();
+        if (sessionId)
+            console.log(`\nResume with: min-agent exec --resume ${sessionId}`);
+        return hasError;
+    }
+    finally {
+        await shutdownMcp();
+    }
+}
+/**
+ * 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 = safeText(r.output);
+        messages.push({
+            role: "tool",
+            content: [
+                {
+                    type: "tool-result",
+                    toolCallId: r.toolCallId,
+                    toolName: r.toolName,
+                    output: { type: "text", value: text },
+                },
+            ],
+        });
     }
-    const builtinTools = createCodeTools();
+}
+/**
+ * Tools that stay constant for a whole run: everything except the skill tool,
+ * which is re-bound per iteration (see buildIterationPrompts). Building these
+ * once per run avoids re-reading plugin manifests and re-wrapping MCP tools on
+ * every continue.
+ */
+async function buildRunTools(modelId, abortSignal, planMode, tracker, taskState, subAgent) {
+    const builtinTools = createTools();
+    builtinTools.todo = createTodoTool({ store: taskState });
     const mcpTools = getMcpTools();
+    const catalogTools = getMcpCatalogTools();
     const memoryTools = getMemoryTools();
     const pluginTools = await loadPluginTools();
-    const { createTaskTool } = await import("./tools/task.js");
+    const allTools = {
+        ...builtinTools,
+        ...memoryTools,
+        ...pluginTools,
+        ...mcpTools,
+        ...catalogTools,
+    };
+    const onUsage = tracker ? (usage) => tracker.add(usage) : undefined;
     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,
-        tools: allTools,
-        stopWhen: stepCountIs(MAX_STEPS),
-        maxRetries: 3,
-        abortSignal,
-        onStepFinish() { stepCount++; },
-        onError() { },
+    allTools.explore = createExploreTool(modelId, abortSignal, onUsage, { shouldStop: subAgent.shouldStop });
+    const { createTaskTool } = await import("./tools/task.js");
+    // Sub-agents share the parent's loop guard and budget so they cannot restart
+    // the research allowance or run past the cost ceiling.
+    allTools.task = createTaskTool(modelId, abortSignal, onUsage, {
+        loopGuard: subAgent.loopGuard,
+        shouldStop: subAgent.shouldStop,
     });
-    Promise.resolve(result.usage).catch(() => { });
-    let rawText = "";
-    let assistantText = "";
-    const md = new MarkdownRenderer();
-    const thinkingSplit = new ThinkingBodySplitter();
+    if (planMode) {
+        for (const name of ["bash", "write", "edit", "apply_patch"])
+            delete allTools[name];
+        const mcpReadOnly = getMcpReadOnlyToolIds();
+        for (const id of Object.keys(mcpTools)) {
+            if (!mcpReadOnly.has(id))
+                delete allTools[id];
+        }
+        const pluginReadOnly = getPluginReadOnlyIds();
+        for (const id of Object.keys(pluginTools)) {
+            if (!pluginReadOnly.has(id))
+                delete allTools[id];
+        }
+    }
+    return allTools;
+}
+function buildIterationPrompts(allTools, messages, taskState, loopGuard) {
+    const skillsPrompt = attachSkills(allTools, collectLoadedSkillNames(messages));
+    return {
+        stable: [skillsPrompt].filter((s) => s.length > 0),
+        volatile: [getMemorySystemPrompt(), formatTaskStatePrompt(taskState), loopGuard.promptHint()].filter((s) => s.length > 0),
+    };
+}
+/** Ephemeral per-request message carrying the volatile prompt sections. */
+export const SESSION_STATE_HEADER = "## Session state (current, not part of the conversation)";
+function sessionStateMessage(volatile) {
+    if (volatile.length === 0)
+        return null;
+    return { role: "system", content: [SESSION_STATE_HEADER, ...volatile].join("\n\n") };
+}
+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;
+}
+function safeText(value) {
+    if (typeof value === "string")
+        return value;
     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;
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function isContextOverflowError(msg) {
+    return /context[\s_-]*(length|window|size)|context_length_exceeded|maximum context|too many tokens|prompt (is )?too long|reduce the (prompt )?length|token limit exceeded/i.test(msg);
+}
+function invokeCallback(fn, ...args) {
+    if (!fn)
+        return;
+    try {
+        fn(...args);
+    }
+    catch (err) {
+        log("error", `callback failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+const INTERRUPTED_TOOL_RESULT = "Error: tool call was interrupted before a result was returned.";
+function pairToolTurn(calls, results) {
+    const resultIds = new Set(results.map((r) => r.toolCallId));
+    const callIds = new Set(calls.map((c) => c.toolCallId));
+    const keptResults = results.filter((r) => callIds.has(r.toolCallId));
+    const synthetics = calls
+        .filter((c) => !resultIds.has(c.toolCallId))
+        .map((c) => ({
+        toolCallId: c.toolCallId,
+        toolName: c.toolName,
+        output: INTERRUPTED_TOOL_RESULT,
+    }));
+    return { calls, results: [...keptResults, ...synthetics] };
+}
+async function safeUsage(result) {
+    try {
+        return await result.usage;
+    }
+    catch {
+        return undefined;
+    }
+}
+function usageNonZero(usage) {
+    return (usage?.inputTokens ?? 0) > 0 || (usage?.outputTokens ?? 0) > 0;
+}
+function mergeUsage(a, b) {
+    if (!usageNonZero(b))
+        return a ?? b;
+    if (!usageNonZero(a))
+        return b;
+    const inputTokens = (a.inputTokens ?? 0) + (b.inputTokens ?? 0);
+    const outputTokens = (a.outputTokens ?? 0) + (b.outputTokens ?? 0);
+    return {
+        ...a,
+        ...b,
+        inputTokens,
+        outputTokens,
+        totalTokens: (a.totalTokens ?? 0) + (b.totalTokens ?? 0) || inputTokens + outputTokens,
+    };
+}
+function pickUsage(...candidates) {
+    const present = candidates.filter((u) => u != null);
+    if (present.length === 0)
+        return undefined;
+    const scored = present.filter(usageNonZero);
+    const pool = scored.length > 0 ? scored : present;
+    return pool.reduce((best, u) => {
+        const outDiff = (u.outputTokens ?? 0) - (best.outputTokens ?? 0);
+        if (outDiff !== 0)
+            return outDiff > 0 ? u : best;
+        return (u.inputTokens ?? 0) > (best.inputTokens ?? 0) ? u : best;
+    });
+}
+function injectUser(messages, text) {
+    const last = messages[messages.length - 1];
+    if (last && isSyntheticMessage(last) && last.role === "user") {
+        last.content = text;
+        return;
+    }
+    const continueMsg = { role: "user", content: text };
+    messages.push(continueMsg);
+    markSyntheticMessage(continueMsg);
+}
+function continuePromptFor(guard) {
+    if (guard.researchCapped)
+        return DELIVER_PROMPT;
+    if (guard.webResearchCount >= 6)
+        return STEER_PROMPT;
+    return CONTINUE_PROMPT;
+}
+function stubWebResearchTools(tools) {
+    for (const name of WEB_RESEARCH_TOOLS) {
+        const current = tools[name];
+        if (!current)
+            continue;
+        tools[name] = {
+            ...current,
+            execute: async () => RESEARCH_STUB_RESULT,
+        };
+    }
+}
+/**
+ * Drop the research tools for the rest of the turn. Removing them from the
+ * schema (instead of leaving a stub the model keeps calling) is what actually
+ * stops the model from burning steps on searches that cannot return anything.
+ */
+function removeWebResearchTools(tools) {
+    const removed = [];
+    for (const name of WEB_RESEARCH_TOOLS) {
+        if (!tools[name])
+            continue;
+        delete tools[name];
+        removed.push(name);
+    }
+    return removed;
+}
+async function applyCompaction(messages, model, tracker, cbs, callbacks, compactCfg, pruneOptions = {}) {
+    applyToolPrune(messages, pruneOptions);
+    try {
+        if (!(await needsCompaction(messages, tracker, compactCfg)))
+            return false;
+        if (cbs.onCompaction)
+            invokeCallback(cbs.onCompaction, "compacting_start");
+        else if (!callbacks)
+            console.log("\x1b[90m⟳ Compacting context...\x1b[0m");
+        const result = await compactMessages(messages, model, compactCfg);
+        if (!result.compacted)
+            return false;
+        if (result.usage && tracker)
+            tracker.add(result.usage);
+        messages.length = 0;
+        messages.push(...result.messages);
+        if (tracker)
+            tracker.resetContext();
+        resetActiveInstructionTracker();
+        if (cbs.onCompaction)
+            invokeCallback(cbs.onCompaction, `compacted_ok estimated_tokens=${estimateTokens(messages)}`);
+        else if (!callbacks)
+            console.log(`\x1b[90m  ✓ Compacted (${estimateTokens(messages)} tokens estimated)\x1b[0m`);
+        return true;
+    }
+    catch (err) {
+        log("warn", `compaction failed: ${err instanceof Error ? err.message : String(err)}`);
+        invokeCallback(cbs.onCompaction, "compacted_failed");
+        return false;
+    }
+}
+async function runOnceCore(messages, systemPrompt, modelId, abortSignal, callbacks, tracker, options) {
+    return runWithInstructionTracker(() => runOnceCoreLoop(messages, systemPrompt, modelId, abortSignal, callbacks, tracker, options));
+}
+async function runOnceCoreLoop(messages, systemPrompt, modelId, abortSignal, callbacks, tracker, options) {
+    const model = resolveModel(modelId, options?.providerName);
+    startRunLog();
+    log("info", `run start messages=${messages.length} model=${typeof model === "string" ? model : model.modelId}`);
+    const cbs = callbacks ?? {};
+    const cfg = getEffectiveConfig();
+    const sampling = cfg.sampling ?? {};
+    const temperature = options?.temperature ?? sampling.temperature;
+    const maxTokens = options?.maxTokens ?? sampling.maxTokens;
+    const topP = options?.topP ?? sampling.topP;
+    const taskState = options?.taskState ?? emptyTaskState();
+    captureGoal(taskState, messages);
+    const { cap: maxSteps, bounded: stepBounded } = resolveMaxSteps(options?.maxSteps ?? cfg.agent?.maxSteps);
+    const maxContinues = options?.maxContinues ?? cfg.agent?.maxContinues ?? DEFAULT_MAX_CONTINUES;
+    const autoContinue = options?.autoContinue ?? cfg.agent?.autoContinue ?? cfg.compaction?.autoContinue ?? true;
+    const maxEmptyAttempts = Math.max(1, options?.maxEmptyAttempts ?? cfg.agent?.maxEmptyAttempts ?? DEFAULT_MAX_EMPTY_ATTEMPTS);
+    const emptyRetryDelayMs = options?.emptyRetryDelayMs ?? cfg.agent?.emptyRetryDelayMs ?? EMPTY_RETRY_BASE_DELAY_MS;
+    const turnTimeLimitMs = resolveLimit(options?.turnTimeLimitMs, cfg.agent?.turnTimeLimitMs) ?? DEFAULT_TURN_TIME_LIMIT_MS;
+    const softStepLimit = resolveLimit(options?.softStepLimit, cfg.agent?.softStepLimit) ?? DEFAULT_SOFT_STEP_LIMIT;
+    const turnStartedAt = Date.now();
+    /** Time / step budget for the whole turn (0 disables either half). */
+    const overTurnBudget = (steps) => (turnTimeLimitMs > 0 && Date.now() - turnStartedAt >= turnTimeLimitMs) ||
+        (softStepLimit > 0 && steps >= softStepLimit);
+    const loopGuard = new DoomLoopDetector({
+        steerAfter: options?.researchSteerAfter ?? cfg.agent?.researchSteerAfter,
+        stopAfter: options?.researchStopAfter ?? cfg.agent?.researchStopAfter,
+        totalCap: options?.researchTotalCap ?? cfg.agent?.researchTotalCap,
+    });
+    /** Tokens spent on the system prompt + tool schemas of the current pass. */
+    const overhead = { tokens: 0 };
+    const compactCfg = {
+        abortSignal,
+        modelId,
+        taskGoal: taskState.goal || undefined,
+        get overheadTokens() {
+            return overhead.tokens;
+        },
+    };
+    const windowInfo = await getContextWindowInfo(modelId);
+    const ctxWindow = windowInfo.tokens;
+    const compactThreshold = ctxWindow * COMPACTION_RATIO;
+    /** Old tool payloads are only dropped once the context is actually filling up. */
+    const pruneBudget = () => ({
+        pressureTokens: ctxWindow * PRUNE_PRESSURE_RATIO,
+        targetTokens: ctxWindow * PRUNE_TARGET_RATIO,
+        overheadTokens: overhead.tokens,
+    });
+    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 ?? "");
+    }
+    let budgetExceeded = false;
+    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;
+    };
+    await applyCompaction(messages, model, tracker, cbs, callbacks, compactCfg, pruneBudget());
+    let totalSteps = 0;
+    let continues = 0;
+    let emptyAttempts = 0;
+    let wrapUpAsked = false;
+    let hasError = false;
+    let lastUsage;
+    let allowContextAbort = true;
+    const allTools = await buildRunTools(modelId, abortSignal, options?.planMode ?? false, tracker, taskState, {
+        loopGuard,
+        shouldStop: () => checkBudget() || overTurnBudget(totalSteps),
+    });
+    const finish = async (opts) => {
+        log("info", `run end steps=${totalSteps} continues=${continues} tokens_in=${lastUsage?.inputTokens ?? 0} tokens_out=${lastUsage?.outputTokens ?? 0}`);
+        endRunLog();
+        if (cbs.onRunFinish) {
+            try {
+                await cbs.onRunFinish({
+                    stepCount: totalSteps,
+                    usage: lastUsage,
+                    contextTokens: tracker?.lastInputTokens ?? 0,
+                    hasError,
+                    aborted: opts.aborted,
+                    maxStepsReached: opts.maxStepsReached,
+                    budgetExceeded,
+                    continues,
+                    incomplete: opts.incomplete ?? false,
+                    stopped: opts.stopped ?? false,
+                    emptyResponse: opts.emptyResponse ?? false,
+                    emptyAttempts,
+                    wrapUp: opts.wrapUp ?? false,
+                });
+            }
+            catch (err) {
+                log("error", `onRunFinish failed: ${err instanceof Error ? err.message : String(err)}`);
             }
+            return { hasError };
         }
-        const end = thinkingSplit.flush();
-        if (end.thinking) {
-            if (callbacks?.onThinkingDelta)
-                callbacks.onThinkingDelta(end.thinking);
-            else
-                writeThinkingDelta(end.thinking);
+        if (hasError) {
+            printDivider();
+            return { hasError };
         }
-        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);
-            }
+        printDivider();
+        printDone(totalSteps, lastUsage, ctxWindow, tracker?.lastInputTokens);
+        if (budgetExceeded)
+            console.log(`\x1b[33m⚠ 已达到预算上限 ($${budgetLimit})，运行已中断\x1b[0m`);
+        if (opts.stopped)
+            console.log(`\x1b[33m⚠ ${LOOP_HALT_MESSAGE}\x1b[0m`);
+        if (opts.emptyResponse) {
+            console.log(`\x1b[33m⚠ ${emptyResponseMessage(emptyAttempts)}\x1b[0m`);
         }
-        if (!api) {
-            const remaining = md.flush();
-            if (remaining)
-                process.stdout.write(remaining);
-            if (rawText.trim())
-                console.log();
+        else if (opts.wrapUp) {
+            console.log(`\x1b[33m⚠ ${WRAP_UP_MESSAGE}\x1b[0m`);
         }
-        const cleaned = stripThinkingFromAssistantText(assistantText);
-        if (cleaned.trim())
-            messages.push({ role: "assistant", content: cleaned });
-        let usage;
-        try {
-            usage = await result.usage;
+        else if (opts.maxStepsReached) {
+            console.log(`\x1b[33m⚠ 已达到自动续跑上限，发送消息继续\x1b[0m`);
         }
-        catch {
-            usage = undefined;
+        else if (opts.incomplete) {
+            console.log(`\x1b[33m⚠ 还没有完整回复，发送消息可继续\x1b[0m`);
         }
-        if (usage && tracker)
-            tracker.update(usage);
-        if (callbacks?.onRunFinish) {
-            callbacks.onRunFinish({ stepCount, usage, hasError, aborted: false });
+        return { hasError };
+    };
+    while (true) {
+        if (abortSignal?.aborted)
+            return finish({ aborted: true, maxStepsReached: false });
+        if (checkBudget())
+            return finish({ aborted: true, maxStepsReached: false });
+        let inner;
+        nextRunPass();
+        try {
+            inner = await runInnerStream({
+                messages,
+                systemPrompt,
+                model,
+                abortSignal,
+                callbacks,
+                cbs,
+                tracker,
+                taskState,
+                allTools,
+                maxSteps,
+                stepBounded,
+                temperature,
+                maxTokens,
+                topP,
+                checkBudget,
+                overTurnBudget: (stepsInPass) => overTurnBudget(totalSteps + stepsInPass),
+                pruneBudget,
+                overhead,
+                compactThreshold,
+                allowContextAbort,
+                loopGuard,
+                onStepPersist: options?.onStepPersist,
+            });
         }
-        else {
-            if (!hasError && usage) {
-                printDivider();
-                const { getContextWindow } = await import("./context-window.js");
-                const ctxWindow = await getContextWindow(modelId);
-                printDone(stepCount, usage, ctxWindow);
-            }
-            else {
-                printDivider();
-            }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            log("error", msg);
+            hasError = true;
+            if (cbs.onStreamError)
+                invokeCallback(cbs.onStreamError, msg);
+            else
+                console.error(`\x1b[31m${formatErrorMessage(msg)}\x1b[0m`);
+            return finish({ aborted: Boolean(abortSignal?.aborted), maxStepsReached: false });
         }
-    }
-    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;
+        totalSteps += inner.stepCount;
+        lastUsage = mergeUsage(lastUsage, inner.usage);
+        if (inner.hasError)
+            hasError = true;
+        if (inner.budgetExceeded)
+            budgetExceeded = true;
+        if (inner.userAborted)
+            return finish({ aborted: true, maxStepsReached: false });
+        if (inner.doomLoop)
+            return finish({ aborted: false, maxStepsReached: false, stopped: true });
+        if (inner.hasError && !inner.contextPressure && !inner.toolPressure) {
+            return finish({ aborted: false, maxStepsReached: false });
         }
-        if (callbacks?.onStreamError)
-            callbacks.onStreamError(err.message);
-        else {
-            printDivider();
-            console.error(`\x1b[31mError: ${err.message}\x1b[0m`);
+        if (budgetExceeded)
+            return finish({ aborted: true, maxStepsReached: false });
+        if (inner.toolPressure) {
+            applyToolPrune(messages, pruneBudget());
+            continue;
         }
-    }
-}
-export async function runOnce(messages, instructions, modelId, abortSignal, callbacks, tracker) {
-    const model = resolveModel(modelId);
-    const api = !!callbacks;
-    // Auto-compact if context is getting too large
-    if (needsCompaction(messages, tracker)) {
-        if (api) {
-            callbacks.onCompaction?.("compacting_start");
+        // The provider produced nothing at all (no text, no reasoning-backed reply,
+        // no tool call): a transport / gateway hiccup rather than model intent.
+        // Re-send the same request with backoff instead of nudging the model.
+        if (inner.emptyCompletion) {
+            emptyAttempts++;
+            if (emptyAttempts >= maxEmptyAttempts) {
+                log("warn", `empty response from provider ${emptyAttempts}x, ending run`);
+                return finish({ aborted: false, maxStepsReached: false, incomplete: true, emptyResponse: true });
+            }
+            continues++;
+            if (continues > maxContinues) {
+                return finish({ aborted: false, maxStepsReached: true, incomplete: true });
+            }
+            const delay = emptyRetryDelay(emptyAttempts, emptyRetryDelayMs);
+            log("warn", `empty response from provider, retry ${emptyAttempts}/${maxEmptyAttempts - 1} after ${delay}ms`);
+            if (cbs.onRetryNotice)
+                invokeCallback(cbs.onRetryNotice, {
+                    kind: "empty_response",
+                    attempt: emptyAttempts,
+                    maxAttempts: maxEmptyAttempts - 1,
+                    delayMs: delay,
+                });
+            else if (!callbacks)
+                console.log(`\x1b[90m⟳ 模型返回空响应，重试 ${emptyAttempts}/${maxEmptyAttempts - 1}…\x1b[0m`);
+            await sleep(delay);
+            continue;
         }
-        else {
-            console.log("\x1b[90m⟳ Compacting context...\x1b[0m");
+        const hitResearchLimit = inner.researchCap || inner.researchSteer;
+        const forceDeliver = !loopGuard.producedArtifact &&
+            (hitResearchLimit ||
+                (inner.lastStepHadTools && (loopGuard.researchCapped || (!autoContinue && loopGuard.webResearchCount > 0))));
+        const stalled = inner.lastStepHadTools || inner.xmlToolFollowUp || inner.providerStall;
+        const shouldKeepGoing = inner.xmlToolFollowUp ||
+            (autoContinue && (inner.contextPressure || inner.lastStepHadTools || inner.providerStall));
+        // A finished answer always wins: never override it with a budget notice.
+        if (!forceDeliver && !shouldKeepGoing) {
+            const capped = !autoContinue && inner.maxStepsReached && inner.lastStepHadTools;
+            if (capped && !callbacks) {
+                console.log(`\x1b[33m⚠ 本轮已达到步数上限（${maxSteps}），发送消息继续\x1b[0m`);
+            }
+            return finish({ aborted: false, maxStepsReached: capped, incomplete: stalled && !capped });
         }
-        const result = await compactMessages(messages, model);
-        if (result.compacted) {
-            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 });
+        // Out of time / steps for this turn: ask for a wrap-up once, then stop.
+        if (inner.wrapUp || overTurnBudget(totalSteps)) {
+            if (wrapUpAsked) {
+                log("warn", `turn budget spent after wrap-up (steps=${totalSteps})`);
+                return finish({ aborted: false, maxStepsReached: false, incomplete: true, wrapUp: true });
             }
-            if (tracker)
-                tracker.resetContext();
-            if (api) {
-                callbacks.onCompaction?.(`compacted_ok estimated_tokens=${estimateTokens(messages)}`);
+            wrapUpAsked = true;
+            continues++;
+            if (continues > maxContinues) {
+                return finish({ aborted: false, maxStepsReached: true, incomplete: true });
             }
-            else {
-                console.log(`\x1b[90m  ✓ Compacted (${estimateTokens(messages)} tokens estimated)\x1b[0m`);
+            log("info", `auto-continue reason=wrap_up steps=${totalSteps} elapsed=${Date.now() - turnStartedAt}ms`);
+            if (cbs.onRetryNotice)
+                invokeCallback(cbs.onRetryNotice, {
+                    kind: "wrap_up",
+                    attempt: 1,
+                    maxAttempts: 1,
+                    delayMs: 0,
+                });
+            else if (!callbacks)
+                console.log(`\x1b[90m⟳ 本轮预算用尽，正在收尾…\x1b[0m`);
+            await applyCompaction(messages, model, tracker, cbs, callbacks, compactCfg, pruneBudget());
+            injectUser(messages, WRAP_UP_PROMPT);
+            continue;
+        }
+        if (forceDeliver) {
+            continues++;
+            if (continues > maxContinues) {
+                return finish({ aborted: false, maxStepsReached: true, incomplete: true });
             }
+            removeWebResearchTools(allTools);
+            loopGuard.markCapped();
+            log("info", `auto-continue reason=${hitResearchLimit ? (inner.researchCap ? "research_cap" : "research_steer") : "awaiting_deliverable"}`);
+            await applyCompaction(messages, model, tracker, cbs, callbacks, compactCfg, pruneBudget());
+            injectUser(messages, DELIVER_PROMPT);
+            continue;
+        }
+        continues++;
+        if (continues > maxContinues) {
+            return finish({ aborted: false, maxStepsReached: true, incomplete: stalled });
         }
+        log("info", `auto-continue reason=${inner.xmlToolFollowUp ? "xml_search" : inner.contextPressure ? "context" : inner.providerStall ? "provider_stall" : "tools_without_reply"}`);
+        const compacted = await applyCompaction(messages, model, tracker, cbs, callbacks, { ...compactCfg, force: inner.contextPressure }, pruneBudget());
+        if (inner.contextPressure && !compacted)
+            allowContextAbort = false;
+        injectUser(messages, continuePromptFor(loopGuard));
     }
-    // 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;
+}
+/**
+ * Accumulates the current assistant turn (text + tool call/result pairs) and
+ * flushes it into the shared message history at step boundaries.
+ */
+class TurnAssembler {
+    messages;
+    onFlush;
+    stepText = "";
+    toolCalls = [];
+    toolResults = [];
+    innerSteps = 0;
+    lastStepHadTools = false;
+    hadTools = false;
+    hadAssistantText = false;
+    /** Estimated model output of this pass (assistant text + tool-call arguments). */
+    producedTokens = 0;
+    constructor(messages, onFlush) {
+        this.messages = messages;
+        this.onFlush = onFlush;
     }
-    if (skills.length > 0) {
-        allTools["skill"] = getSkillsTool();
+    get pendingResults() {
+        return this.toolResults.length;
     }
-    let stepCount = 0;
-    let hasError = false;
-    const doomLoop = new DoomLoopDetector();
-    const result = streamText({
-        model,
-        system: buildSystemPrompt(instructions),
-        messages,
-        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();
-    const emitThinking = (t) => {
+    get hasUnpairedCalls() {
+        const resultIds = new Set(this.toolResults.map((r) => r.toolCallId));
+        return this.toolCalls.some((c) => !resultIds.has(c.toolCallId));
+    }
+    appendText(display) {
+        this.stepText += display;
+    }
+    recordCall(call) {
+        this.toolCalls.push(call);
+    }
+    recordResult(result) {
+        this.toolResults.push(result);
+    }
+    /** Placeholder id for tool-call events missing one (kept stable per step). */
+    nextMissingCallId() {
+        return `missing-${this.innerSteps}-${this.toolCalls.length}`;
+    }
+    flushStep() {
+        const hasTools = this.toolCalls.length > 0 || this.toolResults.length > 0;
+        const hasText = Boolean(this.stepText.trim());
+        if (!hasText && !hasTools)
+            return;
+        this.lastStepHadTools = hasTools;
+        if (hasTools)
+            this.hadTools = true;
+        if (hasText)
+            this.hadAssistantText = true;
+        this.producedTokens += estimateStringTokens(this.stepText);
+        for (const call of this.toolCalls) {
+            this.producedTokens += estimateStringTokens(safeText(call.input));
+        }
+        const paired = pairToolTurn(this.toolCalls, this.toolResults);
+        pushTurn(this.messages, this.stepText, paired.calls, paired.results);
+        this.innerSteps++;
+        this.stepText = "";
+        this.toolCalls = [];
+        this.toolResults = [];
+        this.onFlush?.({ steps: this.innerSteps });
+    }
+}
+/**
+ * Splits thinking and inline <web_search> dumps from displayable text, then
+ * fans both out to the callbacks (HTTP/TUI) or the TTY (single-shot).
+ */
+class StreamRenderer {
+    cbs;
+    interactive;
+    md = new MarkdownRenderer();
+    thinkingSplit = new ThinkingBodySplitter();
+    xmlSplit = new XmlSearchSplitter();
+    rawText = "";
+    constructor(cbs, interactive) {
+        this.cbs = cbs;
+        this.interactive = interactive;
+    }
+    emitThinking(t) {
         if (!t)
             return;
-        if (callbacks?.onThinkingDelta)
-            callbacks.onThinkingDelta(t);
+        if (this.cbs.onThinkingDelta)
+            invokeCallback(this.cbs.onThinkingDelta, t);
         else
             writeThinkingDelta(t);
-    };
-    try {
-        for await (const event of result.fullStream) {
-            switch (event.type) {
-                case "text-delta": {
-                    const { display, thinking } = thinkingSplit.feed(event.text);
-                    emitThinking(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": {
-                    // Doom loop detection
-                    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();
-                    }
-                    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;
-                    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`);
-                    }
-                    else {
-                        console.error(`\x1b[31mError: ${errorMsg}\x1b[0m`);
-                    }
-                    break;
-                case "finish":
-                    break;
+    }
+    emitDisplay(delta) {
+        try {
+            if (this.cbs.onAssistantDisplayDelta) {
+                this.cbs.onAssistantDisplayDelta(delta);
+                return;
             }
+            const formatted = this.md.write(delta);
+            if (formatted)
+                process.stdout.write(formatted);
         }
-        const splitEnd = thinkingSplit.flush();
-        emitThinking(splitEnd.thinking);
-        if (splitEnd.display) {
-            rawText += splitEnd.display;
-            assistantText += splitEnd.display;
-            if (callbacks?.onAssistantDisplayDelta)
-                callbacks.onAssistantDisplayDelta(splitEnd.display);
+        catch (err) {
+            log("error", `display callback failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    feedReasoning(text) {
+        this.emitThinking(text);
+    }
+    mirror(display) {
+        if (!display)
+            return;
+        this.rawText += display;
+        this.emitDisplay(display);
+    }
+    pipeXml(display, flush) {
+        const slices = display ? this.xmlSplit.feed(display) : [];
+        if (flush)
+            slices.push(...this.xmlSplit.flush());
+        const out = [];
+        for (const sl of slices) {
+            if (sl.type === "display") {
+                if (!sl.text)
+                    continue;
+                this.mirror(sl.text);
+                out.push(sl);
+            }
             else {
-                const tail = md.write(splitEnd.display);
-                if (tail)
-                    process.stdout.write(tail);
+                out.push(sl);
             }
         }
-        if (!callbacks) {
-            const remaining = md.flush();
-            if (remaining)
-                process.stdout.write(remaining);
-            if (rawText.trim())
+        return out;
+    }
+    feedText(text) {
+        const { display, thinking } = this.thinkingSplit.feed(text);
+        this.emitThinking(thinking);
+        return this.pipeXml(display, false);
+    }
+    flushSplitText() {
+        const out = this.thinkingSplit.flush();
+        this.emitThinking(out.thinking);
+        return this.pipeXml(out.display, true);
+    }
+    flushMarkdown() {
+        if (this.interactive) {
+            try {
+                const flushed = this.md.flush();
+                if (flushed)
+                    process.stdout.write(flushed);
+            }
+            catch { }
+            if (this.rawText.trim())
                 console.log();
         }
-        const cleanedAssistant = stripThinkingFromAssistantText(assistantText);
-        if (cleanedAssistant.trim()) {
-            messages.push({ role: "assistant", content: cleanedAssistant });
+        this.rawText = "";
+    }
+    flushOutput() {
+        const slices = this.flushSplitText();
+        this.flushMarkdown();
+        return slices;
+    }
+    flushOnError() {
+        if (this.interactive && this.rawText.trim())
+            console.log();
+        const slices = this.flushSplitText();
+        if (this.interactive) {
+            try {
+                process.stdout.write(this.md.flush());
+            }
+            catch { }
         }
-        let usage;
-        try {
-            usage = await result.usage;
+        this.rawText = "";
+        return slices;
+    }
+}
+/**
+ * Explicit state machine for one streaming pass: owns the abort controller,
+ * stop flags, doom-loop detector, turn assembly and rendering, and reacts to
+ * each fullStream event via handleEvent (returns true to stop the loop).
+ */
+class InnerStreamMachine {
+    params;
+    stop = {
+        budget: false,
+        doom: false,
+        steer: false,
+        cap: false,
+        context: false,
+        tools: false,
+        stall: false,
+        wrapUp: false,
+    };
+    hasError = false;
+    assembler;
+    renderer;
+    usageSteps = 0;
+    innerController = new AbortController();
+    forwardAbort = () => this.innerController.abort();
+    xmlSearchRecovered = false;
+    answerAfterXml = false;
+    pendingLoop = null;
+    stepFinishSeen = false;
+    stepUsage;
+    totalUsage;
+    constructor(params) {
+        this.params = params;
+        this.assembler = new TurnAssembler(params.messages, (info) => {
+            if (params.onStepPersist)
+                invokeCallback(params.onStepPersist, info);
+        });
+        this.renderer = new StreamRenderer(params.cbs, !params.callbacks);
+    }
+    get signal() {
+        return this.innerController.signal;
+    }
+    attachAbort() {
+        this.params.abortSignal?.addEventListener("abort", this.forwardAbort, { once: true });
+    }
+    detachAbort() {
+        this.params.abortSignal?.removeEventListener("abort", this.forwardAbort);
+    }
+    /** streamText onStepFinish: budget / context-pressure / tool-output pruning checks. */
+    onStepFinish(usage) {
+        const { tracker, checkBudget, allowContextAbort, compactThreshold, messages, overTurnBudget } = this.params;
+        if (usage && tracker)
+            tracker.update(usage);
+        this.usageSteps++;
+        if (checkBudget()) {
+            this.stop.budget = true;
+            this.innerController.abort();
         }
-        catch {
-            usage = undefined;
+        else if (overTurnBudget(this.assembler.innerSteps)) {
+            // Do not let one pass run past the turn budget: stop here so the outer
+            // loop can ask for a wrap-up.
+            this.stop.wrapUp = true;
+            this.innerController.abort();
         }
-        // Update token tracker with real usage from API
-        if (usage && tracker) {
-            tracker.update(usage);
+        else if (allowContextAbort && this.usageSteps >= 2 && tracker && tracker.lastInputTokens > compactThreshold) {
+            this.stop.context = true;
+            this.innerController.abort();
         }
-        if (callbacks?.onRunFinish) {
-            callbacks.onRunFinish({ stepCount, usage, hasError, aborted: false });
+        else if (this.usageSteps >= KEEP_RECENT_STEPS_BEFORE_PRUNE &&
+            pruneToolOutputs(messages, this.params.pruneBudget()) !== messages) {
+            this.stop.tools = true;
+            this.innerController.abort();
         }
-        else {
-            if (hasError) {
-                printDivider();
-                return;
+    }
+    noteStepUsage(usage) {
+        this.stepUsage = mergeUsage(this.stepUsage, usage);
+    }
+    resolvedUsage(fromResult) {
+        const reported = pickUsage(fromResult, this.totalUsage, this.stepUsage);
+        if (usageNonZero(reported))
+            return reported;
+        // We cut the stream ourselves (research steer, context pressure, stall…),
+        // so the provider never sent its usage chunk. Estimate instead of dropping
+        // the pass from cost / context accounting entirely.
+        const estimated = this.estimateUsage();
+        if (!estimated)
+            return reported;
+        if (this.params.tracker)
+            this.params.tracker.update(estimated);
+        log("info", `usage estimated for aborted pass in=${estimated.inputTokens} out=${estimated.outputTokens}`);
+        return estimated;
+    }
+    /** Rough usage for a pass whose provider usage never arrived. */
+    estimateUsage() {
+        const outputTokens = this.assembler.producedTokens;
+        if (outputTokens === 0)
+            return undefined;
+        const inputTokens = estimateTokens(this.params.messages) + this.params.overhead.tokens;
+        return {
+            inputTokens,
+            outputTokens,
+            totalTokens: inputTokens + outputTokens,
+            inputTokenDetails: { noCacheTokens: inputTokens, cacheReadTokens: undefined, cacheWriteTokens: undefined },
+            outputTokenDetails: { textTokens: outputTokens, reasoningTokens: undefined },
+        };
+    }
+    /** streamText onError callback (step failed, will retry). */
+    onStepError(error) {
+        const msg = String(error);
+        if (isContextOverflowError(msg))
+            this.stop.context = true;
+        log("warn", `step failed (will retry): ${msg}`);
+    }
+    async applySlices(slices) {
+        for (const sl of slices) {
+            if (sl.type === "display") {
+                if (!sl.text)
+                    continue;
+                if (this.assembler.pendingResults > 0)
+                    this.assembler.flushStep();
+                this.assembler.appendText(sl.text);
+                if (this.xmlSearchRecovered && sl.text.trim())
+                    this.answerAfterXml = true;
+            }
+            else if (await this.materializeXmlSearch(sl.block)) {
+                return true;
             }
-            printDivider();
-            const { getContextWindow } = await import("./context-window.js");
-            const ctxWindow = await getContextWindow(modelId);
-            printDone(stepCount, usage, ctxWindow);
         }
+        return false;
     }
-    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);
-                }
+    applyLoopAction(action) {
+        if (action === "ok")
+            return false;
+        if (action === "halt") {
+            this.stop.doom = true;
+            this.innerController.abort();
+            return true;
+        }
+        this.pendingLoop = action;
+        stubWebResearchTools(this.params.allTools);
+        return false;
+    }
+    /** End the inner stream after research steer/cap, but only once every tool call has a result. */
+    settlePendingLoop() {
+        if (!this.pendingLoop)
+            return false;
+        if (this.assembler.hasUnpairedCalls)
+            return false;
+        this.stop.steer = this.pendingLoop === "steer";
+        this.stop.cap = this.pendingLoop === "cap";
+        this.pendingLoop = null;
+        this.innerController.abort();
+        return true;
+    }
+    async flushAndSettleLoop() {
+        if (this.assembler.hasUnpairedCalls)
+            return false;
+        if (await this.flushOutputAndStep())
+            return true;
+        return this.settlePendingLoop();
+    }
+    async materializeXmlSearch(block) {
+        const { cbs, loopGuard } = this.params;
+        const toolName = "search_web";
+        const query = block.query.trim();
+        const input = { query };
+        const toolCallId = this.assembler.nextMissingCallId();
+        this.renderer.flushMarkdown();
+        this.assembler.recordCall({ toolCallId, toolName, input });
+        logToolCall(toolName, input);
+        if (cbs.onToolCall)
+            invokeCallback(cbs.onToolCall, toolName, input, toolCallId);
+        else
+            printToolCall(toolName, input);
+        if (loopGuard.researchCapped) {
+            const output = RESEARCH_STUB_RESULT;
+            this.assembler.recordResult({ toolCallId, toolName, output });
+            logToolResult(toolName, output);
+            if (cbs.onToolResult)
+                invokeCallback(cbs.onToolResult, toolName, output, { toolCallId, isError: false });
+            else
+                printToolResult(toolName, output, false);
+            this.xmlSearchRecovered = true;
+            return false;
+        }
+        if (this.applyLoopAction(loopGuard.observe(toolName, input))) {
+            const output = LOOP_HALT_MESSAGE;
+            this.assembler.recordResult({ toolCallId, toolName, output });
+            logToolResult(toolName, output);
+            if (cbs.onToolResult)
+                invokeCallback(cbs.onToolResult, toolName, output, { toolCallId, isError: false });
+            else
+                printToolResult(toolName, output, false);
+            return true;
+        }
+        const output = block.kind === "results" ? block.body : await this.executeSearchWeb(query, toolCallId);
+        const isError = typeof output === "string" && /^(error|search error)\b/i.test(output);
+        this.assembler.recordResult({ toolCallId, toolName, output });
+        logToolResult(toolName, output);
+        if (cbs.onToolResult)
+            invokeCallback(cbs.onToolResult, toolName, output, { toolCallId, isError });
+        else
+            printToolResult(toolName, output, isError);
+        this.xmlSearchRecovered = true;
+        this.applyLoopAction(loopGuard.observeResult(toolName, isError ? "error" : output));
+        return false;
+    }
+    async executeSearchWeb(query, toolCallId) {
+        if (!query)
+            return 'Search error: "query" must be a non-empty string.';
+        const search = this.params.allTools.search_web;
+        if (typeof search?.execute !== "function")
+            return "Search error: search_web is unavailable.";
+        try {
+            const out = await search.execute({ query }, { toolCallId, messages: this.params.messages, abortSignal: this.signal });
+            return typeof out === "string" ? out : safeText(out);
+        }
+        catch (err) {
+            return `Search error: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    async flushOutputAndStep() {
+        const stop = await this.applySlices(this.renderer.flushOutput());
+        this.assembler.flushStep();
+        return stop;
+    }
+    /** Handle one fullStream event; returns true to break out of the stream loop. */
+    async handleEvent(event) {
+        const { cbs, loopGuard } = this.params;
+        switch (event.type) {
+            case "start-step":
+                this.stepFinishSeen = false;
+                if (!this.assembler.hasUnpairedCalls)
+                    this.assembler.flushStep();
+                return false;
+            case "finish-step":
+                this.stepFinishSeen = true;
+                this.noteStepUsage(event.usage);
+                return await this.flushAndSettleLoop();
+            case "finish":
+                if (usageNonZero(event.totalUsage))
+                    this.totalUsage = event.totalUsage;
+                return false;
+            case "reasoning-delta": {
+                if (event.text)
+                    this.renderer.feedReasoning(event.text);
+                return false;
             }
-            if (!callbacks)
-                process.stdout.write(md.flush());
-            const cleaned = stripThinkingFromAssistantText(assistantText);
-            if (cleaned.trim()) {
-                messages.push({ role: "assistant", content: cleaned });
+            case "text-delta": {
+                if (this.assembler.pendingResults > 0 && (await this.flushOutputAndStep()))
+                    return true;
+                return await this.applySlices(this.renderer.feedText(event.text));
             }
-            let usage;
-            try {
-                usage = await result.usage;
+            case "tool-call": {
+                if (this.assembler.pendingResults > 0 && (await this.flushOutputAndStep()))
+                    return true;
+                if (await this.applySlices(this.renderer.flushOutput()))
+                    return true;
+                const toolName = event.toolName || "unknown";
+                const toolCallId = event.toolCallId || this.assembler.nextMissingCallId();
+                this.assembler.recordCall({ toolCallId, toolName, input: event.input });
+                logToolCall(toolName, event.input);
+                if (cbs.onToolCall)
+                    invokeCallback(cbs.onToolCall, toolName, event.input, toolCallId);
+                else
+                    printToolCall(toolName, event.input);
+                if (this.applyLoopAction(loopGuard.observe(toolName, event.input))) {
+                    await this.flushOutputAndStep();
+                    return true;
+                }
+                return false;
             }
-            catch {
-                usage = undefined;
+            case "tool-result":
+            case "tool-error": {
+                const isError = event.type === "tool-error";
+                const output = isError ? event.error : event.output;
+                const displayed = isError ? `Error: ${safeText(event.error)}` : event.output;
+                this.assembler.recordResult({
+                    toolCallId: event.toolCallId,
+                    toolName: event.toolName || "unknown",
+                    output,
+                });
+                logToolResult(event.toolName, displayed);
+                if (cbs.onToolResult)
+                    invokeCallback(cbs.onToolResult, event.toolName, displayed, { toolCallId: event.toolCallId, isError });
+                else
+                    printToolResult(event.toolName, displayed, isError);
+                // Research productivity is judged on the result, not the call.
+                this.applyLoopAction(loopGuard.observeResult(event.toolName || "unknown", isError ? "error" : output));
+                if (this.stepFinishSeen || this.pendingLoop)
+                    return await this.flushAndSettleLoop();
+                return false;
+            }
+            case "error": {
+                const errorMsg = String(event.error);
+                if (isProviderStallError(event.error)) {
+                    this.stop.stall = true;
+                    log("warn", `provider stall: ${describeError(event.error)}`);
+                    await this.flushOutputAndStep();
+                    this.innerController.abort();
+                    return true;
+                }
+                if (isContextOverflowError(errorMsg)) {
+                    this.stop.context = true;
+                    log("warn", `context overflow: ${errorMsg}`);
+                    await this.flushOutputAndStep();
+                    this.innerController.abort();
+                    return true;
+                }
+                this.hasError = true;
+                log("error", `stream error: ${errorMsg}`);
+                if (cbs.onStreamError)
+                    invokeCallback(cbs.onStreamError, errorMsg);
+                else
+                    console.error(`\x1b[31m${formatErrorMessage(errorMsg)}\x1b[0m`);
+                return false;
             }
-            callbacks?.onRunFinish?.({ stepCount, usage, hasError: false, aborted: true });
-            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`);
+        return false;
+    }
+    snapshot(usage, extra = {}) {
+        return {
+            hasError: this.hasError,
+            userAborted: Boolean(this.params.abortSignal?.aborted),
+            budgetExceeded: this.stop.budget,
+            doomLoop: this.stop.doom,
+            researchSteer: this.stop.steer,
+            researchCap: this.stop.cap,
+            contextPressure: this.stop.context,
+            toolPressure: this.stop.tools,
+            maxStepsReached: this.params.stepBounded && this.assembler.innerSteps >= this.params.maxSteps && this.assembler.lastStepHadTools,
+            wrapUp: this.stop.wrapUp,
+            lastStepHadTools: this.assembler.lastStepHadTools,
+            xmlToolFollowUp: this.xmlSearchRecovered && !this.answerAfterXml && !this.stop.doom,
+            emptyCompletion: !this.assembler.hadAssistantText && !this.assembler.hadTools && !this.xmlSearchRecovered,
+            providerStall: this.stop.stall,
+            stepCount: this.assembler.innerSteps,
+            usage,
+            ...extra,
+        };
+    }
+    /** Normal end-of-stream: flush everything and snapshot usage. */
+    async finalize(result) {
+        await this.flushOutputAndStep();
+        this.settlePendingLoop();
+        return this.snapshot(this.resolvedUsage(result ? await safeUsage(result) : undefined));
+    }
+    /** Exception path: flush, classify the error, snapshot. */
+    async handleException(err, result) {
+        await this.applySlices(this.renderer.flushOnError());
+        this.assembler.flushStep();
+        this.settlePendingLoop();
+        const usage = this.resolvedUsage(result ? await safeUsage(result) : undefined);
+        if (this.params.abortSignal?.aborted)
+            return this.snapshot(usage, { userAborted: true });
+        if (isProviderStallError(err)) {
+            // The provider went quiet and we cut the request. Nothing was produced →
+            // let the empty-reply retry path re-send it; otherwise keep the partial
+            // turn and continue like any other tool-only step.
+            const produced = this.assembler.hadAssistantText || this.assembler.hadTools;
+            log("warn", `provider stall: ${describeError(err)}`);
+            this.stop.stall = true;
+            return this.snapshot(usage, { hasError: false, userAborted: false, emptyCompletion: !produced });
         }
-        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`);
+        if (err instanceof Error && err.name === "AbortError") {
+            return this.snapshot(usage, { userAborted: false });
         }
-        else if (msg.includes("timeout") || msg.includes("ETIMEDOUT") || msg.includes("ECONNRESET")) {
-            console.error(`\x1b[31mNetwork error (retries exhausted): ${msg}\x1b[0m`);
+        const msg = err instanceof Error ? err.message : String(err);
+        log("error", msg);
+        if (isContextOverflowError(msg)) {
+            this.stop.context = true;
+            return this.snapshot(usage, { hasError: false, contextPressure: true, userAborted: false });
         }
-        else {
+        this.hasError = true;
+        const display = formatErrorMessage(msg);
+        if (this.params.cbs.onStreamError)
+            invokeCallback(this.params.cbs.onStreamError, msg);
+        else if (display !== msg)
+            console.error(`\x1b[31m${display}\x1b[0m`);
+        else
             console.error(`\x1b[31mError: ${msg}\x1b[0m`);
+        return this.snapshot(usage, { hasError: true, userAborted: false, contextPressure: false });
+    }
+}
+async function runInnerStream(params) {
+    const machine = new InnerStreamMachine(params);
+    let result;
+    try {
+        machine.attachAbort();
+        const prompts = buildIterationPrompts(params.allTools, params.messages, params.taskState, params.loopGuard);
+        const system = [params.systemPrompt, ...prompts.stable].join("\n\n");
+        applyToolPrune(params.messages, params.pruneBudget());
+        // Volatile state rides along as a trailing message so the cached prefix
+        // (system + history) stays stable across passes.
+        const stateMessage = sessionStateMessage(prompts.volatile);
+        const requestMessages = stateMessage ? [...params.messages, stateMessage] : params.messages;
+        params.overhead.tokens =
+            estimateOverheadTokens(system, params.allTools) +
+                (stateMessage ? estimateOverheadTokens(String(stateMessage.content)) : 0);
+        result = streamText({
+            model: params.model,
+            system,
+            messages: requestMessages,
+            tools: params.allTools,
+            stopWhen: stepCountIs(params.maxSteps),
+            maxRetries: 3,
+            abortSignal: machine.signal,
+            ...(params.temperature != null ? { temperature: params.temperature } : {}),
+            ...(params.maxTokens != null ? { maxOutputTokens: params.maxTokens } : {}),
+            ...(params.topP != null ? { topP: params.topP } : {}),
+            onStepFinish({ usage }) {
+                machine.onStepFinish(usage);
+            },
+            onError({ error }) {
+                machine.onStepError(error);
+            },
+        });
+        for await (const event of result.fullStream) {
+            if (await machine.handleEvent(event))
+                break;
         }
-        let usage;
-        try {
-            usage = await result.usage;
-        }
-        catch {
-            usage = undefined;
-        }
-        callbacks?.onRunFinish?.({ stepCount, usage, hasError: true, aborted: false });
+        return await machine.finalize(result);
+    }
+    catch (err) {
+        return machine.handleException(err, result);
+    }
+    finally {
+        machine.detachAbort();
     }
 }
+export async function runOnce(messages, instructions, modelId, abortSignal, callbacks, tracker, options) {
+    const project = scanProject();
+    const systemPrompt = buildCodeSystemPrompt(project, instructions);
+    return runOnceCore(messages, systemPrompt, modelId, abortSignal, callbacks, tracker, options);
+}
+export async function runOnceWithSystem(messages, systemPrompt, modelId, abortSignal, callbacks, tracker, options) {
+    return runOnceCore(messages, systemPrompt, modelId, abortSignal, callbacks, tracker, options);
+}