@theokit/sdk 1.5.0

package/dist/workflow.d.cts

@@ -0,0 +1,97 @@
+/**
+ * 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
+ */
+import type { ZodType } from "zod";
+import type { SDKAgent } from "./types/agent.js";
+import type { AgentStep, BranchStep, DowhileStep, FnStep, RetryPolicy, Step, StepContext, WorkflowOptions, WorkflowResumeOptions, WorkflowRun, WorkflowRunOptions } from "./types/workflow.js";
+export 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;
+}
+export 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>;
+    /**
+     * 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>>;
+    /**
+     * 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_-]*$`.
+ */
+export 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.
+ */
+export declare function agentStep(id: string, agent: SDKAgent, promptTemplate: string | ((input: unknown) => string), opts?: {
+    retry?: RetryPolicy;
+}): AgentStep;
+export { __resetSnapshotStoresForTests } from "./internal/workflow/snapshot-store.js";
+export type * from "./types/workflow.js";
+export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowMaxIterationsExceededError, WorkflowNotSerializableError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError, } from "./types/workflow.js";

package/dist/workflow.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 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
+ */
+import type { ZodType } from "zod";
+import type { SDKAgent } from "./types/agent.js";
+import type { AgentStep, BranchStep, DowhileStep, FnStep, RetryPolicy, Step, StepContext, WorkflowOptions, WorkflowResumeOptions, WorkflowRun, WorkflowRunOptions } from "./types/workflow.js";
+export 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;
+}
+export 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>;
+    /**
+     * 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>>;
+    /**
+     * 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_-]*$`.
+ */
+export 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.
+ */
+export declare function agentStep(id: string, agent: SDKAgent, promptTemplate: string | ((input: unknown) => string), opts?: {
+    retry?: RetryPolicy;
+}): AgentStep;
+export { __resetSnapshotStoresForTests } from "./internal/workflow/snapshot-store.js";
+export type * from "./types/workflow.js";
+export { WorkflowAlreadyRunningError, WorkflowCompensateNotImplementedError, WorkflowDuplicateStepIdError, WorkflowMaxIterationsExceededError, WorkflowNotSerializableError, WorkflowParallelError, WorkflowResumeStepNotFoundError, WorkflowSnapshotNotFoundError, } from "./types/workflow.js";