attocode 0.1.2 → 0.1.4

package/dist/src/agent.js

@@ -21,9 +21,12 @@
 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, createInteractivePlanner, createRecursiveContext, } 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';
+// Model registry for context window limits
+import { modelRegistry } from './costs/index.js';
+import { getModelContextLength } from './integrations/openrouter-pricing.js';
 // Spawn agent tool for LLM-driven subagent delegation
 import { createBoundSpawnAgentTool } from './tools/agent.js';
 // =============================================================================
@@ -62,6 +65,11 @@ export class ProductionAgent {
     pendingPlanManager;
     interactivePlanner = null;
     recursiveContext = null;
+    learningStore = null;
+    compactor = null;
+    autoCompactionManager = null;
+    fileChangeTracker = null;
+    capabilitiesRegistry = null;
     toolResolver = null;
     // Initialization tracking
     initPromises = [];
@@ -410,6 +418,224 @@ export class ProductionAgent {
                 }
             });
         }
+        // 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
+            // Wire reversible compaction through contextEngineering when available
+            const compactHandler = this.contextEngineering
+                ? async (messages) => {
+                    // Use contextEngineering's reversible compaction to preserve references
+                    const summarize = async (msgs) => {
+                        // Use the basic compactor's summarization capability
+                        const result = await this.compactor.compact(msgs);
+                        return result.summary;
+                    };
+                    const contextMsgs = messages.map(m => ({
+                        role: m.role,
+                        content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content),
+                    }));
+                    const result = await this.contextEngineering.compact(contextMsgs, summarize);
+                    const tokensBefore = this.compactor.estimateTokens(messages);
+                    const tokensAfter = this.compactor.estimateTokens([{ role: 'assistant', content: result.summary }]);
+                    return {
+                        summary: result.summary + (result.reconstructionPrompt ? `\n\n${result.reconstructionPrompt}` : ''),
+                        tokensBefore,
+                        tokensAfter,
+                        preservedMessages: [{ role: 'assistant', content: result.summary }],
+                        references: result.references,
+                    };
+                }
+                : undefined;
+            // Get model's actual context window - try OpenRouter first (real API data),
+            // then fall back to hardcoded ModelRegistry, then config, then default
+            const openRouterContext = getModelContextLength(this.config.model || '');
+            const registryInfo = modelRegistry.getModel(this.config.model || '');
+            const registryContext = registryInfo?.capabilities?.maxContextTokens;
+            const maxContextTokens = this.config.maxContextTokens
+                ?? openRouterContext // From OpenRouter API (e.g., GLM-4.7 = 202752)
+                ?? registryContext // From hardcoded registry (Claude, GPT-4o, etc.)
+                ?? 200000; // Fallback to 200K
+            this.autoCompactionManager = createAutoCompactionManager(this.compactor, {
+                mode: compactionConfig.mode ?? 'auto',
+                warningThreshold: 0.70, // Warn at 70% of model's context
+                autoCompactThreshold: 0.80, // Compact at 80% (changed from 0.90)
+                hardLimitThreshold: 0.95, // Hard limit at 95%
+                preserveRecentUserMessages: Math.ceil((compactionConfig.preserveRecentCount ?? 10) / 2),
+                preserveRecentAssistantMessages: Math.ceil((compactionConfig.preserveRecentCount ?? 10) / 2),
+                cooldownMs: 60000, // 1 minute cooldown
+                maxContextTokens, // Dynamic from model registry or config
+                compactHandler, // Use reversible compaction when contextEngineering is available
+            });
+            // 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.
@@ -438,9 +664,19 @@ export class ProductionAgent {
         const traceId = this.observability?.tracer?.startTrace('agent.run') || `trace-${Date.now()}`;
         this.emit({ type: 'start', task, traceId });
         this.observability?.logger?.info('Agent started', { task });
-        // Lesson 26: Start trace capture session
-        const traceSessionId = `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-        await this.traceCollector?.startSession(traceSessionId, task, this.config.model || 'default', {});
+        // Lesson 26: Start trace capture
+        // If session is already active (managed by REPL), start a task within it.
+        // Otherwise, start a new session for backward compatibility (single-task mode).
+        const taskId = `task-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        if (this.traceCollector?.isSessionActive()) {
+            // Session managed by REPL - just start a task
+            await this.traceCollector.startTask(taskId, task);
+        }
+        else {
+            // Single-task mode (backward compatibility) - start session with task
+            const traceSessionId = `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            await this.traceCollector?.startSession(traceSessionId, task, this.config.model || 'default', {});
+        }
         try {
             // Check for cancellation before starting
             cancellationToken?.throwIfCancellationRequested();
@@ -471,8 +707,14 @@ export class ProductionAgent {
             };
             this.emit({ type: 'complete', result });
             this.observability?.logger?.info('Agent completed', { duration, success: true });
-            // Lesson 26: End trace capture session
-            await this.traceCollector?.endSession({ success: true, output: response });
+            // Lesson 26: End trace capture
+            // If task is active (REPL mode), end the task. Otherwise end the session (single-task mode).
+            if (this.traceCollector?.isTaskActive()) {
+                await this.traceCollector.endTask({ success: true, output: response });
+            }
+            else if (this.traceCollector?.isSessionActive()) {
+                await this.traceCollector.endSession({ success: true, output: response });
+            }
             return result;
         }
         catch (err) {
@@ -484,8 +726,13 @@ export class ProductionAgent {
                 const cleanupDuration = Date.now() - cleanupStart;
                 this.emit({ type: 'cancellation.completed', cleanupDuration });
                 this.observability?.logger?.info('Agent cancelled', { reason: error.message, cleanupDuration });
-                // Lesson 26: End trace capture session on cancellation
-                await this.traceCollector?.endSession({ success: false, failureReason: `Cancelled: ${error.message}` });
+                // Lesson 26: End trace capture on cancellation
+                if (this.traceCollector?.isTaskActive()) {
+                    await this.traceCollector.endTask({ success: false, failureReason: `Cancelled: ${error.message}` });
+                }
+                else if (this.traceCollector?.isSessionActive()) {
+                    await this.traceCollector.endSession({ success: false, failureReason: `Cancelled: ${error.message}` });
+                }
                 return {
                     success: false,
                     response: '',
@@ -499,8 +746,13 @@ export class ProductionAgent {
             await this.observability?.tracer?.endTrace();
             this.emit({ type: 'error', error: error.message });
             this.observability?.logger?.error('Agent failed', { error: error.message });
-            // Lesson 26: End trace capture session on error
-            await this.traceCollector?.endSession({ success: false, failureReason: error.message });
+            // Lesson 26: End trace capture on error
+            if (this.traceCollector?.isTaskActive()) {
+                await this.traceCollector.endTask({ success: false, failureReason: error.message });
+            }
+            else if (this.traceCollector?.isSessionActive()) {
+                await this.traceCollector.endSession({ success: false, failureReason: error.message });
+            }
             return {
                 success: false,
                 response: '',
@@ -573,6 +825,11 @@ export class ProductionAgent {
             // Agent loop - now uses economics-based budget checking
             while (true) {
                 this.state.iteration++;
+                // Record iteration start for tracing
+                this.traceCollector?.record({
+                    type: 'iteration.start',
+                    data: { iterationNumber: this.state.iteration },
+                });
                 // =======================================================================
                 // CANCELLATION CHECK
                 // =======================================================================
@@ -774,14 +1031,21 @@ export class ProductionAgent {
                 // =====================================================================
                 // RESILIENT LLM CALL: Empty response retries + max_tokens continuation
                 // =====================================================================
-                const MAX_EMPTY_RETRIES = 2;
-                const MAX_CONTINUATIONS = 3;
+                // 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
-                while (emptyRetries < MAX_EMPTY_RETRIES) {
-                    const hasContent = response.content && response.content.length > 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
@@ -818,8 +1082,8 @@ export class ProductionAgent {
                     this.state.messages.push(nudgeMessage);
                     response = await this.callLLM(messages);
                 }
-                // Phase 2: Handle max_tokens truncation with continuation
-                if (response.stopReason === 'max_tokens' && !response.toolCalls?.length) {
+                // 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++;
@@ -896,6 +1160,11 @@ export class ProductionAgent {
                             continuations,
                         });
                     }
+                    // Record iteration end for tracing (no tool calls case)
+                    this.traceCollector?.record({
+                        type: 'iteration.end',
+                        data: { iterationNumber: this.state.iteration },
+                    });
                     break;
                 }
                 // Execute tool calls
@@ -910,8 +1179,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;
@@ -965,6 +1260,25 @@ 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.getMaxContextTokens();
+                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,
+                });
+                // Record iteration end for tracing (after tool execution)
+                this.traceCollector?.record({
+                    type: 'iteration.end',
+                    data: { iterationNumber: this.state.iteration },
+                });
             }
             // =======================================================================
             // REFLECTION (Lesson 16)
@@ -1012,6 +1326,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) {
@@ -1059,9 +1378,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) {
@@ -1118,7 +1438,7 @@ export class ProductionAgent {
             return sum + Math.ceil(content.length / 3.5); // ~3.5 chars per token estimate
         }, 0);
         // Use context window size, not output token limit
-        const contextLimit = this.config.maxContextTokens || 100000;
+        const contextLimit = this.getMaxContextTokens();
         this.emit({
             type: 'insight.context',
             currentTokens: estimatedTokens,
@@ -1193,6 +1513,38 @@ 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,
+                });
+                // Enhanced tracing: Record routing decision
+                this.traceCollector?.record({
+                    type: 'decision',
+                    data: {
+                        type: 'routing',
+                        decision: `Selected model: ${actualModel}`,
+                        outcome: 'allowed',
+                        reasoning: actualModel !== model
+                            ? `Task complexity ${(complexity * 100).toFixed(0)}% exceeded threshold - routed to ${actualModel}`
+                            : `Default model ${model} suitable for task complexity ${(complexity * 100).toFixed(0)}%`,
+                        factors: [
+                            { name: 'complexity', value: complexity, weight: 0.8 },
+                            { name: 'hasTools', value: context.hasTools, weight: 0.1 },
+                            { name: 'taskType', value: context.taskType, weight: 0.1 },
+                        ],
+                        alternatives: actualModel !== model
+                            ? [{ option: model, reason: 'complexity threshold exceeded', rejected: true }]
+                            : undefined,
+                        confidence: 0.9,
+                    },
+                });
             }
             else {
                 response = await this.provider.chat(messages, {
@@ -1226,6 +1578,19 @@ export class ProductionAgent {
                     durationMs: duration,
                 },
             });
+            // Enhanced tracing: Record thinking/reasoning blocks if present
+            if (response.thinking) {
+                this.traceCollector?.record({
+                    type: 'llm.thinking',
+                    data: {
+                        requestId,
+                        content: response.thinking,
+                        summarized: response.thinking.length > 10000, // Summarize if very long
+                        originalLength: response.thinking.length,
+                        durationMs: duration,
+                    },
+                });
+            }
             // Record metrics
             this.observability?.metrics?.recordLLMCall(response.usage?.inputTokens || 0, response.usage?.outputTokens || 0, duration, actualModel, response.usage?.cost // Actual cost from provider (e.g., OpenRouter)
             );
@@ -1299,6 +1664,7 @@ export class ProductionAgent {
                         type: 'plan.change.queued',
                         tool: toolCall.name,
                         changeId: change?.id,
+                        summary: this.formatToolArgsForPlan(toolCall.name, toolCall.arguments),
                     });
                     // Return a message indicating the change was queued
                     const queueMessage = `[PLAN MODE] Change queued for approval:\n` +
@@ -1329,6 +1695,32 @@ 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,
+                    });
+                    // Enhanced tracing: Record policy decision
+                    this.traceCollector?.record({
+                        type: 'decision',
+                        data: {
+                            type: 'policy',
+                            decision: `Tool ${toolCall.name}: ${evaluation.policy}`,
+                            outcome: evaluation.policy === 'forbidden' ? 'blocked'
+                                : evaluation.policy === 'prompt' ? 'deferred'
+                                    : 'allowed',
+                            reasoning: evaluation.reason,
+                            factors: [
+                                { name: 'policy', value: evaluation.policy },
+                                { name: 'requiresApproval', value: evaluation.requiresApproval ?? false },
+                            ],
+                            confidence: evaluation.intent?.confidence ?? 0.8,
+                        },
+                    });
                     // Handle forbidden policy - always block
                     if (evaluation.policy === 'forbidden') {
                         throw new Error(`Forbidden by policy: ${evaluation.reason}`);
@@ -1594,6 +1986,12 @@ export class ProductionAgent {
         if (toolName === 'delete_file') {
             return `Delete: ${args.path || args.file_path}`;
         }
+        if (toolName === 'spawn_agent' || toolName === 'researcher') {
+            const task = String(args.task || args.prompt || args.goal || '');
+            const model = args.model ? ` (${args.model})` : '';
+            const firstLine = task.split('\n')[0].slice(0, 100);
+            return `${firstLine}${task.length > 100 ? '...' : ''}${model}`;
+        }
         // Generic
         return `Args: ${JSON.stringify(args).slice(0, 100)}...`;
     }
@@ -1621,6 +2019,27 @@ export class ProductionAgent {
     getState() {
         return { ...this.state };
     }
+    /**
+     * Get the maximum context tokens for this agent's model.
+     * Priority: user config > OpenRouter API > hardcoded ModelRegistry > 200K default
+     */
+    getMaxContextTokens() {
+        if (this.config.maxContextTokens) {
+            return this.config.maxContextTokens;
+        }
+        // Try OpenRouter API cache (has real data for GLM-4.7, etc.)
+        const openRouterContext = getModelContextLength(this.config.model || '');
+        if (openRouterContext) {
+            return openRouterContext;
+        }
+        // Fall back to hardcoded registry
+        const registryInfo = modelRegistry.getModel(this.config.model || '');
+        if (registryInfo?.capabilities?.maxContextTokens) {
+            return registryInfo.capabilities.maxContextTokens;
+        }
+        // Default
+        return 200000;
+    }
     /**
      * Get the trace collector (Lesson 26).
      * Returns null if trace capture is not enabled.
@@ -1628,6 +2047,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.
      */
@@ -2280,6 +2760,8 @@ export class ProductionAgent {
         this.emit({ type: 'agent.spawn', agentId: `spawn-${Date.now()}`, name: agentName, task });
         this.observability?.logger?.info('Spawning agent', { name: agentName, task });
         const startTime = Date.now();
+        const childSessionId = `subagent-${agentName}-${Date.now()}`;
+        const childTraceId = `trace-${childSessionId}`;
         try {
             // Filter tools for this agent
             const agentTools = filterToolsForAgent(agentDef, Array.from(this.tools.values()));
@@ -2288,13 +2770,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,
@@ -2317,21 +2813,88 @@ export class ProductionAgent {
                 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 });
+                // Enhanced tracing: Record subagent completion
+                this.traceCollector?.record({
+                    type: 'subagent.link',
+                    data: {
+                        parentSessionId: this.traceCollector.getSessionId() || 'unknown',
+                        childSessionId,
+                        childTraceId,
+                        childConfig: {
+                            agentType: agentName,
+                            model: resolvedModel || 'default',
+                            task,
+                            tools: agentTools.map(t => t.name),
+                        },
+                        spawnContext: {
+                            reason: `Delegated task: ${task.slice(0, 100)}`,
+                            expectedOutcome: agentDef.description,
+                            parentIteration: this.state.iteration,
+                        },
+                        result: {
+                            success: result.success,
+                            summary: (result.response || result.error || '').slice(0, 500),
+                            tokensUsed: result.metrics.totalTokens,
+                            durationMs: duration,
+                        },
+                    },
+                });
+                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);
@@ -2814,6 +3377,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.
      */
@@ -2860,6 +3435,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.
      */