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

package/dist/cjs/session.js

@@ -29,6 +29,7 @@ var import_telemetry = require("./telemetry.js");
 var import_schema = require("./schema.js");
 var import_types = require("./types.js");
 var import_factory = require("./factory.js");
+var import_workflow = require("./workflow.js");
 function isFactoryResumeErrorCode(value) {
   return value === "not_found" || value === "non_resumable" || value === "already_active" || value === "factory_already_running" || value === "factory_limits_invalid" || value === "factory_session_disposed" || value === "factory_storage_unavailable" || value === "factory_storage_corrupt";
 }
@@ -38,6 +39,15 @@ function copyDefinedFactoryAgentOption(source, target, key) {
     target[key] = value;
   }
 }
+function isWorkflowResumeErrorCode(value) {
+  return value === "not_found" || value === "non_resumable" || value === "workflow_run_not_resumable" || value === "already_active" || value === "workflow_already_running" || value === "workflow_limits_invalid" || value === "workflow_session_disposed" || value === "workflow_storage_unavailable" || value === "workflow_storage_corrupt";
+}
+function copyDefinedWorkflowAgentOption(source, target, key) {
+  const value = source[key];
+  if (value !== void 0) {
+    target[key] = value;
+  }
+}
 const factoryExecutionStore = new import_node_async_hooks.AsyncLocalStorage();
 function throwIfFactoryExecutionIsActive() {
   if (factoryExecutionStore.getStore()?.active) {
@@ -46,6 +56,18 @@ function throwIfFactoryExecutionIsActive() {
     );
   }
 }
+const workflowExecutionStore = new import_node_async_hooks.AsyncLocalStorage();
+function throwIfWorkflowExecutionIsActive() {
+  if (workflowExecutionStore.getStore()?.active) {
+    throw new Error(
+      "workflow.run, workflow.resume, and workflow.pause are not allowed while a workflow body is running on this call path."
+    );
+  }
+}
+function runInWorkflowHelperScope(helperScope, callback) {
+  const current = workflowExecutionStore.getStore();
+  return workflowExecutionStore.run({ active: current?.active ?? false, helperScope }, callback);
+}
 function runInFactoryHelperScope(helperScope, callback) {
   const current = factoryExecutionStore.getStore();
   return factoryExecutionStore.run({ active: current?.active ?? false, helperScope }, callback);
@@ -127,6 +149,54 @@ async function runFactoryPipeline(items, ...stages) {
     })
   );
 }
+async function runWorkflowParallel(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(() => runInWorkflowHelperScope("parallel", thunk)).catch((error) => {
+        if (isFactoryFatalError(error)) {
+          throw error;
+        }
+        return null;
+      })
+    )
+  );
+}
+async function runWorkflowPipeline(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 runInWorkflowHelperScope(
+            "pipeline",
+            () => stage(previous, item, index)
+          );
+        } catch (error) {
+          if (isFactoryFatalError(error)) {
+            throw error;
+          }
+          return null;
+        }
+      }
+      return previous;
+    })
+  );
+}
 class FactoryProgressBuffer {
   constructor(send) {
     this.send = send;
@@ -206,6 +276,85 @@ class FactoryProgressBuffer {
     }
   }
 }
+class WorkflowProgressBuffer {
+  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 workflow 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) {
+      console.warn(
+        "Ignoring a background workflow progress flush failure after the workflow body settled",
+        this.flushError
+      );
+    }
+    if (lines.length > 0) {
+      try {
+        await this.send(lines);
+      } catch (error) {
+        console.warn(
+          "Failed to flush final workflow progress after the workflow 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;
+    }
+  }
+}
 async function awaitFactoryOperation(operation, signal) {
   let rejectAbort;
   const abortPromise = new Promise((_resolve, reject) => {
@@ -220,11 +369,19 @@ async function awaitFactoryOperation(operation, signal) {
     signal.removeEventListener("abort", onAbort);
   }
 }
+async function awaitWorkflowOperation(operation, signal) {
+  return awaitFactoryOperation(operation, signal);
+}
 function throwIfFactoryAborted(signal) {
   if (signal.aborted) {
     throw signal.reason ?? new DOMException("Factory run was aborted", "AbortError");
   }
 }
+function throwIfWorkflowAborted(signal) {
+  if (signal.aborted) {
+    throw signal.reason ?? new DOMException("Workflow run was aborted", "AbortError");
+  }
+}
 function isFactoryAbortError(error) {
   return typeof error === "object" && error !== null && "name" in error && error.name === "AbortError";
 }
@@ -263,6 +420,8 @@ class CopilotSession {
   commandHandlers = /* @__PURE__ */ new Map();
   factories = /* @__PURE__ */ new Map();
   factoryAbortControllers = /* @__PURE__ */ new Map();
+  workflows = /* @__PURE__ */ new Map();
+  workflowAbortControllers = /* @__PURE__ */ new Map();
   permissionHandler;
   mcpAuthHandler;
   userInputHandler;
@@ -346,6 +505,56 @@ class CopilotSession {
     },
     cancel: async (runId) => this.rpc.factory.cancel({ runId })
   };
+  workflow = {
+    run: (async (nameOrHandle, options) => {
+      throwIfWorkflowExecutionIsActive();
+      const name = typeof nameOrHandle === "string" ? nameOrHandle : (0, import_workflow.getWorkflowDefinition)(nameOrHandle).meta.name;
+      const envelope = await this.rpc.workflow.run({
+        name,
+        args: options?.args === void 0 ? {} : options.args,
+        options: {
+          limits: options?.limits,
+          notifyOnComplete: options?.notifyOnComplete,
+          logPhaseNames: options?.logPhaseNames
+        }
+      });
+      return this.settleWorkflowRun(envelope);
+    }),
+    resume: (async (runId, options) => {
+      throwIfWorkflowExecutionIsActive();
+      let response;
+      try {
+        response = await this.rpc.workflow.resume({
+          runId,
+          limits: options?.limits,
+          notifyOnComplete: options?.notifyOnComplete,
+          logPhaseNames: options?.logPhaseNames
+        });
+      } catch (error) {
+        if (error instanceof import_node.ResponseError && typeof error.data === "object" && error.data !== null) {
+          const code = error.data.code;
+          if (isWorkflowResumeErrorCode(code)) {
+            throw new import_workflow.WorkflowResumeError(code, error.message);
+          }
+        }
+        throw error;
+      }
+      return this.settleWorkflowRun(response.run);
+    }),
+    getRun: async (runId) => this.rpc.workflow.getRun({ runId }),
+    waitForRun: (runId, options) => this.waitForWorkflowRun(runId, options?.signal),
+    listRuns: (async (options) => {
+      const page = await this.rpc.workflow.listRuns(options ?? {});
+      return options === void 0 ? page.runs : page;
+    }),
+    getRunDetail: (runId) => this.rpc.workflow.getRunDetail({ runId }),
+    getRunProgress: (runId, options = {}) => this.rpc.workflow.getRunProgress({ runId, ...options }),
+    pause: async (runId) => {
+      throwIfWorkflowExecutionIsActive();
+      return this.rpc.workflow.pause({ runId });
+    },
+    cancel: async (runId) => this.rpc.workflow.cancel({ runId })
+  };
   /**
    * Resolve a start/resume envelope into the terminal envelope callers expect.
    *
@@ -433,6 +642,86 @@ class CopilotSession {
       void read();
     });
   }
+  settleWorkflowRun(envelope) {
+    if ((0, import_workflow.isWorkflowRunTerminal)(envelope.status)) {
+      return Promise.resolve(envelope);
+    }
+    return this.waitForWorkflowRun(envelope.runId);
+  }
+  /**
+   * Resolve when a workflow 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.
+   */
+  waitForWorkflowRun(runId, signal) {
+    const abortError = () => signal?.reason ?? new DOMException("Workflow 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.workflow.getRun({ runId });
+            if ((0, import_workflow.isWorkflowRunTerminal)(envelope.status)) {
+              finish(() => resolve(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.
    */
@@ -695,6 +984,13 @@ class CopilotSession {
       }
     }
     this.factoryAbortControllers.clear();
+    this.workflows.clear();
+    for (const controllersForRun of this.workflowAbortControllers.values()) {
+      for (const controller of controllersForRun.values()) {
+        controller.abort();
+      }
+    }
+    this.workflowAbortControllers.clear();
     this.transformCallbacks?.clear();
   }
   /** @internal */
@@ -1328,6 +1624,192 @@ class CopilotSession {
       }
     };
   }
+  /**
+   * Registers workflow closures and reverse-RPC handlers for this session.
+   *
+   * @param workflows - Workflow handles declared by the joining extension.
+   * @internal Called by the SDK when an extension joins a session.
+   */
+  registerWorkflows(workflows) {
+    this.workflows.clear();
+    if (!workflows || workflows.length === 0) {
+      delete this.clientSessionApis.workflow;
+      return;
+    }
+    for (const handle of workflows) {
+      const definition = (0, import_workflow.getWorkflowDefinition)(handle);
+      if (this.workflows.has(definition.meta.name)) {
+        throw new Error(
+          `Duplicate workflow name "${definition.meta.name}". Workflow names must be unique within a joinSession call.`
+        );
+      }
+      this.workflows.set(definition.meta.name, definition);
+    }
+    const self = this;
+    this.clientSessionApis.workflow = {
+      async execute(params) {
+        const definition = self.workflows.get(params.name);
+        if (!definition) {
+          const message = `No workflow registered with name "${params.name}"`;
+          throw new import_node.ResponseError(import_node.ErrorCodes.InvalidParams, message, {
+            code: "workflow_not_found",
+            name: params.name
+          });
+        }
+        const controller = new AbortController();
+        let controllersForRun = self.workflowAbortControllers.get(params.runId);
+        if (controllersForRun === void 0) {
+          controllersForRun = /* @__PURE__ */ new Map();
+          self.workflowAbortControllers.set(params.runId, controllersForRun);
+        }
+        controllersForRun.set(params.executionToken, controller);
+        const progress = new WorkflowProgressBuffer(async (lines) => {
+          await self.rpc.workflow.log({
+            runId: params.runId,
+            executionToken: params.executionToken,
+            lines
+          });
+        });
+        try {
+          const context = {
+            runId: params.runId,
+            args: params.args,
+            session: self,
+            signal: controller.signal,
+            phase: (title) => {
+              throwIfWorkflowAborted(controller.signal);
+              progress.enqueue("phase", title);
+            },
+            log: (message) => {
+              throwIfWorkflowAborted(controller.signal);
+              progress.enqueue("log", message);
+            },
+            agent: async (prompt, options = {}) => {
+              await progress.flush();
+              const opts = {};
+              for (const key of import_workflow.WORKFLOW_AGENT_OPTION_KEYS) {
+                copyDefinedWorkflowAgentOption(options, opts, key);
+              }
+              const response = await awaitWorkflowOperation(
+                () => self.rpc.workflow.agent({
+                  workflowRunId: params.runId,
+                  executionToken: params.executionToken,
+                  prompt,
+                  opts
+                }),
+                controller.signal
+              );
+              return response.result ?? null;
+            },
+            step: async (key, producer, options = {}) => {
+              await progress.flush();
+              if (options.volatile) {
+                throwIfWorkflowAborted(controller.signal);
+                return producer();
+              }
+              const cached = await awaitWorkflowOperation(
+                () => self.rpc.workflow.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`
+                  );
+                }
+                assertWorkflowStepResult(cached.resultJson, key);
+                return cached.resultJson;
+              }
+              const result2 = await producer();
+              assertWorkflowStepResult(result2, key);
+              await awaitWorkflowOperation(
+                () => self.rpc.workflow.journal.put({
+                  runId: params.runId,
+                  executionToken: params.executionToken,
+                  key,
+                  resultJson: result2
+                }),
+                controller.signal
+              );
+              return result2;
+            },
+            pause: async (key) => {
+              if (typeof key !== "string" || key.length === 0) {
+                throw new Error("Workflow pause checkpoint key must not be empty");
+              }
+              const helperScope = workflowExecutionStore.getStore()?.helperScope;
+              if (helperScope !== void 0) {
+                throw new Error(
+                  `Workflow pause checkpoints are not allowed inside ${helperScope}() branches`
+                );
+              }
+              await progress.flush();
+              const response = await awaitWorkflowOperation(
+                () => self.internalRpc.workflow.pauseAtCheckpoint({
+                  runId: params.runId,
+                  executionToken: params.executionToken,
+                  key
+                }),
+                controller.signal
+              );
+              switch (response.action) {
+                case "continue":
+                  return;
+                case "pause":
+                  await awaitWorkflowOperation(
+                    () => new Promise(() => {
+                    }),
+                    controller.signal
+                  );
+              }
+            },
+            parallel: runWorkflowParallel,
+            pipeline: runWorkflowPipeline,
+            workflow: async () => {
+              throw new Error("nested workflows are not supported");
+            }
+          };
+          const execution = { active: true };
+          const result = await workflowExecutionStore.run(execution, async () => {
+            try {
+              return await definition.run(context);
+            } finally {
+              execution.active = false;
+            }
+          });
+          if (result === void 0) {
+            return {};
+          }
+          assertWorkflowResult(result);
+          return { result };
+        } finally {
+          try {
+            await progress.close();
+          } finally {
+            const controllersForRun2 = self.workflowAbortControllers.get(params.runId);
+            if (controllersForRun2?.get(params.executionToken) === controller) {
+              controllersForRun2.delete(params.executionToken);
+              if (controllersForRun2.size === 0) {
+                self.workflowAbortControllers.delete(params.runId);
+              }
+            }
+          }
+        }
+      },
+      async abort(params) {
+        const controllersForRun = self.workflowAbortControllers.get(params.runId);
+        const controller = controllersForRun?.get(params.executionToken);
+        if (controller !== void 0) {
+          controller.abort(new DOMException("Workflow run was aborted", "AbortError"));
+        }
+        return {};
+      }
+    };
+  }
   /**
    * Registers per-provider {@link BearerTokenProvider} callbacks for BYOK providers
    * configured with managed-identity / on-demand bearer-token auth.
@@ -2022,6 +2504,20 @@ function assertFactoryStepResult(value, key) {
     allowTopLevelUndefined: false
   });
 }
+function assertWorkflowResult(value) {
+  assertStrictJson(value, {
+    code: "workflow_result_not_json",
+    label: "Workflow result",
+    allowTopLevelUndefined: true
+  });
+}
+function assertWorkflowStepResult(value, key) {
+  assertStrictJson(value, {
+    code: "workflow_step_not_json",
+    label: `Workflow step "${key}" result`,
+    allowTopLevelUndefined: false
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CopilotSession

package/dist/cjs/workflow.js

@@ -0,0 +1,134 @@
+"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 workflow_exports = {};
+__export(workflow_exports, {
+  WORKFLOW_AGENT_OPTION_KEYS: () => WORKFLOW_AGENT_OPTION_KEYS,
+  WorkflowResumeError: () => WorkflowResumeError,
+  defineWorkflow: () => defineWorkflow,
+  getWorkflowDefinition: () => getWorkflowDefinition,
+  isWorkflowRunTerminal: () => isWorkflowRunTerminal
+});
+module.exports = __toCommonJS(workflow_exports);
+const WORKFLOW_TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "halted",
+  "paused",
+  "cancelled",
+  "error"
+]);
+function isWorkflowRunTerminal(status) {
+  return WORKFLOW_TERMINAL_STATUSES.has(status);
+}
+const WORKFLOW_AGENT_OPTION_KEYS = [
+  "label",
+  "schema",
+  "model",
+  "reasoningEffort",
+  "contextTier",
+  "agent"
+];
+class WorkflowResumeError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "WorkflowResumeError";
+  }
+  code;
+}
+const workflowHandles = /* @__PURE__ */ new WeakMap();
+const MAX_WORKFLOW_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(`Workflow limit "${field}" must be a positive integer`);
+    }
+  }
+  if (limits.timeoutSeconds !== void 0 && (!Number.isFinite(limits.timeoutSeconds) || limits.timeoutSeconds <= 0)) {
+    throw new Error(
+      'Workflow limit "timeoutSeconds" must be a positive, finite number of seconds'
+    );
+  }
+  if (limits.timeoutSeconds !== void 0 && limits.timeoutSeconds > MAX_WORKFLOW_TIMEOUT_SECONDS) {
+    throw new Error(
+      `Workflow limit "timeoutSeconds" must not exceed ${MAX_WORKFLOW_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(
+        'Workflow 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("Workflow phase titles must not be empty");
+    }
+    if (titles.has(phase.title)) {
+      throw new Error(`Workflow phase title "${phase.title}" is declared more than once`);
+    }
+    titles.add(phase.title);
+  }
+}
+function defineWorkflow(definition) {
+  const meta = deepFreeze(structuredClone(definition.meta));
+  validateLimits(meta);
+  validatePhases(meta);
+  const stored = {
+    meta,
+    run: definition.run
+  };
+  const handle = Object.freeze({ meta });
+  workflowHandles.set(handle, stored);
+  return handle;
+}
+function getWorkflowDefinition(handle) {
+  const definition = workflowHandles.get(handle);
+  if (!definition) {
+    throw new Error("Invalid workflow handle");
+  }
+  return definition;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WORKFLOW_AGENT_OPTION_KEYS,
+  WorkflowResumeError,
+  defineWorkflow,
+  getWorkflowDefinition,
+  isWorkflowRunTerminal
+});