@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
@@ -3,98 +3,183 @@
3
3
  * Copyright (c) 2025 Hexastack.
4
4
  * Full terms: see LICENSE.md.
5
5
  */
6
- import { getAbortReason, throwIfAborted } from '../errors';
6
+ import { buildWaitId, } from '../checkpoint';
7
+ import { createLinkedAbortController, getAbortReason, isWorkflowResumeRejectedError, throwIfAborted, WorkflowCancellationError, } from '../errors';
8
+ import { cloneAsJson, cloneValue } from '../utils/clone';
7
9
  import { evaluateMapping } from '../workflow-values';
8
10
  /**
9
- * Execute a task step by running its task and handling suspension or output mapping.
11
+ * Execute a task step, returning a frame when its action suspends.
12
+ *
13
+ * Given a frame, the step either stays parked (its wait is not resolved by
14
+ * this pass) or re-runs its action body: earlier `suspend()` calls resolve
15
+ * from the frame, including the one this pass resolved. A body that refuses
16
+ * that payload returns the frame unchanged, so the wait stays open.
10
17
  *
11
18
  * @param env Executor environment with compiled workflow and helpers.
12
19
  * @param step The compiled task step to execute.
13
20
  * @param state Mutable workflow execution state.
14
21
  * @param _path Location of the step within the workflow (unused in this executor).
15
- * @returns A suspension if the task pauses execution, otherwise void.
22
+ * @param frame Frame returned when this step previously suspended.
23
+ * @returns A frame if the task suspends, otherwise void.
16
24
  */
17
- export async function executeTaskStep(env, step, state, _path) {
25
+ export async function executeTaskStep(env, step, state, _path, frame) {
18
26
  void _path;
19
27
  const task = env.compiled.tasks[step.taskName];
20
28
  if (!task) {
21
29
  throw new Error(`Task "${step.taskName}" is not defined.`);
22
30
  }
31
+ // A parked wait that this pass does not resolve stays exactly as it was.
32
+ if (frame && !env.resolutions.has(frame.wait.waitId)) {
33
+ return frame;
34
+ }
23
35
  const stepInfo = env.buildInstanceStepInfo(step, state.iterationStack);
24
36
  if (env.signal.aborted) {
25
37
  const error = getAbortReason(env.signal);
26
- recordTaskCancellation(env, stepInfo, error);
38
+ recordTaskCancellation(env, stepInfo, error, frame?.wait);
27
39
  throw error;
28
40
  }
29
- const scope = {
30
- input: state.input,
31
- context: env.context.state,
32
- output: state.output,
33
- iteration: state.iteration,
34
- accumulator: state.accumulator,
35
- };
36
- const inputs = await evaluateMapping(task.inputs, scope);
41
+ // Resumed bodies reuse the inputs they first ran with: re-evaluating could
42
+ // differ, e.g. when an expression depends on the event that woke the run.
43
+ const inputs = frame
44
+ ? cloneValue(frame.inputs)
45
+ : await evaluateMapping(task.inputs, buildScope(env, state));
37
46
  if (env.signal.aborted) {
38
47
  const error = getAbortReason(env.signal);
39
- recordTaskCancellation(env, stepInfo, error);
48
+ recordTaskCancellation(env, stepInfo, error, frame?.wait);
40
49
  throw error;
41
50
  }
51
+ // Kept apart from the object the body gets, so that a body changing its
52
+ // inputs cannot change the inputs every later pass replays.
53
+ const recordedInputs = frame ? frame.inputs : copyInputs(inputs);
54
+ const resumeData = frame ? env.resolutions.get(frame.wait.waitId) : undefined;
55
+ const seed = frame
56
+ ? {
57
+ awaitResults: {
58
+ ...readRecordedResults(frame.awaitResults),
59
+ [frame.wait.suspendKey]: resumeData,
60
+ },
61
+ expected: {
62
+ suspendKey: frame.wait.suspendKey,
63
+ reason: frame.wait.reason,
64
+ },
65
+ }
66
+ : undefined;
42
67
  const stepExecution = env.recordStepExecution(stepInfo, {
43
68
  action: task.actionName,
44
69
  status: 'running',
45
70
  startedAt: Date.now(),
71
+ endedAt: undefined,
72
+ reason: undefined,
46
73
  input: inputs,
47
74
  context: { before: env.context.snapshot() },
48
75
  });
49
- env.beginStepExecution?.(stepInfo.id);
50
- env.setCurrentStep(stepInfo);
76
+ env.runtime.beginStep(stepInfo, { seed });
51
77
  env.markSnapshot(stepInfo, 'running');
52
- env.emit('hook:step:start', {
53
- runId: env.runId,
54
- step: stepInfo,
55
- stepExecution,
56
- });
78
+ if (frame) {
79
+ env.emit('hook:step:resumed', {
80
+ runId: env.runId,
81
+ step: stepInfo,
82
+ stepExecution,
83
+ wait: frame.wait,
84
+ resumeData,
85
+ });
86
+ }
87
+ else {
88
+ env.emit('hook:step:start', {
89
+ runId: env.runId,
90
+ step: stepInfo,
91
+ stepExecution,
92
+ });
93
+ }
94
+ // Each action gets its own signal so a suspension can stop its body
95
+ // without cancelling anything else.
96
+ const { controller, unlink } = createLinkedAbortController(env.signal);
97
+ let outcome;
57
98
  try {
58
99
  throwIfAborted(env.signal);
59
- const actionPromise = Promise.resolve().then(() => task.action.run(inputs, env.context, task.settings, task.bindings, env.signal));
60
- const outcome = await waitForTaskProgress(env, stepInfo.id, actionPromise);
61
- if (outcome.type === 'completed') {
62
- await completeTask(env, stepInfo.id, stepInfo, task, state, outcome.value);
100
+ const actionPromise = Promise.resolve().then(() => task.action.run(inputs, env.context, task.settings, task.bindings, controller.signal));
101
+ outcome = await waitForTaskProgress(controller.signal, env.runtime, actionPromise);
102
+ }
103
+ catch (error) {
104
+ env.runtime.endStep();
105
+ throw error;
106
+ }
107
+ finally {
108
+ unlink();
109
+ }
110
+ switch (outcome.type) {
111
+ case 'suspended':
112
+ env.runtime.endStep();
113
+ // The body is parked on a promise that never settles. Aborting it clears
114
+ // its timeout and stops its retry loop; resuming re-runs it instead.
115
+ controller.abort(new WorkflowCancellationError(`Step "${stepInfo.id}" suspended.`));
116
+ return suspendTask(env, step, stepInfo, recordedInputs, outcome.request);
117
+ case 'completed':
118
+ try {
119
+ env.runtime.endStep({ completed: true });
120
+ }
121
+ catch (error) {
122
+ recordTaskFailure(env, stepInfo, error);
123
+ throw error;
124
+ }
125
+ await completeTask(env, stepInfo, task, state, outcome.value);
63
126
  return undefined;
127
+ case 'failed': {
128
+ const { error } = outcome;
129
+ // Only a body that already read the resolved payload can refuse it.
130
+ const rejected = frame !== undefined &&
131
+ isWorkflowResumeRejectedError(error) &&
132
+ env.runtime.hasReachedResolvedSuspension();
133
+ env.runtime.endStep();
134
+ if (rejected) {
135
+ return keepWaiting(env, stepInfo, frame, error);
136
+ }
137
+ recordTaskFailure(env, stepInfo, error);
138
+ throw error;
64
139
  }
65
- if (outcome.type === 'failed') {
66
- env.clearStepSuspensions(stepInfo.id, outcome.error);
67
- recordTaskFailure(env, stepInfo, outcome.error);
68
- throw outcome.error;
69
- }
70
- if (outcome.type === 'cancelled') {
71
- env.clearStepSuspensions(stepInfo.id, outcome.error);
72
- recordTaskCancellation(env, stepInfo, outcome.error);
140
+ case 'cancelled':
141
+ env.runtime.endStep();
142
+ recordTaskCancellation(env, stepInfo, outcome.error, frame?.wait);
73
143
  throw outcome.error;
74
- }
75
- return buildSuspensionContinuation(env, stepInfo.id, stepInfo, task, state, actionPromise, outcome.request);
76
- }
77
- finally {
78
- env.setCurrentStep(undefined);
79
144
  }
80
145
  }
81
- const waitForTaskProgress = async (env, stepId, actionPromise) => {
146
+ /**
147
+ * Copy the inputs a body first runs with, the way the checkpoint stores them.
148
+ * Inputs JSON cannot encode are returned as they are: building the checkpoint
149
+ * reports them if the step suspends.
150
+ */
151
+ const copyInputs = (inputs) => {
152
+ try {
153
+ return cloneAsJson(inputs);
154
+ }
155
+ catch {
156
+ return inputs;
157
+ }
158
+ };
159
+ const buildScope = (env, state) => ({
160
+ input: state.input,
161
+ context: env.context.state,
162
+ output: state.output,
163
+ iteration: state.iteration,
164
+ accumulator: state.accumulator,
165
+ });
166
+ const waitForTaskProgress = async (signal, runtime, actionPromise) => {
82
167
  const completion = actionPromise.then((value) => ({ type: 'completed', value }), (error) => ({ type: 'failed', error }));
83
- const suspension = env
84
- .waitForStepSuspension(stepId)
168
+ const suspension = runtime
169
+ .waitForSuspension()
85
170
  .then((request) => ({ type: 'suspended', request }));
86
171
  let cleanupCancellation = () => undefined;
87
172
  const cancellation = new Promise((resolve) => {
88
- if (env.signal.aborted) {
89
- resolve({ type: 'cancelled', error: getAbortReason(env.signal) });
173
+ if (signal.aborted) {
174
+ resolve({ type: 'cancelled', error: getAbortReason(signal) });
90
175
  return;
91
176
  }
92
177
  const onAbort = () => {
93
- resolve({ type: 'cancelled', error: getAbortReason(env.signal) });
178
+ resolve({ type: 'cancelled', error: getAbortReason(signal) });
94
179
  };
95
- env.signal.addEventListener('abort', onAbort, { once: true });
180
+ signal.addEventListener('abort', onAbort, { once: true });
96
181
  cleanupCancellation = () => {
97
- env.signal.removeEventListener('abort', onAbort);
182
+ signal.removeEventListener('abort', onAbort);
98
183
  };
99
184
  });
100
185
  try {
@@ -104,7 +189,7 @@ const waitForTaskProgress = async (env, stepId, actionPromise) => {
104
189
  cleanupCancellation();
105
190
  }
106
191
  };
107
- const completeTask = async (env, stepId, stepInfo, task, state, result) => {
192
+ const completeTask = async (env, stepInfo, task, state, result) => {
108
193
  await env.captureTaskOutput(task, state, result);
109
194
  const stepExecution = env.recordStepExecution(stepInfo, {
110
195
  status: 'completed',
@@ -118,69 +203,63 @@ const completeTask = async (env, stepId, stepInfo, task, state, result) => {
118
203
  step: stepInfo,
119
204
  stepExecution,
120
205
  });
121
- env.clearStepSuspensions(stepId);
122
206
  };
123
- const recordSuspension = (env, stepInfo, reason, data) => {
207
+ const suspendTask = (env, step, stepInfo, inputs, request) => {
208
+ const wait = {
209
+ waitId: buildWaitId(stepInfo.id, request.suspendKey),
210
+ step: stepInfo,
211
+ suspendKey: request.suspendKey,
212
+ reason: request.reason,
213
+ data: request.data,
214
+ ...(request.accepts ? { accepts: request.accepts } : {}),
215
+ ...(request.payloadOptional ? { payloadOptional: true } : {}),
216
+ };
124
217
  const stepExecution = env.recordStepExecution(stepInfo, {
125
218
  status: 'suspended',
126
219
  endedAt: Date.now(),
127
- reason,
220
+ reason: request.reason,
128
221
  context: { after: env.context.snapshot() },
129
222
  });
130
- env.markSnapshot(stepInfo, 'suspended', reason);
223
+ env.markSnapshot(stepInfo, 'suspended', request.reason);
131
224
  env.emit('hook:step:suspended', {
132
225
  runId: env.runId,
133
226
  step: stepInfo,
134
227
  stepExecution,
135
- reason,
136
- data,
228
+ wait,
137
229
  });
138
- };
139
- const buildSuspensionContinuation = (env, stepId, stepInfo, task, state, actionPromise, request) => {
140
- recordSuspension(env, stepInfo, request.reason, request.data);
141
- let resumed = false;
142
230
  return {
143
- step: stepInfo,
144
- reason: request.reason,
145
- data: request.data,
146
- stepExecId: request.stepExecId,
147
- suspendIndex: request.suspendIndex,
148
- suspendKey: request.suspendKey,
149
- awaitResults: request.awaitResults,
150
- continue: async (resumeData) => {
151
- if (resumed) {
152
- throw new Error(`Suspension for step "${stepInfo.id}" has already been resumed.`);
153
- }
154
- resumed = true;
155
- env.setCurrentStep(stepInfo);
156
- env.recordStepSuspendResult?.({
157
- stepId,
158
- stepExecId: request.stepExecId,
159
- suspendIndex: request.suspendIndex,
160
- suspendKey: request.suspendKey,
161
- resumeData,
162
- });
163
- request.resume.resolve(resumeData);
164
- let outcome;
165
- try {
166
- outcome = await waitForTaskProgress(env, stepId, actionPromise);
167
- }
168
- finally {
169
- env.setCurrentStep(undefined);
170
- }
171
- if (outcome.type === 'suspended') {
172
- return buildSuspensionContinuation(env, stepId, stepInfo, task, state, actionPromise, outcome.request);
173
- }
174
- if (outcome.type === 'completed') {
175
- await completeTask(env, stepId, stepInfo, task, state, outcome.value);
176
- return undefined;
177
- }
178
- env.clearStepSuspensions(stepId, outcome.error);
179
- recordTaskFailure(env, stepInfo, outcome.error);
180
- throw outcome.error;
181
- },
231
+ kind: 'task',
232
+ stepId: step.id,
233
+ inputs,
234
+ awaitResults: recordResults(request.awaitResults),
235
+ wait,
182
236
  };
183
237
  };
238
+ /** Wrap each answer so that one without payload survives JSON. */
239
+ const recordResults = (results) => Object.fromEntries(Object.entries(results).map(([key, value]) => [key, { value }]));
240
+ const readRecordedResults = (recorded) => Object.fromEntries(Object.entries(recorded).map(([key, result]) => [key, result.value]));
241
+ /**
242
+ * Put a resumed step back in its suspended state after its body refused the
243
+ * resume payload, and hand back the frame it resumed from.
244
+ */
245
+ const keepWaiting = (env, stepInfo, frame, error) => {
246
+ const stepExecution = env.recordStepExecution(stepInfo, {
247
+ status: 'suspended',
248
+ endedAt: Date.now(),
249
+ reason: frame.wait.reason,
250
+ context: { after: env.context.snapshot() },
251
+ });
252
+ env.markSnapshot(stepInfo, 'suspended', frame.wait.reason);
253
+ env.emit('hook:step:resume_rejected', {
254
+ runId: env.runId,
255
+ step: stepInfo,
256
+ stepExecution,
257
+ wait: frame.wait,
258
+ error,
259
+ });
260
+ env.rejectResume({ waitId: frame.wait.waitId, error });
261
+ return frame;
262
+ };
184
263
  const recordTaskFailure = (env, stepInfo, error) => {
185
264
  const normalizedError = normalizeError(error);
186
265
  const stepExecution = env.recordStepExecution(stepInfo, {
@@ -197,7 +276,11 @@ const recordTaskFailure = (env, stepInfo, error) => {
197
276
  error,
198
277
  });
199
278
  };
200
- const recordTaskCancellation = (env, stepInfo, error) => {
279
+ /**
280
+ * Record a cancelled task. A task cancelled while resolving a wait drops that
281
+ * wait, so the event carries it.
282
+ */
283
+ const recordTaskCancellation = (env, stepInfo, error, wait) => {
201
284
  const normalizedError = normalizeError(error);
202
285
  const stepExecution = env.recordStepExecution(stepInfo, {
203
286
  status: 'cancelled',
@@ -211,6 +294,7 @@ const recordTaskCancellation = (env, stepInfo, error) => {
211
294
  step: stepInfo,
212
295
  stepExecution,
213
296
  error,
297
+ ...(wait ? { wait } : {}),
214
298
  });
215
299
  };
216
300
  const normalizeError = (error) => error instanceof Error
@@ -0,0 +1,67 @@
1
+ /*
2
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
3
+ * Copyright (c) 2025 Hexastack.
4
+ * Full terms: see LICENSE.md.
5
+ */
6
+ /**
7
+ * Deep-clone a value, preferring `structuredClone` and falling back to a JSON
8
+ * round trip, then to a shallow copy for values neither can handle.
9
+ *
10
+ * @param value The value to clone.
11
+ * @returns A detached copy of the value.
12
+ */
13
+ export function cloneValue(value) {
14
+ if (value === undefined || value === null) {
15
+ return value;
16
+ }
17
+ if (typeof structuredClone === 'function') {
18
+ try {
19
+ return structuredClone(value);
20
+ }
21
+ catch {
22
+ // Fall through to JSON clone below.
23
+ }
24
+ }
25
+ try {
26
+ return JSON.parse(JSON.stringify(value));
27
+ }
28
+ catch {
29
+ if (Array.isArray(value)) {
30
+ return [...value];
31
+ }
32
+ if (isRecord(value)) {
33
+ return { ...value };
34
+ }
35
+ return value;
36
+ }
37
+ }
38
+ /**
39
+ * Copy a value through a JSON round trip, exactly as a host persisting it
40
+ * would: dates become ISO strings, and `undefined` values and functions are
41
+ * dropped.
42
+ *
43
+ * @param value The value to copy.
44
+ * @returns A detached, JSON-only copy of the value.
45
+ * @throws {TypeError} When JSON cannot encode the value (BigInt, cycles).
46
+ */
47
+ export function cloneAsJson(value) {
48
+ return JSON.parse(JSON.stringify(value));
49
+ }
50
+ /**
51
+ * Deep-clone a record.
52
+ *
53
+ * @param value The record to clone.
54
+ * @returns A detached copy of the record.
55
+ */
56
+ export function cloneRecord(value) {
57
+ return cloneValue(value);
58
+ }
59
+ /**
60
+ * Report whether a value is a plain (non-array) object.
61
+ *
62
+ * @param value The value to check.
63
+ * @returns True when the value is a non-null, non-array object.
64
+ */
65
+ export function isRecord(value) {
66
+ return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
67
+ }
@@ -0,0 +1,134 @@
1
+ /*
2
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
3
+ * Copyright (c) 2025 Hexastack.
4
+ * Full terms: see LICENSE.md.
5
+ */
6
+ import { StepType } from './workflow-event-emitter';
7
+ /** Separator between fingerprint parts; never produced by the parts themselves. */
8
+ const PART_SEPARATOR = '~|~';
9
+ /** Fingerprints are pure functions of the compiled graph, so compute each once. */
10
+ const fingerprintCache = new WeakMap();
11
+ /**
12
+ * Fingerprint the parts of a compiled workflow that a checkpoint depends on.
13
+ *
14
+ * Hashing step ids alone is not enough: a changed `until`, `while`, branch
15
+ * condition or `inputs` mapping keeps every id stable while changing what the
16
+ * resumed run actually does. Labels are included because `buildStepId`
17
+ * embeds them, so renaming a task changes every downstream step id.
18
+ *
19
+ * @param compiled The compiled workflow to fingerprint.
20
+ * @returns A short, stable hash of the resume-relevant definition surface.
21
+ */
22
+ export const fingerprintWorkflow = (compiled) => {
23
+ const cached = fingerprintCache.get(compiled);
24
+ if (cached !== undefined) {
25
+ return cached;
26
+ }
27
+ const parts = [];
28
+ collectSteps(compiled, compiled.flow, parts);
29
+ parts.push('outputs', ...describeMapping(compiled.outputMapping));
30
+ const fingerprint = hash(parts.join(PART_SEPARATOR));
31
+ fingerprintCache.set(compiled, fingerprint);
32
+ return fingerprint;
33
+ };
34
+ /**
35
+ * Append a canonical description of each step, depth first.
36
+ *
37
+ * @param compiled The compiled workflow, used to resolve task definitions.
38
+ * @param steps Steps to describe.
39
+ * @param parts Accumulator receiving the description fragments.
40
+ */
41
+ const collectSteps = (compiled, steps, parts) => {
42
+ for (const step of steps) {
43
+ parts.push(step.type, step.id, step.label);
44
+ switch (step.type) {
45
+ case StepType.Task: {
46
+ const task = compiled.tasks[step.taskName];
47
+ parts.push(step.taskName, task?.actionName ?? '');
48
+ parts.push(...describeMapping(task?.inputs));
49
+ break;
50
+ }
51
+ case StepType.Parallel:
52
+ parts.push(step.strategy);
53
+ collectSteps(compiled, step.steps, parts);
54
+ break;
55
+ case StepType.Conditional:
56
+ for (const branch of step.branches) {
57
+ parts.push(branch.id, describeValue(branch.condition));
58
+ collectSteps(compiled, branch.steps, parts);
59
+ }
60
+ break;
61
+ case StepType.Loop:
62
+ parts.push(step.loopType, step.name ?? '');
63
+ parts.push(step.accumulate
64
+ ? `${step.accumulate.as}=${stringify(step.accumulate.initial)}:${describeValue(step.accumulate.merge)}`
65
+ : '');
66
+ if (step.loopType === 'for_each') {
67
+ parts.push(step.forEach.item, describeValue(step.forEach.in));
68
+ parts.push(describeValue(step.until));
69
+ }
70
+ else {
71
+ parts.push(describeValue(step.while));
72
+ }
73
+ collectSteps(compiled, step.steps, parts);
74
+ break;
75
+ }
76
+ }
77
+ };
78
+ /**
79
+ * Describe a compiled mapping in a key-stable order.
80
+ *
81
+ * @param mapping The mapping to describe.
82
+ * @returns One fragment per mapped key.
83
+ */
84
+ const describeMapping = (mapping) => {
85
+ if (!mapping) {
86
+ return [];
87
+ }
88
+ return Object.keys(mapping)
89
+ .sort()
90
+ .map((key) => `${key}=${describeValue(mapping[key])}`);
91
+ };
92
+ /**
93
+ * Describe a compiled value by its authored source, not its compiled form.
94
+ *
95
+ * @param value The compiled value.
96
+ * @returns A stable textual description.
97
+ */
98
+ const describeValue = (value) => {
99
+ if (!value) {
100
+ return '';
101
+ }
102
+ return value.kind === 'expression'
103
+ ? `=${value.source}`
104
+ : stringify(value.value);
105
+ };
106
+ const stringify = (value) => {
107
+ try {
108
+ return JSON.stringify(value) ?? String(value);
109
+ }
110
+ catch {
111
+ return String(value);
112
+ }
113
+ };
114
+ /**
115
+ * Hash a string with two FNV-1a style passes under different constants.
116
+ *
117
+ * Kept dependency-free on purpose: the package is consumed from browser
118
+ * bundles, so `node:crypto` is not available.
119
+ *
120
+ * @param value The canonical description to hash.
121
+ * @returns A 16-character hexadecimal digest.
122
+ */
123
+ const hash = (value) => {
124
+ let low = 0x811c9dc5;
125
+ let high = 0x01000193;
126
+ for (let index = 0; index < value.length; index += 1) {
127
+ const code = value.charCodeAt(index);
128
+ low ^= code;
129
+ low = Math.imul(low, 0x01000193) >>> 0;
130
+ high ^= code + index;
131
+ high = Math.imul(high, 0x85ebca6b) >>> 0;
132
+ }
133
+ return `${low.toString(16).padStart(8, '0')}${high.toString(16).padStart(8, '0')}`;
134
+ };