#region AgentChat.UxDecisions [C:3] [TYPE ADR] [SEMANTICS ux,decisions,agent-chat,native-stack]
@defgroup Ux UX design decisions — revised for LangChain v1 native stack + Gradio native features. Replaces prior decisions.md.

## Screen: Agent Chat Panel

### Phase 1 — Screen Decomposition

| Decision | Choice | Rationale |
|----------|--------|-----------|
| **Navigation** | C — Гибрид: drawer 420px + кнопка «Развернуть» → `/agent` | Быстрые вопросы в drawer; сложные на `/agent` |
| **Layout** | B — Две колонки на `/agent`, одно колоночное в drawer | Структурированно для `/agent`, drawer компактный |
| **Data density** | B — Infinite scroll для сообщений и диалогов + поиск | Для активного оператора с 50+ диалогами |

### Phase 2 — State Exhaustion

| Decision | Choice | Rationale |
|----------|--------|-----------|
| **Чипсы примеров** | A — Только в новом пустом диалоге | Welcome-зона. Gradio `examples` рендерит их нативно |
| **Cancel** | A — Единая кнопка Stop с момента отправки. `submission.cancel()` | Нативный Gradio cancel |
| **Confirmation timeout** | A — Карточка остаётся, кнопки заблокированы, «Повторить» | Явный контроль |
| **Reconnect** | A — 5×5s, затем disconnected_permanent + ручная кнопка | Предсказуемо |
| **Ошибка истории** | A — Сразу ошибка, без кэша | Консистентность |
| **Multi-tab** | A — Client-side gate: `GET /api/agent/conversations/{id}/active` перед отправкой. Отклоняет вторую вкладку | Просто, без server-push. `concurrency_limit=1` на Gradio сериализует на сервере |

### Phase 3 — Interaction Design

| Decision | Choice | Rationale |
|----------|--------|-----------|
| **Отправка** | Gradio `submit()` с `additional_inputs=[conversation_id]` | Нативный механизм. `RunnableWithMessageHistory` загружает историю автоматически |
| **Stop** | `submission.cancel()` — optimistic UI | Нативный Gradio cancel. Частичный текст сохранён |
| **Подтверждение** | Second `submit()` с `__resume__` + `__action__`. In-memory pending interrupts в handler | Два submit() к одному стриму. HumanInTheLoopMiddleware + чекпоинт |

### Phase 4 — API Design

| Decision | Choice | Rationale |
|----------|--------|-----------|
| **Транспорт** | Gradio `submit()` через nginx proxy. Structured JSON metadata (`ChatMessage.metadata.type`) | Нулевой custom код. LangGraph события → структурированные объекты |
| **Диалоги REST** | Плоский список с сервера, группировка на клиенте | API не зависит от визуализации |

## Rejected Alternatives

- **Custom WebSocket protocol** — rejected: @gradio/client не raw WebSocket
- **REST confirmation endpoints** — rejected: HumanInTheLoopMiddleware + resume protocol проще
- **Ручная передача history** — rejected: RunnableWithMessageHistory делает автоматически
- **WebSocket-based active/follower multi-tab pattern** — rejected: сложный server-push, требует pub/sub на Gradio. Client-side gate + concurrency_limit=1 — accepted.
- **@assistant_tool registry для новых тулов** — rejected: нативные @tool функции LangChain

#endregion AgentChat.UxDecisions
