@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
|
@@ -0,0 +1,293 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Hexabot — Fair Core License (FCL-1.0-ALv2)
|
|
3
|
+
* Copyright (c) 2025 Hexastack.
|
|
4
|
+
* Full terms: see LICENSE.md.
|
|
5
|
+
*/
|
|
6
|
+
import { z } from 'zod';
|
|
7
|
+
import { WorkflowCheckpointInvalidError, WorkflowDefinitionDriftError, WorkflowResumeError, WorkflowWaitAmbiguousError, WorkflowWaitNotFoundError, } from './errors';
|
|
8
|
+
import { checkResumePayload } from './resume-payload';
|
|
9
|
+
import { isRecord } from './utils/clone';
|
|
10
|
+
import { StepType } from './workflow-event-emitter';
|
|
11
|
+
import { fingerprintWorkflow } from './workflow-fingerprint';
|
|
12
|
+
/** Current format version of {@link WorkflowCheckpoint}. */
|
|
13
|
+
export const CHECKPOINT_VERSION = 1;
|
|
14
|
+
const recordSchema = z.record(z.string(), z.unknown());
|
|
15
|
+
const stepIdSchema = z.string().min(1);
|
|
16
|
+
const stepInfoSchema = z.object({
|
|
17
|
+
id: stepIdSchema,
|
|
18
|
+
name: z.string(),
|
|
19
|
+
type: z.enum(StepType),
|
|
20
|
+
});
|
|
21
|
+
const waitInfoSchema = z.object({
|
|
22
|
+
waitId: z.string().min(1),
|
|
23
|
+
step: stepInfoSchema,
|
|
24
|
+
suspendKey: z.string().min(1),
|
|
25
|
+
reason: z.string().optional(),
|
|
26
|
+
data: z.unknown().optional(),
|
|
27
|
+
accepts: recordSchema.optional(),
|
|
28
|
+
payloadOptional: z.boolean().optional(),
|
|
29
|
+
});
|
|
30
|
+
const taskFrameSchema = z.object({
|
|
31
|
+
kind: z.literal('task'),
|
|
32
|
+
stepId: stepIdSchema,
|
|
33
|
+
inputs: recordSchema,
|
|
34
|
+
awaitResults: z.record(z.string(), z.object({ value: z.unknown().optional() })),
|
|
35
|
+
wait: waitInfoSchema,
|
|
36
|
+
});
|
|
37
|
+
const conditionalFrameSchema = z.lazy(() => z.object({
|
|
38
|
+
kind: z.literal('conditional'),
|
|
39
|
+
stepId: stepIdSchema,
|
|
40
|
+
branchIndex: z.int().nonnegative(),
|
|
41
|
+
child: sequenceFrameSchema,
|
|
42
|
+
}));
|
|
43
|
+
const loopFrameSchema = z.lazy(() => z.object({
|
|
44
|
+
kind: z.literal('loop'),
|
|
45
|
+
stepId: stepIdSchema,
|
|
46
|
+
index: z.int().nonnegative(),
|
|
47
|
+
items: z.array(z.unknown()).optional(),
|
|
48
|
+
accumulator: z.unknown().optional(),
|
|
49
|
+
child: sequenceFrameSchema,
|
|
50
|
+
}));
|
|
51
|
+
const parallelFrameSchema = z.lazy(() => z.object({
|
|
52
|
+
kind: z.literal('parallel'),
|
|
53
|
+
stepId: stepIdSchema,
|
|
54
|
+
branches: z.array(z.union([
|
|
55
|
+
z.object({ status: z.literal('fulfilled'), outputDelta: recordSchema }),
|
|
56
|
+
z.object({
|
|
57
|
+
status: z.literal('suspended'),
|
|
58
|
+
outputDelta: recordSchema,
|
|
59
|
+
child: stepFrameSchema,
|
|
60
|
+
}),
|
|
61
|
+
])),
|
|
62
|
+
}));
|
|
63
|
+
const stepFrameSchema = z.lazy(() => z.union([
|
|
64
|
+
taskFrameSchema,
|
|
65
|
+
conditionalFrameSchema,
|
|
66
|
+
loopFrameSchema,
|
|
67
|
+
parallelFrameSchema,
|
|
68
|
+
]));
|
|
69
|
+
const sequenceFrameSchema = z.lazy(() => z.object({
|
|
70
|
+
kind: z.literal('sequence'),
|
|
71
|
+
index: z.int().nonnegative(),
|
|
72
|
+
accumulator: z.unknown().optional(),
|
|
73
|
+
child: stepFrameSchema,
|
|
74
|
+
}));
|
|
75
|
+
/** Schema of a persisted {@link WorkflowCheckpoint}, for hosts to type storage. */
|
|
76
|
+
export const workflowCheckpointSchema = z.object({
|
|
77
|
+
version: z.literal(CHECKPOINT_VERSION),
|
|
78
|
+
fingerprint: z.string().min(1),
|
|
79
|
+
input: recordSchema,
|
|
80
|
+
output: recordSchema,
|
|
81
|
+
root: sequenceFrameSchema,
|
|
82
|
+
waits: z.array(waitInfoSchema).min(1),
|
|
83
|
+
});
|
|
84
|
+
/**
|
|
85
|
+
* Build the handle of a wait from the instance step that suspended and its
|
|
86
|
+
* suspend key.
|
|
87
|
+
*
|
|
88
|
+
* @param stepInstanceId Instance step id, including any loop iteration suffix.
|
|
89
|
+
* @param suspendKey Normalized suspend key within the step body.
|
|
90
|
+
* @returns The wait id.
|
|
91
|
+
*/
|
|
92
|
+
export const buildWaitId = (stepInstanceId, suspendKey) => `${stepInstanceId}@${suspendKey}`;
|
|
93
|
+
/**
|
|
94
|
+
* List the open waits held by a frame tree, in flow order.
|
|
95
|
+
*
|
|
96
|
+
* @param frame Root or subtree of a checkpoint.
|
|
97
|
+
* @returns The waits of every suspended task under the frame.
|
|
98
|
+
*/
|
|
99
|
+
export function collectWaits(frame) {
|
|
100
|
+
switch (frame.kind) {
|
|
101
|
+
case 'task':
|
|
102
|
+
return [frame.wait];
|
|
103
|
+
case 'sequence':
|
|
104
|
+
case 'conditional':
|
|
105
|
+
case 'loop':
|
|
106
|
+
return collectWaits(frame.child);
|
|
107
|
+
case 'parallel':
|
|
108
|
+
return frame.branches.flatMap((branch) => branch.status === 'suspended' ? collectWaits(branch.child) : []);
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* Pick the wait a resume targets. `resume()` and `validateCheckpoint` both
|
|
113
|
+
* use it, so a payload is always checked against the wait it would resolve.
|
|
114
|
+
*
|
|
115
|
+
* @param waits Open waits of the suspended run.
|
|
116
|
+
* @param waitId Requested wait, optional when exactly one wait is open.
|
|
117
|
+
* @returns The targeted wait.
|
|
118
|
+
* @throws {WorkflowWaitNotFoundError} When `waitId` is not an open wait.
|
|
119
|
+
* @throws {WorkflowWaitAmbiguousError} When several waits are open and no
|
|
120
|
+
* `waitId` is given.
|
|
121
|
+
*/
|
|
122
|
+
export function selectWait(waits, waitId) {
|
|
123
|
+
const openWaitIds = waits.map((candidate) => candidate.waitId);
|
|
124
|
+
if (waitId === undefined) {
|
|
125
|
+
if (waits.length === 1) {
|
|
126
|
+
return waits[0];
|
|
127
|
+
}
|
|
128
|
+
throw new WorkflowWaitAmbiguousError(openWaitIds);
|
|
129
|
+
}
|
|
130
|
+
const wait = waits.find((candidate) => candidate.waitId === waitId);
|
|
131
|
+
if (!wait) {
|
|
132
|
+
throw new WorkflowWaitNotFoundError(waitId, openWaitIds);
|
|
133
|
+
}
|
|
134
|
+
return wait;
|
|
135
|
+
}
|
|
136
|
+
/**
|
|
137
|
+
* Check that a frame was taken for the given compiled step.
|
|
138
|
+
*
|
|
139
|
+
* @param frame The frame about to be resumed, if any.
|
|
140
|
+
* @param step The compiled step it is being handed to.
|
|
141
|
+
* @param path Location used in the error message.
|
|
142
|
+
* @throws {WorkflowCheckpointInvalidError} When the frame belongs elsewhere.
|
|
143
|
+
*/
|
|
144
|
+
export function assertFrameMatchesStep(frame, step, path = []) {
|
|
145
|
+
if (!frame) {
|
|
146
|
+
return;
|
|
147
|
+
}
|
|
148
|
+
if (frame.kind !== step.type || frame.stepId !== step.id) {
|
|
149
|
+
throw new WorkflowCheckpointInvalidError('structure', `Checkpoint expects ${frame.kind} step "${frame.stepId}" but the flow ` +
|
|
150
|
+
`has ${step.type} step "${step.id}".`, { path });
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* Decide whether a checkpoint can resume against a compiled workflow, without
|
|
155
|
+
* running anything.
|
|
156
|
+
*
|
|
157
|
+
* Checks, in order: presence and shape, format version, definition
|
|
158
|
+
* fingerprint, that every frame lines up with the compiled step it names, that
|
|
159
|
+
* the `waits` index matches the frame tree, and (optionally) that a given wait
|
|
160
|
+
* is open and accepts a given payload.
|
|
161
|
+
*
|
|
162
|
+
* @param compiled The compiled workflow the run will resume against.
|
|
163
|
+
* @param checkpoint The persisted checkpoint, as stored.
|
|
164
|
+
* @param options.waitId Wait the caller is about to resume.
|
|
165
|
+
* @param options.resumeData Payload the caller is about to resume with. When
|
|
166
|
+
* the key is present, it is checked against the wait `resume()` would pick:
|
|
167
|
+
* the one named by `waitId`, or the only open wait.
|
|
168
|
+
* @returns The parsed checkpoint, or the typed reason it cannot resume.
|
|
169
|
+
*/
|
|
170
|
+
export function validateCheckpoint(compiled, checkpoint, options = {}) {
|
|
171
|
+
try {
|
|
172
|
+
const parsed = parseCheckpoint(checkpoint);
|
|
173
|
+
const actual = fingerprintWorkflow(compiled);
|
|
174
|
+
if (parsed.fingerprint !== actual) {
|
|
175
|
+
throw new WorkflowDefinitionDriftError(parsed.fingerprint, actual);
|
|
176
|
+
}
|
|
177
|
+
assertSequenceMatches(compiled.flow, parsed.root, ['root']);
|
|
178
|
+
assertWaitIndex(parsed);
|
|
179
|
+
if (options.waitId !== undefined || 'resumeData' in options) {
|
|
180
|
+
const wait = selectWait(parsed.waits, options.waitId);
|
|
181
|
+
if ('resumeData' in options) {
|
|
182
|
+
const payload = checkResumePayload(wait, options.resumeData);
|
|
183
|
+
if (!payload.ok) {
|
|
184
|
+
throw payload.error;
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
return { ok: true, checkpoint: parsed };
|
|
189
|
+
}
|
|
190
|
+
catch (error) {
|
|
191
|
+
if (error instanceof WorkflowResumeError) {
|
|
192
|
+
return { ok: false, error };
|
|
193
|
+
}
|
|
194
|
+
throw error;
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
const parseCheckpoint = (checkpoint) => {
|
|
198
|
+
if (checkpoint === null || checkpoint === undefined) {
|
|
199
|
+
throw new WorkflowCheckpointInvalidError('missing', 'No checkpoint was persisted for this run.');
|
|
200
|
+
}
|
|
201
|
+
if (isRecord(checkpoint) &&
|
|
202
|
+
checkpoint.version !== undefined &&
|
|
203
|
+
checkpoint.version !== CHECKPOINT_VERSION) {
|
|
204
|
+
throw new WorkflowCheckpointInvalidError('unsupported_version', `Unsupported checkpoint version ${String(checkpoint.version)}; ` +
|
|
205
|
+
`expected ${CHECKPOINT_VERSION}.`);
|
|
206
|
+
}
|
|
207
|
+
const result = workflowCheckpointSchema.safeParse(checkpoint);
|
|
208
|
+
if (!result.success) {
|
|
209
|
+
const issues = result.error.issues.map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`);
|
|
210
|
+
throw new WorkflowCheckpointInvalidError('malformed', `Checkpoint does not match the expected shape: ${issues.join('; ')}`, { issues });
|
|
211
|
+
}
|
|
212
|
+
return result.data;
|
|
213
|
+
};
|
|
214
|
+
const structureError = (message, path) => new WorkflowCheckpointInvalidError('structure', message, { path });
|
|
215
|
+
const assertSequenceMatches = (steps, frame, path) => {
|
|
216
|
+
const step = steps[frame.index];
|
|
217
|
+
if (!step) {
|
|
218
|
+
throw structureError(`Sequence position ${frame.index} is out of range (${steps.length} steps).`, path);
|
|
219
|
+
}
|
|
220
|
+
assertStepMatches(step, frame.child, [...path, frame.index]);
|
|
221
|
+
};
|
|
222
|
+
const assertStepMatches = (step, frame, path) => {
|
|
223
|
+
assertFrameMatchesStep(frame, step, path);
|
|
224
|
+
switch (step.type) {
|
|
225
|
+
case StepType.Task:
|
|
226
|
+
return;
|
|
227
|
+
case StepType.Conditional:
|
|
228
|
+
return assertConditionalMatches(step, frame, path);
|
|
229
|
+
case StepType.Loop:
|
|
230
|
+
return assertLoopMatches(step, frame, path);
|
|
231
|
+
case StepType.Parallel:
|
|
232
|
+
return assertParallelMatches(step, frame, path);
|
|
233
|
+
}
|
|
234
|
+
};
|
|
235
|
+
const assertConditionalMatches = (step, frame, path) => {
|
|
236
|
+
const branch = step.branches[frame.branchIndex];
|
|
237
|
+
if (!branch) {
|
|
238
|
+
throw structureError(`Branch ${frame.branchIndex} does not exist on conditional "${step.id}".`, path);
|
|
239
|
+
}
|
|
240
|
+
assertSequenceMatches(branch.steps, frame.child, [
|
|
241
|
+
...path,
|
|
242
|
+
'branch',
|
|
243
|
+
frame.branchIndex,
|
|
244
|
+
]);
|
|
245
|
+
};
|
|
246
|
+
const assertLoopMatches = (step, frame, path) => {
|
|
247
|
+
if (step.loopType === 'for_each') {
|
|
248
|
+
if (!frame.items || frame.index >= frame.items.length) {
|
|
249
|
+
throw structureError(`for_each loop "${step.id}" is suspended at iteration ${frame.index} ` +
|
|
250
|
+
`of ${frame.items?.length ?? 0} recorded items.`, path);
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
else if (frame.items !== undefined) {
|
|
254
|
+
throw structureError(`while loop "${step.id}" cannot carry for_each items.`, path);
|
|
255
|
+
}
|
|
256
|
+
assertSequenceMatches(step.steps, frame.child, [...path, frame.index]);
|
|
257
|
+
};
|
|
258
|
+
const assertParallelMatches = (step, frame, path) => {
|
|
259
|
+
if (frame.branches.length !== step.steps.length) {
|
|
260
|
+
throw structureError(`Parallel "${step.id}" has ${step.steps.length} branches but the ` +
|
|
261
|
+
`checkpoint records ${frame.branches.length}.`, path);
|
|
262
|
+
}
|
|
263
|
+
let suspended = 0;
|
|
264
|
+
frame.branches.forEach((branch, index) => {
|
|
265
|
+
if (branch.status === 'suspended') {
|
|
266
|
+
suspended += 1;
|
|
267
|
+
assertStepMatches(step.steps[index], branch.child, [
|
|
268
|
+
...path,
|
|
269
|
+
'parallel',
|
|
270
|
+
index,
|
|
271
|
+
]);
|
|
272
|
+
}
|
|
273
|
+
else if (step.strategy === 'wait_any') {
|
|
274
|
+
// A fulfilled branch wins a wait_any race, so it can never be parked.
|
|
275
|
+
throw structureError(`wait_any parallel "${step.id}" cannot record a fulfilled branch.`, path);
|
|
276
|
+
}
|
|
277
|
+
});
|
|
278
|
+
if (suspended === 0) {
|
|
279
|
+
throw structureError(`Parallel "${step.id}" is recorded as suspended without a suspended branch.`, path);
|
|
280
|
+
}
|
|
281
|
+
};
|
|
282
|
+
const assertWaitIndex = (checkpoint) => {
|
|
283
|
+
const expected = collectWaits(checkpoint.root).map((wait) => wait.waitId);
|
|
284
|
+
const actual = checkpoint.waits.map((wait) => wait.waitId);
|
|
285
|
+
if (expected.length !== actual.length ||
|
|
286
|
+
expected.some((waitId, index) => waitId !== actual[index])) {
|
|
287
|
+
throw structureError(`Checkpoint waits [${actual.join(', ')}] do not match the suspended ` +
|
|
288
|
+
`steps [${expected.join(', ')}].`, ['waits']);
|
|
289
|
+
}
|
|
290
|
+
if (new Set(expected).size !== expected.length) {
|
|
291
|
+
throw structureError(`Checkpoint holds duplicate waits [${expected.join(', ')}].`, ['waits']);
|
|
292
|
+
}
|
|
293
|
+
};
|
package/dist/esm/context.js
CHANGED
|
@@ -3,13 +3,14 @@
|
|
|
3
3
|
* Copyright (c) 2025 Hexastack.
|
|
4
4
|
* Full terms: see LICENSE.md.
|
|
5
5
|
*/
|
|
6
|
+
import { cloneRecord } from './utils/clone';
|
|
6
7
|
/**
|
|
7
8
|
* Lifecycle of a workflow run:
|
|
8
9
|
* - idle: runner constructed but `start` not invoked.
|
|
9
10
|
* - running: set when `start` or `resume` begins executing steps.
|
|
10
11
|
* - suspended: an action awaited `workflow.suspend`; `resume` moves back to running.
|
|
11
12
|
* - finished: all steps completed and outputs were evaluated successfully.
|
|
12
|
-
* - failed: an uncaught error bubbled out of a step or
|
|
13
|
+
* - failed: an uncaught error bubbled out of a step or the output mapping.
|
|
13
14
|
*/
|
|
14
15
|
export var EWorkflowRunStatus;
|
|
15
16
|
(function (EWorkflowRunStatus) {
|
|
@@ -47,7 +48,7 @@ export class BaseWorkflowContext {
|
|
|
47
48
|
* Override to filter or reshape the exposed state.
|
|
48
49
|
*/
|
|
49
50
|
snapshot() {
|
|
50
|
-
return
|
|
51
|
+
return cloneRecord(this.state ?? {});
|
|
51
52
|
}
|
|
52
53
|
/**
|
|
53
54
|
* Provides access to the workflow runtime API for the current execution.
|
|
@@ -61,6 +62,14 @@ export class BaseWorkflowContext {
|
|
|
61
62
|
}
|
|
62
63
|
return this._workflowControl;
|
|
63
64
|
}
|
|
65
|
+
/**
|
|
66
|
+
* Reads the runtime control without throwing when none is attached.
|
|
67
|
+
*
|
|
68
|
+
* @returns The attached runtime control, or `undefined` outside a run.
|
|
69
|
+
*/
|
|
70
|
+
getWorkflowRuntime() {
|
|
71
|
+
return this._workflowControl;
|
|
72
|
+
}
|
|
64
73
|
/**
|
|
65
74
|
* Attaches or detaches the runtime control object.
|
|
66
75
|
*
|
|
@@ -71,28 +80,3 @@ export class BaseWorkflowContext {
|
|
|
71
80
|
this._workflowControl = control;
|
|
72
81
|
}
|
|
73
82
|
}
|
|
74
|
-
const safeCloneRecord = (value) => {
|
|
75
|
-
if (!value) {
|
|
76
|
-
return {};
|
|
77
|
-
}
|
|
78
|
-
if (typeof structuredClone === 'function') {
|
|
79
|
-
try {
|
|
80
|
-
return structuredClone(value);
|
|
81
|
-
}
|
|
82
|
-
catch {
|
|
83
|
-
// Fall through to JSON clone below.
|
|
84
|
-
}
|
|
85
|
-
}
|
|
86
|
-
try {
|
|
87
|
-
return JSON.parse(JSON.stringify(value));
|
|
88
|
-
}
|
|
89
|
-
catch {
|
|
90
|
-
const shallow = {};
|
|
91
|
-
for (const [key, entry] of Object.entries(value)) {
|
|
92
|
-
if (typeof entry !== 'function') {
|
|
93
|
-
shallow[key] = entry;
|
|
94
|
-
}
|
|
95
|
-
}
|
|
96
|
-
return shallow;
|
|
97
|
-
}
|
|
98
|
-
};
|
package/dist/esm/dsl.types.js
CHANGED
|
@@ -161,6 +161,9 @@ const ConditionalWhenSchema = z.lazy(() => z.strictObject({
|
|
|
161
161
|
steps: z.array(FlowStepSchema),
|
|
162
162
|
}));
|
|
163
163
|
const ConditionalElseSchema = z.lazy(() => z.strictObject({
|
|
164
|
+
// Refusing `condition` here keeps a `when` branch with a bad condition
|
|
165
|
+
// from also matching as an `else` branch, so its own issue is reported.
|
|
166
|
+
condition: z.never().optional(),
|
|
164
167
|
else: z.unknown().optional(),
|
|
165
168
|
steps: z.array(FlowStepSchema),
|
|
166
169
|
}));
|
package/dist/esm/errors.js
CHANGED
|
@@ -9,14 +9,93 @@ export class WorkflowCancellationError extends Error {
|
|
|
9
9
|
this.name = 'WorkflowCancellationError';
|
|
10
10
|
}
|
|
11
11
|
}
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
12
|
+
/** Base class for every reason a suspended run cannot be resumed. */
|
|
13
|
+
export class WorkflowResumeError extends Error {
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* The checkpoint cannot be used: nothing was persisted, its shape is wrong,
|
|
17
|
+
* its format version is unsupported, or its frames do not line up with the
|
|
18
|
+
* compiled flow they claim to describe.
|
|
19
|
+
*/
|
|
20
|
+
export class WorkflowCheckpointInvalidError extends WorkflowResumeError {
|
|
21
|
+
constructor(code, message, options) {
|
|
22
|
+
super(message);
|
|
23
|
+
this.name = 'WorkflowCheckpointInvalidError';
|
|
24
|
+
this.code = code;
|
|
25
|
+
this.path = options?.path;
|
|
26
|
+
this.issues = options?.issues;
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* The compiled definition no longer matches the one the checkpoint was taken
|
|
31
|
+
* against, so its frames cannot be trusted to point at the same steps.
|
|
32
|
+
*/
|
|
33
|
+
export class WorkflowDefinitionDriftError extends WorkflowResumeError {
|
|
34
|
+
constructor(expected, actual) {
|
|
35
|
+
super('Workflow definition changed since this run was suspended ' +
|
|
36
|
+
`(checkpoint fingerprint ${expected}, current ${actual}).`);
|
|
37
|
+
this.name = 'WorkflowDefinitionDriftError';
|
|
38
|
+
this.expected = expected;
|
|
39
|
+
this.actual = actual;
|
|
16
40
|
}
|
|
17
41
|
}
|
|
18
|
-
|
|
19
|
-
|
|
42
|
+
/** Several waits are open and the resume did not say which one it satisfies. */
|
|
43
|
+
export class WorkflowWaitAmbiguousError extends WorkflowResumeError {
|
|
44
|
+
constructor(openWaitIds) {
|
|
45
|
+
super(`Workflow run is waiting on ${openWaitIds.length} suspensions; pass a ` +
|
|
46
|
+
`waitId to choose one (${openWaitIds.join(', ')}).`);
|
|
47
|
+
this.name = 'WorkflowWaitAmbiguousError';
|
|
48
|
+
this.openWaitIds = openWaitIds;
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
/** The run is not waiting on the requested suspension. */
|
|
52
|
+
export class WorkflowWaitNotFoundError extends WorkflowResumeError {
|
|
53
|
+
constructor(waitId, openWaitIds) {
|
|
54
|
+
super(`Workflow run is not waiting on "${waitId}"` +
|
|
55
|
+
(openWaitIds.length > 0
|
|
56
|
+
? ` (open waits: ${openWaitIds.join(', ')}).`
|
|
57
|
+
: ' (no open waits).'));
|
|
58
|
+
this.name = 'WorkflowWaitNotFoundError';
|
|
59
|
+
this.waitId = waitId;
|
|
60
|
+
this.openWaitIds = openWaitIds;
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* The resume payload was refused. The wait stays open under the same
|
|
65
|
+
* `waitId`, so it can be resumed again, and the run's checkpoint, snapshot
|
|
66
|
+
* and step log are left as they were. Events already emitted by
|
|
67
|
+
* a body that refused the payload stay emitted, and its side effects,
|
|
68
|
+
* including writes to context state, are not undone.
|
|
69
|
+
*
|
|
70
|
+
* The runtime raises it when a payload does not match the `accepts` schema of
|
|
71
|
+
* the wait. An action may throw it itself, after its `suspend()` call
|
|
72
|
+
* resolved, to refuse a payload for reasons a schema cannot express.
|
|
73
|
+
*/
|
|
74
|
+
export class WorkflowResumeRejectedError extends WorkflowResumeError {
|
|
75
|
+
constructor(message, options) {
|
|
76
|
+
super(message);
|
|
77
|
+
this.name = 'WorkflowResumeRejectedError';
|
|
78
|
+
this.issues = options?.issues;
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* A resumed action body did not replay the way it ran before it suspended,
|
|
83
|
+
* so the results recorded for it cannot be trusted.
|
|
84
|
+
*/
|
|
85
|
+
export class NonDeterministicWorkflowError extends Error {
|
|
86
|
+
constructor(message) {
|
|
87
|
+
super(message);
|
|
88
|
+
this.name = 'NonDeterministicWorkflowError';
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
// Errors that cross into action code are also matched by name: an extension
|
|
92
|
+
// may import the other (CJS or ESM) build of this package, whose classes are
|
|
93
|
+
// distinct from these.
|
|
94
|
+
const isNamedError = (error, name) => error instanceof Error && error.name === name;
|
|
95
|
+
export const isWorkflowResumeRejectedError = (error) => error instanceof WorkflowResumeRejectedError ||
|
|
96
|
+
isNamedError(error, 'WorkflowResumeRejectedError');
|
|
97
|
+
export const isNonDeterministicWorkflowError = (error) => error instanceof NonDeterministicWorkflowError ||
|
|
98
|
+
isNamedError(error, 'NonDeterministicWorkflowError');
|
|
20
99
|
export const getAbortReason = (signal) => {
|
|
21
100
|
if (signal.reason instanceof Error) {
|
|
22
101
|
return signal.reason;
|
|
@@ -31,3 +110,23 @@ export const throwIfAborted = (signal) => {
|
|
|
31
110
|
throw getAbortReason(signal);
|
|
32
111
|
}
|
|
33
112
|
};
|
|
113
|
+
/**
|
|
114
|
+
* Create a controller that aborts along with a parent signal, so a child
|
|
115
|
+
* scope can be cancelled on its own without cancelling the parent.
|
|
116
|
+
*
|
|
117
|
+
* @param parent Signal whose abort propagates to the new controller.
|
|
118
|
+
* @returns The controller, and a function detaching it from `parent`.
|
|
119
|
+
*/
|
|
120
|
+
export const createLinkedAbortController = (parent) => {
|
|
121
|
+
const controller = new AbortController();
|
|
122
|
+
if (parent.aborted) {
|
|
123
|
+
controller.abort(getAbortReason(parent));
|
|
124
|
+
return { controller, unlink: () => undefined };
|
|
125
|
+
}
|
|
126
|
+
const onAbort = () => controller.abort(getAbortReason(parent));
|
|
127
|
+
parent.addEventListener('abort', onAbort, { once: true });
|
|
128
|
+
return {
|
|
129
|
+
controller,
|
|
130
|
+
unlink: () => parent.removeEventListener('abort', onAbort),
|
|
131
|
+
};
|
|
132
|
+
};
|
package/dist/esm/index.js
CHANGED
|
@@ -10,10 +10,10 @@ export * from './dsl.types';
|
|
|
10
10
|
export { issueMessages, } from './validation-issue';
|
|
11
11
|
export { compileWorkflow, Workflow, WorkflowEventEmitter, WorkflowRunner, } from './workflow';
|
|
12
12
|
export { StepType } from './workflow-event-emitter';
|
|
13
|
-
export {
|
|
14
|
-
export {
|
|
13
|
+
export { CHECKPOINT_VERSION, collectWaits, validateCheckpoint, workflowCheckpointSchema, } from './checkpoint';
|
|
14
|
+
export { fingerprintWorkflow } from './workflow-fingerprint';
|
|
15
|
+
export { NonDeterministicWorkflowError, WorkflowCancellationError, WorkflowCheckpointInvalidError, WorkflowDefinitionDriftError, WorkflowResumeError, WorkflowResumeRejectedError, WorkflowWaitAmbiguousError, WorkflowWaitNotFoundError, } from './errors';
|
|
15
16
|
export { compileValue, evaluateMapping, evaluateValue, mergeSettings, } from './workflow-values';
|
|
16
|
-
export { createDeferred } from './utils/deferred';
|
|
17
17
|
export { assertSnakeCaseName, isSnakeCaseName, toSnakeCase, } from './utils/naming';
|
|
18
18
|
export { sleep, withTimeout } from './utils/timeout';
|
|
19
19
|
export { collectWorkflowDefinitionResourceRefs, remapWorkflowDefinitionResourceRefs, } from './utils/workflow-definition-resources';
|