@github/copilot-sdk 0.2.1-preview.0 → 0.2.1-preview.2

package/README.md

@@ -60,7 +60,10 @@ await client.stop();
 Sessions also support `Symbol.asyncDispose` for use with [`await using`](https://github.com/tc39/proposal-explicit-resource-management) (TypeScript 5.2+/Node.js 18.0+):
 
 ```typescript
-await using session = await client.createSession({ model: "gpt-5", onPermissionRequest: approveAll });
+await using session = await client.createSession({
+    model: "gpt-5",
+    onPermissionRequest: approveAll,
+});
 // session is automatically disconnected when leaving scope
 ```
 
@@ -76,7 +79,7 @@ new CopilotClient(options?: CopilotClientOptions)
 
 **Options:**
 
-- `cliPath?: string` - Path to CLI executable (default: "copilot" from PATH)
+- `cliPath?: string` - Path to CLI executable (default: uses COPILOT_CLI_PATH env var or bundled instance)
 - `cliArgs?: string[]` - Extra arguments prepended before SDK-managed flags (e.g. `["./dist-cli/index.js"]` when using `node`)
 - `cliUrl?: string` - URL of existing CLI server to connect to (e.g., `"localhost:8080"`, `"http://127.0.0.1:9000"`, or just `"8080"`). When provided, the client will not spawn a CLI process.
 - `port?: number` - Server port (default: 0 for random)
@@ -117,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>`
@@ -184,6 +188,7 @@ const unsubscribe = client.on((event) => {
 ```
 
 **Lifecycle Event Types:**
+
 - `session.created` - A new session was created
 - `session.deleted` - A session was deleted
 - `session.updated` - A session was updated (e.g., new messages)
@@ -289,11 +294,13 @@ 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.
 
-##### `destroy(): Promise<void>` *(deprecated)*
+##### `destroy(): Promise<void>` _(deprecated)_
 
 Deprecated — use `disconnect()` instead.
 
@@ -454,8 +461,10 @@ defineTool("edit_file", {
     description: "Custom file editor with project-specific validation",
     parameters: z.object({ path: z.string(), content: z.string() }),
     overridesBuiltInTool: true,
-    handler: async ({ path, content }) => { /* your logic */ },
-})
+    handler: async ({ path, content }) => {
+        /* your logic */
+    },
+});
 ```
 
 #### Skipping Permission Prompts
@@ -467,8 +476,10 @@ defineTool("safe_lookup", {
     description: "A read-only lookup that needs no confirmation",
     parameters: z.object({ id: z.string() }),
     skipPermission: true,
-    handler: async ({ id }) => { /* your logic */ },
-})
+    handler: async ({ id }) => {
+        /* your logic */
+    },
+});
 ```
 
 ### Commands
@@ -497,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 });
@@ -571,7 +582,10 @@ const session = await client.createSession({
         mode: "customize",
         sections: {
             // Replace the tone/style section
-            tone: { action: "replace", content: "Respond in a warm, professional tone. Be thorough in explanations." },
+            tone: {
+                action: "replace",
+                content: "Respond in a warm, professional tone. Be thorough in explanations.",
+            },
             // Remove coding-specific rules
             code_change_rules: { action: "remove" },
             // Append to existing guidelines
@@ -586,6 +600,7 @@ const session = await client.createSession({
 Available section IDs: `identity`, `tone`, `tool_efficiency`, `environment_context`, `code_change_rules`, `guidelines`, `safety`, `tool_instructions`, `custom_instructions`, `last_instructions`. Use the `SYSTEM_PROMPT_SECTIONS` constant for descriptions of each section.
 
 Each section override supports four actions:
+
 - **`replace`** — Replace the section content entirely
 - **`remove`** — Remove the section from the prompt
 - **`append`** — Add content after the existing section
@@ -624,7 +639,7 @@ const session = await client.createSession({
     model: "gpt-5",
     infiniteSessions: {
         enabled: true,
-        backgroundCompactionThreshold: 0.80, // Start compacting at 80% context usage
+        backgroundCompactionThreshold: 0.8, // Start compacting at 80% context usage
         bufferExhaustionThreshold: 0.95, // Block at 95% until compaction completes
     },
 });
@@ -723,8 +738,8 @@ const session = await client.createSession({
 const session = await client.createSession({
     model: "gpt-4",
     provider: {
-        type: "azure",  // Must be "azure" for Azure endpoints, NOT "openai"
-        baseUrl: "https://my-resource.openai.azure.com",  // Just the host, no path
+        type: "azure", // Must be "azure" for Azure endpoints, NOT "openai"
+        baseUrl: "https://my-resource.openai.azure.com", // Just the host, no path
         apiKey: process.env.AZURE_OPENAI_KEY,
         azure: {
             apiVersion: "2024-10-21",
@@ -734,6 +749,7 @@ const session = await client.createSession({
 ```
 
 > **Important notes:**
+>
 > - When using a custom provider, the `model` parameter is **required**. The SDK will throw an error if no model is specified.
 > - For Azure OpenAI endpoints (`*.openai.azure.com`), you **must** use `type: "azure"`, not `type: "openai"`.
 > - The `baseUrl` should be just the host (e.g., `https://my-resource.openai.azure.com`). Do **not** include `/openai/v1` in the URL - the SDK handles path construction automatically.
@@ -744,9 +760,9 @@ The SDK supports OpenTelemetry for distributed tracing. Provide a `telemetry` co
 
 ```typescript
 const client = new CopilotClient({
-  telemetry: {
-    otlpEndpoint: "http://localhost:4318",
-  },
+    telemetry: {
+        otlpEndpoint: "http://localhost:4318",
+    },
 });
 ```
 
@@ -772,12 +788,12 @@ If you're already using `@opentelemetry/api` in your app and want this linkage,
 import { propagation, context } from "@opentelemetry/api";
 
 const client = new CopilotClient({
-  telemetry: { otlpEndpoint: "http://localhost:4318" },
-  onGetTraceContext: () => {
-    const carrier: Record<string, string> = {};
-    propagation.inject(context.active(), carrier);
-    return carrier;
-  },
+    telemetry: { otlpEndpoint: "http://localhost:4318" },
+    onGetTraceContext: () => {
+        const carrier: Record<string, string> = {};
+        propagation.inject(context.active(), carrier);
+        return carrier;
+    },
 });
 ```
 
@@ -837,14 +853,15 @@ const session = await client.createSession({
 
 ### Permission Result Kinds
 
-| Kind | Meaning |
-|------|---------|
-| `"approved"` | Allow the tool to run |
-| `"denied-interactively-by-user"` | User explicitly denied the request |
-| `"denied-no-approval-rule-and-could-not-request-from-user"` | No approval rule matched and user could not be asked |
-| `"denied-by-rules"` | Denied by a policy rule |
-| `"denied-by-content-exclusion-policy"` | Denied due to a content exclusion policy |
-| `"no-result"` | Leave the request unanswered (only valid with protocol v1; rejected by protocol v2 servers) |
+| Kind                                                        | Meaning                                                                                     |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `"approved"`                                                | Allow the tool to run                                                                       |
+| `"denied-interactively-by-user"`                            | User explicitly denied the request                                                          |
+| `"denied-no-approval-rule-and-could-not-request-from-user"` | No approval rule matched and user could not be asked                                        |
+| `"denied-by-rules"`                                         | Denied by a policy rule                                                                     |
+| `"denied-by-content-exclusion-policy"`                      | Denied due to a content exclusion policy                                                    |
+| `"no-result"`                                               | Leave the request unanswered (only valid with protocol v1; rejected by protocol v2 servers) |
+
 ### Resuming Sessions
 
 Pass `onPermissionRequest` when resuming a session too — it is required:
@@ -885,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,8 +177,10 @@ 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 || getBundledCliPath(),
+      cliPath: options.cliUrl ? void 0 : options.cliPath || effectiveEnv.COPILOT_CLI_PATH || getBundledCliPath(),
       cliArgs: options.cliArgs ?? [],
       cwd: options.cwd ?? process.cwd(),
       port: options.port || 0,
@@ -187,7 +191,7 @@ class CopilotClient {
       logLevel: options.logLevel || "debug",
       autoStart: options.autoStart ?? true,
       autoRestart: false,
-      env: options.env ?? process.env,
+      env: effectiveEnv,
       githubToken: options.githubToken,
       // Default useLoggedInUser to false when githubToken is provided, otherwise true
       useLoggedInUser: options.useLoggedInUser ?? (options.githubToken ? false : true),
@@ -245,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";
@@ -456,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);
     }
@@ -469,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),
@@ -493,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,
@@ -563,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);
     }
@@ -576,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),
@@ -600,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,
@@ -811,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.
@@ -1150,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 };
     }
   }
   /**
@@ -290,6 +309,8 @@ class CopilotSession {
         result = "";
       } else if (typeof rawResult === "string") {
         result = rawResult;
+      } else if (isToolResultObject(rawResult)) {
+        result = rawResult;
       } else {
         result = JSON.stringify(rawResult);
       }
@@ -409,6 +430,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.
    *
@@ -767,6 +822,25 @@ class CopilotSession {
     await this.rpc.log({ message, ...options });
   }
 }
+function isToolResultObject(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  if (!("textResultForLlm" in value) || typeof value.textResultForLlm !== "string") {
+    return false;
+  }
+  if (!("resultType" in value) || typeof value.resultType !== "string") {
+    return false;
+  }
+  const allowedResultTypes = [
+    "success",
+    "failure",
+    "rejected",
+    "denied",
+    "timeout"
+  ];
+  return allowedResultTypes.includes(value.resultType);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CopilotSession,

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.
      *