@effect-uai/core 0.5.2 → 0.7.0

package/src/loop/Loop.ts

@@ -1,10 +1,10 @@
 /**
  * Pull-based `loop` for state-threaded sub-streams.
  *
- * Each iteration runs a body that returns a `Stream<Event<A, S>>`. The body
+ * Each iteration runs a body that returns a `Stream<Step<A, S>>`. The body
  * emits values via `Loop.value(a)` and signals iteration control via
- * `Loop.next(state)` (continue with new state) or `Loop.stop` (terminate).
- * The loop unwraps `Value` events back to `A` for downstream consumers, so
+ * `Loop.next(state)` (continue with new state) or `Loop.stop()` (terminate).
+ * The loop unwraps `Value` steps back to `A` for downstream consumers, so
  * the resulting stream is a plain `Stream<A>`.
  *
  * The next body stream is only pulled when downstream pulls the outer
@@ -12,10 +12,11 @@
  * scoped resources, and backpressure stay aligned with normal Stream
  * semantics.
  *
- * Convention: a `Next` or `Stop` event is the terminal element of a body's
+ * Convention: a `Next` or `Stop` step is the terminal element of a body's
  * iteration. Values emitted in the same chunk after one are discarded
- * (their producing side effects may already have run). Prefer the
- * `Loop.nextAfter` / `Loop.stopAfter` helpers to terminate cleanly.
+ * (their producing side effects may already have run). The `Loop.next` /
+ * `Loop.stop` helpers each emit a single terminal step, so concatenate
+ * your values before them (`values.pipe(Stream.concat(Loop.next(state)))`).
  */
 import {
   Array as Arr,
@@ -28,7 +29,6 @@ import {
   Match,
   Option,
   Ref,
-  Result,
   Scope,
   Stream,
   SubscriptionRef,
@@ -37,165 +37,67 @@ import { IncompleteTurn } from "../domain/AiError.js"
 import { isTurnComplete, type Turn, type TurnEvent } from "../domain/Turn.js"
 
 // ---------------------------------------------------------------------------
-// Event type - the body's emit shape
+// Step type - the body's emit shape
 // ---------------------------------------------------------------------------
 
 /**
  * The tagged union a body emits per pull. `Value` carries a payload that
  * flows downstream. `Next` ends the current iteration and continues with a
  * new state. `Stop` ends the loop entirely with no carried state.
- * `StopWith` also ends the loop but carries a final state that `loopFrom`
+ * `StopWith` also ends the loop but carries a final state that `loopOver`
  * will thread to the next input and `loopWithState` will write to its
  * `SubscriptionRef` before the loop ends. Plain `loop` has no next
  * iteration to apply it to and treats `StopWith` like `Stop`.
  *
- * `Stop` is intentionally `{}` so the bare `stopEvent` / `stop` helpers
- * don't constrain `S` from a body's stream type — every body has a `Stop`
+ * `Stop` is intentionally `{}` so the bare `stop()` helper doesn't
+ * constrain `S` from a body's stream type — every body has a `Stop`
  * variant in its union, and forcing `S` to flow through it would break
- * inference whenever the body never uses `next` / `stopWith`.
+ * inference whenever the body never uses `next` / `stop(state)`.
  */
-export type Event<A, S> = Data.TaggedEnum<{
+export type Step<A, S> = Data.TaggedEnum<{
   Value: { readonly value: A }
   Next: { readonly state: S }
   Stop: {}
   StopWith: { readonly state: S }
 }>
 
-interface EventDef extends Data.TaggedEnum.WithGenerics<2> {
-  readonly taggedEnum: Event<this["A"], this["B"]>
+interface StepDef extends Data.TaggedEnum.WithGenerics<2> {
+  readonly taggedEnum: Step<this["A"], this["B"]>
 }
 
-const Event = Data.taggedEnum<EventDef>()
+const Step = Data.taggedEnum<StepDef>()
 
 /** Wrap a value so it flows through the loop to downstream consumers. */
-export const value = <A>(a: A): Event<A, never> => Event.Value({ value: a })
-
-/** End the current iteration and continue with a new state. */
-export const next = <S>(state: S): Event<never, S> => Event.Next({ state })
-
-/**
- * The terminal `Stop` event with no carried state. Use `stop` (the Stream)
- * to end a loop body without communicating a final state.
- */
-export const stopEvent: Event<never, never> = Event.Stop()
-
-/**
- * Terminal event that ends the loop AND carries a final state. For
- * `loopFrom` this is the natural "this input is done, here's the state to
- * carry forward to the next input" signal — symmetric with `next(s)` but
- * ending the inner loop instead of continuing it. For `loopWithState` the
- * carried state is written to the `SubscriptionRef` before the loop ends.
- */
-export const stopWith = <S>(state: S): Event<never, S> => Event.StopWith({ state })
-
-/**
- * A single-element stream that ends the loop. Return this from a body when
- * there's nothing else to emit; equivalent to `stopAfter(Stream.empty)` but
- * named for the common case.
- */
-export const stop: Stream.Stream<Event<never, never>> = Stream.succeed(stopEvent)
-
-/**
- * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate the
- * iteration with `next(state)`. Common shape for "stream this turn's
- * deltas, then continue with updated history."
- *
- * Dual: data-first `nextAfter(stream, state)` and data-last
- * `stream.pipe(nextAfter(state))` both work.
- */
-export const nextAfter: {
-  <S>(state: S): <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, S>, E, R>
-  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, E, R>
-} = Function.dual(
-  2,
-  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, E, R> =>
-    Stream.concat(Stream.map(stream, value), Stream.fromIterable([next(state)])),
-)
-
-/**
- * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate the
- * loop. Common shape for "stream this turn's deltas, then we're done."
- *
- * Unary on the stream — already pipe-compatible via `stream.pipe(stopAfter)`.
- */
-export const stopAfter = <A, E, R>(
-  stream: Stream.Stream<A, E, R>,
-): Stream.Stream<Event<A, never>, E, R> =>
-  Stream.concat(Stream.map(stream, value), Stream.fromIterable([stopEvent]))
+export const value = <A>(a: A): Step<A, never> => Step.Value({ value: a })
 
 /**
- * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate with
- * `stopWith(state)`. The natural "emit final outputs, advance state, end
- * this input's inner loop" shape for `loopFrom`.
- *
- * Dual: data-first `stopWithAfter(stream, state)` and data-last
- * `stream.pipe(stopWithAfter(state))` both work.
+ * End the current iteration and continue with a new state. Emits a single
+ * terminal `Next` step as a one-element stream, so it slots directly into a
+ * loop body or after a run of values: `values.pipe(Stream.concat(next(s)))`.
  */
-export const stopWithAfter: {
-  <S>(state: S): <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, S>, E, R>
-  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, E, R>
-} = Function.dual(
-  2,
-  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, E, R> =>
-    Stream.concat(Stream.map(stream, value), Stream.fromIterable([stopWith(state)])),
-)
+export const next = <S>(state: S): Stream.Stream<Step<never, S>> =>
+  Stream.succeed(Step.Next({ state }))
 
 /**
- * General `nextAfter` variant: drain `stream` to the consumer, fold elements
- * into an accumulator, and at end-of-stream emit one `next(build(finalAcc))`.
- *
- * Subsumes `nextAfter` when state is constant (`reduce: (s, _) => s`,
- * `build: (s) => s`). Used by `Toolkit.continueWith` to collect tool
- * results and build next state without exposing a Ref to recipes.
- *
- * Dual: data-first `nextAfterFold(stream, initial, reduce, build)` and
- * data-last `stream.pipe(nextAfterFold(initial, reduce, build))` both work.
+ * End the loop. Called with no argument it emits a bare `Stop`; called with
+ * a state it emits `StopWith(state)` — `loopOver` threads that final state
+ * to the next input and `loopWithState` writes it to its `SubscriptionRef`
+ * before the loop ends. Either way it returns a single-element stream, so
+ * return it directly from a loop body.
  */
-export const nextAfterFold: {
-  <A, B, S>(
-    initial: B,
-    reduce: (acc: B, a: A) => B,
-    build: (b: B) => S,
-  ): <E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, S>, E, R>
-  <A, B, S, E, R>(
-    stream: Stream.Stream<A, E, R>,
-    initial: B,
-    reduce: (acc: B, a: A) => B,
-    build: (b: B) => S,
-  ): Stream.Stream<Event<A, S>, E, R>
-} = Function.dual(
-  4,
-  <A, B, S, E, R>(
-    stream: Stream.Stream<A, E, R>,
-    initial: B,
-    reduce: (acc: B, a: A) => B,
-    build: (b: B) => S,
-  ): Stream.Stream<Event<A, S>, E, R> =>
-    Stream.unwrap(
-      Effect.gen(function* () {
-        const ref = yield* Ref.make(initial)
-        const tapped = stream.pipe(
-          Stream.tap((a) => Ref.update(ref, (acc) => reduce(acc, a))),
-          Stream.map(value),
-        )
-        const continuation = Stream.fromEffect(
-          Ref.get(ref).pipe(Effect.map((acc) => next(build(acc)))),
-        )
-        return tapped.pipe(Stream.concat(continuation))
-      }),
-    ),
-)
+export const stop = <S = never>(state?: S): Stream.Stream<Step<never, S>> =>
+  Stream.succeed<Step<never, S>>(state === undefined ? Step.Stop() : Step.StopWith({ state }))
 
 // ---------------------------------------------------------------------------
 // onTurnComplete - turn-aware stream operator for loop bodies
 // ---------------------------------------------------------------------------
 
 /**
- * Lift a provider's `Stream<TurnEvent>` into a loop body's `Stream<Event<TurnEvent | A, S>>`.
+ * Lift a provider's `Stream<TurnEvent>` into a loop body's `Stream<Step<TurnEvent | A, S>>`.
  * Each delta passes through as `value(delta)` (including the terminal
  * `TurnComplete`, so the consumer sees turn boundaries naturally). Once
  * the terminal arrives, `then(turn)` runs and its returned stream of loop
- * events (typically tool outputs followed by `next(state)` or `stop`) is
+ * steps (typically tool outputs followed by `next(state)` or `stop()`) is
  * concatenated.
  *
  * Pre-pipe transforms (`Stream.tap` / `Stream.map` / `Stream.filter`) on
@@ -210,25 +112,25 @@ export const nextAfterFold: {
  */
 export const onTurnComplete: {
   <S, A, E2 = never, R2 = never>(
-    then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>,
+    then: (turn: Turn) => Effect.Effect<Stream.Stream<Step<A, S>, E2, R2>, E2, R2>,
   ): <E, R>(
     deltas: Stream.Stream<TurnEvent, E, R>,
-  ) => Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>
+  ) => Stream.Stream<Step<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>
   <S, A, E, R, E2 = never, R2 = never>(
     deltas: Stream.Stream<TurnEvent, E, R>,
-    then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>,
-  ): Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>
+    then: (turn: Turn) => Effect.Effect<Stream.Stream<Step<A, S>, E2, R2>, E2, R2>,
+  ): Stream.Stream<Step<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>
 } = Function.dual(
   2,
   <S, A, E, R, E2, R2>(
     deltas: Stream.Stream<TurnEvent, E, R>,
-    then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>,
-  ): Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2> =>
+    then: (turn: Turn) => Effect.Effect<Stream.Stream<Step<A, S>, E2, R2>, E2, R2>,
+  ): Stream.Stream<Step<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2> =>
     Stream.unwrap(
       Effect.gen(function* () {
         const turnRef = yield* Ref.make<Option.Option<Turn>>(Option.none())
 
-        const events: Stream.Stream<Event<TurnEvent, S>, E, R> = deltas.pipe(
+        const events: Stream.Stream<Step<TurnEvent, S>, E, R> = deltas.pipe(
           Stream.tap((delta) =>
             isTurnComplete(delta) ? Ref.set(turnRef, Option.some(delta.turn)) : Effect.void,
           ),
@@ -257,7 +159,7 @@ const isNonEmpty = <A>(array: ReadonlyArray<A>): array is readonly [A, ...Array<
 
 type CurrentBody<S, A, E, R> = {
   readonly scope: Scope.Closeable
-  readonly pull: Effect.Effect<ReadonlyArray<Event<A, S>>, E | Cause.Done<void>, R>
+  readonly pull: Effect.Effect<ReadonlyArray<Step<A, S>>, E | Cause.Done<void>, R>
 }
 
 const closeBody = <S, A, E, R>(
@@ -266,23 +168,23 @@ const closeBody = <S, A, E, R>(
 ) => Scope.close(current.scope, exit)
 
 /**
- * Walk a chunk of `Event<A, S>` until a terminal `Next` or `Stop` is found.
+ * Walk a chunk of `Step<A, S>` until a terminal `Next` or `Stop` is found.
  * Returns the unwrapped values seen so far and (optionally) the terminal
- * event. Anything in the chunk after the terminal is discarded - its
+ * step. Anything in the chunk after the terminal is discarded - its
  * producing side effects may have run, but downstream never sees it.
  */
 const partitionChunk = <A, S>(
-  chunk: ReadonlyArray<Event<A, S>>,
+  chunk: ReadonlyArray<Step<A, S>>,
 ): {
   readonly values: ReadonlyArray<A>
-  readonly decision: Option.Option<Event<A, S>>
+  readonly decision: Option.Option<Step<A, S>>
 } => {
-  const [valueEvents, rest] = Arr.span(
+  const [valueSteps, rest] = Arr.span(
     chunk,
-    (e): e is Event<A, S> & { _tag: "Value" } => e._tag === "Value",
+    (e): e is Step<A, S> & { _tag: "Value" } => e._tag === "Value",
   )
   return {
-    values: valueEvents.map((e) => e.value),
+    values: valueSteps.map((e) => e.value),
     decision: Arr.head(rest),
   }
 }
@@ -293,12 +195,12 @@ const partitionChunk = <A, S>(
 
 type LoopBody<S, A, E, R> = (
   state: S,
-) => Stream.Stream<Event<A, S>, E, R> | Effect.Effect<Stream.Stream<Event<A, S>, E, R>, E, R>
+) => Stream.Stream<Step<A, S>, E, R> | Effect.Effect<Stream.Stream<Step<A, S>, E, R>, E, R>
 
 /**
  * Drive a state-threaded loop body. Each iteration runs `body(state)` to get
- * a `Stream<Event<A, S>>`; values flow downstream, `next(s)` continues with
- * a new state, `stop` ends the loop. See the file header for the full
+ * a `Stream<Step<A, S>>`; values flow downstream, `next(s)` continues with
+ * a new state, `stop()` ends the loop. See the file header for the full
  * pull-based execution model.
  *
  * Dual: data-first `loop(initial, body)` and data-last `loop(body)(initial)`
@@ -352,7 +254,7 @@ export const loop: {
               const chunk = yield* active.pull.pipe(
                 Effect.catchIf(Cause.isDone, () =>
                   closeActive(active, Exit.void).pipe(
-                    Effect.as(undefined as ReadonlyArray<Event<A, S>> | undefined),
+                    Effect.as(undefined as ReadonlyArray<Step<A, S>> | undefined),
                   ),
                 ),
                 Effect.onError((cause) => closeActive(active, Exit.failCause(cause))),
@@ -369,7 +271,7 @@ export const loop: {
                 yield* closeActive(active, Exit.void)
                 if (decision.value._tag === "Stop" || decision.value._tag === "StopWith") {
                   // `loop` has no next iteration to apply StopWith's state to;
-                  // the state lands in `loopFrom`'s outer ref or
+                  // the state lands in `loopOver`'s outer ref or
                   // `loopWithState`'s SubscriptionRef via their taps.
                   done = true
                 } else if (decision.value._tag === "Next") {
@@ -378,7 +280,7 @@ export const loop: {
               }
 
               // Emit the values seen so far if any. Chunks from a Stream pull
-              // are non-empty, so when `decision` is `None` every event was
+              // are non-empty, so when `decision` is `None` every step was
               // a `Value` and `values` is non-empty here. With a decision and
               // no preceding values, fall through to the next iteration.
               if (isNonEmpty(values)) return values
@@ -392,54 +294,54 @@ export const loop: {
 )
 
 // ---------------------------------------------------------------------------
-// loopFrom - stream-driven sibling of loop. One input item runs a full
+// loopOver - stream-driven sibling of loop. One input item runs a full
 // multi-turn inner loop.
 // ---------------------------------------------------------------------------
 
-type LoopFromBody<S, I, A, E, R> = (
+type LoopOverBody<S, I, A, E, R> = (
   state: S,
   input: I,
-) => Stream.Stream<Event<A, S>, E, R> | Effect.Effect<Stream.Stream<Event<A, S>, E, R>, E, R>
+) => Stream.Stream<Step<A, S>, E, R> | Effect.Effect<Stream.Stream<Step<A, S>, E, R>, E, R>
 
 /**
  * Input-driven sibling of `loop`. For each item pulled from the input
  * stream, runs an inner seed-driven `loop` whose body is
  * `(s) => body(s, item)`. State is threaded across input items.
  *
- * **Per-input semantics — the body emits standard `Event<A, S>`:**
+ * **Per-input semantics — the body emits standard `Step<A, S>`:**
  *   - `value(a)`: emit `a` downstream
  *   - `next(s)`: re-run the body with the SAME input and new state `s`
  *     (multi-turn within one input — e.g. multiple model turns + tool
  *     calls for one document)
- *   - `stop`: end this input's inner loop, advance to the next input
+ *   - `stop()`: end this input's inner loop, advance to the next input
  *     (state preserved)
- *   - body stream ending without a decision: same as `stop` (advance)
+ *   - body stream ending without a decision: same as `stop()` (advance)
  *
  * **Outer termination:** the input stream ending. To halt programmatically
  * from within, end the input stream upstream (`Stream.takeWhile`, a
- * `SubscriptionRef` gate, etc.). Reserving `stop` for per-item
+ * `SubscriptionRef` gate, etc.). Reserving `stop()` for per-item
  * advancement is what makes the common "stream of documents, multi-turn
  * conversation per document" shape readable.
  *
- * Dual: data-first `loopFrom(input, initial, body)` and data-last
- * `input.pipe(loopFrom(initial, body))` both work.
+ * Dual: data-first `loopOver(input, initial, body)` and data-last
+ * `input.pipe(loopOver(initial, body))` both work.
  */
-export const loopFrom: {
+export const loopOver: {
   <S, I, A, E, R>(
     initial: S,
-    body: LoopFromBody<S, I, A, E, R>,
+    body: LoopOverBody<S, I, A, E, R>,
   ): <EI, RI>(input: Stream.Stream<I, EI, RI>) => Stream.Stream<A, E | EI, R | RI>
   <S, I, A, E, R, EI, RI>(
     input: Stream.Stream<I, EI, RI>,
     initial: S,
-    body: LoopFromBody<S, I, A, E, R>,
+    body: LoopOverBody<S, I, A, E, R>,
   ): Stream.Stream<A, E | EI, R | RI>
 } = Function.dual(
   3,
   <S, I, A, E, R, EI, RI>(
     input: Stream.Stream<I, EI, RI>,
     initial: S,
-    body: LoopFromBody<S, I, A, E, R>,
+    body: LoopOverBody<S, I, A, E, R>,
   ): Stream.Stream<A, E | EI, R | RI> =>
     Stream.unwrap(
       Effect.gen(function* () {
@@ -449,15 +351,15 @@ export const loopFrom: {
             Stream.unwrap(
               Effect.gen(function* () {
                 const state = yield* Ref.get(stateRef)
-                // Capture Next states (and stopWith's final state) into the
+                // Capture Next states (and stop(state)'s final state) into the
                 // outer ref so the LAST state seen in this input's inner
                 // loop is what the next input starts from.
                 const wrappedBody = (s: S) => {
                   const result = body(s, item)
                   const stream = Effect.isEffect(result) ? Stream.unwrap(result) : result
                   return stream.pipe(
-                    Stream.tap((event) =>
-                      Match.value(event).pipe(
+                    Stream.tap((step) =>
+                      Match.value(step).pipe(
                         Match.tags({
                           Next: (e) => Ref.set(stateRef, e.state),
                           StopWith: (e) => Ref.set(stateRef, e.state),
@@ -485,7 +387,7 @@ export const loopFrom: {
  * alongside the value stream.
  *
  * Allocates one `SubscriptionRef<S>` seeded with `initial`, then runs the
- * loop with a wrapped body that taps every `Next(s)` event into the ref
+ * loop with a wrapped body that taps every `Next(s)` step into the ref
  * before forwarding it. The caller decides how to consume both channels:
  *
  *   - **Final state**: drain the stream, then `SubscriptionRef.get(state)`
@@ -510,10 +412,10 @@ export const loopWithState = <S, A, E, R>(
   Effect.gen(function* () {
     const stateRef = yield* SubscriptionRef.make(initial)
 
-    const tap = (stream: Stream.Stream<Event<A, S>, E, R>): Stream.Stream<Event<A, S>, E, R> =>
+    const tap = (stream: Stream.Stream<Step<A, S>, E, R>): Stream.Stream<Step<A, S>, E, R> =>
       stream.pipe(
-        Stream.tap((event) =>
-          Match.value(event).pipe(
+        Stream.tap((step) =>
+          Match.value(step).pipe(
             Match.tags({
               Next: (e) => SubscriptionRef.set(stateRef, e.state),
               StopWith: (e) => SubscriptionRef.set(stateRef, e.state),