@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
|
@@ -4,7 +4,9 @@
|
|
|
4
4
|
* Full terms: see LICENSE.md.
|
|
5
5
|
*/
|
|
6
6
|
|
|
7
|
+
import type { WaitInfo } from './checkpoint';
|
|
7
8
|
import type { StepExecutionRecord } from './context';
|
|
9
|
+
import type { WorkflowResumeRejectedError } from './errors';
|
|
8
10
|
|
|
9
11
|
export enum StepType {
|
|
10
12
|
Task = 'task',
|
|
@@ -31,17 +33,41 @@ export type WorkflowEventMap = {
|
|
|
31
33
|
'hook:workflow:failure': { runId?: string; error: unknown };
|
|
32
34
|
'hook:workflow:suspended': {
|
|
33
35
|
runId?: string;
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
36
|
+
/** Every open wait of the run, in flow order. */
|
|
37
|
+
waits: WaitInfo[];
|
|
38
|
+
};
|
|
39
|
+
/** A resume payload was refused; the run is unchanged and the wait stays open. */
|
|
40
|
+
'hook:workflow:resume_rejected': {
|
|
41
|
+
runId?: string;
|
|
42
|
+
/** The wait the payload was meant for. */
|
|
43
|
+
wait: WaitInfo;
|
|
44
|
+
/** The payload as passed to `resume()`. */
|
|
45
|
+
resumeData: unknown;
|
|
46
|
+
error: WorkflowResumeRejectedError;
|
|
37
47
|
};
|
|
38
48
|
'hook:step:start': StepWorkflowEventPayload;
|
|
49
|
+
/** A suspended step whose wait was resolved re-runs its action body. */
|
|
50
|
+
'hook:step:resumed': StepWorkflowEventPayload & {
|
|
51
|
+
/** The wait this resume resolved. */
|
|
52
|
+
wait: WaitInfo;
|
|
53
|
+
/** The payload recorded for the wait, after its JSON round trip. */
|
|
54
|
+
resumeData: unknown;
|
|
55
|
+
};
|
|
56
|
+
/** A resumed step refused its payload and is suspended again on the same wait. */
|
|
57
|
+
'hook:step:resume_rejected': StepWorkflowEventPayload & {
|
|
58
|
+
wait: WaitInfo;
|
|
59
|
+
error: WorkflowResumeRejectedError;
|
|
60
|
+
};
|
|
39
61
|
'hook:step:success': StepWorkflowEventPayload;
|
|
40
62
|
'hook:step:error': StepWorkflowEventPayload & { error: unknown };
|
|
41
|
-
'hook:step:cancelled': StepWorkflowEventPayload & {
|
|
63
|
+
'hook:step:cancelled': StepWorkflowEventPayload & {
|
|
64
|
+
error: unknown;
|
|
65
|
+
/** The wait the step was suspended on, which is now dropped. */
|
|
66
|
+
wait?: WaitInfo;
|
|
67
|
+
};
|
|
42
68
|
'hook:step:suspended': StepWorkflowEventPayload & {
|
|
43
|
-
|
|
44
|
-
|
|
69
|
+
/** The wait this suspension opened. */
|
|
70
|
+
wait: WaitInfo;
|
|
45
71
|
};
|
|
46
72
|
'hook:step:skipped': { runId?: string; step: StepInfo; reason?: string };
|
|
47
73
|
};
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Hexabot — Fair Core License (FCL-1.0-ALv2)
|
|
3
|
+
* Copyright (c) 2025 Hexastack.
|
|
4
|
+
* Full terms: see LICENSE.md.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { StepType } from './workflow-event-emitter';
|
|
8
|
+
import type {
|
|
9
|
+
CompiledMapping,
|
|
10
|
+
CompiledStep,
|
|
11
|
+
CompiledValue,
|
|
12
|
+
CompiledWorkflow,
|
|
13
|
+
} from './workflow-types';
|
|
14
|
+
|
|
15
|
+
/** Separator between fingerprint parts; never produced by the parts themselves. */
|
|
16
|
+
const PART_SEPARATOR = '~|~';
|
|
17
|
+
/** Fingerprints are pure functions of the compiled graph, so compute each once. */
|
|
18
|
+
const fingerprintCache = new WeakMap<CompiledWorkflow, string>();
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Fingerprint the parts of a compiled workflow that a checkpoint depends on.
|
|
22
|
+
*
|
|
23
|
+
* Hashing step ids alone is not enough: a changed `until`, `while`, branch
|
|
24
|
+
* condition or `inputs` mapping keeps every id stable while changing what the
|
|
25
|
+
* resumed run actually does. Labels are included because `buildStepId`
|
|
26
|
+
* embeds them, so renaming a task changes every downstream step id.
|
|
27
|
+
*
|
|
28
|
+
* @param compiled The compiled workflow to fingerprint.
|
|
29
|
+
* @returns A short, stable hash of the resume-relevant definition surface.
|
|
30
|
+
*/
|
|
31
|
+
export const fingerprintWorkflow = (compiled: CompiledWorkflow): string => {
|
|
32
|
+
const cached = fingerprintCache.get(compiled);
|
|
33
|
+
if (cached !== undefined) {
|
|
34
|
+
return cached;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
const parts: string[] = [];
|
|
38
|
+
|
|
39
|
+
collectSteps(compiled, compiled.flow, parts);
|
|
40
|
+
parts.push('outputs', ...describeMapping(compiled.outputMapping));
|
|
41
|
+
|
|
42
|
+
const fingerprint = hash(parts.join(PART_SEPARATOR));
|
|
43
|
+
fingerprintCache.set(compiled, fingerprint);
|
|
44
|
+
|
|
45
|
+
return fingerprint;
|
|
46
|
+
};
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Append a canonical description of each step, depth first.
|
|
50
|
+
*
|
|
51
|
+
* @param compiled The compiled workflow, used to resolve task definitions.
|
|
52
|
+
* @param steps Steps to describe.
|
|
53
|
+
* @param parts Accumulator receiving the description fragments.
|
|
54
|
+
*/
|
|
55
|
+
const collectSteps = (
|
|
56
|
+
compiled: CompiledWorkflow,
|
|
57
|
+
steps: CompiledStep[],
|
|
58
|
+
parts: string[],
|
|
59
|
+
): void => {
|
|
60
|
+
for (const step of steps) {
|
|
61
|
+
parts.push(step.type, step.id, step.label);
|
|
62
|
+
|
|
63
|
+
switch (step.type) {
|
|
64
|
+
case StepType.Task: {
|
|
65
|
+
const task = compiled.tasks[step.taskName];
|
|
66
|
+
|
|
67
|
+
parts.push(step.taskName, task?.actionName ?? '');
|
|
68
|
+
parts.push(...describeMapping(task?.inputs));
|
|
69
|
+
break;
|
|
70
|
+
}
|
|
71
|
+
case StepType.Parallel:
|
|
72
|
+
parts.push(step.strategy);
|
|
73
|
+
collectSteps(compiled, step.steps, parts);
|
|
74
|
+
break;
|
|
75
|
+
case StepType.Conditional:
|
|
76
|
+
for (const branch of step.branches) {
|
|
77
|
+
parts.push(branch.id, describeValue(branch.condition));
|
|
78
|
+
collectSteps(compiled, branch.steps, parts);
|
|
79
|
+
}
|
|
80
|
+
break;
|
|
81
|
+
case StepType.Loop:
|
|
82
|
+
parts.push(step.loopType, step.name ?? '');
|
|
83
|
+
parts.push(
|
|
84
|
+
step.accumulate
|
|
85
|
+
? `${step.accumulate.as}=${stringify(step.accumulate.initial)}:${describeValue(step.accumulate.merge)}`
|
|
86
|
+
: '',
|
|
87
|
+
);
|
|
88
|
+
if (step.loopType === 'for_each') {
|
|
89
|
+
parts.push(step.forEach.item, describeValue(step.forEach.in));
|
|
90
|
+
parts.push(describeValue(step.until));
|
|
91
|
+
} else {
|
|
92
|
+
parts.push(describeValue(step.while));
|
|
93
|
+
}
|
|
94
|
+
collectSteps(compiled, step.steps, parts);
|
|
95
|
+
break;
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
};
|
|
99
|
+
/**
|
|
100
|
+
* Describe a compiled mapping in a key-stable order.
|
|
101
|
+
*
|
|
102
|
+
* @param mapping The mapping to describe.
|
|
103
|
+
* @returns One fragment per mapped key.
|
|
104
|
+
*/
|
|
105
|
+
const describeMapping = (mapping?: CompiledMapping): string[] => {
|
|
106
|
+
if (!mapping) {
|
|
107
|
+
return [];
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
return Object.keys(mapping)
|
|
111
|
+
.sort()
|
|
112
|
+
.map((key) => `${key}=${describeValue(mapping[key])}`);
|
|
113
|
+
};
|
|
114
|
+
/**
|
|
115
|
+
* Describe a compiled value by its authored source, not its compiled form.
|
|
116
|
+
*
|
|
117
|
+
* @param value The compiled value.
|
|
118
|
+
* @returns A stable textual description.
|
|
119
|
+
*/
|
|
120
|
+
const describeValue = (value?: CompiledValue): string => {
|
|
121
|
+
if (!value) {
|
|
122
|
+
return '';
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
return value.kind === 'expression'
|
|
126
|
+
? `=${value.source}`
|
|
127
|
+
: stringify(value.value);
|
|
128
|
+
};
|
|
129
|
+
const stringify = (value: unknown): string => {
|
|
130
|
+
try {
|
|
131
|
+
return JSON.stringify(value) ?? String(value);
|
|
132
|
+
} catch {
|
|
133
|
+
return String(value);
|
|
134
|
+
}
|
|
135
|
+
};
|
|
136
|
+
/**
|
|
137
|
+
* Hash a string with two FNV-1a style passes under different constants.
|
|
138
|
+
*
|
|
139
|
+
* Kept dependency-free on purpose: the package is consumed from browser
|
|
140
|
+
* bundles, so `node:crypto` is not available.
|
|
141
|
+
*
|
|
142
|
+
* @param value The canonical description to hash.
|
|
143
|
+
* @returns A 16-character hexadecimal digest.
|
|
144
|
+
*/
|
|
145
|
+
const hash = (value: string): string => {
|
|
146
|
+
let low = 0x811c9dc5;
|
|
147
|
+
let high = 0x01000193;
|
|
148
|
+
|
|
149
|
+
for (let index = 0; index < value.length; index += 1) {
|
|
150
|
+
const code = value.charCodeAt(index);
|
|
151
|
+
|
|
152
|
+
low ^= code;
|
|
153
|
+
low = Math.imul(low, 0x01000193) >>> 0;
|
|
154
|
+
high ^= code + index;
|
|
155
|
+
high = Math.imul(high, 0x85ebca6b) >>> 0;
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
return `${low.toString(16).padStart(8, '0')}${high.toString(16).padStart(8, '0')}`;
|
|
159
|
+
};
|