@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
|
@@ -3,98 +3,183 @@
|
|
|
3
3
|
* Copyright (c) 2025 Hexastack.
|
|
4
4
|
* Full terms: see LICENSE.md.
|
|
5
5
|
*/
|
|
6
|
-
import {
|
|
6
|
+
import { buildWaitId, } from '../checkpoint';
|
|
7
|
+
import { createLinkedAbortController, getAbortReason, isWorkflowResumeRejectedError, throwIfAborted, WorkflowCancellationError, } from '../errors';
|
|
8
|
+
import { cloneAsJson, cloneValue } from '../utils/clone';
|
|
7
9
|
import { evaluateMapping } from '../workflow-values';
|
|
8
10
|
/**
|
|
9
|
-
* Execute a task step
|
|
11
|
+
* Execute a task step, returning a frame when its action suspends.
|
|
12
|
+
*
|
|
13
|
+
* Given a frame, the step either stays parked (its wait is not resolved by
|
|
14
|
+
* this pass) or re-runs its action body: earlier `suspend()` calls resolve
|
|
15
|
+
* from the frame, including the one this pass resolved. A body that refuses
|
|
16
|
+
* that payload returns the frame unchanged, so the wait stays open.
|
|
10
17
|
*
|
|
11
18
|
* @param env Executor environment with compiled workflow and helpers.
|
|
12
19
|
* @param step The compiled task step to execute.
|
|
13
20
|
* @param state Mutable workflow execution state.
|
|
14
21
|
* @param _path Location of the step within the workflow (unused in this executor).
|
|
15
|
-
* @
|
|
22
|
+
* @param frame Frame returned when this step previously suspended.
|
|
23
|
+
* @returns A frame if the task suspends, otherwise void.
|
|
16
24
|
*/
|
|
17
|
-
export async function executeTaskStep(env, step, state, _path) {
|
|
25
|
+
export async function executeTaskStep(env, step, state, _path, frame) {
|
|
18
26
|
void _path;
|
|
19
27
|
const task = env.compiled.tasks[step.taskName];
|
|
20
28
|
if (!task) {
|
|
21
29
|
throw new Error(`Task "${step.taskName}" is not defined.`);
|
|
22
30
|
}
|
|
31
|
+
// A parked wait that this pass does not resolve stays exactly as it was.
|
|
32
|
+
if (frame && !env.resolutions.has(frame.wait.waitId)) {
|
|
33
|
+
return frame;
|
|
34
|
+
}
|
|
23
35
|
const stepInfo = env.buildInstanceStepInfo(step, state.iterationStack);
|
|
24
36
|
if (env.signal.aborted) {
|
|
25
37
|
const error = getAbortReason(env.signal);
|
|
26
|
-
recordTaskCancellation(env, stepInfo, error);
|
|
38
|
+
recordTaskCancellation(env, stepInfo, error, frame?.wait);
|
|
27
39
|
throw error;
|
|
28
40
|
}
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
accumulator: state.accumulator,
|
|
35
|
-
};
|
|
36
|
-
const inputs = await evaluateMapping(task.inputs, scope);
|
|
41
|
+
// Resumed bodies reuse the inputs they first ran with: re-evaluating could
|
|
42
|
+
// differ, e.g. when an expression depends on the event that woke the run.
|
|
43
|
+
const inputs = frame
|
|
44
|
+
? cloneValue(frame.inputs)
|
|
45
|
+
: await evaluateMapping(task.inputs, buildScope(env, state));
|
|
37
46
|
if (env.signal.aborted) {
|
|
38
47
|
const error = getAbortReason(env.signal);
|
|
39
|
-
recordTaskCancellation(env, stepInfo, error);
|
|
48
|
+
recordTaskCancellation(env, stepInfo, error, frame?.wait);
|
|
40
49
|
throw error;
|
|
41
50
|
}
|
|
51
|
+
// Kept apart from the object the body gets, so that a body changing its
|
|
52
|
+
// inputs cannot change the inputs every later pass replays.
|
|
53
|
+
const recordedInputs = frame ? frame.inputs : copyInputs(inputs);
|
|
54
|
+
const resumeData = frame ? env.resolutions.get(frame.wait.waitId) : undefined;
|
|
55
|
+
const seed = frame
|
|
56
|
+
? {
|
|
57
|
+
awaitResults: {
|
|
58
|
+
...readRecordedResults(frame.awaitResults),
|
|
59
|
+
[frame.wait.suspendKey]: resumeData,
|
|
60
|
+
},
|
|
61
|
+
expected: {
|
|
62
|
+
suspendKey: frame.wait.suspendKey,
|
|
63
|
+
reason: frame.wait.reason,
|
|
64
|
+
},
|
|
65
|
+
}
|
|
66
|
+
: undefined;
|
|
42
67
|
const stepExecution = env.recordStepExecution(stepInfo, {
|
|
43
68
|
action: task.actionName,
|
|
44
69
|
status: 'running',
|
|
45
70
|
startedAt: Date.now(),
|
|
71
|
+
endedAt: undefined,
|
|
72
|
+
reason: undefined,
|
|
46
73
|
input: inputs,
|
|
47
74
|
context: { before: env.context.snapshot() },
|
|
48
75
|
});
|
|
49
|
-
env.
|
|
50
|
-
env.setCurrentStep(stepInfo);
|
|
76
|
+
env.runtime.beginStep(stepInfo, { seed });
|
|
51
77
|
env.markSnapshot(stepInfo, 'running');
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
78
|
+
if (frame) {
|
|
79
|
+
env.emit('hook:step:resumed', {
|
|
80
|
+
runId: env.runId,
|
|
81
|
+
step: stepInfo,
|
|
82
|
+
stepExecution,
|
|
83
|
+
wait: frame.wait,
|
|
84
|
+
resumeData,
|
|
85
|
+
});
|
|
86
|
+
}
|
|
87
|
+
else {
|
|
88
|
+
env.emit('hook:step:start', {
|
|
89
|
+
runId: env.runId,
|
|
90
|
+
step: stepInfo,
|
|
91
|
+
stepExecution,
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
// Each action gets its own signal so a suspension can stop its body
|
|
95
|
+
// without cancelling anything else.
|
|
96
|
+
const { controller, unlink } = createLinkedAbortController(env.signal);
|
|
97
|
+
let outcome;
|
|
57
98
|
try {
|
|
58
99
|
throwIfAborted(env.signal);
|
|
59
|
-
const actionPromise = Promise.resolve().then(() => task.action.run(inputs, env.context, task.settings, task.bindings,
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
100
|
+
const actionPromise = Promise.resolve().then(() => task.action.run(inputs, env.context, task.settings, task.bindings, controller.signal));
|
|
101
|
+
outcome = await waitForTaskProgress(controller.signal, env.runtime, actionPromise);
|
|
102
|
+
}
|
|
103
|
+
catch (error) {
|
|
104
|
+
env.runtime.endStep();
|
|
105
|
+
throw error;
|
|
106
|
+
}
|
|
107
|
+
finally {
|
|
108
|
+
unlink();
|
|
109
|
+
}
|
|
110
|
+
switch (outcome.type) {
|
|
111
|
+
case 'suspended':
|
|
112
|
+
env.runtime.endStep();
|
|
113
|
+
// The body is parked on a promise that never settles. Aborting it clears
|
|
114
|
+
// its timeout and stops its retry loop; resuming re-runs it instead.
|
|
115
|
+
controller.abort(new WorkflowCancellationError(`Step "${stepInfo.id}" suspended.`));
|
|
116
|
+
return suspendTask(env, step, stepInfo, recordedInputs, outcome.request);
|
|
117
|
+
case 'completed':
|
|
118
|
+
try {
|
|
119
|
+
env.runtime.endStep({ completed: true });
|
|
120
|
+
}
|
|
121
|
+
catch (error) {
|
|
122
|
+
recordTaskFailure(env, stepInfo, error);
|
|
123
|
+
throw error;
|
|
124
|
+
}
|
|
125
|
+
await completeTask(env, stepInfo, task, state, outcome.value);
|
|
63
126
|
return undefined;
|
|
127
|
+
case 'failed': {
|
|
128
|
+
const { error } = outcome;
|
|
129
|
+
// Only a body that already read the resolved payload can refuse it.
|
|
130
|
+
const rejected = frame !== undefined &&
|
|
131
|
+
isWorkflowResumeRejectedError(error) &&
|
|
132
|
+
env.runtime.hasReachedResolvedSuspension();
|
|
133
|
+
env.runtime.endStep();
|
|
134
|
+
if (rejected) {
|
|
135
|
+
return keepWaiting(env, stepInfo, frame, error);
|
|
136
|
+
}
|
|
137
|
+
recordTaskFailure(env, stepInfo, error);
|
|
138
|
+
throw error;
|
|
64
139
|
}
|
|
65
|
-
|
|
66
|
-
env.
|
|
67
|
-
|
|
68
|
-
throw outcome.error;
|
|
69
|
-
}
|
|
70
|
-
if (outcome.type === 'cancelled') {
|
|
71
|
-
env.clearStepSuspensions(stepInfo.id, outcome.error);
|
|
72
|
-
recordTaskCancellation(env, stepInfo, outcome.error);
|
|
140
|
+
case 'cancelled':
|
|
141
|
+
env.runtime.endStep();
|
|
142
|
+
recordTaskCancellation(env, stepInfo, outcome.error, frame?.wait);
|
|
73
143
|
throw outcome.error;
|
|
74
|
-
}
|
|
75
|
-
return buildSuspensionContinuation(env, stepInfo.id, stepInfo, task, state, actionPromise, outcome.request);
|
|
76
|
-
}
|
|
77
|
-
finally {
|
|
78
|
-
env.setCurrentStep(undefined);
|
|
79
144
|
}
|
|
80
145
|
}
|
|
81
|
-
|
|
146
|
+
/**
|
|
147
|
+
* Copy the inputs a body first runs with, the way the checkpoint stores them.
|
|
148
|
+
* Inputs JSON cannot encode are returned as they are: building the checkpoint
|
|
149
|
+
* reports them if the step suspends.
|
|
150
|
+
*/
|
|
151
|
+
const copyInputs = (inputs) => {
|
|
152
|
+
try {
|
|
153
|
+
return cloneAsJson(inputs);
|
|
154
|
+
}
|
|
155
|
+
catch {
|
|
156
|
+
return inputs;
|
|
157
|
+
}
|
|
158
|
+
};
|
|
159
|
+
const buildScope = (env, state) => ({
|
|
160
|
+
input: state.input,
|
|
161
|
+
context: env.context.state,
|
|
162
|
+
output: state.output,
|
|
163
|
+
iteration: state.iteration,
|
|
164
|
+
accumulator: state.accumulator,
|
|
165
|
+
});
|
|
166
|
+
const waitForTaskProgress = async (signal, runtime, actionPromise) => {
|
|
82
167
|
const completion = actionPromise.then((value) => ({ type: 'completed', value }), (error) => ({ type: 'failed', error }));
|
|
83
|
-
const suspension =
|
|
84
|
-
.
|
|
168
|
+
const suspension = runtime
|
|
169
|
+
.waitForSuspension()
|
|
85
170
|
.then((request) => ({ type: 'suspended', request }));
|
|
86
171
|
let cleanupCancellation = () => undefined;
|
|
87
172
|
const cancellation = new Promise((resolve) => {
|
|
88
|
-
if (
|
|
89
|
-
resolve({ type: 'cancelled', error: getAbortReason(
|
|
173
|
+
if (signal.aborted) {
|
|
174
|
+
resolve({ type: 'cancelled', error: getAbortReason(signal) });
|
|
90
175
|
return;
|
|
91
176
|
}
|
|
92
177
|
const onAbort = () => {
|
|
93
|
-
resolve({ type: 'cancelled', error: getAbortReason(
|
|
178
|
+
resolve({ type: 'cancelled', error: getAbortReason(signal) });
|
|
94
179
|
};
|
|
95
|
-
|
|
180
|
+
signal.addEventListener('abort', onAbort, { once: true });
|
|
96
181
|
cleanupCancellation = () => {
|
|
97
|
-
|
|
182
|
+
signal.removeEventListener('abort', onAbort);
|
|
98
183
|
};
|
|
99
184
|
});
|
|
100
185
|
try {
|
|
@@ -104,7 +189,7 @@ const waitForTaskProgress = async (env, stepId, actionPromise) => {
|
|
|
104
189
|
cleanupCancellation();
|
|
105
190
|
}
|
|
106
191
|
};
|
|
107
|
-
const completeTask = async (env,
|
|
192
|
+
const completeTask = async (env, stepInfo, task, state, result) => {
|
|
108
193
|
await env.captureTaskOutput(task, state, result);
|
|
109
194
|
const stepExecution = env.recordStepExecution(stepInfo, {
|
|
110
195
|
status: 'completed',
|
|
@@ -118,69 +203,63 @@ const completeTask = async (env, stepId, stepInfo, task, state, result) => {
|
|
|
118
203
|
step: stepInfo,
|
|
119
204
|
stepExecution,
|
|
120
205
|
});
|
|
121
|
-
env.clearStepSuspensions(stepId);
|
|
122
206
|
};
|
|
123
|
-
const
|
|
207
|
+
const suspendTask = (env, step, stepInfo, inputs, request) => {
|
|
208
|
+
const wait = {
|
|
209
|
+
waitId: buildWaitId(stepInfo.id, request.suspendKey),
|
|
210
|
+
step: stepInfo,
|
|
211
|
+
suspendKey: request.suspendKey,
|
|
212
|
+
reason: request.reason,
|
|
213
|
+
data: request.data,
|
|
214
|
+
...(request.accepts ? { accepts: request.accepts } : {}),
|
|
215
|
+
...(request.payloadOptional ? { payloadOptional: true } : {}),
|
|
216
|
+
};
|
|
124
217
|
const stepExecution = env.recordStepExecution(stepInfo, {
|
|
125
218
|
status: 'suspended',
|
|
126
219
|
endedAt: Date.now(),
|
|
127
|
-
reason,
|
|
220
|
+
reason: request.reason,
|
|
128
221
|
context: { after: env.context.snapshot() },
|
|
129
222
|
});
|
|
130
|
-
env.markSnapshot(stepInfo, 'suspended', reason);
|
|
223
|
+
env.markSnapshot(stepInfo, 'suspended', request.reason);
|
|
131
224
|
env.emit('hook:step:suspended', {
|
|
132
225
|
runId: env.runId,
|
|
133
226
|
step: stepInfo,
|
|
134
227
|
stepExecution,
|
|
135
|
-
|
|
136
|
-
data,
|
|
228
|
+
wait,
|
|
137
229
|
});
|
|
138
|
-
};
|
|
139
|
-
const buildSuspensionContinuation = (env, stepId, stepInfo, task, state, actionPromise, request) => {
|
|
140
|
-
recordSuspension(env, stepInfo, request.reason, request.data);
|
|
141
|
-
let resumed = false;
|
|
142
230
|
return {
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
suspendKey: request.suspendKey,
|
|
149
|
-
awaitResults: request.awaitResults,
|
|
150
|
-
continue: async (resumeData) => {
|
|
151
|
-
if (resumed) {
|
|
152
|
-
throw new Error(`Suspension for step "${stepInfo.id}" has already been resumed.`);
|
|
153
|
-
}
|
|
154
|
-
resumed = true;
|
|
155
|
-
env.setCurrentStep(stepInfo);
|
|
156
|
-
env.recordStepSuspendResult?.({
|
|
157
|
-
stepId,
|
|
158
|
-
stepExecId: request.stepExecId,
|
|
159
|
-
suspendIndex: request.suspendIndex,
|
|
160
|
-
suspendKey: request.suspendKey,
|
|
161
|
-
resumeData,
|
|
162
|
-
});
|
|
163
|
-
request.resume.resolve(resumeData);
|
|
164
|
-
let outcome;
|
|
165
|
-
try {
|
|
166
|
-
outcome = await waitForTaskProgress(env, stepId, actionPromise);
|
|
167
|
-
}
|
|
168
|
-
finally {
|
|
169
|
-
env.setCurrentStep(undefined);
|
|
170
|
-
}
|
|
171
|
-
if (outcome.type === 'suspended') {
|
|
172
|
-
return buildSuspensionContinuation(env, stepId, stepInfo, task, state, actionPromise, outcome.request);
|
|
173
|
-
}
|
|
174
|
-
if (outcome.type === 'completed') {
|
|
175
|
-
await completeTask(env, stepId, stepInfo, task, state, outcome.value);
|
|
176
|
-
return undefined;
|
|
177
|
-
}
|
|
178
|
-
env.clearStepSuspensions(stepId, outcome.error);
|
|
179
|
-
recordTaskFailure(env, stepInfo, outcome.error);
|
|
180
|
-
throw outcome.error;
|
|
181
|
-
},
|
|
231
|
+
kind: 'task',
|
|
232
|
+
stepId: step.id,
|
|
233
|
+
inputs,
|
|
234
|
+
awaitResults: recordResults(request.awaitResults),
|
|
235
|
+
wait,
|
|
182
236
|
};
|
|
183
237
|
};
|
|
238
|
+
/** Wrap each answer so that one without payload survives JSON. */
|
|
239
|
+
const recordResults = (results) => Object.fromEntries(Object.entries(results).map(([key, value]) => [key, { value }]));
|
|
240
|
+
const readRecordedResults = (recorded) => Object.fromEntries(Object.entries(recorded).map(([key, result]) => [key, result.value]));
|
|
241
|
+
/**
|
|
242
|
+
* Put a resumed step back in its suspended state after its body refused the
|
|
243
|
+
* resume payload, and hand back the frame it resumed from.
|
|
244
|
+
*/
|
|
245
|
+
const keepWaiting = (env, stepInfo, frame, error) => {
|
|
246
|
+
const stepExecution = env.recordStepExecution(stepInfo, {
|
|
247
|
+
status: 'suspended',
|
|
248
|
+
endedAt: Date.now(),
|
|
249
|
+
reason: frame.wait.reason,
|
|
250
|
+
context: { after: env.context.snapshot() },
|
|
251
|
+
});
|
|
252
|
+
env.markSnapshot(stepInfo, 'suspended', frame.wait.reason);
|
|
253
|
+
env.emit('hook:step:resume_rejected', {
|
|
254
|
+
runId: env.runId,
|
|
255
|
+
step: stepInfo,
|
|
256
|
+
stepExecution,
|
|
257
|
+
wait: frame.wait,
|
|
258
|
+
error,
|
|
259
|
+
});
|
|
260
|
+
env.rejectResume({ waitId: frame.wait.waitId, error });
|
|
261
|
+
return frame;
|
|
262
|
+
};
|
|
184
263
|
const recordTaskFailure = (env, stepInfo, error) => {
|
|
185
264
|
const normalizedError = normalizeError(error);
|
|
186
265
|
const stepExecution = env.recordStepExecution(stepInfo, {
|
|
@@ -197,7 +276,11 @@ const recordTaskFailure = (env, stepInfo, error) => {
|
|
|
197
276
|
error,
|
|
198
277
|
});
|
|
199
278
|
};
|
|
200
|
-
|
|
279
|
+
/**
|
|
280
|
+
* Record a cancelled task. A task cancelled while resolving a wait drops that
|
|
281
|
+
* wait, so the event carries it.
|
|
282
|
+
*/
|
|
283
|
+
const recordTaskCancellation = (env, stepInfo, error, wait) => {
|
|
201
284
|
const normalizedError = normalizeError(error);
|
|
202
285
|
const stepExecution = env.recordStepExecution(stepInfo, {
|
|
203
286
|
status: 'cancelled',
|
|
@@ -211,6 +294,7 @@ const recordTaskCancellation = (env, stepInfo, error) => {
|
|
|
211
294
|
step: stepInfo,
|
|
212
295
|
stepExecution,
|
|
213
296
|
error,
|
|
297
|
+
...(wait ? { wait } : {}),
|
|
214
298
|
});
|
|
215
299
|
};
|
|
216
300
|
const normalizeError = (error) => error instanceof Error
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Hexabot — Fair Core License (FCL-1.0-ALv2)
|
|
3
|
+
* Copyright (c) 2025 Hexastack.
|
|
4
|
+
* Full terms: see LICENSE.md.
|
|
5
|
+
*/
|
|
6
|
+
/**
|
|
7
|
+
* Deep-clone a value, preferring `structuredClone` and falling back to a JSON
|
|
8
|
+
* round trip, then to a shallow copy for values neither can handle.
|
|
9
|
+
*
|
|
10
|
+
* @param value The value to clone.
|
|
11
|
+
* @returns A detached copy of the value.
|
|
12
|
+
*/
|
|
13
|
+
export function cloneValue(value) {
|
|
14
|
+
if (value === undefined || value === null) {
|
|
15
|
+
return value;
|
|
16
|
+
}
|
|
17
|
+
if (typeof structuredClone === 'function') {
|
|
18
|
+
try {
|
|
19
|
+
return structuredClone(value);
|
|
20
|
+
}
|
|
21
|
+
catch {
|
|
22
|
+
// Fall through to JSON clone below.
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
try {
|
|
26
|
+
return JSON.parse(JSON.stringify(value));
|
|
27
|
+
}
|
|
28
|
+
catch {
|
|
29
|
+
if (Array.isArray(value)) {
|
|
30
|
+
return [...value];
|
|
31
|
+
}
|
|
32
|
+
if (isRecord(value)) {
|
|
33
|
+
return { ...value };
|
|
34
|
+
}
|
|
35
|
+
return value;
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Copy a value through a JSON round trip, exactly as a host persisting it
|
|
40
|
+
* would: dates become ISO strings, and `undefined` values and functions are
|
|
41
|
+
* dropped.
|
|
42
|
+
*
|
|
43
|
+
* @param value The value to copy.
|
|
44
|
+
* @returns A detached, JSON-only copy of the value.
|
|
45
|
+
* @throws {TypeError} When JSON cannot encode the value (BigInt, cycles).
|
|
46
|
+
*/
|
|
47
|
+
export function cloneAsJson(value) {
|
|
48
|
+
return JSON.parse(JSON.stringify(value));
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Deep-clone a record.
|
|
52
|
+
*
|
|
53
|
+
* @param value The record to clone.
|
|
54
|
+
* @returns A detached copy of the record.
|
|
55
|
+
*/
|
|
56
|
+
export function cloneRecord(value) {
|
|
57
|
+
return cloneValue(value);
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Report whether a value is a plain (non-array) object.
|
|
61
|
+
*
|
|
62
|
+
* @param value The value to check.
|
|
63
|
+
* @returns True when the value is a non-null, non-array object.
|
|
64
|
+
*/
|
|
65
|
+
export function isRecord(value) {
|
|
66
|
+
return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
|
|
67
|
+
}
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Hexabot — Fair Core License (FCL-1.0-ALv2)
|
|
3
|
+
* Copyright (c) 2025 Hexastack.
|
|
4
|
+
* Full terms: see LICENSE.md.
|
|
5
|
+
*/
|
|
6
|
+
import { StepType } from './workflow-event-emitter';
|
|
7
|
+
/** Separator between fingerprint parts; never produced by the parts themselves. */
|
|
8
|
+
const PART_SEPARATOR = '~|~';
|
|
9
|
+
/** Fingerprints are pure functions of the compiled graph, so compute each once. */
|
|
10
|
+
const fingerprintCache = new WeakMap();
|
|
11
|
+
/**
|
|
12
|
+
* Fingerprint the parts of a compiled workflow that a checkpoint depends on.
|
|
13
|
+
*
|
|
14
|
+
* Hashing step ids alone is not enough: a changed `until`, `while`, branch
|
|
15
|
+
* condition or `inputs` mapping keeps every id stable while changing what the
|
|
16
|
+
* resumed run actually does. Labels are included because `buildStepId`
|
|
17
|
+
* embeds them, so renaming a task changes every downstream step id.
|
|
18
|
+
*
|
|
19
|
+
* @param compiled The compiled workflow to fingerprint.
|
|
20
|
+
* @returns A short, stable hash of the resume-relevant definition surface.
|
|
21
|
+
*/
|
|
22
|
+
export const fingerprintWorkflow = (compiled) => {
|
|
23
|
+
const cached = fingerprintCache.get(compiled);
|
|
24
|
+
if (cached !== undefined) {
|
|
25
|
+
return cached;
|
|
26
|
+
}
|
|
27
|
+
const parts = [];
|
|
28
|
+
collectSteps(compiled, compiled.flow, parts);
|
|
29
|
+
parts.push('outputs', ...describeMapping(compiled.outputMapping));
|
|
30
|
+
const fingerprint = hash(parts.join(PART_SEPARATOR));
|
|
31
|
+
fingerprintCache.set(compiled, fingerprint);
|
|
32
|
+
return fingerprint;
|
|
33
|
+
};
|
|
34
|
+
/**
|
|
35
|
+
* Append a canonical description of each step, depth first.
|
|
36
|
+
*
|
|
37
|
+
* @param compiled The compiled workflow, used to resolve task definitions.
|
|
38
|
+
* @param steps Steps to describe.
|
|
39
|
+
* @param parts Accumulator receiving the description fragments.
|
|
40
|
+
*/
|
|
41
|
+
const collectSteps = (compiled, steps, parts) => {
|
|
42
|
+
for (const step of steps) {
|
|
43
|
+
parts.push(step.type, step.id, step.label);
|
|
44
|
+
switch (step.type) {
|
|
45
|
+
case StepType.Task: {
|
|
46
|
+
const task = compiled.tasks[step.taskName];
|
|
47
|
+
parts.push(step.taskName, task?.actionName ?? '');
|
|
48
|
+
parts.push(...describeMapping(task?.inputs));
|
|
49
|
+
break;
|
|
50
|
+
}
|
|
51
|
+
case StepType.Parallel:
|
|
52
|
+
parts.push(step.strategy);
|
|
53
|
+
collectSteps(compiled, step.steps, parts);
|
|
54
|
+
break;
|
|
55
|
+
case StepType.Conditional:
|
|
56
|
+
for (const branch of step.branches) {
|
|
57
|
+
parts.push(branch.id, describeValue(branch.condition));
|
|
58
|
+
collectSteps(compiled, branch.steps, parts);
|
|
59
|
+
}
|
|
60
|
+
break;
|
|
61
|
+
case StepType.Loop:
|
|
62
|
+
parts.push(step.loopType, step.name ?? '');
|
|
63
|
+
parts.push(step.accumulate
|
|
64
|
+
? `${step.accumulate.as}=${stringify(step.accumulate.initial)}:${describeValue(step.accumulate.merge)}`
|
|
65
|
+
: '');
|
|
66
|
+
if (step.loopType === 'for_each') {
|
|
67
|
+
parts.push(step.forEach.item, describeValue(step.forEach.in));
|
|
68
|
+
parts.push(describeValue(step.until));
|
|
69
|
+
}
|
|
70
|
+
else {
|
|
71
|
+
parts.push(describeValue(step.while));
|
|
72
|
+
}
|
|
73
|
+
collectSteps(compiled, step.steps, parts);
|
|
74
|
+
break;
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
};
|
|
78
|
+
/**
|
|
79
|
+
* Describe a compiled mapping in a key-stable order.
|
|
80
|
+
*
|
|
81
|
+
* @param mapping The mapping to describe.
|
|
82
|
+
* @returns One fragment per mapped key.
|
|
83
|
+
*/
|
|
84
|
+
const describeMapping = (mapping) => {
|
|
85
|
+
if (!mapping) {
|
|
86
|
+
return [];
|
|
87
|
+
}
|
|
88
|
+
return Object.keys(mapping)
|
|
89
|
+
.sort()
|
|
90
|
+
.map((key) => `${key}=${describeValue(mapping[key])}`);
|
|
91
|
+
};
|
|
92
|
+
/**
|
|
93
|
+
* Describe a compiled value by its authored source, not its compiled form.
|
|
94
|
+
*
|
|
95
|
+
* @param value The compiled value.
|
|
96
|
+
* @returns A stable textual description.
|
|
97
|
+
*/
|
|
98
|
+
const describeValue = (value) => {
|
|
99
|
+
if (!value) {
|
|
100
|
+
return '';
|
|
101
|
+
}
|
|
102
|
+
return value.kind === 'expression'
|
|
103
|
+
? `=${value.source}`
|
|
104
|
+
: stringify(value.value);
|
|
105
|
+
};
|
|
106
|
+
const stringify = (value) => {
|
|
107
|
+
try {
|
|
108
|
+
return JSON.stringify(value) ?? String(value);
|
|
109
|
+
}
|
|
110
|
+
catch {
|
|
111
|
+
return String(value);
|
|
112
|
+
}
|
|
113
|
+
};
|
|
114
|
+
/**
|
|
115
|
+
* Hash a string with two FNV-1a style passes under different constants.
|
|
116
|
+
*
|
|
117
|
+
* Kept dependency-free on purpose: the package is consumed from browser
|
|
118
|
+
* bundles, so `node:crypto` is not available.
|
|
119
|
+
*
|
|
120
|
+
* @param value The canonical description to hash.
|
|
121
|
+
* @returns A 16-character hexadecimal digest.
|
|
122
|
+
*/
|
|
123
|
+
const hash = (value) => {
|
|
124
|
+
let low = 0x811c9dc5;
|
|
125
|
+
let high = 0x01000193;
|
|
126
|
+
for (let index = 0; index < value.length; index += 1) {
|
|
127
|
+
const code = value.charCodeAt(index);
|
|
128
|
+
low ^= code;
|
|
129
|
+
low = Math.imul(low, 0x01000193) >>> 0;
|
|
130
|
+
high ^= code + index;
|
|
131
|
+
high = Math.imul(high, 0x85ebca6b) >>> 0;
|
|
132
|
+
}
|
|
133
|
+
return `${low.toString(16).padStart(8, '0')}${high.toString(16).padStart(8, '0')}`;
|
|
134
|
+
};
|