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

package/dist/session.js

@@ -2,6 +2,14 @@ import { ConnectionError, ErrorCodes, ResponseError } from "vscode-jsonrpc/node.
 import { createSessionRpc } from "./generated/rpc.js";
 import { CanvasError } from "./canvas.js";
 import { getTraceContext } from "./telemetry.js";
+import {
+  getFactoryDefinition,
+  FactoryResumeError,
+  isFactoryRunTerminal
+} from "./factory.js";
+function isFactoryResumeErrorCode(value) {
+  return value === "not_found" || value === "non_resumable" || value === "already_active" || value === "reapproval_declined" || value === "no_approval_provider";
+}
 function deserializeHookInput(raw) {
   if (!raw || typeof raw !== "object" || typeof raw.timestamp !== "number") {
     return raw;
@@ -22,6 +30,164 @@ function isOpenCanvasInstance(value) {
   const instance = value;
   return typeof instance.instanceId === "string" && instance.instanceId.length > 0 && typeof instance.extensionId === "string" && instance.extensionId.length > 0 && typeof instance.canvasId === "string" && instance.canvasId.length > 0;
 }
+const FACTORY_LOG_FLUSH_DELAY_MS = 10;
+const MAX_FACTORY_FANOUT_ITEMS = 4096;
+function assertFactoryFanoutSize(kind, size) {
+  if (size > MAX_FACTORY_FANOUT_ITEMS) {
+    throw new Error(
+      `${kind}() accepts at most ${MAX_FACTORY_FANOUT_ITEMS} items; got ${size}.`
+    );
+  }
+}
+async function runFactoryParallel(thunks) {
+  if (!Array.isArray(thunks)) {
+    throw new Error(
+      "parallel() expects an array of functions, not promises. Wrap each call: () => agent(...)"
+    );
+  }
+  assertFactoryFanoutSize("parallel", thunks.length);
+  if (thunks.some((thunk) => typeof thunk !== "function")) {
+    throw new Error(
+      "parallel() expects an array of functions, not promises. Wrap each call: () => agent(...)"
+    );
+  }
+  return Promise.all(
+    thunks.map(
+      (thunk) => Promise.resolve().then(() => thunk()).catch((error) => {
+        if (isFactoryFatalError(error)) {
+          throw error;
+        }
+        return null;
+      })
+    )
+  );
+}
+async function runFactoryPipeline(items, ...stages) {
+  if (!Array.isArray(items)) {
+    throw new Error("pipeline(items, ...stages): items must be an array");
+  }
+  assertFactoryFanoutSize("pipeline", items.length);
+  return Promise.all(
+    items.map(async (item, index) => {
+      let previous = item;
+      for (const stage of stages) {
+        try {
+          previous = await stage(previous, item, index);
+        } catch (error) {
+          if (isFactoryFatalError(error)) {
+            throw error;
+          }
+          return null;
+        }
+      }
+      return previous;
+    })
+  );
+}
+class FactoryProgressBuffer {
+  constructor(send) {
+    this.send = send;
+  }
+  send;
+  nextSeq = 0;
+  pending = [];
+  flushTimer;
+  flushTail = Promise.resolve();
+  flushError;
+  flushFailed = false;
+  closed = false;
+  enqueue(kind, text) {
+    if (this.closed) {
+      throw new Error("Cannot log after the factory run has settled");
+    }
+    this.pending.push({ seq: this.nextSeq++, kind, text });
+    this.scheduleFlush();
+  }
+  async flush() {
+    this.clearFlushTimer();
+    const lines = this.pending.splice(0);
+    if (lines.length > 0) {
+      this.flushTail = this.flushTail.then(async () => {
+        try {
+          await this.send(lines);
+        } catch (error) {
+          if (!this.flushFailed) {
+            this.flushFailed = true;
+            this.flushError = error;
+          }
+        }
+      });
+    }
+    await this.flushTail;
+    if (this.flushFailed) {
+      throw this.flushError;
+    }
+  }
+  async close() {
+    this.closed = true;
+    this.clearFlushTimer();
+    const lines = this.pending.splice(0);
+    await this.flushTail;
+    if (this.flushFailed) {
+      throw this.flushError;
+    }
+    if (lines.length > 0) {
+      try {
+        await this.send(lines);
+      } catch (error) {
+        console.warn(
+          "Failed to flush final factory progress after the factory body settled",
+          error
+        );
+      }
+    }
+  }
+  scheduleFlush() {
+    if (this.flushTimer !== void 0) {
+      return;
+    }
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = void 0;
+      void this.flush().catch(() => {
+      });
+    }, FACTORY_LOG_FLUSH_DELAY_MS);
+    this.flushTimer.unref?.();
+  }
+  clearFlushTimer() {
+    if (this.flushTimer !== void 0) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = void 0;
+    }
+  }
+}
+function toPublicFactoryRunResult(envelope) {
+  return envelope;
+}
+async function awaitFactoryOperation(operation, signal) {
+  let rejectAbort;
+  const abortPromise = new Promise((_resolve, reject) => {
+    rejectAbort = reject;
+  });
+  const onAbort = () => rejectAbort?.(signal.reason ?? new DOMException("Factory run was aborted", "AbortError"));
+  signal.addEventListener("abort", onAbort, { once: true });
+  try {
+    throwIfFactoryAborted(signal);
+    return await Promise.race([operation(), abortPromise]);
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+}
+function throwIfFactoryAborted(signal) {
+  if (signal.aborted) {
+    throw signal.reason ?? new DOMException("Factory run was aborted", "AbortError");
+  }
+}
+function isFactoryAbortError(error) {
+  return typeof error === "object" && error !== null && "name" in error && error.name === "AbortError";
+}
+function isFactoryFatalError(error) {
+  return isFactoryAbortError(error) || error instanceof ResponseError || error instanceof ConnectionError;
+}
 const TOOL_SEARCH_TOOL_NAME = "tool_search_tool";
 class CopilotSession {
   /**
@@ -49,6 +215,8 @@ class CopilotSession {
   canvases = /* @__PURE__ */ new Map();
   bearerTokenProviders = /* @__PURE__ */ new Map();
   commandHandlers = /* @__PURE__ */ new Map();
+  factories = /* @__PURE__ */ new Map();
+  factoryAbortControllers = /* @__PURE__ */ new Map();
   permissionHandler;
   mcpAuthHandler;
   userInputHandler;
@@ -64,6 +232,128 @@ class CopilotSession {
   disconnected = false;
   /** @internal Client session API handlers, populated by CopilotClient during create/resume. */
   clientSessionApis = {};
+  /**
+   * Friendly factory API for running registered factories by name or handle.
+   *
+   * @experimental Part of the experimental Agent Factories surface and may
+   * change or be removed in future SDK or CLI releases.
+   */
+  factory = {
+    run: (async (nameOrHandle, options) => {
+      const name = typeof nameOrHandle === "string" ? nameOrHandle : getFactoryDefinition(nameOrHandle).meta.name;
+      if (options?.resumeFromRunId !== void 0) {
+        return this.factory.resume(options.resumeFromRunId, {
+          limits: options.limits
+        });
+      }
+      const envelope = await this.rpc.factory.run({
+        name,
+        args: options?.args === void 0 ? {} : options.args,
+        options: {
+          limits: options?.limits
+        }
+      });
+      return toPublicFactoryRunResult(envelope);
+    }),
+    resume: (async (runId, options) => {
+      let response;
+      try {
+        response = await this.rpc.factory.resume({
+          runId,
+          limits: options?.limits
+        });
+      } catch (error) {
+        if (error instanceof ResponseError && typeof error.data === "object" && error.data !== null) {
+          const code = error.data.code;
+          if (isFactoryResumeErrorCode(code)) {
+            throw new FactoryResumeError(code, error.message);
+          }
+        }
+        throw error;
+      }
+      return toPublicFactoryRunResult(response.run);
+    }),
+    getRun: async (runId) => toPublicFactoryRunResult(await this.rpc.factory.getRun({ runId })),
+    waitForRun: (runId, options) => this.waitForFactoryRun(runId, options?.signal),
+    listRuns: async () => (await this.rpc.factory.listRuns()).runs,
+    getRunDetail: (runId) => this.rpc.factory.getRunDetail({ runId }),
+    getRunProgress: (runId, options = {}) => this.rpc.factory.getRunProgress({ runId, ...options }),
+    cancel: async (runId) => toPublicFactoryRunResult(await this.rpc.factory.cancel({ runId }))
+  };
+  /**
+   * Resolve when a factory run reaches a terminal status.
+   *
+   * The subscription is installed *before* the first read so a transition
+   * landing between the two cannot be missed, and re-reads are serialized so
+   * overlapping invalidation events cannot interleave — the run's revision
+   * advances once per operation, so a burst of events is common and must
+   * collapse into a single in-flight read. A bounded periodic re-read keeps a
+   * dropped invalidation from leaving the wait pending forever.
+   */
+  waitForFactoryRun(runId, signal) {
+    const abortError = () => signal?.reason ?? new DOMException("Factory run wait was aborted", "AbortError");
+    if (signal?.aborted === true) {
+      return Promise.reject(abortError());
+    }
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let reading = false;
+      let rereadRequested = false;
+      let pollHandle;
+      let unsubscribe;
+      let onAbort;
+      const finish = (complete) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        if (pollHandle !== void 0) {
+          clearInterval(pollHandle);
+        }
+        unsubscribe?.();
+        if (onAbort !== void 0) {
+          signal?.removeEventListener("abort", onAbort);
+        }
+        complete();
+      };
+      const read = async () => {
+        if (settled) {
+          return;
+        }
+        if (reading) {
+          rereadRequested = true;
+          return;
+        }
+        reading = true;
+        try {
+          do {
+            rereadRequested = false;
+            const envelope = await this.rpc.factory.getRun({ runId });
+            if (isFactoryRunTerminal(envelope.status)) {
+              finish(() => resolve(toPublicFactoryRunResult(envelope)));
+              return;
+            }
+          } while (rereadRequested && !settled);
+        } catch (error) {
+          finish(() => reject(error));
+        } finally {
+          reading = false;
+        }
+      };
+      if (signal !== void 0) {
+        onAbort = () => finish(() => reject(abortError()));
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+      unsubscribe = this.on("factory.run_updated", (event) => {
+        if (event.data.runId === runId) {
+          void read();
+        }
+      });
+      pollHandle = setInterval(() => void read(), 5e3);
+      pollHandle.unref?.();
+      void read();
+    });
+  }
   /**
    * Typed session-scoped RPC methods.
    */
@@ -178,6 +468,13 @@ class CopilotSession {
     this.autoModeSwitchHandler = void 0;
     this.commandHandlers.clear();
     this.canvases.clear();
+    this.factories.clear();
+    for (const controllersForRun of this.factoryAbortControllers.values()) {
+      for (const controller of controllersForRun.values()) {
+        controller.abort();
+      }
+    }
+    this.factoryAbortControllers.clear();
     this.transformCallbacks?.clear();
   }
   on(eventTypeOrHandler, handler) {
@@ -564,6 +861,157 @@ class CopilotSession {
       }
     };
   }
+  /**
+   * Registers factory closures and reverse-RPC handlers for this session.
+   *
+   * @param factories - Factory handles declared by the joining extension.
+   * @internal Called by the SDK when an extension joins a session.
+   */
+  registerFactories(factories) {
+    this.factories.clear();
+    if (!factories || factories.length === 0) {
+      delete this.clientSessionApis.factory;
+      return;
+    }
+    for (const handle of factories) {
+      const definition = getFactoryDefinition(handle);
+      if (this.factories.has(definition.meta.name)) {
+        throw new Error(
+          `Duplicate factory name "${definition.meta.name}". Factory names must be unique within a joinSession call.`
+        );
+      }
+      this.factories.set(definition.meta.name, definition);
+    }
+    const self = this;
+    this.clientSessionApis.factory = {
+      async execute(params) {
+        const definition = self.factories.get(params.name);
+        if (!definition) {
+          const message = `No factory registered with name "${params.name}"`;
+          throw new ResponseError(ErrorCodes.InvalidParams, message, {
+            code: "factory_not_found",
+            name: params.name
+          });
+        }
+        const controller = new AbortController();
+        let controllersForRun = self.factoryAbortControllers.get(params.runId);
+        if (controllersForRun === void 0) {
+          controllersForRun = /* @__PURE__ */ new Map();
+          self.factoryAbortControllers.set(params.runId, controllersForRun);
+        }
+        controllersForRun.set(params.executionToken, controller);
+        const progress = new FactoryProgressBuffer(async (lines) => {
+          await self.rpc.factory.log({
+            runId: params.runId,
+            executionToken: params.executionToken,
+            lines
+          });
+        });
+        try {
+          const context = {
+            runId: params.runId,
+            args: params.args,
+            session: self,
+            signal: controller.signal,
+            phase: (title) => {
+              throwIfFactoryAborted(controller.signal);
+              progress.enqueue("phase", title);
+            },
+            log: (message) => {
+              throwIfFactoryAborted(controller.signal);
+              progress.enqueue("log", message);
+            },
+            agent: async (prompt, options = {}) => {
+              await progress.flush();
+              const response = await awaitFactoryOperation(
+                () => self.rpc.factory.agent({
+                  factoryRunId: params.runId,
+                  executionToken: params.executionToken,
+                  prompt,
+                  opts: {
+                    label: options.label,
+                    schema: options.schema,
+                    model: options.model
+                  }
+                }),
+                controller.signal
+              );
+              return response.result ?? null;
+            },
+            step: async (key, producer, options = {}) => {
+              await progress.flush();
+              if (options.volatile) {
+                throwIfFactoryAborted(controller.signal);
+                return producer();
+              }
+              const cached = await awaitFactoryOperation(
+                () => self.rpc.factory.journal.get({
+                  runId: params.runId,
+                  executionToken: params.executionToken,
+                  key
+                }),
+                controller.signal
+              );
+              if (cached.hit) {
+                if (cached.resultJson === void 0) {
+                  throw new Error(
+                    `step("${key}") journal returned a hit without a result`
+                  );
+                }
+                assertFactoryStepResult(cached.resultJson, key);
+                return cached.resultJson;
+              }
+              const result2 = await producer();
+              assertFactoryStepResult(result2, key);
+              await awaitFactoryOperation(
+                () => self.rpc.factory.journal.put({
+                  runId: params.runId,
+                  executionToken: params.executionToken,
+                  key,
+                  resultJson: result2
+                }),
+                controller.signal
+              );
+              return result2;
+            },
+            parallel: runFactoryParallel,
+            pipeline: runFactoryPipeline,
+            factory: async () => {
+              throw new Error("nested factories are not supported");
+            }
+          };
+          const result = await definition.run(context);
+          if (result === void 0) {
+            return {};
+          }
+          assertFactoryResult(result);
+          return { result };
+        } finally {
+          try {
+            await progress.close();
+          } finally {
+            const controllersForRun2 = self.factoryAbortControllers.get(params.runId);
+            if (controllersForRun2?.get(params.executionToken) === controller) {
+              controllersForRun2.delete(params.executionToken);
+              if (controllersForRun2.size === 0) {
+                self.factoryAbortControllers.delete(params.runId);
+              }
+            }
+          }
+        }
+      },
+      async abort(params) {
+        const controllersForRun = self.factoryAbortControllers.get(params.runId);
+        if (controllersForRun !== void 0) {
+          const reason = new DOMException("Factory run was aborted", "AbortError");
+          for (const controller of controllersForRun.values()) {
+            controller.abort(reason);
+          }
+        }
+        return {};
+      }
+    };
+  }
   /**
    * Registers per-provider {@link BearerTokenProvider} callbacks for BYOK providers
    * configured with managed-identity / on-demand bearer-token auth.
@@ -1055,6 +1503,151 @@ function toCanvasRpcError(error) {
   const message = error instanceof Error ? error.message : String(error);
   return new ResponseError(ErrorCodes.InternalError, message, { code, message });
 }
+function strictJsonValidationError(context, category, message, path) {
+  return new ResponseError(ErrorCodes.InternalError, message, {
+    code: context.code,
+    category,
+    path
+  });
+}
+function assertStrictJson(value, context) {
+  const ancestors = /* @__PURE__ */ new Set();
+  const visit = (current, path, allowUndefined) => {
+    if (current === void 0) {
+      if (allowUndefined) {
+        return;
+      }
+      throw strictJsonValidationError(
+        context,
+        "nested_undefined",
+        `${context.label} contains nested undefined at ${path}`,
+        path
+      );
+    }
+    if (current === null || typeof current === "boolean" || typeof current === "string") {
+      return;
+    }
+    if (typeof current === "number") {
+      if (!Number.isFinite(current)) {
+        throw strictJsonValidationError(
+          context,
+          "non_finite_number",
+          `${context.label} contains a non-finite number at ${path}`,
+          path
+        );
+      }
+      if (Object.is(current, -0)) {
+        throw strictJsonValidationError(
+          context,
+          "negative_zero",
+          `${context.label} contains negative zero at ${path}; normalize it to 0`,
+          path
+        );
+      }
+      return;
+    }
+    if (typeof current === "function" || typeof current === "symbol" || typeof current === "bigint") {
+      throw strictJsonValidationError(
+        context,
+        "unsupported_type",
+        `${context.label} contains a function, symbol, or BigInt at ${path}`,
+        path
+      );
+    }
+    if (typeof current !== "object") {
+      throw strictJsonValidationError(
+        context,
+        "unsupported_type",
+        `${context.label} contains a function, symbol, or BigInt at ${path}`,
+        path
+      );
+    }
+    if (ancestors.has(current)) {
+      throw strictJsonValidationError(
+        context,
+        "cyclic_value",
+        `${context.label} contains a cyclic reference at ${path}`,
+        path
+      );
+    }
+    ancestors.add(current);
+    try {
+      if (Array.isArray(current)) {
+        const keys = Reflect.ownKeys(current);
+        if (keys.length !== current.length + 1 || keys.some(
+          (key) => key !== "length" && (typeof key !== "string" || !/^(0|[1-9]\d*)$/.test(key) || Number(key) >= current.length)
+        )) {
+          throw strictJsonValidationError(
+            context,
+            "unsupported_object",
+            `${context.label} contains a non-JSON array property at ${path}`,
+            path
+          );
+        }
+        for (let index = 0; index < current.length; index++) {
+          const descriptor = Object.getOwnPropertyDescriptor(current, String(index));
+          if (descriptor === void 0 || !descriptor.enumerable || !("value" in descriptor)) {
+            throw strictJsonValidationError(
+              context,
+              "unsupported_object",
+              `${context.label} contains a non-JSON array property at ${path}[${index}]`,
+              `${path}[${index}]`
+            );
+          }
+          visit(descriptor.value, `${path}[${index}]`, false);
+        }
+        return;
+      }
+      const prototype = Object.getPrototypeOf(current);
+      if (prototype !== Object.prototype && prototype !== null) {
+        throw strictJsonValidationError(
+          context,
+          "unsupported_object",
+          `${context.label} contains a non-JSON object at ${path}`,
+          path
+        );
+      }
+      for (const key of Reflect.ownKeys(current)) {
+        if (typeof key === "symbol") {
+          throw strictJsonValidationError(
+            context,
+            "unsupported_type",
+            `${context.label} contains a function, symbol, or BigInt at ${path}`,
+            path
+          );
+        }
+        const propertyPath = /^[A-Za-z_$][\w$]*$/.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`;
+        const descriptor = Object.getOwnPropertyDescriptor(current, key);
+        if (descriptor === void 0 || !descriptor.enumerable || !("value" in descriptor)) {
+          throw strictJsonValidationError(
+            context,
+            "unsupported_object",
+            `${context.label} contains a non-JSON property at ${propertyPath}`,
+            propertyPath
+          );
+        }
+        visit(descriptor.value, propertyPath, false);
+      }
+    } finally {
+      ancestors.delete(current);
+    }
+  };
+  visit(value, "$", context.allowTopLevelUndefined);
+}
+function assertFactoryResult(value) {
+  assertStrictJson(value, {
+    code: "factory_result_not_json",
+    label: "Factory result",
+    allowTopLevelUndefined: true
+  });
+}
+function assertFactoryStepResult(value, key) {
+  assertStrictJson(value, {
+    code: "factory_step_not_json",
+    label: `Factory step "${key}" result`,
+    allowTopLevelUndefined: false
+  });
+}
 export {
   CopilotSession
 };

package/dist/types.d.ts

@@ -1525,6 +1525,45 @@ export interface CanvasProviderIdentity {
     /** Optional display name surfaced as the canvas extension name. */
     name?: string;
 }
+/**
+ * Static resource ceilings declared by a factory before it runs.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface FactoryLimits {
+    /** Maximum number of factory subagents that may run concurrently. Must be positive when present. */
+    maxConcurrentSubagents?: number;
+    /** Maximum total number of factory subagents that may be spawned. Must be positive when present. */
+    maxTotalSubagents?: number;
+    /** Maximum AI credits consumed by factory subagents and descendants. This post-paid ceiling is soft. */
+    maxAiCredits?: number;
+    /**
+     * Maximum accumulated active-execution time, in seconds. Active execution includes the entire extension body,
+     * subprocess waits, queued-agent waits, and sleeps. The limit is armed from the remaining headroom when a run
+     * resumes; time between attempts is not counted. Must be finite and positive when present.
+     */
+    timeoutSeconds?: number;
+}
+/**
+ * Registration metadata for an extension-authored factory.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface FactoryMeta {
+    /** Stable factory name used for invocation. */
+    name: string;
+    /** Human-readable factory description. */
+    description: string;
+    /** Display metadata for the progress phases the factory may report. */
+    phases: Array<{
+        title: string;
+        detail?: string;
+    }>;
+    /** Optional resource ceilings presented to the user before execution. */
+    limits?: FactoryLimits;
+}
 /**
  * Provider-scoped options for the Copilot API (CAPI).
  *
@@ -1631,13 +1670,8 @@ export interface SessionConfigBase {
      */
     configDirectory?: string;
     /**
-     * When true, automatically discovers MCP server configurations (e.g. `.mcp.json`,
-     * `.vscode/mcp.json`) and skill directories from the working directory and merges
-     * them with any explicitly provided `mcpServers` and `skillDirectories`, with
-     * explicit values taking precedence on name collision.
-     *
-     * Note: custom instruction files (`.github/copilot-instructions.md`, `AGENTS.md`, etc.)
-     * are always loaded from the working directory regardless of this setting.
+     * Enables runtime discovery of supported configuration. Explicitly supplied
+     * configuration takes precedence over discovered values.
      *
      * @default false
      */

package/docs/extensions.md

@@ -56,4 +56,5 @@ The `session` object provides methods for sending messages, logging to the timel
 ## Further Reading
 
 - `examples.md` — Practical code examples for tools, hooks, events, and complete extensions
+- `factories.md`: Authoring, running, resuming, and observing Agent Factories
 - `agent-author.md` — Step-by-step workflow for agents authoring extensions programmatically