fascicle 0.1.13 → 0.3.3

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.
package/dist/index.js CHANGED
@@ -1,5 +1,7 @@
1
1
  import { createHash, randomUUID } from "node:crypto";
2
2
  import { z } from "zod";
3
+ import { readFile, readdir } from "node:fs/promises";
4
+ import { join } from "node:path";
3
5
  import { spawn } from "node:child_process";
4
6
  import { generateText, stepCountIs, streamText, tool } from "ai";
5
7
  //#region packages/core/src/flow-schema.json
@@ -29,6 +31,8 @@ var flow_schema_default = {
29
31
  { "required": ["retry"] },
30
32
  { "required": ["fallback"] },
31
33
  { "required": ["timeout"] },
34
+ { "required": ["loop"] },
35
+ { "required": ["compose_node"] },
32
36
  { "required": ["adversarial"] },
33
37
  { "required": ["ensemble"] },
34
38
  { "required": ["tournament"] },
@@ -48,6 +52,8 @@ var flow_schema_default = {
48
52
  "retry": { "$ref": "#/$defs/retry_config" },
49
53
  "fallback": { "$ref": "#/$defs/fallback_config" },
50
54
  "timeout": { "$ref": "#/$defs/timeout_config" },
55
+ "loop": { "$ref": "#/$defs/loop_config" },
56
+ "compose_node": { "$ref": "#/$defs/compose_node_config" },
51
57
  "adversarial": { "$ref": "#/$defs/adversarial_config" },
52
58
  "ensemble": { "$ref": "#/$defs/ensemble_config" },
53
59
  "tournament": { "$ref": "#/$defs/tournament_config" },
@@ -141,6 +147,35 @@ var flow_schema_default = {
141
147
  }
142
148
  }
143
149
  },
150
+ "compose_node_config": {
151
+ "type": "object",
152
+ "required": ["name", "do"],
153
+ "properties": {
154
+ "name": {
155
+ "type": "string",
156
+ "minLength": 1
157
+ },
158
+ "do": { "$ref": "#/$defs/node" }
159
+ }
160
+ },
161
+ "loop_config": {
162
+ "type": "object",
163
+ "required": ["body", "max_rounds"],
164
+ "properties": {
165
+ "name": {
166
+ "type": "string",
167
+ "minLength": 1
168
+ },
169
+ "init": { "type": "string" },
170
+ "body": { "$ref": "#/$defs/node" },
171
+ "guard": { "$ref": "#/$defs/node" },
172
+ "finish": { "type": "string" },
173
+ "max_rounds": {
174
+ "type": "integer",
175
+ "minimum": 1
176
+ }
177
+ }
178
+ },
144
179
  "adversarial_config": {
145
180
  "type": "object",
146
181
  "required": [
@@ -490,6 +525,19 @@ const dispatch = /* @__PURE__ */ new Map();
490
525
  function register_kind(kind, fn) {
491
526
  dispatch.set(kind, fn);
492
527
  }
528
+ /**
529
+ * Resolve the trajectory span label for a step. Prefers a non-empty
530
+ * `display_name` from `flow.config`; otherwise falls back to the supplied
531
+ * default (typically the step's `kind`).
532
+ *
533
+ * Dispatch handlers use this so that any composer carrying a user-supplied
534
+ * `name` surfaces under that label in the trajectory, while unconfigured
535
+ * composers retain their kind-based label.
536
+ */
537
+ function resolve_span_label(flow, fallback) {
538
+ const display = flow.config?.["display_name"];
539
+ return typeof display === "string" && display.length > 0 ? display : fallback;
540
+ }
493
541
  const active_runs = /* @__PURE__ */ new Set();
494
542
  let signal_handler_installed = false;
495
543
  let sigint_handler = null;
@@ -519,6 +567,44 @@ const noop_logger = {
519
567
  start_span: (name) => `${name}:${randomUUID().slice(0, 8)}`,
520
568
  end_span: () => {}
521
569
  };
570
+ /**
571
+ * Wrap a logger so every emitted event automatically carries `run_id`.
572
+ *
573
+ * Studios and other downstream consumers can multiplex events across runs
574
+ * by reading this field. Callers may still set their own `run_id` on a record;
575
+ * we don't overwrite it.
576
+ */
577
+ function stamp_run_id(inner, run_id) {
578
+ return {
579
+ record: (event) => {
580
+ if ("run_id" in event) {
581
+ inner.record(event);
582
+ return;
583
+ }
584
+ inner.record({
585
+ ...event,
586
+ run_id
587
+ });
588
+ },
589
+ start_span: (name, meta) => {
590
+ if (meta && "run_id" in meta) return inner.start_span(name, meta);
591
+ return inner.start_span(name, {
592
+ ...meta,
593
+ run_id
594
+ });
595
+ },
596
+ end_span: (id, meta) => {
597
+ if (meta && "run_id" in meta) {
598
+ inner.end_span(id, meta);
599
+ return;
600
+ }
601
+ inner.end_span(id, {
602
+ ...meta,
603
+ run_id
604
+ });
605
+ }
606
+ };
607
+ }
522
608
  async function dispatch_step(flow, input, ctx) {
523
609
  const handler = dispatch.get(flow.kind);
524
610
  if (!handler) throw new Error(`unknown step kind: ${flow.kind} (step id: ${flow.id})`);
@@ -539,19 +625,20 @@ function start_run(flow, input, options, high_water_mark) {
539
625
  const install_signal_handlers = options.install_signal_handlers !== false;
540
626
  const base_logger = options.trajectory ?? noop_logger;
541
627
  const streaming = high_water_mark !== null;
542
- let logger = base_logger;
628
+ const controller = new AbortController();
629
+ const run_id = randomUUID();
630
+ let logger = stamp_run_id(base_logger, run_id);
543
631
  let stream_events = empty_async_iterable();
544
632
  let close_stream = null;
545
633
  if (streaming) {
546
- const channel = create_streaming_channel(base_logger, high_water_mark);
634
+ const channel = create_streaming_channel(logger, high_water_mark);
547
635
  logger = channel.logger;
548
636
  stream_events = channel.events;
549
637
  close_stream = channel.close;
550
638
  }
551
- const controller = new AbortController();
552
639
  const cleanup = create_cleanup_registry(logger);
553
640
  const ctx = {
554
- run_id: randomUUID(),
641
+ run_id,
555
642
  trajectory: logger,
556
643
  state: /* @__PURE__ */ new Map(),
557
644
  abort: controller.signal,
@@ -619,9 +706,12 @@ const run = Object.assign(run_impl, { stream: run_stream });
619
706
  /**
620
707
  * step() factory.
621
708
  *
622
- * Two forms:
623
- * step(id, fn) — named step. id is rendered in trajectory spans and describe().
624
- * step(fn) — anonymous step. id is `anon_<counter>`; cannot be checkpointed.
709
+ * Three forms:
710
+ * step(id, fn) — named step. id is rendered in trajectory spans and describe().
711
+ * step(id, fn, meta) — named step with optional human-readable metadata for studio,
712
+ * codegen, and similar consumers. `meta` is purely descriptive
713
+ * and never affects runtime semantics.
714
+ * step(fn) — anonymous step. id is `anon_<counter>`; cannot be checkpointed.
625
715
  *
626
716
  * Anonymous steps carry an internal `anonymous: true` flag so checkpoint can
627
717
  * reject them synchronously at flow construction time (spec.md §9 F6 / §7 invariant 8).
@@ -631,7 +721,7 @@ function next_anon_id() {
631
721
  anon_counter += 1;
632
722
  return `anon_${anon_counter}`;
633
723
  }
634
- function step(id_or_fn, maybe_fn) {
724
+ function step(id_or_fn, maybe_fn, meta) {
635
725
  if (typeof id_or_fn === "function") return {
636
726
  id: next_anon_id(),
637
727
  kind: "step",
@@ -639,6 +729,12 @@ function step(id_or_fn, maybe_fn) {
639
729
  anonymous: true
640
730
  };
641
731
  if (typeof maybe_fn !== "function") throw new TypeError("step(id, fn): fn must be a function");
732
+ if (meta) return {
733
+ id: id_or_fn,
734
+ kind: "step",
735
+ run: maybe_fn,
736
+ meta
737
+ };
642
738
  return {
643
739
  id: id_or_fn,
644
740
  kind: "step",
@@ -698,8 +794,13 @@ function render_text(node, depth, lines, path, strict) {
698
794
  }
699
795
  path.add(node);
700
796
  try {
701
- lines.push(`${prefix}${node.kind}(${node.id})`);
702
- if (node.config) for (const [key, value] of Object.entries(node.config)) lines.push(`${prefix}${INDENT}${key}: ${render_value_text(value, path, strict)}`);
797
+ const display = node.config?.["display_name"];
798
+ const label = typeof display === "string" && display.length > 0 ? display : node.kind;
799
+ lines.push(`${prefix}${label}(${node.id})`);
800
+ if (node.config) for (const [key, value] of Object.entries(node.config)) {
801
+ if (key === "display_name") continue;
802
+ lines.push(`${prefix}${INDENT}${key}: ${render_value_text(value, path, strict)}`);
803
+ }
703
804
  if (node.children && node.children.length > 0) for (const child of node.children) render_text(child, depth + 1, lines, path, strict);
704
805
  } finally {
705
806
  path.delete(node);
@@ -748,6 +849,7 @@ function render_json(node, path, strict) {
748
849
  result.config = config;
749
850
  }
750
851
  if (node.children && node.children.length > 0) result.children = node.children.map((child) => render_json(child, path, strict));
852
+ if (node.meta) result.meta = node.meta;
751
853
  return result;
752
854
  } finally {
753
855
  path.delete(node);
@@ -811,27 +913,30 @@ function is_zod_schema(value) {
811
913
  * See spec.md §5.2 and §6.1.
812
914
  */
813
915
  let sequence_counter = 0;
814
- function next_id$12() {
916
+ function next_id$10() {
815
917
  sequence_counter += 1;
816
918
  return `sequence_${sequence_counter}`;
817
919
  }
818
- function sequence(children) {
819
- const id = next_id$12();
920
+ function sequence(children, options) {
921
+ const id = next_id$10();
820
922
  const children_ref = children;
821
923
  const run_fn = async (input, ctx) => {
822
924
  let acc = input;
823
925
  for (const child of children_ref) acc = await dispatch_step(child, acc, ctx);
824
926
  return acc;
825
927
  };
928
+ const config_meta = options?.name === void 0 ? void 0 : { display_name: options.name };
826
929
  return {
827
930
  id,
828
931
  kind: "sequence",
829
932
  children,
933
+ ...config_meta ? { config: config_meta } : {},
830
934
  run: run_fn
831
935
  };
832
936
  }
833
937
  register_kind("sequence", async (flow, input, ctx) => {
834
- const span_id = ctx.trajectory.start_span("sequence", { id: flow.id });
938
+ const label = resolve_span_label(flow, "sequence");
939
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
835
940
  try {
836
941
  const out = await flow.run(input, ctx);
837
942
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -860,12 +965,12 @@ register_kind("sequence", async (flow, input, ctx) => {
860
965
  * "agent-pattern" composer contract in spec.md §6.8.
861
966
  */
862
967
  let parallel_counter = 0;
863
- function next_id$11() {
968
+ function next_id$9() {
864
969
  parallel_counter += 1;
865
970
  return `parallel_${parallel_counter}`;
866
971
  }
867
- function parallel(members) {
868
- const id = next_id$11();
972
+ function parallel(members, options) {
973
+ const id = next_id$9();
869
974
  const entries = Object.entries(members);
870
975
  const child_list = entries.map(([, s]) => s);
871
976
  const keys = entries.map(([k]) => k);
@@ -911,16 +1016,19 @@ function parallel(members) {
911
1016
  ctx.abort.removeEventListener("abort", on_parent_abort);
912
1017
  }
913
1018
  };
1019
+ const config_meta = { keys };
1020
+ if (options?.name !== void 0) config_meta["display_name"] = options.name;
914
1021
  return {
915
1022
  id,
916
1023
  kind: "parallel",
917
1024
  children: child_list,
918
- config: { keys },
1025
+ config: config_meta,
919
1026
  run: run_fn
920
1027
  };
921
1028
  }
922
1029
  register_kind("parallel", async (flow, input, ctx) => {
923
- const span_id = ctx.trajectory.start_span("parallel", { id: flow.id });
1030
+ const label = resolve_span_label(flow, "parallel");
1031
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
924
1032
  try {
925
1033
  const out = await flow.run(input, ctx);
926
1034
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -945,30 +1053,33 @@ register_kind("parallel", async (flow, input, ctx) => {
945
1053
  * See spec.md §5.4.
946
1054
  */
947
1055
  let branch_counter = 0;
948
- function next_id$10() {
1056
+ function next_id$8() {
949
1057
  branch_counter += 1;
950
1058
  return `branch_${branch_counter}`;
951
1059
  }
952
1060
  function branch(config) {
953
- const id = next_id$10();
954
- const { when, then: then_step, otherwise: otherwise_step } = config;
1061
+ const id = next_id$8();
1062
+ const { when, then: then_step, otherwise: otherwise_step, name } = config;
955
1063
  const run_fn = async (input, ctx) => {
956
1064
  return dispatch_step(await when(input) ? then_step : otherwise_step, input, ctx);
957
1065
  };
1066
+ const config_meta = {
1067
+ when,
1068
+ then: then_step,
1069
+ otherwise: otherwise_step
1070
+ };
1071
+ if (name !== void 0) config_meta["display_name"] = name;
958
1072
  return {
959
1073
  id,
960
1074
  kind: "branch",
961
1075
  children: [then_step, otherwise_step],
962
- config: {
963
- when,
964
- then: then_step,
965
- otherwise: otherwise_step
966
- },
1076
+ config: config_meta,
967
1077
  run: run_fn
968
1078
  };
969
1079
  }
970
1080
  register_kind("branch", async (flow, input, ctx) => {
971
- const span_id = ctx.trajectory.start_span("branch", { id: flow.id });
1081
+ const label = resolve_span_label(flow, "branch");
1082
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
972
1083
  try {
973
1084
  const out = await flow.run(input, ctx);
974
1085
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -997,13 +1108,13 @@ register_kind("branch", async (flow, input, ctx) => {
997
1108
  * rethrowing `ctx.abort.reason`.
998
1109
  */
999
1110
  let map_counter = 0;
1000
- function next_id$9() {
1111
+ function next_id$7() {
1001
1112
  map_counter += 1;
1002
1113
  return `map_${map_counter}`;
1003
1114
  }
1004
1115
  function map(config) {
1005
- const id = next_id$9();
1006
- const { items, do: per_item, concurrency } = config;
1116
+ const id = next_id$7();
1117
+ const { items, do: per_item, concurrency, name } = config;
1007
1118
  const run_fn = async (input, ctx) => {
1008
1119
  const list = await items(input);
1009
1120
  if (list.length === 0) return [];
@@ -1057,19 +1168,20 @@ function map(config) {
1057
1168
  ctx.abort.removeEventListener("abort", on_parent_abort);
1058
1169
  }
1059
1170
  };
1171
+ const config_meta = { items };
1172
+ if (concurrency !== void 0) config_meta["concurrency"] = concurrency;
1173
+ if (name !== void 0) config_meta["display_name"] = name;
1060
1174
  return {
1061
1175
  id,
1062
1176
  kind: "map",
1063
1177
  children: [per_item],
1064
- ...concurrency === void 0 ? { config: { items } } : { config: {
1065
- items,
1066
- concurrency
1067
- } },
1178
+ config: config_meta,
1068
1179
  run: run_fn
1069
1180
  };
1070
1181
  }
1071
1182
  register_kind("map", async (flow, input, ctx) => {
1072
- const span_id = ctx.trajectory.start_span("map", { id: flow.id });
1183
+ const label = resolve_span_label(flow, "map");
1184
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1073
1185
  try {
1074
1186
  const out = await flow.run(input, ctx);
1075
1187
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -1093,25 +1205,28 @@ register_kind("map", async (flow, input, ctx) => {
1093
1205
  * See spec.md §5.6.
1094
1206
  */
1095
1207
  let pipe_counter = 0;
1096
- function next_id$8() {
1208
+ function next_id$6() {
1097
1209
  pipe_counter += 1;
1098
1210
  return `pipe_${pipe_counter}`;
1099
1211
  }
1100
- function pipe(inner, fn) {
1101
- const id = next_id$8();
1212
+ function pipe(inner, fn, options) {
1213
+ const id = next_id$6();
1102
1214
  const run_fn = async (input, ctx) => {
1103
1215
  return fn(await dispatch_step(inner, input, ctx));
1104
1216
  };
1217
+ const config_meta = { fn };
1218
+ if (options?.name !== void 0) config_meta["display_name"] = options.name;
1105
1219
  return {
1106
1220
  id,
1107
1221
  kind: "pipe",
1108
1222
  children: [inner],
1109
- config: { fn },
1223
+ config: config_meta,
1110
1224
  run: run_fn
1111
1225
  };
1112
1226
  }
1113
1227
  register_kind("pipe", async (flow, input, ctx) => {
1114
- const span_id = ctx.trajectory.start_span("pipe", { id: flow.id });
1228
+ const label = resolve_span_label(flow, "pipe");
1229
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1115
1230
  try {
1116
1231
  const out = await flow.run(input, ctx);
1117
1232
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -1141,7 +1256,7 @@ register_kind("pipe", async (flow, input, ctx) => {
1141
1256
  */
1142
1257
  const DEFAULT_BACKOFF_MS = 1e3;
1143
1258
  let retry_counter = 0;
1144
- function next_id$7() {
1259
+ function next_id$5() {
1145
1260
  retry_counter += 1;
1146
1261
  return `retry_${retry_counter}`;
1147
1262
  }
@@ -1166,7 +1281,7 @@ async function abortable_wait(ms, ctx) {
1166
1281
  });
1167
1282
  }
1168
1283
  function retry(inner, config) {
1169
- const id = next_id$7();
1284
+ const id = next_id$5();
1170
1285
  const max_attempts = Math.max(1, Math.floor(config.max_attempts));
1171
1286
  const backoff_ms = config.backoff_ms ?? DEFAULT_BACKOFF_MS;
1172
1287
  const on_error = config.on_error;
@@ -1193,6 +1308,7 @@ function retry(inner, config) {
1193
1308
  backoff_ms
1194
1309
  };
1195
1310
  if (on_error) config_meta["on_error"] = on_error;
1311
+ if (config.name !== void 0) config_meta["display_name"] = config.name;
1196
1312
  return {
1197
1313
  id,
1198
1314
  kind: "retry",
@@ -1202,7 +1318,8 @@ function retry(inner, config) {
1202
1318
  };
1203
1319
  }
1204
1320
  register_kind("retry", async (flow, input, ctx) => {
1205
- const span_id = ctx.trajectory.start_span("retry", { id: flow.id });
1321
+ const label = resolve_span_label(flow, "retry");
1322
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1206
1323
  try {
1207
1324
  const out = await flow.run(input, ctx);
1208
1325
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -1225,12 +1342,12 @@ register_kind("retry", async (flow, input, ctx) => {
1225
1342
  * propagates. See spec.md §5.8.
1226
1343
  */
1227
1344
  let fallback_counter = 0;
1228
- function next_id$6() {
1345
+ function next_id$4() {
1229
1346
  fallback_counter += 1;
1230
1347
  return `fallback_${fallback_counter}`;
1231
1348
  }
1232
- function fallback(primary, backup) {
1233
- const id = next_id$6();
1349
+ function fallback(primary, backup, options) {
1350
+ const id = next_id$4();
1234
1351
  const run_fn = async (input, ctx) => {
1235
1352
  try {
1236
1353
  return await dispatch_step(primary, input, ctx);
@@ -1238,15 +1355,18 @@ function fallback(primary, backup) {
1238
1355
  return dispatch_step(backup, input, ctx);
1239
1356
  }
1240
1357
  };
1358
+ const config_meta = options?.name === void 0 ? void 0 : { display_name: options.name };
1241
1359
  return {
1242
1360
  id,
1243
1361
  kind: "fallback",
1244
1362
  children: [primary, backup],
1363
+ ...config_meta ? { config: config_meta } : {},
1245
1364
  run: run_fn
1246
1365
  };
1247
1366
  }
1248
1367
  register_kind("fallback", async (flow, input, ctx) => {
1249
- const span_id = ctx.trajectory.start_span("fallback", { id: flow.id });
1368
+ const label = resolve_span_label(flow, "fallback");
1369
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1250
1370
  try {
1251
1371
  const out = await flow.run(input, ctx);
1252
1372
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -1277,12 +1397,12 @@ register_kind("fallback", async (flow, input, ctx) => {
1277
1397
  * block so it does not leak across retries.
1278
1398
  */
1279
1399
  let timeout_counter = 0;
1280
- function next_id$5() {
1400
+ function next_id$3() {
1281
1401
  timeout_counter += 1;
1282
1402
  return `timeout_${timeout_counter}`;
1283
1403
  }
1284
- function timeout(inner, ms) {
1285
- const id = next_id$5();
1404
+ function timeout(inner, ms, options) {
1405
+ const id = next_id$3();
1286
1406
  const run_fn = async (input, ctx) => {
1287
1407
  const local = new AbortController();
1288
1408
  const composed = AbortSignal.any([ctx.abort, local.signal]);
@@ -1315,16 +1435,19 @@ function timeout(inner, ms) {
1315
1435
  clearTimeout(timer);
1316
1436
  }
1317
1437
  };
1438
+ const config_meta = { ms };
1439
+ if (options?.name !== void 0) config_meta["display_name"] = options.name;
1318
1440
  return {
1319
1441
  id,
1320
1442
  kind: "timeout",
1321
1443
  children: [inner],
1322
- config: { ms },
1444
+ config: config_meta,
1323
1445
  run: run_fn
1324
1446
  };
1325
1447
  }
1326
1448
  register_kind("timeout", async (flow, input, ctx) => {
1327
- const span_id = ctx.trajectory.start_span("timeout", { id: flow.id });
1449
+ const label = resolve_span_label(flow, "timeout");
1450
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1328
1451
  try {
1329
1452
  const out = await flow.run(input, ctx);
1330
1453
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -1338,316 +1461,77 @@ register_kind("timeout", async (flow, input, ctx) => {
1338
1461
  }
1339
1462
  });
1340
1463
  //#endregion
1341
- //#region packages/core/src/adversarial.ts
1464
+ //#region packages/core/src/loop.ts
1342
1465
  /**
1343
- * adversarial: build-and-critique loop.
1466
+ * loop: bounded iteration with carry-state.
1344
1467
  *
1345
- * `adversarial({ build, critique, accept, max_rounds })` runs up to
1346
- * `max_rounds` iterations of: build a candidate (receiving the prior
1347
- * candidate and critique notes when available) -> critique the candidate
1348
- * -> check `accept(critique_result)`. Returns `{ candidate, converged,
1349
- * rounds }`. Does not throw on non-convergence (spec.md §9 F3).
1468
+ * `loop({ init, body, guard?, finish, max_rounds, name? })` runs `body` up to
1469
+ * `max_rounds` times, threading `state` through each iteration. After every
1470
+ * `body` call, an optional `guard` step inspects (and may transform) the state
1471
+ * and decides whether to stop. When `guard.stop` is true, the loop exits
1472
+ * "converged"; otherwise it continues until `max_rounds`. `finish` projects
1473
+ * the final state to the loop's output value.
1474
+ *
1475
+ * Non-convergence is data, not error: when `max_rounds` is exhausted without
1476
+ * `guard` returning stop, the loop returns `{ value, converged: false, rounds }`.
1477
+ * This matches the existing convention from adversarial/consensus.
1350
1478
  *
1351
- * See spec.md §5.10.
1479
+ * Cancellation: between rounds the parent `ctx.abort` is honored — a pending
1480
+ * abort short-circuits and propagates `ctx.abort.reason`. The body and guard
1481
+ * receive the parent context unchanged; their own dispatch routes already
1482
+ * thread cancellation per the runner contract.
1352
1483
  */
1353
- let adversarial_counter = 0;
1354
- function next_id$4() {
1355
- adversarial_counter += 1;
1356
- return `adversarial_${adversarial_counter}`;
1357
- }
1358
- function adversarial(config) {
1359
- const id = next_id$4();
1360
- const { build, critique, accept, max_rounds } = config;
1361
- const rounds_limit = Math.max(1, Math.floor(max_rounds));
1484
+ let loop_counter = 0;
1485
+ function next_id$2(name) {
1486
+ loop_counter += 1;
1487
+ return `${name ?? "loop"}_${loop_counter}`;
1488
+ }
1489
+ function throw_if_aborted$2(ctx) {
1490
+ if (!ctx.abort.aborted) return;
1491
+ const reason = ctx.abort.reason;
1492
+ throw reason instanceof Error ? reason : new aborted_error("aborted", { reason });
1493
+ }
1494
+ function loop(config) {
1495
+ const { init, body, guard, finish, name } = config;
1496
+ const rounds_limit = Math.max(1, Math.floor(config.max_rounds));
1497
+ const id = next_id$2(name);
1362
1498
  const run_fn = async (input, ctx) => {
1363
- let candidate = void 0;
1364
- let critique_notes = void 0;
1499
+ let state = init(input);
1365
1500
  let round = 0;
1501
+ let converged = false;
1366
1502
  while (round < rounds_limit) {
1503
+ throw_if_aborted$2(ctx);
1367
1504
  round += 1;
1368
- candidate = await dispatch_step(build, candidate === void 0 ? { input } : critique_notes === void 0 ? {
1369
- input,
1370
- prior: candidate
1371
- } : {
1372
- input,
1373
- prior: candidate,
1374
- critique: critique_notes
1375
- }, ctx);
1376
- const critique_result = await dispatch_step(critique, candidate, ctx);
1377
- if (accept(critique_result)) return {
1378
- candidate,
1379
- converged: true,
1380
- rounds: round
1381
- };
1382
- critique_notes = critique_result.notes;
1383
- }
1384
- return {
1385
- candidate,
1386
- converged: false,
1387
- rounds: round
1388
- };
1389
- };
1390
- return {
1391
- id,
1392
- kind: "adversarial",
1393
- children: [build, critique],
1394
- config: {
1395
- max_rounds: rounds_limit,
1396
- accept
1397
- },
1398
- run: run_fn
1399
- };
1400
- }
1401
- register_kind("adversarial", async (flow, input, ctx) => {
1402
- const span_id = ctx.trajectory.start_span("adversarial", { id: flow.id });
1403
- try {
1404
- const out = await flow.run(input, ctx);
1405
- ctx.trajectory.end_span(span_id, { id: flow.id });
1406
- return out;
1407
- } catch (err) {
1408
- ctx.trajectory.end_span(span_id, {
1409
- id: flow.id,
1410
- error: err instanceof Error ? err.message : String(err)
1411
- });
1412
- throw err;
1413
- }
1414
- });
1415
- //#endregion
1416
- //#region packages/core/src/ensemble.ts
1417
- /**
1418
- * ensemble: N-of-M pick best.
1419
- *
1420
- * `ensemble({ members, score, select? })` runs every member concurrently with
1421
- * the same input, scores each result, and returns the winner (highest or
1422
- * lowest by `select`) plus the complete score map. Tie-breaking is defined
1423
- * as "any tied result is acceptable".
1424
- *
1425
- * Cancellation (constraints.md §5.1, spec.md §6.8): each member runs with a
1426
- * composed abort signal via `AbortSignal.any([ctx.abort, child_local])`. On
1427
- * abort the composer awaits all in-flight members before rethrowing
1428
- * `ctx.abort.reason`.
1429
- *
1430
- * See spec.md §5.11.
1431
- */
1432
- let ensemble_counter = 0;
1433
- function next_id$3() {
1434
- ensemble_counter += 1;
1435
- return `ensemble_${ensemble_counter}`;
1436
- }
1437
- function ensemble(config) {
1438
- const id = next_id$3();
1439
- const entries = Object.entries(config.members);
1440
- const child_list = entries.map(([, s]) => s);
1441
- const keys = entries.map(([k]) => k);
1442
- const score_fn = config.score;
1443
- const select = config.select ?? "max";
1444
- const run_fn = async (input, ctx) => {
1445
- const controllers = entries.map(() => new AbortController());
1446
- const on_parent_abort = () => {
1447
- for (const c of controllers) c.abort(ctx.abort.reason);
1448
- };
1449
- if (ctx.abort.aborted) on_parent_abort();
1450
- else ctx.abort.addEventListener("abort", on_parent_abort, { once: true });
1451
- try {
1452
- const settled = await Promise.all(entries.map(async ([key, member], idx) => {
1453
- const local = controllers[idx];
1454
- if (!local) throw new Error("ensemble: missing controller");
1455
- const composed = AbortSignal.any([ctx.abort, local.signal]);
1456
- const child_ctx = {
1457
- ...ctx,
1458
- abort: composed
1459
- };
1460
- try {
1461
- return {
1462
- status: "ok",
1463
- key,
1464
- value: await dispatch_step(member, input, child_ctx)
1465
- };
1466
- } catch (err) {
1467
- return {
1468
- status: "err",
1469
- key,
1470
- err
1471
- };
1472
- }
1473
- }));
1474
- if (ctx.abort.aborted) {
1475
- const reason = ctx.abort.reason;
1476
- throw reason instanceof Error ? reason : new aborted_error("aborted", { reason });
1477
- }
1478
- for (const s of settled) if (s.status === "err") throw s.err;
1479
- const scores = {};
1480
- const results = {};
1481
- for (const s of settled) if (s.status === "ok") {
1482
- results[s.key] = s.value;
1483
- scores[s.key] = await score_fn(s.value, s.key);
1484
- }
1485
- let winner_key = void 0;
1486
- let winner_score = void 0;
1487
- for (const k of keys) {
1488
- const current = scores[k];
1489
- if (current === void 0) continue;
1490
- if (winner_score === void 0) {
1491
- winner_key = k;
1492
- winner_score = current;
1493
- continue;
1494
- }
1495
- if (select === "max" ? current > winner_score : current < winner_score) {
1496
- winner_key = k;
1497
- winner_score = current;
1505
+ state = await dispatch_step(body, state, ctx);
1506
+ if (guard) {
1507
+ throw_if_aborted$2(ctx);
1508
+ const guard_out = await dispatch_step(guard, state, ctx);
1509
+ state = guard_out.state;
1510
+ if (guard_out.stop) {
1511
+ converged = true;
1512
+ break;
1498
1513
  }
1499
1514
  }
1500
- if (winner_key === void 0) throw new Error("ensemble: no members produced a result");
1501
- const winner = results[winner_key];
1502
- if (winner === void 0) throw new Error("ensemble: winner missing from results");
1503
- return {
1504
- winner,
1505
- scores
1506
- };
1507
- } finally {
1508
- ctx.abort.removeEventListener("abort", on_parent_abort);
1509
1515
  }
1510
- };
1511
- return {
1512
- id,
1513
- kind: "ensemble",
1514
- children: child_list,
1515
- config: {
1516
- keys,
1517
- select
1518
- },
1519
- run: run_fn
1520
- };
1521
- }
1522
- register_kind("ensemble", async (flow, input, ctx) => {
1523
- const span_id = ctx.trajectory.start_span("ensemble", { id: flow.id });
1524
- try {
1525
- const out = await flow.run(input, ctx);
1526
- ctx.trajectory.end_span(span_id, { id: flow.id });
1527
- return out;
1528
- } catch (err) {
1529
- ctx.trajectory.end_span(span_id, {
1530
- id: flow.id,
1531
- error: err instanceof Error ? err.message : String(err)
1532
- });
1533
- throw err;
1534
- }
1535
- });
1536
- //#endregion
1537
- //#region packages/core/src/tournament.ts
1538
- /**
1539
- * tournament: pairwise bracket.
1540
- *
1541
- * `tournament({ members, compare })` runs every member, then pairs them off
1542
- * in a single-elimination bracket. `compare(a, b)` returns which result
1543
- * advances. An odd member count yields one bye per affected round. The
1544
- * returned `bracket` is a list of `{ round, a_id, b_id, winner_id }`.
1545
- *
1546
- * Cancellation (constraints.md §5.1, spec.md §6.8): each member runs with a
1547
- * composed abort signal. On abort the composer awaits in-flight members
1548
- * before rethrowing `ctx.abort.reason`.
1549
- *
1550
- * See spec.md §5.12.
1551
- */
1552
- let tournament_counter = 0;
1553
- function next_id$2() {
1554
- tournament_counter += 1;
1555
- return `tournament_${tournament_counter}`;
1556
- }
1557
- function tournament(config) {
1558
- const id = next_id$2();
1559
- const entries = Object.entries(config.members);
1560
- const child_list = entries.map(([, s]) => s);
1561
- const keys = entries.map(([k]) => k);
1562
- const compare_fn = config.compare;
1563
- const run_fn = async (input, ctx) => {
1564
- if (entries.length === 0) throw new Error("tournament: at least one member required");
1565
- const controllers = entries.map(() => new AbortController());
1566
- const on_parent_abort = () => {
1567
- for (const c of controllers) c.abort(ctx.abort.reason);
1516
+ return {
1517
+ value: finish(state, round),
1518
+ converged,
1519
+ rounds: round
1568
1520
  };
1569
- if (ctx.abort.aborted) on_parent_abort();
1570
- else ctx.abort.addEventListener("abort", on_parent_abort, { once: true });
1571
- try {
1572
- const settled = await Promise.all(entries.map(async ([key, member], idx) => {
1573
- const local = controllers[idx];
1574
- if (!local) throw new Error("tournament: missing controller");
1575
- const composed = AbortSignal.any([ctx.abort, local.signal]);
1576
- const child_ctx = {
1577
- ...ctx,
1578
- abort: composed
1579
- };
1580
- try {
1581
- return {
1582
- status: "ok",
1583
- key,
1584
- value: await dispatch_step(member, input, child_ctx)
1585
- };
1586
- } catch (err) {
1587
- return {
1588
- status: "err",
1589
- key,
1590
- err
1591
- };
1592
- }
1593
- }));
1594
- if (ctx.abort.aborted) {
1595
- const reason = ctx.abort.reason;
1596
- throw reason instanceof Error ? reason : new aborted_error("aborted", { reason });
1597
- }
1598
- for (const s of settled) if (s.status === "err") throw s.err;
1599
- const results = /* @__PURE__ */ new Map();
1600
- for (const s of settled) if (s.status === "ok") results.set(s.key, s.value);
1601
- let current = [...keys];
1602
- const bracket = [];
1603
- let round = 0;
1604
- while (current.length > 1) {
1605
- round += 1;
1606
- const next_round = [];
1607
- for (let i = 0; i < current.length; i += 2) {
1608
- const a_id = current[i];
1609
- const b_id = current[i + 1];
1610
- if (a_id === void 0) continue;
1611
- if (b_id === void 0) {
1612
- next_round.push(a_id);
1613
- continue;
1614
- }
1615
- const a_val = results.get(a_id);
1616
- const b_val = results.get(b_id);
1617
- if (a_val === void 0 || b_val === void 0) throw new Error("tournament: missing result for match");
1618
- const winner_id = await compare_fn(a_val, b_val) === "a" ? a_id : b_id;
1619
- bracket.push({
1620
- round,
1621
- a_id,
1622
- b_id,
1623
- winner_id
1624
- });
1625
- next_round.push(winner_id);
1626
- }
1627
- current = next_round;
1628
- }
1629
- const final_id = current[0];
1630
- if (final_id === void 0) throw new Error("tournament: no winner");
1631
- const winner = results.get(final_id);
1632
- if (winner === void 0) throw new Error("tournament: winner missing from results");
1633
- return {
1634
- winner,
1635
- bracket
1636
- };
1637
- } finally {
1638
- ctx.abort.removeEventListener("abort", on_parent_abort);
1639
- }
1640
1521
  };
1522
+ const config_meta = { max_rounds: rounds_limit };
1523
+ if (name !== void 0) config_meta["display_name"] = name;
1641
1524
  return {
1642
1525
  id,
1643
- kind: "tournament",
1644
- children: child_list,
1645
- config: { keys },
1526
+ kind: "loop",
1527
+ children: guard ? [body, guard] : [body],
1528
+ config: config_meta,
1646
1529
  run: run_fn
1647
1530
  };
1648
1531
  }
1649
- register_kind("tournament", async (flow, input, ctx) => {
1650
- const span_id = ctx.trajectory.start_span("tournament", { id: flow.id });
1532
+ register_kind("loop", async (flow, input, ctx) => {
1533
+ const label = resolve_span_label(flow, "loop");
1534
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1651
1535
  try {
1652
1536
  const out = await flow.run(input, ctx);
1653
1537
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -1661,106 +1545,42 @@ register_kind("tournament", async (flow, input, ctx) => {
1661
1545
  }
1662
1546
  });
1663
1547
  //#endregion
1664
- //#region packages/core/src/consensus.ts
1548
+ //#region packages/core/src/compose.ts
1665
1549
  /**
1666
- * consensus: run until agreement.
1550
+ * compose: name a composite step.
1667
1551
  *
1668
- * `consensus({ members, agree, max_rounds })` runs every member concurrently
1669
- * with the same input. If `agree(results)` is true, returns the results with
1670
- * `converged: true`. Otherwise re-runs all members up to `max_rounds` times.
1671
- * Returns the last result with `converged: false` if no agreement.
1552
+ * `compose(name, inner)` wraps any step and labels its trajectory span with
1553
+ * `name`. The inner step's own span (e.g. a `sequence`) appears as a child of
1554
+ * the compose span — the implementation tree is preserved while the user's
1555
+ * intent ("this whole thing is an ensemble") is surfaced in observability.
1672
1556
  *
1673
- * Cancellation (constraints.md §5.1, spec.md §6.8): each member runs with a
1674
- * composed abort signal. On abort the composer awaits in-flight members
1675
- * before rethrowing `ctx.abort.reason`.
1557
+ * Used by the @repo/composites package to make built-in patterns appear under
1558
+ * their familiar names, and available to library consumers who want their own
1559
+ * named composites to show up in logs as first-class components.
1676
1560
  *
1677
- * See spec.md §5.13.
1561
+ * The primitive's `kind` is always `'compose'`; the user-supplied label lives
1562
+ * in `config.display_name` and is the span name the dispatcher opens.
1678
1563
  */
1679
- let consensus_counter = 0;
1680
- function next_id$1() {
1681
- consensus_counter += 1;
1682
- return `consensus_${consensus_counter}`;
1683
- }
1684
- function consensus(config) {
1685
- const id = next_id$1();
1686
- const entries = Object.entries(config.members);
1687
- const child_list = entries.map(([, s]) => s);
1688
- const keys = entries.map(([k]) => k);
1689
- const agree_fn = config.agree;
1690
- const rounds_limit = Math.max(1, Math.floor(config.max_rounds));
1691
- const run_fn = async (input, ctx) => {
1692
- let last_result = {};
1693
- let round = 0;
1694
- while (round < rounds_limit) {
1695
- round += 1;
1696
- if (ctx.abort.aborted) {
1697
- const reason = ctx.abort.reason;
1698
- throw reason instanceof Error ? reason : new aborted_error("aborted", { reason });
1699
- }
1700
- const controllers = entries.map(() => new AbortController());
1701
- const on_parent_abort = () => {
1702
- for (const c of controllers) c.abort(ctx.abort.reason);
1703
- };
1704
- if (ctx.abort.aborted) on_parent_abort();
1705
- else ctx.abort.addEventListener("abort", on_parent_abort, { once: true });
1706
- try {
1707
- const settled = await Promise.all(entries.map(async ([key, member], idx) => {
1708
- const local = controllers[idx];
1709
- if (!local) throw new Error("consensus: missing controller");
1710
- const composed = AbortSignal.any([ctx.abort, local.signal]);
1711
- const child_ctx = {
1712
- ...ctx,
1713
- abort: composed
1714
- };
1715
- try {
1716
- return {
1717
- status: "ok",
1718
- key,
1719
- value: await dispatch_step(member, input, child_ctx)
1720
- };
1721
- } catch (err) {
1722
- return {
1723
- status: "err",
1724
- key,
1725
- err
1726
- };
1727
- }
1728
- }));
1729
- if (ctx.abort.aborted) {
1730
- const reason = ctx.abort.reason;
1731
- throw reason instanceof Error ? reason : new aborted_error("aborted", { reason });
1732
- }
1733
- for (const s of settled) if (s.status === "err") throw s.err;
1734
- const results = {};
1735
- for (const s of settled) if (s.status === "ok") results[s.key] = s.value;
1736
- last_result = results;
1737
- if (agree_fn(results)) return {
1738
- result: results,
1739
- converged: true
1740
- };
1741
- } finally {
1742
- ctx.abort.removeEventListener("abort", on_parent_abort);
1743
- }
1744
- }
1745
- return {
1746
- result: last_result,
1747
- converged: false
1748
- };
1749
- };
1564
+ let compose_counter = 0;
1565
+ function next_id$1(name) {
1566
+ compose_counter += 1;
1567
+ return `${name}_${compose_counter}`;
1568
+ }
1569
+ function compose(name, inner) {
1570
+ if (typeof name !== "string" || name.length === 0) throw new TypeError("compose(name, inner): name must be a non-empty string");
1571
+ const id = next_id$1(name);
1572
+ const run_fn = (input, ctx) => dispatch_step(inner, input, ctx);
1750
1573
  return {
1751
1574
  id,
1752
- kind: "consensus",
1753
- children: child_list,
1754
- config: {
1755
- keys,
1756
- max_rounds: rounds_limit,
1757
- agree: agree_fn
1758
- },
1575
+ kind: "compose",
1576
+ children: [inner],
1577
+ config: { display_name: name },
1759
1578
  run: run_fn
1760
1579
  };
1761
1580
  }
1762
- register_kind("consensus", async (flow, input, ctx) => {
1763
- const span_id = ctx.trajectory.start_span("consensus", { id: flow.id });
1581
+ register_kind("compose", async (flow, input, ctx) => {
1582
+ const label = resolve_span_label(flow, "compose");
1583
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1764
1584
  try {
1765
1585
  const out = await flow.run(input, ctx);
1766
1586
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -1816,16 +1636,19 @@ function checkpoint(inner, config) {
1816
1636
  if (store) await store.set(key, result);
1817
1637
  return result;
1818
1638
  };
1639
+ const config_meta = { key: key_spec };
1640
+ if (config.name !== void 0) config_meta["display_name"] = config.name;
1819
1641
  return {
1820
1642
  id,
1821
1643
  kind: "checkpoint",
1822
1644
  children: [inner],
1823
- config: { key: key_spec },
1645
+ config: config_meta,
1824
1646
  run: run_fn
1825
1647
  };
1826
1648
  }
1827
1649
  register_kind("checkpoint", async (flow, input, ctx) => {
1828
- const span_id = ctx.trajectory.start_span("checkpoint", { id: flow.id });
1650
+ const label = resolve_span_label(flow, "checkpoint");
1651
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1829
1652
  try {
1830
1653
  const out = await flow.run(input, ctx);
1831
1654
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -1880,15 +1703,18 @@ function suspend(config) {
1880
1703
  if (is_step(result)) return dispatch_step(result, input, ctx);
1881
1704
  return result;
1882
1705
  };
1706
+ const config_meta = { id: suspend_id };
1707
+ if (config.name !== void 0) config_meta["display_name"] = config.name;
1883
1708
  return {
1884
1709
  id: suspend_id,
1885
1710
  kind: "suspend",
1886
- config: { id: suspend_id },
1711
+ config: config_meta,
1887
1712
  run: run_fn
1888
1713
  };
1889
1714
  }
1890
1715
  register_kind("suspend", async (flow, input, ctx) => {
1891
- const span_id = ctx.trajectory.start_span("suspend", { id: flow.id });
1716
+ const label = resolve_span_label(flow, "suspend");
1717
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1892
1718
  try {
1893
1719
  const out = await flow.run(input, ctx);
1894
1720
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -1937,7 +1763,7 @@ function next_use_id() {
1937
1763
  use_counter += 1;
1938
1764
  return `use_${use_counter}`;
1939
1765
  }
1940
- function scope(children) {
1766
+ function scope(children, options) {
1941
1767
  const id = next_scope_id();
1942
1768
  const children_ref = children;
1943
1769
  const run_fn = async (input, ctx) => {
@@ -1951,14 +1777,16 @@ function scope(children) {
1951
1777
  for (const child of children_ref) acc = await dispatch_step(child, acc, scope_ctx);
1952
1778
  return acc;
1953
1779
  };
1780
+ const config_meta = options?.name === void 0 ? void 0 : { display_name: options.name };
1954
1781
  return {
1955
1782
  id,
1956
1783
  kind: "scope",
1957
1784
  children,
1785
+ ...config_meta ? { config: config_meta } : {},
1958
1786
  run: run_fn
1959
1787
  };
1960
1788
  }
1961
- function stash(key, source) {
1789
+ function stash(key, source, options) {
1962
1790
  const id = next_stash_id();
1963
1791
  const run_fn = async (input, ctx) => {
1964
1792
  if (!is_scope_state(ctx.state)) throw new Error("stash() may only appear inside scope(); got: top-level");
@@ -1966,15 +1794,17 @@ function stash(key, source) {
1966
1794
  ctx.state.set(key, value);
1967
1795
  return value;
1968
1796
  };
1797
+ const config_meta = { key };
1798
+ if (options?.name !== void 0) config_meta["display_name"] = options.name;
1969
1799
  return {
1970
1800
  id,
1971
1801
  kind: "stash",
1972
1802
  children: [source],
1973
- config: { key },
1803
+ config: config_meta,
1974
1804
  run: run_fn
1975
1805
  };
1976
1806
  }
1977
- function use(keys, fn) {
1807
+ function use(keys, fn, options) {
1978
1808
  const id = next_use_id();
1979
1809
  const run_fn = async (input, ctx) => {
1980
1810
  if (!is_scope_state(ctx.state)) throw new Error("use() may only appear inside scope(); got: top-level");
@@ -1982,15 +1812,18 @@ function use(keys, fn) {
1982
1812
  for (const k of keys) projection[k] = ctx.state.get(k);
1983
1813
  return fn(projection, input, ctx);
1984
1814
  };
1815
+ const config_meta = { keys: [...keys] };
1816
+ if (options?.name !== void 0) config_meta["display_name"] = options.name;
1985
1817
  return {
1986
1818
  id,
1987
1819
  kind: "use",
1988
- config: { keys: [...keys] },
1820
+ config: config_meta,
1989
1821
  run: run_fn
1990
1822
  };
1991
1823
  }
1992
1824
  register_kind("scope", async (flow, input, ctx) => {
1993
- const span_id = ctx.trajectory.start_span("scope", { id: flow.id });
1825
+ const label = resolve_span_label(flow, "scope");
1826
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1994
1827
  try {
1995
1828
  const out = await flow.run(input, ctx);
1996
1829
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -2004,7 +1837,8 @@ register_kind("scope", async (flow, input, ctx) => {
2004
1837
  }
2005
1838
  });
2006
1839
  register_kind("stash", async (flow, input, ctx) => {
2007
- const span_id = ctx.trajectory.start_span("stash", { id: flow.id });
1840
+ const label = resolve_span_label(flow, "stash");
1841
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
2008
1842
  try {
2009
1843
  const out = await flow.run(input, ctx);
2010
1844
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -2018,7 +1852,8 @@ register_kind("stash", async (flow, input, ctx) => {
2018
1852
  }
2019
1853
  });
2020
1854
  register_kind("use", async (flow, input, ctx) => {
2021
- const span_id = ctx.trajectory.start_span("use", { id: flow.id });
1855
+ const label = resolve_span_label(flow, "use");
1856
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
2022
1857
  try {
2023
1858
  const out = await flow.run(input, ctx);
2024
1859
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -2032,8 +1867,85 @@ register_kind("use", async (flow, input, ctx) => {
2032
1867
  }
2033
1868
  });
2034
1869
  //#endregion
1870
+ //#region packages/core/src/step_kinds.ts
1871
+ /**
1872
+ * Closed registry of every `Step.kind` produced by the composition layer.
1873
+ *
1874
+ * Studio (and any other consumer that needs to enumerate primitives — palette,
1875
+ * docs, code generation) can rely on this being the exhaustive set. New
1876
+ * primitives must add their kind here. The `step_kinds_cover_runner` contract
1877
+ * test in `step_kinds.test.ts` asserts every dispatch handler corresponds to a
1878
+ * kind listed here.
1879
+ */
1880
+ const STEP_KINDS = [
1881
+ "step",
1882
+ "sequence",
1883
+ "parallel",
1884
+ "branch",
1885
+ "map",
1886
+ "pipe",
1887
+ "retry",
1888
+ "fallback",
1889
+ "timeout",
1890
+ "loop",
1891
+ "compose",
1892
+ "adversarial",
1893
+ "ensemble",
1894
+ "tournament",
1895
+ "consensus",
1896
+ "checkpoint",
1897
+ "suspend",
1898
+ "scope",
1899
+ "stash",
1900
+ "use"
1901
+ ];
1902
+ function is_step_kind(value) {
1903
+ return typeof value === "string" && STEP_KINDS.includes(value);
1904
+ }
1905
+ //#endregion
1906
+ //#region packages/core/src/trajectory.ts
1907
+ /**
1908
+ * Wire-format schema for trajectory events.
1909
+ *
1910
+ * `TrajectoryEvent` (in `types.ts`) is the loose internal type — any code that
1911
+ * calls `trajectory.record(event)` or `start_span(name, meta)` produces values
1912
+ * conforming to it. This file defines the *narrower* shapes that the studio
1913
+ * (and any other downstream consumer) can parse out of the wire stream:
1914
+ *
1915
+ * span_start — composer span open
1916
+ * span_end — composer span close
1917
+ * emit — user-emitted event from inside a step (ctx.emit)
1918
+ * <other> — falls through `custom_event_schema`, which only requires a
1919
+ * string `kind` and tolerates any extra fields
1920
+ *
1921
+ * The discriminated union is **ordered**: well-known shapes are tried before
1922
+ * the permissive `custom` schema, so a `{ kind: 'span_start', ... }` event
1923
+ * always parses as `SpanStartEvent`, never as `CustomTrajectoryEvent`.
1924
+ *
1925
+ * Every well-known schema and `custom_event_schema` use `.passthrough()` so
1926
+ * additional fields (e.g. `run_id`, `id`, provider-specific metadata) survive
1927
+ * a parse / re-serialize round-trip without loss.
1928
+ */
1929
+ const span_start_event_schema = z.object({
1930
+ kind: z.literal("span_start"),
1931
+ span_id: z.string(),
1932
+ name: z.string()
1933
+ }).passthrough();
1934
+ const span_end_event_schema = z.object({
1935
+ kind: z.literal("span_end"),
1936
+ span_id: z.string()
1937
+ }).passthrough();
1938
+ const emit_event_schema = z.object({ kind: z.literal("emit") }).passthrough();
1939
+ const custom_event_schema = z.object({ kind: z.string() }).passthrough();
1940
+ const trajectory_event_schema = z.union([
1941
+ span_start_event_schema,
1942
+ span_end_event_schema,
1943
+ emit_event_schema,
1944
+ custom_event_schema
1945
+ ]);
1946
+ //#endregion
2035
1947
  //#region packages/core/src/version.ts
2036
- const version = "0.1.13";
1948
+ const version = "0.3.3";
2037
1949
  //#endregion
2038
1950
  //#region packages/core/src/index.ts
2039
1951
  /**
@@ -2045,8 +1957,643 @@ const version = "0.1.13";
2045
1957
  */
2046
1958
  const flow_schema = flow_schema_default;
2047
1959
  //#endregion
1960
+ //#region packages/composites/src/adversarial.ts
1961
+ /**
1962
+ * adversarial: build-and-critique loop.
1963
+ *
1964
+ * `adversarial({ build, critique, accept, max_rounds })` runs up to
1965
+ * `max_rounds` iterations of: build a candidate (receiving the prior
1966
+ * candidate and critique notes when available) -> critique the candidate
1967
+ * -> check `accept(critique_result)`. Returns `{ candidate, converged,
1968
+ * rounds }`. Does not throw on non-convergence.
1969
+ *
1970
+ * Implemented as a `compose`d `loop` whose body builds a new candidate
1971
+ * and whose guard runs the critique step and checks `accept`. State is
1972
+ * threaded through `scope`/`stash`/`use` so the build and critique steps
1973
+ * remain unmodified user-supplied `Step` values.
1974
+ *
1975
+ * This file is the canonical example of how a user-built composite is
1976
+ * structured — the entire implementation is a composition of @repo/core
1977
+ * primitives. Read it as documentation.
1978
+ */
1979
+ function build_input_from_state(s) {
1980
+ if (s.candidate === void 0) return { input: s.input };
1981
+ if (s.critique_notes === void 0) return {
1982
+ input: s.input,
1983
+ prior: s.candidate
1984
+ };
1985
+ return {
1986
+ input: s.input,
1987
+ prior: s.candidate,
1988
+ critique: s.critique_notes
1989
+ };
1990
+ }
1991
+ function adversarial(config) {
1992
+ const { build, critique, accept, max_rounds } = config;
1993
+ const inner = pipe(loop({
1994
+ init: (input) => ({ input }),
1995
+ body: scope([
1996
+ stash("state", step("snapshot", (s) => s)),
1997
+ step("to_build_input", (s) => build_input_from_state(s)),
1998
+ build,
1999
+ use(["state"], (vars, candidate) => {
2000
+ return {
2001
+ ...vars["state"],
2002
+ candidate
2003
+ };
2004
+ })
2005
+ ]),
2006
+ guard: scope([
2007
+ stash("state", step("snapshot", (s) => s)),
2008
+ step("extract_candidate", (s) => {
2009
+ if (s.candidate === void 0) throw new Error("adversarial: guard reached without a candidate");
2010
+ return s.candidate;
2011
+ }),
2012
+ critique,
2013
+ use(["state"], (vars, critique_result) => {
2014
+ const prior = vars["state"];
2015
+ return {
2016
+ stop: accept(critique_result),
2017
+ state: {
2018
+ ...prior,
2019
+ last_critique: critique_result,
2020
+ critique_notes: critique_result.notes
2021
+ }
2022
+ };
2023
+ })
2024
+ ]),
2025
+ finish: (s) => {
2026
+ if (s.candidate === void 0) throw new Error("adversarial: finished without a candidate");
2027
+ return s.candidate;
2028
+ },
2029
+ max_rounds
2030
+ }), (result) => ({
2031
+ candidate: result.value,
2032
+ converged: result.converged,
2033
+ rounds: result.rounds
2034
+ }));
2035
+ return compose(config.name ?? "adversarial", inner);
2036
+ }
2037
+ //#endregion
2038
+ //#region packages/composites/src/consensus.ts
2039
+ /**
2040
+ * consensus: run-until-agreement.
2041
+ *
2042
+ * `consensus({ members, agree, max_rounds })` runs every member concurrently
2043
+ * with the same input. If `agree(results)` is true, returns the results with
2044
+ * `converged: true`. Otherwise re-runs all members up to `max_rounds` times,
2045
+ * returning the last results with `converged: false` if no agreement is
2046
+ * reached.
2047
+ *
2048
+ * Implemented as a `compose`d `loop` whose body runs `parallel(members)` and
2049
+ * whose guard evaluates `agree`. State carries the original input alongside
2050
+ * the most recent results so each round receives the same input.
2051
+ */
2052
+ function consensus(config) {
2053
+ const { members, agree, max_rounds } = config;
2054
+ const round_step = parallel(members);
2055
+ const inner = pipe(loop({
2056
+ init: (input) => ({
2057
+ input,
2058
+ results: {}
2059
+ }),
2060
+ body: scope([
2061
+ stash("state", step("snapshot", (s) => s)),
2062
+ step("extract_input", (s) => s.input),
2063
+ round_step,
2064
+ use(["state"], (vars, results) => {
2065
+ return {
2066
+ ...vars["state"],
2067
+ results
2068
+ };
2069
+ })
2070
+ ]),
2071
+ guard: step("agree", (s) => ({
2072
+ stop: agree(s.results),
2073
+ state: s
2074
+ })),
2075
+ finish: (s) => s.results,
2076
+ max_rounds
2077
+ }), (result) => ({
2078
+ result: result.value,
2079
+ converged: result.converged
2080
+ }));
2081
+ return compose(config.name ?? "consensus", inner);
2082
+ }
2083
+ //#endregion
2084
+ //#region packages/composites/src/ensemble.ts
2085
+ /**
2086
+ * ensemble: N-of-M pick-best.
2087
+ *
2088
+ * `ensemble({ members, score, select? })` runs every member concurrently with
2089
+ * the same input, scores each result, and returns the winner (highest or
2090
+ * lowest by `select`) plus the complete score map. Tie-breaking is "any tied
2091
+ * result is acceptable".
2092
+ *
2093
+ * Implemented as a `compose`d `sequence` of `parallel(members)` followed by
2094
+ * a single picking step. Cancellation, fan-out, and abort propagation come
2095
+ * from `parallel`'s own contract.
2096
+ */
2097
+ function ensemble(config) {
2098
+ const select = config.select ?? "max";
2099
+ const score_fn = config.score;
2100
+ const keys = Object.keys(config.members);
2101
+ const inner = sequence([parallel(config.members), step("pick_winner", async (results) => {
2102
+ const scores = {};
2103
+ for (const k of keys) {
2104
+ const value = results[k];
2105
+ if (value === void 0) continue;
2106
+ scores[k] = await score_fn(value, k);
2107
+ }
2108
+ let winner_key = void 0;
2109
+ let winner_score = void 0;
2110
+ for (const k of keys) {
2111
+ const current = scores[k];
2112
+ if (current === void 0) continue;
2113
+ if (winner_score === void 0) {
2114
+ winner_key = k;
2115
+ winner_score = current;
2116
+ continue;
2117
+ }
2118
+ if (select === "max" ? current > winner_score : current < winner_score) {
2119
+ winner_key = k;
2120
+ winner_score = current;
2121
+ }
2122
+ }
2123
+ if (winner_key === void 0) throw new Error("ensemble: no members produced a result");
2124
+ const winner = results[winner_key];
2125
+ if (winner === void 0) throw new Error("ensemble: winner missing from results");
2126
+ return {
2127
+ winner,
2128
+ scores
2129
+ };
2130
+ })]);
2131
+ return compose(config.name ?? "ensemble", inner);
2132
+ }
2133
+ //#endregion
2134
+ //#region packages/composites/src/ensemble_step.ts
2135
+ /**
2136
+ * ensemble_step: N-of-M pick-best with a Step-based scorer.
2137
+ *
2138
+ * `ensemble_step({ members, score, rank_by, select? })` is the sibling of
2139
+ * `ensemble` for the case where scoring is itself a `Step` (e.g. a separate
2140
+ * model call, a sub-flow, anything that wants its own trajectory span and
2141
+ * abort routing). Each member runs concurrently with the same input; the
2142
+ * `score` step is dispatched once per result; `rank_by` projects a number
2143
+ * out of the structured scored output; the highest- or lowest-ranking
2144
+ * winner is returned alongside its full structured score and the score
2145
+ * map for the rest.
2146
+ *
2147
+ * Returning `winner_scored` avoids the cost of re-scoring the winner — the
2148
+ * structured output from the round's scoring run is preserved verbatim.
2149
+ *
2150
+ * Implemented as a `compose`d `scope` over (`stash(parallel(members))` →
2151
+ * `to_pairs` → `map(score per result, threading id)` → `use` to pick
2152
+ * winner). Cancellation, fan-out, and abort propagation come from the
2153
+ * underlying `parallel` and `map` contracts.
2154
+ */
2155
+ const RESULTS_KEY = "__ensemble_step_results";
2156
+ const ITEM_KEY = "__ensemble_step_item";
2157
+ function ensemble_step(config) {
2158
+ const { members, score, rank_by } = config;
2159
+ const select = config.select ?? "max";
2160
+ const keys = Object.keys(members);
2161
+ if (keys.length === 0) throw new Error("ensemble_step: at least one member required");
2162
+ const fan_out = parallel(members);
2163
+ const score_one = scope([
2164
+ stash(ITEM_KEY, step("ensemble_step_item_snapshot", (item) => item)),
2165
+ step("ensemble_step_extract_value", (item) => item.value),
2166
+ score,
2167
+ use([ITEM_KEY], (vars, scored) => {
2168
+ return {
2169
+ id: vars[ITEM_KEY].id,
2170
+ scored
2171
+ };
2172
+ })
2173
+ ]);
2174
+ const to_pairs = step("ensemble_step_to_pairs", (results) => {
2175
+ const out = [];
2176
+ for (const id of keys) if (id in results) out.push({
2177
+ id,
2178
+ value: results[id]
2179
+ });
2180
+ return out;
2181
+ });
2182
+ const score_each = map({
2183
+ items: (pairs) => pairs,
2184
+ do: score_one
2185
+ });
2186
+ const pick = use([RESULTS_KEY], (vars, scored_pairs) => {
2187
+ const results = vars[RESULTS_KEY];
2188
+ const scored = {};
2189
+ let winner_id;
2190
+ let winner_rank;
2191
+ let winner_scored;
2192
+ for (const pair of scored_pairs) {
2193
+ scored[pair.id] = pair.scored;
2194
+ const rank = rank_by(pair.scored);
2195
+ if (winner_rank === void 0 ? true : select === "max" ? rank > winner_rank : rank < winner_rank) {
2196
+ winner_id = pair.id;
2197
+ winner_rank = rank;
2198
+ winner_scored = pair.scored;
2199
+ }
2200
+ }
2201
+ if (winner_id === void 0 || winner_scored === void 0) throw new Error("ensemble_step: no members produced a result");
2202
+ const winner = results[winner_id];
2203
+ if (winner === void 0) throw new Error("ensemble_step: winner missing from results");
2204
+ return {
2205
+ winner_id,
2206
+ winner,
2207
+ winner_scored,
2208
+ scored
2209
+ };
2210
+ });
2211
+ const inner = scope([
2212
+ stash(RESULTS_KEY, fan_out),
2213
+ to_pairs,
2214
+ score_each,
2215
+ pick
2216
+ ]);
2217
+ return compose(config.name ?? "ensemble_step", inner);
2218
+ }
2219
+ //#endregion
2220
+ //#region packages/composites/src/improve.ts
2221
+ /**
2222
+ * improve: bounded online self-improvement loop.
2223
+ *
2224
+ * `improve({ seed, propose, score, budget })` runs a round-bounded loop that
2225
+ * threads a `parent` candidate through repeated propose → score → accept/reject
2226
+ * cycles. The kernel decides acceptance via a hard gate (`scored.accepted`) and
2227
+ * an epsilon-improvement test (`scored.score > parent_score + epsilon`).
2228
+ * Plateau detection stops the loop early when no progress has been made for
2229
+ * `patience` rounds; an optional wall-clock budget caps total runtime.
2230
+ *
2231
+ * `improve` is the *online* counterpart to `learn`: where `learn` reflects on
2232
+ * recorded trajectories offline, `improve` runs the propose/score loop live
2233
+ * inside a single run. The amplify example is a domain-specific consumer of
2234
+ * this same pattern (filesystem mutation, test-suite gates, subprocess
2235
+ * research). `improve` strips those opinions out so any domain can plug in
2236
+ * its own `propose` and `score` steps.
2237
+ *
2238
+ * Implemented as a `compose`d `scope` of (seed) → (init state) → (loop) →
2239
+ * (unwrap). The loop body is itself a small `scope` that snapshots prior
2240
+ * state, builds a round input, dispatches the proposers + scorer via
2241
+ * `ensemble_step`, and merges the outcome back into state via `use`.
2242
+ * State threading is the entire job.
2243
+ */
2244
+ const PRIOR_KEY = "__improve_prior";
2245
+ function improve(config) {
2246
+ const { seed, propose, score, budget } = config;
2247
+ const epsilon = config.epsilon ?? 0;
2248
+ const proposers_per_round = Math.max(1, config.proposers_per_round ?? 1);
2249
+ const lessons_capacity = Math.max(0, config.lessons_capacity ?? 5);
2250
+ const { max_rounds, max_wallclock_ms, patience } = budget;
2251
+ const proposers = {};
2252
+ for (let i = 0; i < proposers_per_round; i += 1) proposers[`p${String(i)}`] = propose;
2253
+ const round_ensemble = ensemble_step({
2254
+ name: "improve_round",
2255
+ members: proposers,
2256
+ score,
2257
+ rank_by: (s) => s.score
2258
+ });
2259
+ const project_round = use([PRIOR_KEY], (vars, ensemble_result, ctx) => {
2260
+ const round = vars[PRIOR_KEY].round + 1;
2261
+ for (const slot_id of Object.keys(ensemble_result.scored)) {
2262
+ const scored = ensemble_result.scored[slot_id];
2263
+ if (scored === void 0) continue;
2264
+ ctx.trajectory.record({
2265
+ kind: "improve.candidate",
2266
+ round,
2267
+ proposer_id: slot_id,
2268
+ score: scored.score,
2269
+ accepted: scored.accepted,
2270
+ ...scored.reason === void 0 ? {} : { reason: scored.reason }
2271
+ });
2272
+ }
2273
+ const w = ensemble_result.winner_scored;
2274
+ return {
2275
+ ...w,
2276
+ candidate: {
2277
+ ...w.candidate,
2278
+ proposer_id: ensemble_result.winner_id
2279
+ }
2280
+ };
2281
+ });
2282
+ const init_state = step("improve_init_state", (seed_result) => ({
2283
+ parent: seed_result.content,
2284
+ parent_score: seed_result.score,
2285
+ round: 0,
2286
+ rounds_since_progress: 0,
2287
+ started_at_ms: Date.now(),
2288
+ history: [],
2289
+ lessons: []
2290
+ }));
2291
+ const to_round_input = step("improve_to_round_input", (s, ctx) => {
2292
+ const round = s.round + 1;
2293
+ ctx.trajectory.record({
2294
+ kind: "improve.round_start",
2295
+ round,
2296
+ parent_score: s.parent_score,
2297
+ lessons_count: s.lessons.length
2298
+ });
2299
+ return {
2300
+ parent: s.parent,
2301
+ parent_score: s.parent_score,
2302
+ round,
2303
+ lessons: s.lessons
2304
+ };
2305
+ });
2306
+ const merge_outcome = use([PRIOR_KEY], (vars, scored, ctx) => {
2307
+ const prior = vars[PRIOR_KEY];
2308
+ const next_round = prior.round + 1;
2309
+ const better = scored.score > prior.parent_score + epsilon;
2310
+ const accepted = scored.accepted && better;
2311
+ const next_lessons = !accepted && scored.reason !== void 0 ? [...prior.lessons, {
2312
+ round: next_round,
2313
+ proposer_id: scored.candidate.proposer_id,
2314
+ reason: scored.reason
2315
+ }].slice(-lessons_capacity) : prior.lessons;
2316
+ ctx.trajectory.record({
2317
+ kind: accepted ? "improve.accept" : "improve.reject",
2318
+ round: next_round,
2319
+ proposer_id: scored.candidate.proposer_id,
2320
+ score: scored.score,
2321
+ prior_score: prior.parent_score,
2322
+ ...accepted ? { delta: scored.score - prior.parent_score } : {},
2323
+ ...scored.reason === void 0 ? {} : { reason: scored.reason }
2324
+ });
2325
+ return {
2326
+ parent: accepted ? scored.candidate.content : prior.parent,
2327
+ parent_score: accepted ? scored.score : prior.parent_score,
2328
+ round: next_round,
2329
+ rounds_since_progress: accepted ? 0 : prior.rounds_since_progress + 1,
2330
+ started_at_ms: prior.started_at_ms,
2331
+ history: [...prior.history, {
2332
+ round: next_round,
2333
+ winner: scored,
2334
+ accepted
2335
+ }],
2336
+ lessons: next_lessons
2337
+ };
2338
+ });
2339
+ const inner = scope([
2340
+ seed,
2341
+ init_state,
2342
+ loop({
2343
+ init: (s) => s,
2344
+ body: scope([
2345
+ stash(PRIOR_KEY, step("improve_snapshot", (s) => s)),
2346
+ to_round_input,
2347
+ round_ensemble,
2348
+ project_round,
2349
+ merge_outcome
2350
+ ]),
2351
+ guard: step("improve_guard", (s) => {
2352
+ if (s.rounds_since_progress >= patience) return {
2353
+ stop: true,
2354
+ state: {
2355
+ ...s,
2356
+ stopped_by: "plateau"
2357
+ }
2358
+ };
2359
+ if (max_wallclock_ms !== void 0 && Date.now() - s.started_at_ms >= max_wallclock_ms) return {
2360
+ stop: true,
2361
+ state: {
2362
+ ...s,
2363
+ stopped_by: "budget"
2364
+ }
2365
+ };
2366
+ return {
2367
+ stop: false,
2368
+ state: s
2369
+ };
2370
+ }),
2371
+ finish: (s) => ({
2372
+ best: {
2373
+ content: s.parent,
2374
+ score: s.parent_score
2375
+ },
2376
+ rounds_used: s.round,
2377
+ stopped_by: s.stopped_by ?? "budget",
2378
+ history: s.history
2379
+ }),
2380
+ max_rounds
2381
+ }),
2382
+ step("improve_unwrap", (result, ctx) => {
2383
+ ctx.trajectory.record({
2384
+ kind: "improve.stop",
2385
+ stopped_by: result.value.stopped_by,
2386
+ rounds_used: result.value.rounds_used,
2387
+ final_score: result.value.best.score
2388
+ });
2389
+ return result.value;
2390
+ })
2391
+ ]);
2392
+ return compose(config.name ?? "improve", inner);
2393
+ }
2394
+ //#endregion
2395
+ //#region packages/composites/src/learn.ts
2396
+ /**
2397
+ * learn: offline self-improvement composer.
2398
+ *
2399
+ * `learn({ flow, source, analyzer })` reads recorded trajectory events from
2400
+ * past runs of `flow`, hands them to a user-supplied `analyzer` step alongside
2401
+ * `describe(flow)`, and returns the analyzer's proposals plus summary metadata
2402
+ * (events considered, distinct run ids).
2403
+ *
2404
+ * The amplify example is the *online* counterpart of this pattern: propose →
2405
+ * score → accept/reject inside a single run. `learn` is the *offline*
2406
+ * counterpart: reflect on what already happened across one or many recorded
2407
+ * runs without an evaluator in the loop.
2408
+ *
2409
+ * Implemented as a `compose`d `scope` of (compute meta) → (build LearnInput) →
2410
+ * (analyzer) → (wrap result with meta). No engine dependency; the analyzer
2411
+ * decides how to use the events.
2412
+ *
2413
+ * Three source kinds: `events` (in-memory), `paths` (explicit JSONL files),
2414
+ * `dir` (recursive *.jsonl walk). File reads honor `ctx.abort` at file-level
2415
+ * granularity; malformed lines are skipped and surface as `learn.parse_error`
2416
+ * trajectory events with 1-indexed line offsets. When `max_events` clips the
2417
+ * filtered set, a `learn.truncated` event records `available`, `kept`, and the
2418
+ * configured cap.
2419
+ */
2420
+ const DEFAULT_MAX_EVENTS = 1e4;
2421
+ const META_KEY = "__learn_meta";
2422
+ async function walk_jsonl(dir) {
2423
+ const out = [];
2424
+ const entries = await readdir(dir, { withFileTypes: true });
2425
+ for (const entry of entries) {
2426
+ const full = join(dir, entry.name);
2427
+ if (entry.isDirectory()) out.push(...await walk_jsonl(full));
2428
+ else if (entry.isFile() && entry.name.endsWith(".jsonl")) out.push(full);
2429
+ }
2430
+ return out;
2431
+ }
2432
+ async function read_jsonl(file_path, ctx) {
2433
+ const lines = (await readFile(file_path, "utf8")).split("\n");
2434
+ const events = [];
2435
+ for (let i = 0; i < lines.length; i += 1) {
2436
+ const raw = lines[i];
2437
+ if (raw === void 0 || raw.trim() === "") continue;
2438
+ let parsed;
2439
+ try {
2440
+ parsed = JSON.parse(raw);
2441
+ } catch {
2442
+ ctx.trajectory.record({
2443
+ kind: "learn.parse_error",
2444
+ path: file_path,
2445
+ line: i + 1
2446
+ });
2447
+ continue;
2448
+ }
2449
+ const result = trajectory_event_schema.safeParse(parsed);
2450
+ if (result.success) events.push(result.data);
2451
+ else ctx.trajectory.record({
2452
+ kind: "learn.parse_error",
2453
+ path: file_path,
2454
+ line: i + 1
2455
+ });
2456
+ }
2457
+ return events;
2458
+ }
2459
+ function throw_if_aborted$1(ctx) {
2460
+ if (!ctx.abort.aborted) return;
2461
+ const reason = ctx.abort.reason;
2462
+ if (reason instanceof aborted_error) throw reason;
2463
+ throw new aborted_error("aborted", reason === void 0 ? {} : { reason });
2464
+ }
2465
+ async function resolve_events(source, ctx) {
2466
+ if (source.kind === "events") return source.events;
2467
+ const file_paths = source.kind === "paths" ? [...source.paths] : (await walk_jsonl(source.dir)).toSorted();
2468
+ const all = [];
2469
+ for (const p of file_paths) {
2470
+ throw_if_aborted$1(ctx);
2471
+ const events = await read_jsonl(p, ctx);
2472
+ all.push(...events);
2473
+ }
2474
+ return all;
2475
+ }
2476
+ function collect_run_ids(events) {
2477
+ const seen = /* @__PURE__ */ new Set();
2478
+ const out = [];
2479
+ for (const event of events) {
2480
+ const id = event["run_id"];
2481
+ if (typeof id === "string" && !seen.has(id)) {
2482
+ seen.add(id);
2483
+ out.push(id);
2484
+ }
2485
+ }
2486
+ return out;
2487
+ }
2488
+ function learn(config) {
2489
+ const { flow, source, analyzer, filter } = config;
2490
+ const max = config.max_events ?? DEFAULT_MAX_EVENTS;
2491
+ const compute_meta = step("learn_compute_meta", async (prior, ctx) => {
2492
+ const all = await resolve_events(source, ctx);
2493
+ const filtered = filter ? all.filter(filter) : all;
2494
+ const truncated = filtered.length > max;
2495
+ const capped = truncated ? filtered.slice(0, max) : filtered;
2496
+ if (truncated) ctx.trajectory.record({
2497
+ kind: "learn.truncated",
2498
+ available: filtered.length,
2499
+ kept: capped.length,
2500
+ max_events: max
2501
+ });
2502
+ return {
2503
+ events_considered: capped.length,
2504
+ run_ids: collect_run_ids(capped),
2505
+ events: capped,
2506
+ prior
2507
+ };
2508
+ });
2509
+ const build_input = step("learn_build_input", (meta) => ({
2510
+ flow_description: describe(flow),
2511
+ events: meta.events,
2512
+ prior: meta.prior
2513
+ }));
2514
+ const wrap_result = use([META_KEY], (vars, proposals, ctx) => {
2515
+ const meta = vars[META_KEY];
2516
+ ctx.trajectory.record({
2517
+ kind: "learn.summary",
2518
+ events_considered: meta.events_considered,
2519
+ run_ids: meta.run_ids
2520
+ });
2521
+ return {
2522
+ proposals,
2523
+ events_considered: meta.events_considered,
2524
+ run_ids: meta.run_ids
2525
+ };
2526
+ });
2527
+ const inner = scope([
2528
+ stash(META_KEY, compute_meta),
2529
+ build_input,
2530
+ analyzer,
2531
+ wrap_result
2532
+ ]);
2533
+ return compose(config.name ?? "learn", inner);
2534
+ }
2535
+ //#endregion
2536
+ //#region packages/composites/src/tournament.ts
2537
+ /**
2538
+ * tournament: pairwise bracket.
2539
+ *
2540
+ * `tournament({ members, compare })` runs every member, then pairs them off
2541
+ * in a single-elimination bracket. `compare(a, b)` returns which result
2542
+ * advances. An odd member count yields one bye per affected round. Returns
2543
+ * `{ winner, bracket }` where `bracket` lists every match record.
2544
+ *
2545
+ * Implemented as a `compose`d `sequence` of `parallel(members)` followed
2546
+ * by a single bracket-reduction step. Cancellation, fan-out, and abort
2547
+ * propagation come from `parallel`'s contract; the bracket step only runs
2548
+ * after all members settle.
2549
+ */
2550
+ function tournament(config) {
2551
+ const compare_fn = config.compare;
2552
+ const keys = Object.keys(config.members);
2553
+ if (keys.length === 0) throw new Error("tournament: at least one member required");
2554
+ const inner = sequence([parallel(config.members), step("bracket", async (results) => {
2555
+ let current = [...keys];
2556
+ const bracket = [];
2557
+ let round = 0;
2558
+ while (current.length > 1) {
2559
+ round += 1;
2560
+ const next_round = [];
2561
+ for (let i = 0; i < current.length; i += 2) {
2562
+ const a_id = current[i];
2563
+ const b_id = current[i + 1];
2564
+ if (a_id === void 0) continue;
2565
+ if (b_id === void 0) {
2566
+ next_round.push(a_id);
2567
+ continue;
2568
+ }
2569
+ const a_val = results[a_id];
2570
+ const b_val = results[b_id];
2571
+ if (a_val === void 0 || b_val === void 0) throw new Error("tournament: missing result for match");
2572
+ const winner_id = await compare_fn(a_val, b_val) === "a" ? a_id : b_id;
2573
+ bracket.push({
2574
+ round,
2575
+ a_id,
2576
+ b_id,
2577
+ winner_id
2578
+ });
2579
+ next_round.push(winner_id);
2580
+ }
2581
+ current = next_round;
2582
+ }
2583
+ const final_id = current[0];
2584
+ if (final_id === void 0) throw new Error("tournament: no winner");
2585
+ const winner = results[final_id];
2586
+ if (winner === void 0) throw new Error("tournament: winner missing from results");
2587
+ return {
2588
+ winner,
2589
+ bracket
2590
+ };
2591
+ })]);
2592
+ return compose(config.name ?? "tournament", inner);
2593
+ }
2594
+ //#endregion
2048
2595
  //#region packages/engine/src/version.ts
2049
- const version$1 = "0.1.13";
2596
+ const version$1 = "0.3.3";
2050
2597
  //#endregion
2051
2598
  //#region packages/engine/src/errors.ts
2052
2599
  var rate_limit_error = class extends Error {
@@ -2588,7 +3135,9 @@ const ANTHROPIC_THINKING_BUDGETS = {
2588
3135
  none: 0,
2589
3136
  low: 1024,
2590
3137
  medium: 5e3,
2591
- high: 2e4
3138
+ high: 2e4,
3139
+ xhigh: 32e3,
3140
+ max: 64e3
2592
3141
  };
2593
3142
  function translate_anthropic_effort(effort) {
2594
3143
  const budget = ANTHROPIC_THINKING_BUDGETS[effort];
@@ -2638,7 +3187,9 @@ const create_anthropic_adapter = (init) => {
2638
3187
  const OPENAI_REASONING_EFFORT = {
2639
3188
  low: "low",
2640
3189
  medium: "medium",
2641
- high: "high"
3190
+ high: "high",
3191
+ xhigh: "high",
3192
+ max: "high"
2642
3193
  };
2643
3194
  function translate_openai_effort(effort) {
2644
3195
  if (effort === "none") return {
@@ -2686,7 +3237,9 @@ const create_openai_adapter = (init) => {
2686
3237
  const GOOGLE_THINKING_BUDGET = {
2687
3238
  low: "low",
2688
3239
  medium: "medium",
2689
- high: "high"
3240
+ high: "high",
3241
+ xhigh: "high",
3242
+ max: "high"
2690
3243
  };
2691
3244
  function translate_google_effort(effort) {
2692
3245
  if (effort === "none") return {
@@ -3955,9 +4508,21 @@ const SUPPORTED = new Set([
3955
4508
  "text",
3956
4509
  "tools",
3957
4510
  "schema",
3958
- "streaming"
4511
+ "streaming",
4512
+ "reasoning"
3959
4513
  ]);
3960
4514
  const PROVIDER_NAME = "claude_cli";
4515
+ const CLAUDE_CLI_EFFORT_VALUES = {
4516
+ low: "low",
4517
+ medium: "medium",
4518
+ high: "high",
4519
+ xhigh: "xhigh",
4520
+ max: "max"
4521
+ };
4522
+ function effort_env_for_claude_cli(effort) {
4523
+ if (effort === void 0 || effort === "none") return {};
4524
+ return { CLAUDE_CODE_EFFORT_LEVEL: CLAUDE_CLI_EFFORT_VALUES[effort] };
4525
+ }
3961
4526
  function extract_call_opts(opts) {
3962
4527
  const raw = opts.provider_options?.["claude_cli"];
3963
4528
  if (raw === void 0 || raw === null || typeof raw !== "object") return {};
@@ -4088,6 +4653,7 @@ function create_claude_cli_adapter(init) {
4088
4653
  const merged_system = merge_system(opts.system ?? system_from_prompt, call_opts.append_system_prompt);
4089
4654
  const stdin_text = extract_prompt_text(opts.prompt);
4090
4655
  const env = build_env(config, call_opts.env, resolved_auth_mode);
4656
+ Object.assign(env, effort_env_for_claude_cli(opts.effort));
4091
4657
  const sandbox_plan = build_sandbox_plan(resolved_binary, config.sandbox);
4092
4658
  const cwd = config.default_cwd;
4093
4659
  const dispatch_chunk = opts.on_chunk !== void 0 ? async (chunk) => {
@@ -5527,6 +6093,6 @@ function forward_standard_env() {
5527
6093
  return out;
5528
6094
  }
5529
6095
  //#endregion
5530
- export { aborted_error, adversarial, branch, checkpoint, consensus, version as core_version, create_engine, describe, describe_cycle_error, engine_config_error, version$1 as engine_version, ensemble, fallback, flow_schema, forward_standard_env, map, model_call, model_not_found_error, on_chunk_error, parallel, pipe, provider_capability_error, provider_error, provider_not_configured_error, rate_limit_error, resume_validation_error, retry, run, schema_validation_error, scope, sequence, stash, step, suspend, suspended_error, timeout, timeout_error, tool_approval_denied_error, tool_error, tournament, use };
6096
+ export { STEP_KINDS, aborted_error, adversarial, branch, checkpoint, compose, consensus, version as core_version, create_engine, custom_event_schema, describe, describe_cycle_error, emit_event_schema, engine_config_error, version$1 as engine_version, ensemble, ensemble_step, fallback, flow_schema, forward_standard_env, improve, is_step_kind, learn, loop, map, model_call, model_not_found_error, on_chunk_error, parallel, pipe, provider_capability_error, provider_error, provider_not_configured_error, rate_limit_error, resume_validation_error, retry, run, schema_validation_error, scope, sequence, span_end_event_schema, span_start_event_schema, stash, step, suspend, suspended_error, timeout, timeout_error, tool_approval_denied_error, tool_error, tournament, trajectory_event_schema, use };
5531
6097
 
5532
6098
  //# sourceMappingURL=index.js.map