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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (134) hide show
  1. package/README.md +67 -15
  2. package/dist/cjs/action/abstract-action.js +13 -1
  3. package/dist/cjs/checkpoint.js +301 -0
  4. package/dist/cjs/context.js +11 -27
  5. package/dist/cjs/dsl.types.js +3 -0
  6. package/dist/cjs/errors.js +116 -9
  7. package/dist/cjs/index.js +15 -6
  8. package/dist/cjs/resume-payload.js +257 -0
  9. package/dist/cjs/runner-runtime-control.js +181 -306
  10. package/dist/cjs/step-executors/conditional-executor.js +27 -29
  11. package/dist/cjs/step-executors/loop-executor.js +53 -62
  12. package/dist/cjs/step-executors/parallel-executor.js +169 -102
  13. package/dist/cjs/step-executors/task-executor.js +180 -96
  14. package/dist/cjs/utils/clone.js +73 -0
  15. package/dist/cjs/workflow-fingerprint.js +138 -0
  16. package/dist/cjs/workflow-runner.js +220 -155
  17. package/dist/cjs/workflow.js +24 -12
  18. package/dist/esm/action/abstract-action.js +14 -2
  19. package/dist/esm/checkpoint.js +293 -0
  20. package/dist/esm/context.js +11 -27
  21. package/dist/esm/dsl.types.js +3 -0
  22. package/dist/esm/errors.js +105 -6
  23. package/dist/esm/index.js +3 -3
  24. package/dist/esm/resume-payload.js +250 -0
  25. package/dist/esm/runner-runtime-control.js +179 -303
  26. package/dist/esm/step-executors/conditional-executor.js +27 -29
  27. package/dist/esm/step-executors/loop-executor.js +53 -62
  28. package/dist/esm/step-executors/parallel-executor.js +165 -98
  29. package/dist/esm/step-executors/task-executor.js +181 -97
  30. package/dist/esm/utils/clone.js +67 -0
  31. package/dist/esm/workflow-fingerprint.js +134 -0
  32. package/dist/esm/workflow-runner.js +220 -155
  33. package/dist/esm/workflow.js +24 -12
  34. package/dist/types/action/abstract-action.d.ts.map +1 -1
  35. package/dist/types/action/action.types.d.ts +0 -14
  36. package/dist/types/action/action.types.d.ts.map +1 -1
  37. package/dist/types/checkpoint.d.ts +188 -0
  38. package/dist/types/checkpoint.d.ts.map +1 -0
  39. package/dist/types/context.d.ts +45 -11
  40. package/dist/types/context.d.ts.map +1 -1
  41. package/dist/types/dsl.types.d.ts.map +1 -1
  42. package/dist/types/errors.d.ts +77 -3
  43. package/dist/types/errors.d.ts.map +1 -1
  44. package/dist/types/index.d.ts +6 -7
  45. package/dist/types/index.d.ts.map +1 -1
  46. package/dist/types/resume-payload.d.ts +69 -0
  47. package/dist/types/resume-payload.d.ts.map +1 -0
  48. package/dist/types/runner-runtime-control.d.ts +63 -51
  49. package/dist/types/runner-runtime-control.d.ts.map +1 -1
  50. package/dist/types/step-executors/conditional-executor.d.ts +6 -3
  51. package/dist/types/step-executors/conditional-executor.d.ts.map +1 -1
  52. package/dist/types/step-executors/loop-executor.d.ts +6 -4
  53. package/dist/types/step-executors/loop-executor.d.ts.map +1 -1
  54. package/dist/types/step-executors/parallel-executor.d.ts +11 -3
  55. package/dist/types/step-executors/parallel-executor.d.ts.map +1 -1
  56. package/dist/types/step-executors/task-executor.d.ts +11 -4
  57. package/dist/types/step-executors/task-executor.d.ts.map +1 -1
  58. package/dist/types/step-executors/types.d.ts +21 -13
  59. package/dist/types/step-executors/types.d.ts.map +1 -1
  60. package/dist/types/utils/clone.d.ts +33 -0
  61. package/dist/types/utils/clone.d.ts.map +1 -0
  62. package/dist/types/workflow-event-emitter.d.ts +29 -5
  63. package/dist/types/workflow-event-emitter.d.ts.map +1 -1
  64. package/dist/types/workflow-fingerprint.d.ts +14 -0
  65. package/dist/types/workflow-fingerprint.d.ts.map +1 -0
  66. package/dist/types/workflow-runner.d.ts +83 -41
  67. package/dist/types/workflow-runner.d.ts.map +1 -1
  68. package/dist/types/workflow-types.d.ts +25 -54
  69. package/dist/types/workflow-types.d.ts.map +1 -1
  70. package/dist/types/workflow.d.ts +24 -9
  71. package/dist/types/workflow.d.ts.map +1 -1
  72. package/examples/defs-bindings-agent/bindings.ts +1 -1
  73. package/examples/defs-bindings-agent/workflow.ts +3 -2
  74. package/examples/full/actions/await-user-input.ts +3 -2
  75. package/examples/full/actions/call-llm.ts +18 -18
  76. package/examples/full/actions/create-ticket.ts +1 -2
  77. package/examples/full/actions/decision-router.ts +6 -2
  78. package/examples/full/actions/get-calendar-events.ts +1 -2
  79. package/examples/full/actions/get-user-profile.ts +1 -2
  80. package/examples/full/actions/query-memory.ts +1 -2
  81. package/examples/full/actions/search-web.ts +1 -2
  82. package/examples/full/actions/send-email.ts +3 -2
  83. package/examples/full/workflow.ts +3 -2
  84. package/examples/loop/actions/await-reply.ts +2 -7
  85. package/examples/loop/workflow.ts +4 -2
  86. package/examples/suspend-resume/actions/wait-for-user.ts +11 -9
  87. package/examples/suspend-resume/workflow.ts +51 -11
  88. package/package.json +3 -3
  89. package/src/__tests__/checkpoint.test.ts +2568 -0
  90. package/src/__tests__/resume-payload.test.ts +245 -0
  91. package/src/__tests__/runner-runtime-control.test.ts +265 -0
  92. package/src/__tests__/workflow-fingerprint.test.ts +165 -0
  93. package/src/__tests__/workflow-runner.test.ts +167 -144
  94. package/src/__tests__/workflow.test.ts +97 -6
  95. package/src/action/abstract-action.ts +21 -2
  96. package/src/action/action.types.ts +0 -12
  97. package/src/checkpoint.ts +561 -0
  98. package/src/context.ts +51 -41
  99. package/src/dsl.types.ts +3 -0
  100. package/src/errors.ts +161 -8
  101. package/src/index.ts +33 -14
  102. package/src/resume-payload.ts +326 -0
  103. package/src/runner-runtime-control.ts +222 -456
  104. package/src/step-executors/conditional-executor.test.ts +77 -46
  105. package/src/step-executors/conditional-executor.ts +47 -40
  106. package/src/step-executors/loop-executor.test.ts +106 -92
  107. package/src/step-executors/loop-executor.ts +84 -101
  108. package/src/step-executors/parallel-executor.test.ts +300 -89
  109. package/src/step-executors/parallel-executor.ts +243 -125
  110. package/src/step-executors/task-executor.test.ts +321 -51
  111. package/src/step-executors/task-executor.ts +232 -145
  112. package/src/step-executors/types.ts +23 -22
  113. package/src/utils/clone.ts +75 -0
  114. package/src/workflow-event-emitter.ts +32 -6
  115. package/src/workflow-fingerprint.ts +159 -0
  116. package/src/workflow-runner.ts +325 -209
  117. package/src/workflow-types.ts +25 -56
  118. package/src/workflow.ts +41 -34
  119. package/dist/cjs/step-executors/suspension-continuation.js +0 -27
  120. package/dist/cjs/suspension-rebuilder.js +0 -265
  121. package/dist/cjs/utils/deferred.js +0 -17
  122. package/dist/esm/step-executors/suspension-continuation.js +0 -24
  123. package/dist/esm/suspension-rebuilder.js +0 -260
  124. package/dist/esm/utils/deferred.js +0 -14
  125. package/dist/types/step-executors/suspension-continuation.d.ts +0 -10
  126. package/dist/types/step-executors/suspension-continuation.d.ts.map +0 -1
  127. package/dist/types/suspension-rebuilder.d.ts +0 -67
  128. package/dist/types/suspension-rebuilder.d.ts.map +0 -1
  129. package/dist/types/utils/deferred.d.ts +0 -7
  130. package/dist/types/utils/deferred.d.ts.map +0 -1
  131. package/src/__tests__/suspension-rebuilder.test.ts +0 -404
  132. package/src/step-executors/suspension-continuation.ts +0 -31
  133. package/src/suspension-rebuilder.ts +0 -446
  134. package/src/utils/deferred.ts +0 -23
@@ -4,13 +4,31 @@
4
4
  * Full terms: see LICENSE.md.
5
5
  */
6
6
 
7
- import { getAbortReason, throwIfAborted } from '../errors';
8
- import type { RuntimeSuspensionRequest } from '../runner-runtime-control';
7
+ import {
8
+ buildWaitId,
9
+ type RecordedResult,
10
+ type TaskFrame,
11
+ type WaitInfo,
12
+ } from '../checkpoint';
13
+ import {
14
+ createLinkedAbortController,
15
+ getAbortReason,
16
+ isWorkflowResumeRejectedError,
17
+ throwIfAborted,
18
+ WorkflowCancellationError,
19
+ type WorkflowResumeRejectedError,
20
+ } from '../errors';
21
+ import type {
22
+ RunnerRuntimeControl,
23
+ RuntimeSuspensionRequest,
24
+ StepReplaySeed,
25
+ } from '../runner-runtime-control';
26
+ import { cloneAsJson, cloneValue } from '../utils/clone';
27
+ import type { StepInfo } from '../workflow-event-emitter';
9
28
  import type {
10
29
  CompiledTask,
11
30
  EvaluationScope,
12
31
  ExecutionState,
13
- Suspension,
14
32
  TaskStep,
15
33
  } from '../workflow-types';
16
34
  import { evaluateMapping } from '../workflow-values';
@@ -24,63 +42,102 @@ type TaskProgressOutcome =
24
42
  | { type: 'suspended'; request: RuntimeSuspensionRequest };
25
43
 
26
44
  /**
27
- * Execute a task step by running its task and handling suspension or output mapping.
45
+ * Execute a task step, returning a frame when its action suspends.
46
+ *
47
+ * Given a frame, the step either stays parked (its wait is not resolved by
48
+ * this pass) or re-runs its action body: earlier `suspend()` calls resolve
49
+ * from the frame, including the one this pass resolved. A body that refuses
50
+ * that payload returns the frame unchanged, so the wait stays open.
28
51
  *
29
52
  * @param env Executor environment with compiled workflow and helpers.
30
53
  * @param step The compiled task step to execute.
31
54
  * @param state Mutable workflow execution state.
32
55
  * @param _path Location of the step within the workflow (unused in this executor).
33
- * @returns A suspension if the task pauses execution, otherwise void.
56
+ * @param frame Frame returned when this step previously suspended.
57
+ * @returns A frame if the task suspends, otherwise void.
34
58
  */
35
59
  export async function executeTaskStep(
36
60
  env: StepExecutorEnv,
37
61
  step: TaskStep,
38
62
  state: ExecutionState,
39
63
  _path: Array<number | string>,
40
- ): Promise<Suspension | void> {
64
+ frame?: TaskFrame,
65
+ ): Promise<TaskFrame | void> {
41
66
  void _path;
42
67
  const task = env.compiled.tasks[step.taskName];
43
68
  if (!task) {
44
69
  throw new Error(`Task "${step.taskName}" is not defined.`);
45
70
  }
46
71
 
72
+ // A parked wait that this pass does not resolve stays exactly as it was.
73
+ if (frame && !env.resolutions.has(frame.wait.waitId)) {
74
+ return frame;
75
+ }
76
+
47
77
  const stepInfo = env.buildInstanceStepInfo(step, state.iterationStack);
48
78
  if (env.signal.aborted) {
49
79
  const error = getAbortReason(env.signal);
50
- recordTaskCancellation(env, stepInfo, error);
80
+ recordTaskCancellation(env, stepInfo, error, frame?.wait);
51
81
  throw error;
52
82
  }
53
83
 
54
- const scope: EvaluationScope = {
55
- input: state.input,
56
- context: env.context.state,
57
- output: state.output,
58
- iteration: state.iteration,
59
- accumulator: state.accumulator,
60
- };
61
- const inputs = await evaluateMapping(task.inputs, scope);
84
+ // Resumed bodies reuse the inputs they first ran with: re-evaluating could
85
+ // differ, e.g. when an expression depends on the event that woke the run.
86
+ const inputs = frame
87
+ ? cloneValue(frame.inputs)
88
+ : await evaluateMapping(task.inputs, buildScope(env, state));
62
89
  if (env.signal.aborted) {
63
90
  const error = getAbortReason(env.signal);
64
- recordTaskCancellation(env, stepInfo, error);
91
+ recordTaskCancellation(env, stepInfo, error, frame?.wait);
65
92
  throw error;
66
93
  }
67
-
94
+ // Kept apart from the object the body gets, so that a body changing its
95
+ // inputs cannot change the inputs every later pass replays.
96
+ const recordedInputs = frame ? frame.inputs : copyInputs(inputs);
97
+ const resumeData = frame ? env.resolutions.get(frame.wait.waitId) : undefined;
98
+ const seed: StepReplaySeed | undefined = frame
99
+ ? {
100
+ awaitResults: {
101
+ ...readRecordedResults(frame.awaitResults),
102
+ [frame.wait.suspendKey]: resumeData,
103
+ },
104
+ expected: {
105
+ suspendKey: frame.wait.suspendKey,
106
+ reason: frame.wait.reason,
107
+ },
108
+ }
109
+ : undefined;
68
110
  const stepExecution = env.recordStepExecution(stepInfo, {
69
111
  action: task.actionName,
70
112
  status: 'running',
71
113
  startedAt: Date.now(),
114
+ endedAt: undefined,
115
+ reason: undefined,
72
116
  input: inputs,
73
117
  context: { before: env.context.snapshot() },
74
118
  });
75
- env.beginStepExecution?.(stepInfo.id);
76
- env.setCurrentStep(stepInfo);
119
+ env.runtime.beginStep(stepInfo, { seed });
77
120
  env.markSnapshot(stepInfo, 'running');
78
- env.emit('hook:step:start', {
79
- runId: env.runId,
80
- step: stepInfo,
81
- stepExecution,
82
- });
121
+ if (frame) {
122
+ env.emit('hook:step:resumed', {
123
+ runId: env.runId,
124
+ step: stepInfo,
125
+ stepExecution,
126
+ wait: frame.wait,
127
+ resumeData,
128
+ });
129
+ } else {
130
+ env.emit('hook:step:start', {
131
+ runId: env.runId,
132
+ step: stepInfo,
133
+ stepExecution,
134
+ });
135
+ }
83
136
 
137
+ // Each action gets its own signal so a suspension can stop its body
138
+ // without cancelling anything else.
139
+ const { controller, unlink } = createLinkedAbortController(env.signal);
140
+ let outcome: TaskProgressOutcome;
84
141
  try {
85
142
  throwIfAborted(env.signal);
86
143
 
@@ -90,77 +147,115 @@ export async function executeTaskStep(
90
147
  env.context,
91
148
  task.settings,
92
149
  task.bindings,
93
- env.signal,
150
+ controller.signal,
94
151
  ),
95
152
  );
96
- const outcome = await waitForTaskProgress(env, stepInfo.id, actionPromise);
153
+ outcome = await waitForTaskProgress(
154
+ controller.signal,
155
+ env.runtime,
156
+ actionPromise,
157
+ );
158
+ } catch (error) {
159
+ env.runtime.endStep();
160
+ throw error;
161
+ } finally {
162
+ unlink();
163
+ }
97
164
 
98
- if (outcome.type === 'completed') {
99
- await completeTask(
100
- env,
101
- stepInfo.id,
102
- stepInfo,
103
- task,
104
- state,
105
- outcome.value,
165
+ switch (outcome.type) {
166
+ case 'suspended':
167
+ env.runtime.endStep();
168
+ // The body is parked on a promise that never settles. Aborting it clears
169
+ // its timeout and stops its retry loop; resuming re-runs it instead.
170
+ controller.abort(
171
+ new WorkflowCancellationError(`Step "${stepInfo.id}" suspended.`),
106
172
  );
107
173
 
174
+ return suspendTask(env, step, stepInfo, recordedInputs, outcome.request);
175
+ case 'completed':
176
+ try {
177
+ env.runtime.endStep({ completed: true });
178
+ } catch (error) {
179
+ recordTaskFailure(env, stepInfo, error);
180
+ throw error;
181
+ }
182
+
183
+ await completeTask(env, stepInfo, task, state, outcome.value);
184
+
108
185
  return undefined;
109
- }
186
+ case 'failed': {
187
+ const { error } = outcome;
188
+ // Only a body that already read the resolved payload can refuse it.
189
+ const rejected =
190
+ frame !== undefined &&
191
+ isWorkflowResumeRejectedError(error) &&
192
+ env.runtime.hasReachedResolvedSuspension();
193
+ env.runtime.endStep();
194
+ if (rejected) {
195
+ return keepWaiting(env, stepInfo, frame, error);
196
+ }
110
197
 
111
- if (outcome.type === 'failed') {
112
- env.clearStepSuspensions(stepInfo.id, outcome.error);
113
- recordTaskFailure(env, stepInfo, outcome.error);
114
- throw outcome.error;
198
+ recordTaskFailure(env, stepInfo, error);
199
+ throw error;
115
200
  }
116
-
117
- if (outcome.type === 'cancelled') {
118
- env.clearStepSuspensions(stepInfo.id, outcome.error);
119
- recordTaskCancellation(env, stepInfo, outcome.error);
201
+ case 'cancelled':
202
+ env.runtime.endStep();
203
+ recordTaskCancellation(env, stepInfo, outcome.error, frame?.wait);
120
204
  throw outcome.error;
121
- }
122
-
123
- return buildSuspensionContinuation(
124
- env,
125
- stepInfo.id,
126
- stepInfo,
127
- task,
128
- state,
129
- actionPromise,
130
- outcome.request,
131
- );
132
- } finally {
133
- env.setCurrentStep(undefined);
134
205
  }
135
206
  }
136
207
 
137
- const waitForTaskProgress = async (
208
+ /**
209
+ * Copy the inputs a body first runs with, the way the checkpoint stores them.
210
+ * Inputs JSON cannot encode are returned as they are: building the checkpoint
211
+ * reports them if the step suspends.
212
+ */
213
+ const copyInputs = (
214
+ inputs: Record<string, unknown>,
215
+ ): Record<string, unknown> => {
216
+ try {
217
+ return cloneAsJson(inputs);
218
+ } catch {
219
+ return inputs;
220
+ }
221
+ };
222
+ const buildScope = (
138
223
  env: StepExecutorEnv,
139
- stepId: string,
224
+ state: ExecutionState,
225
+ ): EvaluationScope => ({
226
+ input: state.input,
227
+ context: env.context.state,
228
+ output: state.output,
229
+ iteration: state.iteration,
230
+ accumulator: state.accumulator,
231
+ });
232
+ const waitForTaskProgress = async (
233
+ signal: AbortSignal,
234
+ runtime: RunnerRuntimeControl,
140
235
  actionPromise: Promise<unknown>,
141
236
  ): Promise<TaskProgressOutcome> => {
142
237
  const completion = actionPromise.then(
143
238
  (value): TaskProgressOutcome => ({ type: 'completed', value }),
144
239
  (error): TaskProgressOutcome => ({ type: 'failed', error }),
145
240
  );
146
- const suspension = env
147
- .waitForStepSuspension(stepId)
241
+ const suspension = runtime
242
+ .waitForSuspension()
148
243
  .then<TaskProgressOutcome>((request) => ({ type: 'suspended', request }));
149
244
  let cleanupCancellation = () => undefined;
150
245
  const cancellation = new Promise<TaskProgressOutcome>((resolve) => {
151
- if (env.signal.aborted) {
152
- resolve({ type: 'cancelled', error: getAbortReason(env.signal) });
246
+ if (signal.aborted) {
247
+ resolve({ type: 'cancelled', error: getAbortReason(signal) });
153
248
 
154
249
  return;
155
250
  }
156
251
 
157
252
  const onAbort = () => {
158
- resolve({ type: 'cancelled', error: getAbortReason(env.signal) });
253
+ resolve({ type: 'cancelled', error: getAbortReason(signal) });
159
254
  };
160
255
 
161
- env.signal.addEventListener('abort', onAbort, { once: true });
256
+ signal.addEventListener('abort', onAbort, { once: true });
162
257
  cleanupCancellation = () => {
163
- env.signal.removeEventListener('abort', onAbort);
258
+ signal.removeEventListener('abort', onAbort);
164
259
  };
165
260
  });
166
261
 
@@ -172,8 +267,7 @@ const waitForTaskProgress = async (
172
267
  };
173
268
  const completeTask = async (
174
269
  env: StepExecutorEnv,
175
- stepId: string,
176
- stepInfo: Suspension['step'],
270
+ stepInfo: StepInfo,
177
271
  task: CompiledTask,
178
272
  state: ExecutionState,
179
273
  result: unknown,
@@ -191,102 +285,89 @@ const completeTask = async (
191
285
  step: stepInfo,
192
286
  stepExecution,
193
287
  });
194
- env.clearStepSuspensions(stepId);
195
288
  };
196
- const recordSuspension = (
289
+ const suspendTask = (
197
290
  env: StepExecutorEnv,
198
- stepInfo: Suspension['step'],
199
- reason?: string,
200
- data?: unknown,
201
- ) => {
291
+ step: TaskStep,
292
+ stepInfo: StepInfo,
293
+ inputs: Record<string, unknown>,
294
+ request: RuntimeSuspensionRequest,
295
+ ): TaskFrame => {
296
+ const wait: WaitInfo = {
297
+ waitId: buildWaitId(stepInfo.id, request.suspendKey),
298
+ step: stepInfo,
299
+ suspendKey: request.suspendKey,
300
+ reason: request.reason,
301
+ data: request.data,
302
+ ...(request.accepts ? { accepts: request.accepts } : {}),
303
+ ...(request.payloadOptional ? { payloadOptional: true } : {}),
304
+ };
202
305
  const stepExecution = env.recordStepExecution(stepInfo, {
203
306
  status: 'suspended',
204
307
  endedAt: Date.now(),
205
- reason,
308
+ reason: request.reason,
206
309
  context: { after: env.context.snapshot() },
207
310
  });
208
- env.markSnapshot(stepInfo, 'suspended', reason);
311
+ env.markSnapshot(stepInfo, 'suspended', request.reason);
209
312
  env.emit('hook:step:suspended', {
210
313
  runId: env.runId,
211
314
  step: stepInfo,
212
315
  stepExecution,
213
- reason,
214
- data,
316
+ wait,
215
317
  });
216
- };
217
- const buildSuspensionContinuation = (
218
- env: StepExecutorEnv,
219
- stepId: string,
220
- stepInfo: Suspension['step'],
221
- task: CompiledTask,
222
- state: ExecutionState,
223
- actionPromise: Promise<unknown>,
224
- request: RuntimeSuspensionRequest,
225
- ): Suspension => {
226
- recordSuspension(env, stepInfo, request.reason, request.data);
227
-
228
- let resumed = false;
229
318
 
230
319
  return {
320
+ kind: 'task',
321
+ stepId: step.id,
322
+ inputs,
323
+ awaitResults: recordResults(request.awaitResults),
324
+ wait,
325
+ };
326
+ };
327
+ /** Wrap each answer so that one without payload survives JSON. */
328
+ const recordResults = (
329
+ results: Record<string, unknown>,
330
+ ): Record<string, RecordedResult> =>
331
+ Object.fromEntries(
332
+ Object.entries(results).map(([key, value]) => [key, { value }]),
333
+ );
334
+ const readRecordedResults = (
335
+ recorded: Record<string, RecordedResult>,
336
+ ): Record<string, unknown> =>
337
+ Object.fromEntries(
338
+ Object.entries(recorded).map(([key, result]) => [key, result.value]),
339
+ );
340
+ /**
341
+ * Put a resumed step back in its suspended state after its body refused the
342
+ * resume payload, and hand back the frame it resumed from.
343
+ */
344
+ const keepWaiting = (
345
+ env: StepExecutorEnv,
346
+ stepInfo: StepInfo,
347
+ frame: TaskFrame,
348
+ error: WorkflowResumeRejectedError,
349
+ ): TaskFrame => {
350
+ const stepExecution = env.recordStepExecution(stepInfo, {
351
+ status: 'suspended',
352
+ endedAt: Date.now(),
353
+ reason: frame.wait.reason,
354
+ context: { after: env.context.snapshot() },
355
+ });
356
+ env.markSnapshot(stepInfo, 'suspended', frame.wait.reason);
357
+ env.emit('hook:step:resume_rejected', {
358
+ runId: env.runId,
231
359
  step: stepInfo,
232
- reason: request.reason,
233
- data: request.data,
234
- stepExecId: request.stepExecId,
235
- suspendIndex: request.suspendIndex,
236
- suspendKey: request.suspendKey,
237
- awaitResults: request.awaitResults,
238
- continue: async (resumeData: unknown) => {
239
- if (resumed) {
240
- throw new Error(
241
- `Suspension for step "${stepInfo.id}" has already been resumed.`,
242
- );
243
- }
244
-
245
- resumed = true;
246
- env.setCurrentStep(stepInfo);
247
- env.recordStepSuspendResult?.({
248
- stepId,
249
- stepExecId: request.stepExecId,
250
- suspendIndex: request.suspendIndex,
251
- suspendKey: request.suspendKey,
252
- resumeData,
253
- });
254
- request.resume.resolve(resumeData);
255
-
256
- let outcome: TaskProgressOutcome;
257
- try {
258
- outcome = await waitForTaskProgress(env, stepId, actionPromise);
259
- } finally {
260
- env.setCurrentStep(undefined);
261
- }
262
-
263
- if (outcome.type === 'suspended') {
264
- return buildSuspensionContinuation(
265
- env,
266
- stepId,
267
- stepInfo,
268
- task,
269
- state,
270
- actionPromise,
271
- outcome.request,
272
- );
273
- }
274
-
275
- if (outcome.type === 'completed') {
276
- await completeTask(env, stepId, stepInfo, task, state, outcome.value);
277
-
278
- return undefined;
279
- }
360
+ stepExecution,
361
+ wait: frame.wait,
362
+ error,
363
+ });
364
+ env.rejectResume({ waitId: frame.wait.waitId, error });
280
365
 
281
- env.clearStepSuspensions(stepId, outcome.error);
282
- recordTaskFailure(env, stepInfo, outcome.error);
283
- throw outcome.error;
284
- },
285
- };
366
+ return frame;
286
367
  };
287
368
  const recordTaskFailure = (
288
369
  env: StepExecutorEnv,
289
- stepInfo: Suspension['step'],
370
+ stepInfo: StepInfo,
290
371
  error: unknown,
291
372
  ) => {
292
373
  const normalizedError = normalizeError(error);
@@ -304,10 +385,15 @@ const recordTaskFailure = (
304
385
  error,
305
386
  });
306
387
  };
388
+ /**
389
+ * Record a cancelled task. A task cancelled while resolving a wait drops that
390
+ * wait, so the event carries it.
391
+ */
307
392
  const recordTaskCancellation = (
308
393
  env: StepExecutorEnv,
309
- stepInfo: Suspension['step'],
394
+ stepInfo: StepInfo,
310
395
  error: unknown,
396
+ wait?: WaitInfo,
311
397
  ) => {
312
398
  const normalizedError = normalizeError(error);
313
399
  const stepExecution = env.recordStepExecution(stepInfo, {
@@ -322,6 +408,7 @@ const recordTaskCancellation = (
322
408
  step: stepInfo,
323
409
  stepExecution,
324
410
  error,
411
+ ...(wait ? { wait } : {}),
325
412
  });
326
413
  };
327
414
  const normalizeError = (error: unknown): { message: string; stack?: string } =>
@@ -4,41 +4,48 @@
4
4
  * Full terms: see LICENSE.md.
5
5
  */
6
6
 
7
+ import type { SequenceFrame, StepFrame } from '../checkpoint';
7
8
  import type {
8
9
  ActionSnapshot,
9
10
  BaseWorkflowContext,
10
11
  StepExecutionRecord,
11
12
  } from '../context';
12
- import type {
13
- RuntimeResolvedSuspension,
14
- RuntimeStepReplaySeed,
15
- RuntimeSuspensionRequest,
16
- } from '../runner-runtime-control';
13
+ import type { RunnerRuntimeControl } from '../runner-runtime-control';
17
14
  import type { StepInfo, WorkflowEventMap } from '../workflow-event-emitter';
18
15
  import type {
19
16
  CompiledStep,
20
17
  CompiledTask,
21
18
  CompiledWorkflow,
22
19
  ExecutionState,
23
- Suspension,
20
+ ResumeRejection,
24
21
  } from '../workflow-types';
25
22
 
26
23
  export type StepExecutorEnvForkOverrides = {
27
24
  context?: BaseWorkflowContext;
28
25
  signal?: AbortSignal;
29
- setCurrentStep?: (step?: StepInfo) => void;
30
- captureTaskOutput?: (
31
- task: CompiledTask,
32
- state: ExecutionState,
33
- result: unknown,
34
- ) => Promise<void>;
26
+ runtime?: RunnerRuntimeControl;
35
27
  };
36
28
 
29
+ /**
30
+ * Everything a step executor needs from the runner.
31
+ *
32
+ * Executors return a frame when the step suspends and `undefined` when it
33
+ * completes. Passing that frame back in resumes the step where it stopped.
34
+ */
37
35
  export type StepExecutorEnv = {
38
36
  compiled: CompiledWorkflow;
39
37
  context: BaseWorkflowContext;
40
38
  signal: AbortSignal;
41
39
  runId?: string;
40
+ /** Suspension control of the concurrency scope this env runs in. */
41
+ runtime: RunnerRuntimeControl;
42
+ /** Resume payloads for the waits this execution pass satisfies, by wait id. */
43
+ resolutions: ReadonlyMap<string, unknown>;
44
+ /**
45
+ * Report that a resumed step refused its payload. The runner then leaves
46
+ * the run exactly as it was before this pass.
47
+ */
48
+ rejectResume: (rejection: ResumeRejection) => void;
42
49
  buildInstanceStepInfo: (
43
50
  step: CompiledStep,
44
51
  iterationStack: number[],
@@ -56,13 +63,6 @@ export type StepExecutorEnv = {
56
63
  event: K,
57
64
  payload: WorkflowEventMap[K],
58
65
  ) => void;
59
- setCurrentStep: (step?: StepInfo) => void;
60
- beginStepExecution?: (stepId: string) => string;
61
- waitForStepSuspension: (stepId: string) => Promise<RuntimeSuspensionRequest>;
62
- clearStepSuspensions: (stepId: string, error?: unknown) => void;
63
- primeStepResumeData: (stepId: string, resumeData: unknown) => void;
64
- prepareStepReplay?: (seed: RuntimeStepReplaySeed) => void;
65
- recordStepSuspendResult?: (params: RuntimeResolvedSuspension) => void;
66
66
  captureTaskOutput: (
67
67
  task: CompiledTask,
68
68
  state: ExecutionState,
@@ -72,12 +72,13 @@ export type StepExecutorEnv = {
72
72
  steps: CompiledStep[],
73
73
  state: ExecutionState,
74
74
  path: Array<number | string>,
75
- startIndex?: number,
76
- ) => Promise<Suspension | void>;
75
+ frame?: SequenceFrame,
76
+ ) => Promise<SequenceFrame | void>;
77
77
  executeStep: (
78
78
  step: CompiledStep,
79
79
  state: ExecutionState,
80
80
  path: Array<number | string>,
81
- ) => Promise<Suspension | void>;
81
+ frame?: StepFrame,
82
+ ) => Promise<StepFrame | void>;
82
83
  fork: (overrides: StepExecutorEnvForkOverrides) => StepExecutorEnv;
83
84
  };
@@ -0,0 +1,75 @@
1
+ /*
2
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
3
+ * Copyright (c) 2025 Hexastack.
4
+ * Full terms: see LICENSE.md.
5
+ */
6
+
7
+ /**
8
+ * Deep-clone a value, preferring `structuredClone` and falling back to a JSON
9
+ * round trip, then to a shallow copy for values neither can handle.
10
+ *
11
+ * @param value The value to clone.
12
+ * @returns A detached copy of the value.
13
+ */
14
+ export function cloneValue<T>(value: T): T {
15
+ if (value === undefined || value === null) {
16
+ return value;
17
+ }
18
+
19
+ if (typeof structuredClone === 'function') {
20
+ try {
21
+ return structuredClone(value);
22
+ } catch {
23
+ // Fall through to JSON clone below.
24
+ }
25
+ }
26
+
27
+ try {
28
+ return JSON.parse(JSON.stringify(value)) as T;
29
+ } catch {
30
+ if (Array.isArray(value)) {
31
+ return [...value] as T;
32
+ }
33
+
34
+ if (isRecord(value)) {
35
+ return { ...value } as T;
36
+ }
37
+
38
+ return value;
39
+ }
40
+ }
41
+
42
+ /**
43
+ * Copy a value through a JSON round trip, exactly as a host persisting it
44
+ * would: dates become ISO strings, and `undefined` values and functions are
45
+ * dropped.
46
+ *
47
+ * @param value The value to copy.
48
+ * @returns A detached, JSON-only copy of the value.
49
+ * @throws {TypeError} When JSON cannot encode the value (BigInt, cycles).
50
+ */
51
+ export function cloneAsJson<T>(value: T): T {
52
+ return JSON.parse(JSON.stringify(value)) as T;
53
+ }
54
+
55
+ /**
56
+ * Deep-clone a record.
57
+ *
58
+ * @param value The record to clone.
59
+ * @returns A detached copy of the record.
60
+ */
61
+ export function cloneRecord(
62
+ value: Record<string, unknown>,
63
+ ): Record<string, unknown> {
64
+ return cloneValue(value) as Record<string, unknown>;
65
+ }
66
+
67
+ /**
68
+ * Report whether a value is a plain (non-array) object.
69
+ *
70
+ * @param value The value to check.
71
+ * @returns True when the value is a non-null, non-array object.
72
+ */
73
+ export function isRecord(value: unknown): value is Record<string, unknown> {
74
+ return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
75
+ }