@selesai/code 0.13.40 → 0.14.3

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, 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, CustomEntry, ReadonlySessionManager, SessionEntry, SessionManager } from "../session-manager.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 { Skill } from "../skills.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, ReadToolDetails, ReadToolInput, WriteToolInput } from "../tools/index.ts";
+import type { BashToolDetails, BashToolInput, EditToolInput, FindToolDetails, FindToolInput, GrepToolDetails, GrepToolInput, LsToolDetails, LsToolInput, PowerShellToolDetails, PowerShellToolInput, ReadToolDetails, ReadToolInput, WriteToolInput } from "../tools/index.ts";
+import type { ModelRoute, ModelRouteRequest, VirtualModelDefinition } from "../virtual-models.ts";
 export type { ExecOptions, ExecResult } from "../exec.ts";
 export type { BuildSystemPromptOptions, NormalizedBuildSystemPromptOptions } from "../system-prompt.ts";
 export type { AgentToolResult, AgentToolUpdateCallback, ToolExecutionMode };
@@ -105,8 +108,8 @@ export interface ExtensionUIContext {
     /** Set a custom footer component, or undefined to restore the built-in footer.
      *
      * The factory receives a FooterDataProvider for data not otherwise accessible:
-     * git branch and extension statuses from setStatus(). Token stats, model info,
-     * etc. are available via ctx.sessionManager and ctx.model.
+     * git branch and extension statuses from setStatus(). Context usage is on
+     * ctx.getContextUsage(), token stats on ctx.sessionManager.getEntries(), model info on ctx.model.
      */
     setFooter(factory: ((tui: TUI, theme: Theme, footerData: ReadonlyFooterDataProvider) => Component & {
         dispose?(): void;
@@ -251,6 +254,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.
@@ -341,6 +372,78 @@ export interface ToolRenderContext<TState = any, TArgs = any> {
     showImages: boolean;
     /** Whether the current result is an error. */
     isError: boolean;
+    /**
+     * Milliseconds the tool's execution took, from the final result; `undefined` while it runs, when it did not run, or
+     * for results stored before durations were recorded.
+     */
+    durationMs: number | undefined;
+    /** Horizontal padding configured by the outputPad setting. Renderers with `renderShell: "self"` apply it themselves. */
+    outputPad: number;
+}
+/**
+ * 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;
+    /** A tool's `promptGuidelines`. Hidden declarations leave them out of the system prompt. */
+    getPromptGuidelines(name: string): readonly string[];
+}
+/** 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().
@@ -354,20 +457,6 @@ export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = un
     description: string;
     /** 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 discovery metadata for the capability gateway. When present, the
-     * tool is eligible for catalog/discovery; when absent, a conservative
-     * name/first-sentence fallback summary is used. Never contains the full
-     * tool description or schema.
-     */
-    discovery?: {
-        /** Short one-line purpose shown in the catalog. */
-        summary?: string;
-        /** Alternative names the router can match. */
-        aliases?: string[];
-        /** Stable category label. */
-        category?: string;
-    };
     /** Optional guideline bullets appended to the default system prompt Guidelines section when this tool is active. */
     promptGuidelines?: string[];
     /** Parameter schema (TypeBox) */
@@ -378,6 +467,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.
@@ -387,13 +501,19 @@ 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>>) => Component;
     /** Custom rendering for tool result display */
     renderResult?: (result: AgentToolResult<TDetails>, options: ToolRenderResultOptions, theme: Theme, context: ToolRenderContext<TState, Static<TParams>>) => Component;
 }
 type AnyToolDefinition = ToolDefinition<any, any, any>;
+export type ToolRenderers = Pick<AnyToolDefinition, "renderShell" | "renderCall" | "renderResult">;
+/**
+ * Chooses how calls to a tool are drawn, including tools that are not registered. `next()` returns
+ * the renderers the remaining resolvers, then the registered tool, would use.
+ */
+export type ToolRendererResolver = (toolName: string, next: () => ToolRenderers | undefined) => ToolRenderers | undefined;
 /**
  * Preserve parameter inference for standalone tool definitions.
  *
@@ -430,6 +550,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";
@@ -478,13 +609,18 @@ export interface SessionCompactEvent {
     /** True when the aborted turn is retried after this compaction (overflow recovery) */
     willRetry: boolean;
 }
-/** Fired after context compaction fails or is aborted. */
+/** Fired after context compaction fails or is aborted */
 export interface SessionCompactFailedEvent {
     type: "session_compact_failed";
+    /** What triggered the compaction: manual /compact, the context threshold, or context overflow recovery */
     reason: "manual" | "threshold" | "overflow";
+    /** Error text when compaction failed for a non-abort reason. */
     errorMessage?: string;
+    /** True when compaction was cancelled or aborted. */
     aborted: boolean;
+    /** True when the aborted turn would have been retried after this compaction (overflow recovery) */
     willRetry: boolean;
+    /** True when the failing compaction content came from a session_before_compact handler. */
     fromExtension: boolean;
 }
 /** Fired when the session display name changes (e.g. via /name). */
@@ -529,11 +665,26 @@ export interface SessionTreeEvent {
     fromExtension?: boolean;
 }
 export type SessionEvent = SessionStartEvent | SessionInfoChangedEvent | SessionBeforeSwitchEvent | SessionBeforeForkEvent | SessionBeforeCompactEvent | SessionCompactEvent | SessionCompactFailedEvent | SessionShutdownEvent | SessionBeforeTreeEvent | SessionTreeEvent | SessionInfoChangedEvent;
-/** Fired before each LLM call. Can modify messages. */
+/**
+ * Fired before each LLM call. Can modify messages.
+ *
+ * `messages` holds the conversation without system messages. The prompt and tool state
+ * belong to Pi: it restores them after the handler returns, so a handler cannot drop
+ * them and does not need to preserve them.
+ */
 export interface ContextEvent {
     type: "context";
     messages: AgentMessage[];
 }
+/**
+ * Fired before each LLM call, after every `context` handler has run and Pi has restored
+ * the prompt and tool state. `messages` is the full transcript including system messages,
+ * and the result is sent as returned: the handler owns the prompt and tool declarations.
+ */
+export interface ContextWithSystemEvent {
+    type: "context_with_system";
+    messages: AgentMessage[];
+}
 /** Fired before a provider request is sent. Can replace the payload. */
 export interface BeforeProviderRequestEvent {
     type: "before_provider_request";
@@ -554,6 +705,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";
@@ -575,9 +734,59 @@ export interface AgentEndEvent {
     type: "agent_end";
     messages: AgentMessage[];
 }
+export type AgentActivityOutcome = "completed" | "aborted" | "error";
+export interface CustomEntryDraft {
+    type: "custom";
+    customType: string;
+    data?: unknown;
+}
+export interface CustomMessageEntryDraft {
+    type: "custom_message";
+    customType: string;
+    content: string | (TextContent | ImageContent)[];
+    display: boolean;
+    details?: unknown;
+}
+export interface ContextEditEntryDraft {
+    type: "context_edit";
+    targetId: string;
+    replacement: ContextEditEntry["replacement"];
+}
+export interface CompactionEntryDraft {
+    type: "compaction";
+    summary: string;
+    /** Null creates a self-retaining compaction that keeps no preceding entries. */
+    firstKeptEntryId: string | null;
+    details?: unknown;
+    usage?: Usage;
+}
+export type SessionBoundaryDraft = CustomEntryDraft | CustomMessageEntryDraft | ContextEditEntryDraft | CompactionEntryDraft;
+export interface BoundaryContextPreview {
+    contextEntries: ProjectedSessionEntry[];
+    contextMessages: AgentMessage[];
+    llmMessages: Message[];
+    pendingMessages: AgentMessage[];
+    canContinue: boolean;
+}
+export interface BoundaryState {
+    entries: SessionBoundaryDraft[];
+    continue: boolean;
+    context: BoundaryContextPreview;
+    outcome: AgentActivityOutcome;
+}
+export interface BoundaryResult {
+    entries?: SessionBoundaryDraft[];
+    continue?: boolean;
+}
+/** Fired before final settlement. May append entries and ensure one next provider request. */
+export interface AgentBeforeSettleEvent extends BoundaryState {
+    type: "agent_before_settle";
+}
 /** Fired after an agent run has fully settled and no automatic retry, compaction, or queued continuation will run. */
 export interface AgentSettledEvent {
     type: "agent_settled";
+    /** Whether the run ended because it was aborted, for example with Escape. */
+    aborted: boolean;
 }
 export type UIPromptKind = "select" | "confirm" | "input" | "editor" | "custom";
 /** Fired when Pi starts waiting on a blocking user-facing extension UI prompt. */
@@ -601,11 +810,13 @@ export interface TurnStartEvent {
     timestamp: number;
 }
 /** Fired at the end of each turn */
-export interface TurnEndEvent {
+export interface TurnEndEvent extends BoundaryState {
     type: "turn_end";
     turnIndex: number;
     message: AgentMessage;
     toolResults: ToolResultMessage[];
+    messageEntryId: string;
+    toolResultEntryIds: string[];
 }
 /** Fired when a message starts (user, assistant, or toolResult) */
 export interface MessageStartEvent {
@@ -629,6 +840,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 {
@@ -637,6 +850,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 {
@@ -645,6 +860,10 @@ export interface ToolExecutionEndEvent {
     toolName: string;
     result: any;
     isError: boolean;
+    /** Milliseconds `execute()` took, measured with a monotonic clock; absent when the tool did not run. */
+    durationMs?: number;
+    /** 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 */
@@ -696,12 +915,23 @@ 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";
     input: BashToolInput;
 }
+export interface PowerShellToolCallEvent extends ToolCallEventBase {
+    toolName: "powershell";
+    input: PowerShellToolInput;
+}
 export interface ReadToolCallEvent extends ToolCallEventBase {
     toolName: "read";
     input: ReadToolInput;
@@ -736,12 +966,20 @@ export interface CustomToolCallEvent extends ToolCallEventBase {
  * `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;
+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;
@@ -750,6 +988,10 @@ export interface BashToolResultEvent extends ToolResultEventBase {
     toolName: "bash";
     details: BashToolDetails | undefined;
 }
+export interface PowerShellToolResultEvent extends ToolResultEventBase {
+    toolName: "powershell";
+    details: PowerShellToolDetails | undefined;
+}
 export interface ReadToolResultEvent extends ToolResultEventBase {
     toolName: "read";
     details: ReadToolDetails | undefined;
@@ -779,8 +1021,9 @@ export interface CustomToolResultEvent extends ToolResultEventBase {
     details: unknown;
 }
 /** Fired after a tool executes. Can modify result. */
-export type ToolResultEvent = BashToolResultEvent | ReadToolResultEvent | EditToolResultEvent | WriteToolResultEvent | GrepToolResultEvent | FindToolResultEvent | LsToolResultEvent | CustomToolResultEvent;
+export type ToolResultEvent = BashToolResultEvent | PowerShellToolResultEvent | ReadToolResultEvent | EditToolResultEvent | WriteToolResultEvent | GrepToolResultEvent | FindToolResultEvent | LsToolResultEvent | CustomToolResultEvent;
 export declare function isBashToolResult(e: ToolResultEvent): e is BashToolResultEvent;
+export declare function isPowerShellToolResult(e: ToolResultEvent): e is PowerShellToolResultEvent;
 export declare function isReadToolResult(e: ToolResultEvent): e is ReadToolResultEvent;
 export declare function isEditToolResult(e: ToolResultEvent): e is EditToolResultEvent;
 export declare function isWriteToolResult(e: ToolResultEvent): e is WriteToolResultEvent;
@@ -808,6 +1051,7 @@ export declare function isLsToolResult(e: ToolResultEvent): e is LsToolResultEve
  * CustomToolCallEvent.toolName is `string` which overlaps with all literals.
  */
 export declare function isToolCallEventType(toolName: "bash", event: ToolCallEvent): event is BashToolCallEvent;
+export declare function isToolCallEventType(toolName: "powershell", event: ToolCallEvent): event is PowerShellToolCallEvent;
 export declare function isToolCallEventType(toolName: "read", event: ToolCallEvent): event is ReadToolCallEvent;
 export declare function isToolCallEventType(toolName: "edit", event: ToolCallEvent): event is EditToolCallEvent;
 export declare function isToolCallEventType(toolName: "write", event: ToolCallEvent): event is WriteToolCallEvent;
@@ -819,16 +1063,23 @@ export declare function isToolCallEventType<TName extends string, TInput extends
     input: TInput;
 };
 /** Union of all event types */
-export type ExtensionEvent = ProjectTrustEvent | ResourcesDiscoverEvent | SessionEvent | ContextEvent | CacheWarmingDecisionEvent | BeforeProviderRequestEvent | BeforeProviderHeadersEvent | AfterProviderResponseEvent | BeforeAgentStartEvent | AgentStartEvent | AgentEndEvent | 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[];
 }
+export type TurnEndEventResult = BoundaryResult;
+export type AgentBeforeSettleEventResult = BoundaryResult;
 export type BeforeProviderRequestEventResult = unknown;
 export type { CacheWarmingDecisionEvent, CacheWarmingDecisionEventResult } from "../cache-warmer.ts";
 export interface ToolCallEventResult {
     /** Block tool execution. To modify arguments, mutate `event.input` in place instead. */
     block?: boolean;
     reason?: string;
+    /**
+     * Hint that the agent should stop after the current tool batch when this call is blocked.
+     * Early termination only happens when every finalized tool result in the batch sets this to true.
+     */
+    terminate?: boolean;
 }
 /** Result from user_bash event handler */
 export type UserBashEventResult = {
@@ -840,9 +1091,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;
     /** Hint that the current assistant tool batch should not trigger another LLM call. */
@@ -924,21 +1181,25 @@ 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;
+    on(event: "context_with_system", handler: ExtensionHandler<ContextWithSystemEvent, ContextEventResult>): () => void;
     on(event: "cache_warming_decision", handler: ExtensionHandler<CacheWarmingDecisionEvent, CacheWarmingDecisionEventResult>): () => void;
     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;
+    on(event: "agent_before_settle", handler: ExtensionHandler<AgentBeforeSettleEvent, AgentBeforeSettleEventResult>): () => void;
     on(event: "agent_settled", handler: ExtensionHandler<AgentSettledEvent>): () => void;
     on(event: "ui_prompt_start", handler: ExtensionHandler<UIPromptStartEvent>): () => void;
     on(event: "ui_prompt_end", handler: ExtensionHandler<UIPromptEndEvent>): () => void;
     on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): () => void;
-    on(event: "turn_end", handler: ExtensionHandler<TurnEndEvent>): () => void;
+    on(event: "turn_end", handler: ExtensionHandler<TurnEndEvent, TurnEndEventResult>): () => void;
     on(event: "message_start", handler: ExtensionHandler<MessageStartEvent>): () => void;
     on(event: "message_update", handler: ExtensionHandler<MessageUpdateEvent>): () => void;
     on(event: "message_end", handler: ExtensionHandler<MessageEndEvent, MessageEndEventResult>): () => void;
@@ -963,17 +1224,23 @@ export interface ExtensionAPI {
     /** Register a CLI flag. */
     registerFlag(name: string, options: {
         description?: string;
-        type: "boolean" | "string";
-        default?: boolean | string;
+        type: "boolean";
+        default?: boolean;
+    } | {
+        description?: string;
+        type: "string";
+        default?: string;
     }): void;
     /** Get the value of a registered CLI flag. */
     getFlag(name: string): boolean | string | undefined;
-    /** Register a markdown transformer for assistant/user/thinking text rendering. */
-    registerMarkdownTransformer(transformer: MarkdownTransformer): void;
     /** Register a custom renderer for CustomMessageEntry. */
     registerMessageRenderer<T = unknown>(customType: string, renderer: MessageRenderer<T>): void;
+    /** Register a transformer for user and assistant Markdown before Pi renders it in the interactive transcript. */
+    registerMarkdownTransformer(transformer: MarkdownTransformer): void;
     /** Register a custom renderer for CustomEntry. Custom entries do not participate in LLM context. */
     registerEntryRenderer<T = unknown>(customType: string, renderer: EntryRenderer<T>): void;
+    /** Choose how tool calls are drawn. Resolvers run in extension load order. */
+    registerToolRenderer(resolver: ToolRendererResolver): void;
     /** Send a custom message to the session. */
     sendMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">, options?: {
         triggerTurn?: boolean;
@@ -998,7 +1265,7 @@ 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 the resolved, trust-filtered skill catalog (enabled skills with
@@ -1014,9 +1281,14 @@ export interface ExtensionAPI {
      * mutated; explicit inline skill invocation is unaffected.
      */
     setSkillsIndexFilter(filter: ((skills: Skill[]) => Skill[]) | undefined): void;
-    /** 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[];
@@ -1100,9 +1372,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. */
@@ -1119,9 +1427,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. */
@@ -1130,62 +1444,105 @@ export interface ProviderConfig {
     models?: ProviderModelConfig[];
     /**
      * Refresh this provider's model list. The returned list replaces extension-provided models.
-     * Use context.store explicitly when the catalog should persist across sessions.
+     * Use context.publish({ persist: entry }) when the catalog should persist across sessions.
      */
     refreshModels?(context: RefreshModelsContext): Promise<ProviderModelConfig[]>;
     /** OAuth provider for /login support. The `id` is set automatically from the provider name. */
     oauth?: {
         /** Display name for the provider in login UI. */
         name: string;
+        /** Whether access through this auth method is backed by a provider subscription. */
+        isSubscription?: boolean;
         /** @deprecated Retained for source compatibility; canonical auth flows ignore it. */
         usesCallbackServer?: boolean;
         /** Run the login flow, return credentials to persist. */
         login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>;
         /** Refresh expired credentials, return updated credentials to persist. */
-        refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials>;
+        refreshToken(credentials: OAuthCredentials, signal: AbortSignal): Promise<OAuthCredentials>;
         /** Convert credentials to API key string for the provider. */
         getApiKey(credentials: OAuthCredentials): string;
         /** Legacy synchronous credential-dependent model projection. */
         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;
+    /** Supported input types. */
+    input: ("text" | "image")[];
+    /** Provider input limits and cache-safe image preprocessing metadata. */
+    inputLimits?: AnyModel["inputLimits"];
+    /** Per-million-token cost rates and optional request-wide input pricing tiers. */
+    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"];
-    /** Supported input types. */
-    input: ("text" | "image")[];
-    /** Per-million-token cost rates and optional request-wide input pricing tiers. */
-    cost: Model<Api>["cost"];
     /** 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;
@@ -1218,7 +1575,10 @@ export type SetSessionNameHandler = (name: string) => void;
 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" | "discovery"> & {
+export type ToolInfo = Pick<ToolDefinition, "name" | "description" | "parameters" | "promptGuidelines"> & {
+    exposure: ToolExposure;
+    namespace?: ToolNamespace;
+    annotations?: ToolAnnotations;
     sourceInfo: SourceInfo;
 };
 /** A resolved, trust-filtered skill in the extension-facing catalog. */
@@ -1231,6 +1591,7 @@ export interface ResolvedSkillInfo {
     disableModelInvocation: boolean;
 }
 export type GetAllToolsHandler = () => ToolInfo[];
+export type GetSettingsHandler = () => Settings;
 export type GetCommandsHandler = () => SlashCommandInfo[];
 export type SetActiveToolsHandler = (toolNames: string[]) => void;
 export type RefreshToolsHandler = () => void;
@@ -1255,10 +1616,19 @@ 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. */
     invalidate: (message?: string) => void;
+    /** Retain an event-bus subscription until this runtime is invalidated. */
+    trackEventBusSubscription: (unsubscribe: () => void) => () => void;
     /**
      * Register or unregister a provider.
      *
@@ -1268,6 +1638,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.
@@ -1282,6 +1656,7 @@ export interface ExtensionActions {
     setLabel: SetLabelHandler;
     getActiveTools: GetActiveToolsHandler;
     getAllTools: GetAllToolsHandler;
+    getSettings: GetSettingsHandler;
     setActiveTools: SetActiveToolsHandler;
     getResolvedSkills: () => ResolvedSkillInfo[];
     setSkillsIndexFilter: (filter: ((skills: Skill[]) => Skill[]) | undefined) => void;
@@ -1308,6 +1683,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).
@@ -1354,10 +1733,14 @@ export interface Extension {
     path: string;
     resolvedPath: string;
     hidden?: boolean;
+    /** See {@link InlineExtension}. */
+    replaceable?: boolean;
     sourceInfo: SourceInfo;
     handlers: Map<string, HandlerFn[]>;
     tools: Map<string, RegisteredTool>;
     messageRenderers: Map<string, MessageRenderer>;
+    toolRenderers?: ToolRendererResolver[];
+    markdownTransformer?: MarkdownTransformer;
     entryRenderers?: Map<string, EntryRenderer>;
     commands: Map<string, RegisteredCommand>;
     flags: Map<string, ExtensionFlag>;
@@ -1370,6 +1753,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;
 }