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

package/dist/core/extensions/types.d.ts

@@ -7,10 +7,10 @@
  * - Register commands, keyboard shortcuts, and CLI flags
  * - Interact with the user via UI primitives
  */
-import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel } from "phi-code-agent";
+import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode } from "phi-code-agent";
 import type { Api, AssistantMessageEvent, AssistantMessageEventStream, Context, ImageContent, Model, OAuthCredentials, OAuthLoginCallbacks, SimpleStreamOptions, TextContent, ToolResultMessage } from "phi-code-ai";
-import type { AutocompleteItem, Component, EditorComponent, EditorTheme, KeyId, OverlayHandle, OverlayOptions, TUI } from "phi-code-tui";
-import type { Static, TSchema } from "@sinclair/typebox";
+import type { AutocompleteItem, AutocompleteProvider, Component, EditorComponent, EditorTheme, KeyId, OverlayHandle, OverlayOptions, TUI } from "phi-code-tui";
+import type { Static, TSchema } from "typebox";
 import type { Theme } from "../../modes/interactive/theme/theme.js";
 import type { BashResult } from "../bash-executor.js";
 import type { CompactionPreparation, CompactionResult } from "../compaction/index.js";
@@ -22,12 +22,15 @@ import type { CustomMessage } from "../messages.js";
 import type { ModelRegistry } from "../model-registry.js";
 import type { BranchSummaryEntry, CompactionEntry, ReadonlySessionManager, SessionEntry, SessionManager } from "../session-manager.js";
 import type { SlashCommandInfo } from "../slash-commands.js";
+import type { SourceInfo } from "../source-info.js";
+import type { BuildSystemPromptOptions } from "../system-prompt.js";
 import type { BashOperations } from "../tools/bash.js";
 import type { EditToolDetails } from "../tools/edit.js";
 import type { BashToolDetails, BashToolInput, EditToolInput, FindToolDetails, FindToolInput, GrepToolDetails, GrepToolInput, LsToolDetails, LsToolInput, ReadToolDetails, ReadToolInput, WriteToolInput } from "../tools/index.js";
 export type { ExecOptions, ExecResult } from "../exec.js";
-export type { AgentToolResult, AgentToolUpdateCallback };
-export type { AppAction, KeybindingsManager } from "../keybindings.js";
+export type { BuildSystemPromptOptions } from "../system-prompt.js";
+export type { AgentToolResult, AgentToolUpdateCallback, ToolExecutionMode };
+export type { AppKeybinding, KeybindingsManager } from "../keybindings.js";
 /** Options for extension UI dialogs. */
 export interface ExtensionUIDialogOptions {
     /** AbortSignal to programmatically dismiss the dialog. */
@@ -47,6 +50,16 @@ export type TerminalInputHandler = (data: string) => {
     consume?: boolean;
     data?: string;
 } | undefined;
+/** Working indicator configuration for the interactive streaming loader. */
+export interface WorkingIndicatorOptions {
+    /** Animation frames. Use an empty array to hide the indicator entirely. Custom frames are rendered verbatim. */
+    frames?: string[];
+    /** Frame interval in milliseconds for animated indicators. */
+    intervalMs?: number;
+}
+/** Wrap the current autocomplete provider with additional behavior. */
+export type AutocompleteProviderFactory = (current: AutocompleteProvider) => AutocompleteProvider;
+export type EditorFactory = (tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) => EditorComponent;
 /**
  * UI context for extensions to request interactive UI.
  * Each mode (interactive, RPC, print) provides its own implementation.
@@ -66,6 +79,19 @@ export interface ExtensionUIContext {
     setStatus(key: string, text: string | undefined): void;
     /** Set the working/loading message shown during streaming. Call with no argument to restore default. */
     setWorkingMessage(message?: string): void;
+    /** Show or hide the built-in interactive working loader row during streaming. */
+    setWorkingVisible(visible: boolean): void;
+    /**
+     * Configure the interactive working indicator shown during streaming.
+     *
+     * - Omit the argument to restore the default animated spinner.
+     * - Use `frames: ["●"]` for a static indicator.
+     * - Use `frames: []` to hide the indicator entirely.
+     * - Custom frames are rendered as provided, so extensions must add their own colors.
+     */
+    setWorkingIndicator(options?: WorkingIndicatorOptions): void;
+    /** Set the label shown for hidden thinking blocks. Call with no argument to restore default. */
+    setHiddenThinkingLabel(label?: string): void;
     /** Set a widget to display above or below the editor. Accepts string array or component factory. */
     setWidget(key: string, content: string[] | undefined, options?: ExtensionWidgetOptions): void;
     setWidget(key: string, content: ((tui: TUI, theme: Theme) => Component & {
@@ -106,6 +132,8 @@ export interface ExtensionUIContext {
     getEditorText(): string;
     /** Show a multi-line editor for text editing. */
     editor(title: string, prefill?: string): Promise<string | undefined>;
+    /** Stack additional autocomplete behavior on top of the built-in provider. */
+    addAutocompleteProvider(factory: AutocompleteProviderFactory): void;
     /**
      * Set a custom editor component via factory function.
      * Pass undefined to restore the default editor.
@@ -115,12 +143,12 @@ export interface ExtensionUIContext {
      * - `keybindings`: KeybindingsManager for app-level keybindings
      *
      * For full app keybinding support (escape, ctrl+d, model switching, etc.),
-     * extend `CustomEditor` from `phi-code` and call
+     * extend `CustomEditor` from `@phi-code-admin/phi-code` and call
      * `super.handleInput(data)` for keys you don't handle.
      *
      * @example
      * ```ts
-     * import { CustomEditor } from "phi-code";
+     * import { CustomEditor } from "@phi-code-admin/phi-code";
      *
      * class VimEditor extends CustomEditor {
      *   private mode: "normal" | "insert" = "insert";
@@ -139,7 +167,9 @@ export interface ExtensionUIContext {
      * );
      * ```
      */
-    setEditorComponent(factory: ((tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) => EditorComponent) | undefined): void;
+    setEditorComponent(factory: EditorFactory | undefined): void;
+    /** Get the currently configured custom editor factory, or undefined when using the default editor. */
+    getEditorComponent(): EditorFactory | undefined;
     /** Get the current theme for styling. */
     readonly theme: Theme;
     /** Get all available themes with their names and file paths. */
@@ -189,6 +219,8 @@ export interface ExtensionContext {
     model: Model<any> | undefined;
     /** Whether the agent is idle (not streaming) */
     isIdle(): boolean;
+    /** The current abort signal, or undefined when the agent is not streaming. */
+    signal: AbortSignal | undefined;
     /** Abort the current agent operation */
     abort(): void;
     /** Whether there are queued messages waiting */
@@ -213,11 +245,15 @@ export interface ExtensionCommandContext extends ExtensionContext {
     newSession(options?: {
         parentSession?: string;
         setup?: (sessionManager: SessionManager) => Promise<void>;
+        withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
     }): Promise<{
         cancelled: boolean;
     }>;
     /** Fork from a specific entry, creating a new session file. */
-    fork(entryId: string): Promise<{
+    fork(entryId: string, options?: {
+        position?: "before" | "at";
+        withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
+    }): Promise<{
         cancelled: boolean;
     }>;
     /** Navigate to a different point in the session tree. */
@@ -230,12 +266,28 @@ export interface ExtensionCommandContext extends ExtensionContext {
         cancelled: boolean;
     }>;
     /** Switch to a different session file. */
-    switchSession(sessionPath: string): Promise<{
+    switchSession(sessionPath: string, options?: {
+        withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
+    }): Promise<{
         cancelled: boolean;
     }>;
     /** Reload extensions, skills, prompts, and themes. */
     reload(): Promise<void>;
 }
+/**
+ * Fresh command-capable context bound to the replacement session after a session switch.
+ *
+ * This is passed to `withSession()` callbacks on `newSession()`, `fork()`, and `switchSession()`.
+ */
+export interface ReplacedSessionContext extends ExtensionCommandContext {
+    sendMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">, options?: {
+        triggerTurn?: boolean;
+        deliverAs?: "steer" | "followUp" | "nextTurn";
+    }): Promise<void>;
+    sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
+        deliverAs?: "steer" | "followUp";
+    }): Promise<void>;
+}
 /** Rendering options for tool results */
 export interface ToolRenderResultOptions {
     /** Whether the result view is expanded */
@@ -243,29 +295,77 @@ export interface ToolRenderResultOptions {
     /** Whether this is a partial/streaming result */
     isPartial: boolean;
 }
+/** Context passed to tool renderers. */
+export interface ToolRenderContext<TState = any, TArgs = any> {
+    /** Current tool call arguments. Shared across call/result renders for the same tool call. */
+    args: TArgs;
+    /** Unique id for this tool execution. Stable across call/result renders for the same tool call. */
+    toolCallId: string;
+    /** Invalidate just this tool execution component for redraw. */
+    invalidate: () => void;
+    /** Previously returned component for this render slot, if any. */
+    lastComponent: Component | undefined;
+    /** Shared renderer state for this tool row. Initialized by tool-execution.ts. */
+    state: TState;
+    /** Working directory for this tool execution. */
+    cwd: string;
+    /** Whether the tool execution has started. */
+    executionStarted: boolean;
+    /** Whether the tool call arguments are complete. */
+    argsComplete: boolean;
+    /** Whether the tool result is partial/streaming. */
+    isPartial: boolean;
+    /** Whether the result view is expanded. */
+    expanded: boolean;
+    /** Whether inline images are currently shown in the TUI. */
+    showImages: boolean;
+    /** Whether the current result is an error. */
+    isError: boolean;
+}
 /**
  * Tool definition for registerTool().
  */
-export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = unknown> {
+export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = unknown, TState = any> {
     /** Tool name (used in LLM tool calls) */
     name: string;
     /** Human-readable label for UI */
     label: string;
     /** Description for LLM */
     description: string;
-    /** Optional one-line snippet for the Available tools section in the default system prompt. Falls back to description when omitted. */
+    /** Optional one-line snippet for the Available tools section in the default system prompt. Custom tools are omitted from that section when this is not provided. */
     promptSnippet?: string;
     /** Optional guideline bullets appended to the default system prompt Guidelines section when this tool is active. */
     promptGuidelines?: string[];
     /** Parameter schema (TypeBox) */
     parameters: TParams;
+    /** Controls whether ToolExecutionComponent renders the standard colored shell or the tool renders its own framing. */
+    renderShell?: "default" | "self";
+    /** Optional compatibility shim to prepare raw tool call arguments before schema validation. Must return an object conforming to TParams. */
+    prepareArguments?: (args: unknown) => Static<TParams>;
+    /**
+     * Per-tool execution mode override.
+     * - "sequential": this tool must execute one at a time with other tool calls.
+     * - "parallel": this tool can execute concurrently with other tool calls.
+     *
+     * If omitted, the default execution mode applies.
+     */
+    executionMode?: ToolExecutionMode;
     /** Execute the tool. */
     execute(toolCallId: string, params: Static<TParams>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<TDetails> | undefined, ctx: ExtensionContext): Promise<AgentToolResult<TDetails>>;
     /** Custom rendering for tool call display */
-    renderCall?: (args: Static<TParams>, theme: Theme) => Component | undefined;
+    renderCall?: (args: Static<TParams>, theme: Theme, context: ToolRenderContext<TState, Static<TParams>>) => Component;
     /** Custom rendering for tool result display */
-    renderResult?: (result: AgentToolResult<TDetails>, options: ToolRenderResultOptions, theme: Theme) => Component | undefined;
+    renderResult?: (result: AgentToolResult<TDetails>, options: ToolRenderResultOptions, theme: Theme, context: ToolRenderContext<TState, Static<TParams>>) => Component;
 }
+type AnyToolDefinition = ToolDefinition<any, any, any>;
+/**
+ * Preserve parameter inference for standalone tool definitions.
+ *
+ * Use this when assigning a tool to a variable or passing it through arrays such
+ * as `customTools`, where contextual typing would otherwise widen params to
+ * `unknown`.
+ */
+export declare function defineTool<TParams extends TSchema, TDetails = unknown, TState = any>(tool: ToolDefinition<TParams, TDetails, TState>): ToolDefinition<TParams, TDetails, TState> & AnyToolDefinition;
 /** Fired after session_start to allow extensions to provide additional resource paths. */
 export interface ResourcesDiscoverEvent {
     type: "resources_discover";
@@ -278,9 +378,13 @@ export interface ResourcesDiscoverResult {
     promptPaths?: string[];
     themePaths?: string[];
 }
-/** Fired on initial session load */
+/** Fired when a session is started, loaded, or reloaded */
 export interface SessionStartEvent {
     type: "session_start";
+    /** Why this session start happened. */
+    reason: "startup" | "reload" | "new" | "resume" | "fork";
+    /** Previously active session file. Present for "new", "resume", and "fork". */
+    previousSessionFile?: string;
 }
 /** Fired before switching to another session (can be cancelled) */
 export interface SessionBeforeSwitchEvent {
@@ -288,21 +392,11 @@ export interface SessionBeforeSwitchEvent {
     reason: "new" | "resume";
     targetSessionFile?: string;
 }
-/** Fired after switching to another session */
-export interface SessionSwitchEvent {
-    type: "session_switch";
-    reason: "new" | "resume";
-    previousSessionFile: string | undefined;
-}
 /** Fired before forking a session (can be cancelled) */
 export interface SessionBeforeForkEvent {
     type: "session_before_fork";
     entryId: string;
-}
-/** Fired after forking a session */
-export interface SessionForkEvent {
-    type: "session_fork";
-    previousSessionFile: string | undefined;
+    position: "before" | "at";
 }
 /** Fired before context compaction (can be cancelled or customized) */
 export interface SessionBeforeCompactEvent {
@@ -318,9 +412,12 @@ export interface SessionCompactEvent {
     compactionEntry: CompactionEntry;
     fromExtension: boolean;
 }
-/** Fired on process exit */
+/** Fired before an extension runtime is torn down due to quit, reload, or session replacement. */
 export interface SessionShutdownEvent {
     type: "session_shutdown";
+    reason: "quit" | "reload" | "new" | "resume" | "fork";
+    /** Destination session file when shutting down due to session replacement. */
+    targetSessionFile?: string;
 }
 /** Preparation data for tree navigation */
 export interface TreePreparation {
@@ -350,18 +447,34 @@ export interface SessionTreeEvent {
     summaryEntry?: BranchSummaryEntry;
     fromExtension?: boolean;
 }
-export type SessionEvent = SessionStartEvent | SessionBeforeSwitchEvent | SessionSwitchEvent | SessionBeforeForkEvent | SessionForkEvent | SessionBeforeCompactEvent | SessionCompactEvent | SessionShutdownEvent | SessionBeforeTreeEvent | SessionTreeEvent;
+export type SessionEvent = SessionStartEvent | SessionBeforeSwitchEvent | SessionBeforeForkEvent | SessionBeforeCompactEvent | SessionCompactEvent | SessionShutdownEvent | SessionBeforeTreeEvent | SessionTreeEvent;
 /** Fired before each LLM call. Can modify messages. */
 export interface ContextEvent {
     type: "context";
     messages: AgentMessage[];
 }
+/** Fired before a provider request is sent. Can replace the payload. */
+export interface BeforeProviderRequestEvent {
+    type: "before_provider_request";
+    payload: unknown;
+}
+/** Fired after a provider response is received and before the response stream is consumed. */
+export interface AfterProviderResponseEvent {
+    type: "after_provider_response";
+    status: number;
+    headers: Record<string, string>;
+}
 /** Fired after user submits prompt but before agent loop. */
 export interface BeforeAgentStartEvent {
     type: "before_agent_start";
+    /** The raw user prompt text (after expansion). */
     prompt: string;
+    /** Images attached to the user prompt, if any. */
     images?: ImageContent[];
+    /** The fully assembled system prompt string. */
     systemPrompt: string;
+    /** Structured options used to build the system prompt. Extensions can inspect this to understand what Pi loaded without re-discovering resources. */
+    systemPromptOptions: BuildSystemPromptOptions;
 }
 /** Fired when an agent loop starts */
 export interface AgentStartEvent {
@@ -432,6 +545,12 @@ export interface ModelSelectEvent {
     previousModel: Model<any> | undefined;
     source: ModelSelectSource;
 }
+/** Fired when a new thinking level is selected */
+export interface ThinkingLevelSelectEvent {
+    type: "thinking_level_select";
+    level: ThinkingLevel;
+    previousLevel: ThinkingLevel;
+}
 /** Fired when user executes a bash command via ! or !! prefix */
 export interface UserBashEvent {
     type: "user_bash";
@@ -500,7 +619,12 @@ export interface CustomToolCallEvent extends ToolCallEventBase {
     toolName: string;
     input: Record<string, unknown>;
 }
-/** Fired before a tool executes. Can block. */
+/**
+ * Fired before a tool executes. Can block.
+ *
+ * `event.input` is mutable. Mutate it in place to patch tool arguments before execution.
+ * Later `tool_call` handlers see earlier mutations. No re-validation is performed after mutation.
+ */
 export type ToolCallEvent = BashToolCallEvent | ReadToolCallEvent | EditToolCallEvent | WriteToolCallEvent | GrepToolCallEvent | FindToolCallEvent | LsToolCallEvent | CustomToolCallEvent;
 interface ToolResultEventBase {
     type: "tool_result";
@@ -582,11 +706,13 @@ export declare function isToolCallEventType<TName extends string, TInput extends
     input: TInput;
 };
 /** Union of all event types */
-export type ExtensionEvent = ResourcesDiscoverEvent | SessionEvent | ContextEvent | BeforeAgentStartEvent | AgentStartEvent | AgentEndEvent | TurnStartEvent | TurnEndEvent | MessageStartEvent | MessageUpdateEvent | MessageEndEvent | ToolExecutionStartEvent | ToolExecutionUpdateEvent | ToolExecutionEndEvent | ModelSelectEvent | UserBashEvent | InputEvent | ToolCallEvent | ToolResultEvent;
+export type ExtensionEvent = ResourcesDiscoverEvent | SessionEvent | ContextEvent | BeforeProviderRequestEvent | AfterProviderResponseEvent | BeforeAgentStartEvent | AgentStartEvent | AgentEndEvent | TurnStartEvent | TurnEndEvent | MessageStartEvent | MessageUpdateEvent | MessageEndEvent | ToolExecutionStartEvent | ToolExecutionUpdateEvent | ToolExecutionEndEvent | ModelSelectEvent | ThinkingLevelSelectEvent | UserBashEvent | InputEvent | ToolCallEvent | ToolResultEvent;
 export interface ContextEventResult {
     messages?: AgentMessage[];
 }
+export type BeforeProviderRequestEventResult = unknown;
 export interface ToolCallEventResult {
+    /** Block tool execution. To modify arguments, mutate `event.input` in place instead. */
     block?: boolean;
     reason?: string;
 }
@@ -602,6 +728,10 @@ export interface ToolResultEventResult {
     details?: unknown;
     isError?: boolean;
 }
+export interface MessageEndEventResult {
+    /** Replace the finalized message. The replacement must keep the original message role. */
+    message?: AgentMessage;
+}
 export interface BeforeAgentStartEventResult {
     message?: Pick<CustomMessage, "customType" | "content" | "display" | "details">;
     /** Replace the system prompt for this turn. If multiple extensions return this, they are chained. */
@@ -637,10 +767,14 @@ export interface MessageRenderOptions {
 export type MessageRenderer<T = unknown> = (message: CustomMessage<T>, options: MessageRenderOptions, theme: Theme) => Component | undefined;
 export interface RegisteredCommand {
     name: string;
+    sourceInfo: SourceInfo;
     description?: string;
-    getArgumentCompletions?: (argumentPrefix: string) => AutocompleteItem[] | null;
+    getArgumentCompletions?: (argumentPrefix: string) => AutocompleteItem[] | null | Promise<AutocompleteItem[] | null>;
     handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>;
 }
+export interface ResolvedCommand extends RegisteredCommand {
+    invocationName: string;
+}
 /** Handler function type for events */
 export type ExtensionHandler<E, R = undefined> = (event: E, ctx: ExtensionContext) => Promise<R | void> | R | void;
 /**
@@ -650,15 +784,15 @@ export interface ExtensionAPI {
     on(event: "resources_discover", handler: ExtensionHandler<ResourcesDiscoverEvent, ResourcesDiscoverResult>): void;
     on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
     on(event: "session_before_switch", handler: ExtensionHandler<SessionBeforeSwitchEvent, SessionBeforeSwitchResult>): void;
-    on(event: "session_switch", handler: ExtensionHandler<SessionSwitchEvent>): void;
     on(event: "session_before_fork", handler: ExtensionHandler<SessionBeforeForkEvent, SessionBeforeForkResult>): void;
-    on(event: "session_fork", handler: ExtensionHandler<SessionForkEvent>): void;
     on(event: "session_before_compact", handler: ExtensionHandler<SessionBeforeCompactEvent, SessionBeforeCompactResult>): void;
     on(event: "session_compact", handler: ExtensionHandler<SessionCompactEvent>): void;
     on(event: "session_shutdown", handler: ExtensionHandler<SessionShutdownEvent>): void;
     on(event: "session_before_tree", handler: ExtensionHandler<SessionBeforeTreeEvent, SessionBeforeTreeResult>): void;
     on(event: "session_tree", handler: ExtensionHandler<SessionTreeEvent>): void;
     on(event: "context", handler: ExtensionHandler<ContextEvent, ContextEventResult>): void;
+    on(event: "before_provider_request", handler: ExtensionHandler<BeforeProviderRequestEvent, BeforeProviderRequestEventResult>): void;
+    on(event: "after_provider_response", handler: ExtensionHandler<AfterProviderResponseEvent>): void;
     on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult>): void;
     on(event: "agent_start", handler: ExtensionHandler<AgentStartEvent>): void;
     on(event: "agent_end", handler: ExtensionHandler<AgentEndEvent>): void;
@@ -666,19 +800,20 @@ export interface ExtensionAPI {
     on(event: "turn_end", handler: ExtensionHandler<TurnEndEvent>): void;
     on(event: "message_start", handler: ExtensionHandler<MessageStartEvent>): void;
     on(event: "message_update", handler: ExtensionHandler<MessageUpdateEvent>): void;
-    on(event: "message_end", handler: ExtensionHandler<MessageEndEvent>): void;
+    on(event: "message_end", handler: ExtensionHandler<MessageEndEvent, MessageEndEventResult>): void;
     on(event: "tool_execution_start", handler: ExtensionHandler<ToolExecutionStartEvent>): void;
     on(event: "tool_execution_update", handler: ExtensionHandler<ToolExecutionUpdateEvent>): void;
     on(event: "tool_execution_end", handler: ExtensionHandler<ToolExecutionEndEvent>): void;
     on(event: "model_select", handler: ExtensionHandler<ModelSelectEvent>): void;
+    on(event: "thinking_level_select", handler: ExtensionHandler<ThinkingLevelSelectEvent>): void;
     on(event: "tool_call", handler: ExtensionHandler<ToolCallEvent, ToolCallEventResult>): void;
     on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): void;
     on(event: "user_bash", handler: ExtensionHandler<UserBashEvent, UserBashEventResult>): void;
     on(event: "input", handler: ExtensionHandler<InputEvent, InputEventResult>): void;
     /** Register a tool that the LLM can call. */
-    registerTool<TParams extends TSchema = TSchema, TDetails = unknown>(tool: ToolDefinition<TParams, TDetails>): void;
+    registerTool<TParams extends TSchema = TSchema, TDetails = unknown, TState = any>(tool: ToolDefinition<TParams, TDetails, TState>): void;
     /** Register a custom command. */
-    registerCommand(name: string, options: Omit<RegisteredCommand, "name">): void;
+    registerCommand(name: string, options: Omit<RegisteredCommand, "name" | "sourceInfo">): void;
     /** Register a keyboard shortcut. */
     registerShortcut(shortcut: KeyId, options: {
         description?: string;
@@ -718,7 +853,7 @@ export interface ExtensionAPI {
     exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
     /** Get the list of currently active tool names. */
     getActiveTools(): string[];
-    /** Get all configured tools with name and description. */
+    /** Get all configured tools with parameter schema and source metadata. */
     getAllTools(): ToolInfo[];
     /** Set the active tools by name. */
     setActiveTools(toolNames: string[]): void;
@@ -802,6 +937,8 @@ export interface ExtensionAPI {
 }
 /** Configuration for registering a provider via pi.registerProvider(). */
 export interface ProviderConfig {
+    /** Display name for the provider in UI. */
+    name?: string;
     /** Base URL for the API endpoint. Required when defining models. */
     baseUrl?: string;
     /** API key or environment variable name. Required when defining models (unless oauth provided). */
@@ -838,8 +975,12 @@ export interface ProviderModelConfig {
     name: string;
     /** API type override for this model. */
     api?: Api;
+    /** API endpoint URL override for this model. */
+    baseUrl?: string;
     /** Whether the model supports extended thinking. */
     reasoning: boolean;
+    /** Maps pi thinking levels to provider/model-specific values; null marks a level unsupported. */
+    thinkingLevelMap?: Model<Api>["thinkingLevelMap"];
     /** Supported input types. */
     input: ("text" | "image")[];
     /** Cost per token (for tracking, can be 0). */
@@ -862,7 +1003,7 @@ export interface ProviderModelConfig {
 export type ExtensionFactory = (pi: ExtensionAPI) => void | Promise<void>;
 export interface RegisteredTool {
     definition: ToolDefinition;
-    extensionPath: string;
+    sourceInfo: SourceInfo;
 }
 export interface ExtensionFlag {
     name: string;
@@ -889,8 +1030,10 @@ export type AppendEntryHandler = <T = unknown>(customType: string, data?: T) =>
 export type SetSessionNameHandler = (name: string) => void;
 export type GetSessionNameHandler = () => string | undefined;
 export type GetActiveToolsHandler = () => string[];
-/** Tool info with name, description, and parameter schema */
-export type ToolInfo = Pick<ToolDefinition, "name" | "description" | "parameters">;
+/** Tool info with name, description, parameter schema, and source metadata */
+export type ToolInfo = Pick<ToolDefinition, "name" | "description" | "parameters"> & {
+    sourceInfo: SourceInfo;
+};
 export type GetAllToolsHandler = () => ToolInfo[];
 export type GetCommandsHandler = () => SlashCommandInfo[];
 export type SetActiveToolsHandler = (toolNames: string[]) => void;
@@ -909,15 +1052,20 @@ export interface ExtensionRuntimeState {
     pendingProviderRegistrations: Array<{
         name: string;
         config: ProviderConfig;
+        extensionPath: string;
     }>;
+    /** Throws when this extension instance is stale after runtime replacement. */
+    assertActive: () => void;
+    /** Marks this extension instance as stale after runtime replacement or reload. */
+    invalidate: (message?: string) => void;
     /**
      * Register or unregister a provider.
      *
      * Before bindCore(): queues registrations / removes from queue.
      * After bindCore(): calls ModelRegistry directly for immediate effect.
      */
-    registerProvider: (name: string, config: ProviderConfig) => void;
-    unregisterProvider: (name: string) => void;
+    registerProvider: (name: string, config: ProviderConfig, extensionPath?: string) => void;
+    unregisterProvider: (name: string, extensionPath?: string) => void;
 }
 /**
  * Action implementations for pi.* API methods.
@@ -946,6 +1094,7 @@ export interface ExtensionActions {
 export interface ExtensionContextActions {
     getModel: () => Model<any> | undefined;
     isIdle: () => boolean;
+    getSignal: () => AbortSignal | undefined;
     abort: () => void;
     hasPendingMessages: () => boolean;
     shutdown: () => void;
@@ -962,10 +1111,14 @@ export interface ExtensionCommandContextActions {
     newSession: (options?: {
         parentSession?: string;
         setup?: (sessionManager: SessionManager) => Promise<void>;
+        withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
     }) => Promise<{
         cancelled: boolean;
     }>;
-    fork: (entryId: string) => Promise<{
+    fork: (entryId: string, options?: {
+        position?: "before" | "at";
+        withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
+    }) => Promise<{
         cancelled: boolean;
     }>;
     navigateTree: (targetId: string, options?: {
@@ -976,7 +1129,9 @@ export interface ExtensionCommandContextActions {
     }) => Promise<{
         cancelled: boolean;
     }>;
-    switchSession: (sessionPath: string) => Promise<{
+    switchSession: (sessionPath: string, options?: {
+        withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
+    }) => Promise<{
         cancelled: boolean;
     }>;
     reload: () => Promise<void>;
@@ -991,6 +1146,7 @@ export interface ExtensionRuntime extends ExtensionRuntimeState, ExtensionAction
 export interface Extension {
     path: string;
     resolvedPath: string;
+    sourceInfo: SourceInfo;
     handlers: Map<string, HandlerFn[]>;
     tools: Map<string, RegisteredTool>;
     messageRenderers: Map<string, MessageRenderer>;