ADR 0016: Внешний агент по Agent Client Protocol (stdio, Cursor CLI)

Статус: Accepted · Implemented
Дата: 2026-04-05

Связанные ADR

ADR	Роль
0008	MCP — другой контур: сервер инструментов IDE; не путать с ACP

Вне ADR

Документ	Роль
note-acp-cascade-cursor-v1.md	терминология и ссылки на спецификацию
concept-pfd-mfd-cascade-v1.md	concept pfd mfd cascade v1

Снимок реализации

Элемент	Значение
—	Cursor ACP / stdio в чате и настройках; ортогонально MCP — см. текст

Контекст

Нужна связь встроенного чата CascadeIDE с внешним агентом (в первую очередь Cursor через официальный CLI и режим ACP), без встраивания UI Cursor и без собственного провода «с нуля».

Agent Client Protocol (ACP) — открытый контракт клиент↔агент (JSON-RPC по строкам, типичный транспорт stdio). PoC пройден: ответы в чате, русский текст, сессия и обратные вызовы к IDE (fs, terminal) по спецификации.

Решение

Транспорт: подпроцесс cursor-agent (или эквивалент из пакета dist-package) с аргументом acp, stdin/stdout для протокола, без консольного окна (CreateNoWindow), перенаправление потоков.
Кодировка: для Windows явно задавать UTF-8 для перенаправленных stdin/stdout/stderr процесса агента (и для дочерних процессов ACP-terminal), иначе ответы на русском декодируются в OEM и дают «кракозябры».
Клиентский SDK: библиотека AgentClientProtocol (community, upstream acp-csharp) — вендор в externals/acp-csharp/ как исходники, подключаются через ProjectReference. Исходники под externals/**/*.cs не компилируются в основной сборке IDE (Compile Remove в CascadeIDE.csproj), чтобы вложенный sandbox с top-level Main не перехватывал точку входа приложения.
Интеграция в продукт: отдельный провайдер чата (Cursor ACP), настройка пути к cursor-agent.cmd или к каталогу с dist-package; жизненный цикл сессии ACP и зеркалирование terminal/fs — в Services/CursorAcp/.
Аутентификация Cursor: не интерактивно внутри WinExe-чата при первом запуске; пользователь проходит agent login / API key в обычном терминале или через переменные окружения (как в документации Cursor). Ошибки агента до UI — по мере развития можно дублировать stderr в чат/лог (не часть этого ADR).
Границы: ACP — про диалог с внешним агентом. MCP-сервер IDE (--mcp-stdio, инструменты для агента) остаётся отдельным контуром (0008); объединение сценариев — последующими итерациями.

Последствия

Обновления upstream acp-csharp — осознанный merge/вендоринг; при смене major спецификации ACP — проверка совместимости с cursor-agent.
Зависимость от формата CLI Cursor (аргумент acp); при изменениях документации Cursor — регрессия вручную или смоук-сценарий.
Дублирование типов при ошибочном включении исходников SDK и ссылки на пакет — предотвращается Compile Remove для externals.

Отклонённые альтернативы

Только Ollama / только локальные LLM без ACP — остаётся другим провайдером; не покрывает сценарий «тот же агент, что в Cursor».
Свой бинарный протокол поверх stdio — отклонён в пользу стандарта ACP и готового клиентского SDK.
Встраивание webview Cursor — вне scope десктопного клиента ACP.

Обсуждение (не блокирует Accepted)

Подмодуль вместо вендоринга externals/acp-csharp — возможна миграция при стабилизации процесса обновлений.
Вывод stderr агента в UI чата при ошибках и «Authentication required».