@github/copilot-sdk 1.0.0-beta.8 → 1.0.0

package/dist/client.js

@@ -21,6 +21,7 @@ import { getSdkProtocolVersion } from "./sdkProtocolVersion.js";
 import { CopilotSession } from "./session.js";
 import { createSessionFsAdapter } from "./sessionFsProvider.js";
 import { getTraceContext } from "./telemetry.js";
+import { ToolSet } from "./toolSet.js";
 import { defaultJoinSessionPermissionHandler } from "./types.js";
 const MIN_PROTOCOL_VERSION = 3;
 function isZodSchema(value) {
@@ -53,6 +54,33 @@ function toWireCustomAgents(agents) {
     return { ...rest, mcpServers: toWireMcpServers(mcpServers) };
   });
 }
+function toWireLargeOutput(config) {
+  if (!config) return void 0;
+  const { outputDirectory, ...rest } = config;
+  const wire = { ...rest };
+  if (outputDirectory !== void 0) {
+    wire.outputDir = outputDirectory;
+  }
+  return wire;
+}
+function toolFilterListToArray(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return value instanceof ToolSet ? value.toArray() : value;
+}
+function validateToolFilterList(field, list) {
+  if (!list) {
+    return;
+  }
+  for (const entry of list) {
+    if (entry === "*") {
+      throw new Error(
+        `Invalid ${field} entry '*': there is no bare wildcard. Use one or more of \`new ToolSet().addBuiltIn('*')\`, \`.addMcp('*')\`, or \`.addCustom('*')\` to target a specific source.`
+      );
+    }
+  }
+}
 function extractTransformCallbacks(systemMessage) {
   if (!systemMessage || systemMessage.mode !== "customize" || !systemMessage.sections) {
     return { wirePayload: systemMessage, transformCallbacks: void 0 };
@@ -235,8 +263,19 @@ class CopilotClient {
       telemetry: options.telemetry,
       baseDirectory: options.baseDirectory,
       sessionIdleTimeoutSeconds: options.sessionIdleTimeoutSeconds ?? 0,
-      enableRemoteSessions: options.enableRemoteSessions ?? false
+      enableRemoteSessions: options.enableRemoteSessions ?? false,
+      mode: options.mode ?? "copilot-cli"
     };
+    if (this.options.mode === "empty") {
+      const hasPersistence = this.options.baseDirectory !== void 0 || this.sessionFsConfig !== null || // External runtimes manage their own persistence layer; the SDK
+      // can't enforce it from here.
+      conn.kind === "uri" || conn.kind === "parent-process";
+      if (!hasPersistence) {
+        throw new Error(
+          "CopilotClient was created with mode: 'empty' but neither 'baseDirectory' nor 'sessionFs' was set. Empty mode requires an explicit per-session persistence location; pick one."
+        );
+      }
+    }
   }
   connectionExtraArgs = [];
   /**
@@ -546,54 +585,190 @@ class CopilotClient {
    * });
    * ```
    */
-  async createSession(config) {
-    if (!this.connection) {
-      await this.start();
+  /**
+   * Normalizes session-level tool filter options. Converts {@link ToolSet}
+   * instances to plain string arrays, rejects misuse (bare `"*"`) and the
+   * missing-availableTools case in `mode = "empty"`.
+   *
+   * The SDK always sends `toolFilterPrecedence: "excluded"` so callers can
+   * compose include + exclude lists naturally (e.g. "everything matching X
+   * except Y") regardless of mode. Allowlist-precedence is intentionally not
+   * exposed — it's available on the runtime side as a CLI-only concession to
+   * legacy behavior, but SDK consumers always get the composable semantics.
+   *
+   * @internal
+   */
+  resolveToolFilterOptions(config) {
+    const availableTools = toolFilterListToArray(config.availableTools);
+    const excludedTools = toolFilterListToArray(config.excludedTools);
+    validateToolFilterList("availableTools", availableTools);
+    validateToolFilterList("excludedTools", excludedTools);
+    if (this.options.mode === "empty") {
+      if (availableTools === void 0) {
+        throw new Error(
+          "CopilotClient is in mode: 'empty' but the session config did not specify 'availableTools'. Empty mode requires every session to explicitly opt into the tools it wants \u2014 e.g. `new ToolSet().addBuiltIn(BuiltInTools.Isolated)`."
+        );
+      }
     }
-    const sessionId = config.sessionId ?? randomUUID();
-    const session = new CopilotSession(
-      sessionId,
-      this.connection,
-      void 0,
-      this.onGetTraceContext
-    );
-    session.registerTools(config.tools);
-    session.registerCanvases(config.canvases);
-    session.registerCommands(config.commands);
-    session.registerPermissionHandler(config.onPermissionRequest);
-    if (config.onUserInputRequest) {
-      session.registerUserInputHandler(config.onUserInputRequest);
+    return { availableTools, excludedTools, toolFilterPrecedence: "excluded" };
+  }
+  /** Mode-specific defaults spread under the caller's config (app values win). */
+  configDefaultsForMode() {
+    if (this.options.mode === "empty") {
+      return {
+        enableSessionTelemetry: false,
+        mcpOAuthTokenStorage: "in-memory",
+        skipEmbeddingRetrieval: true,
+        embeddingCacheStorage: "in-memory",
+        enableOnDemandInstructionDiscovery: false,
+        enableFileHooks: false,
+        enableHostGitOperations: false,
+        enableSessionStore: false,
+        enableSkills: false
+      };
     }
-    if (config.onElicitationRequest) {
-      session.registerElicitationHandler(config.onElicitationRequest);
+    return {};
+  }
+  /**
+   * Returns the systemMessage config to use, adjusted for the current mode.
+   * In empty mode we ensure the environment_context section is removed
+   * unless the app has already taken control of it. `append` (and
+   * unspecified) mode is promoted to `customize` so we can also strip
+   * environment_context; the caller's `content` is preserved verbatim
+   * because the runtime appends it as additional instructions in both
+   * customize and append modes.
+   */
+  getSystemMessageConfigForMode(supplied) {
+    if (this.options.mode !== "empty") return supplied;
+    if (!supplied) {
+      return {
+        mode: "customize",
+        sections: { environment_context: { action: "remove" } }
+      };
     }
-    if (config.onExitPlanModeRequest) {
-      session.registerExitPlanModeHandler(config.onExitPlanModeRequest);
+    switch (supplied.mode) {
+      case "replace":
+        return supplied;
+      case "customize":
+        if (supplied.sections?.environment_context) return supplied;
+        return {
+          ...supplied,
+          sections: {
+            ...supplied.sections,
+            environment_context: { action: "remove" }
+          }
+        };
+      case "append":
+      case void 0:
+        return {
+          mode: "customize",
+          content: supplied.content,
+          sections: { environment_context: { action: "remove" } }
+        };
     }
-    if (config.onAutoModeSwitchRequest) {
-      session.registerAutoModeSwitchHandler(config.onAutoModeSwitchRequest);
+  }
+  /**
+   * Mode-specific options applied via session.options.update after create/resume.
+   *
+   * In empty mode, defaults the four overridable feature flags to safe values
+   * (caller values from `config` win). `installedPlugins=[]` is unconditional
+   * in empty mode — apps that need custom plugins should switch modes.
+   */
+  async updateSessionOptionsForMode(session, config) {
+    const patch = {};
+    if (this.options.mode === "empty") {
+      patch.skipCustomInstructions = config.skipCustomInstructions ?? true;
+      patch.customAgentsLocalOnly = config.customAgentsLocalOnly ?? true;
+      patch.coauthorEnabled = config.coauthorEnabled ?? false;
+      patch.manageScheduleEnabled = config.manageScheduleEnabled ?? false;
+      patch.installedPlugins = [];
+    } else {
+      if (config.skipCustomInstructions !== void 0)
+        patch.skipCustomInstructions = config.skipCustomInstructions;
+      if (config.customAgentsLocalOnly !== void 0)
+        patch.customAgentsLocalOnly = config.customAgentsLocalOnly;
+      if (config.coauthorEnabled !== void 0)
+        patch.coauthorEnabled = config.coauthorEnabled;
+      if (config.manageScheduleEnabled !== void 0)
+        patch.manageScheduleEnabled = config.manageScheduleEnabled;
+    }
+    if (Object.keys(patch).length === 0) {
+      return;
     }
-    if (config.hooks) {
-      session.registerHooks(config.hooks);
+    try {
+      await session.rpc.options.update(patch);
+    } catch (e) {
+      try {
+        await session.disconnect();
+      } catch {
+      }
+      throw e;
+    }
+  }
+  async createSession(config) {
+    if (!this.connection) {
+      await this.start();
     }
+    config = { ...this.configDefaultsForMode(), ...config };
+    config.systemMessage = this.getSystemMessageConfigForMode(config.systemMessage);
+    const callerSessionId = config.sessionId;
+    const useServerGeneratedId = config.cloud != null && callerSessionId == null;
+    const localSessionId = useServerGeneratedId ? void 0 : callerSessionId ?? randomUUID();
     const { wirePayload: wireSystemMessage, transformCallbacks } = extractTransformCallbacks(
       config.systemMessage
     );
-    if (transformCallbacks) {
-      session.registerTransformCallbacks(transformCallbacks);
-    }
-    if (config.onEvent) {
-      session.on(config.onEvent);
+    const initializeSession = (sessionId) => {
+      const s = new CopilotSession(
+        sessionId,
+        this.connection,
+        void 0,
+        this.onGetTraceContext
+      );
+      s.registerTools(config.tools);
+      s.registerCanvases(config.canvases);
+      s.registerCommands(config.commands);
+      s.registerPermissionHandler(config.onPermissionRequest);
+      if (config.onUserInputRequest) {
+        s.registerUserInputHandler(config.onUserInputRequest);
+      }
+      if (config.onElicitationRequest) {
+        s.registerElicitationHandler(config.onElicitationRequest);
+      }
+      if (config.onExitPlanModeRequest) {
+        s.registerExitPlanModeHandler(config.onExitPlanModeRequest);
+      }
+      if (config.onAutoModeSwitchRequest) {
+        s.registerAutoModeSwitchHandler(config.onAutoModeSwitchRequest);
+      }
+      if (config.hooks) {
+        s.registerHooks(config.hooks);
+      }
+      if (transformCallbacks) {
+        s.registerTransformCallbacks(transformCallbacks);
+      }
+      if (config.onEvent) {
+        s.on(config.onEvent);
+      }
+      this.sessions.set(sessionId, s);
+      this.setupSessionFs(s, config);
+      return s;
+    };
+    let session;
+    let registeredId;
+    if (localSessionId !== void 0) {
+      session = initializeSession(localSessionId);
+      registeredId = localSessionId;
     }
-    this.sessions.set(sessionId, session);
-    this.setupSessionFs(session, config);
+    const toolFilterOptions = this.resolveToolFilterOptions(config);
     try {
       const response = await this.connection.sendRequest("session.create", {
         ...await getTraceContext(this.onGetTraceContext),
         model: config.model,
-        sessionId,
+        sessionId: localSessionId,
         clientName: config.clientName,
         reasoningEffort: config.reasoningEffort,
+        reasoningSummary: config.reasoningSummary,
+        contextTier: config.contextTier,
         tools: config.tools?.map((tool) => ({
           name: tool.name,
           description: tool.description,
@@ -604,20 +779,24 @@ class CopilotClient {
         canvases: config.canvases?.map((canvas) => canvas.declaration),
         requestCanvasRenderer: config.requestCanvasRenderer,
         requestExtensions: config.requestExtensions,
+        extensionSdkPath: config.extensionSdkPath,
         extensionInfo: config.extensionInfo,
         commands: config.commands?.map((cmd) => ({
           name: cmd.name,
           description: cmd.description
         })),
         systemMessage: wireSystemMessage,
-        availableTools: config.availableTools,
-        excludedTools: config.excludedTools,
+        availableTools: toolFilterOptions.availableTools,
+        excludedTools: toolFilterOptions.excludedTools,
+        toolFilterPrecedence: toolFilterOptions.toolFilterPrecedence,
         provider: config.provider,
         enableSessionTelemetry: config.enableSessionTelemetry,
         modelCapabilities: config.modelCapabilities,
+        largeOutput: toWireLargeOutput(config.largeOutput),
         requestPermission: !!config.onPermissionRequest,
         requestUserInput: !!config.onUserInputRequest,
         requestElicitation: !!config.onElicitationRequest,
+        ...config.enableMcpApps ? { requestMcpApps: true } : {},
         requestExitPlanMode: !!config.onExitPlanModeRequest,
         requestAutoModeSwitch: !!config.onAutoModeSwitchRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
@@ -625,13 +804,23 @@ class CopilotClient {
         streaming: config.streaming,
         includeSubAgentStreamingEvents: config.includeSubAgentStreamingEvents ?? true,
         mcpServers: toWireMcpServers(config.mcpServers),
+        mcpOAuthTokenStorage: config.mcpOAuthTokenStorage,
         envValueMode: "direct",
         customAgents: toWireCustomAgents(config.customAgents),
         defaultAgent: config.defaultAgent,
         agent: config.agent,
-        configDir: config.configDir,
+        configDir: config.configDirectory,
         enableConfigDiscovery: config.enableConfigDiscovery,
+        skipEmbeddingRetrieval: config.skipEmbeddingRetrieval,
+        embeddingCacheStorage: config.embeddingCacheStorage,
+        organizationCustomInstructions: config.organizationCustomInstructions,
+        enableOnDemandInstructionDiscovery: config.enableOnDemandInstructionDiscovery,
+        enableFileHooks: config.enableFileHooks,
+        enableHostGitOperations: config.enableHostGitOperations,
+        enableSessionStore: config.enableSessionStore,
+        enableSkills: config.enableSkills,
         skillDirectories: config.skillDirectories,
+        pluginDirectories: config.pluginDirectories,
         instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         infiniteSessions: config.infiniteSessions,
@@ -639,11 +828,30 @@ class CopilotClient {
         remoteSession: config.remoteSession,
         cloud: config.cloud
       });
-      const { workspacePath, capabilities } = response;
+      const {
+        sessionId: returnedSessionId,
+        workspacePath,
+        capabilities
+      } = response;
+      if (!returnedSessionId) {
+        throw new Error("session.create response did not include a sessionId");
+      }
+      if (localSessionId !== void 0 && localSessionId !== returnedSessionId) {
+        throw new Error(
+          `session.create returned sessionId ${returnedSessionId} but the caller requested ${localSessionId}`
+        );
+      }
+      if (session === void 0) {
+        session = initializeSession(returnedSessionId);
+        registeredId = returnedSessionId;
+      }
       session["_workspacePath"] = workspacePath;
       session.setCapabilities(capabilities);
+      await this.updateSessionOptionsForMode(session, config);
     } catch (e) {
-      this.sessions.delete(sessionId);
+      if (registeredId !== void 0) {
+        this.sessions.delete(registeredId);
+      }
       throw e;
     }
     return session;
@@ -701,6 +909,8 @@ class CopilotClient {
     if (config.hooks) {
       session.registerHooks(config.hooks);
     }
+    config = { ...this.configDefaultsForMode(), ...config };
+    config.systemMessage = this.getSystemMessageConfigForMode(config.systemMessage);
     const { wirePayload: wireSystemMessage, transformCallbacks } = extractTransformCallbacks(
       config.systemMessage
     );
@@ -712,6 +922,7 @@ class CopilotClient {
     }
     this.sessions.set(sessionId, session);
     this.setupSessionFs(session, config);
+    const toolFilterOptions = this.resolveToolFilterOptions(config);
     try {
       const response = await this.connection.sendRequest("session.resume", {
         ...await getTraceContext(this.onGetTraceContext),
@@ -719,9 +930,12 @@ class CopilotClient {
         clientName: config.clientName,
         model: config.model,
         reasoningEffort: config.reasoningEffort,
+        reasoningSummary: config.reasoningSummary,
+        contextTier: config.contextTier,
         systemMessage: wireSystemMessage,
-        availableTools: config.availableTools,
-        excludedTools: config.excludedTools,
+        availableTools: toolFilterOptions.availableTools,
+        excludedTools: toolFilterOptions.excludedTools,
+        toolFilterPrecedence: toolFilterOptions.toolFilterPrecedence,
         enableSessionTelemetry: config.enableSessionTelemetry,
         tools: config.tools?.map((tool) => ({
           name: tool.name,
@@ -733,6 +947,7 @@ class CopilotClient {
         canvases: config.canvases?.map((canvas) => canvas.declaration),
         requestCanvasRenderer: config.requestCanvasRenderer,
         requestExtensions: config.requestExtensions,
+        extensionSdkPath: config.extensionSdkPath,
         extensionInfo: config.extensionInfo,
         commands: config.commands?.map((cmd) => ({
           name: cmd.name,
@@ -740,27 +955,39 @@ class CopilotClient {
         })),
         provider: config.provider,
         modelCapabilities: config.modelCapabilities,
+        largeOutput: toWireLargeOutput(config.largeOutput),
         requestPermission: config.onPermissionRequest !== defaultJoinSessionPermissionHandler,
         requestUserInput: !!config.onUserInputRequest,
         requestElicitation: !!config.onElicitationRequest,
+        ...config.enableMcpApps ? { requestMcpApps: true } : {},
         requestExitPlanMode: !!config.onExitPlanModeRequest,
         requestAutoModeSwitch: !!config.onAutoModeSwitchRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
         workingDirectory: config.workingDirectory,
-        configDir: config.configDir,
+        configDir: config.configDirectory,
         enableConfigDiscovery: config.enableConfigDiscovery,
+        skipEmbeddingRetrieval: config.skipEmbeddingRetrieval,
+        embeddingCacheStorage: config.embeddingCacheStorage,
+        organizationCustomInstructions: config.organizationCustomInstructions,
+        enableOnDemandInstructionDiscovery: config.enableOnDemandInstructionDiscovery,
+        enableFileHooks: config.enableFileHooks,
+        enableHostGitOperations: config.enableHostGitOperations,
+        enableSessionStore: config.enableSessionStore,
+        enableSkills: config.enableSkills,
         streaming: config.streaming,
         includeSubAgentStreamingEvents: config.includeSubAgentStreamingEvents ?? true,
         mcpServers: toWireMcpServers(config.mcpServers),
+        mcpOAuthTokenStorage: config.mcpOAuthTokenStorage,
         envValueMode: "direct",
         customAgents: toWireCustomAgents(config.customAgents),
         defaultAgent: config.defaultAgent,
         agent: config.agent,
         skillDirectories: config.skillDirectories,
+        pluginDirectories: config.pluginDirectories,
         instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         infiniteSessions: config.infiniteSessions,
-        suppressResumeEvent: config.suppressResumeEvent,
+        disableResume: config.suppressResumeEvent,
         continuePendingWork: config.continuePendingWork,
         gitHubToken: config.gitHubToken,
         remoteSession: config.remoteSession,
@@ -770,6 +997,7 @@ class CopilotClient {
       session["_workspacePath"] = workspacePath;
       session.setCapabilities(capabilities);
       session.setOpenCanvases(openCanvases ?? []);
+      await this.updateSessionOptionsForMode(session, config);
     } catch (e) {
       this.sessions.delete(sessionId);
       throw e;
@@ -1148,6 +1376,9 @@ class CopilotClient {
       if (this.options.baseDirectory) {
         envWithoutNodeDebug.COPILOT_HOME = this.options.baseDirectory;
       }
+      if (this.options.mode === "empty") {
+        envWithoutNodeDebug.COPILOT_DISABLE_KEYTAR = "1";
+      }
       if (!this.resolvedCliPath) {
         throw new Error(
           "Path to Copilot CLI is required. Please supply it via `RuntimeConnection.forStdio({ path })` or `RuntimeConnection.forTcp({ path })`, set the COPILOT_CLI_PATH environment variable, or use `RuntimeConnection.forUri(...)` to connect to an already-running runtime."

package/dist/extension.d.ts

@@ -1,7 +1,7 @@
 import type { CopilotSession } from "./session.js";
 import { type ExtensionInfo, type PermissionHandler, type ResumeSessionConfig } from "./types.js";
 export { Canvas, CanvasError, createCanvas, type CanvasAction, type CanvasDeclaration, type CanvasHostContext, type CanvasJsonSchema, type CanvasOptions, } from "./canvas.js";
-export type JoinSessionConfig = Omit<ResumeSessionConfig, "onPermissionRequest"> & {
+export type JoinSessionConfig = Omit<ResumeSessionConfig, "onPermissionRequest" | "extensionSdkPath"> & {
     onPermissionRequest?: PermissionHandler;
 };
 export type { ExtensionInfo };

package/dist/extension.js

@@ -15,8 +15,10 @@ async function joinSession(config = {}) {
     );
   }
   const client = new CopilotClient({ _internalConnection: { kind: "parent-process" } });
+  const { extensionSdkPath: _stripped, ...rest } = config;
+  void _stripped;
   return client.resumeSession(sessionId, {
-    ...config,
+    ...rest,
     onPermissionRequest: config.onPermissionRequest ?? defaultJoinSessionPermissionHandler,
     suppressResumeEvent: config.suppressResumeEvent ?? true
   });