kagent-ts 0.1.3 → 0.1.5

package/dist/core/agent.js

@@ -1,11 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Agent = void 0;
+const model_router_1 = require("../llm/model-router");
+const message_1 = require("../messages/message");
+const system_prompts_1 = require("./system-prompts");
+const boundaries_1 = require("../security/boundaries");
 const context_manager_1 = require("../context/context-manager");
 const tool_registry_1 = require("../tools/tool-registry");
+const tool_output_truncator_1 = require("../tools/tool-output-truncator");
+const types_1 = require("../tools/types");
+const tool_validator_1 = require("../tools/tool-validator");
 const skill_manager_1 = require("../skills/skill-manager");
+const memory_manager_1 = require("../memory/memory-manager");
+const project_rules_1 = require("../rules/project-rules");
 const session_manager_1 = require("../session/session-manager");
+const token_counter_1 = require("../utils/token-counter");
 const preference_manager_1 = require("../preferences/preference-manager");
+const mcp_client_manager_1 = require("../mcp/mcp-client-manager");
+const subagent_manager_1 = require("../subagent/subagent-manager");
+const rag_manager_1 = require("../rag/rag-manager");
+const search_knowledge_1 = require("../rag/search-knowledge");
+const list_subagents_1 = require("../tools/builtin/list-subagents");
+const spawn_subagent_1 = require("../tools/builtin/spawn-subagent");
+const list_errors_1 = require("../tools/builtin/list-errors");
+const skill_1 = require("../tools/builtin/skill");
+const remember_1 = require("../tools/builtin/remember");
+const recall_1 = require("../tools/builtin/recall");
+const builtin_1 = require("../tools/builtin");
+const logger_1 = require("../logging/logger");
+const token_budget_1 = require("../llm/token-budget");
 /**
  * Abstract base Agent class.
  *
@@ -25,6 +48,10 @@ class Agent {
     contextManager;
     toolRegistry;
     skillManager;
+    /** Long-term memory (rules + project facts) persisted across sessions. */
+    memoryManager;
+    /** User-defined project rules loaded from disk. */
+    projectRules;
     /** The original core system prompt (before skill sections are appended). */
     coreSystemPrompt;
     /** User preferences — plain-text directives injected into the system prompt. */
@@ -33,10 +60,14 @@ class Agent {
     preferenceManager;
     /** Lifecycle hooks for observing agent execution. */
     hooks = [];
-    /**
-     * Trace ID of the most recent tool error waiting for LLM analysis.
-     * Set after a tool fails, cleared when the LLM's analysis is recorded. */
-    pendingErrorTraceId = null;
+    /** Logger for framework-internal messages. */
+    logger;
+    /** Token budget for session-level cost control (optional). */
+    tokenBudget;
+    /** Human-in-the-loop approval callback (from AgentConfig). */
+    onToolApproval;
+    /** Whether to execute independent tool calls in parallel (default: true). */
+    enableParallelToolExecution;
     // ─── Session & Cancellation ─────────────────────────────────────────
     /** Session manager for checkpoint persistence (optional). */
     sessionManager;
@@ -44,36 +75,64 @@ class Agent {
     checkpointingEnabled = false;
     /** Whether the current run has been cancelled by the user. */
     _cancelled = false;
+    /** Controller for aborting in-flight LLM requests on cancellation. */
+    _abortController;
+    // ─── MCP (Model Context Protocol) ─────────────────────────────────────
+    /** MCP server configurations (from AgentConfig). */
+    mcpServerConfigs;
+    /** MCP client manager for dynamic tool discovery (lazily initialized). */
+    mcpClientManager;
+    /** Guards async init() from running more than once per instance. */
+    _mcpInitialized = false;
+    // ─── RAG ────────────────────────────────────────────────────────────────
+    /** RAG manager (lazily initialized in init()). */
+    ragManager;
+    /** RAG configuration (from AgentConfig). */
+    ragConfig;
+    // ─── Sub-Agent ────────────────────────────────────────────────────────
+    /** Sub-agent manager (lazily initialized in init()). */
+    subAgentManager;
+    /** Sub-agent definitions directory (from AgentConfig). */
+    subAgentsDir;
+    /** LLM provider for sub-agents (defaults to main llm if not set). */
+    subAgentLLM;
+    /** Skills directory path (from AgentConfig). */
+    skillsDir;
     constructor(config) {
         this._cancelled = false;
         this.llm = config.llm;
-        this.contextManager = config.contextManager ?? new context_manager_1.ContextManager();
+        this.logger = config.logger ?? new logger_1.ConsoleLogger();
+        this.onToolApproval = config.onToolApproval;
+        this.enableParallelToolExecution = config.enableParallelToolExecution ?? true;
+        this.contextManager = config.contextManager ?? new context_manager_1.ContextManager(undefined, this.logger);
         // Prefer toolRegistry; fall back to plain tools array
         if (config.toolRegistry) {
             this.toolRegistry = config.toolRegistry;
         }
         else {
-            this.toolRegistry = new tool_registry_1.ToolRegistry(config.toolRetryCount, config.toolErrorTracker);
+            const truncator = (config.toolOutputMaxBytes && config.toolOutputMaxBytes > 0)
+                ? new tool_output_truncator_1.ToolOutputTruncator(config.toolOutputMaxBytes)
+                : undefined;
+            this.toolRegistry = new tool_registry_1.ToolRegistry(config.toolRetryCount, config.toolErrorTracker, truncator);
             if (config.tools && config.tools.length > 0) {
                 this.toolRegistry.registerMany(config.tools);
             }
         }
-        // Skill manager — auto-bind the tool registry so skill tools register
+        // Skill manager — file-based progressive disclosure
         if (config.skillManager) {
             this.skillManager = config.skillManager;
         }
         else {
-            this.skillManager = new skill_manager_1.SkillManager();
-        }
-        this.skillManager.bindToolRegistry(this.toolRegistry);
-        // Register any skills passed directly
-        if (config.skills && config.skills.length > 0) {
-            this.skillManager.register(...config.skills);
+            this.skillManager = new skill_manager_1.SkillManager(this.logger);
         }
         // Register file-based skills if a directory is configured
         if (config.skillsDir) {
             this.skillManager.registerFromDirectory(config.skillsDir);
         }
+        // Memory — long-term facts, rules, and project context
+        this.memoryManager = new memory_manager_1.MemoryManager(config.memoryDir);
+        // Project rules — user-authored, always injected
+        this.projectRules = new project_rules_1.ProjectRules(config.rulesPath);
         // Store core system prompt and set it
         this.coreSystemPrompt = config.systemPrompt ?? "";
         if (this.coreSystemPrompt) {
@@ -87,6 +146,24 @@ class Agent {
             });
         }
         this.checkpointingEnabled = config.enableCheckpointing ?? false;
+        this.mcpServerConfigs = config.mcpServers;
+        this.subAgentsDir = config.subAgentsDir;
+        this.skillsDir = config.skillsDir;
+        this.ragConfig = config.rag;
+        // Resolve sub-agent LLM:
+        // 1. Explicit `subAgentLLM` → use it directly
+        // 2. `llm` is a ModelRouter → use router.forSubAgent()
+        // 3. Fallback → sub-agents share the main `llm`
+        if (config.subAgentLLM) {
+            this.subAgentLLM = config.subAgentLLM;
+        }
+        else if (config.llm instanceof model_router_1.ModelRouter) {
+            this.subAgentLLM = config.llm.forSubAgent();
+        }
+        // Token budget — session-level cost control
+        if (config.tokenBudgetConfig) {
+            this.tokenBudget = new token_budget_1.TokenBudget(config.tokenBudgetConfig);
+        }
         // ── Hooks ──────────────────────────────────────────────────────────────
         const rawHooks = config.hooks ?? [];
         this.hooks = Array.isArray(rawHooks) ? rawHooks : [rawHooks];
@@ -118,12 +195,6 @@ class Agent {
         return this.toolRegistry;
     }
     // ─── Skill Management ────────────────────────────────────────────────
-    /**
-     * Add skills to the agent's SkillManager.
-     */
-    addSkill(...skills) {
-        this.skillManager.register(...skills);
-    }
     /**
      * Get the SkillManager (for advanced management).
      */
@@ -160,42 +231,372 @@ class Agent {
         this.hooks.push(hook);
     }
     /**
-     * Rebuild the system message from the core prompt + user preferences + active skills.
-     * Called automatically when skills are activated/deactivated or preferences change.
+     * Rebuild the system message.
+     *
+     * Sections are assembled in priority order:
+     *   1. Core prompt           (agent identity + instructions)
+     *   2. Project rules         (user-authored, always injected)
+     *   3. Preferences           (user-set language / verbosity / style)
+     *   4. Error recovery rules  (tool failure recovery guidance)
+     *   5. Long-term memories    (index of persisted facts + rules)
+     *   6. Available skills      (inactive skills the LLM can activate)
+     *   7. Active skill content  (full instructions for activated skills)
+     *
+     * Empty sections are silently skipped.
      */
+    /**
+     * Build the full system prompt from all sections.
+     *
+     * Subclasses that need to append extra content (e.g. plan progress)
+     * should call this and concatenate, instead of duplicating the assembly.
+     */
+    buildSystemPrompt() {
+        const sections = [
+            this.coreSystemPrompt,
+            system_prompts_1.SECURITY_GUIDANCE,
+            this.hasSubAgents() ? system_prompts_1.SUB_AGENT_DELEGATION : "",
+            this.projectRules.buildPrompt(),
+            preference_manager_1.PreferenceManager.toPrompt(this.preferences),
+            this.memoryManager.buildPromptHint(),
+            this.skillManager.buildAvailableSkillsHint(),
+            this.skillManager.buildSkillsPrompt(),
+        ].filter(Boolean);
+        return sections.join("");
+    }
     rebuildSystemPrompt() {
-        const prefsPrompt = preference_manager_1.PreferenceManager.toPrompt(this.preferences);
-        const skillsHint = this.skillManager.buildAvailableSkillsHint();
-        const skillsContent = this.skillManager.buildSkillsPrompt();
-        const fullPrompt = this.coreSystemPrompt + prefsPrompt + skillsHint + skillsContent;
-        this.contextManager.setSystemMessage(fullPrompt);
+        this.contextManager.setSystemMessage(this.buildSystemPrompt());
     }
     /**
-     * Pre-iteration maintenance:
-     * 1. Compress context window if needed.
-     * 2. Auto-reload preferences from disk if the file was manually edited.
+     * Pre-iteration maintenance: compress context window if needed.
      */
-    checkAndCompress() {
-        if (this.contextManager.shouldCompress()) {
-            const { removedCount } = this.contextManager.compress();
-            console.log(`[Context] Compression triggered: removed ${removedCount} messages.`);
-        }
-        // Auto-reload preferences if the file was manually edited
+    async checkAndCompress() {
+        await this.contextManager.checkAndCompress(this.llm);
+    }
+    /**
+     * Reload preferences from disk if the file was manually edited.
+     * Called once at the start of each run so edits between runs take
+     * effect without restarting the agent process — but they won't
+     * change mid-run behavior.
+     */
+    reloadPreferencesIfChanged() {
         if (this.preferenceManager?.hasFileChanged()) {
             this.preferences = this.preferenceManager.reload();
             this.rebuildSystemPrompt();
-            console.log("[Preferences] Reloaded from disk (file changed).");
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Re-scan the skills directory for new SKILL.md files added between runs.
+     * New skills are registered and become available to the LLM immediately.
+     */
+    reloadSkillsFromDirectory() {
+        if (!this.skillsDir)
+            return false;
+        const added = this.skillManager.reloadFromDirectory(this.skillsDir);
+        if (added.length > 0) {
+            this.rebuildSystemPrompt();
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Re-read the MEMORY.md index from disk if it was manually edited
+     * between runs. The index is a lightweight list of memory names +
+     * descriptions — full content is loaded on demand via the recall tool.
+     */
+    reloadMemoryIfChanged() {
+        if (this.memoryManager.reloadIfChanged()) {
+            this.rebuildSystemPrompt();
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Incrementally connect to MCP servers that were added to the config
+     * since the last run. Already-connected servers are left untouched.
+     */
+    async reconnectMCPIfNeeded() {
+        if (!this.mcpClientManager || !this.mcpServerConfigs)
+            return;
+        const newServers = {};
+        for (const [name, config] of Object.entries(this.mcpServerConfigs)) {
+            if (!this.mcpClientManager.hasServer(name)) {
+                newServers[name] = config;
+            }
+        }
+        if (Object.keys(newServers).length === 0)
+            return;
+        const errors = await this.mcpClientManager.connectAll(newServers);
+        if (errors.length > 0) {
+            this.logger.warn("MCP", `${errors.length} new server(s) failed to connect: ` +
+                errors.map((e) => e.serverName).join(", "));
+        }
+    }
+    /**
+     * Reload all dynamic resources at the start of a run.
+     * Picks up changes made between conversation turns.
+     */
+    async reloadDynamicResources() {
+        this.reloadPreferencesIfChanged(); // rebuilds internally if changed
+        const rulesChanged = this.projectRules.reloadIfChanged();
+        this.reloadSkillsFromDirectory(); // rebuilds internally if changed
+        this.reloadMemoryIfChanged(); // rebuilds internally if changed
+        if (rulesChanged) {
+            this.rebuildSystemPrompt();
+        }
+        await this.reconnectMCPIfNeeded();
+    }
+    /**
+     * After a resume, recover results from sub-agents that were cancelled
+     * mid-run. Completed results are injected into context so the LLM can
+     * see them; still-running sub-agents get a notice.
+     */
+    recoverOrphanedSubAgentResults() {
+        if (!this.subAgentManager)
+            return;
+        const orphaned = this.subAgentManager.collectOrphanedResults();
+        for (const r of orphaned) {
+            const msg = message_1.Message.user(`[Sub-agent "${r.name}" (${r.subAgentId}) — recovered after interruption]\n\n${r.output}`);
+            this.contextManager.addMessage(msg.toDict());
+        }
+        // If some cancelled sub-agents are still running, let the LLM know
+        const stillRunning = this.subAgentManager.getActiveCount();
+        if (stillRunning > 0) {
+            const msg = message_1.Message.user(`[System] ${stillRunning} sub-agent(s) from the previous session are still running. ` +
+                `Their results will appear when ready. Do not re-spawn them.`);
+            this.contextManager.addMessage(msg.toDict());
+        }
+    }
+    /**
+     * Validate that user input won't overwhelm the context window.
+     *
+     * Returns a user-facing error string if the input is too large,
+     * or `null` if it passes the check.
+     */
+    validateInputSize(input) {
+        const { maxTokens } = this.contextManager.getState();
+        const inputTokens = (0, token_counter_1.countTokens)(input);
+        // Reserve ~20% for system prompt + tools + response overhead
+        const maxSafeInput = Math.floor(maxTokens * 0.8);
+        if (inputTokens > maxSafeInput) {
+            return (`Your input is too large (~${inputTokens} tokens). ` +
+                `The maximum safe input size is ~${maxSafeInput} tokens ` +
+                `(context window: ${maxTokens} tokens, with 20% reserved for system overhead). ` +
+                `Please split your request into smaller parts.`);
+        }
+        return null;
+    }
+    /**
+     * Check whether a tool that requires approval should be executed.
+     *
+     * @returns `true` if approved, `false` if denied (or no callback configured).
+     */
+    async checkToolApproval(toolName, args) {
+        if (!this.onToolApproval) {
+            this.logger.warn("Approval", `Tool "${toolName}" requires approval but no onToolApproval configured — denied.`);
+            return false;
+        }
+        try {
+            return await this.onToolApproval(toolName, args);
+        }
+        catch {
+            this.logger.warn("Approval", `Approval callback threw for "${toolName}" — denied.`);
+            return false;
+        }
+    }
+    /**
+     * Execute a batch of tool calls from a single LLM response.
+     *
+     * When `enableParallelToolExecution` is true and all tools in the batch are
+     * parallel-safe (`sequential` is not set), tools execute concurrently via
+     * `Promise.allSettled`. Otherwise, they execute one at a time (serial).
+     *
+     * Handles the full lifecycle for each tool call:
+     * 1. Parse JSON arguments (malformed args → error result, no execution)
+     * 2. HITL approval check for tools marked `requireApproval`
+     * 3. Hook notifications (`onToolStart`, `onToolEnd`, `onToolError`)
+     * 4. Execution via `ToolRegistry.execute()`
+     * 5. Context injection (all results added after execution completes)
+     * 6. Post-execution: sub-agent spawn tracking, MCP failure warnings
+     *
+     * @param toolCalls       The tool calls from the LLM response.
+     * @param mcpWarnedServers Set tracking which MCP servers have already
+     *                         been warned about in this batch.
+     * @returns Whether any tool in the batch failed.
+     */
+    async executeToolCallsBatch(toolCalls, mcpWarnedServers) {
+        // ── Step 1: Parse & validate all arguments up front ──────────────
+        const slots = [];
+        for (const tc of toolCalls) {
+            // 1a. JSON syntax check
+            let args;
+            try {
+                args = JSON.parse(tc.function.arguments);
+            }
+            catch {
+                const result = (0, types_1.toolError)(types_1.ToolErrorCode.ARGUMENTS_PARSE_ERROR, `[RETRYABLE:ARGUMENTS_PARSE_ERROR] Failed to parse arguments for tool "${tc.function.name}". ` +
+                    `The raw arguments were: ${tc.function.arguments || "(empty)"}\n\n` +
+                    `Please re-invoke the tool with correctly formatted JSON arguments.`, "retryable");
+                for (const h of this.hooks)
+                    h.onToolError?.(tc.function.name, result.content, tc.id);
+                slots.push({ toolCall: tc, args: {}, result });
+                continue;
+            }
+            // 1b. JSON Schema validation against the tool's parameter definition
+            const tool = this.toolRegistry.getTool(tc.function.name);
+            if (tool) {
+                const validationError = (0, tool_validator_1.validateToolArgs)(tc.function.name, tool.parameters, args);
+                if (validationError) {
+                    for (const h of this.hooks)
+                        h.onToolError?.(tc.function.name, validationError.content, tc.id);
+                    slots.push({ toolCall: tc, args, result: validationError });
+                    continue;
+                }
+            }
+            slots.push({ toolCall: tc, args });
+        }
+        // ── Step 2: HITL approval — check all requiring tools upfront ────
+        for (const slot of slots) {
+            if (slot.result)
+                continue; // already failed at parse stage
+            const tool = this.toolRegistry.getTool(slot.toolCall.function.name);
+            if (tool?.requireApproval) {
+                const approved = await this.checkToolApproval(slot.toolCall.function.name, slot.args);
+                if (!approved) {
+                    slot.result = (0, types_1.toolError)(types_1.ToolErrorCode.APPROVAL_DENIED, `[FATAL:APPROVAL_DENIED] Tool "${slot.toolCall.function.name}" requires approval and was denied. ` +
+                        `Do NOT retry this tool. Find a different approach.`, "fatal");
+                    for (const h of this.hooks)
+                        h.onToolError?.(slot.toolCall.function.name, slot.result.content, slot.toolCall.id);
+                }
+            }
+        }
+        // ── Step 3: Decide serial vs parallel ──────────────────────────────
+        const executable = slots.filter((s) => !s.result);
+        const allParallelSafe = executable.every((s) => {
+            const tool = this.toolRegistry.getTool(s.toolCall.function.name);
+            return !tool?.sequential;
+        });
+        const shouldParallelize = this.enableParallelToolExecution &&
+            allParallelSafe &&
+            executable.length > 1;
+        // ── Step 4: Execute ────────────────────────────────────────────────
+        if (shouldParallelize) {
+            // Fire onToolStart for all executable tools before concurrent execution
+            for (const slot of executable) {
+                for (const h of this.hooks)
+                    h.onToolStart?.(slot.toolCall.function.name, slot.args, slot.toolCall.id);
+            }
+            // Execute all in parallel.
+            // Each task fires its own onToolEnd / onToolError hooks so the
+            // TraceLogger (and other hook consumers) see events in actual
+            // completion order rather than array order.
+            await Promise.allSettled(executable.map(async (slot) => {
+                const result = await this.toolRegistry.execute(slot.toolCall.function.name, slot.args);
+                slot.result = result;
+                if (result.success) {
+                    for (const h of this.hooks)
+                        h.onToolEnd?.(slot.toolCall.function.name, result.content, slot.toolCall.id);
+                }
+                else {
+                    for (const h of this.hooks)
+                        h.onToolError?.(slot.toolCall.function.name, result.content, slot.toolCall.id);
+                }
+            }));
+        }
+        else {
+            // Serial path (legacy behaviour or forced by sequential tools)
+            for (const slot of executable) {
+                for (const h of this.hooks)
+                    h.onToolStart?.(slot.toolCall.function.name, slot.args, slot.toolCall.id);
+                slot.result = await this.toolRegistry.execute(slot.toolCall.function.name, slot.args);
+                if (slot.result.success) {
+                    for (const h of this.hooks)
+                        h.onToolEnd?.(slot.toolCall.function.name, slot.result.content, slot.toolCall.id);
+                }
+                else {
+                    for (const h of this.hooks)
+                        h.onToolError?.(slot.toolCall.function.name, slot.result.content, slot.toolCall.id);
+                }
+            }
+        }
+        // ── Step 5: Inject results into context & post-process ─────────────
+        let hadFailure = false;
+        for (const slot of slots) {
+            const result = slot.result;
+            const toolName = slot.toolCall.function.name;
+            const toolMessage = message_1.Message.tool((0, boundaries_1.wrapAndScan)(`tool:${toolName}`, result.content), slot.toolCall.id, toolName);
+            this.contextManager.addMessage(toolMessage.toDict());
+            if (!result.success) {
+                hadFailure = true;
+            }
+            // Sub-agent spawned — purely informational; results arrive
+            // asynchronously and will be injected via pollSubAgentResults().
+            if (result.success && slot.toolCall.function.name === "spawn_subagent") {
+                this.logger.info("SubAgent", `Spawned "${slot.args.name ?? "unknown"}" — ` +
+                    `result will arrive in a later iteration.`);
+            }
+            // MCP tool failure — warn about potential connection loss.
+            // Only warn once per server per batch to avoid duplicate messages.
+            if (!result.success &&
+                !builtin_1.BUILTIN_TOOL_NAMES.has(slot.toolCall.function.name)) {
+                const serverName = slot.toolCall.function.name.split("_")[0] ?? "unknown";
+                if (!mcpWarnedServers.has(serverName)) {
+                    const isConnErr = result.content.includes("connection") ||
+                        result.content.includes("not connected") ||
+                        result.content.includes("ECONNREFUSED") ||
+                        result.content.includes("ENOTFOUND");
+                    if (isConnErr) {
+                        mcpWarnedServers.add(serverName);
+                        this.logger.info("MCP", `Connection lost to server "${serverName}" — ` +
+                            `further calls to this server may fail.`);
+                        const mcpWarn = message_1.Message.system(`MCP server "${serverName}" appears to be disconnected: ${result.content.slice(0, 200)}`);
+                        this.contextManager.addMessage(mcpWarn.toDict());
+                    }
+                }
+            }
+        }
+        return { hadFailure };
+    }
+    /**
+     * Check whether the token budget allows another LLM call.
+     *
+     * @param estimatedInputTokens  Approximate tokens in the upcoming request
+     *                              (system prompt + context messages).
+     * @returns A user-facing error string if the budget is exhausted,
+     *          or `null` if the call can proceed.
+     */
+    checkTokenBudget(estimatedInputTokens) {
+        if (!this.tokenBudget)
+            return null;
+        const status = this.tokenBudget.checkBeforeCall(estimatedInputTokens);
+        if (status.isExhausted) {
+            return (`Token budget exhausted: ${status.totalTokensUsed.toLocaleString()}/${status.maxTotalTokens.toLocaleString()} tokens used ` +
+                `across ${status.callCount} LLM calls. ` +
+                `Start a new conversation with agent.newTopic() or agent.clearConversation() to reset the budget.`);
+        }
+        // One-shot warning at 80 %
+        if (this.tokenBudget.shouldWarn()) {
+            this.logger.warn("TokenBudget", `Warning: ${Math.round(status.totalTokensUsed / status.maxTotalTokens * 100)}% of budget used ` +
+                `(${status.totalTokensUsed.toLocaleString()}/${status.maxTotalTokens.toLocaleString()} tokens).`);
         }
+        return null;
     }
     // ─── Cancellation ────────────────────────────────────────────────────
     /**
      * Cancel the current run.
      *
-     * Prevents any further checkpoint saves. Call this when the user presses
-     * SIGINT to discard the session rather than persisting it.
+     * Aborts any in-flight LLM request via the AbortController, sets the
+     * cancellation flag, and cancels all running sub-agents. The agent loop
+     * will save a "cancelled" checkpoint and exit at its next iteration.
+     * The session is preserved on disk and can be resumed later.
      */
     cancel() {
+        // Abort the in-flight LLM request first so the agent doesn't keep
+        // waiting for a response that's about to be discarded anyway.
+        this._abortController?.abort();
         this._cancelled = true;
+        this.subAgentManager?.cancelAll();
     }
     /**
      * Whether the run has been cancelled by the user.
@@ -269,17 +670,41 @@ class Agent {
         };
     }
     /**
-     * Save a session checkpoint to disk (if session manager is configured
-     * and the run has NOT been cancelled).
+     * Save a session checkpoint to disk (if session manager is configured).
      */
     saveCheckpoint(status = "active") {
         if (!this.sessionManager)
             return;
-        if (this.isCancelled)
-            return; // Don't save on abort
         const state = this.buildBaseSessionState(status);
         this.sessionManager.saveCheckpoint(state);
     }
+    /**
+     * Handle an LLMNetworkError: save an interrupted checkpoint if
+     * checkpointing is enabled, and return a user-facing message with
+     * resume instructions.
+     *
+     * @param err               The network error that occurred.
+     * @param iteration         The current iteration number (for the log).
+     * @param resumeInstruction What the user should type to resume
+     *                          (e.g. "continue with my previous request").
+     */
+    handleNetworkError(err, iteration, resumeInstruction = "continue") {
+        if (this.checkpointingEnabled) {
+            this.saveCheckpoint("interrupted");
+        }
+        const sid = this.sessionManager?.getSessionId() ?? "unknown";
+        this.logger.error("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}", "${resumeInstruction}")\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.`);
+    }
     /**
      * Restore agent state from a previously saved session.
      *
@@ -303,6 +728,9 @@ class Agent {
             throw new Error(`Session "${sessionId}" was created by a ${state.agentType} agent, ` +
                 `but this agent is type "${expectedType}". Cannot resume.`);
         }
+        // Clear cancellation state — the user explicitly chose to resume
+        this._cancelled = false;
+        this._abortController = undefined; // will be recreated in run()
         // Sync session manager to the restored session ID so subsequent
         // checkpoints write to the correct file
         this.sessionManager.setSessionId(state.sessionId);
@@ -326,6 +754,49 @@ class Agent {
      */
     clearConversation() {
         this.contextManager.clear();
+        this.tokenBudget?.reset();
+    }
+    /**
+     * Continue the current conversation with a follow-up input.
+     *
+     * Equivalent to `run()` but conveys the semantics of a multi-turn
+     * conversation continuation. Messages from previous calls are preserved
+     * in context, so the LLM sees the full conversation history.
+     *
+     * @param input The follow-up message from the user.
+     * @returns The agent's response.
+     */
+    async chat(input) {
+        return this.run(input);
+    }
+    /**
+     * Start a new topic with a fresh conversation.
+     *
+     * Clears the message history (preserving the system prompt and
+     * configuration) and runs the input as the first message of a
+     * new conversation. The token budget is also reset.
+     *
+     * @param input The first message of the new topic.
+     * @returns The agent's response.
+     */
+    async newTopic(input) {
+        this.clearConversation();
+        return this.run(input);
+    }
+    /**
+     * The number of messages in the current conversation (excluding the
+     * system message). Use this to check whether there is an active
+     * conversation or to monitor context growth.
+     */
+    get conversationLength() {
+        return this.contextManager.getMessages().length;
+    }
+    /**
+     * Get the cumulative token consumption and cost for the current session.
+     * Returns null if no `tokenBudgetConfig` was configured.
+     */
+    getSessionCost() {
+        return this.tokenBudget?.getSessionCost() ?? null;
     }
     /**
      * Reset the agent to its initial state.
@@ -334,10 +805,13 @@ class Agent {
      * After calling reset(), the agent behaves as if newly constructed.
      */
     reset() {
+        this._abortController?.abort();
+        this._cancelled = false;
         this.contextManager.clear();
         this.coreSystemPrompt = "";
         this.preferences = {};
-        this.pendingErrorTraceId = null;
+        this.tokenBudget?.reset();
+        this.subAgentManager?.cancelAll();
         if (this.sessionManager) {
             this.sessionManager.deleteSession(this.sessionManager.getSessionId());
         }
@@ -349,6 +823,147 @@ class Agent {
     getAgentType() {
         return "react";
     }
+    // ─── MCP / Async Initialization ─────────────────────────────────────────
+    /**
+     * Initialize async resources (MCP connections, tool discovery).
+     *
+     * Idempotent — safe to call multiple times; the actual work happens
+     * only on the first invocation. Subclasses SHOULD call `await this.init()`
+     * at the start of `run()`.
+     *
+     * If MCP servers are configured:
+     * 1. Creates an McpClientManager bound to the tool registry.
+     * 2. Connects to each server and registers discovered tools.
+     * 3. Logs warnings for any servers that fail to connect.
+     */
+    async init() {
+        if (this._mcpInitialized)
+            return;
+        this._mcpInitialized = true;
+        // ── Error tracking tool ──────────────────────────────────────────
+        try {
+            this.toolRegistry.register((0, list_errors_1.createListErrorsTool)(this.toolRegistry));
+        }
+        catch {
+            this.logger.debug("Init", `"list_errors" already registered — keeping existing.`);
+        }
+        // ── MCP connections ──────────────────────────────────────────────
+        if (this.mcpServerConfigs && Object.keys(this.mcpServerConfigs).length > 0) {
+            this.mcpClientManager = new mcp_client_manager_1.McpClientManager(this.toolRegistry, this.logger);
+            const errors = await this.mcpClientManager.connectAll(this.mcpServerConfigs);
+            if (errors.length > 0) {
+                this.logger.warn("MCP", `${errors.length} of ${Object.keys(this.mcpServerConfigs).length} server(s) failed to connect.`);
+            }
+        }
+        // ── Sub-agent registry ───────────────────────────────────────────
+        if (this.subAgentsDir) {
+            this.subAgentManager = new subagent_manager_1.SubAgentManager();
+            this.subAgentManager.setLogger(this.logger);
+            this.subAgentManager.bind(this.llm, this.toolRegistry, this.skillManager, this.skillsDir, undefined, undefined, this.subAgentLLM);
+            this.subAgentManager.registerFromDirectory(this.subAgentsDir);
+            // Register sub-agent tools into the tool registry
+            try {
+                this.toolRegistry.register((0, list_subagents_1.createListSubagentsTool)(this.subAgentManager));
+            }
+            catch {
+                this.logger.debug("Init", `"list_subagents" already registered — keeping existing.`);
+            }
+            try {
+                this.toolRegistry.register((0, spawn_subagent_1.createSpawnSubagentTool)(this.subAgentManager));
+            }
+            catch {
+                this.logger.debug("Init", `"spawn_subagent" already registered — keeping existing.`);
+            }
+        }
+        // ── RAG knowledge base ─────────────────────────────────────────────
+        if (this.ragConfig) {
+            this.ragManager = new rag_manager_1.RAGManager(this.ragConfig, this.logger);
+            await this.ragManager.index();
+            try {
+                this.toolRegistry.register((0, search_knowledge_1.createSearchKnowledgeTool)(this.ragManager));
+            }
+            catch {
+                this.logger.debug("Init", `"search_knowledge" already registered — keeping existing.`);
+            }
+            try {
+                this.toolRegistry.register((0, search_knowledge_1.createListKnowledgeDocumentsTool)(this.ragManager));
+            }
+            catch {
+                this.logger.debug("Init", `"list_knowledge_documents" already registered — keeping existing.`);
+            }
+        }
+        // ── Skill tool (LLM-driven activation) ────────────────────────────
+        try {
+            this.toolRegistry.register((0, skill_1.createSkillTool)(this.skillManager, () => this.rebuildSystemPrompt()));
+        }
+        catch {
+            this.logger.debug("Init", `"skill" already registered — keeping existing.`);
+        }
+        // ── Remember / Recall tools (long-term memory) ────────────────────
+        try {
+            this.toolRegistry.register((0, remember_1.createRememberTool)(this.memoryManager));
+        }
+        catch {
+            this.logger.debug("Init", `"remember" already registered — keeping existing.`);
+        }
+        try {
+            this.toolRegistry.register((0, recall_1.createRecallTool)(this.memoryManager));
+        }
+        catch {
+            this.logger.debug("Init", `"recall" already registered — keeping existing.`);
+        }
+    }
+    /**
+     * Gracefully shut down MCP connections.
+     *
+     * Disconnects all servers and unregisters their tools. Safe to call
+     * even if init() was never called or no servers were configured.
+     */
+    async shutdown() {
+        await this.mcpClientManager?.disconnectAll();
+        if (this.subAgentManager) {
+            await this.subAgentManager.awaitAll();
+        }
+    }
+    // ─── Sub-Agent ────────────────────────────────────────────────────────
+    /**
+     * Check whether sub-agents are available.
+     *
+     * Used by `buildSystemPrompt()` to decide whether to include sub-agent
+     * delegation instructions. Returns true only when a SubAgentManager is
+     * configured AND has at least one registered definition.
+     */
+    hasSubAgents() {
+        return this.subAgentManager?.hasDefinitions() === true;
+    }
+    /**
+     * Spawn a sub-agent by definition name.
+     *
+     * The sub-agent runs asynchronously — this method returns immediately.
+     * Call `pollSubAgentResults()` at the start of each iteration to
+     * collect completed results.
+     *
+     * @param name  The registered sub-agent definition name.
+     * @param input The task description for the sub-agent.
+     * @returns The unique run ID.
+     */
+    spawnSubAgent(name, input) {
+        if (!this.subAgentManager) {
+            throw new Error("No SubAgentManager configured. Set `subAgentsDir` in AgentConfig.");
+        }
+        return this.subAgentManager.spawn(name, input);
+    }
+    /**
+     * Poll for completed sub-agent results.
+     *
+     * Should be called at the start of each ReAct iteration to inject
+     * sub-agent outputs into the main agent's context.
+     */
+    async pollSubAgentResults() {
+        if (!this.subAgentManager)
+            return [];
+        return this.subAgentManager.pollCompleted();
+    }
     // ─── Error Trace & Analysis ──────────────────────────────────────────
     /**
      * Get the error tracker (if configured via the ToolRegistry).
@@ -357,38 +972,38 @@ class Agent {
         return this.toolRegistry.getErrorTracker();
     }
     /**
-     * Call after a tool returns an error string — checks if the error
-     * indicates a tool failure (with retry guidance) and saves the trace ID
-     * so the next LLM analysis thought can be captured.
+     * Call after a tool returns a result — checks if the result indicates
+     * a tool failure (retryable or fatal) and saves the trace ID so the
+     * next LLM analysis thought can be captured.
      *
-     * @param toolName The name of the tool that failed.
-     * @param result   The string returned by ToolRegistry.execute().
+     * @param toolName The name of the tool that was executed.
+     * @param result   The structured ToolResult returned by ToolRegistry.execute().
      */
-    trackToolErrorForAnalysis(toolName, result) {
-        const tracker = this.errorTracker;
-        if (!tracker)
-            return;
-        // Check if the result contains retry guidance (indicating a failure)
-        if (result.includes("[Retry Guidance]") || result.includes("has been automatically disabled")) {
-            const activeTraceId = tracker.getActiveTraceId(toolName);
-            if (activeTraceId) {
-                this.pendingErrorTraceId = activeTraceId;
-            }
-        }
-    }
     /**
-     * Records the LLM's analysis thought against the pending tool error trace.
-     * Should be called each iteration after parsing the LLM's response.
+     * Capture the LLM's reasoning as error analysis for any active tool error traces.
+     *
+     * Call this after parsing the LLM's `thought` from each response. If any tools
+     * have an open failure chain (active trace), the thought is recorded as the
+     * LLM's analysis of what went wrong and how to proceed.
+     *
+     * This feeds the error→analysis pipeline:
+     *  1. Tool fails     → recordFailure() creates an active trace
+     *  2. LLM sees error → its next thought IS the analysis
+     *  3. Analysis       → recordAnalysis() attaches the LLM's reasoning to the trace
      *
-     * @param thought The LLM's thought/analysis content.
+     * For cross-session learning, use ErrorNotebook (错题本) via ReflectionHook.
+     *
+     * @param thought The LLM's reasoning (from parsed.thought).
      */
-    captureAnalysisFromThought(thought) {
-        if (this.pendingErrorTraceId && thought) {
-            const tracker = this.errorTracker;
-            if (tracker) {
-                tracker.recordAnalysis(this.pendingErrorTraceId, thought);
-            }
-            this.pendingErrorTraceId = null;
+    captureErrorAnalysis(thought) {
+        if (!thought)
+            return;
+        const tracker = this.toolRegistry.getErrorTracker();
+        if (!tracker)
+            return;
+        const activeTraces = tracker.getActiveTraces();
+        for (const { traceId } of activeTraces) {
+            tracker.recordAnalysis(traceId, thought);
         }
     }
     /**