@hexabot-ai/agentic 3.4.0 → 3.5.0-beta.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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
|
@@ -33,15 +33,10 @@ export const awaitReply = defineAction<
|
|
|
33
33
|
inputSchema,
|
|
34
34
|
outputSchema,
|
|
35
35
|
execute: async ({ context }) => {
|
|
36
|
-
|
|
36
|
+
return context.workflow.suspend({
|
|
37
37
|
reason: 'awaiting_user_response',
|
|
38
38
|
data: { hint: 'Provide phone number' },
|
|
39
|
+
accepts: resumeSchema,
|
|
39
40
|
});
|
|
40
|
-
const parsed = resumeSchema.safeParse(resumeData);
|
|
41
|
-
if (!parsed.success) {
|
|
42
|
-
throw new Error('resumeData must include a string `text` field.');
|
|
43
|
-
}
|
|
44
|
-
|
|
45
|
-
return parsed.data;
|
|
46
41
|
},
|
|
47
42
|
});
|
|
@@ -23,8 +23,10 @@ async function main() {
|
|
|
23
23
|
const context = new LoopExampleContext({ channel: 'chat' }, emitter);
|
|
24
24
|
|
|
25
25
|
emitter.on('hook:workflow:start', () => context.log('workflow started'));
|
|
26
|
-
emitter.on('hook:workflow:suspended', ({
|
|
27
|
-
|
|
26
|
+
emitter.on('hook:workflow:suspended', ({ waits }) =>
|
|
27
|
+
waits.forEach(({ step, reason }) =>
|
|
28
|
+
context.log(`workflow suspended at "${step.name}"`, { reason }),
|
|
29
|
+
),
|
|
28
30
|
);
|
|
29
31
|
emitter.on('hook:workflow:finish', ({ output }) =>
|
|
30
32
|
context.log('workflow finished', output),
|
|
@@ -33,19 +33,21 @@ export const waitForUser = defineAction<
|
|
|
33
33
|
inputSchema,
|
|
34
34
|
outputSchema,
|
|
35
35
|
execute: async ({ input, context }) => {
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
36
|
+
// A resumed body runs again from the top; skip work that already happened.
|
|
37
|
+
if (!context.workflow.hasRecordedResult()) {
|
|
38
|
+
context.log('Suspending workflow until we get a reply', {
|
|
39
|
+
prompt: input.prompt,
|
|
40
|
+
});
|
|
41
|
+
}
|
|
39
42
|
|
|
40
|
-
|
|
43
|
+
// A payload that does not match `accepts` is refused and the wait stays
|
|
44
|
+
// open, instead of failing the run.
|
|
45
|
+
const { reply } = await context.workflow.suspend({
|
|
41
46
|
reason: 'awaiting_user',
|
|
42
47
|
data: { prompt: input.prompt },
|
|
48
|
+
accepts: resumeSchema,
|
|
43
49
|
});
|
|
44
|
-
const parsed = resumeSchema.safeParse(resumeData);
|
|
45
|
-
if (!parsed.success) {
|
|
46
|
-
throw new Error('resumeData must include a string reply');
|
|
47
|
-
}
|
|
48
50
|
|
|
49
|
-
return { reply
|
|
51
|
+
return { reply };
|
|
50
52
|
},
|
|
51
53
|
});
|
|
@@ -23,14 +23,17 @@ async function main() {
|
|
|
23
23
|
const context = new SuspendResumeContext({ channel: 'chat' }, emitter);
|
|
24
24
|
|
|
25
25
|
emitter.on('hook:workflow:start', () => context.log('workflow started'));
|
|
26
|
-
emitter.on('hook:workflow:suspended', ({
|
|
27
|
-
|
|
26
|
+
emitter.on('hook:workflow:suspended', ({ waits }) =>
|
|
27
|
+
waits.forEach(({ step, reason, data }) =>
|
|
28
|
+
context.log(`workflow suspended at "${step.name}"`, { reason, data }),
|
|
29
|
+
),
|
|
28
30
|
);
|
|
29
31
|
emitter.on('hook:workflow:finish', ({ output }) =>
|
|
30
32
|
context.log('workflow finished', output),
|
|
31
33
|
);
|
|
32
34
|
|
|
33
35
|
const runner = await workflow.buildAsyncRunner();
|
|
36
|
+
// The run below suspends; the `runner` instance is dropped after that.
|
|
34
37
|
const startResult = await runner.start({
|
|
35
38
|
inputData: {
|
|
36
39
|
question: "Can we deploy to production after today's smoke tests?",
|
|
@@ -50,24 +53,61 @@ async function main() {
|
|
|
50
53
|
return;
|
|
51
54
|
}
|
|
52
55
|
|
|
53
|
-
|
|
56
|
+
// Persist the checkpoint and snapshot; they are plain JSON.
|
|
57
|
+
const stored = JSON.stringify({
|
|
58
|
+
checkpoint: startResult.checkpoint,
|
|
59
|
+
snapshot: startResult.snapshot,
|
|
60
|
+
});
|
|
61
|
+
const [wait] = startResult.waits;
|
|
62
|
+
context.log('persisted checkpoint; waiting on', {
|
|
63
|
+
waitId: wait.waitId,
|
|
64
|
+
reason: wait.reason,
|
|
65
|
+
});
|
|
54
66
|
|
|
55
|
-
|
|
56
|
-
|
|
67
|
+
// Later, possibly in another process: check the checkpoint still fits this
|
|
68
|
+
// workflow and the wait accepts the payload, then restore a fresh runner
|
|
69
|
+
// and resolve the wait.
|
|
70
|
+
const { checkpoint, snapshot } = JSON.parse(stored);
|
|
71
|
+
const resumeData = { reply: 'Yes, proceed once monitoring is green.' };
|
|
72
|
+
const validation = workflow.validateCheckpoint(checkpoint, {
|
|
73
|
+
waitId: wait.waitId,
|
|
74
|
+
resumeData,
|
|
75
|
+
});
|
|
76
|
+
if (!validation.ok) {
|
|
77
|
+
console.error('Cannot resume this run', validation.error);
|
|
78
|
+
|
|
79
|
+
return;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
const restoredContext = new SuspendResumeContext(
|
|
83
|
+
{ channel: 'chat' },
|
|
84
|
+
emitter,
|
|
85
|
+
);
|
|
86
|
+
const restored = workflow.buildRunnerFromCheckpoint({
|
|
87
|
+
checkpoint,
|
|
88
|
+
snapshot,
|
|
89
|
+
context: restoredContext,
|
|
90
|
+
});
|
|
91
|
+
const resumeResult = await restored.resume({
|
|
92
|
+
waitId: wait.waitId,
|
|
93
|
+
resumeData,
|
|
57
94
|
});
|
|
58
95
|
|
|
59
96
|
if (resumeResult.status === 'finished') {
|
|
60
|
-
|
|
97
|
+
restoredContext.log('resumed and completed', resumeResult.output);
|
|
61
98
|
|
|
62
99
|
return;
|
|
63
100
|
}
|
|
64
101
|
|
|
65
102
|
if (resumeResult.status === 'suspended') {
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
103
|
+
// A refused payload leaves the run as it was: the wait is still open.
|
|
104
|
+
if (resumeResult.rejection) {
|
|
105
|
+
restoredContext.log('payload refused', resumeResult.rejection.error);
|
|
106
|
+
|
|
107
|
+
return;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
restoredContext.log('suspended again', resumeResult.waits);
|
|
71
111
|
|
|
72
112
|
return;
|
|
73
113
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hexabot-ai/agentic",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.5.0-beta.0",
|
|
4
4
|
"description": "Schemas and utilities for the Hexabot agentic workflow DSL.",
|
|
5
5
|
"main": "dist/cjs/index.js",
|
|
6
6
|
"module": "dist/esm/index.js",
|
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
"dependencies": {
|
|
22
22
|
"jsonata": "^2.2.0",
|
|
23
23
|
"yaml": "^2.8.3",
|
|
24
|
-
"zod": "^4.
|
|
24
|
+
"zod": "^4.6.7"
|
|
25
25
|
},
|
|
26
26
|
"devDependencies": {
|
|
27
27
|
"@typescript-eslint/eslint-plugin": "^8.46.0",
|
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
"*.{ts}": "eslint --fix --config eslint.config-staged.cjs"
|
|
44
44
|
},
|
|
45
45
|
"engines": {
|
|
46
|
-
"node": ">=24.
|
|
46
|
+
"node": ">=24.22.1"
|
|
47
47
|
},
|
|
48
48
|
"license": "FCL-1.0-ALv2",
|
|
49
49
|
"scripts": {
|