@hexabot-ai/agentic 3.5.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
@@ -10,6 +10,7 @@ import {
10
10
  type TaskFrame,
11
11
  type WaitInfo,
12
12
  } from '../checkpoint';
13
+ import type { StepExecutionRecord } from '../context';
13
14
  import {
14
15
  createLinkedAbortController,
15
16
  getAbortReason,
@@ -25,14 +26,10 @@ import type {
25
26
  } from '../runner-runtime-control';
26
27
  import { cloneAsJson, cloneValue } from '../utils/clone';
27
28
  import type { StepInfo } from '../workflow-event-emitter';
28
- import type {
29
- CompiledTask,
30
- EvaluationScope,
31
- ExecutionState,
32
- TaskStep,
33
- } from '../workflow-types';
29
+ import type { CompiledTask, ExecutionState, TaskStep } from '../workflow-types';
34
30
  import { evaluateMapping } from '../workflow-values';
35
31
 
32
+ import { buildEvaluationScope } from './scope';
36
33
  import type { StepExecutorEnv } from './types';
37
34
 
38
35
  type TaskProgressOutcome =
@@ -75,38 +72,18 @@ export async function executeTaskStep(
75
72
  }
76
73
 
77
74
  const stepInfo = env.buildInstanceStepInfo(step, state.iterationStack);
78
- if (env.signal.aborted) {
79
- const error = getAbortReason(env.signal);
80
- recordTaskCancellation(env, stepInfo, error, frame?.wait);
81
- throw error;
82
- }
75
+ throwIfCancelled(env, stepInfo, frame);
83
76
 
84
77
  // Resumed bodies reuse the inputs they first ran with: re-evaluating could
85
78
  // differ, e.g. when an expression depends on the event that woke the run.
86
79
  const inputs = frame
87
80
  ? cloneValue(frame.inputs)
88
- : await evaluateMapping(task.inputs, buildScope(env, state));
89
- if (env.signal.aborted) {
90
- const error = getAbortReason(env.signal);
91
- recordTaskCancellation(env, stepInfo, error, frame?.wait);
92
- throw error;
93
- }
81
+ : await evaluateMapping(task.inputs, buildEvaluationScope(env, state));
82
+ throwIfCancelled(env, stepInfo, frame);
94
83
  // Kept apart from the object the body gets, so that a body changing its
95
84
  // inputs cannot change the inputs every later pass replays.
96
85
  const recordedInputs = frame ? frame.inputs : copyInputs(inputs);
97
86
  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;
110
87
  const stepExecution = env.recordStepExecution(stepInfo, {
111
88
  action: task.actionName,
112
89
  status: 'running',
@@ -116,7 +93,9 @@ export async function executeTaskStep(
116
93
  input: inputs,
117
94
  context: { before: env.context.snapshot() },
118
95
  });
119
- env.runtime.beginStep(stepInfo, { seed });
96
+ env.runtime.beginStep(stepInfo, {
97
+ seed: frame ? buildReplaySeed(frame, resumeData) : undefined,
98
+ });
120
99
  env.markSnapshot(stepInfo, 'running');
121
100
  if (frame) {
122
101
  env.emit('hook:step:resumed', {
@@ -219,15 +198,39 @@ const copyInputs = (
219
198
  return inputs;
220
199
  }
221
200
  };
222
- const buildScope = (
201
+ /**
202
+ * Record the task cancelled and throw when the run was aborted before its
203
+ * body started.
204
+ */
205
+ const throwIfCancelled = (
223
206
  env: StepExecutorEnv,
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,
207
+ stepInfo: StepInfo,
208
+ frame?: TaskFrame,
209
+ ): void => {
210
+ if (!env.signal.aborted) {
211
+ return;
212
+ }
213
+
214
+ const error = getAbortReason(env.signal);
215
+ recordTaskCancellation(env, stepInfo, error, frame?.wait);
216
+ throw error;
217
+ };
218
+ /**
219
+ * Seed a resumed body with every answer it already got, including the one
220
+ * this pass resolved, and the suspension it is expected to reach again.
221
+ */
222
+ const buildReplaySeed = (
223
+ frame: TaskFrame,
224
+ resumeData: unknown,
225
+ ): StepReplaySeed => ({
226
+ awaitResults: {
227
+ ...readRecordedResults(frame.awaitResults),
228
+ [frame.wait.suspendKey]: resumeData,
229
+ },
230
+ expected: {
231
+ suspendKey: frame.wait.suspendKey,
232
+ reason: frame.wait.reason,
233
+ },
231
234
  });
232
235
  const waitForTaskProgress = async (
233
236
  signal: AbortSignal,
@@ -273,13 +276,9 @@ const completeTask = async (
273
276
  result: unknown,
274
277
  ) => {
275
278
  await env.captureTaskOutput(task, state, result);
276
- const stepExecution = env.recordStepExecution(stepInfo, {
277
- status: 'completed',
278
- endedAt: Date.now(),
279
+ const stepExecution = endStepExecution(env, stepInfo, 'completed', {
279
280
  output: result,
280
- context: { after: env.context.snapshot() },
281
281
  });
282
- env.markSnapshot(stepInfo, 'completed');
283
282
  env.emit('hook:step:success', {
284
283
  runId: env.runId,
285
284
  step: stepInfo,
@@ -302,13 +301,13 @@ const suspendTask = (
302
301
  ...(request.accepts ? { accepts: request.accepts } : {}),
303
302
  ...(request.payloadOptional ? { payloadOptional: true } : {}),
304
303
  };
305
- const stepExecution = env.recordStepExecution(stepInfo, {
306
- status: 'suspended',
307
- endedAt: Date.now(),
308
- reason: request.reason,
309
- context: { after: env.context.snapshot() },
310
- });
311
- env.markSnapshot(stepInfo, 'suspended', request.reason);
304
+ const stepExecution = endStepExecution(
305
+ env,
306
+ stepInfo,
307
+ 'suspended',
308
+ { reason: request.reason },
309
+ request.reason,
310
+ );
312
311
  env.emit('hook:step:suspended', {
313
312
  runId: env.runId,
314
313
  step: stepInfo,
@@ -347,13 +346,13 @@ const keepWaiting = (
347
346
  frame: TaskFrame,
348
347
  error: WorkflowResumeRejectedError,
349
348
  ): 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);
349
+ const stepExecution = endStepExecution(
350
+ env,
351
+ stepInfo,
352
+ 'suspended',
353
+ { reason: frame.wait.reason },
354
+ frame.wait.reason,
355
+ );
357
356
  env.emit('hook:step:resume_rejected', {
358
357
  runId: env.runId,
359
358
  step: stepInfo,
@@ -370,14 +369,12 @@ const recordTaskFailure = (
370
369
  stepInfo: StepInfo,
371
370
  error: unknown,
372
371
  ) => {
373
- const normalizedError = normalizeError(error);
374
- const stepExecution = env.recordStepExecution(stepInfo, {
375
- status: 'failed',
376
- endedAt: Date.now(),
377
- error: normalizedError,
378
- context: { after: env.context.snapshot() },
379
- });
380
- env.markSnapshot(stepInfo, 'failed', normalizeErrorMessage(error));
372
+ const stepExecution = endStepExecutionWithError(
373
+ env,
374
+ stepInfo,
375
+ 'failed',
376
+ error,
377
+ );
381
378
  env.emit('hook:step:error', {
382
379
  runId: env.runId,
383
380
  step: stepInfo,
@@ -395,14 +392,12 @@ const recordTaskCancellation = (
395
392
  error: unknown,
396
393
  wait?: WaitInfo,
397
394
  ) => {
398
- const normalizedError = normalizeError(error);
399
- const stepExecution = env.recordStepExecution(stepInfo, {
400
- status: 'cancelled',
401
- endedAt: Date.now(),
402
- error: normalizedError,
403
- context: { after: env.context.snapshot() },
404
- });
405
- env.markSnapshot(stepInfo, 'cancelled', normalizeErrorMessage(error));
395
+ const stepExecution = endStepExecutionWithError(
396
+ env,
397
+ stepInfo,
398
+ 'cancelled',
399
+ error,
400
+ );
406
401
  env.emit('hook:step:cancelled', {
407
402
  runId: env.runId,
408
403
  step: stepInfo,
@@ -411,9 +406,44 @@ const recordTaskCancellation = (
411
406
  ...(wait ? { wait } : {}),
412
407
  });
413
408
  };
414
- const normalizeError = (error: unknown): { message: string; stack?: string } =>
415
- error instanceof Error
416
- ? { message: error.message, stack: error.stack }
417
- : { message: String(error) };
418
- const normalizeErrorMessage = (error: unknown): string =>
419
- error instanceof Error ? error.message : String(error);
409
+ /**
410
+ * Close the step's execution record with the status the step ended (or
411
+ * paused) with, and mirror that status on its snapshot.
412
+ *
413
+ * @returns The updated execution record, for the event announcing it.
414
+ */
415
+ const endStepExecution = (
416
+ env: StepExecutorEnv,
417
+ stepInfo: StepInfo,
418
+ status: 'completed' | 'suspended' | 'failed' | 'cancelled',
419
+ details: Pick<StepExecutionRecord, 'output' | 'reason' | 'error'>,
420
+ snapshotReason?: string,
421
+ ): StepExecutionRecord => {
422
+ const stepExecution = env.recordStepExecution(stepInfo, {
423
+ status,
424
+ endedAt: Date.now(),
425
+ ...details,
426
+ context: { after: env.context.snapshot() },
427
+ });
428
+ env.markSnapshot(stepInfo, status, snapshotReason);
429
+
430
+ return stepExecution;
431
+ };
432
+ const endStepExecutionWithError = (
433
+ env: StepExecutorEnv,
434
+ stepInfo: StepInfo,
435
+ status: 'failed' | 'cancelled',
436
+ error: unknown,
437
+ ): StepExecutionRecord =>
438
+ endStepExecution(
439
+ env,
440
+ stepInfo,
441
+ status,
442
+ {
443
+ error:
444
+ error instanceof Error
445
+ ? { message: error.message, stack: error.stack }
446
+ : { message: String(error) },
447
+ },
448
+ error instanceof Error ? error.message : String(error),
449
+ );
@@ -0,0 +1,121 @@
1
+ /*
2
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
3
+ * Copyright (c) 2026 Hexastack.
4
+ * Full terms: see LICENSE.md.
5
+ */
6
+
7
+ import type { FlowStep } from '../dsl.types';
8
+
9
+ import { collectTaskReferences } from './flow-steps';
10
+
11
+ describe('collectTaskReferences', () => {
12
+ it('lists the task references of every nested step list, in flow order', () => {
13
+ const flow: FlowStep[] = [
14
+ { do: 'first' },
15
+ {
16
+ parallel: {
17
+ steps: [
18
+ { do: 'second' },
19
+ {
20
+ conditional: {
21
+ when: [
22
+ { condition: '=true', steps: [{ do: 'third' }] },
23
+ {
24
+ else: true,
25
+ steps: [
26
+ {
27
+ loop: {
28
+ type: 'while',
29
+ while: '=false',
30
+ steps: [{ do: 'fourth' }, { do: 'first' }],
31
+ },
32
+ },
33
+ ],
34
+ },
35
+ ],
36
+ },
37
+ },
38
+ ],
39
+ },
40
+ },
41
+ ];
42
+
43
+ expect(collectTaskReferences(flow)).toEqual([
44
+ { taskId: 'first', path: ['flow', 0, 'do'] },
45
+ { taskId: 'second', path: ['flow', 1, 'parallel', 'steps', 0, 'do'] },
46
+ {
47
+ taskId: 'third',
48
+ path: [
49
+ 'flow',
50
+ 1,
51
+ 'parallel',
52
+ 'steps',
53
+ 1,
54
+ 'conditional',
55
+ 'when',
56
+ 0,
57
+ 'steps',
58
+ 0,
59
+ 'do',
60
+ ],
61
+ },
62
+ {
63
+ taskId: 'fourth',
64
+ path: [
65
+ 'flow',
66
+ 1,
67
+ 'parallel',
68
+ 'steps',
69
+ 1,
70
+ 'conditional',
71
+ 'when',
72
+ 1,
73
+ 'steps',
74
+ 0,
75
+ 'loop',
76
+ 'steps',
77
+ 0,
78
+ 'do',
79
+ ],
80
+ },
81
+ {
82
+ taskId: 'first',
83
+ path: [
84
+ 'flow',
85
+ 1,
86
+ 'parallel',
87
+ 'steps',
88
+ 1,
89
+ 'conditional',
90
+ 'when',
91
+ 1,
92
+ 'steps',
93
+ 0,
94
+ 'loop',
95
+ 'steps',
96
+ 1,
97
+ 'do',
98
+ ],
99
+ },
100
+ ]);
101
+ });
102
+
103
+ it('locates references under the given base path', () => {
104
+ expect(collectTaskReferences([{ do: 'task' }], ['defs', 'x'])).toEqual([
105
+ { taskId: 'task', path: ['defs', 'x', 0, 'do'] },
106
+ ]);
107
+ });
108
+
109
+ it('finds no reference in empty or unknown steps', () => {
110
+ expect(collectTaskReferences([])).toEqual([]);
111
+ expect(
112
+ collectTaskReferences([{ unknown: {} } as unknown as FlowStep]),
113
+ ).toEqual([]);
114
+ expect(
115
+ collectTaskReferences([
116
+ { parallel: { steps: [] } },
117
+ { loop: { type: 'while', while: '=false', steps: [] } },
118
+ ]),
119
+ ).toEqual([]);
120
+ });
121
+ });
@@ -0,0 +1,62 @@
1
+ /*
2
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
3
+ * Copyright (c) 2026 Hexastack.
4
+ * Full terms: see LICENSE.md.
5
+ */
6
+
7
+ import type { FlowStep } from '../dsl.types';
8
+
9
+ type DefinitionPath = Array<string | number>;
10
+
11
+ /** A `do` step: the task it runs, and where the reference sits. */
12
+ export type TaskReference = {
13
+ taskId: string;
14
+ path: DefinitionPath;
15
+ };
16
+
17
+ /**
18
+ * The step lists nested in a flow step, each with its path relative to the
19
+ * step: one for `parallel` and `loop`, one per branch for `conditional`.
20
+ */
21
+ const nestedStepLists = (
22
+ step: FlowStep,
23
+ ): Array<{ steps: FlowStep[]; path: DefinitionPath }> => {
24
+ if ('parallel' in step) {
25
+ return [{ steps: step.parallel.steps, path: ['parallel', 'steps'] }];
26
+ }
27
+
28
+ if ('conditional' in step) {
29
+ return step.conditional.when.map((branch, branchIndex) => ({
30
+ steps: branch.steps,
31
+ path: ['conditional', 'when', branchIndex, 'steps'],
32
+ }));
33
+ }
34
+
35
+ if ('loop' in step) {
36
+ return [{ steps: step.loop.steps, path: ['loop', 'steps'] }];
37
+ }
38
+
39
+ return [];
40
+ };
41
+
42
+ /**
43
+ * List every task reference of a flow, depth first, in flow order.
44
+ *
45
+ * @param steps The flow, or a nested step list.
46
+ * @param basePath Path of `steps` inside the workflow definition.
47
+ */
48
+ export const collectTaskReferences = (
49
+ steps: FlowStep[],
50
+ basePath: DefinitionPath = ['flow'],
51
+ ): TaskReference[] =>
52
+ steps.flatMap((step, index) => {
53
+ const stepPath = [...basePath, index];
54
+
55
+ if ('do' in step) {
56
+ return [{ taskId: step.do, path: [...stepPath, 'do'] }];
57
+ }
58
+
59
+ return nestedStepLists(step).flatMap(({ steps: nested, path }) =>
60
+ collectTaskReferences(nested, [...stepPath, ...path]),
61
+ );
62
+ });
@@ -0,0 +1,50 @@
1
+ /*
2
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
3
+ * Copyright (c) 2026 Hexastack.
4
+ * Full terms: see LICENSE.md.
5
+ */
6
+
7
+ import { assertSnakeCaseName, isSnakeCaseName, toSnakeCase } from './naming';
8
+
9
+ describe('isSnakeCaseName', () => {
10
+ it.each(['send', 'send_email', 'step_2', 'v2_api'])('accepts %s', (name) => {
11
+ expect(isSnakeCaseName(name)).toBe(true);
12
+ });
13
+
14
+ it.each([
15
+ '',
16
+ 'Send',
17
+ 'send-email',
18
+ 'send__email',
19
+ '_send',
20
+ 'send_',
21
+ 'send email',
22
+ ])('refuses "%s"', (name) => {
23
+ expect(isSnakeCaseName(name)).toBe(false);
24
+ });
25
+ });
26
+
27
+ describe('assertSnakeCaseName', () => {
28
+ it('accepts a single word', () => {
29
+ expect(() => assertSnakeCaseName('send', 'action')).not.toThrow();
30
+ });
31
+
32
+ it('names the entity and the rule it breaks', () => {
33
+ expect(() => assertSnakeCaseName('sendEmail', 'action')).toThrow(
34
+ 'action name must be snake_case (lowercase letters and digits separated by single underscores). Received: "sendEmail"',
35
+ );
36
+ });
37
+ });
38
+
39
+ describe('toSnakeCase', () => {
40
+ it.each([
41
+ ['sendEmail', 'send_email'],
42
+ ['Send Email!', 'send_email'],
43
+ [' --send--email-- ', 'send_email'],
44
+ ['HTTPRequest2xx', 'httprequest2xx'],
45
+ ['already_snake', 'already_snake'],
46
+ ['', ''],
47
+ ])('turns "%s" into "%s"', (input, expected) => {
48
+ expect(toSnakeCase(input)).toBe(expected);
49
+ });
50
+ });
@@ -8,6 +8,15 @@ export const SNAKE_CASE_REGEX = /^[a-z0-9]+(?:_[a-z0-9]+)*$/;
8
8
 
9
9
  export type WorkflowEntity = 'action' | 'workflow' | 'predicate';
10
10
 
11
+ /**
12
+ * Checks whether the provided string is snake_case compliant.
13
+ *
14
+ * @param value - Text to evaluate.
15
+ * @returns `true` when the value is snake_case; otherwise `false`.
16
+ */
17
+ export const isSnakeCaseName = (value: string): boolean =>
18
+ SNAKE_CASE_REGEX.test(value);
19
+
11
20
  /**
12
21
  * Verifies that names follow the snake_case convention required by the system.
13
22
  *
@@ -19,22 +28,13 @@ export function assertSnakeCaseName(
19
28
  name: string,
20
29
  entity: WorkflowEntity,
21
30
  ): void {
22
- if (!SNAKE_CASE_REGEX.test(name)) {
31
+ if (!isSnakeCaseName(name)) {
23
32
  throw new Error(
24
- `${entity} name must be snake_case with at least one underscore. Received: "${name}"`,
33
+ `${entity} name must be snake_case (lowercase letters and digits separated by single underscores). Received: "${name}"`,
25
34
  );
26
35
  }
27
36
  }
28
37
 
29
- /**
30
- * Checks whether the provided string is snake_case compliant.
31
- *
32
- * @param value - Text to evaluate.
33
- * @returns `true` when the value is snake_case; otherwise `false`.
34
- */
35
- export const isSnakeCaseName = (value: string): boolean =>
36
- SNAKE_CASE_REGEX.test(value);
37
-
38
38
  /**
39
39
  * Converts arbitrary text into snake_case for use in workflow entities.
40
40
  *
@@ -0,0 +1,70 @@
1
+ /*
2
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
3
+ * Copyright (c) 2026 Hexastack.
4
+ * Full terms: see LICENSE.md.
5
+ */
6
+
7
+ import { getValueAtPath, setValueAtPath } from './object-path';
8
+
9
+ describe('getValueAtPath', () => {
10
+ const value = { flow: [{ do: 'first' }, { loop: { steps: ['x'] } }] };
11
+
12
+ it('reads nested object keys and array indexes', () => {
13
+ expect(getValueAtPath(value, ['flow', 1, 'loop', 'steps', 0])).toBe('x');
14
+ expect(getValueAtPath(value, [])).toBe(value);
15
+ });
16
+
17
+ it('reads nothing past null, undefined or a primitive', () => {
18
+ expect(getValueAtPath({ flow: null }, ['flow', 0])).toBeUndefined();
19
+ expect(getValueAtPath({}, ['flow', 0])).toBeUndefined();
20
+ expect(getValueAtPath({ name: 'run' }, ['name', 'length'])).toBeUndefined();
21
+ });
22
+
23
+ it('reads array items by number only', () => {
24
+ expect(getValueAtPath(value, ['flow', '0'])).toBeUndefined();
25
+ expect(getValueAtPath(value, ['flow', 'length'])).toBeUndefined();
26
+ });
27
+
28
+ it('reads object keys given as numbers', () => {
29
+ expect(getValueAtPath({ 1: 'one' }, [1])).toBe('one');
30
+ });
31
+ });
32
+
33
+ describe('setValueAtPath', () => {
34
+ it('copies every container on the path and leaves the input untouched', () => {
35
+ const value = { flow: [{ do: 'first' }, { do: 'second' }], outputs: {} };
36
+ const next = setValueAtPath(value, ['flow', 1, 'do'], 'renamed');
37
+
38
+ expect(next).toEqual({
39
+ flow: [{ do: 'first' }, { do: 'renamed' }],
40
+ outputs: {},
41
+ });
42
+ expect(value.flow[1].do).toBe('second');
43
+ expect(next.flow).not.toBe(value.flow);
44
+ expect(next.flow[0]).toBe(value.flow[0]);
45
+ expect(next.outputs).toBe(value.outputs);
46
+ });
47
+
48
+ it('replaces the whole value for an empty path', () => {
49
+ expect(setValueAtPath({ a: 1 }, [], 'next')).toBe('next');
50
+ });
51
+
52
+ it('sets a missing last key but creates no missing container', () => {
53
+ expect(setValueAtPath({}, ['defs'], { task: {} })).toEqual({
54
+ defs: { task: {} },
55
+ });
56
+ expect(setValueAtPath({}, ['defs', 'task'], { kind: 'task' })).toEqual({
57
+ defs: undefined,
58
+ });
59
+ });
60
+
61
+ it('returns the value as is when the path does not fit it', () => {
62
+ const list = ['a'];
63
+
64
+ expect(setValueAtPath(list, ['0'], 'b')).toBe(list);
65
+ expect(setValueAtPath('text', ['length'], 1)).toBe('text');
66
+ expect(setValueAtPath({ name: null }, ['name', 'first'], 'x')).toEqual({
67
+ name: null,
68
+ });
69
+ });
70
+ });
@@ -0,0 +1,67 @@
1
+ /*
2
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
3
+ * Copyright (c) 2026 Hexastack.
4
+ * Full terms: see LICENSE.md.
5
+ */
6
+
7
+ /**
8
+ * Read a nested value. Array segments must be numbers; a path that leaves
9
+ * the value resolves to `undefined`.
10
+ */
11
+ export const getValueAtPath = (
12
+ value: unknown,
13
+ path: ReadonlyArray<string | number>,
14
+ ): unknown =>
15
+ path.reduce<unknown>((acc, key) => {
16
+ if (acc === null || acc === undefined) {
17
+ return undefined;
18
+ }
19
+ if (Array.isArray(acc)) {
20
+ return typeof key === 'number' ? acc[key] : undefined;
21
+ }
22
+ if (typeof acc === 'object') {
23
+ return (acc as Record<string, unknown>)[String(key)];
24
+ }
25
+
26
+ return undefined;
27
+ }, value);
28
+
29
+ /**
30
+ * Copy a value with one nested value replaced; the input is left untouched.
31
+ * A path that does not fit the value returns it as is.
32
+ */
33
+ export const setValueAtPath = <T>(
34
+ value: T,
35
+ path: ReadonlyArray<string | number>,
36
+ nextValue: unknown,
37
+ ): T => {
38
+ if (path.length === 0) {
39
+ return nextValue as T;
40
+ }
41
+
42
+ const [key, ...rest] = path;
43
+
44
+ if (Array.isArray(value)) {
45
+ if (typeof key !== 'number') {
46
+ return value;
47
+ }
48
+ const nextArray = [...value];
49
+
50
+ nextArray[key] = setValueAtPath(value[key], rest, nextValue);
51
+
52
+ return nextArray as unknown as T;
53
+ }
54
+
55
+ if (value && typeof value === 'object') {
56
+ return {
57
+ ...(value as Record<string, unknown>),
58
+ [String(key)]: setValueAtPath(
59
+ (value as Record<string, unknown>)[String(key)],
60
+ rest,
61
+ nextValue,
62
+ ),
63
+ } as T;
64
+ }
65
+
66
+ return value;
67
+ };