@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
@@ -531,6 +531,104 @@ describe('validateWorkflow', () => {
531
531
  }
532
532
  });
533
533
 
534
+ it('reports each binding cycle once, on the def it starts from', () => {
535
+ const workflow = {
536
+ defs: mergeTaskDefs(
537
+ { agent_step: { action: 'understand_request_action' } },
538
+ {
539
+ alpha: {
540
+ kind: 'toolset',
541
+ settings: { name: 'alpha' },
542
+ bindings: { toolset: ['beta'] },
543
+ },
544
+ beta: {
545
+ kind: 'toolset',
546
+ settings: { name: 'beta' },
547
+ bindings: { toolset: ['alpha'] },
548
+ },
549
+ gamma: {
550
+ kind: 'toolset',
551
+ settings: { name: 'gamma' },
552
+ bindings: { toolset: ['gamma'] },
553
+ },
554
+ },
555
+ ),
556
+ flow: [{ do: 'agent_step' }],
557
+ outputs: { result: '=$output.agent_step' },
558
+ };
559
+ const result = validateWorkflow(workflow, {
560
+ bindingKinds: {
561
+ toolset: { ...bindingKinds.toolset, supportedBindings: ['toolset'] },
562
+ },
563
+ });
564
+
565
+ expect(result.success).toBe(false);
566
+ if (!result.success) {
567
+ expect(result.issues).toEqual([
568
+ {
569
+ code: 'binding_cycle',
570
+ message:
571
+ 'defs.alpha.bindings: Circular binding reference detected (alpha -> beta -> alpha).',
572
+ path: ['defs', 'alpha', 'bindings'],
573
+ },
574
+ {
575
+ code: 'binding_cycle',
576
+ message:
577
+ 'defs.gamma.bindings: Circular binding reference detected (gamma -> gamma).',
578
+ path: ['defs', 'gamma', 'bindings'],
579
+ },
580
+ ]);
581
+ }
582
+ });
583
+
584
+ it('enforces the action policy of binding kinds', () => {
585
+ const workflow = {
586
+ defs: mergeTaskDefs(
587
+ { agent_step: { action: 'understand_request_action' } },
588
+ {
589
+ lookup: { kind: 'tools', settings: {} },
590
+ catalog: {
591
+ kind: 'catalog',
592
+ action: 'list_products',
593
+ settings: {},
594
+ },
595
+ },
596
+ ),
597
+ flow: [{ do: 'agent_step' }],
598
+ outputs: { result: '=$output.agent_step' },
599
+ };
600
+ const result = validateWorkflow(workflow, {
601
+ bindingKinds: {
602
+ tools: bindingKinds.tools,
603
+ catalog: {
604
+ schema: z.record(z.string(), z.unknown()),
605
+ multiple: false,
606
+ actionPolicy: 'forbidden' as const,
607
+ },
608
+ },
609
+ });
610
+
611
+ expect(result.success).toBe(false);
612
+ if (!result.success) {
613
+ expect(result.issues).toEqual([
614
+ {
615
+ code: 'action_required',
616
+ message:
617
+ 'defs.lookup.action: Binding kind "tools" requires an action.',
618
+ path: ['defs', 'lookup', 'action'],
619
+ bindingKind: 'tools',
620
+ },
621
+ {
622
+ code: 'action_forbidden',
623
+ message:
624
+ 'defs.catalog.action: Binding kind "catalog" does not allow action declarations.',
625
+ path: ['defs', 'catalog', 'action'],
626
+ bindingKind: 'catalog',
627
+ },
628
+ ]);
629
+ }
630
+ });
631
+
534
632
  describe('structured issues', () => {
535
633
  it('reports missing required action inputs and settings', () => {
536
634
  const workflow = {
@@ -720,6 +818,124 @@ describe('validateWorkflow', () => {
720
818
  }
721
819
  });
722
820
 
821
+ it('reports a missing action once, without judging the bindings it would support', () => {
822
+ const workflow = {
823
+ defs: mergeTaskDefs(
824
+ {
825
+ agent_step: {
826
+ action: 'not_installed_action',
827
+ bindings: { toolset: ['support_tools'] },
828
+ },
829
+ },
830
+ {
831
+ support_tools: { kind: 'toolset', settings: { name: 'support' } },
832
+ },
833
+ ),
834
+ flow: [{ do: 'agent_step' }],
835
+ outputs: { result: '=$output.agent_step' },
836
+ };
837
+ const result = validateWorkflow(workflow, {
838
+ bindingKinds,
839
+ actions: {},
840
+ });
841
+
842
+ expect(result.success).toBe(false);
843
+ if (!result.success) {
844
+ expect(result.issues).toEqual([
845
+ {
846
+ code: 'missing_action',
847
+ message:
848
+ 'defs.agent_step.action: No action implementation provided for "not_installed_action".',
849
+ path: ['defs', 'agent_step', 'action'],
850
+ actionName: 'not_installed_action',
851
+ },
852
+ ]);
853
+ }
854
+ });
855
+
856
+ it('does not take inherited object members for installed actions', () => {
857
+ const workflow = {
858
+ defs: mergeTaskDefs({ agent_step: { action: 'constructor' } }),
859
+ flow: [{ do: 'agent_step' }],
860
+ outputs: { result: '=$output.agent_step' },
861
+ };
862
+ const result = validateWorkflow(workflow, {
863
+ bindingKinds,
864
+ actions: {},
865
+ });
866
+
867
+ expect(result.success).toBe(false);
868
+ if (!result.success) {
869
+ expect(result.issues.map(({ code, path }) => ({ code, path }))).toEqual(
870
+ [{ code: 'missing_action', path: ['defs', 'agent_step', 'action'] }],
871
+ );
872
+ }
873
+ });
874
+
875
+ it('reports an empty task action as missing', () => {
876
+ const workflow = {
877
+ defs: mergeTaskDefs({ agent_step: { action: '' } }),
878
+ flow: [{ do: 'agent_step' }],
879
+ outputs: { result: '=$output.agent_step' },
880
+ };
881
+ const result = validateWorkflow(workflow, {
882
+ bindingKinds,
883
+ actions: {},
884
+ });
885
+
886
+ expect(result.success).toBe(false);
887
+ if (!result.success) {
888
+ expect(result.issues).toEqual([
889
+ {
890
+ code: 'missing_action',
891
+ message:
892
+ 'defs.agent_step.action: No action implementation provided for "".',
893
+ path: ['defs', 'agent_step', 'action'],
894
+ actionName: '',
895
+ },
896
+ ]);
897
+ }
898
+ });
899
+
900
+ it('reports the missing action of a def whose kind is unknown', () => {
901
+ const workflow = {
902
+ defs: mergeTaskDefs(
903
+ { agent_step: { action: 'understand_request_action' } },
904
+ {
905
+ remote_server: {
906
+ kind: 'mcp_server',
907
+ action: 'not_installed_action',
908
+ settings: {},
909
+ bindings: { toolset: ['support_tools'] },
910
+ },
911
+ support_tools: { kind: 'toolset', settings: { name: 'support' } },
912
+ },
913
+ ),
914
+ flow: [{ do: 'agent_step' }],
915
+ outputs: { result: '=$output.agent_step' },
916
+ };
917
+ const result = validateWorkflow(workflow, {
918
+ bindingKinds,
919
+ actions: { understand_request_action: {} },
920
+ });
921
+
922
+ expect(result.success).toBe(false);
923
+ if (!result.success) {
924
+ expect(result.issues.map(({ code, path }) => ({ code, path }))).toEqual(
925
+ [
926
+ {
927
+ code: 'unknown_binding_kind',
928
+ path: ['defs', 'remote_server', 'kind'],
929
+ },
930
+ {
931
+ code: 'missing_action',
932
+ path: ['defs', 'remote_server', 'action'],
933
+ },
934
+ ],
935
+ );
936
+ }
937
+ });
938
+
723
939
  it('reports unknown task references per task with paths', () => {
724
940
  const parsed = parseYaml(fixtureYaml) as Record<string, unknown>;
725
941
  parsed.flow = [
@@ -800,4 +1016,118 @@ describe('validateWorkflow', () => {
800
1016
  }
801
1017
  });
802
1018
  });
1019
+
1020
+ describe('inputs.schema', () => {
1021
+ const validateInputs = (schema: unknown) =>
1022
+ validateWorkflow({
1023
+ inputs: { schema },
1024
+ defs: {},
1025
+ flow: [],
1026
+ outputs: {},
1027
+ });
1028
+ const messagesOf = (schema: unknown) => {
1029
+ const result = validateInputs(schema);
1030
+
1031
+ return result.success ? [] : issueMessages(result.issues);
1032
+ };
1033
+
1034
+ it('accepts a JSON Schema of type object', () => {
1035
+ const schema = {
1036
+ type: 'object',
1037
+ properties: {
1038
+ question: { type: 'string', description: 'What to ask.' },
1039
+ pages: { type: 'integer', default: 1, minimum: 1 },
1040
+ mode: { enum: ['fast', 'thorough'] },
1041
+ tags: { type: 'array', items: { type: 'string' } },
1042
+ author: {
1043
+ type: 'object',
1044
+ properties: { name: { type: ['string', 'null'] } },
1045
+ required: ['name'],
1046
+ },
1047
+ },
1048
+ required: ['question'],
1049
+ additionalProperties: false,
1050
+ };
1051
+ const result = validateInputs(schema);
1052
+
1053
+ expect(result).toEqual(
1054
+ expect.objectContaining({
1055
+ success: true,
1056
+ data: expect.objectContaining({ inputs: { schema } }),
1057
+ }),
1058
+ );
1059
+ });
1060
+
1061
+ it('accepts a workflow without inputs, or without a schema', () => {
1062
+ expect(
1063
+ validateWorkflow({ defs: {}, flow: [], outputs: {} }).success,
1064
+ ).toBe(true);
1065
+ expect(
1066
+ validateWorkflow({ inputs: {}, defs: {}, flow: [], outputs: {} })
1067
+ .success,
1068
+ ).toBe(true);
1069
+ });
1070
+
1071
+ it('refuses a map of fields with one issue naming the expected format', () => {
1072
+ const result = validateInputs({
1073
+ question: { type: 'string' },
1074
+ pages: { type: 'array', items: { type: 'string' } },
1075
+ });
1076
+
1077
+ expect(result.success).toBe(false);
1078
+ if (!result.success) {
1079
+ expect(result.issues).toEqual([
1080
+ {
1081
+ code: 'schema',
1082
+ message:
1083
+ 'inputs.schema: Workflow inputs must be described by a JSON ' +
1084
+ 'Schema, e.g. { type: object, properties: { question: { type: ' +
1085
+ 'string } }, required: [question] }; a map of fields ' +
1086
+ '({ question: { type: string } }) is no longer supported',
1087
+ path: ['inputs', 'schema'],
1088
+ },
1089
+ ]);
1090
+ }
1091
+ });
1092
+
1093
+ it('refuses a map of fields that has a field named "type"', () => {
1094
+ expect(messagesOf({ type: { type: 'string' } })).toEqual([
1095
+ expect.stringContaining('a map of fields'),
1096
+ ]);
1097
+ });
1098
+
1099
+ it.each([
1100
+ ['an empty schema', {}],
1101
+ ['a schema without a type', { properties: { a: { type: 'string' } } }],
1102
+ ['a schema of another type', { type: 'string' }],
1103
+ ['a schema with several types', { type: ['object', 'null'] }],
1104
+ ])('refuses %s, as the input is always an object', (_label, schema) => {
1105
+ expect(messagesOf(schema)).toEqual([
1106
+ 'inputs.schema.type: Workflow inputs must be described by a JSON ' +
1107
+ 'Schema of type "object"; declare the input fields under ' +
1108
+ '"properties"',
1109
+ ]);
1110
+ });
1111
+
1112
+ it('refuses a schema that is not valid JSON Schema, with the reason', () => {
1113
+ expect(
1114
+ messagesOf({ type: 'object', properties: { a: { type: 'text' } } }),
1115
+ ).toEqual([
1116
+ 'inputs.schema: Not a valid JSON Schema (Unsupported type: text)',
1117
+ ]);
1118
+ });
1119
+
1120
+ it('refuses keys other than "schema" under inputs', () => {
1121
+ const result = validateWorkflow({
1122
+ inputs: { type: 'object' },
1123
+ defs: {},
1124
+ flow: [],
1125
+ outputs: {},
1126
+ });
1127
+
1128
+ expect(result.success ? [] : issueMessages(result.issues)).toEqual([
1129
+ 'inputs: Unrecognized key: "type"',
1130
+ ]);
1131
+ });
1132
+ });
803
1133
  });
@@ -10,7 +10,10 @@ import type { Action } from '../action/action.types';
10
10
  import type { BindingKindSchemas } from '../bindings/base-binding';
11
11
  import { BaseWorkflowContext } from '../context';
12
12
  import type { Settings, WorkflowDefinition } from '../dsl.types';
13
- import { compileWorkflow } from '../workflow-compiler';
13
+ import {
14
+ buildWorkflowInputParser,
15
+ compileWorkflow,
16
+ } from '../workflow-compiler';
14
17
  import { StepType, type EventEmitterLike } from '../workflow-event-emitter';
15
18
 
16
19
  import { createTaskDefs, mergeTaskDefs } from './test-helpers';
@@ -125,8 +128,12 @@ describe('compileWorkflow', () => {
125
128
  outputs: { final: '=$output.worker_task.echoed' },
126
129
  inputs: {
127
130
  schema: {
128
- source: { type: 'string' },
129
- items: { type: 'array', items: { type: 'string' } },
131
+ type: 'object',
132
+ properties: {
133
+ source: { type: 'string' },
134
+ items: { type: 'array', items: { type: 'string' } },
135
+ },
136
+ additionalProperties: false,
130
137
  },
131
138
  },
132
139
  };
@@ -299,6 +306,7 @@ describe('compileWorkflow', () => {
299
306
  tools: {
300
307
  calculate: {
301
308
  action: 'calculate_score',
309
+ description: 'Compute a score',
302
310
  settings: {
303
311
  multiplier: 2,
304
312
  bias: 1,
@@ -712,4 +720,271 @@ describe('compileWorkflow', () => {
712
720
  }),
713
721
  ).toThrow(/No action implementation provided for "calculate_score"/);
714
722
  });
723
+ it('compiles each step kind with its path-based id, label and defaults', () => {
724
+ const { action } = createAction();
725
+ const definition: WorkflowDefinition = {
726
+ defs: createTaskDefs({ worker_task: { action: 'worker_action' } }),
727
+ flow: [
728
+ { do: 'worker_task' },
729
+ { parallel: { steps: [{ do: 'worker_task' }] } },
730
+ {
731
+ parallel: {
732
+ description: 'race',
733
+ strategy: 'wait_any',
734
+ steps: [],
735
+ },
736
+ },
737
+ {
738
+ conditional: {
739
+ when: [
740
+ { condition: '=true', steps: [{ do: 'worker_task' }] },
741
+ { else: true, steps: [] },
742
+ ],
743
+ },
744
+ },
745
+ { conditional: { description: 'route', when: [{ steps: [] }] } },
746
+ {
747
+ loop: {
748
+ type: 'while',
749
+ while: '=false',
750
+ steps: [{ do: 'worker_task' }],
751
+ },
752
+ },
753
+ {
754
+ loop: {
755
+ type: 'for_each',
756
+ name: 'each_item',
757
+ description: 'items',
758
+ for_each: { item: 'item', in: '=[1]' },
759
+ max_concurrency: 2,
760
+ until: '=true',
761
+ accumulate: { as: 'all', initial: [], merge: '=$accumulator' },
762
+ steps: [],
763
+ },
764
+ },
765
+ {
766
+ loop: {
767
+ type: 'for_each',
768
+ for_each: { item: 'item', in: '=[]' },
769
+ steps: [],
770
+ },
771
+ },
772
+ ],
773
+ outputs: {},
774
+ };
775
+ const { flow } = compileWorkflow(definition, {
776
+ actions: { worker_action: action },
777
+ });
778
+ const expression = (source: string) =>
779
+ expect.objectContaining({ kind: 'expression', source });
780
+
781
+ expect(flow).toEqual([
782
+ {
783
+ type: StepType.Task,
784
+ id: '0:worker_task',
785
+ label: 'worker_task',
786
+ taskName: 'worker_task',
787
+ },
788
+ {
789
+ type: StepType.Parallel,
790
+ id: '1:parallel',
791
+ label: 'parallel',
792
+ description: undefined,
793
+ strategy: 'wait_all',
794
+ steps: [
795
+ {
796
+ type: StepType.Task,
797
+ id: '1.parallel.0:worker_task',
798
+ label: 'worker_task',
799
+ taskName: 'worker_task',
800
+ },
801
+ ],
802
+ },
803
+ {
804
+ type: StepType.Parallel,
805
+ id: '2:parallel',
806
+ label: 'race',
807
+ description: 'race',
808
+ strategy: 'wait_any',
809
+ steps: [],
810
+ },
811
+ {
812
+ type: StepType.Conditional,
813
+ id: '3:conditional',
814
+ label: 'conditional',
815
+ description: undefined,
816
+ branches: [
817
+ {
818
+ id: '3.branch.0:conditional',
819
+ condition: expression('=true'),
820
+ steps: [
821
+ {
822
+ type: StepType.Task,
823
+ id: '3.branch.0.0:worker_task',
824
+ label: 'worker_task',
825
+ taskName: 'worker_task',
826
+ },
827
+ ],
828
+ },
829
+ { id: '3.branch.1:conditional', condition: undefined, steps: [] },
830
+ ],
831
+ },
832
+ {
833
+ type: StepType.Conditional,
834
+ id: '4:conditional',
835
+ label: 'route',
836
+ description: 'route',
837
+ branches: [
838
+ { id: '4.branch.0:conditional', condition: undefined, steps: [] },
839
+ ],
840
+ },
841
+ {
842
+ type: StepType.Loop,
843
+ id: '5:loop',
844
+ label: 'loop',
845
+ name: undefined,
846
+ description: undefined,
847
+ accumulate: undefined,
848
+ loopType: 'while',
849
+ while: expression('=false'),
850
+ steps: [
851
+ {
852
+ type: StepType.Task,
853
+ id: '5.loop.0:worker_task',
854
+ label: 'worker_task',
855
+ taskName: 'worker_task',
856
+ },
857
+ ],
858
+ },
859
+ {
860
+ type: StepType.Loop,
861
+ id: '6:each_item',
862
+ label: 'each_item',
863
+ name: 'each_item',
864
+ description: 'items',
865
+ accumulate: {
866
+ as: 'all',
867
+ initial: [],
868
+ merge: expression('=$accumulator'),
869
+ },
870
+ loopType: 'for_each',
871
+ forEach: { item: 'item', in: expression('=[1]') },
872
+ maxConcurrency: 2,
873
+ until: expression('=true'),
874
+ steps: [],
875
+ },
876
+ {
877
+ type: StepType.Loop,
878
+ id: '7:loop',
879
+ label: 'loop',
880
+ name: undefined,
881
+ description: undefined,
882
+ accumulate: undefined,
883
+ loopType: 'for_each',
884
+ forEach: { item: 'item', in: expression('=[]') },
885
+ maxConcurrency: undefined,
886
+ until: undefined,
887
+ steps: [],
888
+ },
889
+ ]);
890
+ });
891
+ it('refuses to compile a task with an empty action name', () => {
892
+ const { action } = createAction();
893
+
894
+ expect(() =>
895
+ compileWorkflow(
896
+ {
897
+ defs: createTaskDefs({ worker_task: { action: '' } }),
898
+ flow: [{ do: 'worker_task' }],
899
+ outputs: {},
900
+ },
901
+ { actions: { worker_action: action } },
902
+ ),
903
+ ).toThrow(
904
+ 'Workflow bindings validation failed: defs.worker_task.action: No action implementation provided for "".',
905
+ );
906
+ });
907
+ });
908
+
909
+ describe('buildWorkflowInputParser', () => {
910
+ const parser = buildWorkflowInputParser({
911
+ type: 'object',
912
+ properties: {
913
+ question: { type: 'string' },
914
+ pages: { type: 'integer', default: 1 },
915
+ mode: { enum: ['fast', 'thorough'] },
916
+ author: {
917
+ type: 'object',
918
+ properties: { name: { type: 'string' } },
919
+ required: ['name'],
920
+ additionalProperties: false,
921
+ },
922
+ },
923
+ required: ['question'],
924
+ });
925
+ const issuesOf = (input: unknown) => {
926
+ const result = parser.safeParse(input);
927
+
928
+ return result.success
929
+ ? []
930
+ : result.error.issues.map(
931
+ (issue) => `${issue.path.join('.')}: ${issue.code}`,
932
+ );
933
+ };
934
+
935
+ it('accepts a matching payload and applies the default values', () => {
936
+ expect(parser.parse({ question: 'Why?' })).toEqual({
937
+ question: 'Why?',
938
+ pages: 1,
939
+ });
940
+ expect(parser.parse({ question: 'Why?', pages: 3, mode: 'fast' })).toEqual({
941
+ question: 'Why?',
942
+ pages: 3,
943
+ mode: 'fast',
944
+ });
945
+ });
946
+
947
+ it('refuses a payload without a required field', () => {
948
+ expect(issuesOf({})).toEqual(['question: invalid_type']);
949
+ expect(issuesOf({ question: 'Why?', author: {} })).toEqual([
950
+ 'author.name: invalid_type',
951
+ ]);
952
+ });
953
+
954
+ it('refuses values of the wrong type or outside an enum', () => {
955
+ expect(issuesOf({ question: 1, pages: 1.5, mode: 'slow' }).sort()).toEqual([
956
+ 'mode: invalid_value',
957
+ 'pages: invalid_type',
958
+ 'question: invalid_type',
959
+ ]);
960
+ });
961
+
962
+ it('keeps undeclared keys unless the schema forbids them', () => {
963
+ expect(parser.parse({ question: 'Why?', extra: true })).toEqual({
964
+ question: 'Why?',
965
+ pages: 1,
966
+ extra: true,
967
+ });
968
+ expect(
969
+ issuesOf({ question: 'Why?', author: { name: 'Ada', extra: true } }),
970
+ ).toEqual(['author: unrecognized_keys']);
971
+ });
972
+
973
+ it('refuses a payload that is not an object', () => {
974
+ expect(issuesOf('Why?')).toEqual([': invalid_type']);
975
+ expect(issuesOf(['Why?'])).toEqual([': invalid_type']);
976
+ });
977
+
978
+ it('accepts any object when the workflow declares no schema', () => {
979
+ const open = buildWorkflowInputParser(undefined);
980
+
981
+ expect(open.parse({ anything: [1, 2] })).toEqual({ anything: [1, 2] });
982
+ expect(open.safeParse('text').success).toBe(false);
983
+ });
984
+
985
+ it('throws on a schema that is not valid JSON Schema', () => {
986
+ expect(() => buildWorkflowInputParser({ type: 'text' })).toThrow(
987
+ 'Unsupported type: text',
988
+ );
989
+ });
715
990
  });
@@ -192,6 +192,8 @@ describe('workflow definition path helpers', () => {
192
192
  Workflow.removeStepAtPath(definition, ['defs', 'task_one', 0]),
193
193
  ).toBeNull();
194
194
  expect(Workflow.removeStepAtPath(definition, ['flow', 99])).toBeNull();
195
+ expect(Workflow.removeStepAtPath(definition, ['flow', 3])).toBeNull();
196
+ expect(Workflow.removeStepAtPath(definition, ['flow', -1])).toBeNull();
195
197
  });
196
198
  });
197
199