security(websocket): agent RuntimeError text is surfaced verbatim to public chat visitors

[codeacme17]

Problem

When an agent turn fails with a RuntimeError, its text is sent to the client twice — as the message_rejected ack and as an error event — and the frontend renders both verbatim:

• src/xagent/web/api/websocket.py: message = f"Runtime error: {str(e)}" in _handle_chat_message_unserialized and in handle_execute_task.
• frontend/src/contexts/app-context-chat.tsx:882 reads the string unchanged and :5578 renders it as an assistant error bubble.

The same handler serves widget and share connections, so an anonymous visitor can receive whatever a runtime failure happened to interpolate — provider payloads, file paths, driver messages.

Why this is not just a bug fix

Surfacing that text is a deliberate, tested contract: tests/web/api/test_websocket_owner_actor.py:2260 asserts "inject failed" in rejected[0]["message"], i.e. an agent post_user_message failure must reach the sender. For an authenticated operator debugging their own task, that is useful. For an anonymous widget visitor, it is disclosure.

So the fix is not "redact it" — it is deciding who may see it, which is a product call:

• redact for public widget/share connections and keep the current text for authenticated owners, or
• introduce a safe_for_display / stable error-code field on the wire and localize codes on the client, keeping raw text out of every path.

Already done

#1472 fixed the neighbouring half: incidental ValueError/KeyError/TypeError text is now replaced with CLIENT_SAFE_VALIDATION_ERROR, while messages genuinely written for the sender raise ClientVisibleValidationError and keep their wording (tests/web/api/test_websocket_client_safe_errors.py). The RuntimeError path was left untouched on purpose, because changing it means changing the pinned contract above.

Context

Raised as finding N3 in the #1472 review. Related: #1468, #1467.

[codeacme17]

Adding a consumer-side consequence found in the #1472 review, since it lands on the same contract this issue proposes.

message_rejected text is now surfaced verbatim in the clarification form (that was the point of #1468's second leg). Because the wire carries prose and not a code, a backend rejection written in English — "A previous guidance message is still being applied. Please wait for it to finish." — renders untranslated inside an otherwise fully localized Chinese form. Only the surrounding hint is translated.

There is no client-side fix that keeps the feature: the frontend cannot tell a localized message from an unlocalized one, so "only mark already-localized messages as user-facing" degenerates into never showing the reason at all, which is the bug #1468 set out to fix.

The safe_for_display / stable error-code contract this issue proposes solves both at once: codes are what let the client both trust the message and translate it. Worth designing the field with localization in mind rather than as a boolean — an enum the client maps to i18n keys, with the prose kept as a developer-facing fallback.

Raised as P5 in the #1472 review and deliberately not patched there.

[codeacme17]

Baseline correction — the "Already done" note credits #1472 for work that is in #1514.

This issue says "Already done: #1472 fixed the neighbouring half … (tests/web/api/test_websocket_client_safe_errors.py)". That test file and the client_safe_error_message chokepoint are not in #1472, which is still open; they were split out into #1514.

Also relevant to the contract described here: #1514 anchors the RuntimeError carve-out to (function, expression) rather than to unparsed source text. The previous form blessed f"Runtime error: {str(e)}" anywhere it appeared, which silently covered five sites rather than the two this issue names, and would have blessed a sixth pasted into a validation branch. The five currently allowlisted are _handle_chat_message_unserialized, handle_execute_task, handle_intervention, _handle_pause_task_unserialized, _handle_resume_task_unserialized.

Worth noting for scoping this issue: handle_intervention is reachable by anonymous share/widget visitors, which is broader than the post_user_message-only contract described here.