@github/copilot-sdk 1.0.9-preview.0 → 1.0.9-preview.2

package/README.md

@@ -71,6 +71,12 @@ await using session = await client.createSession({
 // session is automatically disconnected when leaving scope
 ```
 
+When targeting MCP tools configured through `mcpServers`, remember the runtime
+tool name is `<server-key>-<tool-name>`. For `availableTools` and
+`excludedTools`, prefer `new ToolSet().addMcp("<server-key>-<tool-name>")` or
+the raw `mcp:<server-key>-<tool-name>` form. For `customAgents[].tools` and
+`defaultAgent.excludedTools`, use `<server-key>-<tool-name>` directly.
+
 ## API Reference
 
 ### CopilotClient
@@ -129,6 +135,7 @@ Create a new conversation session.
 - `tools?: Tool[]` - Custom tools exposed to the CLI. Tools without `handler` are declaration-only and must be resolved via pending tool-call RPCs.
 - `systemMessage?: SystemMessageConfig` - System message customization (see below)
 - `infiniteSessions?: InfiniteSessionConfig` - Configure automatic context compaction (see below)
+- `enableSessionStore?: boolean` - Enables the cross-session store for search and retrieval across sessions. When unset in `"copilot-cli"` mode, the runtime default applies (enabled). In `"empty"` mode, defaults to disabled.
 - `provider?: ProviderConfig` - Custom API provider configuration (BYOK - Bring Your Own Key). See [Custom Providers](#custom-providers) section.
 - `onPermissionRequest?: PermissionHandler` - Optional handler called before each tool execution to approve or deny it. When omitted, permission requests are emitted as events and left pending for manual resolution. Use `approveAll` to allow everything, or provide a custom function for fine-grained control. See [Permission Handling](#permission-handling) section.
 - `onUserInputRequest?: UserInputHandler` - Handler for user input requests from the agent. Enables the `ask_user` tool. See [User Input Requests](#user-input-requests) section.

package/dist/cjs/client.js

@@ -520,9 +520,6 @@ class CopilotClient {
   }
   setupClientGlobalHandlers() {
     const handlers = {};
-    handlers.hooks = {
-      invoke: async (params) => await this.handleHooksInvoke(params)
-    };
     if (this.requestHandler) {
       handlers.llmInference = (0, import_copilotRequestHandler.createCopilotRequestAdapter)(this.requestHandler, () => {
         if (!this.connection) {
@@ -917,7 +914,8 @@ class CopilotClient {
         enableHostGitOperations: false,
         enableSessionStore: false,
         enableSkills: false,
-        memory: { enabled: false }
+        memory: { enabled: false },
+        customAgentsLocalOnly: true
       };
     }
     return {};
@@ -1002,7 +1000,9 @@ class CopilotClient {
     if (!this.connection) {
       await this.start();
     }
-    config = { ...this.configDefaultsForMode(), ...config };
+    const modeDefaults = this.configDefaultsForMode();
+    config = { ...modeDefaults, ...config };
+    config.customAgentsLocalOnly ??= modeDefaults.customAgentsLocalOnly;
     config.systemMessage = this.getSystemMessageConfigForMode(config.systemMessage);
     const callerSessionId = config.sessionId;
     const useServerGeneratedId = config.cloud != null && callerSessionId == null;
@@ -1120,6 +1120,7 @@ class CopilotClient {
         mcpOAuthTokenStorage: config.mcpOAuthTokenStorage,
         envValueMode: "direct",
         customAgents: toWireCustomAgents(config.customAgents),
+        customAgentsLocalOnly: config.customAgentsLocalOnly,
         defaultAgent: config.defaultAgent,
         agent: config.agent,
         configDir: config.configDirectory,
@@ -1203,6 +1204,13 @@ class CopilotClient {
    * ```
    */
   async resumeSession(sessionId, config) {
+    return this.resumeSessionInternal(sessionId, config);
+  }
+  /** @internal */
+  async resumeSessionForExtension(sessionId, config, factories) {
+    return this.resumeSessionInternal(sessionId, config, factories);
+  }
+  async resumeSessionInternal(sessionId, config, factories) {
     if (!this.connection) {
       await this.start();
     }
@@ -1216,6 +1224,7 @@ class CopilotClient {
     session.registerTools(config.tools);
     session.registerCanvases(config.canvases);
     session.registerCommands(config.commands);
+    session.registerFactories(factories);
     const {
       wireProvider: bearerWireProvider,
       wireProviders: bearerWireProviders,
@@ -1240,7 +1249,9 @@ class CopilotClient {
     if (config.hooks) {
       session.registerHooks(config.hooks);
     }
-    config = { ...this.configDefaultsForMode(), ...config };
+    const modeDefaults = this.configDefaultsForMode();
+    config = { ...modeDefaults, ...config };
+    config.customAgentsLocalOnly ??= modeDefaults.customAgentsLocalOnly;
     config.systemMessage = this.getSystemMessageConfigForMode(config.systemMessage);
     const { wirePayload: wireSystemMessage, transformCallbacks } = extractTransformCallbacks(
       config.systemMessage
@@ -1282,6 +1293,7 @@ class CopilotClient {
         })),
         toolSearch: config.toolSearch,
         canvases: config.canvases?.map((canvas) => canvas.declaration),
+        factories: factories?.map((factory) => factory.meta),
         requestCanvasRenderer: config.requestCanvasRenderer,
         requestExtensions: config.requestExtensions,
         extensionSdkPath: config.extensionSdkPath,
@@ -1322,6 +1334,7 @@ class CopilotClient {
         mcpOAuthTokenStorage: config.mcpOAuthTokenStorage,
         envValueMode: "direct",
         customAgents: toWireCustomAgents(config.customAgents),
+        customAgentsLocalOnly: config.customAgentsLocalOnly,
         defaultAgent: config.defaultAgent,
         agent: config.agent,
         skillDirectories: config.skillDirectories,
@@ -2079,6 +2092,12 @@ stderr: ${stderrOutput}`
       return session.clientSessionApis;
     });
     (0, import_rpc.registerClientGlobalApiHandlers)(this.connection, this.clientGlobalHandlers);
+    this.connection.onRequest(
+      "hooks.invoke",
+      async (params) => {
+        return await this.handleHooksInvoke(params);
+      }
+    );
     this.connection.onClose(() => {
       this.state = "disconnected";
     });

package/dist/cjs/extension.js

@@ -20,13 +20,17 @@ var extension_exports = {};
 __export(extension_exports, {
   Canvas: () => import_canvas.Canvas,
   CanvasError: () => import_canvas.CanvasError,
+  FactoryResumeError: () => import_factory.FactoryResumeError,
   createCanvas: () => import_canvas.createCanvas,
+  defineFactory: () => import_factory.defineFactory,
+  isFactoryRunTerminal: () => import_factory.isFactoryRunTerminal,
   joinSession: () => joinSession
 });
 module.exports = __toCommonJS(extension_exports);
 var import_client = require("./client.js");
 var import_types = require("./types.js");
 var import_canvas = require("./canvas.js");
+var import_factory = require("./factory.js");
 async function joinSession(config = {}) {
   const sessionId = process.env.SESSION_ID;
   if (!sessionId) {
@@ -35,18 +39,29 @@ async function joinSession(config = {}) {
     );
   }
   const client = new import_client.CopilotClient({ _internalConnection: { kind: "parent-process" } });
-  const { extensionSdkPath: _stripped, ...rest } = config;
+  const {
+    extensionSdkPath: _stripped,
+    factories,
+    ...rest
+  } = config;
   void _stripped;
-  return client.resumeSession(sessionId, {
-    ...rest,
-    onPermissionRequest: config.onPermissionRequest ?? import_types.defaultJoinSessionPermissionHandler,
-    suppressResumeEvent: config.suppressResumeEvent ?? true
-  });
+  return client.resumeSessionForExtension(
+    sessionId,
+    {
+      ...rest,
+      onPermissionRequest: config.onPermissionRequest ?? import_types.defaultJoinSessionPermissionHandler,
+      suppressResumeEvent: config.suppressResumeEvent ?? true
+    },
+    factories
+  );
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Canvas,
   CanvasError,
+  FactoryResumeError,
   createCanvas,
+  defineFactory,
+  isFactoryRunTerminal,
   joinSession
 });

package/dist/cjs/factory.js

@@ -0,0 +1,123 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var factory_exports = {};
+__export(factory_exports, {
+  FactoryResumeError: () => FactoryResumeError,
+  defineFactory: () => defineFactory,
+  getFactoryDefinition: () => getFactoryDefinition,
+  isFactoryRunTerminal: () => isFactoryRunTerminal
+});
+module.exports = __toCommonJS(factory_exports);
+const FACTORY_TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "halted",
+  "cancelled",
+  "error"
+]);
+function isFactoryRunTerminal(status) {
+  return FACTORY_TERMINAL_STATUSES.has(status);
+}
+class FactoryResumeError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "FactoryResumeError";
+  }
+  code;
+}
+const factoryHandles = /* @__PURE__ */ new WeakMap();
+const MAX_FACTORY_TIMEOUT_SECONDS = 2147483647e-3;
+const NANO_AIU_PER_AIU = 1e9;
+function deepFreeze(value) {
+  if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const nested of Object.values(value)) {
+      deepFreeze(nested);
+    }
+  }
+  return value;
+}
+function validateLimits(meta) {
+  const limits = meta.limits;
+  if (!limits) {
+    return;
+  }
+  for (const field of ["maxConcurrentSubagents", "maxTotalSubagents"]) {
+    const value = limits[field];
+    if (value !== void 0 && (!Number.isInteger(value) || value <= 0)) {
+      throw new Error(`Factory limit "${field}" must be a positive integer`);
+    }
+  }
+  if (limits.timeoutSeconds !== void 0 && (!Number.isFinite(limits.timeoutSeconds) || limits.timeoutSeconds <= 0)) {
+    throw new Error(
+      'Factory limit "timeoutSeconds" must be a positive, finite number of seconds'
+    );
+  }
+  if (limits.timeoutSeconds !== void 0 && limits.timeoutSeconds > MAX_FACTORY_TIMEOUT_SECONDS) {
+    throw new Error(
+      `Factory limit "timeoutSeconds" must not exceed ${MAX_FACTORY_TIMEOUT_SECONDS} seconds`
+    );
+  }
+  if (limits.maxAiCredits !== void 0) {
+    const maxNanoAiu = Math.round(limits.maxAiCredits * NANO_AIU_PER_AIU);
+    if (!Number.isFinite(limits.maxAiCredits) || limits.maxAiCredits <= 0 || !Number.isSafeInteger(maxNanoAiu) || maxNanoAiu < 1) {
+      throw new Error(
+        'Factory limit "maxAiCredits" must be a positive, finite number that rounds to a safe positive integer nano-AIU ceiling'
+      );
+    }
+  }
+}
+function validatePhases(meta) {
+  const titles = /* @__PURE__ */ new Set();
+  for (const phase of meta.phases) {
+    if (phase.title.trim().length === 0) {
+      throw new Error("Factory phase titles must not be empty");
+    }
+    if (titles.has(phase.title)) {
+      throw new Error(`Factory phase title "${phase.title}" is declared more than once`);
+    }
+    titles.add(phase.title);
+  }
+}
+function defineFactory(definition) {
+  const meta = deepFreeze(structuredClone(definition.meta));
+  validateLimits(meta);
+  validatePhases(meta);
+  const stored = {
+    meta,
+    run: definition.run
+  };
+  const handle = Object.freeze({ meta });
+  factoryHandles.set(handle, stored);
+  return handle;
+}
+function getFactoryDefinition(handle) {
+  const definition = factoryHandles.get(handle);
+  if (!definition) {
+    throw new Error("Invalid factory handle");
+  }
+  return definition;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FactoryResumeError,
+  defineFactory,
+  getFactoryDefinition,
+  isFactoryRunTerminal
+});

package/dist/cjs/generated/rpc.js

@@ -2582,11 +2582,6 @@ function registerClientSessionApiHandlers(connection, getHandlers) {
   });
 }
 function registerClientGlobalApiHandlers(connection, handlers) {
-  connection.onRequest("hooks.invoke", async (params) => {
-    const handler = handlers.hooks;
-    if (!handler) throw new Error("No hooks client-global handler registered");
-    return handler.invoke(params);
-  });
   connection.onRequest("llmInference.httpRequestStart", async (params) => {
     const handler = handlers.llmInference;
     if (!handler) throw new Error("No llmInference client-global handler registered");

package/dist/cjs/index.js

@@ -27,6 +27,7 @@ __export(index_exports, {
   CopilotWebSocketCloseStatus: () => import_types2.CopilotWebSocketCloseStatus,
   CopilotWebSocketForwarder: () => import_types2.CopilotWebSocketForwarder,
   CopilotWebSocketHandler: () => import_types2.CopilotWebSocketHandler,
+  FactoryResumeError: () => import_factory.FactoryResumeError,
   RuntimeConnection: () => import_types.RuntimeConnection,
   SYSTEM_MESSAGE_SECTIONS: () => import_types2.SYSTEM_MESSAGE_SECTIONS,
   SessionFsSqliteTransactionFailure: () => import_types2.SessionFsSqliteTransactionFailure,
@@ -35,13 +36,16 @@ __export(index_exports, {
   convertMcpCallToolResult: () => import_types2.convertMcpCallToolResult,
   createCanvas: () => import_canvas.createCanvas,
   createSessionFsAdapter: () => import_types2.createSessionFsAdapter,
-  defineTool: () => import_types2.defineTool
+  defineFactory: () => import_factory.defineFactory,
+  defineTool: () => import_types2.defineTool,
+  isFactoryRunTerminal: () => import_factory.isFactoryRunTerminal
 });
 module.exports = __toCommonJS(index_exports);
 var import_client = require("./client.js");
 var import_types = require("./types.js");
 var import_toolSet = require("./toolSet.js");
 var import_session = require("./session.js");
+var import_factory = require("./factory.js");
 var import_canvas = require("./canvas.js");
 var import_types2 = require("./types.js");
 // Annotate the CommonJS export names for ESM import in node:
@@ -55,6 +59,7 @@ var import_types2 = require("./types.js");
   CopilotWebSocketCloseStatus,
   CopilotWebSocketForwarder,
   CopilotWebSocketHandler,
+  FactoryResumeError,
   RuntimeConnection,
   SYSTEM_MESSAGE_SECTIONS,
   SessionFsSqliteTransactionFailure,
@@ -63,5 +68,7 @@ var import_types2 = require("./types.js");
   convertMcpCallToolResult,
   createCanvas,
   createSessionFsAdapter,
-  defineTool
+  defineFactory,
+  defineTool,
+  isFactoryRunTerminal
 });