@gobing-ai/ts-dual-workflow-engine 0.2.8 → 0.2.9

package/src/state-machine.ts

@@ -54,6 +54,7 @@ export class StateMachineDriver {
                 vars,
                 env,
                 options,
+                transitionsTaken,
             );
             if (lastActionResult?.ok === false)
                 return await this.fail(
@@ -103,6 +104,7 @@ export class StateMachineDriver {
                 vars,
                 env,
                 options,
+                transitionsTaken,
             );
             if (exitResult?.ok === false)
                 return await this.fail(runId, workflow.name, mode, current.id, transitionsTaken, exitResult.error);
@@ -139,13 +141,14 @@ export class StateMachineDriver {
         vars: Record<string, string>,
         env: Record<string, string>,
         options: WorkflowRunOptions,
+        transitionsTaken: number,
     ): Promise<ActionResult | undefined> {
         let last: ActionResult | undefined;
         for (const action of actions) {
             const resolved = resolveTemplates(action.options ?? {}, {
                 vars,
                 env,
-                builtins: { workflow: workflowName, state: stateId, runId },
+                builtins: runtimeBuiltins(workflowName, stateId, runId, transitionsTaken),
             });
             last = await this.options.host.runAction(action.kind, resolved, {
                 runId,
@@ -186,6 +189,25 @@ export class StateMachineDriver {
     }
 }
 
+/** 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',
+    };
+}
+
 async function firstPassingTransition(
     transitions: StateMachineWorkflowDef['transitions'],
     host: WorkflowEngineHost,

package/src/transition-flow.ts

@@ -1,4 +1,5 @@
 import { getProcessEnv } from '@gobing-ai/ts-runtime';
+import { FSMError } from './errors';
 import type { WorkflowEngineHost } from './host';
 import type {
     ActionResult,
@@ -37,7 +38,7 @@ export class TransitionFlowDriver {
         const iterationBound = workflow.iterationBound ?? 50;
 
         if (current === undefined) {
-            throw new Error(`Initial node "${workflow.initialNode}" is not declared`);
+            throw new FSMError(`Initial node "${workflow.initialNode}" is not declared`);
         }
 
         while (true) {
@@ -50,7 +51,7 @@ export class TransitionFlowDriver {
                 const resolved = resolveTemplates(current.action.options ?? {}, {
                     vars,
                     env,
-                    builtins: { workflow: workflow.name, node: current.id, runId },
+                    builtins: runtimeBuiltins(workflow.name, current.id, runId, transitionsTaken),
                 });
                 lastActionResult = await this.options.host.runAction(current.action.kind, resolved, {
                     runId,
@@ -110,7 +111,7 @@ export class TransitionFlowDriver {
 
             // 7. Move to the target node and repeat.
             const nextNode = nodes.get(edge.to);
-            if (nextNode === undefined) throw new Error(`Edge target "${edge.to}" is not declared`);
+            if (nextNode === undefined) throw new FSMError(`Edge target "${edge.to}" is not declared`);
             current = nextNode;
         }
     }
@@ -141,6 +142,25 @@ export class TransitionFlowDriver {
     }
 }
 
+/** 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(
     edges: TransitionFlowWorkflowDef['edges'],
     host: WorkflowEngineHost,

package/src/types.ts

@@ -24,6 +24,8 @@ export interface GuardDef {
 /** One state in a state-machine workflow. */
 export interface StateDef {
     readonly id: string;
+    /** Optional human description of what this state does. */
+    readonly description?: string;
     readonly onEnter?: readonly ActionDef[];
     readonly onExit?: readonly ActionDef[];
 }
@@ -32,6 +34,8 @@ export interface StateDef {
 export interface TransitionDef {
     readonly from: string;
     readonly to: string;
+    /** Optional human description of when/why this transition is taken. */
+    readonly description?: string;
     readonly trigger?: string;
     readonly guard?: GuardDef;
 }
@@ -40,6 +44,10 @@ export interface TransitionDef {
 export interface StateMachineWorkflowDef {
     readonly kind?: 'state-machine';
     readonly name: string;
+    /** Optional behavior-free document version tag. */
+    readonly version?: string;
+    /** Optional human description of the workflow's purpose. */
+    readonly description?: string;
     readonly initialState: string;
     readonly terminalStates?: readonly string[];
     readonly iterationBound?: number;
@@ -52,6 +60,8 @@ export interface StateMachineWorkflowDef {
 /** Transition-flow node definition. */
 export interface FlowNodeDef {
     readonly id: string;
+    /** Optional human description of what this node does. */
+    readonly description?: string;
     readonly type?: 'action' | 'gate' | 'parallel' | 'decision';
     readonly action?: ActionDef;
 }
@@ -60,6 +70,8 @@ export interface FlowNodeDef {
 export interface FlowEdgeDef {
     readonly from: string;
     readonly to: string;
+    /** Optional human description of when/why this edge is taken. */
+    readonly description?: string;
     readonly condition?: GuardDef;
 }
 
@@ -67,6 +79,10 @@ export interface FlowEdgeDef {
 export interface TransitionFlowWorkflowDef {
     readonly kind: 'transition-flow';
     readonly name: string;
+    /** Optional behavior-free document version tag. */
+    readonly version?: string;
+    /** Optional human description of the workflow's purpose. */
+    readonly description?: string;
     readonly initialNode: string;
     readonly terminalNodes?: readonly string[];
     readonly iterationBound?: number;