refactor(ai): rename llm package

packages/ai/test/adapter.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect } from "bun:test"
+import { Effect, Schema, Stream } from "effect"
+import { LLM, LLMResponse } from "../src"
+import { Route, Endpoint, LLMClient, Protocol, type FramingDef } from "../src/route"
+import { Model } from "../src/schema"
+import { testEffect } from "./lib/effect"
+import { dynamicResponse } from "./lib/http"
+
+const updateModel = (model: Model, patch: Partial<Model.Input>) => Model.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 raiseEvent = (event: FakeEvent): import("../src/schema").LLMEvent =>
+  event.type === "finish"
+    ? { type: "finish", reason: event.reason }
+    : { type: "text-delta", id: "text-0", 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 configuredFake = fake.with({ endpoint: { baseURL: "https://fake.local" } })
+
+const gemini = Route.make({
+  id: "gemini-fake",
+  protocol: fakeProtocol,
+  endpoint: Endpoint.path("/chat"),
+  framing: fakeFraming,
+})
+const configuredGemini = gemini.with({ endpoint: { baseURL: "https://fake.local" } })
+
+const request = LLM.request({
+  id: "req_1",
+  model: Model.make({
+    id: "fake-model",
+    provider: "fake-provider",
+    route: configuredFake,
+  }),
+  prompt: "hello",
+})
+
+const echoLayer = dynamicResponse(({ text, respond }) =>
+  Effect.succeed(
+    respond(
+      encodeJson([
+        { type: "text", text: `echo:${text}` },
+        { type: "finish", reason: "stop" },
+      ]),
+    ),
+  ),
+)
+
+const it = testEffect(echoLayer)
+const unterminated = testEffect(
+  dynamicResponse(({ respond }) => Effect.succeed(respond(encodeJson([{ type: "text", text: "partial" }])))),
+)
+
+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)
+      const reduced = LLMResponse.fromEvents(events)
+
+      expect(events.map((event) => event.type)).toEqual(["text-delta", "finish"])
+      expect(reduced).toBeDefined()
+      if (!reduced) throw new Error("stream reducer did not produce a completed response")
+      expect(response.events).toEqual(events)
+      expect(response.message).toEqual(reduced.message)
+      expect(response.usage).toEqual(reduced.usage)
+      expect(response.finishReason).toEqual(reduced.finishReason)
+      expect(response.message.content).toEqual([{ type: "text", text: 'echo:{"body":"hello"}' }])
+    }),
+  )
+
+  unterminated.effect("fails when the normalized stream ends without a terminal event", () =>
+    Effect.gen(function* () {
+      const error = yield* (yield* LLMClient.Service).stream(request).pipe(Stream.runDrain, Effect.flip)
+
+      expect(error.reason).toMatchObject({ _tag: "InvalidProviderOutput" })
+      expect(error.message).toContain("Provider stream ended without a terminal finish event")
+    }),
+  )
+
+  it.effect("selects routes by model route value", () =>
+    Effect.gen(function* () {
+      const llm = yield* LLMClient.Service
+      const prepared = yield* llm.prepare(
+        LLM.updateRequest(request, { model: updateModel(request.model, { route: configuredGemini }) }),
+      )
+
+      expect(prepared.route).toBe("gemini-fake")
+    }),
+  )
+
+  it.effect("builds models from configured routes", () =>
+    Effect.gen(function* () {
+      const configured = fake.with({ provider: "fake-provider", endpoint: { baseURL: "https://fake.local" } })
+
+      expect(configured.model({ id: "fake-model" })).toMatchObject({
+        provider: "fake-provider",
+      })
+    }),
+  )
+
+  it.effect("does not register duplicate route ids globally", () =>
+    Effect.gen(function* () {
+      const duplicate = Route.make({
+        id: "fake",
+        protocol: Protocol.make({
+          ...fakeProtocol,
+          body: {
+            ...fakeProtocol.body,
+            from: () => Effect.succeed({ body: "late-default" }),
+          },
+        }),
+        endpoint: Endpoint.path("/chat", { baseURL: "https://fake.local" }),
+        framing: fakeFraming,
+      })
+
+      const prepared = yield* (yield* LLMClient.Service).prepare(
+        LLM.updateRequest(request, { model: updateModel(request.model, { route: duplicate }) }),
+      )
+
+      expect(prepared.body).toEqual({ body: "late-default" })
+    }),
+  )
+})

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

@@ -0,0 +1,217 @@
+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 OpenAIChat from "../src/protocols/openai-chat"
+import * as AmazonBedrock from "../src/providers/amazon-bedrock"
+import * as Anthropic from "../src/providers/anthropic"
+import * as AnthropicCompatible from "../src/providers/anthropic-compatible"
+import * as Azure from "../src/providers/azure"
+import * as Cloudflare from "../src/providers/cloudflare"
+import * as GitHubCopilot from "../src/providers/github-copilot"
+import * as Google from "../src/providers/google"
+import * as GoogleVertex from "../src/providers/google-vertex"
+import * as GoogleVertexAnthropic from "../src/providers/google-vertex-anthropic"
+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"
+
+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")
+
+OpenAIChat.route.model({ id: "gpt-4.1-mini" })
+
+// @ts-expect-error route model selection does not configure endpoints.
+OpenAIChat.route.model({ id: "gpt-4.1-mini", baseURL: "https://gateway.example.com/v1" })
+
+// @ts-expect-error route model selection does not configure query params.
+OpenAIChat.route.model({ id: "gpt-4.1-mini", queryParams: { debug: "1" } })
+
+// @ts-expect-error route model selection does not configure auth.
+OpenAIChat.route.model({ id: "gpt-4.1-mini", auth })
+
+// @ts-expect-error route model selection does not configure api keys.
+OpenAIChat.route.model({ id: "gpt-4.1-mini", apiKey: "sk-test" })
+
+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.configure({}).responses("gpt-4.1-mini")
+OpenAI.configure({ apiKey: "sk-test" }).responses("gpt-4.1-mini")
+OpenAI.configure({ apiKey: configApiKey }).responses("gpt-4.1-mini")
+OpenAI.configure({ auth: RuntimeAuth.bearer("oauth-token") }).responses("gpt-4.1-mini")
+OpenAI.configure({
+  auth: RuntimeAuth.headers({ authorization: "Bearer gateway" }),
+  baseURL: "https://gateway.example.com/v1",
+}).responses("gpt-4.1-mini")
+OpenAI.configure({
+  generation: { maxTokens: 100 },
+  providerOptions: { openai: { store: false } },
+}).responses("gpt-4.1-mini")
+
+// @ts-expect-error OpenAI model selectors only accept model ids.
+OpenAI.configure({ apiKey: "sk-test" }).responses("gpt-4.1-mini", {})
+
+// @ts-expect-error apiKey only accepts string, Redacted<string>, or Config<string | Redacted<string>>.
+OpenAI.configure({ apiKey: 123 })
+
+// @ts-expect-error provider helpers reject unknown top-level options.
+OpenAI.configure({ bogus: true })
+
+// @ts-expect-error common generation options remain typed.
+OpenAI.configure({ generation: { maxTokens: "many" } })
+
+// @ts-expect-error provider-native options remain typed.
+OpenAI.configure({ providerOptions: { openai: { store: "false" } } })
+
+// @ts-expect-error auth is an override, so OpenAI rejects apiKey with auth.
+OpenAI.configure({ apiKey: "sk-test", auth: RuntimeAuth.bearer("oauth-token") })
+
+OpenAI.chat("gpt-4.1-mini")
+OpenAI.configure({ apiKey: "sk-test" }).chat("gpt-4.1-mini")
+OpenAI.configure({ apiKey: configApiKey }).chat("gpt-4.1-mini")
+OpenAI.configure({ auth: RuntimeAuth.bearer("oauth-token") }).chat("gpt-4.1-mini")
+
+// @ts-expect-error OpenAI chat selectors only accept model ids.
+OpenAI.configure({ apiKey: "sk-test" }).chat("gpt-4.1-mini", {})
+
+// @ts-expect-error auth is an override, so OpenAI Chat rejects apiKey with auth.
+OpenAI.configure({ apiKey: "sk-test", auth: RuntimeAuth.bearer("oauth-token") })
+
+// @ts-expect-error Azure requires at least one of `resourceName` or `baseURL`.
+Azure.configure()
+Azure.configure({ apiKey: "azure-key", resourceName: "resource" }).responses("deployment")
+Azure.configure({ apiKey: configApiKey, resourceName: "resource" }).responses("deployment")
+Azure.configure({ auth: RuntimeAuth.header("api-key", "azure-key"), resourceName: "resource" }).responses("deployment")
+
+// @ts-expect-error Azure model selectors only accept deployment ids.
+Azure.configure({ apiKey: "azure-key", resourceName: "resource" }).responses("deployment", {})
+
+// @ts-expect-error auth is an override, so Azure rejects apiKey with auth.
+Azure.configure({ resourceName: "resource", apiKey: "azure-key", auth: RuntimeAuth.header("api-key", "override") })
+
+Azure.configure({ apiKey: "azure-key", resourceName: "resource" }).chat("deployment")
+Azure.configure({ apiKey: configApiKey, resourceName: "resource" }).chat("deployment")
+Azure.configure({ auth: RuntimeAuth.header("api-key", "azure-key"), resourceName: "resource" }).chat("deployment")
+
+// @ts-expect-error Azure chat model selectors only accept deployment ids.
+Azure.configure({ apiKey: "azure-key", resourceName: "resource" }).chat("deployment", {})
+
+// @ts-expect-error auth is an override, so Azure Chat rejects apiKey with auth.
+Azure.configure({ resourceName: "resource", apiKey: "azure-key", auth: RuntimeAuth.header("api-key", "override") })
+
+Anthropic.configure({ apiKey: "anthropic-key" }).model("claude-haiku")
+// @ts-expect-error Anthropic model selectors only accept model ids.
+Anthropic.configure({ apiKey: "anthropic-key" }).model("claude-haiku", {})
+// @ts-expect-error Anthropic package settings accept only one auth source.
+Anthropic.model("claude-sonnet-4-6", { apiKey: "anthropic-key", authToken: "anthropic-token" })
+
+AnthropicCompatible.configure({
+  apiKey: "messages-key",
+  baseURL: "https://messages.example.com/v1",
+  provider: "example",
+}).model("compatible-model")
+// @ts-expect-error Anthropic-compatible providers require a base URL.
+AnthropicCompatible.configure({ apiKey: "messages-key" })
+// @ts-expect-error Anthropic-compatible model selectors only accept model ids.
+AnthropicCompatible.configure({ baseURL: "https://messages.example.com/v1" }).model("compatible-model", {})
+// @ts-expect-error Anthropic-compatible package settings accept only one auth source.
+AnthropicCompatible.model("compatible-model", {
+  apiKey: "messages-key",
+  authToken: "messages-token",
+  baseURL: "https://messages.example.com/v1",
+})
+
+Google.configure({ apiKey: "google-key" }).model("gemini-2.5-flash")
+// @ts-expect-error Google model selectors only accept model ids.
+Google.configure({ apiKey: "google-key" }).model("gemini-2.5-flash", {})
+
+GoogleVertex.configure({ apiKey: "vertex-key" }).model("gemini-3.5-flash")
+GoogleVertex.configure({ accessToken: "vertex-token", project: "project" }).model("gemini-3.5-flash")
+GoogleVertex.configure({ auth: RuntimeAuth.bearer("vertex-token"), project: "project" }).model("gemini-3.5-flash")
+// @ts-expect-error Vertex Gemini model selectors only accept model ids.
+GoogleVertex.configure({ apiKey: "vertex-key" }).model("gemini-3.5-flash", {})
+// @ts-expect-error Vertex Gemini config accepts only one auth source.
+GoogleVertex.configure({ accessToken: "vertex-token", apiKey: "vertex-key", project: "project" })
+// @ts-expect-error Vertex Gemini package settings accept only one auth source.
+GoogleVertex.model("gemini-3.5-flash", { accessToken: "vertex-token", apiKey: "vertex-key", project: "project" })
+
+GoogleVertexAnthropic.configure({ accessToken: "vertex-token", project: "project" }).model("claude-sonnet-4-6")
+// @ts-expect-error Vertex Anthropic package settings do not accept API keys.
+GoogleVertexAnthropic.model("claude-sonnet-4-6", { apiKey: "vertex-key", project: "project" })
+GoogleVertexAnthropic.configure({ auth: RuntimeAuth.bearer("vertex-token"), project: "project" }).model(
+  "claude-sonnet-4-6",
+)
+GoogleVertexAnthropic.configure({ accessToken: "vertex-token", project: "project" }).model(
+  "claude-sonnet-4-6",
+  // @ts-expect-error Vertex Anthropic model selectors only accept model ids.
+  {},
+)
+GoogleVertexAnthropic.configure({
+  accessToken: "vertex-token",
+  // @ts-expect-error Vertex Anthropic config accepts only one auth source.
+  auth: RuntimeAuth.bearer("vertex-token"),
+  project: "project",
+})
+
+AmazonBedrock.configure({ apiKey: "bedrock-key" }).model("anthropic.claude")
+// @ts-expect-error Bedrock model selectors only accept model ids.
+AmazonBedrock.configure({ apiKey: "bedrock-key" }).model("anthropic.claude", {})
+
+OpenRouter.configure({ apiKey: "openrouter-key" }).model("openai/gpt-4o-mini")
+// @ts-expect-error OpenRouter model selectors only accept model ids.
+OpenRouter.configure({ apiKey: "openrouter-key" }).model("openai/gpt-4o-mini", {})
+
+XAI.configure({ apiKey: "xai-key" }).responses("grok-4")
+XAI.configure({ apiKey: "xai-key" }).chat("grok-4")
+// @ts-expect-error xAI Responses selectors only accept model ids.
+XAI.configure({ apiKey: "xai-key" }).responses("grok-4", {})
+// @ts-expect-error xAI Chat selectors only accept model ids.
+XAI.configure({ apiKey: "xai-key" }).chat("grok-4", {})
+
+OpenAICompatible.deepseek.configure({ apiKey: "deepseek-key" }).model("deepseek-chat")
+// @ts-expect-error OpenAI-compatible family selectors only accept model ids.
+OpenAICompatible.deepseek.configure({ apiKey: "deepseek-key" }).model("deepseek-chat", {})
+
+Cloudflare.CloudflareWorkersAI.configure({ accountId: "account", apiKey: "cf-key" }).model("@cf/meta/llama")
+// @ts-expect-error Cloudflare Workers AI model selectors only accept model ids.
+Cloudflare.CloudflareWorkersAI.configure({ accountId: "account", apiKey: "cf-key" }).model("@cf/meta/llama", {})
+
+GitHubCopilot.configure({ baseURL: "https://copilot.test", apiKey: "copilot-key" }).model("gpt-4.1")
+// @ts-expect-error GitHub Copilot model selectors only accept model ids.
+GitHubCopilot.configure({ baseURL: "https://copilot.test", apiKey: "copilot-key" }).model("gpt-4.1", {})

packages/ai/test/auth.test.ts

@@ -0,0 +1,103 @@
+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 * as OpenAIChat from "../src/protocols/openai-chat"
+import { Model } from "../src/schema"
+import { it } from "./lib/effect"
+
+const request = LLM.request({
+  id: "req_auth",
+  model: Model.make({ id: "fake-model", provider: "fake", route: OpenAIChat.route }),
+  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/ai/test/cache-policy.test.ts

@@ -0,0 +1,262 @@
+import { describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { CacheHint, LLM, Message } from "../src"
+import { Auth, LLMClient } from "../src/route"
+import { AmazonBedrock } from "../src/providers"
+import * as AnthropicMessages from "../src/protocols/anthropic-messages"
+import * as Gemini from "../src/protocols/gemini"
+import * as OpenAIChat from "../src/protocols/openai-chat"
+import { applyCachePolicy } from "../src/cache-policy"
+import { it } from "./lib/effect"
+
+const anthropicModel = AnthropicMessages.route
+  .with({ endpoint: { baseURL: "https://api.anthropic.test/v1/" }, auth: Auth.header("x-api-key", "test") })
+  .model({ id: "claude-sonnet-4-5" })
+
+const bedrockModel = AmazonBedrock.configure({
+  credentials: { region: "us-east-1", accessKeyId: "fixture", secretAccessKey: "fixture" },
+}).model("anthropic.claude-3-5-sonnet-20241022-v2:0")
+
+const openaiModel = OpenAIChat.route
+  .with({ endpoint: { baseURL: "https://api.openai.test/v1/" }, auth: Auth.bearer("test") })
+  .model({ id: "gpt-4o-mini" })
+
+const geminiModel = Gemini.route
+  .with({
+    endpoint: { baseURL: "https://generativelanguage.test/v1beta/" },
+    auth: Auth.header("x-goog-api-key", "test"),
+  })
+  .model({ id: "gemini-2.5-flash" })
+
+describe("applyCachePolicy", () => {
+  it.effect("undefined cache resolves to 'auto' (the recommended default)", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model: anthropicModel,
+          system: "You are concise.",
+          prompt: "hi",
+        }),
+      )
+
+      // No explicit cache field → auto policy fires → last system part + latest
+      // user message both get cache_control markers.
+      expect(prepared.body).toMatchObject({
+        system: [{ type: "text", text: "You are concise.", cache_control: { type: "ephemeral" } }],
+        messages: [{ role: "user", content: [{ type: "text", text: "hi", cache_control: { type: "ephemeral" } }] }],
+      })
+    }),
+  )
+
+  it.effect("'auto' marks the last tool, last system part, and latest user message on Anthropic", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model: anthropicModel,
+          system: "Sys A",
+          tools: [{ name: "t1", description: "t1", inputSchema: { type: "object", properties: {} } }],
+          messages: [
+            Message.user("first user"),
+            Message.assistant("assistant reply"),
+            Message.user("latest user message"),
+          ],
+          cache: "auto",
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        tools: [{ name: "t1", cache_control: { type: "ephemeral" } }],
+        system: [{ type: "text", text: "Sys A", cache_control: { type: "ephemeral" } }],
+        messages: [
+          { role: "user", content: [{ type: "text", text: "first user" }] },
+          { role: "assistant", content: [{ type: "text", text: "assistant reply" }] },
+          {
+            role: "user",
+            content: [{ type: "text", text: "latest user message", cache_control: { type: "ephemeral" } }],
+          },
+        ],
+      })
+    }),
+  )
+
+  it.effect("'auto' is a no-op on OpenAI (implicit caching protocol)", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model: openaiModel,
+          system: "Sys",
+          prompt: "hi",
+          cache: "auto",
+        }),
+      )
+
+      const body = prepared.body as { messages: Array<{ content: unknown }> }
+      // OpenAI doesn't accept cache_control on messages — policy must skip.
+      const flat = JSON.stringify(body)
+      expect(flat).not.toContain("cache_control")
+      expect(flat).not.toContain("cachePoint")
+    }),
+  )
+
+  it.effect("'auto' is a no-op on Gemini (out-of-band caching protocol)", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model: geminiModel,
+          system: "Sys",
+          prompt: "hi",
+          cache: "auto",
+        }),
+      )
+
+      const flat = JSON.stringify(prepared.body)
+      expect(flat).not.toContain("cache_control")
+      expect(flat).not.toContain("cachePoint")
+    }),
+  )
+
+  it.effect("'auto' on Bedrock emits cachePoint markers in the right places", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model: bedrockModel,
+          system: "Sys",
+          tools: [{ name: "t1", description: "t1", inputSchema: { type: "object", properties: {} } }],
+          messages: [Message.user("first user"), Message.assistant("reply"), Message.user("latest user")],
+          cache: "auto",
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        toolConfig: {
+          tools: [{ toolSpec: { name: "t1" } }, { cachePoint: { type: "default" } }],
+        },
+        system: [{ text: "Sys" }, { cachePoint: { type: "default" } }],
+        messages: [
+          { role: "user", content: [{ text: "first user" }] },
+          { role: "assistant", content: [{ text: "reply" }] },
+          { role: "user", content: [{ text: "latest user" }, { cachePoint: { type: "default" } }] },
+        ],
+      })
+    }),
+  )
+
+  it.effect("'none' disables auto placement even when manual hints exist", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model: anthropicModel,
+          system: "Sys",
+          tools: [{ name: "t1", description: "t1", inputSchema: { type: "object", properties: {} } }],
+          prompt: "hi",
+          cache: "none",
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        tools: [{ name: "t1", cache_control: undefined }],
+        system: [{ type: "text", text: "Sys", cache_control: undefined }],
+      })
+    }),
+  )
+
+  it.effect("granular object form: tools-only marks just tools", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model: anthropicModel,
+          system: "Sys",
+          tools: [{ name: "t1", description: "t1", inputSchema: { type: "object", properties: {} } }],
+          prompt: "hi",
+          cache: { tools: true },
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        tools: [{ name: "t1", cache_control: { type: "ephemeral" } }],
+        system: [{ type: "text", text: "Sys", cache_control: undefined }],
+      })
+    }),
+  )
+
+  it.effect("auto policy preserves manual CacheHints on other parts", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model: anthropicModel,
+          system: [
+            { type: "text", text: "first system", cache: new CacheHint({ type: "ephemeral", ttlSeconds: 3600 }) },
+            { type: "text", text: "last system" },
+          ],
+          prompt: "hi",
+          cache: "auto",
+        }),
+      )
+
+      const body = prepared.body as { system: Array<{ text: string; cache_control?: unknown }> }
+      expect(body.system[0]?.cache_control).toEqual({ type: "ephemeral", ttl: "1h" })
+      expect(body.system[1]?.cache_control).toEqual({ type: "ephemeral" })
+    }),
+  )
+
+  it.effect("ttlSeconds in the policy flows through to wire markers", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model: anthropicModel,
+          system: "Sys",
+          prompt: "hi",
+          cache: { system: true, ttlSeconds: 3600 },
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        system: [{ type: "text", text: "Sys", cache_control: { type: "ephemeral", ttl: "1h" } }],
+      })
+    }),
+  )
+
+  it.effect("messages: { tail: 2 } marks the last 2 message boundaries", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model: anthropicModel,
+          messages: [Message.user("u1"), Message.assistant("a1"), Message.user("u2"), Message.assistant("a2")],
+          cache: { messages: { tail: 2 } },
+        }),
+      )
+
+      const body = prepared.body as { messages: Array<{ content: Array<{ cache_control?: unknown }> }> }
+      expect(body.messages[0]?.content[0]?.cache_control).toBeUndefined()
+      expect(body.messages[1]?.content[0]?.cache_control).toBeUndefined()
+      expect(body.messages[2]?.content[0]?.cache_control).toEqual({ type: "ephemeral" })
+      expect(body.messages[3]?.content[0]?.cache_control).toEqual({ type: "ephemeral" })
+    }),
+  )
+
+  it.effect("'latest-assistant' marks the last assistant message", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model: anthropicModel,
+          messages: [Message.user("u1"), Message.assistant("a1"), Message.user("u2")],
+          cache: { messages: "latest-assistant" },
+        }),
+      )
+
+      const body = prepared.body as { messages: Array<{ content: Array<{ cache_control?: unknown }> }> }
+      expect(body.messages[0]?.content[0]?.cache_control).toBeUndefined()
+      expect(body.messages[1]?.content[0]?.cache_control).toEqual({ type: "ephemeral" })
+      expect(body.messages[2]?.content[0]?.cache_control).toBeUndefined()
+    }),
+  )
+
+  test("returns the same request reference when policy is a no-op (pure function)", () => {
+    const request = LLM.request({
+      model: anthropicModel,
+      prompt: "hi",
+      cache: "none",
+    })
+    expect(applyCachePolicy(request)).toBe(request)
+  })
+})

packages/ai/test/continuation-scenarios.ts

@@ -0,0 +1,104 @@
+import { LLM, Message, ToolCallPart, ToolDefinition, ToolResultPart, type ContentPart, type Model } from "../src"
+
+export const basicContinuation = ["system", "user-text", "assistant-text", "user-follow-up"] as const
+export const toolContinuation = ["tool-call", "tool-result"] as const
+export const reasoningContinuation = ["assistant-reasoning", "encrypted-reasoning"] as const
+export const mediaContinuation = ["user-image"] as const
+export const maximalContinuation = [
+  ...basicContinuation,
+  ...toolContinuation,
+  ...reasoningContinuation,
+  ...mediaContinuation,
+] as const
+
+export type ContinuationFeature = (typeof maximalContinuation)[number]
+
+export const nativeOpenAIResponsesContinuation = [
+  ...basicContinuation,
+  ...toolContinuation,
+  "encrypted-reasoning",
+  ...mediaContinuation,
+] as const satisfies ReadonlyArray<ContinuationFeature>
+
+export const nativeAnthropicMessagesContinuation = [
+  ...basicContinuation,
+  ...toolContinuation,
+  "assistant-reasoning",
+  ...mediaContinuation,
+] as const satisfies ReadonlyArray<ContinuationFeature>
+
+export const continuationTool = ToolDefinition.make({
+  name: "get_weather",
+  description: "Get current weather for a city.",
+  inputSchema: {
+    type: "object",
+    properties: { city: { type: "string" } },
+    required: ["city"],
+    additionalProperties: false,
+  },
+})
+
+export function continuationRequest(input: {
+  readonly id: string
+  readonly model: Model
+  readonly features: ReadonlyArray<ContinuationFeature>
+  readonly image?: string
+}) {
+  const features = new Set(input.features)
+  const messages = []
+  const firstUser: ContentPart[] = []
+  const firstAssistant: ContentPart[] = []
+
+  if (features.has("user-text")) firstUser.push({ type: "text", text: "What is shown here?" })
+  if (features.has("user-image"))
+    firstUser.push({ type: "media", mediaType: "image/png", data: input.image ?? "AAECAw==" })
+  if (firstUser.length > 0) messages.push(Message.user(firstUser))
+
+  if (features.has("assistant-reasoning"))
+    firstAssistant.push({
+      type: "reasoning",
+      text: "I inspected the previous turn.",
+      providerMetadata: { anthropic: { signature: "sig_continuation_1" } },
+    })
+  if (features.has("encrypted-reasoning"))
+    firstAssistant.push({
+      type: "reasoning",
+      text: "I inspected the previous turn.",
+      providerMetadata: {
+        openai: {
+          itemId: "rs_continuation_1",
+          reasoningEncryptedContent: "encrypted-continuation-state",
+        },
+      },
+    })
+  if (features.has("assistant-text")) firstAssistant.push({ type: "text", text: "It shows a small test image." })
+  if (firstAssistant.length > 0) messages.push(Message.assistant(firstAssistant))
+
+  if (features.has("tool-call")) {
+    messages.push(Message.user("Check the weather in Paris before continuing."))
+    messages.push(
+      Message.assistant([ToolCallPart.make({ id: "call_weather_1", name: "get_weather", input: { city: "Paris" } })]),
+    )
+  }
+  if (features.has("tool-result")) {
+    messages.push(
+      Message.tool(ToolResultPart.make({ id: "call_weather_1", name: "get_weather", result: { temperature: 22 } })),
+    )
+    if (features.has("assistant-text")) messages.push(Message.assistant("Paris is 22 degrees."))
+  }
+  if (features.has("user-follow-up"))
+    messages.push(Message.user("Continue from this conversation in one short sentence."))
+
+  return LLM.request({
+    id: input.id,
+    model: input.model,
+    system: features.has("system") ? "You are concise. Continue from the provided history." : undefined,
+    messages,
+    tools: features.has("tool-call") ? [continuationTool] : [],
+    cache: "none",
+    providerOptions: features.has("encrypted-reasoning")
+      ? { openai: { store: false, include: ["reasoning.encrypted_content"], reasoningSummary: "auto" } }
+      : undefined,
+    generation: { maxTokens: 80, temperature: 0 },
+  })
+}

packages/ai/test/endpoint.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test"
+import { LLM } from "../src"
+import * as OpenAIChat from "../src/protocols/openai-chat"
+import { Endpoint } from "../src/route"
+import { Model } from "../src/schema"
+
+const request = () =>
+  LLM.request({
+    model: Model.make({
+      id: "model-1",
+      provider: "test",
+      route: OpenAIChat.route,
+    }),
+    prompt: "hello",
+  })
+
+describe("Endpoint", () => {
+  test("appends a static path to the model's baseURL", () => {
+    const url = Endpoint.render(Endpoint.path("/chat", { baseURL: "https://api.example.test/v1/" }), {
+      request: request(),
+      body: {},
+    })
+
+    expect(url.toString()).toBe("https://api.example.test/v1/chat")
+  })
+
+  test("endpoint query params are appended to the rendered URL", () => {
+    const url = Endpoint.render(
+      Endpoint.path("/chat?alt=sse", {
+        baseURL: "https://custom.example.test/root/",
+        query: { "api-version": "2026-01-01", alt: "json" },
+      }),
+      {
+        request: request(),
+        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`,
+        { baseURL: "https://bedrock-runtime.us-east-1.amazonaws.com" },
+      ),
+      {
+        request: request(),
+        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/ai/test/executor.test.ts

@@ -0,0 +1,400 @@
+import { describe, expect } from "bun:test"
+import { Effect, Layer, Ref } from "effect"
+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 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("classifies context overflow responses", () =>
+    Effect.gen(function* () {
+      const executor = yield* RequestExecutor.Service
+      const error = yield* executor.execute(request).pipe(Effect.flip)
+
+      expectLLMError(error)
+      expect(error.reason).toMatchObject({ _tag: "InvalidRequest", classification: "context-overflow" })
+    }).pipe(
+      Effect.provide(
+        responsesLayer([
+          new Response('{"error":{"code":"context_length_exceeded","message":"prompt too long"}}', {
+            status: 400,
+          }),
+        ]),
+      ),
+    ),
+  )
+
+  it.effect("does not classify generic HTTP 413 payload errors as context overflow", () =>
+    Effect.gen(function* () {
+      const executor = yield* RequestExecutor.Service
+      const error = yield* executor.execute(request).pipe(Effect.flip)
+
+      expectLLMError(error)
+      expect(error.reason).toMatchObject({ _tag: "InvalidRequest" })
+      expect("classification" in error.reason ? error.reason.classification : undefined).toBeUndefined()
+    }).pipe(Effect.provide(responsesLayer([new Response("request too large", { status: 413 })]))),
+  )
+
+  it.effect("does not classify ordinary invalid requests as context overflow", () =>
+    Effect.gen(function* () {
+      const executor = yield* RequestExecutor.Service
+      const error = yield* executor.execute(request).pipe(Effect.flip)
+
+      expectLLMError(error)
+      expect(error.reason).toMatchObject({ _tag: "InvalidRequest" })
+      expect("classification" in error.reason ? error.reason.classification : undefined).toBeUndefined()
+    }).pipe(Effect.provide(responsesLayer([new Response("invalid parameter", { status: 400 })]))),
+  )
+
+  it.effect("classifies provider rate limits hidden behind HTTP 400", () =>
+    Effect.gen(function* () {
+      const classify = (body: string) =>
+        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" })
+        }).pipe(Effect.provide(responsesLayer([new Response(body, { status: 400 })])))
+
+      yield* classify("Request rate increased too quickly")
+      yield* classify('{"type":"error","error":{"type":"too_many_requests"}}')
+      yield* classify('{"type":"error","error":{"code":"rate_limit_exceeded"}}')
+    }),
+  )
+
+  it.effect("classifies provider overloads hidden behind HTTP 400", () =>
+    Effect.gen(function* () {
+      const classify = (body: string) =>
+        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" })
+        }).pipe(Effect.provide(responsesLayer([new Response(body, { status: 400 })])))
+
+      yield* classify('{"code":"resource_exhausted"}')
+      yield* classify('{"code":"service_unavailable"}')
+    }),
+  )
+
+  it.effect("returns redacted diagnostics for rate limits", () =>
+    Effect.gen(function* () {
+      const executor = yield* RequestExecutor.Service
+      const error = yield* executor.execute(request).pipe(Effect.flip)
+
+      expectLLMError(error)
+      expect(error).toMatchObject({
+        reason: {
+          _tag: "RateLimit",
+          retryAfterMs: 0,
+          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([
+          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([
+          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([
+          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("returns provider status failures without retrying", () =>
+    Effect.gen(function* () {
+      const attempts = yield* Ref.make(0)
+      const error = yield* Effect.gen(function* () {
+        const executor = yield* RequestExecutor.Service
+        return yield* executor.execute(request).pipe(Effect.flip)
+      }).pipe(
+        Effect.provide(
+          countedResponsesLayer(attempts, [
+            new Response("busy", { status: 503, headers: { "retry-after-ms": "0" } }),
+            new Response("ok", { status: 200 }),
+          ]),
+        ),
+      )
+
+      expectLLMError(error)
+      expect(error.reason).toMatchObject({ _tag: "ProviderInternal", status: 503 })
+      expect(yield* Ref.get(attempts)).toBe(1)
+    }),
+  )
+
+  it.effect("marks 504 and 529 status responses as provider-internal", () =>
+    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 })
+        }).pipe(
+          Effect.provide(
+            responsesLayer([
+              new Response("provider failure", {
+                status,
+                headers: { "retry-after-ms": "0" },
+              }),
+            ]),
+          ),
+        )
+
+      yield* failWith(504)
+      yield* failWith(529)
+    }),
+  )
+
+  it.effect("truncates large authentication error 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(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("does not re-execute after a successful response reaches stream parsing", () =>
+    Effect.gen(function* () {
+      const attempts = yield* Ref.make(0)
+      const model = OpenAIChat.route
+        .with({ endpoint: { baseURL: "https://api.openai.test/v1" } })
+        .model({ id: "gpt-4o-mini" })
+      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/ai/test/exports.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from "bun:test"
+import { LLM, LLMClient, Provider } from "@opencode-ai/ai"
+import { Route, Protocol } from "@opencode-ai/ai/route"
+import { Provider as ProviderSubpath } from "@opencode-ai/ai/provider"
+import {
+  CloudflareAIGateway,
+  CloudflareWorkersAI,
+  OpenAI,
+  OpenAICompatible,
+  OpenRouter,
+  XAI,
+} from "@opencode-ai/ai/providers"
+import * as GitHubCopilot from "@opencode-ai/ai/providers/github-copilot"
+import {
+  OpenAIChat,
+  OpenAICompatibleChat,
+  OpenAICompatibleResponses,
+  OpenAIResponses,
+} from "@opencode-ai/ai/protocols"
+import * as AnthropicMessages from "@opencode-ai/ai/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", async () => {
+    const { OpenAICompatibleResponses } = await import("@opencode-ai/ai/providers")
+
+    expect(OpenAI.model).toBeFunction()
+    expect(OpenAI.provider.responses).toBe(OpenAI.responses)
+    expect(OpenAI.provider.responsesWebSocket).toBe(OpenAI.responsesWebSocket)
+    expect(OpenAI.configure({ apiKey: "fixture" }).responses).toBeFunction()
+    expect(OpenAICompatible.deepseek.model).toBeFunction()
+    expect(
+      OpenAICompatibleResponses.configure({ baseURL: "https://responses.test/v1" }).model("fixture").route.id,
+    ).toBe("openai-compatible-responses")
+    expect(CloudflareAIGateway.configure).toBeFunction()
+    expect(CloudflareAIGateway.configure({ accountId: "fixture", gatewayApiKey: "fixture" }).model).toBeFunction()
+    expect(CloudflareWorkersAI.configure).toBeFunction()
+    expect(CloudflareWorkersAI.configure({ accountId: "fixture", apiKey: "fixture" }).model).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.provider.responses).toBe(XAI.responses)
+    expect(XAI.provider.chat).toBe(XAI.chat)
+    expect(XAI.configure({ apiKey: "fixture" }).responses("grok-4.3").route.id).toBe("openai-responses")
+    expect(XAI.configure({ apiKey: "fixture" }).chat("grok-4.3").route.id).toBe("openai-compatible-chat")
+    expect(
+      GitHubCopilot.configure({ baseURL: "https://api.githubcopilot.test", apiKey: "fixture" }).model,
+    ).toBeFunction()
+    expect(
+      GitHubCopilot.configure({
+        baseURL: "https://api.githubcopilot.test",
+        apiKey: "fixture",
+        endpoint: "responses",
+      }).model("mai-code-1-flash-picker").route.id,
+    ).toBe("openai-responses")
+    expect(
+      GitHubCopilot.configure({
+        baseURL: "https://api.githubcopilot.test",
+        apiKey: "fixture",
+        endpoint: "chat",
+      }).model("gpt-5").route.id,
+    ).toBe("openai-chat")
+  })
+
+  test("protocol barrels expose supported low-level routes", () => {
+    expect(OpenAIChat.route.id).toBe("openai-chat")
+    expect(OpenAICompatibleChat.route.id).toBe("openai-compatible-chat")
+    expect(OpenAICompatibleResponses.route.id).toBe("openai-compatible-responses")
+    expect(OpenAIResponses.route.id).toBe("openai-responses")
+    expect(OpenAIResponses.webSocketRoute.id).toBe("openai-responses-websocket")
+    expect(AnthropicMessages.route.id).toBe("anthropic-messages")
+  })
+})

packages/ai/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/ai/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/ai/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/ai/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/ai/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/ai/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/ai/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/ai/test/fixtures/recordings/cloudflare-ai-gateway/cloudflare-ai-gateway-workers-ai-llama-3-1-8b-text.json

@@ -0,0 +1,32 @@
+{
+  "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/ai/test/fixtures/recordings/cloudflare-workers-ai/cloudflare-workers-ai-llama-3-1-8b-text.json

@@ -0,0 +1,32 @@
+{
+  "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/ai/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/ai/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/ai/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/ai/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/ai/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/ai/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/ai/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/ai/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/ai/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/ai/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/ai/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/ai/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/ai/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/ai/test/generate-object.test.ts

@@ -0,0 +1,184 @@
+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 { Auth } from "../src/route"
+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.route
+  .with({ endpoint: { baseURL: "https://api.openai.test/v1/" }, auth: Auth.bearer("test") })
+  .model({ id: "gpt-4o-mini" })
+
+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/ai/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/ai/test/lib/http.ts

@@ -0,0 +1,98 @@
+import { Effect, Layer, Ref } from "effect"
+import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
+import { LLMClient, RequestExecutor, WebSocketExecutor } 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"
+
+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 | WebSocketExecutorService | LLMClientService
+
+export const runtimeLayer = (layer: Layer.Layer<HttpClient.HttpClient>): Layer.Layer<RuntimeEnv> => {
+  const requestExecutorLayer = RequestExecutor.layer.pipe(Layer.provide(layer))
+  const deps = Layer.mergeAll(requestExecutorLayer, WebSocketExecutor.layer)
+  const llmClientLayer = LLMClient.layer.pipe(Layer.provide(deps))
+  return Layer.mergeAll(deps, 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/ai/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/ai/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/ai/test/lib/tool-runtime.ts

@@ -0,0 +1,146 @@
+import { Effect, Stream } from "effect"
+import { LLMClient } from "../../src/route"
+import {
+  LLMEvent,
+  LLMRequest,
+  Message,
+  type ContentPart,
+  type ProviderMetadata,
+  type ToolCallPart,
+  ToolResultPart,
+  type ToolResultValue,
+  type Usage,
+} from "../../src/schema"
+import { type Tools, toDefinitions } from "../../src/tool"
+import { ToolRuntime } from "../../src/tool-runtime"
+
+interface RunOptions<T extends Tools> {
+  readonly request: LLMRequest
+  readonly tools: T
+  readonly maxSteps?: number
+}
+
+/** Test-owned continuation loop. Production callers must own durable history. */
+export const runTools = <T extends Tools>(options: RunOptions<T>) =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const names = new Set(Object.keys(options.tools))
+      let request = LLMRequest.update(options.request, {
+        tools: [...options.request.tools.filter((tool) => !names.has(tool.name)), ...toDefinitions(options.tools)],
+      })
+      let usage: Usage | undefined
+      const events: LLMEvent[] = []
+
+      for (let step = 0; step < (options.maxSteps ?? 10); step++) {
+        const streamed = Array.from(yield* LLMClient.stream(request).pipe(Stream.runCollect))
+        const state = stepState(streamed)
+        usage = addUsage(usage, state.usage)
+        events.push(...streamed.filter((event) => event.type !== "finish").map((event) => indexStep(event, step)))
+
+        if (state.toolCalls.length === 0) {
+          events.push(LLMEvent.finish({ reason: state.reason, usage, providerMetadata: state.providerMetadata }))
+          return Stream.fromIterable(events)
+        }
+
+        const dispatched = yield* Effect.forEach(
+          state.toolCalls,
+          (call) => ToolRuntime.dispatch(options.tools, call).pipe(Effect.map((result) => [call, result] as const)),
+          { concurrency: 10 },
+        )
+        events.push(...dispatched.flatMap(([, result]) => result.events))
+
+        if (step + 1 >= (options.maxSteps ?? 10)) {
+          events.push(LLMEvent.finish({ reason: state.reason, usage, providerMetadata: state.providerMetadata }))
+          return Stream.fromIterable(events)
+        }
+
+        request = LLMRequest.update(request, {
+          messages: [
+            ...request.messages,
+            Message.assistant(state.assistantContent),
+            ...dispatched.map(([call, dispatched]) =>
+              Message.tool({ id: call.id, name: call.name, result: dispatched.result }),
+            ),
+          ],
+        })
+      }
+
+      return Stream.fromIterable(events)
+    }),
+  )
+
+const indexStep = (event: LLMEvent, index: number): LLMEvent => {
+  if (event.type === "step-start") return LLMEvent.stepStart({ index })
+  if (event.type === "step-finish") return LLMEvent.stepFinish({ ...event, index })
+  return event
+}
+
+const stepState = (events: ReadonlyArray<LLMEvent>) => {
+  const assistantContent: ContentPart[] = []
+  const toolCalls: ToolCallPart[] = []
+  let reason: Extract<LLMEvent, { type: "finish" }>["reason"] = "unknown"
+  let usage: Usage | undefined
+  let providerMetadata: ProviderMetadata | undefined
+
+  for (const event of events) {
+    if (event.type === "text-delta" || event.type === "reasoning-delta") {
+      appendText(assistantContent, event.type === "text-delta" ? "text" : "reasoning", event.text)
+    } else if (event.type === "text-end" || event.type === "reasoning-end") {
+      appendText(assistantContent, event.type === "text-end" ? "text" : "reasoning", "", event.providerMetadata)
+    } else if (event.type === "tool-call") {
+      assistantContent.push(event)
+      if (!event.providerExecuted) toolCalls.push(event)
+    } else if (event.type === "tool-result" && event.providerExecuted && event.result !== undefined) {
+      assistantContent.push(
+        ToolResultPart.make({
+          id: event.id,
+          name: event.name,
+          result: event.result,
+          providerExecuted: true,
+          providerMetadata: event.providerMetadata,
+        }),
+      )
+    } else if (event.type === "finish") {
+      reason = event.reason
+      usage = event.usage
+      providerMetadata = event.providerMetadata
+    }
+  }
+  return { assistantContent, toolCalls, reason, usage, providerMetadata }
+}
+
+const appendText = (
+  content: ContentPart[],
+  type: "text" | "reasoning",
+  text: string,
+  providerMetadata?: ProviderMetadata,
+) => {
+  const last = content.at(-1)
+  if (last?.type === type) {
+    content[content.length - 1] = {
+      ...last,
+      text: `${last.text}${text}`,
+      providerMetadata: providerMetadata ?? last.providerMetadata,
+    }
+    return
+  }
+  content.push({ type, text, providerMetadata })
+}
+
+const addUsage = (left: Usage | undefined, right: Usage | undefined): Usage | undefined => {
+  if (!left) return right
+  if (!right) return left
+  const sum = (key: keyof Usage) =>
+    typeof left[key] !== "number" && typeof right[key] !== "number"
+      ? undefined
+      : ((left[key] as number | undefined) ?? 0) + ((right[key] as number | undefined) ?? 0)
+  return {
+    inputTokens: sum("inputTokens"),
+    outputTokens: sum("outputTokens"),
+    nonCachedInputTokens: sum("nonCachedInputTokens"),
+    cacheReadInputTokens: sum("cacheReadInputTokens"),
+    cacheWriteInputTokens: sum("cacheWriteInputTokens"),
+    reasoningTokens: sum("reasoningTokens"),
+    totalTokens: sum("totalTokens"),
+  } as Usage
+}

packages/ai/test/llm.test.ts

@@ -0,0 +1,199 @@
+import { describe, expect, test } from "bun:test"
+import { CacheHint, LLM, LLMResponse } from "../src"
+import * as OpenAIChat from "../src/protocols/openai-chat"
+import * as OpenAIResponses from "../src/protocols/openai-responses"
+import { LLMRequest, Message, Model, ToolCallPart, ToolChoice, ToolDefinition, ToolResultPart } from "../src/schema"
+
+const chatRoute = OpenAIChat.route
+const responsesRoute = OpenAIResponses.route
+
+describe("llm constructors", () => {
+  test("builds canonical schema classes from ergonomic input", () => {
+    const request = LLM.request({
+      id: "req_1",
+      model: Model.make({ id: "fake-model", provider: "fake", route: chatRoute }),
+      system: "You are concise.",
+      prompt: "Say hello.",
+    })
+
+    expect(request).toBeInstanceOf(LLMRequest)
+    expect(request.model).toBeInstanceOf(Model)
+    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: Model.make({ id: "fake-model", provider: "fake", route: chatRoute }),
+      prompt: "Say hello.",
+    })
+    const updated = LLM.updateRequest(base, {
+      generation: { maxTokens: 20 },
+      messages: [...base.messages, Message.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 route defaults", () => {
+    const request = LLM.request({
+      model: Model.make({
+        id: "fake-model",
+        provider: "fake",
+        route: chatRoute.with({
+          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: Model.make({ id: "fake-model", provider: "fake", route: chatRoute }),
+      prompt: "Say hello.",
+    })
+    const updated = LLMRequest.update(base, { messages: [...base.messages, Message.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 = Model.make({
+      id: "fake-model",
+      provider: "fake",
+      route: chatRoute,
+    })
+    const updated = Model.update(base, {
+      route: responsesRoute,
+      defaults: { generation: { maxTokens: 20 } },
+      compatibility: { toolSchema: "gemini" },
+    })
+    const updatedInput = Model.input(updated)
+
+    expect(updated).toBeInstanceOf(Model)
+    expect(String(updated.id)).toBe("fake-model")
+    expect(updated.route).toBe(responsesRoute)
+    expect(updated.defaults?.generation).toEqual({ maxTokens: 20 })
+    expect(updated.compatibility).toEqual({ toolSchema: "gemini" })
+    expect(updatedInput.defaults).toBe(updated.defaults)
+    expect(updatedInput.compatibility).toBe(updated.compatibility)
+    expect(String(updatedInput.provider)).toBe("fake")
+    expect(Model.update(updated, {})).toBe(updated)
+  })
+
+  test("carries model defaults and compatibility through route model selection", () => {
+    const model = chatRoute.model({
+      id: "kimi-k2",
+      defaults: {
+        limits: { context: 128_000, output: 8_192 },
+        generation: { maxTokens: 1_024, stop: ["END"] },
+        providerOptions: { openai: { parallelToolCalls: false } },
+        http: { body: { extra_body: true } },
+      },
+      compatibility: { toolSchema: "moonshot" },
+    })
+    const request = LLM.request({ model, prompt: "Say hello." })
+
+    expect(request.model.defaults?.limits).toEqual({ context: 128_000, output: 8_192 })
+    expect(request.model.defaults?.generation).toEqual({ maxTokens: 1_024, stop: ["END"] })
+    expect(request.model.defaults?.providerOptions).toEqual({ openai: { parallelToolCalls: false } })
+    expect(request.model.defaults?.http).toEqual({ body: { extra_body: true } })
+    expect(request.model.compatibility).toEqual({ toolSchema: "moonshot" })
+    expect(request.generation).toBeUndefined()
+    expect(request.providerOptions).toBeUndefined()
+    expect(request.http).toBeUndefined()
+  })
+
+  test("builds tool choices from names and tools", () => {
+    const tool = ToolDefinition.make({ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } })
+
+    expect(tool).toBeInstanceOf(ToolDefinition)
+    expect(ToolChoice.make("lookup")).toEqual(new ToolChoice({ type: "tool", name: "lookup" }))
+    expect(ToolChoice.named("required")).toEqual(new ToolChoice({ type: "tool", name: "required" }))
+    expect(ToolChoice.make(tool)).toEqual(new ToolChoice({ type: "tool", name: "lookup" }))
+  })
+
+  test("builds tool choice modes from reserved strings", () => {
+    expect(ToolChoice.make("auto")).toEqual(new ToolChoice({ type: "auto" }))
+    expect(ToolChoice.make("none")).toEqual(new ToolChoice({ type: "none" }))
+    expect(ToolChoice.make("required")).toEqual(new ToolChoice({ type: "required" }))
+    expect(
+      LLM.request({
+        model: Model.make({
+          id: "fake-model",
+          provider: "fake",
+          route: chatRoute,
+        }),
+        prompt: "Use tools if needed.",
+        toolChoice: "required",
+      }).toolChoice,
+    ).toEqual(new ToolChoice({ type: "required" }))
+  })
+
+  test("builds assistant tool calls and tool result messages", () => {
+    const call = ToolCallPart.make({ id: "call_1", name: "lookup", input: { query: "weather" } })
+    const result = ToolResultPart.make({ id: "call_1", name: "lookup", result: { temperature: 72 } })
+
+    expect(Message.assistant([call]).content).toEqual([call])
+    expect(Message.tool(result).content).toEqual([
+      { type: "tool-result", id: "call_1", name: "lookup", result: { type: "json", value: { temperature: 72 } } },
+    ])
+  })
+
+  test("builds chronological text-only system updates separately from the initial system prompt", () => {
+    const update = Message.system([
+      { type: "text", text: "Use parameterized SQL.", cache: new CacheHint({ type: "ephemeral" }) },
+    ])
+    const request = LLM.request({
+      model: Model.make({ id: "fake-model", provider: "fake", route: chatRoute }),
+      system: "Initial operator prompt.",
+      messages: [Message.user("Review this."), update],
+    })
+
+    expect(update).toBeInstanceOf(Message)
+    expect(update).toEqual({
+      role: "system",
+      content: [{ type: "text", text: "Use parameterized SQL.", cache: { type: "ephemeral" } }],
+    })
+    expect(request.system).toEqual([{ type: "text", text: "Initial operator prompt." }])
+    expect(request.messages.map((message) => message.role)).toEqual(["user", "system"])
+  })
+
+  test("extracts output text from response events", () => {
+    expect(
+      LLMResponse.text({
+        events: [
+          { type: "text-delta", id: "text-0", text: "hi" },
+          { type: "finish", reason: "stop" },
+        ],
+      }),
+    ).toBe("hi")
+  })
+})

packages/ai/test/prepare.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, test } from "bun:test"
+import { Effect, Schema } from "effect"
+import { HttpClientRequest } from "effect/unstable/http"
+import { LLM, mergeProviderOptions } from "../src"
+import { AnthropicMessages, OpenAIChat } from "../src/protocols"
+import { Auth, LLMClient } from "../src/route"
+import { it } from "./lib/effect"
+import { dynamicResponse } from "./lib/http"
+import { deltaChunk } from "./lib/openai-chunks"
+import { sseEvents } from "./lib/sse"
+
+const TargetJson = Schema.fromJsonString(Schema.Unknown)
+const decodeJson = Schema.decodeUnknownSync(TargetJson)
+
+describe("request option precedence", () => {
+  test("deep-merges provider option records and replaces arrays, primitives, and null", () => {
+    const merged = mergeProviderOptions(
+      {
+        openai: {
+          include: ["route"],
+          metadata: { route: true, shared: "route" },
+          nullable: "route",
+          primitive: "route",
+        },
+      },
+      {
+        openai: {
+          include: ["model"],
+          metadata: { model: true, shared: "model" },
+          nullable: null,
+          primitive: "model",
+        },
+      },
+      { openai: { metadata: { request: true }, primitive: false } },
+    )
+
+    expect(merged).toEqual({
+      openai: {
+        include: ["model"],
+        metadata: { route: true, model: true, request: true, shared: "model" },
+        nullable: null,
+        primitive: false,
+      },
+    })
+  })
+
+  it.effect("prepares bodies with route defaults, model defaults, and call options in order", () =>
+    Effect.gen(function* () {
+      const route = OpenAIChat.route.with({
+        endpoint: { baseURL: "https://api.openai.test/v1/" },
+        auth: Auth.bearer("test"),
+        generation: { maxTokens: 10, temperature: 1, stop: ["route"] },
+        providerOptions: { openai: { store: false, reasoningEffort: "low" } },
+      })
+      const model = route.model({
+        id: "gpt-4o-mini",
+        defaults: {
+          generation: { maxTokens: 20, temperature: 0.5, frequencyPenalty: 0.25, stop: ["model"] },
+          providerOptions: { openai: { reasoningEffort: "medium" } },
+        },
+      })
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        LLM.request({
+          model,
+          prompt: "Say hello.",
+          generation: { maxTokens: 30, topP: 0.9, stop: ["request"] },
+          providerOptions: { openai: { store: true } },
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        model: "gpt-4o-mini",
+        stream: true,
+        max_tokens: 30,
+        temperature: 0.5,
+        top_p: 0.9,
+        frequency_penalty: 0.25,
+        store: true,
+        reasoning_effort: "medium",
+      })
+      expect(prepared.body.stop).toEqual(["request"])
+    }),
+  )
+
+  it.effect("applies model HTTP defaults before request HTTP overlays", () =>
+    LLMClient.generate(
+      LLM.request({
+        model: OpenAIChat.route
+          .with({
+            endpoint: { baseURL: "https://api.openai.test/v1/" },
+            auth: Auth.bearer("fresh-key"),
+            http: {
+              body: { metadata: { route: true, shared: "route" }, value: "route" },
+              headers: { "x-route": "route", "x-shared": "route" },
+              query: { route: "1", shared: "route" },
+            },
+          })
+          .model({
+            id: "gpt-4o-mini",
+            defaults: {
+              http: {
+                body: { metadata: { model: true, shared: "model" }, value: "model" },
+                headers: { "x-model": "model", "x-shared": "model" },
+                query: { model: "1", shared: "model" },
+              },
+            },
+          }),
+        prompt: "Say hello.",
+        http: {
+          body: { metadata: { request: true }, value: null },
+          headers: { "x-request": "request" },
+          query: { request: "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?route=1&shared=model&model=1&request=1")
+            expect(web.headers.get("authorization")).toBe("Bearer fresh-key")
+            expect(web.headers.get("x-route")).toBe("route")
+            expect(web.headers.get("x-model")).toBe("model")
+            expect(web.headers.get("x-request")).toBe("request")
+            expect(web.headers.get("x-shared")).toBe("model")
+            expect(decodeJson(input.text)).toMatchObject({
+              metadata: { route: true, model: true, request: true, shared: "model" },
+              value: null,
+            })
+            return input.respond(sseEvents(deltaChunk({}, "stop")), {
+              headers: { "content-type": "text/event-stream" },
+            })
+          }),
+        ),
+      ),
+    ),
+  )
+
+  it.effect("rejects raw body overlays for protocol-owned roots", () =>
+    Effect.gen(function* () {
+      const model = OpenAIChat.route
+        .with({ endpoint: { baseURL: "https://api.openai.test/v1/" }, auth: Auth.bearer("test") })
+        .model({ id: "gpt-4o-mini" })
+      const error = yield* LLMClient.prepare(
+        LLM.request({
+          model,
+          prompt: "Say hello.",
+          http: { body: { model: "gpt-5", messages: [], tools: [] } },
+        }),
+      ).pipe(Effect.flip)
+
+      expect(error.reason).toMatchObject({
+        _tag: "InvalidRequest",
+        message: "http.body cannot overlay protocol-owned field(s): model, messages, tools",
+      })
+    }),
+  )
+
+  it.effect("uses model output limits after route limits and before call maxTokens", () =>
+    Effect.gen(function* () {
+      const route = AnthropicMessages.route.with({
+        endpoint: { baseURL: "https://api.anthropic.test/v1/" },
+        auth: Auth.header("x-api-key", "test"),
+        limits: { output: 128 },
+      })
+      const model = route.model({ id: "claude-sonnet-4-5", defaults: { limits: { output: 64 } } })
+      const withoutMaxTokens = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+        LLM.request({ model, prompt: "Say hello.", cache: "none" }),
+      )
+      const withMaxTokens = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+        LLM.request({ model, prompt: "Say hello.", cache: "none", generation: { maxTokens: 32 } }),
+      )
+
+      expect(withoutMaxTokens.body.max_tokens).toBe(64)
+      expect(withMaxTokens.body.max_tokens).toBe(32)
+    }),
+  )
+})

packages/ai/test/provider-error.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test"
+import { isContextOverflow } from "../src"
+import { classifyProviderFailure } from "../src/provider-error"
+
+describe("provider error classification", () => {
+  test("classifies Z.AI GLM token limit messages as context overflow", () => {
+    expect(isContextOverflow("tokens in request more than max tokens allowed")).toBe(true)
+  })
+
+  test("classifies V1 plain-text rate limit fallbacks", () => {
+    expect(
+      [
+        "Request rate increased too quickly",
+        "Rate limit exceeded, please try again later",
+        "Too many requests, please slow down",
+      ].map((message) => classifyProviderFailure({ message })._tag),
+    ).toEqual(["RateLimit", "RateLimit", "RateLimit"])
+  })
+
+  test("classifies V1 JSON rate limit fallbacks", () => {
+    expect(
+      [
+        '{"type":"error","error":{"type":"too_many_requests"}}',
+        '{"type":"error","error":{"code":"rate_limit_exceeded"}}',
+        '{"code":"bad_request","error":{"code":"rate_limit_exceeded"}}',
+        '{"type":"error","error":{"code":"unknown","type":"too_many_requests"}}',
+      ].map((message) => classifyProviderFailure({ message })._tag),
+    ).toEqual(["RateLimit", "RateLimit", "RateLimit", "RateLimit"])
+  })
+
+  test("classifies V1 overloaded provider codes", () => {
+    expect(
+      ['{"code":"resource_exhausted"}', '{"code":"service_unavailable"}'].map(
+        (message) => classifyProviderFailure({ message })._tag,
+      ),
+    ).toEqual(["ProviderInternal", "ProviderInternal"])
+  })
+
+  test("classifies nested provider codes when a top-level code is also present", () => {
+    expect(
+      [
+        '{"code":"bad_request","error":{"code":"usage_not_included"}}',
+        '{"code":"bad_request","error":{"code":"server_error"}}',
+        '{"code":"bad_request","error":{"type":"invalid_request_error"}}',
+      ].map((message) => classifyProviderFailure({ message })._tag),
+    ).toEqual(["QuotaExceeded", "ProviderInternal", "InvalidRequest"])
+  })
+
+  test("keeps unknown and malformed provider payloads non-retryable", () => {
+    expect(classifyProviderFailure({ message: '{"error":{"message":"no_kv_space"}}' })._tag).toBe("UnknownProvider")
+    expect(classifyProviderFailure({ message: '{"type":"error","error":{"code":123}}' })._tag).toBe("UnknownProvider")
+    expect(classifyProviderFailure({ message: "not-json" })._tag).toBe("UnknownProvider")
+  })
+})

packages/ai/test/provider-package.test.ts

@@ -0,0 +1,239 @@
+import { describe, expect, test } from "bun:test"
+import { model } from "@opencode-ai/ai/providers/openai"
+
+describe("provider package entrypoints", () => {
+  test("semantic API aliases expose the same contract", async () => {
+    const modules = await Promise.all([
+      import("@opencode-ai/ai/providers/openai"),
+      import("@opencode-ai/ai/providers/openai/responses"),
+      import("@opencode-ai/ai/providers/openai/chat"),
+      import("@opencode-ai/ai/providers/anthropic"),
+      import("@opencode-ai/ai/providers/anthropic-compatible"),
+      import("@opencode-ai/ai/providers/openai-compatible"),
+      import("@opencode-ai/ai/providers/openai-compatible/responses"),
+      import("@opencode-ai/ai/providers/amazon-bedrock"),
+      import("@opencode-ai/ai/providers/azure"),
+      import("@opencode-ai/ai/providers/azure/responses"),
+      import("@opencode-ai/ai/providers/azure/chat"),
+      import("@opencode-ai/ai/providers/google"),
+      import("@opencode-ai/ai/providers/google-vertex"),
+      import("@opencode-ai/ai/providers/google-vertex/anthropic"),
+    ])
+
+    for (const module of modules) expect(module.model).toBeFunction()
+    expect(modules[0].model).toBe(modules[1].model)
+    expect(modules[8].model).toBe(modules[9].model)
+  })
+
+  test("maps package settings onto the executable model", () => {
+    const selected = model("gpt-5", {
+      apiKey: "fixture",
+      baseURL: "https://api.openai.test/v1",
+      headers: { "x-application": "opencode" },
+      body: { service_tier: "priority" },
+      limits: { context: 200_000, output: 64_000 },
+      unrelatedInheritedSetting: true,
+    })
+
+    expect(selected.route.id).toBe("openai-responses")
+    expect(selected.route.defaults.headers).toEqual({ "x-application": "opencode" })
+    expect(selected.route.defaults.http?.body).toEqual({ service_tier: "priority" })
+    expect(selected.route.defaults.limits).toEqual({ context: 200_000, output: 64_000 })
+  })
+
+  test("selects transport without changing the semantic API", () => {
+    expect(model("gpt-5", { apiKey: "fixture" }).route.id).toBe("openai-responses")
+    expect(model("gpt-5", { apiKey: "fixture", transport: "websocket" }).route.id).toBe("openai-responses-websocket")
+  })
+
+  test("maps OpenAI-compatible Responses settings onto the executable model", async () => {
+    const OpenAICompatibleResponses = await import("@opencode-ai/ai/providers/openai-compatible/responses")
+    const selected = OpenAICompatibleResponses.model("custom-model", {
+      apiKey: "fixture",
+      baseURL: "https://responses.example.test/v1",
+      provider: "example",
+      headers: { "x-application": "opencode" },
+      body: { service_tier: "priority" },
+      limits: { context: 200_000, output: 64_000 },
+      providerOptions: { openai: { reasoningEffort: "low", store: true } },
+    })
+
+    expect(String(selected.provider)).toBe("example")
+    expect(selected.route.id).toBe("openai-compatible-responses")
+    expect(selected.route.endpoint).toMatchObject({
+      baseURL: "https://responses.example.test/v1",
+      path: "/responses",
+    })
+    expect(selected.route.defaults.headers).toEqual({ "x-application": "opencode" })
+    expect(selected.route.defaults.http?.body).toEqual({ service_tier: "priority" })
+    expect(selected.route.defaults.limits).toEqual({ context: 200_000, output: 64_000 })
+    expect(selected.route.defaults.providerOptions).toEqual({
+      openai: { reasoningEffort: "low", store: true },
+    })
+  })
+
+  test("maps Anthropic-compatible settings onto the executable model", async () => {
+    const AnthropicCompatible = await import("@opencode-ai/ai/providers/anthropic-compatible")
+    const selected = AnthropicCompatible.model("compatible-model", {
+      apiKey: "fixture",
+      baseURL: "https://messages.example.test/v1",
+      provider: "example",
+      headers: { "x-application": "opencode" },
+      body: { metadata: { user_id: "user_1" } },
+      limits: { context: 200_000, output: 64_000 },
+    })
+
+    expect(String(selected.provider)).toBe("example")
+    expect(selected.route.id).toBe("anthropic-messages")
+    expect(selected.route.endpoint).toMatchObject({
+      baseURL: "https://messages.example.test/v1",
+      path: "/messages",
+    })
+    expect(selected.route.defaults.headers).toEqual({ "x-application": "opencode" })
+    expect(selected.route.defaults.http?.body).toEqual({ metadata: { user_id: "user_1" } })
+    expect(selected.route.defaults.limits).toEqual({ context: 200_000, output: 64_000 })
+  })
+
+  test("requires an Anthropic-compatible base URL at runtime", async () => {
+    const AnthropicCompatible = await import("@opencode-ai/ai/providers/anthropic-compatible")
+    expect(() =>
+      Reflect.apply(AnthropicCompatible.model, undefined, ["compatible-model", { apiKey: "fixture" }]),
+    ).toThrow("Anthropic-compatible providers require a baseURL")
+  })
+
+  test("rejects conflicting Anthropic-compatible auth settings at runtime", async () => {
+    const Anthropic = await import("@opencode-ai/ai/providers/anthropic")
+    const AnthropicCompatible = await import("@opencode-ai/ai/providers/anthropic-compatible")
+    expect(() =>
+      Reflect.apply(AnthropicCompatible.model, undefined, [
+        "compatible-model",
+        {
+          apiKey: "fixture",
+          authToken: "token",
+          baseURL: "https://messages.example.test/v1",
+        },
+      ]),
+    ).toThrow("Anthropic-compatible apiKey cannot be combined with authToken")
+    expect(() =>
+      Reflect.apply(Anthropic.model, undefined, ["claude-sonnet-4-6", { apiKey: "fixture", authToken: "token" }]),
+    ).toThrow("Anthropic apiKey cannot be combined with authToken")
+  })
+
+  test("maps legacy OpenAI organization and project settings to headers", () => {
+    const selected = model("gpt-5", {
+      apiKey: "fixture",
+      organization: "org_123",
+      project: "proj_123",
+    })
+
+    expect(selected.route.defaults.headers).toMatchObject({
+      "OpenAI-Organization": "org_123",
+      "OpenAI-Project": "proj_123",
+    })
+  })
+
+  test("selects Azure API entrypoints with the same model contract", async () => {
+    const Azure = await import("@opencode-ai/ai/providers/azure")
+    const AzureChat = await import("@opencode-ai/ai/providers/azure/chat")
+    const AzureResponses = await import("@opencode-ai/ai/providers/azure/responses")
+    const settings = {
+      apiKey: "fixture",
+      resourceName: "opencode-test",
+      headers: { "x-application": "opencode" },
+      body: { service_tier: "priority" },
+      limits: { context: 200_000, output: 64_000 },
+    }
+
+    const responses = AzureResponses.model("deployment", settings)
+    const chat = AzureChat.model("deployment", settings)
+
+    expect(Azure.model("deployment", settings).route.id).toBe("azure-openai-responses")
+    expect(responses.route.id).toBe("azure-openai-responses")
+    expect(responses.route.endpoint.baseURL).toBe("https://opencode-test.openai.azure.com/openai/v1")
+    expect(responses.route.defaults.headers).toEqual({ "x-application": "opencode" })
+    expect(responses.route.defaults.http?.body).toEqual({ service_tier: "priority" })
+    expect(responses.route.defaults.limits).toEqual({ context: 200_000, output: 64_000 })
+    expect(chat.route.id).toBe("azure-openai-chat")
+  })
+
+  test("maps Google package settings onto the Gemini model", async () => {
+    const Google = await import("@opencode-ai/ai/providers/google")
+    const selected = Google.model("gemini-2.5-flash", {
+      apiKey: "fixture",
+      baseURL: "https://generativelanguage.test/v1beta",
+      headers: { "x-application": "opencode" },
+      body: { safetySettings: [] },
+      limits: { context: 1_000_000, output: 65_536 },
+      providerOptions: { gemini: { thinkingConfig: { thinkingBudget: 1_024 } } },
+    })
+
+    expect(selected.route.id).toBe("gemini")
+    expect(selected.route.endpoint.baseURL).toBe("https://generativelanguage.test/v1beta")
+    expect(selected.route.defaults.headers).toEqual({ "x-application": "opencode" })
+    expect(selected.route.defaults.http?.body).toEqual({ safetySettings: [] })
+    expect(selected.route.defaults.limits).toEqual({ context: 1_000_000, output: 65_536 })
+    expect(selected.route.defaults.providerOptions).toEqual({
+      gemini: { thinkingConfig: { thinkingBudget: 1_024 } },
+    })
+  })
+
+  test("selects Vertex entrypoints with the same model contract", async () => {
+    const GoogleVertex = await import("@opencode-ai/ai/providers/google-vertex")
+    const GoogleVertexAnthropic = await import("@opencode-ai/ai/providers/google-vertex/anthropic")
+    const gemini = GoogleVertex.model("gemini-3.5-flash", {
+      apiKey: "fixture",
+      headers: { "x-application": "opencode" },
+      body: { safetySettings: [] },
+      limits: { context: 1_000_000, output: 65_536 },
+    })
+    const anthropic = GoogleVertexAnthropic.model("claude-sonnet-4-6", {
+      accessToken: "fixture",
+      location: "global",
+      project: "vertex-project",
+    })
+
+    expect(gemini.route.id).toBe("google-vertex-gemini")
+    expect(gemini.route.endpoint.baseURL).toBe("https://aiplatform.googleapis.com/v1/publishers/google")
+    expect(gemini.route.defaults.headers).toEqual({ "x-application": "opencode" })
+    expect(gemini.route.defaults.http?.body).toEqual({ safetySettings: [] })
+    expect(gemini.route.defaults.limits).toEqual({ context: 1_000_000, output: 65_536 })
+    expect(
+      GoogleVertex.model("gemini-3.5-flash", {
+        accessToken: "fixture",
+        location: "eu",
+        project: "vertex-project",
+      }).route.endpoint.baseURL,
+    ).toBe("https://aiplatform.eu.rep.googleapis.com/v1beta1/projects/vertex-project/locations/eu/publishers/google")
+    expect(anthropic.route.id).toBe("google-vertex-anthropic")
+    expect(anthropic.route.endpoint.baseURL).toBe(
+      "https://aiplatform.googleapis.com/v1/projects/vertex-project/locations/global/publishers/anthropic/models",
+    )
+  })
+
+  test("rejects conflicting Vertex auth settings at runtime", async () => {
+    const GoogleVertex = await import("@opencode-ai/ai/providers/google-vertex")
+    const GoogleVertexAnthropic = await import("@opencode-ai/ai/providers/google-vertex/anthropic")
+    const Providers = await import("@opencode-ai/ai/providers")
+    expect(() =>
+      Reflect.apply(GoogleVertex.model, undefined, [
+        "gemini-3.5-flash",
+        { accessToken: "token", apiKey: "fixture", project: "vertex-project" },
+      ]),
+    ).toThrow("Google Vertex apiKey cannot be combined with accessToken or auth")
+    const configured = Reflect.apply(GoogleVertex.configure, undefined, [
+      { accessToken: "token", auth: {}, project: "vertex-project" },
+    ])
+    expect(() => configured.model("gemini-3.5-flash")).toThrow("Google Vertex accessToken cannot be combined with auth")
+    expect(() =>
+      Reflect.apply(GoogleVertexAnthropic.model, undefined, [
+        "claude-sonnet-4-6",
+        { apiKey: "fixture", project: "vertex-project" },
+      ]),
+    ).toThrow("Google Vertex Anthropic does not support API keys")
+    expect(() =>
+      Reflect.apply(Providers.GoogleVertexAnthropic.configure, undefined, [
+        { apiKey: "fixture", project: "vertex-project" },
+      ]),
+    ).toThrow("Google Vertex Anthropic does not support API keys")
+  })
+})

packages/ai/test/provider.types.ts

@@ -0,0 +1,41 @@
+import { Provider } from "../src/provider"
+import { ProviderID, type Model } from "../src/schema"
+
+declare const model: (id: string) => Model
+declare const requiredModel: (id: string, options: { readonly baseURL: string }) => Model
+declare const chat: (id: string, options: { readonly apiKey: string }) => Model
+
+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,
+})
+
+// Provider.make is advanced structural typing coverage; built-in providers use
+// configure(...).model(id) facades instead of second-argument selectors.
+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/ai/test/provider/anthropic-messages-cache.recorded.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { CacheHint, LLM } from "../../src"
+import { LLMClient } from "../../src/route"
+import * as Anthropic from "../../src/providers/anthropic"
+import { LARGE_CACHEABLE_SYSTEM } from "../recorded-scenarios"
+import { recordedTests } from "../recorded-test"
+
+const model = Anthropic.configure({
+  apiKey: process.env.ANTHROPIC_API_KEY ?? "fixture",
+}).model("claude-haiku-4-5-20251001")
+
+// Two identical generations in a row. The first call writes the prefix into
+// Anthropic's cache; the second should report a cache read against the same
+// prefix. Cassette captures both interactions in order.
+const cacheRequest = LLM.request({
+  id: "recorded_anthropic_cache",
+  model,
+  system: [{ type: "text", text: LARGE_CACHEABLE_SYSTEM, cache: new CacheHint({ type: "ephemeral" }) }],
+  prompt: "Say hi.",
+  // Manual hint on the system part is the only marker we want here — skip the
+  // auto-policy's latest-user-message breakpoint so the cassette body matches.
+  cache: "none",
+  generation: { maxTokens: 16, temperature: 0 },
+})
+
+const recorded = recordedTests({
+  prefix: "anthropic-messages-cache",
+  provider: "anthropic",
+  protocol: "anthropic-messages",
+  requires: ["ANTHROPIC_API_KEY"],
+  // Two identical requests in one cassette — replay walks the cassette in
+  // recording order so the second call replays the cached-hit interaction.
+  options: {
+    redact: { allowRequestHeaders: ["anthropic-version"] },
+  },
+})
+
+describe("Anthropic Messages cache recorded", () => {
+  recorded.effect.with("writes then reads cache_control on identical second call", { tags: ["cache"] }, () =>
+    Effect.gen(function* () {
+      const first = yield* LLMClient.generate(cacheRequest)
+      // The first call may write the cache (cacheWriteInputTokens > 0) or it
+      // may be a fresh miss (both fields 0) depending on whether the prefix is
+      // already warm on Anthropic's side. The assertion that matters is that
+      // the SECOND call reports a non-zero cache read.
+      expect(first.usage?.cacheReadInputTokens ?? 0).toBeGreaterThanOrEqual(0)
+
+      const second = yield* LLMClient.generate(cacheRequest)
+      expect(second.usage?.cacheReadInputTokens ?? 0).toBeGreaterThan(0)
+    }),
+  )
+})

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

@@ -0,0 +1,45 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { LLM, LLMError, Message, ToolCallPart } from "../../src"
+import { LLMClient } from "../../src/route"
+import * as Anthropic from "../../src/providers/anthropic"
+import { weatherToolName } from "../recorded-scenarios"
+import { recordedTests } from "../recorded-test"
+
+const model = Anthropic.configure({
+  apiKey: process.env.ANTHROPIC_API_KEY ?? "fixture",
+}).model("claude-haiku-4-5-20251001")
+
+const malformedToolOrderRequest = LLM.request({
+  id: "recorded_anthropic_malformed_tool_order",
+  model,
+  messages: [
+    Message.assistant([
+      ToolCallPart.make({ id: "call_1", name: weatherToolName, input: { city: "Paris" } }),
+      { type: "text", text: "I will check the weather." },
+    ]),
+    Message.tool({ id: "call_1", name: weatherToolName, result: { temperature: "72F" } }),
+    Message.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: { redact: { allowRequestHeaders: ["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/ai/test/provider/anthropic-messages.test.ts

@@ -0,0 +1,912 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { HttpClientRequest } from "effect/unstable/http"
+import { CacheHint, LLM, LLMError, Message, ToolCallPart, Usage } from "../../src"
+import { Auth, LLMClient } from "../../src/route"
+import * as AnthropicMessages from "../../src/protocols/anthropic-messages"
+import { continuationRequest, nativeAnthropicMessagesContinuation } from "../continuation-scenarios"
+import { it } from "../lib/effect"
+import { dynamicResponse, fixedResponse } from "../lib/http"
+import { sseEvents } from "../lib/sse"
+
+const model = AnthropicMessages.route
+  .with({ endpoint: { baseURL: "https://api.anthropic.test/v1/" }, auth: Auth.header("x-api-key", "test") })
+  .model({ id: "claude-sonnet-4-5" })
+
+const opus48 = AnthropicMessages.route
+  .with({ endpoint: { baseURL: "https://api.anthropic.test/v1/" }, auth: Auth.header("x-api-key", "test") })
+  .model({ id: "claude-opus-4-8" })
+
+const request = LLM.request({
+  id: "req_1",
+  model,
+  system: { type: "text", text: "You are concise.", cache: new CacheHint({ type: "ephemeral" }) },
+  prompt: "Say hello.",
+  // This fixture predates the `cache: "auto"` default; pin the policy off so
+  // existing wire-shape assertions only see the manual hint on the system part.
+  cache: "none",
+  generation: { maxTokens: 20, temperature: 0 },
+})
+
+type AnthropicToolResult = Extract<
+  AnthropicMessages.AnthropicMessagesBody["messages"][number]["content"][number],
+  { readonly type: "tool_result" }
+>
+
+const expectToolResult = (body: AnthropicMessages.AnthropicMessagesBody): AnthropicToolResult => {
+  const result = body.messages
+    .flatMap((message) => (message.role === "user" ? message.content : []))
+    .find((block): block is AnthropicToolResult => block.type === "tool_result")
+  expect(result).toBeDefined()
+  return result!
+}
+
+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("lowers adaptive thinking settings with effort", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+        LLM.updateRequest(request, {
+          providerOptions: {
+            anthropic: { thinking: { type: "adaptive", display: "summarized" }, effort: "low" },
+          },
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        thinking: { type: "adaptive", display: "summarized" },
+        output_config: { effort: "low" },
+      })
+    }),
+  )
+
+  it.effect("lowers chronological system updates natively for Claude Opus 4.8 with cache hints", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+        LLM.request({
+          model: opus48,
+          messages: [
+            Message.user("Before."),
+            Message.system([{ type: "text", text: "Operator update.", cache: new CacheHint({ type: "ephemeral" }) }]),
+            Message.assistant("After."),
+          ],
+          cache: "none",
+        }),
+      )
+
+      expect(prepared.body.messages).toEqual([
+        { role: "user", content: [{ type: "text", text: "Before." }] },
+        {
+          role: "system",
+          content: [{ type: "text", text: "Operator update.", cache_control: { type: "ephemeral" } }],
+        },
+        { role: "assistant", content: [{ type: "text", text: "After." }] },
+      ])
+    }),
+  )
+
+  it.effect("lowers chronological system updates to wrapped user text for unsupported Anthropic models", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+        LLM.request({
+          model,
+          messages: [
+            Message.user("Before."),
+            Message.system("Treat </system-update> literally."),
+            Message.assistant("After."),
+          ],
+          cache: "none",
+        }),
+      )
+
+      expect(prepared.body.messages).toEqual([
+        {
+          role: "user",
+          content: [
+            { type: "text", text: "Before." },
+            { type: "text", text: "<system-update>\nTreat &lt;/system-update&gt; literally.\n</system-update>" },
+          ],
+        },
+        { role: "assistant", content: [{ type: "text", text: "After." }] },
+      ])
+    }),
+  )
+
+  it.effect("rejects non-text chronological system update content before send", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.prepare(
+        LLM.request({
+          model: opus48,
+          messages: [
+            Message.user("Before."),
+            Message.make({ role: "system", content: { type: "media", mediaType: "image/png", data: "AAECAw==" } }),
+          ],
+        }),
+      ).pipe(Effect.flip)
+
+      expect(error.message).toContain("Anthropic Messages system messages only support text content for now")
+    }),
+  )
+
+  it.effect("falls back for unsupported native chronological system update placement", () =>
+    Effect.gen(function* () {
+      expect(
+        (yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+          LLM.request({
+            model: opus48,
+            messages: [Message.assistant("Plain."), Message.system("After plain assistant.")],
+            cache: "none",
+          }),
+        )).body.messages,
+      ).toEqual([
+        { role: "assistant", content: [{ type: "text", text: "Plain." }] },
+        {
+          role: "user",
+          content: [{ type: "text", text: "<system-update>\nAfter plain assistant.\n</system-update>" }],
+        },
+      ])
+      expect(
+        (yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+          LLM.request({ model: opus48, messages: [Message.system("First.")], cache: "none" }),
+        )).body.messages,
+      ).toEqual([{ role: "user", content: [{ type: "text", text: "<system-update>\nFirst.\n</system-update>" }] }])
+      expect(
+        (yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+          LLM.request({
+            model: opus48,
+            messages: [Message.user("Before."), Message.system("One."), Message.system("Two.")],
+            cache: "none",
+          }),
+        )).body.messages,
+      ).toEqual([
+        {
+          role: "user",
+          content: [
+            { type: "text", text: "Before." },
+            { type: "text", text: "<system-update>\nOne.\n</system-update>" },
+            { type: "text", text: "<system-update>\nTwo.\n</system-update>" },
+          ],
+        },
+      ])
+    }),
+  )
+
+  it.effect("rejects a system update between a local tool call and its result", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.prepare(
+        LLM.request({
+          model: opus48,
+          messages: [
+            Message.user("Use the tool."),
+            Message.assistant([ToolCallPart.make({ id: "call_1", name: "lookup", input: {} })]),
+            Message.system("Too early."),
+            Message.tool({ id: "call_1", name: "lookup", result: "Done." }),
+          ],
+          cache: "none",
+        }),
+      ).pipe(Effect.flip)
+
+      expect(error.message).toContain("system updates cannot split a local tool call from its tool result")
+    }),
+  )
+
+  it.effect("prepares tool call and tool result messages", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+        LLM.request({
+          id: "req_tool_result",
+          model,
+          messages: [
+            Message.user("What is the weather?"),
+            Message.assistant([ToolCallPart.make({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
+            Message.tool({ id: "call_1", name: "lookup", result: { forecast: "sunny" } }),
+          ],
+          cache: "none",
+        }),
+      )
+
+      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,
+      })
+    }),
+  )
+
+  // Regression: screenshot/read tool results must stay structured so base64
+  // image data is not JSON-stringified into `tool_result.content`.
+  it.effect("lowers image tool-result content as structured image blocks", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+        LLM.request({
+          id: "req_tool_result_image",
+          model,
+          messages: [
+            Message.user("Show me the screenshot."),
+            Message.assistant([ToolCallPart.make({ id: "call_1", name: "read", input: { filePath: "shot.png" } })]),
+            Message.tool({
+              id: "call_1",
+              name: "read",
+              resultType: "content",
+              result: [
+                { type: "text", text: "Image read successfully" },
+                { type: "file", uri: "data:image/png;base64,AAECAw==", mime: "image/png" },
+              ],
+            }),
+          ],
+          cache: "none",
+        }),
+      )
+
+      expect(expectToolResult(prepared.body).content).toEqual([
+        { type: "text", text: "Image read successfully" },
+        { type: "image", source: { type: "base64", media_type: "image/png", data: "AAECAw==" } },
+      ])
+    }),
+  )
+
+  it.effect("lowers single-image tool-result content as a structured image block", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+        LLM.request({
+          id: "req_tool_result_image_only",
+          model,
+          messages: [
+            Message.assistant([ToolCallPart.make({ id: "call_1", name: "screenshot", input: {} })]),
+            Message.tool({
+              id: "call_1",
+              name: "screenshot",
+              resultType: "content",
+              result: [{ type: "file", uri: "data:image/jpeg;base64,/9j/AA==", mime: "image/jpeg" }],
+            }),
+          ],
+          cache: "none",
+        }),
+      )
+
+      expect(expectToolResult(prepared.body).content).toEqual([
+        { type: "image", source: { type: "base64", media_type: "image/jpeg", data: "/9j/AA==" } },
+      ])
+    }),
+  )
+
+  it.effect("rejects non-image media in tool-result content with a clear error", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_tool_result_unsupported_media",
+          model,
+          messages: [
+            Message.assistant([ToolCallPart.make({ id: "call_1", name: "fetch", input: {} })]),
+            Message.tool({
+              id: "call_1",
+              name: "fetch",
+              resultType: "content",
+              result: [{ type: "file", uri: "data:audio/mpeg;base64,AAECAw==", mime: "audio/mpeg" }],
+            }),
+          ],
+          cache: "none",
+        }),
+      ).pipe(Effect.flip)
+
+      expect(error.message).toContain("Anthropic Messages")
+      expect(error.message).toContain("audio/mpeg")
+    }),
+  )
+
+  it.effect("prepares the composed native continuation request", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<AnthropicMessages.AnthropicMessagesBody>(
+        continuationRequest({
+          id: "req_native_continuation_anthropic",
+          model,
+          features: nativeAnthropicMessagesContinuation,
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        system: [{ type: "text", text: "You are concise. Continue from the provided history." }],
+        messages: [
+          {
+            role: "user",
+            content: [
+              { type: "text", text: "What is shown here?" },
+              { type: "image", source: { type: "base64", media_type: "image/png", data: "AAECAw==" } },
+            ],
+          },
+          {
+            role: "assistant",
+            content: [
+              { type: "thinking", thinking: "I inspected the previous turn.", signature: "sig_continuation_1" },
+              { type: "text", text: "It shows a small test image." },
+            ],
+          },
+          { role: "user", content: [{ type: "text", text: "Check the weather in Paris before continuing." }] },
+          {
+            role: "assistant",
+            content: [{ type: "tool_use", id: "call_weather_1", name: "get_weather", input: { city: "Paris" } }],
+          },
+          {
+            role: "user",
+            content: [{ type: "tool_result", tool_use_id: "call_weather_1", content: '{"temperature":22}' }],
+          },
+          { role: "assistant", content: [{ type: "text", text: "Paris is 22 degrees." }] },
+          { role: "user", content: [{ type: "text", text: "Continue from this conversation in one short sentence." }] },
+        ],
+      })
+      expect(prepared.body.tools).toEqual([expect.objectContaining({ name: "get_weather" })])
+    }),
+  )
+
+  it.effect("lowers preserved Anthropic reasoning signature metadata", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model,
+          messages: [
+            Message.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: 6,
+        outputTokens: 2,
+        nonCachedInputTokens: 5,
+        cacheReadInputTokens: 1,
+        totalTokens: 8,
+      })
+      expect(response.events.find((event) => event.type === "reasoning-end")).toMatchObject({
+        providerMetadata: { anthropic: { signature: "sig_1" } },
+      })
+      expect(response.message.content).toEqual([
+        { type: "text", text: "Hello!" },
+        { type: "reasoning", text: "thinking", providerMetadata: { anthropic: { signature: "sig_1" } } },
+      ])
+      expect(response.events.at(-1)).toMatchObject({
+        type: "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)))
+      const usage = new Usage({
+        inputTokens: 5,
+        outputTokens: 1,
+        nonCachedInputTokens: 5,
+        cacheReadInputTokens: undefined,
+        cacheWriteInputTokens: undefined,
+        totalTokens: 6,
+        providerMetadata: { anthropic: { input_tokens: 5, output_tokens: 1 } },
+      })
+
+      expect(response.toolCalls).toEqual([
+        {
+          type: "tool-call",
+          id: "call_1",
+          name: "lookup",
+          input: { query: "weather" },
+          providerExecuted: undefined,
+          providerMetadata: undefined,
+        },
+      ])
+      expect(response.events).toEqual([
+        { type: "step-start", index: 0 },
+        { type: "tool-input-start", id: "call_1", name: "lookup" },
+        { type: "tool-input-delta", id: "call_1", name: "lookup", text: '{"query"' },
+        { type: "tool-input-delta", id: "call_1", name: "lookup", text: ':"weather"}' },
+        { type: "tool-input-end", id: "call_1", name: "lookup", providerMetadata: undefined },
+        {
+          type: "tool-call",
+          id: "call_1",
+          name: "lookup",
+          input: { query: "weather" },
+          providerExecuted: undefined,
+          providerMetadata: undefined,
+        },
+        { type: "step-finish", index: 0, reason: "tool-calls", usage, providerMetadata: undefined },
+        {
+          type: "finish",
+          reason: "tool-calls",
+          providerMetadata: undefined,
+          usage,
+        },
+      ])
+    }),
+  )
+
+  it.effect("fails with a typed provider error for stream error frames", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.generate(request).pipe(
+        Effect.provide(
+          fixedResponse(sseEvents({ type: "error", error: { type: "overloaded_error", message: "Overloaded" } })),
+        ),
+        Effect.flip,
+      )
+
+      expect(error.reason).toMatchObject({ _tag: "ProviderInternal", message: "overloaded_error: Overloaded" })
+    }),
+  )
+
+  it.effect("classifies prompt-too-long provider errors", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.generate(request).pipe(
+        Effect.provide(
+          fixedResponse(
+            sseEvents({
+              type: "error",
+              error: { type: "invalid_request_error", message: "prompt is too long: 210000 tokens" },
+            }),
+          ),
+        ),
+        Effect.flip,
+      )
+
+      expect(error.reason).toMatchObject({
+        _tag: "InvalidRequest",
+        message: "invalid_request_error: prompt is too long: 210000 tokens",
+        classification: "context-overflow",
+      })
+    }),
+  )
+
+  it.effect("falls back to error type when no message is present", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.generate(request).pipe(
+        Effect.provide(fixedResponse(sseEvents({ type: "error", error: { type: "overloaded_error", message: "" } }))),
+        Effect.flip,
+      )
+
+      expect(error.reason).toMatchObject({ _tag: "ProviderInternal", message: "overloaded_error" })
+    }),
+  )
+
+  it.effect("falls back to a stable default when error payload is absent", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.generate(request).pipe(
+        Effect.provide(fixedResponse(sseEvents({ type: "error" }))),
+        Effect.flip,
+      )
+
+      expect(error.reason).toMatchObject({ _tag: "UnknownProvider", message: "Anthropic Messages stream error" })
+    }),
+  )
+
+  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: "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: [
+            Message.user("Search for something."),
+            Message.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." },
+            ]),
+            Message.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: [
+            Message.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("continues a conversation with user image content", () =>
+    Effect.gen(function* () {
+      const response = yield* LLMClient.generate(
+        LLM.request({
+          id: "req_media",
+          model,
+          messages: [
+            Message.user([
+              { type: "text", text: "What is in this image?" },
+              { type: "media", mediaType: "image/png", data: "AAECAw==" },
+            ]),
+          ],
+        }),
+      ).pipe(
+        Effect.provide(
+          dynamicResponse((input) =>
+            Effect.gen(function* () {
+              const web = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+              expect(yield* Effect.promise(() => web.json())).toMatchObject({
+                messages: [
+                  {
+                    role: "user",
+                    content: [
+                      { type: "text", text: "What is in this image?" },
+                      { type: "image", source: { type: "base64", media_type: "image/png", data: "AAECAw==" } },
+                    ],
+                  },
+                ],
+              })
+              return input.respond(
+                sseEvents(
+                  { type: "content_block_start", index: 0, content_block: { type: "text", text: "" } },
+                  { type: "content_block_delta", index: 0, delta: { type: "text_delta", text: "An image." } },
+                  { type: "content_block_stop", index: 0 },
+                  { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 3 } },
+                  { type: "message_stop" },
+                ),
+                { headers: { "content-type": "text/event-stream" } },
+              )
+            }),
+          ),
+        ),
+      )
+
+      expect(response.text).toBe("An image.")
+    }),
+  )
+
+  it.effect("maps ttlSeconds >= 3600 to cache_control ttl: '1h'", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model,
+          system: { type: "text", text: "system", cache: new CacheHint({ type: "ephemeral", ttlSeconds: 3600 }) },
+          prompt: "hi",
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        system: [{ type: "text", text: "system", cache_control: { type: "ephemeral", ttl: "1h" } }],
+      })
+    }),
+  )
+
+  it.effect("emits cache_control on tool definitions and tool-result blocks", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model,
+          tools: [
+            {
+              name: "lookup",
+              description: "lookup tool",
+              inputSchema: { type: "object", properties: {} },
+              cache: new CacheHint({ type: "ephemeral" }),
+            },
+          ],
+          messages: [
+            Message.user("What's the weather?"),
+            Message.assistant([ToolCallPart.make({ id: "call_1", name: "lookup", input: {} })]),
+            Message.tool({
+              id: "call_1",
+              name: "lookup",
+              result: { temp: 72 },
+              cache: new CacheHint({ type: "ephemeral" }),
+            }),
+          ],
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        tools: [{ name: "lookup", cache_control: { type: "ephemeral" } }],
+        messages: [
+          { role: "user", content: [{ type: "text", text: "What's the weather?" }] },
+          { role: "assistant", content: [{ type: "tool_use", id: "call_1", name: "lookup" }] },
+          {
+            role: "user",
+            content: [{ type: "tool_result", tool_use_id: "call_1", cache_control: { type: "ephemeral" } }],
+          },
+        ],
+      })
+    }),
+  )
+
+  it.effect("drops cache_control breakpoints past the 4-per-request cap", () =>
+    Effect.gen(function* () {
+      const hint = new CacheHint({ type: "ephemeral" })
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model,
+          system: [
+            { type: "text", text: "a", cache: hint },
+            { type: "text", text: "b", cache: hint },
+            { type: "text", text: "c", cache: hint },
+            { type: "text", text: "d", cache: hint },
+            { type: "text", text: "e", cache: hint },
+            { type: "text", text: "f", cache: hint },
+          ],
+          prompt: "hi",
+        }),
+      )
+
+      const system = (prepared.body as { system: Array<{ cache_control?: unknown }> }).system
+      const marked = system.filter((part) => part.cache_control !== undefined)
+      expect(marked).toHaveLength(4)
+      expect(system[4]?.cache_control).toBeUndefined()
+      expect(system[5]?.cache_control).toBeUndefined()
+    }),
+  )
+
+  it.effect("spends breakpoint budget on tools before system before messages", () =>
+    Effect.gen(function* () {
+      const hint = new CacheHint({ type: "ephemeral" })
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model,
+          tools: [
+            {
+              name: "t1",
+              description: "t1",
+              inputSchema: { type: "object", properties: {} },
+              cache: hint,
+            },
+            {
+              name: "t2",
+              description: "t2",
+              inputSchema: { type: "object", properties: {} },
+              cache: hint,
+            },
+            {
+              name: "t3",
+              description: "t3",
+              inputSchema: { type: "object", properties: {} },
+              cache: hint,
+            },
+            {
+              name: "t4",
+              description: "t4",
+              inputSchema: { type: "object", properties: {} },
+              cache: hint,
+            },
+          ],
+          system: [{ type: "text", text: "system-tail", cache: hint }],
+          messages: [Message.user([{ type: "text", text: "message-tail", cache: hint }])],
+        }),
+      )
+
+      const body = prepared.body as {
+        tools: Array<{ cache_control?: unknown }>
+        system: Array<{ cache_control?: unknown }>
+        messages: Array<{ content: Array<{ cache_control?: unknown }> }>
+      }
+      expect(body.tools.every((t) => t.cache_control !== undefined)).toBe(true)
+      expect(body.system[0]?.cache_control).toBeUndefined()
+      expect(body.messages[0]?.content[0]?.cache_control).toBeUndefined()
+    }),
+  )
+})

packages/ai/test/provider/bedrock-converse-cache.recorded.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { CacheHint, LLM } from "../../src"
+import { LLMClient } from "../../src/route"
+import { AmazonBedrock } from "../../src/providers"
+import { LARGE_CACHEABLE_SYSTEM } from "../recorded-scenarios"
+import { recordedTests } from "../recorded-test"
+
+const RECORDING_REGION = process.env.BEDROCK_RECORDING_REGION ?? "us-east-1"
+
+// Use a Claude model on Bedrock — Nova has automatic prefix caching that
+// doesn't reliably surface `cacheRead`/`cacheWrite` in usage, so the second
+// call wouldn't deterministically prove cache mapping works. Override with
+// BEDROCK_CACHE_MODEL_ID if your account has access elsewhere.
+const model = AmazonBedrock.configure({
+  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,
+  },
+}).model(process.env.BEDROCK_CACHE_MODEL_ID ?? "us.anthropic.claude-haiku-4-5-20251001-v1:0")
+
+const cacheRequest = LLM.request({
+  id: "recorded_bedrock_cache",
+  model,
+  system: [{ type: "text", text: LARGE_CACHEABLE_SYSTEM, cache: new CacheHint({ type: "ephemeral" }) }],
+  prompt: "Say hi.",
+  // Manual hint on the system part is the only marker we want here — skip the
+  // auto-policy's latest-user-message breakpoint so the cassette body matches.
+  cache: "none",
+  generation: { maxTokens: 16, temperature: 0 },
+})
+
+const recorded = recordedTests({
+  prefix: "bedrock-converse-cache",
+  provider: "amazon-bedrock",
+  protocol: "bedrock-converse",
+  requires: ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"],
+  // Two identical requests in one cassette — replay walks the cassette in
+  // recording order so the second call replays the cached-hit interaction.
+})
+
+describe("Bedrock Converse cache recorded", () => {
+  recorded.effect.with("writes then reads cachePoint on identical second call", { tags: ["cache"] }, () =>
+    Effect.gen(function* () {
+      const first = yield* LLMClient.generate(cacheRequest)
+      expect(first.usage?.cacheReadInputTokens ?? 0).toBeGreaterThanOrEqual(0)
+
+      const second = yield* LLMClient.generate(cacheRequest)
+      expect(second.usage?.cacheReadInputTokens ?? 0).toBeGreaterThan(0)
+    }),
+  )
+})

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

@@ -0,0 +1,740 @@
+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, Message, ToolCallPart, ToolChoice } from "../../src"
+import { LLMClient } from "../../src/route"
+import { AmazonBedrock } from "../../src/providers"
+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 = AmazonBedrock.configure({
+  baseURL: "https://bedrock-runtime.test",
+  apiKey: "test-bearer",
+}).model("anthropic.claude-3-5-sonnet-20240620-v1:0")
+
+const baseRequest = LLM.request({
+  id: "req_1",
+  model,
+  system: "You are concise.",
+  prompt: "Say hello.",
+  // Wire-shape assertions in this file predate the `cache: "auto"` default;
+  // pin the policy off so they only exercise the lowering path itself.
+  cache: "none",
+  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("passes topK through additionalModelRequestFields as top_k", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<BedrockConverse.BedrockConverseBody>(
+        LLM.updateRequest(baseRequest, { generation: { maxTokens: 64, temperature: 0, topK: 40 } }),
+      )
+
+      // Converse's inferenceConfig has no topK; Anthropic/Nova read it from
+      // additionalModelRequestFields as top_k.
+      expect(prepared.body.inferenceConfig).toEqual({ maxTokens: 64, temperature: 0 })
+      expect(prepared.body.additionalModelRequestFields).toEqual({ top_k: 40 })
+    }),
+  )
+
+  it.effect("omits additionalModelRequestFields when topK is unset", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<BedrockConverse.BedrockConverseBody>(baseRequest)
+      expect(prepared.body.additionalModelRequestFields).toBeUndefined()
+    }),
+  )
+
+  it.effect("lowers chronological system updates to wrapped user text in order", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<BedrockConverse.BedrockConverseBody>(
+        LLM.request({
+          model,
+          messages: [Message.user("Before."), Message.system("Update."), Message.assistant("After.")],
+          cache: "none",
+        }),
+      )
+
+      expect(prepared.body.messages).toEqual([
+        { role: "user", content: [{ text: "Before." }, { text: "<system-update>\nUpdate.\n</system-update>" }] },
+        { role: "assistant", content: [{ text: "After." }] },
+      ])
+    }),
+  )
+
+  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: ToolChoice.make({ 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: [
+            Message.user("What is the weather?"),
+            Message.assistant([ToolCallPart.make({ id: "tool_1", name: "lookup", input: { query: "weather" } })]),
+            Message.tool({ id: "tool_1", name: "lookup", result: { forecast: "sunny" } }),
+          ],
+          cache: "none",
+        }),
+      )
+
+      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("lowers image content in tool-result messages", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_tool_image",
+          model,
+          messages: [
+            Message.user("Capture the screen."),
+            Message.assistant([ToolCallPart.make({ id: "tool_1", name: "screenshot", input: {} })]),
+            Message.tool({
+              id: "tool_1",
+              name: "screenshot",
+              result: {
+                type: "content",
+                value: [
+                  { type: "text", text: "Screenshot captured." },
+                  { type: "file", uri: "data:image/png;base64,AAAA", mime: "image/png" },
+                ],
+              },
+            }),
+          ],
+          cache: "none",
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        messages: [
+          { role: "user", content: [{ text: "Capture the screen." }] },
+          {
+            role: "assistant",
+            content: [{ toolUse: { toolUseId: "tool_1", name: "screenshot", input: {} } }],
+          },
+          {
+            role: "user",
+            content: [
+              {
+                toolResult: {
+                  toolUseId: "tool_1",
+                  content: [{ text: "Screenshot captured." }, { image: { format: "png", source: { bytes: "AAAA" } } }],
+                  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 === "finish")
+      // Bedrock splits the finish across `messageStop` (carries reason) and
+      // `metadata` (carries usage). We consolidate them into a single
+      // terminal `finish` event with both.
+      expect(finishes).toHaveLength(1)
+      expect(finishes[0]).toMatchObject({ type: "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: "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("preserves streamed reasoning signatures for continuation lowering", () =>
+    Effect.gen(function* () {
+      const body = eventStreamBody(
+        ["messageStart", { role: "assistant" }],
+        ["contentBlockDelta", { contentBlockIndex: 0, delta: { reasoningContent: { text: "Let me think." } } }],
+        ["contentBlockDelta", { contentBlockIndex: 0, delta: { reasoningContent: { signature: "sig_1" } } }],
+        ["contentBlockStop", { contentBlockIndex: 0 }],
+        ["messageStop", { stopReason: "end_turn" }],
+      )
+      const response = yield* LLMClient.generate(baseRequest).pipe(Effect.provide(fixedBytes(body)))
+      const reasoning = response.events.find((event) => event.type === "reasoning-end")
+
+      expect(reasoning).toEqual({
+        type: "reasoning-end",
+        id: "reasoning-0",
+        providerMetadata: { bedrock: { signature: "sig_1" } },
+      })
+
+      const prepared = yield* LLMClient.prepare<BedrockConverse.BedrockConverseBody>(
+        LLM.request({
+          model,
+          messages: [
+            Message.assistant([
+              { type: "reasoning", text: "Let me think.", providerMetadata: reasoning?.providerMetadata },
+            ]),
+          ],
+          cache: "none",
+        }),
+      )
+      expect(prepared.body.messages).toEqual([
+        {
+          role: "assistant",
+          content: [{ reasoningContent: { reasoningText: { text: "Let me think.", signature: "sig_1" } } }],
+        },
+      ])
+    }),
+  )
+
+  it.effect("classifies throttlingException as a rate limit", () =>
+    Effect.gen(function* () {
+      const body = eventStreamBody(
+        ["messageStart", { role: "assistant" }],
+        ["throttlingException", { message: "Slow down" }],
+      )
+      const error = yield* LLMClient.generate(baseRequest).pipe(Effect.provide(fixedBytes(body)), Effect.flip)
+
+      expect(error.reason).toMatchObject({ _tag: "RateLimit", message: "Slow down" })
+    }),
+  )
+
+  it.effect("classifies input-too-long validation exceptions", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.generate(baseRequest).pipe(
+        Effect.provide(
+          fixedBytes(eventStreamBody(["validationException", { message: "Input is too long for requested model" }])),
+        ),
+        Effect.flip,
+      )
+
+      expect(error.reason).toMatchObject({
+        _tag: "InvalidRequest",
+        message: "Input is too long for requested model",
+        classification: "context-overflow",
+      })
+    }),
+  )
+
+  it.effect("rejects requests with no auth path", () =>
+    Effect.gen(function* () {
+      const unsignedModel = AmazonBedrock.configure({
+        baseURL: "https://bedrock-runtime.test",
+      }).model("anthropic.claude-3-5-sonnet-20240620-v1:0")
+      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 route bearer auth or AWS credentials")
+    }),
+  )
+
+  it.effect("signs requests with SigV4 when AWS credentials are provided (deterministic plumbing check)", () =>
+    Effect.gen(function* () {
+      const signed = AmazonBedrock.configure({
+        baseURL: "https://bedrock-runtime.test",
+        credentials: {
+          region: "us-east-1",
+          accessKeyId: "AKIAIOSFODNN7EXAMPLE",
+          secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
+        },
+      }).model("anthropic.claude-3-5-sonnet-20240620-v1:0")
+      const prepared = yield* LLMClient.prepare(LLM.updateRequest(baseRequest, { model: signed }))
+
+      expect(prepared.route).toBe("bedrock-converse")
+      expect(prepared.model).toBe(signed)
+    }),
+  )
+
+  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: [
+            Message.user([{ type: "text", text: "User prefix.", cache }]),
+            Message.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: [
+            Message.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" },
+            ]),
+          ],
+          cache: "none",
+        }),
+      )
+
+      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: [Message.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: [
+            Message.user([
+              { type: "media", mediaType: "application/pdf", data: "UERGREFUQQ==", filename: "report.pdf" },
+              { type: "media", mediaType: "text/csv", data: "Q1NWREFUQQ==" },
+            ]),
+          ],
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        messages: [
+          {
+            role: "user",
+            content: [
+              // Filename round-trips when supplied.
+              { document: { format: "pdf", name: "report.pdf", source: { bytes: "UERGREFUQQ==" } } },
+              // Falls back to a stable placeholder when filename is missing.
+              { document: { format: "csv", name: "document.csv", source: { bytes: "Q1NWREFUQQ==" } } },
+            ],
+          },
+        ],
+      })
+    }),
+  )
+
+  it.effect("rejects unsupported image media types", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.prepare(
+        LLM.request({
+          id: "req_bad_image",
+          model,
+          messages: [Message.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: [Message.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")
+    }),
+  )
+
+  it.effect("maps ttlSeconds >= 3600 to cachePoint ttl: '1h'", () =>
+    Effect.gen(function* () {
+      const cache = new CacheHint({ type: "ephemeral", ttlSeconds: 3600 })
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model,
+          system: [{ type: "text", text: "system", cache }],
+          prompt: "hi",
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        system: [{ text: "system" }, { cachePoint: { type: "default", ttl: "1h" } }],
+      })
+    }),
+  )
+
+  it.effect("appends cachePoint after marked tool definitions and tool-result blocks", () =>
+    Effect.gen(function* () {
+      const cache = new CacheHint({ type: "ephemeral" })
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model,
+          tools: [{ name: "lookup", description: "lookup", inputSchema: { type: "object", properties: {} }, cache }],
+          messages: [
+            Message.user("What's the weather?"),
+            Message.assistant([ToolCallPart.make({ id: "call_1", name: "lookup", input: {} })]),
+            Message.tool({ id: "call_1", name: "lookup", result: { temp: 72 }, cache }),
+          ],
+          cache: "none",
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        toolConfig: {
+          tools: [{ toolSpec: { name: "lookup" } }, { cachePoint: { type: "default" } }],
+        },
+        messages: [
+          { role: "user", content: [{ text: "What's the weather?" }] },
+          { role: "assistant", content: [{ toolUse: { toolUseId: "call_1" } }] },
+          {
+            role: "user",
+            content: [{ toolResult: { toolUseId: "call_1" } }, { cachePoint: { type: "default" } }],
+          },
+        ],
+      })
+    }),
+  )
+
+  it.effect("drops cachePoint markers past the 4-per-request cap", () =>
+    Effect.gen(function* () {
+      const cache = new CacheHint({ type: "ephemeral" })
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model,
+          system: [
+            { type: "text", text: "a", cache },
+            { type: "text", text: "b", cache },
+            { type: "text", text: "c", cache },
+            { type: "text", text: "d", cache },
+            { type: "text", text: "e", cache },
+            { type: "text", text: "f", cache },
+          ],
+          prompt: "hi",
+        }),
+      )
+
+      const system = (prepared.body as { system: Array<{ cachePoint?: unknown }> }).system
+      expect(system.filter((part) => "cachePoint" in part)).toHaveLength(4)
+    }),
+  )
+})
+
+// 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 = () =>
+  AmazonBedrock.configure({
+    // 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.
+    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,
+    },
+  }).model(process.env.BEDROCK_MODEL_ID ?? "us.amazon.nova-micro-v1:0")
+
+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.",
+          cache: "none",
+          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: ToolChoice.make(weatherTool),
+          cache: "none",
+          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* () {
+      expectWeatherToolLoop(
+        yield* runWeatherToolLoop(
+          weatherToolLoopRequest({
+            id: "recorded_bedrock_tool_loop",
+            model: recordedModel(),
+          }),
+        ),
+      )
+    }),
+  )
+})

packages/ai/test/provider/cloudflare.test.ts

@@ -0,0 +1,230 @@
+import { describe, expect } from "bun:test"
+import { ConfigProvider, Effect, Schema } from "effect"
+import { HttpClientRequest } from "effect/unstable/http"
+import { LLM } from "../../src"
+import { CloudflareAIGateway, CloudflareWorkersAI } 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 = CloudflareAIGateway.configure({
+        accountId: "test-account",
+        gatewayId: "test-gateway",
+        apiKey: "test-token",
+      }).model("workers-ai/@cf/meta/llama-3.3-70b-instruct")
+
+      expect(model).toMatchObject({
+        id: "workers-ai/@cf/meta/llama-3.3-70b-instruct",
+        provider: "cloudflare-ai-gateway",
+        route: { id: "cloudflare-ai-gateway" },
+      })
+      expect(model.route.endpoint.baseURL).toBe("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: CloudflareAIGateway.configure({
+            accountId: "test-account",
+            gatewayId: "test-gateway",
+            apiKey: "test-token",
+          }).model("openai/gpt-4o-mini"),
+          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(
+        CloudflareAIGateway.configure({
+          accountId: "test-account",
+          gatewayId: "",
+          gatewayApiKey: "test-token",
+        }).model("workers-ai/@cf/meta/llama-3.3-70b-instruct").route.endpoint.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: CloudflareAIGateway.configure({
+            accountId: "test-account",
+            gatewayApiKey: "gateway-token",
+            apiKey: "provider-token",
+          }).model("openai/gpt-4o-mini"),
+          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: CloudflareAIGateway.configure({
+            baseURL: "https://gateway.proxy.test/v1/custom/compat",
+            apiKey: "test-token",
+          }).model("openai/gpt-4o-mini"),
+          prompt: "Say hello.",
+        }),
+      )
+
+      expect(prepared.model.route.endpoint.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 = CloudflareWorkersAI.configure({
+        accountId: "test-account",
+        apiKey: "test-token",
+      }).model("@cf/meta/llama-3.1-8b-instruct")
+
+      expect(model).toMatchObject({
+        id: "@cf/meta/llama-3.1-8b-instruct",
+        provider: "cloudflare-workers-ai",
+        route: { id: "cloudflare-workers-ai" },
+      })
+      expect(model.route.endpoint.baseURL).toBe("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: CloudflareWorkersAI.configure({
+            accountId: "test-account",
+            apiKey: "test-token",
+          }).model("@cf/meta/llama-3.1-8b-instruct"),
+          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: CloudflareWorkersAI.configure({
+            accountId: "test-account",
+          }).model("@cf/meta/llama-3.1-8b-instruct"),
+          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/ai/test/provider/gemini-cache.recorded.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { LLM } from "../../src"
+import { LLMClient } from "../../src/route"
+import * as Google from "../../src/providers/google"
+import { LARGE_CACHEABLE_SYSTEM } from "../recorded-scenarios"
+import { recordedTests } from "../recorded-test"
+
+const model = Google.configure({
+  apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY ?? process.env.GEMINI_API_KEY ?? "fixture",
+}).model("gemini-2.5-flash")
+
+// Gemini does implicit prefix caching on 2.5+ models above ~1024 tokens. The
+// `CacheHint` is currently a no-op for Gemini (the explicit `CachedContent`
+// API is out-of-band and intentionally not wired up). This test exists to
+// pin the usage-parsing path: `cachedContentTokenCount` should surface as
+// `cacheReadInputTokens` on the second identical call.
+const cacheRequest = LLM.request({
+  id: "recorded_gemini_cache",
+  model,
+  system: LARGE_CACHEABLE_SYSTEM,
+  prompt: "Say hi.",
+  generation: { maxTokens: 16, temperature: 0 },
+})
+
+const recorded = recordedTests({
+  prefix: "gemini-cache",
+  provider: "google",
+  protocol: "gemini",
+  requires: ["GOOGLE_GENERATIVE_AI_API_KEY"],
+  // Two identical requests in one cassette — replay walks the cassette in
+  // recording order so the second call replays the cached-hit interaction.
+})
+
+describe("Gemini cache recorded", () => {
+  recorded.effect.with("reports cachedContentTokenCount on identical second call", { tags: ["cache"] }, () =>
+    Effect.gen(function* () {
+      const first = yield* LLMClient.generate(cacheRequest)
+      expect(first.usage?.cacheReadInputTokens ?? 0).toBeGreaterThanOrEqual(0)
+
+      const second = yield* LLMClient.generate(cacheRequest)
+      // Implicit caching is best-effort on Gemini's side; we assert the field
+      // is at least populated and non-negative. When re-recording, verify the
+      // cassette shows > 0 in the second response's usage.
+      expect(second.usage?.cacheReadInputTokens ?? 0).toBeGreaterThanOrEqual(0)
+    }),
+  )
+})

packages/ai/test/provider/gemini.test.ts

@@ -0,0 +1,584 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { LLM, LLMError, Message, ToolCallPart, Usage } from "../../src"
+import { Auth, LLMClient } from "../../src/route"
+import * as Gemini from "../../src/protocols/gemini"
+import { ProviderShared } from "../../src/protocols/shared"
+import { it } from "../lib/effect"
+import { fixedResponse } from "../lib/http"
+import { sseEvents, sseRaw } from "../lib/sse"
+
+const model = Gemini.route
+  .with({
+    endpoint: { baseURL: "https://generativelanguage.test/v1beta/" },
+    auth: Auth.header("x-goog-api-key", "test"),
+  })
+  .model({ id: "gemini-2.5-flash" })
+
+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("lowers chronological system updates to wrapped user text in order", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<Gemini.GeminiBody>(
+        LLM.request({
+          model,
+          messages: [Message.user("Before."), Message.system("Update."), Message.assistant("After.")],
+        }),
+      )
+
+      expect(prepared.body.contents).toEqual([
+        { role: "user", parts: [{ text: "Before." }, { text: "<system-update>\nUpdate.\n</system-update>" }] },
+        { role: "model", parts: [{ text: "After." }] },
+      ])
+    }),
+  )
+
+  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: [
+            Message.user([
+              { type: "text", text: "What is in this image?" },
+              { type: "media", mediaType: "image/png", data: "AAECAw==" },
+            ]),
+            Message.assistant([ToolCallPart.make({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
+            Message.tool({ 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("continues image tool results as inline vision input without base64 text", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<Gemini.GeminiBody>(
+        LLM.request({
+          model,
+          messages: [
+            Message.assistant([ToolCallPart.make({ id: "call_image", name: "read", input: { path: "pixel.png" } })]),
+            Message.tool({
+              id: "call_image",
+              name: "read",
+              result: {
+                type: "content",
+                value: [
+                  { type: "text", text: "Image read successfully" },
+                  { type: "file", uri: "data:image/png;base64,AAECAw==", mime: "image/png", name: "pixel.png" },
+                ],
+              },
+            }),
+          ],
+        }),
+      )
+
+      expect(prepared.body.contents).toEqual([
+        { role: "model", parts: [{ functionCall: { name: "read", args: { path: "pixel.png" } } }] },
+        {
+          role: "user",
+          parts: [
+            {
+              functionResponse: {
+                name: "read",
+                response: { name: "read", content: "Image read successfully" },
+              },
+            },
+            { inlineData: { mimeType: "image/png", data: "AAECAw==" } },
+          ],
+        },
+      ])
+      expect(JSON.stringify(prepared.body.contents)).not.toContain('"content":"AAECAw=="')
+    }),
+  )
+
+  it.effect("strips matching data URLs to raw base64 inlineData", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<Gemini.GeminiBody>(
+        LLM.request({
+          model,
+          messages: [
+            Message.user({ type: "media", mediaType: "image/png", data: "data:image/png;base64,AAEC" }),
+            Message.tool({
+              id: "call_image",
+              name: "read",
+              result: {
+                type: "content",
+                value: [{ type: "file", uri: "data:image/jpeg;base64,/9j/", mime: "image/jpeg" }],
+              },
+            }),
+          ],
+        }),
+      )
+      expect(prepared.body.contents).toEqual([
+        { role: "user", parts: [{ inlineData: { mimeType: "image/png", data: "AAEC" } }] },
+        {
+          role: "user",
+          parts: [
+            { functionResponse: { name: "read", response: { name: "read", content: "" } } },
+            { inlineData: { mimeType: "image/jpeg", data: "/9j/" } },
+          ],
+        },
+      ])
+    }),
+  )
+
+  for (const [name, media] of [
+    ["mismatched data URL MIME", { mediaType: "image/png", data: "data:image/jpeg;base64,/9j/" }],
+    ["malformed base64", { mediaType: "image/png", data: "%%%=" }],
+    ["unsupported SVG", { mediaType: "image/svg+xml", data: "PHN2Zz4=" }],
+  ] as const)
+    it.effect(`rejects ${name}`, () =>
+      Effect.gen(function* () {
+        const error = yield* LLMClient.prepare(
+          LLM.request({ model, messages: [Message.user({ type: "media", ...media })] }),
+        ).pipe(Effect.flip)
+        expect(error.message).toMatch(/does not support|does not match|valid base64/)
+      }),
+    )
+
+  it.effect("rejects oversized image input", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.prepare(
+        LLM.request({
+          model,
+          messages: [
+            Message.user({
+              type: "media",
+              mediaType: "image/png",
+              data: "A".repeat(ProviderShared.MAX_MEDIA_ENCODED_BYTES + 4),
+            }),
+          ],
+        }),
+      ).pipe(Effect.flip)
+      expect(error.message).toContain("encoded limit")
+    }),
+  )
+
+  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: 3,
+        nonCachedInputTokens: 4,
+        cacheReadInputTokens: 1,
+        reasoningTokens: 1,
+        totalTokens: 7,
+      })
+      const usage = new Usage({
+        inputTokens: 5,
+        outputTokens: 3,
+        nonCachedInputTokens: 4,
+        cacheReadInputTokens: 1,
+        reasoningTokens: 1,
+        totalTokens: 7,
+        providerMetadata: {
+          google: {
+            promptTokenCount: 5,
+            candidatesTokenCount: 2,
+            totalTokenCount: 7,
+            thoughtsTokenCount: 1,
+            cachedContentTokenCount: 1,
+          },
+        },
+      })
+      expect(response.events).toEqual([
+        { type: "step-start", index: 0 },
+        { type: "reasoning-start", id: "reasoning-0" },
+        { type: "reasoning-delta", id: "reasoning-0", text: "thinking" },
+        { type: "reasoning-end", id: "reasoning-0" },
+        { type: "text-start", id: "text-0" },
+        { type: "text-delta", id: "text-0", text: "Hello" },
+        { type: "text-delta", id: "text-0", text: "!" },
+        { type: "text-end", id: "text-0" },
+        { type: "step-finish", index: 0, reason: "stop", usage, providerMetadata: undefined },
+        {
+          type: "finish",
+          reason: "stop",
+          usage,
+        },
+      ])
+    }),
+  )
+
+  it.effect("preserves thoughtSignature for reasoning and tool-call continuation", () =>
+    Effect.gen(function* () {
+      const body = sseEvents({
+        candidates: [
+          {
+            content: {
+              role: "model",
+              parts: [
+                { text: "thinking", thought: true },
+                { text: "", thought: true, thoughtSignature: "thought_sig" },
+                { functionCall: { name: "lookup", args: { query: "weather" } }, thoughtSignature: "tool_sig" },
+              ],
+            },
+            finishReason: "STOP",
+          },
+        ],
+      })
+      const response = yield* LLMClient.generate(
+        LLM.updateRequest(request, {
+          tools: [{ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } }],
+        }),
+      ).pipe(Effect.provide(fixedResponse(body)))
+      const reasoning = response.events.find((event) => event.type === "reasoning-start")
+      const reasoningEnd = response.events.find((event) => event.type === "reasoning-end")
+      const toolCall = response.events.find((event) => event.type === "tool-call")
+
+      expect(reasoning).toEqual({
+        type: "reasoning-start",
+        id: "reasoning-0",
+        providerMetadata: undefined,
+      })
+      expect(reasoningEnd).toEqual({
+        type: "reasoning-end",
+        id: "reasoning-0",
+        providerMetadata: { google: { thoughtSignature: "thought_sig" } },
+      })
+      expect(toolCall).toMatchObject({ providerMetadata: { google: { thoughtSignature: "tool_sig" } } })
+      expect(response.events.findIndex((event) => event.type === "reasoning-end")).toBeLessThan(
+        response.events.findIndex((event) => event.type === "tool-call"),
+      )
+
+      const prepared = yield* LLMClient.prepare<Gemini.GeminiBody>(
+        LLM.request({
+          model,
+          messages: [
+            Message.assistant([
+              { type: "reasoning", text: "thinking", providerMetadata: reasoningEnd?.providerMetadata },
+              ToolCallPart.make({
+                id: "tool_0",
+                name: "lookup",
+                input: { query: "weather" },
+                providerMetadata: toolCall?.providerMetadata,
+              }),
+            ]),
+          ],
+        }),
+      )
+      expect(prepared.body.contents).toEqual([
+        {
+          role: "model",
+          parts: [
+            { text: "thinking", thought: true, thoughtSignature: "thought_sig" },
+            { functionCall: { name: "lookup", args: { query: "weather" } }, thoughtSignature: "tool_sig" },
+          ],
+        },
+      ])
+    }),
+  )
+
+  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)))
+      const usage = new Usage({
+        inputTokens: 5,
+        outputTokens: 1,
+        nonCachedInputTokens: 5,
+        cacheReadInputTokens: undefined,
+        reasoningTokens: undefined,
+        totalTokens: 6,
+        providerMetadata: { google: { promptTokenCount: 5, candidatesTokenCount: 1 } },
+      })
+
+      expect(response.toolCalls).toEqual([
+        {
+          type: "tool-call",
+          id: "tool_0",
+          name: "lookup",
+          input: { query: "weather" },
+          providerExecuted: undefined,
+          providerMetadata: undefined,
+        },
+      ])
+      expect(response.events).toEqual([
+        { type: "step-start", index: 0 },
+        {
+          type: "tool-call",
+          id: "tool_0",
+          name: "lookup",
+          input: { query: "weather" },
+          providerExecuted: undefined,
+          providerMetadata: undefined,
+        },
+        { type: "step-finish", index: 0, reason: "tool-calls", usage, providerMetadata: undefined },
+        {
+          type: "finish",
+          reason: "tool-calls",
+          usage,
+        },
+      ])
+    }),
+  )
+
+  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: "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.map((event) => event.type)).toEqual(["step-start", "step-finish", "finish"])
+      expect(length.events.at(-1)).toMatchObject({ type: "finish", reason: "length" })
+      expect(filtered.events.map((event) => event.type)).toEqual(["step-start", "step-finish", "finish"])
+      expect(filtered.events.at(-1)).toMatchObject({ type: "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: [Message.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/ai/test/provider/golden.recorded.test.ts

@@ -0,0 +1,214 @@
+import * as Anthropic from "../../src/providers/anthropic"
+import { CloudflareAIGateway, CloudflareWorkersAI } from "../../src/providers/cloudflare"
+import * as Google from "../../src/providers/google"
+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 openAI = OpenAI.configure({
+  apiKey: process.env.OPENAI_API_KEY ?? "fixture",
+})
+const openAIChat = openAI.chat("gpt-4o-mini")
+const openAIResponses = openAI.responses("gpt-5.5")
+const anthropic = Anthropic.configure({
+  apiKey: process.env.ANTHROPIC_API_KEY ?? "fixture",
+})
+const anthropicHaiku = anthropic.model("claude-haiku-4-5-20251001")
+const anthropicOpus = anthropic.model("claude-opus-4-7")
+const google = Google.configure({ apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY ?? "fixture" })
+const gemini = google.model("gemini-2.5-flash")
+const xai = XAI.configure({ apiKey: process.env.XAI_API_KEY ?? "fixture" })
+const xaiBasic = xai.model("grok-3-mini")
+const xaiFlagship = xai.model("grok-4.3")
+const cloudflareAIGateway = CloudflareAIGateway.configure({
+  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 cloudflareWorkers = CloudflareWorkersAI.configure({
+  accountId: process.env.CLOUDFLARE_ACCOUNT_ID ?? "fixture-account",
+  apiKey: process.env.CLOUDFLARE_API_KEY ?? "fixture",
+})
+const cloudflareAIGatewayWorkers = cloudflareAIGateway.model("workers-ai/@cf/meta/llama-3.1-8b-instruct")
+const cloudflareAIGatewayWorkersTools = cloudflareAIGateway.model("workers-ai/@cf/openai/gpt-oss-20b")
+const cloudflareWorkersAI = cloudflareWorkers.model("@cf/meta/llama-3.1-8b-instruct")
+const cloudflareWorkersAITools = cloudflareWorkers.model("@cf/openai/gpt-oss-20b")
+const deepseek = OpenAICompatible.deepseek
+  .configure({ apiKey: process.env.DEEPSEEK_API_KEY ?? "fixture" })
+  .model("deepseek-chat")
+const together = OpenAICompatible.togetherai
+  .configure({
+    apiKey: process.env.TOGETHER_AI_API_KEY ?? "fixture",
+  })
+  .model("meta-llama/Llama-3.3-70B-Instruct-Turbo")
+const groq = OpenAICompatible.groq
+  .configure({ apiKey: process.env.GROQ_API_KEY ?? "fixture" })
+  .model("llama-3.3-70b-versatile")
+const openRouter = OpenRouter.configure({ apiKey: process.env.OPENROUTER_API_KEY ?? "fixture" })
+const openrouter = openRouter.model("openai/gpt-4o-mini")
+const openrouterGpt55 = openRouter.model("openai/gpt-5.5")
+const openrouterOpus = OpenRouter.configure({
+  apiKey: process.env.OPENROUTER_API_KEY ?? "fixture",
+}).model("anthropic/claude-opus-4.7")
+
+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", { id: "image-tool-result", maxTokens: 40 }],
+  },
+  {
+    name: "OpenAI Responses gpt-5.5",
+    prefix: "openai-responses",
+    model: openAIResponses,
+    requires: ["OPENAI_API_KEY"],
+    tags: ["flagship"],
+    scenarios: [
+      { id: "text", temperature: false },
+      { id: "reasoning", temperature: false },
+      { id: "reasoning-continuation", temperature: false },
+      { id: "tool-call", temperature: false },
+      { id: "tool-loop", temperature: false },
+      { id: "image-tool-result", temperature: false, maxTokens: 40 },
+    ],
+  },
+  {
+    name: "Anthropic Haiku 4.5",
+    prefix: "anthropic-messages",
+    model: anthropicHaiku,
+    requires: ["ANTHROPIC_API_KEY"],
+    options: { redact: { allowRequestHeaders: ["anthropic-version"] } },
+    scenarios: ["text", "tool-call"],
+  },
+  {
+    name: "Anthropic Opus 4.7",
+    prefix: "anthropic-messages",
+    model: anthropicOpus,
+    requires: ["ANTHROPIC_API_KEY"],
+    tags: ["flagship"],
+    options: { redact: { allowRequestHeaders: ["anthropic-version"] } },
+    scenarios: [
+      { id: "tool-loop", temperature: false },
+      { id: "image-tool-result", temperature: false, maxTokens: 40 },
+    ],
+  },
+  {
+    name: "Gemini 2.5 Flash",
+    prefix: "gemini",
+    model: gemini,
+    requires: ["GOOGLE_GENERATIVE_AI_API_KEY"],
+    scenarios: [
+      { id: "text", maxTokens: 80 },
+      "tool-call",
+      { id: "image", maxTokens: 160 },
+      { id: "image-tool-result", maxTokens: 40 },
+    ],
+  },
+  {
+    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/ai/test/provider/google-vertex.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { HttpClientRequest } from "effect/unstable/http"
+import { LLM } from "../../src"
+import { GoogleVertex, GoogleVertexAnthropic } from "../../src/providers"
+import { LLMClient } from "../../src/route"
+import { it } from "../lib/effect"
+import { dynamicResponse } from "../lib/http"
+import { sseEvents } from "../lib/sse"
+
+describe("Google Vertex providers", () => {
+  it.effect("sends Gemini requests to the global Vertex endpoint", () =>
+    Effect.gen(function* () {
+      const response = yield* LLMClient.generate(
+        LLM.request({
+          model: GoogleVertex.configure({
+            accessToken: "vertex-token",
+            location: "global",
+            project: "vertex-project",
+          }).model("gemini-3.5-flash"),
+          prompt: "Say hello.",
+        }),
+      ).pipe(
+        Effect.provide(
+          dynamicResponse((input) =>
+            Effect.gen(function* () {
+              const request = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+              expect(request.url).toBe(
+                "https://aiplatform.googleapis.com/v1beta1/projects/vertex-project/locations/global/publishers/google/models/gemini-3.5-flash:streamGenerateContent?alt=sse",
+              )
+              expect(request.headers.get("authorization")).toBe("Bearer vertex-token")
+              expect(yield* Effect.promise(() => request.json())).toMatchObject({
+                contents: [{ role: "user", parts: [{ text: "Say hello." }] }],
+              })
+              return input.respond(
+                sseEvents({
+                  candidates: [
+                    {
+                      content: { role: "model", parts: [{ text: "Hello." }] },
+                      finishReason: "STOP",
+                    },
+                  ],
+                }),
+                { headers: { "content-type": "text/event-stream" } },
+              )
+            }),
+          ),
+        ),
+      )
+
+      expect(response.text).toBe("Hello.")
+    }),
+  )
+
+  it.effect("projects Anthropic Messages onto the Vertex raw-predict API", () =>
+    Effect.gen(function* () {
+      const response = yield* LLMClient.generate(
+        LLM.request({
+          model: GoogleVertexAnthropic.configure({
+            accessToken: "vertex-token",
+            location: "eu",
+            project: "vertex-project",
+          }).model("claude-sonnet-4-6"),
+          prompt: "Say hello.",
+        }),
+      ).pipe(
+        Effect.provide(
+          dynamicResponse((input) =>
+            Effect.gen(function* () {
+              const request = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+              expect(request.url).toBe(
+                "https://aiplatform.eu.rep.googleapis.com/v1/projects/vertex-project/locations/eu/publishers/anthropic/models/claude-sonnet-4-6:streamRawPredict",
+              )
+              expect(request.headers.get("authorization")).toBe("Bearer vertex-token")
+              expect(request.headers.get("anthropic-version")).toBeNull()
+              const body = yield* Effect.promise(() => request.json())
+              expect(body).toMatchObject({
+                anthropic_version: "vertex-2023-10-16",
+                messages: [{ role: "user", content: [{ type: "text", text: "Say hello." }] }],
+                stream: true,
+              })
+              expect(body).not.toHaveProperty("model")
+              return input.respond(
+                sseEvents(
+                  { 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_stop", index: 0 },
+                  { type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 2 } },
+                  { type: "message_stop" },
+                ),
+                { headers: { "content-type": "text/event-stream" } },
+              )
+            }),
+          ),
+        ),
+      )
+
+      expect(response.text).toBe("Hello.")
+    }),
+  )
+
+  it.effect("protects the Vertex Anthropic API version from body overlays", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.prepare(
+        LLM.request({
+          model: GoogleVertexAnthropic.configure({
+            accessToken: "vertex-token",
+            http: { body: { anthropic_version: "wrong" } },
+            project: "vertex-project",
+          }).model("claude-sonnet-4-6"),
+          prompt: "Say hello.",
+        }),
+      ).pipe(Effect.flip)
+
+      expect(error.message).toContain("http.body cannot overlay protocol-owned field(s): anthropic_version")
+    }),
+  )
+
+  it.effect("routes tuned Gemini models through their deployed endpoint", () =>
+    Effect.gen(function* () {
+      const response = yield* LLMClient.generate(
+        LLM.request({
+          model: GoogleVertex.configure({
+            accessToken: "vertex-token",
+            location: "us-central1",
+            project: "vertex-project",
+          }).model("endpoints/1234567890"),
+          prompt: "Say hello.",
+        }),
+      ).pipe(
+        Effect.provide(
+          dynamicResponse((input) =>
+            Effect.gen(function* () {
+              const request = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+              expect(request.url).toBe(
+                "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/vertex-project/locations/us-central1/endpoints/1234567890:streamGenerateContent?alt=sse",
+              )
+              return input.respond(
+                sseEvents({
+                  candidates: [
+                    {
+                      content: { role: "model", parts: [{ text: "Hello." }] },
+                      finishReason: "STOP",
+                    },
+                  ],
+                }),
+                { headers: { "content-type": "text/event-stream" } },
+              )
+            }),
+          ),
+        ),
+      )
+
+      expect(response.text).toBe("Hello.")
+    }),
+  )
+
+  it.effect("rejects tuned Gemini models in express mode", () =>
+    Effect.sync(() => {
+      expect(() => GoogleVertex.configure({ apiKey: "fixture" }).model("endpoints/1234567890")).toThrow(
+        "Google Vertex tuned models do not support Express Mode API keys",
+      )
+    }),
+  )
+})

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

@@ -0,0 +1,693 @@
+import { describe, expect } from "bun:test"
+import { Effect, Schema, Stream } from "effect"
+import { HttpClientRequest } from "effect/unstable/http"
+import { LLM, LLMError, LLMEvent, Message, Model, ToolCallPart, Usage } 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 { ProviderShared } from "../../src/protocols/shared"
+import { Auth, 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.route
+  .with({ endpoint: { baseURL: "https://api.openai.test/v1/" }, auth: Auth.bearer("test") })
+  .model({ id: "gpt-4o-mini" })
+
+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("lowers chronological system updates to escaped user wrappers in order", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        LLM.request({
+          model,
+          messages: [
+            Message.user("Before."),
+            Message.system("Treat <admin> & data literally."),
+            Message.assistant("After."),
+          ],
+        }),
+      )
+
+      expect(prepared.body.messages).toEqual([
+        {
+          role: "user",
+          content: "Before.\n<system-update>\nTreat &lt;admin&gt; &amp; data literally.\n</system-update>",
+        },
+        { role: "assistant", content: "After." },
+      ])
+    }),
+  )
+
+  it.effect("replays canonical reasoning as OpenAI-compatible reasoning_content", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        LLM.request({
+          model,
+          messages: [
+            Message.assistant([
+              { type: "reasoning", text: "thinking" },
+              { type: "text", text: "Hello" },
+            ]),
+          ],
+        }),
+      )
+
+      expect(prepared.body.messages).toEqual([{ role: "assistant", content: "Hello", reasoning_content: "thinking" }])
+    }),
+  )
+
+  it.effect("maps OpenAI provider options to Chat options", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        LLM.request({
+          model: OpenAI.configure({ baseURL: "https://api.openai.test/v1/", apiKey: "test" }).chat("gpt-4o-mini"),
+          prompt: "think",
+          providerOptions: { openai: { reasoningEffort: "max" } },
+        }),
+      )
+
+      expect(prepared.body.store).toBe(false)
+      expect(prepared.body.reasoning_effort).toBe("max")
+    }),
+  )
+
+  it.effect("passes through custom OpenAI-compatible reasoning effort strings", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        LLM.request({
+          model,
+          prompt: "think",
+          providerOptions: { openai: { reasoningEffort: "experimental" } },
+        }),
+      )
+
+      expect(prepared.body.reasoning_effort).toBe("experimental")
+    }),
+  )
+
+  it.effect("adds native query params to the Chat Completions URL", () =>
+    LLMClient.generate(
+      LLM.updateRequest(request, {
+        model: Model.update(model, { route: model.route.with({ endpoint: { query: { "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.configure({
+          baseURL: "https://opencode-test.openai.azure.com/openai/v1/",
+          apiKey: "azure-key",
+          headers: { authorization: "Bearer stale" },
+        }).chat("gpt-4o-mini"),
+      }),
+    ).pipe(
+      Effect.provide(
+        dynamicResponse((input) =>
+          Effect.gen(function* () {
+            const web = yield* HttpClientRequest.toWeb(input.request).pipe(Effect.orDie)
+            expect(web.url).toBe("https://opencode-test.openai.azure.com/openai/v1/chat/completions?api-version=v1")
+            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: model.route
+          .with({ auth: Auth.bearer("fresh-key"), headers: { authorization: "Bearer stale" } })
+          .model({ id: model.id }),
+        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: [
+            Message.user("What is the weather?"),
+            Message.assistant([ToolCallPart.make({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
+            Message.tool({ 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("preserves structured tool errors for the model", () =>
+    Effect.gen(function* () {
+      const error = { error: { type: "unknown", message: "Tool execution interrupted" } }
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        LLM.request({
+          model,
+          messages: [
+            Message.assistant([ToolCallPart.make({ id: "call_1", name: "bash", input: {} })]),
+            Message.tool({ id: "call_1", name: "bash", resultType: "error", result: error }),
+          ],
+        }),
+      )
+
+      expect(prepared.body.messages.at(-1)).toEqual({
+        role: "tool",
+        tool_call_id: "call_1",
+        content: ProviderShared.encodeJson(error),
+      })
+    }),
+  )
+
+  it.effect("continues image tool results as vision input without base64 text", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        LLM.request({
+          model,
+          messages: [
+            Message.assistant([ToolCallPart.make({ id: "call_image", name: "read", input: { path: "pixel.png" } })]),
+            Message.tool({
+              id: "call_image",
+              name: "read",
+              result: {
+                type: "content",
+                value: [
+                  { type: "text", text: "Image read successfully" },
+                  { type: "file", uri: "data:image/png;base64,AAECAw==", mime: "image/png", name: "pixel.png" },
+                ],
+              },
+            }),
+          ],
+        }),
+      )
+
+      expect(prepared.body.messages).toEqual([
+        {
+          role: "assistant",
+          content: null,
+          tool_calls: [
+            {
+              id: "call_image",
+              type: "function",
+              function: { name: "read", arguments: encodeJson({ path: "pixel.png" }) },
+            },
+          ],
+        },
+        { role: "tool", tool_call_id: "call_image", content: "Image read successfully" },
+        {
+          role: "user",
+          content: [{ type: "image_url", image_url: { url: "data:image/png;base64,AAECAw==" } }],
+        },
+      ])
+      expect(JSON.stringify(prepared.body.messages)).not.toContain('"content":"AAECAw=="')
+    }),
+  )
+
+  it.effect("orders parallel tool responses before one aggregated vision message", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        LLM.request({
+          model,
+          messages: [
+            Message.assistant([
+              ToolCallPart.make({ id: "call_1", name: "read", input: {} }),
+              ToolCallPart.make({ id: "call_2", name: "read", input: {} }),
+            ]),
+            Message.make({
+              role: "tool",
+              content: [
+                {
+                  type: "tool-result",
+                  id: "call_1",
+                  name: "read",
+                  result: {
+                    type: "content",
+                    value: [{ type: "file", uri: "data:image/png;base64,AAEC", mime: "image/png" }],
+                  },
+                },
+                {
+                  type: "tool-result",
+                  id: "call_2",
+                  name: "read",
+                  result: {
+                    type: "content",
+                    value: [{ type: "file", uri: "data:image/jpeg;base64,/9j/", mime: "image/jpeg" }],
+                  },
+                },
+              ],
+            }),
+          ],
+        }),
+      )
+      expect(prepared.body.messages.slice(1)).toEqual([
+        { role: "tool", tool_call_id: "call_1", content: "" },
+        { role: "tool", tool_call_id: "call_2", content: "" },
+        {
+          role: "user",
+          content: [
+            { type: "image_url", image_url: { url: "data:image/png;base64,AAEC" } },
+            { type: "image_url", image_url: { url: "data:image/jpeg;base64,/9j/" } },
+          ],
+        },
+      ])
+    }),
+  )
+
+  it.effect("aggregates consecutive tool images with a following system update", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        LLM.request({
+          model,
+          messages: [
+            Message.tool({
+              id: "call_1",
+              name: "read",
+              result: {
+                type: "content",
+                value: [{ type: "file", uri: "data:image/png;base64,AAEC", mime: "image/png" }],
+              },
+            }),
+            Message.tool({
+              id: "call_2",
+              name: "read",
+              result: {
+                type: "content",
+                value: [{ type: "file", uri: "data:image/webp;base64,UklG", mime: "image/webp" }],
+              },
+            }),
+            Message.system("Inspect both images."),
+          ],
+        }),
+      )
+      expect(prepared.body.messages).toEqual([
+        { role: "tool", tool_call_id: "call_1", content: "" },
+        { role: "tool", tool_call_id: "call_2", content: "" },
+        {
+          role: "user",
+          content: [
+            { type: "image_url", image_url: { url: "data:image/png;base64,AAEC" } },
+            { type: "image_url", image_url: { url: "data:image/webp;base64,UklG" } },
+            { type: "text", text: "<system-update>\nInspect both images.\n</system-update>" },
+          ],
+        },
+      ])
+    }),
+  )
+
+  it.effect("appends system updates without replacing multipart user content", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        LLM.request({
+          model,
+          messages: [
+            Message.user({ type: "media", mediaType: "image/png", data: "AAEC" }),
+            Message.system("Keep the image."),
+          ],
+        }),
+      )
+      expect(prepared.body.messages).toEqual([
+        {
+          role: "user",
+          content: [
+            { type: "image_url", image_url: { url: "data:image/png;base64,AAEC" } },
+            { type: "text", text: "<system-update>\nKeep the image.\n</system-update>" },
+          ],
+        },
+      ])
+    }),
+  )
+
+  for (const [name, media] of [
+    ["mismatched data URL MIME", { mediaType: "image/png", data: "data:image/jpeg;base64,/9j/" }],
+    ["malformed base64", { mediaType: "image/png", data: "not-base64" }],
+    ["unsupported SVG", { mediaType: "image/svg+xml", data: "PHN2Zz4=" }],
+  ] as const)
+    it.effect(`rejects ${name}`, () =>
+      Effect.gen(function* () {
+        const error = yield* LLMClient.prepare(
+          LLM.request({ model, messages: [Message.user({ type: "media", ...media })] }),
+        ).pipe(Effect.flip)
+        expect(error.message).toMatch(/does not support|does not match|valid base64/)
+      }),
+    )
+
+  it.effect("rejects oversized image input", () =>
+    Effect.gen(function* () {
+      const error = yield* LLMClient.prepare(
+        LLM.request({
+          model,
+          messages: [
+            Message.user({
+              type: "media",
+              mediaType: "image/png",
+              data: "A".repeat(ProviderShared.MAX_MEDIA_ENCODED_BYTES + 4),
+            }),
+          ],
+        }),
+      ).pipe(Effect.flip)
+      expect(error.message).toContain("encoded limit")
+    }),
+  )
+
+  it.effect("prepares raw and data URL image media as vision input", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        LLM.request({
+          id: "req_media",
+          model,
+          messages: [
+            Message.user([
+              { type: "media", mediaType: "image/png", data: "AAECAw==" },
+              { type: "media", mediaType: "image/jpeg", data: "data:image/jpeg;base64,/9j/" },
+            ]),
+          ],
+        }),
+      )
+
+      expect(prepared.body.messages).toEqual([
+        {
+          role: "user",
+          content: [
+            { type: "image_url", image_url: { url: "data:image/png;base64,AAECAw==" } },
+            { type: "image_url", image_url: { url: "data:image/jpeg;base64,/9j/" } },
+          ],
+        },
+      ])
+    }),
+  )
+
+  it.effect("lowers reasoning-only assistant history", () =>
+    Effect.gen(function* () {
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        LLM.request({
+          id: "req_reasoning",
+          model,
+          messages: [Message.assistant({ type: "reasoning", text: "hidden" })],
+        }),
+      )
+
+      expect(prepared.body.messages).toEqual([{ role: "assistant", content: null, reasoning_content: "hidden" }])
+    }),
+  )
+
+  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)))
+      const usage = new Usage({
+        inputTokens: 5,
+        outputTokens: 2,
+        nonCachedInputTokens: 4,
+        cacheReadInputTokens: 1,
+        reasoningTokens: 0,
+        totalTokens: 7,
+        providerMetadata: {
+          openai: {
+            prompt_tokens: 5,
+            completion_tokens: 2,
+            total_tokens: 7,
+            prompt_tokens_details: { cached_tokens: 1 },
+            completion_tokens_details: { reasoning_tokens: 0 },
+          },
+        },
+      })
+
+      expect(response.text).toBe("Hello!")
+      expect(response.events).toEqual([
+        { type: "step-start", index: 0 },
+        { type: "text-start", id: "text-0" },
+        { type: "text-delta", id: "text-0", text: "Hello" },
+        { type: "text-delta", id: "text-0", text: "!" },
+        { type: "text-end", id: "text-0" },
+        { type: "step-finish", index: 0, reason: "stop", usage, providerMetadata: undefined },
+        {
+          type: "finish",
+          reason: "stop",
+          usage,
+        },
+      ])
+    }),
+  )
+
+  it.effect("parses OpenAI-compatible reasoning content deltas", () =>
+    Effect.gen(function* () {
+      const body = sseEvents(
+        { choices: [{ delta: { reasoning_content: "thinking" } }] },
+        { choices: [{ delta: { content: "Hello" } }] },
+        { choices: [{ delta: {}, finish_reason: "stop" }] },
+      )
+
+      const response = yield* LLMClient.generate(request).pipe(Effect.provide(fixedResponse(body)))
+
+      expect(response.reasoning).toBe("thinking")
+      expect(response.text).toBe("Hello")
+      expect(response.events).toMatchObject([
+        { type: "step-start", index: 0 },
+        { type: "reasoning-start", id: "reasoning-0" },
+        { type: "reasoning-delta", id: "reasoning-0", text: "thinking" },
+        { type: "reasoning-end", id: "reasoning-0" },
+        { type: "text-start", id: "text-0" },
+        { type: "text-delta", id: "text-0", text: "Hello" },
+        { type: "text-end", id: "text-0" },
+        { type: "step-finish", index: 0, reason: "stop" },
+        { type: "finish", reason: "stop" },
+      ])
+    }),
+  )
+
+  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: "step-start", index: 0 },
+        { type: "tool-input-start", id: "call_1", name: "lookup", providerMetadata: undefined },
+        { type: "tool-input-delta", id: "call_1", name: "lookup", text: '{"query"' },
+        { type: "tool-input-delta", id: "call_1", name: "lookup", text: ':"weather"}' },
+        { type: "tool-input-end", id: "call_1", name: "lookup", providerMetadata: undefined },
+        {
+          type: "tool-call",
+          id: "call_1",
+          name: "lookup",
+          input: { query: "weather" },
+          providerExecuted: undefined,
+          providerMetadata: undefined,
+        },
+        { type: "step-finish", index: 0, reason: "tool-calls", usage: undefined, providerMetadata: undefined },
+        { type: "finish", reason: "tool-calls", usage: undefined },
+      ])
+    }),
+  )
+
+  it.effect("fails a streamed tool call when the provider ends 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 input = LLM.updateRequest(request, {
+        tools: [{ name: "lookup", description: "Lookup data", inputSchema: { type: "object" } }],
+      })
+      const events: LLMEvent[] = []
+      const streamError = yield* LLMClient.stream(input).pipe(
+        Stream.runForEach((event) => Effect.sync(() => events.push(event))),
+        Effect.flip,
+        Effect.provide(fixedResponse(body)),
+      )
+      const error = yield* LLMClient.generate(input).pipe(Effect.provide(fixedResponse(body)), Effect.flip)
+
+      expect(events).toEqual([
+        { type: "step-start", index: 0 },
+        { type: "tool-input-start", id: "call_1", name: "lookup", providerMetadata: undefined },
+        { type: "tool-input-delta", id: "call_1", name: "lookup", text: '{"query"' },
+        { type: "tool-input-delta", id: "call_1", name: "lookup", text: ':"weather"}' },
+      ])
+      expect(events.filter(LLMEvent.is.toolCall)).toEqual([])
+      expect(streamError.reason).toMatchObject({ _tag: "InvalidProviderOutput" })
+      expect(streamError.message).toContain("Provider stream ended without a terminal finish event")
+      expect(error.message).toContain("Provider stream ended without a terminal finish event")
+    }),
+  )
+
+  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(["step-start"])
+    }),
+  )
+})

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

@@ -0,0 +1,238 @@
+import { describe, expect } from "bun:test"
+import { Effect, Schema } from "effect"
+import { HttpClientRequest } from "effect/unstable/http"
+import { LLM, Message, ToolCallPart } from "../../src"
+import { Auth, 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.route
+  .with({
+    provider: "deepseek",
+    endpoint: { baseURL: "https://api.deepseek.test/v1/", query: { "api-version": "2026-01-01" } },
+    auth: Auth.bearer("test-key"),
+  })
+  .model({ id: "deepseek-chat" })
+
+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: { id: "openai-compatible-chat" },
+      })
+      expect(prepared.model.route.endpoint).toMatchObject({
+        baseURL: "https://api.deepseek.test/v1/",
+        query: { "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.configure({ apiKey: "test-key" }).model(`${provider}-model`)
+          return {
+            id: String(model.id),
+            provider: String(model.provider),
+            route: model.route.id,
+            baseURL: model.route.endpoint.baseURL,
+          }
+        }),
+      ).toEqual(
+        providerFamilies.map(([provider, _, baseURL]) => ({
+          id: `${provider}-model`,
+          provider,
+          route: "openai-compatible-chat",
+          baseURL,
+        })),
+      )
+
+      const custom = OpenAICompatible.deepseek
+        .configure({
+          apiKey: "test-key",
+          baseURL: "https://custom.deepseek.test/v1",
+        })
+        .model("deepseek-chat")
+      expect(custom).toMatchObject({
+        provider: "deepseek",
+        route: { id: "openai-compatible-chat" },
+      })
+      expect(custom.route.endpoint.baseURL).toBe("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: [
+            Message.user("What is the weather?"),
+            Message.assistant([ToolCallPart.make({ id: "call_1", name: "lookup", input: { query: "weather" } })]),
+            Message.tool({ 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: "finish", reason: "stop" })
+    }),
+  )
+})

packages/ai/test/provider/openai-compatible-responses.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { LLM } from "../../src"
+import { configure } from "../../src/providers/openai-compatible-responses"
+import { OpenAICompatibleResponses } from "../../src/protocols/openai-compatible-responses"
+import { OpenAIResponses } from "../../src/protocols/openai-responses"
+import { LLMClient } from "../../src/route"
+import { it } from "../lib/effect"
+
+describe("OpenAI-compatible Responses route", () => {
+  it.effect("reuses the OpenAI Responses protocol for a configured deployment", () =>
+    Effect.gen(function* () {
+      expect(OpenAICompatibleResponses.route.body).toBe(OpenAIResponses.protocol.body)
+      expect(OpenAICompatibleResponses.route.transport).toBe(OpenAIResponses.httpTransport)
+
+      const model = configure({
+        apiKey: "test-key",
+        baseURL: "https://responses.example.test/v1",
+        provider: "example",
+      }).model("example-model")
+      const prepared = yield* LLMClient.prepare(
+        LLM.request({
+          model,
+          system: "You are concise.",
+          prompt: "Say hello.",
+        }),
+      )
+
+      expect(prepared.route).toBe("openai-compatible-responses")
+      expect(prepared.protocol).toBe("openai-responses")
+      expect(prepared.model).toMatchObject({
+        id: "example-model",
+        provider: "example",
+        route: {
+          id: "openai-compatible-responses",
+          endpoint: {
+            baseURL: "https://responses.example.test/v1",
+            path: "/responses",
+          },
+        },
+      })
+      expect(prepared.body).toEqual({
+        model: "example-model",
+        input: [
+          { role: "system", content: "You are concise." },
+          { role: "user", content: [{ type: "input_text", text: "Say hello." }] },
+        ],
+        store: false,
+        stream: true,
+      })
+    }),
+  )
+})

packages/ai/test/provider/openai-responses-cache.recorded.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect } from "bun:test"
+import { Effect } from "effect"
+import { LLM } from "../../src"
+import { LLMClient } from "../../src/route"
+import * as OpenAI from "../../src/providers/openai"
+import { LARGE_CACHEABLE_SYSTEM } from "../recorded-scenarios"
+import { recordedTests } from "../recorded-test"
+
+const model = OpenAI.configure({
+  apiKey: process.env.OPENAI_API_KEY ?? "fixture",
+}).responses("gpt-4.1-mini")
+
+// OpenAI caches prefixes automatically once they cross the 1024-token threshold;
+// `CacheHint` is a no-op for the wire body. The stable signal is the
+// `prompt_cache_key` routing hint, which keeps repeated calls on the same shard
+// so cache hits are observable.
+const cacheRequest = LLM.request({
+  id: "recorded_openai_responses_cache",
+  model,
+  system: LARGE_CACHEABLE_SYSTEM,
+  prompt: "Say hi.",
+  generation: { maxTokens: 16, temperature: 0 },
+  providerOptions: { openai: { promptCacheKey: "recorded-cache-test" } },
+})
+
+const recorded = recordedTests({
+  prefix: "openai-responses-cache",
+  provider: "openai",
+  protocol: "openai-responses",
+  requires: ["OPENAI_API_KEY"],
+  // Two identical requests in one cassette — replay walks the cassette in
+  // recording order so the second call replays the cached-hit interaction,
+  // not the cold-miss one.
+})
+
+describe("OpenAI Responses cache recorded", () => {
+  recorded.effect.with("reports cached_tokens on identical second call", { tags: ["cache"] }, () =>
+    Effect.gen(function* () {
+      const first = yield* LLMClient.generate(cacheRequest)
+      expect(first.usage?.cacheReadInputTokens ?? 0).toBeGreaterThanOrEqual(0)
+
+      const second = yield* LLMClient.generate(cacheRequest)
+      expect(second.usage?.cacheReadInputTokens ?? 0).toBeGreaterThan(0)
+    }),
+  )
+})

packages/ai/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.configure({ apiKey: "test-key" }).model("openai/gpt-4o-mini")
+
+      expect(model).toMatchObject({
+        id: "openai/gpt-4o-mini",
+        provider: "openrouter",
+        route: { id: "openrouter" },
+      })
+      expect(model.route.endpoint.baseURL).toBe("https://openrouter.ai/api/v1")
+
+      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.configure({
+            apiKey: "test-key",
+            providerOptions: {
+              openrouter: {
+                usage: true,
+                reasoning: { effort: "high" },
+                promptCacheKey: "session_123",
+              },
+            },
+          }).model("anthropic/claude-3.7-sonnet:thinking"),
+          prompt: "Think briefly.",
+        }),
+      )
+
+      expect(prepared.body).toMatchObject({
+        usage: { include: true },
+        reasoning: { effort: "high" },
+        prompt_cache_key: "session_123",
+      })
+    }),
+  )
+})

packages/ai/test/recorded-golden.ts

@@ -0,0 +1,97 @@
+import type { HttpRecorder } from "@opencode-ai/http-recorder"
+import { describe } from "bun:test"
+import { Effect } from "effect"
+import type { Model } from "../src"
+import { goldenScenarioTags, goldenScenarioTitle, 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
+    }
+
+type TargetInput = {
+  readonly name: string
+  readonly model: Model
+  readonly protocol?: string
+  readonly requires?: ReadonlyArray<string>
+  readonly transport?: Transport
+  readonly prefix?: string
+  readonly tags?: ReadonlyArray<string>
+  readonly metadata?: HttpRecorder.CassetteMetadata
+  readonly options?: HttpRecorder.RecorderOptions
+  readonly scenarios: ReadonlyArray<ScenarioInput>
+}
+
+const scenarioInput = (input: ScenarioInput) => (typeof input === "string" ? { id: input } : input)
+
+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.id}${transport}`
+}
+
+const metadata = (target: TargetInput) => ({
+  provider: target.model.provider,
+  ...(target.protocol ? { protocol: target.protocol } : {}),
+  route: target.model.route.id,
+  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 ?? goldenScenarioTitle(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/ai/test/recorded-runner.ts

@@ -0,0 +1,101 @@
+import type { HttpRecorder } from "@opencode-ai/http-recorder"
+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?: HttpRecorder.CassetteMetadata
+}
+
+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?: HttpRecorder.CassetteMetadata
+}
+
+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: HttpRecorder.CassetteMetadata
+    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/ai/test/recorded-scenarios.ts

@@ -0,0 +1,531 @@
+import { expect } from "bun:test"
+import { Effect, Schema } from "effect"
+import {
+  LLM,
+  LLMEvent,
+  LLMResponse,
+  Message,
+  ToolRuntime,
+  ToolChoice,
+  ToolDefinition,
+  toDefinitions,
+  type ContentPart,
+  type FinishReason,
+  type LLMRequest,
+  type Model,
+} from "../src"
+import { LLMClient } from "../src/route"
+import { Tool } from "../src/tool"
+
+export const weatherToolName = "get_weather"
+
+// A deterministic system prompt long enough to clear every supported provider's
+// minimum cacheable-prefix threshold (Anthropic Haiku 3.5: 2048 tokens; Anthropic
+// Opus/Haiku 4.5: 4096 tokens; OpenAI/Gemini/Bedrock: lower). Built by repeating
+// a fixed sentence — the cassette replays bit-for-bit, so the exact text matters
+// only when re-recording with `RECORD=true`.
+export const LARGE_CACHEABLE_SYSTEM = (() => {
+  const sentence = "You are a concise, factual assistant. Answer precisely and avoid filler. Cite numbers when known. "
+  // ~100 chars per sentence × 250 repeats ≈ 25,000 chars ≈ 5k+ tokens, safely
+  // above every provider's threshold.
+  return sentence.repeat(250)
+})()
+
+export const weatherTool = ToolDefinition.make({
+  name: weatherToolName,
+  description: "Get current weather for a city.",
+  inputSchema: {
+    type: "object",
+    properties: { city: { type: "string" } },
+    required: ["city"],
+    additionalProperties: false,
+  },
+})
+
+export const weatherRuntimeTool = Tool.make({
+  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 weatherToolLoopRequest = (input: {
+  readonly id: string
+  readonly model: Model
+  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?",
+    cache: "none",
+    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: Model
+  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.",
+  })
+
+const RESTROOM_IMAGE_TEXT = "jiggling restroom prison"
+const restroomImage = () =>
+  Effect.promise(() => Bun.file(new URL("./fixtures/media/restroom.png", import.meta.url)).bytes()).pipe(
+    Effect.map((bytes) => Buffer.from(bytes).toString("base64")),
+  )
+
+export const runWeatherToolLoop = (request: LLMRequest) =>
+  Effect.gen(function* () {
+    const tools = { [weatherToolName]: weatherRuntimeTool }
+    let next = LLM.updateRequest(request, { tools: toDefinitions(tools) })
+    const events: LLMEvent[] = []
+
+    for (let step = 0; step < 10; step++) {
+      const response = yield* LLMClient.generate(next)
+      events.push(...response.events.filter((event) => event.type !== "finish"))
+      const calls = response.events.filter(LLMEvent.is.toolCall).filter((call) => !call.providerExecuted)
+      if (calls.length === 0) {
+        const finish = response.events.find(LLMEvent.is.finish)
+        if (finish) events.push(finish)
+        return events
+      }
+
+      const dispatched = yield* Effect.forEach(calls, (call) =>
+        ToolRuntime.dispatch(tools, call).pipe(Effect.map((result) => [call, result] as const)),
+      )
+      events.push(...dispatched.flatMap(([, result]) => result.events))
+      next = LLM.updateRequest(next, {
+        messages: [
+          ...next.messages,
+          Message.assistant(assistantContent(response.events)),
+          ...dispatched.map(([call, result]) => Message.tool({ id: call.id, name: call.name, result: result.result })),
+        ],
+      })
+    }
+
+    throw new Error("Weather tool loop exceeded 10 steps")
+  })
+
+const assistantContent = (events: ReadonlyArray<LLMEvent>) => {
+  const content: ContentPart[] = []
+  for (const event of events) {
+    if (event.type === "text-delta" || event.type === "reasoning-delta") {
+      const type = event.type === "text-delta" ? "text" : "reasoning"
+      const last = content.at(-1)
+      if (last?.type === type) {
+        content[content.length - 1] = { ...last, text: `${last.text}${event.text}` }
+      } else {
+        content.push({ type, text: event.text })
+      }
+      continue
+    }
+    if (event.type === "text-end" || event.type === "reasoning-end") {
+      const type = event.type === "text-end" ? "text" : "reasoning"
+      const last = content.at(-1)
+      if (last?.type === type) content[content.length - 1] = { ...last, providerMetadata: event.providerMetadata }
+      continue
+    }
+    if (event.type === "tool-call") content.push(event)
+  }
+  return content
+}
+
+export const expectFinish = (
+  events: ReadonlyArray<LLMEvent>,
+  reason: Extract<LLMEvent, { readonly type: "finish" }>["reason"],
+) => expect(events.at(-1)).toMatchObject({ type: "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.finish)
+  expect(finishes).toHaveLength(1)
+  expect(finishes[0]?.reason).toBe("stop")
+
+  const stepFinishes = events.filter(LLMEvent.is.stepFinish)
+  expect(stepFinishes.map((event) => event.reason)).toEqual(["tool-calls", "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 interface GoldenScenarioContext {
+  readonly id: string
+  readonly model: Model
+  readonly maxTokens?: number
+  readonly temperature?: number | false
+}
+
+const generate = (request: LLMRequest) => LLMClient.generate(request)
+
+const generation = (context: GoldenScenarioContext, maxTokens: number) =>
+  context.temperature === false ? { maxTokens } : { maxTokens, temperature: context.temperature ?? 0 }
+
+const normalizeImageText = (value: string) =>
+  value
+    .toLowerCase()
+    .replace(/[^a-z\s]/g, "")
+    .replace(/\s+/g, " ")
+    .trim()
+
+const encryptedReasoningOptions = {
+  openai: {
+    store: false,
+    include: ["reasoning.encrypted_content"],
+    reasoningEffort: "low",
+    reasoningSummary: "auto",
+  },
+} as const
+
+type AssistantTextExpectation = string | RegExp
+
+type UserStep = { readonly type: "user"; readonly content: Message.ContentInput }
+type AssistantStep = {
+  readonly type: "assistant"
+  readonly text?: AssistantTextExpectation
+  readonly toolCall?: { readonly name: string; readonly input: unknown }
+  readonly reasoning?: "openai-encrypted"
+  readonly id?: string
+  readonly system?: string
+  readonly maxTokens?: number
+  readonly finish?: FinishReason
+  readonly tools?: LLM.RequestInput["tools"]
+  readonly toolChoice?: LLM.RequestInput["toolChoice"]
+  readonly providerOptions?: LLMRequest["providerOptions"]
+  readonly assert?: (response: LLMResponse) => void
+}
+type ConversationStep = UserStep | AssistantStep
+
+const user = (content: Message.ContentInput): ConversationStep => ({ type: "user", content })
+
+const assistant = {
+  expectText: (
+    text: AssistantTextExpectation,
+    options?: Omit<AssistantStep, "type" | "text" | "reasoning" | "toolCall">,
+  ): ConversationStep => ({ type: "assistant", text, ...options }),
+  expectToolCall: (
+    name: string,
+    input: unknown,
+    options?: Omit<AssistantStep, "type" | "text" | "reasoning" | "toolCall" | "finish">,
+  ): ConversationStep => ({ type: "assistant", toolCall: { name, input }, finish: "tool-calls", ...options }),
+  expectEncryptedReasoningText: (
+    text: AssistantTextExpectation,
+    options?: Omit<AssistantStep, "type" | "text" | "reasoning" | "toolCall" | "providerOptions">,
+  ): ConversationStep => ({
+    type: "assistant",
+    text,
+    reasoning: "openai-encrypted",
+    providerOptions: encryptedReasoningOptions,
+    ...options,
+  }),
+}
+
+const assertAssistantText = (actual: string, expected: AssistantTextExpectation) => {
+  if (typeof expected === "string") {
+    expect(actual.trim()).toBe(expected)
+    return
+  }
+  expect(actual.trim()).toMatch(expected)
+}
+
+const assertAssistantToolCall = (response: LLMResponse, expected: NonNullable<AssistantStep["toolCall"]>) => {
+  expect(response.toolCalls).toMatchObject([
+    { type: "tool-call", id: expect.any(String), name: expected.name, input: expected.input },
+  ])
+}
+
+// The generated golden scenarios only model one assistant shape at a time:
+// encrypted reasoning + text, text, or tool call. Keep mixed interleavings in
+// focused protocol tests where event order can be asserted directly.
+const assistantMessageFromResponse = (response: LLMResponse, step: AssistantStep) => {
+  const content: ContentPart[] = []
+  if (step.reasoning === "openai-encrypted") {
+    const reasoning = response.events.find(
+      (event): event is Extract<LLMEvent, { readonly type: "reasoning-end" }> =>
+        LLMEvent.is.reasoningEnd(event) && typeof event.providerMetadata?.openai?.itemId === "string",
+    )
+    if (!reasoning) throw new Error("OpenAI Responses did not return reasoning metadata")
+    expect(reasoning.providerMetadata?.openai?.reasoningEncryptedContent).toEqual(expect.any(String))
+    content.push({ type: "reasoning", text: response.reasoning, providerMetadata: reasoning.providerMetadata })
+  }
+
+  if (response.text.length > 0) content.push({ type: "text", text: response.text })
+  content.push(...response.toolCalls)
+  return Message.assistant(content)
+}
+
+const runGeneratedConversation = (context: GoldenScenarioContext, steps: ReadonlyArray<ConversationStep>) =>
+  Effect.gen(function* () {
+    const messages: Message[] = []
+    let generated = 0
+    for (const step of steps) {
+      if (step.type === "user") {
+        messages.push(Message.user(step.content))
+        continue
+      }
+
+      generated += 1
+      const response = yield* generate(
+        LLM.request({
+          id: step.id ? `${context.id}_${step.id}` : `${context.id}_${generated}`,
+          model: context.model,
+          system: step.system,
+          cache: "none",
+          messages,
+          tools: step.tools,
+          toolChoice: step.toolChoice,
+          providerOptions: step.providerOptions,
+          generation: generation(context, step.maxTokens ?? context.maxTokens ?? 80),
+        }),
+      )
+      if (step.text !== undefined) assertAssistantText(response.text, step.text)
+      if (step.toolCall) assertAssistantToolCall(response, step.toolCall)
+      step.assert?.(response)
+      expectFinish(response.events, step.finish ?? "stop")
+      messages.push(assistantMessageFromResponse(response, step))
+    }
+  })
+
+const runTextScenario = (context: GoldenScenarioContext) =>
+  runGeneratedConversation(context, [
+    user("Reply exactly with: Hello!"),
+    assistant.expectText(/^Hello!?$/, {
+      system: "You are concise.",
+      maxTokens: context.maxTokens ?? 40,
+      providerOptions:
+        context.model.route.id === "gemini" ? { gemini: { thinkingConfig: { thinkingBudget: 0 } } } : undefined,
+    }),
+  ])
+
+const runToolCallScenario = (context: GoldenScenarioContext) =>
+  runGeneratedConversation(context, [
+    user("Call get_weather with city exactly Paris."),
+    assistant.expectToolCall(
+      weatherToolName,
+      { city: "Paris" },
+      {
+        system: "Call tools exactly as requested.",
+        tools: [weatherTool],
+        toolChoice: ToolChoice.make(weatherTool),
+        maxTokens: context.maxTokens ?? 80,
+      },
+    ),
+  ])
+
+const runImageScenario = (context: GoldenScenarioContext) =>
+  Effect.gen(function* () {
+    yield* runGeneratedConversation(context, [
+      user([
+        {
+          type: "text",
+          text: "The image contains exactly three lowercase English words. Read them left to right and reply with only those words.",
+        },
+        { type: "media", mediaType: "image/png", data: yield* restroomImage() },
+      ]),
+      assistant.expectText(/.+/, {
+        system: "Read images carefully. Reply only with the visible text.",
+        maxTokens: context.maxTokens ?? 20,
+        assert: (response) => expect(normalizeImageText(response.text)).toBe(RESTROOM_IMAGE_TEXT),
+      }),
+    ])
+  })
+
+// Reproduces a tool-result image round trip: a tool returns image bytes, and
+// the next model turn must receive provider-native image content instead of a
+// JSON-stringified base64 blob.
+const screenshotToolName = "read_screenshot"
+const runImageToolResultScenario = (context: GoldenScenarioContext) =>
+  Effect.gen(function* () {
+    const image = yield* restroomImage()
+    const response = yield* generate(
+      LLM.request({
+        id: `${context.id}_image_tool_result`,
+        model: context.model,
+        system: "Read images carefully. Reply only with the visible text, lowercase, no punctuation.",
+        cache: "none",
+        generation: generation(context, context.maxTokens ?? 40),
+        messages: [
+          Message.user("Use the read_screenshot tool, then reply with the words shown."),
+          Message.assistant([{ type: "tool-call", id: "call_screenshot_1", name: screenshotToolName, input: {} }]),
+          Message.tool({
+            id: "call_screenshot_1",
+            name: screenshotToolName,
+            resultType: "content",
+            result: [
+              { type: "text", text: "Image read successfully" },
+              { type: "file", uri: `data:image/png;base64,${image}`, mime: "image/png" },
+            ],
+          }),
+        ],
+        tools: [
+          ToolDefinition.make({
+            name: screenshotToolName,
+            description: "Capture a screenshot of the current screen.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+          }),
+        ],
+      }),
+    )
+
+    expectFinish(response.events, "stop")
+    expect(normalizeImageText(response.text)).toBe(RESTROOM_IMAGE_TEXT)
+  })
+
+const runReasoningScenario = (context: GoldenScenarioContext) =>
+  runGeneratedConversation(context, [
+    user("Think briefly, then reply exactly with: Hello!"),
+    assistant.expectText(/^Hello!?$/, {
+      system: "Show concise reasoning when the provider supports visible reasoning summaries.",
+      providerOptions: { openai: { reasoningEffort: "low", reasoningSummary: "auto" } },
+      maxTokens: context.maxTokens ?? 120,
+      assert: (response) => expect(response.usage?.reasoningTokens ?? 0).toBeGreaterThan(0),
+    }),
+  ])
+
+const runReasoningContinuationScenario = (context: GoldenScenarioContext) =>
+  runGeneratedConversation(context, [
+    user("Think briefly, then reply exactly with: Hello!"),
+    assistant.expectEncryptedReasoningText(/^Hello!?$/, {
+      id: "first",
+      system: "Show concise reasoning when the provider supports visible reasoning summaries.",
+      maxTokens: context.maxTokens ?? 120,
+    }),
+    user("Now reply exactly with: Done."),
+    assistant.expectText(/^Done\.?$/, { id: "second", maxTokens: 40, providerOptions: encryptedReasoningOptions }),
+  ])
+
+const runToolLoopScenario = (context: GoldenScenarioContext) =>
+  Effect.gen(function* () {
+    expectGoldenWeatherToolLoop(
+      yield* runWeatherToolLoop(
+        goldenWeatherToolLoopRequest({
+          id: context.id,
+          model: context.model,
+          maxTokens: context.maxTokens ?? 80,
+          temperature: context.temperature,
+        }),
+      ),
+    )
+  })
+
+const goldenScenarios = {
+  text: { title: "streams text", tags: ["text", "golden"], run: runTextScenario },
+  "tool-call": { title: "streams tool call", tags: ["tool", "tool-call", "golden"], run: runToolCallScenario },
+  "tool-loop": { title: "drives a tool loop", tags: ["tool", "tool-loop", "golden"], run: runToolLoopScenario },
+  image: { title: "reads image text", tags: ["media", "image", "vision", "golden"], run: runImageScenario },
+  "image-tool-result": {
+    title: "reads image returned from tool result",
+    tags: ["media", "image", "vision", "tool", "tool-result", "golden"],
+    run: runImageToolResultScenario,
+  },
+  reasoning: { title: "uses reasoning", tags: ["reasoning", "golden"], run: runReasoningScenario },
+  "reasoning-continuation": {
+    title: "continues encrypted reasoning",
+    tags: ["reasoning", "continuation", "encrypted-reasoning", "golden"],
+    run: runReasoningContinuationScenario,
+  },
+} as const
+
+export type GoldenScenarioID = keyof typeof goldenScenarios
+export const goldenScenarioTitle = (id: GoldenScenarioID) => goldenScenarios[id].title
+export const goldenScenarioTags = (id: GoldenScenarioID) => [...goldenScenarios[id].tags]
+export const runGoldenScenario = (id: GoldenScenarioID, context: GoldenScenarioContext) =>
+  goldenScenarios[id].run(context)
+
+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 = `${typeof last.value === "string" ? 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 === "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/ai/test/recorded-test.ts

@@ -0,0 +1,86 @@
+import { HttpRecorder } from "@opencode-ai/http-recorder"
+import { Layer } from "effect"
+import * as path from "node:path"
+import { fileURLToPath } from "node:url"
+import { LLMClient, RequestExecutor, WebSocketExecutor } 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"
+
+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.RecorderOptions
+}
+
+type RecordedCaseOptions = RunnerCaseOptions & {
+  readonly options?: HttpRecorder.RecorderOptions
+}
+
+const mergeOptions = (
+  base: HttpRecorder.RecorderOptions | undefined,
+  override: HttpRecorder.RecorderOptions | undefined,
+) => {
+  if (!base) return override
+  if (!override) return base
+  return {
+    ...base,
+    ...override,
+    metadata: base.metadata || override.metadata ? { ...base.metadata, ...override.metadata } : undefined,
+    redact:
+      base.redact || override.redact
+        ? {
+            ...base.redact,
+            ...override.redact,
+            headers: [...(base.redact?.headers ?? []), ...(override.redact?.headers ?? [])],
+            allowRequestHeaders: [
+              ...(base.redact?.allowRequestHeaders ?? []),
+              ...(override.redact?.allowRequestHeaders ?? []),
+            ],
+            allowResponseHeaders: [
+              ...(base.redact?.allowResponseHeaders ?? []),
+              ...(override.redact?.allowResponseHeaders ?? []),
+            ],
+            queryParameters: [...(base.redact?.queryParameters ?? []), ...(override.redact?.queryParameters ?? [])],
+            jsonFields: [...(base.redact?.jsonFields ?? []), ...(override.redact?.jsonFields ?? [])],
+          }
+        : 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,
+      }
+      if (recording) {
+        if (process.env.CI !== undefined) throw new Error("Unset CI before recording HTTP cassettes")
+        HttpRecorder.removeCassetteSync(cassette, { directory: FIXTURES_DIR })
+      }
+      const requestExecutor = RequestExecutor.layer.pipe(
+        Layer.provide(
+          HttpRecorder.layerFetch(cassette, {
+            ...recorderOptions,
+            directory: FIXTURES_DIR,
+            metadata: recorderMetadata,
+          }),
+        ),
+      )
+      const deps = Layer.mergeAll(requestExecutor, WebSocketExecutor.layer)
+      return Layer.mergeAll(deps, LLMClient.layer.pipe(Layer.provide(deps)))
+    },
+  })

packages/ai/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/ai/test/response.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, test } from "bun:test"
+import { LLMEvent, LLMResponse } from "../src"
+
+const reduce = (events: ReadonlyArray<LLMEvent>) => events.reduce(LLMResponse.reduce, LLMResponse.empty())
+const finishEvents = (events: ReadonlyArray<LLMEvent>) => events.filter(LLMEvent.is.finish)
+
+describe("LLMResponse reducer", () => {
+  test("assembles interleaved reasoning and text with end metadata", () => {
+    const events = [
+      LLMEvent.reasoningStart({ id: "r1" }),
+      LLMEvent.reasoningDelta({ id: "r1", text: "I should " }),
+      LLMEvent.textStart({ id: "t1" }),
+      LLMEvent.reasoningDelta({ id: "r1", text: "compare..." }),
+      LLMEvent.reasoningEnd({ id: "r1", providerMetadata: { anthropic: { signature: "sig" } } }),
+      LLMEvent.textDelta({ id: "t1", text: "Answer" }),
+      LLMEvent.textEnd({ id: "t1" }),
+      LLMEvent.finish({ reason: "stop", usage: { outputTokens: 5 } }),
+    ]
+    const response = LLMResponse.fromEvents(events)
+
+    expect(response?.finishReason).toBe("stop")
+    expect(response?.usage).toMatchObject({ outputTokens: 5 })
+    expect(response?.events).toEqual(events)
+    expect(response?.events.map((event) => event.type)).toEqual([
+      "reasoning-start",
+      "reasoning-delta",
+      "text-start",
+      "reasoning-delta",
+      "reasoning-end",
+      "text-delta",
+      "text-end",
+      "finish",
+    ])
+    expect(finishEvents(response?.events ?? [])).toHaveLength(1)
+    expect(response?.message.content).toEqual([
+      {
+        type: "reasoning",
+        text: "I should compare...",
+        providerMetadata: { anthropic: { signature: "sig" } },
+      },
+      { type: "text", text: "Answer" },
+    ])
+  })
+
+  test("preserves partial content without completing a failed stream", () => {
+    const state = reduce([LLMEvent.textStart({ id: "t1" }), LLMEvent.textDelta({ id: "t1", text: "partial" })])
+
+    expect(LLMResponse.complete(state)).toBeUndefined()
+    expect(state.message.content).toEqual([{ type: "text", text: "partial" }])
+  })
+
+  test("does not complete ended content without a terminal finish", () => {
+    const state = reduce([
+      LLMEvent.textStart({ id: "t1" }),
+      LLMEvent.textDelta({ id: "t1", text: "partial" }),
+      LLMEvent.textEnd({ id: "t1" }),
+    ])
+
+    expect(LLMResponse.complete(state)).toBeUndefined()
+    expect(state.message.content).toEqual([{ type: "text", text: "partial" }])
+  })
+
+  test("uses terminal usage when present and keeps prior usage when finish omits it", () => {
+    const withFinishUsage = LLMResponse.fromEvents([
+      LLMEvent.stepFinish({ index: 0, reason: "stop", usage: { inputTokens: 3 } }),
+      LLMEvent.finish({ reason: "stop", usage: { outputTokens: 2 } }),
+    ])
+    const withoutFinishUsage = LLMResponse.fromEvents([
+      LLMEvent.stepFinish({ index: 0, reason: "stop", usage: { inputTokens: 3 } }),
+      LLMEvent.finish({ reason: "stop" }),
+    ])
+
+    expect(withFinishUsage?.usage).toMatchObject({ outputTokens: 2 })
+    expect(withoutFinishUsage?.usage).toMatchObject({ inputTokens: 3 })
+  })
+
+  test("assembles tool-call content only after the completed tool call event", () => {
+    const pending = reduce([
+      LLMEvent.toolInputStart({ id: "call_1", name: "lookup" }),
+      LLMEvent.toolInputDelta({ id: "call_1", name: "lookup", text: '{"query"' }),
+    ])
+
+    expect(pending.message.content).toEqual([])
+    expect(pending.toolInputs.call_1?.text).toBe('{"query"')
+
+    const response = LLMResponse.fromEvents([
+      ...pending.events,
+      LLMEvent.toolInputDelta({ id: "call_1", name: "lookup", text: ':"weather"}' }),
+      LLMEvent.toolInputEnd({ id: "call_1", name: "lookup" }),
+      LLMEvent.toolCall({ id: "call_1", name: "lookup", input: { query: "weather" } }),
+      LLMEvent.finish({ reason: "tool-calls" }),
+    ])
+
+    expect(response?.message.content).toEqual([
+      { type: "tool-call", id: "call_1", name: "lookup", input: { query: "weather" } },
+    ])
+  })
+})

packages/ai/test/route.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test"
+import * as OpenAIChat from "../src/protocols/openai-chat"
+import { Auth } from "../src/route"
+
+describe("Route.with", () => {
+  test("merges endpoint query and header defaults while replacing auth and id", () => {
+    const auth = Auth.headers({ "x-auth": "new" })
+    const route = OpenAIChat.route
+      .with({
+        id: "base-chat",
+        endpoint: {
+          baseURL: "https://api.example.test/v1",
+          query: { keep: "base", base: "1" },
+        },
+        headers: { "x-base": "base", "x-override": "base" },
+        auth: Auth.headers({ "x-auth": "old" }),
+      })
+      .with({
+        id: "patched-chat",
+        endpoint: { query: { keep: "patch", patch: "1" } },
+        headers: { "x-override": "patch", "x-patch": "patch" },
+        auth,
+      })
+
+    expect(route.id).toBe("patched-chat")
+    expect(route.auth).toBe(auth)
+    expect(route.endpoint).toMatchObject({
+      baseURL: "https://api.example.test/v1",
+      path: "/chat/completions",
+      query: { keep: "patch", base: "1", patch: "1" },
+    })
+    expect(route.defaults.headers).toEqual({
+      "x-base": "base",
+      "x-override": "patch",
+      "x-patch": "patch",
+    })
+    expect(route.defaults.http?.headers).toEqual({
+      "x-base": "base",
+      "x-override": "patch",
+      "x-patch": "patch",
+    })
+  })
+})

packages/ai/test/schema.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from "bun:test"
+import { Schema } from "effect"
+import * as OpenAIChat from "../src/protocols/openai-chat"
+import * as OpenAIResponses from "../src/protocols/openai-responses"
+import { ContentPart, LLMEvent, LLMRequest, Model, ModelID, ProviderID, Usage } from "../src/schema"
+import { ProviderShared } from "../src/protocols/shared"
+
+const model = new Model({
+  id: ModelID.make("fake-model"),
+  provider: ProviderID.make("fake-provider"),
+  route: OpenAIChat.route,
+})
+
+const decodeLLMRequest = Schema.decodeUnknownSync(LLMRequest as unknown as Schema.Decoder<LLMRequest>)
+const decodeLLMEvent = Schema.decodeUnknownSync(LLMEvent as unknown as Schema.Decoder<LLMEvent>)
+
+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 = decodeLLMRequest(input)
+
+    expect(decoded.id).toBe("req_1")
+    expect(decoded.messages[0]?.content[0]?.type).toBe("text")
+  })
+
+  test("accepts custom route ids", () => {
+    const decoded = decodeLLMRequest({
+      model: Model.update(model, { route: OpenAIResponses.route }),
+      system: [],
+      messages: [],
+      tools: [],
+      generation: {},
+    })
+
+    expect(decoded.model.route.id).toBe("openai-responses")
+  })
+
+  test("rejects invalid event type", () => {
+    expect(() => decodeLLMEvent({ type: "bogus" })).toThrow()
+  })
+
+  test("finish constructors accept usage input", () => {
+    expect(LLMEvent.stepFinish({ index: 0, reason: "stop", usage: { inputTokens: 1 } }).usage).toBeInstanceOf(Usage)
+    expect(LLMEvent.finish({ reason: "stop", usage: { outputTokens: 2 } }).usage).toBeInstanceOf(Usage)
+  })
+
+  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)
+  })
+})
+
+describe("LLM.Usage", () => {
+  test("subtractTokens clamps non-sensical breakdowns to zero", () => {
+    // Defense against a provider reporting cached_tokens > prompt_tokens or
+    // reasoning_tokens > completion_tokens — the negative would otherwise
+    // round-trip through the pipeline and crash strict downstream schemas.
+    expect(ProviderShared.subtractTokens(5, 3)).toBe(2)
+    expect(ProviderShared.subtractTokens(5, 10)).toBe(0)
+    expect(ProviderShared.subtractTokens(5, undefined)).toBe(5)
+    expect(ProviderShared.subtractTokens(undefined, 3)).toBeUndefined()
+    expect(ProviderShared.subtractTokens(undefined, undefined)).toBeUndefined()
+  })
+
+  test("sumTokens returns undefined only when every input is undefined", () => {
+    expect(ProviderShared.sumTokens(1, 2, 3)).toBe(6)
+    expect(ProviderShared.sumTokens(1, undefined, 3)).toBe(4)
+    expect(ProviderShared.sumTokens(undefined, undefined, undefined)).toBeUndefined()
+    expect(ProviderShared.sumTokens()).toBeUndefined()
+  })
+
+  test("visibleOutputTokens clamps reasoning > output to zero", () => {
+    expect(new Usage({ outputTokens: 10, reasoningTokens: 4 }).visibleOutputTokens).toBe(6)
+    expect(new Usage({ outputTokens: 10 }).visibleOutputTokens).toBe(10)
+    expect(new Usage({ outputTokens: 4, reasoningTokens: 10 }).visibleOutputTokens).toBe(0)
+    expect(new Usage({}).visibleOutputTokens).toBe(0)
+  })
+})

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

@@ -0,0 +1,818 @@
+import { describe, expect } from "bun:test"
+import { Effect, Schema, Stream } from "effect"
+import {
+  GenerationOptions,
+  LLM,
+  LLMEvent,
+  LLMRequest,
+  LLMResponse,
+  ToolChoice,
+  ToolContent,
+  ToolOutput,
+  toDefinitions,
+} from "../src"
+import { Auth, LLMClient } from "../src/route"
+import * as AnthropicMessages from "../src/protocols/anthropic-messages"
+import * as OpenAIChat from "../src/protocols/openai-chat"
+import * as OpenAIResponses from "../src/protocols/openai-responses"
+import { Tool, ToolFailure, type ToolExecuteContext } from "../src/tool"
+import { ToolRuntime } from "../src/tool-runtime"
+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.route
+  .with({ endpoint: { baseURL: "https://api.openai.test/v1/" }, auth: Auth.bearer("test") })
+  .model({ id: "gpt-4o-mini" })
+const Json = Schema.fromJsonString(Schema.Unknown)
+const decodeJson = Schema.decodeUnknownSync(Json)
+
+const baseRequest = LLM.request({
+  id: "req_1",
+  model,
+  prompt: "Use the tool.",
+})
+const weatherFailureCause = new Error("weather lookup denied")
+
+const get_weather = Tool.make({
+  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}`, error: weatherFailureCause })
+      return { temperature: 22, condition: "sunny" }
+    }),
+})
+
+const schema_only_weather = Tool.make({
+  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: GenerationOptions.make({ maxTokens: 50 }),
+          toolChoice: ToolChoice.make("auto"),
+        }),
+        tools: { get_weather },
+      }).pipe(Stream.runCollect, Effect.provide(layer))
+
+      const second = bodies[1]
+      if (!second || typeof second !== "object") throw new Error("Expected second request body")
+      const messages = Reflect.get(second, "messages")
+      const tools = Reflect.get(second, "tools")
+
+      expect(Reflect.get(second, "max_tokens")).toBe(50)
+      expect(Reflect.get(second, "tool_choice")).toBe("auto")
+      expect(tools).toHaveLength(1)
+      expect(
+        Array.isArray(messages)
+          ? messages.map((message) =>
+              message && typeof message === "object" ? Reflect.get(message, "role") : undefined,
+            )
+          : undefined,
+      ).toEqual(["user", "assistant", "tool"])
+      expect(Array.isArray(messages) ? messages[1] : undefined).toMatchObject({
+        role: "assistant",
+        content: null,
+        tool_calls: [{ id: "call_1", type: "function", function: { name: "get_weather" } }],
+      })
+      expect(Array.isArray(messages) ? messages[2] : undefined).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("finish")
+      expect(LLMResponse.text({ events })).toBe("It's sunny in Paris.")
+    }),
+  )
+
+  it.effect("projects encoded typed tool success into canonical model content", () =>
+    Effect.gen(function* () {
+      const calls: unknown[] = []
+      const projected = Tool.make({
+        description: "Project an encoded success.",
+        parameters: Schema.Struct({ prefix: Schema.String }),
+        success: Schema.Struct({ count: Schema.NumberFromString }),
+        execute: () => Effect.succeed({ count: 2 }),
+        toModelOutput: (input) => {
+          calls.push(input)
+          return [{ type: "text", text: `${input.parameters.prefix}:${input.output.count}` }]
+        },
+      })
+
+      const dispatched = yield* ToolRuntime.dispatch(
+        { projected },
+        LLMEvent.toolCall({ id: "call_projected", name: "projected", input: { prefix: "count" } }),
+      )
+
+      expect(calls).toEqual([{ callID: "call_projected", parameters: { prefix: "count" }, output: { count: "2" } }])
+      expect(dispatched.result).toEqual({ type: "text", value: "count:2" })
+      expect(dispatched.output).toEqual({ structured: { count: "2" }, content: [{ type: "text", text: "count:2" }] })
+      expect(dispatched.events).toEqual([
+        LLMEvent.toolResult({
+          id: "call_projected",
+          name: "projected",
+          result: { type: "text", value: "count:2" },
+          output: { structured: { count: "2" }, content: [{ type: "text", text: "count:2" }] },
+        }),
+      ])
+    }),
+  )
+
+  it.effect("uses the narrow default projection for encoded typed success", () =>
+    Effect.gen(function* () {
+      const text = Tool.make({
+        description: "Return text.",
+        parameters: Schema.Struct({}),
+        success: Schema.String,
+        execute: () => Effect.succeed("hello"),
+      })
+      const json = Tool.make({
+        description: "Return JSON.",
+        parameters: Schema.Struct({}),
+        success: Schema.Struct({ ok: Schema.Boolean }),
+        execute: () => Effect.succeed({ ok: true }),
+      })
+
+      expect(
+        (yield* ToolRuntime.dispatch({ text }, LLMEvent.toolCall({ id: "call_text", name: "text", input: {} }))).output,
+      ).toEqual({ structured: "hello", content: [{ type: "text", text: "hello" }] })
+      expect(
+        (yield* ToolRuntime.dispatch({ json }, LLMEvent.toolCall({ id: "call_json", name: "json", input: {} }))).output,
+      ).toEqual({ structured: { ok: true }, content: [] })
+    }),
+  )
+
+  it.effect("can retain model media while redacting duplicated structured payloads", () =>
+    Effect.gen(function* () {
+      const image = Tool.make({
+        description: "Return an image.",
+        parameters: Schema.Struct({}),
+        success: Schema.Struct({ mime: Schema.String, data: Schema.String }),
+        execute: () => Effect.succeed({ mime: "image/png", data: "AAECAw==" }),
+        toStructuredOutput: (output) => ({ mime: output.mime }),
+        toModelOutput: ({ output }) => [
+          { type: "file", uri: `data:${output.mime};base64,${output.data}`, mime: output.mime },
+        ],
+      })
+
+      const dispatched = yield* ToolRuntime.dispatch(
+        { image },
+        LLMEvent.toolCall({ id: "call_image", name: "image", input: {} }),
+      )
+
+      expect(dispatched.output).toEqual({
+        structured: { mime: "image/png" },
+        content: [{ type: "file", uri: "data:image/png;base64,AAECAw==", mime: "image/png" }],
+      })
+    }),
+  )
+
+  it.effect("models canonical tool files with URIs", () =>
+    Effect.sync(() => {
+      const decode = Schema.decodeUnknownSync(ToolContent)
+
+      expect(decode({ type: "file", uri: "data:image/png;base64,AAAA", mime: "image/png" })).toEqual({
+        type: "file",
+        uri: "data:image/png;base64,AAAA",
+        mime: "image/png",
+      })
+      expect(decode({ type: "file", uri: "https://example.test/image.png", mime: "image/png" })).toEqual({
+        type: "file",
+        uri: "https://example.test/image.png",
+        mime: "image/png",
+      })
+      expect(decode({ type: "file", uri: "file:///tmp/image.png", mime: "image/png" })).toEqual({
+        type: "file",
+        uri: "file:///tmp/image.png",
+        mime: "image/png",
+      })
+    }),
+  )
+
+  it.effect("preserves canonical tool file URIs", () =>
+    Effect.sync(() => {
+      expect(
+        ToolOutput.toResultValue(
+          ToolOutput.make({}, [{ type: "file", uri: "data:image/png;base64,AAAA", mime: "image/png" }]),
+        ),
+      ).toEqual({
+        type: "content",
+        value: [{ type: "file", uri: "data:image/png;base64,AAAA", mime: "image/png" }],
+      })
+      expect(
+        ToolOutput.toResultValue(
+          ToolOutput.make({}, [{ type: "file", uri: "https://example.test/image.png", mime: "image/png" }]),
+        ),
+      ).toEqual({
+        type: "content",
+        value: [{ type: "file", uri: "https://example.test/image.png", mime: "image/png" }],
+      })
+      expect(
+        ToolOutput.toResultValue(
+          ToolOutput.make({}, [{ type: "file", uri: "file:///tmp/image.png", mime: "image/png" }]),
+        ),
+      ).toEqual({
+        type: "content",
+        value: [{ type: "file", uri: "file:///tmp/image.png", mime: "image/png" }],
+      })
+      expect(
+        ToolOutput.fromResultValue({
+          type: "content",
+          value: [{ type: "file", uri: "https://example.test/image.png", mime: "image/png" }],
+        }),
+      ).toEqual({
+        structured: {},
+        content: [{ type: "file", uri: "https://example.test/image.png", mime: "image/png" }],
+      })
+    }),
+  )
+
+  it.effect("settles projected URL files as canonical tool results", () =>
+    Effect.gen(function* () {
+      const remote = Tool.make({
+        description: "Return a remote file.",
+        parameters: Schema.Struct({}),
+        success: Schema.Struct({ ok: Schema.Boolean }),
+        execute: () => Effect.succeed({ ok: true }),
+        toModelOutput: () => [{ type: "file", uri: "https://example.test/image.png", mime: "image/png" }],
+      })
+
+      const dispatched = yield* ToolRuntime.dispatch(
+        { remote },
+        LLMEvent.toolCall({ id: "call_remote", name: "remote", input: {} }),
+      )
+
+      expect(dispatched.output).toEqual({
+        structured: { ok: true },
+        content: [{ type: "file", uri: "https://example.test/image.png", mime: "image/png" }],
+      })
+      expect(dispatched.result).toEqual({
+        type: "content",
+        value: [{ type: "file", uri: "https://example.test/image.png", mime: "image/png" }],
+      })
+      expect(dispatched.events.map((event) => event.type)).toEqual(["tool-result"])
+    }),
+  )
+
+  it.effect("derives typed output schemas and preserves dynamic output schemas", () =>
+    Effect.sync(() => {
+      const [typed] = toDefinitions({ get_weather })
+      const schema = { type: "object", properties: { result: { type: "string" } } } as const
+      const [dynamic] = toDefinitions({
+        dynamic: Tool.make({ description: "Dynamic tool.", jsonSchema: { type: "object" }, outputSchema: schema }),
+      })
+
+      expect(typed?.outputSchema).toMatchObject({
+        type: "object",
+        properties: { condition: { type: "string" } },
+        required: ["temperature", "condition"],
+        additionalProperties: false,
+      })
+      expect(Reflect.get(Reflect.get(typed?.outputSchema ?? {}, "properties") as object, "temperature")).toBeDefined()
+      expect(dynamic?.outputSchema).toEqual(schema)
+    }),
+  )
+
+  it.effect("preserves content tool results from dynamic tools", () =>
+    Effect.gen(function* () {
+      const screenshot = Tool.make({
+        description: "Capture a screenshot.",
+        jsonSchema: { type: "object", properties: {} },
+        execute: () =>
+          Effect.succeed({
+            type: "content" as const,
+            value: [
+              { type: "text" as const, text: "Screenshot captured." },
+              { type: "file" as const, uri: "data:image/png;base64,AAAA", mime: "image/png" },
+            ],
+          }),
+      })
+
+      const events = Array.from(
+        yield* TestToolRuntime.runTools({ request: baseRequest, tools: { screenshot }, maxSteps: 1 }).pipe(
+          Stream.runCollect,
+          Effect.provide(
+            scriptedResponses([sseEvents(toolCallChunk("call_1", "screenshot", "{}"), finishChunk("tool_calls"))]),
+          ),
+        ),
+      )
+
+      expect(events.find(LLMEvent.is.toolResult)).toMatchObject({
+        type: "tool-result",
+        id: "call_1",
+        name: "screenshot",
+        result: {
+          type: "content",
+          value: [
+            { type: "text", text: "Screenshot captured." },
+            { type: "file", uri: "data:image/png;base64,AAAA", mime: "image/png" },
+          ],
+        },
+      })
+    }),
+  )
+
+  it.effect("does not mistake dynamic tool output fields for dispatcher state", () =>
+    Effect.gen(function* () {
+      const callerOwned = { type: "json" as const, value: { ok: true }, events: ["caller-owned"] }
+      const eventful = Tool.make({
+        description: "Return an events field.",
+        jsonSchema: { type: "object", properties: {} },
+        execute: () => Effect.succeed(callerOwned),
+      })
+
+      const dispatched = yield* ToolRuntime.dispatch(
+        { eventful },
+        LLMEvent.toolCall({ id: "call_1", name: "eventful", input: {} }),
+      )
+
+      expect(dispatched.result).toEqual(callerOwned)
+      expect(dispatched.events).toEqual([
+        LLMEvent.toolResult({
+          id: "call_1",
+          name: "eventful",
+          result: callerOwned,
+          output: { structured: { ok: true }, content: [] },
+        }),
+      ])
+    }),
+  )
+
+  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* TestToolRuntime.runTools({ request: baseRequest, tools: { get_weather }, maxSteps: 1 }).pipe(
+          Stream.runCollect,
+          Effect.provide(layer),
+        ),
+      )
+
+      expect(events.filter(LLMEvent.is.finish)).toHaveLength(1)
+      expect(events.find(LLMEvent.is.toolResult)).toMatchObject({ type: "tool-result", id: "call_1" })
+    }),
+  )
+
+  it.effect("passes tool call context to execute", () =>
+    Effect.gen(function* () {
+      let context: ToolExecuteContext | undefined
+      const contextual = Tool.make({
+        description: "Capture tool context.",
+        parameters: Schema.Struct({ value: Schema.String }),
+        success: Schema.Struct({ ok: Schema.Boolean }),
+        execute: (_params, ctx) =>
+          Effect.sync(() => {
+            context = ctx
+            return { ok: true }
+          }),
+      })
+      const events = Array.from(
+        yield* TestToolRuntime.runTools({ request: baseRequest, tools: { contextual } }).pipe(
+          Stream.runCollect,
+          Effect.provide(
+            scriptedResponses([
+              sseEvents(toolCallChunk("call_ctx", "contextual", '{"value":"x"}'), finishChunk("tool_calls")),
+            ]),
+          ),
+        ),
+      )
+
+      expect(events.some(LLMEvent.is.toolResult)).toBe(true)
+      expect(context).toEqual({ id: "call_ctx", name: "contextual" })
+    }),
+  )
+
+  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(
+          LLMRequest.update(baseRequest, { tools: toDefinitions({ get_weather: schema_only_weather }) }),
+        ).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.route
+            .with({ auth: Auth.header("x-api-key", "test") })
+            .model({ id: "claude-sonnet-4-5" }),
+        }),
+        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("replays encrypted OpenAI reasoning items with tool outputs", () =>
+    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: "response.output_item.added",
+                    item: { type: "reasoning", id: "rs_1", encrypted_content: null },
+                  },
+                  { type: "response.reasoning_summary_part.added", item_id: "rs_1", summary_index: 0 },
+                  { type: "response.reasoning_summary_part.done", item_id: "rs_1", summary_index: 0 },
+                  {
+                    type: "response.output_item.done",
+                    item: { type: "reasoning", id: "rs_1", encrypted_content: "encrypted-state" },
+                  },
+                  {
+                    type: "response.output_item.added",
+                    item: {
+                      type: "function_call",
+                      id: "item_1",
+                      call_id: "call_1",
+                      name: "get_weather",
+                      arguments: "",
+                    },
+                  },
+                  { type: "response.function_call_arguments.delta", item_id: "item_1", delta: '{"city":"Paris"}' },
+                  {
+                    type: "response.output_item.done",
+                    item: {
+                      type: "function_call",
+                      id: "item_1",
+                      call_id: "call_1",
+                      name: "get_weather",
+                      arguments: '{"city":"Paris"}',
+                    },
+                  },
+                  { type: "response.completed", response: {} },
+                )
+              : sseEvents(
+                  { type: "response.output_text.delta", item_id: "msg_1", delta: "Done." },
+                  { type: "response.completed", response: {} },
+                ),
+            { headers: { "content-type": "text/event-stream" } },
+          )
+        }),
+      )
+
+      yield* TestToolRuntime.runTools({
+        request: LLM.request({
+          model: OpenAIResponses.route
+            .with({ endpoint: { baseURL: "https://api.openai.test/v1/" }, auth: Auth.bearer("test") })
+            .model({ id: "gpt-5.5" }),
+          prompt: "Use the tool.",
+          providerOptions: { openai: { store: false, include: ["reasoning.encrypted_content"] } },
+        }),
+        tools: { get_weather },
+      }).pipe(Stream.runCollect, Effect.provide(layer))
+
+      expect(bodies[1]).toMatchObject({
+        include: ["reasoning.encrypted_content"],
+        input: [
+          { role: "user" },
+          { type: "reasoning", summary: [], encrypted_content: "encrypted-state" },
+          { type: "function_call", call_id: "call_1", name: "get_weather" },
+          { type: "function_call_output", call_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")
+      expect(toolError?.error).toBe(weatherFailureCause)
+    }),
+  )
+
+  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([
+        "step-start",
+        "text-start",
+        "text-delta",
+        "text-end",
+        "step-finish",
+        "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.finish)).toHaveLength(1)
+      expect(events.filter(LLMEvent.is.stepStart).map((event) => event.index)).toEqual([0, 1])
+      expect(events.filter(LLMEvent.is.stepFinish).map((event) => event.index)).toEqual([0, 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.route
+              .with({ auth: Auth.header("x-api-key", "test") })
+              .model({ id: "claude-sonnet-4-5" }),
+          }),
+          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/ai/test/tool-schema-projection.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { LLM } from "../src"
+import { OpenAIChat } from "../src/protocols"
+import { ToolSchemaProjection } from "../src/protocols/utils/tool-schema"
+import { Auth, LLMClient } from "../src/route"
+import { it } from "./lib/effect"
+
+describe("tool schema projections", () => {
+  test("moonshot strips $ref siblings and converts tuple arrays to a schema object", () => {
+    expect(
+      ToolSchemaProjection.moonshot({
+        type: "object",
+        properties: {
+          linked: { $ref: "#/$defs/Linked", description: "drop me" },
+          tuple: { type: "array", items: [{ type: "string" }, { type: "number" }] },
+          prefixTuple: { type: "array", prefixItems: [{ type: "boolean" }, { type: "string" }] },
+        },
+      }),
+    ).toEqual({
+      type: "object",
+      properties: {
+        linked: { $ref: "#/$defs/Linked" },
+        tuple: { type: "array", items: { anyOf: [{ type: "string" }, { type: "number" }] } },
+        prefixTuple: { type: "array", items: { anyOf: [{ type: "boolean" }, { type: "string" }] } },
+      },
+    })
+  })
+
+  test("gemini handles numeric enums, dangling required fields, untyped arrays, and scalar object keys", () => {
+    expect(
+      ToolSchemaProjection.gemini({
+        type: "object",
+        required: ["status", "missing"],
+        properties: {
+          status: { type: "integer", enum: [1, 2] },
+          tags: { type: "array" },
+          name: { type: "string", properties: { ignored: { type: "string" } }, required: ["ignored"] },
+        },
+      }),
+    ).toEqual({
+      type: "object",
+      required: ["status"],
+      properties: {
+        status: { type: "string", enum: ["1", "2"] },
+        tags: { type: "array", items: { type: "string" } },
+        name: { type: "string" },
+      },
+    })
+  })
+
+  test("openai keeps one flat object top-level schema", () => {
+    expect(
+      ToolSchemaProjection.openAI({
+        anyOf: [
+          {
+            type: "object",
+            properties: {
+              path: { type: "string" },
+              maybe: { anyOf: [{ type: "string" }, { type: "null" }] },
+            },
+          },
+          { type: "object", properties: { resource: { type: "string" } } },
+        ],
+      }),
+    ).toEqual({
+      type: "object",
+      properties: {
+        path: { type: "string" },
+        maybe: { type: "string" },
+        resource: { type: "string" },
+      },
+      additionalProperties: false,
+    })
+  })
+
+  it.effect("applies model compatibility before protocol projection", () =>
+    Effect.gen(function* () {
+      const model = OpenAIChat.route
+        .with({ endpoint: { baseURL: "https://api.openai.test/v1/" }, auth: Auth.bearer("test") })
+        .model({ id: "kimi-k2", compatibility: { toolSchema: "moonshot" } })
+      const prepared = yield* LLMClient.prepare<OpenAIChat.OpenAIChatBody>(
+        LLM.request({
+          model,
+          prompt: "Use the tool.",
+          tools: [
+            {
+              name: "lookup",
+              description: "Lookup data.",
+              inputSchema: {
+                type: "object",
+                anyOf: [
+                  {
+                    type: "object",
+                    properties: {
+                      tuple: { type: "array", items: [{ type: "string" }, { type: "number" }] },
+                      linked: { $ref: "#/$defs/Linked", description: "drop me" },
+                    },
+                  },
+                ],
+              },
+            },
+          ],
+        }),
+      )
+
+      expect(prepared.body.tools?.[0]?.function.parameters).toEqual({
+        type: "object",
+        properties: {
+          tuple: { type: "array", items: { anyOf: [{ type: "string" }, { type: "number" }] } },
+          linked: { $ref: "#/$defs/Linked" },
+        },
+        additionalProperties: false,
+      })
+    }),
+  )
+})

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

@@ -0,0 +1,99 @@
+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.events).toEqual([
+        { type: "tool-input-start", id: "call_1", name: "lookup" },
+        { type: "tool-input-delta", id: "call_1", name: "lookup", text: '{"query"' },
+      ])
+      expect(second.events).toEqual([{ type: "tool-input-delta", id: "call_1", name: "lookup", text: ':"weather"}' }])
+      expect(finished).toEqual({
+        tools: {},
+        events: [
+          { type: "tool-input-end", id: "call_1", name: "lookup" },
+          { 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: {},
+        events: [
+          { type: "tool-input-end", id: "call_1", name: "lookup" },
+          { 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-input-end", id: "call_1", name: "lookup" },
+          { type: "tool-call", id: "call_1", name: "lookup", input: {} },
+          { type: "tool-input-end", id: "call_2", name: "web_search" },
+          {
+            type: "tool-call",
+            id: "call_2",
+            name: "web_search",
+            input: { query: "docs" },
+            providerExecuted: true,
+          },
+        ],
+      })
+    }),
+  )
+})

packages/ai/test/tool.types.ts

@@ -0,0 +1,40 @@
+import { Effect, Schema } from "effect"
+import { LLM, LLMRequest, ToolRuntime, toDefinitions } from "../src"
+import * as OpenAIChat from "../src/protocols/openai-chat"
+import { Auth } from "../src/route"
+import { Tool } from "../src/tool"
+
+const request = LLM.request({
+  model: OpenAIChat.route.with({ auth: Auth.bearer("fixture") }).model({ id: "gpt-4o-mini" }),
+  prompt: "Use the tool.",
+})
+
+const executable = Tool.make({
+  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.make({
+  description: "Get weather.",
+  parameters: Schema.Struct({ city: Schema.String }),
+  success: Schema.Struct({ forecast: Schema.String }),
+})
+
+Tool.make({
+  description: "Encode success before projection.",
+  parameters: Schema.Struct({ city: Schema.String }),
+  success: Schema.Struct({ forecast: Schema.NumberFromString }),
+  execute: () => Effect.succeed({ forecast: 1 }),
+  toModelOutput: ({ callID, parameters, output }) => [
+    { type: "text", text: `${callID}:${parameters.city}:${output.forecast}` },
+  ],
+})
+
+LLM.stream(request)
+LLM.generate(LLMRequest.update(request, { tools: toDefinitions({ schemaOnly }) }))
+ToolRuntime.dispatch({ executable }, { type: "tool-call", id: "call_1", name: "executable", input: { city: "Paris" } })
+
+// @ts-expect-error High-level tool orchestration overloads are intentionally not supported.
+LLM.stream({ request, tools: { schemaOnly } })