@github/copilot-sdk 1.0.13-preview.1 → 1.0.13-preview.3

package/README.md

@@ -137,12 +137,26 @@ Create a new conversation session.
 - `infiniteSessions?: InfiniteSessionConfig` - Configure automatic context compaction (see below)
 - `workingDirectory?: string` - Working directory for the session (default: runtime process cwd).
 - `enableSessionStore?: boolean` - Enables the cross-session store for search and retrieval across sessions. When unset in `"copilot-cli"` mode, the runtime default applies (enabled). In `"empty"` mode, defaults to disabled.
+- `gitHubTokenProvider?: GitHubTokenProvider` - Acquires rotating, session-scoped GitHub tokens. Token results require a positive `expiresIn` value in seconds remaining when the callback completes; production tokens typically last eight hours. Cannot be combined with `gitHubToken`.
 - `provider?: ProviderConfig` - Custom API provider configuration (BYOK - Bring Your Own Key). See [Custom Providers](#custom-providers) section.
 - `onPermissionRequest?: PermissionHandler` - Optional handler called before each tool execution to approve or deny it. When omitted, permission requests are emitted as events and left pending for manual resolution. `approveAll` approves requests when managed settings are disabled and throws when `enableManagedSettings` is true. Custom handlers can inspect `managedApprovalRequired` for human-facing confirmation logic. See [Permission Handling](#permission-handling) section.
-- `onUserInputRequest?: UserInputHandler` - Handler for user input requests from the agent. Enables the `ask_user` tool. See [User Input Requests](#user-input-requests) section.
+- `onUserInputRequest?: UserInputHandler` - Handler for legacy question-and-answer requests from the agent. Enables the legacy `ask_user` tool. See [User Input Requests](#user-input-requests) section.
+- `askUserVariant?: "legacy" | "elicitation"` - Selects the model-facing `ask_user` tool shape when creating or cold-resuming a session. Defaults to `"legacy"`; use `"elicitation"` with `onElicitationRequest`.
 - `onElicitationRequest?: ElicitationHandler` - Handler for elicitation requests dispatched by the server. Enables this client to present form-based UI dialogs on behalf of the agent or other session participants. See [Elicitation Requests](#elicitation-requests) section.
 - `hooks?: SessionHooks` - Hook handlers for session lifecycle events. See [Session Hooks](#session-hooks) section.
 
+```typescript
+const session = await client.createSession({
+    gitHubTokenProvider: async ({ host }) => ({
+        kind: "token",
+        accessToken: await acquireTokenForHost(host),
+        expiresIn: 8 * 60 * 60,
+    }),
+});
+```
+
+Initial acquisition runs during session creation or resume. Cancellation, provider errors, and invalid token responses reject that operation instead of falling back to ambient authentication. Idle sessions refresh only before their next credential-consuming operation; there is no background refresh timer.
+
 ##### `resumeSession(sessionId: string, config?: ResumeSessionConfig): Promise<CopilotSession>`
 
 Resume an existing session. Returns the session with `workspacePath` populated if infinite sessions were enabled.
@@ -946,7 +960,7 @@ To let a specific custom tool bypass the permission prompt entirely, set `skipPe
 
 ## User Input Requests
 
-Enable the agent to ask questions to the user using the `ask_user` tool by providing an `onUserInputRequest` handler:
+Enable the legacy question-and-answer `ask_user` tool by providing an `onUserInputRequest` handler:
 
 ```typescript
 const session = await client.createSession({
@@ -978,6 +992,7 @@ Register an `onElicitationRequest` handler to let your client act as an elicitat
 const session = await client.createSession({
     model: "gpt-5",
     onPermissionRequest: approveAll,
+    askUserVariant: "elicitation",
     onElicitationRequest: async (context) => {
         // context.sessionId - Session that triggered the request
         // context.message - Description of what information is needed
@@ -999,6 +1014,9 @@ const session = await client.createSession({
 console.log(session.capabilities.ui?.elicitation); // true
 ```
 
+Set `askUserVariant: "elicitation"` to expose the structured form as the model's
+`ask_user` tool. Omit it to retain the legacy SDK behavior.
+
 When `onElicitationRequest` is provided, the SDK sends `requestElicitation: true` during session create/resume, which enables `session.capabilities.ui.elicitation` on the session.
 
 In multi-client scenarios:

package/dist/cjs/client.js

@@ -294,6 +294,7 @@ class CopilotClient {
   builtinPluginDirectories = [];
   onGitHubTelemetry;
   clientGlobalHandlers = {};
+  githubTokenProviders = /* @__PURE__ */ new Map();
   /**
    * Typed server-scoped RPC methods.
    * @throws Error if the client is not connected
@@ -551,8 +552,53 @@ class CopilotClient {
         }
       };
     }
+    handlers.gitHubToken = {
+      getToken: (params) => this.acquireGitHubToken(params)
+    };
     this.clientGlobalHandlers = handlers;
   }
+  async acquireGitHubToken(params) {
+    const registration = this.githubTokenProviders.get(params.registrationId);
+    if (!registration) {
+      throw new Error(
+        `No GitHub token provider registered for registration ID "${params.registrationId}"`
+      );
+    }
+    return await registration.provider({
+      host: params.host,
+      sessionId: params.sessionId ?? registration.sessionId,
+      reason: params.reason
+    });
+  }
+  registerGitHubTokenProvider(provider, sessionId) {
+    if (!provider) {
+      return void 0;
+    }
+    const registrationId = (0, import_node_crypto.randomUUID)();
+    this.githubTokenProviders.set(registrationId, { provider, sessionId, committed: false });
+    return registrationId;
+  }
+  assignGitHubTokenProvider(registrationId, sessionId) {
+    if (!registrationId) {
+      return;
+    }
+    const registration = this.githubTokenProviders.get(registrationId);
+    if (registration) {
+      registration.sessionId = sessionId;
+    }
+  }
+  commitGitHubTokenProvider(sessionId, registrationId) {
+    for (const [candidateId, registration2] of this.githubTokenProviders) {
+      if (registration2.sessionId === sessionId && registration2.committed) {
+        this.githubTokenProviders.delete(candidateId);
+      }
+    }
+    const registration = registrationId ? this.githubTokenProviders.get(registrationId) : void 0;
+    if (registration) {
+      registration.sessionId = sessionId;
+      registration.committed = true;
+    }
+  }
   /**
    * Starts the CLI server and establishes a connection.
    *
@@ -669,6 +715,7 @@ class CopilotClient {
       session._markDisconnected();
     }
     this.sessions.clear();
+    this.githubTokenProviders.clear();
     if (this.connection && (this.cliProcess || this.ffiHost) && !this.isExternalServer) {
       const runtimeShutdownStart = Date.now();
       const shutdownPromise = this.rpc.runtime.shutdown();
@@ -823,6 +870,7 @@ class CopilotClient {
       session._markDisconnected();
     }
     this.sessions.clear();
+    this.githubTokenProviders.clear();
     if (this.messageWriter) {
       this.messageWriter.suppressWriteErrors = true;
     }
@@ -1026,6 +1074,9 @@ class CopilotClient {
     }
   }
   async createSession(config) {
+    if (config.gitHubToken !== void 0 && config.gitHubTokenProvider !== void 0) {
+      throw new Error("gitHubToken and gitHubTokenProvider are mutually exclusive");
+    }
     if (!this.connection) {
       await this.start();
     }
@@ -1036,6 +1087,11 @@ class CopilotClient {
     const callerSessionId = config.sessionId;
     const useServerGeneratedId = config.cloud != null && callerSessionId == null;
     const localSessionId = useServerGeneratedId ? void 0 : callerSessionId ?? (0, import_node_crypto.randomUUID)();
+    const toolFilterOptions = this.resolveToolFilterOptions(config);
+    const gitHubTokenProviderRegistrationId = this.registerGitHubTokenProvider(
+      config.gitHubTokenProvider,
+      localSessionId
+    );
     const {
       wireProvider: bearerWireProvider,
       wireProviders: bearerWireProviders,
@@ -1052,7 +1108,10 @@ class CopilotClient {
         this.onGetTraceContext,
         {
           mcpAuthHandler: config.onMcpAuthRequest,
-          managedSettingsEnabled: config.enableManagedSettings === true || config.managedSettings !== void 0
+          managedSettingsEnabled: config.enableManagedSettings === true || config.managedSettings !== void 0,
+          onDisconnected: gitHubTokenProviderRegistrationId === void 0 ? void 0 : () => this.githubTokenProviders.delete(
+            gitHubTokenProviderRegistrationId
+          )
         }
       );
       s.registerTools(config.tools);
@@ -1090,10 +1149,16 @@ class CopilotClient {
     let session;
     let registeredId;
     if (localSessionId !== void 0) {
-      session = initializeSession(localSessionId);
-      registeredId = localSessionId;
+      try {
+        session = initializeSession(localSessionId);
+        registeredId = localSessionId;
+      } catch (error) {
+        if (gitHubTokenProviderRegistrationId !== void 0) {
+          this.githubTokenProviders.delete(gitHubTokenProviderRegistrationId);
+        }
+        throw error;
+      }
     }
-    const toolFilterOptions = this.resolveToolFilterOptions(config);
     try {
       const response = await this.connection.sendRequest("session.create", {
         ...await (0, import_telemetry.getTraceContext)(this.onGetTraceContext),
@@ -1143,6 +1208,7 @@ class CopilotClient {
         requestPermission: !!config.onPermissionRequest,
         requestUserInput: !!config.onUserInputRequest,
         requestElicitation: !!config.onElicitationRequest,
+        askUserVariant: config.askUserVariant,
         ...config.enableMcpApps ? { requestMcpApps: true } : {},
         ...config.githubMcpToolConfig != null ? { githubMcpToolConfig: config.githubMcpToolConfig } : {},
         requestExitPlanMode: !!config.onExitPlanModeRequest,
@@ -1178,6 +1244,7 @@ class CopilotClient {
         infiniteSessions: config.infiniteSessions,
         memory: config.memory,
         gitHubToken: config.gitHubToken,
+        gitHubTokenProviderRegistrationId,
         remoteSession: config.remoteSession,
         cloud: config.cloud,
         expAssignments: config.expAssignments,
@@ -1201,6 +1268,7 @@ class CopilotClient {
         session = initializeSession(returnedSessionId);
         registeredId = returnedSessionId;
       }
+      this.assignGitHubTokenProvider(gitHubTokenProviderRegistrationId, returnedSessionId);
       if (config.onMcpAuthRequest) {
         await this.connection.sendRequest("session.eventLog.registerInterest", {
           sessionId: returnedSessionId,
@@ -1210,10 +1278,14 @@ class CopilotClient {
       session["_workspacePath"] = workspacePath;
       session.setCapabilities(capabilities);
       await this.updateSessionOptionsForMode(session, config);
+      this.commitGitHubTokenProvider(returnedSessionId, gitHubTokenProviderRegistrationId);
     } catch (e) {
       if (registeredId !== void 0) {
         this.sessions.delete(registeredId);
       }
+      if (gitHubTokenProviderRegistrationId !== void 0) {
+        this.githubTokenProviders.delete(gitHubTokenProviderRegistrationId);
+      }
       throw e;
     }
     return session;
@@ -1250,6 +1322,9 @@ class CopilotClient {
     return this.resumeSessionInternal(sessionId, config, factories, extensionOptions);
   }
   async resumeSessionInternal(sessionId, config, factories, extensionOptions) {
+    if (config.gitHubToken !== void 0 && config.gitHubTokenProvider !== void 0) {
+      throw new Error("gitHubToken and gitHubTokenProvider are mutually exclusive");
+    }
     if (!this.connection) {
       await this.start();
     }
@@ -1307,6 +1382,15 @@ class CopilotClient {
     this.sessions.set(sessionId, session);
     this.setupSessionFs(session, config);
     const toolFilterOptions = this.resolveToolFilterOptions(config);
+    const gitHubTokenProviderRegistrationId = this.registerGitHubTokenProvider(
+      config.gitHubTokenProvider,
+      sessionId
+    );
+    if (gitHubTokenProviderRegistrationId !== void 0) {
+      session._setOnDisconnected(
+        () => this.githubTokenProviders.delete(gitHubTokenProviderRegistrationId)
+      );
+    }
     try {
       const response = await this.connection.sendRequest("session.resume", {
         ...await (0, import_telemetry.getTraceContext)(this.onGetTraceContext),
@@ -1357,6 +1441,7 @@ class CopilotClient {
         requestPermission: config.onPermissionRequest !== import_types.defaultJoinSessionPermissionHandler,
         requestUserInput: !!config.onUserInputRequest,
         requestElicitation: !!config.onElicitationRequest,
+        askUserVariant: config.askUserVariant,
         ...config.enableMcpApps ? { requestMcpApps: true } : {},
         ...config.githubMcpToolConfig != null ? { githubMcpToolConfig: config.githubMcpToolConfig } : {},
         requestExitPlanMode: !!config.onExitPlanModeRequest,
@@ -1394,6 +1479,7 @@ class CopilotClient {
         disableResume: config.suppressResumeEvent,
         continuePendingWork: config.continuePendingWork,
         gitHubToken: config.gitHubToken,
+        gitHubTokenProviderRegistrationId,
         remoteSession: config.remoteSession,
         openCanvases: config.openCanvases,
         expAssignments: config.expAssignments,
@@ -1423,8 +1509,12 @@ class CopilotClient {
         });
       }
       await this.updateSessionOptionsForMode(session, config);
+      this.commitGitHubTokenProvider(sessionId, gitHubTokenProviderRegistrationId);
     } catch (e) {
       this.sessions.delete(sessionId);
+      if (gitHubTokenProviderRegistrationId !== void 0) {
+        this.githubTokenProviders.delete(gitHubTokenProviderRegistrationId);
+      }
       throw e;
     }
     return session;
@@ -1613,7 +1703,9 @@ class CopilotClient {
     if (!success) {
       throw new Error(`Failed to delete session ${sessionId}: ${error || "Unknown error"}`);
     }
+    const session = this.sessions.get(sessionId);
     this.sessions.delete(sessionId);
+    session?._runOnDisconnected();
   }
   /**
    * List all available sessions.
@@ -2161,6 +2253,7 @@ stderr: ${stderrOutput}`
     );
     this.connection.onClose(() => {
       this.state = "disconnected";
+      this.githubTokenProviders.clear();
     });
     this.connection.onError((_error) => {
       this.state = "disconnected";

package/dist/cjs/generated/rpc.js

@@ -200,7 +200,7 @@ function createServerRpc(connection) {
       disable: async (params) => connection.sendRequest("extensions.disable", params)
     },
     /**
-     * Registers the calling SDK client as the per-entrypoint extension launch provider. Call before creating any sessions. When omitted, the runtime temporarily falls back to its built-in Node launcher for backward compatibility.
+     * Registers the calling SDK client as the per-entrypoint extension launch provider. Call before creating any sessions. When omitted, the runtime uses its built-in extension launcher.
      *
      * @experimental
      */
@@ -773,6 +773,15 @@ function createSessionRpc(connection, sessionId) {
      * @experimental
      */
     sendMessages: async (params) => connection.sendRequest("session.sendMessages", { sessionId, ...params }),
+    /** @experimental */
+    sandbox: {
+      /**
+       * Returns whether managed policy requires sandbox enforcement and whether an enforcement failure has permanently blocked the session.
+       *
+       * @returns Managed sandbox enforcement state for a session.
+       */
+      getEnforcementStatus: async () => connection.sendRequest("session.sandbox.getEnforcementStatus", { sessionId })
+    },
     /**
      * Aborts the current agent turn.
      *
@@ -2540,6 +2549,25 @@ function createInternalSessionRpc(connection, sessionId) {
       }
     },
     /** @experimental */
+    factory: {
+      /**
+       * Internal tool-originated factory invocation.
+       *
+       * @param params Internal parameters for invoking a registered factory from a tool.
+       *
+       * @returns Complete current or terminal factory run envelope.
+       */
+      runFromTool: async (params) => connection.sendRequest("session.factory.runFromTool", { sessionId, ...params }),
+      /**
+       * Internal tool-originated factory resume.
+       *
+       * @param params Internal parameters for resuming a factory run from a tool.
+       *
+       * @returns Resolved persisted factory identity and resumed run envelope.
+       */
+      resumeFromTool: async (params) => connection.sendRequest("session.factory.resumeFromTool", { sessionId, ...params })
+    },
+    /** @experimental */
     model: {
       /**
        * Resolves and applies organization-managed and repository model overlays.

package/dist/cjs/session.js

@@ -241,6 +241,7 @@ class CopilotSession {
     this.traceContextProvider = traceContextProvider;
     this.mcpAuthHandler = options?.mcpAuthHandler;
     this.managedSettingsEnabled = options?.managedSettingsEnabled === true;
+    this.onDisconnected = options?.onDisconnected;
   }
   sessionId;
   connection;
@@ -267,6 +268,7 @@ class CopilotSession {
   _capabilities = {};
   openCanvasInstances = [];
   disconnected = false;
+  onDisconnected;
   /** @internal Client session API handlers, populated by CopilotClient during create/resume. */
   clientSessionApis = {};
   /**
@@ -281,14 +283,18 @@ class CopilotSession {
       const name = typeof nameOrHandle === "string" ? nameOrHandle : (0, import_factory.getFactoryDefinition)(nameOrHandle).meta.name;
       if (options?.resumeFromRunId !== void 0) {
         return this.factory.resume(options.resumeFromRunId, {
-          limits: options.limits
+          limits: options.limits,
+          notifyOnComplete: options.notifyOnComplete,
+          logPhaseNames: options.logPhaseNames
         });
       }
       const envelope = await this.rpc.factory.run({
         name,
         args: options?.args === void 0 ? {} : options.args,
         options: {
-          limits: options?.limits
+          limits: options?.limits,
+          notifyOnComplete: options?.notifyOnComplete,
+          logPhaseNames: options?.logPhaseNames
         }
       });
       return this.settleFactoryRun(envelope);
@@ -299,7 +305,9 @@ class CopilotSession {
       try {
         response = await this.rpc.factory.resume({
           runId,
-          limits: options?.limits
+          limits: options?.limits,
+          notifyOnComplete: options?.notifyOnComplete,
+          logPhaseNames: options?.logPhaseNames
         });
       } catch (error) {
         if (error instanceof import_node.ResponseError && typeof error.data === "object" && error.data !== null) {
@@ -314,7 +322,10 @@ class CopilotSession {
     }),
     getRun: async (runId) => this.rpc.factory.getRun({ runId }),
     waitForRun: (runId, options) => this.waitForFactoryRun(runId, options?.signal),
-    listRuns: async () => (await this.rpc.factory.listRuns({})).runs,
+    listRuns: (async (options) => {
+      const page = await this.rpc.factory.listRuns(options ?? {});
+      return options === void 0 ? page.runs : page;
+    }),
     getRunDetail: (runId) => this.rpc.factory.getRunDetail({ runId }),
     getRunProgress: (runId, options = {}) => this.rpc.factory.getRunProgress({ runId, ...options }),
     cancel: async (runId) => this.rpc.factory.cancel({ runId })
@@ -475,7 +486,7 @@ class CopilotSession {
     const unsubscribe = this.on((event) => {
       if (event.type === "assistant.message") {
         lastAssistantMessage = event;
-      } else if (event.type === "session.idle") {
+      } else if (event.type === "session.idle" && event.data.mode !== "autopilot") {
         resolveOutcome({ kind: "idle" });
       } else if (event.type === "session.error") {
         const error = new Error(event.data.message);
@@ -510,7 +521,11 @@ class CopilotSession {
   }
   /** @internal */
   _markDisconnected() {
+    if (this.disconnected) {
+      return;
+    }
     this.disconnected = true;
+    this._runOnDisconnected();
     this.eventHandlers.clear();
     this.typedEventHandlers.clear();
     this.toolHandlers.clear();
@@ -530,6 +545,15 @@ class CopilotSession {
     this.factoryAbortControllers.clear();
     this.transformCallbacks?.clear();
   }
+  /** @internal */
+  _runOnDisconnected() {
+    this.onDisconnected?.();
+    this.onDisconnected = void 0;
+  }
+  /** @internal */
+  _setOnDisconnected(callback) {
+    this.onDisconnected = callback;
+  }
   on(eventTypeOrHandler, handler) {
     if (typeof eventTypeOrHandler === "string" && handler) {
       const eventType = eventTypeOrHandler;

package/dist/client.d.ts

@@ -40,6 +40,7 @@ export declare class CopilotClient {
     private builtinPluginDirectories;
     private onGitHubTelemetry?;
     private clientGlobalHandlers;
+    private githubTokenProviders;
     /**
      * Typed server-scoped RPC methods.
      * @throws Error if the client is not connected
@@ -96,6 +97,10 @@ export declare class CopilotClient {
     private validateSessionFsConfig;
     private setupSessionFs;
     private setupClientGlobalHandlers;
+    private acquireGitHubToken;
+    private registerGitHubTokenProvider;
+    private assignGitHubTokenProvider;
+    private commitGitHubTokenProvider;
     /**
      * Starts the CLI server and establishes a connection.
      *