fix: surface provider error details from Responses API stream failures

[chrarnoldus]

What

Dependency bumps — @ai-sdk/openai 3.0.53 → 3.0.88 in packages/opencode, packages/core, and packages/kilo-gateway; @ai-sdk/azure 3.0.49 → 3.0.93 (opencode/core); and the AI SDK core set in lockstep so no duplicate provider packages result: ai catalog 6.0.168 → 6.0.235, @ai-sdk/gateway 3.0.104 → 3.0.157, @ai-sdk/provider 3.0.8 → 3.0.14, @ai-sdk/provider-utils 4.0.23 → 4.0.40, @ai-sdk/anthropic (kilo-gateway) 3.0.71 → 3.0.82. The lockfile resolves single shared copies for the bumped set.

Error rendering — ProviderError.parseStreamError now recognizes provider stream failures that arrive without the { type: "error" } envelope, via two additions in packages/opencode/src/kilocode/provider/error.ts:

• frame() normalizes the incoming frame with zod schemas: OpenAI Responses API response.failed terminal frames are unwrapped to their inner response.error, envelope-less { error: { code, message } } wrappers and bare { code, message } objects are wrapped in the standard envelope (nested error wins over bare top-level fields, explicit null fields tolerated).
• fallback() handles normalized frames whose error code isn't in the existing switch: any frame with a non-empty error.message renders as a clean APIError instead of a JSON.stringify dump, with retryability kept on par with the Session.retryable heuristics that previously applied (429/5xx numeric or string codes, rate-limit/exhausted/overload-style code and error.type signals, and a narrow rate-limit-only match on free-form message text).

Why

When a Responses API stream ends with a response.failed event (e.g. an upstream 429 rate limit from a gateway), @ai-sdk/openai < 3.0.82 parsed the response.error payload but silently discarded it, ending the stream with a bare finishReason: "error". Kilo then fell back to the generic "The provider ended the response with an error before returning details" notice (KiloSessionProcessor.providerFinishError), hiding actionable messages like "temporarily rate-limited upstream, retry shortly".

@ai-sdk/openai@3.0.82 (vercel/ai commit ae00aeb) fixes the drop: pre-output failures throw an APICallError with the provider's actual message/status, and mid-stream failures enqueue an error chunk with the full response.failed payload. The mid-stream chunk is a plain object, not an Error, so without the frame normalizer it rendered as a raw JSON dump (NamedError.Unknown) — the normalizer routes it into the existing provider-error handling, producing a clean APIError with the provider's message and retryability, preserving the original frame in responseBody.

Version choice

Pins are the newest versions that pass the repo's minimumReleaseAge quarantine (~4.75 days) at PR time; openai 3.0.88 ≥ 3.0.82 so it contains the fix. Azure 3.0.93 adds @ai-sdk/deepseek as a new transitive dependency (2.0.50, quarantine-safe). @ai-sdk/anthropic is quarantine-exempt.

Deliberately out of scope

• @ai-sdk/amazon-bedrock — its 4.0.141 bump also drags bundled @ai-sdk/anthropic 3.0.81 → 3.0.102 (every Claude-on-Bedrock request), which deserves its own PR with a Bedrock smoke test.
• GitHub Copilot Responses — the vendored model in packages/core/src/github-copilot/responses/ has no response.failed handling; porting the upstream fix there is a follow-up. The changeset text is scoped accordingly.
• One stale copy remains under ai-gateway-provider (Vercel AI Gateway optional deps) — a third-party transitive resolution we can't pin from here.

Testing

• packages/opencode/test/kilocode/provider/error.test.ts grows from 5 to 18 tests: the exact response.failed rate-limit payload, envelope-less and bare error objects, nested-error precedence, explicit null fields, unlisted codes, numeric and numeric-string 429/5xx retryability, Anthropic rate_limit_error and resource_exhausted parity with the old heuristics, hyphenated rate-limit prose, and terminal-error messages that merely mention availability.
• Typecheck passes on opencode, core, and kilo-gateway; provider-area tests pass (463/463).

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (1 file)

• packages/opencode/src/kilocode/provider/error.ts

Verification notes / assumptions

• Incremental review of 9245279de5..e07d7d4618 only. The delta is comment-only: the "nested error wins over bare top-level fields" rationale moved from the bare schema to the wrapper schema it actually describes, and the RETRYABLE_TEXT comment was reworded. No executable lines changed, so no new behavior to review.
• Re-checked that the relocated comment matches the code: frame() does try wrapper (line 44) before bare (line 46), so the claim on packages/opencode/src/kilocode/provider/error.ts:22-24 is accurate.
• Earlier findings from prior rounds were already verified as addressed at the previous review and are not carried forward.
• Tests were not executed (read-only mode); CI-enforced checks intentionally not reviewed.

Previous Review Summaries (7 snapshots, latest commit 9245279)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 9245279)

Status: No Issues Found | Recommendation: Merge

Resolved since the previous review

• RETRYABLE_TEXT missed hyphenated rate-limit prose — the pattern now uses the same lazy separators as the code/type pattern (rate.?limit, too.?many.?requests), so the PR's motivating message ("temporarily rate-limited upstream") stays retryable even without a rate_limit_exceeded code or a matching error.type. Covered by the new test at packages/opencode/test/kilocode/provider/error.test.ts:229, which uses a non-matching code (upstream_error) so retryability can only come from the message branch.

Files Reviewed (2 files)

• packages/opencode/src/kilocode/provider/error.ts
• packages/opencode/test/kilocode/provider/error.test.ts

Verification notes / assumptions

• Incremental review of 411f28f118..9245279de5 only; no other files changed in this range, so earlier (already-answered) findings on the dependency bumps, changeset, and src/provider/error.ts are not carried forward.
• Re-traced retryable() at src/kilocode/provider/error.ts:59-70 against the plain-text branch of src/session/retry.ts:90-100. The widened text pattern is a strict superset of the old literal phrases, so no previously-retried error becomes terminal. The extra breadth is limited to one arbitrary separator character between rate/limit and too/many/requests, which does not introduce a new false-positive class beyond what the literal phrases already matched (e.g. "separate limits").
• Fork hygiene unchanged: the whole delta stays inside src/kilocode/ and test/kilocode/.
• Tests were not executed (read-only mode); CI-enforced checks (typecheck, lint, tests, marker guards) intentionally not reviewed.

Previous review (commit 411f28f)

Status: 1 Issue Found | Recommendation: Optional polish; nothing blocking

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	1

Issue Details (click to expand)

SUGGESTION

File	Line	Issue
packages/opencode/src/kilocode/provider/error.ts	54	RETRYABLE_TEXT uses literal-space rate limit / too many requests, which is exact parity with Session.retryable() but stricter than the rate.?limit / too.?many.?requests forms in RETRYABLE. Hyphenated provider prose ("temporarily rate-limited upstream" — the PR's own motivating message) won't match, so such a frame stays terminal if it lacks a rate_limit_exceeded code or a matching error.type. Reusing the lazy separators closes the gap without re-introducing the broad server/unavailable/timeout terms.

Resolved since the previous review

• Null error fields rejected by the zod schemas — payload now uses .nullish() for code/message and bare.code accepts z.null(), so the standard OpenAI shape ({ error: { message, type: "server_error", param: null, code: null } }) and response.failed frames with code: null parse and reach fallback(). Both are covered by new tests (error.test.ts:190, :207).
• Over-broad message retry heuristic — the wide RETRYABLE alternation is now restricted to error.code / error.type, with RETRYABLE_TEXT handling free-form messages. Verified against src/session/retry.ts:90-100: the three phrases match the old plain-text branch exactly, and the new test at error.test.ts:220 pins that "unavailable in your region" no longer retries.

Files Reviewed (2 files)

• packages/opencode/src/kilocode/provider/error.ts - 1 issue
• packages/opencode/test/kilocode/provider/error.test.ts - 0 issues

Verification notes / assumptions

• Incremental review of 31d844a708..411f28f118 only. Dependency/lockfile, changeset, and src/provider/error.ts were unchanged in this range; their earlier findings were all answered and are not carried forward.
• Re-traced every frame() branch and the retryable() code/type/message ladder against parseStreamError (src/provider/error.ts:109-170) with the new nullable shapes: { error: null } still fails terminal, wrapper, and bare, so the "no error payload" case correctly stays a non-APIError; null codes fall through the switch into fallback() and produce a clean message.
• Fork hygiene remains good — the entire delta is inside src/kilocode/ and test/kilocode/.
• Tests were not executed (read-only mode); CI-enforced checks (typecheck, lint, tests, marker guards) intentionally not reviewed.

Fix these issues in Kilo Cloud

Previous review (commit 31d844a)

Status: 2 Issues Found | Recommendation: Address the null-code gap before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	1

Issue Details (click to expand)

WARNING

File	Line	Issue
packages/opencode/src/kilocode/provider/error.ts	12-13	The zod payload schema uses .optional(), which rejects null. OpenAI/gateway error objects routinely send explicit nulls ({ error: { message, type: "server_error", param: null, code: null } }), so wrapper/bare/terminal all fail to parse, frame() returns a body with type still undefined, and parseStreamError bails at the body.type !== "error" gate — reverting to the generic notice this PR removes. .nullish() restores the pre-zod behavior.

SUGGESTION

File	Line	Issue
packages/opencode/src/kilocode/provider/error.ts	66	RETRYABLE.test(message) applies the full alternation (server, unavailable, timeout, overload) to free-form provider prose, while Session.retryable() only matched rate-limit phrases in text and reserved exhausted/unavailable for the parsed code. Terminal errors like "model is unavailable in your region" now retry futilely. Consider a narrow message pattern plus the wide code/type pattern.

Resolved since the previous review

• Retry-classification regression — retryable() (src/kilocode/provider/error.ts:56) now checks numeric and numeric-string codes, the error.type field, and the message, and RETRYABLE gained too.?many.?requests / rate increased too quickly / exhausted. Verified parity against src/session/retry.ts:89-115 for resource_exhausted, Anthropic rate_limit_error, and "429"/"503" string codes; new tests cover all three.
• 5xx test gap — the numeric-code test now loops { code: 429 } and { code: 503 }, exercising both halves of the branch.

Files Reviewed (2 files)

• packages/opencode/src/kilocode/provider/error.ts - 2 issues
• packages/opencode/test/kilocode/provider/error.test.ts - 0 issues (real MessageV2.fromError path, no mocks)

Verification notes / assumptions

• Incremental review of 97792169ee..31d844a708 only; dependency/lockfile, changeset, and src/provider/error.ts were unchanged in this range and not re-reviewed.
• zod is pinned to 4.1.8 in the root catalog, so z.looseObject exists and .optional() is undefined-only (not nullable) — that is the basis for the WARNING above.
• Traced the zod rewrite branch-by-branch against the previous hand-rolled isRecord version; the only behavior narrowing found is value-type strictness on code/message (null and non-string/number values now fall through). Everything else (branch order, nested-error precedence, type: "error" passthrough) is equivalent.
• Fork hygiene is good: the whole change stays inside src/kilocode/, with the shared file limited to the annotated KiloError.fallback() call.
• CI-enforced checks (typecheck, lint, tests, marker guards) intentionally not reviewed.

Fix these issues in Kilo Cloud

Previous review (commit 9779216)

Status: 2 Issues Found | Recommendation: Consider the retry-classification regression before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	1

Issue Details (click to expand)

WARNING

File	Line	Issue
packages/opencode/src/kilocode/provider/error.ts	48	fallback() converts frames that fall past the switch from NamedError.Unknown into APIError, so Session.retryable() short-circuits at retry.ts:80 and never reaches the text/code heuristics at retry.ts:92-116. { code: "resource_exhausted", … } (previously retried via code.includes("exhausted")) and Anthropic-shaped { error: { type: "rate_limit_error", message: "…rate limit…" } } (previously retried via the "rate limit" text match) both become terminal. Numeric-string codes ("429", "503") miss both branches too.

SUGGESTION

File	Line	Issue
packages/opencode/test/kilocode/provider/error.test.ts	152	Test titled "marks numeric 429 and 5xx error codes retryable" only asserts 429; the code >= 500 && code < 600 half of the new branch is untested

Resolved since the previous review

• { error: { code, message } } wrappers fell through the envelope gate — frame() gained an body.type === undefined && isRecord(body.error) branch ordered before the bare-field branch (src/kilocode/provider/error.ts:24), so nested error records win over top-level code/message instead of being overwritten. Verified against the two new tests, which exercise the real MessageV2.fromError path.
• Unlisted error.code values rendered as a raw JSON dump — parseStreamError now ends with KiloError.fallback(body, responseBody) (src/provider/error.ts:170), surfacing the provider message for codes outside the enumerated switch. Message rendering is correct; only the retryability derivation is questioned above.

Files Reviewed (3 files)

• packages/opencode/src/kilocode/provider/error.ts - 1 issue
• packages/opencode/src/provider/error.ts - 0 issues (three added lines, all behind kilocode_change markers, logic delegated to the Kilo module — good fork hygiene)
• packages/opencode/test/kilocode/provider/error.test.ts - 1 issue

Verification notes / assumptions

• Incremental review of 861e2e5bdd..97792169ee only; dependency/lockfile and changeset files were unchanged in this range and not re-reviewed.
• Traced the retry impact end to end rather than from the diff: SessionRetry.policy → retryParse → KiloSessionProcessor.parseError → MessageV2.fromError → Session.retryable(). MessageV2.APIError is SessionV1.APIError, so the isInstance early return in retryable() does apply to the new fallback output.
• Note that retryParse already blocks retries once any text/reasoning/tool output was emitted, so the regression window is pre-output mid-stream failures.
• New tests use the real MessageV2.fromError path with no mocks — good.
• CI-enforced checks (typecheck, lint, tests, marker guards) intentionally not reviewed.

Fix these issues in Kilo Cloud

Previous review (commit 861e2e5)

Status: 2 Issues Found | Recommendation: Suggestions only — safe to merge after considering

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	2

Issue Details (click to expand)

SUGGESTION

File	Line	Issue
packages/opencode/src/kilocode/provider/error.ts	22	The bare-object branch only matches top-level code/message, so the common { error: { code, message } } frame still falls through the type !== "error" guard; it also overwrites a nested error record when both are present, discarding the more specific inner code
packages/opencode/src/provider/error.ts	119	Normalized frames whose error.code isn't one of the six enumerated codes (numeric gateway codes, invalid_api_key, model_not_found, …) still fall through to NamedError.Unknown({ message: JSON.stringify(e) }) — a terminal fallback on a non-empty error.message would cover the rest

Resolved since the previous review

• Mid-stream response.failed rendered as a JSON dump — parseStreamError now normalizes envelope-less frames through KiloError.frame() (packages/opencode/src/provider/error.ts:116). Verified end to end against the real code path: the error stream part becomes Effect.fail(event.error) (packages/opencode/src/session/llm/ai-sdk.ts:274), a plain object reaches the default branch of MessageV2.fromError, and frame() unwraps response.failed → response.error so the rate_limit_exceeded case produces a clean APIError with responseBody still holding the original frame. Existing { type: "error", … } frames are unaffected (frame() third branch is a no-op for them), and the three new tests exercise the real implementation via MessageV2.fromError rather than mocks.
• @ai-sdk/anthropic duplicate subtree in kilo-gateway — pin moved to 3.0.82; the @kilocode/kilo-gateway/@ai-sdk/anthropic subtree (with its own provider 3.0.8 / provider-utils 4.0.23) is gone from bun.lock, and the gateway now shares the top-level @ai-sdk/anthropic@3.0.82 on the pre-existing provider 3.0.10 / provider-utils 4.0.27 subtree — no new copies added.

Files Reviewed (5 files)

• bun.lock - 0 issues (dedup verified: gateway anthropic now shares the top-level copy)
• packages/kilo-gateway/package.json - 0 issues (previous finding resolved)
• packages/opencode/src/kilocode/provider/error.ts - 1 issue
• packages/opencode/src/provider/error.ts - 1 issue
• packages/opencode/test/kilocode/provider/error.test.ts - 0 issues

Verification notes / assumptions

• Incremental review of 0e3ce11862..861e2e5bdd only; files unchanged in this range (changeset, root/opencode/core package.json) were not re-reviewed.
• Fork hygiene looks right: the shared upstream file gains three lines behind one kilocode_change marker, with the logic in src/kilocode/provider/error.ts. Traced all four frame() branches against the three new tests by hand and they behave as asserted, including the error: null case returning undefined and falling back to the previous behavior.
• responseBody is computed from original before normalization, so the raw frame is preserved for diagnostics — good.
• No provider credentials or node_modules here, so the claim that @ai-sdk/openai@3.0.88 emits exactly the tested response.failed chunk shape mid-stream was not verified against the installed package; the parser was verified against the payload as written in the tests.
• CI-enforced checks (typecheck, lint, tests, frozen lockfile, marker/allowlist guards) were intentionally not reviewed.

Fix these issues in Kilo Cloud

Previous review (commit 0e3ce11)

Status: 2 Issues Found | Recommendation: Suggestions only — safe to merge after considering

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	2

Issue Details (click to expand)

SUGGESTION

File	Line	Issue
packages/opencode/package.json	85	Mid-stream response.failed payloads don't match the type === "error" guard in ProviderError.parseStreamError, so that half of the fix still surfaces JSON.stringify(payload) via the NamedError.Unknown fallback instead of the clean provider message the changeset promises
packages/kilo-gateway/package.json	37	@ai-sdk/anthropic@3.0.71 now resolves to its own nested @ai-sdk/provider@3.0.8 / provider-utils@4.0.23 subtree after the top-level move to 3.0.14 / 4.0.40 — extra duplicate copy in the bundled CLI plus provider-spec skew against the newly bumped ai core; aligning to 3.0.82 would collapse it

Resolved since the previous review

• AI SDK core skew — ai (catalog 6.0.235), @ai-sdk/gateway (3.0.157), @ai-sdk/provider (3.0.14) and @ai-sdk/provider-utils (4.0.40) now move in lockstep. Verified in bun.lock: @ai-sdk/openai@3.0.88 and @ai-sdk/azure@3.0.93 both resolve to the single top-level provider pair, and their nested override entries are gone.
• Bedrock blast radius — @ai-sdk/amazon-bedrock is back to 4.0.112, so bundled @ai-sdk/anthropic stays at 3.0.81 and no Claude-on-Bedrock traffic is touched by this PR.
• Changeset overpromise — wording is now scoped to "an OpenAI or Azure Responses API stream", which matches the code: @ai-sdk/azure@3.0.93 depends on exactly @ai-sdk/openai@3.0.88, so the Azure claim holds, and the vendored GitHub Copilot Responses model is correctly excluded.

Files Reviewed (5 files)

• .changeset/responses-stream-error-details.md - 0 issues (previous scoping concern resolved)
• bun.lock - 0 issues (dedup verified end to end; no stale version references remain elsewhere in the repo)
• package.json - 0 issues (ai catalog 6.0.235)
• packages/core/package.json - 0 issues
• packages/kilo-gateway/package.json - 1 issue
• packages/opencode/package.json - 1 issue

Verification notes / assumptions

• The ai core jump (6.0.168 → 6.0.235) is the widest-reaching change here — it sits under every provider, not just OpenAI/Azure — but it is the price of the single-copy dedup requested in the last round, and the PR description documents the tradeoff, so it is not raised as a separate finding. No patchedDependencies entry targets ai, @ai-sdk/openai, or the provider packages, so no patch needs rebasing.
• No workspace package declares a peer or direct pin on @ai-sdk/provider / provider-utils outside packages/opencode and packages/core, and only packages/opencode and packages/kilo-gateway consume the ai catalog entry, so the graph is internally consistent.
• Error-class identity across the remaining duplicated @ai-sdk/provider copies is safe: the code uses APICallError.isInstance(...) (marker-symbol based), not instanceof.
• @ai-sdk/anthropic and @ai-sdk/amazon-bedrock are both listed in minimumReleaseAgeExcludes (bunfig.toml:5), so the Bedrock revert and the gateway Anthropic pin are policy choices rather than quarantine constraints.
• node_modules was not installed and the npm registry was unreachable, so the claim that the installed 3.0.88 bundle contains the fix, the exact response.failed chunk shape emitted mid-stream, and registry publish dates for the quarantine argument were not independently verified.
• CI-enforced checks (typecheck, lint, tests, frozen-lockfile, marker/allowlist guards) were intentionally not reviewed.

Fix these issues in Kilo Cloud

Previous review (commit f695425)

Status: 3 Issues Found | Recommendation: Suggestions only — safe to merge after considering

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	3

Issue Details (click to expand)

SUGGESTION

File	Line	Issue
packages/opencode/package.json	88	@ai-sdk/provider (3.0.8), @ai-sdk/provider-utils (4.0.23) and ai (6.0.168) stay behind the openai 3.0.88 bump — spec skew against the ai core plus duplicate copies in the bundled CLI binary
packages/core/package.json	86	Bedrock 4.0.112 → 4.0.141 also jumps its bundled @ai-sdk/anthropic 3.0.81 → 3.0.102, widening the blast radius to all Claude-on-Bedrock traffic; not mentioned in the PR description
.changeset/responses-stream-error-details.md	5	github-copilot uses the vendored Responses model in packages/core/, which has no response.failed handling — those users still see the generic notice, so the release-note wording overpromises

Files Reviewed (5 files)

• .changeset/responses-stream-error-details.md - 1 issue
• bun.lock - 0 issues (verified resolutions are internally consistent; all three workspace pins match)
• packages/core/package.json - 1 issue
• packages/kilo-gateway/package.json - 0 issues
• packages/opencode/package.json - 1 issue

Verification notes / assumptions

• Confirmed the mid-stream error path actually reaches the user: packages/opencode/src/session/llm/ai-sdk.ts:273 maps an error stream part to Effect.fail(event.error), and packages/opencode/src/session/message-v2.ts:848 falls back to parseStreamError / NamedError.Unknown for non-Error payloads. Note that a raw response.failed payload (type: "response.failed") does not match the body.type !== "error" guard in ProviderError.parseStreamError (packages/opencode/src/provider/error.ts:116), so mid-stream failures may surface as a JSON dump rather than a formatted message — extending that parser would improve the UX the changeset promises.
• Error-class identity across the now-duplicated @ai-sdk/provider copies is safe: the code uses APICallError.isInstance(...) (marker-symbol based), not instanceof.
• The experimental native LLM runtime (packages/llm/src/protocols/openai-responses.ts) already handles response.failed, but it is opt-in behind flags.experimentalNativeLlm, so the ai-sdk bump is the correct fix for the default path.
• node_modules was not installed in this environment and network access to the npm registry was unavailable, so the claim that the installed 3.0.88 bundle contains the fix, and the exact response.failed payload shape emitted mid-stream, were not independently verified.
• CI-enforced checks (typecheck, lint, tests, marker/allowlist guards) were intentionally not reviewed.

Fix these issues in Kilo Cloud

---

_{Reviewed by claude-opus-5 · Input: 22 · Output: 2.6K · Cached: 456.6K}

_{Review guidance: REVIEW.md from base branch main}

[chrarnoldus]