@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
@@ -0,0 +1,2568 @@
1
+ /*
2
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
3
+ * Copyright (c) 2025 Hexastack.
4
+ * Full terms: see LICENSE.md.
5
+ */
6
+
7
+ import { z } from 'zod';
8
+
9
+ import { defineAction } from '../action/action';
10
+ import type { Action } from '../action/action.types';
11
+ import {
12
+ validateCheckpoint,
13
+ type WaitInfo,
14
+ type WorkflowCheckpoint,
15
+ } from '../checkpoint';
16
+ import { BaseWorkflowContext } from '../context';
17
+ import type { Settings, WorkflowDefinition } from '../dsl.types';
18
+ import {
19
+ NonDeterministicWorkflowError,
20
+ WorkflowCheckpointInvalidError,
21
+ WorkflowDefinitionDriftError,
22
+ WorkflowResumeError,
23
+ WorkflowResumeRejectedError,
24
+ WorkflowWaitAmbiguousError,
25
+ WorkflowWaitNotFoundError,
26
+ } from '../errors';
27
+ import { compileWorkflow } from '../workflow-compiler';
28
+ import {
29
+ WorkflowEventEmitter,
30
+ type WorkflowEventEmitterLike,
31
+ } from '../workflow-event-emitter';
32
+ import { WorkflowRunner } from '../workflow-runner';
33
+ import type { WorkflowRunResult } from '../workflow-types';
34
+
35
+ import { createTaskDefs } from './test-helpers';
36
+
37
+ class TestContext extends BaseWorkflowContext<
38
+ Record<string, unknown>,
39
+ WorkflowEventEmitter
40
+ > {
41
+ public eventEmitter: WorkflowEventEmitterLike<WorkflowEventEmitter> =
42
+ new WorkflowEventEmitter();
43
+ }
44
+
45
+ /** Number of times each action body started, across every attempt. */
46
+ let bodyRuns: Record<string, number> = {};
47
+ const countRun = (name: string) => {
48
+ bodyRuns[name] = (bodyRuns[name] ?? 0) + 1;
49
+ };
50
+ const labelSchema = z.object({ label: z.string() });
51
+ const replySchema = z.object({ reply: z.string() });
52
+ const record = defineAction<
53
+ { label: string },
54
+ { label: string },
55
+ TestContext,
56
+ Settings
57
+ >({
58
+ name: 'record',
59
+ inputSchema: labelSchema,
60
+ outputSchema: labelSchema,
61
+ execute: async ({ input }) => {
62
+ countRun('record');
63
+
64
+ return { label: input.label };
65
+ },
66
+ });
67
+ const ask = defineAction<
68
+ { label: string },
69
+ { label: string; reply: string },
70
+ TestContext,
71
+ Settings
72
+ >({
73
+ name: 'ask',
74
+ inputSchema: labelSchema,
75
+ outputSchema: z.object({ label: z.string(), reply: z.string() }),
76
+ execute: async ({ input, context }) => {
77
+ countRun('ask');
78
+ const { reply } = replySchema.parse(
79
+ await context.workflow.suspend({
80
+ reason: 'awaiting_reply',
81
+ data: { label: input.label },
82
+ }),
83
+ );
84
+
85
+ return { label: input.label, reply };
86
+ },
87
+ });
88
+ const askTwice = defineAction<
89
+ { label: string },
90
+ { first: string; second: string },
91
+ TestContext,
92
+ Settings
93
+ >({
94
+ name: 'ask_twice',
95
+ inputSchema: labelSchema,
96
+ outputSchema: z.object({ first: z.string(), second: z.string() }),
97
+ execute: async ({ context }) => {
98
+ countRun('ask_twice');
99
+ const first = replySchema.parse(
100
+ await context.workflow.suspend({ reason: 'first' }),
101
+ );
102
+ const second = replySchema.parse(
103
+ await context.workflow.suspend({ key: 'confirm', reason: 'second' }),
104
+ );
105
+
106
+ return { first: first.reply, second: second.reply };
107
+ },
108
+ });
109
+ const stamp = defineAction<
110
+ Record<string, never>,
111
+ { at: Date },
112
+ TestContext,
113
+ Settings
114
+ >({
115
+ name: 'stamp',
116
+ outputSchema: z.object({ at: z.date() }),
117
+ execute: async () => {
118
+ countRun('stamp');
119
+
120
+ return { at: new Date(0) };
121
+ },
122
+ });
123
+ /** Changes its input and two answers in place before suspending again. */
124
+ const amend = defineAction<
125
+ { tags: string[] },
126
+ { tags: string[]; first: string; second: string; third: string },
127
+ TestContext,
128
+ Settings
129
+ >({
130
+ name: 'amend',
131
+ outputSchema: z.object({
132
+ tags: z.array(z.string()),
133
+ first: z.string(),
134
+ second: z.string(),
135
+ third: z.string(),
136
+ }),
137
+ execute: async ({ input, context }) => {
138
+ countRun('amend');
139
+ input.tags.push('seen');
140
+ const first = (await context.workflow.suspend({ reason: 'first' })) as {
141
+ reply: string;
142
+ };
143
+ first.reply += '!';
144
+ const second = (await context.workflow.suspend({
145
+ reason: 'second',
146
+ accepts: z.any(),
147
+ })) as { reply: string };
148
+ second.reply += '!';
149
+ const third = replySchema.parse(
150
+ await context.workflow.suspend({ reason: 'third' }),
151
+ );
152
+
153
+ return {
154
+ tags: input.tags,
155
+ first: first.reply,
156
+ second: second.reply,
157
+ third: third.reply,
158
+ };
159
+ },
160
+ });
161
+ const actions = { record, ask, ask_twice: askTwice, stamp, amend };
162
+ const compile = (definition: WorkflowDefinition) =>
163
+ compileWorkflow(definition, { actions });
164
+ const noRetries = { retries: { enabled: false } } as Settings;
165
+
166
+ type Fixture = {
167
+ name: string;
168
+ definition: WorkflowDefinition;
169
+ /** Choose the wait to resolve next; defaults to the first open wait. */
170
+ pick?: (waits: WaitInfo[]) => WaitInfo;
171
+ expectedOutput: Record<string, unknown>;
172
+ expectedResumes: number;
173
+ expectedRuns: Record<string, number>;
174
+ };
175
+
176
+ type Mode = 'in-process' | 'durable';
177
+
178
+ /**
179
+ * Drive a fixture to completion, answering waits with `r<turn>`.
180
+ *
181
+ * In `durable` mode every suspension goes through a JSON round trip into a
182
+ * brand-new compiled workflow, runner, and context: nothing in memory
183
+ * survives from one turn to the next.
184
+ */
185
+ const drive = async (fixture: Fixture, mode: Mode) => {
186
+ bodyRuns = {};
187
+
188
+ let runner = new WorkflowRunner(compile(fixture.definition));
189
+ let result: WorkflowRunResult = await runner.start({
190
+ inputData: {},
191
+ context: new TestContext({}),
192
+ });
193
+ let turn = 0;
194
+
195
+ while (result.status === 'suspended') {
196
+ expect(turn).toBeLessThan(20);
197
+ const wait = (fixture.pick ?? ((waits) => waits[0]))(result.waits);
198
+
199
+ if (mode === 'durable') {
200
+ const persisted = JSON.parse(
201
+ JSON.stringify({
202
+ checkpoint: result.checkpoint,
203
+ snapshot: result.snapshot,
204
+ }),
205
+ );
206
+ runner = WorkflowRunner.fromCheckpoint(compile(fixture.definition), {
207
+ checkpoint: persisted.checkpoint,
208
+ snapshot: persisted.snapshot,
209
+ context: new TestContext({}),
210
+ });
211
+ }
212
+
213
+ result = await runner.resume({
214
+ waitId: wait.waitId,
215
+ resumeData: { reply: `r${turn}` },
216
+ });
217
+ turn += 1;
218
+ }
219
+
220
+ if (result.status === 'failed') {
221
+ throw result.error;
222
+ }
223
+
224
+ return { output: result.output, resumes: turn, runs: { ...bodyRuns } };
225
+ };
226
+ const fixtures: Fixture[] = [
227
+ {
228
+ name: 'sequential steps',
229
+ definition: {
230
+ defs: createTaskDefs({
231
+ first: { action: 'record', inputs: { label: 'a' } },
232
+ question: { action: 'ask', inputs: { label: 'b' } },
233
+ last: { action: 'record', inputs: { label: 'c' } },
234
+ }),
235
+ flow: [{ do: 'first' }, { do: 'question' }, { do: 'last' }],
236
+ outputs: {
237
+ first: '=$output.first.label',
238
+ reply: '=$output.question.reply',
239
+ last: '=$output.last.label',
240
+ },
241
+ },
242
+ expectedOutput: { first: 'a', reply: 'r0', last: 'c' },
243
+ expectedResumes: 1,
244
+ expectedRuns: { record: 2, ask: 2 },
245
+ },
246
+ {
247
+ name: 'output values that are not plain JSON',
248
+ definition: {
249
+ defs: createTaskDefs({
250
+ clock: { action: 'stamp' },
251
+ question: { action: 'ask', inputs: { label: 'q' } },
252
+ }),
253
+ flow: [{ do: 'clock' }, { do: 'question' }],
254
+ outputs: { at: '=$output.clock.at' },
255
+ },
256
+ // Both modes resume from what a host stores: the Date as an ISO string.
257
+ expectedOutput: { at: '1970-01-01T00:00:00.000Z' },
258
+ expectedResumes: 1,
259
+ expectedRuns: { stamp: 1, ask: 2 },
260
+ },
261
+ {
262
+ name: 'conditional branch',
263
+ definition: {
264
+ defs: createTaskDefs({
265
+ question: { action: 'ask', inputs: { label: 'q' } },
266
+ skipped: { action: 'record', inputs: { label: 'never' } },
267
+ after: {
268
+ action: 'record',
269
+ inputs: { label: '=$output.question.reply' },
270
+ },
271
+ }),
272
+ flow: [
273
+ {
274
+ conditional: {
275
+ when: [
276
+ { condition: '=true', steps: [{ do: 'question' }] },
277
+ { else: true, steps: [{ do: 'skipped' }] },
278
+ ],
279
+ },
280
+ },
281
+ { do: 'after' },
282
+ ],
283
+ outputs: { after: '=$output.after.label' },
284
+ },
285
+ expectedOutput: { after: 'r0' },
286
+ expectedResumes: 1,
287
+ expectedRuns: { record: 1, ask: 2 },
288
+ },
289
+ {
290
+ name: 'for_each accumulator reading $iteration.item',
291
+ definition: {
292
+ defs: createTaskDefs({
293
+ question: { action: 'ask', inputs: { label: '=$iteration.item' } },
294
+ }),
295
+ flow: [
296
+ {
297
+ loop: {
298
+ type: 'for_each',
299
+ name: 'items',
300
+ for_each: { item: 'item', in: '=["a", "b", "c"]' },
301
+ accumulate: {
302
+ as: 'acc',
303
+ initial: [],
304
+ merge:
305
+ '=$append($accumulator, [$output.question.label & ":" & $output.question.reply])',
306
+ },
307
+ steps: [{ do: 'question' }],
308
+ },
309
+ },
310
+ ],
311
+ outputs: { acc: '=$output.items.acc' },
312
+ },
313
+ expectedOutput: { acc: ['a:r0', 'b:r1', 'c:r2'] },
314
+ expectedResumes: 3,
315
+ expectedRuns: { ask: 6 },
316
+ },
317
+ {
318
+ name: 'nested for_each and while loops',
319
+ definition: {
320
+ defs: createTaskDefs({
321
+ question: {
322
+ action: 'ask',
323
+ inputs: { label: '="q" & $string($iteration.index)' },
324
+ },
325
+ done: { action: 'record', inputs: { label: 'done' } },
326
+ }),
327
+ flow: [
328
+ {
329
+ loop: {
330
+ type: 'for_each',
331
+ name: 'outer',
332
+ for_each: { item: 'item', in: '=["a", "b"]' },
333
+ accumulate: {
334
+ as: 'acc',
335
+ initial: [],
336
+ merge:
337
+ '=$append($accumulator, [$iteration.item & "=" & $join($output.inner.replies, "+")])',
338
+ },
339
+ steps: [
340
+ {
341
+ loop: {
342
+ type: 'while',
343
+ name: 'inner',
344
+ while: '=$count($accumulator) < 2',
345
+ accumulate: {
346
+ as: 'replies',
347
+ initial: [],
348
+ merge: '=$append($accumulator, [$output.question.reply])',
349
+ },
350
+ steps: [{ do: 'question' }],
351
+ },
352
+ },
353
+ ],
354
+ },
355
+ },
356
+ { do: 'done' },
357
+ ],
358
+ outputs: { acc: '=$output.outer.acc' },
359
+ },
360
+ expectedOutput: { acc: ['a=r0+r1', 'b=r2+r3'] },
361
+ expectedResumes: 4,
362
+ expectedRuns: { ask: 8, record: 1 },
363
+ },
364
+ {
365
+ name: 'action with two suspend points',
366
+ definition: {
367
+ defs: createTaskDefs({
368
+ confirm: { action: 'ask_twice', inputs: { label: 'x' } },
369
+ after: { action: 'record', inputs: { label: 'after' } },
370
+ }),
371
+ flow: [{ do: 'confirm' }, { do: 'after' }],
372
+ outputs: {
373
+ first: '=$output.confirm.first',
374
+ second: '=$output.confirm.second',
375
+ },
376
+ },
377
+ expectedOutput: { first: 'r0', second: 'r1' },
378
+ expectedResumes: 2,
379
+ expectedRuns: { ask_twice: 3, record: 1 },
380
+ },
381
+ {
382
+ name: 'action that changes its input and its answers in place',
383
+ definition: {
384
+ defs: createTaskDefs({
385
+ edit: { action: 'amend', inputs: { tags: ['a'] } },
386
+ }),
387
+ flow: [{ do: 'edit' }],
388
+ outputs: {
389
+ tags: '=$output.edit.tags',
390
+ first: '=$output.edit.first',
391
+ second: '=$output.edit.second',
392
+ third: '=$output.edit.third',
393
+ },
394
+ },
395
+ // Every pass starts from the recorded values, so each change lands once.
396
+ expectedOutput: {
397
+ tags: ['a', 'seen'],
398
+ first: 'r0!',
399
+ second: 'r1!',
400
+ third: 'r2',
401
+ },
402
+ expectedResumes: 3,
403
+ expectedRuns: { amend: 4 },
404
+ },
405
+ ...(['first', 'last'] as const).map(
406
+ (order): Fixture => ({
407
+ name: `parallel wait_all with two waits resumed ${order} first`,
408
+ definition: {
409
+ defs: createTaskDefs({
410
+ ask_a: { action: 'ask', inputs: { label: 'a' } },
411
+ middle: { action: 'record', inputs: { label: 'middle' } },
412
+ ask_b: { action: 'ask', inputs: { label: 'b' } },
413
+ after: { action: 'record', inputs: { label: 'after' } },
414
+ }),
415
+ flow: [
416
+ {
417
+ parallel: {
418
+ strategy: 'wait_all',
419
+ steps: [{ do: 'ask_a' }, { do: 'middle' }, { do: 'ask_b' }],
420
+ },
421
+ },
422
+ { do: 'after' },
423
+ ],
424
+ outputs: {
425
+ a: '=$output.ask_a.reply',
426
+ middle: '=$output.middle.label',
427
+ b: '=$output.ask_b.reply',
428
+ },
429
+ },
430
+ pick: (waits) => (order === 'first' ? waits[0] : waits[waits.length - 1]),
431
+ expectedOutput:
432
+ order === 'first'
433
+ ? { a: 'r0', middle: 'middle', b: 'r1' }
434
+ : { a: 'r1', middle: 'middle', b: 'r0' },
435
+ expectedResumes: 2,
436
+ expectedRuns: { ask: 4, record: 2 },
437
+ }),
438
+ ),
439
+ {
440
+ name: 'parallel wait_any where a sibling fulfills while another waits',
441
+ definition: {
442
+ defs: createTaskDefs({
443
+ question: { action: 'ask', inputs: { label: 'q' } },
444
+ quick: { action: 'record', inputs: { label: 'quick' } },
445
+ }),
446
+ flow: [
447
+ {
448
+ parallel: {
449
+ strategy: 'wait_any',
450
+ steps: [{ do: 'question' }, { do: 'quick' }],
451
+ },
452
+ },
453
+ ],
454
+ outputs: {
455
+ quick: '=$output.quick.label',
456
+ question: '=$exists($output.question)',
457
+ },
458
+ },
459
+ expectedOutput: { quick: 'quick', question: false },
460
+ expectedResumes: 0,
461
+ expectedRuns: { ask: 1, record: 1 },
462
+ },
463
+ {
464
+ name: 'parallel wait_any where the first resolved wait wins',
465
+ definition: {
466
+ defs: createTaskDefs({
467
+ ask_a: { action: 'ask', inputs: { label: 'a' } },
468
+ ask_b: { action: 'ask', inputs: { label: 'b' } },
469
+ }),
470
+ flow: [
471
+ {
472
+ parallel: {
473
+ strategy: 'wait_any',
474
+ steps: [{ do: 'ask_a' }, { do: 'ask_b' }],
475
+ },
476
+ },
477
+ ],
478
+ outputs: {
479
+ b: '=$output.ask_b.reply',
480
+ a: '=$exists($output.ask_a)',
481
+ },
482
+ },
483
+ pick: (waits) => waits[1],
484
+ expectedOutput: { b: 'r0', a: false },
485
+ expectedResumes: 1,
486
+ expectedRuns: { ask: 3 },
487
+ },
488
+ {
489
+ name: 'loop inside parallel inside loop',
490
+ definition: {
491
+ defs: createTaskDefs({
492
+ question: { action: 'ask', inputs: { label: '=$iteration.item' } },
493
+ side: {
494
+ action: 'record',
495
+ inputs: { label: '="side-" & $string($iteration.item)' },
496
+ },
497
+ }),
498
+ flow: [
499
+ {
500
+ loop: {
501
+ type: 'for_each',
502
+ name: 'outer',
503
+ for_each: { item: 'n', in: '=[1, 2]' },
504
+ accumulate: {
505
+ as: 'acc',
506
+ initial: [],
507
+ merge:
508
+ '=$append($accumulator, [$output.side.label & ":" & $output.question.reply])',
509
+ },
510
+ steps: [
511
+ {
512
+ parallel: {
513
+ strategy: 'wait_all',
514
+ steps: [
515
+ {
516
+ loop: {
517
+ type: 'for_each',
518
+ name: 'inner',
519
+ for_each: { item: 'letter', in: '=["a", "b"]' },
520
+ steps: [{ do: 'question' }],
521
+ },
522
+ },
523
+ { do: 'side' },
524
+ ],
525
+ },
526
+ },
527
+ ],
528
+ },
529
+ },
530
+ ],
531
+ outputs: { acc: '=$output.outer.acc' },
532
+ },
533
+ expectedOutput: { acc: ['side-1:r1', 'side-2:r3'] },
534
+ expectedResumes: 4,
535
+ expectedRuns: { ask: 8, record: 2 },
536
+ },
537
+ {
538
+ name: '$accumulator of a finished loop read after a suspension',
539
+ definition: {
540
+ defs: createTaskDefs({
541
+ tick: {
542
+ action: 'record',
543
+ inputs: { label: '="n" & $string($iteration.item)' },
544
+ },
545
+ question: { action: 'ask', inputs: { label: 'q' } },
546
+ total: {
547
+ action: 'record',
548
+ inputs: { label: '=$string($accumulator)' },
549
+ },
550
+ }),
551
+ flow: [
552
+ {
553
+ loop: {
554
+ type: 'for_each',
555
+ for_each: { item: 'n', in: '=[1, 2, 3]' },
556
+ accumulate: { as: 'count', initial: 0, merge: '=$accumulator + 1' },
557
+ steps: [{ do: 'tick' }],
558
+ },
559
+ },
560
+ { do: 'question' },
561
+ { do: 'total' },
562
+ ],
563
+ outputs: { total: '=$output.total.label' },
564
+ },
565
+ expectedOutput: { total: '3' },
566
+ expectedResumes: 1,
567
+ expectedRuns: { record: 4, ask: 2 },
568
+ },
569
+ {
570
+ name: '$accumulator of an inner loop read after a suspension in the outer loop',
571
+ definition: {
572
+ defs: createTaskDefs({
573
+ tick: { action: 'record', inputs: { label: 'tick' } },
574
+ question: { action: 'ask', inputs: { label: 'q' } },
575
+ after: {
576
+ action: 'record',
577
+ inputs: { label: '=$string($accumulator)' },
578
+ },
579
+ }),
580
+ flow: [
581
+ {
582
+ loop: {
583
+ type: 'for_each',
584
+ name: 'outer',
585
+ for_each: { item: 'item', in: '=["a", "b"]' },
586
+ accumulate: {
587
+ as: 'seen',
588
+ initial: [],
589
+ merge: '=$append($accumulator, [$output.after.label])',
590
+ },
591
+ steps: [
592
+ {
593
+ loop: {
594
+ type: 'for_each',
595
+ for_each: { item: 'n', in: '=[1, 2]' },
596
+ accumulate: {
597
+ as: 'count',
598
+ initial: 10,
599
+ merge: '=$accumulator + 1',
600
+ },
601
+ steps: [{ do: 'tick' }],
602
+ },
603
+ },
604
+ { do: 'question' },
605
+ { do: 'after' },
606
+ ],
607
+ },
608
+ },
609
+ ],
610
+ outputs: { seen: '=$output.outer.seen' },
611
+ },
612
+ // Steps after the inner loop see its result, not the outer accumulator.
613
+ expectedOutput: { seen: ['12', '12'] },
614
+ expectedResumes: 2,
615
+ expectedRuns: { record: 6, ask: 4 },
616
+ },
617
+ ];
618
+
619
+ describe('checkpoint durability', () => {
620
+ it.each(fixtures)(
621
+ '$name behaves the same in process and across fresh runners',
622
+ async (fixture) => {
623
+ const inProcess = await drive(fixture, 'in-process');
624
+ const durable = await drive(fixture, 'durable');
625
+
626
+ expect(inProcess.output).toEqual(fixture.expectedOutput);
627
+ expect(durable.output).toEqual(inProcess.output);
628
+ expect(inProcess.resumes).toBe(fixture.expectedResumes);
629
+ expect(durable.resumes).toBe(fixture.expectedResumes);
630
+ // Completed steps and parallel siblings run exactly once; a suspended
631
+ // body runs once, then once more per resolved wait.
632
+ expect(inProcess.runs).toEqual(fixture.expectedRuns);
633
+ expect(durable.runs).toEqual(fixture.expectedRuns);
634
+ },
635
+ );
636
+ });
637
+
638
+ describe('checkpoint validation', () => {
639
+ const definition: WorkflowDefinition = {
640
+ defs: createTaskDefs({
641
+ first: { action: 'record', inputs: { label: 'a' } },
642
+ question: { action: 'ask', inputs: { label: '=$iteration.item' } },
643
+ }),
644
+ flow: [
645
+ { do: 'first' },
646
+ {
647
+ loop: {
648
+ type: 'for_each',
649
+ name: 'items',
650
+ for_each: { item: 'item', in: '=["a", "b"]' },
651
+ until: '=false',
652
+ steps: [{ do: 'question' }],
653
+ },
654
+ },
655
+ ],
656
+ outputs: { reply: '=$output.question.reply' },
657
+ };
658
+ const suspend = async (source: WorkflowDefinition = definition) => {
659
+ const runner = new WorkflowRunner(compile(source));
660
+ const result = await runner.start({
661
+ inputData: {},
662
+ context: new TestContext({}),
663
+ });
664
+ if (result.status !== 'suspended') {
665
+ throw new Error('Expected the run to suspend');
666
+ }
667
+
668
+ bodyRuns = {};
669
+
670
+ return JSON.parse(JSON.stringify(result.checkpoint)) as WorkflowCheckpoint;
671
+ };
672
+ const expectRejected = <E extends Error>(
673
+ checkpoint: unknown,
674
+ type: new (...args: any[]) => E,
675
+ compiled = compile(definition),
676
+ waitId?: string,
677
+ ): E => {
678
+ const result = validateCheckpoint(compiled, checkpoint, {
679
+ waitId,
680
+ });
681
+ if (result.ok) {
682
+ throw new Error('Expected the checkpoint to be rejected');
683
+ }
684
+ expect(result.error).toBeInstanceOf(type);
685
+ if (waitId === undefined) {
686
+ expect(() =>
687
+ WorkflowRunner.fromCheckpoint(compiled, {
688
+ checkpoint,
689
+ context: new TestContext({}),
690
+ }),
691
+ ).toThrow(type);
692
+ }
693
+ expect(bodyRuns).toEqual({});
694
+
695
+ return result.error as E;
696
+ };
697
+
698
+ it('accepts a checkpoint and a wait it holds', async () => {
699
+ const checkpoint = await suspend();
700
+ const result = validateCheckpoint(compile(definition), checkpoint, {
701
+ waitId: checkpoint.waits[0].waitId,
702
+ });
703
+
704
+ expect(result.ok).toBe(true);
705
+ expect(checkpoint.waits.map((wait) => wait.step.id)).toEqual([
706
+ '1.items.0:question[0]',
707
+ ]);
708
+ });
709
+
710
+ it('reports a missing checkpoint', () => {
711
+ expect(expectRejected(undefined, WorkflowCheckpointInvalidError).code).toBe(
712
+ 'missing',
713
+ );
714
+ });
715
+
716
+ it('reports an unsupported version', async () => {
717
+ const checkpoint = { ...(await suspend()), version: 2 };
718
+
719
+ expect(
720
+ expectRejected(checkpoint, WorkflowCheckpointInvalidError).code,
721
+ ).toBe('unsupported_version');
722
+ });
723
+
724
+ it('reports a malformed checkpoint with its issues', async () => {
725
+ const checkpoint = await suspend();
726
+ const broken = { ...checkpoint, root: { kind: 'sequence', index: -1 } };
727
+ const error = expectRejected(broken, WorkflowCheckpointInvalidError);
728
+
729
+ expect(error.code).toBe('malformed');
730
+ expect(error.issues?.length).toBeGreaterThan(0);
731
+ });
732
+
733
+ it('reports frames that do not line up with the flow', async () => {
734
+ const checkpoint = await suspend();
735
+ const broken = {
736
+ ...checkpoint,
737
+ root: { ...checkpoint.root, index: 0 },
738
+ };
739
+ const error = expectRejected(broken, WorkflowCheckpointInvalidError);
740
+
741
+ expect(error.code).toBe('structure');
742
+ expect(error.path).toEqual(['root', 0]);
743
+ });
744
+
745
+ it('reports a waits index that disagrees with the frames', async () => {
746
+ const checkpoint = await suspend();
747
+ const broken = {
748
+ ...checkpoint,
749
+ waits: [{ ...checkpoint.waits[0], waitId: 'other@index:1' }],
750
+ };
751
+
752
+ expect(expectRejected(broken, WorkflowCheckpointInvalidError).code).toBe(
753
+ 'structure',
754
+ );
755
+ });
756
+
757
+ describe('frames checked against the compiled flow', () => {
758
+ const nested: WorkflowDefinition = {
759
+ defs: createTaskDefs({
760
+ ask_a: { action: 'ask', inputs: { label: 'a' } },
761
+ ask_b: { action: 'ask', inputs: { label: 'b' } },
762
+ }),
763
+ flow: [
764
+ {
765
+ conditional: {
766
+ when: [
767
+ {
768
+ condition: '=true',
769
+ steps: [
770
+ {
771
+ loop: {
772
+ type: 'for_each',
773
+ name: 'outer',
774
+ for_each: { item: 'item', in: '=["x", "y"]' },
775
+ steps: [
776
+ {
777
+ parallel: {
778
+ strategy: 'wait_all',
779
+ steps: [
780
+ { do: 'ask_a' },
781
+ {
782
+ loop: {
783
+ type: 'while',
784
+ name: 'inner',
785
+ while: '=$count($accumulator) < 1',
786
+ accumulate: {
787
+ as: 'seen',
788
+ initial: [],
789
+ merge: '=$append($accumulator, [1])',
790
+ },
791
+ steps: [{ do: 'ask_b' }],
792
+ },
793
+ },
794
+ ],
795
+ },
796
+ },
797
+ ],
798
+ },
799
+ },
800
+ ],
801
+ },
802
+ ],
803
+ },
804
+ },
805
+ ],
806
+ outputs: {},
807
+ };
808
+ // root -> conditional -> for_each -> parallel -> [task, while -> task]
809
+ const conditionalFrame = (checkpoint: any) => checkpoint.root.child;
810
+ const forEachFrame = (checkpoint: any) =>
811
+ conditionalFrame(checkpoint).child.child;
812
+ const parallelFrame = (checkpoint: any) =>
813
+ forEachFrame(checkpoint).child.child;
814
+ const loopPath = ['root', 0, 'branch', 0, 0];
815
+ const parallelPath = [...loopPath, 0, 0];
816
+
817
+ it.each<[string, (checkpoint: any) => void, Array<string | number>]>([
818
+ [
819
+ 'a sequence position out of range',
820
+ (checkpoint) => (checkpoint.root.index = 5),
821
+ ['root'],
822
+ ],
823
+ [
824
+ 'a conditional branch that does not exist',
825
+ (checkpoint) => (conditionalFrame(checkpoint).branchIndex = 3),
826
+ ['root', 0],
827
+ ],
828
+ [
829
+ 'a for_each iteration past its items',
830
+ (checkpoint) => (forEachFrame(checkpoint).index = 2),
831
+ loopPath,
832
+ ],
833
+ [
834
+ 'a for_each frame without items',
835
+ (checkpoint) => delete forEachFrame(checkpoint).items,
836
+ loopPath,
837
+ ],
838
+ [
839
+ 'a while frame carrying items',
840
+ (checkpoint) =>
841
+ (parallelFrame(checkpoint).branches[1].child.items = []),
842
+ [...parallelPath, 'parallel', 1],
843
+ ],
844
+ [
845
+ 'a parallel branch count that differs from the flow',
846
+ (checkpoint) => parallelFrame(checkpoint).branches.pop(),
847
+ parallelPath,
848
+ ],
849
+ [
850
+ 'a parallel frame without a suspended branch',
851
+ (checkpoint) => {
852
+ parallelFrame(checkpoint).branches = [
853
+ { status: 'fulfilled', outputDelta: {} },
854
+ { status: 'fulfilled', outputDelta: {} },
855
+ ];
856
+ },
857
+ parallelPath,
858
+ ],
859
+ [
860
+ 'two frames holding the same wait',
861
+ (checkpoint) => {
862
+ const [first, second] = parallelFrame(checkpoint).branches;
863
+ second.child.child.child.wait.waitId = first.child.wait.waitId;
864
+ checkpoint.waits[1].waitId = first.child.wait.waitId;
865
+ },
866
+ ['waits'],
867
+ ],
868
+ ])('reports %s', async (_label, tamper, path) => {
869
+ const checkpoint = await suspend(nested);
870
+ tamper(checkpoint);
871
+ const error = expectRejected(
872
+ checkpoint,
873
+ WorkflowCheckpointInvalidError,
874
+ compile(nested),
875
+ );
876
+
877
+ expect(error.code).toBe('structure');
878
+ expect(error.path).toEqual(path);
879
+ });
880
+
881
+ it('reports a wait_any block that records a fulfilled branch', async () => {
882
+ const race: WorkflowDefinition = {
883
+ defs: createTaskDefs({
884
+ ask_a: { action: 'ask', inputs: { label: 'a' } },
885
+ ask_b: { action: 'ask', inputs: { label: 'b' } },
886
+ }),
887
+ flow: [
888
+ {
889
+ parallel: {
890
+ strategy: 'wait_any',
891
+ steps: [{ do: 'ask_a' }, { do: 'ask_b' }],
892
+ },
893
+ },
894
+ ],
895
+ outputs: {},
896
+ };
897
+ const checkpoint: any = await suspend(race);
898
+ checkpoint.root.child.branches[0] = {
899
+ status: 'fulfilled',
900
+ outputDelta: {},
901
+ };
902
+ checkpoint.waits = checkpoint.waits.slice(1);
903
+ const error = expectRejected(
904
+ checkpoint,
905
+ WorkflowCheckpointInvalidError,
906
+ compile(race),
907
+ );
908
+
909
+ expect(error.code).toBe('structure');
910
+ expect(error.message).toMatch(/cannot record a fulfilled branch/);
911
+ });
912
+ });
913
+
914
+ it.each([
915
+ [
916
+ 'a renamed task',
917
+ (next: WorkflowDefinition) => {
918
+ next.defs = createTaskDefs({
919
+ first: { action: 'record', inputs: { label: 'a' } },
920
+ prompt: { action: 'ask', inputs: { label: '=$iteration.item' } },
921
+ });
922
+ (next.flow[1] as any).loop.steps = [{ do: 'prompt' }];
923
+ },
924
+ ],
925
+ [
926
+ 'a step inserted before the wait',
927
+ (next: WorkflowDefinition) => {
928
+ next.flow.unshift({ do: 'first' });
929
+ },
930
+ ],
931
+ [
932
+ 'a changed until expression',
933
+ (next: WorkflowDefinition) => {
934
+ (next.flow[1] as any).loop.until = '=true';
935
+ },
936
+ ],
937
+ ])('reports drift after %s', async (_label, mutate) => {
938
+ const checkpoint = await suspend();
939
+ const next = structuredClone(definition);
940
+ mutate(next);
941
+
942
+ expectRejected(checkpoint, WorkflowDefinitionDriftError, compile(next));
943
+ });
944
+
945
+ it('reports a wait that is not open', async () => {
946
+ const checkpoint = await suspend();
947
+ const error = expectRejected(
948
+ checkpoint,
949
+ WorkflowWaitNotFoundError,
950
+ compile(definition),
951
+ 'missing@index:1',
952
+ );
953
+
954
+ expect(error.openWaitIds).toEqual([checkpoint.waits[0].waitId]);
955
+
956
+ const runner = WorkflowRunner.fromCheckpoint(compile(definition), {
957
+ checkpoint,
958
+ context: new TestContext({}),
959
+ });
960
+ await expect(
961
+ runner.resume({ waitId: 'missing@index:1', resumeData: {} }),
962
+ ).rejects.toBeInstanceOf(WorkflowWaitNotFoundError);
963
+ expect(bodyRuns).toEqual({});
964
+
965
+ // The rejected call leaves the run suspended on the same open wait.
966
+ expect(runner.getStatus()).toBe('suspended');
967
+ const resumed = await runner.resume({
968
+ waitId: checkpoint.waits[0].waitId,
969
+ resumeData: { reply: 'a' },
970
+ });
971
+
972
+ expect(resumed.status).toBe('suspended');
973
+ if (resumed.status === 'suspended') {
974
+ expect(resumed.waits[0].step.id).toBe('1.items.0:question[1]');
975
+ }
976
+ });
977
+ });
978
+
979
+ describe('suspended action bodies', () => {
980
+ it('re-resolves suspend results when a resumed body is retried', async () => {
981
+ let failures = 0;
982
+ const flaky = defineAction<
983
+ Record<string, never>,
984
+ { reply: string },
985
+ TestContext,
986
+ Settings
987
+ >({
988
+ name: 'flaky',
989
+ outputSchema: replySchema,
990
+ execute: async ({ context }) => {
991
+ countRun('flaky');
992
+ const resumed = replySchema.parse(await context.workflow.suspend());
993
+ if (failures === 0) {
994
+ failures += 1;
995
+ throw new Error('transient');
996
+ }
997
+
998
+ return resumed;
999
+ },
1000
+ });
1001
+ const compiled = compileWorkflow(
1002
+ {
1003
+ defs: createTaskDefs({
1004
+ step: {
1005
+ action: 'flaky',
1006
+ settings: {
1007
+ retries: {
1008
+ enabled: true,
1009
+ max_attempts: 2,
1010
+ backoff_ms: 0,
1011
+ max_delay_ms: 0,
1012
+ jitter: 0,
1013
+ multiplier: 1,
1014
+ },
1015
+ },
1016
+ },
1017
+ }),
1018
+ flow: [{ do: 'step' }],
1019
+ outputs: { reply: '=$output.step.reply' },
1020
+ },
1021
+ { actions: { flaky } },
1022
+ );
1023
+ bodyRuns = {};
1024
+ const runner = new WorkflowRunner(compiled);
1025
+ const started = await runner.start({
1026
+ inputData: {},
1027
+ context: new TestContext({}),
1028
+ });
1029
+ expect(started.status).toBe('suspended');
1030
+
1031
+ const resumed = await runner.resume({ resumeData: { reply: 'ok' } });
1032
+
1033
+ expect(resumed.status).toBe('finished');
1034
+ if (resumed.status === 'finished') {
1035
+ expect(resumed.output).toEqual({ reply: 'ok' });
1036
+ }
1037
+ // Start, then the failing re-run, then its retry.
1038
+ expect(bodyRuns).toEqual({ flaky: 3 });
1039
+ });
1040
+
1041
+ it('stops the timeout of a suspended body', async () => {
1042
+ const unhandled = jest.fn();
1043
+ process.on('unhandledRejection', unhandled);
1044
+ try {
1045
+ const compiled = compileWorkflow(
1046
+ {
1047
+ defs: createTaskDefs({
1048
+ question: {
1049
+ action: 'ask',
1050
+ inputs: { label: 'q' },
1051
+ settings: { timeout_ms: 30 },
1052
+ },
1053
+ }),
1054
+ flow: [{ do: 'question' }],
1055
+ outputs: { reply: '=$output.question.reply' },
1056
+ },
1057
+ { actions },
1058
+ );
1059
+ const runner = new WorkflowRunner(compiled);
1060
+ await runner.start({ inputData: {}, context: new TestContext({}) });
1061
+ await new Promise((resolve) => setTimeout(resolve, 80));
1062
+
1063
+ const resumed = await runner.resume({ resumeData: { reply: 'late' } });
1064
+
1065
+ expect(resumed.status).toBe('finished');
1066
+ expect(unhandled).not.toHaveBeenCalled();
1067
+ } finally {
1068
+ process.off('unhandledRejection', unhandled);
1069
+ }
1070
+ });
1071
+
1072
+ it('fails the run when a branch fails while a sibling is suspended', async () => {
1073
+ const boom = defineAction<
1074
+ Record<string, never>,
1075
+ never,
1076
+ TestContext,
1077
+ Settings
1078
+ >({
1079
+ name: 'boom',
1080
+ execute: async () => {
1081
+ await new Promise((resolve) => setTimeout(resolve, 5));
1082
+ throw new Error('boom');
1083
+ },
1084
+ });
1085
+ const compiled = compileWorkflow(
1086
+ {
1087
+ defs: createTaskDefs({
1088
+ question: { action: 'ask', inputs: { label: 'q' } },
1089
+ explode: { action: 'boom', settings: noRetries },
1090
+ }),
1091
+ flow: [
1092
+ {
1093
+ parallel: {
1094
+ strategy: 'wait_all',
1095
+ steps: [{ do: 'question' }, { do: 'explode' }],
1096
+ },
1097
+ },
1098
+ ],
1099
+ outputs: {},
1100
+ },
1101
+ { actions: { ...actions, boom } },
1102
+ );
1103
+ const runner = new WorkflowRunner(compiled);
1104
+ const result = await runner.start({
1105
+ inputData: {},
1106
+ context: new TestContext({}),
1107
+ });
1108
+
1109
+ expect(result.status).toBe('failed');
1110
+ if (result.status === 'failed') {
1111
+ expect((result.error as Error).message).toBe('boom');
1112
+ expect(result.snapshot.actions['0.parallel.0:question']).toMatchObject({
1113
+ status: 'cancelled',
1114
+ });
1115
+ }
1116
+ });
1117
+
1118
+ it('requires a waitId when several waits are open', async () => {
1119
+ const compiled = compileWorkflow(
1120
+ {
1121
+ defs: createTaskDefs({
1122
+ ask_a: { action: 'ask', inputs: { label: 'a' } },
1123
+ ask_b: { action: 'ask', inputs: { label: 'b' } },
1124
+ }),
1125
+ flow: [
1126
+ {
1127
+ parallel: {
1128
+ strategy: 'wait_all',
1129
+ steps: [{ do: 'ask_a' }, { do: 'ask_b' }],
1130
+ },
1131
+ },
1132
+ ],
1133
+ outputs: {},
1134
+ },
1135
+ { actions },
1136
+ );
1137
+ const runner = new WorkflowRunner(compiled);
1138
+ const started = await runner.start({
1139
+ inputData: {},
1140
+ context: new TestContext({}),
1141
+ });
1142
+
1143
+ expect(started.status).toBe('suspended');
1144
+ if (started.status !== 'suspended') {
1145
+ return;
1146
+ }
1147
+ expect(started.waits.map((wait) => wait.waitId)).toEqual([
1148
+ '0.parallel.0:ask_a@index:1',
1149
+ '0.parallel.1:ask_b@index:1',
1150
+ ]);
1151
+ const ambiguous = runner.resume({ resumeData: {} });
1152
+ await expect(ambiguous).rejects.toThrow(/pass a waitId/);
1153
+ await expect(ambiguous).rejects.toBeInstanceOf(WorkflowWaitAmbiguousError);
1154
+ await expect(
1155
+ runner.resume({ waitId: 'nope', resumeData: {} }),
1156
+ ).rejects.toBeInstanceOf(WorkflowWaitNotFoundError);
1157
+ });
1158
+
1159
+ it('fails instead of suspending when the run state is not JSON-serializable', async () => {
1160
+ const counter = defineAction<
1161
+ Record<string, never>,
1162
+ { total: bigint },
1163
+ TestContext,
1164
+ Settings
1165
+ >({
1166
+ name: 'counter',
1167
+ outputSchema: z.object({ total: z.bigint() }),
1168
+ execute: async () => ({ total: BigInt(1) }),
1169
+ });
1170
+ const compiled = compileWorkflow(
1171
+ {
1172
+ defs: createTaskDefs({
1173
+ count: { action: 'counter' },
1174
+ question: { action: 'ask', inputs: { label: 'q' } },
1175
+ }),
1176
+ flow: [{ do: 'count' }, { do: 'question' }],
1177
+ outputs: {},
1178
+ },
1179
+ { actions: { ...actions, counter } },
1180
+ );
1181
+ const runner = new WorkflowRunner(compiled);
1182
+ const result = await runner.start({
1183
+ inputData: {},
1184
+ context: new TestContext({}),
1185
+ });
1186
+
1187
+ expect(result.status).toBe('failed');
1188
+ if (result.status === 'failed') {
1189
+ expect((result.error as Error).message).toMatch(
1190
+ /^Cannot checkpoint the suspended run: its state is not JSON-serializable/,
1191
+ );
1192
+ }
1193
+ expect(runner.getCheckpoint()).toBeUndefined();
1194
+ });
1195
+
1196
+ it('resumes a body with the inputs recorded when it suspended', async () => {
1197
+ const definition: WorkflowDefinition = {
1198
+ defs: createTaskDefs({
1199
+ question: { action: 'ask', inputs: { label: '=$context.topic' } },
1200
+ }),
1201
+ flow: [{ do: 'question' }],
1202
+ outputs: { label: '=$output.question.label' },
1203
+ };
1204
+ const started = await new WorkflowRunner(compile(definition)).start({
1205
+ inputData: {},
1206
+ context: new TestContext({ topic: 'billing' }),
1207
+ });
1208
+ if (started.status !== 'suspended') {
1209
+ throw new Error('Expected the run to suspend');
1210
+ }
1211
+
1212
+ // Re-evaluating the inputs against the new context would read "shipping".
1213
+ const restored = WorkflowRunner.fromCheckpoint(compile(definition), {
1214
+ checkpoint: JSON.parse(JSON.stringify(started.checkpoint)),
1215
+ context: new TestContext({ topic: 'shipping' }),
1216
+ });
1217
+ const resumed = await restored.resume({ resumeData: { reply: 'ok' } });
1218
+
1219
+ expect(resumed).toMatchObject({
1220
+ status: 'finished',
1221
+ output: { label: 'billing' },
1222
+ });
1223
+ });
1224
+
1225
+ it('keeps the suspend position of a body that runs another action', async () => {
1226
+ const lookup = defineAction<
1227
+ Record<string, never>,
1228
+ string,
1229
+ TestContext,
1230
+ Settings
1231
+ >({
1232
+ name: 'lookup',
1233
+ outputSchema: z.string(),
1234
+ execute: async () => 'found',
1235
+ });
1236
+ const wizard = defineAction<
1237
+ Record<string, never>,
1238
+ { first: string; second: string },
1239
+ TestContext,
1240
+ Settings
1241
+ >({
1242
+ name: 'wizard',
1243
+ outputSchema: z.object({ first: z.string(), second: z.string() }),
1244
+ execute: async ({ context }) => {
1245
+ const first = replySchema.parse(await context.workflow.suspend());
1246
+ // Its attempt must not rewind the suspend cursor of this step.
1247
+ await lookup.run({}, context);
1248
+ const second = replySchema.parse(await context.workflow.suspend());
1249
+
1250
+ return { first: first.reply, second: second.reply };
1251
+ },
1252
+ });
1253
+ const compiled = compileWorkflow(
1254
+ {
1255
+ defs: createTaskDefs({ steps: { action: 'wizard' } }),
1256
+ flow: [{ do: 'steps' }],
1257
+ outputs: {
1258
+ first: '=$output.steps.first',
1259
+ second: '=$output.steps.second',
1260
+ },
1261
+ },
1262
+ { actions: { wizard, lookup } },
1263
+ );
1264
+ const runner = new WorkflowRunner(compiled);
1265
+ await runner.start({ inputData: {}, context: new TestContext({}) });
1266
+
1267
+ const middle = await runner.resume({ resumeData: { reply: 'r0' } });
1268
+
1269
+ expect(middle.status).toBe('suspended');
1270
+ if (middle.status === 'suspended') {
1271
+ expect(middle.waits[0].suspendKey).toBe('index:2');
1272
+ }
1273
+ await expect(
1274
+ runner.resume({ resumeData: { reply: 'r1' } }),
1275
+ ).resolves.toMatchObject({
1276
+ status: 'finished',
1277
+ output: { first: 'r0', second: 'r1' },
1278
+ });
1279
+ });
1280
+
1281
+ it('re-resolves the suspends of a nested action run that is retried', async () => {
1282
+ let failures = 0;
1283
+ const confirm = defineAction<
1284
+ Record<string, never>,
1285
+ { reply: string },
1286
+ TestContext,
1287
+ Settings
1288
+ >({
1289
+ name: 'confirm',
1290
+ outputSchema: replySchema,
1291
+ execute: async ({ context }) => {
1292
+ countRun('confirm');
1293
+ const reply = replySchema.parse(
1294
+ await context.workflow.suspend({ reason: 'confirm' }),
1295
+ );
1296
+ if (failures === 0) {
1297
+ failures += 1;
1298
+ throw new Error('transient');
1299
+ }
1300
+
1301
+ return reply;
1302
+ },
1303
+ });
1304
+ const twoAttempts = {
1305
+ retries: {
1306
+ enabled: true,
1307
+ max_attempts: 2,
1308
+ backoff_ms: 0,
1309
+ max_delay_ms: 0,
1310
+ jitter: 0,
1311
+ multiplier: 1,
1312
+ },
1313
+ };
1314
+ const wizard = defineAction<
1315
+ Record<string, never>,
1316
+ { first: string; second: string },
1317
+ TestContext,
1318
+ Settings
1319
+ >({
1320
+ name: 'wizard',
1321
+ outputSchema: z.object({ first: z.string(), second: z.string() }),
1322
+ execute: async ({ context }) => {
1323
+ const first = replySchema.parse(
1324
+ await context.workflow.suspend({ reason: 'first' }),
1325
+ );
1326
+ // Its retry starts over from its own first suspend, `index:2`.
1327
+ const second = await confirm.run({}, context, twoAttempts);
1328
+
1329
+ return { first: first.reply, second: second.reply };
1330
+ },
1331
+ });
1332
+ const compiled = compileWorkflow(
1333
+ {
1334
+ defs: createTaskDefs({ steps: { action: 'wizard' } }),
1335
+ flow: [{ do: 'steps' }],
1336
+ outputs: {
1337
+ first: '=$output.steps.first',
1338
+ second: '=$output.steps.second',
1339
+ },
1340
+ },
1341
+ { actions: { wizard, confirm } },
1342
+ );
1343
+ bodyRuns = {};
1344
+ const runner = new WorkflowRunner(compiled);
1345
+ await runner.start({ inputData: {}, context: new TestContext({}) });
1346
+ await runner.resume({ resumeData: { reply: 'r0' } });
1347
+
1348
+ await expect(
1349
+ runner.resume({ resumeData: { reply: 'r1' } }),
1350
+ ).resolves.toMatchObject({
1351
+ status: 'finished',
1352
+ output: { first: 'r0', second: 'r1' },
1353
+ });
1354
+ // Reached on the first resume, then the failing run and its retry.
1355
+ expect(bodyRuns).toEqual({ confirm: 3 });
1356
+ });
1357
+
1358
+ it('re-resolves suspend results of a retried action run behind a wrapper', async () => {
1359
+ let failures = 0;
1360
+ const flaky = defineAction<
1361
+ Record<string, never>,
1362
+ { reply: string },
1363
+ TestContext,
1364
+ Settings
1365
+ >({
1366
+ name: 'flaky',
1367
+ outputSchema: replySchema,
1368
+ execute: async ({ context }) => {
1369
+ const resumed = replySchema.parse(await context.workflow.suspend());
1370
+ if (failures === 0) {
1371
+ failures += 1;
1372
+ throw new Error('transient');
1373
+ }
1374
+
1375
+ return resumed;
1376
+ },
1377
+ });
1378
+ // A decorator around the action, e.g. to add logging or metrics.
1379
+ const wrapped: Action<Record<string, never>, { reply: string }> = {
1380
+ name: 'wrapped',
1381
+ description: 'Logs around flaky',
1382
+ inputSchema: flaky.inputSchema,
1383
+ outputSchema: flaky.outputSchema,
1384
+ settingSchema: flaky.settingSchema,
1385
+ execute: (args) => flaky.execute(args as never),
1386
+ parseInput: (payload) => flaky.parseInput(payload),
1387
+ parseOutput: (payload) => flaky.parseOutput(payload),
1388
+ parseSettings: (payload) => flaky.parseSettings(payload),
1389
+ run: (payload, context, settings, bindings, signal) =>
1390
+ flaky.run(payload, context as TestContext, settings, bindings, signal),
1391
+ };
1392
+ const compiled = compileWorkflow(
1393
+ {
1394
+ defs: createTaskDefs({
1395
+ step: {
1396
+ action: 'wrapped',
1397
+ settings: {
1398
+ retries: {
1399
+ enabled: true,
1400
+ max_attempts: 2,
1401
+ backoff_ms: 0,
1402
+ max_delay_ms: 0,
1403
+ jitter: 0,
1404
+ multiplier: 1,
1405
+ },
1406
+ },
1407
+ },
1408
+ }),
1409
+ flow: [{ do: 'step' }],
1410
+ outputs: { reply: '=$output.step.reply' },
1411
+ },
1412
+ { actions: { wrapped: wrapped as Action } },
1413
+ );
1414
+ const runner = new WorkflowRunner(compiled);
1415
+ await runner.start({ inputData: {}, context: new TestContext({}) });
1416
+
1417
+ await expect(
1418
+ runner.resume({ resumeData: { reply: 'ok' } }),
1419
+ ).resolves.toMatchObject({ status: 'finished', output: { reply: 'ok' } });
1420
+ });
1421
+
1422
+ it('fails when a body reuses a suspend key', async () => {
1423
+ const reusing = defineAction<
1424
+ Record<string, never>,
1425
+ unknown,
1426
+ TestContext,
1427
+ Settings
1428
+ >({
1429
+ name: 'reusing',
1430
+ execute: async ({ context }) => {
1431
+ await context.workflow.suspend({ key: 'reply' });
1432
+
1433
+ return context.workflow.suspend({ key: 'reply' });
1434
+ },
1435
+ });
1436
+ const compiled = compileWorkflow(
1437
+ {
1438
+ defs: createTaskDefs({
1439
+ step: { action: 'reusing', settings: noRetries },
1440
+ }),
1441
+ flow: [{ do: 'step' }],
1442
+ outputs: {},
1443
+ },
1444
+ { actions: { reusing } },
1445
+ );
1446
+ const runner = new WorkflowRunner(compiled);
1447
+ await runner.start({ inputData: {}, context: new TestContext({}) });
1448
+
1449
+ // Without the check, the second call would resolve with the first answer.
1450
+ const resumed = await runner.resume({ resumeData: 'first' });
1451
+
1452
+ expect(resumed.status).toBe('failed');
1453
+ if (resumed.status === 'failed') {
1454
+ expect((resumed.error as Error).message).toMatch(
1455
+ /key "reply" is used more than once in step "0:step"/,
1456
+ );
1457
+ }
1458
+ });
1459
+
1460
+ it('fails when a resumed body completes without reaching its suspension', async () => {
1461
+ let suspends = true;
1462
+ const optional = defineAction<
1463
+ Record<string, never>,
1464
+ unknown,
1465
+ TestContext,
1466
+ Settings
1467
+ >({
1468
+ name: 'optional',
1469
+ execute: async ({ context }) =>
1470
+ suspends ? context.workflow.suspend({ reason: 'maybe' }) : 'skipped',
1471
+ });
1472
+ const compiled = compileWorkflow(
1473
+ {
1474
+ defs: createTaskDefs({ step: { action: 'optional' } }),
1475
+ flow: [{ do: 'step' }],
1476
+ outputs: {},
1477
+ },
1478
+ { actions: { optional } },
1479
+ );
1480
+ const runner = new WorkflowRunner(compiled);
1481
+ await runner.start({ inputData: {}, context: new TestContext({}) });
1482
+ suspends = false;
1483
+
1484
+ const resumed = await runner.resume({ resumeData: {} });
1485
+
1486
+ expect(resumed.status).toBe('failed');
1487
+ if (resumed.status === 'failed') {
1488
+ expect(resumed.error).toBeInstanceOf(NonDeterministicWorkflowError);
1489
+ expect(resumed.snapshot.actions['0:step']).toMatchObject({
1490
+ status: 'failed',
1491
+ });
1492
+ }
1493
+ });
1494
+
1495
+ it('fails when a resumed body reaches a new suspension before its own', async () => {
1496
+ let asksFirst = false;
1497
+ const growing = defineAction<
1498
+ Record<string, never>,
1499
+ unknown,
1500
+ TestContext,
1501
+ Settings
1502
+ >({
1503
+ name: 'growing',
1504
+ execute: async ({ context }) => {
1505
+ if (asksFirst) {
1506
+ await context.workflow.suspend({ key: 'intro' });
1507
+ }
1508
+
1509
+ return context.workflow.suspend({ key: 'answer' });
1510
+ },
1511
+ });
1512
+ const compiled = compileWorkflow(
1513
+ {
1514
+ defs: createTaskDefs({
1515
+ step: { action: 'growing', settings: noRetries },
1516
+ }),
1517
+ flow: [{ do: 'step' }],
1518
+ outputs: {},
1519
+ },
1520
+ { actions: { growing } },
1521
+ );
1522
+ const runner = new WorkflowRunner(compiled);
1523
+ await runner.start({ inputData: {}, context: new TestContext({}) });
1524
+ asksFirst = true;
1525
+
1526
+ const resumed = await runner.resume({ resumeData: {} });
1527
+
1528
+ expect(resumed.status).toBe('failed');
1529
+ if (resumed.status === 'failed') {
1530
+ expect(resumed.error).toBeInstanceOf(NonDeterministicWorkflowError);
1531
+ expect((resumed.error as Error).message).toMatch(
1532
+ /reached unexpected suspend "key:intro" before expected "key:answer"/,
1533
+ );
1534
+ }
1535
+ });
1536
+
1537
+ it('fails when a resumed body reaches its suspension with a different reason', async () => {
1538
+ let reason = 'first';
1539
+ const drifting = defineAction<
1540
+ Record<string, never>,
1541
+ unknown,
1542
+ TestContext,
1543
+ Settings
1544
+ >({
1545
+ name: 'drifting',
1546
+ execute: async ({ context }) => {
1547
+ countRun('drifting');
1548
+
1549
+ return context.workflow.suspend({ reason });
1550
+ },
1551
+ });
1552
+ const compiled = compileWorkflow(
1553
+ {
1554
+ defs: createTaskDefs({
1555
+ step: {
1556
+ action: 'drifting',
1557
+ settings: {
1558
+ retries: {
1559
+ enabled: true,
1560
+ max_attempts: 3,
1561
+ backoff_ms: 0,
1562
+ max_delay_ms: 0,
1563
+ jitter: 0,
1564
+ multiplier: 1,
1565
+ },
1566
+ },
1567
+ },
1568
+ }),
1569
+ flow: [{ do: 'step' }],
1570
+ outputs: {},
1571
+ },
1572
+ { actions: { drifting } },
1573
+ );
1574
+ bodyRuns = {};
1575
+ const runner = new WorkflowRunner(compiled);
1576
+ await runner.start({ inputData: {}, context: new TestContext({}) });
1577
+ reason = 'second';
1578
+
1579
+ const resumed = await runner.resume({ resumeData: {} });
1580
+
1581
+ expect(resumed.status).toBe('failed');
1582
+ if (resumed.status === 'failed') {
1583
+ expect(resumed.error).toBeInstanceOf(NonDeterministicWorkflowError);
1584
+ }
1585
+ // A retry would replay the same body into the same mismatch.
1586
+ expect(bodyRuns).toEqual({ drifting: 2 });
1587
+ });
1588
+ });
1589
+
1590
+ describe('events and snapshots', () => {
1591
+ /** Record `<event> <step id>` for the step events of a context. */
1592
+ const recordStepEvents = (context: TestContext) => {
1593
+ const log: string[] = [];
1594
+
1595
+ (
1596
+ ['hook:step:start', 'hook:step:resumed', 'hook:step:cancelled'] as const
1597
+ ).forEach((event) =>
1598
+ context.eventEmitter.on(event, ({ step }) => {
1599
+ log.push(`${event} ${step.id}`);
1600
+ }),
1601
+ );
1602
+
1603
+ return log;
1604
+ };
1605
+ const race: WorkflowDefinition = {
1606
+ defs: createTaskDefs({
1607
+ ask_a: { action: 'ask', inputs: { label: 'a' } },
1608
+ ask_b: { action: 'ask', inputs: { label: 'b' } },
1609
+ }),
1610
+ flow: [
1611
+ {
1612
+ parallel: {
1613
+ strategy: 'wait_any',
1614
+ steps: [{ do: 'ask_a' }, { do: 'ask_b' }],
1615
+ },
1616
+ },
1617
+ ],
1618
+ outputs: { b: '=$output.ask_b.reply' },
1619
+ };
1620
+
1621
+ it('publishes every open wait when the run suspends', async () => {
1622
+ const context = new TestContext({});
1623
+ const suspended = jest.fn();
1624
+ context.eventEmitter.on('hook:workflow:suspended', suspended);
1625
+
1626
+ const started = await new WorkflowRunner(compile(race), {
1627
+ runId: 'run-1',
1628
+ }).start({ inputData: {}, context });
1629
+ if (started.status !== 'suspended') {
1630
+ throw new Error('Expected the run to suspend');
1631
+ }
1632
+
1633
+ expect(started.waits).toHaveLength(2);
1634
+ expect(suspended).toHaveBeenCalledTimes(1);
1635
+ expect(suspended).toHaveBeenCalledWith({
1636
+ runId: 'run-1',
1637
+ waits: started.waits,
1638
+ });
1639
+ });
1640
+
1641
+ it('resumes the resolved step and cancels the parked losers of wait_any', async () => {
1642
+ const context = new TestContext({});
1643
+ const log = recordStepEvents(context);
1644
+ const runner = new WorkflowRunner(compile(race));
1645
+ const started = await runner.start({ inputData: {}, context });
1646
+ if (started.status !== 'suspended') {
1647
+ throw new Error('Expected the run to suspend');
1648
+ }
1649
+ log.length = 0;
1650
+
1651
+ const resumed = await runner.resume({
1652
+ waitId: started.waits[1].waitId,
1653
+ resumeData: { reply: 'b' },
1654
+ });
1655
+
1656
+ expect(resumed.status).toBe('finished');
1657
+ expect(log).toContain('hook:step:resumed 0.parallel.1:ask_b');
1658
+ expect(log).toContain('hook:step:cancelled 0.parallel.0:ask_a');
1659
+ expect(log).not.toContain('hook:step:start 0.parallel.1:ask_b');
1660
+ expect(resumed.snapshot.actions).toMatchObject({
1661
+ '0.parallel.0:ask_a': { status: 'cancelled' },
1662
+ '0.parallel.1:ask_b': { status: 'completed' },
1663
+ });
1664
+ expect(runner.getStepLog()).toMatchObject({
1665
+ '0.parallel.0:ask_a': { status: 'cancelled' },
1666
+ '0.parallel.1:ask_b': { status: 'completed' },
1667
+ });
1668
+ });
1669
+
1670
+ it.each(['wait_any', 'wait_all'] as const)(
1671
+ 'drops the wait of a %s branch that suspends while it is cancelled',
1672
+ async (strategy) => {
1673
+ const late = defineAction<
1674
+ { ticks: number },
1675
+ unknown,
1676
+ TestContext,
1677
+ Settings
1678
+ >({
1679
+ name: 'late',
1680
+ inputSchema: z.object({ ticks: z.number() }),
1681
+ execute: async ({ input, context }) => {
1682
+ for (let tick = 0; tick < input.ticks; tick += 1) {
1683
+ await Promise.resolve();
1684
+ }
1685
+
1686
+ return context.workflow.suspend({ reason: 'late' });
1687
+ },
1688
+ });
1689
+ const boom = defineAction<
1690
+ Record<string, never>,
1691
+ never,
1692
+ TestContext,
1693
+ Settings
1694
+ >({
1695
+ name: 'boom',
1696
+ execute: async () => {
1697
+ throw new Error('boom');
1698
+ },
1699
+ });
1700
+ // wait_any: the sibling wins; wait_all: the sibling fails.
1701
+ const sibling =
1702
+ strategy === 'wait_any'
1703
+ ? { action: 'record', inputs: { label: 'quick' } }
1704
+ : { action: 'boom', settings: noRetries };
1705
+ const failures: string[] = [];
1706
+
1707
+ // Sweep how long the branch runs before suspending, so that its
1708
+ // suspension lands before, during and after the sibling settles.
1709
+ for (const lateFirst of [true, false]) {
1710
+ for (let ticks = 0; ticks <= 30; ticks += 1) {
1711
+ const context = new TestContext({});
1712
+ const opened: string[] = [];
1713
+ const dropped: string[] = [];
1714
+ context.eventEmitter.on('hook:step:suspended', ({ wait }) => {
1715
+ opened.push(wait.waitId);
1716
+ });
1717
+ context.eventEmitter.on('hook:step:cancelled', ({ wait }) => {
1718
+ if (wait) {
1719
+ dropped.push(wait.waitId);
1720
+ }
1721
+ });
1722
+ const steps = [{ do: 'late' }, { do: 'sibling' }];
1723
+ const runner = new WorkflowRunner(
1724
+ compileWorkflow(
1725
+ {
1726
+ defs: createTaskDefs({
1727
+ late: { action: 'late', inputs: { ticks } },
1728
+ sibling,
1729
+ }),
1730
+ flow: [
1731
+ {
1732
+ parallel: {
1733
+ strategy,
1734
+ steps: lateFirst ? steps : [...steps].reverse(),
1735
+ },
1736
+ },
1737
+ ],
1738
+ outputs: {},
1739
+ },
1740
+ { actions: { ...actions, late, boom } },
1741
+ ),
1742
+ );
1743
+ const result = await runner.start({ inputData: {}, context });
1744
+ const lateId = `0.parallel.${lateFirst ? 0 : 1}:late`;
1745
+ const statuses = [
1746
+ result.status,
1747
+ result.snapshot.actions[lateId]?.status,
1748
+ runner.getStepLog()[lateId]?.status,
1749
+ ];
1750
+
1751
+ if (
1752
+ result.status !==
1753
+ (strategy === 'wait_any' ? 'finished' : 'failed') ||
1754
+ statuses.includes('suspended') ||
1755
+ dropped.join() !== opened.join()
1756
+ ) {
1757
+ failures.push(
1758
+ `${ticks} ticks, late ${lateFirst ? 'first' : 'last'}: ` +
1759
+ `statuses ${statuses.join('/')}, opened [${opened}], dropped [${dropped}]`,
1760
+ );
1761
+ }
1762
+ }
1763
+ }
1764
+
1765
+ expect(failures).toEqual([]);
1766
+ },
1767
+ );
1768
+
1769
+ it('identifies the wait in every wait event, across processes', async () => {
1770
+ // What a host keeps per wait, e.g. a notification sent or an expiry timer.
1771
+ const tracked = new Map<string, string>();
1772
+ const startContext = new TestContext({});
1773
+ startContext.eventEmitter.on('hook:step:suspended', ({ wait }) => {
1774
+ tracked.set(wait.waitId, 'notified');
1775
+ });
1776
+ const started = await new WorkflowRunner(compile(race)).start({
1777
+ inputData: {},
1778
+ context: startContext,
1779
+ });
1780
+ if (started.status !== 'suspended') {
1781
+ throw new Error('Expected the run to suspend');
1782
+ }
1783
+ expect([...tracked.keys()]).toEqual(
1784
+ started.waits.map((wait) => wait.waitId),
1785
+ );
1786
+
1787
+ const stored = JSON.parse(JSON.stringify(started));
1788
+ const context = new TestContext({});
1789
+ const resumed = jest.fn();
1790
+ context.eventEmitter.on('hook:step:resumed', resumed);
1791
+ context.eventEmitter.on('hook:step:cancelled', ({ wait }) => {
1792
+ if (wait) {
1793
+ tracked.set(wait.waitId, 'dropped');
1794
+ }
1795
+ });
1796
+ const runner = WorkflowRunner.fromCheckpoint(compile(race), {
1797
+ checkpoint: stored.checkpoint,
1798
+ snapshot: stored.snapshot,
1799
+ context,
1800
+ });
1801
+ const [loser, winner] = stored.waits as WaitInfo[];
1802
+
1803
+ await expect(
1804
+ runner.resume({ waitId: winner.waitId, resumeData: { reply: 'b' } }),
1805
+ ).resolves.toMatchObject({ status: 'finished' });
1806
+ expect(resumed).toHaveBeenCalledWith(
1807
+ expect.objectContaining({ wait: winner, resumeData: { reply: 'b' } }),
1808
+ );
1809
+ expect(tracked).toEqual(
1810
+ new Map([
1811
+ [loser.waitId, 'dropped'],
1812
+ [winner.waitId, 'notified'],
1813
+ ]),
1814
+ );
1815
+ });
1816
+
1817
+ it('cancels a wait_any loser whose action is still running', async () => {
1818
+ const slow = defineAction<
1819
+ Record<string, never>,
1820
+ never,
1821
+ TestContext,
1822
+ Settings
1823
+ >({
1824
+ name: 'slow',
1825
+ execute: ({ signal }) =>
1826
+ new Promise<never>((_resolve, reject) => {
1827
+ signal.addEventListener('abort', () => reject(signal.reason), {
1828
+ once: true,
1829
+ });
1830
+ }),
1831
+ });
1832
+ const compiled = compileWorkflow(
1833
+ {
1834
+ defs: createTaskDefs({
1835
+ loser: { action: 'slow' },
1836
+ winner: { action: 'record', inputs: { label: 'quick' } },
1837
+ }),
1838
+ flow: [
1839
+ {
1840
+ parallel: {
1841
+ strategy: 'wait_any',
1842
+ steps: [{ do: 'loser' }, { do: 'winner' }],
1843
+ },
1844
+ },
1845
+ ],
1846
+ outputs: { label: '=$output.winner.label' },
1847
+ },
1848
+ { actions: { ...actions, slow } },
1849
+ );
1850
+ const context = new TestContext({});
1851
+ const log = recordStepEvents(context);
1852
+ const runner = new WorkflowRunner(compiled);
1853
+ const result = await runner.start({ inputData: {}, context });
1854
+
1855
+ expect(result).toMatchObject({
1856
+ status: 'finished',
1857
+ output: { label: 'quick' },
1858
+ });
1859
+ expect(result.snapshot.actions['0.parallel.0:loser']).toMatchObject({
1860
+ status: 'cancelled',
1861
+ });
1862
+ expect(runner.getStepLog()['0.parallel.0:loser']).toMatchObject({
1863
+ status: 'cancelled',
1864
+ });
1865
+ expect(log).toContain('hook:step:cancelled 0.parallel.0:loser');
1866
+ });
1867
+ });
1868
+
1869
+ describe('runner and context API', () => {
1870
+ it('exposes the checkpoint while suspended and clears it once finished', async () => {
1871
+ const runner = new WorkflowRunner(
1872
+ compile({
1873
+ defs: createTaskDefs({
1874
+ question: { action: 'ask', inputs: { label: 'q' } },
1875
+ }),
1876
+ flow: [{ do: 'question' }],
1877
+ outputs: {},
1878
+ }),
1879
+ );
1880
+ const started = await runner.start({
1881
+ inputData: {},
1882
+ context: new TestContext({}),
1883
+ });
1884
+ if (started.status !== 'suspended') {
1885
+ throw new Error('Expected the run to suspend');
1886
+ }
1887
+
1888
+ expect(runner.getCheckpoint()).toEqual(started.checkpoint);
1889
+
1890
+ await runner.resume({ resumeData: { reply: 'ok' } });
1891
+
1892
+ expect(runner.getCheckpoint()).toBeUndefined();
1893
+ });
1894
+
1895
+ it('resolves suspend() with the payload as the checkpoint records it, not as passed', async () => {
1896
+ const inspect = defineAction<
1897
+ Record<string, never>,
1898
+ { reply: unknown },
1899
+ TestContext,
1900
+ Settings
1901
+ >({
1902
+ name: 'inspect',
1903
+ outputSchema: z.object({ reply: z.unknown() }),
1904
+ execute: async ({ context }) => ({
1905
+ reply: await context.workflow.suspend(),
1906
+ }),
1907
+ });
1908
+ const runner = new WorkflowRunner(
1909
+ compileWorkflow(
1910
+ {
1911
+ defs: createTaskDefs({
1912
+ first: { action: 'inspect' },
1913
+ second: { action: 'inspect' },
1914
+ }),
1915
+ flow: [{ do: 'first' }, { do: 'second' }],
1916
+ outputs: { first: '=$output.first', second: '=$output.second' },
1917
+ },
1918
+ { actions: { inspect } },
1919
+ ),
1920
+ );
1921
+ await runner.start({ inputData: {}, context: new TestContext({}) });
1922
+
1923
+ await runner.resume({ resumeData: { at: new Date(0), note: undefined } });
1924
+ const finished = await runner.resume({});
1925
+
1926
+ expect(finished).toMatchObject({
1927
+ status: 'finished',
1928
+ output: { first: { reply: { at: '1970-01-01T00:00:00.000Z' } } },
1929
+ });
1930
+ // A resume without payload stays without payload.
1931
+ if (finished.status === 'finished') {
1932
+ expect(finished.output.second).toEqual({});
1933
+ }
1934
+ });
1935
+ });
1936
+
1937
+ describe('resume payloads', () => {
1938
+ const answerSchema = z.object({
1939
+ reply: z.string().refine((reply) => reply !== 'forbidden', 'forbidden'),
1940
+ count: z.coerce.number().default(1),
1941
+ });
1942
+ const answer = defineAction<
1943
+ Record<string, never>,
1944
+ { reply: string; count: number },
1945
+ TestContext,
1946
+ Settings
1947
+ >({
1948
+ name: 'answer',
1949
+ outputSchema: z.object({ reply: z.string(), count: z.number() }),
1950
+ execute: async ({ context }) => {
1951
+ countRun('answer');
1952
+
1953
+ return context.workflow.suspend({
1954
+ reason: 'awaiting_answer',
1955
+ accepts: answerSchema,
1956
+ });
1957
+ },
1958
+ });
1959
+ const knownOrders = new Set(['order-1']);
1960
+ const lookup = defineAction<
1961
+ Record<string, never>,
1962
+ { orderId: string },
1963
+ TestContext,
1964
+ Settings
1965
+ >({
1966
+ name: 'lookup',
1967
+ outputSchema: z.object({ orderId: z.string() }),
1968
+ execute: async ({ context }) => {
1969
+ countRun('lookup');
1970
+ const { orderId } = await context.workflow.suspend({
1971
+ reason: 'awaiting_order',
1972
+ accepts: z.object({ orderId: z.string() }),
1973
+ });
1974
+ if (!knownOrders.has(orderId)) {
1975
+ throw new WorkflowResumeRejectedError(`Unknown order "${orderId}".`);
1976
+ }
1977
+
1978
+ return { orderId };
1979
+ },
1980
+ });
1981
+ const payloadActions = { ...actions, answer, lookup };
1982
+ const compilePayload = (definition: WorkflowDefinition) =>
1983
+ compileWorkflow(definition, { actions: payloadActions });
1984
+ const single: WorkflowDefinition = {
1985
+ defs: createTaskDefs({ question: { action: 'answer' } }),
1986
+ flow: [{ do: 'question' }],
1987
+ outputs: { answer: '=$output.question' },
1988
+ };
1989
+ const retrying = {
1990
+ retries: {
1991
+ enabled: true,
1992
+ max_attempts: 3,
1993
+ backoff_ms: 0,
1994
+ max_delay_ms: 0,
1995
+ jitter: 0,
1996
+ multiplier: 1,
1997
+ },
1998
+ } as Settings;
1999
+ const suspendedResult = (result: WorkflowRunResult) => {
2000
+ if (result.status !== 'suspended') {
2001
+ throw new Error(`Expected the run to suspend, got ${result.status}`);
2002
+ }
2003
+
2004
+ return result;
2005
+ };
2006
+ /** Record `<event> <step id>` for resume and cancellation events. */
2007
+ const recordResumeEvents = (context: TestContext) => {
2008
+ const log: string[] = [];
2009
+
2010
+ (
2011
+ [
2012
+ 'hook:step:resumed',
2013
+ 'hook:step:resume_rejected',
2014
+ 'hook:step:cancelled',
2015
+ 'hook:workflow:resume_rejected',
2016
+ ] as const
2017
+ ).forEach((event) =>
2018
+ context.eventEmitter.on(event, (payload) => {
2019
+ const step = 'step' in payload ? payload.step : payload.wait.step;
2020
+ log.push(`${event} ${step.id}`);
2021
+ }),
2022
+ );
2023
+
2024
+ return log;
2025
+ };
2026
+
2027
+ beforeEach(() => {
2028
+ bodyRuns = {};
2029
+ });
2030
+
2031
+ it('refuses a payload the wait does not accept without running the body', async () => {
2032
+ const context = new TestContext({});
2033
+ const log = recordResumeEvents(context);
2034
+ const rejected = jest.fn();
2035
+ context.eventEmitter.on('hook:workflow:resume_rejected', rejected);
2036
+ const runner = new WorkflowRunner(compilePayload(single), {
2037
+ runId: 'run-1',
2038
+ });
2039
+ const started = suspendedResult(
2040
+ await runner.start({ inputData: {}, context }),
2041
+ );
2042
+ const [wait] = started.waits;
2043
+ expect(wait.accepts).toMatchObject({
2044
+ type: 'object',
2045
+ properties: { reply: { type: 'string' } },
2046
+ required: ['reply'],
2047
+ });
2048
+
2049
+ const refused = suspendedResult(
2050
+ await runner.resume({ waitId: wait.waitId, resumeData: { reply: 1 } }),
2051
+ );
2052
+
2053
+ expect(refused.rejection).toEqual({
2054
+ waitId: wait.waitId,
2055
+ error: expect.any(WorkflowResumeRejectedError),
2056
+ });
2057
+ expect(refused.rejection?.error.issues).toEqual([
2058
+ expect.stringMatching(/^reply: /),
2059
+ ]);
2060
+ expect(refused.checkpoint).toBe(started.checkpoint);
2061
+ expect(refused.waits).toEqual(started.waits);
2062
+ expect(runner.getStatus()).toBe('suspended');
2063
+ expect(bodyRuns).toEqual({ answer: 1 });
2064
+ expect(log).toEqual(['hook:workflow:resume_rejected 0:question']);
2065
+ expect(rejected).toHaveBeenCalledWith({
2066
+ runId: 'run-1',
2067
+ wait,
2068
+ resumeData: { reply: 1 },
2069
+ error: refused.rejection?.error,
2070
+ });
2071
+
2072
+ // The same waitId, e.g. from a link already sent, still works.
2073
+ await expect(
2074
+ runner.resume({
2075
+ waitId: wait.waitId,
2076
+ resumeData: { reply: 'ok', count: '3' },
2077
+ }),
2078
+ ).resolves.toMatchObject({
2079
+ status: 'finished',
2080
+ output: { answer: { reply: 'ok', count: 3 } },
2081
+ });
2082
+ });
2083
+
2084
+ it('lets a host refuse a payload before claiming the run', async () => {
2085
+ const started = suspendedResult(
2086
+ await new WorkflowRunner(compilePayload(single)).start({
2087
+ inputData: {},
2088
+ context: new TestContext({}),
2089
+ }),
2090
+ );
2091
+ const stored = JSON.parse(JSON.stringify(started.checkpoint));
2092
+ const [{ waitId }] = started.waits;
2093
+ const compiled = compilePayload(single);
2094
+ const refused = validateCheckpoint(compiled, stored, {
2095
+ waitId,
2096
+ resumeData: { count: 2 },
2097
+ });
2098
+ expect(refused.ok).toBe(false);
2099
+ if (!refused.ok) {
2100
+ expect(refused.error).toBeInstanceOf(WorkflowResumeRejectedError);
2101
+ expect(refused.error.message).toContain(`wait "${waitId}"`);
2102
+ }
2103
+
2104
+ // Without waitId the only open wait is checked.
2105
+ expect(
2106
+ validateCheckpoint(compiled, stored, { resumeData: undefined }).ok,
2107
+ ).toBe(false);
2108
+ expect(
2109
+ validateCheckpoint(compiled, stored, {
2110
+ waitId,
2111
+ resumeData: { reply: 'ok' },
2112
+ }).ok,
2113
+ ).toBe(true);
2114
+ // No payload given, nothing to check.
2115
+ expect(validateCheckpoint(compiled, stored, { waitId }).ok).toBe(true);
2116
+ });
2117
+
2118
+ it('picks the wait to check the way resume() does', async () => {
2119
+ const definition: WorkflowDefinition = {
2120
+ defs: createTaskDefs({
2121
+ left: { action: 'answer' },
2122
+ right: { action: 'answer' },
2123
+ }),
2124
+ flow: [
2125
+ {
2126
+ parallel: {
2127
+ strategy: 'wait_all',
2128
+ steps: [{ do: 'left' }, { do: 'right' }],
2129
+ },
2130
+ },
2131
+ ],
2132
+ outputs: {},
2133
+ };
2134
+ const started = suspendedResult(
2135
+ await new WorkflowRunner(compilePayload(definition)).start({
2136
+ inputData: {},
2137
+ context: new TestContext({}),
2138
+ }),
2139
+ );
2140
+ const stored = JSON.parse(JSON.stringify(started.checkpoint));
2141
+ const compiled = compilePayload(definition);
2142
+ const openWaitIds = started.waits.map((wait) => wait.waitId);
2143
+ // With two open waits and no waitId, neither can check the payload.
2144
+ const checked = validateCheckpoint(compiled, stored, {
2145
+ resumeData: { reply: 1 },
2146
+ });
2147
+ expect(checked.ok).toBe(false);
2148
+ if (!checked.ok) {
2149
+ expect(checked.error).toBeInstanceOf(WorkflowWaitAmbiguousError);
2150
+ expect((checked.error as WorkflowWaitAmbiguousError).openWaitIds).toEqual(
2151
+ openWaitIds,
2152
+ );
2153
+ }
2154
+ // Without a payload to check, the checkpoint alone is valid.
2155
+ expect(validateCheckpoint(compiled, stored).ok).toBe(true);
2156
+
2157
+ const runner = WorkflowRunner.fromCheckpoint(compiled, {
2158
+ checkpoint: stored,
2159
+ context: new TestContext({}),
2160
+ });
2161
+ const resumed = runner.resume({ resumeData: { reply: 'ok' } });
2162
+ await expect(resumed).rejects.toBeInstanceOf(WorkflowWaitAmbiguousError);
2163
+ await expect(resumed).rejects.toBeInstanceOf(WorkflowResumeError);
2164
+ expect(runner.getStatus()).toBe('suspended');
2165
+ });
2166
+
2167
+ it('resumes a wait whose payload is optional without a payload', async () => {
2168
+ const noteSchema = z.object({ note: z.string() });
2169
+ const notes = defineAction<
2170
+ Record<string, never>,
2171
+ { first: string; second: string },
2172
+ TestContext,
2173
+ Settings
2174
+ >({
2175
+ name: 'notes',
2176
+ outputSchema: z.object({ first: z.string(), second: z.string() }),
2177
+ execute: async ({ context }) => {
2178
+ countRun('notes');
2179
+ const first = await context.workflow.suspend({
2180
+ accepts: noteSchema.optional(),
2181
+ });
2182
+ const second = await context.workflow.suspend({
2183
+ key: 'second',
2184
+ accepts: noteSchema,
2185
+ });
2186
+
2187
+ return { first: first?.note ?? 'none', second: second.note };
2188
+ },
2189
+ });
2190
+ const definition: WorkflowDefinition = {
2191
+ defs: createTaskDefs({ step: { action: 'notes' } }),
2192
+ flow: [{ do: 'step' }],
2193
+ outputs: { first: '=$output.step.first', second: '=$output.step.second' },
2194
+ };
2195
+ const compiled = compileWorkflow(definition, { actions: { notes } });
2196
+ const persist = (result: WorkflowRunResult) =>
2197
+ JSON.parse(JSON.stringify(suspendedResult(result).checkpoint));
2198
+ const started = suspendedResult(
2199
+ await new WorkflowRunner(compiled).start({
2200
+ inputData: {},
2201
+ context: new TestContext({}),
2202
+ }),
2203
+ );
2204
+ expect(started.waits[0].payloadOptional).toBe(true);
2205
+
2206
+ const stored = persist(started);
2207
+ expect(
2208
+ validateCheckpoint(compiled, stored, { resumeData: undefined }).ok,
2209
+ ).toBe(true);
2210
+ expect(
2211
+ validateCheckpoint(compiled, stored, { resumeData: { note: 1 } }).ok,
2212
+ ).toBe(false);
2213
+
2214
+ // The absent payload survives the checkpoint's JSON round trip.
2215
+ const middle = await WorkflowRunner.fromCheckpoint(compiled, {
2216
+ checkpoint: stored,
2217
+ context: new TestContext({}),
2218
+ }).resume({});
2219
+ const next = persist(middle);
2220
+ expect(next.waits[0].payloadOptional).toBeUndefined();
2221
+ expect(
2222
+ validateCheckpoint(compiled, next, { resumeData: undefined }).ok,
2223
+ ).toBe(false);
2224
+
2225
+ const restored = WorkflowRunner.fromCheckpoint(compiled, {
2226
+ checkpoint: next,
2227
+ context: new TestContext({}),
2228
+ });
2229
+ await expect(
2230
+ restored.resume({ resumeData: { note: 'later' } }),
2231
+ ).resolves.toMatchObject({
2232
+ status: 'finished',
2233
+ output: { first: 'none', second: 'later' },
2234
+ });
2235
+ expect(bodyRuns).toEqual({ notes: 3 });
2236
+ });
2237
+
2238
+ it('fails a suspend whose accepts schema no JSON payload can match', async () => {
2239
+ const dated = defineAction<
2240
+ Record<string, never>,
2241
+ unknown,
2242
+ TestContext,
2243
+ Settings
2244
+ >({
2245
+ name: 'dated',
2246
+ execute: async ({ context }) => {
2247
+ countRun('dated');
2248
+
2249
+ return context.workflow.suspend({
2250
+ accepts: z.object({ at: z.date(), tags: z.set(z.string()) }),
2251
+ });
2252
+ },
2253
+ });
2254
+ const runner = new WorkflowRunner(
2255
+ compileWorkflow(
2256
+ {
2257
+ defs: createTaskDefs({
2258
+ step: { action: 'dated', settings: noRetries },
2259
+ }),
2260
+ flow: [{ do: 'step' }],
2261
+ outputs: {},
2262
+ },
2263
+ { actions: { dated } },
2264
+ ),
2265
+ );
2266
+ const result = await runner.start({
2267
+ inputData: {},
2268
+ context: new TestContext({}),
2269
+ });
2270
+
2271
+ // Opening the wait would leave a run nothing can ever resume.
2272
+ expect(result.status).toBe('failed');
2273
+ if (result.status === 'failed') {
2274
+ expect((result.error as Error).message).toMatch(
2275
+ /in step "0:step" can never match a JSON payload: at \(date\), tags \(set\)\./,
2276
+ );
2277
+ }
2278
+ });
2279
+
2280
+ it('parses the JSON form of a payload through its accepts schema', async () => {
2281
+ const dated = defineAction<
2282
+ Record<string, never>,
2283
+ { at: string; isDate: boolean },
2284
+ TestContext,
2285
+ Settings
2286
+ >({
2287
+ name: 'dated',
2288
+ outputSchema: z.object({ at: z.string(), isDate: z.boolean() }),
2289
+ execute: async ({ context }) => {
2290
+ const { at } = await context.workflow.suspend({
2291
+ accepts: z.object({ at: z.coerce.date() }),
2292
+ });
2293
+
2294
+ return { at: at.toISOString(), isDate: at instanceof Date };
2295
+ },
2296
+ });
2297
+ const runner = new WorkflowRunner(
2298
+ compileWorkflow(
2299
+ {
2300
+ defs: createTaskDefs({ step: { action: 'dated' } }),
2301
+ flow: [{ do: 'step' }],
2302
+ outputs: { step: '=$output.step' },
2303
+ },
2304
+ { actions: { dated } },
2305
+ ),
2306
+ );
2307
+ await runner.start({ inputData: {}, context: new TestContext({}) });
2308
+
2309
+ await expect(
2310
+ runner.resume({ resumeData: { at: new Date(0) } }),
2311
+ ).resolves.toMatchObject({
2312
+ status: 'finished',
2313
+ output: { step: { at: '1970-01-01T00:00:00.000Z', isDate: true } },
2314
+ });
2315
+ });
2316
+
2317
+ it('keeps the wait open when the body refuses the payload', async () => {
2318
+ const started = suspendedResult(
2319
+ await new WorkflowRunner(compilePayload(single)).start({
2320
+ inputData: {},
2321
+ context: new TestContext({}),
2322
+ }),
2323
+ );
2324
+ const stored = JSON.parse(
2325
+ JSON.stringify({
2326
+ checkpoint: started.checkpoint,
2327
+ snapshot: started.snapshot,
2328
+ }),
2329
+ );
2330
+ const context = new TestContext({});
2331
+ const log = recordResumeEvents(context);
2332
+ const stepRejected = jest.fn();
2333
+ context.eventEmitter.on('hook:step:resume_rejected', stepRejected);
2334
+ const runner = WorkflowRunner.fromCheckpoint(compilePayload(single), {
2335
+ checkpoint: stored.checkpoint,
2336
+ snapshot: stored.snapshot,
2337
+ context,
2338
+ });
2339
+ const stepLog = runner.getStepLog();
2340
+ // Passes the JSON Schema; only the refinement in the body refuses it.
2341
+ const refused = suspendedResult(
2342
+ await runner.resume({ resumeData: { reply: 'forbidden' } }),
2343
+ );
2344
+
2345
+ expect(refused.rejection?.error).toBeInstanceOf(
2346
+ WorkflowResumeRejectedError,
2347
+ );
2348
+ expect(refused.rejection?.error.message).toMatch(
2349
+ /^Resume payload for step "0:question" was rejected: reply: forbidden/,
2350
+ );
2351
+ // Everything the runner reports is left as it was before the resume.
2352
+ expect(refused.checkpoint).toEqual(stored.checkpoint);
2353
+ expect(refused.snapshot).toEqual(stored.snapshot);
2354
+ expect(runner.getStepLog()).toEqual(stepLog);
2355
+ expect(bodyRuns).toEqual({ answer: 2 });
2356
+ expect(log).toEqual([
2357
+ 'hook:step:resumed 0:question',
2358
+ 'hook:step:resume_rejected 0:question',
2359
+ 'hook:workflow:resume_rejected 0:question',
2360
+ ]);
2361
+ expect(stepRejected).toHaveBeenCalledWith(
2362
+ expect.objectContaining({ wait: stored.checkpoint.waits[0] }),
2363
+ );
2364
+
2365
+ await expect(
2366
+ runner.resume({ resumeData: { reply: 'fine' } }),
2367
+ ).resolves.toMatchObject({
2368
+ status: 'finished',
2369
+ output: { answer: { reply: 'fine', count: 1 } },
2370
+ });
2371
+ });
2372
+
2373
+ it('lets an action refuse a payload itself, without retrying it', async () => {
2374
+ const definition: WorkflowDefinition = {
2375
+ defs: createTaskDefs({
2376
+ order: { action: 'lookup', settings: retrying },
2377
+ }),
2378
+ flow: [{ do: 'order' }],
2379
+ outputs: { orderId: '=$output.order.orderId' },
2380
+ };
2381
+ const runner = new WorkflowRunner(compilePayload(definition));
2382
+ const started = suspendedResult(
2383
+ await runner.start({ inputData: {}, context: new TestContext({}) }),
2384
+ );
2385
+ const refused = suspendedResult(
2386
+ await runner.resume({ resumeData: { orderId: 'order-404' } }),
2387
+ );
2388
+
2389
+ expect(refused.rejection?.error.message).toBe('Unknown order "order-404".');
2390
+ expect(refused.waits).toEqual(started.waits);
2391
+ expect(bodyRuns).toEqual({ lookup: 2 });
2392
+
2393
+ await expect(
2394
+ runner.resume({ resumeData: { orderId: 'order-1' } }),
2395
+ ).resolves.toMatchObject({
2396
+ status: 'finished',
2397
+ output: { orderId: 'order-1' },
2398
+ });
2399
+ });
2400
+
2401
+ it('recognises a refusal thrown by another copy of the package', async () => {
2402
+ // What the class looks like when an extension imports the other (CJS or
2403
+ // ESM) build: same name, different constructor.
2404
+ class ForeignResumeRejectedError extends Error {
2405
+ constructor(message: string) {
2406
+ super(message);
2407
+ this.name = 'WorkflowResumeRejectedError';
2408
+ }
2409
+ }
2410
+ const foreign = defineAction<
2411
+ Record<string, never>,
2412
+ never,
2413
+ TestContext,
2414
+ Settings
2415
+ >({
2416
+ name: 'foreign',
2417
+ execute: async ({ context }) => {
2418
+ countRun('foreign');
2419
+ await context.workflow.suspend();
2420
+
2421
+ throw new ForeignResumeRejectedError('Unknown order.');
2422
+ },
2423
+ });
2424
+ const runner = new WorkflowRunner(
2425
+ compileWorkflow(
2426
+ {
2427
+ defs: createTaskDefs({
2428
+ step: { action: 'foreign', settings: retrying },
2429
+ }),
2430
+ flow: [{ do: 'step' }],
2431
+ outputs: {},
2432
+ },
2433
+ { actions: { foreign } },
2434
+ ),
2435
+ );
2436
+ const started = suspendedResult(
2437
+ await runner.start({ inputData: {}, context: new TestContext({}) }),
2438
+ );
2439
+ const refused = suspendedResult(await runner.resume({ resumeData: {} }));
2440
+
2441
+ expect(refused.rejection?.error.message).toBe('Unknown order.');
2442
+ expect(refused.waits).toEqual(started.waits);
2443
+ expect(bodyRuns).toEqual({ foreign: 2 });
2444
+ });
2445
+
2446
+ it('refuses a payload JSON cannot store', async () => {
2447
+ const runner = new WorkflowRunner(compilePayload(single));
2448
+ await runner.start({ inputData: {}, context: new TestContext({}) });
2449
+
2450
+ const refused = suspendedResult(
2451
+ await runner.resume({ resumeData: { reply: BigInt(1) } }),
2452
+ );
2453
+
2454
+ expect(refused.rejection?.error.message).toMatch(
2455
+ /cannot be stored as JSON/,
2456
+ );
2457
+ expect(bodyRuns).toEqual({ answer: 1 });
2458
+ });
2459
+
2460
+ it.each(['wait_all', 'wait_any'] as const)(
2461
+ 'keeps every wait of a %s block open when one payload is refused',
2462
+ async (strategy) => {
2463
+ const definition: WorkflowDefinition = {
2464
+ defs: createTaskDefs({
2465
+ left: { action: 'answer' },
2466
+ right: { action: 'answer' },
2467
+ }),
2468
+ flow: [
2469
+ {
2470
+ parallel: { strategy, steps: [{ do: 'left' }, { do: 'right' }] },
2471
+ },
2472
+ ],
2473
+ outputs: { left: '=$output.left.reply', right: '=$output.right.reply' },
2474
+ };
2475
+ const context = new TestContext({});
2476
+ const log = recordResumeEvents(context);
2477
+ const runner = new WorkflowRunner(compilePayload(definition));
2478
+ const started = suspendedResult(
2479
+ await runner.start({ inputData: {}, context }),
2480
+ );
2481
+ const stepLog = runner.getStepLog();
2482
+ const [left, right] = started.waits;
2483
+ const refused = suspendedResult(
2484
+ await runner.resume({
2485
+ waitId: left.waitId,
2486
+ resumeData: { reply: 'forbidden' },
2487
+ }),
2488
+ );
2489
+
2490
+ expect(refused.rejection?.waitId).toBe(left.waitId);
2491
+ expect(refused.waits).toEqual(started.waits);
2492
+ expect(refused.snapshot).toEqual(started.snapshot);
2493
+ expect(runner.getStepLog()).toEqual(stepLog);
2494
+ expect(log).not.toContainEqual(expect.stringMatching(/cancelled/));
2495
+
2496
+ const next = await runner.resume({
2497
+ waitId: right.waitId,
2498
+ resumeData: { reply: 'R' },
2499
+ });
2500
+ if (strategy === 'wait_any') {
2501
+ expect(next).toMatchObject({ status: 'finished' });
2502
+
2503
+ return;
2504
+ }
2505
+
2506
+ expect(suspendedResult(next).waits).toEqual([left]);
2507
+ await expect(
2508
+ runner.resume({ waitId: left.waitId, resumeData: { reply: 'L' } }),
2509
+ ).resolves.toMatchObject({
2510
+ status: 'finished',
2511
+ output: { left: 'L', right: 'R' },
2512
+ });
2513
+ },
2514
+ );
2515
+
2516
+ it('keeps the loop position of a refused wait', async () => {
2517
+ const definition: WorkflowDefinition = {
2518
+ defs: createTaskDefs({ question: { action: 'answer' } }),
2519
+ flow: [
2520
+ {
2521
+ loop: {
2522
+ type: 'for_each',
2523
+ name: 'items',
2524
+ for_each: { item: 'item', in: '=["a", "b"]' },
2525
+ accumulate: {
2526
+ as: 'replies',
2527
+ initial: [],
2528
+ merge: '=$append($accumulator, [$output.question.reply])',
2529
+ },
2530
+ steps: [{ do: 'question' }],
2531
+ },
2532
+ },
2533
+ ],
2534
+ outputs: { replies: '=$output.items.replies' },
2535
+ };
2536
+ const resumeDurably = async (
2537
+ result: WorkflowRunResult,
2538
+ resumeData: unknown,
2539
+ ) => {
2540
+ const stored = JSON.parse(JSON.stringify(suspendedResult(result)));
2541
+
2542
+ return WorkflowRunner.fromCheckpoint(compilePayload(definition), {
2543
+ checkpoint: stored.checkpoint,
2544
+ snapshot: stored.snapshot,
2545
+ context: new TestContext({}),
2546
+ }).resume({ resumeData });
2547
+ };
2548
+ const started = await new WorkflowRunner(compilePayload(definition)).start({
2549
+ inputData: {},
2550
+ context: new TestContext({}),
2551
+ });
2552
+ const first = suspendedResult(started).waits[0].waitId;
2553
+ expect(first).toMatch(/\[0\]@/);
2554
+
2555
+ const refused = suspendedResult(
2556
+ await resumeDurably(started, { reply: 'forbidden' }),
2557
+ );
2558
+ expect(refused.rejection).toBeDefined();
2559
+ expect(refused.waits[0].waitId).toBe(first);
2560
+
2561
+ const second = await resumeDurably(refused, { reply: 'a' });
2562
+ expect(suspendedResult(second).waits[0].waitId).toMatch(/\[1\]@/);
2563
+ await expect(resumeDurably(second, { reply: 'b' })).resolves.toMatchObject({
2564
+ status: 'finished',
2565
+ output: { replies: ['a', 'b'] },
2566
+ });
2567
+ });
2568
+ });