M5.2 — Q&A WebSocket endpoint

[zestones]

Note

Milestone: M5 — Work Order Generator + Q&A
Planning doc: docs/planning/M5-workorder-qa/issues.md

Scope. backend/agents/qa_agent.py + route dans main.py :

• WS /api/v1/agent/chat
• Stateful per connection : maintient messages: list côté serveur
• Tools : tools = await mcp_client.get_tools_schema() + UI_TOOLS + [ASK_INVESTIGATOR_TOOL]
  (M5.2 est le fallback impl des M5.4 Managed Agents — même toolset)
• Sur message client {type: "user", content: str} :
  • Append au history
  • Lance agent loop avec tools + Anthropic streaming
  • Pour chaque event reçu de l'API Anthropic :
    • Si content_block_delta text → envoie {type: "text_delta", content: ...} au client
    • Si tool_use block avec render_* → broadcast ui_render + envoie {type: "ui_render", component, props} au client
    • Si tool_use block avec ask_investigator → broadcast agent_handoff + spawn mini-session Investigator
      • envoie {type: "agent_handoff", from: "qa", to: "investigator", reason} au client
    • Si tool_use autre → envoie {type: "tool_call", name, args} + appelle mcp_client.call_tool()
      • envoie {type: "tool_result", name, ...}
  • À end_turn → envoie {type: "done"}

System prompt. "Tu es ARIA, assistant maintenance. Réponds aux questions de
l'opérateur sur ses équipements en utilisant les tools. Cite toujours les sources
(KB, logbook, signaux, RCA passés)."

Note

Decided — frontend gère le multi-tour.
Le ChatPanel (M6.5) affiche les
blocs dans l'ordre reçu : text_delta accumule dans une bulle assistant en
cours, tool_call crée une carte collapsable inline, tool_result enrichit la
carte, puis nouveau text_delta crée une nouvelle bulle. Événement done libre
l'input. Pattern éprouvé (Claude.ai, Cursor) — pas de risque.

Note

Decided — auth via cookie + decode manuel.
Au handshake :

token = ws.cookies.get("access_token")
try:
    payload = decode_jwt(token)
    user_id = payload["sub"]
except Exception:
    await ws.close(code=4401)
    return
await ws.accept()

Helper réutilisable core/security/ws_auth.py (même fonction utilisée par
WS /api/v1/events en M4.1).

Acceptance.

• wscat -c ws://localhost:8000/api/v1/agent/chat (avec cookie auth) → question "OEE de la pompe P-02 ce mois ?" → stream texte cohérent + tool_call get_oee visible — unit path fully covered by test_mcp_tool_call_streams_tool_call_and_result_summary (drives a fake messages.stream through the get_oee tool and asserts the client receives tool_call → tool_result → text_delta in order). Live E2E requires docker compose up + Sonnet key.
• (added) Auth handshake: missing/invalid cookie closes with code 4401 — test_unauth_handshake_closes_without_calling_run_turn confirms the agent loop never runs unauthenticated.
• (added) Per-connection messages: list state grows across user turns — verified in router test by passing the same list to two consecutive turns.
• (added) ChatMap.tool_result.summary is a short string — _summarise_tool_result + test_summarise_tool_result_handles_list_dict_scalar_error pin the contract; raw tool JSON never reaches the chat channel.
• (added) Dual-channel broadcast for ui_render and agent_handoff — events-bus uses from_agent/to_agent, chat channel uses from/to per ws.types.ts. test_render_tool_dual_channel_broadcast + test_ask_investigator_dual_channel_handoff assert both shapes.
• (added) ask_investigator handoff does NOT spawn a 120s run_investigator — it calls the lightweight answer_investigator_question (Sonnet one-shot over recent RCAs + failure_history). Mirrors answer_kb_question (M3.5 — KB Builder en mode "agent appelé" (ask_kb_builder handler) #21) contract: pure, never raises, returns fallback dict on any error. Per audit §5 (M5.4).
• (added) ASK_INVESTIGATOR_TOOL schema declared here (not M5.4 — Q&A migration vers Claude Managed Agents #33) so Managed Agents migration in M5.4 — Q&A migration vers Claude Managed Agents #33 just imports it.
• (added) Turn isolation: each user frame sets current_turn_id ContextVar then resets on exit — every nested ws_manager.broadcast auto-tags with the correct turn_id for the Activity Feed / Agent Inspector.

---

[zestones]

Audit follow-up — implementation context

From docs/audits/M4-M5-issue-context-pass.md §2.9 and M4-M5-sentinel-investigator-workorder-qa-audit.md §5 (M5.2) / §2.3.

Drifts from main

Drift	Issue body says	Real code on main
JWT decode function	decode_jwt(token)	verify_access_token(token) (core/security/jwt.py:54); returns dict | None
ws_auth.py file	Referenced as existing	Does not exist — create as new file
tool_result on chat	{type: "tool_result", name, ...}	Per ChatMap (ws.types.ts:71): {type, name, summary: string} — summary is mandatory
Render bundle name	"UI_TOOLS"	QA_RENDER_TOOLS (agents/ui_tools.py:380-384) — SignalChart, BarChart, EquipmentKbCard
Agent handoff payload	Implicit	Chat channel uses {type, from, to, reason} per ChatMap:73 (no _agent suffix)
Thinking on Q&A	Not clarified	ChatMap.thinking_delta exists but Q&A uses model_for("chat") (Sonnet) — Q&A never emits thinking

Real-code anchors

• Model: from agents.anthropic_client import anthropic, model_for — use model_for("chat") (Sonnet).
• MCP: from aria_mcp.client import mcp_client.
• UI bundle: from agents.ui_tools import QA_RENDER_TOOLS — three tools: SignalChart, BarChart, EquipmentKbCard.
• Auth building block: from core.security.jwt import verify_access_token — returns dict | None.

Create backend/core/security/ws_auth.py (shared with #23)

"""WebSocket cookie-auth helper shared by /events and /agent/chat."""

from __future__ import annotations

from fastapi import WebSocket
from core.security.jwt import verify_access_token


async def require_access_cookie(ws: WebSocket) -> dict | None:
    """Decode the `access_token` cookie; close with 4401 on failure.

    Returns the decoded payload on success, or None after closing the socket.
    Callers should `if payload is None: return` before `await ws.accept()`.
    """
    token = ws.cookies.get("access_token")
    payload = verify_access_token(token) if token else None
    if payload is None:
        await ws.close(code=4401)
        return None
    return payload

ChatMap shapes (from frontend/src/lib/ws.types.ts)

Everything the handler sends on the chat channel must match one of these discriminated-union members:

Direction	Shape
Client → server	{type: "user", content: str} — not yet in ChatMap; coordinate with #43
Server → client	{type: "text_delta", content}
Server → client	{type: "thinking_delta", content} (Q&A does not produce this — Sonnet, no thinking)
Server → client	{type: "tool_call", name, args}
Server → client	{type: "tool_result", name, summary} — summary is mandatory, short string
Server → client	{type: "ui_render", component, props} (component is bare name, e.g. "signal_chart")
Server → client	{type: "agent_handoff", from, to, reason} — unprefixed on this channel
Server → client	{type: "done", error?} — fires at end_turn

Warning

tool_result.summary is a short string, not the raw tool JSON. Produce it server-side:

def _summarize_tool_result(name: str, content: str, is_error: bool) -> str:
    if is_error:
        return f"{name} failed"
    try:
        data = json.loads(content)
    except ValueError:
        return content[:120]
    if isinstance(data, list):
        return f"{name} returned {len(data)} rows"
    if isinstance(data, dict):
        return f"{name} returned {list(data.keys())[:5]}"
    return str(data)[:120]

Dual-channel broadcast rule

Every ui_render and agent_handoff fires on both channels so Control Room and ChatPanel both see it:

1. ws_manager.broadcast("ui_render", {...}) — events bus, EventBusMap shape.
2. await ws.send_json({"type": "ui_render", "component": ..., "props": ...}) — chat channel, ChatMap shape.

Same for agent_handoff (with two different field conventions, see #28).

Client input contract

The issue specifies the client sends {type: "user", content: str}. That shape is not yet in ChatMap. Either:

1. Extend ChatMap with a client → server variant (cleanest), or
2. Accept arbitrary {content} server-side and do not type it on the client.

Coordinate with #43 (M7.4 ChatPanel wire).

System prompt

You are ARIA, a maintenance assistant. Answer operator questions about their
equipment using the available tools. Always cite your sources (KB, logbook,
signals, past RCAs). Respond in the language of the operator's question.
Default to French if ambiguous.

Cross-references

• Upstream: M3.1 — Anthropic client wrapper #17 (M3.1), M2.7 — MCPClient singleton (auto-discovery + call_tool) #14 (M2.7), M2.9 — UI tools generative (render_*) déclarés dans les agents #16 (M2.9 QA_RENDER_TOOLS), M4.1 — WSManager broadcast manager #23 (M4.1 WSManager + ws_auth.py), M4.6 — Agent-as-tool (handoffs dynamiques) #28 (M4.6 ask_investigator symmetric side)
• Downstream: M5.4 — Q&A migration vers Claude Managed Agents #33 (M5.4 swaps the loop for Managed Agents), M7.4 — Wire ChatPanel au vrai WS /api/v1/agent/chat #43 (M7.4 ChatPanel wire)
• Frontend consumers: M7.5 — Artifact registry + dispatcher #44 (M7.5 artifact registry), M8.3 — Artifacts bundle (WorkOrderCard + DiagnosticCard + CorrelationMatrix + PatternMatch + BarChart + AlertBanner + KbProgress) #47 (M8.3 BarChart), M8.4 — Agent Activity Feed #48 (M8.4 activity feed)