@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
@@ -4,17 +4,16 @@
4
4
  * Full terms: see LICENSE.md.
5
5
  */
6
6
 
7
+ import type { LoopFrame } from '../checkpoint';
7
8
  import type {
8
9
  EvaluationScope,
9
10
  ExecutionState,
10
11
  ForEachLoopStep,
11
12
  LoopStep,
12
- Suspension,
13
13
  WhileLoopStep,
14
14
  } from '../workflow-types';
15
15
  import { evaluateValue } from '../workflow-values';
16
16
 
17
- import { wrapSuspensionContinuation } from './suspension-continuation';
18
17
  import type { StepExecutorEnv } from './types';
19
18
 
20
19
  type LoopScope = EvaluationScope;
@@ -26,21 +25,22 @@ type LoopScope = EvaluationScope;
26
25
  * @param step The loop step configuration.
27
26
  * @param state Mutable workflow execution state.
28
27
  * @param path Path tokens locating this loop within the workflow.
29
- * @param startIndex Index to resume iteration from when continuing.
30
- * @returns A suspension if a child step pauses execution, otherwise void.
28
+ * @param frame Frame returned when an iteration previously suspended; the
29
+ * loop resumes that iteration with the items and accumulator it recorded.
30
+ * @returns A frame if an iteration suspends, otherwise void.
31
31
  */
32
32
  export async function executeLoop(
33
33
  env: StepExecutorEnv,
34
34
  step: LoopStep,
35
35
  state: ExecutionState,
36
36
  path: Array<number | string>,
37
- startIndex = 0,
38
- ): Promise<Suspension | void> {
37
+ frame?: LoopFrame,
38
+ ): Promise<LoopFrame | void> {
39
39
  if (step.loopType === 'for_each') {
40
- return executeForEachLoop(env, step, state, path, startIndex);
40
+ return executeForEachLoop(env, step, state, path, frame);
41
41
  }
42
42
 
43
- return executeWhileLoop(env, step, state, path, startIndex);
43
+ return executeWhileLoop(env, step, state, path, frame);
44
44
  }
45
45
 
46
46
  async function executeForEachLoop(
@@ -48,64 +48,41 @@ async function executeForEachLoop(
48
48
  step: ForEachLoopStep,
49
49
  state: ExecutionState,
50
50
  path: Array<number | string>,
51
- startIndex: number,
52
- ): Promise<Suspension | void> {
53
- const scope = {
54
- input: state.input,
55
- context: env.context.state,
56
- output: state.output,
57
- iteration: state.iteration,
58
- accumulator: state.accumulator,
59
- };
60
- const items = await evaluateValue(step.forEach.in, scope);
61
- const iterable = Array.isArray(items) ? items : [];
62
- let accumulator = step.accumulate?.initial ?? state.accumulator;
63
-
64
- for (let index = startIndex; index < iterable.length; index += 1) {
65
- const item = iterable[index];
51
+ frame?: LoopFrame,
52
+ ): Promise<LoopFrame | void> {
53
+ // The item list is resolved once, when the loop starts; a resumed loop
54
+ // keeps iterating over the same items even if `in` would now differ.
55
+ const items = frame
56
+ ? (frame.items ?? [])
57
+ : await resolveItems(env, step, state);
58
+ let accumulator = frame
59
+ ? frame.accumulator
60
+ : (step.accumulate?.initial ?? state.accumulator);
61
+
62
+ for (let index = frame?.index ?? 0; index < items.length; index += 1) {
63
+ const item = items[index];
66
64
  const iterationState: ExecutionState = {
67
65
  ...state,
68
66
  iteration: { item, index },
69
67
  accumulator,
70
68
  iterationStack: [...state.iterationStack, index],
71
69
  };
72
- const suspension = await env.executeFlow(step.steps, iterationState, [
73
- ...path,
74
- index,
75
- ]);
76
-
77
- if (suspension) {
78
- return wrapSuspensionContinuation(suspension, async () => {
79
- const postScope = buildScope(
80
- env,
81
- iterationState,
82
- { item, index },
83
- accumulator,
84
- );
85
- accumulator = await updateAccumulator(step, postScope, accumulator);
86
-
87
- const shouldStop = await shouldStopLoop(step, postScope);
88
- if (shouldStop) {
89
- state.accumulator = accumulator;
90
- if (step.accumulate && step.name) {
91
- state.output[step.name] = { [step.accumulate.as]: accumulator };
92
- }
93
-
94
- return undefined;
95
- }
96
-
97
- return executeForEachLoop(
98
- env,
99
- step,
100
- {
101
- ...iterationState,
102
- accumulator,
103
- iterationStack: state.iterationStack,
104
- },
105
- path,
106
- index + 1,
107
- );
108
- });
70
+ const child = await env.executeFlow(
71
+ step.steps,
72
+ iterationState,
73
+ [...path, index],
74
+ frame && index === frame.index ? frame.child : undefined,
75
+ );
76
+
77
+ if (child) {
78
+ return {
79
+ kind: 'loop',
80
+ stepId: step.id,
81
+ index,
82
+ items,
83
+ accumulator,
84
+ child,
85
+ };
109
86
  }
110
87
 
111
88
  const postScope = buildScope(
@@ -135,20 +112,28 @@ async function executeWhileLoop(
135
112
  step: WhileLoopStep,
136
113
  state: ExecutionState,
137
114
  path: Array<number | string>,
138
- startIndex: number,
139
- ): Promise<Suspension | void> {
140
- let accumulator = step.accumulate?.initial ?? state.accumulator;
141
-
142
- for (let index = startIndex; ; index += 1) {
143
- const conditionScope = buildScope(
144
- env,
145
- state,
146
- { item: undefined, index },
147
- accumulator,
148
- );
149
- const shouldContinue = await evaluateValue(step.while, conditionScope);
150
- if (!Boolean(shouldContinue)) {
151
- break;
115
+ frame?: LoopFrame,
116
+ ): Promise<LoopFrame | void> {
117
+ let accumulator = frame
118
+ ? frame.accumulator
119
+ : (step.accumulate?.initial ?? state.accumulator);
120
+
121
+ for (let index = frame?.index ?? 0; ; index += 1) {
122
+ const resumedChild =
123
+ frame && index === frame.index ? frame.child : undefined;
124
+
125
+ // The guard of a resumed iteration already passed before it suspended.
126
+ if (!resumedChild) {
127
+ const conditionScope = buildScope(
128
+ env,
129
+ state,
130
+ { item: undefined, index },
131
+ accumulator,
132
+ );
133
+ const shouldContinue = await evaluateValue(step.while, conditionScope);
134
+ if (!Boolean(shouldContinue)) {
135
+ break;
136
+ }
152
137
  }
153
138
 
154
139
  const iterationState: ExecutionState = {
@@ -157,33 +142,15 @@ async function executeWhileLoop(
157
142
  accumulator,
158
143
  iterationStack: [...state.iterationStack, index],
159
144
  };
160
- const suspension = await env.executeFlow(step.steps, iterationState, [
161
- ...path,
162
- index,
163
- ]);
164
-
165
- if (suspension) {
166
- return wrapSuspensionContinuation(suspension, async () => {
167
- const postScope = buildScope(
168
- env,
169
- iterationState,
170
- { item: undefined, index },
171
- accumulator,
172
- );
173
- accumulator = await updateAccumulator(step, postScope, accumulator);
174
-
175
- return executeWhileLoop(
176
- env,
177
- step,
178
- {
179
- ...iterationState,
180
- accumulator,
181
- iterationStack: state.iterationStack,
182
- },
183
- path,
184
- index + 1,
185
- );
186
- });
145
+ const child = await env.executeFlow(
146
+ step.steps,
147
+ iterationState,
148
+ [...path, index],
149
+ resumedChild,
150
+ );
151
+
152
+ if (child) {
153
+ return { kind: 'loop', stepId: step.id, index, accumulator, child };
187
154
  }
188
155
 
189
156
  const postScope = buildScope(
@@ -202,6 +169,22 @@ async function executeWhileLoop(
202
169
  return undefined;
203
170
  }
204
171
 
172
+ async function resolveItems(
173
+ env: StepExecutorEnv,
174
+ step: ForEachLoopStep,
175
+ state: ExecutionState,
176
+ ): Promise<unknown[]> {
177
+ const items = await evaluateValue(step.forEach.in, {
178
+ input: state.input,
179
+ context: env.context.state,
180
+ output: state.output,
181
+ iteration: state.iteration,
182
+ accumulator: state.accumulator,
183
+ });
184
+
185
+ return Array.isArray(items) ? items : [];
186
+ }
187
+
205
188
  function finalizeAccumulatorState(
206
189
  step: LoopStep,
207
190
  state: ExecutionState,