@hexabot-ai/agentic 3.4.0 → 3.5.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/src/workflow-runner.ts
CHANGED
|
@@ -4,6 +4,21 @@
|
|
|
4
4
|
* Full terms: see LICENSE.md.
|
|
5
5
|
*/
|
|
6
6
|
|
|
7
|
+
import {
|
|
8
|
+
assertFrameMatchesStep,
|
|
9
|
+
CHECKPOINT_VERSION,
|
|
10
|
+
collectWaits,
|
|
11
|
+
selectWait,
|
|
12
|
+
validateCheckpoint,
|
|
13
|
+
type ConditionalFrame,
|
|
14
|
+
type LoopFrame,
|
|
15
|
+
type ParallelFrame,
|
|
16
|
+
type SequenceFrame,
|
|
17
|
+
type StepFrame,
|
|
18
|
+
type TaskFrame,
|
|
19
|
+
type WaitInfo,
|
|
20
|
+
type WorkflowCheckpoint,
|
|
21
|
+
} from './checkpoint';
|
|
7
22
|
import {
|
|
8
23
|
EWorkflowRunStatus,
|
|
9
24
|
type ActionSnapshot,
|
|
@@ -14,40 +29,59 @@ import {
|
|
|
14
29
|
type WorkflowSnapshot,
|
|
15
30
|
} from './context';
|
|
16
31
|
import { throwIfAborted } from './errors';
|
|
32
|
+
import { checkResumePayload } from './resume-payload';
|
|
17
33
|
import { RunnerRuntimeControl } from './runner-runtime-control';
|
|
18
34
|
import { executeConditional as runConditionalExecutor } from './step-executors/conditional-executor';
|
|
19
35
|
import { executeLoop as runLoopExecutor } from './step-executors/loop-executor';
|
|
20
36
|
import { executeParallel as runParallelExecutor } from './step-executors/parallel-executor';
|
|
21
|
-
import { wrapSuspensionContinuation } from './step-executors/suspension-continuation';
|
|
22
37
|
import { executeTaskStep as runTaskExecutor } from './step-executors/task-executor';
|
|
23
38
|
import type {
|
|
24
39
|
StepExecutorEnv,
|
|
25
40
|
StepExecutorEnvForkOverrides,
|
|
26
41
|
} from './step-executors/types';
|
|
27
|
-
import {
|
|
28
|
-
rebuildSuspension,
|
|
29
|
-
type SuspensionRebuilderDeps,
|
|
30
|
-
} from './suspension-rebuilder';
|
|
42
|
+
import { cloneAsJson } from './utils/clone';
|
|
31
43
|
import {
|
|
32
44
|
StepType,
|
|
33
45
|
type StepInfo,
|
|
34
46
|
type WorkflowEventMap,
|
|
35
47
|
} from './workflow-event-emitter';
|
|
48
|
+
import { fingerprintWorkflow } from './workflow-fingerprint';
|
|
36
49
|
import type {
|
|
37
50
|
CompiledStep,
|
|
38
51
|
CompiledTask,
|
|
39
52
|
CompiledWorkflow,
|
|
40
53
|
ExecutionState,
|
|
41
|
-
|
|
42
|
-
ResumeResult,
|
|
54
|
+
ResumeRejection,
|
|
43
55
|
RunnerResumeArgs,
|
|
44
56
|
RunnerStartArgs,
|
|
45
|
-
|
|
46
|
-
Suspension,
|
|
57
|
+
SuspendedResult,
|
|
47
58
|
WorkflowRunOptions,
|
|
59
|
+
WorkflowRunResult,
|
|
48
60
|
} from './workflow-types';
|
|
49
61
|
import { evaluateMapping } from './workflow-values';
|
|
50
62
|
|
|
63
|
+
/** One start or resume pass over the flow. */
|
|
64
|
+
type ExecutionPass = {
|
|
65
|
+
/** Resume payloads for the waits this pass satisfies, by wait id. */
|
|
66
|
+
resolutions: ReadonlyMap<string, unknown>;
|
|
67
|
+
/** Set when the resumed step refused its payload. */
|
|
68
|
+
rejection?: ResumeRejection;
|
|
69
|
+
};
|
|
70
|
+
|
|
71
|
+
/** What the runner reports about a run, put back when a resume is refused. */
|
|
72
|
+
type RunReport = {
|
|
73
|
+
state?: ExecutionState;
|
|
74
|
+
snapshots: Record<string, ActionSnapshot>;
|
|
75
|
+
stepLog: Record<string, StepExecutionRecord>;
|
|
76
|
+
};
|
|
77
|
+
|
|
78
|
+
/** The suspended run a resume pass starts from. */
|
|
79
|
+
type ResumedRun = {
|
|
80
|
+
checkpoint: WorkflowCheckpoint;
|
|
81
|
+
/** The report before the pass, restored if the payload is refused. */
|
|
82
|
+
report: RunReport;
|
|
83
|
+
};
|
|
84
|
+
|
|
51
85
|
/**
|
|
52
86
|
* Executes a compiled workflow definition, tracking state, suspensions, and event hooks.
|
|
53
87
|
* Create a new instance per execution to avoid leaking state between runs.
|
|
@@ -68,18 +102,12 @@ export class WorkflowRunner {
|
|
|
68
102
|
// Detailed execution records for each task step, used by UI/telemetry.
|
|
69
103
|
private stepLog: Record<string, StepExecutionRecord> = {};
|
|
70
104
|
|
|
71
|
-
//
|
|
72
|
-
private
|
|
105
|
+
// Checkpoint of the run while it is suspended awaiting external input.
|
|
106
|
+
private checkpoint?: WorkflowCheckpoint;
|
|
73
107
|
|
|
74
108
|
// Control surface exposed to actions to suspend/resume the workflow.
|
|
75
109
|
private runtimeControl?: RunnerRuntimeControl;
|
|
76
110
|
|
|
77
|
-
// Step currently being executed, used in event payloads and errors.
|
|
78
|
-
private currentStep?: StepInfo;
|
|
79
|
-
|
|
80
|
-
// Last payload provided to resume; exposed to actions via the context.
|
|
81
|
-
private lastResumeData?: unknown;
|
|
82
|
-
|
|
83
111
|
// Mutable execution state including input and outputs.
|
|
84
112
|
private state?: ExecutionState;
|
|
85
113
|
|
|
@@ -146,21 +174,13 @@ export class WorkflowRunner {
|
|
|
146
174
|
}
|
|
147
175
|
|
|
148
176
|
/**
|
|
149
|
-
* Read the
|
|
177
|
+
* Read the checkpoint of a suspended run: everything a host must persist to
|
|
178
|
+
* resume it later, in this process or another one. Treat it as read-only.
|
|
150
179
|
*
|
|
151
|
-
* @returns
|
|
180
|
+
* @returns The checkpoint while the run is suspended, otherwise undefined.
|
|
152
181
|
*/
|
|
153
|
-
|
|
154
|
-
return this.
|
|
155
|
-
}
|
|
156
|
-
|
|
157
|
-
/**
|
|
158
|
-
* Access the last payload supplied to a resume call.
|
|
159
|
-
*
|
|
160
|
-
* @returns The most recent resume data, or undefined if none.
|
|
161
|
-
*/
|
|
162
|
-
getLastResumeData(): unknown {
|
|
163
|
-
return this.lastResumeData;
|
|
182
|
+
getCheckpoint(): WorkflowCheckpoint | undefined {
|
|
183
|
+
return this.checkpoint;
|
|
164
184
|
}
|
|
165
185
|
|
|
166
186
|
/**
|
|
@@ -170,13 +190,11 @@ export class WorkflowRunner {
|
|
|
170
190
|
* @param args Input payload and context to seed execution.
|
|
171
191
|
* @returns Execution result including status and snapshot.
|
|
172
192
|
*/
|
|
173
|
-
async start(args: RunnerStartArgs): Promise<
|
|
193
|
+
async start(args: RunnerStartArgs): Promise<WorkflowRunResult> {
|
|
174
194
|
this.status = EWorkflowRunStatus.RUNNING;
|
|
175
195
|
this.snapshots = {};
|
|
176
196
|
this.stepLog = {};
|
|
177
|
-
this.
|
|
178
|
-
this.lastResumeData = undefined;
|
|
179
|
-
this.currentStep = undefined;
|
|
197
|
+
this.checkpoint = undefined;
|
|
180
198
|
this.context = args.context;
|
|
181
199
|
this.state = {
|
|
182
200
|
input: this.compiled.inputParser.parse(args.inputData ?? {}),
|
|
@@ -184,85 +202,163 @@ export class WorkflowRunner {
|
|
|
184
202
|
iterationStack: [],
|
|
185
203
|
};
|
|
186
204
|
|
|
187
|
-
this.runtimeControl = new RunnerRuntimeControl(
|
|
205
|
+
this.runtimeControl = new RunnerRuntimeControl();
|
|
188
206
|
this.context.attachWorkflowRuntime(this.runtimeControl);
|
|
189
207
|
|
|
190
208
|
this.emit('hook:workflow:start', { runId: this.runId });
|
|
191
209
|
|
|
192
|
-
|
|
193
|
-
if (!state) {
|
|
194
|
-
throw new Error('Workflow state not initialized.');
|
|
195
|
-
}
|
|
196
|
-
|
|
197
|
-
const env = this.createExecutorEnv();
|
|
198
|
-
|
|
199
|
-
return this.runExecution(() =>
|
|
200
|
-
this.executeFlow(this.compiled.flow, state, [], 0, env),
|
|
201
|
-
);
|
|
210
|
+
return this.runExecution(new Map());
|
|
202
211
|
}
|
|
203
212
|
|
|
204
213
|
/**
|
|
205
|
-
* Resume a
|
|
214
|
+
* Resume a suspended workflow by satisfying one of its open waits.
|
|
206
215
|
*
|
|
207
|
-
*
|
|
216
|
+
* Execution re-enters the checkpoint's frames: completed work is skipped,
|
|
217
|
+
* the resolved step re-runs its action body, and waits left untouched stay
|
|
218
|
+
* parked.
|
|
219
|
+
*
|
|
220
|
+
* A payload the wait does not accept is refused, first against the wait's
|
|
221
|
+
* `accepts` JSON Schema without running anything, then by the action body.
|
|
222
|
+
* Either way the result is suspended on the same waits and carries
|
|
223
|
+
* `rejection`, and the checkpoint, snapshot and step log are left as they
|
|
224
|
+
* were. Events a refusing body emitted are not withdrawn, and its side
|
|
225
|
+
* effects, including writes to context state, are not undone.
|
|
226
|
+
*
|
|
227
|
+
* @param args Resume payload and, when several waits are open, the wait it satisfies.
|
|
208
228
|
* @returns Execution result including status and snapshot.
|
|
229
|
+
* @throws {WorkflowWaitNotFoundError} When `waitId` is not an open wait.
|
|
230
|
+
* @throws {WorkflowWaitAmbiguousError} When several waits are open and no
|
|
231
|
+
* `waitId` is given.
|
|
209
232
|
*/
|
|
210
|
-
async resume(args: RunnerResumeArgs): Promise<
|
|
211
|
-
if (this.status !== EWorkflowRunStatus.SUSPENDED || !this.
|
|
233
|
+
async resume(args: RunnerResumeArgs): Promise<WorkflowRunResult> {
|
|
234
|
+
if (this.status !== EWorkflowRunStatus.SUSPENDED || !this.checkpoint) {
|
|
212
235
|
throw new Error('Cannot resume a workflow that is not suspended.');
|
|
213
236
|
}
|
|
214
237
|
|
|
215
|
-
if (!this.context
|
|
238
|
+
if (!this.context) {
|
|
216
239
|
throw new Error('Workflow state is not initialized.');
|
|
217
240
|
}
|
|
218
241
|
|
|
219
|
-
|
|
220
|
-
|
|
242
|
+
const wait = selectWait(this.checkpoint.waits, args.waitId);
|
|
243
|
+
const payload = checkResumePayload(wait, args.resumeData);
|
|
244
|
+
const result = payload.ok
|
|
245
|
+
? await this.resolveWait(wait, payload.value)
|
|
246
|
+
: this.keepWaiting(this.checkpoint, {
|
|
247
|
+
waitId: wait.waitId,
|
|
248
|
+
error: payload.error,
|
|
249
|
+
});
|
|
250
|
+
if (result.status === EWorkflowRunStatus.SUSPENDED && result.rejection) {
|
|
251
|
+
this.emit('hook:workflow:resume_rejected', {
|
|
252
|
+
runId: this.runId,
|
|
253
|
+
wait,
|
|
254
|
+
resumeData: args.resumeData,
|
|
255
|
+
error: result.rejection.error,
|
|
256
|
+
});
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
return result;
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
/**
|
|
263
|
+
* Run the pass that resolves one wait with an accepted payload.
|
|
264
|
+
*
|
|
265
|
+
* @param wait The wait being resolved.
|
|
266
|
+
* @param recorded The payload as the checkpoint records it.
|
|
267
|
+
* @returns Execution result including status and snapshot.
|
|
268
|
+
*/
|
|
269
|
+
private async resolveWait(
|
|
270
|
+
wait: WaitInfo,
|
|
271
|
+
recorded: unknown,
|
|
272
|
+
): Promise<WorkflowRunResult> {
|
|
273
|
+
const checkpoint = this.checkpoint;
|
|
274
|
+
if (!checkpoint) {
|
|
275
|
+
throw new Error('Cannot resume a workflow that is not suspended.');
|
|
276
|
+
}
|
|
221
277
|
|
|
222
|
-
const
|
|
278
|
+
const report: RunReport = {
|
|
279
|
+
state: this.state,
|
|
280
|
+
snapshots: { ...this.snapshots },
|
|
281
|
+
stepLog: { ...this.stepLog },
|
|
282
|
+
};
|
|
283
|
+
this.status = EWorkflowRunStatus.RUNNING;
|
|
284
|
+
this.context?.attachWorkflowRuntime(this.runtimeControl);
|
|
223
285
|
|
|
224
|
-
return this.runExecution(
|
|
286
|
+
return this.runExecution(new Map([[wait.waitId, recorded]]), {
|
|
287
|
+
checkpoint,
|
|
288
|
+
report,
|
|
289
|
+
});
|
|
225
290
|
}
|
|
226
291
|
|
|
227
292
|
/**
|
|
228
|
-
*
|
|
293
|
+
* Run the flow from the top, or from a checkpoint, and normalize
|
|
294
|
+
* suspension, finish, and failure handling.
|
|
229
295
|
*
|
|
230
|
-
* @param
|
|
296
|
+
* @param resolutions Resume payloads for the waits this pass satisfies.
|
|
297
|
+
* @param resumed Suspended run to resume from; omitted on start.
|
|
231
298
|
* @returns Result of the execution attempt.
|
|
232
299
|
*/
|
|
233
300
|
private async runExecution(
|
|
234
|
-
|
|
235
|
-
|
|
301
|
+
resolutions: ReadonlyMap<string, unknown>,
|
|
302
|
+
resumed?: ResumedRun,
|
|
303
|
+
): Promise<WorkflowRunResult> {
|
|
304
|
+
const pass: ExecutionPass = { resolutions };
|
|
305
|
+
|
|
236
306
|
try {
|
|
237
|
-
|
|
307
|
+
// In-process and durable resumes start from the same detached JSON
|
|
308
|
+
// copy, so both see exactly what a host would have persisted.
|
|
309
|
+
const from = resumed ? cloneAsJson(resumed.checkpoint) : undefined;
|
|
310
|
+
if (from) {
|
|
311
|
+
this.state = {
|
|
312
|
+
input: from.input,
|
|
313
|
+
output: from.output,
|
|
314
|
+
iterationStack: [],
|
|
315
|
+
};
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
const state = this.state;
|
|
319
|
+
if (!state) {
|
|
320
|
+
throw new Error('Workflow state not initialized.');
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
const root = await this.executeFlow(
|
|
324
|
+
this.compiled.flow,
|
|
325
|
+
state,
|
|
326
|
+
[],
|
|
327
|
+
from?.root,
|
|
328
|
+
this.createExecutorEnv(pass),
|
|
329
|
+
);
|
|
330
|
+
|
|
331
|
+
// Only the refusing step ran in this pass, and it did not complete, so
|
|
332
|
+
// the run is put back as the checkpoint it started from describes it.
|
|
333
|
+
if (pass.rejection && resumed) {
|
|
334
|
+
this.state = resumed.report.state;
|
|
335
|
+
this.snapshots = resumed.report.snapshots;
|
|
336
|
+
this.stepLog = resumed.report.stepLog;
|
|
337
|
+
|
|
338
|
+
return this.keepWaiting(resumed.checkpoint, pass.rejection);
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
if (root) {
|
|
342
|
+
const next = this.buildCheckpoint(state, root);
|
|
238
343
|
|
|
239
|
-
|
|
240
|
-
this.suspension = suspension;
|
|
344
|
+
this.checkpoint = next;
|
|
241
345
|
this.status = EWorkflowRunStatus.SUSPENDED;
|
|
242
346
|
this.emit('hook:workflow:suspended', {
|
|
243
347
|
runId: this.runId,
|
|
244
|
-
|
|
245
|
-
reason: suspension.reason,
|
|
246
|
-
data: suspension.data,
|
|
348
|
+
waits: next.waits,
|
|
247
349
|
});
|
|
248
350
|
|
|
249
351
|
return {
|
|
250
352
|
status: EWorkflowRunStatus.SUSPENDED,
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
data: suspension.data,
|
|
254
|
-
stepExecId: suspension.stepExecId,
|
|
255
|
-
suspendIndex: suspension.suspendIndex,
|
|
256
|
-
suspendKey: suspension.suspendKey,
|
|
257
|
-
awaitResults: suspension.awaitResults,
|
|
353
|
+
waits: next.waits,
|
|
354
|
+
checkpoint: next,
|
|
258
355
|
snapshot: this.getSnapshot(),
|
|
259
356
|
};
|
|
260
357
|
}
|
|
261
358
|
|
|
262
359
|
const output = await this.evaluateWorkflowOutputs();
|
|
263
360
|
this.status = EWorkflowRunStatus.FINISHED;
|
|
264
|
-
this.
|
|
265
|
-
this.currentStep = undefined;
|
|
361
|
+
this.checkpoint = undefined;
|
|
266
362
|
this.emit('hook:workflow:finish', { runId: this.runId, output });
|
|
267
363
|
if (!this.context) {
|
|
268
364
|
throw new Error('Workflow context is not attached.');
|
|
@@ -276,7 +372,7 @@ export class WorkflowRunner {
|
|
|
276
372
|
};
|
|
277
373
|
} catch (error) {
|
|
278
374
|
this.status = EWorkflowRunStatus.FAILED;
|
|
279
|
-
this.
|
|
375
|
+
this.checkpoint = undefined;
|
|
280
376
|
this.emit('hook:workflow:failure', { runId: this.runId, error });
|
|
281
377
|
this.context?.attachWorkflowRuntime(undefined);
|
|
282
378
|
|
|
@@ -289,67 +385,106 @@ export class WorkflowRunner {
|
|
|
289
385
|
}
|
|
290
386
|
|
|
291
387
|
/**
|
|
292
|
-
*
|
|
388
|
+
* Leave the run suspended on `checkpoint` after a resume payload was
|
|
389
|
+
* refused.
|
|
390
|
+
*
|
|
391
|
+
* @param checkpoint The checkpoint the run was suspended on.
|
|
392
|
+
* @param rejection The refused wait and why.
|
|
393
|
+
* @returns The suspended result, carrying the rejection.
|
|
394
|
+
*/
|
|
395
|
+
private keepWaiting(
|
|
396
|
+
checkpoint: WorkflowCheckpoint,
|
|
397
|
+
rejection: ResumeRejection,
|
|
398
|
+
): SuspendedResult {
|
|
399
|
+
this.checkpoint = checkpoint;
|
|
400
|
+
this.status = EWorkflowRunStatus.SUSPENDED;
|
|
401
|
+
|
|
402
|
+
return {
|
|
403
|
+
status: EWorkflowRunStatus.SUSPENDED,
|
|
404
|
+
waits: checkpoint.waits,
|
|
405
|
+
checkpoint,
|
|
406
|
+
snapshot: this.getSnapshot(),
|
|
407
|
+
rejection,
|
|
408
|
+
};
|
|
409
|
+
}
|
|
410
|
+
|
|
411
|
+
/**
|
|
412
|
+
* Snapshot the suspended run as a detached JSON checkpoint.
|
|
413
|
+
*
|
|
414
|
+
* The checkpoint goes through the same JSON round trip a host applies when
|
|
415
|
+
* persisting it, so a resumed run sees the same values in process and
|
|
416
|
+
* after a restore.
|
|
417
|
+
*
|
|
418
|
+
* @param state Root execution state at suspension time.
|
|
419
|
+
* @param root Frame returned by the top-level flow.
|
|
420
|
+
* @returns The checkpoint to hand to the host.
|
|
421
|
+
* @throws When the run's state cannot be encoded as JSON.
|
|
422
|
+
*/
|
|
423
|
+
private buildCheckpoint(
|
|
424
|
+
state: ExecutionState,
|
|
425
|
+
root: SequenceFrame,
|
|
426
|
+
): WorkflowCheckpoint {
|
|
427
|
+
try {
|
|
428
|
+
return cloneAsJson({
|
|
429
|
+
version: CHECKPOINT_VERSION,
|
|
430
|
+
fingerprint: fingerprintWorkflow(this.compiled),
|
|
431
|
+
input: state.input,
|
|
432
|
+
output: state.output,
|
|
433
|
+
root,
|
|
434
|
+
waits: collectWaits(root),
|
|
435
|
+
});
|
|
436
|
+
} catch (error) {
|
|
437
|
+
const reason = error instanceof Error ? error.message : String(error);
|
|
438
|
+
|
|
439
|
+
throw new Error(
|
|
440
|
+
`Cannot checkpoint the suspended run: its state is not JSON-serializable (${reason}).`,
|
|
441
|
+
);
|
|
442
|
+
}
|
|
443
|
+
}
|
|
444
|
+
|
|
445
|
+
/**
|
|
446
|
+
* Restore a suspended run from its persisted checkpoint, typically in a
|
|
447
|
+
* different process than the one that suspended it.
|
|
293
448
|
*
|
|
294
449
|
* @param compiled The compiled workflow definition.
|
|
295
|
-
* @param options
|
|
296
|
-
* @
|
|
450
|
+
* @param options.checkpoint Checkpoint returned when the run suspended.
|
|
451
|
+
* @param options.context Freshly hydrated workflow context.
|
|
452
|
+
* @param options.snapshot Persisted action snapshot, to keep reporting past steps.
|
|
453
|
+
* @param options.runId Run identifier propagated through events.
|
|
454
|
+
* @returns A suspended runner ready for {@link resume}.
|
|
455
|
+
* @throws {WorkflowResumeError} When the checkpoint cannot resume against `compiled`.
|
|
297
456
|
*/
|
|
298
|
-
static
|
|
457
|
+
static fromCheckpoint(
|
|
299
458
|
compiled: CompiledWorkflow,
|
|
300
459
|
options: {
|
|
301
|
-
|
|
460
|
+
checkpoint: unknown;
|
|
302
461
|
context: BaseWorkflowContext;
|
|
303
|
-
snapshot
|
|
304
|
-
suspension?: PersistedSuspension;
|
|
462
|
+
snapshot?: WorkflowSnapshot;
|
|
305
463
|
runId?: string;
|
|
306
|
-
lastResumeData?: unknown;
|
|
307
464
|
},
|
|
308
|
-
):
|
|
465
|
+
): WorkflowRunner {
|
|
466
|
+
const validation = validateCheckpoint(compiled, options.checkpoint);
|
|
467
|
+
if (!validation.ok) {
|
|
468
|
+
throw validation.error;
|
|
469
|
+
}
|
|
470
|
+
|
|
471
|
+
const checkpoint = validation.checkpoint;
|
|
309
472
|
const runner = new WorkflowRunner(compiled, {
|
|
310
473
|
runId: options.runId,
|
|
311
474
|
});
|
|
312
475
|
|
|
476
|
+
runner.checkpoint = checkpoint;
|
|
313
477
|
runner.state = {
|
|
314
|
-
input:
|
|
315
|
-
output:
|
|
316
|
-
|
|
317
|
-
accumulator: options.state.accumulator,
|
|
318
|
-
iterationStack: [...(options.state.iterationStack ?? [])],
|
|
478
|
+
input: checkpoint.input,
|
|
479
|
+
output: checkpoint.output,
|
|
480
|
+
iterationStack: [],
|
|
319
481
|
};
|
|
320
482
|
runner.context = options.context;
|
|
321
|
-
runner.snapshots = options.snapshot
|
|
322
|
-
runner.
|
|
323
|
-
runner.
|
|
324
|
-
runner.lastResumeData = options.lastResumeData;
|
|
325
|
-
runner.runtimeControl = new RunnerRuntimeControl(runner);
|
|
483
|
+
runner.snapshots = { ...(options.snapshot?.actions ?? {}) };
|
|
484
|
+
runner.status = EWorkflowRunStatus.SUSPENDED;
|
|
485
|
+
runner.runtimeControl = new RunnerRuntimeControl();
|
|
326
486
|
options.context.attachWorkflowRuntime(runner.runtimeControl);
|
|
327
487
|
|
|
328
|
-
if (options.suspension) {
|
|
329
|
-
const suspension = rebuildSuspension(
|
|
330
|
-
runner.createSuspensionRebuilderDeps(),
|
|
331
|
-
{
|
|
332
|
-
state: runner.state,
|
|
333
|
-
stepId: options.suspension.stepId,
|
|
334
|
-
reason: options.suspension.reason ?? undefined,
|
|
335
|
-
data: options.suspension.data,
|
|
336
|
-
stepExecId: options.suspension.stepExecId,
|
|
337
|
-
suspendIndex: options.suspension.suspendIndex,
|
|
338
|
-
suspendKey: options.suspension.suspendKey,
|
|
339
|
-
awaitResults: options.suspension.awaitResults,
|
|
340
|
-
},
|
|
341
|
-
);
|
|
342
|
-
|
|
343
|
-
if (!suspension) {
|
|
344
|
-
throw new Error(
|
|
345
|
-
`Unable to rebuild suspension for step ${options.suspension.stepId}`,
|
|
346
|
-
);
|
|
347
|
-
}
|
|
348
|
-
|
|
349
|
-
runner.suspension = suspension;
|
|
350
|
-
runner.status = EWorkflowRunStatus.SUSPENDED;
|
|
351
|
-
}
|
|
352
|
-
|
|
353
488
|
return runner;
|
|
354
489
|
}
|
|
355
490
|
|
|
@@ -465,10 +600,13 @@ export class WorkflowRunner {
|
|
|
465
600
|
/**
|
|
466
601
|
* Construct the environment object passed to step executors.
|
|
467
602
|
*
|
|
603
|
+
* @param pass The execution pass, shared by every scope it forks.
|
|
604
|
+
* @param overrides Scope-specific replacements, e.g. for a parallel branch.
|
|
468
605
|
* @returns A step executor environment bound to this runner.
|
|
469
|
-
* @throws When the workflow context is missing.
|
|
606
|
+
* @throws When the workflow context or runtime control is missing.
|
|
470
607
|
*/
|
|
471
608
|
private createExecutorEnv(
|
|
609
|
+
pass: ExecutionPass,
|
|
472
610
|
overrides: StepExecutorEnvForkOverrides = {},
|
|
473
611
|
): StepExecutorEnv {
|
|
474
612
|
const context = overrides.context ?? this.context;
|
|
@@ -476,21 +614,22 @@ export class WorkflowRunner {
|
|
|
476
614
|
throw new Error('Workflow context is not attached.');
|
|
477
615
|
}
|
|
478
616
|
|
|
617
|
+
const runtime = overrides.runtime ?? this.runtimeControl;
|
|
618
|
+
if (!runtime) {
|
|
619
|
+
throw new Error('Workflow runtime control is not initialized.');
|
|
620
|
+
}
|
|
621
|
+
|
|
479
622
|
const signal = overrides.signal ?? new AbortController().signal;
|
|
480
|
-
const setCurrentStep =
|
|
481
|
-
overrides.setCurrentStep ??
|
|
482
|
-
((step?: StepInfo) => {
|
|
483
|
-
this.currentStep = step;
|
|
484
|
-
});
|
|
485
|
-
const captureTaskOutput =
|
|
486
|
-
overrides.captureTaskOutput ??
|
|
487
|
-
((task: CompiledTask, state: ExecutionState, result: unknown) =>
|
|
488
|
-
this.captureTaskOutput(task, state, result));
|
|
489
623
|
const executorEnv: StepExecutorEnv = {
|
|
490
624
|
compiled: this.compiled,
|
|
491
625
|
context,
|
|
492
626
|
signal,
|
|
493
627
|
runId: this.runId,
|
|
628
|
+
runtime,
|
|
629
|
+
resolutions: pass.resolutions,
|
|
630
|
+
rejectResume: (rejection) => {
|
|
631
|
+
pass.rejection = rejection;
|
|
632
|
+
},
|
|
494
633
|
buildInstanceStepInfo: (step, iterationStack) =>
|
|
495
634
|
this.buildInstanceStepInfo(step, iterationStack),
|
|
496
635
|
markSnapshot: (step, status, reason) =>
|
|
@@ -498,45 +637,17 @@ export class WorkflowRunner {
|
|
|
498
637
|
recordStepExecution: (step, update) =>
|
|
499
638
|
this.recordStepExecution(step, update),
|
|
500
639
|
emit: (event, payload) => this.emit(event, payload),
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
return this.runtimeControl.beginStepExecution(stepId);
|
|
508
|
-
},
|
|
509
|
-
waitForStepSuspension: (stepId) => {
|
|
510
|
-
if (!this.runtimeControl) {
|
|
511
|
-
throw new Error('Workflow runtime control is not initialized.');
|
|
512
|
-
}
|
|
513
|
-
|
|
514
|
-
return this.runtimeControl.waitForStepSuspension(stepId);
|
|
515
|
-
},
|
|
516
|
-
clearStepSuspensions: (stepId, error) => {
|
|
517
|
-
this.runtimeControl?.clearStepSuspensions(stepId, error);
|
|
518
|
-
},
|
|
519
|
-
primeStepResumeData: (stepId, resumeData) => {
|
|
520
|
-
this.runtimeControl?.primeStepResumeData(stepId, resumeData);
|
|
521
|
-
},
|
|
522
|
-
prepareStepReplay: (seed) => {
|
|
523
|
-
this.runtimeControl?.prepareStepReplay(seed);
|
|
524
|
-
},
|
|
525
|
-
recordStepSuspendResult: (params) => {
|
|
526
|
-
this.runtimeControl?.recordStepSuspendResult(params);
|
|
527
|
-
},
|
|
528
|
-
captureTaskOutput,
|
|
529
|
-
executeFlow: (steps, state, path, startIndex) =>
|
|
530
|
-
this.executeFlow(steps, state, path, startIndex, executorEnv),
|
|
531
|
-
executeStep: (step, state, path) =>
|
|
532
|
-
this.executeStep(step, state, path, executorEnv),
|
|
640
|
+
captureTaskOutput: (task, state, result) =>
|
|
641
|
+
this.captureTaskOutput(task, state, result),
|
|
642
|
+
executeFlow: (steps, state, path, frame) =>
|
|
643
|
+
this.executeFlow(steps, state, path, frame, executorEnv),
|
|
644
|
+
executeStep: (step, state, path, frame) =>
|
|
645
|
+
this.executeStep(step, state, path, frame, executorEnv),
|
|
533
646
|
fork: (forkOverrides) =>
|
|
534
|
-
this.createExecutorEnv({
|
|
647
|
+
this.createExecutorEnv(pass, {
|
|
535
648
|
context: forkOverrides.context ?? context,
|
|
536
649
|
signal: forkOverrides.signal ?? signal,
|
|
537
|
-
|
|
538
|
-
captureTaskOutput:
|
|
539
|
-
forkOverrides.captureTaskOutput ?? captureTaskOutput,
|
|
650
|
+
runtime: forkOverrides.runtime ?? runtime,
|
|
540
651
|
}),
|
|
541
652
|
};
|
|
542
653
|
|
|
@@ -544,56 +655,45 @@ export class WorkflowRunner {
|
|
|
544
655
|
}
|
|
545
656
|
|
|
546
657
|
/**
|
|
547
|
-
*
|
|
548
|
-
*
|
|
549
|
-
* @returns Dependency bag for suspension rebuilders.
|
|
550
|
-
*/
|
|
551
|
-
private createSuspensionRebuilderDeps(): SuspensionRebuilderDeps {
|
|
552
|
-
return {
|
|
553
|
-
compiled: this.compiled,
|
|
554
|
-
context: this.context,
|
|
555
|
-
runId: this.runId,
|
|
556
|
-
createExecutorEnv: () => this.createExecutorEnv(),
|
|
557
|
-
buildInstanceStepInfo: (step, iterationStack) =>
|
|
558
|
-
this.buildInstanceStepInfo(step, iterationStack),
|
|
559
|
-
captureTaskOutput: (task, state, result) =>
|
|
560
|
-
this.captureTaskOutput(task, state, result),
|
|
561
|
-
markSnapshot: (step, status, reason) =>
|
|
562
|
-
this.markSnapshot(step, status, reason),
|
|
563
|
-
emit: (event, payload) => this.emit(event, payload),
|
|
564
|
-
executeFlow: (steps, state, path, startIndex) =>
|
|
565
|
-
this.executeFlow(steps, state, path, startIndex),
|
|
566
|
-
};
|
|
567
|
-
}
|
|
568
|
-
|
|
569
|
-
/**
|
|
570
|
-
* Walk a list of compiled steps, threading state and returning a suspension when encountered.
|
|
658
|
+
* Walk a list of compiled steps, threading state and returning a frame when
|
|
659
|
+
* one of them suspends.
|
|
571
660
|
*
|
|
572
661
|
* @param steps The steps to execute sequentially.
|
|
573
662
|
* @param state Mutable execution state shared across steps.
|
|
574
663
|
* @param path Path tokens leading to the current step for tracing.
|
|
575
|
-
* @param
|
|
576
|
-
* @
|
|
664
|
+
* @param frame Frame of a previous suspension within these steps.
|
|
665
|
+
* @param env Executor environment of the current scope.
|
|
666
|
+
* @returns A frame if execution pauses, otherwise void.
|
|
577
667
|
*/
|
|
578
668
|
private async executeFlow(
|
|
579
669
|
steps: CompiledStep[],
|
|
580
670
|
state: ExecutionState,
|
|
581
671
|
path: Array<number | string>,
|
|
582
|
-
|
|
583
|
-
env
|
|
584
|
-
): Promise<
|
|
585
|
-
|
|
586
|
-
|
|
672
|
+
frame: SequenceFrame | undefined,
|
|
673
|
+
env: StepExecutorEnv,
|
|
674
|
+
): Promise<SequenceFrame | void> {
|
|
675
|
+
if (frame) {
|
|
676
|
+
state.accumulator = frame.accumulator;
|
|
677
|
+
}
|
|
678
|
+
|
|
679
|
+
for (let index = frame?.index ?? 0; index < steps.length; index += 1) {
|
|
587
680
|
throwIfAborted(env.signal);
|
|
588
681
|
|
|
589
|
-
const
|
|
590
|
-
|
|
591
|
-
|
|
682
|
+
const child = await this.executeStep(
|
|
683
|
+
steps[index],
|
|
684
|
+
state,
|
|
685
|
+
[...path, index],
|
|
686
|
+
frame && index === frame.index ? frame.child : undefined,
|
|
687
|
+
env,
|
|
688
|
+
);
|
|
592
689
|
|
|
593
|
-
if (
|
|
594
|
-
return
|
|
595
|
-
|
|
596
|
-
|
|
690
|
+
if (child) {
|
|
691
|
+
return {
|
|
692
|
+
kind: 'sequence',
|
|
693
|
+
index,
|
|
694
|
+
accumulator: state.accumulator,
|
|
695
|
+
child,
|
|
696
|
+
};
|
|
597
697
|
}
|
|
598
698
|
}
|
|
599
699
|
|
|
@@ -606,25 +706,41 @@ export class WorkflowRunner {
|
|
|
606
706
|
* @param step The step to run.
|
|
607
707
|
* @param state The shared execution state.
|
|
608
708
|
* @param path Tokens describing the location of the step in the workflow.
|
|
609
|
-
* @
|
|
709
|
+
* @param frame Frame of a previous suspension of this step.
|
|
710
|
+
* @param env Executor environment of the current scope.
|
|
711
|
+
* @returns A frame if the step pauses execution, otherwise void.
|
|
610
712
|
*/
|
|
611
713
|
private async executeStep(
|
|
612
714
|
step: CompiledStep,
|
|
613
715
|
state: ExecutionState,
|
|
614
716
|
path: Array<number | string>,
|
|
615
|
-
|
|
616
|
-
|
|
717
|
+
frame: StepFrame | undefined,
|
|
718
|
+
env: StepExecutorEnv,
|
|
719
|
+
): Promise<StepFrame | void> {
|
|
617
720
|
throwIfAborted(env.signal);
|
|
721
|
+
assertFrameMatchesStep(frame, step, path);
|
|
618
722
|
|
|
619
723
|
switch (step.type) {
|
|
620
724
|
case StepType.Task:
|
|
621
|
-
return runTaskExecutor(env, step, state, path);
|
|
725
|
+
return runTaskExecutor(env, step, state, path, frame as TaskFrame);
|
|
622
726
|
case StepType.Parallel:
|
|
623
|
-
return runParallelExecutor(
|
|
727
|
+
return runParallelExecutor(
|
|
728
|
+
env,
|
|
729
|
+
step,
|
|
730
|
+
state,
|
|
731
|
+
path,
|
|
732
|
+
frame as ParallelFrame,
|
|
733
|
+
);
|
|
624
734
|
case StepType.Conditional:
|
|
625
|
-
return runConditionalExecutor(
|
|
735
|
+
return runConditionalExecutor(
|
|
736
|
+
env,
|
|
737
|
+
step,
|
|
738
|
+
state,
|
|
739
|
+
path,
|
|
740
|
+
frame as ConditionalFrame,
|
|
741
|
+
);
|
|
626
742
|
case StepType.Loop:
|
|
627
|
-
return runLoopExecutor(env, step, state, path);
|
|
743
|
+
return runLoopExecutor(env, step, state, path, frame as LoopFrame);
|
|
628
744
|
}
|
|
629
745
|
}
|
|
630
746
|
|