@hexabot-ai/agentic 3.4.0-beta.2 → 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
@@ -1,404 +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
- import { z } from 'zod';
8
-
9
- import type { Action } from '../action/action.types';
10
- import { BaseWorkflowContext } from '../context';
11
- import type {
12
- Settings,
13
- TaskDefinition,
14
- WorkflowDefinition,
15
- } from '../dsl.types';
16
- import {
17
- executeLoop as runLoopExecutor,
18
- shouldStopLoop,
19
- updateAccumulator,
20
- } from '../step-executors/loop-executor';
21
- import type { StepExecutorEnv } from '../step-executors/types';
22
- import {
23
- parseSuspendedStepId,
24
- rebuildSuspension,
25
- type SuspensionRebuilderDeps,
26
- } from '../suspension-rebuilder';
27
- import { type EventEmitterLike, StepType } from '../workflow-event-emitter';
28
- import type {
29
- CompiledStep,
30
- CompiledTask,
31
- CompiledWorkflow,
32
- ExecutionState,
33
- } from '../workflow-types';
34
-
35
- jest.mock('../step-executors/loop-executor', () => ({
36
- __esModule: true,
37
- executeLoop: jest.fn(),
38
- updateAccumulator: jest.fn(),
39
- shouldStopLoop: jest.fn(),
40
- }));
41
-
42
- const mockedRunLoopExecutor = runLoopExecutor as jest.MockedFunction<
43
- typeof runLoopExecutor
44
- >;
45
- const mockedUpdateAccumulator = updateAccumulator as jest.MockedFunction<
46
- typeof updateAccumulator
47
- >;
48
- const mockedShouldStopLoop = shouldStopLoop as jest.MockedFunction<
49
- typeof shouldStopLoop
50
- >;
51
-
52
- class TestContext extends BaseWorkflowContext {
53
- public eventEmitter: EventEmitterLike = { emit: jest.fn(), on: jest.fn() };
54
-
55
- constructor(initial: Record<string, unknown>) {
56
- super(initial);
57
- }
58
- }
59
-
60
- const dummyAction: Action<unknown, unknown, BaseWorkflowContext, Settings> = {
61
- name: 'dummy',
62
- description: 'dummy',
63
- inputSchema: z.any(),
64
- outputSchema: z.any(),
65
- execute: jest.fn(),
66
- parseInput: (value) => value as unknown,
67
- parseOutput: (value) => value as unknown,
68
- parseSettings: (value) => value as Settings,
69
- run: jest.fn(),
70
- };
71
- const buildStepInfo = (step: CompiledStep, iterationStack: number[]) => ({
72
- id: `${step.id}${
73
- iterationStack.length > 0 ? `[${iterationStack.join('.')}]` : ''
74
- }`,
75
- name: step.label,
76
- type: step.type,
77
- });
78
- const createCompiledWorkflow = (
79
- flow: CompiledStep[],
80
- tasks: Record<string, CompiledTask>,
81
- ): CompiledWorkflow =>
82
- ({
83
- definition: {} as WorkflowDefinition,
84
- tasks,
85
- flow,
86
- outputMapping: {},
87
- inputParser: { parse: (value: unknown) => value },
88
- }) as CompiledWorkflow;
89
- const createDeps = (
90
- compiled: CompiledWorkflow,
91
- overrides?: Partial<SuspensionRebuilderDeps>,
92
- ): SuspensionRebuilderDeps => {
93
- const context = overrides?.context ?? new TestContext({});
94
- const captureTaskOutput =
95
- overrides?.captureTaskOutput ?? jest.fn().mockResolvedValue(undefined);
96
- const markSnapshot =
97
- overrides?.markSnapshot ??
98
- (jest.fn() as SuspensionRebuilderDeps['markSnapshot']);
99
- const emit =
100
- overrides?.emit ?? (jest.fn() as SuspensionRebuilderDeps['emit']);
101
- const executeFlow =
102
- overrides?.executeFlow ??
103
- (jest
104
- .fn()
105
- .mockResolvedValue(undefined) as SuspensionRebuilderDeps['executeFlow']);
106
- const deps: SuspensionRebuilderDeps = {
107
- compiled,
108
- context,
109
- runId: overrides?.runId ?? 'run-123',
110
- createExecutorEnv:
111
- overrides?.createExecutorEnv ??
112
- jest.fn(
113
- () =>
114
- ({
115
- context,
116
- }) as unknown as StepExecutorEnv,
117
- ),
118
- buildInstanceStepInfo: overrides?.buildInstanceStepInfo ?? buildStepInfo,
119
- captureTaskOutput,
120
- markSnapshot,
121
- emit,
122
- executeFlow,
123
- };
124
-
125
- return deps;
126
- };
127
- const createTask = (name: string): CompiledTask =>
128
- ({
129
- name,
130
- definition: { action: name } as TaskDefinition,
131
- actionName: name,
132
- action: dummyAction,
133
- inputs: {},
134
- settings: {} as Settings,
135
- bindings: {},
136
- }) as CompiledTask;
137
-
138
- afterEach(() => {
139
- jest.clearAllMocks();
140
- });
141
-
142
- describe('parseSuspendedStepId', () => {
143
- it('extracts path and iteration stack from a nested id', () => {
144
- expect(parseSuspendedStepId('1.branch.0:conditional[2.4]')).toEqual({
145
- path: [1, 'branch', 0],
146
- iterationStack: [2, 4],
147
- });
148
- });
149
-
150
- it('returns empty path and iteration data for root ids', () => {
151
- expect(parseSuspendedStepId('root:task')).toEqual({
152
- path: [],
153
- iterationStack: [],
154
- });
155
- });
156
- });
157
-
158
- describe('rebuildSuspension', () => {
159
- it('returns null when no state is available', () => {
160
- const compiled = createCompiledWorkflow([], {});
161
- const deps = createDeps(compiled);
162
- const suspension = rebuildSuspension(deps, {
163
- state: undefined,
164
- stepId: '0:task',
165
- });
166
-
167
- expect(suspension).toBeNull();
168
- });
169
-
170
- it('rebuilds a task suspension and resumes the flow', async () => {
171
- const task = createTask('first_task');
172
- const taskStep: CompiledStep = {
173
- type: StepType.Task,
174
- id: '0:first_task',
175
- label: 'first_task',
176
- taskName: 'first_task',
177
- };
178
- const compiled = createCompiledWorkflow([taskStep], {
179
- first_task: task,
180
- });
181
- const state: ExecutionState = {
182
- input: {},
183
- output: {},
184
- iterationStack: [3],
185
- };
186
- const deps = createDeps(compiled);
187
- const suspension = rebuildSuspension(deps, {
188
- state,
189
- stepId: '0:first_task',
190
- reason: 'needs_input',
191
- data: { foo: 'bar' },
192
- });
193
-
194
- expect(suspension?.step.id).toBe('0:first_task[3]');
195
- expect(suspension?.reason).toBe('needs_input');
196
- expect(suspension?.data).toEqual({ foo: 'bar' });
197
-
198
- await suspension?.continue({ reply: 'ok' });
199
-
200
- expect(deps.captureTaskOutput).toHaveBeenCalledWith(task, state, {
201
- reply: 'ok',
202
- });
203
- expect(deps.markSnapshot).toHaveBeenCalledWith(
204
- expect.objectContaining({ id: '0:first_task[3]' }),
205
- 'completed',
206
- );
207
- expect(deps.emit).toHaveBeenCalledWith('hook:step:success', {
208
- runId: 'run-123',
209
- step: expect.objectContaining({ id: '0:first_task[3]' }),
210
- });
211
- expect(deps.executeFlow).toHaveBeenCalledWith(compiled.flow, state, [], 1);
212
- });
213
-
214
- it('continues outer flow after resuming a suspension inside a conditional branch', async () => {
215
- const branchTask = createTask('branch_task');
216
- const afterTask = createTask('after_task');
217
- const branchStep: CompiledStep = {
218
- type: StepType.Task,
219
- id: '0.branch.0.0:branch_task',
220
- label: 'branch_task',
221
- taskName: 'branch_task',
222
- };
223
- const conditionalStep: CompiledStep = {
224
- type: StepType.Conditional,
225
- id: '0:conditional',
226
- label: 'conditional',
227
- branches: [{ id: '0:branch_0', steps: [branchStep] }],
228
- };
229
- const outerStep: CompiledStep = {
230
- type: StepType.Task,
231
- id: '1:after_task',
232
- label: 'after_task',
233
- taskName: 'after_task',
234
- };
235
- const compiled = createCompiledWorkflow([conditionalStep, outerStep], {
236
- branch_task: branchTask,
237
- after_task: afterTask,
238
- });
239
- const state: ExecutionState = {
240
- input: {},
241
- output: {},
242
- iterationStack: [],
243
- };
244
- const deps = createDeps(compiled);
245
- deps.executeFlow = jest
246
- .fn()
247
- .mockResolvedValue(undefined) as SuspensionRebuilderDeps['executeFlow'];
248
-
249
- const suspension = rebuildSuspension(deps, {
250
- state,
251
- stepId: '0.branch.0.0:branch_task',
252
- });
253
-
254
- await suspension?.continue({ reply: 'ok' });
255
-
256
- expect(deps.captureTaskOutput).toHaveBeenCalledWith(branchTask, state, {
257
- reply: 'ok',
258
- });
259
- expect(deps.executeFlow).toHaveBeenCalledWith(compiled.flow, state, [], 1);
260
- });
261
-
262
- it('does not rebuild suspensions inside parallel blocks', () => {
263
- const firstTask = createTask('child_a');
264
- const secondTask = createTask('child_b');
265
- const childA: CompiledStep = {
266
- type: StepType.Task,
267
- id: '0.parallel.0:child_a',
268
- label: 'child_a',
269
- taskName: 'child_a',
270
- };
271
- const childB: CompiledStep = {
272
- type: StepType.Task,
273
- id: '0.parallel.1:child_b',
274
- label: 'child_b',
275
- taskName: 'child_b',
276
- };
277
- const parallelStep: CompiledStep = {
278
- type: StepType.Parallel,
279
- id: '0:parallel',
280
- label: 'parallel',
281
- strategy: 'wait_all',
282
- steps: [childA, childB],
283
- };
284
- const compiled = createCompiledWorkflow([parallelStep], {
285
- child_a: firstTask,
286
- child_b: secondTask,
287
- });
288
- const state: ExecutionState = {
289
- input: {},
290
- output: {},
291
- iterationStack: [],
292
- };
293
- const deps = createDeps(compiled);
294
-
295
- deps.executeFlow = jest
296
- .fn()
297
- .mockResolvedValue(undefined) as SuspensionRebuilderDeps['executeFlow'];
298
- const suspension = rebuildSuspension(deps, {
299
- state,
300
- stepId: '0.parallel.1:child_b',
301
- });
302
-
303
- expect(suspension).toBeNull();
304
- expect(deps.captureTaskOutput).not.toHaveBeenCalled();
305
- });
306
-
307
- it('resumes a loop suspension, updating accumulators and continuing execution', async () => {
308
- const loopTask = createTask('loop_task');
309
- const childTask: CompiledStep = {
310
- type: StepType.Task,
311
- id: '0.collector.0:loop_task',
312
- label: 'loop_task',
313
- taskName: 'loop_task',
314
- };
315
- const loopStep: CompiledStep = {
316
- type: StepType.Loop,
317
- id: '0:collector',
318
- loopType: 'for_each',
319
- label: 'collector',
320
- name: 'collector',
321
- forEach: { item: 'entry', in: { kind: 'literal', value: [] } },
322
- steps: [childTask],
323
- accumulate: {
324
- as: 'sum',
325
- initial: 0,
326
- merge: { kind: 'literal', value: 0 },
327
- },
328
- };
329
- const compiled = createCompiledWorkflow([loopStep], {
330
- loop_task: loopTask,
331
- });
332
- const state: ExecutionState = {
333
- input: {},
334
- output: {},
335
- iterationStack: [1],
336
- accumulator: 2,
337
- };
338
- const deps = createDeps(compiled);
339
-
340
- deps.executeFlow = jest
341
- .fn()
342
- .mockResolvedValue(undefined) as SuspensionRebuilderDeps['executeFlow'];
343
-
344
- mockedUpdateAccumulator.mockResolvedValue(5);
345
- mockedShouldStopLoop.mockResolvedValue(false);
346
- const nextSuspension = {
347
- step: {
348
- id: '0.collector.0:loop_task[2]',
349
- name: 'loop_task',
350
- type: StepType.Task,
351
- },
352
- continue: jest.fn().mockResolvedValue(undefined),
353
- };
354
- mockedRunLoopExecutor.mockResolvedValue(nextSuspension);
355
-
356
- const suspension = rebuildSuspension(deps, {
357
- state,
358
- stepId: '0.collector.0:loop_task[1]',
359
- });
360
- const result = await suspension?.continue({ resumed: true });
361
-
362
- expect(deps.captureTaskOutput).toHaveBeenCalledWith(
363
- loopTask,
364
- expect.objectContaining({ iteration: { index: 1, item: undefined } }),
365
- { resumed: true },
366
- );
367
- expect(mockedUpdateAccumulator).toHaveBeenCalledWith(
368
- loopStep,
369
- expect.objectContaining({
370
- iteration: { item: undefined, index: 1 },
371
- accumulator: 2,
372
- }),
373
- 2,
374
- );
375
- expect(mockedShouldStopLoop).toHaveBeenCalled();
376
- expect((state.output as { collector: { sum: number } }).collector.sum).toBe(
377
- 5,
378
- );
379
- expect(mockedRunLoopExecutor).toHaveBeenCalledWith(
380
- expect.anything(),
381
- loopStep,
382
- expect.objectContaining({ accumulator: 5, iterationStack: [] }),
383
- [0],
384
- 2,
385
- );
386
- const loopState = mockedRunLoopExecutor.mock.calls[0]?.[2];
387
- expect(loopState?.accumulator).toBe(5);
388
- expect(loopState?.iterationStack).toEqual([]);
389
- expect(result?.step.id).toBe(nextSuspension.step.id);
390
-
391
- await result?.continue({ done: true });
392
-
393
- expect(nextSuspension.continue).toHaveBeenCalledWith({ done: true });
394
- expect(deps.executeFlow).toHaveBeenLastCalledWith(
395
- compiled.flow,
396
- expect.objectContaining({
397
- accumulator: 5,
398
- output: expect.objectContaining({ collector: { sum: 5 } }),
399
- }),
400
- [],
401
- 1,
402
- );
403
- });
404
- });
@@ -1,31 +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
- import type { Suspension } from '../workflow-types';
8
-
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
- export function wrapSuspensionContinuation(
17
- suspension: Suspension,
18
- onComplete: () => Promise<Suspension | void>,
19
- ): Suspension {
20
- return {
21
- ...suspension,
22
- continue: async (resumeData: unknown) => {
23
- const next = await suspension.continue(resumeData);
24
- if (next) {
25
- return wrapSuspensionContinuation(next, onComplete);
26
- }
27
-
28
- return onComplete();
29
- },
30
- };
31
- }