@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
@@ -5,7 +5,7 @@
5
5
  * Full terms: see LICENSE.md.
6
6
  */
7
7
  Object.defineProperty(exports, "__esModule", { value: true });
8
- exports.compileWorkflow = void 0;
8
+ exports.compileWorkflow = exports.buildWorkflowInputParser = void 0;
9
9
  const zod_1 = require("zod");
10
10
  const base_binding_1 = require("./bindings/base-binding");
11
11
  const dsl_types_1 = require("./dsl.types");
@@ -17,59 +17,22 @@ const buildStepId = (path, label) => {
17
17
  const pathPart = path.length > 0 ? path.join('.') : 'root';
18
18
  return `${pathPart}:${label}`;
19
19
  };
20
- /** Convert workflow input field metadata to a zod schema. */
21
- const inputFieldToZod = (field) => {
22
- let schema;
23
- switch (field.type) {
24
- case 'string':
25
- schema = zod_1.z.string();
26
- break;
27
- case 'number':
28
- schema = zod_1.z.number();
29
- break;
30
- case 'integer':
31
- schema = zod_1.z.int();
32
- break;
33
- case 'boolean':
34
- schema = zod_1.z.boolean();
35
- break;
36
- case 'array':
37
- schema = zod_1.z.array(field.items ? inputFieldToZod(field.items) : zod_1.z.any());
38
- break;
39
- case 'object': {
40
- const properties = {};
41
- if (field.properties) {
42
- for (const [name, child] of Object.entries(field.properties)) {
43
- properties[name] = inputFieldToZod(child).optional();
44
- }
45
- }
46
- schema =
47
- Object.keys(properties).length > 0
48
- ? zod_1.z.strictObject(properties).partial()
49
- : zod_1.z.record(zod_1.z.string(), zod_1.z.any());
50
- break;
51
- }
52
- default:
53
- schema = zod_1.z.any();
54
- }
55
- if (field.enum) {
56
- schema = schema.refine((value) => field.enum?.some((allowed) => allowed === value), {
57
- message: `Value must be one of: ${field.enum.join(', ')}`,
58
- });
59
- }
60
- return schema;
61
- };
62
- /** Assemble a parser for the workflow top-level input payload. */
63
- const buildInputParser = (schema) => {
64
- if (!schema || Object.keys(schema).length === 0) {
65
- return zod_1.z.looseObject({});
66
- }
67
- const shape = {};
68
- for (const [name, field] of Object.entries(schema)) {
69
- shape[name] = inputFieldToZod(field).optional();
70
- }
71
- return zod_1.z.strictObject(shape).partial();
72
- };
20
+ /**
21
+ * Build the parser of a workflow's input payload from its `inputs.schema`.
22
+ *
23
+ * This is the one conversion from that JSON Schema to a parser: the runner
24
+ * uses it when a run starts, and a host that checks an input before creating
25
+ * a run should use it too, so both accept and refuse the same payloads. The
26
+ * parser applies the schema's `default` values.
27
+ *
28
+ * @param schema The JSON Schema under `inputs.schema`, when one is declared.
29
+ * @returns A parser of the input payload; it accepts any object without a schema.
30
+ * @throws When the schema is not a JSON Schema zod can read.
31
+ */
32
+ const buildWorkflowInputParser = (schema) => schema
33
+ ? zod_1.z.fromJSONSchema(schema)
34
+ : zod_1.z.looseObject({});
35
+ exports.buildWorkflowInputParser = buildWorkflowInputParser;
73
36
  /** Compile a raw mapping object into expression-aware value mappings. */
74
37
  const compileMapping = (values, options) => {
75
38
  if (!values) {
@@ -80,15 +43,6 @@ const compileMapping = (values, options) => {
80
43
  (0, workflow_values_1.compileValue)(value, options),
81
44
  ]));
82
45
  };
83
- /** Ensure every task references a provided action implementation. */
84
- const assertActionsBound = (tasks, actions) => {
85
- const missing = Object.values(tasks)
86
- .map((task) => task.action)
87
- .filter((actionName) => !Object.prototype.hasOwnProperty.call(actions, actionName));
88
- if (missing.length > 0) {
89
- throw new Error(`No action implementations provided for: ${missing.join(', ')}`);
90
- }
91
- };
92
46
  /** Parse settings, compile inputs, and bind actions for each task. */
93
47
  const compileTasks = (definition, options) => {
94
48
  const compiled = {};
@@ -101,7 +55,6 @@ const compileTasks = (definition, options) => {
101
55
  if (bindingValidation.issues.length > 0) {
102
56
  throw new Error(`Workflow bindings validation failed: ${(0, validation_issue_1.issueMessages)(bindingValidation.issues).join('; ')}`);
103
57
  }
104
- assertActionsBound(taskDefinitions, options.actions);
105
58
  for (const [taskName, task] of Object.entries(taskDefinitions)) {
106
59
  const action = options.actions[task.action];
107
60
  const settingsPayload = (0, workflow_values_1.mergeSettings)(defaultSettings, task.settings);
@@ -119,48 +72,51 @@ const compileTasks = (definition, options) => {
119
72
  return compiled;
120
73
  };
121
74
  /** Recursively compile flow steps into executable nodes with generated ids. */
122
- const compileFlowSteps = (steps, path = [], options) => steps.map((step, index) => {
123
- const stepPath = [...path, index];
75
+ const compileFlowSteps = (steps, path = [], options) => steps.map((step, index) => compileFlowStep(step, [...path, index], options));
76
+ const compileFlowStep = (step, stepPath, options) => {
124
77
  if ('do' in step) {
125
- const label = step.do;
126
78
  return {
127
79
  type: workflow_event_emitter_1.StepType.Task,
128
80
  id: buildStepId(stepPath, step.do),
129
- label,
81
+ label: step.do,
130
82
  taskName: step.do,
131
83
  };
132
84
  }
133
85
  if ('parallel' in step) {
134
- const label = step.parallel.description ?? 'parallel';
135
- return {
136
- type: workflow_event_emitter_1.StepType.Parallel,
137
- id: buildStepId(stepPath, 'parallel'),
138
- label,
139
- description: step.parallel.description,
140
- strategy: step.parallel.strategy ?? 'wait_all',
141
- steps: compileFlowSteps(step.parallel.steps, [...stepPath, 'parallel'], options),
142
- };
86
+ return compileParallelStep(step.parallel, stepPath, options);
143
87
  }
144
88
  if ('conditional' in step) {
145
- const label = step.conditional.description ?? 'conditional';
146
- const branches = step.conditional.when.map((branch, branchIdx) => ({
147
- id: buildStepId([...stepPath, 'branch', branchIdx], 'conditional'),
89
+ return compileConditionalStep(step.conditional, stepPath, options);
90
+ }
91
+ return compileLoopStep(step.loop, stepPath, options);
92
+ };
93
+ const compileParallelStep = (parallel, stepPath, options) => ({
94
+ type: workflow_event_emitter_1.StepType.Parallel,
95
+ id: buildStepId(stepPath, 'parallel'),
96
+ label: parallel.description ?? 'parallel',
97
+ description: parallel.description,
98
+ strategy: parallel.strategy ?? 'wait_all',
99
+ steps: compileFlowSteps(parallel.steps, [...stepPath, 'parallel'], options),
100
+ });
101
+ const compileConditionalStep = (conditional, stepPath, options) => ({
102
+ type: workflow_event_emitter_1.StepType.Conditional,
103
+ id: buildStepId(stepPath, 'conditional'),
104
+ label: conditional.description ?? 'conditional',
105
+ description: conditional.description,
106
+ branches: conditional.when.map((branch, branchIndex) => {
107
+ const branchPath = [...stepPath, 'branch', branchIndex];
108
+ return {
109
+ id: buildStepId(branchPath, 'conditional'),
148
110
  condition: 'condition' in branch
149
111
  ? (0, workflow_values_1.compileValue)(branch.condition, options)
150
112
  : undefined,
151
- steps: compileFlowSteps(branch.steps, [...stepPath, 'branch', branchIdx], options),
152
- }));
153
- return {
154
- type: workflow_event_emitter_1.StepType.Conditional,
155
- id: buildStepId(stepPath, 'conditional'),
156
- label,
157
- description: step.conditional.description,
158
- branches,
113
+ steps: compileFlowSteps(branch.steps, branchPath, options),
159
114
  };
160
- }
161
- const loop = step.loop;
115
+ }),
116
+ });
117
+ const compileLoopStep = (loop, stepPath, options) => {
162
118
  const label = loop.name ?? 'loop';
163
- const commonLoop = {
119
+ const common = {
164
120
  type: workflow_event_emitter_1.StepType.Loop,
165
121
  id: buildStepId(stepPath, label),
166
122
  label,
@@ -173,11 +129,11 @@ const compileFlowSteps = (steps, path = [], options) => steps.map((step, index)
173
129
  merge: (0, workflow_values_1.compileValue)(loop.accumulate.merge, options),
174
130
  }
175
131
  : undefined,
176
- steps: compileFlowSteps(loop.steps, [...stepPath, loop.name ?? 'loop'], options),
132
+ steps: compileFlowSteps(loop.steps, [...stepPath, label], options),
177
133
  };
178
134
  if (loop.type === 'for_each') {
179
135
  return {
180
- ...commonLoop,
136
+ ...common,
181
137
  loopType: 'for_each',
182
138
  forEach: {
183
139
  item: loop.for_each.item,
@@ -188,14 +144,14 @@ const compileFlowSteps = (steps, path = [], options) => steps.map((step, index)
188
144
  };
189
145
  }
190
146
  return {
191
- ...commonLoop,
147
+ ...common,
192
148
  loopType: 'while',
193
149
  while: (0, workflow_values_1.compileValue)(loop.while, options),
194
150
  };
195
- });
151
+ };
196
152
  /** Compile a workflow definition into structures consumable by the runtime. */
197
153
  const compileWorkflow = (definition, options) => {
198
- const inputParser = buildInputParser(definition.inputs?.schema);
154
+ const inputParser = (0, exports.buildWorkflowInputParser)(definition.inputs?.schema);
199
155
  const tasks = compileTasks(definition, options);
200
156
  const flow = compileFlowSteps(definition.flow, [], options);
201
157
  const outputMapping = compileMapping(definition.outputs, options) ?? {};
@@ -63,22 +63,33 @@ const collectSteps = (compiled, steps, parts) => {
63
63
  }
64
64
  break;
65
65
  case workflow_event_emitter_1.StepType.Loop:
66
- parts.push(step.loopType, step.name ?? '');
67
- parts.push(step.accumulate
68
- ? `${step.accumulate.as}=${stringify(step.accumulate.initial)}:${describeValue(step.accumulate.merge)}`
69
- : '');
70
- if (step.loopType === 'for_each') {
71
- parts.push(step.forEach.item, describeValue(step.forEach.in));
72
- parts.push(describeValue(step.until));
73
- }
74
- else {
75
- parts.push(describeValue(step.while));
76
- }
66
+ parts.push(...describeLoop(step));
77
67
  collectSteps(compiled, step.steps, parts);
78
68
  break;
79
69
  }
80
70
  }
81
71
  };
72
+ /**
73
+ * Describe what drives a loop: its kind, name, accumulator, and items or
74
+ * condition.
75
+ *
76
+ * @param step The loop step.
77
+ * @returns The description fragments, in a fixed order.
78
+ */
79
+ const describeLoop = (step) => [
80
+ step.loopType,
81
+ step.name ?? '',
82
+ step.accumulate
83
+ ? `${step.accumulate.as}=${stringify(step.accumulate.initial)}:${describeValue(step.accumulate.merge)}`
84
+ : '',
85
+ ...(step.loopType === 'for_each'
86
+ ? [
87
+ step.forEach.item,
88
+ describeValue(step.forEach.in),
89
+ describeValue(step.until),
90
+ ]
91
+ : [describeValue(step.while)]),
92
+ ];
82
93
  /**
83
94
  * Describe a compiled mapping in a key-stable order.
84
95
  *
@@ -19,6 +19,14 @@ const clone_1 = require("./utils/clone");
19
19
  const workflow_event_emitter_1 = require("./workflow-event-emitter");
20
20
  const workflow_fingerprint_1 = require("./workflow-fingerprint");
21
21
  const workflow_values_1 = require("./workflow-values");
22
+ /** Execution state of the root flow, outside any loop iteration. */
23
+ const rootState = (input, output) => ({ input, output, iterationStack: [] });
24
+ /** Copy a step record, so callers cannot change the one the runner keeps. */
25
+ const copyStepRecord = (record) => ({
26
+ ...record,
27
+ context: record.context ? { ...record.context } : undefined,
28
+ error: record.error ? { ...record.error } : undefined,
29
+ });
22
30
  /**
23
31
  * Executes a compiled workflow definition, tracking state, suspensions, and event hooks.
24
32
  * Create a new instance per execution to avoid leaking state between runs.
@@ -75,11 +83,7 @@ class WorkflowRunner {
75
83
  getStepLog() {
76
84
  return Object.fromEntries(Object.entries(this.stepLog).map(([id, record]) => [
77
85
  id,
78
- {
79
- ...record,
80
- context: record.context ? { ...record.context } : undefined,
81
- error: record.error ? { ...record.error } : undefined,
82
- },
86
+ copyStepRecord(record),
83
87
  ]));
84
88
  }
85
89
  /**
@@ -97,18 +101,20 @@ class WorkflowRunner {
97
101
  *
98
102
  * @param args Input payload and context to seed execution.
99
103
  * @returns Execution result including status and snapshot.
104
+ * @throws {WorkflowInputRejectedError} When the input payload does not match
105
+ * the workflow's `inputs.schema`; nothing ran and the runner is unchanged.
100
106
  */
101
107
  async start(args) {
108
+ const input = this.compiled.inputParser.safeParse(args.inputData ?? {});
109
+ if (!input.success) {
110
+ throw new errors_1.WorkflowInputRejectedError((0, resume_payload_1.describeSchemaIssues)(input.error.issues));
111
+ }
102
112
  this.status = context_1.EWorkflowRunStatus.RUNNING;
103
113
  this.snapshots = {};
104
114
  this.stepLog = {};
105
115
  this.checkpoint = undefined;
106
116
  this.context = args.context;
107
- this.state = {
108
- input: this.compiled.inputParser.parse(args.inputData ?? {}),
109
- output: {},
110
- iterationStack: [],
111
- };
117
+ this.state = rootState(input.data, {});
112
118
  this.runtimeControl = new runner_runtime_control_1.RunnerRuntimeControl();
113
119
  this.context.attachWorkflowRuntime(this.runtimeControl);
114
120
  this.emit('hook:workflow:start', { runId: this.runId });
@@ -198,11 +204,7 @@ class WorkflowRunner {
198
204
  // copy, so both see exactly what a host would have persisted.
199
205
  const from = resumed ? (0, clone_1.cloneAsJson)(resumed.checkpoint) : undefined;
200
206
  if (from) {
201
- this.state = {
202
- input: from.input,
203
- output: from.output,
204
- iterationStack: [],
205
- };
207
+ this.state = rootState(from.input, from.output);
206
208
  }
207
209
  const state = this.state;
208
210
  if (!state) {
@@ -327,11 +329,7 @@ class WorkflowRunner {
327
329
  runId: options.runId,
328
330
  });
329
331
  runner.checkpoint = checkpoint;
330
- runner.state = {
331
- input: checkpoint.input,
332
- output: checkpoint.output,
333
- iterationStack: [],
334
- };
332
+ runner.state = rootState(checkpoint.input, checkpoint.output);
335
333
  runner.context = options.context;
336
334
  runner.snapshots = { ...(options.snapshot?.actions ?? {}) };
337
335
  runner.status = context_1.EWorkflowRunStatus.SUSPENDED;
@@ -421,11 +419,7 @@ class WorkflowRunner {
421
419
  context: mergedContext,
422
420
  };
423
421
  this.stepLog[step.id] = nextRecord;
424
- return {
425
- ...nextRecord,
426
- context: nextRecord.context ? { ...nextRecord.context } : undefined,
427
- error: nextRecord.error ? { ...nextRecord.error } : undefined,
428
- };
422
+ return copyStepRecord(nextRecord);
429
423
  }
430
424
  /**
431
425
  * Construct the environment object passed to step executors.
@@ -8,12 +8,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
8
8
  return (mod && mod.__esModule) ? mod : { "default": mod };
9
9
  };
10
10
  Object.defineProperty(exports, "__esModule", { value: true });
11
- exports.mergeSettings = exports.evaluateMapping = exports.evaluateValue = exports.compileValue = void 0;
11
+ exports.mergeSettings = exports.evaluateMapping = exports.evaluateValue = exports.compileValue = exports.isExpressionString = void 0;
12
12
  const jsonata_1 = __importDefault(require("jsonata"));
13
- /** Basic object guard that rejects arrays and null. */
14
- const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
13
+ const clone_1 = require("./utils/clone");
14
+ /** Strings starting with `=` are JSONata expressions; anything else is a literal. */
15
+ const isExpressionString = (value) => typeof value === 'string' && value.startsWith('=');
16
+ exports.isExpressionString = isExpressionString;
15
17
  const resolveNestedExpressions = async (value, scope, jsonataFunctions, seen = new WeakSet()) => {
16
- if (typeof value === 'string' && value.startsWith('=')) {
18
+ if ((0, exports.isExpressionString)(value)) {
17
19
  return (0, exports.evaluateValue)((0, exports.compileValue)(value, { jsonataFunctions }), scope);
18
20
  }
19
21
  if (Array.isArray(value)) {
@@ -23,7 +25,7 @@ const resolveNestedExpressions = async (value, scope, jsonataFunctions, seen = n
23
25
  seen.add(value);
24
26
  return Promise.all(value.map((entry) => resolveNestedExpressions(entry, scope, jsonataFunctions, seen)));
25
27
  }
26
- if (isPlainObject(value)) {
28
+ if ((0, clone_1.isRecord)(value)) {
27
29
  if (seen.has(value)) {
28
30
  return value;
29
31
  }
@@ -58,7 +60,7 @@ const registerJsonataFunctions = (expression, registry) => {
58
60
  */
59
61
  const compileValue = (value, options) => {
60
62
  const jsonataFunctions = options?.jsonataFunctions;
61
- if (typeof value === 'string' && value.startsWith('=')) {
63
+ if ((0, exports.isExpressionString)(value)) {
62
64
  const expression = (0, jsonata_1.default)(value.slice(1));
63
65
  registerJsonataFunctions(expression, jsonataFunctions);
64
66
  return { kind: 'expression', source: value, expression, jsonataFunctions };
@@ -113,7 +115,7 @@ const mergeSettings = (base, override) => {
113
115
  for (const key of Object.keys(override)) {
114
116
  const value = override[key];
115
117
  const previous = merged[key];
116
- if (isPlainObject(previous) && isPlainObject(value)) {
118
+ if ((0, clone_1.isRecord)(previous) && (0, clone_1.isRecord)(value)) {
117
119
  merged[key] = (0, exports.mergeSettings)(previous, value);
118
120
  }
119
121
  else if (value !== undefined) {
@@ -5,16 +5,19 @@
5
5
  * Full terms: see LICENSE.md.
6
6
  */
7
7
  Object.defineProperty(exports, "__esModule", { value: true });
8
- exports.Workflow = exports.WorkflowRunner = exports.WorkflowEventEmitter = exports.compileWorkflow = void 0;
8
+ exports.Workflow = exports.WorkflowRunner = exports.WorkflowEventEmitter = exports.compileWorkflow = exports.buildWorkflowInputParser = void 0;
9
9
  const yaml_1 = require("yaml");
10
10
  const checkpoint_1 = require("./checkpoint");
11
11
  const context_1 = require("./context");
12
12
  const dsl_types_1 = require("./dsl.types");
13
+ const flow_steps_1 = require("./utils/flow-steps");
14
+ const object_path_1 = require("./utils/object-path");
13
15
  const workflow_definition_1 = require("./utils/workflow-definition");
14
16
  const validation_issue_1 = require("./validation-issue");
15
17
  const workflow_compiler_1 = require("./workflow-compiler");
16
18
  const workflow_runner_1 = require("./workflow-runner");
17
19
  var workflow_compiler_2 = require("./workflow-compiler");
20
+ Object.defineProperty(exports, "buildWorkflowInputParser", { enumerable: true, get: function () { return workflow_compiler_2.buildWorkflowInputParser; } });
18
21
  Object.defineProperty(exports, "compileWorkflow", { enumerable: true, get: function () { return workflow_compiler_2.compileWorkflow; } });
19
22
  var workflow_event_emitter_1 = require("./workflow-event-emitter");
20
23
  Object.defineProperty(exports, "WorkflowEventEmitter", { enumerable: true, get: function () { return workflow_event_emitter_1.WorkflowEventEmitter; } });
@@ -35,22 +38,25 @@ const getTaskNameFromStep = (step) => {
35
38
  const taskName = step.do;
36
39
  return typeof taskName === 'string' ? taskName : null;
37
40
  };
38
- const hasTaskReference = (steps, taskName) => {
39
- return steps.some((step) => {
40
- if ('do' in step) {
41
- return step.do === taskName;
42
- }
43
- if ('parallel' in step) {
44
- return hasTaskReference(step.parallel.steps, taskName);
45
- }
46
- if ('conditional' in step) {
47
- return step.conditional.when.some((branch) => hasTaskReference(branch.steps, taskName));
48
- }
49
- if ('loop' in step) {
50
- return hasTaskReference(step.loop.steps, taskName);
51
- }
52
- return false;
53
- });
41
+ /** The step list a step path points into, and the index it points at. */
42
+ const resolveStepSlot = (definition, stepPath) => {
43
+ const index = stepPath[stepPath.length - 1];
44
+ if (typeof index !== 'number') {
45
+ return null;
46
+ }
47
+ const stepsPath = stepPath.slice(0, -1);
48
+ const steps = (0, object_path_1.getValueAtPath)(definition, stepsPath);
49
+ return Array.isArray(steps) ? { stepsPath, steps, index } : null;
50
+ };
51
+ /** Drop a task def once no flow step references it anymore. */
52
+ const dropUnreferencedTask = (definition, taskName) => {
53
+ if (!Object.prototype.hasOwnProperty.call(definition.defs, taskName) ||
54
+ definition.defs[taskName]?.kind !== dsl_types_1.TASK_KIND ||
55
+ (0, flow_steps_1.collectTaskReferences)(definition.flow).some(({ taskId }) => taskId === taskName)) {
56
+ return definition;
57
+ }
58
+ const { [taskName]: _removedTask, ...remainingDefs } = definition.defs;
59
+ return { ...definition, defs: remainingDefs };
54
60
  };
55
61
  /**
56
62
  * Entry point for preparing and executing workflows from YAML or object definitions.
@@ -65,22 +71,17 @@ class Workflow {
65
71
  * The definition is validated before compilation to catch schema issues early.
66
72
  */
67
73
  static fromDefinition(definition, options) {
68
- const validation = (0, dsl_types_1.validateWorkflow)(definition, {
69
- bindingKinds: options.bindingKinds,
70
- actions: options.actions,
71
- });
72
- if (!validation.success) {
73
- throw new Error(`Workflow validation failed: ${(0, validation_issue_1.issueMessages)(validation.issues).join('; ')}`);
74
- }
75
- const compiled = (0, workflow_compiler_1.compileWorkflow)(validation.data, options);
76
- return new Workflow(compiled);
74
+ return Workflow.validateAndCompile(definition, options);
77
75
  }
78
76
  /**
79
77
  * Create a workflow from YAML source.
80
78
  * YAML is validated and compiled before being wrapped in a {@link Workflow} instance.
81
79
  */
82
80
  static fromYaml(yaml, options) {
83
- const validation = (0, dsl_types_1.validateWorkflow)(yaml, {
81
+ return Workflow.validateAndCompile(yaml, options);
82
+ }
83
+ static validateAndCompile(source, options) {
84
+ const validation = (0, dsl_types_1.validateWorkflow)(source, {
84
85
  bindingKinds: options.bindingKinds,
85
86
  actions: options.actions,
86
87
  });
@@ -102,102 +103,42 @@ class Workflow {
102
103
  * Resolve a nested value from a workflow definition by path.
103
104
  */
104
105
  static getValueAtPath(value, path) {
105
- return path.reduce((acc, key) => {
106
- if (acc === null || acc === undefined) {
107
- return undefined;
108
- }
109
- if (Array.isArray(acc)) {
110
- return typeof key === 'number' ? acc[key] : undefined;
111
- }
112
- if (typeof acc === 'object') {
113
- return acc[String(key)];
114
- }
115
- return undefined;
116
- }, value);
106
+ return (0, object_path_1.getValueAtPath)(value, path);
117
107
  }
118
108
  /**
119
109
  * Create a new value with a nested path updated immutably.
120
110
  */
121
111
  static setValueAtPath(value, path, nextValue) {
122
- if (path.length === 0) {
123
- return nextValue;
124
- }
125
- const [key, ...rest] = path;
126
- if (Array.isArray(value)) {
127
- if (typeof key !== 'number') {
128
- return value;
129
- }
130
- const nextArray = [...value];
131
- nextArray[key] = Workflow.setValueAtPath(value[key], rest, nextValue);
132
- return nextArray;
133
- }
134
- if (value && typeof value === 'object') {
135
- return {
136
- ...value,
137
- [String(key)]: Workflow.setValueAtPath(value[String(key)], rest, nextValue),
138
- };
139
- }
140
- return value;
112
+ return (0, object_path_1.setValueAtPath)(value, path, nextValue);
141
113
  }
142
114
  /**
143
115
  * Remove a flow step from the definition at the given path, if valid.
144
116
  */
145
117
  static removeStepAtPath(definition, stepPath) {
146
- if (!stepPath.length) {
147
- return null;
148
- }
149
- const removeIndex = stepPath[stepPath.length - 1];
150
- if (typeof removeIndex !== 'number') {
151
- return null;
152
- }
153
- const stepsPath = stepPath.slice(0, -1);
154
- const steps = Workflow.getValueAtPath(definition, stepsPath);
155
- if (!Array.isArray(steps)) {
156
- return null;
157
- }
158
- if (removeIndex < 0 || removeIndex >= steps.length) {
118
+ const slot = resolveStepSlot(definition, stepPath);
119
+ if (!slot || slot.index < 0 || slot.index >= slot.steps.length) {
159
120
  return null;
160
121
  }
161
- const removedTaskName = getTaskNameFromStep(steps[removeIndex]);
162
- const nextSteps = [...steps];
163
- nextSteps.splice(removeIndex, 1);
164
- const nextDefinition = Workflow.setValueAtPath(definition, stepsPath, nextSteps);
165
- if (!removedTaskName ||
166
- !Object.prototype.hasOwnProperty.call(nextDefinition.defs, removedTaskName)) {
167
- return nextDefinition;
168
- }
169
- if (nextDefinition.defs[removedTaskName]?.kind !== dsl_types_1.TASK_KIND) {
170
- return nextDefinition;
171
- }
172
- if (hasTaskReference(nextDefinition.flow, removedTaskName)) {
173
- return nextDefinition;
174
- }
175
- const { [removedTaskName]: _removedTask, ...remainingDefs } = nextDefinition.defs;
176
- return {
177
- ...nextDefinition,
178
- defs: remainingDefs,
179
- };
122
+ const removedTaskName = getTaskNameFromStep(slot.steps[slot.index]);
123
+ const nextSteps = [...slot.steps];
124
+ nextSteps.splice(slot.index, 1);
125
+ const nextDefinition = (0, object_path_1.setValueAtPath)(definition, slot.stepsPath, nextSteps);
126
+ return removedTaskName
127
+ ? dropUnreferencedTask(nextDefinition, removedTaskName)
128
+ : nextDefinition;
180
129
  }
181
130
  /**
182
131
  * Insert a flow step into the definition at the given path, if valid.
183
132
  */
184
133
  static insertStepAtPath(definition, insertPath, step) {
185
- if (!insertPath.length) {
186
- return null;
187
- }
188
- const insertIndex = insertPath[insertPath.length - 1];
189
- if (typeof insertIndex !== 'number') {
190
- return null;
191
- }
192
- const stepsPath = insertPath.slice(0, -1);
193
- const steps = Workflow.getValueAtPath(definition, stepsPath);
194
- if (!Array.isArray(steps)) {
134
+ const slot = resolveStepSlot(definition, insertPath);
135
+ if (!slot) {
195
136
  return null;
196
137
  }
197
- const nextSteps = [...steps];
198
- const safeIndex = Math.min(Math.max(insertIndex, 0), nextSteps.length);
138
+ const nextSteps = [...slot.steps];
139
+ const safeIndex = Math.min(Math.max(slot.index, 0), nextSteps.length);
199
140
  nextSteps.splice(safeIndex, 0, step);
200
- return Workflow.setValueAtPath(definition, stepsPath, nextSteps);
141
+ return (0, object_path_1.setValueAtPath)(definition, slot.stepsPath, nextSteps);
201
142
  }
202
143
  /**
203
144
  * Rename a task key and update references in flow steps and output expressions.