@github/copilot-sdk 1.0.3 → 1.0.4

package/dist/session.js

@@ -15,7 +15,7 @@ function isOpenCanvasInstance(value) {
     return false;
   }
   const instance = value;
-  return typeof instance.instanceId === "string" && instance.instanceId.length > 0 && typeof instance.extensionId === "string" && instance.extensionId.length > 0 && typeof instance.canvasId === "string" && instance.canvasId.length > 0 && typeof instance.reopen === "boolean" && (instance.availability === "ready" || instance.availability === "stale");
+  return typeof instance.instanceId === "string" && instance.instanceId.length > 0 && typeof instance.extensionId === "string" && instance.extensionId.length > 0 && typeof instance.canvasId === "string" && instance.canvasId.length > 0;
 }
 class CopilotSession {
   /**
@@ -40,6 +40,7 @@ class CopilotSession {
   typedEventHandlers = /* @__PURE__ */ new Map();
   toolHandlers = /* @__PURE__ */ new Map();
   canvases = /* @__PURE__ */ new Map();
+  bearerTokenProviders = /* @__PURE__ */ new Map();
   commandHandlers = /* @__PURE__ */ new Map();
   permissionHandler;
   userInputHandler;
@@ -52,6 +53,7 @@ class CopilotSession {
   traceContextProvider;
   _capabilities = {};
   openCanvasInstances = [];
+  disconnected = false;
   /** @internal Client session API handlers, populated by CopilotClient during create/resume. */
   clientSessionApis = {};
   /**
@@ -155,6 +157,21 @@ class CopilotSession {
       unsubscribe();
     }
   }
+  /** @internal */
+  _markDisconnected() {
+    this.disconnected = true;
+    this.eventHandlers.clear();
+    this.typedEventHandlers.clear();
+    this.toolHandlers.clear();
+    this.permissionHandler = void 0;
+    this.userInputHandler = void 0;
+    this.elicitationHandler = void 0;
+    this.exitPlanModeHandler = void 0;
+    this.autoModeSwitchHandler = void 0;
+    this.commandHandlers.clear();
+    this.canvases.clear();
+    this.transformCallbacks?.clear();
+  }
   on(eventTypeOrHandler, handler) {
     if (typeof eventTypeOrHandler === "string" && handler) {
       const eventType = eventTypeOrHandler;
@@ -208,6 +225,9 @@ class CopilotSession {
    * @internal
    */
   _handleBroadcastEvent(event) {
+    if (this.disconnected) {
+      return;
+    }
     if (event.type === "external_tool.requested") {
       const { requestId, toolName } = event.data;
       const args = event.data.arguments;
@@ -313,8 +333,14 @@ class CopilotSession {
       } else {
         result = JSON.stringify(rawResult);
       }
+      if (this.disconnected) {
+        return;
+      }
       await this.rpc.tools.handlePendingToolCall({ requestId, result });
     } catch (error) {
+      if (this.disconnected) {
+        return;
+      }
       const message = error instanceof Error ? error.message : String(error);
       try {
         await this.rpc.tools.handlePendingToolCall({ requestId, error: message });
@@ -337,8 +363,14 @@ class CopilotSession {
       if (result.kind === "no-result") {
         return;
       }
+      if (this.disconnected) {
+        return;
+      }
       await this.rpc.permissions.handlePendingPermissionRequest({ requestId, result });
     } catch (_error) {
+      if (this.disconnected) {
+        return;
+      }
       try {
         await this.rpc.permissions.handlePendingPermissionRequest({
           requestId,
@@ -374,8 +406,14 @@ class CopilotSession {
     }
     try {
       await handler({ sessionId: this.sessionId, command, commandName, args });
+      if (this.disconnected) {
+        return;
+      }
       await this.rpc.commands.handlePendingCommand({ requestId });
     } catch (error) {
+      if (this.disconnected) {
+        return;
+      }
       const message = error instanceof Error ? error.message : String(error);
       try {
         await this.rpc.commands.handlePendingCommand({ requestId, error: message });
@@ -471,6 +509,43 @@ class CopilotSession {
       }
     };
   }
+  /**
+   * Registers per-provider {@link GetBearerToken} callbacks for BYOK providers
+   * configured with managed-identity / on-demand bearer-token auth.
+   *
+   * The runtime never receives the callback itself; the SDK strips it from the
+   * provider config and instead sends `hasBearerTokenProvider: true`. When the
+   * runtime needs a token it issues a session-scoped `providerToken.getToken`
+   * request, which this handler routes to the matching per-provider callback.
+   *
+   * @param providers - Map of provider name → callback, or undefined/empty to clear.
+   * @internal This method is called internally when creating/resuming a session.
+   */
+  registerBearerTokenProviders(providers) {
+    this.bearerTokenProviders.clear();
+    if (!providers || providers.size === 0) {
+      delete this.clientSessionApis.providerToken;
+      return;
+    }
+    for (const [name, callback] of providers) {
+      this.bearerTokenProviders.set(name, callback);
+    }
+    const self = this;
+    this.clientSessionApis.providerToken = {
+      async getToken(params) {
+        const callback = self.bearerTokenProviders.get(params.providerName);
+        if (!callback) {
+          throw new Error(
+            `No bearer-token provider registered for provider "${params.providerName}"`
+          );
+        }
+        const token = await callback({
+          providerName: params.providerName
+        });
+        return { token };
+      }
+    };
+  }
   /**
    * Registers command handlers for this session.
    *
@@ -825,17 +900,13 @@ class CopilotSession {
    * ```
    */
   async disconnect() {
+    if (this.disconnected) {
+      return;
+    }
     await this.connection.sendRequest("session.destroy", {
       sessionId: this.sessionId
     });
-    this.eventHandlers.clear();
-    this.typedEventHandlers.clear();
-    this.toolHandlers.clear();
-    this.permissionHandler = void 0;
-    this.userInputHandler = void 0;
-    this.elicitationHandler = void 0;
-    this.exitPlanModeHandler = void 0;
-    this.autoModeSwitchHandler = void 0;
+    this._markDisconnected();
   }
   /** Enables `await using session = ...` syntax for automatic cleanup. */
   async [Symbol.asyncDispose]() {

package/dist/types.d.ts

@@ -3,6 +3,7 @@
  */
 import type { Canvas } from "./canvas.js";
 import type { SessionFsProvider } from "./sessionFsProvider.js";
+import type { CopilotRequestHandler } from "./copilotRequestHandler.js";
 import type { ReasoningSummary, SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
 import type { CopilotSession } from "./session.js";
 import type { ModelBillingTokenPrices, OpenCanvasInstance, RemoteSessionMode } from "./generated/rpc.js";
@@ -17,6 +18,9 @@ export type { SessionFsFileInfo } from "./sessionFsProvider.js";
 export type { SessionFsSqliteQueryResult } from "./sessionFsProvider.js";
 export type { SessionFsSqliteQueryType } from "./sessionFsProvider.js";
 export type { SessionFsSqliteProvider } from "./sessionFsProvider.js";
+export type { LlmInferenceHeaders } from "./generated/rpc.js";
+export type { CopilotRequestContext } from "./copilotRequestHandler.js";
+export { CopilotRequestHandler, CopilotWebSocketHandler, CopilotWebSocketCloseStatus, CopilotWebSocketForwarder, } from "./copilotRequestHandler.js";
 /**
  * Options for creating a CopilotClient
  */
@@ -243,6 +247,29 @@ export interface CopilotClientOptions {
      * instead of the server's default local filesystem storage.
      */
     sessionFs?: SessionFsConfig;
+    /**
+     * Custom handler for outbound model-layer requests (experimental).
+     *
+     * When provided, the client registers as the runtime's request handler
+     * on connection: every outbound model-layer request the runtime would
+     * otherwise have issued itself — plain HTTP, streaming SSE, and
+     * WebSocket — is dispatched back to the handler over JSON-RPC. The
+     * handler returns the response verbatim, exactly as if the runtime had
+     * issued the request itself.
+     *
+     * Subclass {@link CopilotRequestHandler} and override the hooks you need;
+     * an instance that overrides nothing is a transparent pass-through.
+     *
+     * v1 notes:
+     * - HTTP (buffered and streaming SSE) and WebSocket transports are all
+     *   intercepted. The handler receives a `transport` discriminator on the
+     *   {@link CopilotRequestContext} for both.
+     * - The handler is set process-globally on the runtime; the same
+     *   handler is invoked for every session created on this client.
+     *
+     * @experimental
+     */
+    requestHandler?: CopilotRequestHandler;
     /**
      * Server-wide idle timeout for sessions in seconds.
      * Sessions without activity for this duration are automatically cleaned up.
@@ -622,7 +649,7 @@ export interface ToolCallResponsePayload {
  * Known system message section identifiers for the "customize" mode.
  * Each section corresponds to a distinct part of the system prompt.
  */
-export type SystemMessageSection = "identity" | "tone" | "tool_efficiency" | "environment_context" | "code_change_rules" | "guidelines" | "safety" | "tool_instructions" | "custom_instructions" | "runtime_instructions" | "last_instructions";
+export type SystemMessageSection = "preamble" | "identity" | "tone" | "tool_efficiency" | "environment_context" | "code_change_rules" | "guidelines" | "safety" | "tool_instructions" | "custom_instructions" | "runtime_instructions" | "last_instructions";
 /** Section metadata for documentation and tooling. */
 export declare const SYSTEM_MESSAGE_SECTIONS: Record<SystemMessageSection, {
     description: string;
@@ -638,9 +665,11 @@ export type SectionTransformFn = (currentContent: string) => string | Promise<st
  * - `"remove"`: Remove the section
  * - `"append"`: Append to existing section content
  * - `"prepend"`: Prepend to existing section content
+ * - `"preserve"`: No-op marker that opts an individually-addressable section out of a
+ *   group-level `"remove"` (e.g. keep `tone` when removing the `identity` group)
  * - `function`: Transform callback — receives current section content, returns new content
  */
-export type SectionOverrideAction = "replace" | "remove" | "append" | "prepend" | SectionTransformFn;
+export type SectionOverrideAction = "replace" | "remove" | "append" | "prepend" | "preserve" | SectionTransformFn;
 /**
  * Override operation for a single system message section.
  */
@@ -1260,6 +1289,30 @@ export interface ExtensionInfo {
     /** Stable provider name within the source namespace. */
     name: string;
 }
+/**
+ * Provider-scoped options for the Copilot API (CAPI).
+ *
+ * These settings apply to the built-in Copilot API provider only. They live
+ * under their own namespace because a single session can host multiple
+ * providers (CAPI alongside BYOK via {@link ProviderConfig}), so transport and
+ * provider-level choices are conceptually per-provider rather than global.
+ */
+export interface CapiSessionOptions {
+    /**
+     * Whether to use the WebSocket transport for the CAPI Responses API.
+     *
+     * WebSocket transport is enabled by default whenever the selected model
+     * advertises the `ws:/responses` endpoint. Set this to `false` to fall back
+     * to the HTTP Responses transport instead — useful for users behind proxies
+     * where WebSocket connections fail.
+     *
+     * Setting this to `false` is equivalent to setting the
+     * `COPILOT_CLI_DISABLE_WEBSOCKET_RESPONSES` environment variable.
+     *
+     * @default true
+     */
+    enableWebSocketResponses?: boolean;
+}
 /**
  * Shared configuration fields used by both {@link SessionConfig} (for
  * creating a new session) and {@link ResumeSessionConfig} (for resuming
@@ -1400,6 +1453,12 @@ export interface SessionConfigBase {
      * When specified, uses the provided API endpoint instead of the Copilot API.
      */
     provider?: ProviderConfig;
+    /**
+     * Provider-scoped options for the built-in Copilot API (CAPI), such as
+     * opting out of the WebSocket Responses transport. See
+     * {@link CapiSessionOptions}.
+     */
+    capi?: CapiSessionOptions;
     /**
      * Named BYOK provider connections (transport + credentials), referenced by
      * {@link models} entries via {@link NamedProviderConfig.name}.
@@ -1739,6 +1798,37 @@ export interface ResumeSessionConfig extends SessionConfigBase {
      */
     openCanvases?: OpenCanvasInstance[];
 }
+/**
+ * Arguments passed to a {@link GetBearerToken} callback when the runtime needs a
+ * fresh bearer token for a BYOK provider.
+ *
+ * @experimental Part of the experimental managed-identity / bearer-token-provider
+ * surface and may change or be removed in future SDK or CLI releases.
+ */
+export interface ProviderTokenArgs {
+    /**
+     * Name of the BYOK provider needing a token. For the singular, whole-session
+     * {@link ProviderConfig} this is the implicit provider name (`"default"`); for
+     * {@link NamedProviderConfig} entries it is {@link NamedProviderConfig.name}.
+     *
+     * The callback closes over its own token scope/audience; the runtime is
+     * provider-agnostic and forwards only the provider name.
+     */
+    providerName: string;
+}
+/**
+ * Per-provider callback that resolves a bearer token on demand, returning the
+ * raw token string (without the `Bearer ` prefix). The Copilot SDK itself takes
+ * no Azure dependency: the consumer supplies this callback backed by their own
+ * identity library (for example `@azure/identity`'s
+ * `DefaultAzureCredential.getToken(scope)`), and the runtime calls it once before
+ * each outbound model request. The runtime does no caching of its own, so the
+ * callback (or the identity library it wraps) owns token caching and refresh.
+ *
+ * @experimental Part of the experimental managed-identity / bearer-token-provider
+ * surface and may change or be removed in future SDK or CLI releases.
+ */
+export type GetBearerToken = (args: ProviderTokenArgs) => Promise<string>;
 /**
  * Configuration for a custom API provider.
  */
@@ -1751,6 +1841,16 @@ export interface ProviderConfig {
      * API format (openai/azure only). Defaults to "completions".
      */
     wireApi?: "completions" | "responses";
+    /**
+     * Transport for OpenAI Responses requests. Defaults to "http".
+     *
+     * Set to "websockets" to deliver Responses API requests over a persistent
+     * WebSocket connection instead of HTTP. Useful for long-running,
+     * tool-call-heavy sessions that benefit from incremental
+     * `previous_response_id` continuations. Applies to OpenAI-compatible
+     * providers using `wireApi: "responses"`.
+     */
+    transport?: "http" | "websockets";
     /**
      * API endpoint URL
      */
@@ -1765,6 +1865,17 @@ export interface ProviderConfig {
      * Takes precedence over apiKey when both are set.
      */
     bearerToken?: string;
+    /**
+     * Per-request bearer-token provider for managed-identity / on-demand auth.
+     * When set, the SDK keeps this function client-side (it is never serialized)
+     * and the runtime calls back into this client to acquire a token before each
+     * outbound request. The runtime does no caching of its own, so the callback
+     * owns token caching and refresh. Mutually exclusive with {@link apiKey} /
+     * {@link bearerToken}.
+     *
+     * @experimental
+     */
+    getBearerToken?: GetBearerToken;
     /**
      * Azure-specific options
      */
@@ -1844,6 +1955,17 @@ export interface NamedProviderConfig {
      * Takes precedence over {@link apiKey} when both are set.
      */
     bearerToken?: string;
+    /**
+     * Per-request bearer-token provider for managed-identity / on-demand auth.
+     * When set, the SDK keeps this function client-side (it is never serialized)
+     * and the runtime calls back into this client to acquire a token before each
+     * outbound request. The runtime does no caching of its own, so the callback
+     * owns token caching and refresh. Mutually exclusive with {@link apiKey} /
+     * {@link bearerToken}.
+     *
+     * @experimental
+     */
+    getBearerToken?: GetBearerToken;
     /**
      * Azure-specific options.
      */

package/dist/types.js

@@ -1,4 +1,10 @@
 import { createSessionFsAdapter } from "./sessionFsProvider.js";
+import {
+  CopilotRequestHandler,
+  CopilotWebSocketHandler,
+  CopilotWebSocketCloseStatus,
+  CopilotWebSocketForwarder
+} from "./copilotRequestHandler.js";
 const RuntimeConnection = {
   /**
    * Spawn a runtime child process and communicate over its stdin/stdout.
@@ -73,7 +79,10 @@ function defineTool(name, config) {
   return { name, ...config };
 }
 const SYSTEM_MESSAGE_SECTIONS = {
-  identity: { description: "Agent identity preamble and mode statement" },
+  preamble: { description: "Agent identity preamble and mode statement" },
+  identity: {
+    description: "Section group covering the identity preamble and its sibling sub-sections (tone, tool efficiency, etc.)"
+  },
   tone: { description: "Response style, conciseness rules, output formatting preferences" },
   tool_efficiency: { description: "Tool usage patterns, parallel calling, batching guidelines" },
   environment_context: { description: "CWD, OS, git root, directory listing, available tools" },
@@ -94,6 +103,10 @@ const defaultJoinSessionPermissionHandler = () => ({
   kind: "no-result"
 });
 export {
+  CopilotRequestHandler,
+  CopilotWebSocketCloseStatus,
+  CopilotWebSocketForwarder,
+  CopilotWebSocketHandler,
   RuntimeConnection,
   SYSTEM_MESSAGE_SECTIONS,
   approveAll,

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/cjs/index.js",
   "types": "./dist/index.d.ts",
@@ -56,13 +56,14 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@github/copilot": "^1.0.64-1",
+    "@github/copilot": "^1.0.65",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@platformatic/vfs": "^0.3.0",
     "@types/node": "^25.2.0",
+    "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^8.54.0",
     "@typescript-eslint/parser": "^8.54.0",
     "esbuild": "^0.28.1",
@@ -76,7 +77,8 @@
     "semver": "^7.7.3",
     "tsx": "^4.20.6",
     "typescript": "^5.0.0",
-    "vitest": "^4.0.18"
+    "vitest": "^4.0.18",
+    "ws": "^8.21.0"
   },
   "engines": {
     "node": "^20.19.0 || >=22.12.0"