indusagi-coding-agent 0.1.41 → 0.1.43

package/dist/runtime/agent-session.js

@@ -0,0 +1,2927 @@
+/**
+ * Agent Session - Core abstraction for agent lifecycle and session management
+ *
+ * @module core/agent-session
+ * @description
+ * Central controller for agent execution across all run modes (interactive, print, RPC).
+ * Manages complete agent lifecycle including state, events, persistence, and tool execution.
+ *
+ * Based on session management patterns from Anthropic's Claude API SDK
+ * and stateful execution frameworks. Refactored for multi-modal agent architecture.
+ *
+ * ## Responsibilities
+ *
+ * **Agent Lifecycle Management:**
+ * - Session initialization and persistence
+ * - Event subscription and publishing
+ * - State transitions and message handling
+ * - Model and thinking level selection
+ *
+ * **Tool Execution:**
+ * - Bash command execution with streaming and cancellation
+ * - Tool wrapping with extensions and hooks
+ * - Result recording and context building
+ *
+ * **Session Persistence:**
+ * - Automatic message persisting on completion
+ * - Session compaction and summarization
+ * - Branch navigation and forking
+ * - Context overflow recovery
+ *
+ * **Advanced Features:**
+ * - Auto-retry with exponential backoff for transient errors
+ * - Auto-compaction at configurable thresholds
+ * - Branch summarization for abandoned paths
+ * - Extension system integration
+ * - Skill and prompt template expansion
+ *
+ * ## Architecture
+ *
+ * This class is shared between all run modes (interactive, print, RPC).
+ * Modes use this class and add their own I/O layer on top.
+ *
+ * **Core Dependencies:**
+ * - EventBus: Event subscription system (internal only)
+ * - SessionManager: Persistence layer for session files
+ * - SettingsManager: User configuration
+ * - ExtensionRunner: Plugin system with command registration
+ * - HookRunner: Lifecycle hooks for advanced customization
+ * - Tools: Bash, read, write, edit, find, grep, and more
+ * - CompactionSystem: Automatic context compression
+ *
+ * **Event Flow:**
+ * ```
+ * Agent Events -> AgentSession._handleAgentEvent
+ * -> Extensions (hooks + custom message emission)
+ * -> User Listeners (via subscribe())
+ * -> Persistence (session manager)
+ * -> Auto-retry / Auto-compaction checks
+ * ```
+ *
+ * **Tool Execution Flow:**
+ * ```
+ * Agent Tool Call
+ * -> Extensions (before hooks)
+ * -> Tool Implementation
+ * -> Streaming via onChunk callback
+ * -> Tool Result Recording
+ * -> Extensions (after hooks)
+ * -> Context Building
+ * ```
+ *
+ * ## Usage Examples
+ *
+ * ### Initialize a session
+ * ```typescript
+ * const config: AgentSessionConfig = {
+ *   agent: new Agent({ ... }),
+ *   sessionManager: new SessionManager({ ... }),
+ *   settingsManager: new SettingsManager({ ... }),
+ *   cwd: process.cwd(),
+ *   resourceLoader: new ResourceLoader({ ... }),
+ *   modelRegistry: new ModelRegistry({ ... }),
+ * };
+ *
+ * const session = new AgentSession(config);
+ * ```
+ *
+ * ### Subscribe to events
+ * ```typescript
+ * const unsubscribe = session.subscribe((event) => {
+ *   if (event.type === "message_end") {
+ *     console.log("Message completed:", event.message);
+ *   }
+ * });
+ * ```
+ *
+ * ### Send a prompt
+ * ```typescript
+ * // User prompt with model validation
+ * await session.prompt("Help me refactor this code", {
+ *   expandPromptTemplates: true,
+ * });
+ *
+ * // Extension command (executed immediately)
+ * await session.prompt("/login anthropic");
+ *
+ * // During streaming: interrupt with steering
+ * await session.steer("Wait, try a different approach");
+ *
+ * // Or queue follow-up
+ * await session.followUp("Please continue when done");
+ * ```
+ *
+ * ### Execute bash
+ * ```typescript
+ * const result = await session.executeBash("npm test", (chunk) => {
+ *   process.stdout.write(chunk);
+ * });
+ *
+ * console.log("Exit code:", result.exitCode);
+ * if (result.truncated) {
+ *   console.log("Full output:", result.fullOutputPath);
+ * }
+ * ```
+ *
+ * ### Session management
+ * ```typescript
+ * // Create new session
+ * await session.newSession();
+ *
+ * // Switch to existing session
+ * await session.switchSession("/path/to/session.jsonl");
+ *
+ * // Fork at specific entry
+ * const { selectedText, cancelled } = await session.fork(entryId);
+ *
+ * // Navigate tree with optional branch summarization
+ * await session.navigateTree(targetId, { summarize: true });
+ *
+ * // Manually compact session
+ * await session.compact("Focus on backend changes");
+ * ```
+ *
+ * ### Model & thinking level
+ * ```typescript
+ * // Cycle through models (or scoped models if --models was used)
+ * const result = await session.cycleModel("forward");
+ * console.log("Switched to:", result?.model.id);
+ *
+ * // Set thinking level (automatically clamped to model capabilities)
+ * session.setThinkingLevel("high");
+ * const available = session.getAvailableThinkingLevels();
+ * ```
+ *
+ * ## Lifecycle Hooks
+ *
+ * Extensions can listen to these session events:
+ * - `session_start`: Session initialized or reloaded
+ * - `session_switch`: Switched to different session file
+ * - `session_fork`: Created fork from entry
+ * - `session_tree`: Navigated within tree
+ * - `session_before_switch`: Before switching (can cancel)
+ * - `session_before_fork`: Before creating fork (can cancel)
+ * - `session_before_tree`: Before tree navigation (can cancel)
+ * - `session_before_compact`: Before compaction (can cancel or provide custom)
+ * - `session_compact`: Completed compaction
+ * - `session_shutdown`: Session cleanup
+ *
+ * ## Error Handling
+ *
+ * **Transient Errors (auto-retry):**
+ * - Overloaded/rate limit errors
+ * - Server 5xx errors
+ * - Connection errors
+ * - Automatic exponential backoff + retry
+ *
+ * **Context Overflow (auto-compaction):**
+ * - Detected when LLM returns context limit error
+ * - Automatic summary generation
+ * - Old messages removed, new ones retry
+ *
+ * **Tool Errors:**
+ * - Validation errors (invalid input)
+ * - Execution errors (file not found, permission denied)
+ * - Timeout errors (bash commands)
+ * - Returned as tool results for LLM handling
+ *
+ * **Configuration Errors:**
+ * - No model selected → error on prompt()
+ * - No API key → error on prompt()
+ * - Extensions disabled → ignored, execution continues
+ *
+ * ## Performance Considerations
+ *
+ * - Tool output truncation prevents runaway memory usage
+ * - Bash output streamed via callbacks, not buffered
+ * - Large output written to temp files for later retrieval
+ * - Session messages indexed for fast lookup
+ * - Lazy-loading of extensions and hooks
+ *
+ * ## Security Notes
+ *
+ * - All bash commands execute in isolated subprocess
+ * - No shell injection: using spawn() not shell strings
+ * - File operations limited to working directory
+ * - Extensions loaded from trusted paths only
+ * - User input validated before LLM submission
+ *
+ * ## Implementation Status
+ *
+ * Based on: https://github.com/varunisrani/indusagi-ts/vendor/indusagi-agent/src/agent-loop.ts
+ * Modifications:
+ * - Extended with session persistence layer
+ * - Added extension system integration
+ * - Added hook system for customization
+ * - Added auto-compaction and auto-retry
+ * - Added branch summarization
+ * - Added command expansion and skill system
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isContextOverflow, modelsAreEqual, resetApiProviders, supportsXhigh } from "indusagi/ai";
+import { AgentEventObserveAdapter } from "../observe.js";
+import { getAgentDir, getDocsPath } from "../config.js";
+import { theme } from "../interfaces/terminal-ui/theme/theme.js";
+import { runObserveOperation } from "./observe.js";
+import { stripFrontmatter } from "../helpers/frontmatter.js";
+import { sleep } from "../helpers/sleep.js";
+import { executeBash as executeBashCommand, executeBashWithOperations } from "./bash-executor.js";
+import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./context-compression/index.js";
+import { exportSessionToHtml } from "./html-export/index.js";
+import { createToolHtmlRenderer } from "./html-export/tool-renderer.js";
+import { ExtensionRunner, wrapRegisteredTools, wrapToolsWithExtensions, } from "./plugins/index.js";
+import { expandPromptTemplate } from "./prompt-templates.js";
+import { buildSystemPrompt } from "./system-prompt.js";
+import { HookRunner } from "./lifecycle/index.js";
+import { createAllTools } from "./tooling/index.js";
+import { createMemory, createMemoryTools, DEFAULT_WORKING_MEMORY_TEMPLATE } from "./tooling/memory.js";
+import { SubagentStore } from "./subagents.js";
+import { createSessionTodoStore } from "./tooling/index.js";
+/**
+ * Parse a skill block from message text.
+ * Returns null if the text doesn't contain a skill block.
+ */
+export function parseSkillBlock(text) {
+    const match = text.match(/^<skill name="([^"]+)" location="([^"]+)">\n([\s\S]*?)\n<\/skill>(?:\n\n([\s\S]+))?$/);
+    if (!match)
+        return null;
+    return {
+        name: match[1],
+        location: match[2],
+        content: match[3],
+        userMessage: match[4]?.trim() || undefined,
+    };
+}
+// ============================================================================
+// Constants
+// ============================================================================
+/** Standard thinking levels */
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high"];
+/** Thinking levels including xhigh (for supported models) */
+const THINKING_LEVELS_WITH_XHIGH = ["off", "minimal", "low", "medium", "high", "xhigh"];
+// ============================================================================
+// AgentSession Class
+// ============================================================================
+export class AgentSession {
+    constructor(config) {
+        this._eventListeners = [];
+        /** Tracks pending steering messages for UI display. Removed when delivered. */
+        this._steeringMessages = [];
+        /** Tracks pending follow-up messages for UI display. Removed when delivered. */
+        this._followUpMessages = [];
+        /** Messages queued to be included with the next user prompt as context ("asides"). */
+        this._pendingNextTurnMessages = [];
+        // Compaction state
+        this._compactionAbortController = undefined;
+        this._autoCompactionAbortController = undefined;
+        // Branch summarization state
+        this._branchSummaryAbortController = undefined;
+        // Retry state
+        this._retryAbortController = undefined;
+        this._retryAttempt = 0;
+        this._retryPromise = undefined;
+        this._retryResolve = undefined;
+        // Bash execution state
+        this._bashAbortController = undefined;
+        this._pendingBashMessages = [];
+        // Extension system
+        this._extensionRunner = undefined;
+        this._hookRunner = undefined;
+        this._turnIndex = 0;
+        this._baseToolRegistry = new Map();
+        this._mcpTools = [];
+        this._memoryTools = [];
+        this._memoryThreadId = "";
+        this._memoryResourceId = "default-user";
+        // Tool registry for extension getTools/setTools
+        this._toolRegistry = new Map();
+        // Base system prompt (without extension appends) - used to apply fresh appends each turn
+        this._baseSystemPrompt = "";
+        // Track last assistant message for auto-compaction check
+        this._lastAssistantMessage = undefined;
+        /** Internal handler for agent events - shared by subscribe and reconnect */
+        this._handleAgentEvent = async (event) => {
+            this._consumeQueuedUserMessage(event);
+            if (event.type === "message_end" &&
+                event.message.role === "assistant" &&
+                this._hookRunner?.hasHandlers("experimental.text.complete")) {
+                for (const part of event.message.content) {
+                    if (part.type !== "text")
+                        continue;
+                    const output = { text: part.text };
+                    await this._hookRunner.trigger("experimental.text.complete", { sessionId: this.sessionId }, output);
+                    part.text = output.text;
+                }
+            }
+            // Emit to extensions first
+            await this._emitExtensionEvent(event);
+            // Notify all listeners
+            this._emit(event);
+            if (event.type === "message_end") {
+                this._persistCompletedMessage(event);
+            }
+            if (event.type === "agent_end" && this._lastAssistantMessage) {
+                const message = this._lastAssistantMessage;
+                this._lastAssistantMessage = undefined;
+                await this._handlePromptFlow(message);
+            }
+        };
+        this.agent = config.agent;
+        this.sessionManager = config.sessionManager;
+        this.settingsManager = config.settingsManager;
+        this._scopedModels = config.scopedModels ?? [];
+        this._resourceLoader = config.resourceLoader;
+        this._customTools = config.customTools ?? [];
+        this._cwd = config.cwd;
+        this._modelRegistry = config.modelRegistry;
+        this._agentDir = config.agentDir ?? getAgentDir();
+        this._todoStore = createSessionTodoStore({
+            sessionManager: this.sessionManager,
+            getSessionId: () => this.sessionId,
+        });
+        this._todoStore.rebuildFromBranch();
+        this._subagentStore = new SubagentStore({ cwd: this._cwd, agentDir: this._agentDir });
+        this._extensionRunnerRef = config.extensionRunnerRef;
+        this._hookRunnerRef = config.hookRunnerRef;
+        this._observe = config.observe;
+        this._initialActiveToolNames = config.initialActiveToolNames;
+        this._baseToolsOverride = config.baseToolsOverride;
+        this._wireAgentEventHandlers();
+        this._rebuildRuntimeState({
+            activeToolNames: this._initialActiveToolNames,
+            includeAllExtensionTools: true,
+        });
+    }
+    /** Model registry for API key resolution and model discovery */
+    get modelRegistry() {
+        return this._modelRegistry;
+    }
+    async initializeObserve() {
+        if (!this._observe)
+            return;
+        await this._observe.initializeSession(this._getObserveSessionSnapshot());
+        if (!this._observeAgentEventsUnsubscribe) {
+            const adapter = new AgentEventObserveAdapter({
+                sink: this._observe.sink,
+                includeMessageText: this._observe.captureAgentEventText,
+            });
+            this._observeAgentEventsUnsubscribe = adapter.attach(this.agent);
+        }
+        await this._observe.log({
+            sessionId: this.sessionId,
+            name: "session.initialize",
+            summary: "observe session initialized",
+            attributes: {
+                sessionFile: this.sessionFile,
+                activeToolCount: this.getActiveToolNames().length,
+            },
+        });
+    }
+    // =========================================================================
+    // Event Subscription
+    // =========================================================================
+    /** Emit an event to all listeners */
+    _emit(event) {
+        for (const l of this._eventListeners) {
+            l(event);
+        }
+    }
+    _wireAgentEventHandlers() {
+        this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
+    }
+    _rebuildRuntimeState(options) {
+        this._buildRuntime(options);
+    }
+    _rebuildTodoStore() {
+        this._todoStore.rebuildFromBranch();
+    }
+    _consumeQueuedUserMessage(event) {
+        if (event.type !== "message_start" || event.message.role !== "user") {
+            return;
+        }
+        const messageText = this._getUserMessageText(event.message);
+        if (!messageText) {
+            return;
+        }
+        const steeringIndex = this._steeringMessages.indexOf(messageText);
+        if (steeringIndex !== -1) {
+            this._steeringMessages.splice(steeringIndex, 1);
+            return;
+        }
+        const followUpIndex = this._followUpMessages.indexOf(messageText);
+        if (followUpIndex !== -1) {
+            this._followUpMessages.splice(followUpIndex, 1);
+        }
+    }
+    _persistCompletedMessage(event) {
+        if (event.message.role === "custom") {
+            this.sessionManager.appendCustomMessageEntry(event.message.customType, event.message.content, event.message.display, event.message.details);
+        }
+        else if (event.message.role === "user" ||
+            event.message.role === "assistant" ||
+            event.message.role === "toolResult") {
+            this.sessionManager.appendMessage(event.message);
+        }
+        if (event.message.role === "assistant") {
+            this._lastAssistantMessage = event.message;
+        }
+    }
+    async _handlePromptFlow(message) {
+        if (this._isRetryableError(message)) {
+            const didRetry = await this._handleRetryFlow(message);
+            if (didRetry) {
+                return;
+            }
+        }
+        else if (this._retryAttempt > 0) {
+            this._emit({ type: "auto_retry_end", success: true, attempt: this._retryAttempt });
+            this._retryAttempt = 0;
+            this._resolveRetry();
+        }
+        await this._handleCompactionFlow(message);
+    }
+    async _handleRetryFlow(message) {
+        return this._handleRetryableError(message);
+    }
+    async _handleCompactionFlow(message) {
+        await this._checkCompaction(message);
+    }
+    /** Resolve the pending retry promise */
+    _resolveRetry() {
+        if (this._retryResolve) {
+            this._retryResolve();
+            this._retryResolve = undefined;
+            this._retryPromise = undefined;
+        }
+    }
+    _getObserveSessionSnapshot() {
+        return {
+            id: this.sessionId,
+            cwd: this._cwd,
+            sessionFile: this.sessionFile,
+            model: this.model ? { provider: this.model.provider, id: this.model.id } : undefined,
+            activeToolNames: this.getActiveToolNames(),
+        };
+    }
+    async _refreshObserveSession() {
+        await this._observe?.initializeSession(this._getObserveSessionSnapshot());
+    }
+    async _endObserveSession(sessionId, status = "ended") {
+        await this._observe?.endSession(sessionId, status);
+    }
+    async _logObserve(options) {
+        await this._observe?.log({
+            sessionId: this.sessionId,
+            ...options,
+        });
+    }
+    async _runObserveOperation(name, kind, fn, options = {}) {
+        return runObserveOperation(this._observe, {
+            sessionId: this.sessionId,
+            name,
+            kind,
+            input: options.input,
+            attributes: {
+                sessionFile: this.sessionFile,
+                modelId: this.model?.id,
+                provider: this.model?.provider,
+                ...options.attributes,
+            },
+            output: options.output,
+        }, fn);
+    }
+    /** Extract text content from a message */
+    _getUserMessageText(message) {
+        if (message.role !== "user")
+            return "";
+        const content = message.content;
+        if (typeof content === "string")
+            return content;
+        const textBlocks = content.filter((c) => c.type === "text");
+        return textBlocks.map((c) => c.text).join("");
+    }
+    /** Find the last assistant message in agent state (including aborted ones) */
+    _findLastAssistantMessage() {
+        const messages = this.agent.state.messages;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            const msg = messages[i];
+            if (msg.role === "assistant") {
+                return msg;
+            }
+        }
+        return undefined;
+    }
+    /** Emit extension events based on agent events */
+    async _emitExtensionEvent(event) {
+        if (this._hookRunner?.hasHandlers("event")) {
+            await this._hookRunner.emitEvent(event);
+        }
+        if (!this._extensionRunner)
+            return;
+        if (event.type === "agent_start") {
+            this._turnIndex = 0;
+            await this._extensionRunner.emit({ type: "agent_start" });
+        }
+        else if (event.type === "agent_end") {
+            await this._extensionRunner.emit({ type: "agent_end", messages: event.messages });
+        }
+        else if (event.type === "turn_start") {
+            const extensionEvent = {
+                type: "turn_start",
+                turnIndex: this._turnIndex,
+                timestamp: Date.now(),
+            };
+            await this._extensionRunner.emit(extensionEvent);
+        }
+        else if (event.type === "turn_end") {
+            const extensionEvent = {
+                type: "turn_end",
+                turnIndex: this._turnIndex,
+                message: event.message,
+                toolResults: event.toolResults,
+            };
+            await this._extensionRunner.emit(extensionEvent);
+            // Process through memory (extract observations)
+            if (this._memory && event.message) {
+                this._processMemoryOutput(event.message).catch((err) => {
+                    console.warn("Memory output processing failed:", err);
+                });
+            }
+            this._turnIndex++;
+        }
+    }
+    /**
+     * Subscribe to agent events.
+     * Session persistence is handled internally (saves messages on message_end).
+     * Multiple listeners can be added. Returns unsubscribe function for this listener.
+     */
+    subscribe(listener) {
+        this._eventListeners.push(listener);
+        // Return unsubscribe function for this specific listener
+        return () => {
+            const index = this._eventListeners.indexOf(listener);
+            if (index !== -1) {
+                this._eventListeners.splice(index, 1);
+            }
+        };
+    }
+    /**
+     * Temporarily disconnect from agent events.
+     * User listeners are preserved and will receive events again after resubscribe().
+     * Used internally during operations that need to pause event processing.
+     */
+    _disconnectFromAgent() {
+        if (this._unsubscribeAgent) {
+            this._unsubscribeAgent();
+            this._unsubscribeAgent = undefined;
+        }
+    }
+    /**
+     * Reconnect to agent events after _disconnectFromAgent().
+     * Preserves all existing listeners.
+     */
+    _reconnectToAgent() {
+        if (this._unsubscribeAgent)
+            return; // Already connected
+        this._wireAgentEventHandlers();
+    }
+    /**
+     * Remove all listeners and disconnect from agent.
+     * Call this when completely done with the session.
+     */
+    dispose() {
+        this._disconnectFromAgent();
+        this._observeAgentEventsUnsubscribe?.();
+        this._observeAgentEventsUnsubscribe = undefined;
+        this._eventListeners = [];
+    }
+    // =========================================================================
+    // Read-only State Access
+    // =========================================================================
+    /** Full agent state */
+    get state() {
+        return this.agent.state;
+    }
+    /** Current model (may be undefined if not yet selected) */
+    get model() {
+        return this.agent.state.model;
+    }
+    /** Current thinking level */
+    get thinkingLevel() {
+        return this.agent.state.thinkingLevel;
+    }
+    /** Whether agent is currently streaming a response */
+    get isStreaming() {
+        return this.agent.state.isStreaming;
+    }
+    /** Current retry attempt (0 if not retrying) */
+    get retryAttempt() {
+        return this._retryAttempt;
+    }
+    /**
+     * Get the names of currently active tools.
+     * Returns the names of tools currently set on the agent.
+     */
+    getActiveToolNames() {
+        return this.agent.state.tools.map((t) => t.name);
+    }
+    /**
+     * Get all configured tools with name and description.
+     */
+    getAllTools() {
+        return Array.from(this._toolRegistry.values()).map((t) => ({
+            name: t.name,
+            description: t.description,
+        }));
+    }
+    /**
+     * Set active tools by name.
+     * Only tools in the registry can be enabled. Unknown tool names are ignored.
+     * Also rebuilds the system prompt to reflect the new tool set.
+     * Changes take effect on the next agent turn.
+     */
+    setActiveToolsByName(toolNames) {
+        const tools = [];
+        const validToolNames = [];
+        for (const name of toolNames) {
+            const tool = this._toolRegistry.get(name);
+            if (tool) {
+                tools.push(tool);
+                validToolNames.push(name);
+            }
+        }
+        this.agent.setTools(tools);
+        // Rebuild base system prompt with new tool set
+        this._baseSystemPrompt = this._rebuildSystemPrompt(validToolNames);
+        this.agent.setSystemPrompt(this._baseSystemPrompt);
+    }
+    /** Whether auto-compaction is currently running */
+    get isCompacting() {
+        return this._autoCompactionAbortController !== undefined || this._compactionAbortController !== undefined;
+    }
+    /** All messages including custom types like BashExecutionMessage */
+    get messages() {
+        return this.agent.state.messages;
+    }
+    /** Current steering mode */
+    get steeringMode() {
+        return this.agent.getSteeringMode();
+    }
+    /** Current follow-up mode */
+    get followUpMode() {
+        return this.agent.getFollowUpMode();
+    }
+    /** Current session file path, or undefined if sessions are disabled */
+    get sessionFile() {
+        return this.sessionManager.getSessionFile();
+    }
+    /** Current session ID */
+    get sessionId() {
+        return this.sessionManager.getSessionId();
+    }
+    getSessionId() {
+        return this.sessionId;
+    }
+    getTree() {
+        return this.sessionManager.getTree();
+    }
+    /** Scoped models for cycling (from --models flag) */
+    get scopedModels() {
+        return this._scopedModels;
+    }
+    /** Update scoped models for cycling */
+    setScopedModels(scopedModels) {
+        this._scopedModels = scopedModels;
+    }
+    /** File-based prompt templates */
+    get promptTemplates() {
+        return this._resourceLoader.getPrompts().prompts;
+    }
+    _rebuildSystemPrompt(toolNames) {
+        const validToolNames = toolNames.filter((name) => this._baseToolRegistry.has(name));
+        const loaderSystemPrompt = this._resourceLoader.getSystemPrompt();
+        const loaderAppendSystemPrompt = this._resourceLoader.getAppendSystemPrompt();
+        const appendSystemPrompt = loaderAppendSystemPrompt.length > 0 ? loaderAppendSystemPrompt.join("\n\n") : undefined;
+        const loadedSkills = this._resourceLoader.getSkills().skills;
+        const loadedContextFiles = this._resourceLoader.getAgentsFiles().agentsFiles;
+        return buildSystemPrompt({
+            cwd: this._cwd,
+            skills: loadedSkills,
+            contextFiles: loadedContextFiles,
+            customPrompt: loaderSystemPrompt,
+            appendSystemPrompt,
+            selectedTools: validToolNames,
+            subagents: this._subagentStore.list(),
+        });
+    }
+    // =========================================================================
+    // Prompting
+    // =========================================================================
+    /**
+     * Send a prompt to the agent.
+     * - Handles extension commands (registered via indusagi.registerCommand) immediately, even during streaming
+     * - Expands file-based prompt templates by default
+     * - During streaming, queues via steer() or followUp() based on streamingBehavior option
+     * - Validates model and API key before sending (when not streaming)
+     * @throws Error if streaming and no streamingBehavior specified
+     * @throws Error if no model selected or no API key available (when not streaming)
+     */
+    async prompt(text, options) {
+        const expandPromptTemplates = options?.expandPromptTemplates ?? true;
+        // Handle extension commands first (execute immediately, even during streaming)
+        // Extension commands manage their own LLM interaction via indusagi.sendMessage()
+        if (expandPromptTemplates && text.startsWith("/")) {
+            const handled = await this._tryExecuteExtensionCommand(text);
+            if (handled) {
+                // Extension command executed, no prompt to send
+                return;
+            }
+        }
+        // Emit input event for extension interception (before skill/template expansion)
+        let currentText = text;
+        let currentImages = options?.images;
+        if (this._extensionRunner?.hasHandlers("input")) {
+            const inputResult = await this._extensionRunner.emitInput(currentText, currentImages, options?.source ?? "interactive");
+            if (inputResult.action === "handled") {
+                return;
+            }
+            if (inputResult.action === "transform") {
+                currentText = inputResult.text;
+                currentImages = inputResult.images ?? currentImages;
+            }
+        }
+        // Expand skill commands (/skill:name args) and prompt templates (/template args)
+        let expandedText = currentText;
+        if (expandPromptTemplates) {
+            expandedText = this._expandSkillCommand(expandedText);
+            expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
+        }
+        // If streaming, queue via steer() or followUp() based on option
+        if (this.isStreaming) {
+            if (!options?.streamingBehavior) {
+                throw new Error("Agent is already processing. Specify streamingBehavior ('steer' or 'followUp') to queue the message.");
+            }
+            if (options.streamingBehavior === "followUp") {
+                await this._queueFollowUp(expandedText);
+            }
+            else {
+                await this._queueSteer(expandedText);
+            }
+            return;
+        }
+        // Flush any pending bash messages before the new prompt
+        this._flushPendingBashMessages();
+        // Validate model
+        if (!this.model) {
+            throw new Error("No model selected.\n\n" +
+                `Use /login or set an API key environment variable. See ${join(getDocsPath(), "authentication.md")}\n\n` +
+                "Then use /model to select a model.");
+        }
+        // Validate API key
+        const apiKey = await this._modelRegistry.getApiKey(this.model);
+        if (!apiKey) {
+            const isOAuth = this._modelRegistry.isUsingOAuth(this.model);
+            if (isOAuth) {
+                throw new Error(`Authentication failed for "${this.model.provider}". ` +
+                    `Credentials may have expired or network is unavailable. ` +
+                    `Run '/login ${this.model.provider}' to re-authenticate.`);
+            }
+            throw new Error(`No API key found for ${this.model.provider}.\n\n` +
+                `Use /login or set an API key environment variable. See ${join(getDocsPath(), "authentication.md")}`);
+        }
+        // Check if we need to compact before sending (catches aborted responses)
+        const lastAssistant = this._findLastAssistantMessage();
+        if (lastAssistant) {
+            await this._checkCompaction(lastAssistant, false);
+        }
+        // Build messages array (custom message if any, then user message)
+        const messages = [];
+        // Add user message
+        let userContent = [{ type: "text", text: expandedText }];
+        if (currentImages) {
+            userContent.push(...currentImages);
+        }
+        if (this._hookRunner?.hasHandlers("chat.message")) {
+            const output = { content: userContent };
+            await this._hookRunner.trigger("chat.message", { sessionId: this.sessionId, model: this.model }, output);
+            userContent = output.content;
+            const updatedTextParts = userContent
+                .filter((part) => part.type === "text")
+                .map((part) => part.text);
+            const updatedImages = userContent.filter((part) => part.type === "image");
+            expandedText = updatedTextParts.join("\n");
+            currentImages = updatedImages.length > 0 ? updatedImages : undefined;
+        }
+        messages.push({
+            role: "user",
+            content: userContent,
+            timestamp: Date.now(),
+        });
+        // Inject any pending "nextTurn" messages as context alongside the user message
+        for (const msg of this._pendingNextTurnMessages) {
+            messages.push(msg);
+        }
+        this._pendingNextTurnMessages = [];
+        // Emit before_agent_start extension event
+        if (this._extensionRunner) {
+            const result = await this._extensionRunner.emitBeforeAgentStart(expandedText, currentImages, this._baseSystemPrompt);
+            // Add all custom messages from extensions
+            if (result?.messages) {
+                for (const msg of result.messages) {
+                    messages.push({
+                        role: "custom",
+                        customType: msg.customType,
+                        content: msg.content,
+                        display: msg.display,
+                        details: msg.details,
+                        timestamp: Date.now(),
+                    });
+                }
+            }
+            // Apply extension-modified system prompt, or reset to base
+            if (result?.systemPrompt) {
+                this.agent.setSystemPrompt(result.systemPrompt);
+            }
+            else {
+                // Ensure we're using the base prompt (in case previous turn had modifications)
+                this.agent.setSystemPrompt(this._baseSystemPrompt);
+            }
+        }
+        await this._logObserve({
+            name: "session.prompt",
+            summary: "prompt submitted to agent",
+            attributes: {
+                textLength: expandedText.length,
+                imageCount: currentImages?.length ?? 0,
+                pendingNextTurnMessages: messages.length - 1,
+            },
+            data: {
+                imageCount: currentImages?.length ?? 0,
+            },
+        });
+        await this.agent.prompt(messages);
+        await this.waitForRetry();
+        await this._refreshObserveSession();
+    }
+    /**
+     * Try to execute an extension command. Returns true if command was found and executed.
+     */
+    async _tryExecuteExtensionCommand(text) {
+        if (!this._extensionRunner)
+            return false;
+        // Parse command name and args
+        const spaceIndex = text.indexOf(" ");
+        const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+        const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1);
+        const command = this._extensionRunner.getCommand(commandName);
+        if (!command)
+            return false;
+        // Get command context from extension runner (includes session control methods)
+        const ctx = this._extensionRunner.createCommandContext();
+        try {
+            let commandArgs = args;
+            if (this._hookRunner?.hasHandlers("command.execute.before")) {
+                const output = { args: commandArgs };
+                await this._hookRunner.trigger("command.execute.before", { sessionId: this.sessionId, command: commandName, args: commandArgs }, output);
+                commandArgs = output.args;
+            }
+            await command.handler(commandArgs, ctx);
+            return true;
+        }
+        catch (err) {
+            // Emit error via extension runner
+            this._extensionRunner.emitError({
+                extensionPath: `command:${commandName}`,
+                event: "command",
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return true;
+        }
+    }
+    /**
+     * Expand skill commands (/skill:name args) to their full content.
+     * Returns the expanded text, or the original text if not a skill command or skill not found.
+     * Emits errors via extension runner if file read fails.
+     */
+    _expandSkillCommand(text) {
+        if (!text.startsWith("/skill:"))
+            return text;
+        const spaceIndex = text.indexOf(" ");
+        const skillName = spaceIndex === -1 ? text.slice(7) : text.slice(7, spaceIndex);
+        const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1).trim();
+        const skill = this.resourceLoader.getSkills().skills.find((s) => s.name === skillName);
+        if (!skill)
+            return text; // Unknown skill, pass through
+        try {
+            const content = readFileSync(skill.filePath, "utf-8");
+            const body = stripFrontmatter(content).trim();
+            const skillBlock = `<skill name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${skill.baseDir}.\n\n${body}\n</skill>`;
+            return args ? `${skillBlock}\n\n${args}` : skillBlock;
+        }
+        catch (err) {
+            // Emit error like extension commands do
+            this._extensionRunner?.emitError({
+                extensionPath: skill.filePath,
+                event: "skill_expansion",
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return text; // Return original on error
+        }
+    }
+    /**
+     * Queue a steering message to interrupt the agent mid-run.
+     * Delivered after current tool execution, skips remaining tools.
+     * Expands skill commands and prompt templates. Errors on extension commands.
+     * @throws Error if text is an extension command
+     */
+    async steer(text) {
+        // Check for extension commands (cannot be queued)
+        if (text.startsWith("/")) {
+            this._throwIfExtensionCommand(text);
+        }
+        // Expand skill commands and prompt templates
+        let expandedText = this._expandSkillCommand(text);
+        expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
+        await this._queueSteer(expandedText);
+    }
+    /**
+     * Queue a follow-up message to be processed after the agent finishes.
+     * Delivered only when agent has no more tool calls or steering messages.
+     * Expands skill commands and prompt templates. Errors on extension commands.
+     * @throws Error if text is an extension command
+     */
+    async followUp(text) {
+        // Check for extension commands (cannot be queued)
+        if (text.startsWith("/")) {
+            this._throwIfExtensionCommand(text);
+        }
+        // Expand skill commands and prompt templates
+        let expandedText = this._expandSkillCommand(text);
+        expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
+        await this._queueFollowUp(expandedText);
+    }
+    /**
+     * Internal: Queue a steering message (already expanded, no extension command check).
+     */
+    async _queueSteer(text) {
+        this._steeringMessages.push(text);
+        this.agent.steer({
+            role: "user",
+            content: [{ type: "text", text }],
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Internal: Queue a follow-up message (already expanded, no extension command check).
+     */
+    async _queueFollowUp(text) {
+        this._followUpMessages.push(text);
+        this.agent.followUp({
+            role: "user",
+            content: [{ type: "text", text }],
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Throw an error if the text is an extension command.
+     */
+    _throwIfExtensionCommand(text) {
+        if (!this._extensionRunner)
+            return;
+        const spaceIndex = text.indexOf(" ");
+        const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+        const command = this._extensionRunner.getCommand(commandName);
+        if (command) {
+            throw new Error(`Extension command "/${commandName}" cannot be queued. Use prompt() or execute the command when not streaming.`);
+        }
+    }
+    /**
+     * Send a custom message to the session. Creates a CustomMessageEntry.
+     *
+     * Handles three cases:
+     * - Streaming: queues message, processed when loop pulls from queue
+     * - Not streaming + triggerTurn: appends to state/session, starts new turn
+     * - Not streaming + no trigger: appends to state/session, no turn
+     *
+     * @param message Custom message with customType, content, display, details
+     * @param options.triggerTurn If true and not streaming, triggers a new LLM turn
+     * @param options.deliverAs Delivery mode: "steer", "followUp", or "nextTurn"
+     */
+    async sendCustomMessage(message, options) {
+        const appMessage = {
+            role: "custom",
+            customType: message.customType,
+            content: message.content,
+            display: message.display,
+            details: message.details,
+            timestamp: Date.now(),
+        };
+        if (options?.deliverAs === "nextTurn") {
+            this._pendingNextTurnMessages.push(appMessage);
+        }
+        else if (this.isStreaming) {
+            if (options?.deliverAs === "followUp") {
+                this.agent.followUp(appMessage);
+            }
+            else {
+                this.agent.steer(appMessage);
+            }
+        }
+        else if (options?.triggerTurn) {
+            await this.agent.prompt(appMessage);
+        }
+        else {
+            this.agent.appendMessage(appMessage);
+            this.sessionManager.appendCustomMessageEntry(message.customType, message.content, message.display, message.details);
+            this._emit({ type: "message_start", message: appMessage });
+            this._emit({ type: "message_end", message: appMessage });
+        }
+    }
+    /**
+     * Send a user message to the agent. Always triggers a turn.
+     * When the agent is streaming, use deliverAs to specify how to queue the message.
+     *
+     * @param content User message content (string or content array)
+     * @param options.deliverAs Delivery mode when streaming: "steer" or "followUp"
+     */
+    async sendUserMessage(content, options) {
+        // Normalize content to text string + optional images
+        let text;
+        let images;
+        if (typeof content === "string") {
+            text = content;
+        }
+        else {
+            const textParts = [];
+            images = [];
+            for (const part of content) {
+                if (part.type === "text") {
+                    textParts.push(part.text);
+                }
+                else {
+                    images.push(part);
+                }
+            }
+            text = textParts.join("\n");
+            if (images.length === 0)
+                images = undefined;
+        }
+        // Use prompt() with expandPromptTemplates: false to skip command handling and template expansion
+        await this.prompt(text, {
+            expandPromptTemplates: false,
+            streamingBehavior: options?.deliverAs,
+            images,
+            source: "extension",
+        });
+    }
+    /**
+     * Clear all queued messages and return them.
+     * Useful for restoring to editor when user aborts.
+     * @returns Object with steering and followUp arrays
+     */
+    clearQueue() {
+        const steering = [...this._steeringMessages];
+        const followUp = [...this._followUpMessages];
+        this._steeringMessages = [];
+        this._followUpMessages = [];
+        this.agent.clearAllQueues();
+        return { steering, followUp };
+    }
+    /** Number of pending messages (includes both steering and follow-up) */
+    get pendingMessageCount() {
+        return this._steeringMessages.length + this._followUpMessages.length;
+    }
+    /** Get pending steering messages (read-only) */
+    getSteeringMessages() {
+        return this._steeringMessages;
+    }
+    /** Get pending follow-up messages (read-only) */
+    getFollowUpMessages() {
+        return this._followUpMessages;
+    }
+    get resourceLoader() {
+        return this._resourceLoader;
+    }
+    /**
+     * Abort current operation and wait for agent to become idle.
+     */
+    async abort() {
+        this.abortRetry();
+        this.agent.abort();
+        await this.agent.waitForIdle();
+    }
+    /**
+     * Start a new session, optionally with initial messages and parent tracking.
+     * Clears all messages and starts a new session.
+     * Listeners are preserved and will continue receiving events.
+     * @param options - Optional initial messages and parent session path
+     * @returns true if completed, false if cancelled by extension
+     */
+    async newSession(options) {
+        return this._runObserveOperation("session.new", "session_switch", async () => {
+            const previousSessionFile = this.sessionFile;
+            const previousSessionId = this.sessionId;
+            // Emit session_before_switch event with reason "new" (can be cancelled)
+            if (this._extensionRunner?.hasHandlers("session_before_switch")) {
+                const result = (await this._extensionRunner.emit({
+                    type: "session_before_switch",
+                    reason: "new",
+                }));
+                if (result?.cancel) {
+                    return false;
+                }
+            }
+            this._disconnectFromAgent();
+            await this.abort();
+            this.agent.reset();
+            this.sessionManager.newSession(options);
+            this._rebuildTodoStore();
+            this.agent.sessionId = this.sessionManager.getSessionId();
+            this._memoryThreadId = this.sessionManager.getSessionId();
+            this._steeringMessages = [];
+            this._followUpMessages = [];
+            this._pendingNextTurnMessages = [];
+            this._reconnectToAgent();
+            await this._endObserveSession(previousSessionId);
+            await this._refreshObserveSession();
+            await this._logObserve({
+                name: "session.new",
+                summary: "created new session",
+                attributes: {
+                    previousSessionId,
+                    previousSessionFile,
+                },
+            });
+            // Emit session_switch event with reason "new" to extensions
+            if (this._extensionRunner) {
+                await this._extensionRunner.emit({
+                    type: "session_switch",
+                    reason: "new",
+                    previousSessionFile,
+                });
+            }
+            return true;
+        }, {
+            attributes: {
+                previousSessionFile: this.sessionFile,
+            },
+            output: (completed) => ({ completed }),
+        });
+    }
+    // =========================================================================
+    // Model Management
+    // =========================================================================
+    async _emitModelSelect(nextModel, previousModel, source) {
+        if (!this._extensionRunner)
+            return;
+        if (modelsAreEqual(previousModel, nextModel))
+            return;
+        await this._extensionRunner.emit({
+            type: "model_select",
+            model: nextModel,
+            previousModel,
+            source,
+        });
+    }
+    /**
+     * Set model directly.
+     * Validates API key, saves to session and settings.
+     * @throws Error if no API key available for the model
+     */
+    async setModel(model) {
+        const apiKey = await this._modelRegistry.getApiKey(model);
+        if (!apiKey) {
+            throw new Error(`No API key for ${model.provider}/${model.id}`);
+        }
+        const previousModel = this.model;
+        this.agent.setModel(model);
+        this.sessionManager.appendModelChange(model.provider, model.id);
+        this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);
+        // Re-clamp thinking level for new model's capabilities
+        this.setThinkingLevel(this.thinkingLevel);
+        await this._emitModelSelect(model, previousModel, "set");
+    }
+    /**
+     * Cycle to next/previous model.
+     * Uses scoped models (from --models flag) if available, otherwise all available models.
+     * @param direction - "forward" (default) or "backward"
+     * @returns The new model info, or undefined if only one model available
+     */
+    async cycleModel(direction = "forward") {
+        if (this._scopedModels.length > 0) {
+            return this._cycleScopedModel(direction);
+        }
+        return this._cycleAvailableModel(direction);
+    }
+    async _cycleScopedModel(direction) {
+        if (this._scopedModels.length <= 1)
+            return undefined;
+        const currentModel = this.model;
+        let currentIndex = this._scopedModels.findIndex((sm) => modelsAreEqual(sm.model, currentModel));
+        if (currentIndex === -1)
+            currentIndex = 0;
+        const len = this._scopedModels.length;
+        const nextIndex = direction === "forward" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;
+        const next = this._scopedModels[nextIndex];
+        // Validate API key
+        const apiKey = await this._modelRegistry.getApiKey(next.model);
+        if (!apiKey) {
+            throw new Error(`No API key for ${next.model.provider}/${next.model.id}`);
+        }
+        // Apply model
+        this.agent.setModel(next.model);
+        this.sessionManager.appendModelChange(next.model.provider, next.model.id);
+        this.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id);
+        // Apply thinking level (setThinkingLevel clamps to model capabilities)
+        this.setThinkingLevel(next.thinkingLevel);
+        await this._emitModelSelect(next.model, currentModel, "cycle");
+        return { model: next.model, thinkingLevel: this.thinkingLevel, isScoped: true };
+    }
+    async _cycleAvailableModel(direction) {
+        const availableModels = await this._modelRegistry.getAvailable();
+        if (availableModels.length <= 1)
+            return undefined;
+        const currentModel = this.model;
+        let currentIndex = availableModels.findIndex((m) => modelsAreEqual(m, currentModel));
+        if (currentIndex === -1)
+            currentIndex = 0;
+        const len = availableModels.length;
+        const nextIndex = direction === "forward" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;
+        const nextModel = availableModels[nextIndex];
+        const apiKey = await this._modelRegistry.getApiKey(nextModel);
+        if (!apiKey) {
+            throw new Error(`No API key for ${nextModel.provider}/${nextModel.id}`);
+        }
+        this.agent.setModel(nextModel);
+        this.sessionManager.appendModelChange(nextModel.provider, nextModel.id);
+        this.settingsManager.setDefaultModelAndProvider(nextModel.provider, nextModel.id);
+        // Re-clamp thinking level for new model's capabilities
+        this.setThinkingLevel(this.thinkingLevel);
+        await this._emitModelSelect(nextModel, currentModel, "cycle");
+        return { model: nextModel, thinkingLevel: this.thinkingLevel, isScoped: false };
+    }
+    // =========================================================================
+    // Thinking Level Management
+    // =========================================================================
+    /**
+     * Set thinking level.
+     * Clamps to model capabilities based on available thinking levels.
+     * Saves to session and settings.
+     */
+    setThinkingLevel(level) {
+        const availableLevels = this.getAvailableThinkingLevels();
+        const effectiveLevel = availableLevels.includes(level) ? level : this._clampThinkingLevel(level, availableLevels);
+        this.agent.setThinkingLevel(effectiveLevel);
+        this.sessionManager.appendThinkingLevelChange(effectiveLevel);
+        this.settingsManager.setDefaultThinkingLevel(effectiveLevel);
+    }
+    /**
+     * Cycle to next thinking level.
+     * @returns New level, or undefined if model doesn't support thinking
+     */
+    cycleThinkingLevel() {
+        if (!this.supportsThinking())
+            return undefined;
+        const levels = this.getAvailableThinkingLevels();
+        const currentIndex = levels.indexOf(this.thinkingLevel);
+        const nextIndex = (currentIndex + 1) % levels.length;
+        const nextLevel = levels[nextIndex];
+        this.setThinkingLevel(nextLevel);
+        return nextLevel;
+    }
+    /**
+     * Get available thinking levels for current model.
+     * The provider will clamp to what the specific model supports internally.
+     */
+    getAvailableThinkingLevels() {
+        if (!this.supportsThinking())
+            return ["off"];
+        return this.supportsXhighThinking() ? THINKING_LEVELS_WITH_XHIGH : THINKING_LEVELS;
+    }
+    /**
+     * Check if current model supports xhigh thinking level.
+     */
+    supportsXhighThinking() {
+        return this.model ? supportsXhigh(this.model) : false;
+    }
+    /**
+     * Check if current model supports thinking/reasoning.
+     */
+    supportsThinking() {
+        return !!this.model?.reasoning;
+    }
+    _clampThinkingLevel(level, availableLevels) {
+        const ordered = THINKING_LEVELS_WITH_XHIGH;
+        const available = new Set(availableLevels);
+        const requestedIndex = ordered.indexOf(level);
+        if (requestedIndex === -1) {
+            return availableLevels[0] ?? "off";
+        }
+        for (let i = requestedIndex; i < ordered.length; i++) {
+            const candidate = ordered[i];
+            if (available.has(candidate))
+                return candidate;
+        }
+        for (let i = requestedIndex - 1; i >= 0; i--) {
+            const candidate = ordered[i];
+            if (available.has(candidate))
+                return candidate;
+        }
+        return availableLevels[0] ?? "off";
+    }
+    // =========================================================================
+    // Queue Mode Management
+    // =========================================================================
+    /**
+     * Set steering message mode.
+     * Saves to settings.
+     */
+    setSteeringMode(mode) {
+        this.agent.setSteeringMode(mode);
+        this.settingsManager.setSteeringMode(mode);
+    }
+    /**
+     * Set follow-up message mode.
+     * Saves to settings.
+     */
+    setFollowUpMode(mode) {
+        this.agent.setFollowUpMode(mode);
+        this.settingsManager.setFollowUpMode(mode);
+    }
+    // =========================================================================
+    // Compaction
+    // =========================================================================
+    /**
+     * Manually compact the session context.
+     * Aborts current agent operation first.
+     * @param customInstructions Optional instructions for the compaction summary
+     */
+    async compact(customInstructions) {
+        this._disconnectFromAgent();
+        await this.abort();
+        this._compactionAbortController = new AbortController();
+        try {
+            if (!this.model) {
+                throw new Error("No model selected");
+            }
+            const apiKey = await this._modelRegistry.getApiKey(this.model);
+            if (!apiKey) {
+                throw new Error(`No API key for ${this.model.provider}`);
+            }
+            const pathEntries = this.sessionManager.getBranch();
+            const settings = this.settingsManager.getCompactionSettings();
+            const preparation = prepareCompaction(pathEntries, settings);
+            if (!preparation) {
+                // Check why we can't compact
+                const lastEntry = pathEntries[pathEntries.length - 1];
+                if (lastEntry?.type === "compaction") {
+                    throw new Error("Already compacted");
+                }
+                throw new Error("Nothing to compact (session too small)");
+            }
+            let extensionCompaction;
+            let fromExtension = false;
+            if (this._extensionRunner?.hasHandlers("session_before_compact")) {
+                const result = (await this._extensionRunner.emit({
+                    type: "session_before_compact",
+                    preparation,
+                    branchEntries: pathEntries,
+                    customInstructions,
+                    signal: this._compactionAbortController.signal,
+                }));
+                if (result?.cancel) {
+                    throw new Error("Compaction cancelled");
+                }
+                if (result?.compaction) {
+                    extensionCompaction = result.compaction;
+                    fromExtension = true;
+                }
+            }
+            let hookPrompt;
+            let hookContext = [];
+            if (!extensionCompaction && this._hookRunner?.hasHandlers("experimental.session.compacting")) {
+                const output = { context: [], prompt: undefined };
+                await this._hookRunner.trigger("experimental.session.compacting", { sessionId: this.sessionId }, output);
+                hookContext = output.context;
+                hookPrompt = output.prompt;
+            }
+            const combinedInstructions = [customInstructions, ...hookContext].filter(Boolean).join("\n\n");
+            const resolvedInstructions = combinedInstructions.length > 0 ? combinedInstructions : undefined;
+            let summary;
+            let firstKeptEntryId;
+            let tokensBefore;
+            let details;
+            if (extensionCompaction) {
+                // Extension provided compaction content
+                summary = extensionCompaction.summary;
+                firstKeptEntryId = extensionCompaction.firstKeptEntryId;
+                tokensBefore = extensionCompaction.tokensBefore;
+                details = extensionCompaction.details;
+            }
+            else {
+                // Generate compaction result
+                const result = await compact(preparation, this.model, apiKey, resolvedInstructions, this._compactionAbortController.signal, hookPrompt);
+                summary = result.summary;
+                firstKeptEntryId = result.firstKeptEntryId;
+                tokensBefore = result.tokensBefore;
+                details = result.details;
+            }
+            if (this._compactionAbortController.signal.aborted) {
+                throw new Error("Compaction cancelled");
+            }
+            this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension);
+            const newEntries = this.sessionManager.getEntries();
+            const sessionContext = this.sessionManager.buildSessionContext();
+            this.agent.replaceMessages(sessionContext.messages);
+            // Get the saved compaction entry for the extension event
+            const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
+            if (this._extensionRunner && savedCompactionEntry) {
+                await this._extensionRunner.emit({
+                    type: "session_compact",
+                    compactionEntry: savedCompactionEntry,
+                    fromExtension,
+                });
+            }
+            return {
+                summary,
+                firstKeptEntryId,
+                tokensBefore,
+                details,
+            };
+        }
+        finally {
+            this._compactionAbortController = undefined;
+            this._reconnectToAgent();
+        }
+    }
+    /**
+     * Cancel in-progress compaction (manual or auto).
+     */
+    abortCompaction() {
+        this._compactionAbortController?.abort();
+        this._autoCompactionAbortController?.abort();
+    }
+    /**
+     * Cancel in-progress branch summarization.
+     */
+    abortBranchSummary() {
+        this._branchSummaryAbortController?.abort();
+    }
+    /**
+     * Check if compaction is needed and run it.
+     * Called after agent_end and before prompt submission.
+     *
+     * Two cases:
+     * 1. Overflow: LLM returned context overflow error, remove error message from agent state, compact, auto-retry
+     * 2. Threshold: Context over threshold, compact, NO auto-retry (user continues manually)
+     *
+     * @param assistantMessage The assistant message to check
+     * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
+     */
+    async _checkCompaction(assistantMessage, skipAbortedCheck = true) {
+        const settings = this.settingsManager.getCompactionSettings();
+        if (!settings.enabled)
+            return;
+        // Skip if message was aborted (user cancelled) - unless skipAbortedCheck is false
+        if (skipAbortedCheck && assistantMessage.stopReason === "aborted")
+            return;
+        const contextWindow = this.model?.contextWindow ?? 0;
+        // Skip overflow check if the message came from a different model.
+        // This handles the case where user switched from a smaller-context model (e.g. opus)
+        // to a larger-context model (e.g. codex) - the overflow error from the old model
+        // shouldn't trigger compaction for the new model.
+        const sameModel = this.model && assistantMessage.provider === this.model.provider && assistantMessage.model === this.model.id;
+        // Skip overflow check if the error is from before a compaction in the current path.
+        // This handles the case where an error was kept after compaction (in the "kept" region).
+        // The error shouldn't trigger another compaction since we already compacted.
+        // Example: opus fails → switch to codex → compact → switch back to opus → opus error
+        // is still in context but shouldn't trigger compaction again.
+        const compactionEntry = this.sessionManager.getBranch().find((e) => e.type === "compaction");
+        const errorIsFromBeforeCompaction = compactionEntry && assistantMessage.timestamp < new Date(compactionEntry.timestamp).getTime();
+        // Case 1: Overflow - LLM returned context overflow error
+        if (sameModel && !errorIsFromBeforeCompaction && isContextOverflow(assistantMessage, contextWindow)) {
+            // Remove the error message from agent state (it IS saved to session for history,
+            // but we don't want it in context for the retry)
+            const messages = this.agent.state.messages;
+            if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
+                this.agent.replaceMessages(messages.slice(0, -1));
+            }
+            await this._runAutoCompaction("overflow", true);
+            return;
+        }
+        // Case 2: Threshold - turn succeeded but context is getting large
+        // Skip if this was an error (non-overflow errors don't have usage data)
+        if (assistantMessage.stopReason === "error")
+            return;
+        const contextTokens = calculateContextTokens(assistantMessage.usage);
+        if (shouldCompact(contextTokens, contextWindow, settings)) {
+            await this._runAutoCompaction("threshold", false);
+        }
+    }
+    /**
+     * Internal: Run auto-compaction with events.
+     */
+    async _runAutoCompaction(reason, willRetry) {
+        const settings = this.settingsManager.getCompactionSettings();
+        this._emit({ type: "auto_compaction_start", reason });
+        this._autoCompactionAbortController = new AbortController();
+        try {
+            if (!this.model) {
+                this._emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false });
+                return;
+            }
+            const apiKey = await this._modelRegistry.getApiKey(this.model);
+            if (!apiKey) {
+                this._emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false });
+                return;
+            }
+            const pathEntries = this.sessionManager.getBranch();
+            const preparation = prepareCompaction(pathEntries, settings);
+            if (!preparation) {
+                this._emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false });
+                return;
+            }
+            let extensionCompaction;
+            let fromExtension = false;
+            if (this._extensionRunner?.hasHandlers("session_before_compact")) {
+                const extensionResult = (await this._extensionRunner.emit({
+                    type: "session_before_compact",
+                    preparation,
+                    branchEntries: pathEntries,
+                    customInstructions: undefined,
+                    signal: this._autoCompactionAbortController.signal,
+                }));
+                if (extensionResult?.cancel) {
+                    this._emit({ type: "auto_compaction_end", result: undefined, aborted: true, willRetry: false });
+                    return;
+                }
+                if (extensionResult?.compaction) {
+                    extensionCompaction = extensionResult.compaction;
+                    fromExtension = true;
+                }
+            }
+            let hookPrompt;
+            let hookContext = [];
+            if (!extensionCompaction && this._hookRunner?.hasHandlers("experimental.session.compacting")) {
+                const output = { context: [], prompt: undefined };
+                await this._hookRunner.trigger("experimental.session.compacting", { sessionId: this.sessionId }, output);
+                hookContext = output.context;
+                hookPrompt = output.prompt;
+            }
+            const resolvedInstructions = hookContext.length > 0 ? hookContext.join("\n\n") : undefined;
+            let summary;
+            let firstKeptEntryId;
+            let tokensBefore;
+            let details;
+            if (extensionCompaction) {
+                // Extension provided compaction content
+                summary = extensionCompaction.summary;
+                firstKeptEntryId = extensionCompaction.firstKeptEntryId;
+                tokensBefore = extensionCompaction.tokensBefore;
+                details = extensionCompaction.details;
+            }
+            else {
+                // Generate compaction result
+                const compactResult = await compact(preparation, this.model, apiKey, resolvedInstructions, this._autoCompactionAbortController.signal, hookPrompt);
+                summary = compactResult.summary;
+                firstKeptEntryId = compactResult.firstKeptEntryId;
+                tokensBefore = compactResult.tokensBefore;
+                details = compactResult.details;
+            }
+            if (this._autoCompactionAbortController.signal.aborted) {
+                this._emit({ type: "auto_compaction_end", result: undefined, aborted: true, willRetry: false });
+                return;
+            }
+            this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension);
+            const newEntries = this.sessionManager.getEntries();
+            const sessionContext = this.sessionManager.buildSessionContext();
+            this.agent.replaceMessages(sessionContext.messages);
+            // Get the saved compaction entry for the extension event
+            const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
+            if (this._extensionRunner && savedCompactionEntry) {
+                await this._extensionRunner.emit({
+                    type: "session_compact",
+                    compactionEntry: savedCompactionEntry,
+                    fromExtension,
+                });
+            }
+            const result = {
+                summary,
+                firstKeptEntryId,
+                tokensBefore,
+                details,
+            };
+            this._emit({ type: "auto_compaction_end", result, aborted: false, willRetry });
+            if (willRetry) {
+                const messages = this.agent.state.messages;
+                const lastMsg = messages[messages.length - 1];
+                if (lastMsg?.role === "assistant" && lastMsg.stopReason === "error") {
+                    this.agent.replaceMessages(messages.slice(0, -1));
+                }
+                setTimeout(() => {
+                    this.agent.continue().catch(() => { });
+                }, 100);
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "compaction failed";
+            this._emit({
+                type: "auto_compaction_end",
+                result: undefined,
+                aborted: false,
+                willRetry: false,
+                errorMessage: reason === "overflow"
+                    ? `Context overflow recovery failed: ${errorMessage}`
+                    : `Auto-compaction failed: ${errorMessage}`,
+            });
+        }
+        finally {
+            this._autoCompactionAbortController = undefined;
+        }
+    }
+    /**
+     * Toggle auto-compaction setting.
+     */
+    setAutoCompactionEnabled(enabled) {
+        this.settingsManager.setCompactionEnabled(enabled);
+    }
+    /** Whether auto-compaction is enabled */
+    get autoCompactionEnabled() {
+        return this.settingsManager.getCompactionEnabled();
+    }
+    async bindExtensions(bindings) {
+        if (bindings.uiContext !== undefined) {
+            this._extensionUIContext = bindings.uiContext;
+        }
+        if (bindings.commandContextActions !== undefined) {
+            this._extensionCommandContextActions = bindings.commandContextActions;
+        }
+        if (bindings.shutdownHandler !== undefined) {
+            this._extensionShutdownHandler = bindings.shutdownHandler;
+        }
+        if (bindings.onError !== undefined) {
+            this._extensionErrorListener = bindings.onError;
+        }
+        if (bindings.onHookError !== undefined) {
+            this._hookErrorListener = bindings.onHookError;
+        }
+        if (this._extensionRunner) {
+            this._applyExtensionBindings(this._extensionRunner);
+            await this._extensionRunner.emit({ type: "session_start" });
+        }
+        this._applyHookBindings();
+    }
+    _applyExtensionBindings(runner) {
+        runner.setUIContext(this._extensionUIContext);
+        runner.bindCommandContext(this._extensionCommandContextActions);
+        this._extensionErrorUnsubscriber?.();
+        this._extensionErrorUnsubscriber = this._extensionErrorListener
+            ? runner.onError(this._extensionErrorListener)
+            : undefined;
+    }
+    _applyHookBindings() {
+        this._hookErrorUnsubscriber?.();
+        this._hookErrorUnsubscriber =
+            this._hookErrorListener && this._hookRunner
+                ? this._hookRunner.onError(this._hookErrorListener)
+                : undefined;
+    }
+    _bindExtensionCore(runner) {
+        runner.bindCore({
+            sendMessage: (message, options) => {
+                this.sendCustomMessage(message, options).catch((err) => {
+                    runner.emitError({
+                        extensionPath: "<runtime>",
+                        event: "send_message",
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                });
+            },
+            sendUserMessage: (content, options) => {
+                this.sendUserMessage(content, options).catch((err) => {
+                    runner.emitError({
+                        extensionPath: "<runtime>",
+                        event: "send_user_message",
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                });
+            },
+            appendEntry: (customType, data) => {
+                this.sessionManager.appendCustomEntry(customType, data);
+            },
+            setSessionName: (name) => {
+                this.sessionManager.appendSessionInfo(name);
+            },
+            getSessionName: () => {
+                return this.sessionManager.getSessionName();
+            },
+            setLabel: (entryId, label) => {
+                this.sessionManager.appendLabelChange(entryId, label);
+            },
+            getActiveTools: () => this.getActiveToolNames(),
+            getAllTools: () => this.getAllTools(),
+            setActiveTools: (toolNames) => this.setActiveToolsByName(toolNames),
+            setModel: async (model) => {
+                const key = await this.modelRegistry.getApiKey(model);
+                if (!key)
+                    return false;
+                await this.setModel(model);
+                return true;
+            },
+            getThinkingLevel: () => this.thinkingLevel,
+            setThinkingLevel: (level) => this.setThinkingLevel(level),
+        }, {
+            getModel: () => this.model,
+            isIdle: () => !this.isStreaming,
+            abort: () => this.abort(),
+            hasPendingMessages: () => this.pendingMessageCount > 0,
+            shutdown: () => {
+                this._extensionShutdownHandler?.();
+            },
+            getContextUsage: () => this.getContextUsage(),
+            compact: (options) => {
+                void (async () => {
+                    try {
+                        const result = await this.compact(options?.customInstructions);
+                        options?.onComplete?.(result);
+                    }
+                    catch (error) {
+                        const err = error instanceof Error ? error : new Error(String(error));
+                        options?.onError?.(err);
+                    }
+                })();
+            },
+        });
+    }
+    _buildRuntime(options) {
+        const autoResizeImages = this.settingsManager.getImageAutoResize();
+        const shellCommandPrefix = this.settingsManager.getShellCommandPrefix();
+        const hooksResult = this._resourceLoader.getHooks?.() ?? { hooks: [], errors: [] };
+        this._hookRunner = hooksResult.hooks.length > 0 ? new HookRunner(hooksResult.hooks) : undefined;
+        if (this._hookRunnerRef) {
+            this._hookRunnerRef.current = this._hookRunner;
+        }
+        this._applyHookBindings();
+        const taskOptions = {
+            settingsManager: this.settingsManager,
+            modelRegistry: this._modelRegistry,
+            subagentStore: this._subagentStore,
+            getDefaultModel: () => this.model,
+            getDefaultThinkingLevel: () => this.thinkingLevel,
+            contextFiles: this._resourceLoader.getAgentsFiles().agentsFiles,
+            skills: this._resourceLoader.getSkills().skills,
+        };
+        const baseTools = this._baseToolsOverride
+            ? this._baseToolsOverride
+            : createAllTools(this._cwd, {
+                read: { autoResizeImages },
+                bash: { commandPrefix: shellCommandPrefix },
+                task: taskOptions,
+                todoStore: this._todoStore,
+            });
+        this._baseToolRegistry = new Map(Object.entries(baseTools).map(([name, tool]) => [name, tool]));
+        const extensionsResult = this._resourceLoader.getExtensions();
+        if (options.flagValues) {
+            for (const [name, value] of options.flagValues) {
+                extensionsResult.runtime.flagValues.set(name, value);
+            }
+        }
+        const hasExtensions = extensionsResult.extensions.length > 0;
+        const hasCustomTools = this._customTools.length > 0;
+        this._extensionRunner =
+            hasExtensions || hasCustomTools
+                ? new ExtensionRunner(extensionsResult.extensions, extensionsResult.runtime, this._cwd, this.sessionManager, this._modelRegistry)
+                : undefined;
+        if (this._extensionRunnerRef) {
+            this._extensionRunnerRef.current = this._extensionRunner;
+        }
+        if (this._extensionRunner) {
+            this._bindExtensionCore(this._extensionRunner);
+            this._applyExtensionBindings(this._extensionRunner);
+        }
+        const registeredTools = this._extensionRunner?.getAllRegisteredTools() ?? [];
+        const allCustomTools = [
+            ...registeredTools,
+            ...this._customTools.map((def) => ({ definition: def, extensionPath: "<sdk>" })),
+        ];
+        const wrappedExtensionTools = this._extensionRunner
+            ? wrapRegisteredTools(allCustomTools, this._extensionRunner)
+            : [];
+        const toolRegistry = new Map(this._baseToolRegistry);
+        for (const tool of wrappedExtensionTools) {
+            toolRegistry.set(tool.name, tool);
+        }
+        const defaultActiveToolNames = this._baseToolsOverride
+            ? Object.keys(this._baseToolsOverride)
+            : ["read", "bash", "edit", "write", "task", "todoread", "todowrite"];
+        const baseActiveToolNames = options.activeToolNames ?? defaultActiveToolNames;
+        const activeToolNameSet = new Set(baseActiveToolNames);
+        if (options.includeAllExtensionTools) {
+            for (const tool of wrappedExtensionTools) {
+                activeToolNameSet.add(tool.name);
+            }
+        }
+        const extensionToolNames = new Set(wrappedExtensionTools.map((tool) => tool.name));
+        const activeBaseTools = Array.from(activeToolNameSet)
+            .filter((name) => this._baseToolRegistry.has(name) && !extensionToolNames.has(name))
+            .map((name) => this._baseToolRegistry.get(name));
+        const activeExtensionTools = wrappedExtensionTools.filter((tool) => activeToolNameSet.has(tool.name));
+        // Include MCP tools that are in the active set
+        const activeMCPTools = this._mcpTools.filter((tool) => activeToolNameSet.has(tool.name));
+        // Include memory tools that are in the active set
+        const activeMemoryTools = this._memoryTools.filter((tool) => activeToolNameSet.has(tool.name));
+        const activeToolsArray = [...activeBaseTools, ...activeExtensionTools, ...activeMCPTools, ...activeMemoryTools];
+        const shouldWrapTools = Boolean(this._extensionRunner || this._hookRunner);
+        if (shouldWrapTools) {
+            const wrappedActiveTools = wrapToolsWithExtensions(activeToolsArray, this._extensionRunner, this._hookRunner, this.sessionId);
+            this.agent.setTools(wrappedActiveTools);
+            const wrappedAllTools = wrapToolsWithExtensions(Array.from(toolRegistry.values()), this._extensionRunner, this._hookRunner, this.sessionId);
+            this._toolRegistry = new Map(wrappedAllTools.map((tool) => [tool.name, tool]));
+        }
+        else {
+            this.agent.setTools(activeToolsArray);
+            this._toolRegistry = toolRegistry;
+        }
+        const systemPromptToolNames = Array.from(activeToolNameSet).filter((name) => this._baseToolRegistry.has(name));
+        this._baseSystemPrompt = this._rebuildSystemPrompt(systemPromptToolNames);
+        this.agent.setSystemPrompt(this._baseSystemPrompt);
+    }
+    async reload() {
+        const previousFlagValues = this._extensionRunner?.getFlagValues();
+        await this._extensionRunner?.emit({ type: "session_shutdown" });
+        // Disconnect MCP servers before reloading
+        await this.disconnectMCP();
+        resetApiProviders();
+        await this._resourceLoader.reload();
+        this._subagentStore.refresh();
+        this._rebuildRuntimeState({
+            activeToolNames: this.getActiveToolNames(),
+            flagValues: previousFlagValues,
+            includeAllExtensionTools: true,
+        });
+        const hasBindings = this._extensionUIContext ||
+            this._extensionCommandContextActions ||
+            this._extensionShutdownHandler ||
+            this._extensionErrorListener;
+        if (this._extensionRunner && hasBindings) {
+            await this._extensionRunner.emit({ type: "session_start" });
+        }
+    }
+    // =========================================================================
+    // Auto-Retry
+    // =========================================================================
+    /**
+     * Check if an error is retryable (overloaded, rate limit, server errors).
+     * Context overflow errors are NOT retryable (handled by compaction instead).
+     */
+    _isRetryableError(message) {
+        if (message.stopReason !== "error" || !message.errorMessage)
+            return false;
+        // Context overflow is handled by compaction, not retry
+        const contextWindow = this.model?.contextWindow ?? 0;
+        if (isContextOverflow(message, contextWindow))
+            return false;
+        const err = message.errorMessage;
+        // Match: overloaded_error, rate limit, 429, 500, 502, 503, 504, service unavailable, connection errors, fetch failed, terminated
+        return /overloaded|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server error|internal error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|reset before headers|terminated/i.test(err);
+    }
+    /**
+     * Handle retryable errors with exponential backoff.
+     * @returns true if retry was initiated, false if max retries exceeded or disabled
+     */
+    async _handleRetryableError(message) {
+        const settings = this.settingsManager.getRetrySettings();
+        if (!settings.enabled)
+            return false;
+        this._retryAttempt++;
+        // Create retry promise on first attempt so waitForRetry() can await it
+        if (this._retryAttempt === 1 && !this._retryPromise) {
+            this._retryPromise = new Promise((resolve) => {
+                this._retryResolve = resolve;
+            });
+        }
+        if (this._retryAttempt > settings.maxRetries) {
+            // Max retries exceeded, emit final failure and reset
+            this._emit({
+                type: "auto_retry_end",
+                success: false,
+                attempt: this._retryAttempt - 1,
+                finalError: message.errorMessage,
+            });
+            this._retryAttempt = 0;
+            this._resolveRetry(); // Resolve so waitForRetry() completes
+            return false;
+        }
+        const delayMs = settings.baseDelayMs * 2 ** (this._retryAttempt - 1);
+        this._emit({
+            type: "auto_retry_start",
+            attempt: this._retryAttempt,
+            maxAttempts: settings.maxRetries,
+            delayMs,
+            errorMessage: message.errorMessage || "Unknown error",
+        });
+        // Remove error message from agent state (keep in session for history)
+        const messages = this.agent.state.messages;
+        if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
+            this.agent.replaceMessages(messages.slice(0, -1));
+        }
+        // Wait with exponential backoff (abortable)
+        this._retryAbortController = new AbortController();
+        try {
+            await sleep(delayMs, this._retryAbortController.signal);
+        }
+        catch {
+            // Aborted during sleep - emit end event so UI can clean up
+            const attempt = this._retryAttempt;
+            this._retryAttempt = 0;
+            this._retryAbortController = undefined;
+            this._emit({
+                type: "auto_retry_end",
+                success: false,
+                attempt,
+                finalError: "Retry cancelled",
+            });
+            this._resolveRetry();
+            return false;
+        }
+        this._retryAbortController = undefined;
+        // Retry via continue() - use setTimeout to break out of event handler chain
+        setTimeout(() => {
+            this.agent.continue().catch(() => {
+                // Retry failed - will be caught by next agent_end
+            });
+        }, 0);
+        return true;
+    }
+    /**
+     * Cancel in-progress retry.
+     */
+    abortRetry() {
+        this._retryAbortController?.abort();
+        // Note: _retryAttempt is reset in the catch block of _autoRetry
+        this._resolveRetry();
+    }
+    /**
+     * Wait for any in-progress retry to complete.
+     * Returns immediately if no retry is in progress.
+     */
+    async waitForRetry() {
+        if (this._retryPromise) {
+            await this._retryPromise;
+        }
+    }
+    /** Whether auto-retry is currently in progress */
+    get isRetrying() {
+        return this._retryPromise !== undefined;
+    }
+    /** Whether auto-retry is enabled */
+    get autoRetryEnabled() {
+        return this.settingsManager.getRetryEnabled();
+    }
+    /**
+     * Toggle auto-retry setting.
+     */
+    setAutoRetryEnabled(enabled) {
+        this.settingsManager.setRetryEnabled(enabled);
+    }
+    // =========================================================================
+    // Bash Execution
+    // =========================================================================
+    /**
+     * Execute a bash command.
+     * Adds result to agent context and session.
+     * @param command The bash command to execute
+     * @param onChunk Optional streaming callback for output
+     * @param options.excludeFromContext If true, command output won't be sent to LLM (!! prefix)
+     * @param options.operations Custom BashOperations for remote execution
+     */
+    async executeBash(command, onChunk, options) {
+        return this._runObserveOperation("session.execute_bash", "command_execution", async () => {
+            this._bashAbortController = new AbortController();
+            // Apply command prefix if configured (e.g., "shopt -s expand_aliases" for alias support)
+            const prefix = this.settingsManager.getShellCommandPrefix();
+            const resolvedCommand = prefix ? `${prefix}\n${command}` : command;
+            const hookEnv = this._hookRunner?.hasHandlers("shell.env")
+                ? (await this._hookRunner.trigger("shell.env", { cwd: process.cwd() }, { env: {} })).env
+                : undefined;
+            try {
+                const result = options?.operations
+                    ? await executeBashWithOperations(resolvedCommand, process.cwd(), options.operations, {
+                        onChunk,
+                        signal: this._bashAbortController.signal,
+                        env: hookEnv,
+                    })
+                    : await executeBashCommand(resolvedCommand, {
+                        onChunk,
+                        signal: this._bashAbortController.signal,
+                        env: hookEnv,
+                    });
+                this.recordBashResult(command, result, options);
+                await this._logObserve({
+                    name: "session.execute_bash",
+                    summary: "bash command completed",
+                    attributes: {
+                        commandLength: command.length,
+                        exitCode: result.exitCode,
+                        cancelled: result.cancelled,
+                        truncated: result.truncated,
+                        excludeFromContext: options?.excludeFromContext ?? false,
+                    },
+                });
+                return result;
+            }
+            finally {
+                this._bashAbortController = undefined;
+            }
+        }, {
+            input: {
+                commandLength: command.length,
+                excludeFromContext: options?.excludeFromContext ?? false,
+            },
+            attributes: {
+                hasCustomOperations: !!options?.operations,
+            },
+            output: (result) => ({
+                exitCode: result.exitCode,
+                cancelled: result.cancelled,
+                truncated: result.truncated,
+            }),
+        });
+    }
+    /**
+     * Record a bash execution result in session history.
+     * Used by executeBash and by extensions that handle bash execution themselves.
+     */
+    recordBashResult(command, result, options) {
+        const bashMessage = {
+            role: "bashExecution",
+            command,
+            output: result.output,
+            exitCode: result.exitCode,
+            cancelled: result.cancelled,
+            truncated: result.truncated,
+            fullOutputPath: result.fullOutputPath,
+            timestamp: Date.now(),
+            excludeFromContext: options?.excludeFromContext,
+        };
+        // If agent is streaming, defer adding to avoid breaking tool_use/tool_result ordering
+        if (this.isStreaming) {
+            // Queue for later - will be flushed on agent_end
+            this._pendingBashMessages.push(bashMessage);
+        }
+        else {
+            // Add to agent state immediately
+            this.agent.appendMessage(bashMessage);
+            // Save to session
+            this.sessionManager.appendMessage(bashMessage);
+        }
+    }
+    /**
+     * Cancel running bash command.
+     */
+    abortBash() {
+        this._bashAbortController?.abort();
+    }
+    /** Whether a bash command is currently running */
+    get isBashRunning() {
+        return this._bashAbortController !== undefined;
+    }
+    /** Whether there are pending bash messages waiting to be flushed */
+    get hasPendingBashMessages() {
+        return this._pendingBashMessages.length > 0;
+    }
+    /**
+     * Flush pending bash messages to agent state and session.
+     * Called after agent turn completes to maintain proper message ordering.
+     */
+    _flushPendingBashMessages() {
+        if (this._pendingBashMessages.length === 0)
+            return;
+        for (const bashMessage of this._pendingBashMessages) {
+            // Add to agent state
+            this.agent.appendMessage(bashMessage);
+            // Save to session
+            this.sessionManager.appendMessage(bashMessage);
+        }
+        this._pendingBashMessages = [];
+    }
+    // =========================================================================
+    // Session Management
+    // =========================================================================
+    /**
+     * Switch to a different session file.
+     * Aborts current operation, loads messages, restores model/thinking.
+     * Listeners are preserved and will continue receiving events.
+     * @returns true if switch completed, false if cancelled by extension
+     */
+    async switchSession(sessionPath) {
+        return this._runObserveOperation("session.switch", "session_switch", async () => {
+            const previousSessionFile = this.sessionManager.getSessionFile();
+            const previousSessionId = this.sessionId;
+            // Emit session_before_switch event (can be cancelled)
+            if (this._extensionRunner?.hasHandlers("session_before_switch")) {
+                const result = (await this._extensionRunner.emit({
+                    type: "session_before_switch",
+                    reason: "resume",
+                    targetSessionFile: sessionPath,
+                }));
+                if (result?.cancel) {
+                    return false;
+                }
+            }
+            this._disconnectFromAgent();
+            await this.abort();
+            this._steeringMessages = [];
+            this._followUpMessages = [];
+            this._pendingNextTurnMessages = [];
+            // Set new session
+            this.sessionManager.setSessionFile(sessionPath);
+            this._rebuildTodoStore();
+            this.agent.sessionId = this.sessionManager.getSessionId();
+            this._memoryThreadId = this.sessionManager.getSessionId();
+            // Reload messages
+            const sessionContext = this.sessionManager.buildSessionContext();
+            // Emit session_switch event to extensions
+            if (this._extensionRunner) {
+                await this._extensionRunner.emit({
+                    type: "session_switch",
+                    reason: "resume",
+                    previousSessionFile,
+                });
+            }
+            this.agent.replaceMessages(sessionContext.messages);
+            // Restore model if saved
+            if (sessionContext.model) {
+                const previousModel = this.model;
+                const availableModels = await this._modelRegistry.getAvailable();
+                const match = availableModels.find((m) => m.provider === sessionContext.model.provider && m.id === sessionContext.model.modelId);
+                if (match) {
+                    this.agent.setModel(match);
+                    await this._emitModelSelect(match, previousModel, "restore");
+                }
+            }
+            // Restore thinking level if saved (setThinkingLevel clamps to model capabilities)
+            if (sessionContext.thinkingLevel) {
+                this.setThinkingLevel(sessionContext.thinkingLevel);
+            }
+            this._reconnectToAgent();
+            await this._endObserveSession(previousSessionId);
+            await this._refreshObserveSession();
+            await this._logObserve({
+                name: "session.switch",
+                summary: "switched session",
+                attributes: {
+                    previousSessionId,
+                    previousSessionFile,
+                    targetSessionFile: sessionPath,
+                },
+            });
+            return true;
+        }, {
+            input: { targetSessionFile: sessionPath },
+            output: (completed) => ({ completed }),
+        });
+    }
+    /**
+     * Create a fork from a specific entry.
+     * Emits before_fork/fork session events to extensions.
+     *
+     * @param entryId ID of the entry to fork from
+     * @returns Object with:
+     *   - selectedText: The text of the selected user message (for editor pre-fill)
+     *   - cancelled: True if an extension cancelled the fork
+     */
+    async fork(entryId) {
+        return this._runObserveOperation("session.fork", "session_fork", async () => {
+            const previousSessionFile = this.sessionFile;
+            const previousSessionId = this.sessionId;
+            const selectedEntry = this.sessionManager.getEntry(entryId);
+            if (!selectedEntry || selectedEntry.type !== "message" || selectedEntry.message.role !== "user") {
+                throw new Error("Invalid entry ID for forking");
+            }
+            const selectedText = this._extractUserMessageText(selectedEntry.message.content);
+            let skipConversationRestore = false;
+            // Emit session_before_fork event (can be cancelled)
+            if (this._extensionRunner?.hasHandlers("session_before_fork")) {
+                const result = (await this._extensionRunner.emit({
+                    type: "session_before_fork",
+                    entryId,
+                }));
+                if (result?.cancel) {
+                    return { selectedText, cancelled: true };
+                }
+                skipConversationRestore = result?.skipConversationRestore ?? false;
+            }
+            // Clear pending messages (bound to old session state)
+            this._pendingNextTurnMessages = [];
+            if (!selectedEntry.parentId) {
+                this.sessionManager.newSession();
+            }
+            else {
+                this.sessionManager.createBranchedSession(selectedEntry.parentId);
+            }
+            this.agent.sessionId = this.sessionManager.getSessionId();
+            this._memoryThreadId = this.sessionManager.getSessionId();
+            this._rebuildTodoStore();
+            // Reload messages from entries (works for both file and in-memory mode)
+            const sessionContext = this.sessionManager.buildSessionContext();
+            // Emit session_fork event to extensions (after fork completes)
+            if (this._extensionRunner) {
+                await this._extensionRunner.emit({
+                    type: "session_fork",
+                    previousSessionFile,
+                });
+            }
+            if (!skipConversationRestore) {
+                this.agent.replaceMessages(sessionContext.messages);
+            }
+            await this._endObserveSession(previousSessionId);
+            await this._refreshObserveSession();
+            await this._logObserve({
+                name: "session.fork",
+                summary: "forked session branch",
+                attributes: {
+                    entryId,
+                    previousSessionId,
+                    previousSessionFile,
+                    skipConversationRestore,
+                },
+            });
+            return { selectedText, cancelled: false };
+        }, {
+            input: { entryId },
+            output: (result) => ({ cancelled: result.cancelled, selectedTextLength: result.selectedText.length }),
+        });
+    }
+    // =========================================================================
+    // Tree Navigation
+    // =========================================================================
+    /**
+     * Navigate to a different node in the session tree.
+     * Unlike fork() which creates a new session file, this stays in the same file.
+     *
+     * @param targetId The entry ID to navigate to
+     * @param options.summarize Whether user wants to summarize abandoned branch
+     * @param options.customInstructions Custom instructions for summarizer
+     * @param options.replaceInstructions If true, customInstructions replaces the default prompt
+     * @param options.label Label to attach to the branch summary entry
+     * @returns Result with editorText (if user message) and cancelled status
+     */
+    async navigateTree(targetId, options = {}) {
+        const oldLeafId = this.sessionManager.getLeafId();
+        // No-op if already at target
+        if (targetId === oldLeafId) {
+            return { cancelled: false };
+        }
+        // Model required for summarization
+        if (options.summarize && !this.model) {
+            throw new Error("No model available for summarization");
+        }
+        const targetEntry = this.sessionManager.getEntry(targetId);
+        if (!targetEntry) {
+            throw new Error(`Entry ${targetId} not found`);
+        }
+        // Collect entries to summarize (from old leaf to common ancestor)
+        const { entries: entriesToSummarize, commonAncestorId } = collectEntriesForBranchSummary(this.sessionManager, oldLeafId, targetId);
+        // Prepare event data - mutable so extensions can override
+        let customInstructions = options.customInstructions;
+        let replaceInstructions = options.replaceInstructions;
+        let label = options.label;
+        const preparation = {
+            targetId,
+            oldLeafId,
+            commonAncestorId,
+            entriesToSummarize,
+            userWantsSummary: options.summarize ?? false,
+            customInstructions,
+            replaceInstructions,
+            label,
+        };
+        // Set up abort controller for summarization
+        this._branchSummaryAbortController = new AbortController();
+        let extensionSummary;
+        let fromExtension = false;
+        // Emit session_before_tree event
+        if (this._extensionRunner?.hasHandlers("session_before_tree")) {
+            const result = (await this._extensionRunner.emit({
+                type: "session_before_tree",
+                preparation,
+                signal: this._branchSummaryAbortController.signal,
+            }));
+            if (result?.cancel) {
+                return { cancelled: true };
+            }
+            if (result?.summary && options.summarize) {
+                extensionSummary = result.summary;
+                fromExtension = true;
+            }
+            // Allow extensions to override instructions and label
+            if (result?.customInstructions !== undefined) {
+                customInstructions = result.customInstructions;
+            }
+            if (result?.replaceInstructions !== undefined) {
+                replaceInstructions = result.replaceInstructions;
+            }
+            if (result?.label !== undefined) {
+                label = result.label;
+            }
+        }
+        // Run default summarizer if needed
+        let summaryText;
+        let summaryDetails;
+        if (options.summarize && entriesToSummarize.length > 0 && !extensionSummary) {
+            const model = this.model;
+            const apiKey = await this._modelRegistry.getApiKey(model);
+            if (!apiKey) {
+                throw new Error(`No API key for ${model.provider}`);
+            }
+            const branchSummarySettings = this.settingsManager.getBranchSummarySettings();
+            const result = await generateBranchSummary(entriesToSummarize, {
+                model,
+                apiKey,
+                signal: this._branchSummaryAbortController.signal,
+                customInstructions,
+                replaceInstructions,
+                reserveTokens: branchSummarySettings.reserveTokens,
+            });
+            this._branchSummaryAbortController = undefined;
+            if (result.aborted) {
+                return { cancelled: true, aborted: true };
+            }
+            if (result.error) {
+                throw new Error(result.error);
+            }
+            summaryText = result.summary;
+            summaryDetails = {
+                readFiles: result.readFiles || [],
+                modifiedFiles: result.modifiedFiles || [],
+            };
+        }
+        else if (extensionSummary) {
+            summaryText = extensionSummary.summary;
+            summaryDetails = extensionSummary.details;
+        }
+        // Determine the new leaf position based on target type
+        let newLeafId;
+        let editorText;
+        if (targetEntry.type === "message" && targetEntry.message.role === "user") {
+            // User message: leaf = parent (null if root), text goes to editor
+            newLeafId = targetEntry.parentId;
+            editorText = this._extractUserMessageText(targetEntry.message.content);
+        }
+        else if (targetEntry.type === "custom_message") {
+            // Custom message: leaf = parent (null if root), text goes to editor
+            newLeafId = targetEntry.parentId;
+            editorText =
+                typeof targetEntry.content === "string"
+                    ? targetEntry.content
+                    : targetEntry.content
+                        .filter((c) => c.type === "text")
+                        .map((c) => c.text)
+                        .join("");
+        }
+        else {
+            // Non-user message: leaf = selected node
+            newLeafId = targetId;
+        }
+        // Switch leaf (with or without summary)
+        // Summary is attached at the navigation target position (newLeafId), not the old branch
+        let summaryEntry;
+        if (summaryText) {
+            // Create summary at target position (can be null for root)
+            const summaryId = this.sessionManager.branchWithSummary(newLeafId, summaryText, summaryDetails, fromExtension);
+            summaryEntry = this.sessionManager.getEntry(summaryId);
+            // Attach label to the summary entry
+            if (label) {
+                this.sessionManager.appendLabelChange(summaryId, label);
+            }
+        }
+        else if (newLeafId === null) {
+            // No summary, navigating to root - reset leaf
+            this.sessionManager.resetLeaf();
+        }
+        else {
+            // No summary, navigating to non-root
+            this.sessionManager.branch(newLeafId);
+        }
+        // Attach label to target entry when not summarizing (no summary entry to label)
+        if (label && !summaryText) {
+            this.sessionManager.appendLabelChange(targetId, label);
+        }
+        // Update agent state
+        this._rebuildTodoStore();
+        const sessionContext = this.sessionManager.buildSessionContext();
+        this.agent.replaceMessages(sessionContext.messages);
+        // Emit session_tree event
+        if (this._extensionRunner) {
+            await this._extensionRunner.emit({
+                type: "session_tree",
+                newLeafId: this.sessionManager.getLeafId(),
+                oldLeafId,
+                summaryEntry,
+                fromExtension: summaryText ? fromExtension : undefined,
+            });
+        }
+        // Emit to custom tools
+        this._branchSummaryAbortController = undefined;
+        return { editorText, cancelled: false, summaryEntry };
+    }
+    /**
+     * Get all user messages from session for fork selector.
+     */
+    getUserMessagesForForking() {
+        const entries = this.sessionManager.getEntries();
+        const result = [];
+        for (const entry of entries) {
+            if (entry.type !== "message")
+                continue;
+            if (entry.message.role !== "user")
+                continue;
+            const text = this._extractUserMessageText(entry.message.content);
+            if (text) {
+                result.push({ entryId: entry.id, text });
+            }
+        }
+        return result;
+    }
+    _extractUserMessageText(content) {
+        if (typeof content === "string")
+            return content;
+        if (Array.isArray(content)) {
+            return content
+                .filter((c) => c.type === "text")
+                .map((c) => c.text)
+                .join("");
+        }
+        return "";
+    }
+    /**
+     * Get session statistics.
+     */
+    getSessionStats() {
+        const state = this.state;
+        const userMessages = state.messages.filter((m) => m.role === "user").length;
+        const assistantMessages = state.messages.filter((m) => m.role === "assistant").length;
+        const toolResults = state.messages.filter((m) => m.role === "toolResult").length;
+        let toolCalls = 0;
+        let totalInput = 0;
+        let totalOutput = 0;
+        let totalCacheRead = 0;
+        let totalCacheWrite = 0;
+        let totalCost = 0;
+        for (const message of state.messages) {
+            if (message.role === "assistant") {
+                const assistantMsg = message;
+                toolCalls += assistantMsg.content.filter((c) => c.type === "toolCall").length;
+                totalInput += assistantMsg.usage.input;
+                totalOutput += assistantMsg.usage.output;
+                totalCacheRead += assistantMsg.usage.cacheRead;
+                totalCacheWrite += assistantMsg.usage.cacheWrite;
+                totalCost += assistantMsg.usage.cost.total;
+            }
+        }
+        return {
+            sessionFile: this.sessionFile,
+            sessionId: this.sessionId,
+            userMessages,
+            assistantMessages,
+            toolCalls,
+            toolResults,
+            totalMessages: state.messages.length,
+            tokens: {
+                input: totalInput,
+                output: totalOutput,
+                cacheRead: totalCacheRead,
+                cacheWrite: totalCacheWrite,
+                total: totalInput + totalOutput + totalCacheRead + totalCacheWrite,
+            },
+            cost: totalCost,
+        };
+    }
+    getContextUsage() {
+        const model = this.model;
+        if (!model)
+            return undefined;
+        const contextWindow = model.contextWindow ?? 0;
+        if (contextWindow <= 0)
+            return undefined;
+        const estimate = estimateContextTokens(this.messages);
+        const percent = (estimate.tokens / contextWindow) * 100;
+        return {
+            tokens: estimate.tokens,
+            contextWindow,
+            percent,
+            usageTokens: estimate.usageTokens,
+            trailingTokens: estimate.trailingTokens,
+            lastUsageIndex: estimate.lastUsageIndex,
+        };
+    }
+    /**
+     * Export session to HTML.
+     * @param outputPath Optional output path (defaults to session directory)
+     * @returns Path to exported file
+     */
+    async exportToHtml(outputPath) {
+        const themeName = this.settingsManager.getTheme();
+        // Create tool renderer if we have an extension runner (for custom tool HTML rendering)
+        let toolRenderer;
+        if (this._extensionRunner) {
+            toolRenderer = createToolHtmlRenderer({
+                getToolDefinition: (name) => this._extensionRunner.getToolDefinition(name),
+                theme,
+            });
+        }
+        return await exportSessionToHtml(this.sessionManager, this.state, {
+            outputPath,
+            themeName,
+            toolRenderer,
+        });
+    }
+    // =========================================================================
+    // Utilities
+    // =========================================================================
+    /**
+     * Get text content of last assistant message.
+     * Useful for /copy command.
+     * @returns Text content, or undefined if no assistant message exists
+     */
+    getLastAssistantText() {
+        const lastAssistant = this.messages
+            .slice()
+            .reverse()
+            .find((m) => {
+            if (m.role !== "assistant")
+                return false;
+            const msg = m;
+            // Skip aborted messages with no content
+            if (msg.stopReason === "aborted" && msg.content.length === 0)
+                return false;
+            return true;
+        });
+        if (!lastAssistant)
+            return undefined;
+        let text = "";
+        for (const content of lastAssistant.content) {
+            if (content.type === "text") {
+                text += content.text;
+            }
+        }
+        return text.trim() || undefined;
+    }
+    // =========================================================================
+    // Extension System
+    // =========================================================================
+    /**
+     * Check if extensions have handlers for a specific event type.
+     */
+    hasExtensionHandlers(eventType) {
+        return this._extensionRunner?.hasHandlers(eventType) ?? false;
+    }
+    /**
+     * Get the extension runner (for setting UI context and error handlers).
+     */
+    get extensionRunner() {
+        return this._extensionRunner;
+    }
+    // =========================================================================
+    // MCP (Model Context Protocol)
+    // =========================================================================
+    /**
+     * Register MCP tools with the session.
+     * Called by createAgentSession after MCP servers are connected.
+     * @param tools - MCP tools wrapped as AgentTools
+     * @param pool - MCP client pool for lifecycle management
+     */
+    registerMCPTools(tools, pool) {
+        this._mcpPool = pool;
+        this._mcpTools = tools;
+        // Add MCP tools to the tool registry
+        for (const tool of tools) {
+            this._toolRegistry.set(tool.name, tool);
+        }
+        // Rebuild active tools to include MCP tools
+        const currentActive = this.getActiveToolNames();
+        const mcpToolNames = tools.map((t) => t.name);
+        this.setActiveToolsByName([...currentActive, ...mcpToolNames]);
+        // Rebuild runtime to include MCP tools in agent
+        this._rebuildRuntimeState({
+            activeToolNames: [...currentActive, ...mcpToolNames],
+            includeAllExtensionTools: true,
+        });
+        void this._refreshObserveSession();
+        void this._logObserve({
+            name: "mcp.register_tools",
+            summary: "registered MCP tools",
+            attributes: {
+                toolCount: tools.length,
+                toolNames: tools.map((tool) => tool.name),
+            },
+        });
+    }
+    /**
+     * Get MCP server status.
+     * @returns Status object for each connected server
+     */
+    async getMCPStatus() {
+        if (!this._mcpPool)
+            return [];
+        return this._mcpPool.getStatus();
+    }
+    /**
+     * Get MCP tool names.
+     * @returns Array of MCP tool names
+     */
+    getMCPToolNames() {
+        return this._mcpTools.map(t => t.name);
+    }
+    /**
+     * Get MCP tool definitions for UI rendering.
+     * @returns Array of MCP tools
+     */
+    getMCPTools() {
+        return this._mcpTools;
+    }
+    /**
+     * Disconnect MCP servers.
+     * Should be called during session shutdown.
+     */
+    async disconnectMCP() {
+        if (this._mcpPool) {
+            await this._mcpPool.disconnectAll();
+            this._mcpPool = undefined;
+            this._mcpTools = [];
+        }
+    }
+    /**
+     * Reconnect to MCP servers.
+     * @param configPath - Path to the MCP servers config file
+     * @returns Promise resolving to the number of tools loaded
+     */
+    async reconnectMCP(configPath) {
+        return this._runObserveOperation("mcp.reconnect", "mcp_call", async () => {
+            // First disconnect existing connections
+            await this.disconnectMCP();
+            // Load new tools
+            const { createMCPTools } = await import("./tooling/index.js");
+            const result = await createMCPTools(configPath);
+            // Register tools
+            if (result.tools.length > 0) {
+                this.registerMCPTools(result.tools, result.pool);
+            }
+            await this._refreshObserveSession();
+            return result.tools.length;
+        }, {
+            input: { configPath },
+            output: (toolCount) => ({ toolCount }),
+        });
+    }
+    // =========================================================================
+    // Memory System
+    // =========================================================================
+    /**
+     * Register memory tools with the session.
+     * Called by createAgentSession after memory is initialized.
+     * @param tools - Memory tools wrapped as AgentTools
+     * @param memory - Memory instance for context enrichment
+     */
+    registerMemoryTools(tools, memory) {
+        this._memory = memory;
+        this._memoryTools = tools;
+        this._memoryThreadId = this.sessionManager.getSessionId();
+        // Add memory tools to the tool registry
+        for (const tool of tools) {
+            this._toolRegistry.set(tool.name, tool);
+        }
+        // Rebuild active tools to include memory tools
+        const currentActive = this.getActiveToolNames();
+        const memoryToolNames = tools.map((t) => t.name);
+        this.setActiveToolsByName([...currentActive, ...memoryToolNames]);
+        // Rebuild runtime to include memory tools in agent
+        this._rebuildRuntimeState({
+            activeToolNames: [...currentActive, ...memoryToolNames],
+            includeAllExtensionTools: true,
+        });
+        void this._refreshObserveSession();
+        void this._logObserve({
+            name: "memory.register_tools",
+            summary: "registered memory tools",
+            attributes: {
+                toolCount: tools.length,
+                toolNames: tools.map((tool) => tool.name),
+            },
+        });
+    }
+    /**
+     * Enable memory for the current and future sessions.
+     * Optionally persists an OpenAI API key before initializing memory.
+     */
+    async enableMemory(options) {
+        await this._runObserveOperation("memory.enable", "custom", async () => {
+            const persistSettings = options?.persistSettings ?? true;
+            if (this._memory) {
+                await this.disableMemory({ persistSettings: false });
+            }
+            if (options?.apiKey) {
+                this._modelRegistry.authStorage.set("openai", "default", {
+                    type: "api_key",
+                    key: options.apiKey,
+                    accountName: "Default",
+                });
+            }
+            const openaiKey = options?.apiKey ?? (await this._modelRegistry.getApiKeyForProvider("openai"));
+            if (!openaiKey) {
+                throw new Error("OpenAI API key not found. Run /memory setup <OPENAI_API_KEY> first.");
+            }
+            const memory = await createMemory({
+                apiKey: openaiKey,
+                lastMessages: this.settingsManager.getMemoryLastMessages(),
+                workingMemory: this.settingsManager.getMemoryWorkingMemoryEnabled()
+                    ? { enabled: true, scope: "resource", template: DEFAULT_WORKING_MEMORY_TEMPLATE }
+                    : undefined,
+                semanticRecall: this.settingsManager.getMemorySemanticRecallEnabled()
+                    ? { topK: 5, messageRange: 2 }
+                    : undefined,
+                observationalMemory: this.settingsManager.getMemoryObservationalMemoryEnabled()
+                    ? { enabled: true, scope: "thread" }
+                    : undefined,
+            });
+            const memoryTools = createMemoryTools(memory, {
+                threadId: this.sessionManager.getSessionId(),
+                resourceId: this._memoryResourceId,
+            });
+            this.registerMemoryTools(memoryTools, memory);
+            if (persistSettings) {
+                this.settingsManager.setMemorySettings({ enabled: true, autoConnect: true });
+            }
+            await this._refreshObserveSession();
+        }, {
+            attributes: {
+                persistSettings: options?.persistSettings ?? true,
+                hasApiKeyOverride: !!options?.apiKey,
+            },
+        });
+    }
+    /**
+     * Disable memory for the current and future sessions.
+     */
+    async disableMemory(options) {
+        await this._runObserveOperation("memory.disable", "custom", async () => {
+            const persistSettings = options?.persistSettings ?? true;
+            const memoryToolNames = new Set(this._memoryTools.map((tool) => tool.name));
+            const activeWithoutMemory = this.getActiveToolNames().filter((name) => !memoryToolNames.has(name));
+            this._memory = undefined;
+            this._memoryTools = [];
+            this._memoryThreadId = "";
+            this._rebuildRuntimeState({
+                activeToolNames: activeWithoutMemory,
+                includeAllExtensionTools: true,
+            });
+            if (persistSettings) {
+                this.settingsManager.setMemorySettings({ enabled: false, autoConnect: false });
+            }
+            await this._refreshObserveSession();
+        }, {
+            attributes: {
+                persistSettings: options?.persistSettings ?? true,
+            },
+        });
+    }
+    /**
+     * Get the memory instance.
+     * @returns Memory instance or undefined if not enabled
+     */
+    getMemory() {
+        return this._memory;
+    }
+    /**
+     * Get memory tool names.
+     * @returns Array of memory tool names
+     */
+    getMemoryToolNames() {
+        return this._memoryTools.map(t => t.name);
+    }
+    /**
+     * Get memory tools.
+     * @returns Array of memory tools
+     */
+    getMemoryTools() {
+        return this._memoryTools;
+    }
+    /**
+     * Check if memory is enabled.
+     * @returns True if memory is initialized
+     */
+    isMemoryEnabled() {
+        return this._memory !== undefined;
+    }
+    /**
+     * Get working memory for the current thread.
+     * @returns Working memory content or undefined
+     */
+    async getWorkingMemory() {
+        if (!this._memory)
+            return undefined;
+        try {
+            const workingMemory = await this._memory.getWorkingMemory?.({
+                threadId: this._memoryThreadId,
+                resourceId: this._memoryResourceId,
+            });
+            return typeof workingMemory === 'string' ? workingMemory : (workingMemory?.content || undefined);
+        }
+        catch (err) {
+            console.warn("Failed to get working memory:", err);
+            return undefined;
+        }
+    }
+    /**
+     * Clear memory for the current thread.
+     */
+    async clearMemory() {
+        if (!this._memory)
+            return;
+        try {
+            await this._memory.deleteThread?.(this._memoryThreadId);
+        }
+        catch (err) {
+            console.warn("Failed to clear memory:", err);
+        }
+    }
+    // =========================================================================
+    // Memory Processing (Internal)
+    // =========================================================================
+    /**
+     * Process input through memory (inject working memory + semantic recall).
+     * Called internally before agent.prompt() to enrich context.
+     * @param messages - Messages to process
+     * @returns Processed messages with memory context injected
+     */
+    async _processMemoryInput(messages) {
+        if (!this._memory)
+            return messages;
+        try {
+            // Convert AgentMessage to CoreMessage format
+            const coreMessages = messages
+                .filter((msg) => msg.role === "user" || msg.role === "assistant")
+                .map((msg) => {
+                const content = typeof msg.content === "string"
+                    ? msg.content
+                    : Array.isArray(msg.content)
+                        ? msg.content.filter((c) => c.type === "text").map((c) => c.text).join("")
+                        : "";
+                return {
+                    id: msg.id || crypto.randomUUID(),
+                    role: msg.role,
+                    content,
+                    createdAt: new Date(msg.timestamp || Date.now()),
+                };
+            });
+            // Process through memory
+            await this._memory.processInput?.({
+                messages: coreMessages,
+                threadId: this._memoryThreadId,
+                resourceId: this._memoryResourceId,
+            });
+            // Return original messages (memory enrichment happens via system prompt)
+            return messages;
+        }
+        catch (err) {
+            console.warn("Memory input processing failed:", err);
+            return messages;
+        }
+    }
+    /**
+     * Process output through memory (extract observations).
+     * Called internally after turn_end to store conversation in memory.
+     * @param message - The message to process
+     */
+    async _processMemoryOutput(message) {
+        if (!this._memory)
+            return;
+        try {
+            // Only process user and assistant messages
+            if (message.role !== "user" && message.role !== "assistant")
+                return;
+            const content = typeof message.content === "string"
+                ? message.content
+                : Array.isArray(message.content)
+                    ? message.content.filter((c) => c.type === "text").map((c) => c.text).join("")
+                    : "";
+            const coreMessage = {
+                id: message.id || crypto.randomUUID(),
+                role: message.role,
+                content,
+                createdAt: new Date(message.timestamp || Date.now()),
+            };
+            await this._memory.processOutput?.({
+                messages: [coreMessage],
+                threadId: this._memoryThreadId,
+                resourceId: this._memoryResourceId,
+            });
+        }
+        catch (err) {
+            console.warn("Memory output processing failed:", err);
+        }
+    }
+}
+//# sourceMappingURL=agent-session.js.map