@hexabot-ai/agentic 3.5.0-beta.0 → 3.6.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 (145) hide show
  1. package/README.md +12 -3
  2. package/dist/cjs/action/abstract-action.js +51 -35
  3. package/dist/cjs/bindings/base-binding.js +229 -211
  4. package/dist/cjs/checkpoint.js +1 -1
  5. package/dist/cjs/context.js +2 -3
  6. package/dist/cjs/dsl.types.js +44 -90
  7. package/dist/cjs/errors.js +13 -1
  8. package/dist/cjs/index.js +3 -1
  9. package/dist/cjs/resume-payload.js +11 -1
  10. package/dist/cjs/runner-runtime-control.js +39 -27
  11. package/dist/cjs/step-executors/conditional-executor.js +2 -7
  12. package/dist/cjs/step-executors/loop-executor.js +14 -28
  13. package/dist/cjs/step-executors/parallel-executor.js +14 -25
  14. package/dist/cjs/step-executors/scope.js +25 -0
  15. package/dist/cjs/step-executors/skip-helpers.js +26 -34
  16. package/dist/cjs/step-executors/task-executor.js +58 -69
  17. package/dist/cjs/utils/flow-steps.js +41 -0
  18. package/dist/cjs/utils/naming.js +10 -10
  19. package/dist/cjs/utils/object-path.js +51 -0
  20. package/dist/cjs/utils/timeout.js +16 -39
  21. package/dist/cjs/validation-issue.js +14 -1
  22. package/dist/cjs/workflow-compiler.js +52 -96
  23. package/dist/cjs/workflow-fingerprint.js +22 -11
  24. package/dist/cjs/workflow-runner.js +19 -25
  25. package/dist/cjs/workflow-values.js +9 -7
  26. package/dist/cjs/workflow.js +44 -103
  27. package/dist/esm/action/abstract-action.js +51 -35
  28. package/dist/esm/bindings/base-binding.js +229 -211
  29. package/dist/esm/checkpoint.js +2 -2
  30. package/dist/esm/context.js +2 -3
  31. package/dist/esm/dsl.types.js +42 -88
  32. package/dist/esm/errors.js +11 -0
  33. package/dist/esm/index.js +2 -2
  34. package/dist/esm/resume-payload.js +10 -1
  35. package/dist/esm/runner-runtime-control.js +39 -27
  36. package/dist/esm/step-executors/conditional-executor.js +2 -7
  37. package/dist/esm/step-executors/loop-executor.js +14 -28
  38. package/dist/esm/step-executors/parallel-executor.js +14 -25
  39. package/dist/esm/step-executors/scope.js +21 -0
  40. package/dist/esm/step-executors/skip-helpers.js +27 -35
  41. package/dist/esm/step-executors/task-executor.js +58 -69
  42. package/dist/esm/utils/flow-steps.js +37 -0
  43. package/dist/esm/utils/naming.js +9 -9
  44. package/dist/esm/utils/object-path.js +46 -0
  45. package/dist/esm/utils/timeout.js +16 -39
  46. package/dist/esm/validation-issue.js +11 -0
  47. package/dist/esm/workflow-compiler.js +50 -95
  48. package/dist/esm/workflow-fingerprint.js +22 -11
  49. package/dist/esm/workflow-runner.js +21 -27
  50. package/dist/esm/workflow-values.js +7 -6
  51. package/dist/esm/workflow.js +43 -103
  52. package/dist/types/action/abstract-action.d.ts +7 -1
  53. package/dist/types/action/abstract-action.d.ts.map +1 -1
  54. package/dist/types/bindings/base-binding.d.ts +10 -0
  55. package/dist/types/bindings/base-binding.d.ts.map +1 -1
  56. package/dist/types/context.d.ts +2 -3
  57. package/dist/types/context.d.ts.map +1 -1
  58. package/dist/types/dsl.types.d.ts +7 -12
  59. package/dist/types/dsl.types.d.ts.map +1 -1
  60. package/dist/types/errors.d.ts +9 -0
  61. package/dist/types/errors.d.ts.map +1 -1
  62. package/dist/types/index.d.ts +2 -2
  63. package/dist/types/index.d.ts.map +1 -1
  64. package/dist/types/resume-payload.d.ts +7 -0
  65. package/dist/types/resume-payload.d.ts.map +1 -1
  66. package/dist/types/runner-runtime-control.d.ts.map +1 -1
  67. package/dist/types/step-executors/conditional-executor.d.ts.map +1 -1
  68. package/dist/types/step-executors/loop-executor.d.ts +2 -4
  69. package/dist/types/step-executors/loop-executor.d.ts.map +1 -1
  70. package/dist/types/step-executors/parallel-executor.d.ts.map +1 -1
  71. package/dist/types/step-executors/scope.d.ts +12 -0
  72. package/dist/types/step-executors/scope.d.ts.map +1 -0
  73. package/dist/types/step-executors/skip-helpers.d.ts +2 -8
  74. package/dist/types/step-executors/skip-helpers.d.ts.map +1 -1
  75. package/dist/types/step-executors/task-executor.d.ts.map +1 -1
  76. package/dist/types/utils/flow-steps.d.ts +16 -0
  77. package/dist/types/utils/flow-steps.d.ts.map +1 -0
  78. package/dist/types/utils/naming.d.ts +7 -7
  79. package/dist/types/utils/naming.d.ts.map +1 -1
  80. package/dist/types/utils/object-path.d.ts +11 -0
  81. package/dist/types/utils/object-path.d.ts.map +1 -0
  82. package/dist/types/utils/timeout.d.ts.map +1 -1
  83. package/dist/types/validation-issue.d.ts +13 -0
  84. package/dist/types/validation-issue.d.ts.map +1 -1
  85. package/dist/types/workflow-compiler.d.ts +15 -1
  86. package/dist/types/workflow-compiler.d.ts.map +1 -1
  87. package/dist/types/workflow-fingerprint.d.ts.map +1 -1
  88. package/dist/types/workflow-runner.d.ts +2 -0
  89. package/dist/types/workflow-runner.d.ts.map +1 -1
  90. package/dist/types/workflow-values.d.ts +2 -0
  91. package/dist/types/workflow-values.d.ts.map +1 -1
  92. package/dist/types/workflow.d.ts +2 -1
  93. package/dist/types/workflow.d.ts.map +1 -1
  94. package/examples/defs-bindings-agent/actions/ai-agent.ts +5 -3
  95. package/examples/defs-bindings-agent/actions/{caculate-score.ts → calculate-score.ts} +8 -8
  96. package/examples/defs-bindings-agent/actions/index.ts +2 -2
  97. package/examples/defs-bindings-agent/workflow.yml +2 -2
  98. package/examples/full/workflow.yml +20 -15
  99. package/examples/suspend-resume/workflow.yml +6 -3
  100. package/package.json +8 -5
  101. package/src/__tests__/checkpoint.test.ts +6 -1
  102. package/src/__tests__/resume-payload.test.ts +29 -0
  103. package/src/__tests__/test-helpers.ts +1 -1
  104. package/src/__tests__/validation.test.ts +330 -0
  105. package/src/__tests__/workflow-compiler.test.ts +278 -3
  106. package/src/__tests__/workflow-definition-path.test.ts +2 -0
  107. package/src/__tests__/workflow-fingerprint.test.ts +65 -0
  108. package/src/__tests__/workflow-runner.test.ts +280 -5
  109. package/src/__tests__/workflow-values.test.ts +13 -0
  110. package/src/__tests__/workflow.test.ts +4 -2
  111. package/src/action/__tests__/abstract-action-timing.test.ts +92 -0
  112. package/src/action/abstract-action.ts +67 -40
  113. package/src/bindings/base-binding.test.ts +470 -0
  114. package/src/bindings/base-binding.ts +344 -267
  115. package/src/checkpoint.ts +2 -4
  116. package/src/context.ts +2 -3
  117. package/src/dsl.types.ts +75 -154
  118. package/src/errors.ts +15 -0
  119. package/src/index.ts +2 -0
  120. package/src/resume-payload.ts +13 -3
  121. package/src/runner-runtime-control.ts +52 -29
  122. package/src/step-executors/conditional-executor.ts +3 -7
  123. package/src/step-executors/loop-executor.test.ts +55 -0
  124. package/src/step-executors/loop-executor.ts +16 -50
  125. package/src/step-executors/parallel-executor.ts +14 -37
  126. package/src/step-executors/scope.ts +30 -0
  127. package/src/step-executors/skip-helpers.test.ts +133 -0
  128. package/src/step-executors/skip-helpers.ts +43 -76
  129. package/src/step-executors/task-executor.test.ts +130 -1
  130. package/src/step-executors/task-executor.ts +109 -79
  131. package/src/utils/flow-steps.test.ts +121 -0
  132. package/src/utils/flow-steps.ts +62 -0
  133. package/src/utils/naming.test.ts +50 -0
  134. package/src/utils/naming.ts +11 -11
  135. package/src/utils/object-path.test.ts +70 -0
  136. package/src/utils/object-path.ts +67 -0
  137. package/src/utils/timeout.test.ts +152 -0
  138. package/src/utils/timeout.ts +26 -44
  139. package/src/validation-issue.test.ts +70 -0
  140. package/src/validation-issue.ts +27 -0
  141. package/src/workflow-compiler.ts +118 -180
  142. package/src/workflow-fingerprint.ts +23 -12
  143. package/src/workflow-runner.ts +28 -27
  144. package/src/workflow-values.ts +9 -7
  145. package/src/workflow.ts +58 -140
@@ -162,4 +162,69 @@ describe('fingerprintWorkflow', () => {
162
162
 
163
163
  expect(fingerprint(next)).not.toBe(fingerprint(createDefinition()));
164
164
  });
165
+ it('keeps the fingerprint of every step kind stable across releases', () => {
166
+ // Persisted checkpoints carry this value: any change to it fails every
167
+ // suspended run with WorkflowDefinitionDriftError on resume.
168
+ const definition: WorkflowDefinition = {
169
+ defs: createTaskDefs({
170
+ ask: { action: 'first', inputs: { label: 'x', count: '=$input.n' } },
171
+ note: { action: 'second' },
172
+ }),
173
+ flow: [
174
+ { do: 'ask' },
175
+ {
176
+ parallel: {
177
+ strategy: 'wait_any',
178
+ description: 'race',
179
+ steps: [
180
+ { do: 'note' },
181
+ {
182
+ conditional: {
183
+ when: [
184
+ { condition: '=$output.ask.ok', steps: [{ do: 'ask' }] },
185
+ {
186
+ else: true,
187
+ steps: [
188
+ {
189
+ loop: {
190
+ type: 'while',
191
+ while: '=$iteration.index < 2',
192
+ steps: [{ do: 'note' }],
193
+ },
194
+ },
195
+ ],
196
+ },
197
+ ],
198
+ },
199
+ },
200
+ ],
201
+ },
202
+ },
203
+ {
204
+ loop: {
205
+ type: 'for_each',
206
+ name: 'collect',
207
+ for_each: { item: 'entry', in: '=[1, 2, 3]' },
208
+ until: '=$accumulator > 3',
209
+ accumulate: {
210
+ as: 'sum',
211
+ initial: 0,
212
+ merge: '=$accumulator + $iteration.item',
213
+ },
214
+ steps: [{ do: 'ask' }, { parallel: { steps: [{ do: 'note' }] } }],
215
+ },
216
+ },
217
+ {
218
+ loop: {
219
+ type: 'for_each',
220
+ for_each: { item: 'x', in: '=[]' },
221
+ steps: [],
222
+ },
223
+ },
224
+ ],
225
+ outputs: { result: '=$output.ask', total: '=$output.collect.sum' },
226
+ };
227
+
228
+ expect(fingerprint(definition)).toBe('5bfb3ba54027417e');
229
+ });
165
230
  });
@@ -10,7 +10,10 @@ import { defineAction } from '../action/action';
10
10
  import type { TaskFrame, WorkflowCheckpoint } from '../checkpoint';
11
11
  import { BaseWorkflowContext } from '../context';
12
12
  import type { Settings, WorkflowDefinition } from '../dsl.types';
13
- import { WorkflowCheckpointInvalidError } from '../errors';
13
+ import {
14
+ WorkflowCheckpointInvalidError,
15
+ WorkflowInputRejectedError,
16
+ } from '../errors';
14
17
  import { compileWorkflow } from '../workflow-compiler';
15
18
  import {
16
19
  StepType,
@@ -284,7 +287,10 @@ describe('WorkflowRunner', () => {
284
287
  },
285
288
  inputs: {
286
289
  schema: {
287
- items: { type: 'array', items: { type: 'number' } },
290
+ type: 'object',
291
+ properties: {
292
+ items: { type: 'array', items: { type: 'number' } },
293
+ },
288
294
  },
289
295
  },
290
296
  };
@@ -913,7 +919,8 @@ describe('WorkflowRunner', () => {
913
919
  outputs: { note: '=$output.emit_step.note' },
914
920
  inputs: {
915
921
  schema: {
916
- note: { type: 'string' },
922
+ type: 'object',
923
+ properties: { note: { type: 'string' } },
917
924
  },
918
925
  },
919
926
  };
@@ -1194,7 +1201,10 @@ describe('WorkflowRunner', () => {
1194
1201
  },
1195
1202
  inputs: {
1196
1203
  schema: {
1197
- items: { type: 'array', items: { type: 'string' } },
1204
+ type: 'object',
1205
+ properties: {
1206
+ items: { type: 'array', items: { type: 'string' } },
1207
+ },
1198
1208
  },
1199
1209
  },
1200
1210
  };
@@ -1693,7 +1703,8 @@ describe('WorkflowRunner', () => {
1693
1703
  outputs: { total: '=$output.count_step.total' },
1694
1704
  inputs: {
1695
1705
  schema: {
1696
- amount: { type: 'number' },
1706
+ type: 'object',
1707
+ properties: { amount: { type: 'number' } },
1697
1708
  },
1698
1709
  },
1699
1710
  };
@@ -1773,4 +1784,268 @@ describe('WorkflowRunner', () => {
1773
1784
  expect(record?.context?.before).not.toHaveProperty('secret');
1774
1785
  expect(record?.context?.after).not.toHaveProperty('secret');
1775
1786
  });
1787
+ it('parses a start without input data as an empty input', async () => {
1788
+ const action = defineAction({
1789
+ name: 'echo_action',
1790
+ execute: async () => ({ ok: true }),
1791
+ });
1792
+ const compiled = compileWorkflow(
1793
+ {
1794
+ inputs: {
1795
+ schema: { type: 'object', properties: { name: { type: 'string' } } },
1796
+ },
1797
+ defs: createTaskDefs({ echo: { action: 'echo_action' } }),
1798
+ flow: [{ do: 'echo' }],
1799
+ outputs: { input: '=$input' },
1800
+ },
1801
+ { actions: { echo_action: action } },
1802
+ );
1803
+ const runner = new WorkflowRunner(compiled);
1804
+ const result = await runner.start({
1805
+ inputData: undefined,
1806
+ context: new TestContext({}),
1807
+ });
1808
+
1809
+ expect(result).toEqual(
1810
+ expect.objectContaining({ status: 'finished', output: { input: {} } }),
1811
+ );
1812
+ expect(runner.getState()).toEqual({
1813
+ input: {},
1814
+ output: { echo: { ok: true } },
1815
+ iterationStack: [],
1816
+ });
1817
+ });
1818
+
1819
+ it('applies the default values of the input schema to $input', async () => {
1820
+ const action = defineAction({
1821
+ name: 'echo_action',
1822
+ execute: async () => ({ ok: true }),
1823
+ });
1824
+ const compiled = compileWorkflow(
1825
+ {
1826
+ inputs: {
1827
+ schema: {
1828
+ type: 'object',
1829
+ properties: {
1830
+ name: { type: 'string' },
1831
+ pages: { type: 'integer', default: 2 },
1832
+ },
1833
+ required: ['name'],
1834
+ },
1835
+ },
1836
+ defs: createTaskDefs({ echo: { action: 'echo_action' } }),
1837
+ flow: [{ do: 'echo' }],
1838
+ outputs: { input: '=$input' },
1839
+ },
1840
+ { actions: { echo_action: action } },
1841
+ );
1842
+ const result = await new WorkflowRunner(compiled).start({
1843
+ inputData: { name: 'Ada', extra: true },
1844
+ context: new TestContext({}),
1845
+ });
1846
+
1847
+ expect(result).toEqual(
1848
+ expect.objectContaining({
1849
+ status: 'finished',
1850
+ output: { input: { name: 'Ada', pages: 2, extra: true } },
1851
+ }),
1852
+ );
1853
+ });
1854
+
1855
+ it('refuses an input that does not match the input schema, without starting', async () => {
1856
+ const execute = jest.fn(async () => ({ ok: true }));
1857
+ const action = defineAction({ name: 'echo_action', execute });
1858
+ const compiled = compileWorkflow(
1859
+ {
1860
+ inputs: {
1861
+ schema: {
1862
+ type: 'object',
1863
+ properties: {
1864
+ name: { type: 'string' },
1865
+ pages: { type: 'integer' },
1866
+ },
1867
+ required: ['name'],
1868
+ additionalProperties: false,
1869
+ },
1870
+ },
1871
+ defs: createTaskDefs({ echo: { action: 'echo_action' } }),
1872
+ flow: [{ do: 'echo' }],
1873
+ outputs: {},
1874
+ },
1875
+ { actions: { echo_action: action } },
1876
+ );
1877
+ const emitter = new WorkflowEventEmitter();
1878
+ const events: string[] = [];
1879
+ emitter.on('hook:workflow:start', () => events.push('start'));
1880
+ emitter.on('hook:workflow:failure', () => events.push('failure'));
1881
+ const context = new TestContext({});
1882
+ context.eventEmitter = emitter;
1883
+ const runner = new WorkflowRunner(compiled);
1884
+ const statusBefore = runner.getStatus();
1885
+ const started = runner.start({
1886
+ inputData: { pages: 'two', extra: true },
1887
+ context,
1888
+ });
1889
+
1890
+ await expect(started).rejects.toBeInstanceOf(WorkflowInputRejectedError);
1891
+ await expect(started).rejects.toMatchObject({
1892
+ name: 'WorkflowInputRejectedError',
1893
+ message:
1894
+ 'Workflow input was rejected: ' +
1895
+ 'name: Invalid input: expected string, received undefined; ' +
1896
+ 'pages: Invalid input: expected number, received string; ' +
1897
+ '(root): Unrecognized key: "extra"',
1898
+ issues: [
1899
+ 'name: Invalid input: expected string, received undefined',
1900
+ 'pages: Invalid input: expected number, received string',
1901
+ '(root): Unrecognized key: "extra"',
1902
+ ],
1903
+ });
1904
+ expect(runner.getStatus()).toBe(statusBefore);
1905
+ expect(runner.getState()).toBeUndefined();
1906
+ expect(events).toEqual([]);
1907
+ expect(execute).not.toHaveBeenCalled();
1908
+ });
1909
+
1910
+ it('hands out copies of its step records', async () => {
1911
+ const action = defineAction({
1912
+ name: 'echo_action',
1913
+ execute: async () => ({ ok: true }),
1914
+ });
1915
+ const compiled = compileWorkflow(
1916
+ {
1917
+ defs: createTaskDefs({ echo: { action: 'echo_action' } }),
1918
+ flow: [{ do: 'echo' }],
1919
+ outputs: {},
1920
+ },
1921
+ { actions: { echo_action: action } },
1922
+ );
1923
+ const runner = new WorkflowRunner(compiled);
1924
+ const events: Array<WorkflowEventMap['hook:step:success']> = [];
1925
+ const context = new TestContext({ count: 1 });
1926
+ context.eventEmitter.on('hook:step:success', (payload) =>
1927
+ events.push(payload),
1928
+ );
1929
+
1930
+ await runner.start({ inputData: {}, context });
1931
+
1932
+ // The copies are shallow: their own record, context and error objects.
1933
+ const record = runner.getStepLog()['0:echo'];
1934
+ record.status = 'failed';
1935
+ record.context!.after = { count: 2 };
1936
+ events[0].stepExecution!.context!.before = { count: 3 };
1937
+
1938
+ expect(runner.getStepLog()['0:echo']).toEqual(
1939
+ expect.objectContaining({
1940
+ status: 'completed',
1941
+ context: { before: { count: 1 }, after: { count: 1 } },
1942
+ }),
1943
+ );
1944
+ });
1945
+ it('keeps the error of a failed step in its step record', async () => {
1946
+ const action = defineAction({
1947
+ name: 'boom_action',
1948
+ execute: async () => {
1949
+ throw new Error('boom');
1950
+ },
1951
+ });
1952
+ const compiled = compileWorkflow(
1953
+ {
1954
+ defs: createTaskDefs({ boom: { action: 'boom_action' } }),
1955
+ flow: [{ do: 'boom' }],
1956
+ outputs: {},
1957
+ },
1958
+ { actions: { boom_action: action } },
1959
+ );
1960
+ const runner = new WorkflowRunner(compiled);
1961
+
1962
+ await expect(
1963
+ runner.start({ inputData: {}, context: new TestContext({}) }),
1964
+ ).resolves.toEqual(expect.objectContaining({ status: 'failed' }));
1965
+
1966
+ const record = runner.getStepLog()['0:boom'];
1967
+ expect(record).toEqual(
1968
+ expect.objectContaining({
1969
+ status: 'failed',
1970
+ error: { message: 'boom', stack: expect.any(String) },
1971
+ }),
1972
+ );
1973
+ record.error!.message = 'changed';
1974
+ expect(runner.getStepLog()['0:boom'].error?.message).toBe('boom');
1975
+ });
1976
+
1977
+ it('leaves the error of a step record unset when the step did not fail', async () => {
1978
+ const action = defineAction({
1979
+ name: 'echo_action',
1980
+ execute: async () => ({ ok: true }),
1981
+ });
1982
+ const compiled = compileWorkflow(
1983
+ {
1984
+ defs: createTaskDefs({ echo: { action: 'echo_action' } }),
1985
+ flow: [{ do: 'echo' }],
1986
+ outputs: {},
1987
+ },
1988
+ { actions: { echo_action: action } },
1989
+ );
1990
+ const runner = new WorkflowRunner(compiled);
1991
+
1992
+ await runner.start({ inputData: {}, context: new TestContext({}) });
1993
+
1994
+ expect(runner.getStepLog()['0:echo']).toHaveProperty('error', undefined);
1995
+ });
1996
+ it('records the cancelled loser of a restored wait_any run without context', async () => {
1997
+ const ask = defineAction<{ label: string }, unknown, TestContext, Settings>(
1998
+ {
1999
+ name: 'ask',
2000
+ inputSchema: z.object({ label: z.string() }),
2001
+ execute: async ({ context }) =>
2002
+ context.workflow.suspend({ reason: 'reply' }),
2003
+ },
2004
+ );
2005
+ const compiled = compileWorkflow(
2006
+ {
2007
+ defs: createTaskDefs({
2008
+ ask_a: { action: 'ask', inputs: { label: 'a' } },
2009
+ ask_b: { action: 'ask', inputs: { label: 'b' } },
2010
+ }),
2011
+ flow: [
2012
+ {
2013
+ parallel: {
2014
+ strategy: 'wait_any',
2015
+ steps: [{ do: 'ask_a' }, { do: 'ask_b' }],
2016
+ },
2017
+ },
2018
+ ],
2019
+ outputs: {},
2020
+ },
2021
+ { actions: { ask } },
2022
+ );
2023
+ const started = await new WorkflowRunner(compiled).start({
2024
+ inputData: {},
2025
+ context: new TestContext({}),
2026
+ });
2027
+ if (started.status !== 'suspended') {
2028
+ throw new Error('Expected the run to suspend');
2029
+ }
2030
+
2031
+ // A restored runner starts without the step records of the first pass.
2032
+ const restored = WorkflowRunner.fromCheckpoint(compiled, {
2033
+ checkpoint: persist(started.checkpoint),
2034
+ context: new TestContext({}),
2035
+ });
2036
+ const resumed = await restored.resume({
2037
+ waitId: started.waits[1].waitId,
2038
+ resumeData: 'b',
2039
+ });
2040
+
2041
+ expect(resumed.status).toBe('finished');
2042
+ const loser = restored.getStepLog()['0.parallel.0:ask_a'];
2043
+ expect(loser).toEqual(
2044
+ expect.objectContaining({
2045
+ status: 'cancelled',
2046
+ error: expect.any(Object),
2047
+ }),
2048
+ );
2049
+ expect(loser).toHaveProperty('context', undefined);
2050
+ });
1776
2051
  });
@@ -174,4 +174,17 @@ describe('workflow values', () => {
174
174
  },
175
175
  });
176
176
  });
177
+ it('merges nested objects only, letting other overrides replace the default', () => {
178
+ expect(
179
+ mergeSettings(
180
+ { a: 'text', b: { keep: 1, swap: 1 }, c: [1, 2], d: { x: 1 } },
181
+ { a: { nested: true }, b: { swap: 2 }, c: [3], d: 'flat' },
182
+ ),
183
+ ).toEqual({
184
+ a: { nested: true },
185
+ b: { keep: 1, swap: 2 },
186
+ c: [3],
187
+ d: 'flat',
188
+ });
189
+ });
177
190
  });
@@ -89,7 +89,8 @@ describe('Workflow execution', () => {
89
89
  },
90
90
  inputs: {
91
91
  schema: {
92
- name: { type: 'string' },
92
+ type: 'object',
93
+ properties: { name: { type: 'string' } },
93
94
  },
94
95
  },
95
96
  };
@@ -181,7 +182,8 @@ describe('Workflow execution', () => {
181
182
  outputs: { result: '=$output.double_step.doubled' },
182
183
  inputs: {
183
184
  schema: {
184
- value: { type: 'number' },
185
+ type: 'object',
186
+ properties: { value: { type: 'number' } },
185
187
  },
186
188
  },
187
189
  };
@@ -180,4 +180,96 @@ describe('AbstractAction timing and retries', () => {
180
180
  expect(randomSpy).toHaveBeenCalled();
181
181
  expect(attemptTimestamps[1] - attemptTimestamps[0]).toBe(150);
182
182
  });
183
+ it('runs once without a retries block', async () => {
184
+ const execute = jest.fn().mockRejectedValue(new Error('Boom'));
185
+ const action = new HarnessedAction(execute);
186
+
187
+ await expect(action.run({ value: 1 }, new TestContext())).rejects.toThrow(
188
+ 'Boom',
189
+ );
190
+ expect(execute).toHaveBeenCalledTimes(1);
191
+ });
192
+
193
+ it('runs once when retries are disabled, whatever max_attempts says', async () => {
194
+ const execute = jest.fn().mockRejectedValue(new Error('Boom'));
195
+ const action = new HarnessedAction(execute);
196
+
197
+ await expect(
198
+ action.run({ value: 1 }, new TestContext(), {
199
+ retries: { enabled: false, max_attempts: 3, backoff_ms: 0 },
200
+ } as Partial<Settings>),
201
+ ).rejects.toThrow('Boom');
202
+ expect(execute).toHaveBeenCalledTimes(1);
203
+ });
204
+
205
+ it('retries when a retries block leaves enabled out', async () => {
206
+ const execute = jest
207
+ .fn()
208
+ .mockRejectedValueOnce(new Error('Boom'))
209
+ .mockRejectedValueOnce(new Error('Boom'))
210
+ .mockResolvedValue({ result: 3 });
211
+ const action = new HarnessedAction(execute);
212
+
213
+ await expect(
214
+ action.run({ value: 1 }, new TestContext(), {
215
+ retries: { max_attempts: 3, backoff_ms: 0 },
216
+ } as Partial<Settings>),
217
+ ).resolves.toEqual({ result: 3 });
218
+ expect(execute).toHaveBeenCalledTimes(3);
219
+ });
220
+
221
+ it('gives up after max_attempts and throws the last error', async () => {
222
+ const execute = jest
223
+ .fn()
224
+ .mockRejectedValueOnce(new Error('First'))
225
+ .mockRejectedValueOnce(new Error('Last'));
226
+ const action = new HarnessedAction(execute);
227
+
228
+ await expect(
229
+ action.run({ value: 1 }, new TestContext(), {
230
+ retries: { max_attempts: 2, backoff_ms: 0 },
231
+ } as Partial<Settings>),
232
+ ).rejects.toThrow('Last');
233
+ expect(execute).toHaveBeenCalledTimes(2);
234
+ });
235
+
236
+ it('retries right away when the jittered delay rounds to zero', async () => {
237
+ jest.useFakeTimers();
238
+ jest.spyOn(Math, 'random').mockReturnValue(0);
239
+ const execute = jest
240
+ .fn()
241
+ .mockRejectedValueOnce(new Error('Boom'))
242
+ .mockResolvedValue({ result: 2 });
243
+ const action = new HarnessedAction(execute);
244
+
245
+ // A jitter of 1 with Math.random() at 0 scales the delay by 0.
246
+ await expect(
247
+ action.run({ value: 1 }, new TestContext(), {
248
+ retries: { max_attempts: 2, backoff_ms: 100, jitter: 1 },
249
+ } as Partial<Settings>),
250
+ ).resolves.toEqual({ result: 2 });
251
+ expect(execute).toHaveBeenCalledTimes(2);
252
+ });
253
+
254
+ it('stops retrying once the signal is aborted', async () => {
255
+ jest.useFakeTimers();
256
+ const controller = new AbortController();
257
+ const execute = jest.fn().mockRejectedValue(new Error('Boom'));
258
+ const action = new HarnessedAction(execute);
259
+ const runPromise = action.run(
260
+ { value: 1 },
261
+ new TestContext(),
262
+ {
263
+ retries: { max_attempts: 3, backoff_ms: 100 },
264
+ } as Partial<Settings>,
265
+ undefined,
266
+ controller.signal,
267
+ );
268
+ const outcome = expect(runPromise).rejects.toThrow('stopped');
269
+
270
+ await jest.advanceTimersByTimeAsync(50);
271
+ controller.abort(new Error('stopped'));
272
+ await outcome;
273
+ expect(execute).toHaveBeenCalledTimes(1);
274
+ });
183
275
  });
@@ -26,6 +26,55 @@ import {
26
26
 
27
27
  const BASE_SETTINGS_KEYS = Object.keys(BaseSettingsSchema.shape);
28
28
 
29
+ type RetryPolicy = {
30
+ maxAttempts: number;
31
+ backoffMs: number;
32
+ maxDelayMs: number;
33
+ jitter: number;
34
+ multiplier: number;
35
+ };
36
+
37
+ /**
38
+ * Read the retry settings of a run. Without a `retries` block an action runs
39
+ * once; a block that leaves `enabled` out turns retries on.
40
+ */
41
+ const resolveRetryPolicy = (
42
+ retries: RuntimeSettings['retries'],
43
+ ): RetryPolicy => {
44
+ if (!retries) {
45
+ return {
46
+ maxAttempts: 1,
47
+ backoffMs: 0,
48
+ maxDelayMs: 0,
49
+ jitter: 0,
50
+ multiplier: 1,
51
+ };
52
+ }
53
+
54
+ return {
55
+ maxAttempts: (retries.enabled ?? true) ? retries.max_attempts : 1,
56
+ backoffMs: retries.backoff_ms ?? 0,
57
+ maxDelayMs: retries.max_delay_ms,
58
+ jitter: retries.jitter,
59
+ multiplier: retries.multiplier,
60
+ };
61
+ };
62
+ /** Cap a retry delay at the policy's `max_delay_ms`, when one is set. */
63
+ const capDelay = (delay: number, { maxDelayMs }: RetryPolicy): number =>
64
+ maxDelayMs > 0 ? Math.min(delay, maxDelayMs) : delay;
65
+ /** Pause before the next attempt: the delay, capped, then spread by the jitter. */
66
+ const retryPause = (delay: number, policy: RetryPolicy): number => {
67
+ const cappedDelay = capDelay(delay, policy);
68
+ if (cappedDelay <= 0) {
69
+ return 0;
70
+ }
71
+
72
+ const jitterFactor =
73
+ policy.jitter > 0 ? 1 + (Math.random() * 2 - 1) * policy.jitter : 1;
74
+
75
+ return Math.max(0, Math.round(cappedDelay * jitterFactor));
76
+ };
77
+
29
78
  /**
30
79
  * Base implementation that enforces schema-validated input/output.
31
80
  */
@@ -98,11 +147,10 @@ export abstract class AbstractAction<
98
147
  }
99
148
 
100
149
  /**
101
- * Executes the action with retry, timeout, and schema safety.
150
+ * Parses settings over the base execution settings (timeout, retries).
102
151
  *
103
- * @param payload - Raw input being provided to the action.
104
- * @returns Validated output produced by the action.
105
- * @throws Error when retries are exhausted or validation fails.
152
+ * @param payload - Raw settings of the task.
153
+ * @returns Settings typed as `RuntimeSettings<S>` after schema validation.
106
154
  */
107
155
  parseSettings(payload: unknown): RuntimeSettings<S> {
108
156
  const settings = z
@@ -112,6 +160,13 @@ export abstract class AbstractAction<
112
160
  return (settings ?? {}) as RuntimeSettings<S>;
113
161
  }
114
162
 
163
+ /**
164
+ * Executes the action with retry, timeout, and schema safety.
165
+ *
166
+ * @param payload - Raw input being provided to the action.
167
+ * @returns Validated output produced by the action.
168
+ * @throws Error when retries are exhausted or validation fails.
169
+ */
115
170
  async run(
116
171
  payload: unknown,
117
172
  context: C,
@@ -124,22 +179,8 @@ export abstract class AbstractAction<
124
179
  const parsedBindings = (bindings ?? {}) as B;
125
180
  this.assertSupportedBindings(parsedBindings);
126
181
  const timeoutMs = parsedSettings.timeout_ms ?? 0;
127
- const retrySettings = parsedSettings.retries ?? {
128
- enabled: false,
129
- max_attempts: 1,
130
- backoff_ms: 0,
131
- max_delay_ms: 0,
132
- jitter: 0,
133
- multiplier: 1,
134
- };
135
- const retriesEnabled = retrySettings.enabled ?? true;
136
- const maxAttempts = retriesEnabled ? retrySettings.max_attempts : 1;
137
-
138
- let attempt = 0;
139
- let currentDelay = retrySettings.backoff_ms ?? 0;
140
- const maxDelayMs = retrySettings.max_delay_ms;
141
- const jitter = retrySettings.jitter;
142
- const multiplier = retrySettings.multiplier;
182
+ const retryPolicy = resolveRetryPolicy(parsedSettings.retries);
183
+ let delay = retryPolicy.backoffMs;
143
184
  // Suspend keys are positional within the body, so every attempt has to
144
185
  // start from where this run did: otherwise a retry asks for `index:2`
145
186
  // where the first attempt resolved `index:1`, and the step suspends on a
@@ -148,7 +189,7 @@ export abstract class AbstractAction<
148
189
  ?.getWorkflowRuntime?.()
149
190
  ?.markSuspendCursor?.();
150
191
 
151
- while (attempt < maxAttempts) {
192
+ for (let attempt = 1; attempt <= retryPolicy.maxAttempts; attempt += 1) {
152
193
  if (signal) {
153
194
  throwIfAborted(signal);
154
195
  }
@@ -170,36 +211,22 @@ export abstract class AbstractAction<
170
211
 
171
212
  return this.parseOutput(result);
172
213
  } catch (error) {
173
- attempt += 1;
174
-
175
214
  // A retry would read the same refused resume payload again, or replay
176
215
  // the same body into the same mismatch with what it recorded.
177
216
  if (
178
- attempt >= maxAttempts ||
217
+ attempt >= retryPolicy.maxAttempts ||
179
218
  isWorkflowResumeRejectedError(error) ||
180
219
  isNonDeterministicWorkflowError(error)
181
220
  ) {
182
221
  throw error;
183
222
  }
184
223
 
185
- let delay = currentDelay;
186
- if (maxDelayMs > 0) {
187
- delay = Math.min(delay, maxDelayMs);
188
- }
189
-
190
- if (delay > 0) {
191
- const jitterFactor =
192
- jitter > 0 ? 1 + (Math.random() * 2 - 1) * jitter : 1;
193
- const jitteredDelay = Math.max(0, Math.round(delay * jitterFactor));
194
-
195
- if (jitteredDelay > 0) {
196
- await sleep(jitteredDelay, signal);
197
- }
224
+ const pause = retryPause(delay, retryPolicy);
225
+ if (pause > 0) {
226
+ await sleep(pause, signal);
198
227
  }
199
228
 
200
- const nextDelay = currentDelay * multiplier;
201
- currentDelay =
202
- maxDelayMs > 0 ? Math.min(nextDelay, maxDelayMs) : nextDelay;
229
+ delay = capDelay(delay * retryPolicy.multiplier, retryPolicy);
203
230
  }
204
231
  }
205
232