fascicle 0.11.0 → 0.12.0

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.d.ts CHANGED
@@ -1,6 +1,6 @@
1
- import { a as StepMetadata, i as StepFn, n as RunContext, o as TrajectoryEvent, r as Step, s as TrajectoryLogger, t as CheckpointStore } from "./types-BDSbSUAO.js";
1
+ import { a as StepFn, c as TrajectoryLogger, i as Step, n as CheckpointStore, o as StepMetadata, r as RunContext, s as TrajectoryEvent, t as AnyStep } from "./types-CVdTBXE_.js";
2
2
  import { n as SchemaIssue, r as ToolSchema, t as AnySchema } from "./types-BCtKsxrX.js";
3
- import { A as TurnResult, B as ProviderTransport, C as StreamChunk, D as ToolCallRecord, E as ToolApprovalRequest, F as ExternalAgentAdapter, H as default_normalize_usage, I as NativeProviderAdapter, L as ProviderAdapter, M as UserContentPart, N as AiSdkProviderAdapter, O as ToolExecContext, P as EffortTranslation, R as ProviderCapability, S as StepRecord, T as ToolApprovalHandler, V as RawProviderUsage, _ as ProviderConfigMap, a as Engine, b as RetryFailureKind, c as FinishReason, d as Message, f as PrepareStepContext, g as PricingTable, h as Pricing, i as EffortLevel, j as UsageTotals, k as TurnRequest, l as GenerateOptions, m as PrepareStepResult, n as AssistantContentPart, o as EngineConfig, p as PrepareStepHook, r as CostBreakdown, s as EngineDefaults, t as AiSdkTelemetrySettings, u as GenerateResult, v as ProviderInit, w as Tool, x as RetryPolicy, y as ResolvedModel, z as ProviderFactory } from "./types-B3HIsBBD.js";
3
+ import { A as TurnResult, B as ProviderTransport, C as StreamChunk, D as ToolCallRecord, E as ToolApprovalRequest, F as ExternalAgentAdapter, H as default_normalize_usage, I as NativeProviderAdapter, L as ProviderAdapter, M as UserContentPart, N as AiSdkProviderAdapter, O as ToolExecContext, P as EffortTranslation, R as ProviderCapability, S as StepRecord, T as ToolApprovalHandler, V as RawProviderUsage, _ as ProviderConfigMap, a as Engine, b as RetryFailureKind, c as FinishReason, d as Message, f as PrepareStepContext, g as PricingTable, h as Pricing, i as EffortLevel, j as UsageTotals, k as TurnRequest, l as GenerateOptions, m as PrepareStepResult, n as AssistantContentPart, o as EngineConfig, p as PrepareStepHook, r as CostBreakdown, s as EngineDefaults, t as AiSdkTelemetrySettings, u as GenerateResult, v as ProviderInit, w as Tool, x as RetryPolicy, y as ResolvedModel, z as ProviderFactory } from "./types-4l54cexm.js";
4
4
 
5
5
  //#region src/core/flow-schema.json.d.ts
6
6
  declare let $schema: string;
@@ -105,6 +105,10 @@ declare namespace $defs {
105
105
  let $ref_18: string;
106
106
  export { $ref_18 as $ref };
107
107
  }
108
+ namespace chain {
109
+ let $ref_19: string;
110
+ export { $ref_19 as $ref };
111
+ }
108
112
  namespace ref {
109
113
  let type_4: string;
110
114
  export { type_4 as type };
@@ -133,8 +137,8 @@ declare namespace $defs {
133
137
  let type_8: string;
134
138
  export { type_8 as type };
135
139
  export namespace items_1 {
136
- let $ref_19: string;
137
- export { $ref_19 as $ref };
140
+ let $ref_20: string;
141
+ export { $ref_20 as $ref };
138
142
  }
139
143
  export { items_1 as items };
140
144
  }
@@ -142,8 +146,8 @@ declare namespace $defs {
142
146
  let type_9: string;
143
147
  export { type_9 as type };
144
148
  export namespace additionalProperties {
145
- let $ref_20: string;
146
- export { $ref_20 as $ref };
149
+ let $ref_21: string;
150
+ export { $ref_21 as $ref };
147
151
  }
148
152
  }
149
153
  namespace branch_config {
@@ -157,13 +161,13 @@ declare namespace $defs {
157
161
  export { type_11 as type };
158
162
  }
159
163
  namespace then {
160
- let $ref_21: string;
161
- export { $ref_21 as $ref };
162
- }
163
- namespace otherwise {
164
164
  let $ref_22: string;
165
165
  export { $ref_22 as $ref };
166
166
  }
167
+ namespace otherwise {
168
+ let $ref_23: string;
169
+ export { $ref_23 as $ref };
170
+ }
167
171
  }
168
172
  export { properties_3 as properties };
169
173
  }
@@ -179,8 +183,8 @@ declare namespace $defs {
179
183
  }
180
184
  export { items_2 as items };
181
185
  export namespace _do {
182
- let $ref_23: string;
183
- export { $ref_23 as $ref };
186
+ let $ref_24: string;
187
+ export { $ref_24 as $ref };
184
188
  }
185
189
  export { _do as do };
186
190
  export namespace concurrency {
@@ -198,8 +202,8 @@ declare namespace $defs {
198
202
  export { required_4 as required };
199
203
  export namespace properties_5 {
200
204
  export namespace of {
201
- let $ref_24: string;
202
- export { $ref_24 as $ref };
205
+ let $ref_25: string;
206
+ export { $ref_25 as $ref };
203
207
  }
204
208
  export namespace fn_1 {
205
209
  let type_16: string;
@@ -216,8 +220,8 @@ declare namespace $defs {
216
220
  export { required_5 as required };
217
221
  export namespace properties_6 {
218
222
  export namespace _do_1 {
219
- let $ref_25: string;
220
- export { $ref_25 as $ref };
223
+ let $ref_26: string;
224
+ export { $ref_26 as $ref };
221
225
  }
222
226
  export { _do_1 as do };
223
227
  export namespace max_attempts {
@@ -242,13 +246,13 @@ declare namespace $defs {
242
246
  export { required_6 as required };
243
247
  export namespace properties_7 {
244
248
  namespace primary {
245
- let $ref_26: string;
246
- export { $ref_26 as $ref };
247
- }
248
- namespace backup {
249
249
  let $ref_27: string;
250
250
  export { $ref_27 as $ref };
251
251
  }
252
+ namespace backup {
253
+ let $ref_28: string;
254
+ export { $ref_28 as $ref };
255
+ }
252
256
  }
253
257
  export { properties_7 as properties };
254
258
  }
@@ -259,8 +263,8 @@ declare namespace $defs {
259
263
  export { required_7 as required };
260
264
  export namespace properties_8 {
261
265
  export namespace _do_2 {
262
- let $ref_28: string;
263
- export { $ref_28 as $ref };
266
+ let $ref_29: string;
267
+ export { $ref_29 as $ref };
264
268
  }
265
269
  export { _do_2 as do };
266
270
  export namespace ms {
@@ -284,8 +288,8 @@ declare namespace $defs {
284
288
  export let minLength: number;
285
289
  }
286
290
  export namespace _do_3 {
287
- let $ref_29: string;
288
- export { $ref_29 as $ref };
291
+ let $ref_30: string;
292
+ export { $ref_30 as $ref };
289
293
  }
290
294
  export { _do_3 as do };
291
295
  }
@@ -309,13 +313,13 @@ declare namespace $defs {
309
313
  export { type_27 as type };
310
314
  }
311
315
  export namespace body {
312
- let $ref_30: string;
313
- export { $ref_30 as $ref };
314
- }
315
- export namespace guard {
316
316
  let $ref_31: string;
317
317
  export { $ref_31 as $ref };
318
318
  }
319
+ export namespace guard {
320
+ let $ref_32: string;
321
+ export { $ref_32 as $ref };
322
+ }
319
323
  export namespace finish {
320
324
  let type_28: string;
321
325
  export { type_28 as type };
@@ -336,13 +340,13 @@ declare namespace $defs {
336
340
  export { required_10 as required };
337
341
  export namespace properties_11 {
338
342
  export namespace build {
339
- let $ref_32: string;
340
- export { $ref_32 as $ref };
341
- }
342
- export namespace critique {
343
343
  let $ref_33: string;
344
344
  export { $ref_33 as $ref };
345
345
  }
346
+ export namespace critique {
347
+ let $ref_34: string;
348
+ export { $ref_34 as $ref };
349
+ }
346
350
  export namespace accept {
347
351
  let type_31: string;
348
352
  export { type_31 as type };
@@ -367,8 +371,8 @@ declare namespace $defs {
367
371
  let type_34: string;
368
372
  export { type_34 as type };
369
373
  export namespace additionalProperties_1 {
370
- let $ref_34: string;
371
- export { $ref_34 as $ref };
374
+ let $ref_35: string;
375
+ export { $ref_35 as $ref };
372
376
  }
373
377
  export { additionalProperties_1 as additionalProperties };
374
378
  }
@@ -395,8 +399,8 @@ declare namespace $defs {
395
399
  let type_38: string;
396
400
  export { type_38 as type };
397
401
  export namespace additionalProperties_2 {
398
- let $ref_35: string;
399
- export { $ref_35 as $ref };
402
+ let $ref_36: string;
403
+ export { $ref_36 as $ref };
400
404
  }
401
405
  export { additionalProperties_2 as additionalProperties };
402
406
  }
@@ -418,8 +422,8 @@ declare namespace $defs {
418
422
  let type_41: string;
419
423
  export { type_41 as type };
420
424
  export namespace additionalProperties_3 {
421
- let $ref_36: string;
422
- export { $ref_36 as $ref };
425
+ let $ref_37: string;
426
+ export { $ref_37 as $ref };
423
427
  }
424
428
  export { additionalProperties_3 as additionalProperties };
425
429
  }
@@ -445,8 +449,8 @@ declare namespace $defs {
445
449
  export { required_14 as required };
446
450
  export namespace properties_15 {
447
451
  export namespace _do_4 {
448
- let $ref_37: string;
449
- export { $ref_37 as $ref };
452
+ let $ref_38: string;
453
+ export { $ref_38 as $ref };
450
454
  }
451
455
  export { _do_4 as do };
452
456
  export namespace key {
@@ -486,8 +490,8 @@ declare namespace $defs {
486
490
  let type_51: string;
487
491
  export { type_51 as type };
488
492
  export namespace items_3 {
489
- let $ref_38: string;
490
- export { $ref_38 as $ref };
493
+ let $ref_39: string;
494
+ export { $ref_39 as $ref };
491
495
  }
492
496
  export { items_3 as items };
493
497
  }
@@ -523,6 +527,64 @@ declare namespace $defs {
523
527
  };
524
528
  })[];
525
529
  }
530
+ namespace chain_config {
531
+ let type_53: string;
532
+ export { type_53 as type };
533
+ let required_16: string[];
534
+ export { required_16 as required };
535
+ export namespace properties_17 {
536
+ namespace input {
537
+ let type_54: string;
538
+ export { type_54 as type };
539
+ }
540
+ namespace steps {
541
+ let type_55: string;
542
+ export { type_55 as type };
543
+ export namespace items_4 {
544
+ let $ref_40: string;
545
+ export { $ref_40 as $ref };
546
+ }
547
+ export { items_4 as items };
548
+ }
549
+ namespace output {
550
+ let type_56: string;
551
+ export { type_56 as type };
552
+ }
553
+ }
554
+ export { properties_17 as properties };
555
+ }
556
+ namespace chain_entry {
557
+ let type_57: string;
558
+ export { type_57 as type };
559
+ let oneOf_1: ({
560
+ type: string;
561
+ required: string[];
562
+ properties: {
563
+ step: {
564
+ type: string;
565
+ };
566
+ fn: {
567
+ type: string;
568
+ };
569
+ stage?: never;
570
+ project?: never;
571
+ };
572
+ } | {
573
+ type: string;
574
+ required: string[];
575
+ properties: {
576
+ stage: {
577
+ type: string;
578
+ };
579
+ project: {
580
+ type: string;
581
+ };
582
+ step?: never;
583
+ fn?: never;
584
+ };
585
+ })[];
586
+ export { oneOf_1 as oneOf };
587
+ }
526
588
  }
527
589
  declare namespace __json_default_export {
528
590
  export { $schema, $id, title, description, type, items, $defs };
@@ -540,6 +602,13 @@ type StreamingRunHandle<o> = {
540
602
  readonly events: AsyncIterable<TrajectoryEvent>;
541
603
  readonly result: Promise<o>;
542
604
  };
605
+ /**
606
+ * Route a step to its registered kind handler.
607
+ *
608
+ * This is the single entry point composers use to run children. On failure
609
+ * the step's id is prepended to the error's `path`, so an error surfacing
610
+ * from a deep tree carries the chain of step ids it crossed.
611
+ */
543
612
  /**
544
613
  * Execute a flow and resolve with its final output.
545
614
  */
@@ -548,16 +617,41 @@ declare function run_impl<i, o>(flow: Step<i, o>, input: i, options?: RunOptions
548
617
  * Execute a flow while exposing its trajectory events as an async iterable.
549
618
  */
550
619
  declare function run_stream<i, o>(flow: Step<i, o>, input: i, options?: RunOptions): StreamingRunHandle<o>;
620
+ type RunOutcome<o> = {
621
+ readonly kind: 'done';
622
+ readonly output: o;
623
+ } | {
624
+ readonly kind: 'suspended';
625
+ readonly id: string;
626
+ readonly resume: (data: unknown) => Promise<RunOutcome<o>>;
627
+ };
628
+ /**
629
+ * Execute a flow, reporting suspension as a typed outcome instead of a
630
+ * thrown `suspended_error`.
631
+ *
632
+ * Resolves `{ kind: 'done', output }` on completion. When a `suspend` gate
633
+ * fires, resolves `{ kind: 'suspended', id, resume }` where `id` is the
634
+ * gate's suspend id and `resume(data)` re-runs the flow from the original
635
+ * input with `resume_data[id] = data` merged over the caller's options: the
636
+ * same full re-run semantics as calling `run` again yourself, so pure
637
+ * prefixes replay and `checkpoint`ed steps are served from the store. The
638
+ * returned promise resolves to the next outcome, so a flow with several
639
+ * gates is driven by awaiting `resume` repeatedly. Real errors still throw,
640
+ * from the initial call and from `resume` alike.
641
+ */
642
+ declare function run_until_suspended<i, o>(flow: Step<i, o>, input: i, options?: RunOptions): Promise<RunOutcome<o>>;
551
643
  /**
552
644
  * The public entry point for executing a flow.
553
645
  *
554
- * Callable as `run(flow, input, options?)` for a plain result, or
555
- * `run.stream(flow, input, options?)` for `{ events, result }`. Both share
556
- * one implementation, so a streamed run and a plain run of the same flow
557
- * produce identical output.
646
+ * Callable as `run(flow, input, options?)` for a plain result,
647
+ * `run.stream(flow, input, options?)` for `{ events, result }`, or
648
+ * `run.until_suspended(flow, input, options?)` for a `RunOutcome` that
649
+ * carries suspension as data. All share one implementation, so every entry
650
+ * point runs the same graph identically.
558
651
  */
559
652
  declare const run: typeof run_impl & {
560
653
  stream: typeof run_stream;
654
+ until_suspended: typeof run_until_suspended;
561
655
  };
562
656
  //#endregion
563
657
  //#region src/core/step.d.ts
@@ -605,37 +699,48 @@ declare const describe: {
605
699
  };
606
700
  //#endregion
607
701
  //#region src/core/sequence.d.ts
608
- type AnyStep$2 = Step<unknown, unknown>;
609
702
  type FirstInput<children> = children extends readonly [Step<infer i, unknown>, ...unknown[]] ? i : unknown;
610
- type LastOutput$1<children> = children extends readonly [...unknown[], Step<unknown, infer o>] ? o : children extends readonly [Step<unknown, infer o>] ? o : unknown;
703
+ type LastOutput$1<children> = children extends readonly [...unknown[], Step<never, infer o>] ? o : children extends readonly [Step<never, infer o>] ? o : unknown;
704
+ type OutputOf$1<s> = s extends Step<never, infer o> ? o : unknown;
705
+ type CheckedJoint<element, prev> = unknown extends element ? unknown : element extends AnyStep ? Step<OutputOf$1<prev>, OutputOf$1<element>> : AnyStep;
706
+ type CheckedFirst<element> = unknown extends element ? unknown : element extends AnyStep ? element : AnyStep;
707
+ type CheckedTail<children extends readonly unknown[], rest extends readonly unknown[]> = { readonly [k in keyof rest]: CheckedJoint<rest[k], k extends keyof children ? children[k] : never> };
708
+ type CheckedChildren<children extends readonly unknown[]> = children extends readonly [infer first, ...infer rest] ? readonly [CheckedFirst<first>, ...CheckedTail<children, rest>] : unknown[] extends children ? children : readonly AnyStep[];
611
709
  type SequenceOptions = {
612
710
  readonly name?: string;
613
711
  };
614
712
  /**
615
713
  * Build a step that chains children, each feeding the next.
616
714
  *
617
- * Validates every element up front so a non-Step (usually a bare function)
618
- * fails at construction with a pointed message rather than at run time.
619
- * Checks `ctx.abort` before each child so aborts land on step boundaries.
715
+ * The children parameter is checked joint by joint for literal tuples via
716
+ * `CheckedChildren`; the intersection with the bare `children` parameter is
717
+ * what lets inference read the precise tuple while the checked shape
718
+ * constrains it. Validates every element up front so a non-Step (usually a
719
+ * bare function) fails at construction with a pointed message rather than at
720
+ * run time. Checks `ctx.abort` before each child so aborts land on step
721
+ * boundaries.
620
722
  */
621
- declare function sequence<const children extends readonly AnyStep$2[]>(children: children, options?: SequenceOptions): Step<FirstInput<children>, LastOutput$1<children>>;
723
+ declare function sequence<const children extends readonly unknown[]>(children: children & CheckedChildren<children>, options?: SequenceOptions): Step<FirstInput<children>, LastOutput$1<children>>;
622
724
  //#endregion
623
725
  //#region src/core/parallel.d.ts
624
- type AnyStep$1 = Step<unknown, unknown>;
625
- type OutputOf<s> = s extends Step<unknown, infer o> ? o : unknown;
626
- type ParallelOutputs<children extends Record<string, AnyStep$1>> = { [k in keyof children]: OutputOf<children[k]> };
726
+ type OutputOf<s> = s extends Step<never, infer o> ? o : unknown;
727
+ type InputOf<s> = s extends Step<infer i, unknown> ? i : never;
728
+ type UnionToIntersection<u> = (u extends unknown ? (x: u) => void : never) extends ((x: infer i) => void) ? i : never;
729
+ type ParallelInput<children extends Record<string, AnyStep>> = UnionToIntersection<InputOf<children[keyof children]>>;
730
+ type ParallelOutputs<children extends Record<string, AnyStep>> = { [k in keyof children]: OutputOf<children[k]> };
627
731
  type ParallelOptions = {
628
732
  readonly name?: string;
629
733
  };
630
734
  /**
631
735
  * Build a step that runs named children concurrently on the same input.
632
736
  *
633
- * Returns an object keyed by child name. All children settle before any
634
- * error propagates; a `suspended_error` wins over application errors so a
635
- * human-approval gate stays resumable instead of being masked by a sibling's
636
- * failure.
737
+ * The step's input type is the intersection of the children's inputs, since
738
+ * every child receives the input verbatim. Returns an object keyed by child
739
+ * name. All children settle before any error propagates; a `suspended_error`
740
+ * wins over application errors so a human-approval gate stays resumable
741
+ * instead of being masked by a sibling's failure.
637
742
  */
638
- declare function parallel<i, children extends Record<string, Step<i, unknown>>>(members: children, options?: ParallelOptions): Step<i, ParallelOutputs<children>>;
743
+ declare function parallel<children extends Record<string, AnyStep>>(members: children, options?: ParallelOptions): Step<ParallelInput<children>, ParallelOutputs<children>>;
639
744
  //#endregion
640
745
  //#region src/core/branch.d.ts
641
746
  type BranchConfig<i, o> = {
@@ -787,7 +892,7 @@ type SuspendConfig<i, o, resume> = {
787
892
  readonly name?: string;
788
893
  readonly on: (input: i, ctx: RunContext) => Promise<void> | void;
789
894
  readonly resume_schema: AnySchema<resume>;
790
- readonly combine: (input: i, resume: resume, ctx: RunContext) => Promise<o> | o | Step<unknown, o>;
895
+ readonly combine: (input: i, resume: resume, ctx: RunContext) => Promise<o> | o | Step<i, o>;
791
896
  };
792
897
  /**
793
898
  * Build a human-in-the-loop pause step.
@@ -800,8 +905,7 @@ type SuspendConfig<i, o, resume> = {
800
905
  declare function suspend<i, o, resume>(config: SuspendConfig<i, o, resume>): Step<i, o>;
801
906
  //#endregion
802
907
  //#region src/core/scope.d.ts
803
- type AnyStep = Step<unknown, unknown>;
804
- type LastOutput<children> = children extends readonly [...unknown[], Step<unknown, infer o>] ? o : children extends readonly [Step<unknown, infer o>] ? o : unknown;
908
+ type LastOutput<children> = children extends readonly [...unknown[], Step<never, infer o>] ? o : children extends readonly [Step<never, infer o>] ? o : unknown;
805
909
  type ScopeOptions = {
806
910
  readonly name?: string;
807
911
  };
@@ -834,6 +938,30 @@ declare function stash<i, v>(key: string, source: Step<i, v>, options?: StashOpt
834
938
  */
835
939
  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>;
836
940
  //#endregion
941
+ //#region src/core/chain.d.ts
942
+ type merge<a, b> = { readonly [k in keyof (a & b)]: (a & b)[k] };
943
+ type ChainStepOptions = {
944
+ readonly arm?: AnyStep;
945
+ };
946
+ type Chain<i, acc> = {
947
+ readonly step: <k extends string, o>(name: k, fn: (s: acc, ctx: RunContext) => Promise<o> | o, options?: ChainStepOptions) => Chain<i, merge<acc, { readonly [p in k]: o }>>;
948
+ readonly stage: {
949
+ (name: string): Chain<i, acc>;
950
+ <next extends Record<string, unknown>>(name: string, project: (s: acc, ctx: RunContext) => Promise<next> | next): Chain<i, merge<next, unknown>>;
951
+ };
952
+ readonly output: <o>(fn: (s: acc, ctx: RunContext) => Promise<o> | o) => Step<i, o>;
953
+ };
954
+ /**
955
+ * Open a chain builder whose record starts as `{ [input_name]: input }`.
956
+ *
957
+ * `input_name` defaults to `'input'`. The builder is typed: each `.step`
958
+ * narrows subsequent callbacks to the record accumulated so far, and
959
+ * `.stage` with a projection re-types the record to the projection's
960
+ * return, so binding names and views are checked at compile time with no
961
+ * declared state shape.
962
+ */
963
+ declare function chain<i, k extends string = 'input'>(input_name?: k): Chain<i, { readonly [p in k]: i }>;
964
+ //#endregion
837
965
  //#region src/core/errors.d.ts
838
966
  declare class timeout_error extends Error {
839
967
  readonly kind: "timeout_error";
@@ -884,7 +1012,7 @@ declare class aborted_error extends Error {
884
1012
  * test in `step_kinds.test.ts` asserts every dispatch handler corresponds to a
885
1013
  * kind listed here.
886
1014
  */
887
- 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"];
1015
+ 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", "chain"];
888
1016
  type StepKind = (typeof STEP_KINDS)[number];
889
1017
  /**
890
1018
  * Check whether a value is one of the registered `Step.kind` strings.
@@ -1112,12 +1240,13 @@ type AdversarialResult<candidate> = {
1112
1240
  readonly converged: boolean;
1113
1241
  readonly rounds: number;
1114
1242
  };
1115
- type AdversarialConfig<input, candidate> = {
1243
+ type AdversarialConfig<input, candidate, projected = AdversarialResult<candidate>> = {
1116
1244
  readonly name?: string;
1117
1245
  readonly build: Step<AdversarialBuildInput<input, candidate>, candidate>;
1118
1246
  readonly critique: Step<candidate, AdversarialCritiqueResult>;
1119
1247
  readonly accept: (critique_result: AdversarialCritiqueResult) => boolean;
1120
1248
  readonly max_rounds: number;
1249
+ readonly project?: (r: AdversarialResult<candidate>) => projected;
1121
1250
  };
1122
1251
  /**
1123
1252
  * Builds a Step that runs up to `max_rounds` iterations of build ->
@@ -1126,21 +1255,24 @@ type AdversarialConfig<input, candidate> = {
1126
1255
  * Each round builds a candidate (receiving the prior candidate and critique
1127
1256
  * notes when available), critiques it, then checks `accept(critique_result)`.
1128
1257
  * Returns `{ candidate, converged, rounds }`. Does not throw on
1129
- * non-convergence; `converged: false` reports it instead.
1258
+ * non-convergence; `converged: false` reports it instead. `project` maps
1259
+ * that envelope into the step's output (e.g. `(r) => r.candidate`); omitted,
1260
+ * the envelope itself is the output.
1130
1261
  *
1131
1262
  * Implemented as a `compose`d `loop` whose body builds a new candidate and
1132
1263
  * whose guard runs the critique step and checks `accept`. State is threaded
1133
1264
  * through `scope`/`stash`/`use` so the build and critique steps remain
1134
1265
  * unmodified user-supplied `Step` values.
1135
1266
  */
1136
- declare function adversarial<input, candidate>(config: AdversarialConfig<input, candidate>): Step<input, AdversarialResult<candidate>>;
1267
+ declare function adversarial<input, candidate, projected = AdversarialResult<candidate>>(config: AdversarialConfig<input, candidate, projected>): Step<input, projected>;
1137
1268
  //#endregion
1138
1269
  //#region src/composites/consensus.d.ts
1139
- type ConsensusConfig<i, o> = {
1270
+ type ConsensusConfig<i, o, projected = ConsensusResult<o>> = {
1140
1271
  readonly name?: string;
1141
1272
  readonly members: Record<string, Step<i, o>>;
1142
1273
  readonly agree: (results: Record<string, o>) => boolean;
1143
1274
  readonly max_rounds: number;
1275
+ readonly project?: (r: ConsensusResult<o>) => projected;
1144
1276
  };
1145
1277
  type ConsensusResult<o> = {
1146
1278
  readonly result: Record<string, o>;
@@ -1153,19 +1285,22 @@ type ConsensusResult<o> = {
1153
1285
  * On agreement, returns the round's results with `converged: true`.
1154
1286
  * Otherwise re-runs all members up to `max_rounds` times and returns the
1155
1287
  * last results with `converged: false` if no agreement is reached.
1288
+ * `project` maps the `{ result, converged }` envelope into the step's output
1289
+ * (e.g. `(r) => r.converged`); omitted, the envelope itself is the output.
1156
1290
  *
1157
1291
  * Implemented as a `compose`d `loop` whose body runs `parallel(members)` and
1158
1292
  * whose guard evaluates `agree`. State carries the original input alongside
1159
1293
  * the most recent results so each round receives the same input.
1160
1294
  */
1161
- declare function consensus<i, o>(config: ConsensusConfig<i, o>): Step<i, ConsensusResult<o>>;
1295
+ declare function consensus<i, o, projected = ConsensusResult<o>>(config: ConsensusConfig<i, o, projected>): Step<i, projected>;
1162
1296
  //#endregion
1163
1297
  //#region src/composites/ensemble.d.ts
1164
- type EnsembleConfig<i, o> = {
1298
+ type EnsembleConfig<i, o, projected = EnsembleResult<o>> = {
1165
1299
  readonly name?: string;
1166
1300
  readonly members: Record<string, Step<i, o>>;
1167
1301
  readonly score: (result: o, member_id: string) => number | Promise<number>;
1168
1302
  readonly select?: 'max' | 'min';
1303
+ readonly project?: (r: EnsembleResult<o>) => projected;
1169
1304
  };
1170
1305
  type EnsembleResult<o> = {
1171
1306
  readonly winner: o;
@@ -1177,21 +1312,24 @@ type EnsembleResult<o> = {
1177
1312
  *
1178
1313
  * `select` picks the highest (`'max'`, the default) or lowest (`'min'`)
1179
1314
  * score. Tie-breaking is "any tied result is acceptable": the first member
1180
- * (in `members` key order) holding the best score wins.
1315
+ * (in `members` key order) holding the best score wins. `project` maps the
1316
+ * `{ winner, scores }` envelope into the step's output (e.g. `(r) =>
1317
+ * r.winner`); omitted, the envelope itself is the output.
1181
1318
  *
1182
1319
  * Implemented as a `compose`d `sequence` of `parallel(members)` followed by
1183
1320
  * a single picking step. Cancellation, fan-out, and abort propagation come
1184
1321
  * from `parallel`'s own contract.
1185
1322
  */
1186
- declare function ensemble<i, o>(config: EnsembleConfig<i, o>): Step<i, EnsembleResult<o>>;
1323
+ declare function ensemble<i, o, projected = EnsembleResult<o>>(config: EnsembleConfig<i, o, projected>): Step<i, projected>;
1187
1324
  //#endregion
1188
1325
  //#region src/composites/ensemble_step.d.ts
1189
- type EnsembleStepConfig<i, o, ranked> = {
1326
+ type EnsembleStepConfig<i, o, ranked, projected = EnsembleStepResult<o, ranked>> = {
1190
1327
  readonly name?: string;
1191
1328
  readonly members: Record<string, Step<i, o>>;
1192
1329
  readonly score: Step<o, ranked>;
1193
1330
  readonly rank_by: (r: ranked) => number;
1194
1331
  readonly select?: 'max' | 'min';
1332
+ readonly project?: (r: EnsembleStepResult<o, ranked>) => projected;
1195
1333
  };
1196
1334
  type EnsembleStepResult<o, ranked> = {
1197
1335
  readonly winner_id: string;
@@ -1211,14 +1349,16 @@ type EnsembleStepResult<o, ranked> = {
1211
1349
  *
1212
1350
  * The result carries `winner_scored`, the structured output from the round's
1213
1351
  * scoring run preserved verbatim, so callers never pay to re-score the
1214
- * winner. `scored` holds the structured score for every member.
1352
+ * winner. `scored` holds the structured score for every member. `project`
1353
+ * maps that envelope into the step's output (e.g. `(r) => r.winner`);
1354
+ * omitted, the envelope itself is the output.
1215
1355
  *
1216
1356
  * Implemented as a `compose`d `scope` over (`stash(parallel(members))` ->
1217
1357
  * `to_pairs` -> `map(score per result, threading id)` -> `use` to pick the
1218
1358
  * winner). Cancellation, fan-out, and abort propagation come from the
1219
1359
  * underlying `parallel` and `map` contracts.
1220
1360
  */
1221
- declare function ensemble_step<i, o, ranked>(config: EnsembleStepConfig<i, o, ranked>): Step<i, EnsembleStepResult<o, ranked>>;
1361
+ declare function ensemble_step<i, o, ranked, projected = EnsembleStepResult<o, ranked>>(config: EnsembleStepConfig<i, o, ranked, projected>): Step<i, projected>;
1222
1362
  //#endregion
1223
1363
  //#region src/composites/improve.d.ts
1224
1364
  type Candidate<c> = {
@@ -1248,7 +1388,7 @@ type ImproveBudget = {
1248
1388
  readonly max_wallclock_ms?: number;
1249
1389
  readonly patience: number;
1250
1390
  };
1251
- type ImproveConfig<i, c> = {
1391
+ type ImproveConfig<i, c, projected = ImproveResult<c>> = {
1252
1392
  readonly name?: string;
1253
1393
  readonly seed: Step<i, {
1254
1394
  readonly content: c;
@@ -1260,6 +1400,7 @@ type ImproveConfig<i, c> = {
1260
1400
  readonly epsilon?: number;
1261
1401
  readonly proposers_per_round?: number;
1262
1402
  readonly lessons_capacity?: number;
1403
+ readonly project?: (r: ImproveResult<c>) => projected;
1263
1404
  };
1264
1405
  type HistoryEntry<c> = {
1265
1406
  readonly round: number;
@@ -1284,7 +1425,9 @@ type ImproveResult<c> = {
1284
1425
  * Rejected rounds with a `reason` feed a bounded lessons list back into the
1285
1426
  * next round's input. Plateau detection stops the loop early when no
1286
1427
  * progress has been made for `patience` rounds; an optional wall-clock
1287
- * budget caps total runtime.
1428
+ * budget caps total runtime. `project` maps the result envelope into the
1429
+ * step's output (e.g. `(r) => r.best.content`); omitted, the envelope
1430
+ * itself is the output.
1288
1431
  *
1289
1432
  * Implemented as a `compose`d `scope` of (seed) -> (init state) -> (loop) ->
1290
1433
  * (unwrap). The loop body is itself a small `scope` that snapshots prior
@@ -1292,7 +1435,7 @@ type ImproveResult<c> = {
1292
1435
  * `ensemble_step`, and merges the outcome back into state via `use`.
1293
1436
  * State threading is the entire job.
1294
1437
  */
1295
- declare function improve<i, c>(config: ImproveConfig<i, c>): Step<i, ImproveResult<c>>;
1438
+ declare function improve<i, c, projected = ImproveResult<c>>(config: ImproveConfig<i, c, projected>): Step<i, projected>;
1296
1439
  //#endregion
1297
1440
  //#region src/composites/learn.d.ts
1298
1441
  type TrajectorySource = {
@@ -1318,7 +1461,7 @@ type Improvement = {
1318
1461
  };
1319
1462
  type LearnConfig<i extends LearnInput, o> = {
1320
1463
  readonly name?: string;
1321
- readonly flow: Step<unknown, unknown>;
1464
+ readonly flow: AnyStep;
1322
1465
  readonly source: TrajectorySource;
1323
1466
  readonly analyzer: Step<i, o>;
1324
1467
  readonly filter?: (event: TrajectoryEvent) => boolean;
@@ -1346,10 +1489,11 @@ type BracketRecord = {
1346
1489
  readonly b_id: string;
1347
1490
  readonly winner_id: string;
1348
1491
  };
1349
- type TournamentConfig<i, o> = {
1492
+ type TournamentConfig<i, o, projected = TournamentResult<o>> = {
1350
1493
  readonly name?: string;
1351
1494
  readonly members: Record<string, Step<i, o>>;
1352
1495
  readonly compare: (a: o, b: o) => Promise<'a' | 'b'> | 'a' | 'b';
1496
+ readonly project?: (r: TournamentResult<o>) => projected;
1353
1497
  };
1354
1498
  type TournamentResult<o> = {
1355
1499
  readonly winner: o;
@@ -1360,9 +1504,11 @@ type TournamentResult<o> = {
1360
1504
  *
1361
1505
  * All members run concurrently via `parallel`; the bracket step then reduces
1362
1506
  * survivors round by round with `compare`, recording every match. Requires at
1363
- * least one member so a winner always exists.
1507
+ * least one member so a winner always exists. `project` maps the `{ winner,
1508
+ * bracket }` envelope into the step's output (e.g. `(r) => r.winner`);
1509
+ * omitted, the envelope itself is the output.
1364
1510
  */
1365
- declare function tournament<i, o>(config: TournamentConfig<i, o>): Step<i, TournamentResult<o>>;
1511
+ declare function tournament<i, o, projected = TournamentResult<o>>(config: TournamentConfig<i, o, projected>): Step<i, projected>;
1366
1512
  //#endregion
1367
1513
  //#region src/composites/errors.d.ts
1368
1514
  /**
@@ -1544,7 +1690,7 @@ declare function write_baseline(path: string, report: BenchReport): Promise<void
1544
1690
  //#endregion
1545
1691
  //#region src/model_call.d.ts
1546
1692
  type ModelCallInput = string | ReadonlyArray<Message>;
1547
- type ModelCallConfig<T = string> = {
1693
+ type ModelCallConfig<T = string, projected = GenerateResult<T>> = {
1548
1694
  readonly engine: Engine;
1549
1695
  /**
1550
1696
  * Model or alias string. Optional: if omitted, the engine's
@@ -1570,6 +1716,13 @@ type ModelCallConfig<T = string> = {
1570
1716
  readonly tool_call_repair_attempts?: number;
1571
1717
  readonly max_tool_calls_per_step?: number;
1572
1718
  readonly on_tool_approval?: ToolApprovalHandler;
1719
+ /**
1720
+ * Map the `GenerateResult` envelope into the step's output at the source.
1721
+ * The projection runs inside the model_call step itself, so `describe` and
1722
+ * the trajectory gain no wrapper node. Omitted, the envelope is the output.
1723
+ * `model_step` is this option preset to `(r) => r.content`.
1724
+ */
1725
+ readonly project?: (r: GenerateResult<T>) => projected;
1573
1726
  };
1574
1727
  /**
1575
1728
  * Build a `Step` that calls `cfg.engine.generate` with `cfg` translated into
@@ -1577,9 +1730,28 @@ type ModelCallConfig<T = string> = {
1577
1730
  *
1578
1731
  * Threads `ctx.abort` and `ctx.trajectory` (nested under the model_call
1579
1732
  * step's own span) into every call, and, when `run.stream` is driving,
1580
- * records each chunk as a `model_chunk` trajectory event.
1733
+ * records each chunk as a `model_chunk` trajectory event. `cfg.project`
1734
+ * maps the `GenerateResult` envelope into the step's output inside the same
1735
+ * step; omitted, the envelope is the output.
1736
+ */
1737
+ declare function model_call<T = string, projected = GenerateResult<T>>(cfg: ModelCallConfig<T, projected>): Step<ModelCallInput, projected>;
1738
+ /**
1739
+ * model_step: `model_call` projected to its content.
1740
+ *
1741
+ * Returns a Step whose output is the model's final content (a `string`, or
1742
+ * the schema-validated value when `cfg.schema` is set) instead of the full
1743
+ * `GenerateResult` envelope. Use `model_step` when the flow only wants the
1744
+ * answer, keeping compositions at the `step, step, model_step, step` cadence;
1745
+ * drop to `model_call` when the caller needs usage, cost, tool calls, or
1746
+ * finish reason (or its `project` option, when the flow wants a slice of the
1747
+ * envelope mapped at the source).
1748
+ *
1749
+ * Implemented as `model_call` with `project` preset to `(r) => r.content`,
1750
+ * so the leaf is a single node in `describe` and the trajectory. Wrapping a
1751
+ * primitive into an app-shaped helper of your own is still the extension
1752
+ * pattern; this is its smallest instance.
1581
1753
  */
1582
- declare function model_call<T = string>(cfg: ModelCallConfig<T>): Step<ModelCallInput, GenerateResult<T>>;
1754
+ declare function model_step<T = string>(cfg: Omit<ModelCallConfig<T>, 'project'>): Step<ModelCallInput, T>;
1583
1755
  //#endregion
1584
1756
  //#region src/forward_standard_env.d.ts
1585
1757
  /**
@@ -1628,19 +1800,6 @@ type ViewerHandle = {
1628
1800
  declare function start_viewer(options?: StartViewerOptions): Promise<ViewerHandle>;
1629
1801
  //#endregion
1630
1802
  //#region src/viewer/cli.d.ts
1631
- /**
1632
- * fascicle-viewer CLI.
1633
- *
1634
- * fascicle-viewer <path> # tail a JSONL file (primary)
1635
- * fascicle-viewer --listen # accept HTTP push only
1636
- * fascicle-viewer <path> --listen # both producers feed the same broadcaster
1637
- *
1638
- * Flags: --port <n> --host <h> --buffer <n> --no-open --help
1639
- *
1640
- * Defaults bind 127.0.0.1:4242 and open the user's default browser. SIGINT
1641
- * shuts everything down cleanly. The CLI body is exposed as `run_viewer_cli`
1642
- * so the umbrella's bin shim can drive it from a bundled `dist/index.js`.
1643
- */
1644
1803
  /**
1645
1804
  * CLI entry point: parses argv, starts the viewer, and wires shutdown.
1646
1805
  *
@@ -1651,5 +1810,5 @@ declare function start_viewer(options?: StartViewerOptions): Promise<ViewerHandl
1651
1810
  */
1652
1811
  declare function run_viewer_cli(argv: readonly string[]): Promise<void>;
1653
1812
  //#endregion
1654
- 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 LoopOutcome, 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 TrajectoryParseResult, type TrajectorySource, type TurnRequest, type TurnResult, type UsageTotals, type UserContentPart, type ViewerHandle, aborted_error, adversarial, bench, bench_suspend_error, branch, checkpoint, claude_cli_error, compose, consensus, create_engine, default_normalize_usage, describe, describe_cycle_error, engine_config_error, engine_disposed_error, ensemble, ensemble_step, fallback, __json_default_export as flow_schema, forward_standard_env, improve, incomplete_generation_error, is_custom_trajectory_event, is_emit_event, is_span_end_event, is_span_start_event, is_step_kind, judge_equals, judge_llm, judge_with, learn, loop, map, model_call, model_required_error, normalize_score, on_chunk_error, parallel, parse_trajectory_event, 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, start_viewer, stash, step, suspend, suspended_error, timeout, timeout_error, tool_approval_denied_error, tool_error, tournament, use, write_baseline };
1813
+ export { type AdversarialBuildInput, type AdversarialConfig, type AdversarialCritiqueResult, type AdversarialResult, type AiSdkProviderAdapter, type AiSdkTelemetrySettings, type AnyStep, type AssistantContentPart, type BenchCase, type BenchOptions, type BenchReport, type BenchSummary, type BracketRecord, type Candidate, type CaseResult, type Chain, type ChainStepOptions, 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 LoopOutcome, 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, type RunOutcome, 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 TrajectoryParseResult, type TrajectorySource, type TurnRequest, type TurnResult, type UsageTotals, type UserContentPart, type ViewerHandle, aborted_error, adversarial, bench, bench_suspend_error, branch, chain, checkpoint, claude_cli_error, compose, consensus, create_engine, default_normalize_usage, describe, describe_cycle_error, engine_config_error, engine_disposed_error, ensemble, ensemble_step, fallback, __json_default_export as flow_schema, forward_standard_env, improve, incomplete_generation_error, is_custom_trajectory_event, is_emit_event, is_span_end_event, is_span_start_event, is_step_kind, judge_equals, judge_llm, judge_with, learn, loop, map, model_call, model_required_error, model_step, normalize_score, on_chunk_error, parallel, parse_trajectory_event, 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, start_viewer, stash, step, suspend, suspended_error, timeout, timeout_error, tool_approval_denied_error, tool_error, tournament, use, write_baseline };
1655
1814
  //# sourceMappingURL=index.d.ts.map