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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (134) hide show
  1. package/README.md +67 -15
  2. package/dist/cjs/action/abstract-action.js +13 -1
  3. package/dist/cjs/checkpoint.js +301 -0
  4. package/dist/cjs/context.js +11 -27
  5. package/dist/cjs/dsl.types.js +3 -0
  6. package/dist/cjs/errors.js +116 -9
  7. package/dist/cjs/index.js +15 -6
  8. package/dist/cjs/resume-payload.js +257 -0
  9. package/dist/cjs/runner-runtime-control.js +181 -306
  10. package/dist/cjs/step-executors/conditional-executor.js +27 -29
  11. package/dist/cjs/step-executors/loop-executor.js +53 -62
  12. package/dist/cjs/step-executors/parallel-executor.js +169 -102
  13. package/dist/cjs/step-executors/task-executor.js +180 -96
  14. package/dist/cjs/utils/clone.js +73 -0
  15. package/dist/cjs/workflow-fingerprint.js +138 -0
  16. package/dist/cjs/workflow-runner.js +220 -155
  17. package/dist/cjs/workflow.js +24 -12
  18. package/dist/esm/action/abstract-action.js +14 -2
  19. package/dist/esm/checkpoint.js +293 -0
  20. package/dist/esm/context.js +11 -27
  21. package/dist/esm/dsl.types.js +3 -0
  22. package/dist/esm/errors.js +105 -6
  23. package/dist/esm/index.js +3 -3
  24. package/dist/esm/resume-payload.js +250 -0
  25. package/dist/esm/runner-runtime-control.js +179 -303
  26. package/dist/esm/step-executors/conditional-executor.js +27 -29
  27. package/dist/esm/step-executors/loop-executor.js +53 -62
  28. package/dist/esm/step-executors/parallel-executor.js +165 -98
  29. package/dist/esm/step-executors/task-executor.js +181 -97
  30. package/dist/esm/utils/clone.js +67 -0
  31. package/dist/esm/workflow-fingerprint.js +134 -0
  32. package/dist/esm/workflow-runner.js +220 -155
  33. package/dist/esm/workflow.js +24 -12
  34. package/dist/types/action/abstract-action.d.ts.map +1 -1
  35. package/dist/types/action/action.types.d.ts +0 -14
  36. package/dist/types/action/action.types.d.ts.map +1 -1
  37. package/dist/types/checkpoint.d.ts +188 -0
  38. package/dist/types/checkpoint.d.ts.map +1 -0
  39. package/dist/types/context.d.ts +45 -11
  40. package/dist/types/context.d.ts.map +1 -1
  41. package/dist/types/dsl.types.d.ts.map +1 -1
  42. package/dist/types/errors.d.ts +77 -3
  43. package/dist/types/errors.d.ts.map +1 -1
  44. package/dist/types/index.d.ts +6 -7
  45. package/dist/types/index.d.ts.map +1 -1
  46. package/dist/types/resume-payload.d.ts +69 -0
  47. package/dist/types/resume-payload.d.ts.map +1 -0
  48. package/dist/types/runner-runtime-control.d.ts +63 -51
  49. package/dist/types/runner-runtime-control.d.ts.map +1 -1
  50. package/dist/types/step-executors/conditional-executor.d.ts +6 -3
  51. package/dist/types/step-executors/conditional-executor.d.ts.map +1 -1
  52. package/dist/types/step-executors/loop-executor.d.ts +6 -4
  53. package/dist/types/step-executors/loop-executor.d.ts.map +1 -1
  54. package/dist/types/step-executors/parallel-executor.d.ts +11 -3
  55. package/dist/types/step-executors/parallel-executor.d.ts.map +1 -1
  56. package/dist/types/step-executors/task-executor.d.ts +11 -4
  57. package/dist/types/step-executors/task-executor.d.ts.map +1 -1
  58. package/dist/types/step-executors/types.d.ts +21 -13
  59. package/dist/types/step-executors/types.d.ts.map +1 -1
  60. package/dist/types/utils/clone.d.ts +33 -0
  61. package/dist/types/utils/clone.d.ts.map +1 -0
  62. package/dist/types/workflow-event-emitter.d.ts +29 -5
  63. package/dist/types/workflow-event-emitter.d.ts.map +1 -1
  64. package/dist/types/workflow-fingerprint.d.ts +14 -0
  65. package/dist/types/workflow-fingerprint.d.ts.map +1 -0
  66. package/dist/types/workflow-runner.d.ts +83 -41
  67. package/dist/types/workflow-runner.d.ts.map +1 -1
  68. package/dist/types/workflow-types.d.ts +25 -54
  69. package/dist/types/workflow-types.d.ts.map +1 -1
  70. package/dist/types/workflow.d.ts +24 -9
  71. package/dist/types/workflow.d.ts.map +1 -1
  72. package/examples/defs-bindings-agent/bindings.ts +1 -1
  73. package/examples/defs-bindings-agent/workflow.ts +3 -2
  74. package/examples/full/actions/await-user-input.ts +3 -2
  75. package/examples/full/actions/call-llm.ts +18 -18
  76. package/examples/full/actions/create-ticket.ts +1 -2
  77. package/examples/full/actions/decision-router.ts +6 -2
  78. package/examples/full/actions/get-calendar-events.ts +1 -2
  79. package/examples/full/actions/get-user-profile.ts +1 -2
  80. package/examples/full/actions/query-memory.ts +1 -2
  81. package/examples/full/actions/search-web.ts +1 -2
  82. package/examples/full/actions/send-email.ts +3 -2
  83. package/examples/full/workflow.ts +3 -2
  84. package/examples/loop/actions/await-reply.ts +2 -7
  85. package/examples/loop/workflow.ts +4 -2
  86. package/examples/suspend-resume/actions/wait-for-user.ts +11 -9
  87. package/examples/suspend-resume/workflow.ts +51 -11
  88. package/package.json +3 -3
  89. package/src/__tests__/checkpoint.test.ts +2568 -0
  90. package/src/__tests__/resume-payload.test.ts +245 -0
  91. package/src/__tests__/runner-runtime-control.test.ts +265 -0
  92. package/src/__tests__/workflow-fingerprint.test.ts +165 -0
  93. package/src/__tests__/workflow-runner.test.ts +167 -144
  94. package/src/__tests__/workflow.test.ts +97 -6
  95. package/src/action/abstract-action.ts +21 -2
  96. package/src/action/action.types.ts +0 -12
  97. package/src/checkpoint.ts +561 -0
  98. package/src/context.ts +51 -41
  99. package/src/dsl.types.ts +3 -0
  100. package/src/errors.ts +161 -8
  101. package/src/index.ts +33 -14
  102. package/src/resume-payload.ts +326 -0
  103. package/src/runner-runtime-control.ts +222 -456
  104. package/src/step-executors/conditional-executor.test.ts +77 -46
  105. package/src/step-executors/conditional-executor.ts +47 -40
  106. package/src/step-executors/loop-executor.test.ts +106 -92
  107. package/src/step-executors/loop-executor.ts +84 -101
  108. package/src/step-executors/parallel-executor.test.ts +300 -89
  109. package/src/step-executors/parallel-executor.ts +243 -125
  110. package/src/step-executors/task-executor.test.ts +321 -51
  111. package/src/step-executors/task-executor.ts +232 -145
  112. package/src/step-executors/types.ts +23 -22
  113. package/src/utils/clone.ts +75 -0
  114. package/src/workflow-event-emitter.ts +32 -6
  115. package/src/workflow-fingerprint.ts +159 -0
  116. package/src/workflow-runner.ts +325 -209
  117. package/src/workflow-types.ts +25 -56
  118. package/src/workflow.ts +41 -34
  119. package/dist/cjs/step-executors/suspension-continuation.js +0 -27
  120. package/dist/cjs/suspension-rebuilder.js +0 -265
  121. package/dist/cjs/utils/deferred.js +0 -17
  122. package/dist/esm/step-executors/suspension-continuation.js +0 -24
  123. package/dist/esm/suspension-rebuilder.js +0 -260
  124. package/dist/esm/utils/deferred.js +0 -14
  125. package/dist/types/step-executors/suspension-continuation.d.ts +0 -10
  126. package/dist/types/step-executors/suspension-continuation.d.ts.map +0 -1
  127. package/dist/types/suspension-rebuilder.d.ts +0 -67
  128. package/dist/types/suspension-rebuilder.d.ts.map +0 -1
  129. package/dist/types/utils/deferred.d.ts +0 -7
  130. package/dist/types/utils/deferred.d.ts.map +0 -1
  131. package/src/__tests__/suspension-rebuilder.test.ts +0 -404
  132. package/src/step-executors/suspension-continuation.ts +0 -31
  133. package/src/suspension-rebuilder.ts +0 -446
  134. package/src/utils/deferred.ts +0 -23
@@ -4,9 +4,9 @@
4
4
  * Full terms: see LICENSE.md.
5
5
  */
6
6
 
7
+ import type { ParallelFrame, StepFrame, TaskFrame } from '../checkpoint';
7
8
  import { BaseWorkflowContext } from '../context';
8
- import { ParallelSuspensionError } from '../errors';
9
- import type { RuntimeSuspensionRequest } from '../runner-runtime-control';
9
+ import { RunnerRuntimeControl } from '../runner-runtime-control';
10
10
  import {
11
11
  StepType,
12
12
  type EventEmitterLike,
@@ -16,7 +16,6 @@ import type {
16
16
  CompiledStep,
17
17
  ExecutionState,
18
18
  ParallelStep,
19
- Suspension,
20
19
  } from '../workflow-types';
21
20
 
22
21
  import { executeParallel } from './parallel-executor';
@@ -30,6 +29,24 @@ class TestContext extends BaseWorkflowContext {
30
29
  }
31
30
  }
32
31
 
32
+ /** What a branch sees when the parallel executor runs its child step. */
33
+ type ChildBranch = {
34
+ signal: AbortSignal;
35
+ frame?: StepFrame;
36
+ context: BaseWorkflowContext;
37
+ };
38
+
39
+ type ChildRunner = (
40
+ child: CompiledStep,
41
+ branchState: ExecutionState,
42
+ path: Array<number | string>,
43
+ branch: ChildBranch,
44
+ ) => Promise<StepFrame | void>;
45
+
46
+ type TestEnv = StepExecutorEnv & {
47
+ runChild: jest.Mock<ReturnType<ChildRunner>, Parameters<ChildRunner>>;
48
+ };
49
+
33
50
  const createState = (): ExecutionState => ({
34
51
  input: {},
35
52
  output: {},
@@ -41,7 +58,7 @@ const createChild = (id: string): CompiledStep => ({
41
58
  label: id,
42
59
  taskName: `task_${id}`,
43
60
  });
44
- const createEnv = (): StepExecutorEnv => {
61
+ const createEnv = (): TestEnv => {
45
62
  const compiled = {
46
63
  definition: {} as any,
47
64
  tasks: {},
@@ -54,41 +71,31 @@ const createEnv = (): StepExecutorEnv => {
54
71
  context: new TestContext(),
55
72
  signal: new AbortController().signal,
56
73
  runId: 'run-1',
74
+ runtime: new RunnerRuntimeControl(),
75
+ resolutions: new Map<string, unknown>(),
76
+ rejectResume: jest.fn(),
57
77
  buildInstanceStepInfo: jest.fn((step: CompiledStep): StepInfo => {
58
78
  return { id: step.id, name: step.label, type: step.type };
59
79
  }),
60
80
  markSnapshot: jest.fn(),
61
81
  recordStepExecution: jest.fn(),
62
82
  emit: jest.fn(),
63
- setCurrentStep: jest.fn(),
64
- waitForStepSuspension: jest
65
- .fn()
66
- .mockImplementation(
67
- () => new Promise<RuntimeSuspensionRequest>(() => undefined),
68
- ),
69
- clearStepSuspensions: jest.fn(),
70
- primeStepResumeData: jest.fn(),
71
83
  captureTaskOutput: jest.fn(),
72
84
  executeFlow: jest.fn(),
73
85
  executeStep: jest.fn(),
74
86
  fork: jest.fn(),
75
- } as StepExecutorEnv;
87
+ runChild: jest.fn(),
88
+ } as TestEnv;
76
89
 
77
90
  env.fork = jest.fn((overrides) => {
78
91
  const forked = { ...env, ...overrides } as StepExecutorEnv;
79
92
 
80
- forked.executeStep = jest.fn((step, state, path) =>
81
- (env.executeStep as jest.Mock)(step, state, path, forked.signal),
82
- );
83
- forked.executeFlow = jest.fn((steps, state, path, startIndex) =>
84
- (env.executeFlow as jest.Mock)(
85
- steps,
86
- state,
87
- path,
88
- startIndex,
89
- forked.signal,
90
- ),
91
- );
93
+ forked.executeStep = (step, state, path, frame) =>
94
+ env.runChild(step, state, path, {
95
+ signal: forked.signal,
96
+ frame,
97
+ context: forked.context,
98
+ });
92
99
 
93
100
  return forked;
94
101
  });
@@ -102,6 +109,23 @@ const createStep = (strategy: ParallelStep['strategy']): ParallelStep => ({
102
109
  strategy,
103
110
  steps: [createChild('a'), createChild('b')],
104
111
  });
112
+ const createTaskFrame = (id: string): TaskFrame => ({
113
+ kind: 'task',
114
+ stepId: id,
115
+ inputs: {},
116
+ awaitResults: {},
117
+ wait: {
118
+ waitId: `${id}@index:1`,
119
+ step: { id, name: id, type: StepType.Task },
120
+ suspendKey: 'index:1',
121
+ },
122
+ });
123
+ const rejectOnAbort = (signal: AbortSignal) =>
124
+ new Promise<void>((_resolve, reject) => {
125
+ signal.addEventListener('abort', () => reject(signal.reason), {
126
+ once: true,
127
+ });
128
+ });
105
129
  const flushPromises = async () => {
106
130
  await Promise.resolve();
107
131
  await Promise.resolve();
@@ -115,7 +139,7 @@ describe('executeParallel', () => {
115
139
  const started: string[] = [];
116
140
  const resolvers: Array<() => void> = [];
117
141
 
118
- env.executeStep = jest.fn((child: CompiledStep) => {
142
+ env.runChild.mockImplementation((child) => {
119
143
  started.push(child.id);
120
144
 
121
145
  return new Promise<void>((resolve) => {
@@ -127,7 +151,7 @@ describe('executeParallel', () => {
127
151
  await flushPromises();
128
152
 
129
153
  expect(started).toEqual(['a', 'b']);
130
- expect(env.executeStep).toHaveBeenCalledTimes(2);
154
+ expect(env.runChild).toHaveBeenCalledTimes(2);
131
155
 
132
156
  resolvers.forEach((resolve) => resolve());
133
157
  await expect(resultPromise).resolves.toBeUndefined();
@@ -139,12 +163,10 @@ describe('executeParallel', () => {
139
163
  const step = createStep('wait_all');
140
164
 
141
165
  state.output.existing = 'keep';
142
- env.executeStep = jest.fn(
143
- async (child: CompiledStep, branchState: ExecutionState) => {
144
- branchState.output.shared = child.id;
145
- branchState.output[`${child.id}_only`] = true;
146
- },
147
- );
166
+ env.runChild.mockImplementation(async (child, branchState) => {
167
+ branchState.output.shared = child.id;
168
+ branchState.output[`${child.id}_only`] = true;
169
+ });
148
170
 
149
171
  await executeParallel(env, step, state, []);
150
172
 
@@ -162,24 +184,13 @@ describe('executeParallel', () => {
162
184
  const step = createStep('wait_all');
163
185
  const failure = new Error('branch failed');
164
186
 
165
- env.executeStep = jest.fn(
166
- (
167
- child: CompiledStep,
168
- _branchState: ExecutionState,
169
- _path: Array<number | string>,
170
- signal?: AbortSignal,
171
- ) => {
172
- if (child.id === 'a') {
173
- return Promise.reject(failure);
174
- }
187
+ env.runChild.mockImplementation((child, _branchState, _path, branch) => {
188
+ if (child.id === 'a') {
189
+ return Promise.reject(failure);
190
+ }
175
191
 
176
- return new Promise<void>((_resolve, reject) => {
177
- signal?.addEventListener('abort', () => reject(signal.reason), {
178
- once: true,
179
- });
180
- });
181
- },
182
- );
192
+ return rejectOnAbort(branch.signal);
193
+ });
183
194
 
184
195
  await expect(executeParallel(env, step, state, [])).rejects.toThrow(
185
196
  'branch failed',
@@ -197,13 +208,8 @@ describe('executeParallel', () => {
197
208
  const step = createStep('wait_any');
198
209
  const started: string[] = [];
199
210
 
200
- env.executeStep = jest.fn(
201
- async (
202
- child: CompiledStep,
203
- branchState: ExecutionState,
204
- _path: Array<number | string>,
205
- signal?: AbortSignal,
206
- ) => {
211
+ env.runChild.mockImplementation(
212
+ async (child, branchState, _path, branch) => {
207
213
  started.push(child.id);
208
214
  if (child.id === 'b') {
209
215
  branchState.output.winner = child.id;
@@ -211,11 +217,7 @@ describe('executeParallel', () => {
211
217
  return undefined;
212
218
  }
213
219
 
214
- return new Promise<void>((_resolve, reject) => {
215
- signal?.addEventListener('abort', () => reject(signal.reason), {
216
- once: true,
217
- });
218
- });
220
+ return rejectOnAbort(branch.signal);
219
221
  },
220
222
  );
221
223
 
@@ -235,26 +237,15 @@ describe('executeParallel', () => {
235
237
  const state = createState();
236
238
  const step = createStep('wait_any');
237
239
 
238
- env.executeStep = jest.fn(
239
- (
240
- child: CompiledStep,
241
- branchState: ExecutionState,
242
- _path: Array<number | string>,
243
- signal?: AbortSignal,
244
- ) => {
245
- if (child.id === 'a') {
246
- return Promise.reject(new Error('no winner'));
247
- }
240
+ env.runChild.mockImplementation((child, branchState, _path, branch) => {
241
+ if (child.id === 'a') {
242
+ return Promise.reject(new Error('no winner'));
243
+ }
248
244
 
249
- branchState.output.loser = true;
245
+ branchState.output.loser = true;
250
246
 
251
- return new Promise<void>((_resolve, reject) => {
252
- signal?.addEventListener('abort', () => reject(signal.reason), {
253
- once: true,
254
- });
255
- });
256
- },
257
- );
247
+ return rejectOnAbort(branch.signal);
248
+ });
258
249
 
259
250
  await expect(executeParallel(env, step, state, [])).rejects.toThrow(
260
251
  'no winner',
@@ -267,25 +258,245 @@ describe('executeParallel', () => {
267
258
  );
268
259
  });
269
260
 
270
- it('rejects suspensions returned by children', async () => {
261
+ it('lets running siblings settle before suspending, recording every branch', async () => {
271
262
  const env = createEnv();
272
263
  const state = createState();
273
264
  const step = createStep('wait_all');
274
- const innerSuspension: Suspension = {
275
- step: { id: 'a', name: 'a', type: StepType.Task } as StepInfo,
276
- continue: jest.fn().mockResolvedValue(undefined),
265
+ const order: string[] = [];
266
+
267
+ env.runChild.mockImplementation(async (child, branchState) => {
268
+ if (child.id === 'a') {
269
+ branchState.output.a_partial = 1;
270
+ order.push('a suspended');
271
+
272
+ return createTaskFrame('a');
273
+ }
274
+
275
+ await new Promise((resolve) => setTimeout(resolve, 5));
276
+ branchState.output.b_done = true;
277
+ order.push('b completed');
278
+
279
+ return undefined;
280
+ });
281
+
282
+ const frame = await executeParallel(env, step, state, []);
283
+
284
+ expect(order).toEqual(['a suspended', 'b completed']);
285
+ expect(frame).toEqual({
286
+ kind: 'parallel',
287
+ stepId: 'parallel',
288
+ branches: [
289
+ {
290
+ status: 'suspended',
291
+ outputDelta: { a_partial: 1 },
292
+ child: createTaskFrame('a'),
293
+ },
294
+ { status: 'fulfilled', outputDelta: { b_done: true } },
295
+ ],
296
+ });
297
+ // Nothing is merged into the parent until the whole block completes.
298
+ expect(state.output).toEqual({});
299
+ });
300
+
301
+ it('resumes only suspended branches and merges recorded siblings', async () => {
302
+ const env = createEnv();
303
+ const state = createState();
304
+ const step = createStep('wait_all');
305
+ const frame: ParallelFrame = {
306
+ kind: 'parallel',
307
+ stepId: 'parallel',
308
+ branches: [
309
+ {
310
+ status: 'suspended',
311
+ outputDelta: { a_partial: 1 },
312
+ child: createTaskFrame('a'),
313
+ },
314
+ { status: 'fulfilled', outputDelta: { b_done: true } },
315
+ ],
277
316
  };
317
+ const seen: Array<{ id: string; frame?: StepFrame; output: unknown }> = [];
318
+ env.resolutions = new Map([[createTaskFrame('a').wait.waitId, 'reply']]);
319
+
320
+ env.runChild.mockImplementation(
321
+ async (child, branchState, _path, branch) => {
322
+ seen.push({
323
+ id: child.id,
324
+ frame: branch.frame,
325
+ output: { ...branchState.output },
326
+ });
327
+ branchState.output.a_done = true;
328
+
329
+ return undefined;
330
+ },
331
+ );
332
+
333
+ const result = await executeParallel(env, step, state, [], frame);
334
+
335
+ expect(result).toBeUndefined();
336
+ expect(seen).toEqual([
337
+ { id: 'a', frame: createTaskFrame('a'), output: { a_partial: 1 } },
338
+ ]);
339
+ expect(state.output).toEqual({ a_partial: 1, a_done: true, b_done: true });
340
+ });
341
+
342
+ it('gives each branch its own runtime scope', async () => {
343
+ const env = createEnv();
344
+ const step = createStep('wait_all');
345
+ const scopes: unknown[] = [];
346
+
347
+ env.runChild.mockImplementation(async (_child, _state, _path, branch) => {
348
+ scopes.push(branch.context.workflow);
349
+ expect(branch.context.getWorkflowRuntime()).toBe(branch.context.workflow);
350
+ });
351
+
352
+ await executeParallel(env, step, createState(), []);
278
353
 
279
- env.executeStep = jest.fn((child: CompiledStep) => {
354
+ expect(scopes).toHaveLength(2);
355
+ expect(scopes[0]).toBeInstanceOf(RunnerRuntimeControl);
356
+ expect(scopes[0]).not.toBe(scopes[1]);
357
+ expect(scopes[0]).not.toBe(env.runtime);
358
+ });
359
+
360
+ it('wait_any suspends when every branch is parked', async () => {
361
+ const env = createEnv();
362
+ const step = createStep('wait_any');
363
+
364
+ env.runChild.mockImplementation(async (child) => createTaskFrame(child.id));
365
+
366
+ await expect(
367
+ executeParallel(env, step, createState(), []),
368
+ ).resolves.toEqual({
369
+ kind: 'parallel',
370
+ stepId: 'parallel',
371
+ branches: [
372
+ { status: 'suspended', outputDelta: {}, child: createTaskFrame('a') },
373
+ { status: 'suspended', outputDelta: {}, child: createTaskFrame('b') },
374
+ ],
375
+ });
376
+ });
377
+
378
+ it('wait_any drops the waits of parked losers once a branch wins', async () => {
379
+ const env = createEnv();
380
+ const state = createState();
381
+ const step = createStep('wait_any');
382
+
383
+ env.runChild.mockImplementation(async (child, branchState) => {
280
384
  if (child.id === 'a') {
281
- return Promise.resolve(innerSuspension);
385
+ return createTaskFrame('a');
282
386
  }
283
387
 
284
- return Promise.resolve(undefined);
388
+ await flushPromises();
389
+ branchState.output.winner = child.id;
390
+
391
+ return undefined;
392
+ });
393
+
394
+ await expect(
395
+ executeParallel(env, step, state, []),
396
+ ).resolves.toBeUndefined();
397
+ expect(state.output).toEqual({ winner: 'b' });
398
+ expect(env.markSnapshot).toHaveBeenCalledWith(
399
+ createTaskFrame('a').wait.step,
400
+ 'cancelled',
401
+ 'Parallel wait_any winner selected.',
402
+ );
403
+ expect(env.recordStepExecution).toHaveBeenCalledWith(
404
+ createTaskFrame('a').wait.step,
405
+ expect.objectContaining({
406
+ status: 'cancelled',
407
+ reason: 'Parallel wait_any winner selected.',
408
+ }),
409
+ );
410
+ expect(env.emit).toHaveBeenCalledWith('hook:step:cancelled', {
411
+ runId: 'run-1',
412
+ step: createTaskFrame('a').wait.step,
413
+ error: expect.objectContaining({
414
+ message: 'Parallel wait_any winner selected.',
415
+ }),
416
+ wait: createTaskFrame('a').wait,
417
+ });
418
+ });
419
+
420
+ it('drops parked waits when a resumed branch fails', async () => {
421
+ const env = createEnv();
422
+ const state = createState();
423
+ const step = createStep('wait_all');
424
+ const failure = new Error('resumed branch failed');
425
+ const frame: ParallelFrame = {
426
+ kind: 'parallel',
427
+ stepId: 'parallel',
428
+ branches: [
429
+ { status: 'suspended', outputDelta: {}, child: createTaskFrame('a') },
430
+ { status: 'suspended', outputDelta: {}, child: createTaskFrame('b') },
431
+ ],
432
+ };
433
+
434
+ // Branch b's wait is not resolved by this pass: it stays parked.
435
+ env.resolutions = new Map([[createTaskFrame('a').wait.waitId, 'reply']]);
436
+ env.runChild.mockImplementation(async () => {
437
+ await flushPromises();
438
+ throw failure;
285
439
  });
286
440
 
287
- await expect(executeParallel(env, step, state, [])).rejects.toBeInstanceOf(
288
- ParallelSuspensionError,
441
+ await expect(executeParallel(env, step, state, [], frame)).rejects.toBe(
442
+ failure,
289
443
  );
444
+ expect(env.runChild).toHaveBeenCalledTimes(1);
445
+ expect(env.markSnapshot).toHaveBeenCalledWith(
446
+ createTaskFrame('b').wait.step,
447
+ 'cancelled',
448
+ 'resumed branch failed',
449
+ );
450
+ expect(env.recordStepExecution).toHaveBeenCalledWith(
451
+ createTaskFrame('b').wait.step,
452
+ expect.objectContaining({
453
+ status: 'cancelled',
454
+ error: { message: 'resumed branch failed' },
455
+ }),
456
+ );
457
+ expect(env.emit).toHaveBeenCalledWith(
458
+ 'hook:step:cancelled',
459
+ expect.objectContaining({
460
+ step: createTaskFrame('b').wait.step,
461
+ wait: createTaskFrame('b').wait,
462
+ }),
463
+ );
464
+ expect(state.output).toEqual({});
465
+ });
466
+
467
+ it('keeps branches parked without launching them when this pass does not resolve their wait', async () => {
468
+ const env = createEnv();
469
+ const step = createStep('wait_all');
470
+ const frame: ParallelFrame = {
471
+ kind: 'parallel',
472
+ stepId: 'parallel',
473
+ branches: [
474
+ {
475
+ status: 'suspended',
476
+ outputDelta: { a_partial: 1 },
477
+ child: createTaskFrame('a'),
478
+ },
479
+ { status: 'suspended', outputDelta: {}, child: createTaskFrame('b') },
480
+ ],
481
+ };
482
+ env.resolutions = new Map([[createTaskFrame('b').wait.waitId, 'reply']]);
483
+ env.runChild.mockImplementation(async (_child, branchState) => {
484
+ branchState.output.b_done = true;
485
+ });
486
+
487
+ const result = await executeParallel(env, step, createState(), [], frame);
488
+
489
+ // Only the resolved branch gets a scope, a context and a copy of $output.
490
+ expect(env.fork).toHaveBeenCalledTimes(1);
491
+ expect(env.runChild).toHaveBeenCalledTimes(1);
492
+ expect(env.runChild.mock.calls[0][0].id).toBe('b');
493
+ expect(result).toEqual({
494
+ kind: 'parallel',
495
+ stepId: 'parallel',
496
+ branches: [
497
+ frame.branches[0],
498
+ { status: 'fulfilled', outputDelta: { b_done: true } },
499
+ ],
500
+ });
290
501
  });
291
502
  });