fascicle 0.9.8 → 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/CHANGELOG.md +25 -0
- package/dist/{adapters-Dbx3M8m-.js → adapters-CJnu1687.js} +44 -5
- package/dist/adapters-CJnu1687.js.map +1 -0
- package/dist/adapters.d.ts +26 -1
- package/dist/adapters.js +1 -1
- package/dist/agents.d.ts +10 -2
- package/dist/agents.js +35 -3
- package/dist/agents.js.map +1 -1
- package/dist/{core-CYpxskeT.js → core-DNH8ddMT.js} +340 -45
- package/dist/core-DNH8ddMT.js.map +1 -0
- package/dist/{index-DyjXGal_.d.ts → index-Bfjpd_3o.d.ts} +33 -18
- package/dist/{index-JhJahQNi.d.ts → index-SkPG_Rew.d.ts} +140 -5
- package/dist/index.d.ts +186 -2
- package/dist/index.js +1438 -276
- package/dist/index.js.map +1 -1
- package/dist/mcp.d.ts +28 -2
- package/dist/mcp.js +136 -11
- package/dist/mcp.js.map +1 -1
- package/dist/otel.d.ts +8 -1
- package/dist/otel.js +29 -4
- package/dist/otel.js.map +1 -1
- package/dist/stdio.d.ts +18 -1
- package/dist/stdio.js +53 -2
- package/dist/stdio.js.map +1 -1
- package/dist/ui.d.ts +12 -2
- package/dist/ui.js +39 -2
- package/dist/ui.js.map +1 -1
- package/package.json +10 -7
- package/dist/adapters-Dbx3M8m-.js.map +0 -1
- package/dist/core-CYpxskeT.js.map +0 -1
|
@@ -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
|
|
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
|
|
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.
|
|
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
|
|
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-
|
|
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-
|
|
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-
|
|
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 };
|