http: surface the server's error body on failed calls and discovery

[h3xxit]

Summary

Python counterpart of universal-tool-calling-protocol/typescript-utcp#44 (which lands typescript-utcp#26), so both SDKs surface the server's error body in the same release.

raise_for_status() raises a ClientResponseError whose message is only the reason phrase (Forbidden). Servers put the real reason in the body, typically {"error": "..."}, and that was discarded, so a refused call or discovery surfaced as nothing more than a status code.

Change: a new raise_for_status_with_body helper reads the body on a 4xx/5xx and raises a ClientResponseError of the same status and headers whose message is <reason>: <detail>. detail is a string error / message / detail field when the body is a JSON object (an object-valued field falls through to the raw JSON so its structure shows, matching the TypeScript behavior), otherwise the raw body, truncated to 2000 characters. The raw text is attached as .body. Used by the HTTP protocol's tool calls and discovery, and by SSE and Streamable HTTP discovery.

The exception type is unchanged, so existing except ClientResponseError handlers keep working; they just see a more useful message.

Test plan

• New tests: body in the tool-call error, object-valued error field shows INVALID_FIELD / value out of range, discovery errors[] carries the body for HTTP, SSE and Streamable HTTP
• pytest plugins/communication_protocols/http/tests: 213 passed

🤖 Generated with Claude Code

---

Summary by cubic

Surfaces the server's error body on failed HTTP calls and discovery so errors include the real reason from the response instead of just the status code.

Bug Fixes

• New raise_for_status_with_body reads the body on 4xx/5xx and includes it in the error message, preferring error/message/detail JSON fields.
• Structured error fields are shown as raw JSON instead of falling back to a generic string; body reads are capped at 64 KiB and fall back to UTF-8 when the charset is missing or unknown.
• Used for tool calls and discovery in HTTP, SSE, and Streamable HTTP protocols; existing ClientResponseError handlers still work.

^{Written for commit badca39. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 7 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="plugins/communication_protocols/http/src/utcp_http/http_communication_protocol.py">

<violation number="1" location="plugins/communication_protocols/http/src/utcp_http/http_communication_protocol.py:214">
P2: `raise_for_status_with_body` buffers the whole error body with `await response.text()` before `error_detail_from_body` truncates the message. The 2000-char cap (MAX_DETAIL_CHARS) only bounds the folded message, not the memory used to read it, so a provider (including an attacker-controlled discovery endpoint, the same trust surface handled elsewhere in this file) returning an arbitrarily large 4xx/5xx body causes an unbounded in-memory buffer on every failed call. Previously `response.raise_for_status()` never touched the body. Read the body incrementally against the cap (e.g. `response.content.iter_chunked`) and stop once MAX_DETAIL_CHARS bytes are collected.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: raise_for_status_with_body buffers the whole error body with await response.text() before error_detail_from_body truncates the message. The 2000-char cap (MAX_DETAIL_CHARS) only bounds the folded message, not the memory used to read it, so a provider (including an attacker-controlled discovery endpoint, the same trust surface handled elsewhere in this file) returning an arbitrarily large 4xx/5xx body causes an unbounded in-memory buffer on every failed call. Previously response.raise_for_status() never touched the body. Read the body incrementally against the cap (e.g. response.content.iter_chunked) and stop once MAX_DETAIL_CHARS bytes are collected.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At plugins/communication_protocols/http/src/utcp_http/http_communication_protocol.py, line 214:

<comment>`raise_for_status_with_body` buffers the whole error body with `await response.text()` before `error_detail_from_body` truncates the message. The 2000-char cap (MAX_DETAIL_CHARS) only bounds the folded message, not the memory used to read it, so a provider (including an attacker-controlled discovery endpoint, the same trust surface handled elsewhere in this file) returning an arbitrarily large 4xx/5xx body causes an unbounded in-memory buffer on every failed call. Previously `response.raise_for_status()` never touched the body. Read the body incrementally against the cap (e.g. `response.content.iter_chunked`) and stop once MAX_DETAIL_CHARS bytes are collected.</comment>

<file context>
@@ -210,7 +211,7 @@ async def register_manual(self, caller, manual_call_template: CallTemplate) -> R
                         auth_header_names=auth_header_names,
                     ) as response:
-                        response.raise_for_status()  # Raise exception for 4XX/5XX responses
+                        await raise_for_status_with_body(response)  # 4XX/5XX, with the server's body in the message
 
                         # Check content type to determine how to parse the response
</file context>

[h3xxit]

Valid, fixed: the body is now read with iter_chunked and the read stops at MAX_BODY_READ_BYTES (64 KiB), decoded leniently with the response charset, so the cap bounds memory and not just the message. Test added with a 1 MiB error body asserting both the read and the message stay bounded.

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>