@hexabot-ai/agentic 3.4.0-beta.2 → 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
@@ -4,6 +4,21 @@
4
4
  * Full terms: see LICENSE.md.
5
5
  */
6
6
 
7
+ import {
8
+ assertFrameMatchesStep,
9
+ CHECKPOINT_VERSION,
10
+ collectWaits,
11
+ selectWait,
12
+ validateCheckpoint,
13
+ type ConditionalFrame,
14
+ type LoopFrame,
15
+ type ParallelFrame,
16
+ type SequenceFrame,
17
+ type StepFrame,
18
+ type TaskFrame,
19
+ type WaitInfo,
20
+ type WorkflowCheckpoint,
21
+ } from './checkpoint';
7
22
  import {
8
23
  EWorkflowRunStatus,
9
24
  type ActionSnapshot,
@@ -14,40 +29,59 @@ import {
14
29
  type WorkflowSnapshot,
15
30
  } from './context';
16
31
  import { throwIfAborted } from './errors';
32
+ import { checkResumePayload } from './resume-payload';
17
33
  import { RunnerRuntimeControl } from './runner-runtime-control';
18
34
  import { executeConditional as runConditionalExecutor } from './step-executors/conditional-executor';
19
35
  import { executeLoop as runLoopExecutor } from './step-executors/loop-executor';
20
36
  import { executeParallel as runParallelExecutor } from './step-executors/parallel-executor';
21
- import { wrapSuspensionContinuation } from './step-executors/suspension-continuation';
22
37
  import { executeTaskStep as runTaskExecutor } from './step-executors/task-executor';
23
38
  import type {
24
39
  StepExecutorEnv,
25
40
  StepExecutorEnvForkOverrides,
26
41
  } from './step-executors/types';
27
- import {
28
- rebuildSuspension,
29
- type SuspensionRebuilderDeps,
30
- } from './suspension-rebuilder';
42
+ import { cloneAsJson } from './utils/clone';
31
43
  import {
32
44
  StepType,
33
45
  type StepInfo,
34
46
  type WorkflowEventMap,
35
47
  } from './workflow-event-emitter';
48
+ import { fingerprintWorkflow } from './workflow-fingerprint';
36
49
  import type {
37
50
  CompiledStep,
38
51
  CompiledTask,
39
52
  CompiledWorkflow,
40
53
  ExecutionState,
41
- PersistedSuspension,
42
- ResumeResult,
54
+ ResumeRejection,
43
55
  RunnerResumeArgs,
44
56
  RunnerStartArgs,
45
- StartResult,
46
- Suspension,
57
+ SuspendedResult,
47
58
  WorkflowRunOptions,
59
+ WorkflowRunResult,
48
60
  } from './workflow-types';
49
61
  import { evaluateMapping } from './workflow-values';
50
62
 
63
+ /** One start or resume pass over the flow. */
64
+ type ExecutionPass = {
65
+ /** Resume payloads for the waits this pass satisfies, by wait id. */
66
+ resolutions: ReadonlyMap<string, unknown>;
67
+ /** Set when the resumed step refused its payload. */
68
+ rejection?: ResumeRejection;
69
+ };
70
+
71
+ /** What the runner reports about a run, put back when a resume is refused. */
72
+ type RunReport = {
73
+ state?: ExecutionState;
74
+ snapshots: Record<string, ActionSnapshot>;
75
+ stepLog: Record<string, StepExecutionRecord>;
76
+ };
77
+
78
+ /** The suspended run a resume pass starts from. */
79
+ type ResumedRun = {
80
+ checkpoint: WorkflowCheckpoint;
81
+ /** The report before the pass, restored if the payload is refused. */
82
+ report: RunReport;
83
+ };
84
+
51
85
  /**
52
86
  * Executes a compiled workflow definition, tracking state, suspensions, and event hooks.
53
87
  * Create a new instance per execution to avoid leaking state between runs.
@@ -68,18 +102,12 @@ export class WorkflowRunner {
68
102
  // Detailed execution records for each task step, used by UI/telemetry.
69
103
  private stepLog: Record<string, StepExecutionRecord> = {};
70
104
 
71
- // Suspension state when execution is paused awaiting external input.
72
- private suspension?: Suspension;
105
+ // Checkpoint of the run while it is suspended awaiting external input.
106
+ private checkpoint?: WorkflowCheckpoint;
73
107
 
74
108
  // Control surface exposed to actions to suspend/resume the workflow.
75
109
  private runtimeControl?: RunnerRuntimeControl;
76
110
 
77
- // Step currently being executed, used in event payloads and errors.
78
- private currentStep?: StepInfo;
79
-
80
- // Last payload provided to resume; exposed to actions via the context.
81
- private lastResumeData?: unknown;
82
-
83
111
  // Mutable execution state including input and outputs.
84
112
  private state?: ExecutionState;
85
113
 
@@ -146,21 +174,13 @@ export class WorkflowRunner {
146
174
  }
147
175
 
148
176
  /**
149
- * Read the step currently being executed.
177
+ * Read the checkpoint of a suspended run: everything a host must persist to
178
+ * resume it later, in this process or another one. Treat it as read-only.
150
179
  *
151
- * @returns Metadata for the in-flight step, if any.
180
+ * @returns The checkpoint while the run is suspended, otherwise undefined.
152
181
  */
153
- getCurrentStep(): StepInfo | undefined {
154
- return this.currentStep;
155
- }
156
-
157
- /**
158
- * Access the last payload supplied to a resume call.
159
- *
160
- * @returns The most recent resume data, or undefined if none.
161
- */
162
- getLastResumeData(): unknown {
163
- return this.lastResumeData;
182
+ getCheckpoint(): WorkflowCheckpoint | undefined {
183
+ return this.checkpoint;
164
184
  }
165
185
 
166
186
  /**
@@ -170,13 +190,11 @@ export class WorkflowRunner {
170
190
  * @param args Input payload and context to seed execution.
171
191
  * @returns Execution result including status and snapshot.
172
192
  */
173
- async start(args: RunnerStartArgs): Promise<StartResult> {
193
+ async start(args: RunnerStartArgs): Promise<WorkflowRunResult> {
174
194
  this.status = EWorkflowRunStatus.RUNNING;
175
195
  this.snapshots = {};
176
196
  this.stepLog = {};
177
- this.suspension = undefined;
178
- this.lastResumeData = undefined;
179
- this.currentStep = undefined;
197
+ this.checkpoint = undefined;
180
198
  this.context = args.context;
181
199
  this.state = {
182
200
  input: this.compiled.inputParser.parse(args.inputData ?? {}),
@@ -184,85 +202,163 @@ export class WorkflowRunner {
184
202
  iterationStack: [],
185
203
  };
186
204
 
187
- this.runtimeControl = new RunnerRuntimeControl(this);
205
+ this.runtimeControl = new RunnerRuntimeControl();
188
206
  this.context.attachWorkflowRuntime(this.runtimeControl);
189
207
 
190
208
  this.emit('hook:workflow:start', { runId: this.runId });
191
209
 
192
- const state = this.state;
193
- if (!state) {
194
- throw new Error('Workflow state not initialized.');
195
- }
196
-
197
- const env = this.createExecutorEnv();
198
-
199
- return this.runExecution(() =>
200
- this.executeFlow(this.compiled.flow, state, [], 0, env),
201
- );
210
+ return this.runExecution(new Map());
202
211
  }
203
212
 
204
213
  /**
205
- * Resume a previously suspended workflow using the supplied resume data.
214
+ * Resume a suspended workflow by satisfying one of its open waits.
206
215
  *
207
- * @param args Data provided to resume the suspended step.
216
+ * Execution re-enters the checkpoint's frames: completed work is skipped,
217
+ * the resolved step re-runs its action body, and waits left untouched stay
218
+ * parked.
219
+ *
220
+ * A payload the wait does not accept is refused, first against the wait's
221
+ * `accepts` JSON Schema without running anything, then by the action body.
222
+ * Either way the result is suspended on the same waits and carries
223
+ * `rejection`, and the checkpoint, snapshot and step log are left as they
224
+ * were. Events a refusing body emitted are not withdrawn, and its side
225
+ * effects, including writes to context state, are not undone.
226
+ *
227
+ * @param args Resume payload and, when several waits are open, the wait it satisfies.
208
228
  * @returns Execution result including status and snapshot.
229
+ * @throws {WorkflowWaitNotFoundError} When `waitId` is not an open wait.
230
+ * @throws {WorkflowWaitAmbiguousError} When several waits are open and no
231
+ * `waitId` is given.
209
232
  */
210
- async resume(args: RunnerResumeArgs): Promise<ResumeResult> {
211
- if (this.status !== EWorkflowRunStatus.SUSPENDED || !this.suspension) {
233
+ async resume(args: RunnerResumeArgs): Promise<WorkflowRunResult> {
234
+ if (this.status !== EWorkflowRunStatus.SUSPENDED || !this.checkpoint) {
212
235
  throw new Error('Cannot resume a workflow that is not suspended.');
213
236
  }
214
237
 
215
- if (!this.context || !this.state) {
238
+ if (!this.context) {
216
239
  throw new Error('Workflow state is not initialized.');
217
240
  }
218
241
 
219
- this.status = EWorkflowRunStatus.RUNNING;
220
- this.lastResumeData = args.resumeData;
242
+ const wait = selectWait(this.checkpoint.waits, args.waitId);
243
+ const payload = checkResumePayload(wait, args.resumeData);
244
+ const result = payload.ok
245
+ ? await this.resolveWait(wait, payload.value)
246
+ : this.keepWaiting(this.checkpoint, {
247
+ waitId: wait.waitId,
248
+ error: payload.error,
249
+ });
250
+ if (result.status === EWorkflowRunStatus.SUSPENDED && result.rejection) {
251
+ this.emit('hook:workflow:resume_rejected', {
252
+ runId: this.runId,
253
+ wait,
254
+ resumeData: args.resumeData,
255
+ error: result.rejection.error,
256
+ });
257
+ }
258
+
259
+ return result;
260
+ }
261
+
262
+ /**
263
+ * Run the pass that resolves one wait with an accepted payload.
264
+ *
265
+ * @param wait The wait being resolved.
266
+ * @param recorded The payload as the checkpoint records it.
267
+ * @returns Execution result including status and snapshot.
268
+ */
269
+ private async resolveWait(
270
+ wait: WaitInfo,
271
+ recorded: unknown,
272
+ ): Promise<WorkflowRunResult> {
273
+ const checkpoint = this.checkpoint;
274
+ if (!checkpoint) {
275
+ throw new Error('Cannot resume a workflow that is not suspended.');
276
+ }
221
277
 
222
- const suspension: Suspension = this.suspension;
278
+ const report: RunReport = {
279
+ state: this.state,
280
+ snapshots: { ...this.snapshots },
281
+ stepLog: { ...this.stepLog },
282
+ };
283
+ this.status = EWorkflowRunStatus.RUNNING;
284
+ this.context?.attachWorkflowRuntime(this.runtimeControl);
223
285
 
224
- return this.runExecution(() => suspension.continue(args.resumeData));
286
+ return this.runExecution(new Map([[wait.waitId, recorded]]), {
287
+ checkpoint,
288
+ report,
289
+ });
225
290
  }
226
291
 
227
292
  /**
228
- * Execute the provided workflow operation and normalize suspension, finish, and failure handling.
293
+ * Run the flow from the top, or from a checkpoint, and normalize
294
+ * suspension, finish, and failure handling.
229
295
  *
230
- * @param execute Function that advances workflow execution and may return a suspension.
296
+ * @param resolutions Resume payloads for the waits this pass satisfies.
297
+ * @param resumed Suspended run to resume from; omitted on start.
231
298
  * @returns Result of the execution attempt.
232
299
  */
233
300
  private async runExecution(
234
- execute: () => Promise<Suspension | void>,
235
- ): Promise<StartResult> {
301
+ resolutions: ReadonlyMap<string, unknown>,
302
+ resumed?: ResumedRun,
303
+ ): Promise<WorkflowRunResult> {
304
+ const pass: ExecutionPass = { resolutions };
305
+
236
306
  try {
237
- const suspension = await execute();
307
+ // In-process and durable resumes start from the same detached JSON
308
+ // copy, so both see exactly what a host would have persisted.
309
+ const from = resumed ? cloneAsJson(resumed.checkpoint) : undefined;
310
+ if (from) {
311
+ this.state = {
312
+ input: from.input,
313
+ output: from.output,
314
+ iterationStack: [],
315
+ };
316
+ }
317
+
318
+ const state = this.state;
319
+ if (!state) {
320
+ throw new Error('Workflow state not initialized.');
321
+ }
322
+
323
+ const root = await this.executeFlow(
324
+ this.compiled.flow,
325
+ state,
326
+ [],
327
+ from?.root,
328
+ this.createExecutorEnv(pass),
329
+ );
330
+
331
+ // Only the refusing step ran in this pass, and it did not complete, so
332
+ // the run is put back as the checkpoint it started from describes it.
333
+ if (pass.rejection && resumed) {
334
+ this.state = resumed.report.state;
335
+ this.snapshots = resumed.report.snapshots;
336
+ this.stepLog = resumed.report.stepLog;
337
+
338
+ return this.keepWaiting(resumed.checkpoint, pass.rejection);
339
+ }
340
+
341
+ if (root) {
342
+ const next = this.buildCheckpoint(state, root);
238
343
 
239
- if (suspension) {
240
- this.suspension = suspension;
344
+ this.checkpoint = next;
241
345
  this.status = EWorkflowRunStatus.SUSPENDED;
242
346
  this.emit('hook:workflow:suspended', {
243
347
  runId: this.runId,
244
- step: suspension.step,
245
- reason: suspension.reason,
246
- data: suspension.data,
348
+ waits: next.waits,
247
349
  });
248
350
 
249
351
  return {
250
352
  status: EWorkflowRunStatus.SUSPENDED,
251
- step: suspension.step,
252
- reason: suspension.reason,
253
- data: suspension.data,
254
- stepExecId: suspension.stepExecId,
255
- suspendIndex: suspension.suspendIndex,
256
- suspendKey: suspension.suspendKey,
257
- awaitResults: suspension.awaitResults,
353
+ waits: next.waits,
354
+ checkpoint: next,
258
355
  snapshot: this.getSnapshot(),
259
356
  };
260
357
  }
261
358
 
262
359
  const output = await this.evaluateWorkflowOutputs();
263
360
  this.status = EWorkflowRunStatus.FINISHED;
264
- this.suspension = undefined;
265
- this.currentStep = undefined;
361
+ this.checkpoint = undefined;
266
362
  this.emit('hook:workflow:finish', { runId: this.runId, output });
267
363
  if (!this.context) {
268
364
  throw new Error('Workflow context is not attached.');
@@ -276,7 +372,7 @@ export class WorkflowRunner {
276
372
  };
277
373
  } catch (error) {
278
374
  this.status = EWorkflowRunStatus.FAILED;
279
- this.currentStep = undefined;
375
+ this.checkpoint = undefined;
280
376
  this.emit('hook:workflow:failure', { runId: this.runId, error });
281
377
  this.context?.attachWorkflowRuntime(undefined);
282
378
 
@@ -289,67 +385,106 @@ export class WorkflowRunner {
289
385
  }
290
386
 
291
387
  /**
292
- * Rebuild a runner from persisted state, allowing hosts to resume after restarts.
388
+ * Leave the run suspended on `checkpoint` after a resume payload was
389
+ * refused.
390
+ *
391
+ * @param checkpoint The checkpoint the run was suspended on.
392
+ * @param rejection The refused wait and why.
393
+ * @returns The suspended result, carrying the rejection.
394
+ */
395
+ private keepWaiting(
396
+ checkpoint: WorkflowCheckpoint,
397
+ rejection: ResumeRejection,
398
+ ): SuspendedResult {
399
+ this.checkpoint = checkpoint;
400
+ this.status = EWorkflowRunStatus.SUSPENDED;
401
+
402
+ return {
403
+ status: EWorkflowRunStatus.SUSPENDED,
404
+ waits: checkpoint.waits,
405
+ checkpoint,
406
+ snapshot: this.getSnapshot(),
407
+ rejection,
408
+ };
409
+ }
410
+
411
+ /**
412
+ * Snapshot the suspended run as a detached JSON checkpoint.
413
+ *
414
+ * The checkpoint goes through the same JSON round trip a host applies when
415
+ * persisting it, so a resumed run sees the same values in process and
416
+ * after a restore.
417
+ *
418
+ * @param state Root execution state at suspension time.
419
+ * @param root Frame returned by the top-level flow.
420
+ * @returns The checkpoint to hand to the host.
421
+ * @throws When the run's state cannot be encoded as JSON.
422
+ */
423
+ private buildCheckpoint(
424
+ state: ExecutionState,
425
+ root: SequenceFrame,
426
+ ): WorkflowCheckpoint {
427
+ try {
428
+ return cloneAsJson({
429
+ version: CHECKPOINT_VERSION,
430
+ fingerprint: fingerprintWorkflow(this.compiled),
431
+ input: state.input,
432
+ output: state.output,
433
+ root,
434
+ waits: collectWaits(root),
435
+ });
436
+ } catch (error) {
437
+ const reason = error instanceof Error ? error.message : String(error);
438
+
439
+ throw new Error(
440
+ `Cannot checkpoint the suspended run: its state is not JSON-serializable (${reason}).`,
441
+ );
442
+ }
443
+ }
444
+
445
+ /**
446
+ * Restore a suspended run from its persisted checkpoint, typically in a
447
+ * different process than the one that suspended it.
293
448
  *
294
449
  * @param compiled The compiled workflow definition.
295
- * @param options Persisted state and metadata needed to rebuild the runner.
296
- * @returns A runner positioned to continue from the prior suspension or status.
450
+ * @param options.checkpoint Checkpoint returned when the run suspended.
451
+ * @param options.context Freshly hydrated workflow context.
452
+ * @param options.snapshot Persisted action snapshot, to keep reporting past steps.
453
+ * @param options.runId Run identifier propagated through events.
454
+ * @returns A suspended runner ready for {@link resume}.
455
+ * @throws {WorkflowResumeError} When the checkpoint cannot resume against `compiled`.
297
456
  */
298
- static async fromPersistedState(
457
+ static fromCheckpoint(
299
458
  compiled: CompiledWorkflow,
300
459
  options: {
301
- state: ExecutionState;
460
+ checkpoint: unknown;
302
461
  context: BaseWorkflowContext;
303
- snapshot: WorkflowSnapshot;
304
- suspension?: PersistedSuspension;
462
+ snapshot?: WorkflowSnapshot;
305
463
  runId?: string;
306
- lastResumeData?: unknown;
307
464
  },
308
- ): Promise<WorkflowRunner> {
465
+ ): WorkflowRunner {
466
+ const validation = validateCheckpoint(compiled, options.checkpoint);
467
+ if (!validation.ok) {
468
+ throw validation.error;
469
+ }
470
+
471
+ const checkpoint = validation.checkpoint;
309
472
  const runner = new WorkflowRunner(compiled, {
310
473
  runId: options.runId,
311
474
  });
312
475
 
476
+ runner.checkpoint = checkpoint;
313
477
  runner.state = {
314
- input: options.state.input ?? {},
315
- output: options.state.output ?? {},
316
- iteration: options.state.iteration,
317
- accumulator: options.state.accumulator,
318
- iterationStack: [...(options.state.iterationStack ?? [])],
478
+ input: checkpoint.input,
479
+ output: checkpoint.output,
480
+ iterationStack: [],
319
481
  };
320
482
  runner.context = options.context;
321
- runner.snapshots = options.snapshot.actions ?? {};
322
- runner.stepLog = {};
323
- runner.status = options.snapshot.status ?? EWorkflowRunStatus.IDLE;
324
- runner.lastResumeData = options.lastResumeData;
325
- runner.runtimeControl = new RunnerRuntimeControl(runner);
483
+ runner.snapshots = { ...(options.snapshot?.actions ?? {}) };
484
+ runner.status = EWorkflowRunStatus.SUSPENDED;
485
+ runner.runtimeControl = new RunnerRuntimeControl();
326
486
  options.context.attachWorkflowRuntime(runner.runtimeControl);
327
487
 
328
- if (options.suspension) {
329
- const suspension = rebuildSuspension(
330
- runner.createSuspensionRebuilderDeps(),
331
- {
332
- state: runner.state,
333
- stepId: options.suspension.stepId,
334
- reason: options.suspension.reason ?? undefined,
335
- data: options.suspension.data,
336
- stepExecId: options.suspension.stepExecId,
337
- suspendIndex: options.suspension.suspendIndex,
338
- suspendKey: options.suspension.suspendKey,
339
- awaitResults: options.suspension.awaitResults,
340
- },
341
- );
342
-
343
- if (!suspension) {
344
- throw new Error(
345
- `Unable to rebuild suspension for step ${options.suspension.stepId}`,
346
- );
347
- }
348
-
349
- runner.suspension = suspension;
350
- runner.status = EWorkflowRunStatus.SUSPENDED;
351
- }
352
-
353
488
  return runner;
354
489
  }
355
490
 
@@ -465,10 +600,13 @@ export class WorkflowRunner {
465
600
  /**
466
601
  * Construct the environment object passed to step executors.
467
602
  *
603
+ * @param pass The execution pass, shared by every scope it forks.
604
+ * @param overrides Scope-specific replacements, e.g. for a parallel branch.
468
605
  * @returns A step executor environment bound to this runner.
469
- * @throws When the workflow context is missing.
606
+ * @throws When the workflow context or runtime control is missing.
470
607
  */
471
608
  private createExecutorEnv(
609
+ pass: ExecutionPass,
472
610
  overrides: StepExecutorEnvForkOverrides = {},
473
611
  ): StepExecutorEnv {
474
612
  const context = overrides.context ?? this.context;
@@ -476,21 +614,22 @@ export class WorkflowRunner {
476
614
  throw new Error('Workflow context is not attached.');
477
615
  }
478
616
 
617
+ const runtime = overrides.runtime ?? this.runtimeControl;
618
+ if (!runtime) {
619
+ throw new Error('Workflow runtime control is not initialized.');
620
+ }
621
+
479
622
  const signal = overrides.signal ?? new AbortController().signal;
480
- const setCurrentStep =
481
- overrides.setCurrentStep ??
482
- ((step?: StepInfo) => {
483
- this.currentStep = step;
484
- });
485
- const captureTaskOutput =
486
- overrides.captureTaskOutput ??
487
- ((task: CompiledTask, state: ExecutionState, result: unknown) =>
488
- this.captureTaskOutput(task, state, result));
489
623
  const executorEnv: StepExecutorEnv = {
490
624
  compiled: this.compiled,
491
625
  context,
492
626
  signal,
493
627
  runId: this.runId,
628
+ runtime,
629
+ resolutions: pass.resolutions,
630
+ rejectResume: (rejection) => {
631
+ pass.rejection = rejection;
632
+ },
494
633
  buildInstanceStepInfo: (step, iterationStack) =>
495
634
  this.buildInstanceStepInfo(step, iterationStack),
496
635
  markSnapshot: (step, status, reason) =>
@@ -498,45 +637,17 @@ export class WorkflowRunner {
498
637
  recordStepExecution: (step, update) =>
499
638
  this.recordStepExecution(step, update),
500
639
  emit: (event, payload) => this.emit(event, payload),
501
- setCurrentStep,
502
- beginStepExecution: (stepId) => {
503
- if (!this.runtimeControl) {
504
- return `${stepId}#1`;
505
- }
506
-
507
- return this.runtimeControl.beginStepExecution(stepId);
508
- },
509
- waitForStepSuspension: (stepId) => {
510
- if (!this.runtimeControl) {
511
- throw new Error('Workflow runtime control is not initialized.');
512
- }
513
-
514
- return this.runtimeControl.waitForStepSuspension(stepId);
515
- },
516
- clearStepSuspensions: (stepId, error) => {
517
- this.runtimeControl?.clearStepSuspensions(stepId, error);
518
- },
519
- primeStepResumeData: (stepId, resumeData) => {
520
- this.runtimeControl?.primeStepResumeData(stepId, resumeData);
521
- },
522
- prepareStepReplay: (seed) => {
523
- this.runtimeControl?.prepareStepReplay(seed);
524
- },
525
- recordStepSuspendResult: (params) => {
526
- this.runtimeControl?.recordStepSuspendResult(params);
527
- },
528
- captureTaskOutput,
529
- executeFlow: (steps, state, path, startIndex) =>
530
- this.executeFlow(steps, state, path, startIndex, executorEnv),
531
- executeStep: (step, state, path) =>
532
- this.executeStep(step, state, path, executorEnv),
640
+ captureTaskOutput: (task, state, result) =>
641
+ this.captureTaskOutput(task, state, result),
642
+ executeFlow: (steps, state, path, frame) =>
643
+ this.executeFlow(steps, state, path, frame, executorEnv),
644
+ executeStep: (step, state, path, frame) =>
645
+ this.executeStep(step, state, path, frame, executorEnv),
533
646
  fork: (forkOverrides) =>
534
- this.createExecutorEnv({
647
+ this.createExecutorEnv(pass, {
535
648
  context: forkOverrides.context ?? context,
536
649
  signal: forkOverrides.signal ?? signal,
537
- setCurrentStep: forkOverrides.setCurrentStep ?? setCurrentStep,
538
- captureTaskOutput:
539
- forkOverrides.captureTaskOutput ?? captureTaskOutput,
650
+ runtime: forkOverrides.runtime ?? runtime,
540
651
  }),
541
652
  };
542
653
 
@@ -544,56 +655,45 @@ export class WorkflowRunner {
544
655
  }
545
656
 
546
657
  /**
547
- * Build dependencies used to reconstruct a suspension from persisted state.
548
- *
549
- * @returns Dependency bag for suspension rebuilders.
550
- */
551
- private createSuspensionRebuilderDeps(): SuspensionRebuilderDeps {
552
- return {
553
- compiled: this.compiled,
554
- context: this.context,
555
- runId: this.runId,
556
- createExecutorEnv: () => this.createExecutorEnv(),
557
- buildInstanceStepInfo: (step, iterationStack) =>
558
- this.buildInstanceStepInfo(step, iterationStack),
559
- captureTaskOutput: (task, state, result) =>
560
- this.captureTaskOutput(task, state, result),
561
- markSnapshot: (step, status, reason) =>
562
- this.markSnapshot(step, status, reason),
563
- emit: (event, payload) => this.emit(event, payload),
564
- executeFlow: (steps, state, path, startIndex) =>
565
- this.executeFlow(steps, state, path, startIndex),
566
- };
567
- }
568
-
569
- /**
570
- * Walk a list of compiled steps, threading state and returning a suspension when encountered.
658
+ * Walk a list of compiled steps, threading state and returning a frame when
659
+ * one of them suspends.
571
660
  *
572
661
  * @param steps The steps to execute sequentially.
573
662
  * @param state Mutable execution state shared across steps.
574
663
  * @param path Path tokens leading to the current step for tracing.
575
- * @param startIndex Index to resume from within the flow.
576
- * @returns A suspension if execution pauses, otherwise void.
664
+ * @param frame Frame of a previous suspension within these steps.
665
+ * @param env Executor environment of the current scope.
666
+ * @returns A frame if execution pauses, otherwise void.
577
667
  */
578
668
  private async executeFlow(
579
669
  steps: CompiledStep[],
580
670
  state: ExecutionState,
581
671
  path: Array<number | string>,
582
- startIndex = 0,
583
- env = this.createExecutorEnv(),
584
- ): Promise<Suspension | void> {
585
- // Walk the flow sequentially; if a step suspends, wrap its continuation so we resume at the same index.
586
- for (let index = startIndex; index < steps.length; index += 1) {
672
+ frame: SequenceFrame | undefined,
673
+ env: StepExecutorEnv,
674
+ ): Promise<SequenceFrame | void> {
675
+ if (frame) {
676
+ state.accumulator = frame.accumulator;
677
+ }
678
+
679
+ for (let index = frame?.index ?? 0; index < steps.length; index += 1) {
587
680
  throwIfAborted(env.signal);
588
681
 
589
- const step = steps[index];
590
- const stepPath = [...path, index];
591
- const suspension = await this.executeStep(step, state, stepPath, env);
682
+ const child = await this.executeStep(
683
+ steps[index],
684
+ state,
685
+ [...path, index],
686
+ frame && index === frame.index ? frame.child : undefined,
687
+ env,
688
+ );
592
689
 
593
- if (suspension) {
594
- return wrapSuspensionContinuation(suspension, () =>
595
- this.executeFlow(steps, state, path, index + 1, env),
596
- );
690
+ if (child) {
691
+ return {
692
+ kind: 'sequence',
693
+ index,
694
+ accumulator: state.accumulator,
695
+ child,
696
+ };
597
697
  }
598
698
  }
599
699
 
@@ -606,25 +706,41 @@ export class WorkflowRunner {
606
706
  * @param step The step to run.
607
707
  * @param state The shared execution state.
608
708
  * @param path Tokens describing the location of the step in the workflow.
609
- * @returns A suspension if the step pauses execution, otherwise void.
709
+ * @param frame Frame of a previous suspension of this step.
710
+ * @param env Executor environment of the current scope.
711
+ * @returns A frame if the step pauses execution, otherwise void.
610
712
  */
611
713
  private async executeStep(
612
714
  step: CompiledStep,
613
715
  state: ExecutionState,
614
716
  path: Array<number | string>,
615
- env = this.createExecutorEnv(),
616
- ): Promise<Suspension | void> {
717
+ frame: StepFrame | undefined,
718
+ env: StepExecutorEnv,
719
+ ): Promise<StepFrame | void> {
617
720
  throwIfAborted(env.signal);
721
+ assertFrameMatchesStep(frame, step, path);
618
722
 
619
723
  switch (step.type) {
620
724
  case StepType.Task:
621
- return runTaskExecutor(env, step, state, path);
725
+ return runTaskExecutor(env, step, state, path, frame as TaskFrame);
622
726
  case StepType.Parallel:
623
- return runParallelExecutor(env, step, state, path);
727
+ return runParallelExecutor(
728
+ env,
729
+ step,
730
+ state,
731
+ path,
732
+ frame as ParallelFrame,
733
+ );
624
734
  case StepType.Conditional:
625
- return runConditionalExecutor(env, step, state, path);
735
+ return runConditionalExecutor(
736
+ env,
737
+ step,
738
+ state,
739
+ path,
740
+ frame as ConditionalFrame,
741
+ );
626
742
  case StepType.Loop:
627
- return runLoopExecutor(env, step, state, path);
743
+ return runLoopExecutor(env, step, state, path, frame as LoopFrame);
628
744
  }
629
745
  }
630
746