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