Summary

What problem does this PR solve?

• Fix classification: Root-cause fix for the agent-runtime proxy error-response parser reading unbounded JSON bodies.
• Root cause: The root cause was that the non-OK /api/stream proxy response path called Response.json() directly, so the parser had to read and decode the complete error body before the proxy client could fall back to the HTTP status message.
• Why this is root-cause fix: This fixes the parser/source invariant by routing proxy error JSON through readProviderJsonResponse, the existing bounded JSON response reader backed by readResponseWithLimit, instead of adding a downstream fallback after the unbounded read already happened.
• Patch quality notes: The code diff remains unchanged from the submitted PR: an XS scoped proxy error-branch change, reuse of the canonical bounded reader, preserved status/statusText fallback for malformed or oversized bodies, and deterministic regression coverage for the oversized-body path.

Why does this matter now?

• Why it matters / User impact: Users and operators keep the same visible proxy error behavior for normal failures, while a bad proxy or intermediary can no longer force the client process to buffer an arbitrary-size error body before surfacing the failure.

What is the intended outcome?

• Maintainer-ready confidence: High; the code is unchanged from the previous submitted head, local focused tests pass, a new real local HTTP proxy proof directly addresses ClawSweeper RF-001 through RF-004, and local verification is bound to the current PR head.

What is intentionally out of scope?

• What did NOT change: This does not change auth credentials, provider configuration, session state, schema, migrations, proxy protocol, successful SSE stream parsing, or normal small { "error": "..." } error extraction.
• Out of scope: Successful streaming response buffering and live external proxy network behavior are not changed; this PR only fixes and proves the non-OK proxy error JSON parsing branch.

What does success look like?

The proxy client reports the existing Proxy error: 502 Bad Gateway fallback for an oversized malformed JSON error response, and the real local HTTP proxy observes the client closing the response before the full oversized body is sent.

What should reviewers focus on?

• Architecture / source-of-truth check: readProviderJsonResponse is already the source-of-truth helper for bounded provider JSON parsing, so this proxy path now follows the same response-size invariant instead of maintaining a separate limit.
• Related open PR / same-contract scan: check-upstream-fixed found origin/main has not covered this PR and has no overlapping files with the PR diff; newer main changes are unrelated media/plugin/state work.

Linked context

Which issue does this close?

No linked issue number; this PR is based on the reported proxy error-response path.

Which issues, PRs, or discussions are related?

Related: ClawSweeper comment requiring real proxy/gateway proof for PR #97351.

Was this requested by a maintainer or owner?

No maintainer request was linked in the local task context.

Real behavior proof (required for external PRs)

• Behavior or issue addressed: A non-OK /api/stream proxy error response with a very large JSON body should return the proxy error result without reading the whole error stream into memory.

• Real environment tested: Local OpenClaw agent runtime loaded from this PR head, using the real streamProxy implementation and a real local HTTP proxy server listening on 127.0.0.1 for /api/stream.

• Exact steps or command run after this patch: node --import tsx <local real-proxy proof script>

• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output):

  Real proxy proof: local HTTP proxy returned oversized non-OK JSON body
  request_path=/api/stream
  response_status=502 Bad Gateway
  client_error_message=Proxy error: 502 Bad Gateway
  chunks_planned=24
  chunk_size_bytes=1048576
  chunks_sent_before_close=18
  bytes_sent_before_close=18874368
  connection_closed_before_full_body=true
  bounded_fallback_without_full_read=true
  

• Observed result after fix: The real local proxy planned to stream 24 MiB but observed the client connection close after 18 MiB, while the client surfaced Proxy error: 502 Bad Gateway; this shows the bounded reader stopped the oversized non-OK body before the full response was consumed.

• What was not tested: No external hosted proxy service was called; the proof uses a real local HTTP proxy endpoint to avoid credentials and non-public infrastructure while exercising the real client fetch path.

• Proof limitations or environment constraints: The proof is a localhost proxy/gateway simulation for the client-side parser boundary, not a full deployed OpenClaw gateway run; it directly covers the failure ClawSweeper requested: oversized non-OK proxy body, bounded fallback, and early connection close.

• Before evidence (optional but encouraged): The regression test failed before the fix with expected 20 to be less than 20, showing the old path read all twenty 1 MiB chunks in the controlled streaming Response case.

Tests and validation

Which commands did you run?

• Target test file: src/agents/runtime/proxy.test.ts via pnpm exec vitest run src/agents/runtime/proxy.test.ts.

What regression coverage was added or updated?

• Scenario locked in: A 502 Bad Gateway proxy response with Content-Type: application/json streams oversized chunks; the proxy must return the fallback error and stop reading before the complete body is consumed.

What failed before this fix, if known?

• Why this is the smallest reliable guardrail: The test exercises the actual streamProxy non-OK response branch and response-reader boundary directly, while the new real local proxy proof exercises the same branch through a real HTTP server and Node fetch path.

If no test was added, why not?

A regression test was added in src/agents/runtime/proxy.test.ts; the current update adds PR-visible proof only and does not change production code.

Risk checklist

Did user-visible behavior change? (Yes/No)

No for normal proxy errors; oversized or malformed JSON error bodies now stop at the bounded reader and keep the existing status/statusText fallback.

Did config, environment, or migration behavior change? (Yes/No)

No.

Did security, auth, secrets, network, or tool execution behavior change? (Yes/No)

No; the touched code is proxy/provider-adjacent, but it only changes how non-OK error response bodies are parsed after fetch returns.

What is the highest-risk area?

• Risk labels considered: auth-provider, compatibility, session-state.
• Risk explanation: The auth-provider signal comes from touching the agent proxy/provider-adjacent path. Compatibility and session-state are not touched by this PR's two changed files.

How is that risk mitigated?

• Why acceptable: The committed diff only changes src/agents/runtime/proxy.ts and src/agents/runtime/proxy.test.ts, does not touch config/schema/session/auth storage, preserves existing fallback messages, and now includes a real local proxy proof showing early close before full oversized body consumption.

Current review state

What is the next action?

Ready for ClawSweeper/maintainer re-review after this PR body update with real proxy proof.

What is still waiting on author, maintainer, CI, or external proof?

RF-001, RF-002, and RF-003 are addressed by the real local HTTP proxy proof above; RF-004 is addressed because no code repair job is needed and this update only supplies contributor proof.

Which bot or reviewer comments were addressed?

Addressed ClawSweeper comment #97351 (comment): added redacted real local proxy output showing bounded fallback and early connection close for an oversized non-OK response body.