@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
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Hexabot — Fair Core License (FCL-1.0-ALv2)
|
|
3
|
+
* Copyright (c) 2025 Hexastack.
|
|
4
|
+
* Full terms: see LICENSE.md.
|
|
5
|
+
*/
|
|
6
|
+
import { z } from 'zod';
|
|
7
|
+
import { WorkflowResumeRejectedError } from './errors';
|
|
8
|
+
import { cloneAsJson } from './utils/clone';
|
|
9
|
+
// Keywords that `z.fromJSONSchema` turns back into the same check. Others,
|
|
10
|
+
// such as `pattern` (regex flags are lost), `format` or `propertyNames` (an
|
|
11
|
+
// enum of keys becomes exhaustive), can come back stricter than the schema
|
|
12
|
+
// they were generated from, so they are dropped.
|
|
13
|
+
const KEPT_KEYWORDS = new Set([
|
|
14
|
+
'$schema',
|
|
15
|
+
'$ref',
|
|
16
|
+
'$defs',
|
|
17
|
+
'title',
|
|
18
|
+
'description',
|
|
19
|
+
'type',
|
|
20
|
+
'properties',
|
|
21
|
+
'required',
|
|
22
|
+
'additionalProperties',
|
|
23
|
+
'items',
|
|
24
|
+
'prefixItems',
|
|
25
|
+
'anyOf',
|
|
26
|
+
'allOf',
|
|
27
|
+
'enum',
|
|
28
|
+
'const',
|
|
29
|
+
'minLength',
|
|
30
|
+
'maxLength',
|
|
31
|
+
'minimum',
|
|
32
|
+
'maximum',
|
|
33
|
+
'exclusiveMinimum',
|
|
34
|
+
'exclusiveMaximum',
|
|
35
|
+
'minItems',
|
|
36
|
+
'maxItems',
|
|
37
|
+
]);
|
|
38
|
+
// Bounds a rewrite such as `.trim()` applies to the rewritten value.
|
|
39
|
+
const BOUND_KEYWORDS = [
|
|
40
|
+
'minLength',
|
|
41
|
+
'maxLength',
|
|
42
|
+
'minimum',
|
|
43
|
+
'maximum',
|
|
44
|
+
'exclusiveMinimum',
|
|
45
|
+
'exclusiveMaximum',
|
|
46
|
+
'minItems',
|
|
47
|
+
'maxItems',
|
|
48
|
+
];
|
|
49
|
+
// Types JSON has no value for: a payload read back from the checkpoint can
|
|
50
|
+
// never match them unless they coerce.
|
|
51
|
+
const NON_JSON_TYPES = new Set([
|
|
52
|
+
'date',
|
|
53
|
+
'bigint',
|
|
54
|
+
'symbol',
|
|
55
|
+
'map',
|
|
56
|
+
'set',
|
|
57
|
+
'nan',
|
|
58
|
+
'function',
|
|
59
|
+
'file',
|
|
60
|
+
]);
|
|
61
|
+
// Wrappers whose input is their inner schema's input.
|
|
62
|
+
const WRAPPER_TYPES = new Set([
|
|
63
|
+
'optional',
|
|
64
|
+
'nullable',
|
|
65
|
+
'nonoptional',
|
|
66
|
+
'readonly',
|
|
67
|
+
'default',
|
|
68
|
+
'prefault',
|
|
69
|
+
'promise',
|
|
70
|
+
]);
|
|
71
|
+
/**
|
|
72
|
+
* Describe the payload a `suspend()` call accepts as a JSON Schema that can
|
|
73
|
+
* be stored on its wait.
|
|
74
|
+
*
|
|
75
|
+
* JSON Schema cannot express everything a Zod schema checks, so the result is
|
|
76
|
+
* relaxed until it never refuses a JSON payload the Zod schema accepts:
|
|
77
|
+
* coerced, preprocessed and `catch` nodes accept anything, and keywords that
|
|
78
|
+
* do not round-trip exactly are dropped. The Zod schema stays authoritative
|
|
79
|
+
* when the action body reads the payload.
|
|
80
|
+
*
|
|
81
|
+
* @param schema The `accepts` schema passed to `suspend()`.
|
|
82
|
+
* @returns The relaxed JSON Schema, or undefined when it cannot be generated.
|
|
83
|
+
*/
|
|
84
|
+
export function describeResumePayload(schema) {
|
|
85
|
+
try {
|
|
86
|
+
return z.toJSONSchema(schema, {
|
|
87
|
+
io: 'input',
|
|
88
|
+
unrepresentable: 'any',
|
|
89
|
+
override: ({ zodSchema, jsonSchema }) => relaxNode(zodSchema._zod.def, jsonSchema),
|
|
90
|
+
});
|
|
91
|
+
}
|
|
92
|
+
catch {
|
|
93
|
+
return undefined;
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Report whether an `accepts` schema also accepts a resume without payload.
|
|
98
|
+
* Its JSON Schema cannot say so, since JSON has no `undefined`.
|
|
99
|
+
*
|
|
100
|
+
* @param schema The `accepts` schema passed to `suspend()`.
|
|
101
|
+
* @returns True when the schema accepts `undefined`, e.g. when it is optional.
|
|
102
|
+
*/
|
|
103
|
+
export function isPayloadOptional(schema) {
|
|
104
|
+
const { optin, def } = schema._zod;
|
|
105
|
+
// Zod marks `.default()` as "defaulted" and gives `z.undefined()` and
|
|
106
|
+
// `z.void()` no optin, though both accept a missing payload.
|
|
107
|
+
return (optin === 'optional' ||
|
|
108
|
+
optin === 'defaulted' ||
|
|
109
|
+
def.type === 'undefined' ||
|
|
110
|
+
def.type === 'void');
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* List the parts of an `accepts` schema that no JSON payload can match.
|
|
114
|
+
*
|
|
115
|
+
* Payloads are read back from the checkpoint as JSON, so a type JSON cannot
|
|
116
|
+
* carry, such as `z.date()`, refuses every payload: a `Date` resumes as its
|
|
117
|
+
* ISO string. Parts that coerce, preprocess or catch their input are fine.
|
|
118
|
+
*
|
|
119
|
+
* @param schema The `accepts` schema passed to `suspend()`.
|
|
120
|
+
* @returns One `<path> (<type>)` entry per offending part, in schema order.
|
|
121
|
+
*/
|
|
122
|
+
export function findNonJsonTypes(schema) {
|
|
123
|
+
const found = [];
|
|
124
|
+
const seen = new Set();
|
|
125
|
+
const visit = (node, path) => {
|
|
126
|
+
// Shared and recursive schemas are visited once.
|
|
127
|
+
if (!node || seen.has(node)) {
|
|
128
|
+
return;
|
|
129
|
+
}
|
|
130
|
+
seen.add(node);
|
|
131
|
+
const def = node._zod.def;
|
|
132
|
+
if (acceptsBeyondItsType(def)) {
|
|
133
|
+
return;
|
|
134
|
+
}
|
|
135
|
+
if (NON_JSON_TYPES.has(def.type)) {
|
|
136
|
+
found.push(`${path || '(root)'} (${def.type})`);
|
|
137
|
+
return;
|
|
138
|
+
}
|
|
139
|
+
if (WRAPPER_TYPES.has(def.type)) {
|
|
140
|
+
return visit(def.innerType, path);
|
|
141
|
+
}
|
|
142
|
+
switch (def.type) {
|
|
143
|
+
case 'object':
|
|
144
|
+
return Object.entries(def.shape ?? {}).forEach(([key, child]) => visit(child, path ? `${path}.${key}` : key));
|
|
145
|
+
case 'record':
|
|
146
|
+
return visit(def.valueType, `${path}.*`);
|
|
147
|
+
case 'array':
|
|
148
|
+
return visit(def.element, `${path}[]`);
|
|
149
|
+
case 'tuple':
|
|
150
|
+
def.items?.forEach((item, index) => visit(item, `${path}[${index}]`));
|
|
151
|
+
return visit(def.rest, `${path}[]`);
|
|
152
|
+
case 'union':
|
|
153
|
+
return def.options?.forEach((option) => visit(option, path));
|
|
154
|
+
case 'intersection':
|
|
155
|
+
visit(def.left, path);
|
|
156
|
+
return visit(def.right, path);
|
|
157
|
+
case 'pipe':
|
|
158
|
+
// The payload is the input of the pipe, e.g. the string of a codec.
|
|
159
|
+
return visit(def.in, path);
|
|
160
|
+
case 'lazy':
|
|
161
|
+
return visit(def.getter?.(), path);
|
|
162
|
+
}
|
|
163
|
+
};
|
|
164
|
+
visit(schema, '');
|
|
165
|
+
return found;
|
|
166
|
+
}
|
|
167
|
+
/**
|
|
168
|
+
* Check a resume payload against the wait it resolves, without running
|
|
169
|
+
* anything.
|
|
170
|
+
*
|
|
171
|
+
* The payload is first normalized the way the checkpoint stores it, so the
|
|
172
|
+
* check sees what the action body will read. A resume without payload stays
|
|
173
|
+
* `undefined`, which a wait with `accepts` takes only when its payload is
|
|
174
|
+
* optional.
|
|
175
|
+
*
|
|
176
|
+
* @param wait The wait the payload resolves.
|
|
177
|
+
* @param resumeData The payload, as passed to `resume()`.
|
|
178
|
+
* @returns The normalized payload, or why it is refused.
|
|
179
|
+
*/
|
|
180
|
+
export function checkResumePayload(wait, resumeData) {
|
|
181
|
+
let value;
|
|
182
|
+
try {
|
|
183
|
+
value = resumeData === undefined ? undefined : cloneAsJson(resumeData);
|
|
184
|
+
}
|
|
185
|
+
catch (error) {
|
|
186
|
+
const reason = error instanceof Error ? error.message : String(error);
|
|
187
|
+
return {
|
|
188
|
+
ok: false,
|
|
189
|
+
error: new WorkflowResumeRejectedError(`Resume payload for wait "${wait.waitId}" cannot be stored as JSON (${reason}).`),
|
|
190
|
+
};
|
|
191
|
+
}
|
|
192
|
+
if (!wait.accepts || (value === undefined && wait.payloadOptional)) {
|
|
193
|
+
return { ok: true, value };
|
|
194
|
+
}
|
|
195
|
+
let schema;
|
|
196
|
+
try {
|
|
197
|
+
schema = z.fromJSONSchema(wait.accepts);
|
|
198
|
+
}
|
|
199
|
+
catch {
|
|
200
|
+
// Unreadable here; the action's own schema still checks the payload.
|
|
201
|
+
return { ok: true, value };
|
|
202
|
+
}
|
|
203
|
+
const result = schema.safeParse(value);
|
|
204
|
+
if (result.success) {
|
|
205
|
+
return { ok: true, value };
|
|
206
|
+
}
|
|
207
|
+
return {
|
|
208
|
+
ok: false,
|
|
209
|
+
error: rejectResumePayload(`wait "${wait.waitId}"`, result.error.issues),
|
|
210
|
+
};
|
|
211
|
+
}
|
|
212
|
+
/**
|
|
213
|
+
* Build the error refusing a payload that failed a schema.
|
|
214
|
+
*
|
|
215
|
+
* @param subject What the payload was meant for, used in the message.
|
|
216
|
+
* @param issues The schema issues.
|
|
217
|
+
* @returns The rejection error.
|
|
218
|
+
*/
|
|
219
|
+
export function rejectResumePayload(subject, issues) {
|
|
220
|
+
const messages = issues.map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`);
|
|
221
|
+
return new WorkflowResumeRejectedError(`Resume payload for ${subject} was rejected: ${messages.join('; ')}`, { issues: messages });
|
|
222
|
+
}
|
|
223
|
+
const relaxNode = (def, jsonSchema) => {
|
|
224
|
+
if (acceptsBeyondItsType(def)) {
|
|
225
|
+
for (const keyword of Object.keys(jsonSchema)) {
|
|
226
|
+
delete jsonSchema[keyword];
|
|
227
|
+
}
|
|
228
|
+
return;
|
|
229
|
+
}
|
|
230
|
+
// `oneOf` refuses a payload matching several options; `anyOf` does not.
|
|
231
|
+
if ('oneOf' in jsonSchema) {
|
|
232
|
+
jsonSchema.anyOf = jsonSchema.oneOf;
|
|
233
|
+
delete jsonSchema.oneOf;
|
|
234
|
+
}
|
|
235
|
+
for (const keyword of Object.keys(jsonSchema)) {
|
|
236
|
+
if (!KEPT_KEYWORDS.has(keyword)) {
|
|
237
|
+
delete jsonSchema[keyword];
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
if (def.checks?.some((check) => check._zod.def.check === 'overwrite')) {
|
|
241
|
+
for (const keyword of BOUND_KEYWORDS) {
|
|
242
|
+
delete jsonSchema[keyword];
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
};
|
|
246
|
+
/** Nodes that accept inputs their JSON Schema type would refuse. */
|
|
247
|
+
const acceptsBeyondItsType = (def) => def.coerce === true ||
|
|
248
|
+
def.type === 'catch' ||
|
|
249
|
+
def.type === 'custom' ||
|
|
250
|
+
(def.type === 'pipe' && def.in?._zod.def.type === 'transform');
|