@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
package/src/workflow.ts CHANGED
@@ -23,6 +23,8 @@ import {
23
23
  validateWorkflow,
24
24
  type FlowStep,
25
25
  } from './dsl.types';
26
+ import { collectTaskReferences } from './utils/flow-steps';
27
+ import { getValueAtPath, setValueAtPath } from './utils/object-path';
26
28
  import { safeRenameTaskInDefinition as renameTaskInDefinition } from './utils/workflow-definition';
27
29
  import { issueMessages } from './validation-issue';
28
30
  import {
@@ -32,7 +34,7 @@ import {
32
34
  import { WorkflowRunner } from './workflow-runner';
33
35
  import type { CompiledWorkflow, WorkflowRunOptions } from './workflow-types';
34
36
 
35
- export { compileWorkflow } from './workflow-compiler';
37
+ export { buildWorkflowInputParser, compileWorkflow } from './workflow-compiler';
36
38
 
37
39
  export { WorkflowEventEmitter } from './workflow-event-emitter';
38
40
 
@@ -68,28 +70,39 @@ const getTaskNameFromStep = (step: unknown): string | null => {
68
70
 
69
71
  return typeof taskName === 'string' ? taskName : null;
70
72
  };
71
- const hasTaskReference = (steps: FlowStep[], taskName: string): boolean => {
72
- return steps.some((step) => {
73
- if ('do' in step) {
74
- return step.do === taskName;
75
- }
73
+ /** The step list a step path points into, and the index it points at. */
74
+ const resolveStepSlot = (
75
+ definition: WorkflowDefinition,
76
+ stepPath: FlowStepPath,
77
+ ): { stepsPath: FlowStepPath; steps: unknown[]; index: number } | null => {
78
+ const index = stepPath[stepPath.length - 1];
79
+ if (typeof index !== 'number') {
80
+ return null;
81
+ }
76
82
 
77
- if ('parallel' in step) {
78
- return hasTaskReference(step.parallel.steps, taskName);
79
- }
83
+ const stepsPath = stepPath.slice(0, -1);
84
+ const steps = getValueAtPath(definition, stepsPath);
80
85
 
81
- if ('conditional' in step) {
82
- return step.conditional.when.some((branch) =>
83
- hasTaskReference(branch.steps, taskName),
84
- );
85
- }
86
+ return Array.isArray(steps) ? { stepsPath, steps, index } : null;
87
+ };
88
+ /** Drop a task def once no flow step references it anymore. */
89
+ const dropUnreferencedTask = (
90
+ definition: WorkflowDefinition,
91
+ taskName: string,
92
+ ): WorkflowDefinition => {
93
+ if (
94
+ !Object.prototype.hasOwnProperty.call(definition.defs, taskName) ||
95
+ definition.defs[taskName]?.kind !== TASK_KIND ||
96
+ collectTaskReferences(definition.flow).some(
97
+ ({ taskId }) => taskId === taskName,
98
+ )
99
+ ) {
100
+ return definition;
101
+ }
86
102
 
87
- if ('loop' in step) {
88
- return hasTaskReference(step.loop.steps, taskName);
89
- }
103
+ const { [taskName]: _removedTask, ...remainingDefs } = definition.defs;
90
104
 
91
- return false;
92
- });
105
+ return { ...definition, defs: remainingDefs };
93
106
  };
94
107
 
95
108
  /**
@@ -111,19 +124,7 @@ export class Workflow {
111
124
  definition: WorkflowDefinition,
112
125
  options: WorkflowCompileOptions,
113
126
  ): Workflow {
114
- const validation = validateWorkflow(definition, {
115
- bindingKinds: options.bindingKinds,
116
- actions: options.actions,
117
- });
118
- if (!validation.success) {
119
- throw new Error(
120
- `Workflow validation failed: ${issueMessages(validation.issues).join('; ')}`,
121
- );
122
- }
123
-
124
- const compiled = compileWorkflow(validation.data, options);
125
-
126
- return new Workflow(compiled);
127
+ return Workflow.validateAndCompile(definition, options);
127
128
  }
128
129
 
129
130
  /**
@@ -131,7 +132,14 @@ export class Workflow {
131
132
  * YAML is validated and compiled before being wrapped in a {@link Workflow} instance.
132
133
  */
133
134
  static fromYaml(yaml: string, options: WorkflowCompileOptions): Workflow {
134
- const validation = validateWorkflow(yaml, {
135
+ return Workflow.validateAndCompile(yaml, options);
136
+ }
137
+
138
+ private static validateAndCompile(
139
+ source: WorkflowDefinition | string,
140
+ options: WorkflowCompileOptions,
141
+ ): Workflow {
142
+ const validation = validateWorkflow(source, {
135
143
  bindingKinds: options.bindingKinds,
136
144
  actions: options.actions,
137
145
  });
@@ -160,19 +168,7 @@ export class Workflow {
160
168
  * Resolve a nested value from a workflow definition by path.
161
169
  */
162
170
  static getValueAtPath(value: unknown, path: FlowStepPath): unknown {
163
- return path.reduce<unknown>((acc, key) => {
164
- if (acc === null || acc === undefined) {
165
- return undefined;
166
- }
167
- if (Array.isArray(acc)) {
168
- return typeof key === 'number' ? acc[key] : undefined;
169
- }
170
- if (typeof acc === 'object') {
171
- return (acc as Record<string, unknown>)[String(key)];
172
- }
173
-
174
- return undefined;
175
- }, value);
171
+ return getValueAtPath(value, path);
176
172
  }
177
173
 
178
174
  /**
@@ -183,35 +179,7 @@ export class Workflow {
183
179
  path: FlowStepPath,
184
180
  nextValue: unknown,
185
181
  ): T {
186
- if (path.length === 0) {
187
- return nextValue as T;
188
- }
189
-
190
- const [key, ...rest] = path;
191
-
192
- if (Array.isArray(value)) {
193
- if (typeof key !== 'number') {
194
- return value;
195
- }
196
- const nextArray = [...value];
197
-
198
- nextArray[key] = Workflow.setValueAtPath(value[key], rest, nextValue);
199
-
200
- return nextArray as unknown as T;
201
- }
202
-
203
- if (value && typeof value === 'object') {
204
- return {
205
- ...(value as Record<string, unknown>),
206
- [String(key)]: Workflow.setValueAtPath(
207
- (value as Record<string, unknown>)[String(key)],
208
- rest,
209
- nextValue,
210
- ),
211
- } as T;
212
- }
213
-
214
- return value;
182
+ return setValueAtPath(value, path, nextValue);
215
183
  }
216
184
 
217
185
  /**
@@ -221,63 +189,25 @@ export class Workflow {
221
189
  definition: WorkflowDefinition,
222
190
  stepPath: FlowStepPath,
223
191
  ): WorkflowDefinition | null {
224
- if (!stepPath.length) {
225
- return null;
226
- }
227
-
228
- const removeIndex = stepPath[stepPath.length - 1];
229
-
230
- if (typeof removeIndex !== 'number') {
231
- return null;
232
- }
233
-
234
- const stepsPath = stepPath.slice(0, -1);
235
- const steps = Workflow.getValueAtPath(definition, stepsPath);
236
-
237
- if (!Array.isArray(steps)) {
238
- return null;
239
- }
240
-
241
- if (removeIndex < 0 || removeIndex >= steps.length) {
192
+ const slot = resolveStepSlot(definition, stepPath);
193
+ if (!slot || slot.index < 0 || slot.index >= slot.steps.length) {
242
194
  return null;
243
195
  }
244
196
 
245
- const removedTaskName = getTaskNameFromStep(steps[removeIndex]);
246
- const nextSteps = [...steps];
197
+ const removedTaskName = getTaskNameFromStep(slot.steps[slot.index]);
198
+ const nextSteps = [...slot.steps];
247
199
 
248
- nextSteps.splice(removeIndex, 1);
200
+ nextSteps.splice(slot.index, 1);
249
201
 
250
- const nextDefinition = Workflow.setValueAtPath(
202
+ const nextDefinition = setValueAtPath(
251
203
  definition,
252
- stepsPath,
204
+ slot.stepsPath,
253
205
  nextSteps,
254
206
  );
255
207
 
256
- if (
257
- !removedTaskName ||
258
- !Object.prototype.hasOwnProperty.call(
259
- nextDefinition.defs,
260
- removedTaskName,
261
- )
262
- ) {
263
- return nextDefinition;
264
- }
265
-
266
- if (nextDefinition.defs[removedTaskName]?.kind !== TASK_KIND) {
267
- return nextDefinition;
268
- }
269
-
270
- if (hasTaskReference(nextDefinition.flow, removedTaskName)) {
271
- return nextDefinition;
272
- }
273
-
274
- const { [removedTaskName]: _removedTask, ...remainingDefs } =
275
- nextDefinition.defs;
276
-
277
- return {
278
- ...nextDefinition,
279
- defs: remainingDefs,
280
- };
208
+ return removedTaskName
209
+ ? dropUnreferencedTask(nextDefinition, removedTaskName)
210
+ : nextDefinition;
281
211
  }
282
212
 
283
213
  /**
@@ -288,29 +218,17 @@ export class Workflow {
288
218
  insertPath: FlowStepPath,
289
219
  step: FlowStep,
290
220
  ): WorkflowDefinition | null {
291
- if (!insertPath.length) {
292
- return null;
293
- }
294
-
295
- const insertIndex = insertPath[insertPath.length - 1];
296
-
297
- if (typeof insertIndex !== 'number') {
298
- return null;
299
- }
300
-
301
- const stepsPath = insertPath.slice(0, -1);
302
- const steps = Workflow.getValueAtPath(definition, stepsPath);
303
-
304
- if (!Array.isArray(steps)) {
221
+ const slot = resolveStepSlot(definition, insertPath);
222
+ if (!slot) {
305
223
  return null;
306
224
  }
307
225
 
308
- const nextSteps = [...steps];
309
- const safeIndex = Math.min(Math.max(insertIndex, 0), nextSteps.length);
226
+ const nextSteps = [...slot.steps];
227
+ const safeIndex = Math.min(Math.max(slot.index, 0), nextSteps.length);
310
228
 
311
229
  nextSteps.splice(safeIndex, 0, step);
312
230
 
313
- return Workflow.setValueAtPath(definition, stepsPath, nextSteps);
231
+ return setValueAtPath(definition, slot.stepsPath, nextSteps);
314
232
  }
315
233
 
316
234
  /**