@github/copilot-sdk 1.0.4 → 1.0.5-preview.1

package/dist/session.js

@@ -27,11 +27,12 @@ class CopilotSession {
    * @param traceContextProvider - Optional callback to get W3C Trace Context for outbound RPCs
    * @internal This constructor is internal. Use {@link CopilotClient.createSession} to create sessions.
    */
-  constructor(sessionId, connection, _workspacePath, traceContextProvider) {
+  constructor(sessionId, connection, _workspacePath, traceContextProvider, options) {
     this.sessionId = sessionId;
     this.connection = connection;
     this._workspacePath = _workspacePath;
     this.traceContextProvider = traceContextProvider;
+    this.mcpAuthHandler = options?.mcpAuthHandler;
   }
   sessionId;
   connection;
@@ -43,6 +44,7 @@ class CopilotSession {
   bearerTokenProviders = /* @__PURE__ */ new Map();
   commandHandlers = /* @__PURE__ */ new Map();
   permissionHandler;
+  mcpAuthHandler;
   userInputHandler;
   elicitationHandler;
   exitPlanModeHandler;
@@ -254,6 +256,18 @@ class CopilotSession {
       if (this.permissionHandler) {
         void this._executePermissionAndRespond(requestId, permissionRequest);
       }
+    } else if (event.type === "mcp.oauth_required") {
+      const data = event.data;
+      if (!data?.requestId) {
+        return;
+      }
+      if (!this.mcpAuthHandler) {
+        console.warn(
+          `Received MCP OAuth request without a registered MCP auth handler. SessionId=${this.sessionId}, RequestId=${data.requestId}`
+        );
+        return;
+      }
+      void this._executeMcpAuthAndRespond(data);
     } else if (event.type === "command.execute") {
       const { requestId, commandName, command, args } = event.data;
       void this._executeCommandAndRespond(requestId, commandName, command, args);
@@ -385,6 +399,31 @@ class CopilotSession {
       }
     }
   }
+  /**
+   * Executes an MCP auth handler and sends the result back via RPC.
+   * @internal
+   */
+  async _executeMcpAuthAndRespond(request) {
+    try {
+      const result = await this.mcpAuthHandler(request, { sessionId: this.sessionId });
+      const response = result && "accessToken" in result ? { kind: "token", ...result } : { kind: "cancelled" };
+      await this.rpc.mcp.oauth.handlePendingRequest({
+        requestId: request.requestId,
+        result: response
+      });
+    } catch (_error) {
+      try {
+        await this.rpc.mcp.oauth.handlePendingRequest({
+          requestId: request.requestId,
+          result: { kind: "cancelled" }
+        });
+      } catch (rpcError) {
+        if (!(rpcError instanceof ConnectionError || rpcError instanceof ResponseError)) {
+          throw rpcError;
+        }
+      }
+    }
+  }
   /**
    * Executes a command handler and sends the result back via RPC.
    * @internal
@@ -510,7 +549,7 @@ class CopilotSession {
     };
   }
   /**
-   * Registers per-provider {@link GetBearerToken} callbacks for BYOK providers
+   * Registers per-provider {@link BearerTokenProvider} 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
@@ -540,7 +579,8 @@ class CopilotSession {
           );
         }
         const token = await callback({
-          providerName: params.providerName
+          providerName: params.providerName,
+          sessionId: params.sessionId
         });
         return { token };
       }

package/dist/types.d.ts

@@ -1280,6 +1280,68 @@ export type ReasoningEffort = "low" | "medium" | "high" | "xhigh";
  * long-context tier when the selected model supports it.
  */
 export type ContextTier = "default" | "long_context";
+/** Parsed parameters from an MCP server's WWW-Authenticate response. */
+export interface McpAuthWwwAuthenticateParams {
+    /** Parsed resource_metadata URL used for protected-resource metadata discovery, if present. */
+    resourceMetadataUrl?: string;
+    /** Parsed OAuth scope, if present. */
+    scope?: string;
+    /** Parsed OAuth error, if present. */
+    error?: string;
+}
+/** Static OAuth client configuration supplied by the MCP server, if available. */
+export interface McpAuthStaticClientConfig {
+    /** OAuth client ID for the server. */
+    clientId: string;
+    /** Optional OAuth client secret for confidential static clients. */
+    clientSecret?: string;
+    /** Optional non-default OAuth grant type. */
+    grantType?: "client_credentials";
+    /** Whether this is a public OAuth client. */
+    publicClient?: boolean;
+}
+/** MCP OAuth request that the SDK host can satisfy with a host-acquired token. */
+export interface McpAuthRequest {
+    /** Unique request identifier used by the SDK when responding. */
+    requestId: string;
+    /** Display name of the MCP server that requires OAuth. */
+    serverName: string;
+    /** URL of the MCP server that requires OAuth. */
+    serverUrl: string;
+    /** Why the runtime is requesting host-provided OAuth credentials. */
+    reason: "initial" | "refresh" | "reauth" | "upscope";
+    /** Parsed WWW-Authenticate parameters from the MCP server. */
+    wwwAuthenticateParams?: McpAuthWwwAuthenticateParams;
+    /** Raw RFC 9728 protected-resource metadata JSON fetched by the runtime, if available. */
+    resourceMetadata?: string;
+    /** Static OAuth client configuration, if the server specifies one. */
+    staticClientConfig?: McpAuthStaticClientConfig;
+}
+/** Host-provided OAuth token data for a pending MCP OAuth request. */
+export interface McpAuthToken {
+    /** Access token acquired by the SDK host. */
+    accessToken: string;
+    /** OAuth token type. Defaults to Bearer when omitted. */
+    tokenType?: string;
+    /** Token lifetime in seconds, if known. */
+    expiresIn?: number;
+}
+/**
+ * Result returned by an MCP auth request handler.
+ *
+ * Return `null`/`undefined` or `{ kind: "cancelled" }` to cancel the pending
+ * OAuth request. Return `{ kind: "token", ... }` to provide host-acquired
+ * OAuth token data.
+ */
+export type McpAuthResult = ({
+    kind: "token";
+} & McpAuthToken) | {
+    kind: "cancelled";
+};
+/** Callback invoked when an MCP server requires OAuth and the SDK host opted in. */
+export type McpAuthHandler = (request: McpAuthRequest, context: {
+    sessionId: string;
+}) => McpAuthResult | McpAuthToken | null | undefined | Promise<McpAuthResult | McpAuthToken | null | undefined>;
 /**
  * Stable extension identity for session participants that provide canvases.
  */
@@ -1531,6 +1593,12 @@ export interface SessionConfigBase {
      * the consumer to resolve via the pending permission RPC.
      */
     onPermissionRequest?: PermissionHandler;
+    /**
+     * Optional handler for MCP OAuth requests from MCP servers.
+     * When provided, the SDK can satisfy MCP server OAuth requests with
+     * host-provided token data or cancellation.
+     */
+    onMcpAuthRequest?: McpAuthHandler;
     /**
      * Handler for user input requests from the agent.
      * When provided, enables the ask_user tool allowing the agent to ask questions.
@@ -1799,7 +1867,7 @@ export interface ResumeSessionConfig extends SessionConfigBase {
     openCanvases?: OpenCanvasInstance[];
 }
 /**
- * Arguments passed to a {@link GetBearerToken} callback when the runtime needs a
+ * Arguments passed to a {@link BearerTokenProvider} callback when the runtime needs a
  * fresh bearer token for a BYOK provider.
  *
  * @experimental Part of the experimental managed-identity / bearer-token-provider
@@ -1814,7 +1882,14 @@ export interface ProviderTokenArgs {
      * The callback closes over its own token scope/audience; the runtime is
      * provider-agnostic and forwards only the provider name.
      */
-    providerName: string;
+    readonly providerName: string;
+    /**
+     * Id of the session that triggered this token request. A client-level shared
+     * callback registered for many sessions can use this to resolve the owning
+     * session (e.g. via the client's session lookup) to scope token acquisition
+     * or caching per session.
+     */
+    readonly sessionId: string;
 }
 /**
  * Per-provider callback that resolves a bearer token on demand, returning the
@@ -1828,7 +1903,7 @@ export interface ProviderTokenArgs {
  * @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>;
+export type BearerTokenProvider = (args: ProviderTokenArgs) => Promise<string>;
 /**
  * Configuration for a custom API provider.
  */
@@ -1870,12 +1945,14 @@ export interface ProviderConfig {
      * 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}.
+     * owns token caching and refresh. When set alongside {@link apiKey} /
+     * {@link bearerToken}, this callback takes precedence: the runtime applies
+     * the token it returns as the `Authorization: Bearer` header for each
+     * request and does not send the static credential.
      *
      * @experimental
      */
-    getBearerToken?: GetBearerToken;
+    bearerTokenProvider?: BearerTokenProvider;
     /**
      * Azure-specific options
      */
@@ -1960,12 +2037,14 @@ export interface NamedProviderConfig {
      * 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}.
+     * owns token caching and refresh. When set alongside {@link apiKey} /
+     * {@link bearerToken}, this callback takes precedence: the runtime applies
+     * the token it returns as the `Authorization: Bearer` header for each
+     * request and does not send the static credential.
      *
      * @experimental
      */
-    getBearerToken?: GetBearerToken;
+    bearerTokenProvider?: BearerTokenProvider;
     /**
      * Azure-specific options.
      */

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "1.0.4",
+  "version": "1.0.5-preview.1",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/cjs/index.js",
   "types": "./dist/index.d.ts",
@@ -56,7 +56,7 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@github/copilot": "^1.0.65",
+    "@github/copilot": "^1.0.66-2",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.6"
   },