@hexabot-ai/agentic 3.4.0 → 3.5.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 +67 -15
- package/dist/cjs/action/abstract-action.js +13 -1
- package/dist/cjs/checkpoint.js +301 -0
- package/dist/cjs/context.js +11 -27
- package/dist/cjs/dsl.types.js +3 -0
- package/dist/cjs/errors.js +116 -9
- package/dist/cjs/index.js +15 -6
- package/dist/cjs/resume-payload.js +257 -0
- package/dist/cjs/runner-runtime-control.js +181 -306
- package/dist/cjs/step-executors/conditional-executor.js +27 -29
- package/dist/cjs/step-executors/loop-executor.js +53 -62
- package/dist/cjs/step-executors/parallel-executor.js +169 -102
- package/dist/cjs/step-executors/task-executor.js +180 -96
- package/dist/cjs/utils/clone.js +73 -0
- package/dist/cjs/workflow-fingerprint.js +138 -0
- package/dist/cjs/workflow-runner.js +220 -155
- package/dist/cjs/workflow.js +24 -12
- package/dist/esm/action/abstract-action.js +14 -2
- package/dist/esm/checkpoint.js +293 -0
- package/dist/esm/context.js +11 -27
- package/dist/esm/dsl.types.js +3 -0
- package/dist/esm/errors.js +105 -6
- package/dist/esm/index.js +3 -3
- package/dist/esm/resume-payload.js +250 -0
- package/dist/esm/runner-runtime-control.js +179 -303
- package/dist/esm/step-executors/conditional-executor.js +27 -29
- package/dist/esm/step-executors/loop-executor.js +53 -62
- package/dist/esm/step-executors/parallel-executor.js +165 -98
- package/dist/esm/step-executors/task-executor.js +181 -97
- package/dist/esm/utils/clone.js +67 -0
- package/dist/esm/workflow-fingerprint.js +134 -0
- package/dist/esm/workflow-runner.js +220 -155
- package/dist/esm/workflow.js +24 -12
- package/dist/types/action/abstract-action.d.ts.map +1 -1
- package/dist/types/action/action.types.d.ts +0 -14
- package/dist/types/action/action.types.d.ts.map +1 -1
- package/dist/types/checkpoint.d.ts +188 -0
- package/dist/types/checkpoint.d.ts.map +1 -0
- package/dist/types/context.d.ts +45 -11
- package/dist/types/context.d.ts.map +1 -1
- package/dist/types/dsl.types.d.ts.map +1 -1
- package/dist/types/errors.d.ts +77 -3
- package/dist/types/errors.d.ts.map +1 -1
- package/dist/types/index.d.ts +6 -7
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/resume-payload.d.ts +69 -0
- package/dist/types/resume-payload.d.ts.map +1 -0
- package/dist/types/runner-runtime-control.d.ts +63 -51
- package/dist/types/runner-runtime-control.d.ts.map +1 -1
- package/dist/types/step-executors/conditional-executor.d.ts +6 -3
- package/dist/types/step-executors/conditional-executor.d.ts.map +1 -1
- package/dist/types/step-executors/loop-executor.d.ts +6 -4
- package/dist/types/step-executors/loop-executor.d.ts.map +1 -1
- package/dist/types/step-executors/parallel-executor.d.ts +11 -3
- package/dist/types/step-executors/parallel-executor.d.ts.map +1 -1
- package/dist/types/step-executors/task-executor.d.ts +11 -4
- package/dist/types/step-executors/task-executor.d.ts.map +1 -1
- package/dist/types/step-executors/types.d.ts +21 -13
- package/dist/types/step-executors/types.d.ts.map +1 -1
- package/dist/types/utils/clone.d.ts +33 -0
- package/dist/types/utils/clone.d.ts.map +1 -0
- package/dist/types/workflow-event-emitter.d.ts +29 -5
- package/dist/types/workflow-event-emitter.d.ts.map +1 -1
- package/dist/types/workflow-fingerprint.d.ts +14 -0
- package/dist/types/workflow-fingerprint.d.ts.map +1 -0
- package/dist/types/workflow-runner.d.ts +83 -41
- package/dist/types/workflow-runner.d.ts.map +1 -1
- package/dist/types/workflow-types.d.ts +25 -54
- package/dist/types/workflow-types.d.ts.map +1 -1
- package/dist/types/workflow.d.ts +24 -9
- package/dist/types/workflow.d.ts.map +1 -1
- package/examples/defs-bindings-agent/bindings.ts +1 -1
- package/examples/defs-bindings-agent/workflow.ts +3 -2
- package/examples/full/actions/await-user-input.ts +3 -2
- package/examples/full/actions/call-llm.ts +18 -18
- package/examples/full/actions/create-ticket.ts +1 -2
- package/examples/full/actions/decision-router.ts +6 -2
- package/examples/full/actions/get-calendar-events.ts +1 -2
- package/examples/full/actions/get-user-profile.ts +1 -2
- package/examples/full/actions/query-memory.ts +1 -2
- package/examples/full/actions/search-web.ts +1 -2
- package/examples/full/actions/send-email.ts +3 -2
- package/examples/full/workflow.ts +3 -2
- package/examples/loop/actions/await-reply.ts +2 -7
- package/examples/loop/workflow.ts +4 -2
- package/examples/suspend-resume/actions/wait-for-user.ts +11 -9
- package/examples/suspend-resume/workflow.ts +51 -11
- package/package.json +3 -3
- package/src/__tests__/checkpoint.test.ts +2568 -0
- package/src/__tests__/resume-payload.test.ts +245 -0
- package/src/__tests__/runner-runtime-control.test.ts +265 -0
- package/src/__tests__/workflow-fingerprint.test.ts +165 -0
- package/src/__tests__/workflow-runner.test.ts +167 -144
- package/src/__tests__/workflow.test.ts +97 -6
- package/src/action/abstract-action.ts +21 -2
- package/src/action/action.types.ts +0 -12
- package/src/checkpoint.ts +561 -0
- package/src/context.ts +51 -41
- package/src/dsl.types.ts +3 -0
- package/src/errors.ts +161 -8
- package/src/index.ts +33 -14
- package/src/resume-payload.ts +326 -0
- package/src/runner-runtime-control.ts +222 -456
- package/src/step-executors/conditional-executor.test.ts +77 -46
- package/src/step-executors/conditional-executor.ts +47 -40
- package/src/step-executors/loop-executor.test.ts +106 -92
- package/src/step-executors/loop-executor.ts +84 -101
- package/src/step-executors/parallel-executor.test.ts +300 -89
- package/src/step-executors/parallel-executor.ts +243 -125
- package/src/step-executors/task-executor.test.ts +321 -51
- package/src/step-executors/task-executor.ts +232 -145
- package/src/step-executors/types.ts +23 -22
- package/src/utils/clone.ts +75 -0
- package/src/workflow-event-emitter.ts +32 -6
- package/src/workflow-fingerprint.ts +159 -0
- package/src/workflow-runner.ts +325 -209
- package/src/workflow-types.ts +25 -56
- package/src/workflow.ts +41 -34
- package/dist/cjs/step-executors/suspension-continuation.js +0 -27
- package/dist/cjs/suspension-rebuilder.js +0 -265
- package/dist/cjs/utils/deferred.js +0 -17
- package/dist/esm/step-executors/suspension-continuation.js +0 -24
- package/dist/esm/suspension-rebuilder.js +0 -260
- package/dist/esm/utils/deferred.js +0 -14
- package/dist/types/step-executors/suspension-continuation.d.ts +0 -10
- package/dist/types/step-executors/suspension-continuation.d.ts.map +0 -1
- package/dist/types/suspension-rebuilder.d.ts +0 -67
- package/dist/types/suspension-rebuilder.d.ts.map +0 -1
- package/dist/types/utils/deferred.d.ts +0 -7
- package/dist/types/utils/deferred.d.ts.map +0 -1
- package/src/__tests__/suspension-rebuilder.test.ts +0 -404
- package/src/step-executors/suspension-continuation.ts +0 -31
- package/src/suspension-rebuilder.ts +0 -446
- package/src/utils/deferred.ts +0 -23
package/dist/cjs/errors.js
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
* Full terms: see LICENSE.md.
|
|
6
6
|
*/
|
|
7
7
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
8
|
-
exports.throwIfAborted = exports.getAbortReason = exports.
|
|
8
|
+
exports.createLinkedAbortController = exports.throwIfAborted = exports.getAbortReason = exports.isNonDeterministicWorkflowError = exports.isWorkflowResumeRejectedError = exports.NonDeterministicWorkflowError = exports.WorkflowResumeRejectedError = exports.WorkflowWaitNotFoundError = exports.WorkflowWaitAmbiguousError = exports.WorkflowDefinitionDriftError = exports.WorkflowCheckpointInvalidError = exports.WorkflowResumeError = exports.WorkflowCancellationError = void 0;
|
|
9
9
|
class WorkflowCancellationError extends Error {
|
|
10
10
|
constructor(message = 'Workflow execution was cancelled.') {
|
|
11
11
|
super(message);
|
|
@@ -13,16 +13,102 @@ class WorkflowCancellationError extends Error {
|
|
|
13
13
|
}
|
|
14
14
|
}
|
|
15
15
|
exports.WorkflowCancellationError = WorkflowCancellationError;
|
|
16
|
-
class
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
16
|
+
/** Base class for every reason a suspended run cannot be resumed. */
|
|
17
|
+
class WorkflowResumeError extends Error {
|
|
18
|
+
}
|
|
19
|
+
exports.WorkflowResumeError = WorkflowResumeError;
|
|
20
|
+
/**
|
|
21
|
+
* The checkpoint cannot be used: nothing was persisted, its shape is wrong,
|
|
22
|
+
* its format version is unsupported, or its frames do not line up with the
|
|
23
|
+
* compiled flow they claim to describe.
|
|
24
|
+
*/
|
|
25
|
+
class WorkflowCheckpointInvalidError extends WorkflowResumeError {
|
|
26
|
+
constructor(code, message, options) {
|
|
27
|
+
super(message);
|
|
28
|
+
this.name = 'WorkflowCheckpointInvalidError';
|
|
29
|
+
this.code = code;
|
|
30
|
+
this.path = options?.path;
|
|
31
|
+
this.issues = options?.issues;
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
exports.WorkflowCheckpointInvalidError = WorkflowCheckpointInvalidError;
|
|
35
|
+
/**
|
|
36
|
+
* The compiled definition no longer matches the one the checkpoint was taken
|
|
37
|
+
* against, so its frames cannot be trusted to point at the same steps.
|
|
38
|
+
*/
|
|
39
|
+
class WorkflowDefinitionDriftError extends WorkflowResumeError {
|
|
40
|
+
constructor(expected, actual) {
|
|
41
|
+
super('Workflow definition changed since this run was suspended ' +
|
|
42
|
+
`(checkpoint fingerprint ${expected}, current ${actual}).`);
|
|
43
|
+
this.name = 'WorkflowDefinitionDriftError';
|
|
44
|
+
this.expected = expected;
|
|
45
|
+
this.actual = actual;
|
|
20
46
|
}
|
|
21
47
|
}
|
|
22
|
-
exports.
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
48
|
+
exports.WorkflowDefinitionDriftError = WorkflowDefinitionDriftError;
|
|
49
|
+
/** Several waits are open and the resume did not say which one it satisfies. */
|
|
50
|
+
class WorkflowWaitAmbiguousError extends WorkflowResumeError {
|
|
51
|
+
constructor(openWaitIds) {
|
|
52
|
+
super(`Workflow run is waiting on ${openWaitIds.length} suspensions; pass a ` +
|
|
53
|
+
`waitId to choose one (${openWaitIds.join(', ')}).`);
|
|
54
|
+
this.name = 'WorkflowWaitAmbiguousError';
|
|
55
|
+
this.openWaitIds = openWaitIds;
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
exports.WorkflowWaitAmbiguousError = WorkflowWaitAmbiguousError;
|
|
59
|
+
/** The run is not waiting on the requested suspension. */
|
|
60
|
+
class WorkflowWaitNotFoundError extends WorkflowResumeError {
|
|
61
|
+
constructor(waitId, openWaitIds) {
|
|
62
|
+
super(`Workflow run is not waiting on "${waitId}"` +
|
|
63
|
+
(openWaitIds.length > 0
|
|
64
|
+
? ` (open waits: ${openWaitIds.join(', ')}).`
|
|
65
|
+
: ' (no open waits).'));
|
|
66
|
+
this.name = 'WorkflowWaitNotFoundError';
|
|
67
|
+
this.waitId = waitId;
|
|
68
|
+
this.openWaitIds = openWaitIds;
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
exports.WorkflowWaitNotFoundError = WorkflowWaitNotFoundError;
|
|
72
|
+
/**
|
|
73
|
+
* The resume payload was refused. The wait stays open under the same
|
|
74
|
+
* `waitId`, so it can be resumed again, and the run's checkpoint, snapshot
|
|
75
|
+
* and step log are left as they were. Events already emitted by
|
|
76
|
+
* a body that refused the payload stay emitted, and its side effects,
|
|
77
|
+
* including writes to context state, are not undone.
|
|
78
|
+
*
|
|
79
|
+
* The runtime raises it when a payload does not match the `accepts` schema of
|
|
80
|
+
* the wait. An action may throw it itself, after its `suspend()` call
|
|
81
|
+
* resolved, to refuse a payload for reasons a schema cannot express.
|
|
82
|
+
*/
|
|
83
|
+
class WorkflowResumeRejectedError extends WorkflowResumeError {
|
|
84
|
+
constructor(message, options) {
|
|
85
|
+
super(message);
|
|
86
|
+
this.name = 'WorkflowResumeRejectedError';
|
|
87
|
+
this.issues = options?.issues;
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
exports.WorkflowResumeRejectedError = WorkflowResumeRejectedError;
|
|
91
|
+
/**
|
|
92
|
+
* A resumed action body did not replay the way it ran before it suspended,
|
|
93
|
+
* so the results recorded for it cannot be trusted.
|
|
94
|
+
*/
|
|
95
|
+
class NonDeterministicWorkflowError extends Error {
|
|
96
|
+
constructor(message) {
|
|
97
|
+
super(message);
|
|
98
|
+
this.name = 'NonDeterministicWorkflowError';
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
exports.NonDeterministicWorkflowError = NonDeterministicWorkflowError;
|
|
102
|
+
// Errors that cross into action code are also matched by name: an extension
|
|
103
|
+
// may import the other (CJS or ESM) build of this package, whose classes are
|
|
104
|
+
// distinct from these.
|
|
105
|
+
const isNamedError = (error, name) => error instanceof Error && error.name === name;
|
|
106
|
+
const isWorkflowResumeRejectedError = (error) => error instanceof WorkflowResumeRejectedError ||
|
|
107
|
+
isNamedError(error, 'WorkflowResumeRejectedError');
|
|
108
|
+
exports.isWorkflowResumeRejectedError = isWorkflowResumeRejectedError;
|
|
109
|
+
const isNonDeterministicWorkflowError = (error) => error instanceof NonDeterministicWorkflowError ||
|
|
110
|
+
isNamedError(error, 'NonDeterministicWorkflowError');
|
|
111
|
+
exports.isNonDeterministicWorkflowError = isNonDeterministicWorkflowError;
|
|
26
112
|
const getAbortReason = (signal) => {
|
|
27
113
|
if (signal.reason instanceof Error) {
|
|
28
114
|
return signal.reason;
|
|
@@ -39,3 +125,24 @@ const throwIfAborted = (signal) => {
|
|
|
39
125
|
}
|
|
40
126
|
};
|
|
41
127
|
exports.throwIfAborted = throwIfAborted;
|
|
128
|
+
/**
|
|
129
|
+
* Create a controller that aborts along with a parent signal, so a child
|
|
130
|
+
* scope can be cancelled on its own without cancelling the parent.
|
|
131
|
+
*
|
|
132
|
+
* @param parent Signal whose abort propagates to the new controller.
|
|
133
|
+
* @returns The controller, and a function detaching it from `parent`.
|
|
134
|
+
*/
|
|
135
|
+
const createLinkedAbortController = (parent) => {
|
|
136
|
+
const controller = new AbortController();
|
|
137
|
+
if (parent.aborted) {
|
|
138
|
+
controller.abort((0, exports.getAbortReason)(parent));
|
|
139
|
+
return { controller, unlink: () => undefined };
|
|
140
|
+
}
|
|
141
|
+
const onAbort = () => controller.abort((0, exports.getAbortReason)(parent));
|
|
142
|
+
parent.addEventListener('abort', onAbort, { once: true });
|
|
143
|
+
return {
|
|
144
|
+
controller,
|
|
145
|
+
unlink: () => parent.removeEventListener('abort', onAbort),
|
|
146
|
+
};
|
|
147
|
+
};
|
|
148
|
+
exports.createLinkedAbortController = createLinkedAbortController;
|
package/dist/cjs/index.js
CHANGED
|
@@ -19,7 +19,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
|
|
|
19
19
|
for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
|
|
20
20
|
};
|
|
21
21
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
22
|
-
exports.remapWorkflowDefinitionResourceRefs = exports.collectWorkflowDefinitionResourceRefs = exports.withTimeout = exports.sleep = exports.toSnakeCase = exports.isSnakeCaseName = exports.assertSnakeCaseName = exports.
|
|
22
|
+
exports.remapWorkflowDefinitionResourceRefs = exports.collectWorkflowDefinitionResourceRefs = exports.withTimeout = exports.sleep = exports.toSnakeCase = exports.isSnakeCaseName = exports.assertSnakeCaseName = exports.mergeSettings = exports.evaluateValue = exports.evaluateMapping = exports.compileValue = exports.WorkflowWaitNotFoundError = exports.WorkflowWaitAmbiguousError = exports.WorkflowResumeRejectedError = exports.WorkflowResumeError = exports.WorkflowDefinitionDriftError = exports.WorkflowCheckpointInvalidError = exports.WorkflowCancellationError = exports.NonDeterministicWorkflowError = exports.fingerprintWorkflow = exports.workflowCheckpointSchema = exports.validateCheckpoint = exports.collectWaits = exports.CHECKPOINT_VERSION = exports.StepType = exports.WorkflowRunner = exports.WorkflowEventEmitter = exports.Workflow = exports.compileWorkflow = exports.issueMessages = exports.WORKFLOW_RUN_STATUSES = exports.EWorkflowRunStatus = exports.BaseWorkflowContext = exports.defineAction = exports.AbstractAction = void 0;
|
|
23
23
|
var abstract_action_1 = require("./action/abstract-action");
|
|
24
24
|
Object.defineProperty(exports, "AbstractAction", { enumerable: true, get: function () { return abstract_action_1.AbstractAction; } });
|
|
25
25
|
var action_1 = require("./action/action");
|
|
@@ -38,18 +38,27 @@ Object.defineProperty(exports, "WorkflowEventEmitter", { enumerable: true, get:
|
|
|
38
38
|
Object.defineProperty(exports, "WorkflowRunner", { enumerable: true, get: function () { return workflow_1.WorkflowRunner; } });
|
|
39
39
|
var workflow_event_emitter_1 = require("./workflow-event-emitter");
|
|
40
40
|
Object.defineProperty(exports, "StepType", { enumerable: true, get: function () { return workflow_event_emitter_1.StepType; } });
|
|
41
|
-
var
|
|
42
|
-
Object.defineProperty(exports, "
|
|
41
|
+
var checkpoint_1 = require("./checkpoint");
|
|
42
|
+
Object.defineProperty(exports, "CHECKPOINT_VERSION", { enumerable: true, get: function () { return checkpoint_1.CHECKPOINT_VERSION; } });
|
|
43
|
+
Object.defineProperty(exports, "collectWaits", { enumerable: true, get: function () { return checkpoint_1.collectWaits; } });
|
|
44
|
+
Object.defineProperty(exports, "validateCheckpoint", { enumerable: true, get: function () { return checkpoint_1.validateCheckpoint; } });
|
|
45
|
+
Object.defineProperty(exports, "workflowCheckpointSchema", { enumerable: true, get: function () { return checkpoint_1.workflowCheckpointSchema; } });
|
|
46
|
+
var workflow_fingerprint_1 = require("./workflow-fingerprint");
|
|
47
|
+
Object.defineProperty(exports, "fingerprintWorkflow", { enumerable: true, get: function () { return workflow_fingerprint_1.fingerprintWorkflow; } });
|
|
43
48
|
var errors_1 = require("./errors");
|
|
44
|
-
Object.defineProperty(exports, "
|
|
49
|
+
Object.defineProperty(exports, "NonDeterministicWorkflowError", { enumerable: true, get: function () { return errors_1.NonDeterministicWorkflowError; } });
|
|
45
50
|
Object.defineProperty(exports, "WorkflowCancellationError", { enumerable: true, get: function () { return errors_1.WorkflowCancellationError; } });
|
|
51
|
+
Object.defineProperty(exports, "WorkflowCheckpointInvalidError", { enumerable: true, get: function () { return errors_1.WorkflowCheckpointInvalidError; } });
|
|
52
|
+
Object.defineProperty(exports, "WorkflowDefinitionDriftError", { enumerable: true, get: function () { return errors_1.WorkflowDefinitionDriftError; } });
|
|
53
|
+
Object.defineProperty(exports, "WorkflowResumeError", { enumerable: true, get: function () { return errors_1.WorkflowResumeError; } });
|
|
54
|
+
Object.defineProperty(exports, "WorkflowResumeRejectedError", { enumerable: true, get: function () { return errors_1.WorkflowResumeRejectedError; } });
|
|
55
|
+
Object.defineProperty(exports, "WorkflowWaitAmbiguousError", { enumerable: true, get: function () { return errors_1.WorkflowWaitAmbiguousError; } });
|
|
56
|
+
Object.defineProperty(exports, "WorkflowWaitNotFoundError", { enumerable: true, get: function () { return errors_1.WorkflowWaitNotFoundError; } });
|
|
46
57
|
var workflow_values_1 = require("./workflow-values");
|
|
47
58
|
Object.defineProperty(exports, "compileValue", { enumerable: true, get: function () { return workflow_values_1.compileValue; } });
|
|
48
59
|
Object.defineProperty(exports, "evaluateMapping", { enumerable: true, get: function () { return workflow_values_1.evaluateMapping; } });
|
|
49
60
|
Object.defineProperty(exports, "evaluateValue", { enumerable: true, get: function () { return workflow_values_1.evaluateValue; } });
|
|
50
61
|
Object.defineProperty(exports, "mergeSettings", { enumerable: true, get: function () { return workflow_values_1.mergeSettings; } });
|
|
51
|
-
var deferred_1 = require("./utils/deferred");
|
|
52
|
-
Object.defineProperty(exports, "createDeferred", { enumerable: true, get: function () { return deferred_1.createDeferred; } });
|
|
53
62
|
var naming_1 = require("./utils/naming");
|
|
54
63
|
Object.defineProperty(exports, "assertSnakeCaseName", { enumerable: true, get: function () { return naming_1.assertSnakeCaseName; } });
|
|
55
64
|
Object.defineProperty(exports, "isSnakeCaseName", { enumerable: true, get: function () { return naming_1.isSnakeCaseName; } });
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/*
|
|
3
|
+
* Hexabot — Fair Core License (FCL-1.0-ALv2)
|
|
4
|
+
* Copyright (c) 2025 Hexastack.
|
|
5
|
+
* Full terms: see LICENSE.md.
|
|
6
|
+
*/
|
|
7
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
8
|
+
exports.describeResumePayload = describeResumePayload;
|
|
9
|
+
exports.isPayloadOptional = isPayloadOptional;
|
|
10
|
+
exports.findNonJsonTypes = findNonJsonTypes;
|
|
11
|
+
exports.checkResumePayload = checkResumePayload;
|
|
12
|
+
exports.rejectResumePayload = rejectResumePayload;
|
|
13
|
+
const zod_1 = require("zod");
|
|
14
|
+
const errors_1 = require("./errors");
|
|
15
|
+
const clone_1 = require("./utils/clone");
|
|
16
|
+
// Keywords that `z.fromJSONSchema` turns back into the same check. Others,
|
|
17
|
+
// such as `pattern` (regex flags are lost), `format` or `propertyNames` (an
|
|
18
|
+
// enum of keys becomes exhaustive), can come back stricter than the schema
|
|
19
|
+
// they were generated from, so they are dropped.
|
|
20
|
+
const KEPT_KEYWORDS = new Set([
|
|
21
|
+
'$schema',
|
|
22
|
+
'$ref',
|
|
23
|
+
'$defs',
|
|
24
|
+
'title',
|
|
25
|
+
'description',
|
|
26
|
+
'type',
|
|
27
|
+
'properties',
|
|
28
|
+
'required',
|
|
29
|
+
'additionalProperties',
|
|
30
|
+
'items',
|
|
31
|
+
'prefixItems',
|
|
32
|
+
'anyOf',
|
|
33
|
+
'allOf',
|
|
34
|
+
'enum',
|
|
35
|
+
'const',
|
|
36
|
+
'minLength',
|
|
37
|
+
'maxLength',
|
|
38
|
+
'minimum',
|
|
39
|
+
'maximum',
|
|
40
|
+
'exclusiveMinimum',
|
|
41
|
+
'exclusiveMaximum',
|
|
42
|
+
'minItems',
|
|
43
|
+
'maxItems',
|
|
44
|
+
]);
|
|
45
|
+
// Bounds a rewrite such as `.trim()` applies to the rewritten value.
|
|
46
|
+
const BOUND_KEYWORDS = [
|
|
47
|
+
'minLength',
|
|
48
|
+
'maxLength',
|
|
49
|
+
'minimum',
|
|
50
|
+
'maximum',
|
|
51
|
+
'exclusiveMinimum',
|
|
52
|
+
'exclusiveMaximum',
|
|
53
|
+
'minItems',
|
|
54
|
+
'maxItems',
|
|
55
|
+
];
|
|
56
|
+
// Types JSON has no value for: a payload read back from the checkpoint can
|
|
57
|
+
// never match them unless they coerce.
|
|
58
|
+
const NON_JSON_TYPES = new Set([
|
|
59
|
+
'date',
|
|
60
|
+
'bigint',
|
|
61
|
+
'symbol',
|
|
62
|
+
'map',
|
|
63
|
+
'set',
|
|
64
|
+
'nan',
|
|
65
|
+
'function',
|
|
66
|
+
'file',
|
|
67
|
+
]);
|
|
68
|
+
// Wrappers whose input is their inner schema's input.
|
|
69
|
+
const WRAPPER_TYPES = new Set([
|
|
70
|
+
'optional',
|
|
71
|
+
'nullable',
|
|
72
|
+
'nonoptional',
|
|
73
|
+
'readonly',
|
|
74
|
+
'default',
|
|
75
|
+
'prefault',
|
|
76
|
+
'promise',
|
|
77
|
+
]);
|
|
78
|
+
/**
|
|
79
|
+
* Describe the payload a `suspend()` call accepts as a JSON Schema that can
|
|
80
|
+
* be stored on its wait.
|
|
81
|
+
*
|
|
82
|
+
* JSON Schema cannot express everything a Zod schema checks, so the result is
|
|
83
|
+
* relaxed until it never refuses a JSON payload the Zod schema accepts:
|
|
84
|
+
* coerced, preprocessed and `catch` nodes accept anything, and keywords that
|
|
85
|
+
* do not round-trip exactly are dropped. The Zod schema stays authoritative
|
|
86
|
+
* when the action body reads the payload.
|
|
87
|
+
*
|
|
88
|
+
* @param schema The `accepts` schema passed to `suspend()`.
|
|
89
|
+
* @returns The relaxed JSON Schema, or undefined when it cannot be generated.
|
|
90
|
+
*/
|
|
91
|
+
function describeResumePayload(schema) {
|
|
92
|
+
try {
|
|
93
|
+
return zod_1.z.toJSONSchema(schema, {
|
|
94
|
+
io: 'input',
|
|
95
|
+
unrepresentable: 'any',
|
|
96
|
+
override: ({ zodSchema, jsonSchema }) => relaxNode(zodSchema._zod.def, jsonSchema),
|
|
97
|
+
});
|
|
98
|
+
}
|
|
99
|
+
catch {
|
|
100
|
+
return undefined;
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* Report whether an `accepts` schema also accepts a resume without payload.
|
|
105
|
+
* Its JSON Schema cannot say so, since JSON has no `undefined`.
|
|
106
|
+
*
|
|
107
|
+
* @param schema The `accepts` schema passed to `suspend()`.
|
|
108
|
+
* @returns True when the schema accepts `undefined`, e.g. when it is optional.
|
|
109
|
+
*/
|
|
110
|
+
function isPayloadOptional(schema) {
|
|
111
|
+
const { optin, def } = schema._zod;
|
|
112
|
+
// Zod marks `.default()` as "defaulted" and gives `z.undefined()` and
|
|
113
|
+
// `z.void()` no optin, though both accept a missing payload.
|
|
114
|
+
return (optin === 'optional' ||
|
|
115
|
+
optin === 'defaulted' ||
|
|
116
|
+
def.type === 'undefined' ||
|
|
117
|
+
def.type === 'void');
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* List the parts of an `accepts` schema that no JSON payload can match.
|
|
121
|
+
*
|
|
122
|
+
* Payloads are read back from the checkpoint as JSON, so a type JSON cannot
|
|
123
|
+
* carry, such as `z.date()`, refuses every payload: a `Date` resumes as its
|
|
124
|
+
* ISO string. Parts that coerce, preprocess or catch their input are fine.
|
|
125
|
+
*
|
|
126
|
+
* @param schema The `accepts` schema passed to `suspend()`.
|
|
127
|
+
* @returns One `<path> (<type>)` entry per offending part, in schema order.
|
|
128
|
+
*/
|
|
129
|
+
function findNonJsonTypes(schema) {
|
|
130
|
+
const found = [];
|
|
131
|
+
const seen = new Set();
|
|
132
|
+
const visit = (node, path) => {
|
|
133
|
+
// Shared and recursive schemas are visited once.
|
|
134
|
+
if (!node || seen.has(node)) {
|
|
135
|
+
return;
|
|
136
|
+
}
|
|
137
|
+
seen.add(node);
|
|
138
|
+
const def = node._zod.def;
|
|
139
|
+
if (acceptsBeyondItsType(def)) {
|
|
140
|
+
return;
|
|
141
|
+
}
|
|
142
|
+
if (NON_JSON_TYPES.has(def.type)) {
|
|
143
|
+
found.push(`${path || '(root)'} (${def.type})`);
|
|
144
|
+
return;
|
|
145
|
+
}
|
|
146
|
+
if (WRAPPER_TYPES.has(def.type)) {
|
|
147
|
+
return visit(def.innerType, path);
|
|
148
|
+
}
|
|
149
|
+
switch (def.type) {
|
|
150
|
+
case 'object':
|
|
151
|
+
return Object.entries(def.shape ?? {}).forEach(([key, child]) => visit(child, path ? `${path}.${key}` : key));
|
|
152
|
+
case 'record':
|
|
153
|
+
return visit(def.valueType, `${path}.*`);
|
|
154
|
+
case 'array':
|
|
155
|
+
return visit(def.element, `${path}[]`);
|
|
156
|
+
case 'tuple':
|
|
157
|
+
def.items?.forEach((item, index) => visit(item, `${path}[${index}]`));
|
|
158
|
+
return visit(def.rest, `${path}[]`);
|
|
159
|
+
case 'union':
|
|
160
|
+
return def.options?.forEach((option) => visit(option, path));
|
|
161
|
+
case 'intersection':
|
|
162
|
+
visit(def.left, path);
|
|
163
|
+
return visit(def.right, path);
|
|
164
|
+
case 'pipe':
|
|
165
|
+
// The payload is the input of the pipe, e.g. the string of a codec.
|
|
166
|
+
return visit(def.in, path);
|
|
167
|
+
case 'lazy':
|
|
168
|
+
return visit(def.getter?.(), path);
|
|
169
|
+
}
|
|
170
|
+
};
|
|
171
|
+
visit(schema, '');
|
|
172
|
+
return found;
|
|
173
|
+
}
|
|
174
|
+
/**
|
|
175
|
+
* Check a resume payload against the wait it resolves, without running
|
|
176
|
+
* anything.
|
|
177
|
+
*
|
|
178
|
+
* The payload is first normalized the way the checkpoint stores it, so the
|
|
179
|
+
* check sees what the action body will read. A resume without payload stays
|
|
180
|
+
* `undefined`, which a wait with `accepts` takes only when its payload is
|
|
181
|
+
* optional.
|
|
182
|
+
*
|
|
183
|
+
* @param wait The wait the payload resolves.
|
|
184
|
+
* @param resumeData The payload, as passed to `resume()`.
|
|
185
|
+
* @returns The normalized payload, or why it is refused.
|
|
186
|
+
*/
|
|
187
|
+
function checkResumePayload(wait, resumeData) {
|
|
188
|
+
let value;
|
|
189
|
+
try {
|
|
190
|
+
value = resumeData === undefined ? undefined : (0, clone_1.cloneAsJson)(resumeData);
|
|
191
|
+
}
|
|
192
|
+
catch (error) {
|
|
193
|
+
const reason = error instanceof Error ? error.message : String(error);
|
|
194
|
+
return {
|
|
195
|
+
ok: false,
|
|
196
|
+
error: new errors_1.WorkflowResumeRejectedError(`Resume payload for wait "${wait.waitId}" cannot be stored as JSON (${reason}).`),
|
|
197
|
+
};
|
|
198
|
+
}
|
|
199
|
+
if (!wait.accepts || (value === undefined && wait.payloadOptional)) {
|
|
200
|
+
return { ok: true, value };
|
|
201
|
+
}
|
|
202
|
+
let schema;
|
|
203
|
+
try {
|
|
204
|
+
schema = zod_1.z.fromJSONSchema(wait.accepts);
|
|
205
|
+
}
|
|
206
|
+
catch {
|
|
207
|
+
// Unreadable here; the action's own schema still checks the payload.
|
|
208
|
+
return { ok: true, value };
|
|
209
|
+
}
|
|
210
|
+
const result = schema.safeParse(value);
|
|
211
|
+
if (result.success) {
|
|
212
|
+
return { ok: true, value };
|
|
213
|
+
}
|
|
214
|
+
return {
|
|
215
|
+
ok: false,
|
|
216
|
+
error: rejectResumePayload(`wait "${wait.waitId}"`, result.error.issues),
|
|
217
|
+
};
|
|
218
|
+
}
|
|
219
|
+
/**
|
|
220
|
+
* Build the error refusing a payload that failed a schema.
|
|
221
|
+
*
|
|
222
|
+
* @param subject What the payload was meant for, used in the message.
|
|
223
|
+
* @param issues The schema issues.
|
|
224
|
+
* @returns The rejection error.
|
|
225
|
+
*/
|
|
226
|
+
function rejectResumePayload(subject, issues) {
|
|
227
|
+
const messages = issues.map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`);
|
|
228
|
+
return new errors_1.WorkflowResumeRejectedError(`Resume payload for ${subject} was rejected: ${messages.join('; ')}`, { issues: messages });
|
|
229
|
+
}
|
|
230
|
+
const relaxNode = (def, jsonSchema) => {
|
|
231
|
+
if (acceptsBeyondItsType(def)) {
|
|
232
|
+
for (const keyword of Object.keys(jsonSchema)) {
|
|
233
|
+
delete jsonSchema[keyword];
|
|
234
|
+
}
|
|
235
|
+
return;
|
|
236
|
+
}
|
|
237
|
+
// `oneOf` refuses a payload matching several options; `anyOf` does not.
|
|
238
|
+
if ('oneOf' in jsonSchema) {
|
|
239
|
+
jsonSchema.anyOf = jsonSchema.oneOf;
|
|
240
|
+
delete jsonSchema.oneOf;
|
|
241
|
+
}
|
|
242
|
+
for (const keyword of Object.keys(jsonSchema)) {
|
|
243
|
+
if (!KEPT_KEYWORDS.has(keyword)) {
|
|
244
|
+
delete jsonSchema[keyword];
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
if (def.checks?.some((check) => check._zod.def.check === 'overwrite')) {
|
|
248
|
+
for (const keyword of BOUND_KEYWORDS) {
|
|
249
|
+
delete jsonSchema[keyword];
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
};
|
|
253
|
+
/** Nodes that accept inputs their JSON Schema type would refuse. */
|
|
254
|
+
const acceptsBeyondItsType = (def) => def.coerce === true ||
|
|
255
|
+
def.type === 'catch' ||
|
|
256
|
+
def.type === 'custom' ||
|
|
257
|
+
(def.type === 'pipe' && def.in?._zod.def.type === 'transform');
|