@github/copilot-sdk 0.1.10-preview.1 → 0.1.11

package/dist/client.js

@@ -6,6 +6,7 @@ import {
   StreamMessageWriter
 } from "vscode-jsonrpc/node.js";
 import { CopilotSession } from "./session.js";
+import { getSdkProtocolVersion } from "./sdkProtocolVersion.js";
 function isZodSchema(value) {
   return value != null && typeof value === "object" && "toJSONSchema" in value && typeof value.toJSONSchema === "function";
 }
@@ -27,6 +28,27 @@ class CopilotClient {
   options;
   isExternalServer = false;
   forceStopping = false;
+  /**
+   * Creates a new CopilotClient instance.
+   *
+   * @param options - Configuration options for the client
+   * @throws Error if mutually exclusive options are provided (e.g., cliUrl with useStdio or cliPath)
+   *
+   * @example
+   * ```typescript
+   * // Default options - spawns CLI server using stdio
+   * const client = new CopilotClient();
+   *
+   * // Connect to an existing server
+   * const client = new CopilotClient({ cliUrl: "localhost:3000" });
+   *
+   * // Custom CLI path with specific log level
+   * const client = new CopilotClient({
+   *   cliPath: "/usr/local/bin/copilot",
+   *   logLevel: "debug"
+   * });
+   * ```
+   */
   constructor(options = {}) {
     if (options.cliUrl && (options.useStdio === true || options.cliPath)) {
       throw new Error("cliUrl is mutually exclusive with useStdio and cliPath");
@@ -74,7 +96,22 @@ class CopilotClient {
     return { host, port };
   }
   /**
-   * Start the CLI server and establish connection
+   * Starts the CLI server and establishes a connection.
+   *
+   * If connecting to an external server (via cliUrl), only establishes the connection.
+   * Otherwise, spawns the CLI server process and then connects.
+   *
+   * This method is called automatically when creating a session if `autoStart` is true (default).
+   *
+   * @returns A promise that resolves when the connection is established
+   * @throws Error if the server fails to start or the connection fails
+   *
+   * @example
+   * ```typescript
+   * const client = new CopilotClient({ autoStart: false });
+   * await client.start();
+   * // Now ready to create sessions
+   * ```
    */
   async start() {
     if (this.state === "connected") {
@@ -86,6 +123,7 @@ class CopilotClient {
         await this.startCLIServer();
       }
       await this.connectToServer();
+      await this.verifyProtocolVersion();
       this.state = "connected";
     } catch (error) {
       this.state = "error";
@@ -93,8 +131,23 @@ class CopilotClient {
     }
   }
   /**
-   * Stop the CLI server and close all sessions
-   * Returns array of errors encountered during cleanup (empty if all succeeded)
+   * Stops the CLI server and closes all active sessions.
+   *
+   * This method performs graceful cleanup:
+   * 1. Destroys all active sessions with retry logic
+   * 2. Closes the JSON-RPC connection
+   * 3. Terminates the CLI server process (if spawned by this client)
+   *
+   * @returns A promise that resolves with an array of errors encountered during cleanup.
+   *          An empty array indicates all cleanup succeeded.
+   *
+   * @example
+   * ```typescript
+   * const errors = await client.stop();
+   * if (errors.length > 0) {
+   *   console.error("Cleanup errors:", errors);
+   * }
+   * ```
    */
   async stop() {
     const errors = [];
@@ -164,8 +217,29 @@ class CopilotClient {
     return errors;
   }
   /**
-   * Force stop the CLI server without graceful cleanup
-   * Use when normal stop() fails or takes too long
+   * Forcefully stops the CLI server without graceful cleanup.
+   *
+   * Use this when {@link stop} fails or takes too long. This method:
+   * - Clears all sessions immediately without destroying them
+   * - Force closes the connection
+   * - Sends SIGKILL to the CLI process (if spawned by this client)
+   *
+   * @returns A promise that resolves when the force stop is complete
+   *
+   * @example
+   * ```typescript
+   * // If normal stop hangs, force stop
+   * const stopPromise = client.stop();
+   * const timeout = new Promise((_, reject) =>
+   *   setTimeout(() => reject(new Error("Timeout")), 5000)
+   * );
+   *
+   * try {
+   *   await Promise.race([stopPromise, timeout]);
+   * } catch {
+   *   await client.forceStop();
+   * }
+   * ```
    */
   async forceStop() {
     this.forceStopping = true;
@@ -195,7 +269,32 @@ class CopilotClient {
     this.actualPort = null;
   }
   /**
-   * Create a new session
+   * Creates a new conversation session with the Copilot CLI.
+   *
+   * Sessions maintain conversation state, handle events, and manage tool execution.
+   * If the client is not connected and `autoStart` is enabled, this will automatically
+   * start the connection.
+   *
+   * @param config - Optional configuration for the session
+   * @returns A promise that resolves with the created session
+   * @throws Error if the client is not connected and autoStart is disabled
+   *
+   * @example
+   * ```typescript
+   * // Basic session
+   * const session = await client.createSession();
+   *
+   * // Session with model and tools
+   * const session = await client.createSession({
+   *   model: "gpt-4",
+   *   tools: [{
+   *     name: "get_weather",
+   *     description: "Get weather for a location",
+   *     parameters: { type: "object", properties: { location: { type: "string" } } },
+   *     handler: async (args) => ({ temperature: 72 })
+   *   }]
+   * });
+   * ```
    */
   async createSession(config = {}) {
     if (!this.connection) {
@@ -218,7 +317,9 @@ class CopilotClient {
       excludedTools: config.excludedTools,
       provider: config.provider,
       requestPermission: !!config.onPermissionRequest,
-      streaming: config.streaming
+      streaming: config.streaming,
+      mcpServers: config.mcpServers,
+      customAgents: config.customAgents
     });
     const sessionId = response.sessionId;
     const session = new CopilotSession(sessionId, this.connection);
@@ -230,7 +331,27 @@ class CopilotClient {
     return session;
   }
   /**
-   * Resume an existing session
+   * Resumes an existing conversation session by its ID.
+   *
+   * This allows you to continue a previous conversation, maintaining all
+   * conversation history. The session must have been previously created
+   * and not deleted.
+   *
+   * @param sessionId - The ID of the session to resume
+   * @param config - Optional configuration for the resumed session
+   * @returns A promise that resolves with the resumed session
+   * @throws Error if the session does not exist or the client is not connected
+   *
+   * @example
+   * ```typescript
+   * // Resume a previous session
+   * const session = await client.resumeSession("session-123");
+   *
+   * // Resume with new tools
+   * const session = await client.resumeSession("session-123", {
+   *   tools: [myNewTool]
+   * });
+   * ```
    */
   async resumeSession(sessionId, config = {}) {
     if (!this.connection) {
@@ -249,7 +370,9 @@ class CopilotClient {
       })),
       provider: config.provider,
       requestPermission: !!config.onPermissionRequest,
-      streaming: config.streaming
+      streaming: config.streaming,
+      mcpServers: config.mcpServers,
+      customAgents: config.customAgents
     });
     const resumedSessionId = response.sessionId;
     const session = new CopilotSession(resumedSessionId, this.connection);
@@ -261,13 +384,32 @@ class CopilotClient {
     return session;
   }
   /**
-   * Get connection state
+   * Gets the current connection state of the client.
+   *
+   * @returns The current connection state: "disconnected", "connecting", "connected", or "error"
+   *
+   * @example
+   * ```typescript
+   * if (client.getState() === "connected") {
+   *   const session = await client.createSession();
+   * }
+   * ```
    */
   getState() {
     return this.state;
   }
   /**
-   * Ping the server
+   * Sends a ping request to the server to verify connectivity.
+   *
+   * @param message - Optional message to include in the ping
+   * @returns A promise that resolves with the ping response containing the message and timestamp
+   * @throws Error if the client is not connected
+   *
+   * @example
+   * ```typescript
+   * const response = await client.ping("health check");
+   * console.log(`Server responded at ${new Date(response.timestamp)}`);
+   * ```
    */
   async ping(message) {
     if (!this.connection) {
@@ -277,8 +419,39 @@ class CopilotClient {
     return result;
   }
   /**
-   * Get the ID of the most recently updated session
-   * @returns The session ID, or undefined if no sessions exist
+   * Verify that the server's protocol version matches the SDK's expected version
+   */
+  async verifyProtocolVersion() {
+    const expectedVersion = getSdkProtocolVersion();
+    const pingResult = await this.ping();
+    const serverVersion = pingResult.protocolVersion;
+    if (serverVersion === void 0) {
+      throw new Error(
+        `SDK protocol version mismatch: SDK expects version ${expectedVersion}, but server does not report a protocol version. Please update your server to ensure compatibility.`
+      );
+    }
+    if (serverVersion !== expectedVersion) {
+      throw new Error(
+        `SDK protocol version mismatch: SDK expects version ${expectedVersion}, but server reports version ${serverVersion}. Please update your SDK or server to ensure compatibility.`
+      );
+    }
+  }
+  /**
+   * Gets the ID of the most recently updated session.
+   *
+   * This is useful for resuming the last conversation when the session ID
+   * was not stored.
+   *
+   * @returns A promise that resolves with the session ID, or undefined if no sessions exist
+   * @throws Error if the client is not connected
+   *
+   * @example
+   * ```typescript
+   * const lastId = await client.getLastSessionId();
+   * if (lastId) {
+   *   const session = await client.resumeSession(lastId);
+   * }
+   * ```
    */
   async getLastSessionId() {
     if (!this.connection) {
@@ -288,8 +461,19 @@ class CopilotClient {
     return response.sessionId;
   }
   /**
-   * Delete a session and its data from disk
-   * @param sessionId The ID of the session to delete
+   * Deletes a session and its data from disk.
+   *
+   * This permanently removes the session and all its conversation history.
+   * The session cannot be resumed after deletion.
+   *
+   * @param sessionId - The ID of the session to delete
+   * @returns A promise that resolves when the session is deleted
+   * @throws Error if the session does not exist or deletion fails
+   *
+   * @example
+   * ```typescript
+   * await client.deleteSession("session-123");
+   * ```
    */
   async deleteSession(sessionId) {
     if (!this.connection) {
@@ -305,8 +489,20 @@ class CopilotClient {
     this.sessions.delete(sessionId);
   }
   /**
-   * List all available sessions
-   * @returns Array of session metadata
+   * Lists all available sessions known to the server.
+   *
+   * Returns metadata about each session including ID, timestamps, and summary.
+   *
+   * @returns A promise that resolves with an array of session metadata
+   * @throws Error if the client is not connected
+   *
+   * @example
+   * ```typescript
+   * const sessions = await client.listSessions();
+   * for (const session of sessions) {
+   *   console.log(`${session.sessionId}: ${session.summary}`);
+   * }
+   * ```
    */
   async listSessions() {
     if (!this.connection) {

package/dist/nodejs/src/client.d.ts

@@ -0,0 +1,306 @@
+import { CopilotSession } from "./session.js";
+import type { ConnectionState, CopilotClientOptions, ResumeSessionConfig, SessionConfig, SessionMetadata } from "./types.js";
+/**
+ * Main client for interacting with the Copilot CLI.
+ *
+ * The CopilotClient manages the connection to the Copilot CLI server and provides
+ * methods to create and manage conversation sessions. It can either spawn a CLI
+ * server process or connect to an existing server.
+ *
+ * @example
+ * ```typescript
+ * import { CopilotClient } from "@github/copilot-sdk";
+ *
+ * // Create a client with default options (spawns CLI server)
+ * const client = new CopilotClient();
+ *
+ * // Or connect to an existing server
+ * const client = new CopilotClient({ cliUrl: "localhost:3000" });
+ *
+ * // Create a session
+ * const session = await client.createSession({ model: "gpt-4" });
+ *
+ * // Send messages and handle responses
+ * session.on((event) => {
+ *   if (event.type === "assistant.message") {
+ *     console.log(event.data.content);
+ *   }
+ * });
+ * await session.send({ prompt: "Hello!" });
+ *
+ * // Clean up
+ * await session.destroy();
+ * await client.stop();
+ * ```
+ */
+export declare class CopilotClient {
+    private cliProcess;
+    private connection;
+    private socket;
+    private actualPort;
+    private actualHost;
+    private state;
+    private sessions;
+    private options;
+    private isExternalServer;
+    private forceStopping;
+    /**
+     * Creates a new CopilotClient instance.
+     *
+     * @param options - Configuration options for the client
+     * @throws Error if mutually exclusive options are provided (e.g., cliUrl with useStdio or cliPath)
+     *
+     * @example
+     * ```typescript
+     * // Default options - spawns CLI server using stdio
+     * const client = new CopilotClient();
+     *
+     * // Connect to an existing server
+     * const client = new CopilotClient({ cliUrl: "localhost:3000" });
+     *
+     * // Custom CLI path with specific log level
+     * const client = new CopilotClient({
+     *   cliPath: "/usr/local/bin/copilot",
+     *   logLevel: "debug"
+     * });
+     * ```
+     */
+    constructor(options?: CopilotClientOptions);
+    /**
+     * Parse CLI URL into host and port
+     * Supports formats: "host:port", "http://host:port", "https://host:port", or just "port"
+     */
+    private parseCliUrl;
+    /**
+     * Starts the CLI server and establishes a connection.
+     *
+     * If connecting to an external server (via cliUrl), only establishes the connection.
+     * Otherwise, spawns the CLI server process and then connects.
+     *
+     * This method is called automatically when creating a session if `autoStart` is true (default).
+     *
+     * @returns A promise that resolves when the connection is established
+     * @throws Error if the server fails to start or the connection fails
+     *
+     * @example
+     * ```typescript
+     * const client = new CopilotClient({ autoStart: false });
+     * await client.start();
+     * // Now ready to create sessions
+     * ```
+     */
+    start(): Promise<void>;
+    /**
+     * Stops the CLI server and closes all active sessions.
+     *
+     * This method performs graceful cleanup:
+     * 1. Destroys all active sessions with retry logic
+     * 2. Closes the JSON-RPC connection
+     * 3. Terminates the CLI server process (if spawned by this client)
+     *
+     * @returns A promise that resolves with an array of errors encountered during cleanup.
+     *          An empty array indicates all cleanup succeeded.
+     *
+     * @example
+     * ```typescript
+     * const errors = await client.stop();
+     * if (errors.length > 0) {
+     *   console.error("Cleanup errors:", errors);
+     * }
+     * ```
+     */
+    stop(): Promise<Error[]>;
+    /**
+     * Forcefully stops the CLI server without graceful cleanup.
+     *
+     * Use this when {@link stop} fails or takes too long. This method:
+     * - Clears all sessions immediately without destroying them
+     * - Force closes the connection
+     * - Sends SIGKILL to the CLI process (if spawned by this client)
+     *
+     * @returns A promise that resolves when the force stop is complete
+     *
+     * @example
+     * ```typescript
+     * // If normal stop hangs, force stop
+     * const stopPromise = client.stop();
+     * const timeout = new Promise((_, reject) =>
+     *   setTimeout(() => reject(new Error("Timeout")), 5000)
+     * );
+     *
+     * try {
+     *   await Promise.race([stopPromise, timeout]);
+     * } catch {
+     *   await client.forceStop();
+     * }
+     * ```
+     */
+    forceStop(): Promise<void>;
+    /**
+     * Creates a new conversation session with the Copilot CLI.
+     *
+     * Sessions maintain conversation state, handle events, and manage tool execution.
+     * If the client is not connected and `autoStart` is enabled, this will automatically
+     * start the connection.
+     *
+     * @param config - Optional configuration for the session
+     * @returns A promise that resolves with the created session
+     * @throws Error if the client is not connected and autoStart is disabled
+     *
+     * @example
+     * ```typescript
+     * // Basic session
+     * const session = await client.createSession();
+     *
+     * // Session with model and tools
+     * const session = await client.createSession({
+     *   model: "gpt-4",
+     *   tools: [{
+     *     name: "get_weather",
+     *     description: "Get weather for a location",
+     *     parameters: { type: "object", properties: { location: { type: "string" } } },
+     *     handler: async (args) => ({ temperature: 72 })
+     *   }]
+     * });
+     * ```
+     */
+    createSession(config?: SessionConfig): Promise<CopilotSession>;
+    /**
+     * Resumes an existing conversation session by its ID.
+     *
+     * This allows you to continue a previous conversation, maintaining all
+     * conversation history. The session must have been previously created
+     * and not deleted.
+     *
+     * @param sessionId - The ID of the session to resume
+     * @param config - Optional configuration for the resumed session
+     * @returns A promise that resolves with the resumed session
+     * @throws Error if the session does not exist or the client is not connected
+     *
+     * @example
+     * ```typescript
+     * // Resume a previous session
+     * const session = await client.resumeSession("session-123");
+     *
+     * // Resume with new tools
+     * const session = await client.resumeSession("session-123", {
+     *   tools: [myNewTool]
+     * });
+     * ```
+     */
+    resumeSession(sessionId: string, config?: ResumeSessionConfig): Promise<CopilotSession>;
+    /**
+     * Gets the current connection state of the client.
+     *
+     * @returns The current connection state: "disconnected", "connecting", "connected", or "error"
+     *
+     * @example
+     * ```typescript
+     * if (client.getState() === "connected") {
+     *   const session = await client.createSession();
+     * }
+     * ```
+     */
+    getState(): ConnectionState;
+    /**
+     * Sends a ping request to the server to verify connectivity.
+     *
+     * @param message - Optional message to include in the ping
+     * @returns A promise that resolves with the ping response containing the message and timestamp
+     * @throws Error if the client is not connected
+     *
+     * @example
+     * ```typescript
+     * const response = await client.ping("health check");
+     * console.log(`Server responded at ${new Date(response.timestamp)}`);
+     * ```
+     */
+    ping(message?: string): Promise<{
+        message: string;
+        timestamp: number;
+        protocolVersion?: number;
+    }>;
+    /**
+     * Verify that the server's protocol version matches the SDK's expected version
+     */
+    private verifyProtocolVersion;
+    /**
+     * Gets the ID of the most recently updated session.
+     *
+     * This is useful for resuming the last conversation when the session ID
+     * was not stored.
+     *
+     * @returns A promise that resolves with the session ID, or undefined if no sessions exist
+     * @throws Error if the client is not connected
+     *
+     * @example
+     * ```typescript
+     * const lastId = await client.getLastSessionId();
+     * if (lastId) {
+     *   const session = await client.resumeSession(lastId);
+     * }
+     * ```
+     */
+    getLastSessionId(): Promise<string | undefined>;
+    /**
+     * Deletes a session and its data from disk.
+     *
+     * This permanently removes the session and all its conversation history.
+     * The session cannot be resumed after deletion.
+     *
+     * @param sessionId - The ID of the session to delete
+     * @returns A promise that resolves when the session is deleted
+     * @throws Error if the session does not exist or deletion fails
+     *
+     * @example
+     * ```typescript
+     * await client.deleteSession("session-123");
+     * ```
+     */
+    deleteSession(sessionId: string): Promise<void>;
+    /**
+     * Lists all available sessions known to the server.
+     *
+     * Returns metadata about each session including ID, timestamps, and summary.
+     *
+     * @returns A promise that resolves with an array of session metadata
+     * @throws Error if the client is not connected
+     *
+     * @example
+     * ```typescript
+     * const sessions = await client.listSessions();
+     * for (const session of sessions) {
+     *   console.log(`${session.sessionId}: ${session.summary}`);
+     * }
+     * ```
+     */
+    listSessions(): Promise<SessionMetadata[]>;
+    /**
+     * Start the CLI server process
+     */
+    private startCLIServer;
+    /**
+     * Connect to the CLI server (via socket or stdio)
+     */
+    private connectToServer;
+    /**
+     * Connect via stdio pipes
+     */
+    private connectViaStdio;
+    /**
+     * Connect to the CLI server via TCP socket
+     */
+    private connectViaTcp;
+    private attachConnectionHandlers;
+    private handleSessionEventNotification;
+    private handleToolCallRequest;
+    private executeToolCall;
+    private handlePermissionRequest;
+    private normalizeToolResult;
+    private isToolResultObject;
+    private buildUnsupportedToolResult;
+    /**
+     * Attempt to reconnect to the server
+     */
+    private reconnect;
+}

package/dist/{generated → nodejs/src/generated}/session-events.d.ts

@@ -3,7 +3,7 @@
  *
  * Generated from: @github/copilot/session-events.schema.json
  * Generated by: scripts/generate-session-types.ts
- * Generated at: 2026-01-08T23:59:19.905Z
+ * Generated at: 2026-01-13T00:08:20.716Z
  *
  * To update these types:
  * 1. Update the schema in copilot-agent-runtime
@@ -121,6 +121,13 @@ export type SessionEvent = {
         }[];
         source?: string;
     };
+} | {
+    id: string;
+    timestamp: string;
+    parentId: string | null;
+    ephemeral: true;
+    type: "pending_messages.modified";
+    data: {};
 } | {
     id: string;
     timestamp: string;

package/dist/nodejs/src/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copilot SDK - TypeScript/Node.js Client
+ *
+ * JSON-RPC based SDK for programmatic control of GitHub Copilot CLI
+ */
+export { CopilotClient } from "./client.js";
+export { CopilotSession } from "./session.js";
+export { defineTool } from "./types.js";
+export type { ConnectionState, CopilotClientOptions, CustomAgentConfig, MCPLocalServerConfig, MCPRemoteServerConfig, MCPServerConfig, MessageOptions, PermissionHandler, PermissionRequest, PermissionRequestResult, ResumeSessionConfig, SessionConfig, SessionEvent, SessionEventHandler, SessionMetadata, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageReplaceConfig, Tool, ToolHandler, ToolInvocation, ToolResultObject, ZodSchema, } from "./types.js";

package/dist/nodejs/src/sdkProtocolVersion.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Gets the SDK protocol version from sdk-protocol-version.json.
+ * @returns The protocol version number
+ */
+export declare function getSdkProtocolVersion(): number;

package/dist/nodejs/src/session.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Copilot Session - represents a single conversation session with the Copilot CLI.
+ * @module session
+ */
+import type { MessageConnection } from "vscode-jsonrpc/node";
+import type { MessageOptions, PermissionHandler, PermissionRequestResult, SessionEvent, SessionEventHandler, Tool, ToolHandler } from "./types.js";
+/**
+ * Represents a single conversation session with the Copilot CLI.
+ *
+ * A session maintains conversation state, handles events, and manages tool execution.
+ * Sessions are created via {@link CopilotClient.createSession} or resumed via
+ * {@link CopilotClient.resumeSession}.
+ *
+ * @example
+ * ```typescript
+ * const session = await client.createSession({ model: "gpt-4" });
+ *
+ * // Subscribe to events
+ * const unsubscribe = session.on((event) => {
+ *   if (event.type === "assistant.message") {
+ *     console.log(event.data.content);
+ *   }
+ * });
+ *
+ * // Send a message
+ * await session.send({ prompt: "Hello, world!" });
+ *
+ * // Clean up
+ * unsubscribe();
+ * await session.destroy();
+ * ```
+ */
+export declare class CopilotSession {
+    readonly sessionId: string;
+    private connection;
+    private eventHandlers;
+    private toolHandlers;
+    private permissionHandler?;
+    /**
+     * Creates a new CopilotSession instance.
+     *
+     * @param sessionId - The unique identifier for this session
+     * @param connection - The JSON-RPC message connection to the Copilot CLI
+     * @internal This constructor is internal. Use {@link CopilotClient.createSession} to create sessions.
+     */
+    constructor(sessionId: string, connection: MessageConnection);
+    /**
+     * Sends a message to this session and waits for the response.
+     *
+     * The message is processed asynchronously. Subscribe to events via {@link on}
+     * to receive streaming responses and other session events.
+     *
+     * @param options - The message options including the prompt and optional attachments
+     * @returns A promise that resolves with the message ID of the response
+     * @throws Error if the session has been destroyed or the connection fails
+     *
+     * @example
+     * ```typescript
+     * const messageId = await session.send({
+     *   prompt: "Explain this code",
+     *   attachments: [{ type: "file", path: "./src/index.ts" }]
+     * });
+     * ```
+     */
+    send(options: MessageOptions): Promise<string>;
+    /**
+     * Subscribes to events from this session.
+     *
+     * Events include assistant messages, tool executions, errors, and session state changes.
+     * Multiple handlers can be registered and will all receive events.
+     *
+     * @param handler - A callback function that receives session events
+     * @returns A function that, when called, unsubscribes the handler
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = session.on((event) => {
+     *   switch (event.type) {
+     *     case "assistant.message":
+     *       console.log("Assistant:", event.data.content);
+     *       break;
+     *     case "session.error":
+     *       console.error("Error:", event.data.message);
+     *       break;
+     *   }
+     * });
+     *
+     * // Later, to stop receiving events:
+     * unsubscribe();
+     * ```
+     */
+    on(handler: SessionEventHandler): () => void;
+    /**
+     * Dispatches an event to all registered handlers.
+     *
+     * @param event - The session event to dispatch
+     * @internal This method is for internal use by the SDK.
+     */
+    _dispatchEvent(event: SessionEvent): void;
+    /**
+     * Registers custom tool handlers for this session.
+     *
+     * Tools allow the assistant to execute custom functions. When the assistant
+     * invokes a tool, the corresponding handler is called with the tool arguments.
+     *
+     * @param tools - An array of tool definitions with their handlers, or undefined to clear all tools
+     * @internal This method is typically called internally when creating a session with tools.
+     */
+    registerTools(tools?: Tool[]): void;
+    /**
+     * Retrieves a registered tool handler by name.
+     *
+     * @param name - The name of the tool to retrieve
+     * @returns The tool handler if found, or undefined
+     * @internal This method is for internal use by the SDK.
+     */
+    getToolHandler(name: string): ToolHandler | undefined;
+    /**
+     * Registers a handler for permission requests.
+     *
+     * When the assistant needs permission to perform certain actions (e.g., file operations),
+     * this handler is called to approve or deny the request.
+     *
+     * @param handler - The permission handler function, or undefined to remove the handler
+     * @internal This method is typically called internally when creating a session.
+     */
+    registerPermissionHandler(handler?: PermissionHandler): void;
+    /**
+     * Handles a permission request from the Copilot CLI.
+     *
+     * @param request - The permission request data from the CLI
+     * @returns A promise that resolves with the permission decision
+     * @internal This method is for internal use by the SDK.
+     */
+    _handlePermissionRequest(request: unknown): Promise<PermissionRequestResult>;
+    /**
+     * Retrieves all events and messages from this session's history.
+     *
+     * This returns the complete conversation history including user messages,
+     * assistant responses, tool executions, and other session events.
+     *
+     * @returns A promise that resolves with an array of all session events
+     * @throws Error if the session has been destroyed or the connection fails
+     *
+     * @example
+     * ```typescript
+     * const events = await session.getMessages();
+     * for (const event of events) {
+     *   if (event.type === "assistant.message") {
+     *     console.log("Assistant:", event.data.content);
+     *   }
+     * }
+     * ```
+     */
+    getMessages(): Promise<SessionEvent[]>;
+    /**
+     * Destroys this session and releases all associated resources.
+     *
+     * After calling this method, the session can no longer be used. All event
+     * handlers and tool handlers are cleared. To continue the conversation,
+     * use {@link CopilotClient.resumeSession} with the session ID.
+     *
+     * @returns A promise that resolves when the session is destroyed
+     * @throws Error if the connection fails
+     *
+     * @example
+     * ```typescript
+     * // Clean up when done
+     * await session.destroy();
+     * ```
+     */
+    destroy(): Promise<void>;
+    /**
+     * Aborts the currently processing message in this session.
+     *
+     * Use this to cancel a long-running request. The session remains valid
+     * and can continue to be used for new messages.
+     *
+     * @returns A promise that resolves when the abort request is acknowledged
+     * @throws Error if the session has been destroyed or the connection fails
+     *
+     * @example
+     * ```typescript
+     * // Start a long-running request
+     * const messagePromise = session.send({ prompt: "Write a very long story..." });
+     *
+     * // Abort after 5 seconds
+     * setTimeout(async () => {
+     *   await session.abort();
+     * }, 5000);
+     * ```
+     */
+    abort(): Promise<void>;
+}

package/dist/{types.d.ts → nodejs/src/types.d.ts}

@@ -166,6 +166,90 @@ export interface PermissionRequestResult {
 export type PermissionHandler = (request: PermissionRequest, invocation: {
     sessionId: string;
 }) => Promise<PermissionRequestResult> | PermissionRequestResult;
+/**
+ * Base interface for MCP server configuration.
+ */
+interface MCPServerConfigBase {
+    /**
+     * List of tools to include from this server. [] means none. "*" means all.
+     */
+    tools: string[];
+    /**
+     * Indicates "remote" or "local" server type.
+     * If not specified, defaults to "local".
+     */
+    type?: string;
+    /**
+     * Optional timeout in milliseconds for tool calls to this server.
+     */
+    timeout?: number;
+}
+/**
+ * Configuration for a local/stdio MCP server.
+ */
+export interface MCPLocalServerConfig extends MCPServerConfigBase {
+    type?: "local" | "stdio";
+    command: string;
+    args: string[];
+    /**
+     * Environment variables to pass to the server.
+     */
+    env?: Record<string, string>;
+    cwd?: string;
+}
+/**
+ * Configuration for a remote MCP server (HTTP or SSE).
+ */
+export interface MCPRemoteServerConfig extends MCPServerConfigBase {
+    type: "http" | "sse";
+    /**
+     * URL of the remote server.
+     */
+    url: string;
+    /**
+     * Optional HTTP headers to include in requests.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Union type for MCP server configurations.
+ */
+export type MCPServerConfig = MCPLocalServerConfig | MCPRemoteServerConfig;
+/**
+ * Configuration for a custom agent.
+ */
+export interface CustomAgentConfig {
+    /**
+     * Unique name of the custom agent.
+     */
+    name: string;
+    /**
+     * Display name for UI purposes.
+     */
+    displayName?: string;
+    /**
+     * Description of what the agent does.
+     */
+    description?: string;
+    /**
+     * List of tool names the agent can use.
+     * Use null or undefined for all tools.
+     */
+    tools?: string[] | null;
+    /**
+     * The prompt content for the agent.
+     */
+    prompt: string;
+    /**
+     * MCP servers specific to this agent.
+     */
+    mcpServers?: Record<string, MCPServerConfig>;
+    /**
+     * Whether the agent should be available for model inference.
+     * @default true
+     */
+    infer?: boolean;
+}
 export interface SessionConfig {
     /**
      * Optional custom session ID
@@ -206,11 +290,20 @@ export interface SessionConfig {
      */
     onPermissionRequest?: PermissionHandler;
     streaming?: boolean;
+    /**
+     * MCP server configurations for the session.
+     * Keys are server names, values are server configurations.
+     */
+    mcpServers?: Record<string, MCPServerConfig>;
+    /**
+     * Custom agent configurations for the session.
+     */
+    customAgents?: CustomAgentConfig[];
 }
 /**
  * Configuration for resuming a session
  */
-export type ResumeSessionConfig = Pick<SessionConfig, "tools" | "provider" | "streaming" | "onPermissionRequest">;
+export type ResumeSessionConfig = Pick<SessionConfig, "tools" | "provider" | "streaming" | "onPermissionRequest" | "mcpServers" | "customAgents">;
 /**
  * Configuration for a custom API provider.
  */
@@ -288,3 +381,4 @@ export interface SessionMetadata {
     summary?: string;
     isRemote: boolean;
 }
+export {};

package/dist/sdkProtocolVersion.js

@@ -0,0 +1,7 @@
+import sdkProtocolVersion from "../../sdk-protocol-version.json";
+function getSdkProtocolVersion() {
+  return sdkProtocolVersion.version;
+}
+export {
+  getSdkProtocolVersion
+};

package/dist/session.js

@@ -1,4 +1,11 @@
 class CopilotSession {
+  /**
+   * Creates a new CopilotSession instance.
+   *
+   * @param sessionId - The unique identifier for this session
+   * @param connection - The JSON-RPC message connection to the Copilot CLI
+   * @internal This constructor is internal. Use {@link CopilotClient.createSession} to create sessions.
+   */
   constructor(sessionId, connection) {
     this.sessionId = sessionId;
     this.connection = connection;
@@ -7,7 +14,22 @@ class CopilotSession {
   toolHandlers = /* @__PURE__ */ new Map();
   permissionHandler;
   /**
-   * Send a message to this session
+   * Sends a message to this session and waits for the response.
+   *
+   * The message is processed asynchronously. Subscribe to events via {@link on}
+   * to receive streaming responses and other session events.
+   *
+   * @param options - The message options including the prompt and optional attachments
+   * @returns A promise that resolves with the message ID of the response
+   * @throws Error if the session has been destroyed or the connection fails
+   *
+   * @example
+   * ```typescript
+   * const messageId = await session.send({
+   *   prompt: "Explain this code",
+   *   attachments: [{ type: "file", path: "./src/index.ts" }]
+   * });
+   * ```
    */
   async send(options) {
     const response = await this.connection.sendRequest("session.send", {
@@ -19,8 +41,30 @@ class CopilotSession {
     return response.messageId;
   }
   /**
-   * Subscribe to events from this session
-   * @returns Unsubscribe function
+   * Subscribes to events from this session.
+   *
+   * Events include assistant messages, tool executions, errors, and session state changes.
+   * Multiple handlers can be registered and will all receive events.
+   *
+   * @param handler - A callback function that receives session events
+   * @returns A function that, when called, unsubscribes the handler
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = session.on((event) => {
+   *   switch (event.type) {
+   *     case "assistant.message":
+   *       console.log("Assistant:", event.data.content);
+   *       break;
+   *     case "session.error":
+   *       console.error("Error:", event.data.message);
+   *       break;
+   *   }
+   * });
+   *
+   * // Later, to stop receiving events:
+   * unsubscribe();
+   * ```
    */
   on(handler) {
     this.eventHandlers.add(handler);
@@ -29,7 +73,10 @@ class CopilotSession {
     };
   }
   /**
-   * Internal: dispatch an event to all handlers
+   * Dispatches an event to all registered handlers.
+   *
+   * @param event - The session event to dispatch
+   * @internal This method is for internal use by the SDK.
    */
   _dispatchEvent(event) {
     for (const handler of this.eventHandlers) {
@@ -39,6 +86,15 @@ class CopilotSession {
       }
     }
   }
+  /**
+   * Registers custom tool handlers for this session.
+   *
+   * Tools allow the assistant to execute custom functions. When the assistant
+   * invokes a tool, the corresponding handler is called with the tool arguments.
+   *
+   * @param tools - An array of tool definitions with their handlers, or undefined to clear all tools
+   * @internal This method is typically called internally when creating a session with tools.
+   */
   registerTools(tools) {
     this.toolHandlers.clear();
     if (!tools) {
@@ -48,12 +104,35 @@ class CopilotSession {
       this.toolHandlers.set(tool.name, tool.handler);
     }
   }
+  /**
+   * Retrieves a registered tool handler by name.
+   *
+   * @param name - The name of the tool to retrieve
+   * @returns The tool handler if found, or undefined
+   * @internal This method is for internal use by the SDK.
+   */
   getToolHandler(name) {
     return this.toolHandlers.get(name);
   }
+  /**
+   * Registers a handler for permission requests.
+   *
+   * When the assistant needs permission to perform certain actions (e.g., file operations),
+   * this handler is called to approve or deny the request.
+   *
+   * @param handler - The permission handler function, or undefined to remove the handler
+   * @internal This method is typically called internally when creating a session.
+   */
   registerPermissionHandler(handler) {
     this.permissionHandler = handler;
   }
+  /**
+   * Handles a permission request from the Copilot CLI.
+   *
+   * @param request - The permission request data from the CLI
+   * @returns A promise that resolves with the permission decision
+   * @internal This method is for internal use by the SDK.
+   */
   async _handlePermissionRequest(request) {
     if (!this.permissionHandler) {
       return { kind: "denied-no-approval-rule-and-could-not-request-from-user" };
@@ -68,7 +147,23 @@ class CopilotSession {
     }
   }
   /**
-   * Get all events/messages from this session
+   * Retrieves all events and messages from this session's history.
+   *
+   * This returns the complete conversation history including user messages,
+   * assistant responses, tool executions, and other session events.
+   *
+   * @returns A promise that resolves with an array of all session events
+   * @throws Error if the session has been destroyed or the connection fails
+   *
+   * @example
+   * ```typescript
+   * const events = await session.getMessages();
+   * for (const event of events) {
+   *   if (event.type === "assistant.message") {
+   *     console.log("Assistant:", event.data.content);
+   *   }
+   * }
+   * ```
    */
   async getMessages() {
     const response = await this.connection.sendRequest("session.getMessages", {
@@ -77,7 +172,20 @@ class CopilotSession {
     return response.events;
   }
   /**
-   * Destroy this session and free resources
+   * Destroys this session and releases all associated resources.
+   *
+   * After calling this method, the session can no longer be used. All event
+   * handlers and tool handlers are cleared. To continue the conversation,
+   * use {@link CopilotClient.resumeSession} with the session ID.
+   *
+   * @returns A promise that resolves when the session is destroyed
+   * @throws Error if the connection fails
+   *
+   * @example
+   * ```typescript
+   * // Clean up when done
+   * await session.destroy();
+   * ```
    */
   async destroy() {
     await this.connection.sendRequest("session.destroy", {
@@ -88,7 +196,24 @@ class CopilotSession {
     this.permissionHandler = void 0;
   }
   /**
-   * Abort the currently processing message in this session
+   * Aborts the currently processing message in this session.
+   *
+   * Use this to cancel a long-running request. The session remains valid
+   * and can continue to be used for new messages.
+   *
+   * @returns A promise that resolves when the abort request is acknowledged
+   * @throws Error if the session has been destroyed or the connection fails
+   *
+   * @example
+   * ```typescript
+   * // Start a long-running request
+   * const messagePromise = session.send({ prompt: "Write a very long story..." });
+   *
+   * // Abort after 5 seconds
+   * setTimeout(async () => {
+   *   await session.abort();
+   * }, 5000);
+   * ```
    */
   async abort() {
     await this.connection.sendRequest("session.abort", {

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "0.1.10-preview.1",
+  "version": "0.1.11",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -26,6 +26,7 @@
     "lint:fix": "eslint --fix \"src/**/*.ts\" \"test/**/*.ts\"",
     "typecheck": "tsc --noEmit",
     "generate:session-types": "tsx scripts/generate-session-types.ts",
+    "update:protocol-version": "tsx scripts/generate-protocol-version.ts",
     "prepublishOnly": "npm run build",
     "package": "npm run clean && npm run build && node scripts/set-version.js && npm pack && npm version 0.1.0 --no-git-tag-version --allow-same-version"
   },
@@ -39,12 +40,12 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@github/copilot": "^0.0.378-0",
+    "@github/copilot": "^0.0.382-0",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^22.19.6",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",
     "esbuild": "^0.27.0",

package/dist/client.d.ts

@@ -1,96 +0,0 @@
-import { CopilotSession } from "./session.js";
-import type { ConnectionState, CopilotClientOptions, ResumeSessionConfig, SessionConfig, SessionMetadata } from "./types.js";
-export declare class CopilotClient {
-    private cliProcess;
-    private connection;
-    private socket;
-    private actualPort;
-    private actualHost;
-    private state;
-    private sessions;
-    private options;
-    private isExternalServer;
-    private forceStopping;
-    constructor(options?: CopilotClientOptions);
-    /**
-     * Parse CLI URL into host and port
-     * Supports formats: "host:port", "http://host:port", "https://host:port", or just "port"
-     */
-    private parseCliUrl;
-    /**
-     * Start the CLI server and establish connection
-     */
-    start(): Promise<void>;
-    /**
-     * Stop the CLI server and close all sessions
-     * Returns array of errors encountered during cleanup (empty if all succeeded)
-     */
-    stop(): Promise<Error[]>;
-    /**
-     * Force stop the CLI server without graceful cleanup
-     * Use when normal stop() fails or takes too long
-     */
-    forceStop(): Promise<void>;
-    /**
-     * Create a new session
-     */
-    createSession(config?: SessionConfig): Promise<CopilotSession>;
-    /**
-     * Resume an existing session
-     */
-    resumeSession(sessionId: string, config?: ResumeSessionConfig): Promise<CopilotSession>;
-    /**
-     * Get connection state
-     */
-    getState(): ConnectionState;
-    /**
-     * Ping the server
-     */
-    ping(message?: string): Promise<{
-        message: string;
-        timestamp: number;
-    }>;
-    /**
-     * Get the ID of the most recently updated session
-     * @returns The session ID, or undefined if no sessions exist
-     */
-    getLastSessionId(): Promise<string | undefined>;
-    /**
-     * Delete a session and its data from disk
-     * @param sessionId The ID of the session to delete
-     */
-    deleteSession(sessionId: string): Promise<void>;
-    /**
-     * List all available sessions
-     * @returns Array of session metadata
-     */
-    listSessions(): Promise<SessionMetadata[]>;
-    /**
-     * Start the CLI server process
-     */
-    private startCLIServer;
-    /**
-     * Connect to the CLI server (via socket or stdio)
-     */
-    private connectToServer;
-    /**
-     * Connect via stdio pipes
-     */
-    private connectViaStdio;
-    /**
-     * Connect to the CLI server via TCP socket
-     */
-    private connectViaTcp;
-    private attachConnectionHandlers;
-    private handleSessionEventNotification;
-    private handleToolCallRequest;
-    private executeToolCall;
-    private handlePermissionRequest;
-    private normalizeToolResult;
-    private isToolResultObject;
-    private buildUnsupportedToolResult;
-    /**
-     * Attempt to reconnect to the server
-     */
-    private reconnect;
-}

package/dist/index.d.ts

@@ -1,9 +0,0 @@
-/**
- * Copilot SDK - TypeScript/Node.js Client
- *
- * JSON-RPC based SDK for programmatic control of GitHub Copilot CLI
- */
-export { CopilotClient } from "./client.js";
-export { CopilotSession } from "./session.js";
-export { defineTool } from "./types.js";
-export type { ConnectionState, CopilotClientOptions, MessageOptions, PermissionHandler, PermissionRequest, PermissionRequestResult, ResumeSessionConfig, SessionConfig, SessionEvent, SessionEventHandler, SessionMetadata, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageReplaceConfig, Tool, ToolHandler, ToolInvocation, ToolResultObject, ZodSchema, } from "./types.js";

package/dist/session.d.ts

@@ -1,42 +0,0 @@
-/**
- * Copilot Session - represents a single conversation session with the CLI
- */
-import type { MessageConnection } from "vscode-jsonrpc/node";
-import type { MessageOptions, PermissionHandler, PermissionRequestResult, SessionEvent, SessionEventHandler, Tool, ToolHandler } from "./types.js";
-export declare class CopilotSession {
-    readonly sessionId: string;
-    private connection;
-    private eventHandlers;
-    private toolHandlers;
-    private permissionHandler?;
-    constructor(sessionId: string, connection: MessageConnection);
-    /**
-     * Send a message to this session
-     */
-    send(options: MessageOptions): Promise<string>;
-    /**
-     * Subscribe to events from this session
-     * @returns Unsubscribe function
-     */
-    on(handler: SessionEventHandler): () => void;
-    /**
-     * Internal: dispatch an event to all handlers
-     */
-    _dispatchEvent(event: SessionEvent): void;
-    registerTools(tools?: Tool[]): void;
-    getToolHandler(name: string): ToolHandler | undefined;
-    registerPermissionHandler(handler?: PermissionHandler): void;
-    _handlePermissionRequest(request: unknown): Promise<PermissionRequestResult>;
-    /**
-     * Get all events/messages from this session
-     */
-    getMessages(): Promise<SessionEvent[]>;
-    /**
-     * Destroy this session and free resources
-     */
-    destroy(): Promise<void>;
-    /**
-     * Abort the currently processing message in this session
-     */
-    abort(): Promise<void>;
-}