@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.
Files changed (134) hide show
  1. package/README.md +67 -15
  2. package/dist/cjs/action/abstract-action.js +13 -1
  3. package/dist/cjs/checkpoint.js +301 -0
  4. package/dist/cjs/context.js +11 -27
  5. package/dist/cjs/dsl.types.js +3 -0
  6. package/dist/cjs/errors.js +116 -9
  7. package/dist/cjs/index.js +15 -6
  8. package/dist/cjs/resume-payload.js +257 -0
  9. package/dist/cjs/runner-runtime-control.js +181 -306
  10. package/dist/cjs/step-executors/conditional-executor.js +27 -29
  11. package/dist/cjs/step-executors/loop-executor.js +53 -62
  12. package/dist/cjs/step-executors/parallel-executor.js +169 -102
  13. package/dist/cjs/step-executors/task-executor.js +180 -96
  14. package/dist/cjs/utils/clone.js +73 -0
  15. package/dist/cjs/workflow-fingerprint.js +138 -0
  16. package/dist/cjs/workflow-runner.js +220 -155
  17. package/dist/cjs/workflow.js +24 -12
  18. package/dist/esm/action/abstract-action.js +14 -2
  19. package/dist/esm/checkpoint.js +293 -0
  20. package/dist/esm/context.js +11 -27
  21. package/dist/esm/dsl.types.js +3 -0
  22. package/dist/esm/errors.js +105 -6
  23. package/dist/esm/index.js +3 -3
  24. package/dist/esm/resume-payload.js +250 -0
  25. package/dist/esm/runner-runtime-control.js +179 -303
  26. package/dist/esm/step-executors/conditional-executor.js +27 -29
  27. package/dist/esm/step-executors/loop-executor.js +53 -62
  28. package/dist/esm/step-executors/parallel-executor.js +165 -98
  29. package/dist/esm/step-executors/task-executor.js +181 -97
  30. package/dist/esm/utils/clone.js +67 -0
  31. package/dist/esm/workflow-fingerprint.js +134 -0
  32. package/dist/esm/workflow-runner.js +220 -155
  33. package/dist/esm/workflow.js +24 -12
  34. package/dist/types/action/abstract-action.d.ts.map +1 -1
  35. package/dist/types/action/action.types.d.ts +0 -14
  36. package/dist/types/action/action.types.d.ts.map +1 -1
  37. package/dist/types/checkpoint.d.ts +188 -0
  38. package/dist/types/checkpoint.d.ts.map +1 -0
  39. package/dist/types/context.d.ts +45 -11
  40. package/dist/types/context.d.ts.map +1 -1
  41. package/dist/types/dsl.types.d.ts.map +1 -1
  42. package/dist/types/errors.d.ts +77 -3
  43. package/dist/types/errors.d.ts.map +1 -1
  44. package/dist/types/index.d.ts +6 -7
  45. package/dist/types/index.d.ts.map +1 -1
  46. package/dist/types/resume-payload.d.ts +69 -0
  47. package/dist/types/resume-payload.d.ts.map +1 -0
  48. package/dist/types/runner-runtime-control.d.ts +63 -51
  49. package/dist/types/runner-runtime-control.d.ts.map +1 -1
  50. package/dist/types/step-executors/conditional-executor.d.ts +6 -3
  51. package/dist/types/step-executors/conditional-executor.d.ts.map +1 -1
  52. package/dist/types/step-executors/loop-executor.d.ts +6 -4
  53. package/dist/types/step-executors/loop-executor.d.ts.map +1 -1
  54. package/dist/types/step-executors/parallel-executor.d.ts +11 -3
  55. package/dist/types/step-executors/parallel-executor.d.ts.map +1 -1
  56. package/dist/types/step-executors/task-executor.d.ts +11 -4
  57. package/dist/types/step-executors/task-executor.d.ts.map +1 -1
  58. package/dist/types/step-executors/types.d.ts +21 -13
  59. package/dist/types/step-executors/types.d.ts.map +1 -1
  60. package/dist/types/utils/clone.d.ts +33 -0
  61. package/dist/types/utils/clone.d.ts.map +1 -0
  62. package/dist/types/workflow-event-emitter.d.ts +29 -5
  63. package/dist/types/workflow-event-emitter.d.ts.map +1 -1
  64. package/dist/types/workflow-fingerprint.d.ts +14 -0
  65. package/dist/types/workflow-fingerprint.d.ts.map +1 -0
  66. package/dist/types/workflow-runner.d.ts +83 -41
  67. package/dist/types/workflow-runner.d.ts.map +1 -1
  68. package/dist/types/workflow-types.d.ts +25 -54
  69. package/dist/types/workflow-types.d.ts.map +1 -1
  70. package/dist/types/workflow.d.ts +24 -9
  71. package/dist/types/workflow.d.ts.map +1 -1
  72. package/examples/defs-bindings-agent/bindings.ts +1 -1
  73. package/examples/defs-bindings-agent/workflow.ts +3 -2
  74. package/examples/full/actions/await-user-input.ts +3 -2
  75. package/examples/full/actions/call-llm.ts +18 -18
  76. package/examples/full/actions/create-ticket.ts +1 -2
  77. package/examples/full/actions/decision-router.ts +6 -2
  78. package/examples/full/actions/get-calendar-events.ts +1 -2
  79. package/examples/full/actions/get-user-profile.ts +1 -2
  80. package/examples/full/actions/query-memory.ts +1 -2
  81. package/examples/full/actions/search-web.ts +1 -2
  82. package/examples/full/actions/send-email.ts +3 -2
  83. package/examples/full/workflow.ts +3 -2
  84. package/examples/loop/actions/await-reply.ts +2 -7
  85. package/examples/loop/workflow.ts +4 -2
  86. package/examples/suspend-resume/actions/wait-for-user.ts +11 -9
  87. package/examples/suspend-resume/workflow.ts +51 -11
  88. package/package.json +3 -3
  89. package/src/__tests__/checkpoint.test.ts +2568 -0
  90. package/src/__tests__/resume-payload.test.ts +245 -0
  91. package/src/__tests__/runner-runtime-control.test.ts +265 -0
  92. package/src/__tests__/workflow-fingerprint.test.ts +165 -0
  93. package/src/__tests__/workflow-runner.test.ts +167 -144
  94. package/src/__tests__/workflow.test.ts +97 -6
  95. package/src/action/abstract-action.ts +21 -2
  96. package/src/action/action.types.ts +0 -12
  97. package/src/checkpoint.ts +561 -0
  98. package/src/context.ts +51 -41
  99. package/src/dsl.types.ts +3 -0
  100. package/src/errors.ts +161 -8
  101. package/src/index.ts +33 -14
  102. package/src/resume-payload.ts +326 -0
  103. package/src/runner-runtime-control.ts +222 -456
  104. package/src/step-executors/conditional-executor.test.ts +77 -46
  105. package/src/step-executors/conditional-executor.ts +47 -40
  106. package/src/step-executors/loop-executor.test.ts +106 -92
  107. package/src/step-executors/loop-executor.ts +84 -101
  108. package/src/step-executors/parallel-executor.test.ts +300 -89
  109. package/src/step-executors/parallel-executor.ts +243 -125
  110. package/src/step-executors/task-executor.test.ts +321 -51
  111. package/src/step-executors/task-executor.ts +232 -145
  112. package/src/step-executors/types.ts +23 -22
  113. package/src/utils/clone.ts +75 -0
  114. package/src/workflow-event-emitter.ts +32 -6
  115. package/src/workflow-fingerprint.ts +159 -0
  116. package/src/workflow-runner.ts +325 -209
  117. package/src/workflow-types.ts +25 -56
  118. package/src/workflow.ts +41 -34
  119. package/dist/cjs/step-executors/suspension-continuation.js +0 -27
  120. package/dist/cjs/suspension-rebuilder.js +0 -265
  121. package/dist/cjs/utils/deferred.js +0 -17
  122. package/dist/esm/step-executors/suspension-continuation.js +0 -24
  123. package/dist/esm/suspension-rebuilder.js +0 -260
  124. package/dist/esm/utils/deferred.js +0 -14
  125. package/dist/types/step-executors/suspension-continuation.d.ts +0 -10
  126. package/dist/types/step-executors/suspension-continuation.d.ts.map +0 -1
  127. package/dist/types/suspension-rebuilder.d.ts +0 -67
  128. package/dist/types/suspension-rebuilder.d.ts.map +0 -1
  129. package/dist/types/utils/deferred.d.ts +0 -7
  130. package/dist/types/utils/deferred.d.ts.map +0 -1
  131. package/src/__tests__/suspension-rebuilder.test.ts +0 -404
  132. package/src/step-executors/suspension-continuation.ts +0 -31
  133. package/src/suspension-rebuilder.ts +0 -446
  134. package/src/utils/deferred.ts +0 -23
@@ -0,0 +1,326 @@
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 { z, type ZodType } from 'zod';
8
+
9
+ import type { WaitInfo } from './checkpoint';
10
+ import { WorkflowResumeRejectedError } from './errors';
11
+ import { cloneAsJson } from './utils/clone';
12
+
13
+ type JsonSchema = Record<string, unknown>;
14
+
15
+ type ZodNode = { _zod: { def: ZodDefLike; optin?: 'optional' | 'defaulted' } };
16
+
17
+ // The parts of a Zod 4 schema definition these helpers read.
18
+ type ZodDefLike = {
19
+ type: string;
20
+ coerce?: boolean;
21
+ in?: ZodNode;
22
+ checks?: Array<{ _zod: { def: { check: string } } }>;
23
+ innerType?: ZodNode;
24
+ shape?: Record<string, ZodNode>;
25
+ element?: ZodNode;
26
+ items?: ZodNode[];
27
+ rest?: ZodNode | null;
28
+ options?: ZodNode[];
29
+ left?: ZodNode;
30
+ right?: ZodNode;
31
+ valueType?: ZodNode;
32
+ getter?: () => ZodNode;
33
+ };
34
+
35
+ /** Result of checking a resume payload against the wait it resolves. */
36
+ export type ResumePayloadCheck =
37
+ | { ok: true; value: unknown }
38
+ | { ok: false; error: WorkflowResumeRejectedError };
39
+
40
+ // Keywords that `z.fromJSONSchema` turns back into the same check. Others,
41
+ // such as `pattern` (regex flags are lost), `format` or `propertyNames` (an
42
+ // enum of keys becomes exhaustive), can come back stricter than the schema
43
+ // they were generated from, so they are dropped.
44
+ const KEPT_KEYWORDS = new Set([
45
+ '$schema',
46
+ '$ref',
47
+ '$defs',
48
+ 'title',
49
+ 'description',
50
+ 'type',
51
+ 'properties',
52
+ 'required',
53
+ 'additionalProperties',
54
+ 'items',
55
+ 'prefixItems',
56
+ 'anyOf',
57
+ 'allOf',
58
+ 'enum',
59
+ 'const',
60
+ 'minLength',
61
+ 'maxLength',
62
+ 'minimum',
63
+ 'maximum',
64
+ 'exclusiveMinimum',
65
+ 'exclusiveMaximum',
66
+ 'minItems',
67
+ 'maxItems',
68
+ ]);
69
+ // Bounds a rewrite such as `.trim()` applies to the rewritten value.
70
+ const BOUND_KEYWORDS = [
71
+ 'minLength',
72
+ 'maxLength',
73
+ 'minimum',
74
+ 'maximum',
75
+ 'exclusiveMinimum',
76
+ 'exclusiveMaximum',
77
+ 'minItems',
78
+ 'maxItems',
79
+ ];
80
+ // Types JSON has no value for: a payload read back from the checkpoint can
81
+ // never match them unless they coerce.
82
+ const NON_JSON_TYPES = new Set([
83
+ 'date',
84
+ 'bigint',
85
+ 'symbol',
86
+ 'map',
87
+ 'set',
88
+ 'nan',
89
+ 'function',
90
+ 'file',
91
+ ]);
92
+ // Wrappers whose input is their inner schema's input.
93
+ const WRAPPER_TYPES = new Set([
94
+ 'optional',
95
+ 'nullable',
96
+ 'nonoptional',
97
+ 'readonly',
98
+ 'default',
99
+ 'prefault',
100
+ 'promise',
101
+ ]);
102
+
103
+ /**
104
+ * Describe the payload a `suspend()` call accepts as a JSON Schema that can
105
+ * be stored on its wait.
106
+ *
107
+ * JSON Schema cannot express everything a Zod schema checks, so the result is
108
+ * relaxed until it never refuses a JSON payload the Zod schema accepts:
109
+ * coerced, preprocessed and `catch` nodes accept anything, and keywords that
110
+ * do not round-trip exactly are dropped. The Zod schema stays authoritative
111
+ * when the action body reads the payload.
112
+ *
113
+ * @param schema The `accepts` schema passed to `suspend()`.
114
+ * @returns The relaxed JSON Schema, or undefined when it cannot be generated.
115
+ */
116
+ export function describeResumePayload(schema: ZodType): JsonSchema | undefined {
117
+ try {
118
+ return z.toJSONSchema(schema, {
119
+ io: 'input',
120
+ unrepresentable: 'any',
121
+ override: ({ zodSchema, jsonSchema }) =>
122
+ relaxNode(
123
+ (zodSchema as unknown as { _zod: { def: ZodDefLike } })._zod.def,
124
+ jsonSchema as JsonSchema,
125
+ ),
126
+ }) as JsonSchema;
127
+ } catch {
128
+ return undefined;
129
+ }
130
+ }
131
+
132
+ /**
133
+ * Report whether an `accepts` schema also accepts a resume without payload.
134
+ * Its JSON Schema cannot say so, since JSON has no `undefined`.
135
+ *
136
+ * @param schema The `accepts` schema passed to `suspend()`.
137
+ * @returns True when the schema accepts `undefined`, e.g. when it is optional.
138
+ */
139
+ export function isPayloadOptional(schema: ZodType): boolean {
140
+ const { optin, def } = (schema as unknown as ZodNode)._zod;
141
+
142
+ // Zod marks `.default()` as "defaulted" and gives `z.undefined()` and
143
+ // `z.void()` no optin, though both accept a missing payload.
144
+ return (
145
+ optin === 'optional' ||
146
+ optin === 'defaulted' ||
147
+ def.type === 'undefined' ||
148
+ def.type === 'void'
149
+ );
150
+ }
151
+
152
+ /**
153
+ * List the parts of an `accepts` schema that no JSON payload can match.
154
+ *
155
+ * Payloads are read back from the checkpoint as JSON, so a type JSON cannot
156
+ * carry, such as `z.date()`, refuses every payload: a `Date` resumes as its
157
+ * ISO string. Parts that coerce, preprocess or catch their input are fine.
158
+ *
159
+ * @param schema The `accepts` schema passed to `suspend()`.
160
+ * @returns One `<path> (<type>)` entry per offending part, in schema order.
161
+ */
162
+ export function findNonJsonTypes(schema: ZodType): string[] {
163
+ const found: string[] = [];
164
+ const seen = new Set<ZodNode>();
165
+ const visit = (node: ZodNode | null | undefined, path: string): void => {
166
+ // Shared and recursive schemas are visited once.
167
+ if (!node || seen.has(node)) {
168
+ return;
169
+ }
170
+
171
+ seen.add(node);
172
+ const def = node._zod.def;
173
+ if (acceptsBeyondItsType(def)) {
174
+ return;
175
+ }
176
+
177
+ if (NON_JSON_TYPES.has(def.type)) {
178
+ found.push(`${path || '(root)'} (${def.type})`);
179
+
180
+ return;
181
+ }
182
+
183
+ if (WRAPPER_TYPES.has(def.type)) {
184
+ return visit(def.innerType, path);
185
+ }
186
+
187
+ switch (def.type) {
188
+ case 'object':
189
+ return Object.entries(def.shape ?? {}).forEach(([key, child]) =>
190
+ visit(child, path ? `${path}.${key}` : key),
191
+ );
192
+ case 'record':
193
+ return visit(def.valueType, `${path}.*`);
194
+ case 'array':
195
+ return visit(def.element, `${path}[]`);
196
+ case 'tuple':
197
+ def.items?.forEach((item, index) => visit(item, `${path}[${index}]`));
198
+
199
+ return visit(def.rest, `${path}[]`);
200
+ case 'union':
201
+ return def.options?.forEach((option) => visit(option, path));
202
+ case 'intersection':
203
+ visit(def.left, path);
204
+
205
+ return visit(def.right, path);
206
+ case 'pipe':
207
+ // The payload is the input of the pipe, e.g. the string of a codec.
208
+ return visit(def.in, path);
209
+ case 'lazy':
210
+ return visit(def.getter?.(), path);
211
+ }
212
+ };
213
+
214
+ visit(schema as unknown as ZodNode, '');
215
+
216
+ return found;
217
+ }
218
+
219
+ /**
220
+ * Check a resume payload against the wait it resolves, without running
221
+ * anything.
222
+ *
223
+ * The payload is first normalized the way the checkpoint stores it, so the
224
+ * check sees what the action body will read. A resume without payload stays
225
+ * `undefined`, which a wait with `accepts` takes only when its payload is
226
+ * optional.
227
+ *
228
+ * @param wait The wait the payload resolves.
229
+ * @param resumeData The payload, as passed to `resume()`.
230
+ * @returns The normalized payload, or why it is refused.
231
+ */
232
+ export function checkResumePayload(
233
+ wait: WaitInfo,
234
+ resumeData: unknown,
235
+ ): ResumePayloadCheck {
236
+ let value: unknown;
237
+ try {
238
+ value = resumeData === undefined ? undefined : cloneAsJson(resumeData);
239
+ } catch (error) {
240
+ const reason = error instanceof Error ? error.message : String(error);
241
+
242
+ return {
243
+ ok: false,
244
+ error: new WorkflowResumeRejectedError(
245
+ `Resume payload for wait "${wait.waitId}" cannot be stored as JSON (${reason}).`,
246
+ ),
247
+ };
248
+ }
249
+
250
+ if (!wait.accepts || (value === undefined && wait.payloadOptional)) {
251
+ return { ok: true, value };
252
+ }
253
+
254
+ let schema: ZodType;
255
+ try {
256
+ schema = z.fromJSONSchema(wait.accepts);
257
+ } catch {
258
+ // Unreadable here; the action's own schema still checks the payload.
259
+ return { ok: true, value };
260
+ }
261
+
262
+ const result = schema.safeParse(value);
263
+ if (result.success) {
264
+ return { ok: true, value };
265
+ }
266
+
267
+ return {
268
+ ok: false,
269
+ error: rejectResumePayload(`wait "${wait.waitId}"`, result.error.issues),
270
+ };
271
+ }
272
+
273
+ /**
274
+ * Build the error refusing a payload that failed a schema.
275
+ *
276
+ * @param subject What the payload was meant for, used in the message.
277
+ * @param issues The schema issues.
278
+ * @returns The rejection error.
279
+ */
280
+ export function rejectResumePayload(
281
+ subject: string,
282
+ issues: z.core.$ZodIssue[],
283
+ ): WorkflowResumeRejectedError {
284
+ const messages = issues.map(
285
+ (issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`,
286
+ );
287
+
288
+ return new WorkflowResumeRejectedError(
289
+ `Resume payload for ${subject} was rejected: ${messages.join('; ')}`,
290
+ { issues: messages },
291
+ );
292
+ }
293
+
294
+ const relaxNode = (def: ZodDefLike, jsonSchema: JsonSchema): void => {
295
+ if (acceptsBeyondItsType(def)) {
296
+ for (const keyword of Object.keys(jsonSchema)) {
297
+ delete jsonSchema[keyword];
298
+ }
299
+
300
+ return;
301
+ }
302
+
303
+ // `oneOf` refuses a payload matching several options; `anyOf` does not.
304
+ if ('oneOf' in jsonSchema) {
305
+ jsonSchema.anyOf = jsonSchema.oneOf;
306
+ delete jsonSchema.oneOf;
307
+ }
308
+
309
+ for (const keyword of Object.keys(jsonSchema)) {
310
+ if (!KEPT_KEYWORDS.has(keyword)) {
311
+ delete jsonSchema[keyword];
312
+ }
313
+ }
314
+
315
+ if (def.checks?.some((check) => check._zod.def.check === 'overwrite')) {
316
+ for (const keyword of BOUND_KEYWORDS) {
317
+ delete jsonSchema[keyword];
318
+ }
319
+ }
320
+ };
321
+ /** Nodes that accept inputs their JSON Schema type would refuse. */
322
+ const acceptsBeyondItsType = (def: ZodDefLike): boolean =>
323
+ def.coerce === true ||
324
+ def.type === 'catch' ||
325
+ def.type === 'custom' ||
326
+ (def.type === 'pipe' && def.in?._zod.def.type === 'transform');