gsd-pi 2.76.0 → 2.77.0-dev.538325aea

package/packages/gsd-agent-core/dist/agent-session.js

@@ -0,0 +1,2595 @@
+/**
+ * AgentSession - Core abstraction for agent lifecycle and session management.
+ *
+ * This class is shared between all run modes (interactive, print, rpc).
+ * It encapsulates:
+ * - Agent state access
+ * - Event subscription with automatic session persistence
+ * - Model and thinking level management
+ * - Compaction (manual and auto)
+ * - Bash execution
+ * - Session switching and branching
+ *
+ * Modes use this class and add their own I/O layer on top.
+ */
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, join } from "node:path";
+import { modelsAreEqual, resetApiProviders, supportsXhigh } from "@gsd/pi-ai";
+import { Type } from "@sinclair/typebox";
+import { getAgentDir, stripFrontmatter, createReadTool, createBashTool, createEditTool, createWriteTool, createGrepTool, createFindTool, createLsTool, createHashlineEditTool, createHashlineReadTool, } from "@gsd/pi-coding-agent";
+/** Extract a human-readable error message from an unknown thrown value. */
+function getErrorMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+import { executeBash as executeBashCommand, executeBashWithOperations } from "./bash-executor.js";
+import { calculateContextTokens, collectEntriesForBranchSummary, estimateContextTokens, generateBranchSummary, } from "./compaction/index.js";
+import { CompactionOrchestrator } from "./compaction-orchestrator.js";
+import { exportSessionToHtml } from "./export-html/index.js";
+import { ExtensionRunner, wrapRegisteredTools, } from "@gsd/pi-coding-agent";
+import { FallbackResolver, } from "./fallback-resolver.js";
+import { RetryHandler } from "./retry-handler.js";
+import { isImageDimensionError, downsizeConversationImages } from "./image-overflow-recovery.js";
+import { getLatestCompactionEntry } from "@gsd/pi-coding-agent";
+import { buildSystemPrompt } from "./system-prompt.js";
+const require = createRequire(import.meta.url);
+const DEFAULT_THINKING_LEVEL = "medium";
+const BUILTIN_SLASH_COMMANDS = [
+    { name: "settings", description: "Open settings menu" },
+    { name: "model", description: "Select model (opens selector UI)" },
+    { name: "scoped-models", description: "Enable/disable models for Ctrl+P cycling" },
+    { name: "export", description: "Export session to HTML file" },
+    { name: "share", description: "Share session as a secret GitHub gist" },
+    { name: "copy", description: "Copy last agent message to clipboard" },
+    { name: "name", description: "Set session display name" },
+    { name: "session", description: "Show session info and stats" },
+    { name: "changelog", description: "Show changelog entries" },
+    { name: "hotkeys", description: "Show all keyboard shortcuts" },
+    { name: "fork", description: "Create a new fork from a previous message" },
+    { name: "tree", description: "Navigate session tree (switch branches)" },
+    { name: "provider", description: "Manage provider configuration" },
+    { name: "login", description: "Login with OAuth provider" },
+    { name: "logout", description: "Logout from OAuth provider" },
+    { name: "new", description: "Start a new session" },
+    { name: "compact", description: "Manually compact the session context" },
+    { name: "resume", description: "Resume a different session" },
+    { name: "reload", description: "Reload extensions, skills, prompts, and themes" },
+    { name: "thinking", description: "Set thinking level (off/minimal/low/medium/high/xhigh)" },
+    { name: "edit-mode", description: "Toggle edit mode (standard/hashline)" },
+    { name: "terminal", description: "Run a shell command directly (e.g. /terminal ping -c3 1.1.1.1)" },
+    { name: "quit", description: "Quit pi" },
+];
+function getDocsPath() {
+    const piEntryPath = require.resolve("@gsd/pi-coding-agent");
+    return join(dirname(piEntryPath), "..", "docs");
+}
+function parsePromptArgs(argsString) {
+    const args = [];
+    let current = "";
+    let inQuote = null;
+    for (let i = 0; i < argsString.length; i++) {
+        const char = argsString[i];
+        if (inQuote) {
+            if (char === inQuote) {
+                inQuote = null;
+            }
+            else {
+                current += char;
+            }
+        }
+        else if (char === '"' || char === "'") {
+            inQuote = char;
+        }
+        else if (char === " " || char === "\t") {
+            if (current) {
+                args.push(current);
+                current = "";
+            }
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current) {
+        args.push(current);
+    }
+    return args;
+}
+function substituteTemplateArgs(content, args) {
+    let result = content;
+    result = result.replace(/\$(\d+)/g, (_, num) => {
+        const index = Number.parseInt(num, 10) - 1;
+        return args[index] ?? "";
+    });
+    result = result.replace(/\$ARGUMENTS/g, args.join(" "));
+    result = result.replace(/\$@/g, args.join(" "));
+    return result;
+}
+function expandPromptTemplate(text, templates) {
+    if (!text.startsWith("/"))
+        return text;
+    const spaceIndex = text.indexOf(" ");
+    const templateName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+    const argsString = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1);
+    const template = templates.find((candidate) => candidate.name === templateName);
+    if (!template)
+        return text;
+    const args = parsePromptArgs(argsString);
+    return substituteTemplateArgs(template.content, args);
+}
+function createAllTools(cwd, options) {
+    return {
+        read: createReadTool(cwd, options?.read),
+        bash: createBashTool(cwd, options?.bash),
+        edit: createEditTool(cwd),
+        write: createWriteTool(cwd),
+        grep: createGrepTool(cwd),
+        find: createFindTool(cwd),
+        ls: createLsTool(cwd),
+        hashline_edit: createHashlineEditTool(cwd),
+        hashline_read: createHashlineReadTool(cwd, options?.read),
+    };
+}
+async function createAgentSessionRuntime(factory, initial) {
+    const runtime = {
+        createRuntime: factory,
+        async newSession(options) {
+            if (options?.setup) {
+                await options.setup(initial.sessionManager);
+            }
+            await runtime.createRuntime({
+                ...initial,
+                sessionStartEvent: { type: "session_start", reason: "new" },
+            });
+            return { cancelled: false };
+        },
+        async switchSession(sessionPath) {
+            const previousSessionFile = initial.sessionManager.getSessionFile();
+            initial.sessionManager.setSessionFile(sessionPath);
+            await runtime.createRuntime({
+                ...initial,
+                sessionStartEvent: {
+                    type: "session_start",
+                    reason: "resume",
+                    previousSessionFile,
+                },
+            });
+            return { cancelled: false };
+        },
+    };
+    await runtime.createRuntime(initial);
+    return runtime;
+}
+/**
+ * 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 = [];
+        this._agentEventQueue = Promise.resolve();
+        /** 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 = [];
+        // Cumulative session stats — survives compaction (#1423)
+        this._cumulativeCost = 0;
+        this._cumulativeInputTokens = 0;
+        this._cumulativeOutputTokens = 0;
+        this._cumulativeToolCalls = 0;
+        /** Cost of the most recent assistant response (for per-prompt display). */
+        this._lastTurnCost = 0;
+        // Bash execution state
+        this._bashAbortController = undefined;
+        this._pendingBashMessages = [];
+        // Extension system
+        this._extensionRunner = undefined;
+        this._turnIndex = 0;
+        this._baseToolRegistry = new Map();
+        // Tool registry for extension getTools/setTools
+        this._toolRegistry = new Map();
+        this._toolPromptSnippets = new Map();
+        this._toolPromptGuidelines = 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 = (event) => {
+            // Create retry promise synchronously before queueing async processing.
+            // Agent.emit() calls this handler synchronously, and prompt() calls waitForRetry()
+            // as soon as agent.prompt() resolves. If the retry promise is created only inside
+            // _processAgentEvent, slow earlier queued events can delay agent_end processing
+            // and waitForRetry() can miss the in-flight retry.
+            this._createRetryPromiseForAgentEnd(event);
+            this._agentEventQueue = this._agentEventQueue.then(() => this._processAgentEvent(event), () => this._processAgentEvent(event));
+            // Keep queue alive if an event handler fails
+            this._agentEventQueue.catch(() => { });
+        };
+        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._fallbackResolver = new FallbackResolver(this.settingsManager, this._modelRegistry.authStorage, this._modelRegistry);
+        this._extensionRunnerRef = config.extensionRunnerRef;
+        this._initialActiveToolNames = config.initialActiveToolNames;
+        this._baseToolsOverride = config.baseToolsOverride;
+        // Initialize delegated subsystems
+        this._retryHandler = new RetryHandler({
+            agent: this.agent,
+            settingsManager: this.settingsManager,
+            modelRegistry: this._modelRegistry,
+            fallbackResolver: this._fallbackResolver,
+            getModel: () => this.model,
+            getSessionId: () => this.sessionId,
+            emit: (event) => this._emit(event),
+            onModelChange: (model) => this.sessionManager.appendModelChange(model.provider, model.id),
+            isClaudeCodeReady: config.isClaudeCodeReady,
+        });
+        this._compactionOrchestrator = new CompactionOrchestrator({
+            agent: this.agent,
+            sessionManager: this.sessionManager,
+            settingsManager: this.settingsManager,
+            modelRegistry: this._modelRegistry,
+            getModel: () => this.model,
+            getSessionId: () => this.sessionId,
+            getExtensionRunner: () => this._extensionRunner,
+            emit: (event) => this._emit(event),
+            disconnectFromAgent: () => this._disconnectFromAgent(),
+            reconnectToAgent: () => this._reconnectToAgent(),
+            abort: () => this.abort(),
+        });
+        // Always subscribe to agent events for internal handling
+        // (session persistence, extensions, auto-compaction, retry logic)
+        this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
+        // Install tool hooks that await the event queue before emitting extension events.
+        // This ensures extensions always see settled state (e.g., assistant message appended)
+        // even when tools execute in parallel.
+        this._installAgentToolHooks();
+        this._buildRuntime({
+            activeToolNames: this._initialActiveToolNames,
+            includeAllExtensionTools: true,
+        });
+    }
+    /** Model registry for API key resolution and model discovery */
+    get modelRegistry() {
+        return this._modelRegistry;
+    }
+    /** Fallback resolver for cross-provider fallback */
+    get fallbackResolver() {
+        return this._fallbackResolver;
+    }
+    // =========================================================================
+    // Event Subscription
+    // =========================================================================
+    /** Emit an event to all listeners */
+    _emit(event) {
+        for (const l of this._eventListeners) {
+            l(event);
+        }
+    }
+    _emitSessionStateChanged(reason) {
+        this._emit({ type: "session_state_changed", reason });
+    }
+    _createRetryPromiseForAgentEnd(event) {
+        if (event.type !== "agent_end")
+            return;
+        // AgentMessage[] satisfies the { role: string; [key: string]: unknown }[] shape at runtime.
+        this._retryHandler.createRetryPromiseForAgentEnd(event.messages);
+    }
+    async _processAgentEvent(event) {
+        // When a user message starts, check if it's from either queue and remove it BEFORE emitting
+        // This ensures the UI sees the updated queue state
+        if (event.type === "message_start" && event.message.role === "user") {
+            this._compactionOrchestrator.resetOverflowRecovery();
+            const messageText = this._getUserMessageText(event.message);
+            if (messageText) {
+                // Check steering queue first
+                const steeringIndex = this._steeringMessages.indexOf(messageText);
+                if (steeringIndex !== -1) {
+                    this._steeringMessages.splice(steeringIndex, 1);
+                }
+                else {
+                    // Check follow-up queue
+                    const followUpIndex = this._followUpMessages.indexOf(messageText);
+                    if (followUpIndex !== -1) {
+                        this._followUpMessages.splice(followUpIndex, 1);
+                    }
+                }
+            }
+        }
+        // Emit to extensions first
+        await this._emitExtensionEvent(event);
+        // Notify all listeners
+        this._emit(event);
+        // Handle session persistence
+        if (event.type === "message_end") {
+            // Check if this is a custom message from extensions
+            if (event.message.role === "custom") {
+                // Persist as CustomMessageEntry
+                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") {
+                // Regular LLM message - persist as SessionMessageEntry
+                this.sessionManager.appendMessage(event.message);
+            }
+            // Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere
+            // Track assistant message for auto-compaction (checked on agent_end)
+            if (event.message.role === "assistant") {
+                this._lastAssistantMessage = event.message;
+                // Accumulate session stats that survive compaction (#1423)
+                const assistantMsg = event.message;
+                this._lastTurnCost = assistantMsg.usage?.cost?.total ?? 0;
+                this._cumulativeCost += assistantMsg.usage?.cost?.total ?? 0;
+                this._cumulativeInputTokens += assistantMsg.usage?.input ?? 0;
+                this._cumulativeOutputTokens += assistantMsg.usage?.output ?? 0;
+                this._cumulativeToolCalls += assistantMsg.content.filter((c) => c.type === "toolCall").length;
+                if (assistantMsg.stopReason !== "error") {
+                    this._compactionOrchestrator.clearOverflowRecovery();
+                }
+                // Reset retry counter immediately on successful assistant response
+                // This prevents accumulation across multiple LLM calls within a turn
+                if (assistantMsg.stopReason !== "error") {
+                    this._retryHandler.handleSuccessfulResponse();
+                }
+            }
+        }
+        // Check auto-retry and auto-compaction after agent completes
+        if (event.type === "agent_end" && this._lastAssistantMessage) {
+            const msg = this._lastAssistantMessage;
+            this._lastAssistantMessage = undefined;
+            // Check for retryable errors first (overloaded, rate limit, server errors)
+            if (this._retryHandler.isRetryableError(msg)) {
+                const didRetry = await this._retryHandler.handleRetryableError(msg);
+                if (didRetry)
+                    return; // Retry was initiated, don't proceed to compaction
+            }
+            // Check for image dimension overflow (many-image 400 error).
+            // When a session accumulates many images, the API rejects requests
+            // whose images exceed the many-image dimension limit. Strip older
+            // images from the conversation and auto-retry. (#2874)
+            if (msg.stopReason === "error" &&
+                isImageDimensionError(msg.errorMessage)) {
+                const messages = this.agent.state.messages;
+                const result = downsizeConversationImages(messages);
+                if (result.processed) {
+                    // Remove the trailing error assistant message, then replace
+                    if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
+                        this.agent.state.messages = messages.slice(0, -1);
+                    }
+                    this._emit({
+                        type: "image_overflow_recovery",
+                        strippedCount: result.strippedCount,
+                        imageCount: result.imageCount,
+                    });
+                    // Auto-retry after downsizing
+                    setTimeout(() => {
+                        this.agent.continue().catch(() => { });
+                    }, 0);
+                    return;
+                }
+            }
+            await this._compactionOrchestrator.checkCompaction(msg);
+        }
+    }
+    /**
+     * Install beforeToolCall/afterToolCall hooks on the Agent.
+     *
+     * These hooks await `_agentEventQueue` before emitting extension events,
+     * ensuring that all prior events (including `message_end` which appends
+     * the assistant message) have fully settled. This prevents a race condition
+     * in parallel tool execution where extension `tool_call` handlers could
+     * see stale agent state.
+     */
+    _installAgentToolHooks() {
+        this.agent.setBeforeToolCall(async ({ toolCall, args }) => {
+            // Wait for all queued agent events to settle before emitting to extensions
+            await this._agentEventQueue;
+            if (!this._extensionRunner?.hasHandlers("tool_call"))
+                return undefined;
+            try {
+                const callResult = await this._extensionRunner.emitToolCall({
+                    type: "tool_call",
+                    toolName: toolCall.name,
+                    toolCallId: toolCall.id,
+                    input: args,
+                });
+                if (callResult?.block) {
+                    return {
+                        block: true,
+                        reason: callResult.reason || "Tool execution was blocked by an extension",
+                    };
+                }
+            }
+            catch (err) {
+                return { block: true, reason: err instanceof Error ? err.message : `Extension failed, blocking execution: ${String(err)}` };
+            }
+            return undefined;
+        });
+        this.agent.setAfterToolCall(async ({ toolCall, args, result, isError }) => {
+            // Wait for all queued agent events to settle
+            await this._agentEventQueue;
+            if (!this._extensionRunner?.hasHandlers("tool_result"))
+                return undefined;
+            const resultResult = await this._extensionRunner.emitToolResult({
+                type: "tool_result",
+                toolName: toolCall.name,
+                toolCallId: toolCall.id,
+                input: args,
+                content: result.content,
+                details: result.details,
+                isError,
+            });
+            if (resultResult) {
+                return {
+                    content: resultResult.content ?? undefined,
+                    details: resultResult.details ?? undefined,
+                };
+            }
+            return undefined;
+        });
+    }
+    /** 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._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);
+            this._turnIndex++;
+        }
+        else if (event.type === "message_start") {
+            const extensionEvent = {
+                type: "message_start",
+                message: event.message,
+            };
+            await this._extensionRunner.emit(extensionEvent);
+        }
+        else if (event.type === "message_update") {
+            const extensionEvent = {
+                type: "message_update",
+                message: event.message,
+                assistantMessageEvent: event.assistantMessageEvent,
+            };
+            await this._extensionRunner.emit(extensionEvent);
+        }
+        else if (event.type === "message_end") {
+            const extensionEvent = {
+                type: "message_end",
+                message: event.message,
+            };
+            await this._extensionRunner.emit(extensionEvent);
+        }
+        else if (event.type === "tool_execution_start") {
+            const extensionEvent = {
+                type: "tool_execution_start",
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+                args: event.args,
+            };
+            await this._extensionRunner.emit(extensionEvent);
+        }
+        else if (event.type === "tool_execution_update") {
+            const extensionEvent = {
+                type: "tool_execution_update",
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+                args: event.args,
+                partialResult: event.partialResult,
+            };
+            await this._extensionRunner.emit(extensionEvent);
+        }
+        else if (event.type === "tool_execution_end") {
+            const extensionEvent = {
+                type: "tool_execution_end",
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+                result: event.result,
+                isError: event.isError,
+            };
+            await this._extensionRunner.emit(extensionEvent);
+        }
+    }
+    // =========================================================================
+    // Session State Snapshot / Restore (D-14)
+    // =========================================================================
+    /**
+     * Capture a shallow snapshot of listener and message state before a session transition.
+     * Used by _restoreState() to re-attach listeners and message arrays after the transition
+     * tears down and recreates the runtime.
+     */
+    _snapshotState() {
+        return {
+            listeners: [...this._eventListeners],
+            steering: [...this._steeringMessages],
+            followUp: [...this._followUpMessages],
+            pending: [...this._pendingNextTurnMessages],
+        };
+    }
+    /**
+     * Restore listener and message state after a session transition has completed.
+     * Re-registers all event listeners captured by _snapshotState() on this session
+     * and restores the pending message arrays.
+     */
+    _restoreState(snapshot) {
+        this._eventListeners = snapshot.listeners;
+        this._steeringMessages = snapshot.steering;
+        this._followUpMessages = snapshot.followUp;
+        this._pendingNextTurnMessages = snapshot.pending;
+    }
+    // =========================================================================
+    // AgentSessionRuntime Factory (D-12)
+    // =========================================================================
+    /**
+     * Create and return a CreateAgentSessionRuntimeFactory closure that captures this
+     * AgentSession. When the factory is called by AgentSessionRuntime (after teardown),
+     * it re-initialises this session's internal state to match the incoming sessionManager
+     * and sessionStartEvent, then returns a CreateAgentSessionRuntimeResult wrapping this
+     * session so AgentSessionRuntime can track it.
+     *
+     * The factory is kept alive on _runtime and reused for all subsequent transitions.
+     */
+    _createRuntimeFactory() {
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const gsdSession = this;
+        return async (options) => {
+            const reason = options.sessionStartEvent?.reason ?? "new";
+            const previousCwd = gsdSession._cwd;
+            gsdSession._cwd = options.cwd;
+            // Apply the incoming sessionManager state to the GSD session's readonly SM.
+            // options.sessionManager has already been wired up by the runtime caller
+            // (SessionManager.create / open / createBranchedSession). Mirror the same
+            // state into gsdSession.sessionManager so GSD's SM stays authoritative.
+            if (reason === "resume") {
+                const targetFile = options.sessionManager.getSessionFile();
+                if (targetFile) {
+                    gsdSession.sessionManager.setSessionFile(targetFile);
+                }
+            }
+            // For "new" and "fork" the sessionManager was already mutated by the GSD
+            // transition method before calling _runtime (see newSession / fork callers).
+            // No extra SM mutation is needed here.
+            gsdSession.agent.sessionId = gsdSession.sessionManager.getSessionId();
+            // Rebuild tools if cwd changed, otherwise refresh registry (#633, #3616).
+            if (gsdSession._cwd !== previousCwd) {
+                gsdSession._buildRuntime({
+                    activeToolNames: gsdSession.getActiveToolNames(),
+                    includeAllExtensionTools: true,
+                });
+            }
+            else {
+                gsdSession._refreshToolRegistry({
+                    activeToolNames: gsdSession.getActiveToolNames(),
+                    includeAllExtensionTools: true,
+                });
+            }
+            gsdSession._reconnectToAgent();
+            // Emit session_start to extensions (Pitfall 7: single emission point).
+            if (options.sessionStartEvent && gsdSession._extensionRunner) {
+                await gsdSession._extensionRunner.emit(options.sessionStartEvent);
+            }
+            // Build a minimal AgentSessionServices compatible object from what GSD
+            // already holds — pi's runtime uses this for cwd tracking and process.chdir.
+            const services = {
+                cwd: options.cwd,
+                agentDir: options.agentDir,
+                authStorage: gsdSession._modelRegistry.authStorage,
+                settingsManager: gsdSession.settingsManager,
+                modelRegistry: gsdSession._modelRegistry,
+                resourceLoader: gsdSession._resourceLoader,
+                diagnostics: [],
+            };
+            return {
+                // Cast: GSD's AgentSession is structurally compatible with pi's AgentSession
+                // (same fields: agent, sessionManager, extensionRunner, sessionFile, dispose).
+                // Nominal incompatibility arises only from different module paths.
+                session: gsdSession,
+                services,
+                diagnostics: [],
+                extensionsResult: gsdSession._resourceLoader.getExtensions(),
+            };
+        };
+    }
+    /**
+     * Ensure _runtime is initialised. Creates it lazily on first session transition
+     * using createAgentSessionRuntime so that the runtime's factory is wired once
+     * and reused for all subsequent newSession / switchSession / fork calls.
+     *
+     * The initial call uses the current session state — no actual session reset occurs
+     * on first init because the session is already live.
+     */
+    async _ensureRuntime() {
+        if (this._runtime)
+            return this._runtime;
+        const factory = this._createRuntimeFactory();
+        // Prefer the agentDir stored on DefaultResourceLoader (runtime property) or
+        // fall back to the global getAgentDir() helper imported from @gsd/pi-coding-agent.
+        const agentDir = this._resourceLoader.agentDir ?? getAgentDir();
+        // Build minimal services for the initial runtime construction.
+        const services = {
+            cwd: this._cwd,
+            agentDir,
+            authStorage: this._modelRegistry.authStorage,
+            settingsManager: this.settingsManager,
+            modelRegistry: this._modelRegistry,
+            resourceLoader: this._resourceLoader,
+            diagnostics: [],
+        };
+        // createAgentSessionRuntime calls factory once to build the initial result.
+        // We pass a factory that short-circuits on the first call (init-only) because
+        // the session is already live — no teardown/rebuild needed.
+        let initDone = false;
+        const initFactory = async (opts) => {
+            if (!initDone) {
+                initDone = true;
+                // First call: session already live, just return current state.
+                return {
+                    session: this,
+                    services,
+                    diagnostics: [],
+                    extensionsResult: this._resourceLoader.getExtensions(),
+                };
+            }
+            // Subsequent calls: delegate to the real factory.
+            return factory(opts);
+        };
+        this._runtime = await createAgentSessionRuntime(initFactory, {
+            cwd: this._cwd,
+            agentDir,
+            sessionManager: this.sessionManager,
+        });
+        // Replace the one-shot initFactory with the real factory so all future
+        // transitions go through the proper path.
+        // vendor-seam: dual-module-path — AgentSessionRuntime does not expose a public
+        // createRuntime setter. Required for one-shot init to factory transition.
+        // Bounded to this single call site.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- vendor-seam: dual-module-path, no public setter available
+        this._runtime /* vendor-seam: dual-module-path */["createRuntime"] = factory;
+        return this._runtime;
+    }
+    /**
+     * 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._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
+    }
+    /**
+     * Remove all listeners and disconnect from agent.
+     * Call this when completely done with the session.
+     */
+    dispose() {
+        this._extensionErrorUnsubscriber?.();
+        this._extensionErrorUnsubscriber = undefined;
+        this._disconnectFromAgent();
+        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 effective system prompt (includes any per-turn extension modifications) */
+    get systemPrompt() {
+        return this.agent.state.systemPrompt;
+    }
+    /** Current retry attempt (0 if not retrying) */
+    get retryAttempt() {
+        return this._retryHandler.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, description, and parameter schema.
+     */
+    getAllTools() {
+        return Array.from(this._toolRegistry.values()).map((t) => ({
+            name: t.name,
+            description: t.description,
+            parameters: t.parameters,
+            sourceInfo: { path: "", source: "builtin", scope: "temporary", origin: "top-level" },
+        }));
+    }
+    /**
+     * 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 requestedToolNames = [...new Set([...toolNames, ...this._getBuiltinToolNames()])];
+        const tools = [];
+        const validToolNames = [];
+        for (const name of requestedToolNames) {
+            const tool = this._toolRegistry.get(name);
+            if (tool) {
+                tools.push(tool);
+                validToolNames.push(name);
+            }
+        }
+        this.agent.state.tools = tools;
+        // Rebuild base system prompt with new tool set
+        this._baseSystemPrompt = this._rebuildSystemPrompt(validToolNames);
+        this.agent.state.systemPrompt = this._baseSystemPrompt;
+    }
+    /** Whether compaction or branch summarization is currently running */
+    get isCompacting() {
+        return this._compactionOrchestrator.isCompacting;
+    }
+    /**
+     * Switch edit mode between standard (text-match) and hashline (LINE#ID anchors).
+     * Swaps the active read/edit tools and rebuilds the system prompt.
+     */
+    setEditMode(mode) {
+        this.settingsManager.setEditMode(mode);
+        // Get current active tool registry keys
+        const currentKeys = new Set();
+        for (const [key, tool] of this._toolRegistry.entries()) {
+            if (this.agent.state.tools.includes(tool)) {
+                currentKeys.add(key);
+            }
+        }
+        // Swap read tools
+        if (mode === "hashline") {
+            currentKeys.delete("read");
+            currentKeys.add("hashline_read");
+            currentKeys.delete("edit");
+            currentKeys.add("hashline_edit");
+        }
+        else {
+            currentKeys.delete("hashline_read");
+            currentKeys.add("read");
+            currentKeys.delete("hashline_edit");
+            currentKeys.add("edit");
+        }
+        this.setActiveToolsByName([...currentKeys]);
+    }
+    /** Current edit mode */
+    get editMode() {
+        return this.settingsManager.getEditMode();
+    }
+    /** 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();
+    }
+    /** Current session display name, if set */
+    get sessionName() {
+        return this.sessionManager.getSessionName();
+    }
+    /** 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;
+    }
+    _normalizePromptSnippet(text) {
+        if (!text)
+            return undefined;
+        const oneLine = text
+            .replace(/[\r\n]+/g, " ")
+            .replace(/\s+/g, " ")
+            .trim();
+        return oneLine.length > 0 ? oneLine : undefined;
+    }
+    _normalizePromptGuidelines(guidelines) {
+        if (!guidelines || guidelines.length === 0) {
+            return [];
+        }
+        const unique = new Set();
+        for (const guideline of guidelines) {
+            const normalized = guideline.trim();
+            if (normalized.length > 0) {
+                unique.add(normalized);
+            }
+        }
+        return Array.from(unique);
+    }
+    _findSkillByName(skillName) {
+        return this.resourceLoader.getSkills().skills.find((skill) => skill.name === skillName);
+    }
+    _formatMissingSkillMessage(skillName) {
+        const availableSkills = this.resourceLoader.getSkills().skills.map((skill) => skill.name).join(", ") || "(none)";
+        return `Skill "${skillName}" not found. Available skills: ${availableSkills}`;
+    }
+    _emitSkillExpansionError(skillFilePath, err) {
+        this._extensionRunner?.emitError({
+            extensionPath: skillFilePath,
+            event: "skill_expansion",
+            error: getErrorMessage(err),
+        });
+    }
+    _renderSkillInvocation(skill, args) {
+        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 && args.trim() ? `${skillBlock}\n\n${args.trim()}` : skillBlock;
+    }
+    _expandSkillByName(skillName, args) {
+        const skill = this._findSkillByName(skillName);
+        if (!skill) {
+            throw new Error(this._formatMissingSkillMessage(skillName));
+        }
+        try {
+            return this._renderSkillInvocation(skill, args);
+        }
+        catch (err) {
+            this._emitSkillExpansionError(skill.filePath, err);
+            throw err;
+        }
+    }
+    _formatSkillInvocation(skillName, args) {
+        return this._expandSkillByName(skillName, args);
+    }
+    _rebuildSystemPrompt(toolNames) {
+        const validToolNames = toolNames.filter((name) => this._toolRegistry.has(name));
+        const toolSnippets = {};
+        const promptGuidelines = [];
+        for (const name of validToolNames) {
+            const snippet = this._toolPromptSnippets.get(name);
+            if (snippet) {
+                toolSnippets[name] = snippet;
+            }
+            const toolGuidelines = this._toolPromptGuidelines.get(name);
+            if (toolGuidelines) {
+                promptGuidelines.push(...toolGuidelines);
+            }
+        }
+        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,
+            toolSnippets,
+            promptGuidelines,
+        });
+    }
+    // =========================================================================
+    // Prompting
+    // =========================================================================
+    /**
+     * Send a prompt to the agent.
+     * - Handles extension commands (registered via pi.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 pi.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, currentImages);
+            }
+            else {
+                await this._queueSteer(expandedText, currentImages);
+            }
+            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(), "providers.md")}\n\n` +
+                "Then use /model to select a model.");
+        }
+        // Check if a higher-priority provider in the fallback chain has recovered
+        const restoration = await this._fallbackResolver.checkForRestoration(this.model);
+        if (restoration) {
+            const previousProvider = `${this.model.provider}/${this.model.id}`;
+            this.agent.state.model = restoration.model;
+            this.sessionManager.appendModelChange(restoration.model.provider, restoration.model.id);
+            this._emit({
+                type: "fallback_provider_restored",
+                provider: `${restoration.model.provider}/${restoration.model.id}`,
+                reason: `Restored from ${previousProvider}`,
+            });
+        }
+        // Validate provider readiness
+        if (!this._modelRegistry.isProviderRequestReady(this.model.provider)) {
+            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(), "providers.md")}`);
+        }
+        // Check if we need to compact before sending (catches aborted responses)
+        const lastAssistant = this._findLastAssistantMessage();
+        if (lastAssistant) {
+            await this._compactionOrchestrator.checkCompaction(lastAssistant, false);
+        }
+        // Build messages array (custom message if any, then user message)
+        const messages = [];
+        // Add user message
+        const userContent = [{ type: "text", text: expandedText }];
+        if (currentImages) {
+            userContent.push(...currentImages);
+        }
+        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.state.systemPrompt = result.systemPrompt;
+            }
+            else {
+                // Ensure we're using the base prompt (in case previous turn had modifications)
+                this.agent.state.systemPrompt = this._baseSystemPrompt;
+            }
+        }
+        await this.agent.prompt(messages);
+        await this._retryHandler.waitForRetry();
+    }
+    /**
+     * 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 {
+            await command.handler(args, ctx);
+            return true;
+        }
+        catch (err) {
+            // Emit error via extension runner
+            this._extensionRunner.emitError({
+                extensionPath: `command:${commandName}`,
+                event: "command",
+                error: getErrorMessage(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();
+        if (!this._findSkillByName(skillName))
+            return text;
+        try {
+            return this._formatSkillInvocation(skillName, args);
+        }
+        catch {
+            return text;
+        }
+    }
+    _createBuiltInSkillTool() {
+        const skillSchema = Type.Object({
+            skill: Type.String({ description: "The skill name. E.g., 'commit', 'review-pr', or 'pdf'" }),
+            args: Type.Optional(Type.String({ description: "Optional arguments for the skill" })),
+        });
+        return {
+            name: "Skill",
+            label: "Skill",
+            description: "Execute a skill within the main conversation. Use this tool when users ask for a slash command or reference a skill by name. Returns the expanded skill block and appends args after it.",
+            parameters: skillSchema,
+            execute: async (_toolCallId, params) => {
+                const input = params;
+                try {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: this._expandSkillByName(input.skill, input.args),
+                            },
+                        ],
+                        details: undefined,
+                    };
+                }
+                catch (err) {
+                    return {
+                        content: [{ type: "text", text: getErrorMessage(err) }],
+                        details: undefined,
+                    };
+                }
+            },
+        };
+    }
+    _getBuiltinToolNames() {
+        return this._getBuiltinTools().map((tool) => tool.name);
+    }
+    _getBuiltinTools() {
+        return [this._createBuiltInSkillTool()];
+    }
+    _getRegisteredToolDefinitions() {
+        const registeredTools = this._extensionRunner?.getAllRegisteredTools() ?? [];
+        return registeredTools.map((tool) => tool.definition);
+    }
+    _getBuiltinToolDefinitions() {
+        return this._getBuiltinTools().map((tool) => ({
+            name: tool.name,
+            label: tool.label,
+            description: tool.description,
+            parameters: tool.parameters,
+            execute: async () => ({ content: [], details: undefined }),
+        }));
+    }
+    getRenderableToolDefinition(toolName) {
+        const normalizedToolName = toolName.toLowerCase();
+        return [...this._getBuiltinToolDefinitions(), ...this._getRegisteredToolDefinitions()].find((tool) => tool.name.toLowerCase() === normalizedToolName);
+    }
+    /**
+     * 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.
+     * @param images Optional image attachments to include with the message
+     * @throws Error if text is an extension command
+     */
+    async steer(text, images) {
+        // 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, images);
+    }
+    /**
+     * 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.
+     * @param images Optional image attachments to include with the message
+     * @throws Error if text is an extension command
+     */
+    async followUp(text, images) {
+        // 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, images);
+    }
+    /**
+     * Internal: Queue a steering message (already expanded, no extension command check).
+     */
+    async _queueSteer(text, images) {
+        this._steeringMessages.push(text);
+        const content = [{ type: "text", text }];
+        if (images) {
+            content.push(...images);
+        }
+        this.agent.steer({
+            role: "user",
+            content,
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Internal: Queue a follow-up message (already expanded, no extension command check).
+     */
+    async _queueFollowUp(text, images) {
+        this._followUpMessages.push(text);
+        const content = [{ type: "text", text }];
+        if (images) {
+            content.push(...images);
+        }
+        this.agent.followUp({
+            role: "user",
+            content,
+            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.state.messages = [...this.agent.state.messages, 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() {
+        // In 0.67.2, drainUserMessages() was removed. Agent queues no longer distinguish
+        // user-origin messages from system messages. Clear all queues and return
+        // the session-tracked string arrays for display purposes.
+        const steering = [...this._steeringMessages];
+        const followUp = [...this._followUpMessages];
+        this._steeringMessages = [];
+        this._followUpMessages = [];
+        // Clear all agent queues
+        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._retryHandler.abortRetry();
+        this.agent.abort();
+        await this.agent.waitForIdle();
+        // Ensure agent_end is emitted even when abort interrupts a tool call (#1414).
+        // The agent may go idle without emitting agent_end if the abort happens
+        // between tool execution and response processing.
+        if (!this.isStreaming && this._extensionRunner) {
+            await this._extensionRunner.emit({
+                type: "agent_end",
+                messages: this.agent.state.messages,
+            });
+        }
+    }
+    /**
+     * 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.parentSession - Optional parent session path for tracking
+     * @param options.setup - Optional callback to initialize session (e.g., append messages)
+     * @returns true if completed, false if cancelled by extension
+     */
+    async newSession(options) {
+        // Snapshot state before transition so listeners and message queues survive (D-14).
+        const snapshot = this._snapshotState();
+        const _previousSessionFile = this.sessionFile;
+        // 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;
+            }
+        }
+        // Mutate sessionManager in place BEFORE calling the runtime so the factory
+        // can call getSessionId() on the already-updated SM.
+        this.sessionManager.newSession({ parentSession: options?.parentSession });
+        this.sessionManager.appendThinkingLevelChange(this.thinkingLevel);
+        // #4243: Must call abort() BEFORE _disconnectFromAgent() so that
+        // message_end/agent_end events fire and the #4216 finalization code
+        // can run before we unsubscribe from the event bus.
+        await this.abort();
+        this._disconnectFromAgent();
+        this.agent.reset();
+        // Delegate to AgentSessionRuntime for lifecycle coordination (D-12).
+        // The factory (_createRuntimeFactory) re-initialises this session's internals
+        // (cwd update, tool rebuild, agent reconnect, session_start emission).
+        const runtime = await this._ensureRuntime();
+        const result = await runtime.newSession({
+            parentSession: options?.parentSession,
+            setup: options?.setup,
+        });
+        if (result.cancelled) {
+            return false;
+        }
+        // Restore listener and message queue state that survived the transition (D-14).
+        this._restoreState(snapshot);
+        // Emit session event to custom tools
+        this._emitSessionStateChanged("new_session");
+        return true;
+    }
+    // =========================================================================
+    // 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,
+        });
+    }
+    /**
+     * Apply a model change: set the model on the agent, persist to session/settings,
+     * re-clamp thinking level, and emit the model_select event.
+     */
+    async _applyModelChange(model, thinkingLevel, source, options) {
+        const previousModel = this.model;
+        // Explicit model switches must cancel any in-flight retry loop from the
+        // previous provider/model. Otherwise stale provider backoff errors can
+        // continue to land after the user or runtime has already switched models.
+        this._retryHandler.abortRetry();
+        this.agent.state.model = model;
+        this.sessionManager.appendModelChange(model.provider, model.id);
+        if (options?.persist !== false) {
+            this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);
+        }
+        this.setThinkingLevel(thinkingLevel);
+        await this._emitModelSelect(model, previousModel, source);
+        this._emitSessionStateChanged("set_model");
+    }
+    /**
+     * Set model directly.
+     * Validates provider readiness, saves to session and settings.
+     * @throws Error if provider is not ready (missing credentials for apiKey/oauth providers)
+     */
+    async setModel(model, options) {
+        if (!this._modelRegistry.isProviderRequestReady(model.provider)) {
+            throw new Error(`No API key for ${model.provider}/${model.id}`);
+        }
+        const thinkingLevel = this._getThinkingLevelForModelSwitch();
+        await this._applyModelChange(model, thinkingLevel, "set", options);
+    }
+    /**
+     * 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", options) {
+        if (this._scopedModels.length > 0) {
+            return this._cycleScopedModel(direction, options);
+        }
+        return this._cycleAvailableModel(direction, options);
+    }
+    _getReadyScopedModels() {
+        return this._scopedModels.filter((scoped) => this._modelRegistry.isProviderRequestReady(scoped.model.provider));
+    }
+    async _cycleScopedModel(direction, options) {
+        const scopedModels = this._getReadyScopedModels();
+        if (scopedModels.length <= 1)
+            return undefined;
+        const currentModel = this.model;
+        let currentIndex = scopedModels.findIndex((sm) => modelsAreEqual(sm.model, currentModel));
+        if (currentIndex === -1)
+            currentIndex = 0;
+        const len = scopedModels.length;
+        const nextIndex = direction === "forward" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;
+        const next = scopedModels[nextIndex];
+        // Explicit scoped model thinking level overrides current session level;
+        // undefined scoped model thinking level inherits the current session preference.
+        const thinkingLevel = this._getThinkingLevelForModelSwitch(next.thinkingLevel);
+        await this._applyModelChange(next.model, thinkingLevel, "cycle", options);
+        return { model: next.model, thinkingLevel: this.thinkingLevel, isScoped: true };
+    }
+    async _cycleAvailableModel(direction, options) {
+        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 thinkingLevel = this._getThinkingLevelForModelSwitch();
+        await this._applyModelChange(nextModel, thinkingLevel, "cycle", options);
+        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 only if the level actually changes.
+     */
+    setThinkingLevel(level) {
+        const availableLevels = this.getAvailableThinkingLevels();
+        const effectiveLevel = availableLevels.includes(level) ? level : this._clampThinkingLevel(level, availableLevels);
+        // Only persist if actually changing
+        const isChanging = effectiveLevel !== this.agent.state.thinkingLevel;
+        this.agent.state.thinkingLevel = effectiveLevel;
+        if (isChanging) {
+            this.sessionManager.appendThinkingLevelChange(effectiveLevel);
+            if (this.supportsThinking() || effectiveLevel !== "off") {
+                this.settingsManager.setDefaultThinkingLevel(effectiveLevel);
+            }
+            this._emitSessionStateChanged("set_thinking_level");
+        }
+    }
+    /**
+     * 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;
+    }
+    _getThinkingLevelForModelSwitch(explicitLevel) {
+        if (explicitLevel !== undefined) {
+            return explicitLevel;
+        }
+        if (!this.supportsThinking()) {
+            return this.settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL;
+        }
+        return this.thinkingLevel;
+    }
+    _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);
+        this._emitSessionStateChanged("set_steering_mode");
+    }
+    /**
+     * Set follow-up message mode.
+     * Saves to settings.
+     */
+    setFollowUpMode(mode) {
+        this.agent.setFollowUpMode(mode);
+        this.settingsManager.setFollowUpMode(mode);
+        this._emitSessionStateChanged("set_follow_up_mode");
+    }
+    // =========================================================================
+    // Compaction
+    // =========================================================================
+    /**
+     * Manually compact the session context.
+     * Aborts current agent operation first.
+     * @param customInstructions Optional instructions for the compaction summary
+     */
+    async compact(customInstructions) {
+        return this._compactionOrchestrator.compact(customInstructions);
+    }
+    /** Cancel in-progress compaction (manual or auto) */
+    abortCompaction() {
+        this._compactionOrchestrator.abortCompaction();
+    }
+    /** Cancel in-progress branch summarization */
+    abortBranchSummary() {
+        this._compactionOrchestrator.abortBranchSummary();
+    }
+    /** Toggle auto-compaction setting */
+    setAutoCompactionEnabled(enabled) {
+        this._compactionOrchestrator.setAutoCompactionEnabled(enabled);
+        this._emitSessionStateChanged("set_auto_compaction");
+    }
+    /** Whether auto-compaction is enabled */
+    get autoCompactionEnabled() {
+        return this._compactionOrchestrator.autoCompactionEnabled;
+    }
+    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 (this._extensionRunner) {
+            this._applyExtensionBindings(this._extensionRunner);
+            await this._extensionRunner.emit({ type: "session_start", reason: "new" });
+            await this.extendResourcesFromExtensions("startup");
+        }
+    }
+    async extendResourcesFromExtensions(reason) {
+        if (!this._extensionRunner?.hasHandlers("resources_discover")) {
+            return;
+        }
+        const { skillPaths, promptPaths, themePaths } = await this._extensionRunner.emitResourcesDiscover(this._cwd, reason);
+        if (skillPaths.length === 0 && promptPaths.length === 0 && themePaths.length === 0) {
+            return;
+        }
+        const extensionPaths = {
+            skillPaths: this.buildExtensionResourcePaths(skillPaths),
+            promptPaths: this.buildExtensionResourcePaths(promptPaths),
+            themePaths: this.buildExtensionResourcePaths(themePaths),
+        };
+        this._resourceLoader.extendResources(extensionPaths);
+        this._baseSystemPrompt = this._rebuildSystemPrompt(this.getActiveToolNames());
+        this.agent.state.systemPrompt = this._baseSystemPrompt;
+    }
+    buildExtensionResourcePaths(entries) {
+        return entries.map((entry) => {
+            const source = this.getExtensionSourceLabel(entry.extensionPath);
+            const baseDir = entry.extensionPath.startsWith("<") ? undefined : dirname(entry.extensionPath);
+            return {
+                path: entry.path,
+                metadata: {
+                    source,
+                    scope: "temporary",
+                    origin: "top-level",
+                    baseDir,
+                },
+            };
+        });
+    }
+    getExtensionSourceLabel(extensionPath) {
+        if (extensionPath.startsWith("<")) {
+            return `extension:${extensionPath.replace(/[<>]/g, "")}`;
+        }
+        const base = basename(extensionPath);
+        const name = base.replace(/\.(ts|js)$/, "");
+        return `extension:${name}`;
+    }
+    _applyExtensionBindings(runner) {
+        runner.setUIContext(this._extensionUIContext);
+        runner.bindCommandContext(this._extensionCommandContextActions);
+        try {
+            this._extensionErrorUnsubscriber?.();
+        }
+        catch {
+            // Ignore errors from previous unsubscriber
+        }
+        this._extensionErrorUnsubscriber = this._extensionErrorListener
+            ? runner.onError(this._extensionErrorListener)
+            : undefined;
+    }
+    _bindExtensionCore(runner) {
+        const reservedBuiltins = new Set(BUILTIN_SLASH_COMMANDS.map((command) => command.name));
+        const getCommands = () => {
+            const extensionCommands = runner
+                .getRegisteredCommands()
+                .filter((command) => !reservedBuiltins.has(command.name))
+                .map((command) => ({
+                name: command.name,
+                description: command.description,
+                source: "extension",
+                sourceInfo: command.sourceInfo,
+            }));
+            const templates = this.promptTemplates.map((template) => ({
+                name: template.name,
+                description: template.description,
+                source: "prompt",
+                sourceInfo: template.sourceInfo,
+            }));
+            const skills = this._resourceLoader.getSkills().skills.map((skill) => ({
+                name: `skill:${skill.name}`,
+                description: skill.description,
+                source: "skill",
+                sourceInfo: skill.sourceInfo,
+            }));
+            return [...extensionCommands, ...templates, ...skills];
+        };
+        runner.bindCore({
+            sendMessage: (message, options) => {
+                this.sendCustomMessage(message, options).catch((err) => {
+                    runner.emitError({
+                        extensionPath: "<runtime>",
+                        event: "send_message",
+                        error: getErrorMessage(err),
+                    });
+                });
+            },
+            sendUserMessage: (content, options) => {
+                this.sendUserMessage(content, options).catch((err) => {
+                    runner.emitError({
+                        extensionPath: "<runtime>",
+                        event: "send_user_message",
+                        error: getErrorMessage(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),
+            refreshTools: () => this._refreshToolRegistry(),
+            getCommands,
+            setModel: async (model) => {
+                if (!this.modelRegistry.isProviderRequestReady(model.provider))
+                    return false;
+                await this.setModel(model);
+                return true;
+            },
+            getThinkingLevel: () => this.thinkingLevel,
+            setThinkingLevel: (level) => this.setThinkingLevel(level),
+            retryLastTurn: () => {
+                void this.agent.continue();
+            },
+        }, {
+            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);
+                    }
+                })();
+            },
+            getSystemPrompt: () => this.systemPrompt,
+        });
+    }
+    _refreshToolRegistry(options) {
+        const previousRegistryNames = new Set(this._toolRegistry.keys());
+        const previousActiveToolNames = this.getActiveToolNames();
+        const registeredTools = this._extensionRunner?.getAllRegisteredTools() ?? [];
+        const allCustomTools = [
+            ...registeredTools,
+            ...this._customTools.map((def) => ({
+                definition: def,
+                extensionPath: "<sdk>",
+            })),
+        ];
+        this._toolPromptSnippets = new Map(allCustomTools
+            .map((registeredTool) => {
+            const snippet = this._normalizePromptSnippet(registeredTool.definition.promptSnippet ?? registeredTool.definition.description);
+            return snippet ? [registeredTool.definition.name, snippet] : undefined;
+        })
+            .filter((entry) => entry !== undefined));
+        this._toolPromptGuidelines = new Map(allCustomTools
+            .map((registeredTool) => {
+            const guidelines = this._normalizePromptGuidelines(registeredTool.definition.promptGuidelines);
+            return guidelines.length > 0 ? [registeredTool.definition.name, guidelines] : undefined;
+        })
+            .filter((entry) => entry !== undefined));
+        const wrappedExtensionTools = this._extensionRunner
+            ? wrapRegisteredTools(allCustomTools, this._extensionRunner)
+            : [];
+        const builtinTools = this._getBuiltinTools();
+        const toolRegistry = new Map(this._baseToolRegistry);
+        for (const tool of builtinTools) {
+            toolRegistry.set(tool.name, tool);
+        }
+        for (const tool of wrappedExtensionTools) {
+            toolRegistry.set(tool.name, tool);
+        }
+        // Tool interception (tool_call/tool_result extension events) is handled by
+        // beforeToolCall/afterToolCall hooks installed in _installAgentToolHooks(),
+        // which await _agentEventQueue for safe parallel execution.
+        this._toolRegistry = toolRegistry;
+        const nextActiveToolNames = options?.activeToolNames
+            ? [...options.activeToolNames]
+            : [...previousActiveToolNames];
+        if (options?.includeAllExtensionTools) {
+            for (const tool of wrappedExtensionTools) {
+                nextActiveToolNames.push(tool.name);
+            }
+        }
+        else if (!options?.activeToolNames) {
+            for (const toolName of this._toolRegistry.keys()) {
+                if (!previousRegistryNames.has(toolName)) {
+                    nextActiveToolNames.push(toolName);
+                }
+            }
+        }
+        this.setActiveToolsByName([...new Set(nextActiveToolNames)]);
+    }
+    _buildRuntime(options) {
+        const autoResizeImages = this.settingsManager.getImageAutoResize();
+        const shellCommandPrefix = this.settingsManager.getShellCommandPrefix();
+        const baseTools = this._baseToolsOverride
+            ? this._baseToolsOverride
+            : createAllTools(this._cwd, {
+                read: { autoResizeImages },
+                bash: {
+                    commandPrefix: shellCommandPrefix,
+                },
+            });
+        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 defaultActiveToolNames = this._baseToolsOverride
+            ? Object.keys(this._baseToolsOverride)
+            : ["read", "bash", "edit", "write", "lsp"];
+        const baseActiveToolNames = options.activeToolNames ?? defaultActiveToolNames;
+        this._refreshToolRegistry({
+            activeToolNames: baseActiveToolNames,
+            includeAllExtensionTools: options.includeAllExtensionTools,
+        });
+    }
+    async reload() {
+        const previousFlagValues = this._extensionRunner?.getFlagValues();
+        await this._extensionRunner?.emit({ type: "session_shutdown" });
+        this.settingsManager.reload();
+        resetApiProviders();
+        await this._resourceLoader.reload();
+        this._buildRuntime({
+            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", reason: "resume" });
+            await this.extendResourcesFromExtensions("reload");
+        }
+    }
+    // =========================================================================
+    // Auto-Retry (delegated to RetryHandler)
+    // =========================================================================
+    /** Cancel in-progress retry */
+    abortRetry() {
+        const hadRetry = this._retryHandler.isRetrying;
+        this._retryHandler.abortRetry();
+        if (hadRetry) {
+            this._emitSessionStateChanged("abort_retry");
+        }
+    }
+    /** Whether auto-retry is currently in progress */
+    get isRetrying() {
+        return this._retryHandler.isRetrying;
+    }
+    /** Whether auto-retry is enabled */
+    get autoRetryEnabled() {
+        return this._retryHandler.autoRetryEnabled;
+    }
+    /** Toggle auto-retry setting */
+    setAutoRetryEnabled(enabled) {
+        this._retryHandler.setAutoRetryEnabled(enabled);
+        this._emitSessionStateChanged("set_auto_retry");
+    }
+    // =========================================================================
+    // 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) {
+        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;
+        try {
+            const result = options?.operations
+                ? await executeBashWithOperations(resolvedCommand, process.cwd(), options.operations, {
+                    onChunk,
+                    signal: this._bashAbortController.signal,
+                })
+                : await executeBashCommand(resolvedCommand, {
+                    onChunk,
+                    signal: this._bashAbortController.signal,
+                    loginShell: options?.loginShell,
+                });
+            this.recordBashResult(command, result, options);
+            return result;
+        }
+        finally {
+            this._bashAbortController = undefined;
+        }
+    }
+    /**
+     * 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.state.messages = [...this.agent.state.messages, 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.state.messages = [...this.agent.state.messages, 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) {
+        // Snapshot state before transition so listeners and message queues survive (D-14).
+        const snapshot = this._snapshotState();
+        const _previousSessionFile = this.sessionManager.getSessionFile();
+        // 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;
+            }
+        }
+        // #4243: Must call abort() BEFORE _disconnectFromAgent() so that
+        // message_end/agent_end events fire and the #4216 finalization code
+        // can run before we unsubscribe from the event bus.
+        await this.abort();
+        this._disconnectFromAgent();
+        // Delegate to AgentSessionRuntime for lifecycle coordination (D-12).
+        // The factory (_createRuntimeFactory) handles setSessionFile, agent reconnect,
+        // and session_start emission for the "resume" reason.
+        const runtime = await this._ensureRuntime();
+        const result = await runtime.switchSession(sessionPath);
+        if (result.cancelled) {
+            return false;
+        }
+        // Reload messages and restore model/thinking level (GSD-specific logic not in pi runtime).
+        const sessionContext = this.sessionManager.buildSessionContext();
+        this.agent.state.messages = sessionContext.messages;
+        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.state.model = match;
+                await this._emitModelSelect(match, previousModel, "restore");
+            }
+        }
+        const hasThinkingEntry = this.sessionManager.getBranch().some((entry) => entry.type === "thinking_level_change");
+        const defaultThinkingLevel = this.settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL;
+        if (hasThinkingEntry) {
+            // Restore thinking level if saved (setThinkingLevel clamps to model capabilities)
+            this.setThinkingLevel(sessionContext.thinkingLevel);
+        }
+        else {
+            const availableLevels = this.getAvailableThinkingLevels();
+            const effectiveLevel = availableLevels.includes(defaultThinkingLevel)
+                ? defaultThinkingLevel
+                : this._clampThinkingLevel(defaultThinkingLevel, availableLevels);
+            this.agent.state.thinkingLevel = effectiveLevel;
+            this.sessionManager.appendThinkingLevelChange(effectiveLevel);
+        }
+        // Restore listener and message queue state that survived the transition (D-14).
+        this._restoreState(snapshot);
+        this._emitSessionStateChanged("switch_session");
+        return true;
+    }
+    /**
+     * Set a display name for the current session.
+     */
+    setSessionName(name) {
+        this.sessionManager.appendSessionInfo(name);
+        this._emitSessionStateChanged("set_session_name");
+    }
+    /**
+     * 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) {
+        // Snapshot state before transition so listeners and message queues survive (D-14).
+        const snapshot = this._snapshotState();
+        const _previousSessionFile = this.sessionFile;
+        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;
+        }
+        // Mutate sessionManager in place BEFORE calling the runtime (same pattern as newSession).
+        if (!selectedEntry.parentId) {
+            this.sessionManager.newSession({ parentSession: _previousSessionFile });
+        }
+        else {
+            this.sessionManager.createBranchedSession(selectedEntry.parentId);
+        }
+        this.agent.sessionId = this.sessionManager.getSessionId();
+        // Reload messages from entries (works for both file and in-memory mode)
+        const sessionContext = this.sessionManager.buildSessionContext();
+        // Emit session_start event with reason "fork" to extensions (after fork completes).
+        // Ensure _runtime is initialised so the field is live (D-12).
+        await this._ensureRuntime();
+        if (this._extensionRunner) {
+            await this._extensionRunner.emit({
+                type: "session_start",
+            });
+        }
+        if (!skipConversationRestore) {
+            this.agent.state.messages = sessionContext.messages;
+        }
+        // Restore listener and message queue state that survived the transition (D-14).
+        this._restoreState(snapshot);
+        this._emitSessionStateChanged("fork");
+        return { selectedText, cancelled: false };
+    }
+    // =========================================================================
+    // 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._compactionOrchestrator.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._compactionOrchestrator.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;
+            if (!this._modelRegistry.isProviderRequestReady(model.provider)) {
+                throw new Error(`No API key for ${model.provider}`);
+            }
+            const authResult = await this._modelRegistry.getApiKeyAndHeaders(model);
+            const apiKey = authResult.ok ? authResult.apiKey : undefined;
+            const branchSummarySettings = this.settingsManager.getBranchSummarySettings();
+            const result = await generateBranchSummary(entriesToSummarize, {
+                model,
+                apiKey,
+                signal: this._compactionOrchestrator.branchSummaryAbortController.signal,
+                customInstructions,
+                replaceInstructions,
+                reserveTokens: branchSummarySettings.reserveTokens,
+            });
+            this._compactionOrchestrator.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
+        const sessionContext = this.sessionManager.buildSessionContext();
+        this.agent.state.messages = 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._compactionOrchestrator.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: Math.max(toolCalls, this._cumulativeToolCalls),
+            toolResults,
+            totalMessages: state.messages.length,
+            tokens: {
+                input: Math.max(totalInput, this._cumulativeInputTokens),
+                output: Math.max(totalOutput, this._cumulativeOutputTokens),
+                cacheRead: totalCacheRead,
+                cacheWrite: totalCacheWrite,
+                total: Math.max(totalInput + totalOutput, this._cumulativeInputTokens + this._cumulativeOutputTokens) + totalCacheRead + totalCacheWrite,
+            },
+            cost: Math.max(totalCost, this._cumulativeCost),
+        };
+    }
+    /**
+     * Get the cost of the most recent assistant response.
+     * Returns 0 if no assistant message has been received yet.
+     */
+    getLastTurnCost() {
+        return this._lastTurnCost;
+    }
+    getContextUsage() {
+        const model = this.model;
+        if (!model)
+            return undefined;
+        const contextWindow = model.contextWindow ?? 0;
+        if (contextWindow <= 0)
+            return undefined;
+        // After compaction, the last assistant usage reflects pre-compaction context size.
+        // We can only trust usage from an assistant that responded after the latest compaction.
+        // If no such assistant exists, context token count is unknown until the next LLM response.
+        const branchEntries = this.sessionManager.getBranch();
+        const latestCompaction = getLatestCompactionEntry(branchEntries);
+        if (latestCompaction) {
+            // Check if there's a valid assistant usage after the compaction boundary
+            const compactionIndex = branchEntries.lastIndexOf(latestCompaction);
+            let hasPostCompactionUsage = false;
+            for (let i = branchEntries.length - 1; i > compactionIndex; i--) {
+                const entry = branchEntries[i];
+                if (entry.type === "message" && entry.message.role === "assistant") {
+                    const assistant = entry.message;
+                    if (assistant.stopReason !== "aborted" && assistant.stopReason !== "error") {
+                        const contextTokens = calculateContextTokens(assistant.usage);
+                        if (contextTokens > 0) {
+                            hasPostCompactionUsage = true;
+                        }
+                        break;
+                    }
+                }
+            }
+            if (!hasPostCompactionUsage) {
+                return { tokens: null, contextWindow, percent: null };
+            }
+        }
+        const estimate = estimateContextTokens(this.messages);
+        const percent = (estimate.tokens / contextWindow) * 100;
+        return {
+            tokens: estimate.tokens,
+            contextWindow,
+            percent,
+        };
+    }
+    /**
+     * 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();
+        return await exportSessionToHtml(this.sessionManager, this.state, {
+            outputPath,
+            themeName,
+        });
+    }
+    // =========================================================================
+    // 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;
+    }
+}
+//# sourceMappingURL=agent-session.js.map