ss-tools/specs/033-gradio-agent-chat/ux_reference.md

#region AgentChat.UxReference [C:3] [TYPE ADR] [SEMANTICS ux,reference,agent-chat,final] @BRIEF Final UX reference — Gradio submit(), LangChain v1 HITL, structured metadata, Archive UX, operator recovery.

1. Persona

Platform operator in superset-tools Svelte interface. Opens chat (drawer or /agent page). Streams responses, confirms dangerous ops via inline card, uploads files for analysis, and diagnoses LLM/Gradio stalls without leaving the page.

2. Happy Path

submit("/chat", {message}, conversation_id, user_id, user_jwt, env_id). The UI synchronizes selected environment before each send. Tokens stream in real time. Tool cards appear from structured metadata. Confirmation card for dangerous ops — Confirm via second submit(). Archive conversations via delete (soft-delete).

3. Key Elements

• Input: Textarea + paperclip (PDF/XLSX/JSON/CSV/PNG/JPEG)
• Context indicator: Header shows selected environment and process strip (Контекст, Понимание задачи, Инструменты, Подтверждение, Результат).
• Streaming: Text character-by-character. Tool cards from metadata.type.
• Stop: submission.cancel() — native.
• Confirmation: Warning card from metadata.type="confirm_required". Confirm → second submit().
• Diagnostics: /agent header menu exposes debug panel, copy JSON diagnostics, and LLM status check. Debug panel shows conv_id, pending thread_id, connection/streaming state, env/user, message count, last message id, active tool calls, and current error.
• Visible text hygiene: User bubbles and conversation titles do not show hidden runtime/prefetch/upload context. System-only tool titles normalize to Системное действие.
• Conversation Switcher: Search, date-grouped, infinite scroll.
• Connection: Green/red dot.

4. Error Scenarios

• Gradio down: Dot red, retry 5×5s.
• LLM error: Stream metadata.type="error" → recovery card.
• Silent LLM/Gradio hang: No first token/tool/confirmation/checkpoint for 60s → recovery card with retry/check LLM/copy debug/new dialog.
• Tool failure: metadata.type="tool_error" → cross + detail.
• File parse: Error chip: "Не удалось прочитать".
• Multi-tab: REST gate rejects second tab.
• Relative maintenance request: Hidden runtime context gives the LLM current ISO datetime and duration rules. The hidden block must not render in chat/history.

5. Gradual Transition

Phase 1: Gradio + Svelte submit(). Phase 2: Agent tools moved to native LangChain @tool; old registry → @DEPRECATED. Phase 3: REST preserved (FR-022).

#endregion AgentChat.UxReference