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.

1. Persona

Platform operator in ss-tools Svelte interface. Opens chat (drawer or /agent page). Streams responses, confirms dangerous ops via inline card, uploads files for analysis.

2. Happy Path

submit("/chat", {message}, conversation_id). 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)
• 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().
• 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" → card + retry.
• Tool failure: metadata.type="tool_error" → cross + detail.
• File parse: Error chip: "Не удалось прочитать".
• Multi-tab: REST gate rejects second tab.

5. Gradual Transition

Phase 1: Gradio + Svelte submit(). Phase 2: Old registry → @DEPRECATED. Phase 3: REST preserved (FR-022).

#endregion AgentChat.UxReference