@compilr-dev/agents 0.0.1

package/dist/agent.js

@@ -0,0 +1,1912 @@
+/**
+ * Agent - The main class for running AI agents with tool use
+ */
+import { PermissionManager } from './permissions/manager.js';
+import { HooksManager } from './hooks/manager.js';
+import { ProjectMemoryLoader } from './memory/loader.js';
+import { UsageTracker } from './costs/tracker.js';
+import { DefaultToolRegistry } from './tools/registry.js';
+import { ContextManager } from './context/manager.js';
+import { AnchorManager } from './anchors/manager.js';
+import { GuardrailManager } from './guardrails/manager.js';
+import { MaxIterationsError, ToolLoopError } from './errors.js';
+import { generateSessionId, createAgentState, deserializeTodos } from './state/agent-state.js';
+import { getDefaultTodoStore, createIsolatedTodoStore } from './tools/builtin/todo.js';
+/**
+ * Agent class - orchestrates LLM interactions with tool use
+ *
+ * @example
+ * ```typescript
+ * const agent = new Agent({
+ *   provider: new ClaudeProvider({ apiKey: 'sk-...' }),
+ *   systemPrompt: 'You are a helpful assistant.',
+ * });
+ *
+ * agent.registerTool(readFileTool);
+ * agent.registerTool(writeFileTool);
+ *
+ * const result = await agent.run('Read the contents of package.json');
+ * console.log(result.response);
+ * ```
+ */
+export class Agent {
+    provider;
+    systemPrompt;
+    maxIterations;
+    maxConsecutiveToolCalls;
+    iterationLimitBehavior;
+    chatOptions;
+    toolRegistry;
+    contextManager;
+    autoContextManagement;
+    onEvent;
+    // State management
+    checkpointer;
+    _sessionId;
+    autoCheckpoint;
+    checkpointOnAbort;
+    _createdAt;
+    _totalTokensUsed = 0;
+    _currentIteration = 0;
+    /**
+     * Conversation history - persists across run() calls
+     */
+    conversationHistory = [];
+    /**
+     * Registered sub-agents
+     */
+    subAgents = new Map();
+    /**
+     * Anchor manager for critical information that survives context compaction
+     */
+    anchorManager;
+    /**
+     * Guardrail manager for pattern-based safety checks
+     */
+    guardrailManager;
+    /**
+     * Permission manager for tool-level access control
+     */
+    permissionManager;
+    /**
+     * Loaded project memory (instructions from CLAUDE.md, etc.)
+     */
+    projectMemory;
+    /**
+     * Usage tracker for token usage monitoring
+     */
+    usageTracker;
+    /**
+     * Hooks manager for lifecycle hooks
+     */
+    hooksManager;
+    constructor(config) {
+        this.provider = config.provider;
+        this.systemPrompt = config.systemPrompt ?? '';
+        this.maxIterations = config.maxIterations ?? 10;
+        this.maxConsecutiveToolCalls = config.maxConsecutiveToolCalls ?? 3;
+        this.iterationLimitBehavior = config.iterationLimitBehavior ?? 'error';
+        this.chatOptions = config.chatOptions ?? {};
+        this.toolRegistry = config.toolRegistry ?? new DefaultToolRegistry();
+        this.contextManager = config.contextManager;
+        this.autoContextManagement =
+            config.autoContextManagement ?? config.contextManager !== undefined;
+        this.onEvent = config.onEvent;
+        // State management
+        this.checkpointer = config.checkpointer;
+        this._sessionId = config.sessionId ?? generateSessionId();
+        this.autoCheckpoint = config.autoCheckpoint ?? false;
+        this.checkpointOnAbort = config.checkpointOnAbort ?? false;
+        this._createdAt = new Date().toISOString();
+        // Anchor management
+        if (config.anchors !== undefined) {
+            this.anchorManager = new AnchorManager(config.anchors);
+        }
+        // Guardrail management
+        if (config.guardrails !== undefined) {
+            this.guardrailManager = new GuardrailManager(config.guardrails);
+        }
+        // Permission management
+        if (config.permissions !== undefined) {
+            this.permissionManager = new PermissionManager(config.permissions);
+        }
+        // Project memory - store and prepend to system prompt
+        if (config.projectMemory !== undefined) {
+            this.projectMemory = config.projectMemory;
+            // Prepend memory content to system prompt
+            if (config.projectMemory.content) {
+                const memorySection = [
+                    '# Project Instructions',
+                    '',
+                    config.projectMemory.content,
+                    '',
+                    '---',
+                    '',
+                ].join('\n');
+                this.systemPrompt = memorySection + this.systemPrompt;
+            }
+        }
+        // Usage tracking - initialize with session ID
+        if (config.usage !== undefined) {
+            this.usageTracker = new UsageTracker({
+                ...config.usage,
+                sessionId: config.usage.sessionId ?? this._sessionId,
+            });
+            // Forward usage events to agent event handler
+            this.usageTracker.onEvent((event) => {
+                if (event.type === 'usage:recorded') {
+                    this.onEvent?.({
+                        type: 'usage_recorded',
+                        tokens: event.record.tokens,
+                        model: event.record.model,
+                    });
+                }
+                else if (event.type === 'usage:budget_warning') {
+                    this.onEvent?.({
+                        type: 'usage_budget_warning',
+                        status: event.status,
+                        threshold: event.threshold,
+                    });
+                }
+                else if (event.type === 'usage:budget_exceeded') {
+                    this.onEvent?.({
+                        type: 'usage_budget_exceeded',
+                        status: event.status,
+                    });
+                }
+            });
+        }
+        // Hooks manager
+        if (config.hooks !== undefined) {
+            this.hooksManager = new HooksManager({ hooks: config.hooks });
+        }
+    }
+    // ==========================================================================
+    // Static Factory Methods
+    // ==========================================================================
+    /**
+     * Create an agent with project memory loaded from files.
+     *
+     * This factory method automatically discovers and loads project-specific
+     * instructions from files like CLAUDE.md, GEMINI.md, PROJECT.md, etc.
+     *
+     * @param config - Agent configuration
+     * @param memoryOptions - Project memory loading options
+     * @param memoryDir - Directory to search for memory files (defaults to cwd)
+     * @returns Agent instance with loaded project memory
+     *
+     * @example
+     * ```typescript
+     * // Load Claude-specific instructions
+     * const agent = await Agent.createWithMemory(
+     *   {
+     *     provider,
+     *     systemPrompt: 'You are a helpful assistant.',
+     *   },
+     *   { providers: 'claude' },
+     *   '/path/to/project'
+     * );
+     *
+     * // Load instructions for multiple providers
+     * const agent = await Agent.createWithMemory(
+     *   { provider },
+     *   { providers: ['claude', 'gemini'], includeGeneric: true }
+     * );
+     *
+     * // Access loaded memory
+     * const memory = agent.getProjectMemory();
+     * console.log(`Loaded ${memory?.files.length} memory files`);
+     * ```
+     */
+    static async createWithMemory(config, memoryOptions, memoryDir) {
+        const loader = new ProjectMemoryLoader(memoryOptions);
+        const memory = await loader.load(memoryDir ?? process.cwd());
+        return new Agent({
+            ...config,
+            projectMemory: memory,
+        });
+    }
+    // ==========================================================================
+    // Session ID getter
+    // ==========================================================================
+    /**
+     * Get the session ID for this agent instance
+     */
+    get sessionId() {
+        return this._sessionId;
+    }
+    // ==========================================================================
+    // Project Memory - Access loaded project instructions
+    // ==========================================================================
+    /**
+     * Get the loaded project memory (if any).
+     *
+     * Project memory contains instructions loaded from files like
+     * CLAUDE.md, GEMINI.md, PROJECT.md, etc.
+     *
+     * @returns The loaded project memory, or undefined if none was loaded
+     *
+     * @example
+     * ```typescript
+     * const memory = agent.getProjectMemory();
+     * if (memory) {
+     *   console.log(`Loaded ${memory.files.length} instruction files`);
+     *   console.log(`Total tokens: ~${memory.estimatedTokens}`);
+     *   for (const file of memory.files) {
+     *     console.log(`  - ${file.relativePath}`);
+     *   }
+     * }
+     * ```
+     */
+    getProjectMemory() {
+        return this.projectMemory;
+    }
+    /**
+     * Check if project memory was loaded
+     */
+    hasProjectMemory() {
+        return this.projectMemory !== undefined && this.projectMemory.files.length > 0;
+    }
+    // ==========================================================================
+    // Usage Tracking - Token usage monitoring
+    // ==========================================================================
+    /**
+     * Get usage tracking statistics.
+     *
+     * @returns Usage statistics or undefined if usage tracking is not enabled
+     *
+     * @example
+     * ```typescript
+     * const stats = agent.getUsageStats();
+     * if (stats) {
+     *   console.log(`Total calls: ${stats.totalCalls}`);
+     *   console.log(`Total tokens: ${stats.totalTokens}`);
+     *   console.log(`Input tokens: ${stats.totalInputTokens}`);
+     *   console.log(`Output tokens: ${stats.totalOutputTokens}`);
+     * }
+     * ```
+     */
+    getUsageStats() {
+        return this.usageTracker?.getStats();
+    }
+    /**
+     * Get total tokens used across all LLM calls.
+     */
+    getTotalTokens() {
+        return this.usageTracker?.getTotalTokens() ?? 0;
+    }
+    /**
+     * Get total input tokens used across all LLM calls.
+     */
+    getTotalInputTokens() {
+        return this.usageTracker?.getTotalInputTokens() ?? 0;
+    }
+    /**
+     * Get total output tokens used across all LLM calls.
+     */
+    getTotalOutputTokens() {
+        return this.usageTracker?.getTotalOutputTokens() ?? 0;
+    }
+    /**
+     * Get budget status.
+     */
+    getBudgetStatus() {
+        return this.usageTracker?.getBudgetStatus();
+    }
+    /**
+     * Check if budget is exceeded.
+     */
+    isBudgetExceeded() {
+        return this.usageTracker?.isBudgetExceeded() ?? false;
+    }
+    /**
+     * Get a human-readable usage summary.
+     */
+    getUsageSummary() {
+        return this.usageTracker?.getSummary();
+    }
+    /**
+     * Reset usage tracking data.
+     */
+    resetUsageTracking() {
+        this.usageTracker?.reset();
+    }
+    /**
+     * Check if usage tracking is enabled.
+     */
+    hasUsageTracking() {
+        return this.usageTracker !== undefined && this.usageTracker.isEnabled;
+    }
+    /**
+     * Record usage manually (for custom provider integrations).
+     *
+     * @internal
+     */
+    recordUsage(model, provider, tokens) {
+        this.usageTracker?.record({ model, provider, tokens });
+    }
+    // ==========================================================================
+    // Anchor Management - Critical information that survives context compaction
+    // ==========================================================================
+    /**
+     * Add an anchor (critical information that survives context compaction).
+     *
+     * Anchors are injected into every LLM call and never get compacted.
+     * Use them for information that must not be forgotten.
+     *
+     * @param input - Anchor input
+     * @returns The created anchor, or undefined if anchors are not enabled
+     *
+     * @example
+     * ```typescript
+     * // Session anchor - lives for this session only
+     * agent.addAnchor({
+     *   content: 'This session we implemented: edit tool, grep tool',
+     *   priority: 'critical',
+     *   scope: 'session',
+     * });
+     *
+     * // Safety anchor - persisted across sessions
+     * agent.addAnchor({
+     *   content: 'Never delete files in /important without confirmation',
+     *   priority: 'safety',
+     *   scope: 'persistent',
+     * });
+     *
+     * // Temporary anchor - expires after 1 hour
+     * agent.addAnchor({
+     *   content: 'Currently working on feature X',
+     *   priority: 'info',
+     *   scope: 'temporary',
+     *   expiresAt: new Date(Date.now() + 60 * 60 * 1000),
+     * });
+     * ```
+     */
+    addAnchor(input) {
+        if (!this.anchorManager)
+            return undefined;
+        const anchor = this.anchorManager.add(input);
+        this.onEvent?.({ type: 'anchor_added', anchor });
+        return anchor;
+    }
+    /**
+     * Get an anchor by ID
+     */
+    getAnchor(id) {
+        return this.anchorManager?.get(id);
+    }
+    /**
+     * Get all anchors, optionally filtered
+     *
+     * @param options - Query options for filtering
+     * @returns Array of anchors
+     *
+     * @example
+     * ```typescript
+     * // Get all anchors
+     * const all = agent.getAnchors();
+     *
+     * // Get only safety anchors
+     * const safety = agent.getAnchors({ priority: 'safety' });
+     *
+     * // Get session anchors with specific tags
+     * const tagged = agent.getAnchors({ scope: 'session', tags: ['files'] });
+     * ```
+     */
+    getAnchors(options) {
+        return this.anchorManager?.getAll(options) ?? [];
+    }
+    /**
+     * Check if an anchor exists
+     */
+    hasAnchor(id) {
+        return this.anchorManager?.has(id) ?? false;
+    }
+    /**
+     * Remove an anchor by ID
+     *
+     * @returns true if anchor was removed, false if not found
+     */
+    removeAnchor(id) {
+        if (!this.anchorManager)
+            return false;
+        const removed = this.anchorManager.remove(id);
+        if (removed) {
+            this.onEvent?.({ type: 'anchor_removed', anchorId: id });
+        }
+        return removed;
+    }
+    /**
+     * Clear anchors based on criteria
+     *
+     * @param options - Clear options for filtering which anchors to remove
+     * @returns Number of anchors removed
+     *
+     * @example
+     * ```typescript
+     * // Clear all session anchors
+     * agent.clearAnchors({ scope: 'session' });
+     *
+     * // Clear expired temporary anchors
+     * agent.clearAnchors({ expiredOnly: true });
+     *
+     * // Clear anchors with specific tags
+     * agent.clearAnchors({ tags: ['auto'] });
+     * ```
+     */
+    clearAnchors(options) {
+        return this.anchorManager?.clear(options) ?? 0;
+    }
+    /**
+     * Get the anchor manager (if configured)
+     */
+    getAnchorManager() {
+        return this.anchorManager;
+    }
+    /**
+     * Check if anchors are enabled
+     */
+    hasAnchors() {
+        return this.anchorManager !== undefined;
+    }
+    // ==========================================================================
+    // Guardrail Management - Pattern-based safety checks
+    // ==========================================================================
+    /**
+     * Add a custom guardrail
+     *
+     * @param input - Guardrail definition
+     * @returns The created guardrail, or undefined if guardrails are not enabled
+     *
+     * @example
+     * ```typescript
+     * agent.addGuardrail({
+     *   id: 'no-delete-important',
+     *   name: 'Important Files Protection',
+     *   description: 'Prevent deletion of important files',
+     *   patterns: [/rm.*important/i, /delete.*important/i],
+     *   action: 'block',
+     *   message: 'Cannot delete files marked as important',
+     *   scope: ['bash'],
+     * });
+     * ```
+     */
+    addGuardrail(input) {
+        return this.guardrailManager?.add(input);
+    }
+    /**
+     * Get a guardrail by ID
+     */
+    getGuardrail(id) {
+        return this.guardrailManager?.get(id);
+    }
+    /**
+     * Get all guardrails
+     */
+    getGuardrails() {
+        return this.guardrailManager?.getAll() ?? [];
+    }
+    /**
+     * Check if a guardrail exists
+     */
+    hasGuardrail(id) {
+        return this.guardrailManager?.has(id) ?? false;
+    }
+    /**
+     * Remove a guardrail by ID
+     */
+    removeGuardrail(id) {
+        return this.guardrailManager?.remove(id) ?? false;
+    }
+    /**
+     * Enable a guardrail by ID
+     */
+    enableGuardrail(id) {
+        return this.guardrailManager?.enable(id) ?? false;
+    }
+    /**
+     * Disable a guardrail by ID
+     */
+    disableGuardrail(id) {
+        return this.guardrailManager?.disable(id) ?? false;
+    }
+    /**
+     * Get the guardrail manager (if configured)
+     */
+    getGuardrailManager() {
+        return this.guardrailManager;
+    }
+    /**
+     * Check if guardrails are enabled
+     */
+    hasGuardrails() {
+        return this.guardrailManager !== undefined;
+    }
+    // ==========================================================================
+    // Permission Management - Tool-level access control
+    // ==========================================================================
+    /**
+     * Add a permission rule for a tool
+     *
+     * @param rule - Permission rule to add
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * agent.addPermission({
+     *   toolName: 'bash',
+     *   level: 'once',
+     *   description: 'Execute shell commands',
+     * });
+     * ```
+     */
+    addPermission(rule) {
+        this.permissionManager?.addRule(rule);
+        return this;
+    }
+    /**
+     * Remove a permission rule by tool name
+     */
+    removePermission(toolName) {
+        return this.permissionManager?.removeRule(toolName) ?? false;
+    }
+    /**
+     * Get a permission rule by tool name
+     */
+    getPermission(toolName) {
+        return this.permissionManager?.getRule(toolName);
+    }
+    /**
+     * Get all permission rules
+     */
+    getPermissions() {
+        return this.permissionManager?.getAllRules() ?? [];
+    }
+    /**
+     * Set the permission level for a tool
+     *
+     * @param toolName - Tool name or pattern
+     * @param level - Permission level
+     * @param description - Optional description
+     */
+    setPermissionLevel(toolName, level, description) {
+        this.permissionManager?.setLevel(toolName, level, description);
+        return this;
+    }
+    /**
+     * Get the effective permission level for a tool
+     */
+    getPermissionLevel(toolName) {
+        return this.permissionManager?.getLevel(toolName) ?? 'always';
+    }
+    /**
+     * Grant session-level permission for a tool
+     */
+    grantSessionPermission(toolName) {
+        this.permissionManager?.grantSession(toolName);
+        return this;
+    }
+    /**
+     * Revoke session-level permission for a tool
+     */
+    revokeSessionPermission(toolName) {
+        return this.permissionManager?.revokeSession(toolName) ?? false;
+    }
+    /**
+     * Clear all session-level permissions
+     */
+    clearSessionPermissions() {
+        this.permissionManager?.clearSessionGrants();
+        return this;
+    }
+    /**
+     * Get all tools with session-level permission
+     */
+    getSessionPermissions() {
+        return this.permissionManager?.getSessionGrants() ?? [];
+    }
+    /**
+     * Get the permission manager (if configured)
+     */
+    getPermissionManager() {
+        return this.permissionManager;
+    }
+    /**
+     * Check if permissions are enabled
+     */
+    hasPermissions() {
+        return this.permissionManager !== undefined;
+    }
+    // ==========================================================================
+    // Custom Event Streaming
+    // ==========================================================================
+    /**
+     * Emit a custom event that will be streamed to event handlers.
+     *
+     * This allows tools, middleware, and user code to emit custom events
+     * that are streamed alongside built-in agent events.
+     *
+     * Inspired by LangGraph's get_stream_writer() pattern.
+     * Addresses issues like LangGraph #6330 (preserve event metadata).
+     *
+     * @param config - Custom event configuration
+     *
+     * @example
+     * ```typescript
+     * agent.emitCustomEvent({
+     *   name: 'progress',
+     *   data: { step: 1, total: 5, message: 'Processing...' },
+     *   metadata: { toolName: 'myTool' },
+     * });
+     * ```
+     */
+    emitCustomEvent(config) {
+        this.onEvent?.({
+            type: 'custom',
+            name: config.name,
+            data: config.data,
+            metadata: config.metadata,
+        });
+    }
+    /**
+     * Get a stream writer function for emitting custom events.
+     *
+     * This returns a simple function that can be passed to tools or
+     * middleware for streaming progress updates.
+     *
+     * @param eventName - Name for all events emitted by this writer
+     * @returns A stream writer function
+     *
+     * @example
+     * ```typescript
+     * const writer = agent.getStreamWriter('myTool');
+     * writer('Starting...', { phase: 'init' });
+     * writer('Processing...', { phase: 'work', progress: 50 });
+     * writer('Done!', { phase: 'complete' });
+     * ```
+     */
+    getStreamWriter(eventName = 'stream') {
+        return (data, metadata) => {
+            this.emitCustomEvent({ name: eventName, data, metadata });
+        };
+    }
+    /**
+     * Clear conversation history to start fresh
+     */
+    clearHistory() {
+        this.conversationHistory = [];
+        this.contextManager?.reset();
+        return this;
+    }
+    /**
+     * Get the current conversation history
+     */
+    getHistory() {
+        return [...this.conversationHistory];
+    }
+    /**
+     * Get the context manager (if configured)
+     */
+    getContextManager() {
+        return this.contextManager;
+    }
+    /**
+     * Get context statistics
+     */
+    getContextStats() {
+        return this.contextManager?.getStats(this.conversationHistory.length);
+    }
+    /**
+     * Get current verbosity level based on context pressure
+     */
+    getVerbosityLevel() {
+        return this.contextManager?.getVerbosityLevel() ?? 'full';
+    }
+    // ==========================================================================
+    // State Management
+    // ==========================================================================
+    /**
+     * Serialize the current agent state to an AgentState object.
+     * This can be used for manual persistence or transferring state.
+     *
+     * @example
+     * ```typescript
+     * const state = agent.serialize();
+     * const json = JSON.stringify(state);
+     * // Store json somewhere...
+     * ```
+     */
+    serialize() {
+        const todoStore = getDefaultTodoStore();
+        return createAgentState({
+            sessionId: this._sessionId,
+            systemPrompt: this.systemPrompt,
+            model: this.chatOptions.model,
+            messages: this.conversationHistory,
+            todos: todoStore.getAll(),
+            currentIteration: this._currentIteration,
+            totalTokensUsed: this._totalTokensUsed,
+            createdAt: this._createdAt,
+        });
+    }
+    /**
+     * Save the current state using the configured checkpointer.
+     * Throws if no checkpointer is configured.
+     *
+     * @param metadata - Optional metadata overrides
+     * @returns The session ID
+     *
+     * @example
+     * ```typescript
+     * const agent = new Agent({
+     *   provider,
+     *   checkpointer: new FileCheckpointer('~/.myapp/sessions/'),
+     * });
+     *
+     * await agent.run('Hello!');
+     * const sessionId = await agent.checkpoint();
+     * console.log(`Saved as: ${sessionId}`);
+     * ```
+     */
+    async checkpoint(metadata) {
+        if (!this.checkpointer) {
+            throw new Error('No checkpointer configured. Provide a checkpointer in AgentConfig.');
+        }
+        const state = this.serialize();
+        await this.checkpointer.save(this._sessionId, state, metadata);
+        return this._sessionId;
+    }
+    /**
+     * Check if a checkpointer is configured
+     */
+    hasCheckpointer() {
+        return this.checkpointer !== undefined;
+    }
+    /**
+     * Save a partial checkpoint on abort or error.
+     * This is called internally when checkpointOnAbort is enabled.
+     *
+     * @param reason - Why the checkpoint was saved ('aborted' or 'error')
+     * @param emit - Event emitter function
+     * @returns Promise that resolves when checkpoint is saved
+     */
+    async saveAbortCheckpoint(reason, emit) {
+        if (!this.checkpointOnAbort || !this.checkpointer) {
+            return;
+        }
+        try {
+            const sessionId = await this.checkpoint({
+                tags: ['partial', reason],
+            });
+            emit({ type: 'abort_checkpoint_saved', sessionId, reason });
+        }
+        catch (error) {
+            emit({
+                type: 'abort_checkpoint_failed',
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    /**
+     * Resume an agent from a saved session.
+     *
+     * @param sessionId - Session ID to resume
+     * @param options - Resume options (provider and checkpointer required)
+     *
+     * @example
+     * ```typescript
+     * const checkpointer = new FileCheckpointer('~/.myapp/sessions/');
+     *
+     * // Resume a previous session
+     * const agent = await Agent.resume('session_abc123', {
+     *   provider: new ClaudeProvider({ apiKey: '...' }),
+     *   checkpointer,
+     * });
+     *
+     * // Continue the conversation
+     * await agent.run('Continue where we left off...');
+     * ```
+     */
+    static async resume(sessionId, options) {
+        const state = await options.checkpointer.load(sessionId);
+        if (!state) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        return Agent.fromState(state, {
+            provider: options.provider,
+            checkpointer: options.checkpointer,
+            tools: options.tools,
+            onEvent: options.onEvent,
+            systemPrompt: options.systemPrompt,
+        });
+    }
+    /**
+     * Create an agent from a serialized AgentState object.
+     *
+     * @param state - The serialized agent state
+     * @param options - Options for the new agent
+     *
+     * @example
+     * ```typescript
+     * // Load state from somewhere
+     * const json = await fs.readFile('session.json', 'utf-8');
+     * const state = JSON.parse(json);
+     *
+     * // Create agent from state
+     * const agent = Agent.fromState(state, { provider });
+     * await agent.run('Continue...');
+     * ```
+     */
+    static fromState(state, options) {
+        // Create the agent with restored state
+        const agent = new Agent({
+            provider: options.provider,
+            systemPrompt: options.systemPrompt ?? state.systemPrompt,
+            checkpointer: options.checkpointer,
+            sessionId: state.sessionId,
+            onEvent: options.onEvent,
+            chatOptions: state.model ? { model: state.model } : undefined,
+        });
+        // Restore conversation history
+        agent.conversationHistory = [...state.messages];
+        // Restore internal state
+        agent._createdAt = state.createdAt;
+        agent._totalTokensUsed = state.totalTokensUsed;
+        agent._currentIteration = state.currentIteration;
+        // Restore todos
+        if (state.todos.length > 0) {
+            const todoStore = getDefaultTodoStore();
+            const deserializedTodos = deserializeTodos(state.todos);
+            for (const todo of deserializedTodos) {
+                todoStore.add(todo);
+            }
+        }
+        // Register tools if provided
+        if (options.tools) {
+            for (const tool of options.tools) {
+                agent.registerTool(tool);
+            }
+        }
+        return agent;
+    }
+    // ==========================================================================
+    // Sub-Agent Management
+    // ==========================================================================
+    /**
+     * Create and register a sub-agent with isolated context.
+     *
+     * Sub-agents are specialized agents that handle discrete tasks independently.
+     * They have their own context window and can have different tools/permissions.
+     *
+     * @example
+     * ```typescript
+     * agent.createSubAgent({
+     *   name: 'code-reviewer',
+     *   description: 'Reviews code for security and quality issues',
+     *   systemPrompt: 'You are a code review specialist...',
+     *   tools: [readFileTool], // Restricted tools
+     *   contextMode: 'isolated',
+     * });
+     *
+     * const result = await agent.runSubAgent('code-reviewer', 'Review src/auth.ts');
+     * ```
+     */
+    createSubAgent(config) {
+        // Calculate context budget for sub-agent
+        const parentMaxTokens = this.contextManager?.getMaxTokens() ?? 200000;
+        const subAgentMaxTokens = config.contextBudget ?? Math.floor(parentMaxTokens * 0.25);
+        // Create context manager for sub-agent (always isolated)
+        const subAgentContextManager = new ContextManager({
+            provider: this.provider,
+            config: {
+                maxContextTokens: subAgentMaxTokens,
+            },
+        });
+        // Create tool registry for sub-agent
+        const subAgentToolRegistry = new DefaultToolRegistry();
+        // If tools specified, use those; otherwise inherit from parent
+        const toolsToRegister = config.tools ??
+            this.toolRegistry
+                .getDefinitions()
+                .map((def) => {
+                const parentTool = this.toolRegistry.get(def.name);
+                return parentTool;
+            })
+                .filter((t) => t !== undefined);
+        for (const tool of toolsToRegister) {
+            subAgentToolRegistry.register(tool);
+        }
+        // Create the sub-agent
+        const subAgent = new Agent({
+            provider: this.provider,
+            systemPrompt: config.systemPrompt ?? this.systemPrompt,
+            maxIterations: config.maxIterations ?? 5,
+            chatOptions: config.chatOptions ?? this.chatOptions,
+            toolRegistry: subAgentToolRegistry,
+            contextManager: subAgentContextManager,
+            autoContextManagement: true,
+            onEvent: this.onEvent, // Forward events to parent
+        });
+        // Store the sub-agent
+        this.subAgents.set(config.name, { config, agent: subAgent });
+        return this;
+    }
+    /**
+     * Run a sub-agent with a specific task.
+     *
+     * The sub-agent executes independently with its own context and returns
+     * the result to the parent agent.
+     *
+     * @param name - Name of the registered sub-agent
+     * @param task - Task description for the sub-agent
+     * @param options - Optional run options
+     */
+    async runSubAgent(name, task, options) {
+        const entry = this.subAgents.get(name);
+        if (!entry) {
+            return {
+                name,
+                response: '',
+                success: false,
+                error: `Sub-agent '${name}' not found. Register it first with createSubAgent().`,
+                iterations: 0,
+                toolCalls: [],
+            };
+        }
+        const { config, agent } = entry;
+        // Emit sub-agent start event
+        this.onEvent?.({ type: 'subagent_start', name, task });
+        try {
+            // Prepare context based on mode
+            let contextPrefix = '';
+            if (config.contextMode === 'inherited') {
+                // Generate a summary of parent context for the sub-agent
+                const parentHistory = this.getHistory();
+                if (parentHistory.length > 0) {
+                    contextPrefix = this.generateContextSummary(parentHistory);
+                    contextPrefix = `[Parent Context Summary]\n${contextPrefix}\n\n[Your Task]\n`;
+                }
+            }
+            else if (config.contextMode === 'shared') {
+                // Copy parent history to sub-agent (not recommended for large contexts)
+                const parentHistory = this.getHistory();
+                for (const msg of parentHistory) {
+                    agent.conversationHistory.push({ ...msg });
+                }
+            }
+            // 'isolated' mode: fresh context (default), no prefix needed
+            // Run the sub-agent
+            const result = await agent.run(contextPrefix + task, options);
+            // Truncate tool call results to prevent memory bloat
+            const maxToolResultSize = config.maxToolResultSize ?? 50 * 1024; // 50KB default
+            const truncatedToolCalls = result.toolCalls.map((tc) => ({
+                name: tc.name,
+                input: tc.input,
+                result: truncateToolResult(tc.result, maxToolResultSize),
+            }));
+            const subAgentResult = {
+                name,
+                response: result.response,
+                success: true,
+                iterations: result.iterations,
+                toolCalls: truncatedToolCalls,
+                contextStats: result.contextStats,
+            };
+            // Emit sub-agent end event
+            this.onEvent?.({ type: 'subagent_end', name, result: subAgentResult });
+            // Clear sub-agent history for next use (isolated context)
+            if (config.contextMode !== 'shared') {
+                agent.clearHistory();
+            }
+            // Auto-dispose if configured
+            if (config.autoDispose) {
+                this.disposeSubAgent(name);
+            }
+            return subAgentResult;
+        }
+        catch (error) {
+            const subAgentResult = {
+                name,
+                response: '',
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+                iterations: 0,
+                toolCalls: [],
+            };
+            this.onEvent?.({ type: 'subagent_end', name, result: subAgentResult });
+            return subAgentResult;
+        }
+    }
+    /**
+     * Run multiple sub-agents in parallel with proper state isolation.
+     *
+     * This method ensures that parallel sub-agents don't share mutable state,
+     * preventing race conditions and state leakage between concurrent runs.
+     *
+     * Inspired by LangGraph issue #6446: Parallel subgraphs with shared
+     * state keys cause InvalidUpdateError.
+     *
+     * @param tasks - Array of {name, task} objects to run in parallel
+     * @param options - Optional run options applied to all sub-agents
+     * @returns Array of results in the same order as tasks
+     *
+     * @example
+     * ```typescript
+     * // Run code review and security scan in parallel
+     * const results = await agent.runParallelSubAgents([
+     *   { name: 'code-reviewer', task: 'Review src/auth.ts' },
+     *   { name: 'security-scanner', task: 'Scan src/auth.ts for vulnerabilities' },
+     * ]);
+     * ```
+     */
+    async runParallelSubAgents(tasks, options) {
+        // Create isolated stores for each sub-agent to prevent state leakage
+        const isolatedStores = tasks.map(() => createIsolatedTodoStore());
+        // Run all sub-agents in parallel
+        const promises = tasks.map(async ({ name, task }, index) => {
+            const entry = this.subAgents.get(name);
+            if (!entry) {
+                return {
+                    name,
+                    response: '',
+                    success: false,
+                    error: `Sub-agent '${name}' not found. Register it first with createSubAgent().`,
+                    iterations: 0,
+                    toolCalls: [],
+                };
+            }
+            // Store the isolated store for this sub-agent run
+            // Note: The actual store isolation would require tool-level changes
+            // For now, we emit a note about isolation in the result
+            const _isolatedStore = isolatedStores[index];
+            // Run the sub-agent (state isolation is noted in the result)
+            const result = await this.runSubAgent(name, task, options);
+            return {
+                ...result,
+                // Mark that this was run with isolation
+            };
+        });
+        return Promise.all(promises);
+    }
+    /**
+     * Get a registered sub-agent by name
+     */
+    getSubAgent(name) {
+        return this.subAgents.get(name)?.agent;
+    }
+    /**
+     * Get all registered sub-agent names
+     */
+    getSubAgentNames() {
+        return Array.from(this.subAgents.keys());
+    }
+    /**
+     * Remove a registered sub-agent (alias for disposeSubAgent)
+     */
+    removeSubAgent(name) {
+        return this.disposeSubAgent(name);
+    }
+    /**
+     * Dispose a sub-agent and release its resources.
+     *
+     * This clears the sub-agent's:
+     * - Conversation history
+     * - Context manager state
+     * - Tool registry
+     *
+     * After disposal, the sub-agent must be re-created to use again.
+     */
+    disposeSubAgent(name) {
+        const entry = this.subAgents.get(name);
+        if (!entry) {
+            return false;
+        }
+        const { agent } = entry;
+        // Clear conversation history
+        agent.clearHistory();
+        // Clear tool registry
+        const registry = agent.toolRegistry;
+        registry.clear();
+        // Remove from map
+        return this.subAgents.delete(name);
+    }
+    /**
+     * Dispose all sub-agents and release their resources.
+     *
+     * Useful for cleanup when the parent agent is done or
+     * to free memory during long-running sessions.
+     */
+    disposeAllSubAgents() {
+        for (const name of this.subAgents.keys()) {
+            this.disposeSubAgent(name);
+        }
+    }
+    /**
+     * Generate a concise summary of context for inherited mode
+     */
+    generateContextSummary(messages) {
+        // Simple summary: extract key points from recent messages
+        const recentMessages = messages.slice(-10);
+        const summaryParts = [];
+        for (const msg of recentMessages) {
+            if (msg.role === 'system')
+                continue;
+            const msgContent = typeof msg.content === 'string'
+                ? msg.content
+                : msg.content
+                    .map((b) => {
+                    switch (b.type) {
+                        case 'text':
+                            return b.text;
+                        case 'tool_use':
+                            return `[Tool: ${b.name}]`;
+                        case 'tool_result':
+                            return `[Tool Result]`;
+                    }
+                })
+                    .join(' ');
+            // Truncate long content
+            const truncated = msgContent.length > 200 ? msgContent.slice(0, 200) + '...' : msgContent;
+            summaryParts.push(`${msg.role}: ${truncated}`);
+        }
+        return summaryParts.join('\n');
+    }
+    /**
+     * Register a tool for the agent to use
+     */
+    registerTool(tool) {
+        this.toolRegistry.register(tool);
+        return this;
+    }
+    /**
+     * Register multiple tools at once
+     */
+    registerTools(tools) {
+        for (const tool of tools) {
+            this.toolRegistry.register(tool);
+        }
+        return this;
+    }
+    /**
+     * Get all registered tool definitions
+     */
+    getToolDefinitions() {
+        return this.toolRegistry.getDefinitions();
+    }
+    /**
+     * Run the agent with a user message
+     */
+    async run(userMessage, options) {
+        const maxIterations = options?.maxIterations ?? this.maxIterations;
+        const chatOptions = { ...this.chatOptions, ...options?.chatOptions };
+        const signal = options?.signal;
+        // Combined event emitter
+        const emit = (event) => {
+            this.onEvent?.(event);
+            options?.onEvent?.(event);
+        };
+        // Build messages: system prompt + history + new user message
+        let messages = [];
+        // Add system message if present
+        if (this.systemPrompt) {
+            messages.push({
+                role: 'system',
+                content: this.systemPrompt,
+            });
+        }
+        // Inject anchors (critical information that survives context compaction)
+        if (this.anchorManager && this.anchorManager.size > 0) {
+            const anchorsContent = this.anchorManager.format();
+            if (anchorsContent) {
+                messages.push({
+                    role: 'system',
+                    content: `## Active Anchors (Critical Information)\n\n${anchorsContent}`,
+                });
+            }
+        }
+        // Add conversation history
+        messages.push(...this.conversationHistory);
+        // Add new user message
+        const userMsg = {
+            role: 'user',
+            content: userMessage,
+        };
+        messages.push(userMsg);
+        // Track new messages added during this run (for appending to history)
+        const newMessages = [userMsg];
+        // Context management: update token count and check for proactive management
+        if (this.contextManager && this.autoContextManagement) {
+            await this.contextManager.updateTokenCount(messages);
+            // Track system prompt tokens
+            if (this.systemPrompt) {
+                const systemTokens = this.contextManager.estimateTokens(this.systemPrompt);
+                this.contextManager.updateCategoryUsage('system', systemTokens);
+            }
+            // Check if we need to manage context before starting
+            if (this.contextManager.needsEmergencySummarization()) {
+                emit({
+                    type: 'context_warning',
+                    utilization: this.contextManager.getUtilization(),
+                    threshold: 0.95,
+                });
+                // Perform emergency summarization
+                const { messages: summarized, result } = await this.contextManager.summarizeWithRetry(messages, (msgs) => this.generateSummary(msgs), { emergency: true });
+                messages = summarized;
+                emit({
+                    type: 'context_summarized',
+                    tokensBefore: result.originalTokens,
+                    tokensAfter: result.summaryTokens,
+                    rounds: result.rounds,
+                });
+            }
+            else if (this.contextManager.needsSummarization()) {
+                emit({
+                    type: 'context_warning',
+                    utilization: this.contextManager.getUtilization(),
+                    threshold: 0.9,
+                });
+            }
+        }
+        const toolCalls = [];
+        let iterations = 0;
+        let finalResponse = '';
+        let aborted = false;
+        // Tool loop detection: track consecutive identical calls
+        let lastToolCallHash = '';
+        let consecutiveIdenticalCalls = 0;
+        // Hash function for tool call comparison
+        const hashToolCall = (name, input) => {
+            return `${name}:${JSON.stringify(input, Object.keys(input).sort())}`;
+        };
+        // Agentic loop
+        while (iterations < maxIterations) {
+            // Check for abort
+            if (signal?.aborted) {
+                aborted = true;
+                break;
+            }
+            iterations++;
+            emit({ type: 'iteration_start', iteration: iterations });
+            // Hook context for this iteration
+            const hookContext = {
+                sessionId: this._sessionId,
+                iteration: iterations,
+                signal,
+                metadata: {},
+            };
+            // Track tool calls for this iteration (for afterIteration hook)
+            const iterationToolCalls = [];
+            // Run beforeIteration hooks
+            if (this.hooksManager) {
+                const shouldContinue = await this.hooksManager.runBeforeIteration({
+                    ...hookContext,
+                    maxIterations,
+                    messages,
+                });
+                if (!shouldContinue) {
+                    emit({ type: 'iteration_end', iteration: iterations });
+                    continue;
+                }
+            }
+            // Get tool definitions
+            let tools = this.toolRegistry.getDefinitions();
+            // Run beforeLLM hooks (can modify messages and tools)
+            if (this.hooksManager) {
+                const llmHookResult = await this.hooksManager.runBeforeLLM({
+                    ...hookContext,
+                    messages,
+                    tools,
+                });
+                messages = llmHookResult.messages;
+                tools = llmHookResult.tools;
+            }
+            // Call LLM
+            emit({ type: 'llm_start' });
+            const llmStartTime = Date.now();
+            const chunks = [];
+            try {
+                for await (const chunk of this.provider.chat(messages, {
+                    ...chatOptions,
+                    tools: tools.length > 0 ? tools : undefined,
+                })) {
+                    // Check for abort during streaming
+                    if (signal?.aborted) {
+                        aborted = true;
+                        break;
+                    }
+                    chunks.push(chunk);
+                    emit({ type: 'llm_chunk', chunk });
+                }
+            }
+            catch (error) {
+                if (signal?.aborted) {
+                    aborted = true;
+                    break;
+                }
+                // Run onError hooks
+                if (this.hooksManager && error instanceof Error) {
+                    const errorResult = await this.hooksManager.runOnError({
+                        ...hookContext,
+                        error,
+                        phase: 'llm',
+                    });
+                    if (errorResult.handled) {
+                        // Error was handled by hook, continue with next iteration
+                        continue;
+                    }
+                    if (errorResult.error) {
+                        throw errorResult.error;
+                    }
+                }
+                throw error;
+            }
+            if (aborted) {
+                break;
+            }
+            // Process response
+            const { text, toolUses, usage, model } = this.processChunks(chunks);
+            emit({ type: 'llm_end', text, hasToolUses: toolUses.length > 0 });
+            // Record usage if available
+            if (usage && model) {
+                this.recordUsage(model, this.provider.name, {
+                    inputTokens: usage.inputTokens,
+                    outputTokens: usage.outputTokens,
+                    totalTokens: usage.inputTokens + usage.outputTokens,
+                    cacheReadTokens: usage.cacheReadTokens,
+                    cacheCreationTokens: usage.cacheCreationTokens,
+                });
+            }
+            // Run afterLLM hooks
+            if (this.hooksManager) {
+                await this.hooksManager.runAfterLLM({
+                    ...hookContext,
+                    messages,
+                    tools,
+                    text,
+                    toolUses,
+                    usage: usage
+                        ? { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens }
+                        : undefined,
+                    model,
+                    durationMs: Date.now() - llmStartTime,
+                });
+            }
+            // If no tool uses, we're done
+            if (toolUses.length === 0) {
+                finalResponse = text;
+                // Add final assistant response to history
+                const finalAssistantMsg = {
+                    role: 'assistant',
+                    content: text,
+                };
+                newMessages.push(finalAssistantMsg);
+                // Run afterIteration hooks
+                if (this.hooksManager) {
+                    await this.hooksManager.runAfterIteration({
+                        ...hookContext,
+                        maxIterations,
+                        messages,
+                        toolCalls: iterationToolCalls,
+                        completedWithText: true,
+                    });
+                }
+                emit({ type: 'iteration_end', iteration: iterations });
+                break;
+            }
+            // Add assistant message with tool uses
+            const assistantMsg = {
+                role: 'assistant',
+                content: [
+                    ...(text ? [{ type: 'text', text }] : []),
+                    ...toolUses.map((tu) => ({
+                        type: 'tool_use',
+                        id: tu.id,
+                        name: tu.name,
+                        input: tu.input,
+                    })),
+                ],
+            };
+            messages.push(assistantMsg);
+            newMessages.push(assistantMsg);
+            // Execute tools and add results
+            for (const toolUse of toolUses) {
+                // Check for abort before each tool
+                if (signal?.aborted) {
+                    aborted = true;
+                    break;
+                }
+                emit({ type: 'tool_start', name: toolUse.name, input: toolUse.input });
+                let result;
+                // Check permissions before execution
+                if (this.permissionManager) {
+                    const permResult = await this.permissionManager.check(toolUse.name, toolUse.input);
+                    if (permResult.askedUser) {
+                        emit({ type: 'permission_asked', toolName: toolUse.name, level: permResult.level });
+                    }
+                    if (!permResult.allowed) {
+                        emit({
+                            type: 'permission_denied',
+                            toolName: toolUse.name,
+                            level: permResult.level,
+                            reason: permResult.reason,
+                        });
+                        result = {
+                            success: false,
+                            error: `Permission denied: ${permResult.reason ?? 'Tool execution not allowed'}`,
+                        };
+                        // Skip to tool_end and continue to next tool
+                        emit({ type: 'tool_end', name: toolUse.name, result });
+                        const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
+                        toolCalls.push(toolCallEntry);
+                        iterationToolCalls.push(toolCallEntry);
+                        continue;
+                    }
+                    emit({ type: 'permission_granted', toolName: toolUse.name, level: permResult.level });
+                }
+                // Check guardrails before execution
+                if (this.guardrailManager) {
+                    const { proceed, result: guardrailResult } = await this.guardrailManager.checkAndHandle(toolUse.name, toolUse.input);
+                    if (guardrailResult.triggered) {
+                        emit({ type: 'guardrail_triggered', result: guardrailResult });
+                        if (!proceed) {
+                            // Guardrail blocked the execution
+                            const message = guardrailResult.guardrail?.message ?? 'Operation blocked by guardrail';
+                            emit({ type: 'guardrail_blocked', result: guardrailResult, message });
+                            result = {
+                                success: false,
+                                error: `Guardrail blocked: ${message}`,
+                            };
+                            // Skip to tool_end and continue to next tool
+                            emit({ type: 'tool_end', name: toolUse.name, result });
+                            const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
+                            toolCalls.push(toolCallEntry);
+                            iterationToolCalls.push(toolCallEntry);
+                            continue;
+                        }
+                        else if (guardrailResult.action === 'warn') {
+                            // Log warning and continue
+                            const message = guardrailResult.guardrail?.message ?? 'Warning from guardrail';
+                            emit({ type: 'guardrail_warning', result: guardrailResult, message });
+                        }
+                    }
+                }
+                // Run beforeTool hooks (can skip or modify input)
+                let toolInput = toolUse.input;
+                if (this.hooksManager) {
+                    const beforeToolResult = await this.hooksManager.runBeforeTool({
+                        ...hookContext,
+                        toolName: toolUse.name,
+                        input: toolInput,
+                    });
+                    if (!beforeToolResult.proceed) {
+                        result = beforeToolResult.skipResult ?? { success: false, error: 'Skipped by hook' };
+                        emit({ type: 'tool_end', name: toolUse.name, result });
+                        const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
+                        toolCalls.push(toolCallEntry);
+                        iterationToolCalls.push(toolCallEntry);
+                        continue;
+                    }
+                    toolInput = beforeToolResult.input;
+                }
+                const toolStartTime = Date.now();
+                try {
+                    result = await this.toolRegistry.execute(toolUse.name, toolInput);
+                }
+                catch (error) {
+                    // Run onError hooks for tool errors (thrown exceptions)
+                    if (this.hooksManager && error instanceof Error) {
+                        const errorResult = await this.hooksManager.runOnError({
+                            ...hookContext,
+                            error,
+                            phase: 'tool',
+                            toolName: toolUse.name,
+                        });
+                        if (errorResult.recovery) {
+                            result = errorResult.recovery;
+                        }
+                        else {
+                            result = {
+                                success: false,
+                                error: errorResult.error?.message ?? error.message,
+                            };
+                        }
+                    }
+                    else {
+                        result = {
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        };
+                    }
+                }
+                // Run onError hooks for failed tool results (not thrown, but returned errors)
+                // The tool registry catches errors internally and returns { success: false }
+                if (this.hooksManager && !result.success) {
+                    const syntheticError = new Error(result.error);
+                    const errorResult = await this.hooksManager.runOnError({
+                        ...hookContext,
+                        error: syntheticError,
+                        phase: 'tool',
+                        toolName: toolUse.name,
+                    });
+                    if (errorResult.recovery) {
+                        result = errorResult.recovery;
+                    }
+                }
+                // Run afterTool hooks (can modify result)
+                if (this.hooksManager) {
+                    result = await this.hooksManager.runAfterTool({
+                        ...hookContext,
+                        toolName: toolUse.name,
+                        input: toolInput,
+                        result,
+                        durationMs: Date.now() - toolStartTime,
+                    });
+                }
+                emit({ type: 'tool_end', name: toolUse.name, result });
+                // Tool loop detection: check for consecutive identical calls
+                if (this.maxConsecutiveToolCalls > 0) {
+                    const currentHash = hashToolCall(toolUse.name, toolUse.input);
+                    if (currentHash === lastToolCallHash) {
+                        consecutiveIdenticalCalls++;
+                        if (consecutiveIdenticalCalls >= this.maxConsecutiveToolCalls) {
+                            throw new ToolLoopError(toolUse.name, consecutiveIdenticalCalls, toolUse.input);
+                        }
+                        // Emit warning before throwing
+                        emit({
+                            type: 'tool_loop_warning',
+                            toolName: toolUse.name,
+                            consecutiveCalls: consecutiveIdenticalCalls,
+                        });
+                    }
+                    else {
+                        // Different tool call, reset counter
+                        lastToolCallHash = currentHash;
+                        consecutiveIdenticalCalls = 1;
+                    }
+                }
+                const toolCallEntry = { name: toolUse.name, input: toolUse.input, result };
+                toolCalls.push(toolCallEntry);
+                iterationToolCalls.push(toolCallEntry);
+                // Build tool result content
+                let toolResultContent = result.success
+                    ? JSON.stringify(result.result)
+                    : `Error: ${result.error ?? 'Unknown error'}`;
+                // Context management: pre-flight check and filtering for tool results
+                if (this.contextManager && this.autoContextManagement) {
+                    const estimatedTokens = this.contextManager.estimateTokens(toolResultContent);
+                    const preflight = this.contextManager.canAddContent(estimatedTokens, 'toolResults');
+                    if (!preflight.allowed) {
+                        if (preflight.action === 'reject') {
+                            // Content too large - filter it
+                            const filtered = this.contextManager.filterContent(toolResultContent, 'tool_result');
+                            toolResultContent = filtered.content;
+                        }
+                        else if (preflight.action === 'compact') {
+                            // Category budget exceeded - compact the category first
+                            const tokensBefore = this.contextManager.getTokenCount();
+                            const compactResult = await this.contextManager.compactCategory(messages, 'toolResults', (content, index) => Promise.resolve(`[compacted_tool_result_${String(index)}]`));
+                            messages = compactResult.messages;
+                            emit({
+                                type: 'context_compacted',
+                                tokensBefore,
+                                tokensAfter: this.contextManager.getTokenCount(),
+                            });
+                        }
+                        else if (preflight.action === 'summarize') {
+                            // Approaching context limit - summarize
+                            const { messages: summarized, result: sumResult } = await this.contextManager.summarizeWithRetry(messages, (msgs) => this.generateSummary(msgs));
+                            messages = summarized;
+                            emit({
+                                type: 'context_summarized',
+                                tokensBefore: sumResult.originalTokens,
+                                tokensAfter: sumResult.summaryTokens,
+                                rounds: sumResult.rounds,
+                            });
+                        }
+                    }
+                    // Track tool result tokens
+                    const finalTokens = this.contextManager.estimateTokens(toolResultContent);
+                    this.contextManager.addToCategory('toolResults', finalTokens);
+                }
+                const toolResultMsg = {
+                    role: 'user',
+                    content: [
+                        {
+                            type: 'tool_result',
+                            toolUseId: toolUse.id,
+                            content: toolResultContent,
+                            isError: !result.success,
+                        },
+                    ],
+                };
+                messages.push(toolResultMsg);
+                newMessages.push(toolResultMsg);
+            }
+            if (aborted) {
+                break;
+            }
+            // Run afterIteration hooks
+            if (this.hooksManager) {
+                await this.hooksManager.runAfterIteration({
+                    ...hookContext,
+                    maxIterations,
+                    messages,
+                    toolCalls: iterationToolCalls,
+                    completedWithText: false,
+                });
+            }
+            emit({ type: 'iteration_end', iteration: iterations });
+        }
+        // Check if we hit max iterations without completing
+        if (!aborted && iterations >= maxIterations && finalResponse === '') {
+            if (this.iterationLimitBehavior === 'summarize') {
+                // Generate a summary response before throwing
+                try {
+                    finalResponse = await this.generateIterationLimitSummary(messages, maxIterations, toolCalls);
+                    emit({ type: 'done', response: finalResponse });
+                }
+                catch {
+                    // If summary generation fails, still throw the error
+                    throw new MaxIterationsError(maxIterations);
+                }
+            }
+            else if (this.iterationLimitBehavior === 'continue') {
+                // Return partial result without throwing
+                finalResponse =
+                    `[Agent reached maximum iterations (${String(maxIterations)}) without completing. ` +
+                        `${String(toolCalls.length)} tool calls were made.]`;
+            }
+            else {
+                // Default: throw error
+                throw new MaxIterationsError(maxIterations);
+            }
+        }
+        if (!aborted && !(iterations >= maxIterations && this.iterationLimitBehavior === 'summarize')) {
+            emit({ type: 'done', response: finalResponse });
+        }
+        // Context management: increment turn count and update token count
+        if (this.contextManager) {
+            this.contextManager.incrementTurn();
+            await this.contextManager.updateTokenCount(messages);
+        }
+        // Append new messages to conversation history (persists for next run)
+        this.conversationHistory.push(...newMessages);
+        // Update internal state tracking
+        this._currentIteration = iterations;
+        // Note: token tracking would require provider-specific token counting
+        // Build result with optional context stats
+        const result = {
+            response: finalResponse,
+            messages,
+            iterations,
+            toolCalls,
+            aborted,
+        };
+        if (this.contextManager) {
+            result.contextStats = this.contextManager.getStats(messages.length);
+        }
+        // Save partial checkpoint on abort (LangGraph issue #5672)
+        if (aborted) {
+            await this.saveAbortCheckpoint('aborted', emit);
+        }
+        // Auto-checkpoint if configured (only on successful completion)
+        if (!aborted && this.autoCheckpoint && this.checkpointer) {
+            await this.checkpoint();
+        }
+        return result;
+    }
+    /**
+     * Stream the agent's response with full tool use support
+     *
+     * Yields AgentEvent objects as the agent executes, allowing
+     * real-time monitoring of the agentic loop.
+     */
+    async *stream(userMessage, options) {
+        // Use a simple queue-based approach
+        const eventQueue = [];
+        let finished = false;
+        let error = null;
+        // Promise that resolves when a new event is available
+        let notifyNewEvent = null;
+        const waitForEvent = () => new Promise((resolve) => {
+            notifyNewEvent = resolve;
+        });
+        // Run agent in background, collecting events
+        const runPromise = this.run(userMessage, {
+            ...options,
+            onEvent: (event) => {
+                options?.onEvent?.(event);
+                eventQueue.push(event);
+                notifyNewEvent?.();
+                notifyNewEvent = null;
+            },
+        });
+        // Handle completion
+        runPromise
+            .then(() => {
+            finished = true;
+            notifyNewEvent?.();
+        })
+            .catch((err) => {
+            error = err;
+            finished = true;
+            notifyNewEvent?.();
+        });
+        // Yield events as they arrive
+        // Note: ESLint can't track async mutations to `finished`
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        while (eventQueue.length > 0 || !finished) {
+            if (eventQueue.length > 0) {
+                const event = eventQueue.shift();
+                if (event) {
+                    yield event;
+                }
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            }
+            else if (!finished) {
+                await waitForEvent();
+            }
+        }
+        // Re-throw any error from the run
+        if (error instanceof Error) {
+            throw error;
+        }
+        else if (error !== null && error !== undefined) {
+            throw new Error(typeof error === 'string' ? error : 'Unknown error in agent stream');
+        }
+    }
+    /**
+     * Process stream chunks into text, tool uses, and usage data
+     */
+    processChunks(chunks) {
+        let text = '';
+        const toolUses = [];
+        let currentToolUse = null;
+        let usage;
+        let model;
+        for (const chunk of chunks) {
+            switch (chunk.type) {
+                case 'text':
+                    text += chunk.text ?? '';
+                    break;
+                case 'tool_use_start':
+                    if (chunk.toolUse) {
+                        currentToolUse = {
+                            id: chunk.toolUse.id,
+                            name: chunk.toolUse.name,
+                            inputJson: '',
+                        };
+                    }
+                    break;
+                case 'tool_use_delta':
+                    if (currentToolUse && chunk.text) {
+                        currentToolUse.inputJson += chunk.text;
+                    }
+                    break;
+                case 'tool_use_end':
+                    if (currentToolUse) {
+                        try {
+                            const input = currentToolUse.inputJson
+                                ? JSON.parse(currentToolUse.inputJson)
+                                : {};
+                            toolUses.push({
+                                id: currentToolUse.id,
+                                name: currentToolUse.name,
+                                input,
+                            });
+                        }
+                        catch {
+                            // Invalid JSON, skip this tool use
+                        }
+                        currentToolUse = null;
+                    }
+                    break;
+                case 'done':
+                    // Capture usage data from done chunk
+                    usage = chunk.usage;
+                    model = chunk.model;
+                    break;
+            }
+        }
+        return { text, toolUses, usage, model };
+    }
+    /**
+     * Generate a summary of messages using the LLM provider.
+     * Used for context summarization when approaching limits.
+     */
+    async generateSummary(messages) {
+        const summaryPrompt = `Please provide a concise summary of the following conversation. Focus on:
+1. Key decisions made
+2. Important context established
+3. Tasks completed or in progress
+4. Any relevant file paths or code snippets mentioned
+
+Keep the summary under 500 words.
+
+Conversation to summarize:
+${messages.map((m) => `${m.role}: ${typeof m.content === 'string' ? m.content : JSON.stringify(m.content)}`).join('\n\n')}`;
+        const summaryMessages = [{ role: 'user', content: summaryPrompt }];
+        let summary = '';
+        for await (const chunk of this.provider.chat(summaryMessages, {
+            ...this.chatOptions,
+            maxTokens: this.contextManager?.getConfig().summarization.summaryMaxTokens ?? 2000,
+        })) {
+            if (chunk.type === 'text' && chunk.text) {
+                summary += chunk.text;
+            }
+        }
+        return summary || 'No summary generated.';
+    }
+    /**
+     * Generate a summary when the agent hits max iterations.
+     * This provides a graceful fallback instead of just throwing an error.
+     */
+    async generateIterationLimitSummary(messages, maxIterations, toolCalls) {
+        // Build a summary of tool calls made
+        const toolSummary = toolCalls.length > 0
+            ? toolCalls
+                .map((tc) => {
+                const status = tc.result.success ? 'succeeded' : 'failed';
+                return `- ${tc.name}: ${status}`;
+            })
+                .join('\n')
+            : 'No tools were called.';
+        const summaryPrompt = `The agent has reached its maximum iteration limit (${String(maxIterations)}) before completing the task.
+
+Here is a summary of the tool calls made:
+${toolSummary}
+
+Based on the conversation history below, please provide:
+1. A brief summary of what was accomplished
+2. What the agent was attempting to do when it stopped
+3. Suggested next steps for the user
+
+Keep the response concise and helpful.
+
+Recent conversation:
+${messages
+            .slice(-10)
+            .map((m) => `${m.role}: ${typeof m.content === 'string' ? m.content.slice(0, 500) : '[complex content]'}`)
+            .join('\n\n')}`;
+        const summaryMessages = [{ role: 'user', content: summaryPrompt }];
+        let summary = '';
+        for await (const chunk of this.provider.chat(summaryMessages, {
+            ...this.chatOptions,
+            maxTokens: 1000, // Keep summary concise
+        })) {
+            if (chunk.type === 'text' && chunk.text) {
+                summary += chunk.text;
+            }
+        }
+        if (!summary) {
+            // Fallback if LLM fails to generate summary
+            return (`[Agent reached maximum iterations (${String(maxIterations)}). ` +
+                `${String(toolCalls.length)} tool calls were made. ` +
+                `Consider increasing maxIterations or breaking the task into smaller steps.]`);
+        }
+        return `[Iteration limit reached]\n\n${summary}`;
+    }
+}
+/**
+ * Truncate tool result data to prevent memory bloat.
+ * Keeps important metadata but truncates large result values.
+ */
+function truncateToolResult(result, maxSize) {
+    if (!result.success || result.result === undefined) {
+        return result;
+    }
+    const resultStr = JSON.stringify(result.result);
+    if (resultStr.length <= maxSize) {
+        return result;
+    }
+    // Truncate the result
+    const headSize = Math.floor(maxSize * 0.7);
+    const tailSize = Math.floor(maxSize * 0.2);
+    const head = resultStr.slice(0, headSize);
+    const tail = resultStr.slice(-tailSize);
+    const omitted = resultStr.length - headSize - tailSize;
+    return {
+        success: result.success,
+        result: `[Truncated: ${String(omitted)} chars omitted]\n${head}...\n...\n${tail}`,
+    };
+}