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/CHANGELOG.md +119 -1
- package/README.md +107 -167
- package/dist/bin/fascicle-viewer.js +9 -0
- package/dist/index.d.ts +474 -69
- package/dist/index.js +2263 -548
- package/dist/index.js.map +1 -1
- package/dist/static/viewer.html +374 -0
- package/package.json +9 -3
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
|
-
|
|
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(
|
|
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
|
|
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
|
-
*
|
|
623
|
-
* step(id, fn)
|
|
624
|
-
* step(fn)
|
|
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
|
-
|
|
702
|
-
|
|
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$
|
|
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$
|
|
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
|
|
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$
|
|
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$
|
|
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:
|
|
1029
|
+
config: config_meta,
|
|
919
1030
|
run: run_fn
|
|
920
1031
|
};
|
|
921
1032
|
}
|
|
922
1033
|
register_kind("parallel", async (flow, input, ctx) => {
|
|
923
|
-
const
|
|
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$
|
|
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$
|
|
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
|
|
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$
|
|
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$
|
|
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
|
-
|
|
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
|
|
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$
|
|
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$
|
|
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:
|
|
1227
|
+
config: config_meta,
|
|
1110
1228
|
run: run_fn
|
|
1111
1229
|
};
|
|
1112
1230
|
}
|
|
1113
1231
|
register_kind("pipe", async (flow, input, ctx) => {
|
|
1114
|
-
const
|
|
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$
|
|
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$
|
|
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
|
|
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$
|
|
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$
|
|
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
|
|
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$
|
|
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$
|
|
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:
|
|
1448
|
+
config: config_meta,
|
|
1323
1449
|
run: run_fn
|
|
1324
1450
|
};
|
|
1325
1451
|
}
|
|
1326
1452
|
register_kind("timeout", async (flow, input, ctx) => {
|
|
1327
|
-
const
|
|
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/
|
|
1468
|
+
//#region packages/core/src/loop.ts
|
|
1342
1469
|
/**
|
|
1343
|
-
*
|
|
1470
|
+
* loop: bounded iteration with carry-state.
|
|
1344
1471
|
*
|
|
1345
|
-
* `
|
|
1346
|
-
* `max_rounds`
|
|
1347
|
-
*
|
|
1348
|
-
*
|
|
1349
|
-
*
|
|
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
|
-
*
|
|
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
|
|
1354
|
-
function next_id$
|
|
1355
|
-
|
|
1356
|
-
return
|
|
1357
|
-
}
|
|
1358
|
-
function
|
|
1359
|
-
|
|
1360
|
-
const
|
|
1361
|
-
|
|
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
|
|
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
|
-
|
|
1369
|
-
|
|
1370
|
-
|
|
1371
|
-
|
|
1372
|
-
|
|
1373
|
-
|
|
1374
|
-
|
|
1375
|
-
|
|
1376
|
-
|
|
1377
|
-
|
|
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
|
-
|
|
1386
|
-
converged
|
|
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: "
|
|
1393
|
-
children: [
|
|
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("
|
|
1402
|
-
const
|
|
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/
|
|
1552
|
+
//#region packages/core/src/compose.ts
|
|
1417
1553
|
/**
|
|
1418
|
-
*
|
|
1554
|
+
* compose: name a composite step.
|
|
1419
1555
|
*
|
|
1420
|
-
* `
|
|
1421
|
-
*
|
|
1422
|
-
*
|
|
1423
|
-
*
|
|
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
|
-
*
|
|
1426
|
-
*
|
|
1427
|
-
*
|
|
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
|
-
*
|
|
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
|
|
1433
|
-
function next_id$
|
|
1434
|
-
|
|
1435
|
-
return
|
|
1436
|
-
}
|
|
1437
|
-
function
|
|
1438
|
-
|
|
1439
|
-
const
|
|
1440
|
-
const
|
|
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: "
|
|
1514
|
-
children:
|
|
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("
|
|
1523
|
-
const
|
|
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/
|
|
1601
|
+
//#region packages/core/src/checkpoint.ts
|
|
1538
1602
|
/**
|
|
1539
|
-
*
|
|
1603
|
+
* checkpoint: persist and resume.
|
|
1540
1604
|
*
|
|
1541
|
-
* `
|
|
1542
|
-
*
|
|
1543
|
-
*
|
|
1544
|
-
*
|
|
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
|
-
*
|
|
1547
|
-
*
|
|
1548
|
-
*
|
|
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.
|
|
1614
|
+
* See spec.md §5.14, §6.3.
|
|
1551
1615
|
*/
|
|
1552
|
-
let
|
|
1553
|
-
function next_id
|
|
1554
|
-
|
|
1555
|
-
return `
|
|
1616
|
+
let checkpoint_counter = 0;
|
|
1617
|
+
function next_id() {
|
|
1618
|
+
checkpoint_counter += 1;
|
|
1619
|
+
return `checkpoint_${checkpoint_counter}`;
|
|
1556
1620
|
}
|
|
1557
|
-
function
|
|
1558
|
-
|
|
1559
|
-
const
|
|
1560
|
-
const
|
|
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
|
-
|
|
1565
|
-
const
|
|
1566
|
-
|
|
1567
|
-
|
|
1568
|
-
|
|
1569
|
-
|
|
1570
|
-
|
|
1571
|
-
|
|
1572
|
-
|
|
1573
|
-
|
|
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
|
-
|
|
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: "
|
|
1644
|
-
children:
|
|
1645
|
-
config:
|
|
1647
|
+
kind: "checkpoint",
|
|
1648
|
+
children: [inner],
|
|
1649
|
+
config: config_meta,
|
|
1646
1650
|
run: run_fn
|
|
1647
1651
|
};
|
|
1648
1652
|
}
|
|
1649
|
-
register_kind("
|
|
1650
|
-
const
|
|
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/
|
|
1669
|
+
//#region packages/core/src/suspend.ts
|
|
1665
1670
|
/**
|
|
1666
|
-
*
|
|
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
|
-
*
|
|
1674
|
-
*
|
|
1675
|
-
*
|
|
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.
|
|
1682
|
+
* See spec.md §5.15, §6.4.
|
|
1678
1683
|
*/
|
|
1679
|
-
|
|
1680
|
-
|
|
1681
|
-
|
|
1682
|
-
|
|
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:
|
|
1715
|
+
config: config_meta,
|
|
1887
1716
|
run: run_fn
|
|
1888
1717
|
};
|
|
1889
1718
|
}
|
|
1890
1719
|
register_kind("suspend", async (flow, input, ctx) => {
|
|
1891
|
-
const
|
|
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:
|
|
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:
|
|
1824
|
+
config: config_meta,
|
|
1989
1825
|
run: run_fn
|
|
1990
1826
|
};
|
|
1991
1827
|
}
|
|
1992
|
-
register_kind("scope", async (flow, input, ctx) => {
|
|
1993
|
-
const
|
|
1994
|
-
|
|
1995
|
-
|
|
1996
|
-
|
|
1997
|
-
|
|
1998
|
-
|
|
1999
|
-
|
|
2000
|
-
|
|
2001
|
-
|
|
2002
|
-
|
|
2003
|
-
|
|
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
|
-
|
|
2007
|
-
const
|
|
2008
|
-
|
|
2009
|
-
|
|
2010
|
-
|
|
2011
|
-
|
|
2012
|
-
|
|
2013
|
-
|
|
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
|
-
|
|
2021
|
-
|
|
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
|
-
|
|
2024
|
-
|
|
2025
|
-
return
|
|
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
|
-
|
|
2035
|
-
|
|
2036
|
-
const
|
|
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/
|
|
3079
|
+
//#region packages/composites/src/regression.ts
|
|
2039
3080
|
/**
|
|
2040
|
-
*
|
|
3081
|
+
* regression_compare: diff two BenchReports for regressions.
|
|
2041
3082
|
*
|
|
2042
|
-
*
|
|
2043
|
-
*
|
|
2044
|
-
*
|
|
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
|
-
|
|
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.
|
|
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
|
-
|
|
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
|