Add native LLM core foundation (#24712)

packages/llm/test/adapter.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect } from "bun:test"
+import { Effect, Schema, Stream } from "effect"
+import { LLM } from "../src"
+import { Route, Endpoint, LLMClient, Protocol, type RouteModelInput, type FramingDef } from "../src/route"
+import { ModelRef } from "../src/schema"
+import { testEffect } from "./lib/effect"
+import { dynamicResponse } from "./lib/http"
+
+const updateModel = (model: ModelRef, patch: Partial<ModelRef.Input>) => ModelRef.update(model, patch)
+
+const Json = Schema.fromJsonString(Schema.Unknown)
+const encodeJson = Schema.encodeSync(Json)
+
+type FakeBody = {
+  readonly body: string
+}
+
+const FakeEvent = Schema.Union([
+  Schema.Struct({ type: Schema.Literal("text"), text: Schema.String }),
+  Schema.Struct({ type: Schema.Literal("finish"), reason: Schema.Literal("stop") }),
+])
+type FakeEvent = Schema.Schema.Type<typeof FakeEvent>
+const decodeFakeEvents = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(FakeEvent)))
+
+const fakeFraming: FramingDef<FakeEvent> = {
+  id: "fake-json-array",
+  frame: (bytes) =>
+    Stream.fromEffect(
+      bytes.pipe(
+        Stream.decodeText(),
+        Stream.runFold(
+          () => "",
+          (text, event) => text + event,
+        ),
+        Effect.flatMap(decodeFakeEvents),
+        Effect.orDie,
+      ),
+    ).pipe(Stream.flatMap(Stream.fromIterable)),
+}
+
+const request = LLM.request({
+  id: "req_1",
+  model: LLM.model({
+    id: "fake-model",
+    provider: "fake-provider",
+    route: "fake",
+    baseURL: "https://fake.local",
+  }),
+  prompt: "hello",
+})
+
+const raiseEvent = (event: FakeEvent): import("../src/schema").LLMEvent =>
+  event.type === "finish" ? { type: "request-finish", reason: event.reason } : { type: "text-delta", text: event.text }
+
+const fakeProtocol = Protocol.make<FakeBody, FakeEvent, FakeEvent, void>({
+  id: "fake",
+  body: {
+    schema: Schema.Struct({
+      body: Schema.String,
+    }),
+    from: (request) =>
+      Effect.succeed({
+        body: [
+          ...request.messages
+            .flatMap((message) => message.content)
+            .filter((part) => part.type === "text")
+            .map((part) => part.text),
+          ...request.tools.map((tool) => `tool:${tool.name}:${tool.description}`),
+        ].join("\n"),
+      }),
+  },
+  stream: {
+    event: FakeEvent,
+    initial: () => undefined,
+    step: (state, event) => Effect.succeed([state, [raiseEvent(event)]] as const),
+  },
+})
+
+const fake = Route.make({
+  id: "fake",
+  protocol: fakeProtocol,
+  endpoint: Endpoint.path("/chat"),
+  framing: fakeFraming,
+})
+
+const gemini = Route.make({
+  id: "gemini-fake",
+  protocol: fakeProtocol,
+  endpoint: Endpoint.path("/chat"),
+  framing: fakeFraming,
+})
+
+const echoLayer = dynamicResponse(({ text, respond }) =>
+  Effect.succeed(
+    respond(
+      encodeJson([
+        { type: "text", text: `echo:${text}` },
+        { type: "finish", reason: "stop" },
+      ]),
+    ),
+  ),
+)
+
+const it = testEffect(echoLayer)
+
+describe("llm route", () => {
+  it.effect("stream and generate use the route pipeline", () =>
+    Effect.gen(function* () {
+      const llm = yield* LLMClient.Service
+      const events = Array.from(yield* llm.stream(request).pipe(Stream.runCollect))
+      const response = yield* llm.generate(request)
+
+      expect(events.map((event) => event.type)).toEqual(["text-delta", "request-finish"])
+      expect(response.events.map((event) => event.type)).toEqual(["text-delta", "request-finish"])
+    }),
+  )
+
+  it.effect("selects routes by request route", () =>
+    Effect.gen(function* () {
+      const llm = yield* LLMClient.Service
+      const prepared = yield* llm.prepare(
+        LLM.updateRequest(request, { model: updateModel(request.model, { route: "gemini-fake" }) }),
+      )
+
+      expect(prepared.route).toBe("gemini-fake")
+    }),
+  )
+
+  it.effect("maps model input before building refs", () =>
+    Effect.gen(function* () {
+      const mapped = Route.model<RouteModelInput & { readonly region?: string }>(
+        fake,
+        { provider: "fake-provider", baseURL: "https://fake.local" },
+        {
+          mapInput: (input) => {
+            const { region, ...rest } = input
+            return { ...rest, native: { region } }
+          },
+        },
+      )
+
+      expect(mapped({ id: "fake-model", region: "us-east-1" }).native).toEqual({ region: "us-east-1" })
+    }),
+  )
+
+  it.effect("rejects duplicate route ids", () =>
+    Effect.gen(function* () {
+      expect(() =>
+        Route.make({
+          id: "fake",
+          protocol: Protocol.make({
+            ...fakeProtocol,
+            body: {
+              ...fakeProtocol.body,
+              from: () => Effect.succeed({ body: "late-default" }),
+            },
+          }),
+          endpoint: Endpoint.path("/chat"),
+          framing: fakeFraming,
+        }),
+      ).toThrow('Duplicate LLM route id "fake"')
+    }),
+  )
+
+  it.effect("rejects missing route", () =>
+    Effect.gen(function* () {
+      const llm = yield* LLMClient.Service
+      const error = yield* llm
+        .prepare(LLM.updateRequest(request, { model: updateModel(request.model, { route: "missing" }) }))
+        .pipe(Effect.flip)
+
+      expect(error.message).toContain("No LLM route")
+    }),
+  )
+})

packages/llm/test/auth-options.types.ts

@@ -0,0 +1,100 @@
+import { Config } from "effect"
+import type { Auth } from "../src/route/auth"
+import type { ModelFactory } from "../src/route/auth-options"
+import { Auth as RuntimeAuth } from "../src/route/auth"
+import * as Azure from "../src/providers/azure"
+import * as OpenAI from "../src/providers/openai"
+
+type BaseOptions = {
+  readonly baseURL?: string
+  readonly headers?: Record<string, string>
+}
+
+type Model = {
+  readonly id: string
+}
+
+declare const auth: Auth
+declare const optionalAuthModel: ModelFactory<BaseOptions, "optional", Model>
+declare const requiredAuthModel: ModelFactory<BaseOptions, "required", Model>
+const configApiKey = Config.redacted("OPENAI_API_KEY")
+
+optionalAuthModel("gpt-4.1-mini")
+optionalAuthModel("gpt-4.1-mini", {})
+optionalAuthModel("gpt-4.1-mini", { apiKey: "sk-test" })
+optionalAuthModel("gpt-4.1-mini", { apiKey: configApiKey })
+optionalAuthModel("gpt-4.1-mini", { auth })
+optionalAuthModel("gpt-4.1-mini", { auth, baseURL: "https://gateway.example.com/v1" })
+optionalAuthModel("gpt-4.1-mini", { apiKey: "sk-test", headers: { "x-source": "test" } })
+
+// @ts-expect-error auth is an override, so apiKey cannot be supplied with it.
+optionalAuthModel("gpt-4.1-mini", { apiKey: "sk-test", auth })
+
+requiredAuthModel("custom-model", { apiKey: "key" })
+requiredAuthModel("custom-model", { apiKey: configApiKey })
+requiredAuthModel("custom-model", { auth })
+requiredAuthModel("custom-model", { auth, headers: { "x-tenant-id": "tenant" } })
+
+// @ts-expect-error providers without config fallback need apiKey or auth.
+requiredAuthModel("custom-model")
+
+// @ts-expect-error providers without config fallback need apiKey or auth.
+requiredAuthModel("custom-model", {})
+
+// @ts-expect-error auth is an override, so apiKey cannot be supplied with it.
+requiredAuthModel("custom-model", { apiKey: "key", auth })
+
+OpenAI.responses("gpt-4.1-mini")
+OpenAI.responses("gpt-4.1-mini", {})
+OpenAI.responses("gpt-4.1-mini", { apiKey: "sk-test" })
+OpenAI.responses("gpt-4.1-mini", { apiKey: configApiKey })
+OpenAI.responses("gpt-4.1-mini", { auth: RuntimeAuth.bearer("oauth-token") })
+OpenAI.responses("gpt-4.1-mini", {
+  auth: RuntimeAuth.headers({ authorization: "Bearer gateway" }),
+  baseURL: "https://gateway.example.com/v1",
+})
+OpenAI.responses("gpt-4.1-mini", {
+  generation: { maxTokens: 100 },
+  providerOptions: { openai: { store: false } },
+})
+
+// @ts-expect-error apiKey only accepts string, Redacted<string>, or Config<string | Redacted<string>>.
+OpenAI.responses("gpt-4.1-mini", { apiKey: 123 })
+
+// @ts-expect-error provider helpers reject unknown top-level options.
+OpenAI.responses("gpt-4.1-mini", { bogus: true })
+
+// @ts-expect-error common generation options remain typed.
+OpenAI.responses("gpt-4.1-mini", { generation: { maxTokens: "many" } })
+
+// @ts-expect-error provider-native options remain typed.
+OpenAI.responses("gpt-4.1-mini", { providerOptions: { openai: { store: "false" } } })
+
+// @ts-expect-error auth is an override, so OpenAI rejects apiKey with auth.
+OpenAI.responses("gpt-4.1-mini", { apiKey: "sk-test", auth: RuntimeAuth.bearer("oauth-token") })
+
+OpenAI.chat("gpt-4.1-mini")
+OpenAI.chat("gpt-4.1-mini", { apiKey: "sk-test" })
+OpenAI.chat("gpt-4.1-mini", { apiKey: configApiKey })
+OpenAI.chat("gpt-4.1-mini", { auth: RuntimeAuth.bearer("oauth-token") })
+
+// @ts-expect-error auth is an override, so OpenAI Chat rejects apiKey with auth.
+OpenAI.chat("gpt-4.1-mini", { apiKey: "sk-test", auth: RuntimeAuth.bearer("oauth-token") })
+
+// @ts-expect-error Azure requires at least one of `resourceName` or `baseURL`.
+Azure.responses("deployment")
+Azure.responses("deployment", { apiKey: "azure-key", resourceName: "resource" })
+Azure.responses("deployment", { apiKey: configApiKey, resourceName: "resource" })
+Azure.responses("deployment", { auth: RuntimeAuth.header("api-key", "azure-key"), resourceName: "resource" })
+
+// @ts-expect-error auth is an override, so Azure rejects apiKey with auth.
+Azure.responses("deployment", { apiKey: "azure-key", auth: RuntimeAuth.header("api-key", "override") })
+
+// @ts-expect-error Azure requires at least one of `resourceName` or `baseURL`.
+Azure.chat("deployment")
+Azure.chat("deployment", { apiKey: "azure-key", resourceName: "resource" })
+Azure.chat("deployment", { apiKey: configApiKey, resourceName: "resource" })
+Azure.chat("deployment", { auth: RuntimeAuth.header("api-key", "azure-key"), resourceName: "resource" })
+
+// @ts-expect-error auth is an override, so Azure Chat rejects apiKey with auth.
+Azure.chat("deployment", { apiKey: "azure-key", auth: RuntimeAuth.header("api-key", "override") })

packages/llm/test/auth.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect } from "bun:test"
+import { ConfigProvider, Effect } from "effect"
+import { Headers } from "effect/unstable/http"
+import { LLM } from "../src"
+import { Auth } from "../src/route/auth"
+import { it } from "./lib/effect"
+
+const request = LLM.request({
+  id: "req_auth",
+  model: LLM.model({ id: "fake-model", provider: "fake", route: "fake", baseURL: "https://fake.local" }),
+  prompt: "hello",
+})
+
+const input = {
+  request,
+  method: "POST" as const,
+  url: "https://example.test/v1/chat",
+  body: "{}",
+  headers: Headers.fromInput({ "x-existing": "yes" }),
+}
+
+const withEnv = (env: Record<string, string>) => Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnv({ env })))
+
+describe("Auth", () => {
+  it.effect("renders a config credential as bearer auth", () =>
+    Effect.gen(function* () {
+      const headers = yield* Auth.config("OPENAI_API_KEY")
+        .bearer()
+        .apply(input)
+        .pipe(withEnv({ OPENAI_API_KEY: "sk-test" }))
+
+      expect(headers.authorization).toBe("Bearer sk-test")
+      expect(headers["x-existing"]).toBe("yes")
+    }),
+  )
+
+  it.effect("falls back between credential sources before rendering", () =>
+    Effect.gen(function* () {
+      const headers = yield* Auth.config("PRIMARY_KEY")
+        .orElse(Auth.value("fallback-key"))
+        .pipe(Auth.header("x-api-key"))
+        .apply(input)
+        .pipe(withEnv({}))
+
+      expect(headers["x-api-key"]).toBe("fallback-key")
+      expect(headers["x-existing"]).toBe("yes")
+    }),
+  )
+
+  it.effect("composes header auth in sequence", () =>
+    Effect.gen(function* () {
+      const headers = yield* Auth.headers({ "x-tenant-id": "tenant-1" })
+        .andThen(Auth.bearer("gateway-token"))
+        .apply(input)
+
+      expect(headers["x-tenant-id"]).toBe("tenant-1")
+      expect(headers.authorization).toBe("Bearer gateway-token")
+      expect(headers["x-existing"]).toBe("yes")
+    }),
+  )
+
+  it.effect("renders a direct secret as a custom header", () =>
+    Effect.gen(function* () {
+      const headers = yield* Auth.header("api-key", "direct-key").apply(input)
+
+      expect(headers["api-key"]).toBe("direct-key")
+      expect(headers["x-existing"]).toBe("yes")
+    }),
+  )
+
+  it.effect("renders bearer auth into a custom header", () =>
+    Effect.gen(function* () {
+      const headers = yield* Auth.bearerHeader("cf-aig-authorization", "gateway-token").apply(input)
+
+      expect(headers["cf-aig-authorization"]).toBe("Bearer gateway-token")
+      expect(headers["x-existing"]).toBe("yes")
+    }),
+  )
+
+  it.effect("falls back between full auth values", () =>
+    Effect.gen(function* () {
+      const headers = yield* Auth.config("OPENAI_API_KEY")
+        .bearer()
+        .orElse(Auth.headers({ authorization: "Bearer supplied" }))
+        .apply(input)
+        .pipe(withEnv({}))
+
+      expect(headers.authorization).toBe("Bearer supplied")
+      expect(headers["x-existing"]).toBe("yes")
+    }),
+  )
+
+  it.effect("can intentionally leave auth untouched", () =>
+    Effect.gen(function* () {
+      const headers = yield* Auth.none.apply(input)
+
+      expect(headers.authorization).toBeUndefined()
+      expect(headers["x-existing"]).toBe("yes")
+    }),
+  )
+})

packages/llm/test/endpoint.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test"
+import { LLM } from "../src"
+import { Endpoint } from "../src/route"
+
+const request = (
+  input: {
+    readonly baseURL: string
+    readonly queryParams?: Record<string, string>
+  },
+) =>
+  LLM.request({
+    model: LLM.model({
+      id: "model-1",
+      provider: "test",
+      route: "test-route",
+      baseURL: input.baseURL,
+      queryParams: input.queryParams,
+    }),
+    prompt: "hello",
+  })
+
+describe("Endpoint", () => {
+  test("appends a static path to the model's baseURL", () => {
+    const url = Endpoint.render(Endpoint.path("/chat"), {
+      request: request({ baseURL: "https://api.example.test/v1/" }),
+      body: {},
+    })
+
+    expect(url.toString()).toBe("https://api.example.test/v1/chat")
+  })
+
+  test("model query params are appended to the rendered URL", () => {
+    const url = Endpoint.render(Endpoint.path("/chat?alt=sse"), {
+      request: request({
+        baseURL: "https://custom.example.test/root/",
+        queryParams: { "api-version": "2026-01-01", alt: "json" },
+      }),
+      body: {},
+    })
+
+    expect(url.toString()).toBe("https://custom.example.test/root/chat?alt=json&api-version=2026-01-01")
+  })
+
+  test("path may be a function of the validated body", () => {
+    const url = Endpoint.render(
+      Endpoint.path<{ readonly modelId: string }>(({ body }) => `/model/${encodeURIComponent(body.modelId)}/converse-stream`),
+      {
+        request: request({ baseURL: "https://bedrock-runtime.us-east-1.amazonaws.com" }),
+        body: { modelId: "us.amazon.nova-micro-v1:0" },
+      },
+    )
+
+    expect(url.toString()).toBe(
+      "https://bedrock-runtime.us-east-1.amazonaws.com/model/us.amazon.nova-micro-v1%3A0/converse-stream",
+    )
+  })
+})

packages/llm/test/executor.test.ts

@@ -0,0 +1,416 @@
+import { describe, expect } from "bun:test"
+import { Effect, Fiber, Layer, Random, Ref } from "effect"
+import * as TestClock from "effect/testing/TestClock"
+import { Headers, HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
+import { LLM, LLMError } from "../src"
+import { LLMClient, RequestExecutor } from "../src/route"
+import * as OpenAIChat from "../src/protocols/openai-chat"
+import { dynamicResponse } from "./lib/http"
+import { deltaChunk } from "./lib/openai-chunks"
+import { sseRaw } from "./lib/sse"
+import { it } from "./lib/effect"
+
+const request = HttpClientRequest.post("https://provider.test/v1/chat?api_key=secret&key=secret&debug=1").pipe(
+  HttpClientRequest.setHeaders(Headers.fromInput({ authorization: "Bearer secret", "x-safe": "visible" })),
+)
+
+const secretRequest = HttpClientRequest.post("https://provider.test/v1/chat?api_key=query-secret-123&debug=1").pipe(
+  HttpClientRequest.setHeaders(Headers.fromInput({ authorization: "Bearer header-secret-456" })),
+)
+
+const responsesLayer = (responses: ReadonlyArray<Response>) =>
+  RequestExecutor.layer.pipe(
+    Layer.provide(
+      Layer.unwrap(
+        Effect.gen(function* () {
+          const cursor = yield* Ref.make(0)
+          return Layer.succeed(
+            HttpClient.HttpClient,
+            HttpClient.make((request) =>
+              Effect.gen(function* () {
+                const index = yield* Ref.getAndUpdate(cursor, (value) => value + 1)
+                return HttpClientResponse.fromWeb(request, responses[index] ?? responses[responses.length - 1])
+              }),
+            ),
+          )
+        }),
+      ),
+    ),
+  )
+
+const countedResponsesLayer = (attempts: Ref.Ref<number>, responses: ReadonlyArray<Response>) =>
+  RequestExecutor.layer.pipe(
+    Layer.provide(
+      Layer.unwrap(
+        Effect.gen(function* () {
+          const cursor = yield* Ref.make(0)
+          return Layer.succeed(
+            HttpClient.HttpClient,
+            HttpClient.make((request) =>
+              Effect.gen(function* () {
+                yield* Ref.update(attempts, (value) => value + 1)
+                const index = yield* Ref.getAndUpdate(cursor, (value) => value + 1)
+                return HttpClientResponse.fromWeb(request, responses[index] ?? responses[responses.length - 1])
+              }),
+            ),
+          )
+        }),
+      ),
+    ),
+  )
+
+const randomMidpoint = {
+  nextDoubleUnsafe: () => 0.5,
+  nextIntUnsafe: () => 0,
+}
+
+const expectLLMError = (error: unknown) => {
+  expect(error).toBeInstanceOf(LLMError)
+  if (!(error instanceof LLMError)) throw new Error("expected LLMError")
+  return error
+}
+
+const errorHttp = (error: LLMError) => ("http" in error.reason ? error.reason.http : undefined)
+
+describe("RequestExecutor", () => {
+  it.effect("returns redacted diagnostics for retryable rate limits", () =>
+    Effect.gen(function* () {
+      const executor = yield* RequestExecutor.Service
+      const error = yield* executor.execute(request).pipe(Effect.flip)
+
+      expectLLMError(error)
+      expect(error).toMatchObject({
+        retryable: true,
+        retryAfterMs: 0,
+        reason: {
+          _tag: "RateLimit",
+          rateLimit: { retryAfterMs: 0 },
+          http: {
+            requestId: "req_123",
+            request: {
+              method: "POST",
+              url: "https://provider.test/v1/chat?api_key=%3Credacted%3E&key=%3Credacted%3E&debug=1",
+              headers: { authorization: "<redacted>", "x-safe": "visible" },
+            },
+            response: {
+              status: 429,
+              headers: {
+                "retry-after-ms": "0",
+                "x-request-id": "req_123",
+                "x-api-key": "<redacted>",
+              },
+            },
+          },
+        },
+      })
+      expect(errorHttp(error)?.body).toBe("rate limited")
+    }).pipe(
+      Effect.provide(
+        responsesLayer([
+          ...Array.from(
+            { length: 3 },
+            () =>
+              new Response("rate limited", {
+                status: 429,
+                headers: { "retry-after-ms": "0", "x-request-id": "req_123", "x-api-key": "secret" },
+              }),
+          ),
+        ]),
+      ),
+    ),
+  )
+
+  it.effect("honors current redacted header names in diagnostics", () =>
+    Effect.gen(function* () {
+      const executor = yield* RequestExecutor.Service
+      const error = yield* executor.execute(request).pipe(Effect.flip)
+
+      expectLLMError(error)
+      expect(errorHttp(error)?.request.headers["x-safe"]).toBe("<redacted>")
+      expect(errorHttp(error)?.response?.headers["x-safe"]).toBe("<redacted>")
+    }).pipe(
+      Effect.provide(responsesLayer([new Response("bad", { status: 400, headers: { "x-safe": "response-secret" } })])),
+      Effect.provideService(Headers.CurrentRedactedNames, ["x-safe"]),
+    ),
+  )
+
+  it.effect("extracts OpenAI-style rate-limit diagnostics", () =>
+    Effect.gen(function* () {
+      const executor = yield* RequestExecutor.Service
+      const error = yield* executor.execute(request).pipe(Effect.flip)
+
+      expectLLMError(error)
+      expect(error.reason).toMatchObject({ _tag: "RateLimit" })
+      expect(error.reason._tag === "RateLimit" ? error.reason.rateLimit : undefined).toEqual({
+        retryAfterMs: 0,
+        limit: { requests: "500", tokens: "30000" },
+        remaining: { requests: "499", tokens: "29900" },
+        reset: { requests: "1s", tokens: "10s" },
+      })
+    }).pipe(
+      Effect.provide(
+        responsesLayer(
+          Array.from(
+            { length: 3 },
+            () =>
+              new Response("rate limited", {
+                status: 429,
+                headers: {
+                  "retry-after-ms": "0",
+                  "x-ratelimit-limit-requests": "500",
+                  "x-ratelimit-limit-tokens": "30000",
+                  "x-ratelimit-remaining-requests": "499",
+                  "x-ratelimit-remaining-tokens": "29900",
+                  "x-ratelimit-reset-requests": "1s",
+                  "x-ratelimit-reset-tokens": "10s",
+                },
+              }),
+          ),
+        ),
+      ),
+    ),
+  )
+
+  it.effect("extracts Anthropic-style rate-limit diagnostics", () =>
+    Effect.gen(function* () {
+      const executor = yield* RequestExecutor.Service
+      const error = yield* executor.execute(request).pipe(Effect.flip)
+
+      expectLLMError(error)
+      expect(error.reason).toMatchObject({ _tag: "ProviderInternal" })
+      expect(errorHttp(error)?.rateLimit).toEqual({
+        retryAfterMs: 0,
+        limit: { requests: "100", "input-tokens": "10000" },
+        remaining: { requests: "12", "input-tokens": "9000" },
+        reset: { requests: "2026-05-06T12:00:00Z", "input-tokens": "2026-05-06T12:00:10Z" },
+      })
+    }).pipe(
+      Effect.provide(
+        responsesLayer(
+          Array.from(
+            { length: 3 },
+            () =>
+              new Response("overloaded", {
+                status: 529,
+                headers: {
+                  "retry-after-ms": "0",
+                  "anthropic-ratelimit-requests-limit": "100",
+                  "anthropic-ratelimit-requests-remaining": "12",
+                  "anthropic-ratelimit-requests-reset": "2026-05-06T12:00:00Z",
+                  "anthropic-ratelimit-input-tokens-limit": "10000",
+                  "anthropic-ratelimit-input-tokens-remaining": "9000",
+                  "anthropic-ratelimit-input-tokens-reset": "2026-05-06T12:00:10Z",
+                },
+              }),
+          ),
+        ),
+      ),
+    ),
+  )
+
+  it.effect("retries retryable status responses before returning the stream", () =>
+    Effect.gen(function* () {
+      const executor = yield* RequestExecutor.Service
+      const response = yield* executor.execute(request)
+
+      expect(response.status).toBe(200)
+      expect(yield* response.text).toBe("ok")
+    }).pipe(
+      Effect.provide(
+        responsesLayer([
+          new Response("busy", { status: 503, headers: { "retry-after-ms": "0" } }),
+          new Response("ok", { status: 200 }),
+        ]),
+      ),
+    ),
+  )
+
+  it.effect("marks 504 and 529 status responses retryable", () =>
+    Effect.gen(function* () {
+      const failWith = (status: number) =>
+        Effect.gen(function* () {
+          const executor = yield* RequestExecutor.Service
+          const error = yield* executor.execute(request).pipe(Effect.flip)
+
+          expectLLMError(error)
+          expect(error.reason).toMatchObject({ _tag: "ProviderInternal", status })
+          expect(error.retryable).toBe(true)
+        }).pipe(
+          Effect.provide(
+            responsesLayer(
+              Array.from(
+                { length: 3 },
+                () =>
+                  new Response("retry", {
+                    status,
+                    headers: { "retry-after-ms": "0" },
+                  }),
+              ),
+            ),
+          ),
+        )
+
+      yield* failWith(504)
+      yield* failWith(529)
+    }),
+  )
+
+  it.effect("does not retry non-retryable status responses and truncates large bodies", () =>
+    Effect.gen(function* () {
+      const executor = yield* RequestExecutor.Service
+      const error = yield* executor.execute(request).pipe(Effect.flip)
+
+      expectLLMError(error)
+      expect(error.reason).toMatchObject({ _tag: "Authentication" })
+      expect(error.retryable).toBe(false)
+      expect(errorHttp(error)?.bodyTruncated).toBe(true)
+      expect(errorHttp(error)?.body).toHaveLength(16_384)
+    }).pipe(
+      Effect.provide(
+        responsesLayer([
+          new Response("x".repeat(20_000), { status: 401 }),
+          new Response("should not retry", { status: 200 }),
+        ]),
+      ),
+    ),
+  )
+
+  it.effect("redacts common secret fields in response bodies", () =>
+    Effect.gen(function* () {
+      const executor = yield* RequestExecutor.Service
+      const error = yield* executor.execute(request).pipe(Effect.flip)
+
+      expectLLMError(error)
+      expect(errorHttp(error)?.body).toContain('"key":"<redacted>"')
+      expect(errorHttp(error)?.body).toContain("api_key=<redacted>")
+      expect(errorHttp(error)?.body).not.toContain("body-secret")
+      expect(errorHttp(error)?.body).not.toContain("query-secret")
+    }).pipe(
+      Effect.provide(
+        responsesLayer([
+          new Response('{"error":{"message":"bad","key":"body-secret","detail":"api_key=query-secret"}}', {
+            status: 400,
+          }),
+        ]),
+      ),
+    ),
+  )
+
+  it.effect("redacts echoed request secret values in response bodies", () =>
+    Effect.gen(function* () {
+      const executor = yield* RequestExecutor.Service
+      const error = yield* executor.execute(secretRequest).pipe(Effect.flip)
+
+      expectLLMError(error)
+      expect(errorHttp(error)?.body).toContain("provider echoed <redacted>")
+      expect(errorHttp(error)?.body).toContain("authorization <redacted>")
+      expect(errorHttp(error)?.body).not.toContain("query-secret-123")
+      expect(errorHttp(error)?.body).not.toContain("header-secret-456")
+    }).pipe(
+      Effect.provide(
+        responsesLayer([
+          new Response("provider echoed query-secret-123 and authorization header-secret-456", { status: 400 }),
+        ]),
+      ),
+    ),
+  )
+
+  it.effect("honors Retry-After delta seconds before retrying", () =>
+    Effect.gen(function* () {
+      const attempts = yield* Ref.make(0)
+      return yield* Effect.gen(function* () {
+        const executor = yield* RequestExecutor.Service
+        const fiber = yield* executor.execute(request).pipe(Effect.forkChild)
+
+        yield* Effect.yieldNow
+        expect(yield* Ref.get(attempts)).toBe(1)
+
+        yield* TestClock.adjust(1_999)
+        yield* Effect.yieldNow
+        expect(yield* Ref.get(attempts)).toBe(1)
+
+        yield* TestClock.adjust(1)
+        const response = yield* Fiber.join(fiber)
+
+        expect(response.status).toBe(200)
+        expect(yield* Ref.get(attempts)).toBe(2)
+      }).pipe(
+        Effect.provide(
+          countedResponsesLayer(attempts, [
+            new Response("busy", { status: 503, headers: { "retry-after": "2" } }),
+            new Response("ok", { status: 200 }),
+          ]),
+        ),
+      )
+    }),
+  )
+
+  it.effect("uses exponential jittered delay when retry-after is absent", () =>
+    Effect.gen(function* () {
+      const attempts = yield* Ref.make(0)
+      return yield* Effect.gen(function* () {
+        const executor = yield* RequestExecutor.Service
+        const fiber = yield* executor.execute(request).pipe(Effect.flip, Effect.forkChild)
+
+        yield* Effect.yieldNow
+        expect(yield* Ref.get(attempts)).toBe(1)
+
+        yield* TestClock.adjust(499)
+        yield* Effect.yieldNow
+        expect(yield* Ref.get(attempts)).toBe(1)
+
+        yield* TestClock.adjust(1)
+        yield* Effect.yieldNow
+        expect(yield* Ref.get(attempts)).toBe(2)
+
+        yield* TestClock.adjust(999)
+        yield* Effect.yieldNow
+        expect(yield* Ref.get(attempts)).toBe(2)
+
+        yield* TestClock.adjust(1)
+        const error = yield* Fiber.join(fiber)
+
+        expectLLMError(error)
+        expect(error.reason).toMatchObject({ _tag: "ProviderInternal" })
+        expect(yield* Ref.get(attempts)).toBe(3)
+      }).pipe(
+        Effect.provide(
+          countedResponsesLayer(attempts, [
+            new Response("busy", { status: 503 }),
+            new Response("still busy", { status: 503 }),
+            new Response("done retrying", { status: 503 }),
+          ]),
+        ),
+      )
+    }).pipe(Effect.provideService(Random.Random, randomMidpoint)),
+  )
+
+  it.effect("does not retry after a successful response reaches stream parsing", () =>
+    Effect.gen(function* () {
+      const attempts = yield* Ref.make(0)
+      const model = OpenAIChat.model({ id: "gpt-4o-mini", baseURL: "https://api.openai.test/v1" })
+      const error = yield* LLMClient.generate(LLM.request({ model, prompt: "Say hello." })).pipe(
+        Effect.provide(
+          dynamicResponse((input) =>
+            Ref.update(attempts, (value) => value + 1).pipe(
+              Effect.as(
+                input.respond(
+                  sseRaw(
+                    `data: ${JSON.stringify(deltaChunk({ role: "assistant", content: "Hello" }))}`,
+                    "data: not-json",
+                  ),
+                  { headers: { "content-type": "text/event-stream" } },
+                ),
+              ),
+            ),
+          ),
+        ),
+        Effect.flip,
+      )
+
+      expectLLMError(error)
+      expect(error.reason).toMatchObject({ _tag: "InvalidProviderOutput" })
+      expect(yield* Ref.get(attempts)).toBe(1)
+    }),
+  )
+})

packages/llm/test/exports.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test"
+import { LLM, LLMClient, Provider } from "@opencode-ai/llm"
+import { Route, Protocol } from "@opencode-ai/llm/route"
+import { Provider as ProviderSubpath } from "@opencode-ai/llm/provider"
+import { Cloudflare, OpenAI, OpenAICompatible, OpenRouter, XAI } from "@opencode-ai/llm/providers"
+import * as GitHubCopilot from "@opencode-ai/llm/providers/github-copilot"
+import { OpenAIChat, OpenAICompatibleChat, OpenAIResponses } from "@opencode-ai/llm/protocols"
+import * as AnthropicMessages from "@opencode-ai/llm/protocols/anthropic-messages"
+
+describe("public exports", () => {
+  test("root exposes app-facing runtime APIs", () => {
+    expect(LLM.request).toBeFunction()
+    expect(LLMClient.Service).toBeFunction()
+    expect(LLMClient.layer).toBeDefined()
+    expect(Provider.make).toBeFunction()
+    expect(ProviderSubpath.make).toBe(Provider.make)
+  })
+
+  test("route barrel exposes route-authoring APIs", () => {
+    expect(Route.make).toBeFunction()
+    expect(Protocol.make).toBeFunction()
+  })
+
+  test("provider barrels expose user-facing facades", () => {
+    expect(OpenAI.model).toBeFunction()
+    expect(OpenAI.provider.model).toBe(OpenAI.model)
+    expect(OpenAI.apis.responses).toBe(OpenAI.responses)
+    expect(OpenAI.apis.responsesWebSocket).toBe(OpenAI.responsesWebSocket)
+    expect(OpenAICompatible.deepseek.model).toBeFunction()
+    expect(Cloudflare.model).toBeFunction()
+    expect(Cloudflare.provider.model).toBe(Cloudflare.model)
+    expect(Cloudflare.aiGateway).toBeFunction()
+    expect(Cloudflare.workersAI).toBeFunction()
+    expect(OpenRouter.model).toBeFunction()
+    expect(OpenRouter.provider.model).toBe(OpenRouter.model)
+    expect(XAI.model).toBeFunction()
+    expect(XAI.provider.model).toBe(XAI.model)
+    expect(XAI.apis.responses).toBe(XAI.responses)
+    expect(XAI.apis.chat).toBe(XAI.chat)
+    expect(XAI.responses("grok-4.3", { apiKey: "fixture" })).toMatchObject({
+      route: "openai-responses",
+    })
+    expect(XAI.chat("grok-4.3", { apiKey: "fixture" })).toMatchObject({
+      route: "openai-compatible-chat",
+    })
+    expect(GitHubCopilot.model).toBeFunction()
+  })
+
+  test("protocol barrels expose supported low-level routes", () => {
+    expect(OpenAIChat.route.id).toBe("openai-chat")
+    expect(OpenAICompatibleChat.route.id).toBe("openai-compatible-chat")
+    expect(OpenAIResponses.route.id).toBe("openai-responses")
+    expect(OpenAIResponses.webSocketRoute.id).toBe("openai-responses-websocket")
+    expect(AnthropicMessages.route.id).toBe("anthropic-messages")
+  })
+})

packages/llm/test/fixtures/recordings/anthropic-messages/accepts-malformed-assistant-tool-order-with-default-patch.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "anthropic-messages/accepts-malformed-assistant-tool-order-with-default-patch",
+    "recordedAt": "2026-05-05T20:09:16.245Z",
+    "tags": ["prefix:anthropic-messages", "provider:anthropic", "protocol:anthropic-messages", "tool"]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.anthropic.com/v1/messages",
+        "headers": {
+          "anthropic-version": "2023-06-01",
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"claude-haiku-4-5-20251001\",\"messages\":[{\"role\":\"assistant\",\"content\":[{\"type\":\"text\",\"text\":\"I will check the weather.\"}]},{\"role\":\"assistant\",\"content\":[{\"type\":\"tool_use\",\"id\":\"call_1\",\"name\":\"get_weather\",\"input\":{\"city\":\"Paris\"}}]},{\"role\":\"user\",\"content\":[{\"type\":\"tool_result\",\"tool_use_id\":\"call_1\",\"content\":\"{\\\"temperature\\\":\\\"72F\\\"}\"}]},{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"Use that result to answer briefly.\",\"cache_control\":{\"type\":\"ephemeral\"}}]}],\"tools\":[{\"name\":\"get_weather\",\"description\":\"Get weather\",\"input_schema\":{\"type\":\"object\",\"properties\":{}}}],\"stream\":true,\"max_tokens\":4096}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream; charset=utf-8"
+        },
+        "body": "event: message_start\ndata: {\"type\":\"message_start\",\"message\":{\"model\":\"claude-haiku-4-5-20251001\",\"id\":\"msg_01SikJVFaMR1XLMtavUhvuog\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[],\"stop_reason\":null,\"stop_sequence\":null,\"stop_details\":null,\"usage\":{\"input_tokens\":638,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":0,\"cache_creation\":{\"ephemeral_5m_input_tokens\":0,\"ephemeral_1h_input_tokens\":0},\"output_tokens\":1,\"service_tier\":\"standard\",\"inference_geo\":\"not_available\"}}               }\n\nevent: content_block_start\ndata: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"text\",\"text\":\"\"}          }\n\nevent: ping\ndata: {\"type\": \"ping\"}\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"The\"}     }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\" weather in Paris is currently 72°F.\"}        }\n\nevent: content_block_stop\ndata: {\"type\":\"content_block_stop\",\"index\":0}\n\nevent: message_delta\ndata: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"end_turn\",\"stop_sequence\":null,\"stop_details\":null},\"usage\":{\"input_tokens\":638,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":0,\"output_tokens\":14}              }\n\nevent: message_stop\ndata: {\"type\":\"message_stop\"             }\n\n"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/anthropic-messages/claude-opus-4-7-drives-a-tool-loop.json

@@ -0,0 +1,56 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "anthropic-messages/claude-opus-4-7-drives-a-tool-loop",
+    "recordedAt": "2026-05-03T19:59:44.186Z",
+    "tags": [
+      "prefix:anthropic-messages",
+      "provider:anthropic",
+      "protocol:anthropic-messages",
+      "tool",
+      "tool-loop",
+      "golden",
+      "flagship"
+    ]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.anthropic.com/v1/messages",
+        "headers": {
+          "anthropic-version": "2023-06-01",
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"claude-opus-4-7\",\"system\":[{\"type\":\"text\",\"text\":\"Use the get_weather tool, then answer in one short sentence.\"}],\"messages\":[{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"What is the weather in Paris?\"}]}],\"tools\":[{\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"input_schema\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false}}],\"stream\":true,\"max_tokens\":80}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream; charset=utf-8"
+        },
+        "body": "event: message_start\ndata: {\"type\":\"message_start\",\"message\":{\"model\":\"claude-opus-4-7\",\"id\":\"msg_01DgAEgLgB1ZhavZon4qGE1t\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[],\"stop_reason\":null,\"stop_sequence\":null,\"stop_details\":null,\"usage\":{\"input_tokens\":798,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":0,\"cache_creation\":{\"ephemeral_5m_input_tokens\":0,\"ephemeral_1h_input_tokens\":0},\"output_tokens\":0,\"service_tier\":\"standard\",\"inference_geo\":\"global\"}}    }\n\nevent: content_block_start\ndata: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"tool_use\",\"id\":\"toolu_01M8nJQQMxqpv1VaPYuJKT4j\",\"name\":\"get_weather\",\"input\":{},\"caller\":{\"type\":\"direct\"}}              }\n\nevent: ping\ndata: {\"type\": \"ping\"}\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"\"} }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"{\\\"city\\\": \"}              }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"\\\"Pa\"}    }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"ris\\\"}\"}  }\n\nevent: content_block_stop\ndata: {\"type\":\"content_block_stop\",\"index\":0           }\n\nevent: message_delta\ndata: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"tool_use\",\"stop_sequence\":null,\"stop_details\":null},\"usage\":{\"input_tokens\":798,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":0,\"output_tokens\":66}             }\n\nevent: message_stop\ndata: {\"type\":\"message_stop\"            }\n\n"
+      }
+    },
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.anthropic.com/v1/messages",
+        "headers": {
+          "anthropic-version": "2023-06-01",
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"claude-opus-4-7\",\"system\":[{\"type\":\"text\",\"text\":\"Use the get_weather tool, then answer in one short sentence.\"}],\"messages\":[{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"What is the weather in Paris?\"}]},{\"role\":\"assistant\",\"content\":[{\"type\":\"tool_use\",\"id\":\"toolu_01M8nJQQMxqpv1VaPYuJKT4j\",\"name\":\"get_weather\",\"input\":{\"city\":\"Paris\"}}]},{\"role\":\"user\",\"content\":[{\"type\":\"tool_result\",\"tool_use_id\":\"toolu_01M8nJQQMxqpv1VaPYuJKT4j\",\"content\":\"{\\\"temperature\\\":22,\\\"condition\\\":\\\"sunny\\\"}\"}]}],\"tools\":[{\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"input_schema\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false}}],\"stream\":true,\"max_tokens\":80}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream; charset=utf-8"
+        },
+        "body": "event: message_start\ndata: {\"type\":\"message_start\",\"message\":{\"model\":\"claude-opus-4-7\",\"id\":\"msg_011KJqj32QjkrUAiBFxhmEoG\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[],\"stop_reason\":null,\"stop_sequence\":null,\"stop_details\":null,\"usage\":{\"input_tokens\":895,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":0,\"cache_creation\":{\"ephemeral_5m_input_tokens\":0,\"ephemeral_1h_input_tokens\":0},\"output_tokens\":5,\"service_tier\":\"standard\",\"inference_geo\":\"global\"}}       }\n\nevent: content_block_start\ndata: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"text\",\"text\":\"\"}            }\n\nevent: ping\ndata: {\"type\": \"ping\"}\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"Paris is curr\"}   }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"ently sunny at 22°C.\"}           }\n\nevent: content_block_stop\ndata: {\"type\":\"content_block_stop\",\"index\":0        }\n\nevent: message_delta\ndata: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"end_turn\",\"stop_sequence\":null,\"stop_details\":null},\"usage\":{\"input_tokens\":895,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":0,\"output_tokens\":19}}\n\nevent: message_stop\ndata: {\"type\":\"message_stop\"}\n\n"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/anthropic-messages/rejects-malformed-assistant-tool-order-without-patch.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "anthropic-messages/rejects-malformed-assistant-tool-order-without-patch",
+    "recordedAt": "2026-05-05T20:08:42.597Z",
+    "tags": ["prefix:anthropic-messages", "provider:anthropic", "protocol:anthropic-messages", "tool", "sad-path"]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.anthropic.com/v1/messages",
+        "headers": {
+          "anthropic-version": "2023-06-01",
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"claude-haiku-4-5-20251001\",\"messages\":[{\"role\":\"assistant\",\"content\":[{\"type\":\"tool_use\",\"id\":\"call_1\",\"name\":\"get_weather\",\"input\":{\"city\":\"Paris\"}},{\"type\":\"text\",\"text\":\"I will check the weather.\"}]},{\"role\":\"user\",\"content\":[{\"type\":\"tool_result\",\"tool_use_id\":\"call_1\",\"content\":\"{\\\"temperature\\\":\\\"72F\\\"}\"}]},{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"Use that result to answer briefly.\"}]}],\"tools\":[{\"name\":\"get_weather\",\"description\":\"Get weather\",\"input_schema\":{\"type\":\"object\",\"properties\":{}}}],\"stream\":true,\"max_tokens\":4096}"
+      },
+      "response": {
+        "status": 400,
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"type\":\"error\",\"error\":{\"type\":\"invalid_request_error\",\"message\":\"messages.1: `tool_use` ids were found without `tool_result` blocks immediately after: call_1. Each `tool_use` block must have a corresponding `tool_result` block in the next message.\"},\"request_id\":\"req_011Cak2XdJgnzxKCY2BC2Beh\"}"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/anthropic-messages/streams-text.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "anthropic-messages/streams-text",
+    "recordedAt": "2026-04-28T21:18:45.535Z",
+    "tags": ["prefix:anthropic-messages", "provider:anthropic", "protocol:anthropic-messages"]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.anthropic.com/v1/messages",
+        "headers": {
+          "anthropic-version": "2023-06-01",
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"claude-haiku-4-5-20251001\",\"system\":[{\"type\":\"text\",\"text\":\"You are concise.\"}],\"messages\":[{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"Reply with exactly: Hello!\"}]}],\"stream\":true,\"max_tokens\":20,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream; charset=utf-8"
+        },
+        "body": "event: message_start\ndata: {\"type\":\"message_start\",\"message\":{\"model\":\"claude-haiku-4-5-20251001\",\"id\":\"msg_01UodR8c3ezAK8rAfi8HAs8g\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[],\"stop_reason\":null,\"stop_sequence\":null,\"stop_details\":null,\"usage\":{\"input_tokens\":18,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":0,\"cache_creation\":{\"ephemeral_5m_input_tokens\":0,\"ephemeral_1h_input_tokens\":0},\"output_tokens\":2,\"service_tier\":\"standard\",\"inference_geo\":\"not_available\"}}          }\n\nevent: content_block_start\ndata: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"text\",\"text\":\"\"}    }\n\nevent: ping\ndata: {\"type\": \"ping\"}\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"Hello!\"}    }\n\nevent: content_block_stop\ndata: {\"type\":\"content_block_stop\",\"index\":0   }\n\nevent: message_delta\ndata: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"end_turn\",\"stop_sequence\":null,\"stop_details\":null},\"usage\":{\"input_tokens\":18,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":0,\"output_tokens\":5}             }\n\nevent: message_stop\ndata: {\"type\":\"message_stop\"         }\n\n"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/anthropic-messages/streams-tool-call.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "anthropic-messages/streams-tool-call",
+    "recordedAt": "2026-04-28T21:18:46.878Z",
+    "tags": ["prefix:anthropic-messages", "provider:anthropic", "protocol:anthropic-messages", "tool"]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.anthropic.com/v1/messages",
+        "headers": {
+          "anthropic-version": "2023-06-01",
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"claude-haiku-4-5-20251001\",\"system\":[{\"type\":\"text\",\"text\":\"Call tools exactly as requested.\"}],\"messages\":[{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"Call get_weather with city exactly Paris.\"}]}],\"tools\":[{\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"input_schema\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false}}],\"tool_choice\":{\"type\":\"tool\",\"name\":\"get_weather\"},\"stream\":true,\"max_tokens\":80,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream; charset=utf-8"
+        },
+        "body": "event: message_start\ndata: {\"type\":\"message_start\",\"message\":{\"model\":\"claude-haiku-4-5-20251001\",\"id\":\"msg_01RYgU7NUPMK4B9v8S7gVpCS\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[],\"stop_reason\":null,\"stop_sequence\":null,\"stop_details\":null,\"usage\":{\"input_tokens\":677,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":0,\"cache_creation\":{\"ephemeral_5m_input_tokens\":0,\"ephemeral_1h_input_tokens\":0},\"output_tokens\":16,\"service_tier\":\"standard\",\"inference_geo\":\"not_available\"}}             }\n\nevent: content_block_start\ndata: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"tool_use\",\"id\":\"toolu_012rmAruviySvUXSjgCPWVRu\",\"name\":\"get_weather\",\"input\":{},\"caller\":{\"type\":\"direct\"}}      }\n\nevent: ping\ndata: {\"type\": \"ping\"}\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"\"}             }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\"{\\\"city\\\":\"}    }\n\nevent: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"input_json_delta\",\"partial_json\":\" \\\"Paris\\\"}\"}     }\n\nevent: content_block_stop\ndata: {\"type\":\"content_block_stop\",\"index\":0     }\n\nevent: message_delta\ndata: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"tool_use\",\"stop_sequence\":null,\"stop_details\":null},\"usage\":{\"input_tokens\":677,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":0,\"output_tokens\":33}              }\n\nevent: message_stop\ndata: {\"type\":\"message_stop\"     }\n\n"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/bedrock-converse/streams-a-tool-call.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "bedrock-converse/streams-a-tool-call",
+    "recordedAt": "2026-04-28T21:18:46.929Z",
+    "tags": ["prefix:bedrock-converse", "provider:amazon-bedrock", "protocol:bedrock-converse", "tool"]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://bedrock-runtime.us-east-1.amazonaws.com/model/us.amazon.nova-micro-v1%3A0/converse-stream",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"modelId\":\"us.amazon.nova-micro-v1:0\",\"messages\":[{\"role\":\"user\",\"content\":[{\"text\":\"Call get_weather with city exactly Paris.\"}]}],\"system\":[{\"text\":\"Call tools exactly as requested.\"}],\"inferenceConfig\":{\"maxTokens\":80,\"temperature\":0},\"toolConfig\":{\"tools\":[{\"toolSpec\":{\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"inputSchema\":{\"json\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false}}}}],\"toolChoice\":{\"tool\":{\"name\":\"get_weather\"}}}}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "application/vnd.amazon.eventstream"
+        },
+        "body": "AAAAuQAAAFL9kIXUCzpldmVudC10eXBlBwAMbWVzc2FnZVN0YXJ0DTpjb250ZW50LXR5cGUHABBhcHBsaWNhdGlvbi9qc29uDTptZXNzYWdlLXR5cGUHAAVldmVudHsicCI6ImFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVowMTIzNDU2NyIsInJvbGUiOiJhc3Npc3RhbnQifWf51EkAAAEMAAAAV56BJZoLOmV2ZW50LXR5cGUHABFjb250ZW50QmxvY2tTdGFydA06Y29udGVudC10eXBlBwAQYXBwbGljYXRpb24vanNvbg06bWVzc2FnZS10eXBlBwAFZXZlbnR7ImNvbnRlbnRCbG9ja0luZGV4IjowLCJwIjoiYWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXpBQkNERUZHSElKS0xNTk9QUVJTVFUiLCJzdGFydCI6eyJ0b29sVXNlIjp7Im5hbWUiOiJnZXRfd2VhdGhlciIsInRvb2xVc2VJZCI6InRvb2x1c2VfNmExcFB2bmM5OUdMS08zS0drVUEyTiJ9fX2LR7PFAAAA4gAAAFfCOY+BCzpldmVudC10eXBlBwARY29udGVudEJsb2NrRGVsdGENOmNvbnRlbnQtdHlwZQcAEGFwcGxpY2F0aW9uL2pzb24NOm1lc3NhZ2UtdHlwZQcABWV2ZW50eyJjb250ZW50QmxvY2tJbmRleCI6MCwiZGVsdGEiOnsidG9vbFVzZSI6eyJpbnB1dCI6IntcImNpdHlcIjpcIlBhcmlzXCJ9In19LCJwIjoiYWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXpBQkNERUZHSElKS0xNTiJ9RkW+2gAAAIcAAABW5OxHKgs6ZXZlbnQtdHlwZQcAEGNvbnRlbnRCbG9ja1N0b3ANOmNvbnRlbnQtdHlwZQcAEGFwcGxpY2F0aW9uL2pzb24NOm1lc3NhZ2UtdHlwZQcABWV2ZW50eyJjb250ZW50QmxvY2tJbmRleCI6MCwicCI6ImFiYyJ9y6nrtwAAAK4AAABRtlmf/As6ZXZlbnQtdHlwZQcAC21lc3NhZ2VTdG9wDTpjb250ZW50LXR5cGUHABBhcHBsaWNhdGlvbi9qc29uDTptZXNzYWdlLXR5cGUHAAVldmVudHsicCI6ImFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6QUJDREVGR0hJSktMTU5PUFFSUyIsInN0b3BSZWFzb24iOiJ0b29sX3VzZSJ9MTlQawAAAOIAAABOplInQQs6ZXZlbnQtdHlwZQcACG1ldGFkYXRhDTpjb250ZW50LXR5cGUHABBhcHBsaWNhdGlvbi9qc29uDTptZXNzYWdlLXR5cGUHAAVldmVudHsibWV0cmljcyI6eyJsYXRlbmN5TXMiOjM1NX0sInAiOiJhYmNkZWZnaGlqayIsInVzYWdlIjp7ImlucHV0VG9rZW5zIjo0MTksIm91dHB1dFRva2VucyI6MTYsInNlcnZlclRvb2xVc2FnZSI6e30sInRvdGFsVG9rZW5zIjo0MzV9fU1tVJc=",
+        "bodyEncoding": "base64"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/bedrock-converse/streams-text.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "bedrock-converse/streams-text",
+    "recordedAt": "2026-04-28T21:18:46.553Z",
+    "tags": ["prefix:bedrock-converse", "provider:amazon-bedrock", "protocol:bedrock-converse"]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://bedrock-runtime.us-east-1.amazonaws.com/model/us.amazon.nova-micro-v1%3A0/converse-stream",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"modelId\":\"us.amazon.nova-micro-v1:0\",\"messages\":[{\"role\":\"user\",\"content\":[{\"text\":\"Say hello.\"}]}],\"system\":[{\"text\":\"Reply with the single word 'Hello'.\"}],\"inferenceConfig\":{\"maxTokens\":16,\"temperature\":0}}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "application/vnd.amazon.eventstream"
+        },
+        "body": "AAAAmQAAAFI8UarQCzpldmVudC10eXBlBwAMbWVzc2FnZVN0YXJ0DTpjb250ZW50LXR5cGUHABBhcHBsaWNhdGlvbi9qc29uDTptZXNzYWdlLXR5cGUHAAVldmVudHsicCI6ImFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6QUIiLCJyb2xlIjoiYXNzaXN0YW50In3SL1jNAAAAvQAAAFd4etebCzpldmVudC10eXBlBwARY29udGVudEJsb2NrRGVsdGENOmNvbnRlbnQtdHlwZQcAEGFwcGxpY2F0aW9uL2pzb24NOm1lc3NhZ2UtdHlwZQcABWV2ZW50eyJjb250ZW50QmxvY2tJbmRleCI6MCwiZGVsdGEiOnsidGV4dCI6IkhlbGxvIn0sInAiOiJhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ekFCQ0RFIn2B0NR6AAAAxgAAAFf2eAZFCzpldmVudC10eXBlBwARY29udGVudEJsb2NrRGVsdGENOmNvbnRlbnQtdHlwZQcAEGFwcGxpY2F0aW9uL2pzb24NOm1lc3NhZ2UtdHlwZQcABWV2ZW50eyJjb250ZW50QmxvY2tJbmRleCI6MCwiZGVsdGEiOnsidGV4dCI6IiJ9LCJwIjoiYWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXpBQkNERUZHSElKS0xNTk9QUVJTIn3XaHMvAAAAhwAAAFbk7EcqCzpldmVudC10eXBlBwAQY29udGVudEJsb2NrU3RvcA06Y29udGVudC10eXBlBwAQYXBwbGljYXRpb24vanNvbg06bWVzc2FnZS10eXBlBwAFZXZlbnR7ImNvbnRlbnRCbG9ja0luZGV4IjowLCJwIjoiYWJjIn3Lqeu3AAAAjwAAAFFK+JlICzpldmVudC10eXBlBwALbWVzc2FnZVN0b3ANOmNvbnRlbnQtdHlwZQcAEGFwcGxpY2F0aW9uL2pzb24NOm1lc3NhZ2UtdHlwZQcABWV2ZW50eyJwIjoiYWJjZGVmZ2hpamtsbW4iLCJzdG9wUmVhc29uIjoiZW5kX3R1cm4ifZ+RQqEAAAECAAAATkXaMzsLOmV2ZW50LXR5cGUHAAhtZXRhZGF0YQ06Y29udGVudC10eXBlBwAQYXBwbGljYXRpb24vanNvbg06bWVzc2FnZS10eXBlBwAFZXZlbnR7Im1ldHJpY3MiOnsibGF0ZW5jeU1zIjozMDZ9LCJwIjoiYWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXpBQkNERUZHSElKS0xNTk9QUVJTVCIsInVzYWdlIjp7ImlucHV0VG9rZW5zIjoxMiwib3V0cHV0VG9rZW5zIjoyLCJzZXJ2ZXJUb29sVXNhZ2UiOnt9LCJ0b3RhbFRva2VucyI6MTR9fSnnkUk=",
+        "bodyEncoding": "base64"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/cloudflare-ai-gateway/cloudflare-ai-gateway-workers-ai-llama-3-1-8b-text.json

@@ -0,0 +1,37 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "cloudflare-ai-gateway/cloudflare-ai-gateway-workers-ai-llama-3-1-8b-text",
+    "recordedAt": "2026-05-08T15:55:48.952Z",
+    "provider": "cloudflare-ai-gateway",
+    "route": "cloudflare-ai-gateway",
+    "transport": "http",
+    "model": "workers-ai/@cf/meta/llama-3.1-8b-instruct",
+    "tags": [
+      "prefix:cloudflare-ai-gateway",
+      "provider:cloudflare-ai-gateway",
+      "text",
+      "golden"
+    ]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://gateway.ai.cloudflare.com/v1/{account}/{gateway}/compat/chat/completions",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"workers-ai/@cf/meta/llama-3.1-8b-instruct\",\"messages\":[{\"role\":\"system\",\"content\":\"You are concise.\"},{\"role\":\"user\",\"content\":\"Reply exactly with: Hello!\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true},\"max_tokens\":40,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream"
+        },
+        "body": "data: {\"id\":\"id-1778255748911\",\"created\":1778255748,\"model\":\"@cf/meta/llama-3.1-8b-instruct\",\"object\":\"chat.completion.chunk\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"Hello\"}}]}\n\ndata: {\"id\":\"id-1778255748911\",\"created\":1778255748,\"model\":\"@cf/meta/llama-3.1-8b-instruct\",\"object\":\"chat.completion.chunk\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"!\"}}]}\n\ndata: {\"id\":\"id-1778255748911\",\"object\":\"chat.completion.chunk\",\"created\":1778255748,\"model\":\"@cf/meta/llama-3.1-8b-instruct\",\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":\"stop\"}],\"usage\":{\"prompt_tokens\":45,\"completion_tokens\":2,\"total_tokens\":47}}\n\ndata: {\"id\":\"id-1778255748911\",\"object\":\"chat.completion.chunk\",\"created\":1778255748,\"model\":\"@cf/meta/llama-3.1-8b-instruct\",\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":\"stop\"}],\"usage\":{\"prompt_tokens\":0,\"completion_tokens\":0,\"total_tokens\":0,\"prompt_tokens_details\":{\"cached_tokens\":0}}}\n\ndata: [DONE]\n\n"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/cloudflare-workers-ai/cloudflare-workers-ai-llama-3-1-8b-text.json

@@ -0,0 +1,37 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "cloudflare-workers-ai/cloudflare-workers-ai-llama-3-1-8b-text",
+    "recordedAt": "2026-05-08T15:56:18.284Z",
+    "provider": "cloudflare-workers-ai",
+    "route": "cloudflare-workers-ai",
+    "transport": "http",
+    "model": "@cf/meta/llama-3.1-8b-instruct",
+    "tags": [
+      "prefix:cloudflare-workers-ai",
+      "provider:cloudflare-workers-ai",
+      "text",
+      "golden"
+    ]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.cloudflare.com/client/v4/accounts/{account}/ai/v1/chat/completions",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"@cf/meta/llama-3.1-8b-instruct\",\"messages\":[{\"role\":\"system\",\"content\":\"You are concise.\"},{\"role\":\"user\",\"content\":\"Reply exactly with: Hello!\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true},\"max_tokens\":40,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream"
+        },
+        "body": "data: {\"id\":\"id-1778255778230\",\"created\":1778255778,\"model\":\"@cf/meta/llama-3.1-8b-instruct\",\"object\":\"chat.completion.chunk\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"Hello\"}}]}\n\ndata: {\"id\":\"id-1778255778230\",\"created\":1778255778,\"model\":\"@cf/meta/llama-3.1-8b-instruct\",\"object\":\"chat.completion.chunk\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"!\"}}]}\n\ndata: {\"id\":\"id-1778255778230\",\"object\":\"chat.completion.chunk\",\"created\":1778255778,\"model\":\"@cf/meta/llama-3.1-8b-instruct\",\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":\"stop\"}],\"usage\":{\"prompt_tokens\":45,\"completion_tokens\":2,\"total_tokens\":47}}\n\ndata: {\"id\":\"id-1778255778230\",\"object\":\"chat.completion.chunk\",\"created\":1778255778,\"model\":\"@cf/meta/llama-3.1-8b-instruct\",\"choices\":[{\"index\":0,\"delta\":{},\"finish_reason\":\"stop\"}],\"usage\":{\"prompt_tokens\":0,\"completion_tokens\":0,\"total_tokens\":0,\"prompt_tokens_details\":{\"cached_tokens\":0}}}\n\ndata: [DONE]\n\n"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/gemini/streams-text.json

@@ -0,0 +1,28 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "gemini/streams-text",
+    "recordedAt": "2026-04-28T21:18:47.483Z",
+    "tags": ["prefix:gemini", "provider:google", "protocol:gemini"]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"contents\":[{\"role\":\"user\",\"parts\":[{\"text\":\"Reply with exactly: Hello!\"}]}],\"systemInstruction\":{\"parts\":[{\"text\":\"You are concise.\"}]},\"generationConfig\":{\"maxOutputTokens\":80,\"temperature\":0}}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream"
+        },
+        "body": "data: {\"candidates\": [{\"content\": {\"parts\": [{\"text\": \"Hello!\"}],\"role\": \"model\"},\"finishReason\": \"STOP\",\"index\": 0}],\"usageMetadata\": {\"promptTokenCount\": 11,\"candidatesTokenCount\": 2,\"totalTokenCount\": 29,\"promptTokensDetails\": [{\"modality\": \"TEXT\",\"tokenCount\": 11}],\"thoughtsTokenCount\": 16},\"modelVersion\": \"gemini-2.5-flash\",\"responseId\": \"NyTxaczMAZ-b_uMP6u--iQg\"}\r\n\r\n"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/gemini/streams-tool-call.json

@@ -0,0 +1,28 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "gemini/streams-tool-call",
+    "recordedAt": "2026-04-28T21:18:48.285Z",
+    "tags": ["prefix:gemini", "provider:google", "protocol:gemini", "tool"]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"contents\":[{\"role\":\"user\",\"parts\":[{\"text\":\"Call get_weather with city exactly Paris.\"}]}],\"systemInstruction\":{\"parts\":[{\"text\":\"Call tools exactly as requested.\"}]},\"tools\":[{\"functionDeclarations\":[{\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"parameters\":{\"required\":[\"city\"],\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}}}}]}],\"toolConfig\":{\"functionCallingConfig\":{\"mode\":\"ANY\",\"allowedFunctionNames\":[\"get_weather\"]}},\"generationConfig\":{\"maxOutputTokens\":80,\"temperature\":0}}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream"
+        },
+        "body": "data: {\"candidates\": [{\"content\": {\"parts\": [{\"functionCall\": {\"name\": \"get_weather\",\"args\": {\"city\": \"Paris\"}},\"thoughtSignature\": \"CiQBDDnWx5RcSsS1UMbykQ5HWlrMu6wrxXGUhmZ0uRKLaMhDZaEKXwEMOdbHVoJAlfbOQyKB378pDZ/gkjWr3HP+dWw1us1kMG22g4G3oJvuTq/SrWS+7KYtSlvOxCKhW2l/2/TczpyGyGmANmsusDcxF1SKOYA5/8Hg0nI24MAlT3+91V/MCoUBAQw51seClFLy3E71v2H44F1kpmjgz8FeTRZofrjbaazfrT+w8Yxgdr3UgGagLMY4OadZemQTWckq9IAqRum78hrBg6NGtQvn15SbtfTNqI4PcxX/+qPo4/g4/ZT5kVORDhVqO8BVP/RA5GQ3ce3sRK8hSkvQlXSoXIPpHh6x7hBezIGXzw==\"}],\"role\": \"model\"},\"finishReason\": \"STOP\",\"index\": 0,\"finishMessage\": \"Model generated function call(s).\"}],\"usageMetadata\": {\"promptTokenCount\": 55,\"candidatesTokenCount\": 15,\"totalTokenCount\": 115,\"promptTokensDetails\": [{\"modality\": \"TEXT\",\"tokenCount\": 55}],\"thoughtsTokenCount\": 45},\"modelVersion\": \"gemini-2.5-flash\",\"responseId\": \"NyTxaYuTJ_OW_uMPgIPKgAg\"}\r\n\r\n"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/openai-chat/streams-text.json

@@ -0,0 +1,28 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "openai-chat/streams-text",
+    "recordedAt": "2026-05-06T01:33:30.542Z",
+    "tags": ["prefix:openai-chat", "provider:openai", "protocol:openai-chat"]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.openai.com/v1/chat/completions",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"gpt-4o-mini\",\"messages\":[{\"role\":\"system\",\"content\":\"You are concise.\"},{\"role\":\"user\",\"content\":\"Say hello in one short sentence.\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true},\"max_tokens\":20,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream; charset=utf-8"
+        },
+        "body": "data: {\"id\":\"chatcmpl-DcLQgbFetadY4JFl0fHK0g7OYsCOL\",\"object\":\"chat.completion.chunk\",\"created\":1778031210,\"model\":\"gpt-4o-mini-2024-07-18\",\"service_tier\":\"default\",\"system_fingerprint\":\"fp_57133166c6\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":\"\",\"refusal\":null},\"logprobs\":null,\"finish_reason\":null}],\"usage\":null,\"obfuscation\":\"g9SWm2h6J\"}\n\ndata: {\"id\":\"chatcmpl-DcLQgbFetadY4JFl0fHK0g7OYsCOL\",\"object\":\"chat.completion.chunk\",\"created\":1778031210,\"model\":\"gpt-4o-mini-2024-07-18\",\"service_tier\":\"default\",\"system_fingerprint\":\"fp_57133166c6\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"Hello\"},\"logprobs\":null,\"finish_reason\":null}],\"usage\":null,\"obfuscation\":\"lVzwlh\"}\n\ndata: {\"id\":\"chatcmpl-DcLQgbFetadY4JFl0fHK0g7OYsCOL\",\"object\":\"chat.completion.chunk\",\"created\":1778031210,\"model\":\"gpt-4o-mini-2024-07-18\",\"service_tier\":\"default\",\"system_fingerprint\":\"fp_57133166c6\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"!\"},\"logprobs\":null,\"finish_reason\":null}],\"usage\":null,\"obfuscation\":\"onzhziaLGv\"}\n\ndata: {\"id\":\"chatcmpl-DcLQgbFetadY4JFl0fHK0g7OYsCOL\",\"object\":\"chat.completion.chunk\",\"created\":1778031210,\"model\":\"gpt-4o-mini-2024-07-18\",\"service_tier\":\"default\",\"system_fingerprint\":\"fp_57133166c6\",\"choices\":[{\"index\":0,\"delta\":{},\"logprobs\":null,\"finish_reason\":\"stop\"}],\"usage\":null,\"obfuscation\":\"LzUj1\"}\n\ndata: {\"id\":\"chatcmpl-DcLQgbFetadY4JFl0fHK0g7OYsCOL\",\"object\":\"chat.completion.chunk\",\"created\":1778031210,\"model\":\"gpt-4o-mini-2024-07-18\",\"service_tier\":\"default\",\"system_fingerprint\":\"fp_57133166c6\",\"choices\":[],\"usage\":{\"prompt_tokens\":22,\"completion_tokens\":2,\"total_tokens\":24,\"prompt_tokens_details\":{\"cached_tokens\":0,\"audio_tokens\":0},\"completion_tokens_details\":{\"reasoning_tokens\":0,\"audio_tokens\":0,\"accepted_prediction_tokens\":0,\"rejected_prediction_tokens\":0}},\"obfuscation\":\"emMuPcvvOkI\"}\n\ndata: [DONE]\n\n"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/openai-chat/streams-tool-call.json

@@ -0,0 +1,28 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "openai-chat/streams-tool-call",
+    "recordedAt": "2026-05-06T01:33:31.127Z",
+    "tags": ["prefix:openai-chat", "provider:openai", "protocol:openai-chat", "tool"]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.openai.com/v1/chat/completions",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"gpt-4o-mini\",\"messages\":[{\"role\":\"system\",\"content\":\"Call tools exactly as requested.\"},{\"role\":\"user\",\"content\":\"Call get_weather with city exactly Paris.\"}],\"tools\":[{\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"parameters\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false}}}],\"tool_choice\":{\"type\":\"function\",\"function\":{\"name\":\"get_weather\"}},\"stream\":true,\"stream_options\":{\"include_usage\":true},\"max_tokens\":80,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream; charset=utf-8"
+        },
+        "body": "data: {\"id\":\"chatcmpl-DcLQgGuIIwnMHqZMRCOwZMLir5SkK\",\"object\":\"chat.completion.chunk\",\"created\":1778031210,\"model\":\"gpt-4o-mini-2024-07-18\",\"service_tier\":\"default\",\"system_fingerprint\":\"fp_d0a1738203\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":null,\"tool_calls\":[{\"index\":0,\"id\":\"call_5wBV98AvGPwOyC6a2HtKh85w\",\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"arguments\":\"\"}}],\"refusal\":null},\"logprobs\":null,\"finish_reason\":null}],\"usage\":null,\"obfuscation\":\"hrw8\"}\n\ndata: {\"id\":\"chatcmpl-DcLQgGuIIwnMHqZMRCOwZMLir5SkK\",\"object\":\"chat.completion.chunk\",\"created\":1778031210,\"model\":\"gpt-4o-mini-2024-07-18\",\"service_tier\":\"default\",\"system_fingerprint\":\"fp_d0a1738203\",\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"{\\\"\"}}]},\"logprobs\":null,\"finish_reason\":null}],\"usage\":null,\"obfuscation\":\"MzOlaTohF20Sbb\"}\n\ndata: {\"id\":\"chatcmpl-DcLQgGuIIwnMHqZMRCOwZMLir5SkK\",\"object\":\"chat.completion.chunk\",\"created\":1778031210,\"model\":\"gpt-4o-mini-2024-07-18\",\"service_tier\":\"default\",\"system_fingerprint\":\"fp_d0a1738203\",\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"city\"}}]},\"logprobs\":null,\"finish_reason\":null}],\"usage\":null,\"obfuscation\":\"QuYBQ5vYEUVxR\"}\n\ndata: {\"id\":\"chatcmpl-DcLQgGuIIwnMHqZMRCOwZMLir5SkK\",\"object\":\"chat.completion.chunk\",\"created\":1778031210,\"model\":\"gpt-4o-mini-2024-07-18\",\"service_tier\":\"default\",\"system_fingerprint\":\"fp_d0a1738203\",\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"\\\":\\\"\"}}]},\"logprobs\":null,\"finish_reason\":null}],\"usage\":null,\"obfuscation\":\"spyXlsV2hl6l\"}\n\ndata: {\"id\":\"chatcmpl-DcLQgGuIIwnMHqZMRCOwZMLir5SkK\",\"object\":\"chat.completion.chunk\",\"created\":1778031210,\"model\":\"gpt-4o-mini-2024-07-18\",\"service_tier\":\"default\",\"system_fingerprint\":\"fp_d0a1738203\",\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"Paris\"}}]},\"logprobs\":null,\"finish_reason\":null}],\"usage\":null,\"obfuscation\":\"Db1cjFKa6YAI\"}\n\ndata: {\"id\":\"chatcmpl-DcLQgGuIIwnMHqZMRCOwZMLir5SkK\",\"object\":\"chat.completion.chunk\",\"created\":1778031210,\"model\":\"gpt-4o-mini-2024-07-18\",\"service_tier\":\"default\",\"system_fingerprint\":\"fp_d0a1738203\",\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"\\\"}\"}}]},\"logprobs\":null,\"finish_reason\":null}],\"usage\":null,\"obfuscation\":\"oPu35nrhXcjTL5\"}\n\ndata: {\"id\":\"chatcmpl-DcLQgGuIIwnMHqZMRCOwZMLir5SkK\",\"object\":\"chat.completion.chunk\",\"created\":1778031210,\"model\":\"gpt-4o-mini-2024-07-18\",\"service_tier\":\"default\",\"system_fingerprint\":\"fp_d0a1738203\",\"choices\":[{\"index\":0,\"delta\":{},\"logprobs\":null,\"finish_reason\":\"stop\"}],\"usage\":null,\"obfuscation\":\"63TVy\"}\n\ndata: {\"id\":\"chatcmpl-DcLQgGuIIwnMHqZMRCOwZMLir5SkK\",\"object\":\"chat.completion.chunk\",\"created\":1778031210,\"model\":\"gpt-4o-mini-2024-07-18\",\"service_tier\":\"default\",\"system_fingerprint\":\"fp_d0a1738203\",\"choices\":[],\"usage\":{\"prompt_tokens\":67,\"completion_tokens\":5,\"total_tokens\":72,\"prompt_tokens_details\":{\"cached_tokens\":0,\"audio_tokens\":0},\"completion_tokens_details\":{\"reasoning_tokens\":0,\"audio_tokens\":0,\"accepted_prediction_tokens\":0,\"rejected_prediction_tokens\":0}},\"obfuscation\":\"NxJjur40z4H\"}\n\ndata: [DONE]\n\n"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/openai-compatible-chat/deepseek-streams-text.json

@@ -0,0 +1,28 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "openai-compatible-chat/deepseek-streams-text",
+    "recordedAt": "2026-04-28T21:18:49.498Z",
+    "tags": ["prefix:openai-compatible-chat", "protocol:openai-compatible-chat", "provider:deepseek"]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.deepseek.com/v1/chat/completions",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"deepseek-chat\",\"messages\":[{\"role\":\"system\",\"content\":\"You are concise.\"},{\"role\":\"user\",\"content\":\"Reply with exactly: Hello!\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true},\"max_tokens\":20,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream; charset=utf-8"
+        },
+        "body": "data: {\"id\":\"0c811926-1e0c-4160-baf8-6e71247c8ad7\",\"object\":\"chat.completion.chunk\",\"created\":1777411128,\"model\":\"deepseek-v4-flash\",\"system_fingerprint\":\"fp_058df29938_prod0820_fp8_kvcache_20260402\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":\"\"},\"logprobs\":null,\"finish_reason\":null}]}\n\ndata: {\"id\":\"0c811926-1e0c-4160-baf8-6e71247c8ad7\",\"object\":\"chat.completion.chunk\",\"created\":1777411128,\"model\":\"deepseek-v4-flash\",\"system_fingerprint\":\"fp_058df29938_prod0820_fp8_kvcache_20260402\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"Hello\"},\"logprobs\":null,\"finish_reason\":null}]}\n\ndata: {\"id\":\"0c811926-1e0c-4160-baf8-6e71247c8ad7\",\"object\":\"chat.completion.chunk\",\"created\":1777411128,\"model\":\"deepseek-v4-flash\",\"system_fingerprint\":\"fp_058df29938_prod0820_fp8_kvcache_20260402\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"!\"},\"logprobs\":null,\"finish_reason\":null}]}\n\ndata: {\"id\":\"0c811926-1e0c-4160-baf8-6e71247c8ad7\",\"object\":\"chat.completion.chunk\",\"created\":1777411128,\"model\":\"deepseek-v4-flash\",\"system_fingerprint\":\"fp_058df29938_prod0820_fp8_kvcache_20260402\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\"},\"logprobs\":null,\"finish_reason\":\"stop\"}],\"usage\":{\"prompt_tokens\":14,\"completion_tokens\":2,\"total_tokens\":16,\"prompt_tokens_details\":{\"cached_tokens\":0},\"prompt_cache_hit_tokens\":0,\"prompt_cache_miss_tokens\":14}}\n\ndata: [DONE]\n\n"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/openai-compatible-chat/groq-streams-text.json

@@ -0,0 +1,28 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "openai-compatible-chat/groq-streams-text",
+    "recordedAt": "2026-05-06T01:35:05.532Z",
+    "tags": ["prefix:openai-compatible-chat", "protocol:openai-compatible-chat", "provider:groq"]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.groq.com/openai/v1/chat/completions",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"llama-3.3-70b-versatile\",\"messages\":[{\"role\":\"system\",\"content\":\"You are concise.\"},{\"role\":\"user\",\"content\":\"Reply with exactly: Hello!\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true},\"max_tokens\":20,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream"
+        },
+        "body": "data: {\"id\":\"chatcmpl-dd5aae9f-7032-44a7-aca8-01027903b4c9\",\"object\":\"chat.completion.chunk\",\"created\":1778031305,\"model\":\"llama-3.3-70b-versatile\",\"system_fingerprint\":\"fp_d42c28f9ce\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":\"\"},\"logprobs\":null,\"finish_reason\":null}],\"x_groq\":{\"id\":\"req_01kqxes8r3fmja0yhxvt665m6h\",\"seed\":687314058}}\n\ndata: {\"id\":\"chatcmpl-dd5aae9f-7032-44a7-aca8-01027903b4c9\",\"object\":\"chat.completion.chunk\",\"created\":1778031305,\"model\":\"llama-3.3-70b-versatile\",\"system_fingerprint\":\"fp_d42c28f9ce\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"Hello\"},\"logprobs\":null,\"finish_reason\":null}]}\n\ndata: {\"id\":\"chatcmpl-dd5aae9f-7032-44a7-aca8-01027903b4c9\",\"object\":\"chat.completion.chunk\",\"created\":1778031305,\"model\":\"llama-3.3-70b-versatile\",\"system_fingerprint\":\"fp_d42c28f9ce\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"!\"},\"logprobs\":null,\"finish_reason\":null}]}\n\ndata: {\"id\":\"chatcmpl-dd5aae9f-7032-44a7-aca8-01027903b4c9\",\"object\":\"chat.completion.chunk\",\"created\":1778031305,\"model\":\"llama-3.3-70b-versatile\",\"system_fingerprint\":\"fp_d42c28f9ce\",\"choices\":[{\"index\":0,\"delta\":{},\"logprobs\":null,\"finish_reason\":\"stop\"}],\"x_groq\":{\"id\":\"req_01kqxes8r3fmja0yhxvt665m6h\",\"usage\":{\"queue_time\":0.0381395,\"prompt_tokens\":45,\"prompt_time\":0.003985297,\"completion_tokens\":3,\"completion_time\":0.014171875,\"total_tokens\":48,\"total_time\":0.018157172}},\"usage\":{\"queue_time\":0.0381395,\"prompt_tokens\":45,\"prompt_time\":0.003985297,\"completion_tokens\":3,\"completion_time\":0.014171875,\"total_tokens\":48,\"total_time\":0.018157172}}\n\ndata: {\"id\":\"chatcmpl-dd5aae9f-7032-44a7-aca8-01027903b4c9\",\"object\":\"chat.completion.chunk\",\"created\":1778031305,\"model\":\"llama-3.3-70b-versatile\",\"system_fingerprint\":\"fp_d42c28f9ce\",\"choices\":[],\"usage\":{\"queue_time\":0.0381395,\"prompt_tokens\":45,\"prompt_time\":0.003985297,\"completion_tokens\":3,\"completion_time\":0.014171875,\"total_tokens\":48,\"total_time\":0.018157172},\"service_tier\":\"on_demand\"}\n\ndata: [DONE]\n\n"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/openai-compatible-chat/groq-streams-tool-call.json

@@ -0,0 +1,28 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "openai-compatible-chat/groq-streams-tool-call",
+    "recordedAt": "2026-05-06T01:35:05.706Z",
+    "tags": ["prefix:openai-compatible-chat", "protocol:openai-compatible-chat", "provider:groq", "tool"]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.groq.com/openai/v1/chat/completions",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"llama-3.3-70b-versatile\",\"messages\":[{\"role\":\"system\",\"content\":\"Call tools exactly as requested.\"},{\"role\":\"user\",\"content\":\"Call get_weather with city exactly Paris.\"}],\"tools\":[{\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"parameters\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false}}}],\"tool_choice\":{\"type\":\"function\",\"function\":{\"name\":\"get_weather\"}},\"stream\":true,\"stream_options\":{\"include_usage\":true},\"max_tokens\":80,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream"
+        },
+        "body": "data: {\"id\":\"chatcmpl-05380361-f8e4-444a-ae80-296b4d1d46f7\",\"object\":\"chat.completion.chunk\",\"created\":1778031305,\"model\":\"llama-3.3-70b-versatile\",\"system_fingerprint\":\"fp_0761e44d7b\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":null},\"logprobs\":null,\"finish_reason\":null}],\"x_groq\":{\"id\":\"req_01kqxes8v4fm7baf4smt42f0qn\",\"seed\":1846647562}}\n\ndata: {\"id\":\"chatcmpl-05380361-f8e4-444a-ae80-296b4d1d46f7\",\"object\":\"chat.completion.chunk\",\"created\":1778031305,\"model\":\"llama-3.3-70b-versatile\",\"system_fingerprint\":\"fp_0761e44d7b\",\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"id\":\"mcf2d8nn1\",\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"arguments\":\"{\\\"city\\\":\\\"Paris\\\"}\"},\"index\":0}]},\"logprobs\":null,\"finish_reason\":null}]}\n\ndata: {\"id\":\"chatcmpl-05380361-f8e4-444a-ae80-296b4d1d46f7\",\"object\":\"chat.completion.chunk\",\"created\":1778031305,\"model\":\"llama-3.3-70b-versatile\",\"system_fingerprint\":\"fp_0761e44d7b\",\"choices\":[{\"index\":0,\"delta\":{},\"logprobs\":null,\"finish_reason\":\"tool_calls\"}],\"x_groq\":{\"id\":\"req_01kqxes8v4fm7baf4smt42f0qn\",\"usage\":{\"queue_time\":0.07684935,\"prompt_tokens\":249,\"prompt_time\":0.014815006,\"completion_tokens\":10,\"completion_time\":0.036435756,\"total_tokens\":259,\"total_time\":0.051250762}},\"usage\":{\"queue_time\":0.07684935,\"prompt_tokens\":249,\"prompt_time\":0.014815006,\"completion_tokens\":10,\"completion_time\":0.036435756,\"total_tokens\":259,\"total_time\":0.051250762}}\n\ndata: {\"id\":\"chatcmpl-05380361-f8e4-444a-ae80-296b4d1d46f7\",\"object\":\"chat.completion.chunk\",\"created\":1778031305,\"model\":\"llama-3.3-70b-versatile\",\"system_fingerprint\":\"fp_0761e44d7b\",\"choices\":[],\"usage\":{\"queue_time\":0.07684935,\"prompt_tokens\":249,\"prompt_time\":0.014815006,\"completion_tokens\":10,\"completion_time\":0.036435756,\"total_tokens\":259,\"total_time\":0.051250762},\"service_tier\":\"on_demand\"}\n\ndata: [DONE]\n\n"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/openai-compatible-chat/openrouter-claude-opus-4-7-drives-a-tool-loop.json

@@ -0,0 +1,54 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "openai-compatible-chat/openrouter-claude-opus-4-7-drives-a-tool-loop",
+    "recordedAt": "2026-05-06T01:35:14.282Z",
+    "tags": [
+      "prefix:openai-compatible-chat",
+      "protocol:openai-compatible-chat",
+      "provider:openrouter",
+      "tool",
+      "tool-loop",
+      "golden",
+      "flagship"
+    ]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://openrouter.ai/api/v1/chat/completions",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"anthropic/claude-opus-4.7\",\"messages\":[{\"role\":\"system\",\"content\":\"Use the get_weather tool exactly once, then answer in one short sentence.\"},{\"role\":\"user\",\"content\":\"What is the weather in Paris?\"}],\"tools\":[{\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"parameters\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false}}}],\"stream\":true,\"stream_options\":{\"include_usage\":true},\"max_tokens\":80,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream"
+        },
+        "body": ": OPENROUTER PROCESSING\n\n: OPENROUTER PROCESSING\n\n: OPENROUTER PROCESSING\n\ndata: {\"id\":\"gen-1778031311-S3NlfYGRwAnOoPoNrThK\",\"object\":\"chat.completion.chunk\",\"created\":1778031311,\"model\":\"anthropic/claude-4.7-opus-20260416\",\"provider\":\"Amazon Bedrock\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"id\":\"toolu_bdrk_01AVRkzbigpMbNJ3zjnuQ6ZE\",\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"arguments\":\"\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031311-S3NlfYGRwAnOoPoNrThK\",\"object\":\"chat.completion.chunk\",\"created\":1778031311,\"model\":\"anthropic/claude-4.7-opus-20260416\",\"provider\":\"Amazon Bedrock\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031311-S3NlfYGRwAnOoPoNrThK\",\"object\":\"chat.completion.chunk\",\"created\":1778031311,\"model\":\"anthropic/claude-4.7-opus-20260416\",\"provider\":\"Amazon Bedrock\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031311-S3NlfYGRwAnOoPoNrThK\",\"object\":\"chat.completion.chunk\",\"created\":1778031311,\"model\":\"anthropic/claude-4.7-opus-20260416\",\"provider\":\"Amazon Bedrock\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"{\\\"city\\\": \\\"P\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031311-S3NlfYGRwAnOoPoNrThK\",\"object\":\"chat.completion.chunk\",\"created\":1778031311,\"model\":\"anthropic/claude-4.7-opus-20260416\",\"provider\":\"Amazon Bedrock\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"ari\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031311-S3NlfYGRwAnOoPoNrThK\",\"object\":\"chat.completion.chunk\",\"created\":1778031311,\"model\":\"anthropic/claude-4.7-opus-20260416\",\"provider\":\"Amazon Bedrock\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"s\\\"}\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031311-S3NlfYGRwAnOoPoNrThK\",\"object\":\"chat.completion.chunk\",\"created\":1778031311,\"model\":\"anthropic/claude-4.7-opus-20260416\",\"provider\":\"Amazon Bedrock\",\"service_tier\":\"standard\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\",\"role\":\"assistant\"},\"finish_reason\":\"tool_calls\",\"native_finish_reason\":\"tool_use\"}]}\n\ndata: {\"id\":\"gen-1778031311-S3NlfYGRwAnOoPoNrThK\",\"object\":\"chat.completion.chunk\",\"created\":1778031311,\"model\":\"anthropic/claude-4.7-opus-20260416\",\"provider\":\"Amazon Bedrock\",\"service_tier\":\"standard\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\",\"role\":\"assistant\"},\"finish_reason\":\"tool_calls\",\"native_finish_reason\":\"tool_use\"}],\"usage\":{\"prompt_tokens\":802,\"completion_tokens\":66,\"total_tokens\":868,\"cost\":0.00566,\"is_byok\":false,\"prompt_tokens_details\":{\"cached_tokens\":0,\"cache_write_tokens\":0,\"audio_tokens\":0,\"video_tokens\":0},\"cost_details\":{\"upstream_inference_cost\":0.00566,\"upstream_inference_prompt_cost\":0.00401,\"upstream_inference_completions_cost\":0.00165},\"completion_tokens_details\":{\"reasoning_tokens\":0,\"image_tokens\":0,\"audio_tokens\":0}}}\n\ndata: [DONE]\n\n"
+      }
+    },
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://openrouter.ai/api/v1/chat/completions",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"anthropic/claude-opus-4.7\",\"messages\":[{\"role\":\"system\",\"content\":\"Use the get_weather tool exactly once, then answer in one short sentence.\"},{\"role\":\"user\",\"content\":\"What is the weather in Paris?\"},{\"role\":\"assistant\",\"content\":null,\"tool_calls\":[{\"id\":\"toolu_bdrk_01AVRkzbigpMbNJ3zjnuQ6ZE\",\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"arguments\":\"{\\\"city\\\":\\\"Paris\\\"}\"}}]},{\"role\":\"tool\",\"tool_call_id\":\"toolu_bdrk_01AVRkzbigpMbNJ3zjnuQ6ZE\",\"content\":\"{\\\"temperature\\\":22,\\\"condition\\\":\\\"sunny\\\"}\"}],\"tools\":[{\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"parameters\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false}}}],\"stream\":true,\"stream_options\":{\"include_usage\":true},\"max_tokens\":80,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream"
+        },
+        "body": ": OPENROUTER PROCESSING\n\ndata: {\"id\":\"gen-1778031313-XM4XZGmFyt6jg3GZ772w\",\"object\":\"chat.completion.chunk\",\"created\":1778031313,\"model\":\"anthropic/claude-4.7-opus-20260416\",\"provider\":\"Amazon Bedrock\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"It\",\"role\":\"assistant\"},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031313-XM4XZGmFyt6jg3GZ772w\",\"object\":\"chat.completion.chunk\",\"created\":1778031313,\"model\":\"anthropic/claude-4.7-opus-20260416\",\"provider\":\"Amazon Bedrock\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"'s sunny and\",\"role\":\"assistant\"},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031313-XM4XZGmFyt6jg3GZ772w\",\"object\":\"chat.completion.chunk\",\"created\":1778031313,\"model\":\"anthropic/claude-4.7-opus-20260416\",\"provider\":\"Amazon Bedrock\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\" 22°C in\",\"role\":\"assistant\"},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031313-XM4XZGmFyt6jg3GZ772w\",\"object\":\"chat.completion.chunk\",\"created\":1778031313,\"model\":\"anthropic/claude-4.7-opus-20260416\",\"provider\":\"Amazon Bedrock\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\" Paris.\",\"role\":\"assistant\"},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031313-XM4XZGmFyt6jg3GZ772w\",\"object\":\"chat.completion.chunk\",\"created\":1778031313,\"model\":\"anthropic/claude-4.7-opus-20260416\",\"provider\":\"Amazon Bedrock\",\"service_tier\":\"standard\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\",\"role\":\"assistant\"},\"finish_reason\":\"stop\",\"native_finish_reason\":\"end_turn\"}]}\n\ndata: {\"id\":\"gen-1778031313-XM4XZGmFyt6jg3GZ772w\",\"object\":\"chat.completion.chunk\",\"created\":1778031313,\"model\":\"anthropic/claude-4.7-opus-20260416\",\"provider\":\"Amazon Bedrock\",\"service_tier\":\"standard\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\",\"role\":\"assistant\"},\"finish_reason\":\"stop\",\"native_finish_reason\":\"end_turn\"}],\"usage\":{\"prompt_tokens\":899,\"completion_tokens\":19,\"total_tokens\":918,\"cost\":0.00497,\"is_byok\":false,\"prompt_tokens_details\":{\"cached_tokens\":0,\"cache_write_tokens\":0,\"audio_tokens\":0,\"video_tokens\":0},\"cost_details\":{\"upstream_inference_cost\":0.00497,\"upstream_inference_prompt_cost\":0.004495,\"upstream_inference_completions_cost\":0.000475},\"completion_tokens_details\":{\"reasoning_tokens\":0,\"image_tokens\":0,\"audio_tokens\":0}}}\n\ndata: [DONE]\n\n"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/openai-compatible-chat/openrouter-gpt-5-5-drives-a-tool-loop.json

@@ -0,0 +1,54 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "openai-compatible-chat/openrouter-gpt-5-5-drives-a-tool-loop",
+    "recordedAt": "2026-05-06T01:35:11.662Z",
+    "tags": [
+      "prefix:openai-compatible-chat",
+      "protocol:openai-compatible-chat",
+      "provider:openrouter",
+      "tool",
+      "tool-loop",
+      "golden",
+      "flagship"
+    ]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://openrouter.ai/api/v1/chat/completions",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"openai/gpt-5.5\",\"messages\":[{\"role\":\"system\",\"content\":\"Use the get_weather tool exactly once, then answer in one short sentence.\"},{\"role\":\"user\",\"content\":\"What is the weather in Paris?\"}],\"tools\":[{\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"parameters\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false}}}],\"stream\":true,\"stream_options\":{\"include_usage\":true},\"max_tokens\":80,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream"
+        },
+        "body": ": OPENROUTER PROCESSING\n\n: OPENROUTER PROCESSING\n\ndata: {\"id\":\"gen-1778031308-dVa9axcHcOlG9GcilZkz\",\"object\":\"chat.completion.chunk\",\"created\":1778031308,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"id\":\"call_4A7V7UN36HXCUUn8qAOQaKGw\",\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"arguments\":\"\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031308-dVa9axcHcOlG9GcilZkz\",\"object\":\"chat.completion.chunk\",\"created\":1778031308,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031308-dVa9axcHcOlG9GcilZkz\",\"object\":\"chat.completion.chunk\",\"created\":1778031308,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"{\\\"\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031308-dVa9axcHcOlG9GcilZkz\",\"object\":\"chat.completion.chunk\",\"created\":1778031308,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"city\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031308-dVa9axcHcOlG9GcilZkz\",\"object\":\"chat.completion.chunk\",\"created\":1778031308,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"\\\":\\\"\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031308-dVa9axcHcOlG9GcilZkz\",\"object\":\"chat.completion.chunk\",\"created\":1778031308,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"Paris\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031308-dVa9axcHcOlG9GcilZkz\",\"object\":\"chat.completion.chunk\",\"created\":1778031308,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"\\\"}\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031308-dVa9axcHcOlG9GcilZkz\",\"object\":\"chat.completion.chunk\",\"created\":1778031308,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"service_tier\":\"default\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\",\"role\":\"assistant\"},\"finish_reason\":\"tool_calls\",\"native_finish_reason\":\"completed\"}]}\n\ndata: {\"id\":\"gen-1778031308-dVa9axcHcOlG9GcilZkz\",\"object\":\"chat.completion.chunk\",\"created\":1778031308,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"service_tier\":\"default\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\",\"role\":\"assistant\"},\"finish_reason\":\"tool_calls\",\"native_finish_reason\":\"completed\"}],\"usage\":{\"prompt_tokens\":69,\"completion_tokens\":18,\"total_tokens\":87,\"cost\":0.000885,\"is_byok\":false,\"prompt_tokens_details\":{\"cached_tokens\":0,\"cache_write_tokens\":0,\"audio_tokens\":0,\"video_tokens\":0},\"cost_details\":{\"upstream_inference_cost\":0.000885,\"upstream_inference_prompt_cost\":0.000345,\"upstream_inference_completions_cost\":0.00054},\"completion_tokens_details\":{\"reasoning_tokens\":0,\"image_tokens\":0,\"audio_tokens\":0}}}\n\ndata: [DONE]\n\n"
+      }
+    },
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://openrouter.ai/api/v1/chat/completions",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"openai/gpt-5.5\",\"messages\":[{\"role\":\"system\",\"content\":\"Use the get_weather tool exactly once, then answer in one short sentence.\"},{\"role\":\"user\",\"content\":\"What is the weather in Paris?\"},{\"role\":\"assistant\",\"content\":null,\"tool_calls\":[{\"id\":\"call_4A7V7UN36HXCUUn8qAOQaKGw\",\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"arguments\":\"{\\\"city\\\":\\\"Paris\\\"}\"}}]},{\"role\":\"tool\",\"tool_call_id\":\"call_4A7V7UN36HXCUUn8qAOQaKGw\",\"content\":\"{\\\"temperature\\\":22,\\\"condition\\\":\\\"sunny\\\"}\"}],\"tools\":[{\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"parameters\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false}}}],\"stream\":true,\"stream_options\":{\"include_usage\":true},\"max_tokens\":80,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream"
+        },
+        "body": ": OPENROUTER PROCESSING\n\n: OPENROUTER PROCESSING\n\ndata: {\"id\":\"gen-1778031310-JUYfFzDbun699uUYoA4N\",\"object\":\"chat.completion.chunk\",\"created\":1778031310,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"Paris\",\"role\":\"assistant\"},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031310-JUYfFzDbun699uUYoA4N\",\"object\":\"chat.completion.chunk\",\"created\":1778031310,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\" is\",\"role\":\"assistant\"},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031310-JUYfFzDbun699uUYoA4N\",\"object\":\"chat.completion.chunk\",\"created\":1778031310,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\" sunny\",\"role\":\"assistant\"},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031310-JUYfFzDbun699uUYoA4N\",\"object\":\"chat.completion.chunk\",\"created\":1778031310,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\" and\",\"role\":\"assistant\"},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031310-JUYfFzDbun699uUYoA4N\",\"object\":\"chat.completion.chunk\",\"created\":1778031310,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\" \",\"role\":\"assistant\"},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031310-JUYfFzDbun699uUYoA4N\",\"object\":\"chat.completion.chunk\",\"created\":1778031310,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"22\",\"role\":\"assistant\"},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031310-JUYfFzDbun699uUYoA4N\",\"object\":\"chat.completion.chunk\",\"created\":1778031310,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"°C\",\"role\":\"assistant\"},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031310-JUYfFzDbun699uUYoA4N\",\"object\":\"chat.completion.chunk\",\"created\":1778031310,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\".\",\"role\":\"assistant\"},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031310-JUYfFzDbun699uUYoA4N\",\"object\":\"chat.completion.chunk\",\"created\":1778031310,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"service_tier\":\"default\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\",\"role\":\"assistant\"},\"finish_reason\":\"stop\",\"native_finish_reason\":\"completed\"}]}\n\ndata: {\"id\":\"gen-1778031310-JUYfFzDbun699uUYoA4N\",\"object\":\"chat.completion.chunk\",\"created\":1778031310,\"model\":\"openai/gpt-5.5-20260423\",\"provider\":\"OpenAI\",\"service_tier\":\"default\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\",\"role\":\"assistant\"},\"finish_reason\":\"stop\",\"native_finish_reason\":\"completed\"}],\"usage\":{\"prompt_tokens\":108,\"completion_tokens\":12,\"total_tokens\":120,\"cost\":0.0009,\"is_byok\":false,\"prompt_tokens_details\":{\"cached_tokens\":0,\"cache_write_tokens\":0,\"audio_tokens\":0,\"video_tokens\":0},\"cost_details\":{\"upstream_inference_cost\":0.0009,\"upstream_inference_prompt_cost\":0.00054,\"upstream_inference_completions_cost\":0.00036},\"completion_tokens_details\":{\"reasoning_tokens\":0,\"image_tokens\":0,\"audio_tokens\":0}}}\n\ndata: [DONE]\n\n"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/openai-compatible-chat/openrouter-streams-text.json

@@ -0,0 +1,28 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "openai-compatible-chat/openrouter-streams-text",
+    "recordedAt": "2026-05-06T01:35:06.767Z",
+    "tags": ["prefix:openai-compatible-chat", "protocol:openai-compatible-chat", "provider:openrouter"]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://openrouter.ai/api/v1/chat/completions",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"openai/gpt-4o-mini\",\"messages\":[{\"role\":\"system\",\"content\":\"You are concise.\"},{\"role\":\"user\",\"content\":\"Reply with exactly: Hello!\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true},\"max_tokens\":20,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream"
+        },
+        "body": ": OPENROUTER PROCESSING\n\ndata: {\"id\":\"gen-1778031306-UD7bR0I1JNCsPvVzlXat\",\"object\":\"chat.completion.chunk\",\"created\":1778031306,\"model\":\"openai/gpt-4o-mini\",\"provider\":\"Azure\",\"system_fingerprint\":\"fp_eb37e061ec\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"Hello\",\"role\":\"assistant\"},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031306-UD7bR0I1JNCsPvVzlXat\",\"object\":\"chat.completion.chunk\",\"created\":1778031306,\"model\":\"openai/gpt-4o-mini\",\"provider\":\"Azure\",\"system_fingerprint\":\"fp_eb37e061ec\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"!\",\"role\":\"assistant\"},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031306-UD7bR0I1JNCsPvVzlXat\",\"object\":\"chat.completion.chunk\",\"created\":1778031306,\"model\":\"openai/gpt-4o-mini\",\"provider\":\"Azure\",\"system_fingerprint\":\"fp_eb37e061ec\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\",\"role\":\"assistant\"},\"finish_reason\":\"stop\",\"native_finish_reason\":\"stop\"}]}\n\ndata: {\"id\":\"gen-1778031306-UD7bR0I1JNCsPvVzlXat\",\"object\":\"chat.completion.chunk\",\"created\":1778031306,\"model\":\"openai/gpt-4o-mini\",\"provider\":\"Azure\",\"system_fingerprint\":\"fp_eb37e061ec\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\",\"role\":\"assistant\"},\"finish_reason\":\"stop\",\"native_finish_reason\":\"stop\"}],\"usage\":{\"prompt_tokens\":21,\"completion_tokens\":3,\"total_tokens\":24,\"cost\":0.00000495,\"is_byok\":false,\"prompt_tokens_details\":{\"cached_tokens\":0,\"cache_write_tokens\":0,\"audio_tokens\":0,\"video_tokens\":0},\"cost_details\":{\"upstream_inference_cost\":0.00000495,\"upstream_inference_prompt_cost\":0.00000315,\"upstream_inference_completions_cost\":0.0000018},\"completion_tokens_details\":{\"reasoning_tokens\":0,\"image_tokens\":0,\"audio_tokens\":0}}}\n\ndata: [DONE]\n\n"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/openai-compatible-chat/openrouter-streams-tool-call.json

@@ -0,0 +1,28 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "openai-compatible-chat/openrouter-streams-tool-call",
+    "recordedAt": "2026-05-06T01:35:07.466Z",
+    "tags": ["prefix:openai-compatible-chat", "protocol:openai-compatible-chat", "provider:openrouter", "tool"]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://openrouter.ai/api/v1/chat/completions",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"openai/gpt-4o-mini\",\"messages\":[{\"role\":\"system\",\"content\":\"Call tools exactly as requested.\"},{\"role\":\"user\",\"content\":\"Call get_weather with city exactly Paris.\"}],\"tools\":[{\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"parameters\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false}}}],\"tool_choice\":{\"type\":\"function\",\"function\":{\"name\":\"get_weather\"}},\"stream\":true,\"stream_options\":{\"include_usage\":true},\"max_tokens\":80,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream"
+        },
+        "body": ": OPENROUTER PROCESSING\n\ndata: {\"id\":\"gen-1778031306-HYzOq04JIk1hZQ4iaNjD\",\"object\":\"chat.completion.chunk\",\"created\":1778031306,\"model\":\"openai/gpt-4o-mini\",\"provider\":\"OpenAI\",\"system_fingerprint\":\"fp_b6580bbee1\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"id\":\"call_L7mHMq49ZSUTBHjLJfBIP2eT\",\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"arguments\":\"\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031306-HYzOq04JIk1hZQ4iaNjD\",\"object\":\"chat.completion.chunk\",\"created\":1778031306,\"model\":\"openai/gpt-4o-mini\",\"provider\":\"OpenAI\",\"system_fingerprint\":\"fp_b6580bbee1\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031306-HYzOq04JIk1hZQ4iaNjD\",\"object\":\"chat.completion.chunk\",\"created\":1778031306,\"model\":\"openai/gpt-4o-mini\",\"provider\":\"OpenAI\",\"system_fingerprint\":\"fp_b6580bbee1\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"{\\\"\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031306-HYzOq04JIk1hZQ4iaNjD\",\"object\":\"chat.completion.chunk\",\"created\":1778031306,\"model\":\"openai/gpt-4o-mini\",\"provider\":\"OpenAI\",\"system_fingerprint\":\"fp_b6580bbee1\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"city\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031306-HYzOq04JIk1hZQ4iaNjD\",\"object\":\"chat.completion.chunk\",\"created\":1778031306,\"model\":\"openai/gpt-4o-mini\",\"provider\":\"OpenAI\",\"system_fingerprint\":\"fp_b6580bbee1\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"\\\":\\\"\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031306-HYzOq04JIk1hZQ4iaNjD\",\"object\":\"chat.completion.chunk\",\"created\":1778031306,\"model\":\"openai/gpt-4o-mini\",\"provider\":\"OpenAI\",\"system_fingerprint\":\"fp_b6580bbee1\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"Paris\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031306-HYzOq04JIk1hZQ4iaNjD\",\"object\":\"chat.completion.chunk\",\"created\":1778031306,\"model\":\"openai/gpt-4o-mini\",\"provider\":\"OpenAI\",\"system_fingerprint\":\"fp_b6580bbee1\",\"choices\":[{\"index\":0,\"delta\":{\"content\":null,\"role\":\"assistant\",\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"\\\"}\"}}]},\"finish_reason\":null,\"native_finish_reason\":null}]}\n\ndata: {\"id\":\"gen-1778031306-HYzOq04JIk1hZQ4iaNjD\",\"object\":\"chat.completion.chunk\",\"created\":1778031306,\"model\":\"openai/gpt-4o-mini\",\"provider\":\"OpenAI\",\"system_fingerprint\":\"fp_b6580bbee1\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\",\"role\":\"assistant\"},\"finish_reason\":\"tool_calls\",\"native_finish_reason\":\"stop\"}]}\n\ndata: {\"id\":\"gen-1778031306-HYzOq04JIk1hZQ4iaNjD\",\"object\":\"chat.completion.chunk\",\"created\":1778031306,\"model\":\"openai/gpt-4o-mini\",\"provider\":\"OpenAI\",\"system_fingerprint\":\"fp_b6580bbee1\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"\",\"role\":\"assistant\"},\"finish_reason\":\"tool_calls\",\"native_finish_reason\":\"stop\"}],\"usage\":{\"prompt_tokens\":67,\"completion_tokens\":5,\"total_tokens\":72,\"cost\":0.00001305,\"is_byok\":false,\"prompt_tokens_details\":{\"cached_tokens\":0,\"cache_write_tokens\":0,\"audio_tokens\":0,\"video_tokens\":0},\"cost_details\":{\"upstream_inference_cost\":0.00001305,\"upstream_inference_prompt_cost\":0.00001005,\"upstream_inference_completions_cost\":0.000003},\"completion_tokens_details\":{\"reasoning_tokens\":0,\"image_tokens\":0,\"audio_tokens\":0}}}\n\ndata: [DONE]\n\n"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/openai-compatible-chat/togetherai-streams-text.json

@@ -0,0 +1,28 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "openai-compatible-chat/togetherai-streams-text",
+    "recordedAt": "2026-04-28T21:18:55.266Z",
+    "tags": ["prefix:openai-compatible-chat", "protocol:openai-compatible-chat", "provider:togetherai"]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.together.xyz/v1/chat/completions",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"meta-llama/Llama-3.3-70B-Instruct-Turbo\",\"messages\":[{\"role\":\"system\",\"content\":\"You are concise.\"},{\"role\":\"user\",\"content\":\"Reply with exactly: Hello!\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true},\"max_tokens\":20,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream;charset=utf-8"
+        },
+        "body": "data: {\"id\":\"ogzjdpL-6Ng1vN-9f391a08f8af75e1\",\"object\":\"chat.completion.chunk\",\"created\":1777411129,\"choices\":[{\"index\":0,\"text\":\"Hello\",\"logprobs\":null,\"finish_reason\":null,\"seed\":null,\"delta\":{\"token_id\":9906,\"role\":\"assistant\",\"content\":\"Hello\"}}],\"model\":\"meta-llama/Llama-3.3-70B-Instruct-Turbo\",\"usage\":null}\n\ndata: {\"id\":\"ogzjdpL-6Ng1vN-9f391a08f8af75e1\",\"object\":\"chat.completion.chunk\",\"created\":1777411129,\"choices\":[{\"index\":0,\"text\":\"!\",\"logprobs\":null,\"finish_reason\":null,\"seed\":null,\"delta\":{\"token_id\":null,\"role\":\"assistant\",\"content\":\"!\"}}],\"model\":\"meta-llama/Llama-3.3-70B-Instruct-Turbo\",\"usage\":null}\n\ndata: {\"id\":\"ogzjdpL-6Ng1vN-9f391a08f8af75e1\",\"object\":\"chat.completion.chunk\",\"created\":1777411129,\"choices\":[{\"index\":0,\"text\":\"\",\"logprobs\":null,\"finish_reason\":\"stop\",\"seed\":15924764223251450000,\"delta\":{\"token_id\":128009,\"role\":\"assistant\",\"content\":\"\"}}],\"model\":\"meta-llama/Llama-3.3-70B-Instruct-Turbo\",\"usage\":{\"prompt_tokens\":45,\"completion_tokens\":3,\"total_tokens\":48,\"cached_tokens\":0}}\n\ndata: [DONE]\n\n"
+      }
+    }
+  ]
+}

packages/llm/test/fixtures/recordings/openai-compatible-chat/togetherai-streams-tool-call.json

@@ -0,0 +1,28 @@
+{
+  "version": 1,
+  "metadata": {
+    "name": "openai-compatible-chat/togetherai-streams-tool-call",
+    "recordedAt": "2026-04-28T21:18:59.123Z",
+    "tags": ["prefix:openai-compatible-chat", "protocol:openai-compatible-chat", "provider:togetherai", "tool"]
+  },
+  "interactions": [
+    {
+      "transport": "http",
+      "request": {
+        "method": "POST",
+        "url": "https://api.together.xyz/v1/chat/completions",
+        "headers": {
+          "content-type": "application/json"
+        },
+        "body": "{\"model\":\"meta-llama/Llama-3.3-70B-Instruct-Turbo\",\"messages\":[{\"role\":\"system\",\"content\":\"Call tools exactly as requested.\"},{\"role\":\"user\",\"content\":\"Call get_weather with city exactly Paris.\"}],\"tools\":[{\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"parameters\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"],\"additionalProperties\":false}}}],\"tool_choice\":{\"type\":\"function\",\"function\":{\"name\":\"get_weather\"}},\"stream\":true,\"stream_options\":{\"include_usage\":true},\"max_tokens\":80,\"temperature\":0}"
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "content-type": "text/event-stream;charset=utf-8"
+        },
+        "body": "data: {\"id\":\"ogzjfRD-6Ng1vN-9f391a2bb8ca75e1\",\"object\":\"chat.completion.chunk\",\"created\":1777411135,\"choices\":[{\"index\":0,\"role\":\"assistant\",\"text\":\"\",\"logprobs\":null,\"finish_reason\":null,\"delta\":{\"token_id\":null,\"role\":\"assistant\",\"content\":\"\"}}],\"model\":\"meta-llama/Llama-3.3-70B-Instruct-Turbo\"}\n\ndata: {\"id\":\"ogzjfRD-6Ng1vN-9f391a2bb8ca75e1\",\"object\":\"chat.completion.chunk\",\"created\":1777411135,\"choices\":[{\"index\":0,\"text\":\"\",\"logprobs\":null,\"finish_reason\":null,\"delta\":{\"token_id\":null,\"role\":\"assistant\",\"content\":\"\",\"tool_calls\":[{\"index\":0,\"id\":\"call_yu1mxtmex7x48nximi9c8jpo\",\"type\":\"function\",\"function\":{\"name\":\"get_weather\",\"arguments\":\"\"}}]}}],\"model\":\"meta-llama/Llama-3.3-70B-Instruct-Turbo\"}\n\ndata: {\"id\":\"ogzjfRD-6Ng1vN-9f391a2bb8ca75e1\",\"object\":\"chat.completion.chunk\",\"created\":1777411135,\"choices\":[{\"index\":0,\"text\":\"\",\"logprobs\":null,\"finish_reason\":\"tool_calls\",\"delta\":{\"token_id\":null,\"role\":\"assistant\",\"content\":\"\",\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"{\\\"city\\\":\\\"Paris\\\"}\"}}]}}],\"model\":\"meta-llama/Llama-3.3-70B-Instruct-Turbo\"}\n\ndata: {\"id\":\"ogzjfRD-6Ng1vN-9f391a2bb8ca75e1\",\"object\":\"chat.completion.chunk\",\"created\":1777411135,\"choices\":[{\"index\":0,\"text\":\"\",\"logprobs\":null,\"finish_reason\":\"tool_calls\",\"seed\":9033012299842426000,\"delta\":{\"token_id\":128009,\"role\":\"assistant\",\"content\":\"\"}}],\"model\":\"meta-llama/Llama-3.3-70B-Instruct-Turbo\",\"usage\":{\"prompt_tokens\":194,\"completion_tokens\":19,\"total_tokens\":213,\"cached_tokens\":0}}\n\ndata: [DONE]\n\n"
+      }
+    }
+  ]
+}

packages/llm/test/generate-object.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, test } from "bun:test"
+import { Effect, Schema } from "effect"
+import { LLM } from "../src"
+import * as OpenAIChat from "../src/protocols/openai-chat"
+import { Tool, toDefinitions } from "../src/tool"
+import { it } from "./lib/effect"
+import { dynamicResponse } from "./lib/http"
+import { finishChunk, toolCallChunk } from "./lib/openai-chunks"
+import { sseEvents } from "./lib/sse"
+
+type OpenAIChatBody = {
+  readonly tool_choice?: unknown
+  readonly tools?: ReadonlyArray<{
+    readonly function: {
+      readonly parameters: unknown
+    }
+  }>
+}
+
+const model = OpenAIChat.model({
+  id: "gpt-4o-mini",
+  baseURL: "https://api.openai.test/v1/",
+  headers: { authorization: "Bearer test" },
+})
+
+const Json = Schema.fromJsonString(Schema.Unknown)
+const decodeJson = Schema.decodeUnknownSync(Json)
+const decodeBody = (text: string): OpenAIChatBody => decodeJson(text) as OpenAIChatBody
+
+describe("Tool.make (dynamic JSON Schema)", () => {
+  test("forwards JSON Schema and description through toDefinitions", () => {
+    const jsonSchema = {
+      type: "object" as const,
+      properties: { city: { type: "string" } },
+      required: ["city"],
+    }
+    const lookup = Tool.make({
+      description: "Look up something",
+      jsonSchema,
+      execute: () => Effect.succeed({ ok: true }),
+    })
+    const [definition] = toDefinitions({ lookup })
+    expect(definition?.name).toBe("lookup")
+    expect(definition?.description).toBe("Look up something")
+    expect(definition?.inputSchema).toEqual(jsonSchema)
+  })
+
+  test("execute receives the raw input untouched", async () => {
+    const seen: unknown[] = []
+    const tool = Tool.make({
+      description: "echo",
+      jsonSchema: { type: "object" },
+      execute: (params) =>
+        Effect.sync(() => {
+          seen.push(params)
+          return { ok: true }
+        }),
+    })
+    const result = await Effect.runPromise(tool.execute({ hello: "world" }))
+    expect(seen).toEqual([{ hello: "world" }])
+    expect(result).toEqual({ ok: true })
+  })
+})
+
+describe("LLM.generateObject", () => {
+  it.effect("forces a synthetic tool call and decodes the input", () =>
+    Effect.gen(function* () {
+      const bodies: OpenAIChatBody[] = []
+      const layer = dynamicResponse((input) =>
+        Effect.sync(() => {
+          bodies.push(decodeBody(input.text))
+          return input.respond(
+            sseEvents(
+              toolCallChunk("call_1", "generate_object", '{"city":"Paris","temp":22}'),
+              finishChunk("tool_calls"),
+            ),
+            { headers: { "content-type": "text/event-stream" } },
+          )
+        }),
+      )
+
+      const response = yield* LLM.generateObject({
+        model,
+        prompt: "Return a structured weather report.",
+        schema: Schema.Struct({ city: Schema.String, temp: Schema.Number }),
+      }).pipe(Effect.provide(layer))
+
+      expect(response.object).toEqual({ city: "Paris", temp: 22 })
+      expect(response.response.toolCalls).toHaveLength(1)
+      expect(bodies).toHaveLength(1)
+      expect(bodies[0].tool_choice).toEqual({ type: "function", function: { name: "generate_object" } })
+      const tool = bodies[0].tools?.[0]
+      expect(bodies[0].tools).toHaveLength(1)
+      expect(tool).toMatchObject({
+        type: "function",
+        function: { name: "generate_object" },
+      })
+      const params = tool?.function.parameters as {
+        readonly type?: unknown
+        readonly required?: unknown
+        readonly properties?: Record<string, unknown>
+      }
+      expect(params.type).toBe("object")
+      expect(params.required).toEqual(["city", "temp"])
+      expect(params.properties?.city).toMatchObject({ type: "string" })
+      expect(params.properties?.temp).toBeDefined()
+    }),
+  )
+
+  it.effect("accepts a raw JSON Schema and returns the input untouched", () =>
+    Effect.gen(function* () {
+      const bodies: OpenAIChatBody[] = []
+      const layer = dynamicResponse((input) =>
+        Effect.sync(() => {
+          bodies.push(decodeBody(input.text))
+          return input.respond(
+            sseEvents(toolCallChunk("call_1", "generate_object", '{"name":"Ada","age":30}'), finishChunk("tool_calls")),
+            { headers: { "content-type": "text/event-stream" } },
+          )
+        }),
+      )
+
+      const response = yield* LLM.generateObject({
+        model,
+        prompt: "Extract the user.",
+        jsonSchema: {
+          type: "object",
+          properties: { name: { type: "string" }, age: { type: "number" } },
+          required: ["name", "age"],
+        },
+      }).pipe(Effect.provide(layer))
+
+      expect(response.object).toEqual({ name: "Ada", age: 30 })
+      expect(bodies[0].tools?.[0]?.function.parameters).toEqual({
+        type: "object",
+        properties: { name: { type: "string" }, age: { type: "number" } },
+        required: ["name", "age"],
+      })
+    }),
+  )
+
+  it.effect("fails when the model does not call the synthetic tool", () =>
+    Effect.gen(function* () {
+      const layer = dynamicResponse((input) =>
+        Effect.sync(() =>
+          input.respond(sseEvents({ id: "x", choices: [{ delta: { content: "no thanks" }, finish_reason: "stop" }] }), {
+            headers: { "content-type": "text/event-stream" },
+          }),
+        ),
+      )
+
+      const exit = yield* LLM.generateObject({
+        model,
+        prompt: "Return a structured value.",
+        schema: Schema.Struct({ value: Schema.Number }),
+      }).pipe(Effect.provide(layer), Effect.exit)
+
+      expect(exit._tag).toBe("Failure")
+    }),
+  )
+
+  it.effect("fails with a decode error when the tool input does not match the schema", () =>
+    Effect.gen(function* () {
+      const layer = dynamicResponse((input) =>
+        Effect.sync(() =>
+          input.respond(
+            sseEvents(toolCallChunk("call_1", "generate_object", '{"value":"not-a-number"}'), finishChunk("tool_calls")),
+            { headers: { "content-type": "text/event-stream" } },
+          ),
+        ),
+      )
+
+      const exit = yield* LLM.generateObject({
+        model,
+        prompt: "Return a structured value.",
+        schema: Schema.Struct({ value: Schema.Number }),
+      }).pipe(Effect.provide(layer), Effect.exit)
+
+      expect(exit._tag).toBe("Failure")
+    }),
+  )
+})

packages/llm/test/lib/effect.ts

@@ -0,0 +1,50 @@
+import { test, type TestOptions } from "bun:test"
+import { Cause, Effect, Exit, Layer } from "effect"
+import type * as Scope from "effect/Scope"
+import * as TestClock from "effect/testing/TestClock"
+import * as TestConsole from "effect/testing/TestConsole"
+
+type Body<A, E, R> = Effect.Effect<A, E, R> | (() => Effect.Effect<A, E, R>)
+
+const body = <A, E, R>(value: Body<A, E, R>) => Effect.suspend(() => (typeof value === "function" ? value() : value))
+
+const run = <A, E, R, E2>(value: Body<A, E, R | Scope.Scope>, layer: Layer.Layer<R, E2>) =>
+  Effect.gen(function* () {
+    const exit = yield* body(value).pipe(Effect.scoped, Effect.provide(layer), Effect.exit)
+    if (Exit.isFailure(exit)) {
+      for (const err of Cause.prettyErrors(exit.cause)) {
+        yield* Effect.logError(err)
+      }
+    }
+    return yield* exit
+  }).pipe(Effect.runPromise)
+
+const make = <R, E>(testLayer: Layer.Layer<R, E>, liveLayer: Layer.Layer<R, E>) => {
+  const effect = <A, E2>(name: string, value: Body<A, E2, R | Scope.Scope>, opts?: number | TestOptions) =>
+    test(name, () => run(value, testLayer), opts)
+
+  effect.only = <A, E2>(name: string, value: Body<A, E2, R | Scope.Scope>, opts?: number | TestOptions) =>
+    test.only(name, () => run(value, testLayer), opts)
+
+  effect.skip = <A, E2>(name: string, value: Body<A, E2, R | Scope.Scope>, opts?: number | TestOptions) =>
+    test.skip(name, () => run(value, testLayer), opts)
+
+  const live = <A, E2>(name: string, value: Body<A, E2, R | Scope.Scope>, opts?: number | TestOptions) =>
+    test(name, () => run(value, liveLayer), opts)
+
+  live.only = <A, E2>(name: string, value: Body<A, E2, R | Scope.Scope>, opts?: number | TestOptions) =>
+    test.only(name, () => run(value, liveLayer), opts)
+
+  live.skip = <A, E2>(name: string, value: Body<A, E2, R | Scope.Scope>, opts?: number | TestOptions) =>
+    test.skip(name, () => run(value, liveLayer), opts)
+
+  return { effect, live }
+}
+
+const testEnv = Layer.mergeAll(TestConsole.layer, TestClock.layer())
+const liveEnv = TestConsole.layer
+
+export const it = make(testEnv, liveEnv)
+
+export const testEffect = <R, E>(layer: Layer.Layer<R, E>) =>
+  make(Layer.provideMerge(layer, testEnv), Layer.provideMerge(layer, liveEnv))

packages/llm/test/lib/http.ts

@@ -0,0 +1,96 @@
+import { Effect, Layer, Ref } from "effect"
+import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
+import { LLMClient, RequestExecutor } from "../../src/route"
+import type { Service as LLMClientService } from "../../src/route/client"
+import type { Service as RequestExecutorService } from "../../src/route/executor"
+
+export type HandlerInput = {
+  readonly request: HttpClientRequest.HttpClientRequest
+  readonly text: string
+  readonly respond: (
+    body: ConstructorParameters<typeof Response>[0],
+    init?: ResponseInit,
+  ) => HttpClientResponse.HttpClientResponse
+}
+
+export type Handler = (input: HandlerInput) => Effect.Effect<HttpClientResponse.HttpClientResponse>
+
+const handlerLayer = (handler: Handler): Layer.Layer<HttpClient.HttpClient> =>
+  Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) =>
+      Effect.gen(function* () {
+        const web = yield* HttpClientRequest.toWeb(request).pipe(Effect.orDie)
+        const text = yield* Effect.promise(() => web.text())
+        return yield* handler({
+          request,
+          text,
+          respond: (body, init) => HttpClientResponse.fromWeb(request, new Response(body, init)),
+        })
+      }),
+    ),
+  )
+
+export type RuntimeEnv = RequestExecutorService | LLMClientService
+
+export const runtimeLayer = (layer: Layer.Layer<HttpClient.HttpClient>): Layer.Layer<RuntimeEnv> => {
+  const requestExecutorLayer = RequestExecutor.layer.pipe(Layer.provide(layer))
+  const llmClientLayer = LLMClient.layer.pipe(Layer.provide(requestExecutorLayer))
+  return Layer.mergeAll(requestExecutorLayer, llmClientLayer)
+}
+
+const SSE_HEADERS = { "content-type": "text/event-stream" } as const
+
+/**
+ * Layer that returns a single fixed response body. Use for stream-parser
+ * fixture tests where the request shape is irrelevant. The body type widens
+ * to whatever `Response` accepts so binary fixtures (`Uint8Array`,
+ * `ReadableStream`, etc.) flow through without casts.
+ */
+export const fixedResponse = (
+  body: ConstructorParameters<typeof Response>[0],
+  init: ResponseInit = { headers: SSE_HEADERS },
+) => runtimeLayer(handlerLayer((input) => Effect.succeed(input.respond(body, init))))
+
+/**
+ * Layer that builds a response per request. Useful for echo servers.
+ */
+export const dynamicResponse = (handler: Handler) => runtimeLayer(handlerLayer(handler))
+
+/**
+ * Layer that emits the supplied SSE chunks and then aborts mid-stream. Used to
+ * exercise transport errors that surface during parsing.
+ */
+export const truncatedStream = (chunks: ReadonlyArray<string>) =>
+  dynamicResponse((input) =>
+    Effect.sync(() => {
+      const encoder = new TextEncoder()
+      const stream = new ReadableStream({
+        start(controller) {
+          for (const chunk of chunks) controller.enqueue(encoder.encode(chunk))
+          controller.error(new Error("connection reset"))
+        },
+      })
+      return input.respond(stream, { headers: SSE_HEADERS })
+    }),
+  )
+
+/**
+ * Layer that returns successive bodies on each request. Useful for scripting
+ * multi-step model exchanges (e.g. tool-call loops). The last body in the
+ * array is reused if the test makes more requests than scripted.
+ */
+export const scriptedResponses = (bodies: ReadonlyArray<string>, init: ResponseInit = { headers: SSE_HEADERS }) => {
+  if (bodies.length === 0) throw new Error("scriptedResponses requires at least one body")
+  return Layer.unwrap(
+    Effect.gen(function* () {
+      const cursor = yield* Ref.make(0)
+      return dynamicResponse((input) =>
+        Effect.gen(function* () {
+          const index = yield* Ref.getAndUpdate(cursor, (n) => n + 1)
+          return input.respond(bodies[index] ?? bodies[bodies.length - 1], init)
+        }),
+      )
+    }),
+  )
+}

packages/llm/test/lib/openai-chunks.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared chunk shapes for OpenAI Chat / OpenAI-compatible Chat fixture tests.
+ * Multiple test files build the same `{ id, choices: [{ delta, finish_reason }], usage }`
+ * envelope; consolidating here keeps tool-call event shapes consistent.
+ */
+
+const FIXTURE_ID = "chatcmpl_fixture"
+
+export const deltaChunk = (delta: object, finishReason: string | null = null) => ({
+  id: FIXTURE_ID,
+  choices: [{ delta, finish_reason: finishReason }],
+  usage: null,
+})
+
+export const usageChunk = (usage: object) => ({
+  id: FIXTURE_ID,
+  choices: [],
+  usage,
+})
+
+export const finishChunk = (reason: string) => deltaChunk({}, reason)
+
+export const toolCallChunk = (id: string, name: string, args: string, index = 0) =>
+  deltaChunk({
+    role: "assistant",
+    tool_calls: [{ index, id, function: { name, arguments: args } }],
+  })

packages/llm/test/lib/sse.ts

@@ -0,0 +1,17 @@
+/**
+ * Helpers for building deterministic SSE bodies in tests.
+ *
+ * Inline template-literal SSE strings are hard to write and review when chunks
+ * contain JSON; this helper accepts plain values and serializes them, so test
+ * authors only think about the chunk shapes, not the wire format.
+ */
+export const sseEvents = (...chunks: ReadonlyArray<unknown>): string =>
+  `${chunks.map(formatChunk).join("")}data: [DONE]\n\n`
+
+const formatChunk = (chunk: unknown) => `data: ${typeof chunk === "string" ? chunk : JSON.stringify(chunk)}\n\n`
+
+/**
+ * Build an SSE body from already-serialized strings (used when the chunk shape
+ * itself is part of what's being tested, e.g. malformed chunks).
+ */
+export const sseRaw = (...lines: ReadonlyArray<string>): string => lines.map((line) => `${line}\n\n`).join("")

packages/llm/test/lib/tool-runtime.ts

@@ -0,0 +1,9 @@
+import { Stream } from "effect"
+import { LLMClient } from "../../src/route"
+import type { Tools } from "../../src/tool"
+import type { RunOptions } from "../../src/tool-runtime"
+
+type CompatRunOptions<T extends Tools> = RunOptions<T> & { readonly maxSteps?: number }
+
+export const runTools = <T extends Tools>(options: CompatRunOptions<T>) =>
+  LLMClient.stream({ ...options, stopWhen: options.stopWhen ?? LLMClient.stepCountIs(options.maxSteps ?? 10) })

packages/llm/test/llm.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, test } from "bun:test"
+import { LLM, LLMResponse } from "../src"
+import { LLMRequest, Message, ModelRef, ToolChoice, ToolDefinition } from "../src/schema"
+
+describe("llm constructors", () => {
+  test("builds canonical schema classes from ergonomic input", () => {
+    const request = LLM.request({
+      id: "req_1",
+      model: LLM.model({ id: "fake-model", provider: "fake", route: "openai-chat", baseURL: "https://fake.local" }),
+      system: "You are concise.",
+      prompt: "Say hello.",
+    })
+
+    expect(request).toBeInstanceOf(LLMRequest)
+    expect(request.model).toBeInstanceOf(ModelRef)
+    expect(request.messages[0]).toBeInstanceOf(Message)
+    expect(request.system).toEqual([{ type: "text", text: "You are concise." }])
+    expect(request.messages[0]?.content).toEqual([{ type: "text", text: "Say hello." }])
+    expect(request.generation).toBeUndefined()
+    expect(request.tools).toEqual([])
+  })
+
+  test("updates requests without spreading schema class instances", () => {
+    const base = LLM.request({
+      id: "req_1",
+      model: LLM.model({ id: "fake-model", provider: "fake", route: "openai-chat", baseURL: "https://fake.local" }),
+      prompt: "Say hello.",
+    })
+    const updated = LLM.updateRequest(base, {
+      generation: { maxTokens: 20 },
+      messages: [...base.messages, LLM.assistant("Hi.")],
+    })
+
+    expect(updated).toBeInstanceOf(LLMRequest)
+    expect(updated.id).toBe("req_1")
+    expect(updated.model).toEqual(base.model)
+    expect(updated.generation).toEqual({ maxTokens: 20 })
+    expect(updated.messages.map((message) => message.role)).toEqual(["user", "assistant"])
+  })
+
+  test("keeps request options separate from model defaults", () => {
+    const request = LLM.request({
+      model: LLM.model({
+        id: "fake-model",
+        provider: "fake",
+        route: "openai-chat",
+        baseURL: "https://fake.local",
+        generation: { maxTokens: 100, temperature: 1 },
+        providerOptions: { openai: { store: false, metadata: { model: true } } },
+        http: { body: { metadata: { model: true } }, headers: { "x-shared": "model" }, query: { model: "1" } },
+      }),
+      prompt: "Say hello.",
+      generation: { temperature: 0 },
+      providerOptions: { openai: { store: true, metadata: { request: true } } },
+      http: { body: { metadata: { request: true } }, headers: { "x-shared": "request" }, query: { request: "1" } },
+    })
+
+    expect(request.generation).toEqual({ temperature: 0 })
+    expect(request.providerOptions).toEqual({ openai: { store: true, metadata: { request: true } } })
+    expect(request.http).toEqual({
+      body: { metadata: { request: true } },
+      headers: { "x-shared": "request" },
+      query: { request: "1" },
+    })
+  })
+
+  test("updates canonical requests from the request datatype", () => {
+    const base = LLM.request({
+      id: "req_1",
+      model: LLM.model({ id: "fake-model", provider: "fake", route: "openai-chat", baseURL: "https://fake.local" }),
+      prompt: "Say hello.",
+    })
+    const updated = LLMRequest.update(base, { messages: [...base.messages, LLM.assistant("Hi.")] })
+
+    expect(updated).toBeInstanceOf(LLMRequest)
+    expect(updated.id).toBe("req_1")
+    expect(LLMRequest.input(updated).id).toBe("req_1")
+    expect(updated.messages.map((message) => message.role)).toEqual(["user", "assistant"])
+    expect(LLMRequest.update(updated, {})).toBe(updated)
+  })
+
+  test("updates canonical models from the model datatype", () => {
+    const base = LLM.model({ id: "fake-model", provider: "fake", route: "openai-chat", baseURL: "https://fake.local" })
+    const updated = ModelRef.update(base, { route: "openai-responses" })
+
+    expect(updated).toBeInstanceOf(ModelRef)
+    expect(String(updated.id)).toBe("fake-model")
+    expect(updated.route).toBe("openai-responses")
+    expect(String(ModelRef.input(updated).provider)).toBe("fake")
+    expect(ModelRef.update(updated, {})).toBe(updated)
+  })
+
+  test("builds tool choices from names and tools", () => {
+    const tool = LLM.toolDefinition({ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } })
+
+    expect(tool).toBeInstanceOf(ToolDefinition)
+    expect(LLM.toolChoice("lookup")).toEqual(new ToolChoice({ type: "tool", name: "lookup" }))
+    expect(LLM.toolChoiceName("required")).toEqual(new ToolChoice({ type: "tool", name: "required" }))
+    expect(LLM.toolChoice(tool)).toEqual(new ToolChoice({ type: "tool", name: "lookup" }))
+  })
+
+  test("builds tool choice modes from reserved strings", () => {
+    expect(LLM.toolChoice("auto")).toEqual(new ToolChoice({ type: "auto" }))
+    expect(LLM.toolChoice("none")).toEqual(new ToolChoice({ type: "none" }))
+    expect(LLM.toolChoice("required")).toEqual(new ToolChoice({ type: "required" }))
+    expect(
+      LLM.request({
+        model: LLM.model({ id: "fake-model", provider: "fake", route: "openai-chat", baseURL: "https://fake.local" }),
+        prompt: "Use tools if needed.",
+        toolChoice: "required",
+      }).toolChoice,
+    ).toEqual(new ToolChoice({ type: "required" }))
+  })
+
+  test("builds assistant tool calls and tool result messages", () => {
+    const call = LLM.toolCall({ id: "call_1", name: "lookup", input: { query: "weather" } })
+    const result = LLM.toolResult({ id: "call_1", name: "lookup", result: { temperature: 72 } })
+
+    expect(LLM.assistant([call]).content).toEqual([call])
+    expect(LLM.toolMessage(result).content).toEqual([
+      { type: "tool-result", id: "call_1", name: "lookup", result: { type: "json", value: { temperature: 72 } } },
+    ])
+  })
+
+  test("extracts output text from response events", () => {
+    expect(
+      LLMResponse.text({
+        events: [
+          { type: "text-delta", text: "hi" },
+          { type: "request-finish", reason: "stop" },
+        ],
+      }),
+    ).toBe("hi")
+  })
+})

packages/llm/test/provider.types.ts

@@ -0,0 +1,39 @@
+import { Provider } from "../src/provider"
+import { ProviderID, type ModelRef } from "../src/schema"
+
+declare const model: (id: string) => ModelRef
+declare const requiredModel: (id: string, options: { readonly baseURL: string }) => ModelRef
+declare const chat: (id: string, options: { readonly apiKey: string }) => ModelRef
+
+Provider.make({
+  id: ProviderID.make("example"),
+  model,
+})
+
+Provider.make({
+  id: ProviderID.make("bad"),
+  model,
+  // @ts-expect-error provider definitions should not grow accidental top-level fields.
+  routes: [],
+})
+
+const requiredProvider = Provider.make({
+  id: ProviderID.make("required"),
+  model: requiredModel,
+})
+
+requiredProvider.model("custom", { baseURL: "https://example.com/v1" })
+
+// @ts-expect-error Provider.make preserves required model options.
+requiredProvider.model("custom")
+
+const multiApiProvider = Provider.make({
+  id: ProviderID.make("multi-api"),
+  model,
+  apis: { chat },
+})
+
+multiApiProvider.apis.chat("chat-model", { apiKey: "key" })
+
+// @ts-expect-error Provider.make preserves API-specific option types.
+multiApiProvider.apis.chat("chat-model")

packages/llm/test/provider/anthropic-messages.recorded.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { LLM, LLMError } from "../../src"
+import { LLMClient } from "../../src/route"
+import * as AnthropicMessages from "../../src/protocols/anthropic-messages"
+import { weatherToolName } from "../recorded-scenarios"
+import { recordedTests } from "../recorded-test"
+
+const model = AnthropicMessages.model({
+  id: "claude-haiku-4-5-20251001",
+  apiKey: process.env.ANTHROPIC_API_KEY ?? "fixture",
+})
+
+const malformedToolOrderRequest = LLM.request({
+  id: "recorded_anthropic_malformed_tool_order",
+  model,
+  messages: [
+    LLM.assistant([
+      LLM.toolCall({ id: "call_1", name: weatherToolName, input: { city: "Paris" } }),
+      { type: "text", text: "I will check the weather." },
+    ]),
+    LLM.toolMessage({ id: "call_1", name: weatherToolName, result: { temperature: "72F" } }),
+    LLM.user("Use that result to answer briefly."),
+  ],
+  tools: [{ name: weatherToolName, description: "Get weather", inputSchema: { type: "object", properties: {} } }],
+})
+
+const recorded = recordedTests({
+  prefix: "anthropic-messages",
+  provider: "anthropic",
+  protocol: "anthropic-messages",
+  requires: ["ANTHROPIC_API_KEY"],
+  options: { requestHeaders: ["content-type", "anthropic-version"] },
+})
+
+describe("Anthropic Messages sad-path recorded", () => {
+  recorded.effect.with("rejects malformed assistant tool order", { tags: ["tool", "sad-path"] }, () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.generate(malformedToolOrderRequest).pipe(Effect.flip)
+
+      expect(error).toBeInstanceOf(LLMError)
+      expect(error.reason).toMatchObject({ _tag: "InvalidRequest" })
+      expect(error.message).toContain("HTTP 400")
+    }),
+  )
+})

packages/llm/test/provider/anthropic-messages.test.ts

@@ -0,0 +1,377 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { CacheHint, LLM, LLMError } from "../../src"
+import { LLMClient } from "../../src/route"
+import * as AnthropicMessages from "../../src/protocols/anthropic-messages"
+import { it } from "../lib/effect"
+import { fixedResponse } from "../lib/http"
+import { sseEvents } from "../lib/sse"
+
+const model = AnthropicMessages.model({
+  id: "claude-sonnet-4-5",
+  baseURL: "https://api.anthropic.test/v1/",
+  headers: { "x-api-key": "test" },
+})
+
+const request = LLM.request({
+  id: "req_1",
+  model,
+  system: { type: "text", text: "You are concise.", cache: new CacheHint({ type: "ephemeral" }) },
+  prompt: "Say hello.",
+  generation: { maxTokens: 20, temperature: 0 },
+})
+
+describe("Anthropic Messages route", () => {
+  it.effect("prepares Anthropic Messages target", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(request)
+
+      expect(prepared.body).toEqual({
+        model: "claude-sonnet-4-5",
+        system: [{ type: "text", text: "You are concise.", cache_control: { type: "ephemeral" } }],
+        messages: [{ role: "user", content: [{ type: "text", text: "Say hello." }] }],
+        stream: true,
+        max_tokens: 20,
+        temperature: 0,
+      })
+    }),
+  )
+
+  it.effect("prepares tool call and tool result messages", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_tool_result",
+          model,
+          messages: [
+            LLM.user("What is the weather?"),
+            LLM.assistant([LLM.toolCall({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
+            LLM.toolMessage({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
+          ],
+        }),
+      )
+
+      expect(prepared.body).toEqual({
+        model: "claude-sonnet-4-5",
+        messages: [
+          { role: "user", content: [{ type: "text", text: "What is the weather?" }] },
+          {
+            role: "assistant",
+            content: [{ type: "tool_use", id: "call_1", name: "lookup", input: { query: "weather" } }],
+          },
+          { role: "user", content: [{ type: "tool_result", tool_use_id: "call_1", content: '{"forecast":"sunny"}' }] },
+        ],
+        stream: true,
+        max_tokens: 4096,
+      })
+    }),
+  )
+
+  it.effect("lowers preserved Anthropic reasoning signature metadata", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model,
+          messages: [
+            LLM.assistant([
+              { type: "reasoning", text: "thinking", providerMetadata: { anthropic: { signature: "sig_1" } } },
+            ]),
+          ],
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        messages: [{ role: "assistant", content: [{ type: "thinking", thinking: "thinking", signature: "sig_1" }] }],
+      })
+    }),
+  )
+
+  it.effect("parses text, reasoning, and usage stream fixtures", () =>
+    Effect.gen(function* () {
+      const body = sseEvents(
+        { type: "message_start", message: { usage: { input_tokens: 5, cache_read_input_tokens: 1 } } },
+        { type: "content_block_start", index: 0, content_block: { type: "text", text: "" } },
+        { type: "content_block_delta", index: 0, delta: { type: "text_delta", text: "Hello" } },
+        { type: "content_block_delta", index: 0, delta: { type: "text_delta", text: "!" } },
+        { type: "content_block_stop", index: 0 },
+        { type: "content_block_start", index: 1, content_block: { type: "thinking", thinking: "" } },
+        { type: "content_block_delta", index: 1, delta: { type: "thinking_delta", thinking: "thinking" } },
+        { type: "content_block_delta", index: 1, delta: { type: "signature_delta", signature: "sig_1" } },
+        { type: "content_block_stop", index: 1 },
+        {
+          type: "message_delta",
+          delta: { stop_reason: "end_turn", stop_sequence: "\n\nHuman:" },
+          usage: { output_tokens: 2 },
+        },
+        { type: "message_stop" },
+      )
+      const response = yield* LLMClient.generate(request).pipe(Effect.provide(fixedResponse(body)))
+
+      expect(response.text).toBe("Hello!")
+      expect(response.reasoning).toBe("thinking")
+      expect(response.usage).toMatchObject({
+        inputTokens: 5,
+        outputTokens: 2,
+        cacheReadInputTokens: 1,
+        totalTokens: 7,
+      })
+      expect(response.events.find((event) => event.type === "reasoning-delta" && event.text === "")).toMatchObject({
+        providerMetadata: { anthropic: { signature: "sig_1" } },
+      })
+      expect(response.events.at(-1)).toMatchObject({
+        type: "request-finish",
+        reason: "stop",
+        providerMetadata: { anthropic: { stopSequence: "\n\nHuman:" } },
+      })
+    }),
+  )
+
+  it.effect("assembles streamed tool call input", () =>
+    Effect.gen(function* () {
+      const body = sseEvents(
+        { type: "message_start", message: { usage: { input_tokens: 5 } } },
+        { type: "content_block_start", index: 0, content_block: { type: "tool_use", id: "call_1", name: "lookup" } },
+        { type: "content_block_delta", index: 0, delta: { type: "input_json_delta", partial_json: '{"query"' } },
+        { type: "content_block_delta", index: 0, delta: { type: "input_json_delta", partial_json: ':"weather"}' } },
+        { type: "content_block_stop", index: 0 },
+        { type: "message_delta", delta: { stop_reason: "tool_use" }, usage: { output_tokens: 1 } },
+      )
+      const response = yield* LLMClient.generate(
+        LLM.updateRequest(request, {
+          tools: [{ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } }],
+        }),
+      ).pipe(Effect.provide(fixedResponse(body)))
+
+      expect(response.toolCalls).toEqual([
+        { type: "tool-call", id: "call_1", name: "lookup", input: { query: "weather" } },
+      ])
+      expect(response.events).toEqual([
+        { type: "tool-input-delta", id: "call_1", name: "lookup", text: '{"query"' },
+        { type: "tool-input-delta", id: "call_1", name: "lookup", text: ':"weather"}' },
+        { type: "tool-call", id: "call_1", name: "lookup", input: { query: "weather" } },
+        {
+          type: "request-finish",
+          reason: "tool-calls",
+          usage: { inputTokens: 5, outputTokens: 1, totalTokens: 6, native: { input_tokens: 5, output_tokens: 1 } },
+        },
+      ])
+    }),
+  )
+
+  it.effect("emits provider-error events for mid-stream provider errors", () =>
+    Effect.gen(function* () {
+      const response = yield* LLMClient.generate(request).pipe(
+        Effect.provide(
+          fixedResponse(sseEvents({ type: "error", error: { type: "overloaded_error", message: "Overloaded" } })),
+        ),
+      )
+
+      expect(response.events).toEqual([{ type: "provider-error", message: "Overloaded" }])
+    }),
+  )
+
+  it.effect("fails HTTP provider errors before stream parsing", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.generate(request).pipe(
+        Effect.provide(
+          fixedResponse('{"type":"error","error":{"type":"invalid_request_error","message":"Bad request"}}', {
+            status: 400,
+            headers: { "content-type": "application/json" },
+          }),
+        ),
+        Effect.flip,
+      )
+
+      expect(error).toBeInstanceOf(LLMError)
+      expect(error.reason).toMatchObject({ _tag: "InvalidRequest" })
+      expect(error.message).toContain("HTTP 400")
+    }),
+  )
+
+  it.effect("decodes server_tool_use + web_search_tool_result as provider-executed events", () =>
+    Effect.gen(function* () {
+      const body = sseEvents(
+        { type: "message_start", message: { usage: { input_tokens: 5 } } },
+        {
+          type: "content_block_start",
+          index: 0,
+          content_block: { type: "server_tool_use", id: "srvtoolu_abc", name: "web_search" },
+        },
+        {
+          type: "content_block_delta",
+          index: 0,
+          delta: { type: "input_json_delta", partial_json: '{"query":"effect 4"}' },
+        },
+        { type: "content_block_stop", index: 0 },
+        {
+          type: "content_block_start",
+          index: 1,
+          content_block: {
+            type: "web_search_tool_result",
+            tool_use_id: "srvtoolu_abc",
+            content: [{ type: "web_search_result", url: "https://example.com", title: "Example" }],
+          },
+        },
+        { type: "content_block_stop", index: 1 },
+        { type: "content_block_start", index: 2, content_block: { type: "text", text: "" } },
+        { type: "content_block_delta", index: 2, delta: { type: "text_delta", text: "Found it." } },
+        { type: "content_block_stop", index: 2 },
+        { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 8 } },
+      )
+      const response = yield* LLMClient.generate(
+        LLM.updateRequest(request, {
+          tools: [{ name: "web_search", description: "Web search", inputSchema: { type: "object" } }],
+        }),
+      ).pipe(Effect.provide(fixedResponse(body)))
+
+      const toolCall = response.events.find((event) => event.type === "tool-call")
+      expect(toolCall).toEqual({
+        type: "tool-call",
+        id: "srvtoolu_abc",
+        name: "web_search",
+        input: { query: "effect 4" },
+        providerExecuted: true,
+      })
+      const toolResult = response.events.find((event) => event.type === "tool-result")
+      expect(toolResult).toEqual({
+        type: "tool-result",
+        id: "srvtoolu_abc",
+        name: "web_search",
+        result: { type: "json", value: [{ type: "web_search_result", url: "https://example.com", title: "Example" }] },
+        providerExecuted: true,
+        providerMetadata: { anthropic: { blockType: "web_search_tool_result" } },
+      })
+      expect(response.text).toBe("Found it.")
+      expect(response.events.at(-1)).toMatchObject({ type: "request-finish", reason: "stop" })
+    }),
+  )
+
+  it.effect("decodes web_search_tool_result_error as provider-executed error result", () =>
+    Effect.gen(function* () {
+      const body = sseEvents(
+        { type: "message_start", message: { usage: { input_tokens: 5 } } },
+        {
+          type: "content_block_start",
+          index: 0,
+          content_block: { type: "server_tool_use", id: "srvtoolu_x", name: "web_search" },
+        },
+        { type: "content_block_delta", index: 0, delta: { type: "input_json_delta", partial_json: '{"query":"q"}' } },
+        { type: "content_block_stop", index: 0 },
+        {
+          type: "content_block_start",
+          index: 1,
+          content_block: {
+            type: "web_search_tool_result",
+            tool_use_id: "srvtoolu_x",
+            content: { type: "web_search_tool_result_error", error_code: "max_uses_exceeded" },
+          },
+        },
+        { type: "content_block_stop", index: 1 },
+        { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 1 } },
+      )
+      const response = yield* LLMClient.generate(
+        LLM.updateRequest(request, {
+          tools: [{ name: "web_search", description: "Web search", inputSchema: { type: "object" } }],
+        }),
+      ).pipe(Effect.provide(fixedResponse(body)))
+
+      const toolResult = response.events.find((event) => event.type === "tool-result")
+      expect(toolResult).toMatchObject({
+        type: "tool-result",
+        id: "srvtoolu_x",
+        name: "web_search",
+        result: { type: "error" },
+        providerExecuted: true,
+      })
+    }),
+  )
+
+  it.effect("round-trips provider-executed assistant content into server tool blocks", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_round_trip",
+          model,
+          messages: [
+            LLM.user("Search for something."),
+            LLM.assistant([
+              {
+                type: "tool-call",
+                id: "srvtoolu_abc",
+                name: "web_search",
+                input: { query: "effect 4" },
+                providerExecuted: true,
+              },
+              {
+                type: "tool-result",
+                id: "srvtoolu_abc",
+                name: "web_search",
+                result: { type: "json", value: [{ url: "https://example.com" }] },
+                providerExecuted: true,
+              },
+              { type: "text", text: "Found it." },
+            ]),
+            LLM.user("Thanks."),
+          ],
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        messages: [
+          { role: "user", content: [{ type: "text", text: "Search for something." }] },
+          {
+            role: "assistant",
+            content: [
+              { type: "server_tool_use", id: "srvtoolu_abc", name: "web_search", input: { query: "effect 4" } },
+              {
+                type: "web_search_tool_result",
+                tool_use_id: "srvtoolu_abc",
+                content: [{ url: "https://example.com" }],
+              },
+              { type: "text", text: "Found it." },
+            ],
+          },
+          { role: "user", content: [{ type: "text", text: "Thanks." }] },
+        ],
+      })
+    }),
+  )
+
+  it.effect("rejects round-trip for unknown server tool names", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_unknown_server_tool",
+          model,
+          messages: [
+            LLM.assistant([
+              {
+                type: "tool-result",
+                id: "srvtoolu_abc",
+                name: "future_server_tool",
+                result: { type: "json", value: {} },
+                providerExecuted: true,
+              },
+            ]),
+          ],
+        }),
+      ).pipe(Effect.flip)
+
+      expect(error.message).toContain("future_server_tool")
+    }),
+  )
+
+  it.effect("rejects unsupported user media content", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_media",
+          model,
+          messages: [LLM.user({ type: "media", mediaType: "image/png", data: "AAECAw==" })],
+        }),
+      ).pipe(Effect.flip)
+
+      expect(error.message).toContain("Anthropic Messages user messages only support text content for now")
+    }),
+  )
+})

packages/llm/test/provider/bedrock-converse.test.ts

@@ -0,0 +1,533 @@
+import { EventStreamCodec } from "@smithy/eventstream-codec"
+import { fromUtf8, toUtf8 } from "@smithy/util-utf8"
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { CacheHint, LLM } from "../../src"
+import { LLMClient } from "../../src/route"
+import * as BedrockConverse from "../../src/protocols/bedrock-converse"
+import { it } from "../lib/effect"
+import { fixedResponse } from "../lib/http"
+import {
+  eventSummary,
+  expectWeatherToolLoop,
+  runWeatherToolLoop,
+  weatherTool,
+  weatherToolLoopRequest,
+  weatherToolName,
+} from "../recorded-scenarios"
+import { recordedTests } from "../recorded-test"
+
+const codec = new EventStreamCodec(toUtf8, fromUtf8)
+const utf8Encoder = new TextEncoder()
+
+// Build a single AWS event-stream frame for a Converse stream event. Each
+// frame carries `:message-type=event` + `:event-type=<name>` headers and a
+// JSON payload body.
+const eventFrame = (type: string, payload: object) =>
+  codec.encode({
+    headers: {
+      ":message-type": { type: "string", value: "event" },
+      ":event-type": { type: "string", value: type },
+      ":content-type": { type: "string", value: "application/json" },
+    },
+    body: utf8Encoder.encode(JSON.stringify(payload)),
+  })
+
+const concat = (frames: ReadonlyArray<Uint8Array>) => {
+  const total = frames.reduce((sum, frame) => sum + frame.length, 0)
+  const out = new Uint8Array(total)
+  let offset = 0
+  for (const frame of frames) {
+    out.set(frame, offset)
+    offset += frame.length
+  }
+  return out
+}
+
+const eventStreamBody = (...payloads: ReadonlyArray<readonly [string, object]>) =>
+  concat(payloads.map(([type, payload]) => eventFrame(type, payload)))
+
+// Override the default SSE content-type with the binary event-stream type so
+// the cassette layer treats the body as bytes when recording.
+const fixedBytes = (bytes: Uint8Array) =>
+  fixedResponse(bytes.slice().buffer, { headers: { "content-type": "application/vnd.amazon.eventstream" } })
+
+const model = BedrockConverse.model({
+  id: "anthropic.claude-3-5-sonnet-20240620-v1:0",
+  baseURL: "https://bedrock-runtime.test",
+  apiKey: "test-bearer",
+})
+
+const baseRequest = LLM.request({
+  id: "req_1",
+  model,
+  system: "You are concise.",
+  prompt: "Say hello.",
+  generation: { maxTokens: 64, temperature: 0 },
+})
+
+describe("Bedrock Converse route", () => {
+  it.effect("prepares Converse target with system, inference config, and messages", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(baseRequest)
+
+      expect(prepared.body).toEqual({
+        modelId: "anthropic.claude-3-5-sonnet-20240620-v1:0",
+        system: [{ text: "You are concise." }],
+        messages: [{ role: "user", content: [{ text: "Say hello." }] }],
+        inferenceConfig: { maxTokens: 64, temperature: 0 },
+      })
+    }),
+  )
+
+  it.effect("prepares tool config with toolSpec and toolChoice", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.updateRequest(baseRequest, {
+          tools: [
+            {
+              name: "lookup",
+              description: "Lookup data",
+              inputSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
+            },
+          ],
+          toolChoice: LLM.toolChoice({ type: "required" }),
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        toolConfig: {
+          tools: [
+            {
+              toolSpec: {
+                name: "lookup",
+                description: "Lookup data",
+                inputSchema: {
+                  json: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
+                },
+              },
+            },
+          ],
+          toolChoice: { any: {} },
+        },
+      })
+    }),
+  )
+
+  it.effect("lowers assistant tool-call + tool-result message history", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_history",
+          model,
+          messages: [
+            LLM.user("What is the weather?"),
+            LLM.assistant([LLM.toolCall({ id: "tool_1", name: "lookup", input: { query: "weather" } })]),
+            LLM.toolMessage({ id: "tool_1", name: "lookup", result: { forecast: "sunny" } }),
+          ],
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        messages: [
+          { role: "user", content: [{ text: "What is the weather?" }] },
+          {
+            role: "assistant",
+            content: [{ toolUse: { toolUseId: "tool_1", name: "lookup", input: { query: "weather" } } }],
+          },
+          {
+            role: "user",
+            content: [
+              {
+                toolResult: {
+                  toolUseId: "tool_1",
+                  content: [{ json: { forecast: "sunny" } }],
+                  status: "success",
+                },
+              },
+            ],
+          },
+        ],
+      })
+    }),
+  )
+
+  it.effect("decodes text-delta + messageStop + metadata usage from binary event stream", () =>
+    Effect.gen(function* () {
+      const body = eventStreamBody(
+        ["messageStart", { role: "assistant" }],
+        ["contentBlockDelta", { contentBlockIndex: 0, delta: { text: "Hello" } }],
+        ["contentBlockDelta", { contentBlockIndex: 0, delta: { text: "!" } }],
+        ["contentBlockStop", { contentBlockIndex: 0 }],
+        ["messageStop", { stopReason: "end_turn" }],
+        ["metadata", { usage: { inputTokens: 5, outputTokens: 2, totalTokens: 7 } }],
+      )
+      const response = yield* LLMClient.generate(baseRequest).pipe(Effect.provide(fixedBytes(body)))
+
+      expect(response.text).toBe("Hello!")
+      const finishes = response.events.filter((event) => event.type === "request-finish")
+      // Bedrock splits the finish across `messageStop` (carries reason) and
+      // `metadata` (carries usage). We consolidate them into a single
+      // terminal `request-finish` event with both.
+      expect(finishes).toHaveLength(1)
+      expect(finishes[0]).toMatchObject({ type: "request-finish", reason: "stop" })
+      expect(response.usage).toMatchObject({
+        inputTokens: 5,
+        outputTokens: 2,
+        totalTokens: 7,
+      })
+    }),
+  )
+
+  it.effect("assembles streamed tool call input", () =>
+    Effect.gen(function* () {
+      const body = eventStreamBody(
+        ["messageStart", { role: "assistant" }],
+        [
+          "contentBlockStart",
+          {
+            contentBlockIndex: 0,
+            start: { toolUse: { toolUseId: "tool_1", name: "lookup" } },
+          },
+        ],
+        ["contentBlockDelta", { contentBlockIndex: 0, delta: { toolUse: { input: '{"query"' } } }],
+        ["contentBlockDelta", { contentBlockIndex: 0, delta: { toolUse: { input: ':"weather"}' } } }],
+        ["contentBlockStop", { contentBlockIndex: 0 }],
+        ["messageStop", { stopReason: "tool_use" }],
+      )
+      const response = yield* LLMClient.generate(
+        LLM.updateRequest(baseRequest, {
+          tools: [{ name: "lookup", description: "Lookup", inputSchema: { type: "object" } }],
+        }),
+      ).pipe(Effect.provide(fixedBytes(body)))
+
+      expect(response.toolCalls).toEqual([
+        { type: "tool-call", id: "tool_1", name: "lookup", input: { query: "weather" } },
+      ])
+      const events = response.events.filter((event) => event.type === "tool-input-delta")
+      expect(events).toEqual([
+        { type: "tool-input-delta", id: "tool_1", name: "lookup", text: '{"query"' },
+        { type: "tool-input-delta", id: "tool_1", name: "lookup", text: ':"weather"}' },
+      ])
+      expect(response.events.at(-1)).toMatchObject({ type: "request-finish", reason: "tool-calls" })
+    }),
+  )
+
+  it.effect("decodes reasoning deltas", () =>
+    Effect.gen(function* () {
+      const body = eventStreamBody(
+        ["messageStart", { role: "assistant" }],
+        ["contentBlockDelta", { contentBlockIndex: 0, delta: { reasoningContent: { text: "Let me think." } } }],
+        ["contentBlockStop", { contentBlockIndex: 0 }],
+        ["messageStop", { stopReason: "end_turn" }],
+      )
+      const response = yield* LLMClient.generate(baseRequest).pipe(Effect.provide(fixedBytes(body)))
+
+      expect(response.reasoning).toBe("Let me think.")
+    }),
+  )
+
+  it.effect("emits provider-error for throttlingException", () =>
+    Effect.gen(function* () {
+      const body = eventStreamBody(
+        ["messageStart", { role: "assistant" }],
+        ["throttlingException", { message: "Slow down" }],
+      )
+      const response = yield* LLMClient.generate(baseRequest).pipe(Effect.provide(fixedBytes(body)))
+
+      expect(response.events.find((event) => event.type === "provider-error")).toEqual({
+        type: "provider-error",
+        message: "Slow down",
+        retryable: true,
+      })
+    }),
+  )
+
+  it.effect("rejects requests with no auth path", () =>
+    Effect.gen(function* () {
+      const unsignedModel = BedrockConverse.model({
+        id: "anthropic.claude-3-5-sonnet-20240620-v1:0",
+        baseURL: "https://bedrock-runtime.test",
+      })
+      const error = yield* LLMClient.generate(LLM.updateRequest(baseRequest, { model: unsignedModel })).pipe(
+        Effect.provide(fixedBytes(eventStreamBody(["messageStop", { stopReason: "end_turn" }]))),
+        Effect.flip,
+      )
+
+      expect(error.message).toContain("Bedrock Converse requires either model.apiKey")
+    }),
+  )
+
+  it.effect("signs requests with SigV4 when AWS credentials are provided (deterministic plumbing check)", () =>
+    Effect.gen(function* () {
+      const signed = BedrockConverse.model({
+        id: "anthropic.claude-3-5-sonnet-20240620-v1:0",
+        baseURL: "https://bedrock-runtime.test",
+        credentials: {
+          region: "us-east-1",
+          accessKeyId: "AKIAIOSFODNN7EXAMPLE",
+          secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
+        },
+      })
+      const prepared = yield* LLMClient.prepare(LLM.updateRequest(baseRequest, { model: signed }))
+
+      expect(prepared.route).toBe("bedrock-converse")
+      // The prepare phase doesn't sign — toHttp does. We assert the credential
+      // is plumbed onto the model native field for the signer to find.
+      expect(prepared.model.native).toMatchObject({
+        aws_credentials: { region: "us-east-1", accessKeyId: "AKIAIOSFODNN7EXAMPLE" },
+        aws_region: "us-east-1",
+      })
+    }),
+  )
+
+  it.effect("emits cachePoint markers after system, user-text, and assistant-text with cache hints", () =>
+    Effect.gen(function* () {
+      const cache = new CacheHint({ type: "ephemeral" })
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_cache",
+          model,
+          system: [{ type: "text", text: "System prefix.", cache }],
+          messages: [
+            LLM.user([{ type: "text", text: "User prefix.", cache }]),
+            LLM.assistant([{ type: "text", text: "Assistant prefix.", cache }]),
+          ],
+          generation: { maxTokens: 16, temperature: 0 },
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        // System: text block followed by cachePoint marker.
+        system: [{ text: "System prefix." }, { cachePoint: { type: "default" } }],
+        messages: [
+          {
+            role: "user",
+            content: [{ text: "User prefix." }, { cachePoint: { type: "default" } }],
+          },
+          {
+            role: "assistant",
+            content: [{ text: "Assistant prefix." }, { cachePoint: { type: "default" } }],
+          },
+        ],
+      })
+    }),
+  )
+
+  it.effect("does not emit cachePoint when no cache hint is set", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(baseRequest)
+      expect(prepared.body).toMatchObject({
+        system: [{ text: "You are concise." }],
+        messages: [{ role: "user", content: [{ text: "Say hello." }] }],
+      })
+    }),
+  )
+
+  it.effect("lowers image media into Bedrock image blocks", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_image",
+          model,
+          messages: [
+            LLM.user([
+              { type: "text", text: "What is in this image?" },
+              { type: "media", mediaType: "image/png", data: "AAAA" },
+              { type: "media", mediaType: "image/jpeg", data: "BBBB" },
+              { type: "media", mediaType: "image/jpg", data: "CCCC" },
+              { type: "media", mediaType: "image/webp", data: "DDDD" },
+            ]),
+          ],
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        messages: [
+          {
+            role: "user",
+            content: [
+              { text: "What is in this image?" },
+              { image: { format: "png", source: { bytes: "AAAA" } } },
+              { image: { format: "jpeg", source: { bytes: "BBBB" } } },
+              // image/jpg is a non-standard alias; we map it to jpeg.
+              { image: { format: "jpeg", source: { bytes: "CCCC" } } },
+              { image: { format: "webp", source: { bytes: "DDDD" } } },
+            ],
+          },
+        ],
+      })
+    }),
+  )
+
+  it.effect("base64-encodes Uint8Array image bytes", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_image_bytes",
+          model,
+          messages: [LLM.user([{ type: "media", mediaType: "image/png", data: new Uint8Array([1, 2, 3, 4, 5]) }])],
+        }),
+      )
+
+      // Buffer.from([1,2,3,4,5]).toString("base64") === "AQIDBAU="
+      expect(prepared.body).toMatchObject({
+        messages: [
+          {
+            role: "user",
+            content: [{ image: { format: "png", source: { bytes: "AQIDBAU=" } } }],
+          },
+        ],
+      })
+    }),
+  )
+
+  it.effect("lowers document media into Bedrock document blocks with format and name", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_doc",
+          model,
+          messages: [
+            LLM.user([
+              { type: "media", mediaType: "application/pdf", data: "PDFDATA", filename: "report.pdf" },
+              { type: "media", mediaType: "text/csv", data: "CSVDATA" },
+            ]),
+          ],
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        messages: [
+          {
+            role: "user",
+            content: [
+              // Filename round-trips when supplied.
+              { document: { format: "pdf", name: "report.pdf", source: { bytes: "PDFDATA" } } },
+              // Falls back to a stable placeholder when filename is missing.
+              { document: { format: "csv", name: "document.csv", source: { bytes: "CSVDATA" } } },
+            ],
+          },
+        ],
+      })
+    }),
+  )
+
+  it.effect("rejects unsupported image media types", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_bad_image",
+          model,
+          messages: [LLM.user([{ type: "media", mediaType: "image/svg+xml", data: "x" }])],
+        }),
+      ).pipe(Effect.flip)
+
+      expect(error.message).toContain("Bedrock Converse does not support image media type image/svg+xml")
+    }),
+  )
+
+  it.effect("rejects unsupported document media types", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_bad_doc",
+          model,
+          messages: [LLM.user([{ type: "media", mediaType: "application/x-tar", data: "x", filename: "a.tar" }])],
+        }),
+      ).pipe(Effect.flip)
+
+      expect(error.message).toContain("Bedrock Converse does not support media type application/x-tar")
+    }),
+  )
+})
+
+// Live recorded integration tests. Run with `RECORD=true AWS_ACCESS_KEY_ID=...
+// AWS_SECRET_ACCESS_KEY=... [AWS_SESSION_TOKEN=...] bun run test ...` to refresh
+// cassettes; replay is the default and works without credentials.
+//
+// Region is pinned to us-east-1 in tests so the request URL is stable across
+// machines on replay. If you need to record from a different region (e.g. your
+// account has access elsewhere), pass `BEDROCK_RECORDING_REGION=eu-west-1` —
+// but then commit the resulting cassette and others should record from the
+// same region too.
+const RECORDING_REGION = process.env.BEDROCK_RECORDING_REGION ?? "us-east-1"
+
+const recordedModel = () =>
+  BedrockConverse.model({
+    // Most newer Anthropic models on Bedrock require a cross-region inference
+    // profile (`us.` prefix). Nova does not require an Anthropic use-case form
+    // and is on-demand-throughput accessible by default for most accounts.
+    id: process.env.BEDROCK_MODEL_ID ?? "us.amazon.nova-micro-v1:0",
+    credentials: {
+      region: RECORDING_REGION,
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? "fixture",
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? "fixture",
+      sessionToken: process.env.AWS_SESSION_TOKEN,
+    },
+  })
+
+const recorded = recordedTests({
+  prefix: "bedrock-converse",
+  provider: "amazon-bedrock",
+  protocol: "bedrock-converse",
+  requires: ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"],
+})
+
+describe("Bedrock Converse recorded", () => {
+  recorded.effect("streams text", () =>
+    Effect.gen(function* () {
+      const llm = yield* LLMClient.Service
+      const response = yield* llm.generate(
+        LLM.request({
+          id: "recorded_bedrock_text",
+          model: recordedModel(),
+          system: "Reply with the single word 'Hello'.",
+          prompt: "Say hello.",
+          generation: { maxTokens: 16, temperature: 0 },
+        }),
+      )
+
+      expect(eventSummary(response.events)).toEqual([
+        { type: "text", value: "Hello" },
+        { type: "finish", reason: "stop", usage: { inputTokens: 12, outputTokens: 2, totalTokens: 14 } },
+      ])
+    }),
+  )
+
+  recorded.effect.with("streams a tool call", { tags: ["tool"] }, () =>
+    Effect.gen(function* () {
+      const llm = yield* LLMClient.Service
+      const response = yield* llm.generate(
+        LLM.request({
+          id: "recorded_bedrock_tool_call",
+          model: recordedModel(),
+          system: "Call tools exactly as requested.",
+          prompt: "Call get_weather with city exactly Paris.",
+          tools: [weatherTool],
+          toolChoice: LLM.toolChoice(weatherTool),
+          generation: { maxTokens: 80, temperature: 0 },
+        }),
+      )
+
+      expect(eventSummary(response.events)).toEqual([
+        { type: "tool-call", name: weatherToolName, input: { city: "Paris" } },
+        { type: "finish", reason: "tool-calls", usage: { inputTokens: 419, outputTokens: 16, totalTokens: 435 } },
+      ])
+    }),
+  )
+
+  recorded.effect.with("drives a tool loop", { tags: ["tool", "tool-loop", "golden"] }, () =>
+    Effect.gen(function* () {
+      const llm = yield* LLMClient.Service
+      expectWeatherToolLoop(
+        yield* runWeatherToolLoop(
+          weatherToolLoopRequest({
+            id: "recorded_bedrock_tool_loop",
+            model: recordedModel(),
+          }),
+        ),
+      )
+    }),
+  )
+})

packages/llm/test/provider/cloudflare.test.ts

@@ -0,0 +1,232 @@
+import { describe, expect } from "bun:test"
+import { ConfigProvider, Effect, Schema } from "effect"
+import { HttpClientRequest } from "effect/unstable/http"
+import { LLM } from "../../src"
+import * as Cloudflare from "../../src/providers/cloudflare"
+import { LLMClient } from "../../src/route"
+import { it } from "../lib/effect"
+import { dynamicResponse } from "../lib/http"
+import { sseEvents } from "../lib/sse"
+
+const Json = Schema.fromJsonString(Schema.Unknown)
+const decodeJson = Schema.decodeUnknownSync(Json)
+const withEnv = (env: Record<string, string>) => Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnv({ env })))
+
+const deltaChunk = (delta: object, finishReason: string | null = null) => ({
+  id: "chatcmpl_fixture",
+  choices: [{ delta, finish_reason: finishReason }],
+  usage: null,
+})
+
+describe("Cloudflare", () => {
+  it.effect("prepares AI Gateway models through the OpenAI-compatible Chat protocol", () =>
+    Effect.gen(function* () {
+      const model = Cloudflare.aiGateway("workers-ai/@cf/meta/llama-3.3-70b-instruct", {
+        accountId: "test-account",
+        gatewayId: "test-gateway",
+        apiKey: "test-token",
+      })
+
+      expect(model).toMatchObject({
+        id: "workers-ai/@cf/meta/llama-3.3-70b-instruct",
+        provider: "cloudflare-ai-gateway",
+        route: "cloudflare-ai-gateway",
+        baseURL: "https://gateway.ai.cloudflare.com/v1/test-account/test-gateway/compat",
+      })
+
+      const prepared = yield* LLMClient.prepare(LLM.request({ model, prompt: "Say hello." }))
+
+      expect(prepared.route).toBe("cloudflare-ai-gateway")
+      expect(prepared.body).toMatchObject({
+        model: "workers-ai/@cf/meta/llama-3.3-70b-instruct",
+        messages: [{ role: "user", content: "Say hello." }],
+        stream: true,
+      })
+    }),
+  )
+
+  it.effect("posts to the derived gateway endpoint with bearer auth", () =>
+    Effect.gen(function* () {
+      const response = yield* LLM.generate(
+        LLM.request({
+          model: Cloudflare.aiGateway("openai/gpt-4o-mini", {
+            accountId: "test-account",
+            gatewayId: "test-gateway",
+            apiKey: "test-token",
+          }),
+          prompt: "Say hello.",
+        }),
+      ).pipe(
+        Effect.provide(
+          dynamicResponse((input) =>
+            Effect.gen(function* () {
+              const web = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+              expect(web.url).toBe(
+                "https://gateway.ai.cloudflare.com/v1/test-account/test-gateway/compat/chat/completions",
+              )
+              expect(web.headers.get("authorization")).toBe("Bearer test-token")
+              expect(decodeJson(input.text)).toMatchObject({
+                model: "openai/gpt-4o-mini",
+                stream: true,
+                messages: [{ role: "user", content: "Say hello." }],
+              })
+              return input.respond(
+                sseEvents(deltaChunk({ role: "assistant", content: "Hello" }), deltaChunk({}, "stop")),
+                { headers: { "content-type": "text/event-stream" } },
+              )
+            }),
+          ),
+        ),
+      )
+
+      expect(response.text).toBe("Hello")
+    }),
+  )
+
+  it.effect("defaults AI Gateway id to default when omitted or blank", () =>
+    Effect.gen(function* () {
+      expect(
+        Cloudflare.aiGateway("workers-ai/@cf/meta/llama-3.3-70b-instruct", {
+          accountId: "test-account",
+          gatewayId: "",
+          gatewayApiKey: "test-token",
+        }).baseURL,
+      ).toBe("https://gateway.ai.cloudflare.com/v1/test-account/default/compat")
+    }),
+  )
+
+  it.effect("supports authenticated AI Gateway plus upstream provider auth", () =>
+    Effect.gen(function* () {
+      yield* LLM.generate(
+        LLM.request({
+          model: Cloudflare.aiGateway("openai/gpt-4o-mini", {
+            accountId: "test-account",
+            gatewayApiKey: "gateway-token",
+            apiKey: "provider-token",
+          }),
+          prompt: "Say hello.",
+        }),
+      ).pipe(
+        Effect.provide(
+          dynamicResponse((input) =>
+            Effect.gen(function* () {
+              const web = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+              expect(web.url).toBe("https://gateway.ai.cloudflare.com/v1/test-account/default/compat/chat/completions")
+              expect(web.headers.get("cf-aig-authorization")).toBe("Bearer gateway-token")
+              expect(web.headers.get("authorization")).toBe("Bearer provider-token")
+              return input.respond(
+                sseEvents(deltaChunk({ role: "assistant", content: "Hello" }), deltaChunk({}, "stop")),
+                { headers: { "content-type": "text/event-stream" } },
+              )
+            }),
+          ),
+        ),
+      )
+    }),
+  )
+
+  it.effect("allows a fully configured baseURL override", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model: Cloudflare.aiGateway("openai/gpt-4o-mini", {
+            baseURL: "https://gateway.proxy.test/v1/custom/compat",
+            apiKey: "test-token",
+          }),
+          prompt: "Say hello.",
+        }),
+      )
+
+      expect(prepared.model.baseURL).toBe("https://gateway.proxy.test/v1/custom/compat")
+    }),
+  )
+
+  it.effect("prepares direct Workers AI models through the OpenAI-compatible Chat protocol", () =>
+    Effect.gen(function* () {
+      const model = Cloudflare.workersAI("@cf/meta/llama-3.1-8b-instruct", {
+        accountId: "test-account",
+        apiKey: "test-token",
+      })
+
+      expect(model).toMatchObject({
+        id: "@cf/meta/llama-3.1-8b-instruct",
+        provider: "cloudflare-workers-ai",
+        route: "cloudflare-workers-ai",
+        baseURL: "https://api.cloudflare.com/client/v4/accounts/test-account/ai/v1",
+      })
+
+      const prepared = yield* LLMClient.prepare(LLM.request({ model, prompt: "Say hello." }))
+
+      expect(prepared.route).toBe("cloudflare-workers-ai")
+      expect(prepared.body).toMatchObject({
+        model: "@cf/meta/llama-3.1-8b-instruct",
+        messages: [{ role: "user", content: "Say hello." }],
+        stream: true,
+      })
+    }),
+  )
+
+  it.effect("posts direct Workers AI requests to the account endpoint with bearer auth", () =>
+    Effect.gen(function* () {
+      const response = yield* LLM.generate(
+        LLM.request({
+          model: Cloudflare.workersAI("@cf/meta/llama-3.1-8b-instruct", {
+            accountId: "test-account",
+            apiKey: "test-token",
+          }),
+          prompt: "Say hello.",
+        }),
+      ).pipe(
+        Effect.provide(
+          dynamicResponse((input) =>
+            Effect.gen(function* () {
+              const web = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+              expect(web.url).toBe(
+                "https://api.cloudflare.com/client/v4/accounts/test-account/ai/v1/chat/completions",
+              )
+              expect(web.headers.get("authorization")).toBe("Bearer test-token")
+              expect(decodeJson(input.text)).toMatchObject({
+                model: "@cf/meta/llama-3.1-8b-instruct",
+                stream: true,
+                messages: [{ role: "user", content: "Say hello." }],
+              })
+              return input.respond(
+                sseEvents(deltaChunk({ role: "assistant", content: "Hello" }), deltaChunk({}, "stop")),
+                { headers: { "content-type": "text/event-stream" } },
+              )
+            }),
+          ),
+        ),
+      )
+
+      expect(response.text).toBe("Hello")
+    }),
+  )
+
+  it.effect("supports direct Workers AI token aliases through auth config", () =>
+    Effect.gen(function* () {
+      yield* LLM.generate(
+        LLM.request({
+          model: Cloudflare.workersAI("@cf/meta/llama-3.1-8b-instruct", {
+            accountId: "test-account",
+          }),
+          prompt: "Say hello.",
+        }),
+      ).pipe(
+        withEnv({ CLOUDFLARE_WORKERS_AI_TOKEN: "test-token" }),
+        Effect.provide(
+          dynamicResponse((input) =>
+            Effect.gen(function* () {
+              const web = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+              expect(web.headers.get("authorization")).toBe("Bearer test-token")
+              return input.respond(
+                sseEvents(deltaChunk({ role: "assistant", content: "Hello" }), deltaChunk({}, "stop")),
+                { headers: { "content-type": "text/event-stream" } },
+              )
+            }),
+          ),
+        ),
+      )
+    }),
+  )
+})

packages/llm/test/provider/gemini.test.ts

@@ -0,0 +1,360 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { LLM, LLMError } from "../../src"
+import { LLMClient } from "../../src/route"
+import * as Gemini from "../../src/protocols/gemini"
+import { it } from "../lib/effect"
+import { fixedResponse } from "../lib/http"
+import { sseEvents, sseRaw } from "../lib/sse"
+
+const model = Gemini.model({
+  id: "gemini-2.5-flash",
+  baseURL: "https://generativelanguage.test/v1beta/",
+  headers: { "x-goog-api-key": "test" },
+})
+
+const request = LLM.request({
+  id: "req_1",
+  model,
+  system: "You are concise.",
+  prompt: "Say hello.",
+  generation: { maxTokens: 20, temperature: 0 },
+})
+
+describe("Gemini route", () => {
+  it.effect("prepares Gemini target", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(request)
+
+      expect(prepared.body).toEqual({
+        contents: [{ role: "user", parts: [{ text: "Say hello." }] }],
+        systemInstruction: { parts: [{ text: "You are concise." }] },
+        generationConfig: { maxOutputTokens: 20, temperature: 0 },
+      })
+    }),
+  )
+
+  it.effect("prepares multimodal user input and tool history", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_tool_result",
+          model,
+          tools: [
+            {
+              name: "lookup",
+              description: "Lookup data",
+              inputSchema: { type: "object", properties: { query: { type: "string" } } },
+            },
+          ],
+          toolChoice: { type: "tool", name: "lookup" },
+          messages: [
+            LLM.user([
+              { type: "text", text: "What is in this image?" },
+              { type: "media", mediaType: "image/png", data: "AAECAw==" },
+            ]),
+            LLM.assistant([LLM.toolCall({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
+            LLM.toolMessage({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
+          ],
+        }),
+      )
+
+      expect(prepared.body).toEqual({
+        contents: [
+          {
+            role: "user",
+            parts: [{ text: "What is in this image?" }, { inlineData: { mimeType: "image/png", data: "AAECAw==" } }],
+          },
+          {
+            role: "model",
+            parts: [{ functionCall: { name: "lookup", args: { query: "weather" } } }],
+          },
+          {
+            role: "user",
+            parts: [
+              { functionResponse: { name: "lookup", response: { name: "lookup", content: '{"forecast":"sunny"}' } } },
+            ],
+          },
+        ],
+        tools: [
+          {
+            functionDeclarations: [
+              {
+                name: "lookup",
+                description: "Lookup data",
+                parameters: { type: "object", properties: { query: { type: "string" } } },
+              },
+            ],
+          },
+        ],
+        toolConfig: { functionCallingConfig: { mode: "ANY", allowedFunctionNames: ["lookup"] } },
+      })
+    }),
+  )
+
+  it.effect("omits tools when tool choice is none", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_no_tools",
+          model,
+          prompt: "Say hello.",
+          tools: [{ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } }],
+          toolChoice: { type: "none" },
+        }),
+      )
+
+      expect(prepared.body).toEqual({
+        contents: [{ role: "user", parts: [{ text: "Say hello." }] }],
+      })
+    }),
+  )
+
+  it.effect("sanitizes integer enums, dangling required, untyped arrays, and scalar object keys", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_schema_patch",
+          model,
+          prompt: "Use the tool.",
+          tools: [
+            {
+              name: "lookup",
+              description: "Lookup data",
+              inputSchema: {
+                type: "object",
+                required: ["status", "missing"],
+                properties: {
+                  status: { type: "integer", enum: [1, 2] },
+                  tags: { type: "array" },
+                  name: { type: "string", properties: { ignored: { type: "string" } }, required: ["ignored"] },
+                },
+              },
+            },
+          ],
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        tools: [
+          {
+            functionDeclarations: [
+              {
+                parameters: {
+                  type: "object",
+                  required: ["status"],
+                  properties: {
+                    status: { type: "string", enum: ["1", "2"] },
+                    tags: { type: "array", items: { type: "string" } },
+                    name: { type: "string" },
+                  },
+                },
+              },
+            ],
+          },
+        ],
+      })
+    }),
+  )
+
+  it.effect("parses text, reasoning, and usage stream fixtures", () =>
+    Effect.gen(function* () {
+      const body = sseEvents(
+        {
+          candidates: [
+            {
+              content: { role: "model", parts: [{ text: "thinking", thought: true }] },
+            },
+          ],
+        },
+        {
+          candidates: [
+            {
+              content: { role: "model", parts: [{ text: "Hello" }] },
+            },
+          ],
+        },
+        {
+          candidates: [
+            {
+              content: { role: "model", parts: [{ text: "!" }] },
+              finishReason: "STOP",
+            },
+          ],
+        },
+        {
+          usageMetadata: {
+            promptTokenCount: 5,
+            candidatesTokenCount: 2,
+            totalTokenCount: 7,
+            thoughtsTokenCount: 1,
+            cachedContentTokenCount: 1,
+          },
+        },
+      )
+      const response = yield* LLMClient.generate(request).pipe(Effect.provide(fixedResponse(body)))
+
+      expect(response.text).toBe("Hello!")
+      expect(response.reasoning).toBe("thinking")
+      expect(response.usage).toMatchObject({
+        inputTokens: 5,
+        outputTokens: 2,
+        reasoningTokens: 1,
+        cacheReadInputTokens: 1,
+        totalTokens: 7,
+      })
+      expect(response.events).toEqual([
+        { type: "reasoning-delta", text: "thinking" },
+        { type: "text-delta", text: "Hello" },
+        { type: "text-delta", text: "!" },
+        {
+          type: "request-finish",
+          reason: "stop",
+          usage: {
+            inputTokens: 5,
+            outputTokens: 2,
+            reasoningTokens: 1,
+            cacheReadInputTokens: 1,
+            totalTokens: 7,
+            native: {
+              promptTokenCount: 5,
+              candidatesTokenCount: 2,
+              totalTokenCount: 7,
+              thoughtsTokenCount: 1,
+              cachedContentTokenCount: 1,
+            },
+          },
+        },
+      ])
+    }),
+  )
+
+  it.effect("emits streamed tool calls and maps finish reason", () =>
+    Effect.gen(function* () {
+      const body = sseEvents({
+        candidates: [
+          {
+            content: {
+              role: "model",
+              parts: [{ functionCall: { name: "lookup", args: { query: "weather" } } }],
+            },
+            finishReason: "STOP",
+          },
+        ],
+        usageMetadata: { promptTokenCount: 5, candidatesTokenCount: 1 },
+      })
+      const response = yield* LLMClient.generate(
+        LLM.updateRequest(request, {
+          tools: [{ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } }],
+        }),
+      ).pipe(Effect.provide(fixedResponse(body)))
+
+      expect(response.toolCalls).toEqual([
+        { type: "tool-call", id: "tool_0", name: "lookup", input: { query: "weather" } },
+      ])
+      expect(response.events).toEqual([
+        { type: "tool-call", id: "tool_0", name: "lookup", input: { query: "weather" } },
+        {
+          type: "request-finish",
+          reason: "tool-calls",
+          usage: {
+            inputTokens: 5,
+            outputTokens: 1,
+            totalTokens: 6,
+            native: { promptTokenCount: 5, candidatesTokenCount: 1 },
+          },
+        },
+      ])
+    }),
+  )
+
+  it.effect("assigns unique ids to multiple streamed tool calls", () =>
+    Effect.gen(function* () {
+      const body = sseEvents({
+        candidates: [
+          {
+            content: {
+              role: "model",
+              parts: [
+                { functionCall: { name: "lookup", args: { query: "weather" } } },
+                { functionCall: { name: "lookup", args: { query: "news" } } },
+              ],
+            },
+            finishReason: "STOP",
+          },
+        ],
+      })
+      const response = yield* LLMClient.generate(
+        LLM.updateRequest(request, {
+          tools: [{ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } }],
+        }),
+      ).pipe(Effect.provide(fixedResponse(body)))
+
+      expect(response.toolCalls).toEqual([
+        { type: "tool-call", id: "tool_0", name: "lookup", input: { query: "weather" } },
+        { type: "tool-call", id: "tool_1", name: "lookup", input: { query: "news" } },
+      ])
+      expect(response.events.at(-1)).toMatchObject({ type: "request-finish", reason: "tool-calls" })
+    }),
+  )
+
+  it.effect("maps length and content-filter finish reasons", () =>
+    Effect.gen(function* () {
+      const length = yield* LLMClient.generate(request).pipe(
+        Effect.provide(
+          fixedResponse(
+            sseEvents({ candidates: [{ content: { role: "model", parts: [] }, finishReason: "MAX_TOKENS" }] }),
+          ),
+        ),
+      )
+      const filtered = yield* LLMClient.generate(request).pipe(
+        Effect.provide(
+          fixedResponse(sseEvents({ candidates: [{ content: { role: "model", parts: [] }, finishReason: "SAFETY" }] })),
+        ),
+      )
+
+      expect(length.events).toEqual([{ type: "request-finish", reason: "length" }])
+      expect(filtered.events).toEqual([{ type: "request-finish", reason: "content-filter" }])
+    }),
+  )
+
+  it.effect("leaves total usage undefined when component counts are missing", () =>
+    Effect.gen(function* () {
+      const response = yield* LLMClient.generate(request).pipe(
+        Effect.provide(fixedResponse(sseEvents({ usageMetadata: { thoughtsTokenCount: 1 } }))),
+      )
+
+      expect(response.usage).toMatchObject({ reasoningTokens: 1 })
+      expect(response.usage?.totalTokens).toBeUndefined()
+    }),
+  )
+
+  it.effect("fails invalid stream events", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.generate(request).pipe(
+        Effect.provide(fixedResponse(sseRaw("data: {not json}"))),
+        Effect.flip,
+      )
+
+      expect(error).toBeInstanceOf(LLMError)
+      expect(error.reason).toMatchObject({ _tag: "InvalidProviderOutput" })
+      expect(error.message).toContain("Invalid google/gemini stream event")
+    }),
+  )
+
+  it.effect("rejects unsupported assistant media content", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_media",
+          model,
+          messages: [LLM.assistant({ type: "media", mediaType: "image/png", data: "AAECAw==" })],
+        }),
+      ).pipe(Effect.flip)
+
+      expect(error.message).toContain(
+        "Gemini assistant messages only support text, reasoning, and tool-call content for now",
+      )
+    }),
+  )
+})

packages/llm/test/provider/golden.recorded.test.ts

@@ -0,0 +1,215 @@
+import * as AnthropicMessages from "../../src/protocols/anthropic-messages"
+import * as Gemini from "../../src/protocols/gemini"
+import * as OpenAIChat from "../../src/protocols/openai-chat"
+import * as OpenAIResponses from "../../src/protocols/openai-responses"
+import * as Cloudflare from "../../src/providers/cloudflare"
+import * as OpenAI from "../../src/providers/openai"
+import * as OpenAICompatible from "../../src/providers/openai-compatible"
+import * as OpenRouter from "../../src/providers/openrouter"
+import * as XAI from "../../src/providers/xai"
+import { describeRecordedGoldenScenarios } from "../recorded-golden"
+
+const openAIChat = OpenAIChat.model({ id: "gpt-4o-mini", apiKey: process.env.OPENAI_API_KEY ?? "fixture" })
+const openAIResponses = OpenAIResponses.model({ id: "gpt-5.5", apiKey: process.env.OPENAI_API_KEY ?? "fixture" })
+const openAIResponsesWebSocket = OpenAI.responsesWebSocket("gpt-4.1-mini", {
+  apiKey: process.env.OPENAI_API_KEY ?? "fixture",
+})
+const anthropicHaiku = AnthropicMessages.model({
+  id: "claude-haiku-4-5-20251001",
+  apiKey: process.env.ANTHROPIC_API_KEY ?? "fixture",
+})
+const anthropicOpus = AnthropicMessages.model({
+  id: "claude-opus-4-7",
+  apiKey: process.env.ANTHROPIC_API_KEY ?? "fixture",
+})
+const gemini = Gemini.model({ id: "gemini-2.5-flash", apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY ?? "fixture" })
+const xaiBasic = XAI.model("grok-3-mini", { apiKey: process.env.XAI_API_KEY ?? "fixture" })
+const xaiFlagship = XAI.model("grok-4.3", { apiKey: process.env.XAI_API_KEY ?? "fixture" })
+const cloudflareAIGatewayWorkers = Cloudflare.aiGateway("workers-ai/@cf/meta/llama-3.1-8b-instruct", {
+  accountId: process.env.CLOUDFLARE_ACCOUNT_ID ?? "fixture-account",
+  gatewayId:
+    process.env.CLOUDFLARE_GATEWAY_ID && process.env.CLOUDFLARE_GATEWAY_ID !== process.env.CLOUDFLARE_ACCOUNT_ID
+      ? process.env.CLOUDFLARE_GATEWAY_ID
+      : undefined,
+  gatewayApiKey: process.env.CLOUDFLARE_API_TOKEN ?? "fixture",
+})
+const cloudflareAIGatewayWorkersTools = Cloudflare.aiGateway("workers-ai/@cf/openai/gpt-oss-20b", {
+  accountId: process.env.CLOUDFLARE_ACCOUNT_ID ?? "fixture-account",
+  gatewayId:
+    process.env.CLOUDFLARE_GATEWAY_ID && process.env.CLOUDFLARE_GATEWAY_ID !== process.env.CLOUDFLARE_ACCOUNT_ID
+      ? process.env.CLOUDFLARE_GATEWAY_ID
+      : undefined,
+  gatewayApiKey: process.env.CLOUDFLARE_API_TOKEN ?? "fixture",
+})
+const cloudflareWorkersAI = Cloudflare.workersAI("@cf/meta/llama-3.1-8b-instruct", {
+  accountId: process.env.CLOUDFLARE_ACCOUNT_ID ?? "fixture-account",
+  apiKey: process.env.CLOUDFLARE_API_KEY ?? "fixture",
+})
+const cloudflareWorkersAITools = Cloudflare.workersAI("@cf/openai/gpt-oss-20b", {
+  accountId: process.env.CLOUDFLARE_ACCOUNT_ID ?? "fixture-account",
+  apiKey: process.env.CLOUDFLARE_API_KEY ?? "fixture",
+})
+const deepseek = OpenAICompatible.deepseek.model("deepseek-chat", { apiKey: process.env.DEEPSEEK_API_KEY ?? "fixture" })
+const together = OpenAICompatible.togetherai.model("meta-llama/Llama-3.3-70B-Instruct-Turbo", {
+  apiKey: process.env.TOGETHER_AI_API_KEY ?? "fixture",
+})
+const groq = OpenAICompatible.groq.model("llama-3.3-70b-versatile", { apiKey: process.env.GROQ_API_KEY ?? "fixture" })
+const openrouter = OpenRouter.model("openai/gpt-4o-mini", { apiKey: process.env.OPENROUTER_API_KEY ?? "fixture" })
+const openrouterGpt55 = OpenRouter.model("openai/gpt-5.5", { apiKey: process.env.OPENROUTER_API_KEY ?? "fixture" })
+const openrouterOpus = OpenRouter.model("anthropic/claude-opus-4.7", {
+  apiKey: process.env.OPENROUTER_API_KEY ?? "fixture",
+})
+
+const redactCloudflareURL = (url: string) =>
+  url
+    .replace(/\/client\/v4\/accounts\/[^/]+\/ai\/v1\//, "/client/v4/accounts/{account}/ai/v1/")
+    .replace(/\/v1\/[^/]+\/[^/]+\/compat\//, "/v1/{account}/{gateway}/compat/")
+
+const cloudflareOptions = {
+  redact: { url: redactCloudflareURL },
+}
+
+describeRecordedGoldenScenarios([
+  {
+    name: "OpenAI Chat gpt-4o-mini",
+    prefix: "openai-chat",
+    model: openAIChat,
+    requires: ["OPENAI_API_KEY"],
+    scenarios: ["text", "tool-call", "tool-loop"],
+  },
+  {
+    name: "OpenAI Responses gpt-5.5",
+    prefix: "openai-responses",
+    model: openAIResponses,
+    requires: ["OPENAI_API_KEY"],
+    tags: ["flagship"],
+    scenarios: [
+      { id: "text", temperature: false },
+      { id: "tool-call", temperature: false },
+      { id: "tool-loop", temperature: false },
+    ],
+  },
+  {
+    name: "OpenAI Responses WebSocket gpt-4.1-mini",
+    prefix: "openai-responses-websocket",
+    model: openAIResponsesWebSocket,
+    transport: "websocket",
+    requires: ["OPENAI_API_KEY"],
+    scenarios: ["tool-loop"],
+  },
+  {
+    name: "Anthropic Haiku 4.5",
+    prefix: "anthropic-messages",
+    model: anthropicHaiku,
+    requires: ["ANTHROPIC_API_KEY"],
+    options: { requestHeaders: ["content-type", "anthropic-version"] },
+    scenarios: ["text", "tool-call"],
+  },
+  {
+    name: "Anthropic Opus 4.7",
+    prefix: "anthropic-messages",
+    model: anthropicOpus,
+    requires: ["ANTHROPIC_API_KEY"],
+    tags: ["flagship"],
+    options: { requestHeaders: ["content-type", "anthropic-version"] },
+    scenarios: [{ id: "tool-loop", temperature: false }],
+  },
+  {
+    name: "Gemini 2.5 Flash",
+    prefix: "gemini",
+    model: gemini,
+    requires: ["GOOGLE_GENERATIVE_AI_API_KEY"],
+    scenarios: [{ id: "text", maxTokens: 80 }, "tool-call"],
+  },
+  {
+    name: "xAI Grok 3 Mini",
+    prefix: "xai",
+    model: xaiBasic,
+    requires: ["XAI_API_KEY"],
+    scenarios: ["text", "tool-call"],
+  },
+  {
+    name: "xAI Grok 4.3",
+    prefix: "xai",
+    model: xaiFlagship,
+    requires: ["XAI_API_KEY"],
+    tags: ["flagship"],
+    scenarios: [{ id: "tool-loop", timeout: 30_000 }],
+  },
+  {
+    name: "Cloudflare AI Gateway Workers AI Llama 3.1 8B",
+    prefix: "cloudflare-ai-gateway",
+    model: cloudflareAIGatewayWorkers,
+    requires: ["CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_API_TOKEN"],
+    options: cloudflareOptions,
+    scenarios: ["text"],
+  },
+  {
+    name: "Cloudflare AI Gateway Workers AI GPT OSS 20B Tools",
+    prefix: "cloudflare-ai-gateway",
+    model: cloudflareAIGatewayWorkersTools,
+    requires: ["CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_API_TOKEN"],
+    options: cloudflareOptions,
+    scenarios: [{ id: "tool-call", maxTokens: 120 }],
+  },
+  {
+    name: "Cloudflare Workers AI Llama 3.1 8B",
+    prefix: "cloudflare-workers-ai",
+    model: cloudflareWorkersAI,
+    requires: ["CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_API_KEY"],
+    options: cloudflareOptions,
+    scenarios: ["text"],
+  },
+  {
+    name: "Cloudflare Workers AI GPT OSS 20B Tools",
+    prefix: "cloudflare-workers-ai",
+    model: cloudflareWorkersAITools,
+    requires: ["CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_API_KEY"],
+    options: cloudflareOptions,
+    scenarios: [{ id: "tool-call", maxTokens: 120 }],
+  },
+  {
+    name: "DeepSeek Chat",
+    prefix: "openai-compatible-chat",
+    model: deepseek,
+    requires: ["DEEPSEEK_API_KEY"],
+    scenarios: ["text"],
+  },
+  {
+    name: "TogetherAI Llama 3.3 70B",
+    prefix: "openai-compatible-chat",
+    model: together,
+    requires: ["TOGETHER_AI_API_KEY"],
+    scenarios: ["text", "tool-call"],
+  },
+  {
+    name: "Groq Llama 3.3 70B",
+    prefix: "openai-compatible-chat",
+    model: groq,
+    requires: ["GROQ_API_KEY"],
+    scenarios: ["text", "tool-call", { id: "tool-loop", timeout: 30_000 }],
+  },
+  {
+    name: "OpenRouter gpt-4o-mini",
+    prefix: "openai-compatible-chat",
+    model: openrouter,
+    requires: ["OPENROUTER_API_KEY"],
+    scenarios: ["text", "tool-call", "tool-loop"],
+  },
+  {
+    name: "OpenRouter gpt-5.5",
+    prefix: "openai-compatible-chat",
+    model: openrouterGpt55,
+    requires: ["OPENROUTER_API_KEY"],
+    tags: ["flagship"],
+    scenarios: ["tool-loop"],
+  },
+  {
+    name: "OpenRouter Claude Opus 4.7",
+    prefix: "openai-compatible-chat",
+    model: openrouterOpus,
+    requires: ["OPENROUTER_API_KEY"],
+    tags: ["flagship"],
+    scenarios: ["tool-loop"],
+  },
+])

packages/llm/test/provider/openai-chat.test.ts

@@ -0,0 +1,355 @@
+import { describe, expect } from "bun:test"
+import { Effect, Schema, Stream } from "effect"
+import { HttpClientRequest } from "effect/unstable/http"
+import { LLM, LLMError } from "../../src"
+import * as Azure from "../../src/providers/azure"
+import * as OpenAI from "../../src/providers/openai"
+import * as OpenAIChat from "../../src/protocols/openai-chat"
+import { LLMClient } from "../../src/route"
+import { it } from "../lib/effect"
+import { dynamicResponse, fixedResponse, truncatedStream } from "../lib/http"
+import { deltaChunk, usageChunk } from "../lib/openai-chunks"
+import { sseEvents } from "../lib/sse"
+
+const TargetJson = Schema.fromJsonString(Schema.Unknown)
+const encodeJson = Schema.encodeSync(TargetJson)
+const decodeJson = Schema.decodeUnknownSync(TargetJson)
+
+const model = OpenAIChat.model({
+  id: "gpt-4o-mini",
+  baseURL: "https://api.openai.test/v1/",
+  headers: { authorization: "Bearer test" },
+})
+
+const request = LLM.request({
+  id: "req_1",
+  model,
+  system: "You are concise.",
+  prompt: "Say hello.",
+  generation: { maxTokens: 20, temperature: 0 },
+})
+
+describe("OpenAI Chat route", () => {
+  it.effect("prepares OpenAI Chat payload", () =>
+    Effect.gen(function* () {
+      // Pass the OpenAIChat payload type so `prepared.body` is statically
+      // typed to the route's native shape — the assertions below read field
+      // names without `unknown` casts.
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(request)
+      const _typed: { readonly model: string; readonly stream: true } = prepared.body
+
+      expect(prepared.body).toEqual({
+        model: "gpt-4o-mini",
+        messages: [
+          { role: "system", content: "You are concise." },
+          { role: "user", content: "Say hello." },
+        ],
+        stream: true,
+        stream_options: { include_usage: true },
+        max_tokens: 20,
+        temperature: 0,
+      })
+    }),
+  )
+
+  it.effect("maps OpenAI provider options to Chat options", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        LLM.request({
+          model: OpenAI.chat("gpt-4o-mini", { baseURL: "https://api.openai.test/v1/" }),
+          prompt: "think",
+          providerOptions: { openai: { reasoningEffort: "low" } },
+        }),
+      )
+
+      expect(prepared.body.store).toBe(false)
+      expect(prepared.body.reasoning_effort).toBe("low")
+    }),
+  )
+
+  it.effect("adds native query params to the Chat Completions URL", () =>
+    LLMClient.generate(
+      LLM.updateRequest(request, { model: OpenAIChat.model({ ...model, queryParams: { "api-version": "v1" } }) }),
+    ).pipe(
+      Effect.provide(
+        dynamicResponse((input) =>
+          Effect.gen(function* () {
+            const web = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+            expect(web.url).toBe("https://api.openai.test/v1/chat/completions?api-version=v1")
+            return input.respond(sseEvents(deltaChunk({}, "stop")), {
+              headers: { "content-type": "text/event-stream" },
+            })
+          }),
+        ),
+      ),
+    ),
+  )
+
+  it.effect("uses Azure api-key header for static OpenAI Chat keys", () =>
+    LLMClient.generate(
+      LLM.updateRequest(request, {
+        model: Azure.chat("gpt-4o-mini", {
+          baseURL: "https://opencode-test.openai.azure.com/openai/v1/",
+          apiKey: "azure-key",
+          headers: { authorization: "Bearer stale" },
+        }),
+      }),
+    ).pipe(
+      Effect.provide(
+        dynamicResponse((input) =>
+          Effect.gen(function* () {
+            const web = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+            expect(web.headers.get("api-key")).toBe("azure-key")
+            expect(web.headers.get("authorization")).toBeNull()
+            return input.respond(sseEvents(deltaChunk({}, "stop")), {
+              headers: { "content-type": "text/event-stream" },
+            })
+          }),
+        ),
+      ),
+    ),
+  )
+
+  it.effect("applies serializable HTTP overlays after payload lowering", () =>
+    LLMClient.generate(
+      LLM.updateRequest(request, {
+        model: OpenAIChat.model({ ...model, apiKey: "fresh-key", headers: { authorization: "Bearer stale" } }),
+        http: {
+          body: { metadata: { source: "test" } },
+          headers: { authorization: "Bearer request", "x-custom": "yes" },
+          query: { debug: "1" },
+        },
+      }),
+    ).pipe(
+      Effect.provide(
+        dynamicResponse((input) =>
+          Effect.gen(function* () {
+            const web = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+            expect(web.url).toBe("https://api.openai.test/v1/chat/completions?debug=1")
+            expect(web.headers.get("authorization")).toBe("Bearer fresh-key")
+            expect(web.headers.get("x-custom")).toBe("yes")
+            expect(decodeJson(input.text)).toMatchObject({
+              stream: true,
+              stream_options: { include_usage: true },
+              metadata: { source: "test" },
+            })
+            return input.respond(sseEvents(deltaChunk({}, "stop")), {
+              headers: { "content-type": "text/event-stream" },
+            })
+          }),
+        ),
+      ),
+    ),
+  )
+
+  it.effect("prepares assistant tool-call and tool-result messages", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_tool_result",
+          model,
+          messages: [
+            LLM.user("What is the weather?"),
+            LLM.assistant([LLM.toolCall({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
+            LLM.toolMessage({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
+          ],
+        }),
+      )
+
+      expect(prepared.body).toEqual({
+        model: "gpt-4o-mini",
+        messages: [
+          { role: "user", content: "What is the weather?" },
+          {
+            role: "assistant",
+            content: null,
+            tool_calls: [
+              {
+                id: "call_1",
+                type: "function",
+                function: { name: "lookup", arguments: encodeJson({ query: "weather" }) },
+              },
+            ],
+          },
+          { role: "tool", tool_call_id: "call_1", content: encodeJson({ forecast: "sunny" }) },
+        ],
+        stream: true,
+        stream_options: { include_usage: true },
+      })
+    }),
+  )
+
+  it.effect("rejects unsupported user media content", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_media",
+          model,
+          messages: [LLM.user({ type: "media", mediaType: "image/png", data: "AAECAw==" })],
+        }),
+      ).pipe(Effect.flip)
+
+      expect(error.message).toContain("OpenAI Chat user messages only support text content for now")
+    }),
+  )
+
+  it.effect("rejects unsupported assistant reasoning content", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_reasoning",
+          model,
+          messages: [LLM.assistant({ type: "reasoning", text: "hidden" })],
+        }),
+      ).pipe(Effect.flip)
+
+      expect(error.message).toContain("OpenAI Chat assistant messages only support text and tool-call content for now")
+    }),
+  )
+
+  it.effect("parses text and usage stream fixtures", () =>
+    Effect.gen(function* () {
+      const body = sseEvents(
+        deltaChunk({ role: "assistant", content: "Hello" }),
+        deltaChunk({ content: "!" }),
+        deltaChunk({}, "stop"),
+        usageChunk({
+          prompt_tokens: 5,
+          completion_tokens: 2,
+          total_tokens: 7,
+          prompt_tokens_details: { cached_tokens: 1 },
+          completion_tokens_details: { reasoning_tokens: 0 },
+        }),
+      )
+      const response = yield* LLMClient.generate(request).pipe(Effect.provide(fixedResponse(body)))
+
+      expect(response.text).toBe("Hello!")
+      expect(response.events).toEqual([
+        { type: "text-delta", text: "Hello" },
+        { type: "text-delta", text: "!" },
+        {
+          type: "request-finish",
+          reason: "stop",
+          usage: {
+            inputTokens: 5,
+            outputTokens: 2,
+            reasoningTokens: 0,
+            cacheReadInputTokens: 1,
+            totalTokens: 7,
+            native: {
+              prompt_tokens: 5,
+              completion_tokens: 2,
+              total_tokens: 7,
+              prompt_tokens_details: { cached_tokens: 1 },
+              completion_tokens_details: { reasoning_tokens: 0 },
+            },
+          },
+        },
+      ])
+    }),
+  )
+
+  it.effect("assembles streamed tool call input", () =>
+    Effect.gen(function* () {
+      const body = sseEvents(
+        deltaChunk({
+          role: "assistant",
+          tool_calls: [{ index: 0, id: "call_1", function: { name: "lookup", arguments: '{"query"' } }],
+        }),
+        deltaChunk({ tool_calls: [{ index: 0, function: { arguments: ':"weather"}' } }] }),
+        deltaChunk({}, "tool_calls"),
+      )
+      const response = yield* LLMClient.generate(
+        LLM.updateRequest(request, {
+          tools: [{ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } }],
+        }),
+      ).pipe(Effect.provide(fixedResponse(body)))
+
+      expect(response.events).toEqual([
+        { type: "tool-input-delta", id: "call_1", name: "lookup", text: '{"query"' },
+        { type: "tool-input-delta", id: "call_1", name: "lookup", text: ':"weather"}' },
+        { type: "tool-call", id: "call_1", name: "lookup", input: { query: "weather" } },
+        { type: "request-finish", reason: "tool-calls", usage: undefined },
+      ])
+    }),
+  )
+
+  it.effect("does not finalize streamed tool calls without a finish reason", () =>
+    Effect.gen(function* () {
+      const body = sseEvents(
+        deltaChunk({
+          role: "assistant",
+          tool_calls: [{ index: 0, id: "call_1", function: { name: "lookup", arguments: '{"query"' } }],
+        }),
+        deltaChunk({ tool_calls: [{ index: 0, function: { arguments: ':"weather"}' } }] }),
+      )
+      const response = yield* LLMClient.generate(
+        LLM.updateRequest(request, {
+          tools: [{ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } }],
+        }),
+      ).pipe(Effect.provide(fixedResponse(body)))
+
+      expect(response.events).toEqual([
+        { type: "tool-input-delta", id: "call_1", name: "lookup", text: '{"query"' },
+        { type: "tool-input-delta", id: "call_1", name: "lookup", text: ':"weather"}' },
+      ])
+      expect(response.toolCalls).toEqual([])
+    }),
+  )
+
+  it.effect("fails on malformed stream events", () =>
+    Effect.gen(function* () {
+      const body = sseEvents(deltaChunk({ content: 123 }))
+      const error = yield* LLMClient.generate(request).pipe(Effect.provide(fixedResponse(body)), Effect.flip)
+
+      expect(error.message).toContain("Invalid openai/openai-chat stream event")
+    }),
+  )
+
+  it.effect("surfaces transport errors that occur mid-stream", () =>
+    Effect.gen(function* () {
+      const layer = truncatedStream([
+        `data: ${JSON.stringify(deltaChunk({ role: "assistant", content: "Hello" }))}\n\n`,
+      ])
+      const error = yield* LLMClient.generate(request).pipe(Effect.provide(layer), Effect.flip)
+
+      expect(error.message).toContain("Failed to read openai/openai-chat stream")
+    }),
+  )
+
+  it.effect("fails HTTP provider errors before stream parsing", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.generate(request).pipe(
+        Effect.provide(
+          fixedResponse('{"error":{"message":"Bad request","type":"invalid_request_error"}}', {
+            status: 400,
+            headers: { "content-type": "application/json" },
+          }),
+        ),
+        Effect.flip,
+      )
+
+      expect(error).toBeInstanceOf(LLMError)
+      expect(error.reason).toMatchObject({ _tag: "InvalidRequest" })
+      expect(error.message).toContain("HTTP 400")
+    }),
+  )
+
+  it.effect("short-circuits the upstream stream when the consumer takes a prefix", () =>
+    Effect.gen(function* () {
+      // The body has more chunks than we'll consume. If `Stream.take(1)` did
+      // not interrupt the upstream HTTP body the test would hang waiting for
+      // the rest of the stream to drain.
+      const body = sseEvents(
+        deltaChunk({ role: "assistant", content: "Hello" }),
+        deltaChunk({ content: " world" }),
+        deltaChunk({}, "stop"),
+      )
+
+      const events = Array.from(
+        yield* LLMClient.stream(request).pipe(Stream.take(1), Stream.runCollect, Effect.provide(fixedResponse(body))),
+      )
+      expect(events.map((event) => event.type)).toEqual(["text-delta"])
+    }),
+  )
+})

packages/llm/test/provider/openai-compatible-chat.test.ts

@@ -0,0 +1,237 @@
+import { describe, expect } from "bun:test"
+import { Effect, Schema } from "effect"
+import { HttpClientRequest } from "effect/unstable/http"
+import { LLM } from "../../src"
+import { LLMClient } from "../../src/route"
+import * as OpenAICompatible from "../../src/providers/openai-compatible"
+import * as OpenAICompatibleChat from "../../src/protocols/openai-compatible-chat"
+import { it } from "../lib/effect"
+import { dynamicResponse } from "../lib/http"
+import { sseEvents } from "../lib/sse"
+
+const Json = Schema.fromJsonString(Schema.Unknown)
+const decodeJson = Schema.decodeUnknownSync(Json)
+
+const model = OpenAICompatibleChat.model({
+  id: "deepseek-chat",
+  provider: "deepseek",
+  baseURL: "https://api.deepseek.test/v1/",
+  apiKey: "test-key",
+  queryParams: { "api-version": "2026-01-01" },
+})
+
+const request = LLM.request({
+  id: "req_1",
+  model,
+  system: "You are concise.",
+  prompt: "Say hello.",
+  generation: { maxTokens: 20, temperature: 0 },
+})
+
+const deltaChunk = (delta: object, finishReason: string | null = null) => ({
+  id: "chatcmpl_fixture",
+  choices: [{ delta, finish_reason: finishReason }],
+  usage: null,
+})
+
+const usageChunk = (usage: object) => ({
+  id: "chatcmpl_fixture",
+  choices: [],
+  usage,
+})
+
+const providerFamilies = [
+  ["baseten", OpenAICompatible.baseten, "https://inference.baseten.co/v1"],
+  ["cerebras", OpenAICompatible.cerebras, "https://api.cerebras.ai/v1"],
+  ["deepinfra", OpenAICompatible.deepinfra, "https://api.deepinfra.com/v1/openai"],
+  ["deepseek", OpenAICompatible.deepseek, "https://api.deepseek.com/v1"],
+  ["fireworks", OpenAICompatible.fireworks, "https://api.fireworks.ai/inference/v1"],
+  ["togetherai", OpenAICompatible.togetherai, "https://api.together.xyz/v1"],
+] as const
+
+describe("OpenAI-compatible Chat route", () => {
+  it.effect("prepares generic Chat target", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.updateRequest(request, {
+          tools: [{ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } }],
+          toolChoice: { type: "required" },
+        }),
+      )
+
+      expect(prepared.route).toBe("openai-compatible-chat")
+      expect(prepared.model).toMatchObject({
+        id: "deepseek-chat",
+        provider: "deepseek",
+        route: "openai-compatible-chat",
+        baseURL: "https://api.deepseek.test/v1/",
+        apiKey: "test-key",
+        queryParams: { "api-version": "2026-01-01" },
+      })
+      expect(prepared.body).toEqual({
+        model: "deepseek-chat",
+        messages: [
+          { role: "system", content: "You are concise." },
+          { role: "user", content: "Say hello." },
+        ],
+        tools: [
+          {
+            type: "function",
+            function: { name: "lookup", description: "Lookup data", parameters: { type: "object" } },
+          },
+        ],
+        tool_choice: "required",
+        stream: true,
+        stream_options: { include_usage: true },
+        max_tokens: 20,
+        temperature: 0,
+      })
+    }),
+  )
+
+  it.effect("provides model helpers for compatible provider families", () =>
+    Effect.gen(function* () {
+      expect(
+        providerFamilies.map(([provider, family]) => {
+          const model = family.model(`${provider}-model`, { apiKey: "test-key" })
+          return {
+            id: String(model.id),
+            provider: String(model.provider),
+            route: model.route,
+            baseURL: model.baseURL,
+            apiKey: model.apiKey,
+          }
+        }),
+      ).toEqual(
+        providerFamilies.map(([provider, _, baseURL]) => ({
+          id: `${provider}-model`,
+          provider,
+          route: "openai-compatible-chat",
+          baseURL,
+          apiKey: "test-key",
+        })),
+      )
+
+      const custom = OpenAICompatible.deepseek.model("deepseek-chat", {
+        apiKey: "test-key",
+        baseURL: "https://custom.deepseek.test/v1",
+      })
+      expect(custom).toMatchObject({
+        provider: "deepseek",
+        route: "openai-compatible-chat",
+        baseURL: "https://custom.deepseek.test/v1",
+      })
+    }),
+  )
+
+  it.effect("matches AI SDK compatible basic request body fixture", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(request)
+
+      expect(prepared.body).toEqual({
+        model: "deepseek-chat",
+        messages: [
+          { role: "system", content: "You are concise." },
+          { role: "user", content: "Say hello." },
+        ],
+        stream: true,
+        stream_options: { include_usage: true },
+        max_tokens: 20,
+        temperature: 0,
+      })
+    }),
+  )
+
+  it.effect("matches AI SDK compatible tool request body fixture", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_tool_parity",
+          model,
+          tools: [
+            {
+              name: "lookup",
+              description: "Lookup data",
+              inputSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
+            },
+          ],
+          toolChoice: "lookup",
+          messages: [
+            LLM.user("What is the weather?"),
+            LLM.assistant([LLM.toolCall({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
+            LLM.toolMessage({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
+          ],
+        }),
+      )
+
+      expect(prepared.body).toEqual({
+        model: "deepseek-chat",
+        messages: [
+          { role: "user", content: "What is the weather?" },
+          {
+            role: "assistant",
+            content: null,
+            tool_calls: [
+              {
+                id: "call_1",
+                type: "function",
+                function: { name: "lookup", arguments: '{"query":"weather"}' },
+              },
+            ],
+          },
+          { role: "tool", tool_call_id: "call_1", content: '{"forecast":"sunny"}' },
+        ],
+        tools: [
+          {
+            type: "function",
+            function: {
+              name: "lookup",
+              description: "Lookup data",
+              parameters: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
+            },
+          },
+        ],
+        tool_choice: { type: "function", function: { name: "lookup" } },
+        stream: true,
+        stream_options: { include_usage: true },
+      })
+    }),
+  )
+
+  it.effect("posts to the configured compatible endpoint and parses text usage", () =>
+    Effect.gen(function* () {
+      const response = yield* LLMClient.generate(request).pipe(
+        Effect.provide(
+          dynamicResponse((input) =>
+            Effect.gen(function* () {
+              const web = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+              expect(web.url).toBe("https://api.deepseek.test/v1/chat/completions?api-version=2026-01-01")
+              expect(web.headers.get("authorization")).toBe("Bearer test-key")
+              expect(decodeJson(input.text)).toMatchObject({
+                model: "deepseek-chat",
+                stream: true,
+                messages: [
+                  { role: "system", content: "You are concise." },
+                  { role: "user", content: "Say hello." },
+                ],
+              })
+              return input.respond(
+                sseEvents(
+                  deltaChunk({ role: "assistant", content: "Hello" }),
+                  deltaChunk({ content: "!" }),
+                  deltaChunk({}, "stop"),
+                  usageChunk({ prompt_tokens: 5, completion_tokens: 2, total_tokens: 7 }),
+                ),
+                { headers: { "content-type": "text/event-stream" } },
+              )
+            }),
+          ),
+        ),
+      )
+
+      expect(response.text).toBe("Hello!")
+      expect(response.usage).toMatchObject({ inputTokens: 5, outputTokens: 2, totalTokens: 7 })
+      expect(response.events.at(-1)).toMatchObject({ type: "request-finish", reason: "stop" })
+    }),
+  )
+})

packages/llm/test/provider/openai-responses.test.ts

@@ -0,0 +1,549 @@
+import { describe, expect } from "bun:test"
+import { ConfigProvider, Effect, Layer, Stream } from "effect"
+import { Headers, HttpClientRequest } from "effect/unstable/http"
+import { LLM, LLMError } from "../../src"
+import { Auth, LLMClient, RequestExecutor, WebSocketExecutor } from "../../src/route"
+import * as Azure from "../../src/providers/azure"
+import * as OpenAI from "../../src/providers/openai"
+import * as OpenAIResponses from "../../src/protocols/openai-responses"
+import * as ProviderShared from "../../src/protocols/shared"
+import { it } from "../lib/effect"
+import { dynamicResponse, fixedResponse } from "../lib/http"
+import { sseEvents } from "../lib/sse"
+
+const model = OpenAIResponses.model({
+  id: "gpt-4.1-mini",
+  baseURL: "https://api.openai.test/v1/",
+  headers: { authorization: "Bearer test" },
+})
+
+const request = LLM.request({
+  id: "req_1",
+  model,
+  system: "You are concise.",
+  prompt: "Say hello.",
+  generation: { maxTokens: 20, temperature: 0 },
+})
+
+const configEnv = (env: Record<string, string>) => Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnv({ env })))
+
+describe("OpenAI Responses route", () => {
+  it.effect("prepares OpenAI Responses target", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(request)
+
+      expect(prepared.body).toEqual({
+        model: "gpt-4.1-mini",
+        input: [
+          { role: "system", content: "You are concise." },
+          { role: "user", content: [{ type: "input_text", text: "Say hello." }] },
+        ],
+        stream: true,
+        max_output_tokens: 20,
+        temperature: 0,
+      })
+    }),
+  )
+
+  it.effect("prepares OpenAI Responses WebSocket target", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.updateRequest(request, {
+          model: OpenAI.responsesWebSocket("gpt-4.1-mini", { baseURL: "https://api.openai.test/v1/", apiKey: "test" }),
+        }),
+      )
+
+      expect(prepared.route).toBe("openai-responses-websocket")
+      expect(prepared.protocol).toBe("openai-responses")
+      expect(prepared.metadata).toEqual({ transport: "websocket-json" })
+      expect(prepared.body).toMatchObject({ model: "gpt-4.1-mini", stream: true })
+    }),
+  )
+
+  it.effect("streams OpenAI Responses over WebSocket", () =>
+    Effect.gen(function* () {
+      const sent: string[] = []
+      const opened: Array<{ readonly url: string; readonly authorization: string | undefined }> = []
+      let closed = false
+      const deps = Layer.mergeAll(
+        Layer.succeed(
+          RequestExecutor.Service,
+          RequestExecutor.Service.of({
+            execute: () => Effect.die("unexpected HTTP request"),
+          }),
+        ),
+        Layer.succeed(
+          WebSocketExecutor.Service,
+          WebSocketExecutor.Service.of({
+            open: (input) =>
+              Effect.succeed({
+                sendText: (message) =>
+                  Effect.sync(() => {
+                    opened.push({ url: input.url, authorization: input.headers.authorization })
+                    sent.push(message)
+                  }),
+                messages: Stream.fromArray([
+                  ProviderShared.encodeJson({ type: "response.output_text.delta", item_id: "msg_1", delta: "Hi" }),
+                  ProviderShared.encodeJson({ type: "response.completed", response: { id: "resp_ws" } }),
+                ]),
+                close: Effect.sync(() => {
+                  closed = true
+                }),
+              }),
+          }),
+        ),
+      )
+      const response = yield* LLMClient.generate(
+        LLM.request({
+          model: OpenAI.responsesWebSocket("gpt-4.1-mini", { baseURL: "https://api.openai.test/v1/", apiKey: "test" }),
+          prompt: "Say hello.",
+        }),
+      ).pipe(Effect.provide(LLMClient.layerWithWebSocket.pipe(Layer.provide(deps))))
+
+      expect(response.text).toBe("Hi")
+      expect(opened).toEqual([{ url: "wss://api.openai.test/v1/responses", authorization: "Bearer test" }])
+      expect(closed).toBe(true)
+      expect(sent).toHaveLength(1)
+      expect(JSON.parse(sent[0])).toEqual({
+        type: "response.create",
+        model: "gpt-4.1-mini",
+        input: [{ role: "user", content: [{ type: "input_text", text: "Say hello." }] }],
+        store: false,
+      })
+    }),
+  )
+
+  it.effect("requires WebSocket runtime for OpenAI Responses WebSocket", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.generate(
+        LLM.request({
+          model: OpenAI.responsesWebSocket("gpt-4.1-mini", { baseURL: "https://api.openai.test/v1/", apiKey: "test" }),
+          prompt: "Say hello.",
+        }),
+      ).pipe(
+        Effect.provide(
+          LLMClient.layer.pipe(
+            Layer.provide(
+              Layer.succeed(
+                RequestExecutor.Service,
+                RequestExecutor.Service.of({
+                  execute: () => Effect.die("unexpected HTTP request"),
+                }),
+              ),
+            ),
+          ),
+        ),
+        Effect.flip,
+      )
+
+      expect(error.message).toContain("requires WebSocketExecutor.Service")
+    }),
+  )
+
+  it.effect("fails immediately when WebSocket is already closed", () =>
+    Effect.gen(function* () {
+      const error = yield* WebSocketExecutor.fromWebSocket(
+        { readyState: globalThis.WebSocket.CLOSED } as globalThis.WebSocket,
+        { url: "wss://api.openai.test/v1/responses", headers: Headers.empty },
+      ).pipe(Effect.flip)
+
+      expect(error.message).toContain("closed before opening")
+    }),
+  )
+
+  it.effect("adds native query params to the Responses URL", () =>
+    Effect.gen(function* () {
+      yield* LLMClient.generate(
+        LLM.updateRequest(request, {
+          model: OpenAIResponses.model({ ...model, queryParams: { "api-version": "v1" } }),
+        }),
+      ).pipe(
+        Effect.provide(
+          dynamicResponse((input) =>
+            Effect.gen(function* () {
+              const web = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+              expect(web.url).toBe("https://api.openai.test/v1/responses?api-version=v1")
+              return input.respond(sseEvents({ type: "response.completed", response: {} }), {
+                headers: { "content-type": "text/event-stream" },
+              })
+            }),
+          ),
+        ),
+      )
+    }),
+  )
+
+  it.effect("uses Azure api-key header for static OpenAI Responses keys", () =>
+    Effect.gen(function* () {
+      yield* LLMClient.generate(
+        LLM.updateRequest(request, {
+          model: Azure.responses("gpt-4.1-mini", {
+            baseURL: "https://opencode-test.openai.azure.com/openai/v1/",
+            apiKey: "azure-key",
+            headers: { authorization: "Bearer stale" },
+          }),
+        }),
+      ).pipe(
+        Effect.provide(
+          dynamicResponse((input) =>
+            Effect.gen(function* () {
+              const web = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+              expect(web.headers.get("api-key")).toBe("azure-key")
+              expect(web.headers.get("authorization")).toBeNull()
+              return input.respond(sseEvents({ type: "response.completed", response: {} }), {
+                headers: { "content-type": "text/event-stream" },
+              })
+            }),
+          ),
+        ),
+      )
+    }),
+  )
+
+  it.effect("loads OpenAI default auth from Effect Config", () =>
+    LLMClient.generate(
+      LLM.updateRequest(request, {
+        model: OpenAI.responses("gpt-4.1-mini", { baseURL: "https://api.openai.test/v1/" }),
+      }),
+    ).pipe(
+      configEnv({ OPENAI_API_KEY: "env-key" }),
+      Effect.provide(
+        dynamicResponse((input) =>
+          Effect.gen(function* () {
+            const web = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+            expect(web.headers.get("authorization")).toBe("Bearer env-key")
+            return input.respond(sseEvents({ type: "response.completed", response: {} }), {
+              headers: { "content-type": "text/event-stream" },
+            })
+          }),
+        ),
+      ),
+    ),
+  )
+
+  it.effect("lets explicit auth override OpenAI default API key auth", () =>
+    LLMClient.generate(
+      LLM.updateRequest(request, {
+        model: OpenAI.responses("gpt-4.1-mini", {
+          baseURL: "https://api.openai.test/v1/",
+          auth: Auth.bearer("oauth-token"),
+        }),
+      }),
+    ).pipe(
+      Effect.provide(
+        dynamicResponse((input) =>
+          Effect.gen(function* () {
+            const web = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+            expect(web.headers.get("authorization")).toBe("Bearer oauth-token")
+            return input.respond(sseEvents({ type: "response.completed", response: {} }), {
+              headers: { "content-type": "text/event-stream" },
+            })
+          }),
+        ),
+      ),
+    ),
+  )
+
+  it.effect("prepares function call and function output input items", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_tool_result",
+          model,
+          messages: [
+            LLM.user("What is the weather?"),
+            LLM.assistant([LLM.toolCall({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
+            LLM.toolMessage({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
+          ],
+        }),
+      )
+
+      expect(prepared.body).toEqual({
+        model: "gpt-4.1-mini",
+        input: [
+          { role: "user", content: [{ type: "input_text", text: "What is the weather?" }] },
+          { type: "function_call", call_id: "call_1", name: "lookup", arguments: '{"query":"weather"}' },
+          { type: "function_call_output", call_id: "call_1", output: '{"forecast":"sunny"}' },
+        ],
+        stream: true,
+      })
+    }),
+  )
+
+  it.effect("maps OpenAI provider options to Responses options", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+        LLM.request({
+          model: OpenAI.model("gpt-5.2", { baseURL: "https://api.openai.test/v1/" }),
+          prompt: "think",
+          providerOptions: {
+            openai: {
+              promptCacheKey: "session_123",
+              reasoningEffort: "high",
+              reasoningSummary: "auto",
+              includeEncryptedReasoning: true,
+            },
+          },
+        }),
+      )
+
+      expect(prepared.body.store).toBe(false)
+      expect(prepared.body.prompt_cache_key).toBe("session_123")
+      expect(prepared.body.include).toEqual(["reasoning.encrypted_content"])
+      expect(prepared.body.reasoning).toEqual({ effort: "high", summary: "auto" })
+      expect(prepared.body.text).toEqual({ verbosity: "low" })
+    }),
+  )
+
+  it.effect("request OpenAI provider options override model defaults", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<OpenAIResponses.OpenAIResponsesBody>(
+        LLM.request({
+          model: OpenAI.model("gpt-4.1-mini", {
+            baseURL: "https://api.openai.test/v1/",
+            providerOptions: { openai: { promptCacheKey: "model_cache" } },
+          }),
+          prompt: "no cache",
+          providerOptions: { openai: { promptCacheKey: "request_cache" } },
+        }),
+      )
+
+      expect(prepared.body.prompt_cache_key).toBe("request_cache")
+    }),
+  )
+
+  it.effect("parses text and usage stream fixtures", () =>
+    Effect.gen(function* () {
+      const body = sseEvents(
+        { type: "response.output_text.delta", item_id: "msg_1", delta: "Hello" },
+        { type: "response.output_text.delta", item_id: "msg_1", delta: "!" },
+        {
+          type: "response.completed",
+          response: {
+            id: "resp_1",
+            service_tier: "default",
+            usage: {
+              input_tokens: 5,
+              output_tokens: 2,
+              total_tokens: 7,
+              input_tokens_details: { cached_tokens: 1 },
+              output_tokens_details: { reasoning_tokens: 0 },
+            },
+          },
+        },
+      )
+      const response = yield* LLMClient.generate(request).pipe(Effect.provide(fixedResponse(body)))
+
+      expect(response.text).toBe("Hello!")
+      expect(response.events).toEqual([
+        { type: "text-delta", id: "msg_1", text: "Hello", providerMetadata: { openai: { itemId: "msg_1" } } },
+        { type: "text-delta", id: "msg_1", text: "!", providerMetadata: { openai: { itemId: "msg_1" } } },
+        {
+          type: "request-finish",
+          reason: "stop",
+          providerMetadata: { openai: { responseId: "resp_1", serviceTier: "default" } },
+          usage: {
+            inputTokens: 5,
+            outputTokens: 2,
+            reasoningTokens: 0,
+            cacheReadInputTokens: 1,
+            totalTokens: 7,
+            native: {
+              input_tokens: 5,
+              output_tokens: 2,
+              total_tokens: 7,
+              input_tokens_details: { cached_tokens: 1 },
+              output_tokens_details: { reasoning_tokens: 0 },
+            },
+          },
+        },
+      ])
+    }),
+  )
+
+  it.effect("assembles streamed function call input", () =>
+    Effect.gen(function* () {
+      const body = sseEvents(
+        {
+          type: "response.output_item.added",
+          item: { type: "function_call", id: "item_1", call_id: "call_1", name: "lookup", arguments: "" },
+        },
+        { type: "response.function_call_arguments.delta", item_id: "item_1", delta: '{"query"' },
+        { type: "response.function_call_arguments.delta", item_id: "item_1", delta: ':"weather"}' },
+        {
+          type: "response.output_item.done",
+          item: {
+            type: "function_call",
+            id: "item_1",
+            call_id: "call_1",
+            name: "lookup",
+            arguments: '{"query":"weather"}',
+          },
+        },
+        { type: "response.completed", response: { usage: { input_tokens: 5, output_tokens: 1 } } },
+      )
+      const response = yield* LLMClient.generate(
+        LLM.updateRequest(request, {
+          tools: [{ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } }],
+        }),
+      ).pipe(Effect.provide(fixedResponse(body)))
+
+      expect(response.events).toEqual([
+        {
+          type: "tool-input-delta",
+          id: "call_1",
+          name: "lookup",
+          text: '{"query"',
+          providerMetadata: { openai: { itemId: "item_1" } },
+        },
+        {
+          type: "tool-input-delta",
+          id: "call_1",
+          name: "lookup",
+          text: ':"weather"}',
+          providerMetadata: { openai: { itemId: "item_1" } },
+        },
+        {
+          type: "tool-call",
+          id: "call_1",
+          name: "lookup",
+          input: { query: "weather" },
+          providerMetadata: { openai: { itemId: "item_1" } },
+        },
+        {
+          type: "request-finish",
+          reason: "tool-calls",
+          usage: { inputTokens: 5, outputTokens: 1, totalTokens: 6, native: { input_tokens: 5, output_tokens: 1 } },
+        },
+      ])
+    }),
+  )
+
+  it.effect("decodes web_search_call as provider-executed tool-call + tool-result", () =>
+    Effect.gen(function* () {
+      const item = {
+        type: "web_search_call",
+        id: "ws_1",
+        status: "completed",
+        action: { type: "search", query: "effect 4" },
+      }
+      const body = sseEvents(
+        { type: "response.output_item.added", item },
+        { type: "response.output_item.done", item },
+        { type: "response.completed", response: { usage: { input_tokens: 5, output_tokens: 1 } } },
+      )
+      const response = yield* LLMClient.generate(request).pipe(Effect.provide(fixedResponse(body)))
+
+      const callsAndResults = response.events.filter(
+        (event) => event.type === "tool-call" || event.type === "tool-result",
+      )
+      expect(callsAndResults).toEqual([
+        {
+          type: "tool-call",
+          id: "ws_1",
+          name: "web_search",
+          input: { type: "search", query: "effect 4" },
+          providerExecuted: true,
+          providerMetadata: { openai: { itemId: "ws_1" } },
+        },
+        {
+          type: "tool-result",
+          id: "ws_1",
+          name: "web_search",
+          result: { type: "json", value: item },
+          providerExecuted: true,
+          providerMetadata: { openai: { itemId: "ws_1" } },
+        },
+      ])
+    }),
+  )
+
+  it.effect("decodes code_interpreter_call as provider-executed events with code input", () =>
+    Effect.gen(function* () {
+      const item = {
+        type: "code_interpreter_call",
+        id: "ci_1",
+        status: "completed",
+        code: "print(1+1)",
+        container_id: "cnt_xyz",
+        outputs: [{ type: "logs", logs: "2\n" }],
+      }
+      const body = sseEvents(
+        { type: "response.output_item.done", item },
+        { type: "response.completed", response: { usage: { input_tokens: 5, output_tokens: 1 } } },
+      )
+      const response = yield* LLMClient.generate(request).pipe(Effect.provide(fixedResponse(body)))
+
+      const toolCall = response.events.find((event) => event.type === "tool-call")
+      expect(toolCall).toEqual({
+        type: "tool-call",
+        id: "ci_1",
+        name: "code_interpreter",
+        input: { code: "print(1+1)", container_id: "cnt_xyz" },
+        providerExecuted: true,
+        providerMetadata: { openai: { itemId: "ci_1" } },
+      })
+      const toolResult = response.events.find((event) => event.type === "tool-result")
+      expect(toolResult).toEqual({
+        type: "tool-result",
+        id: "ci_1",
+        name: "code_interpreter",
+        result: { type: "json", value: item },
+        providerExecuted: true,
+        providerMetadata: { openai: { itemId: "ci_1" } },
+      })
+    }),
+  )
+
+  it.effect("rejects unsupported user media content", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_media",
+          model,
+          messages: [LLM.user({ type: "media", mediaType: "image/png", data: "AAECAw==" })],
+        }),
+      ).pipe(Effect.flip)
+
+      expect(error.message).toContain("OpenAI Responses user messages only support text content for now")
+    }),
+  )
+
+  it.effect("emits provider-error events for mid-stream provider errors", () =>
+    Effect.gen(function* () {
+      const response = yield* LLMClient.generate(request).pipe(
+        Effect.provide(fixedResponse(sseEvents({ type: "error", code: "rate_limit_exceeded", message: "Slow down" }))),
+      )
+
+      expect(response.events).toEqual([{ type: "provider-error", message: "Slow down" }])
+    }),
+  )
+
+  it.effect("falls back to error code when no message is present", () =>
+    Effect.gen(function* () {
+      const response = yield* LLMClient.generate(request).pipe(
+        Effect.provide(fixedResponse(sseEvents({ type: "error", code: "internal_error" }))),
+      )
+
+      expect(response.events).toEqual([{ type: "provider-error", message: "internal_error" }])
+    }),
+  )
+
+  it.effect("fails HTTP provider errors before stream parsing", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.generate(request).pipe(
+        Effect.provide(
+          fixedResponse('{"error":{"type":"invalid_request_error","message":"Bad request"}}', {
+            status: 400,
+            headers: { "content-type": "application/json" },
+          }),
+        ),
+        Effect.flip,
+      )
+
+      expect(error).toBeInstanceOf(LLMError)
+      expect(error.reason).toMatchObject({ _tag: "InvalidRequest" })
+      expect(error.message).toContain("HTTP 400")
+    }),
+  )
+})

packages/llm/test/provider/openrouter.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { LLM } from "../../src"
+import { LLMClient } from "../../src/route"
+import * as OpenRouter from "../../src/providers/openrouter"
+import { it } from "../lib/effect"
+
+describe("OpenRouter", () => {
+  it.effect("prepares OpenRouter models through the OpenAI-compatible Chat route", () =>
+    Effect.gen(function* () {
+      const model = OpenRouter.model("openai/gpt-4o-mini", { apiKey: "test-key" })
+
+      expect(model).toMatchObject({
+        id: "openai/gpt-4o-mini",
+        provider: "openrouter",
+        route: "openrouter",
+        baseURL: "https://openrouter.ai/api/v1",
+        apiKey: "test-key",
+      })
+
+      const prepared = yield* LLMClient.prepare(LLM.request({ model, prompt: "Say hello." }))
+
+      expect(prepared.route).toBe("openrouter")
+      expect(prepared.body).toMatchObject({
+        model: "openai/gpt-4o-mini",
+        messages: [{ role: "user", content: "Say hello." }],
+        stream: true,
+      })
+    }),
+  )
+
+  it.effect("applies OpenRouter payload options from the model helper", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model: OpenRouter.model("anthropic/claude-3.7-sonnet:thinking", {
+            providerOptions: {
+              openrouter: {
+                usage: true,
+                reasoning: { effort: "high" },
+                promptCacheKey: "session_123",
+              },
+            },
+          }),
+          prompt: "Think briefly.",
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        usage: { include: true },
+        reasoning: { effort: "high" },
+        prompt_cache_key: "session_123",
+      })
+    }),
+  )
+})

packages/llm/test/recorded-golden.ts

@@ -0,0 +1,103 @@
+import type { HttpRecorder } from "@opencode-ai/http-recorder"
+import { describe, type TestOptions } from "bun:test"
+import { Effect } from "effect"
+import type { ModelRef } from "../src"
+import { goldenScenarioTags, runGoldenScenario, type GoldenScenarioID } from "./recorded-scenarios"
+import { recordedTests } from "./recorded-test"
+import { kebab } from "./recorded-utils"
+
+type Transport = "http" | "websocket"
+
+type ScenarioInput =
+  | GoldenScenarioID
+  | {
+      readonly id: GoldenScenarioID
+      readonly name?: string
+      readonly cassette?: string
+      readonly tags?: ReadonlyArray<string>
+      readonly maxTokens?: number
+      readonly temperature?: number | false
+      readonly timeout?: number | TestOptions
+    }
+
+type TargetInput = {
+  readonly name: string
+  readonly model: ModelRef
+  readonly protocol?: string
+  readonly requires?: ReadonlyArray<string>
+  readonly transport?: Transport
+  readonly prefix?: string
+  readonly tags?: ReadonlyArray<string>
+  readonly metadata?: Record<string, unknown>
+  readonly options?: HttpRecorder.RecordReplayOptions
+  readonly scenarios: ReadonlyArray<ScenarioInput>
+}
+
+const scenarioInput = (input: ScenarioInput) => (typeof input === "string" ? { id: input } : input)
+
+const scenarioTitle = (id: GoldenScenarioID) => {
+  if (id === "text") return "streams text"
+  if (id === "tool-call") return "streams tool call"
+  return "drives a tool loop"
+}
+
+const defaultPrefix = (target: TargetInput) => {
+  if (target.prefix) return target.prefix
+  const transport = target.transport === "websocket" ? "-websocket" : ""
+  return `${target.model.provider}-${target.protocol ?? target.model.route}${transport}`
+}
+
+const metadata = (target: TargetInput) => ({
+  provider: target.model.provider,
+  protocol: target.protocol,
+  route: target.model.route,
+  transport: target.transport ?? "http",
+  model: target.model.id,
+  ...target.metadata,
+})
+
+const tags = (target: TargetInput) => [
+  ...(target.transport === "websocket" ? ["transport:websocket"] : []),
+  ...(target.tags ?? []),
+]
+
+const runTarget = (target: TargetInput) => {
+  const recorded = recordedTests({
+    prefix: defaultPrefix(target),
+    provider: target.model.provider,
+    protocol: target.protocol,
+    requires: target.requires,
+    tags: tags(target),
+    metadata: metadata(target),
+    options: target.options,
+  })
+
+  describe(`${target.name} recorded`, () => {
+    target.scenarios.forEach((raw) => {
+      const input = scenarioInput(raw)
+      const name = input.name ?? scenarioTitle(input.id)
+      recorded.effect.with(
+        name,
+        {
+          cassette: input.cassette,
+          id: `${kebab(target.name)}-${input.id}`,
+          tags: [...goldenScenarioTags(input.id), ...(input.tags ?? [])],
+        },
+        () =>
+          Effect.gen(function* () {
+            yield* runGoldenScenario(input.id, {
+              id: `recorded_${kebab(target.name).replaceAll("-", "_")}_${input.id.replaceAll("-", "_")}`,
+              model: target.model,
+              maxTokens: input.maxTokens,
+              temperature: input.temperature,
+            })
+          }),
+        input.timeout,
+      )
+    })
+  })
+}
+
+export const describeRecordedGoldenScenarios = (targets: ReadonlyArray<TargetInput>) => {
+  targets.forEach(runTarget)
+}

packages/llm/test/recorded-runner.ts

@@ -0,0 +1,100 @@
+import { test, type TestOptions } from "bun:test"
+import { Effect, type Layer } from "effect"
+import { testEffect } from "./lib/effect"
+import { cassetteName, classifiedTags, matchesSelected, missingEnv, unique } from "./recorded-utils"
+
+export type RecordedBody<A, E, R> = Effect.Effect<A, E, R> | (() => Effect.Effect<A, E, R>)
+
+export type RecordedGroupOptions = {
+  readonly prefix: string
+  readonly provider?: string
+  readonly protocol?: string
+  readonly requires?: ReadonlyArray<string>
+  readonly tags?: ReadonlyArray<string>
+  readonly metadata?: Record<string, unknown>
+}
+
+export type RecordedCaseOptions = {
+  readonly cassette?: string
+  readonly id?: string
+  readonly provider?: string
+  readonly protocol?: string
+  readonly requires?: ReadonlyArray<string>
+  readonly tags?: ReadonlyArray<string>
+  readonly metadata?: Record<string, unknown>
+}
+
+export const recordedEffectGroup = <
+  R,
+  E,
+  Options extends RecordedGroupOptions,
+  CaseOptions extends RecordedCaseOptions,
+>(input: {
+  readonly duplicateLabel: string
+  readonly options: Options
+  readonly cassetteExists: (cassette: string) => boolean
+  readonly layer: (input: {
+    readonly cassette: string
+    readonly tags: ReadonlyArray<string>
+    readonly metadata: Record<string, unknown>
+    readonly recording: boolean
+    readonly options: Options
+    readonly caseOptions: CaseOptions
+  }) => Layer.Layer<R, E>
+}) => {
+  const cassettes = new Set<string>()
+
+  const run = <A, E2>(
+    name: string,
+    caseOptions: CaseOptions,
+    body: RecordedBody<A, E2, R>,
+    testOptions?: number | TestOptions,
+  ) => {
+    const cassette = cassetteName(input.options.prefix, name, caseOptions)
+    if (cassettes.has(cassette)) throw new Error(`Duplicate ${input.duplicateLabel} "${cassette}"`)
+    cassettes.add(cassette)
+    const tags = unique([
+      ...classifiedTags(input.options),
+      ...classifiedTags({
+        provider: caseOptions.provider,
+        protocol: caseOptions.protocol,
+        tags: caseOptions.tags,
+      }),
+    ])
+
+    if (!matchesSelected({ prefix: input.options.prefix, name, cassette, tags }))
+      return test.skip(name, () => {}, testOptions)
+
+    const recording = process.env.RECORD === "true"
+    if (recording) {
+      if (missingEnv([...(input.options.requires ?? []), ...(caseOptions.requires ?? [])]).length > 0) {
+        return test.skip(name, () => {}, testOptions)
+      }
+    } else if (!input.cassetteExists(cassette)) {
+      return test.skip(name, () => {}, testOptions)
+    }
+
+    return testEffect(
+      input.layer({
+        cassette,
+        tags,
+        metadata: { ...input.options.metadata, ...caseOptions.metadata, tags },
+        recording,
+        options: input.options,
+        caseOptions,
+      }),
+    ).live(name, body, testOptions)
+  }
+
+  const effect = <A, E2>(name: string, body: RecordedBody<A, E2, R>, testOptions?: number | TestOptions) =>
+    run(name, {} as CaseOptions, body, testOptions)
+
+  effect.with = <A, E2>(
+    name: string,
+    caseOptions: CaseOptions,
+    body: RecordedBody<A, E2, R>,
+    testOptions?: number | TestOptions,
+  ) => run(name, caseOptions, body, testOptions)
+
+  return { effect }
+}

packages/llm/test/recorded-scenarios.ts

@@ -0,0 +1,265 @@
+import { expect } from "bun:test"
+import { Effect, Schema, Stream } from "effect"
+import { LLM, LLMEvent, LLMResponse, type LLMRequest, type ModelRef } from "../src"
+import { LLMClient } from "../src/route"
+import { tool } from "../src/tool"
+
+export const weatherToolName = "get_weather"
+
+export const weatherTool = LLM.toolDefinition({
+  name: weatherToolName,
+  description: "Get current weather for a city.",
+  inputSchema: {
+    type: "object",
+    properties: { city: { type: "string" } },
+    required: ["city"],
+    additionalProperties: false,
+  },
+})
+
+export const weatherRuntimeTool = tool({
+  description: weatherTool.description,
+  parameters: Schema.Struct({ city: Schema.String }),
+  success: Schema.Struct({ temperature: Schema.Number, condition: Schema.String }),
+  execute: ({ city }) =>
+    Effect.succeed(
+      city === "Paris" ? { temperature: 22, condition: "sunny" } : { temperature: 0, condition: "unknown" },
+    ),
+})
+
+export const textRequest = (input: {
+  readonly id: string
+  readonly model: ModelRef
+  readonly prompt?: string
+  readonly maxTokens?: number
+  readonly temperature?: number | false
+}) =>
+  LLM.request({
+    id: input.id,
+    model: input.model,
+    system: "You are concise.",
+    prompt: input.prompt ?? "Reply with exactly: Hello!",
+    generation:
+      input.temperature === false
+        ? { maxTokens: input.maxTokens ?? 20 }
+        : { maxTokens: input.maxTokens ?? 20, temperature: input.temperature ?? 0 },
+  })
+
+export const weatherToolRequest = (input: {
+  readonly id: string
+  readonly model: ModelRef
+  readonly maxTokens?: number
+  readonly temperature?: number | false
+}) =>
+  LLM.request({
+    id: input.id,
+    model: input.model,
+    system: "Call tools exactly as requested.",
+    prompt: "Call get_weather with city exactly Paris.",
+    tools: [weatherTool],
+    toolChoice: LLM.toolChoice(weatherTool),
+    generation:
+      input.temperature === false
+        ? { maxTokens: input.maxTokens ?? 80 }
+        : { maxTokens: input.maxTokens ?? 80, temperature: input.temperature ?? 0 },
+  })
+
+export const weatherToolLoopRequest = (input: {
+  readonly id: string
+  readonly model: ModelRef
+  readonly system?: string
+  readonly maxTokens?: number
+  readonly temperature?: number | false
+}) =>
+  LLM.request({
+    id: input.id,
+    model: input.model,
+    system: input.system ?? "Use the get_weather tool, then answer in one short sentence.",
+    prompt: "What is the weather in Paris?",
+    generation:
+      input.temperature === false
+        ? { maxTokens: input.maxTokens ?? 80 }
+        : { maxTokens: input.maxTokens ?? 80, temperature: input.temperature ?? 0 },
+  })
+
+export const goldenWeatherToolLoopRequest = (input: {
+  readonly id: string
+  readonly model: ModelRef
+  readonly maxTokens?: number
+  readonly temperature?: number | false
+}) =>
+  weatherToolLoopRequest({
+    ...input,
+    system: "Use the get_weather tool exactly once. After the tool result, reply exactly: Paris is sunny.",
+  })
+
+export const runWeatherToolLoop = (request: LLMRequest) =>
+  LLMClient.stream({
+    request,
+    tools: { [weatherToolName]: weatherRuntimeTool },
+    stopWhen: LLMClient.stepCountIs(10),
+  }).pipe(
+    Stream.runCollect,
+    Effect.map((events) => Array.from(events)),
+  )
+
+export const expectFinish = (
+  events: ReadonlyArray<LLMEvent>,
+  reason: Extract<LLMEvent, { readonly type: "request-finish" }>["reason"],
+) => expect(events.at(-1)).toMatchObject({ type: "request-finish", reason })
+
+export const expectWeatherToolCall = (response: LLMResponse) =>
+  expect(response.toolCalls).toMatchObject([
+    { type: "tool-call", id: expect.any(String), name: weatherToolName, input: { city: "Paris" } },
+  ])
+
+export const expectWeatherToolLoop = (events: ReadonlyArray<LLMEvent>) => {
+  const finishes = events.filter(LLMEvent.is.requestFinish)
+  expect(finishes).toHaveLength(2)
+  expect(finishes[0]?.reason).toBe("tool-calls")
+  expect(finishes.at(-1)?.reason).toBe("stop")
+
+  const toolCalls = events.filter(LLMEvent.is.toolCall)
+  expect(toolCalls).toHaveLength(1)
+  expect(toolCalls[0]).toMatchObject({ type: "tool-call", name: weatherToolName, input: { city: "Paris" } })
+
+  const toolResults = events.filter(LLMEvent.is.toolResult)
+  expect(toolResults).toHaveLength(1)
+  expect(toolResults[0]).toMatchObject({
+    type: "tool-result",
+    name: weatherToolName,
+    result: { type: "json", value: { temperature: 22, condition: "sunny" } },
+  })
+
+  const output = LLMResponse.text({ events })
+  expect(output).toContain("Paris")
+  expect(output.trim().length).toBeGreaterThan(0)
+}
+
+export const expectGoldenWeatherToolLoop = (events: ReadonlyArray<LLMEvent>) => {
+  expectWeatherToolLoop(events)
+  expect(LLMResponse.text({ events }).trim()).toMatch(/^Paris is sunny\.?$/)
+}
+
+export type GoldenScenarioID = "text" | "tool-call" | "tool-loop"
+
+export interface GoldenScenarioContext {
+  readonly id: string
+  readonly model: ModelRef
+  readonly maxTokens?: number
+  readonly temperature?: number | false
+}
+
+const generate = (request: LLMRequest) => LLMClient.generate(request)
+
+export const goldenScenarioTags = (id: GoldenScenarioID) => {
+  if (id === "text") return ["text", "golden"]
+  if (id === "tool-call") return ["tool", "tool-call", "golden"]
+  return ["tool", "tool-loop", "golden"]
+}
+
+export const runGoldenScenario = (id: GoldenScenarioID, context: GoldenScenarioContext) =>
+  Effect.gen(function* () {
+    if (id === "text") {
+      const response = yield* generate(
+        textRequest({
+          id: context.id,
+          model: context.model,
+          prompt: "Reply exactly with: Hello!",
+          maxTokens: context.maxTokens ?? 40,
+          temperature: context.temperature,
+        }),
+      )
+      expect(response.text.trim()).toMatch(/^Hello!?$/)
+      expectFinish(response.events, "stop")
+      return
+    }
+
+    if (id === "tool-call") {
+      const response = yield* generate(
+        weatherToolRequest({
+          id: context.id,
+          model: context.model,
+          maxTokens: context.maxTokens ?? 80,
+          temperature: context.temperature,
+        }),
+      )
+      expectWeatherToolCall(response)
+      expectFinish(response.events, "tool-calls")
+      return
+    }
+
+    expectGoldenWeatherToolLoop(
+      yield* runWeatherToolLoop(
+        goldenWeatherToolLoopRequest({
+          id: context.id,
+          model: context.model,
+          maxTokens: context.maxTokens ?? 80,
+          temperature: context.temperature,
+        }),
+      ),
+    )
+  })
+
+const usageSummary = (usage: LLMResponse["usage"] | undefined) => {
+  if (!usage) return undefined
+  return Object.fromEntries(
+    [
+      ["inputTokens", usage.inputTokens],
+      ["outputTokens", usage.outputTokens],
+      ["reasoningTokens", usage.reasoningTokens],
+      ["cacheReadInputTokens", usage.cacheReadInputTokens],
+      ["cacheWriteInputTokens", usage.cacheWriteInputTokens],
+      ["totalTokens", usage.totalTokens],
+    ].filter((entry) => entry[1] !== undefined),
+  )
+}
+
+const pushText = (summary: Array<Record<string, unknown>>, type: "text" | "reasoning", value: string) => {
+  const last = summary.at(-1)
+  if (last?.type === type) {
+    last.value = `${last.value ?? ""}${value}`
+    return
+  }
+  summary.push({ type, value })
+}
+
+export const eventSummary = (events: ReadonlyArray<LLMEvent>) => {
+  const summary: Array<Record<string, unknown>> = []
+  for (const event of events) {
+    if (event.type === "text-delta") {
+      pushText(summary, "text", event.text)
+      continue
+    }
+    if (event.type === "reasoning-delta") {
+      pushText(summary, "reasoning", event.text)
+      continue
+    }
+    if (event.type === "tool-call") {
+      summary.push({
+        type: "tool-call",
+        name: event.name,
+        input: event.input,
+        providerExecuted: event.providerExecuted,
+      })
+      continue
+    }
+    if (event.type === "tool-result") {
+      summary.push({
+        type: "tool-result",
+        name: event.name,
+        result: event.result,
+        providerExecuted: event.providerExecuted,
+      })
+      continue
+    }
+    if (event.type === "tool-error") {
+      summary.push({ type: "tool-error", name: event.name, message: event.message })
+      continue
+    }
+    if (event.type === "request-finish") {
+      summary.push({ type: "finish", reason: event.reason, usage: usageSummary(event.usage) })
+    }
+  }
+  return summary.map((item) => Object.fromEntries(Object.entries(item).filter((entry) => entry[1] !== undefined)))
+}

packages/llm/test/recorded-test.ts

@@ -0,0 +1,76 @@
+import { NodeFileSystem } from "@effect/platform-node"
+import { HttpRecorder } from "@opencode-ai/http-recorder"
+import { Layer } from "effect"
+import { FetchHttpClient } from "effect/unstable/http"
+import * as path from "node:path"
+import { fileURLToPath } from "node:url"
+import { LLMClient, RequestExecutor } from "../src/route"
+import type { Service as LLMClientService } from "../src/route/client"
+import type { Service as RequestExecutorService } from "../src/route/executor"
+import type { Service as WebSocketExecutorService } from "../src/route/transport/websocket"
+import {
+  recordedEffectGroup,
+  type RecordedCaseOptions as RunnerCaseOptions,
+  type RecordedGroupOptions,
+} from "./recorded-runner"
+import { webSocketCassetteLayer } from "./recorded-websocket"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const FIXTURES_DIR = path.resolve(__dirname, "fixtures", "recordings")
+
+type RecordedEnv = RequestExecutorService | WebSocketExecutorService | LLMClientService
+
+type RecordedTestsOptions = RecordedGroupOptions & {
+  readonly options?: HttpRecorder.RecordReplayOptions
+}
+
+type RecordedCaseOptions = RunnerCaseOptions & {
+  readonly options?: HttpRecorder.RecordReplayOptions
+}
+
+const mergeOptions = (
+  base: HttpRecorder.RecordReplayOptions | undefined,
+  override: HttpRecorder.RecordReplayOptions | undefined,
+) => {
+  if (!base) return override
+  if (!override) return base
+  return {
+    ...base,
+    ...override,
+    metadata: base.metadata || override.metadata ? { ...base.metadata, ...override.metadata } : undefined,
+  }
+}
+
+export const recordedTests = (options: RecordedTestsOptions) =>
+  recordedEffectGroup<RecordedEnv, never, RecordedTestsOptions, RecordedCaseOptions>({
+    duplicateLabel: "recorded cassette",
+    options,
+    cassetteExists: (cassette) => HttpRecorder.hasCassetteSync(cassette, { directory: FIXTURES_DIR }),
+    layer: ({ cassette, metadata, options, caseOptions, recording }) => {
+      const recorderOptions = mergeOptions(options.options, caseOptions.options)
+      const recorderMetadata = {
+        ...recorderOptions?.metadata,
+        ...metadata,
+      }
+      const mode = recorderOptions?.mode ?? (recording ? "record" : "replay")
+      const cassetteService = HttpRecorder.Cassette.layer({ directory: FIXTURES_DIR }).pipe(
+        Layer.provide(NodeFileSystem.layer),
+      )
+      const requestExecutor = RequestExecutor.layer.pipe(
+        Layer.provide(
+          HttpRecorder.recordingLayer(cassette, {
+            ...recorderOptions,
+            mode,
+            metadata: recorderMetadata,
+          }).pipe(Layer.provide(FetchHttpClient.layer)),
+        ),
+      )
+      const deps = Layer.mergeAll(
+        requestExecutor,
+        webSocketCassetteLayer(cassette, { metadata: recorderMetadata, mode }),
+      )
+      return Layer.mergeAll(deps, LLMClient.layerWithWebSocket.pipe(Layer.provide(deps))).pipe(
+        Layer.provide(cassetteService),
+      )
+    },
+  })

packages/llm/test/recorded-utils.ts

@@ -0,0 +1,56 @@
+export const kebab = (value: string) =>
+  value
+    .trim()
+    .replace(/['"]/g, "")
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .toLowerCase()
+
+export const missingEnv = (names: ReadonlyArray<string>) => names.filter((name) => !process.env[name])
+
+export const envList = (name: string) =>
+  (process.env[name] ?? "")
+    .split(",")
+    .map((item) => item.trim().toLowerCase())
+    .filter((item) => item !== "")
+
+export const unique = (items: ReadonlyArray<string>) => Array.from(new Set(items))
+
+export const classifiedTags = (input: {
+  readonly prefix?: string
+  readonly provider?: string
+  readonly protocol?: string
+  readonly tags?: ReadonlyArray<string>
+}) =>
+  unique([
+    ...(input.prefix ? [`prefix:${input.prefix}`] : []),
+    ...(input.provider ? [`provider:${input.provider}`] : []),
+    ...(input.protocol ? [`protocol:${input.protocol}`] : []),
+    ...(input.tags ?? []),
+  ])
+
+export const matchesSelected = (input: {
+  readonly prefix: string
+  readonly name: string
+  readonly cassette: string
+  readonly tags: ReadonlyArray<string>
+}) => {
+  const prefixes = envList("RECORDED_PREFIX")
+  const providers = envList("RECORDED_PROVIDER")
+  const requiredTags = envList("RECORDED_TAGS")
+  const tests = envList("RECORDED_TEST")
+  const tags = input.tags.map((tag) => tag.toLowerCase())
+  const names = [input.name, kebab(input.name), input.cassette].map((item) => item.toLowerCase())
+
+  if (prefixes.length > 0 && !prefixes.includes(input.prefix.toLowerCase())) return false
+  if (providers.length > 0 && !providers.some((provider) => tags.includes(`provider:${provider}`))) return false
+  if (requiredTags.length > 0 && !requiredTags.every((tag) => tags.includes(tag))) return false
+  if (tests.length > 0 && !tests.some((test) => names.some((name) => name.includes(test)))) return false
+  return true
+}
+
+export const cassetteName = (
+  prefix: string,
+  name: string,
+  options: { readonly cassette?: string; readonly id?: string },
+) => options.cassette ?? `${prefix}/${options.id ?? kebab(name)}`

packages/llm/test/recorded-websocket.ts

@@ -0,0 +1,27 @@
+import { Cassette, makeWebSocketExecutor } from "@opencode-ai/http-recorder"
+import { Effect, Layer } from "effect"
+import { WebSocketExecutor } from "../src/route"
+import type { Service as WebSocketExecutorService } from "../src/route/transport/websocket"
+
+const liveWebSocket = WebSocketExecutor.open
+type Mode = "record" | "replay" | "passthrough"
+
+export const webSocketCassetteLayer = (
+  cassette: string,
+  input: { readonly metadata?: Record<string, unknown>; readonly mode: Mode },
+): Layer.Layer<WebSocketExecutorService, never, Cassette.Service> =>
+  Layer.effect(
+    WebSocketExecutor.Service,
+    Effect.gen(function* () {
+      const cassetteService = yield* Cassette.Service
+      const executor = yield* makeWebSocketExecutor({
+        name: cassette,
+        mode: input.mode,
+        metadata: input.metadata,
+        cassette: cassetteService,
+        live: { open: liveWebSocket },
+        compareClientMessagesAsJson: true,
+      })
+      return WebSocketExecutor.Service.of(executor)
+    }),
+  )

packages/llm/test/schema.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test"
+import { Schema } from "effect"
+import {
+  ContentPart,
+  LLMEvent,
+  LLMRequest,
+  ModelID,
+  ModelLimits,
+  ModelRef,
+  ProviderID,
+} from "../src/schema"
+
+const model = new ModelRef({
+  id: ModelID.make("fake-model"),
+  provider: ProviderID.make("fake-provider"),
+  route: "openai-chat",
+  baseURL: "https://fake.local",
+  limits: new ModelLimits({}),
+})
+
+describe("llm schema", () => {
+  test("decodes a minimal request", () => {
+    const input: unknown = {
+      id: "req_1",
+      model,
+      system: [{ type: "text", text: "You are terse." }],
+      messages: [{ role: "user", content: [{ type: "text", text: "hi" }] }],
+      tools: [],
+      generation: {},
+    }
+
+    const decoded = Schema.decodeUnknownSync(LLMRequest)(input)
+
+    expect(decoded.id).toBe("req_1")
+    expect(decoded.messages[0]?.content[0]?.type).toBe("text")
+  })
+
+  test("accepts custom route ids", () => {
+    const decoded = Schema.decodeUnknownSync(LLMRequest)({
+      model: { ...model, route: "custom-route" },
+      system: [],
+      messages: [],
+      tools: [],
+      generation: {},
+    })
+
+    expect(decoded.model.route).toBe("custom-route")
+  })
+
+  test("rejects invalid event type", () => {
+    expect(() => Schema.decodeUnknownSync(LLMEvent)({ type: "bogus" })).toThrow()
+  })
+
+  test("content part tagged union exposes guards", () => {
+    expect(ContentPart.guards.text({ type: "text", text: "hi" })).toBe(true)
+    expect(ContentPart.guards.media({ type: "text", text: "hi" })).toBe(false)
+  })
+})

packages/llm/test/tool-runtime.test.ts

@@ -0,0 +1,454 @@
+import { describe, expect } from "bun:test"
+import { Effect, Schema, Stream } from "effect"
+import { LLM, LLMEvent, LLMRequest, LLMResponse } from "../src"
+import { LLMClient } from "../src/route"
+import * as AnthropicMessages from "../src/protocols/anthropic-messages"
+import * as OpenAIChat from "../src/protocols/openai-chat"
+import { tool, ToolFailure } from "../src/tool"
+import { it } from "./lib/effect"
+import * as TestToolRuntime from "./lib/tool-runtime"
+import { dynamicResponse, scriptedResponses } from "./lib/http"
+import { deltaChunk, finishChunk, toolCallChunk } from "./lib/openai-chunks"
+import { sseEvents } from "./lib/sse"
+
+const model = OpenAIChat.model({
+  id: "gpt-4o-mini",
+  baseURL: "https://api.openai.test/v1/",
+  headers: { authorization: "Bearer test" },
+})
+const Json = Schema.fromJsonString(Schema.Unknown)
+const decodeJson = Schema.decodeUnknownSync(Json)
+
+const baseRequest = LLM.request({
+  id: "req_1",
+  model,
+  prompt: "Use the tool.",
+})
+
+const get_weather = tool({
+  description: "Get current weather for a city.",
+  parameters: Schema.Struct({ city: Schema.String }),
+  success: Schema.Struct({ temperature: Schema.Number, condition: Schema.String }),
+  execute: ({ city }) =>
+    Effect.gen(function* () {
+      if (city === "FAIL") return yield* new ToolFailure({ message: `Weather lookup failed for ${city}` })
+      return { temperature: 22, condition: "sunny" }
+    }),
+})
+
+const schema_only_weather = tool({
+  description: "Get current weather for a city.",
+  parameters: Schema.Struct({ city: Schema.String }),
+  success: Schema.Struct({ temperature: Schema.Number, condition: Schema.String }),
+})
+
+describe("LLMClient tools", () => {
+  it.effect("uses the registered model route when adding runtime tools", () =>
+    Effect.gen(function* () {
+      const layer = scriptedResponses([
+        sseEvents(deltaChunk({ role: "assistant", content: "Done." }), finishChunk("stop")),
+      ])
+
+      const events = Array.from(
+        yield* TestToolRuntime.runTools({ request: baseRequest, tools: { get_weather } }).pipe(
+          Stream.runCollect,
+          Effect.provide(layer),
+        ),
+      )
+
+      expect(LLMResponse.text({ events })).toBe("Done.")
+    }),
+  )
+
+  it.effect("sends tool-call history and request options on the follow-up request", () =>
+    Effect.gen(function* () {
+      const bodies: unknown[] = []
+      const responses = [
+        sseEvents(toolCallChunk("call_1", "get_weather", '{"city":"Paris"}'), finishChunk("tool_calls")),
+        sseEvents(deltaChunk({ role: "assistant", content: "It's sunny in Paris." }), finishChunk("stop")),
+      ]
+      const layer = dynamicResponse((input) =>
+        Effect.sync(() => {
+          bodies.push(decodeJson(input.text))
+          return input.respond(responses[bodies.length - 1] ?? responses[responses.length - 1], {
+            headers: { "content-type": "text/event-stream" },
+          })
+        }),
+      )
+
+      yield* TestToolRuntime.runTools({
+        request: LLMRequest.update(baseRequest, {
+          generation: LLM.generation({ maxTokens: 50 }),
+          toolChoice: LLM.toolChoice("auto"),
+        }),
+        tools: { get_weather },
+      }).pipe(Stream.runCollect, Effect.provide(layer))
+
+      const second = bodies[1] as {
+        readonly messages?: ReadonlyArray<Record<string, unknown>>
+        readonly tools?: ReadonlyArray<unknown>
+        readonly tool_choice?: unknown
+        readonly max_tokens?: unknown
+      }
+
+      expect(second.max_tokens).toBe(50)
+      expect(second.tool_choice).toBe("auto")
+      expect(second.tools).toHaveLength(1)
+      expect(second.messages?.map((message) => message.role)).toEqual(["user", "assistant", "tool"])
+      expect(second.messages?.[1]).toMatchObject({
+        role: "assistant",
+        content: null,
+        tool_calls: [{ id: "call_1", type: "function", function: { name: "get_weather" } }],
+      })
+      expect(second.messages?.[2]).toMatchObject({
+        role: "tool",
+        tool_call_id: "call_1",
+        content: '{"temperature":22,"condition":"sunny"}',
+      })
+    }),
+  )
+
+  it.effect("dispatches a tool call, appends results, and resumes streaming", () =>
+    Effect.gen(function* () {
+      const layer = scriptedResponses([
+        sseEvents(toolCallChunk("call_1", "get_weather", '{"city":"Paris"}'), finishChunk("tool_calls")),
+        sseEvents(deltaChunk({ role: "assistant", content: "It's sunny in Paris." }), finishChunk("stop")),
+      ])
+
+      const events = Array.from(
+        yield* TestToolRuntime.runTools({ request: baseRequest, tools: { get_weather } }).pipe(
+          Stream.runCollect,
+          Effect.provide(layer),
+        ),
+      )
+
+      const result = events.find(LLMEvent.is.toolResult)
+      expect(result).toMatchObject({
+        type: "tool-result",
+        id: "call_1",
+        name: "get_weather",
+        result: { type: "json", value: { temperature: 22, condition: "sunny" } },
+      })
+      expect(events.at(-1)?.type).toBe("request-finish")
+      expect(LLMResponse.text({ events })).toBe("It's sunny in Paris.")
+    }),
+  )
+
+  it.effect("executes tool calls for one step without looping by default", () =>
+    Effect.gen(function* () {
+      const layer = scriptedResponses([
+        sseEvents(toolCallChunk("call_1", "get_weather", '{"city":"Paris"}'), finishChunk("tool_calls")),
+        sseEvents(deltaChunk({ role: "assistant", content: "Should not run." }), finishChunk("stop")),
+      ])
+
+      const events = Array.from(
+        yield* LLMClient.stream({ request: baseRequest, tools: { get_weather } }).pipe(
+          Stream.runCollect,
+          Effect.provide(layer),
+        ),
+      )
+
+      expect(events.filter(LLMEvent.is.requestFinish)).toHaveLength(1)
+      expect(events.find(LLMEvent.is.toolResult)).toMatchObject({ type: "tool-result", id: "call_1" })
+    }),
+  )
+
+  it.effect("can expose tool schemas without executing tool calls", () =>
+    Effect.gen(function* () {
+      const layer = scriptedResponses([
+        sseEvents(toolCallChunk("call_1", "get_weather", '{"city":"Paris"}'), finishChunk("tool_calls")),
+      ])
+
+      const events = Array.from(
+        yield* LLMClient.stream({
+          request: baseRequest,
+          tools: { get_weather: schema_only_weather },
+          toolExecution: "none",
+        }).pipe(Stream.runCollect, Effect.provide(layer)),
+      )
+
+      expect(events.find(LLMEvent.is.toolCall)).toMatchObject({ type: "tool-call", id: "call_1" })
+      expect(events.find(LLMEvent.is.toolResult)).toBeUndefined()
+    }),
+  )
+
+  it.effect("preserves provider metadata when folding streamed assistant content into follow-up history", () =>
+    Effect.gen(function* () {
+      const bodies: unknown[] = []
+      const layer = dynamicResponse((input) =>
+        Effect.sync(() => {
+          bodies.push(decodeJson(input.text))
+          return input.respond(
+            bodies.length === 1
+              ? sseEvents(
+                  { type: "message_start", message: { usage: { input_tokens: 5 } } },
+                  { type: "content_block_start", index: 0, content_block: { type: "thinking", thinking: "" } },
+                  { type: "content_block_delta", index: 0, delta: { type: "thinking_delta", thinking: "thinking" } },
+                  { type: "content_block_delta", index: 0, delta: { type: "signature_delta", signature: "sig_1" } },
+                  { type: "content_block_stop", index: 0 },
+                  {
+                    type: "content_block_start",
+                    index: 1,
+                    content_block: { type: "tool_use", id: "call_1", name: "get_weather" },
+                  },
+                  {
+                    type: "content_block_delta",
+                    index: 1,
+                    delta: { type: "input_json_delta", partial_json: '{"city":"Paris"}' },
+                  },
+                  { type: "content_block_stop", index: 1 },
+                  { type: "message_delta", delta: { stop_reason: "tool_use" }, usage: { output_tokens: 5 } },
+                )
+              : sseEvents(
+                  { type: "message_start", message: { usage: { input_tokens: 5 } } },
+                  { type: "content_block_start", index: 0, content_block: { type: "text", text: "" } },
+                  { type: "content_block_delta", index: 0, delta: { type: "text_delta", text: "Done." } },
+                  { type: "content_block_stop", index: 0 },
+                  { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 1 } },
+                ),
+            { headers: { "content-type": "text/event-stream" } },
+          )
+        }),
+      )
+
+      yield* TestToolRuntime.runTools({
+        request: LLM.updateRequest(baseRequest, {
+          model: AnthropicMessages.model({ id: "claude-sonnet-4-5", apiKey: "test" }),
+        }),
+        tools: { get_weather },
+      }).pipe(Stream.runCollect, Effect.provide(layer))
+
+      expect(bodies[1]).toMatchObject({
+        messages: [
+          { role: "user" },
+          {
+            role: "assistant",
+            content: [
+              { type: "thinking", thinking: "thinking", signature: "sig_1" },
+              { type: "tool_use", id: "call_1", name: "get_weather", input: { city: "Paris" } },
+            ],
+          },
+          { role: "user", content: [{ type: "tool_result", tool_use_id: "call_1" }] },
+        ],
+      })
+    }),
+  )
+
+  it.effect("emits tool-error for unknown tools so the model can self-correct", () =>
+    Effect.gen(function* () {
+      const layer = scriptedResponses([
+        sseEvents(toolCallChunk("call_1", "missing_tool", "{}"), finishChunk("tool_calls")),
+        sseEvents(deltaChunk({ role: "assistant", content: "Sorry." }), finishChunk("stop")),
+      ])
+
+      const events = Array.from(
+        yield* TestToolRuntime.runTools({ request: baseRequest, tools: { get_weather } }).pipe(
+          Stream.runCollect,
+          Effect.provide(layer),
+        ),
+      )
+
+      const toolError = events.find(LLMEvent.is.toolError)
+      expect(toolError).toMatchObject({ type: "tool-error", id: "call_1", name: "missing_tool" })
+      expect(toolError?.message).toContain("Unknown tool")
+      expect(events.find(LLMEvent.is.toolResult)).toMatchObject({
+        type: "tool-result",
+        id: "call_1",
+        name: "missing_tool",
+        result: { type: "error", value: "Unknown tool: missing_tool" },
+      })
+    }),
+  )
+
+  it.effect("emits tool-error when the LLM input fails the parameters schema", () =>
+    Effect.gen(function* () {
+      const layer = scriptedResponses([
+        sseEvents(toolCallChunk("call_1", "get_weather", '{"city":42}'), finishChunk("tool_calls")),
+        sseEvents(deltaChunk({ role: "assistant", content: "Done." }), finishChunk("stop")),
+      ])
+
+      const events = Array.from(
+        yield* TestToolRuntime.runTools({ request: baseRequest, tools: { get_weather } }).pipe(
+          Stream.runCollect,
+          Effect.provide(layer),
+        ),
+      )
+
+      const toolError = events.find(LLMEvent.is.toolError)
+      expect(toolError).toMatchObject({ type: "tool-error", id: "call_1", name: "get_weather" })
+      expect(toolError?.message).toContain("Invalid tool input")
+    }),
+  )
+
+  it.effect("emits tool-error when the handler returns a ToolFailure", () =>
+    Effect.gen(function* () {
+      const layer = scriptedResponses([
+        sseEvents(toolCallChunk("call_1", "get_weather", '{"city":"FAIL"}'), finishChunk("tool_calls")),
+        sseEvents(deltaChunk({ role: "assistant", content: "Sorry." }), finishChunk("stop")),
+      ])
+
+      const events = Array.from(
+        yield* TestToolRuntime.runTools({ request: baseRequest, tools: { get_weather } }).pipe(
+          Stream.runCollect,
+          Effect.provide(layer),
+        ),
+      )
+
+      const toolError = events.find(LLMEvent.is.toolError)
+      expect(toolError).toMatchObject({ type: "tool-error", id: "call_1", name: "get_weather" })
+      expect(toolError?.message).toBe("Weather lookup failed for FAIL")
+    }),
+  )
+
+  it.effect("stops when the model finishes without requesting more tools", () =>
+    Effect.gen(function* () {
+      const layer = scriptedResponses([
+        sseEvents(deltaChunk({ role: "assistant", content: "Done." }), finishChunk("stop")),
+      ])
+
+      const events = Array.from(
+        yield* TestToolRuntime.runTools({ request: baseRequest, tools: { get_weather } }).pipe(
+          Stream.runCollect,
+          Effect.provide(layer),
+        ),
+      )
+
+      expect(events.map((event) => event.type)).toEqual(["text-delta", "request-finish"])
+      expect(LLMResponse.text({ events })).toBe("Done.")
+    }),
+  )
+
+  it.effect("respects maxSteps and stops the loop", () =>
+    Effect.gen(function* () {
+      // Every script entry asks for another tool call. With maxSteps: 2 the
+      // runtime should run at most two model rounds and then exit even though
+      // the model still wants to keep going.
+      const toolCallStep = sseEvents(
+        toolCallChunk("call_x", "get_weather", '{"city":"Paris"}'),
+        finishChunk("tool_calls"),
+      )
+      const layer = scriptedResponses([toolCallStep, toolCallStep, toolCallStep])
+
+      const events = Array.from(
+        yield* TestToolRuntime.runTools({ request: baseRequest, tools: { get_weather }, maxSteps: 2 }).pipe(
+          Stream.runCollect,
+          Effect.provide(layer),
+        ),
+      )
+
+      expect(events.filter(LLMEvent.is.requestFinish)).toHaveLength(2)
+    }),
+  )
+
+  it.effect("stops follow-up when stopWhen returns true after the first step", () =>
+    Effect.gen(function* () {
+      const layer = scriptedResponses([
+        sseEvents(toolCallChunk("call_1", "get_weather", '{"city":"Paris"}'), finishChunk("tool_calls")),
+        sseEvents(deltaChunk({ role: "assistant", content: "Should not run." }), finishChunk("stop")),
+      ])
+
+      const events = Array.from(
+        yield* TestToolRuntime.runTools({
+          request: baseRequest,
+          tools: { get_weather },
+          stopWhen: (state) => state.step >= 0,
+        }).pipe(Stream.runCollect, Effect.provide(layer)),
+      )
+
+      expect(events.filter(LLMEvent.is.requestFinish)).toHaveLength(1)
+      expect(events.find(LLMEvent.is.toolResult)).toMatchObject({ type: "tool-result", id: "call_1" })
+    }),
+  )
+
+  it.effect("does not dispatch provider-executed tool calls", () =>
+    Effect.gen(function* () {
+      let streams = 0
+      const layer = dynamicResponse((input) =>
+        Effect.sync(() => {
+          streams++
+          return input.respond(
+            sseEvents(
+              { type: "message_start", message: { usage: { input_tokens: 5 } } },
+              {
+                type: "content_block_start",
+                index: 0,
+                content_block: { type: "server_tool_use", id: "srvtoolu_abc", name: "web_search" },
+              },
+              {
+                type: "content_block_delta",
+                index: 0,
+                delta: { type: "input_json_delta", partial_json: '{"query":"x"}' },
+              },
+              { type: "content_block_stop", index: 0 },
+              {
+                type: "content_block_start",
+                index: 1,
+                content_block: {
+                  type: "web_search_tool_result",
+                  tool_use_id: "srvtoolu_abc",
+                  content: [{ type: "web_search_result", url: "https://example.com", title: "Example" }],
+                },
+              },
+              { type: "content_block_stop", index: 1 },
+              { type: "content_block_start", index: 2, content_block: { type: "text", text: "" } },
+              { type: "content_block_delta", index: 2, delta: { type: "text_delta", text: "Done." } },
+              { type: "content_block_stop", index: 2 },
+              { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 8 } },
+            ),
+            { headers: { "content-type": "text/event-stream" } },
+          )
+        }),
+      )
+      const events = Array.from(
+        yield* TestToolRuntime.runTools({
+          request: LLM.updateRequest(baseRequest, {
+            model: AnthropicMessages.model({ id: "claude-sonnet-4-5", apiKey: "test" }),
+          }),
+          tools: {},
+        }).pipe(Stream.runCollect, Effect.provide(layer)),
+      )
+
+      expect(streams).toBe(1)
+      expect(events.find(LLMEvent.is.toolError)).toBeUndefined()
+      expect(events.filter(LLMEvent.is.toolCall)).toEqual([
+        {
+          type: "tool-call",
+          id: "srvtoolu_abc",
+          name: "web_search",
+          input: { query: "x" },
+          providerExecuted: true,
+        },
+      ])
+      expect(LLMResponse.text({ events })).toBe("Done.")
+    }),
+  )
+
+  it.effect("dispatches multiple tool calls in one step concurrently", () =>
+    Effect.gen(function* () {
+      const layer = scriptedResponses([
+        sseEvents(
+          deltaChunk({
+            role: "assistant",
+            tool_calls: [
+              { index: 0, id: "c1", function: { name: "get_weather", arguments: '{"city":"Paris"}' } },
+              { index: 1, id: "c2", function: { name: "get_weather", arguments: '{"city":"Tokyo"}' } },
+            ],
+          }),
+          finishChunk("tool_calls"),
+        ),
+        sseEvents(deltaChunk({ role: "assistant", content: "Both done." }), finishChunk("stop")),
+      ])
+
+      const events = Array.from(
+        yield* TestToolRuntime.runTools({ request: baseRequest, tools: { get_weather } }).pipe(
+          Stream.runCollect,
+          Effect.provide(layer),
+        ),
+      )
+
+      const results = events.filter(LLMEvent.is.toolResult)
+      expect(results).toHaveLength(2)
+      expect(results.map((event) => event.id).toSorted()).toEqual(["c1", "c2"])
+    }),
+  )
+})

packages/llm/test/tool-stream.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { LLMError } from "../src/schema"
+import { ToolStream } from "../src/protocols/utils/tool-stream"
+import { it } from "./lib/effect"
+
+const ADAPTER = "test-route"
+
+describe("ToolStream", () => {
+  it.effect("starts from OpenAI-style deltas and finalizes parsed input", () =>
+    Effect.gen(function* () {
+      const first = ToolStream.appendOrStart(
+        ADAPTER,
+        ToolStream.empty<number>(),
+        0,
+        { id: "call_1", name: "lookup", text: '{"query"' },
+        "missing tool",
+      )
+      if (ToolStream.isError(first)) return yield* first
+      const second = ToolStream.appendOrStart(ADAPTER, first.tools, 0, { text: ':"weather"}' }, "missing tool")
+      if (ToolStream.isError(second)) return yield* second
+      const finished = yield* ToolStream.finish(ADAPTER, second.tools, 0)
+
+      expect(first.event).toEqual({ type: "tool-input-delta", id: "call_1", name: "lookup", text: '{"query"' })
+      expect(second.event).toEqual({ type: "tool-input-delta", id: "call_1", name: "lookup", text: ':"weather"}' })
+      expect(finished).toEqual({
+        tools: {},
+        event: { type: "tool-call", id: "call_1", name: "lookup", input: { query: "weather" } },
+      })
+    }),
+  )
+
+  it.effect("fails appendExisting when the provider skipped the tool start", () =>
+    Effect.gen(function* () {
+      const error = ToolStream.appendExisting(ADAPTER, ToolStream.empty<number>(), 0, "{}", "missing tool")
+
+      expect(error).toBeInstanceOf(LLMError)
+      if (ToolStream.isError(error)) expect(error.reason.message).toBe("missing tool")
+    }),
+  )
+
+  it.effect("uses final input override without losing accumulated deltas", () =>
+    Effect.gen(function* () {
+      const tools = ToolStream.start(ToolStream.empty<string>(), "item_1", {
+        id: "call_1",
+        name: "lookup",
+        input: '{"query":"partial"}',
+      })
+      const finished = yield* ToolStream.finishWithInput(ADAPTER, tools, "item_1", '{"query":"final"}')
+
+      expect(finished).toEqual({
+        tools: {},
+        event: { type: "tool-call", id: "call_1", name: "lookup", input: { query: "final" } },
+      })
+    }),
+  )
+
+  it.effect("preserves providerExecuted and clears all tools", () =>
+    Effect.gen(function* () {
+      const first: ToolStream.State<number> = ToolStream.start(ToolStream.empty<number>(), 0, {
+        id: "call_1",
+        name: "lookup",
+        input: "{}",
+      })
+      const tools = ToolStream.start(first, 1, {
+        id: "call_2",
+        name: "web_search",
+        input: '{"query":"docs"}',
+        providerExecuted: true,
+      })
+      const finished = yield* ToolStream.finishAll(ADAPTER, tools)
+
+      expect(finished).toEqual({
+        tools: {},
+        events: [
+          { type: "tool-call", id: "call_1", name: "lookup", input: {} },
+          {
+            type: "tool-call",
+            id: "call_2",
+            name: "web_search",
+            input: { query: "docs" },
+            providerExecuted: true,
+          },
+        ],
+      })
+    }),
+  )
+})

packages/llm/test/tool.types.ts

@@ -0,0 +1,29 @@
+import { Effect, Schema } from "effect"
+import { LLM } from "../src"
+import * as OpenAIChat from "../src/protocols/openai-chat"
+import { tool } from "../src/tool"
+
+const request = LLM.request({
+  model: OpenAIChat.model({ id: "gpt-4o-mini", apiKey: "fixture" }),
+  prompt: "Use the tool.",
+})
+
+const executable = tool({
+  description: "Get weather.",
+  parameters: Schema.Struct({ city: Schema.String }),
+  success: Schema.Struct({ forecast: Schema.String }),
+  execute: (input) => Effect.succeed({ forecast: input.city }),
+})
+
+const schemaOnly = tool({
+  description: "Get weather.",
+  parameters: Schema.Struct({ city: Schema.String }),
+  success: Schema.Struct({ forecast: Schema.String }),
+})
+
+LLM.stream({ request, tools: { executable } })
+LLM.generate({ request, tools: { executable }, stopWhen: LLM.stepCountIs(2) })
+LLM.stream({ request, tools: { schemaOnly }, toolExecution: "none" })
+
+// @ts-expect-error Handler-less tools can only be passed with toolExecution: "none".
+LLM.stream({ request, tools: { schemaOnly } })