@sammorrowdrums/mcpi 0.70.9 → 0.85.0-bootstrap.0

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

@@ -7,30 +7,31 @@
  * - Register commands, keyboard shortcuts, and CLI flags
  * - Interact with the user via UI primitives
  */
-import type { AutocompleteItem, AutocompleteProvider, Component, EditorComponent, EditorTheme, KeyId, OverlayHandle, OverlayOptions, TUI } from "@mariozechner/pi-tui";
-import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode } from "@sammorrowdrums/mcpi-agent";
-import type { Api, AssistantMessageEvent, AssistantMessageEventStream, Context, ImageContent, Model, OAuthCredentials, OAuthLoginCallbacks, SimpleStreamOptions, TextContent, ToolResultMessage } from "@sammorrowdrums/mcpi-ai";
+import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode } from "@sammorrowdrums/mcpi-agent-core";
+import type { Api, AssistantMessageEvent, AssistantMessageEventStream, ConstrainedSamplingConfig, Context, ImageContent, Model, OAuthCredentials, OAuthLoginCallbacks, Provider, ProviderHeaders, RefreshModelsContext, SimpleStreamOptions, TextContent, ToolResultMessage, Usage } from "@sammorrowdrums/mcpi-ai";
+import type { AutocompleteItem, AutocompleteProvider, Component, EditorComponent, EditorTheme, KeyId, OverlayHandle, OverlayOptions, TUI } from "@sammorrowdrums/mcpi-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";
-import type { EventBus } from "../event-bus.js";
-import type { ExecOptions, ExecResult } from "../exec.js";
-import type { ReadonlyFooterDataProvider } from "../footer-data-provider.js";
-import type { KeybindingsManager } from "../keybindings.js";
-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 { BuildSystemPromptOptions } from "../system-prompt.js";
+import type { Theme } from "../../modes/interactive/theme/theme.ts";
+import type { BashResult } from "../bash-executor.ts";
+import type { CompactionPreparation, CompactionResult } from "../compaction/index.ts";
+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 { 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 { SlashCommandInfo } from "../slash-commands.ts";
+import type { SourceInfo } from "../source-info.ts";
+import type { BuildSystemPromptOptions } 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";
+export type { ExecOptions, ExecResult } from "../exec.ts";
+export type { BuildSystemPromptOptions } from "../system-prompt.ts";
 export type { AgentToolResult, AgentToolUpdateCallback, ToolExecutionMode };
-export type { AppKeybinding, KeybindingsManager } from "../keybindings.js";
+export type { AppKeybinding, KeybindingsManager } from "../keybindings.ts";
 /** Options for extension UI dialogs. */
 export interface ExtensionUIDialogOptions {
     /** AbortSignal to programmatically dismiss the dialog. */
@@ -59,6 +60,7 @@ export interface WorkingIndicatorOptions {
 }
 /** 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.
@@ -78,6 +80,8 @@ 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.
      *
@@ -140,7 +144,7 @@ export interface ExtensionUIContext {
      * - `keybindings`: KeybindingsManager for app-level keybindings
      *
      * For full app keybinding support (escape, ctrl+d, model switching, etc.),
-     * extend `CustomEditor` from `mcpi` and call
+     * extend `CustomEditor` from `@sammorrowdrums/mcpi` and call
      * `super.handleInput(data)` for keys you don't handle.
      *
      * @example
@@ -164,7 +168,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. */
@@ -199,10 +205,13 @@ export interface CompactOptions {
 /**
  * Context passed to extension event handlers.
  */
+export type ExtensionMode = "tui" | "rpc" | "json" | "print";
 export interface ExtensionContext {
     /** UI methods for user interaction */
     ui: ExtensionUIContext;
-    /** Whether UI is available (false in print/RPC mode) */
+    /** Current run mode. Use "tui" to guard terminal-only UI such as custom components. */
+    mode: ExtensionMode;
+    /** Whether dialog-capable UI is available (true in TUI and RPC modes) */
     hasUI: boolean;
     /** Current working directory */
     cwd: string;
@@ -212,15 +221,24 @@ export interface ExtensionContext {
     modelRegistry: ModelRegistry;
     /** Current model (may be undefined) */
     model: Model<any> | undefined;
+    /** Models scoped to this session (resolved from `--models` /
+     *  `enabledModels` settings against the available catalogue). Same set
+     *  the `/scoped-models` command shows. Empty when no scoping is
+     *  configured (all available models are usable). Read-only snapshot. */
+    scopedModels: readonly ScopedModel[];
+    /** Current thinking level, when provided by the session runtime. */
+    thinkingLevel?: ThinkingLevel;
     /** Whether the agent is idle (not streaming) */
     isIdle(): boolean;
+    /** Whether project-local trust is active for this context. */
+    isProjectTrusted(): 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 */
     hasPendingMessages(): boolean;
-    /** Gracefully shutdown pi and exit. Available in all contexts. */
+    /** Gracefully shut down mcpi and exit. Available in all contexts. */
     shutdown(): void;
     /** Get current context usage for the active model. */
     getContextUsage(): ContextUsage | undefined;
@@ -234,6 +252,8 @@ export interface ExtensionContext {
  * Includes session control methods only safe in user-initiated commands.
  */
 export interface ExtensionCommandContext extends ExtensionContext {
+    /** Get the current base system-prompt construction options. */
+    getSystemPromptOptions(): BuildSystemPromptOptions;
     /** Wait for the agent to finish streaming */
     waitForIdle(): Promise<void>;
     /** Start a new session, optionally with initialization. */
@@ -266,7 +286,7 @@ export interface ExtensionCommandContext extends ExtensionContext {
     }): Promise<{
         cancelled: boolean;
     }>;
-    /** Reload extensions, skills, prompts, and themes. */
+    /** Reload extensions, skills, prompts, themes, and context files. */
     reload(): Promise<void>;
 }
 /**
@@ -281,6 +301,7 @@ export interface ReplacedSessionContext extends ExtensionCommandContext {
     }): Promise<void>;
     sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
         deliverAs?: "steer" | "followUp";
+        expandPromptTemplates?: boolean;
     }): Promise<void>;
 }
 /** Rendering options for tool results */
@@ -333,6 +354,8 @@ export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = un
     promptGuidelines?: string[];
     /** Parameter schema (TypeBox) */
     parameters: TParams;
+    /** Optional provider-side constrained sampling request for this tool. Set false to explicitly disable it, equivalent to leaving it undefined. */
+    constrainedSampling?: false | ConstrainedSamplingConfig;
     /** 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. */
@@ -345,18 +368,6 @@ export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = un
      * If omitted, the default execution mode applies.
      */
     executionMode?: ToolExecutionMode;
-    /**
-     * When true, the tool is registered for execution but excluded from the
-     * system prompt. The model discovers it through conversation content
-     * (e.g. a skill's tool_result) rather than up-front tool descriptions.
-     *
-     * This enables progressive tool disclosure without changing the tools
-     * array sent to the provider, preserving prompt cache across turns.
-     *
-     * Experimental — ideally model providers would explicitly support
-     * deferred tool loading (e.g. Anthropic's `defer_loading`).
-     */
-    deferred?: boolean;
     /** 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 */
@@ -373,6 +384,22 @@ type AnyToolDefinition = ToolDefinition<any, any, any>;
  * `unknown`.
  */
 export declare function defineTool<TParams extends TSchema, TDetails = unknown, TState = any>(tool: ToolDefinition<TParams, TDetails, TState>): ToolDefinition<TParams, TDetails, TState> & AnyToolDefinition;
+export interface ProjectTrustEvent {
+    type: "project_trust";
+    cwd: string;
+}
+export type ProjectTrustEventDecision = "yes" | "no" | "undecided";
+export interface ProjectTrustEventResult {
+    trusted: ProjectTrustEventDecision;
+    remember?: boolean;
+}
+export interface ProjectTrustContext {
+    cwd: string;
+    mode: ExtensionMode;
+    hasUI: boolean;
+    ui: Pick<ExtensionUIContext, "select" | "confirm" | "input" | "notify">;
+}
+export type ProjectTrustHandler = (event: ProjectTrustEvent, ctx: ProjectTrustContext) => Promise<ProjectTrustEventResult> | ProjectTrustEventResult;
 /** Fired after session_start to allow extensions to provide additional resource paths. */
 export interface ResourcesDiscoverEvent {
     type: "resources_discover";
@@ -393,6 +420,12 @@ export interface SessionStartEvent {
     /** Previously active session file. Present for "new", "resume", and "fork". */
     previousSessionFile?: string;
 }
+/** Fired when the current session metadata changes. */
+export interface SessionInfoChangedEvent {
+    type: "session_info_changed";
+    /** Current normalized session name. Undefined when the name is cleared. */
+    name: string | undefined;
+}
 /** Fired before switching to another session (can be cancelled) */
 export interface SessionBeforeSwitchEvent {
     type: "session_before_switch";
@@ -411,6 +444,10 @@ export interface SessionBeforeCompactEvent {
     preparation: CompactionPreparation;
     branchEntries: SessionEntry[];
     customInstructions?: string;
+    /** What triggered the compaction: manual /compact, the context threshold, or context overflow recovery */
+    reason: "manual" | "threshold" | "overflow";
+    /** True when the aborted turn is retried after this compaction (overflow recovery) */
+    willRetry: boolean;
     signal: AbortSignal;
 }
 /** Fired after context compaction */
@@ -418,6 +455,10 @@ export interface SessionCompactEvent {
     type: "session_compact";
     compactionEntry: CompactionEntry;
     fromExtension: boolean;
+    /** What triggered the compaction: manual /compact, the context threshold, or context overflow recovery */
+    reason: "manual" | "threshold" | "overflow";
+    /** True when the aborted turn is retried after this compaction (overflow recovery) */
+    willRetry: boolean;
 }
 /** Fired before an extension runtime is torn down due to quit, reload, or session replacement. */
 export interface SessionShutdownEvent {
@@ -454,7 +495,7 @@ export interface SessionTreeEvent {
     summaryEntry?: BranchSummaryEntry;
     fromExtension?: boolean;
 }
-export type SessionEvent = SessionStartEvent | SessionBeforeSwitchEvent | SessionBeforeForkEvent | SessionBeforeCompactEvent | SessionCompactEvent | SessionShutdownEvent | SessionBeforeTreeEvent | SessionTreeEvent;
+export type SessionEvent = SessionStartEvent | SessionInfoChangedEvent | SessionBeforeSwitchEvent | SessionBeforeForkEvent | SessionBeforeCompactEvent | SessionCompactEvent | SessionShutdownEvent | SessionBeforeTreeEvent | SessionTreeEvent;
 /** Fired before each LLM call. Can modify messages. */
 export interface ContextEvent {
     type: "context";
@@ -465,6 +506,15 @@ export interface BeforeProviderRequestEvent {
     type: "before_provider_request";
     payload: unknown;
 }
+/**
+ * Fired after request headers are assembled, before the provider HTTP call.
+ * Handlers mutate `headers` in place (e.g. to inject tracing/session headers);
+ * the return value is ignored. A `null` value deletes that header.
+ */
+export interface BeforeProviderHeadersEvent {
+    type: "before_provider_headers";
+    headers: ProviderHeaders;
+}
 /** Fired after a provider response is received and before the response stream is consumed. */
 export interface AfterProviderResponseEvent {
     type: "after_provider_response";
@@ -480,7 +530,7 @@ export interface BeforeAgentStartEvent {
     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. */
+    /** Structured options used to build the system prompt. Extensions can inspect this to understand what mcpi loaded without re-discovering resources. */
     systemPromptOptions: BuildSystemPromptOptions;
 }
 /** Fired when an agent loop starts */
@@ -492,6 +542,10 @@ export interface AgentEndEvent {
     type: "agent_end";
     messages: AgentMessage[];
 }
+/** Fired after an agent run has fully settled and no automatic retry, compaction, or queued continuation will run. */
+export interface AgentSettledEvent {
+    type: "agent_settled";
+}
 /** Fired at the start of each turn */
 export interface TurnStartEvent {
     type: "turn_start";
@@ -552,6 +606,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";
@@ -573,6 +633,8 @@ export interface InputEvent {
     images?: ImageContent[];
     /** Where the input came from */
     source: InputSource;
+    /** How the input will be delivered during streaming, or undefined when idle */
+    streamingBehavior?: "steer" | "followUp";
 }
 /** Result from input event handler */
 export type InputEventResult = {
@@ -633,6 +695,8 @@ interface ToolResultEventBase {
     input: Record<string, unknown>;
     content: (TextContent | ImageContent)[];
     isError: boolean;
+    /** Usage from the tool execution itself, if available. */
+    usage?: Usage;
 }
 export interface BashToolResultEvent extends ToolResultEventBase {
     toolName: "bash";
@@ -707,7 +771,7 @@ export declare function isToolCallEventType<TName extends string, TInput extends
     input: TInput;
 };
 /** Union of all event types */
-export type ExtensionEvent = ResourcesDiscoverEvent | SessionEvent | ContextEvent | BeforeProviderRequestEvent | AfterProviderResponseEvent | BeforeAgentStartEvent | AgentStartEvent | AgentEndEvent | TurnStartEvent | TurnEndEvent | MessageStartEvent | MessageUpdateEvent | MessageEndEvent | ToolExecutionStartEvent | ToolExecutionUpdateEvent | ToolExecutionEndEvent | ModelSelectEvent | UserBashEvent | InputEvent | ToolCallEvent | ToolResultEvent;
+export type ExtensionEvent = ProjectTrustEvent | ResourcesDiscoverEvent | SessionEvent | ContextEvent | BeforeProviderRequestEvent | BeforeProviderHeadersEvent | AfterProviderResponseEvent | BeforeAgentStartEvent | AgentStartEvent | AgentEndEvent | AgentSettledEvent | TurnStartEvent | TurnEndEvent | MessageStartEvent | MessageUpdateEvent | MessageEndEvent | ToolExecutionStartEvent | ToolExecutionUpdateEvent | ToolExecutionEndEvent | ModelSelectEvent | ThinkingLevelSelectEvent | UserBashEvent | InputEvent | ToolCallEvent | ToolResultEvent;
 export interface ContextEventResult {
     messages?: AgentMessage[];
 }
@@ -716,6 +780,11 @@ 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 interface UserBashEventResult {
@@ -728,6 +797,11 @@ export interface ToolResultEventResult {
     content?: (TextContent | ImageContent)[];
     details?: unknown;
     isError?: boolean;
+    usage?: Usage;
+}
+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">;
@@ -750,6 +824,7 @@ export interface SessionBeforeTreeResult {
     summary?: {
         summary: string;
         details?: unknown;
+        usage?: Usage;
     };
     /** Override custom instructions for summarization */
     customInstructions?: string;
@@ -760,8 +835,20 @@ export interface SessionBeforeTreeResult {
 }
 export interface MessageRenderOptions {
     expanded: boolean;
+    /** Horizontal padding configured by the outputPad setting. */
+    outputPad: number;
+}
+export interface MarkdownTransformContext {
+    messageType: "user" | "assistant" | "assistant-thinking";
+    isStreaming: boolean;
+    availableWidth: number;
+}
+export type MarkdownTransformer = (markdown: string, context: MarkdownTransformContext) => string;
+export interface EntryRenderOptions {
+    expanded: boolean;
 }
 export type MessageRenderer<T = unknown> = (message: CustomMessage<T>, options: MessageRenderOptions, theme: Theme) => Component | undefined;
+export type EntryRenderer<T = unknown> = (entry: CustomEntry<T>, options: EntryRenderOptions, theme: Theme) => Component | undefined;
 export interface RegisteredCommand {
     name: string;
     sourceInfo: SourceInfo;
@@ -778,8 +865,10 @@ export type ExtensionHandler<E, R = undefined> = (event: E, ctx: ExtensionContex
  * ExtensionAPI passed to extension factory functions.
  */
 export interface ExtensionAPI {
+    on(event: "project_trust", handler: ProjectTrustHandler): void;
     on(event: "resources_discover", handler: ExtensionHandler<ResourcesDiscoverEvent, ResourcesDiscoverResult>): void;
     on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
+    on(event: "session_info_changed", handler: ExtensionHandler<SessionInfoChangedEvent>): void;
     on(event: "session_before_switch", handler: ExtensionHandler<SessionBeforeSwitchEvent, SessionBeforeSwitchResult>): void;
     on(event: "session_before_fork", handler: ExtensionHandler<SessionBeforeForkEvent, SessionBeforeForkResult>): void;
     on(event: "session_before_compact", handler: ExtensionHandler<SessionBeforeCompactEvent, SessionBeforeCompactResult>): void;
@@ -789,19 +878,22 @@ export interface ExtensionAPI {
     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: "before_provider_headers", handler: ExtensionHandler<BeforeProviderHeadersEvent>): 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;
+    on(event: "agent_settled", handler: ExtensionHandler<AgentSettledEvent>): void;
     on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
     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;
@@ -823,16 +915,12 @@ export interface ExtensionAPI {
     }): void;
     /** Get the value of a registered CLI flag. */
     getFlag(name: string): boolean | string | undefined;
-    /**
-     * Set a session-scoped environment variable for agent-spawned subprocesses.
-     * These are merged into the environment of bash tool invocations and exec() calls.
-     * Does not modify `process.env`.
-     */
-    setEnv(key: string, value: string): void;
-    /** Remove a session-scoped environment variable. */
-    unsetEnv(key: string): 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 mcpi 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;
     /** Send a custom message to the session. */
     sendMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">, options?: {
         triggerTurn?: boolean;
@@ -841,9 +929,11 @@ export interface ExtensionAPI {
     /**
      * Send a user message to the agent. Always triggers a turn.
      * When the agent is streaming, use deliverAs to specify how to queue the message.
+     * Set expandPromptTemplates to dispatch extension commands and expand skill commands and prompt templates.
      */
     sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
         deliverAs?: "steer" | "followUp";
+        expandPromptTemplates?: boolean;
     }): void;
     /** Append a custom entry to the session for state persistence (not sent to LLM). */
     appendEntry<T = unknown>(customType: string, data?: T): void;
@@ -855,9 +945,25 @@ export interface ExtensionAPI {
     setLabel(entryId: string, label: string | undefined): void;
     /** Execute a shell command. */
     exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+    /**
+     * Set an environment variable for subprocesses spawned by this session.
+     *
+     * Applies to the `bash` tool and to `pi.exec()`. The value is scoped to the
+     * session and is never written to `process.env`, so it cannot leak into
+     * other sessions or into mcpi itself.
+     */
+    setEnv(key: string, value: string): void;
+    /**
+     * Remove an environment variable from subprocesses spawned by this session.
+     *
+     * This masks the variable even when it is inherited from mcpi's own
+     * environment, so it can be used to keep a variable out of subprocesses
+     * entirely rather than only undoing a previous `setEnv()`.
+     */
+    unsetEnv(key: string): void;
     /** Get the list of currently active tool names. */
     getActiveTools(): string[];
-    /** Get all configured tools with parameter schema and source metadata. */
+    /** Get all configured tools with parameter schema, prompt guidelines, and source metadata. */
     getAllTools(): ToolInfo[];
     /** Set the active tools by name. */
     setActiveTools(toolNames: string[]): void;
@@ -886,7 +992,7 @@ export interface ExtensionAPI {
      * // Register a new provider with custom models
      * pi.registerProvider("my-proxy", {
      *   baseUrl: "https://proxy.example.com",
-     *   apiKey: "PROXY_API_KEY",
+     *   apiKey: "$PROXY_API_KEY",
      *   api: "anthropic-messages",
      *   models: [
      *     {
@@ -921,6 +1027,7 @@ export interface ExtensionAPI {
      *   }
      * });
      */
+    registerProvider(provider: Provider): void;
     registerProvider(name: string, config: ProviderConfig): void;
     /**
      * Unregister a previously registered provider.
@@ -941,13 +1048,20 @@ 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). */
+    /** API key literal, env interpolation ($ENV_VAR or ${ENV_VAR}), or leading !command. Required when defining models (unless oauth provided). */
     apiKey?: string;
     /** API type. Required at provider or model level when defining models. */
     api?: Api;
-    /** Optional streamSimple handler for custom APIs. */
+    /**
+     * Optional streamSimple handler for custom APIs.
+     * 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.
+     */
     streamSimple?: (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
     /** Custom headers to include in requests. */
     headers?: Record<string, string>;
@@ -955,17 +1069,26 @@ export interface ProviderConfig {
     authHeader?: boolean;
     /** Models to register. If provided, replaces all existing models for this provider. */
     models?: ProviderModelConfig[];
+    /**
+     * Refresh this provider's model list. The returned list replaces extension-provided models.
+     * 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;
-        /** Optional: modify models for this provider (e.g., update baseUrl based on credentials). */
+        /** Legacy synchronous credential-dependent model projection. */
         modifyModels?(models: Model<Api>[], credentials: OAuthCredentials): Model<Api>[];
     };
 }
@@ -977,17 +1100,16 @@ 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 mcpi 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). */
-    cost: {
-        input: number;
-        output: number;
-        cacheRead: number;
-        cacheWrite: number;
-    };
+    /** Per-million-token cost rates and optional request-wide input pricing tiers. */
+    cost: Model<Api>["cost"];
     /** Maximum context window size in tokens. */
     contextWindow: number;
     /** Maximum output tokens. */
@@ -999,6 +1121,13 @@ export interface ProviderModelConfig {
 }
 /** 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. */
+    name: string;
+    factory: ExtensionFactory;
+    /** Omit this extension from the startup Extensions list. */
+    hidden?: boolean;
+};
 export interface RegisteredTool {
     definition: ToolDefinition;
     sourceInfo: SourceInfo;
@@ -1023,13 +1152,14 @@ export type SendMessageHandler = <T = unknown>(message: Pick<CustomMessage<T>, "
 }) => void;
 export type SendUserMessageHandler = (content: string | (TextContent | ImageContent)[], options?: {
     deliverAs?: "steer" | "followUp";
+    expandPromptTemplates?: boolean;
 }) => void;
 export type AppendEntryHandler = <T = unknown>(customType: string, data?: T) => void;
 export type SetSessionNameHandler = (name: string) => void;
 export type GetSessionNameHandler = () => string | undefined;
 export type GetActiveToolsHandler = () => string[];
-/** Tool info with name, description, parameter schema, and source metadata */
-export type ToolInfo = Pick<ToolDefinition, "name" | "description" | "parameters"> & {
+/** Tool info with name, description, parameter schema, prompt guidelines, and source metadata. */
+export type ToolInfo = Pick<ToolDefinition, "name" | "description" | "parameters" | "promptGuidelines"> & {
     sourceInfo: SourceInfo;
 };
 export type GetAllToolsHandler = () => ToolInfo[];
@@ -1046,18 +1176,29 @@ export type SetLabelHandler = (entryId: string, label: string | undefined) => vo
  */
 export interface ExtensionRuntimeState {
     flagValues: Map<string, boolean | string>;
-    /** Session-scoped env vars for agent-spawned subprocesses. */
-    sessionEnv: Map<string, string>;
-    /** Provider registrations queued during extension loading, processed when runner binds */
+    /**
+     * Session-scoped environment mutations applied to spawned subprocesses.
+     * `null` masks a variable inherited from mcpi's own environment.
+     * Shared across all extensions loaded into the session.
+     */
+    sessionEnv: Map<string, string | null>;
+    /** Legacy provider-config registrations queued during extension loading, processed when runner binds. */
     pendingProviderRegistrations: Array<{
         name: string;
         config: ProviderConfig;
         extensionPath: string;
     }>;
+    /** Native mcpi-ai provider registrations queued during extension loading, processed when runner binds. */
+    pendingNativeProviderRegistrations: Array<{
+        provider: Provider;
+        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;
+    /** Retain an event-bus subscription until this runtime is invalidated. */
+    trackEventBusSubscription: (unsubscribe: () => void) => () => void;
     /**
      * Register or unregister a provider.
      *
@@ -1065,6 +1206,7 @@ export interface ExtensionRuntimeState {
      * After bindCore(): calls ModelRegistry directly for immediate effect.
      */
     registerProvider: (name: string, config: ProviderConfig, extensionPath?: string) => void;
+    registerNativeProvider: (provider: Provider, extensionPath?: string) => void;
     unregisterProvider: (name: string, extensionPath?: string) => void;
 }
 /**
@@ -1093,7 +1235,9 @@ export interface ExtensionActions {
  */
 export interface ExtensionContextActions {
     getModel: () => Model<any> | undefined;
+    getScopedModels: () => readonly ScopedModel[];
     isIdle: () => boolean;
+    isProjectTrusted: () => boolean;
     getSignal: () => AbortSignal | undefined;
     abort: () => void;
     hasPendingMessages: () => boolean;
@@ -1101,6 +1245,7 @@ export interface ExtensionContextActions {
     getContextUsage: () => ContextUsage | undefined;
     compact: (options?: CompactOptions) => void;
     getSystemPrompt: () => string;
+    getSystemPromptOptions?: () => BuildSystemPromptOptions;
 }
 /**
  * Actions for ExtensionCommandContext (ctx.* in command handlers).
@@ -1146,10 +1291,13 @@ export interface ExtensionRuntime extends ExtensionRuntimeState, ExtensionAction
 export interface Extension {
     path: string;
     resolvedPath: string;
+    hidden?: boolean;
     sourceInfo: SourceInfo;
     handlers: Map<string, HandlerFn[]>;
     tools: Map<string, RegisteredTool>;
     messageRenderers: Map<string, MessageRenderer>;
+    markdownTransformer?: MarkdownTransformer;
+    entryRenderers?: Map<string, EntryRenderer>;
     commands: Map<string, RegisteredCommand>;
     flags: Map<string, ExtensionFlag>;
     shortcuts: Map<KeyId, ExtensionShortcut>;