@gobing-ai/ts-dual-workflow-engine 0.2.1

package/src/state-machine.ts

@@ -0,0 +1,223 @@
+import { getProcessEnv } from '@gobing-ai/ts-runtime';
+import { FSMError } from './errors';
+import type { WorkflowEngineHost } from './host';
+import type {
+    ActionDef,
+    ActionResult,
+    StateMachineWorkflowDef,
+    WorkflowPersistenceAdapter,
+    WorkflowRunOptions,
+    WorkflowRunRecord,
+    WorkflowRunResult,
+} from './types';
+import { mergeVars, resolveTemplates } from './variables';
+
+/** Dependencies required by the state-machine driver. */
+export interface StateMachineDriverOptions {
+    readonly host: WorkflowEngineHost;
+    readonly persistence: WorkflowPersistenceAdapter;
+}
+
+/** State-machine workflow driver with an R7 single control function. */
+export class StateMachineDriver {
+    constructor(private readonly options: StateMachineDriverOptions) {}
+
+    /** Run a state-machine workflow to completion or failure. */
+    async run(workflow: StateMachineWorkflowDef, options: WorkflowRunOptions = {}): Promise<WorkflowRunResult> {
+        const runId = options.runId ?? crypto.randomUUID();
+        const startedAt = new Date().toISOString();
+        const mode = 'state-machine';
+        await this.options.persistence.createRun(runRecord(runId, workflow.name, mode, startedAt, options.metadata));
+
+        const states = new Map(workflow.states.map((state) => [state.id, state]));
+        const terminal = new Set(workflow.terminalStates ?? []);
+        const vars = mergeVars(workflow.vars, options.vars);
+        const env = allowedEnv(workflow.env?.allow ?? [], options.env ?? getProcessEnv());
+        let current = states.get(workflow.initialState);
+        let transitionsTaken = 0;
+        let lastActionResult: ActionResult | undefined;
+        const iterationBound = workflow.iterationBound ?? 50;
+
+        if (current === undefined) throw new FSMError(`Initial state "${workflow.initialState}" is not declared`);
+
+        while (true) {
+            // 1. Persist current state snapshot before work starts.
+            await this.options.persistence.saveWorkflowState(runId, current.id, { transitionsTaken });
+            await this.options.persistence.savePhase(runId, current.id, 'running');
+
+            // 2. Execute this state's on-enter actions in declaration order.
+            lastActionResult = await this.runActions(
+                current.onEnter ?? [],
+                workflow.name,
+                current.id,
+                runId,
+                vars,
+                env,
+                options,
+            );
+            if (lastActionResult?.ok === false)
+                return await this.fail(
+                    runId,
+                    workflow.name,
+                    mode,
+                    current.id,
+                    transitionsTaken,
+                    lastActionResult.error,
+                );
+
+            // 3. Stop immediately when an action explicitly declares terminal success.
+            if (lastActionResult?.terminal === true) {
+                return await this.done(runId, workflow.name, mode, current.id, transitionsTaken);
+            }
+
+            // 4. Stop when the current state is terminal or has no outbound transitions.
+            const outbound = workflow.transitions.filter((transition) => transition.from === current?.id);
+            if (terminal.has(current.id) || outbound.length === 0) {
+                return await this.done(runId, workflow.name, mode, current.id, transitionsTaken);
+            }
+
+            // 5. Evaluate transition guards in declaration order and pick the first passing transition.
+            const nextTransition = await firstPassingTransition(outbound, this.options.host, {
+                runId,
+                current: current.id,
+                vars,
+                lastActionResult,
+            });
+            if (nextTransition === undefined) {
+                return await this.fail(
+                    runId,
+                    workflow.name,
+                    mode,
+                    current.id,
+                    transitionsTaken,
+                    'no-passing-transition',
+                );
+            }
+
+            // 6. Execute this state's on-exit actions before changing state.
+            const exitResult = await this.runActions(
+                current.onExit ?? [],
+                workflow.name,
+                current.id,
+                runId,
+                vars,
+                env,
+                options,
+            );
+            if (exitResult?.ok === false)
+                return await this.fail(runId, workflow.name, mode, current.id, transitionsTaken, exitResult.error);
+
+            // 7. Persist transition and move to the target state.
+            transitionsTaken += 1;
+            await this.options.persistence.saveTransition(
+                runId,
+                current.id,
+                nextTransition.to,
+                nextTransition.trigger ?? null,
+            );
+            if (transitionsTaken > iterationBound) {
+                return await this.fail(
+                    runId,
+                    workflow.name,
+                    mode,
+                    current.id,
+                    transitionsTaken,
+                    'iteration-bound-exceeded',
+                );
+            }
+            const nextState = states.get(nextTransition.to);
+            if (nextState === undefined) throw new FSMError(`Transition target "${nextTransition.to}" is not declared`);
+            current = nextState;
+        }
+    }
+
+    private async runActions(
+        actions: readonly ActionDef[],
+        workflowName: string,
+        stateId: string,
+        runId: string,
+        vars: Record<string, string>,
+        env: Record<string, string>,
+        options: WorkflowRunOptions,
+    ): Promise<ActionResult | undefined> {
+        let last: ActionResult | undefined;
+        for (const action of actions) {
+            const resolved = resolveTemplates(action.options ?? {}, {
+                vars,
+                env,
+                builtins: { workflow: workflowName, state: stateId, runId },
+            });
+            last = await this.options.host.runAction(action.kind, resolved, {
+                runId,
+                workdir: options.workdir,
+                stateOrNodeId: stateId,
+                vars,
+                env,
+                metadata: options.metadata,
+            });
+            if (!last.ok || last.terminal === true) return last;
+        }
+        return last;
+    }
+
+    private async done(
+        runId: string,
+        workflowName: string,
+        mode: 'state-machine',
+        finalState: string,
+        transitionsTaken: number,
+    ): Promise<WorkflowRunResult> {
+        await this.options.persistence.savePhase(runId, finalState, 'done');
+        await this.options.persistence.finalizeRun(runId, 'done', new Date().toISOString());
+        return { runId, workflowName, mode, status: 'done', finalState, transitionsTaken };
+    }
+
+    private async fail(
+        runId: string,
+        workflowName: string,
+        mode: 'state-machine',
+        finalState: string,
+        transitionsTaken: number,
+        reason = 'failed',
+    ): Promise<WorkflowRunResult> {
+        await this.options.persistence.savePhase(runId, finalState, 'failed');
+        await this.options.persistence.finalizeRun(runId, 'failed', new Date().toISOString());
+        return { runId, workflowName, mode, status: 'failed', finalState, transitionsTaken, reason };
+    }
+}
+
+async function firstPassingTransition(
+    transitions: StateMachineWorkflowDef['transitions'],
+    host: WorkflowEngineHost,
+    context: Parameters<WorkflowEngineHost['evaluateGuard']>[2],
+): Promise<StateMachineWorkflowDef['transitions'][number] | undefined> {
+    for (const transition of transitions) {
+        if (transition.guard === undefined) return transition;
+        if (await host.evaluateGuard(transition.guard.kind, transition.guard.options ?? {}, context)) return transition;
+    }
+    return undefined;
+}
+
+function allowedEnv(names: readonly string[], source: Record<string, string | undefined>): Record<string, string> {
+    return Object.fromEntries(
+        names.flatMap((name) => (source[name] === undefined ? [] : [[name, source[name] as string]])),
+    );
+}
+
+function runRecord(
+    runId: string,
+    workflowName: string,
+    mode: string,
+    startedAt: string,
+    metadata: unknown,
+): WorkflowRunRecord {
+    return {
+        id: runId,
+        workflow_name: workflowName,
+        mode,
+        status: 'running',
+        started_at: startedAt,
+        completed_at: null,
+        metadata_json: JSON.stringify(metadata ?? {}),
+    };
+}

package/src/transition-flow.ts

@@ -0,0 +1,178 @@
+import { getProcessEnv } from '@gobing-ai/ts-runtime';
+import type { WorkflowEngineHost } from './host';
+import type {
+    ActionResult,
+    TransitionFlowWorkflowDef,
+    WorkflowPersistenceAdapter,
+    WorkflowRunOptions,
+    WorkflowRunRecord,
+    WorkflowRunResult,
+} from './types';
+import { mergeVars, resolveTemplates } from './variables';
+
+/** Dependencies required by the transition-flow driver. */
+export interface TransitionFlowDriverOptions {
+    readonly host: WorkflowEngineHost;
+    readonly persistence: WorkflowPersistenceAdapter;
+}
+
+/** Transition-flow workflow driver with an R7 single control function. */
+export class TransitionFlowDriver {
+    constructor(private readonly options: TransitionFlowDriverOptions) {}
+
+    /** Run a transition-flow workflow to completion or failure. */
+    async run(workflow: TransitionFlowWorkflowDef, options: WorkflowRunOptions = {}): Promise<WorkflowRunResult> {
+        const runId = options.runId ?? crypto.randomUUID();
+        const startedAt = new Date().toISOString();
+        const mode = 'transition-flow';
+        await this.options.persistence.createRun(runRecord(runId, workflow.name, mode, startedAt, options.metadata));
+
+        const nodes = new Map(workflow.nodes.map((node) => [node.id, node]));
+        const terminal = new Set(workflow.terminalNodes ?? []);
+        const vars = mergeVars(workflow.vars, options.vars);
+        const env = allowedEnv(workflow.env?.allow ?? [], options.env ?? getProcessEnv());
+        let current = nodes.get(workflow.initialNode);
+        let transitionsTaken = 0;
+        let lastActionResult: ActionResult | undefined;
+        const iterationBound = workflow.iterationBound ?? 50;
+
+        if (current === undefined) {
+            throw new Error(`Initial node "${workflow.initialNode}" is not declared`);
+        }
+
+        while (true) {
+            // 1. Persist current node snapshot before action execution.
+            await this.options.persistence.saveWorkflowState(runId, current.id, { transitionsTaken });
+            await this.options.persistence.savePhase(runId, current.id, 'running');
+
+            // 2. Execute the node action when one is configured.
+            if (current.action !== undefined) {
+                const resolved = resolveTemplates(current.action.options ?? {}, {
+                    vars,
+                    env,
+                    builtins: { workflow: workflow.name, node: current.id, runId },
+                });
+                lastActionResult = await this.options.host.runAction(current.action.kind, resolved, {
+                    runId,
+                    workdir: options.workdir,
+                    stateOrNodeId: current.id,
+                    vars,
+                    env,
+                    metadata: options.metadata,
+                });
+                if (!lastActionResult.ok) {
+                    return await this.fail(
+                        runId,
+                        workflow.name,
+                        mode,
+                        current.id,
+                        transitionsTaken,
+                        lastActionResult.error,
+                    );
+                }
+                if (lastActionResult.terminal === true) {
+                    return await this.done(runId, workflow.name, mode, current.id, transitionsTaken);
+                }
+            }
+
+            // 3. Stop when the node is terminal or no outgoing edge exists.
+            const outbound = workflow.edges.filter((edge) => edge.from === current?.id);
+            if (terminal.has(current.id) || outbound.length === 0) {
+                return await this.done(runId, workflow.name, mode, current.id, transitionsTaken);
+            }
+
+            // 4. Evaluate edge conditions in declaration order and pick the first passing edge.
+            const edge = await firstPassingEdge(outbound, this.options.host, {
+                runId,
+                current: current.id,
+                vars,
+                lastActionResult,
+            });
+            if (edge === undefined) {
+                return await this.fail(runId, workflow.name, mode, current.id, transitionsTaken, 'no-passing-edge');
+            }
+
+            // 5. Persist the edge transition.
+            transitionsTaken += 1;
+            await this.options.persistence.saveTransition(runId, current.id, edge.to, edge.condition?.kind ?? null);
+
+            // 6. Enforce the iteration bound after taking the transition.
+            if (transitionsTaken > iterationBound) {
+                return await this.fail(
+                    runId,
+                    workflow.name,
+                    mode,
+                    current.id,
+                    transitionsTaken,
+                    'iteration-bound-exceeded',
+                );
+            }
+
+            // 7. Move to the target node and repeat.
+            const nextNode = nodes.get(edge.to);
+            if (nextNode === undefined) throw new Error(`Edge target "${edge.to}" is not declared`);
+            current = nextNode;
+        }
+    }
+
+    private async done(
+        runId: string,
+        workflowName: string,
+        mode: 'transition-flow',
+        finalState: string,
+        transitionsTaken: number,
+    ): Promise<WorkflowRunResult> {
+        await this.options.persistence.savePhase(runId, finalState, 'done');
+        await this.options.persistence.finalizeRun(runId, 'done', new Date().toISOString());
+        return { runId, workflowName, mode, status: 'done', finalState, transitionsTaken };
+    }
+
+    private async fail(
+        runId: string,
+        workflowName: string,
+        mode: 'transition-flow',
+        finalState: string,
+        transitionsTaken: number,
+        reason = 'failed',
+    ): Promise<WorkflowRunResult> {
+        await this.options.persistence.savePhase(runId, finalState, 'failed');
+        await this.options.persistence.finalizeRun(runId, 'failed', new Date().toISOString());
+        return { runId, workflowName, mode, status: 'failed', finalState, transitionsTaken, reason };
+    }
+}
+
+async function firstPassingEdge(
+    edges: TransitionFlowWorkflowDef['edges'],
+    host: WorkflowEngineHost,
+    context: Parameters<WorkflowEngineHost['evaluateGuard']>[2],
+): Promise<TransitionFlowWorkflowDef['edges'][number] | undefined> {
+    for (const edge of edges) {
+        if (edge.condition === undefined) return edge;
+        if (await host.evaluateGuard(edge.condition.kind, edge.condition.options ?? {}, context)) return edge;
+    }
+    return undefined;
+}
+
+function allowedEnv(names: readonly string[], source: Record<string, string | undefined>): Record<string, string> {
+    return Object.fromEntries(
+        names.flatMap((name) => (source[name] === undefined ? [] : [[name, source[name] as string]])),
+    );
+}
+
+function runRecord(
+    runId: string,
+    workflowName: string,
+    mode: string,
+    startedAt: string,
+    metadata: unknown,
+): WorkflowRunRecord {
+    return {
+        id: runId,
+        workflow_name: workflowName,
+        mode,
+        status: 'running',
+        started_at: startedAt,
+        completed_at: null,
+        metadata_json: JSON.stringify(metadata ?? {}),
+    };
+}

package/src/types.ts

@@ -0,0 +1,160 @@
+/** Workflow execution status persisted for runs and phases. */
+export type WorkflowStatus = 'running' | 'done' | 'failed';
+
+/** Runtime variables and user variables available to workflow definitions. */
+export type Vars = Record<string, string>;
+
+/** Environment allowlist carried by a workflow definition. */
+export interface Env {
+    readonly allow?: readonly string[];
+}
+
+/** Workflow action definition executed by a host action runner. */
+export interface ActionDef {
+    readonly kind: string;
+    readonly options?: Record<string, unknown>;
+}
+
+/** Guard predicate definition used by state-machine transitions and transition-flow edges. */
+export interface GuardDef {
+    readonly kind: string;
+    readonly options?: Record<string, unknown>;
+}
+
+/** One state in a state-machine workflow. */
+export interface StateDef {
+    readonly id: string;
+    readonly onEnter?: readonly ActionDef[];
+    readonly onExit?: readonly ActionDef[];
+}
+
+/** One transition in a state-machine workflow. */
+export interface TransitionDef {
+    readonly from: string;
+    readonly to: string;
+    readonly trigger?: string;
+    readonly guard?: GuardDef;
+}
+
+/** State-machine workflow definition. */
+export interface StateMachineWorkflowDef {
+    readonly kind?: 'state-machine';
+    readonly name: string;
+    readonly initialState: string;
+    readonly terminalStates?: readonly string[];
+    readonly iterationBound?: number;
+    readonly vars?: Vars;
+    readonly env?: Env;
+    readonly states: readonly StateDef[];
+    readonly transitions: readonly TransitionDef[];
+}
+
+/** Transition-flow node definition. */
+export interface FlowNodeDef {
+    readonly id: string;
+    readonly type?: 'action' | 'gate' | 'parallel' | 'decision';
+    readonly action?: ActionDef;
+}
+
+/** Transition-flow edge definition. */
+export interface FlowEdgeDef {
+    readonly from: string;
+    readonly to: string;
+    readonly condition?: GuardDef;
+}
+
+/** Transition-flow workflow definition. */
+export interface TransitionFlowWorkflowDef {
+    readonly kind: 'transition-flow';
+    readonly name: string;
+    readonly initialNode: string;
+    readonly terminalNodes?: readonly string[];
+    readonly iterationBound?: number;
+    readonly vars?: Vars;
+    readonly env?: Env;
+    readonly nodes: readonly FlowNodeDef[];
+    readonly edges: readonly FlowEdgeDef[];
+}
+
+/** Discriminated workflow definition union. */
+export type WorkflowDef = StateMachineWorkflowDef | TransitionFlowWorkflowDef;
+
+/** Action execution context passed to action runners. */
+export interface ActionRunContext {
+    readonly runId: string;
+    readonly workdir?: string;
+    readonly stateOrNodeId: string;
+    readonly vars: Vars;
+    readonly env: Record<string, string>;
+    readonly metadata?: Record<string, unknown>;
+}
+
+/** Result of a single action execution. */
+export interface ActionResult {
+    readonly ok: boolean;
+    readonly data?: Record<string, unknown>;
+    readonly error?: string;
+    readonly terminal?: boolean;
+}
+
+/** Action runner implementation registered in the workflow host. */
+export interface ActionRunner {
+    readonly kind: string;
+    execute(options: Record<string, unknown>, context: ActionRunContext): Promise<ActionResult>;
+}
+
+/** Guard evaluation context. */
+export interface GuardContext {
+    readonly runId: string;
+    readonly current: string;
+    readonly vars: Vars;
+    readonly lastActionResult?: ActionResult;
+}
+
+/** Guard runner implementation registered in the workflow host. */
+export interface GuardRunner {
+    readonly kind: string;
+    evaluate(options: Record<string, unknown>, context: GuardContext): Promise<boolean>;
+}
+
+/** Input for running a workflow. */
+export interface WorkflowRunOptions {
+    readonly runId?: string;
+    readonly workdir?: string;
+    readonly vars?: Vars;
+    readonly env?: Record<string, string | undefined>;
+    readonly metadata?: Record<string, unknown>;
+}
+
+/** Result returned by both driver loops. */
+export interface WorkflowRunResult {
+    readonly runId: string;
+    readonly workflowName: string;
+    readonly mode: 'state-machine' | 'transition-flow';
+    readonly status: WorkflowStatus;
+    readonly finalState: string;
+    readonly transitionsTaken: number;
+    readonly reason?: string;
+}
+
+/** Persisted workflow run record. */
+export interface WorkflowRunRecord {
+    readonly id: string;
+    readonly workflow_name: string;
+    readonly mode: string;
+    readonly status: WorkflowStatus;
+    readonly started_at: string;
+    readonly completed_at: string | null;
+    readonly metadata_json: string;
+}
+
+/** Persistence adapter implemented by DB-backed and test stores. */
+export interface WorkflowPersistenceAdapter {
+    createRun(record: WorkflowRunRecord): Promise<void>;
+    finalizeRun(runId: string, status: WorkflowStatus, completedAt: string): Promise<void>;
+    savePhase(runId: string, phase: string, status: WorkflowStatus): Promise<void>;
+    saveTransition(runId: string, from: string, to: string, trigger: string | null): Promise<void>;
+    saveWorkflowState(runId: string, state: string, data: Record<string, unknown>): Promise<void>;
+    loadRun(runId: string): Promise<WorkflowRunRecord | undefined>;
+    listRuns(): Promise<readonly WorkflowRunRecord[]>;
+}

package/src/variables.ts

@@ -0,0 +1,57 @@
+import { WorkflowValidationError } from './errors';
+import type { Vars } from './types';
+
+const TEMPLATE_REF = /\$\{([^}]+)\}/g;
+
+/** Runtime context used for workflow variable interpolation. */
+export interface VariableContext {
+    readonly vars: Vars;
+    readonly env: Record<string, string | undefined>;
+    readonly builtins?: Record<string, string | number | undefined>;
+}
+
+/** Merge workflow vars with caller overrides; caller values win. */
+export function mergeVars(workflowVars: Vars = {}, overrideVars: Vars = {}): Vars {
+    return { ...workflowVars, ...overrideVars };
+}
+
+/** Resolve templates inside an unknown options value. */
+export function resolveTemplates<T>(value: T, context: VariableContext): T {
+    if (typeof value === 'string') {
+        return resolveTemplateString(value, context) as T;
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => resolveTemplates(entry, context)) as T;
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(
+            Object.entries(value as Record<string, unknown>).map(([key, entry]) => [
+                key,
+                resolveTemplates(entry, context),
+            ]),
+        ) as T;
+    }
+    return value;
+}
+
+/** Resolve a single template string. */
+export function resolveTemplateString(value: string, context: VariableContext): string {
+    return value.replace(TEMPLATE_REF, (_match, name: string) => {
+        if (name.startsWith('vars.')) {
+            const key = name.slice('vars.'.length);
+            const resolved = context.vars[key];
+            if (resolved === undefined) throw new WorkflowValidationError(`Workflow variable "${key}" is not defined`);
+            return resolved;
+        }
+        if (name.startsWith('env.')) {
+            const key = name.slice('env.'.length);
+            const resolved = context.env[key];
+            if (resolved === undefined)
+                throw new WorkflowValidationError(`Environment variable "${key}" is not defined`);
+            return resolved;
+        }
+        const resolved = context.builtins?.[name];
+        if (resolved === undefined) throw new WorkflowValidationError(`Workflow builtin "${name}" is not defined`);
+        return String(resolved);
+    });
+}