@greppleai/grip 0.0.0-stage → 0.0.1

package/dist/core/agent-session.d.ts

@@ -0,0 +1,970 @@
+/**
+ * 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
+ * - Tree navigation and branching
+ *
+ * Modes use this class and add their own I/O layer on top.
+ */
+import type { Agent, AgentEvent, AgentMessage, AgentState, AgentTool, QueueMode, ThinkingLevel } from "@greppleai/grip-agent-core";
+import type { AssistantMessage, ImageContent, Model, TextContent } from "@greppleai/grip-ai";
+import { type Static, type TSchema } from "typebox";
+import { type BashResult } from "./bash-executor.ts";
+import { type CompactionResult } from "./compaction/compaction.ts";
+import { type CompressionDetectionCounts, type CompressionDetectionVerdict } from "./compaction/compression-detector.ts";
+import { type ExtensionErrorListener, ExtensionRunner, type ShutdownHandler } from "./extensions/runner.ts";
+import type { ContextUsage, ExtensionCommandContextActions, ExtensionNavigateTreeOptions, ExtensionSendMessageOptions, ExtensionUIContext, InputSource, ReplacedSessionContext, SessionStartEvent, StreamingBehavior, ToolDefinition, ToolInfo } from "./extensions/types.ts";
+import type { HookDiagnostic, HookExecutionActivityListener, HookExecutionListener, HookRunOptions, JsonObject, LoadedHooks, SessionEndReason } from "./hooks/types.ts";
+import { type LspConfigurationLayer, type ResolvedLspConfiguration } from "./lsp/config.ts";
+import { type LoadLspConfigurationResult, type LspConfigurationSourceDiagnostic } from "./lsp/config-loader.ts";
+import { type LspSessionStatus } from "./lsp/integration.ts";
+import type { LspConnectionFactoryRegistry } from "./lsp/transport.ts";
+import { type CustomMessage } from "./messages.ts";
+import type { ModelRegistry } from "./model-registry.ts";
+import type { ScopedModel } from "./model-resolver.ts";
+import { type PromptTemplate } from "./prompt-templates.ts";
+import type { ResourceLoader } from "./resource-loader.ts";
+import type { Rule } from "./rules.ts";
+import type { Session } from "./session/session.ts";
+import type { BranchSummaryEntry } from "./session/types.ts";
+import type { SettingsManager } from "./settings-manager.ts";
+import type { Skill } from "./skills.ts";
+import { type SourceInfo } from "./source-info.ts";
+import { type ToolBackendInfo, type ToolOperations } from "./tools/operations.ts";
+import { type SubagentConfigRegistry, type SubagentRunner, type SubagentRunRegistry } from "./tools/subagent.ts";
+export declare const SUBAGENT_TOOL_NAMES: readonly ["subagent", "subagent_runs", "create_subagent"];
+export declare const DEFAULT_ACTIVE_TOOL_NAMES: readonly ["read", "bash", "edit", "write", "websearch", "session_search", "session_entry_get"];
+export declare function getDefaultActiveToolNames(enableSubagents?: boolean, enableLspTools?: boolean): string[];
+/** Parsed skill block from a user message */
+export interface ParsedSkillBlock {
+    name: string;
+    location: string;
+    content: string;
+    userMessage: string | undefined;
+}
+/**
+ * Parse a skill block from message text.
+ * Returns null if the text doesn't contain a skill block.
+ */
+export declare function parseSkillBlock(text: string): ParsedSkillBlock | null;
+/** Session-specific events that extend the core AgentEvent */
+export type AgentSessionEvent = Exclude<AgentEvent, {
+    type: "agent_end";
+}> | {
+    type: "agent_end";
+    messages: AgentMessage[];
+    willRetry: boolean;
+} | {
+    type: "queue_update";
+    steering: readonly string[];
+    followUp: readonly string[];
+} | {
+    type: "compaction_start";
+    reason: "manual" | "threshold" | "overflow";
+} | {
+    type: "state_compressed";
+} | {
+    type: "compression_detection_activity";
+    active: boolean;
+} | {
+    type: "compression_detection_result";
+    verdict: CompressionDetectionVerdict;
+} | {
+    type: "session_info_changed";
+    name: string | undefined;
+} | {
+    type: "thinking_level_changed";
+    level: ThinkingLevel;
+} | {
+    type: "compaction_end";
+    reason: "manual" | "threshold" | "overflow";
+    result: CompactionResult | undefined;
+    aborted: boolean;
+    willRetry: boolean;
+    errorMessage?: string;
+} | {
+    type: "agent_settled";
+} | {
+    type: "auto_retry_start";
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    errorMessage: string;
+} | {
+    type: "auto_retry_end";
+    success: boolean;
+    attempt: number;
+    finalError?: string;
+} | {
+    type: "summarization_retry_scheduled";
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    errorMessage: string;
+} | {
+    type: "summarization_retry_attempt_start";
+    source: "branchSummary";
+} | {
+    type: "summarization_retry_attempt_start";
+    source: "compaction";
+    reason: "manual" | "threshold" | "overflow";
+} | {
+    type: "summarization_retry_finished";
+};
+/** Listener function for agent session events */
+export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
+export interface ExtensionRunnerRef {
+    current?: ExtensionRunner;
+}
+export interface SessionStatsTokenTotals {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+}
+export interface AgentSessionConfig {
+    agent: Agent;
+    session: Session;
+    settingsManager: SettingsManager;
+    cwd: string;
+    /** Models to cycle through with Ctrl+P (from --models flag) */
+    scopedModels?: ScopedModel[];
+    /** Resource loader for skills, rules, prompts, themes, context files, system prompt */
+    resourceLoader: ResourceLoader;
+    /** SDK custom tools registered outside extensions */
+    customTools?: ToolDefinition[];
+    /** Tool operation backend used by built-in tools. */
+    toolOperations?: ToolOperations;
+    /** Model registry for API key resolution and model discovery */
+    modelRegistry: ModelRegistry;
+    /** Initial active built-in tool names. Defaults to DEFAULT_ACTIVE_TOOL_NAMES. */
+    initialActiveToolNames?: string[];
+    /** CLI/SDK override for exposing configured LSP tools by default; explicit tool allowlists remain authoritative. */
+    enableLspTools?: boolean;
+    /** Optional allowlist of tool names. When provided, only these tool names are exposed. */
+    allowedToolNames?: string[];
+    /** Tool names that must never be exposed in this session. */
+    excludedToolNames?: string[];
+    /**
+     * Override base tools (useful for custom runtimes).
+     *
+     * These are synthesized into minimal ToolDefinitions internally so AgentSession can keep
+     * a definition-first registry even when callers provide plain AgentTool instances.
+     */
+    baseToolsOverride?: Record<string, AgentTool>;
+    /** Mutable ref used by Agent to access the current ExtensionRunner */
+    extensionRunnerRef?: ExtensionRunnerRef;
+    /** Runner used to create isolated subagent sessions. */
+    subagentRunner?: SubagentRunner;
+    subagentRunRegistry?: SubagentRunRegistry;
+    subagentConfigRegistry?: SubagentConfigRegistry;
+    /** Host-controlled trust grant for project-local subagent presets. */
+    trustProjectAgents?: boolean;
+    /** Validated configuration for the AgentSession-owned LSP runtime. */
+    lspConfiguration?: ResolvedLspConfiguration;
+    /** Host-provided factories referenced by LSP transports with type `connection`. */
+    lspConnectionFactories?: LspConnectionFactoryRegistry;
+    /** Re-resolves settings/file-backed LSP configuration after settings reload. */
+    resolveLspConfiguration?: () => Promise<LoadLspConfigurationResult>;
+    /** Receives current source-attributed diagnostics after each LSP configuration re-resolution. */
+    onLspConfigurationDiagnostics?: (diagnostics: readonly LspConfigurationSourceDiagnostic[]) => void;
+    /** Session start event metadata emitted when extensions bind to this runtime. */
+    sessionStartEvent?: SessionStartEvent;
+    /** Immutable Claude-compatible hook configuration snapshot for this session. */
+    loadedHooks?: LoadedHooks;
+    /** Re-resolves file-backed hook configuration after settings reload. */
+    resolveHooks?: () => Promise<LoadedHooks | undefined>;
+    /** Receives nonfatal hook execution/runtime diagnostics. */
+    onHookDiagnostic?: (diagnostic: HookDiagnostic) => void;
+    /** Host restrictions applied to hook execution. */
+    hookRunOptions?: Pick<HookRunOptions, "allowedHttpHookUrls" | "httpHookAllowedEnvVars">;
+}
+export interface ExtensionBindings {
+    uiContext?: ExtensionUIContext;
+    commandContextActions?: ExtensionCommandContextActions;
+    abortHandler?: () => void;
+    shutdownHandler?: ShutdownHandler;
+    onError?: ExtensionErrorListener;
+}
+export interface AgentSessionReloadResult {
+    lsp?: LoadLspConfigurationResult;
+}
+/** 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?: StreamingBehavior;
+    /** Source of input for extension input event handlers. Defaults to "interactive". */
+    source?: InputSource;
+    /** Internal hook used by RPC mode to observe prompt preflight acceptance or rejection. */
+    preflightResult?: (success: boolean) => void;
+}
+export type StructuredResponseScope = "latest" | "conversation";
+export type StructuredResponseSource = "json" | "tool";
+export interface StructuredResponseOptions<TSchemaValue extends TSchema> {
+    /** TypeBox object schema for the structured response. */
+    schema: TSchemaValue;
+    /** Schema/tool name shown to the model. Defaults to "structured_output". */
+    name?: string;
+    /** Optional description for the temporary structured output tool. */
+    description?: string;
+    /** Maximum correction calls after an invalid response. Defaults to 2. */
+    maxCorrections?: number;
+    /** Source context for extraction. Defaults to the latest assistant answer. */
+    scope?: StructuredResponseScope;
+}
+export interface StructuredResponse<T> {
+    output: T;
+    attempts: number;
+    source: StructuredResponseSource;
+    message: AssistantMessage;
+}
+/** Direction used when cycling through configured models. */
+export type ModelCycleDirection = "forward" | "backward";
+/** Result from cycleModel() */
+export interface ModelCycleResult {
+    model: Model<any>;
+    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: SessionStatsTokenTotals;
+    cost: number;
+    contextUsage?: ContextUsage;
+}
+export interface ConfigureRemoteSandboxOptions {
+    type: "daemon";
+    url: string;
+    token?: string;
+}
+export interface ActivateSandboxDaemonOptions {
+    url: string;
+    token: string;
+    expectedCwd: string;
+}
+export type SessionSkillRegistration = Omit<Skill, "sourceInfo" | "baseDir"> & {
+    baseDir?: string;
+    sourceInfo?: SourceInfo;
+};
+export type SessionRuleRegistration = Omit<Rule, "sourceInfo" | "baseDir"> & {
+    baseDir?: string;
+    sourceInfo?: SourceInfo;
+};
+export interface RegisterSessionToolOptions {
+    lazy?: boolean;
+    sourceInfo?: SourceInfo;
+}
+export type SendCustomMessageOptions = ExtensionSendMessageOptions;
+export interface SendUserMessageOptions {
+    deliverAs?: StreamingBehavior;
+}
+export interface QueuedMessages {
+    steering: string[];
+    followUp: string[];
+}
+export interface ExecuteBashOptions {
+    excludeFromContext?: boolean;
+    operations?: ToolOperations;
+    record?: boolean;
+    truncate?: boolean;
+}
+export interface RecordBashResultOptions {
+    excludeFromContext?: boolean;
+}
+export type NavigateTreeOptions = ExtensionNavigateTreeOptions;
+export interface NavigateTreeResult {
+    editorText?: string;
+    cancelled: boolean;
+    aborted?: boolean;
+    summaryEntry?: BranchSummaryEntry;
+}
+export interface ForkableUserMessage {
+    entryId: string;
+    text: string;
+}
+export type HookPathFlavor = "posix" | "windows";
+export declare function classifyStopFailure(errorMessage: string): string;
+/** Adapt grip's file-tool arguments to Claude's absolute, backend-lexical file_path shape. */
+export declare function adaptFileToolInputForClaudeHook(toolName: string, input: JsonObject, cwd: string, flavor: HookPathFlavor, home?: string | null): JsonObject;
+/** Reverse a Claude file_path replacement to grip's path field before schema validation. */
+export declare function adaptFileToolUpdatedInputFromClaudeHook(toolName: string, input: JsonObject, cwd: string, flavor: HookPathFlavor, home?: string | null): JsonObject;
+export declare class AgentSession {
+    readonly agent: Agent;
+    readonly session: Session;
+    readonly settingsManager: SettingsManager;
+    private _scopedModels;
+    private _unsubscribeAgent?;
+    private _eventListeners;
+    private _disposePromise?;
+    private _shutdownPreparationPromise?;
+    private _disposed;
+    /** Tracks pending steering messages for UI display. Removed when delivered. */
+    private _steeringMessages;
+    /** Tracks pending follow-up messages for UI display. Removed when delivered. */
+    private _followUpMessages;
+    /** Messages queued to be included with the next user prompt as context ("asides"). */
+    private _pendingNextTurnMessages;
+    private _compactionInFlight?;
+    private _compactionAbortController;
+    private _autoCompactionAbortController;
+    private _extensionCompactionQueue;
+    private _extensionCompactionTimer;
+    private _extensionCompactionActivity?;
+    private _extensionCompactionRunning;
+    private _overflowRecoveryAttempted;
+    private _branchSummaryAbortController;
+    private _retryAbortController;
+    private _retryAttempt;
+    private readonly _bashAbortControllers;
+    private _pendingBashMessages;
+    private _extensionRunner;
+    private readonly _extensionLspOwnership;
+    private _turnIndex;
+    private _resourceLoader;
+    private _customTools;
+    private _baseToolDefinitions;
+    private _workspaceToolHost?;
+    private _retiredWorkspaceToolHosts;
+    private _cwd;
+    private _extensionRunnerRef?;
+    private _initialActiveToolNames?;
+    private readonly _enableLspTools?;
+    private _allowedToolNames?;
+    private _excludedToolNames;
+    private _baseToolsOverride?;
+    private _toolOperations?;
+    private _runtimeToolOperations?;
+    private _subagentRunner?;
+    private _subagentRunRegistry?;
+    private _subagentConfigRegistry?;
+    private _trustProjectAgents;
+    private _localResourceToolOperations?;
+    private _sandboxToolOperations?;
+    private _preSandboxToolOperations?;
+    private _lspRuntimeState?;
+    private _lspConfiguration;
+    private readonly _lspConnectionFactories;
+    private readonly _resolveLspConfiguration?;
+    private readonly _onLspConfigurationDiagnostics?;
+    private _runtimeLifecycleQueue;
+    private _sandboxTransitionQueue;
+    private readonly _runtimeLifecycleContext;
+    private readonly _activities;
+    private _activityGeneration;
+    private _activeCycle;
+    private _settlementScheduled;
+    private _settlementRunning;
+    private readonly _idleWaiters;
+    private readonly _barrierOwnerContext;
+    private _sessionStartEvent;
+    private _extensionUIContext?;
+    private _extensionCommandContextActions?;
+    private _extensionAbortHandler?;
+    private _extensionShutdownHandler?;
+    private _extensionErrorListener?;
+    private _extensionErrorUnsubscriber?;
+    private _loadedHooks?;
+    private readonly _resolveHooks?;
+    private _hooksEnabled;
+    private readonly _onHookDiagnostic?;
+    private readonly _hookExecutionListeners;
+    private readonly _hookExecutionActivityListeners;
+    private readonly _hookRunOptions;
+    private readonly _hookAbortController;
+    private _hookSessionStartPromise?;
+    private _hookSessionStartTerminationReason?;
+    private _pendingHookSessionStartContext?;
+    private _hookSessionEnded;
+    private _activePromptId;
+    private _stopHookContinuations;
+    private _stopHookProgress;
+    private readonly _queuedPromptIds;
+    private readonly _toolStartedAt;
+    private readonly _preToolHookContext;
+    private readonly _compressionDetector;
+    private _contextCompressionEnabledOverride?;
+    private _compressionDetectionEnabled;
+    private _agentRunEnding;
+    private _waitingForDetectorAtRequest;
+    private _pendingContextCompression?;
+    private _stateCompressionApplied;
+    private _modelRegistry;
+    private _toolRegistry;
+    private _toolDefinitions;
+    private _sessionTools;
+    private _sessionSkills;
+    private _sessionRules;
+    private _toolPromptSnippets;
+    private _toolPromptGuidelines;
+    private _baseSystemPrompt;
+    private _baseSystemPromptOptions;
+    private _systemPromptOverride?;
+    constructor(config: AgentSessionConfig);
+    /** Model registry for API key resolution and model discovery */
+    get modelRegistry(): ModelRegistry;
+    getToolOperations(): ToolOperations;
+    /** Snapshot of the sole AgentSession-owned LSP runtime and its configured/instantiated servers. */
+    getLspStatus(): LspSessionStatus;
+    /** Validate and replace the AgentSession-owned LSP configuration. Relative paths resolve from the session cwd. */
+    configureLsp(configuration: LspConfigurationLayer): Promise<ResolvedLspConfiguration>;
+    getToolBackendInfo(): ToolBackendInfo;
+    supportsDirectoryChange(): boolean;
+    private _getLocalResourceToolOperations;
+    private _getReadOperationsForPath;
+    configureRemoteSandbox(options: ConfigureRemoteSandboxOptions): Promise<ToolBackendInfo>;
+    activateSandboxDaemon(options: ActivateSandboxDaemonOptions): Promise<ToolBackendInfo>;
+    private _activateSessionRemoteOperations;
+    clearRemoteSandbox(): Promise<void>;
+    private _enqueueSandboxTransition;
+    uploadFile(sourcePath: string, destinationPath: string): Promise<void>;
+    downloadFile(sourcePath: string, destinationPath: string): Promise<void>;
+    private applyToolOperationsBackendChange;
+    private _getRequiredRequestAuth;
+    private _getCompactionRequestAuth;
+    private _hookCommon;
+    private _emitHookExecution;
+    private _emitHookExecutionActivity;
+    private _runHook;
+    private _hasMatchingToolHook;
+    private _hookContextMessage;
+    private _ensureHookSessionStarted;
+    private _reportHookDiagnostic;
+    private _adaptPreToolHookInput;
+    private _resolvePreToolHookPolicy;
+    private _applyPreToolHookInputUpdate;
+    private _emitExtensionToolCall;
+    private _handleBeforeToolCall;
+    private _applyExtensionToolResult;
+    private _runPostToolHook;
+    private _applyPostToolOutputUpdate;
+    private _finalizePostToolHookResult;
+    private _handleAfterToolCall;
+    /**
+     * Install tool hooks once on the Agent instance.
+     *
+     * The callbacks read `this._extensionRunner` at execution time, so extension reload swaps in the
+     * new runner without reinstalling hooks. Extension-specific tool wrappers are still used to adapt
+     * registered tool execution to the extension context. Tool call and tool result interception now
+     * happens here instead of in wrappers.
+     */
+    private _installAgentToolHooks;
+    private _beginActivity;
+    private _endActivity;
+    private _runActivity;
+    private _runSynchronousActivity;
+    private _runAsyncBarrierCallback;
+    private _runBarrierCallback;
+    private _isSettledPredicate;
+    private _scheduleSettlementCheck;
+    private _isCurrentSettlementGeneration;
+    private _finishSettledAgentCycle;
+    private _drainSettlement;
+    private _runRuntimeLifecycleOperation;
+    private _enqueueRuntimeLifecycle;
+    private _syncLspToolResult;
+    private _loadAssociatedInstructionTools;
+    private _loadAssociatedToolsForReadToolCall;
+    private _installAgentTurnPreparation;
+    private _createCompressionAdvisory;
+    /** Add model-only entry ID notices without persisting them. */
+    private _installContextMetadata;
+    private _buildCurrentAgentContext;
+    /** Emit an event to all listeners */
+    private _emit;
+    private _emitAgentSettled;
+    private _emitQueueUpdate;
+    private _lastAssistantMessage;
+    private _consumeStartedQueuedMessage;
+    private _persistCompletedMessage;
+    private _applyPendingContextCompression;
+    private _recordCompressionEconomics;
+    private _restoreCompressionContextState;
+    private _updateRetryStateAfterAssistantMessage;
+    /** Internal handler for agent events - shared by subscribe and reconnect */
+    private _handleAgentEvent;
+    private _willRetryAfterAgentEnd;
+    /** Extract text content from a message */
+    private _getUserMessageText;
+    /** Find the last assistant message in agent state (including aborted ones) */
+    private _findLastAssistantMessage;
+    private _replaceMessageInPlace;
+    private _emitExtensionEvent;
+    /**
+     * 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;
+    /** Subscribe to completed hook executions for host UI rendering. Notices are not persisted or added to model context. */
+    subscribeToHookExecutions(listener: HookExecutionListener): () => void;
+    /** Subscribe to active hook execution changes for host UI rendering. */
+    subscribeToHookExecutionActivity(listener: HookExecutionActivityListener): () => void;
+    /** Whether this session will dispatch subsequent configured hook events. */
+    get hooksEnabled(): boolean;
+    /** Enable or disable subsequent hook dispatches for this session. Active hook executions are not cancelled. */
+    setHooksEnabled(enabled: boolean): void;
+    /** Disconnect from agent events during disposal. */
+    private _disconnectFromAgent;
+    /** Emit the bounded host-local SessionEnd hook once before replacement/disposal. */
+    emitHookSessionEnd(reason: SessionEndReason): Promise<void>;
+    /**
+     * Remove all listeners and disconnect from agent.
+     * Call this when completely done with the session.
+     */
+    dispose(): Promise<void>;
+    /** Stop new prompt admission, abort active work, and wait for the session boundary. */
+    prepareForShutdown(): Promise<void>;
+    private _prepareForShutdown;
+    private _dispose;
+    /** Full agent state */
+    get state(): AgentState;
+    /** Current model (may be undefined if not yet selected) */
+    get model(): Model<any> | undefined;
+    /** Current thinking level */
+    get thinkingLevel(): ThinkingLevel;
+    /** Whether the underlying Agent is currently streaming a response. */
+    get isStreaming(): boolean;
+    private get _hasActiveAgentRun();
+    private _hasPromptAdmission;
+    private get _isAgentRunActive();
+    /** Whether all session-owned work and settlement callbacks have completed. */
+    get isIdle(): boolean;
+    /** Current effective system prompt (includes any per-turn extension modifications) */
+    get systemPrompt(): string;
+    /** Current retry attempt (0 if not retrying) */
+    get retryAttempt(): number;
+    /**
+     * Get the names of currently active tools.
+     * Returns the names of tools currently set on the agent.
+     */
+    getActiveToolNames(): string[];
+    /**
+     * Get all configured tools with name, description, parameter schema, and source metadata.
+     */
+    getAllTools(): ToolInfo[];
+    getToolDefinition(name: string): ToolDefinition | undefined;
+    getRegisteredSkills(): Skill[];
+    getRegisteredRules(): Rule[];
+    registerSessionSkill(skill: SessionSkillRegistration): void;
+    unregisterSessionSkill(name: string): boolean;
+    registerSessionRule(rule: SessionRuleRegistration): void;
+    unregisterSessionRule(name: string): boolean;
+    registerSessionTool(definition: ToolDefinition, options?: RegisterSessionToolOptions): void;
+    unregisterSessionTool(name: string): boolean;
+    loadSessionTool(name: string): boolean;
+    private _loadSessionTool;
+    unloadSessionTool(name: string): boolean;
+    private _unloadSessionTool;
+    getAvailableSessionTools(): ToolInfo[];
+    /**
+     * 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;
+    /** Whether compaction or branch summarization is currently running */
+    get isCompacting(): boolean;
+    /** All messages including custom types like BashExecutionMessage */
+    get messages(): AgentMessage[];
+    /** Current steering mode */
+    get steeringMode(): QueueMode;
+    /** Current follow-up mode */
+    get followUpMode(): QueueMode;
+    /** Current session reference, or undefined for ephemeral sessions. */
+    get sessionReference(): string | undefined;
+    /** Current local session file path, or undefined for non-file-backed sessions. Prefer sessionReference for backend-neutral code. */
+    get sessionFile(): string | undefined;
+    /** Current session ID */
+    get sessionId(): string;
+    /** Current session display name, if set */
+    get sessionName(): string | undefined;
+    /** Scoped models for cycling (from --models flag) */
+    get scopedModels(): ReadonlyArray<ScopedModel>;
+    /** Update scoped models for cycling */
+    setScopedModels(scopedModels: ScopedModel[]): void;
+    /** File-based prompt templates */
+    get promptTemplates(): ReadonlyArray<PromptTemplate>;
+    private _normalizePromptSnippet;
+    private _normalizePromptGuidelines;
+    private _rebuildSystemPrompt;
+    private _buildAvailableToolsPrompt;
+    private _refreshBaseSystemPrompt;
+    private _getSubagentModels;
+    private _resolveSubagentModelHint;
+    private _refreshModelDependentRuntime;
+    private _continueAgentIfReady;
+    private _runAgentPrompt;
+    private _finishFailedRetry;
+    private _resetStopHookContinuationState;
+    private _recordStopHookProgress;
+    private _runStopFailureHook;
+    private _runStopHook;
+    private _handlePostAgentRun;
+    getStructuredResponse<TSchemaValue extends TSchema>(options: StructuredResponseOptions<TSchemaValue>): Promise<StructuredResponse<Static<TSchemaValue>>>;
+    private _requireStructuredResponseModel;
+    private _getStructuredResponse;
+    private _evaluateStructuredResponseAttempt;
+    private _buildStructuredResponseMessages;
+    private _tryParseStructuredAssistantText;
+    private _validateStructuredArguments;
+    private _appendStructuredInternalEntry;
+    private _formatStructuredAssistantLog;
+    private _runPromptAdmission;
+    private _interceptPromptInput;
+    private _expandPromptInput;
+    private _queuePromptIntoActiveRun;
+    private _validatePromptModelAuthentication;
+    private _resumeAfterPromptCompaction;
+    private _buildPromptMessages;
+    private _preparePrompt;
+    /**
+     * Send a prompt to the agent.
+     * - Handles extension commands (registered via the extension API's registerCommand) immediately, even during streaming, when no compaction is active
+     * - 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)
+     * @throws Error if manual or extension-requested compaction is in progress
+     */
+    prompt(text: string, options?: PromptOptions): Promise<void>;
+    private _tryExecuteExtensionCommand;
+    /**
+     * 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;
+    private _expandRuleCommand;
+    /**
+     * Queue a steering message while the agent is running.
+     * Delivered after the current assistant turn finishes executing its tool calls,
+     * before the next LLM call.
+     * Expands skill/rule 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
+     */
+    steer(text: string, images?: ImageContent[]): Promise<void>;
+    /**
+     * 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/rule 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
+     */
+    followUp(text: string, images?: ImageContent[]): Promise<void>;
+    private _queueSteer;
+    private _queueFollowUp;
+    /**
+     * Throw an error if the text is an extension command.
+     */
+    private _throwIfExtensionCommand;
+    /**
+     * 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"
+     */
+    sendCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">, options?: SendCustomMessageOptions): Promise<void>;
+    private _sendCustomMessage;
+    /**
+     * 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"
+     */
+    sendUserMessage(content: string | (TextContent | ImageContent)[], options?: SendUserMessageOptions): Promise<void>;
+    /**
+     * Clear all queued messages and return them.
+     * Useful for restoring to editor when user aborts.
+     * @returns Object with steering and followUp arrays
+     */
+    clearQueue(): QueuedMessages;
+    /** Number of pending messages (includes both steering and follow-up) */
+    get pendingMessageCount(): number;
+    /** Get pending steering messages (read-only) */
+    getSteeringMessages(): readonly string[];
+    /** Get pending follow-up messages (read-only) */
+    getFollowUpMessages(): readonly string[];
+    get resourceLoader(): ResourceLoader;
+    /**
+     * Abort current operation and wait for agent to become idle.
+     */
+    abort(): Promise<void>;
+    private _abortAgentAndDrain;
+    /** Wait for the full AgentSession lifecycle to settle. */
+    waitForIdle(): Promise<void>;
+    private _emitModelSelect;
+    /** Whether agent-initiated context compression is active in this session. */
+    get contextCompressionEnabled(): boolean;
+    /** Toggle compression for this session without changing global settings. */
+    setContextCompressionEnabled(enabled: boolean): void;
+    /** Detection requires both its session opt-in and an active compression tool. */
+    get compressionDetectionEnabled(): boolean;
+    setCompressionDetectionEnabled(enabled: boolean): void;
+    /** Save the detector model and opt in for this session only, without changing the primary model. */
+    setCompressionDetectionModel(reference: string | undefined): void;
+    /**
+     * Set model directly.
+     * Validates that auth is configured, saves to session and settings.
+     * @throws Error if no auth is configured for the model
+     */
+    setModel(model: Model<any>): Promise<void>;
+    /**
+     * 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
+     */
+    cycleModel(direction?: ModelCycleDirection): Promise<ModelCycleResult | undefined>;
+    private _cycleScopedModel;
+    private _cycleAvailableModel;
+    /**
+     * 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: ThinkingLevel): void;
+    /**
+     * Cycle to next thinking level.
+     * @returns New level, or undefined if model doesn't support thinking
+     */
+    cycleThinkingLevel(): ThinkingLevel | undefined;
+    /**
+     * Get available thinking levels for current model.
+     * The provider will clamp to what the specific model supports internally.
+     */
+    getAvailableThinkingLevels(): ThinkingLevel[];
+    /**
+     * Check if current model supports thinking/reasoning.
+     */
+    supportsThinking(): boolean;
+    private _getThinkingLevelForModelSwitch;
+    private _clampThinkingLevel;
+    /**
+     * Set steering message mode.
+     * Saves to settings.
+     */
+    setSteeringMode(mode: QueueMode): void;
+    /**
+     * Set follow-up message mode.
+     * Saves to settings.
+     */
+    setFollowUpMode(mode: QueueMode): void;
+    /** Queue extension-triggered compaction outside the currently active agent turn. */
+    private _requestExtensionCompaction;
+    private _scheduleExtensionCompactions;
+    private _drainExtensionCompactionQueue;
+    private _runRequestedExtensionCompaction;
+    /**
+     * Manually compact the session context.
+     * Aborts current agent operation first.
+     * @param customInstructions Optional instructions for the compaction summary
+     */
+    compact(customInstructions?: string): Promise<CompactionResult>;
+    private _runWithCompactionGuard;
+    private _compactSession;
+    private _prepareForManualCompaction;
+    private _buildManualCompactionPlan;
+    private _runManualCompactionInterceptors;
+    private _resolveManualCompaction;
+    private _commitManualCompaction;
+    private _compactSessionUnlocked;
+    /**
+     * Cancel in-progress compaction (manual or auto).
+     */
+    abortCompaction(): void;
+    /**
+     * Cancel in-progress branch summarization.
+     */
+    abortBranchSummary(): void;
+    private _isAtOrBeforeCompactionBoundary;
+    private _runOverflowCompactionRecovery;
+    private _resolveCompactionThresholdTokens;
+    private _checkCompaction;
+    /**
+     * Internal: Run auto-compaction with events.
+     */
+    private _runAutoCompaction;
+    private _emitAutoCompactionWithoutResult;
+    private _buildAutoCompactionPlan;
+    private _runAutoCompactionInterceptors;
+    private _resolveAutoCompaction;
+    private _commitAutoCompaction;
+    private _runAutoCompactionUnlocked;
+    /**
+     * Toggle auto-compaction setting.
+     */
+    setAutoCompactionEnabled(enabled: boolean): void;
+    /** Whether auto-compaction is enabled */
+    get autoCompactionEnabled(): boolean;
+    /** Whether built-in subagent tools are enabled by default. */
+    get subagentsEnabled(): boolean;
+    /** Persist and immediately apply built-in subagent tool activation. */
+    setSubagentsEnabled(enabled: boolean): void;
+    bindExtensions(bindings: ExtensionBindings): Promise<void>;
+    private _bindExtensions;
+    private extendResourcesFromExtensions;
+    private buildExtensionResourcePaths;
+    private getExtensionSourceLabel;
+    private _applyExtensionBindings;
+    private _refreshCurrentModelFromRegistry;
+    private _updateCurrentRunnerLspOwnership;
+    private _bindExtensionCore;
+    private _createLoadToolDefinition;
+    private _createUnloadToolDefinition;
+    private _resolveRefreshedActiveToolNames;
+    private _refreshToolRegistry;
+    private _registerLspToolDefinitions;
+    private _replaceLspRuntime;
+    private _createWorkspaceToolHost;
+    private _refreshRemoteWorkspaceToolCatalog;
+    private _captureRuntimeBuildSnapshot;
+    private _createRuntimeBaseToolDefinitions;
+    private _initializeRuntimeLsp;
+    private _restoreRuntimeBuildSnapshot;
+    private _buildRuntime;
+    private _withCurrentDefaultTools;
+    private _isToolPermitted;
+    reload(): Promise<AgentSessionReloadResult>;
+    private _reload;
+    /**
+     * Check if an error is retryable (overloaded, rate limit, server errors).
+     * Context overflow errors are NOT retryable (handled by compaction instead).
+     */
+    private _isRetryableError;
+    private _summarizationRetryCallbacks;
+    private _prepareRetry;
+    /**
+     * Cancel in-progress retry.
+     */
+    abortRetry(): void;
+    /** Whether auto-retry is currently in progress */
+    get isRetrying(): boolean;
+    /** Whether auto-retry is enabled */
+    get autoRetryEnabled(): boolean;
+    /**
+     * Toggle auto-retry setting.
+     */
+    setAutoRetryEnabled(enabled: boolean): void;
+    /**
+     * Execute a bash command.
+     * Adds result to agent context and session unless options.record is false.
+     * @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 ToolOperations for remote execution
+     * @param options.record If false, result won't be stored in agent state or session history
+     * @param options.truncate If false, returned output won't be truncated
+     */
+    executeBash(command: string, onChunk?: (chunk: string) => void, options?: ExecuteBashOptions): Promise<BashResult>;
+    /**
+     * Record a bash execution result in session history.
+     * Used by executeBash and by extensions that handle bash execution themselves.
+     */
+    recordBashResult(command: string, result: BashResult, options?: RecordBashResultOptions): void;
+    private _recordBashResult;
+    /**
+     * Cancel running bash command.
+     */
+    abortBash(): void;
+    /** Whether a bash command is currently running */
+    get isBashRunning(): boolean;
+    /** Whether there are pending bash messages waiting to be flushed */
+    get hasPendingBashMessages(): boolean;
+    /**
+     * Flush pending bash messages to agent state and session.
+     * Called after agent turn completes to maintain proper message ordering.
+     */
+    private _flushPendingBashMessages;
+    private _prepareTreeNavigation;
+    private _resolveTreeSummary;
+    private _resolveTreeTarget;
+    private _switchTreeLeaf;
+    /**
+     * Set a display name for the current session.
+     */
+    setSessionName(name: string): void;
+    /**
+     * 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
+     */
+    navigateTree(targetId: string, options?: NavigateTreeOptions): Promise<NavigateTreeResult>;
+    private _navigateTree;
+    /**
+     * Get all user messages from session for fork selector.
+     */
+    getUserMessagesForForking(): ForkableUserMessage[];
+    private _extractUserMessageText;
+    /**
+     * Get session statistics.
+     */
+    getSessionStats(): SessionStats;
+    private _hasUsableAssistantUsageAfterBoundary;
+    getCompressionDetectionCounts(): CompressionDetectionCounts;
+    getCompressionDetectionCost(): number;
+    getContextUsage(): ContextUsage | undefined;
+    /**
+     * Export session to HTML.
+     * @param outputPath Optional output path (defaults to session directory)
+     * @returns Path to exported file
+     */
+    exportToHtml(outputPath?: string): Promise<string>;
+    /**
+     * Export the current session branch to a JSONL file.
+     * Writes the session header followed by all entries on the current branch path.
+     * @param outputPath Target file path. If omitted, generates a timestamped file in cwd.
+     * @returns The resolved output file path.
+     */
+    exportToJsonl(outputPath?: string): string;
+    /**
+     * Get text content of last assistant message.
+     * Useful for /copy command.
+     * @returns Text content, or undefined if no assistant message exists
+     */
+    getLastAssistantText(): string | undefined;
+    createReplacedSessionContext(): ReplacedSessionContext;
+    /**
+     * Check if extensions have handlers for a specific event type.
+     */
+    hasExtensionHandlers(eventType: string): boolean;
+    /**
+     * Get the extension runner (for setting UI context and error handlers).
+     */
+    get extensionRunner(): ExtensionRunner;
+}
+//# sourceMappingURL=agent-session.d.ts.map