@github/copilot-sdk-darwin-x64 0.0.1 → 1.0.13-preview.6

package/copilot-sdk/types.d.ts

@@ -0,0 +1,2974 @@
+/**
+ * Type definitions for the Copilot SDK
+ */
+import type { Canvas } from "./canvas.js";
+import type { SessionFsProvider } from "./sessionFsProvider.js";
+import type { CopilotRequestHandler } from "./copilotRequestHandler.js";
+import type { PermissionRequest as GeneratedPermissionRequest, PermissionRequestedData as GeneratedPermissionRequestedData, PermissionRequestedEvent as GeneratedPermissionRequestedEvent, ReasoningSummary, SessionLimitsConfig, SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
+import type { CopilotSession } from "./session.js";
+import type { FactoryJsonSchema, JsonValue } from "./factory.js";
+import type { GitHubTokenAcquireRequest, GitHubTokenAcquireResult, GitHubTelemetryNotification, ModelBillingTokenPrices, OpenCanvasInstance, RemoteSessionMode, CurrentToolMetadata } from "./generated/rpc.js";
+import type { ToolSet } from "./toolSet.js";
+export type { RemoteSessionMode } from "./generated/rpc.js";
+export type { CurrentToolMetadata } from "./generated/rpc.js";
+export type { GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, } from "./generated/rpc.js";
+/**
+ * Arguments passed to a session's {@link GitHubTokenProvider}.
+ *
+ * The callback registration identifier is intentionally kept inside the SDK.
+ */
+export type GitHubTokenProviderArgs = Pick<GitHubTokenAcquireRequest, "host" | "sessionId" | "reason">;
+/** Tagged token or cancellation returned by a {@link GitHubTokenProvider}. */
+export type GitHubTokenProviderResult = GitHubTokenAcquireResult;
+/**
+ * Acquires a GitHub token for one session.
+ *
+ * A token result must include `expiresIn`: the positive number of seconds of
+ * remaining lifetime when the callback completes. Production GitHub tokens
+ * typically last eight hours. Initial cancellation, callback errors, and
+ * invalid token responses reject session creation or resume instead of falling
+ * back to ambient authentication.
+ */
+export type GitHubTokenProvider = (args: GitHubTokenProviderArgs) => GitHubTokenProviderResult | Promise<GitHubTokenProviderResult>;
+export type { ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, } from "./generated/rpc.js";
+export type SessionEvent = Exclude<GeneratedSessionEvent, {
+    type: "permission.requested";
+}> | PermissionRequestedEvent;
+export type { ReasoningSummary } from "./generated/session-events.js";
+export type { SessionFsProvider } from "./sessionFsProvider.js";
+export { createSessionFsAdapter } from "./sessionFsProvider.js";
+export type { SessionFsFileInfo } from "./sessionFsProvider.js";
+export type { SessionFsSqliteQueryResult } from "./sessionFsProvider.js";
+export type { SessionFsSqliteQueryType } from "./sessionFsProvider.js";
+export type { SessionFsSqliteProvider } from "./sessionFsProvider.js";
+export type { SessionFsSqliteStatement } from "./sessionFsProvider.js";
+export type { SessionFsSqliteTransactionErrorClass } from "./sessionFsProvider.js";
+export { SessionFsSqliteTransactionFailure } from "./sessionFsProvider.js";
+export type { LlmInferenceHeaders } from "./generated/rpc.js";
+export type { PermissionDecisionContext, PermissionDecisionOutcome, PermissionDecisionSource, PermissionDecisionSurface, PermissionResponseCapability, } from "./generated/rpc.js";
+export type { CopilotRequestContext } from "./copilotRequestHandler.js";
+export { CopilotRequestHandler, CopilotWebSocketHandler, CopilotWebSocketCloseStatus, CopilotWebSocketForwarder, } from "./copilotRequestHandler.js";
+/**
+ * Options for creating a CopilotClient
+ */
+/**
+ * W3C Trace Context headers used for distributed trace propagation.
+ */
+export interface TraceContext {
+    traceparent?: string;
+    tracestate?: string;
+}
+/**
+ * Callback that returns the current W3C Trace Context.
+ * Wire this up to your OpenTelemetry (or other tracing) SDK to enable
+ * distributed trace propagation between your app and the Copilot CLI.
+ */
+export type TraceContextProvider = () => TraceContext | Promise<TraceContext>;
+/**
+ * Configuration for OpenTelemetry instrumentation.
+ *
+ * When provided via {@link CopilotClientOptions.telemetry}, the SDK sets
+ * the corresponding environment variables on the spawned CLI process so
+ * that the CLI's built-in OTel exporter is configured automatically.
+ */
+export interface TelemetryConfig {
+    /** OTLP HTTP endpoint URL for trace/metric export. Sets OTEL_EXPORTER_OTLP_ENDPOINT. */
+    otlpEndpoint?: string;
+    /** OTLP HTTP protocol for all signals. Sets OTEL_EXPORTER_OTLP_PROTOCOL. */
+    otlpProtocol?: "http/json" | "http/protobuf";
+    /** File path for JSON-lines trace output. Sets COPILOT_OTEL_FILE_EXPORTER_PATH. */
+    filePath?: string;
+    /** Exporter backend type: "otlp-http" or "file". Sets COPILOT_OTEL_EXPORTER_TYPE. */
+    exporterType?: string;
+    /** Instrumentation scope name. Sets COPILOT_OTEL_SOURCE_NAME. */
+    sourceName?: string;
+    /** Whether to capture message content (prompts, responses). Sets OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT. */
+    captureContent?: boolean;
+}
+/**
+ * Configures how a {@link CopilotClient} connects to the Copilot runtime.
+ * Construct via the factory functions on {@link RuntimeConnection}.
+ */
+export type RuntimeConnection = StdioRuntimeConnection | InProcessRuntimeConnection | TcpRuntimeConnection | UriRuntimeConnection;
+/**
+ * Shared shape for the transports that spawn a runtime **child process**
+ * ({@link StdioRuntimeConnection} and {@link TcpRuntimeConnection}).
+ */
+export interface ChildProcessRuntimeConnection {
+    /** Path to the runtime executable. When omitted, the bundled runtime is used. */
+    readonly path?: string;
+    /** Extra command-line arguments to pass to the runtime process. */
+    readonly args?: readonly string[];
+    /**
+     * Environment variables for the spawned runtime child process, replacing the
+     * inherited environment. Cannot be combined with
+     * {@link CopilotClientOptions.env}; setting both throws when the client is
+     * constructed. When omitted, the client-level env (or `process.env`) is used.
+     */
+    readonly env?: Record<string, string>;
+}
+/**
+ * Spawns a runtime child process and communicates over its stdin/stdout.
+ * This is the default if no {@link CopilotClientOptions.connection} is set.
+ */
+export interface StdioRuntimeConnection extends ChildProcessRuntimeConnection {
+    readonly kind: "stdio";
+}
+/**
+ * Hosts the runtime in-process by loading the native runtime library and speaking
+ * JSON-RPC over its C ABI (FFI), instead of spawning a runtime child process. The
+ * native host spawns the CLI worker itself. Construct via
+ * {@link RuntimeConnection.forInProcess}.
+ *
+ * @experimental The in-process (FFI) transport is experimental and its behavior may
+ * change. Per-client options that are lowered to environment variables — including
+ * {@link CopilotClientOptions.env}, {@link CopilotClientOptions.telemetry},
+ * {@link CopilotClientOptions.gitHubToken}, and
+ * {@link CopilotClientOptions.baseDirectory} — are **not** honored with this
+ * transport, because the native runtime loads into the shared host process and its
+ * worker inherits that process's ambient environment. To configure the in-process
+ * runtime, set the corresponding environment variables on the host process before
+ * constructing the client. See https://github.com/github/copilot-sdk/issues/1934.
+ */
+export interface InProcessRuntimeConnection {
+    readonly kind: "inprocess";
+}
+/**
+ * Spawns a runtime child process that listens on a TCP socket and connects to it.
+ */
+export interface TcpRuntimeConnection extends ChildProcessRuntimeConnection {
+    readonly kind: "tcp";
+    /**
+     * TCP port to listen on. `0` (the default) auto-allocates a free port.
+     * If the chosen port is already in use, startup fails.
+     */
+    readonly port?: number;
+    /**
+     * Optional shared secret the SDK sends to the spawned runtime to authenticate
+     * the TCP connection. When omitted, a UUID is generated automatically so the
+     * loopback listener is safe by default.
+     */
+    readonly connectionToken?: string;
+}
+/**
+ * Connects to an already-running runtime at the specified URL. The SDK does not
+ * spawn a process in this mode.
+ */
+export interface UriRuntimeConnection {
+    readonly kind: "uri";
+    /**
+     * URL of the runtime to connect to. Accepts `"port"`, `"host:port"`, or a
+     * full URL (`"http://host:port"`).
+     */
+    readonly url: string;
+    /** Optional shared secret to authenticate the connection. */
+    readonly connectionToken?: string;
+}
+/** Factory functions for constructing {@link RuntimeConnection} instances. */
+export declare const RuntimeConnection: {
+    /**
+     * Spawn a runtime child process and communicate over its stdin/stdout.
+     * This is the default if no {@link CopilotClientOptions.connection} is set.
+     */
+    readonly forStdio: (opts?: {
+        path?: string;
+        args?: readonly string[];
+        env?: Record<string, string>;
+    }) => StdioRuntimeConnection;
+    /**
+     * Spawn a runtime child process that listens on a TCP socket and connect to it.
+     */
+    readonly forTcp: (opts?: {
+        port?: number;
+        connectionToken?: string;
+        path?: string;
+        args?: readonly string[];
+        env?: Record<string, string>;
+    }) => TcpRuntimeConnection;
+    /**
+     * Connect to an already-running runtime at the given URL. The SDK does not
+     * spawn a process in this mode.
+     */
+    readonly forUri: (url: string, opts?: {
+        connectionToken?: string;
+    }) => UriRuntimeConnection;
+    /**
+     * Host the runtime in-process over the native runtime library's C ABI (FFI).
+     *
+     * @experimental Per-client options lowered to environment variables (`env`,
+     * `telemetry`, `gitHubToken`, `baseDirectory`) are **not** honored in-process;
+     * the worker inherits the host process's ambient environment. Set the
+     * corresponding environment variables on the host process instead. See
+     * https://github.com/github/copilot-sdk/issues/1934.
+     */
+    readonly forInProcess: () => InProcessRuntimeConnection;
+};
+/**
+ * Controls SDK defaults for ambient features.
+ *
+ * - `"copilot-cli"` (default): Defaults equivalent to Copilot CLI. Useful when
+ *   building a coding agent that shares sessions with Copilot CLI. Do not use
+ *   this mode for server-based multi-user applications — the default coding
+ *   agent has tools and capabilities that operate across sessions and can
+ *   access the host OS environment.
+ * - `"empty"`: Disables optional features by default. The app must explicitly
+ *   opt into anything it needs. Required for any scenario where CLI-like
+ *   ambient behavior is unsafe (e.g. multi-user servers).
+ */
+export type CopilotClientMode = "empty" | "copilot-cli";
+export interface CopilotClientOptions {
+    /**
+     * How to connect to the Copilot runtime. When omitted, defaults to
+     * {@link RuntimeConnection.forStdio} with the bundled runtime.
+     */
+    connection?: RuntimeConnection;
+    /**
+     * Selects the SDK defaulting strategy. See {@link CopilotClientMode}.
+     *
+     * When set to `"empty"`, the SDK validates that the app has supplied the
+     * required configuration ({@link CopilotClientOptions.baseDirectory} or
+     * {@link CopilotClientOptions.sessionFs}, plus
+     * {@link SessionConfigBase.availableTools} on each session) and translates
+     * session creation requests into runtime options that flip tool filter
+     * precedence to deny-wins so exclusions are expressible.
+     *
+     * @default "copilot-cli"
+     */
+    mode?: CopilotClientMode;
+    /**
+     * Working directory for the runtime process.
+     * If not set, inherits the current process's working directory.
+     */
+    workingDirectory?: string;
+    /**
+     * Base directory for Copilot data (session state, config, etc.).
+     * Sets the COPILOT_HOME environment variable on the spawned runtime.
+     * When not set, the runtime defaults to ~/.copilot.
+     * Ignored when connecting to an existing runtime via {@link RuntimeConnection.forUri}.
+     */
+    baseDirectory?: string;
+    /**
+     * Absolute paths to trusted plugin directories bundled by the host.
+     * When non-empty, the complete set is registered with the runtime during
+     * startup before any sessions can be created.
+     */
+    builtinPluginDirectories?: readonly string[];
+    /**
+     * Log level for the Copilot runtime. When omitted, the runtime uses its
+     * own default (currently `"info"`).
+     */
+    logLevel?: "none" | "error" | "warning" | "info" | "debug" | "all";
+    /**
+     * Environment variables to pass to the runtime process. If not set, inherits process.env.
+     */
+    env?: Record<string, string | undefined>;
+    /**
+     * GitHub token to use for authentication.
+     * When provided, the token is passed to the runtime via environment variable.
+     * This takes priority over other authentication methods.
+     */
+    gitHubToken?: string;
+    /**
+     * Whether to use the logged-in user for authentication.
+     * When true, the runtime will attempt to use stored OAuth tokens or gh CLI auth.
+     * When false, only explicit tokens (gitHubToken or environment variables) are used.
+     * @default true (but defaults to false when gitHubToken is provided)
+     */
+    useLoggedInUser?: boolean;
+    /**
+     * Custom handler for listing available models.
+     * When provided, client.listModels() calls this handler instead of
+     * querying the runtime. Useful in BYOK mode to return models
+     * available from your custom provider.
+     */
+    onListModels?: () => Promise<ModelInfo[]> | ModelInfo[];
+    /**
+     * OpenTelemetry configuration for the runtime process.
+     * When provided, the corresponding OTel environment variables are set
+     * on the spawned runtime.
+     */
+    telemetry?: TelemetryConfig;
+    /**
+     * Advanced: callback that returns the current W3C Trace Context for distributed
+     * trace propagation.  Most users do not need this — the {@link telemetry} config
+     * alone is sufficient to collect traces from the CLI.
+     *
+     * This callback is only useful when your application creates its own
+     * OpenTelemetry spans and you want them to appear in the **same** distributed
+     * trace as the CLI's spans.  The SDK calls this before `session.create`,
+     * `session.resume`, and `session.send` RPCs to inject `traceparent`/`tracestate`
+     * into the request.
+     *
+     * @example
+     * ```typescript
+     * import { propagation, context } from "@opentelemetry/api";
+     *
+     * const client = new CopilotClient({
+     *   onGetTraceContext: () => {
+     *     const carrier: Record<string, string> = {};
+     *     propagation.inject(context.active(), carrier);
+     *     return carrier;
+     *   },
+     * });
+     * ```
+     */
+    onGetTraceContext?: TraceContextProvider;
+    /**
+     * Custom session filesystem provider.
+     * When provided, the client registers as the session filesystem provider
+     * on connection, routing all session-scoped file I/O through these callbacks
+     * instead of the server's default local filesystem storage.
+     */
+    sessionFs?: SessionFsConfig;
+    /**
+     * Custom handler for outbound model-layer requests (experimental).
+     *
+     * When provided, the client registers as the runtime's request handler
+     * on connection: every outbound model-layer request the runtime would
+     * otherwise have issued itself — plain HTTP, streaming SSE, and
+     * WebSocket — is dispatched back to the handler over JSON-RPC. The
+     * handler returns the response verbatim, exactly as if the runtime had
+     * issued the request itself.
+     *
+     * Subclass {@link CopilotRequestHandler} and override the hooks you need;
+     * an instance that overrides nothing is a transparent pass-through.
+     *
+     * v1 notes:
+     * - HTTP (buffered and streaming SSE) and WebSocket transports are all
+     *   intercepted. The handler receives a `transport` discriminator on the
+     *   {@link CopilotRequestContext} for both.
+     * - The handler is set process-globally on the runtime; the same
+     *   handler is invoked for every session created on this client.
+     *
+     * @experimental
+     */
+    requestHandler?: CopilotRequestHandler;
+    /**
+     * Experimental. Receives GitHub telemetry events the runtime forwards to
+     * this connection. When set, the client opts each session it creates or
+     * resumes into telemetry forwarding and dispatches each
+     * `gitHubTelemetry.event` notification to this connection-global handler;
+     * each {@link GitHubTelemetryNotification} carries its originating
+     * `sessionId`.
+     *
+     * @experimental
+     */
+    onGitHubTelemetry?: (notification: GitHubTelemetryNotification) => void | Promise<void>;
+    /**
+     * Server-wide idle timeout for sessions in seconds.
+     * Sessions without activity for this duration are automatically cleaned up.
+     * Set to 0 or omit to disable (sessions live indefinitely).
+     * Ignored when connecting to an existing runtime via {@link RuntimeConnection.forUri}.
+     * @default undefined (disabled)
+     */
+    sessionIdleTimeoutSeconds?: number;
+    /**
+     * Enable remote session support (Mission Control integration).
+     * When true, sessions in a GitHub repository working directory are
+     * accessible from GitHub web and mobile.
+     * Ignored when connecting to an existing runtime via {@link RuntimeConnection.forUri}.
+     * @default false
+     */
+    enableRemoteSessions?: boolean;
+}
+/**
+ * Configuration for creating a session
+ */
+export type ToolResultType = "success" | "failure" | "rejected" | "denied" | "timeout";
+export type ToolBinaryResult = {
+    data: string;
+    mimeType: string;
+    type: "image" | "resource";
+    description?: string;
+};
+export type ToolTelemetry = Record<string, Record<string, JsonValue> | undefined>;
+export type ToolResultObject = {
+    textResultForLlm: string;
+    binaryResultsForLlm?: ToolBinaryResult[];
+    resultType: ToolResultType;
+    error?: string;
+    sessionLog?: string;
+    toolTelemetry?: ToolTelemetry;
+    /**
+     * Names of tools returned by a tool-search tool.
+     */
+    toolReferences?: string[];
+};
+export type ToolResult = string | ToolResultObject;
+/**
+ * GitHub repository metadata to associate with a cloud session.
+ */
+export interface CloudSessionRepository {
+    owner: string;
+    name: string;
+    branch?: string;
+}
+/**
+ * Options for creating a remote session in the cloud.
+ */
+export interface CloudSessionOptions {
+    repository?: CloudSessionRepository;
+}
+/**
+ * Content block types within an MCP CallToolResult.
+ */
+type McpCallToolResultTextContent = {
+    type: "text";
+    text: string;
+};
+type McpCallToolResultImageContent = {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+type McpCallToolResultResourceContent = {
+    type: "resource";
+    resource: {
+        uri: string;
+        mimeType?: string;
+        text?: string;
+        blob?: string;
+    };
+};
+type McpCallToolResultContent = McpCallToolResultTextContent | McpCallToolResultImageContent | McpCallToolResultResourceContent;
+/**
+ * MCP-compatible CallToolResult type. Can be passed to
+ * {@link convertMcpCallToolResult} to produce a {@link ToolResultObject}.
+ */
+type McpCallToolResult = {
+    content: McpCallToolResultContent[];
+    isError?: boolean;
+};
+/**
+ * Converts an MCP CallToolResult into the SDK's ToolResultObject format.
+ */
+export declare function convertMcpCallToolResult(callResult: McpCallToolResult): ToolResultObject;
+export interface ToolInvocation {
+    sessionId: string;
+    toolCallId: string;
+    toolName: string;
+    arguments: unknown;
+    /**
+     * Snapshot of the session's currently initialized tools. Populated by the
+     * SDK only when this invocation targets the built-in tool-search tool
+     * (`tool_search_tool`), so a tool-search override can rank/filter the live
+     * catalog — including MCP tools configured in settings — without issuing its
+     * own RPC. `undefined` for every other tool invocation.
+     */
+    availableTools?: CurrentToolMetadata[];
+    /** W3C Trace Context traceparent from the CLI's execute_tool span. */
+    traceparent?: string;
+    /** W3C Trace Context tracestate from the CLI's execute_tool span. */
+    tracestate?: string;
+}
+export type ToolHandler<TArgs = unknown> = (args: TArgs, invocation: ToolInvocation) => Promise<unknown> | unknown;
+/**
+ * Zod-like schema interface for type inference.
+ * Any object with `toJSONSchema()` method is treated as a Zod schema.
+ */
+export interface ZodSchema<T = unknown> {
+    _output: T;
+    toJSONSchema(): Record<string, unknown>;
+}
+/**
+ * Tool definition. Parameters can be either:
+ * - A Zod schema (provides type inference for handler)
+ * - A raw JSON schema object
+ * - Omitted (no parameters)
+ *
+ * If `handler` is omitted, the SDK exposes the declaration but does not
+ * automatically invoke the tool. Consumers can resolve tool calls by observing
+ * external tool request events and calling the pending-tool RPC.
+ */
+export interface Tool<TArgs = unknown> {
+    name: string;
+    description?: string;
+    parameters?: ZodSchema<TArgs> | Record<string, unknown>;
+    handler?: ToolHandler<TArgs>;
+    /**
+     * When true, explicitly indicates this tool is intended to override a built-in tool
+     * of the same name. If not set and the name clashes with a built-in tool, the runtime
+     * will return an error.
+     */
+    overridesBuiltInTool?: boolean;
+    /**
+     * When true, the tool can execute without a permission prompt.
+     */
+    skipPermission?: boolean;
+    /**
+     * Controls whether the tool may be deferred (loaded lazily via tool search)
+     * rather than always pre-loaded. When `"auto"`, the tool can be deferred and
+     * surfaced through tool search. When `"never"`, the tool is always pre-loaded.
+     * Optional; defaults to `"auto"`.
+     */
+    defer?: "auto" | "never";
+    /**
+     * Opaque, host-defined metadata associated with the tool definition.
+     *
+     * Keys are namespaced and are not part of the stable public API. Values are
+     * not interpreted and may be recognized to inform host-specific behavior.
+     * Unknown keys are preserved and round-tripped untouched.
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * When true, a successful call to this tool ends the agent turn: the runtime's
+     * tool phase halts instead of feeding the tool result back to the model for
+     * another round. A failed call (for example input validation) leaves the loop
+     * running so the model can read the error and retry.
+     *
+     * Use this for tools whose whole purpose is to terminate the turn, such as a
+     * context clear that replaces the conversation the model would otherwise
+     * continue from.
+     */
+    isTerminal?: boolean;
+}
+/**
+ * Helper to define a tool with Zod schema and get type inference for the handler.
+ * Without this helper, TypeScript cannot infer handler argument types from Zod schemas.
+ */
+export declare function defineTool<T = unknown>(name: string, config: {
+    description?: string;
+    parameters?: ZodSchema<T> | Record<string, unknown>;
+    handler?: ToolHandler<T>;
+    overridesBuiltInTool?: boolean;
+    skipPermission?: boolean;
+    defer?: "auto" | "never";
+    metadata?: Record<string, unknown>;
+    isTerminal?: boolean;
+}): Tool<T>;
+/**
+ * SDK-supplied override for the runtime's built-in tool-search behavior.
+ *
+ * Tool search lets the model discover tools on demand instead of loading every
+ * tool definition up front. When the total tool count exceeds the deferral
+ * threshold, MCP and external tools are marked as deferred and surfaced through
+ * the built-in `tool_search_tool`.
+ *
+ * To override the tool-search tool's model-facing definition and/or its
+ * execution, register a {@link Tool} named `tool_search_tool` with
+ * `overridesBuiltInTool: true`. To customize the in-prompt tool-search
+ * guidance, use the `tool_instructions` section of {@link SystemMessageConfig}
+ * in `"customize"` mode.
+ */
+export interface ToolSearchConfig {
+    /**
+     * Toggle to enable/disable tool search. When disabled, all tools are pre-loaded
+     * and the model's active tool set is not deferred.
+     */
+    enabled?: boolean;
+    /**
+     * Overrides the total tool count at which MCP and external tools are
+     * automatically deferred behind tool search. Defaults to the built-in
+     * threshold (30) when omitted.
+     */
+    deferThreshold?: number;
+}
+/**
+ * Context passed to a command handler when a command is executed.
+ */
+export interface CommandContext {
+    /** Session ID where the command was invoked */
+    sessionId: string;
+    /** The full command text (e.g. "/deploy production") */
+    command: string;
+    /** Command name without leading / */
+    commandName: string;
+    /** Raw argument string after the command name */
+    args: string;
+}
+/**
+ * Handler invoked when a registered command is executed by a user.
+ */
+export type CommandHandler = (context: CommandContext) => Promise<void> | void;
+/**
+ * Definition of a slash command registered with the session.
+ * When the CLI is running with a TUI, registered commands appear as
+ * `/commandName` for the user to invoke.
+ */
+export interface CommandDefinition {
+    /** Command name (without leading /). */
+    name: string;
+    /** Human-readable description shown in command completion UI. */
+    description?: string;
+    /** Handler invoked when the command is executed. */
+    handler: CommandHandler;
+}
+/**
+ * Capabilities reported by the CLI host for this session.
+ */
+export interface SessionCapabilities {
+    ui?: {
+        /** Whether the host supports interactive elicitation dialogs. */
+        elicitation?: boolean;
+        /**
+         * Whether the runtime has accepted the session's MCP Apps (SEP-1865)
+         * opt-in. `true` when the consumer set `enableMcpApps: true` on
+         * create/resume **and** the runtime's `MCP_APPS` feature flag (or
+         * `COPILOT_MCP_APPS=true` env override) is on. Otherwise absent or
+         * `false`, indicating the runtime silently dropped the opt-in.
+         *
+         * @experimental This property is part of an experimental wire-protocol surface
+         * (SEP-1865) and may change or be removed in a future release.
+         */
+        mcpApps?: boolean;
+        /** Whether the host supports canvas rendering. */
+        canvases?: boolean;
+    };
+}
+/**
+ * A single field in an elicitation schema — matches the MCP SDK's
+ * `PrimitiveSchemaDefinition` union.
+ */
+export type ElicitationSchemaField = {
+    type: "string";
+    title?: string;
+    description?: string;
+    enum: string[];
+    enumNames?: string[];
+    default?: string;
+} | {
+    type: "string";
+    title?: string;
+    description?: string;
+    oneOf: {
+        const: string;
+        title: string;
+    }[];
+    default?: string;
+} | {
+    type: "array";
+    title?: string;
+    description?: string;
+    minItems?: number;
+    maxItems?: number;
+    items: {
+        type: "string";
+        enum: string[];
+    };
+    default?: string[];
+} | {
+    type: "array";
+    title?: string;
+    description?: string;
+    minItems?: number;
+    maxItems?: number;
+    items: {
+        anyOf: {
+            const: string;
+            title: string;
+        }[];
+    };
+    default?: string[];
+} | {
+    type: "boolean";
+    title?: string;
+    description?: string;
+    default?: boolean;
+} | {
+    type: "string";
+    title?: string;
+    description?: string;
+    minLength?: number;
+    maxLength?: number;
+    format?: "email" | "uri" | "date" | "date-time";
+    default?: string;
+} | {
+    type: "number" | "integer";
+    title?: string;
+    description?: string;
+    minimum?: number;
+    maximum?: number;
+    default?: number;
+};
+/**
+ * Schema describing the form fields for an elicitation request.
+ */
+export interface ElicitationSchema {
+    type: "object";
+    properties: Record<string, ElicitationSchemaField>;
+    required?: string[];
+}
+/**
+ * Primitive field value in an elicitation result.
+ * Matches MCP SDK's `ElicitResult.content` value type.
+ */
+export type ElicitationFieldValue = string | number | boolean | string[];
+/**
+ * Result returned from an elicitation request.
+ */
+export interface ElicitationResult {
+    /** User action: "accept" (submitted), "decline" (rejected), or "cancel" (dismissed). */
+    action: "accept" | "decline" | "cancel";
+    /** Form values submitted by the user (present when action is "accept"). */
+    content?: Record<string, ElicitationFieldValue>;
+}
+/**
+ * Parameters for a raw elicitation request.
+ */
+export interface ElicitationParams {
+    /** Message describing what information is needed from the user. */
+    message: string;
+    /** JSON Schema describing the form fields to present. */
+    requestedSchema: ElicitationSchema;
+}
+/**
+ * Context for an elicitation handler invocation, combining the request data
+ * with session context. Mirrors the single-argument pattern of {@link CommandContext}.
+ */
+export interface ElicitationContext {
+    /** Identifier of the session that triggered the elicitation request. */
+    sessionId: string;
+    /** Message describing what information is needed from the user. */
+    message: string;
+    /** JSON Schema describing the form fields to present. */
+    requestedSchema?: ElicitationSchema;
+    /** Elicitation mode: "form" for structured input, "url" for browser redirect. */
+    mode?: "form" | "url";
+    /** The source that initiated the request (e.g. MCP server name). */
+    elicitationSource?: string;
+    /** URL to open in the user's browser (url mode only). */
+    url?: string;
+}
+/**
+ * Handler invoked when the server dispatches an elicitation request to this client.
+ * Return an {@link ElicitationResult} with the user's response.
+ */
+export type ElicitationHandler = (context: ElicitationContext) => Promise<ElicitationResult> | ElicitationResult;
+/**
+ * Options for the `input()` convenience method.
+ */
+export interface UiInputOptions {
+    /** Title label for the input field. */
+    title?: string;
+    /** Descriptive text shown below the field. */
+    description?: string;
+    /** Minimum character length. */
+    minLength?: number;
+    /** Maximum character length. */
+    maxLength?: number;
+    /** Semantic format hint. */
+    format?: "email" | "uri" | "date" | "date-time";
+    /** Default value pre-populated in the field. */
+    default?: string;
+}
+/**
+ * The `session.ui` API object providing interactive UI methods.
+ * Only usable when the CLI host supports elicitation.
+ */
+export interface SessionUiApi {
+    /**
+     * Shows a generic elicitation dialog with a custom schema.
+     * @throws Error if the host does not support elicitation.
+     */
+    elicitation(params: ElicitationParams): Promise<ElicitationResult>;
+    /**
+     * Shows a confirmation dialog and returns the user's boolean answer.
+     * Returns `false` if the user declines or cancels.
+     * @throws Error if the host does not support elicitation.
+     */
+    confirm(message: string): Promise<boolean>;
+    /**
+     * Shows a selection dialog with the given options.
+     * Returns the selected value, or `null` if the user declines/cancels.
+     * @throws Error if the host does not support elicitation.
+     */
+    select(message: string, options: string[]): Promise<string | null>;
+    /**
+     * Shows a text input dialog.
+     * Returns the entered text, or `null` if the user declines/cancels.
+     * @throws Error if the host does not support elicitation.
+     */
+    input(message: string, options?: UiInputOptions): Promise<string | null>;
+}
+export interface ToolCallRequestPayload {
+    sessionId: string;
+    toolCallId: string;
+    toolName: string;
+    arguments: unknown;
+}
+export interface ToolCallResponsePayload {
+    result: ToolResult;
+}
+/**
+ * Known system message section identifiers for the "customize" mode.
+ * Each section corresponds to a distinct part of the system prompt.
+ */
+export type SystemMessageSection = "preamble" | "identity" | "tone" | "tool_efficiency" | "environment_context" | "code_change_rules" | "guidelines" | "safety" | "tool_instructions" | "custom_instructions" | "runtime_instructions" | "last_instructions";
+/** Section metadata for documentation and tooling. */
+export declare const SYSTEM_MESSAGE_SECTIONS: Record<SystemMessageSection, {
+    description: string;
+}>;
+/**
+ * Transform callback for a single section: receives current content, returns new content.
+ */
+export type SectionTransformFn = (currentContent: string) => string | Promise<string>;
+/**
+ * Override action: a string literal for static overrides, or a callback for transforms.
+ *
+ * - `"replace"`: Replace section content entirely
+ * - `"remove"`: Remove the section
+ * - `"append"`: Append to existing section content
+ * - `"prepend"`: Prepend to existing section content
+ * - `"preserve"`: No-op marker that opts an individually-addressable section out of a
+ *   group-level `"remove"` (e.g. keep `tone` when removing the `identity` group)
+ * - `function`: Transform callback — receives current section content, returns new content
+ */
+export type SectionOverrideAction = "replace" | "remove" | "append" | "prepend" | "preserve" | SectionTransformFn;
+/**
+ * Override operation for a single system message section.
+ */
+export interface SectionOverride {
+    /**
+     * The operation to perform on this section.
+     * Can be a string action or a transform callback function.
+     */
+    action: SectionOverrideAction;
+    /**
+     * Content for the override. Optional for all actions.
+     * - For replace, omitting content replaces with an empty string.
+     * - For append/prepend, content is added before/after the existing section.
+     * - Ignored for the remove action.
+     */
+    content?: string;
+}
+/**
+ * Append mode: Use CLI foundation with optional appended content (default).
+ */
+export interface SystemMessageAppendConfig {
+    mode?: "append";
+    /**
+     * Additional instructions appended after SDK-managed sections.
+     */
+    content?: string;
+}
+/**
+ * Replace mode: Use caller-provided system message entirely.
+ * Removes all SDK guardrails including security restrictions.
+ */
+export interface SystemMessageReplaceConfig {
+    mode: "replace";
+    /**
+     * Complete system message content.
+     * Replaces the entire SDK-managed system message.
+     */
+    content: string;
+}
+/**
+ * Customize mode: Override individual sections of the system prompt.
+ * Keeps the SDK-managed prompt structure while allowing targeted modifications.
+ */
+export interface SystemMessageCustomizeConfig {
+    mode: "customize";
+    /**
+     * Override specific sections of the system prompt by section ID.
+     * Unknown section IDs gracefully fall back: content-bearing overrides are appended
+     * to additional instructions, and "remove" on unknown sections is a silent no-op.
+     */
+    sections?: Partial<Record<SystemMessageSection, SectionOverride>>;
+    /**
+     * Additional content appended after all sections.
+     * Equivalent to append mode's content field — provided for convenience.
+     */
+    content?: string;
+}
+/**
+ * System message configuration for session creation.
+ * - Append mode (default): SDK foundation + optional custom content
+ * - Replace mode: Full control, caller provides entire system message
+ * - Customize mode: Section-level overrides with graceful fallback
+ */
+export type SystemMessageConfig = SystemMessageAppendConfig | SystemMessageReplaceConfig | SystemMessageCustomizeConfig;
+import type { PermissionDecisionRequest, PermissionDecisionContext } from "./generated/rpc.js";
+/**
+ * Permission request types from the server. This is the generated
+ * discriminated union from the runtime schema — switch on `kind` to
+ * access the variant-specific fields (e.g. shell `commands`, write
+ * `fileName`/`diff`, mcp `toolName`/`args`).
+ *
+ * `managedApprovalRequired` indicates that managed policy requires an explicit
+ * user decision. Hosts should bypass automatic approval and present their
+ * normal confirmation UI. The runtime currently emits it for managed Shell,
+ * Read, Edit, and Domain selector asks.
+ */
+export type PermissionRequest = GeneratedPermissionRequest & {
+    readonly managedApprovalRequired?: boolean;
+};
+export type PermissionRequestedData = Omit<GeneratedPermissionRequestedData, "permissionRequest"> & {
+    permissionRequest: PermissionRequest;
+};
+export type PermissionRequestedEvent = Omit<GeneratedPermissionRequestedEvent, "data"> & {
+    data: PermissionRequestedData;
+};
+/**
+ * Permission decision result returned from a {@link PermissionHandler}.
+ * The discriminated `kind` field selects the decision. Variant-specific
+ * fields (e.g. `feedback` on `{ kind: "reject" }`) come from the generated
+ * `PermissionDecisionRequest["result"]` union.
+ */
+export type PermissionRequestResult = PermissionDecisionRequest["result"] | {
+    kind: "no-result";
+};
+/**
+ * A {@link PermissionRequestResult} annotated with the
+ * {@link PermissionDecisionContext} describing how and where the decision was
+ * reached. The context is informational only — it never changes permission
+ * behavior. Supplying it lets the runtime attribute auto-approval telemetry to
+ * the responding surface.
+ */
+export interface AttributedPermissionResult {
+    kind: "attributed";
+    result: PermissionRequestResult;
+    decisionContext: PermissionDecisionContext;
+}
+/**
+ * Narrows a {@link PermissionHandler} return value to an attributed result.
+ */
+export declare function isAttributedPermissionResult(result: PermissionRequestResult | AttributedPermissionResult): result is AttributedPermissionResult;
+/**
+ * Pair a permission decision with the context describing how and where it was
+ * made, so the runtime can attribute auto-approval telemetry.
+ *
+ * Passing an already-attributed result replaces the previous context rather
+ * than nesting it. The context is informational only and never changes
+ * permission behavior.
+ */
+export declare function createAttributedPermissionResult(result: PermissionRequestResult | AttributedPermissionResult, decisionContext: PermissionDecisionContext): AttributedPermissionResult;
+export type PermissionHandler = (request: PermissionRequest, invocation: {
+    sessionId: string;
+    managedSettingsEnabled?: boolean;
+}) => Promise<PermissionRequestResult | AttributedPermissionResult> | PermissionRequestResult | AttributedPermissionResult;
+/**
+ * Approves permission requests when managed settings are disabled.
+ */
+export declare const approveAll: PermissionHandler;
+export declare const defaultJoinSessionPermissionHandler: PermissionHandler;
+/**
+ * Legacy question-and-answer request from the `ask_user` tool.
+ */
+export interface UserInputRequest {
+    /**
+     * The question to ask the user
+     */
+    question: string;
+    /**
+     * Optional choices for multiple choice questions
+     */
+    choices?: string[];
+    /**
+     * Whether to allow freeform text input in addition to choices
+     * @default true
+     */
+    allowFreeform?: boolean;
+}
+/**
+ * Response to a user input request
+ */
+export interface UserInputResponse {
+    /**
+     * The user's answer
+     */
+    answer: string;
+    /**
+     * Whether the answer was freeform (not from choices)
+     */
+    wasFreeform: boolean;
+}
+/**
+ * Handler for user input requests from the agent
+ */
+export type UserInputHandler = (request: UserInputRequest, invocation: {
+    sessionId: string;
+}) => Promise<UserInputResponse> | UserInputResponse;
+/**
+ * Request to exit plan mode and continue with a selected action.
+ */
+export interface ExitPlanModeRequest {
+    /** Summary of the plan or proposed next step. */
+    summary: string;
+    /** Full plan content, when available. */
+    planContent?: string;
+    /** Available actions the user can select. */
+    actions: string[];
+    /** The action recommended by the runtime. */
+    recommendedAction: string;
+}
+/**
+ * Response to an exit-plan-mode request.
+ */
+export interface ExitPlanModeResult {
+    /** Whether the user approved exiting plan mode. */
+    approved: boolean;
+    /** Selected action, if the user chose one. */
+    selectedAction?: string;
+    /** Optional feedback provided by the user. */
+    feedback?: string;
+}
+/**
+ * Handler for exit-plan-mode requests from the agent.
+ */
+export type ExitPlanModeHandler = (request: ExitPlanModeRequest, invocation: {
+    sessionId: string;
+}) => Promise<ExitPlanModeResult> | ExitPlanModeResult;
+/**
+ * Request to switch to auto mode after an eligible rate limit.
+ */
+export interface AutoModeSwitchRequest {
+    /** The rate-limit error code that triggered the request. */
+    errorCode?: string;
+    /** Seconds until the rate limit resets, when known. */
+    retryAfterSeconds?: number;
+}
+/**
+ * Response to an auto-mode-switch request.
+ */
+export type AutoModeSwitchResponse = "yes" | "yes_always" | "no";
+/**
+ * Handler for auto-mode-switch requests from the agent.
+ */
+export type AutoModeSwitchHandler = (request: AutoModeSwitchRequest, invocation: {
+    sessionId: string;
+}) => Promise<AutoModeSwitchResponse> | AutoModeSwitchResponse;
+/**
+ * Base interface for all hook inputs
+ */
+export interface BaseHookInput {
+    /** The runtime session ID of the session that triggered the hook.
+     * For sub-agent hooks this differs from `invocation.sessionId`. */
+    sessionId: string;
+    /** Time at which the hook event was emitted by the runtime. */
+    timestamp: Date;
+    workingDirectory: string;
+}
+/**
+ * Input for pre-tool-use hook
+ */
+export interface PreToolUseHookInput extends BaseHookInput {
+    toolName: string;
+    toolArgs: unknown;
+}
+/**
+ * Output for pre-tool-use hook
+ */
+export interface PreToolUseHookOutput {
+    permissionDecision?: "allow" | "deny" | "ask";
+    permissionDecisionReason?: string;
+    modifiedArgs?: unknown;
+    additionalContext?: string;
+    suppressOutput?: boolean;
+}
+/**
+ * Handler for pre-tool-use hook
+ */
+export type PreToolUseHandler = (input: PreToolUseHookInput, invocation: {
+    sessionId: string;
+}) => Promise<PreToolUseHookOutput | void> | PreToolUseHookOutput | void;
+/**
+ * Input for pre-MCP-tool-call hook
+ */
+export interface PreMcpToolCallHookInput extends BaseHookInput {
+    toolCallId?: string;
+    serverName: string;
+    toolName: string;
+    arguments: unknown;
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Output for pre-MCP-tool-call hook
+ */
+export interface PreMcpToolCallHookOutput {
+    /**
+     * Hook-controlled metadata to use for the outgoing MCP request.
+     * - undefined/absent: preserve the current request `_meta`
+     * - object: use this object as request `_meta`
+     * - null: omit `_meta`
+     */
+    metaToUse?: Record<string, unknown> | null;
+}
+/**
+ * Handler for pre-MCP-tool-call hook
+ */
+export type PreMcpToolCallHandler = (input: PreMcpToolCallHookInput, invocation: {
+    sessionId: string;
+}) => Promise<PreMcpToolCallHookOutput | void> | PreMcpToolCallHookOutput | void;
+/**
+ * Input for post-tool-use hook
+ */
+export interface PostToolUseHookInput extends BaseHookInput {
+    toolName: string;
+    toolArgs: unknown;
+    toolResult: ToolResultObject;
+}
+/**
+ * Output for post-tool-use hook
+ */
+export interface PostToolUseHookOutput {
+    modifiedResult?: ToolResultObject;
+    additionalContext?: string;
+    suppressOutput?: boolean;
+}
+/**
+ * Handler for post-tool-use hook
+ */
+export type PostToolUseHandler = (input: PostToolUseHookInput, invocation: {
+    sessionId: string;
+}) => Promise<PostToolUseHookOutput | void> | PostToolUseHookOutput | void;
+/**
+ * Input for post-tool-use-failure hook.
+ *
+ * Dispatched after a tool execution whose `resultType` is `"failure"`.
+ * The input differs from {@link PostToolUseHookInput}: the host CLI does not
+ * forward the full `ToolResultObject` to failure hooks — only `error`, the
+ * stringified failure message extracted from the tool's result, is provided.
+ */
+export interface PostToolUseFailureHookInput extends BaseHookInput {
+    toolName: string;
+    toolArgs: unknown;
+    /**
+     * Failure message from the tool's result (the `error` field of the
+     * underlying `ToolResultObject`, falling back to its text/log fields).
+     */
+    error: string;
+}
+/**
+ * Output for post-tool-use-failure hook.
+ *
+ * Only `additionalContext` is consumed by the host CLI — it is appended as
+ * hidden guidance to the model alongside the failed tool result. Other fields
+ * such as `modifiedResult` or `suppressOutput` are not honored for failure
+ * hooks (see {@link PostToolUseHookOutput} for the success-only hook).
+ */
+export interface PostToolUseFailureHookOutput {
+    additionalContext?: string;
+}
+/**
+ * Handler for post-tool-use-failure hook.
+ *
+ * Fires after a tool execution whose result was `"failure"`. `onPostToolUse`
+ * only fires for successful results, so register this handler to observe or
+ * react to failed tool outcomes.
+ *
+ * Note: `"rejected"`, `"denied"`, and `"timeout"` results do not currently
+ * trigger this hook either — only `"failure"` does.
+ */
+export type PostToolUseFailureHandler = (input: PostToolUseFailureHookInput, invocation: {
+    sessionId: string;
+}) => Promise<PostToolUseFailureHookOutput | void> | PostToolUseFailureHookOutput | void;
+/**
+ * Input for user-prompt-submitted hook
+ */
+export interface UserPromptSubmittedHookInput extends BaseHookInput {
+    prompt: string;
+}
+/**
+ * Output for user-prompt-submitted hook
+ */
+export interface UserPromptSubmittedHookOutput {
+    modifiedPrompt?: string;
+    additionalContext?: string;
+    suppressOutput?: boolean;
+}
+/**
+ * Handler for user-prompt-submitted hook
+ */
+export type UserPromptSubmittedHandler = (input: UserPromptSubmittedHookInput, invocation: {
+    sessionId: string;
+}) => Promise<UserPromptSubmittedHookOutput | void> | UserPromptSubmittedHookOutput | void;
+/**
+ * Input for the user-prompt-transformed hook.
+ *
+ * This hook runs after the runtime has transformed the submitted prompt with
+ * generated context, but before it is persisted to session history or sent to
+ * the model.
+ */
+export interface UserPromptTransformedHookInput extends BaseHookInput {
+    prompt: string;
+    transformedPrompt: string;
+}
+/**
+ * Output for the user-prompt-transformed hook.
+ */
+export interface UserPromptTransformedHookOutput {
+    modifiedTransformedPrompt?: string;
+}
+/**
+ * Handler for the user-prompt-transformed hook.
+ */
+export type UserPromptTransformedHandler = (input: UserPromptTransformedHookInput, invocation: {
+    sessionId: string;
+}) => Promise<UserPromptTransformedHookOutput | void> | UserPromptTransformedHookOutput | void;
+/**
+ * Input for session-start hook
+ */
+export interface SessionStartHookInput extends BaseHookInput {
+    source: "startup" | "resume" | "new";
+    initialPrompt?: string;
+}
+/**
+ * Output for session-start hook
+ */
+export interface SessionStartHookOutput {
+    additionalContext?: string;
+    modifiedConfig?: Record<string, unknown>;
+}
+/**
+ * Handler for session-start hook
+ */
+export type SessionStartHandler = (input: SessionStartHookInput, invocation: {
+    sessionId: string;
+}) => Promise<SessionStartHookOutput | void> | SessionStartHookOutput | void;
+/**
+ * Input for session-end hook
+ */
+export interface SessionEndHookInput extends BaseHookInput {
+    reason: "complete" | "error" | "abort" | "timeout" | "user_exit";
+    finalMessage?: string;
+    error?: string;
+}
+/**
+ * Output for session-end hook
+ */
+export interface SessionEndHookOutput {
+    suppressOutput?: boolean;
+    cleanupActions?: string[];
+    sessionSummary?: string;
+}
+/**
+ * Handler for session-end hook
+ */
+export type SessionEndHandler = (input: SessionEndHookInput, invocation: {
+    sessionId: string;
+}) => Promise<SessionEndHookOutput | void> | SessionEndHookOutput | void;
+/**
+ * Input for error-occurred hook
+ */
+export interface ErrorOccurredHookInput extends BaseHookInput {
+    error: string;
+    errorContext: "model_call" | "tool_execution" | "system" | "user_input";
+    recoverable: boolean;
+}
+/**
+ * Output for error-occurred hook
+ */
+export interface ErrorOccurredHookOutput {
+    suppressOutput?: boolean;
+    errorHandling?: "retry" | "skip" | "abort";
+    retryCount?: number;
+    userNotification?: string;
+}
+/**
+ * Handler for error-occurred hook
+ */
+export type ErrorOccurredHandler = (input: ErrorOccurredHookInput, invocation: {
+    sessionId: string;
+}) => Promise<ErrorOccurredHookOutput | void> | ErrorOccurredHookOutput | void;
+/**
+ * Input for the agent-stop hook.
+ *
+ * Fires for the top-level (main) agent when it reaches a natural terminal stop
+ * — i.e. the agent has gone idle without a pending non-terminal tool call and
+ * was not aborted or blocked by a rejected tool. (For sub-agents, the runtime
+ * fires a separate sub-agent stop lifecycle.)
+ */
+export interface AgentStopHookInput extends BaseHookInput {
+    /** Why the agent stopped (for example, `"end_turn"`). */
+    stopReason?: string;
+    /** Path to the on-disk session transcript, when available. */
+    transcriptPath?: string;
+    /**
+     * True when this stop is a re-entry triggered by a previous agent-stop
+     * `block` decision (Claude-compatible `stop_hook_active` semantics). Lets a
+     * handler avoid blocking indefinitely.
+     */
+    stopHookActive?: boolean;
+}
+/**
+ * Output for the agent-stop hook.
+ *
+ * Return `{ decision: "block", reason }` to keep the agent running: the
+ * `reason` is enqueued as a follow-up user message so the agent continues
+ * working (for example, to remediate findings surfaced by the hook). The
+ * runtime caps consecutive blocks to prevent runaway loops. Returning nothing
+ * (or omitting `decision`) lets the agent stop normally.
+ */
+export interface AgentStopHookOutput {
+    decision?: "block";
+    reason?: string;
+}
+/**
+ * Handler for the agent-stop hook.
+ */
+export type AgentStopHandler = (input: AgentStopHookInput, invocation: {
+    sessionId: string;
+}) => Promise<AgentStopHookOutput | void> | AgentStopHookOutput | void;
+/**
+ * Configuration for session hooks
+ */
+export interface SessionHooks {
+    /**
+     * Called before a tool is executed
+     */
+    onPreToolUse?: PreToolUseHandler;
+    /**
+     * Called before an MCP tool is called
+     */
+    onPreMcpToolCall?: PreMcpToolCallHandler;
+    /**
+     * Called after a tool is executed with a successful result.
+     *
+     * For failed tool executions, register {@link onPostToolUseFailure} instead;
+     * this handler does not fire for non-success results.
+     */
+    onPostToolUse?: PostToolUseHandler;
+    /**
+     * Called after a tool execution whose result was `"failure"`.
+     *
+     * Register this handler alongside {@link onPostToolUse} to observe failed
+     * tool calls — `onPostToolUse` only fires for successful results, so
+     * without this hook failed tool calls are invisible to extensions.
+     */
+    onPostToolUseFailure?: PostToolUseFailureHandler;
+    /**
+     * Called when the user submits a prompt
+     */
+    onUserPromptSubmitted?: UserPromptSubmittedHandler;
+    /**
+     * Called after the runtime transforms a submitted prompt and before it is stored.
+     */
+    onUserPromptTransformed?: UserPromptTransformedHandler;
+    /**
+     * Called when a session starts
+     */
+    onSessionStart?: SessionStartHandler;
+    /**
+     * Called when a session ends
+     */
+    onSessionEnd?: SessionEndHandler;
+    /**
+     * Called when an error occurs
+     */
+    onErrorOccurred?: ErrorOccurredHandler;
+    /**
+     * Called when the top-level agent reaches a natural terminal stop (it went
+     * idle without pending work and was not aborted). Return
+     * `{ decision: "block", reason }` to keep the agent running with `reason`
+     * enqueued as a follow-up message — for example, to have the agent
+     * remediate findings the handler surfaced. Returning nothing lets the
+     * agent stop.
+     */
+    onAgentStop?: AgentStopHandler;
+}
+/**
+ * Base interface for MCP server configuration.
+ */
+interface MCPServerConfigBase {
+    /**
+     * List of tools to include from this server.
+     * `undefined` (the default) or `["*"]` means include all tools.
+     * `[]` means include none.
+     */
+    tools?: string[];
+    /**
+     * Indicates the server type: "stdio" for local/subprocess servers, "http"/"sse" for remote servers.
+     * If not specified, defaults to "stdio".
+     */
+    type?: string;
+    /**
+     * Optional timeout in milliseconds for tool calls to this server.
+     */
+    timeout?: number;
+}
+/**
+ * Configuration for a local/stdio MCP server.
+ */
+export interface MCPStdioServerConfig extends MCPServerConfigBase {
+    type?: "local" | "stdio";
+    command: string;
+    args?: string[];
+    /**
+     * Environment variables to pass to the server.
+     */
+    env?: Record<string, string>;
+    /**
+     * Working directory for the server process.
+     */
+    workingDirectory?: string;
+}
+/**
+ * Configuration for a remote MCP server (HTTP or SSE).
+ */
+export interface MCPHTTPServerConfig extends MCPServerConfigBase {
+    type: "http" | "sse";
+    /**
+     * URL of the remote server.
+     */
+    url: string;
+    /**
+     * Optional HTTP headers to include in requests.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Union type for MCP server configurations.
+ */
+export type MCPServerConfig = MCPStdioServerConfig | MCPHTTPServerConfig;
+/**
+ * Configuration for a custom agent.
+ */
+export interface CustomAgentConfig {
+    /**
+     * Unique name of the custom agent.
+     */
+    name: string;
+    /**
+     * Display name for UI purposes.
+     */
+    displayName?: string;
+    /**
+     * Description of what the agent does.
+     */
+    description?: string;
+    /**
+     * List of tool names the agent can use.
+     * Use null or undefined for all tools.
+     */
+    tools?: string[] | null;
+    /**
+     * The prompt content for the agent.
+     */
+    prompt: string;
+    /**
+     * MCP servers specific to this agent.
+     */
+    mcpServers?: Record<string, MCPServerConfig>;
+    /**
+     * Whether the agent should be available for model inference.
+     * @default true
+     */
+    infer?: boolean;
+    /**
+     * List of skill names to preload into this agent's context.
+     * When set, the full content of each listed skill is eagerly injected into
+     * the agent's context at startup. Skills are resolved by name from the
+     * session's configured skill directories (`skillDirectories`).
+     * When omitted, no skills are injected (opt-in model).
+     */
+    skills?: string[];
+    /**
+     * Model identifier for this agent (e.g. "claude-haiku-4.5").
+     * When set, the runtime will attempt to use this model for the agent,
+     * falling back to the parent session model if unavailable.
+     */
+    model?: string;
+    /**
+     * Reasoning effort level for this agent's model.
+     * When omitted, the runtime resolves the effort from model configuration,
+     * then inherits the parent effort only if this agent uses the same model.
+     */
+    reasoningEffort?: ReasoningEffort;
+}
+/**
+ * Configuration for the default agent (the built-in agent that handles
+ * turns when no custom agent is selected).
+ * Use this to control tool visibility for the default agent independently of custom sub-agents.
+ */
+export interface DefaultAgentConfig {
+    /**
+     * List of tool names to exclude from the default agent.
+     * These tools remain available to custom sub-agents that reference them in their `tools` array.
+     * Use this to register tools that should only be accessed via delegation to sub-agents,
+     * keeping the default agent's context clean.
+     */
+    excludedTools?: string[];
+}
+/**
+ * Configuration for infinite sessions with automatic context compaction and workspace persistence.
+ * When enabled, sessions automatically manage context window limits through background compaction
+ * and persist state to a workspace directory.
+ */
+export interface InfiniteSessionConfig {
+    /**
+     * Whether infinite sessions are enabled.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Context utilization threshold (0.0-1.0) at which background compaction starts.
+     * Compaction runs asynchronously, allowing the session to continue processing.
+     * @default 0.80
+     */
+    backgroundCompactionThreshold?: number;
+    /**
+     * Context utilization threshold (0.0-1.0) at which the session blocks until compaction completes.
+     * This prevents context overflow when compaction hasn't finished in time.
+     * @default 0.95
+     */
+    bufferExhaustionThreshold?: number;
+}
+/**
+ * Configuration for the memory feature, which lets the agent persist and recall
+ * information across turns.
+ */
+export interface MemoryConfiguration {
+    /**
+     * Whether the memory feature is enabled for this session.
+     */
+    enabled: boolean;
+}
+/**
+ * Configuration for handling large tool outputs.
+ *
+ * When a tool produces output exceeding the configured size, the output is
+ * written to a temp file and a reference is returned to the model instead of
+ * the full payload.
+ */
+export interface LargeToolOutputConfig {
+    /**
+     * Whether large output handling is enabled.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Maximum size in bytes before output is written to a temp file.
+     * @default 51200
+     */
+    maxSizeBytes?: number;
+    /**
+     * Directory to write temp files to. Defaults to the OS temp directory.
+     */
+    outputDirectory?: string;
+}
+/**
+ * Valid reasoning effort levels for models that support it.
+ */
+export type ReasoningEffort = "low" | "medium" | "high" | "xhigh" | "max";
+/**
+ * Context window tier for the session. "long_context" pins the session to the
+ * long-context tier when the selected model supports it.
+ */
+export type ContextTier = "default" | "long_context";
+/** Parsed parameters from an MCP server's WWW-Authenticate response. */
+export interface McpAuthWwwAuthenticateParams {
+    /** Parsed resource_metadata URL used for protected-resource metadata discovery, if present. */
+    resourceMetadataUrl?: string;
+    /** Parsed OAuth scope, if present. */
+    scope?: string;
+    /** Parsed OAuth error, if present. */
+    error?: string;
+}
+/** Static OAuth client configuration supplied by the MCP server, if available. */
+export interface McpAuthStaticClientConfig {
+    /** OAuth client ID for the server. */
+    clientId: string;
+    /** Optional OAuth client secret for confidential static clients. */
+    clientSecret?: string;
+    /** Optional non-default OAuth grant type. */
+    grantType?: "client_credentials";
+    /** Whether this is a public OAuth client. */
+    publicClient?: boolean;
+}
+/** MCP OAuth request that the SDK host can satisfy with a host-acquired token. */
+export interface McpAuthRequest {
+    /** Unique request identifier used by the SDK when responding. */
+    requestId: string;
+    /** Display name of the MCP server that requires OAuth. */
+    serverName: string;
+    /** URL of the MCP server that requires OAuth. */
+    serverUrl: string;
+    /** Why the runtime is requesting host-provided OAuth credentials. */
+    reason: "initial" | "refresh" | "reauth" | "upscope";
+    /** Parsed WWW-Authenticate parameters from the MCP server. */
+    wwwAuthenticateParams?: McpAuthWwwAuthenticateParams;
+    /** Raw RFC 9728 protected-resource metadata JSON fetched by the runtime, if available. */
+    resourceMetadata?: string;
+    /** Static OAuth client configuration, if the server specifies one. */
+    staticClientConfig?: McpAuthStaticClientConfig;
+}
+/** Host-provided OAuth token data for a pending MCP OAuth request. */
+export interface McpAuthToken {
+    /** Access token acquired by the SDK host. */
+    accessToken: string;
+    /** OAuth token type. Defaults to Bearer when omitted. */
+    tokenType?: string;
+    /** Token lifetime in seconds, if known. */
+    expiresIn?: number;
+}
+/**
+ * Result returned by an MCP auth request handler.
+ *
+ * Return `null`/`undefined` or `{ kind: "cancelled" }` to cancel the pending
+ * OAuth request. Return `{ kind: "token", ... }` to provide host-acquired
+ * OAuth token data.
+ */
+export type McpAuthResult = ({
+    kind: "token";
+} & McpAuthToken) | {
+    kind: "cancelled";
+};
+/** Callback invoked when an MCP server requires OAuth and the SDK host opted in. */
+export type McpAuthHandler = (request: McpAuthRequest, context: {
+    sessionId: string;
+}) => McpAuthResult | McpAuthToken | null | undefined | Promise<McpAuthResult | McpAuthToken | null | undefined>;
+/**
+ * Stable extension identity for session participants that provide canvases.
+ */
+export interface ExtensionInfo {
+    /** Extension namespace/source, e.g. "github-app". */
+    source: string;
+    /** Stable provider name within the source namespace. */
+    name: string;
+}
+/**
+ * Stable identity for a host/SDK connection that supplies built-in canvases.
+ *
+ * When set on session create or resume, the runtime uses {@link id} verbatim
+ * as the agent-facing canvas extension id, so canvases declared on a control
+ * connection survive stdio reconnect and CLI process restart instead of being
+ * re-keyed to a per-connection id. The id is opaque to the runtime; a
+ * per-window-stable value such as `app:builtin:<windowId>` is recommended. An
+ * id beginning with `connection:` is reserved and ignored by the runtime.
+ */
+export interface CanvasProviderIdentity {
+    /** Opaque, stable provider id used verbatim as the canvas extension id. */
+    id: string;
+    /** Optional display name surfaced as the canvas extension name. */
+    name?: string;
+}
+/**
+ * Static resource ceilings declared by a factory before it runs.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface FactoryLimits {
+    /** Maximum number of factory subagents that may run concurrently. Must be positive when present. */
+    maxConcurrentSubagents?: number;
+    /** Maximum total number of factory subagents that may be spawned. Must be positive when present. */
+    maxTotalSubagents?: number;
+    /** Maximum AI credits consumed by factory subagents and descendants. This post-paid ceiling is soft. */
+    maxAiCredits?: number;
+    /**
+     * Maximum accumulated active-execution time, in seconds. Active execution includes the entire extension body,
+     * subprocess waits, queued-agent waits, and sleeps. The limit is armed from the remaining headroom when a run
+     * resumes; time between attempts is not counted. Must be finite and positive when present.
+     */
+    timeoutSeconds?: number;
+}
+/**
+ * Registration metadata for an extension-authored factory.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface FactoryMeta {
+    /** Stable factory name used for invocation. */
+    name: string;
+    /** Human-readable factory description. */
+    description: string;
+    /** Display metadata for the progress phases the factory may report. */
+    phases: Array<{
+        title: string;
+        detail?: string;
+    }>;
+    /**
+     * Optional declared shape of the arguments this factory expects as `ctx.args`.
+     *
+     * Declaring one is strongly recommended for any factory that reads `ctx.args`.
+     * When the model invokes the factory through the `run_factory` tool, the CLI
+     * validates `args` against this declaration **before** the run starts, so a
+     * malformed call is rejected with a correction hint and retried without ever
+     * creating a run row, prompting the user for permission, or spending credits. A
+     * factory that declares nothing is never validated: a malformed call starts,
+     * takes an approval, spends credits, and then fails inside the factory body.
+     * `factories_manage` with `operation: "inspect"` reports the declared shape so an
+     * agent can read it before invoking.
+     *
+     * This covers the model's `run_factory` path only. `session.factory.run(...)` is
+     * not validated against the declaration, so a factory should still check
+     * `ctx.args` rather than assume the declared shape held.
+     *
+     * Enforcement covers structure — types, required properties, and enum/const
+     * values. Finer constraints such as `minLength`, `pattern`, and
+     * `additionalProperties` are recorded in the declaration but not enforced. See
+     * {@link FactoryJsonSchema} for the accepted subset. A declaration outside that
+     * subset is rejected at registration.
+     */
+    argsSchema?: FactoryJsonSchema;
+    /** Optional resource ceilings presented to the user before execution. */
+    limits?: FactoryLimits;
+}
+/**
+ * Provider-scoped options for the Copilot API (CAPI).
+ *
+ * These settings apply to the built-in Copilot API provider only. They live
+ * under their own namespace because a single session can host multiple
+ * providers (CAPI alongside BYOK via {@link ProviderConfig}), so transport and
+ * provider-level choices are conceptually per-provider rather than global.
+ */
+export interface CapiSessionOptions {
+    /**
+     * Whether to use the WebSocket transport for the CAPI Responses API.
+     *
+     * WebSocket transport is enabled by default whenever the selected model
+     * advertises the `ws:/responses` endpoint. Set this to `false` to fall back
+     * to the HTTP Responses transport instead — useful for users behind proxies
+     * where WebSocket connections fail.
+     *
+     * Setting this to `false` is equivalent to setting the
+     * `COPILOT_CLI_DISABLE_WEBSOCKET_RESPONSES` environment variable.
+     *
+     * @default true
+     */
+    enableWebSocketResponses?: boolean;
+}
+/**
+ * A single ExP (Experiment Platform) flag value. ExP assignments resolve to a
+ * string, number, boolean, or `null`.
+ */
+export type ExpFlagValue = string | number | boolean | null;
+/**
+ * A single configuration entry in a {@link CopilotExpAssignmentResponse}. Each
+ * entry carries an identifier and a bag of typed parameter values.
+ */
+export interface ExpConfigEntry {
+    /** Identifier of the configuration entry. */
+    Id: string;
+    /** Parameter values keyed by parameter name. */
+    Parameters: Record<string, ExpFlagValue>;
+}
+/**
+ * ExP ("flight") assignment data, in the same JSON shape the Copilot CLI
+ * fetches from the experimentation service. Field names are PascalCase to match
+ * the on-the-wire contract consumed by the runtime.
+ */
+export interface CopilotExpAssignmentResponse {
+    /** Enabled feature names. */
+    Features: string[];
+    /** Assigned flights keyed by flight name. */
+    Flights: Record<string, string>;
+    /** Configuration entries carrying typed parameter values. */
+    Configs: ExpConfigEntry[];
+    /** Opaque parameter-group payload passed through untouched. */
+    ParameterGroups?: unknown;
+    /** Version of the flighting configuration. */
+    FlightingVersion?: number;
+    /** Impression identifier for the assignment. */
+    ImpressionId?: string;
+    /** Assignment context string forwarded to CAPI and telemetry. */
+    AssignmentContext: string;
+}
+/**
+ * Configuration for the built-in GitHub MCP server.
+ *
+ * `disableFormDeferral` only applies to the built-in GitHub MCP server and
+ * only has an effect when MCP Apps and form-backed GitHub tools are enabled.
+ */
+export interface GitHubMcpToolConfig {
+    enableAllTools?: boolean;
+    additionalToolsets?: string[];
+    additionalTools?: string[];
+    enableInsidersMode?: boolean;
+    disableFormDeferral?: boolean;
+}
+/** Well-known managed bypass-permissions policies. */
+export declare const DisableBypassPermissionsModes: {
+    /** Turn off bypass-permissions mode entirely. */
+    readonly Disable: "disable";
+    /** Permit automatic bypass but block full allow-all. */
+    readonly AllowAutoOnly: "allow-auto-only";
+};
+/**
+ * Permissions-only managed policy injected by the host via
+ * {@link SessionConfigBase.managedSettings}.
+ *
+ * Rule strings use the same vocabulary the runtime accepts for fetched managed
+ * policy (e.g. `"Read(**)"`, `"Shell(git push *)"`); malformed rules are
+ * rejected at session creation.
+ */
+export interface ManagedSettingsPermissions {
+    /**
+     * Restricts bypass-permissions mode for the session. See
+     * {@link DisableBypassPermissionsModes} for well-known values. Unknown
+     * values are forwarded so newer runtime policies fail closed.
+     */
+    disableBypassPermissionsMode?: string;
+    /** Operations that must always be denied. Unioned across managed layers. */
+    deny?: string[];
+    /**
+     * Operations that must prompt for approval. Unioned across managed layers.
+     */
+    ask?: string[];
+    /**
+     * Operations permitted without prompting. Every declared `allow` list
+     * (across managed layers) must admit an operation for it to be allowed.
+     */
+    allow?: string[];
+}
+/**
+ * Host-injected enterprise managed settings. The first supported contract is
+ * permissions-only; unknown sibling keys are rejected by the runtime.
+ *
+ * @see {@link SessionConfigBase.managedSettings}
+ */
+export interface ManagedSettings {
+    /** Managed permission policy for the session. */
+    permissions?: ManagedSettingsPermissions;
+}
+/** Selects the model-facing shape of the built-in `ask_user` tool. */
+export type AskUserVariant = "legacy" | "elicitation";
+/**
+ * Shared configuration fields used by both {@link SessionConfig} (for
+ * creating a new session) and {@link ResumeSessionConfig} (for resuming
+ * an existing one).
+ */
+export interface SessionConfigBase {
+    /**
+     * Client name to identify the application using the SDK.
+     * Included in the User-Agent header for API requests.
+     */
+    clientName?: string;
+    /**
+     * Model to use for this session
+     */
+    model?: string;
+    /**
+     * Reasoning effort level for models that support it.
+     * Only valid for models where capabilities.supports.reasoningEffort is true.
+     * Use client.listModels() to check supported values for each model.
+     */
+    reasoningEffort?: ReasoningEffort;
+    /**
+     * Reasoning summary mode for models that support configurable reasoning summaries.
+     * Use "none" to suppress summary output regardless of whether reasoning is enabled.
+     */
+    reasoningSummary?: ReasoningSummary;
+    /**
+     * Controls whether the session enables experimental features.
+     * Defaults to `false` in `"empty"` mode; otherwise the runtime decides when unset.
+     */
+    enableExperimentalMode?: boolean;
+    /**
+     * Context window tier for models that support it. Use "long_context" to pin
+     * the session to the long-context tier; omit or use "default" otherwise.
+     */
+    contextTier?: ContextTier;
+    /** Per-property overrides for model capabilities, deep-merged over runtime defaults. */
+    modelCapabilities?: ModelCapabilitiesOverride;
+    /**
+     * Configuration for handling large tool outputs. When a tool produces
+     * output exceeding the configured size, the output is written to a temp
+     * file and a reference is returned to the model instead of the full
+     * payload.
+     */
+    largeOutput?: LargeToolOutputConfig;
+    /**
+     * Override the default configuration directory location.
+     * When specified, the session will use this directory for storing config and state.
+     */
+    configDirectory?: string;
+    /**
+     * Enables runtime discovery of supported configuration. Explicitly supplied
+     * configuration takes precedence over discovered values.
+     *
+     * @default false
+     */
+    enableConfigDiscovery?: boolean;
+    /**
+     * Tools exposed to the CLI server. Tools without a handler are declaration-only
+     * and must be resolved by the consumer via pending external tool request RPCs.
+     */
+    tools?: Tool<any>[];
+    /**
+     * Canvases contributed by this session participant. The declaring
+     * connection becomes the live provider for `canvas.open|focus|close|reload`
+     * and `canvas.action.invoke` dispatches targeting each canvas's `id` for
+     * the lifetime of the connection. Re-declaring the same id on resume
+     * replaces the prior declaration.
+     */
+    canvases?: Canvas[];
+    /**
+     * Renderer-side opt-in: when true, the runtime surfaces canvas agent tools
+     * (`list_canvas_capabilities`, `open_canvas`, `invoke_canvas_action`) to
+     * the model for this connection. Default off so SDK callers that cannot
+     * display canvases stay clean.
+     */
+    requestCanvasRenderer?: boolean;
+    /**
+     * Extension surface opt-in: when true, the runtime wires extension
+     * management tools and per-extension tool dispatch onto the session for
+     * this connection. Default off so callers that do not expose extensions
+     * stay clean.
+     */
+    requestExtensions?: boolean;
+    /**
+     * Optional override path to a `copilot-sdk/` folder to inject into
+     * extension subprocesses for this session in place of the bundled SDK.
+     * When unset or invalid (missing folder or missing `index.js` /
+     * `extension.js`), the runtime falls back to the bundled SDK without
+     * throwing. Takes precedence over any server-level default.
+     *
+     * Only honored on session create and resume — extensions joining via
+     * `joinSession` cannot override the SDK path, because the extension
+     * subprocess has already been forked by the host with the SDK the host
+     * chose. `JoinSessionConfig` omits this field for that reason.
+     */
+    extensionSdkPath?: string;
+    /**
+     * Stable extension identity for canvas providers on this connection. When
+     * set, the runtime uses `${source}:${name}` as the agent-facing extension
+     * id instead of a reconnect-specific connection id.
+     */
+    extensionInfo?: ExtensionInfo;
+    /**
+     * Stable identity for a host/SDK connection that supplies built-in
+     * canvases. When set, the runtime uses `id` verbatim as the agent-facing
+     * canvas extension id, so canvases declared on a control connection survive
+     * reconnect and CLI restart. Honored on session create and resume.
+     */
+    canvasProvider?: CanvasProviderIdentity;
+    /**
+     * Slash commands registered for this session.
+     * When the CLI has a TUI, each command appears as `/name` for the user to invoke.
+     * The handler is called when the user executes the command.
+     */
+    commands?: CommandDefinition[];
+    /**
+     * System message configuration
+     * Controls how the system prompt is constructed
+     */
+    systemMessage?: SystemMessageConfig;
+    /**
+     * Override for the runtime's built-in tool-search behavior.
+     *
+     * To also override the tool-search tool's implementation, register a
+     * {@link Tool} named `tool_search_tool` with `overridesBuiltInTool: true` in
+     * {@link SessionConfigBase.tools}.
+     */
+    toolSearch?: ToolSearchConfig;
+    /**
+     * List of tool names to allow. When specified, only these tools will be available.
+     *
+     * Supports source-qualified filter patterns (`builtin:*`, `builtin:<name>`,
+     * `mcp:*`, `mcp:<name>`, `custom:*`, `custom:<name>`) as well as the bare
+     * name form (exact match across any source). Build this list with
+     * {@link ToolSet} for type safety and readable intent.
+     *
+     * Composes with {@link excludedTools}: a tool is enabled when it matches
+     * `availableTools` (or `availableTools` is unset) AND it does not match
+     * `excludedTools`. This lets you express "everything matching X except Y".
+     */
+    availableTools?: string[] | ToolSet;
+    /**
+     * List of tool names to disable. Supports the same pattern syntax as
+     * {@link availableTools}.
+     *
+     * Always takes precedence over {@link availableTools}: a tool listed here
+     * is disabled even if it also matches `availableTools`.
+     */
+    excludedTools?: string[] | ToolSet;
+    /**
+     * Names of built-in agents to exclude from the session. Excluded built-in
+     * agents are hidden from discovery and cannot be selected or invoked unless
+     * a custom agent with the same name is configured.
+     */
+    excludedBuiltinAgents?: string[];
+    /**
+     * Built-in skill names to include in the session. In `mode: "empty"`,
+     * omitting this option excludes all runtime-bundled skills; specifying names
+     * opts those built-ins back in. Skills from other sources remain eligible.
+     */
+    includedBuiltinSkills?: string[];
+    /**
+     * Custom provider configuration (BYOK - Bring Your Own Key).
+     * When specified, uses the provided API endpoint instead of the Copilot API.
+     */
+    provider?: ProviderConfig;
+    /**
+     * Provider-scoped options for the built-in Copilot API (CAPI), such as
+     * opting out of the WebSocket Responses transport. See
+     * {@link CapiSessionOptions}.
+     */
+    capi?: CapiSessionOptions;
+    /**
+     * Named BYOK provider connections (transport + credentials), referenced by
+     * {@link models} entries via {@link NamedProviderConfig.name}.
+     *
+     * Unlike the singular {@link provider} — which makes the entire session BYOK
+     * and bypasses Copilot API authentication — named providers are **additive**:
+     * they coexist with Copilot API auth so models from CAPI and one or more BYOK
+     * providers can be mixed within a single session and across sub-agents.
+     * Combining `providers`/`models` with {@link provider} is rejected.
+     *
+     * @experimental This is part of an experimental multi-provider BYOK surface
+     * and may change or be removed in future SDK or CLI releases.
+     */
+    providers?: NamedProviderConfig[];
+    /**
+     * BYOK model definitions added to the session's selectable model list, each
+     * referencing a `providers[].name`. Each model surfaces under the
+     * provider-qualified selection id `providerName/id`, so BYOK ids never collide
+     * with — and cannot shadow — bare CAPI ids; duplicate selection ids are rejected.
+     *
+     * @experimental This is part of an experimental multi-provider BYOK surface
+     * and may change or be removed in future SDK or CLI releases.
+     */
+    models?: ProviderModelConfig[];
+    /**
+     * Enables or disables internal session telemetry for this session.
+     * When `false`, disables session telemetry. When omitted (the default) or `true`,
+     * telemetry is enabled for GitHub-authenticated sessions.
+     * When a custom {@link provider} (BYOK) is configured, session telemetry is always
+     * disabled regardless of this setting.
+     * This is independent of the OpenTelemetry configuration in {@link CopilotClientOptions.telemetry}.
+     */
+    enableSessionTelemetry?: boolean;
+    /**
+     * Enables native model citations for supported providers.
+     *
+     * @experimental
+     */
+    enableCitations?: boolean;
+    /**
+     * Opt in to capturing file changes for session rewind and cumulative session
+     * diff. On create, capture starts with the first turn. On resume, this can
+     * enable tracking only when the session still has a valid baseline; it cannot
+     * reconstruct changes from earlier untracked turns.
+     */
+    enableFileChangeTracking?: boolean;
+    /**
+     * Limits applied to this session's current accounting window.
+     *
+     * @experimental
+     */
+    sessionLimits?: SessionLimitsConfig;
+    /**
+     * When true, the runtime skips loading custom-instruction sources
+     * (e.g. `.github/copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`).
+     *
+     * Defaults to `false` (custom instructions are loaded). Under
+     * {@link CopilotClientOptions.mode} = `"empty"`, defaults to `true`; apps
+     * can pass `false` here to opt back in.
+     */
+    skipCustomInstructions?: boolean;
+    /**
+     * When true, custom agents default to local-only execution and are not
+     * dispatched to remote workers.
+     *
+     * Defaults to `false`. Under {@link CopilotClientOptions.mode} = `"empty"`,
+     * defaults to `true`; apps can pass `false` here to opt back in.
+     */
+    customAgentsLocalOnly?: boolean;
+    /**
+     * When true, the runtime instructs the agent to include a `Co-authored-by`
+     * trailer in commit messages it composes.
+     *
+     * Defaults to `true`. Under {@link CopilotClientOptions.mode} = `"empty"`,
+     * defaults to `false`; apps can pass `true` here to opt back in.
+     */
+    coauthorEnabled?: boolean;
+    /**
+     * When true, the `manage_schedule` tool is exposed to the agent.
+     *
+     * Defaults to whatever the runtime exposes (typically gated to staff
+     * users). Under {@link CopilotClientOptions.mode} = `"empty"`, defaults to
+     * `false`; apps can pass `true` here to opt back in.
+     */
+    manageScheduleEnabled?: boolean;
+    /**
+     * Optional handler for permission requests from the server.
+     * When omitted, permission requests are surfaced as events and left pending for
+     * the consumer to resolve via the pending permission RPC.
+     */
+    onPermissionRequest?: PermissionHandler;
+    /**
+     * Optional handler for MCP OAuth requests from MCP servers.
+     * When provided, the SDK can satisfy MCP server OAuth requests with
+     * host-provided token data or cancellation.
+     */
+    onMcpAuthRequest?: McpAuthHandler;
+    /**
+     * Handler for user input requests from the agent.
+     * When provided with the default `legacy` {@link AskUserVariant}, enables the
+     * question-and-answer form of the `ask_user` tool.
+     */
+    onUserInputRequest?: UserInputHandler;
+    /**
+     * Selects the model-facing shape of the built-in `ask_user` tool.
+     *
+     * The default is `"legacy"`. To use `"elicitation"`, also provide
+     * {@link onElicitationRequest} so the host can answer structured forms.
+     * The runtime resolves this option when it creates or cold-resumes the session.
+     */
+    askUserVariant?: AskUserVariant;
+    /**
+     * Handler for elicitation requests from the agent.
+     * When provided, the server calls back to this client for form-based UI dialogs.
+     * Also enables the `elicitation` capability on the session.
+     */
+    onElicitationRequest?: ElicitationHandler;
+    /**
+     * Enable MCP Apps (SEP-1865) UI passthrough on this session.
+     *
+     * When `true` **and** the runtime has MCP Apps enabled (via the
+     * `MCP_APPS` feature flag or `COPILOT_MCP_APPS=true` environment
+     * override), the runtime adds the `mcp-apps` capability to the session,
+     * which causes it to advertise the `extensions.io.modelcontextprotocol/ui`
+     * extension to MCP servers (so they expose `_meta.ui.resourceUri` on
+     * tools) and to expose the `session.rpc.mcp.apps.{listTools,callTool,
+     * readResource,setHostContext,getHostContext,diagnose}` JSON-RPC methods.
+     *
+     * If the runtime gate is off, the opt-in is silently dropped server-side
+     * (the runtime logs a warning); the session is created normally but the
+     * MCP Apps surface is unavailable. Inspect the runtime's
+     * `capabilities.ui.mcpApps` on the create/resume response to detect this.
+     *
+     * SDK consumers MUST set this to `true` only when they have an iframe
+     * renderer that can display `ui://` MCP App bundles. Setting it without a
+     * renderer will cause MCP servers to register UI-enabled tool variants
+     * the consumer cannot display.
+     *
+     * @experimental This option is part of an experimental wire-protocol surface
+     * (SEP-1865) and may change or be removed in a future release.
+     *
+     * @default false
+     */
+    enableMcpApps?: boolean;
+    /**
+     * Configuration for the built-in GitHub MCP server.
+     *
+     * `disableFormDeferral` only applies to the built-in GitHub MCP server and
+     * only has an effect when MCP Apps and form-backed GitHub tools are enabled.
+     */
+    githubMcpToolConfig?: GitHubMcpToolConfig;
+    /**
+     * Handler for exit-plan-mode requests from the agent.
+     * When provided, enables `exitPlanMode.request` callbacks.
+     */
+    onExitPlanModeRequest?: ExitPlanModeHandler;
+    /**
+     * Handler for auto-mode-switch requests from the agent.
+     * When provided, enables `autoModeSwitch.request` callbacks.
+     */
+    onAutoModeSwitchRequest?: AutoModeSwitchHandler;
+    /**
+     * Hook handlers for intercepting session lifecycle events.
+     * When provided, enables hooks callback allowing custom logic at various points.
+     */
+    hooks?: SessionHooks;
+    /**
+     * Working directory for the session.
+     * Tool operations will be relative to this directory.
+     */
+    workingDirectory?: string;
+    /**
+     * Additional directories the agent may access beyond the working directory.
+     * Relative paths are resolved against the session's working directory.
+     * Re-supply these directories when resuming a session.
+     */
+    additionalDirectories?: string[];
+    /**
+     * Enable streaming of assistant message and reasoning chunks.
+     * When true, ephemeral assistant.message_delta and assistant.reasoning_delta
+     * events are sent as the response is generated. Clients should accumulate
+     * deltaContent values to build the full response.
+     * @default false
+     */
+    streaming?: boolean;
+    /**
+     * Include sub-agent streaming events in the event stream. When true, streaming
+     * delta events from sub-agents (e.g., `assistant.message_delta`,
+     * `assistant.reasoning_delta`, `assistant.streaming_delta` with `agentId` set)
+     * are forwarded to this connection. When false, only non-streaming sub-agent
+     * events and `subagent.*` lifecycle events are forwarded; streaming deltas from
+     * sub-agents are suppressed.
+     * @default true
+     */
+    includeSubAgentStreamingEvents?: boolean;
+    /**
+     * Controls how MCP OAuth tokens are stored for this session.
+     * - `"persistent"` — tokens are stored in the OS keychain (shared across sessions)
+     * - `"in-memory"` — tokens are stored in memory and discarded when the session ends
+     *
+     * @default "in-memory"
+     */
+    mcpOAuthTokenStorage?: "persistent" | "in-memory";
+    /**
+     * MCP server configurations for the session.
+     * Keys are server names, values are server configurations.
+     */
+    mcpServers?: Record<string, MCPServerConfig>;
+    /**
+     * Custom agent configurations for the session.
+     */
+    customAgents?: CustomAgentConfig[];
+    /**
+     * Configuration for the default agent (the built-in agent that handles
+     * turns when no custom agent is selected).
+     * Use `excludedTools` to hide specific tools from the default agent while keeping
+     * them available to custom sub-agents.
+     */
+    defaultAgent?: DefaultAgentConfig;
+    /**
+     * Name of the custom agent to activate when the session starts.
+     * Must match the `name` of one of the agents in `customAgents`.
+     * Equivalent to calling `session.rpc.agent.select({ name })` after creation.
+     */
+    agent?: string;
+    /**
+     * Directories to load skills from.
+     */
+    skillDirectories?: string[];
+    /**
+     * Local filesystem paths to Open Plugins-format directories
+     * (https://open-plugins.com/) to load for this session.
+     *
+     * Relative paths resolve against `workingDirectory` (or the runtime cwd if
+     * unset); absolute paths are recommended. Invalid entries are logged and
+     * skipped.
+     *
+     * Treated as an explicit opt-in: plugin agents and rules load even when
+     * {@link SessionConfigBase.enableConfigDiscovery} is false. Loaded assets
+     * slot between project (cwd) sources and personal/home sources in the
+     * session-wide precedence order.
+     */
+    pluginDirectories?: string[];
+    /**
+     * Additional directories to search for custom instruction files.
+     */
+    instructionDirectories?: string[];
+    /**
+     * List of skill names to disable.
+     */
+    disabledSkills?: string[];
+    /**
+     * Exact MCP server names to disable for this session. Disabled servers are not
+     * started or authenticated when creating or cold-resuming a session. Supplying
+     * this on a resident resume cannot stop servers that are already running.
+     */
+    disabledMcpServers?: string[];
+    /**
+     * Infinite session configuration for persistent workspaces and automatic compaction.
+     * When enabled (default), sessions automatically manage context limits and persist state.
+     * Set to `{ enabled: false }` to disable.
+     */
+    infiniteSessions?: InfiniteSessionConfig;
+    /**
+     * Memory configuration for the session. When omitted, the runtime default applies.
+     */
+    memory?: MemoryConfiguration;
+    /**
+     * GitHub token for per-session authentication.
+     * When provided, the runtime resolves this token into a full GitHub identity
+     * (login, Copilot plan, endpoints) and stores it on the session. This enables
+     * multitenancy — different sessions can have different GitHub identities.
+     *
+     * This is independent of the client-level `gitHubToken` in {@link CopilotClientOptions},
+     * which authenticates the CLI process itself. The session-level token determines
+     * the identity used for content exclusion, model routing, and quota checks.
+     */
+    gitHubToken?: string;
+    /**
+     * Acquires short-lived GitHub credentials for this session on demand.
+     *
+     * Mutually exclusive with {@link SessionConfigBase.gitHubToken}. The
+     * callback receives the effective GitHub host, the session ID when known,
+     * and whether this is the initial acquisition or a refresh. Its opaque
+     * registration ID remains internal to the SDK.
+     */
+    gitHubTokenProvider?: GitHubTokenProvider;
+    /**
+     * Opt-in: when true, the runtime self-fetches enterprise managed settings
+     * (bypass-permissions policy) at session bootstrap using the session's
+     * `gitHubToken`. Requires {@link SessionConfigBase.gitHubToken} to be set;
+     * if omitted, the runtime is expected to reject session creation (fail-closed).
+     */
+    enableManagedSettings?: boolean;
+    /**
+     * Host-injected enterprise managed settings for this session.
+     *
+     * Unlike {@link SessionConfigBase.enableManagedSettings} — which asks the
+     * runtime to *self-fetch* account/org and device policy — this field lets
+     * the host supply the managed policy directly. The runtime validates it
+     * with the same managed-permission parser it uses for fetched policy and
+     * composes it restrictively with any self-fetched (server) and
+     * device-managed (MDM) layers: `deny`/`ask` rules are unioned, every
+     * declared `allow` list must admit an operation, and bypass-mode
+     * restrictions are composed fail-closed.
+     *
+     * This is startup-only. It is **not** persisted: it must be re-supplied on
+     * {@link CopilotClient.resumeSession | resume}, where it replaces the prior
+     * injected layer (omitting it clears the layer, so warm and cold resume
+     * behave identically). It may be combined with `enableManagedSettings`;
+     * when both are supplied the injected, server, and device restrictions all
+     * apply.
+     *
+     * Requires a Copilot runtime whose RPC schema includes `managedSettings`.
+     * Older runtimes may ignore this additive field, so hosts must not rely on
+     * injected policy until they ship a compatible runtime.
+     */
+    managedSettings?: ManagedSettings;
+    /**
+     * When true, skips embedding-based retrieval for this session.
+     * Use in multitenant deployments to prevent cross-session information leakage
+     * through the shared embedding cache.
+     */
+    skipEmbeddingRetrieval?: boolean;
+    /**
+     * Controls how the embedding cache is stored for this session.
+     * - `"persistent"`: Embeddings are cached on disk and shared across sessions/restarts.
+     * - `"in-memory"`: Embeddings are cached in memory only and discarded when the session ends.
+     */
+    embeddingCacheStorage?: "persistent" | "in-memory";
+    /**
+     * Organization-level custom instructions to include in the system prompt.
+     * Allows hosts to inject organization-specific guidance without relying on
+     * filesystem-based instruction discovery.
+     */
+    organizationCustomInstructions?: string;
+    /**
+     * When true, enables on-demand discovery of instruction files (AGENTS.md,
+     * .github/copilot-instructions.md, etc.) after successful file views.
+     */
+    enableOnDemandInstructionDiscovery?: boolean;
+    /**
+     * When true, enables loading of file-based hooks from `.github/hooks/`.
+     * This is separate from the `hooks` callback parameter which gates SDK
+     * hook event registration.
+     */
+    enableFileHooks?: boolean;
+    /**
+     * When true, enables git operations on the host filesystem (branch detection,
+     * file status, commit history). When false, no git context is surfaced in
+     * the system prompt.
+     */
+    enableHostGitOperations?: boolean;
+    /**
+     * When true, enables the cross-session store for search and retrieval
+     * across sessions. When false, session content is not written to or
+     * read from the shared session store.
+     */
+    enableSessionStore?: boolean;
+    /**
+     * When true, enables skill loading (including builtin skills and discovered
+     * skill directories). When false, no skills are loaded regardless of
+     * `skillDirectories` or `enableConfigDiscovery` settings.
+     */
+    enableSkills?: boolean;
+    /**
+     * Per-session remote behavior control:
+     * - `"off"` — local only, no remote export (default)
+     * - `"export"` — export session events to GitHub without enabling remote steering
+     * - `"on"` — export to GitHub AND enable remote steering
+     */
+    remoteSession?: RemoteSessionMode;
+    /**
+     * Optional event handler that is registered on the session before the
+     * session.create RPC is issued. This guarantees that early events emitted
+     * by the CLI during session creation (e.g. session.start) are delivered to
+     * the handler.
+     *
+     * Equivalent to calling `session.on(handler)` immediately after creation,
+     * but executes earlier in the lifecycle so no events are missed.
+     */
+    onEvent?: SessionEventHandler;
+    /**
+     * Supplies a handler for session filesystem operations. This takes effect
+     * only if {@link CopilotClientOptions.sessionFs} is configured.
+     */
+    createSessionFsProvider?: (session: CopilotSession) => SessionFsProvider;
+}
+/**
+ * Configuration for creating a new session via {@link CopilotClient.createSession}.
+ */
+export interface SessionConfig extends SessionConfigBase {
+    /**
+     * Optional custom session ID. If not provided, the server generates one.
+     */
+    sessionId?: string;
+    /**
+     * Creates a remote session in the cloud instead of a local session.
+     * The optional repository is associated with the cloud session.
+     */
+    cloud?: CloudSessionOptions;
+}
+/**
+ * Configuration for resuming an existing session via
+ * {@link CopilotClient.resumeSession}.
+ */
+export interface ResumeSessionConfig extends SessionConfigBase {
+    /**
+     * When true, skips emitting the session.resume event.
+     * Useful for reconnecting to a session without triggering resume-related side effects.
+     * @default false
+     */
+    suppressResumeEvent?: boolean;
+    /**
+     * When true, the runtime continues any tool calls or permission prompts that were
+     * still pending when the session was last suspended. When false (the default), the
+     * runtime treats pending work as interrupted on resume.
+     *
+     * For permission requests, the runtime re-emits `permission.requested` so the
+     * registered `onPermissionRequest` handler can re-prompt; for external tool calls,
+     * the consumer is expected to supply the result via the corresponding low-level
+     * RPC method.
+     * @default false
+     */
+    continuePendingWork?: boolean;
+    /**
+     * Snapshot of canvases that were already open when the session was suspended.
+     * When provided on resume, the runtime can rehydrate canvas state so consumers
+     * do not need to re-open canvases that were active before the previous shutdown.
+     */
+    openCanvases?: OpenCanvasInstance[];
+}
+/**
+ * Arguments passed to a {@link BearerTokenProvider} callback when the runtime needs a
+ * fresh bearer token for a BYOK provider.
+ *
+ * @experimental Part of the experimental managed-identity / bearer-token-provider
+ * surface and may change or be removed in future SDK or CLI releases.
+ */
+export interface ProviderTokenArgs {
+    /**
+     * Name of the BYOK provider needing a token. For the singular, whole-session
+     * {@link ProviderConfig} this is the implicit provider name (`"default"`); for
+     * {@link NamedProviderConfig} entries it is {@link NamedProviderConfig.name}.
+     *
+     * The callback closes over its own token scope/audience; the runtime is
+     * provider-agnostic and forwards only the provider name.
+     */
+    readonly providerName: string;
+    /**
+     * Id of the session that triggered this token request. A client-level shared
+     * callback registered for many sessions can use this to resolve the owning
+     * session (e.g. via the client's session lookup) to scope token acquisition
+     * or caching per session.
+     */
+    readonly sessionId: string;
+}
+/**
+ * Per-provider callback that resolves a bearer token on demand, returning the
+ * raw token string (without the `Bearer ` prefix). The Copilot SDK itself takes
+ * no Azure dependency: the consumer supplies this callback backed by their own
+ * identity library (for example `@azure/identity`'s
+ * `DefaultAzureCredential.getToken(scope)`), and the runtime calls it once before
+ * each outbound model request. The runtime does no caching of its own, so the
+ * callback (or the identity library it wraps) owns token caching and refresh.
+ *
+ * @experimental Part of the experimental managed-identity / bearer-token-provider
+ * surface and may change or be removed in future SDK or CLI releases.
+ */
+export type BearerTokenProvider = (args: ProviderTokenArgs) => Promise<string>;
+/**
+ * Configuration for a custom API provider.
+ */
+export interface ProviderConfig {
+    /**
+     * Provider type. Defaults to "openai" for generic OpenAI-compatible APIs.
+     */
+    type?: "openai" | "azure" | "anthropic";
+    /**
+     * API format (openai/azure only). Defaults to "completions".
+     */
+    wireApi?: "completions" | "responses";
+    /**
+     * Transport for OpenAI Responses requests. Defaults to "http".
+     *
+     * Set to "websockets" to deliver Responses API requests over a persistent
+     * WebSocket connection instead of HTTP. Useful for long-running,
+     * tool-call-heavy sessions that benefit from incremental
+     * `previous_response_id` continuations. Applies to OpenAI-compatible
+     * providers using `wireApi: "responses"`.
+     */
+    transport?: "http" | "websockets";
+    /**
+     * API endpoint URL
+     */
+    baseUrl: string;
+    /**
+     * API key. Optional for local providers like Ollama.
+     */
+    apiKey?: string;
+    /**
+     * Bearer token for authentication. Sets the Authorization header directly.
+     * Use this for services requiring bearer token auth instead of API key.
+     * Takes precedence over apiKey when both are set.
+     */
+    bearerToken?: string;
+    /**
+     * Per-request bearer-token provider for managed-identity / on-demand auth.
+     * When set, the SDK keeps this function client-side (it is never serialized)
+     * and the runtime calls back into this client to acquire a token before each
+     * outbound request. The runtime does no caching of its own, so the callback
+     * owns token caching and refresh. When set alongside {@link apiKey} /
+     * {@link bearerToken}, this callback takes precedence: the runtime applies
+     * the token it returns as the `Authorization: Bearer` header for each
+     * request and does not send the static credential.
+     *
+     * @experimental
+     */
+    bearerTokenProvider?: BearerTokenProvider;
+    /**
+     * Azure-specific options
+     */
+    azure?: {
+        /**
+         * API version. When omitted, the runtime uses the GA versionless v1 route.
+         */
+        apiVersion?: string;
+    };
+    /**
+     * Custom HTTP headers to include in outbound provider requests.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Well-known model name used by the runtime to look up agent configuration
+     * (tools, prompts, reasoning behavior) and default token limits. Also used
+     * as the wire model when {@link wireModel} is not set.
+     * Falls back to {@link SessionConfig.model}.
+     */
+    modelId?: string;
+    /**
+     * Model name sent to the provider API for inference. Use this when the
+     * provider's model name (e.g. an Azure deployment name or a custom
+     * fine-tune name) differs from {@link modelId}.
+     * Falls back to {@link modelId}, then {@link SessionConfig.model}.
+     */
+    wireModel?: string;
+    /**
+     * Overrides the resolved model's default max prompt tokens. The runtime
+     * triggers conversation compaction before sending a request when the
+     * prompt (system message, history, tool definitions, user message) would
+     * exceed this limit.
+     */
+    maxPromptTokens?: number;
+    /**
+     * Overrides the resolved model's default max output tokens. When hit, the
+     * model stops generating and returns a truncated response.
+     */
+    maxOutputTokens?: number;
+}
+/**
+ * A named BYOK provider connection (transport + credentials only), referenced by
+ * {@link ProviderModelConfig} entries via {@link NamedProviderConfig.name}.
+ *
+ * Unlike the singular, whole-session {@link ProviderConfig} — which bypasses
+ * Copilot API authentication — named providers are **additive** and coexist with
+ * Copilot API auth, so CAPI and BYOK models can be mixed within one session and
+ * across sub-agents. See {@link SessionConfigBase.providers}.
+ *
+ * @experimental This type is part of an experimental multi-provider BYOK surface
+ * and may change or be removed in future SDK or CLI releases.
+ */
+export interface NamedProviderConfig {
+    /**
+     * Stable identifier referenced by {@link ProviderModelConfig.provider}.
+     * Must not contain `/`.
+     */
+    name: string;
+    /**
+     * Provider type. Defaults to "openai" for generic OpenAI-compatible APIs.
+     */
+    type?: "openai" | "azure" | "anthropic";
+    /**
+     * Wire API format (openai/azure only). Defaults to "completions".
+     */
+    wireApi?: "completions" | "responses";
+    /**
+     * API endpoint URL.
+     */
+    baseUrl: string;
+    /**
+     * API key. Optional for local providers like Ollama.
+     */
+    apiKey?: string;
+    /**
+     * Bearer token for authentication. Sets the Authorization header directly.
+     * Takes precedence over {@link apiKey} when both are set.
+     */
+    bearerToken?: string;
+    /**
+     * Per-request bearer-token provider for managed-identity / on-demand auth.
+     * When set, the SDK keeps this function client-side (it is never serialized)
+     * and the runtime calls back into this client to acquire a token before each
+     * outbound request. The runtime does no caching of its own, so the callback
+     * owns token caching and refresh. When set alongside {@link apiKey} /
+     * {@link bearerToken}, this callback takes precedence: the runtime applies
+     * the token it returns as the `Authorization: Bearer` header for each
+     * request and does not send the static credential.
+     *
+     * @experimental
+     */
+    bearerTokenProvider?: BearerTokenProvider;
+    /**
+     * Azure-specific options.
+     */
+    azure?: {
+        /**
+         * API version. When set, uses the versioned deployment route. When
+         * omitted, uses the GA versionless v1 route.
+         */
+        apiVersion?: string;
+    };
+    /**
+     * Custom HTTP headers to include in all outbound requests to the provider.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * A BYOK model definition that references a {@link NamedProviderConfig} by name
+ * and is added to the session's selectable model list.
+ *
+ * Each model has three identities:
+ *  - {@link id}: the provider-local model id, unique within its provider. The
+ *    session-wide selection id (shown in the model list and passed to model
+ *    switching) is the provider-qualified `provider/id`.
+ *  - {@link modelId}: the well-known behavior base model used for
+ *    capability/config lookup. Defaults to {@link id}.
+ *  - {@link wireModel}: the model name actually sent to the provider API for
+ *    inference. Defaults to {@link id}.
+ *
+ * @experimental This type is part of an experimental multi-provider BYOK surface
+ * and may change or be removed in future SDK or CLI releases.
+ */
+export interface ProviderModelConfig {
+    /**
+     * Provider-local model id, unique within its provider. The session-wide
+     * selection id is the provider-qualified `provider/id`.
+     */
+    id: string;
+    /**
+     * Name of the {@link NamedProviderConfig} that serves this model.
+     */
+    provider: string;
+    /**
+     * The model name sent to the provider API for inference. Defaults to {@link id}.
+     */
+    wireModel?: string;
+    /**
+     * Well-known base model id used for behavior/capability/config lookup.
+     * Defaults to {@link id}.
+     */
+    modelId?: string;
+    /**
+     * Display name for model pickers. Defaults to the provider-qualified
+     * selection id (`provider/id`).
+     */
+    name?: string;
+    /**
+     * Maximum prompt/input tokens for the model.
+     */
+    maxPromptTokens?: number;
+    /**
+     * Maximum context window tokens for the model.
+     */
+    maxContextWindowTokens?: number;
+    /**
+     * Maximum output tokens for the model.
+     */
+    maxOutputTokens?: number;
+    /**
+     * Optional capability overrides (vision, tool_calls, reasoning, etc.) for
+     * the synthesized model.
+     */
+    capabilities?: ModelCapabilitiesOverride;
+}
+export interface MessageOptions {
+    /**
+     * The prompt/message to send
+     */
+    prompt: string;
+    /**
+     * File, directory, selection, or blob attachments
+     */
+    attachments?: Array<{
+        type: "file";
+        path: string;
+        displayName?: string;
+    } | {
+        type: "directory";
+        path: string;
+        displayName?: string;
+    } | {
+        type: "selection";
+        filePath: string;
+        displayName: string;
+        selection?: {
+            start: {
+                line: number;
+                character: number;
+            };
+            end: {
+                line: number;
+                character: number;
+            };
+        };
+        text?: string;
+    } | {
+        type: "blob";
+        data: string;
+        mimeType: string;
+        displayName?: string;
+    }>;
+    /**
+     * Message delivery mode
+     * - "enqueue": Add to queue (default)
+     * - "immediate": Send immediately
+     */
+    mode?: "enqueue" | "immediate";
+    /**
+     * The UI mode the agent was in when this message was sent (for example "plan" or "autopilot").
+     * Defaults to the session's current mode when unset.
+     */
+    agentMode?: "interactive" | "plan" | "autopilot" | "shell";
+    /**
+     * Custom HTTP headers to include in outbound model requests for this turn.
+     */
+    requestHeaders?: Record<string, string>;
+    /**
+     * If provided, this is shown in the timeline instead of `prompt`.
+     */
+    displayPrompt?: string;
+}
+/**
+ * All possible event type strings from SessionEvent
+ */
+export type SessionEventType = SessionEvent["type"];
+/**
+ * Extract the specific event payload for a given event type
+ */
+export type SessionEventPayload<T extends SessionEventType> = Extract<SessionEvent, {
+    type: T;
+}>;
+/**
+ * Event handler for a specific event type
+ */
+export type TypedSessionEventHandler<T extends SessionEventType> = (event: SessionEventPayload<T>) => void;
+/**
+ * Event handler callback type (for all events)
+ */
+export type SessionEventHandler = (event: SessionEvent) => void;
+/**
+ * Working directory context for a session
+ */
+export interface SessionContext {
+    /** Working directory where the session was created */
+    workingDirectory: string;
+    /** Git repository root (if in a git repo) */
+    gitRoot?: string;
+    /** GitHub repository in "owner/repo" format */
+    repository?: string;
+    /** Current git branch */
+    branch?: string;
+}
+/**
+ * Configuration for a custom session filesystem provider.
+ */
+export interface SessionFsConfig {
+    /**
+     * Initial working directory for sessions (user's project directory).
+     */
+    initialCwd: string;
+    /**
+     * Path within each session's SessionFs where the runtime stores
+     * session-scoped files (events, workspace, checkpoints, etc.).
+     */
+    sessionStatePath: string;
+    /**
+     * Path conventions used by this filesystem provider.
+     */
+    conventions: "windows" | "posix";
+    /**
+     * Optional capabilities declared by this provider.
+     * The runtime uses these to determine which features are available.
+     */
+    capabilities?: {
+        /**
+         * Whether this provider supports SQLite query/exists operations.
+         * When false or omitted, the runtime will not offer SQL tools or
+         * todo tracking for sessions using this provider.
+         * @default false
+         */
+        sqlite?: boolean;
+    };
+}
+/**
+ * Filter options for listing sessions
+ */
+export interface SessionListFilter {
+    /** Filter by exact working directory match */
+    workingDirectory?: string;
+    /** Filter by git root */
+    gitRoot?: string;
+    /** Filter by repository (owner/repo format) */
+    repository?: string;
+    /** Filter by branch */
+    branch?: string;
+}
+/**
+ * Metadata about a session
+ */
+export interface SessionMetadata {
+    sessionId: string;
+    startTime: Date;
+    modifiedTime: Date;
+    summary?: string;
+    isRemote: boolean;
+    /** Working directory context (working directory, git info) from session creation */
+    context?: SessionContext;
+}
+/**
+ * Response from status.get
+ */
+export interface GetStatusResponse {
+    /** Package version (e.g., "1.0.0") */
+    version: string;
+    /** Protocol version for SDK compatibility */
+    protocolVersion: number;
+}
+/**
+ * Response from auth.getStatus
+ */
+export interface GetAuthStatusResponse {
+    /** Whether the user is authenticated */
+    isAuthenticated: boolean;
+    /** Authentication type */
+    authType?: "user" | "env" | "gh-cli" | "hmac" | "api-key" | "token";
+    /** GitHub host URL */
+    host?: string;
+    /** User login name */
+    login?: string;
+    /** Human-readable status message */
+    statusMessage?: string;
+}
+/**
+ * Model capabilities and limits
+ */
+export interface ModelCapabilities {
+    supports: {
+        vision: boolean;
+        /** Whether this model supports reasoning effort configuration */
+        reasoningEffort: boolean;
+    };
+    limits: {
+        max_prompt_tokens?: number;
+        max_context_window_tokens: number;
+        vision?: {
+            supported_media_types: string[];
+            max_prompt_images: number;
+            max_prompt_image_size: number;
+        };
+    };
+}
+/** Recursively makes all properties optional, preserving arrays as-is. */
+type DeepPartial<T> = T extends readonly (infer U)[] ? DeepPartial<U>[] : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/** Deep-partial override for model capabilities — every property at any depth is optional. */
+export type ModelCapabilitiesOverride = DeepPartial<ModelCapabilities>;
+/**
+ * Model policy state
+ */
+export interface ModelPolicy {
+    state: "enabled" | "disabled" | "unconfigured";
+    terms: string;
+}
+/**
+ * Model billing information
+ */
+export interface ModelBilling {
+    /** Billing cost multiplier relative to the base rate */
+    multiplier?: number;
+    /** Token-level pricing information for this model */
+    tokenPrices?: ModelBillingTokenPrices;
+}
+/**
+ * Information about an available model
+ */
+export interface ModelInfo {
+    /** Model identifier (e.g., "claude-sonnet-4.5") */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Model capabilities and limits */
+    capabilities: ModelCapabilities;
+    /** Policy state */
+    policy?: ModelPolicy;
+    /** Billing information */
+    billing?: ModelBilling;
+    /** Supported reasoning effort levels (only present if model supports reasoning effort) */
+    supportedReasoningEfforts?: ReasoningEffort[];
+    /** Default reasoning effort level (only present if model supports reasoning effort) */
+    defaultReasoningEffort?: ReasoningEffort;
+}
+/**
+ * Types of session lifecycle events.
+ */
+export type SessionLifecycleEventType = "session.created" | "session.deleted" | "session.updated" | "session.foreground" | "session.background";
+/**
+ * Metadata payload for session lifecycle events. Not present on
+ * `session.deleted` events.
+ */
+export interface SessionLifecycleEventMetadata {
+    /** Time the session was created. */
+    startTime: Date;
+    /** Time the session was last modified. */
+    modifiedTime: Date;
+    /** Human-readable summary of the session, if available. */
+    summary?: string;
+}
+/** Base shape shared by every lifecycle event variant. */
+interface SessionLifecycleEventBase {
+    /** ID of the session this event relates to. */
+    sessionId: string;
+    /** Session metadata (not included for `session.deleted`). */
+    metadata?: SessionLifecycleEventMetadata;
+}
+/** Emitted when a new session is created. */
+export interface SessionCreatedEvent extends SessionLifecycleEventBase {
+    type: "session.created";
+    metadata: SessionLifecycleEventMetadata;
+}
+/** Emitted when a session is deleted. The metadata field is omitted. */
+export interface SessionDeletedEvent extends SessionLifecycleEventBase {
+    type: "session.deleted";
+    metadata?: undefined;
+}
+/** Emitted when a session's metadata is updated. */
+export interface SessionUpdatedEvent extends SessionLifecycleEventBase {
+    type: "session.updated";
+    metadata: SessionLifecycleEventMetadata;
+}
+/** Emitted when a session is brought to the foreground (TUI+server mode). */
+export interface SessionForegroundEvent extends SessionLifecycleEventBase {
+    type: "session.foreground";
+    metadata: SessionLifecycleEventMetadata;
+}
+/** Emitted when a session is moved to the background (TUI+server mode). */
+export interface SessionBackgroundEvent extends SessionLifecycleEventBase {
+    type: "session.background";
+    metadata: SessionLifecycleEventMetadata;
+}
+/**
+ * Discriminated union of all session lifecycle events emitted in TUI+server mode.
+ * Switch on `type` to access the variant-specific metadata.
+ */
+export type SessionLifecycleEvent = SessionCreatedEvent | SessionDeletedEvent | SessionUpdatedEvent | SessionForegroundEvent | SessionBackgroundEvent;
+/**
+ * Handler for session lifecycle events.
+ */
+export type SessionLifecycleHandler = (event: SessionLifecycleEvent) => void;
+/**
+ * Typed handler for specific session lifecycle event types.
+ */
+export type TypedSessionLifecycleHandler<K extends SessionLifecycleEventType> = (event: Extract<SessionLifecycleEvent, {
+    type: K;
+}>) => void;
+/**
+ * Information about the foreground session in TUI+server mode
+ */
+export interface ForegroundSessionInfo {
+    /** ID of the foreground session, or undefined if none */
+    sessionId?: string;
+    /** Workspace path of the foreground session */
+    workspacePath?: string;
+}