kagent-ts 0.1.4 → 0.1.5

package/dist/core/fusion-agent.js

@@ -0,0 +1,769 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FusionAgent = void 0;
+const agent_1 = require("./agent");
+const message_1 = require("../messages/message");
+const types_1 = require("../messages/types");
+const response_schema_1 = require("./response-schema");
+const system_prompts_1 = require("./system-prompts");
+const errors_1 = require("../llm/errors");
+const interface_1 = require("../llm/interface");
+const boundaries_1 = require("../security/boundaries");
+const reflection_agent_1 = require("../reflection/reflection-agent");
+// ─── System Prompt ────────────────────────────────────────────────────────
+const DEFAULT_FUSION_SYSTEM_PROMPT = `You are a helpful AI assistant powered by the Fusion Agent paradigm.
+You dynamically adapt your strategy to the task's complexity.
+
+For SIMPLE tasks: direct ReAct (Reasoning + Acting) loop.
+For COMPLEX tasks: Plan → Execute → Reflect.
+
+You have access to a set of tools you can use to answer the user's question.
+${system_prompts_1.SECURITY_GUIDANCE}
+${system_prompts_1.TOOL_ERROR_RECOVERY}${response_schema_1.FUSION_EXECUTION_INSTRUCTIONS}`;
+// ─── FusionAgent ──────────────────────────────────────────────────────────
+/**
+ * Fusion Agent that dynamically combines ReAct, Plan-and-Solve, and
+ * Reflection paradigms based on task complexity.
+ *
+ * ## Execution flow:
+ * ```
+ * User Input
+ *   ↓
+ * [1. Route]    LLM judges complexity → simple / complex
+ *   ↓
+ * ├─ simple ──→ [3. ReAct Execute Loop]
+ * │
+ * └─ complex → [2. Plan]  LLM creates step-by-step plan
+ *                 ↓
+ *               [Confirm?]  Optional user approval
+ *                 ↓
+ *               [3. ReAct Execute Loop]  With plan tracking
+ *   ↓
+ * [4. Reflect]  off | post-hoc | inline | both
+ *   ↓
+ * Final Answer
+ * ```
+ *
+ * ## Session persistence
+ * When `enableCheckpointing` is set, the agent auto-saves checkpoints
+ * that include full fusion state (complexity, plan, reflection progress)
+ * so the session can be resumed after a network interruption.
+ */
+class FusionAgent extends agent_1.Agent {
+    // ── Configuration ───────────────────────────────────────────────────
+    routing;
+    planConfirmation;
+    onPlanConfirm;
+    maxPlanSteps;
+    reflectionMode;
+    reflectionInterval;
+    notebook;
+    maxIterations;
+    replanThreshold;
+    // ── Runtime state ───────────────────────────────────────────────────
+    /** Task complexity determined during routing. */
+    complexity = "complex";
+    /** Whether routing has been completed. */
+    routed = false;
+    /** The current plan steps (empty until the plan is created). */
+    currentPlan = [];
+    /** Whether a plan has been created in this run. */
+    hasPlan = false;
+    /** How many plan steps have been completed. */
+    completedSteps = 0;
+    /** Consecutive tool failures (resets on success). */
+    consecutiveFailures = 0;
+    /** How many inline reflections have been done in this run. */
+    inlineReflectionsDone = 0;
+    /** Internal flag: when true, run() skips state reset (used by resume()). */
+    _skipStateReset = false;
+    /** Routing reason for logging. */
+    routeReason = "";
+    constructor(config) {
+        const mergedConfig = {
+            ...config,
+            systemPrompt: config.systemPrompt ?? DEFAULT_FUSION_SYSTEM_PROMPT,
+        };
+        super(mergedConfig);
+        this.routing = config.routing ?? "auto";
+        this.planConfirmation = config.planConfirmation ?? "auto";
+        this.onPlanConfirm = config.onPlanConfirm;
+        this.maxPlanSteps = config.maxPlanSteps ?? 12;
+        this.reflectionMode = config.reflection ?? "off";
+        this.reflectionInterval = config.reflectionInterval ?? 3;
+        this.notebook = config.notebook;
+        this.maxIterations = config.maxIterations ?? 15;
+        this.replanThreshold = config.replanThreshold ?? 2;
+        // Validate: notebook required for post-hoc/both modes
+        if ((this.reflectionMode === "post-hoc" || this.reflectionMode === "both") &&
+            !this.notebook) {
+            throw new Error("FusionAgent: 'notebook' (ErrorNotebook) is required when reflection is 'post-hoc' or 'both'.");
+        }
+        this.rebuildSystemPrompt();
+    }
+    // ─── Main Entry Point ───────────────────────────────────────────────
+    async run(input) {
+        // Consume the skip-reset flag immediately
+        const skipStateReset = this._skipStateReset;
+        this._skipStateReset = false;
+        // ── Pre-flight: reject oversized input ───────────────────────────
+        const sizeError = this.validateInputSize(input);
+        if (sizeError)
+            return sizeError;
+        // ── Create fresh abort controller for this run ───────────────────
+        this._abortController = new AbortController();
+        // ── Async initialization ─────────────────────────────────────────
+        await this.init();
+        // ── Reload dynamic resources ─────────────────────────────────────
+        await this.reloadDynamicResources();
+        // ── Recover orphaned sub-agent results ───────────────────────────
+        this.recoverOrphanedSubAgentResults();
+        // ── Create user message ──────────────────────────────────────────
+        const userMessage = message_1.Message.user(input);
+        this.contextManager.addMessage(userMessage.toDict());
+        // ── Reset runtime state for this run ─────────────────────────────
+        if (!skipStateReset) {
+            this.complexity = "complex";
+            this.routed = false;
+            this.routeReason = "";
+            this.currentPlan = [];
+            this.hasPlan = false;
+            this.completedSteps = 0;
+            this.consecutiveFailures = 0;
+            this.inlineReflectionsDone = 0;
+        }
+        // Save initial checkpoint
+        if (this.checkpointingEnabled) {
+            this.saveCheckpoint("active");
+        }
+        // ── Phase 1: Route ───────────────────────────────────────────────
+        if (this.routing === "auto") {
+            const routeResult = await this.route(input);
+            this.complexity = routeResult.complexity;
+            this.routeReason = routeResult.reason;
+            this.routed = true;
+            this.logger.info("Fusion", `Route: ${this.complexity} — ${this.routeReason}`);
+        }
+        else if (this.routing === "force-react") {
+            this.complexity = "simple";
+            this.routed = true;
+            this.logger.info("Fusion", "Route: simple (forced)");
+        }
+        else {
+            // force-plan
+            this.complexity = "complex";
+            this.routed = true;
+            this.logger.info("Fusion", "Route: complex (forced)");
+        }
+        // Save checkpoint after routing
+        if (this.checkpointingEnabled) {
+            this.saveCheckpoint("active");
+        }
+        // ── Phase 2: Plan (complex tasks only) ────────────────────────────
+        if (this.complexity === "complex") {
+            const planResult = await this.createPlan(input);
+            if (typeof planResult === "string") {
+                // planResult is a string → plan was aborted / returned as answer
+                for (const h of this.hooks)
+                    h.onFinish?.(planResult);
+                return planResult;
+            }
+            // planResult is string[] → plan was confirmed, continue
+            this.currentPlan = planResult;
+            this.hasPlan = true;
+            for (const h of this.hooks)
+                h.onPlanCreated?.(this.currentPlan);
+            // Save checkpoint after plan creation
+            if (this.checkpointingEnabled) {
+                this.saveCheckpoint("active");
+            }
+        }
+        // ── Phase 3: ReAct Execute Loop ───────────────────────────────────
+        const answer = await this.executeReActLoop();
+        // ── Phase 4: Reflection ───────────────────────────────────────────
+        await this.runReflection(input, answer);
+        for (const h of this.hooks)
+            h.onFinish?.(answer);
+        return answer;
+    }
+    // ─── Phase 1: Route (Complexity Classification) ─────────────────────
+    /**
+     * Ask the LLM to classify the task complexity.
+     *
+     * Sends a lightweight prompt separate from the main conversation so
+     * the routing doesn't pollute the execution context.
+     */
+    async route(input) {
+        const messages = [
+            { role: types_1.Role.System, content: response_schema_1.FUSION_ROUTE_INSTRUCTIONS },
+            { role: types_1.Role.User, content: input },
+        ];
+        try {
+            const response = await this.llm.chat(messages, [], this._abortController?.signal);
+            const parsed = (0, response_schema_1.parseFusionRouteResponse)(response.content);
+            // Record token usage
+            if (response.usage) {
+                this.tokenBudget?.recordUsage(response.usage.prompt_tokens, response.usage.completion_tokens);
+            }
+            return parsed;
+        }
+        catch (err) {
+            if (err instanceof errors_1.LLMNetworkError) {
+                this.logger.warn("Fusion", `Route LLM call failed: ${err.message}. Defaulting to complex.`);
+            }
+            // Default to complex for safety
+            return {
+                complexity: "complex",
+                reason: "Route classification failed; defaulting to complex to be safe.",
+            };
+        }
+    }
+    // ─── Phase 2: Plan (Plan Generation) ────────────────────────────────
+    /**
+     * Generate a plan for a complex task.
+     *
+     * Sends the user input to the LLM with plan-generation instructions.
+     * If plan confirmation is configured, asks the user before proceeding.
+     *
+     * @returns The plan steps (string[]), or the plan text if confirmation
+     *          was denied (returned as the final answer string).
+     */
+    async createPlan(input) {
+        // Rebuild system prompt with plan-generation context
+        const planPrompt = this.buildSystemPrompt() +
+            "\n\nYou are in the PLANNING phase. Analyze the user's request and create a detailed, " +
+            "step-by-step plan. Output ONLY: {\"thought\": \"...\", \"plan\": [\"Step 1: ...\", ...]}\n" +
+            `Maximum ${this.maxPlanSteps} steps. Each step must be concrete and actionable.`;
+        this.contextManager.setSystemMessage(planPrompt);
+        const contextMessages = this.contextManager.getContextMessages();
+        // Token budget check
+        const estimatedInput = this.contextManager.getCurrentTokens();
+        const budgetError = this.checkTokenBudget(estimatedInput);
+        if (budgetError)
+            return budgetError;
+        for (const h of this.hooks)
+            h.onLLMStart?.(contextMessages, this.toolRegistry.getTools());
+        let response;
+        try {
+            response = await this.llm.chat(contextMessages, this.toolRegistry.getTools(), this._abortController?.signal);
+        }
+        catch (err) {
+            // Cancellation by user (AbortController)
+            if (this.isCancelled) {
+                this.saveCheckpoint("cancelled");
+                const sid = this.sessionManager?.getSessionId() ?? "unknown";
+                const cancelMsg = `Execution cancelled by user. Session "${sid}" preserved — ` +
+                    `resume with agent.resume("${sid}", "<your prompt>").`;
+                for (const h of this.hooks)
+                    h.onFinish?.(cancelMsg);
+                return cancelMsg;
+            }
+            if (err instanceof errors_1.LLMNetworkError) {
+                for (const h of this.hooks)
+                    h.onLLMError?.(err);
+                return this.handleNetworkError(err, 0, "continue creating a plan");
+            }
+            throw err;
+        }
+        for (const h of this.hooks)
+            h.onLLMEnd?.(response);
+        if (response.usage) {
+            this.tokenBudget?.recordUsage(response.usage.prompt_tokens, response.usage.completion_tokens);
+        }
+        const parsed = (0, response_schema_1.parseFusionResponse)(response.content);
+        // Store the assistant message in context
+        const assistantMessage = message_1.Message.assistant(response.content, response.tool_calls);
+        this.contextManager.addMessage(assistantMessage.toDict());
+        if (parsed.plan && parsed.plan.length > 0) {
+            const plan = parsed.plan.slice(0, this.maxPlanSteps);
+            this.logger.info("Plan", `Created ${plan.length}-step plan:`);
+            for (let i = 0; i < plan.length; i++) {
+                this.logger.info("Plan", `  ${i + 1}. ${plan[i]}`);
+            }
+            // ── Plan confirmation ──────────────────────────────────────────
+            const shouldConfirm = this.shouldConfirmPlan(plan);
+            if (shouldConfirm && this.onPlanConfirm) {
+                const confirmed = await this.onPlanConfirm(plan, this.routeReason);
+                if (!confirmed) {
+                    // User rejected the plan — return it as the answer
+                    const planText = `I've created the following plan for your task. ` +
+                        `Please review and let me know if you'd like any changes:\n\n` +
+                        plan.map((s, i) => `${i + 1}. ${s}`).join("\n") +
+                        `\n\nYou can resume execution by saying "proceed" or "execute the plan".`;
+                    return planText;
+                }
+            }
+            else if (shouldConfirm && !this.onPlanConfirm) {
+                // Confirmation needed but no callback — return plan as answer
+                const planText = `I've created the following plan for your task:\n\n` +
+                    plan.map((s, i) => `${i + 1}. ${s}`).join("\n") +
+                    `\n\n(Plan confirmation is required but no confirmation callback is configured. ` +
+                    `Send your approval to continue, or set planConfirmation to "never" to auto-execute.)`;
+                return planText;
+            }
+            if (parsed.thought) {
+                this.logger.info("Thought", parsed.thought);
+                for (const h of this.hooks)
+                    h.onThought?.(parsed.thought);
+            }
+            return plan;
+        }
+        // LLM didn't generate a plan — fall back to ReAct
+        this.logger.info("Fusion", "No plan generated by LLM — falling back to direct ReAct.");
+        this.complexity = "simple";
+        return [];
+    }
+    /**
+     * Determine whether plan confirmation is needed based on the
+     * planConfirmation setting and plan content.
+     */
+    shouldConfirmPlan(_plan) {
+        switch (this.planConfirmation) {
+            case "always":
+                return true;
+            case "never":
+                return false;
+            case "auto":
+                // Auto: check if plan contains risky keywords
+                // (deploy, delete, drop, migration, etc.)
+                const riskyKeywords = [
+                    "deploy", "delete", "drop", "migrate", "truncate",
+                    "destroy", "purge", "reset", "format",
+                ];
+                const planText = _plan.join(" ").toLowerCase();
+                return riskyKeywords.some((kw) => planText.includes(kw));
+            default:
+                return false;
+        }
+    }
+    // ─── Phase 3: ReAct Execute Loop ────────────────────────────────────
+    /**
+     * Main execution loop with ReAct reasoning, plan tracking, and optional
+     * inline reflection.
+     */
+    async executeReActLoop() {
+        // Rebuild system prompt for execution mode
+        this.rebuildContextWithPlan();
+        let consecutiveEmptyIterations = 0;
+        const EMPTY_ITERATION_LIMIT = 5;
+        let consecutiveTruncations = 0;
+        const MAX_TRUNCATION_CONTINUES = 3;
+        for (let iteration = 0; iteration < this.maxIterations; iteration++) {
+            // ── Check cancellation ──────────────────────────────────────────
+            if (this.isCancelled) {
+                this.saveCheckpoint("cancelled");
+                const sid = this.sessionManager?.getSessionId() ?? "unknown";
+                const cancelMsg = `Execution cancelled by user. Session "${sid}" preserved — ` +
+                    `resume with agent.resume("${sid}", "<your prompt>").`;
+                return cancelMsg;
+            }
+            // ── Poll sub-agent results ──────────────────────────────────────
+            const subResults = await this.pollSubAgentResults();
+            for (const r of subResults) {
+                const source = `subagent:${r.name}`;
+                const msg = new message_1.Message(types_1.Role.User, (0, boundaries_1.wrapAndScan)(source, r.output), {
+                    name: source,
+                });
+                this.contextManager.addMessage(msg.toDict());
+            }
+            await this.checkAndCompress();
+            // ── Rebuild system prompt (plan progress + replan hint) ─────────
+            this.rebuildContextWithPlan();
+            // ── Token budget ────────────────────────────────────────────────
+            const contextMessages = this.contextManager.getContextMessages();
+            const budgetError = this.checkTokenBudget(this.tokenBudget ? this.contextManager.getCurrentTokens() : 0);
+            if (budgetError)
+                return budgetError;
+            // ── LLM call ────────────────────────────────────────────────────
+            for (const h of this.hooks)
+                h.onLLMStart?.(contextMessages, this.toolRegistry.getTools());
+            let response;
+            try {
+                response = await this.llm.chat(contextMessages, this.toolRegistry.getTools(), this._abortController?.signal);
+            }
+            catch (err) {
+                // Cancellation by user (AbortController) — exit the loop cleanly
+                if (this.isCancelled) {
+                    this.saveCheckpoint("cancelled");
+                    const sid = this.sessionManager?.getSessionId() ?? "unknown";
+                    const cancelMsg = `Execution cancelled by user. Session "${sid}" preserved — ` +
+                        `resume with agent.resume("${sid}", "<your prompt>").`;
+                    for (const h of this.hooks)
+                        h.onFinish?.(cancelMsg);
+                    return cancelMsg;
+                }
+                if (err instanceof errors_1.LLMNetworkError) {
+                    for (const h of this.hooks)
+                        h.onLLMError?.(err);
+                    return this.handleNetworkError(err, iteration + 1, "continue with what you were doing");
+                }
+                throw err;
+            }
+            for (const h of this.hooks)
+                h.onLLMEnd?.(response);
+            if (response.usage) {
+                this.tokenBudget?.recordUsage(response.usage.prompt_tokens, response.usage.completion_tokens);
+            }
+            const parsed = (0, response_schema_1.parseFusionResponse)(response.content);
+            // Capture LLM analysis of active tool error traces
+            if (parsed.thought) {
+                this.captureErrorAnalysis(parsed.thought);
+            }
+            // ── Store assistant message ─────────────────────────────────────
+            const assistantMessage = message_1.Message.assistant(response.content, response.tool_calls);
+            // ── Handle max_tokens truncation ────────────────────────────────
+            const isTruncated = response.responseError?.code === interface_1.LLMResponseErrorCode.MAX_TOKENS;
+            if (isTruncated) {
+                consecutiveTruncations++;
+                if (consecutiveTruncations > MAX_TRUNCATION_CONTINUES) {
+                    const fallback = parsed.answer
+                        ? parsed.answer +
+                            "\n\n[Note: Response may be incomplete due to repeated output limits.]"
+                        : "I apologize, but I'm unable to complete this response due to output length constraints. " +
+                            "Please try breaking your request into smaller steps.";
+                    return fallback;
+                }
+                this.contextManager.addMessage(assistantMessage.toDict());
+                const continueMsg = message_1.Message.user("Your previous response was cut off (max output tokens reached). " +
+                    "Continue exactly where you left off — do NOT repeat any content already written. " +
+                    "If you were calling tools, re-invoke them with complete arguments.");
+                this.contextManager.addMessage(continueMsg.toDict());
+            }
+            else {
+                this.contextManager.addMessage(assistantMessage.toDict());
+                consecutiveTruncations = 0;
+            }
+            // ── Tool calls ──────────────────────────────────────────────────
+            if (response.tool_calls && response.tool_calls.length > 0) {
+                consecutiveEmptyIterations = 0;
+                if (parsed.thought) {
+                    this.logger.info("Thought", parsed.thought);
+                    for (const h of this.hooks)
+                        h.onThought?.(parsed.thought);
+                }
+                // Non-truncation quality issues
+                if (response.responseError &&
+                    response.responseError.code !== interface_1.LLMResponseErrorCode.MAX_TOKENS &&
+                    response.responseError.code !== interface_1.LLMResponseErrorCode.OK) {
+                    const warnMsg = message_1.Message.system(`LLM response quality issue: ${response.responseError.message}`);
+                    this.contextManager.addMessage(warnMsg.toDict());
+                }
+                const mcpWarnedServers = new Set();
+                const { hadFailure } = await this.executeToolCallsBatch(response.tool_calls, mcpWarnedServers);
+                // Update failure counter and step progress
+                if (hadFailure) {
+                    this.consecutiveFailures++;
+                    this.logger.info("Fusion", `Consecutive failures: ${this.consecutiveFailures}` +
+                        (this.replanThreshold > 0 &&
+                            this.consecutiveFailures >= this.replanThreshold
+                            ? ` — threshold reached`
+                            : ""));
+                    // Inline reflection on first failure if enabled
+                    if ((this.reflectionMode === "inline" ||
+                        this.reflectionMode === "both") &&
+                        this.inlineReflectionsDone === 0) {
+                        await this.reflectInline(iteration);
+                    }
+                }
+                else {
+                    this.consecutiveFailures = 0;
+                    // Advance completed steps
+                    if (parsed.currentStep && this.hasPlan) {
+                        this.completedSteps = Math.max(this.completedSteps, Math.min(parsed.currentStep - 1, this.currentPlan.length));
+                    }
+                    else if (this.hasPlan) {
+                        this.completedSteps = Math.min(this.completedSteps + 1, this.currentPlan.length);
+                    }
+                    if (this.hasPlan) {
+                        this.logger.info("Progress", `Step ${this.completedSteps}/${this.currentPlan.length} completed`);
+                    }
+                }
+                // Save checkpoint
+                if (this.checkpointingEnabled) {
+                    this.saveCheckpoint("active");
+                }
+                // Inline reflection at regular intervals
+                if ((this.reflectionMode === "inline" ||
+                    this.reflectionMode === "both") &&
+                    (iteration + 1) % this.reflectionInterval === 0) {
+                    await this.reflectInline(iteration);
+                }
+                continue;
+            }
+            // ── Final answer ────────────────────────────────────────────────
+            if (parsed.answer) {
+                if (isTruncated) {
+                    consecutiveEmptyIterations = 0;
+                    if (parsed.thought) {
+                        this.logger.info("Thought", parsed.thought);
+                        for (const h of this.hooks)
+                            h.onThought?.(parsed.thought);
+                    }
+                    if (iteration === this.maxIterations - 1) {
+                        return (parsed.answer +
+                            "\n\n[Note: Response may be incomplete due to output length constraints.]");
+                    }
+                    this.logger.info("Fusion", "Answer truncated — continuing in next iteration.");
+                    continue;
+                }
+                if (parsed.thought) {
+                    this.logger.info("Thought", parsed.thought);
+                    for (const h of this.hooks)
+                        h.onThought?.(parsed.thought);
+                }
+                this.logger.info("Fusion", "Task complete — returning final answer.");
+                if (this.checkpointingEnabled) {
+                    this.saveCheckpoint("completed");
+                }
+                return parsed.answer;
+            }
+            // ── Plan creation (if LLM generates plan mid-execution) ─────────
+            if (!this.hasPlan &&
+                parsed.plan &&
+                Array.isArray(parsed.plan) &&
+                parsed.plan.length > 0) {
+                consecutiveEmptyIterations = 0;
+                this.currentPlan = parsed.plan.slice(0, this.maxPlanSteps);
+                this.hasPlan = true;
+                this.logger.info("Plan", `Created ${this.currentPlan.length}-step plan mid-execution:`);
+                for (let i = 0; i < this.currentPlan.length; i++) {
+                    this.logger.info("Plan", `  ${i + 1}. ${this.currentPlan[i]}`);
+                }
+                for (const h of this.hooks)
+                    h.onPlanCreated?.(this.currentPlan);
+                if (parsed.thought) {
+                    this.logger.info("Thought", parsed.thought);
+                    for (const h of this.hooks)
+                        h.onThought?.(parsed.thought);
+                }
+                continue;
+            }
+            // ── Plan revision ───────────────────────────────────────────────
+            if (parsed.revised_plan &&
+                Array.isArray(parsed.revised_plan) &&
+                parsed.revised_plan.length > 0) {
+                consecutiveEmptyIterations = 0;
+                this.currentPlan = parsed.revised_plan.slice(0, this.maxPlanSteps);
+                this.completedSteps = 0;
+                this.consecutiveFailures = 0;
+                this.logger.info("Plan", `Revised — ${this.currentPlan.length} steps remaining:`);
+                for (let i = 0; i < this.currentPlan.length; i++) {
+                    this.logger.info("Plan", `  ${i + 1}. ${this.currentPlan[i]}`);
+                }
+                for (const h of this.hooks)
+                    h.onPlanRevised?.(this.currentPlan);
+                if (parsed.thought) {
+                    this.logger.info("Thought", parsed.thought);
+                    for (const h of this.hooks)
+                        h.onThought?.(parsed.thought);
+                }
+                continue;
+            }
+            // ── Thought-only iteration ──────────────────────────────────────
+            if (parsed.thought) {
+                consecutiveEmptyIterations++;
+                this.logger.info("Thought", parsed.thought);
+                for (const h of this.hooks)
+                    h.onThought?.(parsed.thought);
+                if (consecutiveEmptyIterations >= EMPTY_ITERATION_LIMIT) {
+                    const stuckMsg = "I apologize, but I'm having difficulty making progress on your request. " +
+                        "Please try rephrasing or breaking it down into smaller, more specific steps.";
+                    const stuckAssistantMessage = message_1.Message.assistant(stuckMsg);
+                    this.contextManager.addMessage(stuckAssistantMessage.toDict());
+                    return stuckMsg;
+                }
+                continue;
+            }
+            // ── Empty response ──────────────────────────────────────────────
+            consecutiveEmptyIterations++;
+            if (consecutiveEmptyIterations >= EMPTY_ITERATION_LIMIT) {
+                const stuckMsg = "I apologize, but I'm having difficulty making progress on your request. " +
+                    "Please try rephrasing or breaking it down into smaller, more specific steps.";
+                const stuckAssistantMessage = message_1.Message.assistant(stuckMsg);
+                this.contextManager.addMessage(stuckAssistantMessage.toDict());
+                return stuckMsg;
+            }
+        }
+        // ── Max iterations reached ────────────────────────────────────────
+        const timeoutMsg = `I apologize, but I was unable to complete the task within ${this.maxIterations} iterations. ` +
+            `Please try breaking your request into smaller steps.`;
+        const timeoutAssistantMessage = message_1.Message.assistant(timeoutMsg);
+        this.contextManager.addMessage(timeoutAssistantMessage.toDict());
+        return timeoutMsg;
+    }
+    // ─── Phase 4: Reflection ────────────────────────────────────────────
+    /**
+     * Run the configured reflection strategy.
+     */
+    async runReflection(input, answer) {
+        if (this.reflectionMode === "off")
+            return;
+        // ── Post-hoc reflection ──────────────────────────────────────────
+        if (this.reflectionMode === "post-hoc" ||
+            this.reflectionMode === "both") {
+            await this.reflectPostHoc(input, answer);
+        }
+        // Inline reflection is done during the loop — nothing extra here
+    }
+    /**
+     * Inline reflection: pause execution and ask the LLM to self-check
+     * its progress. Results are logged and injected into context.
+     */
+    async reflectInline(iteration) {
+        this.inlineReflectionsDone++;
+        this.logger.info("Reflection", `Inline reflection #${this.inlineReflectionsDone} at iteration ${iteration + 1}`);
+        const reflectionMsg = message_1.Message.user(response_schema_1.INLINE_REFLECTION_PROMPT);
+        this.contextManager.addMessage(reflectionMsg.toDict());
+        // Do NOT call the LLM here — the reflection prompt is injected as a
+        // user message and will be processed in the next iteration of the
+        // main loop. This keeps the reflection lightweight and naturally
+        // integrated into the flow.
+        // Save checkpoint after inline reflection
+        if (this.checkpointingEnabled) {
+            this.saveCheckpoint("active");
+        }
+    }
+    /**
+     * Post-hoc reflection: after execution completes, run the
+     * ReflectionAgent to review the full session.
+     */
+    async reflectPostHoc(input, answer) {
+        if (!this.notebook)
+            return;
+        this.logger.info("Reflection", "Starting post-hoc reflection...");
+        try {
+            const reflector = new reflection_agent_1.ReflectionAgent({
+                llm: this.llm,
+                notebook: this.notebook,
+            });
+            const contextMessages = this.contextManager.getContextMessages();
+            const entries = await reflector.reflect({
+                userQuery: input,
+                finalAnswer: answer,
+                conversation: contextMessages,
+                sessionId: this.sessionManager?.getSessionId() ?? "unknown",
+            });
+            if (entries.length > 0) {
+                this.logger.info("Reflection", `Post-hoc complete — ${entries.length} finding(s) written to notebook.`);
+                for (const entry of entries) {
+                    this.logger.info("Reflection", `  [${entry.category}] ${entry.description}`);
+                }
+            }
+            else {
+                this.logger.info("Reflection", "Post-hoc complete — no issues found.");
+            }
+        }
+        catch (err) {
+            this.logger.warn("Reflection", `Post-hoc reflection failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // ─── System Prompt Management ───────────────────────────────────────
+    /**
+     * Rebuild the system prompt to include plan progress and replan hints.
+     *
+     * Called each iteration so the LLM always sees the up-to-date state.
+     */
+    rebuildContextWithPlan() {
+        let prompt = this.buildSystemPrompt();
+        // Plan context — injected when a plan exists
+        if (this.hasPlan && this.currentPlan.length > 0) {
+            prompt += `\n\n=== Current Plan (${this.completedSteps}/${this.currentPlan.length} completed) ===\n`;
+            for (let i = 0; i < this.currentPlan.length; i++) {
+                const marker = i < this.completedSteps
+                    ? "✅"
+                    : i === this.completedSteps
+                        ? "➡️"
+                        : "  ";
+                prompt += `  ${marker} ${i + 1}. ${this.currentPlan[i]}\n`;
+            }
+            prompt +=
+                `\nWork through the plan step by step. ` +
+                    `When you complete a step, move to the next one. ` +
+                    `If you need to revise remaining steps, output a "revised_plan".`;
+        }
+        // Replan hint — injected when consecutive failures are detected
+        const replanHint = this.computeReplanHint();
+        if (replanHint) {
+            prompt += `\n\n${replanHint}`;
+        }
+        this.contextManager.setSystemMessage(prompt);
+    }
+    /**
+     * Compute a replan hint based on consecutive failure count.
+     */
+    computeReplanHint() {
+        if (this.replanThreshold <= 0)
+            return undefined;
+        if (!this.hasPlan)
+            return undefined;
+        if (this.consecutiveFailures >= this.replanThreshold) {
+            return (`⚠️ REPLAN SUGGESTED: Multiple consecutive tool failures detected (${this.consecutiveFailures}).\n` +
+                `The current approach may be fundamentally wrong.\n` +
+                `Please consider whether your plan needs revision. If so, output a "revised_plan" ` +
+                `with a new strategy for the remaining steps. Only the REMAINING steps — ` +
+                `do NOT re-list already completed steps.`);
+        }
+        return undefined;
+    }
+    // ─── Session Persistence ────────────────────────────────────────────
+    /**
+     * Agent type identifier for session metadata.
+     */
+    getAgentType() {
+        return "fusion";
+    }
+    /**
+     * Include fusion-specific state in session checkpoints.
+     */
+    buildBaseSessionState(status) {
+        const base = super.buildBaseSessionState(status);
+        return {
+            ...base,
+            planState: undefined, // Clear PlanSolve state — fusion uses its own
+            fusionState: {
+                complexity: this.complexity,
+                routed: this.routed,
+                currentPlan: this.currentPlan,
+                hasPlan: this.hasPlan,
+                completedSteps: this.completedSteps,
+                consecutiveFailures: this.consecutiveFailures,
+                reflectionEnabled: this.reflectionMode !== "off",
+                inlineReflectionsDone: this.inlineReflectionsDone,
+            },
+        };
+    }
+    /**
+     * Restore fusion state from a saved session.
+     */
+    loadAndRestoreSession(sessionId) {
+        const state = super.loadAndRestoreSession(sessionId);
+        if (state.fusionState) {
+            const fs = state.fusionState;
+            this.complexity = fs.complexity;
+            this.routed = fs.routed;
+            this.currentPlan = fs.currentPlan;
+            this.hasPlan = fs.hasPlan;
+            this.completedSteps = fs.completedSteps;
+            this.consecutiveFailures = fs.consecutiveFailures;
+            this.inlineReflectionsDone = fs.inlineReflectionsDone;
+        }
+        return state;
+    }
+    // ─── Resume ─────────────────────────────────────────────────────────
+    /**
+     * Resume a previously interrupted session.
+     *
+     * Restores messages, system prompt, plan state, and fusion metadata
+     * so the agent can continue from where it left off.
+     *
+     * @param sessionId The session ID to resume.
+     * @param input     New user input to continue the conversation.
+     */
+    async resume(sessionId, input) {
+        this.loadAndRestoreSession(sessionId);
+        this._skipStateReset = true;
+        return this.run(input);
+    }
+}
+exports.FusionAgent = FusionAgent;
+//# sourceMappingURL=fusion-agent.js.map