/** * 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 type { Agent, AgentEvent, AgentMessage, AgentState, AgentTool, ThinkingLevel, } from "@mariozechner/pi-agent-core"; import type { AssistantMessage, ImageContent, Message, Model, TextContent } from "@mariozechner/pi-ai"; import { isContextOverflow, modelsAreEqual, supportsXhigh } from "@mariozechner/pi-ai"; import { getAuthPath } from "../config.js"; import { theme } from "../modes/interactive/theme/theme.js"; import { stripFrontmatter } from "../utils/frontmatter.js"; import { type BashResult, executeBash as executeBashCommand, executeBashWithOperations } from "./bash-executor.js"; import { type CompactionResult, calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js"; import { exportSessionToHtml, type ToolHtmlRenderer } from "./export-html/index.js"; import { createToolHtmlRenderer } from "./export-html/tool-renderer.js"; import { type ContextUsage, ExtensionRunner, type InputSource, type SessionBeforeCompactResult, type SessionBeforeForkResult, type SessionBeforeSwitchResult, type SessionBeforeTreeResult, type ToolDefinition, type TreePreparation, type TurnEndEvent, type TurnStartEvent, wrapRegisteredTools, wrapToolsWithExtensions, } from "./extensions/index.js"; import type { BashExecutionMessage, CustomMessage } from "./messages.js"; import type { ModelRegistry } from "./model-registry.js"; import { expandPromptTemplate, type PromptTemplate } from "./prompt-templates.js"; import type { ResourceLoader } from "./resource-loader.js"; import type { BranchSummaryEntry, CompactionEntry, NewSessionOptions, SessionManager } from "./session-manager.js"; import type { SettingsManager } from "./settings-manager.js"; import type { Skill, SkillWarning } from "./skills.js"; import { buildSystemPrompt } from "./system-prompt.js"; import type { BashOperations } from "./tools/bash.js"; import type { ToolName } from "./tools/index.js"; /** Session-specific events that extend the core AgentEvent */ export type AgentSessionEvent = | AgentEvent | { type: "auto_compaction_start"; reason: "threshold" | "overflow" } | { type: "auto_compaction_end"; result: CompactionResult | undefined; aborted: boolean; willRetry: boolean; errorMessage?: string; } | { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string } | { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string }; /** Listener function for agent session events */ export type AgentSessionEventListener = (event: AgentSessionEvent) => void; export type RunnerInitializer = (runner: ExtensionRunner) => void | Promise; // ============================================================================ // Types // ============================================================================ export interface AgentSessionConfig { agent: Agent; sessionManager: SessionManager; settingsManager: SettingsManager; cwd: string; /** Models to cycle through with Ctrl+P (from --models flag) */ scopedModels?: Array<{ model: Model; thinkingLevel: ThinkingLevel }>; /** Resource loader for skills, prompts, themes, context files, system prompt */ resourceLoader: ResourceLoader; /** Extension runner (created in sdk.ts with wrapped tools) */ extensionRunner?: ExtensionRunner; /** SDK custom tools registered outside extensions */ customTools?: ToolDefinition[]; /** Base tool registry without extension wrapping */ baseToolRegistry: Map; /** Model registry for API key resolution and model discovery */ modelRegistry: ModelRegistry; /** Tool registry for extension getTools/setTools - maps name to tool */ toolRegistry?: Map; } /** Options for AgentSession.prompt() */ export interface PromptOptions { /** Whether to expand file-based prompt templates (default: true) */ expandPromptTemplates?: boolean; /** Image attachments */ images?: ImageContent[]; /** When streaming, how to queue the message: "steer" (interrupt) or "followUp" (wait). Required if streaming. */ streamingBehavior?: "steer" | "followUp"; /** Source of input for extension input event handlers. Defaults to "interactive". */ source?: InputSource; } /** Result from cycleModel() */ export interface ModelCycleResult { model: Model; thinkingLevel: ThinkingLevel; /** Whether cycling through scoped models (--models flag) or all available */ isScoped: boolean; } /** Session statistics for /session command */ export interface SessionStats { sessionFile: string | undefined; sessionId: string; userMessages: number; assistantMessages: number; toolCalls: number; toolResults: number; totalMessages: number; tokens: { input: number; output: number; cacheRead: number; cacheWrite: number; total: number; }; cost: number; } // ============================================================================ // Constants // ============================================================================ /** Standard thinking levels */ const THINKING_LEVELS: ThinkingLevel[] = ["off", "minimal", "low", "medium", "high"]; /** Thinking levels including xhigh (for supported models) */ const THINKING_LEVELS_WITH_XHIGH: ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh"]; // ============================================================================ // AgentSession Class // ============================================================================ export class AgentSession { readonly agent: Agent; readonly sessionManager: SessionManager; readonly settingsManager: SettingsManager; private _scopedModels: Array<{ model: Model; thinkingLevel: ThinkingLevel }>; // Event subscription state private _unsubscribeAgent?: () => void; private _eventListeners: AgentSessionEventListener[] = []; /** Tracks pending steering messages for UI display. Removed when delivered. */ private _steeringMessages: string[] = []; /** Tracks pending follow-up messages for UI display. Removed when delivered. */ private _followUpMessages: string[] = []; /** Messages queued to be included with the next user prompt as context ("asides"). */ private _pendingNextTurnMessages: CustomMessage[] = []; // Compaction state private _compactionAbortController: AbortController | undefined = undefined; private _autoCompactionAbortController: AbortController | undefined = undefined; // Branch summarization state private _branchSummaryAbortController: AbortController | undefined = undefined; // Retry state private _retryAbortController: AbortController | undefined = undefined; private _retryAttempt = 0; private _retryPromise: Promise | undefined = undefined; private _retryResolve: (() => void) | undefined = undefined; // Bash execution state private _bashAbortController: AbortController | undefined = undefined; private _pendingBashMessages: BashExecutionMessage[] = []; // Extension system private _extensionRunner: ExtensionRunner | undefined = undefined; private _turnIndex = 0; private _resourceLoader: ResourceLoader; private _runnerInitializer?: RunnerInitializer; private _customTools: ToolDefinition[]; private _baseToolRegistry: Map; private _cwd: string; // Model registry for API key resolution private _modelRegistry: ModelRegistry; // Tool registry for extension getTools/setTools private _toolRegistry: Map; // Base system prompt (without extension appends) - used to apply fresh appends each turn private _baseSystemPrompt: string; constructor(config: AgentSessionConfig) { this.agent = config.agent; this.sessionManager = config.sessionManager; this.settingsManager = config.settingsManager; this._scopedModels = config.scopedModels ?? []; this._extensionRunner = config.extensionRunner; this._resourceLoader = config.resourceLoader; this._customTools = config.customTools ?? []; this._baseToolRegistry = config.baseToolRegistry; this._cwd = config.cwd; this._modelRegistry = config.modelRegistry; this._toolRegistry = config.toolRegistry ?? new Map(); this._baseSystemPrompt = config.agent.state.systemPrompt; // Always subscribe to agent events for internal handling // (session persistence, extensions, auto-compaction, retry logic) this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent); } /** Model registry for API key resolution and model discovery */ get modelRegistry(): ModelRegistry { return this._modelRegistry; } // ========================================================================= // Event Subscription // ========================================================================= /** Emit an event to all listeners */ private _emit(event: AgentSessionEvent): void { for (const l of this._eventListeners) { l(event); } } // Track last assistant message for auto-compaction check private _lastAssistantMessage: AssistantMessage | undefined = undefined; /** Internal handler for agent events - shared by subscribe and reconnect */ private _handleAgentEvent = async (event: AgentEvent): Promise => { // 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") { 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; } } // 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._isRetryableError(msg)) { const didRetry = await this._handleRetryableError(msg); if (didRetry) return; // Retry was initiated, don't proceed to compaction } else if (this._retryAttempt > 0) { // Previous retry succeeded - emit success event and reset counter this._emit({ type: "auto_retry_end", success: true, attempt: this._retryAttempt, }); this._retryAttempt = 0; // Resolve the retry promise so waitForRetry() completes this._resolveRetry(); } await this._checkCompaction(msg); } }; /** Resolve the pending retry promise */ private _resolveRetry(): void { if (this._retryResolve) { this._retryResolve(); this._retryResolve = undefined; this._retryPromise = undefined; } } /** Extract text content from a message */ private _getUserMessageText(message: Message): string { 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 as TextContent).text).join(""); } /** Find the last assistant message in agent state (including aborted ones) */ private _findLastAssistantMessage(): AssistantMessage | undefined { 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 as AssistantMessage; } } return undefined; } /** Emit extension events based on agent events */ private async _emitExtensionEvent(event: AgentEvent): Promise { 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: TurnStartEvent = { type: "turn_start", turnIndex: this._turnIndex, timestamp: Date.now(), }; await this._extensionRunner.emit(extensionEvent); } else if (event.type === "turn_end") { const extensionEvent: TurnEndEvent = { type: "turn_end", turnIndex: this._turnIndex, message: event.message, toolResults: event.toolResults, }; await this._extensionRunner.emit(extensionEvent); this._turnIndex++; } } /** * Subscribe to agent events. * Session persistence is handled internally (saves messages on message_end). * Multiple listeners can be added. Returns unsubscribe function for this listener. */ subscribe(listener: AgentSessionEventListener): () => void { 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. */ private _disconnectFromAgent(): void { if (this._unsubscribeAgent) { this._unsubscribeAgent(); this._unsubscribeAgent = undefined; } } /** * Reconnect to agent events after _disconnectFromAgent(). * Preserves all existing listeners. */ private _reconnectToAgent(): void { 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(): void { this._disconnectFromAgent(); this._eventListeners = []; } // ========================================================================= // Read-only State Access // ========================================================================= /** Full agent state */ get state(): AgentState { return this.agent.state; } /** Current model (may be undefined if not yet selected) */ get model(): Model | undefined { return this.agent.state.model; } /** Current thinking level */ get thinkingLevel(): ThinkingLevel { return this.agent.state.thinkingLevel; } /** Whether agent is currently streaming a response */ get isStreaming(): boolean { return this.agent.state.isStreaming; } /** Current retry attempt (0 if not retrying) */ get retryAttempt(): number { return this._retryAttempt; } /** * Get the names of currently active tools. * Returns the names of tools currently set on the agent. */ getActiveToolNames(): string[] { return this.agent.state.tools.map((t) => t.name); } /** * Get all configured tools with name and description. */ getAllTools(): Array<{ name: string; description: string }> { return Array.from(this._toolRegistry.values()).map((t) => ({ name: t.name, description: t.description, })); } /** * Set active tools by name. * Only tools in the registry can be enabled. Unknown tool names are ignored. * Also rebuilds the system prompt to reflect the new tool set. * Changes take effect on the next agent turn. */ setActiveToolsByName(toolNames: string[]): void { const tools: AgentTool[] = []; const validToolNames: string[] = []; for (const name of toolNames) { const tool = this._toolRegistry.get(name); if (tool) { tools.push(tool); validToolNames.push(name); } } this.agent.setTools(tools); // Rebuild base system prompt with new tool set this._baseSystemPrompt = this._rebuildSystemPrompt(validToolNames); this.agent.setSystemPrompt(this._baseSystemPrompt); } /** Whether auto-compaction is currently running */ get isCompacting(): boolean { return this._autoCompactionAbortController !== undefined || this._compactionAbortController !== undefined; } /** All messages including custom types like BashExecutionMessage */ get messages(): AgentMessage[] { return this.agent.state.messages; } /** Current steering mode */ get steeringMode(): "all" | "one-at-a-time" { return this.agent.getSteeringMode(); } /** Current follow-up mode */ get followUpMode(): "all" | "one-at-a-time" { return this.agent.getFollowUpMode(); } /** Current session file path, or undefined if sessions are disabled */ get sessionFile(): string | undefined { return this.sessionManager.getSessionFile(); } /** Current session ID */ get sessionId(): string { return this.sessionManager.getSessionId(); } /** Scoped models for cycling (from --models flag) */ get scopedModels(): ReadonlyArray<{ model: Model; thinkingLevel: ThinkingLevel }> { return this._scopedModels; } /** Update scoped models for cycling */ setScopedModels(scopedModels: Array<{ model: Model; thinkingLevel: ThinkingLevel }>): void { this._scopedModels = scopedModels; } /** File-based prompt templates */ get promptTemplates(): ReadonlyArray { return this._resourceLoader.getPrompts().prompts; } private _rebuildSystemPrompt(toolNames: string[]): string { const validToolNames = toolNames.filter((name): name is ToolName => this._baseToolRegistry.has(name)); const loaderSystemPrompt = this._resourceLoader.getSystemPrompt(); const loaderAppendSystemPrompt = this._resourceLoader.getAppendSystemPrompt(); const appendSystemPrompt = loaderAppendSystemPrompt.length > 0 ? loaderAppendSystemPrompt.join("\n\n") : undefined; const loadedSkills = this._resourceLoader.getSkills().skills; const loadedContextFiles = this._resourceLoader.getAgentsFiles().agentsFiles; return buildSystemPrompt({ cwd: this._cwd, skills: loadedSkills, contextFiles: loadedContextFiles, customPrompt: loaderSystemPrompt, appendSystemPrompt, selectedTools: validToolNames, }); } // ========================================================================= // 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: string, options?: PromptOptions): Promise { 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); } else { await this._queueSteer(expandedText); } return; } // Flush any pending bash messages before the new prompt this._flushPendingBashMessages(); // Validate model if (!this.model) { throw new Error( "No model selected.\n\n" + `Use /login, set an API key environment variable, or create ${getAuthPath()}\n\n` + "Then use /model to select a model.", ); } // Validate API key const apiKey = await this._modelRegistry.getApiKey(this.model); if (!apiKey) { const isOAuth = this._modelRegistry.isUsingOAuth(this.model); if (isOAuth) { throw new Error( `Authentication failed for "${this.model.provider}". ` + `Credentials may have expired or network is unavailable. ` + `Run '/login ${this.model.provider}' to re-authenticate.`, ); } throw new Error( `No API key found for ${this.model.provider}.\n\n` + `Use /login, set an API key environment variable, or create ${getAuthPath()}`, ); } // Check if we need to compact before sending (catches aborted responses) const lastAssistant = this._findLastAssistantMessage(); if (lastAssistant) { await this._checkCompaction(lastAssistant, false); } // Build messages array (custom message if any, then user message) const messages: AgentMessage[] = []; // Add user message const userContent: (TextContent | ImageContent)[] = [{ 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.setSystemPrompt(result.systemPrompt); } else { // Ensure we're using the base prompt (in case previous turn had modifications) this.agent.setSystemPrompt(this._baseSystemPrompt); } } await this.agent.prompt(messages); await this.waitForRetry(); } /** * Try to execute an extension command. Returns true if command was found and executed. */ private async _tryExecuteExtensionCommand(text: string): Promise { 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: err instanceof Error ? err.message : String(err), }); return true; } } /** * Expand skill commands (/skill:name args) to their full content. * Returns the expanded text, or the original text if not a skill command or skill not found. * Emits errors via extension runner if file read fails. */ private _expandSkillCommand(text: string): string { if (!text.startsWith("/skill:")) return text; const spaceIndex = text.indexOf(" "); const skillName = spaceIndex === -1 ? text.slice(7) : text.slice(7, spaceIndex); const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1).trim(); const skill = this.skills.find((s) => s.name === skillName); if (!skill) return text; // Unknown skill, pass through try { const content = readFileSync(skill.filePath, "utf-8"); const body = stripFrontmatter(content).trim(); const header = `Skill location: ${skill.filePath}\nReferences are relative to ${skill.baseDir}.`; const skillMessage = `${header}\n\n${body}`; return args ? `${skillMessage}\n\n---\n\nUser: ${args}` : skillMessage; } catch (err) { // Emit error like extension commands do this._extensionRunner?.emitError({ extensionPath: skill.filePath, event: "skill_expansion", error: err instanceof Error ? err.message : String(err), }); return text; // Return original on error } } /** * Queue a steering message to interrupt the agent mid-run. * Delivered after current tool execution, skips remaining tools. * Expands skill commands and prompt templates. Errors on extension commands. * @throws Error if text is an extension command */ async steer(text: string): Promise { // Check for extension commands (cannot be queued) if (text.startsWith("/")) { this._throwIfExtensionCommand(text); } // Expand skill commands and prompt templates let expandedText = this._expandSkillCommand(text); expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]); await this._queueSteer(expandedText); } /** * Queue a follow-up message to be processed after the agent finishes. * Delivered only when agent has no more tool calls or steering messages. * Expands skill commands and prompt templates. Errors on extension commands. * @throws Error if text is an extension command */ async followUp(text: string): Promise { // Check for extension commands (cannot be queued) if (text.startsWith("/")) { this._throwIfExtensionCommand(text); } // Expand skill commands and prompt templates let expandedText = this._expandSkillCommand(text); expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]); await this._queueFollowUp(expandedText); } /** * Internal: Queue a steering message (already expanded, no extension command check). */ private async _queueSteer(text: string): Promise { this._steeringMessages.push(text); this.agent.steer({ role: "user", content: [{ type: "text", text }], timestamp: Date.now(), }); } /** * Internal: Queue a follow-up message (already expanded, no extension command check). */ private async _queueFollowUp(text: string): Promise { this._followUpMessages.push(text); this.agent.followUp({ role: "user", content: [{ type: "text", text }], timestamp: Date.now(), }); } /** * Throw an error if the text is an extension command. */ private _throwIfExtensionCommand(text: string): void { 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: Pick, "customType" | "content" | "display" | "details">, options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" }, ): Promise { const appMessage = { role: "custom" as const, customType: message.customType, content: message.content, display: message.display, details: message.details, timestamp: Date.now(), } satisfies CustomMessage; if (options?.deliverAs === "nextTurn") { this._pendingNextTurnMessages.push(appMessage); } else if (this.isStreaming) { if (options?.deliverAs === "followUp") { this.agent.followUp(appMessage); } else { this.agent.steer(appMessage); } } else if (options?.triggerTurn) { await this.agent.prompt(appMessage); } else { this.agent.appendMessage(appMessage); this.sessionManager.appendCustomMessageEntry( message.customType, message.content, message.display, message.details, ); } } /** * 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: string | (TextContent | ImageContent)[], options?: { deliverAs?: "steer" | "followUp" }, ): Promise { // Normalize content to text string + optional images let text: string; let images: ImageContent[] | undefined; if (typeof content === "string") { text = content; } else { const textParts: string[] = []; 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(): { steering: string[]; followUp: string[] } { const steering = [...this._steeringMessages]; const followUp = [...this._followUpMessages]; this._steeringMessages = []; this._followUpMessages = []; this.agent.clearAllQueues(); return { steering, followUp }; } /** Number of pending messages (includes both steering and follow-up) */ get pendingMessageCount(): number { return this._steeringMessages.length + this._followUpMessages.length; } /** Get pending steering messages (read-only) */ getSteeringMessages(): readonly string[] { return this._steeringMessages; } /** Get pending follow-up messages (read-only) */ getFollowUpMessages(): readonly string[] { return this._followUpMessages; } /** Skills loaded by resource loader */ get skills(): readonly Skill[] { return this._resourceLoader.getSkills().skills; } /** Skill loading warnings captured by resource loader */ get skillWarnings(): readonly SkillWarning[] { return this._resourceLoader.getSkills().diagnostics.map((diagnostic) => ({ skillPath: diagnostic.path ?? "", message: diagnostic.message, })); } get resourceLoader(): ResourceLoader { return this._resourceLoader; } /** * Abort current operation and wait for agent to become idle. */ async abort(): Promise { this.abortRetry(); this.agent.abort(); await this.agent.waitForIdle(); } /** * Start a new session, optionally with initial messages and parent tracking. * Clears all messages and starts a new session. * Listeners are preserved and will continue receiving events. * @param options - Optional initial messages and parent session path * @returns true if completed, false if cancelled by extension */ async newSession(options?: NewSessionOptions): Promise { 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", })) as SessionBeforeSwitchResult | undefined; if (result?.cancel) { return false; } } this._disconnectFromAgent(); await this.abort(); this.agent.reset(); this.sessionManager.newSession(options); this.agent.sessionId = this.sessionManager.getSessionId(); this._steeringMessages = []; this._followUpMessages = []; this._pendingNextTurnMessages = []; this._reconnectToAgent(); // Emit session_switch event with reason "new" to extensions if (this._extensionRunner) { await this._extensionRunner.emit({ type: "session_switch", reason: "new", previousSessionFile, }); } // Emit session event to custom tools return true; } // ========================================================================= // Model Management // ========================================================================= private async _emitModelSelect( nextModel: Model, previousModel: Model | undefined, source: "set" | "cycle" | "restore", ): Promise { if (!this._extensionRunner) return; if (modelsAreEqual(previousModel, nextModel)) return; await this._extensionRunner.emit({ type: "model_select", model: nextModel, previousModel, source, }); } /** * Set model directly. * Validates API key, saves to session and settings. * @throws Error if no API key available for the model */ async setModel(model: Model): Promise { const apiKey = await this._modelRegistry.getApiKey(model); if (!apiKey) { throw new Error(`No API key for ${model.provider}/${model.id}`); } const previousModel = this.model; this.agent.setModel(model); this.sessionManager.appendModelChange(model.provider, model.id); this.settingsManager.setDefaultModelAndProvider(model.provider, model.id); // Re-clamp thinking level for new model's capabilities this.setThinkingLevel(this.thinkingLevel); await this._emitModelSelect(model, previousModel, "set"); } /** * Cycle to next/previous model. * Uses scoped models (from --models flag) if available, otherwise all available models. * @param direction - "forward" (default) or "backward" * @returns The new model info, or undefined if only one model available */ async cycleModel(direction: "forward" | "backward" = "forward"): Promise { if (this._scopedModels.length > 0) { return this._cycleScopedModel(direction); } return this._cycleAvailableModel(direction); } private async _cycleScopedModel(direction: "forward" | "backward"): Promise { if (this._scopedModels.length <= 1) return undefined; const currentModel = this.model; let currentIndex = this._scopedModels.findIndex((sm) => modelsAreEqual(sm.model, currentModel)); if (currentIndex === -1) currentIndex = 0; const len = this._scopedModels.length; const nextIndex = direction === "forward" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len; const next = this._scopedModels[nextIndex]; // Validate API key const apiKey = await this._modelRegistry.getApiKey(next.model); if (!apiKey) { throw new Error(`No API key for ${next.model.provider}/${next.model.id}`); } // Apply model this.agent.setModel(next.model); this.sessionManager.appendModelChange(next.model.provider, next.model.id); this.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id); // Apply thinking level (setThinkingLevel clamps to model capabilities) this.setThinkingLevel(next.thinkingLevel); await this._emitModelSelect(next.model, currentModel, "cycle"); return { model: next.model, thinkingLevel: this.thinkingLevel, isScoped: true }; } private async _cycleAvailableModel(direction: "forward" | "backward"): Promise { const availableModels = await this._modelRegistry.getAvailable(); if (availableModels.length <= 1) return undefined; const currentModel = this.model; let currentIndex = availableModels.findIndex((m) => modelsAreEqual(m, currentModel)); if (currentIndex === -1) currentIndex = 0; const len = availableModels.length; const nextIndex = direction === "forward" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len; const nextModel = availableModels[nextIndex]; const apiKey = await this._modelRegistry.getApiKey(nextModel); if (!apiKey) { throw new Error(`No API key for ${nextModel.provider}/${nextModel.id}`); } this.agent.setModel(nextModel); this.sessionManager.appendModelChange(nextModel.provider, nextModel.id); this.settingsManager.setDefaultModelAndProvider(nextModel.provider, nextModel.id); // Re-clamp thinking level for new model's capabilities this.setThinkingLevel(this.thinkingLevel); await this._emitModelSelect(nextModel, currentModel, "cycle"); return { model: nextModel, thinkingLevel: this.thinkingLevel, isScoped: false }; } /** * Get all available models with valid API keys. */ async getAvailableModels(): Promise[]> { return this._modelRegistry.getAvailable(); } // ========================================================================= // Thinking Level Management // ========================================================================= /** * Set thinking level. * Clamps to model capabilities based on available thinking levels. * Saves to session and settings. */ setThinkingLevel(level: ThinkingLevel): void { const availableLevels = this.getAvailableThinkingLevels(); const effectiveLevel = availableLevels.includes(level) ? level : this._clampThinkingLevel(level, availableLevels); this.agent.setThinkingLevel(effectiveLevel); this.sessionManager.appendThinkingLevelChange(effectiveLevel); this.settingsManager.setDefaultThinkingLevel(effectiveLevel); } /** * Cycle to next thinking level. * @returns New level, or undefined if model doesn't support thinking */ cycleThinkingLevel(): ThinkingLevel | undefined { 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(): ThinkingLevel[] { if (!this.supportsThinking()) return ["off"]; return this.supportsXhighThinking() ? THINKING_LEVELS_WITH_XHIGH : THINKING_LEVELS; } /** * Check if current model supports xhigh thinking level. */ supportsXhighThinking(): boolean { return this.model ? supportsXhigh(this.model) : false; } /** * Check if current model supports thinking/reasoning. */ supportsThinking(): boolean { return !!this.model?.reasoning; } private _clampThinkingLevel(level: ThinkingLevel, availableLevels: ThinkingLevel[]): ThinkingLevel { 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: "all" | "one-at-a-time"): void { this.agent.setSteeringMode(mode); this.settingsManager.setSteeringMode(mode); } /** * Set follow-up message mode. * Saves to settings. */ setFollowUpMode(mode: "all" | "one-at-a-time"): void { this.agent.setFollowUpMode(mode); this.settingsManager.setFollowUpMode(mode); } // ========================================================================= // Compaction // ========================================================================= /** * Manually compact the session context. * Aborts current agent operation first. * @param customInstructions Optional instructions for the compaction summary */ async compact(customInstructions?: string): Promise { this._disconnectFromAgent(); await this.abort(); this._compactionAbortController = new AbortController(); try { if (!this.model) { throw new Error("No model selected"); } const apiKey = await this._modelRegistry.getApiKey(this.model); if (!apiKey) { throw new Error(`No API key for ${this.model.provider}`); } const pathEntries = this.sessionManager.getBranch(); const settings = this.settingsManager.getCompactionSettings(); const preparation = prepareCompaction(pathEntries, settings); if (!preparation) { // Check why we can't compact const lastEntry = pathEntries[pathEntries.length - 1]; if (lastEntry?.type === "compaction") { throw new Error("Already compacted"); } throw new Error("Nothing to compact (session too small)"); } let extensionCompaction: CompactionResult | undefined; let fromExtension = false; if (this._extensionRunner?.hasHandlers("session_before_compact")) { const result = (await this._extensionRunner.emit({ type: "session_before_compact", preparation, branchEntries: pathEntries, customInstructions, signal: this._compactionAbortController.signal, })) as SessionBeforeCompactResult | undefined; if (result?.cancel) { throw new Error("Compaction cancelled"); } if (result?.compaction) { extensionCompaction = result.compaction; fromExtension = true; } } let summary: string; let firstKeptEntryId: string; let tokensBefore: number; let details: unknown; if (extensionCompaction) { // Extension provided compaction content summary = extensionCompaction.summary; firstKeptEntryId = extensionCompaction.firstKeptEntryId; tokensBefore = extensionCompaction.tokensBefore; details = extensionCompaction.details; } else { // Generate compaction result const result = await compact( preparation, this.model, apiKey, customInstructions, this._compactionAbortController.signal, ); summary = result.summary; firstKeptEntryId = result.firstKeptEntryId; tokensBefore = result.tokensBefore; details = result.details; } if (this._compactionAbortController.signal.aborted) { throw new Error("Compaction cancelled"); } this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromExtension); const newEntries = this.sessionManager.getEntries(); const sessionContext = this.sessionManager.buildSessionContext(); this.agent.replaceMessages(sessionContext.messages); // Get the saved compaction entry for the extension event const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary) as | CompactionEntry | undefined; if (this._extensionRunner && savedCompactionEntry) { await this._extensionRunner.emit({ type: "session_compact", compactionEntry: savedCompactionEntry, fromExtension, }); } return { summary, firstKeptEntryId, tokensBefore, details, }; } finally { this._compactionAbortController = undefined; this._reconnectToAgent(); } } /** * Cancel in-progress compaction (manual or auto). */ abortCompaction(): void { this._compactionAbortController?.abort(); this._autoCompactionAbortController?.abort(); } /** * Cancel in-progress branch summarization. */ abortBranchSummary(): void { this._branchSummaryAbortController?.abort(); } /** * Check if compaction is needed and run it. * Called after agent_end and before prompt submission. * * Two cases: * 1. Overflow: LLM returned context overflow error, remove error message from agent state, compact, auto-retry * 2. Threshold: Context over threshold, compact, NO auto-retry (user continues manually) * * @param assistantMessage The assistant message to check * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true */ private async _checkCompaction(assistantMessage: AssistantMessage, skipAbortedCheck = true): Promise { const settings = this.settingsManager.getCompactionSettings(); if (!settings.enabled) return; // Skip if message was aborted (user cancelled) - unless skipAbortedCheck is false if (skipAbortedCheck && assistantMessage.stopReason === "aborted") return; const contextWindow = this.model?.contextWindow ?? 0; // Skip overflow check if the message came from a different model. // This handles the case where user switched from a smaller-context model (e.g. opus) // to a larger-context model (e.g. codex) - the overflow error from the old model // shouldn't trigger compaction for the new model. const sameModel = this.model && assistantMessage.provider === this.model.provider && assistantMessage.model === this.model.id; // Skip overflow check if the error is from before a compaction in the current path. // This handles the case where an error was kept after compaction (in the "kept" region). // The error shouldn't trigger another compaction since we already compacted. // Example: opus fails → switch to codex → compact → switch back to opus → opus error // is still in context but shouldn't trigger compaction again. const compactionEntry = this.sessionManager.getBranch().find((e) => e.type === "compaction"); const errorIsFromBeforeCompaction = compactionEntry && assistantMessage.timestamp < new Date(compactionEntry.timestamp).getTime(); // Case 1: Overflow - LLM returned context overflow error if (sameModel && !errorIsFromBeforeCompaction && isContextOverflow(assistantMessage, contextWindow)) { // Remove the error message from agent state (it IS saved to session for history, // but we don't want it in context for the retry) const messages = this.agent.state.messages; if (messages.length > 0 && messages[messages.length - 1].role === "assistant") { this.agent.replaceMessages(messages.slice(0, -1)); } await this._runAutoCompaction("overflow", true); return; } // Case 2: Threshold - turn succeeded but context is getting large // Skip if this was an error (non-overflow errors don't have usage data) if (assistantMessage.stopReason === "error") return; const contextTokens = calculateContextTokens(assistantMessage.usage); if (shouldCompact(contextTokens, contextWindow, settings)) { await this._runAutoCompaction("threshold", false); } } /** * Internal: Run auto-compaction with events. */ private async _runAutoCompaction(reason: "overflow" | "threshold", willRetry: boolean): Promise { const settings = this.settingsManager.getCompactionSettings(); this._emit({ type: "auto_compaction_start", reason }); this._autoCompactionAbortController = new AbortController(); try { if (!this.model) { this._emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false }); return; } const apiKey = await this._modelRegistry.getApiKey(this.model); if (!apiKey) { this._emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false }); return; } const pathEntries = this.sessionManager.getBranch(); const preparation = prepareCompaction(pathEntries, settings); if (!preparation) { this._emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false }); return; } let extensionCompaction: CompactionResult | undefined; let fromExtension = false; if (this._extensionRunner?.hasHandlers("session_before_compact")) { const extensionResult = (await this._extensionRunner.emit({ type: "session_before_compact", preparation, branchEntries: pathEntries, customInstructions: undefined, signal: this._autoCompactionAbortController.signal, })) as SessionBeforeCompactResult | undefined; if (extensionResult?.cancel) { this._emit({ type: "auto_compaction_end", result: undefined, aborted: true, willRetry: false }); return; } if (extensionResult?.compaction) { [Showing lines 1-1511 of 2453 (50.0KB limit). Use offset=1512 to continue]