Workflows

export interface AgentStep<TState> {
    name: string;
    agent: Agent;
    inputFrom?: (state: TState) => string;
}

export interface ConditionStep<TState> {
    name: string;
    condition: (state: TState) => boolean;
    steps: StepDef<TState>[];
}

export interface FunctionStep<TState> {
    name: string;
    run: (state: TState, ctx: RunContext) => Promise<Partial<TState>>;
}

export interface ParallelStep<TState> {
    name: string;
    parallel: StepDef<TState>[];
}

export type StepDef<TState> = AgentStep<TState> | FunctionStep<TState> | ConditionStep<TState> | ParallelStep<TState>;

export interface StepResult {
    stepName: string;
    status: "done" | "error" | "skipped";
    error?: string;
    durationMs: number;
}

/**
 * Default checkpoint store backed by a `StorageDriver`. Use any existing driver
 * (in-memory, SQLite, Postgres, MongoDB, Redis, ...) to get persistence.
 */
export declare class StorageBackedCheckpointStore<TState> implements WorkflowCheckpointStore<TState> {
    /** Maximum number of checkpoints kept per run. Older ones are deleted. */
    readonly keepLastN: number;
    constructor(storage: StorageDriver, options?: {
        keepLastN?: number;
    });
    save(cp: WorkflowCheckpoint<TState>): Promise<void>;
    load(checkpointId: string): Promise<WorkflowCheckpoint<TState> | null>;
    listForRun(runId: string): Promise<WorkflowCheckpoint<TState>[]>;
    delete(checkpointId: string): Promise<void>;
}

export declare class Workflow<TState extends Record<string, unknown> = Record<string, unknown>> {
    readonly kind: "workflow";
    readonly name: string;
    readonly eventBus: EventBus;
    constructor(config: WorkflowConfig<TState>);
    run(opts?: RunOpts & {
        initialState?: Partial<TState>;
    }): Promise<WorkflowResult<TState>>;
    /**
     * Same as `run()` but additionally saves a `WorkflowCheckpoint` after every
     * top-level step. Requires `checkpointStore` in the config.
     */
    runWithCheckpoints(opts?: {
        sessionId?: string;
        userId?: string;
    }): Promise<WorkflowResult<TState> & {
        runId: string;
    }>;
    /** List all checkpoints for a given runId. */
    listCheckpoints(runId: string): Promise<WorkflowCheckpoint<TState>[]>;
    /**
     * Replay the workflow from the state captured at `checkpointId`. Continues
     * with the remaining steps. Returns the final result + new run id.
     */
    replay(checkpointId: string): Promise<WorkflowResult<TState> & {
        runId: string;
    }>;
    /**
     * Fork a workflow run from a checkpoint with optional state mutations. The
     * fork gets a fresh runId. Use this for branching ("what if step 3 said X?").
     */
    fork(checkpointId: string, mutations?: (state: TState) => TState | Partial<TState>): Promise<WorkflowResult<TState> & {
        runId: string;
    }>;
}

/**
 * Per-step workflow checkpoint. Captures the state immediately after a step
 * completed so the workflow can replay or fork from that exact point.
 */
export interface WorkflowCheckpoint<TState> {
    /** Stable identifier - `${runId}:${stepIndex}`. */
    id: string;
    runId: string;
    workflowName: string;
    stepIndex: number;
    /** Name of the step whose completion produced this checkpoint. */
    stepName: string;
    /** State immediately AFTER the step ran. */
    state: TState;
    /** Cumulative step results up to and including this step. */
    stepResults: StepResult[];
    timestamp: number;
}

export interface WorkflowCheckpointStore<TState> {
    save(checkpoint: WorkflowCheckpoint<TState>): Promise<void>;
    load(checkpointId: string): Promise<WorkflowCheckpoint<TState> | null>;
    listForRun(runId: string): Promise<WorkflowCheckpoint<TState>[]>;
    delete(checkpointId: string): Promise<void>;
}

export interface WorkflowConfig<TState extends Record<string, unknown> = Record<string, unknown>> {
    name: string;
    initialState: TState;
    steps: StepDef<TState>[];
    storage?: StorageDriver;
    retryPolicy?: {
        maxRetries: number;
        backoffMs: number;
    };
    eventBus?: EventBus;
    /** Auto-register this workflow in the global registry. Default: true. Set false to opt out. */
    register?: boolean;
    /**
     * Enable time-travel: automatically checkpoint state after each step so the
     * workflow can be replayed or forked from any point.
     */
    checkpointStore?: WorkflowCheckpointStore<TState>;
}

export interface WorkflowResult<TState> {
    state: TState;
    stepResults: StepResult[];
}