@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
@@ -4,7 +4,9 @@
4
4
  * Full terms: see LICENSE.md.
5
5
  */
6
6
 
7
+ import type { WaitInfo } from './checkpoint';
7
8
  import type { StepExecutionRecord } from './context';
9
+ import type { WorkflowResumeRejectedError } from './errors';
8
10
 
9
11
  export enum StepType {
10
12
  Task = 'task',
@@ -31,17 +33,41 @@ export type WorkflowEventMap = {
31
33
  'hook:workflow:failure': { runId?: string; error: unknown };
32
34
  'hook:workflow:suspended': {
33
35
  runId?: string;
34
- step: StepInfo;
35
- reason?: string;
36
- data?: unknown;
36
+ /** Every open wait of the run, in flow order. */
37
+ waits: WaitInfo[];
38
+ };
39
+ /** A resume payload was refused; the run is unchanged and the wait stays open. */
40
+ 'hook:workflow:resume_rejected': {
41
+ runId?: string;
42
+ /** The wait the payload was meant for. */
43
+ wait: WaitInfo;
44
+ /** The payload as passed to `resume()`. */
45
+ resumeData: unknown;
46
+ error: WorkflowResumeRejectedError;
37
47
  };
38
48
  'hook:step:start': StepWorkflowEventPayload;
49
+ /** A suspended step whose wait was resolved re-runs its action body. */
50
+ 'hook:step:resumed': StepWorkflowEventPayload & {
51
+ /** The wait this resume resolved. */
52
+ wait: WaitInfo;
53
+ /** The payload recorded for the wait, after its JSON round trip. */
54
+ resumeData: unknown;
55
+ };
56
+ /** A resumed step refused its payload and is suspended again on the same wait. */
57
+ 'hook:step:resume_rejected': StepWorkflowEventPayload & {
58
+ wait: WaitInfo;
59
+ error: WorkflowResumeRejectedError;
60
+ };
39
61
  'hook:step:success': StepWorkflowEventPayload;
40
62
  'hook:step:error': StepWorkflowEventPayload & { error: unknown };
41
- 'hook:step:cancelled': StepWorkflowEventPayload & { error: unknown };
63
+ 'hook:step:cancelled': StepWorkflowEventPayload & {
64
+ error: unknown;
65
+ /** The wait the step was suspended on, which is now dropped. */
66
+ wait?: WaitInfo;
67
+ };
42
68
  'hook:step:suspended': StepWorkflowEventPayload & {
43
- reason?: string;
44
- data?: unknown;
69
+ /** The wait this suspension opened. */
70
+ wait: WaitInfo;
45
71
  };
46
72
  'hook:step:skipped': { runId?: string; step: StepInfo; reason?: string };
47
73
  };
@@ -0,0 +1,159 @@
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 { StepType } from './workflow-event-emitter';
8
+ import type {
9
+ CompiledMapping,
10
+ CompiledStep,
11
+ CompiledValue,
12
+ CompiledWorkflow,
13
+ } from './workflow-types';
14
+
15
+ /** Separator between fingerprint parts; never produced by the parts themselves. */
16
+ const PART_SEPARATOR = '~|~';
17
+ /** Fingerprints are pure functions of the compiled graph, so compute each once. */
18
+ const fingerprintCache = new WeakMap<CompiledWorkflow, string>();
19
+
20
+ /**
21
+ * Fingerprint the parts of a compiled workflow that a checkpoint depends on.
22
+ *
23
+ * Hashing step ids alone is not enough: a changed `until`, `while`, branch
24
+ * condition or `inputs` mapping keeps every id stable while changing what the
25
+ * resumed run actually does. Labels are included because `buildStepId`
26
+ * embeds them, so renaming a task changes every downstream step id.
27
+ *
28
+ * @param compiled The compiled workflow to fingerprint.
29
+ * @returns A short, stable hash of the resume-relevant definition surface.
30
+ */
31
+ export const fingerprintWorkflow = (compiled: CompiledWorkflow): string => {
32
+ const cached = fingerprintCache.get(compiled);
33
+ if (cached !== undefined) {
34
+ return cached;
35
+ }
36
+
37
+ const parts: string[] = [];
38
+
39
+ collectSteps(compiled, compiled.flow, parts);
40
+ parts.push('outputs', ...describeMapping(compiled.outputMapping));
41
+
42
+ const fingerprint = hash(parts.join(PART_SEPARATOR));
43
+ fingerprintCache.set(compiled, fingerprint);
44
+
45
+ return fingerprint;
46
+ };
47
+
48
+ /**
49
+ * Append a canonical description of each step, depth first.
50
+ *
51
+ * @param compiled The compiled workflow, used to resolve task definitions.
52
+ * @param steps Steps to describe.
53
+ * @param parts Accumulator receiving the description fragments.
54
+ */
55
+ const collectSteps = (
56
+ compiled: CompiledWorkflow,
57
+ steps: CompiledStep[],
58
+ parts: string[],
59
+ ): void => {
60
+ for (const step of steps) {
61
+ parts.push(step.type, step.id, step.label);
62
+
63
+ switch (step.type) {
64
+ case StepType.Task: {
65
+ const task = compiled.tasks[step.taskName];
66
+
67
+ parts.push(step.taskName, task?.actionName ?? '');
68
+ parts.push(...describeMapping(task?.inputs));
69
+ break;
70
+ }
71
+ case StepType.Parallel:
72
+ parts.push(step.strategy);
73
+ collectSteps(compiled, step.steps, parts);
74
+ break;
75
+ case StepType.Conditional:
76
+ for (const branch of step.branches) {
77
+ parts.push(branch.id, describeValue(branch.condition));
78
+ collectSteps(compiled, branch.steps, parts);
79
+ }
80
+ break;
81
+ case StepType.Loop:
82
+ parts.push(step.loopType, step.name ?? '');
83
+ parts.push(
84
+ step.accumulate
85
+ ? `${step.accumulate.as}=${stringify(step.accumulate.initial)}:${describeValue(step.accumulate.merge)}`
86
+ : '',
87
+ );
88
+ if (step.loopType === 'for_each') {
89
+ parts.push(step.forEach.item, describeValue(step.forEach.in));
90
+ parts.push(describeValue(step.until));
91
+ } else {
92
+ parts.push(describeValue(step.while));
93
+ }
94
+ collectSteps(compiled, step.steps, parts);
95
+ break;
96
+ }
97
+ }
98
+ };
99
+ /**
100
+ * Describe a compiled mapping in a key-stable order.
101
+ *
102
+ * @param mapping The mapping to describe.
103
+ * @returns One fragment per mapped key.
104
+ */
105
+ const describeMapping = (mapping?: CompiledMapping): string[] => {
106
+ if (!mapping) {
107
+ return [];
108
+ }
109
+
110
+ return Object.keys(mapping)
111
+ .sort()
112
+ .map((key) => `${key}=${describeValue(mapping[key])}`);
113
+ };
114
+ /**
115
+ * Describe a compiled value by its authored source, not its compiled form.
116
+ *
117
+ * @param value The compiled value.
118
+ * @returns A stable textual description.
119
+ */
120
+ const describeValue = (value?: CompiledValue): string => {
121
+ if (!value) {
122
+ return '';
123
+ }
124
+
125
+ return value.kind === 'expression'
126
+ ? `=${value.source}`
127
+ : stringify(value.value);
128
+ };
129
+ const stringify = (value: unknown): string => {
130
+ try {
131
+ return JSON.stringify(value) ?? String(value);
132
+ } catch {
133
+ return String(value);
134
+ }
135
+ };
136
+ /**
137
+ * Hash a string with two FNV-1a style passes under different constants.
138
+ *
139
+ * Kept dependency-free on purpose: the package is consumed from browser
140
+ * bundles, so `node:crypto` is not available.
141
+ *
142
+ * @param value The canonical description to hash.
143
+ * @returns A 16-character hexadecimal digest.
144
+ */
145
+ const hash = (value: string): string => {
146
+ let low = 0x811c9dc5;
147
+ let high = 0x01000193;
148
+
149
+ for (let index = 0; index < value.length; index += 1) {
150
+ const code = value.charCodeAt(index);
151
+
152
+ low ^= code;
153
+ low = Math.imul(low, 0x01000193) >>> 0;
154
+ high ^= code + index;
155
+ high = Math.imul(high, 0x85ebca6b) >>> 0;
156
+ }
157
+
158
+ return `${low.toString(16).padStart(8, '0')}${high.toString(16).padStart(8, '0')}`;
159
+ };