From fce506b3f93bac83228bcc46e27266bf45ea5d2e Mon Sep 17 00:00:00 2001 From: Aiden Cline Date: Mon, 13 Jul 2026 10:47:50 -0500 Subject: [PATCH] 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 | 104 ++++++++-- packages/core/src/generate.ts | 2 +- packages/core/src/session/compaction.ts | 4 +- packages/core/src/session/runner/llm.ts | 4 +- packages/core/src/session/runner/retry.ts | 34 ++-- packages/core/src/session/title.ts | 4 +- packages/core/src/session/to-session-error.ts | 56 +++--- packages/core/test/session-error.test.ts | 104 +++++----- packages/core/test/session-execution.test.ts | 17 +- packages/core/test/session-runner.test.ts | 49 +---- packages/llm/AGENTS.md | 4 +- packages/llm/src/index.ts | 2 +- packages/llm/src/llm.ts | 20 +- packages/llm/src/protocols/shared.ts | 22 +- .../llm/src/protocols/utils/tool-stream.ts | 4 +- packages/llm/src/provider-error.ts | 123 +++++++++++- packages/llm/src/route/auth.ts | 15 +- packages/llm/src/route/client.ts | 4 +- packages/llm/src/route/executor.ts | 138 +++++-------- packages/llm/src/route/transport/websocket.ts | 11 +- packages/llm/src/schema/errors.ts | 188 ++++++++++-------- packages/llm/test/executor.test.ts | 66 +++--- packages/llm/test/prepare.test.ts | 4 +- .../anthropic-messages.recorded.test.ts | 23 ++- .../test/provider/anthropic-messages.test.ts | 6 +- packages/llm/test/provider/gemini.test.ts | 6 +- .../llm/test/provider/openai-chat.test.ts | 6 +- .../test/provider/openai-responses.test.ts | 6 +- packages/llm/test/tool-stream.test.ts | 7 +- 29 files changed, 583 insertions(+), 450 deletions(-) diff --git a/packages/core/src/aisdk.ts b/packages/core/src/aisdk.ts index 3330c77f4a..3efd037a5a 100644 --- a/packages/core/src/aisdk.ts +++ b/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 | 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: [] }) diff --git a/packages/core/src/generate.ts b/packages/core/src/generate.ts index 81c2a0f495..16c49fc6cb 100644 --- a/packages/core/src/generate.ts +++ b/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" diff --git a/packages/core/src/session/compaction.ts b/packages/core/src/session/compaction.ts index d9db191b57..3640781f8d 100644 --- a/packages/core/src/session/compaction.ts +++ b/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) }), diff --git a/packages/core/src/session/runner/llm.ts b/packages/core/src/session/runner/llm.ts index 932470d869..b8d561cee1 100644 --- a/packages/core/src/session/runner/llm.ts +++ b/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 ( diff --git a/packages/core/src/session/runner/retry.ts b/packages/core/src/session/runner/retry.ts index 3ada83b4e4..a3a8461807 100644 --- a/packages/core/src/session/runner/retry.ts +++ b/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 } diff --git a/packages/core/src/session/title.ts b/packages/core/src/session/title.ts index 8e7b5857b7..c2cc9880ea 100644 --- a/packages/core/src/session/title.ts +++ b/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 diff --git a/packages/core/src/session/to-session-error.ts b/packages/core/src/session/to-session-error.ts index 6d3d521fb7..2dfc15d317 100644 --- a/packages/core/src/session/to-session-error.ts +++ b/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 } } diff --git a/packages/core/test/session-error.test.ts b/packages/core/test/session-error.test.ts index 46bdb09e70..f7e5c7b6f0 100644 --- a/packages/core/test/session-error.test.ts +++ b/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)) }) }) diff --git a/packages/core/test/session-execution.test.ts b/packages/core/test/session-execution.test.ts index 2775df3564..6058ca81ef 100644 --- a/packages/core/test/session-execution.test.ts +++ b/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", diff --git a/packages/core/test/session-runner.test.ts b/packages/core/test/session-runner.test.ts index 63171b9a44..23e1e1a763 100644 --- a/packages/core/test/session-runner.test.ts +++ b/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" }), diff --git a/packages/llm/AGENTS.md b/packages/llm/AGENTS.md index e883a9e47d..6814986dcb 100644 --- a/packages/llm/AGENTS.md +++ b/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 `` tool call ``" 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. diff --git a/packages/llm/src/index.ts b/packages/llm/src/index.ts index 83edee7155..9e83f64d38 100644 --- a/packages/llm/src/index.ts +++ b/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, diff --git a/packages/llm/src/llm.ts b/packages/llm/src/llm.ts index e4781d8608..b252dcbe99 100644 --- a/packages/llm/src/llm.ts +++ b/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}`, }), ), ) diff --git a/packages/llm/src/protocols/shared.ts b/packages/llm/src/protocols/shared.ts index 173dc511bb..baea037ab7 100644 --- a/packages/llm/src/protocols/shared.ts +++ b/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 } 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): 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 = ( route: string, diff --git a/packages/llm/src/protocols/utils/tool-stream.ts b/packages/llm/src/protocols/utils/tool-stream.ts index 8e07a64bfe..27f614a8ac 100644 --- a/packages/llm/src/protocols/utils/tool-stream.ts +++ b/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 = ( } export const isError = (result: AppendOutcome | LLMError): result is LLMError => - result instanceof LLMError + isLLMError(result) /** * Register a tool call whose start event arrived before any argument deltas. diff --git a/packages/llm/src/provider-error.ts b/packages/llm/src/provider-error.ts index 321bd7927e..77740f04ee 100644 --- a/packages/llm/src/provider-error.ts +++ b/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 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) +} diff --git a/packages/llm/src/route/auth.ts b/packages/llm/src/route/auth.ts index 32871c0454..26471f9cb1 100644 --- a/packages/llm/src/route/auth.ts +++ b/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 } diff --git a/packages/llm/src/route/client.ts b/packages/llm/src/route/client.ts index a258aae944..70a2ddf049 100644 --- a/packages/llm/src/route/client.ts +++ b/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 { const streamError = (route: string, message: string, cause: Cause.Cause) => { 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)) } diff --git a/packages/llm/src/route/executor.ts b/packages/llm/src/route/executor.ts index 0f7a949168..ddb7214df8 100644 --- a/packages/llm/src/route/executor.ts +++ b/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) => { ) } -const providerInternalStatus = (status: number) => status === 429 || status === 503 || status === 504 || status === 529 - const retryAfterMs = (headers: Record) => { 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).error + if (typeof error !== "object" || error === null) return undefined + const fields = error as Record + 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) => (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, diff --git a/packages/llm/src/route/transport/websocket.ts b/packages/llm/src/route/transport/websocket.ts index 310121420c..f0d2e8f4f2 100644 --- a/packages/llm/src/route/transport/websocket.ts +++ b/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()("@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 diff --git a/packages/llm/src/schema/errors.ts b/packages/llm/src/schema/errors.ts index 3592ea729f..a8add1cdad 100644 --- a/packages/llm/src/schema/errors.ts +++ b/packages/llm/src/schema/errors.ts @@ -31,118 +31,150 @@ export class HttpContext extends Schema.Class("LLM.HttpContext")({ rateLimit: Schema.optional(HttpRateLimitDetails), }) {} -export class InvalidRequestReason extends Schema.Class("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("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("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()("LLM.BadRequest", { + ...apiFailureFields, + parameter: Schema.optional(Schema.String), }) {} -export class RateLimitReason extends Schema.Class("LLM.Error.RateLimit")({ - _tag: Schema.tag("RateLimit"), - message: Schema.String, +/** Credentials are missing, invalid, or expired (401). */ +export class Authentication extends Schema.TaggedErrorClass()("LLM.Authentication", { + ...apiFailureFields, +}) {} + +/** Authenticated but not allowed (403). */ +export class PermissionDenied extends Schema.TaggedErrorClass()("LLM.PermissionDenied", { + ...apiFailureFields, +}) {} + +/** Model or endpoint does not exist (404). */ +export class NotFound extends Schema.TaggedErrorClass()("LLM.NotFound", { + ...apiFailureFields, +}) {} + +/** Transient request throttling (429). Retryable; honor `retryAfterMs` when present. */ +export class RateLimit extends Schema.TaggedErrorClass()("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("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()("LLM.QuotaExceeded", { + ...apiFailureFields, }) {} -export class ContentPolicyReason extends Schema.Class("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()("LLM.ContentPolicy", { + ...apiFailureFields, }) {} -export class ProviderInternalReason extends Schema.Class("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()("LLM.ContextOverflow", { + ...apiFailureFields, +}) {} + +/** Provider-side failure (5xx, `overloaded_error`, internal exceptions). Retryable. */ +export class ServerError extends Schema.TaggedErrorClass()("LLM.ServerError", { + ...apiFailureFields, retryAfterMs: Schema.optional(Schema.Number), - providerMetadata: Schema.optional(ProviderMetadata), - http: Schema.optional(HttpContext), }) {} -export class TransportReason extends Schema.Class("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()("LLM.APIError", { + ...apiFailureFields, +}) {} + +/** Communication failed: connect failure, reset, socket close, DNS. No API response involved. */ +export class ConnectionError extends Schema.TaggedErrorClass()("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( - "LLM.Error.InvalidProviderOutput", -)({ - _tag: Schema.tag("InvalidProviderOutput"), +/** The request or stream read timed out before the provider answered. */ +export class TimeoutError extends Schema.TaggedErrorClass()("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()("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("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 - -export class LLMError extends Schema.TaggedErrorClass()("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()("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 diff --git a/packages/llm/test/executor.test.ts b/packages/llm/test/executor.test.ts index 1227dbbf96..c58a30541f 100644 --- a/packages/llm/test/executor.test.ts +++ b/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, 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: "", "x-safe": "visible" }, - }, - response: { - status: 429, - headers: { - "retry-after-ms": "0", - "x-request-id": "req_123", - "x-api-key": "", - }, + _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: "", "x-safe": "visible" }, + }, + response: { + status: 429, + headers: { + "retry-after-ms": "0", + "x-request-id": "req_123", + "x-api-key": "", }, }, }, @@ -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) }), ) diff --git a/packages/llm/test/prepare.test.ts b/packages/llm/test/prepare.test.ts index 6923c5a678..d9ccc0fcdf 100644 --- a/packages/llm/test/prepare.test.ts +++ b/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", }) }), diff --git a/packages/llm/test/provider/anthropic-messages.recorded.test.ts b/packages/llm/test/provider/anthropic-messages.recorded.test.ts index 9b552550ad..3f441f5675 100644 --- a/packages/llm/test/provider/anthropic-messages.recorded.test.ts +++ b/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") + }), ) }) diff --git a/packages/llm/test/provider/anthropic-messages.test.ts b/packages/llm/test/provider/anthropic-messages.test.ts index 14a35a4fa7..6e73b72a72 100644 --- a/packages/llm/test/provider/anthropic-messages.test.ts +++ b/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") }), ) diff --git a/packages/llm/test/provider/gemini.test.ts b/packages/llm/test/provider/gemini.test.ts index 1dc253c0ea..843393215c 100644 --- a/packages/llm/test/provider/gemini.test.ts +++ b/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") }), ) diff --git a/packages/llm/test/provider/openai-chat.test.ts b/packages/llm/test/provider/openai-chat.test.ts index 63ae09bdd8..004edd2263 100644 --- a/packages/llm/test/provider/openai-chat.test.ts +++ b/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") }), ) diff --git a/packages/llm/test/provider/openai-responses.test.ts b/packages/llm/test/provider/openai-responses.test.ts index 421617b6db..1c27c90d54 100644 --- a/packages/llm/test/provider/openai-responses.test.ts +++ b/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") }), ) diff --git a/packages/llm/test/tool-stream.test.ts b/packages/llm/test/tool-stream.test.ts index b005d2666c..48ab2d7a8a 100644 --- a/packages/llm/test/tool-stream.test.ts +++ b/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(), 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" }) }), )