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