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

package/src/run-lifecycle.ts

@@ -71,24 +71,43 @@ export interface RunLifecycleDeps {
  */
 export class RunLifecycle {
     readonly runId: string;
+    readonly externalKey?: string;
     private readonly persistence: WorkflowPersistenceAdapter;
     private readonly events: EventBus<WorkflowEngineEvents> | undefined;
     private readonly logger: Logger;
-    private readonly startedAt: string;
 
     private constructor(
         runId: string,
         private readonly workflowName: string,
         private readonly mode: WorkflowMode,
         deps: RunLifecycleDeps,
+        externalKey?: string,
     ) {
         this.runId = runId;
+        this.externalKey = externalKey;
         this.persistence = deps.persistence;
         this.events = deps.events;
-        this.startedAt = new Date().toISOString();
         this.logger = (deps.logger ?? getLogger('workflow')).child({ runId, workflow: workflowName, mode });
     }
 
+    /**
+     * Build a lifecycle for an external, single-hop transition request — NOT a run.
+     * Unlike {@link run} / {@link resume} this opens no `workflow.run` span and
+     * creates no run record: an external transition is one guarded hop on an
+     * already-existing run, so it must not masquerade as a run in traces. It exists
+     * only to let {@link WorkflowService.requestTransition} reuse {@link recordTransition}
+     * and {@link guardEvaluated} so the transition persist+emit mechanics live in one
+     * place instead of being hand-rolled at the service layer.
+     */
+    static forExternalTransition(
+        workflowName: string,
+        runId: string,
+        deps: RunLifecycleDeps,
+        externalKey: string | undefined,
+    ): RunLifecycle {
+        return new RunLifecycle(runId, workflowName, 'state-machine', deps, externalKey);
+    }
+
     /**
      * Create the run record and execute `loop` inside the run's OTel span. The
      * driver's control loop is the body; it receives this lifecycle to drive
@@ -101,28 +120,66 @@ export class RunLifecycle {
         options: WorkflowRunOptions,
         loop: (lifecycle: RunLifecycle) => Promise<WorkflowRunResult>,
     ): Promise<WorkflowRunResult> {
-        const runId = options.runId ?? crypto.randomUUID();
-        const lifecycle = new RunLifecycle(runId, workflowName, mode, deps);
         return await traceAsync(
             'workflow.run',
             async () => {
-                await lifecycle.persistence.createRun(lifecycle.runRecord(options.metadata));
+                const startedAt = new Date().toISOString();
+                const proposed = RunLifecycle.runRecord(
+                    options.runId ?? crypto.randomUUID(),
+                    workflowName,
+                    mode,
+                    startedAt,
+                    options.metadata,
+                    options.externalKey,
+                );
+                let record = proposed;
+                if (options.externalKey === undefined) {
+                    await deps.persistence.createRun(proposed);
+                } else {
+                    record = await deps.persistence.createOrAttachRun(proposed);
+                }
+                const extKey = record.external_key ?? undefined;
+                const lifecycle = new RunLifecycle(record.id, workflowName, mode, deps, extKey);
                 lifecycle.logger.info('workflow run started');
                 addSpanEvent('workflow.run.started', {
                     workflowName,
                     mode,
-                    runId,
+                    runId: lifecycle.runId,
                     dryRun: options.dryRun ?? false,
                 });
                 void lifecycle.events?.emit('workflow.run.started', {
                     workflowName,
                     mode,
-                    runId,
+                    runId: lifecycle.runId,
                     dryRun: options.dryRun ?? false,
+                    externalKey: extKey,
                 });
                 return await loop(lifecycle);
             },
-            { attributes: { 'workflow.name': workflowName, 'workflow.mode': mode, 'workflow.run_id': runId } },
+            { attributes: { 'workflow.name': workflowName, 'workflow.mode': mode } },
+        );
+    }
+
+    /**
+     * Resume an existing run without creating a new record. Used by driver resume paths.
+     * The caller is responsible for ensuring the run exists and emitting the resumed event.
+     */
+    static async resume(
+        workflowName: string,
+        mode: WorkflowMode,
+        deps: RunLifecycleDeps,
+        runId: string,
+        externalKey: string | undefined,
+        loop: (lifecycle: RunLifecycle) => Promise<WorkflowRunResult>,
+    ): Promise<WorkflowRunResult> {
+        return await traceAsync(
+            'workflow.run',
+            async () => {
+                const lifecycle = new RunLifecycle(runId, workflowName, mode, deps, externalKey);
+                lifecycle.logger.info('workflow run resumed');
+                return await loop(lifecycle);
+            },
+            { attributes: { 'workflow.name': workflowName, 'workflow.mode': mode } },
         );
     }
 
@@ -156,6 +213,7 @@ export class RunLifecycle {
             from,
             to,
             trigger,
+            externalKey: this.externalKey,
         });
     }
 
@@ -165,7 +223,12 @@ export class RunLifecycle {
         await this.persistence.finalizeRun(this.runId, 'done', new Date().toISOString());
         this.logger.info('workflow run done', { finalState, transitionsTaken });
         addSpanEvent('workflow.run.done', { runId: this.runId, finalState, transitionsTaken });
-        void this.events?.emit('workflow.run.done', { runId: this.runId, finalState, transitionsTaken });
+        void this.events?.emit('workflow.run.done', {
+            runId: this.runId,
+            finalState,
+            transitionsTaken,
+            externalKey: this.externalKey,
+        });
         return this.result('done', finalState, transitionsTaken);
     }
 
@@ -174,11 +237,37 @@ export class RunLifecycle {
         await this.persistence.savePhase(this.runId, finalState, 'failed');
         await this.persistence.finalizeRun(this.runId, 'failed', new Date().toISOString());
         addSpanEvent('workflow.run.failed', { runId: this.runId, finalState, reason });
-        void this.events?.emit('workflow.run.failed', { runId: this.runId, finalState, reason });
+        void this.events?.emit('workflow.run.failed', {
+            runId: this.runId,
+            finalState,
+            reason,
+            externalKey: this.externalKey,
+        });
         this.logger.warn('workflow run failed', { finalState, transitionsTaken, reason });
         return this.result('failed', finalState, transitionsTaken, reason);
     }
 
+    /** Finalize the run as paused and return its result. */
+    async pause(stateOrNodeId: string, transitionsTaken: number): Promise<WorkflowRunResult> {
+        await this.persistence.savePhase(this.runId, stateOrNodeId, 'paused');
+        await this.persistence.finalizeRun(this.runId, 'paused', new Date().toISOString());
+        this.logger.info('workflow run paused', { stateOrNodeId, transitionsTaken });
+        addSpanEvent('workflow.run.paused', { runId: this.runId, node: stateOrNodeId, transitionsTaken });
+        void this.events?.emit('workflow.run.paused', {
+            runId: this.runId,
+            node: stateOrNodeId,
+            transitionsTaken,
+            externalKey: this.externalKey,
+        });
+        return this.result('paused', stateOrNodeId, transitionsTaken);
+    }
+
+    /** Emit the resumed event (called by WorkflowService after re-creating a lifecycle for resume). */
+    emitResumed(node: string): void {
+        addSpanEvent('workflow.run.resumed', { runId: this.runId, node });
+        void this.events?.emit('workflow.run.resumed', { runId: this.runId, node, externalKey: this.externalKey });
+    }
+
     /** Emit action-level observability before a host action is invoked. */
     actionStart(stateOrNodeId: string, kind: string): void {
         addSpanEvent('workflow.action.start', { runId: this.runId, node: stateOrNodeId, kind });
@@ -222,6 +311,7 @@ export class RunLifecycle {
             to,
             kind,
             passed,
+            externalKey: this.externalKey,
         });
     }
 
@@ -252,15 +342,23 @@ export class RunLifecycle {
         };
     }
 
-    private runRecord(metadata: unknown): WorkflowRunRecord {
+    private static runRecord(
+        runId: string,
+        workflowName: string,
+        mode: WorkflowMode,
+        startedAt: string,
+        metadata: unknown,
+        externalKey?: string,
+    ): WorkflowRunRecord {
         return {
-            id: this.runId,
-            workflow_name: this.workflowName,
-            mode: this.mode,
+            id: runId,
+            workflow_name: workflowName,
+            mode,
             status: 'running',
-            started_at: this.startedAt,
+            started_at: startedAt,
             metadata_json: JSON.stringify(metadata ?? {}),
             completed_at: null,
+            external_key: externalKey ?? null,
         };
     }
 }

package/src/schema-sql.ts

@@ -6,6 +6,7 @@ CREATE TABLE IF NOT EXISTS runs (
     mode TEXT,
     status TEXT NOT NULL,
     agent TEXT,
+    external_key TEXT,
     started_at TEXT NOT NULL,
     completed_at TEXT,
     metadata_json TEXT NOT NULL DEFAULT '{}',
@@ -13,6 +14,10 @@ CREATE TABLE IF NOT EXISTS runs (
     updated_at INTEGER NOT NULL DEFAULT 0
 );
 
+CREATE UNIQUE INDEX IF NOT EXISTS idx_runs_external_key
+    ON runs (workflow_name, external_key)
+    WHERE external_key IS NOT NULL;
+
 CREATE TABLE IF NOT EXISTS phase_runs (
     id TEXT PRIMARY KEY,
     run_id TEXT NOT NULL,

package/src/schema.ts

@@ -58,6 +58,8 @@ export const StateMachineWorkflowDefSchema = z
                     description: z.string().optional(),
                     onEnter: z.array(ActionDefSchema).optional(),
                     onExit: z.array(ActionDefSchema).optional(),
+                    /** When true, the engine pauses the run at this state instead of auto-advancing. */
+                    pause: z.boolean().optional(),
                 })
                 .strict(),
         ),
@@ -97,6 +99,8 @@ export const TransitionFlowWorkflowDefSchema = z
                     description: z.string().optional(),
                     type: z.enum(['action', 'gate', 'parallel', 'decision']).optional(),
                     action: ActionDefSchema.optional(),
+                    /** When true, the engine pauses the run at this node instead of auto-advancing. */
+                    pause: z.boolean().optional(),
                 })
                 .strict(),
         ),

package/src/service.ts

@@ -1,11 +1,25 @@
 import { loadWorkflowDef } from './config';
+import { FSMError, WorkflowResumeError } from './errors';
 import type { WorkflowEngineHost } from './host';
+import { RunLifecycle } from './run-lifecycle';
 import { StateMachineDriver } from './state-machine';
 import { TransitionFlowDriver } from './transition-flow';
-import type { WorkflowDef, WorkflowPersistenceAdapter, WorkflowRunOptions, WorkflowRunResult } from './types';
+import type {
+    StateMachineWorkflowDef,
+    TransitionDenied,
+    TransitionRequestResult,
+    WorkflowDef,
+    WorkflowPersistenceAdapter,
+    WorkflowRunOptions,
+    WorkflowRunRecord,
+    WorkflowRunResult,
+} from './types';
 
 /** High-level workflow service for loading, running, and listing persisted workflow runs. */
 export class WorkflowService {
+    /** Per-run serialization: ensures concurrent requestTransition calls serialize. */
+    private readonly runLocks = new Map<string, Promise<void>>();
+
     constructor(
         private readonly host: WorkflowEngineHost,
         private readonly persistence: WorkflowPersistenceAdapter,
@@ -36,4 +50,244 @@ export class WorkflowService {
     async listRuns() {
         return await this.persistence.listRuns();
     }
+
+    /** Find a run by its external key within a workflow definition. */
+    async findRunByKey(workflowName: string, externalKey: string): Promise<WorkflowRunRecord | undefined> {
+        return await this.persistence.findRunByKey(workflowName, externalKey);
+    }
+
+    /** Create a new run or attach to an existing one identified by external key. */
+    async createOrAttachRun(record: WorkflowRunRecord): Promise<WorkflowRunRecord> {
+        return await this.persistence.createOrAttachRun(record);
+    }
+
+    /** Force-set the current state of a run (consumer-side authority reconciliation). */
+    async reseedRun(
+        workflow: WorkflowDef,
+        runId: string,
+        newState: string,
+        options?: WorkflowRunOptions,
+    ): Promise<void>;
+    async reseedRun(runId: string, newState: string, options?: WorkflowRunOptions): Promise<void>;
+    async reseedRun(
+        workflowOrRunId: WorkflowDef | string,
+        runIdOrNewState: string,
+        newStateOrOptions?: string | WorkflowRunOptions,
+        maybeOptions?: WorkflowRunOptions,
+    ): Promise<void> {
+        // 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 as WorkflowRunOptions | undefined,
+                  }
+                : {
+                      workflow: workflowOrRunId,
+                      runId: runIdOrNewState,
+                      newState: newStateOrOptions as string,
+                      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). */
+    private assertReseedTargetDeclared(workflow: WorkflowDef, runId: string, newState: string): void {
+        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. */
+    private async commitReseed(runId: string, newState: string, options?: WorkflowRunOptions): Promise<void> {
+        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: WorkflowDef, runId: string, options?: WorkflowRunOptions): Promise<WorkflowRunResult> {
+        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 as StateMachineWorkflowDef, runId, currentState, extKey, options);
+    }
+
+    /** List runs currently paused. Optional filters and ordering. */
+    async listPausedRuns(options?: { workflowName?: string; limit?: number }): Promise<readonly WorkflowRunRecord[]> {
+        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: StateMachineWorkflowDef,
+        runId: string,
+        toState: string,
+        options?: WorkflowRunOptions,
+    ): Promise<TransitionRequestResult> {
+        // Serialize per-run: chain onto the existing lock, then clean up.
+        let release!: () => void;
+        const previous = this.runLocks.get(runId) ?? Promise.resolve();
+        const next = previous.then(
+            () =>
+                new Promise<void>((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);
+            }
+        }
+    }
+
+    private async evaluateAndCommit(
+        workflow: StateMachineWorkflowDef,
+        runId: string,
+        toState: string,
+        options?: WorkflowRunOptions,
+    ): Promise<TransitionRequestResult> {
+        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.
+     */
+    private denyTransition(
+        options: WorkflowRunOptions | undefined,
+        runId: string,
+        from: string,
+        to: string,
+        externalKey: string | undefined,
+        denial: Omit<TransitionDenied, 'allowed'>,
+    ): TransitionDenied {
+        void options?.events?.emit('workflow.transition.denied', {
+            runId,
+            from,
+            to,
+            reason: denial.reason,
+            externalKey,
+        });
+        return { allowed: false, ...denial };
+    }
 }