@hexabot-ai/agentic 3.5.0-beta.0 → 3.6.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 (145) hide show
  1. package/README.md +12 -3
  2. package/dist/cjs/action/abstract-action.js +51 -35
  3. package/dist/cjs/bindings/base-binding.js +229 -211
  4. package/dist/cjs/checkpoint.js +1 -1
  5. package/dist/cjs/context.js +2 -3
  6. package/dist/cjs/dsl.types.js +44 -90
  7. package/dist/cjs/errors.js +13 -1
  8. package/dist/cjs/index.js +3 -1
  9. package/dist/cjs/resume-payload.js +11 -1
  10. package/dist/cjs/runner-runtime-control.js +39 -27
  11. package/dist/cjs/step-executors/conditional-executor.js +2 -7
  12. package/dist/cjs/step-executors/loop-executor.js +14 -28
  13. package/dist/cjs/step-executors/parallel-executor.js +14 -25
  14. package/dist/cjs/step-executors/scope.js +25 -0
  15. package/dist/cjs/step-executors/skip-helpers.js +26 -34
  16. package/dist/cjs/step-executors/task-executor.js +58 -69
  17. package/dist/cjs/utils/flow-steps.js +41 -0
  18. package/dist/cjs/utils/naming.js +10 -10
  19. package/dist/cjs/utils/object-path.js +51 -0
  20. package/dist/cjs/utils/timeout.js +16 -39
  21. package/dist/cjs/validation-issue.js +14 -1
  22. package/dist/cjs/workflow-compiler.js +52 -96
  23. package/dist/cjs/workflow-fingerprint.js +22 -11
  24. package/dist/cjs/workflow-runner.js +19 -25
  25. package/dist/cjs/workflow-values.js +9 -7
  26. package/dist/cjs/workflow.js +44 -103
  27. package/dist/esm/action/abstract-action.js +51 -35
  28. package/dist/esm/bindings/base-binding.js +229 -211
  29. package/dist/esm/checkpoint.js +2 -2
  30. package/dist/esm/context.js +2 -3
  31. package/dist/esm/dsl.types.js +42 -88
  32. package/dist/esm/errors.js +11 -0
  33. package/dist/esm/index.js +2 -2
  34. package/dist/esm/resume-payload.js +10 -1
  35. package/dist/esm/runner-runtime-control.js +39 -27
  36. package/dist/esm/step-executors/conditional-executor.js +2 -7
  37. package/dist/esm/step-executors/loop-executor.js +14 -28
  38. package/dist/esm/step-executors/parallel-executor.js +14 -25
  39. package/dist/esm/step-executors/scope.js +21 -0
  40. package/dist/esm/step-executors/skip-helpers.js +27 -35
  41. package/dist/esm/step-executors/task-executor.js +58 -69
  42. package/dist/esm/utils/flow-steps.js +37 -0
  43. package/dist/esm/utils/naming.js +9 -9
  44. package/dist/esm/utils/object-path.js +46 -0
  45. package/dist/esm/utils/timeout.js +16 -39
  46. package/dist/esm/validation-issue.js +11 -0
  47. package/dist/esm/workflow-compiler.js +50 -95
  48. package/dist/esm/workflow-fingerprint.js +22 -11
  49. package/dist/esm/workflow-runner.js +21 -27
  50. package/dist/esm/workflow-values.js +7 -6
  51. package/dist/esm/workflow.js +43 -103
  52. package/dist/types/action/abstract-action.d.ts +7 -1
  53. package/dist/types/action/abstract-action.d.ts.map +1 -1
  54. package/dist/types/bindings/base-binding.d.ts +10 -0
  55. package/dist/types/bindings/base-binding.d.ts.map +1 -1
  56. package/dist/types/context.d.ts +2 -3
  57. package/dist/types/context.d.ts.map +1 -1
  58. package/dist/types/dsl.types.d.ts +7 -12
  59. package/dist/types/dsl.types.d.ts.map +1 -1
  60. package/dist/types/errors.d.ts +9 -0
  61. package/dist/types/errors.d.ts.map +1 -1
  62. package/dist/types/index.d.ts +2 -2
  63. package/dist/types/index.d.ts.map +1 -1
  64. package/dist/types/resume-payload.d.ts +7 -0
  65. package/dist/types/resume-payload.d.ts.map +1 -1
  66. package/dist/types/runner-runtime-control.d.ts.map +1 -1
  67. package/dist/types/step-executors/conditional-executor.d.ts.map +1 -1
  68. package/dist/types/step-executors/loop-executor.d.ts +2 -4
  69. package/dist/types/step-executors/loop-executor.d.ts.map +1 -1
  70. package/dist/types/step-executors/parallel-executor.d.ts.map +1 -1
  71. package/dist/types/step-executors/scope.d.ts +12 -0
  72. package/dist/types/step-executors/scope.d.ts.map +1 -0
  73. package/dist/types/step-executors/skip-helpers.d.ts +2 -8
  74. package/dist/types/step-executors/skip-helpers.d.ts.map +1 -1
  75. package/dist/types/step-executors/task-executor.d.ts.map +1 -1
  76. package/dist/types/utils/flow-steps.d.ts +16 -0
  77. package/dist/types/utils/flow-steps.d.ts.map +1 -0
  78. package/dist/types/utils/naming.d.ts +7 -7
  79. package/dist/types/utils/naming.d.ts.map +1 -1
  80. package/dist/types/utils/object-path.d.ts +11 -0
  81. package/dist/types/utils/object-path.d.ts.map +1 -0
  82. package/dist/types/utils/timeout.d.ts.map +1 -1
  83. package/dist/types/validation-issue.d.ts +13 -0
  84. package/dist/types/validation-issue.d.ts.map +1 -1
  85. package/dist/types/workflow-compiler.d.ts +15 -1
  86. package/dist/types/workflow-compiler.d.ts.map +1 -1
  87. package/dist/types/workflow-fingerprint.d.ts.map +1 -1
  88. package/dist/types/workflow-runner.d.ts +2 -0
  89. package/dist/types/workflow-runner.d.ts.map +1 -1
  90. package/dist/types/workflow-values.d.ts +2 -0
  91. package/dist/types/workflow-values.d.ts.map +1 -1
  92. package/dist/types/workflow.d.ts +2 -1
  93. package/dist/types/workflow.d.ts.map +1 -1
  94. package/examples/defs-bindings-agent/actions/ai-agent.ts +5 -3
  95. package/examples/defs-bindings-agent/actions/{caculate-score.ts → calculate-score.ts} +8 -8
  96. package/examples/defs-bindings-agent/actions/index.ts +2 -2
  97. package/examples/defs-bindings-agent/workflow.yml +2 -2
  98. package/examples/full/workflow.yml +20 -15
  99. package/examples/suspend-resume/workflow.yml +6 -3
  100. package/package.json +8 -5
  101. package/src/__tests__/checkpoint.test.ts +6 -1
  102. package/src/__tests__/resume-payload.test.ts +29 -0
  103. package/src/__tests__/test-helpers.ts +1 -1
  104. package/src/__tests__/validation.test.ts +330 -0
  105. package/src/__tests__/workflow-compiler.test.ts +278 -3
  106. package/src/__tests__/workflow-definition-path.test.ts +2 -0
  107. package/src/__tests__/workflow-fingerprint.test.ts +65 -0
  108. package/src/__tests__/workflow-runner.test.ts +280 -5
  109. package/src/__tests__/workflow-values.test.ts +13 -0
  110. package/src/__tests__/workflow.test.ts +4 -2
  111. package/src/action/__tests__/abstract-action-timing.test.ts +92 -0
  112. package/src/action/abstract-action.ts +67 -40
  113. package/src/bindings/base-binding.test.ts +470 -0
  114. package/src/bindings/base-binding.ts +344 -267
  115. package/src/checkpoint.ts +2 -4
  116. package/src/context.ts +2 -3
  117. package/src/dsl.types.ts +75 -154
  118. package/src/errors.ts +15 -0
  119. package/src/index.ts +2 -0
  120. package/src/resume-payload.ts +13 -3
  121. package/src/runner-runtime-control.ts +52 -29
  122. package/src/step-executors/conditional-executor.ts +3 -7
  123. package/src/step-executors/loop-executor.test.ts +55 -0
  124. package/src/step-executors/loop-executor.ts +16 -50
  125. package/src/step-executors/parallel-executor.ts +14 -37
  126. package/src/step-executors/scope.ts +30 -0
  127. package/src/step-executors/skip-helpers.test.ts +133 -0
  128. package/src/step-executors/skip-helpers.ts +43 -76
  129. package/src/step-executors/task-executor.test.ts +130 -1
  130. package/src/step-executors/task-executor.ts +109 -79
  131. package/src/utils/flow-steps.test.ts +121 -0
  132. package/src/utils/flow-steps.ts +62 -0
  133. package/src/utils/naming.test.ts +50 -0
  134. package/src/utils/naming.ts +11 -11
  135. package/src/utils/object-path.test.ts +70 -0
  136. package/src/utils/object-path.ts +67 -0
  137. package/src/utils/timeout.test.ts +152 -0
  138. package/src/utils/timeout.ts +26 -44
  139. package/src/validation-issue.test.ts +70 -0
  140. package/src/validation-issue.ts +27 -0
  141. package/src/workflow-compiler.ts +118 -180
  142. package/src/workflow-fingerprint.ts +23 -12
  143. package/src/workflow-runner.ts +28 -27
  144. package/src/workflow-values.ts +9 -7
  145. package/src/workflow.ts +58 -140
@@ -7,47 +7,39 @@
7
7
  Object.defineProperty(exports, "__esModule", { value: true });
8
8
  exports.markStepsCancelled = exports.markStepsSkipped = void 0;
9
9
  const workflow_event_emitter_1 = require("../workflow-event-emitter");
10
- const markStepSkipped = (env, step, iterationStack, reason) => {
11
- const stepInfo = env.buildInstanceStepInfo(step, iterationStack);
12
- env.markSnapshot(stepInfo, 'skipped', reason);
13
- env.emit('hook:step:skipped', { runId: env.runId, step: stepInfo, reason });
14
- switch (step.type) {
15
- case workflow_event_emitter_1.StepType.Parallel:
16
- step.steps.forEach((child) => markStepSkipped(env, child, iterationStack, reason));
17
- break;
18
- case workflow_event_emitter_1.StepType.Conditional:
19
- step.branches.forEach((branch) => branch.steps.forEach((child) => markStepSkipped(env, child, iterationStack, reason)));
20
- break;
21
- case workflow_event_emitter_1.StepType.Loop:
22
- case workflow_event_emitter_1.StepType.Task:
23
- break;
10
+ /**
11
+ * Visit steps depth first, entering parallel and conditional children. Loop
12
+ * bodies are not entered: their step instances depend on iterations that
13
+ * never ran.
14
+ */
15
+ const forEachStepInTree = (steps, visit) => {
16
+ for (const step of steps) {
17
+ visit(step);
18
+ if (step.type === workflow_event_emitter_1.StepType.Parallel) {
19
+ forEachStepInTree(step.steps, visit);
20
+ }
21
+ else if (step.type === workflow_event_emitter_1.StepType.Conditional) {
22
+ step.branches.forEach((branch) => forEachStepInTree(branch.steps, visit));
23
+ }
24
24
  }
25
25
  };
26
- const markStepCancelled = (env, step, iterationStack, reason) => {
27
- const stepInfo = env.buildInstanceStepInfo(step, iterationStack);
28
- env.markSnapshot(stepInfo, 'cancelled', reason);
29
- env.emit('hook:step:cancelled', {
30
- runId: env.runId,
31
- step: stepInfo,
32
- error: new Error(reason ?? 'Step execution was cancelled.'),
26
+ /** Mark every step of the tree with `status`, then announce it. */
27
+ const markStepTree = (env, steps, iterationStack, status, reason, announce) => {
28
+ forEachStepInTree(steps, (step) => {
29
+ const stepInfo = env.buildInstanceStepInfo(step, iterationStack);
30
+ env.markSnapshot(stepInfo, status, reason);
31
+ announce(stepInfo);
33
32
  });
34
- switch (step.type) {
35
- case workflow_event_emitter_1.StepType.Parallel:
36
- step.steps.forEach((child) => markStepCancelled(env, child, iterationStack, reason));
37
- break;
38
- case workflow_event_emitter_1.StepType.Conditional:
39
- step.branches.forEach((branch) => branch.steps.forEach((child) => markStepCancelled(env, child, iterationStack, reason)));
40
- break;
41
- case workflow_event_emitter_1.StepType.Loop:
42
- case workflow_event_emitter_1.StepType.Task:
43
- break;
44
- }
45
33
  };
46
34
  const markStepsSkipped = (env, steps, iterationStack, reason) => {
47
- steps.forEach((step) => markStepSkipped(env, step, iterationStack, reason));
35
+ markStepTree(env, steps, iterationStack, 'skipped', reason, (stepInfo) => env.emit('hook:step:skipped', { runId: env.runId, step: stepInfo, reason }));
48
36
  };
49
37
  exports.markStepsSkipped = markStepsSkipped;
50
38
  const markStepsCancelled = (env, steps, iterationStack, reason) => {
51
- steps.forEach((step) => markStepCancelled(env, step, iterationStack, reason));
39
+ markStepTree(env, steps, iterationStack, 'cancelled', reason, (stepInfo) => env.emit('hook:step:cancelled', {
40
+ runId: env.runId,
41
+ step: stepInfo,
42
+ error: new Error(reason ?? 'Step execution was cancelled.'),
43
+ }));
52
44
  };
53
45
  exports.markStepsCancelled = markStepsCancelled;
@@ -10,6 +10,7 @@ const checkpoint_1 = require("../checkpoint");
10
10
  const errors_1 = require("../errors");
11
11
  const clone_1 = require("../utils/clone");
12
12
  const workflow_values_1 = require("../workflow-values");
13
+ const scope_1 = require("./scope");
13
14
  /**
14
15
  * Execute a task step, returning a frame when its action suspends.
15
16
  *
@@ -36,37 +37,17 @@ async function executeTaskStep(env, step, state, _path, frame) {
36
37
  return frame;
37
38
  }
38
39
  const stepInfo = env.buildInstanceStepInfo(step, state.iterationStack);
39
- if (env.signal.aborted) {
40
- const error = (0, errors_1.getAbortReason)(env.signal);
41
- recordTaskCancellation(env, stepInfo, error, frame?.wait);
42
- throw error;
43
- }
40
+ throwIfCancelled(env, stepInfo, frame);
44
41
  // Resumed bodies reuse the inputs they first ran with: re-evaluating could
45
42
  // differ, e.g. when an expression depends on the event that woke the run.
46
43
  const inputs = frame
47
44
  ? (0, clone_1.cloneValue)(frame.inputs)
48
- : await (0, workflow_values_1.evaluateMapping)(task.inputs, buildScope(env, state));
49
- if (env.signal.aborted) {
50
- const error = (0, errors_1.getAbortReason)(env.signal);
51
- recordTaskCancellation(env, stepInfo, error, frame?.wait);
52
- throw error;
53
- }
45
+ : await (0, workflow_values_1.evaluateMapping)(task.inputs, (0, scope_1.buildEvaluationScope)(env, state));
46
+ throwIfCancelled(env, stepInfo, frame);
54
47
  // Kept apart from the object the body gets, so that a body changing its
55
48
  // inputs cannot change the inputs every later pass replays.
56
49
  const recordedInputs = frame ? frame.inputs : copyInputs(inputs);
57
50
  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;
70
51
  const stepExecution = env.recordStepExecution(stepInfo, {
71
52
  action: task.actionName,
72
53
  status: 'running',
@@ -76,7 +57,9 @@ async function executeTaskStep(env, step, state, _path, frame) {
76
57
  input: inputs,
77
58
  context: { before: env.context.snapshot() },
78
59
  });
79
- env.runtime.beginStep(stepInfo, { seed });
60
+ env.runtime.beginStep(stepInfo, {
61
+ seed: frame ? buildReplaySeed(frame, resumeData) : undefined,
62
+ });
80
63
  env.markSnapshot(stepInfo, 'running');
81
64
  if (frame) {
82
65
  env.emit('hook:step:resumed', {
@@ -159,12 +142,31 @@ const copyInputs = (inputs) => {
159
142
  return inputs;
160
143
  }
161
144
  };
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,
145
+ /**
146
+ * Record the task cancelled and throw when the run was aborted before its
147
+ * body started.
148
+ */
149
+ const throwIfCancelled = (env, stepInfo, frame) => {
150
+ if (!env.signal.aborted) {
151
+ return;
152
+ }
153
+ const error = (0, errors_1.getAbortReason)(env.signal);
154
+ recordTaskCancellation(env, stepInfo, error, frame?.wait);
155
+ throw error;
156
+ };
157
+ /**
158
+ * Seed a resumed body with every answer it already got, including the one
159
+ * this pass resolved, and the suspension it is expected to reach again.
160
+ */
161
+ const buildReplaySeed = (frame, resumeData) => ({
162
+ awaitResults: {
163
+ ...readRecordedResults(frame.awaitResults),
164
+ [frame.wait.suspendKey]: resumeData,
165
+ },
166
+ expected: {
167
+ suspendKey: frame.wait.suspendKey,
168
+ reason: frame.wait.reason,
169
+ },
168
170
  });
169
171
  const waitForTaskProgress = async (signal, runtime, actionPromise) => {
170
172
  const completion = actionPromise.then((value) => ({ type: 'completed', value }), (error) => ({ type: 'failed', error }));
@@ -194,13 +196,9 @@ const waitForTaskProgress = async (signal, runtime, actionPromise) => {
194
196
  };
195
197
  const completeTask = async (env, stepInfo, task, state, result) => {
196
198
  await env.captureTaskOutput(task, state, result);
197
- const stepExecution = env.recordStepExecution(stepInfo, {
198
- status: 'completed',
199
- endedAt: Date.now(),
199
+ const stepExecution = endStepExecution(env, stepInfo, 'completed', {
200
200
  output: result,
201
- context: { after: env.context.snapshot() },
202
201
  });
203
- env.markSnapshot(stepInfo, 'completed');
204
202
  env.emit('hook:step:success', {
205
203
  runId: env.runId,
206
204
  step: stepInfo,
@@ -217,13 +215,7 @@ const suspendTask = (env, step, stepInfo, inputs, request) => {
217
215
  ...(request.accepts ? { accepts: request.accepts } : {}),
218
216
  ...(request.payloadOptional ? { payloadOptional: true } : {}),
219
217
  };
220
- const stepExecution = env.recordStepExecution(stepInfo, {
221
- status: 'suspended',
222
- endedAt: Date.now(),
223
- reason: request.reason,
224
- context: { after: env.context.snapshot() },
225
- });
226
- env.markSnapshot(stepInfo, 'suspended', request.reason);
218
+ const stepExecution = endStepExecution(env, stepInfo, 'suspended', { reason: request.reason }, request.reason);
227
219
  env.emit('hook:step:suspended', {
228
220
  runId: env.runId,
229
221
  step: stepInfo,
@@ -246,13 +238,7 @@ const readRecordedResults = (recorded) => Object.fromEntries(Object.entries(reco
246
238
  * resume payload, and hand back the frame it resumed from.
247
239
  */
248
240
  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);
241
+ const stepExecution = endStepExecution(env, stepInfo, 'suspended', { reason: frame.wait.reason }, frame.wait.reason);
256
242
  env.emit('hook:step:resume_rejected', {
257
243
  runId: env.runId,
258
244
  step: stepInfo,
@@ -264,14 +250,7 @@ const keepWaiting = (env, stepInfo, frame, error) => {
264
250
  return frame;
265
251
  };
266
252
  const recordTaskFailure = (env, stepInfo, error) => {
267
- const normalizedError = normalizeError(error);
268
- const stepExecution = env.recordStepExecution(stepInfo, {
269
- status: 'failed',
270
- endedAt: Date.now(),
271
- error: normalizedError,
272
- context: { after: env.context.snapshot() },
273
- });
274
- env.markSnapshot(stepInfo, 'failed', normalizeErrorMessage(error));
253
+ const stepExecution = endStepExecutionWithError(env, stepInfo, 'failed', error);
275
254
  env.emit('hook:step:error', {
276
255
  runId: env.runId,
277
256
  step: stepInfo,
@@ -284,14 +263,7 @@ const recordTaskFailure = (env, stepInfo, error) => {
284
263
  * wait, so the event carries it.
285
264
  */
286
265
  const recordTaskCancellation = (env, stepInfo, error, wait) => {
287
- const normalizedError = normalizeError(error);
288
- const stepExecution = env.recordStepExecution(stepInfo, {
289
- status: 'cancelled',
290
- endedAt: Date.now(),
291
- error: normalizedError,
292
- context: { after: env.context.snapshot() },
293
- });
294
- env.markSnapshot(stepInfo, 'cancelled', normalizeErrorMessage(error));
266
+ const stepExecution = endStepExecutionWithError(env, stepInfo, 'cancelled', error);
295
267
  env.emit('hook:step:cancelled', {
296
268
  runId: env.runId,
297
269
  step: stepInfo,
@@ -300,7 +272,24 @@ const recordTaskCancellation = (env, stepInfo, error, wait) => {
300
272
  ...(wait ? { wait } : {}),
301
273
  });
302
274
  };
303
- const normalizeError = (error) => error instanceof Error
304
- ? { message: error.message, stack: error.stack }
305
- : { message: String(error) };
306
- const normalizeErrorMessage = (error) => error instanceof Error ? error.message : String(error);
275
+ /**
276
+ * Close the step's execution record with the status the step ended (or
277
+ * paused) with, and mirror that status on its snapshot.
278
+ *
279
+ * @returns The updated execution record, for the event announcing it.
280
+ */
281
+ const endStepExecution = (env, stepInfo, status, details, snapshotReason) => {
282
+ const stepExecution = env.recordStepExecution(stepInfo, {
283
+ status,
284
+ endedAt: Date.now(),
285
+ ...details,
286
+ context: { after: env.context.snapshot() },
287
+ });
288
+ env.markSnapshot(stepInfo, status, snapshotReason);
289
+ return stepExecution;
290
+ };
291
+ const endStepExecutionWithError = (env, stepInfo, status, error) => endStepExecution(env, stepInfo, status, {
292
+ error: error instanceof Error
293
+ ? { message: error.message, stack: error.stack }
294
+ : { message: String(error) },
295
+ }, error instanceof Error ? error.message : String(error));
@@ -0,0 +1,41 @@
1
+ "use strict";
2
+ /*
3
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
4
+ * Copyright (c) 2026 Hexastack.
5
+ * Full terms: see LICENSE.md.
6
+ */
7
+ Object.defineProperty(exports, "__esModule", { value: true });
8
+ exports.collectTaskReferences = void 0;
9
+ /**
10
+ * The step lists nested in a flow step, each with its path relative to the
11
+ * step: one for `parallel` and `loop`, one per branch for `conditional`.
12
+ */
13
+ const nestedStepLists = (step) => {
14
+ if ('parallel' in step) {
15
+ return [{ steps: step.parallel.steps, path: ['parallel', 'steps'] }];
16
+ }
17
+ if ('conditional' in step) {
18
+ return step.conditional.when.map((branch, branchIndex) => ({
19
+ steps: branch.steps,
20
+ path: ['conditional', 'when', branchIndex, 'steps'],
21
+ }));
22
+ }
23
+ if ('loop' in step) {
24
+ return [{ steps: step.loop.steps, path: ['loop', 'steps'] }];
25
+ }
26
+ return [];
27
+ };
28
+ /**
29
+ * List every task reference of a flow, depth first, in flow order.
30
+ *
31
+ * @param steps The flow, or a nested step list.
32
+ * @param basePath Path of `steps` inside the workflow definition.
33
+ */
34
+ const collectTaskReferences = (steps, basePath = ['flow']) => steps.flatMap((step, index) => {
35
+ const stepPath = [...basePath, index];
36
+ if ('do' in step) {
37
+ return [{ taskId: step.do, path: [...stepPath, 'do'] }];
38
+ }
39
+ return nestedStepLists(step).flatMap(({ steps: nested, path }) => (0, exports.collectTaskReferences)(nested, [...stepPath, ...path]));
40
+ });
41
+ exports.collectTaskReferences = collectTaskReferences;
@@ -9,6 +9,14 @@ exports.isSnakeCaseName = exports.SNAKE_CASE_REGEX = void 0;
9
9
  exports.assertSnakeCaseName = assertSnakeCaseName;
10
10
  exports.toSnakeCase = toSnakeCase;
11
11
  exports.SNAKE_CASE_REGEX = /^[a-z0-9]+(?:_[a-z0-9]+)*$/;
12
+ /**
13
+ * Checks whether the provided string is snake_case compliant.
14
+ *
15
+ * @param value - Text to evaluate.
16
+ * @returns `true` when the value is snake_case; otherwise `false`.
17
+ */
18
+ const isSnakeCaseName = (value) => exports.SNAKE_CASE_REGEX.test(value);
19
+ exports.isSnakeCaseName = isSnakeCaseName;
12
20
  /**
13
21
  * Verifies that names follow the snake_case convention required by the system.
14
22
  *
@@ -17,18 +25,10 @@ exports.SNAKE_CASE_REGEX = /^[a-z0-9]+(?:_[a-z0-9]+)*$/;
17
25
  * @throws Error when the name is not snake_case.
18
26
  */
19
27
  function assertSnakeCaseName(name, entity) {
20
- if (!exports.SNAKE_CASE_REGEX.test(name)) {
21
- throw new Error(`${entity} name must be snake_case with at least one underscore. Received: "${name}"`);
28
+ if (!(0, exports.isSnakeCaseName)(name)) {
29
+ throw new Error(`${entity} name must be snake_case (lowercase letters and digits separated by single underscores). Received: "${name}"`);
22
30
  }
23
31
  }
24
- /**
25
- * Checks whether the provided string is snake_case compliant.
26
- *
27
- * @param value - Text to evaluate.
28
- * @returns `true` when the value is snake_case; otherwise `false`.
29
- */
30
- const isSnakeCaseName = (value) => exports.SNAKE_CASE_REGEX.test(value);
31
- exports.isSnakeCaseName = isSnakeCaseName;
32
32
  /**
33
33
  * Converts arbitrary text into snake_case for use in workflow entities.
34
34
  *
@@ -0,0 +1,51 @@
1
+ "use strict";
2
+ /*
3
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
4
+ * Copyright (c) 2026 Hexastack.
5
+ * Full terms: see LICENSE.md.
6
+ */
7
+ Object.defineProperty(exports, "__esModule", { value: true });
8
+ exports.setValueAtPath = exports.getValueAtPath = void 0;
9
+ /**
10
+ * Read a nested value. Array segments must be numbers; a path that leaves
11
+ * the value resolves to `undefined`.
12
+ */
13
+ const getValueAtPath = (value, path) => path.reduce((acc, key) => {
14
+ if (acc === null || acc === undefined) {
15
+ return undefined;
16
+ }
17
+ if (Array.isArray(acc)) {
18
+ return typeof key === 'number' ? acc[key] : undefined;
19
+ }
20
+ if (typeof acc === 'object') {
21
+ return acc[String(key)];
22
+ }
23
+ return undefined;
24
+ }, value);
25
+ exports.getValueAtPath = getValueAtPath;
26
+ /**
27
+ * Copy a value with one nested value replaced; the input is left untouched.
28
+ * A path that does not fit the value returns it as is.
29
+ */
30
+ const setValueAtPath = (value, path, nextValue) => {
31
+ if (path.length === 0) {
32
+ return nextValue;
33
+ }
34
+ const [key, ...rest] = path;
35
+ if (Array.isArray(value)) {
36
+ if (typeof key !== 'number') {
37
+ return value;
38
+ }
39
+ const nextArray = [...value];
40
+ nextArray[key] = (0, exports.setValueAtPath)(value[key], rest, nextValue);
41
+ return nextArray;
42
+ }
43
+ if (value && typeof value === 'object') {
44
+ return {
45
+ ...value,
46
+ [String(key)]: (0, exports.setValueAtPath)(value[String(key)], rest, nextValue),
47
+ };
48
+ }
49
+ return value;
50
+ };
51
+ exports.setValueAtPath = setValueAtPath;
@@ -48,50 +48,27 @@ async function withTimeout(promise, timeoutMs, signal) {
48
48
  }
49
49
  return new Promise((resolve, reject) => {
50
50
  let settled = false;
51
- const timer = timeoutMs
52
- ? setTimeout(() => {
53
- settled = true;
54
- signal?.removeEventListener('abort', onAbort);
55
- reject(new Error(`Step execution exceeded timeout of ${timeoutMs}ms`));
56
- }, timeoutMs)
57
- : undefined;
58
- const onAbort = () => {
51
+ let timer;
52
+ // The first of the promise, the timeout and the abort settles the
53
+ // result; the other two are detached.
54
+ const settle = (finish) => {
59
55
  if (settled) {
60
56
  return;
61
57
  }
62
58
  settled = true;
63
- if (timer) {
64
- clearTimeout(timer);
65
- }
66
- reject((0, errors_1.getAbortReason)(signal));
59
+ clearTimeout(timer);
60
+ signal?.removeEventListener('abort', onAbort);
61
+ finish();
67
62
  };
68
- if (signal) {
69
- if (signal.aborted) {
70
- onAbort();
71
- return;
72
- }
73
- signal.addEventListener('abort', onAbort, { once: true });
63
+ const onAbort = () => settle(() => reject((0, errors_1.getAbortReason)(signal)));
64
+ if (timeoutMs) {
65
+ timer = setTimeout(() => settle(() => reject(new Error(`Step execution exceeded timeout of ${timeoutMs}ms`))), timeoutMs);
74
66
  }
75
- promise.then((value) => {
76
- if (settled) {
77
- return;
78
- }
79
- settled = true;
80
- if (timer) {
81
- clearTimeout(timer);
82
- }
83
- signal?.removeEventListener('abort', onAbort);
84
- resolve(value);
85
- }, (error) => {
86
- if (settled) {
87
- return;
88
- }
89
- settled = true;
90
- if (timer) {
91
- clearTimeout(timer);
92
- }
93
- signal?.removeEventListener('abort', onAbort);
94
- reject(error);
95
- });
67
+ if (signal?.aborted) {
68
+ onAbort();
69
+ return;
70
+ }
71
+ signal?.addEventListener('abort', onAbort, { once: true });
72
+ promise.then((value) => settle(() => resolve(value)), (error) => settle(() => reject(error)));
96
73
  });
97
74
  }
@@ -5,6 +5,19 @@
5
5
  * Full terms: see LICENSE.md.
6
6
  */
7
7
  Object.defineProperty(exports, "__esModule", { value: true });
8
- exports.issueMessages = void 0;
8
+ exports.toValidationIssues = exports.toIssuePath = exports.issueMessages = void 0;
9
9
  const issueMessages = (issues) => issues.map((issue) => issue.message);
10
10
  exports.issueMessages = issueMessages;
11
+ /** Keep the segments of a schema issue path that can locate a YAML node. */
12
+ const toIssuePath = (path) => path.filter((segment) => typeof segment === 'string' || typeof segment === 'number');
13
+ exports.toIssuePath = toIssuePath;
14
+ /**
15
+ * Turn schema issues into validation issues located under `basePath`, the
16
+ * path of the value the schema checked.
17
+ */
18
+ const toValidationIssues = (code, schemaIssues, basePath = []) => schemaIssues.map((issue) => ({
19
+ code,
20
+ message: `${[...basePath, issue.path.join('.') || '<root>'].join('.')}: ${issue.message}`,
21
+ path: [...basePath, ...(0, exports.toIssuePath)(issue.path)],
22
+ }));
23
+ exports.toValidationIssues = toValidationIssues;