@gobing-ai/ts-dual-workflow-engine 0.3.14 → 0.3.17

package/dist/service.js

@@ -1,10 +1,14 @@
 import { loadWorkflowDef } from './config.js';
+import { FSMError, WorkflowResumeError } from './errors.js';
+import { RunLifecycle } from './run-lifecycle.js';
 import { StateMachineDriver } from './state-machine.js';
 import { TransitionFlowDriver } from './transition-flow.js';
 /** High-level workflow service for loading, running, and listing persisted workflow runs. */
 export class WorkflowService {
     host;
     persistence;
+    /** Per-run serialization: ensures concurrent requestTransition calls serialize. */
+    runLocks = new Map();
     constructor(host, persistence) {
         this.host = host;
         this.persistence = persistence;
@@ -28,4 +32,184 @@ export class WorkflowService {
     async listRuns() {
         return await this.persistence.listRuns();
     }
+    /** Find a run by its external key within a workflow definition. */
+    async findRunByKey(workflowName, externalKey) {
+        return await this.persistence.findRunByKey(workflowName, externalKey);
+    }
+    /** Create a new run or attach to an existing one identified by external key. */
+    async createOrAttachRun(record) {
+        return await this.persistence.createOrAttachRun(record);
+    }
+    async reseedRun(workflowOrRunId, runIdOrNewState, newStateOrOptions, maybeOptions) {
+        // Normalize the two overloads to a single typed shape exactly once, so the
+        // commit path below never re-discriminates or casts.
+        const args = typeof workflowOrRunId === 'string'
+            ? {
+                workflow: undefined,
+                runId: workflowOrRunId,
+                newState: runIdOrNewState,
+                options: newStateOrOptions,
+            }
+            : {
+                workflow: workflowOrRunId,
+                runId: runIdOrNewState,
+                newState: newStateOrOptions,
+                options: maybeOptions,
+            };
+        if (args.workflow !== undefined) {
+            this.assertReseedTargetDeclared(args.workflow, args.runId, args.newState);
+        }
+        await this.commitReseed(args.runId, args.newState, args.options);
+    }
+    /** Reject a reseed target the workflow definition does not allow (state-machine states only). */
+    assertReseedTargetDeclared(workflow, runId, newState) {
+        if (workflow.kind === 'transition-flow') {
+            throw new FSMError('reseedRun only supports state-machine workflows');
+        }
+        if (!workflow.states.some((state) => state.id === newState)) {
+            throw new FSMError(`Cannot reseed run "${runId}" to undeclared state "${newState}"`);
+        }
+    }
+    /** Persist the reseed and emit the corrective event with the run's external key. */
+    async commitReseed(runId, newState, options) {
+        const run = await this.persistence.loadRun(runId);
+        const extKey = run?.external_key ?? undefined;
+        const result = await this.persistence.reseedRun(runId, newState);
+        void options?.events?.emit('workflow.run.reseeded', {
+            runId,
+            fromState: result.fromState ?? '',
+            toState: result.toState,
+            externalKey: extKey,
+        });
+    }
+    /** Resume a paused run, continuing execution from where it stopped. */
+    async resumeRun(workflow, runId, options) {
+        const run = await this.persistence.loadRun(runId);
+        if (run === undefined) {
+            throw new WorkflowResumeError(`Run "${runId}" not found`);
+        }
+        if (run.status !== 'paused') {
+            throw new WorkflowResumeError(`Run "${runId}" is not paused (status: ${run.status})`);
+        }
+        const currentState = await this.persistence.loadCurrentState(runId);
+        if (currentState === undefined) {
+            throw new WorkflowResumeError(`Run "${runId}" has no persisted state to resume from`);
+        }
+        // Re-open the run as running.
+        const extKey = run.external_key ?? undefined;
+        await this.persistence.finalizeRun(runId, 'running', '');
+        void options?.events?.emit('workflow.run.resumed', { runId, node: currentState, externalKey: extKey });
+        // Resume through the appropriate driver, starting from the paused state (skip on-enter).
+        if (workflow.kind === 'transition-flow') {
+            return await new TransitionFlowDriver({
+                host: this.host,
+                persistence: this.persistence,
+            }).resume(workflow, runId, currentState, extKey, options);
+        }
+        return await new StateMachineDriver({
+            host: this.host,
+            persistence: this.persistence,
+        }).resume(workflow, runId, currentState, extKey, options);
+    }
+    /** List runs currently paused. Optional filters and ordering. */
+    async listPausedRuns(options) {
+        return await this.persistence.listPausedRuns(options);
+    }
+    /**
+     * Request an external state transition on a run. Evaluates whether the
+     * transition exists and its guard passes; commits or denies atomically.
+     * Concurrent requests on the same run serialize — the loser re-evaluates
+     * against the new state.
+     */
+    async requestTransition(workflow, runId, toState, options) {
+        // Serialize per-run: chain onto the existing lock, then clean up.
+        let release;
+        const previous = this.runLocks.get(runId) ?? Promise.resolve();
+        const next = previous.then(() => new Promise((resolve) => {
+            release = resolve;
+        }));
+        this.runLocks.set(runId, next);
+        await previous;
+        try {
+            return await this.evaluateAndCommit(workflow, runId, toState, options);
+        }
+        finally {
+            release();
+            if (this.runLocks.get(runId) === next) {
+                this.runLocks.delete(runId);
+            }
+        }
+    }
+    async evaluateAndCommit(workflow, runId, toState, options) {
+        const currentState = await this.persistence.loadCurrentState(runId);
+        const run = await this.persistence.loadRun(runId);
+        const extKey = run?.external_key ?? undefined;
+        if (currentState === undefined) {
+            // No state recorded yet: nothing to transition from, and no `from` to
+            // address a denial event at — return the denial without emitting.
+            return {
+                allowed: false,
+                reason: 'no-such-transition',
+                detail: `No state recorded for run "${runId}"`,
+            };
+        }
+        // An external transition is a single guarded hop on an existing run, not a
+        // run itself — borrow a span-free lifecycle so the transition persist+emit
+        // mechanics reuse the same seam the drivers use (no new workflow.run span).
+        const lifecycle = RunLifecycle.forExternalTransition(workflow.name, runId, { persistence: this.persistence, events: options?.events }, extKey);
+        // Find the matching transition from current state to requested state.
+        const transition = workflow.transitions.find((t) => t.from === currentState && t.to === toState);
+        if (transition === undefined) {
+            return this.denyTransition(options, runId, currentState, toState, extKey, {
+                reason: 'no-such-transition',
+                detail: `No transition from "${currentState}" to "${toState}"`,
+            });
+        }
+        // Evaluate guard if present.
+        if (transition.guard !== undefined) {
+            const guardResult = await this.host.evaluateGuardResult(transition.guard.kind, transition.guard.options ?? {}, {
+                runId,
+                current: currentState,
+                vars: {},
+                workdir: options?.workdir,
+            });
+            lifecycle.guardEvaluated(currentState, toState, transition.guard.kind, guardResult.passed);
+            if (!guardResult.passed) {
+                return this.denyTransition(options, runId, currentState, toState, extKey, {
+                    reason: 'guard-failed',
+                    detail: `Guard "${transition.guard.kind}" denied transition from "${currentState}" to "${toState}"`,
+                    guardKind: transition.guard.kind,
+                    ...(guardResult.report === undefined ? {} : { guardReport: guardResult.report }),
+                });
+            }
+        }
+        // Commit: persist the transition + emit node.transition through the shared
+        // lifecycle seam, then the external-only state snapshot and requested event.
+        const trigger = transition.trigger ?? null;
+        await lifecycle.recordTransition(currentState, toState, trigger);
+        await this.persistence.saveWorkflowState(runId, toState, {});
+        void options?.events?.emit('workflow.transition.requested', {
+            runId,
+            from: currentState,
+            to: toState,
+            trigger,
+            externalKey: extKey,
+        });
+        return { allowed: true, fromState: currentState, toState };
+    }
+    /**
+     * Build a `TransitionDenied` result and emit its `workflow.transition.denied`
+     * event in one place — the single denial seam for the external-transition path,
+     * so the event payload and the returned reason can never drift apart.
+     */
+    denyTransition(options, runId, from, to, externalKey, denial) {
+        void options?.events?.emit('workflow.transition.denied', {
+            runId,
+            from,
+            to,
+            reason: denial.reason,
+            externalKey,
+        });
+        return { allowed: false, ...denial };
+    }
 }

package/dist/state-machine.d.ts

@@ -11,13 +11,8 @@ export declare class StateMachineDriver {
     constructor(options: StateMachineDriverOptions);
     /** Run a state-machine workflow to completion or failure. */
     run(workflow: StateMachineWorkflowDef, options?: WorkflowRunOptions): Promise<WorkflowRunResult>;
+    /** Resume a paused state-machine run from the given state, skipping on-enter. */
+    resume(workflow: StateMachineWorkflowDef, runId: string, resumeFromState: string, externalKey: string | undefined, options?: WorkflowRunOptions): Promise<WorkflowRunResult>;
     private loop;
-    /**
-     * 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 runActions;
 }
 //# sourceMappingURL=state-machine.d.ts.map

package/dist/state-machine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../src/state-machine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAEjD,OAAO,KAAK,EAIR,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,EACpB,MAAM,SAAS,CAAC;AAGjB,yDAAyD;AACzD,MAAM,WAAW,yBAAyB;IACtC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,0BAA0B,CAAC;CACpD;AAED,wEAAwE;AACxE,qBAAa,kBAAkB;IACf,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,yBAAyB;IAE/D,6DAA6D;IACvD,GAAG,CAAC,QAAQ,EAAE,uBAAuB,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;YAU5F,IAAI;IAoGlB;;;;;OAKG;YACW,UAAU;CAwD3B"}
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../src/state-machine.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAEjD,OAAO,KAAK,EAER,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,EACpB,MAAM,SAAS,CAAC;AAGjB,yDAAyD;AACzD,MAAM,WAAW,yBAAyB;IACtC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,0BAA0B,CAAC;CACpD;AAED,wEAAwE;AACxE,qBAAa,kBAAkB;IACf,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,yBAAyB;IAE/D,6DAA6D;IACvD,GAAG,CAAC,QAAQ,EAAE,uBAAuB,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAU1G,iFAAiF;IAC3E,MAAM,CACR,QAAQ,EAAE,uBAAuB,EACjC,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,OAAO,GAAE,kBAAuB,GACjC,OAAO,CAAC,iBAAiB,CAAC;YAWf,IAAI;CAwHrB"}

package/dist/state-machine.js

@@ -1,6 +1,7 @@
+import { runActionSequence } from './action-step.js';
 import { FSMError } from './errors.js';
-import { allowedEnv, RunLifecycle, runtimeBuiltins } from './run-lifecycle.js';
-import { mergeSetVars, mergeVars, resolveOnErrorPolicy, resolveTemplates } from './variables.js';
+import { allowedEnv, RunLifecycle } from './run-lifecycle.js';
+import { mergeSetVars, mergeVars } from './variables.js';
 /** State-machine workflow driver with an R7 single control function. */
 export class StateMachineDriver {
     options;
@@ -11,38 +12,69 @@ export class StateMachineDriver {
     async run(workflow, options = {}) {
         return await RunLifecycle.run(workflow.name, 'state-machine', { persistence: this.options.persistence, events: options.events }, options, (lifecycle) => this.loop(workflow, options, lifecycle));
     }
-    async loop(workflow, options, lifecycle) {
+    /** Resume a paused state-machine run from the given state, skipping on-enter. */
+    async resume(workflow, runId, resumeFromState, externalKey, options = {}) {
+        return await RunLifecycle.resume(workflow.name, 'state-machine', { persistence: this.options.persistence, events: options.events }, runId, externalKey, (lifecycle) => this.loop(workflow, options, lifecycle, resumeFromState));
+    }
+    async loop(workflow, options, lifecycle, resumeFromState) {
         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;
         const iterationBound = workflow.iterationBound ?? 50;
         const defaultOnError = workflow.defaultOnError;
-        if (current === undefined)
-            throw new FSMError(`Initial state "${workflow.initialState}" is not declared`);
+        let isResume = resumeFromState !== undefined;
+        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);
+            if (isResume) {
+                // Resume: skip enter actions on the first iteration (already ran before pause).
+                isResume = false;
             }
-            // 4. Halt only when an action failed under a 'fail' policy.
-            if (enter.outcome === 'fail') {
-                return await lifecycle.fail(current.id, transitionsTaken, lastActionResult?.error);
+            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);
             if (terminal.has(current.id) || outbound.length === 0) {
@@ -59,7 +91,21 @@ export class StateMachineDriver {
                 return await lifecycle.fail(current.id, transitionsTaken, 'no-passing-transition');
             }
             // 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)
@@ -78,54 +124,9 @@ 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`.
-     */
-    async runActions(actions, workflowName, stateId, runId, vars, env, options, transitionsTaken, lifecycle, defaultOnError) {
-        if (options.dryRun) {
-            return { outcome: 'completed', result: undefined };
-        }
-        let last;
-        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 };
-    }
 }
+/** Dry-run sentinel: no action ran, so there is nothing to retain and nothing to halt on. */
+const EMPTY_OUTCOME = { outcome: 'completed', result: undefined };
 async function firstPassingTransition(transitions, host, context, lifecycle) {
     for (const transition of transitions) {
         if (transition.guard === undefined)

package/dist/transition-flow.d.ts

@@ -11,6 +11,8 @@ export declare class TransitionFlowDriver {
     constructor(options: TransitionFlowDriverOptions);
     /** Run a transition-flow workflow to completion or failure. */
     run(workflow: TransitionFlowWorkflowDef, options?: WorkflowRunOptions): Promise<WorkflowRunResult>;
+    /** Resume a paused transition-flow run from the given node, skipping node action. */
+    resume(workflow: TransitionFlowWorkflowDef, runId: string, resumeFromNode: string, externalKey: string | undefined, options?: WorkflowRunOptions): Promise<WorkflowRunResult>;
     private loop;
 }
 //# sourceMappingURL=transition-flow.d.ts.map

package/dist/transition-flow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transition-flow.d.ts","sourceRoot":"","sources":["../src/transition-flow.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAEjD,OAAO,KAAK,EAER,yBAAyB,EACzB,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,EACpB,MAAM,SAAS,CAAC;AAGjB,2DAA2D;AAC3D,MAAM,WAAW,2BAA2B;IACxC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,0BAA0B,CAAC;CACpD;AAED,0EAA0E;AAC1E,qBAAa,oBAAoB;IACjB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,2BAA2B;IAEjE,+DAA+D;IACzD,GAAG,CAAC,QAAQ,EAAE,yBAAyB,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;YAU9F,IAAI;CA6GrB"}
+{"version":3,"file":"transition-flow.d.ts","sourceRoot":"","sources":["../src/transition-flow.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAEjD,OAAO,KAAK,EAER,yBAAyB,EACzB,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,EACpB,MAAM,SAAS,CAAC;AAGjB,2DAA2D;AAC3D,MAAM,WAAW,2BAA2B;IACxC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,0BAA0B,CAAC;CACpD;AAED,0EAA0E;AAC1E,qBAAa,oBAAoB;IACjB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,2BAA2B;IAEjE,+DAA+D;IACzD,GAAG,CAAC,QAAQ,EAAE,yBAAyB,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAU5G,qFAAqF;IAC/E,MAAM,CACR,QAAQ,EAAE,yBAAyB,EACnC,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,OAAO,GAAE,kBAAuB,GACjC,OAAO,CAAC,iBAAiB,CAAC;YAWf,IAAI;CAuGrB"}

package/dist/transition-flow.js

@@ -1,6 +1,7 @@
+import { runActionStep } from './action-step.js';
 import { FSMError } from './errors.js';
-import { allowedEnv, RunLifecycle, runtimeBuiltins } from './run-lifecycle.js';
-import { mergeSetVars, mergeVars, resolveOnErrorPolicy, resolveTemplates } from './variables.js';
+import { allowedEnv, RunLifecycle } from './run-lifecycle.js';
+import { mergeSetVars, mergeVars } from './variables.js';
 /** Transition-flow workflow driver with an R7 single control function. */
 export class TransitionFlowDriver {
     options;
@@ -11,65 +12,67 @@ export class TransitionFlowDriver {
     async run(workflow, options = {}) {
         return await RunLifecycle.run(workflow.name, 'transition-flow', { persistence: this.options.persistence, events: options.events }, options, (lifecycle) => this.loop(workflow, options, lifecycle));
     }
-    async loop(workflow, options, lifecycle) {
+    /** Resume a paused transition-flow run from the given node, skipping node action. */
+    async resume(workflow, runId, resumeFromNode, externalKey, options = {}) {
+        return await RunLifecycle.resume(workflow.name, 'transition-flow', { persistence: this.options.persistence, events: options.events }, runId, externalKey, (lifecycle) => this.loop(workflow, options, lifecycle, resumeFromNode));
+    }
+    async loop(workflow, options, lifecycle, resumeFromNode) {
         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;
         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);
-            // 2. Execute the node action when one is configured (skipped in dry-run).
-            if (options.dryRun) {
-                if (current.action !== undefined) {
-                    lastActionResult = undefined;
-                }
+            if (isResume) {
+                // Resume: skip enter + node action on the first iteration (already ran before pause).
+                isResume = false;
             }
-            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,
+            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 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);
                 }
             }
             // 3. Stop when the node is terminal or no outgoing edge exists.

package/dist/types.d.ts

@@ -3,7 +3,7 @@ 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';
+export type WorkflowStatus = 'running' | 'done' | 'failed' | 'paused';
 /** Runtime variables and user variables available to workflow definitions. */
 export type Vars = Record<string, string>;
 /** Environment allowlist carried by a workflow definition. */
@@ -29,6 +29,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. */
 export interface TransitionDef {
@@ -64,6 +66,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. */
 export interface FlowEdgeDef {
@@ -123,12 +127,18 @@ 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. */
 export interface WorkflowRunOptions {
@@ -143,6 +153,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. */
 export interface WorkflowRunResult {
@@ -163,7 +175,38 @@ 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;
@@ -192,5 +235,18 @@ export interface WorkflowPersistenceAdapter {
     saveActionFinalize(actionId: string, status: WorkflowStatus, durationMs: number, ok: boolean, result?: unknown, redactor?: ActionRedactor): 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[]>;
 }
 //# sourceMappingURL=types.d.ts.map