Sub-issue of #679.
Goal
Eliminate the dual-shape status_data.error payload (single dict vs. {collection: [...]} for MultiAgentError) by always emitting a flat errors: list[ErrorDetail].
Background
Currently src/ai/backend/manager/exceptions.py:101-143 (convert_to_status_data) produces one of two incompatible shapes depending on whether the cause is a MultiAgentError. Consumers must shape-sniff at runtime — see src/ai/backend/manager/event_dispatcher/handlers/session.py:232-235:
if status_data["error"]["name"] == "MultiAgentError":
errors = status_data["error"]["collection"]
else:
errors = [status_data["error"]]
Scope
Backward-compatible rollout (so backend.ai-webui can migrate independently):
- Modify
convert_to_status_data to return both:
- The legacy
error: ErrorDetail field (unchanged, for backward compat)
- A new
errors: list[ErrorDetail] field (always flat — single errors are a 1-element list, MultiAgentError is the flattened collection)
- Update the manager-internal consumer at
event_dispatcher/handlers/session.py:232-235 to read errors first, fall back to shape-sniffing only if missing.
- Add deprecation note for the legacy
error field; plan removal in a later release after backend.ai-webui migrates.
Non-goals
Acceptance criteria
JIRA Issue: BA-5865
Sub-issue of #679.
Goal
Eliminate the dual-shape
status_data.errorpayload (single dict vs.{collection: [...]} forMultiAgentError) by always emitting a flaterrors: list[ErrorDetail].Background
Currently
src/ai/backend/manager/exceptions.py:101-143(convert_to_status_data) produces one of two incompatible shapes depending on whether the cause is aMultiAgentError. Consumers must shape-sniff at runtime — seesrc/ai/backend/manager/event_dispatcher/handlers/session.py:232-235:Scope
Backward-compatible rollout (so backend.ai-webui can migrate independently):
convert_to_status_datato return both:error: ErrorDetailfield (unchanged, for backward compat)errors: list[ErrorDetail]field (always flat — single errors are a 1-element list,MultiAgentErroris the flattened collection)event_dispatcher/handlers/session.py:232-235to readerrorsfirst, fall back to shape-sniffing only if missing.errorfield; plan removal in a later release after backend.ai-webui migrates.Non-goals
status_dataentries (separate sub-issue, see Define a structured JSON schema for transporting kernel status data to backend.ai-webui #679 Step 4).Acceptance criteria
convert_to_status_dataalways emitserrors: list[ErrorDetail]in addition to legacyerror.event_dispatcher/handlers/session.pyconsumeserrorsfirst.MultiAgentError→ flattened list; debug mode preserves traceback / agent_id per entry.JIRA Issue: BA-5865