@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
@@ -33,15 +33,10 @@ export const awaitReply = defineAction<
33
33
  inputSchema,
34
34
  outputSchema,
35
35
  execute: async ({ context }) => {
36
- const resumeData = await context.workflow.suspend({
36
+ return context.workflow.suspend({
37
37
  reason: 'awaiting_user_response',
38
38
  data: { hint: 'Provide phone number' },
39
+ accepts: resumeSchema,
39
40
  });
40
- const parsed = resumeSchema.safeParse(resumeData);
41
- if (!parsed.success) {
42
- throw new Error('resumeData must include a string `text` field.');
43
- }
44
-
45
- return parsed.data;
46
41
  },
47
42
  });
@@ -23,8 +23,10 @@ async function main() {
23
23
  const context = new LoopExampleContext({ channel: 'chat' }, emitter);
24
24
 
25
25
  emitter.on('hook:workflow:start', () => context.log('workflow started'));
26
- emitter.on('hook:workflow:suspended', ({ step, reason }) =>
27
- context.log(`workflow suspended at "${step.name}"`, { reason }),
26
+ emitter.on('hook:workflow:suspended', ({ waits }) =>
27
+ waits.forEach(({ step, reason }) =>
28
+ context.log(`workflow suspended at "${step.name}"`, { reason }),
29
+ ),
28
30
  );
29
31
  emitter.on('hook:workflow:finish', ({ output }) =>
30
32
  context.log('workflow finished', output),
@@ -33,19 +33,21 @@ export const waitForUser = defineAction<
33
33
  inputSchema,
34
34
  outputSchema,
35
35
  execute: async ({ input, context }) => {
36
- context.log('Suspending workflow until we get a reply', {
37
- prompt: input.prompt,
38
- });
36
+ // A resumed body runs again from the top; skip work that already happened.
37
+ if (!context.workflow.hasRecordedResult()) {
38
+ context.log('Suspending workflow until we get a reply', {
39
+ prompt: input.prompt,
40
+ });
41
+ }
39
42
 
40
- const resumeData = await context.workflow.suspend({
43
+ // A payload that does not match `accepts` is refused and the wait stays
44
+ // open, instead of failing the run.
45
+ const { reply } = await context.workflow.suspend({
41
46
  reason: 'awaiting_user',
42
47
  data: { prompt: input.prompt },
48
+ accepts: resumeSchema,
43
49
  });
44
- const parsed = resumeSchema.safeParse(resumeData);
45
- if (!parsed.success) {
46
- throw new Error('resumeData must include a string reply');
47
- }
48
50
 
49
- return { reply: parsed.data.reply };
51
+ return { reply };
50
52
  },
51
53
  });
@@ -23,14 +23,17 @@ async function main() {
23
23
  const context = new SuspendResumeContext({ channel: 'chat' }, emitter);
24
24
 
25
25
  emitter.on('hook:workflow:start', () => context.log('workflow started'));
26
- emitter.on('hook:workflow:suspended', ({ step, reason, data }) =>
27
- context.log(`workflow suspended at "${step.name}"`, { reason, data }),
26
+ emitter.on('hook:workflow:suspended', ({ waits }) =>
27
+ waits.forEach(({ step, reason, data }) =>
28
+ context.log(`workflow suspended at "${step.name}"`, { reason, data }),
29
+ ),
28
30
  );
29
31
  emitter.on('hook:workflow:finish', ({ output }) =>
30
32
  context.log('workflow finished', output),
31
33
  );
32
34
 
33
35
  const runner = await workflow.buildAsyncRunner();
36
+ // The run below suspends; the `runner` instance is dropped after that.
34
37
  const startResult = await runner.start({
35
38
  inputData: {
36
39
  question: "Can we deploy to production after today's smoke tests?",
@@ -50,24 +53,61 @@ async function main() {
50
53
  return;
51
54
  }
52
55
 
53
- context.log('persist this snapshot to resume later', startResult.snapshot);
56
+ // Persist the checkpoint and snapshot; they are plain JSON.
57
+ const stored = JSON.stringify({
58
+ checkpoint: startResult.checkpoint,
59
+ snapshot: startResult.snapshot,
60
+ });
61
+ const [wait] = startResult.waits;
62
+ context.log('persisted checkpoint; waiting on', {
63
+ waitId: wait.waitId,
64
+ reason: wait.reason,
65
+ });
54
66
 
55
- const resumeResult = await runner.resume({
56
- resumeData: { reply: 'Yes, proceed once monitoring is green.' },
67
+ // Later, possibly in another process: check the checkpoint still fits this
68
+ // workflow and the wait accepts the payload, then restore a fresh runner
69
+ // and resolve the wait.
70
+ const { checkpoint, snapshot } = JSON.parse(stored);
71
+ const resumeData = { reply: 'Yes, proceed once monitoring is green.' };
72
+ const validation = workflow.validateCheckpoint(checkpoint, {
73
+ waitId: wait.waitId,
74
+ resumeData,
75
+ });
76
+ if (!validation.ok) {
77
+ console.error('Cannot resume this run', validation.error);
78
+
79
+ return;
80
+ }
81
+
82
+ const restoredContext = new SuspendResumeContext(
83
+ { channel: 'chat' },
84
+ emitter,
85
+ );
86
+ const restored = workflow.buildRunnerFromCheckpoint({
87
+ checkpoint,
88
+ snapshot,
89
+ context: restoredContext,
90
+ });
91
+ const resumeResult = await restored.resume({
92
+ waitId: wait.waitId,
93
+ resumeData,
57
94
  });
58
95
 
59
96
  if (resumeResult.status === 'finished') {
60
- context.log('resumed and completed', resumeResult.output);
97
+ restoredContext.log('resumed and completed', resumeResult.output);
61
98
 
62
99
  return;
63
100
  }
64
101
 
65
102
  if (resumeResult.status === 'suspended') {
66
- context.log('suspended again', {
67
- step: resumeResult.step.name,
68
- reason: resumeResult.reason,
69
- data: resumeResult.data,
70
- });
103
+ // A refused payload leaves the run as it was: the wait is still open.
104
+ if (resumeResult.rejection) {
105
+ restoredContext.log('payload refused', resumeResult.rejection.error);
106
+
107
+ return;
108
+ }
109
+
110
+ restoredContext.log('suspended again', resumeResult.waits);
71
111
 
72
112
  return;
73
113
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hexabot-ai/agentic",
3
- "version": "3.4.0-beta.2",
3
+ "version": "3.5.0-beta.0",
4
4
  "description": "Schemas and utilities for the Hexabot agentic workflow DSL.",
5
5
  "main": "dist/cjs/index.js",
6
6
  "module": "dist/esm/index.js",
@@ -21,7 +21,7 @@
21
21
  "dependencies": {
22
22
  "jsonata": "^2.2.0",
23
23
  "yaml": "^2.8.3",
24
- "zod": "^4.3.6"
24
+ "zod": "^4.6.7"
25
25
  },
26
26
  "devDependencies": {
27
27
  "@typescript-eslint/eslint-plugin": "^8.46.0",
@@ -43,7 +43,7 @@
43
43
  "*.{ts}": "eslint --fix --config eslint.config-staged.cjs"
44
44
  },
45
45
  "engines": {
46
- "node": ">=24.17.0"
46
+ "node": ">=24.22.1"
47
47
  },
48
48
  "license": "FCL-1.0-ALv2",
49
49
  "scripts": {