@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
@@ -9,7 +9,6 @@ exports.executeLoop = executeLoop;
9
9
  exports.updateAccumulator = updateAccumulator;
10
10
  exports.shouldStopLoop = shouldStopLoop;
11
11
  const workflow_values_1 = require("../workflow-values");
12
- const suspension_continuation_1 = require("./suspension-continuation");
13
12
  /**
14
13
  * Execute a loop step by iterating over input items and executing child steps.
15
14
  *
@@ -17,56 +16,43 @@ const suspension_continuation_1 = require("./suspension-continuation");
17
16
  * @param step The loop step configuration.
18
17
  * @param state Mutable workflow execution state.
19
18
  * @param path Path tokens locating this loop within the workflow.
20
- * @param startIndex Index to resume iteration from when continuing.
21
- * @returns A suspension if a child step pauses execution, otherwise void.
19
+ * @param frame Frame returned when an iteration previously suspended; the
20
+ * loop resumes that iteration with the items and accumulator it recorded.
21
+ * @returns A frame if an iteration suspends, otherwise void.
22
22
  */
23
- async function executeLoop(env, step, state, path, startIndex = 0) {
23
+ async function executeLoop(env, step, state, path, frame) {
24
24
  if (step.loopType === 'for_each') {
25
- return executeForEachLoop(env, step, state, path, startIndex);
25
+ return executeForEachLoop(env, step, state, path, frame);
26
26
  }
27
- return executeWhileLoop(env, step, state, path, startIndex);
27
+ return executeWhileLoop(env, step, state, path, frame);
28
28
  }
29
- async function executeForEachLoop(env, step, state, path, startIndex) {
30
- const scope = {
31
- input: state.input,
32
- context: env.context.state,
33
- output: state.output,
34
- iteration: state.iteration,
35
- accumulator: state.accumulator,
36
- };
37
- const items = await (0, workflow_values_1.evaluateValue)(step.forEach.in, scope);
38
- const iterable = Array.isArray(items) ? items : [];
39
- let accumulator = step.accumulate?.initial ?? state.accumulator;
40
- for (let index = startIndex; index < iterable.length; index += 1) {
41
- const item = iterable[index];
29
+ async function executeForEachLoop(env, step, state, path, frame) {
30
+ // The item list is resolved once, when the loop starts; a resumed loop
31
+ // keeps iterating over the same items even if `in` would now differ.
32
+ const items = frame
33
+ ? (frame.items ?? [])
34
+ : await resolveItems(env, step, state);
35
+ let accumulator = frame
36
+ ? frame.accumulator
37
+ : (step.accumulate?.initial ?? state.accumulator);
38
+ for (let index = frame?.index ?? 0; index < items.length; index += 1) {
39
+ const item = items[index];
42
40
  const iterationState = {
43
41
  ...state,
44
42
  iteration: { item, index },
45
43
  accumulator,
46
44
  iterationStack: [...state.iterationStack, index],
47
45
  };
48
- const suspension = await env.executeFlow(step.steps, iterationState, [
49
- ...path,
50
- index,
51
- ]);
52
- if (suspension) {
53
- return (0, suspension_continuation_1.wrapSuspensionContinuation)(suspension, async () => {
54
- const postScope = buildScope(env, iterationState, { item, index }, accumulator);
55
- accumulator = await updateAccumulator(step, postScope, accumulator);
56
- const shouldStop = await shouldStopLoop(step, postScope);
57
- if (shouldStop) {
58
- state.accumulator = accumulator;
59
- if (step.accumulate && step.name) {
60
- state.output[step.name] = { [step.accumulate.as]: accumulator };
61
- }
62
- return undefined;
63
- }
64
- return executeForEachLoop(env, step, {
65
- ...iterationState,
66
- accumulator,
67
- iterationStack: state.iterationStack,
68
- }, path, index + 1);
69
- });
46
+ const child = await env.executeFlow(step.steps, iterationState, [...path, index], frame && index === frame.index ? frame.child : undefined);
47
+ if (child) {
48
+ return {
49
+ kind: 'loop',
50
+ stepId: step.id,
51
+ index,
52
+ items,
53
+ accumulator,
54
+ child,
55
+ };
70
56
  }
71
57
  const postScope = buildScope(env, iterationState, { item, index }, accumulator);
72
58
  accumulator = await updateAccumulator(step, postScope, accumulator);
@@ -79,13 +65,19 @@ async function executeForEachLoop(env, step, state, path, startIndex) {
79
65
  finalizeAccumulatorState(step, state, accumulator);
80
66
  return undefined;
81
67
  }
82
- async function executeWhileLoop(env, step, state, path, startIndex) {
83
- let accumulator = step.accumulate?.initial ?? state.accumulator;
84
- for (let index = startIndex;; index += 1) {
85
- const conditionScope = buildScope(env, state, { item: undefined, index }, accumulator);
86
- const shouldContinue = await (0, workflow_values_1.evaluateValue)(step.while, conditionScope);
87
- if (!Boolean(shouldContinue)) {
88
- break;
68
+ async function executeWhileLoop(env, step, state, path, frame) {
69
+ let accumulator = frame
70
+ ? frame.accumulator
71
+ : (step.accumulate?.initial ?? state.accumulator);
72
+ for (let index = frame?.index ?? 0;; index += 1) {
73
+ const resumedChild = frame && index === frame.index ? frame.child : undefined;
74
+ // The guard of a resumed iteration already passed before it suspended.
75
+ if (!resumedChild) {
76
+ const conditionScope = buildScope(env, state, { item: undefined, index }, accumulator);
77
+ const shouldContinue = await (0, workflow_values_1.evaluateValue)(step.while, conditionScope);
78
+ if (!Boolean(shouldContinue)) {
79
+ break;
80
+ }
89
81
  }
90
82
  const iterationState = {
91
83
  ...state,
@@ -93,20 +85,9 @@ async function executeWhileLoop(env, step, state, path, startIndex) {
93
85
  accumulator,
94
86
  iterationStack: [...state.iterationStack, index],
95
87
  };
96
- const suspension = await env.executeFlow(step.steps, iterationState, [
97
- ...path,
98
- index,
99
- ]);
100
- if (suspension) {
101
- return (0, suspension_continuation_1.wrapSuspensionContinuation)(suspension, async () => {
102
- const postScope = buildScope(env, iterationState, { item: undefined, index }, accumulator);
103
- accumulator = await updateAccumulator(step, postScope, accumulator);
104
- return executeWhileLoop(env, step, {
105
- ...iterationState,
106
- accumulator,
107
- iterationStack: state.iterationStack,
108
- }, path, index + 1);
109
- });
88
+ const child = await env.executeFlow(step.steps, iterationState, [...path, index], resumedChild);
89
+ if (child) {
90
+ return { kind: 'loop', stepId: step.id, index, accumulator, child };
110
91
  }
111
92
  const postScope = buildScope(env, iterationState, { item: undefined, index }, accumulator);
112
93
  accumulator = await updateAccumulator(step, postScope, accumulator);
@@ -115,6 +96,16 @@ async function executeWhileLoop(env, step, state, path, startIndex) {
115
96
  finalizeAccumulatorState(step, state, accumulator);
116
97
  return undefined;
117
98
  }
99
+ async function resolveItems(env, step, state) {
100
+ const items = await (0, workflow_values_1.evaluateValue)(step.forEach.in, {
101
+ input: state.input,
102
+ context: env.context.state,
103
+ output: state.output,
104
+ iteration: state.iteration,
105
+ accumulator: state.accumulator,
106
+ });
107
+ return Array.isArray(items) ? items : [];
108
+ }
118
109
  function finalizeAccumulatorState(step, state, accumulator) {
119
110
  if (step.accumulate && step.name) {
120
111
  state.output[step.name] = { [step.accumulate.as]: accumulator };
@@ -6,25 +6,46 @@
6
6
  */
7
7
  Object.defineProperty(exports, "__esModule", { value: true });
8
8
  exports.executeParallel = executeParallel;
9
+ const checkpoint_1 = require("../checkpoint");
9
10
  const errors_1 = require("../errors");
11
+ const clone_1 = require("../utils/clone");
10
12
  const skip_helpers_1 = require("./skip-helpers");
11
13
  /**
12
14
  * Execute a set of child steps concurrently and resolve according to the configured strategy.
13
15
  *
16
+ * A branch may suspend. The block then waits until every branch has settled
17
+ * (fulfilled, suspended, or failed) before suspending itself, so a sibling that
18
+ * was still running finishes exactly once instead of being re-run on resume.
19
+ *
14
20
  * @param env Executor environment providing helpers and workflow context.
15
21
  * @param step The parallel step definition including strategy and children.
16
22
  * @param state Mutable workflow execution state.
17
23
  * @param path Path tokens locating this parallel block in the workflow.
18
- * @returns Always undefined; suspensions are rejected inside parallel blocks.
24
+ * @param frame Frame returned when the block previously suspended: fulfilled
25
+ * branches are not launched again, parked ones stay parked unless this pass
26
+ * resolves one of their waits, and those resume from their frame.
27
+ * @returns A frame if any branch is left suspended, otherwise void.
19
28
  */
20
- async function executeParallel(env, step, state, path) {
29
+ async function executeParallel(env, step, state, path, frame) {
21
30
  if (step.steps.length === 0) {
22
31
  return undefined;
23
32
  }
24
33
  (0, errors_1.throwIfAborted)(env.signal);
25
- const baseOutput = cloneRecord(state.output);
26
- const baseContextState = cloneRecord(env.context.state);
27
- const branches = step.steps.map((child, index) => launchBranch({
34
+ const outcomes = new Map();
35
+ const launches = [];
36
+ step.steps.forEach((child, index) => {
37
+ const recorded = frame?.branches[index];
38
+ const kept = recorded ? keepRecordedBranch(env, index, recorded) : null;
39
+ if (kept) {
40
+ outcomes.set(index, kept);
41
+ }
42
+ else {
43
+ launches.push({ child, index, recorded });
44
+ }
45
+ });
46
+ const baseOutput = (0, clone_1.cloneRecord)(state.output);
47
+ const baseContextState = (0, clone_1.cloneRecord)(env.context.state);
48
+ const branches = launches.map(({ child, index, recorded }) => launchBranch({
28
49
  env,
29
50
  child,
30
51
  index,
@@ -32,63 +53,102 @@ async function executeParallel(env, step, state, path) {
32
53
  parentState: state,
33
54
  baseOutput,
34
55
  baseContextState,
56
+ recorded,
35
57
  }));
36
58
  if (step.strategy === 'wait_any') {
37
- return executeWaitAny(env, branches, state);
59
+ return executeWaitAny(env, step, branches, outcomes, state);
60
+ }
61
+ return executeWaitAll(env, step, branches, outcomes, state);
62
+ }
63
+ /**
64
+ * Settle a recorded branch that has nothing to run in this pass: a fulfilled
65
+ * branch never runs again, and a parked branch stays exactly as it was
66
+ * unless this pass resolves one of its waits.
67
+ *
68
+ * @returns Its outcome, or null when the branch has to be launched.
69
+ */
70
+ function keepRecordedBranch(env, index, recorded) {
71
+ if (recorded.status === 'fulfilled') {
72
+ return { status: 'fulfilled', index, outputDelta: recorded.outputDelta };
38
73
  }
39
- return executeWaitAll(env, branches, state);
74
+ const resolved = (0, checkpoint_1.collectWaits)(recorded.child).some((wait) => env.resolutions.has(wait.waitId));
75
+ return resolved
76
+ ? null
77
+ : {
78
+ status: 'suspended',
79
+ index,
80
+ outputDelta: recorded.outputDelta,
81
+ frame: recorded.child,
82
+ };
40
83
  }
41
- async function executeWaitAll(env, branches, state) {
84
+ async function executeWaitAll(env, step, branches, outcomes, state) {
42
85
  const pending = new Set(branches);
43
- const outcomes = new Map();
44
86
  while (pending.size > 0) {
45
87
  const { branch, result } = await raceNext(pending);
46
88
  pending.delete(branch);
47
89
  outcomes.set(result.index, result);
48
90
  if (result.status === 'failed' || result.status === 'cancelled') {
49
- cancelBranches(env, pending, result.error, 'Parallel branch execution was cancelled.');
50
- await settleBranches(branches);
91
+ await abandonBranches(env, branches, pending, outcomes, result.error);
51
92
  throw result.error;
52
93
  }
53
94
  }
95
+ if (hasSuspendedBranch(outcomes)) {
96
+ return buildParallelFrame(step, outcomes);
97
+ }
54
98
  mergeBranchOutputs(state, outcomes);
55
99
  }
56
- async function executeWaitAny(env, branches, state) {
100
+ async function executeWaitAny(env, step, branches, outcomes, state) {
57
101
  const pending = new Set(branches);
58
- const outcomes = new Map();
59
102
  while (pending.size > 0) {
60
103
  const { branch, result } = await raceNext(pending);
61
104
  pending.delete(branch);
62
105
  outcomes.set(result.index, result);
106
+ if (result.status === 'suspended') {
107
+ continue;
108
+ }
63
109
  if (result.status === 'fulfilled') {
64
- cancelBranches(env, pending, new errors_1.WorkflowCancellationError('Parallel wait_any winner selected.'), 'Parallel wait_any branch lost the race.');
65
- await settleBranches(branches);
110
+ // Parked losers will never be resumed; drop their waits with the race.
111
+ await abandonBranches(env, branches, pending, outcomes, new errors_1.WorkflowCancellationError('Parallel wait_any winner selected.'), 'Parallel wait_any branch lost the race.');
66
112
  mergeBranchOutputs(state, new Map([[result.index, result]]));
67
- return;
113
+ return undefined;
68
114
  }
69
- cancelBranches(env, pending, result.error, 'Parallel branch execution was cancelled.');
70
- await settleBranches(branches);
115
+ await abandonBranches(env, branches, pending, outcomes, result.error);
71
116
  throw result.error;
72
117
  }
118
+ // Every branch settled without a winner, so all of them are suspended.
119
+ return buildParallelFrame(step, outcomes);
120
+ }
121
+ /**
122
+ * Give up on the block: cancel the branches still running, let every branch
123
+ * settle, then drop the waits of every branch left suspended, including one
124
+ * that suspended while it was being cancelled.
125
+ */
126
+ async function abandonBranches(env, branches, pending, outcomes, reason, snapshotReason = 'Parallel branch execution was cancelled.') {
127
+ cancelBranches(env, pending, reason, snapshotReason);
128
+ for (const result of await settleBranches(branches)) {
129
+ outcomes.set(result.index, result);
130
+ }
131
+ cancelSuspendedBranches(env, outcomes, reason);
73
132
  }
74
- function launchBranch({ env, child, index, path, parentState, baseOutput, baseContextState, }) {
75
- const controller = createBranchController(env.signal);
76
- const trackedOutput = createTrackedOutput(baseOutput);
133
+ function launchBranch({ env, child, index, path, parentState, baseOutput, baseContextState, recorded, }) {
134
+ const { controller, unlink } = (0, errors_1.createLinkedAbortController)(env.signal);
135
+ const trackedOutput = createTrackedOutput(baseOutput, recorded?.outputDelta);
77
136
  const branchState = {
78
137
  input: parentState.input,
79
138
  output: trackedOutput.output,
80
139
  iteration: parentState.iteration ? { ...parentState.iteration } : undefined,
81
- accumulator: cloneValue(parentState.accumulator),
140
+ accumulator: (0, clone_1.cloneValue)(parentState.accumulator),
82
141
  iterationStack: [...parentState.iterationStack],
83
142
  };
84
- const branchContext = createParallelBranchContext(env.context, cloneRecord(baseContextState));
143
+ const branchRuntime = env.runtime.fork();
144
+ const branchContext = createParallelBranchContext(env.context, (0, clone_1.cloneRecord)(baseContextState), branchRuntime);
85
145
  const branchEnv = env.fork({
86
146
  context: branchContext,
87
147
  signal: controller.signal,
88
- setCurrentStep: () => undefined,
148
+ runtime: branchRuntime,
89
149
  });
90
150
  const childPath = [...path, 'parallel', index];
91
- const promise = runBranch(branchEnv, child, branchState, childPath, trackedOutput, index);
151
+ const promise = runBranch(branchEnv, child, branchState, childPath, trackedOutput, index, recorded?.status === 'suspended' ? recorded.child : undefined).finally(unlink);
92
152
  return {
93
153
  index,
94
154
  step: child,
@@ -97,12 +157,19 @@ function launchBranch({ env, child, index, path, parentState, baseOutput, baseCo
97
157
  promise,
98
158
  };
99
159
  }
100
- async function runBranch(env, child, branchState, childPath, trackedOutput, index) {
160
+ async function runBranch(env, child, branchState, childPath, trackedOutput, index, frame) {
101
161
  try {
102
162
  (0, errors_1.throwIfAborted)(env.signal);
103
- const suspension = await env.executeStep(child, branchState, childPath);
104
- if (suspension) {
105
- throw new errors_1.ParallelSuspensionError();
163
+ const suspended = await env.executeStep(child, branchState, childPath, frame);
164
+ // A branch can suspend while it is being cancelled: its wait was opened
165
+ // all the same, so the block needs its frame to drop it.
166
+ if (suspended) {
167
+ return {
168
+ status: 'suspended',
169
+ index,
170
+ outputDelta: trackedOutput.getDelta(),
171
+ frame: suspended,
172
+ };
106
173
  }
107
174
  (0, errors_1.throwIfAborted)(env.signal);
108
175
  return {
@@ -121,8 +188,9 @@ async function runBranch(env, child, branchState, childPath, trackedOutput, inde
121
188
  async function raceNext(pending) {
122
189
  return Promise.race([...pending].map((branch) => branch.promise.then((result) => ({ branch, result }))));
123
190
  }
191
+ /** Wait for every branch to settle; `runBranch` never rejects. */
124
192
  async function settleBranches(branches) {
125
- await Promise.all(branches.map((branch) => branch.promise.catch(() => null)));
193
+ return Promise.all(branches.map((branch) => branch.promise));
126
194
  }
127
195
  function cancelBranches(env, branches, reason, snapshotReason) {
128
196
  for (const branch of branches) {
@@ -134,6 +202,57 @@ function cancelBranches(env, branches, reason, snapshotReason) {
134
202
  (0, skip_helpers_1.markStepsCancelled)(env, [branch.step], branch.iterationStack, reason instanceof Error ? reason.message : snapshotReason);
135
203
  }
136
204
  }
205
+ /**
206
+ * Mark the parked waits of suspended branches cancelled once the block can
207
+ * no longer resume them.
208
+ */
209
+ function cancelSuspendedBranches(env, outcomes, reason) {
210
+ const message = reason instanceof Error ? reason.message : 'Parallel branch was cancelled.';
211
+ for (const outcome of outcomes.values()) {
212
+ if (outcome.status !== 'suspended') {
213
+ continue;
214
+ }
215
+ for (const wait of (0, checkpoint_1.collectWaits)(outcome.frame)) {
216
+ const stepExecution = env.recordStepExecution(wait.step, {
217
+ status: 'cancelled',
218
+ endedAt: Date.now(),
219
+ reason: message,
220
+ error: { message },
221
+ });
222
+ env.markSnapshot(wait.step, 'cancelled', message);
223
+ env.emit('hook:step:cancelled', {
224
+ runId: env.runId,
225
+ step: wait.step,
226
+ stepExecution,
227
+ error: reason instanceof Error ? reason : new Error(message),
228
+ wait,
229
+ });
230
+ }
231
+ }
232
+ }
233
+ function hasSuspendedBranch(outcomes) {
234
+ return [...outcomes.values()].some((outcome) => outcome.status === 'suspended');
235
+ }
236
+ function buildParallelFrame(step, outcomes) {
237
+ return {
238
+ kind: 'parallel',
239
+ stepId: step.id,
240
+ branches: step.steps.map((_, index) => {
241
+ const outcome = outcomes.get(index);
242
+ if (outcome?.status === 'fulfilled') {
243
+ return { status: 'fulfilled', outputDelta: outcome.outputDelta };
244
+ }
245
+ if (outcome?.status === 'suspended') {
246
+ return {
247
+ status: 'suspended',
248
+ outputDelta: outcome.outputDelta,
249
+ child: outcome.frame,
250
+ };
251
+ }
252
+ throw new Error(`Parallel branch ${index} of "${step.id}" did not settle before suspending.`);
253
+ }),
254
+ };
255
+ }
137
256
  function mergeBranchOutputs(state, outcomes) {
138
257
  const ordered = [...outcomes.values()].sort((left, right) => {
139
258
  return left.index - right.index;
@@ -145,18 +264,16 @@ function mergeBranchOutputs(state, outcomes) {
145
264
  Object.assign(state.output, outcome.outputDelta);
146
265
  }
147
266
  }
148
- function createBranchController(parentSignal) {
149
- const controller = new AbortController();
150
- if (parentSignal.aborted) {
151
- controller.abort((0, errors_1.getAbortReason)(parentSignal));
152
- return controller;
267
+ /**
268
+ * Give a branch its own copy of the parent output that remembers which keys
269
+ * the branch wrote. A resumed branch starts from the delta it had recorded.
270
+ */
271
+ function createTrackedOutput(baseOutput, recordedDelta) {
272
+ const writtenKeys = new Set(Object.keys(recordedDelta ?? {}));
273
+ const target = (0, clone_1.cloneRecord)(baseOutput);
274
+ if (recordedDelta) {
275
+ Object.assign(target, (0, clone_1.cloneRecord)(recordedDelta));
153
276
  }
154
- parentSignal.addEventListener('abort', () => controller.abort((0, errors_1.getAbortReason)(parentSignal)), { once: true });
155
- return controller;
156
- }
157
- function createTrackedOutput(baseOutput) {
158
- const writtenKeys = new Set();
159
- const target = cloneRecord(baseOutput);
160
277
  const output = new Proxy(target, {
161
278
  set(record, property, value) {
162
279
  if (typeof property === 'string') {
@@ -178,44 +295,25 @@ function createTrackedOutput(baseOutput) {
178
295
  .map((key) => [key, target[key]])),
179
296
  };
180
297
  }
181
- class ParallelWorkflowRuntimeControl {
182
- constructor(getParent) {
183
- this.getParent = getParent;
184
- }
185
- get status() {
186
- return this.getParent().status;
187
- }
188
- get resumeData() {
189
- return this.getParent().resumeData;
190
- }
191
- suspend() {
192
- return Promise.reject(new errors_1.ParallelSuspensionError());
193
- }
194
- hasRecordedResult() {
195
- // Suspension is not supported inside parallel blocks, so no resume
196
- // result can ever be recorded for them.
197
- return false;
198
- }
199
- resume(data) {
200
- this.getParent().resume(data);
201
- }
202
- getSnapshot() {
203
- return this.getParent().getSnapshot();
204
- }
205
- }
206
- function createParallelBranchContext(context, branchState) {
298
+ /**
299
+ * Isolate a branch's context state and route `context.workflow` to the
300
+ * branch's own runtime scope, so its steps can suspend independently.
301
+ */
302
+ function createParallelBranchContext(context, branchState, runtime) {
207
303
  let state = branchState;
208
- const workflow = new ParallelWorkflowRuntimeControl(() => context.workflow);
209
304
  return new Proxy(context, {
210
305
  get(target, property, receiver) {
211
306
  if (property === 'state') {
212
307
  return state;
213
308
  }
214
309
  if (property === 'workflow') {
215
- return workflow;
310
+ return runtime;
311
+ }
312
+ if (property === 'getWorkflowRuntime') {
313
+ return () => runtime;
216
314
  }
217
315
  if (property === 'snapshot') {
218
- return () => cloneRecord(state);
316
+ return () => (0, clone_1.cloneRecord)(state);
219
317
  }
220
318
  if (property === 'attachWorkflowRuntime') {
221
319
  return () => undefined;
@@ -224,41 +322,10 @@ function createParallelBranchContext(context, branchState) {
224
322
  },
225
323
  set(target, property, value, receiver) {
226
324
  if (property === 'state') {
227
- state = isRecord(value) ? value : {};
325
+ state = (0, clone_1.isRecord)(value) ? value : {};
228
326
  return true;
229
327
  }
230
328
  return Reflect.set(target, property, value, receiver);
231
329
  },
232
330
  });
233
331
  }
234
- function cloneRecord(value) {
235
- return cloneValue(value);
236
- }
237
- function cloneValue(value) {
238
- if (value === undefined || value === null) {
239
- return value;
240
- }
241
- if (typeof structuredClone === 'function') {
242
- try {
243
- return structuredClone(value);
244
- }
245
- catch {
246
- // Fall through to JSON clone below.
247
- }
248
- }
249
- try {
250
- return JSON.parse(JSON.stringify(value));
251
- }
252
- catch {
253
- if (Array.isArray(value)) {
254
- return [...value];
255
- }
256
- if (isRecord(value)) {
257
- return { ...value };
258
- }
259
- return value;
260
- }
261
- }
262
- function isRecord(value) {
263
- return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
264
- }