@github/copilot-sdk 0.1.31 → 0.1.33-unstable.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

@@ -11,6 +11,7 @@ import {
 import { createServerRpc } from "./generated/rpc.js";
 import { getSdkProtocolVersion } from "./sdkProtocolVersion.js";
 import { CopilotSession } 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 +46,7 @@ class CopilotClient {
   options;
   isExternalServer = false;
   forceStopping = false;
+  onListModels;
   modelsCache = null;
   modelsCacheLock = Promise.resolve();
   sessionLifecycleHandlers = /* @__PURE__ */ new Set();
@@ -52,6 +54,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,6 +112,7 @@ class CopilotClient {
     if (options.isChildProcess) {
       this.isExternalServer = true;
     }
+    this.onListModels = options.onListModels;
     this.options = {
       cliPath: options.cliPath || getBundledCliPath(),
       cliArgs: options.cliArgs ?? [],
@@ -399,6 +403,7 @@ class CopilotClient {
       mcpServers: config.mcpServers,
       envValueMode: "direct",
       customAgents: config.customAgents,
+      agent: config.agent,
       configDir: config.configDir,
       skillDirectories: config.skillDirectories,
       disabledSkills: config.disabledSkills,
@@ -478,6 +483,7 @@ class CopilotClient {
       mcpServers: config.mcpServers,
       envValueMode: "direct",
       customAgents: config.customAgents,
+      agent: config.agent,
       skillDirectories: config.skillDirectories,
       disabledSkills: config.disabledSkills,
       infiniteSessions: config.infiniteSessions,
@@ -554,15 +560,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 +578,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 +610,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.
@@ -975,6 +991,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 +1071,98 @@ 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) {
+      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,20 @@
-import { CopilotClient } from "./client.js";
-export declare const extension: CopilotClient;
+import type { CopilotSession } from "./session.js";
+import type { ResumeSessionConfig } from "./types.js";
+/**
+ * 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 { approveAll } from "@github/copilot-sdk";
+ * import { joinSession } from "@github/copilot-sdk/extension";
+ *
+ * const session = await joinSession({
+ *   onPermissionRequest: approveAll,
+ *   tools: [myTool],
+ * });
+ * ```
+ */
+export declare function joinSession(config: ResumeSessionConfig): Promise<CopilotSession>;

package/dist/extension.js

@@ -1,5 +1,17 @@
 import { CopilotClient } from "./client.js";
-const extension = new CopilotClient({ isChildProcess: true });
+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,
+    disableResume: config.disableResume ?? true
+  });
+}
 export {
-  extension
+  joinSession
 };

package/dist/generated/rpc.d.ts

@@ -162,6 +162,7 @@ export interface SessionModelSwitchToParams {
      */
     sessionId: string;
     modelId: string;
+    reasoningEffort?: "low" | "medium" | "high" | "xhigh";
 }
 export interface SessionModeGetResult {
     /**
@@ -442,6 +443,30 @@ export interface SessionPermissionsHandlePendingPermissionRequestParams {
         message: string;
     };
 }
+export interface SessionLogResult {
+    /**
+     * The unique identifier of the emitted session event
+     */
+    eventId: string;
+}
+export interface SessionLogParams {
+    /**
+     * Target session identifier
+     */
+    sessionId: string;
+    /**
+     * Human-readable message
+     */
+    message: string;
+    /**
+     * Log severity level. Determines how the message is displayed in the timeline. Defaults to "info".
+     */
+    level?: "info" | "warning" | "error";
+    /**
+     * When true, the message is transient and not persisted to the session event log on disk
+     */
+    ephemeral?: boolean;
+}
 /** Create typed server-scoped RPC methods (no session required). */
 export declare function createServerRpc(connection: MessageConnection): {
     ping: (params: PingParams) => Promise<PingResult>;
@@ -493,4 +518,5 @@ export declare function createSessionRpc(connection: MessageConnection, sessionI
     permissions: {
         handlePendingPermissionRequest: (params: Omit<SessionPermissionsHandlePendingPermissionRequestParams, "sessionId">) => Promise<SessionPermissionsHandlePendingPermissionRequestResult>;
     };
+    log: (params: Omit<SessionLogParams, "sessionId">) => Promise<SessionLogResult>;
 };

package/dist/generated/rpc.js

@@ -49,7 +49,8 @@ function createSessionRpc(connection, sessionId) {
     },
     permissions: {
       handlePendingPermissionRequest: async (params) => connection.sendRequest("session.permissions.handlePendingPermissionRequest", { sessionId, ...params })
-    }
+    },
+    log: async (params) => connection.sendRequest("session.log", { sessionId, ...params })
   };
 }
 export {

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

@@ -66,6 +66,7 @@ export type SessionEvent = {
              */
             branch?: string;
         };
+        alreadyInUse?: boolean;
     };
 } | {
     /**
@@ -115,6 +116,7 @@ export type SessionEvent = {
              */
             branch?: string;
         };
+        alreadyInUse?: boolean;
     };
 } | {
     /**
@@ -2090,6 +2092,80 @@ export type SessionEvent = {
             };
         };
     };
+} | {
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * When true, the event is transient and not persisted to the session event log on disk
+     */
+    ephemeral?: boolean;
+    type: "system.notification";
+    data: {
+        /**
+         * The notification text, typically wrapped in <system_notification> XML tags
+         */
+        content: string;
+        /**
+         * Structured metadata identifying what triggered this notification
+         */
+        kind: {
+            type: "agent_completed";
+            /**
+             * Unique identifier of the background agent
+             */
+            agentId: string;
+            /**
+             * Type of the agent (e.g., explore, task, general-purpose)
+             */
+            agentType: string;
+            /**
+             * Whether the agent completed successfully or failed
+             */
+            status: "completed" | "failed";
+            /**
+             * Human-readable description of the agent task
+             */
+            description?: string;
+            /**
+             * The full prompt given to the background agent
+             */
+            prompt?: string;
+        } | {
+            type: "shell_completed";
+            /**
+             * Unique identifier of the shell session
+             */
+            shellId: string;
+            /**
+             * Exit code of the shell command, if available
+             */
+            exitCode?: number;
+            /**
+             * Human-readable description of the command
+             */
+            description?: string;
+        } | {
+            type: "shell_detached_completed";
+            /**
+             * Unique identifier of the detached shell session
+             */
+            shellId: string;
+            /**
+             * Human-readable description of the command
+             */
+            description?: string;
+        };
+    };
 } | {
     /**
      * Unique event identifier (UUID v4), generated when the event is emitted

package/dist/session.d.ts

@@ -4,7 +4,7 @@
  */
 import type { MessageConnection } from "vscode-jsonrpc/node";
 import { createSessionRpc } from "./generated/rpc.js";
-import type { MessageOptions, PermissionHandler, SessionEvent, SessionEventHandler, SessionEventType, SessionHooks, Tool, ToolHandler, TypedSessionEventHandler, UserInputHandler, UserInputResponse } from "./types.js";
+import type { MessageOptions, PermissionHandler, PermissionRequestResult, SessionEvent, SessionEventHandler, SessionEventType, SessionHooks, Tool, ToolHandler, TypedSessionEventHandler, UserInputHandler, UserInputResponse } from "./types.js";
 /** Assistant message event - the final response from the assistant. */
 export type AssistantMessageEvent = Extract<SessionEvent, {
     type: "assistant.message";
@@ -226,6 +226,15 @@ export declare class CopilotSession {
      * @internal This method is typically called internally when creating a session.
      */
     registerHooks(hooks?: SessionHooks): void;
+    /**
+     * Handles a permission request in the v2 protocol format (synchronous RPC).
+     * Used as a back-compat adapter when connected to a v2 server.
+     *
+     * @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.
+     */
+    _handlePermissionRequestV2(request: unknown): Promise<PermissionRequestResult>;
     /**
      * Handles a user input request from the Copilot CLI.
      *
@@ -330,4 +339,24 @@ export declare class CopilotSession {
      * ```
      */
     setModel(model: string): Promise<void>;
+    /**
+     * Log a message to the session timeline.
+     * The message appears in the session event stream and is visible to SDK consumers
+     * and (for non-ephemeral messages) persisted to the session event log on disk.
+     *
+     * @param message - Human-readable message text
+     * @param options - Optional log level and ephemeral flag
+     *
+     * @example
+     * ```typescript
+     * await session.log("Processing started");
+     * await session.log("Disk usage high", { level: "warning" });
+     * await session.log("Connection failed", { level: "error" });
+     * await session.log("Debug info", { ephemeral: true });
+     * ```
+     */
+    log(message: string, options?: {
+        level?: "info" | "warning" | "error";
+        ephemeral?: boolean;
+    }): Promise<void>;
 }

package/dist/session.js

@@ -319,6 +319,27 @@ class CopilotSession {
   registerHooks(hooks) {
     this.hooks = hooks;
   }
+  /**
+   * Handles a permission request in the v2 protocol format (synchronous RPC).
+   * Used as a back-compat adapter when connected to a v2 server.
+   *
+   * @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 _handlePermissionRequestV2(request) {
+    if (!this.permissionHandler) {
+      return { kind: "denied-no-approval-rule-and-could-not-request-from-user" };
+    }
+    try {
+      const result = await this.permissionHandler(request, {
+        sessionId: this.sessionId
+      });
+      return result;
+    } catch (_error) {
+      return { kind: "denied-no-approval-rule-and-could-not-request-from-user" };
+    }
+  }
   /**
    * Handles a user input request from the Copilot CLI.
    *
@@ -480,6 +501,25 @@ class CopilotSession {
   async setModel(model) {
     await this.rpc.model.switchTo({ modelId: model });
   }
+  /**
+   * Log a message to the session timeline.
+   * The message appears in the session event stream and is visible to SDK consumers
+   * and (for non-ephemeral messages) persisted to the session event log on disk.
+   *
+   * @param message - Human-readable message text
+   * @param options - Optional log level and ephemeral flag
+   *
+   * @example
+   * ```typescript
+   * await session.log("Processing started");
+   * await session.log("Disk usage high", { level: "warning" });
+   * await session.log("Connection failed", { level: "error" });
+   * await session.log("Debug info", { ephemeral: true });
+   * ```
+   */
+  async log(message, options) {
+    await this.rpc.log({ message, ...options });
+  }
 }
 export {
   CopilotSession

package/dist/types.d.ts

@@ -77,6 +77,13 @@ export interface CopilotClientOptions {
      * @default true (but defaults to false when githubToken is provided)
      */
     useLoggedInUser?: boolean;
+    /**
+     * Custom handler for listing available models.
+     * When provided, client.listModels() calls this handler instead of
+     * querying the CLI server. Useful in BYOK mode to return models
+     * available from your custom provider.
+     */
+    onListModels?: () => Promise<ModelInfo[]> | ModelInfo[];
 }
 /**
  * Configuration for creating a session
@@ -586,6 +593,12 @@ export interface SessionConfig {
      * Custom agent configurations for the session.
      */
     customAgents?: CustomAgentConfig[];
+    /**
+     * Name of the custom agent to activate when the session starts.
+     * Must match the `name` of one of the agents in `customAgents`.
+     * Equivalent to calling `session.rpc.agent.select({ name })` after creation.
+     */
+    agent?: string;
     /**
      * Directories to load skills from.
      */
@@ -604,7 +617,7 @@ export interface SessionConfig {
 /**
  * Configuration for resuming a session
  */
-export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "tools" | "systemMessage" | "availableTools" | "excludedTools" | "provider" | "streaming" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "hooks" | "workingDirectory" | "configDir" | "mcpServers" | "customAgents" | "skillDirectories" | "disabledSkills" | "infiniteSessions"> & {
+export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "tools" | "systemMessage" | "availableTools" | "excludedTools" | "provider" | "streaming" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "hooks" | "workingDirectory" | "configDir" | "mcpServers" | "customAgents" | "agent" | "skillDirectories" | "disabledSkills" | "infiniteSessions"> & {
     /**
      * When true, skips emitting the session.resume event.
      * Useful for reconnecting to a session without triggering resume-related side effects.