@gobing-ai/ts-dual-workflow-engine 0.3.1 → 0.3.3

package/src/state-machine.ts

@@ -1,16 +1,16 @@
-import { getProcessEnv } from '@gobing-ai/ts-runtime';
 import { FSMError } from './errors';
 import type { WorkflowEngineHost } from './host';
+import { allowedEnv, RunLifecycle, runtimeBuiltins } from './run-lifecycle';
 import type {
     ActionDef,
     ActionResult,
+    OnErrorPolicy,
     StateMachineWorkflowDef,
     WorkflowPersistenceAdapter,
     WorkflowRunOptions,
-    WorkflowRunRecord,
     WorkflowRunResult,
 } from './types';
-import { mergeVars, resolveTemplates } from './variables';
+import { mergeVars, resolveOnErrorPolicy, resolveTemplates } from './variables';
 
 /** Dependencies required by the state-machine driver. */
 export interface StateMachineDriverOptions {
@@ -24,29 +24,39 @@ export class StateMachineDriver {
 
     /** 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));
+        return await RunLifecycle.run(
+            workflow.name,
+            'state-machine',
+            { persistence: this.options.persistence, events: options.events },
+            options,
+            (lifecycle) => this.loop(workflow, options, lifecycle),
+        );
+    }
 
+    private async loop(
+        workflow: StateMachineWorkflowDef,
+        options: WorkflowRunOptions,
+        lifecycle: RunLifecycle,
+    ): Promise<WorkflowRunResult> {
+        const runId = lifecycle.runId;
         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());
+        const env = allowedEnv(workflow.env?.allow ?? [], options.env);
         let current = states.get(workflow.initialState);
         let transitionsTaken = 0;
         let lastActionResult: ActionResult | undefined;
         const iterationBound = workflow.iterationBound ?? 50;
+        const defaultOnError = workflow.defaultOnError;
 
         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');
+            await lifecycle.enter(current.id, transitionsTaken);
 
             // 2. Execute this state's on-enter actions in declaration order.
-            lastActionResult = await this.runActions(
+            const enter = await this.runActions(
                 current.onEnter ?? [],
                 workflow.name,
                 current.id,
@@ -55,26 +65,26 @@ export class StateMachineDriver {
                 env,
                 options,
                 transitionsTaken,
+                lifecycle,
+                defaultOnError,
             );
-            if (lastActionResult?.ok === false)
-                return await this.fail(
-                    runId,
-                    workflow.name,
-                    mode,
-                    current.id,
-                    transitionsTaken,
-                    lastActionResult.error,
-                );
-
+            // Retain the last action result (including failures the policy continued
+            // past) so downstream guards can inspect it — matching the transition-flow
+            // driver's `continue` semantics. A state with no enter actions must not
+            // erase the previous result.
+            if (enter.result !== undefined) lastActionResult = enter.result;
             // 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);
+            if (enter.outcome === 'terminal') {
+                return await lifecycle.done(current.id, transitionsTaken);
+            }
+            // 4. Halt only when an action failed under a 'fail' policy.
+            if (enter.outcome === 'fail') {
+                return await lifecycle.fail(current.id, transitionsTaken, lastActionResult?.error);
             }
 
-            // 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);
+                return await lifecycle.done(current.id, transitionsTaken);
             }
 
             // 5. Evaluate transition guards in declaration order and pick the first passing transition.
@@ -85,18 +95,11 @@ export class StateMachineDriver {
                 lastActionResult,
             });
             if (nextTransition === undefined) {
-                return await this.fail(
-                    runId,
-                    workflow.name,
-                    mode,
-                    current.id,
-                    transitionsTaken,
-                    'no-passing-transition',
-                );
+                return await lifecycle.fail(current.id, transitionsTaken, 'no-passing-transition');
             }
 
             // 6. Execute this state's on-exit actions before changing state.
-            const exitResult = await this.runActions(
+            const exit = await this.runActions(
                 current.onExit ?? [],
                 workflow.name,
                 current.id,
@@ -105,27 +108,17 @@ export class StateMachineDriver {
                 env,
                 options,
                 transitionsTaken,
+                lifecycle,
+                defaultOnError,
             );
-            if (exitResult?.ok === false)
-                return await this.fail(runId, workflow.name, mode, current.id, transitionsTaken, exitResult.error);
+            if (exit.result !== undefined) lastActionResult = exit.result;
+            if (exit.outcome === 'fail') return await lifecycle.fail(current.id, transitionsTaken, exit.result?.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,
-            );
+            await lifecycle.recordTransition(current.id, nextTransition.to, nextTransition.trigger ?? null);
             if (transitionsTaken > iterationBound) {
-                return await this.fail(
-                    runId,
-                    workflow.name,
-                    mode,
-                    current.id,
-                    transitionsTaken,
-                    'iteration-bound-exceeded',
-                );
+                return await lifecycle.fail(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`);
@@ -133,6 +126,12 @@ export class StateMachineDriver {
         }
     }
 
+    /**
+     * Run a state's actions in order. Returns the last action result (retained even
+     * when a failure was continued past, so downstream guards can inspect it) plus an
+     * `outcome` discriminator: `terminal` (an action declared terminal success),
+     * `fail` (a failure under a 'fail' policy — caller must halt), or `completed`.
+     */
     private async runActions(
         actions: readonly ActionDef[],
         workflowName: string,
@@ -142,70 +141,45 @@ export class StateMachineDriver {
         env: Record<string, string>,
         options: WorkflowRunOptions,
         transitionsTaken: number,
-    ): Promise<ActionResult | undefined> {
+        lifecycle: RunLifecycle,
+        defaultOnError: OnErrorPolicy | undefined,
+    ): Promise<RunActionsOutcome> {
         let last: ActionResult | undefined;
         for (const action of actions) {
             const resolved = resolveTemplates(action.options ?? {}, {
                 vars,
                 env,
-                builtins: runtimeBuiltins(workflowName, stateId, runId, transitionsTaken),
-            });
-            last = await this.options.host.runAction(action.kind, resolved, {
-                runId,
-                workdir: options.workdir,
-                stateOrNodeId: stateId,
-                vars,
-                env,
-                metadata: options.metadata,
+                builtins: runtimeBuiltins(workflowName, stateId, runId, transitionsTaken, 'state-machine'),
             });
-            if (!last.ok || last.terminal === true) return last;
+            const actionStartMs = Date.now();
+            lifecycle.actionStart(stateId, action.kind);
+            try {
+                last = await this.options.host.runAction(action.kind, resolved, {
+                    runId,
+                    workdir: options.workdir,
+                    stateOrNodeId: stateId,
+                    vars,
+                    env,
+                    metadata: options.metadata,
+                });
+            } finally {
+                lifecycle.actionDone(stateId, action.kind, Date.now() - actionStartMs, last?.ok ?? false);
+            }
+            if (last.terminal === true) return { outcome: 'terminal', result: last };
+            if (!last.ok) {
+                const policy = resolveOnErrorPolicy(action.onError, defaultOnError, options.onError);
+                if (policy === 'fail') return { outcome: 'fail', result: last };
+                lifecycle.warnActionFailed(stateId, transitionsTaken, last.error);
+            }
         }
-        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 };
+        return { outcome: 'completed', result: last };
     }
 }
 
-/** Built-in bare template values available to state-machine action options. */
-function runtimeBuiltins(
-    workflowName: string,
-    stateId: string,
-    runId: string,
-    transitionsTaken: number,
-): Record<string, string | number> {
-    return {
-        workflow: workflowName,
-        runId,
-        task: workflowName,
-        state: stateId,
-        node: stateId,
-        iteration: transitionsTaken,
-        run: runId,
-        runtime: 'state-machine',
-    };
+/** Result of running a state's actions: the last action result plus a control-flow discriminator. */
+interface RunActionsOutcome {
+    readonly outcome: 'completed' | 'terminal' | 'fail';
+    readonly result: ActionResult | undefined;
 }
 
 async function firstPassingTransition(
@@ -219,27 +193,3 @@ async function firstPassingTransition(
     }
     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

@@ -1,15 +1,14 @@
-import { getProcessEnv } from '@gobing-ai/ts-runtime';
 import { FSMError } from './errors';
 import type { WorkflowEngineHost } from './host';
+import { allowedEnv, RunLifecycle, runtimeBuiltins } from './run-lifecycle';
 import type {
     ActionResult,
     TransitionFlowWorkflowDef,
     WorkflowPersistenceAdapter,
     WorkflowRunOptions,
-    WorkflowRunRecord,
     WorkflowRunResult,
 } from './types';
-import { mergeVars, resolveTemplates } from './variables';
+import { mergeVars, resolveOnErrorPolicy, resolveTemplates } from './variables';
 
 /** Dependencies required by the transition-flow driver. */
 export interface TransitionFlowDriverOptions {
@@ -23,19 +22,30 @@ export class TransitionFlowDriver {
 
     /** 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));
+        return await RunLifecycle.run(
+            workflow.name,
+            'transition-flow',
+            { persistence: this.options.persistence, events: options.events },
+            options,
+            (lifecycle) => this.loop(workflow, options, lifecycle),
+        );
+    }
 
+    private async loop(
+        workflow: TransitionFlowWorkflowDef,
+        options: WorkflowRunOptions,
+        lifecycle: RunLifecycle,
+    ): Promise<WorkflowRunResult> {
+        const runId = lifecycle.runId;
         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());
+        const env = allowedEnv(workflow.env?.allow ?? [], options.env);
         let current = nodes.get(workflow.initialNode);
         let transitionsTaken = 0;
         let lastActionResult: ActionResult | undefined;
         const iterationBound = workflow.iterationBound ?? 50;
+        const defaultOnError = workflow.defaultOnError;
 
         if (current === undefined) {
             throw new FSMError(`Initial node "${workflow.initialNode}" is not declared`);
@@ -43,43 +53,50 @@ export class TransitionFlowDriver {
 
         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');
+            await lifecycle.enter(current.id, transitionsTaken);
 
             // 2. Execute the node action when one is configured.
             if (current.action !== undefined) {
                 const resolved = resolveTemplates(current.action.options ?? {}, {
                     vars,
                     env,
-                    builtins: runtimeBuiltins(workflow.name, current.id, runId, transitionsTaken),
-                });
-                lastActionResult = await this.options.host.runAction(current.action.kind, resolved, {
-                    runId,
-                    workdir: options.workdir,
-                    stateOrNodeId: current.id,
-                    vars,
-                    env,
-                    metadata: options.metadata,
+                    builtins: runtimeBuiltins(workflow.name, current.id, runId, transitionsTaken, 'transition-flow'),
                 });
-                if (!lastActionResult.ok) {
-                    return await this.fail(
+                const actionStartMs = Date.now();
+                lifecycle.actionStart(current.id, current.action.kind);
+                try {
+                    lastActionResult = await this.options.host.runAction(current.action.kind, resolved, {
                         runId,
-                        workflow.name,
-                        mode,
+                        workdir: options.workdir,
+                        stateOrNodeId: current.id,
+                        vars,
+                        env,
+                        metadata: options.metadata,
+                    });
+                } finally {
+                    lifecycle.actionDone(
                         current.id,
-                        transitionsTaken,
-                        lastActionResult.error,
+                        current.action.kind,
+                        Date.now() - actionStartMs,
+                        lastActionResult?.ok ?? false,
                     );
                 }
+                if (!lastActionResult.ok) {
+                    const policy = resolveOnErrorPolicy(current.action.onError, defaultOnError, options.onError);
+                    if (policy === 'fail') {
+                        return await lifecycle.fail(current.id, transitionsTaken, lastActionResult.error);
+                    }
+                    lifecycle.warnActionFailed(current.id, transitionsTaken, lastActionResult.error);
+                }
                 if (lastActionResult.terminal === true) {
-                    return await this.done(runId, workflow.name, mode, current.id, transitionsTaken);
+                    return await lifecycle.done(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);
+                return await lifecycle.done(current.id, transitionsTaken);
             }
 
             // 4. Evaluate edge conditions in declaration order and pick the first passing edge.
@@ -90,23 +107,16 @@ export class TransitionFlowDriver {
                 lastActionResult,
             });
             if (edge === undefined) {
-                return await this.fail(runId, workflow.name, mode, current.id, transitionsTaken, 'no-passing-edge');
+                return await lifecycle.fail(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);
+            await lifecycle.recordTransition(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',
-                );
+                return await lifecycle.fail(current.id, transitionsTaken, 'iteration-bound-exceeded');
             }
 
             // 7. Move to the target node and repeat.
@@ -115,50 +125,6 @@ export class TransitionFlowDriver {
             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 };
-    }
-}
-
-/** Built-in bare template values available to transition-flow action options. */
-function runtimeBuiltins(
-    workflowName: string,
-    nodeId: string,
-    runId: string,
-    transitionsTaken: number,
-): Record<string, string | number> {
-    return {
-        workflow: workflowName,
-        runId,
-        task: workflowName,
-        state: nodeId,
-        node: nodeId,
-        iteration: transitionsTaken,
-        run: runId,
-        runtime: 'transition-flow',
-    };
 }
 
 async function firstPassingEdge(
@@ -172,27 +138,3 @@ async function firstPassingEdge(
     }
     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

@@ -1,3 +1,9 @@
+/** Action error handling policy: fail-fast or log-and-continue. */
+export type OnErrorPolicy = 'fail' | 'continue';
+
+import type { EventBus } from '@gobing-ai/ts-infra';
+import type { WorkflowEngineEvents } from './events';
+
 /** Workflow execution status persisted for runs and phases. */
 export type WorkflowStatus = 'running' | 'done' | 'failed';
 
@@ -13,6 +19,8 @@ export interface Env {
 export interface ActionDef {
     readonly kind: string;
     readonly options?: Record<string, unknown>;
+    /** Per-action error policy override. Falls back to workflow default then run-option then 'fail'. */
+    readonly onError?: OnErrorPolicy;
 }
 
 /** Guard predicate definition used by state-machine transitions and transition-flow edges. */
@@ -51,6 +59,8 @@ export interface StateMachineWorkflowDef {
     readonly initialState: string;
     readonly terminalStates?: readonly string[];
     readonly iterationBound?: number;
+    /** Default error policy applied to actions that don't specify their own. Defaults to 'fail'. */
+    readonly defaultOnError?: OnErrorPolicy;
     readonly vars?: Vars;
     readonly env?: Env;
     readonly states: readonly StateDef[];
@@ -86,6 +96,8 @@ export interface TransitionFlowWorkflowDef {
     readonly initialNode: string;
     readonly terminalNodes?: readonly string[];
     readonly iterationBound?: number;
+    /** Default error policy applied to actions that don't specify their own. Defaults to 'fail'. */
+    readonly defaultOnError?: OnErrorPolicy;
     readonly vars?: Vars;
     readonly env?: Env;
     readonly nodes: readonly FlowNodeDef[];
@@ -140,6 +152,10 @@ export interface WorkflowRunOptions {
     readonly vars?: Vars;
     readonly env?: Record<string, string | undefined>;
     readonly metadata?: Record<string, unknown>;
+    /** Optional event bus for structured run observability. */
+    readonly events?: EventBus<WorkflowEngineEvents>;
+    /** Run-level error policy override. Lowest precedence; action-level wins. */
+    readonly onError?: OnErrorPolicy;
 }
 
 /** Result returned by both driver loops. */

package/src/variables.ts

@@ -1,5 +1,5 @@
 import { WorkflowValidationError } from './errors';
-import type { Vars } from './types';
+import type { OnErrorPolicy, Vars } from './types';
 
 const TEMPLATE_REF = /\$\{([^}]+)\}/g;
 
@@ -55,3 +55,15 @@ export function resolveTemplateString(value: string, context: VariableContext):
         return String(resolved);
     });
 }
+
+/**
+ * Resolve the effective error policy via fixed precedence:
+ * `action.onError ?? workflow.defaultOnError ?? runOptions.onError ?? 'fail'`.
+ */
+export function resolveOnErrorPolicy(
+    actionOnError: OnErrorPolicy | undefined,
+    workflowDefault: OnErrorPolicy | undefined,
+    runOptionOverride: OnErrorPolicy | undefined,
+): OnErrorPolicy {
+    return actionOnError ?? workflowDefault ?? runOptionOverride ?? 'fail';
+}