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.
@@ -535,7 +535,7 @@ declare namespace __json_default_export {
535
535
  * engine). Adapter packages import types from here; nothing in
536
536
  * this file imports from any adapter.
537
537
  *
538
- * Type aliases and interfaces use PascalCase per constraints.md §2.
538
+ * Type aliases and interfaces use PascalCase, per the naming convention.
539
539
  * Value-level identifiers (field names, function parameter names) remain
540
540
  * snake_case; those are the value contract, not the type contract.
541
541
  */
@@ -599,13 +599,34 @@ type StreamingRunHandle<o> = {
599
599
  readonly events: AsyncIterable<TrajectoryEvent>;
600
600
  readonly result: Promise<o>;
601
601
  };
602
+ /**
603
+ * Execute a flow and resolve with its final output.
604
+ */
602
605
  declare function run_impl<i, o>(flow: Step<i, o>, input: i, options?: RunOptions): Promise<o>;
606
+ /**
607
+ * Execute a flow while exposing its trajectory events as an async iterable.
608
+ */
603
609
  declare function run_stream<i, o>(flow: Step<i, o>, input: i, options?: RunOptions): StreamingRunHandle<o>;
610
+ /**
611
+ * The public entry point for executing a flow.
612
+ *
613
+ * Callable as `run(flow, input, options?)` for a plain result, or
614
+ * `run.stream(flow, input, options?)` for `{ events, result }`. Both share
615
+ * one implementation, so a streamed run and a plain run of the same flow
616
+ * produce identical output.
617
+ */
604
618
  declare const run: typeof run_impl & {
605
619
  stream: typeof run_stream;
606
620
  };
607
621
  //#endregion
608
622
  //#region src/core/step.d.ts
623
+ /**
624
+ * Wrap a plain function as a `Step`, named or anonymous.
625
+ *
626
+ * The named form takes an explicit id (and optional descriptive `meta`); the
627
+ * anonymous form generates an `anon_<n>` id and marks the step so checkpoint
628
+ * rejects it at construction time.
629
+ */
609
630
  declare function step<i, o>(id: string, fn: StepFn<i, o>, meta?: StepMetadata): Step<i, o>;
610
631
  declare function step<i, o>(fn: StepFn<i, o>): Step<i, o>;
611
632
  //#endregion
@@ -633,6 +654,10 @@ type FlowNode = {
633
654
  type DescribeOptions = {
634
655
  readonly strict?: boolean;
635
656
  };
657
+ /**
658
+ * Public entry point: `describe(step)` for text, `describe.json(step)` for
659
+ * the `FlowNode` tree.
660
+ */
636
661
  declare const describe: {
637
662
  <i, o>(root: Step<i, o>, options?: DescribeOptions): string;
638
663
  json: <i, o>(root: Step<i, o>, options?: DescribeOptions) => FlowNode;
@@ -645,6 +670,13 @@ type LastOutput$1<children> = children extends readonly [...unknown[], Step<unkn
645
670
  type SequenceOptions = {
646
671
  readonly name?: string;
647
672
  };
673
+ /**
674
+ * Build a step that chains children, each feeding the next.
675
+ *
676
+ * Validates every element up front so a non-Step (usually a bare function)
677
+ * fails at construction with a pointed message rather than at run time.
678
+ * Checks `ctx.abort` before each child so aborts land on step boundaries.
679
+ */
648
680
  declare function sequence<const children extends readonly AnyStep$2[]>(children: children, options?: SequenceOptions): Step<FirstInput<children>, LastOutput$1<children>>;
649
681
  //#endregion
650
682
  //#region src/core/parallel.d.ts
@@ -654,6 +686,14 @@ type ParallelOutputs<children extends Record<string, AnyStep$1>> = { [k in keyof
654
686
  type ParallelOptions = {
655
687
  readonly name?: string;
656
688
  };
689
+ /**
690
+ * Build a step that runs named children concurrently on the same input.
691
+ *
692
+ * Returns an object keyed by child name. All children settle before any
693
+ * error propagates; a `suspended_error` wins over application errors so a
694
+ * human-approval gate stays resumable instead of being masked by a sibling's
695
+ * failure.
696
+ */
657
697
  declare function parallel<i, children extends Record<string, Step<i, unknown>>>(members: children, options?: ParallelOptions): Step<i, ParallelOutputs<children>>;
658
698
  //#endregion
659
699
  //#region src/core/branch.d.ts
@@ -663,6 +703,13 @@ type BranchConfig<i, o> = {
663
703
  readonly then: Step<i, o>;
664
704
  readonly otherwise: Step<i, o>;
665
705
  };
706
+ /**
707
+ * Build a conditional-routing step.
708
+ *
709
+ * Evaluates `when(input)` at run time and dispatches to `then` or `otherwise`.
710
+ * Both branches appear as children so `describe()` renders the full tree even
711
+ * though only one branch runs.
712
+ */
666
713
  declare function branch<i, o>(config: BranchConfig<i, o>): Step<i, o>;
667
714
  //#endregion
668
715
  //#region src/core/map.d.ts
@@ -672,12 +719,26 @@ type MapConfig<input, item, result> = {
672
719
  readonly do: Step<item, result>;
673
720
  readonly concurrency?: number;
674
721
  };
722
+ /**
723
+ * Build a per-item execution step.
724
+ *
725
+ * Extracts an array via `items(input)`, runs `do` once per element through a
726
+ * bounded worker pool, and returns results in input order. The first item
727
+ * failure stops new work and propagates after in-flight items settle.
728
+ */
675
729
  declare function map<input, item, result>(config: MapConfig<input, item, result>): Step<input, result[]>;
676
730
  //#endregion
677
731
  //#region src/core/pipe.d.ts
678
732
  type PipeOptions = {
679
733
  readonly name?: string;
680
734
  };
735
+ /**
736
+ * Build an output-transforming step around `inner`.
737
+ *
738
+ * The argument checks reject Steps passed where functions belong: `pipe` is
739
+ * not variadic, and the early `TypeError`s point misuse at `step(fn)` or
740
+ * `sequence([...])` instead of failing obscurely at run time.
741
+ */
681
742
  declare function pipe<i, a, b>(inner: Step<i, a>, fn: (value: a) => b | Promise<b>, options?: PipeOptions): Step<i, b>;
682
743
  //#endregion
683
744
  //#region src/core/retry.d.ts
@@ -687,18 +748,38 @@ type RetryConfig = {
687
748
  readonly backoff_ms?: number;
688
749
  readonly on_error?: (err: unknown, attempt: number) => void;
689
750
  };
751
+ /**
752
+ * Build a retrying step around `inner`.
753
+ *
754
+ * Runs `inner` up to `max_attempts` times with exponential backoff between
755
+ * failures. Application errors consume an attempt and fire `on_error`;
756
+ * control-flow signals propagate untouched.
757
+ */
690
758
  declare function retry<i, o>(inner: Step<i, o>, config: RetryConfig): Step<i, o>;
691
759
  //#endregion
692
760
  //#region src/core/fallback.d.ts
693
761
  type FallbackOptions = {
694
762
  readonly name?: string;
695
763
  };
764
+ /**
765
+ * Build a primary-or-backup step.
766
+ *
767
+ * Runs `primary`; on an application error runs `backup` with the same input.
768
+ * Control-flow signals propagate without triggering the backup.
769
+ */
696
770
  declare function fallback<i, o>(primary: Step<i, o>, backup: Step<i, o>, options?: FallbackOptions): Step<i, o>;
697
771
  //#endregion
698
772
  //#region src/core/timeout.d.ts
699
773
  type TimeoutOptions = {
700
774
  readonly name?: string;
701
775
  };
776
+ /**
777
+ * Build a deadline-bounded step around `inner`.
778
+ *
779
+ * Races the inner dispatch against a timer that aborts the composed signal
780
+ * with `timeout_error`. The `timed_out` flag distinguishes timer expiry from
781
+ * a parent abort so the right error propagates.
782
+ */
702
783
  declare function timeout<i, o>(inner: Step<i, o>, ms: number, options?: TimeoutOptions): Step<i, o>;
703
784
  //#endregion
704
785
  //#region src/core/loop.d.ts
@@ -719,9 +800,24 @@ type LoopResult<o> = {
719
800
  readonly converged: boolean;
720
801
  readonly rounds: number;
721
802
  };
803
+ /**
804
+ * Build a bounded iteration step with carry-state.
805
+ *
806
+ * Threads `state` through up to `max_rounds` runs of `body`, lets the
807
+ * optional `guard` stop early, then projects the final state through
808
+ * `finish`. Returns `{ value, converged, rounds }` so callers can tell a
809
+ * converged run from an exhausted one.
810
+ */
722
811
  declare function loop<i, state, o>(config: LoopConfig<i, state, o>): Step<i, LoopResult<o>>;
723
812
  //#endregion
724
813
  //#region src/core/compose.d.ts
814
+ /**
815
+ * Wrap `inner` in a named composite step.
816
+ *
817
+ * The step's `kind` is always `'compose'`; `name` becomes the
818
+ * `display_name` used as the span label. Throws a `TypeError` when `name`
819
+ * is not a non-empty string, catching the mistake at construction time.
820
+ */
725
821
  declare function compose<i, o>(name: string, inner: Step<i, o>): Step<i, o>;
726
822
  //#endregion
727
823
  //#region src/core/checkpoint.d.ts
@@ -729,6 +825,15 @@ type CheckpointConfig<i> = {
729
825
  readonly name?: string;
730
826
  readonly key: string | ((input: i) => string);
731
827
  };
828
+ /**
829
+ * Wrap `inner` with persist-and-resume behavior keyed by `config.key`.
830
+ *
831
+ * `key` is a fixed string or a function of the input. Without a
832
+ * `checkpoint_store` on the run context, the wrapper runs `inner` directly.
833
+ * A stored `null` or `undefined` counts as a miss, so those values are
834
+ * re-computed rather than replayed. Throws at construction time when `inner`
835
+ * is anonymous.
836
+ */
732
837
  declare function checkpoint<i, o>(inner: Step<i, o>, config: CheckpointConfig<i>): Step<i, o>;
733
838
  //#endregion
734
839
  //#region src/core/suspend.d.ts
@@ -739,6 +844,14 @@ type SuspendConfig<i, o, resume> = {
739
844
  readonly resume_schema: z.ZodType<resume>;
740
845
  readonly combine: (input: i, resume: resume, ctx: RunContext) => Promise<o> | o | Step<unknown, o>;
741
846
  };
847
+ /**
848
+ * Build a human-in-the-loop pause step.
849
+ *
850
+ * First run fires the `on` side effect and throws `suspended_error`; a resume
851
+ * run validates `resume_data[id]` against `resume_schema` and feeds it to
852
+ * `combine`. The step's id is the user-supplied suspend id so resume data can
853
+ * be addressed to it.
854
+ */
742
855
  declare function suspend<i, o, resume>(config: SuspendConfig<i, o, resume>): Step<i, o>;
743
856
  //#endregion
744
857
  //#region src/core/scope.d.ts
@@ -753,17 +866,36 @@ type StashOptions = {
753
866
  type UseOptions = {
754
867
  readonly name?: string;
755
868
  };
869
+ /**
870
+ * Build a step that runs children in sequence under a fresh state map.
871
+ *
872
+ * The local map is seeded from the parent state (inner scopes read outer
873
+ * values) and registered so `stash`/`use` inside recognize it; writes stay
874
+ * local to this scope. Outputs chain like `sequence`.
875
+ */
756
876
  declare function scope<const children extends readonly AnyStep[]>(children: children, options?: ScopeOptions): Step<unknown, LastOutput<children>>;
877
+ /**
878
+ * Build a step that stores its source's output in scope state at `key`.
879
+ *
880
+ * Passes the value through unchanged so it composes mid-chain. Throws when
881
+ * run outside a `scope`.
882
+ */
757
883
  declare function stash<i, v>(key: string, source: Step<i, v>, options?: StashOptions): Step<i, v>;
884
+ /**
885
+ * Build a step that projects named scope values into a function call.
886
+ *
887
+ * Reads `keys` from scope state (missing keys project as `undefined`) and
888
+ * invokes `fn(projection, input, ctx)`. Throws when run outside a `scope`.
889
+ */
758
890
  declare function use<const keys extends readonly string[], i, o>(keys: keys, fn: (state: { [k in keys[number]]: unknown }, input: i, ctx: RunContext) => Promise<o> | o, options?: UseOptions): Step<i, o>;
759
891
  //#endregion
760
892
  //#region src/core/errors.d.ts
761
893
  /**
762
894
  * Typed errors for the composition layer.
763
895
  *
764
- * This is the only source file in packages/core/src/ that uses the `class`
896
+ * This is the only source file in the core layer that uses the `class`
765
897
  * keyword. `Error` is a built-in and `instanceof` branching is how composers
766
- * like `retry` and `fallback` distinguish failure modes. See constraints.md §2.
898
+ * like `retry` and `fallback` distinguish failure modes.
767
899
  */
768
900
  declare class timeout_error extends Error {
769
901
  readonly kind: "timeout_error";
@@ -808,7 +940,7 @@ declare class aborted_error extends Error {
808
940
  /**
809
941
  * Closed registry of every `Step.kind` produced by the composition layer.
810
942
  *
811
- * Studio (and any other consumer that needs to enumerate primitives — palette,
943
+ * Studio (and any other consumer that needs to enumerate primitives: palette,
812
944
  * docs, code generation) can rely on this being the exhaustive set. New
813
945
  * primitives must add their kind here. The `step_kinds_cover_runner` contract
814
946
  * test in `step_kinds.test.ts` asserts every dispatch handler corresponds to a
@@ -816,6 +948,9 @@ declare class aborted_error extends Error {
816
948
  */
817
949
  declare const STEP_KINDS: readonly ["step", "sequence", "parallel", "branch", "map", "pipe", "retry", "fallback", "timeout", "loop", "compose", "adversarial", "ensemble", "tournament", "consensus", "checkpoint", "suspend", "scope", "stash", "use"];
818
950
  type StepKind = (typeof STEP_KINDS)[number];
951
+ /**
952
+ * Check whether a value is one of the registered `Step.kind` strings.
953
+ */
819
954
  declare function is_step_kind(value: unknown): value is StepKind;
820
955
  //#endregion
821
956
  //#region src/core/trajectory.d.ts
@@ -853,4 +988,4 @@ type CustomTrajectoryEvent = z.infer<typeof custom_event_schema>;
853
988
  type ParsedTrajectoryEvent = z.infer<typeof trajectory_event_schema>;
854
989
  //#endregion
855
990
  export { fallback as A, describe as B, checkpoint as C, LoopResult as D, LoopGuardResult as E, parallel as F, Step as G, run as H, sequence as I, TrajectoryLogger as J, StepMetadata as K, DescribeOptions as L, pipe as M, map as N, loop as O, branch as P, FlowNode as R, suspend as S, LoopConfig as T, CheckpointStore as U, step as V, RunContext as W, __json_default_export as Y, suspended_error as _, SpanStartEvent as a, stash as b, span_end_event_schema as c, STEP_KINDS as d, StepKind as f, resume_validation_error as g, describe_cycle_error as h, SpanEndEvent as i, retry as j, timeout as k, span_start_event_schema as l, aborted_error as m, EmitEvent as n, custom_event_schema as o, is_step_kind as p, TrajectoryEvent as q, ParsedTrajectoryEvent as r, emit_event_schema as s, CustomTrajectoryEvent as t, trajectory_event_schema as u, timeout_error as v, compose as w, use as x, scope as y, FlowValue as z };
856
- //# sourceMappingURL=index-JhJahQNi.d.ts.map
991
+ //# sourceMappingURL=index-SkPG_Rew.d.ts.map
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { A as fallback, B as describe, C as checkpoint, D as LoopResult, E as LoopGuardResult, F as parallel, G as Step, H as run, I as sequence, J as TrajectoryLogger, K as StepMetadata, L as DescribeOptions, M as pipe, N as map, O as loop, P as branch, R as FlowNode, S as suspend, T as LoopConfig, U as CheckpointStore, V as step, W as RunContext, Y as __json_default_export, _ as suspended_error, a as SpanStartEvent, b as stash, c as span_end_event_schema, d as STEP_KINDS, f as StepKind, g as resume_validation_error, h as describe_cycle_error, i as SpanEndEvent, j as retry, k as timeout, l as span_start_event_schema, m as aborted_error, n as EmitEvent, o as custom_event_schema, p as is_step_kind, q as TrajectoryEvent, r as ParsedTrajectoryEvent, s as emit_event_schema, t as CustomTrajectoryEvent, u as trajectory_event_schema, v as timeout_error, w as compose, x as use, y as scope, z as FlowValue } from "./index-JhJahQNi.js";
2
- import { $ as ProviderFactory, A as PricingTable, B as ToolApprovalRequest, C as GenerateOptions, D as PrepareStepHook, E as PrepareStepContext, F as RetryPolicy, G as UsageTotals, H as ToolExecContext, I as StepRecord, J as EffortTranslation, K as UserContentPart, L as StreamChunk, M as ProviderInit, N as ResolvedModel, O as PrepareStepResult, P as RetryFailureKind, Q as ProviderCapability, R as Tool, S as FinishReason, T as Message, U as TurnRequest, V as ToolCallRecord, W as TurnResult, X as NativeProviderAdapter, Y as ExternalAgentAdapter, Z as ProviderAdapter, _ as CostBreakdown, a as on_chunk_error, b as EngineConfig, c as provider_error, d as schema_validation_error, et as ProviderTransport, f as tool_approval_denied_error, g as AssistantContentPart, h as AiSdkTelemetrySettings, i as model_required_error, j as ProviderConfigMap, k as Pricing, l as provider_not_configured_error, m as create_engine, n as engine_config_error, nt as default_normalize_usage, o as provider_auth_error, p as tool_error, q as AiSdkProviderAdapter, r as engine_disposed_error, s as provider_capability_error, t as claude_cli_error, tt as RawProviderUsage, u as rate_limit_error, v as EffortLevel, w as GenerateResult, x as EngineDefaults, y as Engine, z as ToolApprovalHandler } from "./index-DyjXGal_.js";
1
+ import { A as fallback, B as describe, C as checkpoint, D as LoopResult, E as LoopGuardResult, F as parallel, G as Step, H as run, I as sequence, J as TrajectoryLogger, K as StepMetadata, L as DescribeOptions, M as pipe, N as map, O as loop, P as branch, R as FlowNode, S as suspend, T as LoopConfig, U as CheckpointStore, V as step, W as RunContext, Y as __json_default_export, _ as suspended_error, a as SpanStartEvent, b as stash, c as span_end_event_schema, d as STEP_KINDS, f as StepKind, g as resume_validation_error, h as describe_cycle_error, i as SpanEndEvent, j as retry, k as timeout, l as span_start_event_schema, m as aborted_error, n as EmitEvent, o as custom_event_schema, p as is_step_kind, q as TrajectoryEvent, r as ParsedTrajectoryEvent, s as emit_event_schema, t as CustomTrajectoryEvent, u as trajectory_event_schema, v as timeout_error, w as compose, x as use, y as scope, z as FlowValue } from "./index-SkPG_Rew.js";
2
+ import { $ as ProviderFactory, A as PricingTable, B as ToolApprovalRequest, C as GenerateOptions, D as PrepareStepHook, E as PrepareStepContext, F as RetryPolicy, G as UsageTotals, H as ToolExecContext, I as StepRecord, J as EffortTranslation, K as UserContentPart, L as StreamChunk, M as ProviderInit, N as ResolvedModel, O as PrepareStepResult, P as RetryFailureKind, Q as ProviderCapability, R as Tool, S as FinishReason, T as Message, U as TurnRequest, V as ToolCallRecord, W as TurnResult, X as NativeProviderAdapter, Y as ExternalAgentAdapter, Z as ProviderAdapter, _ as CostBreakdown, a as on_chunk_error, b as EngineConfig, c as provider_error, d as schema_validation_error, et as ProviderTransport, f as tool_approval_denied_error, g as AssistantContentPart, h as AiSdkTelemetrySettings, i as model_required_error, j as ProviderConfigMap, k as Pricing, l as provider_not_configured_error, m as create_engine, n as engine_config_error, nt as default_normalize_usage, o as provider_auth_error, p as tool_error, q as AiSdkProviderAdapter, r as engine_disposed_error, s as provider_capability_error, t as claude_cli_error, tt as RawProviderUsage, u as rate_limit_error, v as EffortLevel, w as GenerateResult, x as EngineDefaults, y as Engine, z as ToolApprovalHandler } from "./index-Bfjpd_3o.js";
3
3
  import { z } from "zod";
4
4
 
5
5
  //#region src/composites/adversarial.d.ts
@@ -23,6 +23,20 @@ type AdversarialConfig<input, candidate> = {
23
23
  readonly accept: (critique_result: AdversarialCritiqueResult) => boolean;
24
24
  readonly max_rounds: number;
25
25
  };
26
+ /**
27
+ * Builds a Step that runs up to `max_rounds` iterations of build ->
28
+ * critique -> accept.
29
+ *
30
+ * Each round builds a candidate (receiving the prior candidate and critique
31
+ * notes when available), critiques it, then checks `accept(critique_result)`.
32
+ * Returns `{ candidate, converged, rounds }`. Does not throw on
33
+ * non-convergence; `converged: false` reports it instead.
34
+ *
35
+ * Implemented as a `compose`d `loop` whose body builds a new candidate and
36
+ * whose guard runs the critique step and checks `accept`. State is threaded
37
+ * through `scope`/`stash`/`use` so the build and critique steps remain
38
+ * unmodified user-supplied `Step` values.
39
+ */
26
40
  declare function adversarial<input, candidate>(config: AdversarialConfig<input, candidate>): Step<input, AdversarialResult<candidate>>;
27
41
  //#endregion
28
42
  //#region src/composites/consensus.d.ts
@@ -36,6 +50,18 @@ type ConsensusResult<o> = {
36
50
  readonly result: Record<string, o>;
37
51
  readonly converged: boolean;
38
52
  };
53
+ /**
54
+ * Builds a Step that runs every member concurrently with the same input
55
+ * until `agree(results)` accepts a round.
56
+ *
57
+ * On agreement, returns the round's results with `converged: true`.
58
+ * Otherwise re-runs all members up to `max_rounds` times and returns the
59
+ * last results with `converged: false` if no agreement is reached.
60
+ *
61
+ * Implemented as a `compose`d `loop` whose body runs `parallel(members)` and
62
+ * whose guard evaluates `agree`. State carries the original input alongside
63
+ * the most recent results so each round receives the same input.
64
+ */
39
65
  declare function consensus<i, o>(config: ConsensusConfig<i, o>): Step<i, ConsensusResult<o>>;
40
66
  //#endregion
41
67
  //#region src/composites/ensemble.d.ts
@@ -49,6 +75,18 @@ type EnsembleResult<o> = {
49
75
  readonly winner: o;
50
76
  readonly scores: Record<string, number>;
51
77
  };
78
+ /**
79
+ * Builds a Step that runs every member concurrently with the same input,
80
+ * scores each result, and returns the winner plus the complete score map.
81
+ *
82
+ * `select` picks the highest (`'max'`, the default) or lowest (`'min'`)
83
+ * score. Tie-breaking is "any tied result is acceptable": the first member
84
+ * (in `members` key order) holding the best score wins.
85
+ *
86
+ * Implemented as a `compose`d `sequence` of `parallel(members)` followed by
87
+ * a single picking step. Cancellation, fan-out, and abort propagation come
88
+ * from `parallel`'s own contract.
89
+ */
52
90
  declare function ensemble<i, o>(config: EnsembleConfig<i, o>): Step<i, EnsembleResult<o>>;
53
91
  //#endregion
54
92
  //#region src/composites/ensemble_step.d.ts
@@ -65,6 +103,25 @@ type EnsembleStepResult<o, ranked> = {
65
103
  readonly winner_scored: ranked;
66
104
  readonly scored: Record<string, ranked>;
67
105
  };
106
+ /**
107
+ * Builds a Step that runs every member concurrently, scores each result via
108
+ * a scoring `Step`, and returns the best-ranking winner.
109
+ *
110
+ * Sibling of `ensemble` for the case where scoring is itself a `Step` (e.g.
111
+ * a separate model call, a sub-flow, anything that wants its own trajectory
112
+ * span and abort routing). The `score` step is dispatched once per member
113
+ * result; `rank_by` projects a number out of the structured scored output;
114
+ * `select` picks the highest (`'max'`, default) or lowest (`'min'`) rank.
115
+ *
116
+ * The result carries `winner_scored`, the structured output from the round's
117
+ * scoring run preserved verbatim, so callers never pay to re-score the
118
+ * winner. `scored` holds the structured score for every member.
119
+ *
120
+ * Implemented as a `compose`d `scope` over (`stash(parallel(members))` ->
121
+ * `to_pairs` -> `map(score per result, threading id)` -> `use` to pick the
122
+ * winner). Cancellation, fan-out, and abort propagation come from the
123
+ * underlying `parallel` and `map` contracts.
124
+ */
68
125
  declare function ensemble_step<i, o, ranked>(config: EnsembleStepConfig<i, o, ranked>): Step<i, EnsembleStepResult<o, ranked>>;
69
126
  //#endregion
70
127
  //#region src/composites/improve.d.ts
@@ -122,6 +179,23 @@ type ImproveResult<c> = {
122
179
  readonly stopped_by: 'budget' | 'plateau';
123
180
  readonly history: ReadonlyArray<HistoryEntry<c>>;
124
181
  };
182
+ /**
183
+ * Builds a Step that runs a round-bounded loop threading a `parent`
184
+ * candidate through repeated propose -> score -> accept/reject cycles.
185
+ *
186
+ * Acceptance requires both a hard gate (`scored.accepted`) and an
187
+ * epsilon-improvement test (`scored.score > parent_score + epsilon`).
188
+ * Rejected rounds with a `reason` feed a bounded lessons list back into the
189
+ * next round's input. Plateau detection stops the loop early when no
190
+ * progress has been made for `patience` rounds; an optional wall-clock
191
+ * budget caps total runtime.
192
+ *
193
+ * Implemented as a `compose`d `scope` of (seed) -> (init state) -> (loop) ->
194
+ * (unwrap). The loop body is itself a small `scope` that snapshots prior
195
+ * state, builds a round input, dispatches the proposers + scorer via
196
+ * `ensemble_step`, and merges the outcome back into state via `use`.
197
+ * State threading is the entire job.
198
+ */
125
199
  declare function improve<i, c>(config: ImproveConfig<i, c>): Step<i, ImproveResult<c>>;
126
200
  //#endregion
127
201
  //#region src/composites/learn.d.ts
@@ -159,6 +233,14 @@ type LearnResult<o> = {
159
233
  readonly events_considered: number;
160
234
  readonly run_ids: ReadonlyArray<string>;
161
235
  };
236
+ /**
237
+ * Build the offline self-improvement step.
238
+ *
239
+ * Composes a scope that resolves and caps the recorded events, builds the
240
+ * `LearnInput` (including `describe(flow)`), runs the user's analyzer, and
241
+ * wraps its proposals with the stashed meta (event count, run ids) into a
242
+ * `LearnResult`.
243
+ */
162
244
  declare function learn<i extends LearnInput, o>(config: LearnConfig<i, o>): Step<unknown, LearnResult<o>>;
163
245
  //#endregion
164
246
  //#region src/composites/tournament.d.ts
@@ -177,6 +259,13 @@ type TournamentResult<o> = {
177
259
  readonly winner: o;
178
260
  readonly bracket: ReadonlyArray<BracketRecord>;
179
261
  };
262
+ /**
263
+ * Build a single-elimination bracket step over named members.
264
+ *
265
+ * All members run concurrently via `parallel`; the bracket step then reduces
266
+ * survivors round by round with `compare`, recording every match. Requires at
267
+ * least one member so a winner always exists.
268
+ */
180
269
  declare function tournament<i, o>(config: TournamentConfig<i, o>): Step<i, TournamentResult<o>>;
181
270
  //#endregion
182
271
  //#region src/composites/bench.d.ts
@@ -227,12 +316,48 @@ type BenchOptions = {
227
316
  readonly run_id?: string;
228
317
  readonly install_signal_handlers?: boolean;
229
318
  };
319
+ /**
320
+ * Runs `flow` against every case, judges each output, and produces a
321
+ * `BenchReport` you can compare against a committed baseline via
322
+ * `regression_compare`.
323
+ *
324
+ * Each case becomes one `run(flow, case.input, ...)`. Per-case observability:
325
+ * - `trajectory_dir` writes `${dir}/${case.id}.jsonl` via `filesystem_logger`
326
+ * - `live_url` POSTs each event via `http_logger` to a viewer's /api/ingest
327
+ * - both can be combined; bench tees them with an internal cost tracker
328
+ *
329
+ * Cost is tracked per-case in-process by intercepting `kind: 'cost'` events
330
+ * on the trajectory pipeline, so the cost number matches what would be on
331
+ * disk even when no `trajectory_dir` is set.
332
+ *
333
+ * Judges run as Steps after each case, with the same trajectory logger so
334
+ * judge spans land in the case's trajectory file (or push). A judge that
335
+ * throws or returns undefined abstains: the entry is omitted from
336
+ * `case.scores` and the case does not contribute to that judge's mean.
337
+ */
230
338
  declare function bench<I, O, S = Score>(flow: Step<I, O>, cases: ReadonlyArray<BenchCase<I>>, judges: Record<string, Judge<I, O, S>>, options?: BenchOptions): Promise<BenchReport<I, O, S>>;
339
+ /**
340
+ * Coerces a raw judge return value into a `Score`.
341
+ *
342
+ * Accepts a bare finite number or an object with a finite numeric `score`
343
+ * and optional string `reason`. Anything else (including NaN/Infinity, or a
344
+ * non-string `reason`, which is dropped) normalizes toward `undefined` or a
345
+ * reason-less score; `undefined` means the judge abstained.
346
+ */
231
347
  declare function normalize_score(raw: unknown): Score | undefined;
232
348
  //#endregion
233
349
  //#region src/composites/judges.d.ts
350
+ /**
351
+ * Judge that scores 1 when the output deep-equals `meta.expected`, 0
352
+ * otherwise. Abstains when the case has no `meta` or no `expected` key.
353
+ */
234
354
  declare function judge_equals<O>(): Judge<unknown, O>;
235
355
  type JudgeWithFn<I, O> = (args: JudgeArgs<I, O>) => number | Score | undefined | Promise<number | Score | undefined>;
356
+ /**
357
+ * Wraps a plain scoring function as a Judge. The function may return a bare
358
+ * number, a `Score`, or `undefined` to abstain; the result is normalized
359
+ * via `normalize_score`.
360
+ */
236
361
  declare function judge_with<I, O>(fn: JudgeWithFn<I, O>): Judge<I, O>;
237
362
  type JudgeLlmConfig = {
238
363
  readonly model: Step<string, string>;
@@ -242,6 +367,14 @@ type JudgeLlmConfig = {
242
367
  readonly max: number;
243
368
  };
244
369
  };
370
+ /**
371
+ * Judge that prompts a model with a rubric and parses the score out of the
372
+ * reply.
373
+ *
374
+ * Built as a three-step sequence: render the rubric prompt, run the
375
+ * caller-supplied model step, parse the JSON score from the reply. An
376
+ * unparseable reply makes the judge abstain rather than fail the case.
377
+ */
245
378
  declare function judge_llm<I, O>(config: JudgeLlmConfig): Judge<I, O>;
246
379
  //#endregion
247
380
  //#region src/composites/regression.d.ts
@@ -269,8 +402,25 @@ type RegressionCompareOptions = {
269
402
  readonly score_threshold?: number;
270
403
  readonly cost_threshold?: number;
271
404
  };
405
+ /**
406
+ * Diff a current `BenchReport` against a baseline.
407
+ *
408
+ * Compares `pass_rate`, each judge's mean score, and total cost, then every
409
+ * individual case. Score metrics regress on any drop beyond
410
+ * `score_threshold` (default 0); cost regresses on a relative increase above
411
+ * `cost_threshold` (default 10%).
412
+ */
272
413
  declare function regression_compare(current: BenchReport, baseline: BenchReport, options?: RegressionCompareOptions): RegressionReport;
414
+ /**
415
+ * Read and validate a baseline `BenchReport` from a JSON file.
416
+ *
417
+ * Validation is structural (required fields present), so a hand-edited or
418
+ * truncated baseline fails loudly with the offending path in the message.
419
+ */
273
420
  declare function read_baseline(path: string): Promise<BenchReport>;
421
+ /**
422
+ * Write a `BenchReport` as pretty-printed JSON, creating parent directories.
423
+ */
274
424
  declare function write_baseline(path: string, report: BenchReport): Promise<void>;
275
425
  //#endregion
276
426
  //#region src/model_call.d.ts
@@ -302,9 +452,28 @@ type ModelCallConfig<T = string> = {
302
452
  readonly max_tool_calls_per_step?: number;
303
453
  readonly on_tool_approval?: ToolApprovalHandler;
304
454
  };
455
+ /**
456
+ * Build a `Step` that calls `cfg.engine.generate` with `cfg` translated into
457
+ * `GenerateOptions`.
458
+ *
459
+ * Threads `ctx.abort` and `ctx.trajectory` (nested under the model_call
460
+ * step's own span) into every call, and, when `run.stream` is driving,
461
+ * records each chunk as a `model_chunk` trajectory event.
462
+ */
305
463
  declare function model_call<T = string>(cfg: ModelCallConfig<T>): Step<ModelCallInput, GenerateResult<T>>;
306
464
  //#endregion
307
465
  //#region src/forward_standard_env.d.ts
466
+ /**
467
+ * Return the standard env vars a CLI subprocess needs to reach a user's
468
+ * logged-in session: PATH, HOME, SHELL, USER, LOGNAME, LANG, TMPDIR.
469
+ *
470
+ * Keys absent from `process.env` are skipped.
471
+ *
472
+ * @example
473
+ * provider_options: {
474
+ * claude_cli: { env: forward_standard_env() },
475
+ * }
476
+ */
308
477
  declare function forward_standard_env(): Record<string, string>;
309
478
  //#endregion
310
479
  //#region src/viewer/start_viewer.d.ts
@@ -330,6 +499,13 @@ type ViewerHandle = {
330
499
  readonly port: number;
331
500
  readonly close: () => Promise<void>;
332
501
  };
502
+ /**
503
+ * Starts the viewer: brings up the HTTP/SSE server and, if `options.path`
504
+ * is set, a file tail that feeds the same broadcaster.
505
+ *
506
+ * Defaults to `127.0.0.1:4242` with a 1000-event ring buffer. HTTP ingest
507
+ * and SSE are always available; tailing is opt-in via `path`.
508
+ */
333
509
  declare function start_viewer(options?: StartViewerOptions): Promise<ViewerHandle>;
334
510
  //#endregion
335
511
  //#region src/viewer/cli.d.ts
@@ -346,6 +522,14 @@ declare function start_viewer(options?: StartViewerOptions): Promise<ViewerHandl
346
522
  * shuts everything down cleanly. The CLI body is exposed as `run_viewer_cli`
347
523
  * so the umbrella's bin shim can drive it from a bundled `dist/index.js`.
348
524
  */
525
+ /**
526
+ * CLI entry point: parses argv, starts the viewer, and wires shutdown.
527
+ *
528
+ * Warns but proceeds when the tailed path does not exist yet or when the
529
+ * bind host is 0.0.0.0 (the dashboard has no auth). Optionally opens the
530
+ * browser, then installs SIGINT/SIGTERM handlers that close the viewer
531
+ * before exiting.
532
+ */
349
533
  declare function run_viewer_cli(argv: readonly string[]): Promise<void>;
350
534
  //#endregion
351
535
  export { type AdversarialBuildInput, type AdversarialConfig, type AdversarialCritiqueResult, type AdversarialResult, type AiSdkProviderAdapter, type AiSdkTelemetrySettings, type AssistantContentPart, type BenchCase, type BenchOptions, type BenchReport, type BenchSummary, type BracketRecord, type Candidate, type CaseResult, type CheckpointStore, type ConsensusConfig, type ConsensusResult, type CostBreakdown, type CustomTrajectoryEvent, type DescribeOptions, type EffortLevel, type EffortTranslation, type EmitEvent, type Engine, type EngineConfig, type EngineDefaults, type EnsembleConfig, type EnsembleResult, type EnsembleStepConfig, type EnsembleStepResult, type ExternalAgentAdapter, type FinishReason, type FlowNode, type FlowValue, type GenerateOptions, type GenerateResult, type HistoryEntry, type ImproveBudget, type ImproveConfig, type ImproveResult, type ImproveRoundInput, type Improvement, type Judge, type JudgeArgs, type JudgeLlmConfig, type JudgeWithFn, type LearnConfig, type LearnInput, type LearnResult, type Lesson, type LoopConfig, type LoopGuardResult, type LoopResult, type Message, type ModelCallConfig, type ModelCallInput, type NativeProviderAdapter, type ParsedTrajectoryEvent, type PerCaseDelta, type PrepareStepContext, type PrepareStepHook, type PrepareStepResult, type Pricing, type PricingTable, type ProviderAdapter, type ProviderCapability, type ProviderConfigMap, type ProviderFactory, type ProviderInit, type ProviderTransport, type RawProviderUsage, type RegressionCompareOptions, type RegressionDelta, type RegressionReport, type ResolvedModel, type RetryFailureKind, type RetryPolicy, type RunContext, STEP_KINDS, type Score, type ScoredCandidate, type SpanEndEvent, type SpanStartEvent, type StartViewerOptions, type Step, type StepKind, type StepMetadata, type StepRecord, type StreamChunk, type Tool, type ToolApprovalHandler, type ToolApprovalRequest, type ToolCallRecord, type ToolExecContext, type TournamentConfig, type TournamentResult, type TrajectoryEvent, type TrajectoryLogger, type TrajectorySource, type TurnRequest, type TurnResult, type UsageTotals, type UserContentPart, type ViewerHandle, aborted_error, adversarial, bench, branch, checkpoint, claude_cli_error, compose, consensus, create_engine, custom_event_schema, default_normalize_usage, describe, describe_cycle_error, emit_event_schema, engine_config_error, engine_disposed_error, ensemble, ensemble_step, fallback, __json_default_export as flow_schema, forward_standard_env, improve, is_step_kind, judge_equals, judge_llm, judge_with, learn, loop, map, model_call, model_required_error, normalize_score, on_chunk_error, parallel, pipe, provider_auth_error, provider_capability_error, provider_error, provider_not_configured_error, rate_limit_error, read_baseline, regression_compare, resume_validation_error, retry, run, run_viewer_cli, schema_validation_error, scope, sequence, span_end_event_schema, span_start_event_schema, start_viewer, stash, step, suspend, suspended_error, timeout, timeout_error, tool_approval_denied_error, tool_error, tournament, trajectory_event_schema, use, write_baseline };