@hexabot-ai/agentic 3.5.0-beta.0 → 3.6.0-beta.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +12 -3
- package/dist/cjs/action/abstract-action.js +51 -35
- package/dist/cjs/bindings/base-binding.js +229 -211
- package/dist/cjs/checkpoint.js +1 -1
- package/dist/cjs/context.js +2 -3
- package/dist/cjs/dsl.types.js +44 -90
- package/dist/cjs/errors.js +13 -1
- package/dist/cjs/index.js +3 -1
- package/dist/cjs/resume-payload.js +11 -1
- package/dist/cjs/runner-runtime-control.js +39 -27
- package/dist/cjs/step-executors/conditional-executor.js +2 -7
- package/dist/cjs/step-executors/loop-executor.js +14 -28
- package/dist/cjs/step-executors/parallel-executor.js +14 -25
- package/dist/cjs/step-executors/scope.js +25 -0
- package/dist/cjs/step-executors/skip-helpers.js +26 -34
- package/dist/cjs/step-executors/task-executor.js +58 -69
- package/dist/cjs/utils/flow-steps.js +41 -0
- package/dist/cjs/utils/naming.js +10 -10
- package/dist/cjs/utils/object-path.js +51 -0
- package/dist/cjs/utils/timeout.js +16 -39
- package/dist/cjs/validation-issue.js +14 -1
- package/dist/cjs/workflow-compiler.js +52 -96
- package/dist/cjs/workflow-fingerprint.js +22 -11
- package/dist/cjs/workflow-runner.js +19 -25
- package/dist/cjs/workflow-values.js +9 -7
- package/dist/cjs/workflow.js +44 -103
- package/dist/esm/action/abstract-action.js +51 -35
- package/dist/esm/bindings/base-binding.js +229 -211
- package/dist/esm/checkpoint.js +2 -2
- package/dist/esm/context.js +2 -3
- package/dist/esm/dsl.types.js +42 -88
- package/dist/esm/errors.js +11 -0
- package/dist/esm/index.js +2 -2
- package/dist/esm/resume-payload.js +10 -1
- package/dist/esm/runner-runtime-control.js +39 -27
- package/dist/esm/step-executors/conditional-executor.js +2 -7
- package/dist/esm/step-executors/loop-executor.js +14 -28
- package/dist/esm/step-executors/parallel-executor.js +14 -25
- package/dist/esm/step-executors/scope.js +21 -0
- package/dist/esm/step-executors/skip-helpers.js +27 -35
- package/dist/esm/step-executors/task-executor.js +58 -69
- package/dist/esm/utils/flow-steps.js +37 -0
- package/dist/esm/utils/naming.js +9 -9
- package/dist/esm/utils/object-path.js +46 -0
- package/dist/esm/utils/timeout.js +16 -39
- package/dist/esm/validation-issue.js +11 -0
- package/dist/esm/workflow-compiler.js +50 -95
- package/dist/esm/workflow-fingerprint.js +22 -11
- package/dist/esm/workflow-runner.js +21 -27
- package/dist/esm/workflow-values.js +7 -6
- package/dist/esm/workflow.js +43 -103
- package/dist/types/action/abstract-action.d.ts +7 -1
- package/dist/types/action/abstract-action.d.ts.map +1 -1
- package/dist/types/bindings/base-binding.d.ts +10 -0
- package/dist/types/bindings/base-binding.d.ts.map +1 -1
- package/dist/types/context.d.ts +2 -3
- package/dist/types/context.d.ts.map +1 -1
- package/dist/types/dsl.types.d.ts +7 -12
- package/dist/types/dsl.types.d.ts.map +1 -1
- package/dist/types/errors.d.ts +9 -0
- package/dist/types/errors.d.ts.map +1 -1
- package/dist/types/index.d.ts +2 -2
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/resume-payload.d.ts +7 -0
- package/dist/types/resume-payload.d.ts.map +1 -1
- package/dist/types/runner-runtime-control.d.ts.map +1 -1
- package/dist/types/step-executors/conditional-executor.d.ts.map +1 -1
- package/dist/types/step-executors/loop-executor.d.ts +2 -4
- package/dist/types/step-executors/loop-executor.d.ts.map +1 -1
- package/dist/types/step-executors/parallel-executor.d.ts.map +1 -1
- package/dist/types/step-executors/scope.d.ts +12 -0
- package/dist/types/step-executors/scope.d.ts.map +1 -0
- package/dist/types/step-executors/skip-helpers.d.ts +2 -8
- package/dist/types/step-executors/skip-helpers.d.ts.map +1 -1
- package/dist/types/step-executors/task-executor.d.ts.map +1 -1
- package/dist/types/utils/flow-steps.d.ts +16 -0
- package/dist/types/utils/flow-steps.d.ts.map +1 -0
- package/dist/types/utils/naming.d.ts +7 -7
- package/dist/types/utils/naming.d.ts.map +1 -1
- package/dist/types/utils/object-path.d.ts +11 -0
- package/dist/types/utils/object-path.d.ts.map +1 -0
- package/dist/types/utils/timeout.d.ts.map +1 -1
- package/dist/types/validation-issue.d.ts +13 -0
- package/dist/types/validation-issue.d.ts.map +1 -1
- package/dist/types/workflow-compiler.d.ts +15 -1
- package/dist/types/workflow-compiler.d.ts.map +1 -1
- package/dist/types/workflow-fingerprint.d.ts.map +1 -1
- package/dist/types/workflow-runner.d.ts +2 -0
- package/dist/types/workflow-runner.d.ts.map +1 -1
- package/dist/types/workflow-values.d.ts +2 -0
- package/dist/types/workflow-values.d.ts.map +1 -1
- package/dist/types/workflow.d.ts +2 -1
- package/dist/types/workflow.d.ts.map +1 -1
- package/examples/defs-bindings-agent/actions/ai-agent.ts +5 -3
- package/examples/defs-bindings-agent/actions/{caculate-score.ts → calculate-score.ts} +8 -8
- package/examples/defs-bindings-agent/actions/index.ts +2 -2
- package/examples/defs-bindings-agent/workflow.yml +2 -2
- package/examples/full/workflow.yml +20 -15
- package/examples/suspend-resume/workflow.yml +6 -3
- package/package.json +8 -5
- package/src/__tests__/checkpoint.test.ts +6 -1
- package/src/__tests__/resume-payload.test.ts +29 -0
- package/src/__tests__/test-helpers.ts +1 -1
- package/src/__tests__/validation.test.ts +330 -0
- package/src/__tests__/workflow-compiler.test.ts +278 -3
- package/src/__tests__/workflow-definition-path.test.ts +2 -0
- package/src/__tests__/workflow-fingerprint.test.ts +65 -0
- package/src/__tests__/workflow-runner.test.ts +280 -5
- package/src/__tests__/workflow-values.test.ts +13 -0
- package/src/__tests__/workflow.test.ts +4 -2
- package/src/action/__tests__/abstract-action-timing.test.ts +92 -0
- package/src/action/abstract-action.ts +67 -40
- package/src/bindings/base-binding.test.ts +470 -0
- package/src/bindings/base-binding.ts +344 -267
- package/src/checkpoint.ts +2 -4
- package/src/context.ts +2 -3
- package/src/dsl.types.ts +75 -154
- package/src/errors.ts +15 -0
- package/src/index.ts +2 -0
- package/src/resume-payload.ts +13 -3
- package/src/runner-runtime-control.ts +52 -29
- package/src/step-executors/conditional-executor.ts +3 -7
- package/src/step-executors/loop-executor.test.ts +55 -0
- package/src/step-executors/loop-executor.ts +16 -50
- package/src/step-executors/parallel-executor.ts +14 -37
- package/src/step-executors/scope.ts +30 -0
- package/src/step-executors/skip-helpers.test.ts +133 -0
- package/src/step-executors/skip-helpers.ts +43 -76
- package/src/step-executors/task-executor.test.ts +130 -1
- package/src/step-executors/task-executor.ts +109 -79
- package/src/utils/flow-steps.test.ts +121 -0
- package/src/utils/flow-steps.ts +62 -0
- package/src/utils/naming.test.ts +50 -0
- package/src/utils/naming.ts +11 -11
- package/src/utils/object-path.test.ts +70 -0
- package/src/utils/object-path.ts +67 -0
- package/src/utils/timeout.test.ts +152 -0
- package/src/utils/timeout.ts +26 -44
- package/src/validation-issue.test.ts +70 -0
- package/src/validation-issue.ts +27 -0
- package/src/workflow-compiler.ts +118 -180
- package/src/workflow-fingerprint.ts +23 -12
- package/src/workflow-runner.ts +28 -27
- package/src/workflow-values.ts +9 -7
- 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
|
|
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
|
-
|
|
172
|
-
|
|
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
|
-
*
|
|
92
|
+
* Parses settings over the base execution settings (timeout, retries).
|
|
60
93
|
*
|
|
61
|
-
* @param payload - Raw
|
|
62
|
-
* @returns
|
|
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
|
|
78
|
-
|
|
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
|
-
|
|
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
|
-
|
|
124
|
-
if (
|
|
125
|
-
|
|
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
|
-
|
|
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 = (
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
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
|
-
|
|
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
|
-
|
|
117
|
-
|
|
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
|
-
|
|
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
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
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
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
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
|
|
200
|
-
const
|
|
201
|
-
if (!
|
|
202
|
-
|
|
246
|
+
for (const ref of refs) {
|
|
247
|
+
const target = defs[ref];
|
|
248
|
+
if (!target) {
|
|
249
|
+
problems.push(`Unknown def reference "${ref}".`);
|
|
203
250
|
}
|
|
204
|
-
|
|
205
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
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,
|
|
290
|
+
const nestedBindings = (0, exports.mountTaskBindings)(definition.bindings, resolvedDefs, kinds, mountDef);
|
|
300
291
|
const payload = {
|
|
301
|
-
settings
|
|
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
|
|
316
|
-
|
|
306
|
+
if (definition.kind !== TASK_KIND) {
|
|
307
|
+
mountDef(defName);
|
|
317
308
|
}
|
|
318
|
-
mountResolvedDef(defName);
|
|
319
309
|
}
|
|
320
|
-
return
|
|
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
|
-
|
|
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 =
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
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;
|