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

package/dist/session.js

@@ -11,6 +11,12 @@ import {
   FactoryResumeError,
   isFactoryRunTerminal
 } from "./factory.js";
+import {
+  WORKFLOW_AGENT_OPTION_KEYS,
+  getWorkflowDefinition,
+  WorkflowResumeError,
+  isWorkflowRunTerminal
+} from "./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";
 }
@@ -20,6 +26,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 AsyncLocalStorage();
 function throwIfFactoryExecutionIsActive() {
   if (factoryExecutionStore.getStore()?.active) {
@@ -28,6 +43,18 @@ function throwIfFactoryExecutionIsActive() {
     );
   }
 }
+const workflowExecutionStore = new 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);
@@ -109,6 +136,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;
@@ -188,6 +263,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) => {
@@ -202,11 +356,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";
 }
@@ -245,6 +407,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;
@@ -328,6 +492,56 @@ class CopilotSession {
     },
     cancel: async (runId) => this.rpc.factory.cancel({ runId })
   };
+  workflow = {
+    run: (async (nameOrHandle, options) => {
+      throwIfWorkflowExecutionIsActive();
+      const name = typeof nameOrHandle === "string" ? nameOrHandle : 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 ResponseError && typeof error.data === "object" && error.data !== null) {
+          const code = error.data.code;
+          if (isWorkflowResumeErrorCode(code)) {
+            throw new 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.
    *
@@ -415,6 +629,86 @@ class CopilotSession {
       void read();
     });
   }
+  settleWorkflowRun(envelope) {
+    if (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 (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.
    */
@@ -677,6 +971,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 */
@@ -1310,6 +1611,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 = 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 ResponseError(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 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.
@@ -2004,6 +2491,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
+  });
+}
 export {
   CopilotSession
 };