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

package/dist/index.js

@@ -2,6 +2,7 @@ import { CopilotClient } from "./client.js";
 import { RuntimeConnection } from "./types.js";
 import { BuiltInTools, ToolSet } from "./toolSet.js";
 import { CopilotSession } from "./session.js";
+import { defineFactory, FactoryResumeError, isFactoryRunTerminal } from "./factory.js";
 import {
   Canvas,
   CanvasError,
@@ -29,6 +30,7 @@ export {
   CopilotWebSocketCloseStatus,
   CopilotWebSocketForwarder,
   CopilotWebSocketHandler,
+  FactoryResumeError,
   RuntimeConnection,
   SYSTEM_MESSAGE_SECTIONS,
   SessionFsSqliteTransactionFailure,
@@ -37,5 +39,7 @@ export {
   convertMcpCallToolResult,
   createCanvas,
   createSessionFsAdapter,
-  defineTool
+  defineFactory,
+  defineTool,
+  isFactoryRunTerminal
 };

package/dist/session.d.ts

@@ -1,6 +1,7 @@
 import { createSessionRpc } from "./generated/rpc.js";
 import type { OpenCanvasInstance } from "./generated/rpc.js";
 import type { MessageOptions, ContextTier, ReasoningEffort, ReasoningSummary, ModelCapabilitiesOverride, SessionCapabilities, SessionEvent, SessionEventHandler, SessionEventType, SessionUiApi, TypedSessionEventHandler } from "./types.js";
+import { type SessionFactoryApi } from "./factory.js";
 /** Assistant message event - the final response from the assistant. */
 export type AssistantMessageEvent = Extract<SessionEvent, {
     type: "assistant.message";
@@ -45,6 +46,8 @@ export declare class CopilotSession {
     private canvases;
     private bearerTokenProviders;
     private commandHandlers;
+    private factories;
+    private factoryAbortControllers;
     private permissionHandler?;
     private mcpAuthHandler?;
     private userInputHandler?;
@@ -58,6 +61,24 @@ export declare class CopilotSession {
     private _capabilities;
     private openCanvasInstances;
     private disconnected;
+    /**
+     * 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.
+     */
+    readonly factory: SessionFactoryApi;
+    /**
+     * 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.
+     */
+    private waitForFactoryRun;
     /**
      * Typed session-scoped RPC methods.
      */

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