fix(ai): preserve raw provider error payload on responses streams (#44271)

packages/ai/src/protocols/open-responses.ts

@@ -61,6 +61,11 @@ const OpenResponsesOutputText = Schema.Struct({
 export const MessagePhase = Schema.NullOr(Schema.Literals(["commentary", "final_answer"]))
 type MessagePhase = Schema.Schema.Type<typeof MessagePhase>
 
+const messagePhase = (value: unknown): MessagePhase | undefined => {
+  if (value === null || value === "commentary" || value === "final_answer") return value
+  return undefined
+}
+
 const OpenResponsesReasoningSummaryText = Schema.Struct({
   type: Schema.tag("summary_text"),
   text: Schema.String,
@@ -242,6 +247,7 @@ const OpenResponsesErrorPayload = Schema.Struct({
   message: optionalNull(Schema.String),
   param: optionalNull(Schema.String),
 })
+type OpenResponsesErrorPayload = Schema.Schema.Type<typeof OpenResponsesErrorPayload>
 
 const WebSocketErrorHeader = Schema.Union([Schema.String, Schema.Number, Schema.Boolean])
 export const WebSocketErrorEvent = Schema.StructWithRest(
@@ -306,20 +312,6 @@ export const Event = Schema.StructWithRest(
 )
 export type Event = Schema.Schema.Type<typeof Event>
 
-const RefusalEvent = Schema.Union([
-  Schema.Struct({
-    type: Schema.tag("response.refusal.delta"),
-    item_id: Schema.String,
-    delta: Schema.String,
-  }),
-  Schema.Struct({
-    type: Schema.tag("response.refusal.done"),
-    item_id: Schema.String,
-    refusal: Schema.String,
-  }),
-])
-const isRefusalEvent = Schema.is(RefusalEvent)
-
 export interface Extension {
   readonly id: string
   readonly name: string
@@ -340,7 +332,6 @@ export interface ParserState {
   readonly hasFunctionCall: boolean
   readonly lifecycle: Lifecycle.State
   readonly messageItems: ReadonlySet<string>
-  readonly messagePhase: (value: unknown) => MessagePhase | null | undefined
   readonly messagePhases: Readonly<Record<string, MessagePhase | null>>
   readonly reasoningItems: Readonly<Record<string, ReasoningStreamItem>>
   readonly store: boolean | undefined
@@ -418,10 +409,6 @@ const lowerReasoning = (part: ReasoningPart, providerMetadataKey: string): OpenR
   }
 }
 
-const hostedToolItemID = (part: ToolResultPart, providerMetadataKey: string) => {
-  return itemID(part.providerMetadata, providerMetadataKey)
-}
-
 const lowerMedia = Effect.fn("OpenResponses.lowerMedia")(function* (
   part: MediaPart,
   request: LLMRequest,
@@ -592,9 +579,9 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (reques
         }
         if (part.type === "tool-result" && part.providerExecuted === true) {
           flushText()
-          const itemID = hostedToolItemID(part, providerMetadataKey)
-          if (store !== false && itemID && !hostedToolReferences.has(itemID))
-            input.push({ type: "item_reference", id: itemID })
+          const id = itemID(part.providerMetadata, providerMetadataKey)
+          if (store !== false && id && !hostedToolReferences.has(id))
+            input.push({ type: "item_reference", id })
           if (store === false && part.result.type === "content") {
             const content: ReadonlyArray<Content> = part.result.value
             input.push({
@@ -604,7 +591,7 @@ const lowerMessages = Effect.fn("OpenResponses.lowerMessages")(function* (reques
               ),
             })
           }
-          if (itemID) hostedToolReferences.add(itemID)
+          if (id) hostedToolReferences.add(id)
           continue
         }
         return yield* ProviderShared.unsupportedContent(extension.name, "assistant", [
@@ -816,18 +803,17 @@ const reasoningMetadata = (state: ParserState, item: StreamItem & { id: string }
 // best-effort, not guaranteed.
 const onOutputItemAdded = (state: ParserState, event: Event): StepResult => {
   const item = event.item
-  if (item?.type === "message" && item.id)
+  if (item?.type === "message" && item.id) {
+    const phase = messagePhase(item.phase)
     return [
       {
         ...state,
         messageItems: new Set([...state.messageItems, item.id]),
-        messagePhases: (() => {
-          const phase = state.messagePhase(item.phase)
-          return phase === undefined ? state.messagePhases : { ...state.messagePhases, [item.id]: phase }
-        })(),
+        messagePhases: phase === undefined ? state.messagePhases : { ...state.messagePhases, [item.id]: phase },
       },
       NO_EVENTS,
     ]
+  }
   if (item && isReasoningItem(item)) {
     const events: LLMEvent[] = []
     return [
@@ -985,7 +971,7 @@ const onOutputItemDone = Effect.fn("OpenResponses.onOutputItemDone")(function* (
   if (!item) return [state, NO_EVENTS] satisfies StepResult
 
   if (item.type === "message" && item.id) {
-    const itemPhase = state.messagePhase(item.phase)
+    const itemPhase = messagePhase(item.phase)
     const phase = itemPhase === undefined ? state.messagePhases[item.id] : itemPhase
     const events: LLMEvent[] = []
     const messageItems = new Set(state.messageItems)
@@ -1093,22 +1079,26 @@ const onResponseFinish = Effect.fn("OpenResponses.onResponseFinish")(function* (
   return [{ ...state, lifecycle, hasFunctionCall, tools: pending.tools }, events] satisfies StepResult
 })
 
-// Build a single human-readable message from whatever the provider supplied.
+// Build the prettiest summary available from whatever the provider supplied.
 // When both code and message are present, prefix the code so consumers see
 // the failure mode (e.g. `rate_limit_exceeded: Slow down`) instead of just
 // the bare message — production rate limits and context-length failures used
-// to be indistinguishable from generic stream drops.
-const providerErrorMessage = (event: Event, fallback: string): string => {
-  const nested = event.error ?? event.response?.error ?? undefined
+// to be indistinguishable from generic stream drops. Returns undefined when
+// the payload carries no usable summary.
+const providerErrorMessage = (event: Event, nested: OpenResponsesErrorPayload | undefined): string | undefined => {
   const message = event.message || nested?.message || undefined
   const code = event.code || nested?.code || undefined
   if (message && code) return `${code}: ${message}`
-  return message || code || fallback
+  return message || code
 }
 
 export const providerFailure = (id: string, event: Event, fallback: string) => {
-  const code = event.code || event.error?.code || event.response?.error?.code || undefined
-  const message = providerErrorMessage(event, fallback)
+  const nested = event.error ?? event.response?.error ?? undefined
+  const code = event.code || nested?.code || undefined
+  // Keep the full raw payload on the error even when the message is a summary.
+  const body = JSON.stringify(nested ?? event) ?? ""
+  const summary = providerErrorMessage(event, nested)
+  const message = summary ?? (body === "{}" ? fallback : body)
   const status =
     typeof event.status === "number"
       ? event.status
@@ -1118,7 +1108,8 @@ export const providerFailure = (id: string, event: Event, fallback: string) => {
   return new AIError({
     module: id,
     method: "stream",
-    reason: classifyProviderFailure({ message, code, status }),
+    body,
+    reason: classifyProviderFailure({ message, code, status, rawBody: body }),
   })
 }
 
@@ -1134,21 +1125,18 @@ export const step = (state: ParserState, event: Event) => {
     )
   }
   if (event.type === "response.refusal.delta" || event.type === "response.refusal.done") {
-    if (!isRefusalEvent(event)) return ProviderShared.eventError(state.id, `${event.type} is malformed`)
+    const value = event.type === "response.refusal.delta" ? event.delta : event.refusal
+    if (!event.item_id || typeof value !== "string") return ProviderShared.eventError(state.id, `${event.type} is malformed`)
     return Effect.succeed(
       event.type === "response.refusal.delta"
         ? onOutputTextDelta(state, event, event.item_id)
-        : onOutputTextDone(state, { ...event, text: event.refusal }, event.item_id),
+        : onOutputTextDone(state, { ...event, text: value }, event.item_id),
     )
   }
   if (event.type === "response.reasoning.delta" || event.type === "response.reasoning_summary_text.delta") {
     if (!event.item_id) return ProviderShared.eventError(state.id, `${event.type} is missing item_id`)
     return Effect.succeed(onReasoningDelta(state, event, event.item_id))
   }
-  if (event.type === "response.reasoning.done" || event.type === "response.reasoning_summary_text.done") {
-    if (!event.item_id) return ProviderShared.eventError(state.id, `${event.type} is missing item_id`)
-    return Effect.succeed(onReasoningDone(state, event))
-  }
   if (event.type === "response.reasoning_summary_part.added")
     return event.item_id
       ? Effect.succeed(onReasoningSummaryPartAdded(state, event))
@@ -1193,17 +1181,11 @@ export const initial = (request: LLMRequest, extension: Extension = BASE): Parse
   tools: ToolStream.empty<string>(),
   lifecycle: Lifecycle.initial(),
   messageItems: new Set<string>(),
-  messagePhase,
   messagePhases: {},
   reasoningItems: {},
   store: OpenResponsesOptions.resolve(request).store,
 })
 
-const messagePhase = (value: unknown): MessagePhase | undefined => {
-  if (value === null || value === "commentary" || value === "final_answer") return value
-  return undefined
-}
-
 export const protocol = Protocol.make({
   id: ADAPTER,
   body: {

packages/ai/src/provider-error.ts

@@ -80,6 +80,9 @@ export interface ProviderFailure {
   readonly message: string
   readonly status?: number | undefined
   readonly code?: string | undefined
+  // Raw wire payload, scanned for failure signals (codes, overflow phrases)
+  // that the summary message does not carry. Not shown to users.
+  readonly rawBody?: string | undefined
   readonly retryAfterMs?: number | undefined
   readonly rateLimit?: HttpRateLimitDetails | undefined
   readonly http?: HttpContext | undefined
@@ -89,11 +92,13 @@ export interface ProviderFailure {
 // Keep HTTP failures and provider-reported stream failures on one typed path so
 // session retry policy never needs provider-specific string matching.
 export function classifyProviderFailure(input: ProviderFailure): AIError["reason"] {
-  const body = input.http?.body ?? ""
+  const body = input.http?.body ?? input.rawBody ?? ""
   const codes = [input.code, ...providerCodes(body), ...providerCodes(input.message)]
     .filter((code): code is string => code !== undefined)
     .map((code) => code.toLowerCase())
-  const text = body || input.message
+  // Scan the raw payload too so signals missing from the summary message
+  // (e.g. overflow phrases nested in a JSON error body) still classify.
+  const text = [input.message, body].filter((value) => value.length > 0).join("\n")
   const common = { message: input.message, providerMetadata: input.providerMetadata, http: input.http }
   const clientScoped = input.status === undefined || (input.status >= 400 && input.status < 500)
 

packages/ai/src/schema/errors.ts

@@ -153,6 +153,9 @@ export class AIError extends Schema.TaggedError<AIError>()("AI.Error", {
   module: Schema.String,
   method: Schema.String,
   reason: AIErrorReason,
+  // Raw provider payload as a string, so classified failures never lose the
+  // original error detail even when the pretty message is a summary.
+  body: Schema.optional(Schema.String),
 }) {
   override readonly cause = this.reason
 

packages/ai/test/provider-error.test.ts

@@ -106,3 +106,20 @@ describe("provider error classification", () => {
     expect(classifyProviderFailure({ message: "not-json" })._tag).toBe("UnknownProvider")
   })
 })
+
+describe("provider error rawBody classification", () => {
+  test("classifies overflow signals buried in the raw payload when the summary is vague", () => {
+    const reason = classifyProviderFailure({
+      message: "Request failed",
+      rawBody: '{"error":{"message":"This model\'s maximum context length is 40960 tokens"}}',
+    })
+    expect(reason._tag).toBe("InvalidRequest")
+    expect(reason).toMatchObject({ classification: "context-overflow" })
+  })
+
+  test("extracts nested codes from the raw payload", () => {
+    expect(
+      classifyProviderFailure({ message: "Request failed", rawBody: '{"error":{"code":"insufficient_quota"}}' })._tag,
+    ).toBe("QuotaExceeded")
+  })
+})

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

@@ -3016,36 +3016,42 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("falls back to a stable default when error is null", () =>
+  it.effect("falls back to the raw payload when error is null", () =>
     Effect.gen(function* () {
       const error = yield* LLMClient.generate(request).pipe(
         Effect.provide(fixedResponse(sseEvents({ type: "error", error: null }))),
         Effect.flip,
       )
 
-      expect(error.reason).toMatchObject({ _tag: "UnknownProvider", message: "OpenAI Responses stream error" })
+      expect(error.reason).toMatchObject({ _tag: "UnknownProvider" })
+      expect(error.reason.message).toContain('"error":null')
+      expect(error.body).toBe(error.reason.message)
     }),
   )
 
-  it.effect("falls back to a stable default when both error and response are absent", () =>
+  it.effect("falls back to the raw payload when both error and response are absent", () =>
     Effect.gen(function* () {
       const error = yield* LLMClient.generate(request).pipe(
         Effect.provide(fixedResponse(sseEvents({ type: "error" }))),
         Effect.flip,
       )
 
-      expect(error.reason).toMatchObject({ _tag: "UnknownProvider", message: "OpenAI Responses stream error" })
+      expect(error.reason).toMatchObject({ _tag: "UnknownProvider" })
+      expect(error.reason.message).toContain('"type":"error"')
+      expect(error.body).toBe(error.reason.message)
     }),
   )
 
-  it.effect("falls back to a stable default when response.failed has no error payload", () =>
+  it.effect("keeps the raw response payload when response.failed has no error payload", () =>
     Effect.gen(function* () {
       const error = yield* LLMClient.generate(request).pipe(
         Effect.provide(fixedResponse(sseEvents({ type: "response.failed", response: { id: "resp_failed_3" } }))),
         Effect.flip,
       )
 
-      expect(error.reason).toMatchObject({ _tag: "UnknownProvider", message: "OpenAI Responses response failed" })
+      expect(error.reason).toMatchObject({ _tag: "UnknownProvider" })
+      expect(error.reason.message).toContain('"resp_failed_3"')
+      expect(error.body).toBe(error.reason.message)
     }),
   )