@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
|
@@ -8,7 +8,11 @@ import { z, ZodType } from 'zod';
|
|
|
8
8
|
|
|
9
9
|
import { BaseWorkflowContext } from '../context';
|
|
10
10
|
import { BaseSettingsSchema } from '../dsl.types';
|
|
11
|
-
import {
|
|
11
|
+
import {
|
|
12
|
+
isNonDeterministicWorkflowError,
|
|
13
|
+
isWorkflowResumeRejectedError,
|
|
14
|
+
throwIfAborted,
|
|
15
|
+
} from '../errors';
|
|
12
16
|
import { assertSnakeCaseName } from '../utils/naming';
|
|
13
17
|
import { sleep, withTimeout } from '../utils/timeout';
|
|
14
18
|
|
|
@@ -136,12 +140,21 @@ export abstract class AbstractAction<
|
|
|
136
140
|
const maxDelayMs = retrySettings.max_delay_ms;
|
|
137
141
|
const jitter = retrySettings.jitter;
|
|
138
142
|
const multiplier = retrySettings.multiplier;
|
|
143
|
+
// Suspend keys are positional within the body, so every attempt has to
|
|
144
|
+
// start from where this run did: otherwise a retry asks for `index:2`
|
|
145
|
+
// where the first attempt resolved `index:1`, and the step suspends on a
|
|
146
|
+
// wait whose payload was already delivered.
|
|
147
|
+
const rewindSuspendCursor = context
|
|
148
|
+
?.getWorkflowRuntime?.()
|
|
149
|
+
?.markSuspendCursor?.();
|
|
139
150
|
|
|
140
151
|
while (attempt < maxAttempts) {
|
|
141
152
|
if (signal) {
|
|
142
153
|
throwIfAborted(signal);
|
|
143
154
|
}
|
|
144
155
|
|
|
156
|
+
rewindSuspendCursor?.();
|
|
157
|
+
|
|
145
158
|
try {
|
|
146
159
|
const result = await withTimeout(
|
|
147
160
|
this.execute({
|
|
@@ -159,7 +172,13 @@ export abstract class AbstractAction<
|
|
|
159
172
|
} catch (error) {
|
|
160
173
|
attempt += 1;
|
|
161
174
|
|
|
162
|
-
|
|
175
|
+
// A retry would read the same refused resume payload again, or replay
|
|
176
|
+
// the same body into the same mismatch with what it recorded.
|
|
177
|
+
if (
|
|
178
|
+
attempt >= maxAttempts ||
|
|
179
|
+
isWorkflowResumeRejectedError(error) ||
|
|
180
|
+
isNonDeterministicWorkflowError(error)
|
|
181
|
+
) {
|
|
163
182
|
throw error;
|
|
164
183
|
}
|
|
165
184
|
|
|
@@ -9,7 +9,6 @@ import { ZodType } from 'zod';
|
|
|
9
9
|
import type { InferWorkflowBindings } from '../bindings/base-binding';
|
|
10
10
|
import { BaseWorkflowContext } from '../context';
|
|
11
11
|
import { Settings } from '../dsl.types';
|
|
12
|
-
import { Deferred } from '../utils/deferred';
|
|
13
12
|
|
|
14
13
|
export type RuntimeSettings<S = unknown> = Settings & S;
|
|
15
14
|
|
|
@@ -82,14 +81,3 @@ export type InferActionSettings<S extends Action> =
|
|
|
82
81
|
|
|
83
82
|
export type InferActionBindings<S extends Action> =
|
|
84
83
|
InferActionArgs<S>['bindings'];
|
|
85
|
-
|
|
86
|
-
export interface SuspensionNotice {
|
|
87
|
-
stepId: string;
|
|
88
|
-
reason?: string;
|
|
89
|
-
data?: unknown;
|
|
90
|
-
resume: Deferred<unknown>;
|
|
91
|
-
}
|
|
92
|
-
|
|
93
|
-
export type ActionExecutionOutcome<T> =
|
|
94
|
-
| { type: 'completed'; value: T }
|
|
95
|
-
| { type: 'suspended'; notice: SuspensionNotice };
|
|
@@ -0,0 +1,561 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Hexabot — Fair Core License (FCL-1.0-ALv2)
|
|
3
|
+
* Copyright (c) 2025 Hexastack.
|
|
4
|
+
* Full terms: see LICENSE.md.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { z } from 'zod';
|
|
8
|
+
|
|
9
|
+
import {
|
|
10
|
+
WorkflowCheckpointInvalidError,
|
|
11
|
+
WorkflowDefinitionDriftError,
|
|
12
|
+
WorkflowResumeError,
|
|
13
|
+
WorkflowWaitAmbiguousError,
|
|
14
|
+
WorkflowWaitNotFoundError,
|
|
15
|
+
} from './errors';
|
|
16
|
+
import { checkResumePayload } from './resume-payload';
|
|
17
|
+
import { isRecord } from './utils/clone';
|
|
18
|
+
import { StepType, type StepInfo } from './workflow-event-emitter';
|
|
19
|
+
import { fingerprintWorkflow } from './workflow-fingerprint';
|
|
20
|
+
import type {
|
|
21
|
+
CompiledStep,
|
|
22
|
+
CompiledWorkflow,
|
|
23
|
+
ConditionalStep,
|
|
24
|
+
LoopStep,
|
|
25
|
+
ParallelStep,
|
|
26
|
+
} from './workflow-types';
|
|
27
|
+
|
|
28
|
+
/** Current format version of {@link WorkflowCheckpoint}. */
|
|
29
|
+
export const CHECKPOINT_VERSION = 1;
|
|
30
|
+
|
|
31
|
+
/** One open suspension a run is waiting on. */
|
|
32
|
+
export type WaitInfo = {
|
|
33
|
+
/**
|
|
34
|
+
* Handle a host passes to `resume()` to satisfy this wait. Opaque: unique
|
|
35
|
+
* within a run and stable for as long as the wait is open, but never meant
|
|
36
|
+
* to be parsed.
|
|
37
|
+
*/
|
|
38
|
+
waitId: string;
|
|
39
|
+
/** Instance step (loop iterations included) that suspended. */
|
|
40
|
+
step: StepInfo;
|
|
41
|
+
/** Normalized suspend point inside the step body (`index:<n>` or `key:<k>`). */
|
|
42
|
+
suspendKey: string;
|
|
43
|
+
reason?: string;
|
|
44
|
+
data?: unknown;
|
|
45
|
+
/**
|
|
46
|
+
* JSON Schema of the payload the wait accepts, in its JSON form, when
|
|
47
|
+
* `suspend()` was given an `accepts` schema. It is relaxed so that it never
|
|
48
|
+
* refuses a JSON payload the action would accept; the action's schema still
|
|
49
|
+
* has the final say.
|
|
50
|
+
*/
|
|
51
|
+
accepts?: Record<string, unknown>;
|
|
52
|
+
/**
|
|
53
|
+
* Set when the `accepts` schema also accepts a resume without payload,
|
|
54
|
+
* which JSON Schema cannot express: `accepts` describes a payload that is
|
|
55
|
+
* given.
|
|
56
|
+
*/
|
|
57
|
+
payloadOptional?: boolean;
|
|
58
|
+
};
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* Answer recorded for one `suspend()` call. The value is wrapped so that a
|
|
62
|
+
* resume without payload, whose value is `undefined`, is still recorded as
|
|
63
|
+
* answered once JSON drops the value.
|
|
64
|
+
*/
|
|
65
|
+
export type RecordedResult = { value?: unknown };
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Suspended task: the only frame that runs code on resume. Its body re-runs
|
|
69
|
+
* with `inputs`, and every `suspend()` call already answered in
|
|
70
|
+
* `awaitResults` resolves immediately.
|
|
71
|
+
*/
|
|
72
|
+
export type TaskFrame = {
|
|
73
|
+
kind: 'task';
|
|
74
|
+
stepId: string;
|
|
75
|
+
inputs: Record<string, unknown>;
|
|
76
|
+
/** Answers of the body's earlier `suspend()` calls, by suspend key. */
|
|
77
|
+
awaitResults: Record<string, RecordedResult>;
|
|
78
|
+
wait: WaitInfo;
|
|
79
|
+
};
|
|
80
|
+
|
|
81
|
+
/** Conditional whose chosen branch suspended; conditions are not re-evaluated. */
|
|
82
|
+
export type ConditionalFrame = {
|
|
83
|
+
kind: 'conditional';
|
|
84
|
+
stepId: string;
|
|
85
|
+
branchIndex: number;
|
|
86
|
+
child: SequenceFrame;
|
|
87
|
+
};
|
|
88
|
+
|
|
89
|
+
/** Loop suspended inside iteration `index`. */
|
|
90
|
+
export type LoopFrame = {
|
|
91
|
+
kind: 'loop';
|
|
92
|
+
stepId: string;
|
|
93
|
+
index: number;
|
|
94
|
+
/** Items resolved when a `for_each` loop started; absent for `while`. */
|
|
95
|
+
items?: unknown[];
|
|
96
|
+
/** Accumulator value at the start of iteration `index`. */
|
|
97
|
+
accumulator?: unknown;
|
|
98
|
+
child: SequenceFrame;
|
|
99
|
+
};
|
|
100
|
+
|
|
101
|
+
/** Settled state of one parallel branch when the block suspended. */
|
|
102
|
+
export type ParallelBranchFrame =
|
|
103
|
+
| { status: 'fulfilled'; outputDelta: Record<string, unknown> }
|
|
104
|
+
| {
|
|
105
|
+
status: 'suspended';
|
|
106
|
+
outputDelta: Record<string, unknown>;
|
|
107
|
+
child: StepFrame;
|
|
108
|
+
};
|
|
109
|
+
|
|
110
|
+
/** Parallel block with at least one suspended branch. */
|
|
111
|
+
export type ParallelFrame = {
|
|
112
|
+
kind: 'parallel';
|
|
113
|
+
stepId: string;
|
|
114
|
+
branches: ParallelBranchFrame[];
|
|
115
|
+
};
|
|
116
|
+
|
|
117
|
+
/** Frame of a single compiled step. `stepId` is the compiled (not instance) id. */
|
|
118
|
+
export type StepFrame =
|
|
119
|
+
| TaskFrame
|
|
120
|
+
| ConditionalFrame
|
|
121
|
+
| LoopFrame
|
|
122
|
+
| ParallelFrame;
|
|
123
|
+
|
|
124
|
+
/** Position inside a list of sequential steps. */
|
|
125
|
+
export type SequenceFrame = {
|
|
126
|
+
kind: 'sequence';
|
|
127
|
+
index: number;
|
|
128
|
+
/**
|
|
129
|
+
* `$accumulator` of the sequence's scope when it suspended. A loop that
|
|
130
|
+
* finished earlier in the sequence may have replaced the one the scope
|
|
131
|
+
* started with.
|
|
132
|
+
*/
|
|
133
|
+
accumulator?: unknown;
|
|
134
|
+
child: StepFrame;
|
|
135
|
+
};
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* Everything needed to resume a suspended run, in any process.
|
|
139
|
+
*
|
|
140
|
+
* The frame tree mirrors the compiled flow: each composite step records only
|
|
141
|
+
* the local state it needs to continue (sequence position, chosen branch,
|
|
142
|
+
* loop position, parallel branch outcomes), so resuming never replays work
|
|
143
|
+
* that already completed.
|
|
144
|
+
*/
|
|
145
|
+
export type WorkflowCheckpoint = {
|
|
146
|
+
version: typeof CHECKPOINT_VERSION;
|
|
147
|
+
/** Definition fingerprint the frames were taken against. */
|
|
148
|
+
fingerprint: string;
|
|
149
|
+
input: Record<string, unknown>;
|
|
150
|
+
output: Record<string, unknown>;
|
|
151
|
+
root: SequenceFrame;
|
|
152
|
+
/** Every open wait in the frame tree, in flow order. */
|
|
153
|
+
waits: WaitInfo[];
|
|
154
|
+
};
|
|
155
|
+
|
|
156
|
+
export type CheckpointValidationResult =
|
|
157
|
+
| { ok: true; checkpoint: WorkflowCheckpoint }
|
|
158
|
+
| { ok: false; error: WorkflowResumeError };
|
|
159
|
+
|
|
160
|
+
const recordSchema = z.record(z.string(), z.unknown());
|
|
161
|
+
const stepIdSchema = z.string().min(1);
|
|
162
|
+
const stepInfoSchema = z.object({
|
|
163
|
+
id: stepIdSchema,
|
|
164
|
+
name: z.string(),
|
|
165
|
+
type: z.enum(StepType),
|
|
166
|
+
});
|
|
167
|
+
const waitInfoSchema: z.ZodType<WaitInfo> = z.object({
|
|
168
|
+
waitId: z.string().min(1),
|
|
169
|
+
step: stepInfoSchema,
|
|
170
|
+
suspendKey: z.string().min(1),
|
|
171
|
+
reason: z.string().optional(),
|
|
172
|
+
data: z.unknown().optional(),
|
|
173
|
+
accepts: recordSchema.optional(),
|
|
174
|
+
payloadOptional: z.boolean().optional(),
|
|
175
|
+
});
|
|
176
|
+
const taskFrameSchema: z.ZodType<TaskFrame> = z.object({
|
|
177
|
+
kind: z.literal('task'),
|
|
178
|
+
stepId: stepIdSchema,
|
|
179
|
+
inputs: recordSchema,
|
|
180
|
+
awaitResults: z.record(
|
|
181
|
+
z.string(),
|
|
182
|
+
z.object({ value: z.unknown().optional() }),
|
|
183
|
+
),
|
|
184
|
+
wait: waitInfoSchema,
|
|
185
|
+
});
|
|
186
|
+
const conditionalFrameSchema: z.ZodType<ConditionalFrame> = z.lazy(() =>
|
|
187
|
+
z.object({
|
|
188
|
+
kind: z.literal('conditional'),
|
|
189
|
+
stepId: stepIdSchema,
|
|
190
|
+
branchIndex: z.int().nonnegative(),
|
|
191
|
+
child: sequenceFrameSchema,
|
|
192
|
+
}),
|
|
193
|
+
);
|
|
194
|
+
const loopFrameSchema: z.ZodType<LoopFrame> = z.lazy(() =>
|
|
195
|
+
z.object({
|
|
196
|
+
kind: z.literal('loop'),
|
|
197
|
+
stepId: stepIdSchema,
|
|
198
|
+
index: z.int().nonnegative(),
|
|
199
|
+
items: z.array(z.unknown()).optional(),
|
|
200
|
+
accumulator: z.unknown().optional(),
|
|
201
|
+
child: sequenceFrameSchema,
|
|
202
|
+
}),
|
|
203
|
+
);
|
|
204
|
+
const parallelFrameSchema: z.ZodType<ParallelFrame> = z.lazy(() =>
|
|
205
|
+
z.object({
|
|
206
|
+
kind: z.literal('parallel'),
|
|
207
|
+
stepId: stepIdSchema,
|
|
208
|
+
branches: z.array(
|
|
209
|
+
z.union([
|
|
210
|
+
z.object({ status: z.literal('fulfilled'), outputDelta: recordSchema }),
|
|
211
|
+
z.object({
|
|
212
|
+
status: z.literal('suspended'),
|
|
213
|
+
outputDelta: recordSchema,
|
|
214
|
+
child: stepFrameSchema,
|
|
215
|
+
}),
|
|
216
|
+
]),
|
|
217
|
+
),
|
|
218
|
+
}),
|
|
219
|
+
);
|
|
220
|
+
const stepFrameSchema: z.ZodType<StepFrame> = z.lazy(() =>
|
|
221
|
+
z.union([
|
|
222
|
+
taskFrameSchema,
|
|
223
|
+
conditionalFrameSchema,
|
|
224
|
+
loopFrameSchema,
|
|
225
|
+
parallelFrameSchema,
|
|
226
|
+
]),
|
|
227
|
+
);
|
|
228
|
+
const sequenceFrameSchema: z.ZodType<SequenceFrame> = z.lazy(() =>
|
|
229
|
+
z.object({
|
|
230
|
+
kind: z.literal('sequence'),
|
|
231
|
+
index: z.int().nonnegative(),
|
|
232
|
+
accumulator: z.unknown().optional(),
|
|
233
|
+
child: stepFrameSchema,
|
|
234
|
+
}),
|
|
235
|
+
);
|
|
236
|
+
|
|
237
|
+
/** Schema of a persisted {@link WorkflowCheckpoint}, for hosts to type storage. */
|
|
238
|
+
export const workflowCheckpointSchema: z.ZodType<WorkflowCheckpoint> = z.object(
|
|
239
|
+
{
|
|
240
|
+
version: z.literal(CHECKPOINT_VERSION),
|
|
241
|
+
fingerprint: z.string().min(1),
|
|
242
|
+
input: recordSchema,
|
|
243
|
+
output: recordSchema,
|
|
244
|
+
root: sequenceFrameSchema,
|
|
245
|
+
waits: z.array(waitInfoSchema).min(1),
|
|
246
|
+
},
|
|
247
|
+
);
|
|
248
|
+
|
|
249
|
+
/**
|
|
250
|
+
* Build the handle of a wait from the instance step that suspended and its
|
|
251
|
+
* suspend key.
|
|
252
|
+
*
|
|
253
|
+
* @param stepInstanceId Instance step id, including any loop iteration suffix.
|
|
254
|
+
* @param suspendKey Normalized suspend key within the step body.
|
|
255
|
+
* @returns The wait id.
|
|
256
|
+
*/
|
|
257
|
+
export const buildWaitId = (
|
|
258
|
+
stepInstanceId: string,
|
|
259
|
+
suspendKey: string,
|
|
260
|
+
): string => `${stepInstanceId}@${suspendKey}`;
|
|
261
|
+
|
|
262
|
+
/**
|
|
263
|
+
* List the open waits held by a frame tree, in flow order.
|
|
264
|
+
*
|
|
265
|
+
* @param frame Root or subtree of a checkpoint.
|
|
266
|
+
* @returns The waits of every suspended task under the frame.
|
|
267
|
+
*/
|
|
268
|
+
export function collectWaits(frame: SequenceFrame | StepFrame): WaitInfo[] {
|
|
269
|
+
switch (frame.kind) {
|
|
270
|
+
case 'task':
|
|
271
|
+
return [frame.wait];
|
|
272
|
+
case 'sequence':
|
|
273
|
+
case 'conditional':
|
|
274
|
+
case 'loop':
|
|
275
|
+
return collectWaits(frame.child);
|
|
276
|
+
case 'parallel':
|
|
277
|
+
return frame.branches.flatMap((branch) =>
|
|
278
|
+
branch.status === 'suspended' ? collectWaits(branch.child) : [],
|
|
279
|
+
);
|
|
280
|
+
}
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
/**
|
|
284
|
+
* Pick the wait a resume targets. `resume()` and `validateCheckpoint` both
|
|
285
|
+
* use it, so a payload is always checked against the wait it would resolve.
|
|
286
|
+
*
|
|
287
|
+
* @param waits Open waits of the suspended run.
|
|
288
|
+
* @param waitId Requested wait, optional when exactly one wait is open.
|
|
289
|
+
* @returns The targeted wait.
|
|
290
|
+
* @throws {WorkflowWaitNotFoundError} When `waitId` is not an open wait.
|
|
291
|
+
* @throws {WorkflowWaitAmbiguousError} When several waits are open and no
|
|
292
|
+
* `waitId` is given.
|
|
293
|
+
*/
|
|
294
|
+
export function selectWait(waits: WaitInfo[], waitId?: string): WaitInfo {
|
|
295
|
+
const openWaitIds = waits.map((candidate) => candidate.waitId);
|
|
296
|
+
if (waitId === undefined) {
|
|
297
|
+
if (waits.length === 1) {
|
|
298
|
+
return waits[0];
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
throw new WorkflowWaitAmbiguousError(openWaitIds);
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
const wait = waits.find((candidate) => candidate.waitId === waitId);
|
|
305
|
+
if (!wait) {
|
|
306
|
+
throw new WorkflowWaitNotFoundError(waitId, openWaitIds);
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
return wait;
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
/**
|
|
313
|
+
* Check that a frame was taken for the given compiled step.
|
|
314
|
+
*
|
|
315
|
+
* @param frame The frame about to be resumed, if any.
|
|
316
|
+
* @param step The compiled step it is being handed to.
|
|
317
|
+
* @param path Location used in the error message.
|
|
318
|
+
* @throws {WorkflowCheckpointInvalidError} When the frame belongs elsewhere.
|
|
319
|
+
*/
|
|
320
|
+
export function assertFrameMatchesStep(
|
|
321
|
+
frame: StepFrame | undefined,
|
|
322
|
+
step: CompiledStep,
|
|
323
|
+
path: Array<string | number> = [],
|
|
324
|
+
): void {
|
|
325
|
+
if (!frame) {
|
|
326
|
+
return;
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
if ((frame.kind as string) !== step.type || frame.stepId !== step.id) {
|
|
330
|
+
throw new WorkflowCheckpointInvalidError(
|
|
331
|
+
'structure',
|
|
332
|
+
`Checkpoint expects ${frame.kind} step "${frame.stepId}" but the flow ` +
|
|
333
|
+
`has ${step.type} step "${step.id}".`,
|
|
334
|
+
{ path },
|
|
335
|
+
);
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
/**
|
|
340
|
+
* Decide whether a checkpoint can resume against a compiled workflow, without
|
|
341
|
+
* running anything.
|
|
342
|
+
*
|
|
343
|
+
* Checks, in order: presence and shape, format version, definition
|
|
344
|
+
* fingerprint, that every frame lines up with the compiled step it names, that
|
|
345
|
+
* the `waits` index matches the frame tree, and (optionally) that a given wait
|
|
346
|
+
* is open and accepts a given payload.
|
|
347
|
+
*
|
|
348
|
+
* @param compiled The compiled workflow the run will resume against.
|
|
349
|
+
* @param checkpoint The persisted checkpoint, as stored.
|
|
350
|
+
* @param options.waitId Wait the caller is about to resume.
|
|
351
|
+
* @param options.resumeData Payload the caller is about to resume with. When
|
|
352
|
+
* the key is present, it is checked against the wait `resume()` would pick:
|
|
353
|
+
* the one named by `waitId`, or the only open wait.
|
|
354
|
+
* @returns The parsed checkpoint, or the typed reason it cannot resume.
|
|
355
|
+
*/
|
|
356
|
+
export function validateCheckpoint(
|
|
357
|
+
compiled: CompiledWorkflow,
|
|
358
|
+
checkpoint: unknown,
|
|
359
|
+
options: { waitId?: string; resumeData?: unknown } = {},
|
|
360
|
+
): CheckpointValidationResult {
|
|
361
|
+
try {
|
|
362
|
+
const parsed = parseCheckpoint(checkpoint);
|
|
363
|
+
const actual = fingerprintWorkflow(compiled);
|
|
364
|
+
if (parsed.fingerprint !== actual) {
|
|
365
|
+
throw new WorkflowDefinitionDriftError(parsed.fingerprint, actual);
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
assertSequenceMatches(compiled.flow, parsed.root, ['root']);
|
|
369
|
+
assertWaitIndex(parsed);
|
|
370
|
+
|
|
371
|
+
if (options.waitId !== undefined || 'resumeData' in options) {
|
|
372
|
+
const wait = selectWait(parsed.waits, options.waitId);
|
|
373
|
+
if ('resumeData' in options) {
|
|
374
|
+
const payload = checkResumePayload(wait, options.resumeData);
|
|
375
|
+
if (!payload.ok) {
|
|
376
|
+
throw payload.error;
|
|
377
|
+
}
|
|
378
|
+
}
|
|
379
|
+
}
|
|
380
|
+
|
|
381
|
+
return { ok: true, checkpoint: parsed };
|
|
382
|
+
} catch (error) {
|
|
383
|
+
if (error instanceof WorkflowResumeError) {
|
|
384
|
+
return { ok: false, error };
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
throw error;
|
|
388
|
+
}
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
const parseCheckpoint = (checkpoint: unknown): WorkflowCheckpoint => {
|
|
392
|
+
if (checkpoint === null || checkpoint === undefined) {
|
|
393
|
+
throw new WorkflowCheckpointInvalidError(
|
|
394
|
+
'missing',
|
|
395
|
+
'No checkpoint was persisted for this run.',
|
|
396
|
+
);
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
if (
|
|
400
|
+
isRecord(checkpoint) &&
|
|
401
|
+
checkpoint.version !== undefined &&
|
|
402
|
+
checkpoint.version !== CHECKPOINT_VERSION
|
|
403
|
+
) {
|
|
404
|
+
throw new WorkflowCheckpointInvalidError(
|
|
405
|
+
'unsupported_version',
|
|
406
|
+
`Unsupported checkpoint version ${String(checkpoint.version)}; ` +
|
|
407
|
+
`expected ${CHECKPOINT_VERSION}.`,
|
|
408
|
+
);
|
|
409
|
+
}
|
|
410
|
+
|
|
411
|
+
const result = workflowCheckpointSchema.safeParse(checkpoint);
|
|
412
|
+
if (!result.success) {
|
|
413
|
+
const issues = result.error.issues.map(
|
|
414
|
+
(issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`,
|
|
415
|
+
);
|
|
416
|
+
|
|
417
|
+
throw new WorkflowCheckpointInvalidError(
|
|
418
|
+
'malformed',
|
|
419
|
+
`Checkpoint does not match the expected shape: ${issues.join('; ')}`,
|
|
420
|
+
{ issues },
|
|
421
|
+
);
|
|
422
|
+
}
|
|
423
|
+
|
|
424
|
+
return result.data;
|
|
425
|
+
};
|
|
426
|
+
const structureError = (message: string, path: Array<string | number>) =>
|
|
427
|
+
new WorkflowCheckpointInvalidError('structure', message, { path });
|
|
428
|
+
const assertSequenceMatches = (
|
|
429
|
+
steps: CompiledStep[],
|
|
430
|
+
frame: SequenceFrame,
|
|
431
|
+
path: Array<string | number>,
|
|
432
|
+
): void => {
|
|
433
|
+
const step = steps[frame.index];
|
|
434
|
+
if (!step) {
|
|
435
|
+
throw structureError(
|
|
436
|
+
`Sequence position ${frame.index} is out of range (${steps.length} steps).`,
|
|
437
|
+
path,
|
|
438
|
+
);
|
|
439
|
+
}
|
|
440
|
+
|
|
441
|
+
assertStepMatches(step, frame.child, [...path, frame.index]);
|
|
442
|
+
};
|
|
443
|
+
const assertStepMatches = (
|
|
444
|
+
step: CompiledStep,
|
|
445
|
+
frame: StepFrame,
|
|
446
|
+
path: Array<string | number>,
|
|
447
|
+
): void => {
|
|
448
|
+
assertFrameMatchesStep(frame, step, path);
|
|
449
|
+
|
|
450
|
+
switch (step.type) {
|
|
451
|
+
case StepType.Task:
|
|
452
|
+
return;
|
|
453
|
+
case StepType.Conditional:
|
|
454
|
+
return assertConditionalMatches(step, frame as ConditionalFrame, path);
|
|
455
|
+
case StepType.Loop:
|
|
456
|
+
return assertLoopMatches(step, frame as LoopFrame, path);
|
|
457
|
+
case StepType.Parallel:
|
|
458
|
+
return assertParallelMatches(step, frame as ParallelFrame, path);
|
|
459
|
+
}
|
|
460
|
+
};
|
|
461
|
+
const assertConditionalMatches = (
|
|
462
|
+
step: ConditionalStep,
|
|
463
|
+
frame: ConditionalFrame,
|
|
464
|
+
path: Array<string | number>,
|
|
465
|
+
): void => {
|
|
466
|
+
const branch = step.branches[frame.branchIndex];
|
|
467
|
+
if (!branch) {
|
|
468
|
+
throw structureError(
|
|
469
|
+
`Branch ${frame.branchIndex} does not exist on conditional "${step.id}".`,
|
|
470
|
+
path,
|
|
471
|
+
);
|
|
472
|
+
}
|
|
473
|
+
|
|
474
|
+
assertSequenceMatches(branch.steps, frame.child, [
|
|
475
|
+
...path,
|
|
476
|
+
'branch',
|
|
477
|
+
frame.branchIndex,
|
|
478
|
+
]);
|
|
479
|
+
};
|
|
480
|
+
const assertLoopMatches = (
|
|
481
|
+
step: LoopStep,
|
|
482
|
+
frame: LoopFrame,
|
|
483
|
+
path: Array<string | number>,
|
|
484
|
+
): void => {
|
|
485
|
+
if (step.loopType === 'for_each') {
|
|
486
|
+
if (!frame.items || frame.index >= frame.items.length) {
|
|
487
|
+
throw structureError(
|
|
488
|
+
`for_each loop "${step.id}" is suspended at iteration ${frame.index} ` +
|
|
489
|
+
`of ${frame.items?.length ?? 0} recorded items.`,
|
|
490
|
+
path,
|
|
491
|
+
);
|
|
492
|
+
}
|
|
493
|
+
} else if (frame.items !== undefined) {
|
|
494
|
+
throw structureError(
|
|
495
|
+
`while loop "${step.id}" cannot carry for_each items.`,
|
|
496
|
+
path,
|
|
497
|
+
);
|
|
498
|
+
}
|
|
499
|
+
|
|
500
|
+
assertSequenceMatches(step.steps, frame.child, [...path, frame.index]);
|
|
501
|
+
};
|
|
502
|
+
const assertParallelMatches = (
|
|
503
|
+
step: ParallelStep,
|
|
504
|
+
frame: ParallelFrame,
|
|
505
|
+
path: Array<string | number>,
|
|
506
|
+
): void => {
|
|
507
|
+
if (frame.branches.length !== step.steps.length) {
|
|
508
|
+
throw structureError(
|
|
509
|
+
`Parallel "${step.id}" has ${step.steps.length} branches but the ` +
|
|
510
|
+
`checkpoint records ${frame.branches.length}.`,
|
|
511
|
+
path,
|
|
512
|
+
);
|
|
513
|
+
}
|
|
514
|
+
|
|
515
|
+
let suspended = 0;
|
|
516
|
+
frame.branches.forEach((branch, index) => {
|
|
517
|
+
if (branch.status === 'suspended') {
|
|
518
|
+
suspended += 1;
|
|
519
|
+
assertStepMatches(step.steps[index], branch.child, [
|
|
520
|
+
...path,
|
|
521
|
+
'parallel',
|
|
522
|
+
index,
|
|
523
|
+
]);
|
|
524
|
+
} else if (step.strategy === 'wait_any') {
|
|
525
|
+
// A fulfilled branch wins a wait_any race, so it can never be parked.
|
|
526
|
+
throw structureError(
|
|
527
|
+
`wait_any parallel "${step.id}" cannot record a fulfilled branch.`,
|
|
528
|
+
path,
|
|
529
|
+
);
|
|
530
|
+
}
|
|
531
|
+
});
|
|
532
|
+
|
|
533
|
+
if (suspended === 0) {
|
|
534
|
+
throw structureError(
|
|
535
|
+
`Parallel "${step.id}" is recorded as suspended without a suspended branch.`,
|
|
536
|
+
path,
|
|
537
|
+
);
|
|
538
|
+
}
|
|
539
|
+
};
|
|
540
|
+
const assertWaitIndex = (checkpoint: WorkflowCheckpoint): void => {
|
|
541
|
+
const expected = collectWaits(checkpoint.root).map((wait) => wait.waitId);
|
|
542
|
+
const actual = checkpoint.waits.map((wait) => wait.waitId);
|
|
543
|
+
|
|
544
|
+
if (
|
|
545
|
+
expected.length !== actual.length ||
|
|
546
|
+
expected.some((waitId, index) => waitId !== actual[index])
|
|
547
|
+
) {
|
|
548
|
+
throw structureError(
|
|
549
|
+
`Checkpoint waits [${actual.join(', ')}] do not match the suspended ` +
|
|
550
|
+
`steps [${expected.join(', ')}].`,
|
|
551
|
+
['waits'],
|
|
552
|
+
);
|
|
553
|
+
}
|
|
554
|
+
|
|
555
|
+
if (new Set(expected).size !== expected.length) {
|
|
556
|
+
throw structureError(
|
|
557
|
+
`Checkpoint holds duplicate waits [${expected.join(', ')}].`,
|
|
558
|
+
['waits'],
|
|
559
|
+
);
|
|
560
|
+
}
|
|
561
|
+
};
|