@hexabot-ai/agentic 3.4.0-beta.2 → 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
|
@@ -4,13 +4,31 @@
|
|
|
4
4
|
* Full terms: see LICENSE.md.
|
|
5
5
|
*/
|
|
6
6
|
|
|
7
|
-
import {
|
|
8
|
-
|
|
7
|
+
import {
|
|
8
|
+
buildWaitId,
|
|
9
|
+
type RecordedResult,
|
|
10
|
+
type TaskFrame,
|
|
11
|
+
type WaitInfo,
|
|
12
|
+
} from '../checkpoint';
|
|
13
|
+
import {
|
|
14
|
+
createLinkedAbortController,
|
|
15
|
+
getAbortReason,
|
|
16
|
+
isWorkflowResumeRejectedError,
|
|
17
|
+
throwIfAborted,
|
|
18
|
+
WorkflowCancellationError,
|
|
19
|
+
type WorkflowResumeRejectedError,
|
|
20
|
+
} from '../errors';
|
|
21
|
+
import type {
|
|
22
|
+
RunnerRuntimeControl,
|
|
23
|
+
RuntimeSuspensionRequest,
|
|
24
|
+
StepReplaySeed,
|
|
25
|
+
} from '../runner-runtime-control';
|
|
26
|
+
import { cloneAsJson, cloneValue } from '../utils/clone';
|
|
27
|
+
import type { StepInfo } from '../workflow-event-emitter';
|
|
9
28
|
import type {
|
|
10
29
|
CompiledTask,
|
|
11
30
|
EvaluationScope,
|
|
12
31
|
ExecutionState,
|
|
13
|
-
Suspension,
|
|
14
32
|
TaskStep,
|
|
15
33
|
} from '../workflow-types';
|
|
16
34
|
import { evaluateMapping } from '../workflow-values';
|
|
@@ -24,63 +42,102 @@ type TaskProgressOutcome =
|
|
|
24
42
|
| { type: 'suspended'; request: RuntimeSuspensionRequest };
|
|
25
43
|
|
|
26
44
|
/**
|
|
27
|
-
* Execute a task step
|
|
45
|
+
* Execute a task step, returning a frame when its action suspends.
|
|
46
|
+
*
|
|
47
|
+
* Given a frame, the step either stays parked (its wait is not resolved by
|
|
48
|
+
* this pass) or re-runs its action body: earlier `suspend()` calls resolve
|
|
49
|
+
* from the frame, including the one this pass resolved. A body that refuses
|
|
50
|
+
* that payload returns the frame unchanged, so the wait stays open.
|
|
28
51
|
*
|
|
29
52
|
* @param env Executor environment with compiled workflow and helpers.
|
|
30
53
|
* @param step The compiled task step to execute.
|
|
31
54
|
* @param state Mutable workflow execution state.
|
|
32
55
|
* @param _path Location of the step within the workflow (unused in this executor).
|
|
33
|
-
* @
|
|
56
|
+
* @param frame Frame returned when this step previously suspended.
|
|
57
|
+
* @returns A frame if the task suspends, otherwise void.
|
|
34
58
|
*/
|
|
35
59
|
export async function executeTaskStep(
|
|
36
60
|
env: StepExecutorEnv,
|
|
37
61
|
step: TaskStep,
|
|
38
62
|
state: ExecutionState,
|
|
39
63
|
_path: Array<number | string>,
|
|
40
|
-
|
|
64
|
+
frame?: TaskFrame,
|
|
65
|
+
): Promise<TaskFrame | void> {
|
|
41
66
|
void _path;
|
|
42
67
|
const task = env.compiled.tasks[step.taskName];
|
|
43
68
|
if (!task) {
|
|
44
69
|
throw new Error(`Task "${step.taskName}" is not defined.`);
|
|
45
70
|
}
|
|
46
71
|
|
|
72
|
+
// A parked wait that this pass does not resolve stays exactly as it was.
|
|
73
|
+
if (frame && !env.resolutions.has(frame.wait.waitId)) {
|
|
74
|
+
return frame;
|
|
75
|
+
}
|
|
76
|
+
|
|
47
77
|
const stepInfo = env.buildInstanceStepInfo(step, state.iterationStack);
|
|
48
78
|
if (env.signal.aborted) {
|
|
49
79
|
const error = getAbortReason(env.signal);
|
|
50
|
-
recordTaskCancellation(env, stepInfo, error);
|
|
80
|
+
recordTaskCancellation(env, stepInfo, error, frame?.wait);
|
|
51
81
|
throw error;
|
|
52
82
|
}
|
|
53
83
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
accumulator: state.accumulator,
|
|
60
|
-
};
|
|
61
|
-
const inputs = await evaluateMapping(task.inputs, scope);
|
|
84
|
+
// Resumed bodies reuse the inputs they first ran with: re-evaluating could
|
|
85
|
+
// differ, e.g. when an expression depends on the event that woke the run.
|
|
86
|
+
const inputs = frame
|
|
87
|
+
? cloneValue(frame.inputs)
|
|
88
|
+
: await evaluateMapping(task.inputs, buildScope(env, state));
|
|
62
89
|
if (env.signal.aborted) {
|
|
63
90
|
const error = getAbortReason(env.signal);
|
|
64
|
-
recordTaskCancellation(env, stepInfo, error);
|
|
91
|
+
recordTaskCancellation(env, stepInfo, error, frame?.wait);
|
|
65
92
|
throw error;
|
|
66
93
|
}
|
|
67
|
-
|
|
94
|
+
// Kept apart from the object the body gets, so that a body changing its
|
|
95
|
+
// inputs cannot change the inputs every later pass replays.
|
|
96
|
+
const recordedInputs = frame ? frame.inputs : copyInputs(inputs);
|
|
97
|
+
const resumeData = frame ? env.resolutions.get(frame.wait.waitId) : undefined;
|
|
98
|
+
const seed: StepReplaySeed | undefined = frame
|
|
99
|
+
? {
|
|
100
|
+
awaitResults: {
|
|
101
|
+
...readRecordedResults(frame.awaitResults),
|
|
102
|
+
[frame.wait.suspendKey]: resumeData,
|
|
103
|
+
},
|
|
104
|
+
expected: {
|
|
105
|
+
suspendKey: frame.wait.suspendKey,
|
|
106
|
+
reason: frame.wait.reason,
|
|
107
|
+
},
|
|
108
|
+
}
|
|
109
|
+
: undefined;
|
|
68
110
|
const stepExecution = env.recordStepExecution(stepInfo, {
|
|
69
111
|
action: task.actionName,
|
|
70
112
|
status: 'running',
|
|
71
113
|
startedAt: Date.now(),
|
|
114
|
+
endedAt: undefined,
|
|
115
|
+
reason: undefined,
|
|
72
116
|
input: inputs,
|
|
73
117
|
context: { before: env.context.snapshot() },
|
|
74
118
|
});
|
|
75
|
-
env.
|
|
76
|
-
env.setCurrentStep(stepInfo);
|
|
119
|
+
env.runtime.beginStep(stepInfo, { seed });
|
|
77
120
|
env.markSnapshot(stepInfo, 'running');
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
121
|
+
if (frame) {
|
|
122
|
+
env.emit('hook:step:resumed', {
|
|
123
|
+
runId: env.runId,
|
|
124
|
+
step: stepInfo,
|
|
125
|
+
stepExecution,
|
|
126
|
+
wait: frame.wait,
|
|
127
|
+
resumeData,
|
|
128
|
+
});
|
|
129
|
+
} else {
|
|
130
|
+
env.emit('hook:step:start', {
|
|
131
|
+
runId: env.runId,
|
|
132
|
+
step: stepInfo,
|
|
133
|
+
stepExecution,
|
|
134
|
+
});
|
|
135
|
+
}
|
|
83
136
|
|
|
137
|
+
// Each action gets its own signal so a suspension can stop its body
|
|
138
|
+
// without cancelling anything else.
|
|
139
|
+
const { controller, unlink } = createLinkedAbortController(env.signal);
|
|
140
|
+
let outcome: TaskProgressOutcome;
|
|
84
141
|
try {
|
|
85
142
|
throwIfAborted(env.signal);
|
|
86
143
|
|
|
@@ -90,77 +147,115 @@ export async function executeTaskStep(
|
|
|
90
147
|
env.context,
|
|
91
148
|
task.settings,
|
|
92
149
|
task.bindings,
|
|
93
|
-
|
|
150
|
+
controller.signal,
|
|
94
151
|
),
|
|
95
152
|
);
|
|
96
|
-
|
|
153
|
+
outcome = await waitForTaskProgress(
|
|
154
|
+
controller.signal,
|
|
155
|
+
env.runtime,
|
|
156
|
+
actionPromise,
|
|
157
|
+
);
|
|
158
|
+
} catch (error) {
|
|
159
|
+
env.runtime.endStep();
|
|
160
|
+
throw error;
|
|
161
|
+
} finally {
|
|
162
|
+
unlink();
|
|
163
|
+
}
|
|
97
164
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
outcome.value,
|
|
165
|
+
switch (outcome.type) {
|
|
166
|
+
case 'suspended':
|
|
167
|
+
env.runtime.endStep();
|
|
168
|
+
// The body is parked on a promise that never settles. Aborting it clears
|
|
169
|
+
// its timeout and stops its retry loop; resuming re-runs it instead.
|
|
170
|
+
controller.abort(
|
|
171
|
+
new WorkflowCancellationError(`Step "${stepInfo.id}" suspended.`),
|
|
106
172
|
);
|
|
107
173
|
|
|
174
|
+
return suspendTask(env, step, stepInfo, recordedInputs, outcome.request);
|
|
175
|
+
case 'completed':
|
|
176
|
+
try {
|
|
177
|
+
env.runtime.endStep({ completed: true });
|
|
178
|
+
} catch (error) {
|
|
179
|
+
recordTaskFailure(env, stepInfo, error);
|
|
180
|
+
throw error;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
await completeTask(env, stepInfo, task, state, outcome.value);
|
|
184
|
+
|
|
108
185
|
return undefined;
|
|
109
|
-
|
|
186
|
+
case 'failed': {
|
|
187
|
+
const { error } = outcome;
|
|
188
|
+
// Only a body that already read the resolved payload can refuse it.
|
|
189
|
+
const rejected =
|
|
190
|
+
frame !== undefined &&
|
|
191
|
+
isWorkflowResumeRejectedError(error) &&
|
|
192
|
+
env.runtime.hasReachedResolvedSuspension();
|
|
193
|
+
env.runtime.endStep();
|
|
194
|
+
if (rejected) {
|
|
195
|
+
return keepWaiting(env, stepInfo, frame, error);
|
|
196
|
+
}
|
|
110
197
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
recordTaskFailure(env, stepInfo, outcome.error);
|
|
114
|
-
throw outcome.error;
|
|
198
|
+
recordTaskFailure(env, stepInfo, error);
|
|
199
|
+
throw error;
|
|
115
200
|
}
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
env
|
|
119
|
-
recordTaskCancellation(env, stepInfo, outcome.error);
|
|
201
|
+
case 'cancelled':
|
|
202
|
+
env.runtime.endStep();
|
|
203
|
+
recordTaskCancellation(env, stepInfo, outcome.error, frame?.wait);
|
|
120
204
|
throw outcome.error;
|
|
121
|
-
}
|
|
122
|
-
|
|
123
|
-
return buildSuspensionContinuation(
|
|
124
|
-
env,
|
|
125
|
-
stepInfo.id,
|
|
126
|
-
stepInfo,
|
|
127
|
-
task,
|
|
128
|
-
state,
|
|
129
|
-
actionPromise,
|
|
130
|
-
outcome.request,
|
|
131
|
-
);
|
|
132
|
-
} finally {
|
|
133
|
-
env.setCurrentStep(undefined);
|
|
134
205
|
}
|
|
135
206
|
}
|
|
136
207
|
|
|
137
|
-
|
|
208
|
+
/**
|
|
209
|
+
* Copy the inputs a body first runs with, the way the checkpoint stores them.
|
|
210
|
+
* Inputs JSON cannot encode are returned as they are: building the checkpoint
|
|
211
|
+
* reports them if the step suspends.
|
|
212
|
+
*/
|
|
213
|
+
const copyInputs = (
|
|
214
|
+
inputs: Record<string, unknown>,
|
|
215
|
+
): Record<string, unknown> => {
|
|
216
|
+
try {
|
|
217
|
+
return cloneAsJson(inputs);
|
|
218
|
+
} catch {
|
|
219
|
+
return inputs;
|
|
220
|
+
}
|
|
221
|
+
};
|
|
222
|
+
const buildScope = (
|
|
138
223
|
env: StepExecutorEnv,
|
|
139
|
-
|
|
224
|
+
state: ExecutionState,
|
|
225
|
+
): EvaluationScope => ({
|
|
226
|
+
input: state.input,
|
|
227
|
+
context: env.context.state,
|
|
228
|
+
output: state.output,
|
|
229
|
+
iteration: state.iteration,
|
|
230
|
+
accumulator: state.accumulator,
|
|
231
|
+
});
|
|
232
|
+
const waitForTaskProgress = async (
|
|
233
|
+
signal: AbortSignal,
|
|
234
|
+
runtime: RunnerRuntimeControl,
|
|
140
235
|
actionPromise: Promise<unknown>,
|
|
141
236
|
): Promise<TaskProgressOutcome> => {
|
|
142
237
|
const completion = actionPromise.then(
|
|
143
238
|
(value): TaskProgressOutcome => ({ type: 'completed', value }),
|
|
144
239
|
(error): TaskProgressOutcome => ({ type: 'failed', error }),
|
|
145
240
|
);
|
|
146
|
-
const suspension =
|
|
147
|
-
.
|
|
241
|
+
const suspension = runtime
|
|
242
|
+
.waitForSuspension()
|
|
148
243
|
.then<TaskProgressOutcome>((request) => ({ type: 'suspended', request }));
|
|
149
244
|
let cleanupCancellation = () => undefined;
|
|
150
245
|
const cancellation = new Promise<TaskProgressOutcome>((resolve) => {
|
|
151
|
-
if (
|
|
152
|
-
resolve({ type: 'cancelled', error: getAbortReason(
|
|
246
|
+
if (signal.aborted) {
|
|
247
|
+
resolve({ type: 'cancelled', error: getAbortReason(signal) });
|
|
153
248
|
|
|
154
249
|
return;
|
|
155
250
|
}
|
|
156
251
|
|
|
157
252
|
const onAbort = () => {
|
|
158
|
-
resolve({ type: 'cancelled', error: getAbortReason(
|
|
253
|
+
resolve({ type: 'cancelled', error: getAbortReason(signal) });
|
|
159
254
|
};
|
|
160
255
|
|
|
161
|
-
|
|
256
|
+
signal.addEventListener('abort', onAbort, { once: true });
|
|
162
257
|
cleanupCancellation = () => {
|
|
163
|
-
|
|
258
|
+
signal.removeEventListener('abort', onAbort);
|
|
164
259
|
};
|
|
165
260
|
});
|
|
166
261
|
|
|
@@ -172,8 +267,7 @@ const waitForTaskProgress = async (
|
|
|
172
267
|
};
|
|
173
268
|
const completeTask = async (
|
|
174
269
|
env: StepExecutorEnv,
|
|
175
|
-
|
|
176
|
-
stepInfo: Suspension['step'],
|
|
270
|
+
stepInfo: StepInfo,
|
|
177
271
|
task: CompiledTask,
|
|
178
272
|
state: ExecutionState,
|
|
179
273
|
result: unknown,
|
|
@@ -191,102 +285,89 @@ const completeTask = async (
|
|
|
191
285
|
step: stepInfo,
|
|
192
286
|
stepExecution,
|
|
193
287
|
});
|
|
194
|
-
env.clearStepSuspensions(stepId);
|
|
195
288
|
};
|
|
196
|
-
const
|
|
289
|
+
const suspendTask = (
|
|
197
290
|
env: StepExecutorEnv,
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
291
|
+
step: TaskStep,
|
|
292
|
+
stepInfo: StepInfo,
|
|
293
|
+
inputs: Record<string, unknown>,
|
|
294
|
+
request: RuntimeSuspensionRequest,
|
|
295
|
+
): TaskFrame => {
|
|
296
|
+
const wait: WaitInfo = {
|
|
297
|
+
waitId: buildWaitId(stepInfo.id, request.suspendKey),
|
|
298
|
+
step: stepInfo,
|
|
299
|
+
suspendKey: request.suspendKey,
|
|
300
|
+
reason: request.reason,
|
|
301
|
+
data: request.data,
|
|
302
|
+
...(request.accepts ? { accepts: request.accepts } : {}),
|
|
303
|
+
...(request.payloadOptional ? { payloadOptional: true } : {}),
|
|
304
|
+
};
|
|
202
305
|
const stepExecution = env.recordStepExecution(stepInfo, {
|
|
203
306
|
status: 'suspended',
|
|
204
307
|
endedAt: Date.now(),
|
|
205
|
-
reason,
|
|
308
|
+
reason: request.reason,
|
|
206
309
|
context: { after: env.context.snapshot() },
|
|
207
310
|
});
|
|
208
|
-
env.markSnapshot(stepInfo, 'suspended', reason);
|
|
311
|
+
env.markSnapshot(stepInfo, 'suspended', request.reason);
|
|
209
312
|
env.emit('hook:step:suspended', {
|
|
210
313
|
runId: env.runId,
|
|
211
314
|
step: stepInfo,
|
|
212
315
|
stepExecution,
|
|
213
|
-
|
|
214
|
-
data,
|
|
316
|
+
wait,
|
|
215
317
|
});
|
|
216
|
-
};
|
|
217
|
-
const buildSuspensionContinuation = (
|
|
218
|
-
env: StepExecutorEnv,
|
|
219
|
-
stepId: string,
|
|
220
|
-
stepInfo: Suspension['step'],
|
|
221
|
-
task: CompiledTask,
|
|
222
|
-
state: ExecutionState,
|
|
223
|
-
actionPromise: Promise<unknown>,
|
|
224
|
-
request: RuntimeSuspensionRequest,
|
|
225
|
-
): Suspension => {
|
|
226
|
-
recordSuspension(env, stepInfo, request.reason, request.data);
|
|
227
|
-
|
|
228
|
-
let resumed = false;
|
|
229
318
|
|
|
230
319
|
return {
|
|
320
|
+
kind: 'task',
|
|
321
|
+
stepId: step.id,
|
|
322
|
+
inputs,
|
|
323
|
+
awaitResults: recordResults(request.awaitResults),
|
|
324
|
+
wait,
|
|
325
|
+
};
|
|
326
|
+
};
|
|
327
|
+
/** Wrap each answer so that one without payload survives JSON. */
|
|
328
|
+
const recordResults = (
|
|
329
|
+
results: Record<string, unknown>,
|
|
330
|
+
): Record<string, RecordedResult> =>
|
|
331
|
+
Object.fromEntries(
|
|
332
|
+
Object.entries(results).map(([key, value]) => [key, { value }]),
|
|
333
|
+
);
|
|
334
|
+
const readRecordedResults = (
|
|
335
|
+
recorded: Record<string, RecordedResult>,
|
|
336
|
+
): Record<string, unknown> =>
|
|
337
|
+
Object.fromEntries(
|
|
338
|
+
Object.entries(recorded).map(([key, result]) => [key, result.value]),
|
|
339
|
+
);
|
|
340
|
+
/**
|
|
341
|
+
* Put a resumed step back in its suspended state after its body refused the
|
|
342
|
+
* resume payload, and hand back the frame it resumed from.
|
|
343
|
+
*/
|
|
344
|
+
const keepWaiting = (
|
|
345
|
+
env: StepExecutorEnv,
|
|
346
|
+
stepInfo: StepInfo,
|
|
347
|
+
frame: TaskFrame,
|
|
348
|
+
error: WorkflowResumeRejectedError,
|
|
349
|
+
): TaskFrame => {
|
|
350
|
+
const stepExecution = env.recordStepExecution(stepInfo, {
|
|
351
|
+
status: 'suspended',
|
|
352
|
+
endedAt: Date.now(),
|
|
353
|
+
reason: frame.wait.reason,
|
|
354
|
+
context: { after: env.context.snapshot() },
|
|
355
|
+
});
|
|
356
|
+
env.markSnapshot(stepInfo, 'suspended', frame.wait.reason);
|
|
357
|
+
env.emit('hook:step:resume_rejected', {
|
|
358
|
+
runId: env.runId,
|
|
231
359
|
step: stepInfo,
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
awaitResults: request.awaitResults,
|
|
238
|
-
continue: async (resumeData: unknown) => {
|
|
239
|
-
if (resumed) {
|
|
240
|
-
throw new Error(
|
|
241
|
-
`Suspension for step "${stepInfo.id}" has already been resumed.`,
|
|
242
|
-
);
|
|
243
|
-
}
|
|
244
|
-
|
|
245
|
-
resumed = true;
|
|
246
|
-
env.setCurrentStep(stepInfo);
|
|
247
|
-
env.recordStepSuspendResult?.({
|
|
248
|
-
stepId,
|
|
249
|
-
stepExecId: request.stepExecId,
|
|
250
|
-
suspendIndex: request.suspendIndex,
|
|
251
|
-
suspendKey: request.suspendKey,
|
|
252
|
-
resumeData,
|
|
253
|
-
});
|
|
254
|
-
request.resume.resolve(resumeData);
|
|
255
|
-
|
|
256
|
-
let outcome: TaskProgressOutcome;
|
|
257
|
-
try {
|
|
258
|
-
outcome = await waitForTaskProgress(env, stepId, actionPromise);
|
|
259
|
-
} finally {
|
|
260
|
-
env.setCurrentStep(undefined);
|
|
261
|
-
}
|
|
262
|
-
|
|
263
|
-
if (outcome.type === 'suspended') {
|
|
264
|
-
return buildSuspensionContinuation(
|
|
265
|
-
env,
|
|
266
|
-
stepId,
|
|
267
|
-
stepInfo,
|
|
268
|
-
task,
|
|
269
|
-
state,
|
|
270
|
-
actionPromise,
|
|
271
|
-
outcome.request,
|
|
272
|
-
);
|
|
273
|
-
}
|
|
274
|
-
|
|
275
|
-
if (outcome.type === 'completed') {
|
|
276
|
-
await completeTask(env, stepId, stepInfo, task, state, outcome.value);
|
|
277
|
-
|
|
278
|
-
return undefined;
|
|
279
|
-
}
|
|
360
|
+
stepExecution,
|
|
361
|
+
wait: frame.wait,
|
|
362
|
+
error,
|
|
363
|
+
});
|
|
364
|
+
env.rejectResume({ waitId: frame.wait.waitId, error });
|
|
280
365
|
|
|
281
|
-
|
|
282
|
-
recordTaskFailure(env, stepInfo, outcome.error);
|
|
283
|
-
throw outcome.error;
|
|
284
|
-
},
|
|
285
|
-
};
|
|
366
|
+
return frame;
|
|
286
367
|
};
|
|
287
368
|
const recordTaskFailure = (
|
|
288
369
|
env: StepExecutorEnv,
|
|
289
|
-
stepInfo:
|
|
370
|
+
stepInfo: StepInfo,
|
|
290
371
|
error: unknown,
|
|
291
372
|
) => {
|
|
292
373
|
const normalizedError = normalizeError(error);
|
|
@@ -304,10 +385,15 @@ const recordTaskFailure = (
|
|
|
304
385
|
error,
|
|
305
386
|
});
|
|
306
387
|
};
|
|
388
|
+
/**
|
|
389
|
+
* Record a cancelled task. A task cancelled while resolving a wait drops that
|
|
390
|
+
* wait, so the event carries it.
|
|
391
|
+
*/
|
|
307
392
|
const recordTaskCancellation = (
|
|
308
393
|
env: StepExecutorEnv,
|
|
309
|
-
stepInfo:
|
|
394
|
+
stepInfo: StepInfo,
|
|
310
395
|
error: unknown,
|
|
396
|
+
wait?: WaitInfo,
|
|
311
397
|
) => {
|
|
312
398
|
const normalizedError = normalizeError(error);
|
|
313
399
|
const stepExecution = env.recordStepExecution(stepInfo, {
|
|
@@ -322,6 +408,7 @@ const recordTaskCancellation = (
|
|
|
322
408
|
step: stepInfo,
|
|
323
409
|
stepExecution,
|
|
324
410
|
error,
|
|
411
|
+
...(wait ? { wait } : {}),
|
|
325
412
|
});
|
|
326
413
|
};
|
|
327
414
|
const normalizeError = (error: unknown): { message: string; stack?: string } =>
|
|
@@ -4,41 +4,48 @@
|
|
|
4
4
|
* Full terms: see LICENSE.md.
|
|
5
5
|
*/
|
|
6
6
|
|
|
7
|
+
import type { SequenceFrame, StepFrame } from '../checkpoint';
|
|
7
8
|
import type {
|
|
8
9
|
ActionSnapshot,
|
|
9
10
|
BaseWorkflowContext,
|
|
10
11
|
StepExecutionRecord,
|
|
11
12
|
} from '../context';
|
|
12
|
-
import type {
|
|
13
|
-
RuntimeResolvedSuspension,
|
|
14
|
-
RuntimeStepReplaySeed,
|
|
15
|
-
RuntimeSuspensionRequest,
|
|
16
|
-
} from '../runner-runtime-control';
|
|
13
|
+
import type { RunnerRuntimeControl } from '../runner-runtime-control';
|
|
17
14
|
import type { StepInfo, WorkflowEventMap } from '../workflow-event-emitter';
|
|
18
15
|
import type {
|
|
19
16
|
CompiledStep,
|
|
20
17
|
CompiledTask,
|
|
21
18
|
CompiledWorkflow,
|
|
22
19
|
ExecutionState,
|
|
23
|
-
|
|
20
|
+
ResumeRejection,
|
|
24
21
|
} from '../workflow-types';
|
|
25
22
|
|
|
26
23
|
export type StepExecutorEnvForkOverrides = {
|
|
27
24
|
context?: BaseWorkflowContext;
|
|
28
25
|
signal?: AbortSignal;
|
|
29
|
-
|
|
30
|
-
captureTaskOutput?: (
|
|
31
|
-
task: CompiledTask,
|
|
32
|
-
state: ExecutionState,
|
|
33
|
-
result: unknown,
|
|
34
|
-
) => Promise<void>;
|
|
26
|
+
runtime?: RunnerRuntimeControl;
|
|
35
27
|
};
|
|
36
28
|
|
|
29
|
+
/**
|
|
30
|
+
* Everything a step executor needs from the runner.
|
|
31
|
+
*
|
|
32
|
+
* Executors return a frame when the step suspends and `undefined` when it
|
|
33
|
+
* completes. Passing that frame back in resumes the step where it stopped.
|
|
34
|
+
*/
|
|
37
35
|
export type StepExecutorEnv = {
|
|
38
36
|
compiled: CompiledWorkflow;
|
|
39
37
|
context: BaseWorkflowContext;
|
|
40
38
|
signal: AbortSignal;
|
|
41
39
|
runId?: string;
|
|
40
|
+
/** Suspension control of the concurrency scope this env runs in. */
|
|
41
|
+
runtime: RunnerRuntimeControl;
|
|
42
|
+
/** Resume payloads for the waits this execution pass satisfies, by wait id. */
|
|
43
|
+
resolutions: ReadonlyMap<string, unknown>;
|
|
44
|
+
/**
|
|
45
|
+
* Report that a resumed step refused its payload. The runner then leaves
|
|
46
|
+
* the run exactly as it was before this pass.
|
|
47
|
+
*/
|
|
48
|
+
rejectResume: (rejection: ResumeRejection) => void;
|
|
42
49
|
buildInstanceStepInfo: (
|
|
43
50
|
step: CompiledStep,
|
|
44
51
|
iterationStack: number[],
|
|
@@ -56,13 +63,6 @@ export type StepExecutorEnv = {
|
|
|
56
63
|
event: K,
|
|
57
64
|
payload: WorkflowEventMap[K],
|
|
58
65
|
) => void;
|
|
59
|
-
setCurrentStep: (step?: StepInfo) => void;
|
|
60
|
-
beginStepExecution?: (stepId: string) => string;
|
|
61
|
-
waitForStepSuspension: (stepId: string) => Promise<RuntimeSuspensionRequest>;
|
|
62
|
-
clearStepSuspensions: (stepId: string, error?: unknown) => void;
|
|
63
|
-
primeStepResumeData: (stepId: string, resumeData: unknown) => void;
|
|
64
|
-
prepareStepReplay?: (seed: RuntimeStepReplaySeed) => void;
|
|
65
|
-
recordStepSuspendResult?: (params: RuntimeResolvedSuspension) => void;
|
|
66
66
|
captureTaskOutput: (
|
|
67
67
|
task: CompiledTask,
|
|
68
68
|
state: ExecutionState,
|
|
@@ -72,12 +72,13 @@ export type StepExecutorEnv = {
|
|
|
72
72
|
steps: CompiledStep[],
|
|
73
73
|
state: ExecutionState,
|
|
74
74
|
path: Array<number | string>,
|
|
75
|
-
|
|
76
|
-
) => Promise<
|
|
75
|
+
frame?: SequenceFrame,
|
|
76
|
+
) => Promise<SequenceFrame | void>;
|
|
77
77
|
executeStep: (
|
|
78
78
|
step: CompiledStep,
|
|
79
79
|
state: ExecutionState,
|
|
80
80
|
path: Array<number | string>,
|
|
81
|
-
|
|
81
|
+
frame?: StepFrame,
|
|
82
|
+
) => Promise<StepFrame | void>;
|
|
82
83
|
fork: (overrides: StepExecutorEnvForkOverrides) => StepExecutorEnv;
|
|
83
84
|
};
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Hexabot — Fair Core License (FCL-1.0-ALv2)
|
|
3
|
+
* Copyright (c) 2025 Hexastack.
|
|
4
|
+
* Full terms: see LICENSE.md.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Deep-clone a value, preferring `structuredClone` and falling back to a JSON
|
|
9
|
+
* round trip, then to a shallow copy for values neither can handle.
|
|
10
|
+
*
|
|
11
|
+
* @param value The value to clone.
|
|
12
|
+
* @returns A detached copy of the value.
|
|
13
|
+
*/
|
|
14
|
+
export function cloneValue<T>(value: T): T {
|
|
15
|
+
if (value === undefined || value === null) {
|
|
16
|
+
return value;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
if (typeof structuredClone === 'function') {
|
|
20
|
+
try {
|
|
21
|
+
return structuredClone(value);
|
|
22
|
+
} catch {
|
|
23
|
+
// Fall through to JSON clone below.
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
try {
|
|
28
|
+
return JSON.parse(JSON.stringify(value)) as T;
|
|
29
|
+
} catch {
|
|
30
|
+
if (Array.isArray(value)) {
|
|
31
|
+
return [...value] as T;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
if (isRecord(value)) {
|
|
35
|
+
return { ...value } as T;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
return value;
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Copy a value through a JSON round trip, exactly as a host persisting it
|
|
44
|
+
* would: dates become ISO strings, and `undefined` values and functions are
|
|
45
|
+
* dropped.
|
|
46
|
+
*
|
|
47
|
+
* @param value The value to copy.
|
|
48
|
+
* @returns A detached, JSON-only copy of the value.
|
|
49
|
+
* @throws {TypeError} When JSON cannot encode the value (BigInt, cycles).
|
|
50
|
+
*/
|
|
51
|
+
export function cloneAsJson<T>(value: T): T {
|
|
52
|
+
return JSON.parse(JSON.stringify(value)) as T;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Deep-clone a record.
|
|
57
|
+
*
|
|
58
|
+
* @param value The record to clone.
|
|
59
|
+
* @returns A detached copy of the record.
|
|
60
|
+
*/
|
|
61
|
+
export function cloneRecord(
|
|
62
|
+
value: Record<string, unknown>,
|
|
63
|
+
): Record<string, unknown> {
|
|
64
|
+
return cloneValue(value) as Record<string, unknown>;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Report whether a value is a plain (non-array) object.
|
|
69
|
+
*
|
|
70
|
+
* @param value The value to check.
|
|
71
|
+
* @returns True when the value is a non-null, non-array object.
|
|
72
|
+
*/
|
|
73
|
+
export function isRecord(value: unknown): value is Record<string, unknown> {
|
|
74
|
+
return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
|
|
75
|
+
}
|