fascicle 0.11.1 → 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 };
@@ -555,16 +617,41 @@ declare function run_impl<i, o>(flow: Step<i, o>, input: i, options?: RunOptions
555
617
  * Execute a flow while exposing its trajectory events as an async iterable.
556
618
  */
557
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>>;
558
643
  /**
559
644
  * The public entry point for executing a flow.
560
645
  *
561
- * Callable as `run(flow, input, options?)` for a plain result, or
562
- * `run.stream(flow, input, options?)` for `{ events, result }`. Both share
563
- * one implementation, so a streamed run and a plain run of the same flow
564
- * 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.
565
651
  */
566
652
  declare const run: typeof run_impl & {
567
653
  stream: typeof run_stream;
654
+ until_suspended: typeof run_until_suspended;
568
655
  };
569
656
  //#endregion
570
657
  //#region src/core/step.d.ts
@@ -612,37 +699,48 @@ declare const describe: {
612
699
  };
613
700
  //#endregion
614
701
  //#region src/core/sequence.d.ts
615
- type AnyStep$2 = Step<unknown, unknown>;
616
702
  type FirstInput<children> = children extends readonly [Step<infer i, unknown>, ...unknown[]] ? i : unknown;
617
- 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[];
618
709
  type SequenceOptions = {
619
710
  readonly name?: string;
620
711
  };
621
712
  /**
622
713
  * Build a step that chains children, each feeding the next.
623
714
  *
624
- * Validates every element up front so a non-Step (usually a bare function)
625
- * fails at construction with a pointed message rather than at run time.
626
- * 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.
627
722
  */
628
- 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>>;
629
724
  //#endregion
630
725
  //#region src/core/parallel.d.ts
631
- type AnyStep$1 = Step<unknown, unknown>;
632
- type OutputOf<s> = s extends Step<unknown, infer o> ? o : unknown;
633
- 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]> };
634
731
  type ParallelOptions = {
635
732
  readonly name?: string;
636
733
  };
637
734
  /**
638
735
  * Build a step that runs named children concurrently on the same input.
639
736
  *
640
- * Returns an object keyed by child name. All children settle before any
641
- * error propagates; a `suspended_error` wins over application errors so a
642
- * human-approval gate stays resumable instead of being masked by a sibling's
643
- * 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.
644
742
  */
645
- 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>>;
646
744
  //#endregion
647
745
  //#region src/core/branch.d.ts
648
746
  type BranchConfig<i, o> = {
@@ -794,7 +892,7 @@ type SuspendConfig<i, o, resume> = {
794
892
  readonly name?: string;
795
893
  readonly on: (input: i, ctx: RunContext) => Promise<void> | void;
796
894
  readonly resume_schema: AnySchema<resume>;
797
- 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>;
798
896
  };
799
897
  /**
800
898
  * Build a human-in-the-loop pause step.
@@ -807,8 +905,7 @@ type SuspendConfig<i, o, resume> = {
807
905
  declare function suspend<i, o, resume>(config: SuspendConfig<i, o, resume>): Step<i, o>;
808
906
  //#endregion
809
907
  //#region src/core/scope.d.ts
810
- type AnyStep = Step<unknown, unknown>;
811
- 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;
812
909
  type ScopeOptions = {
813
910
  readonly name?: string;
814
911
  };
@@ -841,6 +938,30 @@ declare function stash<i, v>(key: string, source: Step<i, v>, options?: StashOpt
841
938
  */
842
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>;
843
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
844
965
  //#region src/core/errors.d.ts
845
966
  declare class timeout_error extends Error {
846
967
  readonly kind: "timeout_error";
@@ -891,7 +1012,7 @@ declare class aborted_error extends Error {
891
1012
  * test in `step_kinds.test.ts` asserts every dispatch handler corresponds to a
892
1013
  * kind listed here.
893
1014
  */
894
- 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"];
895
1016
  type StepKind = (typeof STEP_KINDS)[number];
896
1017
  /**
897
1018
  * Check whether a value is one of the registered `Step.kind` strings.
@@ -1119,12 +1240,13 @@ type AdversarialResult<candidate> = {
1119
1240
  readonly converged: boolean;
1120
1241
  readonly rounds: number;
1121
1242
  };
1122
- type AdversarialConfig<input, candidate> = {
1243
+ type AdversarialConfig<input, candidate, projected = AdversarialResult<candidate>> = {
1123
1244
  readonly name?: string;
1124
1245
  readonly build: Step<AdversarialBuildInput<input, candidate>, candidate>;
1125
1246
  readonly critique: Step<candidate, AdversarialCritiqueResult>;
1126
1247
  readonly accept: (critique_result: AdversarialCritiqueResult) => boolean;
1127
1248
  readonly max_rounds: number;
1249
+ readonly project?: (r: AdversarialResult<candidate>) => projected;
1128
1250
  };
1129
1251
  /**
1130
1252
  * Builds a Step that runs up to `max_rounds` iterations of build ->
@@ -1133,21 +1255,24 @@ type AdversarialConfig<input, candidate> = {
1133
1255
  * Each round builds a candidate (receiving the prior candidate and critique
1134
1256
  * notes when available), critiques it, then checks `accept(critique_result)`.
1135
1257
  * Returns `{ candidate, converged, rounds }`. Does not throw on
1136
- * 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.
1137
1261
  *
1138
1262
  * Implemented as a `compose`d `loop` whose body builds a new candidate and
1139
1263
  * whose guard runs the critique step and checks `accept`. State is threaded
1140
1264
  * through `scope`/`stash`/`use` so the build and critique steps remain
1141
1265
  * unmodified user-supplied `Step` values.
1142
1266
  */
1143
- 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>;
1144
1268
  //#endregion
1145
1269
  //#region src/composites/consensus.d.ts
1146
- type ConsensusConfig<i, o> = {
1270
+ type ConsensusConfig<i, o, projected = ConsensusResult<o>> = {
1147
1271
  readonly name?: string;
1148
1272
  readonly members: Record<string, Step<i, o>>;
1149
1273
  readonly agree: (results: Record<string, o>) => boolean;
1150
1274
  readonly max_rounds: number;
1275
+ readonly project?: (r: ConsensusResult<o>) => projected;
1151
1276
  };
1152
1277
  type ConsensusResult<o> = {
1153
1278
  readonly result: Record<string, o>;
@@ -1160,19 +1285,22 @@ type ConsensusResult<o> = {
1160
1285
  * On agreement, returns the round's results with `converged: true`.
1161
1286
  * Otherwise re-runs all members up to `max_rounds` times and returns the
1162
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.
1163
1290
  *
1164
1291
  * Implemented as a `compose`d `loop` whose body runs `parallel(members)` and
1165
1292
  * whose guard evaluates `agree`. State carries the original input alongside
1166
1293
  * the most recent results so each round receives the same input.
1167
1294
  */
1168
- 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>;
1169
1296
  //#endregion
1170
1297
  //#region src/composites/ensemble.d.ts
1171
- type EnsembleConfig<i, o> = {
1298
+ type EnsembleConfig<i, o, projected = EnsembleResult<o>> = {
1172
1299
  readonly name?: string;
1173
1300
  readonly members: Record<string, Step<i, o>>;
1174
1301
  readonly score: (result: o, member_id: string) => number | Promise<number>;
1175
1302
  readonly select?: 'max' | 'min';
1303
+ readonly project?: (r: EnsembleResult<o>) => projected;
1176
1304
  };
1177
1305
  type EnsembleResult<o> = {
1178
1306
  readonly winner: o;
@@ -1184,21 +1312,24 @@ type EnsembleResult<o> = {
1184
1312
  *
1185
1313
  * `select` picks the highest (`'max'`, the default) or lowest (`'min'`)
1186
1314
  * score. Tie-breaking is "any tied result is acceptable": the first member
1187
- * (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.
1188
1318
  *
1189
1319
  * Implemented as a `compose`d `sequence` of `parallel(members)` followed by
1190
1320
  * a single picking step. Cancellation, fan-out, and abort propagation come
1191
1321
  * from `parallel`'s own contract.
1192
1322
  */
1193
- 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>;
1194
1324
  //#endregion
1195
1325
  //#region src/composites/ensemble_step.d.ts
1196
- type EnsembleStepConfig<i, o, ranked> = {
1326
+ type EnsembleStepConfig<i, o, ranked, projected = EnsembleStepResult<o, ranked>> = {
1197
1327
  readonly name?: string;
1198
1328
  readonly members: Record<string, Step<i, o>>;
1199
1329
  readonly score: Step<o, ranked>;
1200
1330
  readonly rank_by: (r: ranked) => number;
1201
1331
  readonly select?: 'max' | 'min';
1332
+ readonly project?: (r: EnsembleStepResult<o, ranked>) => projected;
1202
1333
  };
1203
1334
  type EnsembleStepResult<o, ranked> = {
1204
1335
  readonly winner_id: string;
@@ -1218,14 +1349,16 @@ type EnsembleStepResult<o, ranked> = {
1218
1349
  *
1219
1350
  * The result carries `winner_scored`, the structured output from the round's
1220
1351
  * scoring run preserved verbatim, so callers never pay to re-score the
1221
- * 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.
1222
1355
  *
1223
1356
  * Implemented as a `compose`d `scope` over (`stash(parallel(members))` ->
1224
1357
  * `to_pairs` -> `map(score per result, threading id)` -> `use` to pick the
1225
1358
  * winner). Cancellation, fan-out, and abort propagation come from the
1226
1359
  * underlying `parallel` and `map` contracts.
1227
1360
  */
1228
- 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>;
1229
1362
  //#endregion
1230
1363
  //#region src/composites/improve.d.ts
1231
1364
  type Candidate<c> = {
@@ -1255,7 +1388,7 @@ type ImproveBudget = {
1255
1388
  readonly max_wallclock_ms?: number;
1256
1389
  readonly patience: number;
1257
1390
  };
1258
- type ImproveConfig<i, c> = {
1391
+ type ImproveConfig<i, c, projected = ImproveResult<c>> = {
1259
1392
  readonly name?: string;
1260
1393
  readonly seed: Step<i, {
1261
1394
  readonly content: c;
@@ -1267,6 +1400,7 @@ type ImproveConfig<i, c> = {
1267
1400
  readonly epsilon?: number;
1268
1401
  readonly proposers_per_round?: number;
1269
1402
  readonly lessons_capacity?: number;
1403
+ readonly project?: (r: ImproveResult<c>) => projected;
1270
1404
  };
1271
1405
  type HistoryEntry<c> = {
1272
1406
  readonly round: number;
@@ -1291,7 +1425,9 @@ type ImproveResult<c> = {
1291
1425
  * Rejected rounds with a `reason` feed a bounded lessons list back into the
1292
1426
  * next round's input. Plateau detection stops the loop early when no
1293
1427
  * progress has been made for `patience` rounds; an optional wall-clock
1294
- * 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.
1295
1431
  *
1296
1432
  * Implemented as a `compose`d `scope` of (seed) -> (init state) -> (loop) ->
1297
1433
  * (unwrap). The loop body is itself a small `scope` that snapshots prior
@@ -1299,7 +1435,7 @@ type ImproveResult<c> = {
1299
1435
  * `ensemble_step`, and merges the outcome back into state via `use`.
1300
1436
  * State threading is the entire job.
1301
1437
  */
1302
- 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>;
1303
1439
  //#endregion
1304
1440
  //#region src/composites/learn.d.ts
1305
1441
  type TrajectorySource = {
@@ -1325,7 +1461,7 @@ type Improvement = {
1325
1461
  };
1326
1462
  type LearnConfig<i extends LearnInput, o> = {
1327
1463
  readonly name?: string;
1328
- readonly flow: Step<unknown, unknown>;
1464
+ readonly flow: AnyStep;
1329
1465
  readonly source: TrajectorySource;
1330
1466
  readonly analyzer: Step<i, o>;
1331
1467
  readonly filter?: (event: TrajectoryEvent) => boolean;
@@ -1353,10 +1489,11 @@ type BracketRecord = {
1353
1489
  readonly b_id: string;
1354
1490
  readonly winner_id: string;
1355
1491
  };
1356
- type TournamentConfig<i, o> = {
1492
+ type TournamentConfig<i, o, projected = TournamentResult<o>> = {
1357
1493
  readonly name?: string;
1358
1494
  readonly members: Record<string, Step<i, o>>;
1359
1495
  readonly compare: (a: o, b: o) => Promise<'a' | 'b'> | 'a' | 'b';
1496
+ readonly project?: (r: TournamentResult<o>) => projected;
1360
1497
  };
1361
1498
  type TournamentResult<o> = {
1362
1499
  readonly winner: o;
@@ -1367,9 +1504,11 @@ type TournamentResult<o> = {
1367
1504
  *
1368
1505
  * All members run concurrently via `parallel`; the bracket step then reduces
1369
1506
  * survivors round by round with `compare`, recording every match. Requires at
1370
- * 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.
1371
1510
  */
1372
- 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>;
1373
1512
  //#endregion
1374
1513
  //#region src/composites/errors.d.ts
1375
1514
  /**
@@ -1551,7 +1690,7 @@ declare function write_baseline(path: string, report: BenchReport): Promise<void
1551
1690
  //#endregion
1552
1691
  //#region src/model_call.d.ts
1553
1692
  type ModelCallInput = string | ReadonlyArray<Message>;
1554
- type ModelCallConfig<T = string> = {
1693
+ type ModelCallConfig<T = string, projected = GenerateResult<T>> = {
1555
1694
  readonly engine: Engine;
1556
1695
  /**
1557
1696
  * Model or alias string. Optional: if omitted, the engine's
@@ -1577,6 +1716,13 @@ type ModelCallConfig<T = string> = {
1577
1716
  readonly tool_call_repair_attempts?: number;
1578
1717
  readonly max_tool_calls_per_step?: number;
1579
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;
1580
1726
  };
1581
1727
  /**
1582
1728
  * Build a `Step` that calls `cfg.engine.generate` with `cfg` translated into
@@ -1584,9 +1730,28 @@ type ModelCallConfig<T = string> = {
1584
1730
  *
1585
1731
  * Threads `ctx.abort` and `ctx.trajectory` (nested under the model_call
1586
1732
  * step's own span) into every call, and, when `run.stream` is driving,
1587
- * 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.
1588
1753
  */
1589
- 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>;
1590
1755
  //#endregion
1591
1756
  //#region src/forward_standard_env.d.ts
1592
1757
  /**
@@ -1645,5 +1810,5 @@ declare function start_viewer(options?: StartViewerOptions): Promise<ViewerHandl
1645
1810
  */
1646
1811
  declare function run_viewer_cli(argv: readonly string[]): Promise<void>;
1647
1812
  //#endregion
1648
- 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 };
1649
1814
  //# sourceMappingURL=index.d.ts.map