Интеграция ACP — Документация CodeGraph

CodeGraph поддерживает Agent Client Protocol (ACP) поверх JSON-RPC для интеграции с редакторами. ACP v1 — основной профиль, совместимый с промышленным контуром. Экспериментальный профиль ACP v2 alpha включается через CODEGRAPH_ACP_EXPERIMENTAL_V2=true. Метод initialize выбирает профиль на весь срок соединения; сменить его без нового соединения нельзя.

Оба профиля используют общее ядро сессий CodeGraph, ограничения workspace, запросы разрешений и мост Model Context Protocol (MCP). Возможности image и audio сервер не объявляет.

Транспорты и маршруты

Транспорты и маршруты
Транспорт	Точка входа	Контракт
stdio	`codegraph-acp`	Локальная IDE запускает процесс агента. Запросы, ответы и уведомления передаются потоком.
HTTP	`POST /api/v1/admin/runtime/acp/rpc`	Собственный JSON-RPC request/response endpoint CodeGraph. Это не официальный ACP Streamable HTTP.
WebSocket	`WS /api/v1/admin/runtime/acp/ws`	Двунаправленные запросы, вызовы клиента агентом и потоковые уведомления.

Управление HTTP-сессиями доступно через GET /api/v1/admin/runtime/acp/sessions и DELETE /api/v1/admin/runtime/acp/sessions/{session_id}. Состояние протокола и сессии HTTP изолированы по аутентифицированному субъекту и проекту. Для WebSocket область проекта берётся из токена, машинной учётной записи или явно включённого локального контура разработки.

HTTP собирает уведомления prompt в ACP v1 и возвращает их в result._meta.codegraph.sessionUpdates. В ACP v2 метод session/prompt работает асинхронно и требует потоковый транспорт. HTTP отклоняет такой запрос кодом JSON-RPC -32004 до выполнения turn.

Граница аутентификации

Для HTTP JSON-RPC и маршрутов сессий нужны роль администратора, scope admin:all либо service account со scope scenarios:execute. Обход аутентификации на localhost возможен только при явно включённом параметре local_dev_unauthenticated_surfaces_enabled.

WebSocket принимает bearer access token или API key. Для машинной учётной записи сервер также проверяет область проекта, версию X-CodeGraph-Machine-Contract, политику интерфейса и требования mTLS. Аутентификация транспорта завершается до разбора JSON-RPC-параметров. Оба профиля ACP возвращают пустой список authMethods; поэтому устаревший v1-метод authenticate работает только внутри уже проверенной транспортной границы.

Методы ACP v1

Сначала вызовите initialize с protocolVersion: 1. До инициализации сервер отклоняет остальные методы с кодом -32002.

Стандартная поверхность v1 включает session/new, session/load, session/prompt и session/cancel. Во время prompt сервер может вызвать у клиента fs/read_text_file, fs/write_text_file, терминальные методы и session/request_permission. Клиент должен связывать ответы по идентификатору JSON-RPC и одновременно обрабатывать уведомления session/update.

В prompt ACP v1 эти клиентские вызовы включаются явно через расширение _meta.codegraph.clientContext у блока содержимого. Массив readTextFiles принимает объекты с полем path, а массив terminals — command, строковый список args и необязательные cwd, env или outputByteLimit. CodeGraph вызывает только возможности, объявленные клиентом при initialize, добавляет возвращённый редакторский текст и результат терминала в текущий prompt и всегда освобождает созданный терминал. Эти метаданные — расширение CodeGraph, а не новый стандартный метод ACP.

Расширения CodeGraph используют пространство имён _codegraph/:

_codegraph/thread/start, _codegraph/thread/resume, _codegraph/thread/fork, _codegraph/thread/list, _codegraph/thread/archive и _codegraph/thread/compact;
_codegraph/turn/start и _codegraph/turn/interrupt;
_codegraph/diagnostics/subscribe, _codegraph/diagnostics/unsubscribe и _codegraph/hover/request;
_codegraph/item/fileChange/respondApproval.

Имена без префикса, существовавшие до Story 1257, доступны через явный адаптер совместимости. Такой ответ содержит _meta.codegraph.legacyMethod; новые клиенты должны использовать методы с пространством имён. Внутренний класс ClientCapabilitiesV2 описывает расширенные возможности CodeGraph и не относится к версии протокола ACP v2.

Экспериментальный профиль ACP v2

Если задано CODEGRAPH_ACP_EXPERIMENTAL_V2=true, соединение можно инициализировать с protocolVersion: 2, info.name и info.version. Профиль поддерживает session/new, session/list, session/resume, session/close, session/delete, session/prompt, session/cancel и $/cancel_request.

На session/prompt сервер отвечает до завершения turn. Затем клиент получает уведомления session/update, в том числе переходы состояния и обновления tool call. Для этого потока нужен stdio или WebSocket. Повторный initialize с другой версией протокола отклоняется; откройте новое соединение.

Для отката задайте CODEGRAPH_ACP_EXPERIMENTAL_V2=false и перезапустите ACP-соединения. Работа ACP v1 от флага v2 не зависит.

MCP-серверы и запрос разрешения

session/new и соответствующие операции resume/load принимают ACP-дескрипторы MCP для транспортов stdio и http. Stdio-команда преобразуется в путь к исполняемому файлу и запускается как нативный argv без shell. Переменные окружения и заголовки передаются объектами name/value. Сервер проверяет имена и запрещает NUL, возврат каретки и перевод строки в значениях.

Для MCP через HTTP разрешены только публичные HTTPS-endpoint. Сервер отклоняет учётные данные в URL, query string, fragment, loopback, приватные и link-local адреса, а также обычный HTTP. Переходы по redirect подчиняются общей политике исходящих URL.

При создании сессии должны подключиться все объявленные MCP-серверы. Если хотя бы один сервер недоступен, CodeGraph закрывает уже открытые соединения и удаляет незавершённую ACP-сессию. Перед вызовом MCP-инструмента агент отправляет session/request_permission; отказ или тайм-аут отменяет вызов. Один lifecycle-owner task выполняет вход в контекст MCP SDK, операции и выход из контекста, поэтому закрытие сессии или транспорта освобождает дочерние процессы и сетевые клиенты.

Ограничения workspace и терминала

Файловые методы требуют абсолютные workspaceRoot и path. Если целевой путь после нормализации находится вне корня, сервер возвращает outside workspace root. При записи также запрещены чувствительные фрагменты пути: .git, .env, .ssh, .aws и node_modules.

Терминальные методы используют тот же абсолютный workspaceRoot; cwd должен оставаться внутри него. Команда запускается как argv с shell=False. В репозитории задан ограниченный allowlist команд сборки и чтения. Интерпретаторы и оболочки python, powershell, pwsh, cmd, bash, sh и node запрещены. Аргументы передаются нативным списком строк без NUL, перевода строки и возврата каретки.

Эти проверки не превращают ACP в универсальный удалённый shell. Сетевые маршруты должны оставаться за штатной аутентификацией и границей проекта.

Ограничение approval для файловых изменений

Сервер объявляет approval flow и отправляет устоявшееся уведомление item/fileChange/requestApproval. Клиент отвечает каноническим методом _codegraph/item/fileChange/respondApproval; ответ без префикса принимает адаптер совместимости. Если ответ не поступил до тайм-аута, запрос отклоняется.

Текущий обработчик fs/write_text_file не вызывает автоматически этот мост. После проверки пути он записывает файл внутри workspace. Если рабочий процесс требует решения человека, клиент или внешний процесс должен получить и сохранить approval до открытия write-операции.

Ограничения runtime

Значения ACPRuntimeConfig по умолчанию ограничивают сервис 100 одновременными сессиями с тайм-аутом 60 минут, 128 ожидающими запросами agent-to-client на соединение, очередью из 256 stdio-уведомлений и тайм-аутом approval 300 секунд. Та же конфигурация задаёт время ожидания и завершения терминала, интервалы опроса мостов и размер потоковых фрагментов. Развёртывание может переопределить эти значения через общую runtime-конфигурацию; клиент не должен полагаться на сохранение значений по умолчанию.

Восстановление

Проверьте префикс /api/v1/admin/runtime/acp: исторический /acp больше не используется.
Проверьте аутентификацию транспорта до разбора параметров JSON-RPC.
Отправьте один запрос initialize и сохраняйте выбранный профиль до закрытия соединения.
Для prompt в ACP v2 и запросов agent-to-client используйте stdio или WebSocket.
При ошибке файлового или терминального метода держите абсолютные workspaceRoot, path и cwd внутри одного корня.
Запрет исполняемого файла, отклонение MCP-endpoint или отсутствие разрешения означает отказ политики; обходить его через shell нельзя.

Источники истины

src/api/routers/collaboration_suite/acp.py: HTTP/WebSocket-маршруты и аутентификация.
src/acp/server/core/agent.py: диспетчер v1, выбор профиля, запросы клиента и общий вызов MCP.
src/acp/server/core/v2_profile.py: жизненный цикл сессии и асинхронные turn в профиле v2.
src/acp/server/core/session_manager.py: владение сессиями, настройка MCP, отмена и очистка.
src/acp/server/routing/handlers.py: изоляция workspace и ограниченная терминальная политика.
src/acp/integration/mcp_bridge.py: проверка MCP-дескрипторов и жизненный цикл соединений.
src/acp/transport/: поведение stdio, HTTP и WebSocket.
src/config/runtime_sections/unified_config_runtime_models.py: значения ACP runtime по умолчанию.