diff --git a/packages/ai/README.md b/packages/ai/README.md index a6573d11689..313ba9a1024 100644 --- a/packages/ai/README.md +++ b/packages/ai/README.md @@ -137,6 +137,23 @@ res.object.city `stream` puts `object` on its `finish` event; `loop` runs tools first and puts it on the loop's `finish`. A decode failure is an `AIError` whose `partial` holds the response. +### Errors + +Every failure is an `AIError`. `reason._tag` names the kind (`RateLimit`, `InvalidRequest`, `Transport`, ...), and +getters read the common fields without digging into `reason` or the raw body: + +```ts +try { + await ai.generate({ model, prompt: "Hi" }) +} catch (error) { + if (!(error instanceof AIError)) throw error + error.status // HTTP status, when the failure came from a response + error.code // provider error code such as "model_not_found", when known + error.isRetryable // whether sending the same request again may succeed + error.retryAfterMs // delay the provider asked for, when known +} +``` + ### Raw provider events Set `includeRaw: true` on a request to also receive every provider frame as `{ type: "raw", data }`, in order and diff --git a/packages/ai/src/provider-error.ts b/packages/ai/src/provider-error.ts index 43fb6953345..c993b5dbf35 100644 --- a/packages/ai/src/provider-error.ts +++ b/packages/ai/src/provider-error.ts @@ -11,8 +11,7 @@ import { type HttpContext, type HttpRateLimitDetails, } from "./schema/index.js" -import { Json } from "./utils/json.js" -import { isRecord } from "./utils/record.js" +import { awsErrorType, providerCodes } from "./utils/provider-codes.js" const patterns = [ /prompt is too long/i, @@ -85,43 +84,8 @@ export const isContextOverflowFailure = (failure: unknown) => * Whether a failed call may succeed when sent again: rate limits, provider-side failures, transport failures that did * not deliver an accepted write, and unrecognized failures. Callers decide which calls are safe to repeat. */ -export const isRetryable = (error: AIError) => { - const override = error.reason.http?.headers["x-should-retry"] - if (override === "true") return true - if (override === "false") return false - switch (error.reason._tag) { - case "RateLimit": - case "ProviderInternal": - return true - // A WebSocket acknowledgment marks delivery accepted before model output may exist. - // Read failures can still recover; the caller chooses retry versus continuation from durable output. - case "Transport": - return ( - error.reason.delivery !== "rejected" && - (error.reason.delivery !== "accepted" || error.reason.operation === "read") - ) - case "InvalidProviderOutput": - return error.reason.classification === "incomplete-stream" - // Unrecognized failures retry: classification records affirmative - // deterministic evidence, and transient failures are exactly the ones - // that arrive in shapes no classifier anticipates. - case "UnknownProvider": - return true - case "Authentication": - case "QuotaExceeded": - case "ContentPolicy": - case "InvalidRequest": - case "UnsupportedOperation": - case "Timeout": - return false - default: { - const exhaustive: never = error.reason - return exhaustive - } - } -} +export const isRetryable = (error: AIError) => error.isRetryable -const decodeJson = Schema.decodeUnknownOption(Json) // OpenCode Zen reports account caps as typed 429/402 errors that are not throttles. const QUOTA_CODES = new Set([ "insufficient_quota", @@ -317,40 +281,3 @@ export function classifyProviderFailure(input: ProviderFailure): AIError["reason if (input.status !== undefined && input.status >= 400 && input.status < 500) return new InvalidRequestError(details) return new UnknownProviderError(details) } - -function providerCodes(value: unknown) { - const decoded = typeof value === "string" ? Option.getOrUndefined(decodeJson(value)) : value - if (!isRecord(decoded)) return [] - const error = isRecord(decoded.error) ? decoded.error : undefined - const inner = error && isRecord(error.innererror) ? error.innererror : undefined - const metadata = error && isRecord(error.metadata) ? error.metadata : undefined - const response = isRecord(decoded.response) ? decoded.response : undefined - const responseError = response && isRecord(response.error) ? response.error : undefined - const exception = isRecord(decoded.exception) ? decoded.exception : undefined - return [ - decoded.code, - ...awsErrorType(decoded.__type), - ...awsErrorType(decoded.code), - decoded.error_type, - error?.code, - error?.type, - error?.status, - error?.error_type, - // Google `google.rpc.ErrorInfo` details carry the specific reason. - ...(Array.isArray(error?.details) - ? error.details.map((detail) => (isRecord(detail) ? detail.reason : undefined)) - : []), - inner?.code, - metadata?.error_type, - responseError?.code, - response?.error_type, - exception?.type, - ].filter((value): value is string => typeof value === "string") -} - -// AWS restJson1 reports the modeled error in `X-Amzn-Errortype`, `__type` or `code`, possibly -// namespaced (`ns#Name`) or suffixed (`Name:uri`). Keep the shape name only. -// https://smithy.io/2.0/aws/protocols/aws-restjson1-protocol.html#operation-error-serialization -function awsErrorType(value: unknown) { - return typeof value === "string" ? [value.replace(/:.*/s, "").replace(/^[^#]*#/, "")] : [] -} diff --git a/packages/ai/src/schema/errors.ts b/packages/ai/src/schema/errors.ts index 89998daab62..aab00a83a18 100644 --- a/packages/ai/src/schema/errors.ts +++ b/packages/ai/src/schema/errors.ts @@ -3,6 +3,7 @@ import { NonNegativeInt } from "@opencode/schema" import { Tool } from "@opencode/schema/tool" import { ProviderID, RouteID } from "./ids.js" import type { LLMResponse } from "./events.js" +import { awsErrorType, providerCodes } from "../utils/provider-codes.js" export const ProviderFailureClassification = Schema.Literals(["context-overflow", "payload-too-large"]) export type ProviderFailureClassification = typeof ProviderFailureClassification.Type @@ -167,6 +168,66 @@ export class AIError extends Schema.TaggedError()("AI.Error", { override get message(): string { return this.reason.message } + + /** HTTP status of the failed response, when the failure came from one. */ + get status(): number | undefined { + return this.reason.http?.status + } + + /** The provider's error code from the response body or `x-amzn-errortype`, or the transport's system error code. */ + get code(): string | undefined { + if (this.reason._tag === "Transport" && this.reason.code !== undefined) return this.reason.code + return [ + ...(this.reason.body === undefined ? [] : providerCodes(this.reason.body)), + ...awsErrorType(this.reason.http?.headers["x-amzn-errortype"]), + ][0] + } + + /** Delay the provider asked for before retrying, from `retry-after` style headers. */ + get retryAfterMs(): number | undefined { + if (this.reason._tag === "RateLimit") return this.reason.retryAfterMs ?? this.reason.rateLimit?.retryAfterMs + if (this.reason._tag === "QuotaExceeded" || this.reason._tag === "ProviderInternal") return this.reason.retryAfterMs + return undefined + } + + /** + * Whether a failed call may succeed when sent again: rate limits, provider-side failures, transport failures that did + * not deliver an accepted write, and unrecognized failures. Callers decide which calls are safe to repeat. + */ + get isRetryable(): boolean { + const override = this.reason.http?.headers["x-should-retry"] + if (override === "true") return true + if (override === "false") return false + switch (this.reason._tag) { + case "RateLimit": + case "ProviderInternal": + return true + // A WebSocket acknowledgment marks delivery accepted before model output may exist. + // Read failures can still recover; the caller chooses retry versus continuation from durable output. + case "Transport": + return ( + this.reason.delivery !== "rejected" && (this.reason.delivery !== "accepted" || this.reason.operation === "read") + ) + case "InvalidProviderOutput": + return this.reason.classification === "incomplete-stream" + // Unrecognized failures retry: classification records affirmative + // deterministic evidence, and transient failures are exactly the ones + // that arrive in shapes no classifier anticipates. + case "UnknownProvider": + return true + case "Authentication": + case "QuotaExceeded": + case "ContentPolicy": + case "InvalidRequest": + case "UnsupportedOperation": + case "Timeout": + return false + default: { + const exhaustive: never = this.reason + return exhaustive + } + } + } } /** Return `error` with `partial` attached, or unchanged when there is no partial output. */ diff --git a/packages/ai/src/utils/provider-codes.ts b/packages/ai/src/utils/provider-codes.ts new file mode 100644 index 00000000000..d6c9d55a3fe --- /dev/null +++ b/packages/ai/src/utils/provider-codes.ts @@ -0,0 +1,43 @@ +import { Option, Schema } from "effect" +import { Json } from "./json.js" +import { isRecord } from "./record.js" + +const decodeJson = Schema.decodeUnknownOption(Json) + +/** Error codes a provider error body carries, in their original case. The first is its primary code (`AIError.code`). */ +export function providerCodes(value: unknown) { + const decoded = typeof value === "string" ? Option.getOrUndefined(decodeJson(value)) : value + if (!isRecord(decoded)) return [] + const error = isRecord(decoded.error) ? decoded.error : undefined + const inner = error && isRecord(error.innererror) ? error.innererror : undefined + const metadata = error && isRecord(error.metadata) ? error.metadata : undefined + const response = isRecord(decoded.response) ? decoded.response : undefined + const responseError = response && isRecord(response.error) ? response.error : undefined + const exception = isRecord(decoded.exception) ? decoded.exception : undefined + return [ + decoded.code, + ...awsErrorType(decoded.__type), + ...awsErrorType(decoded.code), + decoded.error_type, + error?.code, + error?.type, + error?.status, + error?.error_type, + // Google `google.rpc.ErrorInfo` details carry the specific reason. + ...(Array.isArray(error?.details) + ? error.details.map((detail) => (isRecord(detail) ? detail.reason : undefined)) + : []), + inner?.code, + metadata?.error_type, + responseError?.code, + response?.error_type, + exception?.type, + ].filter((value): value is string => typeof value === "string") +} + +// AWS restJson1 reports the modeled error in `X-Amzn-Errortype`, `__type` or `code`, possibly +// namespaced (`ns#Name`) or suffixed (`Name:uri`). Keep the shape name only. +// https://smithy.io/2.0/aws/protocols/aws-restjson1-protocol.html#operation-error-serialization +export function awsErrorType(value: unknown) { + return typeof value === "string" ? [value.replace(/:.*/s, "").replace(/^[^#]*#/, "")] : [] +} diff --git a/packages/ai/test/provider-error.test.ts b/packages/ai/test/provider-error.test.ts index 84c38fa1605..9f25e0cc766 100644 --- a/packages/ai/test/provider-error.test.ts +++ b/packages/ai/test/provider-error.test.ts @@ -1,6 +1,6 @@ import { describe, expect, test } from "bun:test" import { isContextOverflow, isContextOverflowFailure, isRetryable } from "../src/effect.js" -import { AIError, HttpContext } from "../src/schema/index.js" +import { AIError, HttpContext, RateLimitError, TransportError } from "../src/schema/index.js" import { classifyProviderFailure, providerErrorMessage } from "../src/provider-error.js" describe("provider error classification", () => { @@ -716,3 +716,52 @@ describe("provider error messages", () => { ).toEqual([undefined, undefined, undefined, undefined]) }) }) + +describe("AIError getters", () => { + const rateLimit = new AIError({ + reason: new RateLimitError({ + message: "Rate limit reached", + http: new HttpContext({ url: "https://api.test/v1", status: 429, headers: { "retry-after": "2" } }), + retryAfterMs: 2000, + }), + }) + const invalidBody = '{"error":{"message":"model not found","type":"invalid_request_error","code":"model_not_found"}}' + const invalidRequest = new AIError({ + reason: classifyProviderFailure({ + message: providerErrorMessage(invalidBody), + status: 404, + rawBody: invalidBody, + http: new HttpContext({ url: "https://api.test/v1", status: 404, headers: {} }), + }), + }) + const transport = new AIError({ + reason: new TransportError({ message: "socket hang up", transport: "http", operation: "request" }), + }) + + test("status", () => { + expect([rateLimit.status, invalidRequest.status, transport.status]).toEqual([429, 404, undefined]) + }) + + test("code", () => { + expect([rateLimit.code, invalidRequest.code, transport.code]).toEqual([undefined, "model_not_found", undefined]) + expect( + new AIError({ + reason: new TransportError({ message: "reset", transport: "http", operation: "read", code: "ECONNRESET" }), + }).code, + ).toBe("ECONNRESET") + }) + + test("isRetryable", () => { + expect(invalidRequest.reason._tag).toBe("InvalidRequest") + expect([rateLimit.isRetryable, invalidRequest.isRetryable, transport.isRetryable]).toEqual([true, false, true]) + expect([rateLimit, invalidRequest, transport].map(isRetryable)).toEqual([true, false, true]) + }) + + test("retryAfterMs", () => { + expect([rateLimit.retryAfterMs, invalidRequest.retryAfterMs, transport.retryAfterMs]).toEqual([ + 2000, + undefined, + undefined, + ]) + }) +})