@gobing-ai/ts-dual-workflow-engine 0.3.16 → 0.3.18

package/src/state-machine.ts

@@ -1,16 +1,15 @@
+import { runActionSequence } from './action-step';
 import { FSMError } from './errors';
 import type { WorkflowEngineHost } from './host';
-import { allowedEnv, RunLifecycle, runtimeBuiltins } from './run-lifecycle';
+import { allowedEnv, RunLifecycle } from './run-lifecycle';
 import type {
-    ActionDef,
     ActionResult,
-    OnErrorPolicy,
     StateMachineWorkflowDef,
     WorkflowPersistenceAdapter,
     WorkflowRunOptions,
     WorkflowRunResult,
 } from './types';
-import { mergeSetVars, mergeVars, resolveOnErrorPolicy, resolveTemplates } from './variables';
+import { mergeSetVars, mergeVars } from './variables';
 
 /** Dependencies required by the state-machine driver. */
 export interface StateMachineDriverOptions {
@@ -33,53 +32,89 @@ export class StateMachineDriver {
         );
     }
 
+    /** Resume a paused state-machine run from the given state, skipping on-enter. */
+    async resume(
+        workflow: StateMachineWorkflowDef,
+        runId: string,
+        resumeFromState: string,
+        externalKey: string | undefined,
+        options: WorkflowRunOptions = {},
+    ): Promise<WorkflowRunResult> {
+        return await RunLifecycle.resume(
+            workflow.name,
+            'state-machine',
+            { persistence: this.options.persistence, events: options.events },
+            runId,
+            externalKey,
+            (lifecycle) => this.loop(workflow, options, lifecycle, resumeFromState),
+        );
+    }
+
     private async loop(
         workflow: StateMachineWorkflowDef,
         options: WorkflowRunOptions,
         lifecycle: RunLifecycle,
+        resumeFromState?: string,
     ): Promise<WorkflowRunResult> {
         const runId = lifecycle.runId;
         const states = new Map(workflow.states.map((state) => [state.id, state]));
         const terminal = new Set(workflow.terminalStates ?? []);
         let vars = mergeVars(workflow.vars, options.vars);
         const env = allowedEnv(workflow.env?.allow ?? [], options.env);
-        let current = states.get(workflow.initialState);
+        let current = resumeFromState !== undefined ? states.get(resumeFromState) : states.get(workflow.initialState);
         let transitionsTaken = 0;
         let lastActionResult: ActionResult | undefined;
         const iterationBound = workflow.iterationBound ?? 50;
         const defaultOnError = workflow.defaultOnError;
+        let isResume = resumeFromState !== undefined;
 
-        if (current === undefined) throw new FSMError(`Initial state "${workflow.initialState}" is not declared`);
+        if (current === undefined) {
+            const label = resumeFromState ?? workflow.initialState;
+            throw new FSMError(`State "${label}" is not declared`);
+        }
 
         while (true) {
-            // 1. Persist current state snapshot before work starts.
-            await lifecycle.enter(current.id, transitionsTaken);
-
-            // 2. Execute this state's on-enter actions in declaration order.
-            const enter = await this.runActions(
-                current.onEnter ?? [],
-                workflow.name,
-                current.id,
-                runId,
-                vars,
-                env,
-                options,
-                transitionsTaken,
-                lifecycle,
-                defaultOnError,
-            );
-            // 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;
-            if (enter.result?.setVars) vars = mergeSetVars(vars, enter.result.setVars);
-            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);
+            if (isResume) {
+                // Resume: skip enter actions on the first iteration (already ran before pause).
+                isResume = false;
+            } else {
+                // 1. Persist current state snapshot before work starts.
+                await lifecycle.enter(current.id, transitionsTaken);
+
+                // 2. Execute this state's on-enter actions in declaration order.
+                const enter = options.dryRun
+                    ? EMPTY_OUTCOME
+                    : await runActionSequence(current.onEnter ?? [], vars, {
+                          host: this.options.host,
+                          persistence: this.options.persistence,
+                          lifecycle,
+                          workflowName: workflow.name,
+                          stateOrNodeId: current.id,
+                          runId,
+                          mode: 'state-machine',
+                          transitionsTaken,
+                          env,
+                          options,
+                          defaultOnError,
+                      });
+                // 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;
+                if (enter.result?.setVars) vars = mergeSetVars(vars, enter.result.setVars);
+                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);
+                }
+
+                // Pause: if the state declares pause, stop advancing and persist the paused position.
+                if (current.pause === true) {
+                    return await lifecycle.pause(current.id, transitionsTaken);
+                }
             }
 
             const outbound = workflow.transitions.filter((transition) => transition.from === current?.id);
@@ -105,18 +140,21 @@ export class StateMachineDriver {
             }
 
             // 6. Execute this state's on-exit actions before changing state.
-            const exit = await this.runActions(
-                current.onExit ?? [],
-                workflow.name,
-                current.id,
-                runId,
-                vars,
-                env,
-                options,
-                transitionsTaken,
-                lifecycle,
-                defaultOnError,
-            );
+            const exit = options.dryRun
+                ? EMPTY_OUTCOME
+                : await runActionSequence(current.onExit ?? [], vars, {
+                      host: this.options.host,
+                      persistence: this.options.persistence,
+                      lifecycle,
+                      workflowName: workflow.name,
+                      stateOrNodeId: current.id,
+                      runId,
+                      mode: 'state-machine',
+                      transitionsTaken,
+                      env,
+                      options,
+                      defaultOnError,
+                  });
             if (exit.result !== undefined) lastActionResult = exit.result;
             if (exit.result?.setVars) vars = mergeSetVars(vars, exit.result.setVars);
             if (exit.outcome === 'fail') return await lifecycle.fail(current.id, transitionsTaken, exit.result?.error);
@@ -132,76 +170,10 @@ export class StateMachineDriver {
             current = nextState;
         }
     }
-
-    /**
-     * 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,
-        stateId: string,
-        runId: string,
-        vars: Record<string, string>,
-        env: Record<string, string>,
-        options: WorkflowRunOptions,
-        transitionsTaken: number,
-        lifecycle: RunLifecycle,
-        defaultOnError: OnErrorPolicy | undefined,
-    ): Promise<RunActionsOutcome> {
-        if (options.dryRun) {
-            return { outcome: 'completed', result: undefined };
-        }
-
-        let last: ActionResult | undefined;
-        for (const action of actions) {
-            const resolved = resolveTemplates(action.options ?? {}, {
-                vars,
-                env,
-                builtins: runtimeBuiltins(workflowName, stateId, runId, transitionsTaken, 'state-machine'),
-            });
-            const actionId = await this.options.persistence.saveActionStart(runId, stateId, action.kind);
-            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,
-                    events: options.events,
-                });
-            } finally {
-                const durationMs = Date.now() - actionStartMs;
-                lifecycle.actionDone(stateId, action.kind, durationMs, last?.ok ?? false);
-                void this.options.persistence.saveActionFinalize(
-                    actionId,
-                    last?.ok !== false ? 'done' : 'failed',
-                    durationMs,
-                    last?.ok ?? false,
-                    last,
-                );
-            }
-            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 { outcome: 'completed', result: last };
-    }
 }
 
-/** 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;
-}
+/** Dry-run sentinel: no action ran, so there is nothing to retain and nothing to halt on. */
+const EMPTY_OUTCOME = { outcome: 'completed', result: undefined } as const;
 
 async function firstPassingTransition(
     transitions: StateMachineWorkflowDef['transitions'],

package/src/transition-flow.ts

@@ -1,6 +1,7 @@
+import { runActionStep } from './action-step';
 import { FSMError } from './errors';
 import type { WorkflowEngineHost } from './host';
-import { allowedEnv, RunLifecycle, runtimeBuiltins } from './run-lifecycle';
+import { allowedEnv, RunLifecycle } from './run-lifecycle';
 import type {
     ActionResult,
     TransitionFlowWorkflowDef,
@@ -8,7 +9,7 @@ import type {
     WorkflowRunOptions,
     WorkflowRunResult,
 } from './types';
-import { mergeSetVars, mergeVars, resolveOnErrorPolicy, resolveTemplates } from './variables';
+import { mergeSetVars, mergeVars } from './variables';
 
 /** Dependencies required by the transition-flow driver. */
 export interface TransitionFlowDriverOptions {
@@ -31,75 +32,87 @@ export class TransitionFlowDriver {
         );
     }
 
+    /** Resume a paused transition-flow run from the given node, skipping node action. */
+    async resume(
+        workflow: TransitionFlowWorkflowDef,
+        runId: string,
+        resumeFromNode: string,
+        externalKey: string | undefined,
+        options: WorkflowRunOptions = {},
+    ): Promise<WorkflowRunResult> {
+        return await RunLifecycle.resume(
+            workflow.name,
+            'transition-flow',
+            { persistence: this.options.persistence, events: options.events },
+            runId,
+            externalKey,
+            (lifecycle) => this.loop(workflow, options, lifecycle, resumeFromNode),
+        );
+    }
+
     private async loop(
         workflow: TransitionFlowWorkflowDef,
         options: WorkflowRunOptions,
         lifecycle: RunLifecycle,
+        resumeFromNode?: string,
     ): Promise<WorkflowRunResult> {
         const runId = lifecycle.runId;
         const nodes = new Map(workflow.nodes.map((node) => [node.id, node]));
         const terminal = new Set(workflow.terminalNodes ?? []);
         let vars = mergeVars(workflow.vars, options.vars);
         const env = allowedEnv(workflow.env?.allow ?? [], options.env);
-        let current = nodes.get(workflow.initialNode);
+        let current = resumeFromNode !== undefined ? nodes.get(resumeFromNode) : nodes.get(workflow.initialNode);
         let transitionsTaken = 0;
         let lastActionResult: ActionResult | undefined;
         const iterationBound = workflow.iterationBound ?? 50;
         const defaultOnError = workflow.defaultOnError;
+        let isResume = resumeFromNode !== undefined;
 
         if (current === undefined) {
-            throw new FSMError(`Initial node "${workflow.initialNode}" is not declared`);
+            const label = resumeFromNode ?? workflow.initialNode;
+            throw new FSMError(`Node "${label}" is not declared`);
         }
 
         while (true) {
-            // 1. Persist current node snapshot before action execution.
-            await lifecycle.enter(current.id, transitionsTaken);
+            if (isResume) {
+                // Resume: skip enter + node action on the first iteration (already ran before pause).
+                isResume = false;
+            } else {
+                // 1. Persist current node snapshot before action execution.
+                await lifecycle.enter(current.id, transitionsTaken);
 
-            // 2. Execute the node action when one is configured (skipped in dry-run).
-            if (options.dryRun) {
-                if (current.action !== undefined) {
-                    lastActionResult = undefined;
-                }
-            } else if (current.action !== undefined) {
-                const resolved = resolveTemplates(current.action.options ?? {}, {
-                    vars,
-                    env,
-                    builtins: runtimeBuiltins(workflow.name, current.id, runId, transitionsTaken, 'transition-flow'),
-                });
-                const actionId = await this.options.persistence.saveActionStart(runId, current.id, current.action.kind);
-                const actionStartMs = Date.now();
-                lifecycle.actionStart(current.id, current.action.kind);
-                try {
-                    lastActionResult = await this.options.host.runAction(current.action.kind, resolved, {
-                        runId,
-                        workdir: options.workdir,
+                // 2. Execute the node action when one is configured (skipped in dry-run).
+                if (options.dryRun) {
+                    if (current.action !== undefined) {
+                        lastActionResult = undefined;
+                    }
+                } else if (current.action !== undefined) {
+                    const step = await runActionStep(current.action, vars, {
+                        host: this.options.host,
+                        persistence: this.options.persistence,
+                        lifecycle,
+                        workflowName: workflow.name,
                         stateOrNodeId: current.id,
-                        vars,
+                        runId,
+                        mode: 'transition-flow',
+                        transitionsTaken,
                         env,
-                        metadata: options.metadata,
-                        events: options.events,
+                        options,
+                        defaultOnError,
                     });
-                } finally {
-                    const durationMs = Date.now() - actionStartMs;
-                    lifecycle.actionDone(current.id, current.action.kind, durationMs, lastActionResult?.ok ?? false);
-                    void this.options.persistence.saveActionFinalize(
-                        actionId,
-                        lastActionResult?.ok !== false ? 'done' : 'failed',
-                        durationMs,
-                        lastActionResult?.ok ?? false,
-                        lastActionResult,
-                    );
-                }
-                if (lastActionResult.setVars) vars = mergeSetVars(vars, lastActionResult.setVars);
-                if (!lastActionResult.ok) {
-                    const policy = resolveOnErrorPolicy(current.action.onError, defaultOnError, options.onError);
-                    if (policy === 'fail') {
-                        return await lifecycle.fail(current.id, transitionsTaken, lastActionResult.error);
+                    lastActionResult = step.result;
+                    if (step.result?.setVars) vars = mergeSetVars(vars, step.result.setVars);
+                    if (step.outcome === 'terminal') {
+                        return await lifecycle.done(current.id, transitionsTaken);
+                    }
+                    if (step.outcome === 'fail') {
+                        return await lifecycle.fail(current.id, transitionsTaken, step.result?.error);
                     }
-                    lifecycle.warnActionFailed(current.id, transitionsTaken, lastActionResult.error);
                 }
-                if (lastActionResult.terminal === true) {
-                    return await lifecycle.done(current.id, transitionsTaken);
+
+                // Pause: if the node declares pause, stop advancing and persist the paused position.
+                if (current.pause === true) {
+                    return await lifecycle.pause(current.id, transitionsTaken);
                 }
             }
 

package/src/types.ts

@@ -5,7 +5,7 @@ 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';
+export type WorkflowStatus = 'running' | 'done' | 'failed' | 'paused';
 
 /** Runtime variables and user variables available to workflow definitions. */
 export type Vars = Record<string, string>;
@@ -36,6 +36,8 @@ export interface StateDef {
     readonly description?: string;
     readonly onEnter?: readonly ActionDef[];
     readonly onExit?: readonly ActionDef[];
+    /** When true, the engine pauses the run at this state instead of auto-advancing. */
+    readonly pause?: boolean;
 }
 
 /** One transition in a state-machine workflow. */
@@ -74,6 +76,8 @@ export interface FlowNodeDef {
     readonly description?: string;
     readonly type?: 'action' | 'gate' | 'parallel' | 'decision';
     readonly action?: ActionDef;
+    /** When true, the engine pauses the run at this node instead of auto-advancing. */
+    readonly pause?: boolean;
 }
 
 /** Transition-flow edge definition. */
@@ -140,13 +144,20 @@ export interface GuardContext {
     readonly runId: string;
     readonly current: string;
     readonly vars: Vars;
+    readonly workdir?: string;
     readonly lastActionResult?: ActionResult;
 }
 
+/** Rich guard evaluation result. Boolean guard runners remain supported for compatibility. */
+export interface GuardEvaluationResult {
+    readonly passed: boolean;
+    readonly report?: unknown;
+}
+
 /** Guard runner implementation registered in the workflow host. */
 export interface GuardRunner {
     readonly kind: string;
-    evaluate(options: Record<string, unknown>, context: GuardContext): Promise<boolean>;
+    evaluate(options: Record<string, unknown>, context: GuardContext): Promise<boolean | GuardEvaluationResult>;
 }
 
 /** Input for running a workflow. */
@@ -162,6 +173,8 @@ export interface WorkflowRunOptions {
     readonly onError?: OnErrorPolicy;
     /** Validate the definition and walk the transition graph without executing actions. */
     readonly dryRun?: boolean;
+    /** Optional caller-supplied external key, unique per workflow definition. */
+    readonly externalKey?: string;
 }
 
 /** Result returned by both driver loops. */
@@ -184,8 +197,44 @@ export interface WorkflowRunRecord {
     readonly started_at: string;
     readonly completed_at: string | null;
     readonly metadata_json: string;
+    /** Optional caller-supplied external key, unique per workflow definition. */
+    readonly external_key?: string | null;
 }
 
+/** Result of force-setting the current state of a run. */
+export interface WorkflowReseedResult {
+    readonly fromState: string | null;
+    readonly toState: string;
+}
+
+/** Reason categories when an external transition request is denied. */
+export type TransitionDeniedReason = 'no-such-transition' | 'guard-failed';
+
+/** Result when an external transition request is allowed. */
+export interface TransitionAllowed {
+    readonly allowed: true;
+    /** The state the run has moved to. */
+    readonly toState: string;
+    /** The state the run moved from. */
+    readonly fromState: string;
+}
+
+/** Result when an external transition request is denied. */
+export interface TransitionDenied {
+    readonly allowed: false;
+    /** Machine-readable reason category. */
+    readonly reason: TransitionDeniedReason;
+    /** Human-readable detail from the guard (when guard-failed) or transition lookup. */
+    readonly detail: string;
+    /** The guard kind that was evaluated (when guard-failed). */
+    readonly guardKind?: string;
+    /** Machine-readable guard report/output when a guard was evaluated. */
+    readonly guardReport?: unknown;
+}
+
+/** Discriminated union result for external transition requests. */
+export type TransitionRequestResult = TransitionAllowed | TransitionDenied;
+
 /** Persisted action run record — one row per action executed in a workflow run. */
 export interface ActionRunRecord {
     readonly id: string;
@@ -223,4 +272,14 @@ export interface WorkflowPersistenceAdapter {
     ): Promise<void>;
     loadRun(runId: string): Promise<WorkflowRunRecord | undefined>;
     listRuns(): Promise<readonly WorkflowRunRecord[]>;
+    /** Look up a run by its external key within a workflow definition. Returns undefined if not found. */
+    findRunByKey(workflowName: string, externalKey: string): Promise<WorkflowRunRecord | undefined>;
+    /** Create a run or attach to an existing one by external key. Atomic create-or-attach semantics. */
+    createOrAttachRun(record: WorkflowRunRecord): Promise<WorkflowRunRecord>;
+    /** Force-set the current state of a run (consumer-side authority reconciliation). */
+    reseedRun(runId: string, newState: string): Promise<WorkflowReseedResult>;
+    /** Load the current state name for a run (latest state snapshot). Returns undefined if no state recorded. */
+    loadCurrentState(runId: string): Promise<string | undefined>;
+    /** List runs with status 'paused'. Optional filters: workflow name, limit. Ordered most-recent-first. */
+    listPausedRuns(options?: { workflowName?: string; limit?: number }): Promise<readonly WorkflowRunRecord[]>;
 }