@github/copilot-sdk 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/types.d.ts

@@ -1,13 +1,22 @@
 /**
  * Type definitions for the Copilot SDK
  */
+import type { Canvas } from "./canvas.js";
 import type { SessionFsProvider } from "./sessionFsProvider.js";
-import type { SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
+import type { ReasoningSummary, SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
 import type { CopilotSession } from "./session.js";
+import type { RemoteSessionMode } from "./generated/rpc.js";
+import type { OpenCanvasInstance } from "./generated/rpc.js";
+import type { ToolSet } from "./toolSet.js";
+export type { RemoteSessionMode } from "./generated/rpc.js";
 export type SessionEvent = GeneratedSessionEvent;
+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";
 /**
  * Options for creating a CopilotClient
  */
@@ -43,80 +52,146 @@ export interface TelemetryConfig {
     /** Whether to capture message content (prompts, responses). Sets OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT. */
     captureContent?: boolean;
 }
-export interface CopilotClientOptions {
+/**
+ * Configures how a {@link CopilotClient} connects to the Copilot runtime.
+ * Construct via the factory functions on {@link RuntimeConnection}.
+ */
+export type RuntimeConnection = StdioRuntimeConnection | TcpRuntimeConnection | UriRuntimeConnection;
+/**
+ * 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 {
+    readonly kind: "stdio";
+    /** 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[];
+}
+/**
+ * Spawns a runtime child process that listens on a TCP socket and connects to it.
+ */
+export interface TcpRuntimeConnection {
+    readonly kind: "tcp";
     /**
-     * Path to the CLI executable or JavaScript entry point.
-     * If not specified, uses the bundled CLI from the @github/copilot package.
+     * TCP port to listen on. `0` (the default) auto-allocates a free port.
+     * If the chosen port is already in use, startup fails.
      */
-    cliPath?: string;
+    readonly port?: number;
     /**
-     * Extra arguments to pass to the CLI executable (inserted before SDK-managed args)
+     * 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.
      */
-    cliArgs?: string[];
+    readonly connectionToken?: string;
+    /** 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[];
+}
+/**
+ * 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";
     /**
-     * Working directory for the CLI process
-     * If not set, inherits the current process's working directory
+     * URL of the runtime to connect to. Accepts `"port"`, `"host:port"`, or a
+     * full URL (`"http://host:port"`).
      */
-    cwd?: string;
+    readonly url: string;
+    /** Optional shared secret to authenticate the connection. */
+    readonly connectionToken?: string;
+}
+/** Factory functions for constructing {@link RuntimeConnection} instances. */
+export declare const RuntimeConnection: {
     /**
-     * Base directory for Copilot data (session state, config, etc.).
-     * Sets the COPILOT_HOME environment variable on the spawned CLI process.
-     * When not set, the CLI defaults to ~/.copilot.
-     * This option is only used when the SDK spawns the CLI process; it is ignored
-     * when connecting to an external server via {@link cliUrl}.
+     * Spawn a runtime child process and communicate over its stdin/stdout.
+     * This is the default if no {@link CopilotClientOptions.connection} is set.
      */
-    copilotHome?: string;
+    readonly forStdio: (opts?: {
+        path?: string;
+        args?: readonly string[];
+    }) => StdioRuntimeConnection;
     /**
-     * Port for the CLI server (TCP mode only)
-     * @default 0 (random available port)
+     * Spawn a runtime child process that listens on a TCP socket and connect to it.
      */
-    port?: number;
+    readonly forTcp: (opts?: {
+        port?: number;
+        connectionToken?: string;
+        path?: string;
+        args?: readonly string[];
+    }) => TcpRuntimeConnection;
     /**
-     * Use stdio transport instead of TCP
-     * When true, communicates with CLI via stdin/stdout pipes
-     * @default true
+     * Connect to an already-running runtime at the given URL. The SDK does not
+     * spawn a process in this mode.
      */
-    useStdio?: boolean;
+    readonly forUri: (url: string, opts?: {
+        connectionToken?: string;
+    }) => UriRuntimeConnection;
+};
+/**
+ * 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 {
     /**
-     * When true, indicates the SDK is running as a child process of the Copilot CLI server, and should
-     * use its own stdio for communicating with the existing parent process. Can only be used in combination
-     * with useStdio: true.
+     * How to connect to the Copilot runtime. When omitted, defaults to
+     * {@link RuntimeConnection.forStdio} with the bundled runtime.
      */
-    isChildProcess?: boolean;
+    connection?: RuntimeConnection;
     /**
-     * URL of an existing Copilot CLI server to connect to over TCP
-     * When provided, the client will not spawn a CLI process
-     * Format: "host:port" or "http://host:port" or just "port" (defaults to localhost)
-     * Examples: "localhost:8080", "http://127.0.0.1:9000", "8080"
-     * Mutually exclusive with cliPath, useStdio
+     * 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"
      */
-    cliUrl?: string;
+    mode?: CopilotClientMode;
     /**
-     * Log level for the CLI server
+     * Working directory for the runtime process.
+     * If not set, inherits the current process's working directory.
      */
-    logLevel?: "none" | "error" | "warning" | "info" | "debug" | "all";
+    workingDirectory?: string;
     /**
-     * Auto-start the CLI server on first use
-     * @default true
+     * 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}.
      */
-    autoStart?: boolean;
+    baseDirectory?: string;
     /**
-     * @deprecated This option has no effect and will be removed in a future release.
+     * Log level for the Copilot runtime. When omitted, the runtime uses its
+     * own default (currently `"info"`).
      */
-    autoRestart?: boolean;
+    logLevel?: "none" | "error" | "warning" | "info" | "debug" | "all";
     /**
-     * Environment variables to pass to the CLI process. If not set, inherits process.env.
+     * 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 CLI server via environment variable.
+     * 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 CLI server will attempt to use stored OAuth tokens or gh CLI auth.
+     * 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)
      */
@@ -124,14 +199,14 @@ export interface CopilotClientOptions {
     /**
      * Custom handler for listing available models.
      * When provided, client.listModels() calls this handler instead of
-     * querying the CLI server. Useful in BYOK mode to return models
+     * querying the runtime. Useful in BYOK mode to return models
      * available from your custom provider.
      */
     onListModels?: () => Promise<ModelInfo[]> | ModelInfo[];
     /**
-     * OpenTelemetry configuration for the CLI process.
+     * OpenTelemetry configuration for the runtime process.
      * When provided, the corresponding OTel environment variables are set
-     * on the spawned CLI server.
+     * on the spawned runtime.
      */
     telemetry?: TelemetryConfig;
     /**
@@ -170,18 +245,18 @@ export interface CopilotClientOptions {
      * 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).
-     * This option is only used when the SDK spawns the CLI process; it is ignored
-     * when connecting to an external server via {@link cliUrl}.
+     * Ignored when connecting to an existing runtime via {@link RuntimeConnection.forUri}.
      * @default undefined (disabled)
      */
     sessionIdleTimeoutSeconds?: number;
     /**
-     * Connection token for the headless CLI server (TCP only). When the SDK
-     * spawns its own CLI in TCP mode and this is omitted, a UUID is generated
-     * automatically so the loopback listener is safe by default. Rejected with
-     * `useStdio: true` (stdio is pre-authenticated by transport).
+     * 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
      */
-    tcpConnectionToken?: string;
+    enableRemoteSessions?: boolean;
 }
 /**
  * Configuration for creating a session
@@ -190,18 +265,33 @@ export type ToolResultType = "success" | "failure" | "rejected" | "denied" | "ti
 export type ToolBinaryResult = {
     data: string;
     mimeType: string;
-    type: string;
+    type: "image" | "resource";
     description?: string;
 };
+export type ToolTelemetry = Record<string, Record<string, unknown> | undefined>;
 export type ToolResultObject = {
     textResultForLlm: string;
     binaryResultsForLlm?: ToolBinaryResult[];
     resultType: ToolResultType;
     error?: string;
     sessionLog?: string;
-    toolTelemetry?: Record<string, unknown>;
+    toolTelemetry?: ToolTelemetry;
 };
 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.
  */
@@ -260,12 +350,16 @@ export interface ZodSchema<T = unknown> {
  * - 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>;
+    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
@@ -284,7 +378,7 @@ export interface Tool<TArgs = unknown> {
 export declare function defineTool<T = unknown>(name: string, config: {
     description?: string;
     parameters?: ZodSchema<T> | Record<string, unknown>;
-    handler: ToolHandler<T>;
+    handler?: ToolHandler<T>;
     overridesBuiltInTool?: boolean;
     skipPermission?: boolean;
 }): Tool<T>;
@@ -325,6 +419,19 @@ 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;
     };
 }
 /**
@@ -449,7 +556,7 @@ export type ElicitationHandler = (context: ElicitationContext) => Promise<Elicit
 /**
  * Options for the `input()` convenience method.
  */
-export interface InputOptions {
+export interface UiInputOptions {
     /** Title label for the input field. */
     title?: string;
     /** Descriptive text shown below the field. */
@@ -490,7 +597,7 @@ export interface SessionUiApi {
      * Returns the entered text, or `null` if the user declines/cancels.
      * @throws Error if the host does not support elicitation.
      */
-    input(message: string, options?: InputOptions): Promise<string | null>;
+    input(message: string, options?: UiInputOptions): Promise<string | null>;
 }
 export interface ToolCallRequestPayload {
     sessionId: string;
@@ -502,12 +609,12 @@ export interface ToolCallResponsePayload {
     result: ToolResult;
 }
 /**
- * Known system prompt section identifiers for the "customize" mode.
+ * Known system message section identifiers for the "customize" mode.
  * Each section corresponds to a distinct part of the system prompt.
  */
-export type SystemPromptSection = "identity" | "tone" | "tool_efficiency" | "environment_context" | "code_change_rules" | "guidelines" | "safety" | "tool_instructions" | "custom_instructions" | "last_instructions";
+export type SystemMessageSection = "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_PROMPT_SECTIONS: Record<SystemPromptSection, {
+export declare const SYSTEM_MESSAGE_SECTIONS: Record<SystemMessageSection, {
     description: string;
 }>;
 /**
@@ -525,7 +632,7 @@ export type SectionTransformFn = (currentContent: string) => string | Promise<st
  */
 export type SectionOverrideAction = "replace" | "remove" | "append" | "prepend" | SectionTransformFn;
 /**
- * Override operation for a single system prompt section.
+ * Override operation for a single system message section.
  */
 export interface SectionOverride {
     /**
@@ -574,7 +681,7 @@ export interface SystemMessageCustomizeConfig {
      * 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<SystemPromptSection, SectionOverride>>;
+    sections?: Partial<Record<SystemMessageSection, SectionOverride>>;
     /**
      * Additional content appended after all sections.
      * Equivalent to append mode's content field — provided for convenience.
@@ -589,13 +696,20 @@ export interface SystemMessageCustomizeConfig {
  */
 export type SystemMessageConfig = SystemMessageAppendConfig | SystemMessageReplaceConfig | SystemMessageCustomizeConfig;
 /**
- * Permission request types from the server
+ * 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`).
  */
-export interface PermissionRequest {
-    kind: "shell" | "write" | "mcp" | "read" | "url" | "custom-tool" | "memory" | "hook";
-    toolCallId?: string;
-}
+export type { PermissionRequest } from "./generated/session-events.js";
+import type { PermissionRequest } from "./generated/session-events.js";
 import type { PermissionDecisionRequest } from "./generated/rpc.js";
+/**
+ * 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";
 };
@@ -641,12 +755,65 @@ export interface UserInputResponse {
 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 {
-    timestamp: number;
-    cwd: string;
+    /** 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
@@ -671,6 +838,34 @@ export interface PreToolUseHookOutput {
 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
  */
@@ -693,6 +888,47 @@ export interface PostToolUseHookOutput {
 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
  */
@@ -787,9 +1023,24 @@ export interface SessionHooks {
      */
     onPreToolUse?: PreToolUseHandler;
     /**
-     * Called after a tool is executed
+     * 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
      */
@@ -812,9 +1063,11 @@ export interface SessionHooks {
  */
 interface MCPServerConfigBase {
     /**
-     * List of tools to include from this server. [] means none. "*" means all.
+     * List of tools to include from this server.
+     * `undefined` (the default) or `["*"]` means include all tools.
+     * `[]` means include none.
      */
-    tools: string[];
+    tools?: string[];
     /**
      * Indicates the server type: "stdio" for local/subprocess servers, "http"/"sse" for remote servers.
      * If not specified, defaults to "stdio".
@@ -831,12 +1084,15 @@ interface MCPServerConfigBase {
 export interface MCPStdioServerConfig extends MCPServerConfigBase {
     type?: "local" | "stdio";
     command: string;
-    args: string[];
+    args?: string[];
     /**
      * Environment variables to pass to the server.
      */
     env?: Record<string, string>;
-    cwd?: string;
+    /**
+     * Working directory for the server process.
+     */
+    workingDirectory?: string;
 }
 /**
  * Configuration for a remote MCP server (HTTP or SSE).
@@ -898,6 +1154,12 @@ export interface CustomAgentConfig {
      * 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;
 }
 /**
  * Configuration for the default agent (the built-in agent that handles
@@ -938,15 +1200,52 @@ export interface InfiniteSessionConfig {
     bufferExhaustionThreshold?: number;
 }
 /**
- * Valid reasoning effort levels for models that support it.
+ * 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 type ReasoningEffort = "low" | "medium" | "high" | "xhigh";
-export interface SessionConfig {
+export interface LargeToolOutputConfig {
     /**
-     * Optional custom session ID
-     * If not provided, server will generate one
+     * Whether large output handling is enabled.
+     * @default true
      */
-    sessionId?: string;
+    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";
+/**
+ * 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";
+/**
+ * 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;
+}
+/**
+ * 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.
@@ -962,13 +1261,30 @@ export interface SessionConfig {
      * 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;
+    /**
+     * 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.
      */
-    configDir?: string;
+    configDirectory?: string;
     /**
      * When true, automatically discovers MCP server configurations (e.g. `.mcp.json`,
      * `.vscode/mcp.json`) and skill directories from the working directory and merges
@@ -982,9 +1298,51 @@ export interface SessionConfig {
      */
     enableConfigDiscovery?: boolean;
     /**
-     * Tools exposed to the CLI server
+     * 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;
     /**
      * Slash commands registered for this session.
      * When the CLI has a TUI, each command appears as `/name` for the user to invoke.
@@ -998,24 +1356,78 @@ export interface SessionConfig {
     systemMessage?: SystemMessageConfig;
     /**
      * List of tool names to allow. When specified, only these tools will be available.
-     * Takes precedence over excludedTools.
+     *
+     * 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[];
+    availableTools?: string[] | ToolSet;
     /**
-     * List of tool names to disable. All other tools remain available.
-     * Ignored if availableTools is specified.
+     * 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[];
+    excludedTools?: string[] | ToolSet;
     /**
      * Custom provider configuration (BYOK - Bring Your Own Key).
      * When specified, uses the provided API endpoint instead of the Copilot API.
      */
     provider?: ProviderConfig;
     /**
-     * Handler for permission requests from the server.
-     * When provided, the server will call this handler to request permission for operations.
+     * 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}.
      */
-    onPermissionRequest: PermissionHandler;
+    enableSessionTelemetry?: boolean;
+    /**
+     * 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;
     /**
      * Handler for user input requests from the agent.
      * When provided, enables the ask_user tool allowing the agent to ask questions.
@@ -1027,6 +1439,43 @@ export interface SessionConfig {
      * 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;
+    /**
+     * 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.
@@ -1037,6 +1486,13 @@ export interface SessionConfig {
      * Tool operations will be relative to this directory.
      */
     workingDirectory?: 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
@@ -1048,6 +1504,14 @@ export interface SessionConfig {
      * @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.
@@ -1074,6 +1538,20 @@ export interface SessionConfig {
      * 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.
      */
@@ -1099,6 +1577,60 @@ export interface SessionConfig {
      * the identity used for content exclusion, model routing, and quota checks.
      */
     gitHubToken?: string;
+    /**
+     * 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
@@ -1113,18 +1645,33 @@ export interface SessionConfig {
      * Supplies a handler for session filesystem operations. This takes effect
      * only if {@link CopilotClientOptions.sessionFs} is configured.
      */
-    createSessionFsHandler?: (session: CopilotSession) => SessionFsProvider;
+    createSessionFsProvider?: (session: CopilotSession) => SessionFsProvider;
 }
 /**
- * Configuration for resuming a session
+ * Configuration for creating a new session via {@link CopilotClient.createSession}.
  */
-export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "tools" | "commands" | "systemMessage" | "availableTools" | "excludedTools" | "provider" | "modelCapabilities" | "streaming" | "includeSubAgentStreamingEvents" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "onElicitationRequest" | "hooks" | "workingDirectory" | "configDir" | "enableConfigDiscovery" | "mcpServers" | "customAgents" | "defaultAgent" | "agent" | "skillDirectories" | "instructionDirectories" | "disabledSkills" | "infiniteSessions" | "gitHubToken" | "onEvent" | "createSessionFsHandler"> & {
+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
      */
-    disableResume?: boolean;
+    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
@@ -1137,7 +1684,13 @@ export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "
      * @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[];
+}
 /**
  * Configuration for a custom API provider.
  */
@@ -1177,6 +1730,32 @@ export interface ProviderConfig {
      * 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;
 }
 /**
  * Options for sending a message to a session
@@ -1224,10 +1803,19 @@ export interface MessageOptions {
      * - "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
@@ -1247,16 +1835,12 @@ export type TypedSessionEventHandler<T extends SessionEventType> = (event: Sessi
  * Event handler callback type (for all events)
  */
 export type SessionEventHandler = (event: SessionEvent) => void;
-/**
- * Connection state
- */
-export type ConnectionState = "disconnected" | "connecting" | "connected" | "error";
 /**
  * Working directory context for a session
  */
 export interface SessionContext {
     /** Working directory where the session was created */
-    cwd: string;
+    workingDirectory: string;
     /** Git repository root (if in a git repo) */
     gitRoot?: string;
     /** GitHub repository in "owner/repo" format */
@@ -1281,13 +1865,26 @@ export interface SessionFsConfig {
      * 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 cwd match */
-    cwd?: string;
+    /** Filter by exact working directory match */
+    workingDirectory?: string;
     /** Filter by git root */
     gitRoot?: string;
     /** Filter by repository (owner/repo format) */
@@ -1304,7 +1901,7 @@ export interface SessionMetadata {
     modifiedTime: Date;
     summary?: string;
     isRemote: boolean;
-    /** Working directory context (cwd, git info) from session creation */
+    /** Working directory context (working directory, git info) from session creation */
     context?: SessionContext;
 }
 /**
@@ -1367,7 +1964,7 @@ export interface ModelPolicy {
  * Model billing information
  */
 export interface ModelBilling {
-    multiplier: number;
+    multiplier?: number;
 }
 /**
  * Information about an available model
@@ -1389,35 +1986,68 @@ export interface ModelInfo {
     defaultReasoningEffort?: ReasoningEffort;
 }
 /**
- * Types of session lifecycle events
+ * Types of session lifecycle events.
  */
 export type SessionLifecycleEventType = "session.created" | "session.deleted" | "session.updated" | "session.foreground" | "session.background";
 /**
- * Session lifecycle event notification
- * Sent when sessions are created, deleted, updated, or change foreground/background state
+ * Metadata payload for session lifecycle events. Not present on
+ * `session.deleted` events.
  */
-export interface SessionLifecycleEvent {
-    /** Type of lifecycle event */
-    type: SessionLifecycleEventType;
-    /** ID of the session this event relates to */
+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 deleted sessions) */
-    metadata?: {
-        startTime: string;
-        modifiedTime: string;
-        summary?: 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
+ * Handler for session lifecycle events.
  */
 export type SessionLifecycleHandler = (event: SessionLifecycleEvent) => void;
 /**
- * Typed handler for specific session lifecycle event types
+ * Typed handler for specific session lifecycle event types.
  */
-export type TypedSessionLifecycleHandler<K extends SessionLifecycleEventType> = (event: SessionLifecycleEvent & {
+export type TypedSessionLifecycleHandler<K extends SessionLifecycleEventType> = (event: Extract<SessionLifecycleEvent, {
     type: K;
-}) => void;
+}>) => void;
 /**
  * Information about the foreground session in TUI+server mode
  */