@theokit/sdk 4.53.1 → 4.55.0

package/dist/types/workflow.d.ts

@@ -11,6 +11,20 @@
 import type { ZodType } from "zod";
 import type { SDKAgent } from "./agent.js";
 import type { MessageOrigin } from "./run.js";
+/**
+ * Any node of a committed workflow, discriminated by `kind`.
+ *
+ * Build these with the helpers rather than by hand: `fn()` and `agentStep()` set the discriminator,
+ * validate the id, and parse the retry policy at construction — where a mistake is cheap — while the
+ * builder methods `.parallel()`, `.branch()`, `.foreach()`, `.dowhile()`, `.sleep()` and `.suspend()`
+ * cover the remaining variants and mint a positional default id (`parallel_0`, `branch_1`, ...) when
+ * you do not pass one.
+ *
+ * Every id, nested ones included, must match `^[a-z0-9][a-z0-9_-]*$` case-insensitively and be at
+ * most 64 characters, and must be unique across the whole workflow. `.commit()` walks the tree —
+ * parallel branches, branch predicates, the fallback, and the inner step of a `foreach`/`dowhile` —
+ * and throws {@link WorkflowDuplicateStepIdError} on the second occurrence.
+ */
 export type Step = FnStep | AgentStep | ParallelStep | BranchStep | ForeachStep | DowhileStep | SleepStep | SuspendStep;
 /** A pure function step. */
 export interface FnStep {
@@ -151,6 +165,22 @@ export interface StepContext {
      */
     readonly setState: (next: unknown) => void;
 }
+/**
+ * The outcome of one step, appended to `WorkflowRun.stepResults` in execution order.
+ *
+ * A failing step does not throw out of `run()`. It lands here with `status: "failed"` and its error
+ * flattened to `{ name, message }` — the thrown instance is gone by the time a caller sees it, so
+ * match on `error.name` and never on `instanceof`.
+ *
+ * `"skipped"` occurs only for a `branch` step whose predicates all returned false and which declared
+ * no fallback; its `output` is the step input, passed through unchanged. `"suspended"` marks the step
+ * that called `StepContext.suspend()`, is always the last entry of the run, and carries no output.
+ *
+ * `attempts` means different things per kind. For `fn` and `agent` it counts execution attempts: 1
+ * without a `retry` policy, and 0 when the step failed before its body ran — an `inputSchema`
+ * rejection, a prompt template that threw, a `compensate` v1 refuses, or a cloud agent. For `dowhile`
+ * it counts loop iterations instead.
+ */
 export interface StepResult {
     readonly stepId: string;
     readonly kind: Step["kind"];
@@ -163,6 +193,19 @@ export interface StepResult {
         message: string;
     };
 }
+/**
+ * The terminal record of one run — what `Workflow.run()` resolves to, what `Workflow.resume()`
+ * returns, and what the `result` promise of `Workflow.stream()` settles with.
+ *
+ * Read `status`; do not rely on `catch`. A step that throws does not reject the promise, it ends the
+ * run with `status: "failed"` and the error in `error`. Only `completed` populates `output`; `failed`
+ * and `cancelled` (an aborted `signal`) populate `error`; `suspended` populates neither and means a
+ * snapshot exists under `id` for `Workflow.resume()`. `running` is part of the union for the benefit
+ * of a host tracking a run in flight — the executor only ever assembles a terminal one.
+ *
+ * `stepResults` is cumulative across a resume: the executor seeds it with the snapshot's prior
+ * results, so the record of a resumed run covers the steps that ran before the suspend as well.
+ */
 export interface WorkflowRun<TOutput = unknown> {
     readonly id: string;
     readonly name: string;
@@ -176,6 +219,25 @@ export interface WorkflowRun<TOutput = unknown> {
     readonly endedAt?: number;
     readonly stepResults: ReadonlyArray<StepResult>;
 }
+/**
+ * The persisted state of a suspended run: written when a step calls `StepContext.suspend()`, read
+ * back by `Workflow.resume()`. Callers never construct one — the type is exported so a host can
+ * inspect what the persistence backend wrote.
+ *
+ * Snapshots are single-shot. `resume()` deletes the snapshot before re-entering the executor, so the
+ * same one cannot be resumed twice; a second attempt raises
+ * {@link WorkflowSnapshotNotFoundError}.
+ *
+ * Everything reachable from here must survive `JSON.stringify` — the store serializes on save even
+ * for the memory backend, and raises `WorkflowNotSerializableError` rather than letting a `TypeError`
+ * escape. That rules out BigInt, circular references and class instances in step outputs, in
+ * `accumulatedInput` and in `state`.
+ *
+ * `currentStepId` is the suspending step, and resume continues from the step AFTER it. A workflow
+ * definition edited between suspend and resume therefore either fails with
+ * `WorkflowResumeStepNotFoundError` (the id is gone) or resumes at a position the author did not
+ * intend (the id moved).
+ */
 export interface WorkflowSnapshot {
     /** v1 = pre-SE29 (no `state`); v2 = SE29 (carries `state`). Resume reads both. */
     readonly _schemaVersion: 1 | 2;
@@ -228,11 +290,39 @@ export type WorkflowEvent = {
 export type WorkflowStream<TOutput = unknown> = AsyncIterableIterator<WorkflowEvent> & {
     readonly result: Promise<WorkflowRun<TOutput>>;
 };
+/**
+ * Where suspend snapshots are kept. Omitting `WorkflowOptions.persistence` selects the same store
+ * `backend: "memory"` selects explicitly.
+ *
+ * `"memory"` is one process-wide map shared by every workflow, so a run suspended under it can only
+ * be resumed by the process that suspended it, and only until it exits. `"json"` writes one
+ * `{runId}.json` per snapshot into `dir` through an atomic write and survives a restart. Any suspend
+ * point that waits on a human or an external system needs `"json"`; `"memory"` is for tests and for
+ * suspends resolved within the same process.
+ *
+ * `dir` is required when `backend` is `"json"` and ignored otherwise — `Workflow.create()` rejects
+ * the options up front when it is missing or empty, rather than failing at the first suspend.
+ */
 export interface WorkflowPersistenceOptions {
     readonly backend: "memory" | "json";
     /** Required for `backend: "json"`. */
     readonly dir?: string;
 }
+/**
+ * Configuration for `Workflow.create()`, validated by Zod before the builder is handed back: a `name`
+ * outside 1..128 characters, or `persistence.backend: "json"` without a `dir`, throws there rather
+ * than at run time.
+ *
+ * `name` is an observability and error-message label, not an identity. Two workflows may share one;
+ * the identity behind the single-flight lock is minted per `.commit()` call, so two separately
+ * committed workflows never block each other however they are named.
+ *
+ * The three schemas are independent and each optional: `inputSchema` guards `run(input)` before step
+ * 1, `outputSchema` guards the final value on the completed path only (a suspended or failed run
+ * skips it), and `stateSchema` guards `initialState` plus every `StepContext.setState()` call. All
+ * three must be synchronous — a schema carrying an async refinement is reported as a validation
+ * failure with that explanation, never awaited.
+ */
 export interface WorkflowOptions {
     readonly name: string;
     readonly persistence?: WorkflowPersistenceOptions;
@@ -267,6 +357,19 @@ export interface WorkflowOptions {
     /** Internal — minted at `.commit()`. Not user-facing. */
     readonly workflowId?: string;
 }
+/**
+ * Per-run options for `Workflow.run()` and `Workflow.stream()`.
+ *
+ * `signal` is combined with the run's internal single-flight signal and reaches every step through
+ * `StepContext.signal`. The executor itself checks it at step boundaries, so a step that ignores the
+ * signal runs to completion before the run reports `status: "cancelled"` — a step doing long I/O
+ * should pass `ctx.signal` down to make abort prompt.
+ *
+ * `runId` is minted per call (`wfr-` plus 8 hex) unless you pass it, which is why concurrent runs of
+ * one workflow do not interfere. Pinning it buys a deterministic id for resume, and buys the
+ * single-flight lock with it: starting a second run of the same committed workflow under a `runId`
+ * that is still in flight throws {@link WorkflowAlreadyRunningError}.
+ */
 export interface WorkflowRunOptions {
     readonly signal?: AbortSignal;
     /** Override run ID for deterministic resume (advanced; default = mintRunId). */
@@ -285,6 +388,22 @@ export interface WorkflowRunOptions {
         meta?: Record<string, unknown>;
     };
 }
+/**
+ * Arguments for `Workflow.resume()`.
+ *
+ * `workflow` is typed structurally as `{ run }`, but resume needs more than `run`: it reads the
+ * committed steps and options off the instance and throws a plain `Error` — "Workflow.resume requires
+ * an instance from Workflow.create().commit()" — for anything else. Pass the same committed
+ * `Workflow` the suspended run came from, not a stand-in.
+ *
+ * `runId` selects the snapshot. An id with no snapshot throws
+ * {@link WorkflowSnapshotNotFoundError}.
+ *
+ * `payload` becomes the input of the step after the suspend point, and is parsed against the
+ * suspending step's `payloadSchema` first when it declared one (a mismatch throws out of `resume`).
+ * Omit it to resume from the accumulated input captured in the snapshot instead — the two are
+ * alternatives, not a merge.
+ */
 export interface WorkflowResumeOptions<TI = unknown> {
     readonly runId: string;
     readonly workflow: {
@@ -293,6 +412,14 @@ export interface WorkflowResumeOptions<TI = unknown> {
     readonly payload?: unknown;
     readonly signal?: AbortSignal;
 }
+/**
+ * Thrown by `.commit()` when one step id appears twice anywhere in the workflow — including inside a
+ * parallel branch, a branch predicate, the fallback, and the inner step of a `foreach` or `dowhile`.
+ *
+ * Ids address steps in snapshots and on resume, so this is refused at build time rather than
+ * discovered mid-run. Workflows nested with `workflowStep()` are exempt: the child runs in its own
+ * executor with its own id-space, so its ids cannot collide with the parent's.
+ */
 export declare class WorkflowDuplicateStepIdError extends Error {
     readonly stepId: string;
     readonly name = "WorkflowDuplicateStepIdError";
@@ -348,17 +475,45 @@ export declare class WorkflowNestedError extends Error {
         message: string;
     } | undefined);
 }
+/**
+ * Thrown out of `Workflow.run()` — one of the few workflow failures that rejects instead of arriving
+ * as `run.status === "failed"` — when the committed workflow already has a run in flight under the
+ * same run id.
+ *
+ * The lock key pairs the id minted at `.commit()` with the run id, not `WorkflowOptions.name`, so
+ * two workflows sharing a name are independent and concurrent runs with distinct minted ids never
+ * collide. In practice this only fires when a caller pins `WorkflowRunOptions.runId`, or resumes a
+ * run id that is still executing. The registry is an in-process map: a crash releases every lock, and
+ * it says nothing about runs in other processes.
+ */
 export declare class WorkflowAlreadyRunningError extends Error {
     readonly workflowName: string;
     readonly runId: string;
     readonly name = "WorkflowAlreadyRunningError";
     constructor(workflowName: string, runId: string);
 }
+/**
+ * Thrown by `Workflow.resume()` when no snapshot exists for the given run id.
+ *
+ * The message suggests configuring persistence, which is the common cause but not the only one. The
+ * run may never have suspended; it may have suspended under the default memory backend in a process
+ * that has since exited; or the snapshot may already have been consumed, since resume deletes it
+ * before re-entering the executor and a second resume of the same run id lands here.
+ */
 export declare class WorkflowSnapshotNotFoundError extends Error {
     readonly runId: string;
     readonly name = "WorkflowSnapshotNotFoundError";
     constructor(runId: string);
 }
+/**
+ * Raised when a `dowhile` step's condition kept returning true past `maxIterations` (default 100).
+ *
+ * It does not escape `run()`: the step fails, the run ends `status: "failed"`, and the error reaches
+ * the caller flattened as `run.error` with `name: "WorkflowMaxIterationsExceededError"` — match on
+ * the name, the instance does not survive. The guard is evaluated before each iteration, so the inner
+ * step runs at most `maxIterations` times; raising the ceiling is a `maxIterations` on the step, and
+ * there is no global default to change.
+ */
 export declare class WorkflowMaxIterationsExceededError extends Error {
     readonly stepId: string;
     readonly maxIterations: number;

package/dist/workflow.cjs

@@ -1,100 +1,101 @@
 'use strict';
 
-var chunkFOXKFTVZ_cjs = require('./chunk-FOXKFTVZ.cjs');
-var chunkEZ2YEF4F_cjs = require('./chunk-EZ2YEF4F.cjs');
-require('./chunk-PNVDQL5Y.cjs');
+var chunkGNT35C5U_cjs = require('./chunk-GNT35C5U.cjs');
+var chunkXWL6O3SW_cjs = require('./chunk-XWL6O3SW.cjs');
+require('./chunk-VTYY7XL5.cjs');
 require('./chunk-WJVHMTKB.cjs');
-require('./chunk-C4H6PB5J.cjs');
-require('./chunk-ZT57WTUJ.cjs');
+require('./chunk-R3UPQFKK.cjs');
 require('./chunk-VKJ7V7EB.cjs');
-require('./chunk-LPVIRJVF.cjs');
-require('./chunk-BM6N4KHO.cjs');
+require('./chunk-I6TGFUCO.cjs');
+require('./chunk-K3FW2XZD.cjs');
+require('./chunk-JTB5Q42C.cjs');
+require('./chunk-NUKRL3I6.cjs');
 
 
 
 Object.defineProperty(exports, "Workflow", {
   enumerable: true,
-  get: function () { return chunkFOXKFTVZ_cjs.Workflow; }
+  get: function () { return chunkGNT35C5U_cjs.Workflow; }
 });
 Object.defineProperty(exports, "WorkflowBuilder", {
   enumerable: true,
-  get: function () { return chunkFOXKFTVZ_cjs.WorkflowBuilder; }
+  get: function () { return chunkGNT35C5U_cjs.WorkflowBuilder; }
 });
 Object.defineProperty(exports, "WorkflowToolError", {
   enumerable: true,
-  get: function () { return chunkFOXKFTVZ_cjs.WorkflowToolError; }
+  get: function () { return chunkGNT35C5U_cjs.WorkflowToolError; }
 });
 Object.defineProperty(exports, "agentStep", {
   enumerable: true,
-  get: function () { return chunkFOXKFTVZ_cjs.agentStep; }
+  get: function () { return chunkGNT35C5U_cjs.agentStep; }
 });
 Object.defineProperty(exports, "cloneWorkflow", {
   enumerable: true,
-  get: function () { return chunkFOXKFTVZ_cjs.cloneWorkflow; }
+  get: function () { return chunkGNT35C5U_cjs.cloneWorkflow; }
 });
 Object.defineProperty(exports, "fn", {
   enumerable: true,
-  get: function () { return chunkFOXKFTVZ_cjs.fn; }
+  get: function () { return chunkGNT35C5U_cjs.fn; }
 });
 Object.defineProperty(exports, "workflowAsTool", {
   enumerable: true,
-  get: function () { return chunkFOXKFTVZ_cjs.workflowAsTool; }
+  get: function () { return chunkGNT35C5U_cjs.workflowAsTool; }
 });
 Object.defineProperty(exports, "workflowStep", {
   enumerable: true,
-  get: function () { return chunkFOXKFTVZ_cjs.workflowStep; }
+  get: function () { return chunkGNT35C5U_cjs.workflowStep; }
 });
 Object.defineProperty(exports, "WorkflowAlreadyRunningError", {
   enumerable: true,
-  get: function () { return chunkEZ2YEF4F_cjs.WorkflowAlreadyRunningError; }
+  get: function () { return chunkXWL6O3SW_cjs.WorkflowAlreadyRunningError; }
 });
 Object.defineProperty(exports, "WorkflowCompensateNotImplementedError", {
   enumerable: true,
-  get: function () { return chunkEZ2YEF4F_cjs.WorkflowCompensateNotImplementedError; }
+  get: function () { return chunkXWL6O3SW_cjs.WorkflowCompensateNotImplementedError; }
 });
 Object.defineProperty(exports, "WorkflowDuplicateStepIdError", {
   enumerable: true,
-  get: function () { return chunkEZ2YEF4F_cjs.WorkflowDuplicateStepIdError; }
+  get: function () { return chunkXWL6O3SW_cjs.WorkflowDuplicateStepIdError; }
 });
 Object.defineProperty(exports, "WorkflowInputError", {
   enumerable: true,
-  get: function () { return chunkEZ2YEF4F_cjs.WorkflowInputError; }
+  get: function () { return chunkXWL6O3SW_cjs.WorkflowInputError; }
 });
 Object.defineProperty(exports, "WorkflowMaxIterationsExceededError", {
   enumerable: true,
-  get: function () { return chunkEZ2YEF4F_cjs.WorkflowMaxIterationsExceededError; }
+  get: function () { return chunkXWL6O3SW_cjs.WorkflowMaxIterationsExceededError; }
 });
 Object.defineProperty(exports, "WorkflowNestedError", {
   enumerable: true,
-  get: function () { return chunkEZ2YEF4F_cjs.WorkflowNestedError; }
+  get: function () { return chunkXWL6O3SW_cjs.WorkflowNestedError; }
 });
 Object.defineProperty(exports, "WorkflowNotSerializableError", {
   enumerable: true,
-  get: function () { return chunkEZ2YEF4F_cjs.WorkflowNotSerializableError; }
+  get: function () { return chunkXWL6O3SW_cjs.WorkflowNotSerializableError; }
 });
 Object.defineProperty(exports, "WorkflowOutputError", {
   enumerable: true,
-  get: function () { return chunkEZ2YEF4F_cjs.WorkflowOutputError; }
+  get: function () { return chunkXWL6O3SW_cjs.WorkflowOutputError; }
 });
 Object.defineProperty(exports, "WorkflowParallelError", {
   enumerable: true,
-  get: function () { return chunkEZ2YEF4F_cjs.WorkflowParallelError; }
+  get: function () { return chunkXWL6O3SW_cjs.WorkflowParallelError; }
 });
 Object.defineProperty(exports, "WorkflowResumeStepNotFoundError", {
   enumerable: true,
-  get: function () { return chunkEZ2YEF4F_cjs.WorkflowResumeStepNotFoundError; }
+  get: function () { return chunkXWL6O3SW_cjs.WorkflowResumeStepNotFoundError; }
 });
 Object.defineProperty(exports, "WorkflowSnapshotNotFoundError", {
   enumerable: true,
-  get: function () { return chunkEZ2YEF4F_cjs.WorkflowSnapshotNotFoundError; }
+  get: function () { return chunkXWL6O3SW_cjs.WorkflowSnapshotNotFoundError; }
 });
 Object.defineProperty(exports, "WorkflowStateError", {
   enumerable: true,
-  get: function () { return chunkEZ2YEF4F_cjs.WorkflowStateError; }
+  get: function () { return chunkXWL6O3SW_cjs.WorkflowStateError; }
 });
 Object.defineProperty(exports, "__resetSnapshotStoresForTests", {
   enumerable: true,
-  get: function () { return chunkEZ2YEF4F_cjs.__resetSnapshotStoresForTests; }
+  get: function () { return chunkXWL6O3SW_cjs.__resetSnapshotStoresForTests; }
 });
 //# sourceMappingURL=workflow.cjs.map
 //# sourceMappingURL=workflow.cjs.map