Перейти к содержанию

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) по спецификации.

Решение

  1. Транспорт: подпроцесс cursor-agent (или эквивалент из пакета dist-package) с аргументом acp, stdin/stdout для протокола, без консольного окна (CreateNoWindow), перенаправление потоков.

  2. Кодировка: для Windows явно задавать UTF-8 для перенаправленных stdin/stdout/stderr процесса агента (и для дочерних процессов ACP-terminal), иначе ответы на русском декодируются в OEM и дают «кракозябры».

  3. Клиентский SDK: библиотека AgentClientProtocol (community, upstream acp-csharp) — вендор в externals/acp-csharp/ как исходники, подключаются через ProjectReference. Исходники под externals/**/*.cs не компилируются в основной сборке IDE (Compile Remove в CascadeIDE.csproj), чтобы вложенный sandbox с top-level Main не перехватывал точку входа приложения.

  4. Интеграция в продукт: отдельный провайдер чата (Cursor ACP), настройка пути к cursor-agent.cmd или к каталогу с dist-package; жизненный цикл сессии ACP и зеркалирование terminal/fs — в Services/CursorAcp/.

  5. Аутентификация Cursor: не интерактивно внутри WinExe-чата при первом запуске; пользователь проходит agent login / API key в обычном терминале или через переменные окружения (как в документации Cursor). Ошибки агента до UI — по мере развития можно дублировать stderr в чат/лог (не часть этого ADR).

  6. Границы: 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».