@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.
Files changed (134) hide show
  1. package/README.md +67 -15
  2. package/dist/cjs/action/abstract-action.js +13 -1
  3. package/dist/cjs/checkpoint.js +301 -0
  4. package/dist/cjs/context.js +11 -27
  5. package/dist/cjs/dsl.types.js +3 -0
  6. package/dist/cjs/errors.js +116 -9
  7. package/dist/cjs/index.js +15 -6
  8. package/dist/cjs/resume-payload.js +257 -0
  9. package/dist/cjs/runner-runtime-control.js +181 -306
  10. package/dist/cjs/step-executors/conditional-executor.js +27 -29
  11. package/dist/cjs/step-executors/loop-executor.js +53 -62
  12. package/dist/cjs/step-executors/parallel-executor.js +169 -102
  13. package/dist/cjs/step-executors/task-executor.js +180 -96
  14. package/dist/cjs/utils/clone.js +73 -0
  15. package/dist/cjs/workflow-fingerprint.js +138 -0
  16. package/dist/cjs/workflow-runner.js +220 -155
  17. package/dist/cjs/workflow.js +24 -12
  18. package/dist/esm/action/abstract-action.js +14 -2
  19. package/dist/esm/checkpoint.js +293 -0
  20. package/dist/esm/context.js +11 -27
  21. package/dist/esm/dsl.types.js +3 -0
  22. package/dist/esm/errors.js +105 -6
  23. package/dist/esm/index.js +3 -3
  24. package/dist/esm/resume-payload.js +250 -0
  25. package/dist/esm/runner-runtime-control.js +179 -303
  26. package/dist/esm/step-executors/conditional-executor.js +27 -29
  27. package/dist/esm/step-executors/loop-executor.js +53 -62
  28. package/dist/esm/step-executors/parallel-executor.js +165 -98
  29. package/dist/esm/step-executors/task-executor.js +181 -97
  30. package/dist/esm/utils/clone.js +67 -0
  31. package/dist/esm/workflow-fingerprint.js +134 -0
  32. package/dist/esm/workflow-runner.js +220 -155
  33. package/dist/esm/workflow.js +24 -12
  34. package/dist/types/action/abstract-action.d.ts.map +1 -1
  35. package/dist/types/action/action.types.d.ts +0 -14
  36. package/dist/types/action/action.types.d.ts.map +1 -1
  37. package/dist/types/checkpoint.d.ts +188 -0
  38. package/dist/types/checkpoint.d.ts.map +1 -0
  39. package/dist/types/context.d.ts +45 -11
  40. package/dist/types/context.d.ts.map +1 -1
  41. package/dist/types/dsl.types.d.ts.map +1 -1
  42. package/dist/types/errors.d.ts +77 -3
  43. package/dist/types/errors.d.ts.map +1 -1
  44. package/dist/types/index.d.ts +6 -7
  45. package/dist/types/index.d.ts.map +1 -1
  46. package/dist/types/resume-payload.d.ts +69 -0
  47. package/dist/types/resume-payload.d.ts.map +1 -0
  48. package/dist/types/runner-runtime-control.d.ts +63 -51
  49. package/dist/types/runner-runtime-control.d.ts.map +1 -1
  50. package/dist/types/step-executors/conditional-executor.d.ts +6 -3
  51. package/dist/types/step-executors/conditional-executor.d.ts.map +1 -1
  52. package/dist/types/step-executors/loop-executor.d.ts +6 -4
  53. package/dist/types/step-executors/loop-executor.d.ts.map +1 -1
  54. package/dist/types/step-executors/parallel-executor.d.ts +11 -3
  55. package/dist/types/step-executors/parallel-executor.d.ts.map +1 -1
  56. package/dist/types/step-executors/task-executor.d.ts +11 -4
  57. package/dist/types/step-executors/task-executor.d.ts.map +1 -1
  58. package/dist/types/step-executors/types.d.ts +21 -13
  59. package/dist/types/step-executors/types.d.ts.map +1 -1
  60. package/dist/types/utils/clone.d.ts +33 -0
  61. package/dist/types/utils/clone.d.ts.map +1 -0
  62. package/dist/types/workflow-event-emitter.d.ts +29 -5
  63. package/dist/types/workflow-event-emitter.d.ts.map +1 -1
  64. package/dist/types/workflow-fingerprint.d.ts +14 -0
  65. package/dist/types/workflow-fingerprint.d.ts.map +1 -0
  66. package/dist/types/workflow-runner.d.ts +83 -41
  67. package/dist/types/workflow-runner.d.ts.map +1 -1
  68. package/dist/types/workflow-types.d.ts +25 -54
  69. package/dist/types/workflow-types.d.ts.map +1 -1
  70. package/dist/types/workflow.d.ts +24 -9
  71. package/dist/types/workflow.d.ts.map +1 -1
  72. package/examples/defs-bindings-agent/bindings.ts +1 -1
  73. package/examples/defs-bindings-agent/workflow.ts +3 -2
  74. package/examples/full/actions/await-user-input.ts +3 -2
  75. package/examples/full/actions/call-llm.ts +18 -18
  76. package/examples/full/actions/create-ticket.ts +1 -2
  77. package/examples/full/actions/decision-router.ts +6 -2
  78. package/examples/full/actions/get-calendar-events.ts +1 -2
  79. package/examples/full/actions/get-user-profile.ts +1 -2
  80. package/examples/full/actions/query-memory.ts +1 -2
  81. package/examples/full/actions/search-web.ts +1 -2
  82. package/examples/full/actions/send-email.ts +3 -2
  83. package/examples/full/workflow.ts +3 -2
  84. package/examples/loop/actions/await-reply.ts +2 -7
  85. package/examples/loop/workflow.ts +4 -2
  86. package/examples/suspend-resume/actions/wait-for-user.ts +11 -9
  87. package/examples/suspend-resume/workflow.ts +51 -11
  88. package/package.json +3 -3
  89. package/src/__tests__/checkpoint.test.ts +2568 -0
  90. package/src/__tests__/resume-payload.test.ts +245 -0
  91. package/src/__tests__/runner-runtime-control.test.ts +265 -0
  92. package/src/__tests__/workflow-fingerprint.test.ts +165 -0
  93. package/src/__tests__/workflow-runner.test.ts +167 -144
  94. package/src/__tests__/workflow.test.ts +97 -6
  95. package/src/action/abstract-action.ts +21 -2
  96. package/src/action/action.types.ts +0 -12
  97. package/src/checkpoint.ts +561 -0
  98. package/src/context.ts +51 -41
  99. package/src/dsl.types.ts +3 -0
  100. package/src/errors.ts +161 -8
  101. package/src/index.ts +33 -14
  102. package/src/resume-payload.ts +326 -0
  103. package/src/runner-runtime-control.ts +222 -456
  104. package/src/step-executors/conditional-executor.test.ts +77 -46
  105. package/src/step-executors/conditional-executor.ts +47 -40
  106. package/src/step-executors/loop-executor.test.ts +106 -92
  107. package/src/step-executors/loop-executor.ts +84 -101
  108. package/src/step-executors/parallel-executor.test.ts +300 -89
  109. package/src/step-executors/parallel-executor.ts +243 -125
  110. package/src/step-executors/task-executor.test.ts +321 -51
  111. package/src/step-executors/task-executor.ts +232 -145
  112. package/src/step-executors/types.ts +23 -22
  113. package/src/utils/clone.ts +75 -0
  114. package/src/workflow-event-emitter.ts +32 -6
  115. package/src/workflow-fingerprint.ts +159 -0
  116. package/src/workflow-runner.ts +325 -209
  117. package/src/workflow-types.ts +25 -56
  118. package/src/workflow.ts +41 -34
  119. package/dist/cjs/step-executors/suspension-continuation.js +0 -27
  120. package/dist/cjs/suspension-rebuilder.js +0 -265
  121. package/dist/cjs/utils/deferred.js +0 -17
  122. package/dist/esm/step-executors/suspension-continuation.js +0 -24
  123. package/dist/esm/suspension-rebuilder.js +0 -260
  124. package/dist/esm/utils/deferred.js +0 -14
  125. package/dist/types/step-executors/suspension-continuation.d.ts +0 -10
  126. package/dist/types/step-executors/suspension-continuation.d.ts.map +0 -1
  127. package/dist/types/suspension-rebuilder.d.ts +0 -67
  128. package/dist/types/suspension-rebuilder.d.ts.map +0 -1
  129. package/dist/types/utils/deferred.d.ts +0 -7
  130. package/dist/types/utils/deferred.d.ts.map +0 -1
  131. package/src/__tests__/suspension-rebuilder.test.ts +0 -404
  132. package/src/step-executors/suspension-continuation.ts +0 -31
  133. package/src/suspension-rebuilder.ts +0 -446
  134. 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
+ };
@@ -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 continuation.
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 safeCloneRecord(this.state);
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
- };
@@ -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
  }));
@@ -9,14 +9,93 @@ export class WorkflowCancellationError extends Error {
9
9
  this.name = 'WorkflowCancellationError';
10
10
  }
11
11
  }
12
- export class ParallelSuspensionError extends Error {
13
- constructor() {
14
- super('workflow.suspend() is not supported inside a parallel block.');
15
- this.name = 'ParallelSuspensionError';
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
- export const isWorkflowCancellationError = (error) => error instanceof WorkflowCancellationError ||
19
- (error instanceof Error && error.name === 'WorkflowCancellationError');
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 { NonDeterministicWorkflowError } from './runner-runtime-control';
14
- export { ParallelSuspensionError, WorkflowCancellationError } from './errors';
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';