@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
@@ -214,7 +214,7 @@ const parseCheckpoint = (checkpoint) => {
214
214
  }
215
215
  const result = exports.workflowCheckpointSchema.safeParse(checkpoint);
216
216
  if (!result.success) {
217
- const issues = result.error.issues.map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`);
217
+ const issues = (0, resume_payload_1.describeSchemaIssues)(result.error.issues);
218
218
  throw new errors_1.WorkflowCheckpointInvalidError('malformed', `Checkpoint does not match the expected shape: ${issues.join('; ')}`, { issues });
219
219
  }
220
220
  return result.data;
@@ -38,10 +38,9 @@ exports.WORKFLOW_RUN_STATUSES = [
38
38
  */
39
39
  class BaseWorkflowContext {
40
40
  /**
41
- * Sets up the context and copies any initial state onto the instance.
41
+ * Sets up the context with its initial state.
42
42
  *
43
- * @param initialState - Optional properties to assign to the context instance.
44
- * @param eventEmitter - Optional workflow event emitter to expose to actions.
43
+ * @param initialState - State exposed to expressions as `$context`.
45
44
  */
46
45
  constructor(initialState) {
47
46
  this.state = (initialState ?? {});
@@ -14,7 +14,11 @@ const jsonata_1 = __importDefault(require("jsonata"));
14
14
  const yaml_1 = require("yaml");
15
15
  const zod_1 = require("zod");
16
16
  const base_binding_1 = require("./bindings/base-binding");
17
+ const clone_1 = require("./utils/clone");
18
+ const flow_steps_1 = require("./utils/flow-steps");
17
19
  const naming_1 = require("./utils/naming");
20
+ const object_path_1 = require("./utils/object-path");
21
+ const validation_issue_1 = require("./validation-issue");
18
22
  const workflow_values_1 = require("./workflow-values");
19
23
  exports.ExpressionStringSchema = zod_1.z
20
24
  .string()
@@ -50,44 +54,52 @@ exports.JsonValueSchema = zod_1.z.lazy(() => zod_1.z.union([
50
54
  zod_1.z.array(exports.JsonValueSchema),
51
55
  zod_1.z.record(zod_1.z.string(), exports.JsonValueSchema),
52
56
  ]));
53
- const InputFieldSchema = zod_1.z.lazy(() => zod_1.z
54
- .strictObject({
55
- type: zod_1.z.enum([
56
- 'string',
57
- 'number',
58
- 'integer',
59
- 'boolean',
60
- 'array',
61
- 'object',
62
- ]),
63
- description: zod_1.z.string().optional(),
64
- enum: zod_1.z.array(zod_1.z.union([zod_1.z.string(), zod_1.z.number(), zod_1.z.boolean()])).optional(),
65
- items: InputFieldSchema.optional(),
66
- properties: zod_1.z.record(zod_1.z.string(), InputFieldSchema).optional(),
67
- })
68
- .superRefine((value, ctx) => {
69
- if (value.type === 'array' && !value.items) {
57
+ const isJsonObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
58
+ /**
59
+ * Tell whether `inputs.schema` is written as the field map this DSL used
60
+ * before JSON Schema (`{ question: { type: string } }`). A JSON Schema has a
61
+ * string `type` at its root, which a field map never has: each of its values
62
+ * is a field, an object with its own `type`.
63
+ */
64
+ const isInputFieldMap = (schema) => {
65
+ const fields = Object.values(schema);
66
+ return (typeof schema.type !== 'string' &&
67
+ fields.length > 0 &&
68
+ fields.every((field) => isJsonObject(field) && 'type' in field));
69
+ };
70
+ const WorkflowInputSchemaSchema = zod_1.z
71
+ .record(zod_1.z.string(), exports.JsonValueSchema)
72
+ .superRefine((schema, ctx) => {
73
+ if (isInputFieldMap(schema)) {
70
74
  ctx.addIssue({
71
75
  code: 'custom',
72
- message: 'Array inputs must declare "items"',
73
- path: ['items'],
76
+ message: 'Workflow inputs must be described by a JSON Schema, e.g. ' +
77
+ '{ type: object, properties: { question: { type: string } }, ' +
78
+ 'required: [question] }; a map of fields ' +
79
+ '({ question: { type: string } }) is no longer supported',
74
80
  });
81
+ return;
75
82
  }
76
- if (value.type !== 'array' && value.items) {
83
+ if (schema.type !== 'object') {
77
84
  ctx.addIssue({
78
85
  code: 'custom',
79
- message: '"items" is only valid when type is "array"',
80
- path: ['items'],
86
+ message: 'Workflow inputs must be described by a JSON Schema of type ' +
87
+ '"object"; declare the input fields under "properties"',
88
+ path: ['type'],
81
89
  });
90
+ return;
91
+ }
92
+ try {
93
+ zod_1.z.fromJSONSchema(schema);
82
94
  }
83
- if (value.type !== 'object' && value.properties) {
95
+ catch (error) {
96
+ const reason = error instanceof Error ? error.message : String(error);
84
97
  ctx.addIssue({
85
98
  code: 'custom',
86
- message: '"properties" is only valid when type is "object"',
87
- path: ['properties'],
99
+ message: `Not a valid JSON Schema (${reason})`,
88
100
  });
89
101
  }
90
- }));
102
+ });
91
103
  // Retry policy: exponential backoff per attempt, capped by max_delay_ms, with optional jitter multiplier.
92
104
  const RetriesSchema = zod_1.z.strictObject({
93
105
  enabled: zod_1.z.boolean().optional().meta({
@@ -230,7 +242,7 @@ exports.WorkflowMetadataSchema = zod_1.z.strictObject({
230
242
  description: zod_1.z.string().optional(),
231
243
  });
232
244
  const InputsSchema = zod_1.z.strictObject({
233
- schema: zod_1.z.record(zod_1.z.string(), InputFieldSchema).optional(),
245
+ schema: WorkflowInputSchemaSchema.optional(),
234
246
  });
235
247
  const DefaultsSchema = zod_1.z.strictObject({
236
248
  settings: exports.SettingsSchema.optional(),
@@ -243,44 +255,6 @@ exports.WorkflowDefinitionSchema = zod_1.z.strictObject({
243
255
  flow: zod_1.z.array(exports.FlowStepSchema),
244
256
  outputs: zod_1.z.record(zod_1.z.string(), exports.ExpressionStringSchema),
245
257
  });
246
- const collectTaskReferences = (steps, basePath = ['flow']) => {
247
- const refs = [];
248
- steps.forEach((step, index) => {
249
- const stepPath = [...basePath, index];
250
- if ('do' in step) {
251
- refs.push({ taskId: step.do, path: [...stepPath, 'do'] });
252
- return;
253
- }
254
- if ('parallel' in step) {
255
- refs.push(...collectTaskReferences(step.parallel.steps, [
256
- ...stepPath,
257
- 'parallel',
258
- 'steps',
259
- ]));
260
- return;
261
- }
262
- if ('conditional' in step) {
263
- step.conditional.when.forEach((branch, branchIndex) => {
264
- refs.push(...collectTaskReferences(branch.steps, [
265
- ...stepPath,
266
- 'conditional',
267
- 'when',
268
- branchIndex,
269
- 'steps',
270
- ]));
271
- });
272
- return;
273
- }
274
- if ('loop' in step) {
275
- refs.push(...collectTaskReferences(step.loop.steps, [
276
- ...stepPath,
277
- 'loop',
278
- 'steps',
279
- ]));
280
- }
281
- });
282
- return refs;
283
- };
284
258
  const isTaskDefinition = (definition) => definition.kind === exports.TASK_KIND;
285
259
  exports.isTaskDefinition = isTaskDefinition;
286
260
  const extractTaskDefinitions = (defs) => Object.entries(defs).reduce((tasks, [defName, def]) => {
@@ -291,20 +265,8 @@ const extractTaskDefinitions = (defs) => Object.entries(defs).reduce((tasks, [de
291
265
  }, {});
292
266
  exports.extractTaskDefinitions = extractTaskDefinitions;
293
267
  const EXECUTION_SETTING_KEYS = new Set(Object.keys(exports.BaseSettingsSchema.shape));
294
- const isExpressionString = (value) => typeof value === 'string' && value.startsWith('=');
295
- const toIssuePath = (path) => path.filter((segment) => typeof segment === 'string' || typeof segment === 'number');
296
- const getValueAtPath = (value, path) => {
297
- let current = value;
298
- for (const segment of path) {
299
- if (current === null || typeof current !== 'object') {
300
- return undefined;
301
- }
302
- current = current[segment];
303
- }
304
- return current;
305
- };
306
268
  const extractActionSettings = (settings) => {
307
- if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
269
+ if (!(0, clone_1.isRecord)(settings)) {
308
270
  return {};
309
271
  }
310
272
  return Object.fromEntries(Object.entries(settings).filter(([key]) => !EXECUTION_SETTING_KEYS.has(key)));
@@ -315,10 +277,10 @@ const toActionSchemaIssues = ({ actionName, code, payload, schema, section, task
315
277
  return [];
316
278
  }
317
279
  return result.error.issues.flatMap((issue) => {
318
- const issuePath = toIssuePath(issue.path);
280
+ const issuePath = (0, validation_issue_1.toIssuePath)(issue.path);
319
281
  // Expressions are resolved immediately before action execution, so their
320
282
  // eventual runtime type cannot be checked while validating the definition.
321
- if (isExpressionString(getValueAtPath(payload, issuePath))) {
283
+ if ((0, workflow_values_1.isExpressionString)((0, object_path_1.getValueAtPath)(payload, issuePath))) {
322
284
  return [];
323
285
  }
324
286
  const path = ['defs', taskId, section, ...issuePath];
@@ -370,14 +332,6 @@ const validateTaskActionSchemas = (definition, actions) => {
370
332
  }
371
333
  return issues;
372
334
  };
373
- const toSchemaIssues = (zodIssues) => zodIssues.map((issue) => {
374
- const path = issue.path.join('.') || '<root>';
375
- return {
376
- code: 'schema',
377
- message: `${path}: ${issue.message}`,
378
- path: issue.path.filter((segment) => typeof segment === 'string' || typeof segment === 'number'),
379
- };
380
- });
381
335
  const invalidWorkflow = (issues) => ({
382
336
  success: false,
383
337
  issues,
@@ -398,12 +352,12 @@ function validateWorkflow(input, options) {
398
352
  }
399
353
  const parsed = exports.WorkflowDefinitionSchema.safeParse(candidate);
400
354
  if (!parsed.success) {
401
- return invalidWorkflow(toSchemaIssues(parsed.error.issues));
355
+ return invalidWorkflow((0, validation_issue_1.toValidationIssues)('schema', parsed.error.issues));
402
356
  }
403
357
  const issues = [];
404
358
  const taskDefinitions = (0, exports.extractTaskDefinitions)(parsed.data.defs);
405
359
  const reportedMissingTasks = new Set();
406
- for (const { taskId, path } of collectTaskReferences(parsed.data.flow)) {
360
+ for (const { taskId, path } of (0, flow_steps_1.collectTaskReferences)(parsed.data.flow)) {
407
361
  if (Object.prototype.hasOwnProperty.call(taskDefinitions, taskId) ||
408
362
  reportedMissingTasks.has(taskId)) {
409
363
  continue;
@@ -5,7 +5,7 @@
5
5
  * Full terms: see LICENSE.md.
6
6
  */
7
7
  Object.defineProperty(exports, "__esModule", { value: true });
8
- exports.createLinkedAbortController = exports.throwIfAborted = exports.getAbortReason = exports.isNonDeterministicWorkflowError = exports.isWorkflowResumeRejectedError = exports.NonDeterministicWorkflowError = exports.WorkflowResumeRejectedError = exports.WorkflowWaitNotFoundError = exports.WorkflowWaitAmbiguousError = exports.WorkflowDefinitionDriftError = exports.WorkflowCheckpointInvalidError = exports.WorkflowResumeError = exports.WorkflowCancellationError = void 0;
8
+ exports.createLinkedAbortController = exports.throwIfAborted = exports.getAbortReason = exports.isNonDeterministicWorkflowError = exports.isWorkflowResumeRejectedError = exports.NonDeterministicWorkflowError = exports.WorkflowResumeRejectedError = exports.WorkflowWaitNotFoundError = exports.WorkflowWaitAmbiguousError = exports.WorkflowDefinitionDriftError = exports.WorkflowCheckpointInvalidError = exports.WorkflowResumeError = exports.WorkflowInputRejectedError = exports.WorkflowCancellationError = void 0;
9
9
  class WorkflowCancellationError extends Error {
10
10
  constructor(message = 'Workflow execution was cancelled.') {
11
11
  super(message);
@@ -13,6 +13,18 @@ class WorkflowCancellationError extends Error {
13
13
  }
14
14
  }
15
15
  exports.WorkflowCancellationError = WorkflowCancellationError;
16
+ /**
17
+ * The input payload passed to `start()` does not match the workflow's
18
+ * `inputs.schema`. Nothing ran: the runner is left as it was before the call.
19
+ */
20
+ class WorkflowInputRejectedError extends Error {
21
+ constructor(issues) {
22
+ super(`Workflow input was rejected: ${issues.join('; ')}`);
23
+ this.name = 'WorkflowInputRejectedError';
24
+ this.issues = issues;
25
+ }
26
+ }
27
+ exports.WorkflowInputRejectedError = WorkflowInputRejectedError;
16
28
  /** Base class for every reason a suspended run cannot be resumed. */
17
29
  class WorkflowResumeError extends Error {
18
30
  }
package/dist/cjs/index.js CHANGED
@@ -19,7 +19,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
19
19
  for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
20
20
  };
21
21
  Object.defineProperty(exports, "__esModule", { value: true });
22
- exports.remapWorkflowDefinitionResourceRefs = exports.collectWorkflowDefinitionResourceRefs = exports.withTimeout = exports.sleep = exports.toSnakeCase = exports.isSnakeCaseName = exports.assertSnakeCaseName = exports.mergeSettings = exports.evaluateValue = exports.evaluateMapping = exports.compileValue = exports.WorkflowWaitNotFoundError = exports.WorkflowWaitAmbiguousError = exports.WorkflowResumeRejectedError = exports.WorkflowResumeError = exports.WorkflowDefinitionDriftError = exports.WorkflowCheckpointInvalidError = exports.WorkflowCancellationError = exports.NonDeterministicWorkflowError = exports.fingerprintWorkflow = exports.workflowCheckpointSchema = exports.validateCheckpoint = exports.collectWaits = exports.CHECKPOINT_VERSION = exports.StepType = exports.WorkflowRunner = exports.WorkflowEventEmitter = exports.Workflow = exports.compileWorkflow = exports.issueMessages = exports.WORKFLOW_RUN_STATUSES = exports.EWorkflowRunStatus = exports.BaseWorkflowContext = exports.defineAction = exports.AbstractAction = void 0;
22
+ exports.remapWorkflowDefinitionResourceRefs = exports.collectWorkflowDefinitionResourceRefs = exports.withTimeout = exports.sleep = exports.toSnakeCase = exports.isSnakeCaseName = exports.assertSnakeCaseName = exports.mergeSettings = exports.evaluateValue = exports.evaluateMapping = exports.compileValue = exports.WorkflowWaitNotFoundError = exports.WorkflowWaitAmbiguousError = exports.WorkflowResumeRejectedError = exports.WorkflowResumeError = exports.WorkflowInputRejectedError = exports.WorkflowDefinitionDriftError = exports.WorkflowCheckpointInvalidError = exports.WorkflowCancellationError = exports.NonDeterministicWorkflowError = exports.fingerprintWorkflow = exports.workflowCheckpointSchema = exports.validateCheckpoint = exports.collectWaits = exports.CHECKPOINT_VERSION = exports.StepType = exports.WorkflowRunner = exports.WorkflowEventEmitter = exports.Workflow = exports.compileWorkflow = exports.buildWorkflowInputParser = exports.issueMessages = exports.WORKFLOW_RUN_STATUSES = exports.EWorkflowRunStatus = exports.BaseWorkflowContext = exports.defineAction = exports.AbstractAction = void 0;
23
23
  var abstract_action_1 = require("./action/abstract-action");
24
24
  Object.defineProperty(exports, "AbstractAction", { enumerable: true, get: function () { return abstract_action_1.AbstractAction; } });
25
25
  var action_1 = require("./action/action");
@@ -32,6 +32,7 @@ __exportStar(require("./dsl.types"), exports);
32
32
  var validation_issue_1 = require("./validation-issue");
33
33
  Object.defineProperty(exports, "issueMessages", { enumerable: true, get: function () { return validation_issue_1.issueMessages; } });
34
34
  var workflow_1 = require("./workflow");
35
+ Object.defineProperty(exports, "buildWorkflowInputParser", { enumerable: true, get: function () { return workflow_1.buildWorkflowInputParser; } });
35
36
  Object.defineProperty(exports, "compileWorkflow", { enumerable: true, get: function () { return workflow_1.compileWorkflow; } });
36
37
  Object.defineProperty(exports, "Workflow", { enumerable: true, get: function () { return workflow_1.Workflow; } });
37
38
  Object.defineProperty(exports, "WorkflowEventEmitter", { enumerable: true, get: function () { return workflow_1.WorkflowEventEmitter; } });
@@ -50,6 +51,7 @@ Object.defineProperty(exports, "NonDeterministicWorkflowError", { enumerable: tr
50
51
  Object.defineProperty(exports, "WorkflowCancellationError", { enumerable: true, get: function () { return errors_1.WorkflowCancellationError; } });
51
52
  Object.defineProperty(exports, "WorkflowCheckpointInvalidError", { enumerable: true, get: function () { return errors_1.WorkflowCheckpointInvalidError; } });
52
53
  Object.defineProperty(exports, "WorkflowDefinitionDriftError", { enumerable: true, get: function () { return errors_1.WorkflowDefinitionDriftError; } });
54
+ Object.defineProperty(exports, "WorkflowInputRejectedError", { enumerable: true, get: function () { return errors_1.WorkflowInputRejectedError; } });
53
55
  Object.defineProperty(exports, "WorkflowResumeError", { enumerable: true, get: function () { return errors_1.WorkflowResumeError; } });
54
56
  Object.defineProperty(exports, "WorkflowResumeRejectedError", { enumerable: true, get: function () { return errors_1.WorkflowResumeRejectedError; } });
55
57
  Object.defineProperty(exports, "WorkflowWaitAmbiguousError", { enumerable: true, get: function () { return errors_1.WorkflowWaitAmbiguousError; } });
@@ -9,6 +9,7 @@ exports.describeResumePayload = describeResumePayload;
9
9
  exports.isPayloadOptional = isPayloadOptional;
10
10
  exports.findNonJsonTypes = findNonJsonTypes;
11
11
  exports.checkResumePayload = checkResumePayload;
12
+ exports.describeSchemaIssues = describeSchemaIssues;
12
13
  exports.rejectResumePayload = rejectResumePayload;
13
14
  const zod_1 = require("zod");
14
15
  const errors_1 = require("./errors");
@@ -216,6 +217,15 @@ function checkResumePayload(wait, resumeData) {
216
217
  error: rejectResumePayload(`wait "${wait.waitId}"`, result.error.issues),
217
218
  };
218
219
  }
220
+ /**
221
+ * Describe schema issues as `<path>: <message>` lines.
222
+ *
223
+ * @param issues The schema issues.
224
+ * @returns One line per issue.
225
+ */
226
+ function describeSchemaIssues(issues) {
227
+ return issues.map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`);
228
+ }
219
229
  /**
220
230
  * Build the error refusing a payload that failed a schema.
221
231
  *
@@ -224,7 +234,7 @@ function checkResumePayload(wait, resumeData) {
224
234
  * @returns The rejection error.
225
235
  */
226
236
  function rejectResumePayload(subject, issues) {
227
- const messages = issues.map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`);
237
+ const messages = describeSchemaIssues(issues);
228
238
  return new errors_1.WorkflowResumeRejectedError(`Resume payload for ${subject} was rejected: ${messages.join('; ')}`, { issues: messages });
229
239
  }
230
240
  const relaxNode = (def, jsonSchema) => {
@@ -87,13 +87,7 @@ class RunnerRuntimeControl {
87
87
  assertJsonPayloadSchema(active, options.accepts);
88
88
  }
89
89
  if (options?.key) {
90
- // A reused key would resolve from the first call's answer on resume,
91
- // so the second call could never suspend.
92
- if (active.usedKeys.has(options.key)) {
93
- throw new Error(`workflow.suspend() key "${options.key}" is used more than once ` +
94
- `in step "${active.step.id}"; keys must be unique within an action body.`);
95
- }
96
- active.usedKeys.add(options.key);
90
+ claimSuspendKey(active, options.key);
97
91
  }
98
92
  active.cursor += 1;
99
93
  const suspendKey = buildSuspendKey(active.cursor, options?.key);
@@ -101,26 +95,7 @@ class RunnerRuntimeControl {
101
95
  if (active.awaitResults.has(suspendKey)) {
102
96
  return resolveRecordedResult(active, suspendKey, options?.accepts);
103
97
  }
104
- const request = {
105
- suspendKey,
106
- reason: options?.reason,
107
- data: options?.data,
108
- awaitResults: Object.fromEntries(active.awaitResults),
109
- };
110
- if (options?.accepts) {
111
- request.accepts = (0, resume_payload_1.describeResumePayload)(options.accepts);
112
- if ((0, resume_payload_1.isPayloadOptional)(options.accepts)) {
113
- request.payloadOptional = true;
114
- }
115
- }
116
- const waiter = active.waiter;
117
- if (waiter) {
118
- active.waiter = undefined;
119
- waiter(request);
120
- }
121
- else {
122
- active.pending.push(request);
123
- }
98
+ deliverSuspension(active, buildSuspensionRequest(active, suspendKey, options));
124
99
  // Never settles: the step executor aborts this body, and resuming re-runs
125
100
  // it so that this call resolves from `awaitResults` instead.
126
101
  return new Promise(() => undefined);
@@ -178,6 +153,43 @@ class RunnerRuntimeControl {
178
153
  }
179
154
  }
180
155
  exports.RunnerRuntimeControl = RunnerRuntimeControl;
156
+ /**
157
+ * Reserve a user key for the running attempt. A reused key would resolve from
158
+ * the first call's answer on resume, so the second call could never suspend.
159
+ */
160
+ const claimSuspendKey = (active, key) => {
161
+ if (active.usedKeys.has(key)) {
162
+ throw new Error(`workflow.suspend() key "${key}" is used more than once ` +
163
+ `in step "${active.step.id}"; keys must be unique within an action body.`);
164
+ }
165
+ active.usedKeys.add(key);
166
+ };
167
+ const buildSuspensionRequest = (active, suspendKey, options) => {
168
+ const request = {
169
+ suspendKey,
170
+ reason: options?.reason,
171
+ data: options?.data,
172
+ awaitResults: Object.fromEntries(active.awaitResults),
173
+ };
174
+ if (options?.accepts) {
175
+ request.accepts = (0, resume_payload_1.describeResumePayload)(options.accepts);
176
+ if ((0, resume_payload_1.isPayloadOptional)(options.accepts)) {
177
+ request.payloadOptional = true;
178
+ }
179
+ }
180
+ return request;
181
+ };
182
+ /** Hand a request to the executor waiting for one, or queue it until it waits. */
183
+ const deliverSuspension = (active, request) => {
184
+ const waiter = active.waiter;
185
+ if (waiter) {
186
+ active.waiter = undefined;
187
+ waiter(request);
188
+ }
189
+ else {
190
+ active.pending.push(request);
191
+ }
192
+ };
181
193
  /**
182
194
  * Refuse an `accepts` schema that no JSON payload can match: the wait it
183
195
  * opens could never be resumed, since payloads are read back as JSON.
@@ -7,6 +7,7 @@
7
7
  Object.defineProperty(exports, "__esModule", { value: true });
8
8
  exports.executeConditional = executeConditional;
9
9
  const workflow_values_1 = require("../workflow-values");
10
+ const scope_1 = require("./scope");
10
11
  const skip_helpers_1 = require("./skip-helpers");
11
12
  /**
12
13
  * Evaluate a conditional step by checking branches in order and executing the first match.
@@ -41,15 +42,9 @@ async function executeConditional(env, step, state, path, frame) {
41
42
  return undefined;
42
43
  }
43
44
  const chooseBranch = async (env, step, state) => {
45
+ const scope = (0, scope_1.buildEvaluationScope)(env, state);
44
46
  for (let index = 0; index < step.branches.length; index += 1) {
45
47
  const branch = step.branches[index];
46
- const scope = {
47
- input: state.input,
48
- context: env.context.state,
49
- output: state.output,
50
- iteration: state.iteration,
51
- accumulator: state.accumulator,
52
- };
53
48
  const conditionResult = branch.condition !== undefined
54
49
  ? await (0, workflow_values_1.evaluateValue)(branch.condition, scope)
55
50
  : true;
@@ -9,6 +9,7 @@ exports.executeLoop = executeLoop;
9
9
  exports.updateAccumulator = updateAccumulator;
10
10
  exports.shouldStopLoop = shouldStopLoop;
11
11
  const workflow_values_1 = require("../workflow-values");
12
+ const scope_1 = require("./scope");
12
13
  /**
13
14
  * Execute a loop step by iterating over input items and executing child steps.
14
15
  *
@@ -54,7 +55,10 @@ async function executeForEachLoop(env, step, state, path, frame) {
54
55
  child,
55
56
  };
56
57
  }
57
- const postScope = buildScope(env, iterationState, { item, index }, accumulator);
58
+ const postScope = (0, scope_1.buildEvaluationScope)(env, iterationState, {
59
+ iteration: { item, index },
60
+ accumulator,
61
+ });
58
62
  accumulator = await updateAccumulator(step, postScope, accumulator);
59
63
  const shouldStop = await shouldStopLoop(step, postScope);
60
64
  if (shouldStop) {
@@ -73,7 +77,10 @@ async function executeWhileLoop(env, step, state, path, frame) {
73
77
  const resumedChild = frame && index === frame.index ? frame.child : undefined;
74
78
  // The guard of a resumed iteration already passed before it suspended.
75
79
  if (!resumedChild) {
76
- const conditionScope = buildScope(env, state, { item: undefined, index }, accumulator);
80
+ const conditionScope = (0, scope_1.buildEvaluationScope)(env, state, {
81
+ iteration: { item: undefined, index },
82
+ accumulator,
83
+ });
77
84
  const shouldContinue = await (0, workflow_values_1.evaluateValue)(step.while, conditionScope);
78
85
  if (!Boolean(shouldContinue)) {
79
86
  break;
@@ -89,7 +96,10 @@ async function executeWhileLoop(env, step, state, path, frame) {
89
96
  if (child) {
90
97
  return { kind: 'loop', stepId: step.id, index, accumulator, child };
91
98
  }
92
- const postScope = buildScope(env, iterationState, { item: undefined, index }, accumulator);
99
+ const postScope = (0, scope_1.buildEvaluationScope)(env, iterationState, {
100
+ iteration: { item: undefined, index },
101
+ accumulator,
102
+ });
93
103
  accumulator = await updateAccumulator(step, postScope, accumulator);
94
104
  state.output = iterationState.output;
95
105
  }
@@ -97,13 +107,7 @@ async function executeWhileLoop(env, step, state, path, frame) {
97
107
  return undefined;
98
108
  }
99
109
  async function resolveItems(env, step, state) {
100
- const items = await (0, workflow_values_1.evaluateValue)(step.forEach.in, {
101
- input: state.input,
102
- context: env.context.state,
103
- output: state.output,
104
- iteration: state.iteration,
105
- accumulator: state.accumulator,
106
- });
110
+ const items = await (0, workflow_values_1.evaluateValue)(step.forEach.in, (0, scope_1.buildEvaluationScope)(env, state));
107
111
  return Array.isArray(items) ? items : [];
108
112
  }
109
113
  function finalizeAccumulatorState(step, state, accumulator) {
@@ -145,21 +149,3 @@ async function shouldStopLoop(step, scope) {
145
149
  const result = await (0, workflow_values_1.evaluateValue)(step.until, scope);
146
150
  return Boolean(result);
147
151
  }
148
- /**
149
- * Build the evaluation scope for loop iteration and accumulator updates.
150
- *
151
- * @param env Executor environment with workflow context.
152
- * @param state Execution state for the current iteration.
153
- * @param iteration The current iteration item and index.
154
- * @param accumulator Accumulator value to expose to expressions.
155
- * @returns An evaluation scope object.
156
- */
157
- function buildScope(env, state, iteration, accumulator) {
158
- return {
159
- input: state.input,
160
- context: env.context.state,
161
- output: state.output,
162
- iteration,
163
- accumulator,
164
- };
165
- }
@@ -55,10 +55,7 @@ async function executeParallel(env, step, state, path, frame) {
55
55
  baseContextState,
56
56
  recorded,
57
57
  }));
58
- if (step.strategy === 'wait_any') {
59
- return executeWaitAny(env, step, branches, outcomes, state);
60
- }
61
- return executeWaitAll(env, step, branches, outcomes, state);
58
+ return settleBlock(env, step, branches, outcomes, state);
62
59
  }
63
60
  /**
64
61
  * Settle a recorded branch that has nothing to run in this pass: a fulfilled
@@ -81,7 +78,13 @@ function keepRecordedBranch(env, index, recorded) {
81
78
  frame: recorded.child,
82
79
  };
83
80
  }
84
- async function executeWaitAll(env, step, branches, outcomes, state) {
81
+ /**
82
+ * Collect branch results as they settle. A failed or cancelled branch fails
83
+ * the block; under `wait_any` the first fulfilled branch wins it. Otherwise
84
+ * the block suspends once every branch settled with at least one suspended,
85
+ * and completes when all of them fulfilled.
86
+ */
87
+ async function settleBlock(env, step, branches, outcomes, state) {
85
88
  const pending = new Set(branches);
86
89
  while (pending.size > 0) {
87
90
  const { branch, result } = await raceNext(pending);
@@ -91,32 +94,18 @@ async function executeWaitAll(env, step, branches, outcomes, state) {
91
94
  await abandonBranches(env, branches, pending, outcomes, result.error);
92
95
  throw result.error;
93
96
  }
94
- }
95
- if (hasSuspendedBranch(outcomes)) {
96
- return buildParallelFrame(step, outcomes);
97
- }
98
- mergeBranchOutputs(state, outcomes);
99
- }
100
- async function executeWaitAny(env, step, branches, outcomes, state) {
101
- const pending = new Set(branches);
102
- while (pending.size > 0) {
103
- const { branch, result } = await raceNext(pending);
104
- pending.delete(branch);
105
- outcomes.set(result.index, result);
106
- if (result.status === 'suspended') {
107
- continue;
108
- }
109
- if (result.status === 'fulfilled') {
97
+ if (result.status === 'fulfilled' && step.strategy === 'wait_any') {
110
98
  // Parked losers will never be resumed; drop their waits with the race.
111
99
  await abandonBranches(env, branches, pending, outcomes, new errors_1.WorkflowCancellationError('Parallel wait_any winner selected.'), 'Parallel wait_any branch lost the race.');
112
100
  mergeBranchOutputs(state, new Map([[result.index, result]]));
113
101
  return undefined;
114
102
  }
115
- await abandonBranches(env, branches, pending, outcomes, result.error);
116
- throw result.error;
117
103
  }
118
- // Every branch settled without a winner, so all of them are suspended.
119
- return buildParallelFrame(step, outcomes);
104
+ // Without a winner, every branch of a wait_any block is suspended.
105
+ if (hasSuspendedBranch(outcomes)) {
106
+ return buildParallelFrame(step, outcomes);
107
+ }
108
+ mergeBranchOutputs(state, outcomes);
120
109
  }
121
110
  /**
122
111
  * Give up on the block: cancel the branches still running, let every branch
@@ -0,0 +1,25 @@
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.buildEvaluationScope = void 0;
9
+ /**
10
+ * Expose the live state of a step to its expressions.
11
+ *
12
+ * @param env Executor environment, for the context state.
13
+ * @param state Execution state of the step.
14
+ * @param overrides The iteration and accumulator a loop evaluates with.
15
+ * @returns The scope expressions are evaluated against.
16
+ */
17
+ const buildEvaluationScope = (env, state, overrides = {}) => ({
18
+ input: state.input,
19
+ context: env.context.state,
20
+ output: state.output,
21
+ iteration: state.iteration,
22
+ accumulator: state.accumulator,
23
+ ...overrides,
24
+ });
25
+ exports.buildEvaluationScope = buildEvaluationScope;