kagent-ts 0.1.0

package/dist/core/react-agent.js

@@ -0,0 +1,266 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReActAgent = void 0;
+const agent_1 = require("./agent");
+const message_1 = require("../messages/message");
+const response_schema_1 = require("./response-schema");
+const openai_provider_1 = require("../llm/openai-provider");
+const response_schema_2 = require("./response-schema");
+/**
+ * Default system prompt for ReAct-style reasoning with structured JSON output.
+ *
+ * The LLM is instructed to respond with JSON so the agent can reliably
+ * parse thoughts and final answers — no free-text format ambiguity.
+ */
+const DEFAULT_REACT_SYSTEM_PROMPT = `You are a helpful AI assistant powered by a ReAct (Reasoning + Acting) loop.
+You have access to a set of tools you can use to answer the user's question.
+
+Follow this process:
+1. Think step by step about what the user needs.
+2. Decide whether to use a tool or give the final answer.
+3. If using a tool, call it with the correct parameters.
+4. Observe the result and decide the next step.
+5. Repeat until you have the complete answer.
+
+If no tools are needed, respond with the final answer directly.
+Always think step by step before acting.
+
+=== Tool Error Recovery ===
+When a tool returns an error:
+1. READ the error message carefully — understand WHY it failed.
+2. ANALYZE whether the parameters were correct. Common issues:
+   - Wrong file path (check spelling, use absolute paths)
+   - Missing or incorrect arguments
+   - The tool may need different input formats
+3. RETRY with corrected parameters if you can fix the issue.
+4. If the same tool fails repeatedly, try a COMPLETELY DIFFERENT approach.
+5. If a tool is disabled after too many failures, DO NOT try to use it again.
+   Find another way to accomplish the task.${response_schema_1.STRUCTURED_OUTPUT_INSTRUCTIONS}`;
+/**
+ * ReAct Agent implementing a structured Thought → Action → Observation → Final Answer loop.
+ *
+ * The agent uses structured JSON output from the LLM:
+ * - Intermediate steps:  {"thought": "..."}
+ * - Final answer:        {"thought": "...", "answer": "..."}
+ * - Tool calls via native function calling (OpenAI tool_calls)
+ *
+ * Session persistence:
+ * When `enableCheckpointing` is set, the agent auto-saves checkpoints after
+ * each LLM+tools cycle. On network error, an `interrupted` checkpoint is
+ * saved so the user can resume later via `agent.resume(sessionId, input)`.
+ */
+class ReActAgent extends agent_1.Agent {
+    maxIterations;
+    enableSkillAutoDetect;
+    constructor(config) {
+        // Set default ReAct system prompt if none provided
+        const mergedConfig = {
+            ...config,
+            systemPrompt: config.systemPrompt ?? DEFAULT_REACT_SYSTEM_PROMPT,
+        };
+        super(mergedConfig);
+        this.maxIterations = config.maxIterations ?? 10;
+        this.enableSkillAutoDetect = config.enableSkillAutoDetect ?? true;
+        // If skills are registered, rebuild the system prompt so the
+        // available-skills hint is included in the initial prompt.
+        if (this.skillManager.activeCount > 0) {
+            this.rebuildSystemPrompt();
+        }
+    }
+    async run(input) {
+        // ── Progressive disclosure ─────────────────────────────────────────
+        if (this.enableSkillAutoDetect && this.skillManager.activeCount >= 0) {
+            const activated = this.skillManager.detectAndActivate(input);
+            if (activated.length > 0) {
+                this.rebuildSystemPrompt();
+                console.log(`[Skills] Auto-activated: ${activated.join(", ")}`);
+            }
+        }
+        // ── Create user message ──────────────────────────────────────────
+        const userMessage = message_1.Message.user(input);
+        this.contextManager.addMessage(userMessage.toDict());
+        // Save initial checkpoint (captures user input before any LLM call)
+        if (this.checkpointingEnabled) {
+            this.saveCheckpoint("active");
+        }
+        // Track consecutive unproductive iterations (no tool calls, no answer)
+        let consecutiveEmptyIterations = 0;
+        const EMPTY_ITERATION_LIMIT = 5;
+        // ── ReAct loop ────────────────────────────────────────────────────
+        for (let iteration = 0; iteration < this.maxIterations; iteration++) {
+            // Check if user cancelled (SIGINT)
+            if (this.isCancelled) {
+                this.sessionManager?.deleteSession(this.sessionManager.getSessionId());
+                return "Execution cancelled by user. Session discarded.";
+            }
+            // Check and compress if needed
+            this.checkAndCompress();
+            // Prepare messages for the LLM
+            const contextMessages = this.contextManager.getContextMessages();
+            // Call the LLM with all registered tools — with network error handling
+            this.hooks.onLLMStart?.();
+            let response;
+            try {
+                response = await this.llm.chat(contextMessages, this.toolRegistry.getTools());
+            }
+            catch (err) {
+                if (err instanceof openai_provider_1.LLMNetworkError) {
+                    this.hooks.onLLMError?.(err);
+                    return this.handleNetworkError(err, iteration + 1);
+                }
+                throw err; // Unknown error — propagate
+            }
+            this.hooks.onLLMEnd?.(response);
+            // Parse the response content as structured JSON
+            const parsed = (0, response_schema_1.parseReActResponse)(response.content);
+            const rawContent = response.content;
+            // Create assistant message from the response
+            const assistantMessage = message_1.Message.assistant(rawContent, response.tool_calls);
+            // Store in context
+            this.contextManager.addMessage(assistantMessage.toDict());
+            // Check if LLM wants to call tools
+            if (response.tool_calls && response.tool_calls.length > 0) {
+                consecutiveEmptyIterations = 0;
+                // Log the reasoning thought and capture as error analysis
+                if (parsed.thought) {
+                    console.log(`[Thought] ${parsed.thought}`);
+                    this.hooks.onThought?.(parsed.thought);
+                    this.captureAnalysisFromThought(parsed.thought);
+                }
+                for (const toolCall of response.tool_calls) {
+                    let args;
+                    try {
+                        args = JSON.parse(toolCall.function.arguments);
+                    }
+                    catch {
+                        args = {};
+                    }
+                    this.hooks.onToolStart?.(toolCall.function.name, args);
+                    // Execute via ToolRegistry — includes circuit breaker protection
+                    let result;
+                    try {
+                        result = await this.toolRegistry.execute(toolCall.function.name, args);
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        result = `Error executing tool "${toolCall.function.name}": ${message}`;
+                    }
+                    // Determine success vs error and fire appropriate hook
+                    if (result.startsWith("Error")) {
+                        this.hooks.onToolError?.(toolCall.function.name, result);
+                    }
+                    else {
+                        this.hooks.onToolEnd?.(toolCall.function.name, result);
+                    }
+                    // Track this result for error analysis if it indicates a failure
+                    this.trackToolErrorForAnalysis(toolCall.function.name, result);
+                    // Create tool result message
+                    const toolMessage = message_1.Message.tool(result, toolCall.id, toolCall.function.name);
+                    this.contextManager.addMessage(toolMessage.toDict());
+                }
+                // Save checkpoint after complete tool execution round
+                if (this.checkpointingEnabled) {
+                    this.saveCheckpoint("active");
+                }
+                // Continue the loop for the next Thought
+                continue;
+            }
+            // No tool calls — extract the final answer from the JSON
+            if ("answer" in parsed && parsed.answer) {
+                this.hooks.onFinish?.(parsed.answer);
+                // Save final checkpoint as completed
+                if (this.checkpointingEnabled) {
+                    this.saveCheckpoint("completed");
+                }
+                return parsed.answer;
+            }
+            // JSON has "thought" but no "answer" — continue the loop
+            // (the agent is still reasoning)
+            if (parsed.thought) {
+                consecutiveEmptyIterations++;
+                console.log(`[Thought] ${parsed.thought}`);
+                this.hooks.onThought?.(parsed.thought);
+                this.captureAnalysisFromThought(parsed.thought);
+                // If stuck in unproductive thought-only loop, inject format reminder
+                if (consecutiveEmptyIterations >= 3) {
+                    console.log(`[ReAct] ${consecutiveEmptyIterations} consecutive thought-only iterations — ` +
+                        `injecting format reminder.`);
+                    const reminderMsg = message_1.Message.assistant(response_schema_2.STRUCTURED_OUTPUT_REMINDER);
+                    this.contextManager.addMessage(reminderMsg.toDict());
+                }
+                // If exceeded limit, bail out
+                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());
+                    this.hooks.onFinish?.(stuckMsg);
+                    return stuckMsg;
+                }
+                // Save checkpoint after a thought-only iteration
+                if (this.checkpointingEnabled) {
+                    this.saveCheckpoint("active");
+                }
+                continue;
+            }
+            // Empty response (no thought, no answer, no tool calls)
+            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());
+                this.hooks.onFinish?.(stuckMsg);
+                return stuckMsg;
+            }
+        }
+        // ── Max iterations reached without final answer ───────────────────
+        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());
+        this.hooks.onFinish?.(timeoutMsg);
+        return timeoutMsg;
+    }
+    // ─── Resume ──────────────────────────────────────────────────────────
+    /**
+     * Resume a previously interrupted session.
+     *
+     * Loads the saved session state (messages, system prompt) so the agent
+     * can continue from where it left off. The `input` is treated as a new
+     * user message appended to the restored conversation.
+     *
+     * @param sessionId The session ID to resume.
+     * @param input     New user input to continue the conversation.
+     * @returns The agent's final response.
+     */
+    async resume(sessionId, input) {
+        this.loadAndRestoreSession(sessionId);
+        return this.run(input);
+    }
+    // ─── Private Helpers ─────────────────────────────────────────────────
+    /**
+     * Handle an LLMNetworkError: save an interrupted checkpoint if
+     * checkpointing is enabled, and return a user-facing message with
+     * resume instructions.
+     */
+    handleNetworkError(err, iteration) {
+        if (this.checkpointingEnabled) {
+            this.saveCheckpoint("interrupted");
+        }
+        const sid = this.sessionManager?.getSessionId() ?? "unknown";
+        console.error(`\n[Network Error] ${err.cause}: ${err.message}`);
+        if (this.checkpointingEnabled && this.sessionManager) {
+            return (`[Network Error] ${err.message}\n\n` +
+                `Your session "${sid}" has been saved (iteration ${iteration}).\n` +
+                `After your network is restored, resume with:\n` +
+                `  agent.resume("${sid}", "continue with my previous request")\n\n` +
+                `Or start a new session by calling agent.run() again with a fresh input.`);
+        }
+        // Checkpointing not enabled — just report the error
+        return (`[Network Error] ${err.message}\n\n` +
+            `Please check your network connection and try again.`);
+    }
+}
+exports.ReActAgent = ReActAgent;
+//# sourceMappingURL=react-agent.js.map

package/dist/core/react-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-agent.js","sourceRoot":"","sources":["../../src/core/react-agent.ts"],"names":[],"mappings":"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"}

package/dist/core/response-schema.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Structured JSON response schema for LLM outputs.
+ *
+ * Instead of parsing free-text ReAct format (Thought/Action/Action Input),
+ * the LLM is instructed to respond with a JSON object that the agent
+ * can reliably parse. This eliminates ambiguity in the agent loop.
+ */
+/**
+ * Intermediate reasoning step (no final answer yet).
+ */
+export interface ReActReasoning {
+    /** Step-by-step reasoning about what to do next. */
+    thought: string;
+}
+/**
+ * Final answer from the agent.
+ */
+export interface ReActFinalAnswer {
+    /** Final reasoning before answering. */
+    thought: string;
+    /** The complete answer for the user. */
+    answer: string;
+}
+/**
+ * Union of all possible ReAct response shapes.
+ */
+export type ReActResponse = ReActReasoning | ReActFinalAnswer;
+/**
+ * Parse a raw LLM content string into a structured ReActResponse.
+ *
+ * Handles:
+ * - Raw JSON:     {"thought": "...", "answer": "..."}
+ * - Code blocks:  ```json\n{"thought": "..."}\n```
+ * - Extra text:   Let me think... {"thought": "..."}
+ *
+ * Falls back to wrapping the raw text as a thought when JSON parsing fails.
+ */
+export declare function parseReActResponse(raw: string): ReActResponse;
+/**
+ * Instructions injected into the system prompt to teach the LLM
+ * the JSON response format.
+ */
+export declare const STRUCTURED_OUTPUT_INSTRUCTIONS = "\n=== Response Format ===\nYou MUST respond with a valid JSON object in the \"content\" field of your message.\nDo NOT wrap the JSON in markdown code blocks.\n\nWhen you have the FINAL ANSWER for the user:\n{\"thought\": \"...step-by-step reasoning...\", \"answer\": \"...complete answer for the user...\"}\n\nWhen you are REASONING (intermediate step, before or after using tools):\n{\"thought\": \"...step-by-step reasoning...\"}\n\nRules:\n- \"thought\" is REQUIRED in every response \u2014 it contains your step-by-step reasoning.\n- \"answer\" is ONLY included in your final response, when you have the complete answer.\n- The JSON must be valid and parseable \u2014 no trailing commas, no comments.\n- If you need to use a tool, put your reasoning in \"thought\" as JSON, and send the tool call via the function calling mechanism.";
+/**
+ * Compact one-line reminder appended to each assistant message
+ * to reinforce the JSON format.
+ */
+export declare const STRUCTURED_OUTPUT_REMINDER = "\n\nRemember: Respond with a JSON object: {\"thought\": \"...\", \"answer\": \"...\"} (answer only for final response).";
+/**
+ * Response from the Plan-and-Solve agent.
+ *
+ * Different phases produce different shapes:
+ * - Planning:    { thought, plan: string[] }
+ * - Executing:   { thought } (may also include tool_calls)
+ * - Revising:    { thought, revised_plan: string[] }
+ * - Final:       { thought, answer }
+ */
+export interface PlanSolveResponse {
+    /** Step-by-step reasoning (required in every response). */
+    thought: string;
+    /** Initial plan — numbered steps covering the full task. */
+    plan?: string[];
+    /** Replacement plan — overrides remaining steps. */
+    revised_plan?: string[];
+    /** Final answer for the user. */
+    answer?: string;
+    /**
+     * 1-based index of the step the LLM is currently working on.
+     * Used for plan progress tracking and display.
+     * Steps before this are marked as completed.
+     */
+    currentStep?: number;
+}
+/**
+ * Parse a raw LLM content string into a PlanSolveResponse.
+ *
+ * Reuses the same multi-strategy JSON extraction as parseReActResponse
+ * but handles the Plan-and-Solve shapes (plan/revised_plan arrays).
+ */
+export declare function parsePlanSolveResponse(raw: string): PlanSolveResponse;
+/**
+ * System prompt instructions for the Plan-and-Solve paradigm.
+ *
+ * The LLM is instructed to separate planning from execution:
+ * 1. Phase 1 — PLAN:  Analyze and create a detailed numbered plan.
+ * 2. Phase 2 — RESOLVE: Work through each step, using tools.
+ *    Revise remaining steps if new information emerges.
+ * 3. Final: When all steps are complete, provide the full answer.
+ */
+export declare const PLAN_SOLVE_INSTRUCTIONS = "\n=== Plan-and-Resolve Paradigm ===\nYou follow a structured two-phase approach to solve tasks:\n\nPhase 1 \u2014 PLAN: Analyze the user's request and create a detailed, step-by-step plan covering all the work needed. Each step must be concrete and actionable.\n\nPhase 2 \u2014 RESOLVE: Execute each step of the plan. Use tools as needed.\n- After each step, you may REVISE remaining steps if the plan needs updating.\n- A revision replaces all remaining steps \u2014 do NOT re-list already completed steps.\n\n=== Response Format ===\nYou MUST respond with a valid JSON object in the \"content\" field.\n\nCreating the INITIAL PLAN:\n{\"thought\": \"...analysis...\", \"plan\": [\"Step 1: description\", \"Step 2: description\", \"...\"]}\n\nExecuting steps (use \"currentStep\" to indicate your progress):\n{\"thought\": \"...reasoning...\", \"currentStep\": 2}\n\nREVISING the plan (replaces REMAINING steps only):\n{\"thought\": \"...reasoning about why the plan needs to change...\", \"revised_plan\": [\"Updated Step A: ...\", \"Updated Step B: ...\", \"...\"]}\n\nFinal answer:\n{\"thought\": \"...summary...\", \"answer\": \"...complete answer for the user...\"}\n\nRules:\n- \"thought\" is REQUIRED in every response.\n- \"plan\" is ONLY for the initial plan creation (first response after user input).\n- \"revised_plan\" replaces REMAINING steps \u2014 do NOT re-list already done steps.\n- \"currentStep\" is the 1-based index of the step you are about to execute next.\n- \"answer\" is ONLY for the final response, when ALL steps are complete.\n- The JSON must be valid and parseable \u2014 no trailing commas, no comments.\n\n=== When to Replan \u2014 output \"revised_plan\" when: ===\n1. REPEATED TOOL FAILURES: A tool fails 2+ consecutive times on the same step.\n   \u2192 The current approach isn't working \u2014 try a completely different method.\n\n2. CONTRADICTED ASSUMPTIONS: A tool result reveals information that disproves\n   a key assumption your plan was based on.\n   \u2192 Adjust remaining steps to account for the new reality.\n\n3. EXECUTION DRIFT: The actual state of things differs from what the plan\n   expected at this point.\n   \u2192 Realign the remaining steps with what has actually happened.\n\n4. STUCK ON A STEP: You cannot make progress on the current step after\n   multiple attempts with different approaches.\n   \u2192 Skip or reorder steps \u2014 try a different angle to reach the goal.\n\nIMPORTANT: Replanning is a normal part of problem-solving. If in doubt,\noutput a \"revised_plan\" rather than retrying the same failing approach.";
+//# sourceMappingURL=response-schema.d.ts.map

package/dist/core/response-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-schema.d.ts","sourceRoot":"","sources":["../../src/core/response-schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,gBAAgB,CAAC;AAI9D;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAwB7D;AAmID;;;GAGG;AACH,eAAO,MAAM,8BAA8B,y0BAesF,CAAC;AAElI;;;GAGG;AACH,eAAO,MAAM,0BAA0B,4HACoF,CAAC;AAI5H;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAwCrE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,oiFAkDoC,CAAC"}

package/dist/core/response-schema.js

@@ -0,0 +1,292 @@
+"use strict";
+/**
+ * Structured JSON response schema for LLM outputs.
+ *
+ * Instead of parsing free-text ReAct format (Thought/Action/Action Input),
+ * the LLM is instructed to respond with a JSON object that the agent
+ * can reliably parse. This eliminates ambiguity in the agent loop.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLAN_SOLVE_INSTRUCTIONS = exports.STRUCTURED_OUTPUT_REMINDER = exports.STRUCTURED_OUTPUT_INSTRUCTIONS = void 0;
+exports.parseReActResponse = parseReActResponse;
+exports.parsePlanSolveResponse = parsePlanSolveResponse;
+// ─── Response Parser ────────────────────────────────────────────────────
+/**
+ * Parse a raw LLM content string into a structured ReActResponse.
+ *
+ * Handles:
+ * - Raw JSON:     {"thought": "...", "answer": "..."}
+ * - Code blocks:  ```json\n{"thought": "..."}\n```
+ * - Extra text:   Let me think... {"thought": "..."}
+ *
+ * Falls back to wrapping the raw text as a thought when JSON parsing fails.
+ */
+function parseReActResponse(raw) {
+    const json = extractJSON(raw);
+    if (json) {
+        try {
+            const parsed = JSON.parse(json);
+            // Must be an object with at least "thought"
+            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+                const thought = String(parsed.thought ?? "");
+                if ("answer" in parsed && parsed.answer !== undefined && parsed.answer !== null) {
+                    return { thought, answer: String(parsed.answer) };
+                }
+                return { thought };
+            }
+        }
+        catch {
+            // JSON parse failed — fall through to fallback
+        }
+    }
+    // Fallback: treat the entire raw string as the thought
+    return { thought: raw };
+}
+/**
+ * Try to extract a JSON object from a string that may contain
+ * markdown, extra text, malformed newlines, or other noise.
+ *
+ * Strategy in order:
+ * 1. Direct parse of the trimmed text.
+ * 2. Extract from ```json ... ``` markdown block.
+ * 3. Find balanced { ... } via depth counting, then try to parse.
+ * 4. Clean up common issues (unescaped newlines) and retry steps 1-3.
+ *
+ * Returns the JSON string if found, or null.
+ */
+function extractJSON(text) {
+    if (!text)
+        return null;
+    // Try with progressively more aggressive cleanup
+    const variants = [
+        text.trim(),
+        cleanupJSON(text.trim()),
+        text.trim().replace(/\n/g, " ").replace(/\r/g, ""),
+    ];
+    // De-duplicate variants
+    const seen = new Set();
+    const uniqueVariants = variants.filter((v) => {
+        if (seen.has(v))
+            return false;
+        seen.add(v);
+        return true;
+    });
+    for (const variant of uniqueVariants) {
+        const result = tryExtractJSON(variant);
+        if (result)
+            return result;
+    }
+    return null;
+}
+/**
+ * Try all extraction strategies on a single variant of the text.
+ */
+function tryExtractJSON(text) {
+    // 1. Try the entire string as JSON
+    if (isValidJSON(text))
+        return text;
+    // 2. Try extracting from markdown code blocks: ```json ... ```
+    const blockMatch = text.match(/```(?:json)?\s*(\{[\s\S]*?\})\s*```/);
+    if (blockMatch && isValidJSON(blockMatch[1]))
+        return blockMatch[1];
+    // 3. Try finding the first { ... } with balanced braces
+    const braceStart = text.indexOf("{");
+    if (braceStart >= 0) {
+        const fromBrace = text.slice(braceStart);
+        const result = extractBalancedBraces(fromBrace);
+        if (result)
+            return result;
+    }
+    return null;
+}
+/**
+ * Find balanced { ... } and validate as JSON.
+ * Handles strings with escaped quotes to avoid false brace matching.
+ */
+function extractBalancedBraces(text) {
+    let depth = 0;
+    let inString = false;
+    let escapeNext = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (escapeNext) {
+                escapeNext = false;
+            }
+            else if (ch === "\\") {
+                escapeNext = true;
+            }
+            else if (ch === '"') {
+                inString = false;
+            }
+        }
+        else {
+            if (ch === '"') {
+                inString = true;
+                escapeNext = false;
+            }
+            else if (ch === "{") {
+                depth++;
+            }
+            else if (ch === "}") {
+                depth--;
+                if (depth === 0) {
+                    const candidate = text.slice(0, i + 1);
+                    if (isValidJSON(candidate))
+                        return candidate;
+                    break;
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Clean up common JSON formatting issues from LLM output.
+ */
+function cleanupJSON(text) {
+    let result = text;
+    // Replace actual newlines inside JSON strings with \n escape
+    // (only between "..." regions)
+    result = result.replace(/\r\n/g, "\n").replace(/\r/g, "");
+    return result;
+}
+/**
+ * Quick check if a string is valid JSON.
+ */
+function isValidJSON(text) {
+    try {
+        JSON.parse(text);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ─── System Prompt Templates ────────────────────────────────────────────
+/**
+ * Instructions injected into the system prompt to teach the LLM
+ * the JSON response format.
+ */
+exports.STRUCTURED_OUTPUT_INSTRUCTIONS = `
+=== Response Format ===
+You MUST respond with a valid JSON object in the "content" field of your message.
+Do NOT wrap the JSON in markdown code blocks.
+
+When you have the FINAL ANSWER for the user:
+{"thought": "...step-by-step reasoning...", "answer": "...complete answer for the user..."}
+
+When you are REASONING (intermediate step, before or after using tools):
+{"thought": "...step-by-step reasoning..."}
+
+Rules:
+- "thought" is REQUIRED in every response — it contains your step-by-step reasoning.
+- "answer" is ONLY included in your final response, when you have the complete answer.
+- The JSON must be valid and parseable — no trailing commas, no comments.
+- If you need to use a tool, put your reasoning in "thought" as JSON, and send the tool call via the function calling mechanism.`;
+/**
+ * Compact one-line reminder appended to each assistant message
+ * to reinforce the JSON format.
+ */
+exports.STRUCTURED_OUTPUT_REMINDER = "\n\nRemember: Respond with a JSON object: {\"thought\": \"...\", \"answer\": \"...\"} (answer only for final response).";
+/**
+ * Parse a raw LLM content string into a PlanSolveResponse.
+ *
+ * Reuses the same multi-strategy JSON extraction as parseReActResponse
+ * but handles the Plan-and-Solve shapes (plan/revised_plan arrays).
+ */
+function parsePlanSolveResponse(raw) {
+    const json = extractJSON(raw);
+    if (json) {
+        try {
+            const parsed = JSON.parse(json);
+            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+                const thought = String(parsed.thought ?? "");
+                const result = { thought };
+                // plan — array of strings
+                if (parsed.plan && Array.isArray(parsed.plan)) {
+                    result.plan = parsed.plan.map(String);
+                }
+                // revised_plan — array of strings
+                if (parsed.revised_plan && Array.isArray(parsed.revised_plan)) {
+                    result.revised_plan = parsed.revised_plan.map(String);
+                }
+                // answer — final response
+                if (parsed.answer !== undefined && parsed.answer !== null) {
+                    result.answer = String(parsed.answer);
+                }
+                // currentStep — step progress indicator (1-based)
+                if (typeof parsed.currentStep === "number" && parsed.currentStep >= 1) {
+                    result.currentStep = Math.floor(parsed.currentStep);
+                }
+                return result;
+            }
+        }
+        catch {
+            // JSON parse failed — fall through to fallback
+        }
+    }
+    // Fallback: treat the entire raw string as thought
+    return { thought: raw };
+}
+/**
+ * System prompt instructions for the Plan-and-Solve paradigm.
+ *
+ * The LLM is instructed to separate planning from execution:
+ * 1. Phase 1 — PLAN:  Analyze and create a detailed numbered plan.
+ * 2. Phase 2 — RESOLVE: Work through each step, using tools.
+ *    Revise remaining steps if new information emerges.
+ * 3. Final: When all steps are complete, provide the full answer.
+ */
+exports.PLAN_SOLVE_INSTRUCTIONS = `
+=== Plan-and-Resolve Paradigm ===
+You follow a structured two-phase approach to solve tasks:
+
+Phase 1 — PLAN: Analyze the user's request and create a detailed, step-by-step plan covering all the work needed. Each step must be concrete and actionable.
+
+Phase 2 — RESOLVE: Execute each step of the plan. Use tools as needed.
+- After each step, you may REVISE remaining steps if the plan needs updating.
+- A revision replaces all remaining steps — do NOT re-list already completed steps.
+
+=== Response Format ===
+You MUST respond with a valid JSON object in the "content" field.
+
+Creating the INITIAL PLAN:
+{"thought": "...analysis...", "plan": ["Step 1: description", "Step 2: description", "..."]}
+
+Executing steps (use "currentStep" to indicate your progress):
+{"thought": "...reasoning...", "currentStep": 2}
+
+REVISING the plan (replaces REMAINING steps only):
+{"thought": "...reasoning about why the plan needs to change...", "revised_plan": ["Updated Step A: ...", "Updated Step B: ...", "..."]}
+
+Final answer:
+{"thought": "...summary...", "answer": "...complete answer for the user..."}
+
+Rules:
+- "thought" is REQUIRED in every response.
+- "plan" is ONLY for the initial plan creation (first response after user input).
+- "revised_plan" replaces REMAINING steps — do NOT re-list already done steps.
+- "currentStep" is the 1-based index of the step you are about to execute next.
+- "answer" is ONLY for the final response, when ALL steps are complete.
+- The JSON must be valid and parseable — no trailing commas, no comments.
+
+=== When to Replan — output "revised_plan" when: ===
+1. REPEATED TOOL FAILURES: A tool fails 2+ consecutive times on the same step.
+   → The current approach isn't working — try a completely different method.
+
+2. CONTRADICTED ASSUMPTIONS: A tool result reveals information that disproves
+   a key assumption your plan was based on.
+   → Adjust remaining steps to account for the new reality.
+
+3. EXECUTION DRIFT: The actual state of things differs from what the plan
+   expected at this point.
+   → Realign the remaining steps with what has actually happened.
+
+4. STUCK ON A STEP: You cannot make progress on the current step after
+   multiple attempts with different approaches.
+   → Skip or reorder steps — try a different angle to reach the goal.
+
+IMPORTANT: Replanning is a normal part of problem-solving. If in doubt,
+output a "revised_plan" rather than retrying the same failing approach.`;
+//# sourceMappingURL=response-schema.js.map