@selesai/code 0.13.39 → 0.14.0

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

@@ -12,18 +12,18 @@
  *
  * Modes use this class and add their own I/O layer on top.
  */
-import type { Agent, AgentEvent, AgentMessage, AgentState, AgentTool, ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { type Agent, type AgentEvent, type AgentMessage, type AgentState, type AgentTool, type ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { ImageContent, Model, TextContent } from "@earendil-works/pi-ai/compat";
 import { type BashResult } from "./bash-executor.ts";
 import type { CacheWarmer, CacheWarmingStatus } from "./cache-warmer.ts";
 import { type CompactionResult } from "./compaction/index.ts";
 import { type ContextUsage, type ExtensionCommandContextActions, type ExtensionErrorListener, type ExtensionMode, ExtensionRunner, type ExtensionUIContext, type InputSource, type ReplacedSessionContext, type SessionStartEvent, type ShutdownHandler, type ToolDefinition, type ToolInfo } from "./extensions/index.ts";
-import type { CustomMessage } from "./messages.ts";
+import { type CustomMessage } from "./messages.ts";
 import type { ModelRuntime } from "./model-runtime.ts";
 import { type PromptTemplate } from "./prompt-templates.ts";
 import type { ResourceLoader } from "./resource-loader.ts";
-import type { BranchSummaryEntry, SessionEntry, SessionManager } from "./session-manager.ts";
-import type { CacheWarmingMode, SettingsManager } from "./settings-manager.ts";
+import { type BranchSummaryEntry, type SessionEntry, SessionManager } from "./session-manager.ts";
+import { type CacheWarmingMode, type SettingsManager } from "./settings-manager.ts";
 import { type BashOperations } from "./tools/bash.ts";
 /** Parsed skill block from a user message */
 export interface ParsedSkillBlock {
@@ -40,15 +40,22 @@ export interface ParsedSkillBlocks {
 export declare function parseSkillBlocks(text: string): ParsedSkillBlocks | null;
 /** Parse one skill block, retained for API compatibility. */
 export declare function parseSkillBlock(text: string): ParsedSkillBlock | null;
+/** Tool execution events of calls a tool made through `ctx.executeTool()` carry `parentToolCallId`. */
+type WithParentToolCallId<E> = E extends {
+    type: "tool_execution_start" | "tool_execution_update" | "tool_execution_end";
+} ? E & {
+    parentToolCallId?: string;
+} : E;
 /** Session-specific events that extend the core AgentEvent */
-export type AgentSessionEvent = Exclude<AgentEvent, {
+export type AgentSessionEvent = WithParentToolCallId<Exclude<AgentEvent, {
     type: "agent_end";
-}> | {
+}>> | {
     type: "agent_end";
     messages: AgentMessage[];
     willRetry: boolean;
 } | {
     type: "agent_settled";
+    aborted: boolean;
 } | {
     type: "queue_update";
     steering: readonly string[];
@@ -136,9 +143,24 @@ export interface AgentSessionConfig {
     cacheWarmer?: Pick<CacheWarmer, "cancel" | "status" | "onAgentSettled" | "onModeChanged" | "onWarmed">;
     /** Initial active built-in tool names. Default: [read, bash, edit, write] */
     initialActiveToolNames?: string[];
-    /** Optional allowlist of tool names. When provided, only these tool names are exposed. */
+    /**
+     * Whether the initial tools come from the `defaultTools` setting. When true, reload activates
+     * tools newly added to the setting. Tools removed from it stay active.
+     */
+    usesDefaultTools?: boolean;
+    /**
+     * `+name`/`-name` entries applied on top of the `defaultTools` setting, from `--tools`. Reload
+     * applies them to the reloaded setting too, so a removed tool stays removed.
+     */
+    defaultToolModifiers?: string[];
+    /**
+     * Optional allowlist of tool names or patterns (`*` matches any characters). When provided, only
+     * matching tools are exposed. A non-empty list without `mcp__` entries also keeps MCP tools
+     * registered for codemode and tool_search; only tool_search can declare them. An empty list
+     * exposes no tools.
+     */
     allowedToolNames?: string[];
-    /** Optional denylist of tool names. When provided, these tool names are not exposed. */
+    /** Optional denylist of tool names or patterns. When provided, matching tools are not exposed. */
     excludedToolNames?: string[];
     /**
      * Override base tools (useful for custom runtimes).
@@ -162,9 +184,11 @@ export interface ExtensionBindings {
     shutdownHandler?: ShutdownHandler;
     onError?: ExtensionErrorListener;
 }
+export type QueuedInputDisposition = "handled" | "queued";
+export type PromptDisposition = QueuedInputDisposition | "started";
 /** Options for AgentSession.prompt() */
 export interface PromptOptions {
-    /** Whether to expand file-based prompt templates (default: true) */
+    /** Whether to dispatch extension commands and expand skill commands and prompt templates (default: true) */
     expandPromptTemplates?: boolean;
     /** Image attachments */
     images?: ImageContent[];
@@ -172,15 +196,15 @@ export interface PromptOptions {
     streamingBehavior?: "steer" | "followUp";
     /** 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;
+    /** Internal hook used by RPC mode to observe how an accepted prompt was dispatched. Not called if the prompt is rejected. */
+    preflightResult?: (disposition: PromptDisposition) => void;
 }
-/** Result from cycleModel() */
-/** Options for model and thinking mutations. */
+/** Options for model/thinking mutations. */
 export interface ModelMutationOptions {
-    /** Persist the value to global defaults. Defaults to session-only. */
+    /** Persist the new value to global defaults. Defaults to session-only. */
     persist?: boolean;
 }
+/** Result from cycleModel() */
 export interface ModelCycleResult {
     model: Model<any>;
     thinkingLevel: ThinkingLevel;
@@ -231,19 +255,47 @@ export declare class AgentSession {
     private _branchSummaryAbortController;
     private _retryAbortController;
     private _retryAttempt;
+    /**
+     * Failed response that the next request repeats, set by auto-retry and overflow recovery. The
+     * retry is routed with it as `failed`, since the context no longer contains it.
+     */
+    private _failedResponse;
     private _lengthContinuations;
     private readonly _bashAbortControllers;
     private _pendingBashMessages;
     private _extensionRunner;
     private _turnIndex;
+    private readonly _entryIdsByMessage;
+    private readonly _boundaryDispatchedMessages;
+    private _lastAssistantMessage;
+    private _lastAssistantToolResults;
+    private _lastActivityOutcome;
+    private _isBeforeSettle;
+    private _abortDuringBeforeSettle;
+    private _isEmittingAgentSettled;
+    private readonly _deferredSettledActions;
     private _resourceLoader;
     private _customTools;
     private _baseToolDefinitions;
     private _cwd;
     private _extensionRunnerRef?;
     private _initialActiveToolNames?;
-    private _allowedToolNames?;
-    private _excludedToolNames?;
+    /**
+     * Tools of the restored or reloaded loadout that are not registered yet, such as tools of MCP
+     * servers that are still connecting. They are activated when they are registered, and dropped when
+     * `setActiveToolsByName()` deactivates a tool or the next agent run starts.
+     */
+    private _pendingToolNames;
+    private _usesDefaultTools;
+    private _defaultToolModifiers;
+    /** Matches the `--tools` entries: tool names or patterns. */
+    private _allowedTools?;
+    /**
+     * Whether the allowlist filters MCP tools: it is empty (`--no-tools`) or names an MCP tool
+     * (`mcp__*`). Otherwise it keeps MCP tools registered for codemode and tool_search.
+     */
+    private _allowlistFiltersMcp;
+    private _excludedTools?;
     private _baseToolsOverride?;
     private _sessionStartEvent;
     private _extensionUIContext?;
@@ -256,6 +308,10 @@ export declare class AgentSession {
     private _modelRuntime;
     private _cacheWarmer?;
     private _toolRegistry;
+    /** Created on the first `ctx.executeTool()` call. */
+    private _nestedToolCalls;
+    /** Declared tools whose declarations requests leave out, from `prepareLoadout` hooks. */
+    private _hiddenDeclarations;
     private _toolDefinitions;
     private _toolPromptSnippets;
     private _toolPromptGuidelines;
@@ -266,6 +322,21 @@ export declare class AgentSession {
     get modelRuntime(): ModelRuntime;
     private _getRequiredRequestAuth;
     private _getSummarizationRequestAuth;
+    /**
+     * The model whose limits apply to `message`, or undefined when the message came from another
+     * model. Under a virtual selection, that is the physical model that produced it.
+     */
+    private _modelForMessage;
+    /**
+     * Record the selection on the current branch when the branch implies another one, so a resume
+     * restores it. Tree navigation can leave the latest `model_change` on another branch; responses
+     * cannot record a virtual selection because they name physical models. Responses do record a
+     * physical selection unless the branch holds a virtual one; checking a physical selection against
+     * responses would record it on every prompt while `prepareRequest` redirects to another model.
+     */
+    private _recordSelection;
+    /** The model whose limits apply to the conversation. */
+    private _limitsModel;
     /**
      * Install tool hooks once on the Agent instance.
      *
@@ -275,8 +346,23 @@ export declare class AgentSession {
      * happens here instead of in wrappers.
      */
     private _installAgentToolHooks;
+    private _beforeToolCall;
+    private _afterToolCall;
+    private _executeNestedToolCall;
+    /** Whether `projection`, the current session projection, exceeds the compaction threshold of `model`. */
+    private _exceedsCompactionThreshold;
     private _compactBeforeNextAssistantResponse;
+    private _installAgentRequestProjection;
+    private _dispatchTurnEndBoundary;
+    private _installAgentBoundaryHooks;
     private _installAgentNextTurnRefresh;
+    private _refreshFinalizedContext;
+    private _applyBoundaryDrafts;
+    private _createBoundaryPreviewManager;
+    private _getPendingBoundaryMessages;
+    private _buildBoundaryContext;
+    private _commitBoundaryDrafts;
+    private _reportInvalidBoundaryContinuation;
     /** Emit an event to all listeners */
     private _emit;
     private _emitQueueUpdate;
@@ -284,12 +370,11 @@ export declare class AgentSession {
     private _getIdleWaitPromise;
     private _resolveIdleWaitIfIdle;
     private _emitAgentSettled;
-    private _autoHandoffTriggered;
-    private _checkAutoHandoff;
-    private _lastAssistantMessage;
     /** Internal handler for agent events - shared by subscribe and reconnect */
     private _handleAgentEvent;
     private _willRetryAfterAgentEnd;
+    private _findPersistedMessageEntryId;
+    private _omitRecoveryAttempt;
     /** Find the last assistant message in agent state (including aborted ones) */
     private _findLastAssistantMessage;
     private _replaceMessageInPlace;
@@ -301,22 +386,15 @@ export declare class AgentSession {
      * Multiple listeners can be added. Returns unsubscribe function for this listener.
      */
     subscribe(listener: AgentSessionEventListener): () => void;
-    /**
-     * 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.
-     */
+    /** Disconnect from agent events during disposal. */
     private _disconnectFromAgent;
-    /**
-     * Reconnect to agent events after _disconnectFromAgent().
-     * Preserves all existing listeners.
-     */
-    private _reconnectToAgent;
     /**
      * Remove all listeners and disconnect from agent.
      * Call this when completely done with the session.
      */
     dispose(): void;
+    /** Refresh the public finalized transcript from the canonical session projection. */
+    refreshContext(): void;
     /** Full agent state */
     get state(): AgentState;
     /** Current cache-warming state and the policy inputs that produced it. */
@@ -327,6 +405,11 @@ export declare class AgentSession {
     get model(): Model<any> | undefined;
     /** Current thinking level */
     get thinkingLevel(): ThinkingLevel;
+    /** Under a virtual selection, the physical model and thinking level of the latest successful response. */
+    get routedModel(): {
+        model: Model<any>;
+        thinkingLevel?: ThinkingLevel;
+    } | undefined;
     /** Whether the session is currently processing an agent run or post-run continuation. */
     get isStreaming(): boolean;
     /** Whether the session has no active agent run, compaction, branch summary, retry, or queued continuation. */
@@ -336,10 +419,12 @@ export declare class AgentSession {
     /** 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.
+     * Get the names of currently active tools, which are the tools declared to the model.
+     * Tools with `codemode` or `deferred` exposure are callable from other tools without being active.
      */
     getActiveToolNames(): string[];
+    /** Get the names of the tools that tools can call through `ctx.executeTool()`. */
+    getCallableToolNames(): string[];
     /**
      * Get all configured tools with name, description, parameter schema, prompt guidelines, and source metadata.
      */
@@ -347,11 +432,37 @@ export declare class AgentSession {
     getToolDefinition(name: string): ToolDefinition | undefined;
     /**
      * Set active tools by name.
-     * Only tools in the registry can be enabled. Unknown tool names are ignored.
+     * Only tools in the registry can be enabled. Unknown and hidden 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;
+    private _setActiveTools;
+    /**
+     * Whether `--tools` and `--exclude-tools` keep the tool registered. MCP tools stay registered
+     * unless the allowlist filters them (see `_allowlistFiltersMcp`).
+     */
+    private _isAllowedTool;
+    /**
+     * Whether the tool may be active, which declares it to the model. MCP tools the allowlist keeps
+     * without matching them are only for codemode and tool_search: they may be declared only when
+     * tool_search can load them (non-`direct` exposure and tool_search registered). This also applies
+     * to tools restored from the transcript or set by extensions.
+     */
+    private _isActivatable;
+    private _getToolExposure;
+    /**
+     * Tools callable through `ctx.executeTool()`: the active `direct` tools and every registered
+     * `codemode` or `deferred` tool.
+     */
+    private _getCallableTools;
+    /**
+     * Set the agent's tools for the given active tool names and return them. The active tools are
+     * the registered, non-hidden ones; they are declared to the model. Active tools with a
+     * `prepareLoadout` hook can change the declared descriptions and hide declarations from
+     * requests (see {@link _installHiddenDeclarationsProjection}).
+     */
+    private _applyToolLoadout;
     /** Whether compaction or branch summarization is currently running */
     get isCompacting(): boolean;
     /** All messages including custom types like BashExecutionMessage */
@@ -402,12 +513,24 @@ export declare class AgentSession {
      * collapse into one head holding the forced text and the current tools. Runs after the
      * `context` extension handlers.
      */
+    /**
+     * Remove the declarations that `prepareLoadout` hooks hide from every request. The whole
+     * transcript is filtered with the current set, so the projected declarations stay consistent
+     * across requests and only change when the loadout does.
+     */
+    private _installHiddenDeclarationsProjection;
     private _installAgentForcedPromptProjection;
-    /** Restore the active tool loadout declared by the session transcript, if it declares one. */
+    /**
+     * Restore the active tool loadout declared by the session transcript, if it declares one.
+     * Tools reachable only from other tools are never declared, but they do not depend on the active
+     * set, so the transcript's declarations are the whole loadout.
+     */
     private _restoreToolsFromTranscript;
     private _runAgentPrompt;
     private _handlePostAgentRun;
+    private _runBeforeSettleBoundary;
     private _runInputHandlers;
+    private _normalizePromptImages;
     /**
      * Send a prompt to the agent.
      * - Handles extension commands (registered via pi.registerCommand) immediately, even during streaming
@@ -437,7 +560,7 @@ export declare class AgentSession {
      */
     steer(text: string, images?: ImageContent[], options?: {
         source?: InputSource;
-    }): Promise<void>;
+    }): Promise<QueuedInputDisposition>;
     /**
      * Queue a follow-up message to be processed after the agent finishes.
      * Delivered only when agent has no more tool calls or steering messages.
@@ -448,7 +571,7 @@ export declare class AgentSession {
      */
     followUp(text: string, images?: ImageContent[], options?: {
         source?: InputSource;
-    }): Promise<void>;
+    }): Promise<QueuedInputDisposition>;
     private _queueSteer;
     private _queueFollowUp;
     /**
@@ -503,6 +626,7 @@ export declare class AgentSession {
      *
      * @param content User message content (string or content array)
      * @param options.deliverAs Delivery mode when streaming: "steer" or "followUp"
+     * @param options.expandPromptTemplates Whether to dispatch extension commands and expand skill commands and prompt templates. Default: false.
      */
     sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
         deliverAs?: "steer" | "followUp";
@@ -534,7 +658,8 @@ export declare class AgentSession {
     private _emitModelSelect;
     /**
      * Set model directly.
-     * Validates that auth is configured, saves to session and settings.
+     * Validates that auth is configured and saves to the session transcript.
+     * Persists to global defaults only when options.persist is true.
      * @throws Error if no auth is configured for the model
      */
     setModel(model: Model<any>, options?: ModelMutationOptions): Promise<void>;
@@ -551,7 +676,8 @@ export declare class AgentSession {
     /**
      * Set thinking level.
      * Clamps to model capabilities based on available thinking levels.
-     * Saves to session and settings only if the level actually changes.
+     * Saves the clamped level to the session transcript only if the level actually changes.
+     * Persists the requested level to global defaults only when options.persist is true.
      */
     setThinkingLevel(level: ThinkingLevel, options?: ModelMutationOptions): void;
     /**
@@ -585,7 +711,17 @@ export declare class AgentSession {
     private _clearManualCompactionState;
     /**
      * Manually compact the session context.
-     * Aborts current agent operation first.
+     *
+     * This is the manual entry point used by `/compact`, RPC, and extensions. It is
+     * separate from automatic threshold/overflow compaction, which enters through
+     * `_checkCompaction()` and `_runAutoCompaction()`. After preparation and the
+     * `session_before_compact` hook, both paths call the lower-level `compact()`
+     * function imported from `./compaction/index.ts`, unless the hook cancels or
+     * supplies a custom result.
+     *
+     * Aborts the current agent operation first. Manual compaction never retries or
+     * continues the interrupted agent turn.
+     *
      * @param customInstructions Optional instructions for the compaction summary
      */
     compact(customInstructions?: string): Promise<CompactionResult>;
@@ -605,8 +741,6 @@ export declare class AgentSession {
     setAutoCompactionEnabled(enabled: boolean): void;
     /** Whether auto-compaction is enabled */
     get autoCompactionEnabled(): boolean;
-    get autoHandoffEnabled(): boolean;
-    get autoHandoffThresholdTokens(): number;
     bindExtensions(bindings: ExtensionBindings): Promise<void>;
     private extendResourcesFromExtensions;
     private buildExtensionResourcePaths;
@@ -615,6 +749,10 @@ export declare class AgentSession {
     private _refreshCurrentModelFromRegistry;
     private _bindExtensionCore;
     private _refreshToolRegistry;
+    /** Whether activating the tool declares it to the model. */
+    private _isDeclarable;
+    /** Whether registering the tool activates it, which declares it to the model. */
+    private _isActivatedOnRegistration;
     private _buildRuntime;
     reload(options?: {
         beforeSessionStart?: () => void | Promise<void>;
@@ -722,6 +860,7 @@ export declare class AgentSession {
     /**
      * Export session to HTML.
      * @param outputPath Optional output path (defaults to session directory)
+     * @param options Optional export presentation settings
      * @returns Path to exported file
      */
     exportToHtml(outputPath?: string, options?: {
@@ -758,3 +897,4 @@ export declare class AgentSession {
      */
     get extensionRunner(): ExtensionRunner;
 }
+export {};