refactor(llm): replace LLMError reasons with flat tagged union

Replace the LLMError { module, method, reason } wrapper with a flat
tagged union (LLM.BadRequest, LLM.Authentication, LLM.PermissionDenied,
LLM.NotFound, LLM.RateLimit, LLM.QuotaExceeded, LLM.ContentPolicy,
LLM.ContextOverflow, LLM.ServerError, LLM.APIError, LLM.ConnectionError,
LLM.TimeoutError, LLM.MalformedResponse, LLM.NoRoute) plus an isLLMError
guard. Add one shared classifyApiFailure classifier used by the HTTP
executor and the AI SDK adapter so both surfaces classify identically,
preserving status, headers, body, and retry-after.

Core policy moves onto tags: retry RateLimit | ServerError |
ConnectionError | TimeoutError; toSessionError adds
provider.context-overflow, provider.timeout, and provider.not-found.

The provider-error stream event and the runner's held-back overflow
handling are unchanged here; isContextOverflowFailure now bridges old
events and new tags until the event is removed.

packages/core/src/aisdk.ts

@@ -15,20 +15,43 @@ import type {
   SharedV3ProviderOptions,
 } from "@ai-sdk/provider"
 import {
+  APIError,
+  Authentication,
+  BadRequest,
+  ConnectionError,
   FinishReason,
-  InvalidProviderOutputReason,
+  HttpContext,
+  HttpRequestDetails,
+  HttpResponseDetails,
   LLMEvent,
-  LLMError,
+  MalformedResponse,
   Model,
+  NotFound,
   ProviderID,
   ProviderMetadata,
   ToolResultValue,
-  UnknownProviderReason,
+  classifyApiFailure,
+  isLLMError,
+  type LLMError,
   type ContentPart,
   type LLMRequest,
   type ToolDefinition,
   type UsageInput,
 } from "@opencode-ai/llm"
+import {
+  APICallError,
+  EmptyResponseBodyError,
+  InvalidArgumentError,
+  InvalidPromptError,
+  InvalidResponseDataError,
+  JSONParseError,
+  LoadAPIKeyError,
+  LoadSettingError,
+  NoContentGeneratedError,
+  NoSuchModelError,
+  TypeValidationError,
+  UnsupportedFunctionalityError,
+} from "@ai-sdk/provider"
 import { Auth, Endpoint, type AnyRoute } from "@opencode-ai/llm/route"
 import { Cause, Context, Effect, Layer, Option, Schema, Scope, Stream } from "effect"
 import { ModelV2 } from "./model"
@@ -490,12 +513,12 @@ function streamLanguage(language: LanguageModelV3, options: LanguageModelV3CallO
     Stream.unwrap(
       Effect.tryPromise({
         try: () => language.doStream(options),
-        catch: (error) => llmError("doStream", error),
+        catch: (error) => llmError(error),
       }).pipe(
         Effect.map((result) =>
           Stream.fromReadableStream({
             evaluate: () => result.stream,
-            onError: (error) => llmError("readStream", error),
+            onError: (error) => llmError(error),
           }).pipe(
             Stream.mapEffect((event) => streamPartEvents(state, event)),
             Stream.flatMap((events) => Stream.fromIterable(events)),
@@ -608,7 +631,7 @@ function streamPartEvents(
         }),
       ])
     case "error":
-      return Effect.fail(llmError("stream", event.error))
+      return Effect.fail(llmError(event.error))
   }
 }
 
@@ -666,16 +689,65 @@ function messageValue(input: unknown) {
   }
 }
 
-function llmError(method: string, error: unknown) {
-  const reason =
-    error instanceof LLMError
-      ? new InvalidProviderOutputReason({ message: error.message })
-      : new UnknownProviderReason({ message: error instanceof Error ? error.message : String(error) })
-  return new LLMError({
-    module: "AISDK",
-    method,
-    reason,
-  })
+const BODY_LIMIT = 16_384
+
+const headerRetryAfterMs = (headers: Record<string, string> | undefined) => {
+  if (!headers) return undefined
+  const millis = Number(headers["retry-after-ms"])
+  if (Number.isFinite(millis)) return Math.max(0, millis)
+  const value = headers["retry-after"]
+  if (!value) return undefined
+  const seconds = Number(value)
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000)
+  const date = Date.parse(value)
+  if (!Number.isNaN(date)) return Math.max(0, date - Date.now())
+  return undefined
+}
+
+// Classify AI SDK failures into the shared `LLMError` union so the synthetic
+// AI SDK route reports failures identically to native protocol routes. An
+// `APICallError` without a status code is the AI SDK's representation of a
+// network-level failure (connect refused, reset, DNS), not an API rejection.
+function llmError(error: unknown): LLMError {
+  if (isLLMError(error)) return error
+  if (APICallError.isInstance(error)) {
+    if (error.statusCode === undefined) {
+      return new ConnectionError({ message: error.message, url: error.url, cause: error })
+    }
+    return classifyApiFailure({
+      message: error.message,
+      status: error.statusCode,
+      retryAfterMs: headerRetryAfterMs(error.responseHeaders),
+      requestID: error.responseHeaders?.["x-request-id"] ?? error.responseHeaders?.["request-id"],
+      http: new HttpContext({
+        request: new HttpRequestDetails({ method: "POST", url: error.url, headers: {} }),
+        response: new HttpResponseDetails({ status: error.statusCode, headers: error.responseHeaders ?? {} }),
+        body: error.responseBody === undefined ? undefined : error.responseBody.slice(0, BODY_LIMIT),
+        bodyTruncated: error.responseBody !== undefined && error.responseBody.length > BODY_LIMIT ? true : undefined,
+      }),
+    })
+  }
+  if (LoadAPIKeyError.isInstance(error) || LoadSettingError.isInstance(error)) {
+    return new Authentication({ message: error.message })
+  }
+  if (NoSuchModelError.isInstance(error)) return new NotFound({ message: error.message })
+  if (
+    InvalidPromptError.isInstance(error) ||
+    InvalidArgumentError.isInstance(error) ||
+    UnsupportedFunctionalityError.isInstance(error)
+  ) {
+    return new BadRequest({ message: error.message })
+  }
+  if (
+    InvalidResponseDataError.isInstance(error) ||
+    JSONParseError.isInstance(error) ||
+    TypeValidationError.isInstance(error) ||
+    EmptyResponseBodyError.isInstance(error) ||
+    NoContentGeneratedError.isInstance(error)
+  ) {
+    return new MalformedResponse({ message: error.message })
+  }
+  return new APIError({ message: error instanceof Error ? error.message : String(error) })
 }
 
 export const node = makeLocationNode({ service: Service, layer: locationLayer, deps: [] })

packages/core/src/generate.ts

@@ -1,6 +1,6 @@
 export * as Generate from "./generate"
 
-import { LLM, LLMClient, LLMError } from "@opencode-ai/llm"
+import { LLM, LLMClient, type LLMError } from "@opencode-ai/llm"
 import { Context, Effect, Layer, Schema } from "effect"
 import { Catalog } from "./catalog"
 import { makeLocationNode } from "./effect/app-node"

packages/core/src/session/compaction.ts

@@ -1,6 +1,6 @@
 export * as SessionCompaction from "./compaction"
 
-import { LLM, LLMClient, LLMError, LLMEvent, Message, type LLMRequest, type Model } from "@opencode-ai/llm"
+import { LLM, LLMClient, LLMEvent, Message, isLLMError, type LLMError, type LLMRequest, type Model } from "@opencode-ai/llm"
 import { SessionError } from "@opencode-ai/schema/session-error"
 import { Context, Effect, Layer, Stream } from "effect"
 import { Config } from "../config"
@@ -261,7 +261,7 @@ const make = (dependencies: Dependencies) => {
           }
           return Effect.void
         }),
-        Effect.catchTag("LLM.Error", (error) =>
+        Effect.catchIf(isLLMError, (error) =>
           Effect.sync(() => {
             failure = toSessionError(error)
           }),

packages/core/src/session/runner/llm.ts

@@ -3,11 +3,11 @@ export * as SessionRunnerLLM from "./llm"
 import {
   LLM,
   LLMClient,
-  LLMError,
   LLMEvent,
   Message,
   SystemPart,
   isContextOverflowFailure,
+  isLLMError,
   type ProviderErrorEvent,
 } from "@opencode-ai/llm"
 import { SessionError } from "@opencode-ai/schema/session-error"
@@ -332,7 +332,7 @@ const layer = Layer.effect(
           // thrown LLM failure records the assistant failure unless a provider error was
           // already recorded from the stream. Terminal publication waits for owned tools.
           if (overflowFailure) yield* publish(overflowFailure)
-          const llmFailure = streamFailure instanceof LLMError ? streamFailure : undefined
+          const llmFailure = streamFailure !== undefined && isLLMError(streamFailure) ? streamFailure : undefined
           if (llmFailure && !publisher.hasProviderError()) {
             const error = toSessionError(llmFailure)
             if (

packages/core/src/session/runner/retry.ts

@@ -1,6 +1,6 @@
 export * as SessionRunnerRetry from "./retry"
 
-import { LLMError } from "@opencode-ai/llm"
+import type { LLMError } from "@opencode-ai/llm"
 import { SessionError } from "@opencode-ai/schema/session-error"
 import { Data, Duration, Effect, Schedule } from "effect"
 import { EventV2 } from "../../event"
@@ -17,29 +17,33 @@ export class RetryableFailure extends Data.TaggedError("SessionRunner.RetryableF
 }> {}
 
 export function isRetryable(error: LLMError) {
-  switch (error.reason._tag) {
-    case "RateLimit":
-    case "ProviderInternal":
-    case "Transport":
+  switch (error._tag) {
+    case "LLM.RateLimit":
+    case "LLM.ServerError":
+    case "LLM.ConnectionError":
+    case "LLM.TimeoutError":
       return true
-    case "Authentication":
-    case "QuotaExceeded":
-    case "ContentPolicy":
-    case "InvalidProviderOutput":
-    case "InvalidRequest":
-    case "NoRoute":
-    case "UnknownProvider":
+    case "LLM.Authentication":
+    case "LLM.PermissionDenied":
+    case "LLM.NotFound":
+    case "LLM.QuotaExceeded":
+    case "LLM.ContentPolicy":
+    case "LLM.ContextOverflow":
+    case "LLM.MalformedResponse":
+    case "LLM.BadRequest":
+    case "LLM.NoRoute":
+    case "LLM.APIError":
       return false
     default: {
-      const exhaustive: never = error.reason
+      const exhaustive: never = error
       return exhaustive
     }
   }
 }
 
 const retryAfter = (failure: RetryableFailure) => {
-  if (failure.cause.reason._tag === "RateLimit" || failure.cause.reason._tag === "ProviderInternal")
-    return failure.cause.reason.retryAfterMs
+  if (failure.cause._tag === "LLM.RateLimit" || failure.cause._tag === "LLM.ServerError")
+    return failure.cause.retryAfterMs
   return undefined
 }
 

packages/core/src/session/title.ts

@@ -1,6 +1,6 @@
 export * as SessionTitle from "./title"
 
-import { LLM, LLMClient, LLMError, LLMEvent, Message, type LLMRequest } from "@opencode-ai/llm"
+import { LLM, LLMClient, LLMEvent, Message, isLLMError, type LLMError, type LLMRequest } from "@opencode-ai/llm"
 import { Context, DateTime, Effect, Layer, Stream } from "effect"
 import { AgentV2 } from "../agent"
 import { Database } from "../database/database"
@@ -66,7 +66,7 @@ const make = (dependencies: Dependencies) => {
           return Effect.void
         }),
         Effect.as(true),
-        Effect.catchTag("LLM.Error", () => Effect.succeed(false)),
+        Effect.catchIf(isLLMError, () => Effect.succeed(false)),
       )
     if (!streamed || failed) return
     const title = chunks

packages/core/src/session/to-session-error.ts

@@ -1,4 +1,4 @@
-import { LLMError, ToolFailure } from "@opencode-ai/llm"
+import { isLLMError, ToolFailure } from "@opencode-ai/llm"
 import { Tool } from "@opencode-ai/plugin/v2/effect/tool"
 import { SessionError } from "@opencode-ai/schema/session-error"
 import { PermissionV2 } from "../permission"
@@ -9,30 +9,38 @@ import { AgentNotFoundError, StepFailedError, UserInterruptedError } from "./err
 import { SessionRunnerModel } from "./runner/model"
 
 export function toSessionError(cause: unknown): SessionError.Error {
-  if (cause instanceof LLMError) {
-    switch (cause.reason._tag) {
-      case "RateLimit":
-        return { type: "provider.rate-limit", message: cause.reason.message }
-      case "Authentication":
-        return { type: "provider.auth", message: cause.reason.message }
-      case "QuotaExceeded":
-        return { type: "provider.quota", message: cause.reason.message }
-      case "ContentPolicy":
-        return { type: "provider.content-filter", message: cause.reason.message }
-      case "Transport":
-        return { type: "provider.transport", message: cause.reason.message }
-      case "ProviderInternal":
-        return { type: "provider.internal", message: cause.reason.message }
-      case "InvalidProviderOutput":
-        return { type: "provider.invalid-output", message: cause.reason.message }
-      case "InvalidRequest":
-        return { type: "provider.invalid-request", message: cause.reason.message }
-      case "NoRoute":
-        return { type: "provider.no-route", message: cause.reason.message }
-      case "UnknownProvider":
-        return { type: "provider.unknown", message: cause.reason.message }
+  if (isLLMError(cause)) {
+    switch (cause._tag) {
+      case "LLM.RateLimit":
+        return { type: "provider.rate-limit", message: cause.message }
+      case "LLM.Authentication":
+        return { type: "provider.auth", message: cause.message }
+      case "LLM.PermissionDenied":
+        return { type: "provider.auth", message: cause.message }
+      case "LLM.NotFound":
+        return { type: "provider.not-found", message: cause.message }
+      case "LLM.QuotaExceeded":
+        return { type: "provider.quota", message: cause.message }
+      case "LLM.ContentPolicy":
+        return { type: "provider.content-filter", message: cause.message }
+      case "LLM.ContextOverflow":
+        return { type: "provider.context-overflow", message: cause.message }
+      case "LLM.ConnectionError":
+        return { type: "provider.transport", message: cause.message }
+      case "LLM.TimeoutError":
+        return { type: "provider.timeout", message: cause.message }
+      case "LLM.ServerError":
+        return { type: "provider.internal", message: cause.message }
+      case "LLM.MalformedResponse":
+        return { type: "provider.invalid-output", message: cause.message }
+      case "LLM.BadRequest":
+        return { type: "provider.invalid-request", message: cause.message }
+      case "LLM.NoRoute":
+        return { type: "provider.no-route", message: cause.message }
+      case "LLM.APIError":
+        return { type: "provider.unknown", message: cause.message }
       default: {
-        const exhaustive: never = cause.reason
+        const exhaustive: never = cause
         return exhaustive
       }
     }

packages/core/test/session-error.test.ts

@@ -1,18 +1,22 @@
 import { describe, expect, test } from "bun:test"
 import {
-  AuthenticationReason,
-  ContentPolicyReason,
-  InvalidProviderOutputReason,
-  InvalidRequestReason,
-  LLMError,
-  NoRouteReason,
+  APIError,
+  Authentication,
+  BadRequest,
+  ConnectionError,
+  ContentPolicy,
+  ContextOverflow,
+  MalformedResponse,
   ModelID,
+  NoRoute,
+  NotFound,
+  PermissionDenied,
   ProviderID,
-  ProviderInternalReason,
-  QuotaExceededReason,
-  RateLimitReason,
-  TransportReason,
-  UnknownProviderReason,
+  QuotaExceeded,
+  RateLimit,
+  RouteID,
+  ServerError,
+  TimeoutError,
   ToolFailure,
 } from "@opencode-ai/llm"
 import { PermissionV2 } from "@opencode-ai/core/permission"
@@ -20,39 +24,33 @@ import { Tool } from "@opencode-ai/plugin/v2/effect/tool"
 import { toSessionError } from "@opencode-ai/core/session/to-session-error"
 import { SessionRunnerRetry } from "@opencode-ai/core/session/runner/retry"
 
-const llm = (reason: LLMError["reason"]) => new LLMError({ module: "test", method: "stream", reason })
-
 describe("toSessionError", () => {
-  test("maps every LLM reason to the open wire type", () => {
-    expect(toSessionError(llm(new RateLimitReason({ message: "rate", retryAfterMs: 123 })))).toEqual({
+  test("maps every LLM error tag to the open wire type", () => {
+    expect(toSessionError(new RateLimit({ message: "rate", retryAfterMs: 123 }))).toEqual({
       type: "provider.rate-limit",
       message: "rate",
     })
-    expect(toSessionError(llm(new AuthenticationReason({ message: "auth", kind: "invalid" }))).type).toBe(
-      "provider.auth",
-    )
-    expect(toSessionError(llm(new QuotaExceededReason({ message: "quota" }))).type).toBe("provider.quota")
-    expect(toSessionError(llm(new ContentPolicyReason({ message: "blocked" }))).type).toBe("provider.content-filter")
-    expect(toSessionError(llm(new TransportReason({ message: "transport" }))).type).toBe("provider.transport")
-    expect(toSessionError(llm(new ProviderInternalReason({ message: "internal", status: 500 }))).type).toBe(
-      "provider.internal",
-    )
-    expect(toSessionError(llm(new InvalidProviderOutputReason({ message: "output" }))).type).toBe(
-      "provider.invalid-output",
-    )
-    expect(toSessionError(llm(new InvalidRequestReason({ message: "request" }))).type).toBe("provider.invalid-request")
+    expect(toSessionError(new Authentication({ message: "auth" })).type).toBe("provider.auth")
+    expect(toSessionError(new PermissionDenied({ message: "forbidden" })).type).toBe("provider.auth")
+    expect(toSessionError(new NotFound({ message: "missing" })).type).toBe("provider.not-found")
+    expect(toSessionError(new QuotaExceeded({ message: "quota" })).type).toBe("provider.quota")
+    expect(toSessionError(new ContentPolicy({ message: "blocked" })).type).toBe("provider.content-filter")
+    expect(toSessionError(new ContextOverflow({ message: "too long" })).type).toBe("provider.context-overflow")
+    expect(toSessionError(new ConnectionError({ message: "reset" })).type).toBe("provider.transport")
+    expect(toSessionError(new TimeoutError({ message: "timed out" })).type).toBe("provider.timeout")
+    expect(toSessionError(new ServerError({ message: "internal", status: 500 })).type).toBe("provider.internal")
+    expect(toSessionError(new MalformedResponse({ message: "output" })).type).toBe("provider.invalid-output")
+    expect(toSessionError(new BadRequest({ message: "request" })).type).toBe("provider.invalid-request")
     expect(
       toSessionError(
-        llm(
-          new NoRouteReason({
-            route: "route",
-            provider: ProviderID.make("provider"),
-            model: ModelID.make("model"),
-          }),
-        ),
+        new NoRoute({
+          route: RouteID.make("route"),
+          provider: ProviderID.make("provider"),
+          model: ModelID.make("model"),
+        }),
       ).type,
     ).toBe("provider.no-route")
-    expect(toSessionError(llm(new UnknownProviderReason({ message: "unknown" }))).type).toBe("provider.unknown")
+    expect(toSessionError(new APIError({ message: "unknown", status: 418 })).type).toBe("provider.unknown")
   })
 
   test("preserves the permission rejection type without exposing internal fields", () => {
@@ -71,23 +69,31 @@ describe("toSessionError", () => {
     })
   })
 
-  test("retries only rate limits, provider-internal failures, and transport failures", () => {
+  test("retries only rate limits, server errors, connection failures, and timeouts", () => {
     const eligible = [
-      llm(new RateLimitReason({ message: "rate" })),
-      llm(new ProviderInternalReason({ message: "internal", status: 500 })),
-      llm(new TransportReason({ message: "transport" })),
+      new RateLimit({ message: "rate" }),
+      new ServerError({ message: "internal", status: 500 }),
+      new ConnectionError({ message: "reset" }),
+      new TimeoutError({ message: "timed out" }),
     ]
     const ineligible = [
-      llm(new AuthenticationReason({ message: "auth", kind: "invalid" })),
-      llm(new QuotaExceededReason({ message: "quota" })),
-      llm(new ContentPolicyReason({ message: "blocked" })),
-      llm(new InvalidProviderOutputReason({ message: "output" })),
-      llm(new InvalidRequestReason({ message: "request" })),
-      llm(new NoRouteReason({ route: "route", provider: ProviderID.make("provider"), model: ModelID.make("model") })),
-      llm(new UnknownProviderReason({ message: "unknown" })),
+      new Authentication({ message: "auth" }),
+      new PermissionDenied({ message: "forbidden" }),
+      new NotFound({ message: "missing" }),
+      new QuotaExceeded({ message: "quota" }),
+      new ContentPolicy({ message: "blocked" }),
+      new ContextOverflow({ message: "too long" }),
+      new MalformedResponse({ message: "output" }),
+      new BadRequest({ message: "request" }),
+      new NoRoute({
+        route: RouteID.make("route"),
+        provider: ProviderID.make("provider"),
+        model: ModelID.make("model"),
+      }),
+      new APIError({ message: "unknown" }),
     ]
 
-    expect(eligible.map(SessionRunnerRetry.isRetryable)).toEqual([true, true, true])
-    expect(ineligible.map(SessionRunnerRetry.isRetryable)).toEqual([false, false, false, false, false, false, false])
+    expect(eligible.map(SessionRunnerRetry.isRetryable)).toEqual([true, true, true, true])
+    expect(ineligible.map(SessionRunnerRetry.isRetryable)).toEqual(ineligible.map(() => false))
   })
 })

packages/core/test/session-execution.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test"
-import { LLMError, TransportReason } from "@opencode-ai/llm"
+import { ConnectionError } from "@opencode-ai/llm"
 import { Database } from "@opencode-ai/core/database/database"
 import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
 import { LayerNode } from "@opencode-ai/core/effect/layer-node"
@@ -25,17 +25,10 @@ const it = testEffect(AppNodeBuilder.build(LayerNode.group([Database.node, Event
 describe("SessionExecution lifecycle", () => {
   test("classifies success and typed failure terminals", () => {
     expect(SessionExecution.terminal(Exit.succeed(undefined))).toEqual({ type: "succeeded" })
-    expect(
-      SessionExecution.terminal(
-        Exit.fail(
-          new LLMError({
-            module: "test",
-            method: "stream",
-            reason: new TransportReason({ message: "Disconnected" }),
-          }),
-        ),
-      ),
-    ).toEqual({ type: "failed", error: { type: "provider.transport", message: "Disconnected" } })
+    expect(SessionExecution.terminal(Exit.fail(new ConnectionError({ message: "Disconnected" })))).toEqual({
+      type: "failed",
+      error: { type: "provider.transport", message: "Disconnected" },
+    })
     const storage = new ToolOutputStore.StorageError({ operation: "encode", cause: new Error("invalid output") })
     expect(SessionExecution.terminal(Exit.fail(storage))).toEqual({
       type: "failed",

packages/core/test/session-runner.test.ts

@@ -1,15 +1,16 @@
 import { describe, expect, test } from "bun:test"
 import {
+  BadRequest,
+  ConnectionError,
+  ContextOverflow,
   LLMClient,
-  LLMError,
   LLMEvent,
+  MalformedResponse,
   Model,
+  RateLimit,
   ToolFailure,
-  TransportReason,
-  InvalidProviderOutputReason,
-  InvalidRequestReason,
-  RateLimitReason,
   type LLMClientShape,
+  type LLMError,
   type LLMRequest,
 } from "@opencode-ai/llm"
 import * as OpenAIChat from "@opencode-ai/llm/protocols/openai-chat"
@@ -483,26 +484,11 @@ const setup = Effect.gen(function* () {
   return yield* SessionV2.Service
 })
 
-const providerUnavailable = () =>
-  new LLMError({
-    module: "test",
-    method: "stream",
-    reason: new TransportReason({ message: "Provider unavailable" }),
-  })
+const providerUnavailable = () => new ConnectionError({ message: "Provider unavailable" })
 
-const invalidRequest = () =>
-  new LLMError({
-    module: "test",
-    method: "stream",
-    reason: new InvalidRequestReason({ message: "Invalid request" }),
-  })
+const invalidRequest = () => new BadRequest({ message: "Invalid request" })
 
-const rateLimited = (retryAfterMs?: number) =>
-  new LLMError({
-    module: "test",
-    method: "stream",
-    reason: new RateLimitReason({ message: "Rate limited", retryAfterMs }),
-  })
+const rateLimited = (retryAfterMs?: number) => new RateLimit({ message: "Rate limited", retryAfterMs })
 
 const setupOverflowRecovery = Effect.gen(function* () {
   const session = yield* setup
@@ -1985,16 +1971,7 @@ describe("SessionRunnerLLM", () => {
   it.effect("recovers once from a raw context overflow failure", () =>
     Effect.gen(function* () {
       const session = yield* setupOverflowRecovery
-      responseStream = Stream.fail(
-        new LLMError({
-          module: "test",
-          method: "stream",
-          reason: new InvalidRequestReason({
-            message: "prompt too long",
-            classification: "context-overflow",
-          }),
-        }),
-      )
+      responseStream = Stream.fail(new ContextOverflow({ message: "prompt too long" }))
       responses = [
         reply.text("## Objective\n- Recover raw overflow", "text-summary"),
         reply.text("Recovered", "text-final"),
@@ -3892,11 +3869,7 @@ describe("SessionRunnerLLM", () => {
     Effect.gen(function* () {
       const session = yield* setup
       yield* admit(session, "Call a malformed tool")
-      const failure = new LLMError({
-        module: "test",
-        method: "stream",
-        reason: new InvalidProviderOutputReason({ message: "Invalid JSON input for tool call echo" }),
-      })
+      const failure = new MalformedResponse({ message: "Invalid JSON input for tool call echo" })
       responseStream = Stream.fromIterable([
         LLMEvent.stepStart({ index: 0 }),
         LLMEvent.toolInputStart({ id: "call-malformed", name: "echo" }),

packages/llm/AGENTS.md

@@ -182,8 +182,8 @@ The dependency arrow points down: `providers/*.ts` files import protocol routes
 - `joinText(parts)` — joins an array of `TextPart` (or anything with a `.text`) with newlines. Use this anywhere a protocol flattens text content into a single string for a provider field.
 - `parseToolInput(route, name, raw)` — Schema-decodes a tool-call argument string with the canonical "Invalid JSON input for `<route>` tool call `<name>`" error message. Treats empty input as `{}`.
 - `parseJson(route, raw, message)` — generic JSON-via-Schema decode for non-tool bodies.
-- `eventError(route, message, ...)` — typed `InvalidProviderOutput` constructor for stream-time decode failures.
-- `validateWith(decoder)` — maps Schema decode errors to `InvalidRequest`. `Route.make(...)` uses this for body validation; lower-level routes can reuse it.
+- `eventError(route, message, ...)` — typed `MalformedResponse` constructor for stream-time decode failures.
+- `validateWith(decoder)` — maps Schema decode errors to `BadRequest`. `Route.make(...)` uses this for body validation; lower-level routes can reuse it.
 - `matchToolChoice(provider, choice, branches)` — branches over `LLMRequest["toolChoice"]` for provider-specific lowering.
 
 If you find yourself copying a 3-to-5-line snippet between two protocols, lift it into `ProviderShared` next to these helpers rather than duplicating.

packages/llm/src/index.ts

@@ -2,7 +2,7 @@ export { LLMClient } from "./route/client"
 export { Auth } from "./route/auth"
 export { Provider } from "./provider"
 export { ProviderPackage } from "./provider-package"
-export { isContextOverflow, isContextOverflowFailure } from "./provider-error"
+export { classifyApiFailure, isContextOverflow, isContextOverflowFailure, type ApiFailure } from "./provider-error"
 export type {
   RouteModelInput,
   RouteRoutedModelInput,

packages/llm/src/llm.ts

@@ -3,8 +3,8 @@ import { LLMClient } from "./route/client"
 import {
   GenerationOptions,
   HttpOptions,
-  InvalidProviderOutputReason,
-  LLMError,
+  MalformedResponse,
+  type LLMError,
   LLMEvent,
   LLMRequest,
   LLMResponse,
@@ -121,22 +121,14 @@ const runGenerateObject = Effect.fn("LLM.generateObject")(function* (
     (event) => LLMEvent.is.toolCall(event) && event.name === GENERATE_OBJECT_TOOL_NAME,
   )
   if (!call || !LLMEvent.is.toolCall(call))
-    return yield* new LLMError({
-      module: "LLM",
-      method: "generateObject",
-      reason: new InvalidProviderOutputReason({
-        message: `generateObject: model did not call the forced \`${GENERATE_OBJECT_TOOL_NAME}\` tool`,
-      }),
+    return yield* new MalformedResponse({
+      message: `generateObject: model did not call the forced \`${GENERATE_OBJECT_TOOL_NAME}\` tool`,
     })
   const object = yield* tool._decode(call.input).pipe(
     Effect.mapError(
       (error) =>
-        new LLMError({
-          module: "LLM",
-          method: "generateObject",
-          reason: new InvalidProviderOutputReason({
-            message: `generateObject: tool input failed schema decode: ${error.message}`,
-          }),
+        new MalformedResponse({
+          message: `generateObject: tool input failed schema decode: ${error.message}`,
         }),
     ),
   )

packages/llm/src/protocols/shared.ts

@@ -3,9 +3,9 @@ import { Effect, Schema, Stream } from "effect"
 import * as Sse from "effect/unstable/encoding/Sse"
 import { Headers, HttpClientRequest } from "effect/unstable/http"
 import {
-  InvalidProviderOutputReason,
-  InvalidRequestReason,
-  LLMError,
+  BadRequest,
+  MalformedResponse,
+  type LLMError,
   type ContentPart,
   type LLMRequest,
   type MediaPart,
@@ -88,11 +88,7 @@ export const sumTokens = (...values: ReadonlyArray<number | undefined>): number
 }
 
 export const eventError = (route: string, message: string, raw?: string) =>
-  new LLMError({
-    module: "ProviderShared",
-    method: "stream",
-    reason: new InvalidProviderOutputReason({ route, message, raw }),
-  })
+  new MalformedResponse({ route, message, raw })
 
 export const parseJson = (route: string, input: string, message: string) =>
   Effect.try({
@@ -252,15 +248,9 @@ export const sseFraming = (bytes: Stream.Stream<Uint8Array, LLMError>): Stream.S
  * Canonical invalid-request constructor. Lift one-line `const invalid =
  * (message) => invalidRequest(message)` aliases out of every
  * route so the error constructor lives in one place. If we ever extend
- * `InvalidRequestReason` with route context or trace metadata, the change
- * lands here.
+ * `BadRequest` with route context or trace metadata, the change lands here.
  */
-export const invalidRequest = (message: string) =>
-  new LLMError({
-    module: "ProviderShared",
-    method: "request",
-    reason: new InvalidRequestReason({ message }),
-  })
+export const invalidRequest = (message: string) => new BadRequest({ message })
 
 export const matchToolChoice = <Auto, None, Required, Tool>(
   route: string,

packages/llm/src/protocols/utils/tool-stream.ts

@@ -1,5 +1,5 @@
 import { Effect } from "effect"
-import { LLMError, LLMEvent, type ProviderMetadata, type ToolCall } from "../../schema"
+import { isLLMError, LLMEvent, type LLMError, type ProviderMetadata, type ToolCall } from "../../schema"
 import { eventError, parseToolInput, type ToolAccumulator } from "../shared"
 
 type StreamKey = string | number
@@ -95,7 +95,7 @@ const appendTool = <K extends StreamKey>(
 }
 
 export const isError = <K extends StreamKey>(result: AppendOutcome<K> | LLMError): result is LLMError =>
-  result instanceof LLMError
+  isLLMError(result)
 
 /**
  * Register a tool call whose start event arrived before any argument deltas.

packages/llm/src/provider-error.ts

@@ -1,5 +1,22 @@
 import { Schema } from "effect"
-import { LLMError, ProviderErrorEvent } from "./schema"
+import {
+  APIError,
+  Authentication,
+  BadRequest,
+  ContentPolicy,
+  ContextOverflow,
+  HttpContext,
+  HttpRateLimitDetails,
+  NotFound,
+  PermissionDenied,
+  ProviderErrorEvent,
+  ProviderMetadata,
+  QuotaExceeded,
+  RateLimit,
+  ServerError,
+  isLLMError,
+  type LLMError,
+} from "./schema"
 
 const patterns = [
   /prompt is too long/i,
@@ -28,6 +45,106 @@ export const isContextOverflow = (message: string) =>
   patterns.some((pattern) => pattern.test(message)) || /^4(00|13)\s*(status code)?\s*\(no body\)/i.test(message)
 
 export const isContextOverflowFailure = (failure: unknown) =>
-  failure instanceof LLMError
-    ? failure.reason._tag === "InvalidRequest" && failure.reason.classification === "context-overflow"
+  isLLMError(failure)
+    ? failure._tag === "LLM.ContextOverflow"
     : Schema.is(ProviderErrorEvent)(failure) && failure.classification === "context-overflow"
+
+const OVERFLOW_CODES = new Set(["context_length_exceeded", "model_context_window_exceeded"])
+const QUOTA_CODES = new Set(["insufficient_quota", "usage_not_included", "billing_error"])
+const QUOTA_TEXT = /insufficient[-_\s]?quota|quota[-_\s]?exceeded/i
+const CONTENT_POLICY_TEXT = /content[-_\s]?policy|content_filter|safety/i
+const SERVER_ERROR_STATUS = (status: number) => status >= 500 || status === 529
+
+const CODE_CLASSIFICATION: Record<string, (input: ApiFailure, common: CommonFields) => LLMError> = {
+  overloaded_error: serverError,
+  api_error: serverError,
+  server_error: serverError,
+  internal_error: serverError,
+  server_is_overloaded: serverError,
+  internalServerException: serverError,
+  serviceUnavailableException: serverError,
+  modelStreamErrorException: serverError,
+  rate_limit_error: rateLimit,
+  rate_limit_exceeded: rateLimit,
+  too_many_requests: rateLimit,
+  throttlingException: rateLimit,
+  authentication_error: (_input, common) => new Authentication(common),
+  permission_error: (_input, common) => new PermissionDenied(common),
+  not_found_error: (_input, common) => new NotFound(common),
+  invalid_request_error: (_input, common) => new BadRequest(common),
+  invalid_prompt: (_input, common) => new BadRequest(common),
+  validationException: (_input, common) => new BadRequest(common),
+}
+
+export interface ApiFailure {
+  readonly message: string
+  readonly status?: number | undefined
+  /** Provider machine-readable error code or type string (e.g. `context_length_exceeded`, `overloaded_error`). */
+  readonly code?: string | undefined
+  readonly retryAfterMs?: number | undefined
+  readonly rateLimit?: HttpRateLimitDetails | undefined
+  readonly requestID?: string | undefined
+  readonly http?: HttpContext | undefined
+  readonly providerMetadata?: ProviderMetadata | undefined
+}
+
+type CommonFields = {
+  readonly message: string
+  readonly status: number | undefined
+  readonly code: string | undefined
+  readonly requestID: string | undefined
+  readonly http: HttpContext | undefined
+  readonly providerMetadata: ProviderMetadata | undefined
+}
+
+function serverError(input: ApiFailure, common: CommonFields) {
+  return new ServerError({ ...common, retryAfterMs: input.retryAfterMs })
+}
+
+function rateLimit(input: ApiFailure, common: CommonFields) {
+  return new RateLimit({ ...common, retryAfterMs: input.retryAfterMs, rateLimit: input.rateLimit })
+}
+
+/**
+ * One classifier for every failure a remote API deliberately reports.
+ * Protocols call it with in-stream error payloads, the request executor with
+ * non-2xx responses, and the AI SDK adapter with `APICallError`s, so all
+ * three surfaces produce identical `LLMError` tags.
+ *
+ * Precedence: context overflow (most specific, 4xx-scoped), content policy,
+ * HTTP status, provider code, then the generic `APIError` fallback.
+ */
+export const classifyApiFailure = (input: ApiFailure): LLMError => {
+  const common: CommonFields = {
+    message: input.message,
+    status: input.status,
+    code: input.code,
+    requestID: input.requestID,
+    http: input.http,
+    providerMetadata: input.providerMetadata,
+  }
+  const body = input.http?.body ?? ""
+  const clientScoped = input.status === undefined || (input.status >= 400 && input.status < 500)
+  if (
+    clientScoped &&
+    ((input.code !== undefined && OVERFLOW_CODES.has(input.code)) ||
+      isContextOverflow(input.message) ||
+      (body.length > 0 && isContextOverflow(body)))
+  )
+    return new ContextOverflow(common)
+  if (CONTENT_POLICY_TEXT.test(body.length > 0 ? body : input.message)) return new ContentPolicy(common)
+  if (input.code !== undefined && QUOTA_CODES.has(input.code)) return new QuotaExceeded(common)
+  if (input.status === 401) return new Authentication(common)
+  if (input.status === 403) return new PermissionDenied(common)
+  if (input.status === 404) return new NotFound(common)
+  if (input.status === 429) {
+    if (QUOTA_TEXT.test(body.length > 0 ? body : input.message)) return new QuotaExceeded(common)
+    return rateLimit(input, common)
+  }
+  if (input.status !== undefined && SERVER_ERROR_STATUS(input.status)) return serverError(input, common)
+  if (input.status === 400 || input.status === 409 || input.status === 413 || input.status === 422)
+    return new BadRequest(common)
+  const byCode = input.code === undefined ? undefined : CODE_CLASSIFICATION[input.code]
+  if (byCode) return byCode(input, common)
+  return new APIError(common)
+}

packages/llm/src/route/auth.ts

@@ -1,6 +1,6 @@
 import { Config, Effect, Redacted } from "effect"
 import { Headers } from "effect/unstable/http"
-import { AuthenticationReason, InvalidRequestReason, LLMError, type LLMRequest } from "../schema"
+import { Authentication, BadRequest, type LLMError, type LLMRequest } from "../schema"
 
 export class MissingCredentialError extends Error {
   readonly _tag = "MissingCredentialError"
@@ -135,16 +135,9 @@ export function bearerHeader(name: string, source?: Secret | Credential) {
 }
 
 const toLLMError = (error: AuthError): LLMError => {
-  if (error instanceof MissingCredentialError || error instanceof Config.ConfigError) {
-    return new LLMError({
-      module: "Auth",
-      method: "apply",
-      reason:
-        error instanceof MissingCredentialError
-          ? new AuthenticationReason({ message: error.message, kind: "missing" })
-          : new InvalidRequestReason({ message: `Failed to resolve auth config: ${error.message}` }),
-    })
-  }
+  if (error instanceof MissingCredentialError) return new Authentication({ message: error.message })
+  if (error instanceof Config.ConfigError)
+    return new BadRequest({ message: `Failed to resolve auth config: ${error.message}` })
   return error
 }
 

packages/llm/src/route/client.ts

@@ -14,11 +14,11 @@ import type { LLMError, LLMEvent, PreparedRequestOf, ProtocolID, ProviderOptions
 import {
   GenerationOptions,
   HttpOptions,
+  isLLMError,
   LLMRequest,
   LLMResponse,
   Model,
   ModelLimits,
-  LLMError as LLMErrorClass,
   PreparedRequest,
   ProviderID,
   mergeGenerationOptions,
@@ -225,7 +225,7 @@ export interface MakeTransportInput<Body, Prepared, Frame, Event, State> {
 
 const streamError = (route: string, message: string, cause: Cause.Cause<unknown>) => {
   const failed = cause.reasons.find(Cause.isFailReason)?.error
-  if (failed instanceof LLMErrorClass) return failed
+  if (failed !== undefined && isLLMError(failed)) return failed
   return ProviderShared.eventError(route, message, Cause.pretty(cause))
 }
 

packages/llm/src/route/executor.ts

@@ -1,4 +1,4 @@
-import { Cause, Context, Effect, Layer } from "effect"
+import { Cause, Context, Effect, Layer, Option, Schema } from "effect"
 import {
   FetchHttpClient,
   Headers,
@@ -8,21 +8,15 @@ import {
   HttpClientResponse,
 } from "effect/unstable/http"
 import {
-  AuthenticationReason,
-  ContentPolicyReason,
+  ConnectionError,
   HttpContext,
   HttpRateLimitDetails,
   HttpRequestDetails,
   HttpResponseDetails,
-  InvalidRequestReason,
-  LLMError,
-  ProviderInternalReason,
-  QuotaExceededReason,
-  RateLimitReason,
-  TransportReason,
-  UnknownProviderReason,
+  TimeoutError,
+  type LLMError,
 } from "../schema"
-import { isContextOverflow } from "../provider-error"
+import { classifyApiFailure } from "../provider-error"
 
 export interface Interface {
   readonly execute: (
@@ -85,8 +79,6 @@ const requestId = (headers: Record<string, string>) => {
   )
 }
 
-const providerInternalStatus = (status: number) => status === 429 || status === 503 || status === 504 || status === 529
-
 const retryAfterMs = (headers: Record<string, string>) => {
   const millis = Number(headers["retry-after-ms"])
   if (Number.isFinite(millis)) return Math.max(0, millis)
@@ -219,56 +211,21 @@ const responseHttp = (input: {
     rateLimit: input.rateLimit,
   })
 
-const statusReason = (input: {
-  readonly status: number
-  readonly message: string
-  readonly retryAfterMs?: number | undefined
-  readonly rateLimit?: HttpRateLimitDetails | undefined
-  readonly http: HttpContext
-}) => {
-  const body = input.http.body ?? ""
-  if (/content[-_\s]?policy|content_filter|safety/i.test(body)) {
-    return new ContentPolicyReason({ message: input.message, http: input.http })
-  }
-  if (input.status === 401) {
-    return new AuthenticationReason({ message: input.message, kind: "invalid", http: input.http })
-  }
-  if (input.status === 403) {
-    return new AuthenticationReason({ message: input.message, kind: "insufficient-permissions", http: input.http })
-  }
-  if (input.status === 429) {
-    if (/insufficient[-_\s]?quota|quota[-_\s]?exceeded/i.test(body)) {
-      return new QuotaExceededReason({ message: input.message, http: input.http })
-    }
-    return new RateLimitReason({
-      message: input.message,
-      retryAfterMs: input.retryAfterMs,
-      rateLimit: input.rateLimit,
-      http: input.http,
-    })
-  }
-  if (
-    input.status === 400 ||
-    input.status === 404 ||
-    input.status === 409 ||
-    input.status === 413 ||
-    input.status === 422
-  ) {
-    return new InvalidRequestReason({
-      message: input.message,
-      classification: isContextOverflow(body) ? "context-overflow" : undefined,
-      http: input.http,
-    })
-  }
-  if (input.status >= 500 || providerInternalStatus(input.status)) {
-    return new ProviderInternalReason({
-      message: input.message,
-      status: input.status,
-      retryAfterMs: input.retryAfterMs,
-      http: input.http,
-    })
-  }
-  return new UnknownProviderReason({ message: input.message, status: input.status, http: input.http })
+const decodeBodyJson = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Unknown))
+
+// Provider machine code from a JSON error body (`error.code` / `error.type`),
+// fed to the shared classifier so code-based rules (overflow, quota) work on
+// HTTP rejections too. Truncated or non-JSON bodies yield undefined.
+const providerCode = (body: string | undefined) => {
+  if (!body) return undefined
+  const decoded = Option.getOrUndefined(decodeBodyJson(body))
+  if (typeof decoded !== "object" || decoded === null) return undefined
+  const error = (decoded as Record<string, unknown>).error
+  if (typeof error !== "object" || error === null) return undefined
+  const fields = error as Record<string, unknown>
+  if (typeof fields.code === "string") return fields.code
+  if (typeof fields.type === "string") return fields.type
+  return undefined
 }
 
 const statusError =
@@ -281,58 +238,55 @@ const statusError =
       const retryAfter = retryAfterMs(headers)
       const rateLimit = rateLimitDetails(headers, retryAfter)
       const details = responseBody(body, request)
-      return yield* new LLMError({
-        module: "RequestExecutor",
-        method: "execute",
-        reason: statusReason({
-          status: response.status,
-          message: providerMessage(response.status, details),
-          retryAfterMs: retryAfter,
+      return yield* classifyApiFailure({
+        status: response.status,
+        message: providerMessage(response.status, details),
+        code: providerCode(details.body),
+        retryAfterMs: retryAfter,
+        rateLimit,
+        requestID: requestId(headers),
+        http: responseHttp({
+          request,
+          response,
+          redactedNames,
+          body: details,
+          requestId: requestId(headers),
           rateLimit,
-          http: responseHttp({
-            request,
-            response,
-            redactedNames,
-            body: details,
-            requestId: requestId(headers),
-            rateLimit,
-          }),
         }),
       })
     })
 
 const toHttpError = (redactedNames: ReadonlyArray<string | RegExp>) => (error: unknown) => {
-  const transportError = (input: {
+  const httpContext = (request: HttpClientRequest.HttpClientRequest | undefined) =>
+    request ? new HttpContext({ request: requestDetails(request, redactedNames) }) : undefined
+  const connectionError = (input: {
     readonly message: string
     readonly kind?: string | undefined
     readonly request?: HttpClientRequest.HttpClientRequest | undefined
   }) =>
-    new LLMError({
-      module: "RequestExecutor",
-      method: "execute",
-      reason: new TransportReason({
-        message: input.message,
-        kind: input.kind,
-        url: input.request ? redactUrl(input.request.url) : undefined,
-        http: input.request ? new HttpContext({ request: requestDetails(input.request, redactedNames) }) : undefined,
-      }),
+    new ConnectionError({
+      message: input.message,
+      kind: input.kind,
+      url: input.request ? redactUrl(input.request.url) : undefined,
+      http: httpContext(input.request),
+      cause: error,
     })
 
   if (Cause.isTimeoutError(error)) {
-    return transportError({ message: error.message, kind: "Timeout" })
+    return new TimeoutError({ message: error.message })
   }
   if (!HttpClientError.isHttpClientError(error)) {
-    return transportError({ message: "HTTP transport failed" })
+    return connectionError({ message: "HTTP transport failed" })
   }
   const request = "request" in error ? error.request : undefined
   if (error.reason._tag === "TransportError") {
-    return transportError({
+    return connectionError({
       message: error.reason.description ?? "HTTP transport failed",
       kind: error.reason._tag,
       request,
     })
   }
-  return transportError({
+  return connectionError({
     message: `HTTP transport failed: ${error.reason._tag}`,
     kind: error.reason._tag,
     request,

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

@@ -1,6 +1,6 @@
 import { Cause, Context, Effect, Layer, Queue, Stream } from "effect"
 import { Headers } from "effect/unstable/http"
-import { LLMError, TransportReason } from "../../schema"
+import { ConnectionError, type LLMError } from "../../schema"
 import * as HttpTransport from "./http"
 import type { Transport } from "./index"
 
@@ -27,15 +27,10 @@ type WebSocketConstructorWithHeaders = new (
 export class Service extends Context.Service<Service, Interface>()("@opencode/LLM/WebSocketExecutor") {}
 
 const transportError = (
-  method: string,
+  _method: string,
   message: string,
   input: { readonly url?: string; readonly kind?: string } = {},
-) =>
-  new LLMError({
-    module: "WebSocketExecutor",
-    method,
-    reason: new TransportReason({ message, url: input.url, kind: input.kind }),
-  })
+) => new ConnectionError({ message, url: input.url, kind: input.kind })
 
 const eventMessage = (event: Event) => {
   if ("message" in event && typeof event.message === "string") return event.message

packages/llm/src/schema/errors.ts

@@ -31,118 +31,150 @@ export class HttpContext extends Schema.Class<HttpContext>("LLM.HttpContext")({
   rateLimit: Schema.optional(HttpRateLimitDetails),
 }) {}
 
-export class InvalidRequestReason extends Schema.Class<InvalidRequestReason>("LLM.Error.InvalidRequest")({
-  _tag: Schema.tag("InvalidRequest"),
+/**
+ * Fields shared by every failure the remote API deliberately reported —
+ * whether as a non-2xx response, an SSE error event, a WebSocket error
+ * message, or a binary exception frame. `status` is absent when the error
+ * arrived mid-stream without an HTTP status; `code` carries the provider's
+ * machine-readable error code (e.g. `context_length_exceeded`) when one
+ * exists.
+ */
+const apiFailureFields = {
   message: Schema.String,
-  parameter: Schema.optional(Schema.String),
-  classification: Schema.optional(ProviderFailureClassification),
-  providerMetadata: Schema.optional(ProviderMetadata),
+  status: Schema.optional(Schema.Number),
+  code: Schema.optional(Schema.String),
+  requestID: Schema.optional(Schema.String),
   http: Schema.optional(HttpContext),
-}) {}
-
-export class NoRouteReason extends Schema.Class<NoRouteReason>("LLM.Error.NoRoute")({
-  _tag: Schema.tag("NoRoute"),
-  route: RouteID,
-  provider: ProviderID,
-  model: ModelID,
-}) {
-  get message() {
-    return `No LLM route for ${this.provider}/${this.model} using ${this.route}`
-  }
+  providerMetadata: Schema.optional(ProviderMetadata),
 }
 
-export class AuthenticationReason extends Schema.Class<AuthenticationReason>("LLM.Error.Authentication")({
-  _tag: Schema.tag("Authentication"),
-  message: Schema.String,
-  kind: Schema.Literals(["missing", "invalid", "expired", "insufficient-permissions", "unknown"]),
-  providerMetadata: Schema.optional(ProviderMetadata),
-  http: Schema.optional(HttpContext),
+/** Provider rejected the request as invalid (400/409/422, `invalid_request_error`, ...). */
+export class BadRequest extends Schema.TaggedErrorClass<BadRequest>()("LLM.BadRequest", {
+  ...apiFailureFields,
+  parameter: Schema.optional(Schema.String),
 }) {}
 
-export class RateLimitReason extends Schema.Class<RateLimitReason>("LLM.Error.RateLimit")({
-  _tag: Schema.tag("RateLimit"),
-  message: Schema.String,
+/** Credentials are missing, invalid, or expired (401). */
+export class Authentication extends Schema.TaggedErrorClass<Authentication>()("LLM.Authentication", {
+  ...apiFailureFields,
+}) {}
+
+/** Authenticated but not allowed (403). */
+export class PermissionDenied extends Schema.TaggedErrorClass<PermissionDenied>()("LLM.PermissionDenied", {
+  ...apiFailureFields,
+}) {}
+
+/** Model or endpoint does not exist (404). */
+export class NotFound extends Schema.TaggedErrorClass<NotFound>()("LLM.NotFound", {
+  ...apiFailureFields,
+}) {}
+
+/** Transient request throttling (429). Retryable; honor `retryAfterMs` when present. */
+export class RateLimit extends Schema.TaggedErrorClass<RateLimit>()("LLM.RateLimit", {
+  ...apiFailureFields,
   retryAfterMs: Schema.optional(Schema.Number),
   rateLimit: Schema.optional(HttpRateLimitDetails),
-  providerMetadata: Schema.optional(ProviderMetadata),
-  http: Schema.optional(HttpContext),
 }) {}
 
-export class QuotaExceededReason extends Schema.Class<QuotaExceededReason>("LLM.Error.QuotaExceeded")({
-  _tag: Schema.tag("QuotaExceeded"),
-  message: Schema.String,
-  providerMetadata: Schema.optional(ProviderMetadata),
-  http: Schema.optional(HttpContext),
+/** Account-level quota or billing exhaustion. Unlike `RateLimit`, waiting does not help. */
+export class QuotaExceeded extends Schema.TaggedErrorClass<QuotaExceeded>()("LLM.QuotaExceeded", {
+  ...apiFailureFields,
 }) {}
 
-export class ContentPolicyReason extends Schema.Class<ContentPolicyReason>("LLM.Error.ContentPolicy")({
-  _tag: Schema.tag("ContentPolicy"),
-  message: Schema.String,
-  providerMetadata: Schema.optional(ProviderMetadata),
-  http: Schema.optional(HttpContext),
+/** Provider refused the content for policy/safety reasons. */
+export class ContentPolicy extends Schema.TaggedErrorClass<ContentPolicy>()("LLM.ContentPolicy", {
+  ...apiFailureFields,
 }) {}
 
-export class ProviderInternalReason extends Schema.Class<ProviderInternalReason>("LLM.Error.ProviderInternal")({
-  _tag: Schema.tag("ProviderInternal"),
-  message: Schema.String,
-  status: Schema.Number,
+/**
+ * The request exceeds the model's context window. Designated tag because
+ * Core recovers from it structurally (compaction) rather than surfacing it.
+ * Upgraded from `BadRequest` by the shared classifier in `provider-error.ts`.
+ */
+export class ContextOverflow extends Schema.TaggedErrorClass<ContextOverflow>()("LLM.ContextOverflow", {
+  ...apiFailureFields,
+}) {}
+
+/** Provider-side failure (5xx, `overloaded_error`, internal exceptions). Retryable. */
+export class ServerError extends Schema.TaggedErrorClass<ServerError>()("LLM.ServerError", {
+  ...apiFailureFields,
   retryAfterMs: Schema.optional(Schema.Number),
-  providerMetadata: Schema.optional(ProviderMetadata),
-  http: Schema.optional(HttpContext),
 }) {}
 
-export class TransportReason extends Schema.Class<TransportReason>("LLM.Error.Transport")({
-  _tag: Schema.tag("Transport"),
+/** Any other deliberate API rejection that matches no designated tag (402, 405, 410, ...). */
+export class APIError extends Schema.TaggedErrorClass<APIError>()("LLM.APIError", {
+  ...apiFailureFields,
+}) {}
+
+/** Communication failed: connect failure, reset, socket close, DNS. No API response involved. */
+export class ConnectionError extends Schema.TaggedErrorClass<ConnectionError>()("LLM.ConnectionError", {
   message: Schema.String,
   kind: Schema.optional(Schema.String),
   url: Schema.optional(Schema.String),
   http: Schema.optional(HttpContext),
+  cause: Schema.optional(Schema.Defect()),
 }) {}
 
-export class InvalidProviderOutputReason extends Schema.Class<InvalidProviderOutputReason>(
-  "LLM.Error.InvalidProviderOutput",
-)({
-  _tag: Schema.tag("InvalidProviderOutput"),
+/** The request or stream read timed out before the provider answered. */
+export class TimeoutError extends Schema.TaggedErrorClass<TimeoutError>()("LLM.TimeoutError", {
+  message: Schema.String,
+  url: Schema.optional(Schema.String),
+  http: Schema.optional(HttpContext),
+}) {}
+
+/**
+ * Transport succeeded but the content broke the protocol contract:
+ * undecodable frames, premature EOF without a terminal `finish`, duplicate
+ * terminals, or output after a terminal event.
+ */
+export class MalformedResponse extends Schema.TaggedErrorClass<MalformedResponse>()("LLM.MalformedResponse", {
   message: Schema.String,
   route: Schema.optional(Schema.String),
   raw: Schema.optional(Schema.String),
   providerMetadata: Schema.optional(ProviderMetadata),
 }) {}
 
-export class UnknownProviderReason extends Schema.Class<UnknownProviderReason>("LLM.Error.UnknownProvider")({
-  _tag: Schema.tag("UnknownProvider"),
-  message: Schema.String,
-  status: Schema.optional(Schema.Number),
-  providerMetadata: Schema.optional(ProviderMetadata),
-  http: Schema.optional(HttpContext),
-}) {}
-
-export const LLMErrorReason = Schema.Union([
-  InvalidRequestReason,
-  NoRouteReason,
-  AuthenticationReason,
-  RateLimitReason,
-  QuotaExceededReason,
-  ContentPolicyReason,
-  ProviderInternalReason,
-  TransportReason,
-  InvalidProviderOutputReason,
-  UnknownProviderReason,
-]).pipe(Schema.toTaggedUnion("_tag"))
-export type LLMErrorReason = Schema.Schema.Type<typeof LLMErrorReason>
-
-export class LLMError extends Schema.TaggedErrorClass<LLMError>()("LLM.Error", {
-  module: Schema.String,
-  method: Schema.String,
-  reason: LLMErrorReason,
+/** Request construction failed locally: the selected model resolves to no executable route. */
+export class NoRoute extends Schema.TaggedErrorClass<NoRoute>()("LLM.NoRoute", {
+  route: RouteID,
+  provider: ProviderID,
+  model: ModelID,
 }) {
-  override readonly cause = this.reason
-
   override get message() {
-    return `${this.module}.${this.method}: ${this.reason.message}`
+    return `No LLM route for ${this.provider}/${this.model} using ${this.route}`
   }
 }
 
+const members = [
+  BadRequest,
+  Authentication,
+  PermissionDenied,
+  NotFound,
+  RateLimit,
+  QuotaExceeded,
+  ContentPolicy,
+  ContextOverflow,
+  ServerError,
+  APIError,
+  ConnectionError,
+  TimeoutError,
+  MalformedResponse,
+  NoRoute,
+] as const
+
+export const LLMErrorSchema = Schema.Union(members)
+
+/**
+ * Every failure of one LLM request. `LLMEvent` streams carry output only;
+ * all failures — HTTP rejections, in-stream provider error events, transport
+ * failures, and protocol-contract violations — exit through this union on
+ * the stream's error channel.
+ */
+export type LLMError = typeof LLMErrorSchema.Type
+
+export const isLLMError = (value: unknown): value is LLMError =>
+  members.some((member) => value instanceof member)
+
 /**
  * Failure type for tool execute handlers. Handlers must map their internal
  * errors to this shape; the runtime catches `ToolFailure`s and surfaces them

packages/llm/test/executor.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect } from "bun:test"
 import { Effect, Layer, Ref } from "effect"
 import { Headers, HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
-import { LLM, LLMError } from "../src"
+import { LLM, isLLMError, type LLMError } from "../src"
 import { LLMClient, RequestExecutor } from "../src/route"
 import * as OpenAIChat from "../src/protocols/openai-chat"
 import { dynamicResponse } from "./lib/http"
@@ -59,12 +59,12 @@ const countedResponsesLayer = (attempts: Ref.Ref<number>, responses: ReadonlyArr
   )
 
 const expectLLMError = (error: unknown) => {
-  expect(error).toBeInstanceOf(LLMError)
-  if (!(error instanceof LLMError)) throw new Error("expected LLMError")
+  expect(isLLMError(error)).toBe(true)
+  if (!isLLMError(error)) throw new Error("expected LLMError")
   return error
 }
 
-const errorHttp = (error: LLMError) => ("http" in error.reason ? error.reason.http : undefined)
+const errorHttp = (error: LLMError) => ("http" in error ? error.http : undefined)
 
 describe("RequestExecutor", () => {
   it.effect("classifies context overflow responses", () =>
@@ -73,7 +73,7 @@ describe("RequestExecutor", () => {
       const error = yield* executor.execute(request).pipe(Effect.flip)
 
       expectLLMError(error)
-      expect(error.reason).toMatchObject({ _tag: "InvalidRequest", classification: "context-overflow" })
+      expect(error).toMatchObject({ _tag: "LLM.ContextOverflow" })
     }).pipe(
       Effect.provide(
         responsesLayer([
@@ -91,8 +91,7 @@ describe("RequestExecutor", () => {
       const error = yield* executor.execute(request).pipe(Effect.flip)
 
       expectLLMError(error)
-      expect(error.reason).toMatchObject({ _tag: "InvalidRequest" })
-      expect("classification" in error.reason ? error.reason.classification : undefined).toBeUndefined()
+      expect(error).toMatchObject({ _tag: "LLM.BadRequest" })
     }).pipe(Effect.provide(responsesLayer([new Response("request too large", { status: 413 })]))),
   )
 
@@ -102,8 +101,7 @@ describe("RequestExecutor", () => {
       const error = yield* executor.execute(request).pipe(Effect.flip)
 
       expectLLMError(error)
-      expect(error.reason).toMatchObject({ _tag: "InvalidRequest" })
-      expect("classification" in error.reason ? error.reason.classification : undefined).toBeUndefined()
+      expect(error).toMatchObject({ _tag: "LLM.BadRequest" })
     }).pipe(Effect.provide(responsesLayer([new Response("invalid parameter", { status: 400 })]))),
   )
 
@@ -114,24 +112,22 @@ describe("RequestExecutor", () => {
 
       expectLLMError(error)
       expect(error).toMatchObject({
-        reason: {
-          _tag: "RateLimit",
-          retryAfterMs: 0,
-          rateLimit: { retryAfterMs: 0 },
-          http: {
-            requestId: "req_123",
-            request: {
-              method: "POST",
-              url: "https://provider.test/v1/chat?api_key=%3Credacted%3E&key=%3Credacted%3E&debug=1",
-              headers: { authorization: "<redacted>", "x-safe": "visible" },
-            },
-            response: {
-              status: 429,
-              headers: {
-                "retry-after-ms": "0",
-                "x-request-id": "req_123",
-                "x-api-key": "<redacted>",
-              },
+        _tag: "LLM.RateLimit",
+        retryAfterMs: 0,
+        rateLimit: { retryAfterMs: 0 },
+        http: {
+          requestId: "req_123",
+          request: {
+            method: "POST",
+            url: "https://provider.test/v1/chat?api_key=%3Credacted%3E&key=%3Credacted%3E&debug=1",
+            headers: { authorization: "<redacted>", "x-safe": "visible" },
+          },
+          response: {
+            status: 429,
+            headers: {
+              "retry-after-ms": "0",
+              "x-request-id": "req_123",
+              "x-api-key": "<redacted>",
             },
           },
         },
@@ -169,8 +165,8 @@ describe("RequestExecutor", () => {
       const error = yield* executor.execute(request).pipe(Effect.flip)
 
       expectLLMError(error)
-      expect(error.reason).toMatchObject({ _tag: "RateLimit" })
-      expect(error.reason._tag === "RateLimit" ? error.reason.rateLimit : undefined).toEqual({
+      expect(error).toMatchObject({ _tag: "LLM.RateLimit" })
+      expect(error._tag === "LLM.RateLimit" ? error.rateLimit : undefined).toEqual({
         retryAfterMs: 0,
         limit: { requests: "500", tokens: "30000" },
         remaining: { requests: "499", tokens: "29900" },
@@ -202,7 +198,7 @@ describe("RequestExecutor", () => {
       const error = yield* executor.execute(request).pipe(Effect.flip)
 
       expectLLMError(error)
-      expect(error.reason).toMatchObject({ _tag: "ProviderInternal" })
+      expect(error).toMatchObject({ _tag: "LLM.ServerError" })
       expect(errorHttp(error)?.rateLimit).toEqual({
         retryAfterMs: 0,
         limit: { requests: "100", "input-tokens": "10000" },
@@ -245,12 +241,12 @@ describe("RequestExecutor", () => {
       )
 
       expectLLMError(error)
-      expect(error.reason).toMatchObject({ _tag: "ProviderInternal", status: 503 })
+      expect(error).toMatchObject({ _tag: "LLM.ServerError", status: 503 })
       expect(yield* Ref.get(attempts)).toBe(1)
     }),
   )
 
-  it.effect("marks 504 and 529 status responses as provider-internal", () =>
+  it.effect("marks 504 and 529 status responses as server errors", () =>
     Effect.gen(function* () {
       const failWith = (status: number) =>
         Effect.gen(function* () {
@@ -258,7 +254,7 @@ describe("RequestExecutor", () => {
           const error = yield* executor.execute(request).pipe(Effect.flip)
 
           expectLLMError(error)
-          expect(error.reason).toMatchObject({ _tag: "ProviderInternal", status })
+          expect(error).toMatchObject({ _tag: "LLM.ServerError", status })
         }).pipe(
           Effect.provide(
             responsesLayer([
@@ -281,7 +277,7 @@ describe("RequestExecutor", () => {
       const error = yield* executor.execute(request).pipe(Effect.flip)
 
       expectLLMError(error)
-      expect(error.reason).toMatchObject({ _tag: "Authentication" })
+      expect(error).toMatchObject({ _tag: "LLM.Authentication" })
       expect(errorHttp(error)?.bodyTruncated).toBe(true)
       expect(errorHttp(error)?.body).toHaveLength(16_384)
     }).pipe(
@@ -360,7 +356,7 @@ describe("RequestExecutor", () => {
       )
 
       expectLLMError(error)
-      expect(error.reason).toMatchObject({ _tag: "InvalidProviderOutput" })
+      expect(error).toMatchObject({ _tag: "LLM.MalformedResponse" })
       expect(yield* Ref.get(attempts)).toBe(1)
     }),
   )

packages/llm/test/prepare.test.ts

@@ -149,8 +149,8 @@ describe("request option precedence", () => {
         }),
       ).pipe(Effect.flip)
 
-      expect(error.reason).toMatchObject({
-        _tag: "InvalidRequest",
+      expect(error).toMatchObject({
+        _tag: "LLM.BadRequest",
         message: "http.body cannot overlay protocol-owned field(s): model, messages, tools",
       })
     }),

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

@@ -1,6 +1,6 @@
 import { describe, expect } from "bun:test"
 import { Effect } from "effect"
-import { LLM, LLMError, Message, ToolCallPart } from "../../src"
+import { isLLMError, LLM, Message, ToolCallPart } from "../../src"
 import { LLMClient } from "../../src/route"
 import * as Anthropic from "../../src/providers/anthropic"
 import { weatherToolName } from "../recorded-scenarios"
@@ -22,6 +22,9 @@ const malformedToolOrderRequest = LLM.request({
     Message.user("Use that result to answer briefly."),
   ],
   tools: [{ name: weatherToolName, description: "Get weather", inputSchema: { type: "object", properties: {} } }],
+  // The cassette predates the `cache: "auto"` default; pin the policy off so
+  // the replayed request matches the recorded wire shape.
+  cache: "none",
 })
 
 const recorded = recordedTests({
@@ -33,13 +36,17 @@ const recorded = recordedTests({
 })
 
 describe("Anthropic Messages sad-path recorded", () => {
-  recorded.effect.with("rejects malformed assistant tool order", { tags: ["tool", "sad-path"] }, () =>
-    Effect.gen(function* () {
-      const error = yield* LLMClient.generate(malformedToolOrderRequest).pipe(Effect.flip)
+  recorded.effect.with(
+    "rejects malformed assistant tool order",
+    // The cassette predates a test rename; keep replaying the existing recording.
+    { id: "rejects-malformed-assistant-tool-order-without-patch", tags: ["tool", "sad-path"] },
+    () =>
+      Effect.gen(function* () {
+        const error = yield* LLMClient.generate(malformedToolOrderRequest).pipe(Effect.flip)
 
-      expect(error).toBeInstanceOf(LLMError)
-      expect(error.reason).toMatchObject({ _tag: "InvalidRequest" })
-      expect(error.message).toContain("HTTP 400")
-    }),
+        expect(isLLMError(error)).toBe(true)
+        expect(error).toMatchObject({ _tag: "LLM.BadRequest" })
+        expect(error.message).toContain("HTTP 400")
+      }),
   )
 })

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

@@ -1,7 +1,7 @@
 import { describe, expect } from "bun:test"
 import { Effect } from "effect"
 import { HttpClientRequest } from "effect/unstable/http"
-import { CacheHint, LLM, LLMError, Message, ToolCallPart, Usage } from "../../src"
+import { CacheHint, isLLMError, LLM, Message, ToolCallPart, Usage } from "../../src"
 import { Auth, LLMClient } from "../../src/route"
 import * as AnthropicMessages from "../../src/protocols/anthropic-messages"
 import { continuationRequest, nativeAnthropicMessagesContinuation } from "../continuation-scenarios"
@@ -553,8 +553,8 @@ describe("Anthropic Messages route", () => {
         Effect.flip,
       )
 
-      expect(error).toBeInstanceOf(LLMError)
-      expect(error.reason).toMatchObject({ _tag: "InvalidRequest" })
+      expect(isLLMError(error)).toBe(true)
+      expect(error).toMatchObject({ _tag: "LLM.BadRequest" })
       expect(error.message).toContain("HTTP 400")
     }),
   )

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

@@ -1,6 +1,6 @@
 import { describe, expect } from "bun:test"
 import { Effect } from "effect"
-import { LLM, LLMError, Message, ToolCallPart, Usage } from "../../src"
+import { isLLMError, LLM, Message, ToolCallPart, Usage } from "../../src"
 import { Auth, LLMClient } from "../../src/route"
 import * as Gemini from "../../src/protocols/gemini"
 import { ProviderShared } from "../../src/protocols/shared"
@@ -560,8 +560,8 @@ describe("Gemini route", () => {
         Effect.flip,
       )
 
-      expect(error).toBeInstanceOf(LLMError)
-      expect(error.reason).toMatchObject({ _tag: "InvalidProviderOutput" })
+      expect(isLLMError(error)).toBe(true)
+      expect(error).toMatchObject({ _tag: "LLM.MalformedResponse" })
       expect(error.message).toContain("Invalid google/gemini stream event")
     }),
   )

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

@@ -1,7 +1,7 @@
 import { describe, expect } from "bun:test"
 import { Effect, Schema, Stream } from "effect"
 import { HttpClientRequest } from "effect/unstable/http"
-import { LLM, LLMError, LLMEvent, Message, Model, ToolCallPart, Usage } from "../../src"
+import { isLLMError, LLM, LLMEvent, Message, Model, ToolCallPart, Usage } from "../../src"
 import * as Azure from "../../src/providers/azure"
 import * as OpenAI from "../../src/providers/openai"
 import * as OpenAIChat from "../../src/protocols/openai-chat"
@@ -662,8 +662,8 @@ describe("OpenAI Chat route", () => {
         Effect.flip,
       )
 
-      expect(error).toBeInstanceOf(LLMError)
-      expect(error.reason).toMatchObject({ _tag: "InvalidRequest" })
+      expect(isLLMError(error)).toBe(true)
+      expect(error).toMatchObject({ _tag: "LLM.BadRequest" })
       expect(error.message).toContain("HTTP 400")
     }),
   )

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

@@ -1,7 +1,7 @@
 import { describe, expect } from "bun:test"
 import { ConfigProvider, Effect, Layer, Stream } from "effect"
 import { Headers, HttpClientRequest } from "effect/unstable/http"
-import { LLM, LLMError, Message, Model, ToolCallPart, Usage } from "../../src"
+import { isLLMError, LLM, Message, Model, ToolCallPart, Usage } from "../../src"
 import { Auth, LLMClient, RequestExecutor, WebSocketExecutor } from "../../src/route"
 import * as Azure from "../../src/providers/azure"
 import * as OpenAI from "../../src/providers/openai"
@@ -1562,8 +1562,8 @@ describe("OpenAI Responses route", () => {
         Effect.flip,
       )
 
-      expect(error).toBeInstanceOf(LLMError)
-      expect(error.reason).toMatchObject({ _tag: "InvalidRequest" })
+      expect(isLLMError(error)).toBe(true)
+      expect(error).toMatchObject({ _tag: "LLM.BadRequest" })
       expect(error.message).toContain("HTTP 400")
     }),
   )

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

@@ -1,6 +1,6 @@
 import { describe, expect } from "bun:test"
 import { Effect } from "effect"
-import { LLMError } from "../src/schema"
+import { isLLMError } from "../src/schema"
 import { ToolStream } from "../src/protocols/utils/tool-stream"
 import { it } from "./lib/effect"
 
@@ -40,8 +40,9 @@ describe("ToolStream", () => {
     Effect.gen(function* () {
       const error = ToolStream.appendExisting(ADAPTER, ToolStream.empty<number>(), 0, "{}", "missing tool")
 
-      expect(error).toBeInstanceOf(LLMError)
-      if (ToolStream.isError(error)) expect(error.reason.message).toBe("missing tool")
+      expect(isLLMError(error)).toBe(true)
+      if (ToolStream.isError(error))
+        expect(error).toMatchObject({ _tag: "LLM.MalformedResponse", message: "missing tool" })
     }),
   )