fascicle 0.1.13 → 0.3.8

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,7 +1,13 @@
1
1
  import { createHash, randomUUID } from "node:crypto";
2
2
  import { z } from "zod";
3
+ import { mkdir, open, readFile, readdir, stat, writeFile } from "node:fs/promises";
4
+ import { dirname, join, resolve } from "node:path";
5
+ import { appendFileSync, createReadStream, existsSync, mkdirSync, statSync, watch } from "node:fs";
3
6
  import { spawn } from "node:child_process";
4
7
  import { generateText, stepCountIs, streamText, tool } from "ai";
8
+ import { createServer } from "node:http";
9
+ import { fileURLToPath } from "node:url";
10
+ import { parseArgs } from "node:util";
5
11
  //#region packages/core/src/flow-schema.json
6
12
  var flow_schema_default = {
7
13
  $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -29,6 +35,8 @@ var flow_schema_default = {
29
35
  { "required": ["retry"] },
30
36
  { "required": ["fallback"] },
31
37
  { "required": ["timeout"] },
38
+ { "required": ["loop"] },
39
+ { "required": ["compose_node"] },
32
40
  { "required": ["adversarial"] },
33
41
  { "required": ["ensemble"] },
34
42
  { "required": ["tournament"] },
@@ -48,6 +56,8 @@ var flow_schema_default = {
48
56
  "retry": { "$ref": "#/$defs/retry_config" },
49
57
  "fallback": { "$ref": "#/$defs/fallback_config" },
50
58
  "timeout": { "$ref": "#/$defs/timeout_config" },
59
+ "loop": { "$ref": "#/$defs/loop_config" },
60
+ "compose_node": { "$ref": "#/$defs/compose_node_config" },
51
61
  "adversarial": { "$ref": "#/$defs/adversarial_config" },
52
62
  "ensemble": { "$ref": "#/$defs/ensemble_config" },
53
63
  "tournament": { "$ref": "#/$defs/tournament_config" },
@@ -141,6 +151,35 @@ var flow_schema_default = {
141
151
  }
142
152
  }
143
153
  },
154
+ "compose_node_config": {
155
+ "type": "object",
156
+ "required": ["name", "do"],
157
+ "properties": {
158
+ "name": {
159
+ "type": "string",
160
+ "minLength": 1
161
+ },
162
+ "do": { "$ref": "#/$defs/node" }
163
+ }
164
+ },
165
+ "loop_config": {
166
+ "type": "object",
167
+ "required": ["body", "max_rounds"],
168
+ "properties": {
169
+ "name": {
170
+ "type": "string",
171
+ "minLength": 1
172
+ },
173
+ "init": { "type": "string" },
174
+ "body": { "$ref": "#/$defs/node" },
175
+ "guard": { "$ref": "#/$defs/node" },
176
+ "finish": { "type": "string" },
177
+ "max_rounds": {
178
+ "type": "integer",
179
+ "minimum": 1
180
+ }
181
+ }
182
+ },
144
183
  "adversarial_config": {
145
184
  "type": "object",
146
185
  "required": [
@@ -490,6 +529,19 @@ const dispatch = /* @__PURE__ */ new Map();
490
529
  function register_kind(kind, fn) {
491
530
  dispatch.set(kind, fn);
492
531
  }
532
+ /**
533
+ * Resolve the trajectory span label for a step. Prefers a non-empty
534
+ * `display_name` from `flow.config`; otherwise falls back to the supplied
535
+ * default (typically the step's `kind`).
536
+ *
537
+ * Dispatch handlers use this so that any composer carrying a user-supplied
538
+ * `name` surfaces under that label in the trajectory, while unconfigured
539
+ * composers retain their kind-based label.
540
+ */
541
+ function resolve_span_label(flow, fallback) {
542
+ const display = flow.config?.["display_name"];
543
+ return typeof display === "string" && display.length > 0 ? display : fallback;
544
+ }
493
545
  const active_runs = /* @__PURE__ */ new Set();
494
546
  let signal_handler_installed = false;
495
547
  let sigint_handler = null;
@@ -519,6 +571,44 @@ const noop_logger = {
519
571
  start_span: (name) => `${name}:${randomUUID().slice(0, 8)}`,
520
572
  end_span: () => {}
521
573
  };
574
+ /**
575
+ * Wrap a logger so every emitted event automatically carries `run_id`.
576
+ *
577
+ * Studios and other downstream consumers can multiplex events across runs
578
+ * by reading this field. Callers may still set their own `run_id` on a record;
579
+ * we don't overwrite it.
580
+ */
581
+ function stamp_run_id(inner, run_id) {
582
+ return {
583
+ record: (event) => {
584
+ if ("run_id" in event) {
585
+ inner.record(event);
586
+ return;
587
+ }
588
+ inner.record({
589
+ ...event,
590
+ run_id
591
+ });
592
+ },
593
+ start_span: (name, meta) => {
594
+ if (meta && "run_id" in meta) return inner.start_span(name, meta);
595
+ return inner.start_span(name, {
596
+ ...meta,
597
+ run_id
598
+ });
599
+ },
600
+ end_span: (id, meta) => {
601
+ if (meta && "run_id" in meta) {
602
+ inner.end_span(id, meta);
603
+ return;
604
+ }
605
+ inner.end_span(id, {
606
+ ...meta,
607
+ run_id
608
+ });
609
+ }
610
+ };
611
+ }
522
612
  async function dispatch_step(flow, input, ctx) {
523
613
  const handler = dispatch.get(flow.kind);
524
614
  if (!handler) throw new Error(`unknown step kind: ${flow.kind} (step id: ${flow.id})`);
@@ -539,19 +629,20 @@ function start_run(flow, input, options, high_water_mark) {
539
629
  const install_signal_handlers = options.install_signal_handlers !== false;
540
630
  const base_logger = options.trajectory ?? noop_logger;
541
631
  const streaming = high_water_mark !== null;
542
- let logger = base_logger;
632
+ const controller = new AbortController();
633
+ const run_id = randomUUID();
634
+ let logger = stamp_run_id(base_logger, run_id);
543
635
  let stream_events = empty_async_iterable();
544
636
  let close_stream = null;
545
637
  if (streaming) {
546
- const channel = create_streaming_channel(base_logger, high_water_mark);
638
+ const channel = create_streaming_channel(logger, high_water_mark);
547
639
  logger = channel.logger;
548
640
  stream_events = channel.events;
549
641
  close_stream = channel.close;
550
642
  }
551
- const controller = new AbortController();
552
643
  const cleanup = create_cleanup_registry(logger);
553
644
  const ctx = {
554
- run_id: randomUUID(),
645
+ run_id,
555
646
  trajectory: logger,
556
647
  state: /* @__PURE__ */ new Map(),
557
648
  abort: controller.signal,
@@ -619,9 +710,12 @@ const run = Object.assign(run_impl, { stream: run_stream });
619
710
  /**
620
711
  * step() factory.
621
712
  *
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.
713
+ * Three forms:
714
+ * step(id, fn) — named step. id is rendered in trajectory spans and describe().
715
+ * step(id, fn, meta) — named step with optional human-readable metadata for studio,
716
+ * codegen, and similar consumers. `meta` is purely descriptive
717
+ * and never affects runtime semantics.
718
+ * step(fn) — anonymous step. id is `anon_<counter>`; cannot be checkpointed.
625
719
  *
626
720
  * Anonymous steps carry an internal `anonymous: true` flag so checkpoint can
627
721
  * reject them synchronously at flow construction time (spec.md §9 F6 / §7 invariant 8).
@@ -631,7 +725,7 @@ function next_anon_id() {
631
725
  anon_counter += 1;
632
726
  return `anon_${anon_counter}`;
633
727
  }
634
- function step(id_or_fn, maybe_fn) {
728
+ function step(id_or_fn, maybe_fn, meta) {
635
729
  if (typeof id_or_fn === "function") return {
636
730
  id: next_anon_id(),
637
731
  kind: "step",
@@ -639,6 +733,12 @@ function step(id_or_fn, maybe_fn) {
639
733
  anonymous: true
640
734
  };
641
735
  if (typeof maybe_fn !== "function") throw new TypeError("step(id, fn): fn must be a function");
736
+ if (meta) return {
737
+ id: id_or_fn,
738
+ kind: "step",
739
+ run: maybe_fn,
740
+ meta
741
+ };
642
742
  return {
643
743
  id: id_or_fn,
644
744
  kind: "step",
@@ -698,8 +798,13 @@ function render_text(node, depth, lines, path, strict) {
698
798
  }
699
799
  path.add(node);
700
800
  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)}`);
801
+ const display = node.config?.["display_name"];
802
+ const label = typeof display === "string" && display.length > 0 ? display : node.kind;
803
+ lines.push(`${prefix}${label}(${node.id})`);
804
+ if (node.config) for (const [key, value] of Object.entries(node.config)) {
805
+ if (key === "display_name") continue;
806
+ lines.push(`${prefix}${INDENT}${key}: ${render_value_text(value, path, strict)}`);
807
+ }
703
808
  if (node.children && node.children.length > 0) for (const child of node.children) render_text(child, depth + 1, lines, path, strict);
704
809
  } finally {
705
810
  path.delete(node);
@@ -748,6 +853,7 @@ function render_json(node, path, strict) {
748
853
  result.config = config;
749
854
  }
750
855
  if (node.children && node.children.length > 0) result.children = node.children.map((child) => render_json(child, path, strict));
856
+ if (node.meta) result.meta = node.meta;
751
857
  return result;
752
858
  } finally {
753
859
  path.delete(node);
@@ -811,27 +917,30 @@ function is_zod_schema(value) {
811
917
  * See spec.md §5.2 and §6.1.
812
918
  */
813
919
  let sequence_counter = 0;
814
- function next_id$12() {
920
+ function next_id$10() {
815
921
  sequence_counter += 1;
816
922
  return `sequence_${sequence_counter}`;
817
923
  }
818
- function sequence(children) {
819
- const id = next_id$12();
924
+ function sequence(children, options) {
925
+ const id = next_id$10();
820
926
  const children_ref = children;
821
927
  const run_fn = async (input, ctx) => {
822
928
  let acc = input;
823
929
  for (const child of children_ref) acc = await dispatch_step(child, acc, ctx);
824
930
  return acc;
825
931
  };
932
+ const config_meta = options?.name === void 0 ? void 0 : { display_name: options.name };
826
933
  return {
827
934
  id,
828
935
  kind: "sequence",
829
936
  children,
937
+ ...config_meta ? { config: config_meta } : {},
830
938
  run: run_fn
831
939
  };
832
940
  }
833
941
  register_kind("sequence", async (flow, input, ctx) => {
834
- const span_id = ctx.trajectory.start_span("sequence", { id: flow.id });
942
+ const label = resolve_span_label(flow, "sequence");
943
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
835
944
  try {
836
945
  const out = await flow.run(input, ctx);
837
946
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -860,12 +969,12 @@ register_kind("sequence", async (flow, input, ctx) => {
860
969
  * "agent-pattern" composer contract in spec.md §6.8.
861
970
  */
862
971
  let parallel_counter = 0;
863
- function next_id$11() {
972
+ function next_id$9() {
864
973
  parallel_counter += 1;
865
974
  return `parallel_${parallel_counter}`;
866
975
  }
867
- function parallel(members) {
868
- const id = next_id$11();
976
+ function parallel(members, options) {
977
+ const id = next_id$9();
869
978
  const entries = Object.entries(members);
870
979
  const child_list = entries.map(([, s]) => s);
871
980
  const keys = entries.map(([k]) => k);
@@ -911,16 +1020,19 @@ function parallel(members) {
911
1020
  ctx.abort.removeEventListener("abort", on_parent_abort);
912
1021
  }
913
1022
  };
1023
+ const config_meta = { keys };
1024
+ if (options?.name !== void 0) config_meta["display_name"] = options.name;
914
1025
  return {
915
1026
  id,
916
1027
  kind: "parallel",
917
1028
  children: child_list,
918
- config: { keys },
1029
+ config: config_meta,
919
1030
  run: run_fn
920
1031
  };
921
1032
  }
922
1033
  register_kind("parallel", async (flow, input, ctx) => {
923
- const span_id = ctx.trajectory.start_span("parallel", { id: flow.id });
1034
+ const label = resolve_span_label(flow, "parallel");
1035
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
924
1036
  try {
925
1037
  const out = await flow.run(input, ctx);
926
1038
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -945,30 +1057,33 @@ register_kind("parallel", async (flow, input, ctx) => {
945
1057
  * See spec.md §5.4.
946
1058
  */
947
1059
  let branch_counter = 0;
948
- function next_id$10() {
1060
+ function next_id$8() {
949
1061
  branch_counter += 1;
950
1062
  return `branch_${branch_counter}`;
951
1063
  }
952
1064
  function branch(config) {
953
- const id = next_id$10();
954
- const { when, then: then_step, otherwise: otherwise_step } = config;
1065
+ const id = next_id$8();
1066
+ const { when, then: then_step, otherwise: otherwise_step, name } = config;
955
1067
  const run_fn = async (input, ctx) => {
956
1068
  return dispatch_step(await when(input) ? then_step : otherwise_step, input, ctx);
957
1069
  };
1070
+ const config_meta = {
1071
+ when,
1072
+ then: then_step,
1073
+ otherwise: otherwise_step
1074
+ };
1075
+ if (name !== void 0) config_meta["display_name"] = name;
958
1076
  return {
959
1077
  id,
960
1078
  kind: "branch",
961
1079
  children: [then_step, otherwise_step],
962
- config: {
963
- when,
964
- then: then_step,
965
- otherwise: otherwise_step
966
- },
1080
+ config: config_meta,
967
1081
  run: run_fn
968
1082
  };
969
1083
  }
970
1084
  register_kind("branch", async (flow, input, ctx) => {
971
- const span_id = ctx.trajectory.start_span("branch", { id: flow.id });
1085
+ const label = resolve_span_label(flow, "branch");
1086
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
972
1087
  try {
973
1088
  const out = await flow.run(input, ctx);
974
1089
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -997,13 +1112,13 @@ register_kind("branch", async (flow, input, ctx) => {
997
1112
  * rethrowing `ctx.abort.reason`.
998
1113
  */
999
1114
  let map_counter = 0;
1000
- function next_id$9() {
1115
+ function next_id$7() {
1001
1116
  map_counter += 1;
1002
1117
  return `map_${map_counter}`;
1003
1118
  }
1004
1119
  function map(config) {
1005
- const id = next_id$9();
1006
- const { items, do: per_item, concurrency } = config;
1120
+ const id = next_id$7();
1121
+ const { items, do: per_item, concurrency, name } = config;
1007
1122
  const run_fn = async (input, ctx) => {
1008
1123
  const list = await items(input);
1009
1124
  if (list.length === 0) return [];
@@ -1057,19 +1172,20 @@ function map(config) {
1057
1172
  ctx.abort.removeEventListener("abort", on_parent_abort);
1058
1173
  }
1059
1174
  };
1175
+ const config_meta = { items };
1176
+ if (concurrency !== void 0) config_meta["concurrency"] = concurrency;
1177
+ if (name !== void 0) config_meta["display_name"] = name;
1060
1178
  return {
1061
1179
  id,
1062
1180
  kind: "map",
1063
1181
  children: [per_item],
1064
- ...concurrency === void 0 ? { config: { items } } : { config: {
1065
- items,
1066
- concurrency
1067
- } },
1182
+ config: config_meta,
1068
1183
  run: run_fn
1069
1184
  };
1070
1185
  }
1071
1186
  register_kind("map", async (flow, input, ctx) => {
1072
- const span_id = ctx.trajectory.start_span("map", { id: flow.id });
1187
+ const label = resolve_span_label(flow, "map");
1188
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1073
1189
  try {
1074
1190
  const out = await flow.run(input, ctx);
1075
1191
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -1093,25 +1209,28 @@ register_kind("map", async (flow, input, ctx) => {
1093
1209
  * See spec.md §5.6.
1094
1210
  */
1095
1211
  let pipe_counter = 0;
1096
- function next_id$8() {
1212
+ function next_id$6() {
1097
1213
  pipe_counter += 1;
1098
1214
  return `pipe_${pipe_counter}`;
1099
1215
  }
1100
- function pipe(inner, fn) {
1101
- const id = next_id$8();
1216
+ function pipe(inner, fn, options) {
1217
+ const id = next_id$6();
1102
1218
  const run_fn = async (input, ctx) => {
1103
1219
  return fn(await dispatch_step(inner, input, ctx));
1104
1220
  };
1221
+ const config_meta = { fn };
1222
+ if (options?.name !== void 0) config_meta["display_name"] = options.name;
1105
1223
  return {
1106
1224
  id,
1107
1225
  kind: "pipe",
1108
1226
  children: [inner],
1109
- config: { fn },
1227
+ config: config_meta,
1110
1228
  run: run_fn
1111
1229
  };
1112
1230
  }
1113
1231
  register_kind("pipe", async (flow, input, ctx) => {
1114
- const span_id = ctx.trajectory.start_span("pipe", { id: flow.id });
1232
+ const label = resolve_span_label(flow, "pipe");
1233
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1115
1234
  try {
1116
1235
  const out = await flow.run(input, ctx);
1117
1236
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -1141,7 +1260,7 @@ register_kind("pipe", async (flow, input, ctx) => {
1141
1260
  */
1142
1261
  const DEFAULT_BACKOFF_MS = 1e3;
1143
1262
  let retry_counter = 0;
1144
- function next_id$7() {
1263
+ function next_id$5() {
1145
1264
  retry_counter += 1;
1146
1265
  return `retry_${retry_counter}`;
1147
1266
  }
@@ -1166,7 +1285,7 @@ async function abortable_wait(ms, ctx) {
1166
1285
  });
1167
1286
  }
1168
1287
  function retry(inner, config) {
1169
- const id = next_id$7();
1288
+ const id = next_id$5();
1170
1289
  const max_attempts = Math.max(1, Math.floor(config.max_attempts));
1171
1290
  const backoff_ms = config.backoff_ms ?? DEFAULT_BACKOFF_MS;
1172
1291
  const on_error = config.on_error;
@@ -1193,6 +1312,7 @@ function retry(inner, config) {
1193
1312
  backoff_ms
1194
1313
  };
1195
1314
  if (on_error) config_meta["on_error"] = on_error;
1315
+ if (config.name !== void 0) config_meta["display_name"] = config.name;
1196
1316
  return {
1197
1317
  id,
1198
1318
  kind: "retry",
@@ -1202,7 +1322,8 @@ function retry(inner, config) {
1202
1322
  };
1203
1323
  }
1204
1324
  register_kind("retry", async (flow, input, ctx) => {
1205
- const span_id = ctx.trajectory.start_span("retry", { id: flow.id });
1325
+ const label = resolve_span_label(flow, "retry");
1326
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1206
1327
  try {
1207
1328
  const out = await flow.run(input, ctx);
1208
1329
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -1225,12 +1346,12 @@ register_kind("retry", async (flow, input, ctx) => {
1225
1346
  * propagates. See spec.md §5.8.
1226
1347
  */
1227
1348
  let fallback_counter = 0;
1228
- function next_id$6() {
1349
+ function next_id$4() {
1229
1350
  fallback_counter += 1;
1230
1351
  return `fallback_${fallback_counter}`;
1231
1352
  }
1232
- function fallback(primary, backup) {
1233
- const id = next_id$6();
1353
+ function fallback(primary, backup, options) {
1354
+ const id = next_id$4();
1234
1355
  const run_fn = async (input, ctx) => {
1235
1356
  try {
1236
1357
  return await dispatch_step(primary, input, ctx);
@@ -1238,15 +1359,18 @@ function fallback(primary, backup) {
1238
1359
  return dispatch_step(backup, input, ctx);
1239
1360
  }
1240
1361
  };
1362
+ const config_meta = options?.name === void 0 ? void 0 : { display_name: options.name };
1241
1363
  return {
1242
1364
  id,
1243
1365
  kind: "fallback",
1244
1366
  children: [primary, backup],
1367
+ ...config_meta ? { config: config_meta } : {},
1245
1368
  run: run_fn
1246
1369
  };
1247
1370
  }
1248
1371
  register_kind("fallback", async (flow, input, ctx) => {
1249
- const span_id = ctx.trajectory.start_span("fallback", { id: flow.id });
1372
+ const label = resolve_span_label(flow, "fallback");
1373
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1250
1374
  try {
1251
1375
  const out = await flow.run(input, ctx);
1252
1376
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -1277,12 +1401,12 @@ register_kind("fallback", async (flow, input, ctx) => {
1277
1401
  * block so it does not leak across retries.
1278
1402
  */
1279
1403
  let timeout_counter = 0;
1280
- function next_id$5() {
1404
+ function next_id$3() {
1281
1405
  timeout_counter += 1;
1282
1406
  return `timeout_${timeout_counter}`;
1283
1407
  }
1284
- function timeout(inner, ms) {
1285
- const id = next_id$5();
1408
+ function timeout(inner, ms, options) {
1409
+ const id = next_id$3();
1286
1410
  const run_fn = async (input, ctx) => {
1287
1411
  const local = new AbortController();
1288
1412
  const composed = AbortSignal.any([ctx.abort, local.signal]);
@@ -1315,16 +1439,19 @@ function timeout(inner, ms) {
1315
1439
  clearTimeout(timer);
1316
1440
  }
1317
1441
  };
1442
+ const config_meta = { ms };
1443
+ if (options?.name !== void 0) config_meta["display_name"] = options.name;
1318
1444
  return {
1319
1445
  id,
1320
1446
  kind: "timeout",
1321
1447
  children: [inner],
1322
- config: { ms },
1448
+ config: config_meta,
1323
1449
  run: run_fn
1324
1450
  };
1325
1451
  }
1326
1452
  register_kind("timeout", async (flow, input, ctx) => {
1327
- const span_id = ctx.trajectory.start_span("timeout", { id: flow.id });
1453
+ const label = resolve_span_label(flow, "timeout");
1454
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1328
1455
  try {
1329
1456
  const out = await flow.run(input, ctx);
1330
1457
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -1338,68 +1465,77 @@ register_kind("timeout", async (flow, input, ctx) => {
1338
1465
  }
1339
1466
  });
1340
1467
  //#endregion
1341
- //#region packages/core/src/adversarial.ts
1468
+ //#region packages/core/src/loop.ts
1342
1469
  /**
1343
- * adversarial: build-and-critique loop.
1470
+ * loop: bounded iteration with carry-state.
1344
1471
  *
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).
1472
+ * `loop({ init, body, guard?, finish, max_rounds, name? })` runs `body` up to
1473
+ * `max_rounds` times, threading `state` through each iteration. After every
1474
+ * `body` call, an optional `guard` step inspects (and may transform) the state
1475
+ * and decides whether to stop. When `guard.stop` is true, the loop exits
1476
+ * "converged"; otherwise it continues until `max_rounds`. `finish` projects
1477
+ * the final state to the loop's output value.
1478
+ *
1479
+ * Non-convergence is data, not error: when `max_rounds` is exhausted without
1480
+ * `guard` returning stop, the loop returns `{ value, converged: false, rounds }`.
1481
+ * This matches the existing convention from adversarial/consensus.
1350
1482
  *
1351
- * See spec.md §5.10.
1483
+ * Cancellation: between rounds the parent `ctx.abort` is honored — a pending
1484
+ * abort short-circuits and propagates `ctx.abort.reason`. The body and guard
1485
+ * receive the parent context unchanged; their own dispatch routes already
1486
+ * thread cancellation per the runner contract.
1352
1487
  */
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));
1488
+ let loop_counter = 0;
1489
+ function next_id$2(name) {
1490
+ loop_counter += 1;
1491
+ return `${name ?? "loop"}_${loop_counter}`;
1492
+ }
1493
+ function throw_if_aborted$2(ctx) {
1494
+ if (!ctx.abort.aborted) return;
1495
+ const reason = ctx.abort.reason;
1496
+ throw reason instanceof Error ? reason : new aborted_error("aborted", { reason });
1497
+ }
1498
+ function loop(config) {
1499
+ const { init, body, guard, finish, name } = config;
1500
+ const rounds_limit = Math.max(1, Math.floor(config.max_rounds));
1501
+ const id = next_id$2(name);
1362
1502
  const run_fn = async (input, ctx) => {
1363
- let candidate = void 0;
1364
- let critique_notes = void 0;
1503
+ let state = init(input);
1365
1504
  let round = 0;
1505
+ let converged = false;
1366
1506
  while (round < rounds_limit) {
1507
+ throw_if_aborted$2(ctx);
1367
1508
  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;
1509
+ state = await dispatch_step(body, state, ctx);
1510
+ if (guard) {
1511
+ throw_if_aborted$2(ctx);
1512
+ const guard_out = await dispatch_step(guard, state, ctx);
1513
+ state = guard_out.state;
1514
+ if (guard_out.stop) {
1515
+ converged = true;
1516
+ break;
1517
+ }
1518
+ }
1383
1519
  }
1384
1520
  return {
1385
- candidate,
1386
- converged: false,
1521
+ value: finish(state, round),
1522
+ converged,
1387
1523
  rounds: round
1388
1524
  };
1389
1525
  };
1526
+ const config_meta = { max_rounds: rounds_limit };
1527
+ if (name !== void 0) config_meta["display_name"] = name;
1390
1528
  return {
1391
1529
  id,
1392
- kind: "adversarial",
1393
- children: [build, critique],
1394
- config: {
1395
- max_rounds: rounds_limit,
1396
- accept
1397
- },
1530
+ kind: "loop",
1531
+ children: guard ? [body, guard] : [body],
1532
+ config: config_meta,
1398
1533
  run: run_fn
1399
1534
  };
1400
1535
  }
1401
- register_kind("adversarial", async (flow, input, ctx) => {
1402
- const span_id = ctx.trajectory.start_span("adversarial", { id: flow.id });
1536
+ register_kind("loop", async (flow, input, ctx) => {
1537
+ const label = resolve_span_label(flow, "loop");
1538
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1403
1539
  try {
1404
1540
  const out = await flow.run(input, ctx);
1405
1541
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -1413,114 +1549,42 @@ register_kind("adversarial", async (flow, input, ctx) => {
1413
1549
  }
1414
1550
  });
1415
1551
  //#endregion
1416
- //#region packages/core/src/ensemble.ts
1552
+ //#region packages/core/src/compose.ts
1417
1553
  /**
1418
- * ensemble: N-of-M pick best.
1554
+ * compose: name a composite step.
1419
1555
  *
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".
1556
+ * `compose(name, inner)` wraps any step and labels its trajectory span with
1557
+ * `name`. The inner step's own span (e.g. a `sequence`) appears as a child of
1558
+ * the compose span — the implementation tree is preserved while the user's
1559
+ * intent ("this whole thing is an ensemble") is surfaced in observability.
1424
1560
  *
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`.
1561
+ * Used by the @repo/composites package to make built-in patterns appear under
1562
+ * their familiar names, and available to library consumers who want their own
1563
+ * named composites to show up in logs as first-class components.
1429
1564
  *
1430
- * See spec.md §5.11.
1565
+ * The primitive's `kind` is always `'compose'`; the user-supplied label lives
1566
+ * in `config.display_name` and is the span name the dispatcher opens.
1431
1567
  */
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;
1498
- }
1499
- }
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
- }
1510
- };
1568
+ let compose_counter = 0;
1569
+ function next_id$1(name) {
1570
+ compose_counter += 1;
1571
+ return `${name}_${compose_counter}`;
1572
+ }
1573
+ function compose(name, inner) {
1574
+ if (typeof name !== "string" || name.length === 0) throw new TypeError("compose(name, inner): name must be a non-empty string");
1575
+ const id = next_id$1(name);
1576
+ const run_fn = (input, ctx) => dispatch_step(inner, input, ctx);
1511
1577
  return {
1512
1578
  id,
1513
- kind: "ensemble",
1514
- children: child_list,
1515
- config: {
1516
- keys,
1517
- select
1518
- },
1579
+ kind: "compose",
1580
+ children: [inner],
1581
+ config: { display_name: name },
1519
1582
  run: run_fn
1520
1583
  };
1521
1584
  }
1522
- register_kind("ensemble", async (flow, input, ctx) => {
1523
- const span_id = ctx.trajectory.start_span("ensemble", { id: flow.id });
1585
+ register_kind("compose", async (flow, input, ctx) => {
1586
+ const label = resolve_span_label(flow, "compose");
1587
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1524
1588
  try {
1525
1589
  const out = await flow.run(input, ctx);
1526
1590
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -1534,120 +1598,61 @@ register_kind("ensemble", async (flow, input, ctx) => {
1534
1598
  }
1535
1599
  });
1536
1600
  //#endregion
1537
- //#region packages/core/src/tournament.ts
1601
+ //#region packages/core/src/checkpoint.ts
1538
1602
  /**
1539
- * tournament: pairwise bracket.
1603
+ * checkpoint: persist and resume.
1540
1604
  *
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 }`.
1605
+ * `checkpoint(inner, { key })` checks a persistent store for a completed
1606
+ * result at `key` before running `inner`. On a hit, returns the stored
1607
+ * value. On a miss, runs `inner`, persists its result at `key`, and returns
1608
+ * it. Corrupted reads (store throws on `get`) are treated as a miss.
1545
1609
  *
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`.
1610
+ * Fail-fast (constraints.md §7 invariant 8, spec.md §9 F6): wrapping an
1611
+ * anonymous inner step throws synchronously at construction time with the
1612
+ * message `checkpoint requires a named step; got anonymous`.
1549
1613
  *
1550
- * See spec.md §5.12.
1614
+ * See spec.md §5.14, §6.3.
1551
1615
  */
1552
- let tournament_counter = 0;
1553
- function next_id$2() {
1554
- tournament_counter += 1;
1555
- return `tournament_${tournament_counter}`;
1616
+ let checkpoint_counter = 0;
1617
+ function next_id() {
1618
+ checkpoint_counter += 1;
1619
+ return `checkpoint_${checkpoint_counter}`;
1556
1620
  }
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;
1621
+ function checkpoint(inner, config) {
1622
+ if (inner.anonymous === true) throw new Error("checkpoint requires a named step; got anonymous");
1623
+ const id = next_id();
1624
+ const key_spec = config.key;
1563
1625
  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);
1568
- };
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;
1626
+ const key = typeof key_spec === "function" ? key_spec(input) : key_spec;
1627
+ const store = ctx.checkpoint_store;
1628
+ if (store) {
1629
+ let cached = void 0;
1630
+ let hit = false;
1631
+ try {
1632
+ cached = await store.get(key);
1633
+ hit = cached !== null && cached !== void 0;
1634
+ } catch {
1635
+ hit = false;
1628
1636
  }
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);
1637
+ if (hit) return cached;
1639
1638
  }
1639
+ const result = await dispatch_step(inner, input, ctx);
1640
+ if (store) await store.set(key, result);
1641
+ return result;
1640
1642
  };
1643
+ const config_meta = { key: key_spec };
1644
+ if (config.name !== void 0) config_meta["display_name"] = config.name;
1641
1645
  return {
1642
1646
  id,
1643
- kind: "tournament",
1644
- children: child_list,
1645
- config: { keys },
1647
+ kind: "checkpoint",
1648
+ children: [inner],
1649
+ config: config_meta,
1646
1650
  run: run_fn
1647
1651
  };
1648
1652
  }
1649
- register_kind("tournament", async (flow, input, ctx) => {
1650
- const span_id = ctx.trajectory.start_span("tournament", { id: flow.id });
1653
+ register_kind("checkpoint", async (flow, input, ctx) => {
1654
+ const label = resolve_span_label(flow, "checkpoint");
1655
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1651
1656
  try {
1652
1657
  const out = await flow.run(input, ctx);
1653
1658
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -1661,204 +1666,26 @@ register_kind("tournament", async (flow, input, ctx) => {
1661
1666
  }
1662
1667
  });
1663
1668
  //#endregion
1664
- //#region packages/core/src/consensus.ts
1669
+ //#region packages/core/src/suspend.ts
1665
1670
  /**
1666
- * consensus: run until agreement.
1667
- *
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.
1671
+ * suspend: human-in-the-loop pause.
1672
1672
  *
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`.
1673
+ * `suspend({ id, on, resume_schema, combine })` pauses a flow waiting on
1674
+ * external input (a notification, an approval, an uploaded file). On first
1675
+ * encounter with no resume data, it calls `on(input, ctx)` (side effect) and
1676
+ * throws `suspended_error` carrying the run state. On resume (re-invocation
1677
+ * with `run_options.resume_data[id]` populated), the provided value is
1678
+ * validated against `resume_schema` and passed to `combine(input, resume,
1679
+ * ctx)`; the result is returned. Invalid resume data throws
1680
+ * `resume_validation_error` built from zod 4's `.flatten()` (spec.md §9 F5).
1676
1681
  *
1677
- * See spec.md §5.13.
1682
+ * See spec.md §5.15, §6.4.
1678
1683
  */
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
- };
1750
- return {
1751
- id,
1752
- kind: "consensus",
1753
- children: child_list,
1754
- config: {
1755
- keys,
1756
- max_rounds: rounds_limit,
1757
- agree: agree_fn
1758
- },
1759
- run: run_fn
1760
- };
1761
- }
1762
- register_kind("consensus", async (flow, input, ctx) => {
1763
- const span_id = ctx.trajectory.start_span("consensus", { id: flow.id });
1764
- try {
1765
- const out = await flow.run(input, ctx);
1766
- ctx.trajectory.end_span(span_id, { id: flow.id });
1767
- return out;
1768
- } catch (err) {
1769
- ctx.trajectory.end_span(span_id, {
1770
- id: flow.id,
1771
- error: err instanceof Error ? err.message : String(err)
1772
- });
1773
- throw err;
1774
- }
1775
- });
1776
- //#endregion
1777
- //#region packages/core/src/checkpoint.ts
1778
- /**
1779
- * checkpoint: persist and resume.
1780
- *
1781
- * `checkpoint(inner, { key })` checks a persistent store for a completed
1782
- * result at `key` before running `inner`. On a hit, returns the stored
1783
- * value. On a miss, runs `inner`, persists its result at `key`, and returns
1784
- * it. Corrupted reads (store throws on `get`) are treated as a miss.
1785
- *
1786
- * Fail-fast (constraints.md §7 invariant 8, spec.md §9 F6): wrapping an
1787
- * anonymous inner step throws synchronously at construction time with the
1788
- * message `checkpoint requires a named step; got anonymous`.
1789
- *
1790
- * See spec.md §5.14, §6.3.
1791
- */
1792
- let checkpoint_counter = 0;
1793
- function next_id() {
1794
- checkpoint_counter += 1;
1795
- return `checkpoint_${checkpoint_counter}`;
1796
- }
1797
- function checkpoint(inner, config) {
1798
- if (inner.anonymous === true) throw new Error("checkpoint requires a named step; got anonymous");
1799
- const id = next_id();
1800
- const key_spec = config.key;
1801
- const run_fn = async (input, ctx) => {
1802
- const key = typeof key_spec === "function" ? key_spec(input) : key_spec;
1803
- const store = ctx.checkpoint_store;
1804
- if (store) {
1805
- let cached = void 0;
1806
- let hit = false;
1807
- try {
1808
- cached = await store.get(key);
1809
- hit = cached !== null && cached !== void 0;
1810
- } catch {
1811
- hit = false;
1812
- }
1813
- if (hit) return cached;
1814
- }
1815
- const result = await dispatch_step(inner, input, ctx);
1816
- if (store) await store.set(key, result);
1817
- return result;
1818
- };
1819
- return {
1820
- id,
1821
- kind: "checkpoint",
1822
- children: [inner],
1823
- config: { key: key_spec },
1824
- run: run_fn
1825
- };
1826
- }
1827
- register_kind("checkpoint", async (flow, input, ctx) => {
1828
- const span_id = ctx.trajectory.start_span("checkpoint", { id: flow.id });
1829
- try {
1830
- const out = await flow.run(input, ctx);
1831
- ctx.trajectory.end_span(span_id, { id: flow.id });
1832
- return out;
1833
- } catch (err) {
1834
- ctx.trajectory.end_span(span_id, {
1835
- id: flow.id,
1836
- error: err instanceof Error ? err.message : String(err)
1837
- });
1838
- throw err;
1839
- }
1840
- });
1841
- //#endregion
1842
- //#region packages/core/src/suspend.ts
1843
- /**
1844
- * suspend: human-in-the-loop pause.
1845
- *
1846
- * `suspend({ id, on, resume_schema, combine })` pauses a flow waiting on
1847
- * external input (a notification, an approval, an uploaded file). On first
1848
- * encounter with no resume data, it calls `on(input, ctx)` (side effect) and
1849
- * throws `suspended_error` carrying the run state. On resume (re-invocation
1850
- * with `run_options.resume_data[id]` populated), the provided value is
1851
- * validated against `resume_schema` and passed to `combine(input, resume,
1852
- * ctx)`; the result is returned. Invalid resume data throws
1853
- * `resume_validation_error` built from zod 4's `.flatten()` (spec.md §9 F5).
1854
- *
1855
- * See spec.md §5.15, §6.4.
1856
- */
1857
- function is_step(value) {
1858
- if (typeof value !== "object" || value === null) return false;
1859
- if (!("id" in value) || !("kind" in value) || !("run" in value)) return false;
1860
- const { id, kind, run } = value;
1861
- return typeof id === "string" && typeof kind === "string" && typeof run === "function";
1684
+ function is_step(value) {
1685
+ if (typeof value !== "object" || value === null) return false;
1686
+ if (!("id" in value) || !("kind" in value) || !("run" in value)) return false;
1687
+ const { id, kind, run } = value;
1688
+ return typeof id === "string" && typeof kind === "string" && typeof run === "function";
1862
1689
  }
1863
1690
  function suspend(config) {
1864
1691
  const suspend_id = config.id;
@@ -1880,15 +1707,18 @@ function suspend(config) {
1880
1707
  if (is_step(result)) return dispatch_step(result, input, ctx);
1881
1708
  return result;
1882
1709
  };
1710
+ const config_meta = { id: suspend_id };
1711
+ if (config.name !== void 0) config_meta["display_name"] = config.name;
1883
1712
  return {
1884
1713
  id: suspend_id,
1885
1714
  kind: "suspend",
1886
- config: { id: suspend_id },
1715
+ config: config_meta,
1887
1716
  run: run_fn
1888
1717
  };
1889
1718
  }
1890
1719
  register_kind("suspend", async (flow, input, ctx) => {
1891
- const span_id = ctx.trajectory.start_span("suspend", { id: flow.id });
1720
+ const label = resolve_span_label(flow, "suspend");
1721
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1892
1722
  try {
1893
1723
  const out = await flow.run(input, ctx);
1894
1724
  ctx.trajectory.end_span(span_id, { id: flow.id });
@@ -1937,7 +1767,7 @@ function next_use_id() {
1937
1767
  use_counter += 1;
1938
1768
  return `use_${use_counter}`;
1939
1769
  }
1940
- function scope(children) {
1770
+ function scope(children, options) {
1941
1771
  const id = next_scope_id();
1942
1772
  const children_ref = children;
1943
1773
  const run_fn = async (input, ctx) => {
@@ -1951,14 +1781,16 @@ function scope(children) {
1951
1781
  for (const child of children_ref) acc = await dispatch_step(child, acc, scope_ctx);
1952
1782
  return acc;
1953
1783
  };
1784
+ const config_meta = options?.name === void 0 ? void 0 : { display_name: options.name };
1954
1785
  return {
1955
1786
  id,
1956
1787
  kind: "scope",
1957
1788
  children,
1789
+ ...config_meta ? { config: config_meta } : {},
1958
1790
  run: run_fn
1959
1791
  };
1960
1792
  }
1961
- function stash(key, source) {
1793
+ function stash(key, source, options) {
1962
1794
  const id = next_stash_id();
1963
1795
  const run_fn = async (input, ctx) => {
1964
1796
  if (!is_scope_state(ctx.state)) throw new Error("stash() may only appear inside scope(); got: top-level");
@@ -1966,15 +1798,17 @@ function stash(key, source) {
1966
1798
  ctx.state.set(key, value);
1967
1799
  return value;
1968
1800
  };
1801
+ const config_meta = { key };
1802
+ if (options?.name !== void 0) config_meta["display_name"] = options.name;
1969
1803
  return {
1970
1804
  id,
1971
1805
  kind: "stash",
1972
1806
  children: [source],
1973
- config: { key },
1807
+ config: config_meta,
1974
1808
  run: run_fn
1975
1809
  };
1976
1810
  }
1977
- function use(keys, fn) {
1811
+ function use(keys, fn, options) {
1978
1812
  const id = next_use_id();
1979
1813
  const run_fn = async (input, ctx) => {
1980
1814
  if (!is_scope_state(ctx.state)) throw new Error("use() may only appear inside scope(); got: top-level");
@@ -1982,71 +1816,1395 @@ function use(keys, fn) {
1982
1816
  for (const k of keys) projection[k] = ctx.state.get(k);
1983
1817
  return fn(projection, input, ctx);
1984
1818
  };
1819
+ const config_meta = { keys: [...keys] };
1820
+ if (options?.name !== void 0) config_meta["display_name"] = options.name;
1985
1821
  return {
1986
1822
  id,
1987
1823
  kind: "use",
1988
- config: { keys: [...keys] },
1824
+ config: config_meta,
1989
1825
  run: run_fn
1990
1826
  };
1991
1827
  }
1992
- register_kind("scope", async (flow, input, ctx) => {
1993
- const span_id = ctx.trajectory.start_span("scope", { id: flow.id });
1994
- try {
1995
- const out = await flow.run(input, ctx);
1996
- ctx.trajectory.end_span(span_id, { id: flow.id });
1997
- return out;
1998
- } catch (err) {
1999
- ctx.trajectory.end_span(span_id, {
2000
- id: flow.id,
2001
- error: err instanceof Error ? err.message : String(err)
2002
- });
2003
- throw err;
1828
+ register_kind("scope", async (flow, input, ctx) => {
1829
+ const label = resolve_span_label(flow, "scope");
1830
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1831
+ try {
1832
+ const out = await flow.run(input, ctx);
1833
+ ctx.trajectory.end_span(span_id, { id: flow.id });
1834
+ return out;
1835
+ } catch (err) {
1836
+ ctx.trajectory.end_span(span_id, {
1837
+ id: flow.id,
1838
+ error: err instanceof Error ? err.message : String(err)
1839
+ });
1840
+ throw err;
1841
+ }
1842
+ });
1843
+ register_kind("stash", async (flow, input, ctx) => {
1844
+ const label = resolve_span_label(flow, "stash");
1845
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1846
+ try {
1847
+ const out = await flow.run(input, ctx);
1848
+ ctx.trajectory.end_span(span_id, { id: flow.id });
1849
+ return out;
1850
+ } catch (err) {
1851
+ ctx.trajectory.end_span(span_id, {
1852
+ id: flow.id,
1853
+ error: err instanceof Error ? err.message : String(err)
1854
+ });
1855
+ throw err;
1856
+ }
1857
+ });
1858
+ register_kind("use", async (flow, input, ctx) => {
1859
+ const label = resolve_span_label(flow, "use");
1860
+ const span_id = ctx.trajectory.start_span(label, { id: flow.id });
1861
+ try {
1862
+ const out = await flow.run(input, ctx);
1863
+ ctx.trajectory.end_span(span_id, { id: flow.id });
1864
+ return out;
1865
+ } catch (err) {
1866
+ ctx.trajectory.end_span(span_id, {
1867
+ id: flow.id,
1868
+ error: err instanceof Error ? err.message : String(err)
1869
+ });
1870
+ throw err;
1871
+ }
1872
+ });
1873
+ //#endregion
1874
+ //#region packages/core/src/step_kinds.ts
1875
+ /**
1876
+ * Closed registry of every `Step.kind` produced by the composition layer.
1877
+ *
1878
+ * Studio (and any other consumer that needs to enumerate primitives — palette,
1879
+ * docs, code generation) can rely on this being the exhaustive set. New
1880
+ * primitives must add their kind here. The `step_kinds_cover_runner` contract
1881
+ * test in `step_kinds.test.ts` asserts every dispatch handler corresponds to a
1882
+ * kind listed here.
1883
+ */
1884
+ const STEP_KINDS = [
1885
+ "step",
1886
+ "sequence",
1887
+ "parallel",
1888
+ "branch",
1889
+ "map",
1890
+ "pipe",
1891
+ "retry",
1892
+ "fallback",
1893
+ "timeout",
1894
+ "loop",
1895
+ "compose",
1896
+ "adversarial",
1897
+ "ensemble",
1898
+ "tournament",
1899
+ "consensus",
1900
+ "checkpoint",
1901
+ "suspend",
1902
+ "scope",
1903
+ "stash",
1904
+ "use"
1905
+ ];
1906
+ function is_step_kind(value) {
1907
+ return typeof value === "string" && STEP_KINDS.includes(value);
1908
+ }
1909
+ //#endregion
1910
+ //#region packages/core/src/trajectory.ts
1911
+ /**
1912
+ * Wire-format schema for trajectory events.
1913
+ *
1914
+ * `TrajectoryEvent` (in `types.ts`) is the loose internal type — any code that
1915
+ * calls `trajectory.record(event)` or `start_span(name, meta)` produces values
1916
+ * conforming to it. This file defines the *narrower* shapes that the studio
1917
+ * (and any other downstream consumer) can parse out of the wire stream:
1918
+ *
1919
+ * span_start — composer span open
1920
+ * span_end — composer span close
1921
+ * emit — user-emitted event from inside a step (ctx.emit)
1922
+ * <other> — falls through `custom_event_schema`, which only requires a
1923
+ * string `kind` and tolerates any extra fields
1924
+ *
1925
+ * The discriminated union is **ordered**: well-known shapes are tried before
1926
+ * the permissive `custom` schema, so a `{ kind: 'span_start', ... }` event
1927
+ * always parses as `SpanStartEvent`, never as `CustomTrajectoryEvent`.
1928
+ *
1929
+ * Every well-known schema and `custom_event_schema` use `.passthrough()` so
1930
+ * additional fields (e.g. `run_id`, `id`, provider-specific metadata) survive
1931
+ * a parse / re-serialize round-trip without loss.
1932
+ */
1933
+ const span_start_event_schema = z.object({
1934
+ kind: z.literal("span_start"),
1935
+ span_id: z.string(),
1936
+ name: z.string()
1937
+ }).passthrough();
1938
+ const span_end_event_schema = z.object({
1939
+ kind: z.literal("span_end"),
1940
+ span_id: z.string()
1941
+ }).passthrough();
1942
+ const emit_event_schema = z.object({ kind: z.literal("emit") }).passthrough();
1943
+ const custom_event_schema = z.object({ kind: z.string() }).passthrough();
1944
+ const trajectory_event_schema = z.union([
1945
+ span_start_event_schema,
1946
+ span_end_event_schema,
1947
+ emit_event_schema,
1948
+ custom_event_schema
1949
+ ]);
1950
+ //#endregion
1951
+ //#region packages/core/src/version.ts
1952
+ const version = "0.3.8";
1953
+ //#endregion
1954
+ //#region packages/core/src/index.ts
1955
+ /**
1956
+ * Public surface for @repo/core.
1957
+ *
1958
+ * Side-effect imports ensure every composer registers itself with the runner
1959
+ * at module load. Importing anything from `@repo/core` populates the
1960
+ * dispatch table with the core primitives. Built-in composites
1961
+ * (adversarial, ensemble, tournament, consensus) live in @repo/composites
1962
+ * and surface through the umbrella package.
1963
+ */
1964
+ const flow_schema = flow_schema_default;
1965
+ //#endregion
1966
+ //#region packages/composites/src/adversarial.ts
1967
+ /**
1968
+ * adversarial: build-and-critique loop.
1969
+ *
1970
+ * `adversarial({ build, critique, accept, max_rounds })` runs up to
1971
+ * `max_rounds` iterations of: build a candidate (receiving the prior
1972
+ * candidate and critique notes when available) -> critique the candidate
1973
+ * -> check `accept(critique_result)`. Returns `{ candidate, converged,
1974
+ * rounds }`. Does not throw on non-convergence.
1975
+ *
1976
+ * Implemented as a `compose`d `loop` whose body builds a new candidate
1977
+ * and whose guard runs the critique step and checks `accept`. State is
1978
+ * threaded through `scope`/`stash`/`use` so the build and critique steps
1979
+ * remain unmodified user-supplied `Step` values.
1980
+ *
1981
+ * This file is the canonical example of how a user-built composite is
1982
+ * structured — the entire implementation is a composition of @repo/core
1983
+ * primitives. Read it as documentation.
1984
+ */
1985
+ function build_input_from_state(s) {
1986
+ if (s.candidate === void 0) return { input: s.input };
1987
+ if (s.critique_notes === void 0) return {
1988
+ input: s.input,
1989
+ prior: s.candidate
1990
+ };
1991
+ return {
1992
+ input: s.input,
1993
+ prior: s.candidate,
1994
+ critique: s.critique_notes
1995
+ };
1996
+ }
1997
+ function adversarial(config) {
1998
+ const { build, critique, accept, max_rounds } = config;
1999
+ const inner = pipe(loop({
2000
+ init: (input) => ({ input }),
2001
+ body: scope([
2002
+ stash("state", step("snapshot", (s) => s)),
2003
+ step("to_build_input", (s) => build_input_from_state(s)),
2004
+ build,
2005
+ use(["state"], (vars, candidate) => {
2006
+ return {
2007
+ ...vars["state"],
2008
+ candidate
2009
+ };
2010
+ })
2011
+ ]),
2012
+ guard: scope([
2013
+ stash("state", step("snapshot", (s) => s)),
2014
+ step("extract_candidate", (s) => {
2015
+ if (s.candidate === void 0) throw new Error("adversarial: guard reached without a candidate");
2016
+ return s.candidate;
2017
+ }),
2018
+ critique,
2019
+ use(["state"], (vars, critique_result) => {
2020
+ const prior = vars["state"];
2021
+ return {
2022
+ stop: accept(critique_result),
2023
+ state: {
2024
+ ...prior,
2025
+ last_critique: critique_result,
2026
+ critique_notes: critique_result.notes
2027
+ }
2028
+ };
2029
+ })
2030
+ ]),
2031
+ finish: (s) => {
2032
+ if (s.candidate === void 0) throw new Error("adversarial: finished without a candidate");
2033
+ return s.candidate;
2034
+ },
2035
+ max_rounds
2036
+ }), (result) => ({
2037
+ candidate: result.value,
2038
+ converged: result.converged,
2039
+ rounds: result.rounds
2040
+ }));
2041
+ return compose(config.name ?? "adversarial", inner);
2042
+ }
2043
+ //#endregion
2044
+ //#region packages/composites/src/consensus.ts
2045
+ /**
2046
+ * consensus: run-until-agreement.
2047
+ *
2048
+ * `consensus({ members, agree, max_rounds })` runs every member concurrently
2049
+ * with the same input. If `agree(results)` is true, returns the results with
2050
+ * `converged: true`. Otherwise re-runs all members up to `max_rounds` times,
2051
+ * returning the last results with `converged: false` if no agreement is
2052
+ * reached.
2053
+ *
2054
+ * Implemented as a `compose`d `loop` whose body runs `parallel(members)` and
2055
+ * whose guard evaluates `agree`. State carries the original input alongside
2056
+ * the most recent results so each round receives the same input.
2057
+ */
2058
+ function consensus(config) {
2059
+ const { members, agree, max_rounds } = config;
2060
+ const round_step = parallel(members);
2061
+ const inner = pipe(loop({
2062
+ init: (input) => ({
2063
+ input,
2064
+ results: {}
2065
+ }),
2066
+ body: scope([
2067
+ stash("state", step("snapshot", (s) => s)),
2068
+ step("extract_input", (s) => s.input),
2069
+ round_step,
2070
+ use(["state"], (vars, results) => {
2071
+ return {
2072
+ ...vars["state"],
2073
+ results
2074
+ };
2075
+ })
2076
+ ]),
2077
+ guard: step("agree", (s) => ({
2078
+ stop: agree(s.results),
2079
+ state: s
2080
+ })),
2081
+ finish: (s) => s.results,
2082
+ max_rounds
2083
+ }), (result) => ({
2084
+ result: result.value,
2085
+ converged: result.converged
2086
+ }));
2087
+ return compose(config.name ?? "consensus", inner);
2088
+ }
2089
+ //#endregion
2090
+ //#region packages/composites/src/ensemble.ts
2091
+ /**
2092
+ * ensemble: N-of-M pick-best.
2093
+ *
2094
+ * `ensemble({ members, score, select? })` runs every member concurrently with
2095
+ * the same input, scores each result, and returns the winner (highest or
2096
+ * lowest by `select`) plus the complete score map. Tie-breaking is "any tied
2097
+ * result is acceptable".
2098
+ *
2099
+ * Implemented as a `compose`d `sequence` of `parallel(members)` followed by
2100
+ * a single picking step. Cancellation, fan-out, and abort propagation come
2101
+ * from `parallel`'s own contract.
2102
+ */
2103
+ function ensemble(config) {
2104
+ const select = config.select ?? "max";
2105
+ const score_fn = config.score;
2106
+ const keys = Object.keys(config.members);
2107
+ const inner = sequence([parallel(config.members), step("pick_winner", async (results) => {
2108
+ const scores = {};
2109
+ for (const k of keys) {
2110
+ const value = results[k];
2111
+ if (value === void 0) continue;
2112
+ scores[k] = await score_fn(value, k);
2113
+ }
2114
+ let winner_key = void 0;
2115
+ let winner_score = void 0;
2116
+ for (const k of keys) {
2117
+ const current = scores[k];
2118
+ if (current === void 0) continue;
2119
+ if (winner_score === void 0) {
2120
+ winner_key = k;
2121
+ winner_score = current;
2122
+ continue;
2123
+ }
2124
+ if (select === "max" ? current > winner_score : current < winner_score) {
2125
+ winner_key = k;
2126
+ winner_score = current;
2127
+ }
2128
+ }
2129
+ if (winner_key === void 0) throw new Error("ensemble: no members produced a result");
2130
+ const winner = results[winner_key];
2131
+ if (winner === void 0) throw new Error("ensemble: winner missing from results");
2132
+ return {
2133
+ winner,
2134
+ scores
2135
+ };
2136
+ })]);
2137
+ return compose(config.name ?? "ensemble", inner);
2138
+ }
2139
+ //#endregion
2140
+ //#region packages/composites/src/ensemble_step.ts
2141
+ /**
2142
+ * ensemble_step: N-of-M pick-best with a Step-based scorer.
2143
+ *
2144
+ * `ensemble_step({ members, score, rank_by, select? })` is the sibling of
2145
+ * `ensemble` for the case where scoring is itself a `Step` (e.g. a separate
2146
+ * model call, a sub-flow, anything that wants its own trajectory span and
2147
+ * abort routing). Each member runs concurrently with the same input; the
2148
+ * `score` step is dispatched once per result; `rank_by` projects a number
2149
+ * out of the structured scored output; the highest- or lowest-ranking
2150
+ * winner is returned alongside its full structured score and the score
2151
+ * map for the rest.
2152
+ *
2153
+ * Returning `winner_scored` avoids the cost of re-scoring the winner — the
2154
+ * structured output from the round's scoring run is preserved verbatim.
2155
+ *
2156
+ * Implemented as a `compose`d `scope` over (`stash(parallel(members))` →
2157
+ * `to_pairs` → `map(score per result, threading id)` → `use` to pick
2158
+ * winner). Cancellation, fan-out, and abort propagation come from the
2159
+ * underlying `parallel` and `map` contracts.
2160
+ */
2161
+ const RESULTS_KEY = "__ensemble_step_results";
2162
+ const ITEM_KEY = "__ensemble_step_item";
2163
+ function ensemble_step(config) {
2164
+ const { members, score, rank_by } = config;
2165
+ const select = config.select ?? "max";
2166
+ const keys = Object.keys(members);
2167
+ if (keys.length === 0) throw new Error("ensemble_step: at least one member required");
2168
+ const fan_out = parallel(members);
2169
+ const score_one = scope([
2170
+ stash(ITEM_KEY, step("ensemble_step_item_snapshot", (item) => item)),
2171
+ step("ensemble_step_extract_value", (item) => item.value),
2172
+ score,
2173
+ use([ITEM_KEY], (vars, scored) => {
2174
+ return {
2175
+ id: vars[ITEM_KEY].id,
2176
+ scored
2177
+ };
2178
+ })
2179
+ ]);
2180
+ const to_pairs = step("ensemble_step_to_pairs", (results) => {
2181
+ const out = [];
2182
+ for (const id of keys) if (id in results) out.push({
2183
+ id,
2184
+ value: results[id]
2185
+ });
2186
+ return out;
2187
+ });
2188
+ const score_each = map({
2189
+ items: (pairs) => pairs,
2190
+ do: score_one
2191
+ });
2192
+ const pick = use([RESULTS_KEY], (vars, scored_pairs) => {
2193
+ const results = vars[RESULTS_KEY];
2194
+ const scored = {};
2195
+ let winner_id;
2196
+ let winner_rank;
2197
+ let winner_scored;
2198
+ for (const pair of scored_pairs) {
2199
+ scored[pair.id] = pair.scored;
2200
+ const rank = rank_by(pair.scored);
2201
+ if (winner_rank === void 0 ? true : select === "max" ? rank > winner_rank : rank < winner_rank) {
2202
+ winner_id = pair.id;
2203
+ winner_rank = rank;
2204
+ winner_scored = pair.scored;
2205
+ }
2206
+ }
2207
+ if (winner_id === void 0 || winner_scored === void 0) throw new Error("ensemble_step: no members produced a result");
2208
+ const winner = results[winner_id];
2209
+ if (winner === void 0) throw new Error("ensemble_step: winner missing from results");
2210
+ return {
2211
+ winner_id,
2212
+ winner,
2213
+ winner_scored,
2214
+ scored
2215
+ };
2216
+ });
2217
+ const inner = scope([
2218
+ stash(RESULTS_KEY, fan_out),
2219
+ to_pairs,
2220
+ score_each,
2221
+ pick
2222
+ ]);
2223
+ return compose(config.name ?? "ensemble_step", inner);
2224
+ }
2225
+ //#endregion
2226
+ //#region packages/composites/src/improve.ts
2227
+ /**
2228
+ * improve: bounded online self-improvement loop.
2229
+ *
2230
+ * `improve({ seed, propose, score, budget })` runs a round-bounded loop that
2231
+ * threads a `parent` candidate through repeated propose → score → accept/reject
2232
+ * cycles. The kernel decides acceptance via a hard gate (`scored.accepted`) and
2233
+ * an epsilon-improvement test (`scored.score > parent_score + epsilon`).
2234
+ * Plateau detection stops the loop early when no progress has been made for
2235
+ * `patience` rounds; an optional wall-clock budget caps total runtime.
2236
+ *
2237
+ * `improve` is the *online* counterpart to `learn`: where `learn` reflects on
2238
+ * recorded trajectories offline, `improve` runs the propose/score loop live
2239
+ * inside a single run. The amplify example is a domain-specific consumer of
2240
+ * this same pattern (filesystem mutation, test-suite gates, subprocess
2241
+ * research). `improve` strips those opinions out so any domain can plug in
2242
+ * its own `propose` and `score` steps.
2243
+ *
2244
+ * Implemented as a `compose`d `scope` of (seed) → (init state) → (loop) →
2245
+ * (unwrap). The loop body is itself a small `scope` that snapshots prior
2246
+ * state, builds a round input, dispatches the proposers + scorer via
2247
+ * `ensemble_step`, and merges the outcome back into state via `use`.
2248
+ * State threading is the entire job.
2249
+ */
2250
+ const PRIOR_KEY = "__improve_prior";
2251
+ function improve(config) {
2252
+ const { seed, propose, score, budget } = config;
2253
+ const epsilon = config.epsilon ?? 0;
2254
+ const proposers_per_round = Math.max(1, config.proposers_per_round ?? 1);
2255
+ const lessons_capacity = Math.max(0, config.lessons_capacity ?? 5);
2256
+ const { max_rounds, max_wallclock_ms, patience } = budget;
2257
+ const proposers = {};
2258
+ for (let i = 0; i < proposers_per_round; i += 1) proposers[`p${String(i)}`] = propose;
2259
+ const round_ensemble = ensemble_step({
2260
+ name: "improve_round",
2261
+ members: proposers,
2262
+ score,
2263
+ rank_by: (s) => s.score
2264
+ });
2265
+ const project_round = use([PRIOR_KEY], (vars, ensemble_result, ctx) => {
2266
+ const round = vars[PRIOR_KEY].round + 1;
2267
+ for (const slot_id of Object.keys(ensemble_result.scored)) {
2268
+ const scored = ensemble_result.scored[slot_id];
2269
+ if (scored === void 0) continue;
2270
+ ctx.trajectory.record({
2271
+ kind: "improve.candidate",
2272
+ round,
2273
+ proposer_id: slot_id,
2274
+ score: scored.score,
2275
+ accepted: scored.accepted,
2276
+ ...scored.reason === void 0 ? {} : { reason: scored.reason }
2277
+ });
2278
+ }
2279
+ const w = ensemble_result.winner_scored;
2280
+ return {
2281
+ ...w,
2282
+ candidate: {
2283
+ ...w.candidate,
2284
+ proposer_id: ensemble_result.winner_id
2285
+ }
2286
+ };
2287
+ });
2288
+ const init_state = step("improve_init_state", (seed_result) => ({
2289
+ parent: seed_result.content,
2290
+ parent_score: seed_result.score,
2291
+ round: 0,
2292
+ rounds_since_progress: 0,
2293
+ started_at_ms: Date.now(),
2294
+ history: [],
2295
+ lessons: []
2296
+ }));
2297
+ const to_round_input = step("improve_to_round_input", (s, ctx) => {
2298
+ const round = s.round + 1;
2299
+ ctx.trajectory.record({
2300
+ kind: "improve.round_start",
2301
+ round,
2302
+ parent_score: s.parent_score,
2303
+ lessons_count: s.lessons.length
2304
+ });
2305
+ return {
2306
+ parent: s.parent,
2307
+ parent_score: s.parent_score,
2308
+ round,
2309
+ lessons: s.lessons
2310
+ };
2311
+ });
2312
+ const merge_outcome = use([PRIOR_KEY], (vars, scored, ctx) => {
2313
+ const prior = vars[PRIOR_KEY];
2314
+ const next_round = prior.round + 1;
2315
+ const better = scored.score > prior.parent_score + epsilon;
2316
+ const accepted = scored.accepted && better;
2317
+ const next_lessons = !accepted && scored.reason !== void 0 ? [...prior.lessons, {
2318
+ round: next_round,
2319
+ proposer_id: scored.candidate.proposer_id,
2320
+ reason: scored.reason
2321
+ }].slice(-lessons_capacity) : prior.lessons;
2322
+ ctx.trajectory.record({
2323
+ kind: accepted ? "improve.accept" : "improve.reject",
2324
+ round: next_round,
2325
+ proposer_id: scored.candidate.proposer_id,
2326
+ score: scored.score,
2327
+ prior_score: prior.parent_score,
2328
+ ...accepted ? { delta: scored.score - prior.parent_score } : {},
2329
+ ...scored.reason === void 0 ? {} : { reason: scored.reason }
2330
+ });
2331
+ return {
2332
+ parent: accepted ? scored.candidate.content : prior.parent,
2333
+ parent_score: accepted ? scored.score : prior.parent_score,
2334
+ round: next_round,
2335
+ rounds_since_progress: accepted ? 0 : prior.rounds_since_progress + 1,
2336
+ started_at_ms: prior.started_at_ms,
2337
+ history: [...prior.history, {
2338
+ round: next_round,
2339
+ winner: scored,
2340
+ accepted
2341
+ }],
2342
+ lessons: next_lessons
2343
+ };
2344
+ });
2345
+ const inner = scope([
2346
+ seed,
2347
+ init_state,
2348
+ loop({
2349
+ init: (s) => s,
2350
+ body: scope([
2351
+ stash(PRIOR_KEY, step("improve_snapshot", (s) => s)),
2352
+ to_round_input,
2353
+ round_ensemble,
2354
+ project_round,
2355
+ merge_outcome
2356
+ ]),
2357
+ guard: step("improve_guard", (s) => {
2358
+ if (s.rounds_since_progress >= patience) return {
2359
+ stop: true,
2360
+ state: {
2361
+ ...s,
2362
+ stopped_by: "plateau"
2363
+ }
2364
+ };
2365
+ if (max_wallclock_ms !== void 0 && Date.now() - s.started_at_ms >= max_wallclock_ms) return {
2366
+ stop: true,
2367
+ state: {
2368
+ ...s,
2369
+ stopped_by: "budget"
2370
+ }
2371
+ };
2372
+ return {
2373
+ stop: false,
2374
+ state: s
2375
+ };
2376
+ }),
2377
+ finish: (s) => ({
2378
+ best: {
2379
+ content: s.parent,
2380
+ score: s.parent_score
2381
+ },
2382
+ rounds_used: s.round,
2383
+ stopped_by: s.stopped_by ?? "budget",
2384
+ history: s.history
2385
+ }),
2386
+ max_rounds
2387
+ }),
2388
+ step("improve_unwrap", (result, ctx) => {
2389
+ ctx.trajectory.record({
2390
+ kind: "improve.stop",
2391
+ stopped_by: result.value.stopped_by,
2392
+ rounds_used: result.value.rounds_used,
2393
+ final_score: result.value.best.score
2394
+ });
2395
+ return result.value;
2396
+ })
2397
+ ]);
2398
+ return compose(config.name ?? "improve", inner);
2399
+ }
2400
+ //#endregion
2401
+ //#region packages/composites/src/learn.ts
2402
+ /**
2403
+ * learn: offline self-improvement composer.
2404
+ *
2405
+ * `learn({ flow, source, analyzer })` reads recorded trajectory events from
2406
+ * past runs of `flow`, hands them to a user-supplied `analyzer` step alongside
2407
+ * `describe(flow)`, and returns the analyzer's proposals plus summary metadata
2408
+ * (events considered, distinct run ids).
2409
+ *
2410
+ * The amplify example is the *online* counterpart of this pattern: propose →
2411
+ * score → accept/reject inside a single run. `learn` is the *offline*
2412
+ * counterpart: reflect on what already happened across one or many recorded
2413
+ * runs without an evaluator in the loop.
2414
+ *
2415
+ * Implemented as a `compose`d `scope` of (compute meta) → (build LearnInput) →
2416
+ * (analyzer) → (wrap result with meta). No engine dependency; the analyzer
2417
+ * decides how to use the events.
2418
+ *
2419
+ * Three source kinds: `events` (in-memory), `paths` (explicit JSONL files),
2420
+ * `dir` (recursive *.jsonl walk). File reads honor `ctx.abort` at file-level
2421
+ * granularity; malformed lines are skipped and surface as `learn.parse_error`
2422
+ * trajectory events with 1-indexed line offsets. When `max_events` clips the
2423
+ * filtered set, a `learn.truncated` event records `available`, `kept`, and the
2424
+ * configured cap.
2425
+ */
2426
+ const DEFAULT_MAX_EVENTS = 1e4;
2427
+ const META_KEY = "__learn_meta";
2428
+ async function walk_jsonl(dir) {
2429
+ const out = [];
2430
+ const entries = await readdir(dir, { withFileTypes: true });
2431
+ for (const entry of entries) {
2432
+ const full = join(dir, entry.name);
2433
+ if (entry.isDirectory()) out.push(...await walk_jsonl(full));
2434
+ else if (entry.isFile() && entry.name.endsWith(".jsonl")) out.push(full);
2435
+ }
2436
+ return out;
2437
+ }
2438
+ async function read_jsonl(file_path, ctx) {
2439
+ const lines = (await readFile(file_path, "utf8")).split("\n");
2440
+ const events = [];
2441
+ for (let i = 0; i < lines.length; i += 1) {
2442
+ const raw = lines[i];
2443
+ if (raw === void 0 || raw.trim() === "") continue;
2444
+ let parsed;
2445
+ try {
2446
+ parsed = JSON.parse(raw);
2447
+ } catch {
2448
+ ctx.trajectory.record({
2449
+ kind: "learn.parse_error",
2450
+ path: file_path,
2451
+ line: i + 1
2452
+ });
2453
+ continue;
2454
+ }
2455
+ const result = trajectory_event_schema.safeParse(parsed);
2456
+ if (result.success) events.push(result.data);
2457
+ else ctx.trajectory.record({
2458
+ kind: "learn.parse_error",
2459
+ path: file_path,
2460
+ line: i + 1
2461
+ });
2462
+ }
2463
+ return events;
2464
+ }
2465
+ function throw_if_aborted$1(ctx) {
2466
+ if (!ctx.abort.aborted) return;
2467
+ const reason = ctx.abort.reason;
2468
+ if (reason instanceof aborted_error) throw reason;
2469
+ throw new aborted_error("aborted", reason === void 0 ? {} : { reason });
2470
+ }
2471
+ async function resolve_events(source, ctx) {
2472
+ if (source.kind === "events") return source.events;
2473
+ const file_paths = source.kind === "paths" ? [...source.paths] : (await walk_jsonl(source.dir)).toSorted();
2474
+ const all = [];
2475
+ for (const p of file_paths) {
2476
+ throw_if_aborted$1(ctx);
2477
+ const events = await read_jsonl(p, ctx);
2478
+ all.push(...events);
2479
+ }
2480
+ return all;
2481
+ }
2482
+ function collect_run_ids(events) {
2483
+ const seen = /* @__PURE__ */ new Set();
2484
+ const out = [];
2485
+ for (const event of events) {
2486
+ const id = event["run_id"];
2487
+ if (typeof id === "string" && !seen.has(id)) {
2488
+ seen.add(id);
2489
+ out.push(id);
2490
+ }
2491
+ }
2492
+ return out;
2493
+ }
2494
+ function learn(config) {
2495
+ const { flow, source, analyzer, filter } = config;
2496
+ const max = config.max_events ?? DEFAULT_MAX_EVENTS;
2497
+ const compute_meta = step("learn_compute_meta", async (prior, ctx) => {
2498
+ const all = await resolve_events(source, ctx);
2499
+ const filtered = filter ? all.filter(filter) : all;
2500
+ const truncated = filtered.length > max;
2501
+ const capped = truncated ? filtered.slice(0, max) : filtered;
2502
+ if (truncated) ctx.trajectory.record({
2503
+ kind: "learn.truncated",
2504
+ available: filtered.length,
2505
+ kept: capped.length,
2506
+ max_events: max
2507
+ });
2508
+ return {
2509
+ events_considered: capped.length,
2510
+ run_ids: collect_run_ids(capped),
2511
+ events: capped,
2512
+ prior
2513
+ };
2514
+ });
2515
+ const build_input = step("learn_build_input", (meta) => ({
2516
+ flow_description: describe(flow),
2517
+ events: meta.events,
2518
+ prior: meta.prior
2519
+ }));
2520
+ const wrap_result = use([META_KEY], (vars, proposals, ctx) => {
2521
+ const meta = vars[META_KEY];
2522
+ ctx.trajectory.record({
2523
+ kind: "learn.summary",
2524
+ events_considered: meta.events_considered,
2525
+ run_ids: meta.run_ids
2526
+ });
2527
+ return {
2528
+ proposals,
2529
+ events_considered: meta.events_considered,
2530
+ run_ids: meta.run_ids
2531
+ };
2532
+ });
2533
+ const inner = scope([
2534
+ stash(META_KEY, compute_meta),
2535
+ build_input,
2536
+ analyzer,
2537
+ wrap_result
2538
+ ]);
2539
+ return compose(config.name ?? "learn", inner);
2540
+ }
2541
+ //#endregion
2542
+ //#region packages/composites/src/tournament.ts
2543
+ /**
2544
+ * tournament: pairwise bracket.
2545
+ *
2546
+ * `tournament({ members, compare })` runs every member, then pairs them off
2547
+ * in a single-elimination bracket. `compare(a, b)` returns which result
2548
+ * advances. An odd member count yields one bye per affected round. Returns
2549
+ * `{ winner, bracket }` where `bracket` lists every match record.
2550
+ *
2551
+ * Implemented as a `compose`d `sequence` of `parallel(members)` followed
2552
+ * by a single bracket-reduction step. Cancellation, fan-out, and abort
2553
+ * propagation come from `parallel`'s contract; the bracket step only runs
2554
+ * after all members settle.
2555
+ */
2556
+ function tournament(config) {
2557
+ const compare_fn = config.compare;
2558
+ const keys = Object.keys(config.members);
2559
+ if (keys.length === 0) throw new Error("tournament: at least one member required");
2560
+ const inner = sequence([parallel(config.members), step("bracket", async (results) => {
2561
+ let current = [...keys];
2562
+ const bracket = [];
2563
+ let round = 0;
2564
+ while (current.length > 1) {
2565
+ round += 1;
2566
+ const next_round = [];
2567
+ for (let i = 0; i < current.length; i += 2) {
2568
+ const a_id = current[i];
2569
+ const b_id = current[i + 1];
2570
+ if (a_id === void 0) continue;
2571
+ if (b_id === void 0) {
2572
+ next_round.push(a_id);
2573
+ continue;
2574
+ }
2575
+ const a_val = results[a_id];
2576
+ const b_val = results[b_id];
2577
+ if (a_val === void 0 || b_val === void 0) throw new Error("tournament: missing result for match");
2578
+ const winner_id = await compare_fn(a_val, b_val) === "a" ? a_id : b_id;
2579
+ bracket.push({
2580
+ round,
2581
+ a_id,
2582
+ b_id,
2583
+ winner_id
2584
+ });
2585
+ next_round.push(winner_id);
2586
+ }
2587
+ current = next_round;
2588
+ }
2589
+ const final_id = current[0];
2590
+ if (final_id === void 0) throw new Error("tournament: no winner");
2591
+ const winner = results[final_id];
2592
+ if (winner === void 0) throw new Error("tournament: winner missing from results");
2593
+ return {
2594
+ winner,
2595
+ bracket
2596
+ };
2597
+ })]);
2598
+ return compose(config.name ?? "tournament", inner);
2599
+ }
2600
+ //#endregion
2601
+ //#region packages/observability/src/filesystem.ts
2602
+ /**
2603
+ * Filesystem JSONL trajectory logger.
2604
+ *
2605
+ * Appends one JSON object per line to a configured output file. `start_span`
2606
+ * and `end_span` each emit a line; `record` emits a line with the event as
2607
+ * written. Hierarchical span ids are tracked via an in-memory stack: when
2608
+ * `start_span` fires, the innermost still-open span's id is attached as
2609
+ * `parent_span_id` on the new span's record. This is best-effort for
2610
+ * concurrent children (two siblings spawned from the same parent will see
2611
+ * whichever opened most recently as their parent until proper async-context
2612
+ * propagation is wired). Two concurrent `run(...)` calls that pass distinct
2613
+ * logger instances (constructed with distinct `output_path`s) share nothing.
2614
+ *
2615
+ * Paths are accepted at construction; the logger never reads `process.env`.
2616
+ */
2617
+ function filesystem_logger(options) {
2618
+ const { output_path } = options;
2619
+ mkdirSync(dirname(output_path), { recursive: true });
2620
+ const stack = [];
2621
+ const write_line = (event) => {
2622
+ appendFileSync(output_path, `${JSON.stringify(event)}\n`);
2623
+ };
2624
+ const start_span = (name, meta) => {
2625
+ const span_id = `${name}:${randomUUID().slice(0, 8)}`;
2626
+ const parent_span_id = stack.length > 0 ? stack[stack.length - 1] : void 0;
2627
+ const event = {
2628
+ kind: "span_start",
2629
+ span_id,
2630
+ name,
2631
+ ...meta
2632
+ };
2633
+ if (parent_span_id !== void 0) event["parent_span_id"] = parent_span_id;
2634
+ write_line(event);
2635
+ stack.push(span_id);
2636
+ return span_id;
2637
+ };
2638
+ const end_span = (id, meta) => {
2639
+ write_line({
2640
+ kind: "span_end",
2641
+ span_id: id,
2642
+ ...meta
2643
+ });
2644
+ const idx = stack.lastIndexOf(id);
2645
+ if (idx !== -1) stack.splice(idx, 1);
2646
+ };
2647
+ const record = (event) => {
2648
+ write_line({ ...event });
2649
+ };
2650
+ return {
2651
+ record,
2652
+ start_span,
2653
+ end_span
2654
+ };
2655
+ }
2656
+ //#endregion
2657
+ //#region packages/observability/src/http.ts
2658
+ /**
2659
+ * HTTP push trajectory logger.
2660
+ *
2661
+ * Conforms to `TrajectoryLogger`. POSTs each event as a single line of
2662
+ * newline-delimited JSON to a configured URL. Pairs naturally with the
2663
+ * fascicle viewer's `/api/ingest` endpoint, but is a generic adapter — the
2664
+ * receiver can be anything that accepts NDJSON over HTTP.
2665
+ *
2666
+ * Failure policy: drop on transport error and invoke the optional `on_error`
2667
+ * callback. Never throws, never blocks the user's flow on a dev tool being
2668
+ * up. The flow always wins; the viewer is best-effort.
2669
+ *
2670
+ * Hierarchical span ids are tracked in-process, mirroring `filesystem_logger`
2671
+ * so the wire format is identical.
2672
+ */
2673
+ const default_fetch = async (url, init) => {
2674
+ const res = await fetch(url, init);
2675
+ return {
2676
+ ok: res.ok,
2677
+ status: res.status
2678
+ };
2679
+ };
2680
+ function http_logger(options) {
2681
+ const { url, on_error } = options;
2682
+ const send = options.fetch ?? default_fetch;
2683
+ const stack = [];
2684
+ const post = (event) => {
2685
+ send(url, {
2686
+ method: "POST",
2687
+ headers: { "content-type": "application/x-ndjson" },
2688
+ body: `${JSON.stringify(event)}\n`
2689
+ }).then((res) => {
2690
+ if (!res.ok && on_error) on_error(/* @__PURE__ */ new Error(`http_logger: POST ${url} -> ${res.status}`));
2691
+ }).catch((err) => {
2692
+ if (on_error) on_error(err);
2693
+ });
2694
+ };
2695
+ const start_span = (name, meta) => {
2696
+ const span_id = `${name}:${randomUUID().slice(0, 8)}`;
2697
+ const parent_span_id = stack.length > 0 ? stack[stack.length - 1] : void 0;
2698
+ const event = {
2699
+ kind: "span_start",
2700
+ span_id,
2701
+ name,
2702
+ ...meta
2703
+ };
2704
+ if (parent_span_id !== void 0) event["parent_span_id"] = parent_span_id;
2705
+ post(event);
2706
+ stack.push(span_id);
2707
+ return span_id;
2708
+ };
2709
+ const end_span = (id, meta) => {
2710
+ post({
2711
+ kind: "span_end",
2712
+ span_id: id,
2713
+ ...meta
2714
+ });
2715
+ const idx = stack.lastIndexOf(id);
2716
+ if (idx !== -1) stack.splice(idx, 1);
2717
+ };
2718
+ const record = (event) => {
2719
+ post({ ...event });
2720
+ };
2721
+ return {
2722
+ record,
2723
+ start_span,
2724
+ end_span
2725
+ };
2726
+ }
2727
+ //#endregion
2728
+ //#region packages/observability/src/tee.ts
2729
+ function tee_logger(...loggers) {
2730
+ if (loggers.length === 0) throw new Error("tee_logger: at least one logger required");
2731
+ const id_map = /* @__PURE__ */ new Map();
2732
+ const safe_each = (fn) => {
2733
+ for (let i = 0; i < loggers.length; i += 1) {
2734
+ const l = loggers[i];
2735
+ if (l === void 0) continue;
2736
+ try {
2737
+ fn(l, i);
2738
+ } catch {}
2739
+ }
2740
+ };
2741
+ return {
2742
+ record: (event) => {
2743
+ safe_each((l) => l.record(event));
2744
+ },
2745
+ start_span: (name, meta) => {
2746
+ const ids = [];
2747
+ safe_each((l) => {
2748
+ ids.push(l.start_span(name, meta));
2749
+ });
2750
+ const canonical = ids[0] ?? `${name}:tee`;
2751
+ if (loggers.length > 1) id_map.set(canonical, ids);
2752
+ return canonical;
2753
+ },
2754
+ end_span: (id, meta) => {
2755
+ const ids = id_map.get(id);
2756
+ if (ids === void 0) {
2757
+ safe_each((l) => l.end_span(id, meta));
2758
+ return;
2759
+ }
2760
+ id_map.delete(id);
2761
+ safe_each((l, idx) => l.end_span(ids[idx] ?? id, meta));
2762
+ }
2763
+ };
2764
+ }
2765
+ //#endregion
2766
+ //#region packages/composites/src/bench.ts
2767
+ /**
2768
+ * bench: run a flow against a fixture set, score each result, return a report.
2769
+ *
2770
+ * Online counterpart to `learn`: where `learn` reflects on past trajectories
2771
+ * after the fact, `bench` runs the flow live against fresh `cases`, judges
2772
+ * each output, and produces a `BenchReport` you can compare against a
2773
+ * committed baseline via `regression_compare`.
2774
+ *
2775
+ * Each case becomes one `run(flow, case.input, ...)`. Per-case observability:
2776
+ * - `trajectory_dir` writes `${dir}/${case.id}.jsonl` via filesystem_logger
2777
+ * - `live_url` POSTs each event via http_logger to a viewer's /api/ingest
2778
+ * - both can be combined; bench tees them with an internal cost tracker
2779
+ *
2780
+ * Cost is tracked per-case in-process by intercepting `kind: 'cost'` events
2781
+ * on the trajectory pipeline. The cost number matches what would be on disk
2782
+ * even when no trajectory_dir is set.
2783
+ *
2784
+ * Judges run as Steps after each case, with the same trajectory logger so
2785
+ * judge spans land in the case's trajectory file (or push). A judge that
2786
+ * throws or returns undefined abstains: the entry is omitted from
2787
+ * `case.scores` and the case does not contribute to that judge's mean.
2788
+ */
2789
+ async function bench(flow, cases, judges, options = {}) {
2790
+ const run_id = options.run_id ?? `bench-${String(Date.now())}-${random_suffix()}`;
2791
+ const flow_name = describe_flow_name(flow);
2792
+ const concurrency = resolve_concurrency(options.concurrency, cases.length);
2793
+ const install_signal_handlers = options.install_signal_handlers ?? false;
2794
+ if (options.trajectory_dir !== void 0) await mkdir(options.trajectory_dir, { recursive: true });
2795
+ const judge_entries = Object.entries(judges);
2796
+ const run_one = async (bc) => {
2797
+ const trajectory_path = options.trajectory_dir === void 0 ? void 0 : join(options.trajectory_dir, `${bc.id}.jsonl`);
2798
+ const sinks = [];
2799
+ if (trajectory_path !== void 0) sinks.push(filesystem_logger({ output_path: trajectory_path }));
2800
+ if (options.live_url !== void 0) sinks.push(http_logger({ url: options.live_url }));
2801
+ const cost_tracker = create_cost_tracker();
2802
+ const case_logger = sinks.length === 0 ? cost_tracker.logger : tee_logger(...sinks, cost_tracker.logger);
2803
+ const start = Date.now();
2804
+ let output;
2805
+ let error;
2806
+ let ok = false;
2807
+ try {
2808
+ output = await run(flow, bc.input, {
2809
+ trajectory: case_logger,
2810
+ install_signal_handlers
2811
+ });
2812
+ ok = true;
2813
+ } catch (err) {
2814
+ error = err instanceof Error ? err.message : String(err);
2815
+ ok = false;
2816
+ }
2817
+ const scores = {};
2818
+ if (ok && output !== void 0) {
2819
+ const judge_input = bc.meta === void 0 ? {
2820
+ input: bc.input,
2821
+ output
2822
+ } : {
2823
+ input: bc.input,
2824
+ output,
2825
+ meta: bc.meta
2826
+ };
2827
+ for (const [name, judge] of judge_entries) {
2828
+ let raw;
2829
+ try {
2830
+ raw = await run(judge, judge_input, {
2831
+ trajectory: case_logger,
2832
+ install_signal_handlers
2833
+ });
2834
+ } catch {
2835
+ continue;
2836
+ }
2837
+ const normalized = normalize_score(raw);
2838
+ if (normalized === void 0) continue;
2839
+ scores[name] = normalized;
2840
+ }
2841
+ }
2842
+ const duration_ms = Date.now() - start;
2843
+ const result = {
2844
+ case_id: bc.id,
2845
+ ok,
2846
+ ...output !== void 0 ? { output } : {},
2847
+ ...error !== void 0 ? { error } : {},
2848
+ scores,
2849
+ duration_ms,
2850
+ cost_usd: cost_tracker.total(),
2851
+ ...trajectory_path !== void 0 ? { trajectory_path } : {}
2852
+ };
2853
+ if (options.on_case) options.on_case(result);
2854
+ return result;
2855
+ };
2856
+ const cases_out = await run_with_concurrency(cases, concurrency, run_one);
2857
+ return {
2858
+ flow_name,
2859
+ run_id,
2860
+ cases: cases_out,
2861
+ summary: summarize(cases_out, judge_entries.map(([n]) => n))
2862
+ };
2863
+ }
2864
+ function summarize(cases, judge_names) {
2865
+ const total_duration_ms = cases.reduce((acc, c) => acc + c.duration_ms, 0);
2866
+ const total_cost_usd = cases.reduce((acc, c) => acc + c.cost_usd, 0);
2867
+ const ok_count = cases.filter((c) => c.ok).length;
2868
+ const pass_rate = cases.length === 0 ? 0 : ok_count / cases.length;
2869
+ const mean_cost_usd = cases.length === 0 ? 0 : total_cost_usd / cases.length;
2870
+ const mean_scores = {};
2871
+ for (const name of judge_names) {
2872
+ let sum = 0;
2873
+ let count = 0;
2874
+ for (const c of cases) {
2875
+ const n = score_value_of(c.scores[name]);
2876
+ if (n === void 0) continue;
2877
+ sum += n;
2878
+ count += 1;
2879
+ }
2880
+ if (count > 0) mean_scores[name] = sum / count;
2881
+ }
2882
+ return {
2883
+ pass_rate,
2884
+ mean_scores,
2885
+ total_duration_ms,
2886
+ total_cost_usd,
2887
+ mean_cost_usd
2888
+ };
2889
+ }
2890
+ function normalize_score(raw) {
2891
+ if (raw === void 0 || raw === null) return void 0;
2892
+ if (typeof raw === "number") return Number.isFinite(raw) ? { score: raw } : void 0;
2893
+ if (typeof raw === "object" && "score" in raw) {
2894
+ const r = raw;
2895
+ if (typeof r.score !== "number" || !Number.isFinite(r.score)) return void 0;
2896
+ if (r.reason !== void 0 && typeof r.reason !== "string") return { score: r.score };
2897
+ return r.reason === void 0 ? { score: r.score } : {
2898
+ score: r.score,
2899
+ reason: r.reason
2900
+ };
2901
+ }
2902
+ }
2903
+ function score_value_of(s) {
2904
+ if (s === void 0 || s === null) return void 0;
2905
+ if (typeof s === "number") return Number.isFinite(s) ? s : void 0;
2906
+ if (typeof s === "object" && "score" in s) {
2907
+ const raw = s["score"];
2908
+ return typeof raw === "number" && Number.isFinite(raw) ? raw : void 0;
2909
+ }
2910
+ }
2911
+ function create_cost_tracker() {
2912
+ let total = 0;
2913
+ return {
2914
+ total: () => total,
2915
+ logger: {
2916
+ record: (event) => {
2917
+ if (event.kind !== "cost") return;
2918
+ const value = event["total_usd"];
2919
+ if (typeof value === "number" && Number.isFinite(value)) total += value;
2920
+ },
2921
+ start_span: (name) => `cost-tracker:${name}`,
2922
+ end_span: () => {}
2923
+ }
2924
+ };
2925
+ }
2926
+ async function run_with_concurrency(items, limit, fn) {
2927
+ if (items.length === 0) return [];
2928
+ if (limit >= items.length) return Promise.all(items.map((it) => fn(it)));
2929
+ const results = Array.from({ length: items.length });
2930
+ let next = 0;
2931
+ const worker = async () => {
2932
+ while (true) {
2933
+ const idx = next;
2934
+ next += 1;
2935
+ if (idx >= items.length) return;
2936
+ const item = items[idx];
2937
+ if (item === void 0) continue;
2938
+ results[idx] = await fn(item);
2939
+ }
2940
+ };
2941
+ const workers = [];
2942
+ for (let i = 0; i < limit; i += 1) workers.push(worker());
2943
+ await Promise.all(workers);
2944
+ return results;
2945
+ }
2946
+ function resolve_concurrency(value, n_cases) {
2947
+ if (value === void 0) return Math.max(1, n_cases);
2948
+ if (!Number.isFinite(value) || value <= 0) return Math.max(1, n_cases);
2949
+ return Math.max(1, Math.floor(value));
2950
+ }
2951
+ function describe_flow_name(flow) {
2952
+ const display = flow.config?.["display_name"];
2953
+ if (typeof display === "string" && display.length > 0) return display;
2954
+ return flow.id ?? flow.kind ?? "flow";
2955
+ }
2956
+ function random_suffix() {
2957
+ return Math.random().toString(36).slice(2, 8);
2958
+ }
2959
+ //#endregion
2960
+ //#region packages/composites/src/judges.ts
2961
+ /**
2962
+ * Stock judges for `bench`.
2963
+ *
2964
+ * A `Judge<I, O, S>` is a `Step<{ input, output, meta }, S>` — i.e. just a
2965
+ * step that scores a flow's input/output/metadata triple. Returning
2966
+ * `undefined` (or throwing) means the judge abstains; bench records the
2967
+ * absence as a missing key in `case.scores` and excludes the case from that
2968
+ * judge's `mean_scores` denominator.
2969
+ *
2970
+ * judge_equals — strict equality vs. `meta.expected`
2971
+ * judge_with — wrap a user-supplied scoring function
2972
+ * judge_llm — prompt a model + parse the rubric score out of the reply
2973
+ *
2974
+ * `judge_llm` is engine-agnostic: callers pass their already-configured
2975
+ * model_call step (Step<string, string>), which keeps composites decoupled
2976
+ * from @repo/engine. The user-facing wiring lives in their own code.
2977
+ */
2978
+ function is_record(v) {
2979
+ return v !== null && typeof v === "object" && !Array.isArray(v);
2980
+ }
2981
+ function deep_equal(a, b) {
2982
+ if (a === b) return true;
2983
+ if (a === null || b === null) return false;
2984
+ if (typeof a !== typeof b) return false;
2985
+ if (typeof a !== "object") return false;
2986
+ if (Array.isArray(a) !== Array.isArray(b)) return false;
2987
+ if (Array.isArray(a) && Array.isArray(b)) {
2988
+ if (a.length !== b.length) return false;
2989
+ for (let i = 0; i < a.length; i += 1) if (!deep_equal(a[i], b[i])) return false;
2990
+ return true;
2004
2991
  }
2005
- });
2006
- register_kind("stash", async (flow, input, ctx) => {
2007
- const span_id = ctx.trajectory.start_span("stash", { id: flow.id });
2008
- try {
2009
- const out = await flow.run(input, ctx);
2010
- ctx.trajectory.end_span(span_id, { id: flow.id });
2011
- return out;
2012
- } catch (err) {
2013
- ctx.trajectory.end_span(span_id, {
2014
- id: flow.id,
2015
- error: err instanceof Error ? err.message : String(err)
2016
- });
2017
- throw err;
2992
+ if (!is_record(a) || !is_record(b)) return false;
2993
+ const ak = Object.keys(a).toSorted();
2994
+ const bk = Object.keys(b).toSorted();
2995
+ if (ak.length !== bk.length) return false;
2996
+ for (let i = 0; i < ak.length; i += 1) {
2997
+ const ka = ak[i];
2998
+ const kb = bk[i];
2999
+ if (ka === void 0 || kb === void 0 || ka !== kb) return false;
3000
+ if (!deep_equal(a[ka], b[kb])) return false;
2018
3001
  }
2019
- });
2020
- register_kind("use", async (flow, input, ctx) => {
2021
- const span_id = ctx.trajectory.start_span("use", { id: flow.id });
3002
+ return true;
3003
+ }
3004
+ function judge_equals() {
3005
+ return step("judge_equals", (args) => {
3006
+ if (args.meta === void 0) return void 0;
3007
+ if (!("expected" in args.meta)) return void 0;
3008
+ const expected = args.meta["expected"];
3009
+ const matches = deep_equal(args.output, expected);
3010
+ return {
3011
+ score: matches ? 1 : 0,
3012
+ reason: matches ? "match" : "mismatch"
3013
+ };
3014
+ });
3015
+ }
3016
+ function judge_with(fn) {
3017
+ return step("judge_with", async (args) => {
3018
+ return normalize_score(await fn(args));
3019
+ });
3020
+ }
3021
+ function judge_llm(config) {
3022
+ const scale = config.scale ?? {
3023
+ min: 0,
3024
+ max: 1
3025
+ };
3026
+ const build_prompt = step("judge_llm_build_prompt", (args) => render_prompt(config.rubric, scale, args));
3027
+ const parse = step("judge_llm_parse", (reply) => parse_score(reply, scale));
3028
+ return compose("judge_llm", sequence([
3029
+ build_prompt,
3030
+ config.model,
3031
+ parse
3032
+ ]));
3033
+ }
3034
+ function render_prompt(rubric, scale, args) {
3035
+ return [
3036
+ `You are an evaluator. Score the model output against the rubric below.`,
3037
+ ``,
3038
+ `Rubric:`,
3039
+ rubric,
3040
+ ``,
3041
+ `Return a single line of JSON with exactly two keys: {"score": <number ${String(scale.min)}..${String(scale.max)}>, "reason": "<short>"}.`,
3042
+ `Do not include prose outside the JSON.`,
3043
+ ``,
3044
+ `Input:`,
3045
+ JSON.stringify(args.input),
3046
+ ``,
3047
+ `Output:`,
3048
+ JSON.stringify(args.output)
3049
+ ].join("\n");
3050
+ }
3051
+ function parse_score(reply, scale) {
3052
+ const candidate = extract_json_object(reply.trim());
3053
+ if (candidate === void 0) return void 0;
3054
+ let parsed;
2022
3055
  try {
2023
- const out = await flow.run(input, ctx);
2024
- ctx.trajectory.end_span(span_id, { id: flow.id });
2025
- return out;
2026
- } catch (err) {
2027
- ctx.trajectory.end_span(span_id, {
2028
- id: flow.id,
2029
- error: err instanceof Error ? err.message : String(err)
2030
- });
2031
- throw err;
3056
+ parsed = JSON.parse(candidate);
3057
+ } catch {
3058
+ return;
2032
3059
  }
2033
- });
2034
- //#endregion
2035
- //#region packages/core/src/version.ts
2036
- const version = "0.1.13";
3060
+ if (!is_record(parsed)) return void 0;
3061
+ const raw_score = parsed["score"];
3062
+ if (typeof raw_score !== "number" || !Number.isFinite(raw_score)) return void 0;
3063
+ const clamped = Math.max(scale.min, Math.min(scale.max, raw_score));
3064
+ const raw_reason = parsed["reason"];
3065
+ const reason = typeof raw_reason === "string" ? raw_reason : void 0;
3066
+ return reason === void 0 ? { score: clamped } : {
3067
+ score: clamped,
3068
+ reason
3069
+ };
3070
+ }
3071
+ function extract_json_object(text) {
3072
+ if (text.startsWith("{")) return text;
3073
+ const start = text.indexOf("{");
3074
+ const end = text.lastIndexOf("}");
3075
+ if (start === -1 || end === -1 || end < start) return void 0;
3076
+ return text.slice(start, end + 1);
3077
+ }
2037
3078
  //#endregion
2038
- //#region packages/core/src/index.ts
3079
+ //#region packages/composites/src/regression.ts
2039
3080
  /**
2040
- * Public surface for @repo/core.
3081
+ * regression_compare: diff two BenchReports for regressions.
2041
3082
  *
2042
- * Side-effect imports ensure every composer registers itself with the runner
2043
- * at module load. Importing anything from `@repo/core` populates the
2044
- * dispatch table with all 16 primitives.
3083
+ * The contract: given a `current` report and a `baseline` report, produce a
3084
+ * `RegressionReport` whose `ok` flag is false when any tracked metric got
3085
+ * worse beyond a threshold. The function does NOT short-circuit on first
3086
+ * failure — every metric and every per-case delta is computed so callers can
3087
+ * print or assert against the whole report.
3088
+ *
3089
+ * Tracked metrics:
3090
+ * - pass_rate (any drop is a regression by default)
3091
+ * - mean_scores.<name> (per judge; any drop is a regression by default)
3092
+ * - total_cost_usd (a relative cost increase above cost_threshold
3093
+ * counts as a regression; default 10%)
3094
+ *
3095
+ * Baselines are plain JSON, written via `write_baseline` and read via
3096
+ * `read_baseline`. They live wherever the caller decides — typically
3097
+ * `bench/<flow>/baseline.json`, checked into git per spec/eval.md §3.
2045
3098
  */
2046
- const flow_schema = flow_schema_default;
3099
+ function regression_compare(current, baseline, options = {}) {
3100
+ const score_threshold = options.score_threshold ?? 0;
3101
+ const cost_threshold = options.cost_threshold ?? .1;
3102
+ const deltas = [];
3103
+ const pass_delta = current.summary.pass_rate - baseline.summary.pass_rate;
3104
+ deltas.push({
3105
+ metric: "pass_rate",
3106
+ baseline: baseline.summary.pass_rate,
3107
+ current: current.summary.pass_rate,
3108
+ delta: pass_delta,
3109
+ is_regression: pass_delta < -score_threshold
3110
+ });
3111
+ const judge_names = collect_judge_names(current, baseline);
3112
+ for (const name of judge_names) {
3113
+ const c = current.summary.mean_scores[name] ?? 0;
3114
+ const b = baseline.summary.mean_scores[name] ?? 0;
3115
+ const d = c - b;
3116
+ deltas.push({
3117
+ metric: `mean_scores.${name}`,
3118
+ baseline: b,
3119
+ current: c,
3120
+ delta: d,
3121
+ is_regression: d < -score_threshold
3122
+ });
3123
+ }
3124
+ const cb = baseline.summary.total_cost_usd;
3125
+ const cc = current.summary.total_cost_usd;
3126
+ const cost_delta = cc - cb;
3127
+ const cost_ratio = cb === 0 ? cc > 0 ? Infinity : 0 : cost_delta / cb;
3128
+ deltas.push({
3129
+ metric: "total_cost_usd",
3130
+ baseline: cb,
3131
+ current: cc,
3132
+ delta: cost_delta,
3133
+ is_regression: cost_ratio > cost_threshold
3134
+ });
3135
+ const per_case = compute_per_case(current, baseline, score_threshold, cost_threshold);
3136
+ return {
3137
+ ok: !deltas.some((d) => d.is_regression) && !per_case.some((c) => c.is_regression),
3138
+ deltas,
3139
+ per_case
3140
+ };
3141
+ }
3142
+ function compute_per_case(current, baseline, score_threshold, cost_threshold) {
3143
+ const by_id_current = index_by_case_id(current.cases);
3144
+ const by_id_baseline = index_by_case_id(baseline.cases);
3145
+ const all_ids = new Set([...by_id_current.keys(), ...by_id_baseline.keys()]);
3146
+ const out = [];
3147
+ for (const id of all_ids) {
3148
+ const c = by_id_current.get(id);
3149
+ const b = by_id_baseline.get(id);
3150
+ const score_deltas = {};
3151
+ let any_score_regression = false;
3152
+ const judge_names = new Set([...Object.keys(c?.scores ?? {}), ...Object.keys(b?.scores ?? {})]);
3153
+ for (const name of judge_names) {
3154
+ const delta = score_value(c?.scores[name]) - score_value(b?.scores[name]);
3155
+ score_deltas[name] = delta;
3156
+ if (delta < -score_threshold) any_score_regression = true;
3157
+ }
3158
+ const cost_delta = (c?.cost_usd ?? 0) - (b?.cost_usd ?? 0);
3159
+ const cost_ratio_regression = b?.cost_usd !== void 0 && b.cost_usd > 0 ? cost_delta / b.cost_usd > cost_threshold : (c?.cost_usd ?? 0) > 0 && (b?.cost_usd ?? 0) === 0 && cost_threshold < Infinity;
3160
+ const ok_regression = b?.ok === true && c?.ok !== true;
3161
+ out.push({
3162
+ case_id: id,
3163
+ ...b !== void 0 ? { baseline: b } : {},
3164
+ ...c !== void 0 ? { current: c } : {},
3165
+ score_deltas,
3166
+ cost_delta,
3167
+ is_regression: any_score_regression || cost_ratio_regression || ok_regression
3168
+ });
3169
+ }
3170
+ return out;
3171
+ }
3172
+ function score_value(s) {
3173
+ if (s === void 0 || s === null) return 0;
3174
+ if (typeof s === "number") return Number.isFinite(s) ? s : 0;
3175
+ if (typeof s === "object" && "score" in s) {
3176
+ const v = s["score"];
3177
+ return typeof v === "number" && Number.isFinite(v) ? v : 0;
3178
+ }
3179
+ return 0;
3180
+ }
3181
+ function index_by_case_id(cases) {
3182
+ const m = /* @__PURE__ */ new Map();
3183
+ for (const c of cases) m.set(c.case_id, c);
3184
+ return m;
3185
+ }
3186
+ function collect_judge_names(a, b) {
3187
+ return [...new Set([...Object.keys(a.summary.mean_scores), ...Object.keys(b.summary.mean_scores)])].toSorted();
3188
+ }
3189
+ async function read_baseline(path) {
3190
+ const text = await readFile(path, "utf8");
3191
+ const parsed = JSON.parse(text);
3192
+ validate_report(parsed, path);
3193
+ return parsed;
3194
+ }
3195
+ async function write_baseline(path, report) {
3196
+ await mkdir(dirname(path), { recursive: true });
3197
+ await writeFile(path, `${JSON.stringify(report, null, 2)}\n`, "utf8");
3198
+ }
3199
+ function validate_report(value, path) {
3200
+ if (value === null || typeof value !== "object") throw new Error(`baseline at ${path} is not an object`);
3201
+ const v = value;
3202
+ if (typeof v.flow_name !== "string" || typeof v.run_id !== "string") throw new Error(`baseline at ${path} missing flow_name/run_id`);
3203
+ if (!Array.isArray(v.cases) || typeof v.summary !== "object" || v.summary === null) throw new Error(`baseline at ${path} missing cases/summary`);
3204
+ }
2047
3205
  //#endregion
2048
3206
  //#region packages/engine/src/version.ts
2049
- const version$1 = "0.1.13";
3207
+ const version$1 = "0.3.8";
2050
3208
  //#endregion
2051
3209
  //#region packages/engine/src/errors.ts
2052
3210
  var rate_limit_error = class extends Error {
@@ -2588,7 +3746,9 @@ const ANTHROPIC_THINKING_BUDGETS = {
2588
3746
  none: 0,
2589
3747
  low: 1024,
2590
3748
  medium: 5e3,
2591
- high: 2e4
3749
+ high: 2e4,
3750
+ xhigh: 32e3,
3751
+ max: 64e3
2592
3752
  };
2593
3753
  function translate_anthropic_effort(effort) {
2594
3754
  const budget = ANTHROPIC_THINKING_BUDGETS[effort];
@@ -2638,7 +3798,9 @@ const create_anthropic_adapter = (init) => {
2638
3798
  const OPENAI_REASONING_EFFORT = {
2639
3799
  low: "low",
2640
3800
  medium: "medium",
2641
- high: "high"
3801
+ high: "high",
3802
+ xhigh: "high",
3803
+ max: "high"
2642
3804
  };
2643
3805
  function translate_openai_effort(effort) {
2644
3806
  if (effort === "none") return {
@@ -2686,7 +3848,9 @@ const create_openai_adapter = (init) => {
2686
3848
  const GOOGLE_THINKING_BUDGET = {
2687
3849
  low: "low",
2688
3850
  medium: "medium",
2689
- high: "high"
3851
+ high: "high",
3852
+ xhigh: "high",
3853
+ max: "high"
2690
3854
  };
2691
3855
  function translate_google_effort(effort) {
2692
3856
  if (effort === "none") return {
@@ -3955,9 +5119,21 @@ const SUPPORTED = new Set([
3955
5119
  "text",
3956
5120
  "tools",
3957
5121
  "schema",
3958
- "streaming"
5122
+ "streaming",
5123
+ "reasoning"
3959
5124
  ]);
3960
5125
  const PROVIDER_NAME = "claude_cli";
5126
+ const CLAUDE_CLI_EFFORT_VALUES = {
5127
+ low: "low",
5128
+ medium: "medium",
5129
+ high: "high",
5130
+ xhigh: "xhigh",
5131
+ max: "max"
5132
+ };
5133
+ function effort_env_for_claude_cli(effort) {
5134
+ if (effort === void 0 || effort === "none") return {};
5135
+ return { CLAUDE_CODE_EFFORT_LEVEL: CLAUDE_CLI_EFFORT_VALUES[effort] };
5136
+ }
3961
5137
  function extract_call_opts(opts) {
3962
5138
  const raw = opts.provider_options?.["claude_cli"];
3963
5139
  if (raw === void 0 || raw === null || typeof raw !== "object") return {};
@@ -4088,6 +5264,7 @@ function create_claude_cli_adapter(init) {
4088
5264
  const merged_system = merge_system(opts.system ?? system_from_prompt, call_opts.append_system_prompt);
4089
5265
  const stdin_text = extract_prompt_text(opts.prompt);
4090
5266
  const env = build_env(config, call_opts.env, resolved_auth_mode);
5267
+ Object.assign(env, effort_env_for_claude_cli(opts.effort));
4091
5268
  const sandbox_plan = build_sandbox_plan(resolved_binary, config.sandbox);
4092
5269
  const cwd = config.default_cwd;
4093
5270
  const dispatch_chunk = opts.on_chunk !== void 0 ? async (chunk) => {
@@ -5527,6 +6704,544 @@ function forward_standard_env() {
5527
6704
  return out;
5528
6705
  }
5529
6706
  //#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 };
6707
+ //#region packages/viewer/src/broadcast.ts
6708
+ function create_broadcaster(options) {
6709
+ const max = Math.max(1, options.buffer | 0);
6710
+ const ring = [];
6711
+ const subscribers = /* @__PURE__ */ new Set();
6712
+ let next_id = 1;
6713
+ const emit = (event) => {
6714
+ const entry = {
6715
+ id: next_id++,
6716
+ event
6717
+ };
6718
+ ring.push(entry);
6719
+ if (ring.length > max) ring.splice(0, ring.length - max);
6720
+ for (const fn of Array.from(subscribers)) try {
6721
+ fn(entry);
6722
+ } catch (err) {
6723
+ subscribers.delete(fn);
6724
+ if (options.on_subscriber_error) options.on_subscriber_error(err);
6725
+ }
6726
+ return entry;
6727
+ };
6728
+ const subscribe = (fn) => {
6729
+ subscribers.add(fn);
6730
+ return () => {
6731
+ subscribers.delete(fn);
6732
+ };
6733
+ };
6734
+ const snapshot = () => [...ring];
6735
+ const snapshot_after = (last_id) => ring.filter((e) => e.id > last_id);
6736
+ const size = () => ring.length;
6737
+ return {
6738
+ emit,
6739
+ subscribe,
6740
+ snapshot,
6741
+ snapshot_after,
6742
+ size
6743
+ };
6744
+ }
6745
+ //#endregion
6746
+ //#region packages/viewer/src/server.ts
6747
+ /**
6748
+ * Tiny HTTP server: 5 routes, SSE fan-out, NDJSON ingest.
6749
+ *
6750
+ * GET / -> static viewer.html
6751
+ * GET /api/events -> text/event-stream replaying the ring buffer
6752
+ * GET /api/snapshot -> JSON dump of the ring buffer
6753
+ * POST /api/ingest -> newline-delimited trajectory events (http_logger)
6754
+ * GET /api/health -> { ok: true }
6755
+ *
6756
+ * The server owns nothing but the socket. The broadcaster owns the event
6757
+ * history; the static html lives on disk. SSE clients reconnect with
6758
+ * `Last-Event-ID` and the server replays anything past their cursor from
6759
+ * the ring buffer; older events are gone (bounded memory by design).
6760
+ */
6761
+ const SSE_HEARTBEAT_MS = 15e3;
6762
+ const STATIC_HTML = resolve(dirname(fileURLToPath(import.meta.url)), "static", "viewer.html");
6763
+ function start_server(options) {
6764
+ const { broadcaster, host, port, on_parse_error } = options;
6765
+ const handler = (req, res) => {
6766
+ const url = new URL(req.url ?? "/", `http://${req.headers.host ?? `${host}:${port}`}`);
6767
+ const route = `${req.method ?? "GET"} ${url.pathname}`;
6768
+ if (route === "GET /" || route === "GET /index.html") {
6769
+ serve_static_html(res);
6770
+ return;
6771
+ }
6772
+ if (route === "GET /api/health") {
6773
+ send_json(res, 200, { ok: true });
6774
+ return;
6775
+ }
6776
+ if (route === "GET /api/snapshot") {
6777
+ send_json(res, 200, { events: broadcaster.snapshot() });
6778
+ return;
6779
+ }
6780
+ if (route === "GET /api/events") {
6781
+ handle_sse(req, res, broadcaster);
6782
+ return;
6783
+ }
6784
+ if (route === "POST /api/ingest") {
6785
+ handle_ingest(req, res, broadcaster, on_parse_error);
6786
+ return;
6787
+ }
6788
+ res.statusCode = 404;
6789
+ res.setHeader("content-type", "application/json");
6790
+ res.end(JSON.stringify({
6791
+ error: "not_found",
6792
+ route
6793
+ }));
6794
+ };
6795
+ const http_server = createServer(handler);
6796
+ return new Promise((res_ok, res_err) => {
6797
+ http_server.once("error", res_err);
6798
+ http_server.listen(port, host, () => {
6799
+ http_server.removeListener("error", res_err);
6800
+ const addr = http_server.address();
6801
+ res_ok({
6802
+ url: `http://${host}:${addr !== null && typeof addr === "object" && "port" in addr ? addr.port : port}`,
6803
+ close: () => close_server(http_server)
6804
+ });
6805
+ });
6806
+ });
6807
+ }
6808
+ function close_server(server) {
6809
+ return new Promise((res_ok, res_err) => {
6810
+ server.close((err) => {
6811
+ if (err) res_err(err);
6812
+ else res_ok();
6813
+ });
6814
+ server.closeAllConnections?.();
6815
+ });
6816
+ }
6817
+ function send_json(res, status, body) {
6818
+ res.statusCode = status;
6819
+ res.setHeader("content-type", "application/json");
6820
+ res.end(JSON.stringify(body));
6821
+ }
6822
+ function serve_static_html(res) {
6823
+ let size;
6824
+ try {
6825
+ size = statSync(STATIC_HTML).size;
6826
+ } catch {
6827
+ res.statusCode = 500;
6828
+ res.setHeader("content-type", "text/plain");
6829
+ res.end("viewer.html missing");
6830
+ return;
6831
+ }
6832
+ res.statusCode = 200;
6833
+ res.setHeader("content-type", "text/html; charset=utf-8");
6834
+ res.setHeader("cache-control", "no-store");
6835
+ res.setHeader("content-length", String(size));
6836
+ createReadStream(STATIC_HTML).pipe(res);
6837
+ }
6838
+ function handle_sse(req, res, broadcaster) {
6839
+ res.statusCode = 200;
6840
+ res.setHeader("content-type", "text/event-stream");
6841
+ res.setHeader("cache-control", "no-store");
6842
+ res.setHeader("connection", "keep-alive");
6843
+ res.setHeader("x-accel-buffering", "no");
6844
+ const last_event_id = parse_last_event_id(req.headers["last-event-id"]);
6845
+ for (const entry of broadcaster.snapshot_after(last_event_id)) write_event(res, entry.id, entry.event);
6846
+ const heartbeat = setInterval(() => {
6847
+ res.write(": heartbeat\n\n");
6848
+ }, SSE_HEARTBEAT_MS);
6849
+ const unsubscribe = broadcaster.subscribe((entry) => {
6850
+ write_event(res, entry.id, entry.event);
6851
+ });
6852
+ const close = () => {
6853
+ clearInterval(heartbeat);
6854
+ unsubscribe();
6855
+ if (!res.writableEnded) {
6856
+ res.write("event: close\ndata: {}\n\n");
6857
+ res.end();
6858
+ }
6859
+ };
6860
+ req.on("close", close);
6861
+ req.on("error", close);
6862
+ }
6863
+ function parse_last_event_id(value) {
6864
+ if (typeof value !== "string") return 0;
6865
+ const n = Number.parseInt(value, 10);
6866
+ return Number.isFinite(n) && n > 0 ? n : 0;
6867
+ }
6868
+ function write_event(res, id, event) {
6869
+ res.write(`id: ${id}\nevent: trajectory\ndata: ${JSON.stringify(event)}\n\n`);
6870
+ }
6871
+ function handle_ingest(req, res, broadcaster, on_parse_error) {
6872
+ let buf = "";
6873
+ let accepted = 0;
6874
+ let rejected = 0;
6875
+ const consume_line = (line) => {
6876
+ if (line.length === 0) return;
6877
+ let parsed;
6878
+ try {
6879
+ parsed = JSON.parse(line);
6880
+ } catch (err) {
6881
+ rejected++;
6882
+ if (on_parse_error) on_parse_error(err, line);
6883
+ return;
6884
+ }
6885
+ const result = trajectory_event_schema.safeParse(parsed);
6886
+ if (!result.success) {
6887
+ rejected++;
6888
+ if (on_parse_error) on_parse_error(result.error, line);
6889
+ return;
6890
+ }
6891
+ broadcaster.emit(result.data);
6892
+ accepted++;
6893
+ };
6894
+ req.setEncoding("utf8");
6895
+ req.on("data", (chunk) => {
6896
+ buf += chunk;
6897
+ let nl = buf.indexOf("\n");
6898
+ while (nl !== -1) {
6899
+ consume_line(buf.slice(0, nl));
6900
+ buf = buf.slice(nl + 1);
6901
+ nl = buf.indexOf("\n");
6902
+ }
6903
+ });
6904
+ req.on("end", () => {
6905
+ if (buf.length > 0) consume_line(buf);
6906
+ send_json(res, 200, {
6907
+ accepted,
6908
+ rejected
6909
+ });
6910
+ });
6911
+ req.on("error", (err) => {
6912
+ if (on_parse_error) on_parse_error(err, "");
6913
+ send_json(res, 400, { error: "bad_request" });
6914
+ });
6915
+ }
6916
+ //#endregion
6917
+ //#region packages/viewer/src/tail.ts
6918
+ /**
6919
+ * JSONL file tailer.
6920
+ *
6921
+ * Watches a file for appends and emits one parsed trajectory event per
6922
+ * complete line. Handles three pathological cases the spec calls out:
6923
+ *
6924
+ * - Truncation / rotation: a watcher event whose stat is shorter than the
6925
+ * current offset means the file shrunk. Reset offset to 0 and re-stream.
6926
+ * - Partial last line: if the trailing chunk has no `\n`, buffer it and
6927
+ * wait. Never parse a half-written line.
6928
+ * - Schema failures: a line that fails `trajectory_event_schema.parse` is
6929
+ * dropped and surfaced to `on_parse_error`. The stream keeps going.
6930
+ *
6931
+ * The watcher is fs.watch-based with a debounced re-read; on platforms where
6932
+ * fs.watch is flaky for appends we still catch up because the next tick
6933
+ * re-stats and re-reads from the saved offset.
6934
+ */
6935
+ function start_tail(options) {
6936
+ const { path, on_event, on_parse_error, on_io_error } = options;
6937
+ let offset = 0;
6938
+ let buffer = "";
6939
+ let busy = false;
6940
+ let pending = false;
6941
+ let closed = false;
6942
+ let watcher = null;
6943
+ let last_drain = Promise.resolve();
6944
+ const handle_line = (line) => {
6945
+ if (line.length === 0) return;
6946
+ let parsed;
6947
+ try {
6948
+ parsed = JSON.parse(line);
6949
+ } catch (err) {
6950
+ if (on_parse_error) on_parse_error(err, line);
6951
+ return;
6952
+ }
6953
+ const result = trajectory_event_schema.safeParse(parsed);
6954
+ if (!result.success) {
6955
+ if (on_parse_error) on_parse_error(result.error, line);
6956
+ return;
6957
+ }
6958
+ on_event(result.data);
6959
+ };
6960
+ const read_more = async () => {
6961
+ let st;
6962
+ try {
6963
+ st = await stat(path);
6964
+ } catch (err) {
6965
+ if (on_io_error) on_io_error(err);
6966
+ return;
6967
+ }
6968
+ if (st.size < offset) {
6969
+ offset = 0;
6970
+ buffer = "";
6971
+ }
6972
+ if (st.size === offset) return;
6973
+ const fh = await open(path, "r").catch((err) => {
6974
+ if (on_io_error) on_io_error(err);
6975
+ return null;
6976
+ });
6977
+ if (!fh) return;
6978
+ try {
6979
+ const length = st.size - offset;
6980
+ const buf = Buffer.alloc(length);
6981
+ const { bytesRead } = await fh.read(buf, 0, length, offset);
6982
+ offset += bytesRead;
6983
+ buffer += buf.subarray(0, bytesRead).toString("utf8");
6984
+ } finally {
6985
+ await fh.close();
6986
+ }
6987
+ let nl = buffer.indexOf("\n");
6988
+ while (nl !== -1) {
6989
+ const line = buffer.slice(0, nl);
6990
+ buffer = buffer.slice(nl + 1);
6991
+ handle_line(line);
6992
+ nl = buffer.indexOf("\n");
6993
+ }
6994
+ };
6995
+ const schedule = () => {
6996
+ if (closed) return;
6997
+ if (busy) {
6998
+ pending = true;
6999
+ return;
7000
+ }
7001
+ busy = true;
7002
+ last_drain = (async () => {
7003
+ try {
7004
+ let keep_going = true;
7005
+ while (keep_going) {
7006
+ pending = false;
7007
+ await read_more();
7008
+ keep_going = pending && !closed;
7009
+ }
7010
+ } finally {
7011
+ busy = false;
7012
+ }
7013
+ })();
7014
+ };
7015
+ schedule();
7016
+ try {
7017
+ watcher = watch(path, { persistent: true }, () => {
7018
+ schedule();
7019
+ });
7020
+ } catch (err) {
7021
+ if (on_io_error) on_io_error(err);
7022
+ }
7023
+ const stop = () => {
7024
+ closed = true;
7025
+ if (watcher) {
7026
+ watcher.close();
7027
+ watcher = null;
7028
+ }
7029
+ };
7030
+ const drain = async () => {
7031
+ schedule();
7032
+ await last_drain;
7033
+ };
7034
+ return {
7035
+ stop,
7036
+ drain
7037
+ };
7038
+ }
7039
+ //#endregion
7040
+ //#region packages/viewer/src/cli.ts
7041
+ /**
7042
+ * fascicle-viewer CLI.
7043
+ *
7044
+ * fascicle-viewer <path> # tail a JSONL file (primary)
7045
+ * fascicle-viewer --listen # accept HTTP push only
7046
+ * fascicle-viewer <path> --listen # both producers feed the same broadcaster
7047
+ *
7048
+ * Flags: --port <n> --host <h> --buffer <n> --no-open --help
7049
+ *
7050
+ * Defaults bind 127.0.0.1:4242 and open the user's default browser. SIGINT
7051
+ * shuts everything down cleanly. The CLI body is exposed as `run_viewer_cli`
7052
+ * so the umbrella's bin shim can drive it from a bundled `dist/index.js`.
7053
+ */
7054
+ const HELP = `\
7055
+ fascicle-viewer — minimal in-repo dashboard for fascicle trajectory streams.
7056
+
7057
+ Usage:
7058
+ fascicle-viewer <path> tail a JSONL file
7059
+ fascicle-viewer --listen accept HTTP push only
7060
+ fascicle-viewer <path> --listen both producers feed the same broadcaster
7061
+
7062
+ Options:
7063
+ --port <n> port (default 4242)
7064
+ --host <h> bind host (default 127.0.0.1; --host 0.0.0.0 warns)
7065
+ --buffer <n> ring-buffer size (default 1000)
7066
+ --no-open do not open the browser
7067
+ --help show this message
7068
+ `;
7069
+ function parse(argv) {
7070
+ const { values, positionals } = parseArgs({
7071
+ args: [...argv],
7072
+ allowPositionals: true,
7073
+ options: {
7074
+ port: {
7075
+ type: "string",
7076
+ default: "4242"
7077
+ },
7078
+ host: {
7079
+ type: "string",
7080
+ default: "127.0.0.1"
7081
+ },
7082
+ buffer: {
7083
+ type: "string",
7084
+ default: "1000"
7085
+ },
7086
+ listen: {
7087
+ type: "boolean",
7088
+ default: false
7089
+ },
7090
+ open: {
7091
+ type: "boolean",
7092
+ default: true
7093
+ },
7094
+ "no-open": {
7095
+ type: "boolean",
7096
+ default: false
7097
+ },
7098
+ help: {
7099
+ type: "boolean",
7100
+ default: false
7101
+ }
7102
+ }
7103
+ });
7104
+ if (values.help) {
7105
+ process.stdout.write(HELP);
7106
+ process.exit(0);
7107
+ }
7108
+ const port_raw = values.port ?? "4242";
7109
+ const buffer_raw = values.buffer ?? "1000";
7110
+ const port = Number.parseInt(port_raw, 10);
7111
+ const buffer = Number.parseInt(buffer_raw, 10);
7112
+ if (!Number.isFinite(port) || port <= 0) {
7113
+ process.stderr.write(`invalid --port: ${port_raw}\n`);
7114
+ process.exit(2);
7115
+ }
7116
+ if (!Number.isFinite(buffer) || buffer <= 0) {
7117
+ process.stderr.write(`invalid --buffer: ${buffer_raw}\n`);
7118
+ process.exit(2);
7119
+ }
7120
+ const path = positionals[0];
7121
+ const listen = values.listen ?? false;
7122
+ if (path === void 0 && !listen) {
7123
+ process.stderr.write("fascicle-viewer: a <path> is required unless --listen is set\n");
7124
+ process.stderr.write(HELP);
7125
+ process.exit(2);
7126
+ }
7127
+ return {
7128
+ ...path !== void 0 ? { path } : {},
7129
+ host: values.host ?? "127.0.0.1",
7130
+ port,
7131
+ buffer,
7132
+ listen,
7133
+ open: !values["no-open"] && (values.open ?? true)
7134
+ };
7135
+ }
7136
+ function open_browser(url) {
7137
+ const platform = process.platform;
7138
+ const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
7139
+ const args = platform === "win32" ? [
7140
+ "/c",
7141
+ "start",
7142
+ "\"\"",
7143
+ url
7144
+ ] : [url];
7145
+ try {
7146
+ const child = spawn(cmd, args, {
7147
+ stdio: "ignore",
7148
+ detached: true
7149
+ });
7150
+ child.on("error", () => {});
7151
+ child.unref();
7152
+ } catch {}
7153
+ }
7154
+ async function run_viewer_cli(argv) {
7155
+ const args = parse(argv);
7156
+ if (args.path !== void 0 && !existsSync(args.path)) process.stderr.write(`fascicle-viewer: warning: ${args.path} does not exist yet — will pick up events once it is created\n`);
7157
+ if (args.host === "0.0.0.0") process.stderr.write("fascicle-viewer: warning: binding 0.0.0.0 — this dashboard has no auth and exposes whatever is in your trajectory stream\n");
7158
+ const handle = await start_viewer({
7159
+ ...args.path !== void 0 ? { path: args.path } : {},
7160
+ host: args.host,
7161
+ port: args.port,
7162
+ buffer: args.buffer,
7163
+ on_parse_error: (err, line) => {
7164
+ const preview = line.length > 120 ? `${line.slice(0, 120)}…` : line;
7165
+ process.stderr.write(`fascicle-viewer: skipped malformed line: ${preview}\n ${describe_error(err)}\n`);
7166
+ },
7167
+ on_io_error: (err) => {
7168
+ process.stderr.write(`fascicle-viewer: io error: ${describe_error(err)}\n`);
7169
+ }
7170
+ });
7171
+ if (args.path !== void 0) process.stderr.write(`watching ${args.path}\n`);
7172
+ if (args.listen || args.path === void 0) process.stderr.write(`listening for HTTP push on ${handle.url}/api/ingest\n`);
7173
+ process.stderr.write(`viewer at ${handle.url}\n`);
7174
+ if (args.open) open_browser(handle.url);
7175
+ const shutdown = async () => {
7176
+ process.stderr.write("\nfascicle-viewer: shutting down\n");
7177
+ await handle.close();
7178
+ process.exit(0);
7179
+ };
7180
+ process.on("SIGINT", () => {
7181
+ shutdown();
7182
+ });
7183
+ process.on("SIGTERM", () => {
7184
+ shutdown();
7185
+ });
7186
+ }
7187
+ function describe_error(err) {
7188
+ if (err instanceof Error) return err.message;
7189
+ try {
7190
+ return JSON.stringify(err);
7191
+ } catch {
7192
+ return String(err);
7193
+ }
7194
+ }
7195
+ if (typeof process.argv[1] === "string" && (process.argv[1].endsWith("/cli.ts") || process.argv[1].endsWith("/cli.js"))) run_viewer_cli(process.argv.slice(2)).catch((err) => {
7196
+ process.stderr.write(`fascicle-viewer: ${describe_error(err)}\n`);
7197
+ process.exit(1);
7198
+ });
7199
+ //#endregion
7200
+ //#region packages/viewer/src/index.ts
7201
+ /**
7202
+ * Public surface for @repo/viewer.
7203
+ *
7204
+ * `start_viewer({ ... })` is the programmatic embed: spin up the server,
7205
+ * optionally start tailing a JSONL file, and return a handle that can stop
7206
+ * both. `start_viewer` only depends on @repo/core's wire-format schema; it
7207
+ * never reaches into the engine, composites, or any provider.
7208
+ */
7209
+ async function start_viewer(options = {}) {
7210
+ const host = options.host ?? "127.0.0.1";
7211
+ const port = options.port ?? 4242;
7212
+ const broadcaster = create_broadcaster({
7213
+ buffer: options.buffer ?? 1e3,
7214
+ ...options.on_subscriber_error ? { on_subscriber_error: options.on_subscriber_error } : {}
7215
+ });
7216
+ const server = await start_server({
7217
+ broadcaster,
7218
+ host,
7219
+ port,
7220
+ ...options.on_parse_error ? { on_parse_error: options.on_parse_error } : {}
7221
+ });
7222
+ let tail = null;
7223
+ if (options.path !== void 0) tail = start_tail({
7224
+ path: options.path,
7225
+ on_event: (event) => {
7226
+ broadcaster.emit(event);
7227
+ },
7228
+ ...options.on_parse_error ? { on_parse_error: options.on_parse_error } : {},
7229
+ ...options.on_io_error ? { on_io_error: options.on_io_error } : {}
7230
+ });
7231
+ return wrap_handle(server, tail, host, port);
7232
+ }
7233
+ function wrap_handle(server, tail, host, port) {
7234
+ return {
7235
+ url: server.url,
7236
+ host,
7237
+ port,
7238
+ close: async () => {
7239
+ if (tail) tail.stop();
7240
+ await server.close();
7241
+ }
7242
+ };
7243
+ }
7244
+ //#endregion
7245
+ export { STEP_KINDS, aborted_error, adversarial, bench, 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, judge_equals, judge_llm, judge_with, learn, loop, map, model_call, model_not_found_error, normalize_score, on_chunk_error, parallel, pipe, provider_capability_error, provider_error, provider_not_configured_error, rate_limit_error, read_baseline, regression_compare, resume_validation_error, retry, run, run_viewer_cli, schema_validation_error, scope, sequence, span_end_event_schema, span_start_event_schema, start_viewer, stash, step, suspend, suspended_error, timeout, timeout_error, tool_approval_denied_error, tool_error, tournament, trajectory_event_schema, use, write_baseline };
5531
7246
 
5532
7247
  //# sourceMappingURL=index.js.map