@hexabot-ai/agentic 3.5.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
@@ -12,12 +12,13 @@ import {
12
12
  mountTaskBindings,
13
13
  validateAndResolveBindings,
14
14
  } from './bindings/base-binding';
15
- import type { BaseWorkflowContext } from './context';
16
15
  import type {
16
+ ConditionalBlock,
17
17
  FlowStep,
18
- InputField,
19
- TaskDefinition,
18
+ LoopStep as LoopBlock,
19
+ ParallelBlock,
20
20
  WorkflowDefinition,
21
+ WorkflowInputSchema,
21
22
  } from './dsl.types';
22
23
  import { extractTaskDefinitions as extractTaskDefinitionsFromDefs } from './dsl.types';
23
24
  import { issueMessages } from './validation-issue';
@@ -27,7 +28,7 @@ import type {
27
28
  CompiledStep,
28
29
  CompiledTask,
29
30
  CompiledWorkflow,
30
- ConditionalBranch,
31
+ ConditionalStep,
31
32
  LoopStep,
32
33
  ParallelStep,
33
34
  } from './workflow-types';
@@ -48,70 +49,25 @@ const buildStepId = (path: Array<number | string>, label: string): string => {
48
49
 
49
50
  return `${pathPart}:${label}`;
50
51
  };
51
- /** Convert workflow input field metadata to a zod schema. */
52
- const inputFieldToZod = (field: InputField): ZodType => {
53
- let schema: ZodType;
54
52
 
55
- switch (field.type) {
56
- case 'string':
57
- schema = z.string();
58
- break;
59
- case 'number':
60
- schema = z.number();
61
- break;
62
- case 'integer':
63
- schema = z.int();
64
- break;
65
- case 'boolean':
66
- schema = z.boolean();
67
- break;
68
- case 'array':
69
- schema = z.array(field.items ? inputFieldToZod(field.items) : z.any());
70
- break;
71
- case 'object': {
72
- const properties: Record<string, ZodType> = {};
73
- if (field.properties) {
74
- for (const [name, child] of Object.entries(field.properties)) {
75
- properties[name] = inputFieldToZod(child).optional();
76
- }
77
- }
78
- schema =
79
- Object.keys(properties).length > 0
80
- ? z.strictObject(properties).partial()
81
- : z.record(z.string(), z.any());
82
- break;
83
- }
84
- default:
85
- schema = z.any();
86
- }
87
-
88
- if (field.enum) {
89
- schema = schema.refine(
90
- (value) => field.enum?.some((allowed) => allowed === value),
91
- {
92
- message: `Value must be one of: ${field.enum.join(', ')}`,
93
- },
94
- );
95
- }
96
-
97
- return schema;
98
- };
99
- /** Assemble a parser for the workflow top-level input payload. */
100
- const buildInputParser = (
101
- schema?: Record<string, InputField>,
102
- ): ZodType<Record<string, unknown>> => {
103
- if (!schema || Object.keys(schema).length === 0) {
104
- return z.looseObject({});
105
- }
106
-
107
- const shape: Record<string, ZodType> = {};
108
-
109
- for (const [name, field] of Object.entries(schema)) {
110
- shape[name] = inputFieldToZod(field).optional();
111
- }
112
-
113
- return z.strictObject(shape).partial();
114
- };
53
+ /**
54
+ * Build the parser of a workflow's input payload from its `inputs.schema`.
55
+ *
56
+ * This is the one conversion from that JSON Schema to a parser: the runner
57
+ * uses it when a run starts, and a host that checks an input before creating
58
+ * a run should use it too, so both accept and refuse the same payloads. The
59
+ * parser applies the schema's `default` values.
60
+ *
61
+ * @param schema The JSON Schema under `inputs.schema`, when one is declared.
62
+ * @returns A parser of the input payload; it accepts any object without a schema.
63
+ * @throws When the schema is not a JSON Schema zod can read.
64
+ */
65
+ export const buildWorkflowInputParser = (
66
+ schema?: WorkflowInputSchema,
67
+ ): ZodType<Record<string, unknown>> =>
68
+ schema
69
+ ? (z.fromJSONSchema(schema) as ZodType<Record<string, unknown>>)
70
+ : z.looseObject({});
115
71
  /** Compile a raw mapping object into expression-aware value mappings. */
116
72
  const compileMapping = (
117
73
  values?: Record<string, unknown>,
@@ -128,24 +84,6 @@ const compileMapping = (
128
84
  ]),
129
85
  );
130
86
  };
131
- /** Ensure every task references a provided action implementation. */
132
- const assertActionsBound = (
133
- tasks: Record<string, TaskDefinition>,
134
- actions: Record<string, Action<unknown, unknown, BaseWorkflowContext>>,
135
- ) => {
136
- const missing = Object.values(tasks)
137
- .map((task) => task.action)
138
- .filter(
139
- (actionName) =>
140
- !Object.prototype.hasOwnProperty.call(actions, actionName),
141
- );
142
-
143
- if (missing.length > 0) {
144
- throw new Error(
145
- `No action implementations provided for: ${missing.join(', ')}`,
146
- );
147
- }
148
- };
149
87
  /** Parse settings, compile inputs, and bind actions for each task. */
150
88
  const compileTasks = (
151
89
  definition: WorkflowDefinition,
@@ -165,8 +103,6 @@ const compileTasks = (
165
103
  );
166
104
  }
167
105
 
168
- assertActionsBound(taskDefinitions, options.actions);
169
-
170
106
  for (const [taskName, task] of Object.entries(taskDefinitions)) {
171
107
  const action = options.actions[task.action];
172
108
  const settingsPayload = mergeSettings(defaultSettings, task.settings);
@@ -195,111 +131,113 @@ const compileFlowSteps = (
195
131
  path: Array<number | string> = [],
196
132
  options?: WorkflowCompileOptions,
197
133
  ): CompiledStep[] =>
198
- steps.map<CompiledStep>((step, index) => {
199
- const stepPath = [...path, index];
200
-
201
- if ('do' in step) {
202
- const label = step.do;
203
-
204
- return {
205
- type: StepType.Task,
206
- id: buildStepId(stepPath, step.do),
207
- label,
208
- taskName: step.do,
209
- };
210
- }
211
-
212
- if ('parallel' in step) {
213
- const label = step.parallel.description ?? 'parallel';
214
-
215
- return {
216
- type: StepType.Parallel,
217
- id: buildStepId(stepPath, 'parallel'),
218
- label,
219
- description: step.parallel.description,
220
- strategy: step.parallel.strategy ?? 'wait_all',
221
- steps: compileFlowSteps(
222
- step.parallel.steps,
223
- [...stepPath, 'parallel'],
224
- options,
225
- ),
226
- } as ParallelStep;
227
- }
134
+ steps.map((step, index) => compileFlowStep(step, [...path, index], options));
135
+ const compileFlowStep = (
136
+ step: FlowStep,
137
+ stepPath: Array<number | string>,
138
+ options?: WorkflowCompileOptions,
139
+ ): CompiledStep => {
140
+ if ('do' in step) {
141
+ return {
142
+ type: StepType.Task,
143
+ id: buildStepId(stepPath, step.do),
144
+ label: step.do,
145
+ taskName: step.do,
146
+ };
147
+ }
228
148
 
229
- if ('conditional' in step) {
230
- const label = step.conditional.description ?? 'conditional';
231
- const branches: ConditionalBranch[] = step.conditional.when.map(
232
- (branch, branchIdx) => ({
233
- id: buildStepId([...stepPath, 'branch', branchIdx], 'conditional'),
234
- condition:
235
- 'condition' in branch
236
- ? compileValue(branch.condition, options)
237
- : undefined,
238
- steps: compileFlowSteps(
239
- branch.steps,
240
- [...stepPath, 'branch', branchIdx],
241
- options,
242
- ),
243
- }),
244
- );
149
+ if ('parallel' in step) {
150
+ return compileParallelStep(step.parallel, stepPath, options);
151
+ }
245
152
 
246
- return {
247
- type: StepType.Conditional,
248
- id: buildStepId(stepPath, 'conditional'),
249
- label,
250
- description: step.conditional.description,
251
- branches,
252
- };
253
- }
153
+ if ('conditional' in step) {
154
+ return compileConditionalStep(step.conditional, stepPath, options);
155
+ }
254
156
 
255
- const loop = step.loop;
256
- const label = loop.name ?? 'loop';
257
- const commonLoop = {
258
- type: StepType.Loop,
259
- id: buildStepId(stepPath, label),
260
- label,
261
- name: loop.name,
262
- description: loop.description,
263
- accumulate: loop.accumulate
264
- ? {
265
- as: loop.accumulate.as,
266
- initial: loop.accumulate.initial,
267
- merge: compileValue(loop.accumulate.merge, options),
268
- }
269
- : undefined,
270
- steps: compileFlowSteps(
271
- loop.steps,
272
- [...stepPath, loop.name ?? 'loop'],
273
- options,
274
- ),
275
- } as const;
157
+ return compileLoopStep(step.loop, stepPath, options);
158
+ };
159
+ const compileParallelStep = (
160
+ parallel: ParallelBlock,
161
+ stepPath: Array<number | string>,
162
+ options?: WorkflowCompileOptions,
163
+ ): ParallelStep => ({
164
+ type: StepType.Parallel,
165
+ id: buildStepId(stepPath, 'parallel'),
166
+ label: parallel.description ?? 'parallel',
167
+ description: parallel.description,
168
+ strategy: parallel.strategy ?? 'wait_all',
169
+ steps: compileFlowSteps(parallel.steps, [...stepPath, 'parallel'], options),
170
+ });
171
+ const compileConditionalStep = (
172
+ conditional: ConditionalBlock,
173
+ stepPath: Array<number | string>,
174
+ options?: WorkflowCompileOptions,
175
+ ): ConditionalStep => ({
176
+ type: StepType.Conditional,
177
+ id: buildStepId(stepPath, 'conditional'),
178
+ label: conditional.description ?? 'conditional',
179
+ description: conditional.description,
180
+ branches: conditional.when.map((branch, branchIndex) => {
181
+ const branchPath = [...stepPath, 'branch', branchIndex];
276
182
 
277
- if (loop.type === 'for_each') {
278
- return {
279
- ...commonLoop,
280
- loopType: 'for_each',
281
- forEach: {
282
- item: loop.for_each.item,
283
- in: compileValue(loop.for_each.in, options),
284
- },
285
- maxConcurrency: loop.max_concurrency,
286
- until: loop.until ? compileValue(loop.until, options) : undefined,
287
- } as LoopStep;
288
- }
183
+ return {
184
+ id: buildStepId(branchPath, 'conditional'),
185
+ condition:
186
+ 'condition' in branch
187
+ ? compileValue(branch.condition, options)
188
+ : undefined,
189
+ steps: compileFlowSteps(branch.steps, branchPath, options),
190
+ };
191
+ }),
192
+ });
193
+ const compileLoopStep = (
194
+ loop: LoopBlock,
195
+ stepPath: Array<number | string>,
196
+ options?: WorkflowCompileOptions,
197
+ ): LoopStep => {
198
+ const label = loop.name ?? 'loop';
199
+ const common = {
200
+ type: StepType.Loop,
201
+ id: buildStepId(stepPath, label),
202
+ label,
203
+ name: loop.name,
204
+ description: loop.description,
205
+ accumulate: loop.accumulate
206
+ ? {
207
+ as: loop.accumulate.as,
208
+ initial: loop.accumulate.initial,
209
+ merge: compileValue(loop.accumulate.merge, options),
210
+ }
211
+ : undefined,
212
+ steps: compileFlowSteps(loop.steps, [...stepPath, label], options),
213
+ } as const;
289
214
 
215
+ if (loop.type === 'for_each') {
290
216
  return {
291
- ...commonLoop,
292
- loopType: 'while',
293
- while: compileValue(loop.while, options),
294
- } as LoopStep;
295
- });
217
+ ...common,
218
+ loopType: 'for_each',
219
+ forEach: {
220
+ item: loop.for_each.item,
221
+ in: compileValue(loop.for_each.in, options),
222
+ },
223
+ maxConcurrency: loop.max_concurrency,
224
+ until: loop.until ? compileValue(loop.until, options) : undefined,
225
+ };
226
+ }
227
+
228
+ return {
229
+ ...common,
230
+ loopType: 'while',
231
+ while: compileValue(loop.while, options),
232
+ };
233
+ };
296
234
 
297
235
  /** Compile a workflow definition into structures consumable by the runtime. */
298
236
  export const compileWorkflow = (
299
237
  definition: WorkflowDefinition,
300
238
  options: WorkflowCompileOptions,
301
239
  ): CompiledWorkflow => {
302
- const inputParser = buildInputParser(definition.inputs?.schema);
240
+ const inputParser = buildWorkflowInputParser(definition.inputs?.schema);
303
241
  const tasks = compileTasks(definition, options);
304
242
  const flow = compileFlowSteps(definition.flow, [], options);
305
243
  const outputMapping = compileMapping(definition.outputs, options) ?? {};
@@ -10,6 +10,7 @@ import type {
10
10
  CompiledStep,
11
11
  CompiledValue,
12
12
  CompiledWorkflow,
13
+ LoopStep,
13
14
  } from './workflow-types';
14
15
 
15
16
  /** Separator between fingerprint parts; never produced by the parts themselves. */
@@ -79,23 +80,33 @@ const collectSteps = (
79
80
  }
80
81
  break;
81
82
  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
- }
83
+ parts.push(...describeLoop(step));
94
84
  collectSteps(compiled, step.steps, parts);
95
85
  break;
96
86
  }
97
87
  }
98
88
  };
89
+ /**
90
+ * Describe what drives a loop: its kind, name, accumulator, and items or
91
+ * condition.
92
+ *
93
+ * @param step The loop step.
94
+ * @returns The description fragments, in a fixed order.
95
+ */
96
+ const describeLoop = (step: LoopStep): string[] => [
97
+ step.loopType,
98
+ step.name ?? '',
99
+ step.accumulate
100
+ ? `${step.accumulate.as}=${stringify(step.accumulate.initial)}:${describeValue(step.accumulate.merge)}`
101
+ : '',
102
+ ...(step.loopType === 'for_each'
103
+ ? [
104
+ step.forEach.item,
105
+ describeValue(step.forEach.in),
106
+ describeValue(step.until),
107
+ ]
108
+ : [describeValue(step.while)]),
109
+ ];
99
110
  /**
100
111
  * Describe a compiled mapping in a key-stable order.
101
112
  *
@@ -28,8 +28,8 @@ import {
28
28
  type WorkflowRunStatus,
29
29
  type WorkflowSnapshot,
30
30
  } from './context';
31
- import { throwIfAborted } from './errors';
32
- import { checkResumePayload } from './resume-payload';
31
+ import { throwIfAborted, WorkflowInputRejectedError } from './errors';
32
+ import { checkResumePayload, describeSchemaIssues } from './resume-payload';
33
33
  import { RunnerRuntimeControl } from './runner-runtime-control';
34
34
  import { executeConditional as runConditionalExecutor } from './step-executors/conditional-executor';
35
35
  import { executeLoop as runLoopExecutor } from './step-executors/loop-executor';
@@ -82,6 +82,18 @@ type ResumedRun = {
82
82
  report: RunReport;
83
83
  };
84
84
 
85
+ /** Execution state of the root flow, outside any loop iteration. */
86
+ const rootState = (
87
+ input: Record<string, unknown>,
88
+ output: Record<string, unknown>,
89
+ ): ExecutionState => ({ input, output, iterationStack: [] });
90
+ /** Copy a step record, so callers cannot change the one the runner keeps. */
91
+ const copyStepRecord = (record: StepExecutionRecord): StepExecutionRecord => ({
92
+ ...record,
93
+ context: record.context ? { ...record.context } : undefined,
94
+ error: record.error ? { ...record.error } : undefined,
95
+ });
96
+
85
97
  /**
86
98
  * Executes a compiled workflow definition, tracking state, suspensions, and event hooks.
87
99
  * Create a new instance per execution to avoid leaking state between runs.
@@ -164,11 +176,7 @@ export class WorkflowRunner {
164
176
  return Object.fromEntries(
165
177
  Object.entries(this.stepLog).map(([id, record]) => [
166
178
  id,
167
- {
168
- ...record,
169
- context: record.context ? { ...record.context } : undefined,
170
- error: record.error ? { ...record.error } : undefined,
171
- },
179
+ copyStepRecord(record),
172
180
  ]),
173
181
  );
174
182
  }
@@ -189,18 +197,23 @@ export class WorkflowRunner {
189
197
  *
190
198
  * @param args Input payload and context to seed execution.
191
199
  * @returns Execution result including status and snapshot.
200
+ * @throws {WorkflowInputRejectedError} When the input payload does not match
201
+ * the workflow's `inputs.schema`; nothing ran and the runner is unchanged.
192
202
  */
193
203
  async start(args: RunnerStartArgs): Promise<WorkflowRunResult> {
204
+ const input = this.compiled.inputParser.safeParse(args.inputData ?? {});
205
+ if (!input.success) {
206
+ throw new WorkflowInputRejectedError(
207
+ describeSchemaIssues(input.error.issues),
208
+ );
209
+ }
210
+
194
211
  this.status = EWorkflowRunStatus.RUNNING;
195
212
  this.snapshots = {};
196
213
  this.stepLog = {};
197
214
  this.checkpoint = undefined;
198
215
  this.context = args.context;
199
- this.state = {
200
- input: this.compiled.inputParser.parse(args.inputData ?? {}),
201
- output: {},
202
- iterationStack: [],
203
- };
216
+ this.state = rootState(input.data, {});
204
217
 
205
218
  this.runtimeControl = new RunnerRuntimeControl();
206
219
  this.context.attachWorkflowRuntime(this.runtimeControl);
@@ -308,11 +321,7 @@ export class WorkflowRunner {
308
321
  // copy, so both see exactly what a host would have persisted.
309
322
  const from = resumed ? cloneAsJson(resumed.checkpoint) : undefined;
310
323
  if (from) {
311
- this.state = {
312
- input: from.input,
313
- output: from.output,
314
- iterationStack: [],
315
- };
324
+ this.state = rootState(from.input, from.output);
316
325
  }
317
326
 
318
327
  const state = this.state;
@@ -474,11 +483,7 @@ export class WorkflowRunner {
474
483
  });
475
484
 
476
485
  runner.checkpoint = checkpoint;
477
- runner.state = {
478
- input: checkpoint.input,
479
- output: checkpoint.output,
480
- iterationStack: [],
481
- };
486
+ runner.state = rootState(checkpoint.input, checkpoint.output);
482
487
  runner.context = options.context;
483
488
  runner.snapshots = { ...(options.snapshot?.actions ?? {}) };
484
489
  runner.status = EWorkflowRunStatus.SUSPENDED;
@@ -590,11 +595,7 @@ export class WorkflowRunner {
590
595
 
591
596
  this.stepLog[step.id] = nextRecord;
592
597
 
593
- return {
594
- ...nextRecord,
595
- context: nextRecord.context ? { ...nextRecord.context } : undefined,
596
- error: nextRecord.error ? { ...nextRecord.error } : undefined,
597
- };
598
+ return copyStepRecord(nextRecord);
598
599
  }
599
600
 
600
601
  /**
@@ -8,6 +8,7 @@ import type { Expression } from 'jsonata';
8
8
  import jsonata from 'jsonata';
9
9
 
10
10
  import type { JsonValue, Settings } from './dsl.types';
11
+ import { isRecord } from './utils/clone';
11
12
  import type {
12
13
  CompiledMapping,
13
14
  CompiledValue,
@@ -25,16 +26,17 @@ export type CompileValueOptions = {
25
26
  jsonataFunctions?: JsonataFunctionRegistry;
26
27
  };
27
28
 
28
- /** Basic object guard that rejects arrays and null. */
29
- const isPlainObject = (value: unknown): value is Record<string, unknown> =>
30
- typeof value === 'object' && value !== null && !Array.isArray(value);
29
+ /** Strings starting with `=` are JSONata expressions; anything else is a literal. */
30
+ export const isExpressionString = (value: unknown): value is string =>
31
+ typeof value === 'string' && value.startsWith('=');
32
+
31
33
  const resolveNestedExpressions = async (
32
34
  value: unknown,
33
35
  scope: EvaluationScope,
34
36
  jsonataFunctions?: JsonataFunctionRegistry,
35
37
  seen: WeakSet<object> = new WeakSet(),
36
38
  ): Promise<unknown> => {
37
- if (typeof value === 'string' && value.startsWith('=')) {
39
+ if (isExpressionString(value)) {
38
40
  return evaluateValue(compileValue(value, { jsonataFunctions }), scope);
39
41
  }
40
42
 
@@ -51,7 +53,7 @@ const resolveNestedExpressions = async (
51
53
  );
52
54
  }
53
55
 
54
- if (isPlainObject(value)) {
56
+ if (isRecord(value)) {
55
57
  if (seen.has(value)) {
56
58
  return value;
57
59
  }
@@ -106,7 +108,7 @@ export const compileValue = (
106
108
  ): CompiledValue => {
107
109
  const jsonataFunctions = options?.jsonataFunctions;
108
110
 
109
- if (typeof value === 'string' && value.startsWith('=')) {
111
+ if (isExpressionString(value)) {
110
112
  const expression = jsonata(value.slice(1));
111
113
  registerJsonataFunctions(expression, jsonataFunctions);
112
114
 
@@ -187,7 +189,7 @@ export const mergeSettings = (
187
189
  const value = override[key];
188
190
  const previous = merged[key];
189
191
 
190
- if (isPlainObject(previous) && isPlainObject(value)) {
192
+ if (isRecord(previous) && isRecord(value)) {
191
193
  merged[key] = mergeSettings(
192
194
  previous as Partial<Settings>,
193
195
  value as Partial<Settings>,