@effect-uai/core 0.4.0 → 0.5.1

package/dist/loop/Loop.mjs

@@ -1,7 +1,7 @@
 import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
 import { IncompleteTurn } from "../domain/AiError.mjs";
 import { isTurnComplete } from "../domain/Turn.mjs";
-import { Cause, Channel, Data, Effect, Exit, Function, Option, Ref, Scope, Stream, SubscriptionRef } from "effect";
+import { Array, Cause, Channel, Data, Effect, Exit, Function, Match, Option, Ref, Scope, Stream, SubscriptionRef } from "effect";
 //#region src/loop/Loop.ts
 /**
 * Pull-based `loop` for state-threaded sub-streams.
@@ -24,6 +24,7 @@ import { Cause, Channel, Data, Effect, Exit, Function, Option, Ref, Scope, Strea
 */
 var Loop_exports = /* @__PURE__ */ __exportAll({
 	loop: () => loop,
+	loopFrom: () => loopFrom,
 	loopWithState: () => loopWithState,
 	next: () => next,
 	nextAfter: () => nextAfter,
@@ -32,6 +33,8 @@ var Loop_exports = /* @__PURE__ */ __exportAll({
 	stop: () => stop,
 	stopAfter: () => stopAfter,
 	stopEvent: () => stopEvent,
+	stopWith: () => stopWith,
+	stopWithAfter: () => stopWithAfter,
 	value: () => value
 });
 const Event = Data.taggedEnum();
@@ -39,9 +42,20 @@ const Event = Data.taggedEnum();
 const value = (a) => Event.Value({ value: a });
 /** End the current iteration and continue with a new state. */
 const next = (state) => Event.Next({ state });
-/** The terminal `Stop` event. Use `stop` (the Stream) to end a loop body. */
+/**
+* The terminal `Stop` event with no carried state. Use `stop` (the Stream)
+* to end a loop body without communicating a final state.
+*/
 const stopEvent = 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.
+*/
+const stopWith = (state) => 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.
@@ -51,31 +65,48 @@ const stop = 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.
 */
-const nextAfter = (stream, state) => Stream.concat(Stream.map(stream, value), Stream.fromIterable([next(state)]));
+const nextAfter = Function.dual(2, (stream, state) => 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)`.
 */
 const stopAfter = (stream) => Stream.concat(Stream.map(stream, value), Stream.fromIterable([stopEvent]));
 /**
+* 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.
+*/
+const stopWithAfter = Function.dual(2, (stream, state) => Stream.concat(Stream.map(stream, value), Stream.fromIterable([stopWith(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.
 */
-const nextAfterFold = (stream, initial, reduce, build) => Stream.unwrap(Effect.gen(function* () {
+const nextAfterFold = Function.dual(4, (stream, initial, reduce, build) => 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));
-}));
+})));
 /**
 * Lift a provider's `Stream<TurnEvent>` into a loop body's `Stream<Event<TurnEvent | A, S>>`.
 * Each delta passes through as `value(delta)` (including the terminal
-* `turn_complete`, so the consumer sees turn boundaries naturally). Once
+* `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
 * concatenated.
@@ -83,20 +114,23 @@ const nextAfterFold = (stream, initial, reduce, build) => Stream.unwrap(Effect.g
 * Pre-pipe transforms (`Stream.tap` / `Stream.map` / `Stream.filter`) on
 * the raw delta stream cover anything an `emit`-style callback would do.
 *
-* If the upstream ends without a `turn_complete`, the resulting stream
+* If the upstream ends without a `TurnComplete`, the resulting stream
 * fails with `AiError.IncompleteTurn`. Catch it via `Stream.catchTag` if
 * you want to recover.
+*
+* Dual: data-first `onTurnComplete(deltas, then)` and data-last
+* `deltas.pipe(onTurnComplete(then))` both work.
 */
-const onTurnComplete = (then) => (deltas) => Stream.unwrap(Effect.gen(function* () {
+const onTurnComplete = Function.dual(2, (deltas, then) => Stream.unwrap(Effect.gen(function* () {
 	const turnRef = yield* Ref.make(Option.none());
 	const events = deltas.pipe(Stream.tap((delta) => isTurnComplete(delta) ? Ref.set(turnRef, Option.some(delta.turn)) : Effect.void), Stream.map(value));
 	const continuation = Stream.unwrap(Effect.gen(function* () {
 		const opt = yield* Ref.get(turnRef);
-		if (Option.isNone(opt)) return yield* Effect.fail(new IncompleteTurn({}));
+		if (Option.isNone(opt)) return yield* new IncompleteTurn({});
 		return yield* then(opt.value);
 	}));
 	return Stream.concat(events, continuation);
-}));
+})));
 const isNonEmpty = (array) => array.length > 0;
 const closeBody = (current, exit) => Scope.close(current.scope, exit);
 /**
@@ -106,18 +140,10 @@ const closeBody = (current, exit) => Scope.close(current.scope, exit);
 * producing side effects may have run, but downstream never sees it.
 */
 const partitionChunk = (chunk) => {
-	const values = [];
-	for (let i = 0; i < chunk.length; i++) {
-		const event = chunk[i];
-		if (event._tag === "Value") values.push(event.value);
-		else return {
-			values,
-			decision: event
-		};
-	}
+	const [valueEvents, rest] = Array.span(chunk, (e) => e._tag === "Value");
 	return {
-		values,
-		decision: void 0
+		values: valueEvents.map((e) => e.value),
+		decision: Array.head(rest)
 	};
 };
 /**
@@ -158,16 +184,53 @@ const loop = Function.dual(2, (initial, body) => Stream.scoped(Stream.fromPull(E
 				return yield* Cause.done();
 			}
 			const { values, decision } = partitionChunk(chunk);
-			if (decision !== void 0) {
+			if (Option.isSome(decision)) {
 				yield* closeActive(active, Exit.void);
-				if (decision._tag === "Stop") done = true;
-				else if (decision._tag === "Next") state = decision.state;
+				if (decision.value._tag === "Stop" || decision.value._tag === "StopWith") done = true;
+				else if (decision.value._tag === "Next") state = decision.value.state;
 			}
 			if (isNonEmpty(values)) return values;
 		}
 	});
 }))));
 /**
+* 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>`:**
+*   - `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
+*     (state preserved)
+*   - 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
+* 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.
+*/
+const loopFrom = Function.dual(3, (input, initial, body) => Stream.unwrap(Effect.gen(function* () {
+	const stateRef = yield* Ref.make(initial);
+	return input.pipe(Stream.flatMap((item) => Stream.unwrap(Effect.gen(function* () {
+		const state = yield* Ref.get(stateRef);
+		const wrappedBody = (s) => {
+			const result = body(s, item);
+			return (Effect.isEffect(result) ? Stream.unwrap(result) : result).pipe(Stream.tap((event) => Match.value(event).pipe(Match.tags({
+				Next: (e) => Ref.set(stateRef, e.state),
+				StopWith: (e) => Ref.set(stateRef, e.state)
+			}), Match.orElse(() => Effect.void))));
+		};
+		return loop(state, wrappedBody);
+	}))));
+})));
+/**
 * Like `loop`, but exposes the current loop state as a `SubscriptionRef`
 * alongside the value stream.
 *
@@ -189,7 +252,10 @@ const loop = Function.dual(2, (initial, body) => Stream.scoped(Stream.fromPull(E
 */
 const loopWithState = (initial, body) => Effect.gen(function* () {
 	const stateRef = yield* SubscriptionRef.make(initial);
-	const tap = (stream) => stream.pipe(Stream.tap((event) => event._tag === "Next" ? SubscriptionRef.set(stateRef, event.state) : Effect.void));
+	const tap = (stream) => stream.pipe(Stream.tap((event) => Match.value(event).pipe(Match.tags({
+		Next: (e) => SubscriptionRef.set(stateRef, e.state),
+		StopWith: (e) => SubscriptionRef.set(stateRef, e.state)
+	}), Match.orElse(() => Effect.void))));
 	const wrappedBody = (s) => {
 		const result = body(s);
 		return Effect.isEffect(result) ? Effect.map(result, tap) : tap(result);
@@ -200,6 +266,6 @@ const loopWithState = (initial, body) => Effect.gen(function* () {
 	};
 });
 //#endregion
-export { loop, loopWithState, next, nextAfter, nextAfterFold, onTurnComplete, stop, stopAfter, stopEvent, Loop_exports as t, value };
+export { loop, loopFrom, loopWithState, next, nextAfter, nextAfterFold, onTurnComplete, stop, stopAfter, stopEvent, stopWith, stopWithAfter, Loop_exports as t, value };
 
 //# sourceMappingURL=Loop.mjs.map

package/dist/loop/Loop.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"Loop.mjs","names":[],"sources":["../../src/loop/Loop.ts"],"sourcesContent":["/**\n * Pull-based `loop` for state-threaded sub-streams.\n *\n * Each iteration runs a body that returns a `Stream<Event<A, S>>`. The body\n * emits values via `Loop.value(a)` and signals iteration control via\n * `Loop.next(state)` (continue with new state) or `Loop.stop` (terminate).\n * The loop unwraps `Value` events back to `A` for downstream consumers, so\n * the resulting stream is a plain `Stream<A>`.\n *\n * The next body stream is only pulled when downstream pulls the outer\n * stream - no producer fiber, no queue buffering. Cancellation, failures,\n * scoped resources, and backpressure stay aligned with normal Stream\n * semantics.\n *\n * Convention: a `Next` or `Stop` event is the terminal element of a body's\n * iteration. Values emitted in the same chunk after one are discarded\n * (their producing side effects may already have run). Prefer the\n * `Loop.nextAfter` / `Loop.stopAfter` helpers to terminate cleanly.\n */\nimport {\n  Cause,\n  Channel,\n  Data,\n  Effect,\n  Exit,\n  Function,\n  Option,\n  Ref,\n  Scope,\n  Stream,\n  SubscriptionRef,\n} from \"effect\"\nimport { IncompleteTurn } from \"../domain/AiError.js\"\nimport { isTurnComplete, type Turn, type TurnEvent } from \"../domain/Turn.js\"\n\n// ---------------------------------------------------------------------------\n// Event type - the body's emit shape\n// ---------------------------------------------------------------------------\n\n/**\n * The tagged union a body emits per pull. `Value` carries a payload that\n * flows downstream. `Next` ends the current iteration and continues with a\n * new state. `Stop` ends the loop entirely.\n */\nexport type Event<A, S> = Data.TaggedEnum<{\n  Value: { readonly value: A }\n  Next: { readonly state: S }\n  Stop: {}\n}>\n\ninterface EventDef extends Data.TaggedEnum.WithGenerics<2> {\n  readonly taggedEnum: Event<this[\"A\"], this[\"B\"]>\n}\n\nconst Event = Data.taggedEnum<EventDef>()\n\n/** Wrap a value so it flows through the loop to downstream consumers. */\nexport const value = <A>(a: A): Event<A, never> => Event.Value({ value: a })\n\n/** End the current iteration and continue with a new state. */\nexport const next = <S>(state: S): Event<never, S> => Event.Next({ state })\n\n/** The terminal `Stop` event. Use `stop` (the Stream) to end a loop body. */\nexport const stopEvent: Event<never, never> = Event.Stop()\n\n/**\n * A single-element stream that ends the loop. Return this from a body when\n * there's nothing else to emit; equivalent to `stopAfter(Stream.empty)` but\n * named for the common case.\n */\nexport const stop: Stream.Stream<Event<never, never>> = Stream.succeed(stopEvent)\n\n/**\n * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate the\n * iteration with `next(state)`. Common shape for \"stream this turn's\n * deltas, then continue with updated history.\"\n */\nexport const nextAfter = <S, A, E, R>(\n  stream: Stream.Stream<A, E, R>,\n  state: S,\n): Stream.Stream<Event<A, S>, E, R> =>\n  Stream.concat(Stream.map(stream, value), Stream.fromIterable([next(state)]))\n\n/**\n * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate the\n * loop. Common shape for \"stream this turn's deltas, then we're done.\"\n */\nexport const stopAfter = <A, E, R>(\n  stream: Stream.Stream<A, E, R>,\n): Stream.Stream<Event<A, never>, E, R> =>\n  Stream.concat(Stream.map(stream, value), Stream.fromIterable([stopEvent]))\n\n/**\n * General `nextAfter` variant: drain `stream` to the consumer, fold elements\n * into an accumulator, and at end-of-stream emit one `next(build(finalAcc))`.\n *\n * Subsumes `nextAfter` when state is constant (`reduce: (s, _) => s`,\n * `build: (s) => s`). Used by `Toolkit.continueWith` to collect tool\n * results and build next state without exposing a Ref to recipes.\n */\nexport const nextAfterFold = <A, B, S, E, R>(\n  stream: Stream.Stream<A, E, R>,\n  initial: B,\n  reduce: (acc: B, a: A) => B,\n  build: (b: B) => S,\n): Stream.Stream<Event<A, S>, E, R> =>\n  Stream.unwrap(\n    Effect.gen(function* () {\n      const ref = yield* Ref.make(initial)\n      const tapped = stream.pipe(\n        Stream.tap((a) => Ref.update(ref, (acc) => reduce(acc, a))),\n        Stream.map(value),\n      )\n      const continuation = Stream.fromEffect(\n        Ref.get(ref).pipe(Effect.map((acc) => next(build(acc)))),\n      )\n      return tapped.pipe(Stream.concat(continuation))\n    }),\n  )\n\n// ---------------------------------------------------------------------------\n// onTurnComplete - turn-aware stream operator for loop bodies\n// ---------------------------------------------------------------------------\n\n/**\n * Lift a provider's `Stream<TurnEvent>` into a loop body's `Stream<Event<TurnEvent | A, S>>`.\n * Each delta passes through as `value(delta)` (including the terminal\n * `turn_complete`, so the consumer sees turn boundaries naturally). Once\n * the terminal arrives, `then(turn)` runs and its returned stream of loop\n * events (typically tool outputs followed by `next(state)` or `stop`) is\n * concatenated.\n *\n * Pre-pipe transforms (`Stream.tap` / `Stream.map` / `Stream.filter`) on\n * the raw delta stream cover anything an `emit`-style callback would do.\n *\n * If the upstream ends without a `turn_complete`, the resulting stream\n * fails with `AiError.IncompleteTurn`. Catch it via `Stream.catchTag` if\n * you want to recover.\n */\nexport const onTurnComplete =\n  <S, A, E2 = never, R2 = never>(\n    then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>,\n  ) =>\n  <E, R>(\n    deltas: Stream.Stream<TurnEvent, E, R>,\n  ): Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2> =>\n    Stream.unwrap(\n      Effect.gen(function* () {\n        const turnRef = yield* Ref.make<Option.Option<Turn>>(Option.none())\n\n        const events: Stream.Stream<Event<TurnEvent, S>, E, R> = deltas.pipe(\n          Stream.tap((delta) =>\n            isTurnComplete(delta) ? Ref.set(turnRef, Option.some(delta.turn)) : Effect.void,\n          ),\n          Stream.map(value),\n        )\n\n        const continuation = Stream.unwrap(\n          Effect.gen(function* () {\n            const opt = yield* Ref.get(turnRef)\n            if (Option.isNone(opt)) return yield* Effect.fail(new IncompleteTurn({}))\n            return yield* then(opt.value)\n          }),\n        )\n\n        return Stream.concat(events, continuation)\n      }),\n    )\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nconst isNonEmpty = <A>(array: ReadonlyArray<A>): array is readonly [A, ...Array<A>] =>\n  array.length > 0\n\ntype CurrentBody<S, A, E, R> = {\n  readonly scope: Scope.Closeable\n  readonly pull: Effect.Effect<ReadonlyArray<Event<A, S>>, E | Cause.Done<void>, R>\n}\n\nconst closeBody = <S, A, E, R>(\n  current: CurrentBody<S, A, E, R>,\n  exit: Exit.Exit<unknown, unknown>,\n) => Scope.close(current.scope, exit)\n\n/**\n * Walk a chunk of `Event<A, S>` until a terminal `Next` or `Stop` is found.\n * Returns the unwrapped values seen so far and (optionally) the terminal\n * event. Anything in the chunk after the terminal is discarded - its\n * producing side effects may have run, but downstream never sees it.\n */\nconst partitionChunk = <A, S>(\n  chunk: ReadonlyArray<Event<A, S>>,\n): { readonly values: Array<A>; readonly decision: Event<A, S> | undefined } => {\n  const values: Array<A> = []\n  for (let i = 0; i < chunk.length; i++) {\n    const event = chunk[i]!\n    if (event._tag === \"Value\") {\n      values.push(event.value)\n    } else {\n      return { values, decision: event }\n    }\n  }\n  return { values, decision: undefined }\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\ntype LoopBody<S, A, E, R> = (\n  state: S,\n) => Stream.Stream<Event<A, S>, E, R> | Effect.Effect<Stream.Stream<Event<A, S>, E, R>, E, R>\n\n/**\n * Drive a state-threaded loop body. Each iteration runs `body(state)` to get\n * a `Stream<Event<A, S>>`; values flow downstream, `next(s)` continues with\n * a new state, `stop` ends the loop. See the file header for the full\n * pull-based execution model.\n *\n * Dual: data-first `loop(initial, body)` and data-last `loop(body)(initial)`\n * (or `pipe(initial, loop(body))`) both work.\n */\nexport const loop: {\n  <S, A, E, R>(body: LoopBody<S, A, E, R>): (initial: S) => Stream.Stream<A, E, R>\n  <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>): Stream.Stream<A, E, R>\n} = Function.dual(\n  2,\n  <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>): Stream.Stream<A, E, R> =>\n    Stream.scoped(\n      Stream.fromPull(\n        Effect.gen(function* () {\n          const outerScope = yield* Effect.scope\n          let state = initial\n          let current: CurrentBody<S, A, E, R> | undefined\n          let done = false\n\n          const closeActive = (\n            active: CurrentBody<S, A, E, R>,\n            exit: Exit.Exit<unknown, unknown>,\n          ) => {\n            const isActive = current === active\n            if (isActive) current = undefined\n            // Scope.close is idempotent. Multiple paths can race to close the\n            // active body during cancellation/failure, so closing twice is safe.\n            return closeBody(active, exit)\n          }\n\n          yield* Scope.addFinalizerExit(outerScope, (exit) =>\n            current === undefined ? Effect.void : closeActive(current, exit),\n          )\n\n          const pull = Effect.gen(function* () {\n            while (true) {\n              if (done) return yield* Cause.done()\n\n              if (current === undefined) {\n                const result = body(state)\n                const stream = Effect.isEffect(result) ? Stream.unwrap(result) : result\n                const bodyScope = yield* Scope.fork(outerScope)\n                const bodyPull = yield* Channel.toPullScoped(\n                  Stream.toChannel(stream),\n                  bodyScope,\n                ).pipe(Effect.onError((cause) => Scope.close(bodyScope, Exit.failCause(cause))))\n                current = { scope: bodyScope, pull: bodyPull }\n              }\n\n              const active = current\n              const chunk = yield* active.pull.pipe(\n                Effect.catchIf(Cause.isDone, () =>\n                  closeActive(active, Exit.void).pipe(\n                    Effect.as(undefined as ReadonlyArray<Event<A, S>> | undefined),\n                  ),\n                ),\n                Effect.onError((cause) => closeActive(active, Exit.failCause(cause))),\n              )\n\n              if (chunk === undefined) {\n                done = true\n                return yield* Cause.done()\n              }\n\n              const { values, decision } = partitionChunk(chunk)\n\n              if (decision !== undefined) {\n                yield* closeActive(active, Exit.void)\n                if (decision._tag === \"Stop\") {\n                  done = true\n                } else if (decision._tag === \"Next\") {\n                  state = decision.state\n                }\n              }\n\n              // Emit the values seen so far if any. Chunks from a Stream pull\n              // are non-empty, so when `decision === undefined` every event was\n              // a `Value` and `values` is non-empty here. With a decision and\n              // no preceding values, fall through to the next iteration.\n              if (isNonEmpty(values)) return values\n            }\n          })\n\n          return pull\n        }),\n      ),\n    ),\n)\n\n// ---------------------------------------------------------------------------\n// loopWithState - same body protocol, plus a live state observable.\n// ---------------------------------------------------------------------------\n\n/**\n * Like `loop`, but exposes the current loop state as a `SubscriptionRef`\n * alongside the value stream.\n *\n * Allocates one `SubscriptionRef<S>` seeded with `initial`, then runs the\n * loop with a wrapped body that taps every `Next(s)` event into the ref\n * before forwarding it. The caller decides how to consume both channels:\n *\n *   - **Final state**: drain the stream, then `SubscriptionRef.get(state)`\n *     - the ref holds the state from the last `Next` (or `initial` if the\n *     loop ended without advancing).\n *   - **Live transitions**: `SubscriptionRef.changes(state)` is a\n *     `Stream<S>` of every state observed; subscribe alongside the value\n *     stream.\n *   - **Mid-iteration peek**: `SubscriptionRef.get(state)` at any time.\n *\n * The returned stream and ref are independent of each other - the ref\n * lives outside the stream's scope, so reading it after the stream\n * completes is safe.\n */\nexport const loopWithState = <S, A, E, R>(\n  initial: S,\n  body: LoopBody<S, A, E, R>,\n): Effect.Effect<{\n  readonly stream: Stream.Stream<A, E, R>\n  readonly state: SubscriptionRef.SubscriptionRef<S>\n}> =>\n  Effect.gen(function* () {\n    const stateRef = yield* SubscriptionRef.make(initial)\n\n    const tap = (stream: Stream.Stream<Event<A, S>, E, R>): Stream.Stream<Event<A, S>, E, R> =>\n      stream.pipe(\n        Stream.tap((event) =>\n          event._tag === \"Next\" ? SubscriptionRef.set(stateRef, event.state) : Effect.void,\n        ),\n      )\n\n    const wrappedBody: LoopBody<S, A, E, R> = (s) => {\n      const result = body(s)\n      return Effect.isEffect(result) ? Effect.map(result, tap) : tap(result)\n    }\n\n    return {\n      stream: loop(initial, wrappedBody),\n      state: stateRef,\n    }\n  })\n"],"mappings":"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"}
+{"version":3,"file":"Loop.mjs","names":["Arr"],"sources":["../../src/loop/Loop.ts"],"sourcesContent":["/**\n * Pull-based `loop` for state-threaded sub-streams.\n *\n * Each iteration runs a body that returns a `Stream<Event<A, S>>`. The body\n * emits values via `Loop.value(a)` and signals iteration control via\n * `Loop.next(state)` (continue with new state) or `Loop.stop` (terminate).\n * The loop unwraps `Value` events back to `A` for downstream consumers, so\n * the resulting stream is a plain `Stream<A>`.\n *\n * The next body stream is only pulled when downstream pulls the outer\n * stream - no producer fiber, no queue buffering. Cancellation, failures,\n * scoped resources, and backpressure stay aligned with normal Stream\n * semantics.\n *\n * Convention: a `Next` or `Stop` event is the terminal element of a body's\n * iteration. Values emitted in the same chunk after one are discarded\n * (their producing side effects may already have run). Prefer the\n * `Loop.nextAfter` / `Loop.stopAfter` helpers to terminate cleanly.\n */\nimport {\n  Array as Arr,\n  Cause,\n  Channel,\n  Data,\n  Effect,\n  Exit,\n  Function,\n  Match,\n  Option,\n  Ref,\n  Result,\n  Scope,\n  Stream,\n  SubscriptionRef,\n} from \"effect\"\nimport { IncompleteTurn } from \"../domain/AiError.js\"\nimport { isTurnComplete, type Turn, type TurnEvent } from \"../domain/Turn.js\"\n\n// ---------------------------------------------------------------------------\n// Event type - the body's emit shape\n// ---------------------------------------------------------------------------\n\n/**\n * The tagged union a body emits per pull. `Value` carries a payload that\n * flows downstream. `Next` ends the current iteration and continues with a\n * new state. `Stop` ends the loop entirely with no carried state.\n * `StopWith` also ends the loop but carries a final state that `loopFrom`\n * will thread to the next input and `loopWithState` will write to its\n * `SubscriptionRef` before the loop ends. Plain `loop` has no next\n * iteration to apply it to and treats `StopWith` like `Stop`.\n *\n * `Stop` is intentionally `{}` so the bare `stopEvent` / `stop` helpers\n * don't constrain `S` from a body's stream type — every body has a `Stop`\n * variant in its union, and forcing `S` to flow through it would break\n * inference whenever the body never uses `next` / `stopWith`.\n */\nexport type Event<A, S> = Data.TaggedEnum<{\n  Value: { readonly value: A }\n  Next: { readonly state: S }\n  Stop: {}\n  StopWith: { readonly state: S }\n}>\n\ninterface EventDef extends Data.TaggedEnum.WithGenerics<2> {\n  readonly taggedEnum: Event<this[\"A\"], this[\"B\"]>\n}\n\nconst Event = Data.taggedEnum<EventDef>()\n\n/** Wrap a value so it flows through the loop to downstream consumers. */\nexport const value = <A>(a: A): Event<A, never> => Event.Value({ value: a })\n\n/** End the current iteration and continue with a new state. */\nexport const next = <S>(state: S): Event<never, S> => Event.Next({ state })\n\n/**\n * The terminal `Stop` event with no carried state. Use `stop` (the Stream)\n * to end a loop body without communicating a final state.\n */\nexport const stopEvent: Event<never, never> = Event.Stop()\n\n/**\n * Terminal event that ends the loop AND carries a final state. For\n * `loopFrom` this is the natural \"this input is done, here's the state to\n * carry forward to the next input\" signal — symmetric with `next(s)` but\n * ending the inner loop instead of continuing it. For `loopWithState` the\n * carried state is written to the `SubscriptionRef` before the loop ends.\n */\nexport const stopWith = <S>(state: S): Event<never, S> => Event.StopWith({ state })\n\n/**\n * A single-element stream that ends the loop. Return this from a body when\n * there's nothing else to emit; equivalent to `stopAfter(Stream.empty)` but\n * named for the common case.\n */\nexport const stop: Stream.Stream<Event<never, never>> = Stream.succeed(stopEvent)\n\n/**\n * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate the\n * iteration with `next(state)`. Common shape for \"stream this turn's\n * deltas, then continue with updated history.\"\n *\n * Dual: data-first `nextAfter(stream, state)` and data-last\n * `stream.pipe(nextAfter(state))` both work.\n */\nexport const nextAfter: {\n  <S>(state: S): <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, S>, E, R>\n  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, E, R>\n} = Function.dual(\n  2,\n  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, E, R> =>\n    Stream.concat(Stream.map(stream, value), Stream.fromIterable([next(state)])),\n)\n\n/**\n * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate the\n * loop. Common shape for \"stream this turn's deltas, then we're done.\"\n *\n * Unary on the stream — already pipe-compatible via `stream.pipe(stopAfter)`.\n */\nexport const stopAfter = <A, E, R>(\n  stream: Stream.Stream<A, E, R>,\n): Stream.Stream<Event<A, never>, E, R> =>\n  Stream.concat(Stream.map(stream, value), Stream.fromIterable([stopEvent]))\n\n/**\n * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate with\n * `stopWith(state)`. The natural \"emit final outputs, advance state, end\n * this input's inner loop\" shape for `loopFrom`.\n *\n * Dual: data-first `stopWithAfter(stream, state)` and data-last\n * `stream.pipe(stopWithAfter(state))` both work.\n */\nexport const stopWithAfter: {\n  <S>(state: S): <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, S>, E, R>\n  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, E, R>\n} = Function.dual(\n  2,\n  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, E, R> =>\n    Stream.concat(Stream.map(stream, value), Stream.fromIterable([stopWith(state)])),\n)\n\n/**\n * General `nextAfter` variant: drain `stream` to the consumer, fold elements\n * into an accumulator, and at end-of-stream emit one `next(build(finalAcc))`.\n *\n * Subsumes `nextAfter` when state is constant (`reduce: (s, _) => s`,\n * `build: (s) => s`). Used by `Toolkit.continueWith` to collect tool\n * results and build next state without exposing a Ref to recipes.\n *\n * Dual: data-first `nextAfterFold(stream, initial, reduce, build)` and\n * data-last `stream.pipe(nextAfterFold(initial, reduce, build))` both work.\n */\nexport const nextAfterFold: {\n  <A, B, S>(\n    initial: B,\n    reduce: (acc: B, a: A) => B,\n    build: (b: B) => S,\n  ): <E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, S>, E, R>\n  <A, B, S, E, R>(\n    stream: Stream.Stream<A, E, R>,\n    initial: B,\n    reduce: (acc: B, a: A) => B,\n    build: (b: B) => S,\n  ): Stream.Stream<Event<A, S>, E, R>\n} = Function.dual(\n  4,\n  <A, B, S, E, R>(\n    stream: Stream.Stream<A, E, R>,\n    initial: B,\n    reduce: (acc: B, a: A) => B,\n    build: (b: B) => S,\n  ): Stream.Stream<Event<A, S>, E, R> =>\n    Stream.unwrap(\n      Effect.gen(function* () {\n        const ref = yield* Ref.make(initial)\n        const tapped = stream.pipe(\n          Stream.tap((a) => Ref.update(ref, (acc) => reduce(acc, a))),\n          Stream.map(value),\n        )\n        const continuation = Stream.fromEffect(\n          Ref.get(ref).pipe(Effect.map((acc) => next(build(acc)))),\n        )\n        return tapped.pipe(Stream.concat(continuation))\n      }),\n    ),\n)\n\n// ---------------------------------------------------------------------------\n// onTurnComplete - turn-aware stream operator for loop bodies\n// ---------------------------------------------------------------------------\n\n/**\n * Lift a provider's `Stream<TurnEvent>` into a loop body's `Stream<Event<TurnEvent | A, S>>`.\n * Each delta passes through as `value(delta)` (including the terminal\n * `TurnComplete`, so the consumer sees turn boundaries naturally). Once\n * the terminal arrives, `then(turn)` runs and its returned stream of loop\n * events (typically tool outputs followed by `next(state)` or `stop`) is\n * concatenated.\n *\n * Pre-pipe transforms (`Stream.tap` / `Stream.map` / `Stream.filter`) on\n * the raw delta stream cover anything an `emit`-style callback would do.\n *\n * If the upstream ends without a `TurnComplete`, the resulting stream\n * fails with `AiError.IncompleteTurn`. Catch it via `Stream.catchTag` if\n * you want to recover.\n *\n * Dual: data-first `onTurnComplete(deltas, then)` and data-last\n * `deltas.pipe(onTurnComplete(then))` both work.\n */\nexport const onTurnComplete: {\n  <S, A, E2 = never, R2 = never>(\n    then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>,\n  ): <E, R>(\n    deltas: Stream.Stream<TurnEvent, E, R>,\n  ) => Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>\n  <S, A, E, R, E2 = never, R2 = never>(\n    deltas: Stream.Stream<TurnEvent, E, R>,\n    then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>,\n  ): Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>\n} = Function.dual(\n  2,\n  <S, A, E, R, E2, R2>(\n    deltas: Stream.Stream<TurnEvent, E, R>,\n    then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>,\n  ): Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2> =>\n    Stream.unwrap(\n      Effect.gen(function* () {\n        const turnRef = yield* Ref.make<Option.Option<Turn>>(Option.none())\n\n        const events: Stream.Stream<Event<TurnEvent, S>, E, R> = deltas.pipe(\n          Stream.tap((delta) =>\n            isTurnComplete(delta) ? Ref.set(turnRef, Option.some(delta.turn)) : Effect.void,\n          ),\n          Stream.map(value),\n        )\n\n        const continuation = Stream.unwrap(\n          Effect.gen(function* () {\n            const opt = yield* Ref.get(turnRef)\n            if (Option.isNone(opt)) return yield* new IncompleteTurn({})\n            return yield* then(opt.value)\n          }),\n        )\n\n        return Stream.concat(events, continuation)\n      }),\n    ),\n)\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nconst isNonEmpty = <A>(array: ReadonlyArray<A>): array is readonly [A, ...Array<A>] =>\n  array.length > 0\n\ntype CurrentBody<S, A, E, R> = {\n  readonly scope: Scope.Closeable\n  readonly pull: Effect.Effect<ReadonlyArray<Event<A, S>>, E | Cause.Done<void>, R>\n}\n\nconst closeBody = <S, A, E, R>(\n  current: CurrentBody<S, A, E, R>,\n  exit: Exit.Exit<unknown, unknown>,\n) => Scope.close(current.scope, exit)\n\n/**\n * Walk a chunk of `Event<A, S>` until a terminal `Next` or `Stop` is found.\n * Returns the unwrapped values seen so far and (optionally) the terminal\n * event. Anything in the chunk after the terminal is discarded - its\n * producing side effects may have run, but downstream never sees it.\n */\nconst partitionChunk = <A, S>(\n  chunk: ReadonlyArray<Event<A, S>>,\n): {\n  readonly values: ReadonlyArray<A>\n  readonly decision: Option.Option<Event<A, S>>\n} => {\n  const [valueEvents, rest] = Arr.span(\n    chunk,\n    (e): e is Event<A, S> & { _tag: \"Value\" } => e._tag === \"Value\",\n  )\n  return {\n    values: valueEvents.map((e) => e.value),\n    decision: Arr.head(rest),\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\ntype LoopBody<S, A, E, R> = (\n  state: S,\n) => Stream.Stream<Event<A, S>, E, R> | Effect.Effect<Stream.Stream<Event<A, S>, E, R>, E, R>\n\n/**\n * Drive a state-threaded loop body. Each iteration runs `body(state)` to get\n * a `Stream<Event<A, S>>`; values flow downstream, `next(s)` continues with\n * a new state, `stop` ends the loop. See the file header for the full\n * pull-based execution model.\n *\n * Dual: data-first `loop(initial, body)` and data-last `loop(body)(initial)`\n * (or `pipe(initial, loop(body))`) both work.\n */\nexport const loop: {\n  <S, A, E, R>(body: LoopBody<S, A, E, R>): (initial: S) => Stream.Stream<A, E, R>\n  <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>): Stream.Stream<A, E, R>\n} = Function.dual(\n  2,\n  <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>): Stream.Stream<A, E, R> =>\n    Stream.scoped(\n      Stream.fromPull(\n        Effect.gen(function* () {\n          const outerScope = yield* Effect.scope\n          let state = initial\n          let current: CurrentBody<S, A, E, R> | undefined\n          let done = false\n\n          const closeActive = (\n            active: CurrentBody<S, A, E, R>,\n            exit: Exit.Exit<unknown, unknown>,\n          ) => {\n            const isActive = current === active\n            if (isActive) current = undefined\n            // Scope.close is idempotent. Multiple paths can race to close the\n            // active body during cancellation/failure, so closing twice is safe.\n            return closeBody(active, exit)\n          }\n\n          yield* Scope.addFinalizerExit(outerScope, (exit) =>\n            current === undefined ? Effect.void : closeActive(current, exit),\n          )\n\n          const pull = Effect.gen(function* () {\n            while (true) {\n              if (done) return yield* Cause.done()\n\n              if (current === undefined) {\n                const result = body(state)\n                const stream = Effect.isEffect(result) ? Stream.unwrap(result) : result\n                const bodyScope = yield* Scope.fork(outerScope)\n                const bodyPull = yield* Channel.toPullScoped(\n                  Stream.toChannel(stream),\n                  bodyScope,\n                ).pipe(Effect.onError((cause) => Scope.close(bodyScope, Exit.failCause(cause))))\n                current = { scope: bodyScope, pull: bodyPull }\n              }\n\n              const active = current\n              const chunk = yield* active.pull.pipe(\n                Effect.catchIf(Cause.isDone, () =>\n                  closeActive(active, Exit.void).pipe(\n                    Effect.as(undefined as ReadonlyArray<Event<A, S>> | undefined),\n                  ),\n                ),\n                Effect.onError((cause) => closeActive(active, Exit.failCause(cause))),\n              )\n\n              if (chunk === undefined) {\n                done = true\n                return yield* Cause.done()\n              }\n\n              const { values, decision } = partitionChunk(chunk)\n\n              if (Option.isSome(decision)) {\n                yield* closeActive(active, Exit.void)\n                if (decision.value._tag === \"Stop\" || decision.value._tag === \"StopWith\") {\n                  // `loop` has no next iteration to apply StopWith's state to;\n                  // the state lands in `loopFrom`'s outer ref or\n                  // `loopWithState`'s SubscriptionRef via their taps.\n                  done = true\n                } else if (decision.value._tag === \"Next\") {\n                  state = decision.value.state\n                }\n              }\n\n              // Emit the values seen so far if any. Chunks from a Stream pull\n              // are non-empty, so when `decision` is `None` every event was\n              // a `Value` and `values` is non-empty here. With a decision and\n              // no preceding values, fall through to the next iteration.\n              if (isNonEmpty(values)) return values\n            }\n          })\n\n          return pull\n        }),\n      ),\n    ),\n)\n\n// ---------------------------------------------------------------------------\n// loopFrom - stream-driven sibling of loop. One input item runs a full\n// multi-turn inner loop.\n// ---------------------------------------------------------------------------\n\ntype LoopFromBody<S, I, A, E, R> = (\n  state: S,\n  input: I,\n) => Stream.Stream<Event<A, S>, E, R> | Effect.Effect<Stream.Stream<Event<A, S>, E, R>, E, R>\n\n/**\n * Input-driven sibling of `loop`. For each item pulled from the input\n * stream, runs an inner seed-driven `loop` whose body is\n * `(s) => body(s, item)`. State is threaded across input items.\n *\n * **Per-input semantics — the body emits standard `Event<A, S>`:**\n *   - `value(a)`: emit `a` downstream\n *   - `next(s)`: re-run the body with the SAME input and new state `s`\n *     (multi-turn within one input — e.g. multiple model turns + tool\n *     calls for one document)\n *   - `stop`: end this input's inner loop, advance to the next input\n *     (state preserved)\n *   - body stream ending without a decision: same as `stop` (advance)\n *\n * **Outer termination:** the input stream ending. To halt programmatically\n * from within, end the input stream upstream (`Stream.takeWhile`, a\n * `SubscriptionRef` gate, etc.). Reserving `stop` for per-item\n * advancement is what makes the common \"stream of documents, multi-turn\n * conversation per document\" shape readable.\n *\n * Dual: data-first `loopFrom(input, initial, body)` and data-last\n * `input.pipe(loopFrom(initial, body))` both work.\n */\nexport const loopFrom: {\n  <S, I, A, E, R>(\n    initial: S,\n    body: LoopFromBody<S, I, A, E, R>,\n  ): <EI, RI>(input: Stream.Stream<I, EI, RI>) => Stream.Stream<A, E | EI, R | RI>\n  <S, I, A, E, R, EI, RI>(\n    input: Stream.Stream<I, EI, RI>,\n    initial: S,\n    body: LoopFromBody<S, I, A, E, R>,\n  ): Stream.Stream<A, E | EI, R | RI>\n} = Function.dual(\n  3,\n  <S, I, A, E, R, EI, RI>(\n    input: Stream.Stream<I, EI, RI>,\n    initial: S,\n    body: LoopFromBody<S, I, A, E, R>,\n  ): Stream.Stream<A, E | EI, R | RI> =>\n    Stream.unwrap(\n      Effect.gen(function* () {\n        const stateRef = yield* Ref.make<S>(initial)\n        return input.pipe(\n          Stream.flatMap((item) =>\n            Stream.unwrap(\n              Effect.gen(function* () {\n                const state = yield* Ref.get(stateRef)\n                // Capture Next states (and stopWith's final state) into the\n                // outer ref so the LAST state seen in this input's inner\n                // loop is what the next input starts from.\n                const wrappedBody = (s: S) => {\n                  const result = body(s, item)\n                  const stream = Effect.isEffect(result) ? Stream.unwrap(result) : result\n                  return stream.pipe(\n                    Stream.tap((event) =>\n                      Match.value(event).pipe(\n                        Match.tags({\n                          Next: (e) => Ref.set(stateRef, e.state),\n                          StopWith: (e) => Ref.set(stateRef, e.state),\n                        }),\n                        Match.orElse(() => Effect.void),\n                      ),\n                    ),\n                  )\n                }\n                return loop(state, wrappedBody)\n              }),\n            ),\n          ),\n        )\n      }),\n    ),\n)\n\n// ---------------------------------------------------------------------------\n// loopWithState - same body protocol, plus a live state observable.\n// ---------------------------------------------------------------------------\n\n/**\n * Like `loop`, but exposes the current loop state as a `SubscriptionRef`\n * alongside the value stream.\n *\n * Allocates one `SubscriptionRef<S>` seeded with `initial`, then runs the\n * loop with a wrapped body that taps every `Next(s)` event into the ref\n * before forwarding it. The caller decides how to consume both channels:\n *\n *   - **Final state**: drain the stream, then `SubscriptionRef.get(state)`\n *     - the ref holds the state from the last `Next` (or `initial` if the\n *     loop ended without advancing).\n *   - **Live transitions**: `SubscriptionRef.changes(state)` is a\n *     `Stream<S>` of every state observed; subscribe alongside the value\n *     stream.\n *   - **Mid-iteration peek**: `SubscriptionRef.get(state)` at any time.\n *\n * The returned stream and ref are independent of each other - the ref\n * lives outside the stream's scope, so reading it after the stream\n * completes is safe.\n */\nexport const loopWithState = <S, A, E, R>(\n  initial: S,\n  body: LoopBody<S, A, E, R>,\n): Effect.Effect<{\n  readonly stream: Stream.Stream<A, E, R>\n  readonly state: SubscriptionRef.SubscriptionRef<S>\n}> =>\n  Effect.gen(function* () {\n    const stateRef = yield* SubscriptionRef.make(initial)\n\n    const tap = (stream: Stream.Stream<Event<A, S>, E, R>): Stream.Stream<Event<A, S>, E, R> =>\n      stream.pipe(\n        Stream.tap((event) =>\n          Match.value(event).pipe(\n            Match.tags({\n              Next: (e) => SubscriptionRef.set(stateRef, e.state),\n              StopWith: (e) => SubscriptionRef.set(stateRef, e.state),\n            }),\n            Match.orElse(() => Effect.void),\n          ),\n        ),\n      )\n\n    const wrappedBody: LoopBody<S, A, E, R> = (s) => {\n      const result = body(s)\n      return Effect.isEffect(result) ? Effect.map(result, tap) : tap(result)\n    }\n\n    return {\n      stream: loop(initial, wrappedBody),\n      state: stateRef,\n    }\n  })\n"],"mappings":"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"}

package/dist/loop/Loop.test.mjs

@@ -1,6 +1,8 @@
-import { loop, loopWithState, next, nextAfter, stopAfter, stopEvent, value } from "./Loop.mjs";
-import { i as it, n as globalExpect, r as describe } from "../dist-DV5ISja1.mjs";
-import { Deferred, Effect, Fiber, Latch, Ref, Stream, SubscriptionRef } from "effect";
+import { RateLimited } from "../domain/AiError.mjs";
+import { TurnEvent } from "../domain/Turn.mjs";
+import { loop, loopFrom, loopWithState, next, nextAfter, onTurnComplete, stop, stopAfter, stopEvent, stopWith, value } from "./Loop.mjs";
+import { i as it, n as globalExpect, r as describe, t as import_dist } from "../dist-DV5ISja1.mjs";
+import { Deferred, Effect, Fiber, Latch, Ref, Stream, SubscriptionRef, pipe } from "effect";
 //#region src/loop/Loop.test.ts
 describe("Loop.loop", () => {
 	it("threads state across iterations and emits each iteration's substream in order", async () => {
@@ -59,6 +61,47 @@ describe("Loop.loop", () => {
 			2
 		]);
 	});
+	it("type: data-last (pipe) form preserves the body's E channel", () => {
+		pipe({ count: 0 }, loop((_state) => Stream.fail(new RateLimited({
+			provider: "test",
+			raw: null
+		}))));
+		(0, import_dist.expectTypeOf)().toEqualTypeOf();
+	});
+	it("type: data-first form preserves the body's E channel", () => {
+		loop({ count: 0 }, (_state) => Stream.fail(new RateLimited({
+			provider: "test",
+			raw: null
+		})));
+		(0, import_dist.expectTypeOf)().toEqualTypeOf();
+	});
+	it("type: onTurnComplete inside loop infers S and A from the handler without annotation", () => {
+		pipe({ turns: 0 }, loop((state) => Effect.gen(function* () {
+			return Stream.empty.pipe(onTurnComplete(() => Effect.sync(() => state.turns >= 1 ? stop : nextAfter(Stream.succeed({
+				_tag: "tool",
+				name: "x"
+			}), { turns: state.turns + 1 }))));
+		})));
+		(0, import_dist.expectTypeOf)().toEqualTypeOf();
+	});
+	it("onTurnComplete: data-first form (Function.dual) works at runtime", async () => {
+		const turnComplete = TurnEvent.TurnComplete({ turn: {
+			items: [],
+			usage: {
+				input_tokens: 0,
+				output_tokens: 0
+			},
+			stop_reason: "stop"
+		} });
+		const textDelta = TurnEvent.TextDelta({ text: "hi" });
+		const deltas = Stream.fromIterable([textDelta, turnComplete]);
+		const dataFirst = onTurnComplete(deltas, () => Effect.sync(() => stop));
+		const dataLast = deltas.pipe(onTurnComplete(() => Effect.sync(() => stop)));
+		const a = await Effect.runPromise(Stream.runCollect(dataFirst));
+		const b = await Effect.runPromise(Stream.runCollect(dataLast));
+		globalExpect(a.length).toBe(3);
+		globalExpect(b.length).toBe(3);
+	});
 	it("is stack-safe and linear-time across many iterations", async () => {
 		const N = 1e5;
 		const stream = loop(0, (n) => n >= N ? Stream.fromIterable([value(n), stopEvent]) : Stream.fromIterable([value(n), next(n + 1)]));
@@ -405,6 +448,131 @@ describe("Loop.loopWithState", () => {
 		]);
 	});
 });
+describe("Loop.loopFrom", () => {
+	it("runs a multi-turn inner loop per input until the body emits stop", async () => {
+		globalExpect(await Effect.runPromise(Stream.fromIterable(["a", "b"]).pipe(loopFrom(0, (turns, input) => {
+			if (turns >= 2 * (input === "a" ? 1 : 2)) return Stream.fromIterable([stopEvent]);
+			return Stream.fromIterable([value(`${input}:${turns}`), next(turns + 1)]);
+		}), Stream.runCollect))).toEqual([
+			"a:0",
+			"a:1",
+			"b:2",
+			"b:3"
+		]);
+	});
+	it("threads state across inputs (audio-pipeline shape)", async () => {
+		globalExpect(await Effect.runPromise(Stream.fromIterable([
+			"x",
+			"y",
+			"z"
+		]).pipe(loopFrom([], (history, input) => Stream.fromIterable([value([...history, input].join(",")), stopWith([...history, input])])), Stream.runCollect))).toEqual([
+			"x",
+			"x,y",
+			"x,y,z"
+		]);
+	});
+	it("simulates a stream of documents with multi-turn tool calls per document", async () => {
+		globalExpect(await Effect.runPromise(Stream.fromIterable(["doc1", "doc2"]).pipe(loopFrom({
+			turn: 0,
+			totalTurns: 0
+		}, (state, doc) => {
+			if (state.turn === 0) return Stream.fromIterable([value({
+				kind: "text",
+				doc,
+				text: "thinking"
+			}), next({
+				turn: 1,
+				totalTurns: state.totalTurns + 1
+			})]);
+			if (state.turn === 1) return Stream.fromIterable([value({
+				kind: "tool",
+				doc,
+				tool: "search"
+			}), next({
+				turn: 2,
+				totalTurns: state.totalTurns + 1
+			})]);
+			return Stream.fromIterable([value({
+				kind: "text",
+				doc,
+				text: "final"
+			}), stopWith({
+				turn: 0,
+				totalTurns: state.totalTurns + 1
+			})]);
+		}), Stream.runCollect))).toEqual([
+			{
+				kind: "text",
+				doc: "doc1",
+				text: "thinking"
+			},
+			{
+				kind: "tool",
+				doc: "doc1",
+				tool: "search"
+			},
+			{
+				kind: "text",
+				doc: "doc1",
+				text: "final"
+			},
+			{
+				kind: "text",
+				doc: "doc2",
+				text: "thinking"
+			},
+			{
+				kind: "tool",
+				doc: "doc2",
+				tool: "search"
+			},
+			{
+				kind: "text",
+				doc: "doc2",
+				text: "final"
+			}
+		]);
+	});
+	it("ends cleanly when the input stream ends mid-conversation", async () => {
+		globalExpect(await Effect.runPromise(Stream.fromIterable(["only"]).pipe(loopFrom(0, (turns, input) => turns >= 2 ? Stream.fromIterable([stopEvent]) : Stream.fromIterable([value(`${input}:${turns}`), next(turns + 1)])), Stream.runCollect))).toEqual(["only:0", "only:1"]);
+	});
+	it("body's `stop` advances to the next input (does NOT halt the whole stream)", async () => {
+		globalExpect(await Effect.runPromise(Stream.fromIterable([
+			1,
+			2,
+			3
+		]).pipe(loopFrom(0, (_state, input) => Stream.fromIterable([value(input * 10), stopEvent])), Stream.runCollect))).toEqual([
+			10,
+			20,
+			30
+		]);
+	});
+	it("data-first form (Function.dual) runs identically to data-last", async () => {
+		const inputs = Stream.fromIterable([1, 2]);
+		globalExpect(await Effect.runPromise(Stream.runCollect(loopFrom(inputs, 0, (state, input) => state >= input ? Stream.fromIterable([stopEvent]) : Stream.fromIterable([value(state + input), next(state + 1)]))))).toEqual([1, 3]);
+	});
+	it("supports Effect-returning bodies (parity with loop)", async () => {
+		globalExpect(await Effect.runPromise(Stream.fromIterable(["a"]).pipe(loopFrom(0, (turns, input) => Effect.gen(function* () {
+			const cur = yield* Effect.succeed(turns);
+			if (cur >= 2) return Stream.fromIterable([stopEvent]);
+			return Stream.fromIterable([value(`${input}:${cur}`), next(cur + 1)]);
+		})), Stream.runCollect))).toEqual(["a:0", "a:1"]);
+	});
+	it("type: data-last (pipe) form preserves the body's E channel", () => {
+		pipe(Stream.fromIterable([1]), loopFrom(0, (_state, _input) => Stream.fail(new RateLimited({
+			provider: "test",
+			raw: null
+		}))));
+		(0, import_dist.expectTypeOf)().toEqualTypeOf();
+	});
+	it("type: data-first form preserves the body's E channel and unifies with input's E", () => {
+		loopFrom(Stream.fail(/* @__PURE__ */ new Error("boom")), 0, (_state, _i) => Stream.fail(new RateLimited({
+			provider: "test",
+			raw: null
+		})));
+		(0, import_dist.expectTypeOf)().toEqualTypeOf();
+	});
+});
 //#endregion
 export {};