@github/copilot-sdk 1.0.8 → 1.0.9-preview.1

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
@@ -751,7 +757,7 @@ The SDK supports custom OpenAI-compatible API providers (BYOK - Bring Your Own K
 - `apiKey?: string` - API key (optional for local providers like Ollama)
 - `bearerToken?: string` - Bearer token for authentication (takes precedence over apiKey)
 - `wireApi?: "completions" | "responses"` - API format for OpenAI/Azure (default: "completions")
-- `azure?.apiVersion?: string` - Azure API version (default: "2024-10-21")
+- `azure?.apiVersion?: string` - Azure API version; when omitted, the runtime uses the GA versionless `v1` route
 
 **Example with Ollama:**
 
@@ -1058,6 +1064,16 @@ const session = await client.createSession({
                 errorHandling: "retry", // "retry", "skip", or "abort"
             };
         },
+
+        // Called when the top-level agent naturally stops
+        onAgentStop: async (input, invocation) => {
+            if (!input.stopHookActive && needsMoreWork()) {
+                return {
+                    decision: "block",
+                    reason: "Run the final validation and fix any failures.",
+                };
+            }
+        },
     },
 });
 ```
@@ -1071,6 +1087,7 @@ const session = await client.createSession({
 - `onSessionStart` - Run logic when a session starts or resumes.
 - `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.
 
 ## Error Handling
 

package/dist/cjs/client.js

@@ -1203,6 +1203,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 +1223,7 @@ class CopilotClient {
     session.registerTools(config.tools);
     session.registerCanvases(config.canvases);
     session.registerCommands(config.commands);
+    session.registerFactories(factories);
     const {
       wireProvider: bearerWireProvider,
       wireProviders: bearerWireProviders,
@@ -1282,6 +1290,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,

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
+});