@phi-code-admin/phi-code 0.74.2 → 0.75.0

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

@@ -16,14 +16,14 @@ import type { Agent, AgentEvent, AgentMessage, AgentState, AgentTool, ThinkingLe
 import type { ImageContent, Model, TextContent } from "phi-code-ai";
 import { type BashResult } from "./bash-executor.js";
 import { type CompactionResult } from "./compaction/index.js";
-import { type ContextUsage, type ExtensionCommandContextActions, type ExtensionErrorListener, ExtensionRunner, type ExtensionUIContext, type InputSource, type ShutdownHandler, type ToolDefinition, type ToolInfo } from "./extensions/index.js";
+import { type ContextUsage, type ExtensionCommandContextActions, type ExtensionErrorListener, ExtensionRunner, type ExtensionUIContext, type InputSource, type ReplacedSessionContext, type SessionStartEvent, type ShutdownHandler, type ToolDefinition, type ToolInfo } from "./extensions/index.js";
 import type { CustomMessage } from "./messages.js";
 import type { ModelRegistry } from "./model-registry.js";
 import { type PromptTemplate } from "./prompt-templates.js";
 import type { ResourceLoader } from "./resource-loader.js";
 import type { BranchSummaryEntry, SessionManager } from "./session-manager.js";
 import type { SettingsManager } from "./settings-manager.js";
-import type { BashOperations } from "./tools/bash.js";
+import { type BashOperations } from "./tools/bash.js";
 /** Parsed skill block from a user message */
 export interface ParsedSkillBlock {
     name: string;
@@ -38,10 +38,21 @@ export interface ParsedSkillBlock {
 export declare function parseSkillBlock(text: string): ParsedSkillBlock | null;
 /** Session-specific events that extend the core AgentEvent */
 export type AgentSessionEvent = AgentEvent | {
-    type: "auto_compaction_start";
-    reason: "threshold" | "overflow";
+    type: "queue_update";
+    steering: readonly string[];
+    followUp: readonly string[];
 } | {
-    type: "auto_compaction_end";
+    type: "compaction_start";
+    reason: "manual" | "threshold" | "overflow";
+} | {
+    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;
@@ -78,12 +89,21 @@ export interface AgentSessionConfig {
     modelRegistry: ModelRegistry;
     /** Initial active built-in tool names. Default: [read, bash, edit, write] */
     initialActiveToolNames?: string[];
-    /** Override base tools (useful for custom runtimes). */
+    /** Optional allowlist of tool names. When provided, only these tool names are exposed. */
+    allowedToolNames?: 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?: {
         current?: ExtensionRunner;
     };
+    /** Session start event metadata emitted when extensions bind to this runtime. */
+    sessionStartEvent?: SessionStartEvent;
 }
 export interface ExtensionBindings {
     uiContext?: ExtensionUIContext;
@@ -101,6 +121,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;
 }
 /** Result from cycleModel() */
 export interface ModelCycleResult {
@@ -126,6 +148,7 @@ export interface SessionStats {
         total: number;
     };
     cost: number;
+    contextUsage?: ContextUsage;
 }
 export declare class AgentSession {
     readonly agent: Agent;
@@ -155,11 +178,13 @@ export declare class AgentSession {
     private _turnIndex;
     private _resourceLoader;
     private _customTools;
-    private _baseToolRegistry;
+    private _baseToolDefinitions;
     private _cwd;
     private _extensionRunnerRef?;
     private _initialActiveToolNames?;
+    private _allowedToolNames?;
     private _baseToolsOverride?;
+    private _sessionStartEvent;
     private _extensionUIContext?;
     private _extensionCommandContextActions?;
     private _extensionShutdownHandler?;
@@ -167,14 +192,27 @@ export declare class AgentSession {
     private _extensionErrorUnsubscriber?;
     private _modelRegistry;
     private _toolRegistry;
+    private _toolDefinitions;
     private _toolPromptSnippets;
     private _toolPromptGuidelines;
     private _baseSystemPrompt;
+    private _baseSystemPromptOptions;
     constructor(config: AgentSessionConfig);
     /** Model registry for API key resolution and model discovery */
     get modelRegistry(): ModelRegistry;
+    private _getRequiredRequestAuth;
+    /**
+     * 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;
     /** Emit an event to all listeners */
     private _emit;
+    private _emitQueueUpdate;
     private _lastAssistantMessage;
     /** Internal handler for agent events - shared by subscribe and reconnect */
     private _handleAgentEvent;
@@ -187,7 +225,7 @@ export declare class AgentSession {
     private _getUserMessageText;
     /** Find the last assistant message in agent state (including aborted ones) */
     private _findLastAssistantMessage;
-    /** Emit extension events based on agent events */
+    private _replaceMessageInPlace;
     private _emitExtensionEvent;
     /**
      * Subscribe to agent events.
@@ -229,9 +267,10 @@ export declare class AgentSession {
      */
     getActiveToolNames(): string[];
     /**
-     * Get all configured tools with name, description, and parameter schema.
+     * Get all configured tools with name, description, parameter schema, and source metadata.
      */
     getAllTools(): ToolInfo[];
+    getToolDefinition(name: string): ToolDefinition | undefined;
     /**
      * Set active tools by name.
      * Only tools in the registry can be enabled. Unknown tool names are ignored.
@@ -278,9 +317,6 @@ 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.
@@ -289,8 +325,9 @@ export declare class AgentSession {
      */
     private _expandSkillCommand;
     /**
-     * Queue a steering message to interrupt the agent mid-run.
-     * Delivered after current tool execution, skips remaining tools.
+     * 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 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
@@ -304,13 +341,7 @@ export declare class AgentSession {
      * @throws Error if text is an extension command
      */
     followUp(text: string, images?: ImageContent[]): Promise<void>;
-    /**
-     * 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.
@@ -362,23 +393,11 @@ export declare class AgentSession {
      * Abort current operation and wait for agent to become idle.
      */
     abort(): Promise<void>;
-    /**
-     * Start a new session, optionally with initial messages and parent tracking.
-     * Clears all messages and starts a new session.
-     * Listeners are preserved and will continue receiving events.
-     * @param options.parentSession - Optional parent session path for tracking
-     * @param options.setup - Optional callback to initialize session (e.g., append messages)
-     * @returns true if completed, false if cancelled by extension
-     */
-    newSession(options?: {
-        parentSession?: string;
-        setup?: (sessionManager: SessionManager) => Promise<void>;
-    }): Promise<boolean>;
     private _emitModelSelect;
     /**
      * Set model directly.
-     * Validates API key, saves to session and settings.
-     * @throws Error if no API key available for the model
+     * 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>;
     /**
@@ -388,7 +407,6 @@ export declare class AgentSession {
      * @returns The new model info, or undefined if only one model available
      */
     cycleModel(direction?: "forward" | "backward"): Promise<ModelCycleResult | undefined>;
-    private _getScopedModelsWithApiKey;
     private _cycleScopedModel;
     private _cycleAvailableModel;
     /**
@@ -407,10 +425,6 @@ export declare class AgentSession {
      * The provider will clamp to what the specific model supports internally.
      */
     getAvailableThinkingLevels(): ThinkingLevel[];
-    /**
-     * Check if current model supports xhigh thinking level.
-     */
-    supportsXhighThinking(): boolean;
     /**
      * Check if current model supports thinking/reasoning.
      */
@@ -441,21 +455,7 @@ 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. Overflow: LLM returned context overflow error, remove error message from agent state, compact, auto-retry
-     * 2. Threshold: Context over threshold, compact, NO auto-retry (user continues manually)
-     *
-     * @param assistantMessage The assistant message to check
-     * @param skipAbortedCheck If false, include aborted messages (for pre-prompt check). Default: true
-     */
     private _checkCompaction;
-    /**
-     * Internal: Run auto-compaction with events.
-     */
     private _runAutoCompaction;
     /**
      * Toggle auto-compaction setting.
@@ -468,6 +468,7 @@ export declare class AgentSession {
     private buildExtensionResourcePaths;
     private getExtensionSourceLabel;
     private _applyExtensionBindings;
+    private _refreshCurrentModelFromRegistry;
     private _bindExtensionCore;
     private _refreshToolRegistry;
     private _buildRuntime;
@@ -477,19 +478,11 @@ export declare class AgentSession {
      * Context overflow errors are NOT retryable (handled by compaction instead).
      */
     private _isRetryableError;
-    /**
-     * Handle retryable errors with exponential backoff.
-     * @returns true if retry was initiated, false if max retries exceeded or disabled
-     */
     private _handleRetryableError;
     /**
      * Cancel in-progress retry.
      */
     abortRetry(): void;
-    /**
-     * Wait for any in-progress retry to complete.
-     * Returns immediately if no retry is in progress.
-     */
     private waitForRetry;
     /** Whether auto-retry is currently in progress */
     get isRetrying(): boolean;
@@ -531,30 +524,10 @@ export declare class AgentSession {
      * Called after agent turn completes to maintain proper message ordering.
      */
     private _flushPendingBashMessages;
-    /**
-     * Switch to a different session file.
-     * Aborts current operation, loads messages, restores model/thinking.
-     * Listeners are preserved and will continue receiving events.
-     * @returns true if switch completed, false if cancelled by extension
-     */
-    switchSession(sessionPath: string): Promise<boolean>;
     /**
      * Set a display name for the current session.
      */
     setSessionName(name: string): void;
-    /**
-     * Create a fork from a specific entry.
-     * Emits before_fork/fork session events to extensions.
-     *
-     * @param entryId ID of the entry to fork from
-     * @returns Object with:
-     *   - selectedText: The text of the selected user message (for editor pre-fill)
-     *   - cancelled: True if an extension cancelled the fork
-     */
-    fork(entryId: string): Promise<{
-        selectedText: string;
-        cancelled: boolean;
-    }>;
     /**
      * Navigate to a different node in the session tree.
      * Unlike fork() which creates a new session file, this stays in the same file.
@@ -596,12 +569,20 @@ export declare class AgentSession {
      * @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.
      */
@@ -609,6 +590,6 @@ export declare class AgentSession {
     /**
      * Get the extension runner (for setting UI context and error handlers).
      */
-    get extensionRunner(): ExtensionRunner | undefined;
+    get extensionRunner(): ExtensionRunner;
 }
 //# sourceMappingURL=agent-session.d.ts.map