fascicle 0.9.6 → 0.9.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
- import { A as timeout_error, C as describe, D as describe_cycle_error, E as aborted_error, O as resume_validation_error, S as sequence, T as run, _ as retry, a as trajectory_event_schema, b as branch, c as scope, d as suspend, f as checkpoint, g as fallback, h as timeout, i as span_start_event_schema, j as flow_schema_default, k as suspended_error, l as stash, m as loop, n as emit_event_schema, o as STEP_KINDS, p as compose, r as span_end_event_schema, s as is_step_kind, t as custom_event_schema, u as use, v as pipe, w as step, x as parallel, y as map } from "./core-CYpxskeT.js";
2
- import { a as http_logger, n as tee_logger, o as filesystem_logger } from "./adapters-Dbx3M8m-.js";
1
+ import { A as timeout_error, C as describe, D as describe_cycle_error, E as aborted_error, O as resume_validation_error, S as sequence, T as run, _ as retry, a as trajectory_event_schema, b as branch, c as scope, d as suspend, f as checkpoint, g as fallback, h as timeout, i as span_start_event_schema, j as flow_schema_default, k as suspended_error, l as stash, m as loop, n as emit_event_schema, o as STEP_KINDS, p as compose, r as span_end_event_schema, s as is_step_kind, t as custom_event_schema, u as use, v as pipe, w as step, x as parallel, y as map } from "./core-DNH8ddMT.js";
2
+ import { a as http_logger, n as tee_logger, o as filesystem_logger } from "./adapters-CJnu1687.js";
3
3
  import { createHash } from "node:crypto";
4
4
  import { z } from "zod";
5
5
  import { mkdir, open, readFile, readdir, stat, writeFile } from "node:fs/promises";
@@ -15,21 +15,16 @@ import { parseArgs } from "node:util";
15
15
  /**
16
16
  * adversarial: build-and-critique loop.
17
17
  *
18
- * `adversarial({ build, critique, accept, max_rounds })` runs up to
19
- * `max_rounds` iterations of: build a candidate (receiving the prior
20
- * candidate and critique notes when available) -> critique the candidate
21
- * -> check `accept(critique_result)`. Returns `{ candidate, converged,
22
- * rounds }`. Does not throw on non-convergence.
23
- *
24
- * Implemented as a `compose`d `loop` whose body builds a new candidate
25
- * and whose guard runs the critique step and checks `accept`. State is
26
- * threaded through `scope`/`stash`/`use` so the build and critique steps
27
- * remain unmodified user-supplied `Step` values.
28
- *
29
18
  * This file is the canonical example of how a user-built composite is
30
- * structured — the entire implementation is a composition of core
19
+ * structured: the entire implementation is a composition of core
31
20
  * primitives. Read it as documentation.
32
21
  */
22
+ /**
23
+ * Projects loop state into the build step's input.
24
+ *
25
+ * Omits `prior` and `critique` until they exist, so the first round's build
26
+ * sees only the original input and later rounds see what came before.
27
+ */
33
28
  function build_input_from_state(s) {
34
29
  if (s.candidate === void 0) return { input: s.input };
35
30
  if (s.critique_notes === void 0) return {
@@ -42,6 +37,20 @@ function build_input_from_state(s) {
42
37
  critique: s.critique_notes
43
38
  };
44
39
  }
40
+ /**
41
+ * Builds a Step that runs up to `max_rounds` iterations of build ->
42
+ * critique -> accept.
43
+ *
44
+ * Each round builds a candidate (receiving the prior candidate and critique
45
+ * notes when available), critiques it, then checks `accept(critique_result)`.
46
+ * Returns `{ candidate, converged, rounds }`. Does not throw on
47
+ * non-convergence; `converged: false` reports it instead.
48
+ *
49
+ * Implemented as a `compose`d `loop` whose body builds a new candidate and
50
+ * whose guard runs the critique step and checks `accept`. State is threaded
51
+ * through `scope`/`stash`/`use` so the build and critique steps remain
52
+ * unmodified user-supplied `Step` values.
53
+ */
45
54
  function adversarial(config) {
46
55
  const { build, critique, accept, max_rounds } = config;
47
56
  const inner = pipe(loop({
@@ -91,13 +100,15 @@ function adversarial(config) {
91
100
  //#endregion
92
101
  //#region src/composites/consensus.ts
93
102
  /**
94
- * consensus: run-until-agreement.
103
+ * consensus: run-until-agreement composite over concurrent members.
104
+ */
105
+ /**
106
+ * Builds a Step that runs every member concurrently with the same input
107
+ * until `agree(results)` accepts a round.
95
108
  *
96
- * `consensus({ members, agree, max_rounds })` runs every member concurrently
97
- * with the same input. If `agree(results)` is true, returns the results with
98
- * `converged: true`. Otherwise re-runs all members up to `max_rounds` times,
99
- * returning the last results with `converged: false` if no agreement is
100
- * reached.
109
+ * On agreement, returns the round's results with `converged: true`.
110
+ * Otherwise re-runs all members up to `max_rounds` times and returns the
111
+ * last results with `converged: false` if no agreement is reached.
101
112
  *
102
113
  * Implemented as a `compose`d `loop` whose body runs `parallel(members)` and
103
114
  * whose guard evaluates `agree`. State carries the original input alongside
@@ -137,12 +148,15 @@ function consensus(config) {
137
148
  //#endregion
138
149
  //#region src/composites/ensemble.ts
139
150
  /**
140
- * ensemble: N-of-M pick-best.
151
+ * ensemble: N-of-M pick-best with a plain-function scorer.
152
+ */
153
+ /**
154
+ * Builds a Step that runs every member concurrently with the same input,
155
+ * scores each result, and returns the winner plus the complete score map.
141
156
  *
142
- * `ensemble({ members, score, select? })` runs every member concurrently with
143
- * the same input, scores each result, and returns the winner (highest or
144
- * lowest by `select`) plus the complete score map. Tie-breaking is "any tied
145
- * result is acceptable".
157
+ * `select` picks the highest (`'max'`, the default) or lowest (`'min'`)
158
+ * score. Tie-breaking is "any tied result is acceptable": the first member
159
+ * (in `members` key order) holding the best score wins.
146
160
  *
147
161
  * Implemented as a `compose`d `sequence` of `parallel(members)` followed by
148
162
  * a single picking step. Cancellation, fan-out, and abort propagation come
@@ -188,26 +202,28 @@ function ensemble(config) {
188
202
  //#region src/composites/ensemble_step.ts
189
203
  /**
190
204
  * ensemble_step: N-of-M pick-best with a Step-based scorer.
205
+ */
206
+ const RESULTS_KEY = "__ensemble_step_results";
207
+ const ITEM_KEY = "__ensemble_step_item";
208
+ /**
209
+ * Builds a Step that runs every member concurrently, scores each result via
210
+ * a scoring `Step`, and returns the best-ranking winner.
191
211
  *
192
- * `ensemble_step({ members, score, rank_by, select? })` is the sibling of
193
- * `ensemble` for the case where scoring is itself a `Step` (e.g. a separate
194
- * model call, a sub-flow, anything that wants its own trajectory span and
195
- * abort routing). Each member runs concurrently with the same input; the
196
- * `score` step is dispatched once per result; `rank_by` projects a number
197
- * out of the structured scored output; the highest- or lowest-ranking
198
- * winner is returned alongside its full structured score and the score
199
- * map for the rest.
212
+ * Sibling of `ensemble` for the case where scoring is itself a `Step` (e.g.
213
+ * a separate model call, a sub-flow, anything that wants its own trajectory
214
+ * span and abort routing). The `score` step is dispatched once per member
215
+ * result; `rank_by` projects a number out of the structured scored output;
216
+ * `select` picks the highest (`'max'`, default) or lowest (`'min'`) rank.
200
217
  *
201
- * Returning `winner_scored` avoids the cost of re-scoring the winner — the
202
- * structured output from the round's scoring run is preserved verbatim.
218
+ * The result carries `winner_scored`, the structured output from the round's
219
+ * scoring run preserved verbatim, so callers never pay to re-score the
220
+ * winner. `scored` holds the structured score for every member.
203
221
  *
204
- * Implemented as a `compose`d `scope` over (`stash(parallel(members))` →
205
- * `to_pairs` → `map(score per result, threading id)` → `use` to pick
222
+ * Implemented as a `compose`d `scope` over (`stash(parallel(members))` ->
223
+ * `to_pairs` -> `map(score per result, threading id)` -> `use` to pick the
206
224
  * winner). Cancellation, fan-out, and abort propagation come from the
207
225
  * underlying `parallel` and `map` contracts.
208
226
  */
209
- const RESULTS_KEY = "__ensemble_step_results";
210
- const ITEM_KEY = "__ensemble_step_item";
211
227
  function ensemble_step(config) {
212
228
  const { members, score, rank_by } = config;
213
229
  const select = config.select ?? "max";
@@ -275,27 +291,31 @@ function ensemble_step(config) {
275
291
  /**
276
292
  * improve: bounded online self-improvement loop.
277
293
  *
278
- * `improve({ seed, propose, score, budget })` runs a round-bounded loop that
279
- * threads a `parent` candidate through repeated propose → score → accept/reject
280
- * cycles. The kernel decides acceptance via a hard gate (`scored.accepted`) and
281
- * an epsilon-improvement test (`scored.score > parent_score + epsilon`).
282
- * Plateau detection stops the loop early when no progress has been made for
283
- * `patience` rounds; an optional wall-clock budget caps total runtime.
284
- *
285
- * `improve` is the *online* counterpart to `learn`: where `learn` reflects on
286
- * recorded trajectories offline, `improve` runs the propose/score loop live
287
- * inside a single run. The amplify example is a domain-specific consumer of
288
- * this same pattern (filesystem mutation, test-suite gates, subprocess
289
- * research). `improve` strips those opinions out so any domain can plug in
294
+ * The *online* counterpart to `learn`: where `learn` reflects on recorded
295
+ * trajectories offline, `improve` runs a propose/score loop live inside a
296
+ * single run. The amplify example is a domain-specific consumer of this
297
+ * same pattern (filesystem mutation, test-suite gates, subprocess
298
+ * research); `improve` strips those opinions out so any domain can plug in
290
299
  * its own `propose` and `score` steps.
300
+ */
301
+ const PRIOR_KEY = "__improve_prior";
302
+ /**
303
+ * Builds a Step that runs a round-bounded loop threading a `parent`
304
+ * candidate through repeated propose -> score -> accept/reject cycles.
291
305
  *
292
- * Implemented as a `compose`d `scope` of (seed) → (init state) → (loop) →
306
+ * Acceptance requires both a hard gate (`scored.accepted`) and an
307
+ * epsilon-improvement test (`scored.score > parent_score + epsilon`).
308
+ * Rejected rounds with a `reason` feed a bounded lessons list back into the
309
+ * next round's input. Plateau detection stops the loop early when no
310
+ * progress has been made for `patience` rounds; an optional wall-clock
311
+ * budget caps total runtime.
312
+ *
313
+ * Implemented as a `compose`d `scope` of (seed) -> (init state) -> (loop) ->
293
314
  * (unwrap). The loop body is itself a small `scope` that snapshots prior
294
315
  * state, builds a round input, dispatches the proposers + scorer via
295
316
  * `ensemble_step`, and merges the outcome back into state via `use`.
296
317
  * State threading is the entire job.
297
318
  */
298
- const PRIOR_KEY = "__improve_prior";
299
319
  function improve(config) {
300
320
  const { seed, propose, score, budget } = config;
301
321
  const epsilon = config.epsilon ?? 0;
@@ -473,6 +493,9 @@ function improve(config) {
473
493
  */
474
494
  const DEFAULT_MAX_EVENTS = 1e4;
475
495
  const META_KEY = "__learn_meta";
496
+ /**
497
+ * Recursively collect every `.jsonl` file path under a directory.
498
+ */
476
499
  async function walk_jsonl(dir) {
477
500
  const out = [];
478
501
  const entries = await readdir(dir, { withFileTypes: true });
@@ -483,6 +506,13 @@ async function walk_jsonl(dir) {
483
506
  }
484
507
  return out;
485
508
  }
509
+ /**
510
+ * Parse one JSONL file into validated trajectory events.
511
+ *
512
+ * Malformed JSON lines and lines that fail schema validation are skipped,
513
+ * each recorded as a `learn.parse_error` event with a 1-indexed line number,
514
+ * so a single corrupt line never sinks an analysis run.
515
+ */
486
516
  async function read_jsonl(file_path, ctx) {
487
517
  const lines = (await readFile(file_path, "utf8")).split("\n");
488
518
  const events = [];
@@ -510,12 +540,23 @@ async function read_jsonl(file_path, ctx) {
510
540
  }
511
541
  return events;
512
542
  }
543
+ /**
544
+ * Throw the abort reason (wrapped in `aborted_error` if needed) when the run
545
+ * has been cancelled.
546
+ */
513
547
  function throw_if_aborted$1(ctx) {
514
548
  if (!ctx.abort.aborted) return;
515
549
  const reason = ctx.abort.reason;
516
550
  if (reason instanceof aborted_error) throw reason;
517
551
  throw new aborted_error("aborted", reason === void 0 ? {} : { reason });
518
552
  }
553
+ /**
554
+ * Materialize a `TrajectorySource` into an event array.
555
+ *
556
+ * `dir` sources walk recursively and sort paths for deterministic order.
557
+ * File-backed sources check `ctx.abort` between files, so cancellation lands
558
+ * at file-level granularity.
559
+ */
519
560
  async function resolve_events(source, ctx) {
520
561
  if (source.kind === "events") return source.events;
521
562
  const file_paths = source.kind === "paths" ? [...source.paths] : (await walk_jsonl(source.dir)).toSorted();
@@ -527,6 +568,9 @@ async function resolve_events(source, ctx) {
527
568
  }
528
569
  return all;
529
570
  }
571
+ /**
572
+ * List the distinct `run_id` values in the events, in first-seen order.
573
+ */
530
574
  function collect_run_ids(events) {
531
575
  const seen = /* @__PURE__ */ new Set();
532
576
  const out = [];
@@ -539,6 +583,14 @@ function collect_run_ids(events) {
539
583
  }
540
584
  return out;
541
585
  }
586
+ /**
587
+ * Build the offline self-improvement step.
588
+ *
589
+ * Composes a scope that resolves and caps the recorded events, builds the
590
+ * `LearnInput` (including `describe(flow)`), runs the user's analyzer, and
591
+ * wraps its proposals with the stashed meta (event count, run ids) into a
592
+ * `LearnResult`.
593
+ */
542
594
  function learn(config) {
543
595
  const { flow, source, analyzer, filter } = config;
544
596
  const max = config.max_events ?? DEFAULT_MAX_EVENTS;
@@ -601,6 +653,13 @@ function learn(config) {
601
653
  * propagation come from `parallel`'s contract; the bracket step only runs
602
654
  * after all members settle.
603
655
  */
656
+ /**
657
+ * Build a single-elimination bracket step over named members.
658
+ *
659
+ * All members run concurrently via `parallel`; the bracket step then reduces
660
+ * survivors round by round with `compare`, recording every match. Requires at
661
+ * least one member so a winner always exists.
662
+ */
604
663
  function tournament(config) {
605
664
  const compare_fn = config.compare;
606
665
  const keys = Object.keys(config.members);
@@ -651,18 +710,22 @@ function tournament(config) {
651
710
  * bench: run a flow against a fixture set, score each result, return a report.
652
711
  *
653
712
  * Online counterpart to `learn`: where `learn` reflects on past trajectories
654
- * after the fact, `bench` runs the flow live against fresh `cases`, judges
655
- * each output, and produces a `BenchReport` you can compare against a
656
- * committed baseline via `regression_compare`.
713
+ * after the fact, `bench` runs the flow live against fresh cases and judges
714
+ * each output.
715
+ */
716
+ /**
717
+ * Runs `flow` against every case, judges each output, and produces a
718
+ * `BenchReport` you can compare against a committed baseline via
719
+ * `regression_compare`.
657
720
  *
658
721
  * Each case becomes one `run(flow, case.input, ...)`. Per-case observability:
659
- * - `trajectory_dir` writes `${dir}/${case.id}.jsonl` via filesystem_logger
660
- * - `live_url` POSTs each event via http_logger to a viewer's /api/ingest
722
+ * - `trajectory_dir` writes `${dir}/${case.id}.jsonl` via `filesystem_logger`
723
+ * - `live_url` POSTs each event via `http_logger` to a viewer's /api/ingest
661
724
  * - both can be combined; bench tees them with an internal cost tracker
662
725
  *
663
726
  * Cost is tracked per-case in-process by intercepting `kind: 'cost'` events
664
- * on the trajectory pipeline. The cost number matches what would be on disk
665
- * even when no trajectory_dir is set.
727
+ * on the trajectory pipeline, so the cost number matches what would be on
728
+ * disk even when no `trajectory_dir` is set.
666
729
  *
667
730
  * Judges run as Steps after each case, with the same trajectory logger so
668
731
  * judge spans land in the case's trajectory file (or push). A judge that
@@ -744,6 +807,13 @@ async function bench(flow, cases, judges, options = {}) {
744
807
  summary: summarize(cases_out, judge_entries.map(([n]) => n))
745
808
  };
746
809
  }
810
+ /**
811
+ * Aggregates per-case results into the report summary.
812
+ *
813
+ * A judge's mean only averages the cases where that judge produced a score;
814
+ * abstained cases do not drag the mean down, and a judge that never scored
815
+ * is omitted from `mean_scores` entirely.
816
+ */
747
817
  function summarize(cases, judge_names) {
748
818
  const total_duration_ms = cases.reduce((acc, c) => acc + c.duration_ms, 0);
749
819
  const total_cost_usd = cases.reduce((acc, c) => acc + c.cost_usd, 0);
@@ -770,6 +840,14 @@ function summarize(cases, judge_names) {
770
840
  mean_cost_usd
771
841
  };
772
842
  }
843
+ /**
844
+ * Coerces a raw judge return value into a `Score`.
845
+ *
846
+ * Accepts a bare finite number or an object with a finite numeric `score`
847
+ * and optional string `reason`. Anything else (including NaN/Infinity, or a
848
+ * non-string `reason`, which is dropped) normalizes toward `undefined` or a
849
+ * reason-less score; `undefined` means the judge abstained.
850
+ */
773
851
  function normalize_score(raw) {
774
852
  if (raw === void 0 || raw === null) return void 0;
775
853
  if (typeof raw === "number") return Number.isFinite(raw) ? { score: raw } : void 0;
@@ -783,6 +861,10 @@ function normalize_score(raw) {
783
861
  };
784
862
  }
785
863
  }
864
+ /**
865
+ * Extracts the numeric value from a score-shaped entry, tolerating both bare
866
+ * numbers and `{ score }` objects since `S` is caller-defined.
867
+ */
786
868
  function score_value_of(s) {
787
869
  if (s === void 0 || s === null) return void 0;
788
870
  if (typeof s === "number") return Number.isFinite(s) ? s : void 0;
@@ -791,6 +873,11 @@ function score_value_of(s) {
791
873
  return typeof raw === "number" && Number.isFinite(raw) ? raw : void 0;
792
874
  }
793
875
  }
876
+ /**
877
+ * Builds a minimal `TrajectoryLogger` that ignores everything except
878
+ * `kind: 'cost'` events and accumulates their `total_usd` into a running
879
+ * total, read back via `total()` after the case finishes.
880
+ */
794
881
  function create_cost_tracker() {
795
882
  let total = 0;
796
883
  return {
@@ -806,6 +893,14 @@ function create_cost_tracker() {
806
893
  }
807
894
  };
808
895
  }
896
+ /**
897
+ * Runs `fn` over `items` with at most `limit` calls in flight, preserving
898
+ * input order in the results.
899
+ *
900
+ * Uses a shared-index worker pool: each of the `limit` workers claims the
901
+ * next unclaimed index and writes its result into that slot, so completion
902
+ * order never reorders the output.
903
+ */
809
904
  async function run_with_concurrency(items, limit, fn) {
810
905
  if (items.length === 0) return [];
811
906
  if (limit >= items.length) return Promise.all(items.map((it) => fn(it)));
@@ -826,16 +921,28 @@ async function run_with_concurrency(items, limit, fn) {
826
921
  await Promise.all(workers);
827
922
  return results;
828
923
  }
924
+ /**
925
+ * Clamps the requested concurrency to a positive integer, defaulting to full
926
+ * fan-out (one worker per case) when unset or invalid.
927
+ */
829
928
  function resolve_concurrency(value, n_cases) {
830
929
  if (value === void 0) return Math.max(1, n_cases);
831
930
  if (!Number.isFinite(value) || value <= 0) return Math.max(1, n_cases);
832
931
  return Math.max(1, Math.floor(value));
833
932
  }
933
+ /**
934
+ * Picks a human-readable name for the report: the flow's `display_name`
935
+ * config when set, else its step id or kind.
936
+ */
834
937
  function describe_flow_name(flow) {
835
938
  const display = flow.config?.["display_name"];
836
939
  if (typeof display === "string" && display.length > 0) return display;
837
940
  return flow.id ?? flow.kind ?? "flow";
838
941
  }
942
+ /**
943
+ * Short random base36 suffix to keep default run ids unique across
944
+ * same-millisecond starts.
945
+ */
839
946
  function random_suffix() {
840
947
  return Math.random().toString(36).slice(2, 8);
841
948
  }
@@ -844,23 +951,32 @@ function random_suffix() {
844
951
  /**
845
952
  * Stock judges for `bench`.
846
953
  *
847
- * A `Judge<I, O, S>` is a `Step<{ input, output, meta }, S>` — i.e. just a
848
- * step that scores a flow's input/output/metadata triple. Returning
849
- * `undefined` (or throwing) means the judge abstains; bench records the
850
- * absence as a missing key in `case.scores` and excludes the case from that
851
- * judge's `mean_scores` denominator.
954
+ * A `Judge<I, O, S>` is a `Step<{ input, output, meta }, S>`: just a step
955
+ * that scores a flow's input/output/metadata triple. Returning `undefined`
956
+ * (or throwing) means the judge abstains; bench records the absence as a
957
+ * missing key in `case.scores` and excludes the case from that judge's
958
+ * `mean_scores` denominator.
852
959
  *
853
- * judge_equals — strict equality vs. `meta.expected`
854
- * judge_with — wrap a user-supplied scoring function
855
- * judge_llm — prompt a model + parse the rubric score out of the reply
960
+ * judge_equals: strict equality vs. `meta.expected`
961
+ * judge_with: wrap a user-supplied scoring function
962
+ * judge_llm: prompt a model + parse the rubric score out of the reply
856
963
  *
857
964
  * `judge_llm` is engine-agnostic: callers pass their already-configured
858
- * model_call step (Step<string, string>), which keeps composites decoupled
965
+ * model_call step (`Step<string, string>`), which keeps composites decoupled
859
966
  * from engine. The user-facing wiring lives in their own code.
860
967
  */
968
+ /**
969
+ * Narrows an unknown value to a plain string-keyed record (non-null object,
970
+ * not an array).
971
+ */
861
972
  function is_record(v) {
862
973
  return v !== null && typeof v === "object" && !Array.isArray(v);
863
974
  }
975
+ /**
976
+ * Structural equality over JSON-shaped values: primitives by `===`, arrays
977
+ * element-wise, records key-by-key with sorted keys. Anything else (class
978
+ * instances, functions) only compares equal by reference.
979
+ */
864
980
  function deep_equal(a, b) {
865
981
  if (a === b) return true;
866
982
  if (Array.isArray(a) || Array.isArray(b)) {
@@ -881,6 +997,10 @@ function deep_equal(a, b) {
881
997
  }
882
998
  return true;
883
999
  }
1000
+ /**
1001
+ * Judge that scores 1 when the output deep-equals `meta.expected`, 0
1002
+ * otherwise. Abstains when the case has no `meta` or no `expected` key.
1003
+ */
884
1004
  function judge_equals() {
885
1005
  return step("judge_equals", (args) => {
886
1006
  if (args.meta === void 0) return void 0;
@@ -893,11 +1013,24 @@ function judge_equals() {
893
1013
  };
894
1014
  });
895
1015
  }
1016
+ /**
1017
+ * Wraps a plain scoring function as a Judge. The function may return a bare
1018
+ * number, a `Score`, or `undefined` to abstain; the result is normalized
1019
+ * via `normalize_score`.
1020
+ */
896
1021
  function judge_with(fn) {
897
1022
  return step("judge_with", async (args) => {
898
1023
  return normalize_score(await fn(args));
899
1024
  });
900
1025
  }
1026
+ /**
1027
+ * Judge that prompts a model with a rubric and parses the score out of the
1028
+ * reply.
1029
+ *
1030
+ * Built as a three-step sequence: render the rubric prompt, run the
1031
+ * caller-supplied model step, parse the JSON score from the reply. An
1032
+ * unparseable reply makes the judge abstain rather than fail the case.
1033
+ */
901
1034
  function judge_llm(config) {
902
1035
  const scale = config.scale ?? {
903
1036
  min: 0,
@@ -911,6 +1044,10 @@ function judge_llm(config) {
911
1044
  parse
912
1045
  ]));
913
1046
  }
1047
+ /**
1048
+ * Renders the evaluator prompt: rubric, required JSON reply shape with the
1049
+ * score scale, and the case's input/output serialized as JSON.
1050
+ */
914
1051
  function render_prompt(rubric, scale, args) {
915
1052
  return [
916
1053
  `You are an evaluator. Score the model output against the rubric below.`,
@@ -928,6 +1065,13 @@ function render_prompt(rubric, scale, args) {
928
1065
  JSON.stringify(args.output)
929
1066
  ].join("\n");
930
1067
  }
1068
+ /**
1069
+ * Parses a model reply into a `Score`, or `undefined` (abstain) when no
1070
+ * valid JSON object with a finite numeric `score` can be extracted.
1071
+ *
1072
+ * Tolerates prose around the JSON via `extract_json_object` and clamps the
1073
+ * score into the configured scale rather than rejecting out-of-range values.
1074
+ */
931
1075
  function parse_score(reply, scale) {
932
1076
  const candidate = extract_json_object(reply.trim());
933
1077
  if (candidate === void 0) return void 0;
@@ -948,6 +1092,11 @@ function parse_score(reply, scale) {
948
1092
  reason
949
1093
  };
950
1094
  }
1095
+ /**
1096
+ * Pulls the outermost `{...}` slice out of a reply that may wrap the JSON
1097
+ * in prose or code fences. Returns the text as-is when it already starts
1098
+ * with `{`.
1099
+ */
951
1100
  function extract_json_object(text) {
952
1101
  if (text.startsWith("{")) return text;
953
1102
  const start = text.indexOf("{");
@@ -963,7 +1112,7 @@ function extract_json_object(text) {
963
1112
  * The contract: given a `current` report and a `baseline` report, produce a
964
1113
  * `RegressionReport` whose `ok` flag is false when any tracked metric got
965
1114
  * worse beyond a threshold. The function does NOT short-circuit on first
966
- * failure — every metric and every per-case delta is computed so callers can
1115
+ * failure; every metric and every per-case delta is computed so callers can
967
1116
  * print or assert against the whole report.
968
1117
  *
969
1118
  * Tracked metrics:
@@ -973,9 +1122,16 @@ function extract_json_object(text) {
973
1122
  * counts as a regression; default 10%)
974
1123
  *
975
1124
  * Baselines are plain JSON, written via `write_baseline` and read via
976
- * `read_baseline`. They live wherever the caller decides — typically
977
- * `bench/<flow>/baseline.json`, checked into git per
978
- * `research/explorations/2026-04-eval-surface.md` §3.
1125
+ * `read_baseline`. They live wherever the caller decides, typically
1126
+ * `bench/<flow>/baseline.json` checked into git.
1127
+ */
1128
+ /**
1129
+ * Diff a current `BenchReport` against a baseline.
1130
+ *
1131
+ * Compares `pass_rate`, each judge's mean score, and total cost, then every
1132
+ * individual case. Score metrics regress on any drop beyond
1133
+ * `score_threshold` (default 0); cost regresses on a relative increase above
1134
+ * `cost_threshold` (default 10%).
979
1135
  */
980
1136
  function regression_compare(current, baseline, options = {}) {
981
1137
  const score_threshold = options.score_threshold ?? 0;
@@ -1020,6 +1176,13 @@ function regression_compare(current, baseline, options = {}) {
1020
1176
  per_case
1021
1177
  };
1022
1178
  }
1179
+ /**
1180
+ * Compute per-case deltas across the union of case ids in both reports.
1181
+ *
1182
+ * Cases present on only one side still appear (missing side scores count as
1183
+ * 0). A case regresses when a judge score drops beyond the threshold, its
1184
+ * cost rises beyond the relative threshold, or it flips from ok to failing.
1185
+ */
1023
1186
  function compute_per_case(current, baseline, score_threshold, cost_threshold) {
1024
1187
  const by_id_current = index_by_case_id(current.cases);
1025
1188
  const by_id_baseline = index_by_case_id(baseline.cases);
@@ -1050,6 +1213,12 @@ function compute_per_case(current, baseline, score_threshold, cost_threshold) {
1050
1213
  }
1051
1214
  return out;
1052
1215
  }
1216
+ /**
1217
+ * Extract a finite numeric score from a raw score entry.
1218
+ *
1219
+ * Accepts a bare number or an object with a numeric `score` field; anything
1220
+ * else (missing, NaN, non-numeric) counts as 0 so deltas stay well-defined.
1221
+ */
1053
1222
  function score_value(s) {
1054
1223
  if (s === void 0 || s === null) return 0;
1055
1224
  if (typeof s === "number") return Number.isFinite(s) ? s : 0;
@@ -1059,24 +1228,42 @@ function score_value(s) {
1059
1228
  }
1060
1229
  return 0;
1061
1230
  }
1231
+ /**
1232
+ * Index case results by their `case_id` for pairwise lookup.
1233
+ */
1062
1234
  function index_by_case_id(cases) {
1063
1235
  const m = /* @__PURE__ */ new Map();
1064
1236
  for (const c of cases) m.set(c.case_id, c);
1065
1237
  return m;
1066
1238
  }
1239
+ /**
1240
+ * Union the judge names appearing in either report, sorted for stable output.
1241
+ */
1067
1242
  function collect_judge_names(a, b) {
1068
1243
  return [.../* @__PURE__ */ new Set([...Object.keys(a.summary.mean_scores), ...Object.keys(b.summary.mean_scores)])].toSorted();
1069
1244
  }
1245
+ /**
1246
+ * Read and validate a baseline `BenchReport` from a JSON file.
1247
+ *
1248
+ * Validation is structural (required fields present), so a hand-edited or
1249
+ * truncated baseline fails loudly with the offending path in the message.
1250
+ */
1070
1251
  async function read_baseline(path) {
1071
1252
  const text = await readFile(path, "utf8");
1072
1253
  const parsed = JSON.parse(text);
1073
1254
  validate_report(parsed, path);
1074
1255
  return parsed;
1075
1256
  }
1257
+ /**
1258
+ * Write a `BenchReport` as pretty-printed JSON, creating parent directories.
1259
+ */
1076
1260
  async function write_baseline(path, report) {
1077
1261
  await mkdir(dirname(path), { recursive: true });
1078
1262
  await writeFile(path, `${JSON.stringify(report, null, 2)}\n`, "utf8");
1079
1263
  }
1264
+ /**
1265
+ * Assert that parsed JSON has the structural shape of a `BenchReport`.
1266
+ */
1080
1267
  function validate_report(value, path) {
1081
1268
  if (value === null || typeof value !== "object") throw new Error(`baseline at ${path} is not an object`);
1082
1269
  const v = value;
@@ -1136,9 +1323,18 @@ const DEFAULT_PRICING = Object.freeze({
1136
1323
  output_per_million: .3
1137
1324
  }
1138
1325
  });
1326
+ /**
1327
+ * Build the `provider:model_id` key used to look up a pricing table entry.
1328
+ */
1139
1329
  function pricing_key(provider, model_id) {
1140
1330
  return `${provider}:${model_id}`;
1141
1331
  }
1332
+ /**
1333
+ * Round a dollar amount to 6 decimal places.
1334
+ *
1335
+ * Per-token rates produce long floating-point tails; 6 places keeps
1336
+ * sub-cent precision without leaking binary rounding noise into reports.
1337
+ */
1142
1338
  function round6$1(value) {
1143
1339
  return Math.round(value * 1e6) / 1e6;
1144
1340
  }
@@ -1230,14 +1426,14 @@ var provider_error = class extends Error {
1230
1426
  }
1231
1427
  };
1232
1428
  /**
1233
- * Turn-timeout expiry (D5). Thrown by the engine-owned retry_turn wrapper when
1234
- * a depth-1 invoke_turn exceeds `turn_timeout_ms` before any chunk streamed.
1429
+ * Turn-timeout expiry. Thrown by the engine-owned retry_turn wrapper when a
1430
+ * single invoke_turn exceeds `turn_timeout_ms` before any chunk streamed.
1235
1431
  * Its `kind` is the RetryFailureKind wire value `'timeout'` (not the class
1236
1432
  * name) on purpose: that is the discriminant classify_retryable /
1237
1433
  * classify_provider_error already key on, so the shared classifier treats an
1238
- * expiry as retryable without any timeout-specific branch. A mid-stream expiry
1239
- * never reaches here — retry_turn converts it to a non-retryable stream
1240
- * interruption first (C4 parity).
1434
+ * expiry as retryable without any timeout-specific branch. A mid-stream
1435
+ * expiry never reaches here; retry_turn converts it to a non-retryable
1436
+ * stream interruption first.
1241
1437
  */
1242
1438
  var turn_timeout_error = class extends Error {
1243
1439
  kind = "timeout";
@@ -1377,6 +1573,13 @@ const DEFAULT_RETRY = {
1377
1573
  "timeout"
1378
1574
  ]
1379
1575
  };
1576
+ /**
1577
+ * Parse an HTTP `Retry-After` header value into a millisecond delay.
1578
+ *
1579
+ * Accepts both forms the header allows: a plain integer or decimal number of
1580
+ * seconds, and an HTTP-date. Returns `undefined` for anything else (missing,
1581
+ * blank, or unparseable).
1582
+ */
1380
1583
  function parse_retry_after(value) {
1381
1584
  if (value === null || value === void 0) return void 0;
1382
1585
  const trimmed = value.trim();
@@ -1386,11 +1589,25 @@ function parse_retry_after(value) {
1386
1589
  if (Number.isNaN(parsed)) return void 0;
1387
1590
  return Math.max(0, parsed - Date.now());
1388
1591
  }
1592
+ /**
1593
+ * Compute the delay before the next retry attempt.
1594
+ *
1595
+ * Exponential backoff (`initial_delay_ms * 2^attempt`) plus up to one
1596
+ * `initial_delay_ms` of random jitter, capped at `max_delay_ms`. The jitter
1597
+ * spreads retries from concurrent callers apart so they don't all retry in
1598
+ * lockstep.
1599
+ */
1389
1600
  function compute_backoff(policy, attempt) {
1390
1601
  const base = policy.initial_delay_ms * 2 ** attempt;
1391
1602
  const jitter = Math.random() * policy.initial_delay_ms;
1392
1603
  return Math.min(base + jitter, policy.max_delay_ms);
1393
1604
  }
1605
+ /**
1606
+ * Wait `ms` milliseconds, or reject immediately with `aborted_error` if
1607
+ * `abort` fires first.
1608
+ *
1609
+ * A zero or negative `ms` resolves synchronously without arming a timer.
1610
+ */
1394
1611
  function wait_ms(ms, abort) {
1395
1612
  return new Promise((resolve, reject) => {
1396
1613
  if (ms <= 0) {
@@ -1412,6 +1629,9 @@ function wait_ms(ms, abort) {
1412
1629
  abort?.addEventListener("abort", on_abort, { once: true });
1413
1630
  });
1414
1631
  }
1632
+ /**
1633
+ * Check whether `policy` allows retrying a failure of the given `kind`.
1634
+ */
1415
1635
  function is_retryable(kind, policy) {
1416
1636
  return policy.retry_on.includes(kind);
1417
1637
  }
@@ -1419,8 +1639,10 @@ function is_retryable(kind, policy) {
1419
1639
  * Retry `fn` under `policy`. `fn` must throw a RetryableError-shaped object to
1420
1640
  * trigger retry; any other thrown value short-circuits as a permanent failure.
1421
1641
  *
1422
- * Returns the value from the last successful fn() call. On exhaustion, throws
1423
- * rate_limit_error (for 429s) or provider_error (for 5xx/network/timeout).
1642
+ * An aborted `abort` signal interrupts a pending backoff wait and throws
1643
+ * `aborted_error`. Returns the value from the last successful `fn()` call. On
1644
+ * exhaustion, throws `rate_limit_error` (for 429s) or `provider_error` (for
1645
+ * 5xx/network/timeout).
1424
1646
  */
1425
1647
  async function retry_with_policy(fn, policy = DEFAULT_RETRY, abort) {
1426
1648
  let attempt = 0;
@@ -1458,14 +1680,28 @@ async function retry_with_policy(fn, policy = DEFAULT_RETRY, abort) {
1458
1680
  }
1459
1681
  }
1460
1682
  }
1683
+ /**
1684
+ * Read `key` off `err` and return it only if the value is a string.
1685
+ */
1461
1686
  function read_string(err, key) {
1462
1687
  const value = Reflect.get(err, key);
1463
1688
  return typeof value === "string" ? value : void 0;
1464
1689
  }
1690
+ /**
1691
+ * Read `key` off `err` and return it only if the value is a number.
1692
+ */
1465
1693
  function read_number$1(err, key) {
1466
1694
  const value = Reflect.get(err, key);
1467
1695
  return typeof value === "number" ? value : void 0;
1468
1696
  }
1697
+ /**
1698
+ * Classify a thrown value into a `RetryableError`, or `undefined` if it
1699
+ * does not carry one of the recognized retryable `kind`s.
1700
+ *
1701
+ * Providers throw plain objects tagged with `kind` (set by
1702
+ * `classify_provider_error` in generate.ts); this reads that shape back out
1703
+ * field by field rather than trusting it wholesale.
1704
+ */
1469
1705
  function classify_retryable(err) {
1470
1706
  if (err === null || typeof err !== "object") return void 0;
1471
1707
  const kind = read_string(err, "kind");
@@ -1509,6 +1745,13 @@ function resolve_transport(init, provider) {
1509
1745
  if (raw === "native") return "native";
1510
1746
  throw new engine_config_error(`${provider} provider: transport must be 'ai_sdk' or 'native', got ${JSON.stringify(raw)}`, provider);
1511
1747
  }
1748
+ /**
1749
+ * Map raw provider usage to UsageTotals, the mapper most adapters share.
1750
+ *
1751
+ * Missing usage zeroes the totals. Optional fields (reasoning and cache
1752
+ * tokens) are set only when the raw payload carries them, reading the
1753
+ * flattened field first and the AI SDK's *_details container second.
1754
+ */
1512
1755
  function default_normalize_usage(raw) {
1513
1756
  if (raw === void 0) return {
1514
1757
  input_tokens: 0,
@@ -1526,6 +1769,11 @@ function default_normalize_usage(raw) {
1526
1769
  else if (typeof raw.input_token_details?.cache_creation_input_tokens === "number") totals.cache_write_tokens = raw.input_token_details.cache_creation_input_tokens;
1527
1770
  return totals;
1528
1771
  }
1772
+ /**
1773
+ * Dynamically import an optional peer dependency, rethrowing an import
1774
+ * failure as an error that names the package and the install command so a
1775
+ * missing peer is diagnosable from the message alone.
1776
+ */
1529
1777
  async function load_optional_peer(specifier) {
1530
1778
  let mod;
1531
1779
  try {
@@ -1545,9 +1793,9 @@ async function load_optional_peer(specifier) {
1545
1793
  * wire (any chunk boundary, including mid-line) and returns the data payloads
1546
1794
  * of every event completed by that chunk; flush() drains an event left open
1547
1795
  * when the stream ends without a trailing blank line. Only `data:` fields
1548
- * matter to the streams fascicle consumes — the Messages API repeats the
1796
+ * matter to the streams fascicle consumes (the Messages API repeats the
1549
1797
  * event type inside the JSON payload and the Chat Completions stream sends
1550
- * nothing but data frames — so `event:`/`id:`/`retry:` fields and `:`
1798
+ * nothing but data frames), so `event:`/`id:`/`retry:` fields and `:`
1551
1799
  * comments are dropped. Multi-line data joins with '\n' per the SSE spec.
1552
1800
  */
1553
1801
  function create_sse_decoder() {
@@ -1595,27 +1843,27 @@ function create_sse_decoder() {
1595
1843
  //#endregion
1596
1844
  //#region src/engine/providers/anthropic_native.ts
1597
1845
  /**
1598
- * Native Anthropic provider adapter (depth-1 raw HTTP).
1846
+ * Native Anthropic provider adapter (raw HTTP).
1599
1847
  *
1600
1848
  * Talks to the Messages API directly over global fetch with zero `ai` /
1601
- * `@ai-sdk/*` in its module graph (D4). It owns request/response mapping
1602
- * only: generate.ts wraps invoke_turn in retry + classification + abort
1603
- * (D5), so failures are thrown in shapes the shared classify_provider_error
1604
- * already understands (`status` + `responseHeaders` for HTTP transients,
1849
+ * `@ai-sdk/*` in its module graph. It owns request/response mapping only:
1850
+ * generate.ts wraps invoke_turn in retry + classification + abort, so
1851
+ * failures are thrown in shapes the shared classify_provider_error already
1852
+ * understands (`status` + `responseHeaders` for HTTP transients,
1605
1853
  * `kind: 'network'` for transport failures) instead of being re-classified
1606
1854
  * or retried here.
1607
1855
  *
1608
1856
  * Selected via `transport: 'native'` on the anthropic provider init. The
1609
1857
  * adapter name stays 'anthropic' so DEFAULT_PRICING keys and UsageTotals
1610
- * fields keep working across transports (C6). Schema requests ride the
1611
- * engine's prompt + parse + repair loop (D6), so `TurnRequest.schema` is
1612
- * intentionally unread. Streaming hand-rolls the SSE parse; the aggregator
1613
- * rebuilds the non-stream payload shape and feeds it through the same
1858
+ * fields keep working across transports. Schema requests ride the engine's
1859
+ * prompt + parse + repair loop, so `TurnRequest.schema` is intentionally
1860
+ * unread. Streaming hand-rolls the SSE parse; the aggregator rebuilds the
1861
+ * non-stream payload shape and feeds it through the same
1614
1862
  * parse_messages_response, so streamed and non-streamed results are equal by
1615
- * construction (C4) rather than by parallel code paths.
1863
+ * construction rather than by parallel code paths.
1616
1864
  */
1617
1865
  /**
1618
- * Effort → extended-thinking budget tokens per spec §6.3. Lives here (not in
1866
+ * Effort level to extended-thinking budget tokens. Lives here (not in
1619
1867
  * anthropic.ts) because both transports map effort from this table and the
1620
1868
  * ai_sdk factory already imports this module for transport dispatch; the
1621
1869
  * reverse import would be a cycle.
@@ -1641,6 +1889,11 @@ const DEFAULT_BASE_URL$2 = "https://api.anthropic.com/v1";
1641
1889
  * rides on top of the thinking budget rather than being swallowed by it.
1642
1890
  */
1643
1891
  const DEFAULT_MAX_TOKENS = 4096;
1892
+ /**
1893
+ * Map user message content to Messages-API text blocks, dropping empty text
1894
+ * (the API rejects empty blocks). Image parts throw a capability error: they
1895
+ * are not mapped on this transport.
1896
+ */
1644
1897
  function to_user_blocks(content) {
1645
1898
  if (typeof content === "string") return content.trim().length > 0 ? [{
1646
1899
  type: "text",
@@ -1656,6 +1909,10 @@ function to_user_blocks(content) {
1656
1909
  }
1657
1910
  return blocks;
1658
1911
  }
1912
+ /**
1913
+ * Map assistant message content to Messages-API blocks: text parts become
1914
+ * text blocks (empties dropped), tool-call parts become tool_use blocks.
1915
+ */
1659
1916
  function to_assistant_blocks(content) {
1660
1917
  if (typeof content === "string") return content.trim().length > 0 ? [{
1661
1918
  type: "text",
@@ -1721,6 +1978,10 @@ function to_anthropic_messages(messages) {
1721
1978
  messages: out
1722
1979
  };
1723
1980
  }
1981
+ /**
1982
+ * Map fascicle tool definitions to the Messages-API tool shape, converting
1983
+ * each zod input schema to JSON Schema.
1984
+ */
1724
1985
  function to_anthropic_tools(tools) {
1725
1986
  return tools.map((tool) => ({
1726
1987
  name: tool.name,
@@ -1728,6 +1989,11 @@ function to_anthropic_tools(tools) {
1728
1989
  input_schema: z.toJSONSchema(tool.input_schema)
1729
1990
  }));
1730
1991
  }
1992
+ /**
1993
+ * Build the Messages-API request body for one turn: mapped messages and
1994
+ * tools, the effort-derived thinking block, the required max_tokens default,
1995
+ * and the `provider_options.anthropic` wire passthrough merged last.
1996
+ */
1731
1997
  function build_messages_body(req) {
1732
1998
  const { system: hoisted_system, messages } = to_anthropic_messages(req.messages);
1733
1999
  const system_parts = [req.system, hoisted_system].filter((s) => typeof s === "string" && s.length > 0);
@@ -1755,6 +2021,9 @@ function build_messages_body(req) {
1755
2021
  ...passthrough
1756
2022
  };
1757
2023
  }
2024
+ /**
2025
+ * Map the Messages-API stop_reason to the engine's FinishReason.
2026
+ */
1758
2027
  function map_anthropic_stop_reason(raw) {
1759
2028
  switch (raw) {
1760
2029
  case "tool_use": return "tool_calls";
@@ -1765,6 +2034,8 @@ function map_anthropic_stop_reason(raw) {
1765
2034
  }
1766
2035
  }
1767
2036
  /**
2037
+ * Map the Messages-API usage object to UsageTotals.
2038
+ *
1768
2039
  * The API reports input_tokens EXCLUSIVE of cache reads and writes, while
1769
2040
  * compute_cost subtracts both back out of UsageTotals.input_tokens to price
1770
2041
  * the fresh remainder. So the inclusive total is the sum of all three; a
@@ -1789,6 +2060,11 @@ function map_anthropic_usage(raw) {
1789
2060
  if (cache_write !== void 0) totals.cache_write_tokens = cache_write;
1790
2061
  return totals;
1791
2062
  }
2063
+ /**
2064
+ * Parse a non-stream Messages-API response payload into a TurnResult. The
2065
+ * stream aggregator rebuilds this same payload shape and feeds it here too,
2066
+ * so both paths share one parser.
2067
+ */
1792
2068
  function parse_messages_response(payload) {
1793
2069
  if (payload === null || typeof payload !== "object") throw new provider_error("anthropic native: response payload is not a JSON object");
1794
2070
  const content = Reflect.get(payload, "content");
@@ -1823,7 +2099,7 @@ function parse_messages_response(payload) {
1823
2099
  * overloaded_error is the SSE analog of a 529, api_error of a 500, and
1824
2100
  * rate_limit_error of a 429, so classify_provider_error sees the transients
1825
2101
  * it already retries. Anything else is a permanent provider_error. Whether a
1826
- * retry actually happens stays retry_turn's call — once chunks have streamed
2102
+ * retry actually happens stays retry_turn's call: once chunks have streamed
1827
2103
  * it refuses, exactly as on the ai_sdk path.
1828
2104
  */
1829
2105
  function stream_event_error(event) {
@@ -1844,6 +2120,10 @@ function stream_event_error(event) {
1844
2120
  if (status !== void 0) return Object.assign(new Error(detail), { status });
1845
2121
  return new provider_error(detail);
1846
2122
  }
2123
+ /**
2124
+ * Read the `index` field every stream event carries, identifying which
2125
+ * content block (text or tool_use) the event applies to.
2126
+ */
1847
2127
  function read_block_index(event) {
1848
2128
  const index = Reflect.get(event, "index");
1849
2129
  if (typeof index !== "number") throw new provider_error("anthropic native: stream event is missing its block index");
@@ -1856,7 +2136,7 @@ function read_block_index(event) {
1856
2136
  * JSON text (input_json_delta) held per open block and parsed at
1857
2137
  * content_block_stop. complete() feeds the synthetic payload through
1858
2138
  * parse_messages_response, which is what makes the streamed TurnResult equal
1859
- * the non-streamed one by construction (C4). A stream that ends without
2139
+ * the non-streamed one by construction. A stream that ends without
1860
2140
  * message_stop is truncated output, so complete() fails loud instead of
1861
2141
  * returning a partial turn.
1862
2142
  */
@@ -2117,6 +2397,11 @@ const SUPPORTED$10 = /* @__PURE__ */ new Set([
2117
2397
  "streaming",
2118
2398
  "reasoning"
2119
2399
  ]);
2400
+ /**
2401
+ * Build the native Anthropic adapter: validates the required api_key,
2402
+ * normalizes base_url, and wires invoke_turn to POST /messages directly
2403
+ * (streamed or not) through the mappers above.
2404
+ */
2120
2405
  const create_anthropic_native_adapter = (init) => {
2121
2406
  const api_key = typeof init.api_key === "string" ? init.api_key : "";
2122
2407
  if (api_key.length === 0) throw new engine_config_error("anthropic provider requires a non-empty api_key", "anthropic");
@@ -2149,6 +2434,12 @@ const create_anthropic_native_adapter = (init) => {
2149
2434
  };
2150
2435
  //#endregion
2151
2436
  //#region src/engine/providers/anthropic.ts
2437
+ /**
2438
+ * Map an effort level to Anthropic's extended-thinking provider options.
2439
+ *
2440
+ * `none` (a zero budget) sends no thinking config at all rather than an
2441
+ * explicit "disabled" value, so non-reasoning models see a plain request.
2442
+ */
2152
2443
  function translate_anthropic_effort(effort) {
2153
2444
  const budget = ANTHROPIC_THINKING_BUDGETS[effort];
2154
2445
  if (effort === "none" || budget === 0) return {
@@ -2163,6 +2454,10 @@ function translate_anthropic_effort(effort) {
2163
2454
  effort_ignored: false
2164
2455
  };
2165
2456
  }
2457
+ /**
2458
+ * Normalize Anthropic usage via the shared default mapper; the AI SDK already
2459
+ * reports cache and reasoning tokens in the fields the default reads.
2460
+ */
2166
2461
  function normalize_anthropic_usage(raw) {
2167
2462
  return default_normalize_usage(raw);
2168
2463
  }
@@ -2174,10 +2469,19 @@ const SUPPORTED$9 = /* @__PURE__ */ new Set([
2174
2469
  "image_input",
2175
2470
  "reasoning"
2176
2471
  ]);
2472
+ /**
2473
+ * Build the Anthropic adapter, dispatching on `init.transport`: 'native' for
2474
+ * the raw-HTTP Messages API adapter, otherwise the AI SDK wrapper.
2475
+ */
2177
2476
  const create_anthropic_adapter = (init) => {
2178
2477
  if (resolve_transport(init, "anthropic") === "native") return create_anthropic_native_adapter(init);
2179
2478
  return create_anthropic_ai_sdk_adapter(init);
2180
2479
  };
2480
+ /**
2481
+ * Build the AI SDK-backed Anthropic adapter. Requires a non-empty api_key at
2482
+ * construction; @ai-sdk/anthropic itself loads lazily on first build_model so
2483
+ * the peer is only required when a model is actually used.
2484
+ */
2181
2485
  const create_anthropic_ai_sdk_adapter = (init) => {
2182
2486
  const api_key = typeof init.api_key === "string" ? init.api_key : "";
2183
2487
  if (api_key.length === 0) throw new engine_config_error("anthropic provider requires a non-empty api_key", "anthropic");
@@ -2199,16 +2503,16 @@ const create_anthropic_ai_sdk_adapter = (init) => {
2199
2503
  //#endregion
2200
2504
  //#region src/engine/providers/openai_compatible_native.ts
2201
2505
  /**
2202
- * OpenAI-compatible native core (depth-1 raw HTTP).
2506
+ * OpenAI-compatible native core: one `chat/completions` implementation
2507
+ * talking raw HTTP, shared by every OpenAI-compatible provider.
2203
2508
  *
2204
- * One `chat/completions` implementation parameterized by a dialect config
2205
- * (D1): base_url, auth strategy, extra headers, stream-usage behavior,
2206
- * token-limit field name, and usage tolerance (D10). The `openai`,
2207
- * `openrouter`, and `lmstudio` factories each build a dialect and share this
2208
- * core; pointing base_url at any compat server (including Ollama's /v1)
2209
- * rides the same path.
2509
+ * Parameterized by a dialect config: base_url, auth strategy, extra headers,
2510
+ * stream-usage behavior, token-limit field name, and usage tolerance. The
2511
+ * `openai`, `openrouter`, and `lmstudio` factories each build a dialect and
2512
+ * share this core; pointing base_url at any compat server (including
2513
+ * Ollama's /v1) rides the same path.
2210
2514
  *
2211
- * Zero `ai` / `@ai-sdk/*` in the module graph (C3). The adapter owns
2515
+ * This module imports nothing from `ai` or `@ai-sdk/*`. The adapter owns
2212
2516
  * request/response mapping only: generate.ts wraps invoke_turn in retry +
2213
2517
  * classification + abort, so failures are thrown in shapes the shared
2214
2518
  * classify_provider_error already understands (`status` + `responseHeaders`
@@ -2218,14 +2522,14 @@ const create_anthropic_ai_sdk_adapter = (init) => {
2218
2522
  * the SSE parse (`data:` lines, the literal `[DONE]` terminator, index-keyed
2219
2523
  * tool_call delta accumulation); the aggregator rebuilds the non-stream
2220
2524
  * payload shape and feeds it through the same parse_chat_completion, so
2221
- * streamed and non-streamed results are equal by construction (C4) rather
2222
- * than by parallel code paths.
2525
+ * streamed and non-streamed results are equal by construction rather than by
2526
+ * parallel code paths.
2223
2527
  */
2224
2528
  /**
2225
- * Effort map per Appendix A4: the wire enum is `low | medium | high` only, so
2226
- * `xhigh` and `max` clamp to `high`, the same clamp as the ai_sdk transport's
2227
- * `reasoningEffort`. `none` omits the field entirely. Non-reasoning models
2228
- * ignore the field server-side; the adapter does not model-sniff.
2529
+ * The wire enum is `low | medium | high` only, so `xhigh` and `max` clamp to
2530
+ * `high`, the same clamp as the ai_sdk transport's `reasoningEffort`. `none`
2531
+ * omits the field entirely. Non-reasoning models ignore the field
2532
+ * server-side; the adapter does not model-sniff.
2229
2533
  */
2230
2534
  const OPENAI_COMPATIBLE_REASONING_EFFORT = {
2231
2535
  low: "low",
@@ -2234,6 +2538,11 @@ const OPENAI_COMPATIBLE_REASONING_EFFORT = {
2234
2538
  xhigh: "high",
2235
2539
  max: "high"
2236
2540
  };
2541
+ /**
2542
+ * Map user message content to this wire's shape (a string, or an array of
2543
+ * text parts). Image parts throw a capability error: they are not mapped on
2544
+ * the native transport.
2545
+ */
2237
2546
  function to_user_content$1(content, provider) {
2238
2547
  if (typeof content === "string") return content;
2239
2548
  const parts = [];
@@ -2246,6 +2555,11 @@ function to_user_content$1(content, provider) {
2246
2555
  }
2247
2556
  return parts.length > 0 ? parts : "";
2248
2557
  }
2558
+ /**
2559
+ * Map assistant message content to Chat Completions shape: text parts join
2560
+ * into `content`, and tool-call parts become `tool_calls` entries with
2561
+ * JSON-stringified arguments.
2562
+ */
2249
2563
  function to_assistant_message$1(content) {
2250
2564
  if (typeof content === "string") return {
2251
2565
  role: "assistant",
@@ -2304,6 +2618,10 @@ function to_chat_messages(messages, provider) {
2304
2618
  }
2305
2619
  return out;
2306
2620
  }
2621
+ /**
2622
+ * Map fascicle Tool[] to the Chat Completions function-tool shape,
2623
+ * converting each zod input schema to JSON Schema.
2624
+ */
2307
2625
  function to_chat_tools(tools) {
2308
2626
  return tools.map((tool) => ({
2309
2627
  type: "function",
@@ -2314,6 +2632,12 @@ function to_chat_tools(tools) {
2314
2632
  }
2315
2633
  }));
2316
2634
  }
2635
+ /**
2636
+ * Build the Chat Completions request body for one turn: mapped messages and
2637
+ * tools, the token-limit field named per dialect, sampling params, the
2638
+ * effort-derived reasoning_effort, and the dialect's
2639
+ * `provider_options.<name>` wire passthrough merged last.
2640
+ */
2317
2641
  function build_chat_completions_body(req, dialect) {
2318
2642
  const messages = [];
2319
2643
  if (req.system !== void 0 && req.system.length > 0) messages.push({
@@ -2340,6 +2664,9 @@ function build_chat_completions_body(req, dialect) {
2340
2664
  ...passthrough
2341
2665
  };
2342
2666
  }
2667
+ /**
2668
+ * Map the Chat Completions finish_reason to the engine's FinishReason.
2669
+ */
2343
2670
  function map_chat_finish_reason(raw) {
2344
2671
  switch (raw) {
2345
2672
  case "tool_calls": return "tool_calls";
@@ -2349,17 +2676,21 @@ function map_chat_finish_reason(raw) {
2349
2676
  }
2350
2677
  }
2351
2678
  /**
2352
- * Usage map per Appendix A3. prompt_tokens is already INCLUSIVE of cached
2353
- * tokens on this API, unlike Anthropic's exclusive accounting, so a straight
2354
- * copy is correct; compute_cost subtracts the cached portion back out. There
2355
- * is no cache-write concept on this wire. A missing usage object throws under
2356
- * a strict dialect (a hosted API omitting usage is a broken response) and
2357
- * zeroes under a tolerant one (D10).
2679
+ * Read a numeric field from a usage object, or undefined if absent or not a
2680
+ * number.
2358
2681
  */
2359
2682
  function read_number(source, key) {
2360
2683
  const value = Reflect.get(source, key);
2361
2684
  return typeof value === "number" ? value : void 0;
2362
2685
  }
2686
+ /**
2687
+ * Map the Chat Completions usage object to UsageTotals. prompt_tokens is
2688
+ * already INCLUSIVE of cached tokens on this API, unlike Anthropic's
2689
+ * exclusive accounting, so a straight copy is correct; compute_cost
2690
+ * subtracts the cached portion back out. There is no cache-write concept on
2691
+ * this wire. A missing usage object throws under a strict dialect (a hosted
2692
+ * API omitting usage is a broken response) and zeroes under a tolerant one.
2693
+ */
2363
2694
  function map_chat_usage(raw, dialect) {
2364
2695
  if (raw === null || typeof raw !== "object") {
2365
2696
  if (dialect.tolerant_usage) return {
@@ -2384,6 +2715,11 @@ function map_chat_usage(raw, dialect) {
2384
2715
  }
2385
2716
  return totals;
2386
2717
  }
2718
+ /**
2719
+ * Parse one Chat Completions tool_calls entry into the engine's tool-call
2720
+ * shape, throwing a provider_error if the entry is missing id, function
2721
+ * name, or valid JSON arguments.
2722
+ */
2387
2723
  function parse_tool_call(raw, provider) {
2388
2724
  if (raw === null || typeof raw !== "object") throw new provider_error(`${provider} native: malformed tool_calls entry in response`);
2389
2725
  const id = Reflect.get(raw, "id");
@@ -2405,9 +2741,9 @@ function parse_tool_call(raw, provider) {
2405
2741
  };
2406
2742
  }
2407
2743
  /**
2408
- * The one response parser every path feeds (C4): non-stream parses the
2409
- * payload directly, and the streaming aggregator (next step) rebuilds this
2410
- * same payload shape from deltas before calling it.
2744
+ * The one response parser every path feeds: non-stream parses the payload
2745
+ * directly, and the streaming aggregator (next step) rebuilds this same
2746
+ * payload shape from deltas before calling it.
2411
2747
  */
2412
2748
  function parse_chat_completion(payload, dialect) {
2413
2749
  if (payload === null || typeof payload !== "object") throw new provider_error(`${dialect.name} native: response payload is not a JSON object`);
@@ -2432,14 +2768,14 @@ function parse_chat_completion(payload, dialect) {
2432
2768
  * StreamChunks as they arrive and rebuilding the non-stream payload as it
2433
2769
  * goes: `delta.content` accumulates into the message text, and
2434
2770
  * `delta.tool_calls[]` entries accumulate `function.arguments` string deltas
2435
- * keyed by their `index` field (A5). A tool call closes — parsed input
2436
- * dispatched — when the choice's finish_reason frame arrives, or at `[DONE]`
2437
- * for servers that never send one. Usage rides the final pre-DONE frame
2771
+ * keyed by their `index` field. A tool call closes (parsed input dispatched)
2772
+ * when the choice's finish_reason frame arrives, or at `[DONE]` for servers
2773
+ * that never send one. Usage rides the final pre-DONE frame
2438
2774
  * (stream_options.include_usage); a stream that ends without `[DONE]` is
2439
2775
  * truncated output, so complete() fails loud instead of returning a partial
2440
2776
  * turn. complete() feeds the synthetic payload through parse_chat_completion,
2441
2777
  * which is what makes the streamed TurnResult equal the non-streamed one by
2442
- * construction (C4).
2778
+ * construction.
2443
2779
  */
2444
2780
  function create_chat_stream_aggregator(dialect, step_index, dispatch) {
2445
2781
  let text = "";
@@ -2675,6 +3011,12 @@ const SUPPORTED$8 = /* @__PURE__ */ new Set([
2675
3011
  "streaming",
2676
3012
  "reasoning"
2677
3013
  ]);
3014
+ /**
3015
+ * Build a native OpenAI-compatible adapter from a dialect: validates the
3016
+ * dialect's api_key when auth is `bearer`, normalizes base_url, and wires
3017
+ * invoke_turn to POST /chat/completions directly (streamed or not) through
3018
+ * the mappers above.
3019
+ */
2678
3020
  const create_openai_compatible_adapter = (dialect) => {
2679
3021
  if (dialect.auth.kind === "bearer" && dialect.auth.api_key.length === 0) throw new engine_config_error(`${dialect.name} provider requires a non-empty api_key`, dialect.name);
2680
3022
  const base_url = dialect.base_url.replace(/\/+$/, "");
@@ -2714,6 +3056,9 @@ const OPENAI_REASONING_EFFORT = {
2714
3056
  xhigh: "high",
2715
3057
  max: "high"
2716
3058
  };
3059
+ /**
3060
+ * Map an EffortLevel to OpenAI's `reasoningEffort` provider option.
3061
+ */
2717
3062
  function translate_openai_effort(effort) {
2718
3063
  if (effort === "none") return {
2719
3064
  provider_options: {},
@@ -2724,6 +3069,9 @@ function translate_openai_effort(effort) {
2724
3069
  effort_ignored: false
2725
3070
  };
2726
3071
  }
3072
+ /**
3073
+ * Normalize OpenAI's raw usage payload into UsageTotals.
3074
+ */
2727
3075
  function normalize_openai_usage(raw) {
2728
3076
  return default_normalize_usage(raw);
2729
3077
  }
@@ -2741,15 +3089,19 @@ const SUPPORTED$7 = /* @__PURE__ */ new Set([
2741
3089
  * pointing at the same place when the transport flips to native.
2742
3090
  */
2743
3091
  const DEFAULT_BASE_URL$1 = "https://api.openai.com/v1";
3092
+ /**
3093
+ * Build the OpenAI adapter, picking the native or ai_sdk backend per the
3094
+ * resolved `transport`.
3095
+ */
2744
3096
  const create_openai_adapter = (init) => {
2745
3097
  if (resolve_transport(init, "openai") === "native") return create_openai_native_adapter(init);
2746
3098
  return create_openai_ai_sdk_adapter(init);
2747
3099
  };
2748
3100
  /**
2749
- * Build the openai dialect (Appendix A1) and hand it to the shared
2750
- * OpenAI-compatible core: Bearer auth, an optional OpenAI-Organization header,
2751
- * the `max_completion_tokens` token-limit field, and strict usage (a hosted
2752
- * API omitting usage is a broken response, not a local-runtime quirk). The
3101
+ * Build the openai dialect and hand it to the shared OpenAI-compatible core:
3102
+ * Bearer auth, an optional OpenAI-Organization header, the
3103
+ * `max_completion_tokens` token-limit field, and strict usage (a hosted API
3104
+ * omitting usage is a broken response, not a local-runtime quirk). The
2753
3105
  * empty-api_key guard rides on the core, which throws the same
2754
3106
  * `openai provider requires a non-empty api_key` engine_config_error.
2755
3107
  */
@@ -2770,6 +3122,10 @@ const create_openai_native_adapter = (init) => {
2770
3122
  ...organization !== void 0 ? { extra_headers: { "OpenAI-Organization": organization } } : {}
2771
3123
  });
2772
3124
  };
3125
+ /**
3126
+ * Build the OpenAI ai_sdk adapter: validates the required api_key and lazily
3127
+ * loads @ai-sdk/openai to build models.
3128
+ */
2773
3129
  const create_openai_ai_sdk_adapter = (init) => {
2774
3130
  const api_key = typeof init.api_key === "string" ? init.api_key : "";
2775
3131
  if (api_key.length === 0) throw new engine_config_error("openai provider requires a non-empty api_key", "openai");
@@ -2799,6 +3155,10 @@ const GOOGLE_THINKING_BUDGET = {
2799
3155
  xhigh: 32768,
2800
3156
  max: 32768
2801
3157
  };
3158
+ /**
3159
+ * Map an EffortLevel to Google's `thinkingConfig.thinkingBudget` provider
3160
+ * option.
3161
+ */
2802
3162
  function translate_google_effort(effort) {
2803
3163
  if (effort === "none") return {
2804
3164
  provider_options: {},
@@ -2809,6 +3169,9 @@ function translate_google_effort(effort) {
2809
3169
  effort_ignored: false
2810
3170
  };
2811
3171
  }
3172
+ /**
3173
+ * Normalize Google's raw usage payload into UsageTotals.
3174
+ */
2812
3175
  function normalize_google_usage(raw) {
2813
3176
  return default_normalize_usage(raw);
2814
3177
  }
@@ -2820,6 +3183,10 @@ const SUPPORTED$6 = /* @__PURE__ */ new Set([
2820
3183
  "image_input",
2821
3184
  "reasoning"
2822
3185
  ]);
3186
+ /**
3187
+ * Build the Google ai_sdk adapter: validates the required api_key and lazily
3188
+ * loads @ai-sdk/google to build models.
3189
+ */
2823
3190
  const create_google_adapter = (init) => {
2824
3191
  const api_key = typeof init.api_key === "string" ? init.api_key : "";
2825
3192
  if (api_key.length === 0) throw new engine_config_error("google provider requires a non-empty api_key", "google");
@@ -2840,6 +3207,11 @@ const create_google_adapter = (init) => {
2840
3207
  };
2841
3208
  //#endregion
2842
3209
  //#region src/engine/providers/ollama_native.ts
3210
+ /**
3211
+ * Map user message content to a plain string, the shape this wire expects
3212
+ * (no part-array support). Image parts throw a capability error: they are
3213
+ * not mapped on the native transport.
3214
+ */
2843
3215
  function to_user_content(content) {
2844
3216
  if (typeof content === "string") return content;
2845
3217
  const parts = [];
@@ -2849,6 +3221,11 @@ function to_user_content(content) {
2849
3221
  }
2850
3222
  return parts.join("\n");
2851
3223
  }
3224
+ /**
3225
+ * Map assistant message content to this wire's message shape: text parts
3226
+ * join into `content`, and tool-call parts become `tool_calls` entries with
3227
+ * structured (not JSON-string) arguments.
3228
+ */
2852
3229
  function to_assistant_message(content) {
2853
3230
  if (typeof content === "string") return {
2854
3231
  role: "assistant",
@@ -2901,6 +3278,11 @@ function to_ollama_messages(messages) {
2901
3278
  }
2902
3279
  return out;
2903
3280
  }
3281
+ /**
3282
+ * Build the /api/chat request body for one turn: mapped messages and tools,
3283
+ * sampling params under the `options` bag, and the `provider_options.ollama`
3284
+ * wire passthrough merged last.
3285
+ */
2904
3286
  function build_ollama_chat_body(req) {
2905
3287
  const messages = [];
2906
3288
  if (req.system !== void 0 && req.system.length > 0) messages.push({
@@ -2926,19 +3308,22 @@ function build_ollama_chat_body(req) {
2926
3308
  };
2927
3309
  }
2928
3310
  /**
2929
- * Appendix A2, Ollama row: the presence of tool calls wins (the wire reports
2930
- * done_reason 'stop' on a tool-call turn), then `length`; everything else —
2931
- * 'stop', 'load', absent — means the model stopped on its own.
3311
+ * Map the daemon's done_reason, plus whether the turn produced tool calls,
3312
+ * to the engine's FinishReason. The presence of tool calls wins, since the
3313
+ * wire reports done_reason 'stop' on a tool-call turn too, then `length`;
3314
+ * everything else ('stop', 'load', or absent) means the model stopped on its
3315
+ * own.
2932
3316
  */
2933
3317
  function map_ollama_finish_reason(raw, has_tool_calls) {
2934
3318
  if (has_tool_calls) return "tool_calls";
2935
3319
  return raw === "length" ? "length" : "stop";
2936
3320
  }
2937
3321
  /**
2938
- * Appendix A3, Ollama row: prompt_eval_count → input_tokens, eval_count →
2939
- * output_tokens; no cache or reasoning fields exist on this wire. Counts are
2940
- * always tolerant (D10): a local daemon that omits them (or a mid-stream
2941
- * frame, which never carries them) zeroes the totals, never throws.
3322
+ * Map the daemon's usage fields to UsageTotals: prompt_eval_count becomes
3323
+ * input_tokens, eval_count becomes output_tokens; no cache or reasoning
3324
+ * fields exist on this wire. Counts are always tolerant: a local daemon that
3325
+ * omits them (or a mid-stream frame, which never carries them) zeroes the
3326
+ * totals instead of throwing.
2942
3327
  */
2943
3328
  function map_ollama_usage(payload) {
2944
3329
  if (payload === null || typeof payload !== "object") return {
@@ -2954,8 +3339,8 @@ function map_ollama_usage(payload) {
2954
3339
  }
2955
3340
  /**
2956
3341
  * This wire sends no tool-call id, so one is synthesized from the step index
2957
- * and the call's ordinal within the turn — deterministic, so the streamed and
2958
- * non-streamed parses of the same turn agree (C4), and unique across steps so
3342
+ * and the call's ordinal within the turn: deterministic, so the streamed and
3343
+ * non-streamed parses of the same turn agree, and unique across steps so
2959
3344
  * transcript tool results stay unambiguous. A wire id is preferred if a
2960
3345
  * future daemon version starts sending one.
2961
3346
  */
@@ -2982,9 +3367,9 @@ function parse_ollama_tool_call(raw, ordinal, step_index) {
2982
3367
  };
2983
3368
  }
2984
3369
  /**
2985
- * The one response parser every path feeds (C4): non-stream parses the
2986
- * payload directly, and the NDJSON aggregator rebuilds this same payload
2987
- * shape from its frames before calling it.
3370
+ * The one response parser every path feeds: non-stream parses the payload
3371
+ * directly, and the NDJSON aggregator rebuilds this same payload shape from
3372
+ * its frames before calling it.
2988
3373
  */
2989
3374
  function parse_ollama_chat(payload, step_index) {
2990
3375
  if (payload === null || typeof payload !== "object") throw new provider_error("ollama native: response payload is not a JSON object");
@@ -3001,15 +3386,19 @@ function parse_ollama_chat(payload, step_index) {
3001
3386
  };
3002
3387
  }
3003
3388
  /**
3004
- * Incremental NDJSON framing: push() takes decoded text at any chunk boundary
3005
- * (including mid-line) and returns the complete lines it finished; flush()
3006
- * drains a final line left open when the stream ends without a trailing
3007
- * newline. Blank lines are dropped; JSON parsing is the aggregator's job.
3389
+ * Append one decoded line to `out`, trimming a trailing `\r` and dropping
3390
+ * blank lines; JSON parsing is the aggregator's job.
3008
3391
  */
3009
3392
  function take_line(raw, out) {
3010
3393
  const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
3011
3394
  if (line.trim().length > 0) out.push(line);
3012
3395
  }
3396
+ /**
3397
+ * Incremental NDJSON framing: push() takes decoded text at any chunk
3398
+ * boundary (including mid-line) and returns the complete lines it finished;
3399
+ * flush() drains a final line left open when the stream ends without a
3400
+ * trailing newline.
3401
+ */
3013
3402
  function create_ndjson_decoder() {
3014
3403
  let buffer = "";
3015
3404
  return {
@@ -3036,14 +3425,14 @@ function create_ndjson_decoder() {
3036
3425
  * Consume /api/chat NDJSON frames, dispatching StreamChunks as they arrive
3037
3426
  * and rebuilding the non-stream payload as it goes: `message.content`
3038
3427
  * accumulates into the turn text, and `message.tool_calls` entries arrive
3039
- * WHOLE per frame — arguments are complete objects on this wire, so each call
3040
- * dispatches tool_call_start then tool_call_end with no input deltas between.
3041
- * The `done: true` frame carries done_reason and the eval counts and closes
3042
- * the turn (step_finish); frames after it are ignored. A stream that ends
3043
- * without one is truncated output, so complete() fails loud instead of
3044
- * returning a partial turn. complete() feeds the synthetic payload through
3045
- * parse_ollama_chat, which is what makes the streamed TurnResult equal the
3046
- * non-streamed one by construction (C4).
3428
+ * whole per frame, since arguments are complete objects on this wire, so
3429
+ * each call dispatches tool_call_start then tool_call_end with no input
3430
+ * deltas between. The `done: true` frame carries done_reason and the eval
3431
+ * counts and closes the turn (step_finish); frames after it are ignored. A
3432
+ * stream that ends without one is truncated output, so complete() fails
3433
+ * loud instead of returning a partial turn. complete() feeds the synthetic
3434
+ * payload through parse_ollama_chat, which is what makes the streamed
3435
+ * TurnResult equal the non-streamed one by construction.
3047
3436
  */
3048
3437
  function create_ollama_stream_aggregator(step_index, dispatch) {
3049
3438
  let text = "";
@@ -3225,6 +3614,11 @@ const SUPPORTED$5 = /* @__PURE__ */ new Set([
3225
3614
  "schema",
3226
3615
  "streaming"
3227
3616
  ]);
3617
+ /**
3618
+ * Build the native Ollama adapter: validates the required base_url and wires
3619
+ * invoke_turn to POST /api/chat directly (streamed or not) through the
3620
+ * mappers above.
3621
+ */
3228
3622
  const create_ollama_native_adapter = (init) => {
3229
3623
  const raw_base_url = typeof init.base_url === "string" ? init.base_url : "";
3230
3624
  if (raw_base_url.length === 0) throw new engine_config_error("ollama provider requires a non-empty base_url", "ollama");
@@ -3253,12 +3647,19 @@ const create_ollama_native_adapter = (init) => {
3253
3647
  };
3254
3648
  //#endregion
3255
3649
  //#region src/engine/providers/ollama.ts
3650
+ /**
3651
+ * Ollama has no reasoning-effort control on this transport, so every
3652
+ * non-`none` level is reported as ignored and no provider option is emitted.
3653
+ */
3256
3654
  function translate_ollama_effort(effort) {
3257
3655
  return {
3258
3656
  provider_options: {},
3259
3657
  effort_ignored: effort !== "none"
3260
3658
  };
3261
3659
  }
3660
+ /**
3661
+ * Normalize Ollama's raw usage payload into UsageTotals.
3662
+ */
3262
3663
  function normalize_ollama_usage(raw) {
3263
3664
  const base = default_normalize_usage(raw);
3264
3665
  delete base.cached_input_tokens;
@@ -3273,10 +3674,18 @@ const SUPPORTED$4 = /* @__PURE__ */ new Set([
3273
3674
  "streaming",
3274
3675
  "structured_output"
3275
3676
  ]);
3677
+ /**
3678
+ * Build the Ollama adapter, picking the native or ai_sdk backend per the
3679
+ * resolved `transport`.
3680
+ */
3276
3681
  const create_ollama_adapter = (init) => {
3277
3682
  if (resolve_transport(init, "ollama") === "native") return create_ollama_native_adapter(init);
3278
3683
  return create_ollama_ai_sdk_adapter(init);
3279
3684
  };
3685
+ /**
3686
+ * Build the Ollama ai_sdk adapter: validates the required base_url and
3687
+ * lazily loads ai-sdk-ollama to build models.
3688
+ */
3280
3689
  const create_ollama_ai_sdk_adapter = (init) => {
3281
3690
  const base_url = typeof init.base_url === "string" ? init.base_url : "";
3282
3691
  if (base_url.length === 0) throw new engine_config_error("ollama provider requires a non-empty base_url", "ollama");
@@ -3293,12 +3702,19 @@ const create_ollama_ai_sdk_adapter = (init) => {
3293
3702
  };
3294
3703
  //#endregion
3295
3704
  //#region src/engine/providers/lmstudio.ts
3705
+ /**
3706
+ * LM Studio has no reasoning-effort control, so every non-`none` level is
3707
+ * reported as ignored and no provider option is emitted.
3708
+ */
3296
3709
  function translate_lmstudio_effort(effort) {
3297
3710
  return {
3298
3711
  provider_options: {},
3299
3712
  effort_ignored: effort !== "none"
3300
3713
  };
3301
3714
  }
3715
+ /**
3716
+ * Normalize LM Studio's raw usage payload into UsageTotals.
3717
+ */
3302
3718
  function normalize_lmstudio_usage(raw) {
3303
3719
  const base = default_normalize_usage(raw);
3304
3720
  delete base.cached_input_tokens;
@@ -3313,15 +3729,19 @@ const SUPPORTED$3 = /* @__PURE__ */ new Set([
3313
3729
  "streaming",
3314
3730
  "structured_output"
3315
3731
  ]);
3732
+ /**
3733
+ * Build the LM Studio adapter, picking the native or ai_sdk backend per the
3734
+ * resolved `transport`.
3735
+ */
3316
3736
  const create_lmstudio_adapter = (init) => {
3317
3737
  if (resolve_transport(init, "lmstudio") === "native") return create_lmstudio_native_adapter(init);
3318
3738
  return create_lmstudio_ai_sdk_adapter(init);
3319
3739
  };
3320
3740
  /**
3321
- * Build the lmstudio dialect (Appendix A1) and hand it to the shared
3322
- * OpenAI-compatible core: no auth, the `max_tokens` token-limit field, and
3323
- * tolerant usage (D10). The base_url guard mirrors the ai_sdk branch; the core
3324
- * has no api_key to check under `auth: { kind: 'none' }`.
3741
+ * Build the lmstudio dialect and hand it to the shared OpenAI-compatible
3742
+ * core: no auth, the `max_tokens` token-limit field, and tolerant usage. The
3743
+ * base_url guard mirrors the ai_sdk branch; the core has no api_key to check
3744
+ * under `auth: { kind: 'none' }`.
3325
3745
  */
3326
3746
  const create_lmstudio_native_adapter = (init) => {
3327
3747
  const base_url = typeof init.base_url === "string" ? init.base_url : "";
@@ -3335,6 +3755,10 @@ const create_lmstudio_native_adapter = (init) => {
3335
3755
  tolerant_usage: true
3336
3756
  });
3337
3757
  };
3758
+ /**
3759
+ * Build the LM Studio ai_sdk adapter: validates the required base_url and
3760
+ * lazily loads @ai-sdk/openai-compatible to build models.
3761
+ */
3338
3762
  const create_lmstudio_ai_sdk_adapter = (init) => {
3339
3763
  const base_url = typeof init.base_url === "string" ? init.base_url : "";
3340
3764
  if (base_url.length === 0) throw new engine_config_error("lmstudio provider requires a non-empty base_url", "lmstudio");
@@ -3355,6 +3779,14 @@ const create_lmstudio_ai_sdk_adapter = (init) => {
3355
3779
  };
3356
3780
  //#endregion
3357
3781
  //#region src/engine/providers/openrouter.ts
3782
+ /**
3783
+ * Map an EffortLevel to OpenRouter's `reasoning.effort` provider option.
3784
+ *
3785
+ * OpenRouter forwards the effort string verbatim to the upstream model.
3786
+ * `low`/`medium`/`high` work everywhere; `xhigh`/`max` flow through but only
3787
+ * the upstream model decides what they mean. Models that don't recognize
3788
+ * the value drop it silently.
3789
+ */
3358
3790
  function translate_openrouter_effort(effort) {
3359
3791
  if (effort === "none") return {
3360
3792
  provider_options: {},
@@ -3365,6 +3797,9 @@ function translate_openrouter_effort(effort) {
3365
3797
  effort_ignored: false
3366
3798
  };
3367
3799
  }
3800
+ /**
3801
+ * Normalize OpenRouter's raw usage payload into UsageTotals.
3802
+ */
3368
3803
  function normalize_openrouter_usage(raw) {
3369
3804
  return default_normalize_usage(raw);
3370
3805
  }
@@ -3382,15 +3817,19 @@ const SUPPORTED$2 = /* @__PURE__ */ new Set([
3382
3817
  * pointing at the same place when the transport flips to native.
3383
3818
  */
3384
3819
  const DEFAULT_BASE_URL = "https://openrouter.ai/api/v1";
3820
+ /**
3821
+ * Build the OpenRouter adapter, picking the native or ai_sdk backend per the
3822
+ * resolved `transport`.
3823
+ */
3385
3824
  const create_openrouter_adapter = (init) => {
3386
3825
  if (resolve_transport(init, "openrouter") === "native") return create_openrouter_native_adapter(init);
3387
3826
  return create_openrouter_ai_sdk_adapter(init);
3388
3827
  };
3389
3828
  /**
3390
- * Build the openrouter dialect (Appendix A1) and hand it to the shared
3391
- * OpenAI-compatible core: Bearer auth, the optional `HTTP-Referer`/`X-Title`
3392
- * attribution headers, the `max_tokens` token-limit field, and strict usage.
3393
- * The empty-api_key guard rides on the core, which throws the same
3829
+ * Build the openrouter dialect and hand it to the shared OpenAI-compatible
3830
+ * core: Bearer auth, the optional `HTTP-Referer`/`X-Title` attribution
3831
+ * headers, the `max_tokens` token-limit field, and strict usage. The
3832
+ * empty-api_key guard rides on the core, which throws the same
3394
3833
  * `openrouter provider requires a non-empty api_key` engine_config_error.
3395
3834
  */
3396
3835
  const create_openrouter_native_adapter = (init) => {
@@ -3414,6 +3853,10 @@ const create_openrouter_native_adapter = (init) => {
3414
3853
  ...Object.keys(extra_headers).length > 0 ? { extra_headers } : {}
3415
3854
  });
3416
3855
  };
3856
+ /**
3857
+ * Build the OpenRouter ai_sdk adapter: validates the required api_key and
3858
+ * lazily loads @openrouter/ai-sdk-provider to build models.
3859
+ */
3417
3860
  const create_openrouter_ai_sdk_adapter = (init) => {
3418
3861
  const api_key = typeof init.api_key === "string" ? init.api_key : "";
3419
3862
  if (api_key.length === 0) throw new engine_config_error("openrouter provider requires a non-empty api_key", "openrouter");
@@ -3448,6 +3891,9 @@ const BEDROCK_THINKING_BUDGETS = {
3448
3891
  xhigh: 32e3,
3449
3892
  max: 64e3
3450
3893
  };
3894
+ /**
3895
+ * Map an EffortLevel to the Bedrock `reasoningConfig` provider option.
3896
+ */
3451
3897
  function translate_bedrock_effort(effort) {
3452
3898
  const budget = BEDROCK_THINKING_BUDGETS[effort];
3453
3899
  if (budget === 0) return {
@@ -3462,6 +3908,9 @@ function translate_bedrock_effort(effort) {
3462
3908
  effort_ignored: false
3463
3909
  };
3464
3910
  }
3911
+ /**
3912
+ * Normalize Bedrock's raw usage payload into UsageTotals.
3913
+ */
3465
3914
  function normalize_bedrock_usage(raw) {
3466
3915
  return default_normalize_usage(raw);
3467
3916
  }
@@ -3473,6 +3922,11 @@ const SUPPORTED$1 = /* @__PURE__ */ new Set([
3473
3922
  "image_input",
3474
3923
  "reasoning"
3475
3924
  ]);
3925
+ /**
3926
+ * Build the Bedrock ai_sdk adapter: validates the required region, resolves
3927
+ * the chosen auth mode (bearer token, SigV4 keys, or the ambient AWS
3928
+ * credential chain), and lazily loads @ai-sdk/amazon-bedrock to build models.
3929
+ */
3476
3930
  const create_bedrock_adapter = (init) => {
3477
3931
  const region = typeof init["region"] === "string" ? init["region"] : "";
3478
3932
  if (region.length === 0) throw new engine_config_error("bedrock provider requires a non-empty region", "bedrock");
@@ -3502,12 +3956,12 @@ const create_bedrock_adapter = (init) => {
3502
3956
  //#endregion
3503
3957
  //#region src/engine/providers/claude_cli/constants.ts
3504
3958
  /**
3505
- * Frozen constants for the claude_cli provider (spec §5.1 defaults, §6.3
3506
- * escalation window, §10.2 cost decomposition multipliers, §11 F19 auth
3507
- * pattern list).
3959
+ * Frozen constants for the claude_cli provider: startup and idle defaults,
3960
+ * the escalation window, cost decomposition multipliers, and the auth
3961
+ * failure pattern list.
3508
3962
  *
3509
3963
  * Arrays are Object.freeze-d at module load so downstream code cannot mutate
3510
- * them (constraints §7 invariant 25).
3964
+ * them.
3511
3965
  */
3512
3966
  const CLI_BINARY_DEFAULT = "claude";
3513
3967
  const SIGKILL_ESCALATION_MS = 2e3;
@@ -3524,31 +3978,20 @@ const DEFAULT_SETTING_SOURCES = Object.freeze(["project", "local"]);
3524
3978
  //#endregion
3525
3979
  //#region src/engine/providers/claude_cli/auth.ts
3526
3980
  /**
3527
- * Authentication enforcement for the claude_cli adapter (spec §4, §6.1).
3981
+ * Authentication enforcement for the claude_cli adapter.
3528
3982
  *
3529
- * - build_env composes the subprocess env from config + caller overrides.
3530
- * Regardless of auth_mode, it seeds the standard process-env keys
3531
- * (PATH, HOME, SHELL, USER, LOGNAME, LANG, TMPDIR) so the spawned
3532
- * subprocess can locate the sandbox wrapper (greywall/bwrap) and the
3533
- * claude binary on PATH. Set `inherit_env: false` to opt out and start
3534
- * from an empty env. Under oauth mode the *full* process.env is also
3535
- * inherited (the CLI needs HOME/etc plus session-specific vars to reach
3536
- * the logged-in OAuth session). Auth-mode scrub runs last on the merged
3537
- * result so nothing — caller env, inherited env, or config — can
3538
- * re-introduce ANTHROPIC_API_KEY under 'oauth'.
3539
- * - validate_auth_config throws engine_config_error synchronously when
3540
- * auth_mode === 'api_key' without a non-empty api_key.
3541
- * - stderr_is_auth_failure matches captured stderr against the frozen
3542
- * CLI_AUTH_ERROR_PATTERNS list, case-insensitively.
3983
+ * Composes the subprocess environment from provider config and call-level
3984
+ * overrides, validates that `auth_mode: 'api_key'` has a key to use, and
3985
+ * recognizes CLI stderr auth failures so they can be surfaced as
3986
+ * `provider_auth_error` instead of a generic exit-code error.
3543
3987
  */
3544
3988
  /**
3545
3989
  * Standard env keys forwarded from process.env so the spawn target
3546
3990
  * (greywall/bwrap on PATH, then `claude`) can be resolved and run.
3547
3991
  *
3548
- * Mirrors `STANDARD_KEYS` in
3549
- * packages/fascicle/src/forward_standard_env.ts. Keep the two lists in
3550
- * sync; engine cannot import from fascicle (the umbrella depends on
3551
- * engine, not the other way).
3992
+ * Mirrors `STANDARD_KEYS` in `src/forward_standard_env.ts`. Keep the two
3993
+ * lists in sync; engine cannot import from fascicle (the umbrella depends
3994
+ * on engine, not the other way).
3552
3995
  */
3553
3996
  const STANDARD_ENV_KEYS = [
3554
3997
  "PATH",
@@ -3559,11 +4002,33 @@ const STANDARD_ENV_KEYS = [
3559
4002
  "LANG",
3560
4003
  "TMPDIR"
3561
4004
  ];
4005
+ /**
4006
+ * Throw `engine_config_error` synchronously when `auth_mode: 'api_key'` is
4007
+ * set without a non-empty `api_key`.
4008
+ *
4009
+ * Runs at adapter construction time so a misconfigured provider fails
4010
+ * fast, before any CLI subprocess is spawned.
4011
+ */
3562
4012
  function validate_auth_config(config) {
3563
4013
  if ((config.auth_mode ?? "auto") === "api_key") {
3564
4014
  if ((typeof config.api_key === "string" ? config.api_key : "").length === 0) throw new engine_config_error("api_key is required for auth_mode: api_key", "claude_cli");
3565
4015
  }
3566
4016
  }
4017
+ /**
4018
+ * Compose the subprocess environment for one claude CLI invocation.
4019
+ *
4020
+ * Regardless of `auth_mode`, seeds the standard process-env keys (PATH,
4021
+ * HOME, SHELL, USER, LOGNAME, LANG, TMPDIR) by default so the spawned
4022
+ * subprocess can locate the sandbox wrapper (greywall/bwrap) and the
4023
+ * claude binary on PATH. Set `inherit_env: false` on the provider config to
4024
+ * opt out and start from an empty env instead.
4025
+ *
4026
+ * Under `auth_mode: 'oauth'` the full `process.env` is inherited instead
4027
+ * of just the standard keys, because the CLI needs HOME plus
4028
+ * session-specific vars to reach the already-logged-in OAuth session. The
4029
+ * auth-mode scrub runs last, after config and caller overrides are merged
4030
+ * in, so nothing can re-introduce `ANTHROPIC_API_KEY` under `'oauth'`.
4031
+ */
3567
4032
  function build_env(config, caller_env, auth_mode) {
3568
4033
  const env = {};
3569
4034
  if (config.inherit_env !== false) if (auth_mode === "oauth") {
@@ -3586,6 +4051,13 @@ function build_env(config, caller_env, auth_mode) {
3586
4051
  if (typeof config.api_key === "string" && config.api_key.length > 0) env["ANTHROPIC_API_KEY"] = config.api_key;
3587
4052
  return env;
3588
4053
  }
4054
+ /**
4055
+ * Check whether captured CLI stderr looks like an auth failure.
4056
+ *
4057
+ * Matches case-insensitively against the frozen `CLI_AUTH_ERROR_PATTERNS`
4058
+ * list; used to turn a nonzero CLI exit into `provider_auth_error` instead
4059
+ * of a generic `claude_cli_error`.
4060
+ */
3589
4061
  function stderr_is_auth_failure(stderr) {
3590
4062
  if (stderr.length === 0) return false;
3591
4063
  const lower = stderr.toLowerCase();
@@ -3594,6 +4066,15 @@ function stderr_is_auth_failure(stderr) {
3594
4066
  }
3595
4067
  //#endregion
3596
4068
  //#region src/engine/providers/claude_cli/argv.ts
4069
+ /**
4070
+ * Assemble the full argv array for one `claude` CLI invocation.
4071
+ *
4072
+ * Always runs the CLI in non-interactive, streaming JSON mode (`-p
4073
+ * --output-format stream-json --verbose`) so the adapter can parse events
4074
+ * line by line. Flags are appended in a fixed order; `--resume` is only
4075
+ * added when a session id is present, and `--append-system-prompt` only
4076
+ * when there's a non-empty merged system prompt.
4077
+ */
3597
4078
  function build_cli_argv(input) {
3598
4079
  const args = [];
3599
4080
  args.push("-p");
@@ -3613,12 +4094,23 @@ function build_cli_argv(input) {
3613
4094
  for (const s of extra_args) args.push(s);
3614
4095
  return Object.freeze(args);
3615
4096
  }
4097
+ /**
4098
+ * Join the caller's `system` prompt and the `append_system_prompt` call
4099
+ * option into the single string passed to `--append-system-prompt`.
4100
+ *
4101
+ * Empty or undefined parts are dropped; when both parts are present they're
4102
+ * separated by a blank line.
4103
+ */
3616
4104
  function merge_system(opts_system, append) {
3617
4105
  const parts = [];
3618
4106
  if (typeof opts_system === "string" && opts_system.length > 0) parts.push(opts_system);
3619
4107
  if (typeof append === "string" && append.length > 0) parts.push(append);
3620
4108
  return parts.join("\n\n");
3621
4109
  }
4110
+ /**
4111
+ * Merge the caller's `allowed_tools` allowlist with the tool names derived
4112
+ * from `opts.tools`, de-duplicating while preserving first-seen order.
4113
+ */
3622
4114
  function merge_allowed_tools(call_allowlist, tool_names) {
3623
4115
  const seen = /* @__PURE__ */ new Set();
3624
4116
  const merged = [];
@@ -3634,11 +4126,11 @@ function merge_allowed_tools(call_allowlist, tool_names) {
3634
4126
  //#endregion
3635
4127
  //#region src/engine/providers/claude_cli/sandbox.ts
3636
4128
  /**
3637
- * Sandbox wrapper for the claude_cli adapter (spec §5.1, F30).
4129
+ * Sandbox wrapper for the claude_cli adapter.
3638
4130
  *
3639
- * Builds the `{ spawn_cmd, prefix_args }` pair for bwrap and greywall. When no
3640
- * sandbox is configured, returns { spawn_cmd: binary, prefix_args: [] } — the
3641
- * caller then concatenates prefix_args before the CLI argv.
4131
+ * Builds the `{ spawn_cmd, prefix_args }` pair for bwrap and greywall. When
4132
+ * no sandbox is configured, returns `{ spawn_cmd: binary, prefix_args: [] }`;
4133
+ * the caller then concatenates prefix_args before the CLI argv.
3642
4134
  *
3643
4135
  * Both wrappers allow the binary to execute while restricting network reach
3644
4136
  * to the allowlist and write access to additional paths on top of the
@@ -3658,6 +4150,12 @@ function merge_allowed_tools(call_allowlist, tool_names) {
3658
4150
  * fields and host-level allowlisting is currently enforced at the
3659
4151
  * greyproxy layer).
3660
4152
  */
4153
+ /**
4154
+ * Pick the sandbox wrapper (if any) and build its wrapping argv.
4155
+ *
4156
+ * Returns the unwrapped binary with no prefix args when `sandbox` is
4157
+ * undefined.
4158
+ */
3661
4159
  function build_sandbox_plan(binary, sandbox) {
3662
4160
  if (sandbox === void 0) return {
3663
4161
  spawn_cmd: binary,
@@ -3672,6 +4170,15 @@ function build_sandbox_plan(binary, sandbox) {
3672
4170
  prefix_args: build_greywall_args(binary, sandbox)
3673
4171
  };
3674
4172
  }
4173
+ /**
4174
+ * Build the `bwrap` argv prefix that sandboxes the claude binary.
4175
+ *
4176
+ * Read-only binds the base OS directories, mounts fresh `/proc`, `/dev`,
4177
+ * and a tmpfs `/tmp`, and unshares the user/pid/ipc/uts/cgroup namespaces
4178
+ * so the child can't see or touch the host outside what's explicitly bound
4179
+ * in. Network access is off (`--unshare-net`) unless a non-empty
4180
+ * `network_allowlist` is given.
4181
+ */
3675
4182
  function build_bwrap_args(binary, sandbox) {
3676
4183
  const args = [];
3677
4184
  args.push("--ro-bind", "/usr", "/usr");
@@ -3699,6 +4206,13 @@ function build_bwrap_args(binary, sandbox) {
3699
4206
  args.push(binary);
3700
4207
  return args;
3701
4208
  }
4209
+ /**
4210
+ * Build the greywall argv prefix: `--settings <path> -- <binary>`.
4211
+ *
4212
+ * Uses `sandbox.settings_path` directly when the caller supplied one;
4213
+ * otherwise writes a fresh settings file derived from
4214
+ * `network_allowlist`/`additional_write_paths`.
4215
+ */
3702
4216
  function build_greywall_args(binary, sandbox) {
3703
4217
  return [
3704
4218
  "--settings",
@@ -3707,6 +4221,10 @@ function build_greywall_args(binary, sandbox) {
3707
4221
  binary
3708
4222
  ];
3709
4223
  }
4224
+ /**
4225
+ * Write a greywall JSON settings file for one sandboxed run to a fresh
4226
+ * temp directory and return its path.
4227
+ */
3710
4228
  function write_greywall_settings(sandbox) {
3711
4229
  const path = join(mkdtempSync(join(tmpdir(), `fascicle-greywall-${process.pid}-`)), "greywall.json");
3712
4230
  const payload = {
@@ -3719,21 +4237,23 @@ function write_greywall_settings(sandbox) {
3719
4237
  //#endregion
3720
4238
  //#region src/engine/providers/claude_cli/spawn.ts
3721
4239
  /**
3722
- * Subprocess lifecycle for the claude_cli adapter (spec §6, constraints §5.10).
4240
+ * Subprocess lifecycle for the claude_cli adapter.
3723
4241
  *
3724
4242
  * The factory exposes:
3725
- * - `live_children`: a closure-captured Set<ChildProcess> per-adapter-factory
3726
- * call (constraints §7 invariant 5: no module-level mutable state).
4243
+ * - `live_children`: a closure-captured Set<ChildProcess> per
4244
+ * adapter-factory call; no state is shared at module scope, so two
4245
+ * factory invocations track two independent sets of children.
3727
4246
  * - `spawn_cli(...)`: spawns the child with { detached: true, stdio: [...],
3728
- * env, cwd, shell: false }; arms startup + stall timers; SIGTERM→SIGKILL
3729
- * escalation on signal; removes from live set on close.
3730
- * - `dispose_all()`: issues SIGTERM→SIGKILL for every live child and awaits
3731
- * every close.
4247
+ * env, cwd, shell: false }; arms startup + stall timers; escalates
4248
+ * SIGTERM to SIGKILL on signal; removes the child from the live set on
4249
+ * close.
4250
+ * - `dispose_all()`: sends SIGTERM then SIGKILL to every live child and
4251
+ * awaits every close.
3732
4252
  *
3733
4253
  * A single process-wide `exit` handler synchronously SIGKILLs every live
3734
- * child across every spawn registry (constraints §5.10 #5). The handler is
3735
- * installed once per Node process and iterates a registry of adapter
3736
- * live-sets.
4254
+ * child across every spawn registry, so a crashing or exiting host process
4255
+ * doesn't leak subprocesses. The handler is installed once per Node
4256
+ * process and iterates a registry of adapter live-sets.
3737
4257
  *
3738
4258
  * `node:child_process` imports are confined to this directory (enforced by
3739
4259
  * rules/no-child-process-outside-claude-cli.yml). The spawn call passes
@@ -3742,6 +4262,15 @@ function write_greywall_settings(sandbox) {
3742
4262
  */
3743
4263
  const ALL_REGISTRIES = /* @__PURE__ */ new Set();
3744
4264
  let exit_handler_installed = false;
4265
+ /**
4266
+ * Install the process-wide `exit` handler that SIGKILLs every live child
4267
+ * across every spawn registry. Calling this more than once is a no-op.
4268
+ *
4269
+ * Children are spawned with `detached: true`, which makes each one the
4270
+ * leader of its own process group; signaling `-child.pid` (a negative pid)
4271
+ * targets the whole group instead of just the direct child, so any
4272
+ * grandchildren the CLI itself spawned die too.
4273
+ */
3745
4274
  function install_exit_handler_once() {
3746
4275
  if (exit_handler_installed) return;
3747
4276
  exit_handler_installed = true;
@@ -3755,6 +4284,14 @@ function install_exit_handler_once() {
3755
4284
  };
3756
4285
  process.on("exit", handler);
3757
4286
  }
4287
+ /**
4288
+ * Build a `SpawnRuntime`: a per-adapter-instance registry of live children
4289
+ * plus the `spawn_cli`/`dispose_all` operations that manage them.
4290
+ *
4291
+ * Registers `live_children` in the module-wide `ALL_REGISTRIES` set so the
4292
+ * process `exit` handler installed by `install_exit_handler_once` can find
4293
+ * and kill this runtime's children too.
4294
+ */
3758
4295
  function create_spawn_runtime() {
3759
4296
  const live_children = /* @__PURE__ */ new Set();
3760
4297
  ALL_REGISTRIES.add(live_children);
@@ -3909,6 +4446,15 @@ function create_spawn_runtime() {
3909
4446
  dispose_all
3910
4447
  };
3911
4448
  }
4449
+ /**
4450
+ * Turn a child process's stdout into an async iterable of complete lines.
4451
+ *
4452
+ * Buffers partial output across `data` events and yields only on `\n`
4453
+ * boundaries; on `end`, flushes a trailing line that has no terminator.
4454
+ * Calls `on_data` on every chunk, before buffering, so the caller can reset
4455
+ * startup/stall timers on any byte of output rather than only on line
4456
+ * boundaries.
4457
+ */
3912
4458
  async function* build_stdout_lines(child, on_data) {
3913
4459
  const stdout = child.stdout;
3914
4460
  if (stdout === null) return;
@@ -3962,29 +4508,29 @@ async function* build_stdout_lines(child, on_data) {
3962
4508
  //#endregion
3963
4509
  //#region src/engine/providers/claude_cli/stream_parse.ts
3964
4510
  /**
3965
- * JSON-lines stream parser for the claude CLI stdout (spec §7).
4511
+ * JSON-lines stream parser for the claude CLI stdout.
3966
4512
  *
3967
- * The parser is a line-buffered state machine with minimal state:
4513
+ * The CLI (run with `--output-format stream-json`) writes one JSON event per
4514
+ * line: `system` (session init), `assistant` (model output), `user` (tool
4515
+ * results echoed back into the conversation), `result` (the single terminal
4516
+ * event carrying totals), and `rate_limit_event` (informational rate-limit
4517
+ * budget report). The parser is a line-buffered state machine with minimal
4518
+ * state:
3968
4519
  * - buffered partial line
3969
- * - last-seen event type (assistant | user/tool_result | system | result)
3970
- * used to increment step_index on the turn boundary (new assistant
3971
- * following a user/tool_result)
3972
- * - current step_index
4520
+ * - last-seen event type (assistant | user/tool_result | system | result);
4521
+ * an `assistant` event that follows a user/tool_result marks a turn
4522
+ * boundary and increments `step_index`
4523
+ * - current `step_index`
3973
4524
  *
3974
4525
  * Malformed JSON records `{ kind: 'cli_parse_error', line }` to trajectory
3975
4526
  * and skips; unknown event types record `{ kind: 'cli_unknown_event', raw }`
3976
- * and skip (spec §7.1, §7.4). Neither ever throws.
4527
+ * and skip. Neither ever throws.
3977
4528
  *
3978
4529
  * Event shapes are Zod-validated via `cli_event_schema` (a
3979
- * `z.discriminatedUnion` over the recognized CLI event types: system,
3980
- * assistant, user, result, rate_limit_event). Per-entry content arrays use
3981
- * `.transform` to silently drop invalid entries rather than rejecting the
3982
- * whole event — this preserves forward compatibility with new CLI content
3983
- * types.
3984
- *
3985
- * `rate_limit_event` is informational: the CLI emits it between turns to
3986
- * report current rate-limit budget. The parser records a structured
3987
- * `cli_rate_limit_event` to trajectory and does not affect turn state.
4530
+ * `z.discriminatedUnion` over the recognized CLI event types). Per-entry
4531
+ * content arrays use `.transform` to silently drop invalid entries rather
4532
+ * than rejecting the whole event; this preserves forward compatibility with
4533
+ * new CLI content types.
3988
4534
  */
3989
4535
  const cli_usage_schema = z.object({
3990
4536
  input_tokens: z.number().optional(),
@@ -4069,6 +4615,9 @@ const cli_event_schema = z.discriminatedUnion("type", [
4069
4615
  result_event_schema,
4070
4616
  rate_limit_event_schema
4071
4617
  ]);
4618
+ /**
4619
+ * Build a fresh, empty `ParserState` for one CLI invocation.
4620
+ */
4072
4621
  function create_parser_state() {
4073
4622
  return {
4074
4623
  buffer: "",
@@ -4091,6 +4640,13 @@ function create_parser_state() {
4091
4640
  received_result: false
4092
4641
  };
4093
4642
  }
4643
+ /**
4644
+ * Convert the CLI's raw usage fields to fascicle's `UsageTotals` shape.
4645
+ *
4646
+ * `cache_read_input_tokens` maps to `cached_input_tokens` and
4647
+ * `cache_creation_input_tokens` maps to `cache_write_tokens`; both are
4648
+ * omitted when the CLI didn't report them.
4649
+ */
4094
4650
  function map_usage(raw) {
4095
4651
  if (raw === void 0) return {
4096
4652
  input_tokens: 0,
@@ -4104,18 +4660,27 @@ function map_usage(raw) {
4104
4660
  if (typeof raw.cache_creation_input_tokens === "number") out.cache_write_tokens = raw.cache_creation_input_tokens;
4105
4661
  return out;
4106
4662
  }
4663
+ /**
4664
+ * Record a line that failed to parse as JSON to the trajectory logger.
4665
+ */
4107
4666
  function record_parse_error(trajectory, line) {
4108
4667
  trajectory?.record({
4109
4668
  kind: "cli_parse_error",
4110
4669
  line
4111
4670
  });
4112
4671
  }
4672
+ /**
4673
+ * Record a parsed-but-unrecognized CLI event to the trajectory logger.
4674
+ */
4113
4675
  function record_unknown_event(trajectory, raw) {
4114
4676
  trajectory?.record({
4115
4677
  kind: "cli_unknown_event",
4116
4678
  raw
4117
4679
  });
4118
4680
  }
4681
+ /**
4682
+ * Record the CLI's `system` (session init) event to the trajectory logger.
4683
+ */
4119
4684
  function record_session_started(trajectory, session_id, model) {
4120
4685
  trajectory?.record({
4121
4686
  kind: "cli_session_started",
@@ -4123,6 +4688,9 @@ function record_session_started(trajectory, session_id, model) {
4123
4688
  model
4124
4689
  });
4125
4690
  }
4691
+ /**
4692
+ * Record a `rate_limit_event` to the trajectory logger.
4693
+ */
4126
4694
  function record_rate_limit(trajectory, event) {
4127
4695
  const info = event.rate_limit_info;
4128
4696
  trajectory?.record({
@@ -4136,6 +4704,10 @@ function record_rate_limit(trajectory, event) {
4136
4704
  is_using_overage: info?.isUsingOverage
4137
4705
  });
4138
4706
  }
4707
+ /**
4708
+ * Push the in-progress turn onto `state.turns` and reset the per-turn
4709
+ * accumulators for the next turn.
4710
+ */
4139
4711
  function flush_turn(state) {
4140
4712
  state.turns.push({
4141
4713
  step_index: state.current_step_index,
@@ -4152,14 +4724,32 @@ function flush_turn(state) {
4152
4724
  output_tokens: 0
4153
4725
  };
4154
4726
  }
4727
+ /**
4728
+ * Validate a parsed JSON value against `cli_event_schema`, returning
4729
+ * `undefined` instead of throwing on a mismatch.
4730
+ */
4155
4731
  function as_event(raw) {
4156
4732
  const result = cli_event_schema.safeParse(raw);
4157
4733
  return result.success ? result.data : void 0;
4158
4734
  }
4735
+ /**
4736
+ * Append a `StreamChunk` to the output array and, if the caller passed an
4737
+ * `on_chunk` dispatcher, await its delivery too.
4738
+ */
4159
4739
  async function emit_chunk(chunks, dispatch, chunk) {
4160
4740
  chunks.push(chunk);
4161
4741
  if (dispatch !== void 0) await dispatch(chunk);
4162
4742
  }
4743
+ /**
4744
+ * Handle one `assistant` event: emit `text`, `tool_call_start`, and
4745
+ * `tool_call_end` chunks for its content and accumulate them onto the
4746
+ * current turn.
4747
+ *
4748
+ * An `assistant` event that follows a `user`/tool-result event marks a new
4749
+ * turn boundary: it first emits a synthetic `step_finish` chunk for the
4750
+ * turn that just ended, flushes that turn onto `state.turns`, and advances
4751
+ * `current_step_index`.
4752
+ */
4163
4753
  async function handle_assistant(state, event, chunks, dispatch) {
4164
4754
  if (state.last_event_type === "user_tool_result") {
4165
4755
  const usage = { ...state.turn_usage };
@@ -4203,6 +4793,10 @@ async function handle_assistant(state, event, chunks, dispatch) {
4203
4793
  }
4204
4794
  state.last_event_type = "assistant";
4205
4795
  }
4796
+ /**
4797
+ * Handle one `user` event: emit a `tool_result` chunk for each tool result
4798
+ * in its content and accumulate them onto the current turn.
4799
+ */
4206
4800
  async function handle_user(state, event, chunks, dispatch) {
4207
4801
  for (const part of event.message.content) {
4208
4802
  if (part.type !== "tool_result") continue;
@@ -4230,6 +4824,14 @@ async function handle_user(state, event, chunks, dispatch) {
4230
4824
  }
4231
4825
  state.last_event_type = "user_tool_result";
4232
4826
  }
4827
+ /**
4828
+ * Handle the terminal `result` event: capture the call's session id, cost,
4829
+ * duration, and final usage, flush the last in-progress turn, and emit the
4830
+ * closing `finish` chunk.
4831
+ *
4832
+ * Falls back to `event.result` for `final_text` only when no assistant
4833
+ * text was collected during the stream.
4834
+ */
4233
4835
  async function handle_result(state, event, chunks, dispatch) {
4234
4836
  state.received_result = true;
4235
4837
  if (typeof event.session_id === "string") state.session_id = event.session_id;
@@ -4250,6 +4852,9 @@ async function handle_result(state, event, chunks, dispatch) {
4250
4852
  usage
4251
4853
  });
4252
4854
  }
4855
+ /**
4856
+ * Dispatch one validated `CliEvent` to its type-specific handler.
4857
+ */
4253
4858
  async function handle_event(state, event, chunks, dispatch, trajectory) {
4254
4859
  switch (event.type) {
4255
4860
  case "system":
@@ -4271,6 +4876,13 @@ async function handle_event(state, event, chunks, dispatch, trajectory) {
4271
4876
  return;
4272
4877
  }
4273
4878
  }
4879
+ /**
4880
+ * Parse and handle one line of CLI stdout.
4881
+ *
4882
+ * Blank lines are skipped. Lines that aren't valid JSON, or that don't
4883
+ * match any known event shape, are recorded to the trajectory logger and
4884
+ * otherwise ignored; this function never throws.
4885
+ */
4274
4886
  async function consume_line(state, line, chunks, dispatch, trajectory) {
4275
4887
  const trimmed = line.trim();
4276
4888
  if (trimmed.length === 0) return;
@@ -4288,6 +4900,13 @@ async function consume_line(state, line, chunks, dispatch, trajectory) {
4288
4900
  }
4289
4901
  await handle_event(state, event, chunks, dispatch, trajectory);
4290
4902
  }
4903
+ /**
4904
+ * Append raw stdout text to the parser's line buffer and consume every
4905
+ * complete line it now contains.
4906
+ *
4907
+ * Any trailing partial line (no `\n` yet) stays buffered for the next
4908
+ * call.
4909
+ */
4291
4910
  async function feed_chunk(state, chunk, chunks, dispatch, trajectory) {
4292
4911
  state.buffer += chunk;
4293
4912
  let nl_index = state.buffer.indexOf("\n");
@@ -4298,12 +4917,24 @@ async function feed_chunk(state, chunk, chunks, dispatch, trajectory) {
4298
4917
  nl_index = state.buffer.indexOf("\n");
4299
4918
  }
4300
4919
  }
4920
+ /**
4921
+ * Consume a final buffered line that has no trailing newline.
4922
+ *
4923
+ * `feed_chunk` only parses complete `\n`-terminated lines, so a trailing
4924
+ * unterminated fragment stays in the buffer until the caller knows the
4925
+ * stream has actually ended. Call this once, after the last `feed_chunk`,
4926
+ * to parse that fragment as one last line.
4927
+ */
4301
4928
  async function flush_remaining(state, chunks, dispatch, trajectory) {
4302
4929
  if (state.buffer.length === 0) return;
4303
4930
  const line = state.buffer;
4304
4931
  state.buffer = "";
4305
4932
  await consume_line(state, line, chunks, dispatch, trajectory);
4306
4933
  }
4934
+ /**
4935
+ * Take an immutable copy of the parser state's accumulated results as a
4936
+ * `ParsedStream`.
4937
+ */
4307
4938
  function snapshot(state) {
4308
4939
  const base = {
4309
4940
  final_text: state.final_text,
@@ -4319,6 +4950,16 @@ function snapshot(state) {
4319
4950
  }
4320
4951
  //#endregion
4321
4952
  //#region src/engine/providers/claude_cli/cost.ts
4953
+ /**
4954
+ * Split a single `total_cost_usd` figure into an input/output cost
4955
+ * breakdown, weighted by token counts.
4956
+ *
4957
+ * Cache-read and cache-write tokens are cheaper and pricier respectively
4958
+ * than base input tokens, so they're weighted by `CACHE_READ_MULTIPLIER`
4959
+ * and `CACHE_WRITE_MULTIPLIER` before the total is distributed
4960
+ * proportionally across all weighted components. Returns an all-zero
4961
+ * estimate when there's no usage or no cost to distribute.
4962
+ */
4322
4963
  function decompose_total_cost(total_cost_usd, usage) {
4323
4964
  const input = Math.max(0, usage.input_tokens);
4324
4965
  const output = Math.max(0, usage.output_tokens);
@@ -4351,6 +4992,15 @@ function decompose_total_cost(total_cost_usd, usage) {
4351
4992
  if (cache_write > 0) breakdown.cache_write_usd = cache_write_usd_raw;
4352
4993
  return breakdown;
4353
4994
  }
4995
+ /**
4996
+ * Split a call's total cost across its turns, proportional to each turn's
4997
+ * output tokens, then decompose each turn's share into a `CostBreakdown`.
4998
+ *
4999
+ * Falls back to an equal split when every turn reports zero output tokens
5000
+ * (the proportional weights would otherwise all be zero). The last turn
5001
+ * absorbs the floating-point rounding remainder so the per-turn totals sum
5002
+ * exactly to `total_cost_usd`.
5003
+ */
4354
5004
  function allocate_cost_across_turns(total_cost_usd, turns) {
4355
5005
  if (turns.length === 0) return [];
4356
5006
  const total_output = turns.reduce((sum, t) => sum + Math.max(0, t.output_tokens), 0);
@@ -4379,6 +5029,14 @@ function allocate_cost_across_turns(total_cost_usd, turns) {
4379
5029
  }
4380
5030
  //#endregion
4381
5031
  //#region src/engine/providers/claude_cli/stream_result.ts
5032
+ /**
5033
+ * Sum a list of per-turn `UsageTotals` into one aggregate total.
5034
+ *
5035
+ * Optional fields (`cached_input_tokens`, `cache_write_tokens`,
5036
+ * `reasoning_tokens`) are included in the sum only when at least one input
5037
+ * reports them, so the aggregate omits a field entirely rather than
5038
+ * reporting a false zero.
5039
+ */
4382
5040
  function sum_usage$1(totals) {
4383
5041
  let input = 0;
4384
5042
  let output = 0;
@@ -4401,6 +5059,12 @@ function sum_usage$1(totals) {
4401
5059
  if (reasoning !== void 0) out.reasoning_tokens = reasoning;
4402
5060
  return out;
4403
5061
  }
5062
+ /**
5063
+ * Sum a list of per-turn `CostBreakdown`s into one aggregate breakdown.
5064
+ *
5065
+ * Returns `undefined` for an empty list. Optional cache fields are
5066
+ * included only when at least one input breakdown reports them.
5067
+ */
4404
5068
  function aggregate_cost_breakdowns(breakdowns) {
4405
5069
  if (breakdowns.length === 0) return void 0;
4406
5070
  let total = 0;
@@ -4434,6 +5098,14 @@ function aggregate_cost_breakdowns(breakdowns) {
4434
5098
  if (cache_write_present) agg.cache_write_usd = cache_write;
4435
5099
  return agg;
4436
5100
  }
5101
+ /**
5102
+ * Return the parsed stream's collected turns, or synthesize a single turn
5103
+ * from the top-level result when none were collected.
5104
+ *
5105
+ * A `result` event with no preceding `assistant` events (an immediate
5106
+ * error, or a response with no visible turns) leaves `parsed.turns` empty;
5107
+ * this keeps `build_generate_result` from having to special-case that.
5108
+ */
4437
5109
  function normalize_turns(parsed) {
4438
5110
  if (parsed.turns.length > 0) return parsed.turns;
4439
5111
  return [{
@@ -4444,6 +5116,13 @@ function normalize_turns(parsed) {
4444
5116
  usage: parsed.final_usage
4445
5117
  }];
4446
5118
  }
5119
+ /**
5120
+ * Build a `ToolCallRecord` for one tool call, attaching its matching
5121
+ * result (output or error) when present.
5122
+ *
5123
+ * `duration_ms` is always 0: the CLI's stream-json events don't report
5124
+ * per-tool-call timing, so there's nothing to measure it against.
5125
+ */
4447
5126
  function tool_call_record(step_index, call, results, now) {
4448
5127
  const rec = {
4449
5128
  id: call.id,
@@ -4459,6 +5138,14 @@ function tool_call_record(step_index, call, results, now) {
4459
5138
  }
4460
5139
  return rec;
4461
5140
  }
5141
+ /**
5142
+ * Assemble a `GenerateResult<T>` from a parsed CLI stream.
5143
+ *
5144
+ * Throws a `claude_cli_error` instead of returning when the CLI reported
5145
+ * an error result, since `FinishReason` has no `'error'` member and
5146
+ * returning `finish_reason: 'stop'` would make the failure look like a
5147
+ * successful call.
5148
+ */
4462
5149
  function build_generate_result(input) {
4463
5150
  const { parsed, resolved } = input;
4464
5151
  if (parsed.is_error) throw new claude_cli_error("result_error", parsed.final_text.length > 0 ? parsed.final_text : "claude_cli returned an error result");
@@ -4526,7 +5213,7 @@ function build_generate_result(input) {
4526
5213
  * that both parses as JSON and matches the schema wins.
4527
5214
  *
4528
5215
  * When every candidate fails, we prefer the schema-validation error from the
4529
- * FIRST candidate that parsed as JSON — that error reflects the model's
5216
+ * FIRST candidate that parsed as JSON: that error reflects the model's
4530
5217
  * primary output and is what a repair prompt should feed back. Later
4531
5218
  * candidates (e.g. the bracket-slice fallback) often produce noisy errors
4532
5219
  * like "expected object, received array" that misdirect the model. Only when
@@ -4557,6 +5244,11 @@ function parse_with_schema(schema, text) {
4557
5244
  };
4558
5245
  }
4559
5246
  const FENCE_BLOCK = /```(?:[\w-]*)\s*\n?([\s\S]*?)\n?```/g;
5247
+ /**
5248
+ * Generate JSON substrings to try parsing, from strictest to most lenient:
5249
+ * the trimmed text as-is, the body of every fenced code block, and the
5250
+ * outermost `{...}` and `[...]` slices. Duplicate candidates are dropped.
5251
+ */
4560
5252
  function json_candidates(text) {
4561
5253
  const candidates = [];
4562
5254
  const seen = /* @__PURE__ */ new Set();
@@ -4575,6 +5267,11 @@ function json_candidates(text) {
4575
5267
  push(slice_outermost(text, "[", "]"));
4576
5268
  return candidates;
4577
5269
  }
5270
+ /**
5271
+ * Slice `text` from its first `open` character through its last matching
5272
+ * `close` character, inclusive. Returns an empty string if `open` is absent
5273
+ * or `close` does not appear after it.
5274
+ */
4578
5275
  function slice_outermost(text, open, close) {
4579
5276
  const first = text.indexOf(open);
4580
5277
  const last = text.lastIndexOf(close);
@@ -4583,8 +5280,9 @@ function slice_outermost(text, open, close) {
4583
5280
  }
4584
5281
  /**
4585
5282
  * Build the canonical repair message appended after a schema parse failure.
4586
- * Content mirrors spec §6.5 exactly so the repair prompt is predictable and
4587
- * user-inspectable in trajectory output.
5283
+ *
5284
+ * The wording is fixed rather than adapter-specific, so the repair prompt
5285
+ * stays predictable and is easy to read back from trajectory output.
4588
5286
  */
4589
5287
  function build_repair_message(zod_error) {
4590
5288
  return {
@@ -4607,6 +5305,13 @@ function build_repair_prompt_text(zod_error) {
4607
5305
  function throw_schema_validation(zod_error, raw_text) {
4608
5306
  throw new schema_validation_error(`schema validation failed: ${format_zod_error(zod_error)}`, zod_error, raw_text);
4609
5307
  }
5308
+ /**
5309
+ * Render an unknown error value as a display string.
5310
+ *
5311
+ * Handles `Error` instances, plain strings, and objects with a string
5312
+ * `message` directly; falls back to `JSON.stringify`, and finally to a fixed
5313
+ * placeholder if even that throws.
5314
+ */
4610
5315
  function format_zod_error(err) {
4611
5316
  if (err === null || err === void 0) return "unknown error";
4612
5317
  if (typeof err === "string") return err;
@@ -4623,22 +5328,38 @@ function format_zod_error(err) {
4623
5328
  }
4624
5329
  //#endregion
4625
5330
  //#region src/engine/trajectory.ts
5331
+ /**
5332
+ * Open the `engine.generate` span that brackets one whole generate call.
5333
+ */
4626
5334
  function start_generate_span(trajectory, meta) {
4627
5335
  if (trajectory === void 0) return void 0;
4628
5336
  return trajectory.start_span("engine.generate", { ...meta });
4629
5337
  }
5338
+ /**
5339
+ * Close the `engine.generate` span with usage, finish reason, resolved model,
5340
+ * or the error message on failure.
5341
+ */
4630
5342
  function end_generate_span(trajectory, span_id, meta) {
4631
5343
  if (trajectory === void 0 || span_id === void 0) return;
4632
5344
  trajectory.end_span(span_id, { ...meta });
4633
5345
  }
5346
+ /**
5347
+ * Open an `engine.generate.step` span for one model turn in the tool loop.
5348
+ */
4634
5349
  function start_step_span(trajectory, index) {
4635
5350
  if (trajectory === void 0) return void 0;
4636
5351
  return trajectory.start_span("engine.generate.step", { index });
4637
5352
  }
5353
+ /**
5354
+ * Close an `engine.generate.step` span with per-step usage or error.
5355
+ */
4638
5356
  function end_step_span(trajectory, span_id, meta) {
4639
5357
  if (trajectory === void 0 || span_id === void 0) return;
4640
5358
  trajectory.end_span(span_id, { ...meta });
4641
5359
  }
5360
+ /**
5361
+ * Record a tool invocation request: name, call id, input, and duration.
5362
+ */
4642
5363
  function record_tool_call(trajectory, meta) {
4643
5364
  if (trajectory === void 0) return;
4644
5365
  const event = {
@@ -4677,16 +5398,19 @@ function record_tool_result(trajectory, meta) {
4677
5398
  });
4678
5399
  }
4679
5400
  /**
4680
- * Wrap a logger so engine events carry a `ts` (epoch milliseconds) even when
4681
- * generate is called directly with a caller-supplied logger rather than through
4682
- * the core runner. When the logger is already runner-decorated, the existing
4683
- * `ts` is preserved. Private to the engine to avoid widening the public surface.
5401
+ * Add a `ts` (epoch milliseconds) to span meta unless one is already set.
4684
5402
  */
4685
5403
  function stamp_ts(meta) {
4686
5404
  const out = { ...meta };
4687
5405
  if (!("ts" in out)) out["ts"] = Date.now();
4688
5406
  return out;
4689
5407
  }
5408
+ /**
5409
+ * Wrap a logger so engine events carry a `ts` (epoch milliseconds) even when
5410
+ * generate is called directly with a caller-supplied logger rather than
5411
+ * through the core runner. When the logger is already runner-decorated, the
5412
+ * existing `ts` is preserved.
5413
+ */
4690
5414
  function with_timestamps(inner) {
4691
5415
  if (inner === void 0) return void 0;
4692
5416
  return {
@@ -4706,6 +5430,10 @@ function with_timestamps(inner) {
4706
5430
  }
4707
5431
  };
4708
5432
  }
5433
+ /**
5434
+ * Record a per-step cost breakdown, tagged with whether the engine derived it
5435
+ * from pricing tables or the provider reported it directly.
5436
+ */
4709
5437
  function record_cost(trajectory, step_index, cost, source) {
4710
5438
  if (trajectory === void 0) return;
4711
5439
  const event = {
@@ -4724,6 +5452,9 @@ function record_cost(trajectory, step_index, cost, source) {
4724
5452
  ...event
4725
5453
  });
4726
5454
  }
5455
+ /**
5456
+ * Build the per-call dedup that emits `pricing_missing` once per model.
5457
+ */
4727
5458
  function create_pricing_missing_dedup(trajectory) {
4728
5459
  const seen = /* @__PURE__ */ new Set();
4729
5460
  return { emit(provider, model_id) {
@@ -4738,6 +5469,10 @@ function create_pricing_missing_dedup(trajectory) {
4738
5469
  });
4739
5470
  } };
4740
5471
  }
5472
+ /**
5473
+ * Record that a requested reasoning-effort setting was ignored because the
5474
+ * model does not support it.
5475
+ */
4741
5476
  function record_effort_ignored(trajectory, model_id) {
4742
5477
  if (trajectory === void 0) return;
4743
5478
  trajectory.record({
@@ -4749,7 +5484,7 @@ function record_effort_ignored(trajectory, model_id) {
4749
5484
  * Emit a structured event when a schema-driven generate call returns text
4750
5485
  * that fails parse + zod validation. Persists the raw model output and a
4751
5486
  * formatted zod issues summary to the trajectory so the failure is debuggable
4752
- * without needing stdout. Spec §6.5.
5487
+ * without needing stdout.
4753
5488
  */
4754
5489
  function record_schema_validation_failed(trajectory, meta) {
4755
5490
  if (trajectory === void 0) return;
@@ -4791,6 +5526,10 @@ function record_tool_calls_dropped(trajectory, meta) {
4791
5526
  dropped: meta.dropped
4792
5527
  });
4793
5528
  }
5529
+ /**
5530
+ * Record one stage of the tool-approval handshake (requested, granted, or
5531
+ * denied) for a specific tool call.
5532
+ */
4794
5533
  function record_tool_approval(trajectory, kind, meta) {
4795
5534
  if (trajectory === void 0) return;
4796
5535
  trajectory.record({
@@ -4800,6 +5539,9 @@ function record_tool_approval(trajectory, kind, meta) {
4800
5539
  tool_call_id: meta.tool_call_id
4801
5540
  });
4802
5541
  }
5542
+ /**
5543
+ * Build the per-call dedup that emits `option_ignored` once per option key.
5544
+ */
4803
5545
  function create_option_ignored_dedup(trajectory) {
4804
5546
  const seen = /* @__PURE__ */ new Set();
4805
5547
  return { emit(option, provider) {
@@ -4816,16 +5558,16 @@ function create_option_ignored_dedup(trajectory) {
4816
5558
  //#endregion
4817
5559
  //#region src/engine/providers/claude_cli/adapter.ts
4818
5560
  /**
4819
- * claude_cli adapter factory (spec §5.5, §6, §8, §13).
5561
+ * claude_cli adapter factory.
4820
5562
  *
4821
5563
  * Exports a `create_claude_cli_adapter(init)` factory that returns a
4822
5564
  * `ExternalAgentAdapter`. The factory closure-captures a per-instance
4823
5565
  * `spawn_runtime` (which owns its own `Set<ChildProcess>` live registry), so
4824
- * two factory invocations produce two independent registries (constraints §7
4825
- * invariant 5: no module-level mutable state).
5566
+ * two factory invocations produce two independent registries; no state is
5567
+ * shared at module scope.
4826
5568
  *
4827
5569
  * The returned adapter exposes exactly `{ kind: 'external', name, generate,
4828
- * dispose, supports }` — no `build_model`, `translate_effort`, or
5570
+ * dispose, supports }`, with no `build_model`, `translate_effort`, or
4829
5571
  * `normalize_usage` members.
4830
5572
  */
4831
5573
  const SUPPORTED = /* @__PURE__ */ new Set([
@@ -4843,21 +5585,46 @@ const CLAUDE_CLI_EFFORT_VALUES = {
4843
5585
  xhigh: "xhigh",
4844
5586
  max: "max"
4845
5587
  };
5588
+ /**
5589
+ * Build the `CLAUDE_CODE_EFFORT_LEVEL` env var entry for a given effort
5590
+ * level.
5591
+ *
5592
+ * Returns an empty object for `undefined` or `'none'`, which leaves the
5593
+ * inherited environment (and thus the CLI's own default) untouched.
5594
+ */
4846
5595
  function effort_env_for_claude_cli(effort) {
4847
5596
  if (effort === void 0 || effort === "none") return {};
4848
5597
  return { CLAUDE_CODE_EFFORT_LEVEL: CLAUDE_CLI_EFFORT_VALUES[effort] };
4849
5598
  }
5599
+ /**
5600
+ * Pull the `claude_cli`-scoped provider options out of `provider_options`.
5601
+ *
5602
+ * Returns an empty object when the caller didn't set any, so downstream
5603
+ * code can read fields without an undefined check.
5604
+ */
4850
5605
  function extract_call_opts(opts) {
4851
5606
  const raw = opts.provider_options?.["claude_cli"];
4852
5607
  if (raw === void 0 || raw === null || typeof raw !== "object") return {};
4853
5608
  return raw;
4854
5609
  }
5610
+ /**
5611
+ * Count how many `user` messages are in the prompt.
5612
+ *
5613
+ * A plain string prompt counts as a single user message.
5614
+ */
4855
5615
  function count_user_messages(prompt) {
4856
5616
  if (typeof prompt === "string") return 1;
4857
5617
  let count = 0;
4858
5618
  for (const m of prompt) if (m.role === "user") count += 1;
4859
5619
  return count;
4860
5620
  }
5621
+ /**
5622
+ * Extract the first user message's text to send as CLI stdin.
5623
+ *
5624
+ * `generate` rejects prompts with more than one user message (claude_cli
5625
+ * only supports a single turn per invocation), so only the first one is
5626
+ * ever relevant here.
5627
+ */
4861
5628
  function extract_prompt_text(prompt) {
4862
5629
  if (typeof prompt === "string") return prompt;
4863
5630
  for (const m of prompt) {
@@ -4869,14 +5636,32 @@ function extract_prompt_text(prompt) {
4869
5636
  }
4870
5637
  return "";
4871
5638
  }
5639
+ /**
5640
+ * Pull the system message content out of a `Message[]` prompt.
5641
+ *
5642
+ * Returns `undefined` for a plain string prompt or when no system message
5643
+ * is present.
5644
+ */
4872
5645
  function extract_system_text(prompt) {
4873
5646
  if (typeof prompt === "string") return void 0;
4874
5647
  for (const m of prompt) if (m.role === "system") return m.content;
4875
5648
  }
5649
+ /**
5650
+ * Serialize a Zod schema to the JSON Schema string the CLI's
5651
+ * `--json-schema` flag expects.
5652
+ */
4876
5653
  function compile_schema(schema) {
4877
5654
  const { $schema: _schema, $id: _id, ...json } = z.toJSONSchema(schema);
4878
5655
  return JSON.stringify(json);
4879
5656
  }
5657
+ /**
5658
+ * Turn a closed CLI subprocess's exit code, signal, and stderr into an
5659
+ * `Error`.
5660
+ *
5661
+ * Checks stderr for an auth failure first, then for a missing sandbox
5662
+ * binary, then falls back to a generic exit-code error. The stderr
5663
+ * snippet attached to each error is truncated to 512 bytes.
5664
+ */
4880
5665
  function classify_close_error(code, signal, stderr) {
4881
5666
  const snippet = stderr.slice(0, 512);
4882
5667
  if (stderr_is_auth_failure(stderr)) return new provider_auth_error(PROVIDER_NAME, `claude CLI reported an auth failure: ${snippet}`, { refresh_command: "claude login" });
@@ -4888,6 +5673,16 @@ function classify_close_error(code, signal, stderr) {
4888
5673
  if (status !== void 0) metadata.status = status;
4889
5674
  return new claude_cli_error("subprocess_exit", message, metadata);
4890
5675
  }
5676
+ /**
5677
+ * Spawn one claude CLI invocation, stream its stdout into parsed events,
5678
+ * and wait for it to close.
5679
+ *
5680
+ * Runs `session.wait_close()` and the stdout-consuming loop concurrently:
5681
+ * the process can still be flushing stdout while it exits, so waiting for
5682
+ * close first would drop those trailing lines. Throws if the process
5683
+ * exits non-zero or closes without ever emitting a terminal `result`
5684
+ * event.
5685
+ */
4891
5686
  async function run_cli(spawn_runtime, args) {
4892
5687
  const argv = build_cli_argv({
4893
5688
  model_id: args.model_id,
@@ -4932,6 +5727,13 @@ async function run_cli(spawn_runtime, args) {
4932
5727
  chunks
4933
5728
  };
4934
5729
  }
5730
+ /**
5731
+ * Build a claude_cli `ExternalAgentAdapter` bound to one config.
5732
+ *
5733
+ * Validates the auth config eagerly, before any call is made, and wires up
5734
+ * a spawn runtime plus an in-flight abort-controller registry that
5735
+ * `dispose()` uses to cancel every call still running.
5736
+ */
4935
5737
  function create_claude_cli_adapter(init) {
4936
5738
  const config = init;
4937
5739
  validate_auth_config(config);
@@ -5118,8 +5920,8 @@ function create_claude_cli_adapter(init) {
5118
5920
  *
5119
5921
  * Unknown provider names throw provider_not_configured_error. Custom
5120
5922
  * providers enter via `EngineConfig.custom_providers` at construction,
5121
- * resolved custom-first in create_engine; runtime (post-construction)
5122
- * registration stays deferred.
5923
+ * resolved custom-first in create_engine; there is no runtime
5924
+ * (post-construction) registration.
5123
5925
  */
5124
5926
  const BUILTIN_PROVIDERS = /* @__PURE__ */ new Map([
5125
5927
  ["anthropic", create_anthropic_adapter],
@@ -5131,9 +5933,16 @@ const BUILTIN_PROVIDERS = /* @__PURE__ */ new Map([
5131
5933
  ["bedrock", create_bedrock_adapter],
5132
5934
  ["claude_cli", create_claude_cli_adapter]
5133
5935
  ]);
5936
+ /**
5937
+ * List the names of every built-in provider, in registration order.
5938
+ */
5134
5939
  function list_builtin_providers() {
5135
5940
  return [...BUILTIN_PROVIDERS.keys()];
5136
5941
  }
5942
+ /**
5943
+ * Look up a built-in provider's adapter factory by name, throwing
5944
+ * provider_not_configured_error for unknown names.
5945
+ */
5137
5946
  function get_provider_factory(name) {
5138
5947
  const factory = BUILTIN_PROVIDERS.get(name);
5139
5948
  if (factory === void 0) throw new provider_not_configured_error(name);
@@ -5143,13 +5952,17 @@ function get_provider_factory(name) {
5143
5952
  //#region src/engine/merge_defaults.ts
5144
5953
  /**
5145
5954
  * Default-merging helpers for engine-level `EngineDefaults`.
5955
+ */
5956
+ /**
5957
+ * Merge per-call `provider_options` over engine-level defaults.
5146
5958
  *
5147
- * Scalar fields are merged inline at the consumer via `opts.x ?? defaults.x`.
5959
+ * Scalar fields merge inline at the call site via `opts.x ?? defaults.x`, but
5148
5960
  * `provider_options` needs a two-level merge: outer keys are provider names
5149
- * (claude_cli, anthropic, ...) and inner records hold per-provider settings.
5150
- * Per-call inner keys override defaults' inner keys; provider keys unique
5151
- * to either side fall through. No recursion beyond that — deeper structures
5152
- * replace wholesale to keep the rule predictable.
5961
+ * (`claude_cli`, `anthropic`, ...) and inner records hold per-provider
5962
+ * settings. Per-call inner keys override the matching default's inner keys;
5963
+ * provider keys unique to either side fall through unchanged. There is no
5964
+ * recursion past that second level, so deeper structures replace wholesale
5965
+ * rather than merging further.
5153
5966
  */
5154
5967
  function merge_provider_options(defaults, call) {
5155
5968
  if (defaults === void 0 && call === void 0) return void 0;
@@ -5171,6 +5984,9 @@ function merge_provider_options(defaults, call) {
5171
5984
  }
5172
5985
  return out;
5173
5986
  }
5987
+ /**
5988
+ * Narrow `value` to a plain (non-null, non-array) object.
5989
+ */
5174
5990
  function is_plain_object$1(value) {
5175
5991
  return value !== null && typeof value === "object" && !Array.isArray(value);
5176
5992
  }
@@ -5206,6 +6022,15 @@ const OPTIONAL_FIELDS = [
5206
6022
  "cached_input_tokens",
5207
6023
  "cache_write_tokens"
5208
6024
  ];
6025
+ /**
6026
+ * Sum token usage across every step of a generate call.
6027
+ *
6028
+ * `input_tokens` and `output_tokens` always total. The optional fields
6029
+ * (`reasoning_tokens`, `cached_input_tokens`, `cache_write_tokens`) stay
6030
+ * absent on the result unless at least one step reported them; once
6031
+ * present, every step contributes to the sum, with steps that omit the
6032
+ * field counting as 0.
6033
+ */
5209
6034
  function sum_usage(steps) {
5210
6035
  let input_tokens = 0;
5211
6036
  let output_tokens = 0;
@@ -5282,6 +6107,9 @@ function scan_balanced_json(text, start_index) {
5282
6107
  }
5283
6108
  }
5284
6109
  }
6110
+ /**
6111
+ * Check for a non-null, non-array object.
6112
+ */
5285
6113
  function is_plain_object(value) {
5286
6114
  return typeof value === "object" && value !== null && !Array.isArray(value);
5287
6115
  }
@@ -5300,18 +6128,36 @@ function call_shape(value) {
5300
6128
  args
5301
6129
  };
5302
6130
  }
6131
+ /**
6132
+ * Check whether a span intersects any masked region.
6133
+ */
5303
6134
  function overlaps_any(span, masks) {
5304
6135
  return masks.some((m) => span.start < m.end && m.start < span.end);
5305
6136
  }
6137
+ /**
6138
+ * Find the mask covering a text index, if any, so scanners can jump past it.
6139
+ */
5306
6140
  function mask_containing(masks, index) {
5307
6141
  return masks.find((m) => index >= m.start && index < m.end);
5308
6142
  }
6143
+ /**
6144
+ * Strip at most one leading and one trailing newline.
6145
+ *
6146
+ * Qwen XML parameter values are written on their own lines; the wrapping
6147
+ * newlines are markup, but interior whitespace is real data and stays.
6148
+ */
5309
6149
  function trim_one_newline(value) {
5310
6150
  let out = value;
5311
6151
  if (out.startsWith("\n")) out = out.slice(1);
5312
6152
  if (out.endsWith("\n")) out = out.slice(0, -1);
5313
6153
  return out;
5314
6154
  }
6155
+ /**
6156
+ * Extract qwen_xml `<function=name>` candidates from a tool_call block body.
6157
+ *
6158
+ * Parameters land as a string map (typed coercion happens at validation).
6159
+ * Spans are offset by `inner_start` back into the full-text coordinate space.
6160
+ */
5315
6161
  function scan_qwen_functions(inner_start, inner) {
5316
6162
  const out = [];
5317
6163
  for (const fn of inner.matchAll(FUNCTION_RE)) {
@@ -5335,6 +6181,12 @@ function scan_qwen_functions(inner_start, inner) {
5335
6181
  }
5336
6182
  return out;
5337
6183
  }
6184
+ /**
6185
+ * Scan `<tool_call>` blocks for hermes and qwen_xml candidates.
6186
+ *
6187
+ * Every block extent (accepted, rejected, or unterminated) is returned as a
6188
+ * mask so later passes never re-match payloads inside it.
6189
+ */
5338
6190
  function scan_tool_call_blocks(text) {
5339
6191
  const candidates = [];
5340
6192
  const masks = [];
@@ -5380,6 +6232,12 @@ function scan_tool_call_blocks(text) {
5380
6232
  masks
5381
6233
  };
5382
6234
  }
6235
+ /**
6236
+ * Scan code fences for JSON-format candidates.
6237
+ *
6238
+ * All fences become masks (keeping the bare pass out of code samples), but
6239
+ * only fences with no info string or `json` are parsed as candidates.
6240
+ */
5383
6241
  function scan_fences(text, block_masks) {
5384
6242
  const candidates = [];
5385
6243
  const masks = [];
@@ -5412,6 +6270,13 @@ function scan_fences(text, block_masks) {
5412
6270
  masks
5413
6271
  };
5414
6272
  }
6273
+ /**
6274
+ * Scan unmasked text for bare `{name, arguments}` JSON objects.
6275
+ *
6276
+ * A complete object that is not call-shaped is skipped whole rather than
6277
+ * descended into, so substructures of ordinary JSON output cannot
6278
+ * false-positive.
6279
+ */
5415
6280
  function scan_bare_json(text, masks) {
5416
6281
  const out = [];
5417
6282
  let i = 0;
@@ -5445,6 +6310,14 @@ function scan_bare_json(text, masks) {
5445
6310
  }
5446
6311
  return out;
5447
6312
  }
6313
+ /**
6314
+ * Promote a candidate to a `SalvagedCall` when its tool exists and its
6315
+ * arguments validate.
6316
+ *
6317
+ * This is the second half of the double gate described in the header.
6318
+ * qwen_xml candidates get one retry with per-parameter JSON coercion, since
6319
+ * XML parameter values always arrive as strings.
6320
+ */
5448
6321
  function validate_candidate(candidate, tool_map) {
5449
6322
  const tool = tool_map.get(candidate.name);
5450
6323
  if (tool === void 0) return void 0;
@@ -5478,12 +6351,24 @@ function validate_candidate(candidate, tool_map) {
5478
6351
  span: candidate.span
5479
6352
  };
5480
6353
  }
6354
+ /**
6355
+ * Remove the accepted calls' spans from the text, back to front so earlier
6356
+ * offsets stay valid, then drop any emptied `<tool_call>` wrappers.
6357
+ */
5481
6358
  function strip_spans(text, spans) {
5482
6359
  let out = text;
5483
6360
  const descending = spans.toSorted((a, b) => b.start - a.start);
5484
6361
  for (const s of descending) out = out.slice(0, s.start) + out.slice(s.end);
5485
6362
  return out.replace(EMPTY_BLOCK_RE, "").trim();
5486
6363
  }
6364
+ /**
6365
+ * Recover tool calls from assistant text, per the header's format rules.
6366
+ *
6367
+ * Runs the three scanners in masking order (blocks, fences, bare JSON),
6368
+ * validates every candidate against the tool registry, and returns the
6369
+ * surviving calls plus the text with their spans stripped. Returns undefined
6370
+ * when nothing survives.
6371
+ */
5487
6372
  function salvage_tool_calls(text, tool_map) {
5488
6373
  if (text.length === 0) return void 0;
5489
6374
  const blocks = scan_tool_call_blocks(text);
@@ -5507,6 +6392,9 @@ function salvage_tool_calls(text, tool_map) {
5507
6392
  }
5508
6393
  //#endregion
5509
6394
  //#region src/engine/tool_loop.ts
6395
+ /**
6396
+ * Throw `aborted_error` (tagged with the step index) if the signal has fired.
6397
+ */
5510
6398
  function throw_if_aborted(abort, step_index) {
5511
6399
  if (!abort.aborted) return;
5512
6400
  throw new aborted_error("aborted", {
@@ -5514,6 +6402,10 @@ function throw_if_aborted(abort, step_index) {
5514
6402
  step_index
5515
6403
  });
5516
6404
  }
6405
+ /**
6406
+ * Like `throw_if_aborted`, but names the tool call that was about to run so
6407
+ * the error shows exactly where the abort landed.
6408
+ */
5517
6409
  function throw_if_aborted_in_flight(abort, step_index, tool_call) {
5518
6410
  if (!abort.aborted) return;
5519
6411
  throw new aborted_error("aborted", {
@@ -5525,6 +6417,9 @@ function throw_if_aborted_in_flight(abort, step_index, tool_call) {
5525
6417
  }
5526
6418
  });
5527
6419
  }
6420
+ /**
6421
+ * Reduce any thrown value to a message string, never throwing itself.
6422
+ */
5528
6423
  function serialize_error(err) {
5529
6424
  if (err instanceof Error) return err.message;
5530
6425
  if (typeof err === "string") return err;
@@ -5534,6 +6429,14 @@ function serialize_error(err) {
5534
6429
  return String(err);
5535
6430
  }
5536
6431
  }
6432
+ /**
6433
+ * Resolve whether a tool call may execute.
6434
+ *
6435
+ * Evaluates `needs_approval` (boolean or async predicate); when approval is
6436
+ * required, records the request event and awaits the handler in a race
6437
+ * against `abort`. A missing handler fails closed with
6438
+ * `tool_approval_denied_error` so approval-gated tools never run silently.
6439
+ */
5537
6440
  async function request_approval(tool, input, step_index, tool_call_id, abort, on_tool_approval, trajectory) {
5538
6441
  const needs_approval = tool.needs_approval;
5539
6442
  if (!(typeof needs_approval === "function" ? await needs_approval(input) : needs_approval === true)) return true;
@@ -5590,6 +6493,9 @@ async function request_approval(tool, input, step_index, tool_call_id, abort, on
5590
6493
  });
5591
6494
  return approved;
5592
6495
  }
6496
+ /**
6497
+ * Emit a `tool_result` stream chunk when streaming is active.
6498
+ */
5593
6499
  async function dispatch_tool_result_chunk(dispatch_chunk, step_index, id, output, error) {
5594
6500
  if (dispatch_chunk === void 0) return;
5595
6501
  const chunk = {
@@ -5601,6 +6507,10 @@ async function dispatch_tool_result_chunk(dispatch_chunk, step_index, id, output
5601
6507
  if (error !== void 0) chunk.error = error;
5602
6508
  await dispatch_chunk(chunk);
5603
6509
  }
6510
+ /**
6511
+ * Build the `role: 'tool'` message that feeds a tool's result back to the
6512
+ * model, JSON-serializing non-string content.
6513
+ */
5604
6514
  function build_tool_result_message(tool_call_id, tool_name, content) {
5605
6515
  return {
5606
6516
  role: "tool",
@@ -5609,6 +6519,10 @@ function build_tool_result_message(tool_call_id, tool_name, content) {
5609
6519
  content: typeof content === "string" ? content : safe_json_stringify(content)
5610
6520
  };
5611
6521
  }
6522
+ /**
6523
+ * JSON-stringify with a `String(value)` fallback for circular references and
6524
+ * other values `JSON.stringify` rejects.
6525
+ */
5612
6526
  function safe_json_stringify(value) {
5613
6527
  try {
5614
6528
  return JSON.stringify(value) ?? String(value);
@@ -5616,6 +6530,10 @@ function safe_json_stringify(value) {
5616
6530
  return String(value);
5617
6531
  }
5618
6532
  }
6533
+ /**
6534
+ * Build the assistant history message for a turn: plain text when there are
6535
+ * no tool calls, otherwise structured text plus tool_call parts.
6536
+ */
5619
6537
  function build_assistant_message(text, tool_calls) {
5620
6538
  if (tool_calls.length === 0) return {
5621
6539
  role: "assistant",
@@ -5637,6 +6555,12 @@ function build_assistant_message(text, tool_calls) {
5637
6555
  content: parts
5638
6556
  };
5639
6557
  }
6558
+ /**
6559
+ * Derive the step's cost from pricing tables and record it.
6560
+ *
6561
+ * Missing pricing for a paid provider emits `pricing_missing` (deduped per
6562
+ * call) and yields no breakdown; free providers skip the emit entirely.
6563
+ */
5640
6564
  function compute_and_record_cost(config, step_index, usage) {
5641
6565
  const pricing = config.resolve_pricing();
5642
6566
  if (pricing === void 0 && !FREE_PROVIDERS.has(config.provider)) {
@@ -5647,6 +6571,10 @@ function compute_and_record_cost(config, step_index, usage) {
5647
6571
  if (breakdown !== void 0) record_cost(config.trajectory, step_index, breakdown, "engine_derived");
5648
6572
  return breakdown;
5649
6573
  }
6574
+ /**
6575
+ * Validate a raw tool-call input against the tool's zod schema before
6576
+ * execution, returning the parsed value or a feedback-ready error message.
6577
+ */
5650
6578
  function validate_tool_input(tool, input) {
5651
6579
  const parsed = tool.input_schema.safeParse(input);
5652
6580
  if (parsed.success) return {
@@ -5659,13 +6587,13 @@ function validate_tool_input(tool, input) {
5659
6587
  };
5660
6588
  }
5661
6589
  /**
5662
- * Apply the prepare_step hook (D6) for one turn. Returns the messages to send
5663
- * to the transport: the hook's replacement when it returns `{ messages }`, else
5664
- * config.messages unchanged. The replacement is ephemeral — it is fed ONLY to
6590
+ * Apply the prepare_step hook for one turn. Returns the messages to send to
6591
+ * the transport: the hook's replacement when it returns `{ messages }`, else
6592
+ * config.messages unchanged. The replacement is ephemeral; it is fed ONLY to
5665
6593
  * invoke_once for this turn, never pushed onto config.messages, so the loop's
5666
6594
  * salvage/approval/ends_turn/schema-repair machinery keeps reading the real
5667
- * transcript. A step_prepared event (recorded inline, as request_sent is) makes
5668
- * the mid-loop mutation legible with the before/after message counts.
6595
+ * transcript. A step_prepared event (recorded inline, as request_sent is)
6596
+ * makes the mid-loop mutation legible with the before/after message counts.
5669
6597
  */
5670
6598
  async function apply_prepare_step(config, step_index) {
5671
6599
  if (config.prepare_step === void 0) return config.messages;
@@ -5682,6 +6610,14 @@ async function apply_prepare_step(config, step_index) {
5682
6610
  });
5683
6611
  return replacement;
5684
6612
  }
6613
+ /**
6614
+ * Run the model-turn / tool-execution loop to completion.
6615
+ *
6616
+ * Each iteration invokes the transport seam once, salvages text-embedded
6617
+ * tool calls when eligible, clamps to `max_tool_calls_per_step`, executes
6618
+ * calls sequentially under the header invariants, and feeds results back
6619
+ * until the model stops, a terminal tool fires, or `max_steps` is reached.
6620
+ */
5685
6621
  async function run_tool_loop(config) {
5686
6622
  const steps = [];
5687
6623
  const tool_calls_all = [];
@@ -6081,6 +7017,10 @@ async function run_tool_loop(config) {
6081
7017
  }
6082
7018
  //#endregion
6083
7019
  //#region src/engine/providers/ai_sdk/telemetry.ts
7020
+ /**
7021
+ * Build the AI SDK's `experimental_telemetry` option from engine settings,
7022
+ * loading the `@ai-sdk/otel` peer only when telemetry is enabled.
7023
+ */
6084
7024
  async function build_ai_sdk_telemetry(settings) {
6085
7025
  if (!settings?.enabled) return void 0;
6086
7026
  const out = {
@@ -6098,16 +7038,18 @@ async function build_ai_sdk_telemetry(settings) {
6098
7038
  /**
6099
7039
  * The ai_sdk transport: the engine's only Vercel AI SDK call site.
6100
7040
  *
6101
- * Invariant 13 (constraints §7, inverted): only this module imports from `ai`
6102
- * or invokes generateText / streamText. generate.ts drives this transport
6103
- * through create_ai_sdk_turn and stays SDK-agnostic; run_tool_loop sees the
6104
- * same neutral TurnResult a native adapter produces. Rule-enforced by
6105
- * rules/no-ai-import-outside-ai-sdk-provider.yml.
7041
+ * Only this module imports from `ai` or invokes generateText / streamText.
7042
+ * generate.ts drives this transport through create_ai_sdk_turn and stays
7043
+ * SDK-agnostic; run_tool_loop sees the same neutral TurnResult a native
7044
+ * adapter produces. Enforced by rules/no-ai-import-outside-ai-sdk-provider.yml.
6106
7045
  *
6107
- * Retry stays out of this module on purpose (D5): generate.ts wraps the turn
7046
+ * Retry stays out of this module on purpose: generate.ts wraps the turn
6108
7047
  * returned here in the engine-owned retry_turn, exactly as it wraps a native
6109
7048
  * adapter's invoke_turn. This module owns request/response mapping only.
6110
7049
  */
7050
+ /**
7051
+ * Map the AI SDK's finish reason string to the engine's FinishReason.
7052
+ */
6111
7053
  function map_finish_reason(raw) {
6112
7054
  switch (raw) {
6113
7055
  case "stop": return "stop";
@@ -6119,6 +7061,11 @@ function map_finish_reason(raw) {
6119
7061
  default: return "stop";
6120
7062
  }
6121
7063
  }
7064
+ /**
7065
+ * Extract the usage fields `default_normalize_usage` understands from an AI
7066
+ * SDK usage object, tolerating both the SDK's camelCase shape and the
7067
+ * flattened snake_case fields some provider mocks return directly.
7068
+ */
6122
7069
  function to_raw_provider_usage(usage) {
6123
7070
  if (usage === null || typeof usage !== "object") return {};
6124
7071
  const raw = {};
@@ -6152,6 +7099,9 @@ function to_raw_provider_usage(usage) {
6152
7099
  if (raw.output_tokens === void 0 && typeof output_flat === "number") raw.output_tokens = output_flat;
6153
7100
  return raw;
6154
7101
  }
7102
+ /**
7103
+ * Map fascicle's Message[] to the AI SDK's ModelMessage[] shape.
7104
+ */
6155
7105
  function to_sdk_messages(messages) {
6156
7106
  const out = [];
6157
7107
  for (const m of messages) {
@@ -6262,6 +7212,12 @@ function split_leading_system(messages) {
6262
7212
  messages: rest
6263
7213
  };
6264
7214
  }
7215
+ /**
7216
+ * Map fascicle's Tool[] to the AI SDK's ToolSet.
7217
+ *
7218
+ * Returns undefined for an empty tool list so the caller can omit `tools`
7219
+ * from the call params entirely instead of passing an empty object.
7220
+ */
6265
7221
  function to_sdk_tools(tools) {
6266
7222
  if (tools.length === 0) return void 0;
6267
7223
  const entries = {};
@@ -6271,6 +7227,10 @@ function to_sdk_tools(tools) {
6271
7227
  });
6272
7228
  return entries;
6273
7229
  }
7230
+ /**
7231
+ * Map one AI SDK stream part to the engine's StreamChunk shape, or undefined
7232
+ * for a part kind the engine does not model.
7233
+ */
6274
7234
  function map_stream_part_to_chunk(part, step_index) {
6275
7235
  switch (part.type) {
6276
7236
  case "text-delta": return {
@@ -6310,9 +7270,17 @@ function map_stream_part_to_chunk(part, step_index) {
6310
7270
  default: return;
6311
7271
  }
6312
7272
  }
7273
+ /**
7274
+ * Normalize a raw AI SDK usage object into UsageTotals for a streamed
7275
+ * step_finish chunk.
7276
+ */
6313
7277
  function default_usage_from_sdk(usage) {
6314
7278
  return default_normalize_usage(to_raw_provider_usage(usage));
6315
7279
  }
7280
+ /**
7281
+ * Run one streamText call, dispatching StreamChunks as parts arrive and
7282
+ * accumulating them into a TurnResult once the stream completes.
7283
+ */
6316
7284
  async function collect_stream(params, step_index, dispatcher, on_first_chunk, internal_controller, adapter) {
6317
7285
  const stream_result = streamText(params);
6318
7286
  let text = "";
@@ -6353,6 +7321,11 @@ async function collect_stream(params, step_index, dispatcher, on_first_chunk, in
6353
7321
  usage: adapter.normalize_usage(raw_usage)
6354
7322
  };
6355
7323
  }
7324
+ /**
7325
+ * Run one generateText call and map its result into a TurnResult, recovering
7326
+ * a schema-validation failure from the SDK via recover_no_object_generated
7327
+ * instead of letting it throw.
7328
+ */
6356
7329
  async function collect_non_stream(params, adapter) {
6357
7330
  let result;
6358
7331
  try {
@@ -6460,6 +7433,15 @@ function create_ai_sdk_turn(cfg) {
6460
7433
  }
6461
7434
  //#endregion
6462
7435
  //#region src/engine/generate.ts
7436
+ /**
7437
+ * Build the initial message list for a generate call from `opts.system` and
7438
+ * `opts.prompt`.
7439
+ *
7440
+ * A non-empty string `system` is prepended as a system message. A string
7441
+ * `prompt` becomes a single user message; a `Message[]` prompt is copied
7442
+ * through element-by-element so the returned array can be mutated without
7443
+ * affecting the caller's.
7444
+ */
6463
7445
  function build_initial_messages(opts) {
6464
7446
  const messages = [];
6465
7447
  if (typeof opts.system === "string" && opts.system.length > 0) messages.push({
@@ -6500,6 +7482,17 @@ function split_leading_system_messages(messages) {
6500
7482
  messages: rest
6501
7483
  };
6502
7484
  }
7485
+ /**
7486
+ * Classify a thrown provider error into the shape `retry_with_policy`
7487
+ * understands.
7488
+ *
7489
+ * Passes through anything that already carries a recognized `kind`.
7490
+ * Otherwise inspects `statusCode`/`status`: 429 becomes `rate_limit`
7491
+ * (reading `Retry-After` off `responseHeaders` when present), 5xx becomes
7492
+ * `provider_5xx`, and a known `ECONNRESET`/`ETIMEDOUT`/`ENOTFOUND`/
7493
+ * `ECONNREFUSED` error code becomes `network`. Anything else passes through
7494
+ * unclassified, which `retry_with_policy` treats as non-retryable.
7495
+ */
6503
7496
  function classify_provider_error(err) {
6504
7497
  if (err === null || typeof err !== "object") return err;
6505
7498
  const existing_kind = Reflect.get(err, "kind");
@@ -6542,14 +7535,14 @@ function classify_provider_error(err) {
6542
7535
  return err;
6543
7536
  }
6544
7537
  /**
6545
- * Compose the per-attempt turn signal (D5): the user's abort OR'd with a fresh
6546
- * `turn_timeout_ms` deadline via AbortSignal.any (the src/core/timeout.ts
6547
- * precedent). `timed_out()` distinguishes an expiry (retryable) from a user
6548
- * abort (terminal) in the retry_turn ladder; `dispose()` clears the timer so a
6549
- * settled attempt never leaves one armed. With no budget the user's abort
6550
- * passes through untouched, so the un-timed path stays byte-for-byte as before.
6551
- * Armed fresh inside retry_with_policy's callback so each retry gets its own
6552
- * full budget rather than sharing one deadline across attempts.
7538
+ * Compose the per-attempt turn signal: the user's abort OR'd with a fresh
7539
+ * `turn_timeout_ms` deadline via `AbortSignal.any` (the same pattern
7540
+ * `src/core/timeout.ts` uses). `timed_out()` distinguishes an expiry
7541
+ * (retryable) from a user abort (terminal) in the `retry_turn` ladder;
7542
+ * `dispose()` clears the timer so a settled attempt never leaves one armed.
7543
+ * With no budget configured, the user's abort signal passes through
7544
+ * unchanged. Armed fresh inside `retry_with_policy`'s callback so each retry
7545
+ * gets its own full budget rather than sharing one deadline across attempts.
6553
7546
  */
6554
7547
  function arm_turn_timeout(user_abort, turn_timeout_ms) {
6555
7548
  if (turn_timeout_ms === void 0) return {
@@ -6573,8 +7566,8 @@ function arm_turn_timeout(user_abort, turn_timeout_ms) {
6573
7566
  };
6574
7567
  }
6575
7568
  /**
6576
- * Engine-owned wrapper shared verbatim by both depth-1 transports: one turn
6577
- * attempt inside retry_with_policy. The catch ladder classifies by CAUSE, not
7569
+ * Engine-owned wrapper shared by both transports: one turn attempt inside
7570
+ * retry_with_policy. The catch ladder classifies by CAUSE, not
6578
7571
  * by the shape the transport happened to throw: on_chunk_error passes through,
6579
7572
  * then a genuine user abort wins, then any error once a chunk has flowed is a
6580
7573
  * non-retryable stream interruption, then a pre-chunk `turn_timeout_ms` expiry
@@ -6584,8 +7577,9 @@ function arm_turn_timeout(user_abort, turn_timeout_ms) {
6584
7577
  * aborted_error and the native one as a raw AbortError, so both must be read as
6585
7578
  * the same interruption rather than the ai_sdk timeout masquerading as a user
6586
7579
  * cancel. call_once receives the composed abort+timeout signal so the deadline
6587
- * actually cancels the in-flight request. Adapters may swap `classify`, never
6588
- * the ladder (D5: the engine owns retry; hidden adapter retries are illegible).
7580
+ * actually cancels the in-flight request. Adapters may swap `classify`, but
7581
+ * never the ladder itself: the engine owns retry, so a hidden adapter-level
7582
+ * retry would be invisible to anything relying on this ladder.
6589
7583
  */
6590
7584
  function retry_turn(call_once, args, has_streamed, retry_policy, classify, turn_timeout_ms) {
6591
7585
  return retry_with_policy(async () => {
@@ -6683,6 +7677,21 @@ function build_native_invoke(cfg) {
6683
7677
  return await retry_turn(call_once, args, () => chunks_started, cfg.retry_policy, classify, cfg.turn_timeout_ms);
6684
7678
  };
6685
7679
  }
7680
+ /**
7681
+ * Resolve a `generate` call's options against engine defaults, run the tool
7682
+ * loop, and return the aggregated result.
7683
+ *
7684
+ * A provider whose adapter is `external` (`adapter.kind === 'external'`)
7685
+ * delegates the whole call to `adapter.generate` before any of the logic
7686
+ * below runs. For `ai_sdk` and native adapters, this function resolves
7687
+ * model, provider, system prompt, and `provider_options` against engine
7688
+ * defaults, checks the adapter supports every capability the call actually
7689
+ * uses (schema, tools, streaming), builds the `InvokeOnce` closure for the
7690
+ * resolved transport, and drives it through `run_tool_loop`. When a schema
7691
+ * is set and the model's output fails validation, it appends a repair
7692
+ * message and re-invokes the loop, until the response parses, repair
7693
+ * attempts run out, or `max_steps` is reached.
7694
+ */
6686
7695
  async function generate(opts_in, engine) {
6687
7696
  if (opts_in.abort?.aborted === true) throw new aborted_error("aborted", { reason: opts_in.abort.reason });
6688
7697
  const resolved_model = opts_in.model ?? engine.default_model;
@@ -6876,9 +7885,22 @@ async function generate(opts_in, engine) {
6876
7885
  throw err;
6877
7886
  }
6878
7887
  }
7888
+ /**
7889
+ * Round `v` to 6 decimal places, the resolution used for the USD cost fields.
7890
+ */
6879
7891
  function round6(v) {
6880
7892
  return Math.round(v * 1e6) / 1e6;
6881
7893
  }
7894
+ /**
7895
+ * Sum per-step cost breakdowns into a single `CostBreakdown` for the whole
7896
+ * generate call.
7897
+ *
7898
+ * Returns `undefined` if no step reports a cost, unless `provider` is free
7899
+ * (`FREE_PROVIDERS`) and at least one step ran; in that case it returns an
7900
+ * explicit all-zero breakdown instead of omitting cost entirely. The
7901
+ * optional fields (`cached_input_usd`, `cache_write_usd`, `reasoning_usd`)
7902
+ * are included only when at least one step reported them.
7903
+ */
6882
7904
  function aggregate_cost(steps, provider) {
6883
7905
  let any_present = false;
6884
7906
  let total = 0;
@@ -6933,6 +7955,16 @@ function aggregate_cost(steps, provider) {
6933
7955
  }
6934
7956
  //#endregion
6935
7957
  //#region src/engine/create_engine.ts
7958
+ /**
7959
+ * Build the provider-name to adapter map from `providers`, resolving each
7960
+ * name to a `custom_providers` factory when one is supplied, or the built-in
7961
+ * registry factory otherwise.
7962
+ *
7963
+ * Each factory validates its init value synchronously, so a bad credential
7964
+ * throws here at construction time rather than later; loading the
7965
+ * underlying SDK is deferred until the first `generate` call. Throws if
7966
+ * `custom_providers` tries to shadow a built-in provider name.
7967
+ */
6936
7968
  function build_provider_adapters(providers, custom_providers) {
6937
7969
  if (custom_providers !== void 0) {
6938
7970
  const builtins = new Set(list_builtin_providers());
@@ -6946,6 +7978,13 @@ function build_provider_adapters(providers, custom_providers) {
6946
7978
  }
6947
7979
  return adapters;
6948
7980
  }
7981
+ /**
7982
+ * Validate `config` and construct an `Engine`.
7983
+ *
7984
+ * Provider entries are validated synchronously via `build_provider_adapters`.
7985
+ * A `generate` call that names a provider absent from `config.providers`
7986
+ * still throws `provider_not_configured_error`, but only at call time.
7987
+ */
6949
7988
  function create_engine(config) {
6950
7989
  if (config.providers === null || typeof config.providers !== "object") throw new engine_config_error("EngineConfig.providers is required");
6951
7990
  const adapters = build_provider_adapters(config.providers, config.custom_providers);
@@ -7018,18 +8057,18 @@ function create_engine(config) {
7018
8057
  //#endregion
7019
8058
  //#region src/model_call.ts
7020
8059
  /**
7021
- * model_call — the single sanctioned bridge between the composition and
8060
+ * model_call: the single sanctioned bridge between the composition and
7022
8061
  * engine layers.
7023
8062
  *
7024
- * This is the only file under packages/fascicle/src/ permitted to import
7025
- * value symbols from both core and engine (enforced by the
7026
- * model-call-is-sole-bridge ast-grep rule in rules/).
8063
+ * This is the only file under `src/` permitted to import value symbols from
8064
+ * both `core` and `engine` (enforced by the model-call-is-sole-bridge
8065
+ * ast-grep rule in `rules/`).
7027
8066
  *
7028
- * The returned Step auto-threads ctx.abort, ctx.trajectory, and — only when
7029
- * run.stream is driving — an on_chunk forwarder into ctx.emit. Callers cannot
7030
- * override these; the composition layer owns cancellation and trajectory
7031
- * plumbing. Cost events flow out via ctx.trajectory per the engine's own
7032
- * emission rules (constraints §5.3).
8067
+ * The returned Step auto-threads ctx.abort, ctx.trajectory, and, only when
8068
+ * run.stream is driving, an on_chunk forwarder that records each chunk as a
8069
+ * `model_chunk` trajectory event. Callers cannot override these: the
8070
+ * composition layer owns cancellation and trajectory plumbing. Cost events
8071
+ * flow out via ctx.trajectory per the engine's own emission rules.
7033
8072
  */
7034
8073
  /**
7035
8074
  * Wrap the run's trajectory so the engine's own spans (engine.generate and its
@@ -7063,6 +8102,12 @@ function engine_trajectory(inner, root_parent) {
7063
8102
  }
7064
8103
  };
7065
8104
  }
8105
+ /**
8106
+ * Derive a short, stable hash from the call's model, provider, system
8107
+ * prompt, and tool/schema shape.
8108
+ *
8109
+ * Used to build a default step id when the caller doesn't supply `cfg.id`.
8110
+ */
7066
8111
  function stable_signature(input) {
7067
8112
  const payload = JSON.stringify({
7068
8113
  model: input.model ?? null,
@@ -7073,6 +8118,14 @@ function stable_signature(input) {
7073
8118
  });
7074
8119
  return createHash("sha256").update(payload).digest("hex").slice(0, 8);
7075
8120
  }
8121
+ /**
8122
+ * Build a `Step` that calls `cfg.engine.generate` with `cfg` translated into
8123
+ * `GenerateOptions`.
8124
+ *
8125
+ * Threads `ctx.abort` and `ctx.trajectory` (nested under the model_call
8126
+ * step's own span) into every call, and, when `run.stream` is driving,
8127
+ * records each chunk as a `model_chunk` trajectory event.
8128
+ */
7076
8129
  function model_call(cfg) {
7077
8130
  const has_tools = Boolean(cfg.tools && cfg.tools.length > 0);
7078
8131
  const has_schema = cfg.schema !== void 0;
@@ -7140,18 +8193,12 @@ function model_call(cfg) {
7140
8193
  //#endregion
7141
8194
  //#region src/forward_standard_env.ts
7142
8195
  /**
7143
- * Returns the standard set of env vars a typical CLI subprocess needs
7144
- * to reach a user's logged-in session: PATH, HOME, SHELL, USER,
7145
- * LOGNAME, LANG, TMPDIR. Values absent from `process.env` are skipped.
8196
+ * Env forwarding allowlist for CLI subprocesses.
7146
8197
  *
7147
8198
  * Useful when passing explicit env to `claude_cli` under api_key mode
7148
- * (oauth mode inherits automatically), or when you want an explicit,
7149
- * minimal allowlist instead of inheriting the full parent env.
7150
- *
7151
- * @example
7152
- * provider_options: {
7153
- * claude_cli: { env: forward_standard_env() },
7154
- * }
8199
+ * (oauth mode inherits the parent env automatically), or whenever an
8200
+ * explicit, minimal allowlist is preferred over inheriting the full parent
8201
+ * env.
7155
8202
  */
7156
8203
  const STANDARD_KEYS = [
7157
8204
  "PATH",
@@ -7162,6 +8209,17 @@ const STANDARD_KEYS = [
7162
8209
  "LANG",
7163
8210
  "TMPDIR"
7164
8211
  ];
8212
+ /**
8213
+ * Return the standard env vars a CLI subprocess needs to reach a user's
8214
+ * logged-in session: PATH, HOME, SHELL, USER, LOGNAME, LANG, TMPDIR.
8215
+ *
8216
+ * Keys absent from `process.env` are skipped.
8217
+ *
8218
+ * @example
8219
+ * provider_options: {
8220
+ * claude_cli: { env: forward_standard_env() },
8221
+ * }
8222
+ */
7165
8223
  function forward_standard_env() {
7166
8224
  const out = {};
7167
8225
  for (const key of STANDARD_KEYS) {
@@ -7172,6 +8230,15 @@ function forward_standard_env() {
7172
8230
  }
7173
8231
  //#endregion
7174
8232
  //#region src/viewer/broadcast.ts
8233
+ /**
8234
+ * Creates a broadcaster: a bounded ring buffer plus subscriber fan-out.
8235
+ *
8236
+ * Each event gets a monotonic `id` so SSE clients can replay from a known
8237
+ * cursor on reconnect (`snapshot_after`). `emit` does not await delivery, so
8238
+ * slow-client backpressure is the subscriber's responsibility. A subscriber
8239
+ * that throws is unsubscribed, and the `on_subscriber_error` callback fires
8240
+ * once with the captured error so the server can log it.
8241
+ */
7175
8242
  function create_broadcaster(options) {
7176
8243
  const max = Math.max(1, options.buffer | 0);
7177
8244
  const ring = [];
@@ -7227,6 +8294,13 @@ function create_broadcaster(options) {
7227
8294
  */
7228
8295
  const SSE_HEARTBEAT_MS = 15e3;
7229
8296
  const STATIC_HTML = resolve(dirname(fileURLToPath(import.meta.url)), "static", "viewer.html");
8297
+ /**
8298
+ * Starts the HTTP server and resolves once it is listening.
8299
+ *
8300
+ * Wires the five routes (static HTML, health, snapshot, SSE, ingest) to a
8301
+ * single request handler and resolves with the bound URL and a `close`
8302
+ * that shuts the socket down.
8303
+ */
7230
8304
  function start_server(options) {
7231
8305
  const { broadcaster, host, port, on_parse_error } = options;
7232
8306
  const handler = (req, res) => {
@@ -7272,10 +8346,20 @@ function start_server(options) {
7272
8346
  });
7273
8347
  });
7274
8348
  }
8349
+ /**
8350
+ * Builds a `"METHOD /path"` route key from a request.
8351
+ *
8352
+ * Falls back to the server's own `host`/`port` when the request has no
8353
+ * `Host` header, so a malformed or missing header never throws inside
8354
+ * `new URL`.
8355
+ */
7275
8356
  function resolve_route(req, host, port) {
7276
8357
  const url = new URL(req.url ?? "/", `http://${req.headers.host ?? `${host}:${port}`}`);
7277
8358
  return `${req.method ?? "GET"} ${url.pathname}`;
7278
8359
  }
8360
+ /**
8361
+ * Closes the HTTP server and resolves once every connection is torn down.
8362
+ */
7279
8363
  function close_server(server) {
7280
8364
  return new Promise((res_ok, res_err) => {
7281
8365
  server.close((err) => {
@@ -7285,11 +8369,17 @@ function close_server(server) {
7285
8369
  server.closeAllConnections?.();
7286
8370
  });
7287
8371
  }
8372
+ /**
8373
+ * Writes a JSON response with the given status code.
8374
+ */
7288
8375
  function send_json(res, status, body) {
7289
8376
  res.statusCode = status;
7290
8377
  res.setHeader("content-type", "application/json");
7291
8378
  res.end(JSON.stringify(body));
7292
8379
  }
8380
+ /**
8381
+ * Streams the bundled `viewer.html` as the response body.
8382
+ */
7293
8383
  function serve_static_html(res) {
7294
8384
  let size;
7295
8385
  try {
@@ -7306,6 +8396,13 @@ function serve_static_html(res) {
7306
8396
  res.setHeader("content-length", String(size));
7307
8397
  createReadStream(STATIC_HTML).pipe(res);
7308
8398
  }
8399
+ /**
8400
+ * Handles `GET /api/events` by turning the connection into an SSE stream.
8401
+ *
8402
+ * Replays whatever the client missed since its `Last-Event-ID` cursor,
8403
+ * subscribes it to the broadcaster for new events, and keeps the
8404
+ * connection alive with a periodic heartbeat comment.
8405
+ */
7309
8406
  function handle_sse(req, res, broadcaster) {
7310
8407
  res.statusCode = 200;
7311
8408
  res.setHeader("content-type", "text/event-stream");
@@ -7331,14 +8428,31 @@ function handle_sse(req, res, broadcaster) {
7331
8428
  req.on("close", close);
7332
8429
  req.on("error", close);
7333
8430
  }
8431
+ /**
8432
+ * Parses the `Last-Event-ID` header into a replay cursor, defaulting to 0.
8433
+ *
8434
+ * Treats a missing header or a non-numeric or non-positive value as "no
8435
+ * cursor", which makes `handle_sse` replay the full ring buffer.
8436
+ */
7334
8437
  function parse_last_event_id(value) {
7335
8438
  if (typeof value !== "string") return 0;
7336
8439
  const n = Number.parseInt(value, 10);
7337
8440
  return Number.isFinite(n) && n > 0 ? n : 0;
7338
8441
  }
8442
+ /**
8443
+ * Writes one SSE `trajectory` event frame to the response stream.
8444
+ */
7339
8445
  function write_event(res, id, event) {
7340
8446
  res.write(`id: ${id}\nevent: trajectory\ndata: ${JSON.stringify(event)}\n\n`);
7341
8447
  }
8448
+ /**
8449
+ * Handles `POST /api/ingest`: parses newline-delimited trajectory events
8450
+ * from the request body and feeds valid ones into the broadcaster.
8451
+ *
8452
+ * Reports how many lines were accepted vs rejected in the response body;
8453
+ * a malformed line is skipped and reported via `on_parse_error`, not
8454
+ * treated as a fatal request error.
8455
+ */
7342
8456
  function handle_ingest(req, res, broadcaster, on_parse_error) {
7343
8457
  let buf = "";
7344
8458
  let accepted = 0;
@@ -7390,7 +8504,7 @@ function handle_ingest(req, res, broadcaster, on_parse_error) {
7390
8504
  * JSONL file tailer.
7391
8505
  *
7392
8506
  * Watches a file for appends and emits one parsed trajectory event per
7393
- * complete line. Handles three pathological cases the spec calls out:
8507
+ * complete line. Handles three pathological cases:
7394
8508
  *
7395
8509
  * - Truncation / rotation: a watcher event whose stat is shorter than the
7396
8510
  * current offset means the file shrunk. Reset offset to 0 and re-stream.
@@ -7399,9 +8513,21 @@ function handle_ingest(req, res, broadcaster, on_parse_error) {
7399
8513
  * - Schema failures: a line that fails `trajectory_event_schema.parse` is
7400
8514
  * dropped and surfaced to `on_parse_error`. The stream keeps going.
7401
8515
  *
7402
- * The watcher is fs.watch-based with a debounced re-read; on platforms where
7403
- * fs.watch is flaky for appends we still catch up because the next tick
7404
- * re-stats and re-reads from the saved offset.
8516
+ * The watcher is fs.watch-based; reads are serialized and change events
8517
+ * that arrive mid-read are coalesced into one extra pass rather than
8518
+ * dropped, so a burst of appends never starts overlapping reads. Each pass
8519
+ * re-stats and re-reads from the saved offset, which also covers platforms
8520
+ * where fs.watch misses some append notifications: the next successful
8521
+ * change event catches the file up regardless.
8522
+ */
8523
+ /**
8524
+ * Starts tailing `path` and returns a handle to stop or drain it.
8525
+ *
8526
+ * Watches the file with `fs.watch` and re-reads from the last known offset
8527
+ * on every change, buffering an incomplete trailing line until the rest
8528
+ * arrives. Overlapping change events are coalesced: a read already in
8529
+ * flight absorbs any events that fire while it runs instead of starting a
8530
+ * second concurrent read.
7405
8531
  */
7406
8532
  function start_tail(options) {
7407
8533
  const { path, on_event, on_parse_error, on_io_error } = options;
@@ -7516,6 +8642,13 @@ function start_tail(options) {
7516
8642
  * handle that can stop both. `start_viewer` only depends on core's wire-format
7517
8643
  * schema; it never reaches into the engine, composites, or any provider.
7518
8644
  */
8645
+ /**
8646
+ * Starts the viewer: brings up the HTTP/SSE server and, if `options.path`
8647
+ * is set, a file tail that feeds the same broadcaster.
8648
+ *
8649
+ * Defaults to `127.0.0.1:4242` with a 1000-event ring buffer. HTTP ingest
8650
+ * and SSE are always available; tailing is opt-in via `path`.
8651
+ */
7519
8652
  async function start_viewer(options = {}) {
7520
8653
  const host = options.host ?? "127.0.0.1";
7521
8654
  const port = options.port ?? 4242;
@@ -7540,6 +8673,12 @@ async function start_viewer(options = {}) {
7540
8673
  });
7541
8674
  return wrap_handle(server, tail, host, port);
7542
8675
  }
8676
+ /**
8677
+ * Combines the server and optional tail into a single `ViewerHandle`.
8678
+ *
8679
+ * `close` stops the tail first, then closes the server, mirroring the
8680
+ * startup order (server first, tail second) in reverse.
8681
+ */
7543
8682
  function wrap_handle(server, tail, host, port) {
7544
8683
  return {
7545
8684
  url: server.url,
@@ -7581,6 +8720,12 @@ Options:
7581
8720
  --no-open do not open the browser
7582
8721
  --help show this message
7583
8722
  `;
8723
+ /**
8724
+ * Parses CLI argv into a validated `CliArgs`, exiting on bad input.
8725
+ *
8726
+ * `--help` prints usage and exits 0. Invalid numeric flags, or a missing
8727
+ * <path> without `--listen`, write to stderr and exit 2.
8728
+ */
7584
8729
  function parse(argv) {
7585
8730
  const { values, positionals } = parseArgs({
7586
8731
  args: [...argv],
@@ -7648,6 +8793,12 @@ function parse(argv) {
7648
8793
  open: !values["no-open"] && (values.open ?? true)
7649
8794
  };
7650
8795
  }
8796
+ /**
8797
+ * Opens `url` in the platform's default browser, best-effort.
8798
+ *
8799
+ * Spawns the platform opener (`open`, `cmd /c start`, or `xdg-open`)
8800
+ * detached and swallows failures; the CLI prints the URL either way.
8801
+ */
7651
8802
  function open_browser(url) {
7652
8803
  const platform = process.platform;
7653
8804
  const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
@@ -7666,6 +8817,14 @@ function open_browser(url) {
7666
8817
  child.unref();
7667
8818
  } catch {}
7668
8819
  }
8820
+ /**
8821
+ * CLI entry point: parses argv, starts the viewer, and wires shutdown.
8822
+ *
8823
+ * Warns but proceeds when the tailed path does not exist yet or when the
8824
+ * bind host is 0.0.0.0 (the dashboard has no auth). Optionally opens the
8825
+ * browser, then installs SIGINT/SIGTERM handlers that close the viewer
8826
+ * before exiting.
8827
+ */
7669
8828
  async function run_viewer_cli(argv) {
7670
8829
  const args = parse(argv);
7671
8830
  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`);
@@ -7699,6 +8858,9 @@ async function run_viewer_cli(argv) {
7699
8858
  shutdown();
7700
8859
  });
7701
8860
  }
8861
+ /**
8862
+ * Renders an unknown thrown value as a human-readable message.
8863
+ */
7702
8864
  function describe_error(err) {
7703
8865
  if (err instanceof Error) return err.message;
7704
8866
  try {