@effect-uai/core 0.5.2 → 0.7.0

package/src/sandbox/SandboxError.ts

@@ -0,0 +1,140 @@
+import { Data, Duration } from "effect"
+
+/**
+ * Failed to provision a sandbox. Covers image pull failures, region
+ * unavailability, the provider being unreachable, etc. The provider's
+ * structured reason (if any) is on `reason`; the raw error from the
+ * underlying SDK is on `raw`.
+ */
+export class SandboxCreateFailed extends Data.TaggedError("SandboxCreateFailed")<{
+  provider: string
+  reason?: string
+  raw: unknown
+}> {}
+
+/**
+ * The requested sandbox id does not exist (or was already destroyed).
+ * Distinct from `SandboxCreateFailed` — this is for `attach` / `destroy` /
+ * `get`-style lookups against a stale id.
+ */
+export class SandboxNotFound extends Data.TaggedError("SandboxNotFound")<{
+  provider: string
+  id: string
+}> {}
+
+/**
+ * Caller tried to create a sandbox whose id is already taken. Providers
+ * that keyed by name (Microsandbox, Modal) surface this when a previous
+ * sandbox with the same name is still alive. Distinct from
+ * `SandboxCreateFailed` so callers can retry with `replace` semantics.
+ */
+export class SandboxAlreadyExists extends Data.TaggedError("SandboxAlreadyExists")<{
+  provider: string
+  id: string
+}> {}
+
+/**
+ * A shell exec inside the sandbox failed at the transport / SDK layer —
+ * i.e. the SDK couldn't deliver the command to the guest, or the guest
+ * agent itself errored. A non-zero exit code from the guest's command
+ * is NOT an error; it's an `ExecResult` with `exitCode !== 0`.
+ */
+export class SandboxExecFailed extends Data.TaggedError("SandboxExecFailed")<{
+  provider: string
+  reason?: string
+  raw: unknown
+}> {}
+
+/**
+ * A sandbox operation (create, exec, file op) exceeded its time budget.
+ * Carries the budget that was breached for observability.
+ */
+export class SandboxTimeout extends Data.TaggedError("SandboxTimeout")<{
+  provider: string
+  operation: "create" | "exec" | "filesystem" | "attach"
+  budget?: Duration.Duration
+  raw?: unknown
+}> {}
+
+/**
+ * Outbound network request from inside the sandbox was blocked by the
+ * configured egress policy (host not on allowlist, CIDR mismatch, etc.).
+ * Surfaced when the provider's SDK reports the denial back to the host
+ * — many providers simply let the request fail inside the guest and
+ * never report this to the host, in which case this error is never
+ * raised by the adapter.
+ */
+export class SandboxNetworkPolicyDenied extends Data.TaggedError("SandboxNetworkPolicyDenied")<{
+  provider: string
+  host?: string
+  reason?: string
+  raw: unknown
+}> {}
+
+/**
+ * Provider rejected the create / exec because account / org / project
+ * quota or concurrency limit was exceeded. Surfaced separately from
+ * `SandboxCreateFailed` so callers can back off and retry intelligently.
+ */
+export class SandboxQuotaExceeded extends Data.TaggedError("SandboxQuotaExceeded")<{
+  provider: string
+  reason?: string
+  raw: unknown
+}> {}
+
+/**
+ * Caller's request shape is malformed for the wired provider — e.g. a
+ * Dockerfile passed to a provider that only accepts registry refs, a
+ * hostname allowlist passed to a CIDR-only provider, etc. Adapters
+ * should also reject these at the request-schema layer where possible;
+ * this is the runtime fallback.
+ */
+export class SandboxInvalidRequest extends Data.TaggedError("SandboxInvalidRequest")<{
+  provider: string
+  param?: string
+  reason?: string
+  raw?: unknown
+}> {}
+
+/**
+ * Sandbox SDK could not authenticate against the provider. Subtype
+ * mirrors the model-side `AiError.AuthFailed` shape for consistency.
+ */
+export type SandboxAuthSubtype = "auth" | "permission" | "billing" | "quota"
+
+export class SandboxAuthFailed extends Data.TaggedError("SandboxAuthFailed")<{
+  provider: string
+  subtype: SandboxAuthSubtype
+  raw: unknown
+}> {}
+
+/**
+ * The wired provider does not implement the requested capability for
+ * this specific request. Distinct from `SandboxInvalidRequest` (the
+ * request shape is malformed) and from compile-time capability
+ * markers (`SandboxSnapshots`, `SandboxSecretInjection`, …) which gate
+ * blanket provider-level gaps.
+ *
+ * Reserved for request-data-dependent gaps where the provider supports
+ * the method in general but not for these inputs — e.g. passing
+ * `hosts: [...]` to a CIDR-only allowlist provider, or passing
+ * `dockerfile: ...` to a provider whose `SandboxCustomImage` marker
+ * was provided but which only accepts a flat Dockerfile string.
+ */
+export class SandboxUnsupported extends Data.TaggedError("SandboxUnsupported")<{
+  provider: string
+  capability: string
+  reason?: string
+}> {}
+
+export type SandboxError =
+  | SandboxCreateFailed
+  | SandboxNotFound
+  | SandboxAlreadyExists
+  | SandboxExecFailed
+  | SandboxTimeout
+  | SandboxNetworkPolicyDenied
+  | SandboxQuotaExceeded
+  | SandboxInvalidRequest
+  | SandboxAuthFailed
+  | SandboxUnsupported

package/src/sandbox/SandboxImage.ts

@@ -0,0 +1,26 @@
+import { ImageRef, SnapshotId } from "./Sandbox.js"
+
+/**
+ * Ergonomic constructors for {@link ImageRef}. `ImageRef.*` tagged
+ * constructors still exist (and are what pattern-matching code uses);
+ * these helpers are what end users reach for at the call site.
+ *
+ * @example
+ * ```ts
+ * import * as Image from "@effect-uai/core/SandboxImage"
+ *
+ * Image.auto                         // provider's house image
+ * Image.registry("python:3.12")      // OCI registry ref
+ * Image.snapshot("ml-warm-1")        // restore captured state (gated)
+ * Image.dockerfile("FROM ubuntu...") // build custom (gated)
+ * ```
+ */
+
+export const auto: ImageRef = ImageRef.Default()
+
+export const registry = (ref: string): ImageRef => ImageRef.Registry({ ref })
+
+export const snapshot = (id: SnapshotId | string): ImageRef =>
+  ImageRef.Snapshot({ id: SnapshotId(id) })
+
+export const dockerfile = (contents: string): ImageRef => ImageRef.Dockerfile({ contents })

package/src/sandbox/SandboxNetwork.ts

@@ -0,0 +1,34 @@
+import { NetworkPolicy } from "./Sandbox.js"
+
+/**
+ * Ergonomic constructors for {@link NetworkPolicy}. The tagged
+ * constructors under `Sandbox.NetworkPolicy.*` still exist (and are
+ * what pattern-matching code uses); these helpers are what end users
+ * reach for at the call site.
+ *
+ * @example
+ * ```ts
+ * import * as Network from "@effect-uai/core/SandboxNetwork"
+ *
+ * Network.open                                    // provider defaults apply
+ * Network.blocked                                 // airgapped — no egress
+ * Network.allowHosts("api.openai.com", "github.com")
+ * Network.allowCidrs("10.0.0.0/8")
+ * Network.allow({ hosts: [...], cidrs: [...] })   // combined allowlist
+ * ```
+ */
+
+export const open: NetworkPolicy = NetworkPolicy.Open()
+
+export const blocked: NetworkPolicy = NetworkPolicy.Blocked()
+
+export const allowHosts = (...hosts: ReadonlyArray<string>): NetworkPolicy =>
+  NetworkPolicy.Allowlist({ hosts })
+
+export const allowCidrs = (...cidrs: ReadonlyArray<string>): NetworkPolicy =>
+  NetworkPolicy.Allowlist({ cidrs })
+
+export const allow = (opts: {
+  readonly hosts?: ReadonlyArray<string>
+  readonly cidrs?: ReadonlyArray<string>
+}): NetworkPolicy => NetworkPolicy.Allowlist(opts)

package/src/speech-synthesizer/SpeechSynthesizer.test.ts

@@ -1,4 +1,4 @@
-import { Effect, Stream } from "effect"
+import { Duration, Effect, Stream } from "effect"
 import { describe, expect, expectTypeOf, it } from "vitest"
 import type * as AiError from "../domain/AiError.js"
 import type { AudioBlob, AudioChunk, AudioFormat } from "../domain/Audio.js"
@@ -14,7 +14,7 @@ const pcmFormat: AudioFormat = {
 const blob: AudioBlob = {
   format: pcmFormat,
   bytes: new Uint8Array([0xde, 0xad, 0xbe, 0xef]),
-  durationSeconds: 0.5,
+  duration: Duration.millis(500),
 }
 
 const chunk = (n: number): AudioChunk => ({ bytes: new Uint8Array([n]) })
@@ -29,7 +29,7 @@ describe("SpeechSynthesizer.synthesize", () => {
     })
     const result = await Effect.runPromise(program.pipe(Effect.provide(mock.layer)))
     expect(result.bytes).toEqual(blob.bytes)
-    expect(result.durationSeconds).toBe(0.5)
+    expect(result.duration).toEqual(Duration.millis(500))
   })
 })
 
@@ -106,6 +106,95 @@ describe("SpeechSynthesizer capability marker (compile-time)", () => {
   })
 })
 
+describe("SpeechSynthesizer.synthesizeDialogue", () => {
+  const dialogueReq: SpeechSynthesizer.CommonSynthesizeDialogueRequest = {
+    model: "mock-tts",
+    turns: [
+      { voiceId: "voice-a", text: "Hi" },
+      { voiceId: "voice-b", text: "Hello" },
+    ],
+  }
+
+  it("returns the scripted AudioBlob", async () => {
+    const mock = MockSpeechSynthesizer.layer({ dialogueBlobs: [blob] })
+    const result = await Effect.runPromise(
+      SpeechSynthesizer.synthesizeDialogue(dialogueReq).pipe(Effect.provide(mock.layer)),
+    )
+    expect(result.bytes).toEqual(blob.bytes)
+  })
+
+  it("records the request on the synthesizeDialogue call channel", async () => {
+    const mock = MockSpeechSynthesizer.layer({ dialogueBlobs: [blob] })
+    const program = Effect.gen(function* () {
+      yield* SpeechSynthesizer.synthesizeDialogue(dialogueReq)
+      return yield* mock.recorder
+    })
+    const rec = await Effect.runPromise(program.pipe(Effect.provide(mock.layer)))
+    expect(rec.synthesizeDialogueCalls.length).toBe(1)
+    expect(rec.synthesizeDialogueCalls[0]!.turns.length).toBe(2)
+    expect(rec.synthesizeCalls.length).toBe(0)
+  })
+
+  it("emits scripted chunks for streamSynthesizeDialogue", async () => {
+    const mock = MockSpeechSynthesizer.layer({
+      streamSynthesizeDialogueChunks: [[chunk(7), chunk(8)]],
+    })
+    const out = await Effect.runPromise(
+      Stream.runCollect(SpeechSynthesizer.streamSynthesizeDialogue(dialogueReq)).pipe(
+        Effect.provide(mock.layer),
+      ),
+    )
+    expect(out.map((c) => Array.from(c.bytes))).toEqual([[7], [8]])
+  })
+})
+
+describe("MultiSpeakerTts capability marker (compile-time)", () => {
+  const dialogueReq: SpeechSynthesizer.CommonSynthesizeDialogueRequest = {
+    model: "mock-tts",
+    turns: [{ voiceId: "a", text: "Hi" }],
+  }
+
+  it("requires `MultiSpeakerTts` on the R channel of synthesizeDialogue", () => {
+    const eff = SpeechSynthesizer.synthesizeDialogue(dialogueReq)
+    expectTypeOf(eff).toEqualTypeOf<
+      Effect.Effect<
+        AudioBlob,
+        AiError.AiError,
+        SpeechSynthesizer.SpeechSynthesizer | SpeechSynthesizer.MultiSpeakerTts
+      >
+    >()
+  })
+
+  it("requires `MultiSpeakerTts` on the R channel of streamSynthesizeDialogue", () => {
+    const s = SpeechSynthesizer.streamSynthesizeDialogue(dialogueReq)
+    expectTypeOf(s).toEqualTypeOf<
+      Stream.Stream<
+        AudioChunk,
+        AiError.AiError,
+        SpeechSynthesizer.SpeechSynthesizer | SpeechSynthesizer.MultiSpeakerTts
+      >
+    >()
+  })
+
+  it("a layer without the marker leaves `MultiSpeakerTts` unsatisfied in R", () => {
+    const noMarker = MockSpeechSynthesizer.layerWithoutMultiSpeaker({})
+    const program = SpeechSynthesizer.synthesizeDialogue(dialogueReq).pipe(
+      Effect.provide(noMarker.layer),
+    )
+    expectTypeOf(program).toEqualTypeOf<
+      Effect.Effect<AudioBlob, AiError.AiError, SpeechSynthesizer.MultiSpeakerTts>
+    >()
+  })
+
+  it("a full layer (with marker) clears R to never", () => {
+    const fullMock = MockSpeechSynthesizer.layer({ dialogueBlobs: [blob] })
+    const program = SpeechSynthesizer.synthesizeDialogue(dialogueReq).pipe(
+      Effect.provide(fullMock.layer),
+    )
+    expectTypeOf(program).toEqualTypeOf<Effect.Effect<AudioBlob, AiError.AiError, never>>()
+  })
+})
+
 describe("SpeechSynthesizer.streamSynthesisFrom", () => {
   const ssfReq: SpeechSynthesizer.CommonStreamSynthesizeRequest = {
     model: "mock-tts",

package/src/speech-synthesizer/SpeechSynthesizer.ts

@@ -2,6 +2,23 @@ import { Context, Effect, Function, Stream } from "effect"
 import * as AiError from "../domain/AiError.js"
 import type { AudioBlob, AudioChunk, AudioFormat } from "../domain/Audio.js"
 
+/**
+ * Per-phrase pronunciation override. `pronunciation` is always IPA, the
+ * universal phonetic interchange format. Adapters translate to the
+ * provider's wire form (inline `/ipa/` token, SSML `<phoneme>`, or a
+ * structured field), converting IPA to X-SAMPA internally where the wire
+ * requires it (Google, Azure).
+ *
+ * Pronunciations are load-bearing (the configured word is mispronounced
+ * if dropped), so a provider with no stateless IPA path fails the call
+ * with `AiError.Unsupported` rather than silently degrading.
+ */
+export type CustomPronunciation = {
+  readonly phrase: string
+  /** IPA notation, e.g. `"ænˈθrɒpɪk"`. */
+  readonly pronunciation: string
+}
+
 /**
  * Cross-provider synthesis request. Provider-specific extensions
  * (ElevenLabs `stability` / `similarity_boost`, Cartesia `emotion`,
@@ -23,6 +40,13 @@ export type CommonSynthesizeRequest = {
   readonly outputFormat?: AudioFormat
   readonly speed?: number
   readonly languageCode?: string
+  /**
+   * IPA phoneme overrides for specific phrases. Adapters render them to
+   * the provider's wire form (inline token, SSML `<phoneme>`, structured
+   * field). Load-bearing: a provider with no stateless IPA path fails
+   * the call with `AiError.Unsupported` rather than mispronouncing.
+   */
+  readonly pronunciations?: ReadonlyArray<CustomPronunciation>
 }
 
 /**
@@ -36,6 +60,31 @@ export type CommonSynthesizeRequest = {
  */
 export type CommonStreamSynthesizeRequest = Omit<CommonSynthesizeRequest, "text">
 
+/**
+ * One turn in a multi-speaker dialogue. Just a voice and its line; the
+ * only in-tree dialogue endpoint (ElevenLabs `/v1/text-to-dialogue`)
+ * accepts `{ voice_id, text }` per turn. Per-turn styling knobs
+ * (Hume Octave-2 `styleDescription` / `speed`) are provider-specific
+ * and belong on a provider-typed turn extension, not here.
+ */
+export type DialogueTurn = {
+  readonly voiceId: string
+  readonly text: string
+}
+
+/**
+ * Cross-provider dialogue request. Same return type as `synthesize` —
+ * one continuous `AudioBlob`. Per-turn timing metadata is not exposed
+ * in the common shape (only Hume returns it natively).
+ */
+export type CommonSynthesizeDialogueRequest = {
+  readonly model: string
+  readonly turns: ReadonlyArray<DialogueTurn>
+  readonly outputFormat?: AudioFormat
+  readonly languageCode?: string
+  readonly pronunciations?: ReadonlyArray<CustomPronunciation>
+}
+
 export type SpeechSynthesizerService = {
   /** One-shot. Full text in, full audio bytes out. Universally supported. */
   readonly synthesize: (
@@ -62,6 +111,26 @@ export type SpeechSynthesizerService = {
     textIn: Stream.Stream<string, E, R>,
     request: CommonStreamSynthesizeRequest,
   ) => Stream.Stream<AudioChunk, AiError.AiError | E, R>
+  /**
+   * One-shot multi-speaker dialogue. Turn array in, single `AudioBlob`
+   * out. Providers without native dialogue support return
+   * `AiError.Unsupported` and do NOT ship the `MultiSpeakerTts` marker
+   * — calls via the top-level helper become a compile-time error.
+   */
+  readonly synthesizeDialogue: (
+    request: CommonSynthesizeDialogueRequest,
+  ) => Effect.Effect<AudioBlob, AiError.AiError>
+  /**
+   * Chunked-streaming variant of `synthesizeDialogue`. Same input,
+   * audio chunks emitted as the wire delivers them. Providers that
+   * synthesize the whole dialogue server-side may fall back to a
+   * single-chunk wrap of the sync result.
+   *
+   * Gated by `MultiSpeakerTts` at the top-level helper.
+   */
+  readonly streamSynthesizeDialogue: (
+    request: CommonSynthesizeDialogueRequest,
+  ) => Stream.Stream<AudioChunk, AiError.AiError>
 }
 
 export class SpeechSynthesizer extends Context.Service<
@@ -83,6 +152,19 @@ export class TtsIncrementalText extends Context.Service<TtsIncrementalText, void
   "@betalyra/effect-uai/capability/TtsIncrementalText",
 ) {}
 
+/**
+ * Capability marker for multi-speaker dialogue. Shipped by provider
+ * Layers whose `synthesizeDialogue` is wired to a native multi-speaker
+ * endpoint (ElevenLabs `/v1/text-to-dialogue`, Hume `/v0/tts` with
+ * `utterances[]`, Google Cloud TTS Gemini TTS `multiSpeakerMarkup`).
+ * Other providers leave the marker unregistered so the top-level
+ * `synthesizeDialogue` / `streamSynthesizeDialogue` helpers fail to
+ * satisfy R against those Layers — compile-time error.
+ */
+export class MultiSpeakerTts extends Context.Service<MultiSpeakerTts, void>()(
+  "@betalyra/effect-uai/capability/MultiSpeakerTts",
+) {}
+
 /** One-shot synthesis. */
 export const synthesize = (
   request: CommonSynthesizeRequest,
@@ -129,3 +211,30 @@ export const streamSynthesisFrom: {
       }),
     ),
 )
+
+/**
+ * One-shot multi-speaker dialogue. Requires `MultiSpeakerTts` in R —
+ * providers without dialogue support are a compile-time error.
+ */
+export const synthesizeDialogue = (
+  request: CommonSynthesizeDialogueRequest,
+): Effect.Effect<AudioBlob, AiError.AiError, SpeechSynthesizer | MultiSpeakerTts> =>
+  Effect.gen(function* () {
+    const s = yield* SpeechSynthesizer.asEffect()
+    yield* MultiSpeakerTts.asEffect()
+    return yield* s.synthesizeDialogue(request)
+  })
+
+/**
+ * Chunked-streaming variant. Same R requirement as `synthesizeDialogue`.
+ */
+export const streamSynthesizeDialogue = (
+  request: CommonSynthesizeDialogueRequest,
+): Stream.Stream<AudioChunk, AiError.AiError, SpeechSynthesizer | MultiSpeakerTts> =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const s = yield* SpeechSynthesizer.asEffect()
+      yield* MultiSpeakerTts.asEffect()
+      return s.streamSynthesizeDialogue(request)
+    }),
+  )

package/src/testing/MockMusicGenerator.ts

@@ -1,11 +1,13 @@
 import { Effect, Layer, Ref, Stream } from "effect"
 import * as AiError from "../domain/AiError.js"
 import type { AudioChunk } from "../domain/Audio.js"
-import type {
-  CommonGenerateMusicRequest,
-  CommonStreamGenerateMusicRequest,
-  MusicResult,
-  MusicSessionInput,
+import {
+  audioEvent,
+  type CommonGenerateMusicRequest,
+  type CommonStreamGenerateMusicRequest,
+  type GenerateResult,
+  type MusicSessionInput,
+  type MusicStreamEvent,
 } from "../domain/Music.js"
 import {
   MusicGenerator,
@@ -21,11 +23,15 @@ export type MockMusicGeneratorRecorder = {
 
 export type MockMusicGeneratorScript = {
   /** One result per `generate` call, consumed in order. */
-  readonly results?: ReadonlyArray<MusicResult>
+  readonly results?: ReadonlyArray<GenerateResult>
   /** One chunk-list per `streamGeneration` call, consumed in order. */
   readonly streamGenerationChunks?: ReadonlyArray<ReadonlyArray<AudioChunk>>
-  /** One chunk-list per `streamGenerationFrom` call, consumed in order. */
-  readonly streamGenerationFromChunks?: ReadonlyArray<ReadonlyArray<AudioChunk>>
+  /**
+   * One event-list per `streamGenerationFrom` call, consumed in order.
+   * If a list contains only `AudioChunk`s for ergonomics, wrap them in
+   * `audioEvent(chunk)` first.
+   */
+  readonly streamGenerationFromEvents?: ReadonlyArray<ReadonlyArray<MusicStreamEvent>>
 }
 
 const makeService = (
@@ -74,22 +80,23 @@ const makeService = (
       streamGenerationFrom: <E, R>(
         input: Stream.Stream<MusicSessionInput, E, R>,
         request: CommonStreamGenerateMusicRequest,
-      ): Stream.Stream<AudioChunk, AiError.AiError | E, R> =>
+      ): Stream.Stream<MusicStreamEvent, AiError.AiError | E, R> =>
         Stream.unwrap(
           Effect.gen(function* () {
             yield* record.streamGenerationFrom(request)
             const i = yield* Ref.getAndUpdate(sgfCursor, (n) => n + 1)
-            const scripted = script.streamGenerationFromChunks ?? []
+            const scripted = script.streamGenerationFromEvents ?? []
             if (i >= scripted.length) {
-              const exhausted: Stream.Stream<AudioChunk, AiError.AiError | E, R> = Stream.fail(
-                new AiError.InvalidRequest({
-                  provider: "mock",
-                  raw: `MockMusicGenerator exhausted: ${scripted.length} streamGenerationFrom lists scripted, but call ${i + 1} was made`,
-                }),
-              )
+              const exhausted: Stream.Stream<MusicStreamEvent, AiError.AiError | E, R> =
+                Stream.fail(
+                  new AiError.InvalidRequest({
+                    provider: "mock",
+                    raw: `MockMusicGenerator exhausted: ${scripted.length} streamGenerationFrom lists scripted, but call ${i + 1} was made`,
+                  }),
+                )
               return exhausted
             }
-            // Drain the input fully before emitting scripted audio chunks,
+            // Drain the input fully before emitting scripted events,
             // so consumers can assert on what session messages were pushed.
             return Stream.drain(input).pipe(Stream.concat(Stream.fromIterable(scripted[i]!)))
           }),
@@ -133,7 +140,7 @@ export const layer = (
 }
 
 /**
- * Variant that omits the `MusicInteractiveSession` marker — simulates a
+ * Variant that omits the `MusicInteractiveSession` marker, simulates a
  * provider without bidirectional support (Lyria 3 sync, ElevenLabs,
  * Mureka, MiniMax, Stable Audio, Suno). Calls to
  * `streamGenerationFrom` in code under test should be a compile-time
@@ -166,3 +173,6 @@ export const layerWithoutInteractive = (
     }),
   }
 }
+
+// Re-export the event constructor for test-script ergonomics.
+export { audioEvent }

package/src/testing/MockProvider.ts

@@ -1,6 +1,6 @@
 import { Array as Arr, Duration, Effect, Layer, Match, Option, Ref, Schedule, Stream } from "effect"
 import * as AiError from "../domain/AiError.js"
-import { type Item, isOutputText } from "../domain/Items.js"
+import { type HistoryItem, isOutputText } from "../domain/Items.js"
 import {
   LanguageModel,
   type LanguageModelService,
@@ -18,7 +18,7 @@ export type MockOptions = {
 }
 
 export type Call = {
-  readonly history: ReadonlyArray<Item>
+  readonly history: ReadonlyArray<HistoryItem>
   readonly turn: Turn
 }
 
@@ -36,24 +36,25 @@ export type MockRecorder = {
 // Pure projection: Turn → ReadonlyArray<TurnEvent>
 // ---------------------------------------------------------------------------
 
-const itemToDeltas: (item: Item) => ReadonlyArray<TurnEvent> = Match.type<Item>().pipe(
-  Match.discriminators("type")({
-    message: (m): ReadonlyArray<TurnEvent> =>
-      m.role === "assistant"
-        ? m.content.filter(isOutputText).map((b) => TurnEvent.TextDelta({ text: b.text }))
-        : [],
-    function_call: (fc) => [
-      TurnEvent.ToolCallStart({ call_id: fc.call_id, name: fc.name }),
-      TurnEvent.ToolCallArgsDelta({ call_id: fc.call_id, delta: fc.arguments }),
-    ],
-    function_call_output: () => [],
-    reasoning: (r) =>
-      r.summary !== undefined
-        ? [TurnEvent.ReasoningDelta({ text: r.summary, kind: "summary" as const })]
-        : [],
-  }),
-  Match.exhaustive,
-)
+const itemToDeltas: (item: HistoryItem) => ReadonlyArray<TurnEvent> =
+  Match.type<HistoryItem>().pipe(
+    Match.discriminators("type")({
+      message: (m): ReadonlyArray<TurnEvent> =>
+        m.role === "assistant"
+          ? m.content.filter(isOutputText).map((b) => TurnEvent.TextDelta({ text: b.text }))
+          : [],
+      function_call: (fc) => [
+        TurnEvent.ToolCallStart({ call_id: fc.call_id, name: fc.name }),
+        TurnEvent.ToolCallArgsDelta({ call_id: fc.call_id, delta: fc.arguments }),
+      ],
+      function_call_output: () => [],
+      reasoning: (r) =>
+        r.summary !== undefined
+          ? [TurnEvent.ReasoningDelta({ text: r.summary, kind: "summary" as const })]
+          : [],
+    }),
+    Match.exhaustive,
+  )
 
 const turnToDeltas = (turn: Turn): ReadonlyArray<TurnEvent> => [
   ...turn.items.flatMap(itemToDeltas),