@github/copilot-sdk 1.0.2 → 1.0.4

package/dist/index.d.ts

@@ -8,6 +8,6 @@ export { RuntimeConnection } from "./types.js";
 export { BuiltInTools, ToolSet } from "./toolSet.js";
 export { CopilotSession, type AssistantMessageEvent } from "./session.js";
 export { Canvas, CanvasError, createCanvas, type CanvasAction, type CanvasDeclaration, type CanvasHostContext, type CanvasHostContextCapabilities, type CanvasJsonSchema, type CanvasOptions, } from "./canvas.js";
-export { defineTool, approveAll, convertMcpCallToolResult, createSessionFsAdapter, SYSTEM_MESSAGE_SECTIONS, } from "./types.js";
+export { defineTool, approveAll, convertMcpCallToolResult, createSessionFsAdapter, CopilotRequestHandler, CopilotWebSocketHandler, CopilotWebSocketCloseStatus, CopilotWebSocketForwarder, SYSTEM_MESSAGE_SECTIONS, } from "./types.js";
 export type * from "./generated/session-events.js";
-export type { CommandContext, CommandDefinition, CommandHandler, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, CopilotClientMode, CopilotClientOptions, StdioRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, MessageOptions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, PermissionHandler, PermissionRequest, PermissionRequestResult, ProviderConfig, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolTelemetry, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export type { CommandContext, CommandDefinition, CommandHandler, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, CopilotClientMode, CopilotClientOptions, StdioRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, GetBearerToken, MessageOptions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, CapiSessionOptions, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestResult, ProviderConfig, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolTelemetry, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";

package/dist/index.js

@@ -12,6 +12,10 @@ import {
   approveAll,
   convertMcpCallToolResult,
   createSessionFsAdapter,
+  CopilotRequestHandler,
+  CopilotWebSocketHandler,
+  CopilotWebSocketCloseStatus,
+  CopilotWebSocketForwarder,
   SYSTEM_MESSAGE_SECTIONS
 } from "./types.js";
 export {
@@ -19,7 +23,11 @@ export {
   Canvas,
   CanvasError,
   CopilotClient,
+  CopilotRequestHandler,
   CopilotSession,
+  CopilotWebSocketCloseStatus,
+  CopilotWebSocketForwarder,
+  CopilotWebSocketHandler,
   RuntimeConnection,
   SYSTEM_MESSAGE_SECTIONS,
   ToolSet,

package/dist/session.d.ts

@@ -38,6 +38,7 @@ export declare class CopilotSession {
     private typedEventHandlers;
     private toolHandlers;
     private canvases;
+    private bearerTokenProviders;
     private commandHandlers;
     private permissionHandler?;
     private userInputHandler?;
@@ -50,6 +51,7 @@ export declare class CopilotSession {
     private traceContextProvider?;
     private _capabilities;
     private openCanvasInstances;
+    private disconnected;
     /**
      * Typed session-scoped RPC methods.
      */

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,36 @@ 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}.
+     *
+     * Unlike the singular {@link provider} — which makes the entire session BYOK
+     * and bypasses Copilot API authentication — named providers are **additive**:
+     * they coexist with Copilot API auth so models from CAPI and one or more BYOK
+     * providers can be mixed within a single session and across sub-agents.
+     * Combining `providers`/`models` with {@link provider} is rejected.
+     *
+     * @experimental This is part of an experimental multi-provider BYOK surface
+     * and may change or be removed in future SDK or CLI releases.
+     */
+    providers?: NamedProviderConfig[];
+    /**
+     * BYOK model definitions added to the session's selectable model list, each
+     * referencing a `providers[].name`. Each model surfaces under the
+     * provider-qualified selection id `providerName/id`, so BYOK ids never collide
+     * with — and cannot shadow — bare CAPI ids; duplicate selection ids are rejected.
+     *
+     * @experimental This is part of an experimental multi-provider BYOK surface
+     * and may change or be removed in future SDK or CLI releases.
+     */
+    models?: ProviderModelConfig[];
     /**
      * Enables or disables internal session telemetry for this session.
      * When `false`, disables session telemetry. When omitted (the default) or `true`,
@@ -1715,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.
  */
@@ -1727,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
      */
@@ -1741,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
      */
@@ -1782,8 +1917,128 @@ export interface ProviderConfig {
     maxOutputTokens?: number;
 }
 /**
- * Options for sending a message to a session
+ * A named BYOK provider connection (transport + credentials only), referenced by
+ * {@link ProviderModelConfig} entries via {@link NamedProviderConfig.name}.
+ *
+ * Unlike the singular, whole-session {@link ProviderConfig} — which bypasses
+ * Copilot API authentication — named providers are **additive** and coexist with
+ * Copilot API auth, so CAPI and BYOK models can be mixed within one session and
+ * across sub-agents. See {@link SessionConfigBase.providers}.
+ *
+ * @experimental This type is part of an experimental multi-provider BYOK surface
+ * and may change or be removed in future SDK or CLI releases.
+ */
+export interface NamedProviderConfig {
+    /**
+     * Stable identifier referenced by {@link ProviderModelConfig.provider}.
+     * Must not contain `/`.
+     */
+    name: string;
+    /**
+     * Provider type. Defaults to "openai" for generic OpenAI-compatible APIs.
+     */
+    type?: "openai" | "azure" | "anthropic";
+    /**
+     * Wire API format (openai/azure only). Defaults to "completions".
+     */
+    wireApi?: "completions" | "responses";
+    /**
+     * API endpoint URL.
+     */
+    baseUrl: string;
+    /**
+     * API key. Optional for local providers like Ollama.
+     */
+    apiKey?: string;
+    /**
+     * Bearer token for authentication. Sets the Authorization header directly.
+     * 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.
+     */
+    azure?: {
+        /**
+         * API version. When set, uses the versioned deployment route. When
+         * omitted, uses the GA versionless v1 route.
+         */
+        apiVersion?: string;
+    };
+    /**
+     * Custom HTTP headers to include in all outbound requests to the provider.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * A BYOK model definition that references a {@link NamedProviderConfig} by name
+ * and is added to the session's selectable model list.
+ *
+ * Each model has three identities:
+ *  - {@link id}: the provider-local model id, unique within its provider. The
+ *    session-wide selection id (shown in the model list and passed to model
+ *    switching) is the provider-qualified `provider/id`.
+ *  - {@link modelId}: the well-known behavior base model used for
+ *    capability/config lookup. Defaults to {@link id}.
+ *  - {@link wireModel}: the model name actually sent to the provider API for
+ *    inference. Defaults to {@link id}.
+ *
+ * @experimental This type is part of an experimental multi-provider BYOK surface
+ * and may change or be removed in future SDK or CLI releases.
  */
+export interface ProviderModelConfig {
+    /**
+     * Provider-local model id, unique within its provider. The session-wide
+     * selection id is the provider-qualified `provider/id`.
+     */
+    id: string;
+    /**
+     * Name of the {@link NamedProviderConfig} that serves this model.
+     */
+    provider: string;
+    /**
+     * The model name sent to the provider API for inference. Defaults to {@link id}.
+     */
+    wireModel?: string;
+    /**
+     * Well-known base model id used for behavior/capability/config lookup.
+     * Defaults to {@link id}.
+     */
+    modelId?: string;
+    /**
+     * Display name for model pickers. Defaults to the provider-qualified
+     * selection id (`provider/id`).
+     */
+    name?: string;
+    /**
+     * Maximum prompt/input tokens for the model.
+     */
+    maxPromptTokens?: number;
+    /**
+     * Maximum context window tokens for the model.
+     */
+    maxContextWindowTokens?: number;
+    /**
+     * Maximum output tokens for the model.
+     */
+    maxOutputTokens?: number;
+    /**
+     * Optional capability overrides (vision, tool_calls, reasoning, etc.) for
+     * the synthesized model.
+     */
+    capabilities?: ModelCapabilitiesOverride;
+}
 export interface MessageOptions {
     /**
      * The prompt/message to send

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.2",
+  "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-0",
+    "@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"