@theokit/sdk 4.53.1 → 4.55.0

package/dist/workflow.d.ts

@@ -1,3 +1,567 @@
+import { ZodType, z } from 'zod';
+import { u as MessageOrigin, C as CustomTool } from './run-BYSHf58D.js';
+import { S as SDKAgent } from './sdk-agent-D8qJVkuV.js';
+
+/**
+ * Public type contract for `Workflow.create / .run / .resume` (Adoption
+ * Roadmap #5; ADRs D230-D248).
+ *
+ * Step types form a discriminated union by `kind`. Helper factory functions
+ * (`fn()`, `agentStep()`) live in `workflow.ts` and hide the discriminator
+ * from end users.
+ *
+ * @public
+ */
+
+/**
+ * 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.
+ */
+type Step = FnStep | AgentStep | ParallelStep | BranchStep | ForeachStep | DowhileStep | SleepStep | SuspendStep;
+/** A pure function step. */
+interface FnStep {
+    readonly kind: "fn";
+    readonly id: string;
+    readonly fn: (input: unknown, ctx: StepContext) => Promise<unknown> | unknown;
+    readonly inputSchema?: ZodType;
+    readonly outputSchema?: ZodType;
+    readonly retry?: RetryPolicy;
+    /** D238 — slot reserved; runtime throws if engine not yet implemented. */
+    readonly compensate?: (input: unknown, output: unknown, error: Error) => Promise<void> | void;
+}
+/** An agent.send-driven step. */
+interface AgentStep {
+    readonly kind: "agent";
+    readonly id: string;
+    readonly agent: SDKAgent;
+    readonly promptTemplate: string | ((input: unknown) => string);
+    readonly retry?: RetryPolicy;
+    /**
+     * SE3 — provenance stamped onto this step's `agent.send()` (forwarded to
+     * `RunResult.origin`). Squad sets `{ kind: "peer", from: "agent-<i-1>" }` on
+     * every step after the first so a peer-driven turn is attributable.
+     */
+    readonly origin?: MessageOrigin;
+}
+/** N concurrent branches, each its own mini-step-list. */
+interface ParallelStep {
+    readonly kind: "parallel";
+    readonly id: string;
+    readonly branches: ReadonlyArray<ReadonlyArray<Step>>;
+    readonly concurrency?: number;
+    readonly errorPolicy?: "fail-fast" | "collect";
+}
+/** First-match-wins predicates + optional fallback. */
+interface BranchStep {
+    readonly kind: "branch";
+    readonly id: string;
+    readonly predicates: ReadonlyArray<readonly [(input: unknown) => boolean | Promise<boolean>, ReadonlyArray<Step>]>;
+    readonly fallback?: ReadonlyArray<Step>;
+}
+/** Map a step over an upstream array output. */
+interface ForeachStep {
+    readonly kind: "foreach";
+    readonly id: string;
+    /** ID of an upstream top-level step whose output is iterable. */
+    readonly iterableFrom: string;
+    readonly step: Step;
+    readonly concurrency?: number;
+}
+/** Loop a step until condFn returns false. */
+interface DowhileStep {
+    readonly kind: "dowhile";
+    readonly id: string;
+    readonly step: Step;
+    readonly condFn: (output: unknown, iteration: number) => boolean | Promise<boolean>;
+    readonly maxIterations?: number;
+}
+/** Pause for a fixed duration. */
+interface SleepStep {
+    readonly kind: "sleep";
+    readonly id: string;
+    readonly durationMs: number;
+}
+/** Standalone explicit suspend point. */
+interface SuspendStep {
+    readonly kind: "suspend";
+    readonly id: string;
+    readonly payloadSchema?: ZodType;
+}
+/**
+ * theokit#161 — one step of a workflow, as a reflection surface sees it.
+ *
+ * `id` and `kind` are the only fields every step variant shares, and they are what a reflection
+ * endpoint renders. Everything else a step carries is an executable — a predicate, a condition, an
+ * agent, a prompt template — which cannot cross a process boundary and means nothing to a caller
+ * enumerating shape.
+ *
+ * @public
+ */
+interface WorkflowStepDescription {
+    readonly id: string;
+    readonly kind: Step["kind"];
+    /**
+     * Nested steps, for the variants that contain them: `parallel` (all branches, flattened — the
+     * branch grouping is a scheduling detail, not shape a reader needs), `branch` (each predicate's
+     * steps plus the fallback), `foreach` and `dowhile` (their single inner step).
+     *
+     * Absent for leaf steps. A flat list would misreport a parallel or branching workflow as linear.
+     */
+    readonly steps?: readonly WorkflowStepDescription[];
+}
+/**
+ * theokit#161 — the read-only shape of a committed workflow.
+ *
+ * Returned by `Workflow.describe()`. There is deliberately NO workflow registry to enumerate: a
+ * `Workflow` is a value the caller constructs and holds, so the caller already knows which ones
+ * exist. What it lacked was a way to DESCRIBE one. A registry would have added process-global state
+ * that nothing ever releases, to re-answer a question the host can answer itself.
+ *
+ * @public
+ */
+interface WorkflowDescription {
+    readonly name: string;
+    readonly steps: readonly WorkflowStepDescription[];
+}
+/** D237 — retry policy applied per fn/agent step. */
+interface RetryPolicy {
+    /** Total attempts (MIN 1, MAX 20). `1` = no retry. */
+    readonly maxAttempts: number;
+    readonly initialBackoffMs?: number;
+    readonly backoffCoefficient?: number;
+    readonly maximumBackoffMs?: number;
+    readonly nonRetryableErrors?: ReadonlyArray<string>;
+}
+/** D247 — context handed to every step.fn. */
+interface StepContext {
+    readonly runId: string;
+    readonly signal: AbortSignal;
+    readonly log: {
+        debug: (msg: string, attrs?: Record<string, unknown>) => void;
+        info: (msg: string, attrs?: Record<string, unknown>) => void;
+        warn: (msg: string, attrs?: Record<string, unknown>) => void;
+    };
+    /** Pause the workflow; resume via `Workflow.resume({...})`. */
+    readonly suspend: (payload?: unknown) => Promise<never>;
+    /**
+     * SE29 — the workflow's shared state (from `WorkflowOptions.initialState`,
+     * mutated by {@link setState}), visible to every subsequent step in the run.
+     * `undefined` when no `initialState`/`setState` has run. Persisted across
+     * suspend/resume.
+     */
+    readonly state: unknown;
+    /**
+     * SE29 — update the shared state for subsequent steps. Validated against
+     * `WorkflowOptions.stateSchema` when set (a mismatch throws
+     * {@link WorkflowStateError}, which fails the step/run — Rule 8).
+     */
+    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.
+ */
+interface StepResult {
+    readonly stepId: string;
+    readonly kind: Step["kind"];
+    readonly status: "completed" | "failed" | "skipped" | "suspended";
+    readonly attempts: number;
+    readonly durationMs: number;
+    readonly output?: unknown;
+    readonly error?: {
+        name: string;
+        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.
+ */
+interface WorkflowRun<TOutput = unknown> {
+    readonly id: string;
+    readonly name: string;
+    readonly status: "running" | "completed" | "failed" | "suspended" | "cancelled";
+    readonly output?: TOutput;
+    readonly error?: {
+        name: string;
+        message: string;
+    };
+    readonly startedAt: number;
+    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).
+ */
+interface WorkflowSnapshot {
+    /** v1 = pre-SE29 (no `state`); v2 = SE29 (carries `state`). Resume reads both. */
+    readonly _schemaVersion: 1 | 2;
+    readonly runId: string;
+    readonly workflowName: string;
+    readonly currentStepId: string;
+    readonly suspendedPayload?: unknown;
+    readonly stepResults: ReadonlyArray<StepResult>;
+    readonly accumulatedInput: unknown;
+    /** SE29 — shared state captured at suspend (v2). Absent on a v1 snapshot. */
+    readonly state?: unknown;
+    readonly suspendedAt: number;
+}
+/**
+ * SE28 — a step-level workflow event emitted by `Workflow.stream()` as top-level
+ * steps run. Coarse-grained (one event per top-level step; nested
+ * parallel/branch/foreach emit as their single wrapping step), distinct from the
+ * token-delta agent stream. Discriminate on `type`.
+ *
+ * @public
+ */
+type WorkflowEvent = {
+    readonly type: "step_started";
+    readonly stepId: string;
+} | {
+    readonly type: "step_completed";
+    readonly stepId: string;
+    readonly output: unknown;
+} | {
+    readonly type: "step_failed";
+    readonly stepId: string;
+    readonly error: {
+        readonly name: string;
+        readonly message: string;
+    };
+} | {
+    readonly type: "workflow_suspended";
+    readonly stepId: string;
+} | {
+    readonly type: "workflow_completed";
+};
+/**
+ * SE28 — the async iterator returned by `Workflow.stream()`. Yields
+ * {@link WorkflowEvent}s in execution order; `result` resolves to the same
+ * terminal {@link WorkflowRun} the `run()` path returns (the authoritative
+ * outcome — the stream ends when the run terminates).
+ *
+ * @public
+ */
+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.
+ */
+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.
+ */
+interface WorkflowOptions {
+    readonly name: string;
+    readonly persistence?: WorkflowPersistenceOptions;
+    /**
+     * SE27 — Zod schema for the WHOLE workflow's input. When set, `run(input)`
+     * validates `input` BEFORE step 1; a mismatch yields `status: "failed"` with a
+     * typed {@link WorkflowInputError} in `error` (fail-fast, no step runs, no
+     * silent coerce). Absent ⇒ no whole-workflow input validation (unchanged).
+     */
+    readonly inputSchema?: ZodType;
+    /**
+     * SE27 — Zod schema for the workflow's final output. When set, the terminal
+     * `completed` output is validated before `WorkflowRun.output` is populated; a
+     * mismatch yields `status: "failed"` with a typed {@link WorkflowOutputError}.
+     * Only validated on the `completed` path (suspended/failed runs skip it).
+     */
+    readonly outputSchema?: ZodType;
+    /**
+     * SE29 — Zod schema for the workflow's shared state (see `StepContext.state` /
+     * `setState`). When set, `initialState` and every `setState(next)` are
+     * validated against it (a mismatch throws {@link WorkflowStateError}). When
+     * `initialState` is absent, `state` starts as `undefined` and validation fires
+     * on the first `setState` call.
+     */
+    readonly stateSchema?: ZodType;
+    /**
+     * SE29 — the initial shared state, seeded onto `StepContext.state` before
+     * step 1. Validated against `stateSchema` when both are set. Persisted across
+     * suspend/resume.
+     */
+    readonly initialState?: unknown;
+    /** 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}.
+ */
+interface WorkflowRunOptions {
+    readonly signal?: AbortSignal;
+    /** Override run ID for deterministic resume (advanced; default = mintRunId). */
+    readonly runId?: string;
+    /**
+     * Opt-in Task wrapping (ADRs D363, D374). Registers the workflow run
+     * as a `Task` (kind="workflow") with a `wf-` namespaced id (D368,
+     * EC-5). The task transitions terminal when `Workflow.run` resolves.
+     *
+     * Auto-id: `wf-{runId}`.
+     *
+     * @public
+     */
+    readonly task?: true | {
+        id?: string;
+        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.
+ */
+interface WorkflowResumeOptions<TI = unknown> {
+    readonly runId: string;
+    readonly workflow: {
+        run: (input: TI, opts?: WorkflowRunOptions) => Promise<WorkflowRun>;
+    };
+    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.
+ */
+declare class WorkflowDuplicateStepIdError extends Error {
+    readonly stepId: string;
+    readonly name = "WorkflowDuplicateStepIdError";
+    constructor(stepId: string);
+}
+/**
+ * SE27 — the whole-workflow `inputSchema` rejected `run(input)` (before step 1).
+ * `detail` is a pre-formatted issues summary (a string, NOT Zod's `ZodIssue[]`).
+ */
+declare class WorkflowInputError extends Error {
+    readonly workflowName: string;
+    readonly detail: string;
+    readonly name = "WorkflowInputError";
+    constructor(workflowName: string, detail: string);
+}
+/**
+ * SE27 — the whole-workflow `outputSchema` rejected the final output (on `completed`).
+ * `detail` is a pre-formatted issues summary (a string, NOT Zod's `ZodIssue[]`).
+ */
+declare class WorkflowOutputError extends Error {
+    readonly workflowName: string;
+    readonly detail: string;
+    readonly name = "WorkflowOutputError";
+    constructor(workflowName: string, detail: string);
+}
+/**
+ * SE29 — `WorkflowOptions.stateSchema` rejected an `initialState` or a
+ * `setState(next)` call. `detail` is a pre-formatted issues summary.
+ */
+declare class WorkflowStateError extends Error {
+    readonly workflowName: string;
+    readonly detail: string;
+    readonly name = "WorkflowStateError";
+    constructor(workflowName: string, detail: string);
+}
+/**
+ * SE30 — a nested workflow (via `workflowStep`) did not `complete`. A nested
+ * `suspended` is NOT resumable in v1 (resume continues AFTER the step, so the
+ * child would be skipped) — restructure with a top-level suspend. A nested
+ * `failed`/`cancelled` fails the parent step with the child's error attached.
+ */
+declare class WorkflowNestedError extends Error {
+    readonly stepId: string;
+    readonly childName: string;
+    readonly childStatus: Exclude<WorkflowRun["status"], "completed">;
+    readonly childError?: {
+        name: string;
+        message: string;
+    } | undefined;
+    readonly name = "WorkflowNestedError";
+    constructor(stepId: string, childName: string, childStatus: Exclude<WorkflowRun["status"], "completed">, childError?: {
+        name: string;
+        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.
+ */
+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.
+ */
+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.
+ */
+declare class WorkflowMaxIterationsExceededError extends Error {
+    readonly stepId: string;
+    readonly maxIterations: number;
+    readonly name = "WorkflowMaxIterationsExceededError";
+    constructor(stepId: string, maxIterations: number);
+}
+/** EC-4 absorbed — JSON.stringify failed on snapshot payload. */
+declare class WorkflowNotSerializableError extends Error {
+    readonly stepId: string;
+    readonly underlying: Error;
+    readonly name = "WorkflowNotSerializableError";
+    constructor(stepId: string, underlying: Error);
+}
+/** EC-8 absorbed — `currentStepId` from snapshot not found in resumed workflow. */
+declare class WorkflowResumeStepNotFoundError extends Error {
+    readonly stepId: string;
+    readonly workflowName: string;
+    readonly name = "WorkflowResumeStepNotFoundError";
+    constructor(stepId: string, workflowName: string);
+}
+/** Aggregate failure from parallel branches. */
+declare class WorkflowParallelError extends AggregateError {
+    readonly stepId: string;
+    readonly name = "WorkflowParallelError";
+    constructor(errors: ReadonlyArray<Error>, stepId: string);
+}
+/** D238 — saga engine not yet implemented. */
+declare class WorkflowCompensateNotImplementedError extends Error {
+    readonly stepId: string;
+    readonly name = "WorkflowCompensateNotImplementedError";
+    constructor(stepId: string);
+}
+
+/**
+ * Snapshot store interface + InMemory and JsonFile backends (ADR D235).
+ *
+ * EC-4 absorbed: serialization happens here. `JSON.stringify` failure raises
+ * `WorkflowNotSerializableError` instead of letting the underlying `TypeError`
+ * leak.
+ *
+ * @internal
+ */
+
+/** Test seam — clear in-memory store between tests. */
+declare function __resetSnapshotStoresForTests(): void;
+
 /**
  * Public `Workflow` class — declarative multi-step orchestration over
  * `Agent.send`, `Handoff`, `Agent.batch` and friends (Adoption Roadmap #5;
@@ -22,12 +586,51 @@
  *
  * @public
  */
-import type { ZodType } from "zod";
-import { z } from "zod";
-import type { CustomTool, SDKAgent } from "./types/agent.js";
-import type { MessageOrigin } from "./types/run.js";
-import type { AgentStep, BranchStep, DowhileStep, FnStep, RetryPolicy, Step, StepContext, WorkflowDescription, WorkflowOptions, WorkflowResumeOptions, WorkflowRun, WorkflowRunOptions, WorkflowStream } from "./types/workflow.js";
-export declare class WorkflowBuilder<TInput = unknown, TOutput = unknown> {
+
+/**
+ * Fluent step accumulator returned by {@link Workflow.create}. Each method
+ * appends a step and returns the SAME builder (mutated in place, never a copy);
+ * `.commit()` freezes the list into a {@link Workflow} and mints the id its
+ * single-flight lock uses.
+ *
+ *   const wf = Workflow.create({ name: "demo" })
+ *     .then(fn("validate", (i: { id: string }) => i))
+ *     .commit();
+ *
+ * You never construct one directly — `Workflow.create(options)` validates the
+ * options with Zod and hands it back. Import it from `@theokit/sdk/workflow`; the
+ * root `@theokit/sdk` barrel does not export it.
+ *
+ * How it fails:
+ *  - Every appending method throws a plain `Error` after `.commit()` —
+ *    "Workflow already committed; create a fresh Workflow.create(...) call." A
+ *    builder is single-use.
+ *  - A step id is validated on the spot by `sanitizeIdentifier`
+ *    (`^[a-z0-9][a-z0-9-_]*$`, max 64 chars). Every rejection — length, a space,
+ *    `/`, `..`, a leading `-`, a NUL or control char — throws `ConfigurationError`
+ *    with code `invalid_identifier`, not a plain `Error` (#368 collapsed a second
+ *    class that the control-char branch used to raise).
+ *  - `sleep(durationMs)` throws a plain `Error` on a negative or non-finite value.
+ *  - A duplicate id anywhere in the tree, including inside `parallel`, `branch`,
+ *    `foreach` and `dowhile`, throws `WorkflowDuplicateStepIdError` at
+ *    `.commit()` — not at the `.then()` that introduced it.
+ *
+ * Traps:
+ *  - `.then(step)` is a STEP APPENDER, not a promise continuation. That makes the
+ *    builder a JavaScript thenable, so `await Workflow.create({ ... })` — the
+ *    shape `await Agent.create({ ... })` trains you into — is a mistake:
+ *    TypeScript rejects it (TS1320) and plain JavaScript throws an unrelated
+ *    `TypeError: Cannot read properties of undefined (reading 'length')` out of
+ *    the id validator. `Workflow.create` is synchronous.
+ *  - `parallel`, `branch`, `foreach`, `dowhile` and `suspend` widen the output
+ *    type to `unknown` (or `unknown[]`); only `.then<T>()` and `sleep` carry a
+ *    type through. The generics are a convenience, not a checked pipeline —
+ *    nothing verifies that one step's output matches the next step's input.
+ *  - Auto-generated ids are POSITIONAL (`parallel_2`, `foreach_5`), so inserting a
+ *    step earlier renames the later ones. Pass `opts.id` for any step whose id you
+ *    rely on in event streams or resume snapshots.
+ */
+declare class WorkflowBuilder<TInput = unknown, TOutput = unknown> {
     private readonly options;
     private readonly _steps;
     private _committed;
@@ -58,7 +661,53 @@ export declare class WorkflowBuilder<TInput = unknown, TOutput = unknown> {
     private validateUniqueIds;
     private assertNotCommitted;
 }
-export declare class Workflow<TInput = unknown, TOutput = unknown> {
+/**
+ * A committed, immutable workflow: a fixed list of steps you can `run`, `stream`
+ * or `resume`. Built with `Workflow.create(options)` plus `.commit()`; the
+ * constructor is not part of the published surface.
+ *
+ *   import { Workflow, fn } from "@theokit/sdk/workflow";
+ *   const wf = Workflow.create({ name: "demo" })
+ *     .then(fn("validate", (i: { id: string }) => i))
+ *     .commit();
+ *   const run = await wf.run({ id: "x" });   // run.status, run.output
+ *
+ * THE IMPORT SPECIFIER MATTERS. `Workflow` is emitted TWICE — once as the
+ * `@theokit/sdk/workflow` sub-path entry, and once inside the shared chunk behind
+ * the root `@theokit/sdk` barrel. Both declarations carry private fields, so the
+ * two are DISTINCT nominal types and TypeScript refuses to pass one where the
+ * other is expected:
+ *
+ *   Types have separate declarations of a private property '_options'.
+ *
+ * Import `Workflow` — and everything that consumes one, such as `workflowStep`
+ * and `cloneWorkflow` — from `@theokit/sdk/workflow`, and do not mix the two
+ * specifiers in one program. The root barrel re-exports only `Workflow`,
+ * `agentStep` and `fn`; the builder, the step helpers, the error classes and every
+ * workflow type live on the sub-path. (`workflowAsTool` is exempt: it accepts any
+ * `{ run }`-shaped value structurally, so either `Workflow` satisfies it.)
+ *
+ * How it fails: a step that throws does NOT reject `run()`. The promise resolves
+ * with `status: "failed"` and the cause on `run.error`; `"suspended"` and
+ * `"cancelled"` are the other non-`"completed"` terminals, and an `outputSchema`
+ * mismatch also lands as `"failed"` (`WorkflowOutputError`) rather than a throw.
+ * What DOES throw out of `run()` is pre-flight: `WorkflowAlreadyRunningError` when
+ * you pin `WorkflowRunOptions.runId` to one still in flight. `Workflow.resume`
+ * throws `WorkflowSnapshotNotFoundError` for an unknown `runId`.
+ *
+ * Traps:
+ *  - Without an explicit `runId` each call mints its own, so concurrent runs of
+ *    the same committed workflow do NOT collide — the single-flight lock only
+ *    bites when you pin the id yourself.
+ *  - `stream()` reports progress; its `result` promise is the AUTHORITATIVE
+ *    outcome. Not every terminal emits a closing event, so a consumer that only
+ *    drains events can miss a failure. Always `await result`.
+ *  - `run()` and `stream()` load the executor by dynamic `import()`, so the first
+ *    call pays a module load and cannot be made synchronous.
+ *
+ * @public
+ */
+declare class Workflow<TInput = unknown, TOutput = unknown> {
     private readonly _options;
     private readonly _steps;
     /**
@@ -114,7 +763,7 @@ export declare class Workflow<TInput = unknown, TOutput = unknown> {
 /**
  * Build a `FnStep`. `id` must match `^[a-z0-9][a-z0-9_-]*$`.
  */
-export declare function fn<I = unknown, O = unknown>(id: string, step: (input: I, ctx: StepContext) => Promise<O> | O, opts?: {
+declare function fn<I = unknown, O = unknown>(id: string, step: (input: I, ctx: StepContext) => Promise<O> | O, opts?: {
     inputSchema?: ZodType;
     outputSchema?: ZodType;
     retry?: RetryPolicy;
@@ -123,7 +772,7 @@ export declare function fn<I = unknown, O = unknown>(id: string, step: (input: I
  * Build an `AgentStep`. The `promptTemplate` can be a static string or a
  * function that receives the input and returns the prompt.
  */
-export declare function agentStep(id: string, agent: SDKAgent, promptTemplate: string | ((input: unknown) => string), opts?: {
+declare function agentStep(id: string, agent: SDKAgent, promptTemplate: string | ((input: unknown) => string), opts?: {
     retry?: RetryPolicy;
     origin?: MessageOrigin;
 }): AgentStep;
@@ -138,7 +787,7 @@ export declare function agentStep(id: string, agent: SDKAgent, promptTemplate: s
  *
  * @public
  */
-export declare function workflowStep<TI = unknown, TO = unknown>(child: Workflow<TI, TO>, opts?: {
+declare function workflowStep<TI = unknown, TO = unknown>(child: Workflow<TI, TO>, opts?: {
     id?: string;
 }): FnStep;
 /**
@@ -148,12 +797,10 @@ export declare function workflowStep<TI = unknown, TO = unknown>(child: Workflow
  *
  * @public
  */
-export declare function cloneWorkflow<TI = unknown, TO = unknown>(wf: Workflow<TI, TO>, opts: {
+declare function cloneWorkflow<TI = unknown, TO = unknown>(wf: Workflow<TI, TO>, opts: {
     id: string;
 }): Workflow<TI, TO>;
-export { __resetSnapshotStoresForTests } from "./internal/workflow/snapshot-store.js";
-export type * from "./types/workflow.js";
-export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, WorkflowOutputError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError, WorkflowStateError, } from "./types/workflow.js";
+
 /**
  * Raised by a {@link workflowAsTool} tool when the wrapped workflow run does not
  * reach `status: "completed"` (a step failed, the run was cancelled/suspended).
@@ -161,7 +808,7 @@ export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, Wor
  *
  * @public
  */
-export declare class WorkflowToolError extends Error {
+declare class WorkflowToolError extends Error {
     readonly toolName: string;
     readonly workflowStatus: string;
     readonly workflowError?: {
@@ -175,7 +822,7 @@ export declare class WorkflowToolError extends Error {
     } | undefined);
 }
 /** Spec for {@link workflowAsTool}. `inputSchema` is the workflow's input shape (Zod). */
-export interface WorkflowAsToolSpec<T extends ZodType> {
+interface WorkflowAsToolSpec<T extends ZodType> {
     /** Tool name surfaced to the LLM. Same constraints as a `CustomTool.name`. */
     name: string;
     /** Description surfaced to the LLM — when the agent should trigger the workflow. */
@@ -196,6 +843,8 @@ export interface WorkflowAsToolSpec<T extends ZodType> {
  *
  * @public
  */
-export declare function workflowAsTool<T extends ZodType, TOutput = unknown>(workflow: {
+declare function workflowAsTool<T extends ZodType, TOutput = unknown>(workflow: {
     run: (input: z.infer<T>) => Promise<WorkflowRun<TOutput>>;
 }, spec: WorkflowAsToolSpec<T>): CustomTool;
+
+export { type AgentStep, type BranchStep, type DowhileStep, type FnStep, type ForeachStep, type ParallelStep, type RetryPolicy, type SleepStep, type Step, type StepContext, type StepResult, type SuspendStep, Workflow, WorkflowAlreadyRunningError, type WorkflowAsToolSpec, WorkflowBuilder, WorkflowCompensateNotImplementedError, type WorkflowDescription, WorkflowDuplicateStepIdError, type WorkflowEvent, WorkflowInputError, WorkflowMaxIterationsExceededError, WorkflowNestedError, WorkflowNotSerializableError, type WorkflowOptions, WorkflowOutputError, WorkflowParallelError, type WorkflowPersistenceOptions, type WorkflowResumeOptions, WorkflowResumeStepNotFoundError, type WorkflowRun, type WorkflowRunOptions, type WorkflowSnapshot, WorkflowSnapshotNotFoundError, WorkflowStateError, type WorkflowStepDescription, type WorkflowStream, WorkflowToolError, __resetSnapshotStoresForTests, agentStep, cloneWorkflow, fn, workflowAsTool, workflowStep };