@averyyy/pi-coding-agent 0.87.1-piclient.1 → 0.99.1-piclient.1

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";
@@ -38,10 +38,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;
@@ -162,6 +168,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) */
@@ -172,8 +180,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 {
@@ -236,10 +244,16 @@ export declare class AgentSession {
     private _prePromptCompletionPromise;
     private _overflowRecoveryAttempted;
     private _lastServerCompactionTimestamp;
+    private _cachePrefixUnavailableReason;
     private _branchSummaryAbortController;
     private _branchSummaryCompletionPromise;
     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 _sessionNameAbortController;
     private readonly _bashAbortControllers;
     private readonly _bashCompletionPromises;
@@ -277,6 +291,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;
@@ -288,6 +306,21 @@ export declare class AgentSession {
     reconcilePiServerHistory(snapshot: PiServerHistorySnapshot): void;
     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.
      *
@@ -297,6 +330,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;
@@ -329,6 +373,7 @@ export declare class AgentSession {
     private _detachPiServerTerminalAssistantFailure;
     private _restoreSessionLeaf;
     private _replaceMessageInPlace;
+    /** Emit extension events based on agent events */
     private _emitExtensionEvent;
     /**
      * Subscribe to agent events.
@@ -355,6 +400,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 current run is being cancelled. New queued intent is drained after cancellation. */
@@ -368,10 +418,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.
      */
@@ -379,11 +431,24 @@ 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 _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 */
@@ -434,8 +499,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 _runAgentOperation;
     private _runAgentPrompt;
@@ -457,6 +532,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.
@@ -476,7 +554,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.
@@ -487,8 +565,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.
@@ -605,6 +689,7 @@ export declare class AgentSession {
      * Saves to settings.
      */
     setFollowUpMode(mode: "all" | "one-at-a-time"): void;
+    private _buildCompactionCacheInput;
     private _applyPiServerCompactionResult;
     private _clearManualCompactionState;
     /**
@@ -621,7 +706,22 @@ export declare class AgentSession {
      * Cancel in-progress branch summarization.
      */
     abortBranchSummary(): void;
+    /**
+     * Check if compaction is needed and run it.
+     * Called after agent_end and before prompt submission.
+     *
+     * Two cases:
+     * 1. Recoverable failure: LLM returned context overflow or stopped below its desired output limit;
+     *    remove the assistant message, compact, and auto-retry once
+     * 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 _checkCompaction;
+    /**
+     * Internal: Run auto-compaction with events.
+     */
     private _runAutoCompaction;
     /**
      * Toggle auto-compaction setting.
@@ -641,6 +741,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>;
@@ -662,6 +766,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.
@@ -789,4 +897,5 @@ export declare class AgentSession {
      */
     get extensionRunner(): ExtensionRunner;
 }
+export {};
 //# sourceMappingURL=agent-session.d.ts.map