@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
@@ -4,18 +4,25 @@
4
4
  * Full terms: see LICENSE.md.
5
5
  */
6
6
 
7
- import type { BaseWorkflowContext, WorkflowRuntimeControl } from '../context';
8
7
  import {
8
+ collectWaits,
9
+ type ParallelBranchFrame,
10
+ type ParallelFrame,
11
+ type StepFrame,
12
+ } from '../checkpoint';
13
+ import type { BaseWorkflowContext } from '../context';
14
+ import {
15
+ createLinkedAbortController,
9
16
  getAbortReason,
10
- ParallelSuspensionError,
11
17
  throwIfAborted,
12
18
  WorkflowCancellationError,
13
19
  } from '../errors';
20
+ import type { RunnerRuntimeControl } from '../runner-runtime-control';
21
+ import { cloneRecord, cloneValue, isRecord } from '../utils/clone';
14
22
  import type {
15
23
  CompiledStep,
16
24
  ExecutionState,
17
25
  ParallelStep,
18
- Suspension,
19
26
  } from '../workflow-types';
20
27
 
21
28
  import { markStepsCancelled } from './skip-helpers';
@@ -23,6 +30,12 @@ import type { StepExecutorEnv } from './types';
23
30
 
24
31
  type BranchResult =
25
32
  | { status: 'fulfilled'; index: number; outputDelta: Record<string, unknown> }
33
+ | {
34
+ status: 'suspended';
35
+ index: number;
36
+ outputDelta: Record<string, unknown>;
37
+ frame: StepFrame;
38
+ }
26
39
  | { status: 'failed'; index: number; error: unknown }
27
40
  | { status: 'cancelled'; index: number; error: Error };
28
41
 
@@ -42,27 +55,51 @@ type TrackedOutput = {
42
55
  /**
43
56
  * Execute a set of child steps concurrently and resolve according to the configured strategy.
44
57
  *
58
+ * A branch may suspend. The block then waits until every branch has settled
59
+ * (fulfilled, suspended, or failed) before suspending itself, so a sibling that
60
+ * was still running finishes exactly once instead of being re-run on resume.
61
+ *
45
62
  * @param env Executor environment providing helpers and workflow context.
46
63
  * @param step The parallel step definition including strategy and children.
47
64
  * @param state Mutable workflow execution state.
48
65
  * @param path Path tokens locating this parallel block in the workflow.
49
- * @returns Always undefined; suspensions are rejected inside parallel blocks.
66
+ * @param frame Frame returned when the block previously suspended: fulfilled
67
+ * branches are not launched again, parked ones stay parked unless this pass
68
+ * resolves one of their waits, and those resume from their frame.
69
+ * @returns A frame if any branch is left suspended, otherwise void.
50
70
  */
51
71
  export async function executeParallel(
52
72
  env: StepExecutorEnv,
53
73
  step: ParallelStep,
54
74
  state: ExecutionState,
55
75
  path: Array<number | string>,
56
- ): Promise<Suspension | void> {
76
+ frame?: ParallelFrame,
77
+ ): Promise<ParallelFrame | void> {
57
78
  if (step.steps.length === 0) {
58
79
  return undefined;
59
80
  }
60
81
 
61
82
  throwIfAborted(env.signal);
62
83
 
84
+ const outcomes = new Map<number, BranchResult>();
85
+ const launches: Array<{
86
+ child: CompiledStep;
87
+ index: number;
88
+ recorded?: ParallelBranchFrame;
89
+ }> = [];
90
+ step.steps.forEach((child, index) => {
91
+ const recorded = frame?.branches[index];
92
+ const kept = recorded ? keepRecordedBranch(env, index, recorded) : null;
93
+ if (kept) {
94
+ outcomes.set(index, kept);
95
+ } else {
96
+ launches.push({ child, index, recorded });
97
+ }
98
+ });
99
+
63
100
  const baseOutput = cloneRecord(state.output);
64
101
  const baseContextState = cloneRecord(env.context.state);
65
- const branches = step.steps.map((child, index) =>
102
+ const branches = launches.map(({ child, index, recorded }) =>
66
103
  launchBranch({
67
104
  env,
68
105
  child,
@@ -71,23 +108,55 @@ export async function executeParallel(
71
108
  parentState: state,
72
109
  baseOutput,
73
110
  baseContextState,
111
+ recorded,
74
112
  }),
75
113
  );
76
114
 
77
115
  if (step.strategy === 'wait_any') {
78
- return executeWaitAny(env, branches, state);
116
+ return executeWaitAny(env, step, branches, outcomes, state);
79
117
  }
80
118
 
81
- return executeWaitAll(env, branches, state);
119
+ return executeWaitAll(env, step, branches, outcomes, state);
120
+ }
121
+
122
+ /**
123
+ * Settle a recorded branch that has nothing to run in this pass: a fulfilled
124
+ * branch never runs again, and a parked branch stays exactly as it was
125
+ * unless this pass resolves one of its waits.
126
+ *
127
+ * @returns Its outcome, or null when the branch has to be launched.
128
+ */
129
+ function keepRecordedBranch(
130
+ env: StepExecutorEnv,
131
+ index: number,
132
+ recorded: ParallelBranchFrame,
133
+ ): BranchResult | null {
134
+ if (recorded.status === 'fulfilled') {
135
+ return { status: 'fulfilled', index, outputDelta: recorded.outputDelta };
136
+ }
137
+
138
+ const resolved = collectWaits(recorded.child).some((wait) =>
139
+ env.resolutions.has(wait.waitId),
140
+ );
141
+
142
+ return resolved
143
+ ? null
144
+ : {
145
+ status: 'suspended',
146
+ index,
147
+ outputDelta: recorded.outputDelta,
148
+ frame: recorded.child,
149
+ };
82
150
  }
83
151
 
84
152
  async function executeWaitAll(
85
153
  env: StepExecutorEnv,
154
+ step: ParallelStep,
86
155
  branches: BranchHandle[],
156
+ outcomes: Map<number, BranchResult>,
87
157
  state: ExecutionState,
88
- ): Promise<void> {
158
+ ): Promise<ParallelFrame | void> {
89
159
  const pending = new Set(branches);
90
- const outcomes = new Map<number, BranchResult>();
91
160
 
92
161
  while (pending.size > 0) {
93
162
  const { branch, result } = await raceNext(pending);
@@ -95,55 +164,78 @@ async function executeWaitAll(
95
164
  outcomes.set(result.index, result);
96
165
 
97
166
  if (result.status === 'failed' || result.status === 'cancelled') {
98
- cancelBranches(
99
- env,
100
- pending,
101
- result.error,
102
- 'Parallel branch execution was cancelled.',
103
- );
104
- await settleBranches(branches);
167
+ await abandonBranches(env, branches, pending, outcomes, result.error);
105
168
  throw result.error;
106
169
  }
107
170
  }
108
171
 
172
+ if (hasSuspendedBranch(outcomes)) {
173
+ return buildParallelFrame(step, outcomes);
174
+ }
175
+
109
176
  mergeBranchOutputs(state, outcomes);
110
177
  }
111
178
 
112
179
  async function executeWaitAny(
113
180
  env: StepExecutorEnv,
181
+ step: ParallelStep,
114
182
  branches: BranchHandle[],
183
+ outcomes: Map<number, BranchResult>,
115
184
  state: ExecutionState,
116
- ): Promise<void> {
185
+ ): Promise<ParallelFrame | void> {
117
186
  const pending = new Set(branches);
118
- const outcomes = new Map<number, BranchResult>();
119
187
 
120
188
  while (pending.size > 0) {
121
189
  const { branch, result } = await raceNext(pending);
122
190
  pending.delete(branch);
123
191
  outcomes.set(result.index, result);
124
192
 
193
+ if (result.status === 'suspended') {
194
+ continue;
195
+ }
196
+
125
197
  if (result.status === 'fulfilled') {
126
- cancelBranches(
198
+ // Parked losers will never be resumed; drop their waits with the race.
199
+ await abandonBranches(
127
200
  env,
201
+ branches,
128
202
  pending,
203
+ outcomes,
129
204
  new WorkflowCancellationError('Parallel wait_any winner selected.'),
130
205
  'Parallel wait_any branch lost the race.',
131
206
  );
132
- await settleBranches(branches);
133
207
  mergeBranchOutputs(state, new Map([[result.index, result]]));
134
208
 
135
- return;
209
+ return undefined;
136
210
  }
137
211
 
138
- cancelBranches(
139
- env,
140
- pending,
141
- result.error,
142
- 'Parallel branch execution was cancelled.',
143
- );
144
- await settleBranches(branches);
212
+ await abandonBranches(env, branches, pending, outcomes, result.error);
145
213
  throw result.error;
146
214
  }
215
+
216
+ // Every branch settled without a winner, so all of them are suspended.
217
+ return buildParallelFrame(step, outcomes);
218
+ }
219
+
220
+ /**
221
+ * Give up on the block: cancel the branches still running, let every branch
222
+ * settle, then drop the waits of every branch left suspended, including one
223
+ * that suspended while it was being cancelled.
224
+ */
225
+ async function abandonBranches(
226
+ env: StepExecutorEnv,
227
+ branches: BranchHandle[],
228
+ pending: Set<BranchHandle>,
229
+ outcomes: Map<number, BranchResult>,
230
+ reason: unknown,
231
+ snapshotReason = 'Parallel branch execution was cancelled.',
232
+ ): Promise<void> {
233
+ cancelBranches(env, pending, reason, snapshotReason);
234
+ for (const result of await settleBranches(branches)) {
235
+ outcomes.set(result.index, result);
236
+ }
237
+
238
+ cancelSuspendedBranches(env, outcomes, reason);
147
239
  }
148
240
 
149
241
  function launchBranch({
@@ -154,6 +246,7 @@ function launchBranch({
154
246
  parentState,
155
247
  baseOutput,
156
248
  baseContextState,
249
+ recorded,
157
250
  }: {
158
251
  env: StepExecutorEnv;
159
252
  child: CompiledStep;
@@ -162,9 +255,10 @@ function launchBranch({
162
255
  parentState: ExecutionState;
163
256
  baseOutput: Record<string, unknown>;
164
257
  baseContextState: Record<string, unknown>;
258
+ recorded?: ParallelBranchFrame;
165
259
  }): BranchHandle {
166
- const controller = createBranchController(env.signal);
167
- const trackedOutput = createTrackedOutput(baseOutput);
260
+ const { controller, unlink } = createLinkedAbortController(env.signal);
261
+ const trackedOutput = createTrackedOutput(baseOutput, recorded?.outputDelta);
168
262
  const branchState: ExecutionState = {
169
263
  input: parentState.input,
170
264
  output: trackedOutput.output,
@@ -172,14 +266,16 @@ function launchBranch({
172
266
  accumulator: cloneValue(parentState.accumulator),
173
267
  iterationStack: [...parentState.iterationStack],
174
268
  };
269
+ const branchRuntime = env.runtime.fork();
175
270
  const branchContext = createParallelBranchContext(
176
271
  env.context,
177
272
  cloneRecord(baseContextState),
273
+ branchRuntime,
178
274
  );
179
275
  const branchEnv = env.fork({
180
276
  context: branchContext,
181
277
  signal: controller.signal,
182
- setCurrentStep: () => undefined,
278
+ runtime: branchRuntime,
183
279
  });
184
280
  const childPath = [...path, 'parallel', index];
185
281
  const promise = runBranch(
@@ -189,7 +285,8 @@ function launchBranch({
189
285
  childPath,
190
286
  trackedOutput,
191
287
  index,
192
- );
288
+ recorded?.status === 'suspended' ? recorded.child : undefined,
289
+ ).finally(unlink);
193
290
 
194
291
  return {
195
292
  index,
@@ -207,13 +304,27 @@ async function runBranch(
207
304
  childPath: Array<number | string>,
208
305
  trackedOutput: TrackedOutput,
209
306
  index: number,
307
+ frame?: StepFrame,
210
308
  ): Promise<BranchResult> {
211
309
  try {
212
310
  throwIfAborted(env.signal);
213
311
 
214
- const suspension = await env.executeStep(child, branchState, childPath);
215
- if (suspension) {
216
- throw new ParallelSuspensionError();
312
+ const suspended = await env.executeStep(
313
+ child,
314
+ branchState,
315
+ childPath,
316
+ frame,
317
+ );
318
+
319
+ // A branch can suspend while it is being cancelled: its wait was opened
320
+ // all the same, so the block needs its frame to drop it.
321
+ if (suspended) {
322
+ return {
323
+ status: 'suspended',
324
+ index,
325
+ outputDelta: trackedOutput.getDelta(),
326
+ frame: suspended,
327
+ };
217
328
  }
218
329
 
219
330
  throwIfAborted(env.signal);
@@ -242,8 +353,11 @@ async function raceNext(
242
353
  );
243
354
  }
244
355
 
245
- async function settleBranches(branches: BranchHandle[]): Promise<void> {
246
- await Promise.all(branches.map((branch) => branch.promise.catch(() => null)));
356
+ /** Wait for every branch to settle; `runBranch` never rejects. */
357
+ async function settleBranches(
358
+ branches: BranchHandle[],
359
+ ): Promise<BranchResult[]> {
360
+ return Promise.all(branches.map((branch) => branch.promise));
247
361
  }
248
362
 
249
363
  function cancelBranches(
@@ -270,6 +384,77 @@ function cancelBranches(
270
384
  }
271
385
  }
272
386
 
387
+ /**
388
+ * Mark the parked waits of suspended branches cancelled once the block can
389
+ * no longer resume them.
390
+ */
391
+ function cancelSuspendedBranches(
392
+ env: StepExecutorEnv,
393
+ outcomes: Map<number, BranchResult>,
394
+ reason: unknown,
395
+ ): void {
396
+ const message =
397
+ reason instanceof Error ? reason.message : 'Parallel branch was cancelled.';
398
+
399
+ for (const outcome of outcomes.values()) {
400
+ if (outcome.status !== 'suspended') {
401
+ continue;
402
+ }
403
+
404
+ for (const wait of collectWaits(outcome.frame)) {
405
+ const stepExecution = env.recordStepExecution(wait.step, {
406
+ status: 'cancelled',
407
+ endedAt: Date.now(),
408
+ reason: message,
409
+ error: { message },
410
+ });
411
+ env.markSnapshot(wait.step, 'cancelled', message);
412
+ env.emit('hook:step:cancelled', {
413
+ runId: env.runId,
414
+ step: wait.step,
415
+ stepExecution,
416
+ error: reason instanceof Error ? reason : new Error(message),
417
+ wait,
418
+ });
419
+ }
420
+ }
421
+ }
422
+
423
+ function hasSuspendedBranch(outcomes: Map<number, BranchResult>): boolean {
424
+ return [...outcomes.values()].some(
425
+ (outcome) => outcome.status === 'suspended',
426
+ );
427
+ }
428
+
429
+ function buildParallelFrame(
430
+ step: ParallelStep,
431
+ outcomes: Map<number, BranchResult>,
432
+ ): ParallelFrame {
433
+ return {
434
+ kind: 'parallel',
435
+ stepId: step.id,
436
+ branches: step.steps.map((_, index): ParallelBranchFrame => {
437
+ const outcome = outcomes.get(index);
438
+
439
+ if (outcome?.status === 'fulfilled') {
440
+ return { status: 'fulfilled', outputDelta: outcome.outputDelta };
441
+ }
442
+
443
+ if (outcome?.status === 'suspended') {
444
+ return {
445
+ status: 'suspended',
446
+ outputDelta: outcome.outputDelta,
447
+ child: outcome.frame,
448
+ };
449
+ }
450
+
451
+ throw new Error(
452
+ `Parallel branch ${index} of "${step.id}" did not settle before suspending.`,
453
+ );
454
+ }),
455
+ };
456
+ }
457
+
273
458
  function mergeBranchOutputs(
274
459
  state: ExecutionState,
275
460
  outcomes: Map<number, BranchResult>,
@@ -287,29 +472,20 @@ function mergeBranchOutputs(
287
472
  }
288
473
  }
289
474
 
290
- function createBranchController(parentSignal: AbortSignal): AbortController {
291
- const controller = new AbortController();
292
-
293
- if (parentSignal.aborted) {
294
- controller.abort(getAbortReason(parentSignal));
295
-
296
- return controller;
297
- }
298
-
299
- parentSignal.addEventListener(
300
- 'abort',
301
- () => controller.abort(getAbortReason(parentSignal)),
302
- { once: true },
303
- );
304
-
305
- return controller;
306
- }
307
-
475
+ /**
476
+ * Give a branch its own copy of the parent output that remembers which keys
477
+ * the branch wrote. A resumed branch starts from the delta it had recorded.
478
+ */
308
479
  function createTrackedOutput(
309
480
  baseOutput: Record<string, unknown>,
481
+ recordedDelta?: Record<string, unknown>,
310
482
  ): TrackedOutput {
311
- const writtenKeys = new Set<string>();
483
+ const writtenKeys = new Set<string>(Object.keys(recordedDelta ?? {}));
312
484
  const target = cloneRecord(baseOutput);
485
+ if (recordedDelta) {
486
+ Object.assign(target, cloneRecord(recordedDelta));
487
+ }
488
+
313
489
  const output = new Proxy(target, {
314
490
  set(record, property, value) {
315
491
  if (typeof property === 'string') {
@@ -338,42 +514,16 @@ function createTrackedOutput(
338
514
  };
339
515
  }
340
516
 
341
- class ParallelWorkflowRuntimeControl implements WorkflowRuntimeControl {
342
- constructor(private readonly getParent: () => WorkflowRuntimeControl) {}
343
-
344
- get status() {
345
- return this.getParent().status;
346
- }
347
-
348
- get resumeData() {
349
- return this.getParent().resumeData;
350
- }
351
-
352
- suspend<T = unknown>(): Promise<T> {
353
- return Promise.reject(new ParallelSuspensionError());
354
- }
355
-
356
- hasRecordedResult(): boolean {
357
- // Suspension is not supported inside parallel blocks, so no resume
358
- // result can ever be recorded for them.
359
- return false;
360
- }
361
-
362
- resume(data?: unknown): void {
363
- this.getParent().resume(data);
364
- }
365
-
366
- getSnapshot() {
367
- return this.getParent().getSnapshot();
368
- }
369
- }
370
-
517
+ /**
518
+ * Isolate a branch's context state and route `context.workflow` to the
519
+ * branch's own runtime scope, so its steps can suspend independently.
520
+ */
371
521
  function createParallelBranchContext(
372
522
  context: BaseWorkflowContext,
373
523
  branchState: Record<string, unknown>,
524
+ runtime: RunnerRuntimeControl,
374
525
  ): BaseWorkflowContext {
375
526
  let state = branchState;
376
- const workflow = new ParallelWorkflowRuntimeControl(() => context.workflow);
377
527
 
378
528
  return new Proxy(context, {
379
529
  get(target, property, receiver) {
@@ -382,7 +532,11 @@ function createParallelBranchContext(
382
532
  }
383
533
 
384
534
  if (property === 'workflow') {
385
- return workflow;
535
+ return runtime;
536
+ }
537
+
538
+ if (property === 'getWorkflowRuntime') {
539
+ return () => runtime;
386
540
  }
387
541
 
388
542
  if (property === 'snapshot') {
@@ -406,39 +560,3 @@ function createParallelBranchContext(
406
560
  },
407
561
  });
408
562
  }
409
-
410
- function cloneRecord(value: Record<string, unknown>): Record<string, unknown> {
411
- return cloneValue(value) as Record<string, unknown>;
412
- }
413
-
414
- function cloneValue<T>(value: T): T {
415
- if (value === undefined || value === null) {
416
- return value;
417
- }
418
-
419
- if (typeof structuredClone === 'function') {
420
- try {
421
- return structuredClone(value);
422
- } catch {
423
- // Fall through to JSON clone below.
424
- }
425
- }
426
-
427
- try {
428
- return JSON.parse(JSON.stringify(value)) as T;
429
- } catch {
430
- if (Array.isArray(value)) {
431
- return [...value] as T;
432
- }
433
-
434
- if (isRecord(value)) {
435
- return { ...value } as T;
436
- }
437
-
438
- return value;
439
- }
440
- }
441
-
442
- function isRecord(value: unknown): value is Record<string, unknown> {
443
- return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
444
- }