@github/copilot-sdk 0.2.0 → 0.2.1-preview.1

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)
@@ -184,6 +187,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)
@@ -279,7 +283,21 @@ Get all events/messages from this session.
 
 Disconnect the session and free resources. Session data on disk is preserved for later resumption.
 
-##### `destroy(): Promise<void>` *(deprecated)*
+##### `capabilities: SessionCapabilities`
+
+Host capabilities reported when the session was created or resumed. Use this to check feature support before calling capability-gated APIs.
+
+```typescript
+if (session.capabilities.ui?.elicitation) {
+    const ok = await session.ui.confirm("Deploy?");
+}
+```
+
+##### `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)_
 
 Deprecated — use `disconnect()` instead.
 
@@ -294,6 +312,8 @@ Sessions emit various events during processing:
 - `assistant.message_delta` - Streaming response chunk
 - `tool.execution_start` - Tool execution started
 - `tool.execution_complete` - Tool execution completed
+- `command.execute` - Command dispatch request (handled internally by the SDK)
+- `commands.changed` - Command registration changed
 - And more...
 
 See `SessionEvent` type in the source for full details.
@@ -438,8 +458,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
@@ -451,10 +473,78 @@ 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
+
+Register slash commands so that users of the CLI's TUI can invoke custom actions via `/commandName`. Each command has a `name`, optional `description`, and a `handler` called when the user executes it.
+
+```ts
+const session = await client.createSession({
+    onPermissionRequest: approveAll,
+    commands: [
+        {
+            name: "deploy",
+            description: "Deploy the app to production",
+            handler: async ({ commandName, args }) => {
+                console.log(`Deploying with args: ${args}`);
+                // Do work here — any thrown error is reported back to the CLI
+            },
+        },
+    ],
+});
+```
+
+When the user types `/deploy staging` in the CLI, the SDK receives a `command.execute` event, routes it to your handler, and automatically responds to the CLI. If the handler throws, the error message is forwarded.
+
+Commands are sent to the CLI on both `createSession` and `resumeSession`, so you can update the command set when resuming.
+
+### 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.
+
+> **Capability check:** Elicitation is only available when the host advertises support. Always check `session.capabilities.ui?.elicitation` before calling UI methods.
+
+```ts
+const session = await client.createSession({ onPermissionRequest: approveAll });
+
+if (session.capabilities.ui?.elicitation) {
+    // Confirm dialog — returns boolean
+    const ok = await session.ui.confirm("Deploy to production?");
+
+    // Selection dialog — returns selected value or null
+    const env = await session.ui.select("Pick environment", ["production", "staging", "dev"]);
+
+    // Text input — returns string or null
+    const name = await session.ui.input("Project name:", {
+        title: "Name",
+        minLength: 1,
+        maxLength: 50,
+    });
+
+    // Generic elicitation with full schema control
+    const result = await session.ui.elicitation({
+        message: "Configure deployment",
+        requestedSchema: {
+            type: "object",
+            properties: {
+                region: { type: "string", enum: ["us-east", "eu-west"] },
+                dryRun: { type: "boolean", default: true },
+            },
+            required: ["region"],
+        },
+    });
+    // result.action: "accept" | "decline" | "cancel"
+    // result.content: { region: "us-east", dryRun: true } (when accepted)
+}
+```
+
+All UI methods throw if elicitation is not supported by the host.
+
 ### System Message Customization
 
 Control the system prompt using `systemMessage` in session config:
@@ -489,7 +579,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
@@ -504,6 +597,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
@@ -542,7 +636,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
     },
 });
@@ -641,8 +735,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",
@@ -652,6 +746,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.
@@ -662,9 +757,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",
+    },
 });
 ```
 
@@ -690,12 +785,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;
+    },
 });
 ```
 
@@ -755,14 +850,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:

package/dist/cjs/client.js

@@ -175,8 +175,9 @@ class CopilotClient {
     }
     this.onListModels = options.onListModels;
     this.onGetTraceContext = options.onGetTraceContext;
+    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 +188,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),
@@ -451,6 +452,7 @@ class CopilotClient {
       this.onGetTraceContext
     );
     session.registerTools(config.tools);
+    session.registerCommands(config.commands);
     session.registerPermissionHandler(config.onPermissionRequest);
     if (config.onUserInputRequest) {
       session.registerUserInputHandler(config.onUserInputRequest);
@@ -482,6 +484,10 @@ class CopilotClient {
           overridesBuiltInTool: tool.overridesBuiltInTool,
           skipPermission: tool.skipPermission
         })),
+        commands: config.commands?.map((cmd) => ({
+          name: cmd.name,
+          description: cmd.description
+        })),
         systemMessage: wireSystemMessage,
         availableTools: config.availableTools,
         excludedTools: config.excludedTools,
@@ -500,8 +506,9 @@ class CopilotClient {
         disabledSkills: config.disabledSkills,
         infiniteSessions: config.infiniteSessions
       });
-      const { workspacePath } = response;
+      const { workspacePath, capabilities } = response;
       session["_workspacePath"] = workspacePath;
+      session.setCapabilities(capabilities);
     } catch (e) {
       this.sessions.delete(sessionId);
       throw e;
@@ -552,6 +559,7 @@ class CopilotClient {
       this.onGetTraceContext
     );
     session.registerTools(config.tools);
+    session.registerCommands(config.commands);
     session.registerPermissionHandler(config.onPermissionRequest);
     if (config.onUserInputRequest) {
       session.registerUserInputHandler(config.onUserInputRequest);
@@ -586,6 +594,10 @@ class CopilotClient {
           overridesBuiltInTool: tool.overridesBuiltInTool,
           skipPermission: tool.skipPermission
         })),
+        commands: config.commands?.map((cmd) => ({
+          name: cmd.name,
+          description: cmd.description
+        })),
         provider: config.provider,
         requestPermission: true,
         requestUserInput: !!config.onUserInputRequest,
@@ -602,8 +614,9 @@ class CopilotClient {
         infiniteSessions: config.infiniteSessions,
         disableResume: config.disableResume
       });
-      const { workspacePath } = response;
+      const { workspacePath, capabilities } = response;
       session["_workspacePath"] = workspacePath;
+      session.setCapabilities(capabilities);
     } catch (e) {
       this.sessions.delete(sessionId);
       throw e;

package/dist/cjs/session.js

@@ -45,12 +45,14 @@ class CopilotSession {
   eventHandlers = /* @__PURE__ */ new Set();
   typedEventHandlers = /* @__PURE__ */ new Map();
   toolHandlers = /* @__PURE__ */ new Map();
+  commandHandlers = /* @__PURE__ */ new Map();
   permissionHandler;
   userInputHandler;
   hooks;
   transformCallbacks;
   _rpc = null;
   traceContextProvider;
+  _capabilities = {};
   /**
    * Typed session-scoped RPC methods.
    */
@@ -68,6 +70,33 @@ class CopilotSession {
   get workspacePath() {
     return this._workspacePath;
   }
+  /**
+   * Host capabilities reported when the session was created or resumed.
+   * Use this to check feature support before calling capability-gated APIs.
+   */
+  get capabilities() {
+    return this._capabilities;
+  }
+  /**
+   * Interactive UI methods for showing dialogs to the user.
+   * Only available when the CLI host supports elicitation
+   * (`session.capabilities.ui?.elicitation === true`).
+   *
+   * @example
+   * ```typescript
+   * if (session.capabilities.ui?.elicitation) {
+   *   const ok = await session.ui.confirm("Deploy to production?");
+   * }
+   * ```
+   */
+  get ui() {
+    return {
+      elicitation: (params) => this._elicitation(params),
+      confirm: (message) => this._confirm(message),
+      select: (message, options) => this._select(message, options),
+      input: (message, options) => this._input(message, options)
+    };
+  }
   /**
    * Sends a message to this session and waits for the response.
    *
@@ -237,6 +266,9 @@ class CopilotSession {
       if (this.permissionHandler) {
         void this._executePermissionAndRespond(requestId, permissionRequest);
       }
+    } else if (event.type === "command.execute") {
+      const { requestId, commandName, command, args } = event.data;
+      void this._executeCommandAndRespond(requestId, commandName, command, args);
     }
   }
   /**
@@ -301,6 +333,39 @@ class CopilotSession {
       }
     }
   }
+  /**
+   * Executes a command handler and sends the result back via RPC.
+   * @internal
+   */
+  async _executeCommandAndRespond(requestId, commandName, command, args) {
+    const handler = this.commandHandlers.get(commandName);
+    if (!handler) {
+      try {
+        await this.rpc.commands.handlePendingCommand({
+          requestId,
+          error: `Unknown command: ${commandName}`
+        });
+      } catch (rpcError) {
+        if (!(rpcError instanceof import_node.ConnectionError || rpcError instanceof import_node.ResponseError)) {
+          throw rpcError;
+        }
+      }
+      return;
+    }
+    try {
+      await handler({ sessionId: this.sessionId, command, commandName, args });
+      await this.rpc.commands.handlePendingCommand({ requestId });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      try {
+        await this.rpc.commands.handlePendingCommand({ requestId, error: message });
+      } catch (rpcError) {
+        if (!(rpcError instanceof import_node.ConnectionError || rpcError instanceof import_node.ResponseError)) {
+          throw rpcError;
+        }
+      }
+    }
+  }
   /**
    * Registers custom tool handlers for this session.
    *
@@ -329,6 +394,99 @@ class CopilotSession {
   getToolHandler(name) {
     return this.toolHandlers.get(name);
   }
+  /**
+   * Registers command handlers for this session.
+   *
+   * @param commands - An array of command definitions with handlers, or undefined to clear
+   * @internal This method is typically called internally when creating/resuming a session.
+   */
+  registerCommands(commands) {
+    this.commandHandlers.clear();
+    if (!commands) {
+      return;
+    }
+    for (const cmd of commands) {
+      this.commandHandlers.set(cmd.name, cmd.handler);
+    }
+  }
+  /**
+   * Sets the host capabilities for this session.
+   *
+   * @param capabilities - The capabilities object from the create/resume response
+   * @internal This method is typically called internally when creating/resuming a session.
+   */
+  setCapabilities(capabilities) {
+    this._capabilities = capabilities ?? {};
+  }
+  assertElicitation() {
+    if (!this._capabilities.ui?.elicitation) {
+      throw new Error(
+        "Elicitation is not supported by the host. Check session.capabilities.ui?.elicitation before calling UI methods."
+      );
+    }
+  }
+  async _elicitation(params) {
+    this.assertElicitation();
+    return this.rpc.ui.elicitation({
+      message: params.message,
+      requestedSchema: params.requestedSchema
+    });
+  }
+  async _confirm(message) {
+    this.assertElicitation();
+    const result = await this.rpc.ui.elicitation({
+      message,
+      requestedSchema: {
+        type: "object",
+        properties: {
+          confirmed: { type: "boolean", default: true }
+        },
+        required: ["confirmed"]
+      }
+    });
+    return result.action === "accept" && result.content?.confirmed === true;
+  }
+  async _select(message, options) {
+    this.assertElicitation();
+    const result = await this.rpc.ui.elicitation({
+      message,
+      requestedSchema: {
+        type: "object",
+        properties: {
+          selection: { type: "string", enum: options }
+        },
+        required: ["selection"]
+      }
+    });
+    if (result.action === "accept" && result.content?.selection != null) {
+      return result.content.selection;
+    }
+    return null;
+  }
+  async _input(message, options) {
+    this.assertElicitation();
+    const field = { type: "string" };
+    if (options?.title) field.title = options.title;
+    if (options?.description) field.description = options.description;
+    if (options?.minLength != null) field.minLength = options.minLength;
+    if (options?.maxLength != null) field.maxLength = options.maxLength;
+    if (options?.format) field.format = options.format;
+    if (options?.default != null) field.default = options.default;
+    const result = await this.rpc.ui.elicitation({
+      message,
+      requestedSchema: {
+        type: "object",
+        properties: {
+          value: field
+        },
+        required: ["value"]
+      }
+    });
+    if (result.action === "accept" && result.content?.value != null) {
+      return result.content.value;
+    }
+    return null;
+  }
   /**
    * Registers a handler for permission requests.
    *

package/dist/client.js

@@ -155,8 +155,9 @@ class CopilotClient {
     }
     this.onListModels = options.onListModels;
     this.onGetTraceContext = options.onGetTraceContext;
+    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,
@@ -167,7 +168,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),
@@ -431,6 +432,7 @@ class CopilotClient {
       this.onGetTraceContext
     );
     session.registerTools(config.tools);
+    session.registerCommands(config.commands);
     session.registerPermissionHandler(config.onPermissionRequest);
     if (config.onUserInputRequest) {
       session.registerUserInputHandler(config.onUserInputRequest);
@@ -462,6 +464,10 @@ class CopilotClient {
           overridesBuiltInTool: tool.overridesBuiltInTool,
           skipPermission: tool.skipPermission
         })),
+        commands: config.commands?.map((cmd) => ({
+          name: cmd.name,
+          description: cmd.description
+        })),
         systemMessage: wireSystemMessage,
         availableTools: config.availableTools,
         excludedTools: config.excludedTools,
@@ -480,8 +486,9 @@ class CopilotClient {
         disabledSkills: config.disabledSkills,
         infiniteSessions: config.infiniteSessions
       });
-      const { workspacePath } = response;
+      const { workspacePath, capabilities } = response;
       session["_workspacePath"] = workspacePath;
+      session.setCapabilities(capabilities);
     } catch (e) {
       this.sessions.delete(sessionId);
       throw e;
@@ -532,6 +539,7 @@ class CopilotClient {
       this.onGetTraceContext
     );
     session.registerTools(config.tools);
+    session.registerCommands(config.commands);
     session.registerPermissionHandler(config.onPermissionRequest);
     if (config.onUserInputRequest) {
       session.registerUserInputHandler(config.onUserInputRequest);
@@ -566,6 +574,10 @@ class CopilotClient {
           overridesBuiltInTool: tool.overridesBuiltInTool,
           skipPermission: tool.skipPermission
         })),
+        commands: config.commands?.map((cmd) => ({
+          name: cmd.name,
+          description: cmd.description
+        })),
         provider: config.provider,
         requestPermission: true,
         requestUserInput: !!config.onUserInputRequest,
@@ -582,8 +594,9 @@ class CopilotClient {
         infiniteSessions: config.infiniteSessions,
         disableResume: config.disableResume
       });
-      const { workspacePath } = response;
+      const { workspacePath, capabilities } = response;
       session["_workspacePath"] = workspacePath;
+      session.setCapabilities(capabilities);
     } catch (e) {
       this.sessions.delete(sessionId);
       throw e;

package/dist/generated/session-events.d.ts

@@ -89,6 +89,10 @@ export type SessionEvent = {
          * Whether the session was already in use by another client at start time
          */
         alreadyInUse?: boolean;
+        /**
+         * Whether this session supports remote steering via Mission Control
+         */
+        steerable?: boolean;
     };
 } | {
     /**
@@ -2070,6 +2074,10 @@ export type SessionEvent = {
          * Version of the plugin this skill originated from, when applicable
          */
         pluginVersion?: string;
+        /**
+         * Description of the skill from its SKILL.md frontmatter
+         */
+        description?: string;
     };
 } | {
     /**
@@ -2144,6 +2152,22 @@ export type SessionEvent = {
          * Human-readable display name of the sub-agent
          */
         agentDisplayName: string;
+        /**
+         * Model used by the sub-agent
+         */
+        model?: string;
+        /**
+         * Total number of tool calls made by the sub-agent
+         */
+        totalToolCalls?: number;
+        /**
+         * Total tokens (input + output) consumed by the sub-agent
+         */
+        totalTokens?: number;
+        /**
+         * Wall-clock duration of the sub-agent execution in milliseconds
+         */
+        durationMs?: number;
     };
 } | {
     /**
@@ -2183,6 +2207,22 @@ export type SessionEvent = {
          * Error message describing why the sub-agent failed
          */
         error: string;
+        /**
+         * Model used by the sub-agent (if any model calls succeeded before failure)
+         */
+        model?: string;
+        /**
+         * Total number of tool calls made before the sub-agent failed
+         */
+        totalToolCalls?: number;
+        /**
+         * Total tokens (input + output) consumed before the sub-agent failed
+         */
+        totalTokens?: number;
+        /**
+         * Wall-clock duration of the sub-agent execution in milliseconds
+         */
+        durationMs?: number;
     };
 } | {
     /**
@@ -3300,6 +3340,68 @@ export type SessionEvent = {
             path?: string;
         }[];
     };
+} | {
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    ephemeral: true;
+    type: "session.custom_agents_updated";
+    data: {
+        /**
+         * Array of loaded custom agent metadata
+         */
+        agents: {
+            /**
+             * Unique identifier for the agent
+             */
+            id: string;
+            /**
+             * Internal name of the agent
+             */
+            name: string;
+            /**
+             * Human-readable display name
+             */
+            displayName: string;
+            /**
+             * Description of what the agent does
+             */
+            description: string;
+            /**
+             * Source location: user, project, inherited, remote, or plugin
+             */
+            source: string;
+            /**
+             * List of tool names available to this agent
+             */
+            tools: string[];
+            /**
+             * Whether the agent can be selected by the user
+             */
+            userInvocable: boolean;
+            /**
+             * Model override for this agent, if set
+             */
+            model?: string;
+        }[];
+        /**
+         * Non-fatal warnings from agent loading
+         */
+        warnings: string[];
+        /**
+         * Fatal errors from agent loading
+         */
+        errors: string[];
+    };
 } | {
     /**
      * Unique event identifier (UUID v4), generated when the event is emitted

package/dist/index.d.ts

@@ -6,4 +6,4 @@
 export { CopilotClient } from "./client.js";
 export { CopilotSession, type AssistantMessageEvent } from "./session.js";
 export { defineTool, approveAll, SYSTEM_PROMPT_SECTIONS } from "./types.js";
-export type { ConnectionState, CopilotClientOptions, CustomAgentConfig, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, MCPLocalServerConfig, MCPRemoteServerConfig, MCPServerConfig, MessageOptions, ModelBilling, ModelCapabilities, ModelInfo, ModelPolicy, PermissionHandler, PermissionRequest, PermissionRequestResult, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionConfig, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventType, SessionLifecycleHandler, SessionContext, SessionListFilter, SessionMetadata, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemPromptSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export type { CommandContext, CommandDefinition, CommandHandler, ConnectionState, CopilotClientOptions, CustomAgentConfig, ElicitationFieldValue, ElicitationParams, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, InputOptions, MCPLocalServerConfig, MCPRemoteServerConfig, MCPServerConfig, MessageOptions, ModelBilling, ModelCapabilities, ModelInfo, ModelPolicy, PermissionHandler, PermissionRequest, PermissionRequestResult, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventType, SessionLifecycleHandler, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemPromptSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";

package/dist/session.d.ts

@@ -4,7 +4,7 @@
  */
 import type { MessageConnection } from "vscode-jsonrpc/node.js";
 import { createSessionRpc } from "./generated/rpc.js";
-import type { MessageOptions, PermissionHandler, PermissionRequestResult, ReasoningEffort, SectionTransformFn, SessionEvent, SessionEventHandler, SessionEventType, SessionHooks, Tool, ToolHandler, TraceContextProvider, TypedSessionEventHandler, UserInputHandler, UserInputResponse } from "./types.js";
+import type { CommandHandler, MessageOptions, PermissionHandler, PermissionRequestResult, ReasoningEffort, SectionTransformFn, SessionCapabilities, SessionEvent, SessionEventHandler, SessionEventType, SessionHooks, SessionUiApi, Tool, ToolHandler, TraceContextProvider, TypedSessionEventHandler, UserInputHandler, UserInputResponse } from "./types.js";
 export declare const NO_RESULT_PERMISSION_V2_ERROR = "Permission handlers cannot return 'no-result' when connected to a protocol v2 server.";
 /** Assistant message event - the final response from the assistant. */
 export type AssistantMessageEvent = Extract<SessionEvent, {
@@ -42,12 +42,14 @@ export declare class CopilotSession {
     private eventHandlers;
     private typedEventHandlers;
     private toolHandlers;
+    private commandHandlers;
     private permissionHandler?;
     private userInputHandler?;
     private hooks?;
     private transformCallbacks?;
     private _rpc;
     private traceContextProvider?;
+    private _capabilities;
     /**
      * Creates a new CopilotSession instance.
      *
@@ -68,6 +70,24 @@ export declare class CopilotSession {
      * Undefined if infinite sessions are disabled.
      */
     get workspacePath(): string | undefined;
+    /**
+     * Host capabilities reported when the session was created or resumed.
+     * Use this to check feature support before calling capability-gated APIs.
+     */
+    get capabilities(): SessionCapabilities;
+    /**
+     * Interactive UI methods for showing dialogs to the user.
+     * Only available when the CLI host supports elicitation
+     * (`session.capabilities.ui?.elicitation === true`).
+     *
+     * @example
+     * ```typescript
+     * if (session.capabilities.ui?.elicitation) {
+     *   const ok = await session.ui.confirm("Deploy to production?");
+     * }
+     * ```
+     */
+    get ui(): SessionUiApi;
     /**
      * Sends a message to this session and waits for the response.
      *
@@ -182,6 +202,11 @@ export declare class CopilotSession {
      * @internal
      */
     private _executePermissionAndRespond;
+    /**
+     * Executes a command handler and sends the result back via RPC.
+     * @internal
+     */
+    private _executeCommandAndRespond;
     /**
      * Registers custom tool handlers for this session.
      *
@@ -200,6 +225,28 @@ export declare class CopilotSession {
      * @internal This method is for internal use by the SDK.
      */
     getToolHandler(name: string): ToolHandler | undefined;
+    /**
+     * Registers command handlers for this session.
+     *
+     * @param commands - An array of command definitions with handlers, or undefined to clear
+     * @internal This method is typically called internally when creating/resuming a session.
+     */
+    registerCommands(commands?: {
+        name: string;
+        handler: CommandHandler;
+    }[]): void;
+    /**
+     * Sets the host capabilities for this session.
+     *
+     * @param capabilities - The capabilities object from the create/resume response
+     * @internal This method is typically called internally when creating/resuming a session.
+     */
+    setCapabilities(capabilities?: SessionCapabilities): void;
+    private assertElicitation;
+    private _elicitation;
+    private _confirm;
+    private _select;
+    private _input;
     /**
      * Registers a handler for permission requests.
      *

package/dist/session.js

@@ -21,12 +21,14 @@ class CopilotSession {
   eventHandlers = /* @__PURE__ */ new Set();
   typedEventHandlers = /* @__PURE__ */ new Map();
   toolHandlers = /* @__PURE__ */ new Map();
+  commandHandlers = /* @__PURE__ */ new Map();
   permissionHandler;
   userInputHandler;
   hooks;
   transformCallbacks;
   _rpc = null;
   traceContextProvider;
+  _capabilities = {};
   /**
    * Typed session-scoped RPC methods.
    */
@@ -44,6 +46,33 @@ class CopilotSession {
   get workspacePath() {
     return this._workspacePath;
   }
+  /**
+   * Host capabilities reported when the session was created or resumed.
+   * Use this to check feature support before calling capability-gated APIs.
+   */
+  get capabilities() {
+    return this._capabilities;
+  }
+  /**
+   * Interactive UI methods for showing dialogs to the user.
+   * Only available when the CLI host supports elicitation
+   * (`session.capabilities.ui?.elicitation === true`).
+   *
+   * @example
+   * ```typescript
+   * if (session.capabilities.ui?.elicitation) {
+   *   const ok = await session.ui.confirm("Deploy to production?");
+   * }
+   * ```
+   */
+  get ui() {
+    return {
+      elicitation: (params) => this._elicitation(params),
+      confirm: (message) => this._confirm(message),
+      select: (message, options) => this._select(message, options),
+      input: (message, options) => this._input(message, options)
+    };
+  }
   /**
    * Sends a message to this session and waits for the response.
    *
@@ -213,6 +242,9 @@ class CopilotSession {
       if (this.permissionHandler) {
         void this._executePermissionAndRespond(requestId, permissionRequest);
       }
+    } else if (event.type === "command.execute") {
+      const { requestId, commandName, command, args } = event.data;
+      void this._executeCommandAndRespond(requestId, commandName, command, args);
     }
   }
   /**
@@ -277,6 +309,39 @@ class CopilotSession {
       }
     }
   }
+  /**
+   * Executes a command handler and sends the result back via RPC.
+   * @internal
+   */
+  async _executeCommandAndRespond(requestId, commandName, command, args) {
+    const handler = this.commandHandlers.get(commandName);
+    if (!handler) {
+      try {
+        await this.rpc.commands.handlePendingCommand({
+          requestId,
+          error: `Unknown command: ${commandName}`
+        });
+      } catch (rpcError) {
+        if (!(rpcError instanceof ConnectionError || rpcError instanceof ResponseError)) {
+          throw rpcError;
+        }
+      }
+      return;
+    }
+    try {
+      await handler({ sessionId: this.sessionId, command, commandName, args });
+      await this.rpc.commands.handlePendingCommand({ requestId });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      try {
+        await this.rpc.commands.handlePendingCommand({ requestId, error: message });
+      } catch (rpcError) {
+        if (!(rpcError instanceof ConnectionError || rpcError instanceof ResponseError)) {
+          throw rpcError;
+        }
+      }
+    }
+  }
   /**
    * Registers custom tool handlers for this session.
    *
@@ -305,6 +370,99 @@ class CopilotSession {
   getToolHandler(name) {
     return this.toolHandlers.get(name);
   }
+  /**
+   * Registers command handlers for this session.
+   *
+   * @param commands - An array of command definitions with handlers, or undefined to clear
+   * @internal This method is typically called internally when creating/resuming a session.
+   */
+  registerCommands(commands) {
+    this.commandHandlers.clear();
+    if (!commands) {
+      return;
+    }
+    for (const cmd of commands) {
+      this.commandHandlers.set(cmd.name, cmd.handler);
+    }
+  }
+  /**
+   * Sets the host capabilities for this session.
+   *
+   * @param capabilities - The capabilities object from the create/resume response
+   * @internal This method is typically called internally when creating/resuming a session.
+   */
+  setCapabilities(capabilities) {
+    this._capabilities = capabilities ?? {};
+  }
+  assertElicitation() {
+    if (!this._capabilities.ui?.elicitation) {
+      throw new Error(
+        "Elicitation is not supported by the host. Check session.capabilities.ui?.elicitation before calling UI methods."
+      );
+    }
+  }
+  async _elicitation(params) {
+    this.assertElicitation();
+    return this.rpc.ui.elicitation({
+      message: params.message,
+      requestedSchema: params.requestedSchema
+    });
+  }
+  async _confirm(message) {
+    this.assertElicitation();
+    const result = await this.rpc.ui.elicitation({
+      message,
+      requestedSchema: {
+        type: "object",
+        properties: {
+          confirmed: { type: "boolean", default: true }
+        },
+        required: ["confirmed"]
+      }
+    });
+    return result.action === "accept" && result.content?.confirmed === true;
+  }
+  async _select(message, options) {
+    this.assertElicitation();
+    const result = await this.rpc.ui.elicitation({
+      message,
+      requestedSchema: {
+        type: "object",
+        properties: {
+          selection: { type: "string", enum: options }
+        },
+        required: ["selection"]
+      }
+    });
+    if (result.action === "accept" && result.content?.selection != null) {
+      return result.content.selection;
+    }
+    return null;
+  }
+  async _input(message, options) {
+    this.assertElicitation();
+    const field = { type: "string" };
+    if (options?.title) field.title = options.title;
+    if (options?.description) field.description = options.description;
+    if (options?.minLength != null) field.minLength = options.minLength;
+    if (options?.maxLength != null) field.maxLength = options.maxLength;
+    if (options?.format) field.format = options.format;
+    if (options?.default != null) field.default = options.default;
+    const result = await this.rpc.ui.elicitation({
+      message,
+      requestedSchema: {
+        type: "object",
+        properties: {
+          value: field
+        },
+        required: ["value"]
+      }
+    });
+    if (result.action === "accept" && result.content?.value != null) {
+      return result.content.value;
+    }
+    return null;
+  }
   /**
    * Registers a handler for permission requests.
    *

package/dist/types.d.ts

@@ -218,6 +218,187 @@ export declare function defineTool<T = unknown>(name: string, config: {
     overridesBuiltInTool?: boolean;
     skipPermission?: boolean;
 }): Tool<T>;
+/**
+ * Context passed to a command handler when a command is executed.
+ */
+export interface CommandContext {
+    /** Session ID where the command was invoked */
+    sessionId: string;
+    /** The full command text (e.g. "/deploy production") */
+    command: string;
+    /** Command name without leading / */
+    commandName: string;
+    /** Raw argument string after the command name */
+    args: string;
+}
+/**
+ * Handler invoked when a registered command is executed by a user.
+ */
+export type CommandHandler = (context: CommandContext) => Promise<void> | void;
+/**
+ * Definition of a slash command registered with the session.
+ * When the CLI is running with a TUI, registered commands appear as
+ * `/commandName` for the user to invoke.
+ */
+export interface CommandDefinition {
+    /** Command name (without leading /). */
+    name: string;
+    /** Human-readable description shown in command completion UI. */
+    description?: string;
+    /** Handler invoked when the command is executed. */
+    handler: CommandHandler;
+}
+/**
+ * Capabilities reported by the CLI host for this session.
+ */
+export interface SessionCapabilities {
+    ui?: {
+        /** Whether the host supports interactive elicitation dialogs. */
+        elicitation?: boolean;
+    };
+}
+/**
+ * A single field in an elicitation schema — matches the MCP SDK's
+ * `PrimitiveSchemaDefinition` union.
+ */
+export type ElicitationSchemaField = {
+    type: "string";
+    title?: string;
+    description?: string;
+    enum: string[];
+    enumNames?: string[];
+    default?: string;
+} | {
+    type: "string";
+    title?: string;
+    description?: string;
+    oneOf: {
+        const: string;
+        title: string;
+    }[];
+    default?: string;
+} | {
+    type: "array";
+    title?: string;
+    description?: string;
+    minItems?: number;
+    maxItems?: number;
+    items: {
+        type: "string";
+        enum: string[];
+    };
+    default?: string[];
+} | {
+    type: "array";
+    title?: string;
+    description?: string;
+    minItems?: number;
+    maxItems?: number;
+    items: {
+        anyOf: {
+            const: string;
+            title: string;
+        }[];
+    };
+    default?: string[];
+} | {
+    type: "boolean";
+    title?: string;
+    description?: string;
+    default?: boolean;
+} | {
+    type: "string";
+    title?: string;
+    description?: string;
+    minLength?: number;
+    maxLength?: number;
+    format?: "email" | "uri" | "date" | "date-time";
+    default?: string;
+} | {
+    type: "number" | "integer";
+    title?: string;
+    description?: string;
+    minimum?: number;
+    maximum?: number;
+    default?: number;
+};
+/**
+ * Schema describing the form fields for an elicitation request.
+ */
+export interface ElicitationSchema {
+    type: "object";
+    properties: Record<string, ElicitationSchemaField>;
+    required?: string[];
+}
+/**
+ * Primitive field value in an elicitation result.
+ * Matches MCP SDK's `ElicitResult.content` value type.
+ */
+export type ElicitationFieldValue = string | number | boolean | string[];
+/**
+ * Result returned from an elicitation request.
+ */
+export interface ElicitationResult {
+    /** User action: "accept" (submitted), "decline" (rejected), or "cancel" (dismissed). */
+    action: "accept" | "decline" | "cancel";
+    /** Form values submitted by the user (present when action is "accept"). */
+    content?: Record<string, ElicitationFieldValue>;
+}
+/**
+ * Parameters for a raw elicitation request.
+ */
+export interface ElicitationParams {
+    /** Message describing what information is needed from the user. */
+    message: string;
+    /** JSON Schema describing the form fields to present. */
+    requestedSchema: ElicitationSchema;
+}
+/**
+ * Options for the `input()` convenience method.
+ */
+export interface InputOptions {
+    /** Title label for the input field. */
+    title?: string;
+    /** Descriptive text shown below the field. */
+    description?: string;
+    /** Minimum character length. */
+    minLength?: number;
+    /** Maximum character length. */
+    maxLength?: number;
+    /** Semantic format hint. */
+    format?: "email" | "uri" | "date" | "date-time";
+    /** Default value pre-populated in the field. */
+    default?: string;
+}
+/**
+ * The `session.ui` API object providing interactive UI methods.
+ * Only usable when the CLI host supports elicitation.
+ */
+export interface SessionUiApi {
+    /**
+     * Shows a generic elicitation dialog with a custom schema.
+     * @throws Error if the host does not support elicitation.
+     */
+    elicitation(params: ElicitationParams): Promise<ElicitationResult>;
+    /**
+     * Shows a confirmation dialog and returns the user's boolean answer.
+     * Returns `false` if the user declines or cancels.
+     * @throws Error if the host does not support elicitation.
+     */
+    confirm(message: string): Promise<boolean>;
+    /**
+     * Shows a selection dialog with the given options.
+     * Returns the selected value, or `null` if the user declines/cancels.
+     * @throws Error if the host does not support elicitation.
+     */
+    select(message: string, options: string[]): Promise<string | null>;
+    /**
+     * Shows a text input dialog.
+     * Returns the entered text, or `null` if the user declines/cancels.
+     * @throws Error if the host does not support elicitation.
+     */
+    input(message: string, options?: InputOptions): Promise<string | null>;
+}
 export interface ToolCallRequestPayload {
     sessionId: string;
     toolCallId: string;
@@ -675,6 +856,12 @@ export interface SessionConfig {
      * Tools exposed to the CLI server
      */
     tools?: Tool<any>[];
+    /**
+     * Slash commands registered for this session.
+     * When the CLI has a TUI, each command appears as `/name` for the user to invoke.
+     * The handler is called when the user executes the command.
+     */
+    commands?: CommandDefinition[];
     /**
      * System message configuration
      * Controls how the system prompt is constructed
@@ -759,7 +946,7 @@ export interface SessionConfig {
 /**
  * Configuration for resuming a session
  */
-export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "tools" | "systemMessage" | "availableTools" | "excludedTools" | "provider" | "streaming" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "hooks" | "workingDirectory" | "configDir" | "mcpServers" | "customAgents" | "agent" | "skillDirectories" | "disabledSkills" | "infiniteSessions" | "onEvent"> & {
+export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "tools" | "commands" | "systemMessage" | "availableTools" | "excludedTools" | "provider" | "streaming" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "hooks" | "workingDirectory" | "configDir" | "mcpServers" | "customAgents" | "agent" | "skillDirectories" | "disabledSkills" | "infiniteSessions" | "onEvent"> & {
     /**
      * When true, skips emitting the session.resume event.
      * Useful for reconnecting to a session without triggering resume-related side effects.

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "0.2.0",
+  "version": "0.2.1-preview.1",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/cjs/index.js",
   "types": "./dist/index.d.ts",
@@ -56,7 +56,7 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@github/copilot": "^1.0.10",
+    "@github/copilot": "^1.0.12-0",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.6"
   },