@theokit/sdk 2.26.0 → 2.27.0

package/dist/internal/workflow/ctx.d.ts

@@ -11,7 +11,12 @@ export declare class WorkflowSuspendedSentinel extends Error {
     readonly name = "WorkflowSuspendedSentinel";
     constructor(payload?: unknown | undefined);
 }
-export declare function makeStepContext(runId: string, signal: AbortSignal): StepContext;
+/** SE29 — the per-run shared-state seam wired into `StepContext.state`/`setState`. */
+export interface StateController {
+    getState: () => unknown;
+    setState: (next: unknown) => void;
+}
+export declare function makeStepContext(runId: string, signal: AbortSignal, state: StateController): StepContext;
 /**
  * Combine the caller-supplied signal with the flight signal so abort on
  * either side cancels the workflow run.

package/dist/internal/workflow/event-stream.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SE28 — a minimal pushable async iterator for `Workflow.stream()`. The executor
+ * pushes {@link WorkflowEvent}s as steps run; the consumer drains them via
+ * `for await`. Buffers events emitted before the consumer is ready; `end()`
+ * closes the iterator so a pending/next `next()` resolves `done: true`.
+ *
+ * @internal
+ */
+export interface PushableEventStream extends AsyncIterableIterator<WorkflowEvent> {
+    push(event: WorkflowEvent): void;
+    end(): void;
+}
+export declare function createEventStream(): PushableEventStream;

package/dist/internal/workflow/executor-helpers.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Pure helpers extracted from the workflow executor (G8 focus): run assembly,
+ * abort, whole-workflow schema validation (SE27), and the shared-state
+ * controller (SE29). No executor-internal dependencies — safe to import both ways.
+ *
+ * @internal
+ */
+import type { StepResult, WorkflowOptions, WorkflowRun } from "../../types/workflow.js";
+import type { StateController } from "./ctx.js";
+export interface AssembleParams<TO> {
+    runId: string;
+    name: string;
+    status: WorkflowRun["status"];
+    stepResults: ReadonlyArray<StepResult>;
+    startedAt: number;
+    output?: TO;
+    error?: {
+        name: string;
+        message: string;
+    };
+}
+export declare function assembleRun<TO>(params: AssembleParams<TO>): WorkflowRun<TO>;
+export declare function abortRun<T>(name: string, runId: string, startedAt: number, stepResults: StepResult[], signal: AbortSignal): WorkflowRun<T>;
+/**
+ * SE27 — validate a value against a whole-workflow schema. Returns a compact
+ * issues string on failure, `undefined` when the schema is absent or matches.
+ */
+export declare function validateWorkflowSchema(schema: ZodType | undefined, value: unknown): string | undefined;
+/** SE29 — the per-run shared-state holder; `setState` validates against `stateSchema`. */
+export declare function makeStateController(options: WorkflowOptions, initial: unknown): StateController;

package/dist/types/workflow.d.ts

@@ -101,6 +101,19 @@ export interface StepContext {
     };
     /** 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;
 }
 export interface StepResult {
     readonly stepId: string;
@@ -128,15 +141,57 @@ export interface WorkflowRun<TOutput = unknown> {
     readonly stepResults: ReadonlyArray<StepResult>;
 }
 export interface WorkflowSnapshot {
-    readonly _schemaVersion: 1;
+    /** 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
+ */
+export 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
+ */
+export type WorkflowStream<TOutput = unknown> = AsyncIterableIterator<WorkflowEvent> & {
+    readonly result: Promise<WorkflowRun<TOutput>>;
+};
 export interface WorkflowPersistenceOptions {
     readonly backend: "memory" | "json";
     /** Required for `backend: "json"`. */
@@ -145,6 +200,34 @@ export interface WorkflowPersistenceOptions {
 export 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;
 }
@@ -179,6 +262,56 @@ export declare class WorkflowDuplicateStepIdError extends Error {
     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[]`).
+ */
+export 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[]`).
+ */
+export 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.
+ */
+export 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.
+ */
+export 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);
+}
 export declare class WorkflowAlreadyRunningError extends Error {
     readonly workflowName: string;
     readonly runId: string;