@github/copilot-sdk 1.0.17-preview.1 → 1.0.17-preview.10

package/dist/cjs/session.js

@@ -38,6 +38,18 @@ function copyDefinedWorkflowAgentOption(source, target, key) {
     target[key] = value;
   }
 }
+function toToolDefinition(tool) {
+  return {
+    name: tool.name,
+    description: tool.description ?? "",
+    parameters: (0, import_schema.toJsonSchema)(tool.parameters),
+    overridesBuiltInTool: tool.overridesBuiltInTool,
+    skipPermission: tool.skipPermission,
+    defer: tool.defer,
+    metadata: tool.metadata,
+    isTerminal: tool.isTerminal
+  };
+}
 const workflowExecutionStore = new import_node_async_hooks.AsyncLocalStorage();
 function throwIfWorkflowExecutionIsActive() {
   if (workflowExecutionStore.getStore()?.active) {
@@ -258,6 +270,8 @@ class CopilotSession {
   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();
@@ -270,6 +284,7 @@ class CopilotSession {
   elicitationHandler;
   exitPlanModeHandler;
   autoModeSwitchHandler;
+  skillProvider;
   hooks;
   transformCallbacks;
   _rpc = null;
@@ -682,6 +697,7 @@ class CopilotSession {
     this.elicitationHandler = void 0;
     this.exitPlanModeHandler = void 0;
     this.autoModeSwitchHandler = void 0;
+    this.skillProvider = void 0;
     this.commandHandlers.clear();
     this.canvases.clear();
     this.workflows.clear();
@@ -1069,7 +1085,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);
+        }
       }
     }
   }
@@ -1575,6 +1604,68 @@ class CopilotSession {
   registerUserInputHandler(handler) {
     this.userInputHandler = handler;
   }
+  /**
+   * Registers the session's skill provider.
+   *
+   * @param provider - The skill provider, or undefined to remove it
+   * @internal This method is typically called internally when creating a session.
+   */
+  registerSkillProvider(provider) {
+    this.skillProvider = provider;
+  }
+  /**
+   * Handles a `skillProvider.list` request from the runtime.
+   *
+   * @internal This method is for internal use by the SDK.
+   */
+  async _handleSkillProviderList(token) {
+    const provider = this.requireSkillProvider();
+    return await this.callSkillProvider("listSkills", token, async (options) => ({
+      skills: await provider.listSkills(options) ?? []
+    }));
+  }
+  /**
+   * Handles a `skillProvider.read` request from the runtime.
+   *
+   * @internal This method is for internal use by the SDK.
+   */
+  async _handleSkillProviderRead(name, token) {
+    const provider = this.requireSkillProvider();
+    return await this.callSkillProvider("readSkill", token, async (options) => ({
+      markdown: await provider.readSkill(name, options) ?? null
+    }));
+  }
+  requireSkillProvider() {
+    if (!this.skillProvider) {
+      throw new Error(`No skill provider for session: ${this.sessionId}`);
+    }
+    return this.skillProvider;
+  }
+  /**
+   * Runs a provider call with an abort signal tied to the runtime's request
+   * cancellation. Failures are logged locally and reported generically.
+   */
+  async callSkillProvider(operation, token, call) {
+    const controller = new AbortController();
+    const subscription = token?.onCancellationRequested(() => controller.abort());
+    if (token?.isCancellationRequested) {
+      controller.abort();
+    }
+    try {
+      return await call({ signal: controller.signal });
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw new import_node.ResponseError(-32800, `Skill provider ${operation} cancelled`);
+      }
+      console.error(`Skill provider ${operation} failed`, {
+        sessionId: this.sessionId,
+        error
+      });
+      throw skillProviderFailure(operation);
+    } finally {
+      subscription?.dispose();
+    }
+  }
   /**
    * Registers hook handlers for session lifecycle events.
    *
@@ -1664,7 +1755,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) {
@@ -1828,6 +1921,59 @@ class CopilotSession {
   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
@@ -1873,6 +2019,9 @@ function toCanvasRpcError(error) {
   const message = error instanceof Error ? error.message : String(error);
   return new import_node.ResponseError(import_node.ErrorCodes.InternalError, message, { code, message });
 }
+function skillProviderFailure(operation) {
+  return new import_node.ResponseError(import_node.ErrorCodes.InternalError, `Skill provider ${operation} failed`);
+}
 function strictJsonValidationError(context, category, message, path) {
   return new import_node.ResponseError(import_node.ErrorCodes.InternalError, message, {
     code: context.code,

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-1";
+export declare const COPILOT_CLI_VERSION = "1.0.93-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-1";
+const COPILOT_CLI_VERSION = "1.0.93-4";
 const COPILOT_CLI_USE_NPM_PACKAGE = false;
 export {
   COPILOT_CLI_USE_NPM_PACKAGE,

package/dist/client.d.ts

@@ -507,6 +507,7 @@ export declare class CopilotClient {
     private handleUserInputRequest;
     private handleExitPlanModeRequest;
     private handleAutoModeSwitchRequest;
+    private resolveSkillProviderSession;
     private handleHooksInvoke;
     private handleSystemMessageTransform;
 }

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() {
@@ -1178,6 +1184,9 @@ class CopilotClient {
     if (config.gitHubToken !== void 0 && config.gitHubTokenProvider !== void 0) {
       throw new Error("gitHubToken and gitHubTokenProvider are mutually exclusive");
     }
+    if (config.cloud != null && config.skillProvider) {
+      throw new Error("Skill providers are not supported for cloud sessions.");
+    }
     if (!this.connection) {
       await this.start();
     }
@@ -1237,18 +1246,22 @@ class CopilotClient {
       if (config.hooks) {
         s.registerHooks(config.hooks);
       }
+      if (config.skillProvider) {
+        s.registerSkillProvider(config.skillProvider);
+      }
       if (transformCallbacks) {
         s.registerTransformCallbacks(transformCallbacks);
       }
       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);
@@ -1342,6 +1355,7 @@ class CopilotClient {
         enableSessionStore: config.enableSessionStore,
         enableSkills: config.enableSkills,
         skillDirectories: config.skillDirectories,
+        ...config.skillProvider ? { hasSkillProvider: true } : {},
         pluginDirectories: config.pluginDirectories,
         instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
@@ -1371,7 +1385,9 @@ class CopilotClient {
         );
       }
       if (session === void 0) {
+        uninitializedCloudSessionId = returnedSessionId;
         session = initializeSession(returnedSessionId);
+        uninitializedCloudSessionId = void 0;
         registeredId = returnedSessionId;
       }
       this.assignGitHubTokenProvider(gitHubTokenProviderRegistrationId, returnedSessionId);
@@ -1393,6 +1409,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()) {
@@ -1479,6 +1509,9 @@ class CopilotClient {
     if (config.hooks) {
       session.registerHooks(config.hooks);
     }
+    if (config.skillProvider) {
+      session.registerSkillProvider(config.skillProvider);
+    }
     const modeDefaults = this.configDefaultsForMode();
     config = { ...modeDefaults, ...config };
     config.customAgentsLocalOnly ??= modeDefaults.customAgentsLocalOnly;
@@ -1492,9 +1525,10 @@ class CopilotClient {
     if (config.onEvent) {
       session.on(config.onEvent);
     }
-    this.sessions.set(sessionId, session);
-    this.setupSessionFs(session, config);
     const toolFilterOptions = this.resolveToolFilterOptions(config);
+    this.setupSessionFs(session, config);
+    const replacedSession = this.sessions.get(sessionId);
+    this.sessions.set(sessionId, session);
     const gitHubTokenProviderRegistrationId = this.registerGitHubTokenProvider(
       config.gitHubTokenProvider,
       sessionId
@@ -1587,6 +1621,7 @@ class CopilotClient {
         defaultAgent: config.defaultAgent,
         agent: config.agent,
         skillDirectories: config.skillDirectories,
+        ...config.skillProvider ? { hasSkillProvider: true } : {},
         pluginDirectories: config.pluginDirectories,
         instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
@@ -1631,7 +1666,13 @@ class CopilotClient {
       this.commitGitHubTokenProvider(sessionId, gitHubTokenProviderRegistrationId);
     } catch (e) {
       session._markDisconnected();
-      this.sessions.delete(sessionId);
+      if (this.sessions.get(sessionId) === session) {
+        if (replacedSession) {
+          this.sessions.set(sessionId, replacedSession);
+        } else {
+          this.sessions.delete(sessionId);
+        }
+      }
       if (gitHubTokenProviderRegistrationId !== void 0) {
         this.githubTokenProviders.delete(gitHubTokenProviderRegistrationId);
       }
@@ -2607,6 +2648,20 @@ stderr: ${stderrOutput}` : ""}`
         return await this.handleHooksInvoke(params);
       }
     );
+    this.connection.onRequest(
+      "skillProvider.list",
+      async (params, token) => await this.resolveSkillProviderSession(params)._handleSkillProviderList(token)
+    );
+    this.connection.onRequest(
+      "skillProvider.read",
+      async (params, token) => {
+        const session = this.resolveSkillProviderSession(params);
+        if (typeof params.name !== "string") {
+          throw new Error("Invalid skillProvider.read payload");
+        }
+        return await session._handleSkillProviderRead(params.name, token);
+      }
+    );
     const connection = this.connection;
     const messageWriter = this.messageWriter;
     const cliProcess = this.isExternalServer ? null : this.cliProcess;
@@ -2763,6 +2818,16 @@ stderr: ${stderrOutput}` : ""}`
     });
     return { response };
   }
+  resolveSkillProviderSession(params) {
+    if (!params || typeof params.sessionId !== "string") {
+      throw new Error("Invalid skillProvider payload");
+    }
+    const session = this.sessions.get(params.sessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${params.sessionId}`);
+    }
+    return session;
+  }
   async handleHooksInvoke(params) {
     if (!params || typeof params.sessionId !== "string" || typeof params.hookType !== "string") {
       throw new Error("Invalid hooks invoke payload");

package/dist/extension.d.ts

@@ -2,7 +2,7 @@ import type { CopilotSession } from "./session.js";
 import { type PermissionHandler, type ResumeSessionConfig } from "./types.js";
 import type { WorkflowHandle } from "./workflow.js";
 export { Canvas, CanvasError, createCanvas, type CanvasAction, type CanvasDeclaration, type CanvasHostContext, type CanvasJsonSchema, type CanvasOptions, } from "./canvas.js";
-export type JoinSessionConfig = Omit<ResumeSessionConfig, "onPermissionRequest" | "extensionSdkPath"> & {
+export type JoinSessionConfig = Omit<ResumeSessionConfig, "onPermissionRequest" | "extensionSdkPath" | "skillProvider"> & {
     onPermissionRequest?: PermissionHandler;
     /**
      * Names of sensitive environment variables this extension needs, such as

package/dist/extension.js

@@ -22,11 +22,13 @@ async function joinSession(config = {}) {
   const client = new CopilotClient({ _internalConnection: { kind: "parent-process" } });
   const {
     extensionSdkPath: _stripped,
+    skillProvider: _strippedSkillProvider,
     workflows,
     requestedEnvironmentVariables,
     ...rest
   } = config;
   void _stripped;
+  void _strippedSkillProvider;
   return client.resumeSessionForExtension(
     sessionId,
     {