@hexabot-ai/agentic 3.4.0 → 3.5.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (134) hide show
  1. package/README.md +67 -15
  2. package/dist/cjs/action/abstract-action.js +13 -1
  3. package/dist/cjs/checkpoint.js +301 -0
  4. package/dist/cjs/context.js +11 -27
  5. package/dist/cjs/dsl.types.js +3 -0
  6. package/dist/cjs/errors.js +116 -9
  7. package/dist/cjs/index.js +15 -6
  8. package/dist/cjs/resume-payload.js +257 -0
  9. package/dist/cjs/runner-runtime-control.js +181 -306
  10. package/dist/cjs/step-executors/conditional-executor.js +27 -29
  11. package/dist/cjs/step-executors/loop-executor.js +53 -62
  12. package/dist/cjs/step-executors/parallel-executor.js +169 -102
  13. package/dist/cjs/step-executors/task-executor.js +180 -96
  14. package/dist/cjs/utils/clone.js +73 -0
  15. package/dist/cjs/workflow-fingerprint.js +138 -0
  16. package/dist/cjs/workflow-runner.js +220 -155
  17. package/dist/cjs/workflow.js +24 -12
  18. package/dist/esm/action/abstract-action.js +14 -2
  19. package/dist/esm/checkpoint.js +293 -0
  20. package/dist/esm/context.js +11 -27
  21. package/dist/esm/dsl.types.js +3 -0
  22. package/dist/esm/errors.js +105 -6
  23. package/dist/esm/index.js +3 -3
  24. package/dist/esm/resume-payload.js +250 -0
  25. package/dist/esm/runner-runtime-control.js +179 -303
  26. package/dist/esm/step-executors/conditional-executor.js +27 -29
  27. package/dist/esm/step-executors/loop-executor.js +53 -62
  28. package/dist/esm/step-executors/parallel-executor.js +165 -98
  29. package/dist/esm/step-executors/task-executor.js +181 -97
  30. package/dist/esm/utils/clone.js +67 -0
  31. package/dist/esm/workflow-fingerprint.js +134 -0
  32. package/dist/esm/workflow-runner.js +220 -155
  33. package/dist/esm/workflow.js +24 -12
  34. package/dist/types/action/abstract-action.d.ts.map +1 -1
  35. package/dist/types/action/action.types.d.ts +0 -14
  36. package/dist/types/action/action.types.d.ts.map +1 -1
  37. package/dist/types/checkpoint.d.ts +188 -0
  38. package/dist/types/checkpoint.d.ts.map +1 -0
  39. package/dist/types/context.d.ts +45 -11
  40. package/dist/types/context.d.ts.map +1 -1
  41. package/dist/types/dsl.types.d.ts.map +1 -1
  42. package/dist/types/errors.d.ts +77 -3
  43. package/dist/types/errors.d.ts.map +1 -1
  44. package/dist/types/index.d.ts +6 -7
  45. package/dist/types/index.d.ts.map +1 -1
  46. package/dist/types/resume-payload.d.ts +69 -0
  47. package/dist/types/resume-payload.d.ts.map +1 -0
  48. package/dist/types/runner-runtime-control.d.ts +63 -51
  49. package/dist/types/runner-runtime-control.d.ts.map +1 -1
  50. package/dist/types/step-executors/conditional-executor.d.ts +6 -3
  51. package/dist/types/step-executors/conditional-executor.d.ts.map +1 -1
  52. package/dist/types/step-executors/loop-executor.d.ts +6 -4
  53. package/dist/types/step-executors/loop-executor.d.ts.map +1 -1
  54. package/dist/types/step-executors/parallel-executor.d.ts +11 -3
  55. package/dist/types/step-executors/parallel-executor.d.ts.map +1 -1
  56. package/dist/types/step-executors/task-executor.d.ts +11 -4
  57. package/dist/types/step-executors/task-executor.d.ts.map +1 -1
  58. package/dist/types/step-executors/types.d.ts +21 -13
  59. package/dist/types/step-executors/types.d.ts.map +1 -1
  60. package/dist/types/utils/clone.d.ts +33 -0
  61. package/dist/types/utils/clone.d.ts.map +1 -0
  62. package/dist/types/workflow-event-emitter.d.ts +29 -5
  63. package/dist/types/workflow-event-emitter.d.ts.map +1 -1
  64. package/dist/types/workflow-fingerprint.d.ts +14 -0
  65. package/dist/types/workflow-fingerprint.d.ts.map +1 -0
  66. package/dist/types/workflow-runner.d.ts +83 -41
  67. package/dist/types/workflow-runner.d.ts.map +1 -1
  68. package/dist/types/workflow-types.d.ts +25 -54
  69. package/dist/types/workflow-types.d.ts.map +1 -1
  70. package/dist/types/workflow.d.ts +24 -9
  71. package/dist/types/workflow.d.ts.map +1 -1
  72. package/examples/defs-bindings-agent/bindings.ts +1 -1
  73. package/examples/defs-bindings-agent/workflow.ts +3 -2
  74. package/examples/full/actions/await-user-input.ts +3 -2
  75. package/examples/full/actions/call-llm.ts +18 -18
  76. package/examples/full/actions/create-ticket.ts +1 -2
  77. package/examples/full/actions/decision-router.ts +6 -2
  78. package/examples/full/actions/get-calendar-events.ts +1 -2
  79. package/examples/full/actions/get-user-profile.ts +1 -2
  80. package/examples/full/actions/query-memory.ts +1 -2
  81. package/examples/full/actions/search-web.ts +1 -2
  82. package/examples/full/actions/send-email.ts +3 -2
  83. package/examples/full/workflow.ts +3 -2
  84. package/examples/loop/actions/await-reply.ts +2 -7
  85. package/examples/loop/workflow.ts +4 -2
  86. package/examples/suspend-resume/actions/wait-for-user.ts +11 -9
  87. package/examples/suspend-resume/workflow.ts +51 -11
  88. package/package.json +3 -3
  89. package/src/__tests__/checkpoint.test.ts +2568 -0
  90. package/src/__tests__/resume-payload.test.ts +245 -0
  91. package/src/__tests__/runner-runtime-control.test.ts +265 -0
  92. package/src/__tests__/workflow-fingerprint.test.ts +165 -0
  93. package/src/__tests__/workflow-runner.test.ts +167 -144
  94. package/src/__tests__/workflow.test.ts +97 -6
  95. package/src/action/abstract-action.ts +21 -2
  96. package/src/action/action.types.ts +0 -12
  97. package/src/checkpoint.ts +561 -0
  98. package/src/context.ts +51 -41
  99. package/src/dsl.types.ts +3 -0
  100. package/src/errors.ts +161 -8
  101. package/src/index.ts +33 -14
  102. package/src/resume-payload.ts +326 -0
  103. package/src/runner-runtime-control.ts +222 -456
  104. package/src/step-executors/conditional-executor.test.ts +77 -46
  105. package/src/step-executors/conditional-executor.ts +47 -40
  106. package/src/step-executors/loop-executor.test.ts +106 -92
  107. package/src/step-executors/loop-executor.ts +84 -101
  108. package/src/step-executors/parallel-executor.test.ts +300 -89
  109. package/src/step-executors/parallel-executor.ts +243 -125
  110. package/src/step-executors/task-executor.test.ts +321 -51
  111. package/src/step-executors/task-executor.ts +232 -145
  112. package/src/step-executors/types.ts +23 -22
  113. package/src/utils/clone.ts +75 -0
  114. package/src/workflow-event-emitter.ts +32 -6
  115. package/src/workflow-fingerprint.ts +159 -0
  116. package/src/workflow-runner.ts +325 -209
  117. package/src/workflow-types.ts +25 -56
  118. package/src/workflow.ts +41 -34
  119. package/dist/cjs/step-executors/suspension-continuation.js +0 -27
  120. package/dist/cjs/suspension-rebuilder.js +0 -265
  121. package/dist/cjs/utils/deferred.js +0 -17
  122. package/dist/esm/step-executors/suspension-continuation.js +0 -24
  123. package/dist/esm/suspension-rebuilder.js +0 -260
  124. package/dist/esm/utils/deferred.js +0 -14
  125. package/dist/types/step-executors/suspension-continuation.d.ts +0 -10
  126. package/dist/types/step-executors/suspension-continuation.d.ts.map +0 -1
  127. package/dist/types/suspension-rebuilder.d.ts +0 -67
  128. package/dist/types/suspension-rebuilder.d.ts.map +0 -1
  129. package/dist/types/utils/deferred.d.ts +0 -7
  130. package/dist/types/utils/deferred.d.ts.map +0 -1
  131. package/src/__tests__/suspension-rebuilder.test.ts +0 -404
  132. package/src/step-executors/suspension-continuation.ts +0 -31
  133. package/src/suspension-rebuilder.ts +0 -446
  134. package/src/utils/deferred.ts +0 -23
@@ -9,9 +9,11 @@ import type { ZodType } from 'zod';
9
9
 
10
10
  import type { Action } from './action/action.types';
11
11
  import type { CompiledTaskBindings } from './bindings/base-binding';
12
+ import type { WaitInfo, WorkflowCheckpoint } from './checkpoint';
12
13
  import type { BaseWorkflowContext, WorkflowSnapshot } from './context';
13
14
  import type { Settings, TaskDefinition, WorkflowDefinition } from './dsl.types';
14
- import { StepType, type StepInfo } from './workflow-event-emitter';
15
+ import type { WorkflowResumeRejectedError } from './errors';
16
+ import { StepType } from './workflow-event-emitter';
15
17
 
16
18
  export type { CompiledTaskBindings } from './bindings/base-binding';
17
19
 
@@ -154,66 +156,35 @@ export type ExecutionState = {
154
156
  iterationStack: number[];
155
157
  };
156
158
 
157
- /** Encapsulates a suspended step and how to continue it. */
158
- export type Suspension = {
159
- step: StepInfo;
160
- reason?: string;
161
- data?: unknown;
162
- stepExecId?: string;
163
- suspendIndex?: number;
164
- suspendKey?: string;
165
- awaitResults?: Record<string, unknown>;
166
- continue: (resumeData: unknown) => Promise<Suspension | void>;
159
+ /** Result of a run that paused on one or more open waits. */
160
+ export type SuspendedResult = {
161
+ status: 'suspended';
162
+ /** Open waits, in flow order; resume one of them by `waitId`. */
163
+ waits: WaitInfo[];
164
+ /** Everything a host must persist to resume the run later. */
165
+ checkpoint: WorkflowCheckpoint;
166
+ snapshot: WorkflowSnapshot;
167
+ /**
168
+ * Set when this resume was refused: the run and its checkpoint are exactly
169
+ * as they were, and the wait is still open under the same `waitId`.
170
+ */
171
+ rejection?: ResumeRejection;
167
172
  };
168
173
 
169
- export type PersistedSuspension = {
170
- stepId: string;
171
- reason?: string | null;
172
- data?: unknown;
173
- stepExecId?: string;
174
- suspendIndex?: number;
175
- suspendKey?: string;
176
- awaitResults?: Record<string, unknown>;
174
+ /** A resume payload that was refused. */
175
+ export type ResumeRejection = {
176
+ waitId: string;
177
+ error: WorkflowResumeRejectedError;
177
178
  };
178
179
 
179
- /** Result of starting a workflow run. */
180
- export type StartResult =
180
+ /** Where a run stopped: the result of both `start()` and `resume()`. */
181
+ export type WorkflowRunResult =
181
182
  | {
182
183
  status: 'finished';
183
184
  output: Record<string, unknown>;
184
185
  snapshot: WorkflowSnapshot;
185
186
  }
186
- | {
187
- status: 'suspended';
188
- step: StepInfo;
189
- reason?: string;
190
- data?: unknown;
191
- stepExecId?: string;
192
- suspendIndex?: number;
193
- suspendKey?: string;
194
- awaitResults?: Record<string, unknown>;
195
- snapshot: WorkflowSnapshot;
196
- }
197
- | { status: 'failed'; error: unknown; snapshot: WorkflowSnapshot };
198
-
199
- /** Result of resuming a suspended workflow. */
200
- export type ResumeResult =
201
- | {
202
- status: 'finished';
203
- output: Record<string, unknown>;
204
- snapshot: WorkflowSnapshot;
205
- }
206
- | {
207
- status: 'suspended';
208
- step: StepInfo;
209
- reason?: string;
210
- data?: unknown;
211
- stepExecId?: string;
212
- suspendIndex?: number;
213
- suspendKey?: string;
214
- awaitResults?: Record<string, unknown>;
215
- snapshot: WorkflowSnapshot;
216
- }
187
+ | SuspendedResult
217
188
  | { status: 'failed'; error: unknown; snapshot: WorkflowSnapshot };
218
189
 
219
190
  /** Options that influence how the workflow runner behaves. */
@@ -221,10 +192,6 @@ export type WorkflowRunOptions = {
221
192
  runId?: string;
222
193
  };
223
194
 
224
- export type WorkflowStartResult = StartResult;
225
-
226
- export type WorkflowResumeResult = ResumeResult;
227
-
228
195
  /** Arguments required to start a run. */
229
196
  export type RunnerStartArgs = {
230
197
  inputData: unknown;
@@ -234,4 +201,6 @@ export type RunnerStartArgs = {
234
201
  /** Payload passed when resuming a suspended run. */
235
202
  export type RunnerResumeArgs = {
236
203
  resumeData?: unknown;
204
+ /** Wait to satisfy; required only when the run has several open waits. */
205
+ waitId?: string;
237
206
  };
package/src/workflow.ts CHANGED
@@ -6,6 +6,11 @@
6
6
 
7
7
  import { stringify as stringifyYaml } from 'yaml';
8
8
 
9
+ import {
10
+ validateCheckpoint,
11
+ type CheckpointValidationResult,
12
+ type WaitInfo,
13
+ } from './checkpoint';
9
14
  import {
10
15
  EWorkflowRunStatus,
11
16
  type BaseWorkflowContext,
@@ -25,12 +30,7 @@ import {
25
30
  type WorkflowCompileOptions,
26
31
  } from './workflow-compiler';
27
32
  import { WorkflowRunner } from './workflow-runner';
28
- import type {
29
- CompiledWorkflow,
30
- ExecutionState,
31
- PersistedSuspension,
32
- WorkflowRunOptions,
33
- } from './workflow-types';
33
+ import type { CompiledWorkflow, WorkflowRunOptions } from './workflow-types';
34
34
 
35
35
  export { compileWorkflow } from './workflow-compiler';
36
36
 
@@ -38,31 +38,24 @@ export { WorkflowEventEmitter } from './workflow-event-emitter';
38
38
 
39
39
  export { WorkflowRunner } from './workflow-runner';
40
40
 
41
- export type {
42
- WorkflowResumeResult,
43
- WorkflowRunOptions,
44
- WorkflowStartResult,
45
- } from './workflow-types';
41
+ export type { WorkflowRunOptions, WorkflowRunResult } from './workflow-types';
46
42
 
47
43
  export type { WorkflowCompileOptions } from './workflow-compiler';
48
44
 
49
45
  export type FlowStepPath = Array<string | number>;
50
46
 
51
47
  class WorkflowRunSuspendedError extends Error {
52
- public readonly stepId: string;
53
-
54
- public readonly reason?: string;
55
-
56
- public readonly data?: unknown;
48
+ /** Every open wait of the run, in flow order. */
49
+ public readonly waits: WaitInfo[];
57
50
 
58
- constructor(stepId: string, options?: { reason?: string; data?: unknown }) {
59
- super(
60
- `Workflow run suspended at step ${stepId}${options?.reason ? `: ${options.reason}` : ''}`,
51
+ constructor(waits: WaitInfo[]) {
52
+ const steps = waits.map(({ step, reason }) =>
53
+ reason ? `${step.id} (${reason})` : step.id,
61
54
  );
55
+
56
+ super(`Workflow run suspended at ${steps.join(', ')}`);
62
57
  this.name = 'WorkflowRunSuspendedError';
63
- this.stepId = stepId;
64
- this.reason = options?.reason;
65
- this.data = options?.data;
58
+ this.waits = waits;
66
59
  }
67
60
  }
68
61
 
@@ -357,10 +350,7 @@ export class Workflow {
357
350
  }
358
351
 
359
352
  context.attachWorkflowRuntime(undefined);
360
- throw new WorkflowRunSuspendedError(result.step.id, {
361
- reason: result.reason,
362
- data: result.data,
363
- });
353
+ throw new WorkflowRunSuspendedError(result.waits);
364
354
  }
365
355
 
366
356
  /**
@@ -373,16 +363,33 @@ export class Workflow {
373
363
  }
374
364
 
375
365
  /**
376
- * Rebuild a runner from persisted state and snapshot, useful after restarts.
366
+ * Decide whether a persisted checkpoint can resume against this workflow,
367
+ * without running anything. Call it before claiming a wait.
368
+ *
369
+ * @param checkpoint The checkpoint, as persisted.
370
+ * @param options.waitId Wait the caller is about to resume.
371
+ * @param options.resumeData Payload the caller is about to resume with,
372
+ * checked against what the wait accepts when the key is present.
373
+ * @returns The parsed checkpoint, or the typed reason it cannot resume.
374
+ */
375
+ validateCheckpoint(
376
+ checkpoint: unknown,
377
+ options?: { waitId?: string; resumeData?: unknown },
378
+ ): CheckpointValidationResult {
379
+ return validateCheckpoint(this.compiled, checkpoint, options);
380
+ }
381
+
382
+ /**
383
+ * Restore a suspended runner from its persisted checkpoint, useful after restarts.
384
+ *
385
+ * @throws {WorkflowResumeError} When the checkpoint cannot resume against this workflow.
377
386
  */
378
- async buildRunnerFromState(options: {
379
- state: ExecutionState;
387
+ buildRunnerFromCheckpoint(options: {
388
+ checkpoint: unknown;
380
389
  context: BaseWorkflowContext;
381
- snapshot: WorkflowSnapshot;
382
- suspension?: PersistedSuspension;
390
+ snapshot?: WorkflowSnapshot;
383
391
  runId?: string;
384
- lastResumeData?: unknown;
385
- }): Promise<WorkflowRunner> {
386
- return WorkflowRunner.fromPersistedState(this.compiled, options);
392
+ }): WorkflowRunner {
393
+ return WorkflowRunner.fromCheckpoint(this.compiled, options);
387
394
  }
388
395
  }
@@ -1,27 +0,0 @@
1
- "use strict";
2
- /*
3
- * Hexabot — Fair Core License (FCL-1.0-ALv2)
4
- * Copyright (c) 2025 Hexastack.
5
- * Full terms: see LICENSE.md.
6
- */
7
- Object.defineProperty(exports, "__esModule", { value: true });
8
- exports.wrapSuspensionContinuation = wrapSuspensionContinuation;
9
- /**
10
- * Compose a suspension with the continuation that should run once it completes.
11
- *
12
- * When resuming a suspension yields another suspension from the same logical
13
- * step, the follow-up suspension still needs to remember how to continue the
14
- * surrounding flow after that step eventually finishes.
15
- */
16
- function wrapSuspensionContinuation(suspension, onComplete) {
17
- return {
18
- ...suspension,
19
- continue: async (resumeData) => {
20
- const next = await suspension.continue(resumeData);
21
- if (next) {
22
- return wrapSuspensionContinuation(next, onComplete);
23
- }
24
- return onComplete();
25
- },
26
- };
27
- }
@@ -1,265 +0,0 @@
1
- "use strict";
2
- /*
3
- * Hexabot — Fair Core License (FCL-1.0-ALv2)
4
- * Copyright (c) 2025 Hexastack.
5
- * Full terms: see LICENSE.md.
6
- */
7
- Object.defineProperty(exports, "__esModule", { value: true });
8
- exports.parseSuspendedStepId = parseSuspendedStepId;
9
- exports.rebuildSuspension = rebuildSuspension;
10
- exports.buildSuspensionForPath = buildSuspensionForPath;
11
- const loop_executor_1 = require("./step-executors/loop-executor");
12
- const suspension_continuation_1 = require("./step-executors/suspension-continuation");
13
- const workflow_event_emitter_1 = require("./workflow-event-emitter");
14
- /**
15
- * Parse a suspended step id into its execution path and iteration stack.
16
- *
17
- * @param stepId The serialized step identifier stored in snapshots.
18
- * @returns The decoded path tokens and iteration stack.
19
- */
20
- function parseSuspendedStepId(stepId) {
21
- const iterationMatch = stepId.match(/^(.*)\[(.+)\]$/);
22
- const baseId = iterationMatch ? iterationMatch[1] : stepId;
23
- const iterationStack = iterationMatch
24
- ? iterationMatch[2]
25
- .split('.')
26
- .map((token) => Number.parseInt(token, 10))
27
- .filter((value) => !Number.isNaN(value))
28
- : [];
29
- const [pathPart] = baseId.split(':');
30
- const path = pathPart.length === 0 || pathPart === 'root'
31
- ? []
32
- : pathPart.split('.').map((token) => {
33
- const numeric = Number.parseInt(token, 10);
34
- return Number.isNaN(numeric) ? token : numeric;
35
- });
36
- return { path, iterationStack };
37
- }
38
- /**
39
- * Rebuild a suspension object based on persisted state and step identifiers.
40
- *
41
- * @param deps Dependencies needed to reconstruct executors and events.
42
- * @param param0 Persisted state and metadata about the suspended step.
43
- * @param param0.state Execution state captured at suspension time.
44
- * @param param0.stepId Serialized step id used to locate the suspension point.
45
- * @param param0.reason Optional reason supplied when the workflow suspended.
46
- * @param param0.data Arbitrary payload provided with the suspension.
47
- * @returns A suspension ready to be resumed, or null if reconstruction fails.
48
- */
49
- function rebuildSuspension(deps, { state, stepId, reason, data, stepExecId, suspendIndex, suspendKey, awaitResults, }) {
50
- if (!state) {
51
- return null;
52
- }
53
- const { path, iterationStack } = parseSuspendedStepId(stepId);
54
- const executionState = {
55
- ...state,
56
- iterationStack: iterationStack.length > 0 ? iterationStack : (state.iterationStack ?? []),
57
- };
58
- const suspensionMetadata = {
59
- stepExecId,
60
- suspendIndex,
61
- suspendKey,
62
- reason,
63
- awaitResults,
64
- };
65
- const suspension = buildSuspensionForPath(deps, deps.compiled.flow, executionState, path, [], 0, suspensionMetadata);
66
- if (!suspension) {
67
- return null;
68
- }
69
- return {
70
- ...suspension,
71
- reason,
72
- data,
73
- stepExecId,
74
- suspendIndex,
75
- suspendKey,
76
- awaitResults,
77
- };
78
- }
79
- /**
80
- * Walk the compiled flow to rebuild the continuation matching a target path.
81
- *
82
- * @param deps Dependencies for executor creation and event emission.
83
- * @param steps The steps to search for the suspended step.
84
- * @param state Mutable execution state to thread through the traversal.
85
- * @param targetPath Path tokens identifying the suspended step location.
86
- * @param pathPrefix Prefix accumulated while descending the tree.
87
- * @param iterationDepth Current loop depth to match iteration stacks.
88
- * @returns A rebuilt suspension or null if the path cannot be matched.
89
- */
90
- function buildSuspensionForPath(deps, steps, state, targetPath, pathPrefix, iterationDepth = 0, suspensionMetadata = {}) {
91
- if (!deps.context) {
92
- throw new Error('Workflow context is not attached.');
93
- }
94
- const env = deps.createExecutorEnv();
95
- if (targetPath.length === 0) {
96
- return null;
97
- }
98
- const [current, ...rest] = targetPath;
99
- if (typeof current !== 'number') {
100
- return null;
101
- }
102
- const step = steps[current];
103
- const currentPath = [...pathPrefix, current];
104
- if (!step) {
105
- return null;
106
- }
107
- if (rest.length === 0) {
108
- if (step.type !== workflow_event_emitter_1.StepType.Task) {
109
- return null;
110
- }
111
- const stepInfo = deps.buildInstanceStepInfo(step, state.iterationStack);
112
- const replayStepExecId = suspensionMetadata.stepExecId ?? `${stepInfo.id}#1`;
113
- const replaySuspension = suspensionMetadata.suspendIndex !== undefined ||
114
- suspensionMetadata.suspendKey !== undefined
115
- ? {
116
- suspendIndex: suspensionMetadata.suspendIndex,
117
- suspendKey: suspensionMetadata.suspendKey,
118
- reason: suspensionMetadata.reason,
119
- }
120
- : undefined;
121
- return {
122
- step: stepInfo,
123
- continue: async (resumeData) => {
124
- const executorEnv = deps.createExecutorEnv();
125
- const prepareStepReplay = executorEnv
126
- .prepareStepReplay;
127
- const recordStepSuspendResult = executorEnv.recordStepSuspendResult;
128
- const primeStepResumeData = executorEnv
129
- .primeStepResumeData;
130
- const executeStep = executorEnv
131
- .executeStep;
132
- if (typeof executeStep === 'function') {
133
- if (typeof prepareStepReplay === 'function') {
134
- prepareStepReplay({
135
- stepId: stepInfo.id,
136
- stepExecId: replayStepExecId,
137
- awaitResults: suspensionMetadata.awaitResults,
138
- activeSuspension: replaySuspension,
139
- });
140
- }
141
- if (typeof recordStepSuspendResult === 'function' &&
142
- replaySuspension) {
143
- recordStepSuspendResult({
144
- stepId: stepInfo.id,
145
- stepExecId: replayStepExecId,
146
- suspendIndex: suspensionMetadata.suspendIndex,
147
- suspendKey: suspensionMetadata.suspendKey,
148
- resumeData,
149
- });
150
- }
151
- else if (typeof primeStepResumeData === 'function') {
152
- primeStepResumeData(stepInfo.id, resumeData);
153
- }
154
- const resumed = await executeStep(step, state, currentPath);
155
- if (resumed) {
156
- return (0, suspension_continuation_1.wrapSuspensionContinuation)(resumed, () => deps.executeFlow(steps, state, pathPrefix, current + 1));
157
- }
158
- return deps.executeFlow(steps, state, pathPrefix, current + 1);
159
- }
160
- const task = deps.compiled.tasks[step.taskName];
161
- if (!task) {
162
- throw new Error(`Task "${step.taskName}" is not defined.`);
163
- }
164
- await deps.captureTaskOutput(task, state, resumeData);
165
- deps.markSnapshot(stepInfo, 'completed');
166
- deps.emit('hook:step:success', { runId: deps.runId, step: stepInfo });
167
- return deps.executeFlow(steps, state, pathPrefix, current + 1);
168
- },
169
- };
170
- }
171
- if (step.type === workflow_event_emitter_1.StepType.Parallel) {
172
- return null;
173
- }
174
- if (step.type === workflow_event_emitter_1.StepType.Conditional) {
175
- if (rest[0] !== 'branch' || typeof rest[1] !== 'number') {
176
- return null;
177
- }
178
- const branchIndex = rest[1];
179
- const childPath = rest.slice(2);
180
- const branch = step.branches[branchIndex];
181
- if (!branch) {
182
- return null;
183
- }
184
- const branchSuspension = buildSuspensionForPath(deps, branch.steps, state, childPath, [...currentPath, 'branch', branchIndex], iterationDepth, suspensionMetadata);
185
- if (!branchSuspension) {
186
- return null;
187
- }
188
- return (0, suspension_continuation_1.wrapSuspensionContinuation)(branchSuspension, () => deps.executeFlow(steps, state, pathPrefix, current + 1));
189
- }
190
- if (step.type === workflow_event_emitter_1.StepType.Loop) {
191
- if (rest.length < 1 || typeof rest[0] !== 'string') {
192
- return null;
193
- }
194
- const loopToken = rest[0];
195
- const childPath = rest.slice(1);
196
- const targetIterationStack = state.iterationStack ?? [];
197
- const iterationIndex = targetIterationStack[iterationDepth] ?? state.iteration?.index;
198
- if (iterationIndex === undefined) {
199
- return null;
200
- }
201
- const ancestorIterationStack = targetIterationStack.slice(0, iterationDepth);
202
- const iterationState = {
203
- ...state,
204
- iterationStack: targetIterationStack,
205
- iteration: state.iteration ??
206
- {
207
- item: undefined,
208
- index: iterationIndex,
209
- },
210
- };
211
- const childSuspension = buildSuspensionForPath(deps, step.steps, iterationState, childPath, [...currentPath, loopToken], iterationDepth + 1, suspensionMetadata);
212
- if (!childSuspension) {
213
- return null;
214
- }
215
- const accumulator = iterationState.accumulator ?? state.accumulator ?? undefined;
216
- return (0, suspension_continuation_1.wrapSuspensionContinuation)(childSuspension, async () => {
217
- const scope = {
218
- input: iterationState.input,
219
- context: env.context.state,
220
- output: iterationState.output,
221
- iteration: iterationState.iteration ?? {
222
- item: undefined,
223
- index: iterationIndex,
224
- },
225
- accumulator,
226
- };
227
- const updatedAccumulator = await (0, loop_executor_1.updateAccumulator)(step, scope, accumulator);
228
- const shouldStop = await (0, loop_executor_1.shouldStopLoop)(step, scope);
229
- state.output = iterationState.output;
230
- if (step.accumulate && step.name) {
231
- state.output[step.name] = {
232
- [step.accumulate.as]: updatedAccumulator,
233
- };
234
- }
235
- if (step.accumulate) {
236
- state.accumulator = updatedAccumulator;
237
- }
238
- if (shouldStop) {
239
- return deps.executeFlow(steps, state, pathPrefix, current + 1);
240
- }
241
- const baseState = {
242
- ...iterationState,
243
- iterationStack: ancestorIterationStack,
244
- accumulator: updatedAccumulator,
245
- output: state.output,
246
- };
247
- const next = await (0, loop_executor_1.executeLoop)(env, step, baseState, currentPath, iterationIndex + 1);
248
- state.output = baseState.output;
249
- if (step.accumulate) {
250
- state.accumulator = baseState.accumulator;
251
- }
252
- if (next) {
253
- return (0, suspension_continuation_1.wrapSuspensionContinuation)(next, async () => {
254
- state.output = baseState.output;
255
- if (step.accumulate) {
256
- state.accumulator = baseState.accumulator;
257
- }
258
- return deps.executeFlow(steps, state, pathPrefix, current + 1);
259
- });
260
- }
261
- return deps.executeFlow(steps, state, pathPrefix, current + 1);
262
- });
263
- }
264
- return null;
265
- }
@@ -1,17 +0,0 @@
1
- "use strict";
2
- /*
3
- * Hexabot — Fair Core License (FCL-1.0-ALv2)
4
- * Copyright (c) 2025 Hexastack.
5
- * Full terms: see LICENSE.md.
6
- */
7
- Object.defineProperty(exports, "__esModule", { value: true });
8
- exports.createDeferred = createDeferred;
9
- function createDeferred() {
10
- let resolve;
11
- let reject;
12
- const promise = new Promise((res, rej) => {
13
- resolve = res;
14
- reject = rej;
15
- });
16
- return { promise, resolve, reject };
17
- }
@@ -1,24 +0,0 @@
1
- /*
2
- * Hexabot — Fair Core License (FCL-1.0-ALv2)
3
- * Copyright (c) 2025 Hexastack.
4
- * Full terms: see LICENSE.md.
5
- */
6
- /**
7
- * Compose a suspension with the continuation that should run once it completes.
8
- *
9
- * When resuming a suspension yields another suspension from the same logical
10
- * step, the follow-up suspension still needs to remember how to continue the
11
- * surrounding flow after that step eventually finishes.
12
- */
13
- export function wrapSuspensionContinuation(suspension, onComplete) {
14
- return {
15
- ...suspension,
16
- continue: async (resumeData) => {
17
- const next = await suspension.continue(resumeData);
18
- if (next) {
19
- return wrapSuspensionContinuation(next, onComplete);
20
- }
21
- return onComplete();
22
- },
23
- };
24
- }