@effect-uai/core 0.4.0 → 0.5.1

package/src/domain/Turn.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from "vitest"
+import * as Items from "./Items.js"
+import * as Turn from "./Turn.js"
+
+const turnOf = (items: Turn.Turn["items"]): Turn.Turn => ({
+  items,
+  usage: { input_tokens: 0, output_tokens: 0 },
+  stop_reason: "stop",
+})
+
+describe("Turn.assistantTexts", () => {
+  it("returns each output_text block in order across a single assistant message", () => {
+    const turn = turnOf([
+      {
+        type: "message",
+        role: "assistant",
+        content: [
+          { type: "output_text", text: "first" },
+          { type: "output_text", text: "second" },
+        ],
+      },
+    ])
+
+    expect(Turn.assistantTexts(turn)).toEqual(["first", "second"])
+  })
+
+  it("preserves order across multiple assistant messages", () => {
+    const turn = turnOf([
+      Items.assistantText("alpha"),
+      Items.assistantText("beta"),
+      Items.assistantText("gamma"),
+    ])
+
+    expect(Turn.assistantTexts(turn)).toEqual(["alpha", "beta", "gamma"])
+  })
+
+  it("drops refusal blocks and non-assistant messages", () => {
+    const turn = turnOf([
+      Items.userText("ignored"),
+      {
+        type: "message",
+        role: "assistant",
+        content: [
+          { type: "output_text", text: "kept" },
+          { type: "refusal", text: "I can't help with that." },
+        ],
+      },
+    ])
+
+    expect(Turn.assistantTexts(turn)).toEqual(["kept"])
+  })
+
+  it("returns an empty array when there's nothing to extract", () => {
+    expect(Turn.assistantTexts(turnOf([]))).toEqual([])
+    expect(Turn.assistantTexts(turnOf([Items.userText("only user")]))).toEqual([])
+  })
+
+  it("composes with caller-chosen separators", () => {
+    const turn = turnOf([Items.assistantText("hello"), Items.assistantText("world")])
+
+    expect(Turn.assistantTexts(turn).join("")).toBe("helloworld")
+    expect(Turn.assistantTexts(turn).join(" ")).toBe("hello world")
+    expect(Turn.assistantTexts(turn).join("\n")).toBe("hello\nworld")
+  })
+})
+
+describe("Turn.assistantText", () => {
+  it("concatenates output_text across a single assistant message's content blocks", () => {
+    const turn = turnOf([
+      {
+        type: "message",
+        role: "assistant",
+        content: [
+          { type: "output_text", text: "hello " },
+          { type: "output_text", text: "world" },
+        ],
+      },
+    ])
+
+    expect(Turn.assistantText(turn)).toBe("hello world")
+  })
+
+  it("concatenates output_text across multiple assistant messages", () => {
+    const turn = turnOf([Items.assistantText("first "), Items.assistantText("second")])
+
+    expect(Turn.assistantText(turn)).toBe("first second")
+  })
+
+  it("ignores non-assistant messages", () => {
+    const turn = turnOf([
+      Items.userText("ignored"),
+      Items.systemText("also ignored"),
+      Items.assistantText("kept"),
+    ])
+
+    expect(Turn.assistantText(turn)).toBe("kept")
+  })
+
+  it("ignores non-output_text content blocks (refusals, etc.)", () => {
+    const turn = turnOf([
+      {
+        type: "message",
+        role: "assistant",
+        content: [
+          { type: "output_text", text: "before " },
+          { type: "refusal", text: "I can't help with that." },
+          { type: "output_text", text: "after" },
+        ],
+      },
+    ])
+
+    expect(Turn.assistantText(turn)).toBe("before after")
+  })
+
+  it("ignores function_call items even when interleaved with messages", () => {
+    const turn = turnOf([
+      Items.assistantText("text "),
+      { type: "function_call", call_id: "c1", name: "search", arguments: "{}" },
+      Items.assistantText("more text"),
+    ])
+
+    expect(Turn.assistantText(turn)).toBe("text more text")
+  })
+
+  it("returns the empty string when no assistant messages exist", () => {
+    expect(Turn.assistantText(turnOf([]))).toBe("")
+    expect(Turn.assistantText(turnOf([Items.userText("only user")]))).toBe("")
+  })
+
+  it("returns the empty string when the assistant message has no output_text blocks", () => {
+    const turn = turnOf([
+      {
+        type: "message",
+        role: "assistant",
+        content: [{ type: "refusal", text: "I can't help." }],
+      },
+    ])
+
+    expect(Turn.assistantText(turn)).toBe("")
+  })
+})

package/src/domain/Turn.ts

@@ -27,54 +27,43 @@ export type Turn = typeof Turn.Type
 /**
  * Canonical events emitted while a single turn is being generated. Most
  * variants are streaming deltas (text, reasoning, tool-call args); the
- * terminal `turn_complete` carries the assembled `Turn`. Lifecycle members
+ * terminal `TurnComplete` carries the assembled `Turn`. Lifecycle members
  * aren't deltas, hence the union name.
+ *
+ * `ReasoningDelta.kind`: `trace` is the model's raw chain-of-thought;
+ * `summary` is a model-written summary intended for display. OpenAI
+ * Responses emits both; Anthropic and Gemini only emit `trace`.
+ *
+ * `RefusalDelta`: the model declined to answer. OpenAI Responses emits
+ * this as its own event; Anthropic surfaces refusals via `stop_reason`
+ * and Gemini collapses them into `finishReason: SAFETY` — both go
+ * without a `RefusalDelta`.
+ *
+ * `UsageUpdate`: mid-stream cumulative usage. Anthropic emits this on
+ * `message_start` and `message_delta`; other providers may only deliver
+ * usage via `TurnComplete.turn.usage`.
  */
-export type TurnEvent =
-  | { readonly type: "text_delta"; readonly text: string }
-  | {
-      readonly type: "reasoning_delta"
-      readonly text: string
-      /**
-       * `trace` is the model's raw chain-of-thought; `summary` is a
-       * model-written summary intended for display. OpenAI Responses emits
-       * both as separate wire events; Anthropic and Gemini only emit
-       * `trace`. Consumers who just want any reasoning text match once;
-       * those who want only summaries filter `kind === "summary"`.
-       */
-      readonly kind: "trace" | "summary"
-    }
-  /**
-   * The model declined to answer. `text` is the (streamed) explanation.
-   * Distinct from the failure channel: a refusal is normal model output and
-   * the stream still completes with `turn_complete`. OpenAI Responses emits
-   * this; Anthropic surfaces refusals via `stop_reason`, and Gemini collapses
-   * them into `finishReason: SAFETY` - both go without a `refusal_delta`.
-   */
-  | { readonly type: "refusal_delta"; readonly text: string }
-  | { readonly type: "tool_call_start"; readonly call_id: string; readonly name: string }
-  | { readonly type: "tool_call_args_delta"; readonly call_id: string; readonly delta: string }
-  /**
-   * Mid-stream cumulative usage. Carries the full `Usage` (including cache
-   * token fields when the provider surfaces them) so consumers can drive
-   * live budget / cost tracking without waiting for `turn_complete`.
-   * Anthropic emits this on `message_start` and `message_delta`; other
-   * providers may not emit any `usage_update` and only deliver usage via
-   * `turn_complete.turn.usage`.
-   */
-  | { readonly type: "usage_update"; readonly usage: Usage }
-  | { readonly type: "turn_complete"; readonly turn: Turn }
+export type TurnEvent = Data.TaggedEnum<{
+  TextDelta: { readonly text: string }
+  ReasoningDelta: { readonly text: string; readonly kind: "trace" | "summary" }
+  RefusalDelta: { readonly text: string }
+  ToolCallStart: { readonly call_id: string; readonly name: string }
+  ToolCallArgsDelta: { readonly call_id: string; readonly delta: string }
+  UsageUpdate: { readonly usage: Usage }
+  TurnComplete: { readonly turn: Turn }
+}>
+
+export const TurnEvent = Data.taggedEnum<TurnEvent>()
 
 /**
  * What flows out of an agent loop body to its consumer per turn: every
- * `TurnEvent` the provider emits (including the terminal `turn_complete`
+ * `TurnEvent` the provider emits (including the terminal `TurnComplete`
  * carrying the assembled `Turn`), plus the output of any tool the loop ran.
- * Both variants carry a `type` discriminator.
+ * Both variants carry a `_tag` discriminator.
  */
 export type InteractionEvent = TurnEvent | FunctionCallOutput
 
-export const isTurnComplete = (d: TurnEvent): d is Extract<TurnEvent, { type: "turn_complete" }> =>
-  d.type === "turn_complete"
+export const isTurnComplete = TurnEvent.$is("TurnComplete")
 
 export const functionCalls = (turn: Turn): ReadonlyArray<FunctionCall> =>
   turn.items.filter((i): i is FunctionCall => i.type === "function_call")
@@ -85,6 +74,26 @@ export const reasonings = (turn: Turn): ReadonlyArray<Reasoning> =>
 export const assistantMessages = (turn: Turn): ReadonlyArray<Message> =>
   turn.items.filter((i): i is Message => i.type === "message" && i.role === "assistant")
 
+/**
+ * Every `output_text` payload across every assistant message in the turn,
+ * preserving order. Refusals and other content blocks are dropped — use
+ * `assistantMessages` if you need to inspect them. The primitive for
+ * "give me the assistant's text"; callers decide how to combine
+ * (typically `.join("")` for prose or `.join(" ")` for log strings).
+ */
+export const assistantTexts = (turn: Turn): ReadonlyArray<string> =>
+  assistantMessages(turn)
+    .flatMap((m) => m.content)
+    .filter(isOutputText)
+    .map((b) => b.text)
+
+/**
+ * Sugar over `assistantTexts(turn).join("")` — the common case for
+ * summarizers, classifiers, judge calls, and structured-output backstops
+ * that want one concatenated string.
+ */
+export const assistantText = (turn: Turn): string => assistantTexts(turn).join("")
+
 /**
  * Append a completed turn and optional follow-up items to a state record's
  * history. Recipes use this at the point where structured tool results are
@@ -104,7 +113,7 @@ export const appendTurn = <S extends { readonly history: ReadonlyArray<Item> }>(
 // ---------------------------------------------------------------------------
 
 /**
- * Project a `TurnEvent` stream onto its `text_delta` payloads. Other
+ * Project a `TurnEvent` stream onto its `TextDelta` payloads. Other
  * variants are dropped. Composes with `Lines.lines` +
  * `decodeJsonLines` for prompted-JSONL streaming.
  */
@@ -112,9 +121,7 @@ export const textDeltas = <E, R>(
   self: Stream.Stream<TurnEvent, E, R>,
 ): Stream.Stream<string, E, R> =>
   self.pipe(
-    Stream.filterMap((ev) =>
-      ev.type === "text_delta" ? Result.succeed(ev.text) : Result.failVoid,
-    ),
+    Stream.filterMap((ev) => (ev._tag === "TextDelta" ? Result.succeed(ev.text) : Result.failVoid)),
   )
 
 // ---------------------------------------------------------------------------

package/src/embedding-model/Embedding.ts

@@ -107,6 +107,29 @@ export const isBinary = (e: Embedding): e is BinaryEmbedding => e._tag === "bina
 export const isSparse = (e: Embedding): e is SparseEmbedding => e._tag === "sparse"
 export const isMultivector = (e: Embedding): e is MultivectorEmbedding => e._tag === "multivector"
 
+/**
+ * Maps an `encoding` request field to the corresponding response embedding
+ * variant. `undefined` (no encoding requested) defaults to `Float32Embedding`,
+ * which is what every provider returns when the caller doesn't ask for
+ * anything else. Widened `E` falls back to the full `Embedding` union — the
+ * caller has to narrow at use site, which honestly reflects what they know
+ * at compile time.
+ *
+ * Used by `EmbedResponse<E>` / `EmbedManyResponse<E>` to give callers a
+ * precise embedding type without a runtime narrowing helper.
+ */
+export type EmbeddingFor<E> = [E] extends [undefined | "float32"]
+  ? Float32Embedding
+  : [E] extends ["int8"]
+    ? Int8Embedding
+    : [E] extends ["binary"]
+      ? BinaryEmbedding
+      : [E] extends ["sparse"]
+        ? SparseEmbedding
+        : [E] extends ["multivector"]
+          ? MultivectorEmbedding
+          : Embedding
+
 /**
  * Token usage for one embed / embedMany call. One value per HTTP request,
  * not per input vector. Most providers populate `inputTokens`; the field

package/src/embedding-model/EmbeddingModel.test.ts

@@ -0,0 +1,92 @@
+import { Effect } from "effect"
+import { describe, expectTypeOf, it } from "vitest"
+import type * as AiError from "../domain/AiError.js"
+import type {
+  BinaryEmbedding,
+  Float32Embedding,
+  Int8Embedding,
+  MultivectorEmbedding,
+  SparseEmbedding,
+} from "./Embedding.js"
+import {
+  type EmbedEncoding,
+  embed,
+  embedMany,
+  type EmbedManyResponse,
+  type EmbedResponse,
+  EmbeddingModel,
+} from "./EmbeddingModel.js"
+
+// Type-level tests only. The actual narrowing happens at the type system
+// boundary — the runtime impl is exercised in provider-specific test files.
+describe("EmbedResponse<E> conditional narrowing", () => {
+  it("defaults to Float32Embedding when E is undefined", () => {
+    expectTypeOf<EmbedResponse>().toEqualTypeOf<{
+      readonly embedding: Float32Embedding
+      readonly usage: import("./Embedding.js").Usage
+    }>()
+  })
+
+  it("maps each EmbedEncoding literal to the matching Embedding variant", () => {
+    expectTypeOf<EmbedResponse<"float32">["embedding"]>().toEqualTypeOf<Float32Embedding>()
+    expectTypeOf<EmbedResponse<"int8">["embedding"]>().toEqualTypeOf<Int8Embedding>()
+    expectTypeOf<EmbedResponse<"binary">["embedding"]>().toEqualTypeOf<BinaryEmbedding>()
+    expectTypeOf<EmbedResponse<"sparse">["embedding"]>().toEqualTypeOf<SparseEmbedding>()
+    expectTypeOf<EmbedResponse<"multivector">["embedding"]>().toEqualTypeOf<MultivectorEmbedding>()
+  })
+
+  it("falls back to the open Embedding union when E is the full EmbedEncoding", () => {
+    expectTypeOf<EmbedResponse<EmbedEncoding>["embedding"]>().toEqualTypeOf<
+      Float32Embedding | Int8Embedding | BinaryEmbedding | SparseEmbedding | MultivectorEmbedding
+    >()
+  })
+})
+
+describe("EmbedManyResponse<E> mirrors EmbedResponse<E>", () => {
+  it("defaults to ReadonlyArray<Float32Embedding>", () => {
+    expectTypeOf<EmbedManyResponse["embeddings"]>().toEqualTypeOf<ReadonlyArray<Float32Embedding>>()
+  })
+
+  it("narrows per encoding", () => {
+    expectTypeOf<EmbedManyResponse<"int8">["embeddings"]>().toEqualTypeOf<
+      ReadonlyArray<Int8Embedding>
+    >()
+  })
+})
+
+describe("embed / embedMany free exports preserve E in their return type", () => {
+  it("embed with no encoding returns EmbedResponse<undefined> = Float32", () => {
+    const result = embed({ input: "x", model: "m" })
+    expectTypeOf(result).toEqualTypeOf<
+      Effect.Effect<EmbedResponse<undefined>, AiError.AiError, EmbeddingModel>
+    >()
+  })
+
+  it("embed with encoding: int8 returns EmbedResponse<int8>", () => {
+    const result = embed({ input: "x", model: "m", encoding: "int8" })
+    expectTypeOf(result).toEqualTypeOf<
+      Effect.Effect<EmbedResponse<"int8">, AiError.AiError, EmbeddingModel>
+    >()
+  })
+
+  it("embedMany with encoding: multivector returns EmbedManyResponse<multivector>", () => {
+    const result = embedMany({ inputs: ["x"], model: "m", encoding: "multivector" })
+    expectTypeOf(result).toEqualTypeOf<
+      Effect.Effect<EmbedManyResponse<"multivector">, AiError.AiError, EmbeddingModel>
+    >()
+  })
+
+  it("when the request is widened to CommonEmbedRequest, the response is the open union", () => {
+    // Demonstrates the documented case: annotating the request type erases
+    // the literal `encoding` and the response falls back to `Embedding`.
+    const req: { input: string; model: string; encoding?: EmbedEncoding } = {
+      input: "x",
+      model: "m",
+      encoding: "int8",
+    }
+    const result = embed(req)
+    expectTypeOf(result).toEqualTypeOf<
+      Effect.Effect<EmbedResponse<EmbedEncoding>, AiError.AiError, EmbeddingModel>
+    >()
+  })
+})

package/src/embedding-model/EmbeddingModel.ts

@@ -1,6 +1,6 @@
 import { Context, Effect } from "effect"
 import * as AiError from "../domain/AiError.js"
-import type { Embedding, EmbedInput, Usage } from "./Embedding.js"
+import type { EmbeddingFor, EmbedInput, Usage } from "./Embedding.js"
 
 /**
  * Output representation requested from the provider.
@@ -18,12 +18,12 @@ import type { Embedding, EmbedInput, Usage } from "./Embedding.js"
  *   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" |
+ * compile time (e.g. `JinaEmbedEncoding = "float32" | "binary" | "sparse" |
  * "multivector"`). On the generic `EmbeddingModel` path, callers can
- * pass any `Encoding` and the provider's API will reject mismatches at
+ * pass any `EmbedEncoding` and the provider's API will reject mismatches at
  * runtime.
  */
-export type Encoding = "float32" | "int8" | "binary" | "sparse" | "multivector"
+export type EmbedEncoding = "float32" | "int8" | "binary" | "sparse" | "multivector"
 
 /**
  * Cross-provider single-embed request. Mirrors the shape of
@@ -57,11 +57,11 @@ export type CommonEmbedRequest = {
    */
   readonly dimensions?: number
   /**
-   * Output representation - see {@link Encoding}. Dense float32 is the
+   * Output representation - see {@link EmbedEncoding}. Dense float32 is the
    * default; provider layers reject unsupported values up front with
    * `InvalidRequest`.
    */
-  readonly encoding?: Encoding
+  readonly encoding?: EmbedEncoding
 }
 
 /**
@@ -73,21 +73,31 @@ export type CommonEmbedManyRequest = Omit<CommonEmbedRequest, "input"> & {
   readonly inputs: ReadonlyArray<EmbedInput>
 }
 
-export type EmbedResponse = {
-  readonly embedding: Embedding
+/**
+ * Single-embed response. The `embedding` type is determined by the
+ * request's `encoding` field via `EmbeddingFor<E>` — callers that don't
+ * specify an encoding get a `Float32Embedding` directly with no runtime
+ * narrowing. Defaults to `undefined` for back-compat with consumers that
+ * use the bare `EmbedResponse` name.
+ */
+export type EmbedResponse<E extends EmbedEncoding | undefined = undefined> = {
+  readonly embedding: EmbeddingFor<E>
   readonly usage: Usage
 }
 
-export type EmbedManyResponse = {
-  readonly embeddings: ReadonlyArray<Embedding>
+/** Batch-embed response. Same encoding rule as {@link EmbedResponse}. */
+export type EmbedManyResponse<E extends EmbedEncoding | undefined = undefined> = {
+  readonly embeddings: ReadonlyArray<EmbeddingFor<E>>
   readonly usage: Usage
 }
 
 export type EmbeddingModelService = {
-  readonly embed: (request: CommonEmbedRequest) => Effect.Effect<EmbedResponse, AiError.AiError>
-  readonly embedMany: (
-    request: CommonEmbedManyRequest,
-  ) => Effect.Effect<EmbedManyResponse, AiError.AiError>
+  readonly embed: <E extends EmbedEncoding | undefined = undefined>(
+    request: Omit<CommonEmbedRequest, "encoding"> & { readonly encoding?: E },
+  ) => Effect.Effect<EmbedResponse<E>, AiError.AiError>
+  readonly embedMany: <E extends EmbedEncoding | undefined = undefined>(
+    request: Omit<CommonEmbedManyRequest, "encoding"> & { readonly encoding?: E },
+  ) => Effect.Effect<EmbedManyResponse<E>, AiError.AiError>
 }
 
 export class EmbeddingModel extends Context.Service<EmbeddingModel, EmbeddingModelService>()(
@@ -95,13 +105,13 @@ export class EmbeddingModel extends Context.Service<EmbeddingModel, EmbeddingMod
 ) {}
 
 /** Embed a single input. */
-export const embed = (
-  request: CommonEmbedRequest,
-): Effect.Effect<EmbedResponse, AiError.AiError, EmbeddingModel> =>
+export const embed = <E extends EmbedEncoding | undefined = undefined>(
+  request: Omit<CommonEmbedRequest, "encoding"> & { readonly encoding?: E },
+): Effect.Effect<EmbedResponse<E>, 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> =>
+export const embedMany = <E extends EmbedEncoding | undefined = undefined>(
+  request: Omit<CommonEmbedManyRequest, "encoding"> & { readonly encoding?: E },
+): Effect.Effect<EmbedManyResponse<E>, AiError.AiError, EmbeddingModel> =>
   Effect.flatMap(EmbeddingModel.asEffect(), (m) => m.embedMany(request))

package/src/language-model/LanguageModel.test.ts

@@ -0,0 +1,170 @@
+import { Cause, Effect, Exit, Layer, Option, Ref, Schedule, Stream } from "effect"
+import { describe, expect, it } from "vitest"
+import * as AiError from "../domain/AiError.js"
+import * as Items from "../domain/Items.js"
+import { type Turn, TurnEvent } from "../domain/Turn.js"
+import { LanguageModel, retry, turn } from "./LanguageModel.js"
+import * as MockProvider from "../testing/MockProvider.js"
+
+const oneTextTurn = (text: string): Turn => ({
+  items: [Items.assistantText(text)],
+  usage: { input_tokens: 1, output_tokens: 1 },
+  stop_reason: "stop",
+})
+
+describe("LanguageModel.turn", () => {
+  it("returns the assembled Turn from the terminal TurnComplete event", async () => {
+    const expected = oneTextTurn("hello world")
+    const program = turn({ history: [Items.userText("hi")], model: "mock" })
+
+    const result = await Effect.runPromise(
+      program.pipe(Effect.provide(MockProvider.layer([expected]))),
+    )
+
+    expect(result).toEqual(expected)
+  })
+
+  it("fails with IncompleteTurn when the stream ends without TurnComplete", async () => {
+    // Custom service whose stream emits a single TextDelta and then ends.
+    const broken = Layer.succeed(LanguageModel, {
+      streamTurn: () => Stream.fromIterable<TurnEvent>([TurnEvent.TextDelta({ text: "partial" })]),
+    })
+
+    const program = turn({ history: [Items.userText("hi")], model: "mock" })
+    const exit = await Effect.runPromise(Effect.exit(program.pipe(Effect.provide(broken))))
+
+    expect(Exit.isFailure(exit)).toBe(true)
+    if (Exit.isFailure(exit)) {
+      const failure = Cause.findErrorOption(exit.cause)
+      expect(Option.isSome(failure)).toBe(true)
+      if (Option.isSome(failure)) {
+        expect(failure.value).toBeInstanceOf(AiError.IncompleteTurn)
+      }
+    }
+  })
+
+  it("propagates an AiError raised by streamTurn", async () => {
+    const rateLimited = new AiError.RateLimited({ provider: "mock", raw: null })
+    const failing = Layer.succeed(LanguageModel, {
+      streamTurn: () => Stream.fail<AiError.AiError>(rateLimited),
+    })
+
+    const program = turn({ history: [], model: "mock" })
+    const exit = await Effect.runPromise(Effect.exit(program.pipe(Effect.provide(failing))))
+
+    expect(Exit.isFailure(exit)).toBe(true)
+    if (Exit.isFailure(exit)) {
+      expect(Cause.findErrorOption(exit.cause)).toEqual(Option.some(rateLimited))
+    }
+  })
+
+  it("returns the LAST TurnComplete when the stream contains multiple (defensive)", async () => {
+    // A misbehaving provider might emit two TurnComplete events; turn
+    // should pick the last one (the most recent assembled Turn).
+    const first = oneTextTurn("first")
+    const second = oneTextTurn("second")
+    const weird = Layer.succeed(LanguageModel, {
+      streamTurn: () =>
+        Stream.fromIterable<TurnEvent>([
+          TurnEvent.TurnComplete({ turn: first }),
+          TurnEvent.TurnComplete({ turn: second }),
+        ]),
+    })
+
+    const program = turn({ history: [], model: "mock" })
+    const result = await Effect.runPromise(program.pipe(Effect.provide(weird)))
+
+    expect(result).toEqual(second)
+  })
+})
+
+describe("LanguageModel.retry", () => {
+  const textDelta = (text: string): TurnEvent => TurnEvent.TextDelta({ text })
+  const textTurn = (text: string): Turn => ({
+    items: [Items.assistantText(text)],
+    usage: { input_tokens: 0, output_tokens: 0 },
+    stop_reason: "stop",
+  })
+  const completeEvent = (text: string): TurnEvent =>
+    TurnEvent.TurnComplete({ turn: textTurn(text) })
+
+  // Builds a stream that emits a failure or success based on attempt counter.
+  // Each call to the returned Effect produces a fresh attempt stream.
+  const attemptStream = (
+    attempts: Ref.Ref<number>,
+    plan: ReadonlyArray<Stream.Stream<TurnEvent, AiError.AiError>>,
+  ): Stream.Stream<TurnEvent, AiError.AiError> =>
+    Stream.unwrap(
+      Ref.getAndUpdate(attempts, (n) => n + 1).pipe(
+        Effect.map((n) => plan[Math.min(n, plan.length - 1)]!),
+      ),
+    )
+
+  it("retries on RateLimited and yields the success on the next attempt", async () => {
+    const program = Effect.gen(function* () {
+      const attempts = yield* Ref.make(0)
+      const stream = attemptStream(attempts, [
+        Stream.fail(new AiError.RateLimited({ provider: "mock", raw: null })),
+        Stream.fromIterable([textDelta("ok"), completeEvent("ok")]),
+      ]).pipe(retry(Schedule.recurs(3)))
+      const events = yield* Stream.runCollect(stream)
+      const count = yield* Ref.get(attempts)
+      return { events: Array.from(events), count }
+    })
+
+    const { events, count } = await Effect.runPromise(program)
+    expect(count).toBe(2)
+    expect(events.map((e) => e._tag)).toEqual(["TextDelta", "TurnComplete"])
+  })
+
+  it("surfaces the underlying retryable failure when retries are exhausted", async () => {
+    const cause = new AiError.Unavailable({ provider: "mock", raw: null })
+    const stream = Stream.fail<AiError.AiError>(cause).pipe(retry(Schedule.recurs(2)))
+
+    const exit = await Effect.runPromise(Effect.exit(Stream.runCollect(stream)))
+    expect(Exit.isFailure(exit)).toBe(true)
+    if (Exit.isFailure(exit)) {
+      expect(Cause.findErrorOption(exit.cause)).toEqual(Option.some(cause))
+    }
+  })
+
+  it("bypasses retry for non-retryable AiError (ContentFiltered)", async () => {
+    const program = Effect.gen(function* () {
+      const attempts = yield* Ref.make(0)
+      const cause = new AiError.ContentFiltered({ provider: "mock", raw: null })
+      const stream = attemptStream(attempts, [Stream.fail(cause)]).pipe(retry(Schedule.recurs(5)))
+      const exit = yield* Effect.exit(Stream.runCollect(stream))
+      const count = yield* Ref.get(attempts)
+      return { exit, count, cause }
+    })
+
+    const { exit, count, cause } = await Effect.runPromise(program)
+    expect(count).toBe(1) // no retry happened
+    expect(Exit.isFailure(exit)).toBe(true)
+    if (Exit.isFailure(exit)) {
+      expect(Cause.findErrorOption(exit.cause)).toEqual(Option.some(cause))
+    }
+  })
+
+  it("preserves deltas emitted before a retryable failure (and replays on retry)", async () => {
+    // Documents the 'replays on retry' caveat in the JSDoc — first attempt
+    // emits a delta then fails; second attempt is a clean success. Consumer
+    // sees the first delta twice (once from the failed attempt, once from
+    // the replay).
+    const program = Effect.gen(function* () {
+      const attempts = yield* Ref.make(0)
+      const stream = attemptStream(attempts, [
+        Stream.concat(
+          Stream.succeed<TurnEvent>(textDelta("partial")),
+          Stream.fail(new AiError.Timeout({ provider: "mock", raw: null })),
+        ),
+        Stream.fromIterable([textDelta("partial"), completeEvent("done")]),
+      ]).pipe(retry(Schedule.recurs(1)))
+      const events = yield* Stream.runCollect(stream)
+      return Array.from(events)
+    })
+
+    const events = await Effect.runPromise(program)
+    expect(events.map((e) => e._tag)).toEqual(["TextDelta", "TextDelta", "TurnComplete"])
+  })
+})