@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,13 @@
4
4
  * Full terms: see LICENSE.md.
5
5
  */
6
6
 
7
+ import type { SequenceFrame } from '../checkpoint';
7
8
  import { BaseWorkflowContext } from '../context';
8
- import type { RuntimeSuspensionRequest } from '../runner-runtime-control';
9
- import {
10
- StepType,
11
- type EventEmitterLike,
12
- type StepInfo,
13
- } from '../workflow-event-emitter';
9
+ import { StepType, type EventEmitterLike } from '../workflow-event-emitter';
14
10
  import type {
15
11
  CompiledStep,
16
12
  ConditionalStep,
17
13
  ExecutionState,
18
- Suspension,
19
14
  } from '../workflow-types';
20
15
 
21
16
  import { executeConditional } from './conditional-executor';
@@ -53,18 +48,13 @@ const createEnv = (): StepExecutorEnv => {
53
48
  context: new TestContext(),
54
49
  signal: new AbortController().signal,
55
50
  runId: 'run-1',
51
+ runtime: {} as StepExecutorEnv['runtime'],
52
+ resolutions: new Map<string, unknown>(),
53
+ rejectResume: jest.fn(),
56
54
  buildInstanceStepInfo: jest.fn(),
57
55
  markSnapshot: jest.fn(),
58
56
  recordStepExecution: jest.fn(),
59
57
  emit: jest.fn(),
60
- setCurrentStep: jest.fn(),
61
- waitForStepSuspension: jest
62
- .fn()
63
- .mockImplementation(
64
- () => new Promise<RuntimeSuspensionRequest>(() => undefined),
65
- ),
66
- clearStepSuspensions: jest.fn(),
67
- primeStepResumeData: jest.fn(),
68
58
  captureTaskOutput: jest.fn(),
69
59
  executeFlow: jest.fn(),
70
60
  executeStep: jest.fn(),
@@ -112,61 +102,102 @@ describe('executeConditional', () => {
112
102
  step.branches[1].steps,
113
103
  state,
114
104
  [0, 'branch', 1],
105
+ undefined,
115
106
  );
116
107
  });
117
108
 
118
- it('wraps and resumes from a suspended branch', async () => {
109
+ it('records the chosen branch when it suspends', async () => {
119
110
  const env = createEnv();
120
111
  const state = createState();
121
- const innerSuspension: Suspension = {
122
- step: { id: 'inner', name: 'inner', type: StepType.Task } as StepInfo,
123
- reason: 'pause',
124
- continue: jest.fn().mockResolvedValue(undefined),
112
+ const child: SequenceFrame = {
113
+ kind: 'sequence',
114
+ index: 0,
115
+ child: {
116
+ kind: 'task',
117
+ stepId: 'b',
118
+ inputs: {},
119
+ awaitResults: {},
120
+ wait: {
121
+ waitId: 'b@index:1',
122
+ step: { id: 'b', name: 'b', type: StepType.Task },
123
+ suspendKey: 'index:1',
124
+ },
125
+ },
125
126
  };
126
- env.executeFlow = jest.fn().mockResolvedValue(innerSuspension);
127
+ env.executeFlow = jest.fn().mockResolvedValue(child);
127
128
 
128
129
  const step: ConditionalStep = {
129
130
  id: 'conditional',
130
131
  type: StepType.Conditional,
131
132
  label: 'conditional',
132
- branches: [{ id: 'branch-0', steps: [createTaskStep('a')] }],
133
+ branches: [
134
+ {
135
+ id: 'branch-0',
136
+ condition: { kind: 'literal', value: false },
137
+ steps: [createTaskStep('a')],
138
+ },
139
+ { id: 'branch-1', steps: [createTaskStep('b')] },
140
+ ],
133
141
  };
134
- const suspension = await executeConditional(env, step, state, []);
135
- expect(suspension).toEqual(
136
- expect.objectContaining({ step: innerSuspension.step, reason: 'pause' }),
137
- );
138
- expect(env.executeFlow).toHaveBeenCalledTimes(1);
139
-
140
- await suspension?.continue('resume-data');
141
- expect(innerSuspension.continue).toHaveBeenCalledWith('resume-data');
142
- expect(env.executeFlow).toHaveBeenCalledTimes(1);
142
+ const frame = await executeConditional(env, step, state, []);
143
+
144
+ expect(frame).toEqual({
145
+ kind: 'conditional',
146
+ stepId: 'conditional',
147
+ branchIndex: 1,
148
+ child,
149
+ });
143
150
  });
144
151
 
145
- it('forwards nested suspensions from branch continuation', async () => {
152
+ it('re-enters the recorded branch without evaluating conditions again', async () => {
146
153
  const env = createEnv();
147
154
  const state = createState();
148
- const nextSuspension: Suspension = {
149
- step: { id: 'next', name: 'next', type: StepType.Task } as StepInfo,
150
- continue: jest.fn(),
151
- };
152
- const innerSuspension: Suspension = {
153
- step: { id: 'inner', name: 'inner', type: StepType.Task } as StepInfo,
154
- continue: jest.fn().mockResolvedValue(nextSuspension),
155
+ const child: SequenceFrame = {
156
+ kind: 'sequence',
157
+ index: 0,
158
+ child: {
159
+ kind: 'task',
160
+ stepId: 'b',
161
+ inputs: {},
162
+ awaitResults: {},
163
+ wait: {
164
+ waitId: 'b@index:1',
165
+ step: { id: 'b', name: 'b', type: StepType.Task },
166
+ suspendKey: 'index:1',
167
+ },
168
+ },
155
169
  };
156
- env.executeFlow = jest.fn().mockResolvedValue(innerSuspension);
170
+ env.executeFlow = jest.fn().mockResolvedValue(undefined);
157
171
 
158
172
  const step: ConditionalStep = {
159
173
  id: 'conditional',
160
174
  type: StepType.Conditional,
161
175
  label: 'conditional',
162
- branches: [{ id: 'branch-0', steps: [createTaskStep('a')] }],
176
+ branches: [
177
+ {
178
+ id: 'branch-0',
179
+ condition: { kind: 'literal', value: true },
180
+ steps: [createTaskStep('a')],
181
+ },
182
+ { id: 'branch-1', steps: [createTaskStep('b')] },
183
+ ],
163
184
  };
164
- const suspension = await executeConditional(env, step, state, []);
165
- const result = await suspension?.continue('resume-data');
185
+ const result = await executeConditional(env, step, state, [2], {
186
+ kind: 'conditional',
187
+ stepId: 'conditional',
188
+ branchIndex: 1,
189
+ child,
190
+ });
166
191
 
167
- expect(result).toBe(nextSuspension);
168
- expect(innerSuspension.continue).toHaveBeenCalledWith('resume-data');
169
- expect(env.executeFlow).toHaveBeenCalledTimes(1);
192
+ expect(result).toBeUndefined();
193
+ expect(env.executeFlow).toHaveBeenCalledWith(
194
+ step.branches[1].steps,
195
+ state,
196
+ [2, 'branch', 1],
197
+ child,
198
+ );
199
+ // Skipped branches were already reported when the branch was chosen.
200
+ expect(env.markSnapshot).not.toHaveBeenCalled();
170
201
  });
171
202
 
172
203
  it('returns undefined when no branch matches', async () => {
@@ -4,11 +4,8 @@
4
4
  * Full terms: see LICENSE.md.
5
5
  */
6
6
 
7
- import type {
8
- ConditionalStep,
9
- ExecutionState,
10
- Suspension,
11
- } from '../workflow-types';
7
+ import type { ConditionalFrame } from '../checkpoint';
8
+ import type { ConditionalStep, ExecutionState } from '../workflow-types';
12
9
  import { evaluateValue } from '../workflow-values';
13
10
 
14
11
  import { markStepsSkipped } from './skip-helpers';
@@ -21,14 +18,55 @@ import type { StepExecutorEnv } from './types';
21
18
  * @param step The conditional step definition.
22
19
  * @param state Mutable workflow execution state.
23
20
  * @param path Path tokens locating this step within the workflow tree.
24
- * @returns A suspension if a branch pauses execution, otherwise void.
21
+ * @param frame Frame returned when the chosen branch previously suspended; its
22
+ * branch is re-entered without evaluating conditions again.
23
+ * @returns A frame if the chosen branch suspends, otherwise void.
25
24
  */
26
25
  export async function executeConditional(
27
26
  env: StepExecutorEnv,
28
27
  step: ConditionalStep,
29
28
  state: ExecutionState,
30
29
  path: Array<number | string>,
31
- ): Promise<Suspension | void> {
30
+ frame?: ConditionalFrame,
31
+ ): Promise<ConditionalFrame | void> {
32
+ const branchIndex = frame
33
+ ? frame.branchIndex
34
+ : await chooseBranch(env, step, state);
35
+ if (branchIndex === undefined) {
36
+ step.branches.forEach((branch) =>
37
+ markStepsSkipped(env, branch.steps, state.iterationStack),
38
+ );
39
+
40
+ return undefined;
41
+ }
42
+
43
+ if (!frame) {
44
+ step.branches.forEach((candidate, candidateIndex) => {
45
+ if (candidateIndex !== branchIndex) {
46
+ markStepsSkipped(env, candidate.steps, state.iterationStack);
47
+ }
48
+ });
49
+ }
50
+
51
+ const child = await env.executeFlow(
52
+ step.branches[branchIndex].steps,
53
+ state,
54
+ [...path, 'branch', branchIndex],
55
+ frame?.child,
56
+ );
57
+
58
+ if (child) {
59
+ return { kind: 'conditional', stepId: step.id, branchIndex, child };
60
+ }
61
+
62
+ return undefined;
63
+ }
64
+
65
+ const chooseBranch = async (
66
+ env: StepExecutorEnv,
67
+ step: ConditionalStep,
68
+ state: ExecutionState,
69
+ ): Promise<number | undefined> => {
32
70
  for (let index = 0; index < step.branches.length; index += 1) {
33
71
  const branch = step.branches[index];
34
72
  const scope = {
@@ -44,40 +82,9 @@ export async function executeConditional(
44
82
  : true;
45
83
 
46
84
  if (conditionResult) {
47
- step.branches.forEach((candidate, candidateIndex) => {
48
- if (candidateIndex !== index) {
49
- markStepsSkipped(env, candidate.steps, state.iterationStack);
50
- }
51
- });
52
- const suspension = await env.executeFlow(branch.steps, state, [
53
- ...path,
54
- 'branch',
55
- index,
56
- ]);
57
-
58
- if (suspension) {
59
- return {
60
- ...suspension,
61
- continue: async (resumeData: unknown) => {
62
- const next = await suspension.continue(resumeData);
63
- if (next) {
64
- return next;
65
- }
66
-
67
- return undefined;
68
- },
69
- };
70
- }
71
-
72
- return undefined;
85
+ return index;
73
86
  }
74
87
  }
75
88
 
76
- if (step.branches.length > 0) {
77
- step.branches.forEach((branch) =>
78
- markStepsSkipped(env, branch.steps, state.iterationStack),
79
- );
80
- }
81
-
82
89
  return undefined;
83
- }
90
+ };
@@ -4,19 +4,10 @@
4
4
  * Full terms: see LICENSE.md.
5
5
  */
6
6
 
7
+ import type { LoopFrame, SequenceFrame } from '../checkpoint';
7
8
  import { BaseWorkflowContext } from '../context';
8
- import type { RuntimeSuspensionRequest } from '../runner-runtime-control';
9
- import {
10
- StepType,
11
- type EventEmitterLike,
12
- type StepInfo,
13
- } from '../workflow-event-emitter';
14
- import type {
15
- CompiledStep,
16
- ExecutionState,
17
- LoopStep,
18
- Suspension,
19
- } from '../workflow-types';
9
+ import { StepType, type EventEmitterLike } from '../workflow-event-emitter';
10
+ import type { CompiledStep, ExecutionState, LoopStep } from '../workflow-types';
20
11
  import { compileValue } from '../workflow-values';
21
12
 
22
13
  import {
@@ -52,18 +43,13 @@ const createEnv = (executeFlow: jest.Mock): StepExecutorEnv => {
52
43
  context: new TestContext(),
53
44
  signal: new AbortController().signal,
54
45
  runId: 'run-loop',
46
+ runtime: {} as StepExecutorEnv['runtime'],
47
+ resolutions: new Map<string, unknown>(),
48
+ rejectResume: jest.fn(),
55
49
  buildInstanceStepInfo: jest.fn(),
56
50
  markSnapshot: jest.fn(),
57
51
  recordStepExecution: jest.fn(),
58
52
  emit: jest.fn(),
59
- setCurrentStep: jest.fn(),
60
- waitForStepSuspension: jest
61
- .fn()
62
- .mockImplementation(
63
- () => new Promise<RuntimeSuspensionRequest>(() => undefined),
64
- ),
65
- clearStepSuspensions: jest.fn(),
66
- primeStepResumeData: jest.fn(),
67
53
  captureTaskOutput: jest.fn(),
68
54
  executeFlow,
69
55
  executeStep: jest.fn(),
@@ -80,6 +66,30 @@ const createTaskStep = (id: string): CompiledStep => ({
80
66
  label: id,
81
67
  taskName: `task_${id}`,
82
68
  });
69
+ const childFrame: SequenceFrame = {
70
+ kind: 'sequence',
71
+ index: 0,
72
+ child: {
73
+ kind: 'task',
74
+ stepId: 'child',
75
+ inputs: {},
76
+ awaitResults: {},
77
+ wait: {
78
+ waitId: 'child[0]@index:1',
79
+ step: { id: 'child[0]', name: 'child', type: StepType.Task },
80
+ suspendKey: 'index:1',
81
+ },
82
+ },
83
+ };
84
+ const recordItem = async (
85
+ _steps: CompiledStep[],
86
+ iterationState: ExecutionState,
87
+ ) => {
88
+ iterationState.output[`item_${iterationState.iteration?.index}`] =
89
+ iterationState.iteration?.item;
90
+
91
+ return undefined;
92
+ };
83
93
 
84
94
  describe('executeLoop', () => {
85
95
  it('iterates items, accumulates values, and stops when the until condition is met', async () => {
@@ -125,24 +135,7 @@ describe('executeLoop', () => {
125
135
  expect(state.output).toMatchObject({ item_0: 2, item_1: 4, item_2: 6 });
126
136
  });
127
137
 
128
- it('resumes after suspension and continues remaining iterations', async () => {
129
- const innerSuspension: Suspension = {
130
- step: { id: 'child', name: 'child', type: StepType.Task } as StepInfo,
131
- continue: jest.fn().mockResolvedValue(undefined),
132
- };
133
- const executeFlow = jest
134
- .fn()
135
- .mockResolvedValueOnce(innerSuspension)
136
- .mockImplementationOnce(
137
- async (_steps: CompiledStep[], iterationState: ExecutionState) => {
138
- iterationState.output[`item_${iterationState.iteration?.index}`] =
139
- iterationState.iteration?.item;
140
-
141
- return undefined;
142
- },
143
- );
144
- const env = createEnv(executeFlow);
145
- const state = createState();
138
+ it('records the suspended iteration and resumes it with the recorded items and accumulator', async () => {
146
139
  const step: LoopStep = {
147
140
  id: 'loop',
148
141
  type: StepType.Loop,
@@ -150,7 +143,6 @@ describe('executeLoop', () => {
150
143
  label: 'loop',
151
144
  name: 'collector',
152
145
  forEach: { item: 'entry', in: { kind: 'literal', value: [1, 2] } },
153
- until: compileValue('=$iteration.index >= 1'),
154
146
  accumulate: {
155
147
  as: 'sum',
156
148
  initial: 0,
@@ -158,30 +150,55 @@ describe('executeLoop', () => {
158
150
  },
159
151
  steps: [createTaskStep('child')],
160
152
  };
161
- const suspension = await executeLoop(env, step, state, []);
162
- expect(suspension).toEqual(
163
- expect.objectContaining({ step: innerSuspension.step }),
153
+ const suspendingFlow = jest
154
+ .fn()
155
+ .mockImplementationOnce(recordItem)
156
+ .mockResolvedValueOnce(childFrame);
157
+ const frame = await executeLoop(
158
+ createEnv(suspendingFlow),
159
+ step,
160
+ createState(),
161
+ [],
164
162
  );
165
163
 
166
- const result = await suspension?.continue({ resumed: true });
164
+ expect(frame).toEqual({
165
+ kind: 'loop',
166
+ stepId: 'loop',
167
+ index: 1,
168
+ items: [1, 2],
169
+ accumulator: 1,
170
+ child: childFrame,
171
+ });
167
172
 
168
- expect(result).toBeUndefined();
169
- expect(innerSuspension.continue).toHaveBeenCalledWith({ resumed: true });
170
- expect(executeFlow).toHaveBeenCalledTimes(2);
171
- expect(executeFlow).toHaveBeenNthCalledWith(
172
- 1,
173
- step.steps,
174
- expect.any(Object),
175
- [0],
173
+ // The item list is not re-evaluated: a resumed loop keeps its items.
174
+ const resumedStep: LoopStep = {
175
+ ...step,
176
+ forEach: { item: 'entry', in: { kind: 'literal', value: [9, 9, 9] } },
177
+ };
178
+ const resumingFlow = jest.fn(recordItem);
179
+ const state = createState();
180
+ const result = await executeLoop(
181
+ createEnv(resumingFlow),
182
+ resumedStep,
183
+ state,
184
+ [],
185
+ frame as LoopFrame,
176
186
  );
177
- expect(executeFlow).toHaveBeenNthCalledWith(
178
- 2,
187
+
188
+ expect(result).toBeUndefined();
189
+ expect(resumingFlow).toHaveBeenCalledTimes(1);
190
+ expect(resumingFlow).toHaveBeenCalledWith(
179
191
  step.steps,
180
- expect.any(Object),
192
+ expect.objectContaining({
193
+ iteration: { item: 2, index: 1 },
194
+ accumulator: 1,
195
+ iterationStack: [1],
196
+ }),
181
197
  [1],
198
+ childFrame,
182
199
  );
183
- expect(state.output.collector).toEqual({ sum: 2 });
184
- expect(state.accumulator).toBeUndefined();
200
+ expect(state.output.collector).toEqual({ sum: 3 });
201
+ expect(state.accumulator).toBe(3);
185
202
  });
186
203
 
187
204
  it('evaluates while loops before each iteration and can exit without running', async () => {
@@ -202,26 +219,7 @@ describe('executeLoop', () => {
202
219
  expect(executeFlow).not.toHaveBeenCalled();
203
220
  });
204
221
 
205
- it('continues while loops after suspension until the condition becomes false', async () => {
206
- const innerSuspension: Suspension = {
207
- step: { id: 'child', name: 'child', type: StepType.Task } as StepInfo,
208
- continue: jest.fn().mockResolvedValue(undefined),
209
- };
210
- const executeFlow = jest
211
- .fn()
212
- .mockResolvedValueOnce(innerSuspension)
213
- .mockImplementationOnce(
214
- async (_steps: CompiledStep[], iterationState: ExecutionState) => {
215
- iterationState.output.should_continue = false;
216
- iterationState.output.done = true;
217
-
218
- return undefined;
219
- },
220
- );
221
- const env = createEnv(executeFlow);
222
- const state = createState();
223
- state.output.should_continue = true;
224
-
222
+ it('resumes a while iteration without re-checking its guard', async () => {
225
223
  const step: LoopStep = {
226
224
  id: 'loop',
227
225
  type: StepType.Loop,
@@ -238,29 +236,45 @@ describe('executeLoop', () => {
238
236
  },
239
237
  steps: [createTaskStep('child')],
240
238
  };
241
- const suspension = await executeLoop(env, step, state, []);
242
- expect(suspension).toEqual(
243
- expect.objectContaining({ step: innerSuspension.step }),
239
+ const state = createState();
240
+ state.output.should_continue = true;
241
+
242
+ const frame = await executeLoop(
243
+ createEnv(jest.fn().mockResolvedValueOnce(childFrame)),
244
+ step,
245
+ state,
246
+ [],
244
247
  );
245
248
 
246
- const result = await suspension?.continue({ resumed: true });
249
+ expect(frame).toEqual({
250
+ kind: 'loop',
251
+ stepId: 'loop',
252
+ index: 0,
253
+ accumulator: 0,
254
+ child: childFrame,
255
+ });
256
+
257
+ // The guard is now false, but the suspended iteration already passed it.
258
+ const resumed = createState();
259
+ resumed.output.should_continue = false;
260
+ const executeFlow = jest.fn().mockResolvedValue(undefined);
261
+ const result = await executeLoop(
262
+ createEnv(executeFlow),
263
+ step,
264
+ resumed,
265
+ [],
266
+ frame as LoopFrame,
267
+ );
247
268
 
248
269
  expect(result).toBeUndefined();
249
- expect(innerSuspension.continue).toHaveBeenCalledWith({ resumed: true });
250
- expect(executeFlow).toHaveBeenCalledTimes(2);
251
- expect(executeFlow).toHaveBeenNthCalledWith(
252
- 1,
270
+ expect(executeFlow).toHaveBeenCalledTimes(1);
271
+ expect(executeFlow).toHaveBeenCalledWith(
253
272
  step.steps,
254
- expect.any(Object),
273
+ expect.objectContaining({ iteration: { item: undefined, index: 0 } }),
255
274
  [0],
275
+ childFrame,
256
276
  );
257
- expect(executeFlow).toHaveBeenNthCalledWith(
258
- 2,
259
- step.steps,
260
- expect.any(Object),
261
- [1],
262
- );
263
- expect(state.output.collector).toEqual({ count: 1 });
277
+ expect(resumed.output.collector).toEqual({ count: 1 });
264
278
  });
265
279
  });
266
280