@hexabot-ai/agentic 3.4.0 → 3.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +67 -15
- package/dist/cjs/action/abstract-action.js +13 -1
- package/dist/cjs/checkpoint.js +301 -0
- package/dist/cjs/context.js +11 -27
- package/dist/cjs/dsl.types.js +3 -0
- package/dist/cjs/errors.js +116 -9
- package/dist/cjs/index.js +15 -6
- package/dist/cjs/resume-payload.js +257 -0
- package/dist/cjs/runner-runtime-control.js +181 -306
- package/dist/cjs/step-executors/conditional-executor.js +27 -29
- package/dist/cjs/step-executors/loop-executor.js +53 -62
- package/dist/cjs/step-executors/parallel-executor.js +169 -102
- package/dist/cjs/step-executors/task-executor.js +180 -96
- package/dist/cjs/utils/clone.js +73 -0
- package/dist/cjs/workflow-fingerprint.js +138 -0
- package/dist/cjs/workflow-runner.js +220 -155
- package/dist/cjs/workflow.js +24 -12
- package/dist/esm/action/abstract-action.js +14 -2
- package/dist/esm/checkpoint.js +293 -0
- package/dist/esm/context.js +11 -27
- package/dist/esm/dsl.types.js +3 -0
- package/dist/esm/errors.js +105 -6
- package/dist/esm/index.js +3 -3
- package/dist/esm/resume-payload.js +250 -0
- package/dist/esm/runner-runtime-control.js +179 -303
- package/dist/esm/step-executors/conditional-executor.js +27 -29
- package/dist/esm/step-executors/loop-executor.js +53 -62
- package/dist/esm/step-executors/parallel-executor.js +165 -98
- package/dist/esm/step-executors/task-executor.js +181 -97
- package/dist/esm/utils/clone.js +67 -0
- package/dist/esm/workflow-fingerprint.js +134 -0
- package/dist/esm/workflow-runner.js +220 -155
- package/dist/esm/workflow.js +24 -12
- package/dist/types/action/abstract-action.d.ts.map +1 -1
- package/dist/types/action/action.types.d.ts +0 -14
- package/dist/types/action/action.types.d.ts.map +1 -1
- package/dist/types/checkpoint.d.ts +188 -0
- package/dist/types/checkpoint.d.ts.map +1 -0
- package/dist/types/context.d.ts +45 -11
- package/dist/types/context.d.ts.map +1 -1
- package/dist/types/dsl.types.d.ts.map +1 -1
- package/dist/types/errors.d.ts +77 -3
- package/dist/types/errors.d.ts.map +1 -1
- package/dist/types/index.d.ts +6 -7
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/resume-payload.d.ts +69 -0
- package/dist/types/resume-payload.d.ts.map +1 -0
- package/dist/types/runner-runtime-control.d.ts +63 -51
- package/dist/types/runner-runtime-control.d.ts.map +1 -1
- package/dist/types/step-executors/conditional-executor.d.ts +6 -3
- package/dist/types/step-executors/conditional-executor.d.ts.map +1 -1
- package/dist/types/step-executors/loop-executor.d.ts +6 -4
- package/dist/types/step-executors/loop-executor.d.ts.map +1 -1
- package/dist/types/step-executors/parallel-executor.d.ts +11 -3
- package/dist/types/step-executors/parallel-executor.d.ts.map +1 -1
- package/dist/types/step-executors/task-executor.d.ts +11 -4
- package/dist/types/step-executors/task-executor.d.ts.map +1 -1
- package/dist/types/step-executors/types.d.ts +21 -13
- package/dist/types/step-executors/types.d.ts.map +1 -1
- package/dist/types/utils/clone.d.ts +33 -0
- package/dist/types/utils/clone.d.ts.map +1 -0
- package/dist/types/workflow-event-emitter.d.ts +29 -5
- package/dist/types/workflow-event-emitter.d.ts.map +1 -1
- package/dist/types/workflow-fingerprint.d.ts +14 -0
- package/dist/types/workflow-fingerprint.d.ts.map +1 -0
- package/dist/types/workflow-runner.d.ts +83 -41
- package/dist/types/workflow-runner.d.ts.map +1 -1
- package/dist/types/workflow-types.d.ts +25 -54
- package/dist/types/workflow-types.d.ts.map +1 -1
- package/dist/types/workflow.d.ts +24 -9
- package/dist/types/workflow.d.ts.map +1 -1
- package/examples/defs-bindings-agent/bindings.ts +1 -1
- package/examples/defs-bindings-agent/workflow.ts +3 -2
- package/examples/full/actions/await-user-input.ts +3 -2
- package/examples/full/actions/call-llm.ts +18 -18
- package/examples/full/actions/create-ticket.ts +1 -2
- package/examples/full/actions/decision-router.ts +6 -2
- package/examples/full/actions/get-calendar-events.ts +1 -2
- package/examples/full/actions/get-user-profile.ts +1 -2
- package/examples/full/actions/query-memory.ts +1 -2
- package/examples/full/actions/search-web.ts +1 -2
- package/examples/full/actions/send-email.ts +3 -2
- package/examples/full/workflow.ts +3 -2
- package/examples/loop/actions/await-reply.ts +2 -7
- package/examples/loop/workflow.ts +4 -2
- package/examples/suspend-resume/actions/wait-for-user.ts +11 -9
- package/examples/suspend-resume/workflow.ts +51 -11
- package/package.json +3 -3
- package/src/__tests__/checkpoint.test.ts +2568 -0
- package/src/__tests__/resume-payload.test.ts +245 -0
- package/src/__tests__/runner-runtime-control.test.ts +265 -0
- package/src/__tests__/workflow-fingerprint.test.ts +165 -0
- package/src/__tests__/workflow-runner.test.ts +167 -144
- package/src/__tests__/workflow.test.ts +97 -6
- package/src/action/abstract-action.ts +21 -2
- package/src/action/action.types.ts +0 -12
- package/src/checkpoint.ts +561 -0
- package/src/context.ts +51 -41
- package/src/dsl.types.ts +3 -0
- package/src/errors.ts +161 -8
- package/src/index.ts +33 -14
- package/src/resume-payload.ts +326 -0
- package/src/runner-runtime-control.ts +222 -456
- package/src/step-executors/conditional-executor.test.ts +77 -46
- package/src/step-executors/conditional-executor.ts +47 -40
- package/src/step-executors/loop-executor.test.ts +106 -92
- package/src/step-executors/loop-executor.ts +84 -101
- package/src/step-executors/parallel-executor.test.ts +300 -89
- package/src/step-executors/parallel-executor.ts +243 -125
- package/src/step-executors/task-executor.test.ts +321 -51
- package/src/step-executors/task-executor.ts +232 -145
- package/src/step-executors/types.ts +23 -22
- package/src/utils/clone.ts +75 -0
- package/src/workflow-event-emitter.ts +32 -6
- package/src/workflow-fingerprint.ts +159 -0
- package/src/workflow-runner.ts +325 -209
- package/src/workflow-types.ts +25 -56
- package/src/workflow.ts +41 -34
- package/dist/cjs/step-executors/suspension-continuation.js +0 -27
- package/dist/cjs/suspension-rebuilder.js +0 -265
- package/dist/cjs/utils/deferred.js +0 -17
- package/dist/esm/step-executors/suspension-continuation.js +0 -24
- package/dist/esm/suspension-rebuilder.js +0 -260
- package/dist/esm/utils/deferred.js +0 -14
- package/dist/types/step-executors/suspension-continuation.d.ts +0 -10
- package/dist/types/step-executors/suspension-continuation.d.ts.map +0 -1
- package/dist/types/suspension-rebuilder.d.ts +0 -67
- package/dist/types/suspension-rebuilder.d.ts.map +0 -1
- package/dist/types/utils/deferred.d.ts +0 -7
- package/dist/types/utils/deferred.d.ts.map +0 -1
- package/src/__tests__/suspension-rebuilder.test.ts +0 -404
- package/src/step-executors/suspension-continuation.ts +0 -31
- package/src/suspension-rebuilder.ts +0 -446
- package/src/utils/deferred.ts +0 -23
package/src/workflow-types.ts
CHANGED
|
@@ -9,9 +9,11 @@ import type { ZodType } from 'zod';
|
|
|
9
9
|
|
|
10
10
|
import type { Action } from './action/action.types';
|
|
11
11
|
import type { CompiledTaskBindings } from './bindings/base-binding';
|
|
12
|
+
import type { WaitInfo, WorkflowCheckpoint } from './checkpoint';
|
|
12
13
|
import type { BaseWorkflowContext, WorkflowSnapshot } from './context';
|
|
13
14
|
import type { Settings, TaskDefinition, WorkflowDefinition } from './dsl.types';
|
|
14
|
-
import {
|
|
15
|
+
import type { WorkflowResumeRejectedError } from './errors';
|
|
16
|
+
import { StepType } from './workflow-event-emitter';
|
|
15
17
|
|
|
16
18
|
export type { CompiledTaskBindings } from './bindings/base-binding';
|
|
17
19
|
|
|
@@ -154,66 +156,35 @@ export type ExecutionState = {
|
|
|
154
156
|
iterationStack: number[];
|
|
155
157
|
};
|
|
156
158
|
|
|
157
|
-
/**
|
|
158
|
-
export type
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
159
|
+
/** Result of a run that paused on one or more open waits. */
|
|
160
|
+
export type SuspendedResult = {
|
|
161
|
+
status: 'suspended';
|
|
162
|
+
/** Open waits, in flow order; resume one of them by `waitId`. */
|
|
163
|
+
waits: WaitInfo[];
|
|
164
|
+
/** Everything a host must persist to resume the run later. */
|
|
165
|
+
checkpoint: WorkflowCheckpoint;
|
|
166
|
+
snapshot: WorkflowSnapshot;
|
|
167
|
+
/**
|
|
168
|
+
* Set when this resume was refused: the run and its checkpoint are exactly
|
|
169
|
+
* as they were, and the wait is still open under the same `waitId`.
|
|
170
|
+
*/
|
|
171
|
+
rejection?: ResumeRejection;
|
|
167
172
|
};
|
|
168
173
|
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
stepExecId?: string;
|
|
174
|
-
suspendIndex?: number;
|
|
175
|
-
suspendKey?: string;
|
|
176
|
-
awaitResults?: Record<string, unknown>;
|
|
174
|
+
/** A resume payload that was refused. */
|
|
175
|
+
export type ResumeRejection = {
|
|
176
|
+
waitId: string;
|
|
177
|
+
error: WorkflowResumeRejectedError;
|
|
177
178
|
};
|
|
178
179
|
|
|
179
|
-
/**
|
|
180
|
-
export type
|
|
180
|
+
/** Where a run stopped: the result of both `start()` and `resume()`. */
|
|
181
|
+
export type WorkflowRunResult =
|
|
181
182
|
| {
|
|
182
183
|
status: 'finished';
|
|
183
184
|
output: Record<string, unknown>;
|
|
184
185
|
snapshot: WorkflowSnapshot;
|
|
185
186
|
}
|
|
186
|
-
|
|
|
187
|
-
status: 'suspended';
|
|
188
|
-
step: StepInfo;
|
|
189
|
-
reason?: string;
|
|
190
|
-
data?: unknown;
|
|
191
|
-
stepExecId?: string;
|
|
192
|
-
suspendIndex?: number;
|
|
193
|
-
suspendKey?: string;
|
|
194
|
-
awaitResults?: Record<string, unknown>;
|
|
195
|
-
snapshot: WorkflowSnapshot;
|
|
196
|
-
}
|
|
197
|
-
| { status: 'failed'; error: unknown; snapshot: WorkflowSnapshot };
|
|
198
|
-
|
|
199
|
-
/** Result of resuming a suspended workflow. */
|
|
200
|
-
export type ResumeResult =
|
|
201
|
-
| {
|
|
202
|
-
status: 'finished';
|
|
203
|
-
output: Record<string, unknown>;
|
|
204
|
-
snapshot: WorkflowSnapshot;
|
|
205
|
-
}
|
|
206
|
-
| {
|
|
207
|
-
status: 'suspended';
|
|
208
|
-
step: StepInfo;
|
|
209
|
-
reason?: string;
|
|
210
|
-
data?: unknown;
|
|
211
|
-
stepExecId?: string;
|
|
212
|
-
suspendIndex?: number;
|
|
213
|
-
suspendKey?: string;
|
|
214
|
-
awaitResults?: Record<string, unknown>;
|
|
215
|
-
snapshot: WorkflowSnapshot;
|
|
216
|
-
}
|
|
187
|
+
| SuspendedResult
|
|
217
188
|
| { status: 'failed'; error: unknown; snapshot: WorkflowSnapshot };
|
|
218
189
|
|
|
219
190
|
/** Options that influence how the workflow runner behaves. */
|
|
@@ -221,10 +192,6 @@ export type WorkflowRunOptions = {
|
|
|
221
192
|
runId?: string;
|
|
222
193
|
};
|
|
223
194
|
|
|
224
|
-
export type WorkflowStartResult = StartResult;
|
|
225
|
-
|
|
226
|
-
export type WorkflowResumeResult = ResumeResult;
|
|
227
|
-
|
|
228
195
|
/** Arguments required to start a run. */
|
|
229
196
|
export type RunnerStartArgs = {
|
|
230
197
|
inputData: unknown;
|
|
@@ -234,4 +201,6 @@ export type RunnerStartArgs = {
|
|
|
234
201
|
/** Payload passed when resuming a suspended run. */
|
|
235
202
|
export type RunnerResumeArgs = {
|
|
236
203
|
resumeData?: unknown;
|
|
204
|
+
/** Wait to satisfy; required only when the run has several open waits. */
|
|
205
|
+
waitId?: string;
|
|
237
206
|
};
|
package/src/workflow.ts
CHANGED
|
@@ -6,6 +6,11 @@
|
|
|
6
6
|
|
|
7
7
|
import { stringify as stringifyYaml } from 'yaml';
|
|
8
8
|
|
|
9
|
+
import {
|
|
10
|
+
validateCheckpoint,
|
|
11
|
+
type CheckpointValidationResult,
|
|
12
|
+
type WaitInfo,
|
|
13
|
+
} from './checkpoint';
|
|
9
14
|
import {
|
|
10
15
|
EWorkflowRunStatus,
|
|
11
16
|
type BaseWorkflowContext,
|
|
@@ -25,12 +30,7 @@ import {
|
|
|
25
30
|
type WorkflowCompileOptions,
|
|
26
31
|
} from './workflow-compiler';
|
|
27
32
|
import { WorkflowRunner } from './workflow-runner';
|
|
28
|
-
import type {
|
|
29
|
-
CompiledWorkflow,
|
|
30
|
-
ExecutionState,
|
|
31
|
-
PersistedSuspension,
|
|
32
|
-
WorkflowRunOptions,
|
|
33
|
-
} from './workflow-types';
|
|
33
|
+
import type { CompiledWorkflow, WorkflowRunOptions } from './workflow-types';
|
|
34
34
|
|
|
35
35
|
export { compileWorkflow } from './workflow-compiler';
|
|
36
36
|
|
|
@@ -38,31 +38,24 @@ export { WorkflowEventEmitter } from './workflow-event-emitter';
|
|
|
38
38
|
|
|
39
39
|
export { WorkflowRunner } from './workflow-runner';
|
|
40
40
|
|
|
41
|
-
export type {
|
|
42
|
-
WorkflowResumeResult,
|
|
43
|
-
WorkflowRunOptions,
|
|
44
|
-
WorkflowStartResult,
|
|
45
|
-
} from './workflow-types';
|
|
41
|
+
export type { WorkflowRunOptions, WorkflowRunResult } from './workflow-types';
|
|
46
42
|
|
|
47
43
|
export type { WorkflowCompileOptions } from './workflow-compiler';
|
|
48
44
|
|
|
49
45
|
export type FlowStepPath = Array<string | number>;
|
|
50
46
|
|
|
51
47
|
class WorkflowRunSuspendedError extends Error {
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
public readonly reason?: string;
|
|
55
|
-
|
|
56
|
-
public readonly data?: unknown;
|
|
48
|
+
/** Every open wait of the run, in flow order. */
|
|
49
|
+
public readonly waits: WaitInfo[];
|
|
57
50
|
|
|
58
|
-
constructor(
|
|
59
|
-
|
|
60
|
-
|
|
51
|
+
constructor(waits: WaitInfo[]) {
|
|
52
|
+
const steps = waits.map(({ step, reason }) =>
|
|
53
|
+
reason ? `${step.id} (${reason})` : step.id,
|
|
61
54
|
);
|
|
55
|
+
|
|
56
|
+
super(`Workflow run suspended at ${steps.join(', ')}`);
|
|
62
57
|
this.name = 'WorkflowRunSuspendedError';
|
|
63
|
-
this.
|
|
64
|
-
this.reason = options?.reason;
|
|
65
|
-
this.data = options?.data;
|
|
58
|
+
this.waits = waits;
|
|
66
59
|
}
|
|
67
60
|
}
|
|
68
61
|
|
|
@@ -357,10 +350,7 @@ export class Workflow {
|
|
|
357
350
|
}
|
|
358
351
|
|
|
359
352
|
context.attachWorkflowRuntime(undefined);
|
|
360
|
-
throw new WorkflowRunSuspendedError(result.
|
|
361
|
-
reason: result.reason,
|
|
362
|
-
data: result.data,
|
|
363
|
-
});
|
|
353
|
+
throw new WorkflowRunSuspendedError(result.waits);
|
|
364
354
|
}
|
|
365
355
|
|
|
366
356
|
/**
|
|
@@ -373,16 +363,33 @@ export class Workflow {
|
|
|
373
363
|
}
|
|
374
364
|
|
|
375
365
|
/**
|
|
376
|
-
*
|
|
366
|
+
* Decide whether a persisted checkpoint can resume against this workflow,
|
|
367
|
+
* without running anything. Call it before claiming a wait.
|
|
368
|
+
*
|
|
369
|
+
* @param checkpoint The checkpoint, as persisted.
|
|
370
|
+
* @param options.waitId Wait the caller is about to resume.
|
|
371
|
+
* @param options.resumeData Payload the caller is about to resume with,
|
|
372
|
+
* checked against what the wait accepts when the key is present.
|
|
373
|
+
* @returns The parsed checkpoint, or the typed reason it cannot resume.
|
|
374
|
+
*/
|
|
375
|
+
validateCheckpoint(
|
|
376
|
+
checkpoint: unknown,
|
|
377
|
+
options?: { waitId?: string; resumeData?: unknown },
|
|
378
|
+
): CheckpointValidationResult {
|
|
379
|
+
return validateCheckpoint(this.compiled, checkpoint, options);
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
/**
|
|
383
|
+
* Restore a suspended runner from its persisted checkpoint, useful after restarts.
|
|
384
|
+
*
|
|
385
|
+
* @throws {WorkflowResumeError} When the checkpoint cannot resume against this workflow.
|
|
377
386
|
*/
|
|
378
|
-
|
|
379
|
-
|
|
387
|
+
buildRunnerFromCheckpoint(options: {
|
|
388
|
+
checkpoint: unknown;
|
|
380
389
|
context: BaseWorkflowContext;
|
|
381
|
-
snapshot
|
|
382
|
-
suspension?: PersistedSuspension;
|
|
390
|
+
snapshot?: WorkflowSnapshot;
|
|
383
391
|
runId?: string;
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
return WorkflowRunner.fromPersistedState(this.compiled, options);
|
|
392
|
+
}): WorkflowRunner {
|
|
393
|
+
return WorkflowRunner.fromCheckpoint(this.compiled, options);
|
|
387
394
|
}
|
|
388
395
|
}
|
|
@@ -1,27 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
/*
|
|
3
|
-
* Hexabot — Fair Core License (FCL-1.0-ALv2)
|
|
4
|
-
* Copyright (c) 2025 Hexastack.
|
|
5
|
-
* Full terms: see LICENSE.md.
|
|
6
|
-
*/
|
|
7
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
8
|
-
exports.wrapSuspensionContinuation = wrapSuspensionContinuation;
|
|
9
|
-
/**
|
|
10
|
-
* Compose a suspension with the continuation that should run once it completes.
|
|
11
|
-
*
|
|
12
|
-
* When resuming a suspension yields another suspension from the same logical
|
|
13
|
-
* step, the follow-up suspension still needs to remember how to continue the
|
|
14
|
-
* surrounding flow after that step eventually finishes.
|
|
15
|
-
*/
|
|
16
|
-
function wrapSuspensionContinuation(suspension, onComplete) {
|
|
17
|
-
return {
|
|
18
|
-
...suspension,
|
|
19
|
-
continue: async (resumeData) => {
|
|
20
|
-
const next = await suspension.continue(resumeData);
|
|
21
|
-
if (next) {
|
|
22
|
-
return wrapSuspensionContinuation(next, onComplete);
|
|
23
|
-
}
|
|
24
|
-
return onComplete();
|
|
25
|
-
},
|
|
26
|
-
};
|
|
27
|
-
}
|
|
@@ -1,265 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
/*
|
|
3
|
-
* Hexabot — Fair Core License (FCL-1.0-ALv2)
|
|
4
|
-
* Copyright (c) 2025 Hexastack.
|
|
5
|
-
* Full terms: see LICENSE.md.
|
|
6
|
-
*/
|
|
7
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
8
|
-
exports.parseSuspendedStepId = parseSuspendedStepId;
|
|
9
|
-
exports.rebuildSuspension = rebuildSuspension;
|
|
10
|
-
exports.buildSuspensionForPath = buildSuspensionForPath;
|
|
11
|
-
const loop_executor_1 = require("./step-executors/loop-executor");
|
|
12
|
-
const suspension_continuation_1 = require("./step-executors/suspension-continuation");
|
|
13
|
-
const workflow_event_emitter_1 = require("./workflow-event-emitter");
|
|
14
|
-
/**
|
|
15
|
-
* Parse a suspended step id into its execution path and iteration stack.
|
|
16
|
-
*
|
|
17
|
-
* @param stepId The serialized step identifier stored in snapshots.
|
|
18
|
-
* @returns The decoded path tokens and iteration stack.
|
|
19
|
-
*/
|
|
20
|
-
function parseSuspendedStepId(stepId) {
|
|
21
|
-
const iterationMatch = stepId.match(/^(.*)\[(.+)\]$/);
|
|
22
|
-
const baseId = iterationMatch ? iterationMatch[1] : stepId;
|
|
23
|
-
const iterationStack = iterationMatch
|
|
24
|
-
? iterationMatch[2]
|
|
25
|
-
.split('.')
|
|
26
|
-
.map((token) => Number.parseInt(token, 10))
|
|
27
|
-
.filter((value) => !Number.isNaN(value))
|
|
28
|
-
: [];
|
|
29
|
-
const [pathPart] = baseId.split(':');
|
|
30
|
-
const path = pathPart.length === 0 || pathPart === 'root'
|
|
31
|
-
? []
|
|
32
|
-
: pathPart.split('.').map((token) => {
|
|
33
|
-
const numeric = Number.parseInt(token, 10);
|
|
34
|
-
return Number.isNaN(numeric) ? token : numeric;
|
|
35
|
-
});
|
|
36
|
-
return { path, iterationStack };
|
|
37
|
-
}
|
|
38
|
-
/**
|
|
39
|
-
* Rebuild a suspension object based on persisted state and step identifiers.
|
|
40
|
-
*
|
|
41
|
-
* @param deps Dependencies needed to reconstruct executors and events.
|
|
42
|
-
* @param param0 Persisted state and metadata about the suspended step.
|
|
43
|
-
* @param param0.state Execution state captured at suspension time.
|
|
44
|
-
* @param param0.stepId Serialized step id used to locate the suspension point.
|
|
45
|
-
* @param param0.reason Optional reason supplied when the workflow suspended.
|
|
46
|
-
* @param param0.data Arbitrary payload provided with the suspension.
|
|
47
|
-
* @returns A suspension ready to be resumed, or null if reconstruction fails.
|
|
48
|
-
*/
|
|
49
|
-
function rebuildSuspension(deps, { state, stepId, reason, data, stepExecId, suspendIndex, suspendKey, awaitResults, }) {
|
|
50
|
-
if (!state) {
|
|
51
|
-
return null;
|
|
52
|
-
}
|
|
53
|
-
const { path, iterationStack } = parseSuspendedStepId(stepId);
|
|
54
|
-
const executionState = {
|
|
55
|
-
...state,
|
|
56
|
-
iterationStack: iterationStack.length > 0 ? iterationStack : (state.iterationStack ?? []),
|
|
57
|
-
};
|
|
58
|
-
const suspensionMetadata = {
|
|
59
|
-
stepExecId,
|
|
60
|
-
suspendIndex,
|
|
61
|
-
suspendKey,
|
|
62
|
-
reason,
|
|
63
|
-
awaitResults,
|
|
64
|
-
};
|
|
65
|
-
const suspension = buildSuspensionForPath(deps, deps.compiled.flow, executionState, path, [], 0, suspensionMetadata);
|
|
66
|
-
if (!suspension) {
|
|
67
|
-
return null;
|
|
68
|
-
}
|
|
69
|
-
return {
|
|
70
|
-
...suspension,
|
|
71
|
-
reason,
|
|
72
|
-
data,
|
|
73
|
-
stepExecId,
|
|
74
|
-
suspendIndex,
|
|
75
|
-
suspendKey,
|
|
76
|
-
awaitResults,
|
|
77
|
-
};
|
|
78
|
-
}
|
|
79
|
-
/**
|
|
80
|
-
* Walk the compiled flow to rebuild the continuation matching a target path.
|
|
81
|
-
*
|
|
82
|
-
* @param deps Dependencies for executor creation and event emission.
|
|
83
|
-
* @param steps The steps to search for the suspended step.
|
|
84
|
-
* @param state Mutable execution state to thread through the traversal.
|
|
85
|
-
* @param targetPath Path tokens identifying the suspended step location.
|
|
86
|
-
* @param pathPrefix Prefix accumulated while descending the tree.
|
|
87
|
-
* @param iterationDepth Current loop depth to match iteration stacks.
|
|
88
|
-
* @returns A rebuilt suspension or null if the path cannot be matched.
|
|
89
|
-
*/
|
|
90
|
-
function buildSuspensionForPath(deps, steps, state, targetPath, pathPrefix, iterationDepth = 0, suspensionMetadata = {}) {
|
|
91
|
-
if (!deps.context) {
|
|
92
|
-
throw new Error('Workflow context is not attached.');
|
|
93
|
-
}
|
|
94
|
-
const env = deps.createExecutorEnv();
|
|
95
|
-
if (targetPath.length === 0) {
|
|
96
|
-
return null;
|
|
97
|
-
}
|
|
98
|
-
const [current, ...rest] = targetPath;
|
|
99
|
-
if (typeof current !== 'number') {
|
|
100
|
-
return null;
|
|
101
|
-
}
|
|
102
|
-
const step = steps[current];
|
|
103
|
-
const currentPath = [...pathPrefix, current];
|
|
104
|
-
if (!step) {
|
|
105
|
-
return null;
|
|
106
|
-
}
|
|
107
|
-
if (rest.length === 0) {
|
|
108
|
-
if (step.type !== workflow_event_emitter_1.StepType.Task) {
|
|
109
|
-
return null;
|
|
110
|
-
}
|
|
111
|
-
const stepInfo = deps.buildInstanceStepInfo(step, state.iterationStack);
|
|
112
|
-
const replayStepExecId = suspensionMetadata.stepExecId ?? `${stepInfo.id}#1`;
|
|
113
|
-
const replaySuspension = suspensionMetadata.suspendIndex !== undefined ||
|
|
114
|
-
suspensionMetadata.suspendKey !== undefined
|
|
115
|
-
? {
|
|
116
|
-
suspendIndex: suspensionMetadata.suspendIndex,
|
|
117
|
-
suspendKey: suspensionMetadata.suspendKey,
|
|
118
|
-
reason: suspensionMetadata.reason,
|
|
119
|
-
}
|
|
120
|
-
: undefined;
|
|
121
|
-
return {
|
|
122
|
-
step: stepInfo,
|
|
123
|
-
continue: async (resumeData) => {
|
|
124
|
-
const executorEnv = deps.createExecutorEnv();
|
|
125
|
-
const prepareStepReplay = executorEnv
|
|
126
|
-
.prepareStepReplay;
|
|
127
|
-
const recordStepSuspendResult = executorEnv.recordStepSuspendResult;
|
|
128
|
-
const primeStepResumeData = executorEnv
|
|
129
|
-
.primeStepResumeData;
|
|
130
|
-
const executeStep = executorEnv
|
|
131
|
-
.executeStep;
|
|
132
|
-
if (typeof executeStep === 'function') {
|
|
133
|
-
if (typeof prepareStepReplay === 'function') {
|
|
134
|
-
prepareStepReplay({
|
|
135
|
-
stepId: stepInfo.id,
|
|
136
|
-
stepExecId: replayStepExecId,
|
|
137
|
-
awaitResults: suspensionMetadata.awaitResults,
|
|
138
|
-
activeSuspension: replaySuspension,
|
|
139
|
-
});
|
|
140
|
-
}
|
|
141
|
-
if (typeof recordStepSuspendResult === 'function' &&
|
|
142
|
-
replaySuspension) {
|
|
143
|
-
recordStepSuspendResult({
|
|
144
|
-
stepId: stepInfo.id,
|
|
145
|
-
stepExecId: replayStepExecId,
|
|
146
|
-
suspendIndex: suspensionMetadata.suspendIndex,
|
|
147
|
-
suspendKey: suspensionMetadata.suspendKey,
|
|
148
|
-
resumeData,
|
|
149
|
-
});
|
|
150
|
-
}
|
|
151
|
-
else if (typeof primeStepResumeData === 'function') {
|
|
152
|
-
primeStepResumeData(stepInfo.id, resumeData);
|
|
153
|
-
}
|
|
154
|
-
const resumed = await executeStep(step, state, currentPath);
|
|
155
|
-
if (resumed) {
|
|
156
|
-
return (0, suspension_continuation_1.wrapSuspensionContinuation)(resumed, () => deps.executeFlow(steps, state, pathPrefix, current + 1));
|
|
157
|
-
}
|
|
158
|
-
return deps.executeFlow(steps, state, pathPrefix, current + 1);
|
|
159
|
-
}
|
|
160
|
-
const task = deps.compiled.tasks[step.taskName];
|
|
161
|
-
if (!task) {
|
|
162
|
-
throw new Error(`Task "${step.taskName}" is not defined.`);
|
|
163
|
-
}
|
|
164
|
-
await deps.captureTaskOutput(task, state, resumeData);
|
|
165
|
-
deps.markSnapshot(stepInfo, 'completed');
|
|
166
|
-
deps.emit('hook:step:success', { runId: deps.runId, step: stepInfo });
|
|
167
|
-
return deps.executeFlow(steps, state, pathPrefix, current + 1);
|
|
168
|
-
},
|
|
169
|
-
};
|
|
170
|
-
}
|
|
171
|
-
if (step.type === workflow_event_emitter_1.StepType.Parallel) {
|
|
172
|
-
return null;
|
|
173
|
-
}
|
|
174
|
-
if (step.type === workflow_event_emitter_1.StepType.Conditional) {
|
|
175
|
-
if (rest[0] !== 'branch' || typeof rest[1] !== 'number') {
|
|
176
|
-
return null;
|
|
177
|
-
}
|
|
178
|
-
const branchIndex = rest[1];
|
|
179
|
-
const childPath = rest.slice(2);
|
|
180
|
-
const branch = step.branches[branchIndex];
|
|
181
|
-
if (!branch) {
|
|
182
|
-
return null;
|
|
183
|
-
}
|
|
184
|
-
const branchSuspension = buildSuspensionForPath(deps, branch.steps, state, childPath, [...currentPath, 'branch', branchIndex], iterationDepth, suspensionMetadata);
|
|
185
|
-
if (!branchSuspension) {
|
|
186
|
-
return null;
|
|
187
|
-
}
|
|
188
|
-
return (0, suspension_continuation_1.wrapSuspensionContinuation)(branchSuspension, () => deps.executeFlow(steps, state, pathPrefix, current + 1));
|
|
189
|
-
}
|
|
190
|
-
if (step.type === workflow_event_emitter_1.StepType.Loop) {
|
|
191
|
-
if (rest.length < 1 || typeof rest[0] !== 'string') {
|
|
192
|
-
return null;
|
|
193
|
-
}
|
|
194
|
-
const loopToken = rest[0];
|
|
195
|
-
const childPath = rest.slice(1);
|
|
196
|
-
const targetIterationStack = state.iterationStack ?? [];
|
|
197
|
-
const iterationIndex = targetIterationStack[iterationDepth] ?? state.iteration?.index;
|
|
198
|
-
if (iterationIndex === undefined) {
|
|
199
|
-
return null;
|
|
200
|
-
}
|
|
201
|
-
const ancestorIterationStack = targetIterationStack.slice(0, iterationDepth);
|
|
202
|
-
const iterationState = {
|
|
203
|
-
...state,
|
|
204
|
-
iterationStack: targetIterationStack,
|
|
205
|
-
iteration: state.iteration ??
|
|
206
|
-
{
|
|
207
|
-
item: undefined,
|
|
208
|
-
index: iterationIndex,
|
|
209
|
-
},
|
|
210
|
-
};
|
|
211
|
-
const childSuspension = buildSuspensionForPath(deps, step.steps, iterationState, childPath, [...currentPath, loopToken], iterationDepth + 1, suspensionMetadata);
|
|
212
|
-
if (!childSuspension) {
|
|
213
|
-
return null;
|
|
214
|
-
}
|
|
215
|
-
const accumulator = iterationState.accumulator ?? state.accumulator ?? undefined;
|
|
216
|
-
return (0, suspension_continuation_1.wrapSuspensionContinuation)(childSuspension, async () => {
|
|
217
|
-
const scope = {
|
|
218
|
-
input: iterationState.input,
|
|
219
|
-
context: env.context.state,
|
|
220
|
-
output: iterationState.output,
|
|
221
|
-
iteration: iterationState.iteration ?? {
|
|
222
|
-
item: undefined,
|
|
223
|
-
index: iterationIndex,
|
|
224
|
-
},
|
|
225
|
-
accumulator,
|
|
226
|
-
};
|
|
227
|
-
const updatedAccumulator = await (0, loop_executor_1.updateAccumulator)(step, scope, accumulator);
|
|
228
|
-
const shouldStop = await (0, loop_executor_1.shouldStopLoop)(step, scope);
|
|
229
|
-
state.output = iterationState.output;
|
|
230
|
-
if (step.accumulate && step.name) {
|
|
231
|
-
state.output[step.name] = {
|
|
232
|
-
[step.accumulate.as]: updatedAccumulator,
|
|
233
|
-
};
|
|
234
|
-
}
|
|
235
|
-
if (step.accumulate) {
|
|
236
|
-
state.accumulator = updatedAccumulator;
|
|
237
|
-
}
|
|
238
|
-
if (shouldStop) {
|
|
239
|
-
return deps.executeFlow(steps, state, pathPrefix, current + 1);
|
|
240
|
-
}
|
|
241
|
-
const baseState = {
|
|
242
|
-
...iterationState,
|
|
243
|
-
iterationStack: ancestorIterationStack,
|
|
244
|
-
accumulator: updatedAccumulator,
|
|
245
|
-
output: state.output,
|
|
246
|
-
};
|
|
247
|
-
const next = await (0, loop_executor_1.executeLoop)(env, step, baseState, currentPath, iterationIndex + 1);
|
|
248
|
-
state.output = baseState.output;
|
|
249
|
-
if (step.accumulate) {
|
|
250
|
-
state.accumulator = baseState.accumulator;
|
|
251
|
-
}
|
|
252
|
-
if (next) {
|
|
253
|
-
return (0, suspension_continuation_1.wrapSuspensionContinuation)(next, async () => {
|
|
254
|
-
state.output = baseState.output;
|
|
255
|
-
if (step.accumulate) {
|
|
256
|
-
state.accumulator = baseState.accumulator;
|
|
257
|
-
}
|
|
258
|
-
return deps.executeFlow(steps, state, pathPrefix, current + 1);
|
|
259
|
-
});
|
|
260
|
-
}
|
|
261
|
-
return deps.executeFlow(steps, state, pathPrefix, current + 1);
|
|
262
|
-
});
|
|
263
|
-
}
|
|
264
|
-
return null;
|
|
265
|
-
}
|
|
@@ -1,17 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
/*
|
|
3
|
-
* Hexabot — Fair Core License (FCL-1.0-ALv2)
|
|
4
|
-
* Copyright (c) 2025 Hexastack.
|
|
5
|
-
* Full terms: see LICENSE.md.
|
|
6
|
-
*/
|
|
7
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
8
|
-
exports.createDeferred = createDeferred;
|
|
9
|
-
function createDeferred() {
|
|
10
|
-
let resolve;
|
|
11
|
-
let reject;
|
|
12
|
-
const promise = new Promise((res, rej) => {
|
|
13
|
-
resolve = res;
|
|
14
|
-
reject = rej;
|
|
15
|
-
});
|
|
16
|
-
return { promise, resolve, reject };
|
|
17
|
-
}
|
|
@@ -1,24 +0,0 @@
|
|
|
1
|
-
/*
|
|
2
|
-
* Hexabot — Fair Core License (FCL-1.0-ALv2)
|
|
3
|
-
* Copyright (c) 2025 Hexastack.
|
|
4
|
-
* Full terms: see LICENSE.md.
|
|
5
|
-
*/
|
|
6
|
-
/**
|
|
7
|
-
* Compose a suspension with the continuation that should run once it completes.
|
|
8
|
-
*
|
|
9
|
-
* When resuming a suspension yields another suspension from the same logical
|
|
10
|
-
* step, the follow-up suspension still needs to remember how to continue the
|
|
11
|
-
* surrounding flow after that step eventually finishes.
|
|
12
|
-
*/
|
|
13
|
-
export function wrapSuspensionContinuation(suspension, onComplete) {
|
|
14
|
-
return {
|
|
15
|
-
...suspension,
|
|
16
|
-
continue: async (resumeData) => {
|
|
17
|
-
const next = await suspension.continue(resumeData);
|
|
18
|
-
if (next) {
|
|
19
|
-
return wrapSuspensionContinuation(next, onComplete);
|
|
20
|
-
}
|
|
21
|
-
return onComplete();
|
|
22
|
-
},
|
|
23
|
-
};
|
|
24
|
-
}
|