@github/copilot-sdk 1.0.9-preview.2 → 1.0.9-preview.3

package/README.md

@@ -36,7 +36,7 @@ import { CopilotClient, approveAll } from "@github/copilot-sdk";
 const client = new CopilotClient();
 await client.start();
 
-// Create a session (onPermissionRequest is optional; approveAll allows every tool)
+// approveAll is only valid when managed settings are disabled.
 const session = await client.createSession({
     model: "gpt-5",
     onPermissionRequest: approveAll,
@@ -137,7 +137,7 @@ Create a new conversation session.
 - `infiniteSessions?: InfiniteSessionConfig` - Configure automatic context compaction (see below)
 - `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.
 - `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. Use `approveAll` to allow everything, or provide a custom function for fine-grained control. See [Permission Handling](#permission-handling) 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.
 - `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.
@@ -862,7 +862,7 @@ An `onPermissionRequest` handler is optional when you create or resume a session
 
 ### Approve All (simplest)
 
-Use the built-in `approveAll` helper to allow every tool call without any checks:
+Use the built-in `approveAll` helper when managed settings are disabled:
 
 ```typescript
 import { CopilotClient, approveAll } from "@github/copilot-sdk";
@@ -873,9 +873,11 @@ const session = await client.createSession({
 });
 ```
 
+When `enableManagedSettings` is true for the session, `approveAll` throws. Use a custom handler for managed sessions; request-level `managedApprovalRequired` remains available for human-facing confirmation logic.
+
 ### Custom Permission Handler
 
-Provide your own function to inspect each request and apply custom logic:
+Provide your own function to inspect each request and apply custom logic. Check `managedApprovalRequired` before any automatic approval:
 
 ```typescript
 import type { PermissionRequest, PermissionRequestResult } from "@github/copilot-sdk";
@@ -883,6 +885,11 @@ import type { PermissionRequest, PermissionRequestResult } from "@github/copilot
 const session = await client.createSession({
     model: "gpt-5",
     onPermissionRequest: (request: PermissionRequest, invocation): PermissionRequestResult => {
+        if ("managedApprovalRequired" in request && request.managedApprovalRequired === true) {
+            // Leave the request pending for the host's human-facing confirmation flow.
+            return { kind: "no-result" };
+        }
+
         // request.kind — what type of operation is being requested:
         //   "shell"       — executing a shell command
         //   "write"       — writing or editing a file
@@ -920,7 +927,7 @@ The handler must return one of the `PermissionDecision` shapes (or `{ kind: "no-
 | `"approve-permanently"`  | Allow this request and persist the approval across sessions (currently used for URL domains) | `domain` (URL domain to approve)                                        |
 | `"reject"`               | Deny the request                                                                             | `feedback?` (optional string surfaced to the agent)                     |
 | `"user-not-available"`   | Deny the request because no user is available to confirm it                                  | —                                                                       |
-| `"no-result"`            | Leave the request unanswered (only valid with protocol v1; rejected by protocol v2 servers)  | —                                                                       |
+| `"no-result"`            | Suppress this SDK client's response so another connected client can answer the pending request | —                                                                     |
 
 ### Resuming Sessions
 

package/dist/cjs/client.js

@@ -920,6 +920,10 @@ class CopilotClient {
     }
     return {};
   }
+  /** Mode-specific default for enableExperimentalMode. */
+  experimentalModeForMode(supplied) {
+    return this.options.mode === "empty" ? supplied ?? false : supplied;
+  }
   /**
    * Returns the systemMessage config to use, adjusted for the current mode.
    * In empty mode we ensure the environment_context section is removed
@@ -1021,7 +1025,10 @@ class CopilotClient {
         this.connection,
         void 0,
         this.onGetTraceContext,
-        { mcpAuthHandler: config.onMcpAuthRequest }
+        {
+          mcpAuthHandler: config.onMcpAuthRequest,
+          managedSettingsEnabled: config.enableManagedSettings
+        }
       );
       s.registerTools(config.tools);
       s.registerCanvases(config.canvases);
@@ -1070,6 +1077,7 @@ class CopilotClient {
         clientName: config.clientName,
         reasoningEffort: config.reasoningEffort,
         reasoningSummary: config.reasoningSummary,
+        isExperimentalMode: this.experimentalModeForMode(config.enableExperimentalMode),
         contextTier: config.contextTier,
         tools: config.tools?.map((tool) => ({
           name: tool.name,
@@ -1109,10 +1117,12 @@ class CopilotClient {
         requestUserInput: !!config.onUserInputRequest,
         requestElicitation: !!config.onElicitationRequest,
         ...config.enableMcpApps ? { requestMcpApps: true } : {},
+        ...config.githubMcpToolConfig != null ? { githubMcpToolConfig: config.githubMcpToolConfig } : {},
         requestExitPlanMode: !!config.onExitPlanModeRequest,
         requestAutoModeSwitch: !!config.onAutoModeSwitchRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
         workingDirectory: config.workingDirectory,
+        additionalDirectories: config.additionalDirectories,
         streaming: config.streaming,
         includeSubAgentStreamingEvents: config.includeSubAgentStreamingEvents ?? true,
         ...this.onGitHubTelemetry != null ? { enableGitHubTelemetryForwarding: true } : {},
@@ -1219,7 +1229,10 @@ class CopilotClient {
       this.connection,
       void 0,
       this.onGetTraceContext,
-      { mcpAuthHandler: config.onMcpAuthRequest }
+      {
+        mcpAuthHandler: config.onMcpAuthRequest,
+        managedSettingsEnabled: config.enableManagedSettings
+      }
     );
     session.registerTools(config.tools);
     session.registerCanvases(config.canvases);
@@ -1273,6 +1286,7 @@ class CopilotClient {
         model: config.model,
         reasoningEffort: config.reasoningEffort,
         reasoningSummary: config.reasoningSummary,
+        isExperimentalMode: this.experimentalModeForMode(config.enableExperimentalMode),
         contextTier: config.contextTier,
         systemMessage: wireSystemMessage,
         availableTools: toolFilterOptions.availableTools,
@@ -1313,10 +1327,12 @@ class CopilotClient {
         requestUserInput: !!config.onUserInputRequest,
         requestElicitation: !!config.onElicitationRequest,
         ...config.enableMcpApps ? { requestMcpApps: true } : {},
+        ...config.githubMcpToolConfig != null ? { githubMcpToolConfig: config.githubMcpToolConfig } : {},
         requestExitPlanMode: !!config.onExitPlanModeRequest,
         requestAutoModeSwitch: !!config.onAutoModeSwitchRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
         workingDirectory: config.workingDirectory,
+        additionalDirectories: config.additionalDirectories,
         configDir: config.configDirectory,
         enableConfigDiscovery: config.enableConfigDiscovery,
         skipEmbeddingRetrieval: config.skipEmbeddingRetrieval,

package/dist/cjs/generated/rpc.js

@@ -171,6 +171,27 @@ function createServerRpc(connection) {
       discover: async (params) => connection.sendRequest("mcp.discover", params)
     },
     /** @experimental */
+    extensions: {
+      /**
+       * Discovers user and enabled installed-plugin extensions from persisted Copilot home state, including enablement preferences. Launch-scoped additional plugins are not included.
+       *
+       * @returns Extensions discovered from persisted Copilot home state and their effective loading mode. Launch-scoped additional plugins are not included.
+       */
+      discover: async () => connection.sendRequest("extensions.discover", {}),
+      /**
+       * Persistently enables extension IDs for future sessions. Active sessions are unchanged; use session.extensions.enable to update them.
+       *
+       * @param params Source-qualified extension identifiers to persistently enable for future sessions.
+       */
+      enable: async (params) => connection.sendRequest("extensions.enable", params),
+      /**
+       * Persistently disables extension IDs for future sessions. Active sessions are unchanged; use session.extensions.disable to update them.
+       *
+       * @param params Source-qualified extension identifiers to persistently disable for future sessions.
+       */
+      disable: async (params) => connection.sendRequest("extensions.disable", params)
+    },
+    /** @experimental */
     plugins: {
       /**
        * Lists plugins installed in user/global state.
@@ -1165,6 +1186,12 @@ function createSessionRpc(connection, sessionId) {
        * @returns Agents available to the session.
        */
       list: async (params) => connection.sendRequest("session.agent.list", { sessionId, ...params }),
+      /**
+       * Sets an in-memory authored prompt override for an available agent. For built-in agents, this replaces only the static base prompt while preserving runtime-owned dynamic prompt composition and behavior. The special `general-purpose` agent is not overrideable. Overrides are not persisted; resumed and forked sessions start without them, so the host must re-apply them.
+       *
+       * @param params An in-memory authored prompt override for an available agent.
+       */
+      setPrompt: async (params) => connection.sendRequest("session.agent.setPrompt", { sessionId, ...params }),
       /**
        * Gets the currently selected custom agent for the session.
        *
@@ -1406,6 +1433,12 @@ function createSessionRpc(connection, sessionId) {
          * @returns Indicates whether the pending MCP OAuth response was accepted.
          */
         handlePendingRequest: async (params) => connection.sendRequest("session.mcp.oauth.handlePendingRequest", { sessionId, ...params }),
+        /**
+         * Notifies the session that MCP OAuth authentication succeeded and updated credentials were persisted, so cached tool definitions can be refreshed.
+         *
+         * @param params Identifies the MCP server whose persisted OAuth credentials were updated.
+         */
+        authenticationStateChanged: async (params) => connection.sendRequest("session.mcp.oauth.authenticationStateChanged", { sessionId, ...params }),
         /**
          * Starts OAuth authentication for a remote MCP server.
          *
@@ -2129,7 +2162,15 @@ function createSessionRpc(connection, sessionId) {
        *
        * @returns Markdown summary of the conversation context (empty when not available).
        */
-      summarizeForHandoff: async () => connection.sendRequest("session.history.summarizeForHandoff", { sessionId })
+      summarizeForHandoff: async () => connection.sendRequest("session.history.summarizeForHandoff", { sessionId }),
+      /**
+       * Clears the session's conversation history, keeping only system and developer messages, and seeds the fresh context window with a first user message. Must be called from inside a tool handler: the clear has to drop the results of the tool calls its wipe orphans, and it rejects when no tool call is in flight.
+       *
+       * @param params Parameters for clearing the conversation and seeding the window that replaces it.
+       *
+       * @returns What a successful clear removed. A clear that could not be applied rejects instead of reporting a count.
+       */
+      clearContext: async (params) => connection.sendRequest("session.history.clearContext", { sessionId, ...params })
     },
     /** @experimental */
     queue: {
@@ -2207,7 +2248,7 @@ function createSessionRpc(connection, sessionId) {
     /** @experimental */
     eventLog: {
       /**
-       * Reads a batch of session events from a cursor, optionally waiting for new events.
+       * Reads a batch of session events from a cursor, optionally waiting for new events. Supports tail-first reads via `direction: backward`.
        *
        * @param params Cursor, batch size, and optional long-poll/filter parameters for reading session events.
        *

package/dist/cjs/session.js

@@ -224,6 +224,7 @@ class CopilotSession {
     this._workspacePath = _workspacePath;
     this.traceContextProvider = traceContextProvider;
     this.mcpAuthHandler = options?.mcpAuthHandler;
+    this.managedSettingsEnabled = options?.managedSettingsEnabled === true;
   }
   sessionId;
   connection;
@@ -246,6 +247,7 @@ class CopilotSession {
   transformCallbacks;
   _rpc = null;
   traceContextProvider;
+  managedSettingsEnabled;
   _capabilities = {};
   openCanvasInstances = [];
   disconnected = false;
@@ -272,7 +274,7 @@ class CopilotSession {
           limits: options?.limits
         }
       });
-      return toPublicFactoryRunResult(envelope);
+      return this.settleFactoryRun(envelope);
     }),
     resume: (async (runId, options) => {
       let response;
@@ -290,7 +292,7 @@ class CopilotSession {
         }
         throw error;
       }
-      return toPublicFactoryRunResult(response.run);
+      return this.settleFactoryRun(response.run);
     }),
     getRun: async (runId) => toPublicFactoryRunResult(await this.rpc.factory.getRun({ runId })),
     waitForRun: (runId, options) => this.waitForFactoryRun(runId, options?.signal),
@@ -299,6 +301,19 @@ class CopilotSession {
     getRunProgress: (runId, options = {}) => this.rpc.factory.getRunProgress({ runId, ...options }),
     cancel: async (runId) => toPublicFactoryRunResult(await this.rpc.factory.cancel({ runId }))
   };
+  /**
+   * Resolve a start/resume envelope into the terminal envelope callers expect.
+   *
+   * The CLI may answer `session.factory.run` and `session.factory.resume`
+   * before the run settles, so a non-terminal envelope is followed by a wait
+   * on the run's terminal state.
+   */
+  settleFactoryRun(envelope) {
+    if ((0, import_factory.isFactoryRunTerminal)(envelope.status)) {
+      return Promise.resolve(toPublicFactoryRunResult(envelope));
+    }
+    return this.waitForFactoryRun(envelope.runId);
+  }
   /**
    * Resolve when a factory run reaches a terminal status.
    *
@@ -704,7 +719,8 @@ class CopilotSession {
   async _executePermissionAndRespond(requestId, permissionRequest) {
     try {
       const result = await this.permissionHandler(permissionRequest, {
-        sessionId: this.sessionId
+        sessionId: this.sessionId,
+        managedSettingsEnabled: this.managedSettingsEnabled
       });
       if (result.kind === "no-result") {
         return;
@@ -713,10 +729,15 @@ class CopilotSession {
         return;
       }
       await this.rpc.permissions.handlePendingPermissionRequest({ requestId, result });
-    } catch (_error) {
+    } catch (error) {
       if (this.disconnected) {
         return;
       }
+      console.error("Permission handler or response delivery failed", {
+        sessionId: this.sessionId,
+        requestId,
+        error
+      });
       try {
         await this.rpc.permissions.handlePendingPermissionRequest({
           requestId,

package/dist/cjs/types.js

@@ -141,7 +141,18 @@ const SYSTEM_MESSAGE_SECTIONS = {
     description: "End-of-prompt instructions: parallel tool calling, persistence, task completion"
   }
 };
-const approveAll = () => ({ kind: "approve-once" });
+const approveAll = (request, invocation) => {
+  if (invocation.managedSettingsEnabled) {
+    throw new Error("approveAll cannot be used when managed settings are enabled");
+  }
+  if ("managedApprovalRequired" in request) {
+    const managedApprovalRequired = request.managedApprovalRequired;
+    if (managedApprovalRequired !== void 0 && managedApprovalRequired !== false) {
+      return { kind: "no-result" };
+    }
+  }
+  return { kind: "approve-once" };
+};
 const defaultJoinSessionPermissionHandler = () => ({
   kind: "no-result"
 });

package/dist/client.d.ts

@@ -180,6 +180,8 @@ export declare class CopilotClient {
     forceStop(): Promise<void>;
     /** Mode-specific defaults spread under the caller's config (app values win). */
     private configDefaultsForMode;
+    /** Mode-specific default for enableExperimentalMode. */
+    private experimentalModeForMode;
     /**
      * Returns the systemMessage config to use, adjusted for the current mode.
      * In empty mode we ensure the environment_context section is removed

package/dist/client.js

@@ -897,6 +897,10 @@ class CopilotClient {
     }
     return {};
   }
+  /** Mode-specific default for enableExperimentalMode. */
+  experimentalModeForMode(supplied) {
+    return this.options.mode === "empty" ? supplied ?? false : supplied;
+  }
   /**
    * Returns the systemMessage config to use, adjusted for the current mode.
    * In empty mode we ensure the environment_context section is removed
@@ -998,7 +1002,10 @@ class CopilotClient {
         this.connection,
         void 0,
         this.onGetTraceContext,
-        { mcpAuthHandler: config.onMcpAuthRequest }
+        {
+          mcpAuthHandler: config.onMcpAuthRequest,
+          managedSettingsEnabled: config.enableManagedSettings
+        }
       );
       s.registerTools(config.tools);
       s.registerCanvases(config.canvases);
@@ -1047,6 +1054,7 @@ class CopilotClient {
         clientName: config.clientName,
         reasoningEffort: config.reasoningEffort,
         reasoningSummary: config.reasoningSummary,
+        isExperimentalMode: this.experimentalModeForMode(config.enableExperimentalMode),
         contextTier: config.contextTier,
         tools: config.tools?.map((tool) => ({
           name: tool.name,
@@ -1086,10 +1094,12 @@ class CopilotClient {
         requestUserInput: !!config.onUserInputRequest,
         requestElicitation: !!config.onElicitationRequest,
         ...config.enableMcpApps ? { requestMcpApps: true } : {},
+        ...config.githubMcpToolConfig != null ? { githubMcpToolConfig: config.githubMcpToolConfig } : {},
         requestExitPlanMode: !!config.onExitPlanModeRequest,
         requestAutoModeSwitch: !!config.onAutoModeSwitchRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
         workingDirectory: config.workingDirectory,
+        additionalDirectories: config.additionalDirectories,
         streaming: config.streaming,
         includeSubAgentStreamingEvents: config.includeSubAgentStreamingEvents ?? true,
         ...this.onGitHubTelemetry != null ? { enableGitHubTelemetryForwarding: true } : {},
@@ -1196,7 +1206,10 @@ class CopilotClient {
       this.connection,
       void 0,
       this.onGetTraceContext,
-      { mcpAuthHandler: config.onMcpAuthRequest }
+      {
+        mcpAuthHandler: config.onMcpAuthRequest,
+        managedSettingsEnabled: config.enableManagedSettings
+      }
     );
     session.registerTools(config.tools);
     session.registerCanvases(config.canvases);
@@ -1250,6 +1263,7 @@ class CopilotClient {
         model: config.model,
         reasoningEffort: config.reasoningEffort,
         reasoningSummary: config.reasoningSummary,
+        isExperimentalMode: this.experimentalModeForMode(config.enableExperimentalMode),
         contextTier: config.contextTier,
         systemMessage: wireSystemMessage,
         availableTools: toolFilterOptions.availableTools,
@@ -1290,10 +1304,12 @@ class CopilotClient {
         requestUserInput: !!config.onUserInputRequest,
         requestElicitation: !!config.onElicitationRequest,
         ...config.enableMcpApps ? { requestMcpApps: true } : {},
+        ...config.githubMcpToolConfig != null ? { githubMcpToolConfig: config.githubMcpToolConfig } : {},
         requestExitPlanMode: !!config.onExitPlanModeRequest,
         requestAutoModeSwitch: !!config.onAutoModeSwitchRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
         workingDirectory: config.workingDirectory,
+        additionalDirectories: config.additionalDirectories,
         configDir: config.configDirectory,
         enableConfigDiscovery: config.enableConfigDiscovery,
         skipEmbeddingRetrieval: config.skipEmbeddingRetrieval,