@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
@@ -4,9 +4,12 @@
4
4
  * Full terms: see LICENSE.md.
5
5
  */
6
6
 
7
- import { z, type ZodIssue } from 'zod';
7
+ import { z } from 'zod';
8
8
 
9
- import { type WorkflowValidationIssue } from '../validation-issue';
9
+ import {
10
+ toValidationIssues,
11
+ type WorkflowValidationIssue,
12
+ } from '../validation-issue';
10
13
 
11
14
  const TASK_KIND = 'task';
12
15
 
@@ -37,6 +40,7 @@ export type MountedBindingPayload<
37
40
  > = {
38
41
  settings: z.infer<TBindingKind['schema']>;
39
42
  action?: string;
43
+ description?: string;
40
44
  bindings?: InferWorkflowBindings<TBindingKinds>;
41
45
  };
42
46
 
@@ -89,6 +93,8 @@ export type ValidateAndResolveBindingsOptions = {
89
93
  actions?: Record<string, BindingValidationActionMetadata>;
90
94
  };
91
95
 
96
+ type ActionCatalog = NonNullable<ValidateAndResolveBindingsOptions['actions']>;
97
+
92
98
  type BindingValidationResult = {
93
99
  issues: WorkflowValidationIssue[];
94
100
  resolvedDefs: ResolvedBindingDefs;
@@ -120,26 +126,14 @@ const hasBindingsConfigured = (workflow: BindingAwareWorkflowLike): boolean => {
120
126
  return hasNonTaskDefs || hasNestedBindings;
121
127
  };
122
128
  const toBindingSettingsIssues = (
123
- zodIssues: ZodIssue[],
129
+ schemaIssues: z.core.$ZodIssue[],
124
130
  defName: string,
125
131
  ): WorkflowValidationIssue[] =>
126
- zodIssues.map((issue) => {
127
- const path = issue.path.join('.') || '<root>';
128
-
129
- return {
130
- code: 'binding_settings',
131
- message: `defs.${defName}.settings.${path}: ${issue.message}`,
132
- path: [
133
- 'defs',
134
- defName,
135
- 'settings',
136
- ...issue.path.filter(
137
- (segment): segment is string | number =>
138
- typeof segment === 'string' || typeof segment === 'number',
139
- ),
140
- ],
141
- };
142
- });
132
+ toValidationIssues('binding_settings', schemaIssues, [
133
+ 'defs',
134
+ defName,
135
+ 'settings',
136
+ ]);
143
137
  const collectDuplicateReferences = (refs: string[]): string[] => {
144
138
  const seen = new Set<string>();
145
139
  const duplicates = new Set<string>();
@@ -239,245 +233,292 @@ const missingActionIssue = (
239
233
  path: ['defs', defName, 'action'],
240
234
  actionName,
241
235
  });
242
- const resolveSupportedBindingKinds = (
236
+ /** Look an action up in the catalog; inherited object members are not actions. */
237
+ const findAction = (
238
+ actions: ActionCatalog | undefined,
239
+ actionName: string,
240
+ ): BindingValidationActionMetadata | undefined =>
241
+ actions && Object.prototype.hasOwnProperty.call(actions, actionName)
242
+ ? actions[actionName]
243
+ : undefined;
244
+ /**
245
+ * Whether a def names an action the catalog does not hold. A task always runs
246
+ * its action, so an empty name is missing as well; other defs may leave it
247
+ * empty.
248
+ */
249
+ const isMissingAction = (
243
250
  definition: DefLike,
244
- defName: string,
245
- kinds: BindingKindSchemas,
246
- actions: Record<string, BindingValidationActionMetadata> | undefined,
247
- issues: WorkflowValidationIssue[],
248
- ): readonly string[] | null => {
249
- if (definition.action) {
250
- if (!actions) {
251
- return null;
252
- }
253
-
254
- const action = actions[definition.action];
255
- if (!action) {
256
- issues.push(missingActionIssue(defName, definition.action));
257
-
258
- return [];
259
- }
260
-
261
- return action.supportedBindings ?? [];
251
+ actions: ActionCatalog | undefined,
252
+ ): definition is DefLike & { action: string } => {
253
+ if (!actions || typeof definition.action !== 'string') {
254
+ return false;
262
255
  }
263
256
 
264
- if (definition.kind === TASK_KIND) {
265
- return [];
257
+ if (definition.action === '' && definition.kind !== TASK_KIND) {
258
+ return false;
266
259
  }
267
260
 
268
- return kinds[definition.kind]?.supportedBindings ?? [];
261
+ return !findAction(actions, definition.action);
269
262
  };
263
+ const actionPolicyIssues = (
264
+ defName: string,
265
+ definition: DefLike,
266
+ { actionPolicy = 'optional' }: BindingKindDescriptor,
267
+ ): WorkflowValidationIssue[] => {
268
+ const issue = (
269
+ code: 'action_required' | 'action_forbidden',
270
+ message: string,
271
+ ): WorkflowValidationIssue[] => [
272
+ {
273
+ code,
274
+ message: `defs.${defName}.action: Binding kind "${definition.kind}" ${message}`,
275
+ path: ['defs', defName, 'action'],
276
+ bindingKind: definition.kind,
277
+ },
278
+ ];
279
+
280
+ if (actionPolicy === 'required' && !definition.action) {
281
+ return issue('action_required', 'requires an action.');
282
+ }
270
283
 
271
- export const validateAndResolveBindings = (
272
- workflow: BindingAwareWorkflowLike,
273
- options?: BindingKindSchemas | ValidateAndResolveBindingsOptions,
274
- ): BindingValidationResult => {
275
- const issues: WorkflowValidationIssue[] = [];
276
- const resolvedDefs: ResolvedBindingDefs = {};
277
- const defs = workflow.defs ?? {};
278
- const resolvedOptions = resolveValidationOptions(options);
279
- const kinds = resolvedOptions.bindingKinds ?? {};
280
- const actions = resolvedOptions.actions;
281
- const kindNames = Object.keys(kinds);
282
- const hasBindingUsage = hasBindingsConfigured(workflow);
283
- const parsedSettingsByDefName = new Map<string, unknown>();
284
-
285
- if (hasBindingUsage && kindNames.length === 0) {
286
- issues.push({
287
- code: 'binding_registry_required',
288
- message:
289
- 'Workflows that declare non-task defs or nested bindings require a non-empty "bindingKinds" registry.',
290
- });
284
+ if (actionPolicy === 'forbidden' && definition.action) {
285
+ return issue('action_forbidden', 'does not allow action declarations.');
291
286
  }
292
287
 
293
- for (const [defName, defDefinition] of Object.entries(defs)) {
294
- if (defDefinition.kind === TASK_KIND) {
295
- if (defDefinition.action && actions && !actions[defDefinition.action]) {
296
- issues.push(missingActionIssue(defName, defDefinition.action));
297
- }
298
- continue;
299
- }
288
+ return [];
289
+ };
290
+ /**
291
+ * Check the kind, action and settings of one def. Settings that match the
292
+ * kind's schema are recorded in `parsedSettings`, for mounting.
293
+ */
294
+ const validateDef = (
295
+ defName: string,
296
+ definition: DefLike,
297
+ kinds: BindingKindSchemas,
298
+ actions: ActionCatalog | undefined,
299
+ parsedSettings: Map<string, unknown>,
300
+ ): WorkflowValidationIssue[] => {
301
+ const missingAction = isMissingAction(definition, actions)
302
+ ? [missingActionIssue(defName, definition.action)]
303
+ : [];
300
304
 
301
- const kindDefinition = kinds[defDefinition.kind];
305
+ if (definition.kind === TASK_KIND) {
306
+ return missingAction;
307
+ }
302
308
 
303
- if (!kindDefinition) {
304
- issues.push({
309
+ const kindDefinition = kinds[definition.kind];
310
+ if (!kindDefinition) {
311
+ return [
312
+ {
305
313
  code: 'unknown_binding_kind',
306
- message: `defs.${defName}.kind: Unknown binding kind "${defDefinition.kind}".`,
314
+ message: `defs.${defName}.kind: Unknown binding kind "${definition.kind}".`,
307
315
  path: ['defs', defName, 'kind'],
308
- bindingKind: defDefinition.kind,
309
- });
310
- continue;
311
- }
312
-
313
- const actionPolicy = kindDefinition.actionPolicy ?? 'optional';
314
- if (actionPolicy === 'required' && !defDefinition.action) {
315
- issues.push({
316
- code: 'action_required',
317
- message: `defs.${defName}.action: Binding kind "${defDefinition.kind}" requires an action.`,
318
- path: ['defs', defName, 'action'],
319
- bindingKind: defDefinition.kind,
320
- });
321
- }
322
- if (actionPolicy === 'forbidden' && defDefinition.action) {
323
- issues.push({
324
- code: 'action_forbidden',
325
- message: `defs.${defName}.action: Binding kind "${defDefinition.kind}" does not allow action declarations.`,
326
- path: ['defs', defName, 'action'],
327
- bindingKind: defDefinition.kind,
328
- });
329
- }
330
- if (defDefinition.action && actions && !actions[defDefinition.action]) {
331
- issues.push(missingActionIssue(defName, defDefinition.action));
332
- }
316
+ bindingKind: definition.kind,
317
+ },
318
+ ...missingAction,
319
+ ];
320
+ }
333
321
 
334
- const { schema } = kindDefinition;
335
- const parsedPayload = schema.safeParse(defDefinition.settings);
322
+ const issues = [
323
+ ...actionPolicyIssues(defName, definition, kindDefinition),
324
+ ...missingAction,
325
+ ];
326
+ const parsed = kindDefinition.schema.safeParse(definition.settings);
327
+ if (!parsed.success) {
328
+ return [
329
+ ...issues,
330
+ ...toBindingSettingsIssues(parsed.error.issues, defName),
331
+ ];
332
+ }
336
333
 
337
- if (!parsedPayload.success) {
338
- issues.push(
339
- ...toBindingSettingsIssues(parsedPayload.error.issues, defName),
340
- );
341
- continue;
342
- }
334
+ parsedSettings.set(defName, parsed.data);
343
335
 
344
- parsedSettingsByDefName.set(defName, parsedPayload.data);
336
+ // `?.` on `safeParse` too: hosts may pass serialized schemas.
337
+ const actionParsed = definition.action
338
+ ? findAction(actions, definition.action)?.settingSchema?.safeParse?.(
339
+ definition.settings,
340
+ )
341
+ : undefined;
342
+ if (actionParsed && !actionParsed.success) {
343
+ issues.push(...toBindingSettingsIssues(actionParsed.error.issues, defName));
344
+ }
345
345
 
346
- const actionSchema = defDefinition.action
347
- ? actions?.[defDefinition.action]?.settingSchema
348
- : undefined;
349
- const actionParsed = actionSchema?.safeParse?.(defDefinition.settings);
346
+ return issues;
347
+ };
348
+ /**
349
+ * List the binding kinds a def may mount, or null when they cannot be known:
350
+ * no action catalog was given, or the def's action is missing from it.
351
+ */
352
+ const resolveSupportedBindingKinds = (
353
+ definition: DefLike,
354
+ kinds: BindingKindSchemas,
355
+ actions: ActionCatalog | undefined,
356
+ ): readonly string[] | null => {
357
+ if (definition.action) {
358
+ const action = findAction(actions, definition.action);
350
359
 
351
- if (actionParsed && !actionParsed.success) {
352
- issues.push(
353
- ...toBindingSettingsIssues(actionParsed.error.issues, defName),
354
- );
355
- }
360
+ return action ? (action.supportedBindings ?? []) : null;
356
361
  }
357
362
 
358
- for (const [defName, defDefinition] of Object.entries(defs)) {
359
- const defBindings = defDefinition.bindings;
363
+ if (definition.kind === TASK_KIND) {
364
+ return [];
365
+ }
360
366
 
361
- if (!defBindings) {
362
- continue;
363
- }
367
+ return kinds[definition.kind]?.supportedBindings ?? [];
368
+ };
369
+ /**
370
+ * Check one `bindings.<kind>` entry of a def: the kind exists, the reference
371
+ * cardinality matches it, the def may mount it, and every reference names a
372
+ * def of that kind.
373
+ */
374
+ const validateBindingEntry = (
375
+ defName: string,
376
+ definition: DefLike,
377
+ bindingKind: string,
378
+ bindingRefs: string | string[],
379
+ context: {
380
+ defs: Record<string, DefLike>;
381
+ kinds: BindingKindSchemas;
382
+ supportedKinds: readonly string[] | null;
383
+ },
384
+ ): WorkflowValidationIssue[] => {
385
+ const issue = (
386
+ code: 'unknown_binding_kind' | 'binding_ref' | 'binding_unsupported',
387
+ message: string,
388
+ ): WorkflowValidationIssue => ({
389
+ code,
390
+ message: `defs.${defName}.bindings.${bindingKind}: ${message}`,
391
+ path: ['defs', defName, 'bindings', bindingKind],
392
+ bindingKind,
393
+ });
394
+ const kindDefinition = context.kinds[bindingKind];
364
395
 
365
- const supportedKinds = resolveSupportedBindingKinds(
366
- defDefinition,
367
- defName,
368
- kinds,
369
- actions,
370
- issues,
371
- );
372
- const shouldValidateSupportedKinds = Array.isArray(supportedKinds);
396
+ if (!kindDefinition) {
397
+ return [
398
+ issue('unknown_binding_kind', `Unknown binding kind "${bindingKind}".`),
399
+ ];
400
+ }
373
401
 
374
- for (const [bindingKind, bindingRefs] of Object.entries(defBindings)) {
375
- const bindingPath = ['defs', defName, 'bindings', bindingKind];
376
- const kindDefinition = kinds[bindingKind];
402
+ const { multiple } = kindDefinition;
403
+ if (
404
+ multiple ? !Array.isArray(bindingRefs) : typeof bindingRefs !== 'string'
405
+ ) {
406
+ const expected = multiple
407
+ ? 'an array of def references'
408
+ : 'a single def reference string';
409
+
410
+ return [
411
+ issue(
412
+ 'binding_ref',
413
+ `Expected ${expected} for binding kind "${bindingKind}".`,
414
+ ),
415
+ ];
416
+ }
377
417
 
378
- if (!kindDefinition) {
379
- issues.push({
380
- code: 'unknown_binding_kind',
381
- message: `defs.${defName}.bindings.${bindingKind}: Unknown binding kind "${bindingKind}".`,
382
- path: bindingPath,
383
- bindingKind,
384
- });
385
- continue;
386
- }
418
+ const issues: WorkflowValidationIssue[] = [];
419
+ const { supportedKinds } = context;
420
+ if (supportedKinds && !supportedKinds.includes(bindingKind)) {
421
+ const supportedKindsLabel =
422
+ supportedKinds.length > 0 ? supportedKinds.join(', ') : '<none>';
423
+ issues.push(
424
+ issue(
425
+ 'binding_unsupported',
426
+ `"${definition.action ?? definition.kind}" does not support binding kind "${bindingKind}". Supported binding kinds: ${supportedKindsLabel}.`,
427
+ ),
428
+ );
429
+ }
387
430
 
388
- const { multiple } = kindDefinition;
389
- if (multiple && !Array.isArray(bindingRefs)) {
390
- issues.push({
391
- code: 'binding_ref',
392
- message: `defs.${defName}.bindings.${bindingKind}: Expected an array of def references for binding kind "${bindingKind}".`,
393
- path: bindingPath,
394
- bindingKind,
395
- });
396
- continue;
397
- }
398
- if (!multiple && typeof bindingRefs !== 'string') {
399
- issues.push({
400
- code: 'binding_ref',
401
- message: `defs.${defName}.bindings.${bindingKind}: Expected a single def reference string for binding kind "${bindingKind}".`,
402
- path: bindingPath,
403
- bindingKind,
404
- });
405
- continue;
406
- }
431
+ const refProblems = describeReferenceProblems(
432
+ toBindingRefs(bindingRefs),
433
+ bindingKind,
434
+ context.defs,
435
+ );
407
436
 
408
- if (
409
- shouldValidateSupportedKinds &&
410
- supportedKinds &&
411
- !supportedKinds.includes(bindingKind)
412
- ) {
413
- const supportedKindsLabel =
414
- supportedKinds.length > 0 ? supportedKinds.join(', ') : '<none>';
415
- issues.push({
416
- code: 'binding_unsupported',
417
- message: `defs.${defName}.bindings.${bindingKind}: "${defDefinition.action ?? defDefinition.kind}" does not support binding kind "${bindingKind}". Supported binding kinds: ${supportedKindsLabel}.`,
418
- path: bindingPath,
419
- bindingKind,
420
- });
421
- }
437
+ return [
438
+ ...issues,
439
+ ...refProblems.map((message) => issue('binding_ref', message)),
440
+ ];
441
+ };
442
+ /** Duplicate references, and references that do not name a def of `bindingKind`. */
443
+ const describeReferenceProblems = (
444
+ refs: string[],
445
+ bindingKind: string,
446
+ defs: Record<string, DefLike>,
447
+ ): string[] => {
448
+ const problems: string[] = [];
449
+ const duplicateRefs = collectDuplicateReferences(refs);
450
+ if (duplicateRefs.length > 0) {
451
+ problems.push(`Duplicate def reference(s): ${duplicateRefs.join(', ')}`);
452
+ }
422
453
 
423
- const refs = toBindingRefs(bindingRefs);
424
- const duplicateRefs = collectDuplicateReferences(refs);
425
- if (duplicateRefs.length > 0) {
426
- issues.push({
427
- code: 'binding_ref',
428
- message: `defs.${defName}.bindings.${bindingKind}: Duplicate def reference(s): ${duplicateRefs.join(', ')}`,
429
- path: bindingPath,
430
- bindingKind,
431
- });
432
- }
454
+ for (const ref of refs) {
455
+ const target = defs[ref];
433
456
 
434
- for (const ref of refs) {
435
- const definition = defs[ref];
436
-
437
- if (!definition) {
438
- issues.push({
439
- code: 'binding_ref',
440
- message: `defs.${defName}.bindings.${bindingKind}: Unknown def reference "${ref}".`,
441
- path: bindingPath,
442
- bindingKind,
443
- });
444
- continue;
445
- }
446
-
447
- if (definition.kind !== bindingKind) {
448
- issues.push({
449
- code: 'binding_ref',
450
- message: `defs.${defName}.bindings.${bindingKind}: Def "${ref}" has kind "${definition.kind}" and cannot be mounted as "${bindingKind}".`,
451
- path: bindingPath,
452
- bindingKind,
453
- });
454
- }
455
- }
457
+ if (!target) {
458
+ problems.push(`Unknown def reference "${ref}".`);
459
+ } else if (target.kind !== bindingKind) {
460
+ problems.push(
461
+ `Def "${ref}" has kind "${target.kind}" and cannot be mounted as "${bindingKind}".`,
462
+ );
456
463
  }
457
464
  }
458
465
 
459
- issues.push(...detectBindingCycles(defs));
466
+ return problems;
467
+ };
468
+ const validateDefBindings = (
469
+ defName: string,
470
+ definition: DefLike,
471
+ defs: Record<string, DefLike>,
472
+ kinds: BindingKindSchemas,
473
+ actions: ActionCatalog | undefined,
474
+ ): WorkflowValidationIssue[] => {
475
+ if (!definition.bindings) {
476
+ return [];
477
+ }
478
+
479
+ const context = {
480
+ defs,
481
+ kinds,
482
+ supportedKinds: resolveSupportedBindingKinds(definition, kinds, actions),
483
+ };
460
484
 
485
+ return Object.entries(definition.bindings).flatMap(
486
+ ([bindingKind, bindingRefs]) =>
487
+ validateBindingEntry(
488
+ defName,
489
+ definition,
490
+ bindingKind,
491
+ bindingRefs,
492
+ context,
493
+ ),
494
+ );
495
+ };
496
+ /**
497
+ * Mount every non-task def whose settings parsed, with its nested bindings.
498
+ * A def reached again while it is being mounted, through a cycle, is left
499
+ * out of the def that reached it.
500
+ */
501
+ const resolveBindingDefs = (
502
+ defs: Record<string, DefLike>,
503
+ kinds: BindingKindSchemas,
504
+ parsedSettings: Map<string, unknown>,
505
+ ): ResolvedBindingDefs => {
506
+ const resolvedDefs: ResolvedBindingDefs = {};
461
507
  const inProgress = new Set<string>();
462
- const mountResolvedDef = (
463
- defName: string,
464
- ): MountedBindingPayload | undefined => {
508
+ const mountDef = (defName: string): MountedBindingPayload | undefined => {
465
509
  const existing = resolvedDefs[defName];
466
510
  if (existing) {
467
511
  return existing.payload;
468
512
  }
469
513
 
470
514
  const definition = defs[defName];
471
- if (!definition || definition.kind === TASK_KIND) {
472
- return undefined;
473
- }
474
-
475
- const parsedSettings = parsedSettingsByDefName.get(defName);
476
- if (parsedSettings === undefined) {
477
- return undefined;
478
- }
479
-
480
- if (inProgress.has(defName)) {
515
+ const settings = parsedSettings.get(defName);
516
+ if (
517
+ !definition ||
518
+ definition.kind === TASK_KIND ||
519
+ settings === undefined ||
520
+ inProgress.has(defName)
521
+ ) {
481
522
  return undefined;
482
523
  }
483
524
 
@@ -486,87 +527,123 @@ export const validateAndResolveBindings = (
486
527
  definition.bindings,
487
528
  resolvedDefs,
488
529
  kinds,
489
- mountResolvedDef,
530
+ mountDef,
490
531
  );
491
532
  const payload: MountedBindingPayload = {
492
- settings: parsedSettings,
533
+ settings,
493
534
  ...(definition.action ? { action: definition.action } : {}),
535
+ ...(definition.description
536
+ ? { description: definition.description }
537
+ : {}),
494
538
  ...(Object.keys(nestedBindings).length > 0
495
539
  ? { bindings: nestedBindings }
496
540
  : {}),
497
541
  };
498
542
 
499
- resolvedDefs[defName] = {
500
- kind: definition.kind,
501
- payload,
502
- };
543
+ resolvedDefs[defName] = { kind: definition.kind, payload };
503
544
  inProgress.delete(defName);
504
545
 
505
546
  return payload;
506
547
  };
507
548
 
508
549
  for (const [defName, definition] of Object.entries(defs)) {
509
- if (definition.kind === TASK_KIND) {
510
- continue;
550
+ if (definition.kind !== TASK_KIND) {
551
+ mountDef(defName);
511
552
  }
553
+ }
554
+
555
+ return resolvedDefs;
556
+ };
557
+
558
+ /**
559
+ * Validate the defs and bindings of a workflow, and mount every valid
560
+ * non-task def so tasks can be handed their bindings.
561
+ */
562
+ export const validateAndResolveBindings = (
563
+ workflow: BindingAwareWorkflowLike,
564
+ options?: BindingKindSchemas | ValidateAndResolveBindingsOptions,
565
+ ): BindingValidationResult => {
566
+ const defs = workflow.defs ?? {};
567
+ const { bindingKinds: kinds = {}, actions } =
568
+ resolveValidationOptions(options);
569
+ const issues: WorkflowValidationIssue[] = [];
570
+ const parsedSettings = new Map<string, unknown>();
571
+
572
+ if (hasBindingsConfigured(workflow) && Object.keys(kinds).length === 0) {
573
+ issues.push({
574
+ code: 'binding_registry_required',
575
+ message:
576
+ 'Workflows that declare non-task defs or nested bindings require a non-empty "bindingKinds" registry.',
577
+ });
578
+ }
579
+
580
+ for (const [defName, definition] of Object.entries(defs)) {
581
+ issues.push(
582
+ ...validateDef(defName, definition, kinds, actions, parsedSettings),
583
+ );
584
+ }
585
+
586
+ for (const [defName, definition] of Object.entries(defs)) {
587
+ issues.push(
588
+ ...validateDefBindings(defName, definition, defs, kinds, actions),
589
+ );
590
+ }
591
+
592
+ issues.push(...detectBindingCycles(defs));
593
+
594
+ return {
595
+ issues,
596
+ resolvedDefs: resolveBindingDefs(defs, kinds, parsedSettings),
597
+ };
598
+ };
512
599
 
513
- mountResolvedDef(defName);
600
+ /** Payloads of the references that resolve, keyed by def name; none gives undefined. */
601
+ const resolveEach = (
602
+ refs: string[],
603
+ resolve: (ref: string) => MountedBindingPayload | undefined,
604
+ ): Record<string, MountedBindingPayload> | undefined => {
605
+ const payloads: Record<string, MountedBindingPayload> = {};
606
+ for (const ref of refs) {
607
+ const payload = resolve(ref);
608
+ if (payload) {
609
+ payloads[ref] = payload;
610
+ }
514
611
  }
515
612
 
516
- return { issues, resolvedDefs };
613
+ return Object.keys(payloads).length > 0 ? payloads : undefined;
517
614
  };
518
615
 
616
+ /**
617
+ * Mount the defs a task (or def) references in `bindings`, by binding kind:
618
+ * one payload for a single-ref kind, payloads keyed by def name otherwise.
619
+ * References that resolve to nothing are left out.
620
+ */
519
621
  export const mountTaskBindings = (
520
622
  taskBindings: TaskBindingReferences | undefined,
521
623
  resolvedDefs: ResolvedBindingDefs,
522
- bindingKinds?: BindingKindSchemas,
624
+ bindingKinds: BindingKindSchemas = {},
523
625
  resolveDef?: (defName: string) => MountedBindingPayload | undefined,
524
626
  ): CompiledTaskBindings => {
525
627
  if (!taskBindings) {
526
628
  return {};
527
629
  }
528
630
 
631
+ const resolve = (ref: string) =>
632
+ resolvedDefs[ref]?.payload ?? resolveDef?.(ref);
529
633
  const mounted: CompiledTaskBindings = {};
530
- const kinds = bindingKinds ?? {};
531
634
 
532
635
  for (const [bindingKind, bindingRefs] of Object.entries(taskBindings)) {
533
636
  const refs = toBindingRefs(bindingRefs);
534
637
  const isMultiple =
535
- kinds[bindingKind]?.multiple ?? Array.isArray(bindingRefs);
536
-
537
- if (!isMultiple) {
538
- const ref = refs[0];
539
-
540
- if (!ref) {
541
- continue;
542
- }
543
-
544
- const resolvedDefPayload =
545
- resolvedDefs[ref]?.payload ?? resolveDef?.(ref) ?? undefined;
546
-
547
- if (!resolvedDefPayload) {
548
- continue;
549
- }
550
-
551
- mounted[bindingKind] = resolvedDefPayload;
552
- continue;
553
- }
554
-
555
- const mountedKindDefs: Record<string, MountedBindingPayload> = {};
556
-
557
- for (const ref of refs) {
558
- const resolvedDefPayload =
559
- resolvedDefs[ref]?.payload ?? resolveDef?.(ref) ?? undefined;
560
-
561
- if (!resolvedDefPayload) {
562
- continue;
563
- }
564
-
565
- mountedKindDefs[ref] = resolvedDefPayload;
566
- }
567
-
568
- if (Object.keys(mountedKindDefs).length > 0) {
569
- mounted[bindingKind] = mountedKindDefs;
638
+ bindingKinds[bindingKind]?.multiple ?? Array.isArray(bindingRefs);
639
+ const payload = isMultiple
640
+ ? resolveEach(refs, resolve)
641
+ : refs[0]
642
+ ? resolve(refs[0])
643
+ : undefined;
644
+
645
+ if (payload) {
646
+ mounted[bindingKind] = payload;
570
647
  }
571
648
  }
572
649