@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
package/README.md CHANGED
@@ -25,7 +25,7 @@ The package ships both ESM (`import`) and CommonJS (`require`) entrypoints plus
25
25
 
26
26
  A workflow is a single YAML (or object) that declares inputs, context, defaults, definitions, control-flow, and outputs. The full annotated reference lives in `./DSL.md` and `examples/full/workflow.yml`. The important pieces:
27
27
 
28
- - `inputs.schema`: JSON-schema-like fields validated at runtime.
28
+ - `inputs.schema`: JSON Schema (root `type: object`) of the payload a run is started with. The payload is checked against it before anything runs, and its `default` values are filled in.
29
29
  - `context`: read-only values injected by the host (including any long-term state) and exposed to expressions.
30
30
  - `defaults.settings`: inherited by every task (timeouts, retries, and action-specific settings).
31
31
  - `defs`: required root registry for all definitions.
@@ -168,8 +168,11 @@ const workflow = Workflow.fromYaml(yamlSource, {
168
168
  ```yaml
169
169
  inputs:
170
170
  schema:
171
- user_id:
172
- type: string
171
+ type: object
172
+ properties:
173
+ user_id:
174
+ type: string
175
+ required: [user_id]
173
176
  defs:
174
177
  greet_user:
175
178
  kind: task
@@ -182,6 +185,12 @@ outputs:
182
185
  reply: "='Hello ' & $output.greet_user.body"
183
186
  ```
184
187
 
188
+ ### Workflow inputs
189
+
190
+ `runner.start({ inputData })` checks `inputData` against `inputs.schema` and throws a `WorkflowInputRejectedError` (with `issues`, one `<path>: <message>` line each) when it does not match; nothing has run at that point. A host that wants to refuse a payload before creating a run can build the same parser with `buildWorkflowInputParser(definition.inputs?.schema)`.
191
+
192
+ > **Breaking change.** `inputs.schema` used to be a map of fields (`{ user_id: { type: string } }`) and is now a JSON Schema. Definitions in the old form fail validation with a message naming the expected format, and the `InputField` type is replaced by `WorkflowInputSchema`. To convert a definition, move the fields under `properties` and add `type: object`; add `additionalProperties: false` to keep refusing undeclared keys, which the old form always did. See `DSL.md` ("Workflow inputs").
193
+
185
194
  ## Custom JSONata functions
186
195
 
187
196
  You can inject additional JSONata functions when compiling a workflow:
@@ -12,6 +12,39 @@ const errors_1 = require("../errors");
12
12
  const naming_1 = require("../utils/naming");
13
13
  const timeout_1 = require("../utils/timeout");
14
14
  const BASE_SETTINGS_KEYS = Object.keys(dsl_types_1.BaseSettingsSchema.shape);
15
+ /**
16
+ * Read the retry settings of a run. Without a `retries` block an action runs
17
+ * once; a block that leaves `enabled` out turns retries on.
18
+ */
19
+ const resolveRetryPolicy = (retries) => {
20
+ if (!retries) {
21
+ return {
22
+ maxAttempts: 1,
23
+ backoffMs: 0,
24
+ maxDelayMs: 0,
25
+ jitter: 0,
26
+ multiplier: 1,
27
+ };
28
+ }
29
+ return {
30
+ maxAttempts: (retries.enabled ?? true) ? retries.max_attempts : 1,
31
+ backoffMs: retries.backoff_ms ?? 0,
32
+ maxDelayMs: retries.max_delay_ms,
33
+ jitter: retries.jitter,
34
+ multiplier: retries.multiplier,
35
+ };
36
+ };
37
+ /** Cap a retry delay at the policy's `max_delay_ms`, when one is set. */
38
+ const capDelay = (delay, { maxDelayMs }) => maxDelayMs > 0 ? Math.min(delay, maxDelayMs) : delay;
39
+ /** Pause before the next attempt: the delay, capped, then spread by the jitter. */
40
+ const retryPause = (delay, policy) => {
41
+ const cappedDelay = capDelay(delay, policy);
42
+ if (cappedDelay <= 0) {
43
+ return 0;
44
+ }
45
+ const jitterFactor = policy.jitter > 0 ? 1 + (Math.random() * 2 - 1) * policy.jitter : 1;
46
+ return Math.max(0, Math.round(cappedDelay * jitterFactor));
47
+ };
15
48
  /**
16
49
  * Base implementation that enforces schema-validated input/output.
17
50
  */
@@ -56,11 +89,10 @@ class AbstractAction {
56
89
  return this.outputSchema.parse(payload);
57
90
  }
58
91
  /**
59
- * Executes the action with retry, timeout, and schema safety.
92
+ * Parses settings over the base execution settings (timeout, retries).
60
93
  *
61
- * @param payload - Raw input being provided to the action.
62
- * @returns Validated output produced by the action.
63
- * @throws Error when retries are exhausted or validation fails.
94
+ * @param payload - Raw settings of the task.
95
+ * @returns Settings typed as `RuntimeSettings<S>` after schema validation.
64
96
  */
65
97
  parseSettings(payload) {
66
98
  const settings = zod_1.z
@@ -68,27 +100,21 @@ class AbstractAction {
68
100
  .parse(payload ?? {});
69
101
  return (settings ?? {});
70
102
  }
103
+ /**
104
+ * Executes the action with retry, timeout, and schema safety.
105
+ *
106
+ * @param payload - Raw input being provided to the action.
107
+ * @returns Validated output produced by the action.
108
+ * @throws Error when retries are exhausted or validation fails.
109
+ */
71
110
  async run(payload, context, settings, bindings, signal) {
72
111
  const input = this.parseInput(payload);
73
112
  const parsedSettings = this.parseSettings(settings);
74
113
  const parsedBindings = (bindings ?? {});
75
114
  this.assertSupportedBindings(parsedBindings);
76
115
  const timeoutMs = parsedSettings.timeout_ms ?? 0;
77
- const retrySettings = parsedSettings.retries ?? {
78
- enabled: false,
79
- max_attempts: 1,
80
- backoff_ms: 0,
81
- max_delay_ms: 0,
82
- jitter: 0,
83
- multiplier: 1,
84
- };
85
- const retriesEnabled = retrySettings.enabled ?? true;
86
- const maxAttempts = retriesEnabled ? retrySettings.max_attempts : 1;
87
- let attempt = 0;
88
- let currentDelay = retrySettings.backoff_ms ?? 0;
89
- const maxDelayMs = retrySettings.max_delay_ms;
90
- const jitter = retrySettings.jitter;
91
- const multiplier = retrySettings.multiplier;
116
+ const retryPolicy = resolveRetryPolicy(parsedSettings.retries);
117
+ let delay = retryPolicy.backoffMs;
92
118
  // Suspend keys are positional within the body, so every attempt has to
93
119
  // start from where this run did: otherwise a retry asks for `index:2`
94
120
  // where the first attempt resolved `index:1`, and the step suspends on a
@@ -96,7 +122,7 @@ class AbstractAction {
96
122
  const rewindSuspendCursor = context
97
123
  ?.getWorkflowRuntime?.()
98
124
  ?.markSuspendCursor?.();
99
- while (attempt < maxAttempts) {
125
+ for (let attempt = 1; attempt <= retryPolicy.maxAttempts; attempt += 1) {
100
126
  if (signal) {
101
127
  (0, errors_1.throwIfAborted)(signal);
102
128
  }
@@ -112,28 +138,18 @@ class AbstractAction {
112
138
  return this.parseOutput(result);
113
139
  }
114
140
  catch (error) {
115
- attempt += 1;
116
141
  // A retry would read the same refused resume payload again, or replay
117
142
  // the same body into the same mismatch with what it recorded.
118
- if (attempt >= maxAttempts ||
143
+ if (attempt >= retryPolicy.maxAttempts ||
119
144
  (0, errors_1.isWorkflowResumeRejectedError)(error) ||
120
145
  (0, errors_1.isNonDeterministicWorkflowError)(error)) {
121
146
  throw error;
122
147
  }
123
- let delay = currentDelay;
124
- if (maxDelayMs > 0) {
125
- delay = Math.min(delay, maxDelayMs);
126
- }
127
- if (delay > 0) {
128
- const jitterFactor = jitter > 0 ? 1 + (Math.random() * 2 - 1) * jitter : 1;
129
- const jitteredDelay = Math.max(0, Math.round(delay * jitterFactor));
130
- if (jitteredDelay > 0) {
131
- await (0, timeout_1.sleep)(jitteredDelay, signal);
132
- }
148
+ const pause = retryPause(delay, retryPolicy);
149
+ if (pause > 0) {
150
+ await (0, timeout_1.sleep)(pause, signal);
133
151
  }
134
- const nextDelay = currentDelay * multiplier;
135
- currentDelay =
136
- maxDelayMs > 0 ? Math.min(nextDelay, maxDelayMs) : nextDelay;
152
+ delay = capDelay(delay * retryPolicy.multiplier, retryPolicy);
137
153
  }
138
154
  }
139
155
  throw new Error('Action failed after exhausting retry attempts.');
@@ -6,6 +6,7 @@
6
6
  */
7
7
  Object.defineProperty(exports, "__esModule", { value: true });
8
8
  exports.mountTaskBindings = exports.validateAndResolveBindings = void 0;
9
+ const validation_issue_1 = require("../validation-issue");
9
10
  const TASK_KIND = 'task';
10
11
  const resolveValidationOptions = (options) => {
11
12
  if (!options) {
@@ -22,19 +23,11 @@ const hasBindingsConfigured = (workflow) => {
22
23
  const hasNestedBindings = Object.values(defs).some((definition) => definition.bindings && Object.keys(definition.bindings).length > 0);
23
24
  return hasNonTaskDefs || hasNestedBindings;
24
25
  };
25
- const toBindingSettingsIssues = (zodIssues, defName) => zodIssues.map((issue) => {
26
- const path = issue.path.join('.') || '<root>';
27
- return {
28
- code: 'binding_settings',
29
- message: `defs.${defName}.settings.${path}: ${issue.message}`,
30
- path: [
31
- 'defs',
32
- defName,
33
- 'settings',
34
- ...issue.path.filter((segment) => typeof segment === 'string' || typeof segment === 'number'),
35
- ],
36
- };
37
- });
26
+ const toBindingSettingsIssues = (schemaIssues, defName) => (0, validation_issue_1.toValidationIssues)('binding_settings', schemaIssues, [
27
+ 'defs',
28
+ defName,
29
+ 'settings',
30
+ ]);
38
31
  const collectDuplicateReferences = (refs) => {
39
32
  const seen = new Set();
40
33
  const duplicates = new Set();
@@ -111,246 +104,271 @@ const missingActionIssue = (defName, actionName) => ({
111
104
  path: ['defs', defName, 'action'],
112
105
  actionName,
113
106
  });
114
- const resolveSupportedBindingKinds = (definition, defName, kinds, actions, issues) => {
107
+ /** Look an action up in the catalog; inherited object members are not actions. */
108
+ const findAction = (actions, actionName) => actions && Object.prototype.hasOwnProperty.call(actions, actionName)
109
+ ? actions[actionName]
110
+ : undefined;
111
+ /**
112
+ * Whether a def names an action the catalog does not hold. A task always runs
113
+ * its action, so an empty name is missing as well; other defs may leave it
114
+ * empty.
115
+ */
116
+ const isMissingAction = (definition, actions) => {
117
+ if (!actions || typeof definition.action !== 'string') {
118
+ return false;
119
+ }
120
+ if (definition.action === '' && definition.kind !== TASK_KIND) {
121
+ return false;
122
+ }
123
+ return !findAction(actions, definition.action);
124
+ };
125
+ const actionPolicyIssues = (defName, definition, { actionPolicy = 'optional' }) => {
126
+ const issue = (code, message) => [
127
+ {
128
+ code,
129
+ message: `defs.${defName}.action: Binding kind "${definition.kind}" ${message}`,
130
+ path: ['defs', defName, 'action'],
131
+ bindingKind: definition.kind,
132
+ },
133
+ ];
134
+ if (actionPolicy === 'required' && !definition.action) {
135
+ return issue('action_required', 'requires an action.');
136
+ }
137
+ if (actionPolicy === 'forbidden' && definition.action) {
138
+ return issue('action_forbidden', 'does not allow action declarations.');
139
+ }
140
+ return [];
141
+ };
142
+ /**
143
+ * Check the kind, action and settings of one def. Settings that match the
144
+ * kind's schema are recorded in `parsedSettings`, for mounting.
145
+ */
146
+ const validateDef = (defName, definition, kinds, actions, parsedSettings) => {
147
+ const missingAction = isMissingAction(definition, actions)
148
+ ? [missingActionIssue(defName, definition.action)]
149
+ : [];
150
+ if (definition.kind === TASK_KIND) {
151
+ return missingAction;
152
+ }
153
+ const kindDefinition = kinds[definition.kind];
154
+ if (!kindDefinition) {
155
+ return [
156
+ {
157
+ code: 'unknown_binding_kind',
158
+ message: `defs.${defName}.kind: Unknown binding kind "${definition.kind}".`,
159
+ path: ['defs', defName, 'kind'],
160
+ bindingKind: definition.kind,
161
+ },
162
+ ...missingAction,
163
+ ];
164
+ }
165
+ const issues = [
166
+ ...actionPolicyIssues(defName, definition, kindDefinition),
167
+ ...missingAction,
168
+ ];
169
+ const parsed = kindDefinition.schema.safeParse(definition.settings);
170
+ if (!parsed.success) {
171
+ return [
172
+ ...issues,
173
+ ...toBindingSettingsIssues(parsed.error.issues, defName),
174
+ ];
175
+ }
176
+ parsedSettings.set(defName, parsed.data);
177
+ // `?.` on `safeParse` too: hosts may pass serialized schemas.
178
+ const actionParsed = definition.action
179
+ ? findAction(actions, definition.action)?.settingSchema?.safeParse?.(definition.settings)
180
+ : undefined;
181
+ if (actionParsed && !actionParsed.success) {
182
+ issues.push(...toBindingSettingsIssues(actionParsed.error.issues, defName));
183
+ }
184
+ return issues;
185
+ };
186
+ /**
187
+ * List the binding kinds a def may mount, or null when they cannot be known:
188
+ * no action catalog was given, or the def's action is missing from it.
189
+ */
190
+ const resolveSupportedBindingKinds = (definition, kinds, actions) => {
115
191
  if (definition.action) {
116
- if (!actions) {
117
- return null;
118
- }
119
- const action = actions[definition.action];
120
- if (!action) {
121
- issues.push(missingActionIssue(defName, definition.action));
122
- return [];
123
- }
124
- return action.supportedBindings ?? [];
192
+ const action = findAction(actions, definition.action);
193
+ return action ? (action.supportedBindings ?? []) : null;
125
194
  }
126
195
  if (definition.kind === TASK_KIND) {
127
196
  return [];
128
197
  }
129
198
  return kinds[definition.kind]?.supportedBindings ?? [];
130
199
  };
131
- const validateAndResolveBindings = (workflow, options) => {
200
+ /**
201
+ * Check one `bindings.<kind>` entry of a def: the kind exists, the reference
202
+ * cardinality matches it, the def may mount it, and every reference names a
203
+ * def of that kind.
204
+ */
205
+ const validateBindingEntry = (defName, definition, bindingKind, bindingRefs, context) => {
206
+ const issue = (code, message) => ({
207
+ code,
208
+ message: `defs.${defName}.bindings.${bindingKind}: ${message}`,
209
+ path: ['defs', defName, 'bindings', bindingKind],
210
+ bindingKind,
211
+ });
212
+ const kindDefinition = context.kinds[bindingKind];
213
+ if (!kindDefinition) {
214
+ return [
215
+ issue('unknown_binding_kind', `Unknown binding kind "${bindingKind}".`),
216
+ ];
217
+ }
218
+ const { multiple } = kindDefinition;
219
+ if (multiple ? !Array.isArray(bindingRefs) : typeof bindingRefs !== 'string') {
220
+ const expected = multiple
221
+ ? 'an array of def references'
222
+ : 'a single def reference string';
223
+ return [
224
+ issue('binding_ref', `Expected ${expected} for binding kind "${bindingKind}".`),
225
+ ];
226
+ }
132
227
  const issues = [];
133
- const resolvedDefs = {};
134
- const defs = workflow.defs ?? {};
135
- const resolvedOptions = resolveValidationOptions(options);
136
- const kinds = resolvedOptions.bindingKinds ?? {};
137
- const actions = resolvedOptions.actions;
138
- const kindNames = Object.keys(kinds);
139
- const hasBindingUsage = hasBindingsConfigured(workflow);
140
- const parsedSettingsByDefName = new Map();
141
- if (hasBindingUsage && kindNames.length === 0) {
142
- issues.push({
143
- code: 'binding_registry_required',
144
- message: 'Workflows that declare non-task defs or nested bindings require a non-empty "bindingKinds" registry.',
145
- });
228
+ const { supportedKinds } = context;
229
+ if (supportedKinds && !supportedKinds.includes(bindingKind)) {
230
+ const supportedKindsLabel = supportedKinds.length > 0 ? supportedKinds.join(', ') : '<none>';
231
+ issues.push(issue('binding_unsupported', `"${definition.action ?? definition.kind}" does not support binding kind "${bindingKind}". Supported binding kinds: ${supportedKindsLabel}.`));
146
232
  }
147
- for (const [defName, defDefinition] of Object.entries(defs)) {
148
- if (defDefinition.kind === TASK_KIND) {
149
- if (defDefinition.action && actions && !actions[defDefinition.action]) {
150
- issues.push(missingActionIssue(defName, defDefinition.action));
151
- }
152
- continue;
153
- }
154
- const kindDefinition = kinds[defDefinition.kind];
155
- if (!kindDefinition) {
156
- issues.push({
157
- code: 'unknown_binding_kind',
158
- message: `defs.${defName}.kind: Unknown binding kind "${defDefinition.kind}".`,
159
- path: ['defs', defName, 'kind'],
160
- bindingKind: defDefinition.kind,
161
- });
162
- continue;
163
- }
164
- const actionPolicy = kindDefinition.actionPolicy ?? 'optional';
165
- if (actionPolicy === 'required' && !defDefinition.action) {
166
- issues.push({
167
- code: 'action_required',
168
- message: `defs.${defName}.action: Binding kind "${defDefinition.kind}" requires an action.`,
169
- path: ['defs', defName, 'action'],
170
- bindingKind: defDefinition.kind,
171
- });
172
- }
173
- if (actionPolicy === 'forbidden' && defDefinition.action) {
174
- issues.push({
175
- code: 'action_forbidden',
176
- message: `defs.${defName}.action: Binding kind "${defDefinition.kind}" does not allow action declarations.`,
177
- path: ['defs', defName, 'action'],
178
- bindingKind: defDefinition.kind,
179
- });
180
- }
181
- if (defDefinition.action && actions && !actions[defDefinition.action]) {
182
- issues.push(missingActionIssue(defName, defDefinition.action));
183
- }
184
- const { schema } = kindDefinition;
185
- const parsedPayload = schema.safeParse(defDefinition.settings);
186
- if (!parsedPayload.success) {
187
- issues.push(...toBindingSettingsIssues(parsedPayload.error.issues, defName));
188
- continue;
189
- }
190
- parsedSettingsByDefName.set(defName, parsedPayload.data);
191
- const actionSchema = defDefinition.action
192
- ? actions?.[defDefinition.action]?.settingSchema
193
- : undefined;
194
- const actionParsed = actionSchema?.safeParse?.(defDefinition.settings);
195
- if (actionParsed && !actionParsed.success) {
196
- issues.push(...toBindingSettingsIssues(actionParsed.error.issues, defName));
197
- }
233
+ const refProblems = describeReferenceProblems(toBindingRefs(bindingRefs), bindingKind, context.defs);
234
+ return [
235
+ ...issues,
236
+ ...refProblems.map((message) => issue('binding_ref', message)),
237
+ ];
238
+ };
239
+ /** Duplicate references, and references that do not name a def of `bindingKind`. */
240
+ const describeReferenceProblems = (refs, bindingKind, defs) => {
241
+ const problems = [];
242
+ const duplicateRefs = collectDuplicateReferences(refs);
243
+ if (duplicateRefs.length > 0) {
244
+ problems.push(`Duplicate def reference(s): ${duplicateRefs.join(', ')}`);
198
245
  }
199
- for (const [defName, defDefinition] of Object.entries(defs)) {
200
- const defBindings = defDefinition.bindings;
201
- if (!defBindings) {
202
- continue;
246
+ for (const ref of refs) {
247
+ const target = defs[ref];
248
+ if (!target) {
249
+ problems.push(`Unknown def reference "${ref}".`);
203
250
  }
204
- const supportedKinds = resolveSupportedBindingKinds(defDefinition, defName, kinds, actions, issues);
205
- const shouldValidateSupportedKinds = Array.isArray(supportedKinds);
206
- for (const [bindingKind, bindingRefs] of Object.entries(defBindings)) {
207
- const bindingPath = ['defs', defName, 'bindings', bindingKind];
208
- const kindDefinition = kinds[bindingKind];
209
- if (!kindDefinition) {
210
- issues.push({
211
- code: 'unknown_binding_kind',
212
- message: `defs.${defName}.bindings.${bindingKind}: Unknown binding kind "${bindingKind}".`,
213
- path: bindingPath,
214
- bindingKind,
215
- });
216
- continue;
217
- }
218
- const { multiple } = kindDefinition;
219
- if (multiple && !Array.isArray(bindingRefs)) {
220
- issues.push({
221
- code: 'binding_ref',
222
- message: `defs.${defName}.bindings.${bindingKind}: Expected an array of def references for binding kind "${bindingKind}".`,
223
- path: bindingPath,
224
- bindingKind,
225
- });
226
- continue;
227
- }
228
- if (!multiple && typeof bindingRefs !== 'string') {
229
- issues.push({
230
- code: 'binding_ref',
231
- message: `defs.${defName}.bindings.${bindingKind}: Expected a single def reference string for binding kind "${bindingKind}".`,
232
- path: bindingPath,
233
- bindingKind,
234
- });
235
- continue;
236
- }
237
- if (shouldValidateSupportedKinds &&
238
- supportedKinds &&
239
- !supportedKinds.includes(bindingKind)) {
240
- const supportedKindsLabel = supportedKinds.length > 0 ? supportedKinds.join(', ') : '<none>';
241
- issues.push({
242
- code: 'binding_unsupported',
243
- message: `defs.${defName}.bindings.${bindingKind}: "${defDefinition.action ?? defDefinition.kind}" does not support binding kind "${bindingKind}". Supported binding kinds: ${supportedKindsLabel}.`,
244
- path: bindingPath,
245
- bindingKind,
246
- });
247
- }
248
- const refs = toBindingRefs(bindingRefs);
249
- const duplicateRefs = collectDuplicateReferences(refs);
250
- if (duplicateRefs.length > 0) {
251
- issues.push({
252
- code: 'binding_ref',
253
- message: `defs.${defName}.bindings.${bindingKind}: Duplicate def reference(s): ${duplicateRefs.join(', ')}`,
254
- path: bindingPath,
255
- bindingKind,
256
- });
257
- }
258
- for (const ref of refs) {
259
- const definition = defs[ref];
260
- if (!definition) {
261
- issues.push({
262
- code: 'binding_ref',
263
- message: `defs.${defName}.bindings.${bindingKind}: Unknown def reference "${ref}".`,
264
- path: bindingPath,
265
- bindingKind,
266
- });
267
- continue;
268
- }
269
- if (definition.kind !== bindingKind) {
270
- issues.push({
271
- code: 'binding_ref',
272
- message: `defs.${defName}.bindings.${bindingKind}: Def "${ref}" has kind "${definition.kind}" and cannot be mounted as "${bindingKind}".`,
273
- path: bindingPath,
274
- bindingKind,
275
- });
276
- }
277
- }
251
+ else if (target.kind !== bindingKind) {
252
+ problems.push(`Def "${ref}" has kind "${target.kind}" and cannot be mounted as "${bindingKind}".`);
278
253
  }
279
254
  }
280
- issues.push(...detectBindingCycles(defs));
255
+ return problems;
256
+ };
257
+ const validateDefBindings = (defName, definition, defs, kinds, actions) => {
258
+ if (!definition.bindings) {
259
+ return [];
260
+ }
261
+ const context = {
262
+ defs,
263
+ kinds,
264
+ supportedKinds: resolveSupportedBindingKinds(definition, kinds, actions),
265
+ };
266
+ return Object.entries(definition.bindings).flatMap(([bindingKind, bindingRefs]) => validateBindingEntry(defName, definition, bindingKind, bindingRefs, context));
267
+ };
268
+ /**
269
+ * Mount every non-task def whose settings parsed, with its nested bindings.
270
+ * A def reached again while it is being mounted, through a cycle, is left
271
+ * out of the def that reached it.
272
+ */
273
+ const resolveBindingDefs = (defs, kinds, parsedSettings) => {
274
+ const resolvedDefs = {};
281
275
  const inProgress = new Set();
282
- const mountResolvedDef = (defName) => {
276
+ const mountDef = (defName) => {
283
277
  const existing = resolvedDefs[defName];
284
278
  if (existing) {
285
279
  return existing.payload;
286
280
  }
287
281
  const definition = defs[defName];
288
- if (!definition || definition.kind === TASK_KIND) {
289
- return undefined;
290
- }
291
- const parsedSettings = parsedSettingsByDefName.get(defName);
292
- if (parsedSettings === undefined) {
293
- return undefined;
294
- }
295
- if (inProgress.has(defName)) {
282
+ const settings = parsedSettings.get(defName);
283
+ if (!definition ||
284
+ definition.kind === TASK_KIND ||
285
+ settings === undefined ||
286
+ inProgress.has(defName)) {
296
287
  return undefined;
297
288
  }
298
289
  inProgress.add(defName);
299
- const nestedBindings = (0, exports.mountTaskBindings)(definition.bindings, resolvedDefs, kinds, mountResolvedDef);
290
+ const nestedBindings = (0, exports.mountTaskBindings)(definition.bindings, resolvedDefs, kinds, mountDef);
300
291
  const payload = {
301
- settings: parsedSettings,
292
+ settings,
302
293
  ...(definition.action ? { action: definition.action } : {}),
294
+ ...(definition.description
295
+ ? { description: definition.description }
296
+ : {}),
303
297
  ...(Object.keys(nestedBindings).length > 0
304
298
  ? { bindings: nestedBindings }
305
299
  : {}),
306
300
  };
307
- resolvedDefs[defName] = {
308
- kind: definition.kind,
309
- payload,
310
- };
301
+ resolvedDefs[defName] = { kind: definition.kind, payload };
311
302
  inProgress.delete(defName);
312
303
  return payload;
313
304
  };
314
305
  for (const [defName, definition] of Object.entries(defs)) {
315
- if (definition.kind === TASK_KIND) {
316
- continue;
306
+ if (definition.kind !== TASK_KIND) {
307
+ mountDef(defName);
317
308
  }
318
- mountResolvedDef(defName);
319
309
  }
320
- return { issues, resolvedDefs };
310
+ return resolvedDefs;
311
+ };
312
+ /**
313
+ * Validate the defs and bindings of a workflow, and mount every valid
314
+ * non-task def so tasks can be handed their bindings.
315
+ */
316
+ const validateAndResolveBindings = (workflow, options) => {
317
+ const defs = workflow.defs ?? {};
318
+ const { bindingKinds: kinds = {}, actions } = resolveValidationOptions(options);
319
+ const issues = [];
320
+ const parsedSettings = new Map();
321
+ if (hasBindingsConfigured(workflow) && Object.keys(kinds).length === 0) {
322
+ issues.push({
323
+ code: 'binding_registry_required',
324
+ message: 'Workflows that declare non-task defs or nested bindings require a non-empty "bindingKinds" registry.',
325
+ });
326
+ }
327
+ for (const [defName, definition] of Object.entries(defs)) {
328
+ issues.push(...validateDef(defName, definition, kinds, actions, parsedSettings));
329
+ }
330
+ for (const [defName, definition] of Object.entries(defs)) {
331
+ issues.push(...validateDefBindings(defName, definition, defs, kinds, actions));
332
+ }
333
+ issues.push(...detectBindingCycles(defs));
334
+ return {
335
+ issues,
336
+ resolvedDefs: resolveBindingDefs(defs, kinds, parsedSettings),
337
+ };
321
338
  };
322
339
  exports.validateAndResolveBindings = validateAndResolveBindings;
323
- const mountTaskBindings = (taskBindings, resolvedDefs, bindingKinds, resolveDef) => {
340
+ /** Payloads of the references that resolve, keyed by def name; none gives undefined. */
341
+ const resolveEach = (refs, resolve) => {
342
+ const payloads = {};
343
+ for (const ref of refs) {
344
+ const payload = resolve(ref);
345
+ if (payload) {
346
+ payloads[ref] = payload;
347
+ }
348
+ }
349
+ return Object.keys(payloads).length > 0 ? payloads : undefined;
350
+ };
351
+ /**
352
+ * Mount the defs a task (or def) references in `bindings`, by binding kind:
353
+ * one payload for a single-ref kind, payloads keyed by def name otherwise.
354
+ * References that resolve to nothing are left out.
355
+ */
356
+ const mountTaskBindings = (taskBindings, resolvedDefs, bindingKinds = {}, resolveDef) => {
324
357
  if (!taskBindings) {
325
358
  return {};
326
359
  }
360
+ const resolve = (ref) => resolvedDefs[ref]?.payload ?? resolveDef?.(ref);
327
361
  const mounted = {};
328
- const kinds = bindingKinds ?? {};
329
362
  for (const [bindingKind, bindingRefs] of Object.entries(taskBindings)) {
330
363
  const refs = toBindingRefs(bindingRefs);
331
- const isMultiple = kinds[bindingKind]?.multiple ?? Array.isArray(bindingRefs);
332
- if (!isMultiple) {
333
- const ref = refs[0];
334
- if (!ref) {
335
- continue;
336
- }
337
- const resolvedDefPayload = resolvedDefs[ref]?.payload ?? resolveDef?.(ref) ?? undefined;
338
- if (!resolvedDefPayload) {
339
- continue;
340
- }
341
- mounted[bindingKind] = resolvedDefPayload;
342
- continue;
343
- }
344
- const mountedKindDefs = {};
345
- for (const ref of refs) {
346
- const resolvedDefPayload = resolvedDefs[ref]?.payload ?? resolveDef?.(ref) ?? undefined;
347
- if (!resolvedDefPayload) {
348
- continue;
349
- }
350
- mountedKindDefs[ref] = resolvedDefPayload;
351
- }
352
- if (Object.keys(mountedKindDefs).length > 0) {
353
- mounted[bindingKind] = mountedKindDefs;
364
+ const isMultiple = bindingKinds[bindingKind]?.multiple ?? Array.isArray(bindingRefs);
365
+ const payload = isMultiple
366
+ ? resolveEach(refs, resolve)
367
+ : refs[0]
368
+ ? resolve(refs[0])
369
+ : undefined;
370
+ if (payload) {
371
+ mounted[bindingKind] = payload;
354
372
  }
355
373
  }
356
374
  return mounted;