@effect-uai/core 0.2.0 → 0.4.0

package/src/domain/Transcript.ts

@@ -0,0 +1,83 @@
+/**
+ * Per-word timing + metadata. `confidence` and `speakerId` are optional
+ * because providers vary widely in what they emit and when (some only on
+ * final, some only with diarization enabled, some not at all).
+ */
+export type WordTimestamp = {
+  readonly text: string
+  readonly startSeconds: number
+  readonly endSeconds: number
+  readonly confidence?: number
+  readonly speakerId?: string
+  readonly languageCode?: string
+}
+
+/**
+ * Sync STT result. `raw` preserves the provider-specific response for
+ * consumers that need fields the common shape doesn't expose
+ * (alternatives, segments, NBest, audio events, etc.).
+ */
+export type TranscriptResult = {
+  readonly text: string
+  readonly languageCode?: string
+  readonly durationSeconds?: number
+  readonly words?: ReadonlyArray<WordTimestamp>
+  readonly raw?: unknown
+}
+
+/**
+ * Streaming STT event union. Collapses every provider's vocabulary into
+ * a small set; provider-specific shapes survive on `metadata.raw`.
+ *
+ * - `partial`: interim hypothesis. `stability` is Google-only.
+ * - `final`: committed transcript for the current utterance / segment.
+ * - `speech-started` / `utterance-ended`: VAD-derived boundaries. Not
+ *   all providers emit them (OpenAI Realtime, Google with
+ *   `voice_activity_events`, Deepgram with `vad_events`, AssemblyAI).
+ * - `audio-event`: non-speech label (`(laughter)`, `(music)`) — ElevenLabs only.
+ * - `metadata`: opaque server-side bookkeeping (request_id, model info).
+ * - `error`: non-fatal provider error mid-stream. Fatal errors surface
+ *   on the `Stream`'s error channel as `AiError.AiError`.
+ */
+export type TranscriptEvent =
+  | {
+      readonly _tag: "partial"
+      readonly text: string
+      readonly words?: ReadonlyArray<WordTimestamp>
+      readonly stability?: number
+    }
+  | {
+      readonly _tag: "final"
+      readonly text: string
+      readonly words?: ReadonlyArray<WordTimestamp>
+      readonly languageCode?: string
+    }
+  | { readonly _tag: "speech-started"; readonly atSeconds: number }
+  | { readonly _tag: "utterance-ended"; readonly atSeconds: number }
+  | {
+      readonly _tag: "audio-event"
+      readonly label: string
+      readonly startSeconds: number
+      readonly endSeconds: number
+    }
+  | { readonly _tag: "metadata"; readonly raw: unknown }
+  | { readonly _tag: "error"; readonly code?: string; readonly message: string }
+
+export const isPartial = (e: TranscriptEvent): e is Extract<TranscriptEvent, { _tag: "partial" }> =>
+  e._tag === "partial"
+export const isFinal = (e: TranscriptEvent): e is Extract<TranscriptEvent, { _tag: "final" }> =>
+  e._tag === "final"
+export const isSpeechStarted = (
+  e: TranscriptEvent,
+): e is Extract<TranscriptEvent, { _tag: "speech-started" }> => e._tag === "speech-started"
+export const isUtteranceEnded = (
+  e: TranscriptEvent,
+): e is Extract<TranscriptEvent, { _tag: "utterance-ended" }> => e._tag === "utterance-ended"
+export const isAudioEvent = (
+  e: TranscriptEvent,
+): e is Extract<TranscriptEvent, { _tag: "audio-event" }> => e._tag === "audio-event"
+export const isMetadata = (
+  e: TranscriptEvent,
+): e is Extract<TranscriptEvent, { _tag: "metadata" }> => e._tag === "metadata"
+export const isError = (e: TranscriptEvent): e is Extract<TranscriptEvent, { _tag: "error" }> =>
+  e._tag === "error"

package/src/embedding-model/Embedding.ts

@@ -0,0 +1,117 @@
+import type { ImageSource } from "../domain/Image.js"
+
+/**
+ * One part of a mixed text+image input. Used inside `EmbedInput.content[]`
+ * for providers that accept interleaved modalities in a single embed call
+ * (Cohere v4, Voyage multimodal, Jina v4, Google `gemini-embedding-2`).
+ */
+export type EmbedContentPart = { readonly text: string } | { readonly image: ImageSource }
+
+/**
+ * What you embed. The `string` shorthand covers the common text-only case;
+ * structured variants exist for image-only and mixed-modality inputs.
+ *
+ * Not every provider accepts every variant: text-only providers (OpenAI,
+ * Mixedbread today) handle `string` and `{ text }`; multimodal providers
+ * (Google, Jina v4, Voyage multimodal, Cohere v4) handle all four. A
+ * provider layer rejects shapes it can't encode as `AiError.InvalidRequest`.
+ */
+export type EmbedInput =
+  | string
+  | { readonly text: string }
+  | { readonly image: ImageSource }
+  | { readonly content: ReadonlyArray<EmbedContentPart> }
+
+// ---------------------------------------------------------------------------
+// Embedding representations
+//
+// The `_tag` reflects the wire form the provider returned, *not* what the
+// consumer asked for - request `encoding: "int8"` and you get back an
+// `Int8Embedding`. Math primitives are typed against the named interfaces
+// (see `Vector.ts`) so e.g. `sparseCosine` only accepts `SparseEmbedding`.
+// ---------------------------------------------------------------------------
+
+/** Dense float32 vector. The default representation across all providers. */
+export type Float32Embedding = {
+  readonly _tag: "float32"
+  readonly vector: Float32Array
+}
+
+/**
+ * Dense int8-quantized vector. ~4x smaller than float32 with minimal
+ * recall loss on most benchmarks.
+ */
+export type Int8Embedding = {
+  readonly _tag: "int8"
+  readonly vector: Int8Array
+}
+
+/**
+ * Dense binary-quantized vector. One bit per dimension, packed into bytes.
+ * ~32x smaller than float32; meaningful recall loss but useful for hot
+ * indexes paired with a float32 reranker pass.
+ */
+export type BinaryEmbedding = {
+  readonly _tag: "binary"
+  readonly vector: Uint8Array
+}
+
+/**
+ * Sparse vector. Token-keyed weights for hybrid search (dense + lexical-
+ * style sparse). The single hosted producer today is Jina's `elser-v2`
+ * model, which returns subword tokens (e.g. `"bread"`, `"##ing"`) with
+ * their relevance weights.
+ *
+ * The shape is `Record<string, number>` rather than `(indices, values)`
+ * because real hosted learned-sparse encoders (ELSER, SPLADE) emit token
+ * strings with no shared vocabulary index. Converting to integer indices
+ * would either need a vocabulary table the model doesn't expose, or
+ * lose the cross-vector matching semantics. If a provider ever exposes
+ * index-valued sparse vectors (Pinecone-style, where you bring your own
+ * vocab), add an `IndexSparseEmbedding` sibling arm with `_tag:
+ * "sparse-indexed"`.
+ *
+ * Score with `Vector.sparseCosine` — dot product over the intersection
+ * of keys, normalized by the L2 norms of both maps.
+ */
+export type SparseEmbedding = {
+  readonly _tag: "sparse"
+  readonly weights: Readonly<Record<string, number>>
+}
+
+/**
+ * Multivector / late-interaction output: one float32 vector per token.
+ * Score documents with `Vector.maxSim` (ColBERT-style: per query vector,
+ * max dot product across doc vectors, summed). Typically ~50-500 vectors
+ * per document, each shorter than a single-vector embedding (~128 dim
+ * vs ~1024).
+ *
+ * Quantized multivector forms aren't modeled for the same reason as
+ * sparse - nothing on hosted APIs ships them yet.
+ */
+export type MultivectorEmbedding = {
+  readonly _tag: "multivector"
+  readonly vectors: ReadonlyArray<Float32Array>
+}
+
+export type Embedding =
+  | Float32Embedding
+  | Int8Embedding
+  | BinaryEmbedding
+  | SparseEmbedding
+  | MultivectorEmbedding
+
+export const isFloat32 = (e: Embedding): e is Float32Embedding => e._tag === "float32"
+export const isInt8 = (e: Embedding): e is Int8Embedding => e._tag === "int8"
+export const isBinary = (e: Embedding): e is BinaryEmbedding => e._tag === "binary"
+export const isSparse = (e: Embedding): e is SparseEmbedding => e._tag === "sparse"
+export const isMultivector = (e: Embedding): e is MultivectorEmbedding => e._tag === "multivector"
+
+/**
+ * Token usage for one embed / embedMany call. One value per HTTP request,
+ * not per input vector. Most providers populate `inputTokens`; the field
+ * is optional for those that don't (or for mock layers in tests).
+ */
+export type Usage = {
+  readonly inputTokens?: number
+}

package/src/embedding-model/EmbeddingModel.ts

@@ -0,0 +1,107 @@
+import { Context, Effect } from "effect"
+import * as AiError from "../domain/AiError.js"
+import type { Embedding, EmbedInput, Usage } from "./Embedding.js"
+
+/**
+ * Output representation requested from the provider.
+ *
+ * Dense quantizations - same vector at different storage cost:
+ * - `float32` — universal default.
+ * - `int8` — ~4x smaller; minimal recall loss on most benchmarks.
+ * - `binary` — ~32x smaller; meaningful recall loss but pairs well with
+ *   a float32 reranker pass over a small candidate set.
+ *
+ * Non-dense representations:
+ * - `sparse` — learned sparse vector for hybrid (dense + lexical) search.
+ *   Currently Jina ELSER only on hosted APIs.
+ * - `multivector` — one vector per token for late-interaction (ColBERT-
+ *   style) scoring via `Vector.maxSim`. Currently Jina v4 only.
+ *
+ * Each provider's typed request narrows this to its supported set at
+ * compile time (e.g. `JinaEncoding = "float32" | "binary" | "sparse" |
+ * "multivector"`). On the generic `EmbeddingModel` path, callers can
+ * pass any `Encoding` and the provider's API will reject mismatches at
+ * runtime.
+ */
+export type Encoding = "float32" | "int8" | "binary" | "sparse" | "multivector"
+
+/**
+ * Cross-provider single-embed request. Mirrors the shape of
+ * `LanguageModel.CommonRequest`: cross-cutting fields here, vendor
+ * specifics in the provider's typed request.
+ *
+ * Provider-specific extensions (Cohere widened `task` enum, Jina LoRA
+ * tasks, Mixedbread free-form `prompt`, etc.) live in that provider's own
+ * request interface, which extends this and narrows `model` / widens
+ * `task`.
+ */
+export type CommonEmbedRequest = {
+  readonly input: EmbedInput
+  /**
+   * Model identifier. Each provider narrows this to its typed literal
+   * union, so code that yields a typed provider tag gets autocompletion.
+   */
+  readonly model: string
+  /**
+   * Retrieval-task hint. Applies to the input. OpenAI ignores this;
+   * Mixedbread doesn't have it; Cohere v3+ requires it on the wire (typed
+   * as required in `CohereEmbedRequest`). Provider-specific task enums
+   * (classification, clustering, code retrieval, …) live on the
+   * provider's own request type.
+   */
+  readonly task?: "query" | "document"
+  /**
+   * Matryoshka truncation. Default: provider's native dimension.
+   * Discrete-value providers (Cohere, Vertex `multimodalembedding@001`)
+   * narrow this to a literal union in their typed request.
+   */
+  readonly dimensions?: number
+  /**
+   * Output representation - see {@link Encoding}. Dense float32 is the
+   * default; provider layers reject unsupported values up front with
+   * `InvalidRequest`.
+   */
+  readonly encoding?: Encoding
+}
+
+/**
+ * Cross-provider batch-embed request. One `task` for the whole batch -
+ * mixed-task batches aren't a real provider feature (rerankers exist for
+ * that).
+ */
+export type CommonEmbedManyRequest = Omit<CommonEmbedRequest, "input"> & {
+  readonly inputs: ReadonlyArray<EmbedInput>
+}
+
+export type EmbedResponse = {
+  readonly embedding: Embedding
+  readonly usage: Usage
+}
+
+export type EmbedManyResponse = {
+  readonly embeddings: ReadonlyArray<Embedding>
+  readonly usage: Usage
+}
+
+export type EmbeddingModelService = {
+  readonly embed: (request: CommonEmbedRequest) => Effect.Effect<EmbedResponse, AiError.AiError>
+  readonly embedMany: (
+    request: CommonEmbedManyRequest,
+  ) => Effect.Effect<EmbedManyResponse, AiError.AiError>
+}
+
+export class EmbeddingModel extends Context.Service<EmbeddingModel, EmbeddingModelService>()(
+  "@betalyra/effect-uai/EmbeddingModel",
+) {}
+
+/** Embed a single input. */
+export const embed = (
+  request: CommonEmbedRequest,
+): Effect.Effect<EmbedResponse, AiError.AiError, EmbeddingModel> =>
+  Effect.flatMap(EmbeddingModel.asEffect(), (m) => m.embed(request))
+
+/** Embed a batch in one provider call. Same `task` for every input. */
+export const embedMany = (
+  request: CommonEmbedManyRequest,
+): Effect.Effect<EmbedManyResponse, AiError.AiError, EmbeddingModel> =>
+  Effect.flatMap(EmbeddingModel.asEffect(), (m) => m.embedMany(request))

package/src/index.ts

@@ -1,11 +1,25 @@
 export * as AiError from "./domain/AiError.js"
+export * as Audio from "./domain/Audio.js"
+export * as Image from "./domain/Image.js"
 export * as Items from "./domain/Items.js"
+export * as Media from "./domain/Media.js"
+export * as Music from "./domain/Music.js"
+export * as Transcript from "./domain/Transcript.js"
 export * as Turn from "./domain/Turn.js"
+export * as Embedding from "./embedding-model/Embedding.js"
+export * as EmbeddingModel from "./embedding-model/EmbeddingModel.js"
 export * as LanguageModel from "./language-model/LanguageModel.js"
+export * as MusicGenerator from "./music-generator/MusicGenerator.js"
+export * as SpeechSynthesizer from "./speech-synthesizer/SpeechSynthesizer.js"
+export * as Transcriber from "./transcriber/Transcriber.js"
+export * as Vector from "./math/Vector.js"
 export * as Loop from "./loop/Loop.js"
-export * as Match from "./match/Match.js"
 export * as Tool from "./tool/Tool.js"
 export * as Toolkit from "./tool/Toolkit.js"
+export * as Outcome from "./tool/Outcome.js"
+export * as ToolEvent from "./tool/ToolEvent.js"
+export * as Resolvers from "./tool/Resolvers.js"
+export * as HistoryCheck from "./tool/HistoryCheck.js"
 export * as JSONL from "./streaming/JSONL.js"
 export * as Lines from "./streaming/Lines.js"
 export * as SSE from "./streaming/SSE.js"

package/src/language-model/LanguageModel.ts

@@ -11,7 +11,7 @@ import { isTurnComplete, type Turn, type TurnEvent } from "../domain/Turn.js"
  * to a single provider (reasoning effort, prompt caching, store flags,
  * ...) lives in that provider's own request interface, which extends this.
  */
-export interface CommonRequest {
+export type CommonRequest = {
   readonly history: ReadonlyArray<Item>
   /**
    * Model identifier. Each provider narrows this to its typed literal union,
@@ -36,7 +36,7 @@ export interface CommonRequest {
   readonly structured?: StructuredFormat.StructuredFormat<unknown>
 }
 
-export interface LanguageModelService {
+export type LanguageModelService = {
   readonly streamTurn: (request: CommonRequest) => Stream.Stream<TurnEvent, AiError.AiError>
 }
 
@@ -51,23 +51,3 @@ export const streamTurn = (
   request: CommonRequest,
 ): Stream.Stream<TurnEvent, AiError.AiError, LanguageModel> =>
   Stream.unwrap(Effect.map(LanguageModel.asEffect(), (m) => m.streamTurn(request)))
-
-/**
- * Run a single turn to completion and return the assembled `Turn`.
- *
- * Implementation: drain the delta stream and pluck the terminal
- * `turn_complete` event. The provider is contractually required to emit
- * exactly one such event as the last delta.
- */
-export const turn = (request: CommonRequest): Effect.Effect<Turn, AiError.AiError, LanguageModel> =>
-  Effect.flatMap(Stream.runCollect(streamTurn(request)), (deltas) => {
-    const last = deltas[deltas.length - 1]
-    return last !== undefined && isTurnComplete(last)
-      ? Effect.succeed(last.turn)
-      : Effect.fail(
-          new AiError.Unavailable({
-            provider: "unknown",
-            raw: "Provider stream ended without a turn_complete event",
-          }),
-        )
-  })

package/src/loop/Loop.test.ts

@@ -1,6 +1,15 @@
-import { Deferred, Effect, Fiber, Ref, Stream } from "effect"
+import { Deferred, Effect, Fiber, Latch, Ref, Stream, SubscriptionRef } from "effect"
 import { describe, expect, it } from "vitest"
-import { type Event, loop, next, nextAfter, stopEvent, stopAfter, value } from "./Loop.js"
+import {
+  type Event,
+  loop,
+  loopWithState,
+  next,
+  nextAfter,
+  stopEvent,
+  stopAfter,
+  value,
+} from "./Loop.js"
 
 describe("Loop.loop", () => {
   it("threads state across iterations and emits each iteration's substream in order", async () => {
@@ -410,3 +419,106 @@ describe("Loop.loop - pull-specific stream semantics", () => {
     expect(result._tag).toBe("Failure")
   })
 })
+
+describe("Loop.loopWithState", () => {
+  it("exposes the final state in the SubscriptionRef after the stream completes", async () => {
+    const program = Effect.gen(function* () {
+      const { stream, state } = yield* loopWithState(0, (n: number) =>
+        n >= 3 ? stopAfter(Stream.fromIterable([n])) : nextAfter(Stream.fromIterable([n]), n + 1),
+      )
+      const values = yield* Stream.runCollect(stream)
+      const finalState = yield* SubscriptionRef.get(state)
+      return { values: Array.from(values), finalState }
+    })
+
+    const { values, finalState } = await Effect.runPromise(program)
+    expect(values).toEqual([0, 1, 2, 3])
+    // Last `next(state)` was `next(3)` before the iteration that emitted Stop.
+    expect(finalState).toBe(3)
+  })
+
+  it("the state ref starts at `initial` and stays there if the loop stops without advancing", async () => {
+    const program = Effect.gen(function* () {
+      const { stream, state } = yield* loopWithState({ count: 7 }, () =>
+        Stream.fromIterable([stopEvent]),
+      )
+      yield* Stream.runDrain(stream)
+      return yield* SubscriptionRef.get(state)
+    })
+
+    expect(await Effect.runPromise(program)).toEqual({ count: 7 })
+  })
+
+  it("a downstream consumer can read the live state between emitted values", async () => {
+    // Body emits one value per iteration, then advances. A `Stream.runForEach`
+    // consumer reads the ref each time a value arrives — proving the ref
+    // tracks loop state without the body needing to surface it.
+    const program = Effect.gen(function* () {
+      const { stream, state } = yield* loopWithState(0, (n: number) =>
+        n >= 3 ? stopAfter(Stream.fromIterable([n])) : nextAfter(Stream.fromIterable([n]), n + 1),
+      )
+      const seen: Array<{ value: number; stateAfter: number }> = []
+      yield* Stream.runForEach(stream, (v) =>
+        Effect.gen(function* () {
+          seen.push({ value: v, stateAfter: yield* SubscriptionRef.get(state) })
+        }),
+      )
+      return seen
+    })
+
+    // For each iter `n`, the consumer reads the ref between values: it sees
+    // the iteration's input state. The terminal iter (n=3) stops without
+    // advancing, so its read still shows 3.
+    expect(await Effect.runPromise(program)).toEqual([
+      { value: 0, stateAfter: 0 },
+      { value: 1, stateAfter: 1 },
+      { value: 2, stateAfter: 2 },
+      { value: 3, stateAfter: 3 },
+    ])
+  })
+
+  it("SubscriptionRef.changes emits every state transition to a concurrent observer", async () => {
+    const program = Effect.gen(function* () {
+      const start = yield* Latch.make(false)
+
+      // Body waits on the latch in iter 0 so the observer can subscribe first.
+      const { stream, state } = yield* loopWithState(0, (n: number) =>
+        Effect.gen(function* () {
+          if (n === 0) yield* Latch.await(start)
+          return n >= 3 ? stopAfter(Stream.empty) : nextAfter(Stream.empty, n + 1)
+        }),
+      )
+
+      // Fork the observer; take 4 distinct states (initial + 3 transitions).
+      const observerFiber = yield* Effect.forkChild(
+        SubscriptionRef.changes(state).pipe(Stream.take(4), Stream.runCollect),
+      )
+
+      // Give the observer fiber a chance to actually subscribe before the
+      // loop starts advancing the ref. Without this, the loop could finish
+      // before the observer's pubsub subscription is in place.
+      yield* Effect.sleep("10 millis")
+
+      yield* Latch.open(start)
+      yield* Stream.runDrain(stream)
+
+      return Array.from(yield* Fiber.join(observerFiber))
+    })
+
+    // initial 0, then next(1), next(2), next(3) — four distinct states.
+    expect(await Effect.runPromise(program)).toEqual([0, 1, 2, 3])
+  })
+
+  it("does not interfere with the body's value stream", async () => {
+    const program = Effect.gen(function* () {
+      const { stream } = yield* loopWithState(0, (n: number) =>
+        n >= 3
+          ? stopAfter(Stream.fromIterable([n]))
+          : nextAfter(Stream.fromIterable([n, n + 0.5]), n + 1),
+      )
+      return Array.from(yield* Stream.runCollect(stream))
+    })
+
+    expect(await Effect.runPromise(program)).toEqual([0, 0.5, 1, 1.5, 2, 2.5, 3])
+  })
+})

package/src/loop/Loop.ts

@@ -17,7 +17,19 @@
  * (their producing side effects may already have run). Prefer the
  * `Loop.nextAfter` / `Loop.stopAfter` helpers to terminate cleanly.
  */
-import { Cause, Channel, Data, Effect, Exit, Function, Option, Ref, Scope, Stream } from "effect"
+import {
+  Cause,
+  Channel,
+  Data,
+  Effect,
+  Exit,
+  Function,
+  Option,
+  Ref,
+  Scope,
+  Stream,
+  SubscriptionRef,
+} from "effect"
 import { IncompleteTurn } from "../domain/AiError.js"
 import { isTurnComplete, type Turn, type TurnEvent } from "../domain/Turn.js"
 
@@ -83,7 +95,7 @@ export const stopAfter = <A, E, R>(
  * 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.nextStateFrom` to collect tool
+ * `build: (s) => s`). Used by `Toolkit.continueWith` to collect tool
  * results and build next state without exposing a Ref to recipes.
  */
 export const nextAfterFold = <A, B, S, E, R>(
@@ -107,7 +119,7 @@ export const nextAfterFold = <A, B, S, E, R>(
   )
 
 // ---------------------------------------------------------------------------
-// streamUntilComplete - turn-aware stream operator for loop bodies
+// onTurnComplete - turn-aware stream operator for loop bodies
 // ---------------------------------------------------------------------------
 
 /**
@@ -125,7 +137,7 @@ export const nextAfterFold = <A, B, S, E, R>(
  * fails with `AiError.IncompleteTurn`. Catch it via `Stream.catchTag` if
  * you want to recover.
  */
-export const streamUntilComplete =
+export const onTurnComplete =
   <S, A, E2 = never, R2 = never>(
     then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>,
   ) =>
@@ -162,7 +174,7 @@ export const streamUntilComplete =
 const isNonEmpty = <A>(array: ReadonlyArray<A>): array is readonly [A, ...Array<A>] =>
   array.length > 0
 
-interface CurrentBody<S, A, E, R> {
+type CurrentBody<S, A, E, R> = {
   readonly scope: Scope.Closeable
   readonly pull: Effect.Effect<ReadonlyArray<Event<A, S>>, E | Cause.Done<void>, R>
 }
@@ -293,3 +305,55 @@ export const loop: {
       ),
     ),
 )
+
+// ---------------------------------------------------------------------------
+// loopWithState - same body protocol, plus a live state observable.
+// ---------------------------------------------------------------------------
+
+/**
+ * Like `loop`, but exposes the current loop state as a `SubscriptionRef`
+ * 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
+ * before forwarding it. The caller decides how to consume both channels:
+ *
+ *   - **Final state**: drain the stream, then `SubscriptionRef.get(state)`
+ *     - the ref holds the state from the last `Next` (or `initial` if the
+ *     loop ended without advancing).
+ *   - **Live transitions**: `SubscriptionRef.changes(state)` is a
+ *     `Stream<S>` of every state observed; subscribe alongside the value
+ *     stream.
+ *   - **Mid-iteration peek**: `SubscriptionRef.get(state)` at any time.
+ *
+ * The returned stream and ref are independent of each other - the ref
+ * lives outside the stream's scope, so reading it after the stream
+ * completes is safe.
+ */
+export const loopWithState = <S, A, E, R>(
+  initial: S,
+  body: LoopBody<S, A, E, R>,
+): Effect.Effect<{
+  readonly stream: Stream.Stream<A, E, R>
+  readonly state: SubscriptionRef.SubscriptionRef<S>
+}> =>
+  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> =>
+      stream.pipe(
+        Stream.tap((event) =>
+          event._tag === "Next" ? SubscriptionRef.set(stateRef, event.state) : Effect.void,
+        ),
+      )
+
+    const wrappedBody: LoopBody<S, A, E, R> = (s) => {
+      const result = body(s)
+      return Effect.isEffect(result) ? Effect.map(result, tap) : tap(result)
+    }
+
+    return {
+      stream: loop(initial, wrappedBody),
+      state: stateRef,
+    }
+  })