@github/copilot-sdk-win32-x64 1.0.17-preview.3 → 1.0.17-preview.5

package/copilot-sdk/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/copilot-sdk/docs/agent-author.md

@@ -122,10 +122,12 @@ hooks: {
     onSessionStart: async (input, invocation) => { ... },
     onSessionEnd: async (input, invocation) => { ... },
     onErrorOccurred: async (input, invocation) => { ... },
+    onSubagentStart: async (input, invocation) => { ... },
+    onSubagentStop: async (input, invocation) => { ... },
 }
 ```
 
-All hook inputs include `timestamp` (`Date`) and `workingDirectory`.
+All hook inputs include `sessionId`, `timestamp` (`Date`) and `workingDirectory`.
 All handlers receive `invocation: { sessionId: string }` as the second argument.
 All handlers may return `void`/`undefined` (no-op) or an output object.
 
@@ -214,7 +216,32 @@ fire it.
 | `retryCount` | `number` | Max retries (when errorHandling is "retry") |
 | `userNotification` | `string` | Message shown to the user |
 
----
+### onSubagentStart
+
+Fires before a sub-agent's first turn. The input's `sessionId` and the
+invocation's `sessionId` identify the parent session, not the child.
+
+**Input:** `{ sessionId: string, transcriptPath: string, agentName: string, agentDisplayName?: string, agentDescription?: string, timestamp, workingDirectory }`
+
+**Output (optional):**
+| Field | Type | Effect |
+|-------|------|--------|
+| `additionalContext` | `string` | Prepended to the child's initial prompt |
+
+### onSubagentStop
+
+Fires after a sub-agent completes a turn. The input includes the child's last
+assistant `response` and the parent's session metadata. `agentId` is available
+when the task registry supplies one. This is distinct from `onAgentStop`, which
+only runs for the top-level agent.
+
+**Input:** `{ sessionId: string, transcriptPath: string, agentName: string, agentDisplayName?: string, agentDescription?: string, agentId?: string, agentType: string, stopReason: "end_turn", response: string, timestamp, workingDirectory }`
+
+**Output (choose one, or return nothing):**
+| Field | Type | Effect |
+|-------|------|--------|
+| `decision` and `reason` | `"block"` and `string` | Continue the child for another turn using `reason` |
+| `modifiedResponse` | `string` | Replace the child's response reported to the parent |
 
 ## Session Object
 

package/copilot-sdk/extension.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 })
     },
@@ -5896,11 +5972,17 @@ function createSessionRpc(connection, sessionId) {
     /** @experimental */
     mcp: {
       /**
-       * Lists MCP servers configured for the session, their connection status, and host-level state. The host-level state (disabled/filtered servers, failed/needs-auth/pending connections, mcp3p policy, full config) is empty/zero when no MCP host has been initialized for the session.
+       * Lists materialized MCP servers and their connection status. Cache misses may start and wait for MCP servers.
        *
        * @returns MCP servers configured for the session, with their connection status and host-level state.
        */
       list: async () => connection.sendRequest("session.mcp.list", { sessionId }),
+      /**
+       * Lists effective MCP configuration without starting, restarting, authenticating, or waiting for servers. An optional live observation is from an already materialized matching server; this is not a readiness guarantee.
+       *
+       * @returns Effective MCP configuration with optional live observations from matching already materialized servers.
+       */
+      listConfigured: async () => connection.sendRequest("session.mcp.listConfigured", { sessionId }),
       /**
        * Lists the tools exposed by a connected MCP server on this session's host. This performs a live `tools/list` request. Tool UI metadata is returned independently of whether MCP Apps rendering is enabled for the session.
        *
@@ -7407,6 +7489,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 +7668,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 +7871,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 +7882,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 +7907,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);
       }
@@ -9827,7 +10001,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);
+        }
       }
     }
   }
@@ -10422,7 +10609,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) {
@@ -10894,6 +11083,7 @@ var EXCLUDED_TOP_LEVEL = /* @__PURE__ */ new Set([
   "app.js",
   "assets",
   "changelog.json",
+  "cli-main.js",
   "copilot",
   "copilot.exe",
   "foundry-local-sdk",
@@ -11212,6 +11402,7 @@ var ToolSet = class {
 // 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;
@@ -11740,6 +11931,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() {
@@ -12423,12 +12619,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);
@@ -12551,7 +12748,9 @@ var CopilotClient = class _CopilotClient {
         );
       }
       if (session === void 0) {
+        uninitializedCloudSessionId = returnedSessionId;
         session = initializeSession(returnedSessionId);
+        uninitializedCloudSessionId = void 0;
         registeredId = returnedSessionId;
       }
       this.assignGitHubTokenProvider(gitHubTokenProviderRegistrationId, returnedSessionId);
@@ -12573,6 +12772,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()) {
@@ -12672,8 +12885,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,