kagent-ts 0.1.4 → 0.1.5

package/dist/reflection/memory-reflector.d.ts

@@ -0,0 +1,97 @@
+import { LLMProvider } from "../llm/interface";
+import { MessageData } from "../messages/types";
+import { MemoryManager, Memory, MemoryType } from "../memory/memory-manager";
+/**
+ * Input provided to the MemoryReflector for analysis.
+ */
+export interface MemoryReflectionInput {
+    /** The original user query. */
+    userQuery: string;
+    /** The final answer produced by the agent. */
+    finalAnswer: string;
+    /** The full conversation messages (for context). */
+    conversation: MessageData[];
+    /** Session identifier. */
+    sessionId: string;
+}
+/**
+ * A single memory extracted from the session.
+ */
+export interface ExtractedMemory {
+    /** Slug (kebab-case, used as filename). */
+    name: string;
+    /** One-line summary shown in the index. */
+    description: string;
+    /** Memory type. */
+    type: MemoryType;
+    /** Markdown body with why + how to apply. */
+    content: string;
+}
+/**
+ * Configuration for the MemoryReflector.
+ */
+export interface MemoryReflectorConfig {
+    /** LLM provider (shared with the main agent). */
+    llm: LLMProvider;
+    /** MemoryManager for checking existing memories and persisting new ones. */
+    memoryManager: MemoryManager;
+    /**
+     * Maximum ReAct iterations for the sub-agent (default: 5).
+     * Memory extraction requires more context reading than error reflection.
+     */
+    maxIterations?: number;
+}
+/**
+ * MemoryReflector — post-execution memory extraction via a forked sub-agent.
+ *
+ * After the main agent finishes, the MemoryReflector forks a lightweight
+ * ReActAgent to review the session and extract lasting memories: user
+ * preferences, project decisions, constraints, and workflow patterns.
+ *
+ * The fork runs in its own context with read-only tools (read_file, grep_search)
+ * so it can verify context against the codebase before recording a memory.
+ *
+ * Usage:
+ * ```ts
+ * const memManager = new MemoryManager({ storageDir: ".memory" });
+ * const reflector = new MemoryReflector({ llm, memoryManager: memManager });
+ * const memories = await reflector.reflect({
+ *   userQuery: input,
+ *   finalAnswer: answer,
+ *   conversation: contextMessages,
+ *   sessionId: "sess_123",
+ * });
+ * ```
+ */
+export declare class MemoryReflector {
+    private llm;
+    private memoryManager;
+    private maxIterations;
+    constructor(config: MemoryReflectorConfig);
+    /**
+     * Fork a sub-agent to extract memories from the session.
+     *
+     * @returns The list of new memories written to the MemoryManager.
+     */
+    reflect(input: MemoryReflectionInput): Promise<Memory[]>;
+    /**
+     * Fork a minimal ReActAgent and run it to completion.
+     * Returns the agent's final answer string.
+     */
+    private forkAndRun;
+    /**
+     * Build the task prompt for the sub-agent from the reflection input.
+     */
+    private buildTaskPrompt;
+    /**
+     * Format the conversation for the memory extraction prompt.
+     * Truncates very long tool results for readability.
+     */
+    private formatConversation;
+    /**
+     * Parse the sub-agent's final answer into a list of ExtractedMemories.
+     * Returns an empty array if parsing fails (best-effort).
+     */
+    private parseMemories;
+}
+//# sourceMappingURL=memory-reflector.d.ts.map

package/dist/reflection/memory-reflector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-reflector.d.ts","sourceRoot":"","sources":["../../src/reflection/memory-reflector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAQ,MAAM,mBAAmB,CAAC;AAMtD,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAI7E;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB;IACnB,IAAI,EAAE,UAAU,CAAC;IACjB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB;AAyDD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,GAAG,EAAE,WAAW,CAAC;IACjB,4EAA4E;IAC5E,aAAa,EAAE,aAAa,CAAC;IAC7B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,GAAG,CAAc;IACzB,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,aAAa,CAAS;gBAElB,MAAM,EAAE,qBAAqB;IAQzC;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAgC9D;;;OAGG;YACW,UAAU;IAiBxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAmCvB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAwB1B;;;OAGG;IACH,OAAO,CAAC,aAAa;CAqCtB"}

package/dist/reflection/memory-reflector.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryReflector = void 0;
+const types_1 = require("../messages/types");
+const react_agent_1 = require("../core/react-agent");
+const tool_registry_1 = require("../tools/tool-registry");
+const read_file_1 = require("../tools/builtin/read-file");
+const grep_search_1 = require("../tools/builtin/grep-search");
+const response_schema_1 = require("../core/response-schema");
+// ─── System Prompt ───────────────────────────────────────────────────────────
+const MEMORY_EXTRACTION_SYSTEM_PROMPT = `You are a memory extraction agent. Your job is to review a completed agent session
+and identify facts, preferences, constraints, and decisions worth remembering for future sessions.
+
+You have access to read_file and grep_search tools to verify context against the codebase.
+
+Categories of memory to extract:
+- **rule**: A constraint the user set — why they required it, and when it takes effect.
+  Example: "Always use kebab-case for file names."
+- **project**: A fact or decision about the project — what happened, why (constraint / deadline
+  that drove it), and how the agent should apply it.
+  Example: "We switched from MySQL to PostgreSQL because of JSONB support."
+
+What to look for:
+- User preferences (language, coding style, naming conventions, tool preferences)
+- Project decisions (architecture choices, tool/library selections, migration decisions)
+- Constraints (deadlines, limitations, requirements, "must not" rules)
+- Patterns worth repeating or avoiding (successful or failed approaches)
+- Workflow preferences (how the user likes to work, communication style)
+
+An existing memories list is provided below — do NOT duplicate any existing memory name.
+Only output genuinely new, useful memories. An empty list is fine if nothing new is found.
+
+In your final answer, output a JSON object with this structure:
+{
+  "memories": [
+    {
+      "name": "kebab-case-slug",
+      "description": "one-line summary",
+      "type": "rule | project",
+      "content": "The fact.\\n\\n**Why:** ...\\n\\n**How to apply:** ..."
+    }
+  ]
+}
+
+Rules:
+- "name" must be a kebab-case slug (lowercase letters, digits, dashes).
+- "description" must be a concise one-line summary (~5-15 words).
+- "type" must be either "rule" or "project".
+- "content" should include **Why:** and **How to apply:** sections for project memories,
+  or **Why:** and **When:** sections for rule memories.
+- Only output memories that provide lasting value across sessions.
+- Be specific and actionable — avoid vague statements.
+- Do NOT duplicate existing memory names.${response_schema_1.STRUCTURED_OUTPUT_INSTRUCTIONS}`;
+/**
+ * MemoryReflector — post-execution memory extraction via a forked sub-agent.
+ *
+ * After the main agent finishes, the MemoryReflector forks a lightweight
+ * ReActAgent to review the session and extract lasting memories: user
+ * preferences, project decisions, constraints, and workflow patterns.
+ *
+ * The fork runs in its own context with read-only tools (read_file, grep_search)
+ * so it can verify context against the codebase before recording a memory.
+ *
+ * Usage:
+ * ```ts
+ * const memManager = new MemoryManager({ storageDir: ".memory" });
+ * const reflector = new MemoryReflector({ llm, memoryManager: memManager });
+ * const memories = await reflector.reflect({
+ *   userQuery: input,
+ *   finalAnswer: answer,
+ *   conversation: contextMessages,
+ *   sessionId: "sess_123",
+ * });
+ * ```
+ */
+class MemoryReflector {
+    llm;
+    memoryManager;
+    maxIterations;
+    constructor(config) {
+        this.llm = config.llm;
+        this.memoryManager = config.memoryManager;
+        this.maxIterations = config.maxIterations ?? 5;
+    }
+    // ─── Public API ────────────────────────────────────────────────────────
+    /**
+     * Fork a sub-agent to extract memories from the session.
+     *
+     * @returns The list of new memories written to the MemoryManager.
+     */
+    async reflect(input) {
+        const existingNames = this.memoryManager.getAll().map((m) => ({
+            name: m.name,
+            description: m.description,
+        }));
+        const taskPrompt = this.buildTaskPrompt(input, existingNames);
+        const answer = await this.forkAndRun(taskPrompt);
+        const extracted = this.parseMemories(answer);
+        // Persist to MemoryManager (add() handles upsert by name)
+        const saved = [];
+        for (const m of extracted) {
+            const memory = {
+                name: m.name,
+                description: m.description,
+                type: m.type,
+                content: m.content,
+            };
+            // Skip if name already exists (defensive — sub-agent should avoid this)
+            if (this.memoryManager.has(m.name))
+                continue;
+            this.memoryManager.add(memory);
+            saved.push(memory);
+        }
+        return saved;
+    }
+    // ─── Private: Fork ─────────────────────────────────────────────────────
+    /**
+     * Fork a minimal ReActAgent and run it to completion.
+     * Returns the agent's final answer string.
+     */
+    async forkAndRun(userPrompt) {
+        const tools = new tool_registry_1.ToolRegistry();
+        tools.register(read_file_1.ReadFileTool);
+        tools.register(grep_search_1.GrepSearchTool);
+        const agent = new react_agent_1.ReActAgent({
+            llm: this.llm,
+            systemPrompt: MEMORY_EXTRACTION_SYSTEM_PROMPT,
+            toolRegistry: tools,
+            maxIterations: this.maxIterations,
+        });
+        return agent.run(userPrompt);
+    }
+    // ─── Private: Prompt Building ──────────────────────────────────────────
+    /**
+     * Build the task prompt for the sub-agent from the reflection input.
+     */
+    buildTaskPrompt(input, existing) {
+        let context = [
+            "Review this agent session and extract any memories worth keeping for future sessions.",
+            "",
+            "=== Existing Memories (do NOT duplicate these names) ===",
+        ];
+        if (existing.length === 0) {
+            context.push("(no existing memories)");
+        }
+        else {
+            for (const m of existing) {
+                context.push(`- ${m.name}: ${m.description}`);
+            }
+        }
+        context.push("", "=== User Query ===", input.userQuery, "", "=== Final Answer ===", input.finalAnswer, "", "=== Conversation ===", ...this.formatConversation(input.conversation), "", "Analyze the session and output extracted memories as JSON in your final answer.");
+        return context.join("\n");
+    }
+    /**
+     * Format the conversation for the memory extraction prompt.
+     * Truncates very long tool results for readability.
+     */
+    formatConversation(messages) {
+        const lines = [];
+        for (const msg of messages) {
+            const role = msg.role.toUpperCase();
+            let content = msg.content;
+            // Truncate long tool results
+            if (msg.role === types_1.Role.Tool && content.length > 1000) {
+                content = content.slice(0, 500) + "\n... (truncated, " + content.length + " chars total)";
+            }
+            lines.push(`[${role}] ${content}`);
+            if (msg.tool_calls && msg.tool_calls.length > 0) {
+                for (const tc of msg.tool_calls) {
+                    lines.push(`  → tool_call: ${tc.function.name}(${tc.function.arguments})`);
+                }
+            }
+        }
+        return lines;
+    }
+    // ─── Private: Parsing ──────────────────────────────────────────────────
+    /**
+     * Parse the sub-agent's final answer into a list of ExtractedMemories.
+     * Returns an empty array if parsing fails (best-effort).
+     */
+    parseMemories(answer) {
+        try {
+            // Extract JSON from the answer (may be wrapped in ```json fences)
+            let raw = answer.trim();
+            const fenceMatch = raw.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+            if (fenceMatch)
+                raw = fenceMatch[1];
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed.memories))
+                return [];
+            const validTypes = new Set(["rule", "project"]);
+            const memories = [];
+            for (const m of parsed.memories) {
+                if (typeof m.name !== "string" || !m.name ||
+                    typeof m.description !== "string" || !m.description ||
+                    typeof m.type !== "string" || !validTypes.has(m.type) ||
+                    typeof m.content !== "string" || !m.content) {
+                    continue;
+                }
+                memories.push({
+                    name: m.name,
+                    description: m.description,
+                    type: m.type,
+                    content: m.content,
+                });
+            }
+            return memories;
+        }
+        catch {
+            return [];
+        }
+    }
+}
+exports.MemoryReflector = MemoryReflector;
+//# sourceMappingURL=memory-reflector.js.map

package/dist/reflection/memory-reflector.js.map

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

package/dist/reflection/reflection-agent.d.ts

@@ -0,0 +1,105 @@
+import { LLMProvider } from "../llm/interface";
+import { MessageData } from "../messages/types";
+import { ErrorNotebook, ErrorNotebookEntry, ReflectionErrorCategory } from "./error-notebook";
+import type { ToolErrorTrace } from "../tools/types";
+/**
+ * Input provided to the ReflectionAgent for analysis.
+ */
+export interface ReflectionInput {
+    /** The original user query. */
+    userQuery: string;
+    /** The final answer produced by the agent. */
+    finalAnswer: string;
+    /** The full conversation messages (for context). */
+    conversation: MessageData[];
+    /** Tool error traces from the session (if any). */
+    errorTraces?: ToolErrorTrace[];
+    /** Session identifier for notebook entries. */
+    sessionId: string;
+}
+/**
+ * A single finding produced by the ReflectionAgent.
+ */
+export interface ReflectionFinding {
+    /** Error category. */
+    category: ReflectionErrorCategory;
+    /** What went wrong. */
+    description: string;
+    /** Root cause. */
+    cause: string;
+    /** How to avoid it next time. */
+    suggestion: string;
+    /** Related tool trace IDs (if applicable). */
+    relatedTraceIds?: string[];
+}
+/**
+ * Configuration for the ReflectionAgent.
+ */
+export interface ReflectionAgentConfig {
+    /** LLM provider (shared with the main agent). */
+    llm: LLMProvider;
+    /** ErrorNotebook for persisting findings. */
+    notebook: ErrorNotebook;
+    /**
+     * Maximum ReAct iterations for the sub-agent (default: 4).
+     */
+    maxIterations?: number;
+}
+/**
+ * ReflectionAgent — post-execution self-reflection via a forked sub-agent.
+ *
+ * After the main agent finishes, the ReflectionAgent forks a lightweight
+ * ReActAgent to review the full session trace. The fork runs in its own
+ * context with read-only tools (read_file, grep_search) so it can verify
+ * findings against the codebase.
+ *
+ * Findings are persisted to an ErrorNotebook (错题本) for future learning.
+ *
+ * Usage:
+ * ```ts
+ * const notebook = new ErrorNotebook({ storageDir: ".error-notebook" });
+ * const reflector = new ReflectionAgent({ llm, notebook, maxIterations: 4 });
+ * const entries = await reflector.reflect({
+ *   userQuery: input,
+ *   finalAnswer: answer,
+ *   conversation: contextMessages,
+ *   sessionId: "sess_123",
+ * });
+ * ```
+ */
+export declare class ReflectionAgent {
+    private llm;
+    private notebook;
+    private maxIterations;
+    constructor(config: ReflectionAgentConfig);
+    /**
+     * Fork a sub-agent to review the session and persist findings.
+     *
+     * @returns The final list of findings written to the notebook.
+     */
+    reflect(input: ReflectionInput): Promise<ErrorNotebookEntry[]>;
+    /**
+     * Fork a minimal ReActAgent and run it to completion.
+     * Returns the agent's final answer string.
+     */
+    private forkAndRun;
+    /**
+     * Build the task prompt for the sub-agent from the reflection input.
+     */
+    private buildTaskPrompt;
+    /**
+     * Format the conversation for the reflection prompt.
+     * Truncates very long tool results for readability.
+     */
+    private formatConversation;
+    /**
+     * Format error traces for the reflection prompt.
+     */
+    private formatErrorTraces;
+    /**
+     * Parse the sub-agent's final answer into a list of ReflectionFindings.
+     * Returns an empty array if parsing fails (best-effort).
+     */
+    private parseFindings;
+}
+//# sourceMappingURL=reflection-agent.d.ts.map

package/dist/reflection/reflection-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflection-agent.d.ts","sourceRoot":"","sources":["../../src/reflection/reflection-agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAQ,MAAM,mBAAmB,CAAC;AAMtD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC9F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAIrD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,mDAAmD;IACnD,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;IAC/B,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sBAAsB;IACtB,QAAQ,EAAE,uBAAuB,CAAC;IAClC,uBAAuB;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAmDD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,GAAG,EAAE,WAAW,CAAC;IACjB,6CAA6C;IAC7C,QAAQ,EAAE,aAAa,CAAC;IACxB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,GAAG,CAAc;IACzB,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,aAAa,CAAS;gBAElB,MAAM,EAAE,qBAAqB;IAQzC;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAoCpE;;;OAGG;YACW,UAAU;IAiBxB;;OAEG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAsB1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;OAGG;IACH,OAAO,CAAC,aAAa;CA2CtB"}

package/dist/reflection/reflection-agent.js

@@ -0,0 +1,234 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReflectionAgent = void 0;
+const types_1 = require("../messages/types");
+const react_agent_1 = require("../core/react-agent");
+const tool_registry_1 = require("../tools/tool-registry");
+const read_file_1 = require("../tools/builtin/read-file");
+const grep_search_1 = require("../tools/builtin/grep-search");
+const response_schema_1 = require("../core/response-schema");
+// ─── System Prompt ───────────────────────────────────────────────────────────
+const ERROR_REFLECTION_SYSTEM_PROMPT = `You are a reflective quality-assurance agent. Your job is to review a completed
+agent session and identify mistakes, missed opportunities, and improvement suggestions.
+
+You have access to read_file and grep_search tools to verify your findings against the actual codebase.
+
+Analyze the session across these dimensions:
+- **Reasoning**: Was the agent's logic sound? Any flawed deductions?
+- **Tool use**: Were the right tools used with correct parameters? Any misuse?
+- **Efficiency**: Could the task have been completed faster or with fewer steps?
+- **Completeness**: Does the answer fully address the user's query? Any missing information?
+- **Context**: Was the context window managed well? Any irrelevant noise?
+
+In your final answer, output a JSON object with this structure:
+{
+  "analysis": "overall assessment (2-4 sentences)",
+  "score": 85,
+  "findings": [
+    {
+      "category": "reasoning_error | tool_misuse | missed_optimization | incomplete_answer | hallucination | context_mismanagement | other",
+      "description": "concise description of what went wrong",
+      "cause": "root cause — why did this happen?",
+      "suggestion": "how to avoid this next time",
+      "relatedTraceIds": ["trace_abc123"]
+    }
+  ]
+}
+
+Rules:
+- Score 0-100 where 100 = flawless execution.
+- Only include findings for actual issues — do NOT fabricate problems.
+- If the session was perfect, return an empty findings array and score 100.
+- Group related findings; don't duplicate.
+- Be specific: cite exact tool names, file paths, reasoning steps where applicable.
+- Use your tools to verify findings against the actual codebase before reporting them.
+${response_schema_1.STRUCTURED_OUTPUT_INSTRUCTIONS}`;
+/**
+ * ReflectionAgent — post-execution self-reflection via a forked sub-agent.
+ *
+ * After the main agent finishes, the ReflectionAgent forks a lightweight
+ * ReActAgent to review the full session trace. The fork runs in its own
+ * context with read-only tools (read_file, grep_search) so it can verify
+ * findings against the codebase.
+ *
+ * Findings are persisted to an ErrorNotebook (错题本) for future learning.
+ *
+ * Usage:
+ * ```ts
+ * const notebook = new ErrorNotebook({ storageDir: ".error-notebook" });
+ * const reflector = new ReflectionAgent({ llm, notebook, maxIterations: 4 });
+ * const entries = await reflector.reflect({
+ *   userQuery: input,
+ *   finalAnswer: answer,
+ *   conversation: contextMessages,
+ *   sessionId: "sess_123",
+ * });
+ * ```
+ */
+class ReflectionAgent {
+    llm;
+    notebook;
+    maxIterations;
+    constructor(config) {
+        this.llm = config.llm;
+        this.notebook = config.notebook;
+        this.maxIterations = config.maxIterations ?? 4;
+    }
+    // ─── Public API ────────────────────────────────────────────────────────
+    /**
+     * Fork a sub-agent to review the session and persist findings.
+     *
+     * @returns The final list of findings written to the notebook.
+     */
+    async reflect(input) {
+        const taskPrompt = this.buildTaskPrompt(input);
+        const answer = await this.forkAndRun(taskPrompt);
+        const findings = this.parseFindings(answer);
+        // Deduplicate by category + description before persisting
+        const seen = new Set();
+        const unique = [];
+        for (const f of findings) {
+            const key = `${f.category}::${f.description.toLowerCase()}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                unique.push(f);
+            }
+        }
+        // Persist to ErrorNotebook
+        const entries = [];
+        for (const f of unique) {
+            const entry = this.notebook.add({
+                sessionId: input.sessionId,
+                category: f.category,
+                description: f.description,
+                cause: f.cause,
+                suggestion: f.suggestion,
+                userQuery: input.userQuery,
+                relatedTraceIds: f.relatedTraceIds,
+            });
+            entries.push(entry);
+        }
+        return entries;
+    }
+    // ─── Private: Fork ─────────────────────────────────────────────────────
+    /**
+     * Fork a minimal ReActAgent and run it to completion.
+     * Returns the agent's final answer string.
+     */
+    async forkAndRun(userPrompt) {
+        const tools = new tool_registry_1.ToolRegistry();
+        tools.register(read_file_1.ReadFileTool);
+        tools.register(grep_search_1.GrepSearchTool);
+        const agent = new react_agent_1.ReActAgent({
+            llm: this.llm,
+            systemPrompt: ERROR_REFLECTION_SYSTEM_PROMPT,
+            toolRegistry: tools,
+            maxIterations: this.maxIterations,
+        });
+        return agent.run(userPrompt);
+    }
+    // ─── Private: Prompt Building ──────────────────────────────────────────
+    /**
+     * Build the task prompt for the sub-agent from the reflection input.
+     */
+    buildTaskPrompt(input) {
+        const context = [
+            "Please review this agent session and identify any issues.",
+            "",
+            "=== User Query ===",
+            input.userQuery,
+            "",
+            "=== Final Answer ===",
+            input.finalAnswer,
+            "",
+            "=== Conversation ===",
+            ...this.formatConversation(input.conversation),
+            "",
+            "=== Tool Error Traces ===",
+            ...this.formatErrorTraces(input.errorTraces),
+            "",
+            "Analyze the session and output your findings as JSON in your final answer.",
+        ].join("\n");
+        return context;
+    }
+    /**
+     * Format the conversation for the reflection prompt.
+     * Truncates very long tool results for readability.
+     */
+    formatConversation(messages) {
+        const lines = [];
+        for (const msg of messages) {
+            const role = msg.role.toUpperCase();
+            let content = msg.content;
+            // Truncate long tool results
+            if (msg.role === types_1.Role.Tool && content.length > 1000) {
+                content = content.slice(0, 500) + "\n... (truncated, " + content.length + " chars total)";
+            }
+            lines.push(`[${role}] ${content}`);
+            if (msg.tool_calls && msg.tool_calls.length > 0) {
+                for (const tc of msg.tool_calls) {
+                    lines.push(`  → tool_call: ${tc.function.name}(${tc.function.arguments})`);
+                }
+            }
+        }
+        return lines;
+    }
+    /**
+     * Format error traces for the reflection prompt.
+     */
+    formatErrorTraces(traces) {
+        if (!traces || traces.length === 0)
+            return ["(no tool errors recorded)"];
+        const lines = [];
+        for (const t of traces) {
+            lines.push(`- ${t.traceId}: ${t.toolName} — ${t.resolved ? "resolved" : "unresolved"} (${t.events.length} events)`);
+        }
+        return lines;
+    }
+    // ─── Private: Parsing ──────────────────────────────────────────────────
+    /**
+     * Parse the sub-agent's final answer into a list of ReflectionFindings.
+     * Returns an empty array if parsing fails (best-effort).
+     */
+    parseFindings(answer) {
+        try {
+            // Extract JSON from the answer (may be wrapped in ```json fences)
+            let raw = answer.trim();
+            const fenceMatch = raw.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+            if (fenceMatch)
+                raw = fenceMatch[1];
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed.findings))
+                return [];
+            const validCategories = new Set([
+                "reasoning_error", "tool_misuse", "missed_optimization",
+                "incomplete_answer", "hallucination", "context_mismanagement", "other",
+            ]);
+            const findings = [];
+            for (const f of parsed.findings) {
+                if (typeof f.category !== "string" ||
+                    !validCategories.has(f.category) ||
+                    typeof f.description !== "string" ||
+                    typeof f.cause !== "string" ||
+                    typeof f.suggestion !== "string") {
+                    continue;
+                }
+                findings.push({
+                    category: f.category,
+                    description: f.description,
+                    cause: f.cause,
+                    suggestion: f.suggestion,
+                    relatedTraceIds: Array.isArray(f.relatedTraceIds)
+                        ? f.relatedTraceIds.filter((id) => typeof id === "string")
+                        : undefined,
+                });
+            }
+            return findings;
+        }
+        catch {
+            return [];
+        }
+    }
+}
+exports.ReflectionAgent = ReflectionAgent;
+//# sourceMappingURL=reflection-agent.js.map