@github/copilot-sdk 0.1.10-preview.0 → 0.1.10

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) {
@@ -217,16 +316,42 @@ class CopilotClient {
       availableTools: config.availableTools,
       excludedTools: config.excludedTools,
       provider: config.provider,
-      streaming: config.streaming
+      requestPermission: !!config.onPermissionRequest,
+      streaming: config.streaming,
+      mcpServers: config.mcpServers,
+      customAgents: config.customAgents
     });
     const sessionId = response.sessionId;
     const session = new CopilotSession(sessionId, this.connection);
     session.registerTools(config.tools);
+    if (config.onPermissionRequest) {
+      session.registerPermissionHandler(config.onPermissionRequest);
+    }
     this.sessions.set(sessionId, session);
     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) {
@@ -244,22 +369,47 @@ class CopilotClient {
         parameters: toJsonSchema(tool.parameters)
       })),
       provider: config.provider,
-      streaming: config.streaming
+      requestPermission: !!config.onPermissionRequest,
+      streaming: config.streaming,
+      mcpServers: config.mcpServers,
+      customAgents: config.customAgents
     });
     const resumedSessionId = response.sessionId;
     const session = new CopilotSession(resumedSessionId, this.connection);
     session.registerTools(config.tools);
+    if (config.onPermissionRequest) {
+      session.registerPermissionHandler(config.onPermissionRequest);
+    }
     this.sessions.set(resumedSessionId, session);
     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) {
@@ -269,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) {
@@ -280,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) {
@@ -297,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) {
@@ -333,8 +537,19 @@ class CopilotClient {
       const envWithoutNodeDebug = { ...this.options.env };
       delete envWithoutNodeDebug.NODE_DEBUG;
       const isJsFile = this.options.cliPath.endsWith(".js");
-      const command = isJsFile ? "node" : this.options.cliPath;
-      const spawnArgs = isJsFile ? [this.options.cliPath, ...args] : args;
+      const isAbsolutePath = this.options.cliPath.startsWith("/") || /^[a-zA-Z]:/.test(this.options.cliPath);
+      let command;
+      let spawnArgs;
+      if (isJsFile) {
+        command = "node";
+        spawnArgs = [this.options.cliPath, ...args];
+      } else if (process.platform === "win32" && !isAbsolutePath) {
+        command = "cmd";
+        spawnArgs = ["/c", `"${this.options.cliPath}"`, ...args];
+      } else {
+        command = this.options.cliPath;
+        spawnArgs = args;
+      }
       this.cliProcess = spawn(command, spawnArgs, {
         stdio: this.options.useStdio ? ["pipe", "pipe", "pipe"] : ["ignore", "pipe", "pipe"],
         cwd: this.options.cwd,
@@ -450,6 +665,10 @@ class CopilotClient {
       "tool.call",
       async (params) => await this.handleToolCallRequest(params)
     );
+    this.connection.onRequest(
+      "permission.request",
+      async (params) => await this.handlePermissionRequest(params)
+    );
     this.connection.onClose(() => {
       if (this.state === "connected" && this.options.autoRestart) {
         void this.reconnect();
@@ -504,6 +723,25 @@ class CopilotClient {
       };
     }
   }
+  async handlePermissionRequest(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._handlePermissionRequest(params.permissionRequest);
+      return { result };
+    } catch (_error) {
+      return {
+        result: {
+          kind: "denied-no-approval-rule-and-could-not-request-from-user"
+        }
+      };
+    }
+  }
   normalizeToolResult(result) {
     if (result === void 0 || result === null) {
       return {

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;
+}