@github/copilot-sdk 1.0.17-preview.3 → 1.0.17-preview.4

package/README.md

@@ -270,6 +270,19 @@ new CopilotClient(options?: CopilotClientOptions)
 - `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.
+
+For a custom provider to serve images to the `view` tool, declare
+`sessionFs.capabilities.binary: true` and implement
+`readFileBytes(path): Promise<Uint8Array>` and
+`writeFileBytes(path, content: Uint8Array, mode?: number): Promise<void>` on each session's provider. The
+adapter transmits exact bytes as standard base64; text-only providers still
+support text operations, but image reads fail rather than falling back to the
+runtime machine's filesystem. A missing binary implementation is rejected
+when a session is created.
+
+Binary reads and writes are limited to 50,330,880 raw bytes (approximately 48 MiB);
+larger results return a filesystem error before encoding or decoding.
+
 - `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`.
 
@@ -857,6 +870,22 @@ defineTool("edit_file", {
 });
 ```
 
+An `apply_patch` override can declare a string schema. The model sees a required
+`input` property, but the runtime restores the declared scalar shape before
+dispatching to any SDK. Both a Zod-inferred Node handler and
+`invocation.arguments` receive the patch text as a string:
+
+```ts
+defineTool("apply_patch", {
+    parameters: z.string(),
+    overridesBuiltInTool: true,
+    handler: (patch) => patch.trim(),
+});
+```
+
+String-schema `apply_patch` overrides cannot contain JSON Schema references;
+use an object schema if references are needed.
+
 #### Skipping Permission Prompts
 
 Set `skipPermission: true` on a tool definition to allow it to execute without triggering a permission prompt:
@@ -1006,6 +1035,8 @@ Available section IDs: `preamble`, `identity`, `tone`, `tool_efficiency`, `envir
 
 `identity` and `tool_instructions` are section _groups_ that target a collection of related sub-sections as a unit. Use `preamble` to target just the identity preamble without affecting its sibling sub-sections.
 
+`last_instructions` includes configured subagent-model guidance when the `task` tool is available. Removing or replacing this section also removes that guidance; a transform callback receives the complete section, including the guidance, and its returned content is authoritative. Append, prepend, and preserve retain their usual section semantics. These overrides change prompt prose only, not configured subagent models, tool availability, or runtime dispatch policy. `runtime_instructions` is a separate section: removing it does not remove `last_instructions`.
+
 Each section override supports five actions:
 
 - **`replace`** — Replace the section content entirely
@@ -1014,6 +1045,8 @@ Each section override supports five actions:
 - **`prepend`** — Add content before the existing section
 - **`preserve`** — No-op that opts an individually-addressable section out of a group-level `remove`
 
+An `action` can also be a callback that receives the current section content and returns the replacement content, synchronously or asynchronously.
+
 Unknown section IDs are handled gracefully: content from `replace`/`append`/`prepend` overrides is appended to additional instructions, and `remove` overrides are silently ignored.
 
 #### Replace Mode
@@ -1461,6 +1494,20 @@ const session = await client.createSession({
                 };
             }
         },
+
+        // Called before a sub-agent's first turn (the input identifies the parent session)
+        onSubagentStart: (input, invocation) => {
+            console.log(`Starting ${input.agentDisplayName ?? input.agentName}`);
+            return { additionalContext: "Check the requested file before reporting back." };
+        },
+
+        // Called when a sub-agent completes a turn
+        onSubagentStop: (input, invocation) => {
+            console.log(`${input.agentName} replied: ${input.response}`);
+            // Return { decision: "block", reason: "Continue checking the file." }
+            // to request another child turn instead.
+            return { modifiedResponse: `Reviewed: ${input.response}` };
+        },
     },
 });
 ```
@@ -1475,6 +1522,8 @@ const session = await client.createSession({
 - `onSessionEnd` - Cleanup or logging when session ends.
 - `onErrorOccurred` - Handle errors with retry/skip/abort strategies.
 - `onAgentStop` - Observe natural top-level agent completion. Return `{ decision: "block", reason }` to request another turn; use `stopHookActive` to avoid repeated blocks.
+- `onSubagentStart` - Observe a sub-agent before its first turn and prepend `additionalContext` to the child's prompt.
+- `onSubagentStop` - Observe a sub-agent's final response. Return `{ decision: "block", reason }` to request another child turn, or `{ modifiedResponse }` to replace the response reported to the parent.
 
 ## Error Handling
 

package/dist/canvas.d.ts

@@ -32,7 +32,12 @@ export interface CanvasAction {
     description?: string;
     /** Optional JSON Schema for the action's `input` payload. */
     inputSchema?: CanvasJsonSchema;
-    /** Required per-action dispatch handler. */
+    /**
+     * Required per-action dispatch handler. The returned value becomes the
+     * `invoke_canvas_action` tool result. Return a `ToolResultObject`
+     * (with `binaryResultsForLlm`) to send text and images to the model, as a
+     * tool handler would; any other value is rendered to the model as JSON text.
+     */
     handler: (ctx: CanvasProviderInvokeActionRequest) => Promise<unknown> | unknown;
 }
 /**

package/dist/cjs/cliVersion.js

@@ -22,7 +22,7 @@ __export(cliVersion_exports, {
   COPILOT_CLI_VERSION: () => COPILOT_CLI_VERSION
 });
 module.exports = __toCommonJS(cliVersion_exports);
-const COPILOT_CLI_VERSION = "1.0.92-3";
+const COPILOT_CLI_VERSION = "1.0.92-4";
 const COPILOT_CLI_USE_NPM_PACKAGE = false;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/cjs/client.js

@@ -52,6 +52,7 @@ var import_toolSet = require("./toolSet.js");
 var import_types = require("./types.js");
 const MIN_PROTOCOL_VERSION = 3;
 const RUNTIME_SHUTDOWN_TIMEOUT_MS = 1e4;
+const CLOUD_SESSION_CLEANUP_TIMEOUT_MS = 1e4;
 function createMessageConnection(reader, writer) {
   let dispatch;
   let finishDrain;
@@ -580,6 +581,11 @@ 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 = (0, import_sessionFsProvider.createSessionFsAdapter)(provider);
   }
   setupClientGlobalHandlers() {
@@ -1263,12 +1269,13 @@ 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);
@@ -1391,7 +1398,9 @@ class CopilotClient {
         );
       }
       if (session === void 0) {
+        uninitializedCloudSessionId = returnedSessionId;
         session = initializeSession(returnedSessionId);
+        uninitializedCloudSessionId = void 0;
         registeredId = returnedSessionId;
       }
       this.assignGitHubTokenProvider(gitHubTokenProviderRegistrationId, returnedSessionId);
@@ -1413,6 +1422,20 @@ 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()) {
@@ -1512,8 +1535,8 @@ 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,

package/dist/cjs/generated/rpc.js

@@ -127,7 +127,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: {
@@ -1047,22 +1088,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.
      *
@@ -1670,16 +1744,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 })
     },
@@ -3383,6 +3459,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.
@@ -3535,11 +3638,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}`);

package/dist/cjs/index.js

@@ -32,6 +32,7 @@ __export(index_exports, {
   RuntimeConnection: () => import_types.RuntimeConnection,
   SYSTEM_MESSAGE_SECTIONS: () => import_types2.SYSTEM_MESSAGE_SECTIONS,
   SessionFsSqliteTransactionFailure: () => import_types2.SessionFsSqliteTransactionFailure,
+  SessionFsWriteFailure: () => import_types2.SessionFsWriteFailure,
   ToolSet: () => import_toolSet.ToolSet,
   WorkflowResumeError: () => import_workflow.WorkflowResumeError,
   approveAll: () => import_types2.approveAll,
@@ -68,6 +69,7 @@ var import_types2 = require("./types.js");
   RuntimeConnection,
   SYSTEM_MESSAGE_SECTIONS,
   SessionFsSqliteTransactionFailure,
+  SessionFsWriteFailure,
   ToolSet,
   WorkflowResumeError,
   approveAll,

package/dist/cjs/runtimeArtifacts.js

@@ -51,6 +51,7 @@ const EXCLUDED_TOP_LEVEL = /* @__PURE__ */ new Set([
   "app.js",
   "assets",
   "changelog.json",
+  "cli-main.js",
   "copilot",
   "copilot.exe",
   "foundry-local-sdk",

package/dist/cjs/session.js

@@ -1083,7 +1083,20 @@ class CopilotSession {
     }
     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 && (0, import_schema.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);
+        }
       }
     }
   }
@@ -1678,7 +1691,9 @@ class CopilotSession {
       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) {

package/dist/cjs/sessionFsProvider.js

@@ -19,9 +19,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var sessionFsProvider_exports = {};
 __export(sessionFsProvider_exports, {
   SessionFsSqliteTransactionFailure: () => SessionFsSqliteTransactionFailure,
+  SessionFsWriteFailure: () => SessionFsWriteFailure,
   createSessionFsAdapter: () => createSessionFsAdapter
 });
 module.exports = __toCommonJS(sessionFsProvider_exports);
+const MAX_BINARY_BYTES = (64 * 1024 * 1024 - 1024) / 4 * 3;
+const MAX_BINARY_CONTENT_LENGTH = Math.ceil(MAX_BINARY_BYTES / 3) * 4;
 class SessionFsSqliteTransactionFailure extends Error {
   /** Failure classification reported to the runtime. */
   errorClass;
@@ -31,6 +34,9 @@ class SessionFsSqliteTransactionFailure extends Error {
     this.errorClass = errorClass;
   }
 }
+class SessionFsWriteFailure extends Error {
+  writeChanged = true;
+}
 function normalizeSqliteParams(params) {
   if (!params) {
     return void 0;
@@ -53,10 +59,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);
       }
@@ -194,5 +250,6 @@ function toSqliteTransactionError(err) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SessionFsSqliteTransactionFailure,
+  SessionFsWriteFailure,
   createSessionFsAdapter
 });

package/dist/cjs/types.js

@@ -26,6 +26,7 @@ __export(types_exports, {
   RuntimeConnection: () => RuntimeConnection,
   SYSTEM_MESSAGE_SECTIONS: () => SYSTEM_MESSAGE_SECTIONS,
   SessionFsSqliteTransactionFailure: () => import_sessionFsProvider2.SessionFsSqliteTransactionFailure,
+  SessionFsWriteFailure: () => import_sessionFsProvider3.SessionFsWriteFailure,
   approveAll: () => approveAll,
   convertMcpCallToolResult: () => convertMcpCallToolResult,
   createAttributedPermissionResult: () => createAttributedPermissionResult,
@@ -37,6 +38,7 @@ __export(types_exports, {
 module.exports = __toCommonJS(types_exports);
 var import_sessionFsProvider = require("./sessionFsProvider.js");
 var import_sessionFsProvider2 = require("./sessionFsProvider.js");
+var import_sessionFsProvider3 = require("./sessionFsProvider.js");
 var import_copilotRequestHandler = require("./copilotRequestHandler.js");
 const RuntimeConnection = {
   /**
@@ -138,10 +140,10 @@ const 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) {
@@ -182,6 +184,7 @@ const DisableBypassPermissionsModes = {
   RuntimeConnection,
   SYSTEM_MESSAGE_SECTIONS,
   SessionFsSqliteTransactionFailure,
+  SessionFsWriteFailure,
   approveAll,
   convertMcpCallToolResult,
   createAttributedPermissionResult,

package/dist/cliVersion.d.ts

@@ -1,2 +1,2 @@
-export declare const COPILOT_CLI_VERSION = "1.0.92-3";
+export declare const COPILOT_CLI_VERSION = "1.0.92-4";
 export declare const COPILOT_CLI_USE_NPM_PACKAGE = false;

package/dist/cliVersion.js

@@ -1,4 +1,4 @@
-const COPILOT_CLI_VERSION = "1.0.92-3";
+const COPILOT_CLI_VERSION = "1.0.92-4";
 const COPILOT_CLI_USE_NPM_PACKAGE = false;
 export {
   COPILOT_CLI_USE_NPM_PACKAGE,

package/dist/client.js

@@ -32,6 +32,7 @@ import { ToolSet } from "./toolSet.js";
 import { defaultJoinSessionPermissionHandler } from "./types.js";
 const MIN_PROTOCOL_VERSION = 3;
 const RUNTIME_SHUTDOWN_TIMEOUT_MS = 1e4;
+const CLOUD_SESSION_CLEANUP_TIMEOUT_MS = 1e4;
 function createMessageConnection(reader, writer) {
   let dispatch;
   let finishDrain;
@@ -560,6 +561,11 @@ 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() {
@@ -1243,12 +1249,13 @@ 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);
@@ -1371,7 +1378,9 @@ class CopilotClient {
         );
       }
       if (session === void 0) {
+        uninitializedCloudSessionId = returnedSessionId;
         session = initializeSession(returnedSessionId);
+        uninitializedCloudSessionId = void 0;
         registeredId = returnedSessionId;
       }
       this.assignGitHubTokenProvider(gitHubTokenProviderRegistrationId, returnedSessionId);
@@ -1393,6 +1402,20 @@ 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()) {
@@ -1492,8 +1515,8 @@ 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,