@github/copilot-sdk 0.1.31 → 0.1.33-preview.0

package/dist/client.d.ts

@@ -1,6 +1,39 @@
 import { createServerRpc } from "./generated/rpc.js";
 import { CopilotSession } from "./session.js";
 import type { ConnectionState, CopilotClientOptions, GetAuthStatusResponse, GetStatusResponse, ModelInfo, ResumeSessionConfig, SessionConfig, SessionLifecycleEventType, SessionLifecycleHandler, SessionListFilter, SessionMetadata, TypedSessionLifecycleHandler } 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({ onPermissionRequest: approveAll, 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.disconnect();
+ * await client.stop();
+ * ```
+ */
 export declare class CopilotClient {
     private cliProcess;
     private connection;
@@ -13,12 +46,14 @@ export declare class CopilotClient {
     private options;
     private isExternalServer;
     private forceStopping;
+    private onListModels?;
     private modelsCache;
     private modelsCacheLock;
     private sessionLifecycleHandlers;
     private typedLifecycleHandlers;
     private _rpc;
     private processExitPromise;
+    private negotiatedProtocolVersion;
     /**
      * Typed server-scoped RPC methods.
      * @throws Error if the client is not connected
@@ -217,14 +252,18 @@ export declare class CopilotClient {
     /**
      * List available models with their metadata.
      *
+     * If an `onListModels` handler was provided in the client options,
+     * it is called instead of querying the CLI server.
+     *
      * Results are cached after the first successful call to avoid rate limiting.
      * The cache is cleared when the client disconnects.
      *
-     * @throws Error if not authenticated
+     * @throws Error if not connected (when no custom handler is set)
      */
     listModels(): Promise<ModelInfo[]>;
     /**
-     * Verify that the server's protocol version matches the SDK's expected version
+     * Verify that the server's protocol version is within the supported range
+     * and store the negotiated version.
      */
     private verifyProtocolVersion;
     /**
@@ -383,6 +422,18 @@ export declare class CopilotClient {
     private handleSessionLifecycleNotification;
     private handleUserInputRequest;
     private handleHooksInvoke;
+    /**
+     * Handles a v2-style tool.call RPC request from the server.
+     * Looks up the session and tool handler, executes it, and returns the result
+     * in the v2 response format.
+     */
+    private handleToolCallRequestV2;
+    /**
+     * Handles a v2-style permission.request RPC request from the server.
+     */
+    private handlePermissionRequestV2;
+    private normalizeToolResultV2;
+    private isToolResultObject;
     /**
      * Attempt to reconnect to the server
      */

package/dist/client.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { Socket } from "node:net";
 import { dirname, join } from "node:path";
@@ -10,7 +11,8 @@ import {
 } from "vscode-jsonrpc/node.js";
 import { createServerRpc } from "./generated/rpc.js";
 import { getSdkProtocolVersion } from "./sdkProtocolVersion.js";
-import { CopilotSession } from "./session.js";
+import { CopilotSession, NO_RESULT_PERMISSION_V2_ERROR } from "./session.js";
+const MIN_PROTOCOL_VERSION = 2;
 function isZodSchema(value) {
   return value != null && typeof value === "object" && "toJSONSchema" in value && typeof value.toJSONSchema === "function";
 }
@@ -45,6 +47,7 @@ class CopilotClient {
   options;
   isExternalServer = false;
   forceStopping = false;
+  onListModels;
   modelsCache = null;
   modelsCacheLock = Promise.resolve();
   sessionLifecycleHandlers = /* @__PURE__ */ new Set();
@@ -52,6 +55,7 @@ class CopilotClient {
   _rpc = null;
   processExitPromise = null;
   // Rejects when CLI process exits
+  negotiatedProtocolVersion = null;
   /**
    * Typed server-scoped RPC methods.
    * @throws Error if the client is not connected
@@ -109,8 +113,9 @@ class CopilotClient {
     if (options.isChildProcess) {
       this.isExternalServer = true;
     }
+    this.onListModels = options.onListModels;
     this.options = {
-      cliPath: options.cliPath || getBundledCliPath(),
+      cliPath: options.cliUrl ? void 0 : options.cliPath || getBundledCliPath(),
       cliArgs: options.cliArgs ?? [],
       cwd: options.cwd ?? process.cwd(),
       port: options.port || 0,
@@ -376,36 +381,8 @@ class CopilotClient {
         throw new Error("Client not connected. Call start() first.");
       }
     }
-    const response = await this.connection.sendRequest("session.create", {
-      model: config.model,
-      sessionId: config.sessionId,
-      clientName: config.clientName,
-      reasoningEffort: config.reasoningEffort,
-      tools: config.tools?.map((tool) => ({
-        name: tool.name,
-        description: tool.description,
-        parameters: toJsonSchema(tool.parameters),
-        overridesBuiltInTool: tool.overridesBuiltInTool
-      })),
-      systemMessage: config.systemMessage,
-      availableTools: config.availableTools,
-      excludedTools: config.excludedTools,
-      provider: config.provider,
-      requestPermission: true,
-      requestUserInput: !!config.onUserInputRequest,
-      hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
-      workingDirectory: config.workingDirectory,
-      streaming: config.streaming,
-      mcpServers: config.mcpServers,
-      envValueMode: "direct",
-      customAgents: config.customAgents,
-      configDir: config.configDir,
-      skillDirectories: config.skillDirectories,
-      disabledSkills: config.disabledSkills,
-      infiniteSessions: config.infiniteSessions
-    });
-    const { sessionId, workspacePath } = response;
-    const session = new CopilotSession(sessionId, this.connection, workspacePath);
+    const sessionId = config.sessionId ?? randomUUID();
+    const session = new CopilotSession(sessionId, this.connection);
     session.registerTools(config.tools);
     session.registerPermissionHandler(config.onPermissionRequest);
     if (config.onUserInputRequest) {
@@ -414,7 +391,46 @@ class CopilotClient {
     if (config.hooks) {
       session.registerHooks(config.hooks);
     }
+    if (config.onEvent) {
+      session.on(config.onEvent);
+    }
     this.sessions.set(sessionId, session);
+    try {
+      const response = await this.connection.sendRequest("session.create", {
+        model: config.model,
+        sessionId,
+        clientName: config.clientName,
+        reasoningEffort: config.reasoningEffort,
+        tools: config.tools?.map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          parameters: toJsonSchema(tool.parameters),
+          overridesBuiltInTool: tool.overridesBuiltInTool
+        })),
+        systemMessage: config.systemMessage,
+        availableTools: config.availableTools,
+        excludedTools: config.excludedTools,
+        provider: config.provider,
+        requestPermission: true,
+        requestUserInput: !!config.onUserInputRequest,
+        hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
+        workingDirectory: config.workingDirectory,
+        streaming: config.streaming,
+        mcpServers: config.mcpServers,
+        envValueMode: "direct",
+        customAgents: config.customAgents,
+        agent: config.agent,
+        configDir: config.configDir,
+        skillDirectories: config.skillDirectories,
+        disabledSkills: config.disabledSkills,
+        infiniteSessions: config.infiniteSessions
+      });
+      const { workspacePath } = response;
+      session["_workspacePath"] = workspacePath;
+    } catch (e) {
+      this.sessions.delete(sessionId);
+      throw e;
+    }
     return session;
   }
   /**
@@ -454,37 +470,7 @@ class CopilotClient {
         throw new Error("Client not connected. Call start() first.");
       }
     }
-    const response = await this.connection.sendRequest("session.resume", {
-      sessionId,
-      clientName: config.clientName,
-      model: config.model,
-      reasoningEffort: config.reasoningEffort,
-      systemMessage: config.systemMessage,
-      availableTools: config.availableTools,
-      excludedTools: config.excludedTools,
-      tools: config.tools?.map((tool) => ({
-        name: tool.name,
-        description: tool.description,
-        parameters: toJsonSchema(tool.parameters),
-        overridesBuiltInTool: tool.overridesBuiltInTool
-      })),
-      provider: config.provider,
-      requestPermission: true,
-      requestUserInput: !!config.onUserInputRequest,
-      hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
-      workingDirectory: config.workingDirectory,
-      configDir: config.configDir,
-      streaming: config.streaming,
-      mcpServers: config.mcpServers,
-      envValueMode: "direct",
-      customAgents: config.customAgents,
-      skillDirectories: config.skillDirectories,
-      disabledSkills: config.disabledSkills,
-      infiniteSessions: config.infiniteSessions,
-      disableResume: config.disableResume
-    });
-    const { sessionId: resumedSessionId, workspacePath } = response;
-    const session = new CopilotSession(resumedSessionId, this.connection, workspacePath);
+    const session = new CopilotSession(sessionId, this.connection);
     session.registerTools(config.tools);
     session.registerPermissionHandler(config.onPermissionRequest);
     if (config.onUserInputRequest) {
@@ -493,7 +479,47 @@ class CopilotClient {
     if (config.hooks) {
       session.registerHooks(config.hooks);
     }
-    this.sessions.set(resumedSessionId, session);
+    if (config.onEvent) {
+      session.on(config.onEvent);
+    }
+    this.sessions.set(sessionId, session);
+    try {
+      const response = await this.connection.sendRequest("session.resume", {
+        sessionId,
+        clientName: config.clientName,
+        model: config.model,
+        reasoningEffort: config.reasoningEffort,
+        systemMessage: config.systemMessage,
+        availableTools: config.availableTools,
+        excludedTools: config.excludedTools,
+        tools: config.tools?.map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          parameters: toJsonSchema(tool.parameters),
+          overridesBuiltInTool: tool.overridesBuiltInTool
+        })),
+        provider: config.provider,
+        requestPermission: true,
+        requestUserInput: !!config.onUserInputRequest,
+        hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
+        workingDirectory: config.workingDirectory,
+        configDir: config.configDir,
+        streaming: config.streaming,
+        mcpServers: config.mcpServers,
+        envValueMode: "direct",
+        customAgents: config.customAgents,
+        agent: config.agent,
+        skillDirectories: config.skillDirectories,
+        disabledSkills: config.disabledSkills,
+        infiniteSessions: config.infiniteSessions,
+        disableResume: config.disableResume
+      });
+      const { workspacePath } = response;
+      session["_workspacePath"] = workspacePath;
+    } catch (e) {
+      this.sessions.delete(sessionId);
+      throw e;
+    }
     return session;
   }
   /**
@@ -554,15 +580,15 @@ class CopilotClient {
   /**
    * List available models with their metadata.
    *
+   * If an `onListModels` handler was provided in the client options,
+   * it is called instead of querying the CLI server.
+   *
    * Results are cached after the first successful call to avoid rate limiting.
    * The cache is cleared when the client disconnects.
    *
-   * @throws Error if not authenticated
+   * @throws Error if not connected (when no custom handler is set)
    */
   async listModels() {
-    if (!this.connection) {
-      throw new Error("Client not connected");
-    }
     await this.modelsCacheLock;
     let resolveLock;
     this.modelsCacheLock = new Promise((resolve) => {
@@ -572,20 +598,29 @@ class CopilotClient {
       if (this.modelsCache !== null) {
         return [...this.modelsCache];
       }
-      const result = await this.connection.sendRequest("models.list", {});
-      const response = result;
-      const models = response.models;
-      this.modelsCache = models;
+      let models;
+      if (this.onListModels) {
+        models = await this.onListModels();
+      } else {
+        if (!this.connection) {
+          throw new Error("Client not connected");
+        }
+        const result = await this.connection.sendRequest("models.list", {});
+        const response = result;
+        models = response.models;
+      }
+      this.modelsCache = [...models];
       return [...models];
     } finally {
       resolveLock();
     }
   }
   /**
-   * Verify that the server's protocol version matches the SDK's expected version
+   * Verify that the server's protocol version is within the supported range
+   * and store the negotiated version.
    */
   async verifyProtocolVersion() {
-    const expectedVersion = getSdkProtocolVersion();
+    const maxVersion = getSdkProtocolVersion();
     let pingResult;
     if (this.processExitPromise) {
       pingResult = await Promise.race([this.ping(), this.processExitPromise]);
@@ -595,14 +630,15 @@ class CopilotClient {
     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.`
+        `SDK protocol version mismatch: SDK supports versions ${MIN_PROTOCOL_VERSION}-${maxVersion}, but server does not report a protocol version. Please update your server to ensure compatibility.`
       );
     }
-    if (serverVersion !== expectedVersion) {
+    if (serverVersion < MIN_PROTOCOL_VERSION || serverVersion > maxVersion) {
       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.`
+        `SDK protocol version mismatch: SDK supports versions ${MIN_PROTOCOL_VERSION}-${maxVersion}, but server reports version ${serverVersion}. Please update your SDK or server to ensure compatibility.`
       );
     }
+    this.negotiatedProtocolVersion = serverVersion;
   }
   /**
    * Gets the ID of the most recently updated session.
@@ -786,6 +822,11 @@ class CopilotClient {
       if (this.options.githubToken) {
         envWithoutNodeDebug.COPILOT_SDK_AUTH_TOKEN = this.options.githubToken;
       }
+      if (!this.options.cliPath) {
+        throw new Error(
+          "Path to Copilot CLI is required. Please provide it via the cliPath option, or use cliUrl to rely on a remote CLI."
+        );
+      }
       if (!existsSync(this.options.cliPath)) {
         throw new Error(
           `Copilot CLI not found at ${this.options.cliPath}. Ensure @github/copilot is installed.`
@@ -975,6 +1016,14 @@ stderr: ${stderrOutput}`
     this.connection.onNotification("session.lifecycle", (notification) => {
       this.handleSessionLifecycleNotification(notification);
     });
+    this.connection.onRequest(
+      "tool.call",
+      async (params) => await this.handleToolCallRequestV2(params)
+    );
+    this.connection.onRequest(
+      "permission.request",
+      async (params) => await this.handlePermissionRequestV2(params)
+    );
     this.connection.onRequest(
       "userInput.request",
       async (params) => await this.handleUserInputRequest(params)
@@ -1047,6 +1096,101 @@ stderr: ${stderrOutput}`
     const output = await session._handleHooksInvoke(params.hookType, params.input);
     return { output };
   }
+  // ========================================================================
+  // Protocol v2 backward-compatibility adapters
+  // ========================================================================
+  /**
+   * Handles a v2-style tool.call RPC request from the server.
+   * Looks up the session and tool handler, executes it, and returns the result
+   * in the v2 response format.
+   */
+  async handleToolCallRequestV2(params) {
+    if (!params || typeof params.sessionId !== "string" || typeof params.toolCallId !== "string" || typeof params.toolName !== "string") {
+      throw new Error("Invalid tool call payload");
+    }
+    const session = this.sessions.get(params.sessionId);
+    if (!session) {
+      throw new Error(`Unknown session ${params.sessionId}`);
+    }
+    const handler = session.getToolHandler(params.toolName);
+    if (!handler) {
+      return {
+        result: {
+          textResultForLlm: `Tool '${params.toolName}' is not supported by this client instance.`,
+          resultType: "failure",
+          error: `tool '${params.toolName}' not supported`,
+          toolTelemetry: {}
+        }
+      };
+    }
+    try {
+      const invocation = {
+        sessionId: params.sessionId,
+        toolCallId: params.toolCallId,
+        toolName: params.toolName,
+        arguments: params.arguments
+      };
+      const result = await handler(params.arguments, invocation);
+      return { result: this.normalizeToolResultV2(result) };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        result: {
+          textResultForLlm: "Invoking this tool produced an error. Detailed information is not available.",
+          resultType: "failure",
+          error: message,
+          toolTelemetry: {}
+        }
+      };
+    }
+  }
+  /**
+   * Handles a v2-style permission.request RPC request from the server.
+   */
+  async handlePermissionRequestV2(params) {
+    if (!params || typeof params.sessionId !== "string" || !params.permissionRequest) {
+      throw new Error("Invalid permission request payload");
+    }
+    const session = this.sessions.get(params.sessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${params.sessionId}`);
+    }
+    try {
+      const result = await session._handlePermissionRequestV2(params.permissionRequest);
+      return { result };
+    } catch (error) {
+      if (error instanceof Error && error.message === NO_RESULT_PERMISSION_V2_ERROR) {
+        throw error;
+      }
+      return {
+        result: {
+          kind: "denied-no-approval-rule-and-could-not-request-from-user"
+        }
+      };
+    }
+  }
+  normalizeToolResultV2(result) {
+    if (result === void 0 || result === null) {
+      return {
+        textResultForLlm: "Tool returned no result",
+        resultType: "failure",
+        error: "tool returned no result",
+        toolTelemetry: {}
+      };
+    }
+    if (this.isToolResultObject(result)) {
+      return result;
+    }
+    const textResult = typeof result === "string" ? result : JSON.stringify(result);
+    return {
+      textResultForLlm: textResult,
+      resultType: "success",
+      toolTelemetry: {}
+    };
+  }
+  isToolResultObject(value) {
+    return typeof value === "object" && value !== null && "textResultForLlm" in value && typeof value.textResultForLlm === "string" && "resultType" in value;
+  }
   /**
    * Attempt to reconnect to the server
    */

package/dist/extension.d.ts

@@ -1,2 +1,19 @@
-import { CopilotClient } from "./client.js";
-export declare const extension: CopilotClient;
+import type { CopilotSession } from "./session.js";
+import type { PermissionHandler, ResumeSessionConfig } from "./types.js";
+export type JoinSessionConfig = Omit<ResumeSessionConfig, "onPermissionRequest"> & {
+    onPermissionRequest?: PermissionHandler;
+};
+/**
+ * Joins the current foreground session.
+ *
+ * @param config - Configuration to add to the session
+ * @returns A promise that resolves with the joined session
+ *
+ * @example
+ * ```typescript
+ * import { joinSession } from "@github/copilot-sdk/extension";
+ *
+ * const session = await joinSession({ tools: [myTool] });
+ * ```
+ */
+export declare function joinSession(config?: JoinSessionConfig): Promise<CopilotSession>;

package/dist/extension.js

@@ -1,5 +1,21 @@
 import { CopilotClient } from "./client.js";
-const extension = new CopilotClient({ isChildProcess: true });
+const defaultJoinSessionPermissionHandler = () => ({
+  kind: "no-result"
+});
+async function joinSession(config = {}) {
+  const sessionId = process.env.SESSION_ID;
+  if (!sessionId) {
+    throw new Error(
+      "joinSession() is intended for extensions running as child processes of the Copilot CLI."
+    );
+  }
+  const client = new CopilotClient({ isChildProcess: true });
+  return client.resumeSession(sessionId, {
+    ...config,
+    onPermissionRequest: config.onPermissionRequest ?? defaultJoinSessionPermissionHandler,
+    disableResume: config.disableResume ?? true
+  });
+}
 export {
-  extension
+  joinSession
 };