diff --git a/docs/research/agent-spawn-packages.md b/docs/research/agent-spawn-packages.md new file mode 100644 index 00000000..d1241994 --- /dev/null +++ b/docs/research/agent-spawn-packages.md @@ -0,0 +1,465 @@ +# Agent Spawn Packages — Deep Dive Research + +**Дата:** 2026-03-25 +**Цель:** Найти лучший способ программно запускать CLI-агентов (Claude Code, Codex, Gemini CLI) из Electron-приложения. + +--- + +## TL;DR — Итоговая Рекомендация + +У всех трёх главных CLI-агентов **теперь есть ОФИЦИАЛЬНЫЕ SDK** для программного запуска: + +| Агент | SDK Пакет | Лицензия | Зрелость | +|-------|-----------|----------|----------| +| Claude Code | `@anthropic-ai/claude-agent-sdk` | **Proprietary** (Commercial ToS) | Stable (v0.2.83) | +| Codex | `@openai/codex-sdk` | **Apache-2.0** | Stable (v0.116.0) | +| Gemini CLI | `@google/gemini-cli-sdk` + `@google/gemini-cli-core` | **Apache-2.0** | Early (v0.30.0+) | + +**Вывод:** Вместо форка `@swarmify/agents-mcp` или написания своих spawn-обёрток, лучше использовать **официальные SDK** от каждого провайдера. Они более надёжны, поддерживаются, и дают нативный доступ без хрупкого парсинга stdout. + +--- + +## 1. @swarmify/agents-mcp + +**npm:** https://www.npmjs.com/package/@swarmify/agents-mcp +**Сайт:** https://swarmify.co/ +**GitHub:** НЕ НАЙДЕН (closed-source или приватный репозиторий) + +### Что это +MCP-сервер, который позволяет любому MCP-клиенту (Claude, Codex, Gemini, Cursor) спавнить параллельных агентов. Часть экосистемы Swarmify. + +### Предоставляет +- **4 MCP-тула:** Spawn, Status, Stop, Tasks +- **3 режима:** plan (read-only), edit (can write), ralph (autonomous) +- Фоновые процессы — агенты переживают перезапуск IDE +- Авто-детект Claude, Codex, Gemini CLI при установке + +### Как спавнит агентов +Агенты коммуницируют через файловую систему — каждый агент пишет в свой лог-файл (stdout.log). Тул Status читает эти логи, нормализует события между разными форматами агентов, и возвращает сводку. + +### IAgent / BaseAgent — НЕ НАЙДЕНЫ +Несмотря на множество поисков, интерфейсы `IAgent` и `BaseAgent` **не обнаружены** в публичной документации пакета. Возможно, они существуют внутри скомпилированного npm-пакета (можно проверить через `node_modules`), но исходный код закрыт. + +### Оценка для нас +- **Надёжность: 3/10** — Closed-source, нет GitHub, невозможно форкнуть +- **Уверенность: 2/10** — Без исходного кода невозможно оценить качество +- **Вердикт:** НЕ подходит для нашего проекта + +--- + +## 2. @anthropic-ai/claude-agent-sdk (OFFICIAL) + +**npm:** https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk +**GitHub:** https://github.com/anthropics/claude-agent-sdk-typescript +**Docs:** https://platform.claude.com/docs/en/agent-sdk/typescript +**Версия:** 0.2.83 (25 марта 2026) +**Лицензия:** Proprietary (Anthropic Commercial Terms of Service) +**Звёзды:** ~1000 | **Форки:** ~117 | **Релизы:** 67 +**691 проект** в npm registry используют этот пакет + +### Что это +Официальный SDK от Anthropic для программного запуска Claude Code. Переименован из "Claude Code SDK" в "Claude Agent SDK". Даёт те же инструменты, agent loop и context management, что и Claude Code. + +### Ключевой API + +```typescript +import { query } from "@anthropic-ai/claude-agent-sdk"; + +// Основная функция — async generator +const q = query({ + prompt: "Fix the bug in auth.py", + options: { + model: "opus", + cwd: "/path/to/project", + allowedTools: ["Read", "Edit", "Bash"], + permissionMode: "bypassPermissions", + allowDangerouslySkipPermissions: true, + maxTurns: 50, + maxBudgetUsd: 5.0, + env: { ANTHROPIC_API_KEY: "..." }, + mcpServers: { /* MCP config */ }, + agents: { + // Программно определяемые субагенты + reviewer: { + description: "Code reviewer agent", + prompt: "Review code for bugs", + model: "sonnet", + tools: ["Read", "Grep", "Glob"], + } + }, + settingSources: ["project"], // Загрузка CLAUDE.md + thinking: { type: "adaptive" }, + } +}); + +// Стриминг событий +for await (const message of q) { + // SDKMessage types: assistant, user, result, system, etc. + console.log(message); +} + +// Query object methods: +// q.interrupt(), q.close(), q.setModel(), q.mcpServerStatus() +// q.initializationResult(), q.supportedModels(), q.supportedAgents() +``` + +### Как спавнит Claude Code +SDK **запускает Claude Code CLI как subprocess** — НЕ чисто API-библиотека. Каждый вызов `query()` спавнит новый процесс (~12 сек overhead). + +Ключевые опции: +- `spawnClaudeCodeProcess` — кастомная функция для запуска процесса (VMs, Docker, remote) +- `pathToClaudeCodeExecutable` — путь к бинарнику Claude Code +- `env` — переменные окружения для subprocess (полезно для Electron) +- `executable` — runtime: `'node'`, `'bun'`, `'deno'` + +### Session Management +```typescript +import { listSessions, getSessionMessages } from "@anthropic-ai/claude-agent-sdk"; + +const sessions = await listSessions({ dir: "/path/to/project", limit: 10 }); +const messages = await getSessionMessages(sessionId, { limit: 20 }); + +// Resume session +const q = query({ + prompt: "Continue working", + options: { resume: sessionId } +}); +``` + +### V2 Preview API (упрощённый интерфейс) +Новый API с `send()` и `stream()` паттернами для multi-turn conversations. + +### Субагенты +Определяются программно через `agents` option в `AgentDefinition`: +```typescript +type AgentDefinition = { + description: string; + prompt: string; + tools?: string[]; + disallowedTools?: string[]; + model?: "sonnet" | "opus" | "haiku" | "inherit"; + mcpServers?: AgentMcpServerSpec[]; + skills?: string[]; + maxTurns?: number; +}; +``` + +### MCP-серверы +Поддерживает in-process MCP серверы: +```typescript +import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk"; +import { z } from "zod"; + +const server = createSdkMcpServer({ + name: "my-server", + tools: [ + tool("search", "Search the web", { query: z.string() }, async ({ query }) => { + return { content: [{ type: "text", text: `Results for: ${query}` }] }; + }) + ] +}); +``` + +### Ограничения лицензии +- **Proprietary** — НЕ open-source +- Запрещено использовать OAuth токены Claude Free/Pro/Max — нужен **API key** +- Продукт должен иметь **собственный брендинг** (не Claude Code) +- Anthropic собирает telemetry (usage, feedback, conversations) + +### Оценка для нас +- **Надёжность: 9/10** — Официальный SDK от Anthropic, активно развивается +- **Уверенность: 9/10** — Отлично документирован, 691+ пользователь +- **Риск:** Proprietary лицензия, ~12 сек overhead на query(), зависимость от CLI binary + +--- + +## 3. @openai/codex-sdk (OFFICIAL) + +**npm:** https://www.npmjs.com/package/@openai/codex-sdk +**GitHub:** https://github.com/openai/codex/tree/main/sdk/typescript +**Docs:** https://developers.openai.com/codex/sdk +**Версия:** 0.116.0 +**Лицензия:** Apache-2.0 +**107 проектов** в npm registry используют этот пакет + +### Что это +Официальный TypeScript SDK от OpenAI для программного управления Codex CLI. Оборачивает CLI, обменивается JSONL-событиями через stdin/stdout. + +### Ключевой API + +```typescript +import { Codex } from "@openai/codex-sdk"; + +// Инициализация +const codex = new Codex({ + env: { PATH: "/usr/local/bin" }, // Полезно для Electron + config: { + show_raw_agent_reasoning: true, + sandbox_workspace_write: { network_access: true } + }, + baseUrl: "https://api.example.com" // Optional +}); + +// Thread management +const thread = codex.startThread({ + workingDirectory: "/path/to/project", + skipGitRepoCheck: true // Для non-git environments +}); + +// Buffered response +const turn = await thread.run("Fix the test failure"); +console.log(turn.finalResponse); +console.log(turn.items); + +// Streaming response +const { events } = await thread.runStreamed("Diagnose failures"); +for await (const event of events) { + switch (event.type) { + case "item.completed": console.log("Item:", event.item); break; + case "turn.completed": console.log("Usage:", event.usage); break; + } +} + +// Multi-turn conversations +const turn1 = await thread.run("Diagnose issue"); +const turn2 = await thread.run("Implement the fix"); + +// Resume persisted thread +const thread2 = codex.resumeThread(process.env.CODEX_THREAD_ID!); +``` + +### Как спавнит Codex CLI +SDK спавнит **Codex CLI** (Rust-based `@openai/codex`) как subprocess и обменивается JSONL-событиями через stdin/stdout. + +- Работает **ТОЛЬКО** с Native (Rust) версией Codex +- SDK инжектит `CODEX_API_KEY` поверх переданных env variables +- `env` параметр — полный контроль над переменными (полезно для Electron) +- `config` — JSON → dotted paths → TOML literals → `--config key=value` flags + +### Session Persistence +- Threads сохраняются в `~/.codex/sessions` +- `resumeThread(id)` — восстановление потерянного Thread + +### Structured Output +```typescript +const schema = { + type: "object", + properties: { + summary: { type: "string" }, + status: { type: "string", enum: ["ok", "action_required"] } + }, + required: ["summary", "status"], + additionalProperties: false +} as const; + +const turn = await thread.run("Summarize status", { outputSchema: schema }); +``` + +### Multi-Agent Collaboration +Поддержка spawn_agent, send_input, wait для координации между threads. + +### Оценка для нас +- **Надёжность: 9/10** — Официальный SDK от OpenAI, Apache-2.0 +- **Уверенность: 8/10** — Хорошо документирован, активно развивается +- **Риск:** Только Rust-based Codex, зависимость от Git repo (опционально отключается) + +--- + +## 4. @google/gemini-cli-sdk + @google/gemini-cli-core (OFFICIAL) + +**npm (CLI):** https://www.npmjs.com/package/@google/gemini-cli +**npm (Core):** https://www.npmjs.com/package/@google/gemini-cli-core +**GitHub:** https://github.com/google-gemini/gemini-cli +**Docs:** https://deepwiki.com/google-gemini/gemini-cli/5.9-sdk-and-programmatic-api +**Версия:** SDK появился в v0.30.0 (2026-02-25) +**Лицензия:** Apache-2.0 +**Звёзды:** ~99K + +### Что это +Официальный SDK от Google для программного запуска Gemini CLI. Монорепо-архитектура. + +### Архитектура пакетов +| Пакет | Роль | +|-------|------| +| `@google/gemini-cli-sdk` | Consumer-facing API | +| `@google/gemini-cli-core` | Core orchestration, tools, API | +| `@google/gemini-cli` | Terminal reference implementation | + +### Ключевой API + +```typescript +import { LocalAgentExecutor, LocalAgentDefinition } from '@google/gemini-cli-core'; + +const agentDef: LocalAgentDefinition = { + modelId: 'gemini-2.0-flash', + systemPrompt: 'You are a helpful assistant', + tools: ['read_file', 'write_file', 'run_shell_command'], + maxTurns: 30, + timeoutMs: 600000 // 10 min +}; + +const executor = new LocalAgentExecutor(config, agentDef); + +// Activity monitoring +executor.onActivity((event) => { + console.log('Agent activity:', event); +}); + +const result = await executor.run({ + task: 'Analyze the codebase and suggest improvements' +}); + +console.log('Termination mode:', result.terminateMode); // GOAL | MAX_TURNS | TIMEOUT +console.log('Result:', result.output); +``` + +### Как спавнит Gemini +В отличие от Claude и Codex, SDK Gemini — **НЕ CLI wrapper**, а **нативная библиотека**. Использует core-логику напрямую: +- `GeminiCliAgent` / `LocalAgentExecutor` — primary entity +- Каждый агент получает свой `ToolRegistry` (изоляция) +- `MessageBus` для async events (tool confirmations) +- `Config` class для model selection и auth + +### Tool Management +- Built-in tools (file system, shell, web) +- MCP server tools +- Extension-provided tools +- Tool confirmation через `TOOL_CONFIRMATION_REQUEST` event + +### Agent Termination +```typescript +enum AgentTerminateMode { + GOAL, // Успешно вызвал complete_task + MAX_TURNS, // Достиг лимита (default 30) + TIMEOUT // Превысил время (default 10 min) +} +``` + +### Headless Mode (альтернатива) +```bash +gemini --output-format json -p "Summarize project" +gemini --output-format stream-json -p "Fix bug" +``` + +### Зрелость +- SDK появился в v0.30.0 (2026-02-25) — **очень свежий** +- Feature request #15539 (Dec 2025) формально запрашивал SDK +- API может меняться + +### Оценка для нас +- **Надёжность: 6/10** — Apache-2.0, открытый код, но SDK совсем новый +- **Уверенность: 6/10** — API может меняться, документация неполная +- **Преимущество:** Нативная библиотека (не CLI wrapper), лучшая производительность + +--- + +## 5. Альтернативные Multi-Agent Frameworks + +### jayminwest/overstory +**GitHub:** https://github.com/jayminwest/overstory +**Лицензия:** MIT + +Pluggable `AgentRuntime` интерфейс с **11 адаптерами** (Claude Code, Codex, Gemini CLI, Aider, Goose, Amp и др). Агенты работают в изолированных git worktrees через tmux. + +| Runtime | CLI | Guard Mechanism | +|---------|-----|-----------------| +| Claude Code | `claude` | `settings.local.json` hooks | +| Codex | `codex` | OS-level sandbox | +| Gemini | `gemini` | `--sandbox` flag | +| Aider | `aider` | None (`--yes-always`) | +| Goose | `goose` | Profile-based permissions | +| + 6 others | ... | ... | + +**Интересно, но:** Ориентирован на CLI/tmux workflow, не на Electron SDK. + +### desplega-ai/agent-swarm +**GitHub:** https://github.com/desplega-ai/agent-swarm +**Docs:** https://docs.agent-swarm.dev/ + +Lead-worker паттерн с Docker-изоляцией. Поддерживает Claude Code, с планами на Codex/Gemini. SQLite + bun. + +--- + +## 6. Сравнительная Таблица SDK + +| | Claude Agent SDK | Codex SDK | Gemini CLI SDK | +|---|---|---|---| +| **Пакет** | `@anthropic-ai/claude-agent-sdk` | `@openai/codex-sdk` | `@google/gemini-cli-sdk` | +| **Версия** | 0.2.83 | 0.116.0 | ~0.30.0+ | +| **Лицензия** | Proprietary | Apache-2.0 | Apache-2.0 | +| **Архитектура** | CLI subprocess | CLI subprocess (Rust) | Нативная библиотека | +| **Стриминг** | AsyncGenerator | AsyncGenerator (events) | onActivity callback | +| **Session Resume** | Да (sessionId) | Да (resumeThread) | Да (SessionContext) | +| **Субагенты** | Да (agents option) | Да (spawn_agent) | Да (LocalAgentDefinition) | +| **MCP серверы** | Да (in-process + external) | Нет (native tools only) | Да (ToolRegistry) | +| **Custom Env** | Да (env option) | Да (env option) | Да (Config) | +| **Custom Spawn** | Да (spawnClaudeCodeProcess) | Нет | Нет (нативная) | +| **Structured Output** | Да (JSON Schema) | Да (JSON Schema + Zod) | Да (zod OutputConfig) | +| **Node.js** | 18+ | 18+ | 18+ | +| **Overhead** | ~12s per query() | Не измерен | Минимальный (нативная) | +| **npm Users** | 691 | 107 | N/A (новый) | + +--- + +## 7. Рекомендация для Claude Agent Teams UI + +### Основной подход (Recommended) +**Использовать официальные SDK каждого провайдера** вместо единого абстрактного слоя. + +``` +src/main/services/agents/ +├── types.ts # Общие типы (AgentProcess, AgentEvent, AgentConfig) +├── claude-adapter.ts # Обёртка над @anthropic-ai/claude-agent-sdk +├── codex-adapter.ts # Обёртка над @openai/codex-sdk +├── gemini-adapter.ts # Обёртка над @google/gemini-cli-sdk +└── agent-registry.ts # Реестр доступных агентов +``` + +Тонкий адаптерный слой (~100-150 LOC на адаптер) над каждым SDK, нормализующий: +- Стриминг событий → единый `AgentEvent` формат +- Session management → единый `AgentSession` интерфейс +- Process lifecycle → start/stop/status + +### Почему НЕ @swarmify/agents-mcp +1. Closed-source — невозможно аудировать или форкнуть +2. MCP-only интерфейс — мы уже имеем прямой доступ к процессам +3. Filesystem-based communication — избыточный overhead для Electron + +### Почему НЕ единый CLI spawn +1. Все 3 провайдера выпустили свои SDK +2. SDK дают типизированные события, session management, structured output +3. Raw CLI spawn хрупок (парсинг stdout/ANSI codes) + +### Почему НЕ overstory AgentRuntime +1. Ориентирован на tmux/worktree workflow +2. MIT лицензия хорошая, но архитектура не подходит для Electron +3. 11 адаптеров — избыточно, нам нужны 3 + +### Порядок интеграции +1. **Claude Code** (`@anthropic-ai/claude-agent-sdk`) — у нас уже есть, нужно мигрировать на SDK +2. **Codex** (`@openai/codex-sdk`) — Apache-2.0, простой API, thread-based +3. **Gemini** (`@google/gemini-cli-sdk`) — подождать стабилизации API (SDK очень свежий) + +### Риски +- **Claude SDK Proprietary лицензия** — нужно проверить совместимость с нашим MIT +- **~12s overhead** Claude SDK per query — может потребоваться process pooling +- **Gemini SDK API unstable** — может сломаться в любом релизе + +--- + +## Источники + +- [@swarmify/agents-mcp (npm)](https://www.npmjs.com/package/@swarmify/agents-mcp) +- [Swarmify](https://swarmify.co/) +- [@anthropic-ai/claude-agent-sdk (npm)](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) +- [Claude Agent SDK TypeScript (GitHub)](https://github.com/anthropics/claude-agent-sdk-typescript) +- [Claude Agent SDK Reference](https://platform.claude.com/docs/en/agent-sdk/typescript) +- [Run Claude Code programmatically](https://code.claude.com/docs/en/headless) +- [@openai/codex-sdk (npm)](https://www.npmjs.com/package/@openai/codex-sdk) +- [Codex SDK TypeScript (GitHub)](https://github.com/openai/codex/tree/main/sdk/typescript) +- [Codex SDK Docs](https://developers.openai.com/codex/sdk) +- [@google/gemini-cli (GitHub)](https://github.com/google-gemini/gemini-cli) +- [Gemini CLI SDK (DeepWiki)](https://deepwiki.com/google-gemini/gemini-cli/5.9-sdk-and-programmatic-api) +- [Gemini CLI SDK Feature Request #15539](https://github.com/google-gemini/gemini-cli/issues/15539) +- [overstory (GitHub)](https://github.com/jayminwest/overstory) +- [agent-swarm (GitHub)](https://github.com/desplega-ai/agent-swarm) diff --git a/docs/research/ai-maestro-deep-dive.md b/docs/research/ai-maestro-deep-dive.md new file mode 100644 index 00000000..5267ec2c --- /dev/null +++ b/docs/research/ai-maestro-deep-dive.md @@ -0,0 +1,334 @@ +# AI Maestro — Deep Dive Research + +**Дата исследования:** 2026-03-25 +**Репозиторий:** [23blocks-OS/ai-maestro](https://github.com/23blocks-OS/ai-maestro) +**Сайт:** [ai-maestro.23blocks.com](https://ai-maestro.23blocks.com/) +**Автор:** Juan Pelaez / 23blocks +**Лицензия:** MIT + +--- + +## Общая информация + +AI Maestro — open-source оркестратор AI-агентов с системой навыков (Skills System), дашбордом для управления агентами, собственным протоколом обмена сообщениями (AMP) и поддержкой мультимашинных mesh-сетей. Позиционирует себя как "The Future of Work: Humans + AI Agents". + +### Метрики репозитория (на 25 марта 2026) + +| Метрика | Значение | +|---------|----------| +| Stars | **557** | +| Forks | 77 | +| Open issues | 8 | +| Коммитов | 890+ | +| Контрибьюторов | ~5 (249 от jpelaez-23blocks, далее 9, 7, 4, 2) | +| Создан | 10 октября 2025 | +| Последний коммит | 25 марта 2026 (сегодня!) | +| Последний релиз | v0.26.4 (25 марта 2026) | +| Языки | TypeScript 89%, Shell 6.7%, JS 3.4%, CSS 0.5% | +| Размер репо | ~312 MB | + +**Вывод:** Проект активно развивается, коммиты ежедневные. Но по факту это проект одного человека (Juan Pelaez — 249 из ~270 коммитов от людей). 4 коммита от аккаунта `claude` — что ироничным образом подтверждает AI-происхождение кода. + +--- + +## Origin Story + +Цитата из описания проекта: +> "I had 35 terminals and couldn't tell which was which." + +Автор запускал 35+ AI-агентов одновременно и стал "human mailman" между ними — копировал контекст из одного терминала в другой. Сейчас утверждает, что запускает **80+ агентов** на нескольких компьютерах. + +--- + +## Поддерживаемые агенты + +### Заявленная совместимость: +- **Claude Code** (основной) +- **Aider** +- **Cursor** +- **GitHub Copilot CLI** +- **OpenCode** (через Skills) +- **Любой терминальный AI-агент** + +### Как это работает: +AI Maestro не является "мультипровайдерным" в том смысле, что он сам вызывает API разных LLM. Он работает на уровне **терминалов** — оборачивает tmux-сессии и предоставляет dashboard для управления ими. Любой инструмент, который работает в терминале, может быть "агентом" в AI Maestro. + +**Важное уточнение:** AI Maestro НЕ абстрагирует LLM-провайдеров (как например LiteLLM). Он оркестрирует **процессы в терминале**. Claude Code внутри себя использует Anthropic API, Aider может использовать OpenAI/Anthropic/etc — но AI Maestro этого не контролирует. + +--- + +## Архитектура + +### Tech Stack + +| Компонент | Технология | Роль | +|-----------|-----------|------| +| Frontend | **Next.js** | Web-дашборд | +| Terminal | **xterm.js** | Эмуляция терминала в браузере | +| Database | **CozoDB** | Граф-реляционная БД для памяти и Code Graph | +| Code Analysis | **ts-morph** | Парсинг AST для Code Graph | +| Process Mgmt | **tmux** | Мультиплексор терминалов | +| Networking | **Peer Mesh** | P2P сеть между машинами | + +### CozoDB — выбор базы данных + +CozoDB (3 926 stars) — необычный выбор. Это транзакционная реляционно-графовая-векторная БД, использующая **Datalog** для запросов. Ключевые фичи: +- Реляционная модель + графовые алгоритмы +- Векторный поиск через HNSW-индексы +- Встраиваемая (embedded) +- Time-travel запросы + +Это позволяет хранить и код-граф (структура кодобазы), и память агентов (conversation history), и выполнять векторный поиск — в одной БД. + +### Три уровня "интеллекта" + +1. **Memory** — Персистентная память через CozoDB. Агенты помнят прошлые решения и разговоры. +2. **Code Graph** — Визуализация структуры кодобазы. ts-morph парсит AST, извлекает классы/функции/импорты, строит граф зависимостей. Delta-индексация (переиндексируются только изменённые файлы). +3. **Documentation** — Автогенерируемая документация из кода, доступная агентам для поиска. + +### Мультимашинная mesh-сеть + +- Peer-to-peer топология: каждая машина — равноправный узел +- Нет центрального сервера +- Новая машина автоматически присоединяется к mesh +- Все агенты со всех машин видны в одном дашборде +- Поддержка remote access через Tailscale VPN + +### Структура репозитория + +``` +/app — Application logic +/components — UI-компоненты +/services — Backend-сервисы +/plugin — Система плагинов для Claude Code +/agent-container — Контейнеризированные агенты +/infrastructure/terraform/aws-agent — AWS deployment +/docs — Документация +``` + +--- + +## Agent Messaging Protocol (AMP) + +AMP — это **собственный протокол** 23blocks для межагентной коммуникации. Отдельный репозиторий: [agentmessaging/protocol](https://github.com/agentmessaging/protocol) (20 stars, Apache 2.0). + +### Ключевые характеристики + +| Параметр | Значение | +|----------|----------| +| Версия | 0.1.3-draft | +| Лицензия | Apache 2.0 | +| Безопасность | Ed25519 криптографические подписи | +| Адресация | Email-подобная: `agent-name@tenant.provider` | +| Спецификации | 11 документов | + +### Формат сообщений + +Конверт содержит: +- `from` / `to` — адреса отправителя/получателя +- `subject` — тема +- `priority` — приоритет +- `in_reply_to` — для тредов +- `payload` — произвольный JSON +- `signature` — Ed25519 подпись + +Каноническая подпись: `from|to|subject|priority|in_reply_to|SHA256(payload)` + +### Доставка сообщений + +4 способа: +1. **WebSocket** — реалтайм для подключённых агентов +2. **REST API** — polling +3. **Webhook** — HTTP POST push +4. **Relay queue** — очередь для офлайн-агентов (TTL 7 дней по умолчанию) +5. **Mesh** — локальная маршрутизация без интернета + +### Провайдеры (федеративная модель) + +- **AI Maestro** (self-hosted): `http://localhost:23000/api/v1` — работает +- **crabmail.ai** — "coming soon" +- **lolainbox.com** — "coming soon" + +### Безопасность + +- Ed25519 подписи предотвращают подмену отправителя +- Trust-level аннотации для внешних сообщений +- Key revocation с федеративным распространением +- Защита от prompt injection (34 паттерна) +- SSRF-превенция для webhook + +### Критическая оценка AMP + +**Плюсы:** +- Формально специфицированный протокол (11 документов) +- Криптографическая безопасность по умолчанию +- Федеративная модель +- Поддержка офлайн-агентов + +**Минусы:** +- Всего 20 stars на GitHub +- Единственная реализация — сам AI Maestro +- Федерация заявлена, но 2 из 3 провайдеров "coming soon" +- По факту проприетарный протокол одного проекта, несмотря на Apache 2.0 лицензию +- Не совместим с ACP (Agent Communication Protocol), MCP или другими стандартами + +--- + +## Kanban Board + +AI Maestro включает kanban-доску с: +- **5 колонок** (статусы задач) +- **Drag-and-drop** перемещение карточек +- **Зависимости** между задачами +- **Шаренные задачи** между агентами +- Часть "War Room" — split-pane интерфейс для командных встреч + +**Детали реализации Kanban ограничены** — в документации и на сайте нет скриншотов или подробного описания UX. Описание сводится к маркетинговым фразам: "full Kanban board with drag-and-drop, dependencies, and 5 status columns." + +--- + +## Gateways — внешние интеграции + +AI Maestro поддерживает "Gateways" для подключения к внешним сервисам: +- **Slack** +- **Discord** +- **Email** +- **WhatsApp** + +Маршрутизация через синтаксис `@AIM:agent-name`. Заявлена защита от 34 паттернов prompt injection. + +--- + +## Skills System + +Система плагинов, устанавливаемых через `npx skills add`. Навыки автоматически триггерят: +- Поиск по памяти +- Запросы к Code Graph +- Поиск документации + +Совместим с 30+ агентами через "Agent Skills Standard". + +### Agent Identity (AID) + +Новая фича (v0.26.0, 24 марта 2026): агенты могут аутентифицироваться на OAuth 2.0 серверах используя Ed25519 identity. Без паролей, без API-ключей. + +--- + +## Релизная активность + +Последние 5 релизов (за 2 дня!): + +| Версия | Дата | Описание | +|--------|------|----------| +| v0.26.4 | 25.03.2026 | AMP mesh routing fix | +| v0.26.3 | 24.03.2026 | AID v0.2.0: независим от AMP | +| v0.26.2 | 24.03.2026 | Dynamic discovery для verification | +| v0.26.1 | 24.03.2026 | Переименование installer, auto-discover skills | +| v0.26.0 | 24.03.2026 | Agent Identity (AID) интеграция | + +5 релизов за 2 дня — это очень высокий темп. Может свидетельствовать как об активной разработке, так и о незрелости (частые фиксы только что выпущенных фич). + +--- + +## Сравнение с нашим продуктом (Claude Agent Teams UI) + +### Фундаментальные различия + +| Аспект | AI Maestro | Claude Agent Teams UI | +|--------|-----------|----------------------| +| **Подход** | Терминальный оркестратор (tmux wrapper) | Нативная UI-надстройка над Claude Code Agent Teams | +| **Агенты** | Любой терминальный AI | Claude Code (нативный Agent Teams API) | +| **Мультипровайдер** | Да (на уровне терминалов) | Нет (Claude-only, но с multi-model: Opus/Sonnet/Haiku) | +| **Kanban** | Есть (5 колонок, drag-drop, dependencies) | Есть (5 колонок, drag-drop, real-time) | +| **Межагентная связь** | AMP protocol (собственный) | Нативный Claude Code inbox/task system | +| **Code Review** | Не указан | Diff view с approve/reject/comment | +| **Deep Analytics** | Memory + Code Graph + Docs | Session analysis, context tracking, token usage | +| **Мультимашинность** | Peer mesh network | Нет (локальный) | +| **UI** | Web (Next.js, браузер) | Desktop (Electron) | +| **Процесс** | tmux sessions | stream-json CLI processes | + +### Где AI Maestro сильнее + +1. **Мультимашинность** — peer mesh сеть, агенты на разных компьютерах. У нас этого нет вообще. +2. **Мультиагентность** — поддерживает Claude, Aider, Cursor, Copilot и любой терминальный инструмент. Мы только Claude Code. +3. **Memory System** — CozoDB с графовыми запросами, векторным поиском, персистентной памятью. У нас аналитика сессий, но не полноценная "память" агентов. +4. **Code Graph** — визуализация кодобазы через ts-morph + CozoDB. У нас такого нет. +5. **External Gateways** — Slack, Discord, Email, WhatsApp. У нас встроенный MCP-сервер, но не gateway к мессенджерам. +6. **Scale** — заявляет 80+ агентов. Наш продукт ориентирован на команды 3-8 агентов. + +### Где наш продукт сильнее + +1. **Нативная интеграция с Claude Code** — мы работаем с официальным Agent Teams API, а не просто оборачиваем терминалы. Наши агенты нативно общаются через inbox, шарят задачи, имеют structured task references. +2. **Code Review** — полноценный diff view с accept/reject/comment, как в Cursor. У AI Maestro это не заявлено. +3. **Kanban UX** — у нас real-time обновления, direct messaging на карточках, quick actions, structured task references с кросс-ссылками. AI Maestro заявляет Kanban, но без деталей UX. +4. **Deep Session Analysis** — bash commands, reasoning, subprocesses breakdown, chunk timeline. AI Maestro показывает терминал, но не анализирует сессии. +5. **Context Monitoring** — 6 категорий контекста (CLAUDE.md, tool outputs, thinking, team coordination), token usage by category. Уникальная фича. +6. **Desktop App** — нативный Electron, не браузерная вкладка. +7. **DM to agents** — прямые сообщения конкретному агенту с карточки задачи. +8. **Zero-setup** — встроенная установка Claude Code и аутентификация. AI Maestro требует Node.js + tmux + установку. +9. **Built-in Code Editor** — редактор файлов с Git support. +10. **Post-compact context recovery** — восстановление инструкций после context compaction. + +### Фундаментальная разница в философии + +**AI Maestro** = "Terminal multiplexer on steroids" — оборачивает tmux, добавляет UI и межагентную коммуникацию. Агенты — это просто терминальные сессии. Протокол AMP — собственный, не стандартный. + +**Claude Agent Teams UI** = "CTO dashboard for Claude teams" — нативная надстройка над Claude Code Agent Teams, с глубоким пониманием внутренних протоколов Claude (stream-json, inbox, tasks). Агенты — это структурированные сущности с ролями, задачами и коммуникацией. + +--- + +## Рыночное позиционирование + +AI Maestro позиционирован в [awesome-agent-orchestrators](https://github.com/andyrewlee/awesome-agent-orchestrators) в категории **"Parallel Agent Runners"** наряду с 38 другими инструментами. + +### Конкуренты AI Maestro (не наши) + +| Инструмент | Фокус | Stars | +|-----------|-------|-------| +| **Maestro** (RunMaestro) | Desktop orchestrator, Claude/Codex/OpenCode | 2000+ | +| **Vibe Kanban** (BloopAI) | Kanban + Git worktree + MCP | N/A | +| **Claw-Kanban** | Kanban + role-based auto-assignment | N/A | +| **Agent Orchestrator** (ComposioHQ) | Plugin-based, tracker-agnostic | N/A | + +RunMaestro (отдельный проект) — самый серьёзный конкурент для AI Maestro: 2000+ stars, desktop app, Group Chat, Auto Run, Mobile Remote Control. + +--- + +## Оценки + +### Надёжность решения: 6/10 + +- Проект одного разработчика (249 из ~270 коммитов) +- Зависимость от CozoDB (нишевая БД) +- 5 релизов за 2 дня — признак незрелости +- AMP протокол — 20 stars, единственная реализация +- Нет community reviews (Reddit/HN) +- Нет automated tests (не видно в описании) + +### Уровень угрозы для нашего продукта: 4/10 + +- Другая ниша: мультиагентный терминальный оркестратор vs нативный Claude Teams UI +- Наша аудитория — пользователи Claude Code Agent Teams +- Их аудитория — пользователи 3+ разных AI-инструментов +- Пересечение небольшое: только если пользователь Claude Code решит добавить другие инструменты + +### Что стоит позаимствовать + +1. **Memory System** — персистентная память агентов между сессиями. Наши агенты теряют контекст при рестарте. CozoDB — overengineered для нас, но концепция ценная. +2. **Code Graph** — визуализация кодобазы. Можно реализовать через tree-sitter или ts-morph + простое хранение. +3. **Multi-machine** — даже не P2P mesh, но хотя бы возможность подключаться к remote Claude Code сессиям. +4. **External integrations** — Slack/Discord уведомления о прогрессе задач. + +--- + +## Источники + +- [GitHub: 23blocks-OS/ai-maestro](https://github.com/23blocks-OS/ai-maestro) +- [AI Maestro Website](https://ai-maestro.23blocks.com/) +- [AMP Protocol: agentmessaging/protocol](https://github.com/agentmessaging/protocol) +- [Agent Messaging Protocol Website](https://agentmessaging.org/) +- [CozoDB](https://github.com/cozodb/cozo) +- [Medium: "Your AI Agent Has Amnesia"](https://medium.com/23blocks/your-ai-agent-has-amnesia-heres-how-we-fixed-it-49980712f2e4) (paywall) +- [Medium: "From 47 Terminal Windows to One Dashboard"](https://medium.com/23blocks/building-ai-maestro-from-47-terminal-windows-to-one-beautiful-dashboard-64cd25ff3b43) (paywall) +- [awesome-agent-orchestrators](https://github.com/andyrewlee/awesome-agent-orchestrators) +- [Maestro vs Superpowers vs ECC comparison gist](https://gist.github.com/jeffscottward/de77a769d9e25a8ccdc92b65291b1c34) diff --git a/docs/research/competitor-spawn-patterns.md b/docs/research/competitor-spawn-patterns.md new file mode 100644 index 00000000..73471f08 --- /dev/null +++ b/docs/research/competitor-spawn-patterns.md @@ -0,0 +1,523 @@ +# Competitor Agent Spawn Patterns Research + +**Date**: 2026-03-25 + +## Executive Summary + +Все 4 конкурента построили собственные adapter-слои для spawning CLI-агентов. Ни один не использует готовую библиотеку. Паттерн единый: **интерфейс/trait + per-agent реализация + config-driven overrides**. + +Самый зрелый и переиспользуемый паттерн у **vibe-kanban** (Rust trait `StandardCodingAgentExecutor` + `enum_dispatch` + ACP harness). У **Emdash** паттерн проще (per-service TypeScript классы + auto-discovery). **Dorothy** самый примитивный (node-pty напрямую). **Superset** закрыт ELv2 лицензией. + +--- + +## 1. Vibe Kanban (BloopAI) + +**Repo**: [github.com/BloopAI/vibe-kanban](https://github.com/BloopAI/vibe-kanban) +**Язык**: Rust (backend) + TypeScript (frontend) +**Лицензия**: Apache-2.0 +**Stars**: ~23K +**Поддерживаемые агенты**: Claude Code, Codex, Gemini CLI, Copilot, Amp, Cursor, OpenCode, Droid, QwenCode, Qoder + +### Архитектура + +Самый архитектурно зрелый подход среди конкурентов. + +**Ядро** — Rust trait + enum_dispatch: + +```rust +#[async_trait] +#[enum_dispatch(CodingAgent)] +pub trait StandardCodingAgentExecutor { + async fn spawn(&self, current_dir: &Path, prompt: &str, + env: &ExecutionEnv) -> Result; + + async fn spawn_follow_up(&self, current_dir: &Path, prompt: &str, + session_id: &str, reset_to_message_id: Option<&str>, + env: &ExecutionEnv) -> Result; + + async fn spawn_review(&self, current_dir: &Path, prompt: &str, + session_id: Option<&str>, env: &ExecutionEnv) + -> Result; +} +``` + +**Dispatch через enum** (compile-time, zero-cost): + +```rust +#[enum_dispatch] +#[derive(Clone, Serialize, Deserialize, PartialEq, TS, Display)] +pub enum CodingAgent { + ClaudeCode, Amp, Gemini, Codex, Opencode, + CursorAgent, QwenCode, Copilot, Droid, QaMock +} +``` + +### Структура файлов + +``` +crates/executors/src/ + executors/ + mod.rs — trait + enum_dispatch + CodingAgent enum + claude.rs — ClaudeCode executor + gemini.rs — Gemini executor (через ACP harness) + codex.rs — Codex executor + amp.rs — Amp executor + copilot.rs — GitHub Copilot + cursor.rs — Cursor Agent + opencode.rs — OpenCode + droid.rs — Droid (factory.ai) + qwen.rs — QwenCode + qa_mock.rs — Mock для тестов + utils.rs — Общие утилиты + acp/ — ACP (Agent Communication Protocol) harness + mod.rs + client.rs — ACP client + harness.rs — Spawn + session lifecycle + session.rs — Session management + normalize_logs.rs — Log normalization + claude/ — Claude-specific subdirectory + codex/ — Codex-specific subdirectory + cursor/ — Cursor-specific subdirectory + droid/ — Droid-specific subdirectory + opencode/ — OpenCode-specific subdirectory + command.rs — CommandBuilder (base cmd + params + overrides) + env.rs — ExecutionEnv (env vars, repo context) + executor_discovery.rs — Auto-discovery + caching + mcp_config.rs — MCP server config per agent + model_selector.rs — Model selection logic + profile.rs — Agent profiles (DEFAULT, APPROVALS variants) + approvals.rs — Permission/approval system + stdout_dup.rs — Stdout duplication utilities + lib.rs — Crate root +``` + +### Как добавить нового агента (на примере Qoder PR #1759) + +1. `crates/executors/src/executors/qoder.rs` — реализация trait +2. `mod.rs` — добавить в `CodingAgent` enum +3. `mcp_config.rs` — MCP Passthrough adapter +4. `default_profiles.json` — профили (DEFAULT/APPROVALS) +5. `generate_types.rs` — ts-rs type generation +6. `shared/types.ts` — TypeScript enum (автогенерация) +7. `shared/schemas/qoder.json` — JSON schema +8. `docs/agents/qoder.mdx` — документация + +### Пример: Gemini executor + +``` +Base command: "npx -y @google/gemini-cli@0.29.3" +Flags: --experimental-acp, --model , --yolo (if auto mode) +Harness: AcpAgentHarness — manages spawn, follow-up, session lifecycle +Output: ACP protocol (structured agent communication) +``` + +### Ключевые паттерны + +- **CommandBuilder** (builder pattern): base cmd → params → overrides → platform-specific split → CommandParts +- **ExecutionEnv**: HashMap env vars + repo context, inject into tokio::Command +- **CmdOverrides**: replace base cmd / append params / set env vars (per-profile) +- **ACP Harness**: shared session/spawn logic for ACP-compatible agents (Gemini, Qoder, etc.) +- **executor_discovery**: async discovery + caching по (path, command_key, agent_type) +- **ts-rs**: Rust types → TypeScript types автогенерация + +### Оценка + +| Метрика | Значение | +|---------|----------| +| LOC adapter layer | ~2000-3000 (весь crate executors) | +| Паттерн | trait + enum_dispatch + CommandBuilder | +| Сложность добавления агента | ~150-200 LOC per agent | +| Можно переиспользовать? | Нет (Rust, другой стек) | +| Можно скопировать паттерн? | ДА — отличный reference | +| Надёжность подхода | 9/10 | + +--- + +## 2. Emdash (General Action) + +**Repo**: [github.com/generalaction/emdash](https://github.com/generalaction/emdash) +**Язык**: TypeScript (Electron) +**Лицензия**: MIT +**Stars**: ~6K +**YC W26** +**Поддерживаемые агенты**: 22+ (Claude Code, Codex, Gemini, Amp, Cursor, Copilot, Goose, Droid, Kiro, Qwen, OpenCode, Cline, Continue, Codebuff, Charm, Kilocode, Kimi, Autohand, Auggie, Rovo Dev, Mistral Vibe, Pi) + +### Архитектура + +Per-service TypeScript классы + auto-discovery. Самый близкий к нашему стеку. + +**Ключевые файлы**: + +``` +src/main/services/ + CodexService.ts — Manages Codex CLI child processes + log streaming + CodexSessionService.ts — Session management for Codex + ClaudeConfigService.ts — Claude-specific configuration + ClaudeHookService.ts — Claude hooks integration + AgentEventService.ts — Agent lifecycle events + TaskLifecycleService.ts — Task state machine + WorkspaceProviderService.ts — Provider workspace management + TerminalConfigParser.ts — CLI terminal config detection + ptyManager.ts — PTY session management (node-pty) + ptyIpc.ts — PTY IPC communication + ConnectionsService.ts — Connection management + RepositoryManager.ts — Git repository management + ProjectSettingsService.ts + DatabaseService.ts — SQLite (drizzle) + AutoUpdateService.ts + __tests__/ — Tests + fs/ — File system services + git-core/ — Git operations + mcp/ — MCP protocol + skills/ — Skills system + ssh/ — SSH remote development +``` + +### Как добавить провайдера (из документации) + +1. Include: provider name, CLI invocation command, auth notes, setup steps +2. Team wires up provider selection in UI and adds to Integrations matrix +3. Providers auto-detected when CLI is in PATH + +### Spawn-паттерн + +- `node:child_process.spawn()` для CLI агентов +- `node-pty` для terminal sessions +- Per-service классы (CodexService, ClaudeConfigService) +- `TerminalConfigParser` для auto-detection CLI в PATH +- `AgentEventService` для lifecycle events (running/waiting/completed/error) +- SQLite (drizzle ORM) для персистенции + +### Ключевые особенности + +- **Auto-discovery**: провайдеры детектятся автоматически по наличию CLI в PATH +- **Native deps**: sqlite3, node-pty, keytar (rebuilt per Electron version) +- **Worktree isolation**: каждый агент в своём git worktree +- **SSH remote**: агенты могут работать на удалённых машинах через SSH/SFTP +- **Best-of-N**: запуск нескольких агентов на одну задачу, выбор лучшего + +### Оценка + +| Метрика | Значение | +|---------|----------| +| LOC adapter layer | ~1500-2000 (services + pty) | +| Паттерн | Per-service classes + auto-discovery | +| Сложность добавления агента | Средняя (новый service file) | +| Можно переиспользовать код? | Потенциально ДА (MIT, TypeScript, Electron) | +| Можно скопировать паттерн? | ДА — очень близко к нашему стеку | +| Надёжность подхода | 7/10 (less structured than vibe-kanban) | + +--- + +## 3. Dorothy (Charlie85270) + +**Repo**: [github.com/Charlie85270/Dorothy](https://github.com/Charlie85270/Dorothy) +**Язык**: TypeScript (Electron + Next.js) +**Лицензия**: MIT +**Stars**: ~3K +**Поддерживаемые агенты**: Claude Code (primarily), расширяется + +### Архитектура + +Самый простой подход — node-pty напрямую, без абстракции adapter layer. + +``` +electron/ + agent-manager.ts — Agent lifecycle & parallel execution (node-pty) + pty-manager.ts — Terminal session multiplexing + window-manager.ts — Window management + services/ + telegram-bot + slack-bot + kanban-automation + mcp-server-launcher + api-server +mcp-orchestrator/ — Super Agent MCP server +mcp-kanban/ — Kanban automation MCP +``` + +### Spawn-паттерн + +- `node-pty` — каждый агент в изолированной PTY-сессии +- Статус определяется парсингом stdout patterns (running/waiting/completed/error) +- N параллельных агентов с отдельными проектами +- Super Agent (мета-агент) контролирует другие через MCP tools +- Cron-based scheduling для повторяющихся задач +- Skills system для extensibility + +### Ключевые особенности + +- **Нет абстракции агентов**: привязан к Claude Code, нет interface для разных CLI +- **Kanban**: задачи → колонки → automatic agent assignment по skills +- **Automations**: GitHub PR/issue polling → agent spawning +- **Remote control**: Telegram/Slack bot для управления + +### Оценка + +| Метрика | Значение | +|---------|----------| +| LOC adapter layer | ~500-800 (agent-manager + pty-manager) | +| Паттерн | Direct node-pty, no abstraction | +| Сложность добавления агента | Высокая (нет interface) | +| Можно переиспользовать код? | Да (MIT), но мало что полезного | +| Можно скопировать паттерн? | НЕТ — слишком примитивный | +| Надёжность подхода | 5/10 | + +--- + +## 4. Superset (superset-sh) + +**Repo**: [github.com/superset-sh/superset](https://github.com/superset-sh/superset) +**Язык**: TypeScript (Electron, monorepo Turborepo + Bun) +**Лицензия**: Elastic License 2.0 (ELv2) — НЕ open-source! +**Stars**: ~7.8K +**Поддерживаемые агенты**: Claude Code, Codex, Aider, Copilot, Cursor Agent, Gemini CLI, OpenCode + custom + +### Архитектура + +Monorepo с 6 apps. Multi-process Electron с 5 entry points: + +``` +apps/desktop/src/ + main/ + index.ts — Main app entry + terminal-host/ + index.ts — Persistent daemon for terminal sessions + pty-subprocess.ts — PTY handler (node-pty) + git-task-worker.ts — Worker thread for Git ops + host-service/ + index.ts — Local HTTP server + +packages/ + @superset/trpc — tRPC routers + @superset/ui — Shared React components + @superset/local-db — SQLite (Drizzle) + @superset/db — PostgreSQL (Neon, cloud sync) +``` + +### Spawn-паттерн + +- **Terminal Host daemon**: persistent subprocess managing terminal sessions +- **PTY subprocess**: node-pty forked on-demand +- **Git Worker**: heavy git ops offloaded to worker_threads +- **tRPC over Electron IPC**: renderer ↔ main communication +- **Worktree isolation**: каждая задача в своём git worktree с уникальным branch +- **Port allocation**: SUPERSET_PORT_BASE + 20 портов на workspace + +### Ключевые особенности + +- **Multi-process**: 5 entry points, daemon-based terminal management +- **Dual DB**: local SQLite + cloud PostgreSQL (ElectricSQL sync) +- **Better Auth**: OAuth deep links для десктопа +- **.superset/config.json**: workspace setup/teardown scripts + +### Оценка + +| Метрика | Значение | +|---------|----------| +| LOC adapter layer | Неизвестно (code not browsable) | +| Паттерн | Multi-process + terminal-host daemon | +| Сложность добавления агента | Неизвестно | +| Можно переиспользовать код? | НЕТ (Elastic License 2.0) | +| Можно скопировать паттерн? | Частично (terminal-host daemon idea) | +| Надёжность подхода | 8/10 (production, enterprise users) | + +--- + +## CLI Agent Programmatic Spawn Reference + +### Claude Code + +```bash +claude --input-format stream-json --output-format stream-json --verbose +``` + +- **Bidirectional NDJSON protocol** over stdin/stdout +- Message types: `initialize`, `user`, `control_response` +- `--verbose` REQUIRED with stream-json +- `--print` mode for one-shot (no multi-turn) +- Session hooks do NOT run in `--print` mode +- Official docs: [incomplete](https://github.com/anthropics/claude-code/issues/24594) — community reverse-engineered +- VS Code extension spawns: `claude --output-format stream-json --verbose --input-format stream-json --max-thinking-tokens 0 --model default --permission-prompt-tool stdio` + +### Codex (OpenAI) + +```bash +codex exec --json "prompt" +``` + +- **JSONL output** (one event per line) +- Event types: `thread.started`, `turn.started`, `turn.completed`, `turn.failed`, `item.*` +- Item types: agent_message, reasoning, command_exec, file_change, mcp_tool_call +- `--output-schema` for structured final output +- `codex exec resume --json` for session resumption +- **App-server mode**: `codex app-server` — stateful JSON-RPC over stdio +- Auth: `CODEX_API_KEY` env var for non-interactive +- Schema BREAKING CHANGES between versions (item_type → type, assistant_message → agent_message) + +### Gemini CLI (Google) + +```bash +gemini -p "prompt" --output-format json +# or streaming: +gemini -p "prompt" --output-format stream-json +``` + +- `-p` flag for non-interactive headless mode +- `--output-format json` — full response + stats +- `--output-format stream-json` — real-time JSONL events +- `--yolo` — auto-approve all tool calls +- `--experimental-acp` — Agent Communication Protocol (used by vibe-kanban) +- **Known issues**: response field may contain markdown-wrapped JSON instead of clean JSON +- Stdin piping supported for additional context + +### Amp (Sourcegraph) + +```bash +amp --execute "prompt" --stream-json +``` + +- `--stream-json` — JSONL output (REQUIRES `--execute`) +- `--stream-json-input` — JSONL input via stdin (REQUIRES `--stream-json`) +- `--stream-json-thinking` — includes thinking blocks (extends schema) +- **Claude Code compatible format** (mostly) +- Multi-turn: `amp threads continue [thread-id]` + `--stream-json-input` +- Auth: `AMP_API_KEY` env var for CI/CD +- Elixir SDK exists as reference: spawns CLI + parses stream-json + +### Goose (Block) + +```bash +goose run -t "prompt" +# or from file: +goose run -i instructions.md +``` + +- `goose run` — non-interactive one-shot mode +- `--output-format json` — [feature request #4419, marked Done](https://github.com/block/goose/issues/4419) +- `--format json` — for session/recipe listing +- Max 10 concurrent subagents (hard-coded) +- 5 min default timeout, 25 max turns +- `GOOSE_SUBAGENT_MAX_TURNS` env override + +--- + +## Сравнительная таблица + +| | Vibe Kanban | Emdash | Dorothy | Superset | +|---|---|---|---|---| +| **Язык** | Rust | TypeScript | TypeScript | TypeScript | +| **Лицензия** | Apache-2.0 | MIT | MIT | ELv2 | +| **Используют готовую библиотеку?** | Нет | Нет | Нет | Нет | +| **Паттерн** | trait + enum_dispatch | Per-service classes | Direct node-pty | Multi-process daemon | +| **Абстракция агентов** | `StandardCodingAgentExecutor` trait | Per-service (CodexService, etc.) | Нет | Terminal-host daemon | +| **Количество агентов** | 10+ | 22+ | 1 (Claude) | 8+ | +| **Сложность добавления** | ~150-200 LOC | ~300-500 LOC | Hard (no interface) | Unknown | +| **LOC adapter layer** | ~2000-3000 | ~1500-2000 | ~500-800 | Unknown | +| **Auto-discovery** | Да (executor_discovery) | Да (PATH detection) | Нет | Unknown | +| **MCP support** | Passthrough per agent | Да | MCP servers | Да | +| **ACP protocol** | Да (shared harness) | Нет | Нет | Нет | +| **Type generation** | ts-rs (Rust → TS) | N/A | N/A | N/A | +| **Isolation** | Git worktrees | Git worktrees | Separate projects | Git worktrees | +| **Можно reuse код?** | Нет (Rust) | Да (MIT, TS) | Да (MIT) | Нет (ELv2) | + +--- + +## Выводы и рекомендации для Claude Agent Teams UI + +### 1. Какой паттерн взять за основу? + +**Рекомендация: гибрид vibe-kanban + emdash подходов** + +От vibe-kanban взять: +- **Interface (trait) + per-agent implementation** — TypeScript interface вместо Rust trait +- **CommandBuilder pattern** — построение команды через builder с overrides +- **ExecutionEnv** — управление env vars + repo context +- **Profile system** — DEFAULT/APPROVALS варианты per agent +- **enum-dispatch idea** — в TS реализуется через discriminated union + factory + +От Emdash взять: +- **Auto-discovery** — детекция CLI в PATH +- **Per-service approach** — но с общим interface +- **node-pty integration** — для terminal sessions + +### 2. Предлагаемый TypeScript interface + +```typescript +interface AgentExecutor { + readonly agentType: AgentType; // discriminated union tag + + spawn(params: SpawnParams): Promise; + spawnFollowUp(params: FollowUpParams): Promise; + spawnReview?(params: ReviewParams): Promise; + + discover(): Promise; + isAvailable(): Promise; + + normalizeOutput(raw: string): string; + parseEvent(line: string): AgentEvent | null; +} + +interface SpawnParams { + workDir: string; + prompt: string; + env: ExecutionEnv; + model?: string; + approvalMode: 'auto' | 'supervised'; + mcpConfig?: string; +} + +interface SpawnedAgent { + process: ChildProcess; + sessionId: string; + stdout: ReadableStream; + stderr: ReadableStream; + kill(): Promise; + sendMessage(msg: string): Promise; +} +``` + +### 3. Что НЕ стоит делать + +- **Не использовать node-pty напрямую** (как Dorothy) — нет абстракции, сложно масштабировать +- **Не строить на Rust** (как vibe-kanban) — у нас TypeScript стек, overhead не оправдан +- **Не копировать multi-process daemon** (как Superset) — over-engineering для нашего случая +- **Не привязываться к одному протоколу** — у каждого CLI свой формат (stream-json, --json, --stream-json) + +### 4. Приоритет агентов для поддержки + +| Приоритет | Агент | Протокол | Сложность | +|-----------|-------|----------|-----------| +| P0 | Claude Code | stream-json bidirectional | Уже есть | +| P1 | Codex | `exec --json` JSONL | Средняя | +| P1 | Gemini CLI | `--output-format stream-json` | Средняя | +| P2 | Amp | `--execute --stream-json` | Средняя (CC-compatible) | +| P2 | Goose | `run -t` + `--output-format json` | Средняя | +| P3 | OpenCode | TBD | Исследовать | +| P3 | Cursor Agent | TBD | Исследовать | + +--- + +## Источники + +- [Vibe Kanban (BloopAI)](https://github.com/BloopAI/vibe-kanban) — Apache-2.0, 23K stars +- [Vibe Kanban AGENTS.md](https://github.com/BloopAI/vibe-kanban/blob/main/AGENTS.md) +- [Vibe Kanban executors crate](https://github.com/BloopAI/vibe-kanban/tree/main/crates/executors/src/executors) +- [Vibe Kanban PR #1759 — Qoder executor pattern](https://github.com/BloopAI/vibe-kanban/pull/1759) +- [Emdash (General Action)](https://github.com/generalaction/emdash) — MIT, 6K stars +- [Emdash Providers Documentation](https://docs.emdash.sh/providers) +- [Emdash AGENTS.md](https://github.com/generalaction/emdash/blob/main/AGENTS.md) +- [Dorothy (Charlie85270)](https://github.com/Charlie85270/Dorothy) — MIT, 3K stars +- [Superset (superset-sh)](https://github.com/superset-sh/superset) — ELv2, 7.8K stars +- [Superset DeepWiki Architecture](https://deepwiki.com/superset-sh/superset/1.1-architecture-overview) +- [Codex CLI Reference](https://developers.openai.com/codex/cli/reference) +- [Codex Non-Interactive Mode](https://developers.openai.com/codex/noninteractive) +- [Codex JSON output issues](https://github.com/openai/codex/issues/2288) +- [Gemini CLI Headless Mode](https://google-gemini.github.io/gemini-cli/docs/cli/headless.html) +- [Gemini CLI JSON issues](https://github.com/google-gemini/gemini-cli/issues/9009) +- [Amp Streaming JSON](https://ampcode.com/news/streaming-json) +- [Amp CLI Manual](https://ampcode.com/manual) +- [Goose CLI Commands](https://block.github.io/goose/docs/guides/goose-cli-commands/) +- [Goose JSON output request #4419](https://github.com/block/goose/issues/4419) +- [Claude Code stream-json docs gap #24594](https://github.com/anthropics/claude-code/issues/24594) +- [Claude Code Automation Skill (LobeHub)](https://lobehub.com/it/skills/coreyja-dotfiles-claude-code-automation) diff --git a/docs/research/inter-agent-communication-standards.md b/docs/research/inter-agent-communication-standards.md new file mode 100644 index 00000000..f47ae5f7 --- /dev/null +++ b/docs/research/inter-agent-communication-standards.md @@ -0,0 +1,639 @@ +# Inter-Agent Communication Standards: How Different AI Agents Can Talk to Each Other + +**Date:** 2026-03-25 +**Status:** Research complete +**Goal:** Determine the best way for AI agents (Claude, Codex, Gemini) to communicate with each other + +--- + +## Table of Contents + +1. [Executive Summary](#executive-summary) +2. [Protocol Landscape Overview](#protocol-landscape-overview) +3. [A2A (Agent-to-Agent Protocol)](#1-a2a--agent-to-agent-protocol) +4. [ACP (Agent Communication Protocol) by IBM/BeeAI](#2-acp--agent-communication-protocol-by-ibmbeeai) +5. [Agent Client Protocol (ACP) by Zed](#3-agent-client-protocol-acp-by-zed) +6. [MCP for Inter-Agent Communication](#4-mcp-for-inter-agent-communication) +7. [Agent Network Protocol (ANP)](#5-agent-network-protocol-anp) +8. [MCP Agent Mail](#6-mcp-agent-mail) +9. [File-Based Inbox Pattern](#7-file-based-inbox-pattern-claude-code-agent-teams) +10. [SQLite/Redis Message Bus](#8-sqliteredis-message-bus) +11. [Cross-Provider Orchestration Tools](#9-cross-provider-orchestration-tools) +12. [Comparison Matrix](#comparison-matrix) +13. [Recommendations for Electron App](#recommendations-for-our-electron-app) +14. [Sources](#sources) + +--- + +## Executive Summary + +На март 2026 года НЕ существует единого универсального стандарта для межагентной коммуникации между разными провайдерами (Claude, Codex, Gemini). Однако экосистема быстро консолидируется вокруг нескольких протоколов: + +| Уровень | Протокол | Назначение | +|---------|----------|------------| +| Tool access | **MCP** (Anthropic) | Агент <-> инструменты/данные | +| Agent-to-Agent | **A2A** (Google/Linux Foundation) | Агент <-> агент (сетевой) | +| Editor-to-Agent | **ACP** (Zed) | Редактор <-> CLI-агент | +| Local coordination | **File-based inbox** (Claude Code) | Агент <-> агент (локальный) | +| Local coordination | **MCP Agent Mail** | Агент <-> агент (MCP + SQLite + Git) | + +**Ключевые выводы:** + +1. **A2A** -- самый зрелый протокол для agent-to-agent, но он HTTP/server-based и плохо подходит для чисто локального Electron-приложения без встроенного сервера. +2. **File-based inbox** (как в Claude Code Agent Teams) -- самый простой и проверенный паттерн для локальной коммуникации. Работает в Electron без проблем. +3. **MCP Agent Mail** -- наиболее feature-rich локальное решение (идентичности, mailboxes, file leases, searchable threads), но Python-based. +4. **MCP** сам по себе эволюционирует в сторону inter-agent communication (AWS, Microsoft активно контрибьютят). +5. **OpenCode** -- единственный инструмент, который реально запускает Claude + Codex + Gemini в одной команде через unified inbox pattern. + +--- + +## Protocol Landscape Overview + +``` + ┌─────────────────────────────────────┐ + │ Agent Network Protocol │ + │ (ANP - open internet, P2P, DID) │ + └──────────────────┬──────────────────┘ + │ + ┌──────────────────┴──────────────────┐ + │ Agent-to-Agent Protocol (A2A) │ + │ (Google/LF, HTTP, JSON-RPC, tasks) │ + └──────────────────┬──────────────────┘ + │ + ┌────────────────────────────┼────────────────────────────┐ + │ │ │ +┌─────────┴─────────┐ ┌─────────────┴─────────────┐ ┌─────────┴─────────┐ +│ MCP (Anthropic) │ │ Agent Client Protocol │ │ File-based inbox │ +│ Agent <-> Tools │ │ (Zed, editor <-> agent) │ │ (Claude Code local)│ +└───────────────────┘ └───────────────────────────┘ └───────────────────┘ +``` + +--- + +## 1. A2A -- Agent-to-Agent Protocol + +**Создатель:** Google, теперь под Linux Foundation +**Статус:** v0.3.0 (Draft v1.0), 150+ организаций-участников +**GitHub:** [a2aproject/A2A](https://github.com/a2aproject/A2A) -- 500+ stars (JS SDK) + +### Как работает + +1. Каждый агент публикует **Agent Card** (JSON) по адресу `/.well-known/agent.json` -- имя, навыки, endpoint, auth +2. Клиент-агент отправляет **задачу** серверу-агенту через JSON-RPC 2.0 over HTTPS +3. Задача проходит жизненный цикл: `submitted` -> `working` -> `completed`/`canceled` +4. Поддерживается streaming через SSE (Server-Sent Events) +5. Результат задачи -- **артефакт** (текст, изображения, файлы) + +### TypeScript SDK + +```bash +npm install @a2a-js/sdk +# Для Express-интеграции: +npm install express +``` + +Пакет: [`@a2a-js/sdk`](https://www.npmjs.com/package/@a2a-js/sdk) v0.3.10 +- 88 зависимых проектов на npm +- Поддержка Express, gRPC, in-memory task store +- Полные типы TypeScript + +**Минимальный сервер (Express):** +```typescript +import { AgentCard, AgentExecutor, DefaultRequestHandler, InMemoryTaskStore } from '@a2a-js/sdk'; +import { agentCardHandler, jsonRpcHandler } from '@a2a-js/sdk/server/express'; +import express from 'express'; + +const card: AgentCard = { + name: 'MyAgent', + description: 'Example agent', + protocolVersion: '0.3.0', + url: 'http://localhost:4000/a2a/jsonrpc', + skills: [{ id: 'hello', name: 'Hello', description: 'Says hello' }], + capabilities: {}, + defaultInputModes: ['text/plain'], + defaultOutputModes: ['text/plain'], +}; + +class MyExecutor implements AgentExecutor { + async execute(context) { + context.eventBus.publish({ type: 'message', message: { role: 'agent', parts: [{ type: 'text', text: 'Hello!' }] } }); + context.eventBus.finished(); + } +} + +const handler = new DefaultRequestHandler(card, new InMemoryTaskStore(), new MyExecutor()); +const app = express(); +app.get('/a2a/agent-card', agentCardHandler(handler)); +app.post('/a2a/jsonrpc', jsonRpcHandler(handler)); +app.listen(4000); +``` + +### Оценка для Electron + +| Критерий | Оценка | +|----------|--------| +| Зрелость протокола | 8/10 -- v0.3, Linux Foundation, 150+ организаций | +| TypeScript поддержка | 9/10 -- официальный SDK, полные типы | +| Electron-совместимость | 5/10 -- требует HTTP-сервер, придётся встраивать Express в main process | +| Локальная работа | 4/10 -- спроектирован для сетевого взаимодействия, localhost возможен но overhead | +| Кросс-провайдер | 9/10 -- протокол-агностик по дизайну | + +### Вердикт + +A2A -- правильный протокол для **распределённых сетевых** мультиагентных систем. Для локального Electron-приложения это overkill, но если планируется поддержка **удалённых агентов** в будущем -- имеет смысл держать в архитектуре. + +--- + +## 2. ACP -- Agent Communication Protocol by IBM/BeeAI + +**Создатель:** IBM Research / BeeAI +**Статус:** MERGED WITH A2A под Linux Foundation. Активная разработка свёрнута. +**GitHub:** [i-am-bee/acp](https://github.com/i-am-bee/acp) + +### Как работает + +- REST-native (не JSON-RPC как A2A) -- стандартные HTTP-конвенции +- Не требует SDK -- можно использовать через curl/Postman +- Async по умолчанию (fire-and-forget с taskId, poll/subscribe для прогресса) +- Sync также поддерживается (простой HTTP POST) +- Offline discovery -- метаданные агента встроены в пакет распространения + +### TypeScript SDK + +```bash +npm install @anthropic-ai/beeai-framework # TypeScript starter +``` + +BeeAI Framework предоставляет TypeScript-клиент для ACP. + +### Оценка для Electron + +| Критерий | Оценка | +|----------|--------| +| Зрелость | 3/10 -- merged into A2A, активная разработка прекращена | +| TypeScript | 6/10 -- клиентский SDK есть | +| Electron | 5/10 -- REST-based, аналогично A2A | +| Рекомендация | НЕ использовать, мигрировать на A2A | + +### Вердикт + +**Устаревший.** Объединён с A2A. Использовать только если уже есть код на ACP -- в таком случае мигрировать на A2A. + +--- + +## 3. Agent Client Protocol (ACP) by Zed + +**ВНИМАНИЕ:** Это ДРУГОЙ протокол с тем же акронимом ACP. Не путать с IBM ACP. + +**Создатель:** Zed Industries +**Статус:** Активный, ACP Registry запущен (2026) +**GitHub:** [agentclientprotocol/agent-client-protocol](https://github.com/agentclientprotocol/agent-client-protocol) +**Сайт:** [agentclientprotocol.com](https://agentclientprotocol.com/) + +### Как работает + +- Стандартизирует связь **редактор <-> CLI-агент** (аналогично LSP для языковых серверов) +- JSON-RPC over stdio (локальные агенты как subprocess) +- JSON-RPC over HTTP/WebSocket (удалённые агенты) +- Переиспользует JSON-представления из MCP где возможно +- Добавляет UX-специфичные типы (diff display, file edits) + +### Поддерживаемые агенты и редакторы + +**Агенты:** +- Claude Code (через Zed SDK adapter) +- Codex CLI +- Gemini CLI (reference implementation) +- OpenCode +- Goose (Block/Square) +- GitHub Copilot CLI +- Kiro CLI + +**Редакторы:** +- Zed (нативная поддержка) +- JetBrains IDEs (скоро) +- Neovim (CodeCompanion, avante.nvim) +- Emacs (agent-shell) +- VS Code (расширение ACP Client) + +### Оценка для Electron + +| Критерий | Оценка | +|----------|--------| +| Зрелость | 7/10 -- активный, registry, множество интеграций | +| TypeScript | 7/10 -- JSON-RPC, спецификация есть | +| Electron | 8/10 -- stdio-based отлично работает с child_process | +| Назначение | Editor <-> Agent, НЕ agent <-> agent | + +### Вердикт + +ACP (Zed) -- **идеален для связи нашего Electron UI с CLI-агентами**. Но это протокол editor<->agent, не agent<->agent. Для межагентной коммуникации нужен другой протокол поверх. + +--- + +## 4. MCP для Inter-Agent Communication + +**Создатель:** Anthropic +**Статус:** Активно развивается в сторону agent-to-agent (2026 roadmap) + +### Как это работает для inter-agent + +MCP изначально создан для tool integration, но его архитектура позволяет agent-to-agent: + +1. **Агент A запускает MCP-сервер**, объявляя свои capabilities как tools +2. **Агент B подключается как MCP-клиент** и вызывает tools агента A +3. Streaming через SSE для real-time обновлений +4. Session resumability для долгих задач +5. Multi-turn interactions через elicitation + +### Паттерн "Agent as MCP Server" + +``` +Agent A (MCP Client) ──────► Agent B (MCP Server) + │ │ + │ call tool "analyze" │ + ├─────────────────────────►│ + │ │ runs analysis + │ streaming results │ + │◄─────────────────────────┤ +``` + +### Кто продвигает + +- **AWS** активно контрибьютит в inter-agent MCP, работает с LangGraph, CrewAI, LlamaIndex +- **Microsoft** показала, что A2A-коммуникацию можно построить на MCP +- **Block (Square)** -- 1000+ инженеров используют MCP-координацию (Goose) + +### TypeScript SDK + +```bash +npm install @modelcontextprotocol/sdk zod +``` + +Официальный SDK: [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) + +### Оценка для Electron + +| Критерий | Оценка | +|----------|--------| +| Зрелость для inter-agent | 5/10 -- изначально не для этого, но быстро эволюционирует | +| TypeScript | 10/10 -- официальный SDK, отличная поддержка | +| Electron | 9/10 -- stdio transport, уже используется в нашем приложении | +| Кросс-провайдер | 8/10 -- все провайдеры поддерживают MCP | + +### Вердикт + +MCP -- **наиболее практичный выбор** для нашего Electron-приложения. Мы уже используем MCP. Паттерн "agent as MCP server" позволяет любому агенту объявить tools/resources, а другой агент подключается как клиент. Roadmap 2026 явно включает agent-to-agent capabilities. + +--- + +## 5. Agent Network Protocol (ANP) + +**Создатель:** Open-source community +**Статус:** Draft, white paper на arXiv +**GitHub:** [agent-network-protocol/AgentNetworkProtocol](https://github.com/agent-network-protocol/AgentNetworkProtocol) +**Сайт:** [agent-network-protocol.com](https://agent-network-protocol.com/) + +### Как работает + +Трёхуровневая архитектура: +1. **Identity & Encrypted Communication** -- W3C DID (Decentralized Identifiers), end-to-end encryption +2. **Meta-Protocol Layer** -- агенты САМИ договариваются о протоколе коммуникации +3. **Application Protocol** -- JSON-LD для описания capabilities + +Позиционирование: "HTTP для агентного интернета". Peer-to-peer, без центральных серверов. + +### Оценка для Electron + +| Критерий | Оценка | +|----------|--------| +| Зрелость | 2/10 -- draft, ранняя стадия | +| TypeScript | 2/10 -- нет SDK | +| Electron | 3/10 -- P2P, сложная интеграция | +| Рекомендация | Следить, НЕ использовать сейчас | + +### Вердикт + +ANP -- интересная vision для **открытого агентного интернета** (peer-to-peer discovery, DID), но слишком рано для продакшна. Может стать актуален через 1-2 года. + +--- + +## 6. MCP Agent Mail + +**Создатель:** Jeff Emanuel (Dicklesworthstone) +**Статус:** Активный, первый open-source agent coordination tool (октябрь 2025) +**GitHub:** [Dicklesworthstone/mcp_agent_mail](https://github.com/Dicklesworthstone/mcp_agent_mail) +**Rust version:** [Dicklesworthstone/mcp_agent_mail_rust](https://github.com/Dicklesworthstone/mcp_agent_mail_rust) +**Сайт:** [mcpagentmail.com](https://mcpagentmail.com/) + +### Как работает + +- MCP-сервер, предоставляющий **34 tool** для координации агентов +- Каждый агент получает **идентичность** (memorable name: GreenCastle, BlueLake) +- **Inbox/Outbox** -- асинхронные mailbox для сообщений +- **Advisory File Reservations** -- агенты объявляют file leases (exclusive/shared) на globs +- **Searchable threads** -- FTS через SQLite +- **Git backing** -- все сообщения и артефакты в Git для аудита +- SQLite для индексации, Git как source of truth + +### Cross-Provider Support + +Работает с Claude Code, Codex, Gemini CLI, Factory Droid -- любой MCP-совместимый клиент. + +### Технические детали + +- Python-based сервер (FastMCP) +- Rust-реимплементация доступна (127.0.0.1:8765, TUI console) +- Не npm-пакет, установка через bash-скрипт +- Local-first, no cloud dependencies + +### Оценка для Electron + +| Критерий | Оценка | +|----------|--------| +| Зрелость | 7/10 -- production-used, хорошо документирован | +| TypeScript | 3/10 -- Python/Rust server, TS клиент через MCP SDK | +| Electron | 6/10 -- можно запустить как sidecar process, но Python/Rust зависимость | +| Feature-richness | 9/10 -- identities, mailboxes, file leases, FTS, Git audit | + +### Вердикт + +Самое feature-rich решение для координации агентов. **Проблема**: Python/Rust dependency. Для нашего Electron-приложения можно: +- Запустить как sidecar process +- Или реализовать ключевые идеи (mailbox, file leases) на TypeScript нативно + +--- + +## 7. File-Based Inbox Pattern (Claude Code Agent Teams) + +**Создатель:** Anthropic (Claude Code) +**Статус:** Production, Claude Code v2.1.32+ + +### Как работает + +Наиболее простой и проверенный паттерн: + +``` +~/.claude/teams/{team-name}/ +├── config.json # member registry +└── inboxes/ + ├── lead.json # lead's inbox + ├── frontend-dev.json # teammate inbox + └── backend-dev.json # teammate inbox +``` + +1. Отправитель **appends** JSON-объект в inbox-файл получателя +2. Получатель **polls** свой inbox-файл между turns +3. Формат сообщения: `{ from, text, timestamp, read }` +4. Broadcast = запись одного сообщения во ВСЕ inbox-файлы + +### Особенности + +- Zero dependencies -- только fs +- Inspectable -- `cat` любой inbox файл в реальном времени +- File I/O масштабируется для 3-5 агентов +- Нет real-time delivery -- получатель увидит сообщение только после текущего turn +- Ownership: каждый агент читает только СВОЙ inbox + +### Inbox/Outbox Pattern (улучшенный) + +``` +agent-a/ +├── inbox.json # входящие сообщения +├── outbox.json # исходящие (для аудита) +└── current-task.json + +agent-b/ +├── inbox.json +├── outbox.json +└── current-task.json +``` + +Правила координации: +- Агент пишет ТОЛЬКО в свой outbox и чужие inbox +- Агент читает ТОЛЬКО свой inbox и current-task +- Boot Sequence: при старте читать inbox.json, resume из current-task.json + +### Оценка для Electron + +| Критерий | Оценка | +|----------|--------| +| Зрелость | 9/10 -- production в Claude Code | +| TypeScript | 10/10 -- чистый fs/path, тривиальная реализация | +| Electron | 10/10 -- идеально, никаких зависимостей | +| Масштабируемость | 5/10 -- до ~10 агентов, потом I/O bottleneck | +| Feature-richness | 4/10 -- только messaging, нет identities/leases/FTS | + +### Вердикт + +**Лучший выбор для немедленного использования.** Мы УЖЕ используем этот паттерн в нашем приложении. Для межагентной коммуникации между разными провайдерами -- это самый простой путь: агенты любого провайдера пишут/читают JSON-файлы. + +--- + +## 8. SQLite/Redis Message Bus + +### SQLite Message Bus + +Паттерн из сообщества: Flask + SQLite message bus для ~16 агентов. + +**Особенности:** +- HTTP API для отправки/получения сообщений +- Broadcast messaging (omit "to" field) +- Reply chains через `reply_to` +- Priority levels (normal/high/urgent) +- Read receipts +- `journal_mode=WAL` для конкурентного доступа +- Auto-archiving старых сообщений + +### Redis Approaches + +| Подход | Плюсы | Минусы | +|--------|-------|--------| +| Redis Pub/Sub | Real-time, low latency | Ephemeral -- сообщения теряются | +| Redis Streams | Persistent, consumer groups | Требует Redis server | +| redis-bus | Autodiscovery, cache | Legacy (Python 2.7) | + +### Оценка для Electron + +| Критерий | Оценка | +|----------|--------| +| SQLite bus | 7/10 -- хорошо для Electron (better-sqlite3 уже есть) | +| Redis | 3/10 -- требует отдельный server, overkill для desktop | +| TypeScript | 8/10 (SQLite) / 6/10 (Redis) | +| Масштабируемость | 8/10 (SQLite WAL) / 9/10 (Redis) | + +### Вердикт + +**SQLite message bus** -- отличный апгрейд с file-based inbox, если нужна persistence, FTS, priority, read receipts. `better-sqlite3` уже хорошо работает в Electron. Redis -- overkill для локального desktop-приложения. + +--- + +## 9. Cross-Provider Orchestration Tools + +### OpenCode -- True Multi-Model Agent Teams + +OpenCode -- единственный инструмент, который **реально запускает Claude + Codex + Gemini в одной команде**. + +**Архитектура:** +- Event-driven inbox (не polling как Claude Code) +- Per-agent JSONL файлы: `{ id, from, text, timestamp, read }` +- Session injection для delivery (не file polling) +- Shared task list с claiming + +**Отличия от Claude Code:** +- Multi-model support (Claude, GPT, Gemini в одной команде) +- Peer-to-peer messaging (не только через lead) +- Event-driven (не polling) +- Append-only JSONL (не JSON array) +- Всё in-process (locks в памяти) + +### sub-agents-skills + +GitHub: [shinpr/sub-agents-skills](https://github.com/shinpr/sub-agents-skills) + +Позволяет использовать Codex, Claude Code, Gemini CLI как sub-agents из любого parent session. Cross-LLM делегация задач. + +### ZenFlow (Zencoder) + +Structured handoffs между Claude и Gemini с quality gates. Не open-source. + +### CC Switch + +Unified management: proxy Claude/Codex/Gemini, unified MCP panel, markdown editor с cross-app sync для CLAUDE.md/AGENTS.md/GEMINI.md. + +--- + +## Comparison Matrix + +| | A2A | MCP (inter-agent) | ACP (Zed) | File Inbox | MCP Agent Mail | SQLite Bus | +|---|---|---|---|---|---|---| +| **Зрелость** | 8/10 | 5/10 | 7/10 | 9/10 | 7/10 | 6/10 | +| **TS SDK** | 9/10 | 10/10 | 7/10 | 10/10 | 3/10 | 8/10 | +| **Electron-ready** | 5/10 | 9/10 | 8/10 | 10/10 | 6/10 | 7/10 | +| **Cross-provider** | 9/10 | 8/10 | 9/10 | 10/10 | 9/10 | 10/10 | +| **No server needed** | No | Partial | Yes (stdio) | Yes | No | Yes | +| **Real-time** | Yes (SSE) | Yes (SSE) | Yes | No (polling) | No | Polling | +| **Persistence** | Optional | No | No | File-based | Git+SQLite | SQLite | +| **File coordination** | No | No | No | No | Yes (leases) | No | +| **Identity system** | Agent Cards | No | No | No | Yes | No | +| **Сложность** | High | Medium | Medium | Very Low | High | Low | + +--- + +## Recommendations for Our Electron App + +### Немедленно (Phase 1) -- File-Based Inbox + +**Надёжность: 9/10 | Уверенность: 10/10** + +Мы уже используем file-based inbox для Claude Code Agent Teams. Этот же паттерн работает для ЛЮБОГО CLI-агента (Codex, Gemini CLI). Агенту не нужно знать протокол -- он просто читает/пишет JSON-файлы. + +``` +~/.claude_teams/{team-name}/inboxes/ +├── claude-lead.json +├── codex-worker.json +├── gemini-researcher.json +``` + +**Что нужно для cross-provider:** +1. Unified inbox format (уже есть: `{ from, text, timestamp, read }`) +2. Agent spawner для каждого CLI (Claude Code, Codex CLI, Gemini CLI) +3. Каждый агент получает system prompt с инструкцией читать/писать inbox files +4. Task board (shared JSON files с flock) + +### Среднесрочно (Phase 2) -- SQLite Message Bus + +**Надёжность: 8/10 | Уверенность: 8/10** + +Upgrade с file-based на SQLite для: +- Persistence и searchable history +- Priority levels и read receipts +- Better concurrency (WAL mode) +- FTS для поиска по сообщениям + +`better-sqlite3` уже отлично работает в Electron. + +### Долгосрочно (Phase 3) -- MCP-Based Inter-Agent + +**Надёжность: 6/10 | Уверенность: 6/10** + +Когда MCP roadmap 2026 реализует agent-to-agent capabilities: +- Каждый агент запускает MCP-сервер со своими capabilities +- Другие агенты подключаются как MCP-клиенты +- Streaming, session management, tool negotiation из коробки +- @modelcontextprotocol/sdk уже в нашем стеке + +### Если потребуются удалённые агенты (Phase 4) -- A2A + +**Надёжность: 7/10 | Уверенность: 5/10** + +A2A имеет смысл только если: +- Нужна коммуникация с агентами на других машинах +- Интеграция с enterprise-системами (Salesforce, SAP агенты) +- Cloud-hosted агенты + +В этом случае: встроить Express-сервер в Electron main process, использовать @a2a-js/sdk. + +### Конкретный ответ на вопрос: "Как заставить Claude поговорить с Codex?" + +**Самый простой работающий способ прямо сейчас:** + +1. Spawn Claude Code CLI как child_process +2. Spawn Codex CLI как child_process +3. Оба читают/пишут в общую директорию inbox-файлов +4. System prompt для каждого включает инструкцию: "To communicate with other agents, write to their inbox file at {path}" +5. Наше Electron-приложение выступает оркестратором: следит за inbox-файлами, доставляет сообщения через stdin, обновляет UI + +Это РОВНО то, что делает Claude Code Agent Teams, и ровно то, что OpenCode расширил для multi-provider. + +--- + +## Sources + +### Протоколы и спецификации +- [A2A Protocol Official Site](https://a2a-protocol.org/latest/) +- [A2A GitHub Repository](https://github.com/a2aproject/A2A) +- [A2A JS SDK](https://github.com/a2aproject/a2a-js) -- [@a2a-js/sdk npm](https://www.npmjs.com/package/@a2a-js/sdk) +- [Agent Client Protocol (Zed)](https://agentclientprotocol.com/) -- [GitHub](https://github.com/agentclientprotocol/agent-client-protocol) +- [ACP Registry](https://zed.dev/blog/acp-registry) +- [Agent Communication Protocol (IBM/BeeAI)](https://github.com/i-am-bee/acp) -- [IBM Research](https://research.ibm.com/projects/agent-communication-protocol) +- [Agent Network Protocol](https://agent-network-protocol.com/) -- [GitHub](https://github.com/agent-network-protocol/AgentNetworkProtocol) +- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) + +### Анонсы и статьи +- [Google: Announcing A2A](https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/) +- [Google Cloud: A2A Getting an Upgrade](https://cloud.google.com/blog/products/ai-machine-learning/agent2agent-protocol-is-getting-an-upgrade) +- [Linux Foundation: A2A Project Launch](https://www.linuxfoundation.org/press/linux-foundation-launches-the-agent2agent-protocol-project-to-enable-secure-intelligent-communication-between-ai-agents) +- [IBM: What is A2A?](https://www.ibm.com/think/topics/agent2agent-protocol) +- [IBM: What is ACP?](https://www.ibm.com/think/topics/agent-communication-protocol) +- [AWS: Inter-Agent Communication on MCP](https://aws.amazon.com/blogs/opensource/open-protocols-for-agent-interoperability-part-1-inter-agent-communication-on-mcp/) +- [Microsoft: A2A on MCP](https://developer.microsoft.com/blog/can-you-build-agent2agent-communication-on-mcp-yes) +- [Auth0: MCP vs A2A](https://auth0.com/blog/mcp-vs-a2a/) +- [Developer's Guide to AI Agent Protocols](https://developers.googleblog.com/developers-guide-to-ai-agent-protocols/) + +### Claude Code Agent Teams +- [Official Docs](https://code.claude.com/docs/en/agent-teams) +- [Reverse-Engineering Claude Code Agent Teams](https://dev.to/nwyin/reverse-engineering-claude-code-agent-teams-architecture-and-protocol-o49) +- [How They Work Under the Hood](https://www.claudecodecamp.com/p/claude-code-agent-teams-how-they-work-under-the-hood) + +### Cross-Provider Orchestration +- [OpenCode Agent Teams](https://dev.to/uenyioha/porting-claude-codes-agent-teams-to-opencode-4hol) +- [sub-agents-skills](https://github.com/shinpr/sub-agents-skills) +- [ZenFlow Multi-Agent Orchestration](https://docs.zencoder.ai/user-guides/guides/multi-agent-orchestration-in-zenflow) +- [Zed: External Agents](https://zed.dev/docs/ai/external-agents) + +### Agent Coordination +- [MCP Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail) -- [Site](https://mcpagentmail.com/) +- [MCP Agent Mail Rust](https://github.com/Dicklesworthstone/mcp_agent_mail_rust) +- [Inbox/Outbox Pattern](https://earezki.com/ai-news/2026-03-09-the-inbox-outbox-pattern-how-ai-agents-coordinate-without-stepping-on-each-other/) +- [Multi-Agent Communication Patterns](https://dev.to/aureus_c_b3ba7f87cc34d74d49/multi-agent-communication-patterns-that-actually-work-50kp) +- [Agent Message Bus (SQLite)](https://dev.to/linou518/agent-message-bus-communication-infrastructure-for-16-ai-agents-18af) + +### Google ADK +- [ADK with A2A](https://google.github.io/adk-docs/a2a/) +- [ADK Docs](https://google.github.io/adk-docs/agents/models/google-gemini/) + +### Surveys +- [Survey of Agent Interoperability Protocols (arXiv)](https://arxiv.org/abs/2505.02279) +- [Top 5 Open Protocols for Multi-Agent AI Systems](https://onereach.ai/blog/power-of-multi-agent-ai-open-protocols/) +- [10 Modern AI Agent Protocols](https://www.ssonetwork.com/intelligent-automation/columns/ai-agent-protocols-10-modern-standards-shaping-the-agentic-era) diff --git a/docs/research/minimal-adapter-design.md b/docs/research/minimal-adapter-design.md new file mode 100644 index 00000000..774f3736 --- /dev/null +++ b/docs/research/minimal-adapter-design.md @@ -0,0 +1,689 @@ +# Minimal CLI Agent Adapter Design + +**Дата**: 2026-03-25 +**Статус**: Research / Design proposal + +## Цель + +Определить МИНИМАЛЬНО достаточный адаптер для запуска нескольких CLI-агентов (Claude, Codex, Gemini, Goose, OpenCode) из нашего Electron-приложения. Без over-engineering, без "велосипедов". + +--- + +## 1. Что мы уже имеем + +### childProcess.ts (221 LOC) +Уже содержит два ключевых примитива: +- **`spawnCli(binaryPath, args, options)`** — spawn с Windows EINVAL fallback +- **`execCli(binaryPath, args, options)`** — exec для одноразовых команд +- **`killProcessTree(child, signal)`** — kill с Windows taskkill fallback +- **`CLI_ENV_DEFAULTS`** — env-переменные для Claude (CLAUDE_HOOK_JUDGE_MODE) + +### TeamProvisioningService.ts (~8000+ LOC) +Монстр, который делает ВСЁ: +- Spawn через `spawnCli()` +- Конструирование args (`--input-format stream-json`, `--output-format stream-json`, `--mcp-config`, `--verbose`, etc.) +- Парсинг stream-json stdout (newline-delimited JSON) +- Stdin messaging (SDKUserMessage format) +- MCP config merge (через TeamMcpConfigBuilder) +- Filesystem monitoring, stall detection, auth retry, etc. + +### ScheduledTaskExecutor.ts (~200 LOC) +Отдельный, более чистый spawn-path для scheduled tasks: +- Тоже `spawnCli()` + `--output-format stream-json` +- Парсинг stdout для summary extraction +- Простой lifecycle: spawn -> wait -> collect result + +### TeamMcpConfigBuilder.ts (229 LOC) +Генерирует MCP config JSON-файл, мержит с user-серверами из `~/.claude.json`. + +### Общий паттерн spawn (из TeamProvisioningService): +```typescript +const spawnArgs = [ + '--input-format', 'stream-json', + '--output-format', 'stream-json', + '--verbose', + '--setting-sources', 'user,project,local', + '--mcp-config', mcpConfigPath, + '--disallowedTools', 'TeamDelete,TodoWrite', + ...(skipPermissions ? ['--dangerously-skip-permissions'] : []), + ...(model ? ['--model', model] : []), +]; +child = spawnCli(claudePath, spawnArgs, { + cwd, env, stdio: ['pipe', 'pipe', 'pipe'], +}); +// stdin: send JSON messages +child.stdin.write(JSON.stringify({ + type: 'user', + message: { role: 'user', content: [{ type: 'text', text: prompt }] } +}) + '\n'); +``` + +--- + +## 2. Что РЕАЛЬНО отличается между CLI-агентами + +### Сводная таблица (исследование март 2026) + +| Аспект | Claude Code | Codex (OpenAI) | Gemini CLI | Goose (Block) | OpenCode | +|--------|-------------|-----------------|------------|---------------|----------| +| **Binary** | `claude` | `codex` | `gemini` | `goose` | `opencode` | +| **Programmatic mode** | `--input-format stream-json --output-format stream-json` | `codex exec --json` (NDJSON events) | `--output-format json` (headless) | `goose run --output-format stream-json` | `opencode run --format json` | +| **Stdin messaging** | stream-json protocol (SDKUserMessage) | Нет stdin — одноразовый exec | Нет stdin — одноразовый | Нет stdin — одноразовый `run` | Нет stdin — pipe prompt или `--attach` | +| **Output protocol** | NDJSON (type: user/assistant/result/control_request/system) | NDJSON events | JSON (структура неизвестна) | NDJSON (text/json/stream-json) | JSON events | +| **MCP config** | `--mcp-config /path/to/file.json` | `config.toml` (`codex mcp add`) | `settings.json` (`gemini mcp add`) | `--with-extension "cmd"` (runtime) | Config file (opencode.json) | +| **MCP config format** | `{ mcpServers: { name: { command, args } } }` | TOML (встроенная команда `codex mcp`) | JSON settings.json `{ mcpServers: {...} }` | CLI flags per extension | JSON config | +| **Kill semantics** | SIGKILL (team) / SIGTERM (scheduled) | SIGTERM | SIGTERM | SIGTERM | SIGTERM | +| **Keep-alive** | Да (stream-json stdin/stdout loop) | Нет (exec = one-shot) | Нет (headless = one-shot) | Нет (run = one-shot) | Возможно (`--attach` к serve) | +| **Team/multi-agent** | Нативные Agent Teams (TeamCreate, SendMessage) | Нет встроенного | Нет встроенного | Нет встроенного | Subagents через Task tool | +| **Prompt flag** | Stdin (stream-json) или `-p` (one-shot) | `codex exec "prompt"` (positional) | `-p "prompt"` или pipe | `goose run -t "prompt"` или `-i file` | `opencode run "prompt"` (positional) | + +### Источники +- [Codex CLI Reference](https://developers.openai.com/codex/cli/reference) — `codex exec --json`, NDJSON events +- [Codex MCP Docs](https://developers.openai.com/codex/mcp) — config.toml based MCP +- [Gemini CLI MCP Docs](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html) — settings.json, `gemini mcp add` +- [Goose CLI Commands](https://block.github.io/goose/docs/guides/goose-cli-commands/) — `--output-format stream-json`, `--with-extension` +- [Goose --output-format issue #4419](https://github.com/block/goose/issues/4419) — json/stream-json Done +- [OpenCode CLI Docs](https://opencode.ai/docs/cli/) — `run --format json` +- [OpenCode Agents Docs](https://opencode.ai/docs/agents/) — subagents, Task tool + +--- + +## 3. Ключевой вывод: ГДЕ реальная сложность + +### Что тривиально (просто конфиг): +- **Binary name** — строка +- **Prompt flag** — `-p`, `-t`, позиционный arg, или stdin +- **Output format flag** — `--output-format stream-json`, `--json`, `--format json` +- **Model flag** — `--model`, `-m`, `--provider/--model` +- **Permission flags** — `--dangerously-skip-permissions`, `--full-auto`, `--yolo` +- **Kill signal** — SIGKILL vs SIGTERM + +### Что НЕ тривиально (требует адаптера): +1. **Stdin protocol** — ТОЛЬКО Claude имеет persistent stdin loop (stream-json). Все остальные — one-shot (запустил, получил результат, процесс завершился). Это ФУНДАМЕНТАЛЬНОЕ отличие. +2. **Output parsing** — NDJSON формат похож, но структура объектов разная. Claude: `{type: "assistant", message: {...}}`. Codex: свой формат events. Goose: свой. Gemini: свой. +3. **MCP config injection** — Claude: `--mcp-config file.json`. Codex: нужно `codex mcp add` заранее или config.toml. Gemini: нужно `gemini mcp add` или settings.json. Goose: `--with-extension` per runtime. + +### Честная оценка: что из 8000 LOC TeamProvisioningService нужно для других CLI? + +**НЕ нужно** (Claude-specific, 80% кода): +- stream-json stdin messaging loop +- `control_request` protocol (tool approval) +- Teammate spawn tracking (`memberSpawnStatuses`) +- Agent Teams protocol (TeamCreate, SendMessage, TaskCreate) +- Post-compact context recovery +- Cross-team messaging relay +- Lead activity state machine +- Filesystem monitoring для team files (config.json, inboxes/, tasks/) +- Auth retry через respawn + +**Нужно** (общий ~20% skeleton): +- Binary resolution (`ClaudeBinaryResolver` -> обобщённый) +- Shell env resolution (`resolveInteractiveShellEnv`) +- MCP config generation и injection +- Process spawn + stdio pipes +- stdout/stderr collection +- Kill + cleanup +- Timeout/stall detection +- Progress reporting + +--- + +## 4. Три варианта дизайна + +### Option A: Config-driven (одна функция + конфиг) + +**~120 LOC total** (config object + spawnAgent function + output normalizer) + +```typescript +// src/main/utils/agentConfig.ts (~60 LOC) + +export type AgentType = 'claude' | 'codex' | 'gemini' | 'goose' | 'opencode'; + +export type OutputProtocol = 'stream-json' | 'ndjson-events' | 'json-batch'; + +/** How to inject the user prompt into the CLI */ +export type PromptMode = + | { type: 'stdin-stream-json' } // Claude: persistent stdin loop + | { type: 'flag'; flag: string } // -p "prompt", -t "prompt" + | { type: 'positional' } // codex exec "prompt" + | { type: 'stdin-pipe' }; // echo "prompt" | opencode run + +export interface AgentConfig { + /** Binary name (resolved via PATH or explicit path) */ + bin: string; + /** How to pass the prompt */ + promptMode: PromptMode; + /** CLI flags for programmatic output */ + outputArgs: string[]; + /** How stdout should be parsed */ + outputProtocol: OutputProtocol; + /** How to inject MCP servers */ + mcpInjection: + | { type: 'flag'; flag: string; format: 'claude-json' } // --mcp-config file.json + | { type: 'runtime-flag'; flag: string } // --with-extension "cmd" + | { type: 'config-file'; path: string; format: 'toml' | 'json' } // write to config + | { type: 'cli-command'; command: string[] }; // codex mcp add ... + /** Signal to use for killing */ + killSignal: NodeJS.Signals; + /** Extra env vars */ + env?: Record; + /** Whether the process stays alive for multi-turn (only Claude) */ + persistent: boolean; +} + +export const AGENT_CONFIGS: Record = { + claude: { + bin: 'claude', + promptMode: { type: 'stdin-stream-json' }, + outputArgs: ['--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose'], + outputProtocol: 'stream-json', + mcpInjection: { type: 'flag', flag: '--mcp-config', format: 'claude-json' }, + killSignal: 'SIGKILL', + env: { CLAUDE_HOOK_JUDGE_MODE: 'true' }, + persistent: true, + }, + codex: { + bin: 'codex', + promptMode: { type: 'positional' }, + outputArgs: ['exec', '--json'], + outputProtocol: 'ndjson-events', + mcpInjection: { type: 'config-file', path: '~/.codex/config.toml', format: 'toml' }, + killSignal: 'SIGTERM', + persistent: false, + }, + gemini: { + bin: 'gemini', + promptMode: { type: 'flag', flag: '-p' }, + outputArgs: ['--output-format', 'json'], + outputProtocol: 'json-batch', + mcpInjection: { type: 'cli-command', command: ['gemini', 'mcp', 'add'] }, + killSignal: 'SIGTERM', + persistent: false, + }, + goose: { + bin: 'goose', + promptMode: { type: 'flag', flag: '-t' }, + outputArgs: ['run', '--output-format', 'stream-json'], + outputProtocol: 'stream-json', + mcpInjection: { type: 'runtime-flag', flag: '--with-extension' }, + killSignal: 'SIGTERM', + persistent: false, + }, + opencode: { + bin: 'opencode', + promptMode: { type: 'positional' }, + outputArgs: ['run', '--format', 'json'], + outputProtocol: 'json-batch', + mcpInjection: { type: 'config-file', path: '.opencode.json', format: 'json' }, + killSignal: 'SIGTERM', + persistent: false, + }, +}; +``` + +```typescript +// src/main/utils/agentSpawn.ts (~60 LOC) + +import { spawnCli, killProcessTree } from './childProcess'; +import { AGENT_CONFIGS, type AgentType, type AgentConfig } from './agentConfig'; + +export interface AgentSpawnOptions { + type: AgentType; + prompt: string; + cwd: string; + env?: NodeJS.ProcessEnv; + model?: string; + mcpConfigPath?: string; // pre-built MCP config file (for Claude-style --mcp-config) + extraArgs?: string[]; +} + +export interface SpawnedAgent { + child: import('child_process').ChildProcess; + config: AgentConfig; + kill: () => void; + /** Send message (only works for persistent agents like Claude) */ + send?: (text: string) => void; +} + +export function spawnAgent(options: AgentSpawnOptions): SpawnedAgent { + const config = AGENT_CONFIGS[options.type]; + const args: string[] = [...config.outputArgs]; + + // Inject MCP config + if (options.mcpConfigPath && config.mcpInjection.type === 'flag') { + args.push(config.mcpInjection.flag, options.mcpConfigPath); + } + + // Extra args + if (options.extraArgs) { + args.push(...options.extraArgs); + } + + // Inject prompt based on mode + switch (config.promptMode.type) { + case 'flag': + args.push(config.promptMode.flag, options.prompt); + break; + case 'positional': + args.push(options.prompt); + break; + case 'stdin-stream-json': + case 'stdin-pipe': + // Handled after spawn + break; + } + + const child = spawnCli(config.bin, args, { + cwd: options.cwd, + env: { ...(options.env ?? process.env), ...(config.env ?? {}) }, + stdio: config.persistent ? ['pipe', 'pipe', 'pipe'] : ['pipe', 'pipe', 'pipe'], + }); + + // Send prompt via stdin if needed + if (config.promptMode.type === 'stdin-stream-json' && child.stdin?.writable) { + const msg = JSON.stringify({ + type: 'user', + message: { role: 'user', content: [{ type: 'text', text: options.prompt }] }, + }); + child.stdin.write(msg + '\n'); + } else if (config.promptMode.type === 'stdin-pipe' && child.stdin) { + child.stdin.write(options.prompt); + child.stdin.end(); + } + + return { + child, + config, + kill: () => killProcessTree(child, config.killSignal), + send: config.persistent + ? (text: string) => { + if (!child.stdin?.writable) return; + const msg = JSON.stringify({ + type: 'user', + message: { role: 'user', content: [{ type: 'text', text }] }, + }); + child.stdin.write(msg + '\n'); + } + : undefined, + }; +} +``` + +**Плюсы:** +- Минимум кода (~120 LOC в двух файлах) +- Нет классов, нет наследования, нет интерфейсов +- Новый CLI = добавить запись в AGENT_CONFIGS +- Легко тестировать (pure config + one function) +- Не ломает существующий код — TeamProvisioningService может использовать или не использовать + +**Минусы:** +- Output parsing НЕ покрыт (каждый CLI имеет свою структуру NDJSON) +- MCP config injection для Codex/Gemini требует отдельной логики (write to config.toml, run `gemini mcp add`) +- `persistent: true` (Claude) vs one-shot (все остальные) — фундаментально разный lifecycle + +**Надёжность: 7/10** — Покрывает spawn, но не parsing. +**Уверенность: 8/10** — Config-based подход проверен в ScheduledTaskExecutor. + +--- + +### Option B: Thin interface + implementations + +**~200 LOC total** (interface + claude adapter + generic one-shot adapter) + +```typescript +// src/main/adapters/AgentAdapter.ts (~30 LOC) + +import type { ChildProcess } from 'child_process'; + +export interface AgentOutput { + type: 'text' | 'tool_use' | 'tool_result' | 'thinking' | 'result' | 'error' | 'raw'; + content: string; + raw?: unknown; +} + +export interface AgentAdapter { + readonly agentType: string; + readonly persistent: boolean; + + /** Build CLI args for spawning */ + buildArgs(prompt: string, options: { model?: string; mcpConfigPath?: string; extraArgs?: string[] }): string[]; + + /** Parse a single line/chunk of stdout into normalized output */ + parseOutput(line: string): AgentOutput | null; + + /** Send a follow-up message (only for persistent agents) */ + sendMessage?(child: ChildProcess, text: string): void; + + /** Which signal to use for kill */ + killSignal: NodeJS.Signals; +} +``` + +```typescript +// src/main/adapters/ClaudeAdapter.ts (~60 LOC) +export class ClaudeAdapter implements AgentAdapter { + readonly agentType = 'claude'; + readonly persistent = true; + readonly killSignal = 'SIGKILL' as const; + + buildArgs(prompt: string, options) { + const args = [ + '--input-format', 'stream-json', + '--output-format', 'stream-json', + '--verbose', + ]; + if (options.mcpConfigPath) args.push('--mcp-config', options.mcpConfigPath); + if (options.model) args.push('--model', options.model); + args.push(...(options.extraArgs ?? [])); + return args; + // prompt sent via sendMessage(), not in args + } + + parseOutput(line: string): AgentOutput | null { + try { + const obj = JSON.parse(line); + if (obj.type === 'assistant') return { type: 'text', content: /* extract */, raw: obj }; + if (obj.type === 'result') return { type: 'result', content: obj.result?.text ?? '', raw: obj }; + return { type: 'raw', content: line, raw: obj }; + } catch { return null; } + } + + sendMessage(child: ChildProcess, text: string) { + if (!child.stdin?.writable) return; + child.stdin.write(JSON.stringify({ + type: 'user', + message: { role: 'user', content: [{ type: 'text', text }] }, + }) + '\n'); + } +} +``` + +```typescript +// src/main/adapters/OneShotAdapter.ts (~80 LOC) +// Generic one-shot adapter configurable for Codex, Goose, Gemini, OpenCode + +export interface OneShotConfig { + agentType: string; + subcommand?: string; // 'exec', 'run', etc. + outputFlag: string[]; // ['--json'], ['--output-format', 'stream-json'], etc. + promptFlag?: string; // '-p', '-t', or undefined for positional + mcpFlag?: string; // '--with-extension' for goose + killSignal?: NodeJS.Signals; +} + +export class OneShotAdapter implements AgentAdapter { + readonly persistent = false; + readonly agentType: string; + readonly killSignal: NodeJS.Signals; + private config: OneShotConfig; + + constructor(config: OneShotConfig) { + this.config = config; + this.agentType = config.agentType; + this.killSignal = config.killSignal ?? 'SIGTERM'; + } + + buildArgs(prompt: string, options) { + const args: string[] = []; + if (this.config.subcommand) args.push(this.config.subcommand); + args.push(...this.config.outputFlag); + if (options.mcpConfigPath && this.config.mcpFlag) { + args.push(this.config.mcpFlag, options.mcpConfigPath); + } + args.push(...(options.extraArgs ?? [])); + if (this.config.promptFlag) { + args.push(this.config.promptFlag, prompt); + } else { + args.push(prompt); // positional + } + return args; + } + + parseOutput(line: string): AgentOutput | null { + try { + const obj = JSON.parse(line); + return { type: 'raw', content: line, raw: obj }; + } catch { return null; } + } +} + +// Pre-built instances: +export const codexAdapter = new OneShotAdapter({ + agentType: 'codex', subcommand: 'exec', outputFlag: ['--json'], killSignal: 'SIGTERM', +}); +export const gooseAdapter = new OneShotAdapter({ + agentType: 'goose', subcommand: 'run', outputFlag: ['--output-format', 'stream-json'], + promptFlag: '-t', mcpFlag: '--with-extension', +}); +export const geminiAdapter = new OneShotAdapter({ + agentType: 'gemini', outputFlag: ['--output-format', 'json'], promptFlag: '-p', +}); +export const opencodeAdapter = new OneShotAdapter({ + agentType: 'opencode', subcommand: 'run', outputFlag: ['--format', 'json'], +}); +``` + +**Плюсы:** +- `parseOutput()` даёт место для нормализации вывода каждого CLI +- Чёткое разделение: Claude (persistent) vs all others (one-shot) +- `OneShotAdapter` — generic, покрывает 4 из 5 CLI одним классом +- Новый CLI = `new OneShotAdapter({ ... })` (одна строка) + +**Минусы:** +- Интерфейс + 2 класса — чуть больше "архитектуры" чем нужно прямо сейчас +- `parseOutput()` для не-Claude CLI будет пустышкой (return raw) пока не изучим их NDJSON формат +- Всё ещё не решает MCP injection для Codex (config.toml) и Gemini (settings.json) + +**Надёжность: 8/10** — Хороший баланс между простотой и расширяемостью. +**Уверенность: 7/10** — Interface-based подход стандартен, но `parseOutput` рискует стать "мёртвым кодом" на начальном этапе. + +--- + +### Option C: Расширить childProcess.ts (минимальные изменения) **(Recommended)** + +**~50 LOC additions** к существующему файлу + **~30 LOC** отдельный config + +```typescript +// Добавить в src/main/utils/childProcess.ts (~25 LOC) + +export type AgentType = 'claude' | 'codex' | 'gemini' | 'goose' | 'opencode'; + +export interface AgentSpawnResult { + child: ChildProcess; + send?: (text: string) => void; + kill: () => void; +} + +/** + * Spawn any supported CLI agent. Thin wrapper over spawnCli that + * handles binary name, output-format flags, and prompt injection. + */ +export function spawnAgent( + type: AgentType, + binaryPath: string, + prompt: string, + options: SpawnOptions & { mcpConfigPath?: string; extraArgs?: string[] } = {} +): AgentSpawnResult { + const cfg = AGENT_SPAWN_CONFIGS[type]; + const args = [...cfg.baseArgs]; + if (options.mcpConfigPath && cfg.mcpFlag) { + args.push(cfg.mcpFlag, options.mcpConfigPath); + } + if (options.extraArgs) args.push(...options.extraArgs); + if (cfg.promptFlag) args.push(cfg.promptFlag, prompt); + else if (!cfg.stdinPrompt) args.push(prompt); + + const child = spawnCli(binaryPath, args, { + ...options, + env: { ...(options.env ?? process.env), ...(cfg.env ?? {}) }, + stdio: ['pipe', 'pipe', 'pipe'], + }); + + // Inject prompt via stdin if needed + if (cfg.stdinPrompt && child.stdin?.writable) { + const msg = cfg.stdinPrompt === 'stream-json' + ? JSON.stringify({ type: 'user', message: { role: 'user', content: [{ type: 'text', text: prompt }] } }) + '\n' + : prompt; + child.stdin.write(msg); + if (cfg.stdinPrompt === 'pipe') child.stdin.end(); + } + + return { + child, + send: cfg.stdinPrompt === 'stream-json' + ? (text: string) => { + if (!child.stdin?.writable) return; + child.stdin.write(JSON.stringify({ + type: 'user', + message: { role: 'user', content: [{ type: 'text', text }] }, + }) + '\n'); + } + : undefined, + kill: () => killProcessTree(child, cfg.killSignal), + }; +} +``` + +```typescript +// src/main/utils/agentConfigs.ts (~30 LOC) + +interface AgentSpawnConfig { + baseArgs: string[]; + promptFlag?: string; // undefined = positional arg + stdinPrompt?: 'stream-json' | 'pipe'; + mcpFlag?: string; + killSignal: NodeJS.Signals; + env?: Record; +} + +export const AGENT_SPAWN_CONFIGS: Record = { + claude: { + baseArgs: ['--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose'], + stdinPrompt: 'stream-json', + mcpFlag: '--mcp-config', + killSignal: 'SIGKILL', + env: { CLAUDE_HOOK_JUDGE_MODE: 'true' }, + }, + codex: { + baseArgs: ['exec', '--json'], + killSignal: 'SIGTERM', + }, + gemini: { + baseArgs: ['--output-format', 'json'], + promptFlag: '-p', + killSignal: 'SIGTERM', + }, + goose: { + baseArgs: ['run', '--output-format', 'stream-json'], + promptFlag: '-t', + mcpFlag: '--with-extension', + killSignal: 'SIGTERM', + }, + opencode: { + baseArgs: ['run', '--format', 'json'], + killSignal: 'SIGTERM', + }, +}; +``` + +**Плюсы:** +- Абсолютный минимум нового кода (~55 LOC) +- Не создаёт новую абстракцию — расширяет существующую +- TeamProvisioningService может постепенно мигрировать (или нет) +- Новый CLI = 5 строк в конфиге +- Binary resolution остаётся на вызывающей стороне (как сейчас с ClaudeBinaryResolver) +- Output parsing — ответственность вызывающего кода (не навязываем) + +**Минусы:** +- Не покрывает output parsing (сознательно) +- Не покрывает MCP config injection для Codex/Gemini +- childProcess.ts станет чуть толще (~275 LOC вместо 221) +- Нет типизации вывода (каждый consumer парсит сам) + +**Надёжность: 7/10** — Минимально, но достаточно для spawn. +**Уверенность: 9/10** — Расширение существующего утилитного файла — самый безопасный путь. + +--- + +## 5. Сравнительная таблица + +| Критерий | Option A (config+fn) | Option B (interface) | Option C (extend existing) | +|----------|---------------------|---------------------|---------------------------| +| **LOC** | ~120 | ~200 | ~55 | +| **Новых файлов** | 2 | 3 | 1 | +| **Output parsing** | Нет | Да (заглушка) | Нет | +| **MCP injection** | Описано, не реализовано | Описано, не реализовано | Описано, не реализовано | +| **Расширяемость** | Хорошая (конфиг) | Отличная (интерфейс) | Хорошая (конфиг) | +| **Breaks existing?** | Нет | Нет | Нет | +| **Time to implement** | 1 час | 2 часа | 30 мин | +| **"Велосипед"?** | Нет, это конфиг | Нет, но чуть преждевременно | Нет, это 55 строк клея | + +--- + +## 6. Рекомендация + +### Начать с Option C (extend childProcess.ts), при необходимости вырастить в Option A + +**Почему:** + +1. **55 LOC — это не велосипед.** Это минимальный config-driven dispatcher. Любой проект, интегрирующий несколько CLI, пишет ровно это. Нет смысла тянуть зависимость ради 55 строк. + +2. **Output parsing — отдельная задача.** Парсинг NDJSON от Codex/Gemini/Goose — это ~50-100 LOC на каждый CLI, и его не нужно решать сейчас. Когда понадобится — это будет Option B (interface с `parseOutput()`), но не раньше. + +3. **MCP injection — тоже отдельная задача.** Для Claude у нас уже есть TeamMcpConfigBuilder. Для Goose — это просто `--with-extension`. Для Codex/Gemini — нужно писать в их config files. Это 3 отдельных утилиты, не общий адаптер. + +4. **Persistent vs one-shot — фундаментально разный lifecycle.** Claude (stream-json loop) живёт долго и получает новые сообщения. Все остальные — fire-and-forget. Эту разницу нельзя "спрятать" за единым интерфейсом без того чтобы интерфейс не стал дырявой абстракцией. + +### Эволюционный путь: + +``` +Этап 1 (сейчас): Option C — spawnAgent() в childProcess.ts + agentConfigs.ts + 55 LOC, покрывает spawn для всех 5 CLI + +Этап 2 (когда добавим 2-й CLI): Вынести в отдельный файл если childProcess.ts станет перегруженным + Может стать Option A (~120 LOC) + +Этап 3 (когда нужен output parsing): Добавить parseOutput() per agent + Может стать Option B (~200 LOC) +``` + +--- + +## 7. Честный ответ: "велосипед" или нет? + +**Нет, это НЕ велосипед.** Вот почему: + +1. **Нет готовой библиотеки.** Не существует npm-пакета "universal-cli-agent-spawner". Каждый из этих CLI — молодой продукт (2025-2026), с собственным протоколом. Никто ещё не написал унификатор. + +2. **55-200 LOC клея — это норма.** Для сравнения: + - Docker SDK для Node.js: ~300 LOC для spawn docker CLI + - Terraform CDK: ~200 LOC для spawn terraform binary + - VS Code extensions: ~150 LOC для spawn language server + +3. **Наш существующий spawnCli() — уже 65 LOC** клея для одного Claude CLI. Расширить его до 5 CLI за +55 LOC — это линейное масштабирование, не экспоненциальное. + +4. **Реальный "велосипед" начался бы** если бы мы писали: + - Свой MCP client (~500+ LOC) + - Свой NDJSON parser с backpressure (~200 LOC) + - Свой process supervisor с restart policies (~400 LOC) + - Свой auth token manager per CLI (~300 LOC) + + Мы этого НЕ делаем. Мы пишем config map + одну функцию. + +5. **Большую часть сложности (8000 LOC TeamProvisioningService) мы уже написали** для Claude — и она Claude-specific. Адаптер для других CLI будет использовать ~5% от этого кода. + +--- + +## 8. Что НЕ включать в адаптер + +Явно НЕ входит в scope минимального адаптера: +- Output parsing/normalization (отдельный слой) +- Team protocol (Agent Teams — Claude-only) +- MCP config generation (отдельный builder per CLI) +- Binary auto-discovery/installation (отдельный resolver per CLI) +- Auth management (каждый CLI сам) +- Session persistence (каждый CLI сам) +- Stall/timeout detection (caller responsibility) +- Progress reporting (caller responsibility) + +Это всё валидная функциональность, но она живёт ВЫШЕ адаптера, в orchestration layer (TeamProvisioningService или его аналог). diff --git a/docs/research/multi-agent-communication-tools.md b/docs/research/multi-agent-communication-tools.md new file mode 100644 index 00000000..cae9ded5 --- /dev/null +++ b/docs/research/multi-agent-communication-tools.md @@ -0,0 +1,542 @@ +# Multi-Agent CLI Orchestrators with Inter-Agent Communication + +> Research date: 2026-03-25 +> Focus: tools where Agent A (Claude) can send a message to Agent B (Codex/Gemini), NOT just "fan-out same task to multiple agents" + +## TL;DR + +Ни один инструмент не является зрелым "фундаментом" для замены нашего стека. Все проекты в этом пространстве молоды (< 6 месяцев), быстро меняют API, и ни один не имеет production-grade inter-agent communication для РАЗНЫХ провайдеров CLI-агентов уровня, который мы уже реализовали для Claude Code Agent Teams. + +**Лидеры по inter-agent communication:** + +| Tool | Stars | Inter-Agent Msg | Multi-Provider | Kanban | Наша оценка | +|------|-------|----------------|----------------|--------|------------| +| Ruflo | 25,709 | SQLite + JSON | Claude + Codex | Нет | Hype-driven, раздутые цифры | +| Composio AO | 5,390 | CI feedback routing | Claude, Codex, Aider | Нет | Planner-executor, не P2P | +| Claude Octopus | 2,069 | Consensus gate 75% | 8 providers | Нет | Plugin, не orchestrator | +| mcp_agent_mail | 1,842 | MCP + SQLite inbox | Any MCP client | Нет | Протокол, не UI | +| claude_code_bridge | 1,855 | Real-time collab | Claude, Codex, Gemini | Нет | Terminal split-pane | +| Overstory | 1,123 | SQLite mail (WAL) | 11 runtimes | Нет | Closest to real P2P | +| agtx | 693 | Session switching | Claude, Codex, Gemini, OpenCode, Cursor | Kanban-like | Autonomous, но молодой | +| AI Maestro | 556 | AMP protocol | Claude, Codex, any | Kanban! | Multi-machine, но TypeScript mesh | +| parallel-code | 407 | Нет (изоляция) | Claude, Codex, Gemini | Diff viewer | Параллельное, не collaborative | +| CAO (AWS) | 344 | SQLite inbox + MCP | Q CLI, Claude, Codex | Нет | AWS-backed, но ранняя стадия | +| MCO | 249 | Fan-out, не P2P | 5 CLIs | Нет | Dispatch layer, не messaging | +| hcom | 164 | File-based hooks | Claude, Codex, Gemini, OpenCode | Нет | Lightweight, hooks-only | +| MetaSwarm | 148 | Skills-based | Claude, Gemini, Codex | Нет | Self-improving framework | +| CAS | 69 | Через MCP server | Claude Code only | Нет | Claude-only, раннее | +| kodo | 46 | Verification cycle | Claude, Codex, Gemini | Нет | SWE-bench verified | + +--- + +## 1. CAS (Coding Agent System) + +- **Repo:** https://github.com/codingagentsystem/cas +- **Stars:** 69 +- **Language:** Rust +- **License:** MIT +- **Created:** 2026-01-05 + +### Что это +Supervisor + Workers модель для Claude Code. Factory mode оркестрирует несколько Claude Code инстансов в параллельных git worktree. MCP server дает агентам persistent memory, task tracking, rules, skills через SQLite + FTS. + +### Inter-Agent Communication +- Нет прямого inter-agent messaging между агентами +- Communication идет через supervisor (hub-and-spoke) +- Workers не общаются друг с другом напрямую +- Coordinator раздает задачи, workers возвращают результаты + +### Multi-Provider Support +- **ТОЛЬКО Claude Code** — нет поддержки Codex, Gemini, Goose и др. + +### Вердикт +Не подходит как фундамент. Claude-only, маленькое коммьюнити (69 stars), нет inter-agent messaging, нет multi-provider. Persistent memory через MCP server — интересная идея, но не уникальная. + +--- + +## 2. AWS CLI Agent Orchestrator (CAO) + +- **Repo:** https://github.com/awslabs/cli-agent-orchestrator +- **Stars:** 344 +- **Language:** Python +- **License:** Apache 2.0 (AWS) +- **Created:** 2025-07-29 + +### Что это +Иерархическая система оркестрации CLI AI агентов от AWS Labs. Три паттерна: Handoff (синхронный transfer), Assign (async spawn), Send Message (прямая коммуникация). + +### Inter-Agent Communication +- **Send Message** — прямые сообщения между существующими агентами +- **SQLite inbox system** — асинхронная доставка сообщений с FIFO ordering +- **File-watching** — определяет когда terminal idle и доставляет pending messages +- **MCP tools** — `handoff`, `assign`, `send_message` для координации +- **REST API** — cao-server на `localhost:9889` + +### Multi-Provider Support +- Amazon Q CLI, Claude Code, Codex CLI (через провайдер с API key) +- Каждый агент в изолированной tmux сессии + +### Что хорошо +- AWS-backed = стабильная поддержка +- Реальный inter-agent messaging через SQLite inbox +- Profile-based agent isolation +- Cron-like scheduled runs + +### Что плохо +- 344 stars — ранняя стадия +- Зависимость на tmux +- Python-based (не наш стек) +- Нет UI/dashboard + +### Вердикт +Наиболее продуманный подход к inter-agent messaging через SQLite inbox. Но ранняя стадия, нет UI, Python-only. Send Message паттерн — это то, что нам нужно, но реализация привязана к tmux sessions. + +--- + +## 3. Overstory + +- **Repo:** https://github.com/jayminwest/overstory +- **Stars:** 1,123 +- **Language:** TypeScript (Bun) +- **License:** MIT +- **Created:** 2026-02-12 + +### Что это +Превращает coding session в multi-agent team. Workers в git worktree через tmux. SQLite mail system для координации. FIFO merge queue с 4-tier conflict resolution. + +### Inter-Agent Communication +- **SQLite mail system** (WAL mode, ~1-5ms/query) — ключевая фича +- **8 typed protocol messages:** `worker_done`, `merge_ready`, `merged`, `merge_failed`, `escalation`, `health_check`, `dispatch`, `assign` +- **Type-safe API:** `sendProtocol()` и `parsePayload()` +- **Broadcast:** группы `@all`, `@builders` и др. +- **`overstory mail`** CLI: send/check/list/read/reply + +### Multi-Provider Support +- **11 runtime adapters:** Claude Code, Pi, Gemini CLI, Aider, Goose, Amp и др. +- Pluggable `AgentRuntime` interface + +### Что хорошо +- Самый развитый SQLite mail system среди всех инструментов +- Type-safe protocol messages — близко к нашему подходу с inbox files +- 11 runtime adapters — реальная мультипровайдерность +- TypeScript/Bun — совместимый стек + +### Что плохо +- Зависимость на tmux + Bun (не Node/Electron) +- "Compounding error rates, cost amplification, debugging complexity" — сами предупреждают +- Нет UI — всё CLI +- 1,123 stars за 1.5 месяца — быстрый рост, но незрелый + +### Вердикт +Ближайший по архитектуре к нашему подходу (SQLite mail ~ наш inbox system). Протокольные сообщения с типами, broadcast — всё это у нас уже есть. Мог бы быть полезен как reference для protocol design, но не как фундамент. + +--- + +## 4. Composio Agent Orchestrator + +- **Repo:** https://github.com/ComposioHQ/agent-orchestrator +- **Stars:** 5,390 +- **Language:** TypeScript +- **License:** MIT +- **Created:** 2026-02-13 + +### Что это +Planner-Executor модель для fleet of parallel coding agents. Orchestrator — сам AI agent который читает codebase, decompose features, мониторит progress. Plugin system с 8 swappable slots. + +### Inter-Agent Communication +- **НЕ peer-to-peer messaging** — orchestrator agent роутит feedback +- CI failures → injection back в agent session +- Review comments → routing в правильный agent с контекстом +- Self-improvement loop: logs → retrospectives → adjustments + +### Multi-Provider Support +- Claude Code, Codex, Aider +- Runtime-agnostic: tmux, Docker +- Tracker-agnostic: GitHub, Linear + +### Что хорошо +- 5,390 stars — самый популярный в категории +- TypeScript — наш стек +- Self-improvement system — уникальная фича +- Plugin architecture — гибко + +### Что плохо +- Нет P2P inter-agent messaging — всё через orchestrator +- Agent A не может напрямую послать сообщение Agent B +- Orchestrator = single point of failure +- 1.5 месяца от creation — очень молодой + +### Вердикт +Самый popular, но inter-agent communication = feedback routing через orchestrator, а не direct messaging. Это принципиально другой паттерн, чем наш. Полезен как reference для planner-executor, но не для P2P communication. + +--- + +## 5. hcom (Hook-Comms) + +- **Repo:** https://github.com/aannoo/hcom +- **Stars:** 164 +- **Language:** Rust +- **Created:** 2025-07-21 + +### Что это +Lightweight CLI для inter-agent messaging через hooks. Agents могут message, watch, spawn друг друга across terminals. + +### Inter-Agent Communication +- **`send`** — отправка сообщений между agents +- **`listen`** — блокирующее ожидание с фильтрами (agent, type, status, sender, intent) +- **`events`** — event stream с подписками +- **`bundle`** — structured context packages для handoffs +- **`transcript`** — чтение conversation другого агента +- **TUI dashboard** для мониторинга + +### Multi-Provider Support +- Claude Code, Gemini CLI, Codex, OpenCode +- Hooks integration для Gemini CLI + +### Что хорошо +- Минимальный, специализированный tool для inter-agent messaging +- Работает с любым CLI agent через hooks +- `listen` с фильтрами — мощный примитив + +### Что плохо +- 164 stars — маленькое коммьюнити +- Rust — другой стек +- Нет task management, нет orchestration — только messaging +- Зависимость на hooks mechanism + +### Вердикт +Интересный lightweight подход к messaging, но это only messaging layer без orchestration. Можно изучить как reference для protocol design, но не как фундамент. + +--- + +## 6. AI Maestro + +- **Repo:** https://github.com/23blocks-OS/ai-maestro +- **Stars:** 556 +- **Language:** TypeScript +- **License:** MIT +- **Created:** 2025-10-10 + +### Что это +Dashboard для управления агентами across multiple machines. Agent Messaging Protocol (AMP). Skills system. Code Graph. Memory. + +### Inter-Agent Communication +- **Agent Messaging Protocol (AMP)** — email-like communication + - Priority levels, message types, cryptographic signatures, push notifications + - Отдельный open-source протокол: https://github.com/agentmessaging/protocol +- **Peer mesh network** — multi-machine без central server +- **External gateways:** Slack, Discord, Email, WhatsApp + +### Multi-Provider Support +- Claude Code, Aider, Cursor, Copilot, OpenCode, Codex CLI, Gemini CLI +- 30+ compatible agents через Skills + +### Kanban Board +- **ДА!** Полный Kanban с drag-and-drop, dependencies, 5 status columns +- Teams + War Rooms + +### Что хорошо +- **Kanban board** — единственный конкурент с Kanban! +- AMP protocol — formalized inter-agent messaging +- Multi-machine support — уникально +- TypeScript — наш стек +- External messaging gateways + +### Что плохо +- 556 stars — умеренная популярность +- AMP protocol ещё развивается +- tmux dependency +- "80+ agents across multiple computers" — выглядит как over-engineering + +### Вердикт +**Самый близкий конкурент** по feature set: Kanban + inter-agent messaging + multi-provider + TypeScript. AMP protocol — интересный formalized подход. Стоит внимательно изучить. Однако peer mesh network и multi-machine — это другой масштаб, чем наш local-first подход. + +--- + +## 7. ORCH + +- **Website:** https://www.orch.one/ +- **Stars:** N/A (repo не найден / приватный на момент исследования) +- **License:** MIT + +### Что это +CLI runtime для управления Claude Code, Codex, Cursor как typed agent teams. State machine, event bus, TUI. + +### Inter-Agent Communication +- **Typed event bus** — 31 event type, agents emit events, orchestrator reacts +- **Inter-agent messaging** — direct messages, broadcasts, injected в prompts +- **Agent Teams** — group agents under lead, broadcast context +- **State machine:** todo -> in_progress -> review -> done + +### Multi-Provider Support +- 5 adapters: Claude, OpenCode (Gemini, DeepSeek via OpenRouter), Codex, Cursor, Shell + +### Что хорошо +- Event bus architecture — decoupled communication +- State machine — production-quality +- 5 adapters из коробки +- Headless daemon mode (`orch serve`) + +### Что плохо +- GitHub repo не найден или приватный — нельзя оценить реальный код +- Event bus = centralized, не P2P +- Нет UI кроме TUI + +### Вердикт +Архитектурно интересный (event bus + state machine), но невозможно оценить зрелость кода без доступа к repo. Event bus — это скорее pub/sub, чем direct messaging. + +--- + +## 8. Ruflo + +- **Repo:** https://github.com/ruvnet/ruflo +- **Stars:** 25,709 +- **Language:** TypeScript +- **License:** MIT +- **Created:** 2025-06-02 + +### Что это +"The leading agent orchestration platform for Claude." Multi-agent swarms, autonomous workflows, RAG integration. Ранее Claude-Flow. + +### Inter-Agent Communication +- SQLite для memory persistence +- JSON-based coordination protocols для inter-agent messaging +- Compaction lifecycle → archive context to SQLite + +### Multi-Provider Support +- Claude Code + Codex integration + +### Что хорошо +- 25K stars — самый популярный в нише +- Comprehensive feature set + +### Что плохо +- 25K stars за < 10 месяцев — подозрительно (возможен бот-boost) +- "v3 introduces self-learning neural capabilities" — marketing buzzwords +- Сравнения с конкурентами в README — red flag +- Claude-centric, minimal real multi-provider + +### Вердикт +Hype-driven проект с подозрительно высокими stars. Inter-agent communication через SQLite + JSON — базовый уровень. Не стоит использовать как фундамент из-за quality concerns. + +--- + +## 9. MCO (Multi-CLI Orchestrator) + +- **Repo:** https://github.com/mco-org/mco +- **Stars:** 249 +- **Language:** Python +- **Created:** 2026-02-26 + +### Что это +Neutral dispatch layer. Отправляет prompts на несколько CLI agents параллельно, агрегирует результаты. + +### Inter-Agent Communication +- **НЕТ real inter-agent messaging** +- Fan-out same prompt → collect results → aggregate +- Structured code review с findings schema + +### Multi-Provider Support +- Claude Code, Codex CLI, Gemini CLI, OpenCode, Qwen Code + +### Вердикт +Dispatch/aggregation, не collaboration. Agent A не знает о Agent B. Полезен для multi-perspective review, но это не inter-agent communication. + +--- + +## 10. mcp_agent_mail + +- **Repo:** https://github.com/Dicklesworthstone/mcp_agent_mail +- **Stars:** 1,842 +- **Language:** Python +- **Created:** 2025-10-23 + +### Что это +Mail-like coordination layer для coding agents. FastMCP server + Git + SQLite. + +### Inter-Agent Communication +- **Inbox/outbox** per agent +- **Searchable message history** +- **File lease system** — voluntary file reservation +- **Memorable identities** для agents +- HTTP-only FastMCP server + +### Multi-Provider Support +- Any MCP-compatible client + +### Что хорошо +- 1,842 stars — солидное коммьюнити +- Clean abstraction: mail metaphor для agent communication +- File leases — unique feature для conflict prevention + +### Что плохо +- Python + FastMCP — другой стек +- Только communication layer, не orchestrator +- Нет task management, нет UI + +### Вердикт +Лучший standalone inter-agent communication protocol. File leases — интересная идея для нас. Но это protocol library, не ready-to-use tool. + +--- + +## 11. agtx + +- **Repo:** https://github.com/fynnfluegge/agtx +- **Stars:** 693 +- **Language:** Rust +- **Created:** 2026-02-08 + +### Что это +Multi-session AI coding terminal manager. Autonomous orchestration с spec-driven workflow. + +### Inter-Agent Communication +- Session switching с context awareness +- Gemini -> research | Claude -> implement | Codex -> review +- Kanban board в TUI + +### Multi-Provider Support +- Claude, Codex, Gemini, OpenCode, Cursor + +### Вердикт +Autonomous orchestration с role-based agent dispatch. Kanban-like TUI. Но Rust стек и нет rich inter-agent messaging. + +--- + +## 12. claude_code_bridge (ccb) + +- **Repo:** https://github.com/bfly123/claude_code_bridge +- **Stars:** 1,855 +- **Language:** Python +- **Created:** 2025-10-25 + +### Что это +Real-time multi-AI collaboration. Split-pane terminal. Persistent context. + +### Inter-Agent Communication +- Real-time collaboration между Claude, Codex, Gemini +- Persistent context sharing +- WYSIWYG split-pane terminal + +### Вердикт +Terminal-based collaboration, не programmatic API. Интересен как UX reference, но не как foundation. + +--- + +## 13. Claude Octopus + +- **Repo:** https://github.com/nyldn/claude-octopus +- **Stars:** 2,069 +- **Language:** Shell +- **Created:** 2026-01-15 + +### Что это +Multi-LLM orchestration plugin для Claude Code. 8 providers, consensus gates. + +### Inter-Agent Communication +- 75% consensus gate — providers должны согласиться +- Parallel (research), sequential (problem scoping), adversarial (review) modes + +### Multi-Provider Support +- Codex, Gemini, Claude, Perplexity, OpenRouter, Copilot, Qwen, Ollama + +### Вердикт +Plugin для Claude Code, не standalone orchestrator. Consensus mechanism — интересно, но это не direct messaging. + +--- + +## Сравнительная таблица: типы Inter-Agent Communication + +| Pattern | Tools | Описание | +|---------|-------|----------| +| **SQLite Inbox/Mail** | CAO, Overstory, mcp_agent_mail | Асинхронная доставка через SQLite, FIFO, typed messages | +| **Event Bus** | ORCH | Typed events, pub/sub, decoupled | +| **AMP Protocol** | AI Maestro | Email-like, priorities, crypto signatures, mesh network | +| **Hooks/File-based** | hcom | File watches + hooks для inter-terminal messaging | +| **Orchestrator Routing** | Composio AO | Central agent роутит feedback, не P2P | +| **Fan-out/Aggregate** | MCO, Claude Octopus | Dispatch same task, collect results — не communication | +| **Session Switching** | agtx, ccb | Context handoff между sessions — implicit communication | + +--- + +## Ключевые выводы + +### 1. Kanban есть ТОЛЬКО у AI Maestro +Из всех исследованных инструментов, только AI Maestro (556 stars) имеет полноценный Kanban board с drag-and-drop. Это подтверждает нашу уникальность. Также agtx имеет kanban-like TUI, но без GUI. + +### 2. Реальный P2P inter-agent messaging — редкость +Большинство инструментов используют hub-and-spoke (orchestrator в центре). Реальный P2P: +- **Overstory** — SQLite mail с typed protocol +- **CAO** — SQLite inbox + Send Message +- **AI Maestro** — AMP protocol + mesh +- **hcom** — hooks-based messaging +- **mcp_agent_mail** — MCP inbox/outbox + +### 3. Ни один инструмент не является зрелым фундаментом +- Все проекты < 6 месяцев (кроме Ruflo и CAO) +- API быстро меняются +- Большинство зависят на tmux +- Нет production-grade error handling + +### 4. Наш подход (Claude Code Agent Teams + Electron UI) остается уникальным +- **Inbox-based messaging** через файлы — мы уже реализовали +- **Kanban board** — мы единственные с полноценным GUI +- **Electron app** — никто больше не делает desktop app для agent orchestration (кроме parallel-code) +- **Team lifecycle management** — наш уровень detail (config.json, session management, DM) не имеет аналогов + +### 5. Что стоит изучить/заимствовать + +| Идея | Источник | Применимость для нас | +|------|----------|---------------------| +| SQLite mail protocol messages (8 types) | Overstory | Можно формализовать наши inbox message types | +| File leases для conflict prevention | mcp_agent_mail | Полезно для multi-agent file editing | +| AMP protocol (priorities, signatures) | AI Maestro | Можно добавить priorities в наш inbox | +| Event bus architecture | ORCH | Для decoupled communication в Electron | +| Self-improvement loop | Composio AO | Agent learning from past sessions | +| Consensus gates | Claude Octopus | Multi-provider code review | +| Pluggable AgentRuntime interface | Overstory | Для будущей multi-provider поддержки | + +--- + +## Рекомендация + +**НЕ использовать ни один из этих инструментов как фундамент.** Причины: + +1. **Наш стек уникален** (Electron + React + TypeScript + Zustand) — ни один tool не совместим +2. **Наша архитектура inbox messaging уже работает** и протестирована +3. **Kanban board** — наше ключевое преимущество, которого нет у конкурентов +4. **Зрелость кода** у всех инструментов низкая (< 6 месяцев) +5. **Dependency risk** — tmux, Bun, Python, Rust — чужой стек + +**Что имеет смысл:** +- Изучить **Overstory** как reference для typed protocol messages +- Изучить **mcp_agent_mail** для file lease механизма +- Изучить **AI Maestro** как ближайшего конкурента (Kanban + AMP) +- Следить за **CAO (AWS)** — AWS backing значит долгосрочную поддержку +- Рассмотреть **AgentRuntime interface** из Overstory для будущей multi-provider поддержки + +--- + +## Источники + +- [CAS - codingagentsystem/cas](https://github.com/codingagentsystem/cas) +- [CAS Website](https://cas.dev/) +- [AWS CLI Agent Orchestrator](https://github.com/awslabs/cli-agent-orchestrator) +- [AWS Blog - Introducing CAO](https://aws.amazon.com/blogs/opensource/introducing-cli-agent-orchestrator-transforming-developer-cli-tools-into-a-multi-agent-powerhouse/) +- [CAO Message Queueing - DeepWiki](https://deepwiki.com/awslabs/cli-agent-orchestrator/3.4-message-queueing-and-inbox-system) +- [Overstory](https://github.com/jayminwest/overstory) +- [Composio Agent Orchestrator](https://github.com/ComposioHQ/agent-orchestrator) +- [hcom](https://github.com/aannoo/hcom) +- [AI Maestro](https://github.com/23blocks-OS/ai-maestro) +- [AMP Protocol](https://github.com/agentmessaging/protocol) +- [ORCH](https://www.orch.one/) +- [MCO](https://github.com/mco-org/mco) +- [Ruflo](https://github.com/ruvnet/ruflo) +- [mcp_agent_mail](https://github.com/Dicklesworthstone/mcp_agent_mail) +- [agtx](https://github.com/fynnfluegge/agtx) +- [claude_code_bridge](https://github.com/bfly123/claude_code_bridge) +- [Claude Octopus](https://github.com/nyldn/claude-octopus) +- [parallel-code](https://github.com/johannesjo/parallel-code) +- [MetaSwarm](https://github.com/dsifry/metaswarm) +- [kodo](https://github.com/ikamensh/kodo) +- [Awesome Agent Orchestrators](https://github.com/andyrewlee/awesome-agent-orchestrators) +- [Zed Editor - External Agents / ACP](https://zed.dev/docs/ai/external-agents) diff --git a/docs/research/opencode-deep-dive.md b/docs/research/opencode-deep-dive.md new file mode 100644 index 00000000..4bdeb4c4 --- /dev/null +++ b/docs/research/opencode-deep-dive.md @@ -0,0 +1,480 @@ +# OpenCode Deep Dive — Comprehensive Analysis (March 2026) + +## Executive Summary + +OpenCode — open-source AI coding agent от Anomaly (ex-SST), ~126K GitHub stars, 800+ контрибьюторов, 5M MAU. Написан на TypeScript (Bun) + Go (TUI), MIT license. Поддерживает 75+ LLM-провайдеров через Models.dev. Архитектура client/server с persistent sessions. Agent Teams — community-implemented (не core), file-based JSONL inbox, peer-to-peer messaging, multi-provider teams (Claude+Codex+Gemini доказано). Главный конкурент Claude Code в terminal-agent пространстве. + +**Claim verification:** +- "95K+ stars" — **занижено**, на март 2026 ~126-129K stars +- "75+ providers" — **подтверждено**, через Models.dev + AI SDK +- "Multi-agent team support" — **частично**: agent teams реализованы community (opencode-ensemble plugin + PR #12730-12732), НЕ core feature, но доказали работу Claude+Codex+Gemini вместе + +--- + +## 1. What IS OpenCode? + +### Основные факты + +| Параметр | Значение | +|----------|----------| +| **Название** | OpenCode | +| **Организация** | Anomaly (ex-SST / Serverless Stack) | +| **GitHub** | [anomalyco/opencode](https://github.com/anomalyco/opencode) | +| **Сайт** | [opencode.ai](https://opencode.ai/) | +| **Stars** | ~126-129K (март 2026) | +| **Contributors** | 800+ | +| **Commits** | 10,000+ | +| **MAU** | 5M+ developers | +| **License** | MIT | +| **Языки** | TypeScript (Bun) — backend, Go — TUI, Zig — OpenTUI core | +| **Дата запуска** | 19 июня 2025 | +| **Версии** | Terminal CLI, Desktop App (beta), IDE extensions | + +### Кто создал + +**Founders:** +1. **Jay V (CEO)** — задает стратегию, enterprise sales. Университет Waterloo. +2. **Frank Wang (CTO)** — техническая архитектура. Model-agnostic дизайн с нуля. Университет Waterloo. +3. **Dax Raad** — public face, подкасты, Twitter. Ex-Amazon, ex-Ironbay. Присоединился к SST в 2021. +4. **Adam Elmore** — AWS Hero, indie hacker, AWS FM podcast host. + +**Происхождение:** Jay и Frank создали Anomaly, затем Serverless Stack (SST) — прошли Y Combinator, привлекли инвестиции от основателей PayPal, LinkedIn, Yelp, YouTube. SST набрал 25K stars, стал прибыльным в 2025. Во время SST команда строила terminal-first UIs и даже запустила Terminal — подписку на кофе через терминал ($100K продаж в первый год). + +### Скандальная история: Fork и Split (2025) + +- Оригинальный OpenCode создал **Kujtim Hoxha** на Go с Bubble Tea TUI +- **Charm** (компания, создатель Bubble Tea) приобрела проект, наняла Kujtim +- Dax Raad и Adam Doty (из SST) были major contributors, им не понравился ход +- Обвинения: Charm переписал git history, удалил контрибуции, забанил критиков +- **Результат:** Charm переименовал свою версию в **Crush**, а Dax/Adam сохранили бренд OpenCode под SST (anomalyco) +- Fork полностью переписан с Go на **TypeScript + Bun** для использования Vercel AI SDK + +### Скандал с Anthropic (январь 2026) + +- Ранние версии OpenCode подделывали HTTP-заголовок `claude-code-20250219`, выдавая себя за Claude Code +- 9 января 2026 Anthropic заблокировал сторонние tools от использования Claude OAuth +- 19 февраля 2026 Anthropic обновил Terms of Service, запретив OAuth токены Free/Pro/Max в third-party tools +- OpenCode удалил весь Claude OAuth код в тот же день +- Запустили **OpenCode Zen** (pay-as-you-go gateway) и **OpenCode Black** ($200/мес, enterprise) +- **18,000 новых stars за 2 недели** — controversy привлекла внимание + +--- + +## 2. Поддержка 75+ провайдеров + +**Подтверждено.** OpenCode использует [Models.dev](https://models.dev) + Vercel AI SDK для поддержки 75+ LLM-провайдеров. + +### Ключевые провайдеры + +| Провайдер | Детали | +|-----------|--------| +| OpenAI (GPT, Codex) | API key | +| Anthropic (Claude) | API key (после блокировки OAuth) | +| Google Gemini | API key + Vertex AI | +| AWS Bedrock | IAM credentials | +| Groq | API key | +| Azure OpenAI | Enterprise endpoint | +| OpenRouter | Pre-loaded models | +| Ollama (local) | `opencode --model ollama/qwen2.5-coder:32b` | +| GitHub Copilot | Copilot subscription (Pro+ для некоторых моделей) | +| ChatGPT Plus/Pro | OAuth login | +| Cloudflare AI Gateway | Unified billing, no per-provider keys | +| SAP AI Core | 40+ models, enterprise platform | +| GitLab | Agent Platform (18.8+) | +| Deepseek | API key | +| Local models | Any OpenAI-compatible endpoint | + +### Как это работает + +``` +User → OpenCode → AI SDK → Models.dev → Provider API → LLM Response +``` + +- Models.dev — реестр моделей с метаданными +- AI SDK (от Vercel) — универсальный SDK для вызова разных провайдеров +- `/connect` команда — добавление credentials +- `/models` команда — список доступных моделей +- Config: можно назначить разные модели для разных agent-ролей (plan vs build) + +### Монетизация через провайдеров + +| Tier | Цена | Описание | +|------|-------|----------| +| Free | $0 | BYO API key или local models (Ollama) | +| OpenCode Zen | Pay-per-token | Curated gateway, pass-through pricing | +| OpenCode Black | $200/мес | Enterprise, multi-provider (sold out) | + +--- + +## 3. Agent Teams: Multi-Agent Support + +### Статус: Community-Implemented, NOT Core Feature + +Важное уточнение: Agent Teams в OpenCode — это **community contribution**, а не встроенная core-фича (в отличие от Claude Code). + +- **GitHub Issue [#12661](https://github.com/anomalyco/opencode/issues/12661)** — Feature request для native agent teams +- **PRs #12730-12732** (dev branch) — community implementation (core, tools & routes, TUI) +- **[opencode-ensemble](https://github.com/hueyexe/opencode-ensemble)** — SDK plugin для agent teams +- **[opencode-workspace](https://github.com/kdcokenny/opencode-workspace)** — multi-agent orchestration harness + +### Архитектура Agent Teams (community implementation) + +#### Messaging: Two-Layer System + +``` +Layer 1: Inbox (Source of Truth) + team_inbox///.jsonl + Каждая строка: { id, from, text, timestamp, read } + +Layer 2: Session Injection (Delivery) + Message → injected as synthetic user message → LLM видит и обрабатывает +``` + +**Ключевые отличия от Claude Code:** + +| Аспект | Claude Code | OpenCode | +|--------|-------------|----------| +| Storage | JSON array (O(N) writes) | JSONL append-only (O(1)) | +| Messaging | Polling JSON files | Event-driven auto-wake | +| Communication | Leader-centric routing | Full mesh peer-to-peer | +| Multi-model | Single provider only | Multiple providers per team | +| Process model | 3 backends (in-process, tmux, iTerm2) | Single process | +| State tracking | Implicit | Two-level state machines | + +#### State Machines (Dual) + +**Member Status (5 states):** `ready` → `busy` → `shutdown_requested` → `shutdown` (terminal), `error` +- Guards: `guard: true` (prevents race conditions), `force: true` (crash recovery) + +**Execution Status (10 states):** Fine-grained prompt loop position tracking + +#### Peer-to-Peer Messaging + +Любой teammate может отправить сообщение любому другому по имени — не только через lead. Lead фокусируется на orchestration, а не routing. + +#### Sub-Agent Isolation + +Team tools (`team_create`, `team_spawn`, `team_message`) запрещены для sub-agents через deny rules + tool visibility hiding. Sub-agents — одноразовые workers, их output не должен попадать в coordination channel. + +### Доказано: Claude + Codex + Gemini в одной команде + +**Тест 1: Architecture Drama (3 провайдера)** +- GPT-5.3 Codex + Gemini 2.5 Pro + Claude Sonnet 4 +- Координация через один message bus +- Claiming tasks из shared list +- "Arguing about architecture" через peer-to-peer messaging + +**Тест 2: Super Bowl Prediction (4 Claude Opus)** +- Stats analyst + Betting analyst + Matchup analyst + Injury scout +- Full-mesh topology +- Atomic task claiming под concurrent access + +**Тест 3: NFL Research (2 Gemini)** +- Обнаружена проблема: Gemini генерировал ~50 одинаковых "task complete" сообщений в цикле + +### Ограничения + +- Agent teams пока на dev branch, не в stable release +- Нет multi-caller support в core — субагент не знает, кто с ним говорит (кроме Parent) +- Gemini имеет проблемы с message loop +- Recovery при crash: нет auto-restart, user должен re-engage teammates + +--- + +## 4. Architecture Deep Dive + +### Двухъязычная система + +``` +┌──────────────────────────────────────────────┐ +│ User runs `opencode` │ +│ (single Bun-compiled binary) │ +└──────────────────┬───────────────────────────┘ + │ + ┌────────▼─────────┐ + │ Bun Process │ + │ (TypeScript) │──── HTTP Server (API + SSE events) + │ - LLM calls │ ▲ + │ - Tool exec │ │ OpenAPI SDK + │ - Sessions │ │ (auto-generated by Stainless) + │ - LSP client │ ┌────┴──────┐ + │ - Plugin system │ │ Go TUI │ + │ - MCP client │ │ (Client) │ + └──────────────────┘ └────────────┘ + │ + (Migrating to OpenTUI: + Zig core + React/Solid/Vue) +``` + +### Backend (TypeScript + Bun) + +- **Runtime:** Bun (fast JavaScript runtime) +- **Build:** `bun build .. --compile` — single executable +- **HTTP Server:** API + SSE events для real-time updates +- **Storage:** SQLite для persistent data +- **LLM Communication:** Через Vercel AI SDK +- **Tool Execution:** LLM решает когда вызвать tool, SDK вызывает `execute` функцию +- **LSP Integration:** Отправляет `textDocument/didChange`, получает diagnostics, кормит LLM +- **40+ event types:** Через GlobalBus, доставка через SSE + +### Frontend (Go TUI → OpenTUI) + +- **Текущий:** Go с Bubble Tea framework +- **Мигрирует на:** [OpenTUI](https://github.com/anomalyco/opentui) — Zig core + TypeScript bindings +- **OpenTUI:** React/SolidJS/Vue reconcilers, Bun exclusive (Node/Deno в процессе) +- **Persistent sessions:** Сервер в background, TUI реконнектится после disconnect/sleep + +### Client-Server Protocol + +- **OpenAPI spec** → auto-generated SDK через Stainless +- **3 official SDKs:** TypeScript, Go, Python +- **SSE** для real-time events (40+ event types) +- **Zero dependencies** в SDK + +### Desktop App + +- Beta на macOS, Windows, Linux +- Также есть community [OpenGUI](https://dev.to/akemmanuel/i-built-a-native-desktop-gui-for-opencode-in-4-days-with-ai-p44) — Electron + React + +### IDE Extensions + +VS Code, Cursor, Zed, Windsurf, VSCodium + GitHub и GitLab integrations. + +--- + +## 5. Built-in Tools + +| Tool | Описание | +|------|----------| +| Shell | Выполнение bash команд | +| Edit | Exact string replacement в файлах | +| Write | Создание/перезапись файлов | +| Read | Чтение файлов | +| Grep | Regex поиск по codebase | +| LSP | Code intelligence: definitions, references, hover, call hierarchy | + +### Agents + +| Agent | Доступ | Назначение | +|-------|--------|------------| +| **Build** (default) | Full access | Development work | +| **Plan** | Read-only | Analysis, planning | +| **Review** | Read-only + docs | Code review | +| **Debug** | Bash + Read | Investigation | +| **Docs** | File ops, no shell | Documentation | +| **@general** | Subagent | Complex search/multistep | + +--- + +## 6. MCP Support + +**Полная поддержка MCP как client.** Feature request для MCP server mode ([#3306](https://github.com/sst/opencode/issues/3306)). + +### Типы MCP серверов + +1. **Local MCP Servers** — stdio-based communication, запускаются как local processes +2. **Remote MCP Servers** — HTTP + OAuth 2.0 (Dynamic Client Registration RFC 7591) + +### Конфигурация + +```json +// opencode.json +{ + "mcp": { + "sentry": { + "command": "npx", + "args": ["@sentry/mcp-server"], + "env": { "SENTRY_AUTH_TOKEN": "{env:SENTRY_TOKEN}" } + } + } +} +``` + +- Поддержка `{env:VAR}` и `{file:path}` для секретов +- `enabled: false` для временного отключения +- Auto-OAuth flow для remote servers +- Tools автоматически доступны LLM наряду с built-in tools + +### Предупреждение о Context + +MCP tools добавляют контекст. GitHub MCP server, например, может быстро превысить context limit. Рекомендуется осторожность при выборе MCP серверов. + +--- + +## 7. Plugin System & Extensibility + +### Plugin Sources + +1. **Directory plugins:** `.opencode/plugins/` (project) или `~/.config/opencode/plugins/` (global) +2. **NPM packages:** в opencode.json, auto-install через Bun + +### Hook Types + +| Hook | Описание | +|------|----------| +| `tool.execute.before/after` | Перехват tool calls | +| `session.created/updated` | Session lifecycle | +| `message.*` | Message events | +| `event` | System events (`session.idle`, `session.created`, etc.) | +| `experimental.session.compacting` | Inject context before compaction | +| `chat.message` | Modify messages before LLM | + +### Custom Tools + +Plugin tools можно определить — они доступны LLM наряду с built-in tools. Если имя совпадает с built-in, plugin tool имеет приоритет. + +### Notable Community Plugins + +- **EnvSitter** — блокирует чтение `.env*` файлов +- **Agent Ensemble** — agent teams orchestration +- **Persistent Memory** — self-editable memory blocks (как Letta) +- **Annotation UI** — перехватывает plan mode, открывает browser UI +- **Worktree Isolation** — git worktree per agent + +--- + +## 8. What Can We Learn From It? + +### Архитектурные идеи для Claude Agent Teams UI + +1. **Client/Server разделение** — persistent sessions, reconnect после disconnect. Наш Electron-подход можно дополнить server mode для remote access. + +2. **JSONL append-only inbox** — O(1) writes vs O(N) JSON array. **Мы уже используем JSONL для session files**, но team inbox в Claude Code — JSON array. Можно предложить Anthropic JSONL формат. + +3. **Event-driven vs Polling** — OpenCode использует SSE + event bus вместо file polling. Мы используем file watching с debounce (100ms). Event-driven подход быстрее и чище. + +4. **Peer-to-Peer messaging** — в Claude Code все идет через lead. OpenCode показывает, что full-mesh topology работает. **Мы уже отключили relay для teammate DMs** (см. CLAUDE.md), что близко к peer-to-peer. + +5. **Two-level state machines** — member status (coarse) + execution status (fine). Может улучшить наш UI для отображения состояния agents. + +6. **Plugin system** — hooks для tool.execute, session events, compaction. Потенциал для нашего MCP integration. + +7. **Multi-provider teams** — самая уникальная фича. Claude Code не может этого. Для нашего UI это не актуально (мы визуализируем Claude Code teams), но показывает направление рынка. + +8. **Auto-wake** — когда teammate отправляет сообщение idle agent'у, он автоматически "просыпается". В Claude Code нужен manual re-engage. + +--- + +## 9. Competitor or Integration Partner? + +### Как конкурент нашему продукту + +| Аспект | OpenCode | Claude Agent Teams UI (мы) | +|--------|----------|---------------------------| +| **Что это** | Coding agent | UI для управления agent teams | +| **Kanban** | Нет (только community: opencode-kanban, VibeKanban) | Встроенный kanban board | +| **Code Review** | Нет diff view в TUI | Diff view per task | +| **Team Management** | CLI-based, нет visual management | Visual kanban + real-time status | +| **Notifications** | Нет | Встроенные уведомления | +| **Session Analysis** | Базовый | Deep analysis (bash, reasoning, subagents) | +| **Context Monitoring** | Нет | Token usage по категориям | +| **Direct Messaging** | Через CLI | Visual DM interface | + +**Вывод: OpenCode — НЕ прямой конкурент.** Они coding agent, мы — UI для управления agent teams. OpenCode больше конкурирует с Claude Code CLI, а не с нашим UI. + +### Как потенциальный integration partner + +OpenCode имеет **полноценный SDK** (TypeScript, Go, Python) и **SSE events**. Теоретически мы могли бы: + +1. **Добавить OpenCode backend** — управлять OpenCode sessions через их SDK вместо/параллельно Claude Code +2. **Визуализировать OpenCode teams** — их agent teams используют JSONL inbox, мы могли бы парсить +3. **Multi-agent kanban** — один kanban для Claude Code + OpenCode agents +4. **Cross-provider orchestration** — использовать наш UI для управления mixed teams (Claude через Claude Code, GPT/Gemini через OpenCode) + +**Риски интеграции:** +- OpenCode agent teams — community feature, не stable API +- Совершенно другая архитектура (HTTP SDK vs CLI process management) +- Потребуется значительная работа по адаптации + +--- + +## 10. Unique Features vs Claude Code + +| Feature | OpenCode | Claude Code | +|---------|----------|-------------| +| **Model freedom** | 75+ providers, local models | Only Anthropic | +| **Open source** | MIT license, full source | Closed source | +| **Desktop app** | Beta (macOS/Win/Linux) | Нет | +| **IDE extensions** | VS Code, Cursor, Zed, Windsurf | Нет (только CLI) | +| **Plugin system** | Hooks, custom tools, npm plugins | Hooks (bash-based) | +| **Persistent sessions** | Client/server, reconnect | Нет | +| **Agent types** | Build/Plan/Review/Debug/Docs + custom | One agent + subagents | +| **SDK** | TypeScript/Go/Python, OpenAPI spec | Нет public SDK | +| **LSP integration** | Built-in, feeds diagnostics to LLM | Нет | +| **Agent Teams** | Community (multi-provider!) | Native (single provider) | +| **Context compaction** | Supports plugin hook | Automatic | +| **Pricing** | Free + BYO API key | $20/mo Claude Pro minimum | +| **Accuracy** | Varies by model | SWE-bench Pro 57.5% | +| **Adoption** | 5M MAU, 126K stars | 4% of GitHub commits, 135K/day | + +### Что уникально у OpenCode + +1. **Model agnosticism** — designed from day one, не afterthought +2. **Client/server architecture** — sessions persist, remote control possible +3. **Multi-provider agent teams** — Claude+Codex+Gemini в одной команде +4. **Plugin ecosystem** — rich hook system, npm packages, custom tools +5. **3 official SDKs** — TypeScript, Go, Python +6. **OpenTUI** — собственный TUI framework на Zig + +### Что уникально у Claude Code (и у нас) + +1. **Native agent teams** — core feature, не community plugin +2. **SWE-bench accuracy** — лучшие результаты на бенчмарках +3. **4% GitHub commits** — доминирует в реальном использовании +4. **Stream-json protocol** — надежный IPC для agent coordination +5. **Kanban board** (наш UI) — НИКТО не имеет визуального kanban для agent teams + +--- + +## Summary & Key Takeaways + +### Факты (verified) + +- OpenCode — реальный и крупный проект: ~126-129K stars, 800+ contributors, 5M MAU +- 75+ providers — подтверждено через Models.dev + AI SDK +- MIT license — подтверждено +- Agent teams с multi-provider — доказано (community implementation) +- TypeScript (Bun) + Go + Zig architecture — подтверждено +- MCP client support — полноценный +- Desktop app + IDE extensions — beta, но работает +- Plugin system — rich, с hooks и custom tools + +### Риски и concerns + +- Agent teams — community feature, не stable, на dev branch +- Скандал с Anthropic OAuth — показывает этические вопросы +- Fork controversy — community split может повлиять на долгосрочную стабильность +- Gemini message loop bug — multi-provider teams нестабильны +- OpenCode Black ($200/мес) sold out — бизнес-модель не ясна + +### Relevance для нашего продукта + +- **Прямая конкуренция: НЕТ** — мы UI для team management, они coding agent +- **Косвенная конкуренция: ДА** — community tools (opencode-kanban, VibeKanban) пытаются решить ту же проблему +- **Потенциал интеграции: СРЕДНИЙ** — SDK доступен, но архитектура сильно отличается +- **Наше преимущество сохраняется:** Kanban board для agent teams нет НИ У КОГО, включая OpenCode + +--- + +## Sources + +- [anomalyco/opencode (GitHub)](https://github.com/anomalyco/opencode) +- [opencode.ai](https://opencode.ai/) +- [OpenCode Docs](https://opencode.ai/docs/) +- [Building Agent Teams in OpenCode (DEV Community)](https://dev.to/uenyioha/porting-claude-codes-agent-teams-to-opencode-4hol) +- [How OpenCode went from zero to titan (Dev Genius)](https://blog.devgenius.io/how-opencode-went-from-zero-to-titan-in-eight-months-dcdcd8ff5572) +- [OpenCode background story (TFN)](https://techfundingnews.com/opencode-the-background-story-on-the-most-popular-open-source-coding-agent-in-the-world/) +- [How Coding Agents Actually Work: Inside OpenCode](https://cefboud.com/posts/coding-agents-internals-opencode-deepdive/) +- [OpenCode vs Claude Code (MorphLLM)](https://www.morphllm.com/comparisons/opencode-vs-claude-code) +- [OpenCode vs Claude Code (DataCamp)](https://www.datacamp.com/blog/opencode-vs-claude-code) +- [OpenCode vs Anthropic Legal Controversy](https://www.shareuhack.com/en/posts/opencode-anthropic-legal-controversy-2026) +- [OpenCode MCP Servers docs](https://opencode.ai/docs/mcp-servers/) +- [OpenCode Plugins docs](https://opencode.ai/docs/plugins/) +- [OpenCode Agents docs](https://opencode.ai/docs/agents/) +- [OpenCode Models docs](https://opencode.ai/docs/models/) +- [OpenCode Providers docs](https://opencode.ai/docs/providers/) +- [OpenTUI (GitHub)](https://github.com/anomalyco/opentui) +- [opencode-ensemble (GitHub)](https://github.com/hueyexe/opencode-ensemble) +- [opencode-kanban (GitHub)](https://github.com/qrafty-ai/opencode-kanban) +- [Vibe Kanban](https://vibekanban.com/) +- [awesome-opencode (GitHub)](https://github.com/awesome-opencode/awesome-opencode) diff --git a/docs/research/orchestrator-as-foundation.md b/docs/research/orchestrator-as-foundation.md new file mode 100644 index 00000000..db3bc2e1 --- /dev/null +++ b/docs/research/orchestrator-as-foundation.md @@ -0,0 +1,284 @@ +# Оценка: внешний оркестратор как фундамент вместо собственного agent management + +**Дата**: 2026-03-25 +**Вопрос**: стоит ли взять готовый multi-agent оркестратор и посадить наш Electron UI сверху, вместо того чтобы развивать собственный TeamProvisioningService? + +--- + +## 1. Что мы бы заменяли (наш текущий стек) + +### Собственная инфраструктура + +| Компонент | Файлы | LOC | Что делает | +|-----------|-------|-----|------------| +| `TeamProvisioningService.ts` | 1 | ~8000 | Полный lifecycle команды: создание, запуск, stream-json протокол, preflight, stdin relay, tool approval, stall detection, cross-team messaging | +| `agent-teams-controller/` | ~20 модулей | ~4050 | Kanban store, task management, review workflow, cross-team protocol, runtime helpers, message store, process store | +| Остальные team сервисы | 38 файлов | ~13200 | TeamConfigReader, TeamInboxReader/Writer, TeamTaskReader/Writer, TeamKanbanManager, TeamMcpConfigBuilder, CascadeGuard, CrossTeamService, ReviewApplier, MemberStatsComputer, TeamBackupService и др. | +| `childProcess.ts` | 1 | ~220 | spawnCli/execCli с Windows fallback, process tree kill | +| MCP server tools | 8 файлов | ~500 | taskTools, kanbanTools, reviewTools, messageTools, processTools, runtimeTools, crossTeamTools | +| **ИТОГО** | ~68 файлов | **~26000 LOC** | | + +### Ключевые точки spawn (spawnCli вызовы) + +- `TeamProvisioningService.ts` — 4 точки: create team, launch team, launch member, DM relay +- `CliInstallerService.ts` — install CLI +- `ScheduledTaskExecutor.ts` — scheduled tasks +- `McpHealthDiagnosticsService.ts`, `PluginInstallService.ts`, `McpInstallService.ts` — execCli для MCP/plugin операций + +### Что уникально в нашей реализации + +1. **stream-json протокол** — двусторонний, lead читает stdin, teammates читают inbox +2. **Tool approval system** — перехват tool_use запросов, auto-approve по правилам, UI промпт +3. **Cross-team communication** — structured TaskRef, inbox files, cross-team MCP tools +4. **Kanban + code review** — 5-column board, diff view, approve/request_changes workflow +5. **MCP config builder** — передача `--mcp-config` с наследованием для teammates +6. **SIGKILL-only kill** — предотвращение cleanup CLI, который удаляет team файлы +7. **Context monitoring** — token usage tracking по категориям + +--- + +## 2. Оценка кандидатов + +### 2.1 MCO (mco-org/mco) + +**GitHub**: https://github.com/mco-org/mco +**Stars**: ~249 | **Лицензия**: MIT | **Язык**: TypeScript (CLI) +**npm**: `@tt-a1i/mco` + +| Критерий | Оценка | +|----------|--------| +| Используется как библиотека? | **НЕТ** — только CLI. Нет programmatic API для import. | +| Inter-agent communication? | Частично — агенты диспатчат задачи через MCO CLI, но нет inbox/messaging системы | +| MCP поддержка? | Да — может работать как MCP server | +| Что бы мы СОХРАНИЛИ? | Всё UI, kanban, review, context tracking | +| Что бы мы ЗАМЕНИЛИ? | Только dispatch логику (4 spawnCli точки), и то частично | +| Effort интеграции | **Высокий** — MCO не даёт API, пришлось бы обёртывать CLI вызовы | +| Риск зависимости | **Средний** — 249 stars, 1 основной автор | + +**Вердикт**: MCO решает другую задачу (dispatch к разным CLI), а не управление командой. У нас уже есть более продвинутая система. +- Надёжность решения: **3/10** +- Уверенность в оценке: **8/10** + +--- + +### 2.2 Overstory (jayminwest/overstory) + +**GitHub**: https://github.com/jayminwest/overstory +**Stars**: ~1100 | **Лицензия**: MIT | **Язык**: TypeScript (Bun-native) +**npm**: `@os-eco/overstory-cli` + +| Критерий | Оценка | +|----------|--------| +| Используется как библиотека? | Частично — есть pluggable AgentRuntime интерфейс, но **ТРЕБУЕТ BUN** (не Node.js/Electron) | +| Inter-agent communication? | **Да** — SQLite mail system, 8 типов сообщений, WAL mode, broadcast | +| MCP поддержка? | Упоминается, но без деталей | +| Зависимости | **Bun v1.0+, tmux, git** — все три обязательны | +| Что бы мы СОХРАНИЛИ? | UI, kanban, review, context tracking, MCP server | +| Что бы мы ЗАМЕНИЛИ? | TeamProvisioningService, inbox system, process management | +| Effort интеграции | **КРИТИЧЕСКИЙ** — Bun runtime несовместим с Electron (Node.js). Потребуется форк или полный переписывание на Node.js | +| Риск зависимости | **Высокий** — 1 автор, Bun lock-in, tmux dependency | + +**Вердикт**: Архитектурно интересен (SQLite mail, pluggable runtimes, watchdog), но **Bun dependency — dealbreaker** для Electron-приложения. tmux dependency тоже проблема (нет на Windows). +- Надёжность решения: **2/10** +- Уверенность в оценке: **9/10** + +--- + +### 2.3 ComposioHQ/agent-orchestrator + +**GitHub**: https://github.com/ComposioHQ/agent-orchestrator +**Stars**: ~5400 | **Лицензия**: MIT | **Язык**: TypeScript (pnpm monorepo) +**npm**: `@composio/ao` (CLI) + +| Критерий | Оценка | +|----------|--------| +| Используется как библиотека? | **Условно** — monorepo с packages, но core не опубликован как отдельный npm пакет `@composio/ao-core`. Нет документации по programmatic API. | +| Inter-agent communication? | **Нет прямой** — агенты изолированы в worktrees, координация через dashboard/server | +| MCP поддержка? | Не упоминается | +| Зависимости | tmux, Next.js dashboard (порт 3000) | +| Plugin architecture | **Сильная** — 8 swappable slots (Runtime, Agent, Workspace, Tracker, SCM, Notifier, Terminal, Lifecycle) | +| Что бы мы СОХРАНИЛИ? | Kanban UI, review, context tracking, cross-team messaging, MCP tools | +| Что бы мы ЗАМЕНИЛИ? | Process spawning, workspace isolation | +| Effort интеграции | **Высокий** — нет published API, потребуется fork monorepo, вырезание Next.js dashboard, адаптация под Electron IPC | +| Риск зависимости | **Средний** — 5.4K stars, Composio (коммерческая компания) за спиной, но agent-orchestrator =/= их core business | + +**Вердикт**: Самый продвинутый из кандидатов. Plugin architecture — то что нужно. НО: нет published programmatic API, нет inter-agent messaging (мы это уже имеем), требует tmux, и dashboard на Next.js конфликтует с нашим Electron. Интеграция = фактически форк. +- Надёжность решения: **4/10** +- Уверенность в оценке: **8/10** + +--- + +### 2.4 MetaSwarm (dsifry/metaswarm) + +**GitHub**: https://github.com/dsifry/metaswarm +**Stars**: ~148 | **Лицензия**: MIT | **Язык**: TypeScript/JS (skills + commands) +**npm**: `metaswarm` (npx installer) + +| Критерий | Оценка | +|----------|--------| +| Используется как библиотека? | **НЕТ** — это framework из skills/commands/hooks, инжектируемый в CLAUDE.md. Не importable. | +| Inter-agent communication? | Через Claude Code Team Mode (нативный) | +| MCP поддержка? | Нет собственной — использует нативный Claude Code | +| Что бы мы ЗАМЕНИЛИ? | Ничего — это workflow methodology, не runtime | +| Effort интеграции | **Неприменимо** — это не backend, это набор CLAUDE.md инструкций и скриптов | +| Риск зависимости | **Высокий** — 148 stars, 2 контрибьютора, последний коммит feb 2026 | + +**Вердикт**: MetaSwarm — это не оркестратор в техническом смысле. Это structured workflow (skills, personas, phases), который инжектируется в prompt. Не подходит как backend. +- Надёжность решения: **1/10** +- Уверенность в оценке: **9/10** + +--- + +### 2.5 ORCH (oxgeneral/ORCH) + +**GitHub**: https://github.com/oxgeneral/ORCH (404 на момент проверки, возможно приватный) +**Website**: https://www.orch.one +**Stars**: Неизвестно | **Лицензия**: MIT | **Язык**: TypeScript +**npm**: `@oxgeneral/orch` (GitHub Packages registry) + +| Критерий | Оценка | +|----------|--------| +| Используется как библиотека? | **НЕТ** — CLI-only (`npm i -g @oxgeneral/orch`). Нет programmatic API. | +| Inter-agent communication? | **Да** — direct messaging + broadcast + shared key-value store | +| MCP поддержка? | Не упоминается | +| State machine | task states: todo → in_progress → review → done | +| Зависимости | git worktrees, TUI (терминал) | +| Что бы мы ЗАМЕНИЛИ? | Process management, state machine, messaging | +| Effort интеграции | **Высокий** — CLI-only, GitHub Packages registry (не стандартный npm), GitHub 404 | +| Риск зависимости | **КРИТИЧЕСКИЙ** — GitHub repo недоступен (404), 1 автор | + +**Вердикт**: Архитектурно интересен (DDD, state machine, 987 тестов), но **GitHub repo 404** — красный флаг. CLI-only без programmatic API. Нельзя рассматривать как зависимость. +- Надёжность решения: **1/10** +- Уверенность в оценке: **7/10** (7 потому что repo недоступен, не можем полноценно проверить) + +--- + +### 2.6 conductor-oss (charannyk06/conductor-oss) + +**GitHub**: https://github.com/charannyk06/conductor-oss +**Stars**: ~14 | **Лицензия**: MIT | **Язык**: Rust (backend) + TypeScript (Next.js frontend) +**Adapters**: 10 (Claude Code, Codex, Gemini, Qwen, Amp, Cursor CLI, OpenCode, Droid, Copilot, CCR) + +| Критерий | Оценка | +|----------|--------| +| Используется как библиотека? | **Частично** — Rust binary + HTTP API (port 4747). Можно использовать API. | +| Inter-agent communication? | Через orchestrator server | +| MCP поддержка? | **Да** — `mcp-server` команда, stdio transport | +| Dashboard | Next.js (порт 3000) — конфликт с нашим Electron | +| Что бы мы ЗАМЕНИЛИ? | Agent spawning, workspace isolation, adapter layer | +| Что бы мы СОХРАНИЛИ? | Всё UI, kanban, review, messaging, context tracking | +| Effort интеграции | **Средний-Высокий** — HTTP API есть, но Rust binary нужно распространять с Electron, Next.js dashboard лишний | +| Риск зависимости | **КРИТИЧЕСКИЙ** — 14 stars, 1 автор, Rust dependency в TypeScript/Electron проекте | + +**Вердикт**: HTTP API делает интеграцию возможной, 10 адаптеров впечатляют. НО: 14 stars, Rust sidecar binary для Electron — серьёзная сложность в packaging и distribution. Проект слишком молодой. +- Надёжность решения: **2/10** +- Уверенность в оценке: **8/10** + +--- + +## 3. Сводная таблица + +| Оркестратор | Stars | Library? | Inter-agent msg | MCP | Electron-совместим | Effort | Риск | +|-------------|-------|----------|-----------------|-----|-------------------|--------|------| +| **MCO** | 249 | CLI only | Partial | Yes | Partial | High | Medium | +| **Overstory** | 1.1K | Bun only | SQLite mail | Partial | **NO (Bun)** | Critical | High | +| **Composio AO** | 5.4K | No published API | No direct | No | Partial (tmux) | High | Medium | +| **MetaSwarm** | 148 | No (skills) | Native CC | No | N/A | N/A | High | +| **ORCH** | ? | CLI only | Yes | No | No (TUI) | High | **Critical** | +| **conductor-oss** | 14 | HTTP API | Via server | Yes | Partial (Rust) | Medium-High | **Critical** | + +--- + +## 4. Что конкретно нам дал бы внешний оркестратор + +### Потенциальная ценность +1. **Multi-runtime support** — запуск не только Claude Code, но и Codex, Gemini, Aider +2. **Git worktree isolation** — у нас нет, но и не нужен (Claude Code сам управляет файлами) +3. **Adapters pattern** — абстракция спавна разных CLI + +### Что мы УЖЕ имеем и ни один оркестратор не даёт +1. **stream-json bidirectional protocol** — уникальная интеграция с Claude Code Agent Teams +2. **Tool approval UI** — перехват и approve/reject tool calls в реальном времени +3. **Cross-team structured messaging** — TaskRef, zero-width metadata encoding +4. **Kanban с code review** — diff view, approve/request_changes per task +5. **Context monitoring** — 6-category token tracking +6. **MCP server with 7 tool groups** — kanban, tasks, review, messages, processes, runtime, cross-team +7. **Post-compact context recovery** — восстановление инструкций после compaction +8. **SIGKILL team kill protocol** — предотвращение file cleanup +9. **Cascading guard** — предотвращение cascade team deletion + +--- + +## 5. Ключевой вопрос: стоит ли зависеть от внешнего оркестратора? + +### Аргументы ЗА интеграцию +- Multi-runtime support (Codex, Gemini, Aider) без написания адаптеров +- Потенциально меньше кода для поддержки +- Community contributions и bug fixes + +### Аргументы ПРОТИВ (перевешивают) + +1. **Ни один оркестратор не имеет programmatic library API для embedding в Electron** + - Все либо CLI-only, либо CLI + собственный dashboard + - Интеграция = обёртка над CLI вызовами или fork — то есть по сути мы сами пишем адаптер + +2. **Наша интеграция глубже любого оркестратора** + - stream-json протокол, tool approval, cross-team refs — этого нет НИ У КОГО + - Мы бы потеряли эти фичи при переходе на внешний backend + +3. **Несовместимость со стеком** + - Bun (Overstory) vs Node.js/Electron + - Rust sidecar (conductor-oss) — packaging nightmare + - tmux (Composio, Overstory) — нет на Windows + - Next.js dashboards — дублирование с нашим Electron UI + +4. **Стоимость интеграции >= стоимость написания адаптера** + - Даже для лучшего кандидата (Composio AO) нужен fork monorepo + выпиливание Next.js + адаптация под IPC + - Это ~2-4 недели работы с непредсказуемым результатом + - Наш собственный adapter layer для нового CLI = ~200-500 LOC (1-2 дня) + +5. **Риск зависимости** + - Большинство проектов < 6 месяцев, 1-2 автора + - Composio AO (5.4K stars) — самый живой, но agent-orchestrator != core business Composio + - Если проект умирает — мы на форке без community + +--- + +## 6. Рекомендация + +### Вердикт: **НЕ ИСПОЛЬЗОВАТЬ внешний оркестратор как фундамент** + +Стоимость интеграции выше, чем написание собственного тонкого adapter layer. + +### Что стоит ЗАИМСТВОВАТЬ (паттерны, не код) + +| Паттерн | Источник | Применение у нас | +|---------|----------|-----------------| +| Plugin architecture (8 slots) | Composio AO | Вынести agent adapter в интерфейс `AgentRuntime` для будущей multi-runtime поддержки | +| SQLite mail system | Overstory | Рассмотреть для замены JSON inbox files (производительность) | +| State machine для tasks | ORCH | У нас уже есть kanban states, но можно формализовать transitions | +| AgentRuntime interface | Overstory | `{ spawn, configure, detectReadiness, parseTranscript }` — хороший контракт | +| Tiered watchdog | Overstory | Stall detection → AI triage → monitor agent | + +### Рекомендуемый план + +1. **Сейчас**: оставить текущую архитектуру, она работает и покрывает наш use case +2. **Если нужен multi-runtime**: написать `AgentRuntime` интерфейс (~200 LOC) + адаптер для каждого CLI (~300-500 LOC) +3. **Если нужна масштабируемость messaging**: рассмотреть миграцию с JSON inbox → SQLite WAL +4. **Мониторить** Composio AO — если опубликуют `@composio/ao-core` как npm library с programmatic API, пересмотреть решение + +- **Надёжность рекомендации**: 8/10 +- **Уверенность**: 9/10 + +--- + +## Источники + +- [MCO (mco-org/mco)](https://github.com/mco-org/mco) — 249 stars, CLI-only orchestrator +- [Overstory (jayminwest/overstory)](https://github.com/jayminwest/overstory) — 1.1K stars, Bun + SQLite + tmux +- [Composio Agent Orchestrator](https://github.com/ComposioHQ/agent-orchestrator) — 5.4K stars, plugin architecture +- [MetaSwarm (dsifry/metaswarm)](https://github.com/dsifry/metaswarm) — 148 stars, workflow framework +- [ORCH (orch.one)](https://www.orch.one/) — CLI runtime, GitHub repo 404 +- [conductor-oss (markdown-native)](https://github.com/charannyk06/conductor-oss) — 14 stars, Rust + 10 adapters +- [Awesome Agent Orchestrators](https://github.com/andyrewlee/awesome-agent-orchestrators) — каталог 80+ инструментов +- [Composio Architecture Design](https://github.com/ComposioHQ/agent-orchestrator/blob/main/artifacts/architecture-design.md) diff --git a/docs/research/sdk-vs-cli-comparison.md b/docs/research/sdk-vs-cli-comparison.md new file mode 100644 index 00000000..5a0e8020 --- /dev/null +++ b/docs/research/sdk-vs-cli-comparison.md @@ -0,0 +1,376 @@ +# SDK vs CLI Direct Spawn: Honest Comparison + +**Date:** 2026-03-25 +**Status:** Research complete +**Verdict:** SDKs are NOT limiting — they ARE the CLI with a nicer API, plus extras. But there are real tradeoffs. + +--- + +## TL;DR + +All three SDKs (Claude Agent SDK, Codex SDK, Gemini CLI SDK) **spawn the CLI as a child process** under the hood and communicate via stdin/stdout JSON protocol. The SDK IS the CLI — it just wraps `child_process.spawn()` with a typed API. There is **no functional limitation** vs direct spawn, because the SDK literally does the same thing. However, there is a **real performance overhead** (~12s per `query()` call for Claude) and some **CLI-only features** (Agent Teams for Claude) that require workarounds. + +--- + +## 1. Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`) + +### Architecture: How It Works Under the Hood + +The SDK **bundles `cli.js`** directly inside the npm package. When you call `query()`, it spawns a Node.js process running this bundled CLI with `--input-format stream-json --output-format stream-json --verbose`. Communication is via NDJSON over stdin/stdout. + +> "The SDK code actually bundles a cli.js file directly — which contains the entire Claude Code CLI." +> — [Claude Agent SDK Pitfalls](https://liruifengv.com/posts/claude-agent-sdk-pitfalls-en/) + +**Key insight:** The `spawnClaudeCodeProcess` option lets you provide a completely custom spawn function. Node's `ChildProcess` already satisfies the `SpawnedProcess` interface. This means you can override HOW the CLI is spawned — Docker, VM, remote, whatever. + +### Complete Options Reference (from [official docs](https://platform.claude.com/docs/en/agent-sdk/typescript)) + +| Option | Type | Description | +|--------|------|-------------| +| `model` | `string` | Claude model to use | +| `cwd` | `string` | Working directory | +| `env` | `Record` | Environment variables | +| `systemPrompt` | `string \| preset` | Custom or `claude_code` preset | +| `allowedTools` | `string[]` | Auto-approve tools | +| `disallowedTools` | `string[]` | Deny tools (checked first, overrides everything) | +| `mcpServers` | `Record` | MCP server configs (stdio, SSE, HTTP, in-process SDK) | +| `strictMcpConfig` | `boolean` | Only use MCP servers from this config | +| `settingSources` | `SettingSource[]` | `["user", "project", "local"]` to match CLI behavior | +| `permissionMode` | `PermissionMode` | `default`, `acceptEdits`, `bypassPermissions`, `plan`, `dontAsk` | +| `canUseTool` | `Function` | Custom permission callback | +| `agents` | `Record` | Programmatic subagents | +| `hooks` | `Partial>` | Programmatic hook callbacks | +| `plugins` | `SdkPluginConfig[]` | Load custom plugins | +| `maxTurns` | `number` | Max agentic turns | +| `maxBudgetUsd` | `number` | Budget cap | +| `effort` | `'low'\|'medium'\|'high'\|'max'` | Thinking depth | +| `thinking` | `ThinkingConfig` | Adaptive thinking config | +| `betas` | `SdkBeta[]` | Beta features (e.g., `context-1m-2025-08-07`) | +| `includePartialMessages` | `boolean` | Stream partial responses | +| `outputFormat` | `{ type: 'json_schema', schema }` | Structured output | +| `spawnClaudeCodeProcess` | `Function` | Custom spawn function | +| `pathToClaudeCodeExecutable` | `string` | Custom CLI path | +| `executable` | `'bun'\|'deno'\|'node'` | JS runtime | +| `executableArgs` | `string[]` | Runtime args | +| **`extraArgs`** | **`Record`** | **ANY arbitrary CLI flags** | +| `debug` | `boolean` | Debug mode | +| `debugFile` | `string` | Debug log file | +| `sandbox` | `SandboxSettings` | Sandbox config | +| `persistSession` | `boolean` | Disable session persistence | +| `resume` | `string` | Resume session by ID | +| `forkSession` | `boolean` | Fork on resume | +| `enableFileCheckpointing` | `boolean` | File change tracking | +| `fallbackModel` | `string` | Fallback model | +| `promptSuggestions` | `boolean` | Emit prompt suggestions | +| `stderr` | `Function` | Stderr callback | + +### Feature Comparison: SDK vs CLI Direct + +| Feature | CLI Direct | SDK | Notes | +|---------|-----------|-----|-------| +| MCP config | `--mcp-config '{...}'` | `mcpServers: {...}` | SDK has typed config + in-process MCP servers (SDK advantage) | +| Strict MCP | `--strict-mcp-config` | `strictMcpConfig: true` | Equivalent | +| Disallowed tools | `--disallowedTools X,Y` | `disallowedTools: ['X','Y']` | Equivalent. Known bug: both ignore MCP tools in `-p` mode ([#12863](https://github.com/anthropics/claude-code/issues/12863)) | +| Allowed tools | `--allowedTools X,Y` | `allowedTools: ['X','Y']` | Equivalent | +| stream-json I/O | `--input-format stream-json --output-format stream-json` | Automatic (SDK default) | SDK uses this internally, no config needed | +| Permission mode | `--permission-mode X` | `permissionMode: 'X'` | Equivalent | +| Custom flags | Any `--flag value` | `extraArgs: { flag: 'value' }` | **SDK supports arbitrary flags via `extraArgs`** | +| CLAUDE.md | Auto-loaded | `settingSources: ['project']` | Opt-in in SDK, auto in CLI | +| Custom spawn | Manual `child_process.spawn()` | `spawnClaudeCodeProcess: (opts) => spawn(...)` | SDK provides typed interface | +| In-process MCP | Not possible | `createSdkMcpServer()` | **SDK-only advantage** — no subprocess overhead | +| Custom tools | Via MCP only | In-process functions | **SDK-only advantage** | +| Programmatic hooks | Via config files | Callback functions | **SDK-only advantage** | +| Programmatic subagents | Via config files | `agents: {...}` inline | **SDK-only advantage** | +| Agent Teams | Full support | **CLI-only feature** | Not configurable via SDK options. Must use CLI | +| Auto memory | Full support | **Never loaded by SDK** | CLI-only feature | +| Skills | Full support | Via `settingSources` + `allowedTools: ['Skill']` | Equivalent when configured | +| Session resume | `claude --resume ID` | `resume: 'sessionId'` | Equivalent | +| Streaming | Via flags | `includePartialMessages: true` | SDK provides typed events | +| Structured output | Not available | `outputFormat: { type: 'json_schema', ... }` | **SDK-only advantage** | +| File checkpointing | Not available | `enableFileCheckpointing: true` | **SDK-only advantage** | +| V2 Session API | Not available | `unstable_v2_*` | **SDK-only**, unstable | + +### Performance: ~12s Overhead Per `query()` Call + +**This is real and documented.** Each `query()` call spawns a new CLI process, which takes ~12s to initialize. + +> "The Claude Agent SDK `query()` has ~12s overhead per call — no hot process reuse" +> — [GitHub Issue #34](https://github.com/anthropics/claude-agent-sdk-typescript/issues/34) + +For comparison, direct Anthropic Messages API: 1-3s. Previous SDK versions: ~40s (improved 70%). + +**But for our use case (long-running agent sessions), this doesn't matter.** We spawn teams that run for minutes/hours. 12s startup is amortized. If you need sub-second responses, use the Anthropic API directly — not the SDK and not CLI direct. + +**Direct CLI spawn has the SAME overhead** — the 12s is the CLI initialization time, not SDK overhead. SDK adds negligible wrapper cost on top. + +### SDK-Only Features (Not Available in CLI Direct) + +1. **In-process MCP servers** — `createSdkMcpServer()`, no subprocess management +2. **Custom tools as functions** — No separate MCP server needed +3. **Programmatic hooks** — TypeScript/Python callbacks, not shell scripts +4. **Structured output** — JSON schema for typed responses +5. **File checkpointing** — Rewind file changes to any point +6. **Typed message stream** — `SDKMessage` union type with discriminators +7. **Dynamic MCP management** — `setMcpServers()`, `toggleMcpServer()`, `reconnectMcpServer()` +8. **Prompt suggestions** — AI-generated next prompt +9. **Permission callbacks** — `canUseTool()` with structured decisions + +### CLI-Only Features (Not Available in SDK) + +1. **Agent Teams** — Multiple coordinated sessions (our core feature!) +2. **Auto memory** — `~/.claude/projects/*/memory/` persistence +3. **Interactive TUI** — Terminal UI + +### Critical Finding for Our Project + +**Agent Teams are CLI-only.** The official docs explicitly state: +> "Agent teams are a CLI feature where one session acts as the team lead, coordinating work across independent teammates." +> — [Claude Code Features in SDK](https://platform.claude.com/docs/en/agent-sdk/claude-code-features) + +This means for our team management feature, we **MUST** use CLI direct (which we already do). The SDK cannot replace our current architecture for teams. + +However, for solo agents or subagent workflows, the SDK provides a better API. + +--- + +## 2. Codex SDK (`@openai/codex-sdk`) + +### Architecture + +> "The TypeScript SDK wraps the Codex CLI from `@openai/codex`. It spawns the CLI and exchanges JSONL events over stdin/stdout." +> — [Codex SDK docs](https://developers.openai.com/codex/sdk) + +Same pattern as Claude: SDK spawns CLI subprocess. + +### API Surface + +```typescript +const codex = new Codex({ + env?: Record, // Environment variables + baseUrl?: string, // API base URL (→ --config openai_base_url=...) + config?: Record // Arbitrary config (→ --config key=value) +}); + +const thread = codex.startThread({ + workingDirectory?: string, + skipGitRepoCheck?: boolean +}); + +// Buffered +const result = await thread.run(prompt, { outputSchema?: JSONSchema }); + +// Streaming +for await (const event of thread.runStreamed(prompt)) { ... } + +// Resume +const thread = codex.resumeThread(threadId); +``` + +### Feature Comparison: SDK vs CLI Direct + +| Feature | CLI Direct | SDK | Notes | +|---------|-----------|-----|-------| +| MCP config | `config.toml` / `codex mcp` | Via `config` option passthrough | CLI manages MCP directly | +| Custom flags | Any flag | `config: { key: value }` → `--config key=value` | Limited to config passthrough | +| Model selection | `/model` command | Not directly exposed | Must use config | +| Approval modes | `--full-auto`, etc. | Not directly exposed | Must use config or env | +| Structured output | Not in interactive mode | `outputSchema` (Zod → JSON Schema) | **SDK advantage** | +| Thread persistence | `codex resume` | `resumeThread(threadId)` | Equivalent | +| Streaming | JSONL stdout | `runStreamed()` async generator | SDK provides typed events | +| Multimodal input | Screenshots, sketches | `{ type: 'local_image', path }` | Equivalent | +| Performance | Baseline (CLI init) | Same + minimal SDK overhead | No significant difference | + +### Native SDK Alternative: `@codex-native/sdk` + +There's a Rust-based alternative via napi-rs that **does NOT spawn child processes**: + +> "The Native SDK provides Rust-powered bindings via napi-rs, giving you direct access to Codex functionality without spawning child processes." +> — [@codex-native/sdk npm](https://www.npmjs.com/package/@codex-native/sdk) + +Full API compatibility with the TypeScript SDK, but with native performance. However, only 33 weekly downloads — practically nobody uses it. + +### Known Issues + +- **Windows spawn EPERM** — CLI fails on Windows ([#7810](https://github.com/openai/codex/issues/7810)) +- **Zombie MCP processes** — 1,300+ zombies, 37GB memory leak ([#12491](https://github.com/openai/codex/issues/12491)) +- **Subagents experimental** — Gated behind `features.multi_agent` flag + +--- + +## 3. Gemini CLI SDK (`@google/gemini-cli-sdk`) + +### Architecture + +Monorepo with three packages: +- `@google/gemini-cli` — Bundled single executable (CLI) +- `@google/gemini-cli-core` — Core logic, API orchestration, tool execution +- `@google/gemini-cli-sdk` — Programmatic API layer over core + +**Key difference from Claude/Codex:** The Gemini SDK **does NOT spawn CLI as subprocess**. It uses `@google/gemini-cli-core` directly as a library. This is architecturally different — the SDK calls core functions in-process. + +### API Surface + +```typescript +// Agent-based API +const agent = new GeminiCliAgent(definition: LocalAgentDefinition); +// Includes: model config, tools, system instructions + +// Session management +const session = new GeminiCliSession(context: AgentLoopContext); + +// Activity monitoring +agent.onActivity((activity) => { ... }); +``` + +### Feature Comparison: SDK vs CLI Direct + +| Feature | CLI Direct | SDK | Notes | +|---------|-----------|-----|-------| +| MCP support | `config.toml` | Via core ToolRegistry | Same underlying system | +| Custom tools | Via MCP servers | Via ToolRegistry + custom definitions | SDK has more direct access | +| Model routing | Auto fallback | Via ModelConfig | Same capability | +| Hooks | Shell scripts | Programmatic callbacks | SDK advantage | +| Sandboxing | Built-in | Via SandboxManager | Same capability | +| Output format | `--output-format json/stream-json` | Typed events via callbacks | SDK provides typed events | +| Extensions | Plugin architecture | Same plugin system | Equivalent | +| Agent Skills | Custom skills | Custom skills | Equivalent | +| Performance | Baseline | **No subprocess — in-process** | **SDK is faster** | +| Abort support | Ctrl+C | Limited — aborted requests continue ([known issue](https://github.com/google-gemini/gemini-cli/issues/15539)) | CLI wins here | +| Checkpointing | Automatic snapshots | Via SDK session | Equivalent | + +### Maturity + +The SDK was introduced in v0.30.0. GitHub issue [#15539](https://github.com/google-gemini/gemini-cli/issues/15539) requesting a formal SDK is now **CLOSED as completed**. The core API surface is still evolving — `@google/gemini-cli-core` includes "robust compatibility measures" suggesting instability. + +--- + +## 4. Cross-SDK Comparison Matrix + +| Dimension | Claude Agent SDK | Codex SDK | Gemini CLI SDK | +|-----------|-----------------|-----------|----------------| +| **Architecture** | Spawns CLI subprocess | Spawns CLI subprocess | In-process (uses core directly) | +| **Startup overhead** | ~12s per query() | Unknown (similar pattern) | Minimal (no subprocess) | +| **CLI flag passthrough** | `extraArgs` for ANY flag | `config` for config flags | N/A (not subprocess-based) | +| **MCP support** | Full (stdio, SSE, HTTP, in-process) | Full (stdio, HTTP) | Full (via ToolRegistry) | +| **In-process tools** | `createSdkMcpServer()` | Custom tool registration | ToolRegistry | +| **Structured output** | JSON Schema | JSON Schema (Zod) | Zod schemas | +| **Agent teams** | CLI-only | N/A | N/A | +| **Subagents** | Programmatic + filesystem | Experimental | Via LocalAgentExecutor | +| **Streaming** | AsyncGenerator | AsyncGenerator events | onActivity callback | +| **Custom spawn** | `spawnClaudeCodeProcess` | Not exposed | N/A (no subprocess) | +| **Session resume** | Full (resume, fork) | Full (resumeThread) | Via GeminiCliSession | +| **Hooks** | Programmatic callbacks | Not documented | Programmatic callbacks | +| **License** | Proprietary | Open source (Apache 2.0) | Open source (Apache 2.0) | +| **npm weekly DL** | High (official Anthropic) | High (official OpenAI) | Medium (newer) | +| **Maturity** | Production (v0.2.81) | Production | Early (v0.30.0+) | + +--- + +## 5. Key Questions Answered + +### Q1: Does Claude Agent SDK support ALL CLI flags? + +**YES.** Via `extraArgs: Record` you can pass ANY arbitrary flag. Plus most important flags have dedicated typed options (`mcpServers`, `disallowedTools`, `allowedTools`, `permissionMode`, etc.). + +### Q2: Does Codex SDK expose all CLI capabilities? + +**Partially.** The `config` option can pass arbitrary config values, but not all CLI flags are exposed as typed options. The API surface is minimal compared to Claude's SDK. + +### Q3: Does Gemini CLI SDK expose all CLI capabilities? + +**Mostly.** Since it uses `@google/gemini-cli-core` directly (not subprocess), it has access to all internal APIs. But the public SDK surface is still maturing. + +### Q4: Is there a performance overhead? + +**Claude/Codex: YES — ~12s startup per query() call.** This is the CLI initialization time, not SDK overhead. Direct spawn has the same cost. + +**Gemini: NO additional overhead** — in-process architecture, no subprocess. + +### Q5: Can we pass arbitrary flags through the SDK? + +- **Claude:** YES, via `extraArgs` +- **Codex:** Partially, via `config` (maps to `--config key=value`) +- **Gemini:** N/A (not subprocess-based) + +### Q6: Does the SDK actually spawn the CLI? + +- **Claude:** YES — spawns bundled `cli.js` via `child_process` +- **Codex:** YES — spawns CLI and exchanges JSONL over stdin/stdout +- **Gemini:** NO — uses core library in-process + +### Q7: What happens when a new CLI flag is added? + +- **Claude:** `extraArgs` passes ANY flag through immediately. No SDK update needed. +- **Codex:** May need SDK update for new flags not covered by `config` +- **Gemini:** Core library update needed, but it's the same package ecosystem + +### Q8: Can we use SDK and direct CLI interchangeably? + +**YES.** They are not mutually exclusive. Use SDK for simple flows, CLI direct for advanced (Agent Teams, etc.). Both produce the same session files, use the same auth, same MCP servers. + +--- + +## 6. Verdict for Our Project (Claude Agent Teams UI) + +### What We Need + +1. **Agent Teams** (lead + teammates, stream-json, inbox messaging) — **CLI-only** +2. **MCP config passthrough** (`--mcp-config`, `--strict-mcp-config`) — **Both work** +3. **Disallowed tools** (`--disallowedTools`) — **Both work** +4. **stream-json stdin/stdout** — **SDK uses this internally, CLI direct also works** +5. **Custom spawn control** (Electron, process management) — **Both work** +6. **Long-running sessions** (teams run for hours) — **Both work, 12s overhead irrelevant** + +### Recommendation + +| Use Case | Approach | Confidence | +|----------|----------|------------| +| Agent Teams (lead + teammates) | **CLI direct spawn** (current) | 10/10 — SDK cannot do this | +| Solo agent mode | **Either works**, SDK is nicer | 9/10 | +| Future multi-provider support | **CLI direct for each** | 8/10 — more flexible | +| Subagent orchestration | **SDK preferred** (typed subagents) | 8/10 | + +### Final Assessment + +**The concern about SDKs being "less flexible" is UNFOUNDED for most use cases.** The SDKs provide typed access to everything the CLI does, plus extras (in-process MCP, programmatic hooks, structured output). The `extraArgs` option in Claude SDK means you're never blocked by missing typed options. + +**The concern about SDKs being "slower" is VALID but IRRELEVANT for long-running agents.** The ~12s startup overhead is the CLI itself, not the SDK wrapper. Direct spawn has the same cost. + +**The ONE real limitation: Agent Teams are CLI-only.** Since our core feature IS Agent Teams, we MUST use CLI direct for team management. This is not a limitation of "SDKs in general" — it's a specific architectural decision by Anthropic. + +### Hybrid Approach (Best of Both Worlds) + +``` +Agent Teams → CLI direct spawn (mandatory) +Solo agents → SDK query() (nicer API, typed, in-process MCP) +Subagents → SDK agents option (programmatic, isolated) +Multi-provider → CLI direct for each provider +``` + +Reliability: 9/10 +Confidence: 9/10 + +--- + +## Sources + +- [Claude Agent SDK TypeScript Reference](https://platform.claude.com/docs/en/agent-sdk/typescript) +- [Claude Code Features in SDK](https://platform.claude.com/docs/en/agent-sdk/claude-code-features) +- [Claude Agent SDK Overview](https://platform.claude.com/docs/en/agent-sdk/overview) +- [Claude Agent SDK MCP](https://platform.claude.com/docs/en/agent-sdk/mcp) +- [Claude Agent SDK Performance Issue #34](https://github.com/anthropics/claude-agent-sdk-typescript/issues/34) +- [Claude Agent SDK Custom Spawn #103](https://github.com/anthropics/claude-agent-sdk-typescript/issues/103) +- [Claude Agent SDK Pitfalls](https://liruifengv.com/posts/claude-agent-sdk-pitfalls-en/) +- [Claude Agent SDK vs CLI System Prompts](https://github.com/shanraisshan/claude-code-best-practice/blob/main/reports/claude-agent-sdk-vs-cli-system-prompts.md) +- [Claude Code vs Claude Agent SDK (Medium)](https://drlee.io/claude-code-vs-claude-agent-sdk-whats-the-difference-177971c442a9) +- [--disallowedTools MCP bug #12863](https://github.com/anthropics/claude-code/issues/12863) +- [Codex SDK Documentation](https://developers.openai.com/codex/sdk) +- [Codex CLI Documentation](https://developers.openai.com/codex/cli) +- [Codex MCP Support](https://developers.openai.com/codex/mcp) +- [@codex-native/sdk npm](https://www.npmjs.com/package/@codex-native/sdk) +- [Codex Zombie Process Bug #12491](https://github.com/openai/codex/issues/12491) +- [Gemini CLI SDK DeepWiki](https://deepwiki.com/google-gemini/gemini-cli/5.9-sdk-and-programmatic-api) +- [Gemini CLI Formal SDK Request #15539](https://github.com/google-gemini/gemini-cli/issues/15539) +- [Gemini CLI npm Package](https://geminicli.com/docs/npm/) +- [Making Claude Agents Run Faster](https://medium.com/@bayllama/making-your-agents-built-using-claude-agent-sdk-run-faster-2f2526a5cb42) +- [Building Agents with Claude Agent SDK (Anthropic)](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk)