HITL: унифицированный контракт для каналов и встроенного чата

Версия: 2.0 Статус: Доработано под текущую реализацию (as-built + план). v1.0 — общее ТЗ; v2.0 привязывает его к яру human_request / ask_human, фактическому реестру каналов (docs/channels.md) и встроенному чату Workspace.

#1. Цель

Единый механизм взаимодействия агента с человеком (Human-in-the-Loop): агент запрашивает решение, данные или подтверждение, рана становится на паузу, вопрос доставляется человеку в его канал, ответ возобновляет ран. Контракт вопроса не зависит от канала: агент описывает запрос один раз, ядро выбирает способ доставки и отображения.

Принцип неизменен со времён v1.0: агент не знает каналов, каналы не знают продукта — ядро мэтчит ответ на вопрос по адресам и времени, а не по протоколу мессенджера.

#2. Что уже реализовано (as-built)

Ядро HITL работает в проде; канонический контракт v1.0 совпадает с ним практически один в один:

Вывод: этапы 1–2 v1.0 (канонический контракт + универсальный web UI) уже выполнены, но в терминах этой системы — «human_request + approval endpoint», а не отдельный HITL-сервис. Дальше — интерактивность каналов и формы.

#3. Текущие каналы связи

Фактический реестр — channelDrivers (kernel/agent/channeldriver.go); возможности каждого канала объявляет Spec().Capabilities. Каналы вне реестра (Teams, Mini Apps) — не в ближнем скоупе (§9).

Правила выбора канала неизменны (pickChannel): предпочитаемый канал получателя, иначе первый включённый и сконфигурированный, иначе web inbox. «Web» — безусловный фолбэк: недоставленный или упавший канал не теряет вопрос.

#3.1. Хостед-формы в каналах (один клик из мессенджера)

Нативные формы в чат-платформах слабы, поэтому schema-вопрос при доставке в канал минтит хостед-форму: workspace_form_link (токен 32 байта, один вопрос на токен, жизнь 7 дней или до решения) и кнопку-ссылку <UI_URL>/kernel-api/forms/<token> в сообщении. База ссылки — тот же UI URL из настроек доставки, что и у всех нотификационных ссылок; страница и ответ живут за /kernel-api на ядре (роуты форм токен-авторизованы, логин в харнес не нужен).

Матрикс: карточка с таблицей полей и кнопкой «fill the form». Остальные каналы: URL в тексте. Ответ проходит ту же валидацию и сигнал, что и из чата; аудит пишет actor form-link.

#4. Capability negotiation

Договор v1.0 (§5.4) отображается на существующий контракт драйвера без новой абстракции:

• возможности канала = ChannelSpec.Capabilities (Text, TwoWay, Threads, FilesOut, FilesIn) + MaxTextLen и Interactive из docs/channels.md §3 (при появлении нативных кнопок);
• алгоритм выбора отображения: вся форма нативно? → канал; нет → web inbox / встроенный чат; взаимодействие невозможно → вопрос всё равно создаётся и ждёт в inbox, доставка фиксируется в notification.sent (status, detail);
• ядро не ветвится по типу канала: всё, что канало-специфично — внутри драйвера (docs/channels.md §3).

#5. Встроенный чат (Workspace) — реализовано

Встроенный чат — канал первого класса: ран, запущенный из чата, показывает вопрос прямо в бабле своего сообщения, отвечать можно не покидая диалог.

Механика (все части уже существовали, новая — только карточка):

1. Доставка — отдельного канала нет: workflow и так эмитит human.requested в журнал рана, SSE-стрим /v1/workspace/runs/{id}/stream пересылает его чату. Карточка прикрепляется к сообщению рана (ChatQuestion: operation_id, arguments_hash, вопрос, контекст, опции).
2. Отображение — ChatQuestionCard: опции кнопками (выбор = ответ), свободный ответ полем (Enter = отправить), «отменить вопрос».
3. Ответ — POST /v1/agent/runs/{runID}/approval?project=… с телом {operation_id, arguments_hash, approved, actor_id, response} — тот же endpoint, что у страницы Runs: одна точка входа, одна модель авторизации и аудита. Отмена — approved=false, response="".
4. Закрытие — авторитетное состояние карточки: журналированные human.answered / human.cancelled / human.timed_out / human.rejected; оптимистичный апдейт после 202 — только для отзывчивости UI. Терминальное событие закрывает карточку только своего operation_id — события старого вопроса не гасят новый.
5. Восстановление — после перезагрузки карточка возвращается из localStorage (там живёт весь ChatMessage) и по tail-replay стрима (пауза рана = human.requested в последних 50 событиях). Восстановление на другом устройстве карточки не создаёт (транскрипт сервера не хранит run_id) — вопрос остаётся виден в inbox; это осознанное ограничение.

Активность вопроса также пишется в ленту статуса бабла (❓ …, ✓ Отвечено: …, ⏱ …) — по тем же formatStreamEvent, что и остальные события.

#6. Жизненный цикл

Состояния v1.0 мэтчатся на human_request так:

Недопустимые переходы отклоняются хранилищем (AnswerHumanRequest на закрытой строке — ErrNotFound/no-op; гонка «ответ пришёл после таймаута» — ожидаемая, строка уже закрыта, ран пошёл дальше).

Версионирование v1.0 (§7.3) уже реализовано избирательно: повторный ответ принимается только под тем же arguments_hash операции; изменение схемы вопроса агентом = новый ask_human с новой операцией.

#7. Формы (v2 контракта — реализовано)

Простой вопрос (options[] + свободный текст) остаётся базовым случаем. Поверх human_request работает форма: агент прикладывает к ask_human необязательную schema, человек заполняет её в UI, сервер проверяет ответ до возобновления рана.

Контракт:

• tool ask_human, параметр schema — JSON Schema-объект {type:"object", properties:{…}, required:[…]}; ограничен 8KB и 20 полями, нерабочая схема деградирует в обычный вопрос (не роняет tool call);
• схема хранится в human_request.schema (JSONB, миграция 0009), едет в карточку через журнальное событие human.requested;
• рендерер общий: карточка чата и тайлы Runs используют HumanForm.tsx; каналы без форм получают текстовую заглушку с перечнем полей и answer_url;
• ответ: approval endpoint принимает values (map); серверная валидация — workspace.ValidateFormValues ДО сигнала воркфлоу (422 при нарушении, строка остаётся открытой); канонический JSON значений становится Response — модель получает данные как JSON в tool result, контракт сигнала не менялся;
• текстовый ответ из мессенджера принимается как прежде — валидация схемы применяется только к структурированной отправке values.

Поддерживаемое подмножество (workspace/forms.go — серверная авторитетная проверка, validateFormValues в HumanForm.tsx — клиентское удобство):

Паттерны компилируются как Go RE2 — тот же синтаксис валиден в браузере, поэтому клиентская и серверная проверки согласованы. Неизвестные ключи игнорируются, неизвестный тип поля отклоняет значение: нераспознанное ограничение не проходит молча.

Ответ доставляется модели целиком: эндпоинт сворачивает проверенные values в канонический JSON до сигнала (422 — до возобновления рана), workflow отдаёт его в tool result без 256-байтового предпросмотра-обрезания — форма не может «дойти пустой».

Пример (агент спрашивает параметры деплоя):

{"question": "Параметры релиза billing-service?",
 "schema": {"type": "object",
   "properties": {
     "channel": {"type": "string", "enum": ["canary", "stable"], "title": "Канал"},
     "version": {"type": "string", "minLength": 5, "title": "Версия"},
     "replicas": {"type": "integer", "minimum": 1, "maximum": 50},
     "confirm":  {"type": "boolean", "title": "Подтверждаю выкат"}},
   "required": ["channel", "version", "confirm"]}}

Ответ придёт агенту как Human response: {"channel":"canary","version":"v1.2.3","replicas":2,"confirm":true}.

Каталог примитивов, условные поля, многошаговость и карточки сущностей из v1.0 §3.2–3.4 остаются референсом для расширений подмножества (не блокируют каналы: новый тип поля = поле в рендерере + ветка в валидаторе).

#8. Безопасность (без изменений по существу)

• авторизация: RoleOperator + проект на approval endpoint; identity-лесенка может запретить адресацию (human.rejected, §30);
• actor: аутентифицированный principal перекрывает присланный actor_id;
• ответы человека — недоверенные данные: текст ответа никогда не исполняется как инструкция (уходит в модель как tool result, не как prompt верхнего уровня);
• идемпотентность: одна строка human_request на операцию; повторная доставка события канала отсекается дедупом, повторный ответ — закрытой строкой;
• аудит: RecordAccessAudit на ответ/отмену, вердикт — через durable outbox;
• ссылка answer_url ведёт в UI под логином, постоянных секретов в URL нет.

#9. Вне ближнего скоупа

Перенесено из v1.0 в бэклог без сроков: Microsoft Teams, Mattermost Dialogs, Telegram Mini Apps, Matrix-кнопки, A2UI/MCP Apps как транспорт форм, групповое согласование и перенос запроса между каналами. Основание: текущие каналы и два UI (inbox, чат) покрывают сценарии; добавление канала — один драйвер (docs/channels.md §8), и формы поверх human_request (§7) не должны заставлять драйверы знать о HITL больше, чем про текст и тред.

#10. Этапы доработки

• Этап A (готово): контракт v1 (ask_human + human_request + approval endpoint + политики таймаутов) — работает во всех каналах.
• Этап B (готово): встроенный чат — карточка вопроса, ответ/отмена в диалоге, восстановление после перезагрузки.
• Этап C (готово): формы — schema в ask_human, хранение в human_request, серверная валидация значений, общий рендерер HumanForm в чате и на Runs, текстовая заглушка для каналов (§7).
• Этап D (готово): нативные кнопки там, где канал умеет: Capabilities.Interactive; telegram inline keyboard — Options кнопками (токены a:<requestID>:<idx>, cancel a:<requestID>:x ≤64Б, иначе деградация в текст), press → тот же approval-путь, что текстовый ответ (kernel/agent/notify.go askButtons, cmd/agent-kernel handleCallback); answerCallbackQuery подтверждает нажатие, editMessageText гасит кнопки.
• Этап E (готово, частично): schema-формы как HTML-виджеты в Telegram (§7.1 ниже) — расширение подмножества §3.2–3.4 по мере надобности.
• Этап F: бэклог §9 по мере появления каналов и требований.

#7.1. Schema-формы как HTML-виджеты (Telegram, Bot API 10.4)

Schema-вопрос при доставке в telegram с Capabilities.Widgets рендерится HTML-виджетом прямо в чате (sendWidget): селекты/чекбоксы/числа вместо «текст + ссылка». Агенты не меняются: виджет — чистая функция над schema из ask_human, всё канало-специфичное живёт под контрактом.

Слои («ядро не знает каналов, драйверы не знают продукта»):

• ядро (kernel/agent/widgetform.go) — нейтральная WidgetModel (поля из подмножества §7, состояние, ошибки) и op-протокол: set/submit/ reset, значения по индексу поля (ops ≤64Б), валидация — зеркало workspace.ValidateFormValues; ответ резолва — канонический JSON значений, тот же tool result, что у веб-формы;
• драйвер (kernel/agent/widgetrender.go) — модель → HTML-виджет (≤32КБ raw / ≤4096Б zlib), кнопка хостед-формы рядом;
• конвейер: доставка пинит сессию в workspace_channel_widget (миграция 0029, внутренний роут POST /v1/workspace/channel-widgets); входной луп обрабатывает widget_query: throttle 5/5с на отправителя → применить op к авторитетному состоянию → answerWidgetQuery (ack ≤15с) → editMessageWidgetData (перерисовка) → на submit — signal+закрытие+аудит через общий resolveAsk (cmd/agent-kernel/channelinbound.go).

Деградации (решает ядро, агент не узнаёт): группа/старый сервер/модель >1КБ → текст + хостед-форма; сессия истекла → «форм уже закрыт»; невалидный submit → ошибки полей уезжают в виджет, строка остаётся открытой. Ограничения prod: виджеты только в личных чатах, protect_content неизбежен, TON-типы запросов (sign_data/sent_transaction) логируются и ack-аются без кошельковой логики.

Черновики генерации (sendMessageDraft): answer-watcher стримит накопленный model.text_delta как ephemeral-превью ответа (tail ≤1200 символов, стабильный draft_id на (чат, ран)); превью живёт ~30с и заменяется финальным sendRichMessage/sendMessage. can_stop выключен — остановка рана остаётся явным продуктовым действием.

#11. Критерии приёмки

1. Агент создаёт вопрос одним контрактом (ask_human), не зная канала.
2. Вопрос, доставленный в любой канал, отвечает в любом другом (матчинг по адресам/тредам, строка одна).
3. Встроенный чат показывает вопрос в диалоге и позволяет ответить (опции, свободный текст, форма, отмена) без ухода со страницы.
4. Ответ из чата идёт через тот же approval endpoint и тот же аудит, что и из Runs и из мессенджера.
5. Перезагрузка страницы при paused-ране восстанавливает открытую карточку; ответ, данный в другом месте, закрывает карточку через журнальное событие.
6. Таймаут закрывает вопрос по политике (fallback/fail/retry/escalate/cancel) и не оставляет открытую строку.
7. Ответ без права/под неверным arguments_hash отклоняется сервером; форма с нарушенной схемой отклоняется с 422 до возобновления рана.
8. Форма рендерится одним компонентом в чате и на Runs; канал без форм получает текстовую заглушку с перечнем полей и не теряет вопрос.
9. Добавление нового канала не меняет контракт агента и не требует правок в ядре HITL (драйвер + возможности).