@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
|
@@ -6,16 +6,18 @@
|
|
|
6
6
|
*/
|
|
7
7
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
8
8
|
exports.WorkflowRunner = void 0;
|
|
9
|
+
const checkpoint_1 = require("./checkpoint");
|
|
9
10
|
const context_1 = require("./context");
|
|
10
11
|
const errors_1 = require("./errors");
|
|
12
|
+
const resume_payload_1 = require("./resume-payload");
|
|
11
13
|
const runner_runtime_control_1 = require("./runner-runtime-control");
|
|
12
14
|
const conditional_executor_1 = require("./step-executors/conditional-executor");
|
|
13
15
|
const loop_executor_1 = require("./step-executors/loop-executor");
|
|
14
16
|
const parallel_executor_1 = require("./step-executors/parallel-executor");
|
|
15
|
-
const suspension_continuation_1 = require("./step-executors/suspension-continuation");
|
|
16
17
|
const task_executor_1 = require("./step-executors/task-executor");
|
|
17
|
-
const
|
|
18
|
+
const clone_1 = require("./utils/clone");
|
|
18
19
|
const workflow_event_emitter_1 = require("./workflow-event-emitter");
|
|
20
|
+
const workflow_fingerprint_1 = require("./workflow-fingerprint");
|
|
19
21
|
const workflow_values_1 = require("./workflow-values");
|
|
20
22
|
/**
|
|
21
23
|
* Executes a compiled workflow definition, tracking state, suspensions, and event hooks.
|
|
@@ -81,20 +83,13 @@ class WorkflowRunner {
|
|
|
81
83
|
]));
|
|
82
84
|
}
|
|
83
85
|
/**
|
|
84
|
-
* Read the
|
|
86
|
+
* Read the checkpoint of a suspended run: everything a host must persist to
|
|
87
|
+
* resume it later, in this process or another one. Treat it as read-only.
|
|
85
88
|
*
|
|
86
|
-
* @returns
|
|
89
|
+
* @returns The checkpoint while the run is suspended, otherwise undefined.
|
|
87
90
|
*/
|
|
88
|
-
|
|
89
|
-
return this.
|
|
90
|
-
}
|
|
91
|
-
/**
|
|
92
|
-
* Access the last payload supplied to a resume call.
|
|
93
|
-
*
|
|
94
|
-
* @returns The most recent resume data, or undefined if none.
|
|
95
|
-
*/
|
|
96
|
-
getLastResumeData() {
|
|
97
|
-
return this.lastResumeData;
|
|
91
|
+
getCheckpoint() {
|
|
92
|
+
return this.checkpoint;
|
|
98
93
|
}
|
|
99
94
|
/**
|
|
100
95
|
* Begin executing the workflow from the first step.
|
|
@@ -107,77 +102,139 @@ class WorkflowRunner {
|
|
|
107
102
|
this.status = context_1.EWorkflowRunStatus.RUNNING;
|
|
108
103
|
this.snapshots = {};
|
|
109
104
|
this.stepLog = {};
|
|
110
|
-
this.
|
|
111
|
-
this.lastResumeData = undefined;
|
|
112
|
-
this.currentStep = undefined;
|
|
105
|
+
this.checkpoint = undefined;
|
|
113
106
|
this.context = args.context;
|
|
114
107
|
this.state = {
|
|
115
108
|
input: this.compiled.inputParser.parse(args.inputData ?? {}),
|
|
116
109
|
output: {},
|
|
117
110
|
iterationStack: [],
|
|
118
111
|
};
|
|
119
|
-
this.runtimeControl = new runner_runtime_control_1.RunnerRuntimeControl(
|
|
112
|
+
this.runtimeControl = new runner_runtime_control_1.RunnerRuntimeControl();
|
|
120
113
|
this.context.attachWorkflowRuntime(this.runtimeControl);
|
|
121
114
|
this.emit('hook:workflow:start', { runId: this.runId });
|
|
122
|
-
|
|
123
|
-
if (!state) {
|
|
124
|
-
throw new Error('Workflow state not initialized.');
|
|
125
|
-
}
|
|
126
|
-
const env = this.createExecutorEnv();
|
|
127
|
-
return this.runExecution(() => this.executeFlow(this.compiled.flow, state, [], 0, env));
|
|
115
|
+
return this.runExecution(new Map());
|
|
128
116
|
}
|
|
129
117
|
/**
|
|
130
|
-
* Resume a
|
|
118
|
+
* Resume a suspended workflow by satisfying one of its open waits.
|
|
119
|
+
*
|
|
120
|
+
* Execution re-enters the checkpoint's frames: completed work is skipped,
|
|
121
|
+
* the resolved step re-runs its action body, and waits left untouched stay
|
|
122
|
+
* parked.
|
|
131
123
|
*
|
|
132
|
-
*
|
|
124
|
+
* A payload the wait does not accept is refused, first against the wait's
|
|
125
|
+
* `accepts` JSON Schema without running anything, then by the action body.
|
|
126
|
+
* Either way the result is suspended on the same waits and carries
|
|
127
|
+
* `rejection`, and the checkpoint, snapshot and step log are left as they
|
|
128
|
+
* were. Events a refusing body emitted are not withdrawn, and its side
|
|
129
|
+
* effects, including writes to context state, are not undone.
|
|
130
|
+
*
|
|
131
|
+
* @param args Resume payload and, when several waits are open, the wait it satisfies.
|
|
133
132
|
* @returns Execution result including status and snapshot.
|
|
133
|
+
* @throws {WorkflowWaitNotFoundError} When `waitId` is not an open wait.
|
|
134
|
+
* @throws {WorkflowWaitAmbiguousError} When several waits are open and no
|
|
135
|
+
* `waitId` is given.
|
|
134
136
|
*/
|
|
135
137
|
async resume(args) {
|
|
136
|
-
if (this.status !== context_1.EWorkflowRunStatus.SUSPENDED || !this.
|
|
138
|
+
if (this.status !== context_1.EWorkflowRunStatus.SUSPENDED || !this.checkpoint) {
|
|
137
139
|
throw new Error('Cannot resume a workflow that is not suspended.');
|
|
138
140
|
}
|
|
139
|
-
if (!this.context
|
|
141
|
+
if (!this.context) {
|
|
140
142
|
throw new Error('Workflow state is not initialized.');
|
|
141
143
|
}
|
|
144
|
+
const wait = (0, checkpoint_1.selectWait)(this.checkpoint.waits, args.waitId);
|
|
145
|
+
const payload = (0, resume_payload_1.checkResumePayload)(wait, args.resumeData);
|
|
146
|
+
const result = payload.ok
|
|
147
|
+
? await this.resolveWait(wait, payload.value)
|
|
148
|
+
: this.keepWaiting(this.checkpoint, {
|
|
149
|
+
waitId: wait.waitId,
|
|
150
|
+
error: payload.error,
|
|
151
|
+
});
|
|
152
|
+
if (result.status === context_1.EWorkflowRunStatus.SUSPENDED && result.rejection) {
|
|
153
|
+
this.emit('hook:workflow:resume_rejected', {
|
|
154
|
+
runId: this.runId,
|
|
155
|
+
wait,
|
|
156
|
+
resumeData: args.resumeData,
|
|
157
|
+
error: result.rejection.error,
|
|
158
|
+
});
|
|
159
|
+
}
|
|
160
|
+
return result;
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* Run the pass that resolves one wait with an accepted payload.
|
|
164
|
+
*
|
|
165
|
+
* @param wait The wait being resolved.
|
|
166
|
+
* @param recorded The payload as the checkpoint records it.
|
|
167
|
+
* @returns Execution result including status and snapshot.
|
|
168
|
+
*/
|
|
169
|
+
async resolveWait(wait, recorded) {
|
|
170
|
+
const checkpoint = this.checkpoint;
|
|
171
|
+
if (!checkpoint) {
|
|
172
|
+
throw new Error('Cannot resume a workflow that is not suspended.');
|
|
173
|
+
}
|
|
174
|
+
const report = {
|
|
175
|
+
state: this.state,
|
|
176
|
+
snapshots: { ...this.snapshots },
|
|
177
|
+
stepLog: { ...this.stepLog },
|
|
178
|
+
};
|
|
142
179
|
this.status = context_1.EWorkflowRunStatus.RUNNING;
|
|
143
|
-
this.
|
|
144
|
-
|
|
145
|
-
|
|
180
|
+
this.context?.attachWorkflowRuntime(this.runtimeControl);
|
|
181
|
+
return this.runExecution(new Map([[wait.waitId, recorded]]), {
|
|
182
|
+
checkpoint,
|
|
183
|
+
report,
|
|
184
|
+
});
|
|
146
185
|
}
|
|
147
186
|
/**
|
|
148
|
-
*
|
|
187
|
+
* Run the flow from the top, or from a checkpoint, and normalize
|
|
188
|
+
* suspension, finish, and failure handling.
|
|
149
189
|
*
|
|
150
|
-
* @param
|
|
190
|
+
* @param resolutions Resume payloads for the waits this pass satisfies.
|
|
191
|
+
* @param resumed Suspended run to resume from; omitted on start.
|
|
151
192
|
* @returns Result of the execution attempt.
|
|
152
193
|
*/
|
|
153
|
-
async runExecution(
|
|
194
|
+
async runExecution(resolutions, resumed) {
|
|
195
|
+
const pass = { resolutions };
|
|
154
196
|
try {
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
197
|
+
// In-process and durable resumes start from the same detached JSON
|
|
198
|
+
// copy, so both see exactly what a host would have persisted.
|
|
199
|
+
const from = resumed ? (0, clone_1.cloneAsJson)(resumed.checkpoint) : undefined;
|
|
200
|
+
if (from) {
|
|
201
|
+
this.state = {
|
|
202
|
+
input: from.input,
|
|
203
|
+
output: from.output,
|
|
204
|
+
iterationStack: [],
|
|
205
|
+
};
|
|
206
|
+
}
|
|
207
|
+
const state = this.state;
|
|
208
|
+
if (!state) {
|
|
209
|
+
throw new Error('Workflow state not initialized.');
|
|
210
|
+
}
|
|
211
|
+
const root = await this.executeFlow(this.compiled.flow, state, [], from?.root, this.createExecutorEnv(pass));
|
|
212
|
+
// Only the refusing step ran in this pass, and it did not complete, so
|
|
213
|
+
// the run is put back as the checkpoint it started from describes it.
|
|
214
|
+
if (pass.rejection && resumed) {
|
|
215
|
+
this.state = resumed.report.state;
|
|
216
|
+
this.snapshots = resumed.report.snapshots;
|
|
217
|
+
this.stepLog = resumed.report.stepLog;
|
|
218
|
+
return this.keepWaiting(resumed.checkpoint, pass.rejection);
|
|
219
|
+
}
|
|
220
|
+
if (root) {
|
|
221
|
+
const next = this.buildCheckpoint(state, root);
|
|
222
|
+
this.checkpoint = next;
|
|
158
223
|
this.status = context_1.EWorkflowRunStatus.SUSPENDED;
|
|
159
224
|
this.emit('hook:workflow:suspended', {
|
|
160
225
|
runId: this.runId,
|
|
161
|
-
|
|
162
|
-
reason: suspension.reason,
|
|
163
|
-
data: suspension.data,
|
|
226
|
+
waits: next.waits,
|
|
164
227
|
});
|
|
165
228
|
return {
|
|
166
229
|
status: context_1.EWorkflowRunStatus.SUSPENDED,
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
data: suspension.data,
|
|
170
|
-
stepExecId: suspension.stepExecId,
|
|
171
|
-
suspendIndex: suspension.suspendIndex,
|
|
172
|
-
suspendKey: suspension.suspendKey,
|
|
173
|
-
awaitResults: suspension.awaitResults,
|
|
230
|
+
waits: next.waits,
|
|
231
|
+
checkpoint: next,
|
|
174
232
|
snapshot: this.getSnapshot(),
|
|
175
233
|
};
|
|
176
234
|
}
|
|
177
235
|
const output = await this.evaluateWorkflowOutputs();
|
|
178
236
|
this.status = context_1.EWorkflowRunStatus.FINISHED;
|
|
179
|
-
this.
|
|
180
|
-
this.currentStep = undefined;
|
|
237
|
+
this.checkpoint = undefined;
|
|
181
238
|
this.emit('hook:workflow:finish', { runId: this.runId, output });
|
|
182
239
|
if (!this.context) {
|
|
183
240
|
throw new Error('Workflow context is not attached.');
|
|
@@ -191,7 +248,7 @@ class WorkflowRunner {
|
|
|
191
248
|
}
|
|
192
249
|
catch (error) {
|
|
193
250
|
this.status = context_1.EWorkflowRunStatus.FAILED;
|
|
194
|
-
this.
|
|
251
|
+
this.checkpoint = undefined;
|
|
195
252
|
this.emit('hook:workflow:failure', { runId: this.runId, error });
|
|
196
253
|
this.context?.attachWorkflowRuntime(undefined);
|
|
197
254
|
return {
|
|
@@ -202,47 +259,84 @@ class WorkflowRunner {
|
|
|
202
259
|
}
|
|
203
260
|
}
|
|
204
261
|
/**
|
|
205
|
-
*
|
|
262
|
+
* Leave the run suspended on `checkpoint` after a resume payload was
|
|
263
|
+
* refused.
|
|
264
|
+
*
|
|
265
|
+
* @param checkpoint The checkpoint the run was suspended on.
|
|
266
|
+
* @param rejection The refused wait and why.
|
|
267
|
+
* @returns The suspended result, carrying the rejection.
|
|
268
|
+
*/
|
|
269
|
+
keepWaiting(checkpoint, rejection) {
|
|
270
|
+
this.checkpoint = checkpoint;
|
|
271
|
+
this.status = context_1.EWorkflowRunStatus.SUSPENDED;
|
|
272
|
+
return {
|
|
273
|
+
status: context_1.EWorkflowRunStatus.SUSPENDED,
|
|
274
|
+
waits: checkpoint.waits,
|
|
275
|
+
checkpoint,
|
|
276
|
+
snapshot: this.getSnapshot(),
|
|
277
|
+
rejection,
|
|
278
|
+
};
|
|
279
|
+
}
|
|
280
|
+
/**
|
|
281
|
+
* Snapshot the suspended run as a detached JSON checkpoint.
|
|
282
|
+
*
|
|
283
|
+
* The checkpoint goes through the same JSON round trip a host applies when
|
|
284
|
+
* persisting it, so a resumed run sees the same values in process and
|
|
285
|
+
* after a restore.
|
|
286
|
+
*
|
|
287
|
+
* @param state Root execution state at suspension time.
|
|
288
|
+
* @param root Frame returned by the top-level flow.
|
|
289
|
+
* @returns The checkpoint to hand to the host.
|
|
290
|
+
* @throws When the run's state cannot be encoded as JSON.
|
|
291
|
+
*/
|
|
292
|
+
buildCheckpoint(state, root) {
|
|
293
|
+
try {
|
|
294
|
+
return (0, clone_1.cloneAsJson)({
|
|
295
|
+
version: checkpoint_1.CHECKPOINT_VERSION,
|
|
296
|
+
fingerprint: (0, workflow_fingerprint_1.fingerprintWorkflow)(this.compiled),
|
|
297
|
+
input: state.input,
|
|
298
|
+
output: state.output,
|
|
299
|
+
root,
|
|
300
|
+
waits: (0, checkpoint_1.collectWaits)(root),
|
|
301
|
+
});
|
|
302
|
+
}
|
|
303
|
+
catch (error) {
|
|
304
|
+
const reason = error instanceof Error ? error.message : String(error);
|
|
305
|
+
throw new Error(`Cannot checkpoint the suspended run: its state is not JSON-serializable (${reason}).`);
|
|
306
|
+
}
|
|
307
|
+
}
|
|
308
|
+
/**
|
|
309
|
+
* Restore a suspended run from its persisted checkpoint, typically in a
|
|
310
|
+
* different process than the one that suspended it.
|
|
206
311
|
*
|
|
207
312
|
* @param compiled The compiled workflow definition.
|
|
208
|
-
* @param options
|
|
209
|
-
* @
|
|
313
|
+
* @param options.checkpoint Checkpoint returned when the run suspended.
|
|
314
|
+
* @param options.context Freshly hydrated workflow context.
|
|
315
|
+
* @param options.snapshot Persisted action snapshot, to keep reporting past steps.
|
|
316
|
+
* @param options.runId Run identifier propagated through events.
|
|
317
|
+
* @returns A suspended runner ready for {@link resume}.
|
|
318
|
+
* @throws {WorkflowResumeError} When the checkpoint cannot resume against `compiled`.
|
|
210
319
|
*/
|
|
211
|
-
static
|
|
320
|
+
static fromCheckpoint(compiled, options) {
|
|
321
|
+
const validation = (0, checkpoint_1.validateCheckpoint)(compiled, options.checkpoint);
|
|
322
|
+
if (!validation.ok) {
|
|
323
|
+
throw validation.error;
|
|
324
|
+
}
|
|
325
|
+
const checkpoint = validation.checkpoint;
|
|
212
326
|
const runner = new WorkflowRunner(compiled, {
|
|
213
327
|
runId: options.runId,
|
|
214
328
|
});
|
|
329
|
+
runner.checkpoint = checkpoint;
|
|
215
330
|
runner.state = {
|
|
216
|
-
input:
|
|
217
|
-
output:
|
|
218
|
-
|
|
219
|
-
accumulator: options.state.accumulator,
|
|
220
|
-
iterationStack: [...(options.state.iterationStack ?? [])],
|
|
331
|
+
input: checkpoint.input,
|
|
332
|
+
output: checkpoint.output,
|
|
333
|
+
iterationStack: [],
|
|
221
334
|
};
|
|
222
335
|
runner.context = options.context;
|
|
223
|
-
runner.snapshots = options.snapshot
|
|
224
|
-
runner.
|
|
225
|
-
runner.
|
|
226
|
-
runner.lastResumeData = options.lastResumeData;
|
|
227
|
-
runner.runtimeControl = new runner_runtime_control_1.RunnerRuntimeControl(runner);
|
|
336
|
+
runner.snapshots = { ...(options.snapshot?.actions ?? {}) };
|
|
337
|
+
runner.status = context_1.EWorkflowRunStatus.SUSPENDED;
|
|
338
|
+
runner.runtimeControl = new runner_runtime_control_1.RunnerRuntimeControl();
|
|
228
339
|
options.context.attachWorkflowRuntime(runner.runtimeControl);
|
|
229
|
-
if (options.suspension) {
|
|
230
|
-
const suspension = (0, suspension_rebuilder_1.rebuildSuspension)(runner.createSuspensionRebuilderDeps(), {
|
|
231
|
-
state: runner.state,
|
|
232
|
-
stepId: options.suspension.stepId,
|
|
233
|
-
reason: options.suspension.reason ?? undefined,
|
|
234
|
-
data: options.suspension.data,
|
|
235
|
-
stepExecId: options.suspension.stepExecId,
|
|
236
|
-
suspendIndex: options.suspension.suspendIndex,
|
|
237
|
-
suspendKey: options.suspension.suspendKey,
|
|
238
|
-
awaitResults: options.suspension.awaitResults,
|
|
239
|
-
});
|
|
240
|
-
if (!suspension) {
|
|
241
|
-
throw new Error(`Unable to rebuild suspension for step ${options.suspension.stepId}`);
|
|
242
|
-
}
|
|
243
|
-
runner.suspension = suspension;
|
|
244
|
-
runner.status = context_1.EWorkflowRunStatus.SUSPENDED;
|
|
245
|
-
}
|
|
246
340
|
return runner;
|
|
247
341
|
}
|
|
248
342
|
/**
|
|
@@ -336,103 +430,71 @@ class WorkflowRunner {
|
|
|
336
430
|
/**
|
|
337
431
|
* Construct the environment object passed to step executors.
|
|
338
432
|
*
|
|
433
|
+
* @param pass The execution pass, shared by every scope it forks.
|
|
434
|
+
* @param overrides Scope-specific replacements, e.g. for a parallel branch.
|
|
339
435
|
* @returns A step executor environment bound to this runner.
|
|
340
|
-
* @throws When the workflow context is missing.
|
|
436
|
+
* @throws When the workflow context or runtime control is missing.
|
|
341
437
|
*/
|
|
342
|
-
createExecutorEnv(overrides = {}) {
|
|
438
|
+
createExecutorEnv(pass, overrides = {}) {
|
|
343
439
|
const context = overrides.context ?? this.context;
|
|
344
440
|
if (!context) {
|
|
345
441
|
throw new Error('Workflow context is not attached.');
|
|
346
442
|
}
|
|
443
|
+
const runtime = overrides.runtime ?? this.runtimeControl;
|
|
444
|
+
if (!runtime) {
|
|
445
|
+
throw new Error('Workflow runtime control is not initialized.');
|
|
446
|
+
}
|
|
347
447
|
const signal = overrides.signal ?? new AbortController().signal;
|
|
348
|
-
const setCurrentStep = overrides.setCurrentStep ??
|
|
349
|
-
((step) => {
|
|
350
|
-
this.currentStep = step;
|
|
351
|
-
});
|
|
352
|
-
const captureTaskOutput = overrides.captureTaskOutput ??
|
|
353
|
-
((task, state, result) => this.captureTaskOutput(task, state, result));
|
|
354
448
|
const executorEnv = {
|
|
355
449
|
compiled: this.compiled,
|
|
356
450
|
context,
|
|
357
451
|
signal,
|
|
358
452
|
runId: this.runId,
|
|
453
|
+
runtime,
|
|
454
|
+
resolutions: pass.resolutions,
|
|
455
|
+
rejectResume: (rejection) => {
|
|
456
|
+
pass.rejection = rejection;
|
|
457
|
+
},
|
|
359
458
|
buildInstanceStepInfo: (step, iterationStack) => this.buildInstanceStepInfo(step, iterationStack),
|
|
360
459
|
markSnapshot: (step, status, reason) => this.markSnapshot(step, status, reason),
|
|
361
460
|
recordStepExecution: (step, update) => this.recordStepExecution(step, update),
|
|
362
461
|
emit: (event, payload) => this.emit(event, payload),
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
}
|
|
368
|
-
return this.runtimeControl.beginStepExecution(stepId);
|
|
369
|
-
},
|
|
370
|
-
waitForStepSuspension: (stepId) => {
|
|
371
|
-
if (!this.runtimeControl) {
|
|
372
|
-
throw new Error('Workflow runtime control is not initialized.');
|
|
373
|
-
}
|
|
374
|
-
return this.runtimeControl.waitForStepSuspension(stepId);
|
|
375
|
-
},
|
|
376
|
-
clearStepSuspensions: (stepId, error) => {
|
|
377
|
-
this.runtimeControl?.clearStepSuspensions(stepId, error);
|
|
378
|
-
},
|
|
379
|
-
primeStepResumeData: (stepId, resumeData) => {
|
|
380
|
-
this.runtimeControl?.primeStepResumeData(stepId, resumeData);
|
|
381
|
-
},
|
|
382
|
-
prepareStepReplay: (seed) => {
|
|
383
|
-
this.runtimeControl?.prepareStepReplay(seed);
|
|
384
|
-
},
|
|
385
|
-
recordStepSuspendResult: (params) => {
|
|
386
|
-
this.runtimeControl?.recordStepSuspendResult(params);
|
|
387
|
-
},
|
|
388
|
-
captureTaskOutput,
|
|
389
|
-
executeFlow: (steps, state, path, startIndex) => this.executeFlow(steps, state, path, startIndex, executorEnv),
|
|
390
|
-
executeStep: (step, state, path) => this.executeStep(step, state, path, executorEnv),
|
|
391
|
-
fork: (forkOverrides) => this.createExecutorEnv({
|
|
462
|
+
captureTaskOutput: (task, state, result) => this.captureTaskOutput(task, state, result),
|
|
463
|
+
executeFlow: (steps, state, path, frame) => this.executeFlow(steps, state, path, frame, executorEnv),
|
|
464
|
+
executeStep: (step, state, path, frame) => this.executeStep(step, state, path, frame, executorEnv),
|
|
465
|
+
fork: (forkOverrides) => this.createExecutorEnv(pass, {
|
|
392
466
|
context: forkOverrides.context ?? context,
|
|
393
467
|
signal: forkOverrides.signal ?? signal,
|
|
394
|
-
|
|
395
|
-
captureTaskOutput: forkOverrides.captureTaskOutput ?? captureTaskOutput,
|
|
468
|
+
runtime: forkOverrides.runtime ?? runtime,
|
|
396
469
|
}),
|
|
397
470
|
};
|
|
398
471
|
return executorEnv;
|
|
399
472
|
}
|
|
400
473
|
/**
|
|
401
|
-
*
|
|
402
|
-
*
|
|
403
|
-
* @returns Dependency bag for suspension rebuilders.
|
|
404
|
-
*/
|
|
405
|
-
createSuspensionRebuilderDeps() {
|
|
406
|
-
return {
|
|
407
|
-
compiled: this.compiled,
|
|
408
|
-
context: this.context,
|
|
409
|
-
runId: this.runId,
|
|
410
|
-
createExecutorEnv: () => this.createExecutorEnv(),
|
|
411
|
-
buildInstanceStepInfo: (step, iterationStack) => this.buildInstanceStepInfo(step, iterationStack),
|
|
412
|
-
captureTaskOutput: (task, state, result) => this.captureTaskOutput(task, state, result),
|
|
413
|
-
markSnapshot: (step, status, reason) => this.markSnapshot(step, status, reason),
|
|
414
|
-
emit: (event, payload) => this.emit(event, payload),
|
|
415
|
-
executeFlow: (steps, state, path, startIndex) => this.executeFlow(steps, state, path, startIndex),
|
|
416
|
-
};
|
|
417
|
-
}
|
|
418
|
-
/**
|
|
419
|
-
* Walk a list of compiled steps, threading state and returning a suspension when encountered.
|
|
474
|
+
* Walk a list of compiled steps, threading state and returning a frame when
|
|
475
|
+
* one of them suspends.
|
|
420
476
|
*
|
|
421
477
|
* @param steps The steps to execute sequentially.
|
|
422
478
|
* @param state Mutable execution state shared across steps.
|
|
423
479
|
* @param path Path tokens leading to the current step for tracing.
|
|
424
|
-
* @param
|
|
425
|
-
* @
|
|
480
|
+
* @param frame Frame of a previous suspension within these steps.
|
|
481
|
+
* @param env Executor environment of the current scope.
|
|
482
|
+
* @returns A frame if execution pauses, otherwise void.
|
|
426
483
|
*/
|
|
427
|
-
async executeFlow(steps, state, path,
|
|
428
|
-
|
|
429
|
-
|
|
484
|
+
async executeFlow(steps, state, path, frame, env) {
|
|
485
|
+
if (frame) {
|
|
486
|
+
state.accumulator = frame.accumulator;
|
|
487
|
+
}
|
|
488
|
+
for (let index = frame?.index ?? 0; index < steps.length; index += 1) {
|
|
430
489
|
(0, errors_1.throwIfAborted)(env.signal);
|
|
431
|
-
const
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
490
|
+
const child = await this.executeStep(steps[index], state, [...path, index], frame && index === frame.index ? frame.child : undefined, env);
|
|
491
|
+
if (child) {
|
|
492
|
+
return {
|
|
493
|
+
kind: 'sequence',
|
|
494
|
+
index,
|
|
495
|
+
accumulator: state.accumulator,
|
|
496
|
+
child,
|
|
497
|
+
};
|
|
436
498
|
}
|
|
437
499
|
}
|
|
438
500
|
return undefined;
|
|
@@ -443,19 +505,22 @@ class WorkflowRunner {
|
|
|
443
505
|
* @param step The step to run.
|
|
444
506
|
* @param state The shared execution state.
|
|
445
507
|
* @param path Tokens describing the location of the step in the workflow.
|
|
446
|
-
* @
|
|
508
|
+
* @param frame Frame of a previous suspension of this step.
|
|
509
|
+
* @param env Executor environment of the current scope.
|
|
510
|
+
* @returns A frame if the step pauses execution, otherwise void.
|
|
447
511
|
*/
|
|
448
|
-
async executeStep(step, state, path, env
|
|
512
|
+
async executeStep(step, state, path, frame, env) {
|
|
449
513
|
(0, errors_1.throwIfAborted)(env.signal);
|
|
514
|
+
(0, checkpoint_1.assertFrameMatchesStep)(frame, step, path);
|
|
450
515
|
switch (step.type) {
|
|
451
516
|
case workflow_event_emitter_1.StepType.Task:
|
|
452
|
-
return (0, task_executor_1.executeTaskStep)(env, step, state, path);
|
|
517
|
+
return (0, task_executor_1.executeTaskStep)(env, step, state, path, frame);
|
|
453
518
|
case workflow_event_emitter_1.StepType.Parallel:
|
|
454
|
-
return (0, parallel_executor_1.executeParallel)(env, step, state, path);
|
|
519
|
+
return (0, parallel_executor_1.executeParallel)(env, step, state, path, frame);
|
|
455
520
|
case workflow_event_emitter_1.StepType.Conditional:
|
|
456
|
-
return (0, conditional_executor_1.executeConditional)(env, step, state, path);
|
|
521
|
+
return (0, conditional_executor_1.executeConditional)(env, step, state, path, frame);
|
|
457
522
|
case workflow_event_emitter_1.StepType.Loop:
|
|
458
|
-
return (0, loop_executor_1.executeLoop)(env, step, state, path);
|
|
523
|
+
return (0, loop_executor_1.executeLoop)(env, step, state, path, frame);
|
|
459
524
|
}
|
|
460
525
|
}
|
|
461
526
|
/**
|
package/dist/cjs/workflow.js
CHANGED
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
8
8
|
exports.Workflow = exports.WorkflowRunner = exports.WorkflowEventEmitter = exports.compileWorkflow = void 0;
|
|
9
9
|
const yaml_1 = require("yaml");
|
|
10
|
+
const checkpoint_1 = require("./checkpoint");
|
|
10
11
|
const context_1 = require("./context");
|
|
11
12
|
const dsl_types_1 = require("./dsl.types");
|
|
12
13
|
const workflow_definition_1 = require("./utils/workflow-definition");
|
|
@@ -20,12 +21,11 @@ Object.defineProperty(exports, "WorkflowEventEmitter", { enumerable: true, get:
|
|
|
20
21
|
var workflow_runner_2 = require("./workflow-runner");
|
|
21
22
|
Object.defineProperty(exports, "WorkflowRunner", { enumerable: true, get: function () { return workflow_runner_2.WorkflowRunner; } });
|
|
22
23
|
class WorkflowRunSuspendedError extends Error {
|
|
23
|
-
constructor(
|
|
24
|
-
|
|
24
|
+
constructor(waits) {
|
|
25
|
+
const steps = waits.map(({ step, reason }) => reason ? `${step.id} (${reason})` : step.id);
|
|
26
|
+
super(`Workflow run suspended at ${steps.join(', ')}`);
|
|
25
27
|
this.name = 'WorkflowRunSuspendedError';
|
|
26
|
-
this.
|
|
27
|
-
this.reason = options?.reason;
|
|
28
|
-
this.data = options?.data;
|
|
28
|
+
this.waits = waits;
|
|
29
29
|
}
|
|
30
30
|
}
|
|
31
31
|
const getTaskNameFromStep = (step) => {
|
|
@@ -224,10 +224,7 @@ class Workflow {
|
|
|
224
224
|
: new Error(String(result.error));
|
|
225
225
|
}
|
|
226
226
|
context.attachWorkflowRuntime(undefined);
|
|
227
|
-
throw new WorkflowRunSuspendedError(result.
|
|
228
|
-
reason: result.reason,
|
|
229
|
-
data: result.data,
|
|
230
|
-
});
|
|
227
|
+
throw new WorkflowRunSuspendedError(result.waits);
|
|
231
228
|
}
|
|
232
229
|
/**
|
|
233
230
|
* Construct a runner without executing, allowing hosts to manage start/resume manually.
|
|
@@ -236,10 +233,25 @@ class Workflow {
|
|
|
236
233
|
return new workflow_runner_1.WorkflowRunner(this.compiled, options);
|
|
237
234
|
}
|
|
238
235
|
/**
|
|
239
|
-
*
|
|
236
|
+
* Decide whether a persisted checkpoint can resume against this workflow,
|
|
237
|
+
* without running anything. Call it before claiming a wait.
|
|
238
|
+
*
|
|
239
|
+
* @param checkpoint The checkpoint, as persisted.
|
|
240
|
+
* @param options.waitId Wait the caller is about to resume.
|
|
241
|
+
* @param options.resumeData Payload the caller is about to resume with,
|
|
242
|
+
* checked against what the wait accepts when the key is present.
|
|
243
|
+
* @returns The parsed checkpoint, or the typed reason it cannot resume.
|
|
244
|
+
*/
|
|
245
|
+
validateCheckpoint(checkpoint, options) {
|
|
246
|
+
return (0, checkpoint_1.validateCheckpoint)(this.compiled, checkpoint, options);
|
|
247
|
+
}
|
|
248
|
+
/**
|
|
249
|
+
* Restore a suspended runner from its persisted checkpoint, useful after restarts.
|
|
250
|
+
*
|
|
251
|
+
* @throws {WorkflowResumeError} When the checkpoint cannot resume against this workflow.
|
|
240
252
|
*/
|
|
241
|
-
|
|
242
|
-
return workflow_runner_1.WorkflowRunner.
|
|
253
|
+
buildRunnerFromCheckpoint(options) {
|
|
254
|
+
return workflow_runner_1.WorkflowRunner.fromCheckpoint(this.compiled, options);
|
|
243
255
|
}
|
|
244
256
|
}
|
|
245
257
|
exports.Workflow = Workflow;
|
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
*/
|
|
6
6
|
import { z } from 'zod';
|
|
7
7
|
import { BaseSettingsSchema } from '../dsl.types';
|
|
8
|
-
import { throwIfAborted } from '../errors';
|
|
8
|
+
import { isNonDeterministicWorkflowError, isWorkflowResumeRejectedError, throwIfAborted, } from '../errors';
|
|
9
9
|
import { assertSnakeCaseName } from '../utils/naming';
|
|
10
10
|
import { sleep, withTimeout } from '../utils/timeout';
|
|
11
11
|
const BASE_SETTINGS_KEYS = Object.keys(BaseSettingsSchema.shape);
|
|
@@ -86,10 +86,18 @@ export class AbstractAction {
|
|
|
86
86
|
const maxDelayMs = retrySettings.max_delay_ms;
|
|
87
87
|
const jitter = retrySettings.jitter;
|
|
88
88
|
const multiplier = retrySettings.multiplier;
|
|
89
|
+
// Suspend keys are positional within the body, so every attempt has to
|
|
90
|
+
// start from where this run did: otherwise a retry asks for `index:2`
|
|
91
|
+
// where the first attempt resolved `index:1`, and the step suspends on a
|
|
92
|
+
// wait whose payload was already delivered.
|
|
93
|
+
const rewindSuspendCursor = context
|
|
94
|
+
?.getWorkflowRuntime?.()
|
|
95
|
+
?.markSuspendCursor?.();
|
|
89
96
|
while (attempt < maxAttempts) {
|
|
90
97
|
if (signal) {
|
|
91
98
|
throwIfAborted(signal);
|
|
92
99
|
}
|
|
100
|
+
rewindSuspendCursor?.();
|
|
93
101
|
try {
|
|
94
102
|
const result = await withTimeout(this.execute({
|
|
95
103
|
input,
|
|
@@ -102,7 +110,11 @@ export class AbstractAction {
|
|
|
102
110
|
}
|
|
103
111
|
catch (error) {
|
|
104
112
|
attempt += 1;
|
|
105
|
-
|
|
113
|
+
// A retry would read the same refused resume payload again, or replay
|
|
114
|
+
// the same body into the same mismatch with what it recorded.
|
|
115
|
+
if (attempt >= maxAttempts ||
|
|
116
|
+
isWorkflowResumeRejectedError(error) ||
|
|
117
|
+
isNonDeterministicWorkflowError(error)) {
|
|
106
118
|
throw error;
|
|
107
119
|
}
|
|
108
120
|
let delay = currentDelay;
|