@vandeepunk/pi-coding-agent 0.0.6 → 1.0.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 "@mariozechner/pi-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 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,15 @@ 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: "compaction_end";
+    reason: "manual" | "threshold" | "overflow";
     result: CompactionResult | undefined;
     aborted: boolean;
     willRetry: boolean;
@@ -68,7 +73,7 @@ export interface AgentSessionConfig {
     /** Models to cycle through with Ctrl+P (from --models flag) */
     scopedModels?: Array<{
         model: Model<any>;
-        thinkingLevel: ThinkingLevel;
+        thinkingLevel?: ThinkingLevel;
     }>;
     /** Resource loader for skills, prompts, themes, context files, system prompt */
     resourceLoader: ResourceLoader;
@@ -78,12 +83,19 @@ 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). */
+    /**
+     * 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;
@@ -126,6 +138,7 @@ export interface SessionStats {
         total: number;
     };
     cost: number;
+    contextUsage?: ContextUsage;
 }
 export declare class AgentSession {
     readonly agent: Agent;
@@ -134,6 +147,7 @@ export declare class AgentSession {
     private _scopedModels;
     private _unsubscribeAgent?;
     private _eventListeners;
+    private _agentEventQueue;
     /** Tracks pending steering messages for UI display. Removed when delivered. */
     private _steeringMessages;
     /** Tracks pending follow-up messages for UI display. Removed when delivered. */
@@ -142,6 +156,7 @@ export declare class AgentSession {
     private _pendingNextTurnMessages;
     private _compactionAbortController;
     private _autoCompactionAbortController;
+    private _overflowRecoveryAttempted;
     private _branchSummaryAbortController;
     private _retryAbortController;
     private _retryAttempt;
@@ -153,11 +168,12 @@ export declare class AgentSession {
     private _turnIndex;
     private _resourceLoader;
     private _customTools;
-    private _baseToolRegistry;
+    private _baseToolDefinitions;
     private _cwd;
     private _extensionRunnerRef?;
     private _initialActiveToolNames?;
     private _baseToolsOverride?;
+    private _sessionStartEvent;
     private _extensionUIContext?;
     private _extensionCommandContextActions?;
     private _extensionShutdownHandler?;
@@ -165,15 +181,32 @@ export declare class AgentSession {
     private _extensionErrorUnsubscriber?;
     private _modelRegistry;
     private _toolRegistry;
+    private _toolDefinitions;
+    private _toolPromptSnippets;
+    private _toolPromptGuidelines;
     private _baseSystemPrompt;
     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;
+    private _createRetryPromiseForAgentEnd;
+    private _findLastAssistantInMessages;
+    private _processAgentEvent;
     /** Resolve the pending retry promise */
     private _resolveRetry;
     /** Extract text content from a message */
@@ -221,9 +254,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.
@@ -231,7 +265,7 @@ export declare class AgentSession {
      * Changes take effect on the next agent turn.
      */
     setActiveToolsByName(toolNames: string[]): void;
-    /** Whether auto-compaction is currently running */
+    /** Whether compaction or branch summarization is currently running */
     get isCompacting(): boolean;
     /** All messages including custom types like BashExecutionMessage */
     get messages(): AgentMessage[];
@@ -248,15 +282,17 @@ export declare class AgentSession {
     /** Scoped models for cycling (from --models flag) */
     get scopedModels(): ReadonlyArray<{
         model: Model<any>;
-        thinkingLevel: ThinkingLevel;
+        thinkingLevel?: ThinkingLevel;
     }>;
     /** Update scoped models for cycling */
     setScopedModels(scopedModels: Array<{
         model: Model<any>;
-        thinkingLevel: ThinkingLevel;
+        thinkingLevel?: ThinkingLevel;
     }>): void;
     /** File-based prompt templates */
     get promptTemplates(): ReadonlyArray<PromptTemplate>;
+    private _normalizePromptSnippet;
+    private _normalizePromptGuidelines;
     private _rebuildSystemPrompt;
     /**
      * Send a prompt to the agent.
@@ -276,8 +312,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
@@ -343,23 +380,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>;
     /**
@@ -369,7 +394,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;
     /**
@@ -396,6 +420,7 @@ export declare class AgentSession {
      * Check if current model supports thinking/reasoning.
      */
     supportsThinking(): boolean;
+    private _getThinkingLevelForModelSwitch;
     private _clampThinkingLevel;
     /**
      * Set steering message mode.
@@ -434,7 +459,9 @@ export declare class AgentSession {
     private buildExtensionResourcePaths;
     private getExtensionSourceLabel;
     private _applyExtensionBindings;
+    private _refreshCurrentModelFromRegistry;
     private _bindExtensionCore;
+    private _refreshToolRegistry;
     private _buildRuntime;
     reload(): Promise<void>;
     /**
@@ -488,30 +515,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.
@@ -553,6 +560,13 @@ 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.