@github/copilot-sdk 0.2.1-preview.1 → 0.2.1-unstable.0

package/README.md

@@ -120,6 +120,7 @@ Create a new conversation session.
 - `provider?: ProviderConfig` - Custom API provider configuration (BYOK - Bring Your Own Key). See [Custom Providers](#custom-providers) section.
 - `onPermissionRequest: PermissionHandler` - **Required.** Handler called before each tool execution to approve or deny it. Use `approveAll` to allow everything, or provide a custom function for fine-grained control. See [Permission Handling](#permission-handling) section.
 - `onUserInputRequest?: UserInputHandler` - Handler for user input requests from the agent. Enables the `ask_user` tool. See [User Input Requests](#user-input-requests) section.
+- `onElicitationRequest?: ElicitationHandler` - Handler for elicitation requests dispatched by the server. Enables this client to present form-based UI dialogs on behalf of the agent or other session participants. See [Elicitation Requests](#elicitation-requests) section.
 - `hooks?: SessionHooks` - Hook handlers for session lifecycle events. See [Session Hooks](#session-hooks) section.
 
 ##### `resumeSession(sessionId: string, config?: ResumeSessionConfig): Promise<CopilotSession>`
@@ -293,6 +294,8 @@ if (session.capabilities.ui?.elicitation) {
 }
 ```
 
+Capabilities may update during the session. For example, when another client joins or disconnects with an elicitation handler. The SDK automatically applies `capabilities.changed` events, so this property always reflects the current state.
+
 ##### `ui: SessionUiApi`
 
 Interactive UI methods for showing dialogs to the user. Only available when the CLI host supports elicitation (`session.capabilities.ui?.elicitation === true`). See [UI Elicitation](#ui-elicitation) for full details.
@@ -505,9 +508,9 @@ Commands are sent to the CLI on both `createSession` and `resumeSession`, so you
 
 ### UI Elicitation
 
-When the CLI is running with a TUI (not in headless mode), the SDK can request interactive form dialogs from the user. The `session.ui` object provides convenience methods built on a single generic `elicitation` RPC.
+When the session has elicitation support — either from the CLI's TUI or from another client that registered an `onElicitationRequest` handler (see [Elicitation Requests](#elicitation-requests)) — the SDK can request interactive form dialogs from the user. The `session.ui` object provides convenience methods built on a single generic `elicitation` RPC.
 
-> **Capability check:** Elicitation is only available when the host advertises support. Always check `session.capabilities.ui?.elicitation` before calling UI methods.
+> **Capability check:** Elicitation is only available when at least one connected participant advertises support. Always check `session.capabilities.ui?.elicitation` before calling UI methods — this property updates automatically as participants join and leave.
 
 ```ts
 const session = await client.createSession({ onPermissionRequest: approveAll });
@@ -899,6 +902,42 @@ const session = await client.createSession({
 });
 ```
 
+## Elicitation Requests
+
+Register an `onElicitationRequest` handler to let your client act as an elicitation provider — presenting form-based UI dialogs on behalf of the agent. When provided, the server notifies your client whenever a tool or MCP server needs structured user input.
+
+```typescript
+const session = await client.createSession({
+    model: "gpt-5",
+    onPermissionRequest: approveAll,
+    onElicitationRequest: async (request, invocation) => {
+        // request.message - Description of what information is needed
+        // request.requestedSchema - JSON Schema describing the form fields
+        // request.mode - "form" (structured input) or "url" (browser redirect)
+        // request.elicitationSource - Origin of the request (e.g. MCP server name)
+
+        console.log(`Elicitation from ${request.elicitationSource}: ${request.message}`);
+
+        // Present UI to the user and collect their response...
+        return {
+            action: "accept", // "accept", "decline", or "cancel"
+            content: { region: "us-east", dryRun: true },
+        };
+    },
+});
+
+// The session now reports elicitation capability
+console.log(session.capabilities.ui?.elicitation); // true
+```
+
+When `onElicitationRequest` is provided, the SDK sends `requestElicitation: true` during session create/resume, which enables `session.capabilities.ui.elicitation` on the session.
+
+In multi-client scenarios:
+
+- If no connected client was previously providing an elicitation capability, but a new client joins that can, all clients will receive a `capabilities.changed` event to notify them that elicitation is now possible. The SDK automatically updates `session.capabilities` when these events arrive.
+- Similarly, if the last elicitation provider disconnects, all clients receive a `capabilities.changed` event indicating elicitation is no longer available.
+- The server fans out elicitation requests to **all** connected clients that registered a handler — the first response wins.
+
 ## Session Hooks
 
 Hook into session lifecycle events by providing handlers in the `hooks` configuration:

package/dist/cjs/client.js

@@ -116,6 +116,8 @@ class CopilotClient {
   processExitPromise = null;
   // Rejects when CLI process exits
   negotiatedProtocolVersion = null;
+  /** Connection-level session filesystem config, set via constructor option. */
+  sessionFsConfig = null;
   /**
    * Typed server-scoped RPC methods.
    * @throws Error if the client is not connected
@@ -175,6 +177,7 @@ class CopilotClient {
     }
     this.onListModels = options.onListModels;
     this.onGetTraceContext = options.onGetTraceContext;
+    this.sessionFsConfig = options.sessionFs ?? null;
     const effectiveEnv = options.env ?? process.env;
     this.options = {
       cliPath: options.cliUrl ? void 0 : options.cliPath || effectiveEnv.COPILOT_CLI_PATH || getBundledCliPath(),
@@ -246,6 +249,13 @@ class CopilotClient {
       }
       await this.connectToServer();
       await this.verifyProtocolVersion();
+      if (this.sessionFsConfig) {
+        await this.connection.sendRequest("sessionFs.setProvider", {
+          initialCwd: this.sessionFsConfig.initialCwd,
+          sessionStatePath: this.sessionFsConfig.sessionStatePath,
+          conventions: this.sessionFsConfig.conventions
+        });
+      }
       this.state = "connected";
     } catch (error) {
       this.state = "error";
@@ -457,6 +467,9 @@ class CopilotClient {
     if (config.onUserInputRequest) {
       session.registerUserInputHandler(config.onUserInputRequest);
     }
+    if (config.onElicitationRequest) {
+      session.registerElicitationHandler(config.onElicitationRequest);
+    }
     if (config.hooks) {
       session.registerHooks(config.hooks);
     }
@@ -470,6 +483,15 @@ class CopilotClient {
       session.on(config.onEvent);
     }
     this.sessions.set(sessionId, session);
+    if (this.sessionFsConfig) {
+      if (config.createSessionFsHandler) {
+        session.clientSessionApis.sessionFs = config.createSessionFsHandler(session);
+      } else {
+        throw new Error(
+          "createSessionFsHandler is required in session config when sessionFs is enabled in client options."
+        );
+      }
+    }
     try {
       const response = await this.connection.sendRequest("session.create", {
         ...await (0, import_telemetry.getTraceContext)(this.onGetTraceContext),
@@ -494,6 +516,7 @@ class CopilotClient {
         provider: config.provider,
         requestPermission: true,
         requestUserInput: !!config.onUserInputRequest,
+        requestElicitation: !!config.onElicitationRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
         workingDirectory: config.workingDirectory,
         streaming: config.streaming,
@@ -564,6 +587,9 @@ class CopilotClient {
     if (config.onUserInputRequest) {
       session.registerUserInputHandler(config.onUserInputRequest);
     }
+    if (config.onElicitationRequest) {
+      session.registerElicitationHandler(config.onElicitationRequest);
+    }
     if (config.hooks) {
       session.registerHooks(config.hooks);
     }
@@ -577,6 +603,15 @@ class CopilotClient {
       session.on(config.onEvent);
     }
     this.sessions.set(sessionId, session);
+    if (this.sessionFsConfig) {
+      if (config.createSessionFsHandler) {
+        session.clientSessionApis.sessionFs = config.createSessionFsHandler(session);
+      } else {
+        throw new Error(
+          "createSessionFsHandler is required in session config when sessionFs is enabled in client options."
+        );
+      }
+    }
     try {
       const response = await this.connection.sendRequest("session.resume", {
         ...await (0, import_telemetry.getTraceContext)(this.onGetTraceContext),
@@ -601,6 +636,7 @@ class CopilotClient {
         provider: config.provider,
         requestPermission: true,
         requestUserInput: !!config.onUserInputRequest,
+        requestElicitation: !!config.onElicitationRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
         workingDirectory: config.workingDirectory,
         configDir: config.configDir,
@@ -812,16 +848,50 @@ class CopilotClient {
     if (!this.connection) {
       throw new Error("Client not connected");
     }
-    const response = await this.connection.sendRequest("session.list", { filter });
+    const response = await this.connection.sendRequest("session.list", {
+      filter
+    });
     const { sessions } = response;
-    return sessions.map((s) => ({
-      sessionId: s.sessionId,
-      startTime: new Date(s.startTime),
-      modifiedTime: new Date(s.modifiedTime),
-      summary: s.summary,
-      isRemote: s.isRemote,
-      context: s.context
-    }));
+    return sessions.map(CopilotClient.toSessionMetadata);
+  }
+  /**
+   * Gets metadata for a specific session by ID.
+   *
+   * This provides an efficient O(1) lookup of a single session's metadata
+   * instead of listing all sessions. Returns undefined if the session is not found.
+   *
+   * @param sessionId - The ID of the session to look up
+   * @returns A promise that resolves with the session metadata, or undefined if not found
+   * @throws Error if the client is not connected
+   *
+   * @example
+   * ```typescript
+   * const metadata = await client.getSessionMetadata("session-123");
+   * if (metadata) {
+   *   console.log(`Session started at: ${metadata.startTime}`);
+   * }
+   * ```
+   */
+  async getSessionMetadata(sessionId) {
+    if (!this.connection) {
+      throw new Error("Client not connected");
+    }
+    const response = await this.connection.sendRequest("session.getMetadata", { sessionId });
+    const { session } = response;
+    if (!session) {
+      return void 0;
+    }
+    return CopilotClient.toSessionMetadata(session);
+  }
+  static toSessionMetadata(raw) {
+    return {
+      sessionId: raw.sessionId,
+      startTime: new Date(raw.startTime),
+      modifiedTime: new Date(raw.modifiedTime),
+      summary: raw.summary,
+      isRemote: raw.isRemote,
+      context: raw.context
+    };
   }
   /**
    * Gets the foreground session ID in TUI+server mode.
@@ -1151,6 +1221,12 @@ stderr: ${stderrOutput}`
       "systemMessage.transform",
       async (params) => await this.handleSystemMessageTransform(params)
     );
+    const sessions = this.sessions;
+    (0, import_rpc.registerClientSessionApiHandlers)(this.connection, (sessionId) => {
+      const session = sessions.get(sessionId);
+      if (!session) throw new Error(`No session found for sessionId: ${sessionId}`);
+      return session.clientSessionApis;
+    });
     this.connection.onClose(() => {
       this.state = "disconnected";
     });

package/dist/cjs/generated/rpc.js

@@ -19,7 +19,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var rpc_exports = {};
 __export(rpc_exports, {
   createServerRpc: () => createServerRpc,
-  createSessionRpc: () => createSessionRpc
+  createSessionRpc: () => createSessionRpc,
+  registerClientSessionApiHandlers: () => registerClientSessionApiHandlers
 });
 module.exports = __toCommonJS(rpc_exports);
 function createServerRpc(connection) {
@@ -33,6 +34,17 @@ function createServerRpc(connection) {
     },
     account: {
       getQuota: async () => connection.sendRequest("account.getQuota", {})
+    },
+    mcp: {
+      config: {
+        list: async () => connection.sendRequest("mcp.config.list", {}),
+        add: async (params) => connection.sendRequest("mcp.config.add", params),
+        update: async (params) => connection.sendRequest("mcp.config.update", params),
+        remove: async (params) => connection.sendRequest("mcp.config.remove", params)
+      }
+    },
+    sessionFs: {
+      setProvider: async (params) => connection.sendRequest("sessionFs.setProvider", params)
     }
   };
 }
@@ -104,7 +116,8 @@ function createSessionRpc(connection, sessionId) {
       handlePendingCommand: async (params) => connection.sendRequest("session.commands.handlePendingCommand", { sessionId, ...params })
     },
     ui: {
-      elicitation: async (params) => connection.sendRequest("session.ui.elicitation", { sessionId, ...params })
+      elicitation: async (params) => connection.sendRequest("session.ui.elicitation", { sessionId, ...params }),
+      handlePendingElicitation: async (params) => connection.sendRequest("session.ui.handlePendingElicitation", { sessionId, ...params })
     },
     permissions: {
       handlePendingPermissionRequest: async (params) => connection.sendRequest("session.permissions.handlePendingPermissionRequest", { sessionId, ...params })
@@ -116,8 +129,61 @@ function createSessionRpc(connection, sessionId) {
     }
   };
 }
+function registerClientSessionApiHandlers(connection, getHandlers) {
+  connection.onRequest("sessionFs.readFile", async (params) => {
+    const handler = getHandlers(params.sessionId).sessionFs;
+    if (!handler) throw new Error(`No sessionFs handler registered for session: ${params.sessionId}`);
+    return handler.readFile(params);
+  });
+  connection.onRequest("sessionFs.writeFile", async (params) => {
+    const handler = getHandlers(params.sessionId).sessionFs;
+    if (!handler) throw new Error(`No sessionFs handler registered for session: ${params.sessionId}`);
+    return handler.writeFile(params);
+  });
+  connection.onRequest("sessionFs.appendFile", async (params) => {
+    const handler = getHandlers(params.sessionId).sessionFs;
+    if (!handler) throw new Error(`No sessionFs handler registered for session: ${params.sessionId}`);
+    return handler.appendFile(params);
+  });
+  connection.onRequest("sessionFs.exists", async (params) => {
+    const handler = getHandlers(params.sessionId).sessionFs;
+    if (!handler) throw new Error(`No sessionFs handler registered for session: ${params.sessionId}`);
+    return handler.exists(params);
+  });
+  connection.onRequest("sessionFs.stat", async (params) => {
+    const handler = getHandlers(params.sessionId).sessionFs;
+    if (!handler) throw new Error(`No sessionFs handler registered for session: ${params.sessionId}`);
+    return handler.stat(params);
+  });
+  connection.onRequest("sessionFs.mkdir", async (params) => {
+    const handler = getHandlers(params.sessionId).sessionFs;
+    if (!handler) throw new Error(`No sessionFs handler registered for session: ${params.sessionId}`);
+    return handler.mkdir(params);
+  });
+  connection.onRequest("sessionFs.readdir", async (params) => {
+    const handler = getHandlers(params.sessionId).sessionFs;
+    if (!handler) throw new Error(`No sessionFs handler registered for session: ${params.sessionId}`);
+    return handler.readdir(params);
+  });
+  connection.onRequest("sessionFs.readdirWithTypes", async (params) => {
+    const handler = getHandlers(params.sessionId).sessionFs;
+    if (!handler) throw new Error(`No sessionFs handler registered for session: ${params.sessionId}`);
+    return handler.readdirWithTypes(params);
+  });
+  connection.onRequest("sessionFs.rm", async (params) => {
+    const handler = getHandlers(params.sessionId).sessionFs;
+    if (!handler) throw new Error(`No sessionFs handler registered for session: ${params.sessionId}`);
+    return handler.rm(params);
+  });
+  connection.onRequest("sessionFs.rename", async (params) => {
+    const handler = getHandlers(params.sessionId).sessionFs;
+    if (!handler) throw new Error(`No sessionFs handler registered for session: ${params.sessionId}`);
+    return handler.rename(params);
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createServerRpc,
-  createSessionRpc
+  createSessionRpc,
+  registerClientSessionApiHandlers
 });

package/dist/cjs/session.js

@@ -48,11 +48,14 @@ class CopilotSession {
   commandHandlers = /* @__PURE__ */ new Map();
   permissionHandler;
   userInputHandler;
+  elicitationHandler;
   hooks;
   transformCallbacks;
   _rpc = null;
   traceContextProvider;
   _capabilities = {};
+  /** @internal Client session API handlers, populated by CopilotClient during create/resume. */
+  clientSessionApis = {};
   /**
    * Typed session-scoped RPC methods.
    */
@@ -269,6 +272,22 @@ class CopilotSession {
     } else if (event.type === "command.execute") {
       const { requestId, commandName, command, args } = event.data;
       void this._executeCommandAndRespond(requestId, commandName, command, args);
+    } else if (event.type === "elicitation.requested") {
+      if (this.elicitationHandler) {
+        const { message, requestedSchema, mode, elicitationSource, url, requestId } = event.data;
+        void this._handleElicitationRequest(
+          {
+            message,
+            requestedSchema,
+            mode,
+            elicitationSource,
+            url
+          },
+          requestId
+        );
+      }
+    } else if (event.type === "capabilities.changed") {
+      this._capabilities = { ...this._capabilities, ...event.data };
     }
   }
   /**
@@ -409,6 +428,40 @@ class CopilotSession {
       this.commandHandlers.set(cmd.name, cmd.handler);
     }
   }
+  /**
+   * Registers the elicitation handler for this session.
+   *
+   * @param handler - The handler to invoke when the server dispatches an elicitation request
+   * @internal This method is typically called internally when creating/resuming a session.
+   */
+  registerElicitationHandler(handler) {
+    this.elicitationHandler = handler;
+  }
+  /**
+   * Handles an elicitation.requested broadcast event.
+   * Invokes the registered handler and responds via handlePendingElicitation RPC.
+   * @internal
+   */
+  async _handleElicitationRequest(request, requestId) {
+    if (!this.elicitationHandler) {
+      return;
+    }
+    try {
+      const result = await this.elicitationHandler(request, { sessionId: this.sessionId });
+      await this.rpc.ui.handlePendingElicitation({ requestId, result });
+    } catch {
+      try {
+        await this.rpc.ui.handlePendingElicitation({
+          requestId,
+          result: { action: "cancel" }
+        });
+      } catch (rpcError) {
+        if (!(rpcError instanceof import_node.ConnectionError || rpcError instanceof import_node.ResponseError)) {
+          throw rpcError;
+        }
+      }
+    }
+  }
   /**
    * Sets the host capabilities for this session.
    *

package/dist/client.d.ts

@@ -55,6 +55,8 @@ export declare class CopilotClient {
     private _rpc;
     private processExitPromise;
     private negotiatedProtocolVersion;
+    /** Connection-level session filesystem config, set via constructor option. */
+    private sessionFsConfig;
     /**
      * Typed server-scoped RPC methods.
      * @throws Error if the client is not connected
@@ -317,6 +319,26 @@ export declare class CopilotClient {
      * const sessions = await client.listSessions({ repository: "owner/repo" });
      */
     listSessions(filter?: SessionListFilter): Promise<SessionMetadata[]>;
+    /**
+     * Gets metadata for a specific session by ID.
+     *
+     * This provides an efficient O(1) lookup of a single session's metadata
+     * instead of listing all sessions. Returns undefined if the session is not found.
+     *
+     * @param sessionId - The ID of the session to look up
+     * @returns A promise that resolves with the session metadata, or undefined if not found
+     * @throws Error if the client is not connected
+     *
+     * @example
+     * ```typescript
+     * const metadata = await client.getSessionMetadata("session-123");
+     * if (metadata) {
+     *   console.log(`Session started at: ${metadata.startTime}`);
+     * }
+     * ```
+     */
+    getSessionMetadata(sessionId: string): Promise<SessionMetadata | undefined>;
+    private static toSessionMetadata;
     /**
      * Gets the foreground session ID in TUI+server mode.
      *

package/dist/client.js

@@ -10,7 +10,7 @@ import {
   StreamMessageReader,
   StreamMessageWriter
 } from "vscode-jsonrpc/node.js";
-import { createServerRpc } from "./generated/rpc.js";
+import { createServerRpc, registerClientSessionApiHandlers } from "./generated/rpc.js";
 import { getSdkProtocolVersion } from "./sdkProtocolVersion.js";
 import { CopilotSession, NO_RESULT_PERMISSION_V2_ERROR } from "./session.js";
 import { getTraceContext } from "./telemetry.js";
@@ -96,6 +96,8 @@ class CopilotClient {
   processExitPromise = null;
   // Rejects when CLI process exits
   negotiatedProtocolVersion = null;
+  /** Connection-level session filesystem config, set via constructor option. */
+  sessionFsConfig = null;
   /**
    * Typed server-scoped RPC methods.
    * @throws Error if the client is not connected
@@ -155,6 +157,7 @@ class CopilotClient {
     }
     this.onListModels = options.onListModels;
     this.onGetTraceContext = options.onGetTraceContext;
+    this.sessionFsConfig = options.sessionFs ?? null;
     const effectiveEnv = options.env ?? process.env;
     this.options = {
       cliPath: options.cliUrl ? void 0 : options.cliPath || effectiveEnv.COPILOT_CLI_PATH || getBundledCliPath(),
@@ -226,6 +229,13 @@ class CopilotClient {
       }
       await this.connectToServer();
       await this.verifyProtocolVersion();
+      if (this.sessionFsConfig) {
+        await this.connection.sendRequest("sessionFs.setProvider", {
+          initialCwd: this.sessionFsConfig.initialCwd,
+          sessionStatePath: this.sessionFsConfig.sessionStatePath,
+          conventions: this.sessionFsConfig.conventions
+        });
+      }
       this.state = "connected";
     } catch (error) {
       this.state = "error";
@@ -437,6 +447,9 @@ class CopilotClient {
     if (config.onUserInputRequest) {
       session.registerUserInputHandler(config.onUserInputRequest);
     }
+    if (config.onElicitationRequest) {
+      session.registerElicitationHandler(config.onElicitationRequest);
+    }
     if (config.hooks) {
       session.registerHooks(config.hooks);
     }
@@ -450,6 +463,15 @@ class CopilotClient {
       session.on(config.onEvent);
     }
     this.sessions.set(sessionId, session);
+    if (this.sessionFsConfig) {
+      if (config.createSessionFsHandler) {
+        session.clientSessionApis.sessionFs = config.createSessionFsHandler(session);
+      } else {
+        throw new Error(
+          "createSessionFsHandler is required in session config when sessionFs is enabled in client options."
+        );
+      }
+    }
     try {
       const response = await this.connection.sendRequest("session.create", {
         ...await getTraceContext(this.onGetTraceContext),
@@ -474,6 +496,7 @@ class CopilotClient {
         provider: config.provider,
         requestPermission: true,
         requestUserInput: !!config.onUserInputRequest,
+        requestElicitation: !!config.onElicitationRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
         workingDirectory: config.workingDirectory,
         streaming: config.streaming,
@@ -544,6 +567,9 @@ class CopilotClient {
     if (config.onUserInputRequest) {
       session.registerUserInputHandler(config.onUserInputRequest);
     }
+    if (config.onElicitationRequest) {
+      session.registerElicitationHandler(config.onElicitationRequest);
+    }
     if (config.hooks) {
       session.registerHooks(config.hooks);
     }
@@ -557,6 +583,15 @@ class CopilotClient {
       session.on(config.onEvent);
     }
     this.sessions.set(sessionId, session);
+    if (this.sessionFsConfig) {
+      if (config.createSessionFsHandler) {
+        session.clientSessionApis.sessionFs = config.createSessionFsHandler(session);
+      } else {
+        throw new Error(
+          "createSessionFsHandler is required in session config when sessionFs is enabled in client options."
+        );
+      }
+    }
     try {
       const response = await this.connection.sendRequest("session.resume", {
         ...await getTraceContext(this.onGetTraceContext),
@@ -581,6 +616,7 @@ class CopilotClient {
         provider: config.provider,
         requestPermission: true,
         requestUserInput: !!config.onUserInputRequest,
+        requestElicitation: !!config.onElicitationRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
         workingDirectory: config.workingDirectory,
         configDir: config.configDir,
@@ -792,16 +828,50 @@ class CopilotClient {
     if (!this.connection) {
       throw new Error("Client not connected");
     }
-    const response = await this.connection.sendRequest("session.list", { filter });
+    const response = await this.connection.sendRequest("session.list", {
+      filter
+    });
     const { sessions } = response;
-    return sessions.map((s) => ({
-      sessionId: s.sessionId,
-      startTime: new Date(s.startTime),
-      modifiedTime: new Date(s.modifiedTime),
-      summary: s.summary,
-      isRemote: s.isRemote,
-      context: s.context
-    }));
+    return sessions.map(CopilotClient.toSessionMetadata);
+  }
+  /**
+   * Gets metadata for a specific session by ID.
+   *
+   * This provides an efficient O(1) lookup of a single session's metadata
+   * instead of listing all sessions. Returns undefined if the session is not found.
+   *
+   * @param sessionId - The ID of the session to look up
+   * @returns A promise that resolves with the session metadata, or undefined if not found
+   * @throws Error if the client is not connected
+   *
+   * @example
+   * ```typescript
+   * const metadata = await client.getSessionMetadata("session-123");
+   * if (metadata) {
+   *   console.log(`Session started at: ${metadata.startTime}`);
+   * }
+   * ```
+   */
+  async getSessionMetadata(sessionId) {
+    if (!this.connection) {
+      throw new Error("Client not connected");
+    }
+    const response = await this.connection.sendRequest("session.getMetadata", { sessionId });
+    const { session } = response;
+    if (!session) {
+      return void 0;
+    }
+    return CopilotClient.toSessionMetadata(session);
+  }
+  static toSessionMetadata(raw) {
+    return {
+      sessionId: raw.sessionId,
+      startTime: new Date(raw.startTime),
+      modifiedTime: new Date(raw.modifiedTime),
+      summary: raw.summary,
+      isRemote: raw.isRemote,
+      context: raw.context
+    };
   }
   /**
    * Gets the foreground session ID in TUI+server mode.
@@ -1131,6 +1201,12 @@ stderr: ${stderrOutput}`
       "systemMessage.transform",
       async (params) => await this.handleSystemMessageTransform(params)
     );
+    const sessions = this.sessions;
+    registerClientSessionApiHandlers(this.connection, (sessionId) => {
+      const session = sessions.get(sessionId);
+      if (!session) throw new Error(`No session found for sessionId: ${sessionId}`);
+      return session.clientSessionApis;
+    });
     this.connection.onClose(() => {
       this.state = "disconnected";
     });