Refactor LLM route-first provider API (#28523)

packages/llm/src/cache-policy.ts

@@ -97,7 +97,7 @@ const markMessages = (
 }
 
 export const applyCachePolicy = (request: LLMRequest): LLMRequest => {
-  if (!RESPECTS_INLINE_HINTS.has(request.model.route)) return request
+  if (!RESPECTS_INLINE_HINTS.has(request.model.route.id)) return request
   const policy = resolve(request.cache)
   if (!policy.tools && !policy.system && !policy.messages) return request
 

packages/llm/src/index.ts

@@ -1,4 +1,4 @@
-export { LLMClient, modelLimits, modelRef } from "./route/client"
+export { LLMClient } from "./route/client"
 export { Auth } from "./route/auth"
 export { Provider } from "./provider"
 export type {
@@ -6,7 +6,6 @@ export type {
   RouteRoutedModelInput,
   Interface as LLMClientShape,
   Service as LLMClientService,
-  ModelRefInput,
 } from "./route/client"
 export * from "./schema"
 export { Tool, ToolFailure, toDefinitions, tool } from "./tool"

packages/llm/src/llm.ts

@@ -1,5 +1,5 @@
 import { Effect, JsonSchema, Schema } from "effect"
-import { LLMClient, modelLimits, modelRef, type ModelRefInput } from "./route/client"
+import { LLMClient } from "./route/client"
 import {
   GenerationOptions,
   HttpOptions,
@@ -9,6 +9,7 @@ import {
   LLMRequest,
   LLMResponse,
   Message,
+  type ModelInput as SchemaModelInput,
   SystemPart,
   ToolChoice,
   ToolDefinition,
@@ -18,7 +19,7 @@ import {
 } from "./schema"
 import { make as makeTool, type ToolSchema } from "./tool"
 
-export type ModelInput = ModelRefInput
+export type ModelInput = SchemaModelInput
 
 export type MessageInput = Message.Input
 
@@ -42,10 +43,6 @@ export type RequestInput = Omit<
   readonly http?: HttpOptions.Input
 }
 
-export const limits = modelLimits
-
-export const model = modelRef
-
 export const generate = LLMClient.generate
 
 export const stream = LLMClient.stream

packages/llm/src/protocols/anthropic-messages.ts

@@ -386,7 +386,7 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
     tools,
     tool_choice: toolChoice,
     stream: true as const,
-    max_tokens: generation?.maxTokens ?? request.model.limits.output ?? 4096,
+    max_tokens: generation?.maxTokens ?? request.model.route.defaults.limits?.output ?? 4096,
     temperature: generation?.temperature,
     top_p: generation?.topP,
     top_k: generation?.topK,
@@ -452,8 +452,8 @@ const mergeUsage = (left: Usage | undefined, right: Usage | undefined) => {
     totalTokens: ProviderShared.totalTokens(inputTokens, outputTokens, undefined),
     providerMetadata: {
       anthropic: {
-        ...(left.providerMetadata?.["anthropic"] ?? {}),
-        ...(right.providerMetadata?.["anthropic"] ?? {}),
+        ...left.providerMetadata?.["anthropic"],
+        ...right.providerMetadata?.["anthropic"],
       },
     },
   })
@@ -673,19 +673,12 @@ export const protocol = Protocol.make({
 
 export const route = Route.make({
   id: ADAPTER,
+  provider: "anthropic",
   protocol,
-  endpoint: Endpoint.path(PATH),
-  auth: Auth.apiKeyHeader("x-api-key"),
+  endpoint: Endpoint.path(PATH, { baseURL: DEFAULT_BASE_URL }),
+  auth: Auth.none,
   framing: Framing.sse,
   headers: () => ({ "anthropic-version": "2023-06-01" }),
 })
 
-// =============================================================================
-// Model Helper
-// =============================================================================
-export const model = Route.model(route, {
-  provider: "anthropic",
-  baseURL: DEFAULT_BASE_URL,
-})
-
 export * as AnthropicMessages from "./anthropic-messages"

packages/llm/src/protocols/bedrock-converse.ts

@@ -1,5 +1,5 @@
 import { Effect, Schema } from "effect"
-import { Route, type RouteModelInput } from "../route/client"
+import { Route } from "../route/client"
 import { Endpoint } from "../route/endpoint"
 import { Protocol } from "../route/protocol"
 import {
@@ -14,7 +14,7 @@ import {
 } from "../schema"
 import { BedrockEventStream } from "./bedrock-event-stream"
 import { JsonObject, optionalArray, ProviderShared } from "./shared"
-import { BedrockAuth, type Credentials as BedrockCredentials } from "./utils/bedrock-auth"
+import { BedrockAuth } from "./utils/bedrock-auth"
 import { BedrockCache } from "./utils/bedrock-cache"
 import { BedrockMedia } from "./utils/bedrock-media"
 import { Lifecycle } from "./utils/lifecycle"
@@ -24,23 +24,6 @@ const ADAPTER = "bedrock-converse"
 
 export type { Credentials as BedrockCredentials } from "./utils/bedrock-auth"
 
-// =============================================================================
-// Public Model Input
-// =============================================================================
-export type BedrockConverseModelInput = RouteModelInput & {
-  /**
-   * Bearer API key (Bedrock's newer API key auth). Sets the `Authorization`
-   * header and bypasses SigV4 signing. Mutually exclusive with `credentials`.
-   */
-  readonly apiKey?: string
-  /**
-   * AWS credentials for SigV4 signing. The route signs each request at
-   * `toHttp` time using `aws4fetch`. Mutually exclusive with `apiKey`.
-   */
-  readonly credentials?: BedrockCredentials
-  readonly headers?: Record<string, string>
-}
-
 // =============================================================================
 // Request Body Schema
 // =============================================================================
@@ -61,6 +44,7 @@ type BedrockToolUseBlock = Schema.Schema.Type<typeof BedrockToolUseBlock>
 const BedrockToolResultContentItem = Schema.Union([
   Schema.Struct({ text: Schema.String }),
   Schema.Struct({ json: Schema.Unknown }),
+  BedrockMedia.ImageBlock,
 ])
 
 const BedrockToolResultBlock = Schema.Struct({
@@ -261,15 +245,33 @@ const lowerToolCall = (part: ToolCallPart): BedrockToolUseBlock => ({
   },
 })
 
-const lowerToolResult = (part: ToolResultPart): BedrockToolResultBlock => ({
-  toolResult: {
-    toolUseId: part.id,
-    content:
-      part.result.type === "text" || part.result.type === "error"
-        ? [{ text: ProviderShared.toolResultText(part) }]
-        : [{ json: part.result.value }],
-    status: part.result.type === "error" ? "error" : "success",
-  },
+const lowerToolResultContent = Effect.fn("BedrockConverse.lowerToolResultContent")(function* (part: ToolResultPart) {
+  if (part.result.type === "text" || part.result.type === "error")
+    return [{ text: ProviderShared.toolResultText(part) }]
+  if (part.result.type === "json") return [{ json: part.result.value }]
+
+  const content: Array<Schema.Schema.Type<typeof BedrockToolResultContentItem>> = []
+  for (const item of part.result.value) {
+    if (item.type === "text") {
+      content.push({ text: item.text })
+      continue
+    }
+    const media = yield* BedrockMedia.lower(item)
+    if (!("image" in media))
+      return yield* ProviderShared.invalidRequest("Bedrock Converse only supports image media in tool results")
+    content.push(media)
+  }
+  return content
+})
+
+const lowerToolResult = Effect.fn("BedrockConverse.lowerToolResult")(function* (part: ToolResultPart) {
+  return {
+    toolResult: {
+      toolUseId: part.id,
+      content: yield* lowerToolResultContent(part),
+      status: part.result.type === "error" ? "error" : "success",
+    },
+  } satisfies BedrockToolResultBlock
 })
 
 const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (
@@ -331,7 +333,7 @@ const lowerMessages = Effect.fn("BedrockConverse.lowerMessages")(function* (
     for (const part of message.content) {
       if (!ProviderShared.supportsContent(part, ["tool-result"]))
         return yield* ProviderShared.unsupportedContent("Bedrock Converse", "tool", ["tool-result"])
-      content.push(lowerToolResult(part))
+      content.push(yield* lowerToolResult(part))
       const cachePoint = BedrockCache.block(breakpoints, part.cache)
       if (cachePoint) content.push(cachePoint)
     }
@@ -597,11 +599,11 @@ export const protocol = Protocol.make({
 
 export const route = Route.make({
   id: ADAPTER,
+  provider: "bedrock",
   protocol,
-  // Bedrock's URL embeds the region in the host (set on `model.baseURL` by
-  // the provider helper from credentials) and the validated modelId in the
-  // path. We read the validated body so the URL matches the body that gets
-  // signed.
+  // Bedrock's URL embeds the region in the route endpoint host and the
+  // validated modelId in the path. We read the validated body so the URL
+  // matches the body that gets signed.
   endpoint: Endpoint.path<BedrockConverseBody>(
     ({ body }) => `/model/${encodeURIComponent(body.modelId)}/converse-stream`,
   ),
@@ -609,26 +611,6 @@ export const route = Route.make({
   framing,
 })
 
-export const nativeCredentials = BedrockAuth.nativeCredentials
-
-const bedrockModel = Route.model(
-  route,
-  {
-    provider: "bedrock",
-  },
-  {
-    mapInput: (input: BedrockConverseModelInput) => {
-      const { credentials, ...rest } = input
-      const region = credentials?.region ?? "us-east-1"
-      return {
-        ...rest,
-        baseURL: rest.baseURL ?? `https://bedrock-runtime.${region}.amazonaws.com`,
-        native: nativeCredentials(input.native, credentials),
-      }
-    },
-  },
-)
-
-export const model = bedrockModel
+export const sigV4Auth = BedrockAuth.sigV4
 
 export * as BedrockConverse from "./bedrock-converse"

packages/llm/src/protocols/gemini.ts

@@ -404,19 +404,14 @@ export const protocol = Protocol.make({
 
 export const route = Route.make({
   id: ADAPTER,
+  provider: "google",
   protocol,
   // Gemini's path embeds the model id and pins SSE framing at the URL level.
-  endpoint: Endpoint.path(({ request }) => `/models/${request.model.id}:streamGenerateContent?alt=sse`),
-  auth: Auth.apiKeyHeader("x-goog-api-key"),
+  endpoint: Endpoint.path(({ request }) => `/models/${request.model.id}:streamGenerateContent?alt=sse`, {
+    baseURL: DEFAULT_BASE_URL,
+  }),
+  auth: Auth.none,
   framing: Framing.sse,
 })
 
-// =============================================================================
-// Model Helper
-// =============================================================================
-export const model = Route.model(route, {
-  provider: "google",
-  baseURL: DEFAULT_BASE_URL,
-})
-
 export * as Gemini from "./gemini"

packages/llm/src/protocols/openai-chat.ts

@@ -2,7 +2,6 @@ import { Array as Arr, Effect, Schema } from "effect"
 import { Route } from "../route/client"
 import { Auth } from "../route/auth"
 import { Endpoint } from "../route/endpoint"
-import { Framing } from "../route/framing"
 import { HttpTransport } from "../route/transport"
 import { Protocol } from "../route/protocol"
 import {
@@ -393,28 +392,15 @@ export const protocol = Protocol.make({
   },
 })
 
-const encodeBody = Schema.encodeSync(Schema.fromJsonString(OpenAIChatBody))
-
-export const httpTransport = HttpTransport.httpJson({
-  endpoint: Endpoint.path(PATH),
-  auth: Auth.bearer(),
-  framing: Framing.sse,
-  encodeBody,
-})
+export const httpTransport = HttpTransport.sseJson.with<OpenAIChatBody>()
 
 export const route = Route.make({
   id: ADAPTER,
   provider: "openai",
   protocol,
+  endpoint: Endpoint.path(PATH, { baseURL: DEFAULT_BASE_URL }),
+  auth: Auth.none,
   transport: httpTransport,
-  defaults: {
-    baseURL: DEFAULT_BASE_URL,
-  },
 })
 
-// =============================================================================
-// Model Helper
-// =============================================================================
-export const model = route.model
-
 export * as OpenAIChat from "./openai-chat"

packages/llm/src/protocols/openai-compatible-chat.ts

@@ -5,16 +5,14 @@ import * as OpenAIChat from "./openai-chat"
 
 const ADAPTER = "openai-compatible-chat"
 
-export type OpenAICompatibleChatModelInput = Omit<RouteRoutedModelInput, "baseURL"> & {
-  readonly baseURL: string
-}
+export type OpenAICompatibleChatModelInput = RouteRoutedModelInput
 
 /**
  * Route for non-OpenAI providers that expose an OpenAI Chat-compatible
  * `/chat/completions` endpoint. Reuses `OpenAIChat.protocol` end-to-end and
  * overrides only the route id so providers can be resolved per-family without
- * colliding with native OpenAI. The model carries the host on `baseURL`,
- * supplied by whichever profile/provider helper builds it.
+ * colliding with native OpenAI. Provider helpers configure the route endpoint
+ * before model selection.
  */
 export const route = Route.make({
   id: ADAPTER,
@@ -23,6 +21,4 @@ export const route = Route.make({
   framing: Framing.sse,
 })
 
-export const model = Route.model<OpenAICompatibleChatModelInput>(route)
-
 export * as OpenAICompatibleChat from "./openai-compatible-chat"

packages/llm/src/protocols/openai-responses.ts

@@ -2,11 +2,11 @@ import { Effect, Schema } from "effect"
 import { Route } from "../route/client"
 import { Auth } from "../route/auth"
 import { Endpoint } from "../route/endpoint"
-import { Framing } from "../route/framing"
 import { HttpTransport, WebSocketTransport } from "../route/transport"
 import { Protocol } from "../route/protocol"
 import {
   LLMEvent,
+  type MediaPart,
   Usage,
   type FinishReason,
   type LLMRequest,
@@ -31,6 +31,12 @@ const OpenAIResponsesInputText = Schema.Struct({
   type: Schema.tag("input_text"),
   text: Schema.String,
 })
+const OpenAIResponsesInputImage = Schema.Struct({
+  type: Schema.tag("input_image"),
+  image_url: Schema.String,
+})
+const OpenAIResponsesInputContent = Schema.Union([OpenAIResponsesInputText, OpenAIResponsesInputImage])
+type OpenAIResponsesInputContent = Schema.Schema.Type<typeof OpenAIResponsesInputContent>
 
 const OpenAIResponsesOutputText = Schema.Struct({
   type: Schema.tag("output_text"),
@@ -39,7 +45,7 @@ const OpenAIResponsesOutputText = Schema.Struct({
 
 const OpenAIResponsesInputItem = Schema.Union([
   Schema.Struct({ role: Schema.tag("system"), content: Schema.String }),
-  Schema.Struct({ role: Schema.tag("user"), content: Schema.Array(OpenAIResponsesInputText) }),
+  Schema.Struct({ role: Schema.tag("user"), content: Schema.Array(OpenAIResponsesInputContent) }),
   Schema.Struct({ role: Schema.tag("assistant"), content: Schema.Array(OpenAIResponsesOutputText) }),
   Schema.Struct({
     type: Schema.tag("function_call"),
@@ -151,12 +157,15 @@ const OpenAIResponsesEvent = Schema.Struct({
   item_id: Schema.optional(Schema.String),
   item: Schema.optional(OpenAIResponsesStreamItem),
   response: Schema.optional(
-    Schema.Struct({
-      id: Schema.optional(Schema.String),
-      service_tier: Schema.optional(Schema.String),
-      incomplete_details: optionalNull(Schema.Struct({ reason: Schema.String })),
-      usage: optionalNull(OpenAIResponsesUsage),
-    }),
+    Schema.StructWithRest(
+      Schema.Struct({
+        id: Schema.optional(Schema.String),
+        service_tier: optionalNull(Schema.String),
+        incomplete_details: optionalNull(Schema.Struct({ reason: Schema.String })),
+        usage: optionalNull(OpenAIResponsesUsage),
+      }),
+      [Schema.Record(Schema.String, Schema.Unknown)],
+    ),
   ),
   code: Schema.optional(Schema.String),
   message: Schema.optional(Schema.String),
@@ -196,6 +205,22 @@ const lowerToolCall = (part: ToolCallPart): OpenAIResponsesInputItem => ({
   arguments: ProviderShared.encodeJson(part.input),
 })
 
+const imageUrl = (part: MediaPart) =>
+  typeof part.data === "string" && part.data.startsWith("data:")
+    ? part.data
+    : `data:${part.mediaType};base64,${ProviderShared.mediaBytes(part)}`
+
+const lowerUserContent = Effect.fn("OpenAIResponses.lowerUserContent")(function* (
+  part: LLMRequest["messages"][number]["content"][number],
+) {
+  if (part.type === "text") return { type: "input_text" as const, text: part.text }
+  if (part.type === "media" && part.mediaType.startsWith("image/")) {
+    return { type: "input_image" as const, image_url: imageUrl(part) }
+  }
+  if (part.type === "media") return yield* invalid("OpenAI Responses user media content only supports images")
+  return yield* ProviderShared.unsupportedContent("OpenAI Responses", "user", ["text", "media"])
+})
+
 const lowerMessages = Effect.fn("OpenAIResponses.lowerMessages")(function* (request: LLMRequest) {
   const system: OpenAIResponsesInputItem[] =
     request.system.length === 0 ? [] : [{ role: "system", content: ProviderShared.joinText(request.system) }]
@@ -203,13 +228,7 @@ const lowerMessages = Effect.fn("OpenAIResponses.lowerMessages")(function* (requ
 
   for (const message of request.messages) {
     if (message.role === "user") {
-      const content: TextPart[] = []
-      for (const part of message.content) {
-        if (!ProviderShared.supportsContent(part, ["text"]))
-          return yield* ProviderShared.unsupportedContent("OpenAI Responses", "user", ["text"])
-        content.push(part)
-      }
-      input.push({ role: "user", content: content.map((part) => ({ type: "input_text", text: part.text })) })
+      input.push({ role: "user", content: yield* Effect.forEach(message.content, lowerUserContent) })
       continue
     }
 
@@ -536,27 +555,18 @@ export const protocol = Protocol.make({
   },
 })
 
-const encodeBody = Schema.encodeSync(Schema.fromJsonString(OpenAIResponsesBody))
-const transportBase = {
-  endpoint: Endpoint.path<OpenAIResponsesBody>(PATH),
-  auth: Auth.bearer(),
-  encodeBody,
-}
-const routeDefaults = {
-  baseURL: DEFAULT_BASE_URL,
-}
+const endpoint = Endpoint.path<OpenAIResponsesBody>(PATH, { baseURL: DEFAULT_BASE_URL })
+const auth = Auth.none
 
-export const httpTransport = HttpTransport.httpJson({
-  ...transportBase,
-  framing: Framing.sse,
-})
+export const httpTransport = HttpTransport.sseJson.with<OpenAIResponsesBody>()
 
 export const route = Route.make({
   id: ADAPTER,
   provider: "openai",
   protocol,
+  endpoint,
+  auth,
   transport: httpTransport,
-  defaults: routeDefaults,
 })
 
 const decodeWebSocketMessage = ProviderShared.validateWith(Schema.decodeUnknownEffect(OpenAIResponsesWebSocketMessage))
@@ -569,8 +579,10 @@ const webSocketMessage = (body: OpenAIResponsesBody | Record<string, unknown>) =
     return yield* decodeWebSocketMessage({ ...message, type: "response.create" })
   })
 
-export const webSocketTransport = WebSocketTransport.json({
-  ...transportBase,
+export const webSocketTransport = WebSocketTransport.jsonTransport.with<
+  OpenAIResponsesBody,
+  OpenAIResponsesWebSocketMessage
+>({
   toMessage: webSocketMessage,
   encodeMessage: encodeWebSocketMessage,
 })
@@ -579,15 +591,9 @@ export const webSocketRoute = Route.make({
   id: `${ADAPTER}-websocket`,
   provider: "openai",
   protocol,
+  endpoint,
+  auth,
   transport: webSocketTransport,
-  defaults: routeDefaults,
 })
 
-// =============================================================================
-// Model Helper
-// =============================================================================
-export const model = route.model
-
-export const webSocketModel = webSocketRoute.model
-
 export * as OpenAIResponses from "./openai-responses"

packages/llm/src/protocols/shared.ts

@@ -11,6 +11,7 @@ import {
   type MediaPart,
   type ToolResultPart,
 } from "../schema"
+export { isRecord } from "../utils/record"
 
 export const Json = Schema.fromJsonString(Schema.Unknown)
 export const decodeJson = Schema.decodeUnknownSync(Json)
@@ -19,13 +20,6 @@ export const JsonObject = Schema.Record(Schema.String, Schema.Unknown)
 export const optionalArray = <const S extends Schema.Top>(schema: S) => Schema.optional(Schema.Array(schema))
 export const optionalNull = <const S extends Schema.Top>(schema: S) => Schema.optional(Schema.NullOr(schema))
 
-/**
- * Plain-record narrowing. Excludes arrays so routes checking nested JSON
- * Schema fragments don't accidentally treat a tuple as a key/value bag.
- */
-export const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null && !Array.isArray(value)
-
 /**
  * Streaming tool-call accumulator. Adapters that build a tool call across
  * multiple `tool-input-delta` chunks store the partial JSON input string here
@@ -132,6 +126,7 @@ export const trimBaseUrl = (value: string) => value.replace(/\/+$/, "")
 
 export const toolResultText = (part: ToolResultPart) => {
   if (part.result.type === "text" || part.result.type === "error") return String(part.result.value)
+  if (part.result.type === "content") return encodeJson(part.result.value)
   return encodeJson(part.result.value)
 }
 

packages/llm/src/protocols/utils/bedrock-auth.ts

@@ -1,15 +1,14 @@
 import { AwsV4Signer } from "aws4fetch"
-import { Effect, Option, Schema } from "effect"
+import { Effect } from "effect"
 import { Headers } from "effect/unstable/http"
 import { Auth, type AuthInput } from "../../route/auth"
-import type { LLMRequest } from "../../schema"
 import { ProviderShared } from "../shared"
 
 /**
- * AWS credentials for SigV4 signing. Bedrock also supports Bearer API key auth
- * via `model.apiKey`, which bypasses SigV4 signing. STS-vended credentials
- * should be refreshed by the consumer (rebuild the model) before they expire;
- * the route does not refresh.
+ * AWS credentials for SigV4 signing. Bedrock also supports Bearer API key auth,
+ * which provider facades configure as route auth instead of SigV4. STS-vended
+ * credentials should be refreshed by the consumer (rebuild the model) before
+ * they expire; the route does not refresh.
  */
 export interface Credentials {
   readonly region: string
@@ -18,32 +17,6 @@ export interface Credentials {
   readonly sessionToken?: string
 }
 
-const NativeCredentials = Schema.Struct({
-  accessKeyId: Schema.String,
-  secretAccessKey: Schema.String,
-  region: Schema.optional(Schema.String),
-  sessionToken: Schema.optional(Schema.String),
-})
-
-const decodeNativeCredentials = Schema.decodeUnknownOption(NativeCredentials)
-
-export const region = (request: LLMRequest) => {
-  const fromNative = request.model.native?.aws_region
-  if (typeof fromNative === "string" && fromNative !== "") return fromNative
-  return (
-    decodeNativeCredentials(request.model.native?.aws_credentials).pipe(
-      Option.map((credentials) => credentials.region),
-      Option.getOrUndefined,
-    ) ?? "us-east-1"
-  )
-}
-
-const credentialsFromInput = (request: LLMRequest): Credentials | undefined =>
-  decodeNativeCredentials(request.model.native?.aws_credentials).pipe(
-    Option.map((creds) => ({ ...creds, region: creds.region ?? region(request) })),
-    Option.getOrUndefined,
-  )
-
 const signRequest = (input: {
   readonly url: string
   readonly body: string
@@ -71,33 +44,27 @@ const signRequest = (input: {
       ),
   })
 
-/**
- * Bedrock auth. `model.apiKey` (Bedrock's newer Bearer API key auth) wins if
- * set; otherwise sign the exact JSON bytes with SigV4 using credentials from
- * `model.native.aws_credentials`.
- */
-export const auth = Auth.custom((input: AuthInput) => {
-  if (input.request.model.apiKey) return Auth.toEffect(Auth.bearer())(input)
-  return Effect.gen(function* () {
-    const credentials = credentialsFromInput(input.request)
-    if (!credentials) {
-      return yield* ProviderShared.invalidRequest(
-        "Bedrock Converse requires either model.apiKey or AWS credentials in model.native.aws_credentials",
-      )
-    }
-    const headersForSigning = Headers.set(input.headers, "content-type", "application/json")
-    const signed = yield* signRequest({ url: input.url, body: input.body, headers: headersForSigning, credentials })
-    return Headers.setAll(headersForSigning, signed)
-  })
-})
-
-export const nativeCredentials = (native: Record<string, unknown> | undefined, credentials: Credentials | undefined) =>
-  credentials
-    ? {
-        ...native,
-        aws_credentials: credentials,
-        aws_region: credentials.region,
+/** Sign the exact JSON bytes with SigV4 using credentials configured on the route. */
+export const sigV4 = (credentials: Credentials | undefined) =>
+  Auth.custom((input: AuthInput) => {
+    return Effect.gen(function* () {
+      if (!credentials) {
+        return yield* ProviderShared.invalidRequest(
+          "Bedrock Converse requires either route bearer auth or AWS credentials configured on the route",
+        )
       }
-    : native
+      const headersForSigning = Headers.set(input.headers, "content-type", "application/json")
+      const signed = yield* signRequest({
+        url: input.url,
+        body: input.body,
+        headers: headersForSigning,
+        credentials,
+      })
+      return Headers.setAll(headersForSigning, signed)
+    })
+  })
+
+/** Bedrock route auth defaults to SigV4 and expects credentials from route configuration. */
+export const auth = sigV4(undefined)
 
 export * as BedrockAuth from "./bedrock-auth"

packages/llm/src/provider.ts

@@ -1,14 +1,20 @@
-import type { RouteModelInput } from "./route/client"
-import type { ModelID, ModelRef, ProviderID } from "./schema"
+import type { RouteDefaultsInput } from "./route/client"
+import type { Model, ModelID, ProviderID } from "./schema"
 
-export type ModelOptions = Omit<RouteModelInput, "id">
+export type ModelOptions = RouteDefaultsInput
 
+/**
+ * Advanced structural provider definition helper. Built-in providers should
+ * prefer explicit `configure(options).model(id)` facades so deployment config is
+ * chosen before model selection. The optional `apis` map remains for external
+ * structural providers that expose multiple route selectors behind one provider.
+ */
 export type ModelFactory<Options extends ModelOptions = ModelOptions> = (
   id: string | ModelID,
   options?: Options,
-) => ModelRef
+) => Model
 
-type AnyModelFactory = (...args: never[]) => ModelRef
+type AnyModelFactory = (...args: never[]) => Model
 
 export interface Definition<Factory extends AnyModelFactory = ModelFactory> {
   readonly id: ProviderID
@@ -18,8 +24,8 @@ export interface Definition<Factory extends AnyModelFactory = ModelFactory> {
 
 type DefinitionShape = {
   readonly id: ProviderID
-  readonly model: (...args: never[]) => ModelRef
-  readonly apis?: Record<string, (...args: never[]) => ModelRef>
+  readonly model: (...args: never[]) => Model
+  readonly apis?: Record<string, (...args: never[]) => Model>
 }
 
 type NoExtraFields<Input, Shape> = Input & Record<Exclude<keyof Input, keyof Shape>, never>

packages/llm/src/providers/amazon-bedrock.ts

@@ -1,12 +1,12 @@
-import { Route, type RouteModelInput } from "../route/client"
-import { Provider } from "../provider"
+import type { RouteDefaultsInput } from "../route/client"
+import { Auth } from "../route/auth"
 import { ProviderID, type ModelID } from "../schema"
 import * as BedrockConverse from "../protocols/bedrock-converse"
 import type { BedrockCredentials } from "../protocols/bedrock-converse"
 
 export const id = ProviderID.make("amazon-bedrock")
 
-export type ModelOptions = Omit<RouteModelInput, "id" | "baseURL"> & {
+export type Config = RouteDefaultsInput & {
   readonly apiKey?: string
   readonly headers?: Record<string, string>
   readonly credentials?: BedrockCredentials
@@ -15,34 +15,29 @@ export type ModelOptions = Omit<RouteModelInput, "id" | "baseURL"> & {
   /** Override the computed `https://bedrock-runtime.<region>.amazonaws.com` URL. */
   readonly baseURL?: string
 }
-type ModelInput = ModelOptions & Pick<RouteModelInput, "id">
-
 export const routes = [BedrockConverse.route]
 
 const bedrockBaseURL = (region: string) => `https://bedrock-runtime.${region}.amazonaws.com`
 
-const converseModel = Route.model<ModelInput>(
-  BedrockConverse.route,
-  {
-    provider: "amazon-bedrock",
-  },
-  {
-    mapInput: (input) => {
-      const { credentials, region, baseURL, ...rest } = input
-      const resolvedRegion = region ?? credentials?.region ?? "us-east-1"
-      return {
-        ...rest,
-        baseURL: baseURL ?? bedrockBaseURL(resolvedRegion),
-        native: BedrockConverse.nativeCredentials(input.native, credentials),
-      }
-    },
-  },
-)
+const configuredRoute = (input: Config) => {
+  const { apiKey, credentials, region, baseURL, ...rest } = input
+  const resolvedRegion = region ?? credentials?.region ?? "us-east-1"
+  return BedrockConverse.route.with({
+    ...rest,
+    provider: id,
+    endpoint: { baseURL: baseURL ?? bedrockBaseURL(resolvedRegion) },
+    auth: apiKey === undefined ? BedrockConverse.sigV4Auth(credentials) : Auth.bearer(apiKey),
+  })
+}
 
-export const model = (modelID: string | ModelID, options: ModelOptions = {}) =>
-  converseModel({ ...options, id: modelID })
+export const configure = (input: Config = {}) => {
+  const route = configuredRoute(input)
+  return {
+    id,
+    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    configure,
+  }
+}
 
-export const provider = Provider.make({
-  id,
-  model,
-})
+export const provider = configure()
+export const model = provider.model

packages/llm/src/providers/anthropic.ts

@@ -1,5 +1,6 @@
-import type { RouteModelInput } from "../route/client"
-import { Provider } from "../provider"
+import type { RouteDefaultsInput } from "../route/client"
+import { Auth } from "../route/auth"
+import type { ProviderAuthOption } from "../route/auth-options"
 import { ProviderID, type ModelID } from "../schema"
 import * as AnthropicMessages from "../protocols/anthropic-messages"
 
@@ -7,12 +8,28 @@ export const id = ProviderID.make("anthropic")
 
 export const routes = [AnthropicMessages.route]
 
-export const model = (
-  id: string | ModelID,
-  options: Omit<RouteModelInput, "id" | "baseURL"> & { readonly baseURL?: string } = {},
-) => AnthropicMessages.model({ ...options, id })
+export type Config = RouteDefaultsInput & ProviderAuthOption<"optional"> & { readonly baseURL?: string }
 
-export const provider = Provider.make({
-  id,
-  model,
-})
+const auth = (options: ProviderAuthOption<"optional">) => {
+  if ("auth" in options && options.auth) return options.auth
+  return Auth.optional("apiKey" in options ? options.apiKey : undefined, "apiKey")
+    .orElse(Auth.config("ANTHROPIC_API_KEY"))
+    .pipe(Auth.header("x-api-key"))
+}
+
+const configuredRoute = (input: Config) => {
+  const { apiKey: _, auth: _auth, baseURL, ...rest } = input
+  return AnthropicMessages.route.with({ ...rest, endpoint: { baseURL }, auth: auth(input) })
+}
+
+export const configure = (input: Config = {}) => {
+  const route = configuredRoute(input)
+  return {
+    id,
+    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    configure,
+  }
+}
+
+export const provider = configure()
+export const model = provider.model

packages/llm/src/providers/azure.ts

@@ -1,83 +1,110 @@
 import { Auth } from "../route/auth"
 import { type AtLeastOne, type ProviderAuthOption } from "../route/auth-options"
-import { Route } from "../route/client"
-import type { ModelInput } from "../llm"
-import { Provider } from "../provider"
+import type { Route as RouteDef, RouteDefaultsInput } from "../route/client"
 import { ProviderID, type ModelID } from "../schema"
 import * as OpenAIChat from "../protocols/openai-chat"
 import * as OpenAIResponses from "../protocols/openai-responses"
 import { withOpenAIOptions, type OpenAIProviderOptionsInput } from "./openai-options"
 
 export const id = ProviderID.make("azure")
-const routeAuth = Auth.remove("authorization").andThen(Auth.apiKeyHeader("api-key"))
+const routeAuth = Auth.remove("authorization")
 
 // Azure needs the customer's resource URL; supply either `resourceName`
 // (helper builds the URL) or `baseURL` directly.
 type AzureURL = AtLeastOne<{ readonly resourceName: string; readonly baseURL: string }>
 
 export type ModelOptions = AzureURL &
-  Omit<ModelInput, "id" | "provider" | "route" | "apiKey" | "auth" | "baseURL"> &
+  RouteDefaultsInput &
   ProviderAuthOption<"optional"> & {
     readonly apiVersion?: string
+    readonly queryParams?: Record<string, string>
     readonly useCompletionUrls?: boolean
     readonly providerOptions?: OpenAIProviderOptionsInput
   }
-type AzureModelInput = ModelOptions & Pick<ModelInput, "id">
+export type Config = ModelOptions
 
 const resourceBaseURL = (resourceName: string) => `https://${resourceName.trim()}.openai.azure.com/openai/v1`
 
 const responsesRoute = OpenAIResponses.route.with({
   id: "azure-openai-responses",
   provider: id,
-  transport: OpenAIResponses.httpTransport.with({ auth: routeAuth }),
+  auth: routeAuth,
+  endpoint: {
+    query: { "api-version": "v1" },
+  },
 })
 
 const chatRoute = OpenAIChat.route.with({
   id: "azure-openai-chat",
   provider: id,
-  transport: OpenAIChat.httpTransport.with({ auth: routeAuth }),
+  auth: routeAuth,
+  endpoint: {
+    query: { "api-version": "v1" },
+  },
 })
 
 export const routes = [responsesRoute, chatRoute]
 
-const mapInput = (input: AzureModelInput) => {
-  const { apiKey: _, apiVersion, resourceName, useCompletionUrls, ...rest } = input
-  return {
-    ...withOpenAIOptions(input.id, rest),
-    auth:
-      "auth" in input && input.auth
-        ? input.auth
-        : Auth.remove("authorization").andThen(
-            Auth.optional("apiKey" in input ? input.apiKey : undefined, "apiKey")
-              .orElse(Auth.config("AZURE_OPENAI_API_KEY"))
-              .pipe(Auth.header("api-key")),
-          ),
-    // AtLeastOne guarantees at least one is set; baseURL wins if both are.
-    baseURL: rest.baseURL ?? resourceBaseURL(resourceName!),
-    queryParams: {
-      ...rest.queryParams,
-      "api-version": apiVersion ?? rest.queryParams?.["api-version"] ?? "v1",
+const defaults = (input: Config) => {
+  const {
+    apiKey: _,
+    apiVersion: _apiVersion,
+    resourceName: _resourceName,
+    useCompletionUrls: _useCompletionUrls,
+    baseURL: _baseURL,
+    queryParams: _queryParams,
+    ...rest
+  } = input
+  if ("auth" in rest) {
+    const { auth: _, ...withoutAuth } = rest
+    return withoutAuth
+  }
+  return rest
+}
+
+const auth = (input: Config) => {
+  if ("auth" in input && input.auth) return input.auth
+  return Auth.remove("authorization").andThen(
+    Auth.optional("apiKey" in input ? input.apiKey : undefined, "apiKey")
+      .orElse(Auth.config("AZURE_OPENAI_API_KEY"))
+      .pipe(Auth.header("api-key")),
+  )
+}
+
+const configuredRoute = <Body, Prepared>(route: RouteDef<Body, Prepared>, input: Config) =>
+  route.with({
+    auth: auth(input),
+    endpoint: {
+      // AtLeastOne guarantees at least one is set; baseURL wins if both are.
+      baseURL: input.baseURL ?? resourceBaseURL(input.resourceName!),
+      query: {
+        ...(input.apiVersion ? { "api-version": input.apiVersion } : {}),
+        ...input.queryParams,
+      },
     },
+  })
+
+export const configure = (input: Config) => {
+  const configuredResponsesRoute = configuredRoute(responsesRoute, input)
+  const configuredChatRoute = configuredRoute(chatRoute, input)
+  const modelDefaults = defaults(input)
+
+  const responses = (modelID: string | ModelID) =>
+    configuredResponsesRoute.with(withOpenAIOptions(modelID, modelDefaults)).model({ id: modelID })
+
+  const chat = (modelID: string | ModelID) =>
+    configuredChatRoute.with(withOpenAIOptions(modelID, modelDefaults)).model({ id: modelID })
+
+  return {
+    id,
+    model: (modelID: string | ModelID) => (input.useCompletionUrls === true ? chat(modelID) : responses(modelID)),
+    responses,
+    chat,
+    configure,
   }
 }
 
-const chatModel = Route.model<AzureModelInput>(chatRoute, {}, { mapInput })
-const responsesModel = Route.model<AzureModelInput>(responsesRoute, {}, { mapInput })
-
-export const responses = (modelID: string | ModelID, options: ModelOptions) =>
-  responsesModel({ ...options, id: modelID })
-
-export const chat = (modelID: string | ModelID, options: ModelOptions) => chatModel({ ...options, id: modelID })
-
-export const model = (modelID: string | ModelID, options: ModelOptions) => {
-  if (options.useCompletionUrls === true) return chat(modelID, options)
-  return responses(modelID, options)
-}
-
-export const provider = Provider.make({
+export const provider = {
   id,
-  model,
-  apis: { responses, chat },
-})
-
-export const apis = provider.apis
+  configure,
+}

packages/llm/src/providers/cloudflare.ts

@@ -1,19 +1,16 @@
 import type { Config, Redacted } from "effect"
-import { type ModelInput } from "../llm"
-import { Provider } from "../provider"
 import * as OpenAICompatibleChat from "../protocols/openai-compatible-chat"
 import { Auth } from "../route/auth"
 import { AuthOptions, type AtLeastOne, type ProviderAuthOption } from "../route/auth-options"
-import { Route } from "../route/client"
+import type { RouteDefaultsInput } from "../route/client"
 import { ProviderID, type ModelID } from "../schema"
 
 export const aiGatewayID = ProviderID.make("cloudflare-ai-gateway")
 export const workersAIID = ProviderID.make("cloudflare-workers-ai")
-export const id = aiGatewayID
 export const aiGatewayAuthEnvVars = ["CLOUDFLARE_API_TOKEN", "CF_AIG_TOKEN"] as const
 export const workersAIAuthEnvVars = ["CLOUDFLARE_API_KEY", "CLOUDFLARE_WORKERS_AI_TOKEN"] as const
 
-type CloudflareSecret = string | Redacted.Redacted<string> | Config.Config<string | Redacted.Redacted<string>>
+type CloudflareSecret = string | Redacted.Redacted | Config.Config<string | Redacted.Redacted>
 
 type GatewayURL = AtLeastOne<{
   readonly accountId: string
@@ -23,32 +20,26 @@ type GatewayURL = AtLeastOne<{
 }
 
 export type AIGatewayOptions = GatewayURL &
-  Omit<ModelInput, "id" | "provider" | "route" | "baseURL" | "apiKey" | "auth"> &
+  RouteDefaultsInput &
   ProviderAuthOption<"optional"> & {
     /** Cloudflare AI Gateway authentication token. Sent as `cf-aig-authorization`. */
     readonly gatewayApiKey?: CloudflareSecret
   }
 
-type AIGatewayInput = AIGatewayOptions & Pick<ModelInput, "id">
-
 type WorkersAIURL = AtLeastOne<{
   readonly accountId: string
   readonly baseURL: string
 }>
 
-export type WorkersAIOptions = WorkersAIURL &
-  Omit<ModelInput, "id" | "provider" | "route" | "baseURL" | "apiKey" | "auth"> &
-  ProviderAuthOption<"optional">
-
-type WorkersAIInput = WorkersAIOptions & Pick<ModelInput, "id">
+export type WorkersAIOptions = WorkersAIURL & RouteDefaultsInput & ProviderAuthOption<"optional">
 
 export const aiGatewayBaseURL = (input: GatewayURL) => {
   if (input.baseURL) return input.baseURL
-  if (!input.accountId) throw new Error("Cloudflare.aiGateway requires accountId unless baseURL is supplied")
+  if (!input.accountId) throw new Error("CloudflareAIGateway.configure requires accountId unless baseURL is supplied")
   return `https://gateway.ai.cloudflare.com/v1/${encodeURIComponent(input.accountId)}/${encodeURIComponent(input.gatewayId?.trim() || "default")}/compat`
 }
 
-const aiGatewayAuth = (input: AIGatewayInput) => {
+const aiGatewayAuth = (input: AIGatewayOptions) => {
   if ("auth" in input && input.auth) return input.auth
   const gateway = Auth.optional(input.gatewayApiKey, "gatewayApiKey")
     .orElse(Auth.config("CLOUDFLARE_API_TOKEN"))
@@ -61,11 +52,11 @@ const aiGatewayAuth = (input: AIGatewayInput) => {
 
 export const workersAIBaseURL = (input: WorkersAIURL) => {
   if (input.baseURL) return input.baseURL
-  if (!input.accountId) throw new Error("Cloudflare.workersAI requires accountId unless baseURL is supplied")
+  if (!input.accountId) throw new Error("CloudflareWorkersAI.configure requires accountId unless baseURL is supplied")
   return `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(input.accountId)}/ai/v1`
 }
 
-const workersAIAuth = (input: WorkersAIInput) => {
+const workersAIAuth = (input: WorkersAIOptions) => {
   return AuthOptions.bearer(input, workersAIAuthEnvVars)
 }
 
@@ -81,59 +72,56 @@ export const workersAIRoute = OpenAICompatibleChat.route.with({
 
 export const routes = [aiGatewayRoute, workersAIRoute]
 
-const aiGatewayModel = Route.model<AIGatewayInput>(
-  aiGatewayRoute,
-  {
-    provider: id,
-  },
-  {
-    mapInput: (input) => {
-      const {
-        accountId: _accountId,
-        gatewayId: _gatewayId,
-        apiKey: _apiKey,
-        gatewayApiKey: _gatewayApiKey,
-        auth: _auth,
-        ...rest
-      } = input
-      return {
-        ...rest,
-        auth: aiGatewayAuth(input),
-        baseURL: aiGatewayBaseURL(input),
-      }
-    },
-  },
-)
+const aiGatewayDefaults = (options: AIGatewayOptions) => {
+  const {
+    accountId: _accountId,
+    gatewayId: _gatewayId,
+    apiKey: _apiKey,
+    gatewayApiKey: _gatewayApiKey,
+    baseURL: _baseURL,
+    auth: _auth,
+    ...rest
+  } = options
+  return rest
+}
 
-const workersAIModel = Route.model<WorkersAIInput>(
-  workersAIRoute,
-  {
-    provider: workersAIID,
-  },
-  {
-    mapInput: (input) => {
-      const { accountId: _accountId, apiKey: _apiKey, auth: _auth, ...rest } = input
-      return {
-        ...rest,
-        auth: workersAIAuth(input),
-        baseURL: workersAIBaseURL(input),
-      }
-    },
-  },
-)
+const workersAIDefaults = (options: WorkersAIOptions) => {
+  const { accountId: _accountId, apiKey: _apiKey, auth: _auth, baseURL: _baseURL, ...rest } = options
+  return rest
+}
 
-export const aiGateway = (modelID: string | ModelID, options: AIGatewayOptions) =>
-  aiGatewayModel({ ...options, id: modelID })
+const configureAIGateway = (options: AIGatewayOptions) => {
+  const route = aiGatewayRoute.with({
+    ...aiGatewayDefaults(options),
+    endpoint: { baseURL: aiGatewayBaseURL(options) },
+    auth: aiGatewayAuth(options),
+  })
+  return {
+    id: aiGatewayID,
+    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    configure: configureAIGateway,
+  }
+}
 
-export const workersAI = (modelID: string | ModelID, options: WorkersAIOptions) =>
-  workersAIModel({ ...options, id: modelID })
+const configureWorkersAI = (options: WorkersAIOptions) => {
+  const route = workersAIRoute.with({
+    ...workersAIDefaults(options),
+    endpoint: { baseURL: workersAIBaseURL(options) },
+    auth: workersAIAuth(options),
+  })
+  return {
+    id: workersAIID,
+    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    configure: configureWorkersAI,
+  }
+}
 
-export const model = aiGateway
+export const CloudflareAIGateway = {
+  id: aiGatewayID,
+  configure: configureAIGateway,
+}
 
-export const provider = Provider.make({
-  id,
-  model,
-  apis: { aiGateway, workersAI },
-})
-
-export const apis = provider.apis
+export const CloudflareWorkersAI = {
+  id: workersAIID,
+  configure: configureWorkersAI,
+}

packages/llm/src/providers/github-copilot.ts

@@ -1,6 +1,5 @@
-import { Route } from "../route/client"
-import type { ModelInput } from "../llm"
-import { Provider } from "../provider"
+import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
+import type { RouteDefaultsInput } from "../route/client"
 import { ProviderID, type ModelID } from "../schema"
 import * as OpenAIChat from "../protocols/openai-chat"
 import * as OpenAIResponses from "../protocols/openai-responses"
@@ -10,10 +9,11 @@ export const id = ProviderID.make("github-copilot")
 
 // GitHub Copilot has no canonical public URL — callers (opencode, etc.) must
 // supply `baseURL` explicitly.
-export type ModelOptions = Omit<ModelInput, "id" | "provider" | "route"> & {
-  readonly providerOptions?: OpenAIProviderOptionsInput
-}
-type CopilotModelInput = ModelOptions & Pick<ModelInput, "id">
+export type ModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
+  ProviderAuthOption<"optional"> & {
+    readonly baseURL: string
+    readonly providerOptions?: OpenAIProviderOptionsInput
+  }
 
 export const shouldUseResponsesApi = (modelID: string | ModelID) => {
   const model = String(modelID)
@@ -24,25 +24,43 @@ export const shouldUseResponsesApi = (modelID: string | ModelID) => {
 
 export const routes = [OpenAIResponses.route, OpenAIChat.route]
 
-const mapInput = (input: CopilotModelInput) => withOpenAIOptions(input.id, input)
+const chatRoute = OpenAIChat.route.with({ provider: id })
+const responsesRoute = OpenAIResponses.route.with({ provider: id })
 
-const chatModel = Route.model<CopilotModelInput>(OpenAIChat.route, { provider: id }, { mapInput })
-const responsesModel = Route.model<CopilotModelInput>(OpenAIResponses.route, { provider: id }, { mapInput })
-
-export const responses = (modelID: string | ModelID, options: ModelOptions) =>
-  responsesModel({ ...options, id: modelID })
-
-export const chat = (modelID: string | ModelID, options: ModelOptions) => chatModel({ ...options, id: modelID })
-
-export const model = (modelID: string | ModelID, options: ModelOptions) => {
-  const create = shouldUseResponsesApi(modelID) ? responsesModel : chatModel
-  return create({ ...options, id: modelID })
+const defaults = (options: ModelOptions) => {
+  const { apiKey: _, auth: _auth, baseURL: _baseURL, ...rest } = options
+  return rest
 }
 
-export const provider = Provider.make({
-  id,
-  model,
-  apis: { responses, chat },
-})
+const configuredResponsesRoute = (options: ModelOptions) =>
+  responsesRoute.with({
+    endpoint: { baseURL: options.baseURL },
+    auth: AuthOptions.bearer(options, []),
+  })
 
-export const apis = provider.apis
+const configuredChatRoute = (options: ModelOptions) =>
+  chatRoute.with({
+    endpoint: { baseURL: options.baseURL },
+    auth: AuthOptions.bearer(options, []),
+  })
+
+export const configure = (options: ModelOptions) => {
+  const responsesRoute = configuredResponsesRoute(options)
+  const chatRoute = configuredChatRoute(options)
+  const responses = (modelID: string | ModelID) =>
+    responsesRoute.with(withOpenAIOptions(modelID, defaults(options))).model({ id: modelID })
+  const chat = (modelID: string | ModelID) =>
+    chatRoute.with(withOpenAIOptions(modelID, defaults(options))).model({ id: modelID })
+  return {
+    id,
+    model: (modelID: string | ModelID) => (shouldUseResponsesApi(modelID) ? responses(modelID) : chat(modelID)),
+    responses,
+    chat,
+    configure,
+  }
+}
+
+export const provider = {
+  id,
+  configure,
+}

packages/llm/src/providers/google.ts

@@ -1,5 +1,6 @@
-import type { RouteModelInput } from "../route/client"
-import { Provider } from "../provider"
+import type { RouteDefaultsInput } from "../route/client"
+import { Auth } from "../route/auth"
+import type { ProviderAuthOption } from "../route/auth-options"
 import { ProviderID, type ModelID } from "../schema"
 import * as Gemini from "../protocols/gemini"
 
@@ -7,12 +8,28 @@ export const id = ProviderID.make("google")
 
 export const routes = [Gemini.route]
 
-export const model = (
-  id: string | ModelID,
-  options: Omit<RouteModelInput, "id" | "baseURL"> & { readonly baseURL?: string } = {},
-) => Gemini.model({ ...options, id })
+export type Config = RouteDefaultsInput & ProviderAuthOption<"optional"> & { readonly baseURL?: string }
 
-export const provider = Provider.make({
-  id,
-  model,
-})
+const auth = (options: ProviderAuthOption<"optional">) => {
+  if ("auth" in options && options.auth) return options.auth
+  return Auth.optional("apiKey" in options ? options.apiKey : undefined, "apiKey")
+    .orElse(Auth.config("GOOGLE_GENERATIVE_AI_API_KEY"))
+    .pipe(Auth.header("x-goog-api-key"))
+}
+
+const configuredRoute = (input: Config) => {
+  const { apiKey: _, auth: _auth, baseURL, ...rest } = input
+  return Gemini.route.with({ ...rest, endpoint: { baseURL }, auth: auth(input) })
+}
+
+export const configure = (input: Config = {}) => {
+  const route = configuredRoute(input)
+  return {
+    id,
+    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    configure,
+  }
+}
+
+export const provider = configure()
+export const model = provider.model

packages/llm/src/providers/index.ts

@@ -2,6 +2,7 @@ export * as Anthropic from "./anthropic"
 export * as AmazonBedrock from "./amazon-bedrock"
 export * as Azure from "./azure"
 export * as Cloudflare from "./cloudflare"
+export { CloudflareAIGateway, CloudflareWorkersAI } from "./cloudflare"
 export * as GitHubCopilot from "./github-copilot"
 export * as Google from "./google"
 export * as OpenAI from "./openai"

packages/llm/src/providers/openai-compatible.ts

@@ -1,56 +1,60 @@
-import { Provider } from "../provider"
 import { ProviderID, type ModelID } from "../schema"
 import * as OpenAICompatibleChat from "../protocols/openai-compatible-chat"
-import type { OpenAICompatibleChatModelInput } from "../protocols/openai-compatible-chat"
+import type { RouteDefaultsInput } from "../route/client"
+import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
 import { profiles, type OpenAICompatibleProfile } from "./openai-compatible-profile"
 
 export const id = ProviderID.make("openai-compatible")
 
-export type ModelOptions = Omit<OpenAICompatibleChatModelInput, "id" | "provider"> & {
-  readonly provider: string
-}
+type GenericModelOptions = RouteDefaultsInput &
+  ProviderAuthOption<"optional"> & {
+    readonly provider?: string
+    readonly baseURL: string
+  }
 
-type GenericModelOptions = Omit<ModelOptions, "provider"> & {
-  readonly provider?: string
-}
-
-export type FamilyModelOptions = Omit<OpenAICompatibleChatModelInput, "id" | "provider" | "baseURL"> & {
-  readonly baseURL?: string
-}
+export type FamilyModelOptions = RouteDefaultsInput &
+  ProviderAuthOption<"optional"> & {
+    readonly baseURL?: string
+  }
 
 export const routes = [OpenAICompatibleChat.route]
 
-export const model = (id: string | ModelID, options: ModelOptions) => {
-  return OpenAICompatibleChat.model({
-    ...options,
-    id,
-    provider: ProviderID.make(options.provider),
+export const configure = (input: GenericModelOptions) => {
+  const provider = input.provider ?? "openai-compatible"
+  const { provider: _, baseURL, apiKey: _apiKey, auth: _auth, ...rest } = input
+  const route = OpenAICompatibleChat.route.with({
+    ...rest,
+    provider,
+    endpoint: { baseURL },
+    auth: AuthOptions.bearer(input, []),
   })
+  return {
+    id: ProviderID.make(provider),
+    model: (modelID: string | ModelID) => route.model({ id: modelID, provider: ProviderID.make(provider) }),
+    configure,
+  }
 }
 
-export const profileModel = (
-  profile: OpenAICompatibleProfile,
-  id: string | ModelID,
-  options: FamilyModelOptions = {},
-) =>
-  OpenAICompatibleChat.model({
-    ...options,
-    id,
-    provider: profile.provider,
-    baseURL: options.baseURL ?? profile.baseURL,
-  })
+const define = (profile: OpenAICompatibleProfile) => {
+  const configureProfile = (input: FamilyModelOptions = {}) => {
+    const facade = configure({
+      ...input,
+      baseURL: input.baseURL ?? profile.baseURL,
+      provider: profile.provider,
+    })
+    return {
+      id: ProviderID.make(profile.provider),
+      model: facade.model,
+      configure: configureProfile,
+    }
+  }
+  return configureProfile()
+}
 
-const define = (profile: OpenAICompatibleProfile) =>
-  Provider.make({
-    id: ProviderID.make(profile.provider),
-    model: (id: string | ModelID, options: FamilyModelOptions = {}) => profileModel(profile, id, options),
-  })
-
-export const provider = Provider.make({
+export const provider = {
   id,
-  model: (id: string | ModelID, options: GenericModelOptions) =>
-    model(id, { ...options, provider: options.provider ?? "openai-compatible" }),
-})
+  configure,
+}
 
 export const baseten = define(profiles.baseten)
 export const cerebras = define(profiles.cerebras)

packages/llm/src/providers/openai-options.ts

@@ -59,10 +59,9 @@ export const withOpenAIOptions = <Options extends { readonly providerOptions?: O
   modelID: string,
   options: Options,
   defaults: { readonly textVerbosity?: boolean } = {},
-): Options & { readonly id: string; readonly providerOptions?: ProviderOptions } => {
+): Omit<Options, "providerOptions"> & { readonly providerOptions?: ProviderOptions } => {
   return {
     ...options,
-    id: modelID,
     providerOptions: mergeProviderOptions(openAIDefaultOptions(modelID, defaults), options.providerOptions),
   }
 }

packages/llm/src/providers/openai.ts

@@ -1,6 +1,5 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
-import type { RouteModelInput } from "../route/client"
-import { Provider } from "../provider"
+import type { Route, RouteDefaultsInput } from "../route/client"
 import { ProviderID, type ModelID } from "../schema"
 import * as OpenAIChat from "../protocols/openai-chat"
 import * as OpenAIResponses from "../protocols/openai-responses"
@@ -15,39 +14,50 @@ export const routes = [OpenAIResponses.route, OpenAIResponses.webSocketRoute, Op
 // This provider facade wraps the lower-level Responses and Chat model factories
 // with OpenAI-specific conveniences: typed options, API-key sugar, env fallback,
 // and default option normalization.
-type OpenAIModelInput<ModelInput> = Omit<ModelInput, "apiKey" | "auth" | "baseURL"> &
+export type Config = RouteDefaultsInput &
   ProviderAuthOption<"optional"> & {
     readonly baseURL?: string
+    readonly queryParams?: Record<string, string>
     readonly providerOptions?: OpenAIProviderOptionsInput
   }
 
 const auth = (options: ProviderAuthOption<"optional">) => AuthOptions.bearer(options, "OPENAI_API_KEY")
 
-export const responses = (id: string | ModelID, options: OpenAIModelInput<Omit<RouteModelInput, "id">> = {}) => {
-  const { apiKey: _, ...rest } = options
-  return OpenAIResponses.model(withOpenAIOptions(id, { ...rest, auth: auth(options) }, { textVerbosity: true }))
+const defaults = (input: Config) => {
+  const { apiKey: _, auth: _auth, baseURL: _baseURL, queryParams: _queryParams, ...rest } = input
+  return rest
 }
 
-export const responsesWebSocket = (
-  id: string | ModelID,
-  options: OpenAIModelInput<Omit<RouteModelInput, "id">> = {},
-) => {
-  const { apiKey: _, ...rest } = options
-  return OpenAIResponses.webSocketModel(
-    withOpenAIOptions(id, { ...rest, auth: auth(options) }, { textVerbosity: true }),
-  )
+const configuredRoute = <Body, Prepared>(route: Route<Body, Prepared>, input: Config) =>
+  route.with({
+    auth: auth(input),
+    endpoint: { baseURL: input.baseURL, query: input.queryParams },
+  })
+
+export const configure = (input: Config = {}) => {
+  const responsesRoute = configuredRoute(OpenAIResponses.route, input)
+  const responsesWebSocketRoute = configuredRoute(OpenAIResponses.webSocketRoute, input)
+  const chatRoute = configuredRoute(OpenAIChat.route, input)
+  const modelDefaults = defaults(input)
+  const responses = (id: string | ModelID) =>
+    responsesRoute.with(withOpenAIOptions(id, modelDefaults, { textVerbosity: true })).model({ id })
+  const responsesWebSocket = (id: string | ModelID) =>
+    responsesWebSocketRoute.with(withOpenAIOptions(id, modelDefaults, { textVerbosity: true })).model({ id })
+  const chat = (id: string | ModelID) => chatRoute.with(withOpenAIOptions(id, modelDefaults)).model({ id })
+
+  return {
+    id,
+    model: responses,
+    responses,
+    responsesWebSocket,
+    chat,
+    configure,
+  }
 }
 
-export const chat = (id: string | ModelID, options: OpenAIModelInput<Omit<RouteModelInput, "id">> = {}) => {
-  const { apiKey: _, ...rest } = options
-  return OpenAIChat.model(withOpenAIOptions(id, { ...rest, auth: auth(options) }))
-}
-
-export const provider = Provider.make({
-  id,
-  model: responses,
-  apis: { responses, responsesWebSocket, chat },
-})
+export const provider = configure()
 
 export const model = provider.model
-export const apis = provider.apis
+export const responses = provider.responses
+export const responsesWebSocket = provider.responsesWebSocket
+export const chat = provider.chat

packages/llm/src/providers/openrouter.ts

@@ -1,9 +1,9 @@
 import { Effect, Schema } from "effect"
-import { Route, type RouteModelInput } from "../route/client"
+import { Route, type RouteDefaultsInput } from "../route/client"
 import { Endpoint } from "../route/endpoint"
 import { Framing } from "../route/framing"
-import { Provider } from "../provider"
 import { Protocol } from "../route/protocol"
+import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
 import { ProviderID, type ModelID, type ProviderOptions } from "../schema"
 import * as OpenAICompatibleProfiles from "./openai-compatible-profile"
 import * as OpenAIChat from "../protocols/openai-chat"
@@ -24,11 +24,11 @@ export type OpenRouterProviderOptionsInput = ProviderOptions & {
   readonly openrouter?: OpenRouterOptions
 }
 
-export type ModelOptions = Omit<RouteModelInput, "id" | "baseURL" | "providerOptions"> & {
-  readonly baseURL?: string
-  readonly providerOptions?: OpenRouterProviderOptionsInput
-}
-type ModelInput = ModelOptions & Pick<RouteModelInput, "id">
+export type ModelOptions = Omit<RouteDefaultsInput, "providerOptions"> &
+  ProviderAuthOption<"optional"> & {
+    readonly baseURL?: string
+    readonly providerOptions?: OpenRouterProviderOptionsInput
+  }
 
 const OpenRouterBody = Schema.StructWithRest(Schema.Struct(OpenAIChat.bodyFields), [
   Schema.Record(Schema.String, Schema.Any),
@@ -68,21 +68,31 @@ const bodyOptions = (input: unknown) => {
 
 export const route = Route.make({
   id: ADAPTER,
+  provider: profile.provider,
   protocol,
-  endpoint: Endpoint.path("/chat/completions"),
+  endpoint: Endpoint.path("/chat/completions", { baseURL: profile.baseURL }),
   framing: Framing.sse,
 })
 
 export const routes = [route]
 
-const modelRef = Route.model<ModelInput>(route, {
-  provider: profile.provider,
-  baseURL: profile.baseURL,
-})
+const configuredRoute = (input: ModelOptions) => {
+  const { apiKey: _, auth: _auth, baseURL, ...rest } = input
+  return route.with({
+    ...rest,
+    endpoint: { baseURL: baseURL ?? profile.baseURL },
+    auth: AuthOptions.bearer(input, "OPENROUTER_API_KEY"),
+  })
+}
 
-export const model = (id: string | ModelID, options: ModelOptions = {}) => modelRef({ ...options, id })
+export const configure = (input: ModelOptions = {}) => {
+  const route = configuredRoute(input)
+  return {
+    id,
+    model: (modelID: string | ModelID) => route.model({ id: modelID }),
+    configure,
+  }
+}
 
-export const provider = Provider.make({
-  id,
-  model,
-})
+export const provider = configure()
+export const model = provider.model

packages/llm/src/providers/xai.ts

@@ -1,7 +1,5 @@
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
-import { Route } from "../route/client"
-import type { RouteModelInput } from "../route/client"
-import { Provider } from "../provider"
+import type { RouteDefaultsInput } from "../route/client"
 import { ProviderID, type ModelID } from "../schema"
 import * as OpenAICompatibleProfiles from "./openai-compatible-profile"
 import * as OpenAICompatibleChat from "../protocols/openai-compatible-chat"
@@ -9,44 +7,50 @@ import * as OpenAIResponses from "../protocols/openai-responses"
 
 export const id = ProviderID.make("xai")
 
-export type ModelOptions = Omit<RouteModelInput, "id" | "apiKey" | "auth" | "baseURL"> &
+export type ModelOptions = RouteDefaultsInput &
   ProviderAuthOption<"optional"> & {
     readonly baseURL?: string
   }
 
 export const routes = [OpenAIResponses.route, OpenAICompatibleChat.route]
 
-const responsesModel = Route.model(OpenAIResponses.route, { provider: id })
-const chatModel = OpenAICompatibleChat.model
-
 const auth = (options: ProviderAuthOption<"optional">) => AuthOptions.bearer(options, "XAI_API_KEY")
 
-export const responses = (modelID: string | ModelID, options: ModelOptions = {}) => {
-  const { apiKey: _, ...rest } = options
-  return responsesModel({
+const configuredResponsesRoute = (input: ModelOptions) => {
+  const { apiKey: _, auth: _auth, baseURL, ...rest } = input
+  return OpenAIResponses.route.with({
     ...rest,
-    auth: auth(options),
-    id: modelID,
-    baseURL: options.baseURL ?? OpenAICompatibleProfiles.profiles.xai.baseURL,
-  })
-}
-
-export const chat = (modelID: string | ModelID, options: ModelOptions = {}) => {
-  const { apiKey: _, ...rest } = options
-  return chatModel({
-    ...rest,
-    auth: auth(options),
-    id: modelID,
     provider: id,
-    baseURL: options.baseURL ?? OpenAICompatibleProfiles.profiles.xai.baseURL,
+    endpoint: { baseURL: baseURL ?? OpenAICompatibleProfiles.profiles.xai.baseURL },
+    auth: auth(input),
   })
 }
 
-export const provider = Provider.make({
-  id,
-  model: responses,
-  apis: { responses, chat },
-})
+const configuredChatRoute = (input: ModelOptions) => {
+  const { apiKey: _, auth: _auth, baseURL, ...rest } = input
+  return OpenAICompatibleChat.route.with({
+    ...rest,
+    provider: id,
+    endpoint: { baseURL: baseURL ?? OpenAICompatibleProfiles.profiles.xai.baseURL },
+    auth: auth(input),
+  })
+}
 
+export const configure = (input: ModelOptions = {}) => {
+  const responsesRoute = configuredResponsesRoute(input)
+  const chatRoute = configuredChatRoute(input)
+  const responses = (modelID: string | ModelID) => responsesRoute.model({ id: modelID })
+  const chat = (modelID: string | ModelID) => chatRoute.model({ id: modelID })
+  return {
+    id,
+    model: responses,
+    responses,
+    chat,
+    configure,
+  }
+}
+
+export const provider = configure()
 export const model = provider.model
-export const apis = provider.apis
+export const responses = provider.responses
+export const chat = provider.chat

packages/llm/src/route/auth.ts

@@ -12,6 +12,7 @@ export class MissingCredentialError extends Error {
 
 export type CredentialError = MissingCredentialError | Config.ConfigError
 export type AuthError = CredentialError | LLMError
+type Secret = string | Redacted.Redacted | Config.Config<string | Redacted.Redacted>
 
 export interface AuthInput {
   readonly request: LLMRequest
@@ -22,7 +23,7 @@ export interface AuthInput {
 }
 
 export interface Credential {
-  readonly load: Effect.Effect<Redacted.Redacted<string>, CredentialError>
+  readonly load: Effect.Effect<Redacted.Redacted, CredentialError>
   readonly orElse: (that: Credential) => Credential
   readonly bearer: () => Auth
   readonly header: (name: string) => Auth
@@ -39,7 +40,7 @@ export interface Auth {
 export const isAuth = (input: unknown): input is Auth =>
   typeof input === "object" && input !== null && "apply" in input && typeof input.apply === "function"
 
-const credential = (load: Effect.Effect<Redacted.Redacted<string>, CredentialError>): Credential => {
+const credential = (load: Effect.Effect<Redacted.Redacted, CredentialError>): Credential => {
   const self: Credential = {
     load,
     orElse: (that) => credential(load.pipe(Effect.catch(() => that.load))),
@@ -66,16 +67,13 @@ const fromCredential = (source: Credential, render: (secret: string) => Headers.
     source.load.pipe(Effect.map((secret) => Headers.setAll(input.headers, render(Redacted.value(secret))))),
   )
 
-const secretEffect = (secret: string | Redacted.Redacted<string>, source: string) => {
+const secretEffect = (secret: string | Redacted.Redacted, source: string) => {
   const redacted = typeof secret === "string" ? Redacted.make(secret) : secret
   if (Redacted.value(redacted) === "") return Effect.fail(new MissingCredentialError(source))
   return Effect.succeed(redacted)
 }
 
-const credentialFromSecret = (
-  secret: string | Redacted.Redacted<string> | Config.Config<string | Redacted.Redacted<string>>,
-  source: string,
-) => {
+const credentialFromSecret = (secret: Secret, source: string) => {
   if (typeof secret === "string" || Redacted.isRedacted(secret)) return credential(secretEffect(secret, source))
   return credential(
     Effect.gen(function* () {
@@ -86,17 +84,14 @@ const credentialFromSecret = (
 
 export const value = (secret: string, source = "value") => credentialFromSecret(secret, source)
 
-export const optional = (
-  secret: string | Redacted.Redacted<string> | Config.Config<string | Redacted.Redacted<string>> | undefined,
-  source = "optional value",
-) =>
+export const optional = (secret: Secret | undefined, source = "optional value") =>
   secret === undefined
     ? credential(Effect.fail(new MissingCredentialError(source)))
     : credentialFromSecret(secret, source)
 
 export const config = (name: string) => credentialFromSecret(Config.redacted(name), name)
 
-export const effect = (load: Effect.Effect<Redacted.Redacted<string>, CredentialError>) => credential(load)
+export const effect = (load: Effect.Effect<Redacted.Redacted, CredentialError>) => credential(load)
 
 export const none = auth((input) => Effect.succeed(input.headers))
 
@@ -109,68 +104,32 @@ export const custom = (apply: (input: AuthInput) => Effect.Effect<Headers.Header
 
 export const passthrough = none
 
-const fromModelApiKey = (from: (apiKey: string) => Headers.Input) =>
-  auth(({ request, headers }) => {
-    const key = request.model.apiKey
-    if (!key) return Effect.succeed(headers)
-    return Effect.succeed(Headers.setAll(headers, from(key)))
-  })
-
-const credentialInput = (
-  source: string | Redacted.Redacted<string> | Config.Config<string | Redacted.Redacted<string>> | Credential,
-) =>
+const credentialInput = (source: Secret | Credential) =>
   typeof source === "string" || Redacted.isRedacted(source) || Config.isConfig(source)
     ? credentialFromSecret(source, "value")
     : source
 
-export function bearer(): Auth
-export function bearer(
-  source: string | Redacted.Redacted<string> | Config.Config<string | Redacted.Redacted<string>> | Credential,
-): Auth
-export function bearer(
-  source?: string | Redacted.Redacted<string> | Config.Config<string | Redacted.Redacted<string>> | Credential,
-) {
-  if (source === undefined) return fromModelApiKey((key) => ({ authorization: `Bearer ${key}` }))
+export function bearer(source: Secret | Credential): Auth
+export function bearer(source: Secret | Credential) {
   return credentialInput(source).bearer()
 }
 
 export const apiKey = bearer
 
-export const apiKeyHeader = (name: string) => fromModelApiKey((key) => ({ [name]: key }))
-
-export function header(
-  name: string,
-): (source: string | Redacted.Redacted<string> | Config.Config<string | Redacted.Redacted<string>> | Credential) => Auth
-export function header(
-  name: string,
-  source: string | Redacted.Redacted<string> | Config.Config<string | Redacted.Redacted<string>> | Credential,
-): Auth
-export function header(
-  name: string,
-  source?: string | Redacted.Redacted<string> | Config.Config<string | Redacted.Redacted<string>> | Credential,
-) {
+export function header(name: string): (source: Secret | Credential) => Auth
+export function header(name: string, source: Secret | Credential): Auth
+export function header(name: string, source?: Secret | Credential) {
   if (source === undefined) {
-    return (
-      next: string | Redacted.Redacted<string> | Config.Config<string | Redacted.Redacted<string>> | Credential,
-    ) => credentialInput(next).header(name)
+    return (next: Secret | Credential) => credentialInput(next).header(name)
   }
   return credentialInput(source).header(name)
 }
 
-export function bearerHeader(
-  name: string,
-): (source: string | Redacted.Redacted<string> | Config.Config<string | Redacted.Redacted<string>> | Credential) => Auth
-export function bearerHeader(
-  name: string,
-  source: string | Redacted.Redacted<string> | Config.Config<string | Redacted.Redacted<string>> | Credential,
-): Auth
-export function bearerHeader(
-  name: string,
-  source?: string | Redacted.Redacted<string> | Config.Config<string | Redacted.Redacted<string>> | Credential,
-) {
-  const render = (
-    input: string | Redacted.Redacted<string> | Config.Config<string | Redacted.Redacted<string>> | Credential,
-  ) => fromCredential(credentialInput(input), (secret) => ({ [name]: `Bearer ${secret}` }))
+export function bearerHeader(name: string): (source: Secret | Credential) => Auth
+export function bearerHeader(name: string, source: Secret | Credential): Auth
+export function bearerHeader(name: string, source?: Secret | Credential) {
+  const render = (input: Secret | Credential) =>
+    fromCredential(credentialInput(input), (secret) => ({ [name]: `Bearer ${secret}` }))
   if (source === undefined) return render
   return render(source)
 }

packages/llm/src/route/client.ts

@@ -1,31 +1,28 @@
 import { Cause, Context, Effect, Layer, Schema, Stream } from "effect"
-import type { Auth as AuthDef } from "./auth"
-import type { Endpoint } from "./endpoint"
+import * as Option from "effect/Option"
+import { Auth, type Auth as AuthDef } from "./auth"
+import { Endpoint, type EndpointPatch } from "./endpoint"
 import { RequestExecutor } from "./executor"
 import type { Framing } from "./framing"
 import { HttpTransport } from "./transport"
 import type { Transport, TransportRuntime } from "./transport"
 import { WebSocketExecutor } from "./transport"
-import type { Service as WebSocketExecutorService } from "./transport/websocket"
 import type { Protocol } from "./protocol"
 import { applyCachePolicy } from "../cache-policy"
 import * as ProviderShared from "../protocols/shared"
 import * as ToolRuntime from "../tool-runtime"
 import type { Tools } from "../tool"
-import type { LLMError, LLMEvent, PreparedRequestOf, ProtocolID } from "../schema"
+import type { LLMError, LLMEvent, PreparedRequestOf, ProtocolID, ProviderOptions } from "../schema"
 import {
   GenerationOptions,
   HttpOptions,
   LLMRequest,
   LLMResponse,
-  ModelID,
+  Model,
   ModelLimits,
-  ModelRef,
   LLMError as LLMErrorClass,
-  NoRouteReason,
   PreparedRequest,
   ProviderID,
-  RouteID,
   mergeGenerationOptions,
   mergeHttpOptions,
   mergeProviderOptions,
@@ -42,11 +39,13 @@ export interface Route<Body, Prepared = unknown> {
   readonly id: string
   readonly provider?: ProviderID
   readonly protocol: ProtocolID
+  readonly endpoint: Endpoint<Body>
+  readonly auth: AuthDef
   readonly transport: Transport<Body, Prepared, unknown>
   readonly defaults: RouteDefaults
   readonly body: RouteBody<Body>
   readonly with: (patch: RoutePatch<Body, Prepared>) => Route<Body, Prepared>
-  readonly model: <Input extends RouteModelInput = RouteModelInput>(input: Input) => ModelRef
+  readonly model: (input: RouteMappedModelInput) => Model
   readonly prepareTransport: (body: Body, request: LLMRequest) => Effect.Effect<Prepared, LLMError>
   readonly streamPrepared: (
     prepared: Prepared,
@@ -61,116 +60,77 @@ export interface Route<Body, Prepared = unknown> {
 // oxlint-disable-next-line typescript-eslint/no-explicit-any
 export type AnyRoute = Route<any, any>
 
-const routeRegistry = new Map<string, AnyRoute>()
-
-// Route lookup is intentionally global: model refs name a route id, and
-// importing the provider/protocol/custom-route module registers the runnable
-// implementation. Duplicate ids are bugs because model refs cannot disambiguate
-// them.
-const register = <R extends AnyRoute>(route: R): R => {
-  const existing = routeRegistry.get(route.id)
-  if (existing && existing !== route) throw new Error(`Duplicate LLM route id "${route.id}"`)
-  routeRegistry.set(route.id, route)
-  return route
-}
-
-const registeredRoute = (id: string) => routeRegistry.get(id)
-
 export type HttpOptionsInput = HttpOptions.Input
 
-export type ModelRefInput = Omit<
-  ConstructorParameters<typeof ModelRef>[0],
-  "id" | "provider" | "route" | "limits" | "generation" | "http" | "auth"
-> & {
-  readonly id: string | ModelID
-  readonly provider: string | ProviderID
-  readonly route: string | RouteID
-  readonly auth?: AuthDef
+export type RouteModelInput = Omit<Model.Input, "provider" | "route">
+
+export type RouteRoutedModelInput = Omit<Model.Input, "route">
+
+export interface RouteDefaults {
+  readonly headers?: Record<string, string>
+  readonly limits?: ModelLimits
+  readonly generation?: GenerationOptions
+  readonly providerOptions?: ProviderOptions
+  readonly http?: HttpOptions
+}
+
+export interface RouteDefaultsInput {
+  readonly headers?: Record<string, string>
   readonly limits?: ModelLimits.Input
   readonly generation?: GenerationOptions.Input
-  readonly http?: HttpOptionsInput
+  readonly providerOptions?: ProviderOptions
+  readonly http?: HttpOptions.Input
 }
 
-// `baseURL` is required on `ModelRefInput` (every materialized `ModelRef` has
-// a host) but optional at the route-input layers below. The route's `defaults`
-// can supply a canonical URL (e.g. OpenAI/Anthropic) so the user's input may
-// omit it. Routes without a canonical URL (OpenAI-compatible, GitHub Copilot)
-// re-tighten this in their own input type.
-export type RouteModelInput = Omit<ModelRefInput, "provider" | "route" | "baseURL"> & {
-  readonly baseURL?: string
-}
-
-export type RouteModelDefaults = Omit<ModelRefInput, "id" | "route" | "baseURL"> & {
-  readonly baseURL?: string
-}
-
-export type RouteRoutedModelInput = Omit<ModelRefInput, "route" | "baseURL"> & {
-  readonly baseURL?: string
-}
-
-export type RouteRoutedModelDefaults = Partial<Omit<ModelRefInput, "id" | "provider" | "route">>
-
-export type RouteDefaults = Partial<Omit<ModelRefInput, "id" | "provider" | "route">>
-
-export interface RoutePatch<Body, Prepared> extends RouteDefaults {
-  readonly id: string
+export interface RoutePatch<Body, Prepared> extends RouteDefaultsInput {
+  readonly id?: string
   readonly provider?: string | ProviderID
+  readonly auth?: AuthDef
   readonly transport?: Transport<Body, Prepared, unknown>
+  readonly endpoint?: EndpointPatch<Body>
 }
 
 type RouteMappedModelInput = RouteModelInput | RouteRoutedModelInput
 
-export interface RouteModelOptions<
-  Input extends RouteMappedModelInput,
-  Output extends RouteMappedModelInput = RouteMappedModelInput,
-> {
-  readonly mapInput?: (input: Input) => Output
+const makeRouteModel = (route: AnyRoute, mapped: RouteMappedModelInput) => {
+  const provider = route.provider ?? ("provider" in mapped ? mapped.provider : undefined)
+  if (!provider) throw new Error(`Route.model(${route.id}) requires a provider`)
+  if (!endpointBaseURL(route.endpoint))
+    throw new Error(`Route.model(${route.id}) requires an endpoint baseURL — configure it on the route first`)
+  return Model.make({
+    ...mapped,
+    provider,
+    route,
+  })
 }
 
-export interface RouteMappedModelOptions<Input, Output extends RouteMappedModelInput = RouteMappedModelInput> {
-  readonly mapInput: (input: Input) => Output
-}
-
-const modelWithDefaults =
-  <Input>(
-    route: AnyRoute,
-    defaults: Partial<Omit<ModelRefInput, "id" | "route">>,
-    options: { readonly mapInput?: (input: Input) => RouteMappedModelInput },
-  ) =>
-  (input: Input) => {
-    const mapped = options.mapInput === undefined ? (input as RouteMappedModelInput) : options.mapInput(input)
-    const provider = defaults.provider ?? route.provider ?? ("provider" in mapped ? mapped.provider : undefined)
-    if (!provider) throw new Error(`Route.model(${route.id}) requires a provider`)
-    const baseURL = mapped.baseURL ?? defaults.baseURL ?? route.defaults.baseURL
-    if (!baseURL)
-      throw new Error(`Route.model(${route.id}) requires a baseURL — supply it via input, defaults, or route defaults`)
-    const generation = mergeGenerationOptions(route.defaults.generation, defaults.generation)
-    const providerOptions = mergeProviderOptions(route.defaults.providerOptions, defaults.providerOptions)
-    const http = mergeHttpOptions(httpOptions(route.defaults.http), httpOptions(defaults.http))
-    return modelRef({
-      ...route.defaults,
-      ...defaults,
-      ...mapped,
-      baseURL,
-      provider,
-      route: route.id,
-      limits: mapped.limits ?? defaults.limits ?? route.defaults.limits,
-      generation: mergeGenerationOptions(generation, mapped.generation),
-      providerOptions: mergeProviderOptions(providerOptions, mapped.providerOptions),
-      http: mergeHttpOptions(http, httpOptions(mapped.http)),
-    })
+const mergeRouteDefaults = (base: RouteDefaults | undefined, patch: RouteDefaultsInput): RouteDefaults => {
+  const headers = mergeHeaders(base?.headers, patch.headers)
+  return {
+    ...base,
+    ...patch,
+    headers,
+    limits: patch.limits === undefined ? base?.limits : ModelLimits.make(patch.limits),
+    generation: mergeGenerationOptions(generationOptions(base?.generation), generationOptions(patch.generation)),
+    providerOptions: mergeProviderOptions(base?.providerOptions, patch.providerOptions),
+    http: mergeHttpOptions(
+      base?.http,
+      httpOptions(patch.http),
+      headers === undefined ? undefined : new HttpOptions({ headers }),
+    ),
   }
+}
 
-const mergeRouteDefaults = (base: RouteDefaults | undefined, patch: RouteDefaults): RouteDefaults => ({
-  ...base,
-  ...patch,
-  limits: patch.limits ?? base?.limits,
-  generation: mergeGenerationOptions(generationOptions(base?.generation), generationOptions(patch.generation)),
-  providerOptions: mergeProviderOptions(base?.providerOptions, patch.providerOptions),
-  http: mergeHttpOptions(httpOptions(base?.http), httpOptions(patch.http)),
-})
+const endpointBaseURL = <Body>(endpoint: Endpoint<Body>) =>
+  typeof endpoint.baseURL === "string" ? endpoint.baseURL : undefined
 
-export const modelLimits = ModelLimits.make
+const mergeHeaders = (...items: ReadonlyArray<Record<string, string> | undefined>) => {
+  const entries = items.flatMap((item) =>
+    item === undefined ? [] : Object.entries(item).filter((entry): entry is [string, string] => entry[1] !== undefined),
+  )
+  if (entries.length === 0) return undefined
+  return Object.fromEntries(entries)
+}
 
 export const generationOptions = (input: GenerationOptions.Input | undefined) =>
   input === undefined ? undefined : GenerationOptions.make(input)
@@ -180,40 +140,6 @@ export const httpOptions = (input: HttpOptionsInput | undefined) => {
   return HttpOptions.make(input)
 }
 
-export const modelRef = (input: ModelRefInput) =>
-  new ModelRef({
-    ...input,
-    id: ModelID.make(input.id),
-    provider: ProviderID.make(input.provider),
-    route: RouteID.make(input.route),
-    limits: modelLimits(input.limits),
-    generation: generationOptions(input.generation),
-    http: httpOptions(input.http),
-  })
-
-function model<Input extends RouteModelInput = RouteModelInput>(
-  route: AnyRoute,
-  defaults: RouteModelDefaults,
-  options?: RouteModelOptions<Input, RouteModelInput>,
-): (input: Input) => ModelRef
-function model<Input extends RouteRoutedModelInput = RouteRoutedModelInput>(
-  route: AnyRoute,
-  defaults?: RouteRoutedModelDefaults,
-  options?: RouteModelOptions<Input, RouteRoutedModelInput>,
-): (input: Input) => ModelRef
-function model<Input, Output extends RouteMappedModelInput = RouteMappedModelInput>(
-  route: AnyRoute,
-  defaults: Partial<Omit<ModelRefInput, "id" | "route">>,
-  options: RouteMappedModelOptions<Input, Output>,
-): (input: Input) => ModelRef
-function model<Input>(
-  route: AnyRoute,
-  defaults: Partial<Omit<ModelRefInput, "id" | "route">> = {},
-  options: { readonly mapInput?: (input: Input) => RouteMappedModelInput } = {},
-) {
-  return modelWithDefaults(route, defaults, options)
-}
-
 export interface Interface {
   /**
    * Compile a request through protocol body construction, validation, and HTTP
@@ -242,22 +168,16 @@ export interface GenerateMethod {
 
 export class Service extends Context.Service<Service, Interface>()("@opencode/LLMClient") {}
 
-const noRoute = (model: ModelRef) =>
-  new LLMErrorClass({
-    module: "LLMClient",
-    method: "resolveRoute",
-    reason: new NoRouteReason({ route: model.route, provider: model.provider, model: model.id }),
-  })
-
 const resolveRequestOptions = (request: LLMRequest) =>
   LLMRequest.update(request, {
-    generation: mergeGenerationOptions(request.model.generation, request.generation) ?? new GenerationOptions({}),
-    providerOptions: mergeProviderOptions(request.model.providerOptions, request.providerOptions),
-    http: mergeHttpOptions(request.model.http, request.http),
+    generation:
+      mergeGenerationOptions(request.model.route.defaults.generation, request.generation) ?? new GenerationOptions({}),
+    providerOptions: mergeProviderOptions(request.model.route.defaults.providerOptions, request.providerOptions),
+    http: mergeHttpOptions(request.model.route.defaults.http, request.http),
   })
 
 export interface MakeInput<Body, Frame, Event, State> {
-  /** Route id used in registry lookup and error messages. */
+  /** Route id used in diagnostics and prepared request metadata. */
   readonly id: string
   /** Provider identity for route-owned model construction. */
   readonly provider?: string | ProviderID
@@ -265,27 +185,33 @@ export interface MakeInput<Body, Frame, Event, State> {
   readonly protocol: Protocol<Body, Frame, Event, State>
   /** Where the request is sent. */
   readonly endpoint: Endpoint<Body>
-  /** Per-request transport auth. Model-level `Auth` overrides this. */
+  /** Per-request transport auth. Provider facades override this via `route.with(...)`. */
   readonly auth?: AuthDef
   /** Stream framing — bytes -> frames before `protocol.stream.event` decoding. */
   readonly framing: Framing<Frame>
   /** Static / per-request headers added before `auth` runs. */
   readonly headers?: (input: { readonly request: LLMRequest }) => Record<string, string>
-  /** Model defaults used by the route's `.model(...)` helper. */
-  readonly defaults?: RouteDefaults
+  /** Route/request defaults used when compiling requests for this route. */
+  readonly defaults?: RouteDefaultsInput
 }
 
 export interface MakeTransportInput<Body, Prepared, Frame, Event, State> {
-  /** Route id used in registry lookup and error messages. */
+  /** Route id used in diagnostics and prepared request metadata. */
   readonly id: string
   /** Provider identity for route-owned model construction. */
   readonly provider?: string | ProviderID
   /** Semantic API contract — owns body construction, body schema, and parsing. */
   readonly protocol: Protocol<Body, Frame, Event, State>
+  /** Where the request is sent. */
+  readonly endpoint: Endpoint<Body>
+  /** Per-request transport auth. Provider facades override this via `route.with(...)`. */
+  readonly auth?: AuthDef
+  /** Static / per-request headers added before `auth` runs. */
+  readonly headers?: (input: { readonly request: LLMRequest }) => Record<string, string>
   /** Runnable transport route. */
   readonly transport: Transport<Body, Prepared, Frame>
-  /** Provider/model defaults used by the route's `.model(...)` helper. */
-  readonly defaults?: RouteDefaults
+  /** Route/request defaults used when compiling requests for this route. */
+  readonly defaults?: RouteDefaultsInput
 }
 
 const streamError = (route: string, message: string, cause: Cause.Cause<unknown>) => {
@@ -298,6 +224,7 @@ function makeFromTransport<Body, Prepared, Frame, Event, State>(
   input: MakeTransportInput<Body, Prepared, Frame, Event, State>,
 ): Route<Body, Prepared> {
   const protocol = input.protocol
+  const encodeBody = Schema.encodeSync(Schema.fromJsonString(protocol.body.schema))
   const decodeEventEffect = Schema.decodeUnknownEffect(protocol.stream.event)
   const decodeEvent = (route: string) => (frame: Frame) =>
     decodeEventEffect(frame).pipe(
@@ -310,29 +237,44 @@ function makeFromTransport<Body, Prepared, Frame, Event, State>(
       ),
     )
 
-  const build = (routeInput: MakeTransportInput<Body, Prepared, Frame, Event, State>): Route<Body, Prepared> => {
+  type BuiltRouteInput = Omit<MakeTransportInput<Body, Prepared, Frame, Event, State>, "defaults"> & {
+    readonly defaults?: RouteDefaults
+  }
+
+  const build = (routeInput: BuiltRouteInput): Route<Body, Prepared> => {
     const route: Route<Body, Prepared> = {
       id: routeInput.id,
       provider: routeInput.provider === undefined ? undefined : ProviderID.make(routeInput.provider),
       protocol: protocol.id,
+      endpoint: routeInput.endpoint,
+      auth: routeInput.auth ?? Auth.none,
       transport: routeInput.transport,
       defaults: routeInput.defaults ?? {},
       body: protocol.body,
       with: (patch: RoutePatch<Body, Prepared>) => {
-        const { id, provider, transport, ...defaults } = patch
-        if (!id || id === routeInput.id) throw new Error(`Route.with(${routeInput.id}) requires a new route id`)
+        const { id, provider, auth, transport, endpoint, ...defaults } = patch
         return build({
           ...routeInput,
-          id,
+          id: id ?? routeInput.id,
           provider: provider ?? routeInput.provider,
+          auth: auth ?? routeInput.auth,
+          endpoint: endpoint ? Endpoint.merge(routeInput.endpoint, endpoint) : routeInput.endpoint,
           transport: (transport as Transport<Body, Prepared, Frame> | undefined) ?? routeInput.transport,
-          defaults: mergeRouteDefaults(routeInput.defaults, defaults),
+          defaults: mergeRouteDefaults(route.defaults, defaults),
         })
       },
-      model: (input: RouteModelInput): ModelRef => modelWithDefaults<RouteModelInput>(route, {}, {})(input),
-      prepareTransport: routeInput.transport.prepare,
+      model: (input) => makeRouteModel(route, input),
+      prepareTransport: (body, request) =>
+        routeInput.transport.prepare({
+          body,
+          request,
+          endpoint: routeInput.endpoint,
+          auth: routeInput.auth ?? Auth.none,
+          encodeBody,
+          headers: routeInput.headers,
+        }),
       streamPrepared: (prepared: Prepared, request: LLMRequest, runtime: TransportRuntime) => {
-        const route = `${request.model.provider}/${request.model.route}`
+        const route = `${request.model.provider}/${request.model.route.id}`
         const events = routeInput.transport
           .frames(prepared, request, runtime)
           .pipe(
@@ -349,10 +291,10 @@ function makeFromTransport<Body, Prepared, Frame, Event, State>(
         )
       },
     } satisfies Route<Body, Prepared>
-    return register(route)
+    return route
   }
 
-  return build(input)
+  return build({ ...input, defaults: mergeRouteDefaults(undefined, input.defaults ?? {}) })
 }
 
 export function make<Body, Prepared, Frame, Event, State>(
@@ -381,18 +323,14 @@ export function make<Body, Prepared, Frame, Event, State>(
 ): Route<Body, Prepared> | Route<Body, HttpTransport.HttpPrepared<Frame>> {
   if ("transport" in input) return makeFromTransport(input)
   const protocol = input.protocol
-  const encodeBody = Schema.encodeSync(Schema.fromJsonString(protocol.body.schema))
   return makeFromTransport({
     id: input.id,
     provider: input.provider,
     protocol,
-    transport: HttpTransport.httpJson({
-      endpoint: input.endpoint,
-      auth: input.auth,
-      framing: input.framing,
-      encodeBody,
-      headers: input.headers,
-    }),
+    endpoint: input.endpoint,
+    auth: input.auth,
+    headers: input.headers,
+    transport: HttpTransport.httpJson({ framing: input.framing }),
     defaults: input.defaults,
   })
 }
@@ -402,8 +340,7 @@ export function make<Body, Prepared, Frame, Event, State>(
 // execute transport.
 const compile = Effect.fn("LLM.compile")(function* (request: LLMRequest) {
   const resolved = applyCachePolicy(resolveRequestOptions(request))
-  const route = registeredRoute(resolved.model.route)
-  if (!route) return yield* noRoute(resolved.model)
+  const route = resolved.model.route
 
   const body = yield* route.body
     .from(resolved)
@@ -495,31 +432,21 @@ export const streamRequest = (request: LLMRequest) =>
 export const layer: Layer.Layer<Service, never, RequestExecutor.Service> = Layer.effect(
   Service,
   Effect.gen(function* () {
-    const stream = streamWith(streamRequestWith({ http: yield* RequestExecutor.Service }))
+    const stream = streamWith(
+      streamRequestWith({
+        http: yield* RequestExecutor.Service,
+        webSocket: Option.getOrUndefined(yield* Effect.serviceOption(WebSocketExecutor.Service)),
+      }),
+    )
     return Service.of({ prepare: prepareWith as Interface["prepare"], stream, generate: generateWith(stream) })
   }),
 )
 
-export const layerWithWebSocket: Layer.Layer<Service, never, RequestExecutor.Service | WebSocketExecutorService> =
-  Layer.effect(
-    Service,
-    Effect.gen(function* () {
-      const stream = streamWith(
-        streamRequestWith({
-          http: yield* RequestExecutor.Service,
-          webSocket: yield* WebSocketExecutor.Service,
-        }),
-      )
-      return Service.of({ prepare: prepareWith as Interface["prepare"], stream, generate: generateWith(stream) })
-    }),
-  )
-
-export const Route = { make, model } as const
+export const Route = { make } as const
 
 export const LLMClient = {
   Service,
   layer,
-  layerWithWebSocket,
   prepare,
   stream,
   generate,

packages/llm/src/route/endpoint.ts

@@ -11,28 +11,42 @@ export type EndpointPart<Body> = string | ((input: EndpointInput<Body>) => strin
 /**
  * Declarative URL construction for one route.
  *
- * `Endpoint` carries only the path. The host always lives on `model.baseURL`,
- * supplied by the provider helper that constructs the model. `render(...)`
- * just appends the path (and any `model.queryParams`) to that host.
+ * `Endpoint` carries URL construction for one route. Routes with a canonical
+ * host put `baseURL` here; provider helpers can override it by configuring the
+ * route before selecting a model.
  *
  * `path` may be a string or a function of `EndpointInput`, for routes whose
  * URL embeds the model id, region, or another body field (e.g. Bedrock,
  * Gemini).
  */
 export interface Endpoint<Body> {
+  readonly baseURL?: string
   readonly path: EndpointPart<Body>
+  readonly query?: Record<string, string>
 }
 
+export type EndpointPatch<Body> = Partial<Endpoint<Body>>
+
 /** Construct an `Endpoint` from a path string or path function. */
-export const path = <Body>(value: EndpointPart<Body>): Endpoint<Body> => ({ path: value })
+export const path = <Body>(value: EndpointPart<Body>, options: Omit<Endpoint<Body>, "path"> = {}): Endpoint<Body> => ({
+  ...options,
+  path: value,
+})
+
+export const merge = <Body>(base: Endpoint<Body>, patch: EndpointPatch<Body>): Endpoint<Body> => ({
+  ...base,
+  ...patch,
+  baseURL: patch.baseURL ?? base.baseURL,
+  path: patch.path ?? base.path,
+  query: patch.query === undefined ? base.query : { ...base.query, ...patch.query },
+})
 
 const renderPart = <Body>(part: EndpointPart<Body>, input: EndpointInput<Body>) =>
   typeof part === "function" ? part(input) : part
 
 export const render = <Body>(endpoint: Endpoint<Body>, input: EndpointInput<Body>) => {
-  const url = new URL(`${ProviderShared.trimBaseUrl(input.request.model.baseURL)}${renderPart(endpoint.path, input)}`)
-  const params = input.request.model.queryParams
-  if (params) for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value)
+  const url = new URL(`${ProviderShared.trimBaseUrl(endpoint.baseURL ?? "")}${renderPart(endpoint.path, input)}`)
+  for (const [key, value] of Object.entries(endpoint.query ?? {})) url.searchParams.set(key, value)
   return url
 }
 

packages/llm/src/route/index.ts

@@ -1,14 +1,13 @@
-export { Route, LLMClient, modelLimits, modelRef } from "./client"
+export { Route, LLMClient } from "./client"
 export type {
   Route as RouteShape,
-  RouteModelDefaults,
   RouteModelInput,
-  RouteRoutedModelDefaults,
   RouteRoutedModelInput,
+  RouteDefaults,
+  RouteDefaultsInput,
   AnyRoute,
   Interface as LLMClientShape,
   Service as LLMClientService,
-  ModelRefInput,
 } from "./client"
 export * from "./executor"
 export { Auth } from "./auth"

packages/llm/src/route/transport/http.ts

@@ -1,20 +1,13 @@
 import { Effect, Stream } from "effect"
 import { Headers, HttpClientRequest } from "effect/unstable/http"
-import { Auth, type Auth as AuthDef } from "../auth"
-import { type Endpoint, render as renderEndpoint } from "../endpoint"
-import type { Framing } from "../framing"
-import type { Transport } from "./index"
+import { Auth } from "../auth"
+import { render as renderEndpoint } from "../endpoint"
+import { Framing, type Framing as FramingDef } from "../framing"
+import type { Transport, TransportPrepareInput } from "./index"
 import * as ProviderShared from "../../protocols/shared"
 import { mergeJsonRecords, type LLMRequest } from "../../schema"
 
-export interface JsonRequestInput<Body> {
-  readonly body: Body
-  readonly request: LLMRequest
-  readonly endpoint: Endpoint<Body>
-  readonly auth: AuthDef
-  readonly encodeBody: (body: Body) => string
-  readonly headers?: (input: { readonly request: LLMRequest }) => Record<string, string>
-}
+export type JsonRequestInput<Body> = TransportPrepareInput<Body>
 
 export interface JsonRequestParts<Body = unknown> {
   readonly url: string
@@ -25,7 +18,7 @@ export interface JsonRequestParts<Body = unknown> {
 
 export interface HttpPrepared<Frame> {
   readonly request: HttpClientRequest.HttpClientRequest
-  readonly framing: Framing<Frame>
+  readonly framing: FramingDef<Frame>
 }
 
 const applyQuery = (url: string, query: Record<string, string> | undefined) => {
@@ -52,28 +45,21 @@ export const jsonRequestParts = <Body>(input: JsonRequestInput<Body>) =>
       input.request.http?.query,
     )
     const body = yield* bodyWithOverlay(input.body, input.request, input.encodeBody)
-    const headers = yield* Auth.toEffect(Auth.isAuth(input.request.model.auth) ? input.request.model.auth : input.auth)(
-      {
-        request: input.request,
-        method: "POST",
-        url,
-        body: body.bodyText,
-        headers: Headers.fromInput({
-          ...(input.headers?.({ request: input.request }) ?? {}),
-          ...input.request.model.headers,
-          ...input.request.http?.headers,
-        }),
-      },
-    )
+    const headers = yield* Auth.toEffect(input.auth)({
+      request: input.request,
+      method: "POST",
+      url,
+      body: body.bodyText,
+      headers: Headers.fromInput({
+        ...input.headers?.({ request: input.request }),
+        ...input.request.http?.headers,
+      }),
+    })
     return { url, jsonBody: body.jsonBody, bodyText: body.bodyText, headers }
   })
 
-export interface HttpJsonInput<Body, Frame> {
-  readonly endpoint: Endpoint<Body>
-  readonly auth?: AuthDef
-  readonly framing: Framing<Frame>
-  readonly encodeBody: (body: Body) => string
-  readonly headers?: (input: { readonly request: LLMRequest }) => Record<string, string>
+export interface HttpJsonInput<_Body, Frame> {
+  readonly framing: FramingDef<Frame>
 }
 
 export type HttpJsonPatch<Body, Frame> = Partial<HttpJsonInput<Body, Frame>>
@@ -85,14 +71,9 @@ export interface HttpJsonTransport<Body, Frame> extends Transport<Body, HttpPrep
 export const httpJson = <Body, Frame>(input: HttpJsonInput<Body, Frame>): HttpJsonTransport<Body, Frame> => ({
   id: "http-json",
   with: (patch) => httpJson({ ...input, ...patch }),
-  prepare: (body, request) =>
+  prepare: (prepareInput) =>
     jsonRequestParts({
-      body,
-      request,
-      endpoint: input.endpoint,
-      auth: input.auth ?? Auth.bearer(),
-      encodeBody: input.encodeBody,
-      headers: input.headers,
+      ...prepareInput,
     }).pipe(
       Effect.map((parts) => ({
         request: ProviderShared.jsonPost({ url: parts.url, body: parts.bodyText, headers: parts.headers }),
@@ -109,8 +90,8 @@ export const httpJson = <Body, Frame>(input: HttpJsonInput<Body, Frame>): HttpJs
               response.stream.pipe(
                 Stream.mapError((error) =>
                   ProviderShared.eventError(
-                    `${request.model.provider}/${request.model.route}`,
-                    `Failed to read ${request.model.provider}/${request.model.route} stream`,
+                    `${request.model.provider}/${request.model.route.id}`,
+                    `Failed to read ${request.model.provider}/${request.model.route.id} stream`,
                     ProviderShared.errorText(error),
                   ),
                 ),
@@ -120,3 +101,8 @@ export const httpJson = <Body, Frame>(input: HttpJsonInput<Body, Frame>): HttpJs
         ),
     ),
 })
+
+export const sseJson = {
+  id: "http-json/sse",
+  with: <Body>() => httpJson<Body, string>({ framing: Framing.sse }),
+} as const

packages/llm/src/route/transport/index.ts

@@ -1,4 +1,6 @@
 import type { Effect, Stream } from "effect"
+import type { Endpoint } from "../endpoint"
+import type { Auth } from "../auth"
 import type { Interface as RequestExecutorInterface } from "../executor"
 import type { Interface as WebSocketExecutorInterface } from "./websocket"
 import type { LLMError, LLMRequest } from "../../schema"
@@ -10,7 +12,7 @@ export interface TransportRuntime {
 
 export interface Transport<Body, Prepared, Frame> {
   readonly id: string
-  readonly prepare: (body: Body, request: LLMRequest) => Effect.Effect<Prepared, LLMError>
+  readonly prepare: (input: TransportPrepareInput<Body>) => Effect.Effect<Prepared, LLMError>
   readonly frames: (
     prepared: Prepared,
     request: LLMRequest,
@@ -18,5 +20,14 @@ export interface Transport<Body, Prepared, Frame> {
   ) => Stream.Stream<Frame, LLMError>
 }
 
+export interface TransportPrepareInput<Body> {
+  readonly body: Body
+  readonly request: LLMRequest
+  readonly endpoint: Endpoint<Body>
+  readonly auth: Auth
+  readonly encodeBody: (body: Body) => string
+  readonly headers?: (input: { readonly request: LLMRequest }) => Record<string, string>
+}
+
 export * as HttpTransport from "./http"
 export { WebSocketExecutor, WebSocketTransport } from "./websocket"

packages/llm/src/route/transport/websocket.ts

@@ -1,7 +1,6 @@
-import { Cause, Context, Effect, Queue, Stream } from "effect"
+import { Cause, Context, Effect, Layer, Queue, Stream } from "effect"
 import { Headers } from "effect/unstable/http"
-import { Auth, type Auth as AuthDef } from "../auth"
-import type { Endpoint } from "../endpoint"
+import { Auth } from "../auth"
 import { LLMError, TransportReason, type LLMRequest } from "../../schema"
 import * as HttpTransport from "./http"
 import type { Transport } from "./index"
@@ -135,6 +134,8 @@ export const open = (input: WebSocketRequest) =>
       }),
   }).pipe(Effect.flatMap((ws) => fromWebSocket(ws, input)))
 
+export const layer: Layer.Layer<Service> = Layer.succeed(Service, Service.of({ open }))
+
 export const fromWebSocket = (
   ws: globalThis.WebSocket,
   input: WebSocketRequest,
@@ -213,12 +214,8 @@ export interface JsonPrepared {
 }
 
 export interface JsonInput<Body, Message> {
-  readonly endpoint: Endpoint<Body>
-  readonly auth?: AuthDef
-  readonly encodeBody: (body: Body) => string
   readonly toMessage: (body: Body | Record<string, unknown>) => Effect.Effect<Message, LLMError>
   readonly encodeMessage: (message: Message) => string
-  readonly headers?: (input: { readonly request: LLMRequest }) => Record<string, string>
 }
 
 export type JsonPatch<Body, Message> = Partial<JsonInput<Body, Message>>
@@ -230,15 +227,10 @@ export interface JsonTransport<Body, Message> extends Transport<Body, JsonPrepar
 export const json = <Body, Message>(input: JsonInput<Body, Message>): JsonTransport<Body, Message> => ({
   id: "websocket-json",
   with: (patch) => json({ ...input, ...patch }),
-  prepare: (body, request) =>
+  prepare: (prepareInput) =>
     Effect.gen(function* () {
       const parts = yield* HttpTransport.jsonRequestParts({
-        body,
-        request,
-        endpoint: input.endpoint,
-        auth: input.auth ?? Auth.bearer(),
-        encodeBody: input.encodeBody,
-        headers: input.headers,
+        ...prepareInput,
       })
       return {
         url: yield* webSocketUrl(parts.url),
@@ -270,8 +262,14 @@ export const json = <Body, Message>(input: JsonInput<Body, Message>): JsonTransp
   },
 })
 
+export const jsonTransport = {
+  id: "websocket-json",
+  with: json,
+} as const
+
 export const WebSocketExecutor = {
   Service,
+  layer,
   open,
   fromWebSocket,
   messageText,
@@ -279,4 +277,5 @@ export const WebSocketExecutor = {
 
 export const WebSocketTransport = {
   json,
+  jsonTransport,
 } as const

packages/llm/src/schema/events.ts

@@ -1,6 +1,6 @@
 import { Schema } from "effect"
 import { ContentBlockID, FinishReason, ProtocolID, ProviderMetadata, RouteID, ToolCallID } from "./ids"
-import { ModelRef } from "./options"
+import { ModelSchema } from "./options"
 import { ToolResultValue } from "./messages"
 
 /**
@@ -290,7 +290,7 @@ export class PreparedRequest extends Schema.Class<PreparedRequest>("LLM.Prepared
   id: Schema.String,
   route: RouteID,
   protocol: ProtocolID,
-  model: ModelRef,
+  model: ModelSchema,
   body: Schema.Unknown,
   metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
 }) {}

packages/llm/src/schema/messages.ts

@@ -1,9 +1,7 @@
 import { Schema } from "effect"
 import { JsonSchema, MessageRole, ProviderMetadata } from "./ids"
-import { CacheHint, CachePolicy, GenerationOptions, HttpOptions, ModelRef, ProviderOptions } from "./options"
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null && !Array.isArray(value)
+import { CacheHint, CachePolicy, GenerationOptions, HttpOptions, ModelSchema, ProviderOptions } from "./options"
+import { isRecord } from "../utils/record"
 
 const systemPartSchema = Schema.Struct({
   type: Schema.Literal("text"),
@@ -41,17 +39,49 @@ export const MediaPart = Schema.Struct({
 }).annotate({ identifier: "LLM.Content.Media" })
 export type MediaPart = Schema.Schema.Type<typeof MediaPart>
 
+export const ToolResultMediaPart = Schema.Struct({
+  type: Schema.Literal("media"),
+  mediaType: Schema.String,
+  data: Schema.String,
+  filename: Schema.optional(Schema.String),
+  metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+}).annotate({ identifier: "LLM.ToolResult.Media" })
+export type ToolResultMediaPart = Schema.Schema.Type<typeof ToolResultMediaPart>
+
+export const ToolResultContentPart = Schema.Union([TextPart, ToolResultMediaPart])
+export type ToolResultContentPart = Schema.Schema.Type<typeof ToolResultContentPart>
+
 const isToolResultValue = (value: unknown): value is ToolResultValue =>
-  isRecord(value) && (value.type === "text" || value.type === "json" || value.type === "error") && "value" in value
+  isRecord(value) &&
+  (value.type === "text" || value.type === "json" || value.type === "error" || value.type === "content") &&
+  "value" in value
 
 export const ToolResultValue = Object.assign(
-  Schema.Struct({
-    type: Schema.Literals(["json", "text", "error"]),
-    value: Schema.Unknown,
-  }).annotate({ identifier: "LLM.ToolResult" }),
+  Schema.Union([
+    Schema.Struct({
+      type: Schema.Literal("json"),
+      value: Schema.Unknown,
+    }),
+    Schema.Struct({
+      type: Schema.Literal("text"),
+      value: Schema.Unknown,
+    }),
+    Schema.Struct({
+      type: Schema.Literal("error"),
+      value: Schema.Unknown,
+    }),
+    Schema.Struct({
+      type: Schema.Literal("content"),
+      value: Schema.Array(ToolResultContentPart),
+    }),
+  ]).annotate({ identifier: "LLM.ToolResult" }),
   {
-    make: (value: unknown, type: ToolResultValue["type"] = "json"): ToolResultValue =>
-      isToolResultValue(value) ? value : { type, value },
+    is: isToolResultValue,
+    make: (value: unknown, type: ToolResultValue["type"] = "json"): ToolResultValue => {
+      if (isToolResultValue(value)) return value
+      if (type === "content") return { type, value: Array.isArray(value) ? value : [] }
+      return { type, value }
+    },
   },
 )
 export type ToolResultValue = Schema.Schema.Type<typeof ToolResultValue>
@@ -197,7 +227,7 @@ export type ResponseFormat = Schema.Schema.Type<typeof ResponseFormat>
 
 export class LLMRequest extends Schema.Class<LLMRequest>("LLM.Request")({
   id: Schema.optional(Schema.String),
-  model: ModelRef,
+  model: ModelSchema,
   system: Schema.Array(SystemPart),
   messages: Schema.Array(Message),
   tools: Schema.Array(ToolDefinition),

packages/llm/src/schema/options.ts

@@ -1,8 +1,7 @@
 import { Schema } from "effect"
-import { JsonSchema, ModelID, ProviderID, RouteID } from "./ids"
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null && !Array.isArray(value)
+import { JsonSchema, ModelID, ProviderID } from "./ids"
+import type { AnyRoute } from "../route/client"
+import { isRecord } from "../utils/record"
 
 export const mergeJsonRecords = (
   ...items: ReadonlyArray<Record<string, unknown> | undefined>
@@ -135,67 +134,59 @@ export namespace ModelLimits {
     input instanceof ModelLimits ? input : new ModelLimits(input ?? {})
 }
 
-export class ModelRef extends Schema.Class<ModelRef>("LLM.ModelRef")({
-  id: ModelID,
-  provider: ProviderID,
-  route: RouteID,
-  baseURL: Schema.String,
-  /** Provider-specific API key convenience. Provider helpers normalize this into `auth`. */
-  apiKey: Schema.optional(Schema.String),
-  /** Optional transport auth policy. Opaque because it may contain functions. */
-  auth: Schema.optional(Schema.Any),
-  headers: Schema.optional(Schema.Record(Schema.String, Schema.String)),
-  /**
-   * Query params appended to the request URL by `Endpoint.baseURL`. Used for
-   * deployment-level URL-scoped settings such as Azure's `api-version` or any
-   * provider that requires a per-request key in the URL. Generic concern, so
-   * lives as a typed first-class field instead of `native`.
-   */
-  queryParams: Schema.optional(Schema.Record(Schema.String, Schema.String)),
-  limits: ModelLimits,
-  /** Provider-neutral generation defaults. Request-level values override them. */
-  generation: Schema.optional(GenerationOptions),
-  /** Provider-owned typed-at-the-facade options for non-portable knobs. */
-  providerOptions: Schema.optional(ProviderOptions),
-  /** Serializable raw HTTP overlays applied to the final outgoing request. */
-  http: Schema.optional(HttpOptions),
-  /**
-   * Provider-specific opaque options. Reach for this only when the value is
-   * genuinely provider-private and does not fit a typed axis (e.g. Bedrock's
-   * `aws_credentials` / `aws_region` for SigV4). Anything used by more than
-   * one route should grow into a typed field instead.
-   */
-  native: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
-}) {}
+export class Model {
+  readonly id: ModelID
+  readonly provider: ProviderID
+  readonly route: AnyRoute
 
-export namespace ModelRef {
-  export type Input = ConstructorParameters<typeof ModelRef>[0]
+  constructor(input: Model.ConstructorInput) {
+    this.id = input.id
+    this.provider = input.provider
+    this.route = input.route
+  }
 
-  export const input = (model: ModelRef): Input => ({
-    id: model.id,
-    provider: model.provider,
-    route: model.route,
-    baseURL: model.baseURL,
-    apiKey: model.apiKey,
-    auth: model.auth,
-    headers: model.headers,
-    queryParams: model.queryParams,
-    limits: model.limits,
-    generation: model.generation,
-    providerOptions: model.providerOptions,
-    http: model.http,
-    native: model.native,
-  })
+  static make(input: Model.Input) {
+    return new Model({
+      id: ModelID.make(input.id),
+      provider: ProviderID.make(input.provider),
+      route: input.route,
+    })
+  }
 
-  export const update = (model: ModelRef, patch: Partial<Input>) => {
+  static input(model: Model): Model.ConstructorInput {
+    return {
+      id: model.id,
+      provider: model.provider,
+      route: model.route,
+    }
+  }
+
+  static update(model: Model, patch: Partial<Model.Input>) {
     if (Object.keys(patch).length === 0) return model
-    return new ModelRef({
-      ...input(model),
+    return Model.make({
+      ...Model.input(model),
       ...patch,
     })
   }
 }
 
+export namespace Model {
+  export type ConstructorInput = {
+    readonly id: ModelID
+    readonly provider: ProviderID
+    readonly route: AnyRoute
+  }
+
+  export type Input = Omit<ConstructorInput, "id" | "provider"> & {
+    readonly id: string | ModelID
+    readonly provider: string | ProviderID
+  }
+}
+
+export type ModelInput = Model.Input
+
+export const ModelSchema = Schema.declare((value): value is Model => value instanceof Model, { expected: "LLM.Model" })
+
 export class CacheHint extends Schema.Class<CacheHint>("LLM.CacheHint")({
   type: Schema.Literals(["ephemeral", "persistent"]),
   ttlSeconds: Schema.optional(Schema.Number),

packages/llm/src/tool-runtime.ts

@@ -11,7 +11,8 @@ import {
   ToolCallPart,
   ToolFailure,
   ToolResultPart,
-  type ToolResultValue,
+  ToolResultValue,
+  type ToolResultValue as ToolResultValueType,
   Usage,
 } from "./schema"
 import { type AnyTool, type ExecutableTools, type Tools, toDefinitions } from "./tool"
@@ -276,7 +277,10 @@ const appendStreamingText = (
   state.assistantContent.push({ type, text, providerMetadata })
 }
 
-const dispatch = (tools: Tools, call: ToolCallPart): Effect.Effect<{ result: ToolResultValue; error?: unknown }> => {
+const dispatch = (
+  tools: Tools,
+  call: ToolCallPart,
+): Effect.Effect<{ result: ToolResultValueType; error?: unknown }> => {
   const tool = tools[call.name]
   if (!tool) return Effect.succeed({ result: { type: "error" as const, value: `Unknown tool: ${call.name}` } })
   if (!tool.execute)
@@ -285,7 +289,7 @@ const dispatch = (tools: Tools, call: ToolCallPart): Effect.Effect<{ result: Too
   return decodeAndExecute(tool, call).pipe(
     Effect.catchTag("LLM.ToolFailure", (failure) =>
       Effect.succeed({
-        result: { type: "error" as const, value: failure.message } satisfies ToolResultValue,
+        result: { type: "error" as const, value: failure.message } satisfies ToolResultValueType,
         error: failure.error,
       }),
     ),
@@ -293,7 +297,7 @@ const dispatch = (tools: Tools, call: ToolCallPart): Effect.Effect<{ result: Too
   )
 }
 
-const decodeAndExecute = (tool: AnyTool, call: ToolCallPart): Effect.Effect<ToolResultValue, ToolFailure> =>
+const decodeAndExecute = (tool: AnyTool, call: ToolCallPart): Effect.Effect<ToolResultValueType, ToolFailure> =>
   tool._decode(call.input).pipe(
     Effect.mapError((error) => new ToolFailure({ message: `Invalid tool input: ${error.message}` })),
     Effect.flatMap((decoded) => tool.execute!(decoded, { id: call.id, name: call.name })),
@@ -307,10 +311,12 @@ const decodeAndExecute = (tool: AnyTool, call: ToolCallPart): Effect.Effect<Tool
         ),
       ),
     ),
-    Effect.map((encoded): ToolResultValue => ({ type: "json", value: encoded })),
+    Effect.map(
+      (encoded): ToolResultValueType => (ToolResultValue.is(encoded) ? encoded : { type: "json", value: encoded }),
+    ),
   )
 
-const emitEvents = (call: ToolCallPart, result: ToolResultValue, error: unknown): ReadonlyArray<LLMEvent> =>
+const emitEvents = (call: ToolCallPart, result: ToolResultValueType, error: unknown): ReadonlyArray<LLMEvent> =>
   result.type === "error"
     ? [
         LLMEvent.toolError({ id: call.id, name: call.name, message: String(result.value), error }),
@@ -321,7 +327,7 @@ const emitEvents = (call: ToolCallPart, result: ToolResultValue, error: unknown)
 const followUpRequest = (
   request: LLMRequest,
   state: StepState,
-  dispatched: ReadonlyArray<readonly [ToolCallPart, ToolResultValue]>,
+  dispatched: ReadonlyArray<readonly [ToolCallPart, ToolResultValueType]>,
 ) =>
   LLMRequest.update(request, {
     messages: [

packages/llm/src/utils/record.ts

@@ -0,0 +1,3 @@
+/** Plain-record narrowing. Excludes arrays so JSON object checks don't accept tuples as key/value bags. */
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)