@thoughtflow/core 0.1.2

package/dist/libs/conversation-runner.class.js

@@ -0,0 +1,1619 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConversationRunner = void 0;
+const contracts_1 = require("../contracts");
+const debug_logger_class_1 = require("./debug-logger.class");
+// ─────────────────────────────────────────────────────────────
+// Utility: collect tool calls from any Ollama response shape
+// ─────────────────────────────────────────────────────────────
+function normalizeToolArgs(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    return raw;
+}
+/**
+ * Walk any Ollama response node and collect { name, arguments } tool call objects.
+ * Handles: tool_calls[], calls[], { function: { name, arguments } }, direct { name, arguments }.
+ */
+function collectStructuredToolCalls(node) {
+    const out = [];
+    const walk = (value) => {
+        if (!value)
+            return;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                walk(item);
+            return;
+        }
+        if (typeof value !== "object")
+            return;
+        const obj = value;
+        if (typeof obj.name === "string") {
+            out.push({ id: typeof obj.id === "string" ? obj.id : undefined, name: obj.name, arguments: normalizeToolArgs(obj.arguments) });
+        }
+        if (obj.function && typeof obj.function === "object") {
+            const fn = obj.function;
+            if (typeof fn.name === "string") {
+                out.push({ id: typeof obj.id === "string" ? obj.id : undefined, name: fn.name, arguments: normalizeToolArgs(fn.arguments) });
+            }
+        }
+        if (Array.isArray(obj.tool_calls))
+            for (const tc of obj.tool_calls)
+                walk(tc);
+        if (Array.isArray(obj.calls))
+            for (const c of obj.calls)
+                walk(c);
+    };
+    walk(node);
+    return out;
+}
+function collectJsonCandidates(content) {
+    const text = (content || "").trim();
+    if (!text)
+        return [];
+    const candidates = [text];
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/gi;
+    let match;
+    while ((match = fenced.exec(text)) !== null) {
+        const block = (match[1] || "").trim();
+        if (block)
+            candidates.push(block);
+    }
+    return candidates;
+}
+/**
+ * Extract tool calls that the LLM embedded as JSON text instead of using the tool API.
+ */
+/**
+ * Attempt to repair common LLM JSON formatting mistakes:
+ * - Single-quoted string values: body: '{"title":"Buy milk"}' → body: "{\"title\":\"Buy milk\"}"
+ */
+function repairLlmJson(raw) {
+    // Replace single-quoted string values with properly double-quoted+escaped equivalents.
+    // Matches: (after : or , or [ or {) 'content' where content may contain double-quotes
+    return raw.replace(/(?<=[,:{[\s]\s*)'((?:[^'\\]|\\.)*)'/g, (_match, inner) => `"${inner.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`);
+}
+function extractTextualToolCalls(content, allowedToolNames) {
+    const calls = [];
+    const seen = new Set();
+    for (const candidate of collectJsonCandidates(content)) {
+        if (!/^[\[{]/.test(candidate))
+            continue;
+        for (const attempt of [candidate, repairLlmJson(candidate)]) {
+            try {
+                const parsed = JSON.parse(attempt);
+                const parsedCalls = collectStructuredToolCalls(parsed);
+                for (const call of parsedCalls) {
+                    if (!allowedToolNames.has(call.name))
+                        continue;
+                    const sig = `${call.name}:${JSON.stringify(call.arguments || {})}`;
+                    if (seen.has(sig))
+                        continue;
+                    seen.add(sig);
+                    calls.push(call);
+                }
+                if (parsedCalls.length > 0)
+                    break; // repair succeeded
+            }
+            catch {
+                /* invalid JSON fragment — try next attempt */
+            }
+        }
+    }
+    return calls;
+}
+/**
+ * Detect when the LLM described what it wanted to do as text/bash blocks
+ * instead of actually calling tools.
+ */
+function isLikelyTextualToolAttempt(content) {
+    const text = content || "";
+    const hasShellBlock = /```(?:bash|sh|shell)\n/i.test(text);
+    const hasCommandLikeLines = /(^|\n)\s*(?:\$\s*)?(?:npm|pnpm|yarn|node|python|rg|grep|git|ls|cat|sed)\b/im.test(text);
+    const hasToolName = /\b(?:read_file|write_file|edit_file|search_codebase|terminal_run|spawn_subagents|web_search|fetch_page|browser_[a-z_]+)\b/i.test(text);
+    const hasIntentVerb = /\b(?:let me|i(?:'ll| will)|uzyje|użyję|uruchomie|uruchomię|wywolam|wywołam|call|invoke|run)\b/i.test(text);
+    // Also detect when the entire response is a raw tool-call JSON object written as text
+    // e.g. {"name": "http_request", "arguments": {...}}
+    const hasRawToolCallJson = /\{\s*"name"\s*:\s*"[a-z_]+"\s*,\s*"arguments"\s*:\s*\{/i.test(text);
+    return hasShellBlock || hasCommandLikeLines || hasRawToolCallJson || (hasToolName && hasIntentVerb);
+}
+// ─────────────────────────────────────────────────────────────
+// Read-only vs action tool classification (for stall detection)
+// ─────────────────────────────────────────────────────────────
+const READ_ONLY_TOOLS = new Set([
+    "read_file", "list_directory", "list_dir", "search_files", "grep", "find_files",
+    "git_status", "git_diff", "search_codebase", "knowledge_search", "knowledge_read",
+    "knowledge_list", "search_plan", "read_plan_section", "search_tasks", "web_search",
+    "fetch_page", "browser_get_text", "browser_screenshot", "browser_navigate",
+    "codebase_search", "codebase_status", "codebase_graph_query", "codebase_graph_visualize",
+    "codebase_graph_circular", "codebase_graph_stats", "codebase_impact", "codebase_flow",
+    "codebase_knowledge", "codebase_crossref", "neural_explain", "neural_suggest",
+    "neural_review", "neural_debug", "neural_security", "neural_smells", "neural_deadcode",
+    "neural_similar", "neural_pattern", "neural_optimize", "quality_complexity",
+    "quality_coupling", "quality_coverage", "quality_deps", "quality_duplication",
+    "quality_size", "quality_types", "doc_check_links", "doc_check_coverage",
+    "db_diagram", "db_index_suggest", "deploy_check", "env_check",
+    "memory_recall", "memory_context", "memory_lessons", "memory_patterns",
+    "pm_estimate", "pm_risks", "pm_progress", "analyze_project", "project_context",
+    "codebase_research", "project_scanner", "safe_edit_policy",
+]);
+const ACTION_TOOLS = new Set([
+    "write_file", "edit_file", "terminal_run", "knowledge_write", "knowledge_update",
+    "container_restart", "app_start", "app_stop"
+]);
+/**
+ * Number of duplicate identical tool invocations (same name + args) before
+ * the runner injects a doom-loop warning into the conversation history.
+ * This escalates beyond the passive [DUPLICATE CALL] prefix in tool results.
+ */
+const DOOM_LOOP_THRESHOLD = 3;
+/** Hard safety limit for iterations per turn — prevents infinite loops when no budget is set. */
+const DEFAULT_MAX_ITERATIONS = 20;
+/** After this many consecutive read-only calls, inject a termination hint to push the model to produce output. */
+const TERMINATION_HINT_AFTER = 6;
+/** Absolute maximum consecutive read-only calls before forced termination. */
+const MAX_CONSECUTIVE_READ_ONLY = 12;
+class ConversationRunner {
+    deps;
+    log;
+    pendingInterrupt = null;
+    constructor(deps) {
+        this.deps = deps;
+        this.log = deps.logger ?? debug_logger_class_1.DebugLogger.NOOP;
+    }
+    hasPendingInterrupt() {
+        return this.pendingInterrupt !== null;
+    }
+    getPendingInterruptSnapshot() {
+        if (!this.pendingInterrupt)
+            return null;
+        return this.toPendingInterruptSnapshot(this.pendingInterrupt);
+    }
+    restorePendingInterrupt(snapshot) {
+        if (!snapshot) {
+            this.pendingInterrupt = null;
+            return;
+        }
+        const interruptToolCalls = snapshot.interruptTools
+            .map((item) => {
+            const toolCall = snapshot.toolCalls[item.index];
+            if (!toolCall)
+                return null;
+            return {
+                index: item.index,
+                toolCall: {
+                    name: toolCall.name,
+                    arguments: { ...(toolCall.args ?? {}) }
+                },
+                config: {
+                    allowedDecisions: [...item.config.allowedDecisions],
+                    description: item.config.description
+                }
+            };
+        })
+            .filter((value) => value !== null);
+        this.pendingInterrupt = {
+            interrupt: this.cloneInterrupt(snapshot.interrupt),
+            toolCalls: snapshot.toolCalls.map((toolCall) => ({
+                name: toolCall.name,
+                arguments: { ...(toolCall.args ?? {}) }
+            })),
+            interruptToolCalls
+        };
+    }
+    getPendingInterrupt() {
+        return this.pendingInterrupt ? this.cloneInterrupt(this.pendingInterrupt.interrupt) : null;
+    }
+    async runTurn(builtPrompt, options) {
+        const toolExecutions = [];
+        let totalTokensIn = 0;
+        let totalTokensOut = 0;
+        let lastThinking;
+        let iterationsUsed = 0;
+        let stopReason = "completed";
+        let runtimeMetadata = this.normalizeRuntimeMetadata(options?.metadata);
+        // Stall detection state
+        const STALL_LIMIT = 14;
+        let consecutiveReadOnly = 0;
+        const recentSignatures = [];
+        const uniqueSignatures = new Set();
+        // Doom-loop tracking: counts duplicate invocations per exact signature.
+        const doomLoopCounts = new Map();
+        const allToolNames = new Set(this.deps.toolRegistry.getLlmToolSpecs().map((t) => t.name));
+        const maxIterations = this.normalizeMaxIterations(options?.maxIterations) ?? DEFAULT_MAX_ITERATIONS;
+        const toolCallBudget = this.createToolCallBudget(options?.maxToolCalls, options?.maxToolCallsPerTool);
+        if (this.pendingInterrupt) {
+            throw new Error("Conversation is interrupted and waiting for decisions. Call resume() before sendPrompt().");
+        }
+        try {
+            this.transition(contracts_1.ConversationStatus.RUNNING);
+            this.deps.eventsBus.pushAgentUpdate("run_start", {
+                phase: "turn",
+                model: this.deps.getModel(),
+                namespace: this.resolveStreamNamespace(runtimeMetadata),
+            });
+            this.throwIfAborted(options?.signal);
+            this.log.info("runner", `start  model=${this.deps.getModel()}  tools=[${[...allToolNames].join(",")}]`);
+            // Only add system message if one doesn't already exist in history.
+            // runTurn is called once per sendPrompt() — system message must appear
+            // exactly once at position 0, otherwise vLLM rejects with
+            // "System message must be at the beginning."
+            const existingSystem = this.deps.history.snapshot().find(m => m.role === "system");
+            if (!existingSystem) {
+                const systemMessage = this.deps.history.unshift("system", builtPrompt.systemPrompt, {
+                    turn: "system",
+                    ...(options?.metadata ?? {})
+                });
+                this.deps.eventsBus.pushMessage(systemMessage);
+            }
+            const userMessage = this.deps.history.push("user", builtPrompt.userPrompt, {
+                turn: "user",
+                ...(options?.metadata ?? {})
+            });
+            this.deps.eventsBus.pushMessage(userMessage);
+            let finalOutput = "";
+            while (true) {
+                this.throwIfAborted(options?.signal);
+                if (maxIterations !== undefined && iterationsUsed >= maxIterations) {
+                    stopReason = "max-iterations";
+                    break;
+                }
+                const currentIteration = iterationsUsed + 1;
+                this.deps.eventsBus.pushAgentUpdate("iteration_start", {
+                    phase: "turn",
+                    iteration: currentIteration,
+                    namespace: this.resolveStreamNamespace(runtimeMetadata),
+                });
+                this.log.info("runner", `iteration ${currentIteration}`);
+                const allowedToolSpecs = await this.resolveAllowedToolSpecs("turn", currentIteration, runtimeMetadata, builtPrompt.userPrompt);
+                const allowedToolNames = new Set(allowedToolSpecs.map((tool) => tool.name));
+                const selectedModel = this.resolveModelForIteration("turn", currentIteration);
+                await this.deps.beforeModelHook?.({
+                    phase: "turn",
+                    iteration: currentIteration,
+                    model: selectedModel,
+                    messages: this.deps.history.snapshot(),
+                    metadata: { ...runtimeMetadata },
+                });
+                const shouldStream = options?.stream !== false;
+                const requestBase = {
+                    model: selectedModel,
+                    messages: this.deps.contextWindowManager
+                        ? this.deps.contextWindowManager.trim(this.deps.history.snapshotWithResolvedPayloads())
+                        : this.deps.history.snapshotWithResolvedPayloads(),
+                    tools: allowedToolSpecs,
+                    signal: options?.signal,
+                    thinking: this.deps.thinking,
+                    temperature: this.deps.temperature,
+                    numCtx: this.deps.numCtx,
+                    seed: this.deps.seed,
+                };
+                const response = shouldStream
+                    ? await this.deps.llmAdapter.streamChat(requestBase, (chunk) => this.deps.eventsBus.pushStreamChunk({
+                        ...chunk,
+                        metadata: {
+                            ...(chunk.metadata ?? {}),
+                            phase: "turn",
+                            iteration: currentIteration,
+                            node: "model",
+                            model: selectedModel,
+                            namespace: this.resolveStreamNamespace(runtimeMetadata),
+                        },
+                    }))
+                    : await this.deps.llmAdapter.chat(requestBase);
+                iterationsUsed++;
+                await this.deps.afterModelHook?.({
+                    phase: "turn",
+                    iteration: iterationsUsed,
+                    model: selectedModel,
+                    messages: this.deps.history.snapshot(),
+                    metadata: { ...runtimeMetadata },
+                    response: response.message,
+                });
+                totalTokensIn += response.tokensInput ?? 0;
+                totalTokensOut += response.tokensOutput ?? 0;
+                if (response.message?.thinking)
+                    lastThinking = response.message.thinking;
+                this.deps.eventsBus.pushAgentUpdate("model_response", {
+                    phase: "turn",
+                    iteration: iterationsUsed,
+                    model: selectedModel,
+                    toolCalls: response.message?.toolCalls?.length ?? 0,
+                    tokensInput: response.tokensInput ?? 0,
+                    tokensOutput: response.tokensOutput ?? 0,
+                    namespace: this.resolveStreamNamespace(runtimeMetadata),
+                });
+                finalOutput = response.message?.content ?? "";
+                this.log.verbose("runner", `llm response  tokIn=${response.tokensInput ?? 0}  tokOut=${response.tokensOutput ?? 0}  toolCalls=${response.message?.toolCalls?.length ?? 0}  contentLen=${finalOutput.length}`);
+                if (finalOutput.length > 0)
+                    this.log.verbose("runner", `llm text: ${finalOutput.slice(0, 200)}${finalOutput.length > 200 ? "…" : ""}`);
+                // Empty response guard — model returned nothing (no content, no reasoning, no tools).
+                // Retry the iteration instead of completing with empty output.
+                if (!finalOutput && !response.message?.thinking && !response.message?.reasoningContent &&
+                    (!response.message?.toolCalls || response.message.toolCalls.length === 0)) {
+                    this.log.info("runner", `empty LLM response — retrying iteration ${currentIteration}`);
+                    this.deps.eventsBus.pushAgentUpdate("model_response", {
+                        phase: "turn", iteration: currentIteration, model: selectedModel, toolCalls: 0,
+                        namespace: this.resolveStreamNamespace(runtimeMetadata),
+                    });
+                    continue;
+                }
+                const assistantMessage = this.deps.history.pushAssistant(finalOutput, response.message?.toolCalls, response.message?.reasoningContent);
+                this.deps.eventsBus.pushMessage(assistantMessage);
+                if (!response.message?.toolCalls || response.message.toolCalls.length === 0) {
+                    // ─── Textual tool-call recovery ───────────────────────────
+                    // LLM sometimes forgets it has function calling and writes JSON/bash as text.
+                    const textualCalls = extractTextualToolCalls(finalOutput, allowedToolNames);
+                    if (textualCalls.length > 0) {
+                        for (const tc of textualCalls) {
+                            if (!this.consumeToolCallBudget(toolCallBudget, tc.name)) {
+                                stopReason = "max-tool-calls";
+                                break;
+                            }
+                            const result = await this.executeTool(tc.name, tc.arguments, toolExecutions, options, runtimeMetadata);
+                            const commandResult = this.applyToolCommand(result.command, runtimeMetadata);
+                            runtimeMetadata = commandResult.metadata;
+                            this.trackStallSignals(tc.name, tc.arguments, uniqueSignatures, recentSignatures);
+                            if (READ_ONLY_TOOLS.has(tc.name))
+                                consecutiveReadOnly++;
+                            else if (ACTION_TOOLS.has(tc.name)) {
+                                consecutiveReadOnly = 0;
+                                recentSignatures.length = 0;
+                            }
+                            const toolOutput = result.success ? result.output ?? "" : `ERROR: ${result.error ?? "Unknown error"}`;
+                            const toolMsg = this.deps.history.pushToolResult(tc.name, toolOutput, "call_textual_" + Date.now() + "_" + Math.random().toString(36).slice(2, 6));
+                            this.deps.eventsBus.pushMessage(toolMsg);
+                            if (commandResult.goto === "end_turn") {
+                                await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+                                this.transition(contracts_1.ConversationStatus.COMPLETED);
+                                return {
+                                    output: commandResult.outputOverride ?? finalOutput,
+                                    thinking: lastThinking,
+                                    stopReason: "completed",
+                                    status: this.deps.statusMachine.current,
+                                    messages: this.deps.history.snapshot(),
+                                    toolExecutions,
+                                    tokensInput: totalTokensIn,
+                                    tokensOutput: totalTokensOut,
+                                    iterationsUsed
+                                };
+                            }
+                            if (commandResult.goto === "next_iteration") {
+                                break;
+                            }
+                        }
+                        if (stopReason !== "completed")
+                            break;
+                        if (options?.signal?.aborted)
+                            break;
+                        await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+                        const stallResult = this.checkStall(consecutiveReadOnly, recentSignatures, STALL_LIMIT, uniqueSignatures);
+                        if (stallResult) {
+                            stopReason = stallResult;
+                            break;
+                        }
+                        continue;
+                    }
+                    // LLM tried to call tools as text but JSON was not parseable
+                    const looksLikeToolAttempt = isLikelyTextualToolAttempt(finalOutput);
+                    const recoveryCount = this.deps.history.snapshot().filter((m) => m.role === "user" && m.content.startsWith("⚠️ Tool-calling reminder")).length;
+                    if (looksLikeToolAttempt && recoveryCount < 2) {
+                        const recoveryMsg = this.deps.history.push("user", "⚠️ Tool-calling reminder: You wrote commands as text but did NOT call any tools. " +
+                            "You MUST use the tool-calling API (function call mechanism) to read files, write files, and run commands. " +
+                            "Do NOT write bash code blocks — actually CALL the tools. Available tools: " +
+                            [...allowedToolNames].join(", ") +
+                            ". Please proceed by calling the appropriate tool now.");
+                        this.deps.eventsBus.pushMessage(recoveryMsg);
+                        continue;
+                    }
+                    // Genuinely finished — no more tool calls
+                    await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+                    stopReason = "completed";
+                    this.transition(contracts_1.ConversationStatus.COMPLETED);
+                    this.deps.eventsBus.pushAgentUpdate("run_complete", {
+                        phase: "turn",
+                        stopReason: "completed",
+                        iterations: iterationsUsed,
+                        namespace: this.resolveStreamNamespace(runtimeMetadata),
+                    });
+                    this.log.info("runner", `done  stopReason=completed  iterations=${iterationsUsed}  tokIn=${totalTokensIn}  tokOut=${totalTokensOut}`);
+                    return {
+                        output: finalOutput,
+                        thinking: lastThinking,
+                        stopReason,
+                        status: this.deps.statusMachine.current,
+                        messages: this.deps.history.snapshot(),
+                        toolExecutions,
+                        tokensInput: totalTokensIn,
+                        tokensOutput: totalTokensOut,
+                        iterationsUsed
+                    };
+                }
+                // ─── Process native tool calls ─────────────────────────────
+                const filteredToolCalls = this.filterBlockedToolCalls(response.message?.toolCalls ?? [], {
+                    phase: "turn",
+                    iteration: iterationsUsed,
+                    metadata: runtimeMetadata,
+                }, toolExecutions);
+                if (filteredToolCalls.length === 0) {
+                    await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+                    this.transition(contracts_1.ConversationStatus.RUNNING);
+                    continue;
+                }
+                const pendingInterrupt = this.buildPendingInterrupt(filteredToolCalls);
+                if (pendingInterrupt) {
+                    this.pendingInterrupt = pendingInterrupt;
+                    stopReason = "interrupted";
+                    this.transition(contracts_1.ConversationStatus.INTERRUPTED);
+                    this.deps.eventsBus.pushInterrupt(pendingInterrupt.interrupt);
+                    await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+                    this.log.info("runner", `interrupted  actions=${pendingInterrupt.interrupt.request.actionRequests.length}`);
+                    return {
+                        output: finalOutput,
+                        thinking: lastThinking,
+                        stopReason,
+                        status: this.deps.statusMachine.current,
+                        messages: this.deps.history.snapshot(),
+                        toolExecutions,
+                        interrupt: this.cloneInterrupt(pendingInterrupt.interrupt),
+                        tokensInput: totalTokensIn,
+                        tokensOutput: totalTokensOut,
+                        iterationsUsed
+                    };
+                }
+                this.transition(contracts_1.ConversationStatus.WAITING_TOOL);
+                for (let _tcIdx = 0; _tcIdx < filteredToolCalls.length; _tcIdx++) {
+                    const toolCall = filteredToolCalls[_tcIdx];
+                    this.throwIfAborted(options?.signal);
+                    if (!this.consumeToolCallBudget(toolCallBudget, toolCall.name)) {
+                        stopReason = "max-tool-calls";
+                        for (let _skipIdx = _tcIdx; _skipIdx < filteredToolCalls.length; _skipIdx++) {
+                            const _skipped = filteredToolCalls[_skipIdx];
+                            const _skipMsg = this.deps.history.pushToolResult(_skipped.name, `\u26a0\ufe0f Tool call skipped: tool call budget exhausted.`, _skipped.id ?? `call_skip_${Date.now()}_${_skipIdx}`);
+                            this.deps.eventsBus.pushMessage(_skipMsg);
+                        }
+                        break;
+                    }
+                    this.log.info("tool", `call  ${toolCall.name}`);
+                    this.log.verbose("tool", `args  ${toolCall.name}`, toolCall.arguments);
+                    const signature = `${toolCall.name}:${JSON.stringify(toolCall.arguments ?? {})}`;
+                    const isDuplicate = uniqueSignatures.has(signature);
+                    this.trackStallSignals(toolCall.name, toolCall.arguments, uniqueSignatures, recentSignatures);
+                    if (ACTION_TOOLS.has(toolCall.name)) {
+                        consecutiveReadOnly = 0;
+                        recentSignatures.length = 0;
+                    }
+                    else if (READ_ONLY_TOOLS.has(toolCall.name)) {
+                        consecutiveReadOnly++;
+                    }
+                    else {
+                        consecutiveReadOnly = 0; // unknown tools count as activity
+                    }
+                    const stallResult = this.checkStall(consecutiveReadOnly, recentSignatures, STALL_LIMIT, uniqueSignatures);
+                    if (stallResult) {
+                        stopReason = stallResult;
+                        for (let _skipIdx = _tcIdx; _skipIdx < filteredToolCalls.length; _skipIdx++) {
+                            const _skipped = filteredToolCalls[_skipIdx];
+                            const _skipMsg = this.deps.history.pushToolResult(_skipped.name, `\u26a0\ufe0f Tool call skipped: ${stallResult === "stall" ? "stall detected after too many consecutive read-only tool calls" : "repetition detected after repeated identical tool calls"}.`, _skipped.id ?? `call_skip_${Date.now()}_${_skipIdx}`);
+                            this.deps.eventsBus.pushMessage(_skipMsg);
+                        }
+                        break;
+                    }
+                    const execution = await this.executeToolWithRetry(toolCall.name, toolCall.arguments ?? {}, options, runtimeMetadata);
+                    this.deps.eventsBus.pushToolEvent(execution.startedTrace);
+                    this.deps.eventsBus.pushToolEvent(execution.trace);
+                    toolExecutions.push(execution.trace);
+                    this.log.info("tool", `result  ${toolCall.name}  ${execution.result.success ? "OK" : "ERROR"}`);
+                    this.log.verbose("tool", `output  ${toolCall.name}`, (execution.result.output ?? execution.result.error ?? "").slice(0, 300));
+                    const duplicatePrefix = isDuplicate
+                        ? `[DUPLICATE CALL: you already called '${toolCall.name}' with these exact arguments. Below is the same result. Stop repeating this call.]\n\n`
+                        : "";
+                    const toolOutput = execution.result.success
+                        ? duplicatePrefix + (execution.result.output ?? "")
+                        : `ERROR: ${execution.result.error ?? "Unknown tool error"}`;
+                    const toolMessage = this.deps.history.pushToolResult(toolCall.name, toolOutput, toolCall.id ?? execution.trace.id);
+                    this.deps.eventsBus.pushMessage(toolMessage);
+                    if (this.injectTerminationHint(consecutiveReadOnly)) {
+                        stopReason = "stall";
+                        break;
+                    }
+                    // Doom-loop injection: escalate after repeated identical calls.
+                    if (isDuplicate) {
+                        const doomCount = (doomLoopCounts.get(signature) ?? 0) + 1;
+                        doomLoopCounts.set(signature, doomCount);
+                        if (doomCount >= DOOM_LOOP_THRESHOLD) {
+                            this.log.info("runner", `doom-loop  ${toolCall.name}  count=${doomCount + 1}`);
+                            const doomMsg = this.deps.history.push("user", `⚠️ Doom-loop warning: You have called '${toolCall.name}' with identical arguments ${doomCount + 1} times. ` +
+                                `This call cannot produce a different result. You MUST break this loop now: ` +
+                                `try a different tool, a different approach, or conclude and summarize your findings.`);
+                            this.deps.eventsBus.pushMessage(doomMsg);
+                        }
+                    }
+                    const commandResult = this.applyToolCommand(execution.result.command, runtimeMetadata);
+                    runtimeMetadata = commandResult.metadata;
+                    if (commandResult.goto === "end_turn") {
+                        this.ensureToolResultsForBatch(filteredToolCalls, "turn ended by tool command");
+                        await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+                        this.transition(contracts_1.ConversationStatus.COMPLETED);
+                        return {
+                            output: commandResult.outputOverride ?? finalOutput,
+                            thinking: lastThinking,
+                            stopReason: "completed",
+                            status: this.deps.statusMachine.current,
+                            messages: this.deps.history.snapshot(),
+                            toolExecutions,
+                            tokensInput: totalTokensIn,
+                            tokensOutput: totalTokensOut,
+                            iterationsUsed
+                        };
+                    }
+                    if (commandResult.goto === "next_iteration") {
+                        break;
+                    }
+                }
+                // ── Placeholder results for unmatched tool calls (DeepSeek compat) ─
+                if (stopReason && stopReason !== "completed") {
+                    this.ensureToolResultsForBatch(filteredToolCalls, "execution terminated early");
+                }
+                if (stopReason !== "completed") {
+                    await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+                    break;
+                }
+                // Persist message history snapshot after each tool-call round-trip
+                await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+                this.transition(contracts_1.ConversationStatus.RUNNING);
+            }
+            // Fell out of the while loop due to stall/repetition/abort
+            if (stopReason === "aborted" || options?.signal?.aborted) {
+                stopReason = "aborted";
+                this.transition(contracts_1.ConversationStatus.CANCELLED);
+            }
+            else {
+                this.transition(contracts_1.ConversationStatus.COMPLETED);
+            }
+            this.deps.eventsBus.pushAgentUpdate("run_complete", {
+                phase: "turn",
+                stopReason,
+                iterations: iterationsUsed,
+                namespace: this.resolveStreamNamespace(runtimeMetadata),
+            });
+            this.log.info("runner", `done  stopReason=${stopReason}  iterations=${iterationsUsed}  tokIn=${totalTokensIn}  tokOut=${totalTokensOut}`);
+            return {
+                output: finalOutput,
+                thinking: lastThinking,
+                stopReason,
+                status: this.deps.statusMachine.current,
+                messages: this.deps.history.snapshot(),
+                toolExecutions,
+                tokensInput: totalTokensIn,
+                tokensOutput: totalTokensOut,
+                iterationsUsed
+            };
+        }
+        catch (error) {
+            this.restorePendingInterrupt(null);
+            if (this.isAbortError(error)) {
+                this.log.info("runner", "aborted");
+                this.transition(contracts_1.ConversationStatus.CANCELLED);
+                return {
+                    output: "",
+                    thinking: lastThinking,
+                    stopReason: "aborted",
+                    status: this.deps.statusMachine.current,
+                    messages: this.deps.history.snapshot(),
+                    toolExecutions,
+                    tokensInput: totalTokensIn,
+                    tokensOutput: totalTokensOut,
+                    iterationsUsed
+                };
+            }
+            const err = error instanceof Error ? error : new Error("Unknown conversation error");
+            this.log.info("runner", `error: ${err.message}`);
+            this.transition(contracts_1.ConversationStatus.FAILED);
+            this.deps.eventsBus.pushError(err);
+            throw err;
+        }
+    }
+    async resumeTurn(response, options) {
+        const pending = this.pendingInterrupt;
+        if (!pending) {
+            throw new Error("No pending interrupt to resume.");
+        }
+        const toolExecutions = [];
+        let totalTokensIn = 0;
+        let totalTokensOut = 0;
+        let lastThinking;
+        let iterationsUsed = 0;
+        let stopReason = "completed";
+        let runtimeMetadata = this.normalizeRuntimeMetadata(options?.metadata);
+        const STALL_LIMIT = 14;
+        let consecutiveReadOnly = 0;
+        const recentSignatures = [];
+        const uniqueSignatures = new Set();
+        // Doom-loop tracking: counts duplicate invocations per exact signature.
+        const doomLoopCounts = new Map();
+        const maxIterations = this.normalizeMaxIterations(options?.maxIterations) ?? DEFAULT_MAX_ITERATIONS;
+        const toolCallBudget = this.createToolCallBudget(options?.maxToolCalls, options?.maxToolCallsPerTool);
+        try {
+            this.transition(contracts_1.ConversationStatus.RUNNING);
+            this.deps.eventsBus.pushAgentUpdate("run_start", {
+                phase: "resume",
+                namespace: this.resolveStreamNamespace(runtimeMetadata),
+            });
+            this.throwIfAborted(options?.signal);
+            const resolvedResponse = this.resolveResumeResponse(response, pending);
+            const decisionResult = this.applyInterruptDecisions(resolvedResponse, pending);
+            this.deps.eventsBus.pushInterruptResolved(pending.interrupt.id, resolvedResponse.decisions);
+            this.pendingInterrupt = null;
+            if (decisionResult.hasRejectedToolCalls) {
+                for (const message of decisionResult.artificialToolMessages) {
+                    const toolMessage = this.deps.history.pushToolResult(message.toolName, message.content, message.toolCallId ?? `call_rejected_${Date.now()}`);
+                    this.deps.eventsBus.pushMessage(toolMessage);
+                }
+                await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+            }
+            else {
+                this.transition(contracts_1.ConversationStatus.WAITING_TOOL);
+                for (const toolCall of decisionResult.revisedToolCalls) {
+                    this.throwIfAborted(options?.signal);
+                    if (!this.consumeToolCallBudget(toolCallBudget, toolCall.name)) {
+                        stopReason = "max-tool-calls";
+                        break;
+                    }
+                    if (!this.isToolAllowed("resume", 0, toolCall.name, runtimeMetadata)) {
+                        const skipped = this.createSkippedToolTrace(toolCall.name, toolCall.arguments, "Tool blocked by dynamic toolFilter.");
+                        this.deps.eventsBus.pushToolEvent(skipped);
+                        toolExecutions.push(skipped);
+                        const blockedMessage = this.deps.history.pushToolResult(toolCall.name, `ERROR: Tool '${toolCall.name}' is blocked by toolFilter for phase 'resume'.`, toolCall.id ?? `call_blocked_${Date.now()}`);
+                        this.deps.eventsBus.pushMessage(blockedMessage);
+                        continue;
+                    }
+                    this.log.info("tool", `call  ${toolCall.name}`);
+                    this.log.verbose("tool", `args  ${toolCall.name}`, toolCall.arguments);
+                    const signature = `${toolCall.name}:${JSON.stringify(toolCall.arguments ?? {})}`;
+                    const isDuplicate = uniqueSignatures.has(signature);
+                    this.trackStallSignals(toolCall.name, toolCall.arguments, uniqueSignatures, recentSignatures);
+                    if (ACTION_TOOLS.has(toolCall.name)) {
+                        consecutiveReadOnly = 0;
+                        recentSignatures.length = 0;
+                    }
+                    else if (READ_ONLY_TOOLS.has(toolCall.name)) {
+                        consecutiveReadOnly++;
+                    }
+                    else {
+                        consecutiveReadOnly = 0;
+                    }
+                    const stallResult = this.checkStall(consecutiveReadOnly, recentSignatures, STALL_LIMIT, uniqueSignatures);
+                    if (stallResult) {
+                        stopReason = stallResult;
+                        break;
+                    }
+                    const execution = await this.executeToolWithRetry(toolCall.name, toolCall.arguments ?? {}, options, runtimeMetadata);
+                    this.deps.eventsBus.pushToolEvent(execution.startedTrace);
+                    this.deps.eventsBus.pushToolEvent(execution.trace);
+                    toolExecutions.push(execution.trace);
+                    const duplicatePrefix = isDuplicate
+                        ? `[DUPLICATE CALL: you already called '${toolCall.name}' with these exact arguments. Below is the same result. Stop repeating this call.]\n\n`
+                        : "";
+                    const toolOutput = execution.result.success
+                        ? duplicatePrefix + (execution.result.output ?? "")
+                        : `ERROR: ${execution.result.error ?? "Unknown tool error"}`;
+                    const toolMessage = this.deps.history.pushToolResult(toolCall.name, toolOutput, toolCall.id ?? execution.trace.id);
+                    this.deps.eventsBus.pushMessage(toolMessage);
+                    if (this.injectTerminationHint(consecutiveReadOnly)) {
+                        stopReason = "stall";
+                        break;
+                    }
+                    const commandResult = this.applyToolCommand(execution.result.command, runtimeMetadata);
+                    runtimeMetadata = commandResult.metadata;
+                    if (commandResult.goto === "end_turn") {
+                        await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+                        this.transition(contracts_1.ConversationStatus.COMPLETED);
+                        return {
+                            output: commandResult.outputOverride ?? "",
+                            thinking: lastThinking,
+                            stopReason: "completed",
+                            status: this.deps.statusMachine.current,
+                            messages: this.deps.history.snapshot(),
+                            toolExecutions,
+                            tokensInput: totalTokensIn,
+                            tokensOutput: totalTokensOut,
+                            iterationsUsed
+                        };
+                    }
+                    if (commandResult.goto === "next_iteration") {
+                        break;
+                    }
+                }
+                await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+                if (stopReason === "completed") {
+                    this.transition(contracts_1.ConversationStatus.RUNNING);
+                }
+            }
+            let finalOutput = "";
+            while (stopReason === "completed") {
+                this.throwIfAborted(options?.signal);
+                if (maxIterations !== undefined && iterationsUsed >= maxIterations) {
+                    stopReason = "max-iterations";
+                    break;
+                }
+                const currentIteration = iterationsUsed + 1;
+                this.deps.eventsBus.pushAgentUpdate("iteration_start", {
+                    phase: "resume",
+                    iteration: currentIteration,
+                    namespace: this.resolveStreamNamespace(runtimeMetadata),
+                });
+                const userMsg = this.deps.history.snapshot().find((m) => m.role === "user");
+                const allowedToolSpecs = await this.resolveAllowedToolSpecs("resume", currentIteration, runtimeMetadata, userMsg?.content);
+                const allowedToolNames = new Set(allowedToolSpecs.map((tool) => tool.name));
+                const selectedModel = this.resolveModelForIteration("resume", currentIteration);
+                await this.deps.beforeModelHook?.({
+                    phase: "resume",
+                    iteration: currentIteration,
+                    model: selectedModel,
+                    messages: this.deps.history.snapshot(),
+                    metadata: { ...runtimeMetadata },
+                });
+                const responseChunk = await this.deps.llmAdapter.streamChat({
+                    model: selectedModel,
+                    messages: this.deps.contextWindowManager
+                        ? this.deps.contextWindowManager.trim(this.deps.history.snapshot())
+                        : this.deps.history.snapshot(),
+                    tools: allowedToolSpecs,
+                    signal: options?.signal,
+                    thinking: this.deps.thinking,
+                    temperature: this.deps.temperature,
+                    numCtx: this.deps.numCtx,
+                    seed: this.deps.seed
+                }, (chunk) => this.deps.eventsBus.pushStreamChunk({
+                    ...chunk,
+                    metadata: {
+                        ...(chunk.metadata ?? {}),
+                        phase: "resume",
+                        iteration: currentIteration,
+                        node: "model",
+                        model: selectedModel,
+                        namespace: this.resolveStreamNamespace(runtimeMetadata),
+                    },
+                }));
+                iterationsUsed++;
+                await this.deps.afterModelHook?.({
+                    phase: "resume",
+                    iteration: iterationsUsed,
+                    model: selectedModel,
+                    messages: this.deps.history.snapshot(),
+                    metadata: { ...runtimeMetadata },
+                    response: responseChunk.message,
+                });
+                totalTokensIn += responseChunk.tokensInput ?? 0;
+                totalTokensOut += responseChunk.tokensOutput ?? 0;
+                if (responseChunk.message?.thinking)
+                    lastThinking = responseChunk.message.thinking;
+                this.deps.eventsBus.pushAgentUpdate("model_response", {
+                    phase: "resume",
+                    iteration: iterationsUsed,
+                    model: selectedModel,
+                    toolCalls: responseChunk.message?.toolCalls?.length ?? 0,
+                    tokensInput: responseChunk.tokensInput ?? 0,
+                    tokensOutput: responseChunk.tokensOutput ?? 0,
+                    namespace: this.resolveStreamNamespace(runtimeMetadata),
+                });
+                finalOutput = responseChunk.message?.content ?? "";
+                const assistantMessage = this.deps.history.pushAssistant(finalOutput, responseChunk.message?.toolCalls, responseChunk.message?.reasoningContent);
+                this.deps.eventsBus.pushMessage(assistantMessage);
+                if (!responseChunk.message?.toolCalls || responseChunk.message.toolCalls.length === 0) {
+                    const textualCalls = extractTextualToolCalls(finalOutput, allowedToolNames);
+                    if (textualCalls.length > 0) {
+                        for (const tc of textualCalls) {
+                            if (!allowedToolNames.has(tc.name)) {
+                                const skipped = this.createSkippedToolTrace(tc.name, tc.arguments, "Tool blocked by dynamic toolFilter.");
+                                this.deps.eventsBus.pushToolEvent(skipped);
+                                toolExecutions.push(skipped);
+                                const blockedMessage = this.deps.history.pushToolResult(tc.name, `ERROR: Tool '${tc.name}' is blocked by toolFilter for phase 'resume'.`, `call_blocked_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`);
+                                this.deps.eventsBus.pushMessage(blockedMessage);
+                                continue;
+                            }
+                            if (!this.consumeToolCallBudget(toolCallBudget, tc.name)) {
+                                stopReason = "max-tool-calls";
+                                break;
+                            }
+                            const result = await this.executeTool(tc.name, tc.arguments, toolExecutions, options, runtimeMetadata);
+                            const commandResult = this.applyToolCommand(result.command, runtimeMetadata);
+                            runtimeMetadata = commandResult.metadata;
+                            this.trackStallSignals(tc.name, tc.arguments, uniqueSignatures, recentSignatures);
+                            if (READ_ONLY_TOOLS.has(tc.name))
+                                consecutiveReadOnly++;
+                            else if (ACTION_TOOLS.has(tc.name)) {
+                                consecutiveReadOnly = 0;
+                                recentSignatures.length = 0;
+                            }
+                            const toolOutput = result.success
+                                ? result.output ?? ""
+                                : `ERROR: ${result.error ?? "Unknown error"}`;
+                            const toolMsg = this.deps.history.pushToolResult(tc.name, toolOutput, "call_textual_" + Date.now() + "_" + Math.random().toString(36).slice(2, 6));
+                            this.deps.eventsBus.pushMessage(toolMsg);
+                            if (commandResult.goto === "end_turn") {
+                                await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+                                this.transition(contracts_1.ConversationStatus.COMPLETED);
+                                return {
+                                    output: commandResult.outputOverride ?? finalOutput,
+                                    thinking: lastThinking,
+                                    stopReason: "completed",
+                                    status: this.deps.statusMachine.current,
+                                    messages: this.deps.history.snapshot(),
+                                    toolExecutions,
+                                    tokensInput: totalTokensIn,
+                                    tokensOutput: totalTokensOut,
+                                    iterationsUsed
+                                };
+                            }
+                            if (commandResult.goto === "next_iteration") {
+                                break;
+                            }
+                        }
+                        if (stopReason !== "completed")
+                            break;
+                        if (options?.signal?.aborted)
+                            break;
+                        await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+                        const stallResult = this.checkStall(consecutiveReadOnly, recentSignatures, STALL_LIMIT, uniqueSignatures);
+                        if (stallResult) {
+                            stopReason = stallResult;
+                            break;
+                        }
+                        continue;
+                    }
+                    const looksLikeToolAttempt = isLikelyTextualToolAttempt(finalOutput);
+                    const recoveryCount = this.deps.history.snapshot().filter((m) => m.role === "user" && m.content.startsWith("⚠️ Tool-calling reminder")).length;
+                    if (looksLikeToolAttempt && recoveryCount < 2) {
+                        const recoveryMsg = this.deps.history.push("user", "⚠️ Tool-calling reminder: You wrote commands as text but did NOT call any tools. " +
+                            "You MUST use the tool-calling API (function call mechanism) to read files, write files, and run commands. " +
+                            "Do NOT write bash code blocks — actually CALL the tools. Available tools: " +
+                            [...allowedToolNames].join(", ") +
+                            ". Please proceed by calling the appropriate tool now.");
+                        this.deps.eventsBus.pushMessage(recoveryMsg);
+                        continue;
+                    }
+                    await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+                    stopReason = "completed";
+                    this.transition(contracts_1.ConversationStatus.COMPLETED);
+                    this.deps.eventsBus.pushAgentUpdate("run_complete", {
+                        phase: "resume",
+                        stopReason: "completed",
+                        iterations: iterationsUsed,
+                        namespace: this.resolveStreamNamespace(runtimeMetadata),
+                    });
+                    return {
+                        output: finalOutput,
+                        thinking: lastThinking,
+                        stopReason,
+                        status: this.deps.statusMachine.current,
+                        messages: this.deps.history.snapshot(),
+                        toolExecutions,
+                        tokensInput: totalTokensIn,
+                        tokensOutput: totalTokensOut,
+                        iterationsUsed
+                    };
+                }
+                const filteredToolCalls = this.filterBlockedToolCalls(responseChunk.message?.toolCalls ?? [], {
+                    phase: "resume",
+                    iteration: iterationsUsed,
+                    metadata: runtimeMetadata,
+                }, toolExecutions);
+                if (filteredToolCalls.length === 0) {
+                    await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+                    this.transition(contracts_1.ConversationStatus.RUNNING);
+                    continue;
+                }
+                const nextPendingInterrupt = this.buildPendingInterrupt(filteredToolCalls);
+                if (nextPendingInterrupt) {
+                    this.pendingInterrupt = nextPendingInterrupt;
+                    stopReason = "interrupted";
+                    this.transition(contracts_1.ConversationStatus.INTERRUPTED);
+                    this.deps.eventsBus.pushInterrupt(nextPendingInterrupt.interrupt);
+                    await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+                    return {
+                        output: finalOutput,
+                        thinking: lastThinking,
+                        stopReason,
+                        status: this.deps.statusMachine.current,
+                        messages: this.deps.history.snapshot(),
+                        toolExecutions,
+                        interrupt: this.cloneInterrupt(nextPendingInterrupt.interrupt),
+                        tokensInput: totalTokensIn,
+                        tokensOutput: totalTokensOut,
+                        iterationsUsed
+                    };
+                }
+                this.transition(contracts_1.ConversationStatus.WAITING_TOOL);
+                for (let _tcIdx = 0; _tcIdx < filteredToolCalls.length; _tcIdx++) {
+                    const toolCall = filteredToolCalls[_tcIdx];
+                    this.throwIfAborted(options?.signal);
+                    if (!this.consumeToolCallBudget(toolCallBudget, toolCall.name)) {
+                        stopReason = "max-tool-calls";
+                        for (let _skipIdx = _tcIdx; _skipIdx < filteredToolCalls.length; _skipIdx++) {
+                            const _skipped = filteredToolCalls[_skipIdx];
+                            const _skipMsg = this.deps.history.pushToolResult(_skipped.name, `\u26a0\ufe0f Tool call skipped: tool call budget exhausted.`, _skipped.id ?? `call_skip_${Date.now()}_${_skipIdx}`);
+                            this.deps.eventsBus.pushMessage(_skipMsg);
+                        }
+                        break;
+                    }
+                    const signature = `${toolCall.name}:${JSON.stringify(toolCall.arguments ?? {})}`;
+                    const isDuplicate = uniqueSignatures.has(signature);
+                    this.trackStallSignals(toolCall.name, toolCall.arguments, uniqueSignatures, recentSignatures);
+                    if (ACTION_TOOLS.has(toolCall.name)) {
+                        consecutiveReadOnly = 0;
+                        recentSignatures.length = 0;
+                    }
+                    else if (READ_ONLY_TOOLS.has(toolCall.name)) {
+                        consecutiveReadOnly++;
+                    }
+                    else {
+                        consecutiveReadOnly = 0;
+                    }
+                    const stallResult = this.checkStall(consecutiveReadOnly, recentSignatures, STALL_LIMIT, uniqueSignatures);
+                    if (stallResult) {
+                        stopReason = stallResult;
+                        for (let _skipIdx = _tcIdx; _skipIdx < filteredToolCalls.length; _skipIdx++) {
+                            const _skipped = filteredToolCalls[_skipIdx];
+                            const _skipMsg = this.deps.history.pushToolResult(_skipped.name, `\u26a0\ufe0f Tool call skipped: ${stallResult === "stall" ? "stall detected after too many consecutive read-only tool calls" : "repetition detected after repeated identical tool calls"}.`, _skipped.id ?? `call_skip_${Date.now()}_${_skipIdx}`);
+                            this.deps.eventsBus.pushMessage(_skipMsg);
+                        }
+                        break;
+                    }
+                    const execution = await this.executeToolWithRetry(toolCall.name, toolCall.arguments ?? {}, options, runtimeMetadata);
+                    this.deps.eventsBus.pushToolEvent(execution.startedTrace);
+                    this.deps.eventsBus.pushToolEvent(execution.trace);
+                    toolExecutions.push(execution.trace);
+                    const duplicatePrefix = isDuplicate
+                        ? `[DUPLICATE CALL: you already called '${toolCall.name}' with these exact arguments. Below is the same result. Stop repeating this call.]\n\n`
+                        : "";
+                    const toolOutput = execution.result.success
+                        ? duplicatePrefix + (execution.result.output ?? "")
+                        : `ERROR: ${execution.result.error ?? "Unknown tool error"}`;
+                    const toolMessage = this.deps.history.pushToolResult(toolCall.name, toolOutput, toolCall.id ?? execution.trace.id);
+                    this.deps.eventsBus.pushMessage(toolMessage);
+                    if (this.injectTerminationHint(consecutiveReadOnly)) {
+                        stopReason = "stall";
+                        break;
+                    }
+                    // Doom-loop injection: escalate after repeated identical calls.
+                    if (isDuplicate) {
+                        const doomCount = (doomLoopCounts.get(signature) ?? 0) + 1;
+                        doomLoopCounts.set(signature, doomCount);
+                        if (doomCount >= DOOM_LOOP_THRESHOLD) {
+                            this.log.info("runner", `doom-loop  ${toolCall.name}  count=${doomCount + 1}`);
+                            const doomMsg = this.deps.history.push("user", `⚠️ Doom-loop warning: You have called '${toolCall.name}' with identical arguments ${doomCount + 1} times. ` +
+                                `This call cannot produce a different result. You MUST break this loop now: ` +
+                                `try a different tool, a different approach, or conclude and summarize your findings.`);
+                            this.deps.eventsBus.pushMessage(doomMsg);
+                        }
+                    }
+                    const commandResult = this.applyToolCommand(execution.result.command, runtimeMetadata);
+                    runtimeMetadata = commandResult.metadata;
+                    if (commandResult.goto === "end_turn") {
+                        this.ensureToolResultsForBatch(filteredToolCalls, "turn ended by tool command");
+                        await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+                        this.transition(contracts_1.ConversationStatus.COMPLETED);
+                        return {
+                            output: commandResult.outputOverride ?? finalOutput,
+                            thinking: lastThinking,
+                            stopReason: "completed",
+                            status: this.deps.statusMachine.current,
+                            messages: this.deps.history.snapshot(),
+                            toolExecutions,
+                            tokensInput: totalTokensIn,
+                            tokensOutput: totalTokensOut,
+                            iterationsUsed
+                        };
+                    }
+                    if (commandResult.goto === "next_iteration") {
+                        break;
+                    }
+                }
+                // ── Placeholder results for unmatched tool calls (DeepSeek compat) ─
+                if (stopReason && stopReason !== "completed") {
+                    this.ensureToolResultsForBatch(filteredToolCalls, "execution terminated early");
+                }
+                if (stopReason !== "completed") {
+                    await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+                    break;
+                }
+                await this.deps.onTurnComplete?.([...this.deps.history.snapshot()]);
+                this.transition(contracts_1.ConversationStatus.RUNNING);
+            }
+            if (stopReason === "aborted" || options?.signal?.aborted) {
+                stopReason = "aborted";
+                this.transition(contracts_1.ConversationStatus.CANCELLED);
+            }
+            else {
+                this.transition(contracts_1.ConversationStatus.COMPLETED);
+            }
+            this.deps.eventsBus.pushAgentUpdate("run_complete", {
+                phase: "resume",
+                stopReason,
+                iterations: iterationsUsed,
+                namespace: this.resolveStreamNamespace(runtimeMetadata),
+            });
+            return {
+                output: "",
+                thinking: lastThinking,
+                stopReason,
+                status: this.deps.statusMachine.current,
+                messages: this.deps.history.snapshot(),
+                toolExecutions,
+                tokensInput: totalTokensIn,
+                tokensOutput: totalTokensOut,
+                iterationsUsed
+            };
+        }
+        catch (error) {
+            this.restorePendingInterrupt(null);
+            if (this.isAbortError(error)) {
+                this.transition(contracts_1.ConversationStatus.CANCELLED);
+                return {
+                    output: "",
+                    thinking: lastThinking,
+                    stopReason: "aborted",
+                    status: this.deps.statusMachine.current,
+                    messages: this.deps.history.snapshot(),
+                    toolExecutions,
+                    tokensInput: totalTokensIn,
+                    tokensOutput: totalTokensOut,
+                    iterationsUsed
+                };
+            }
+            const err = error instanceof Error ? error : new Error("Unknown conversation error");
+            this.transition(contracts_1.ConversationStatus.FAILED);
+            this.deps.eventsBus.pushError(err);
+            throw err;
+        }
+    }
+    // ─────────────────────────────────────────────────────────────
+    // Helpers
+    // ─────────────────────────────────────────────────────────────
+    buildPendingInterrupt(toolCalls) {
+        if (!toolCalls.length)
+            return null;
+        const interruptToolCalls = [];
+        for (let i = 0; i < toolCalls.length; i++) {
+            const toolCall = toolCalls[i];
+            const resolved = this.resolveInterruptConfig(toolCall.name);
+            if (!resolved)
+                continue;
+            interruptToolCalls.push({ index: i, toolCall, config: resolved });
+        }
+        if (!interruptToolCalls.length)
+            return null;
+        const actionRequests = interruptToolCalls.map(({ toolCall, config }) => ({
+            name: toolCall.name,
+            args: toolCall.arguments ?? {},
+            description: config.description ??
+                `${this.deps.interruptDescriptionPrefix ?? "Tool execution requires approval"}\n\nTool: ${toolCall.name}\nArgs: ${JSON.stringify(toolCall.arguments ?? {}, null, 2)}`
+        }));
+        const reviewConfigs = interruptToolCalls.map(({ toolCall, config }) => ({
+            actionName: toolCall.name,
+            allowedDecisions: [...config.allowedDecisions]
+        }));
+        const interrupt = {
+            id: `interrupt_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`,
+            request: {
+                actionRequests,
+                reviewConfigs
+            },
+            createdAt: new Date().toISOString()
+        };
+        return {
+            interrupt,
+            toolCalls: toolCalls.map((toolCall) => ({
+                id: toolCall.id,
+                name: toolCall.name,
+                arguments: { ...(toolCall.arguments ?? {}) }
+            })),
+            interruptToolCalls
+        };
+    }
+    resolveInterruptConfig(toolName) {
+        const interruptOn = this.deps.interruptOn;
+        if (!interruptOn)
+            return null;
+        const config = interruptOn[toolName];
+        if (config === undefined || config === false) {
+            return null;
+        }
+        if (config === true) {
+            return {
+                allowedDecisions: [...contracts_1.DEFAULT_INTERRUPT_DECISIONS]
+            };
+        }
+        const allowedDecisions = config.allowedDecisions && config.allowedDecisions.length > 0
+            ? [...config.allowedDecisions]
+            : [...contracts_1.DEFAULT_INTERRUPT_DECISIONS];
+        return {
+            allowedDecisions,
+            description: config.description
+        };
+    }
+    applyInterruptDecisions(response, pending) {
+        const decisions = response?.decisions;
+        if (!decisions || !Array.isArray(decisions)) {
+            throw new Error("Invalid HITLResponse: decisions must be a non-empty array");
+        }
+        if (decisions.length !== pending.interruptToolCalls.length) {
+            throw new Error(`Number of human decisions (${decisions.length}) does not match number of hanging tool calls (${pending.interruptToolCalls.length}).`);
+        }
+        const revisedToolCalls = [];
+        const artificialToolMessages = [];
+        let hasRejectedToolCalls = false;
+        let interruptDecisionIndex = 0;
+        for (let i = 0; i < pending.toolCalls.length; i++) {
+            const toolCall = pending.toolCalls[i];
+            const interruptToolCall = pending.interruptToolCalls.find((entry) => entry.index === i);
+            if (!interruptToolCall) {
+                revisedToolCalls.push(toolCall);
+                continue;
+            }
+            const decision = decisions[interruptDecisionIndex++];
+            const processed = this.processDecision(decision, toolCall, interruptToolCall.config);
+            if (decision.type === "reject") {
+                hasRejectedToolCalls = true;
+            }
+            if (processed.revisedToolCall) {
+                revisedToolCalls.push(processed.revisedToolCall);
+            }
+            if (processed.toolMessage) {
+                artificialToolMessages.push({ toolName: toolCall.name, content: processed.toolMessage, toolCallId: toolCall.id });
+            }
+        }
+        if (hasRejectedToolCalls) {
+            for (const call of revisedToolCalls) {
+                if (!artificialToolMessages.some((msg) => msg.toolName === call.name)) {
+                    artificialToolMessages.push({
+                        toolName: call.name,
+                        content: `Tool call '${call.name}' deferred because another reviewed action in this batch was rejected.`,
+                        toolCallId: call.id,
+                    });
+                }
+            }
+        }
+        return {
+            revisedToolCalls,
+            artificialToolMessages,
+            hasRejectedToolCalls
+        };
+    }
+    resolveResumeResponse(response, pending) {
+        if (response &&
+            typeof response === "object" &&
+            !Array.isArray(response) &&
+            "decisions" in response) {
+            return response;
+        }
+        if (!response || typeof response !== "object" || Array.isArray(response)) {
+            throw new Error("Invalid resume payload. Expected decisions array or interrupt-id map.");
+        }
+        const mapped = response[pending.interrupt.id];
+        if (!mapped) {
+            throw new Error(`Missing resume response for interrupt id '${pending.interrupt.id}'.`);
+        }
+        return mapped;
+    }
+    processDecision(decision, toolCall, config) {
+        const allowedDecisions = config.allowedDecisions;
+        if (decision.type === "approve" && allowedDecisions.includes("approve")) {
+            return {
+                revisedToolCall: {
+                    name: toolCall.name,
+                    arguments: { ...(toolCall.arguments ?? {}) }
+                },
+                toolMessage: null
+            };
+        }
+        if (decision.type === "edit" && allowedDecisions.includes("edit")) {
+            if (!decision.editedAction || typeof decision.editedAction.name !== "string") {
+                throw new Error(`Invalid edited action for tool "${toolCall.name}": name must be a string`);
+            }
+            if (!decision.editedAction.args || typeof decision.editedAction.args !== "object") {
+                throw new Error(`Invalid edited action for tool "${toolCall.name}": args must be an object`);
+            }
+            return {
+                revisedToolCall: {
+                    name: decision.editedAction.name,
+                    arguments: { ...(decision.editedAction.args ?? {}) }
+                },
+                toolMessage: null
+            };
+        }
+        if (decision.type === "reject" && allowedDecisions.includes("reject")) {
+            if (decision.message !== undefined && typeof decision.message !== "string") {
+                throw new Error(`Tool call response for "${toolCall.name}" must be a string, got ${typeof decision.message}`);
+            }
+            return {
+                revisedToolCall: null,
+                toolMessage: decision.message ??
+                    `User rejected the tool call for '${toolCall.name}'. Please revise your plan.`
+            };
+        }
+        throw new Error(`Unexpected human decision: ${JSON.stringify(decision)}. Decision type '${decision.type}' is not allowed for tool '${toolCall.name}'. Expected one of ${JSON.stringify(allowedDecisions)} based on the tool's configuration.`);
+    }
+    cloneInterrupt(interrupt) {
+        return {
+            id: interrupt.id,
+            createdAt: interrupt.createdAt,
+            request: {
+                actionRequests: interrupt.request.actionRequests.map((action) => ({
+                    name: action.name,
+                    args: { ...(action.args ?? {}) },
+                    description: action.description
+                })),
+                reviewConfigs: interrupt.request.reviewConfigs.map((config) => ({
+                    actionName: config.actionName,
+                    allowedDecisions: [...config.allowedDecisions]
+                }))
+            }
+        };
+    }
+    toPendingInterruptSnapshot(pending) {
+        return {
+            interrupt: this.cloneInterrupt(pending.interrupt),
+            toolCalls: pending.toolCalls.map((toolCall) => ({
+                name: toolCall.name,
+                args: { ...(toolCall.arguments ?? {}) }
+            })),
+            interruptTools: pending.interruptToolCalls.map((item) => ({
+                index: item.index,
+                config: {
+                    allowedDecisions: [...item.config.allowedDecisions],
+                    description: item.config.description
+                }
+            }))
+        };
+    }
+    applyToolCommand(command, currentMetadata) {
+        if (!command) {
+            return {
+                metadata: currentMetadata,
+                goto: "continue",
+            };
+        }
+        const mergedMetadata = this.normalizeRuntimeMetadata({
+            ...currentMetadata,
+            ...(command.update?.state ?? {}),
+            ...(command.update?.metadata ?? {}),
+        });
+        const goto = command.goto ?? "continue";
+        return {
+            metadata: mergedMetadata,
+            goto,
+            outputOverride: command.message,
+        };
+    }
+    trackStallSignals(toolName, args, uniqueSignatures, recentSignatures) {
+        const sig = `${toolName}:${JSON.stringify(args ?? {})}`;
+        uniqueSignatures.add(sig);
+        recentSignatures.push(sig);
+        if (recentSignatures.length > 12)
+            recentSignatures.shift();
+    }
+    checkStall(consecutiveReadOnly, recentSignatures, stallLimit, uniqueSignatures) {
+        if (!this.deps.stallDetection)
+            return null;
+        if (consecutiveReadOnly >= stallLimit) {
+            return "stall";
+        }
+        if (recentSignatures.length >= 8) {
+            const unique = new Set(recentSignatures);
+            if (unique.size <= 3)
+                return "repetition";
+        }
+        return null;
+    }
+    ensureToolResultsForBatch(filteredToolCalls, reason) {
+        const snapshot = this.deps.history.snapshot();
+        const executedIds = new Set();
+        for (const msg of snapshot) {
+            if (msg.role === "tool" && msg.toolCallId)
+                executedIds.add(msg.toolCallId);
+        }
+        for (const tc of filteredToolCalls) {
+            if (tc.id && !executedIds.has(tc.id)) {
+                this.deps.history.pushToolResult(tc.name, `⚠️ Skipped: ${reason}.`, tc.id);
+            }
+        }
+    }
+    injectTerminationHint(consecutiveReadOnly) {
+        if (consecutiveReadOnly < TERMINATION_HINT_AFTER)
+            return false;
+        if (consecutiveReadOnly >= MAX_CONSECUTIVE_READ_ONLY) {
+            const stopMsg = this.deps.history.push("user", `⚠️ You have made ${consecutiveReadOnly} consecutive read-only tool calls. ` +
+                `You have enough information. You MUST now produce your FINAL answer directly — ` +
+                `do NOT call any more tools. Summarize your findings and respond to the user.`);
+            this.deps.eventsBus.pushMessage(stopMsg);
+            return true;
+        }
+        const hintMsg = this.deps.history.push("user", `You have made ${consecutiveReadOnly} read-only calls in a row. ` +
+            `You likely have enough context now. Unless you need specific additional data, ` +
+            `please conclude and produce your final answer directly — do not call more tools.`);
+        this.deps.eventsBus.pushMessage(hintMsg);
+        return false;
+    }
+    resolveModelForIteration(phase, iteration) {
+        const defaultModel = this.deps.getModel();
+        const selectedModel = this.deps.selectModel?.({
+            phase,
+            iteration,
+            defaultModel,
+            messages: this.deps.history.snapshot(),
+        });
+        if (typeof selectedModel !== "string") {
+            return defaultModel;
+        }
+        const trimmed = selectedModel.trim();
+        return trimmed.length > 0 ? trimmed : defaultModel;
+    }
+    normalizeMaxIterations(value) {
+        if (typeof value !== "number") {
+            return undefined;
+        }
+        if (!Number.isFinite(value)) {
+            return undefined;
+        }
+        return Math.max(0, Math.floor(value));
+    }
+    createToolCallBudget(maxToolCalls, maxToolCallsPerTool) {
+        const maxTotal = this.normalizePositiveInt(maxToolCalls);
+        const maxPerTool = {};
+        if (maxToolCallsPerTool && typeof maxToolCallsPerTool === "object") {
+            for (const [toolName, limit] of Object.entries(maxToolCallsPerTool)) {
+                const normalized = this.normalizePositiveInt(limit);
+                if (normalized !== undefined) {
+                    maxPerTool[toolName] = normalized;
+                }
+            }
+        }
+        return {
+            maxTotal,
+            maxPerTool,
+            totalUsed: 0,
+            perToolUsed: new Map(),
+        };
+    }
+    consumeToolCallBudget(budget, toolName) {
+        if (budget.maxTotal !== undefined && budget.totalUsed >= budget.maxTotal) {
+            return false;
+        }
+        const perToolLimit = budget.maxPerTool[toolName];
+        const perToolUsed = budget.perToolUsed.get(toolName) ?? 0;
+        if (perToolLimit !== undefined && perToolUsed >= perToolLimit) {
+            return false;
+        }
+        budget.totalUsed += 1;
+        budget.perToolUsed.set(toolName, perToolUsed + 1);
+        return true;
+    }
+    normalizePositiveInt(value) {
+        if (typeof value !== "number") {
+            return undefined;
+        }
+        if (!Number.isFinite(value)) {
+            return undefined;
+        }
+        const normalized = Math.floor(value);
+        return normalized > 0 ? normalized : undefined;
+    }
+    resolveStreamNamespace(metadata) {
+        const fromStreamNamespace = metadata["streamNamespace"];
+        if (typeof fromStreamNamespace === "string" && fromStreamNamespace.trim().length > 0) {
+            return fromStreamNamespace.trim();
+        }
+        const fromNamespace = metadata["namespace"];
+        if (typeof fromNamespace === "string" && fromNamespace.trim().length > 0) {
+            return fromNamespace.trim();
+        }
+        return "root";
+    }
+    async resolveAllowedToolSpecs(phase, iteration, metadata, userMessage) {
+        const allSpecs = this.deps.toolRegistry.getLlmToolSpecs();
+        // Apply tool router if configured (before toolFilter)
+        let specs = allSpecs;
+        if (this.deps.toolRouter && userMessage) {
+            try {
+                const allTools = this.deps.toolRegistry.getAll();
+                const messages = this.deps.history.snapshot();
+                const historyText = messages.slice(-4).map((m) => m.content).join("\n").slice(-1000);
+                const result = await this.deps.toolRouter.selectTools(userMessage, allTools, { phase, iteration, conversationHistory: historyText });
+                specs = result.toolSpecs;
+            }
+            catch {
+                specs = allSpecs; // fallback to all tools on error
+            }
+        }
+        if (!this.deps.toolFilter) {
+            return specs;
+        }
+        const permissions = this.extractPermissions(metadata);
+        return specs.filter((tool) => {
+            return this.deps.toolFilter?.({
+                phase,
+                iteration,
+                toolName: tool.name,
+                metadata,
+                permissions,
+            }) !== false;
+        });
+    }
+    isToolAllowed(phase, iteration, toolName, metadata) {
+        if (!this.deps.toolFilter) {
+            return true;
+        }
+        const permissions = this.extractPermissions(metadata);
+        return this.deps.toolFilter({
+            phase,
+            iteration,
+            toolName,
+            metadata,
+            permissions,
+        }) !== false;
+    }
+    extractPermissions(metadata) {
+        const raw = metadata["permissions"];
+        if (!Array.isArray(raw)) {
+            return [];
+        }
+        return raw.filter((item) => typeof item === "string");
+    }
+    filterBlockedToolCalls(toolCalls, context, toolExecutions) {
+        const allowed = [];
+        for (const toolCall of toolCalls) {
+            if (this.isToolAllowed(context.phase, context.iteration, toolCall.name, context.metadata)) {
+                allowed.push(toolCall);
+                continue;
+            }
+            const skipped = this.createSkippedToolTrace(toolCall.name, toolCall.arguments, "Tool blocked by dynamic toolFilter.");
+            this.deps.eventsBus.pushToolEvent(skipped);
+            toolExecutions.push(skipped);
+            const blockedMessage = this.deps.history.pushToolResult(toolCall.name, `ERROR: Tool '${toolCall.name}' is blocked by toolFilter for phase '${context.phase}'.`, toolCall.id ?? `call_blocked_${Date.now()}`);
+            this.deps.eventsBus.pushMessage(blockedMessage);
+        }
+        return allowed;
+    }
+    createSkippedToolTrace(toolName, input, reason) {
+        const now = new Date().toISOString();
+        return {
+            id: `tool_skipped_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+            toolName,
+            input,
+            status: "SKIPPED",
+            startedAt: now,
+            endedAt: now,
+            durationMs: 0,
+            error: reason,
+        };
+    }
+    async executeToolWithRetry(name, args, options, runtimeMetadata) {
+        const retryConfig = this.resolveToolRetryConfig(name, args);
+        let attempt = 0;
+        for (;;) {
+            const execution = await this.deps.toolRegistry.execute(name, args, {
+                conversationId: this.deps.conversationId,
+                sessionId: this.deps.sessionId,
+                signal: options?.signal,
+                state: runtimeMetadata ?? options?.metadata,
+                runtimeContext: runtimeMetadata ?? options?.metadata,
+                metadata: runtimeMetadata ?? options?.metadata,
+                conversation: this.deps.caller,
+                emitProgress: (message, data) => {
+                    const progressTrace = {
+                        id: `tool_progress_${Date.now()}`,
+                        toolName: name,
+                        input: args,
+                        status: "RUNNING",
+                        startedAt: new Date().toISOString(),
+                        output: message,
+                        error: data ? JSON.stringify(data) : undefined
+                    };
+                    this.deps.eventsBus.pushToolEvent(progressTrace);
+                    this.deps.eventsBus.pushCustomEvent("tool_progress", {
+                        toolName: name,
+                        message,
+                        data: data ? JSON.stringify(data) : undefined,
+                        attempt: attempt + 1,
+                        namespace: this.resolveStreamNamespace(runtimeMetadata ?? options?.metadata ?? {}),
+                    });
+                }
+            });
+            if (execution.result.success) {
+                return execution;
+            }
+            if (!retryConfig || attempt >= retryConfig.maxRetries) {
+                return execution;
+            }
+            attempt += 1;
+            this.deps.eventsBus.pushAgentUpdate("tool_retry", {
+                toolName: name,
+                attempt,
+                namespace: this.resolveStreamNamespace(runtimeMetadata ?? options?.metadata ?? {}),
+            });
+            if (retryConfig.retryDelayMs > 0) {
+                await this.waitForRetryDelay(retryConfig.retryDelayMs, options?.signal);
+            }
+        }
+    }
+    resolveToolRetryConfig(toolName, input) {
+        const policy = this.deps.toolRetryPolicy;
+        if (!policy) {
+            return null;
+        }
+        const maxRetries = this.normalizePositiveInt(policy.maxRetries);
+        if (!maxRetries) {
+            return null;
+        }
+        const tool = this.deps.toolRegistry.getAll().find((entry) => entry.name === toolName);
+        if (tool?.isDestructive?.(input)) {
+            return null;
+        }
+        const allowlist = new Set((policy.retryableTools ?? []).filter((name) => typeof name === "string"));
+        const isRetryable = tool?.retryable === true || allowlist.has(toolName);
+        if (!isRetryable) {
+            return null;
+        }
+        return {
+            maxRetries,
+            retryDelayMs: Math.max(0, policy.retryDelayMs ?? 0),
+        };
+    }
+    async waitForRetryDelay(ms, signal) {
+        await new Promise((resolve, reject) => {
+            if (signal?.aborted) {
+                reject(new Error("Conversation aborted"));
+                return;
+            }
+            const timer = setTimeout(() => {
+                signal?.removeEventListener("abort", onAbort);
+                resolve();
+            }, ms);
+            const onAbort = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                reject(new Error("Conversation aborted"));
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    async executeTool(name, args, toolExecutions, options, runtimeMetadata) {
+        const execution = await this.executeToolWithRetry(name, args, options, runtimeMetadata);
+        this.deps.eventsBus.pushToolEvent(execution.startedTrace);
+        this.deps.eventsBus.pushToolEvent(execution.trace);
+        toolExecutions.push(execution.trace);
+        return execution.result;
+    }
+    transition(status) {
+        const next = this.deps.statusMachine.transitionTo(status);
+        this.deps.eventsBus.setStatus(next);
+    }
+    normalizeRuntimeMetadata(metadata) {
+        const candidate = { ...(metadata ?? {}) };
+        if (!this.deps.normalizeRuntimeMetadata) {
+            return candidate;
+        }
+        return this.deps.normalizeRuntimeMetadata(candidate);
+    }
+    throwIfAborted(signal) {
+        if (signal?.aborted)
+            throw new Error("Conversation aborted");
+    }
+    isAbortError(error) {
+        if (error instanceof Error && /aborted/i.test(error.message))
+            return true;
+        // DOMException (AbortError / TimeoutError) from fetch — in Node < 21, DOMException does not
+        // extend Error, so we check the duck-typed `name` property directly.
+        if (error != null && typeof error === "object") {
+            const name = error.name;
+            if (name === "AbortError" || name === "TimeoutError")
+                return true;
+        }
+        return false;
+    }
+}
+exports.ConversationRunner = ConversationRunner;
+//# sourceMappingURL=conversation-runner.class.js.map