@relay-harness/coding-agent 0.0.0-stage → 1.0.3

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

@@ -0,0 +1,1720 @@
+/**
+ * Extension system types.
+ *
+ * Extensions are TypeScript modules that can:
+ * - Subscribe to agent lifecycle events
+ * - Register LLM-callable tools
+ * - Register commands, keyboard shortcuts, and CLI flags
+ * - Interact with the user via UI primitives
+ */
+import type { AgentMessage, AgentTool, AgentToolCallOutcome, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode } from "@relay-harness/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 "@relay-harness/ai";
+import type { AutocompleteItem, AutocompleteProvider, Component, EditorComponent, EditorTheme, KeyId, OverlayHandle, OverlayOptions, TUI } from "@relay-harness/tui";
+import type { Static, TSchema } from "typebox";
+import type { Theme } from "../../modes/interactive/theme/theme.ts";
+import type { BashResult } from "../bash-executor.ts";
+import type { CacheWarmingDecisionEvent, CacheWarmingDecisionEventResult } from "../cache-warmer.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 { 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 { 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 };
+export type { AppKeybinding, KeybindingsManager } from "../keybindings.ts";
+/** Options for extension UI dialogs. */
+export interface ExtensionUIDialogOptions {
+    /** AbortSignal to programmatically dismiss the dialog. */
+    signal?: AbortSignal;
+    /** Timeout in milliseconds. Dialog auto-dismisses with live countdown display. */
+    timeout?: number;
+}
+/** Placement for extension widgets. */
+export type WidgetPlacement = "aboveEditor" | "belowEditor";
+/** Options for extension widgets. */
+export interface ExtensionWidgetOptions {
+    /** Where the widget is rendered. Defaults to "aboveEditor". */
+    placement?: WidgetPlacement;
+}
+/** Raw terminal input listener for extensions. */
+export type TerminalInputHandler = (data: string) => {
+    consume?: boolean;
+    data?: string;
+} | undefined;
+/** Working indicator configuration for the interactive streaming loader. */
+export interface WorkingIndicatorOptions {
+    /** Animation frames. Use an empty array to hide the indicator entirely. Custom frames are rendered verbatim. */
+    frames?: string[];
+    /** Frame interval in milliseconds for animated indicators. */
+    intervalMs?: number;
+}
+/** Wrap the current autocomplete provider with additional behavior. */
+export type AutocompleteProviderFactory = (current: AutocompleteProvider) => AutocompleteProvider;
+export type EditorFactory = (tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) => EditorComponent;
+/**
+ * UI context for extensions to request interactive UI.
+ * Each mode (interactive, RPC, print) provides its own implementation.
+ */
+export interface ExtensionUIContext {
+    /** Show a selector and return the user's choice. */
+    select(title: string, options: string[], opts?: ExtensionUIDialogOptions): Promise<string | undefined>;
+    /** Show a confirmation dialog. */
+    confirm(title: string, message: string, opts?: ExtensionUIDialogOptions): Promise<boolean>;
+    /** Show a text input dialog. */
+    input(title: string, placeholder?: string, opts?: ExtensionUIDialogOptions): Promise<string | undefined>;
+    /** Show a notification to the user. */
+    notify(message: string, type?: "info" | "warning" | "error"): void;
+    /** Listen to raw terminal input (interactive mode only). Returns an unsubscribe function. */
+    onTerminalInput(handler: TerminalInputHandler): () => void;
+    /** Set status text in the footer/status bar. Pass undefined to clear. */
+    setStatus(key: string, text: string | undefined): void;
+    /** Set the working/loading message shown during streaming. Call with no argument to restore default. */
+    setWorkingMessage(message?: string): void;
+    /** Show or hide the built-in interactive working loader row during streaming. */
+    setWorkingVisible(visible: boolean): void;
+    /**
+     * Configure the interactive working indicator shown during streaming.
+     *
+     * - Omit the argument to restore the default animated spinner.
+     * - Use `frames: ["●"]` for a static indicator.
+     * - Use `frames: []` to hide the indicator entirely.
+     * - Custom frames are rendered as provided, so extensions must add their own colors.
+     */
+    setWorkingIndicator(options?: WorkingIndicatorOptions): void;
+    /** Set the label shown for hidden thinking blocks. Call with no argument to restore default. */
+    setHiddenThinkingLabel(label?: string): void;
+    /** Set a widget to display above or below the editor. Accepts string array or component factory. */
+    setWidget(key: string, content: string[] | undefined, options?: ExtensionWidgetOptions): void;
+    setWidget(key: string, content: ((tui: TUI, theme: Theme) => Component & {
+        dispose?(): void;
+    }) | undefined, options?: ExtensionWidgetOptions): void;
+    /** 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(). 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;
+    }) | undefined): void;
+    /** Set a custom header component (shown at startup, above chat), or undefined to restore the built-in header. */
+    setHeader(factory: ((tui: TUI, theme: Theme) => Component & {
+        dispose?(): void;
+    }) | undefined): void;
+    /** Set the terminal window/tab title. */
+    setTitle(title: string): void;
+    /** Show a custom component with keyboard focus. */
+    custom<T>(factory: (tui: TUI, theme: Theme, keybindings: KeybindingsManager, done: (result: T) => void) => (Component & {
+        dispose?(): void;
+    }) | Promise<Component & {
+        dispose?(): void;
+    }>, options?: {
+        overlay?: boolean;
+        /** Overlay positioning/sizing options. Can be static or a function for dynamic updates. */
+        overlayOptions?: OverlayOptions | (() => OverlayOptions);
+        /** Called with the overlay handle after the overlay is shown. Use to control visibility. */
+        onHandle?: (handle: OverlayHandle) => void;
+    }): Promise<T>;
+    /** Paste text into the editor, triggering paste handling (collapse for large content). */
+    pasteToEditor(text: string): void;
+    /** Set the text in the core input editor. */
+    setEditorText(text: string): void;
+    /** Get the current text from the core input editor. */
+    getEditorText(): string;
+    /** Show a multi-line editor for text editing. */
+    editor(title: string, prefill?: string): Promise<string | undefined>;
+    /** Stack additional autocomplete behavior on top of the built-in provider. */
+    addAutocompleteProvider(factory: AutocompleteProviderFactory): void;
+    /**
+     * Set a custom editor component via factory function.
+     * Pass undefined to restore the default editor.
+     *
+     * The factory receives:
+     * - `theme`: EditorTheme for styling borders and autocomplete
+     * - `keybindings`: KeybindingsManager for app-level keybindings
+     *
+     * For full app keybinding support (escape, ctrl+d, model switching, etc.),
+     * extend `CustomEditor` from `@relay-harness/coding-agent` and call
+     * `super.handleInput(data)` for keys you don't handle.
+     *
+     * @example
+     * ```ts
+     * import { CustomEditor } from "@relay-harness/coding-agent";
+     *
+     * class VimEditor extends CustomEditor {
+     *   private mode: "normal" | "insert" = "insert";
+     *
+     *   handleInput(data: string): void {
+     *     if (this.mode === "normal") {
+     *       // Handle vim normal mode keys...
+     *       if (data === "i") { this.mode = "insert"; return; }
+     *     }
+     *     super.handleInput(data);  // App keybindings + text editing
+     *   }
+     * }
+     *
+     * ctx.ui.setEditorComponent((tui, theme, keybindings) =>
+     *   new VimEditor(tui, theme, keybindings)
+     * );
+     * ```
+     */
+    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. */
+    getAllThemes(): {
+        name: string;
+        path: string | undefined;
+    }[];
+    /** Load a theme by name without switching to it. Returns undefined if not found. */
+    getTheme(name: string): Theme | undefined;
+    /** Set the current theme by name or Theme object. */
+    setTheme(theme: string | Theme): {
+        success: boolean;
+        error?: string;
+    };
+    /** Get current tool output expansion state. */
+    getToolsExpanded(): boolean;
+    /** Set tool output expansion state. */
+    setToolsExpanded(expanded: boolean): void;
+}
+export interface ContextUsage {
+    /** Estimated context tokens, or null if unknown (e.g. right after compaction, before next LLM response). */
+    tokens: number | null;
+    contextWindow: number;
+    /** Context usage as percentage of context window, or null if tokens is unknown. */
+    percent: number | null;
+}
+export interface CompactOptions {
+    customInstructions?: string;
+    onComplete?: (result: CompactionResult) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Context passed to extension event handlers.
+ */
+export type ExtensionMode = "tui" | "rpc" | "json" | "print";
+export interface ExtensionContext {
+    /** UI methods for user interaction */
+    ui: ExtensionUIContext;
+    /** 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;
+    /** Session manager (read-only) */
+    sessionManager: ReadonlySessionManager;
+    /** Model registry for API key resolution */
+    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 relay and exit. Available in all contexts. */
+    shutdown(): void;
+    /** Get current context usage for the active model. */
+    getContextUsage(): ContextUsage | undefined;
+    /** Trigger compaction without awaiting completion. */
+    compact(options?: CompactOptions): void;
+    /** 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.
+ */
+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. */
+    newSession(options?: {
+        parentSession?: string;
+        setup?: (sessionManager: SessionManager) => Promise<void>;
+        withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
+    }): Promise<{
+        cancelled: boolean;
+    }>;
+    /** Fork from a specific entry, creating a new session file. */
+    fork(entryId: string, options?: {
+        position?: "before" | "at";
+        withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
+    }): Promise<{
+        cancelled: boolean;
+    }>;
+    /** Navigate to a different point in the session tree. */
+    navigateTree(targetId: string, options?: {
+        summarize?: boolean;
+        customInstructions?: string;
+        replaceInstructions?: boolean;
+        label?: string;
+    }): Promise<{
+        cancelled: boolean;
+    }>;
+    /** Switch to a different session file. */
+    switchSession(sessionPath: string, options?: {
+        withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
+    }): Promise<{
+        cancelled: boolean;
+    }>;
+    /** Reload extensions, skills, prompts, themes, and context files. */
+    reload(): Promise<void>;
+}
+/**
+ * Fresh command-capable context bound to the replacement session after a session switch.
+ *
+ * This is passed to `withSession()` callbacks on `newSession()`, `fork()`, and `switchSession()`.
+ */
+export interface ReplacedSessionContext extends ExtensionCommandContext {
+    sendMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">, options?: {
+        triggerTurn?: boolean;
+        deliverAs?: "steer" | "followUp" | "nextTurn";
+    }): Promise<void>;
+    sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
+        deliverAs?: "steer" | "followUp";
+        expandPromptTemplates?: boolean;
+    }): Promise<void>;
+}
+/** Rendering options for tool results */
+export interface ToolRenderResultOptions {
+    /** Whether the result view is expanded */
+    expanded: boolean;
+    /** Whether this is a partial/streaming result */
+    isPartial: boolean;
+}
+/** Context passed to tool renderers. */
+export interface ToolRenderContext<TState = any, TArgs = any> {
+    /** Current tool call arguments. Shared across call/result renders for the same tool call. */
+    args: TArgs;
+    /** Unique id for this tool execution. Stable across call/result renders for the same tool call. */
+    toolCallId: string;
+    /** Invalidate just this tool execution component for redraw. */
+    invalidate: () => void;
+    /** Previously returned component for this render slot, if any. */
+    lastComponent: Component | undefined;
+    /** Shared renderer state for this tool row. Initialized by tool-execution.ts. */
+    state: TState;
+    /** Working directory for this tool execution. */
+    cwd: string;
+    /** Whether the tool execution has started. */
+    executionStarted: boolean;
+    /** Whether the tool call arguments are complete. */
+    argsComplete: boolean;
+    /** Whether the tool result is partial/streaming. */
+    isPartial: boolean;
+    /** Whether the result view is expanded. */
+    expanded: boolean;
+    /** Whether inline images are currently shown in the TUI. */
+    showImages: boolean;
+    /** Whether the current result is an error. */
+    isError: boolean;
+}
+/**
+ * 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().
+ */
+export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = unknown, TState = any> {
+    /** Tool name (used in LLM tool calls) */
+    name: string;
+    /** Human-readable label for UI */
+    label: string;
+    /** Description for LLM */
+    description: string;
+    /** Optional one-line snippet for the Available tools section in the default system prompt. Custom tools are omitted from that section when this is not provided. */
+    promptSnippet?: string;
+    /** Optional guideline bullets appended to the default system prompt Guidelines section when this tool is active. */
+    promptGuidelines?: string[];
+    /** Parameter schema (TypeBox) */
+    parameters: TParams;
+    /** 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. */
+    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.
+     * - "parallel": this tool can execute concurrently with other tool calls.
+     *
+     * If omitted, the default execution mode applies.
+     */
+    executionMode?: ToolExecutionMode;
+    /** Execute the tool. */
+    execute(toolCallId: string, params: Static<TParams>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<TDetails> | undefined, ctx: 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.
+ *
+ * Use this when assigning a tool to a variable or passing it through arrays such
+ * as `customTools`, where contextual typing would otherwise widen params to
+ * `unknown`.
+ */
+export declare function defineTool<TParams extends TSchema, TDetails = unknown, TState = any>(tool: ToolDefinition<TParams, TDetails, TState>): ToolDefinition<TParams, TDetails, TState> & AnyToolDefinition;
+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";
+    cwd: string;
+    reason: "startup" | "reload";
+}
+/** Result from resources_discover event handler */
+export interface ResourcesDiscoverResult {
+    skillPaths?: string[];
+    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 `relay.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";
+    /** Why this session start happened. */
+    reason: "startup" | "reload" | "new" | "resume" | "fork";
+    /** 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";
+    reason: "new" | "resume";
+    targetSessionFile?: string;
+}
+/** Fired before forking a session (can be cancelled) */
+export interface SessionBeforeForkEvent {
+    type: "session_before_fork";
+    entryId: string;
+    position: "before" | "at";
+}
+/** Fired before context compaction (can be cancelled or customized) */
+export interface SessionBeforeCompactEvent {
+    type: "session_before_compact";
+    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 succeeds */
+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 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 before an extension runtime is torn down due to quit, reload, or session replacement. */
+export interface SessionShutdownEvent {
+    type: "session_shutdown";
+    reason: "quit" | "reload" | "new" | "resume" | "fork";
+    /** Destination session file when shutting down due to session replacement. */
+    targetSessionFile?: string;
+}
+/** Preparation data for tree navigation */
+export interface TreePreparation {
+    targetId: string;
+    oldLeafId: string | null;
+    commonAncestorId: string | null;
+    entriesToSummarize: SessionEntry[];
+    userWantsSummary: boolean;
+    /** Custom instructions for summarization */
+    customInstructions?: string;
+    /** If true, customInstructions replaces the default prompt instead of being appended */
+    replaceInstructions?: boolean;
+    /** Label to attach to the branch summary entry */
+    label?: string;
+}
+/** Fired before navigating in the session tree (can be cancelled) */
+export interface SessionBeforeTreeEvent {
+    type: "session_before_tree";
+    preparation: TreePreparation;
+    signal: AbortSignal;
+}
+/** Fired after navigating in the session tree */
+export interface SessionTreeEvent {
+    type: "session_tree";
+    newLeafId: string | null;
+    oldLeafId: string | null;
+    summaryEntry?: BranchSummaryEntry;
+    fromExtension?: boolean;
+}
+export type SessionEvent = SessionStartEvent | SessionInfoChangedEvent | SessionBeforeSwitchEvent | SessionBeforeForkEvent | SessionBeforeCompactEvent | SessionCompactEvent | SessionCompactFailedEvent | SessionShutdownEvent | SessionBeforeTreeEvent | SessionTreeEvent;
+/**
+ * Fired before each LLM call. Can modify messages.
+ *
+ * `messages` holds the conversation without system messages. The prompt and tool state
+ * belong to Relay: 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 Relay 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";
+    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";
+    status: number;
+    headers: Record<string, string>;
+}
+/** Fired for a parsed provider stream event before Relay 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";
+    /** The raw user prompt text (after expansion). */
+    prompt: string;
+    /** Images attached to the user prompt, if any. */
+    images?: ImageContent[];
+    /** The current system prompt, rendered from systemPromptOptions and earlier handler changes. */
+    readonly systemPrompt: string;
+    /** Mutable prompt sections. Later handlers observe mutations made by earlier handlers. */
+    systemPromptOptions: NormalizedBuildSystemPromptOptions;
+}
+/** Fired when an agent loop starts */
+export interface AgentStartEvent {
+    type: "agent_start";
+}
+/** Fired when an agent loop ends */
+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";
+}
+export type UIPromptKind = "select" | "confirm" | "input" | "editor" | "custom";
+/** Fired when Relay starts waiting on a blocking user-facing extension UI prompt. */
+export interface UIPromptStartEvent {
+    type: "ui_prompt_start";
+    reason: "ui_prompt";
+    kind: UIPromptKind;
+    title?: string;
+}
+/** Fired when Relay is no longer waiting on a blocking user-facing extension UI prompt. */
+export interface UIPromptEndEvent {
+    type: "ui_prompt_end";
+    reason: "ui_prompt";
+    kind: UIPromptKind;
+    title?: string;
+}
+/** Fired at the start of each turn */
+export interface TurnStartEvent {
+    type: "turn_start";
+    turnIndex: number;
+    timestamp: number;
+}
+/** Fired at the end of each turn */
+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 {
+    type: "message_start";
+    message: AgentMessage;
+}
+/** Fired during assistant message streaming with token-by-token updates */
+export interface MessageUpdateEvent {
+    type: "message_update";
+    message: AgentMessage;
+    assistantMessageEvent: AssistantMessageEvent;
+}
+/** Fired when a message ends */
+export interface MessageEndEvent {
+    type: "message_end";
+    message: AgentMessage;
+}
+/** Fired when a tool starts executing */
+export interface ToolExecutionStartEvent {
+    type: "tool_execution_start";
+    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 {
+    type: "tool_execution_update";
+    toolCallId: string;
+    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 {
+    type: "tool_execution_end";
+    toolCallId: string;
+    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 */
+export interface ModelSelectEvent {
+    type: "model_select";
+    model: Model<any>;
+    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";
+    /** The command to execute */
+    command: string;
+    /** True if !! prefix was used (excluded from LLM context) */
+    excludeFromContext: boolean;
+    /** Current working directory */
+    cwd: string;
+}
+/** Source of user input */
+export type InputSource = "interactive" | "rpc" | "extension";
+/** Fired when user input is received, before agent processing */
+export interface InputEvent {
+    type: "input";
+    /** The input text */
+    text: string;
+    /** Attached images, if any */
+    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 = {
+    action: "continue";
+} | {
+    action: "transform";
+    text: string;
+    images?: ImageContent[];
+} | {
+    action: "handled";
+};
+interface ToolCallEventBase {
+    type: "tool_call";
+    /**
+     * The call's id. For calls another tool made (with `parentToolCallId` set), relay 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;
+}
+export interface EditToolCallEvent extends ToolCallEventBase {
+    toolName: "edit";
+    input: EditToolInput;
+}
+export interface WriteToolCallEvent extends ToolCallEventBase {
+    toolName: "write";
+    input: WriteToolInput;
+}
+export interface GrepToolCallEvent extends ToolCallEventBase {
+    toolName: "grep";
+    input: GrepToolInput;
+}
+export interface FindToolCallEvent extends ToolCallEventBase {
+    toolName: "find";
+    input: FindToolInput;
+}
+export interface LsToolCallEvent extends ToolCallEventBase {
+    toolName: "ls";
+    input: LsToolInput;
+}
+export interface CustomToolCallEvent extends ToolCallEventBase {
+    toolName: string;
+    input: Record<string, unknown>;
+}
+/**
+ * Fired before a tool executes. Can block.
+ *
+ * `event.input` is mutable. Mutate it in place to patch tool arguments before execution.
+ * Later `tool_call` handlers see earlier mutations. No re-validation is performed after mutation.
+ */
+export type ToolCallEvent = BashToolCallEvent | 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;
+}
+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;
+}
+export interface EditToolResultEvent extends ToolResultEventBase {
+    toolName: "edit";
+    details: EditToolDetails | undefined;
+}
+export interface WriteToolResultEvent extends ToolResultEventBase {
+    toolName: "write";
+    details: undefined;
+}
+export interface GrepToolResultEvent extends ToolResultEventBase {
+    toolName: "grep";
+    details: GrepToolDetails | undefined;
+}
+export interface FindToolResultEvent extends ToolResultEventBase {
+    toolName: "find";
+    details: FindToolDetails | undefined;
+}
+export interface LsToolResultEvent extends ToolResultEventBase {
+    toolName: "ls";
+    details: LsToolDetails | undefined;
+}
+export interface CustomToolResultEvent extends ToolResultEventBase {
+    toolName: string;
+    details: unknown;
+}
+/** Fired after a tool executes. Can modify result. */
+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;
+export declare function isGrepToolResult(e: ToolResultEvent): e is GrepToolResultEvent;
+export declare function isFindToolResult(e: ToolResultEvent): e is FindToolResultEvent;
+export declare function isLsToolResult(e: ToolResultEvent): e is LsToolResultEvent;
+/**
+ * Type guard for narrowing ToolCallEvent by tool name.
+ *
+ * Built-in tools narrow automatically (no type params needed):
+ * ```ts
+ * if (isToolCallEventType("bash", event)) {
+ *   event.input.command;  // string
+ * }
+ * ```
+ *
+ * Custom tools require explicit type parameters:
+ * ```ts
+ * if (isToolCallEventType<"my_tool", MyToolInput>("my_tool", event)) {
+ *   event.input.action;  // typed
+ * }
+ * ```
+ *
+ * Note: Direct narrowing via `event.toolName === "bash"` doesn't work because
+ * 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;
+export declare function isToolCallEventType(toolName: "grep", event: ToolCallEvent): event is GrepToolCallEvent;
+export declare function isToolCallEventType(toolName: "find", event: ToolCallEvent): event is FindToolCallEvent;
+export declare function isToolCallEventType(toolName: "ls", event: ToolCallEvent): event is LsToolCallEvent;
+export declare function isToolCallEventType<TName extends string, TInput extends Record<string, unknown>>(toolName: TName, event: ToolCallEvent): event is ToolCallEvent & {
+    toolName: TName;
+    input: TInput;
+};
+/** Union of all event types */
+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 = {
+    /** Custom operations to use for execution */
+    operations: BashOperations;
+    result?: never;
+} | {
+    operations?: never;
+    /** 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;
+}
+export interface MessageEndEventResult {
+    /** Replace the finalized message. The replacement must keep the original message role. */
+    message?: AgentMessage;
+}
+export interface BeforeAgentStartEventResult {
+    message?: Pick<CustomMessage, "customType" | "content" | "display" | "details">;
+    /** Replace the complete system prompt for this turn. Later handlers observe this exact override. */
+    systemPrompt?: string;
+}
+export interface SessionBeforeSwitchResult {
+    cancel?: boolean;
+}
+export interface SessionBeforeForkResult {
+    cancel?: boolean;
+    skipConversationRestore?: boolean;
+}
+export interface SessionBeforeCompactResult {
+    cancel?: boolean;
+    compaction?: CompactionResult;
+}
+export interface SessionBeforeTreeResult {
+    cancel?: boolean;
+    summary?: {
+        summary: string;
+        details?: unknown;
+        usage?: Usage;
+    };
+    /** Override custom instructions for summarization */
+    customInstructions?: string;
+    /** Override whether customInstructions replaces the default prompt */
+    replaceInstructions?: boolean;
+    /** Override label to attach to the branch summary entry */
+    label?: string;
+}
+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;
+    description?: string;
+    getArgumentCompletions?: (argumentPrefix: string) => AutocompleteItem[] | null | Promise<AutocompleteItem[] | null>;
+    handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>;
+}
+export interface ResolvedCommand extends RegisteredCommand {
+    invocationName: string;
+}
+/** Handler function type for events */
+export type ExtensionHandler<E, R = undefined> = (event: E, ctx: ExtensionContext) => Promise<R | void> | R | void;
+/**
+ * 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;
+    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, 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;
+    on(event: "tool_execution_start", handler: ExtensionHandler<ToolExecutionStartEvent>): () => void;
+    on(event: "tool_execution_update", handler: ExtensionHandler<ToolExecutionUpdateEvent>): () => void;
+    on(event: "tool_execution_end", handler: ExtensionHandler<ToolExecutionEndEvent>): () => void;
+    on(event: "model_select", handler: ExtensionHandler<ModelSelectEvent>): () => void;
+    on(event: "thinking_level_select", handler: ExtensionHandler<ThinkingLevelSelectEvent>): () => void;
+    on(event: "tool_call", handler: ExtensionHandler<ToolCallEvent, ToolCallEventResult>): () => void;
+    on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): () => void;
+    on(event: "user_bash", handler: ExtensionHandler<UserBashEvent, UserBashEventResult>): () => void;
+    on(event: "input", handler: ExtensionHandler<InputEvent, InputEventResult>): () => void;
+    /** Register a tool that the LLM can call. */
+    registerTool<TParams extends TSchema = TSchema, TDetails = unknown, TState = any>(tool: ToolDefinition<TParams, TDetails, TState>): void;
+    /** Register a custom command. */
+    registerCommand(name: string, options: Omit<RegisteredCommand, "name" | "sourceInfo">): void;
+    /** Register a keyboard shortcut. */
+    registerShortcut(shortcut: KeyId, options: {
+        description?: string;
+        handler: (ctx: ExtensionContext) => Promise<void> | void;
+    }): void;
+    /** Register a CLI flag. */
+    registerFlag(name: string, options: {
+        description?: 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 custom renderer for CustomMessageEntry. */
+    registerMessageRenderer<T = unknown>(customType: string, renderer: MessageRenderer<T>): void;
+    /** Register a transformer for user and assistant Markdown before Relay 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;
+        deliverAs?: "steer" | "followUp" | "nextTurn";
+    }): void;
+    /**
+     * 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;
+    /** Set the session display name (shown in session selector). */
+    setSessionName(name: string): void;
+    /** Get the current session name, if set. */
+    getSessionName(): string | undefined;
+    /** Set or clear a label on an entry. Labels are user-defined markers for bookmarking/navigation. */
+    setLabel(entryId: string, label: string | undefined): void;
+    /** Execute a shell command. */
+    exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+    /** 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, exposure, and source metadata. */
+    getAllTools(): ToolInfo[];
+    /** 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[];
+    /**
+     * Set the model for the current session without changing the configured default for new sessions.
+     * Returns false if authentication is not configured for the model's provider.
+     */
+    setModel(model: Model<any>): Promise<boolean>;
+    /** Get current thinking level. */
+    getThinkingLevel(): ThinkingLevel;
+    /**
+     * Set the thinking level (clamped to model capabilities) for the current session without changing the configured default
+     * for new sessions.
+     */
+    setThinkingLevel(level: ThinkingLevel): void;
+    /**
+     * Register or override a model provider.
+     *
+     * If `models` is provided: replaces all existing models for this provider.
+     * If only `baseUrl` is provided: overrides the URL for existing models.
+     * If `oauth` is provided: registers OAuth provider for /login support.
+     * If `streamSimple` is provided: registers a custom API stream handler.
+     *
+     * During initial extension load this call is queued and applied once the
+     * runner has bound its context. After that it takes effect immediately, so
+     * it is safe to call from command handlers or event callbacks without
+     * requiring a `/reload`.
+     *
+     * @example
+     * // Register a new provider with custom models
+     * relay.registerProvider("my-proxy", {
+     *   baseUrl: "https://proxy.example.com",
+     *   apiKey: "$PROXY_API_KEY",
+     *   api: "anthropic-messages",
+     *   models: [
+     *     {
+     *       id: "claude-sonnet-4-20250514",
+     *       name: "Claude 4 Sonnet (proxy)",
+     *       reasoning: false,
+     *       input: ["text", "image"],
+     *       cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+     *       contextWindow: 200000,
+     *       maxTokens: 16384
+     *     }
+     *   ]
+     * });
+     *
+     * @example
+     * // Override baseUrl for an existing provider
+     * relay.registerProvider("anthropic", {
+     *   baseUrl: "https://proxy.example.com"
+     * });
+     *
+     * @example
+     * // Register provider with OAuth support
+     * relay.registerProvider("corporate-ai", {
+     *   baseUrl: "https://ai.corp.com",
+     *   api: "openai-responses",
+     *   models: [...],
+     *   oauth: {
+     *     name: "Corporate AI (SSO)",
+     *     async login(callbacks) { ... },
+     *     async refreshToken(credentials) { ... },
+     *     getApiKey(credentials) { return credentials.access; }
+     *   }
+     * });
+     */
+    registerProvider(provider: Provider): void;
+    registerProvider(name: string, config: ProviderConfig): void;
+    /**
+     * Unregister a previously registered provider.
+     *
+     * Removes all models belonging to the named provider and restores any
+     * built-in models that were overridden by it. Has no effect if the provider
+     * is not currently registered.
+     *
+     * Like `registerProvider`, this takes effect immediately when called after
+     * the initial load phase.
+     *
+     * @example
+     * relay.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
+     * relay.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 relay.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 relay.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 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.
+     * The context is a normalized transcript: read the prompt and tools from its system messages
+     * (`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. 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. */
+    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, 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>[];
+    };
+}
+interface ProviderModelConfigBase {
+    /** Model ID. */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** API type override for this model. */
+    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 relay 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;
+    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 = (relay: ExtensionAPI) => void | Promise<void>;
+export type InlineExtension = ExtensionFactory | {
+    /**
+     * 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, `relay 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;
+    sourceInfo: SourceInfo;
+}
+export interface ExtensionFlag {
+    name: string;
+    description?: string;
+    type: "boolean" | "string";
+    default?: boolean | string;
+    extensionPath: string;
+}
+export interface ExtensionShortcut {
+    shortcut: KeyId;
+    description?: string;
+    handler: (ctx: ExtensionContext) => Promise<void> | void;
+    extensionPath: string;
+}
+type HandlerFn = (...args: unknown[]) => Promise<unknown>;
+export type SendMessageHandler = <T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">, options?: {
+    triggerTurn?: boolean;
+    deliverAs?: "steer" | "followUp" | "nextTurn";
+}) => 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, 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;
+export type SetModelHandler = (model: Model<any>) => Promise<boolean>;
+export type GetThinkingLevelHandler = () => ThinkingLevel;
+export type SetThinkingLevelHandler = (level: ThinkingLevel) => void;
+export type SetLabelHandler = (entryId: string, label: string | undefined) => void;
+/**
+ * Shared state created by loader, used during registration and runtime.
+ * Contains flag values (defaults set during registration, CLI values set after).
+ */
+export interface ExtensionRuntimeState {
+    flagValues: Map<string, boolean | string>;
+    /** Legacy provider-config registrations queued during extension loading, processed when runner binds. */
+    pendingProviderRegistrations: Array<{
+        name: string;
+        config: ProviderConfig;
+        extensionPath: string;
+    }>;
+    /** Native relay-ai provider registrations queued during extension loading, processed when runner binds. */
+    pendingNativeProviderRegistrations: Array<{
+        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.
+     *
+     * Before bindCore(): queues registrations / removes from queue.
+     * 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;
+    /** Servers registered with `relay.registerMcpServer()`. */
+    mcpServers: McpServerRegistry;
+    registerVirtualModel: (definition: VirtualModelDefinition, extensionPath?: string) => void;
+    unregisterVirtualModel: (provider: string, id: string) => void;
+}
+/**
+ * Action implementations for relay.* API methods.
+ * Provided to runner.initialize(), copied into the shared runtime.
+ */
+export interface ExtensionActions {
+    sendMessage: SendMessageHandler;
+    sendUserMessage: SendUserMessageHandler;
+    appendEntry: AppendEntryHandler;
+    setSessionName: SetSessionNameHandler;
+    getSessionName: GetSessionNameHandler;
+    setLabel: SetLabelHandler;
+    getActiveTools: GetActiveToolsHandler;
+    getAllTools: GetAllToolsHandler;
+    getSettings: GetSettingsHandler;
+    setActiveTools: SetActiveToolsHandler;
+    refreshTools: RefreshToolsHandler;
+    getCommands: GetCommandsHandler;
+    setModel: SetModelHandler;
+    getThinkingLevel: GetThinkingLevelHandler;
+    setThinkingLevel: SetThinkingLevelHandler;
+}
+/**
+ * Actions for ExtensionContext (ctx.* in event handlers).
+ * Required by all modes.
+ */
+export interface ExtensionContextActions {
+    getModel: () => Model<any> | undefined;
+    getScopedModels: () => readonly ScopedModel[];
+    isIdle: () => boolean;
+    isProjectTrusted: () => boolean;
+    getSignal: () => AbortSignal | undefined;
+    abort: () => void;
+    hasPendingMessages: () => boolean;
+    shutdown: () => void;
+    getContextUsage: () => ContextUsage | undefined;
+    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).
+ * Only needed for interactive mode where extension commands are invokable.
+ */
+export interface ExtensionCommandContextActions {
+    waitForIdle: () => Promise<void>;
+    newSession: (options?: {
+        parentSession?: string;
+        setup?: (sessionManager: SessionManager) => Promise<void>;
+        withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
+    }) => Promise<{
+        cancelled: boolean;
+    }>;
+    fork: (entryId: string, options?: {
+        position?: "before" | "at";
+        withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
+    }) => Promise<{
+        cancelled: boolean;
+    }>;
+    navigateTree: (targetId: string, options?: {
+        summarize?: boolean;
+        customInstructions?: string;
+        replaceInstructions?: boolean;
+        label?: string;
+    }) => Promise<{
+        cancelled: boolean;
+    }>;
+    switchSession: (sessionPath: string, options?: {
+        withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
+    }) => Promise<{
+        cancelled: boolean;
+    }>;
+    reload: () => Promise<void>;
+}
+/**
+ * Full runtime = state + actions.
+ * Created by loader with throwing action stubs, completed by runner.initialize().
+ */
+export interface ExtensionRuntime extends ExtensionRuntimeState, ExtensionActions {
+}
+/** Loaded extension with all registered items. */
+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>;
+    shortcuts: Map<KeyId, ExtensionShortcut>;
+}
+/** Result of loading extensions. */
+export interface LoadExtensionsResult {
+    extensions: Extension[];
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+    warnings?: Array<{
+        path: string;
+        warning: string;
+    }>;
+    /** Shared runtime - actions are throwing stubs until runner.initialize() */
+    runtime: ExtensionRuntime;
+}
+export interface ExtensionError {
+    extensionPath: string;
+    event: string;
+    error: string;
+    stack?: string;
+}
+//# sourceMappingURL=types.d.ts.map