attocode 0.1.0 → 0.1.3

package/dist/src/agent.js

@@ -21,7 +21,7 @@
 import { buildConfig, isFeatureEnabled, getEnabledFeatures, } from './defaults.js';
 import { createModeManager, formatModeList, parseMode, } from './modes.js';
 import { createLSPFileTools, } from './agent-tools/index.js';
-import { HookManager, MemoryManager, PlanningManager, ObservabilityManager, SafetyManager, RoutingManager, MultiAgentManager, ReActManager, ExecutionPolicyManager, ThreadManager, RulesManager, DEFAULT_RULE_SOURCES, ExecutionEconomicsManager, STANDARD_BUDGET, AgentRegistry, filterToolsForAgent, formatAgentList, createCancellationManager, isCancellationError, createResourceManager, createLSPManager, createSemanticCacheManager, createSkillManager, formatSkillList, createContextEngineering, stableStringify, createCodebaseContext, buildContextFromChunks, createPendingPlanManager, } from './integrations/index.js';
+import { HookManager, MemoryManager, PlanningManager, ObservabilityManager, SafetyManager, RoutingManager, MultiAgentManager, ReActManager, ExecutionPolicyManager, ThreadManager, RulesManager, DEFAULT_RULE_SOURCES, ExecutionEconomicsManager, STANDARD_BUDGET, AgentRegistry, filterToolsForAgent, formatAgentList, createCancellationManager, isCancellationError, createTimeoutToken, createLinkedToken, race, createResourceManager, createLSPManager, createSemanticCacheManager, createSkillManager, formatSkillList, createContextEngineering, stableStringify, createCodebaseContext, buildContextFromChunks, createPendingPlanManager, createInteractivePlanner, createRecursiveContext, createLearningStore, createCompactor, createAutoCompactionManager, createFileChangeTracker, createCapabilitiesRegistry, } from './integrations/index.js';
 // Lesson 26: Tracing & Evaluation integration
 import { createTraceCollector } from './tracing/trace-collector.js';
 // Spawn agent tool for LLM-driven subagent delegation
@@ -60,6 +60,13 @@ export class ProductionAgent {
     traceCollector = null;
     modeManager;
     pendingPlanManager;
+    interactivePlanner = null;
+    recursiveContext = null;
+    learningStore = null;
+    compactor = null;
+    autoCompactionManager = null;
+    fileChangeTracker = null;
+    capabilitiesRegistry = null;
     toolResolver = null;
     // Initialization tracking
     initPromises = [];
@@ -327,6 +334,270 @@ export class ProductionAgent {
                     break;
             }
         });
+        // Interactive Planning (conversational + editable planning)
+        if (isFeatureEnabled(this.config.interactivePlanning)) {
+            const interactiveConfig = typeof this.config.interactivePlanning === 'object'
+                ? this.config.interactivePlanning
+                : {};
+            this.interactivePlanner = createInteractivePlanner({
+                autoCheckpoint: interactiveConfig.enableCheckpoints ?? true,
+                confirmBeforeExecute: interactiveConfig.requireApproval ?? true,
+                maxCheckpoints: 20,
+                autoPauseAtDecisions: true,
+            });
+            // Forward planner events to observability
+            this.interactivePlanner.on(event => {
+                switch (event.type) {
+                    case 'plan.created':
+                        this.observability?.logger?.info('Interactive plan created', {
+                            planId: event.plan.id,
+                            stepCount: event.plan.steps.length,
+                        });
+                        break;
+                    case 'step.completed':
+                        this.observability?.logger?.debug('Plan step completed', {
+                            stepId: event.step.id,
+                            status: event.step.status,
+                        });
+                        break;
+                    case 'plan.cancelled':
+                        this.observability?.logger?.info('Plan cancelled', { reason: event.reason });
+                        break;
+                    case 'checkpoint.created':
+                        this.observability?.logger?.debug('Plan checkpoint created', {
+                            checkpointId: event.checkpoint.id,
+                        });
+                        break;
+                }
+            });
+        }
+        // Recursive Context (RLM - Recursive Language Models)
+        // Enables on-demand context exploration for large codebases
+        if (isFeatureEnabled(this.config.recursiveContext)) {
+            const recursiveConfig = typeof this.config.recursiveContext === 'object'
+                ? this.config.recursiveContext
+                : {};
+            this.recursiveContext = createRecursiveContext({
+                maxDepth: recursiveConfig.maxRecursionDepth ?? 5,
+                snippetTokens: recursiveConfig.maxSnippetTokens ?? 2000,
+                synthesisTokens: 1000,
+                totalBudget: 50000,
+                cacheResults: recursiveConfig.cacheNavigationResults ?? true,
+            });
+            // Note: File system source should be registered when needed with proper glob/readFile functions
+            // This is deferred to allow flexible configuration
+            // Forward RLM events
+            this.recursiveContext.on(event => {
+                switch (event.type) {
+                    case 'process.started':
+                        this.observability?.logger?.debug('RLM process started', {
+                            query: event.query,
+                            depth: event.depth,
+                        });
+                        break;
+                    case 'navigation.command':
+                        this.observability?.logger?.debug('RLM navigation command', {
+                            command: event.command,
+                            depth: event.depth,
+                        });
+                        break;
+                    case 'process.completed':
+                        this.observability?.logger?.debug('RLM process completed', {
+                            stats: event.stats,
+                        });
+                        break;
+                    case 'budget.warning':
+                        this.observability?.logger?.warn('RLM budget warning', {
+                            remaining: event.remaining,
+                            total: event.total,
+                        });
+                        break;
+                }
+            });
+        }
+        // Learning Store (cross-session learning from failures)
+        // Connects to the failure tracker in contextEngineering for automatic learning extraction
+        if (isFeatureEnabled(this.config.learningStore)) {
+            const learningConfig = typeof this.config.learningStore === 'object'
+                ? this.config.learningStore
+                : {};
+            this.learningStore = createLearningStore({
+                dbPath: learningConfig.dbPath ?? '.agent/learnings.db',
+                requireValidation: learningConfig.requireValidation ?? true,
+                autoValidateThreshold: learningConfig.autoValidateThreshold ?? 0.9,
+                maxLearnings: learningConfig.maxLearnings ?? 500,
+            });
+            // Connect to the failure tracker if available
+            if (this.contextEngineering) {
+                const failureTracker = this.contextEngineering.getFailureTracker();
+                if (failureTracker) {
+                    this.learningStore.connectFailureTracker(failureTracker);
+                }
+            }
+            // Forward learning events to observability
+            this.learningStore.on(event => {
+                switch (event.type) {
+                    case 'learning.proposed':
+                        this.observability?.logger?.info('Learning proposed', {
+                            learningId: event.learning.id,
+                            description: event.learning.description,
+                        });
+                        this.emit({
+                            type: 'learning.proposed',
+                            learningId: event.learning.id,
+                            description: event.learning.description,
+                        });
+                        break;
+                    case 'learning.validated':
+                        this.observability?.logger?.info('Learning validated', {
+                            learningId: event.learningId,
+                        });
+                        this.emit({ type: 'learning.validated', learningId: event.learningId });
+                        break;
+                    case 'learning.applied':
+                        this.observability?.logger?.debug('Learning applied', {
+                            learningId: event.learningId,
+                            context: event.context,
+                        });
+                        this.emit({
+                            type: 'learning.applied',
+                            learningId: event.learningId,
+                            context: event.context,
+                        });
+                        break;
+                    case 'pattern.extracted':
+                        this.observability?.logger?.info('Pattern extracted as learning', {
+                            pattern: event.pattern.description,
+                            learningId: event.learning.id,
+                        });
+                        break;
+                }
+            });
+        }
+        // Auto-Compaction Manager (sophisticated context compaction)
+        // Uses the Compactor for LLM-based summarization with threshold monitoring
+        if (isFeatureEnabled(this.config.compaction)) {
+            const compactionConfig = typeof this.config.compaction === 'object'
+                ? this.config.compaction
+                : {};
+            // Create the compactor (requires provider for LLM summarization)
+            this.compactor = createCompactor(this.provider, {
+                enabled: true,
+                tokenThreshold: compactionConfig.tokenThreshold ?? 80000,
+                preserveRecentCount: compactionConfig.preserveRecentCount ?? 10,
+                preserveToolResults: compactionConfig.preserveToolResults ?? true,
+                summaryMaxTokens: compactionConfig.summaryMaxTokens ?? 2000,
+                summaryModel: compactionConfig.summaryModel,
+            });
+            // Create the auto-compaction manager with threshold monitoring
+            this.autoCompactionManager = createAutoCompactionManager(this.compactor, {
+                mode: compactionConfig.mode ?? 'auto',
+                warningThreshold: 0.80,
+                autoCompactThreshold: 0.90,
+                hardLimitThreshold: 0.98,
+                preserveRecentUserMessages: Math.ceil((compactionConfig.preserveRecentCount ?? 10) / 2),
+                preserveRecentAssistantMessages: Math.ceil((compactionConfig.preserveRecentCount ?? 10) / 2),
+                cooldownMs: 60000, // 1 minute cooldown
+                maxContextTokens: this.config.maxContextTokens ?? 200000,
+            });
+            // Forward compactor events to observability
+            this.compactor.on(event => {
+                switch (event.type) {
+                    case 'compaction.start':
+                        this.observability?.logger?.info('Compaction started', {
+                            messageCount: event.messageCount,
+                        });
+                        break;
+                    case 'compaction.complete':
+                        this.observability?.logger?.info('Compaction complete', {
+                            tokensBefore: event.result.tokensBefore,
+                            tokensAfter: event.result.tokensAfter,
+                            compactedCount: event.result.compactedCount,
+                        });
+                        break;
+                    case 'compaction.error':
+                        this.observability?.logger?.error('Compaction error', {
+                            error: event.error,
+                        });
+                        break;
+                }
+            });
+            // Forward auto-compaction events
+            this.autoCompactionManager.on((event) => {
+                switch (event.type) {
+                    case 'autocompaction.warning':
+                        this.observability?.logger?.warn('Context approaching limit', {
+                            currentTokens: event.currentTokens,
+                            ratio: event.ratio,
+                        });
+                        this.emit({
+                            type: 'compaction.warning',
+                            currentTokens: event.currentTokens,
+                            threshold: Math.round(event.ratio * (this.config.maxContextTokens ?? 200000)),
+                        });
+                        break;
+                    case 'autocompaction.triggered':
+                        this.observability?.logger?.info('Auto-compaction triggered', {
+                            mode: event.mode,
+                            currentTokens: event.currentTokens,
+                        });
+                        break;
+                    case 'autocompaction.completed':
+                        this.observability?.logger?.info('Auto-compaction completed', {
+                            tokensBefore: event.tokensBefore,
+                            tokensAfter: event.tokensAfter,
+                            reduction: event.reduction,
+                        });
+                        this.emit({
+                            type: 'compaction.auto',
+                            tokensBefore: event.tokensBefore,
+                            tokensAfter: event.tokensAfter,
+                            messagesCompacted: event.tokensBefore - event.tokensAfter,
+                        });
+                        break;
+                    case 'autocompaction.hard_limit':
+                        this.observability?.logger?.error('Context hard limit reached', {
+                            currentTokens: event.currentTokens,
+                            ratio: event.ratio,
+                        });
+                        break;
+                    case 'autocompaction.emergency_truncate':
+                        this.observability?.logger?.warn('Emergency truncation performed', {
+                            reason: event.reason,
+                            messagesBefore: event.messagesBefore,
+                            messagesAfter: event.messagesAfter,
+                        });
+                        break;
+                }
+            });
+        }
+        // Note: FileChangeTracker requires a database instance which is not
+        // available at this point. Use initFileChangeTracker() to enable it
+        // after the agent is constructed with a database reference.
+        // This allows the feature to be optional and not require SQLite at all times.
+    }
+    /**
+     * Initialize the file change tracker with a database instance.
+     * Call this if you want undo capability for file operations.
+     *
+     * @param db - SQLite database instance from better-sqlite3
+     * @param sessionId - Session ID for tracking changes
+     */
+    initFileChangeTracker(db, sessionId) {
+        if (!isFeatureEnabled(this.config.fileChangeTracker)) {
+            return;
+        }
+        const trackerConfig = typeof this.config.fileChangeTracker === 'object'
+            ? this.config.fileChangeTracker
+            : {};
+        this.fileChangeTracker = createFileChangeTracker(db, sessionId, {
+            enabled: true,
+            maxFullContentBytes: trackerConfig.maxFullContentBytes ?? 50 * 1024,
+        });
+        this.observability?.logger?.info('File change tracker initialized', {
+            sessionId,
+            maxFullContentBytes: trackerConfig.maxFullContentBytes ?? 50 * 1024,
+        });
     }
     /**
      * Ensure all async initialization is complete before running.
@@ -518,11 +789,82 @@ export class ProductionAgent {
                 }
                 // =======================================================================
                 // ECONOMICS CHECK (Token Budget) - replaces hard iteration limit
+                // With recovery: try compaction before giving up on token limits
                 // =======================================================================
                 if (this.economics) {
                     const budgetCheck = this.economics.checkBudget();
                     if (!budgetCheck.canContinue) {
-                        // Hard limit reached
+                        // ===================================================================
+                        // RECOVERY ATTEMPT: Try emergency context reduction before giving up
+                        // Only for token-based limits, not iteration limits
+                        // ===================================================================
+                        const isTokenLimit = budgetCheck.budgetType === 'tokens' || budgetCheck.budgetType === 'cost';
+                        const alreadyTriedRecovery = this.state._recoveryAttempted === true;
+                        if (isTokenLimit && !alreadyTriedRecovery) {
+                            this.observability?.logger?.info('Budget limit reached, attempting recovery via context reduction', {
+                                reason: budgetCheck.reason,
+                                percentUsed: budgetCheck.percentUsed,
+                            });
+                            this.emit({
+                                type: 'resilience.retry',
+                                reason: 'budget_limit_compaction',
+                                attempt: 1,
+                                maxAttempts: 1,
+                            });
+                            // Mark that we've attempted recovery to prevent infinite loops
+                            this.state._recoveryAttempted = true;
+                            const tokensBefore = this.estimateContextTokens(messages);
+                            // Step 1: Compact tool outputs aggressively
+                            this.compactToolOutputs();
+                            // Step 2: Emergency truncation - keep system + last N messages
+                            const PRESERVE_RECENT = 10;
+                            if (messages.length > PRESERVE_RECENT + 2) {
+                                const systemMessage = messages.find(m => m.role === 'system');
+                                const recentMessages = messages.slice(-(PRESERVE_RECENT));
+                                // Rebuild message array
+                                messages.length = 0;
+                                if (systemMessage) {
+                                    messages.push(systemMessage);
+                                }
+                                messages.push({
+                                    role: 'system',
+                                    content: `[CONTEXT REDUCED: Earlier messages were removed to stay within budget. Conversation continues from recent context.]`,
+                                });
+                                messages.push(...recentMessages);
+                                // Update state messages too
+                                this.state.messages.length = 0;
+                                this.state.messages.push(...messages);
+                            }
+                            const tokensAfter = this.estimateContextTokens(messages);
+                            const reduction = Math.round((1 - tokensAfter / tokensBefore) * 100);
+                            if (tokensAfter < tokensBefore * 0.8) {
+                                // Significant reduction achieved
+                                this.observability?.logger?.info('Context reduction successful, continuing execution', {
+                                    tokensBefore,
+                                    tokensAfter,
+                                    reduction,
+                                });
+                                this.emit({
+                                    type: 'resilience.recovered',
+                                    reason: 'budget_limit_compaction',
+                                    attempts: 1,
+                                });
+                                this.emit({
+                                    type: 'compaction.auto',
+                                    tokensBefore,
+                                    tokensAfter,
+                                    messagesCompacted: tokensBefore - tokensAfter,
+                                });
+                                // Continue execution instead of breaking
+                                continue;
+                            }
+                            this.observability?.logger?.warn('Context reduction insufficient', {
+                                tokensBefore,
+                                tokensAfter,
+                                reduction,
+                            });
+                        }
+                        // Hard limit reached and recovery failed (or not applicable)
                         this.observability?.logger?.warn('Budget limit reached', {
                             reason: budgetCheck.reason,
                             budgetType: budgetCheck.budgetType,
@@ -617,8 +959,104 @@ export class ProductionAgent {
                         }
                     }
                 }
-                // Make LLM call
-                const response = await this.callLLM(messages);
+                // =====================================================================
+                // RESILIENT LLM CALL: Empty response retries + max_tokens continuation
+                // =====================================================================
+                // Get resilience config
+                const resilienceConfig = typeof this.config.resilience === 'object'
+                    ? this.config.resilience
+                    : {};
+                const resilienceEnabled = isFeatureEnabled(this.config.resilience);
+                const MAX_EMPTY_RETRIES = resilienceConfig.maxEmptyRetries ?? 2;
+                const MAX_CONTINUATIONS = resilienceConfig.maxContinuations ?? 3;
+                const AUTO_CONTINUE = resilienceConfig.autoContinue ?? true;
+                const MIN_CONTENT_LENGTH = resilienceConfig.minContentLength ?? 1;
+                let response = await this.callLLM(messages);
+                let emptyRetries = 0;
+                let continuations = 0;
+                // Phase 1: Handle empty responses with retry (if resilience enabled)
+                while (resilienceEnabled && emptyRetries < MAX_EMPTY_RETRIES) {
+                    const hasContent = response.content && response.content.length >= MIN_CONTENT_LENGTH;
+                    const hasToolCalls = response.toolCalls && response.toolCalls.length > 0;
+                    if (hasContent || hasToolCalls) {
+                        // Valid response received
+                        if (emptyRetries > 0) {
+                            this.emit({
+                                type: 'resilience.recovered',
+                                reason: 'empty_response',
+                                attempts: emptyRetries,
+                            });
+                            this.observability?.logger?.info('Recovered from empty response', {
+                                retries: emptyRetries,
+                            });
+                        }
+                        break;
+                    }
+                    // Empty response - retry with nudge
+                    emptyRetries++;
+                    this.emit({
+                        type: 'resilience.retry',
+                        reason: 'empty_response',
+                        attempt: emptyRetries,
+                        maxAttempts: MAX_EMPTY_RETRIES,
+                    });
+                    this.observability?.logger?.warn('Empty LLM response, retrying', {
+                        attempt: emptyRetries,
+                        maxAttempts: MAX_EMPTY_RETRIES,
+                    });
+                    // Add gentle nudge and retry
+                    const nudgeMessage = {
+                        role: 'user',
+                        content: '[System: Your previous response was empty. Please provide a response or use a tool.]',
+                    };
+                    messages.push(nudgeMessage);
+                    this.state.messages.push(nudgeMessage);
+                    response = await this.callLLM(messages);
+                }
+                // Phase 2: Handle max_tokens truncation with continuation (if enabled)
+                if (resilienceEnabled && AUTO_CONTINUE && response.stopReason === 'max_tokens' && !response.toolCalls?.length) {
+                    let accumulatedContent = response.content || '';
+                    while (continuations < MAX_CONTINUATIONS && response.stopReason === 'max_tokens') {
+                        continuations++;
+                        this.emit({
+                            type: 'resilience.continue',
+                            reason: 'max_tokens',
+                            continuation: continuations,
+                            maxContinuations: MAX_CONTINUATIONS,
+                            accumulatedLength: accumulatedContent.length,
+                        });
+                        this.observability?.logger?.info('Response truncated at max_tokens, continuing', {
+                            continuation: continuations,
+                            accumulatedLength: accumulatedContent.length,
+                        });
+                        // Add continuation request
+                        const continuationMessage = {
+                            role: 'assistant',
+                            content: accumulatedContent,
+                        };
+                        const continueRequest = {
+                            role: 'user',
+                            content: '[System: Please continue from where you left off. Do not repeat what you already said.]',
+                        };
+                        messages.push(continuationMessage, continueRequest);
+                        this.state.messages.push(continuationMessage, continueRequest);
+                        response = await this.callLLM(messages);
+                        // Accumulate content
+                        if (response.content) {
+                            accumulatedContent += response.content;
+                        }
+                    }
+                    // Update response with accumulated content
+                    if (continuations > 0) {
+                        response = { ...response, content: accumulatedContent };
+                        this.emit({
+                            type: 'resilience.completed',
+                            reason: 'max_tokens_continuation',
+                            continuations,
+                            finalLength: accumulatedContent.length,
+                        });
+                    }
+                }
                 // Record LLM usage for economics
                 if (this.economics && response.usage) {
                     this.economics.recordLLMUsage(response.usage.inputTokens, response.usage.outputTokens, this.config.model, response.usage.cost // Use actual cost from provider when available
@@ -639,6 +1077,20 @@ export class ProductionAgent {
                     // The model has "consumed" the tool outputs and produced a response,
                     // so we can replace verbose outputs with compact summaries
                     this.compactToolOutputs();
+                    // Final validation: warn if response is still empty after all retries
+                    if (!response.content || response.content.length === 0) {
+                        this.observability?.logger?.error('Agent finished with empty response after all retries', {
+                            emptyRetries,
+                            continuations,
+                            iteration: this.state.iteration,
+                        });
+                        this.emit({
+                            type: 'resilience.failed',
+                            reason: 'empty_final_response',
+                            emptyRetries,
+                            continuations,
+                        });
+                    }
                     break;
                 }
                 // Execute tool calls
@@ -653,8 +1105,34 @@ export class ProductionAgent {
                 const MAX_TOOL_OUTPUT_CHARS = 8000; // ~2000 tokens max per tool output
                 // =======================================================================
                 // PROACTIVE BUDGET CHECK - compact BEFORE we overflow, not after
+                // Uses AutoCompactionManager if available for sophisticated compaction
                 // =======================================================================
-                if (this.economics) {
+                const currentContextTokens = this.estimateContextTokens(messages);
+                if (this.autoCompactionManager) {
+                    // Use the AutoCompactionManager for threshold-based compaction
+                    const compactionResult = await this.autoCompactionManager.checkAndMaybeCompact({
+                        currentTokens: currentContextTokens,
+                        messages: messages,
+                    });
+                    // Handle compaction result
+                    if (compactionResult.status === 'compacted' && compactionResult.compactedMessages) {
+                        // Replace messages with compacted version
+                        messages.length = 0;
+                        messages.push(...compactionResult.compactedMessages);
+                        this.state.messages.length = 0;
+                        this.state.messages.push(...compactionResult.compactedMessages);
+                    }
+                    else if (compactionResult.status === 'hard_limit') {
+                        // Hard limit reached - this is serious, emit error
+                        this.emit({
+                            type: 'error',
+                            error: `Context hard limit reached (${Math.round(compactionResult.ratio * 100)}% of max tokens)`,
+                        });
+                        break;
+                    }
+                }
+                else if (this.economics) {
+                    // Fallback to simple compaction
                     const currentUsage = this.economics.getUsage();
                     const budget = this.economics.getBudget();
                     const percentUsed = (currentUsage.tokens / budget.maxTokens) * 100;
@@ -708,6 +1186,20 @@ export class ProductionAgent {
                     messages.push(toolMessage);
                     this.state.messages.push(toolMessage);
                 }
+                // Emit context health after adding tool results
+                const currentTokenEstimate = this.estimateContextTokens(messages);
+                const contextLimit = this.config.maxContextTokens || 100000;
+                const percentUsed = Math.round((currentTokenEstimate / contextLimit) * 100);
+                const avgTokensPerExchange = currentTokenEstimate / Math.max(1, this.state.iteration);
+                const remainingTokens = contextLimit - currentTokenEstimate;
+                const estimatedExchanges = Math.floor(remainingTokens / Math.max(1, avgTokensPerExchange));
+                this.emit({
+                    type: 'context.health',
+                    currentTokens: currentTokenEstimate,
+                    maxTokens: contextLimit,
+                    estimatedExchanges,
+                    percentUsed,
+                });
             }
             // =======================================================================
             // REFLECTION (Lesson 16)
@@ -755,6 +1247,11 @@ export class ProductionAgent {
         const rulesContent = this.rules?.getRulesContent() ?? '';
         const skillsPrompt = this.skillManager?.getActiveSkillsPrompt() ?? '';
         const memoryContext = this.memory?.getContextStrings(task) ?? [];
+        // Get relevant learnings from past sessions
+        const learningsContext = this.learningStore?.getLearningContext({
+            query: task,
+            maxLearnings: 5,
+        }) ?? '';
         // Budget-aware codebase context selection
         let codebaseContextStr = '';
         if (this.codebaseContext) {
@@ -802,9 +1299,10 @@ export class ProductionAgent {
         }
         // Build system prompt using cache-aware builder if available (Trick P)
         let systemPrompt;
-        // Combine memory and codebase context
+        // Combine memory, learnings, and codebase context
         const combinedContext = [
             ...(memoryContext.length > 0 ? memoryContext : []),
+            ...(learningsContext ? [learningsContext] : []),
             ...(codebaseContextStr ? [`\n## Relevant Code\n${codebaseContextStr}`] : []),
         ].join('\n');
         if (this.contextEngineering) {
@@ -936,6 +1434,17 @@ export class ProductionAgent {
                     reason: actualModel !== model ? 'Routed based on complexity' : 'Default model',
                     complexity: complexity <= 0.3 ? 'low' : complexity <= 0.7 ? 'medium' : 'high',
                 });
+                // Emit decision transparency event
+                this.emit({
+                    type: 'decision.routing',
+                    model: actualModel,
+                    reason: actualModel !== model
+                        ? `Complexity ${(complexity * 100).toFixed(0)}% - using ${actualModel}`
+                        : 'Default model for current task',
+                    alternatives: actualModel !== model
+                        ? [{ model, rejected: 'complexity threshold exceeded' }]
+                        : undefined,
+                });
             }
             else {
                 response = await this.provider.chat(messages, {
@@ -1072,6 +1581,15 @@ export class ProductionAgent {
                         policy: evaluation.policy,
                         reason: evaluation.reason,
                     });
+                    // Emit decision transparency event
+                    this.emit({
+                        type: 'decision.tool',
+                        tool: toolCall.name,
+                        decision: evaluation.policy === 'forbidden' ? 'blocked'
+                            : evaluation.policy === 'prompt' ? 'prompted'
+                                : 'allowed',
+                        policyMatch: evaluation.reason,
+                    });
                     // Handle forbidden policy - always block
                     if (evaluation.policy === 'forbidden') {
                         throw new Error(`Forbidden by policy: ${evaluation.reason}`);
@@ -1371,6 +1889,67 @@ export class ProductionAgent {
     getTraceCollector() {
         return this.traceCollector;
     }
+    /**
+     * Get the learning store for cross-session learning.
+     * Returns null if learning store is not enabled.
+     */
+    getLearningStore() {
+        return this.learningStore;
+    }
+    /**
+     * Get the auto-compaction manager.
+     * Returns null if compaction is not enabled.
+     */
+    getAutoCompactionManager() {
+        return this.autoCompactionManager;
+    }
+    /**
+     * Get the file change tracker for undo capability.
+     * Returns null if file change tracking is not enabled.
+     */
+    getFileChangeTracker() {
+        return this.fileChangeTracker;
+    }
+    /**
+     * Record a file change for potential undo.
+     * No-op if file change tracking is not enabled.
+     *
+     * @param params - Change details
+     * @returns Change ID if tracked, -1 otherwise
+     */
+    async trackFileChange(params) {
+        if (!this.fileChangeTracker) {
+            return -1;
+        }
+        return this.fileChangeTracker.recordChange({
+            filePath: params.filePath,
+            operation: params.operation,
+            contentBefore: params.contentBefore,
+            contentAfter: params.contentAfter,
+            turnNumber: this.state.iteration,
+            toolCallId: params.toolCallId,
+        });
+    }
+    /**
+     * Undo the last change to a specific file.
+     * Returns null if file change tracking is not enabled.
+     */
+    async undoLastFileChange(filePath) {
+        if (!this.fileChangeTracker) {
+            return null;
+        }
+        return this.fileChangeTracker.undoLastChange(filePath);
+    }
+    /**
+     * Undo all changes in the current turn.
+     * Returns null if file change tracking is not enabled.
+     */
+    async undoCurrentTurn() {
+        if (!this.fileChangeTracker) {
+            return null;
+        }
+        return this.fileChangeTracker.undoTurn(this.state.iteration);
+    }
     /**
      * Subscribe to events.
      */
@@ -2031,13 +2610,27 @@ export class ProductionAgent {
             const resolvedModel = (agentDef.model && agentDef.model.includes('/'))
                 ? agentDef.model
                 : this.config.model;
+            // Get subagent config with defaults
+            // Note: subagent config is SubagentConfig | false from buildConfig
+            const subagentConfig = this.config.subagent;
+            const hasSubagentConfig = subagentConfig !== false && subagentConfig !== undefined;
+            const defaultMaxIterations = hasSubagentConfig
+                ? subagentConfig.defaultMaxIterations ?? 10
+                : 10;
+            const subagentTimeout = hasSubagentConfig
+                ? subagentConfig.defaultTimeout ?? 120000
+                : 120000;
             // Create a sub-agent with the agent's config
             const subAgent = new ProductionAgent({
                 provider: this.provider,
                 tools: agentTools,
+                // Pass toolResolver so subagent can lazy-load MCP tools
+                toolResolver: this.toolResolver || undefined,
+                // Pass MCP tool summaries so subagent knows what tools are available
+                mcpToolSummaries: this.config.mcpToolSummaries,
                 systemPrompt: agentDef.systemPrompt,
                 model: resolvedModel,
-                maxIterations: agentDef.maxIterations || 30,
+                maxIterations: agentDef.maxIterations || defaultMaxIterations,
                 // Inherit some features but keep subagent simpler
                 memory: false,
                 planning: false,
@@ -2054,26 +2647,68 @@ export class ProductionAgent {
                     custom: [],
                 },
             });
-            // Forward events from subagent
+            // Forward events from subagent with context
             subAgent.subscribe(event => {
-                // Just forward the event as-is - the agent.spawn event already logged the agent name
-                this.emit(event);
+                // Tag event with subagent source so TUI can display it properly
+                const taggedEvent = { ...event, subagent: agentName };
+                this.emit(taggedEvent);
             });
-            // Run the task
-            const result = await subAgent.run(task);
-            const duration = Date.now() - startTime;
-            const spawnResult = {
-                success: result.success,
-                output: result.response || result.error || '',
-                metrics: {
-                    tokens: result.metrics.totalTokens,
-                    duration,
-                    toolCalls: result.metrics.toolCalls,
-                },
-            };
-            this.emit({ type: 'agent.complete', agentId: agentName, success: result.success });
-            await subAgent.cleanup();
-            return spawnResult;
+            // Create timeout token for subagent execution
+            const timeoutSource = createTimeoutToken(subagentTimeout);
+            // Link parent's cancellation with subagent timeout so ESC propagates to subagents
+            const parentSource = this.cancellation?.getSource();
+            const effectiveSource = parentSource
+                ? createLinkedToken(parentSource, timeoutSource)
+                : timeoutSource;
+            try {
+                // Run the task with cancellation propagation from parent
+                const result = await race(subAgent.run(task), effectiveSource.token);
+                const duration = Date.now() - startTime;
+                const spawnResult = {
+                    success: result.success,
+                    output: result.response || result.error || '',
+                    metrics: {
+                        tokens: result.metrics.totalTokens,
+                        duration,
+                        toolCalls: result.metrics.toolCalls,
+                    },
+                };
+                this.emit({ type: 'agent.complete', agentId: agentName, success: result.success });
+                await subAgent.cleanup();
+                return spawnResult;
+            }
+            catch (err) {
+                // Handle cancellation (user ESC or timeout) for cleaner error messages
+                if (isCancellationError(err)) {
+                    const duration = Date.now() - startTime;
+                    const isUserCancellation = parentSource?.isCancellationRequested;
+                    const reason = isUserCancellation
+                        ? 'User cancelled'
+                        : `Timed out after ${subagentTimeout}ms`;
+                    this.emit({ type: 'agent.error', agentId: agentName, error: reason });
+                    // Try to cleanup the subagent gracefully
+                    try {
+                        await subAgent.cleanup();
+                    }
+                    catch {
+                        // Ignore cleanup errors on cancellation
+                    }
+                    const output = isUserCancellation
+                        ? `Subagent '${agentName}' was cancelled by user.`
+                        : `Subagent '${agentName}' timed out after ${Math.round(subagentTimeout / 1000)}s. The task may be too complex or the model may be slow.`;
+                    return {
+                        success: false,
+                        output,
+                        metrics: { tokens: 0, duration, toolCalls: 0 },
+                    };
+                }
+                throw err; // Re-throw non-cancellation errors
+            }
+            finally {
+                // Dispose both sources (linked source disposes its internal state, timeout source handles its timer)
+                effectiveSource.dispose();
+                timeoutSource.dispose();
+            }
         }
         catch (err) {
             const error = err instanceof Error ? err.message : String(err);
@@ -2556,6 +3191,18 @@ If the task is a simple question or doesn't need specialized handling, set bestA
     // =========================================================================
     // SKILLS METHODS
     // =========================================================================
+    /**
+     * Get the skill manager instance for advanced operations.
+     */
+    getSkillManager() {
+        return this.skillManager;
+    }
+    /**
+     * Get the agent registry instance for advanced operations.
+     */
+    getAgentRegistry() {
+        return this.agentRegistry;
+    }
     /**
      * Get all loaded skills.
      */
@@ -2602,6 +3249,34 @@ If the task is a simple question or doesn't need specialized handling, set bestA
     findMatchingSkills(query) {
         return this.skillManager?.findMatchingSkills(query) || [];
     }
+    /**
+     * Get the capabilities registry for unified discovery.
+     * Lazily creates and populates the registry on first access.
+     */
+    getCapabilitiesRegistry() {
+        if (!this.capabilitiesRegistry) {
+            this.capabilitiesRegistry = createCapabilitiesRegistry();
+            // Register sources
+            this.capabilitiesRegistry.registerToolRegistry({
+                getTools: () => this.getTools(),
+            });
+            if (this.skillManager) {
+                this.capabilitiesRegistry.registerSkillManager(this.skillManager);
+            }
+            if (this.agentRegistry) {
+                this.capabilitiesRegistry.registerAgentRegistry(this.agentRegistry);
+            }
+            // MCP client is registered externally if available
+        }
+        return this.capabilitiesRegistry;
+    }
+    /**
+     * Register an MCP client with the capabilities registry.
+     */
+    registerMCPClient(client) {
+        const registry = this.getCapabilitiesRegistry();
+        registry.registerMCPClient(client);
+    }
     /**
      * Get formatted list of available skills.
      */