fascicle 0.11.1 → 0.12.1

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,7 @@
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 Step, c as StepMetadata, d as TrajectoryLogger, i as RunContext, l as StepOutput, n as CheckpointStore, o as StepFn, r as CleanupFn, s as StepInput, t as AnyStep, u as TrajectoryEvent } from "./types-BqUY6nRX.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 { _ as parse_trajectory_event, a as ParsedTrajectoryEvent, c as SpanEndEvent, d as is_checkpoint_event, f as is_custom_trajectory_event, g as is_span_start_event, h as is_span_end_event, i as EmitEvent, l as SpanStartEvent, m as is_run_end_event, n as CheckpointStatus, o as RunEndEvent, p as is_emit_event, r as CustomTrajectoryEvent, s as RunEndStatus, t as CheckpointEvent, u as TrajectoryParseResult } from "./trajectory-cSLNlHzh.js";
4
+ 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-CXBB4aIM.js";
4
5
 
5
6
  //#region src/core/flow-schema.json.d.ts
6
7
  declare let $schema: string;
@@ -105,6 +106,10 @@ declare namespace $defs {
105
106
  let $ref_18: string;
106
107
  export { $ref_18 as $ref };
107
108
  }
109
+ namespace chain {
110
+ let $ref_19: string;
111
+ export { $ref_19 as $ref };
112
+ }
108
113
  namespace ref {
109
114
  let type_4: string;
110
115
  export { type_4 as type };
@@ -133,8 +138,8 @@ declare namespace $defs {
133
138
  let type_8: string;
134
139
  export { type_8 as type };
135
140
  export namespace items_1 {
136
- let $ref_19: string;
137
- export { $ref_19 as $ref };
141
+ let $ref_20: string;
142
+ export { $ref_20 as $ref };
138
143
  }
139
144
  export { items_1 as items };
140
145
  }
@@ -142,8 +147,8 @@ declare namespace $defs {
142
147
  let type_9: string;
143
148
  export { type_9 as type };
144
149
  export namespace additionalProperties {
145
- let $ref_20: string;
146
- export { $ref_20 as $ref };
150
+ let $ref_21: string;
151
+ export { $ref_21 as $ref };
147
152
  }
148
153
  }
149
154
  namespace branch_config {
@@ -157,13 +162,13 @@ declare namespace $defs {
157
162
  export { type_11 as type };
158
163
  }
159
164
  namespace then {
160
- let $ref_21: string;
161
- export { $ref_21 as $ref };
162
- }
163
- namespace otherwise {
164
165
  let $ref_22: string;
165
166
  export { $ref_22 as $ref };
166
167
  }
168
+ namespace otherwise {
169
+ let $ref_23: string;
170
+ export { $ref_23 as $ref };
171
+ }
167
172
  }
168
173
  export { properties_3 as properties };
169
174
  }
@@ -179,8 +184,8 @@ declare namespace $defs {
179
184
  }
180
185
  export { items_2 as items };
181
186
  export namespace _do {
182
- let $ref_23: string;
183
- export { $ref_23 as $ref };
187
+ let $ref_24: string;
188
+ export { $ref_24 as $ref };
184
189
  }
185
190
  export { _do as do };
186
191
  export namespace concurrency {
@@ -198,8 +203,8 @@ declare namespace $defs {
198
203
  export { required_4 as required };
199
204
  export namespace properties_5 {
200
205
  export namespace of {
201
- let $ref_24: string;
202
- export { $ref_24 as $ref };
206
+ let $ref_25: string;
207
+ export { $ref_25 as $ref };
203
208
  }
204
209
  export namespace fn_1 {
205
210
  let type_16: string;
@@ -216,8 +221,8 @@ declare namespace $defs {
216
221
  export { required_5 as required };
217
222
  export namespace properties_6 {
218
223
  export namespace _do_1 {
219
- let $ref_25: string;
220
- export { $ref_25 as $ref };
224
+ let $ref_26: string;
225
+ export { $ref_26 as $ref };
221
226
  }
222
227
  export { _do_1 as do };
223
228
  export namespace max_attempts {
@@ -242,13 +247,13 @@ declare namespace $defs {
242
247
  export { required_6 as required };
243
248
  export namespace properties_7 {
244
249
  namespace primary {
245
- let $ref_26: string;
246
- export { $ref_26 as $ref };
247
- }
248
- namespace backup {
249
250
  let $ref_27: string;
250
251
  export { $ref_27 as $ref };
251
252
  }
253
+ namespace backup {
254
+ let $ref_28: string;
255
+ export { $ref_28 as $ref };
256
+ }
252
257
  }
253
258
  export { properties_7 as properties };
254
259
  }
@@ -259,8 +264,8 @@ declare namespace $defs {
259
264
  export { required_7 as required };
260
265
  export namespace properties_8 {
261
266
  export namespace _do_2 {
262
- let $ref_28: string;
263
- export { $ref_28 as $ref };
267
+ let $ref_29: string;
268
+ export { $ref_29 as $ref };
264
269
  }
265
270
  export { _do_2 as do };
266
271
  export namespace ms {
@@ -284,8 +289,8 @@ declare namespace $defs {
284
289
  export let minLength: number;
285
290
  }
286
291
  export namespace _do_3 {
287
- let $ref_29: string;
288
- export { $ref_29 as $ref };
292
+ let $ref_30: string;
293
+ export { $ref_30 as $ref };
289
294
  }
290
295
  export { _do_3 as do };
291
296
  }
@@ -309,13 +314,13 @@ declare namespace $defs {
309
314
  export { type_27 as type };
310
315
  }
311
316
  export namespace body {
312
- let $ref_30: string;
313
- export { $ref_30 as $ref };
314
- }
315
- export namespace guard {
316
317
  let $ref_31: string;
317
318
  export { $ref_31 as $ref };
318
319
  }
320
+ export namespace guard {
321
+ let $ref_32: string;
322
+ export { $ref_32 as $ref };
323
+ }
319
324
  export namespace finish {
320
325
  let type_28: string;
321
326
  export { type_28 as type };
@@ -336,13 +341,13 @@ declare namespace $defs {
336
341
  export { required_10 as required };
337
342
  export namespace properties_11 {
338
343
  export namespace build {
339
- let $ref_32: string;
340
- export { $ref_32 as $ref };
341
- }
342
- export namespace critique {
343
344
  let $ref_33: string;
344
345
  export { $ref_33 as $ref };
345
346
  }
347
+ export namespace critique {
348
+ let $ref_34: string;
349
+ export { $ref_34 as $ref };
350
+ }
346
351
  export namespace accept {
347
352
  let type_31: string;
348
353
  export { type_31 as type };
@@ -367,8 +372,8 @@ declare namespace $defs {
367
372
  let type_34: string;
368
373
  export { type_34 as type };
369
374
  export namespace additionalProperties_1 {
370
- let $ref_34: string;
371
- export { $ref_34 as $ref };
375
+ let $ref_35: string;
376
+ export { $ref_35 as $ref };
372
377
  }
373
378
  export { additionalProperties_1 as additionalProperties };
374
379
  }
@@ -395,8 +400,8 @@ declare namespace $defs {
395
400
  let type_38: string;
396
401
  export { type_38 as type };
397
402
  export namespace additionalProperties_2 {
398
- let $ref_35: string;
399
- export { $ref_35 as $ref };
403
+ let $ref_36: string;
404
+ export { $ref_36 as $ref };
400
405
  }
401
406
  export { additionalProperties_2 as additionalProperties };
402
407
  }
@@ -418,8 +423,8 @@ declare namespace $defs {
418
423
  let type_41: string;
419
424
  export { type_41 as type };
420
425
  export namespace additionalProperties_3 {
421
- let $ref_36: string;
422
- export { $ref_36 as $ref };
426
+ let $ref_37: string;
427
+ export { $ref_37 as $ref };
423
428
  }
424
429
  export { additionalProperties_3 as additionalProperties };
425
430
  }
@@ -445,8 +450,8 @@ declare namespace $defs {
445
450
  export { required_14 as required };
446
451
  export namespace properties_15 {
447
452
  export namespace _do_4 {
448
- let $ref_37: string;
449
- export { $ref_37 as $ref };
453
+ let $ref_38: string;
454
+ export { $ref_38 as $ref };
450
455
  }
451
456
  export { _do_4 as do };
452
457
  export namespace key {
@@ -486,8 +491,8 @@ declare namespace $defs {
486
491
  let type_51: string;
487
492
  export { type_51 as type };
488
493
  export namespace items_3 {
489
- let $ref_38: string;
490
- export { $ref_38 as $ref };
494
+ let $ref_39: string;
495
+ export { $ref_39 as $ref };
491
496
  }
492
497
  export { items_3 as items };
493
498
  }
@@ -523,6 +528,64 @@ declare namespace $defs {
523
528
  };
524
529
  })[];
525
530
  }
531
+ namespace chain_config {
532
+ let type_53: string;
533
+ export { type_53 as type };
534
+ let required_16: string[];
535
+ export { required_16 as required };
536
+ export namespace properties_17 {
537
+ namespace input {
538
+ let type_54: string;
539
+ export { type_54 as type };
540
+ }
541
+ namespace steps {
542
+ let type_55: string;
543
+ export { type_55 as type };
544
+ export namespace items_4 {
545
+ let $ref_40: string;
546
+ export { $ref_40 as $ref };
547
+ }
548
+ export { items_4 as items };
549
+ }
550
+ namespace output {
551
+ let type_56: string;
552
+ export { type_56 as type };
553
+ }
554
+ }
555
+ export { properties_17 as properties };
556
+ }
557
+ namespace chain_entry {
558
+ let type_57: string;
559
+ export { type_57 as type };
560
+ let oneOf_1: ({
561
+ type: string;
562
+ required: string[];
563
+ properties: {
564
+ step: {
565
+ type: string;
566
+ };
567
+ fn: {
568
+ type: string;
569
+ };
570
+ stage?: never;
571
+ project?: never;
572
+ };
573
+ } | {
574
+ type: string;
575
+ required: string[];
576
+ properties: {
577
+ stage: {
578
+ type: string;
579
+ };
580
+ project: {
581
+ type: string;
582
+ };
583
+ step?: never;
584
+ fn?: never;
585
+ };
586
+ })[];
587
+ export { oneOf_1 as oneOf };
588
+ }
526
589
  }
527
590
  declare namespace __json_default_export {
528
591
  export { $schema, $id, title, description, type, items, $defs };
@@ -540,13 +603,6 @@ type StreamingRunHandle<o> = {
540
603
  readonly events: AsyncIterable<TrajectoryEvent>;
541
604
  readonly result: Promise<o>;
542
605
  };
543
- /**
544
- * Route a step to its registered kind handler.
545
- *
546
- * This is the single entry point composers use to run children. On failure
547
- * the step's id is prepended to the error's `path`, so an error surfacing
548
- * from a deep tree carries the chain of step ids it crossed.
549
- */
550
606
  /**
551
607
  * Execute a flow and resolve with its final output.
552
608
  */
@@ -555,16 +611,43 @@ declare function run_impl<i, o>(flow: Step<i, o>, input: i, options?: RunOptions
555
611
  * Execute a flow while exposing its trajectory events as an async iterable.
556
612
  */
557
613
  declare function run_stream<i, o>(flow: Step<i, o>, input: i, options?: RunOptions): StreamingRunHandle<o>;
614
+ type RunOutcome<o> = {
615
+ readonly kind: 'done';
616
+ readonly output: o;
617
+ } | {
618
+ readonly kind: 'suspended';
619
+ readonly id: string;
620
+ readonly payload: unknown;
621
+ readonly resume: (data: unknown) => Promise<RunOutcome<o>>;
622
+ };
623
+ /**
624
+ * Execute a flow, reporting suspension as a typed outcome instead of a
625
+ * thrown `suspended_error`.
626
+ *
627
+ * Resolves `{ kind: 'done', output }` on completion. When a `suspend` gate
628
+ * fires, resolves `{ kind: 'suspended', id, payload, resume }` where `id` is
629
+ * the gate's suspend id, `payload` is what the gate raised on its
630
+ * `suspended_error`, and `resume(data)` re-runs the flow from the original
631
+ * input with `resume_data[id] = data` merged over the caller's options: the
632
+ * same full re-run semantics as calling `run` again yourself, so pure
633
+ * prefixes replay and `checkpoint`ed steps are served from the store. The
634
+ * returned promise resolves to the next outcome, so a flow with several
635
+ * gates is driven by awaiting `resume` repeatedly. Real errors still throw,
636
+ * from the initial call and from `resume` alike.
637
+ */
638
+ declare function run_until_suspended<i, o>(flow: Step<i, o>, input: i, options?: RunOptions): Promise<RunOutcome<o>>;
558
639
  /**
559
640
  * The public entry point for executing a flow.
560
641
  *
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.
642
+ * Callable as `run(flow, input, options?)` for a plain result,
643
+ * `run.stream(flow, input, options?)` for `{ events, result }`, or
644
+ * `run.until_suspended(flow, input, options?)` for a `RunOutcome` that
645
+ * carries suspension as data. All share one implementation, so every entry
646
+ * point runs the same graph identically.
565
647
  */
566
648
  declare const run: typeof run_impl & {
567
649
  stream: typeof run_stream;
650
+ until_suspended: typeof run_until_suspended;
568
651
  };
569
652
  //#endregion
570
653
  //#region src/core/step.d.ts
@@ -572,7 +655,7 @@ declare const run: typeof run_impl & {
572
655
  * Wrap a plain function as a `Step`, named or anonymous.
573
656
  *
574
657
  * The named form takes an explicit id (and optional descriptive `meta`); the
575
- * anonymous form generates an `anon_<n>` id and marks the step so checkpoint
658
+ * anonymous form generates a `step_<n>` id and marks the step so checkpoint
576
659
  * rejects it at construction time.
577
660
  */
578
661
  declare function step<i, o>(id: string, fn: StepFn<i, o>, meta?: StepMetadata): Step<i, o>;
@@ -612,37 +695,69 @@ declare const describe: {
612
695
  };
613
696
  //#endregion
614
697
  //#region src/core/sequence.d.ts
615
- type AnyStep$2 = Step<unknown, unknown>;
616
698
  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;
699
+ type LastOutput$1<children> = children extends readonly [...unknown[], Step<never, infer o>] ? o : children extends readonly [Step<never, infer o>] ? o : unknown;
700
+ type OutputOf<s> = StepOutput<s>;
701
+ type InputOf<s> = StepInput<s>;
702
+ interface SequenceJointMismatch<at extends string, upstream_output, this_step_accepts> {
703
+ readonly sequence_joint_mismatch: at;
704
+ readonly upstream_output: upstream_output;
705
+ readonly this_step_accepts: this_step_accepts;
706
+ }
707
+ type CheckedJoint<element, upstream, at extends string> = unknown extends element ? unknown : element extends AnyStep ? [upstream] extends [InputOf<element>] ? element : SequenceJointMismatch<at, upstream, InputOf<element>> : AnyStep;
708
+ type CheckedFirst<element> = unknown extends element ? unknown : element extends AnyStep ? element : AnyStep;
709
+ type CheckedTail<children extends readonly unknown[], rest extends readonly unknown[]> = { readonly [k in keyof rest]: CheckedJoint<rest[k], OutputOf<k extends keyof children ? children[k] : never>, `after children[${k & string}]`> };
710
+ type IsPlainArray<t extends readonly unknown[]> = t extends readonly [] ? false : t[number][] extends [...t] ? true : false;
711
+ type CheckedSegment<seg extends readonly unknown[], e, upstream> = unknown extends e ? seg : [e] extends [AnyStep] ? [upstream | OutputOf<e>] extends [InputOf<e>] ? seg : readonly SequenceJointMismatch<'spread segment', upstream | OutputOf<e>, InputOf<e>>[] : readonly AnyStep[];
712
+ type SplitSpreadTrail<t extends readonly unknown[], trail extends readonly unknown[] = []> = IsPlainArray<t> extends true ? [t, trail] : t extends readonly [...infer init, infer last_el] ? SplitSpreadTrail<init, [last_el, ...trail]> : [t, trail];
713
+ type SpreadPos = readonly unknown[] | 'spread';
714
+ type JointAt<p extends SpreadPos> = p extends readonly unknown[] ? `after children[${p['length']}]` : 'after spread segment';
715
+ type NextPos<p extends SpreadPos> = p extends readonly unknown[] ? readonly [...p, unknown] : p;
716
+ type CheckedSpreadTail<upstream, t extends readonly unknown[], p extends SpreadPos> = t extends readonly [] ? readonly [] : IsPlainArray<t> extends true ? readonly [...CheckedSegment<t, t[number], upstream>] : t extends readonly [infer h, ...infer r] ? readonly [CheckedJoint<h, upstream, JointAt<p>>, ...CheckedSpreadTail<OutputOf<h>, r, NextPos<p>>] : SplitSpreadTrail<t> extends [infer seg extends readonly unknown[], infer trail extends readonly unknown[]] ? readonly [...CheckedSegment<seg, seg[number], upstream>, ...CheckedSpreadTail<upstream | OutputOf<seg[number]>, trail, 'spread'>] : never;
717
+ interface SequenceRuntimeChildrenMustBeHomogeneous<element> {
718
+ readonly runtime_built_children: 'no tuple positions to check; use ReadonlyArray<Step<T, T>>';
719
+ readonly element: element;
720
+ }
721
+ interface SequenceLeadingSpreadNeedsFixedFirst {
722
+ readonly leading_spread: 'joint checking needs a fixed first element; a homogeneous ReadonlyArray<Step<T, T>> works via the array overload';
723
+ }
724
+ type CheckedChildren<children extends readonly unknown[]> = unknown[] extends children ? children : IsPlainArray<children> extends true ? SequenceRuntimeChildrenMustBeHomogeneous<children[number]> : number extends children['length'] ? children extends readonly [infer first, ...infer rest] ? readonly [CheckedFirst<first>, ...CheckedSpreadTail<OutputOf<first>, rest, readonly []>] : SequenceLeadingSpreadNeedsFixedFirst : children extends readonly [infer first, ...infer rest] ? readonly [CheckedFirst<first>, ...CheckedTail<children, rest>] : children;
618
725
  type SequenceOptions = {
619
726
  readonly name?: string;
620
727
  };
621
728
  /**
622
729
  * Build a step that chains children, each feeding the next.
623
730
  *
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.
731
+ * The children parameter is checked joint by joint for literal tuples via
732
+ * `CheckedChildren`; the intersection with the bare `children` parameter is
733
+ * what lets inference read the precise tuple while the checked shape
734
+ * constrains it. Runtime-built arrays carry no positional types, so the
735
+ * second overload requires them to be homogeneous and self-composing, which
736
+ * keeps `run` sound instead of degrading to the unknown boundary. Validates
737
+ * every element up front so a non-Step (usually a bare function) fails at
738
+ * construction with a pointed message rather than at run time. Checks
739
+ * `ctx.abort` before each child so aborts land on step boundaries.
627
740
  */
628
- declare function sequence<const children extends readonly AnyStep$2[]>(children: children, options?: SequenceOptions): Step<FirstInput<children>, LastOutput$1<children>>;
741
+ declare function sequence<const children extends readonly unknown[]>(children: children & CheckedChildren<children>, options?: SequenceOptions): Step<FirstInput<children>, LastOutput$1<children>>;
742
+ declare function sequence<t>(children: ReadonlyArray<Step<t, t>>, options?: SequenceOptions): Step<t, t>;
629
743
  //#endregion
630
744
  //#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]> };
745
+ type UnionToIntersection<u> = (u extends unknown ? (x: u) => void : never) extends ((x: infer i) => void) ? i : never;
746
+ type ParallelInput<children extends Record<string, AnyStep>> = UnionToIntersection<StepInput<children[keyof children]>>;
747
+ type ParallelOutputs<children extends Record<string, AnyStep>> = { [k in keyof children]: StepOutput<children[k]> };
634
748
  type ParallelOptions = {
635
749
  readonly name?: string;
636
750
  };
637
751
  /**
638
752
  * Build a step that runs named children concurrently on the same input.
639
753
  *
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.
754
+ * The step's input type is the intersection of the children's inputs, since
755
+ * every child receives the input verbatim. Returns an object keyed by child
756
+ * name. All children settle before any error propagates; a `suspended_error`
757
+ * wins over application errors so a human-approval gate stays resumable
758
+ * instead of being masked by a sibling's failure.
644
759
  */
645
- declare function parallel<i, children extends Record<string, Step<i, unknown>>>(members: children, options?: ParallelOptions): Step<i, ParallelOutputs<children>>;
760
+ declare function parallel<children extends Record<string, AnyStep>>(members: children, options?: ParallelOptions): Step<ParallelInput<children>, ParallelOutputs<children>>;
646
761
  //#endregion
647
762
  //#region src/core/branch.d.ts
648
763
  type BranchConfig<i, o> = {
@@ -739,6 +854,7 @@ type LoopGuardResult<state> = {
739
854
  readonly stop: boolean;
740
855
  readonly state: state;
741
856
  };
857
+ type LoopGuardPredicate<state> = (state: state) => boolean | Promise<boolean>;
742
858
  type LoopOutcome = {
743
859
  readonly converged: boolean;
744
860
  readonly rounds: number;
@@ -747,7 +863,7 @@ type LoopConfig<i, state, o> = {
747
863
  readonly name?: string;
748
864
  readonly init: (input: i) => state;
749
865
  readonly body: Step<state, state>;
750
- readonly guard?: Step<state, LoopGuardResult<state>>;
866
+ readonly guard?: Step<state, LoopGuardResult<state>> | LoopGuardPredicate<state>;
751
867
  readonly finish: (state: state, outcome: LoopOutcome) => o;
752
868
  readonly max_rounds: number;
753
869
  };
@@ -794,7 +910,7 @@ type SuspendConfig<i, o, resume> = {
794
910
  readonly name?: string;
795
911
  readonly on: (input: i, ctx: RunContext) => Promise<void> | void;
796
912
  readonly resume_schema: AnySchema<resume>;
797
- readonly combine: (input: i, resume: resume, ctx: RunContext) => Promise<o> | o | Step<unknown, o>;
913
+ readonly combine: (input: i, resume: resume, ctx: RunContext) => Promise<o> | o | Step<i, o>;
798
914
  };
799
915
  /**
800
916
  * Build a human-in-the-loop pause step.
@@ -807,8 +923,7 @@ type SuspendConfig<i, o, resume> = {
807
923
  declare function suspend<i, o, resume>(config: SuspendConfig<i, o, resume>): Step<i, o>;
808
924
  //#endregion
809
925
  //#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;
926
+ type LastOutput<children> = children extends readonly [...unknown[], Step<never, infer o>] ? o : children extends readonly [Step<never, infer o>] ? o : unknown;
812
927
  type ScopeOptions = {
813
928
  readonly name?: string;
814
929
  };
@@ -841,32 +956,77 @@ declare function stash<i, v>(key: string, source: Step<i, v>, options?: StashOpt
841
956
  */
842
957
  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
958
  //#endregion
959
+ //#region src/core/chain.d.ts
960
+ type merge<a, b> = { readonly [k in keyof (a & b)]: (a & b)[k] };
961
+ type ChainStepOptions = {
962
+ readonly arm?: AnyStep;
963
+ };
964
+ type Chain<i, acc> = {
965
+ readonly step: {
966
+ <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 }>>;
967
+ <k extends string, a, o>(name: k, arm: Step<a, o>, select: (s: acc) => a): Chain<i, merge<acc, { readonly [p in k]: o }>>;
968
+ };
969
+ readonly stage: {
970
+ (name: string): Chain<i, acc>;
971
+ <next extends Record<string, unknown>>(name: string, project: (s: acc, ctx: RunContext) => Promise<next> | next): Chain<i, merge<next, unknown>>;
972
+ };
973
+ readonly output: <o>(fn: (s: acc, ctx: RunContext) => Promise<o> | o) => Step<i, o>;
974
+ };
975
+ /**
976
+ * A freshly opened chain: `Chain` plus `.input<t>()`, which restates the
977
+ * input type once with the binding name already fixed, so
978
+ * `chain('q').input<Request>()` equals `chain<Request, 'q'>('q')`. The first
979
+ * `.step` or `.stage` returns plain `Chain`, so refinement is only possible
980
+ * before any entry is recorded.
981
+ */
982
+ type ChainOpen<i, k extends string, acc> = Chain<i, acc> & {
983
+ readonly input: <t>() => Chain<t, { readonly [p in k]: t }>;
984
+ };
985
+ /**
986
+ * Open a chain builder whose record starts as `{ [input_name]: input }`.
987
+ *
988
+ * `input_name` defaults to `'input'`. The input type defaults to `never`, so
989
+ * a chain that never states it produces a `Step<never, o>` that no real
990
+ * input satisfies at `run`; state it as the type argument or, when the
991
+ * binding is renamed, once via `.input<t>()` on the fresh builder. Each
992
+ * `.step` narrows subsequent callbacks to the record accumulated so far, and
993
+ * `.stage` with a projection re-types the record to the projection's
994
+ * return, so binding names and views are checked at compile time with no
995
+ * declared state shape.
996
+ */
997
+ declare function chain<i = never, k extends string = 'input'>(input_name?: k): ChainOpen<i, k, { readonly [p in k]: i }>;
998
+ //#endregion
844
999
  //#region src/core/errors.d.ts
845
1000
  declare class timeout_error extends Error {
846
1001
  readonly kind: "timeout_error";
1002
+ readonly path?: ReadonlyArray<string>;
847
1003
  readonly timeout_ms: number;
848
1004
  constructor(message: string, timeout_ms: number);
849
1005
  }
850
1006
  declare class suspended_error extends Error {
851
1007
  readonly kind: "suspended_error";
1008
+ readonly path?: ReadonlyArray<string>;
852
1009
  readonly suspend_id: string;
853
1010
  readonly payload: unknown;
854
1011
  constructor(suspend_id: string, payload: unknown, message?: string);
855
1012
  }
856
1013
  declare class resume_validation_error extends Error {
857
1014
  readonly kind: "resume_validation_error";
1015
+ readonly path?: ReadonlyArray<string>;
858
1016
  readonly issues: ReadonlyArray<SchemaIssue>;
859
1017
  constructor(message: string, issues: ReadonlyArray<SchemaIssue>);
860
1018
  }
861
1019
  declare class describe_cycle_error extends Error {
862
1020
  readonly kind: "describe_cycle_error";
1021
+ readonly path?: ReadonlyArray<string>;
863
1022
  readonly step_id: string;
864
1023
  constructor(step_id: string, message?: string);
865
1024
  }
866
1025
  declare class aborted_error extends Error {
867
1026
  readonly kind: "aborted_error";
1027
+ readonly path?: ReadonlyArray<string>;
868
1028
  readonly reason?: unknown;
869
- readonly step_index: number;
1029
+ readonly step_index?: number;
870
1030
  readonly tool_call_in_flight?: {
871
1031
  id: string;
872
1032
  name: string;
@@ -880,6 +1040,25 @@ declare class aborted_error extends Error {
880
1040
  };
881
1041
  });
882
1042
  }
1043
+ /**
1044
+ * Read the step-id path off any error that crossed the runner's dispatch.
1045
+ *
1046
+ * The runner attaches `path` to whatever escapes a step, including
1047
+ * user-thrown errors the declared class fields cannot type, so a catch block
1048
+ * needs a narrowing read rather than a cast. Returns the ids only when the
1049
+ * property is present and well-formed (an all-string array); anything else,
1050
+ * including non-object inputs, is `undefined`.
1051
+ */
1052
+ declare function error_path(err: unknown): ReadonlyArray<string> | undefined;
1053
+ //#endregion
1054
+ //#region src/core/is_step.d.ts
1055
+ /**
1056
+ * Check whether a value is structurally a `Step`.
1057
+ *
1058
+ * True when the value has a string `id`, a string `kind`, and a callable
1059
+ * `run`.
1060
+ */
1061
+ declare function is_step(value: unknown): value is AnyStep;
883
1062
  //#endregion
884
1063
  //#region src/core/step_kinds.d.ts
885
1064
  /**
@@ -891,94 +1070,13 @@ declare class aborted_error extends Error {
891
1070
  * test in `step_kinds.test.ts` asserts every dispatch handler corresponds to a
892
1071
  * kind listed here.
893
1072
  */
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"];
1073
+ 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
1074
  type StepKind = (typeof STEP_KINDS)[number];
896
1075
  /**
897
1076
  * Check whether a value is one of the registered `Step.kind` strings.
898
1077
  */
899
1078
  declare function is_step_kind(value: unknown): value is StepKind;
900
1079
  //#endregion
901
- //#region src/core/trajectory.d.ts
902
- /**
903
- * Wire-format guards for trajectory events.
904
- *
905
- * `TrajectoryEvent` (in `types.ts`) is the loose internal type — any code that
906
- * calls `trajectory.record(event)` or `start_span(name, meta)` produces values
907
- * conforming to it. This file defines the *narrower* shapes that the studio
908
- * (and any other downstream consumer) can recognize in the wire stream:
909
- *
910
- * span_start — composer span open
911
- * span_end — composer span close
912
- * emit — user-emitted event from inside a step (ctx.emit)
913
- * <other> — anything else, recognized by `is_custom_trajectory_event`,
914
- * which only requires a string `kind`
915
- *
916
- * `parse_trajectory_event` is the wire gate, and it is deliberately permissive:
917
- * a value is a trajectory event iff it is a non-array object carrying a string
918
- * `kind`. The well-known guards layered on top are *recognizers*, not gates — a
919
- * `{ kind: 'span_start' }` line missing its `span_id` is still a valid event on
920
- * the wire, just not a `SpanStartEvent`. Anything stricter would have a viewer
921
- * drop lines a newer producer emits, which is the opposite of what a
922
- * forward-compatible wire format is for. `is_custom_trajectory_event` therefore
923
- * answers `true` for well-known kinds too: it is the fallback shape, not a
924
- * fifth disjoint case.
925
- *
926
- * Extra fields (`run_id`, `id`, provider-specific metadata) are neither
927
- * required nor stripped: a successful parse hands the value straight back, so a
928
- * parse / re-serialize round trip is lossless.
929
- */
930
- type SpanStartEvent = {
931
- readonly kind: 'span_start';
932
- readonly span_id: string;
933
- readonly name: string;
934
- } & {
935
- readonly [key: string]: unknown;
936
- };
937
- type SpanEndEvent = {
938
- readonly kind: 'span_end';
939
- readonly span_id: string;
940
- } & {
941
- readonly [key: string]: unknown;
942
- };
943
- type EmitEvent = {
944
- readonly kind: 'emit';
945
- } & {
946
- readonly [key: string]: unknown;
947
- };
948
- type CustomTrajectoryEvent = {
949
- readonly kind: string;
950
- } & {
951
- readonly [key: string]: unknown;
952
- };
953
- type ParsedTrajectoryEvent = SpanStartEvent | SpanEndEvent | EmitEvent | CustomTrajectoryEvent;
954
- type TrajectoryParseResult = {
955
- readonly success: true;
956
- readonly data: ParsedTrajectoryEvent;
957
- } | {
958
- readonly success: false;
959
- readonly error: Error;
960
- };
961
- /**
962
- * The wire gate: a non-array object carrying a string `kind`.
963
- *
964
- * True for every well-known kind as well, since `custom` is the fallback shape
965
- * rather than a disjoint case.
966
- */
967
- declare function is_custom_trajectory_event(value: unknown): value is CustomTrajectoryEvent;
968
- /** A composer span open: both `span_id` and `name` must be present as strings. */
969
- declare function is_span_start_event(value: unknown): value is SpanStartEvent;
970
- /** A composer span close: `span_id` must be present as a string, `name` need not be. */
971
- declare function is_span_end_event(value: unknown): value is SpanEndEvent;
972
- /** A `ctx.emit` event: the kind alone identifies it, the payload is the caller's. */
973
- declare function is_emit_event(value: unknown): value is EmitEvent;
974
- /**
975
- * Parse one wire value into a trajectory event, `safeParse`-shaped.
976
- *
977
- * On success `data` is the value itself, not a copy, so nothing on the line is
978
- * dropped or reordered on the way through.
979
- */
980
- declare function parse_trajectory_event(value: unknown): TrajectoryParseResult;
981
- //#endregion
982
1080
  //#region src/engine/create_engine.d.ts
983
1081
  /**
984
1082
  * Validate `config` and construct an `Engine`.
@@ -992,6 +1090,7 @@ declare function create_engine(config: EngineConfig): Engine;
992
1090
  //#region src/engine/errors.d.ts
993
1091
  declare class rate_limit_error extends Error {
994
1092
  readonly kind: "rate_limit_error";
1093
+ readonly path?: ReadonlyArray<string>;
995
1094
  readonly retry_after_ms: number | undefined;
996
1095
  readonly attempts: number;
997
1096
  readonly status: number | undefined;
@@ -1003,6 +1102,7 @@ declare class rate_limit_error extends Error {
1003
1102
  }
1004
1103
  declare class provider_error extends Error {
1005
1104
  readonly kind: "provider_error";
1105
+ readonly path?: ReadonlyArray<string>;
1006
1106
  readonly status: number | undefined;
1007
1107
  readonly body: string | undefined;
1008
1108
  readonly cause_kind: 'provider_5xx' | 'network' | 'unknown' | undefined;
@@ -1014,12 +1114,14 @@ declare class provider_error extends Error {
1014
1114
  }
1015
1115
  declare class schema_validation_error extends Error {
1016
1116
  readonly kind: "schema_validation_error";
1117
+ readonly path?: ReadonlyArray<string>;
1017
1118
  readonly schema_issues: ReadonlyArray<SchemaIssue>;
1018
1119
  readonly raw_text: string;
1019
1120
  constructor(message: string, schema_issues: ReadonlyArray<SchemaIssue>, raw_text: string);
1020
1121
  }
1021
1122
  declare class tool_error extends Error {
1022
1123
  readonly kind: "tool_error";
1124
+ readonly path?: ReadonlyArray<string>;
1023
1125
  readonly tool_name: string;
1024
1126
  readonly tool_call_id: string;
1025
1127
  readonly cause: unknown;
@@ -1031,6 +1133,7 @@ declare class tool_error extends Error {
1031
1133
  }
1032
1134
  declare class tool_approval_denied_error extends Error {
1033
1135
  readonly kind: "tool_approval_denied_error";
1136
+ readonly path?: ReadonlyArray<string>;
1034
1137
  readonly tool_name: string;
1035
1138
  readonly step_index: number;
1036
1139
  readonly tool_call_id: string;
@@ -1042,36 +1145,55 @@ declare class tool_approval_denied_error extends Error {
1042
1145
  }
1043
1146
  declare class model_required_error extends Error {
1044
1147
  readonly kind: "model_required_error";
1148
+ readonly path?: ReadonlyArray<string>;
1045
1149
  constructor(message?: string);
1046
1150
  }
1047
1151
  declare class provider_not_configured_error extends Error {
1048
1152
  readonly kind: "provider_not_configured_error";
1153
+ readonly path?: ReadonlyArray<string>;
1049
1154
  readonly provider: string;
1050
1155
  constructor(provider: string);
1051
1156
  }
1157
+ /**
1158
+ * No provider could be resolved for a generate call: several providers are
1159
+ * configured, the call named none, and no `defaults.provider` is set. Carries
1160
+ * the configured provider names so the message tells the caller exactly what
1161
+ * the engine can route to.
1162
+ */
1163
+ declare class provider_required_error extends Error {
1164
+ readonly kind: "provider_required_error";
1165
+ readonly path?: ReadonlyArray<string>;
1166
+ readonly configured: ReadonlyArray<string>;
1167
+ constructor(configured: ReadonlyArray<string>);
1168
+ }
1052
1169
  declare class engine_config_error extends Error {
1053
1170
  readonly kind: "engine_config_error";
1171
+ readonly path?: ReadonlyArray<string>;
1054
1172
  readonly provider: string | undefined;
1055
1173
  constructor(message: string, provider?: string);
1056
1174
  }
1057
1175
  declare class on_chunk_error extends Error {
1058
1176
  readonly kind: "on_chunk_error";
1177
+ readonly path?: ReadonlyArray<string>;
1059
1178
  readonly cause: unknown;
1060
1179
  constructor(message: string, cause: unknown);
1061
1180
  }
1062
1181
  declare class provider_capability_error extends Error {
1063
1182
  readonly kind: "provider_capability_error";
1183
+ readonly path?: ReadonlyArray<string>;
1064
1184
  readonly provider: string;
1065
1185
  readonly capability: string;
1066
1186
  constructor(provider: string, capability: string, detail?: string);
1067
1187
  }
1068
1188
  declare class engine_disposed_error extends Error {
1069
1189
  readonly kind: "engine_disposed_error";
1190
+ readonly path?: ReadonlyArray<string>;
1070
1191
  constructor(message?: string);
1071
1192
  }
1072
1193
  type ClaudeCliErrorReason = 'binary_not_found' | 'auth_missing' | 'auth_expired' | 'api_key_missing' | 'startup_timeout' | 'stall_timeout' | 'no_result_event' | 'result_error' | 'subprocess_exit' | 'sandbox_unavailable' | 'engine_disposed' | 'parse_error';
1073
1194
  declare class claude_cli_error extends Error {
1074
1195
  readonly kind: "claude_cli_error";
1196
+ readonly path?: ReadonlyArray<string>;
1075
1197
  readonly reason: ClaudeCliErrorReason;
1076
1198
  readonly status: number | undefined;
1077
1199
  readonly stderr_snippet: string | undefined;
@@ -1082,6 +1204,7 @@ declare class claude_cli_error extends Error {
1082
1204
  }
1083
1205
  declare class provider_auth_error extends Error {
1084
1206
  readonly kind: "provider_auth_error";
1207
+ readonly path?: ReadonlyArray<string>;
1085
1208
  readonly provider: string;
1086
1209
  readonly refresh_command: string | undefined;
1087
1210
  constructor(provider: string, message: string, metadata?: {
@@ -1099,6 +1222,7 @@ declare class provider_auth_error extends Error {
1099
1222
  */
1100
1223
  declare class incomplete_generation_error extends Error {
1101
1224
  readonly kind: "incomplete_generation_error";
1225
+ readonly path?: ReadonlyArray<string>;
1102
1226
  readonly finish_reason: FinishReason;
1103
1227
  readonly raw_text: string;
1104
1228
  readonly provider_reported: Record<string, unknown> | undefined;
@@ -1119,12 +1243,13 @@ type AdversarialResult<candidate> = {
1119
1243
  readonly converged: boolean;
1120
1244
  readonly rounds: number;
1121
1245
  };
1122
- type AdversarialConfig<input, candidate> = {
1246
+ type AdversarialConfig<input, candidate, projected = AdversarialResult<candidate>> = {
1123
1247
  readonly name?: string;
1124
1248
  readonly build: Step<AdversarialBuildInput<input, candidate>, candidate>;
1125
1249
  readonly critique: Step<candidate, AdversarialCritiqueResult>;
1126
1250
  readonly accept: (critique_result: AdversarialCritiqueResult) => boolean;
1127
1251
  readonly max_rounds: number;
1252
+ readonly project?: (r: AdversarialResult<candidate>) => projected;
1128
1253
  };
1129
1254
  /**
1130
1255
  * Builds a Step that runs up to `max_rounds` iterations of build ->
@@ -1133,21 +1258,24 @@ type AdversarialConfig<input, candidate> = {
1133
1258
  * Each round builds a candidate (receiving the prior candidate and critique
1134
1259
  * notes when available), critiques it, then checks `accept(critique_result)`.
1135
1260
  * Returns `{ candidate, converged, rounds }`. Does not throw on
1136
- * non-convergence; `converged: false` reports it instead.
1261
+ * non-convergence; `converged: false` reports it instead. `project` maps
1262
+ * that envelope into the step's output (e.g. `(r) => r.candidate`); omitted,
1263
+ * the envelope itself is the output.
1137
1264
  *
1138
1265
  * Implemented as a `compose`d `loop` whose body builds a new candidate and
1139
1266
  * whose guard runs the critique step and checks `accept`. State is threaded
1140
1267
  * through `scope`/`stash`/`use` so the build and critique steps remain
1141
1268
  * unmodified user-supplied `Step` values.
1142
1269
  */
1143
- declare function adversarial<input, candidate>(config: AdversarialConfig<input, candidate>): Step<input, AdversarialResult<candidate>>;
1270
+ declare function adversarial<input, candidate, projected = AdversarialResult<candidate>>(config: AdversarialConfig<input, candidate, projected>): Step<input, projected>;
1144
1271
  //#endregion
1145
1272
  //#region src/composites/consensus.d.ts
1146
- type ConsensusConfig<i, o> = {
1273
+ type ConsensusConfig<i, o, projected = ConsensusResult<o>> = {
1147
1274
  readonly name?: string;
1148
1275
  readonly members: Record<string, Step<i, o>>;
1149
1276
  readonly agree: (results: Record<string, o>) => boolean;
1150
1277
  readonly max_rounds: number;
1278
+ readonly project?: (r: ConsensusResult<o>) => projected;
1151
1279
  };
1152
1280
  type ConsensusResult<o> = {
1153
1281
  readonly result: Record<string, o>;
@@ -1160,19 +1288,22 @@ type ConsensusResult<o> = {
1160
1288
  * On agreement, returns the round's results with `converged: true`.
1161
1289
  * Otherwise re-runs all members up to `max_rounds` times and returns the
1162
1290
  * last results with `converged: false` if no agreement is reached.
1291
+ * `project` maps the `{ result, converged }` envelope into the step's output
1292
+ * (e.g. `(r) => r.converged`); omitted, the envelope itself is the output.
1163
1293
  *
1164
1294
  * Implemented as a `compose`d `loop` whose body runs `parallel(members)` and
1165
1295
  * whose guard evaluates `agree`. State carries the original input alongside
1166
1296
  * the most recent results so each round receives the same input.
1167
1297
  */
1168
- declare function consensus<i, o>(config: ConsensusConfig<i, o>): Step<i, ConsensusResult<o>>;
1298
+ declare function consensus<i, o, projected = ConsensusResult<o>>(config: ConsensusConfig<i, o, projected>): Step<i, projected>;
1169
1299
  //#endregion
1170
1300
  //#region src/composites/ensemble.d.ts
1171
- type EnsembleConfig<i, o> = {
1301
+ type EnsembleConfig<i, o, projected = EnsembleResult<o>> = {
1172
1302
  readonly name?: string;
1173
1303
  readonly members: Record<string, Step<i, o>>;
1174
1304
  readonly score: (result: o, member_id: string) => number | Promise<number>;
1175
1305
  readonly select?: 'max' | 'min';
1306
+ readonly project?: (r: EnsembleResult<o>) => projected;
1176
1307
  };
1177
1308
  type EnsembleResult<o> = {
1178
1309
  readonly winner: o;
@@ -1184,21 +1315,24 @@ type EnsembleResult<o> = {
1184
1315
  *
1185
1316
  * `select` picks the highest (`'max'`, the default) or lowest (`'min'`)
1186
1317
  * score. Tie-breaking is "any tied result is acceptable": the first member
1187
- * (in `members` key order) holding the best score wins.
1318
+ * (in `members` key order) holding the best score wins. `project` maps the
1319
+ * `{ winner, scores }` envelope into the step's output (e.g. `(r) =>
1320
+ * r.winner`); omitted, the envelope itself is the output.
1188
1321
  *
1189
1322
  * Implemented as a `compose`d `sequence` of `parallel(members)` followed by
1190
1323
  * a single picking step. Cancellation, fan-out, and abort propagation come
1191
1324
  * from `parallel`'s own contract.
1192
1325
  */
1193
- declare function ensemble<i, o>(config: EnsembleConfig<i, o>): Step<i, EnsembleResult<o>>;
1326
+ declare function ensemble<i, o, projected = EnsembleResult<o>>(config: EnsembleConfig<i, o, projected>): Step<i, projected>;
1194
1327
  //#endregion
1195
1328
  //#region src/composites/ensemble_step.d.ts
1196
- type EnsembleStepConfig<i, o, ranked> = {
1329
+ type EnsembleStepConfig<i, o, ranked, projected = EnsembleStepResult<o, ranked>> = {
1197
1330
  readonly name?: string;
1198
1331
  readonly members: Record<string, Step<i, o>>;
1199
1332
  readonly score: Step<o, ranked>;
1200
1333
  readonly rank_by: (r: ranked) => number;
1201
1334
  readonly select?: 'max' | 'min';
1335
+ readonly project?: (r: EnsembleStepResult<o, ranked>) => projected;
1202
1336
  };
1203
1337
  type EnsembleStepResult<o, ranked> = {
1204
1338
  readonly winner_id: string;
@@ -1218,14 +1352,40 @@ type EnsembleStepResult<o, ranked> = {
1218
1352
  *
1219
1353
  * The result carries `winner_scored`, the structured output from the round's
1220
1354
  * scoring run preserved verbatim, so callers never pay to re-score the
1221
- * winner. `scored` holds the structured score for every member.
1355
+ * winner. `scored` holds the structured score for every member. `project`
1356
+ * maps that envelope into the step's output (e.g. `(r) => r.winner`);
1357
+ * omitted, the envelope itself is the output.
1222
1358
  *
1223
1359
  * Implemented as a `compose`d `scope` over (`stash(parallel(members))` ->
1224
1360
  * `to_pairs` -> `map(score per result, threading id)` -> `use` to pick the
1225
1361
  * winner). Cancellation, fan-out, and abort propagation come from the
1226
1362
  * underlying `parallel` and `map` contracts.
1227
1363
  */
1228
- declare function ensemble_step<i, o, ranked>(config: EnsembleStepConfig<i, o, ranked>): Step<i, EnsembleStepResult<o, ranked>>;
1364
+ declare function ensemble_step<i, o, ranked, projected = EnsembleStepResult<o, ranked>>(config: EnsembleStepConfig<i, o, ranked, projected>): Step<i, projected>;
1365
+ //#endregion
1366
+ //#region src/composites/gate.d.ts
1367
+ type GateConfig<o> = {
1368
+ readonly id: string;
1369
+ readonly name?: string;
1370
+ readonly store?: CheckpointStore;
1371
+ readonly format?: (result: o) => unknown;
1372
+ };
1373
+ /**
1374
+ * Build a Step that runs `inner`, checkpoints its result at `gate:<id>`, and
1375
+ * suspends with that result as the payload awaiting approval.
1376
+ *
1377
+ * On resume (any defined resume value) the gate resolves to the inner result
1378
+ * unchanged; the decision itself is discarded. On a re-run against the same
1379
+ * store, the checkpoint absorbs the replay so `inner` never re-executes.
1380
+ * Throws at construction time when `inner` is anonymous, because the cached
1381
+ * result must map back to a stable step.
1382
+ *
1383
+ * Implemented as a `compose`d `scope`: the checkpointed result is stashed,
1384
+ * projected into the approver's view, and handed to `suspend`; the suspend's
1385
+ * `combine` returns a `use` step that restores the stashed result, which is
1386
+ * how the decision stays signal-only.
1387
+ */
1388
+ declare function gate<i, o>(inner: Step<i, o>, config: GateConfig<o>): Step<i, o>;
1229
1389
  //#endregion
1230
1390
  //#region src/composites/improve.d.ts
1231
1391
  type Candidate<c> = {
@@ -1255,7 +1415,7 @@ type ImproveBudget = {
1255
1415
  readonly max_wallclock_ms?: number;
1256
1416
  readonly patience: number;
1257
1417
  };
1258
- type ImproveConfig<i, c> = {
1418
+ type ImproveConfig<i, c, projected = ImproveResult<c>> = {
1259
1419
  readonly name?: string;
1260
1420
  readonly seed: Step<i, {
1261
1421
  readonly content: c;
@@ -1267,6 +1427,7 @@ type ImproveConfig<i, c> = {
1267
1427
  readonly epsilon?: number;
1268
1428
  readonly proposers_per_round?: number;
1269
1429
  readonly lessons_capacity?: number;
1430
+ readonly project?: (r: ImproveResult<c>) => projected;
1270
1431
  };
1271
1432
  type HistoryEntry<c> = {
1272
1433
  readonly round: number;
@@ -1291,7 +1452,9 @@ type ImproveResult<c> = {
1291
1452
  * Rejected rounds with a `reason` feed a bounded lessons list back into the
1292
1453
  * next round's input. Plateau detection stops the loop early when no
1293
1454
  * progress has been made for `patience` rounds; an optional wall-clock
1294
- * budget caps total runtime.
1455
+ * budget caps total runtime. `project` maps the result envelope into the
1456
+ * step's output (e.g. `(r) => r.best.content`); omitted, the envelope
1457
+ * itself is the output.
1295
1458
  *
1296
1459
  * Implemented as a `compose`d `scope` of (seed) -> (init state) -> (loop) ->
1297
1460
  * (unwrap). The loop body is itself a small `scope` that snapshots prior
@@ -1299,7 +1462,7 @@ type ImproveResult<c> = {
1299
1462
  * `ensemble_step`, and merges the outcome back into state via `use`.
1300
1463
  * State threading is the entire job.
1301
1464
  */
1302
- declare function improve<i, c>(config: ImproveConfig<i, c>): Step<i, ImproveResult<c>>;
1465
+ declare function improve<i, c, projected = ImproveResult<c>>(config: ImproveConfig<i, c, projected>): Step<i, projected>;
1303
1466
  //#endregion
1304
1467
  //#region src/composites/learn.d.ts
1305
1468
  type TrajectorySource = {
@@ -1325,7 +1488,7 @@ type Improvement = {
1325
1488
  };
1326
1489
  type LearnConfig<i extends LearnInput, o> = {
1327
1490
  readonly name?: string;
1328
- readonly flow: Step<unknown, unknown>;
1491
+ readonly flow: AnyStep;
1329
1492
  readonly source: TrajectorySource;
1330
1493
  readonly analyzer: Step<i, o>;
1331
1494
  readonly filter?: (event: TrajectoryEvent) => boolean;
@@ -1353,10 +1516,11 @@ type BracketRecord = {
1353
1516
  readonly b_id: string;
1354
1517
  readonly winner_id: string;
1355
1518
  };
1356
- type TournamentConfig<i, o> = {
1519
+ type TournamentConfig<i, o, projected = TournamentResult<o>> = {
1357
1520
  readonly name?: string;
1358
1521
  readonly members: Record<string, Step<i, o>>;
1359
1522
  readonly compare: (a: o, b: o) => Promise<'a' | 'b'> | 'a' | 'b';
1523
+ readonly project?: (r: TournamentResult<o>) => projected;
1360
1524
  };
1361
1525
  type TournamentResult<o> = {
1362
1526
  readonly winner: o;
@@ -1367,9 +1531,11 @@ type TournamentResult<o> = {
1367
1531
  *
1368
1532
  * All members run concurrently via `parallel`; the bracket step then reduces
1369
1533
  * survivors round by round with `compare`, recording every match. Requires at
1370
- * least one member so a winner always exists.
1534
+ * least one member so a winner always exists. `project` maps the `{ winner,
1535
+ * bracket }` envelope into the step's output (e.g. `(r) => r.winner`);
1536
+ * omitted, the envelope itself is the output.
1371
1537
  */
1372
- declare function tournament<i, o>(config: TournamentConfig<i, o>): Step<i, TournamentResult<o>>;
1538
+ declare function tournament<i, o, projected = TournamentResult<o>>(config: TournamentConfig<i, o, projected>): Step<i, projected>;
1373
1539
  //#endregion
1374
1540
  //#region src/composites/errors.d.ts
1375
1541
  /**
@@ -1381,6 +1547,7 @@ declare function tournament<i, o>(config: TournamentConfig<i, o>): Step<i, Tourn
1381
1547
  */
1382
1548
  declare class bench_suspend_error extends Error {
1383
1549
  readonly kind: "bench_suspend_error";
1550
+ readonly path?: ReadonlyArray<string>;
1384
1551
  readonly case_id: string;
1385
1552
  readonly suspend_id: string;
1386
1553
  constructor(case_id: string, suspend_id: string, message?: string);
@@ -1551,17 +1718,18 @@ declare function write_baseline(path: string, report: BenchReport): Promise<void
1551
1718
  //#endregion
1552
1719
  //#region src/model_call.d.ts
1553
1720
  type ModelCallInput = string | ReadonlyArray<Message>;
1554
- type ModelCallConfig<T = string> = {
1721
+ type ModelCallConfig<T = string, projected = GenerateResult<T>> = {
1555
1722
  readonly engine: Engine;
1556
1723
  /**
1557
- * Model or alias string. Optional: if omitted, the engine's
1558
- * `defaults.model` is used. Errors at call time if neither is set.
1724
+ * Model id, sent to the provider verbatim (there is no alias layer).
1725
+ * Optional: if omitted, the engine's `defaults.model` is used. Errors at
1726
+ * call time if neither is set.
1559
1727
  */
1560
1728
  readonly model?: string;
1561
1729
  /**
1562
1730
  * Transport for the model: `anthropic` | `claude_cli` | `openrouter` | ...
1563
- * Optional: if omitted, the engine's `defaults.provider` (or sole configured
1564
- * provider, else `anthropic`) is used.
1731
+ * Optional: if omitted, the engine's `defaults.provider` (or its sole
1732
+ * configured provider) is used.
1565
1733
  */
1566
1734
  readonly provider?: string;
1567
1735
  readonly id?: string;
@@ -1569,7 +1737,20 @@ type ModelCallConfig<T = string> = {
1569
1737
  readonly tools?: ReadonlyArray<Tool>;
1570
1738
  readonly schema?: ToolSchema<T>;
1571
1739
  readonly effort?: EffortLevel;
1740
+ readonly temperature?: number;
1741
+ readonly max_tokens?: number;
1742
+ readonly top_p?: number;
1572
1743
  readonly max_steps?: number;
1744
+ /**
1745
+ * Per-turn wall-clock budget in milliseconds, forwarded to the engine.
1746
+ * See `GenerateOptions.turn_timeout_ms`.
1747
+ */
1748
+ readonly turn_timeout_ms?: number;
1749
+ /**
1750
+ * Per-turn message hook, forwarded to the engine. See
1751
+ * `GenerateOptions.prepare_step`.
1752
+ */
1753
+ readonly prepare_step?: PrepareStepHook;
1573
1754
  readonly provider_options?: Record<string, unknown>;
1574
1755
  readonly retry_policy?: RetryPolicy;
1575
1756
  readonly tool_error_policy?: 'feed_back' | 'throw';
@@ -1577,6 +1758,13 @@ type ModelCallConfig<T = string> = {
1577
1758
  readonly tool_call_repair_attempts?: number;
1578
1759
  readonly max_tool_calls_per_step?: number;
1579
1760
  readonly on_tool_approval?: ToolApprovalHandler;
1761
+ /**
1762
+ * Map the `GenerateResult` envelope into the step's output at the source.
1763
+ * The projection runs inside the model_call step itself, so `describe` and
1764
+ * the trajectory gain no wrapper node. Omitted, the envelope is the output.
1765
+ * `model_step` is this option preset to `(r) => r.content`.
1766
+ */
1767
+ readonly project?: (r: GenerateResult<T>) => projected;
1580
1768
  };
1581
1769
  /**
1582
1770
  * Build a `Step` that calls `cfg.engine.generate` with `cfg` translated into
@@ -1584,9 +1772,28 @@ type ModelCallConfig<T = string> = {
1584
1772
  *
1585
1773
  * Threads `ctx.abort` and `ctx.trajectory` (nested under the model_call
1586
1774
  * step's own span) into every call, and, when `run.stream` is driving,
1587
- * records each chunk as a `model_chunk` trajectory event.
1775
+ * records each chunk as a `model_chunk` trajectory event. `cfg.project`
1776
+ * maps the `GenerateResult` envelope into the step's output inside the same
1777
+ * step; omitted, the envelope is the output.
1778
+ */
1779
+ declare function model_call<T = string, projected = GenerateResult<T>>(cfg: ModelCallConfig<T, projected>): Step<ModelCallInput, projected>;
1780
+ /**
1781
+ * model_step: `model_call` projected to its content.
1782
+ *
1783
+ * Returns a Step whose output is the model's final content (a `string`, or
1784
+ * the schema-validated value when `cfg.schema` is set) instead of the full
1785
+ * `GenerateResult` envelope. Use `model_step` when the flow only wants the
1786
+ * answer, keeping compositions at the `step, step, model_step, step` cadence;
1787
+ * drop to `model_call` when the caller needs usage, cost, tool calls, or
1788
+ * finish reason (or its `project` option, when the flow wants a slice of the
1789
+ * envelope mapped at the source).
1790
+ *
1791
+ * Implemented as `model_call` with `project` preset to `(r) => r.content`,
1792
+ * so the leaf is a single node in `describe` and the trajectory. Wrapping a
1793
+ * primitive into an app-shaped helper of your own is still the extension
1794
+ * pattern; this is its smallest instance.
1588
1795
  */
1589
- declare function model_call<T = string>(cfg: ModelCallConfig<T>): Step<ModelCallInput, GenerateResult<T>>;
1796
+ declare function model_step<T = string>(cfg: Omit<ModelCallConfig<T>, 'project'>): Step<ModelCallInput, T>;
1590
1797
  //#endregion
1591
1798
  //#region src/forward_standard_env.d.ts
1592
1799
  /**
@@ -1602,48 +1809,5 @@ declare function model_call<T = string>(cfg: ModelCallConfig<T>): Step<ModelCall
1602
1809
  */
1603
1810
  declare function forward_standard_env(): Record<string, string>;
1604
1811
  //#endregion
1605
- //#region src/viewer/start_viewer.d.ts
1606
- /**
1607
- * `start_viewer` programmatic embed implementation.
1608
- *
1609
- * Spin up the server, optionally start tailing a JSONL file, and return a
1610
- * handle that can stop both. `start_viewer` only depends on core's wire-format
1611
- * schema; it never reaches into the engine, composites, or any provider.
1612
- */
1613
- type StartViewerOptions = {
1614
- readonly path?: string;
1615
- readonly host?: string;
1616
- readonly port?: number;
1617
- readonly buffer?: number;
1618
- readonly on_parse_error?: (err: unknown, line: string) => void;
1619
- readonly on_io_error?: (err: unknown) => void;
1620
- readonly on_subscriber_error?: (err: unknown) => void;
1621
- };
1622
- type ViewerHandle = {
1623
- readonly url: string;
1624
- readonly host: string;
1625
- readonly port: number;
1626
- readonly close: () => Promise<void>;
1627
- };
1628
- /**
1629
- * Starts the viewer: brings up the HTTP/SSE server and, if `options.path`
1630
- * is set, a file tail that feeds the same broadcaster.
1631
- *
1632
- * Defaults to `127.0.0.1:4242` with a 1000-event ring buffer. HTTP ingest
1633
- * and SSE are always available; tailing is opt-in via `path`.
1634
- */
1635
- declare function start_viewer(options?: StartViewerOptions): Promise<ViewerHandle>;
1636
- //#endregion
1637
- //#region src/viewer/cli.d.ts
1638
- /**
1639
- * CLI entry point: parses argv, starts the viewer, and wires shutdown.
1640
- *
1641
- * Warns but proceeds when the tailed path does not exist yet or when the
1642
- * bind host is 0.0.0.0 (the dashboard has no auth). Optionally opens the
1643
- * browser, then installs SIGINT/SIGTERM handlers that close the viewer
1644
- * before exiting.
1645
- */
1646
- declare function run_viewer_cli(argv: readonly string[]): Promise<void>;
1647
- //#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 };
1812
+ export { type AdversarialBuildInput, type AdversarialConfig, type AdversarialCritiqueResult, type AdversarialResult, type AiSdkProviderAdapter, type AiSdkTelemetrySettings, type AnySchema, type AnyStep, type AssistantContentPart, type BenchCase, type BenchOptions, type BenchReport, type BenchSummary, type BracketRecord, type BranchConfig, type Candidate, type CaseResult, type Chain, type ChainOpen, type ChainStepOptions, type CheckpointConfig, type CheckpointEvent, type CheckpointStatus, type CheckpointStore, type ClaudeCliErrorReason, type CleanupFn, 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 FallbackOptions, type FinishReason, type FlowNode, type FlowValue, type GateConfig, 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 LoopGuardPredicate, type LoopGuardResult, type LoopOutcome, type MapConfig, type Message, type ModelCallConfig, type ModelCallInput, type NativeProviderAdapter, type ParallelOptions, type ParsedTrajectoryEvent, type PerCaseDelta, type PipeOptions, 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 RetryConfig, type RetryFailureKind, type RetryPolicy, type RunContext, type RunEndEvent, type RunEndStatus, type RunOptions, type RunOutcome, STEP_KINDS, type SchemaIssue, type ScopeOptions, type Score, type ScoredCandidate, type SequenceOptions, type SpanEndEvent, type SpanStartEvent, type StashOptions, type Step, type StepFn, type StepInput, type StepKind, type StepMetadata, type StepOutput, type StepRecord, type StreamChunk, type StreamingRunHandle, type SuspendConfig, type TimeoutOptions, type Tool, type ToolApprovalHandler, type ToolApprovalRequest, type ToolCallRecord, type ToolExecContext, type ToolSchema, type TournamentConfig, type TournamentResult, type TrajectoryEvent, type TrajectoryLogger, type TrajectoryParseResult, type TrajectorySource, type TurnRequest, type TurnResult, type UsageTotals, type UseOptions, type UserContentPart, 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, error_path, fallback, __json_default_export as flow_schema, forward_standard_env, gate, improve, incomplete_generation_error, is_checkpoint_event, is_custom_trajectory_event, is_emit_event, is_run_end_event, is_span_end_event, is_span_start_event, is_step, 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, provider_required_error, rate_limit_error, read_baseline, regression_compare, resume_validation_error, retry, run, schema_validation_error, scope, sequence, stash, step, suspend, suspended_error, timeout, timeout_error, tool_approval_denied_error, tool_error, tournament, use, write_baseline };
1649
1813
  //# sourceMappingURL=index.d.ts.map