@github/copilot-sdk 0.1.32 → 0.1.33-preview.1

package/README.md

@@ -82,7 +82,6 @@ new CopilotClient(options?: CopilotClientOptions)
 - `useStdio?: boolean` - Use stdio transport instead of TCP (default: true)
 - `logLevel?: string` - Log level (default: "info")
 - `autoStart?: boolean` - Auto-start server (default: true)
-- `autoRestart?: boolean` - Auto-restart on crash (default: true)
 - `githubToken?: string` - GitHub token for authentication. When provided, takes priority over other auth methods.
 - `useLoggedInUser?: boolean` - Whether to use logged-in user for authentication (default: true, but false when `githubToken` is provided). Cannot be used with `cliUrl`.
 
@@ -426,6 +425,19 @@ defineTool("edit_file", {
 })
 ```
 
+#### Skipping Permission Prompts
+
+Set `skipPermission: true` on a tool definition to allow it to execute without triggering a permission prompt:
+
+```ts
+defineTool("safe_lookup", {
+    description: "A read-only lookup that needs no confirmation",
+    parameters: z.object({ id: z.string() }),
+    skipPermission: true,
+    handler: async ({ id }) => { /* your logic */ },
+})
+```
+
 ### System Message Customization
 
 Control the system prompt using `systemMessage` in session config:

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,6 +46,7 @@ export declare class CopilotClient {
     private options;
     private isExternalServer;
     private forceStopping;
+    private onListModels?;
     private modelsCache;
     private modelsCacheLock;
     private sessionLifecycleHandlers;
@@ -218,10 +252,13 @@ 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[]>;
     /**
@@ -397,8 +434,4 @@ export declare class CopilotClient {
     private handlePermissionRequestV2;
     private normalizeToolResultV2;
     private isToolResultObject;
-    /**
-     * Attempt to reconnect to the server
-     */
-    private reconnect;
 }

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,7 @@ 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";
@@ -46,6 +47,7 @@ class CopilotClient {
   options;
   isExternalServer = false;
   forceStopping = false;
+  onListModels;
   modelsCache = null;
   modelsCacheLock = Promise.resolve();
   sessionLifecycleHandlers = /* @__PURE__ */ new Set();
@@ -111,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,
@@ -122,7 +125,7 @@ class CopilotClient {
       cliUrl: options.cliUrl,
       logLevel: options.logLevel || "debug",
       autoStart: options.autoStart ?? true,
-      autoRestart: options.autoRestart ?? true,
+      autoRestart: false,
       env: options.env ?? process.env,
       githubToken: options.githubToken,
       // Default useLoggedInUser to false when githubToken is provided, otherwise true
@@ -378,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) {
@@ -416,7 +391,47 @@ 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,
+          skipPermission: tool.skipPermission
+        })),
+        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;
   }
   /**
@@ -456,37 +471,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) {
@@ -495,7 +480,48 @@ 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,
+          skipPermission: tool.skipPermission
+        })),
+        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;
   }
   /**
@@ -556,15 +582,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) => {
@@ -574,10 +600,18 @@ 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();
@@ -790,6 +824,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.`
@@ -889,8 +928,6 @@ stderr: ${stderrOutput}`
           } else {
             reject(new Error(`CLI server exited with code ${code}`));
           }
-        } else if (this.options.autoRestart && this.state === "connected") {
-          void this.reconnect();
         }
       });
       setTimeout(() => {
@@ -996,11 +1033,10 @@ stderr: ${stderrOutput}`
       async (params) => await this.handleHooksInvoke(params)
     );
     this.connection.onClose(() => {
-      if (this.state === "connected" && this.options.autoRestart) {
-        void this.reconnect();
-      }
+      this.state = "disconnected";
     });
     this.connection.onError((_error) => {
+      this.state = "disconnected";
     });
   }
   handleSessionEventNotification(notification) {
@@ -1121,7 +1157,10 @@ stderr: ${stderrOutput}`
     try {
       const result = await session._handlePermissionRequestV2(params.permissionRequest);
       return { result };
-    } catch (_error) {
+    } 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"
@@ -1151,17 +1190,6 @@ stderr: ${stderrOutput}`
   isToolResultObject(value) {
     return typeof value === "object" && value !== null && "textResultForLlm" in value && typeof value.textResultForLlm === "string" && "resultType" in value;
   }
-  /**
-   * Attempt to reconnect to the server
-   */
-  async reconnect() {
-    this.state = "disconnected";
-    try {
-      await this.stop();
-      await this.start();
-    } catch (_error) {
-    }
-  }
 }
 export {
   CopilotClient

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

package/dist/generated/rpc.d.ts

@@ -40,16 +40,34 @@ export interface ModelsListResult {
          * Model capabilities and limits
          */
         capabilities: {
+            /**
+             * Feature flags indicating what the model supports
+             */
             supports: {
+                /**
+                 * Whether this model supports vision/image input
+                 */
                 vision?: boolean;
                 /**
                  * Whether this model supports reasoning effort configuration
                  */
                 reasoningEffort?: boolean;
             };
+            /**
+             * Token limits for prompts, outputs, and context window
+             */
             limits: {
+                /**
+                 * Maximum number of prompt/input tokens
+                 */
                 max_prompt_tokens?: number;
+                /**
+                 * Maximum number of output/completion tokens
+                 */
                 max_output_tokens?: number;
+                /**
+                 * Maximum total context window size in tokens
+                 */
                 max_context_window_tokens: number;
             };
         };
@@ -57,13 +75,22 @@ export interface ModelsListResult {
          * Policy state (if applicable)
          */
         policy?: {
+            /**
+             * Current policy state for this model
+             */
             state: string;
+            /**
+             * Usage terms or conditions for this model
+             */
             terms: string;
         };
         /**
          * Billing information
          */
         billing?: {
+            /**
+             * Billing cost multiplier relative to the base rate
+             */
             multiplier: number;
         };
         /**
@@ -145,6 +172,9 @@ export interface AccountGetQuotaResult {
     };
 }
 export interface SessionModelGetCurrentResult {
+    /**
+     * Currently active model identifier
+     */
     modelId?: string;
 }
 export interface SessionModelGetCurrentParams {
@@ -154,6 +184,9 @@ export interface SessionModelGetCurrentParams {
     sessionId: string;
 }
 export interface SessionModelSwitchToResult {
+    /**
+     * Currently active model identifier after the switch
+     */
     modelId?: string;
 }
 export interface SessionModelSwitchToParams {
@@ -161,7 +194,14 @@ export interface SessionModelSwitchToParams {
      * Target session identifier
      */
     sessionId: string;
+    /**
+     * Model identifier to switch to
+     */
     modelId: string;
+    /**
+     * Reasoning effort level to use for the model
+     */
+    reasoningEffort?: string;
 }
 export interface SessionModeGetResult {
     /**
@@ -399,6 +439,9 @@ export interface SessionCompactionCompactParams {
     sessionId: string;
 }
 export interface SessionToolsHandlePendingToolCallResult {
+    /**
+     * Whether the tool call result was handled successfully
+     */
     success: boolean;
 }
 export interface SessionToolsHandlePendingToolCallParams {
@@ -418,6 +461,9 @@ export interface SessionToolsHandlePendingToolCallParams {
     error?: string;
 }
 export interface SessionPermissionsHandlePendingPermissionRequestResult {
+    /**
+     * Whether the permission request was handled successfully
+     */
     success: boolean;
 }
 export interface SessionPermissionsHandlePendingPermissionRequestParams {
@@ -442,6 +488,74 @@ 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;
+}
+export interface SessionShellExecResult {
+    /**
+     * Unique identifier for tracking streamed output
+     */
+    processId: string;
+}
+export interface SessionShellExecParams {
+    /**
+     * Target session identifier
+     */
+    sessionId: string;
+    /**
+     * Shell command to execute
+     */
+    command: string;
+    /**
+     * Working directory (defaults to session working directory)
+     */
+    cwd?: string;
+    /**
+     * Timeout in milliseconds (default: 30000)
+     */
+    timeout?: number;
+}
+export interface SessionShellKillResult {
+    /**
+     * Whether the signal was sent successfully
+     */
+    killed: boolean;
+}
+export interface SessionShellKillParams {
+    /**
+     * Target session identifier
+     */
+    sessionId: string;
+    /**
+     * Process identifier returned by shell.exec
+     */
+    processId: string;
+    /**
+     * Signal to send (default: SIGTERM)
+     */
+    signal?: "SIGTERM" | "SIGKILL" | "SIGINT";
+}
 /** Create typed server-scoped RPC methods (no session required). */
 export declare function createServerRpc(connection: MessageConnection): {
     ping: (params: PingParams) => Promise<PingResult>;
@@ -493,4 +607,9 @@ export declare function createSessionRpc(connection: MessageConnection, sessionI
     permissions: {
         handlePendingPermissionRequest: (params: Omit<SessionPermissionsHandlePendingPermissionRequestParams, "sessionId">) => Promise<SessionPermissionsHandlePendingPermissionRequestResult>;
     };
+    log: (params: Omit<SessionLogParams, "sessionId">) => Promise<SessionLogResult>;
+    shell: {
+        exec: (params: Omit<SessionShellExecParams, "sessionId">) => Promise<SessionShellExecResult>;
+        kill: (params: Omit<SessionShellKillParams, "sessionId">) => Promise<SessionShellKillResult>;
+    };
 };

package/dist/generated/rpc.js

@@ -49,6 +49,11 @@ function createSessionRpc(connection, sessionId) {
     },
     permissions: {
       handlePendingPermissionRequest: async (params) => connection.sendRequest("session.permissions.handlePendingPermissionRequest", { sessionId, ...params })
+    },
+    log: async (params) => connection.sendRequest("session.log", { sessionId, ...params }),
+    shell: {
+      exec: async (params) => connection.sendRequest("session.shell.exec", { sessionId, ...params }),
+      kill: async (params) => connection.sendRequest("session.shell.kill", { sessionId, ...params })
     }
   };
 }