@github/copilot-sdk 0.1.30 → 0.1.31

package/dist/sdkProtocolVersion.d.ts

@@ -2,7 +2,7 @@
  * The SDK protocol version.
  * This must match the version expected by the copilot-agent-runtime server.
  */
-export declare const SDK_PROTOCOL_VERSION = 2;
+export declare const SDK_PROTOCOL_VERSION = 3;
 /**
  * Gets the SDK protocol version.
  * @returns The protocol version number

package/dist/sdkProtocolVersion.js

@@ -1,4 +1,4 @@
-const SDK_PROTOCOL_VERSION = 2;
+const SDK_PROTOCOL_VERSION = 3;
 function getSdkProtocolVersion() {
   return SDK_PROTOCOL_VERSION;
 }

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, PermissionRequestResult, SessionEvent, SessionEventHandler, SessionEventType, SessionHooks, Tool, ToolHandler, TypedSessionEventHandler, UserInputHandler, UserInputResponse } from "./types.js";
+import type { MessageOptions, PermissionHandler, 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";
@@ -31,7 +31,7 @@ export type AssistantMessageEvent = Extract<SessionEvent, {
  * await session.sendAndWait({ prompt: "Hello, world!" });
  *
  * // Clean up
- * await session.destroy();
+ * await session.disconnect();
  * ```
  */
 export declare class CopilotSession {
@@ -72,7 +72,7 @@ export declare class CopilotSession {
      *
      * @param options - The message options including the prompt and optional attachments
      * @returns A promise that resolves with the message ID of the response
-     * @throws Error if the session has been destroyed or the connection fails
+     * @throws Error if the session has been disconnected or the connection fails
      *
      * @example
      * ```typescript
@@ -97,7 +97,7 @@ export declare class CopilotSession {
      * @returns A promise that resolves with the final assistant message when the session becomes idle,
      *          or undefined if no assistant message was received
      * @throws Error if the timeout is reached before the session becomes idle
-     * @throws Error if the session has been destroyed or the connection fails
+     * @throws Error if the session has been disconnected or the connection fails
      *
      * @example
      * ```typescript
@@ -155,11 +155,29 @@ export declare class CopilotSession {
     on(handler: SessionEventHandler): () => void;
     /**
      * Dispatches an event to all registered handlers.
+     * Also handles broadcast request events internally (external tool calls, permissions).
      *
      * @param event - The session event to dispatch
      * @internal This method is for internal use by the SDK.
      */
     _dispatchEvent(event: SessionEvent): void;
+    /**
+     * Handles broadcast request events by executing local handlers and responding via RPC.
+     * Handlers are dispatched as fire-and-forget — rejections propagate as unhandled promise
+     * rejections, consistent with standard EventEmitter / event handler semantics.
+     * @internal
+     */
+    private _handleBroadcastEvent;
+    /**
+     * Executes a tool handler and sends the result back via RPC.
+     * @internal
+     */
+    private _executeToolAndRespond;
+    /**
+     * Executes a permission handler and sends the result back via RPC.
+     * @internal
+     */
+    private _executePermissionAndRespond;
     /**
      * Registers custom tool handlers for this session.
      *
@@ -208,14 +226,6 @@ export declare class CopilotSession {
      * @internal This method is typically called internally when creating a session.
      */
     registerHooks(hooks?: SessionHooks): void;
-    /**
-     * Handles a permission request from the Copilot CLI.
-     *
-     * @param request - The permission request data from the CLI
-     * @returns A promise that resolves with the permission decision
-     * @internal This method is for internal use by the SDK.
-     */
-    _handlePermissionRequest(request: unknown): Promise<PermissionRequestResult>;
     /**
      * Handles a user input request from the Copilot CLI.
      *
@@ -240,7 +250,7 @@ export declare class CopilotSession {
      * assistant responses, tool executions, and other session events.
      *
      * @returns A promise that resolves with an array of all session events
-     * @throws Error if the session has been destroyed or the connection fails
+     * @throws Error if the session has been disconnected or the connection fails
      *
      * @example
      * ```typescript
@@ -254,22 +264,39 @@ export declare class CopilotSession {
      */
     getMessages(): Promise<SessionEvent[]>;
     /**
-     * Destroys this session and releases all associated resources.
+     * Disconnects this session and releases all in-memory resources (event handlers,
+     * tool handlers, permission handlers).
      *
-     * After calling this method, the session can no longer be used. All event
-     * handlers and tool handlers are cleared. To continue the conversation,
-     * use {@link CopilotClient.resumeSession} with the session ID.
+     * Session state on disk (conversation history, planning state, artifacts) is
+     * preserved, so the conversation can be resumed later by calling
+     * {@link CopilotClient.resumeSession} with the session ID. To permanently
+     * remove all session data including files on disk, use
+     * {@link CopilotClient.deleteSession} instead.
      *
-     * @returns A promise that resolves when the session is destroyed
+     * After calling this method, the session object can no longer be used.
+     *
+     * @returns A promise that resolves when the session is disconnected
      * @throws Error if the connection fails
      *
      * @example
      * ```typescript
-     * // Clean up when done
-     * await session.destroy();
+     * // Clean up when done — session can still be resumed later
+     * await session.disconnect();
      * ```
      */
+    disconnect(): Promise<void>;
+    /**
+     * @deprecated Use {@link disconnect} instead. This method will be removed in a future release.
+     *
+     * Disconnects this session and releases all in-memory resources.
+     * Session data on disk is preserved for later resumption.
+     *
+     * @returns A promise that resolves when the session is disconnected
+     * @throws Error if the connection fails
+     */
     destroy(): Promise<void>;
+    /** Enables `await using session = ...` syntax for automatic cleanup. */
+    [Symbol.asyncDispose](): Promise<void>;
     /**
      * Aborts the currently processing message in this session.
      *
@@ -277,7 +304,7 @@ export declare class CopilotSession {
      * and can continue to be used for new messages.
      *
      * @returns A promise that resolves when the abort request is acknowledged
-     * @throws Error if the session has been destroyed or the connection fails
+     * @throws Error if the session has been disconnected or the connection fails
      *
      * @example
      * ```typescript

package/dist/session.js

@@ -1,3 +1,4 @@
+import { ConnectionError, ResponseError } from "vscode-jsonrpc/node";
 import { createSessionRpc } from "./generated/rpc.js";
 class CopilotSession {
   /**
@@ -45,7 +46,7 @@ class CopilotSession {
    *
    * @param options - The message options including the prompt and optional attachments
    * @returns A promise that resolves with the message ID of the response
-   * @throws Error if the session has been destroyed or the connection fails
+   * @throws Error if the session has been disconnected or the connection fails
    *
    * @example
    * ```typescript
@@ -78,7 +79,7 @@ class CopilotSession {
    * @returns A promise that resolves with the final assistant message when the session becomes idle,
    *          or undefined if no assistant message was received
    * @throws Error if the timeout is reached before the session becomes idle
-   * @throws Error if the session has been destroyed or the connection fails
+   * @throws Error if the session has been disconnected or the connection fails
    *
    * @example
    * ```typescript
@@ -152,11 +153,13 @@ class CopilotSession {
   }
   /**
    * Dispatches an event to all registered handlers.
+   * Also handles broadcast request events internally (external tool calls, permissions).
    *
    * @param event - The session event to dispatch
    * @internal This method is for internal use by the SDK.
    */
   _dispatchEvent(event) {
+    this._handleBroadcastEvent(event);
     const typedHandlers = this.typedEventHandlers.get(event.type);
     if (typedHandlers) {
       for (const handler of typedHandlers) {
@@ -173,6 +176,85 @@ class CopilotSession {
       }
     }
   }
+  /**
+   * Handles broadcast request events by executing local handlers and responding via RPC.
+   * Handlers are dispatched as fire-and-forget — rejections propagate as unhandled promise
+   * rejections, consistent with standard EventEmitter / event handler semantics.
+   * @internal
+   */
+  _handleBroadcastEvent(event) {
+    if (event.type === "external_tool.requested") {
+      const { requestId, toolName } = event.data;
+      const args = event.data.arguments;
+      const toolCallId = event.data.toolCallId;
+      const handler = this.toolHandlers.get(toolName);
+      if (handler) {
+        void this._executeToolAndRespond(requestId, toolName, toolCallId, args, handler);
+      }
+    } else if (event.type === "permission.requested") {
+      const { requestId, permissionRequest } = event.data;
+      if (this.permissionHandler) {
+        void this._executePermissionAndRespond(requestId, permissionRequest);
+      }
+    }
+  }
+  /**
+   * Executes a tool handler and sends the result back via RPC.
+   * @internal
+   */
+  async _executeToolAndRespond(requestId, toolName, toolCallId, args, handler) {
+    try {
+      const rawResult = await handler(args, {
+        sessionId: this.sessionId,
+        toolCallId,
+        toolName,
+        arguments: args
+      });
+      let result;
+      if (rawResult == null) {
+        result = "";
+      } else if (typeof rawResult === "string") {
+        result = rawResult;
+      } else {
+        result = JSON.stringify(rawResult);
+      }
+      await this.rpc.tools.handlePendingToolCall({ requestId, result });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      try {
+        await this.rpc.tools.handlePendingToolCall({ requestId, error: message });
+      } catch (rpcError) {
+        if (!(rpcError instanceof ConnectionError || rpcError instanceof ResponseError)) {
+          throw rpcError;
+        }
+      }
+    }
+  }
+  /**
+   * Executes a permission handler and sends the result back via RPC.
+   * @internal
+   */
+  async _executePermissionAndRespond(requestId, permissionRequest) {
+    try {
+      const result = await this.permissionHandler(permissionRequest, {
+        sessionId: this.sessionId
+      });
+      await this.rpc.permissions.handlePendingPermissionRequest({ requestId, result });
+    } catch (_error) {
+      try {
+        await this.rpc.permissions.handlePendingPermissionRequest({
+          requestId,
+          result: {
+            kind: "denied-no-approval-rule-and-could-not-request-from-user"
+          }
+        });
+      } catch (rpcError) {
+        if (!(rpcError instanceof ConnectionError || rpcError instanceof ResponseError)) {
+          throw rpcError;
+        }
+      }
+    }
+  }
   /**
    * Registers custom tool handlers for this session.
    *
@@ -237,26 +319,6 @@ class CopilotSession {
   registerHooks(hooks) {
     this.hooks = hooks;
   }
-  /**
-   * Handles a permission request from the Copilot CLI.
-   *
-   * @param request - The permission request data from the CLI
-   * @returns A promise that resolves with the permission decision
-   * @internal This method is for internal use by the SDK.
-   */
-  async _handlePermissionRequest(request) {
-    if (!this.permissionHandler) {
-      return { kind: "denied-no-approval-rule-and-could-not-request-from-user" };
-    }
-    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.
    *
@@ -315,7 +377,7 @@ class CopilotSession {
    * assistant responses, tool executions, and other session events.
    *
    * @returns A promise that resolves with an array of all session events
-   * @throws Error if the session has been destroyed or the connection fails
+   * @throws Error if the session has been disconnected or the connection fails
    *
    * @example
    * ```typescript
@@ -334,22 +396,27 @@ class CopilotSession {
     return response.events;
   }
   /**
-   * Destroys this session and releases all associated resources.
+   * Disconnects this session and releases all in-memory resources (event handlers,
+   * tool handlers, permission handlers).
+   *
+   * Session state on disk (conversation history, planning state, artifacts) is
+   * preserved, so the conversation can be resumed later by calling
+   * {@link CopilotClient.resumeSession} with the session ID. To permanently
+   * remove all session data including files on disk, use
+   * {@link CopilotClient.deleteSession} instead.
    *
-   * After calling this method, the session can no longer be used. All event
-   * handlers and tool handlers are cleared. To continue the conversation,
-   * use {@link CopilotClient.resumeSession} with the session ID.
+   * After calling this method, the session object can no longer be used.
    *
-   * @returns A promise that resolves when the session is destroyed
+   * @returns A promise that resolves when the session is disconnected
    * @throws Error if the connection fails
    *
    * @example
    * ```typescript
-   * // Clean up when done
-   * await session.destroy();
+   * // Clean up when done — session can still be resumed later
+   * await session.disconnect();
    * ```
    */
-  async destroy() {
+  async disconnect() {
     await this.connection.sendRequest("session.destroy", {
       sessionId: this.sessionId
     });
@@ -358,6 +425,22 @@ class CopilotSession {
     this.toolHandlers.clear();
     this.permissionHandler = void 0;
   }
+  /**
+   * @deprecated Use {@link disconnect} instead. This method will be removed in a future release.
+   *
+   * Disconnects this session and releases all in-memory resources.
+   * Session data on disk is preserved for later resumption.
+   *
+   * @returns A promise that resolves when the session is disconnected
+   * @throws Error if the connection fails
+   */
+  async destroy() {
+    return this.disconnect();
+  }
+  /** Enables `await using session = ...` syntax for automatic cleanup. */
+  async [Symbol.asyncDispose]() {
+    return this.disconnect();
+  }
   /**
    * Aborts the currently processing message in this session.
    *
@@ -365,7 +448,7 @@ class CopilotSession {
    * and can continue to be used for new messages.
    *
    * @returns A promise that resolves when the abort request is acknowledged
-   * @throws Error if the session has been destroyed or the connection fails
+   * @throws Error if the session has been disconnected or the connection fails
    *
    * @example
    * ```typescript

package/dist/types.d.ts

@@ -32,6 +32,12 @@ export interface CopilotClientOptions {
      * @default true
      */
     useStdio?: boolean;
+    /**
+     * When true, indicates the SDK is running as a child process of the Copilot CLI server, and should
+     * use its own stdio for communicating with the existing parent process. Can only be used in combination
+     * with useStdio: true.
+     */
+    isChildProcess?: boolean;
     /**
      * URL of an existing Copilot CLI server to connect to over TCP
      * When provided, the client will not spawn a CLI process
@@ -179,10 +185,8 @@ export interface PermissionRequest {
     toolCallId?: string;
     [key: string]: unknown;
 }
-export interface PermissionRequestResult {
-    kind: "approved" | "denied-by-rules" | "denied-no-approval-rule-and-could-not-request-from-user" | "denied-interactively-by-user";
-    rules?: unknown[];
-}
+import type { SessionPermissionsHandlePendingPermissionRequestParams } from "./generated/rpc.js";
+export type PermissionRequestResult = SessionPermissionsHandlePendingPermissionRequestParams["result"];
 export type PermissionHandler = (request: PermissionRequest, invocation: {
     sessionId: string;
 }) => Promise<PermissionRequestResult> | PermissionRequestResult;

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "0.1.30",
+  "version": "0.1.31",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,6 +12,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./extension": {
+      "import": "./dist/extension.js",
+      "types": "./dist/extension.d.ts"
     }
   },
   "type": "module",
@@ -40,7 +44,7 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@github/copilot": "^0.0.420",
+    "@github/copilot": "^1.0.2",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.6"
   },