Skip to content

Commit 497a24c

Browse files
authored
refactor(ai): consolidate provider error diagnostics (#45381)
1 parent f152100 commit 497a24c

52 files changed

Lines changed: 1889 additions & 926 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎packages/ai/AGENTS.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,14 @@ Per-type constructors live on the type, not as top-level re-exports. Use `Messag
1919
- Use `testEffect(...)` from `test/lib/effect.ts` for tests requiring Effect layers.
2020
- Keep provider tests fixture-first. Live provider calls must stay behind `RECORD=true` and required API-key checks.
2121

22+
## Errors
23+
24+
- `AIError` wraps a union of tagged reason errors. It stores only `reason`, derives `message` from the reason, and exposes the reason as its `cause`.
25+
- Each reason owns its readable `message`, category-specific fields, and optional `body`, `http`, and underlying exception in `cause`.
26+
- `reason.body` is the sole original-response or triggering-event payload field. Preserve original text before schema decoding removes fields; do not replace the complete event with only its nested error.
27+
- `reason.http` describes an observed HTTP response with required `url`, `status`, and response `headers`. Do not invent status codes or derive a separate request ID from headers.
28+
- Reclassification and transport recovery must preserve the reason's body, HTTP context, and underlying cause. Error `message` and `cause` are non-enumerable: copy them explicitly when constructing an enriched reason with its constructor or `AIErrorReason.make`.
29+
2230
## Architecture
2331

2432
This package is an Effect Schema-first LLM core. The Schema classes in `src/schema/` are the canonical runtime data model. Convenience functions in `src/llm.ts` are thin constructors that return those same Schema class instances; they should improve callsites without creating a second model.

‎packages/ai/src/image.ts‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { Effect, Schema } from "effect"
22
import {
33
HttpOptions,
4-
InvalidRequestReason,
4+
InvalidRequestError,
55
AIError,
66
ModelID,
77
ProviderID,
@@ -158,9 +158,10 @@ export function generate(input: ImageRequest | ImageRequestInput) {
158158
try: () => (input instanceof ImageRequest ? input : request(input)),
159159
catch: (error) =>
160160
new AIError({
161-
module: "Image",
162-
method: "generate",
163-
reason: new InvalidRequestReason({ message: error instanceof Error ? error.message : String(error) }),
161+
reason: new InvalidRequestError({
162+
message: error instanceof Error ? error.message : String(error),
163+
cause: error,
164+
}),
164165
}),
165166
}).pipe(Effect.flatMap((request) => ImageClient.generate(request as unknown as ImageRequestFor<ImageOptions>)))
166167
}

‎packages/ai/src/llm.ts‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import { LLMClient, Service } from "./route/client.js"
33
import {
44
GenerationOptions,
55
HttpOptions,
6-
InvalidProviderOutputReason,
6+
InvalidProviderOutputError,
77
AIError,
88
LLMEvent,
99
LLMRequest,
@@ -116,20 +116,17 @@ const runGenerateObject = Effect.fn("LLM.generateObject")(function* (
116116
)
117117
if (!call || !LLMEvent.is.toolCall(call))
118118
return yield* new AIError({
119-
module: "LLM",
120-
method: "generateObject",
121-
reason: new InvalidProviderOutputReason({
119+
reason: new InvalidProviderOutputError({
122120
message: `generateObject: model did not call the forced \`${GENERATE_OBJECT_TOOL_NAME}\` tool`,
123121
}),
124122
})
125123
const object = yield* tool._decode(call.input).pipe(
126124
Effect.mapError(
127125
(error) =>
128126
new AIError({
129-
module: "LLM",
130-
method: "generateObject",
131-
reason: new InvalidProviderOutputReason({
127+
reason: new InvalidProviderOutputError({
132128
message: `generateObject: tool input failed schema decode: ${error.message}`,
129+
cause: error,
133130
}),
134131
}),
135132
),

‎packages/ai/src/protocols/anthropic-messages.ts‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1387,14 +1387,15 @@ const providerErrorMessage = (event: AnthropicEvent): string => {
13871387
return message || type || "Anthropic Messages stream error"
13881388
}
13891389

1390-
const onError = (event: AnthropicEvent) =>
1391-
Effect.fail(
1390+
const onError = (event: AnthropicEvent) => {
1391+
const message = providerErrorMessage(event)
1392+
const body = ProviderShared.encodeJson(event)
1393+
return Effect.fail(
13921394
new AIError({
1393-
module: ADAPTER,
1394-
method: "stream",
1395-
reason: classifyProviderFailure({ message: providerErrorMessage(event), code: event.error?.type }),
1395+
reason: classifyProviderFailure({ message, rawBody: body }),
13961396
}),
13971397
)
1398+
}
13981399

13991400
const isKnownStreamBlockType = (type: string) =>
14001401
type === "text" ||

‎packages/ai/src/protocols/bedrock-converse.ts‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -645,15 +645,13 @@ const step = (state: ParserState, event: BedrockEvent) =>
645645
}
646646

647647
if (event.exception) {
648+
const message =
649+
event.exception.details.message ?? event.exception.details.originalMessage ?? "Bedrock Converse stream error"
650+
const body = ProviderShared.encodeJson(event)
648651
return yield* new AIError({
649-
module: ADAPTER,
650-
method: "stream",
651652
reason: classifyProviderFailure({
652-
message:
653-
event.exception.details.message ??
654-
event.exception.details.originalMessage ??
655-
"Bedrock Converse stream error",
656-
code: event.exception.type,
653+
message,
654+
rawBody: body,
657655
}),
658656
})
659657
}

‎packages/ai/src/protocols/bedrock-event-stream.ts‎

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import { EventStreamCodec } from "@smithy/eventstream-codec"
22
import { fromUtf8, toUtf8 } from "@smithy/util-utf8"
3-
import { Effect, Stream } from "effect"
3+
import { Effect, Encoding, Stream } from "effect"
4+
import { AIError, AIErrorReason } from "../schema/index.js"
45
import { Framing } from "../route/framing.js"
56
import { ProviderShared } from "./shared.js"
67

@@ -49,10 +50,14 @@ const consumeFrames = (route: string) => (state: FrameBufferState, chunk: Uint8A
4950
`Failed to decode Bedrock Converse event-stream frame: ${
5051
error instanceof Error ? error.message : String(error)
5152
}`,
53+
Encoding.encodeBase64(view.subarray(0, totalLength)),
54+
error,
5255
),
5356
})
5457
cursor = { buffer: cursor.buffer, offset: cursor.offset + totalLength }
5558

59+
const payload = utf8.decode(decoded.body)
60+
const body = ProviderShared.encodeJson({ headers: decoded.headers, body: payload })
5661
const messageType = decoded.headers[":message-type"]?.value
5762
if (messageType === "error") {
5863
const code = decoded.headers[":error-code"]?.value
@@ -61,6 +66,7 @@ const consumeFrames = (route: string) => (state: FrameBufferState, chunk: Uint8A
6166
route,
6267
[code, message].filter((value): value is string => typeof value === "string").join(": ") ||
6368
"Bedrock Converse event-stream error",
69+
body,
6470
)
6571
}
6672
const eventType =
@@ -70,7 +76,6 @@ const consumeFrames = (route: string) => (state: FrameBufferState, chunk: Uint8A
7076
? decoded.headers[":exception-type"]?.value
7177
: undefined
7278
if (typeof eventType !== "string") continue
73-
const payload = utf8.decode(decoded.body)
7479
if (!payload) continue
7580
// The AWS event stream pads short payloads with a `p` field. Drop it
7681
// before handing the object to the chunk schema. JSON decode goes
@@ -80,11 +85,21 @@ const consumeFrames = (route: string) => (state: FrameBufferState, chunk: Uint8A
8085
route,
8186
payload,
8287
"Failed to parse Bedrock Converse event-stream payload",
88+
).pipe(
89+
Effect.mapError(
90+
(error) =>
91+
new AIError({
92+
reason: AIErrorReason.make({ ...error.reason, message: error.message, cause: error.reason.cause, body }),
93+
}),
94+
),
8395
)) as Record<string, unknown>
8496
delete parsed.p
85-
out.push(
86-
messageType === "exception" ? { exception: { type: eventType, details: parsed } } : { [eventType]: parsed },
87-
)
97+
out.push({
98+
...(messageType === "exception"
99+
? { exception: { type: eventType, details: parsed } }
100+
: { [eventType]: parsed }),
101+
rawBody: body,
102+
})
88103
}
89104
return [cursor, out] as const
90105
})
@@ -97,6 +112,7 @@ const consumeFrames = (route: string) => (state: FrameBufferState, chunk: Uint8A
97112
*/
98113
export const framing = (route: string): Framing.Definition<object> => ({
99114
id: "aws-event-stream",
115+
body: (frame) => ("rawBody" in frame && typeof frame.rawBody === "string" ? frame.rawBody : undefined),
100116
frame: (bytes) => bytes.pipe(Stream.mapAccumEffect(() => initialFrameBuffer, consumeFrames(route))),
101117
})
102118

‎packages/ai/src/protocols/gemini.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import { Endpoint } from "../route/endpoint.js"
66
import { Framing } from "../route/framing.js"
77
import { Protocol } from "../route/protocol.js"
88
import {
9+
AIError,
910
LLMEvent,
1011
Usage,
1112
type FinishReason,
@@ -17,6 +18,7 @@ import {
1718
type ToolCallPart,
1819
type ToolDefinition,
1920
} from "../schema/index.js"
21+
import { classifyProviderFailure } from "../provider-error.js"
2022
import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared.js"
2123
import { GeminiToolSchema } from "./utils/gemini-tool-schema.js"
2224
import { Lifecycle } from "./utils/lifecycle.js"
@@ -221,6 +223,7 @@ const GeminiPromptFeedback = Schema.StructWithRest(
221223
type GeminiPromptFeedback = Schema.Schema.Type<typeof GeminiPromptFeedback>
222224

223225
const GeminiEvent = Schema.Struct({
226+
error: Schema.optional(Schema.Unknown),
224227
candidates: optionalNull(Schema.Array(GeminiCandidate)),
225228
promptFeedback: optionalNull(GeminiPromptFeedback),
226229
usageMetadata: optionalNull(GeminiUsage),
@@ -598,6 +601,18 @@ const finish = (state: ParserState): ReadonlyArray<LLMEvent> => {
598601
}
599602

600603
const step = (state: ParserState, event: GeminiEvent) => {
604+
if (ProviderShared.isRecord(event.error) && typeof event.error.message === "string") {
605+
const body = ProviderShared.encodeJson(event)
606+
return Effect.fail(
607+
new AIError({
608+
reason: classifyProviderFailure({
609+
message: event.error.message,
610+
status: typeof event.error.code === "number" ? event.error.code : undefined,
611+
rawBody: body,
612+
}),
613+
}),
614+
)
615+
}
601616
const nextState = {
602617
...state,
603618
promptFeedback: event.promptFeedback ?? state.promptFeedback,

‎packages/ai/src/protocols/google-images.ts‎

Lines changed: 11 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,7 @@ import {
99
type ImageRoute,
1010
} from "../image.js"
1111
import { Auth, type Definition as AuthDefinition } from "../route/auth.js"
12-
import {
13-
InvalidProviderOutputReason,
14-
AIError,
15-
Usage,
16-
mergeHttpOptions,
17-
mergeJsonRecords,
18-
type HttpOptions,
19-
type ProviderMetadata,
20-
} from "../schema/index.js"
12+
import { AIError, Usage, mergeHttpOptions, mergeJsonRecords, type HttpOptions } from "../schema/index.js"
2113
import { ProviderShared } from "./shared.js"
2214
import { ImageInputs } from "./utils/image-input.js"
2315

@@ -124,13 +116,6 @@ const nativeOptions = (options: GoogleImageOptions | undefined) => {
124116
)
125117
}
126118

127-
const invalidOutput = (message: string, providerMetadata?: ProviderMetadata) =>
128-
new AIError({
129-
module: ADAPTER,
130-
method: "generate",
131-
reason: new InvalidProviderOutputReason({ message, route: ADAPTER, providerMetadata }),
132-
})
133-
134119
const applyQuery = (url: string, query: Record<string, string> | undefined) => {
135120
if (!query) return url
136121
const next = new URL(url)
@@ -169,11 +154,9 @@ export const model = (input: ModelInput) => {
169154
HttpClientRequest.bodyText(text, "application/json"),
170155
),
171156
)
172-
const payload = yield* response.json.pipe(
173-
Effect.mapError(() => invalidOutput("Failed to read the Google Images response")),
174-
)
175-
const decoded = yield* Schema.decodeUnknownEffect(GoogleImageResponse)(payload).pipe(
176-
Effect.mapError(() => invalidOutput("Google Images returned an invalid response")),
157+
const output = yield* ProviderShared.imageResponse(ADAPTER, "Google Images", response)
158+
const decoded = yield* Schema.decodeUnknownEffect(Schema.fromJsonString(GoogleImageResponse))(output.body).pipe(
159+
Effect.mapError((cause) => output.invalid("Google Images returned an invalid response", cause)),
177160
)
178161
const candidates = decoded.candidates ?? []
179162
const candidateMetadata = candidates.map((candidate, candidateIndex) => ({
@@ -208,9 +191,10 @@ export const model = (input: ModelInput) => {
208191
)
209192
const images = yield* Effect.forEach(encoded, (item) =>
210193
Effect.fromResult(Encoding.decodeBase64(item.inlineData.data)).pipe(
211-
Effect.mapError(() =>
212-
invalidOutput(
194+
Effect.mapError((cause) =>
195+
output.invalid(
213196
`Google Images candidate ${item.candidateIndex} part ${item.partIndex} contains invalid base64 data`,
197+
cause,
214198
),
215199
),
216200
Effect.map(
@@ -237,16 +221,10 @@ export const model = (input: ModelInput) => {
237221
const finishReasons = candidates.flatMap((candidate) =>
238222
candidate.finishReason === undefined ? [] : [candidate.finishReason],
239223
)
240-
return yield* invalidOutput(
224+
return yield* output.invalid(
241225
`Google Images returned no final images${
242226
finishReasons.length === 0 ? "" : ` (finish reasons: ${finishReasons.join(", ")})`
243-
}; inspect reason.providerMetadata.google for prompt feedback and candidate details`,
244-
{
245-
google: {
246-
promptFeedback: decoded.promptFeedback,
247-
candidates: candidateMetadata,
248-
},
249-
},
227+
}; inspect body for prompt feedback and candidate details`,
250228
)
251229
}
252230
const usage = decoded.usageMetadata
@@ -290,12 +268,11 @@ const googleImagePart = (image: ImageInput): Effect.Effect<Record<string, unknow
290268
return Effect.succeed({ inlineData: { mimeType: image.mediaType, data: Encoding.encodeBase64(image.data) } })
291269
if (image.type === "file-uri") return Effect.succeed({ fileData: { mimeType: image.mediaType, fileUri: image.uri } })
292270
if (image.type === "url")
293-
return ImageInputs.decodeDataUrl(image.url, ADAPTER).pipe(
271+
return ImageInputs.decodeDataUrl(image.url).pipe(
294272
Effect.flatMap((decoded) => {
295273
if (decoded === undefined)
296274
return Effect.fail(
297275
ImageInputs.invalid(
298-
ADAPTER,
299276
"Google generateContent does not fetch public image URLs; use bytes, a data URL, or a Gemini file URI",
300277
),
301278
)
@@ -305,7 +282,7 @@ const googleImagePart = (image: ImageInput): Effect.Effect<Record<string, unknow
305282
}),
306283
)
307284
return Effect.fail(
308-
ImageInputs.invalid(ADAPTER, "Google generateContent requires Gemini file URIs rather than provider file IDs"),
285+
ImageInputs.invalid("Google generateContent requires Gemini file URIs rather than provider file IDs"),
309286
)
310287
}
311288

0 commit comments

Comments
 (0)