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

package/dist/cjs/session.js

@@ -25,6 +25,10 @@ var import_node = require("vscode-jsonrpc/node.js");
 var import_rpc = require("./generated/rpc.js");
 var import_canvas = require("./canvas.js");
 var import_telemetry = require("./telemetry.js");
+var import_factory = require("./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;
@@ -45,6 +49,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 import_node.ResponseError || error instanceof import_node.ConnectionError;
+}
 const TOOL_SEARCH_TOOL_NAME = "tool_search_tool";
 class CopilotSession {
   /**
@@ -72,6 +234,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;
@@ -87,6 +251,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 : (0, import_factory.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 import_node.ResponseError && typeof error.data === "object" && error.data !== null) {
+          const code = error.data.code;
+          if (isFactoryResumeErrorCode(code)) {
+            throw new import_factory.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 ((0, import_factory.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.
    */
@@ -201,6 +487,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) {
@@ -587,6 +880,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 = (0, import_factory.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 import_node.ResponseError(import_node.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.
@@ -1078,6 +1522,151 @@ 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 strictJsonValidationError(context, category, message, path) {
+  return new import_node.ResponseError(import_node.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
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CopilotSession

package/dist/client.d.ts

@@ -224,6 +224,7 @@ export declare class CopilotClient {
      * ```
      */
     resumeSession(sessionId: string, config: ResumeSessionConfig): Promise<CopilotSession>;
+    private resumeSessionInternal;
     /**
      * Sends a ping request to the server to verify connectivity.
      *

package/dist/client.js

@@ -1180,6 +1180,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();
     }
@@ -1193,6 +1200,7 @@ class CopilotClient {
     session.registerTools(config.tools);
     session.registerCanvases(config.canvases);
     session.registerCommands(config.commands);
+    session.registerFactories(factories);
     const {
       wireProvider: bearerWireProvider,
       wireProviders: bearerWireProviders,
@@ -1259,6 +1267,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/extension.d.ts

@@ -1,10 +1,19 @@
 import type { CopilotSession } from "./session.js";
-import { type ExtensionInfo, type PermissionHandler, type ResumeSessionConfig } from "./types.js";
+import { type PermissionHandler, type ResumeSessionConfig } from "./types.js";
+import type { FactoryHandle } from "./factory.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"> & {
     onPermissionRequest?: PermissionHandler;
+    /**
+     * Factory handles to register when the extension joins the session.
+     *
+     * @experimental Part of the experimental Agent Factories surface and may
+     * change or be removed in future SDK or CLI releases.
+     */
+    factories?: FactoryHandle[];
 };
-export type { ExtensionInfo };
+export type { ExtensionInfo, FactoryLimits, FactoryMeta } from "./types.js";
+export { defineFactory, FactoryResumeError, isFactoryRunTerminal, type RunOptions, type ResumeOptions, type FactoryResumeErrorCode, type SessionFactoryApi, type FactoryAgentOptions, type FactoryContext, type FactoryDefinition, type FactoryHandle, type FactoryJsonSchema, type JsonValue, type FactoryPipelineStage, type FactoryStepOptions, type FactoryRunResult, type FactoryRunStatus, type FactoryRunSummary, type FactoryRunDetail, type FactoryProgressPage, type FactoryProgressLine, type FactoryPhaseObservation, type FactoryPhaseStatus, type FactoryAgentSummary, } from "./factory.js";
 /**
  * Joins the current foreground session.
  *