pi-namespace-patch 0.87.1-namespace.1 → 1.0.0-namespace.2

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

@@ -12,7 +12,7 @@
  *
  * 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";
@@ -23,7 +23,7 @@ import type { ModelRuntime } from "./model-runtime.ts";
 import { type PromptTemplate } from "./prompt-templates.ts";
 import type { ResourceLoader } from "./resource-loader.ts";
 import { type BranchSummaryEntry, type SessionEntry, SessionManager } from "./session-manager.ts";
-import type { CacheWarmingMode, SettingsManager } from "./settings-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 {
@@ -37,10 +37,16 @@ export interface ParsedSkillBlock {
  * Returns null if the text doesn't contain a skill block.
  */
 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;
@@ -122,6 +128,11 @@ export interface AgentSessionConfig {
     cacheWarmer?: Pick<CacheWarmer, "cancel" | "status" | "onAgentSettled" | "onModeChanged" | "onWarmed">;
     /** Initial active built-in tool names. Default: [read, bash, edit, write] */
     initialActiveToolNames?: string[];
+    /**
+     * 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;
     /** Optional allowlist of tool names. When provided, only these tool names are exposed. */
     allowedToolNames?: string[];
     /** Optional denylist of tool names. When provided, these tool names are not exposed. */
@@ -148,6 +159,8 @@ 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 dispatch extension commands and expand skill commands and prompt templates (default: true) */
@@ -158,8 +171,8 @@ 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;
 }
 /** Options for model/thinking mutations. */
 export interface ModelMutationOptions {
@@ -217,6 +230,11 @@ 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 readonly _bashAbortControllers;
     private _pendingBashMessages;
     private _extensionRunner;
@@ -236,6 +254,13 @@ export declare class AgentSession {
     private _cwd;
     private _extensionRunnerRef?;
     private _initialActiveToolNames?;
+    /**
+     * 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 _allowedToolNames?;
     private _excludedToolNames?;
     private _baseToolsOverride?;
@@ -250,6 +275,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;
@@ -260,6 +289,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.
      *
@@ -269,6 +313,17 @@ export declare class AgentSession {
      * happens here instead of in wrappers.
      */
     private _installAgentToolHooks;
+    /** `tool_call` handlers. `parentToolCallId` is set for calls another tool made. */
+    private _beforeToolCall;
+    /** `tool_result` handlers and image normalization. `parentToolCallId` is set for calls another tool made. */
+    private _afterToolCall;
+    /**
+     * Run a call that the tool call `parentToolCallId` made through `ctx.executeTool()`. It goes
+     * through the agent's tool pipeline with the session's hooks, against the callable tools.
+     */
+    private _executeNestedToolCall;
+    /** Whether `projection`, the current session projection, exceeds the compaction threshold of `model`. */
+    private _exceedsCompactionThreshold;
     private _compactBeforeNextAssistantResponse;
     private _installAgentRequestProjection;
     private _dispatchTurnEndBoundary;
@@ -296,6 +351,7 @@ export declare class AgentSession {
     /** Find the last assistant message in agent state (including aborted ones) */
     private _findLastAssistantMessage;
     private _replaceMessageInPlace;
+    /** Emit extension events based on agent events */
     private _emitExtensionEvent;
     /**
      * Subscribe to agent events.
@@ -322,6 +378,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. */
@@ -331,10 +392,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.
      */
@@ -342,11 +405,26 @@ 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;
+    private _isAllowedTool;
+    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 */
@@ -397,8 +475,18 @@ 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;
@@ -415,6 +503,9 @@ export declare class AgentSession {
      * @throws Error if no model selected or no API key available (when not streaming)
      */
     prompt(text: string, options?: PromptOptions): Promise<void>;
+    /**
+     * Try to execute an extension command. Returns true if command was found and executed.
+     */
     private _tryExecuteExtensionCommand;
     /**
      * Expand skill commands (/skill:name args) to their full content.
@@ -443,7 +534,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.
@@ -454,8 +545,14 @@ export declare class AgentSession {
      */
     followUp(text: string, images?: ImageContent[], options?: {
         source?: InputSource;
-    }): Promise<void>;
+    }): Promise<QueuedInputDisposition>;
+    /**
+     * Internal: Queue a steering message (already expanded, no extension command check).
+     */
     private _queueSteer;
+    /**
+     * Internal: Queue a follow-up message (already expanded, no extension command check).
+     */
     private _queueFollowUp;
     /**
      * Throw an error if the text is an extension command.
@@ -569,6 +666,7 @@ export declare class AgentSession {
      * Saves to settings.
      */
     setFollowUpMode(mode: "all" | "one-at-a-time"): void;
+    /** Generate Pi's built-in compaction summary for manual and automatic compaction. */
     private _runDefaultCompaction;
     private _clearManualCompactionState;
     /**
@@ -595,7 +693,38 @@ export declare class AgentSession {
      * Cancel in-progress branch summarization.
      */
     abortBranchSummary(): void;
+    /**
+     * Dispatch automatic compaction after `agent_end` or before prompt submission.
+     * Manual compaction does not call this method; it enters through `compact()`.
+     *
+     * Automatic cases:
+     * 1. Overflow with retry: a context-overflow error or recoverable length stop;
+     *    remove the failed assistant message, compact, and retry the turn once.
+     * 2. Overflow without retry: a successful response exceeded the configured
+     *    context window; compact but preserve the completed response.
+     * 3. Threshold without retry: valid or estimated context usage crossed the
+     *    configured threshold; compact without retrying the completed response.
+     *
+     * Each case calls `_runAutoCompaction()`. After preparation and the
+     * `session_before_compact` hook, that method calls the lower-level `compact()`
+     * function imported from `./compaction/index.ts`, unless the hook cancels or
+     * supplies a custom result.
+     *
+     * @param assistantMessage The assistant message to check
+     * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
+     * @returns Whether the post-run loop should call `agent.continue()` for overflow recovery or queued messages
+     */
     private _checkCompaction;
+    /**
+     * Execute threshold or overflow compaction. Manual compaction uses
+     * `AgentSession.compact()` instead. Both paths call the lower-level `compact()`
+     * function imported from `./compaction/index.ts` after preparation and extension
+     * interception.
+     *
+     * @param reason Automatic trigger selected by `_checkCompaction()`
+     * @param willRetry Whether to continue the interrupted turn after overflow compaction
+     * @returns Whether the post-run loop should call `agent.continue()`
+     */
     private _runAutoCompaction;
     /**
      * Toggle auto-compaction setting.
@@ -611,6 +740,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>;
@@ -628,6 +761,10 @@ export declare class AgentSession {
      */
     private _summarizationRetryCallbacks;
     private _finishCancelledRetry;
+    /**
+     * Prepare a retryable error for continuation with exponential backoff.
+     * @returns true if the caller should continue the agent, false otherwise
+     */
     private _prepareRetry;
     /**
      * Cancel in-progress retry.
@@ -755,4 +892,5 @@ export declare class AgentSession {
      */
     get extensionRunner(): ExtensionRunner;
 }
+export {};
 //# sourceMappingURL=agent-session.d.ts.map