@github/copilot-sdk-win32-x64 1.0.17-preview.2 → 1.0.17-preview.4

package/copilot-sdk/index.js

@@ -4151,7 +4151,48 @@ function createServerRpc(connection) {
        *
        * @returns Whether the host running this runtime can run the command sandbox. The runtime checks `supported` once per process. A capability answer can change while the process runs, for example after the user installs a missing package.
        */
-      getHostSupport: async () => connection.sendRequest("sandbox.getHostSupport", {})
+      getHostSupport: async () => connection.sendRequest("sandbox.getHostSupport", {}),
+      /** @experimental */
+      proxyCa: {
+        /**
+         * Reports whether the persistent certificate authority of the sandbox credential proxy exists, whether OS trust includes it, and whether it must be rotated. Changes nothing.
+         *
+         * @param params Identifies the credential hosts that the persistent certificate authority of the sandbox credential proxy must cover. The runtime always adds the hosts from the saved user settings.
+         *
+         * @returns Status of the persistent certificate authority of the sandbox credential proxy.
+         */
+        getStatus: async (params) => connection.sendRequest("sandbox.proxyCa.getStatus", params),
+        /**
+         * Creates the persistent certificate authority of the sandbox credential proxy if none is stored, without changing OS trust, and returns the path of its public certificate. Keeps an existing certificate authority, even one that must be rotated. Fails where OS trust is unsupported. Trust it with sandbox.proxyCa.trust: the CLI trusts only the hosts in the saved user settings, so it refuses a certificate authority that also covers hosts from sandboxConfig.
+         *
+         * @param params Identifies the credential hosts that the persistent certificate authority of the sandbox credential proxy must cover. The runtime always adds the hosts from the saved user settings.
+         *
+         * @returns Result of creating the persistent certificate authority of the sandbox credential proxy.
+         */
+        create: async (params) => connection.sendRequest("sandbox.proxyCa.create", params),
+        /**
+         * Replaces the persistent certificate authority of the sandbox credential proxy with a new one for the current credential hosts. If OS trust included the old one, removes it and trusts the new one, which can show an OS authentication prompt. Running sandboxed tools keep the old certificate authority until they restart.
+         *
+         * @param params Identifies the credential hosts that the persistent certificate authority of the sandbox credential proxy must cover. The runtime always adds the hosts from the saved user settings.
+         *
+         * @returns Status of the persistent certificate authority of the sandbox credential proxy.
+         */
+        rotate: async (params) => connection.sendRequest("sandbox.proxyCa.rotate", params),
+        /**
+         * Adds the persistent certificate authority of the sandbox credential proxy to OS trust, so sandboxed clients that read only OS trust accept the proxy. Call create first. Refuses a certificate authority that is not constrained to the current credential hosts. Can show an OS authentication prompt.
+         *
+         * @param params Identifies the credential hosts that the persistent certificate authority of the sandbox credential proxy must cover. The runtime always adds the hosts from the saved user settings.
+         *
+         * @returns Status of the persistent certificate authority of the sandbox credential proxy.
+         */
+        trust: async (params) => connection.sendRequest("sandbox.proxyCa.trust", params),
+        /**
+         * Removes the persistent certificate authority of the sandbox credential proxy from OS trust. Keeps the stored certificate authority. Can show an OS authentication prompt. Sandboxed clients that read only OS trust then reject the proxy; clients that read the per-process certificate bundle continue to work.
+         *
+         * @returns Status of the persistent certificate authority of the sandbox credential proxy.
+         */
+        remove: async () => connection.sendRequest("sandbox.proxyCa.remove", {})
+      }
     },
     /** @experimental */
     tools: {
@@ -5071,22 +5112,55 @@ function createInternalServerRpc(connection) {
        * @param params Params to attach or detach an in-process ExtensionController delegate.
        */
       configureSessionExtensions: async (params) => connection.sendRequest("sessions.configureSessionExtensions", params)
-    },
-    /** @experimental */
-    accounts: {
-      /**
-       * Acquire a Microsoft Entra access token through the runtime's OneAuth broker. Account-scoped because it uses the same native broker as the account stack: a trusted host application mints a scoped Entra token for its own use, most notably to authenticate to a remote MCP server whose authorization server is Entra ID (in place of the generic browser-OAuth flow).
-       *
-       * @param params OneAuth token request supplied by a trusted host application.
-       *
-       * @returns Result of a OneAuth token acquisition.
-       */
-      acquireEntraToken: async (params) => connection.sendRequest("accounts.acquireEntraToken", params)
     }
   };
 }
 function createSessionRpc(connection, sessionId) {
   return {
+    /** @experimental */
+    providers: {
+      /**
+       * Returns adapter definitions and supported operations in this session's effective provider catalog, without running discovery. Does not list provider instances or select inference models.
+       *
+       * @returns Normalized model-provider adapter definitions available to the session, not discovered instances.
+       */
+      getCatalog: async () => connection.sendRequest("session.providers.getCatalog", { sessionId }),
+      /**
+       * Discovers reachable instances using an adapter from this session's effective provider catalog and provider-specific discovery input.
+       *
+       * @param params Provider discovery parameters.
+       *
+       * @returns Provider instances found by a discovery operation.
+       */
+      discover: async (params) => connection.sendRequest("session.providers.discover", { ...params, sessionId }),
+      /**
+       * Gets current health and version information for a discovered model-provider instance.
+       *
+       * @param params Provider status request parameters.
+       *
+       * @returns Current health information for a provider instance.
+       */
+      getStatus: async (params) => connection.sendRequest("session.providers.getStatus", { ...params, sessionId }),
+      /** @experimental */
+      models: {
+        /**
+         * Lists models installed or otherwise available from a discovered model-provider instance.
+         *
+         * @param params Provider model inventory request parameters.
+         *
+         * @returns Models offered for agent conversations by one provider instance. Adapters exclude known-incompatible models, but retain candidates with unknown capabilities. Listing does not guarantee compatibility.
+         */
+        list: async (params) => connection.sendRequest("session.providers.models.list", { ...params, sessionId }),
+        /**
+         * Translates a discovered model into the provider and model configuration needed to use it, and reports whether each is already registered in this session. Prepares only: it registers nothing, writes nothing, and performs no provider requests.
+         *
+         * @param params A discovered instance and one of its models to translate into provider configuration. Pass back the instance and model as returned by `session.providers.discover` and `session.providers.models.list`.
+         *
+         * @returns Provider configuration prepared from a discovered model. Preparing a plan changes nothing: it neither registers the model with the session nor writes durable configuration. To apply it, pass `provider` and `model` to `session.provider.add`, omitting whichever the dispositions report as already configured.
+         */
+        prepareConfiguration: async (params) => connection.sendRequest("session.providers.models.prepareConfiguration", { ...params, sessionId })
+      }
+    },
     /**
      * Suspends the session while preserving persisted state for later resume.
      *
@@ -5694,16 +5768,18 @@ function createSessionRpc(connection, sessionId) {
        */
       getSources: async () => connection.sendRequest("session.instructions.getSources", { sessionId }),
       /**
-       * Invalidates cached custom-instruction discovery so subsequent turns and source reads observe instruction files currently on disk.
+       * For local sessions, invalidates instruction discovery and the model-facing prompt, then returns freshly discovered sources. The updated prompt takes effect on the next turn. Remote sessions must reload on their agent host instead.
+       *
+       * @returns Instruction sources loaded for the session, in merge order.
        */
       reload: async () => connection.sendRequest("session.instructions.reload", { sessionId })
     },
     /** @experimental */
     customizations: {
       /**
-       * Reloads all repository and user customizations for the active session: instructions, plugins and their MCP servers and hooks, custom agents, extensions, and skills. Returns diagnostics from the final skill reload.
+       * For local sessions, reconciles repository context and discovered instructions, plugins, skills, agents, hooks, MCP servers, and extensions after files appear or change under the working directory. Independent component failures are returned in outcomes and errors; a rejected call can have partially applied earlier steps. Remote sessions must reload on their agent host instead. The model-facing context is rebuilt on the next turn.
        *
-       * @returns Diagnostics from reloading skill definitions, with warnings and errors as separate lists.
+       * @returns Results of reloading discovered session customizations. Inspect outcomes for reloaded, skipped, or failed subsystems; a rejection may follow partial mutation. Changes to the model-facing prompt and tools apply on the next turn.
        */
       reload: async () => connection.sendRequest("session.customizations.reload", { sessionId })
     },
@@ -7407,6 +7483,33 @@ function createInternalSessionRpc(connection, sessionId) {
       finalizeInvocationEffect: async (params) => connection.sendRequest("session.commands.finalizeInvocationEffect", { ...params, sessionId })
     },
     /** @experimental */
+    ui: {
+      /**
+       * Resolves a pending elicitation request after direct interaction in the trusted in-process client. Only an accepted response to the built-in ask_user tool can become trusted human evidence.
+       *
+       * @param params Pending elicitation request ID and the user's response (accept/decline/cancel + form values).
+       *
+       * @returns Indicates whether the elicitation response was accepted; false if it was already resolved by another client.
+       */
+      handleHumanAskUser: async (params) => connection.sendRequest("session.ui.handleHumanAskUser", { ...params, sessionId }),
+      /**
+       * Resolves a pending `user_input.requested` event after direct interaction in the trusted in-process client.
+       *
+       * @param params Request ID of a pending `user_input.requested` event and the user's response.
+       *
+       * @returns Indicates whether the pending UI request was resolved by this call.
+       */
+      handleHumanUserInput: async (params) => connection.sendRequest("session.ui.handleHumanUserInput", { ...params, sessionId }),
+      /**
+       * Resolves a pending `exit_plan_mode.requested` event after direct interaction in the trusted in-process client.
+       *
+       * @param params Request ID of a pending `exit_plan_mode.requested` event and the user's response.
+       *
+       * @returns Indicates whether the pending UI request was resolved by this call.
+       */
+      handleHumanExitPlanMode: async (params) => connection.sendRequest("session.ui.handleHumanExitPlanMode", { ...params, sessionId })
+    },
+    /** @experimental */
     settings: {
       /**
        * Returns a redacted snapshot of session runtime settings, with secrets and raw feature flags excluded. Internal: the runtime settings shape is a runtime-internal surface and is deliberately kept out of the public SDK, because consumers should not depend on the runtime's internal settings layout. It remains callable in-process and is expected to be reworked as the runtime internals are consolidated.
@@ -7559,11 +7662,21 @@ function registerClientSessionApiHandlers(connection, getHandlers) {
     if (!handler) throw new Error(`No sessionFs handler registered for session: ${params.sessionId}`);
     return handler.readFile(params);
   });
+  connection.onRequest("sessionFs.readFileBytes", async (params) => {
+    const handler = getHandlers(params.sessionId).sessionFs;
+    if (!handler) throw new Error(`No sessionFs handler registered for session: ${params.sessionId}`);
+    return handler.readFileBytes(params);
+  });
   connection.onRequest("sessionFs.writeFile", async (params) => {
     const handler = getHandlers(params.sessionId).sessionFs;
     if (!handler) throw new Error(`No sessionFs handler registered for session: ${params.sessionId}`);
     return handler.writeFile(params);
   });
+  connection.onRequest("sessionFs.writeFileBytes", async (params) => {
+    const handler = getHandlers(params.sessionId).sessionFs;
+    if (!handler) throw new Error(`No sessionFs handler registered for session: ${params.sessionId}`);
+    return handler.writeFileBytes(params);
+  });
   connection.onRequest("sessionFs.appendFile", async (params) => {
     const handler = getHandlers(params.sessionId).sessionFs;
     if (!handler) throw new Error(`No sessionFs handler registered for session: ${params.sessionId}`);
@@ -7752,6 +7865,8 @@ function isResponseSchema(value) {
 }
 
 // src/sdk/nodejs/dist/sessionFsProvider.js
+var MAX_BINARY_BYTES = (64 * 1024 * 1024 - 1024) / 4 * 3;
+var MAX_BINARY_CONTENT_LENGTH = Math.ceil(MAX_BINARY_BYTES / 3) * 4;
 var SessionFsSqliteTransactionFailure = class extends Error {
   /** Failure classification reported to the runtime. */
   errorClass;
@@ -7761,6 +7876,9 @@ var SessionFsSqliteTransactionFailure = class extends Error {
     this.errorClass = errorClass;
   }
 };
+var SessionFsWriteFailure = class extends Error {
+  writeChanged = true;
+};
 function normalizeSqliteParams(params) {
   if (!params) {
     return void 0;
@@ -7783,10 +7901,60 @@ function createSessionFsAdapter(provider) {
         return { content: "", error: toSessionFsError(err) };
       }
     },
+    readFileBytes: async ({ path }) => {
+      if (!provider.readFileBytes) {
+        return {
+          content: "",
+          error: { code: "UNKNOWN", message: "Binary reads are not supported" }
+        };
+      }
+      try {
+        const bytes = await provider.readFileBytes(path);
+        if (bytes.length > MAX_BINARY_BYTES) {
+          return {
+            content: "",
+            error: {
+              code: "UNKNOWN",
+              message: "sessionFs.readFileBytes content exceeds the binary read limit"
+            }
+          };
+        }
+        return {
+          content: Buffer.from(bytes).toString("base64")
+        };
+      } catch (err) {
+        return { content: "", error: toSessionFsError(err) };
+      }
+    },
     writeFile: async ({ path, content, mode }) => {
       try {
         await provider.writeFile(path, content, mode);
         return void 0;
+      } catch (err) {
+        const error = toSessionFsError(err);
+        return err instanceof SessionFsWriteFailure ? { ...error, writeChanged: true } : error;
+      }
+    },
+    writeFileBytes: async ({ path, content, mode }) => {
+      if (!provider.writeFileBytes) {
+        return { code: "UNKNOWN", message: "Binary writes are not supported" };
+      }
+      if (content.length > MAX_BINARY_CONTENT_LENGTH) {
+        return {
+          code: "UNKNOWN",
+          message: "sessionFs.writeFileBytes content exceeds the binary write limit"
+        };
+      }
+      const bytes = Buffer.from(content, "base64");
+      if (bytes.toString("base64") !== content || bytes.length > MAX_BINARY_BYTES) {
+        return {
+          code: "UNKNOWN",
+          message: "invalid sessionFs.writeFileBytes base64 content"
+        };
+      }
+      try {
+        await provider.writeFileBytes(path, bytes, mode);
+        return void 0;
       } catch (err) {
         return toSessionFsError(err);
       }
@@ -8764,10 +8932,10 @@ var SYSTEM_MESSAGE_SECTIONS = {
   tool_instructions: { description: "Per-tool usage instructions" },
   custom_instructions: { description: "Repository and organization custom instructions" },
   runtime_instructions: {
-    description: "Runtime-provided context and instructions (e.g. system notifications, memories, workspace context, mode-specific instructions, content-exclusion policy)"
+    description: "Runtime-provided system-prompt context and instructions, such as system notifications, memories, workspace context, and content-exclusion policy. Mode-specific instructions can travel in transition messages instead."
   },
   last_instructions: {
-    description: "End-of-prompt instructions: parallel tool calling, persistence, task completion"
+    description: "End-of-prompt instructions: parallel tool calling, persistence, task completion, and configured subagent-model guidance when the task tool is available"
   }
 };
 function isAttributedPermissionResult(result) {
@@ -8910,6 +9078,18 @@ function copyDefinedWorkflowAgentOption(source, target, key) {
     target[key] = value;
   }
 }
+function toToolDefinition(tool) {
+  return {
+    name: tool.name,
+    description: tool.description ?? "",
+    parameters: toJsonSchema(tool.parameters),
+    overridesBuiltInTool: tool.overridesBuiltInTool,
+    skipPermission: tool.skipPermission,
+    defer: tool.defer,
+    metadata: tool.metadata,
+    isTerminal: tool.isTerminal
+  };
+}
 var workflowExecutionStore = new AsyncLocalStorage();
 function throwIfWorkflowExecutionIsActive() {
   if (workflowExecutionStore.getStore()?.active) {
@@ -9130,6 +9310,8 @@ var CopilotSession = class {
   eventHandlers = /* @__PURE__ */ new Set();
   typedEventHandlers = /* @__PURE__ */ new Map();
   toolHandlers = /* @__PURE__ */ new Map();
+  /** Settles once every earlier `setTools` call has finished. */
+  setToolsQueue = Promise.resolve();
   pendingExternalTools = /* @__PURE__ */ new Map();
   canvases = /* @__PURE__ */ new Map();
   bearerTokenProviders = /* @__PURE__ */ new Map();
@@ -9941,7 +10123,20 @@ var CopilotSession = class {
     }
     for (const tool of tools) {
       if (tool.handler) {
-        this.toolHandlers.set(tool.name, tool.handler);
+        const handler = tool.handler;
+        if (tool.name === "apply_patch" && tool.overridesBuiltInTool && toJsonSchema(tool.parameters)?.type === "string") {
+          this.toolHandlers.set(tool.name, (args, invocation) => {
+            if (typeof args === "string") {
+              return handler(args, invocation);
+            }
+            if (typeof args === "object" && args !== null && "input" in args && typeof args.input === "string") {
+              return handler(args.input, invocation);
+            }
+            throw new TypeError("apply_patch string override requires a string input");
+          });
+        } else {
+          this.toolHandlers.set(tool.name, handler);
+        }
       }
     }
   }
@@ -10536,7 +10731,9 @@ var CopilotSession = class {
       sessionStart: this.hooks.onSessionStart,
       sessionEnd: this.hooks.onSessionEnd,
       errorOccurred: this.hooks.onErrorOccurred,
-      agentStop: this.hooks.onAgentStop
+      agentStop: this.hooks.onAgentStop,
+      subagentStart: this.hooks.onSubagentStart,
+      subagentStop: this.hooks.onSubagentStop
     };
     const handler = handlerMap[hookType];
     if (!handler) {
@@ -10700,6 +10897,59 @@ var CopilotSession = class {
   async setAutoTier(autoTier) {
     return await this.rpc.model.switchAutoTier({ autoTier });
   }
+  /**
+   * Replace the tools this client supplies to the session.
+   *
+   * `tools` becomes the complete set of tools this client implements,
+   * replacing the ones it supplied when the session was created or resumed,
+   * or in an earlier call. Built-in, MCP, and plugin tools, and tools other
+   * connected clients supply, are unaffected. Pass an empty array to remove
+   * all of this client's tools.
+   *
+   * Tools are defined the same way as for `createSession`: calls to tools
+   * with a `handler` are dispatched to it, and tools without one are
+   * declaration-only. Once the runtime accepts the replacement, every tool
+   * call this session dispatches uses the new handlers; calls already
+   * running finish on their original handlers. If the runtime rejects the
+   * replacement, this rejects and the previous tools and handlers stay in
+   * place. Concurrent calls on the same session are applied one at a time,
+   * in the order they are made.
+   *
+   * The agent sees the new tools from its next model request, which can fall
+   * within a turn in progress. A model request already in flight was made
+   * with the previous tools, so the agent can still call a tool you removed.
+   * This session doesn't answer that call, and it can stay pending until the
+   * turn is aborted. If a running turn might still call a tool you remove,
+   * replace tools while the session is idle.
+   *
+   * @param tools - The complete set of tools this client supplies
+   *
+   * @experimental Wraps the experimental `session.tools.set` RPC and may change
+   * or be removed in a future release.
+   *
+   * @example
+   * ```typescript
+   * await session.setTools([
+   *     defineTool("search_issues", {
+   *         description: "Search the issues shown on the current page",
+   *         parameters: z.object({ query: z.string() }),
+   *         handler: async ({ query }) => searchIssues(query),
+   *     }),
+   * ]);
+   * ```
+   */
+  async setTools(tools) {
+    const definitions = tools.map(toToolDefinition);
+    const replacement = this.setToolsQueue.then(async () => {
+      await this.rpc.tools.set({ tools: definitions });
+      this.registerTools(tools);
+    });
+    this.setToolsQueue = replacement.then(
+      () => void 0,
+      () => void 0
+    );
+    await replacement;
+  }
   /**
    * Log a message to the session timeline.
    * The message appears in the session event stream and is visible to SDK consumers
@@ -10955,6 +11205,7 @@ var EXCLUDED_TOP_LEVEL = /* @__PURE__ */ new Set([
   "app.js",
   "assets",
   "changelog.json",
+  "cli-main.js",
   "copilot",
   "copilot.exe",
   "foundry-local-sdk",
@@ -11298,6 +11549,7 @@ var BuiltInTools = {
 // src/sdk/nodejs/dist/client.js
 var MIN_PROTOCOL_VERSION = 3;
 var RUNTIME_SHUTDOWN_TIMEOUT_MS = 1e4;
+var CLOUD_SESSION_CLEANUP_TIMEOUT_MS = 1e4;
 function createMessageConnection(reader, writer) {
   let dispatch;
   let finishDrain;
@@ -11826,6 +12078,11 @@ var CopilotClient = class _CopilotClient {
         "SessionFsConfig declares capabilities.sqlite but the provider does not implement sqlite."
       );
     }
+    if (this.sessionFsConfig.capabilities?.binary && (!provider.readFileBytes || !provider.writeFileBytes)) {
+      throw new Error(
+        "SessionFsConfig declares capabilities.binary but the provider does not implement readFileBytes and writeFileBytes."
+      );
+    }
     session.clientSessionApis.sessionFs = createSessionFsAdapter(provider);
   }
   setupClientGlobalHandlers() {
@@ -12509,12 +12766,13 @@ var CopilotClient = class _CopilotClient {
       if (config.onEvent) {
         s.on(config.onEvent);
       }
-      this.sessions.set(sessionId, s);
       this.setupSessionFs(s, config);
+      this.sessions.set(sessionId, s);
       return s;
     };
     let session;
     let registeredId;
+    let uninitializedCloudSessionId;
     if (localSessionId !== void 0) {
       try {
         session = initializeSession(localSessionId);
@@ -12637,7 +12895,9 @@ var CopilotClient = class _CopilotClient {
         );
       }
       if (session === void 0) {
+        uninitializedCloudSessionId = returnedSessionId;
         session = initializeSession(returnedSessionId);
+        uninitializedCloudSessionId = void 0;
         registeredId = returnedSessionId;
       }
       this.assignGitHubTokenProvider(gitHubTokenProviderRegistrationId, returnedSessionId);
@@ -12659,6 +12919,20 @@ var CopilotClient = class _CopilotClient {
       if (gitHubTokenProviderRegistrationId !== void 0) {
         this.githubTokenProviders.delete(gitHubTokenProviderRegistrationId);
       }
+      if (uninitializedCloudSessionId !== void 0) {
+        try {
+          await withTimeout(
+            this.deleteSession(uninitializedCloudSessionId),
+            CLOUD_SESSION_CLEANUP_TIMEOUT_MS,
+            `session.delete timed out after ${CLOUD_SESSION_CLEANUP_TIMEOUT_MS}ms`
+          );
+        } catch (cleanupError) {
+          throw new AggregateError(
+            [e, cleanupError],
+            "Failed to initialize and delete cloud session"
+          );
+        }
+      }
       throw e;
     }
     for (const entry of this.hostHandoffs.values()) {
@@ -12758,8 +13032,8 @@ var CopilotClient = class _CopilotClient {
     if (config.onEvent) {
       session.on(config.onEvent);
     }
-    this.sessions.set(sessionId, session);
     this.setupSessionFs(session, config);
+    this.sessions.set(sessionId, session);
     const toolFilterOptions = this.resolveToolFilterOptions(config);
     const gitHubTokenProviderRegistrationId = this.registerGitHubTokenProvider(
       config.gitHubTokenProvider,
@@ -14066,6 +14340,7 @@ export {
   RuntimeConnection,
   SYSTEM_MESSAGE_SECTIONS,
   SessionFsSqliteTransactionFailure,
+  SessionFsWriteFailure,
   ToolSet,
   WorkflowResumeError,
   approveAll,

package/copilot-sdk/session.d.ts

@@ -1,7 +1,7 @@
 import { createSessionRpc } from "./generated/rpc.js";
 import type { ModelSwitchAutoTierResult } from "./generated/rpc.js";
 import type { OpenCanvasInstance } from "./generated/rpc.js";
-import type { MessageOptions, ResponseSchema, ContextTier, ReasoningEffort, ReasoningSummary, AutoTier, ModelCapabilitiesOverride, SessionCapabilities, SessionEvent, SessionEventHandler, SessionEventType, SessionUiApi, TranscriptRecovery, TypedSessionEventHandler } from "./types.js";
+import type { MessageOptions, ResponseSchema, ContextTier, ReasoningEffort, ReasoningSummary, AutoTier, ModelCapabilitiesOverride, SessionCapabilities, SessionEvent, SessionEventHandler, SessionEventType, SessionUiApi, Tool, TranscriptRecovery, TypedSessionEventHandler } from "./types.js";
 import { type SessionWorkflowApi } from "./workflow.js";
 /** Assistant message event - the final response from the assistant. */
 export type AssistantMessageEvent = Extract<SessionEvent, {
@@ -45,6 +45,8 @@ export declare class CopilotSession {
     private eventHandlers;
     private typedEventHandlers;
     private toolHandlers;
+    /** Settles once every earlier `setTools` call has finished. */
+    private setToolsQueue;
     private pendingExternalTools;
     private canvases;
     private bearerTokenProviders;
@@ -364,6 +366,48 @@ export declare class CopilotSession {
      * ```
      */
     setAutoTier(autoTier: AutoTier | null): Promise<ModelSwitchAutoTierResult>;
+    /**
+     * Replace the tools this client supplies to the session.
+     *
+     * `tools` becomes the complete set of tools this client implements,
+     * replacing the ones it supplied when the session was created or resumed,
+     * or in an earlier call. Built-in, MCP, and plugin tools, and tools other
+     * connected clients supply, are unaffected. Pass an empty array to remove
+     * all of this client's tools.
+     *
+     * Tools are defined the same way as for `createSession`: calls to tools
+     * with a `handler` are dispatched to it, and tools without one are
+     * declaration-only. Once the runtime accepts the replacement, every tool
+     * call this session dispatches uses the new handlers; calls already
+     * running finish on their original handlers. If the runtime rejects the
+     * replacement, this rejects and the previous tools and handlers stay in
+     * place. Concurrent calls on the same session are applied one at a time,
+     * in the order they are made.
+     *
+     * The agent sees the new tools from its next model request, which can fall
+     * within a turn in progress. A model request already in flight was made
+     * with the previous tools, so the agent can still call a tool you removed.
+     * This session doesn't answer that call, and it can stay pending until the
+     * turn is aborted. If a running turn might still call a tool you remove,
+     * replace tools while the session is idle.
+     *
+     * @param tools - The complete set of tools this client supplies
+     *
+     * @experimental Wraps the experimental `session.tools.set` RPC and may change
+     * or be removed in a future release.
+     *
+     * @example
+     * ```typescript
+     * await session.setTools([
+     *     defineTool("search_issues", {
+     *         description: "Search the issues shown on the current page",
+     *         parameters: z.object({ query: z.string() }),
+     *         handler: async ({ query }) => searchIssues(query),
+     *     }),
+     * ]);
+     * ```
+     */
+    setTools(tools: Tool[]): Promise<void>;
     /**
      * Log a message to the session timeline.
      * The message appears in the session event stream and is visible to SDK consumers

package/copilot-sdk/sessionFsProvider.d.ts

@@ -37,6 +37,10 @@ export declare class SessionFsSqliteTransactionFailure extends Error {
     readonly errorClass: SessionFsSqliteTransactionErrorClass;
     constructor(message: string, errorClass?: SessionFsSqliteTransactionErrorClass);
 }
+/** Throw from `writeFile` only when the provider changed the target before failing. */
+export declare class SessionFsWriteFailure extends Error {
+    readonly writeChanged = true;
+}
 /**
  * SQLite operations for the per-session database.
  * Implementers provide query execution and existence checking.
@@ -78,7 +82,11 @@ export interface SessionFsSqliteProvider {
 export interface SessionFsProvider {
     /** Reads the full content of a file. Throw if the file does not exist. */
     readFile(path: string): Promise<string>;
-    /** Writes content to a file, creating parent directories if needed. */
+    /** Read exact file bytes. Required when capabilities.binary is enabled. */
+    readFileBytes?(path: string): Promise<Uint8Array>;
+    /** Write exact file bytes. Required when capabilities.binary is enabled. */
+    writeFileBytes?(path: string, content: Uint8Array, mode?: number): Promise<void>;
+    /** Writes content to a file, creating parent directories if needed. Throw {@link SessionFsWriteFailure} if a failed write changed the target. */
     writeFile(path: string, content: string, mode?: number): Promise<void>;
     /** Appends content to a file, creating parent directories if needed. */
     appendFile(path: string, content: string, mode?: number): Promise<void>;