@theokit/sdk 0.0.0-compat-580-20260905204608

package/dist/workflow.d.ts

@@ -0,0 +1,911 @@
+import { ZodType, z } from 'zod';
+import { S as SDKAgent } from './sdk-agent-D4a_BR_6.js';
+import { t as MessageOrigin, C as CustomTool } from './run-CTAdRU3U.js';
+import { T as TheokitAgentError } from './errors-base-B5g01neU.js';
+
+/**
+ * Owner: `internal/workflow/` (15 of 19 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
+ * 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;
+    /**
+     * @deprecated NOT IMPLEMENTED. Setting this does not enable saga rollback — it arms
+     * `WorkflowCompensateNotImplementedError`, so the step FAILS at run time and the message tells you
+     * to remove it. A field whose only effect is to make the step fail is worse than an absent field,
+     * because the type invites it and the cost is discovered in production.
+     *
+     * Kept rather than removed because `FnStep` is published and dropping a member is a major-version
+     * decision. The deprecation is the part that reaches a caller at the point of use: an editor
+     * strikes it through, which the D238 comment that stood here ("slot reserved") did not.
+     */
+    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;
+}
+
+/**
+ * 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;
+
+/**
+ * SE19 — expose a {@link Workflow} as an agent tool.
+ *
+ * Split out of `workflow.ts` because it answers a different question: that file is about BUILDING a
+ * workflow; this one is about handing a built workflow to an agent as a callable. The file-size gate
+ * is what surfaced the seam, and the seam is real — nothing here runs while steps are composed.
+ *
+ * Re-exported from `workflow.ts`, so `@theokit/sdk/workflow` is unchanged.
+ *
+ * NOTE ON THE MODULE TAG: this header deliberately carries no internal-visibility tag, and does not
+ * even name one — TypeScript attaches a file-leading docblock to the FIRST declaration below it, and
+ * `stripInternal: true` (tsconfig.base) then deletes that declaration from the emitted `.d.ts`.
+ * `tsc --noEmit` stays clean and the declaration rollup fails with `"X" is not exported by "..."`.
+ * Measured twice on this file on 2026-09-01: once with the tag, and again when the comment
+ * EXPLAINING the trap quoted the tag verbatim and re-armed it.
+ */
+
+/**
+ * Raised by a {@link workflowAsTool} tool when the wrapped workflow run does not
+ * reach `status: "completed"` (a step failed, the run was cancelled/suspended).
+ * The dispatch converts it to a `tool_result(isError)`.
+ *
+ * @public
+ */
+declare class WorkflowToolError extends TheokitAgentError {
+    readonly toolName: string;
+    readonly workflowStatus: string;
+    readonly workflowError?: {
+        name: string;
+        message: string;
+    } | undefined;
+    readonly name = "WorkflowToolError";
+    readonly code: "workflow_tool_failed";
+    constructor(toolName: string, workflowStatus: string, workflowError?: {
+        name: string;
+        message: string;
+    } | undefined);
+}
+/** Spec for {@link workflowAsTool}. `inputSchema` is the workflow's input shape (Zod). */
+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. */
+    description: string;
+    /** Zod schema for the workflow's input (a `Workflow` carries no top-level schema). */
+    inputSchema: T;
+}
+/**
+ * SE19 — expose a {@link Workflow} as an agent {@link CustomTool}, completing the
+ * "X as tools" trio (tools; agents-as-tools via `defineSubAgent`; workflows-as-tools).
+ * The handler validates the model's args against `spec.inputSchema`, runs the
+ * workflow, and returns its output (a string as-is, else JSON). A run that does not
+ * reach `status: "completed"` raises a typed {@link WorkflowToolError} (workflow
+ * step errors do NOT throw — they surface via `run.status === "failed"`).
+ *
+ * Accepts any `{ run }`-shaped workflow (structural), so it never imports the
+ * `Workflow` class directly.
+ *
+ * @public
+ */
+declare function workflowAsTool<T extends ZodType, TOutput = unknown>(workflow: {
+    run: (input: z.infer<T>) => Promise<WorkflowRun<TOutput>>;
+}, spec: WorkflowAsToolSpec<T>): CustomTool;
+
+/**
+ * The workflow error hierarchy — runtime classes, deliberately NOT in `types/`.
+ *
+ * `types/index.ts` calls itself "the canonical public contract" and re-exports every sibling with
+ * `export type *`, which cannot carry a value; `.dependency-cruiser.cjs` restates the same rule as
+ * "src/types/* are pure type definitions". These twelve classes lived in `types/workflow.ts` anyway
+ * and reached consumers only because the DTS rollup hoists a declaration the runtime bundle never
+ * emitted — the shape that shipped #279 for `isValidTaskId`. `tests/lint/types-are-types-only.test.ts`
+ * is what stops it recurring.
+ *
+ * The home mirrors `task-errors.ts`: errors for one public surface, next to it, at the src root.
+ * Re-exported by name from `workflow.ts`, so `@theokit/sdk/workflow` is unchanged.
+ *
+ * @public
+ */
+
+/**
+ * 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 TheokitAgentError {
+    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 TheokitAgentError {
+    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 TheokitAgentError {
+    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 TheokitAgentError {
+    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 TheokitAgentError {
+    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 TheokitAgentError {
+    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 TheokitAgentError {
+    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 TheokitAgentError {
+    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 TheokitAgentError {
+    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 TheokitAgentError {
+    readonly stepId: string;
+    readonly workflowName: string;
+    readonly name = "WorkflowResumeStepNotFoundError";
+    constructor(stepId: string, workflowName: string);
+}
+/**
+ * Aggregate failure from parallel branches.
+ *
+ * THE ONE PUBLIC WORKFLOW ERROR STILL OUTSIDE THE SDK HIERARCHY, deliberately. Its ten siblings were
+ * reparented onto `TheokitAgentError` so `isTransientError` — and therefore `Retry.create`'s default
+ * predicate — can see them at all. This one cannot follow without ceasing to be an `AggregateError`,
+ * and `instanceof AggregateError` plus the standard `errors` array is the whole reason a caller
+ * catches it: they want the branch failures, not a single message.
+ *
+ * The cost is stated rather than hidden: `isTransientError(err)` is `false` for this class, so a
+ * parallel step whose branches failed transiently is not retried by the SDK's own helper. Inspect
+ * `err.errors` and decide per branch — which is what an aggregate asks of a caller anyway, since
+ * "should this be retried" has no single answer when the branches failed for different reasons.
+ */
+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 TheokitAgentError {
+    readonly stepId: string;
+    readonly name = "WorkflowCompensateNotImplementedError";
+    constructor(stepId: string);
+}
+
+/**
+ * Public `Workflow` class — declarative multi-step orchestration over
+ * `Agent.send`, `Handoff`, `Agent.batch` and friends (Adoption Roadmap #5;
+ * ADRs D230-D248).
+ *
+ * Usage:
+ *
+ *   import { Agent } from "@theokit/sdk";
+ *   import { Workflow, fn, agentStep } from "@theokit/sdk/workflow";
+ *
+ *   const classifier = await Agent.create({ ... });
+ *   const wf = Workflow.create({ name: "demo" })
+ *     .then(fn("validate", (input: { id: string }) => {
+ *       if (!input.id) throw new Error("missing id");
+ *       return input;
+ *     }))
+ *     .then(agentStep("classify", classifier, (i) => `Classify: ${JSON.stringify(i)}`))
+ *     .commit();
+ *
+ *   const run = await wf.run({ id: "x" });
+ *   console.log(run.status, run.output);
+ *
+ * @public
+ */
+
+/**
+ * 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;
+    then<TO = unknown>(step: Step): WorkflowBuilder<TInput, TO>;
+    parallel(branches: ReadonlyArray<ReadonlyArray<Step>>, opts?: {
+        id?: string;
+        concurrency?: number;
+        errorPolicy?: "fail-fast" | "collect";
+    }): WorkflowBuilder<TInput, unknown[]>;
+    branch(predicates: BranchStep["predicates"], opts?: {
+        id?: string;
+        fallback?: ReadonlyArray<Step>;
+    }): WorkflowBuilder<TInput, unknown>;
+    foreach(iterableFrom: string, step: Step, opts?: {
+        id?: string;
+        concurrency?: number;
+    }): WorkflowBuilder<TInput, unknown[]>;
+    dowhile(step: Step, condFn: DowhileStep["condFn"], opts?: {
+        id?: string;
+        maxIterations?: number;
+    }): WorkflowBuilder<TInput, unknown>;
+    sleep(durationMs: number, id?: string): WorkflowBuilder<TInput, TOutput>;
+    suspend(opts?: {
+        id?: string;
+        payloadSchema?: ZodType;
+    }): WorkflowBuilder<TInput, unknown>;
+    commit(): Workflow<TInput, TOutput>;
+    private validateUniqueIds;
+    private assertNotCommitted;
+}
+/**
+ * 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;
+    /**
+     * Construct a workflow builder. Validate options via Zod and return a
+     * `WorkflowBuilder` for fluent chaining. Call `.commit()` to obtain the
+     * immutable `Workflow`.
+     */
+    static create<TI = unknown, TO = unknown>(options: WorkflowOptions): WorkflowBuilder<TI, TO>;
+    /**
+     * theokit#161 — describe this workflow's shape, for a reflection surface.
+     *
+     * Returns `{ name, steps }`, each step carrying its `id` and `kind`, recursing into `parallel`,
+     * `branch`, `foreach` and `dowhile`. Every executable a step holds — predicates, conditions,
+     * agents, prompt templates — is omitted: it cannot cross a process boundary and says nothing about
+     * shape.
+     *
+     * There is deliberately no `Workflow.list()`. A workflow is a value the caller constructs and
+     * holds, so the caller already knows which ones exist; a registry would add process-global state
+     * nothing releases in order to re-answer a question the host can answer itself. A reflection
+     * endpoint maps over its own workflows and calls this.
+     *
+     * @public
+     */
+    describe(): WorkflowDescription;
+    /**
+     * Run this workflow with the given input. Returns a populated
+     * `WorkflowRun`. Errors inside a step DO NOT throw — they propagate via
+     * `run.status === "failed"`.
+     */
+    run(input: TInput, opts?: WorkflowRunOptions): Promise<WorkflowRun<TOutput>>;
+    /**
+     * SE28 — run the workflow and STREAM step-level events as they happen. Returns
+     * an async iterator of {@link WorkflowEvent}s (`step_started` / `step_completed`
+     * / `step_failed` / `workflow_suspended` / `workflow_completed`, top-level
+     * steps) plus a `result` promise resolving to the same terminal
+     * {@link WorkflowRun} `run()` returns. Iterate for progress; await `result` for
+     * the outcome. The stream ends when the run terminates.
+     *
+     * `result` is the AUTHORITATIVE terminal status. Not every terminal state has a
+     * closing event: a step failure emits `step_failed`, but an `outputSchema`
+     * rejection (SE27) or an abort ends the stream WITHOUT `workflow_completed` —
+     * always `await result` to read the final `status`. Consuming order is free:
+     * awaiting `result` without draining, or draining without awaiting `result`,
+     * both work (breaking out of `for await` stops the buffering early).
+     */
+    stream(input: TInput, opts?: WorkflowRunOptions): WorkflowStream<TOutput>;
+    /**
+     * Resume a suspended workflow from its snapshot. Throws
+     * `WorkflowSnapshotNotFoundError` if `runId` is unknown.
+     */
+    static resume<TO = unknown>(opts: WorkflowResumeOptions): Promise<WorkflowRun<TO>>;
+}
+/**
+ * Build a `FnStep`. `id` must match `^[a-z0-9][a-z0-9_-]*$`.
+ */
+declare function fn<I = unknown, O = unknown>(id: string, step: (input: I, ctx: StepContext) => Promise<O> | O, opts?: {
+    inputSchema?: ZodType;
+    outputSchema?: ZodType;
+    retry?: RetryPolicy;
+}): FnStep;
+/**
+ * Build an `AgentStep`. The `promptTemplate` can be a static string or a
+ * function that receives the input and returns the prompt.
+ */
+declare function agentStep(id: string, agent: SDKAgent, promptTemplate: string | ((input: unknown) => string), opts?: {
+    retry?: RetryPolicy;
+    origin?: MessageOrigin;
+}): AgentStep;
+/**
+ * SE30 — use a committed {@link Workflow} as a step inside another workflow.
+ * Wraps the child as an `FnStep` (opaque — the child runs in its OWN executor
+ * with its own id-space, so nested step-ids never collide with the parent's).
+ * The child's output becomes the step output. A non-`completed` child fails the
+ * parent step with a typed {@link WorkflowNestedError}: nested `suspended` is NOT
+ * resumable in v1 (resume continues AFTER the step — the child would be skipped;
+ * use a top-level suspend). See ADR 0010.
+ *
+ * @public
+ */
+declare function workflowStep<TI = unknown, TO = unknown>(child: Workflow<TI, TO>, opts?: {
+    id?: string;
+}): FnStep;
+/**
+ * SE30 — clone a committed workflow under a new id/name. The clone runs
+ * independently (its own single-flight lock + observability identity) with the
+ * same committed steps. Mirrors a peer framework's `cloneWorkflow`.
+ *
+ * @public
+ */
+declare function cloneWorkflow<TI = unknown, TO = unknown>(wf: Workflow<TI, TO>, opts: {
+    id: string;
+}): Workflow<TI, TO>;
+
+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 };