@astralyn/pi 0.87.6 → 1.0.0

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

@@ -7,8 +7,8 @@
  * - Register commands, keyboard shortcuts, and CLI flags
  * - Interact with the user via UI primitives
  */
-import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode } from "@earendil-works/pi-agent-core";
-import type { Api, AssistantMessageEvent, AssistantMessageEventStream, ConstrainedSamplingConfig, ImageContent, Message, Model, OAuthCredentials, OAuthLoginCallbacks, Provider, ProviderHeaders, RefreshModelsContext, SimpleStreamOptions, TextContent, ToolResultMessage, TranscriptContext, Usage } from "@earendil-works/pi-ai";
+import type { AgentMessage, AgentTool, AgentToolCallOutcome, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode } from "@earendil-works/pi-agent-core";
+import type { AnyModel, Api, AssistantMessageEvent, AssistantMessageEventStream, ClassifierApi, ConstrainedSamplingConfig, ImageApi, ImageContent, JsonValue, Message, Model, OAuthCredentials, OAuthLoginCallbacks, Provider, ProviderClassifier, ProviderHeaders, ProviderId, ProviderImages, RefreshModelsContext, SimpleStreamOptions, TextContent, ToolResultMessage, TranscriptContext, Usage } from "@earendil-works/pi-ai";
 import type { AutocompleteItem, AutocompleteProvider, Component, EditorComponent, EditorTheme, KeyId, OverlayHandle, OverlayOptions, TUI } from "@earendil-works/pi-tui";
 import type { Static, TSchema } from "typebox";
 import type { Theme } from "../../modes/interactive/theme/theme.ts";
@@ -19,17 +19,20 @@ import type { EventBus } from "../event-bus.ts";
 import type { ExecOptions, ExecResult } from "../exec.ts";
 import type { ReadonlyFooterDataProvider } from "../footer-data-provider.ts";
 import type { KeybindingsManager } from "../keybindings.ts";
+import type { McpServerConfig, McpServerRegistry, RegisteredMcpServer } from "../mcp-servers.ts";
 import type { CustomMessage } from "../messages.ts";
 import type { ModelRegistry } from "../model-registry.ts";
 import type { ScopedModel } from "../model-resolver.ts";
 import type { BranchSummaryEntry, CompactionEntry, ContextEditEntry, CustomEntry, ProjectedSessionEntry, ReadonlySessionManager, SessionEntry, SessionManager } from "../session-manager.ts";
+import type { Settings } from "../settings-manager.ts";
 import type { SlashCommandInfo } from "../slash-commands.ts";
 import type { SourceInfo } from "../source-info.ts";
 import type { BuildSystemPromptOptions, NormalizedBuildSystemPromptOptions } from "../system-prompt.ts";
 import type { BashOperations } from "../tools/bash.ts";
 import type { EditToolDetails } from "../tools/edit.ts";
 import type { BashToolDetails, BashToolInput, EditToolInput, FindToolDetails, FindToolInput, GrepToolDetails, GrepToolInput, LsToolDetails, LsToolInput, PowerShellToolDetails, PowerShellToolInput, ReadToolDetails, ReadToolInput, WriteToolInput } from "../tools/index.ts";
-import type { BackgroundContext, ContextSnapshot, EditorHost, ModelRuntime } from "./distribution-api.ts";
+import type { ModelRoute, ModelRouteRequest, VirtualModelDefinition } from "../virtual-models.ts";
+import type { ContextSnapshot, EditorHost, ModelRuntime, TasksContext } from "./distribution-api.ts";
 export type { ExecOptions, ExecResult } from "../exec.ts";
 export type { BuildSystemPromptOptions, NormalizedBuildSystemPromptOptions } from "../system-prompt.ts";
 export type { ContextSnapshot, EditorHost, EditorSubmitEvent, EditorSubmitHandler } from "./distribution-api.ts";
@@ -213,6 +216,10 @@ export interface CompactOptions {
  */
 export type ExtensionMode = "tui" | "rpc" | "json" | "print";
 export interface ExtensionContext {
+    /** Read detached global JSON settings for an extension namespace. */
+    getExtensionSettings(namespace: string): Record<string, unknown>;
+    /** Replace one global namespace; rejects on invalid data or failed persistence. */
+    setExtensionSettings(namespace: string, value: Record<string, unknown>): Promise<void>;
     /** UI methods for user interaction */
     ui: ExtensionUIContext;
     /** Current run mode. Use "tui" to guard terminal-only UI such as custom components. */
@@ -228,7 +235,7 @@ export interface ExtensionContext {
     /** Canonical model and authentication runtime shared by the current session. */
     readonly modelRuntime: ModelRuntime;
     /** Session-owned execution capability; disabled unless the host explicitly enables it. */
-    readonly background: BackgroundContext;
+    readonly tasks: TasksContext;
     /** Capture detached, stable model input and request settings without writing to the session. */
     getContextSnapshot(): Promise<ContextSnapshot>;
     /** Current model (may be undefined) */
@@ -259,6 +266,34 @@ export interface ExtensionContext {
     /** Get the current effective system prompt. */
     getSystemPrompt(): string;
 }
+/** Options for {@link ExtensionToolContext.executeTool}. */
+export interface ExecuteToolOptions {
+    /** Defaults to the calling tool's signal. */
+    signal?: AbortSignal;
+    /** Receives partial results of the nested tool, in addition to `tool_execution_update` events. */
+    onUpdate?: AgentToolUpdateCallback;
+}
+/**
+ * Context passed to tool `execute()` in a session: the extension context plus `executeTool()`
+ * for running other tools through the same validation, hooks, and permission checks as
+ * model-issued calls.
+ *
+ * A tool wrapped with `wrapToolDefinition()` without a context factory, such as a built-in tool
+ * created with `createBashTool()` and run in a plain `Agent` or called directly, gets no context.
+ */
+export interface ExtensionToolContext extends ExtensionContext {
+    /** Tools {@link executeTool} can call. */
+    readonly tools: readonly AgentTool[];
+    /**
+     * Run another tool. The call gets the id `<calling id>/<n>`, and the `tool_call`, `tool_result`,
+     * and `tool_execution_*` events carry `parentToolCallId`. It does not appear in the transcript;
+     * a bounded record of it is kept as `nestedCalls` on the calling tool's result message.
+     *
+     * Never rejects for tool failures: unknown tools, validation errors, blocked calls, and thrown
+     * errors come back as `isError: true`.
+     */
+    executeTool(name: string, args: unknown, options?: ExecuteToolOptions): Promise<AgentToolCallOutcome>;
+}
 /**
  * Extended context for command handlers.
  * Includes session control methods only safe in user-initiated commands.
@@ -355,6 +390,69 @@ export interface ToolRenderContext<TState = any, TArgs = any, TDetails = unknown
     /** Whether the current result is an error. */
     isError: boolean;
 }
+/**
+ * How the model reaches a tool. "Callable" means callable from other tools through
+ * `ctx.executeTool()`, as the `codemode` tool does.
+ *
+ * - `direct`: declared to the model while active, and callable while active.
+ * - `model-only`: declared to the model while active, never callable. Use it for orchestrating or
+ *   interactive tools.
+ * - `codemode`: callable whenever registered. Not declared to the model unless explicitly
+ *   activated. Codemode tools list it in their description.
+ * - `deferred`: like `codemode`, but codemode tools do not list it; tool search can find it.
+ * - `hidden`: registered but unreachable. Activating it has no effect.
+ *
+ * `direct` and `model-only` tools are activated when they are registered; the others are not.
+ * The active tool set (`getActiveTools`/`setActiveTools`) is the set declared to the model.
+ */
+export type ToolExposure = "direct" | "model-only" | "codemode" | "deferred" | "hidden";
+/**
+ * Hints about what a tool does, with the meaning of MCP tool annotations. They come from the tool's
+ * author and are not verified; permission extensions can use them to decide which calls to confirm.
+ */
+export interface ToolAnnotations {
+    /** The tool does not modify its environment. */
+    readOnlyHint?: boolean;
+    /** The tool may delete or overwrite data, rather than only add to it. Meaningful when not read-only. */
+    destructiveHint?: boolean;
+    /** Repeating a call with the same arguments has no further effect. Meaningful when not read-only. */
+    idempotentHint?: boolean;
+    /** The tool reaches an open world of external entities, such as the web, rather than a closed domain. */
+    openWorldHint?: boolean;
+}
+/** A group of related tools, such as the tools of one MCP server. Codemode tools list them together. */
+export interface ToolNamespace {
+    /** For example `mcp__docs`. */
+    name: string;
+    /** Short summary shown once with the group in model-facing tool listings. */
+    description?: string;
+    /**
+     * Longer usage guidance, such as MCP server instructions. Not part of tool listings; tools that
+     * describe the namespace on request (codemode's `describeNamespace()`) return it.
+     */
+    instructions?: string;
+}
+/** The tools of a session as {@link ToolDefinition.prepareLoadout} sees them. */
+export interface ToolLoadout {
+    /** Tools declared to the model (the active tools), in order, with their original descriptions. */
+    readonly declared: readonly AgentTool[];
+    /** Tools callable through `ctx.executeTool()`. */
+    readonly callable: readonly AgentTool[];
+    /** Every registered tool. */
+    readonly registered: readonly AgentTool[];
+    getExposure(name: string): ToolExposure;
+    getNamespace(name: string): ToolNamespace | undefined;
+}
+/** Changes {@link ToolDefinition.prepareLoadout} makes to what the model sees. */
+export interface ToolLoadoutChanges {
+    /** Model-facing descriptions of declared tools, by tool name. */
+    descriptions?: Readonly<Record<string, string>>;
+    /**
+     * Declared tools whose declarations requests leave out. They stay active and callable, and the
+     * transcript still declares them, so the active set survives `/tree` and resume.
+     */
+    hiddenDeclarations?: readonly string[];
+}
 /**
  * Tool definition for registerTool().
  */
@@ -377,6 +475,31 @@ export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = un
     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>;
+    /**
+     * JSON Schema of `structuredContent` in successful results. Tools that declare it should always
+     * set `structuredContent`; codemode scripts then receive it instead of the text content.
+     */
+    outputSchema?: TSchema;
+    /**
+     * How the model reaches the tool. Default: `"direct"`. See {@link ToolExposure}.
+     */
+    exposure?: ToolExposure;
+    /** Group the tool belongs to, for example its MCP server. */
+    namespace?: ToolNamespace;
+    /** Hints about what the tool does, for example from an MCP server. */
+    annotations?: ToolAnnotations;
+    /**
+     * Whether registering the tool activates it. Default: `true` for `direct` and `model-only` tools;
+     * other exposures are never activated on registration. A tool with `defaultActive: false` is
+     * activated by naming it in `--tools` or the `defaultTools` setting, or with `setActiveTools()`.
+     */
+    defaultActive?: boolean;
+    /**
+     * Adjust how the loadout is presented to the model while this tool is active. Called whenever
+     * the active tools change. Tools that orchestrate other tools use it, for example to list the
+     * callable tools in their own description.
+     */
+    prepareLoadout?: (loadout: ToolLoadout) => ToolLoadoutChanges | undefined;
     /**
      * Per-tool execution mode override.
      * - "sequential": this tool must execute one at a time with other tool calls.
@@ -386,7 +509,7 @@ export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = un
      */
     executionMode?: ToolExecutionMode;
     /** Execute the tool. */
-    execute(toolCallId: string, params: Static<TParams>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<TDetails> | undefined, ctx: ExtensionContext): Promise<AgentToolResult<TDetails>>;
+    execute(toolCallId: string, params: Static<TParams>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<TDetails> | undefined, ctx: ExtensionToolContext): Promise<AgentToolResult<TDetails>>;
     /** Custom rendering for tool call display */
     renderCall?: (args: Static<TParams>, theme: Theme, context: ToolRenderContext<TState, Static<TParams>, TDetails>) => Component;
     /** Custom rendering for tool result display */
@@ -429,6 +552,17 @@ export interface ResourcesDiscoverResult {
     promptPaths?: string[];
     themePaths?: string[];
 }
+/**
+ * Fired when an extension registers or unregisters an MCP server after the extensions are bound
+ * (see {@link ExtensionAPI.registerMcpServer}). Servers registered while extensions load are read
+ * with `pi.getMcpServers()` on `session_start`. Handling this event marks an extension as the one
+ * that connects registered servers.
+ */
+export interface McpServersChangeEvent {
+    type: "mcp_servers_change";
+    /** Every registered server after the change. */
+    servers: RegisteredMcpServer[];
+}
 /** Fired when a session is started, loaded, or reloaded */
 export interface SessionStartEvent {
     type: "session_start";
@@ -567,6 +701,14 @@ export interface AfterProviderResponseEvent {
     status: number;
     headers: Record<string, string>;
 }
+/** Fired for a parsed provider stream event before Pi normalizes it. */
+export interface ProviderStreamEvent {
+    type: "provider_stream_event";
+    provider: ProviderId;
+    api: Api;
+    model: string;
+    data: unknown;
+}
 /** Fired after user submits prompt but before agent loop. */
 export interface BeforeAgentStartEvent {
     type: "before_agent_start";
@@ -692,6 +834,8 @@ export interface ToolExecutionStartEvent {
     toolCallId: string;
     toolName: string;
     args: any;
+    /** Set when another tool (for example a codemode script) made this call. */
+    parentToolCallId?: string;
 }
 /** Fired during tool execution with partial/streaming output */
 export interface ToolExecutionUpdateEvent {
@@ -700,6 +844,8 @@ export interface ToolExecutionUpdateEvent {
     toolName: string;
     args: any;
     partialResult: any;
+    /** Set when another tool (for example a codemode script) made this call. */
+    parentToolCallId?: string;
 }
 /** Fired when a tool finishes executing */
 export interface ToolExecutionEndEvent {
@@ -708,6 +854,8 @@ export interface ToolExecutionEndEvent {
     toolName: string;
     result: any;
     isError: boolean;
+    /** Set when another tool (for example a codemode script) made this call. */
+    parentToolCallId?: string;
 }
 export type ModelSelectSource = "set" | "cycle" | "restore";
 /** Fired when a new model is selected */
@@ -759,7 +907,14 @@ export type InputEventResult = {
 };
 interface ToolCallEventBase {
     type: "tool_call";
+    /**
+     * The call's id. For calls another tool made (with `parentToolCallId` set), pi assigns
+     * `<parent id>/<n>`; such ids never appear as tool calls or tool results in the transcript, only
+     * in the parent result's `nestedCalls` record.
+     */
     toolCallId: string;
+    /** Set when another tool (for example a codemode script) issued this call. */
+    parentToolCallId?: string;
 }
 export interface BashToolCallEvent extends ToolCallEventBase {
     toolName: "bash";
@@ -806,9 +961,17 @@ export interface CustomToolCallEvent extends ToolCallEventBase {
 export type ToolCallEvent = BashToolCallEvent | PowerShellToolCallEvent | ReadToolCallEvent | EditToolCallEvent | WriteToolCallEvent | GrepToolCallEvent | FindToolCallEvent | LsToolCallEvent | CustomToolCallEvent;
 interface ToolResultEventBase {
     type: "tool_result";
+    /** The call's id; `<parent id>/<n>` for nested calls, see `ToolCallEvent`. */
     toolCallId: string;
+    /** Set when another tool (for example a codemode script) issued this call. */
+    parentToolCallId?: string;
     input: Record<string, unknown>;
     content: (TextContent | ImageContent)[];
+    /**
+     * Machine-readable result for tools that declare an `outputSchema`. Handlers that redact
+     * `content` should also replace this; replacing `content` alone drops it.
+     */
+    structuredContent?: JsonValue;
     isError: boolean;
     /** Usage from the tool execution itself, if available. */
     usage?: Usage;
@@ -892,7 +1055,7 @@ export declare function isToolCallEventType<TName extends string, TInput extends
     input: TInput;
 };
 /** Union of all event types */
-export type ExtensionEvent = ProjectTrustEvent | ResourcesDiscoverEvent | SessionEvent | ContextEvent | ContextWithSystemEvent | CacheWarmingDecisionEvent | BeforeProviderRequestEvent | BeforeProviderHeadersEvent | AfterProviderResponseEvent | BeforeAgentStartEvent | AgentStartEvent | AgentEndEvent | AgentBeforeSettleEvent | AgentSettledEvent | UIPromptStartEvent | UIPromptEndEvent | TurnStartEvent | TurnEndEvent | MessageStartEvent | MessageUpdateEvent | MessageEndEvent | ToolExecutionStartEvent | ToolExecutionUpdateEvent | ToolExecutionEndEvent | ModelSelectEvent | ThinkingLevelSelectEvent | UserBashEvent | InputEvent | ToolCallEvent | ToolResultEvent;
+export type ExtensionEvent = ProjectTrustEvent | ResourcesDiscoverEvent | McpServersChangeEvent | SessionEvent | ContextEvent | ContextWithSystemEvent | CacheWarmingDecisionEvent | BeforeProviderRequestEvent | BeforeProviderHeadersEvent | AfterProviderResponseEvent | ProviderStreamEvent | BeforeAgentStartEvent | AgentStartEvent | AgentEndEvent | AgentBeforeSettleEvent | AgentSettledEvent | UIPromptStartEvent | UIPromptEndEvent | TurnStartEvent | TurnEndEvent | MessageStartEvent | MessageUpdateEvent | MessageEndEvent | ToolExecutionStartEvent | ToolExecutionUpdateEvent | ToolExecutionEndEvent | ModelSelectEvent | ThinkingLevelSelectEvent | UserBashEvent | InputEvent | ToolCallEvent | ToolResultEvent;
 export interface ContextEventResult {
     messages?: AgentMessage[];
 }
@@ -920,9 +1083,15 @@ export type UserBashEventResult = {
     /** Full replacement: extension handled execution, use this result */
     result: BashResult;
 };
+/**
+ * Changes a `tool_result` handler makes. Omitted fields stay as they are, except that replacing
+ * `content` without returning `structuredContent` drops the structured content, because it may no
+ * longer match. Return it along with `content` to keep it.
+ */
 export interface ToolResultEventResult {
     content?: (TextContent | ImageContent)[];
     details?: unknown;
+    structuredContent?: JsonValue;
     isError?: boolean;
     usage?: Usage;
 }
@@ -1002,6 +1171,7 @@ export interface ExtensionAPI {
     on(event: "session_compact", handler: ExtensionHandler<SessionCompactEvent>): () => void;
     on(event: "session_compact_failed", handler: ExtensionHandler<SessionCompactFailedEvent>): () => void;
     on(event: "session_shutdown", handler: ExtensionHandler<SessionShutdownEvent>): () => void;
+    on(event: "mcp_servers_change", handler: ExtensionHandler<McpServersChangeEvent>): () => 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;
@@ -1010,6 +1180,7 @@ export interface ExtensionAPI {
     on(event: "before_provider_request", handler: ExtensionHandler<BeforeProviderRequestEvent, BeforeProviderRequestEventResult>): () => void;
     on(event: "before_provider_headers", handler: ExtensionHandler<BeforeProviderHeadersEvent>): () => void;
     on(event: "after_provider_response", handler: ExtensionHandler<AfterProviderResponseEvent>): () => void;
+    on(event: "provider_stream_event", handler: ExtensionHandler<ProviderStreamEvent>): () => 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;
@@ -1082,11 +1253,16 @@ export interface ExtensionAPI {
     setLabel(entryId: string, label: string | undefined): void;
     /** Execute a shell command. */
     exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
-    /** Get the list of currently active tool names. */
+    /** Get the names of the active tools, which are the tools declared to the model. */
     getActiveTools(): string[];
-    /** Get all configured tools with parameter schema, prompt guidelines, and source metadata. */
+    /** Get all configured tools with parameter schema, prompt guidelines, exposure, and source metadata. */
     getAllTools(): ToolInfo[];
-    /** Set the active tools by name. */
+    /** Get a copy of the effective settings (global and project settings merged, with overrides). */
+    getSettings(): Settings;
+    /**
+     * Set the active tools by name. Unknown and `hidden` tools are ignored. Tools with `codemode` or
+     * `deferred` exposure stay callable from codemode scripts whether active or not.
+     */
     setActiveTools(toolNames: string[]): void;
     /** Get available slash commands in the current session. */
     getCommands(): SlashCommandInfo[];
@@ -1170,9 +1346,45 @@ export interface ExtensionAPI {
      * pi.unregisterProvider("my-proxy");
      */
     unregisterProvider(name: string): void;
+    /**
+     * Register an MCP server for this session, with the same config as an `mcpServers` entry in
+     * `mcp.json`. The server connects next to the configured servers: on `session_start` when
+     * registered during extension load, right away when registered later. Registering a name again
+     * replaces the extension's earlier registration.
+     *
+     * The registration is not saved; register again on every load. A server of the same name in
+     * `mcp.json` takes precedence. Throws for invalid configs and for names another extension
+     * registered. When no loaded extension handles MCP servers (for example because another MCP
+     * extension replaced the built-in one), the registration is reported as an extension error.
+     *
+     * @example
+     * pi.registerMcpServer("jira", { url: "https://mcp.example.com/jira" });
+     */
+    registerMcpServer(name: string, config: McpServerConfig): void;
+    /** Remove an MCP server this extension registered and close its connection. */
+    unregisterMcpServer(name: string): void;
+    /** Every MCP server registered by extensions. For extensions that connect MCP servers. */
+    getMcpServers(): RegisteredMcpServer[];
+    /**
+     * Register a virtual model: a selectable catalog entry that routes each request to a physical
+     * model. The selection (`ctx.model`, `model_change` entries) names the virtual model; assistant
+     * messages record the physical model and thinking level the router picked.
+     *
+     * `provider` may be any provider id, including one with physical models, and may list several
+     * virtual models. Registering the same provider and id again replaces the virtual model. See
+     * docs/virtual-models.md.
+     */
+    registerVirtualModel<TState = unknown>(model: ExtensionVirtualModel<TState>): void;
+    /** Remove a virtual model registered with `registerVirtualModel()`. */
+    unregisterVirtualModel(provider: string, id: string): void;
     /** Shared event bus for extension communication. */
     events: EventBus;
 }
+/** Virtual model registered via pi.registerVirtualModel(). */
+export interface ExtensionVirtualModel<TState = unknown> extends Omit<VirtualModelDefinition<TState>, "route"> {
+    /** Like `VirtualModelDefinition.route`, with an extension context. */
+    route(request: ModelRouteRequest<TState>, ctx: ExtensionContext): ModelRoute<TState> | Promise<ModelRoute<TState>>;
+}
 /** Configuration for registering a provider via pi.registerProvider(). */
 export interface ProviderConfig {
     /** Display name for the provider in UI. */
@@ -1189,9 +1401,15 @@ export interface ProviderConfig {
      * (`getCurrentSystemPrompt(context.messages)`, `getCurrentTools(context.messages)`).
      * Implementations must invoke `options.onPayload` before sending the provider request and use any
      * returned replacement payload. They must invoke `options.onResponse` after receiving the response
-     * and before consuming its body, matching built-in providers.
+     * and before consuming its body, matching built-in providers. Implementations may invoke
+     * `options.onProviderStreamEvent(data, model)` with parsed stream events before normalization.
+     * Event data is adapter-owned and must be treated as read-only.
      */
     streamSimple?: (model: Model<Api>, context: TranscriptContext, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+    /** Image-generation implementations keyed by image API. */
+    images?: Partial<Record<ImageApi, ProviderImages>>;
+    /** Classifier implementations keyed by classifier API. */
+    classifiers?: Partial<Record<ClassifierApi, ProviderClassifier>>;
     /** Custom headers to include in requests. */
     headers?: Record<string, string>;
     /** If true, adds Authorization: Bearer header with the resolved API key. */
@@ -1221,45 +1439,84 @@ export interface ProviderConfig {
         modifyModels?(models: Model<Api>[], credentials: OAuthCredentials): Model<Api>[];
     };
 }
-/** Configuration for a model within a provider. */
-export interface ProviderModelConfig {
-    /** Model ID (e.g., "claude-sonnet-4-20250514"). */
+interface ProviderModelConfigBase {
+    /** Model ID. */
     id: string;
-    /** Display name (e.g., "Claude 4 Sonnet"). */
+    /** Display name. */
     name: string;
     /** API type override for this model. */
-    api?: Api;
+    api?: string;
     /** 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")[];
     /** Provider input limits and cache-safe image preprocessing metadata. */
-    inputLimits?: Model<Api>["inputLimits"];
+    inputLimits?: AnyModel["inputLimits"];
     /** Per-million-token cost rates and optional request-wide input pricing tiers. */
-    cost: Model<Api>["cost"];
+    cost: AnyModel["cost"];
+    /** Custom headers for this model. */
+    headers?: Record<string, string>;
+}
+/** Chat model configuration. Omitted `type` is normalized to `"chat"`. */
+export interface ProviderChatModelConfig extends ProviderModelConfigBase {
+    type?: "chat";
+    api?: Api;
+    /** 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"];
     /** Best-effort prompt cache lifetime in seconds per retention tier. Unset disables cache warming. */
     promptCache?: Model<Api>["promptCache"];
     /** Maximum context window size in tokens. */
     contextWindow: number;
     /** Maximum output tokens. */
     maxTokens: number;
-    /** Custom headers for this model. */
-    headers?: Record<string, string>;
+    samplingParams?: Record<string, unknown>;
     /** OpenAI compatibility settings. */
     compat?: Model<Api>["compat"];
 }
+/** Image-generation model configuration. */
+export interface ProviderImageModelConfig extends ProviderModelConfigBase {
+    type: "image";
+    api?: ImageApi;
+    output: ("text" | "image")[];
+}
+/** Structured classifier model configuration. */
+export interface ProviderClassifierModelConfig extends ProviderModelConfigBase {
+    type: "classifier";
+    api?: ClassifierApi;
+    contextWindow: number;
+}
+/** Configuration for a model within a provider. */
+export type ProviderModelConfig = ProviderChatModelConfig | ProviderImageModelConfig | ProviderClassifierModelConfig;
 /** Extension factory function type. Supports both sync and async initialization. */
 export type ExtensionFactory = (pi: ExtensionAPI) => void | Promise<void>;
 export type InlineExtension = ExtensionFactory | {
-    /** Display name shown as `<inline:name>` in the startup Extensions list. */
+    /**
+     * Display name shown as `<inline:name>` in the startup Extensions list and errors. With
+     * `builtin`, the extension is named `builtin:name` in errors and diagnostics.
+     */
     name: string;
     factory: ExtensionFactory;
     /** Omit this extension from the startup Extensions list. */
     hidden?: boolean;
+    /**
+     * Leave this extension out when another extension registers a tool, command, or flag with a
+     * name it registers during loading, instead of reporting a conflict. The CLI's built-in MCP,
+     * codemode, and tool search extensions use it, so for example an MCP extension that registers
+     * `/mcp` replaces the built-in MCP support. The factory still runs, so it should only register
+     * tools, commands, flags, and event handlers.
+     */
+    replaceable?: boolean;
+    /**
+     * Supply the code of the `builtin:<name>` extension instead of loading as an inline extension.
+     * `builtin:<name>` is an extension resource like a file: it loads by default, `pi config` lists
+     * it, `-builtin:<name>` in the `extensions` setting and `--no-extensions` disable it, and
+     * `-e builtin:<name>` loads it explicitly. It is hidden from the startup Extensions list and
+     * loads after project trust is resolved, so it cannot handle `project_trust`. The CLI's built-in
+     * extensions use it.
+     */
+    builtin?: boolean;
 };
 export interface RegisteredTool {
     definition: ToolDefinition;
@@ -1293,9 +1550,13 @@ export type GetSessionNameHandler = () => string | undefined;
 export type GetActiveToolsHandler = () => string[];
 /** Tool info with name, description, parameter schema, prompt guidelines, and source metadata. */
 export type ToolInfo = Pick<ToolDefinition, "name" | "description" | "parameters" | "promptGuidelines"> & {
+    exposure: ToolExposure;
+    namespace?: ToolNamespace;
+    annotations?: ToolAnnotations;
     sourceInfo: SourceInfo;
 };
 export type GetAllToolsHandler = () => ToolInfo[];
+export type GetSettingsHandler = () => Settings;
 export type GetCommandsHandler = () => SlashCommandInfo[];
 export type SetActiveToolsHandler = (toolNames: string[]) => void;
 export type RefreshToolsHandler = () => void;
@@ -1320,6 +1581,13 @@ export interface ExtensionRuntimeState {
         provider: Provider;
         extensionPath: string;
     }>;
+    /** Virtual model registrations queued during extension loading, processed when runner binds. */
+    pendingVirtualModelRegistrations: Array<{
+        definition: VirtualModelDefinition;
+        extensionPath: string;
+    }>;
+    /** Create an extension context. Throws before the runner binds. */
+    createContext: () => ExtensionContext;
     /** Throws when this extension instance is stale after runtime replacement. */
     assertActive: () => void;
     /** Marks this extension instance as stale after runtime replacement or reload. */
@@ -1335,6 +1603,10 @@ export interface ExtensionRuntimeState {
     registerProvider: (name: string, config: ProviderConfig, extensionPath?: string) => void;
     registerNativeProvider: (provider: Provider, extensionPath?: string) => void;
     unregisterProvider: (name: string, extensionPath?: string) => void;
+    /** Servers registered with `pi.registerMcpServer()`. */
+    mcpServers: McpServerRegistry;
+    registerVirtualModel: (definition: VirtualModelDefinition, extensionPath?: string) => void;
+    unregisterVirtualModel: (provider: string, id: string) => void;
 }
 /**
  * Action implementations for pi.* API methods.
@@ -1349,6 +1621,7 @@ export interface ExtensionActions {
     setLabel: SetLabelHandler;
     getActiveTools: GetActiveToolsHandler;
     getAllTools: GetAllToolsHandler;
+    getSettings: GetSettingsHandler;
     setActiveTools: SetActiveToolsHandler;
     refreshTools: RefreshToolsHandler;
     getCommands: GetCommandsHandler;
@@ -1361,7 +1634,9 @@ export interface ExtensionActions {
  * Required by all modes.
  */
 export interface ExtensionContextActions {
-    getBackground?: () => BackgroundContext;
+    getExtensionSettings?: ExtensionContext["getExtensionSettings"];
+    setExtensionSettings?: ExtensionContext["setExtensionSettings"];
+    getTasks?: () => TasksContext;
     getModel: () => Model<any> | undefined;
     getScopedModels: () => readonly ScopedModel[];
     isIdle: () => boolean;
@@ -1375,6 +1650,10 @@ export interface ExtensionContextActions {
     compact: (options?: CompactOptions) => void;
     getSystemPrompt: () => string;
     getSystemPromptOptions?: () => BuildSystemPromptOptions;
+    /** Backs `ExtensionToolContext.executeTool()`. Without it, nested calls fail. */
+    executeTool?: (callerId: string, name: string, args: unknown, options: ExecuteToolOptions) => Promise<AgentToolCallOutcome>;
+    /** Backs `ExtensionToolContext.tools`. */
+    getCallableTools?: () => readonly AgentTool[];
 }
 /**
  * Actions for ExtensionCommandContext (ctx.* in command handlers).
@@ -1421,6 +1700,8 @@ export interface Extension {
     path: string;
     resolvedPath: string;
     hidden?: boolean;
+    /** See {@link InlineExtension}. */
+    replaceable?: boolean;
     sourceInfo: SourceInfo;
     handlers: Map<string, HandlerFn[]>;
     tools: Map<string, RegisteredTool>;
@@ -1438,6 +1719,10 @@ export interface LoadExtensionsResult {
         path: string;
         error: string;
     }>;
+    warnings?: Array<{
+        path: string;
+        warning: string;
+    }>;
     /** Shared runtime - actions are throwing stubs until runner.initialize() */
     runtime: ExtensionRuntime;
 }