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

package/README.md

@@ -2,8 +2,6 @@
 
 TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC.
 
-> **Note:** This SDK is in public preview and may change in breaking ways.
-
 ## Installation
 
 ```bash
@@ -57,7 +55,7 @@ await session.disconnect();
 await client.stop();
 ```
 
-Sessions also support `Symbol.asyncDispose` for use with [`await using`](https://github.com/tc39/proposal-explicit-resource-management) (TypeScript 5.2+/Node.js 18.0+):
+Sessions also support `Symbol.asyncDispose` for use with [`await using`](https://github.com/tc39/proposal-explicit-resource-management) (TypeScript 5.2+ / Node.js 20+):
 
 ```typescript
 await using session = await client.createSession({
@@ -82,14 +80,20 @@ new CopilotClient(options?: CopilotClientOptions)
 - `connection?: RuntimeConnection` - How to connect to the Copilot runtime. Construct via the factory functions on `RuntimeConnection`:
     - `RuntimeConnection.forStdio({ path?, args? })` (default) — spawn the runtime and communicate over its stdin/stdout.
     - `RuntimeConnection.forTcp({ port?, connectionToken?, path?, args? })` — spawn the runtime as a TCP server.
-    - `RuntimeConnection.forUri(url, { connectionToken? })` — connect to an already-running runtime (mutually exclusive with `gitHubToken`/`useLoggedInUser`).
-- `cwd?: string` - Working directory for the runtime process (default: current process cwd).
+    - `RuntimeConnection.forUri(url, { connectionToken? })` — connect to an already-running runtime (mutually exclusive with `gitHubToken`/`useLoggedInUser`). There is no top-level `cliUrl` shortcut; use this factory for URL-based connections.
+- `mode?: "empty" | "copilot-cli"` - Defaulting strategy. Use `"empty"` for multi-user server mode; defaults to `"copilot-cli"`.
+- `workingDirectory?: string` - Working directory for the runtime process (default: current process cwd).
 - `baseDirectory?: string` - Base directory for Copilot data (session state, config, etc.). Sets `COPILOT_HOME` on the spawned runtime. When not set, the runtime defaults to `~/.copilot`. Ignored when connecting via `RuntimeConnection.forUri`.
-- `logLevel?: string` - Log level. When omitted, the runtime uses its own default (currently `"info"`).
+- `logLevel?: "none" | "error" | "warning" | "info" | "debug" | "all"` - Log level. When omitted, the runtime uses its own default (currently `"info"`).
+- `env?: Record<string, string | undefined>` - Environment variables for the runtime process. When omitted, inherits `process.env`.
 - `gitHubToken?: string` - GitHub token for authentication. When provided, takes priority over other auth methods.
 - `useLoggedInUser?: boolean` - Whether to use logged-in user for authentication (default: true, but false when `gitHubToken` is provided). Cannot be used with `RuntimeConnection.forUri`.
+- `onListModels?: () => Promise<ModelInfo[]> | ModelInfo[]` - Optional model-list provider, useful when using a custom provider.
 - `telemetry?: TelemetryConfig` - OpenTelemetry configuration for the runtime process. Providing this object enables telemetry — no separate flag needed. See [Telemetry](#telemetry) below.
 - `onGetTraceContext?: TraceContextProvider` - Advanced: callback for linking your application's own OpenTelemetry spans into the same distributed trace as the runtime's spans. Not needed for normal telemetry collection. See [Telemetry](#telemetry) below.
+- `sessionFs?: SessionFsConfig` - Custom session filesystem provider.
+- `sessionIdleTimeoutSeconds?: number` - Server-wide idle timeout for sessions in seconds. Ignored when connecting via `RuntimeConnection.forUri`.
+- `enableRemoteSessions?: boolean` - Enable Mission Control remote session support. Ignored when connecting via `RuntimeConnection.forUri`.
 
 #### Methods
 
@@ -163,7 +167,7 @@ Get the ID of the session currently displayed in the TUI. Only available when co
 
 Request the TUI to switch to displaying the specified session. Only available in TUI+server mode.
 
-##### `on(eventType: SessionLifecycleEventType, handler): () => void`
+##### `onLifecycle(eventType: SessionLifecycleEventType, handler): () => void`
 
 Subscribe to a specific session lifecycle event type. Returns an unsubscribe function.
 
@@ -173,7 +177,7 @@ const unsubscribe = client.onLifecycle("session.foreground", (event) => {
 });
 ```
 
-##### `on(handler: SessionLifecycleHandler): () => void`
+##### `onLifecycle(handler: SessionLifecycleHandler): () => void`
 
 Subscribe to all session lifecycle events. Returns an unsubscribe function.
 
@@ -957,7 +961,7 @@ const session = await client.createSession({
             };
         },
 
-        // Called after each tool execution
+        // Called after each successful tool execution
         onPostToolUse: async (input, invocation) => {
             console.log(`Tool ${input.toolName} completed`);
             // Optionally modify the result or add context
@@ -966,6 +970,16 @@ const session = await client.createSession({
             };
         },
 
+        // Called after a tool execution whose result was "failure".
+        // onPostToolUse does NOT fire for failed tool calls — register this
+        // hook to observe them. Input includes `error` (the failure message
+        // extracted from the tool's result), not the full result object.
+        onPostToolUseFailure: async (input, invocation) => {
+            console.log(`Tool ${input.toolName} failed: ${input.error}`);
+            // Optionally append hidden guidance to the model.
+            return { additionalContext: "Suggest checking inputs and retrying." };
+        },
+
         // Called when user submits a prompt
         onUserPromptSubmitted: async (input, invocation) => {
             console.log(`User prompt: ${input.prompt}`);
@@ -1001,7 +1015,8 @@ const session = await client.createSession({
 **Available hooks:**
 
 - `onPreToolUse` - Intercept tool calls before execution. Can allow/deny or modify arguments.
-- `onPostToolUse` - Process tool results after execution. Can modify results or add context.
+- `onPostToolUse` - Process tool results after **successful** execution. Can modify results or add context.
+- `onPostToolUseFailure` - Observe and append hidden guidance to the model after tool executions whose result was `"failure"`. Register this in addition to `onPostToolUse` to see failed tool calls.
 - `onUserPromptSubmitted` - Intercept user prompts. Can modify the prompt before processing.
 - `onSessionStart` - Run logic when a session starts or resumes.
 - `onSessionEnd` - Cleanup or logging when session ends.

package/dist/canvas.d.ts

@@ -1,14 +1,17 @@
 import type { CanvasJsonSchema, CanvasProviderCloseRequest, CanvasProviderInvokeActionRequest, CanvasProviderOpenRequest, CanvasProviderOpenResult } from "./generated/rpc.js";
-export type { CanvasJsonSchema, CanvasHostContext } from "./generated/rpc.js";
+export type { CanvasJsonSchema, CanvasHostContext, CanvasHostContextCapabilities, } from "./generated/rpc.js";
 /**
  * Extension-owned canvases declared via
  * `joinSession({ canvases: [createCanvas({...})] })`.
  *
  * The runtime sends provider callbacks as `canvas.open`, `canvas.close`, and
- * `canvas.invokeAction` JSON-RPC requests via the codegen client session API
+ * `canvas.action.invoke` JSON-RPC requests via the codegen client session API
  * pipeline. The SDK routes those requests by `canvasId` to the in-process
  * handlers bound by `createCanvas`. Re-opening with an existing `instanceId`
  * is how the host focuses an existing panel; reload is a renderer-only concern.
+ *
+ * @experimental Canvas types are part of an experimental wire-protocol surface
+ * and may change or be removed in future SDK or CLI releases.
  */
 /**
  * A single agent-callable action contributed by a canvas. The metadata
@@ -18,6 +21,9 @@ export type { CanvasJsonSchema, CanvasHostContext } from "./generated/rpc.js";
  *
  * Names MUST NOT start with `canvas.` — that prefix is reserved for
  * lifecycle verbs.
+ *
+ * @experimental This type is part of an experimental wire-protocol surface
+ * and may change or be removed in future SDK or CLI releases.
  */
 export interface CanvasAction {
     /** Action identifier, unique within the canvas. */
@@ -32,6 +38,9 @@ export interface CanvasAction {
 /**
  * Declarative metadata for a single canvas, serialized over the wire on
  * `session.create` / `session.resume`.
+ *
+ * @experimental This type is part of an experimental wire-protocol surface
+ * and may change or be removed in future SDK or CLI releases.
  */
 export interface CanvasDeclaration {
     /** Canvas id, unique within the declaring connection. */
@@ -45,7 +54,12 @@ export interface CanvasDeclaration {
     /** Agent-invocable actions exposed via `invoke_canvas_action`. */
     actions?: Omit<CanvasAction, "handler">[];
 }
-/** Structured error returned from canvas handlers. */
+/**
+ * Structured error returned from canvas handlers.
+ *
+ * @experimental This class is part of an experimental wire-protocol surface
+ * and may change or be removed in future SDK or CLI releases.
+ */
 export declare class CanvasError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
@@ -55,6 +69,9 @@ export declare class CanvasError extends Error {
 /**
  * Options accepted by {@link createCanvas}. Combines the declarative
  * {@link CanvasDeclaration} fields with the in-process handler closures.
+ *
+ * @experimental This interface is part of an experimental wire-protocol surface
+ * and may change or be removed in future SDK or CLI releases.
  */
 export interface CanvasOptions {
     /** @see CanvasDeclaration.id */
@@ -87,6 +104,9 @@ export interface CanvasOptions {
  * ergonomics) where other SDKs (Rust, Python, Go, .NET) expose a single
  * `CanvasHandler` per session that switches on `canvasId`. Both shapes target
  * the same JSON-RPC wire protocol; the divergence is API ergonomics only.
+ *
+ * @experimental This class is part of an experimental wire-protocol surface
+ * and may change or be removed in future SDK or CLI releases.
  */
 export declare class Canvas {
     readonly declaration: CanvasDeclaration;
@@ -99,5 +119,8 @@ export declare class Canvas {
  * `DefineTool`'s co-location ergonomics) where other SDKs (Rust, Python, Go,
  * .NET) expose a single `CanvasHandler` per session that switches on
  * `canvasId`. Both shapes target the same JSON-RPC wire protocol.
+ *
+ * @experimental This function is part of an experimental wire-protocol surface
+ * and may change or be removed in future SDK or CLI releases.
  */
 export declare function createCanvas(options: CanvasOptions): Canvas;

package/dist/cjs/client.js

@@ -34,6 +34,7 @@ var import_sdkProtocolVersion = require("./sdkProtocolVersion.js");
 var import_session = require("./session.js");
 var import_sessionFsProvider = require("./sessionFsProvider.js");
 var import_telemetry = require("./telemetry.js");
+var import_toolSet = require("./toolSet.js");
 var import_types = require("./types.js");
 const import_meta = {};
 const MIN_PROTOCOL_VERSION = 3;
@@ -67,6 +68,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 import_toolSet.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 };
@@ -249,8 +277,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 = [];
   /**
@@ -560,54 +599,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 ?? (0, import_node_crypto.randomUUID)();
-    const session = new import_session.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 ?? (0, import_node_crypto.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 import_session.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 (0, import_telemetry.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,
@@ -618,20 +793,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)),
@@ -639,13 +818,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,
@@ -653,11 +842,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;
@@ -715,6 +923,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
     );
@@ -726,6 +936,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 (0, import_telemetry.getTraceContext)(this.onGetTraceContext),
@@ -733,9 +944,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,
@@ -747,6 +961,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,
@@ -754,27 +969,39 @@ class CopilotClient {
         })),
         provider: config.provider,
         modelCapabilities: config.modelCapabilities,
+        largeOutput: toWireLargeOutput(config.largeOutput),
         requestPermission: config.onPermissionRequest !== import_types.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,
@@ -784,6 +1011,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;
@@ -1162,6 +1390,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/cjs/extension.js

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