ACP и Zed

SOBA умеет работать как Agent Client Protocol server для редакторов, которые запускают agent по stdio. Практический сценарий сейчас — Zed: редактор стартует soba acp, создаёт ACP session и отправляет prompts через Agent Panel, а SOBA возвращает assistant text, tool lifecycle, permissions, usage и evidence metadata через ACP updates.

ACP в SOBA — это adapter поверх общего runtime. Он не содержит собственной политики проверки, permissions, MCP, memory или completion. Те же runtime-команды и проверки, которые доступны в CLI/TUI, используются и в ACP-пути.

1. Запуск

Минимальная команда server:

soba acp

В ACP mode:

• stdout содержит только newline-delimited JSON-RPC сообщения;
• diagnostic logs пишутся в stderr с префиксом [soba acp];
• конфигурация provider/model читается обычным SOBA config path;
• если нет обязательной provider-конфигурации, процесс завершится с понятной ошибкой до старта JSON-RPC loop.

В Zed настройте agent server так, чтобы command запускал soba, а args содержали acp. Если вы запускаете SOBA из исходников, используйте эквивалентную команду вашего dev-окружения, например bun run src/cli.ts acp.

2. Protocol Version And Capabilities

SOBA advertises ACP protocol version 1.

На initialize SOBA возвращает:

• agentInfo.name: soba-agent;
• agentInfo.version: версия из package.json;
• agentCapabilities.loadSession: true;
• promptCapabilities.embeddedContext: true;
• promptCapabilities.image: true;
• promptCapabilities.audio: false;
• sessionCapabilities: close, delete, list, resume.

SOBA также читает clientCapabilities и включает дополнительные client-backed paths, если редактор их рекламирует:

Если capability не объявлена, SOBA использует собственный runtime path или отказывает действие безопасным способом.

Plan mode и интерактивные уточнения

ACP client может переключить session в plan, planning, goal или agent через session/set_mode. В plan и goal режимах SOBA не меняет repository, memory, config или Git state и не даёт модели bash: доступны только native inspection tools и подготовка плана.

Если client рекламирует нестабильную capability elicitation.form, SOBA дополнительно даёт модели ask_user. Во время планирования adapter отправляет elicitation/create с одной form: от двух до пяти button-like enum choices и, если нужно, полем Other. Выбор возвращается как tool result и позволяет закончить план в том же turn.

Без elicitation.form ask_user не попадает в tool list. Модель завершает ответ обычным текстом с открытыми вопросами; SOBA не пытается имитировать форму или блокировать turn.

3. Server Methods

SOBA реализует текущий ACP v1 server surface:

Unknown methods возвращают JSON-RPC Method not found.

4. Prompt Content

session/prompt принимает ACP content blocks и переводит их в protocol-neutral runtime blocks:

Embedded resources считаются untrusted context. Они помогают модели понять текущий файл/выделение, но не заменяют проверку через tools, diff или commands.

ACP command внутри prompt тоже поддержан. Например команда /mcp reload или /sessions list идёт через общий command executor до обращения к модели.

5. Available Commands

После создания, загрузки или resume session SOBA отправляет available_commands_update. Команды берутся из общего runtime metadata, фильтруются по ACP surface и рекламируются с usage hints.

Сейчас через ACP доступны:

/compact
/rewind
/session
/sessions
/capsule
/auto-compact
/budget
/config
/lang
/permissions
/skill
/project-trust
/mcp
/help

TUI-only команды вроде /clear, /notifications, /model, /sidebar и /keys не рекламируются через ACP, потому что они управляют локальным terminal UI, а не editor protocol session.

6. Tool Updates

SOBA мапит runtime tool events в ACP session/update:

Для filesystem/edit/read/search/bash tools SOBA добавляет structured metadata:

• toolCallId;
• title;
• kind;
• status;
• rawInput;
• locations, если известен path/line;
• _meta.tool_name;
• _meta.soba.toolName;
• _meta.soba.kind.

Для edits SOBA отправляет ACP diff content:

type: "diff"
path: "/repo/src/app.ts"
oldText: "..."
newText: "..."

Для bash/terminal calls metadata включает command, exit code, timeout/truncation flags и output preview.

7. Permissions

Dangerous operations в ACP идут через тот же trust/permissions layer, что и CLI/TUI. Если editor поддерживает session/request_permission, SOBA отправляет permission request с tool call summary и вариантами:

Если client request недоступен или падает, SOBA выбирает безопасный default: deny.

8. Evidence Metadata

Финальный handoff строится через общий Evidence Bundle. ACP adapter не решает, достаточно ли проверок; он только передаёт результат пользователю и редактору.

Когда assistant message содержит evidence handoff, ACP update получает:

_meta.soba.evidence.source = "assistant_handoff"
_meta.soba.evidence.status
_meta.soba.evidence.changedFiles
_meta.soba.evidence.diff
_meta.soba.evidence.checks
_meta.soba.evidence.risks
_meta.soba.evidence.reviewActions

Tool lifecycle updates тоже содержат _meta.soba.evidence с phase start, result или end, status, path/command и preview output. Поэтому Zed может показать не только итоговый текст, но и то, какие команды запускались, какие файлы менялись и где остались риски.

9. Sessions

ACP session id может отличаться от внутреннего SOBA session id. Adapter хранит alias mapping, поэтому stale editor ids могут быть привязаны к live runtime session после load или resume.

session/load replay-ит persisted entries обратно в editor через session/update, затем отправляет актуальные config options и available commands.

session/list возвращает:

• sessionId;
• cwd;
• title;
• updatedAt.

10. Client-Backed Delegation

Если ACP client поддерживает filesystem или terminal methods, SOBA может использовать editor-backed operations:

Эта delegation не меняет trust model: dangerous commands всё равно проходят через SOBA approval path.

11. Ограничения

• ACP v2 сейчас не заявлен как полный target; текущая реализация рекламирует protocol version 1.
• Audio prompt blocks не поддержаны.
• OAuth/auth provider integrations для ACP не являются отдельным пользовательским workflow: authenticate и logout сейчас завершаются успешно как local/server-managed no-op.
• MCP tools внутри SOBA работают через обычную .soba/mcp.json конфигурацию. После правки config используйте /mcp reload через ACP command path.
• Zed manual smoke зависит от установленного редактора и его ACP surface; автоматические тесты покрывают stdio server, dispatcher, lifecycle, permissions, tool metadata, diff content и evidence metadata.

12. Проверки Для Разработки

Основной regression set:

bun test tests/adapters/acp
bun test tests/application/runtime-factory.test.ts
bun test tests/architecture/post-acp-architecture-gate.test.ts

Для полного gate:

bun test
bun run lint
bunx tsc --noEmit
bun run build

Архитектурное правило: ACP code живёт в src/adapters/acp и src/apps/acp; core/runtime policy не должен импортировать protocol adapter.