@hexabot-ai/agentic 3.4.0 → 3.5.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
@@ -6,16 +6,18 @@
6
6
  */
7
7
  Object.defineProperty(exports, "__esModule", { value: true });
8
8
  exports.WorkflowRunner = void 0;
9
+ const checkpoint_1 = require("./checkpoint");
9
10
  const context_1 = require("./context");
10
11
  const errors_1 = require("./errors");
12
+ const resume_payload_1 = require("./resume-payload");
11
13
  const runner_runtime_control_1 = require("./runner-runtime-control");
12
14
  const conditional_executor_1 = require("./step-executors/conditional-executor");
13
15
  const loop_executor_1 = require("./step-executors/loop-executor");
14
16
  const parallel_executor_1 = require("./step-executors/parallel-executor");
15
- const suspension_continuation_1 = require("./step-executors/suspension-continuation");
16
17
  const task_executor_1 = require("./step-executors/task-executor");
17
- const suspension_rebuilder_1 = require("./suspension-rebuilder");
18
+ const clone_1 = require("./utils/clone");
18
19
  const workflow_event_emitter_1 = require("./workflow-event-emitter");
20
+ const workflow_fingerprint_1 = require("./workflow-fingerprint");
19
21
  const workflow_values_1 = require("./workflow-values");
20
22
  /**
21
23
  * Executes a compiled workflow definition, tracking state, suspensions, and event hooks.
@@ -81,20 +83,13 @@ class WorkflowRunner {
81
83
  ]));
82
84
  }
83
85
  /**
84
- * Read the step currently being executed.
86
+ * Read the checkpoint of a suspended run: everything a host must persist to
87
+ * resume it later, in this process or another one. Treat it as read-only.
85
88
  *
86
- * @returns Metadata for the in-flight step, if any.
89
+ * @returns The checkpoint while the run is suspended, otherwise undefined.
87
90
  */
88
- getCurrentStep() {
89
- return this.currentStep;
90
- }
91
- /**
92
- * Access the last payload supplied to a resume call.
93
- *
94
- * @returns The most recent resume data, or undefined if none.
95
- */
96
- getLastResumeData() {
97
- return this.lastResumeData;
91
+ getCheckpoint() {
92
+ return this.checkpoint;
98
93
  }
99
94
  /**
100
95
  * Begin executing the workflow from the first step.
@@ -107,77 +102,139 @@ class WorkflowRunner {
107
102
  this.status = context_1.EWorkflowRunStatus.RUNNING;
108
103
  this.snapshots = {};
109
104
  this.stepLog = {};
110
- this.suspension = undefined;
111
- this.lastResumeData = undefined;
112
- this.currentStep = undefined;
105
+ this.checkpoint = undefined;
113
106
  this.context = args.context;
114
107
  this.state = {
115
108
  input: this.compiled.inputParser.parse(args.inputData ?? {}),
116
109
  output: {},
117
110
  iterationStack: [],
118
111
  };
119
- this.runtimeControl = new runner_runtime_control_1.RunnerRuntimeControl(this);
112
+ this.runtimeControl = new runner_runtime_control_1.RunnerRuntimeControl();
120
113
  this.context.attachWorkflowRuntime(this.runtimeControl);
121
114
  this.emit('hook:workflow:start', { runId: this.runId });
122
- const state = this.state;
123
- if (!state) {
124
- throw new Error('Workflow state not initialized.');
125
- }
126
- const env = this.createExecutorEnv();
127
- return this.runExecution(() => this.executeFlow(this.compiled.flow, state, [], 0, env));
115
+ return this.runExecution(new Map());
128
116
  }
129
117
  /**
130
- * Resume a previously suspended workflow using the supplied resume data.
118
+ * Resume a suspended workflow by satisfying one of its open waits.
119
+ *
120
+ * Execution re-enters the checkpoint's frames: completed work is skipped,
121
+ * the resolved step re-runs its action body, and waits left untouched stay
122
+ * parked.
131
123
  *
132
- * @param args Data provided to resume the suspended step.
124
+ * A payload the wait does not accept is refused, first against the wait's
125
+ * `accepts` JSON Schema without running anything, then by the action body.
126
+ * Either way the result is suspended on the same waits and carries
127
+ * `rejection`, and the checkpoint, snapshot and step log are left as they
128
+ * were. Events a refusing body emitted are not withdrawn, and its side
129
+ * effects, including writes to context state, are not undone.
130
+ *
131
+ * @param args Resume payload and, when several waits are open, the wait it satisfies.
133
132
  * @returns Execution result including status and snapshot.
133
+ * @throws {WorkflowWaitNotFoundError} When `waitId` is not an open wait.
134
+ * @throws {WorkflowWaitAmbiguousError} When several waits are open and no
135
+ * `waitId` is given.
134
136
  */
135
137
  async resume(args) {
136
- if (this.status !== context_1.EWorkflowRunStatus.SUSPENDED || !this.suspension) {
138
+ if (this.status !== context_1.EWorkflowRunStatus.SUSPENDED || !this.checkpoint) {
137
139
  throw new Error('Cannot resume a workflow that is not suspended.');
138
140
  }
139
- if (!this.context || !this.state) {
141
+ if (!this.context) {
140
142
  throw new Error('Workflow state is not initialized.');
141
143
  }
144
+ const wait = (0, checkpoint_1.selectWait)(this.checkpoint.waits, args.waitId);
145
+ const payload = (0, resume_payload_1.checkResumePayload)(wait, args.resumeData);
146
+ const result = payload.ok
147
+ ? await this.resolveWait(wait, payload.value)
148
+ : this.keepWaiting(this.checkpoint, {
149
+ waitId: wait.waitId,
150
+ error: payload.error,
151
+ });
152
+ if (result.status === context_1.EWorkflowRunStatus.SUSPENDED && result.rejection) {
153
+ this.emit('hook:workflow:resume_rejected', {
154
+ runId: this.runId,
155
+ wait,
156
+ resumeData: args.resumeData,
157
+ error: result.rejection.error,
158
+ });
159
+ }
160
+ return result;
161
+ }
162
+ /**
163
+ * Run the pass that resolves one wait with an accepted payload.
164
+ *
165
+ * @param wait The wait being resolved.
166
+ * @param recorded The payload as the checkpoint records it.
167
+ * @returns Execution result including status and snapshot.
168
+ */
169
+ async resolveWait(wait, recorded) {
170
+ const checkpoint = this.checkpoint;
171
+ if (!checkpoint) {
172
+ throw new Error('Cannot resume a workflow that is not suspended.');
173
+ }
174
+ const report = {
175
+ state: this.state,
176
+ snapshots: { ...this.snapshots },
177
+ stepLog: { ...this.stepLog },
178
+ };
142
179
  this.status = context_1.EWorkflowRunStatus.RUNNING;
143
- this.lastResumeData = args.resumeData;
144
- const suspension = this.suspension;
145
- return this.runExecution(() => suspension.continue(args.resumeData));
180
+ this.context?.attachWorkflowRuntime(this.runtimeControl);
181
+ return this.runExecution(new Map([[wait.waitId, recorded]]), {
182
+ checkpoint,
183
+ report,
184
+ });
146
185
  }
147
186
  /**
148
- * Execute the provided workflow operation and normalize suspension, finish, and failure handling.
187
+ * Run the flow from the top, or from a checkpoint, and normalize
188
+ * suspension, finish, and failure handling.
149
189
  *
150
- * @param execute Function that advances workflow execution and may return a suspension.
190
+ * @param resolutions Resume payloads for the waits this pass satisfies.
191
+ * @param resumed Suspended run to resume from; omitted on start.
151
192
  * @returns Result of the execution attempt.
152
193
  */
153
- async runExecution(execute) {
194
+ async runExecution(resolutions, resumed) {
195
+ const pass = { resolutions };
154
196
  try {
155
- const suspension = await execute();
156
- if (suspension) {
157
- this.suspension = suspension;
197
+ // In-process and durable resumes start from the same detached JSON
198
+ // copy, so both see exactly what a host would have persisted.
199
+ const from = resumed ? (0, clone_1.cloneAsJson)(resumed.checkpoint) : undefined;
200
+ if (from) {
201
+ this.state = {
202
+ input: from.input,
203
+ output: from.output,
204
+ iterationStack: [],
205
+ };
206
+ }
207
+ const state = this.state;
208
+ if (!state) {
209
+ throw new Error('Workflow state not initialized.');
210
+ }
211
+ const root = await this.executeFlow(this.compiled.flow, state, [], from?.root, this.createExecutorEnv(pass));
212
+ // Only the refusing step ran in this pass, and it did not complete, so
213
+ // the run is put back as the checkpoint it started from describes it.
214
+ if (pass.rejection && resumed) {
215
+ this.state = resumed.report.state;
216
+ this.snapshots = resumed.report.snapshots;
217
+ this.stepLog = resumed.report.stepLog;
218
+ return this.keepWaiting(resumed.checkpoint, pass.rejection);
219
+ }
220
+ if (root) {
221
+ const next = this.buildCheckpoint(state, root);
222
+ this.checkpoint = next;
158
223
  this.status = context_1.EWorkflowRunStatus.SUSPENDED;
159
224
  this.emit('hook:workflow:suspended', {
160
225
  runId: this.runId,
161
- step: suspension.step,
162
- reason: suspension.reason,
163
- data: suspension.data,
226
+ waits: next.waits,
164
227
  });
165
228
  return {
166
229
  status: context_1.EWorkflowRunStatus.SUSPENDED,
167
- step: suspension.step,
168
- reason: suspension.reason,
169
- data: suspension.data,
170
- stepExecId: suspension.stepExecId,
171
- suspendIndex: suspension.suspendIndex,
172
- suspendKey: suspension.suspendKey,
173
- awaitResults: suspension.awaitResults,
230
+ waits: next.waits,
231
+ checkpoint: next,
174
232
  snapshot: this.getSnapshot(),
175
233
  };
176
234
  }
177
235
  const output = await this.evaluateWorkflowOutputs();
178
236
  this.status = context_1.EWorkflowRunStatus.FINISHED;
179
- this.suspension = undefined;
180
- this.currentStep = undefined;
237
+ this.checkpoint = undefined;
181
238
  this.emit('hook:workflow:finish', { runId: this.runId, output });
182
239
  if (!this.context) {
183
240
  throw new Error('Workflow context is not attached.');
@@ -191,7 +248,7 @@ class WorkflowRunner {
191
248
  }
192
249
  catch (error) {
193
250
  this.status = context_1.EWorkflowRunStatus.FAILED;
194
- this.currentStep = undefined;
251
+ this.checkpoint = undefined;
195
252
  this.emit('hook:workflow:failure', { runId: this.runId, error });
196
253
  this.context?.attachWorkflowRuntime(undefined);
197
254
  return {
@@ -202,47 +259,84 @@ class WorkflowRunner {
202
259
  }
203
260
  }
204
261
  /**
205
- * Rebuild a runner from persisted state, allowing hosts to resume after restarts.
262
+ * Leave the run suspended on `checkpoint` after a resume payload was
263
+ * refused.
264
+ *
265
+ * @param checkpoint The checkpoint the run was suspended on.
266
+ * @param rejection The refused wait and why.
267
+ * @returns The suspended result, carrying the rejection.
268
+ */
269
+ keepWaiting(checkpoint, rejection) {
270
+ this.checkpoint = checkpoint;
271
+ this.status = context_1.EWorkflowRunStatus.SUSPENDED;
272
+ return {
273
+ status: context_1.EWorkflowRunStatus.SUSPENDED,
274
+ waits: checkpoint.waits,
275
+ checkpoint,
276
+ snapshot: this.getSnapshot(),
277
+ rejection,
278
+ };
279
+ }
280
+ /**
281
+ * Snapshot the suspended run as a detached JSON checkpoint.
282
+ *
283
+ * The checkpoint goes through the same JSON round trip a host applies when
284
+ * persisting it, so a resumed run sees the same values in process and
285
+ * after a restore.
286
+ *
287
+ * @param state Root execution state at suspension time.
288
+ * @param root Frame returned by the top-level flow.
289
+ * @returns The checkpoint to hand to the host.
290
+ * @throws When the run's state cannot be encoded as JSON.
291
+ */
292
+ buildCheckpoint(state, root) {
293
+ try {
294
+ return (0, clone_1.cloneAsJson)({
295
+ version: checkpoint_1.CHECKPOINT_VERSION,
296
+ fingerprint: (0, workflow_fingerprint_1.fingerprintWorkflow)(this.compiled),
297
+ input: state.input,
298
+ output: state.output,
299
+ root,
300
+ waits: (0, checkpoint_1.collectWaits)(root),
301
+ });
302
+ }
303
+ catch (error) {
304
+ const reason = error instanceof Error ? error.message : String(error);
305
+ throw new Error(`Cannot checkpoint the suspended run: its state is not JSON-serializable (${reason}).`);
306
+ }
307
+ }
308
+ /**
309
+ * Restore a suspended run from its persisted checkpoint, typically in a
310
+ * different process than the one that suspended it.
206
311
  *
207
312
  * @param compiled The compiled workflow definition.
208
- * @param options Persisted state and metadata needed to rebuild the runner.
209
- * @returns A runner positioned to continue from the prior suspension or status.
313
+ * @param options.checkpoint Checkpoint returned when the run suspended.
314
+ * @param options.context Freshly hydrated workflow context.
315
+ * @param options.snapshot Persisted action snapshot, to keep reporting past steps.
316
+ * @param options.runId Run identifier propagated through events.
317
+ * @returns A suspended runner ready for {@link resume}.
318
+ * @throws {WorkflowResumeError} When the checkpoint cannot resume against `compiled`.
210
319
  */
211
- static async fromPersistedState(compiled, options) {
320
+ static fromCheckpoint(compiled, options) {
321
+ const validation = (0, checkpoint_1.validateCheckpoint)(compiled, options.checkpoint);
322
+ if (!validation.ok) {
323
+ throw validation.error;
324
+ }
325
+ const checkpoint = validation.checkpoint;
212
326
  const runner = new WorkflowRunner(compiled, {
213
327
  runId: options.runId,
214
328
  });
329
+ runner.checkpoint = checkpoint;
215
330
  runner.state = {
216
- input: options.state.input ?? {},
217
- output: options.state.output ?? {},
218
- iteration: options.state.iteration,
219
- accumulator: options.state.accumulator,
220
- iterationStack: [...(options.state.iterationStack ?? [])],
331
+ input: checkpoint.input,
332
+ output: checkpoint.output,
333
+ iterationStack: [],
221
334
  };
222
335
  runner.context = options.context;
223
- runner.snapshots = options.snapshot.actions ?? {};
224
- runner.stepLog = {};
225
- runner.status = options.snapshot.status ?? context_1.EWorkflowRunStatus.IDLE;
226
- runner.lastResumeData = options.lastResumeData;
227
- runner.runtimeControl = new runner_runtime_control_1.RunnerRuntimeControl(runner);
336
+ runner.snapshots = { ...(options.snapshot?.actions ?? {}) };
337
+ runner.status = context_1.EWorkflowRunStatus.SUSPENDED;
338
+ runner.runtimeControl = new runner_runtime_control_1.RunnerRuntimeControl();
228
339
  options.context.attachWorkflowRuntime(runner.runtimeControl);
229
- if (options.suspension) {
230
- const suspension = (0, suspension_rebuilder_1.rebuildSuspension)(runner.createSuspensionRebuilderDeps(), {
231
- state: runner.state,
232
- stepId: options.suspension.stepId,
233
- reason: options.suspension.reason ?? undefined,
234
- data: options.suspension.data,
235
- stepExecId: options.suspension.stepExecId,
236
- suspendIndex: options.suspension.suspendIndex,
237
- suspendKey: options.suspension.suspendKey,
238
- awaitResults: options.suspension.awaitResults,
239
- });
240
- if (!suspension) {
241
- throw new Error(`Unable to rebuild suspension for step ${options.suspension.stepId}`);
242
- }
243
- runner.suspension = suspension;
244
- runner.status = context_1.EWorkflowRunStatus.SUSPENDED;
245
- }
246
340
  return runner;
247
341
  }
248
342
  /**
@@ -336,103 +430,71 @@ class WorkflowRunner {
336
430
  /**
337
431
  * Construct the environment object passed to step executors.
338
432
  *
433
+ * @param pass The execution pass, shared by every scope it forks.
434
+ * @param overrides Scope-specific replacements, e.g. for a parallel branch.
339
435
  * @returns A step executor environment bound to this runner.
340
- * @throws When the workflow context is missing.
436
+ * @throws When the workflow context or runtime control is missing.
341
437
  */
342
- createExecutorEnv(overrides = {}) {
438
+ createExecutorEnv(pass, overrides = {}) {
343
439
  const context = overrides.context ?? this.context;
344
440
  if (!context) {
345
441
  throw new Error('Workflow context is not attached.');
346
442
  }
443
+ const runtime = overrides.runtime ?? this.runtimeControl;
444
+ if (!runtime) {
445
+ throw new Error('Workflow runtime control is not initialized.');
446
+ }
347
447
  const signal = overrides.signal ?? new AbortController().signal;
348
- const setCurrentStep = overrides.setCurrentStep ??
349
- ((step) => {
350
- this.currentStep = step;
351
- });
352
- const captureTaskOutput = overrides.captureTaskOutput ??
353
- ((task, state, result) => this.captureTaskOutput(task, state, result));
354
448
  const executorEnv = {
355
449
  compiled: this.compiled,
356
450
  context,
357
451
  signal,
358
452
  runId: this.runId,
453
+ runtime,
454
+ resolutions: pass.resolutions,
455
+ rejectResume: (rejection) => {
456
+ pass.rejection = rejection;
457
+ },
359
458
  buildInstanceStepInfo: (step, iterationStack) => this.buildInstanceStepInfo(step, iterationStack),
360
459
  markSnapshot: (step, status, reason) => this.markSnapshot(step, status, reason),
361
460
  recordStepExecution: (step, update) => this.recordStepExecution(step, update),
362
461
  emit: (event, payload) => this.emit(event, payload),
363
- setCurrentStep,
364
- beginStepExecution: (stepId) => {
365
- if (!this.runtimeControl) {
366
- return `${stepId}#1`;
367
- }
368
- return this.runtimeControl.beginStepExecution(stepId);
369
- },
370
- waitForStepSuspension: (stepId) => {
371
- if (!this.runtimeControl) {
372
- throw new Error('Workflow runtime control is not initialized.');
373
- }
374
- return this.runtimeControl.waitForStepSuspension(stepId);
375
- },
376
- clearStepSuspensions: (stepId, error) => {
377
- this.runtimeControl?.clearStepSuspensions(stepId, error);
378
- },
379
- primeStepResumeData: (stepId, resumeData) => {
380
- this.runtimeControl?.primeStepResumeData(stepId, resumeData);
381
- },
382
- prepareStepReplay: (seed) => {
383
- this.runtimeControl?.prepareStepReplay(seed);
384
- },
385
- recordStepSuspendResult: (params) => {
386
- this.runtimeControl?.recordStepSuspendResult(params);
387
- },
388
- captureTaskOutput,
389
- executeFlow: (steps, state, path, startIndex) => this.executeFlow(steps, state, path, startIndex, executorEnv),
390
- executeStep: (step, state, path) => this.executeStep(step, state, path, executorEnv),
391
- fork: (forkOverrides) => this.createExecutorEnv({
462
+ captureTaskOutput: (task, state, result) => this.captureTaskOutput(task, state, result),
463
+ executeFlow: (steps, state, path, frame) => this.executeFlow(steps, state, path, frame, executorEnv),
464
+ executeStep: (step, state, path, frame) => this.executeStep(step, state, path, frame, executorEnv),
465
+ fork: (forkOverrides) => this.createExecutorEnv(pass, {
392
466
  context: forkOverrides.context ?? context,
393
467
  signal: forkOverrides.signal ?? signal,
394
- setCurrentStep: forkOverrides.setCurrentStep ?? setCurrentStep,
395
- captureTaskOutput: forkOverrides.captureTaskOutput ?? captureTaskOutput,
468
+ runtime: forkOverrides.runtime ?? runtime,
396
469
  }),
397
470
  };
398
471
  return executorEnv;
399
472
  }
400
473
  /**
401
- * Build dependencies used to reconstruct a suspension from persisted state.
402
- *
403
- * @returns Dependency bag for suspension rebuilders.
404
- */
405
- createSuspensionRebuilderDeps() {
406
- return {
407
- compiled: this.compiled,
408
- context: this.context,
409
- runId: this.runId,
410
- createExecutorEnv: () => this.createExecutorEnv(),
411
- buildInstanceStepInfo: (step, iterationStack) => this.buildInstanceStepInfo(step, iterationStack),
412
- captureTaskOutput: (task, state, result) => this.captureTaskOutput(task, state, result),
413
- markSnapshot: (step, status, reason) => this.markSnapshot(step, status, reason),
414
- emit: (event, payload) => this.emit(event, payload),
415
- executeFlow: (steps, state, path, startIndex) => this.executeFlow(steps, state, path, startIndex),
416
- };
417
- }
418
- /**
419
- * Walk a list of compiled steps, threading state and returning a suspension when encountered.
474
+ * Walk a list of compiled steps, threading state and returning a frame when
475
+ * one of them suspends.
420
476
  *
421
477
  * @param steps The steps to execute sequentially.
422
478
  * @param state Mutable execution state shared across steps.
423
479
  * @param path Path tokens leading to the current step for tracing.
424
- * @param startIndex Index to resume from within the flow.
425
- * @returns A suspension if execution pauses, otherwise void.
480
+ * @param frame Frame of a previous suspension within these steps.
481
+ * @param env Executor environment of the current scope.
482
+ * @returns A frame if execution pauses, otherwise void.
426
483
  */
427
- async executeFlow(steps, state, path, startIndex = 0, env = this.createExecutorEnv()) {
428
- // Walk the flow sequentially; if a step suspends, wrap its continuation so we resume at the same index.
429
- for (let index = startIndex; index < steps.length; index += 1) {
484
+ async executeFlow(steps, state, path, frame, env) {
485
+ if (frame) {
486
+ state.accumulator = frame.accumulator;
487
+ }
488
+ for (let index = frame?.index ?? 0; index < steps.length; index += 1) {
430
489
  (0, errors_1.throwIfAborted)(env.signal);
431
- const step = steps[index];
432
- const stepPath = [...path, index];
433
- const suspension = await this.executeStep(step, state, stepPath, env);
434
- if (suspension) {
435
- return (0, suspension_continuation_1.wrapSuspensionContinuation)(suspension, () => this.executeFlow(steps, state, path, index + 1, env));
490
+ const child = await this.executeStep(steps[index], state, [...path, index], frame && index === frame.index ? frame.child : undefined, env);
491
+ if (child) {
492
+ return {
493
+ kind: 'sequence',
494
+ index,
495
+ accumulator: state.accumulator,
496
+ child,
497
+ };
436
498
  }
437
499
  }
438
500
  return undefined;
@@ -443,19 +505,22 @@ class WorkflowRunner {
443
505
  * @param step The step to run.
444
506
  * @param state The shared execution state.
445
507
  * @param path Tokens describing the location of the step in the workflow.
446
- * @returns A suspension if the step pauses execution, otherwise void.
508
+ * @param frame Frame of a previous suspension of this step.
509
+ * @param env Executor environment of the current scope.
510
+ * @returns A frame if the step pauses execution, otherwise void.
447
511
  */
448
- async executeStep(step, state, path, env = this.createExecutorEnv()) {
512
+ async executeStep(step, state, path, frame, env) {
449
513
  (0, errors_1.throwIfAborted)(env.signal);
514
+ (0, checkpoint_1.assertFrameMatchesStep)(frame, step, path);
450
515
  switch (step.type) {
451
516
  case workflow_event_emitter_1.StepType.Task:
452
- return (0, task_executor_1.executeTaskStep)(env, step, state, path);
517
+ return (0, task_executor_1.executeTaskStep)(env, step, state, path, frame);
453
518
  case workflow_event_emitter_1.StepType.Parallel:
454
- return (0, parallel_executor_1.executeParallel)(env, step, state, path);
519
+ return (0, parallel_executor_1.executeParallel)(env, step, state, path, frame);
455
520
  case workflow_event_emitter_1.StepType.Conditional:
456
- return (0, conditional_executor_1.executeConditional)(env, step, state, path);
521
+ return (0, conditional_executor_1.executeConditional)(env, step, state, path, frame);
457
522
  case workflow_event_emitter_1.StepType.Loop:
458
- return (0, loop_executor_1.executeLoop)(env, step, state, path);
523
+ return (0, loop_executor_1.executeLoop)(env, step, state, path, frame);
459
524
  }
460
525
  }
461
526
  /**
@@ -7,6 +7,7 @@
7
7
  Object.defineProperty(exports, "__esModule", { value: true });
8
8
  exports.Workflow = exports.WorkflowRunner = exports.WorkflowEventEmitter = exports.compileWorkflow = void 0;
9
9
  const yaml_1 = require("yaml");
10
+ const checkpoint_1 = require("./checkpoint");
10
11
  const context_1 = require("./context");
11
12
  const dsl_types_1 = require("./dsl.types");
12
13
  const workflow_definition_1 = require("./utils/workflow-definition");
@@ -20,12 +21,11 @@ Object.defineProperty(exports, "WorkflowEventEmitter", { enumerable: true, get:
20
21
  var workflow_runner_2 = require("./workflow-runner");
21
22
  Object.defineProperty(exports, "WorkflowRunner", { enumerable: true, get: function () { return workflow_runner_2.WorkflowRunner; } });
22
23
  class WorkflowRunSuspendedError extends Error {
23
- constructor(stepId, options) {
24
- super(`Workflow run suspended at step ${stepId}${options?.reason ? `: ${options.reason}` : ''}`);
24
+ constructor(waits) {
25
+ const steps = waits.map(({ step, reason }) => reason ? `${step.id} (${reason})` : step.id);
26
+ super(`Workflow run suspended at ${steps.join(', ')}`);
25
27
  this.name = 'WorkflowRunSuspendedError';
26
- this.stepId = stepId;
27
- this.reason = options?.reason;
28
- this.data = options?.data;
28
+ this.waits = waits;
29
29
  }
30
30
  }
31
31
  const getTaskNameFromStep = (step) => {
@@ -224,10 +224,7 @@ class Workflow {
224
224
  : new Error(String(result.error));
225
225
  }
226
226
  context.attachWorkflowRuntime(undefined);
227
- throw new WorkflowRunSuspendedError(result.step.id, {
228
- reason: result.reason,
229
- data: result.data,
230
- });
227
+ throw new WorkflowRunSuspendedError(result.waits);
231
228
  }
232
229
  /**
233
230
  * Construct a runner without executing, allowing hosts to manage start/resume manually.
@@ -236,10 +233,25 @@ class Workflow {
236
233
  return new workflow_runner_1.WorkflowRunner(this.compiled, options);
237
234
  }
238
235
  /**
239
- * Rebuild a runner from persisted state and snapshot, useful after restarts.
236
+ * Decide whether a persisted checkpoint can resume against this workflow,
237
+ * without running anything. Call it before claiming a wait.
238
+ *
239
+ * @param checkpoint The checkpoint, as persisted.
240
+ * @param options.waitId Wait the caller is about to resume.
241
+ * @param options.resumeData Payload the caller is about to resume with,
242
+ * checked against what the wait accepts when the key is present.
243
+ * @returns The parsed checkpoint, or the typed reason it cannot resume.
244
+ */
245
+ validateCheckpoint(checkpoint, options) {
246
+ return (0, checkpoint_1.validateCheckpoint)(this.compiled, checkpoint, options);
247
+ }
248
+ /**
249
+ * Restore a suspended runner from its persisted checkpoint, useful after restarts.
250
+ *
251
+ * @throws {WorkflowResumeError} When the checkpoint cannot resume against this workflow.
240
252
  */
241
- async buildRunnerFromState(options) {
242
- return workflow_runner_1.WorkflowRunner.fromPersistedState(this.compiled, options);
253
+ buildRunnerFromCheckpoint(options) {
254
+ return workflow_runner_1.WorkflowRunner.fromCheckpoint(this.compiled, options);
243
255
  }
244
256
  }
245
257
  exports.Workflow = Workflow;
@@ -5,7 +5,7 @@
5
5
  */
6
6
  import { z } from 'zod';
7
7
  import { BaseSettingsSchema } from '../dsl.types';
8
- import { throwIfAborted } from '../errors';
8
+ import { isNonDeterministicWorkflowError, isWorkflowResumeRejectedError, throwIfAborted, } from '../errors';
9
9
  import { assertSnakeCaseName } from '../utils/naming';
10
10
  import { sleep, withTimeout } from '../utils/timeout';
11
11
  const BASE_SETTINGS_KEYS = Object.keys(BaseSettingsSchema.shape);
@@ -86,10 +86,18 @@ export class AbstractAction {
86
86
  const maxDelayMs = retrySettings.max_delay_ms;
87
87
  const jitter = retrySettings.jitter;
88
88
  const multiplier = retrySettings.multiplier;
89
+ // Suspend keys are positional within the body, so every attempt has to
90
+ // start from where this run did: otherwise a retry asks for `index:2`
91
+ // where the first attempt resolved `index:1`, and the step suspends on a
92
+ // wait whose payload was already delivered.
93
+ const rewindSuspendCursor = context
94
+ ?.getWorkflowRuntime?.()
95
+ ?.markSuspendCursor?.();
89
96
  while (attempt < maxAttempts) {
90
97
  if (signal) {
91
98
  throwIfAborted(signal);
92
99
  }
100
+ rewindSuspendCursor?.();
93
101
  try {
94
102
  const result = await withTimeout(this.execute({
95
103
  input,
@@ -102,7 +110,11 @@ export class AbstractAction {
102
110
  }
103
111
  catch (error) {
104
112
  attempt += 1;
105
- if (attempt >= maxAttempts) {
113
+ // A retry would read the same refused resume payload again, or replay
114
+ // the same body into the same mismatch with what it recorded.
115
+ if (attempt >= maxAttempts ||
116
+ isWorkflowResumeRejectedError(error) ||
117
+ isNonDeterministicWorkflowError(error)) {
106
118
  throw error;
107
119
  }
108
120
  let delay = currentDelay;