610 lines
34 KiB
Markdown
Executable File
610 lines
34 KiB
Markdown
Executable File
# Balda + Prism/Beads + Execution Broker + Callee + Codex
|
||
|
||
> Обновлено: 2026-09-29
|
||
> Статус: целевая архитектура зафиксирована; Broker и интеграции ещё не реализованы.
|
||
|
||
## 1. Цель
|
||
|
||
Balda принимает задачу в Mattermost, ведёт её состояние в Prism/Beads и запускает изолированное выполнение в одноразовой macOS VM.
|
||
|
||
Код, сборка, тесты и Xcode выполняются только внутри VM. Хост Mac управляет VM через Virfield, но не исполняет команды агента в основной системе.
|
||
|
||
Единственная целевая цепочка исполнения:
|
||
|
||
```text
|
||
Mattermost
|
||
→ Balda
|
||
→ Execution Broker
|
||
→ Virfield на Mac
|
||
→ macOS VM
|
||
→ Callee workflow
|
||
→ Codex ACP sessions
|
||
```
|
||
|
||
Контур состояния задачи:
|
||
|
||
```text
|
||
Balda
|
||
→ Prism adapter
|
||
→ bd
|
||
→ Dolt/Beads database
|
||
```
|
||
|
||
Обратный поток:
|
||
|
||
```text
|
||
Codex
|
||
→ ACP result
|
||
→ Callee event
|
||
→ Broker event log
|
||
→ Balda
|
||
→ Prism/Beads + Mattermost
|
||
```
|
||
|
||
## 2. Что уже есть
|
||
|
||
### Подтверждено
|
||
|
||
1. Balda работает в Docker на Mac и отвечает в Mattermost.
|
||
2. Mattermost-сервер остаётся на Kraken; Balda подключается к нему с Mac.
|
||
3. Obsidian MCP доступен Balda по `http://host.docker.internal:3101/sse`.
|
||
4. Virfield MCP работает на хостовом Mac и умеет подготовить VM: clone golden image, start, wait for IP/SSH, create tunnel.
|
||
5. Host Codex и Claude уже подключены к Virfield MCP.
|
||
|
||
### Текущая конфигурация Balda
|
||
|
||
- основной provider: DeepSeek через OpenAI-compatible API;
|
||
- `permissions.mode: allow_all`;
|
||
- `workspace.mode: off`;
|
||
- Virfield в Balda не подключён;
|
||
- Callee CLI и описания агентов находятся в окружении Balda по текущему сетапу, но целевой запуск Callee должен происходить внутри VM.
|
||
|
||
### Чего пока нет
|
||
|
||
- Execution Broker;
|
||
- сетевого API управления Virfield для Broker;
|
||
- VM runner для управляемого запуска Callee;
|
||
- обратного журнала событий Callee → Balda;
|
||
- адаптера Balda → Prism/Beads;
|
||
- подтверждённого сквозного запуска Story → VM → build/test → отчёт.
|
||
|
||
## 3. Владельцы ответственности
|
||
|
||
### Balda — оркестратор верхнего уровня
|
||
|
||
Balda:
|
||
|
||
- принимает задачу и уточнения из Mattermost;
|
||
- создаёт и обновляет Story в Prism/Beads;
|
||
- выбирает разрешённый workflow по его идентификатору;
|
||
- запускает выполнение через Broker;
|
||
- показывает запросы Human и итог пользователю.
|
||
|
||
Balda не управляет процессами внутри VM напрямую. Она работает только через контракты Prism adapter и Execution Broker.
|
||
|
||
### Prism adapter + Beads — долговременное состояние
|
||
|
||
Prism adapter принадлежит контуру Balda и физически может быть отдельным sidecar-контейнером.
|
||
|
||
Он:
|
||
|
||
- предоставляет Balda узкие операции Story/Task/phase;
|
||
- вызывает `bd`;
|
||
- подключается к Dolt/Beads database в соседнем контейнере;
|
||
- обеспечивает идемпотентную запись событий Broker;
|
||
- остаётся единственным писателем предметного состояния задачи.
|
||
|
||
Broker, Callee и Codex не пишут в Beads напрямую. Они возвращают факты выполнения, а Balda решает, как отразить их в Story.
|
||
|
||
### Execution Broker — инфраструктурный исполнитель
|
||
|
||
Broker — отдельный проект и отдельный репозиторий `execution-broker`. В production он живёт отдельным sidecar-контейнером рядом с Balda.
|
||
|
||
Он:
|
||
|
||
- получает от Balda команду запуска;
|
||
- арендует VM через Virfield;
|
||
- запускает VM runner и Callee;
|
||
- хранит техническое состояние run и журнал событий;
|
||
- передаёт ввод, отмену и ссылки на артефакты.
|
||
|
||
Broker не выбирает workflow, не исполняет его граф и не меняет Prism/Beads.
|
||
|
||
### Virfield — граница управления хостом
|
||
|
||
Virfield работает на Mac-хосте и владеет жизненным циклом VM:
|
||
|
||
- clone/start/stop/delete;
|
||
- IP и SSH readiness;
|
||
- сетевые туннели;
|
||
- lease и принудительная уборка VM.
|
||
|
||
Для Broker нужен узкий аутентифицированный HTTP API или HTTP MCP-обёртка над этими операциями. Произвольного host shell в этом API нет.
|
||
|
||
### Callee и Codex — выполнение внутри VM
|
||
|
||
Callee исполняет workflow: фазы, ветвления, циклы, Human-паузы и запуск ролей.
|
||
|
||
`implementer`, `reviewer`, `verifier` — роли Callee. Каждая роль запускает новую Codex ACP-сессию с отдельным prompt и контекстом.
|
||
|
||
Codex изменяет код, запускает `xcodebuild`, тесты и другие команды внутри VM. Codex не запускает Callee и не управляет Story.
|
||
|
||
## 4. Prism и prism-callee
|
||
|
||
Официальный `prism-callee` — плагин к coding-agent host. В штатной схеме он делает coding agent владельцем Beads и запускателем Callee:
|
||
|
||
```text
|
||
Codex → prism-callee skill → Callee → дочерние Codex sessions
|
||
```
|
||
|
||
Эта штатная топология не является целевой, потому что верхним оркестратором должен оставаться Balda.
|
||
|
||
В целевой схеме используются отдельно:
|
||
|
||
- lifecycle и правила Prism — как основа skill/адаптера Balda;
|
||
- Callee workflow pack — как версионируемые workflow-файлы внутри VM;
|
||
- Beads — через отдельный Prism adapter;
|
||
- Codex — только как исполнитель ролей Callee.
|
||
|
||
До реализации требуется проверить, какие части официального плагина можно импортировать без изменений, а какие нужно адаптировать для Balda.
|
||
|
||
## 5. Прямой data flow
|
||
|
||
1. Пользователь ставит задачу Balda в Mattermost.
|
||
2. Balda через Prism adapter создаёт Story и получает `story_id`.
|
||
3. Balda выбирает `workflow_id` из статического allowlist и вызывает `execution_start`.
|
||
4. Broker просит Virfield создать VM, затем запускает внутри неё VM runner и Callee.
|
||
5. Callee выполняет граф и для каждой Role запускает локальный Codex через ACP stdio.
|
||
|
||
Минимальный запрос запуска:
|
||
|
||
```json
|
||
{
|
||
"idempotency_key": "story:bd-42:attempt:1",
|
||
"story_id": "bd-42",
|
||
"workflow_id": "prism/story",
|
||
"workflow_version": "pinned-git-sha",
|
||
"repository": "git@host:org/repo.git",
|
||
"revision": "main",
|
||
"vm_template": "macos-27-golden",
|
||
"task": "Добавить CSV export"
|
||
}
|
||
```
|
||
|
||
Broker возвращает `run_id` сразу после надёжной записи команды. Подготовка VM продолжается асинхронно.
|
||
|
||
## 6. Обратный data flow
|
||
|
||
1. Codex возвращает результат роли в Callee по ACP.
|
||
2. Callee переводит workflow в следующее состояние и отдаёт структурированное событие VM runner.
|
||
3. VM runner передаёт событие Broker; Broker сохраняет его до ответа Balda.
|
||
4. Balda читает события через `execution_events(run_id, after_event_id)` и подтверждает курсор.
|
||
5. Balda обновляет Story через Prism adapter и публикует значимые изменения в Mattermost.
|
||
|
||
События доставляются как минимум один раз. Повторная доставка безопасна благодаря уникальному `(run_id, event_id)`.
|
||
|
||
Минимальное событие:
|
||
|
||
```json
|
||
{
|
||
"event_id": 17,
|
||
"run_id": "run-123",
|
||
"story_id": "bd-42",
|
||
"type": "role_completed",
|
||
"phase": "review",
|
||
"role": "reviewer",
|
||
"status": "passed",
|
||
"summary": "Tests pass",
|
||
"artifacts": [
|
||
{"kind": "git_commit", "ref": "abc123"},
|
||
{"kind": "xcresult", "ref": "artifact://run-123/tests"}
|
||
]
|
||
}
|
||
```
|
||
|
||
Тяжёлые логи и `.xcresult` не помещаются в журнал. Broker хранит только ссылки, checksum, размер и срок жизни.
|
||
|
||
## 7. Human approval
|
||
|
||
1. Callee доходит до Human node и приостанавливает workflow.
|
||
2. VM runner отправляет `human_required` с вопросом и вариантами.
|
||
3. Broker фиксирует состояние `waiting_human`.
|
||
4. Balda показывает вопрос в Mattermost и получает ответ в том же session/topic.
|
||
5. Balda вызывает `execution_respond`; Broker доставляет ответ в конкретный paused run.
|
||
|
||
Связка обязательна: `chat_id/topic_id ↔ story_id ↔ run_id ↔ human_request_id`.
|
||
|
||
Ответ должен быть идемпотентным: повторный `human_request_id` не возобновляет workflow дважды.
|
||
|
||
## 8. Execution Broker: контракт
|
||
|
||
### Где живёт
|
||
|
||
Отдельный контейнер в одном Docker network с Balda. У Broker собственный persistent volume с SQLite.
|
||
|
||
Northbound: HTTP MCP для Balda.
|
||
Southbound: узкий HTTP API Virfield и SSH к выданной VM.
|
||
Внутри VM: VM runner → Callee → Codex ACP stdio.
|
||
|
||
### MCP tools
|
||
|
||
1. `execution_start(request) → run_id`
|
||
2. `execution_status(run_id) → state, phase, last_event_id`
|
||
3. `execution_events(run_id, after_event_id) → events, next_cursor`
|
||
4. `execution_respond(run_id, human_request_id, answer)`
|
||
5. `execution_cancel(run_id, reason)` и `execution_artifacts(run_id)`
|
||
|
||
### Состояния run
|
||
|
||
```text
|
||
accepted
|
||
→ provisioning
|
||
→ booting
|
||
→ running
|
||
→ waiting_human
|
||
→ running
|
||
→ succeeded | failed | canceled | expired
|
||
```
|
||
|
||
Каждый переход записывается транзакционно вместе с событием. После рестарта Broker продолжает незавершённые run или переводит их в явно диагностируемое состояние.
|
||
|
||
### Внутреннее состояние Broker
|
||
|
||
Broker хранит только технические данные:
|
||
|
||
- `run_id`, `story_id`, idempotency key;
|
||
- VM id, IP, lease deadline;
|
||
- workflow id/version и process/session id;
|
||
- event cursor, terminal status и error code;
|
||
- artifact references и cleanup status.
|
||
|
||
### VM runner
|
||
|
||
Нужен небольшой процесс внутри образа VM. Он отделяет Broker от консольного формата Callee.
|
||
|
||
Runner:
|
||
|
||
- проверяет входной manifest и allowlist workflow;
|
||
- запускает Callee в рабочей директории репозитория;
|
||
- преобразует lifecycle/output в стабильные JSON events;
|
||
- принимает cancel и Human response;
|
||
- возвращает terminal result и artifact manifest.
|
||
|
||
Broker не должен парсить человекочитаемый ANSI/TTY-вывод Callee. Если Callee уже имеет стабильный machine-readable API, runner становится тонким адаптером.
|
||
|
||
## 9. Execution workers и распределение ресурсов
|
||
|
||
Broker планирует не только macOS VM. Все среды исполняют один versioned Runner protocol, но имеют разные `runtime_class`:
|
||
|
||
- `linux-container` — обычный код, CLI, Docker builds и инфраструктурная автоматизация;
|
||
- `macos-vm` — Xcode, macOS APIs, GUI и UI tests;
|
||
- `remote-host` — изменение конкретного хоста после Human approval.
|
||
|
||
Минимальный WorkerSpec:
|
||
|
||
```json
|
||
{
|
||
"runtime_class": "macos-vm",
|
||
"worker_profile": "xcode-27",
|
||
"agent_profile": "codex-default",
|
||
"workflow_id": "prism/story",
|
||
"repository": "git@host:org/repo.git",
|
||
"revision": "main"
|
||
}
|
||
```
|
||
|
||
### Параллельные задачи
|
||
|
||
Balda поддерживает несколько независимых chat sessions. Turns внутри одной session сериализуются, разные sessions могут работать параллельно.
|
||
|
||
Callee поддерживает `Parallel`, но это fan-out Role visits внутри одного workflow. VM создаёт и распределяет Broker, не Balda и не Callee.
|
||
|
||
Политика пула:
|
||
|
||
1. Одна изменяющая macOS Story получает одну эксклюзивную VM.
|
||
2. Implementer, reviewer и verifier используют ту же VM, но свежие ACP-сессии.
|
||
3. Отдельная VM на каждый Role не создаётся.
|
||
4. Одновременно работают максимум две macOS VM; остальные run стоят в очереди.
|
||
5. Linux containers масштабируются отдельно и не занимают macOS VM slots.
|
||
|
||
Параллельные read-only роли могут работать в одной VM. Параллельные изменения получают отдельные Git worktrees; запись нескольких агентов в один checkout запрещена политикой Runner.
|
||
|
||
Ограничение в две macOS VM задаёт Apple Virtualization.framework, а не Balda. Практический лимит дополнительно зависит от RAM и CPU.
|
||
|
||
## 10. Изоляция, shared folder и секреты
|
||
|
||
Основная граница безопасности — одноразовая macOS VM.
|
||
|
||
- исходный проект клонируется в VM без host bind mounts;
|
||
- Codex, Callee, Xcode и тесты работают внутри VM;
|
||
- Broker получает только scoped SSH key для конкретной VM;
|
||
- Git credentials выдаются на один репозиторий и ограниченный срок;
|
||
- VM удаляется после выгрузки результатов или по lease timeout.
|
||
|
||
Хостовый Virfield API разрешает только операции жизненного цикла VM. Balda и Broker не получают `docker.sock`, пользовательский `~/.ssh` или произвольный shell на Mac.
|
||
|
||
### Shared folder Lume
|
||
|
||
Lume монтирует shared folder через virtiofs. Изменения содержимого должны появляться динамически; Lume также умеет добавлять folder к уже запущенной VM без reboot/remount.
|
||
|
||
Для mutable workspace и Xcode build shared folder не считается надёжным источником истины. В текущем Virfield уже потребовались `sudo purge` и уникальные DerivedData snapshots из-за stale guest cache.
|
||
|
||
Рабочий контракт:
|
||
|
||
- репозиторий клонируется на локальный диск VM;
|
||
- обновления передаются через Git или `rsync/scp`;
|
||
- shared folder используется для immutable inputs и выгрузки artifacts;
|
||
- каждый набор artifacts получает уникальный путь `run_id/...`;
|
||
- Xcode не собирает проект непосредственно из `/Volumes/My Shared Files`.
|
||
|
||
### Изменение других хостов
|
||
|
||
Задачи настройки Mac, Kraken, TrueNAS и других машин используют `runtime_class: remote-host`.
|
||
|
||
1. Agent в контейнере формирует plan и выполняет read-only preflight.
|
||
2. Balda показывает точный diff действий и запрашивает Human approval.
|
||
3. Broker выдаёт capability lease на конкретные host, identity, operations и TTL 15–30 минут.
|
||
4. Runner применяет изменения через dedicated service account или установленный host-runner.
|
||
5. Verify, audit log и rollback закрывают lease.
|
||
|
||
Личные ключи из пользовательского `~/.ssh` не передаются. Для managed host используется небольшой Go host-runner. Для первичного bootstrap допускается отдельный SSH account с short-lived certificate и ограниченным `sudo`.
|
||
|
||
Изменения самого Mac выполняет отдельный native launchd helper. Он принимает подписанный capability lease; Balda и модель не получают постоянный host shell.
|
||
|
||
## 11. Неподтверждённое
|
||
|
||
### Блокирует прототип
|
||
|
||
1. Есть ли у Callee стабильный machine-readable event stream и программный resume Human node.
|
||
2. Можно ли запустить workflow pack `prism/story` отдельно от stock plugin host.
|
||
3. Как Codex ACP получает workspace/cwd и сохраняет его между Role visits.
|
||
4. Как передавать cancel в Callee без повреждения terminal result.
|
||
5. Какой минимальный Virfield API можно безопасно открыть Broker.
|
||
|
||
### Требует проверки до production
|
||
|
||
- установка и авторизация Codex внутри golden VM;
|
||
- доступность Dolt/Beads из Prism adapter после рестартов;
|
||
- формат и размер Xcode артефактов;
|
||
- восстановление Broker после падения во время `waiting_human`;
|
||
- параллельные Story и лимиты VM/CPU/RAM на Mac.
|
||
|
||
## 12. Варианты
|
||
|
||
### A. Sidecar Broker + VM runner — выбран
|
||
|
||
Balda остаётся оркестратором, Broker изолирует инфраструктуру, Callee владеет workflow, Codex работает в VM. Это целевая схема.
|
||
|
||
### B. Broker как host daemon
|
||
|
||
Меньше сетевых переходов к Virfield и SSH, но Broker получает более широкую поверхность хоста. Использовать только если контейнерный sidecar не может надёжно управлять VM.
|
||
|
||
### C. Stock prism-callee plugin
|
||
|
||
`Codex → plugin → Callee → Codex`. Быстрее для проверки Prism, но Balda перестаёт быть владельцем lifecycle. Подходит как временный reference test, не как production topology.
|
||
|
||
### D. Native remote ACP
|
||
|
||
Будущая transport abstraction в `runtime + acpagent` позволит Balda или Callee подключаться к ACP по WebSocket/Streamable HTTP. Она может заменить SSH-транспорт, но не заменяет Broker, VM lifecycle, durable events и cleanup.
|
||
|
||
## 13. Аудит Virfield и целевая версия v2
|
||
|
||
### Что существует сейчас
|
||
|
||
Virfield — TypeScript/Node.js приложение:
|
||
|
||
- Express + WebSocket backend;
|
||
- React/Vite Web UI;
|
||
- SQLite;
|
||
- отдельный stdio MCP server;
|
||
- shell/Python provisioning scripts.
|
||
|
||
Web UI уже реализован. TypeScript typecheck проходит. Собственной automated test suite практически нет.
|
||
|
||
### Подтверждённые архитектурные проблемы
|
||
|
||
1. Состояние VM определяется одновременно Lume API, Lume CLI, SQLite, JSON-файлами, PID и in-memory maps.
|
||
2. REST и MCP дублируют orchestration; MCP вызывает REST, а при ошибке обходит его и управляет Lume напрямую.
|
||
3. Recovery основан на `pgrep`, `pkill`, PID probing и ручном склеивании stale states.
|
||
4. Virfield читает личные SSH keys, имеет password fallback `lume`, хранит GitHub PAT в SQLite и предоставляет широкий `vm_ssh_exec`.
|
||
5. Long-running jobs частично живут только в памяти и теряют нормальную управляемость после restart.
|
||
|
||
### Решение: переписать control plane, не Lume
|
||
|
||
Lume остаётся hypervisor/backend. Проверенные provisioning scripts временно сохраняются как versioned jobs и постепенно заменяются только при наличии тестов.
|
||
|
||
Virfield v2 состоит из пяти частей:
|
||
|
||
1. `virfieldd` на Go — единственный владелец SQLite, Lume adapter, VM leases, jobs, events и cleanup; запускается через `launchd`.
|
||
2. Image Manager — модуль `virfieldd` для download/pull/build/promote golden images; отдельный daemon ему не нужен.
|
||
3. Web UI — отдельный API client на embedded HTML/HTMX или простом JavaScript без Node toolchain.
|
||
4. `virfield-mcp` на Go — тонкий stdio/HTTP adapter; не обращается к Lume или SQLite напрямую.
|
||
5. Execution Broker и Runner на Go — отдельный execution-контур рядом с Balda и внутри workers.
|
||
|
||
Один Lume adapter скрывает различия HTTP/CLI. UI, MCP и Broker используют только versioned API `virfieldd`.
|
||
|
||
Оценка: Virfield v2 MVP — 7–12 рабочих дней; Broker/Runner — 5–10 дней; UI migration и hardening — ещё 5–8 дней.
|
||
|
||
### Граница проектов и репозиториев — принятое решение
|
||
|
||
`virfield` и `execution-broker` — два независимых проекта. Их нельзя объединять в один репозиторий или один daemon.
|
||
|
||
Репозиторий `virfield` содержит только host control plane:
|
||
|
||
```text
|
||
cmd/virfieldd
|
||
cmd/virfieldctl
|
||
cmd/virfield-mcp
|
||
internal/lume
|
||
internal/images
|
||
internal/leases
|
||
internal/jobs
|
||
web/
|
||
api/
|
||
```
|
||
|
||
Новый репозиторий `execution-broker` содержит execution plane:
|
||
|
||
```text
|
||
cmd/broker
|
||
cmd/runner
|
||
cmd/host-runner
|
||
internal/scheduler
|
||
internal/execution
|
||
internal/events
|
||
internal/drivers/virfield
|
||
internal/drivers/container
|
||
internal/drivers/remotehost
|
||
api/
|
||
```
|
||
|
||
Границы ответственности:
|
||
|
||
1. `virfield` управляет VM, images, leases и host-level cleanup; он ничего не знает о Callee, Prism, Beads и model providers.
|
||
2. `execution-broker` выбирает execution class, запускает Runner/Callee, управляет agent profiles и хранит run event log; он не управляет Lume напрямую.
|
||
3. `balda` вызывает Broker по MCP и отражает события в Prism/Beads; Virfield напрямую из Balda не вызывается.
|
||
4. `execution-broker → virfieldd` использует versioned authenticated HTTP API, описанный OpenAPI.
|
||
5. Общих Go-пакетов между репозиториями нет; совместимость обеспечивается API contract и contract tests.
|
||
|
||
Старый репозиторий/компонент `agents-bridge` не развивается и не переиспользуется для новой системы. Название `execution-broker` выбрано специально, чтобы не смешивать новый scheduler/event broker со старым SSH/MCP-мостом.
|
||
|
||
## 14. Agent profiles и модельная политика
|
||
|
||
Broker и Runner не содержат vendor-specific workflow logic. Run выбирает `agent_profile` из статического allowlist.
|
||
|
||
Для Callee напрямую подтверждены Codex, Claude, Copilot, Grok, OpenCode и Cursor. Gemini и GLM подключаются через `generic_acp` или отдельный ACP adapter и считаются неподтверждёнными до integration test.
|
||
|
||
Worker image содержит Runner, Callee и нужные provider binaries. Credentials выбранного provider выдаются только на срок run. Node отсутствует в Virfield/Broker control plane; он допускается внутри специализированного worker image, если конкретный agent CLI без него не работает.
|
||
|
||
### Распределение моделей
|
||
|
||
Схема `Balda → Callee → coding agent` остаётся правильной. Текущее назначение DeepSeek единственным оркестратором не оптимально: Balda использует один app-scoped provider для всех sessions.
|
||
|
||
Рекомендуемая раскладка:
|
||
|
||
- Balda — надёжное понимание запроса, выбор workflow, управление state и Human interaction;
|
||
- specify/design/review — сильная reasoning-модель;
|
||
- implementation — Codex или другой сильный coding agent;
|
||
- build/test/SSH apply — детерминированные Script/Runner operations;
|
||
- дешёвая модель — routing, summarization и простая диагностика.
|
||
|
||
DeepSeek подходит для ограниченного routing и простых операций с жёсткими tool schemas. Он не принимает самостоятельные решения о privileged SSH-командах и сложной архитектуре.
|
||
|
||
Оптимизация стоимости строится на deterministic routing, token/run budgets, bounded retries и escalation: после повторной неудачи задача повышает model tier, а не повторяет дешёвую модель бесконечно.
|
||
|
||
## 15. Pitfalls
|
||
|
||
### Архитектура
|
||
|
||
1. Смешивание двух топологий: stock `Codex → Callee` и целевой `Balda → Broker → Callee`.
|
||
2. Перенос workflow-логики в Broker превращает его во второй оркестратор.
|
||
3. Прямая запись Broker/Callee/Codex в Beads создаёт несколько владельцев состояния.
|
||
4. Запуск Callee вне VM переносит Script nodes и часть команд на хост.
|
||
5. Парсинг консольного вывода Callee вместо стабильного event protocol ломает resume и диагностику.
|
||
|
||
### Надёжность
|
||
|
||
1. Потеря события между Callee и Balda без durable event log.
|
||
2. Двойной запуск VM без idempotency key.
|
||
3. Повторный Human response возобновляет workflow дважды.
|
||
4. Падение Broker оставляет VM без lease и cleanup.
|
||
5. Большие build-логи забивают SQLite или MCP-ответы.
|
||
|
||
### Безопасность
|
||
|
||
1. Непроверенный `workflow_id`, repository URL или revision превращается в выполнение произвольного ввода.
|
||
2. Общий SSH/Git credential между VM расширяет последствия компрометации.
|
||
3. Секреты в prompt, events или build logs попадают в Mattermost/Beads.
|
||
4. Host path, переданный как ACP cwd, не существует или указывает не туда внутри VM.
|
||
5. VM с доступом в локальную сеть может атаковать хостовые сервисы; egress и host API нужно ограничить.
|
||
|
||
### Исполнение и ресурсы
|
||
|
||
1. Mutable build через virtiofs может прочитать stale content; workspace должен жить на локальном диске worker.
|
||
2. Более двух активных macOS VM невозможны; Broker обязан иметь очередь и admission control.
|
||
3. Parallel Callee roles, пишущие в один checkout, создают file conflicts даже внутри одной VM.
|
||
4. Свободный provider command или agent-generated `cmd` превращает профиль в arbitrary code execution.
|
||
5. Установка всех provider credentials в один golden image нарушает isolation и усложняет rotation.
|
||
|
||
## 16. План реализации
|
||
|
||
### Этап 1 — live spike контрактов, 1–2 дня
|
||
|
||
1. Запустить Virfield и Lume и проверить clone/start/stop/delete без fallback paths.
|
||
2. Проверить stale-cache сценарии shared folder и зафиксировать Git/rsync contract.
|
||
3. Запустить один Callee workflow вручную внутри тестовой VM.
|
||
4. Проверить Codex ACP, Human pause/resume, cancel и terminal result.
|
||
5. Принять versioned contracts Virfield API и VM Runner.
|
||
|
||
Результат: фактические runtime-контракты без предположений.
|
||
|
||
### Этап 2 — Virfield v2 core, 7–12 дней
|
||
|
||
1. Реализовать `virfieldd` и единую SQLite job/event model.
|
||
2. Реализовать один Lume adapter и reconciliation loop.
|
||
3. Добавить leases, idempotency, quotas, audit и cleanup.
|
||
4. Подключить существующие image/provisioning scripts как jobs.
|
||
5. Реализовать Go CLI/MCP adapters и минимальный Web UI.
|
||
|
||
Результат: один надёжный владелец VM и images без Node runtime.
|
||
|
||
### Этап 3 — универсальный Runner, 2–4 дня
|
||
|
||
1. Описать versioned JSON protocol command/event.
|
||
2. Реализовать start, events, Human response и cancel.
|
||
3. Подключить Callee workflow pack и allowlisted agent profiles.
|
||
4. Сформировать artifact manifest для git diff, commit, logs и `.xcresult`.
|
||
5. Добавить terminal result и гарантированное завершение дочерних процессов.
|
||
|
||
Результат: один протокол запускает workflow в VM или container и возвращает структурированные события.
|
||
|
||
### Этап 4 — Broker MVP, 3–6 дней
|
||
|
||
1. Реализовать SQLite schema для runs, events, responses и artifacts.
|
||
2. Реализовать state machine и транзакционный event journal.
|
||
3. Подключить Virfield API, container driver и Runner transport.
|
||
4. Опубликовать MCP tools из §8.
|
||
5. Добавить restart recovery, lease renewal и cleanup worker.
|
||
|
||
Результат: Balda управляет долговечным run через HTTP MCP.
|
||
|
||
### Этап 5 — Balda + Prism, 2–4 дня
|
||
|
||
1. Подключить Broker MCP к runtime Balda.
|
||
2. Развернуть Prism adapter и Dolt/Beads container.
|
||
3. Реализовать отображение events → Story phases.
|
||
4. Связать Human request с Mattermost session/topic.
|
||
5. Сформировать финальный отчёт Result/Artifacts/Confidence/Next action.
|
||
|
||
Результат: Story ведётся в Beads, выполнение и approvals видны в Mattermost.
|
||
|
||
### Этап 6 — сквозная приёмка, 1–2 дня
|
||
|
||
1. Создать Story из реального сообщения Mattermost.
|
||
2. Пройти specify/design/approval/implement/review/verify.
|
||
3. Собрать Xcode-проект и запустить тесты внутри VM.
|
||
4. Перезапустить Broker во время run и проверить восстановление.
|
||
5. Проверить terminal cleanup VM и доступность артефактов.
|
||
|
||
Результат: воспроизводимый end-to-end прогон без исполнения агентских команд на хосте.
|
||
|
||
Оценка после spike: рабочий end-to-end MVP — 17–30 рабочих дней. Срок сильнее всего зависит от Callee machine API, Lume reconciliation и переноса Web UI.
|
||
|
||
## 17. Критерии готовности
|
||
|
||
1. Balda создаёт одну Story и один idempotent run из сообщения Mattermost.
|
||
2. Все команды Codex, Xcode build и тесты исполняются внутри leased VM.
|
||
3. Callee управляет ролями и циклами; Broker не содержит workflow policy.
|
||
4. После рестарта Balda или Broker прогресс восстанавливается без двойного запуска.
|
||
5. Terminal run обновляет Beads, публикует артефакты и удаляет VM по lease policy.
|
||
6. Linux-задачи исполняются в containers и не занимают macOS VM slots.
|
||
7. Remote-host задача не использует личные SSH keys и не выполняется без capability lease.
|
||
8. UI и MCP показывают одно состояние из `virfieldd`, без собственных fallback orchestration paths.
|
||
|
||
## Связанные заметки
|
||
|
||
- [[personal/tech/callee-prism]] — контракты Callee, ACP и Prism.
|
||
- [[personal/tech/agents-bridge]] — предыдущий мост; не часть целевой схемы.
|
||
- [[personal/tech/balda-executor-mcp]] — предыдущий исполнитель; не часть целевой схемы.
|
||
- [[personal/plans/balda-mm-phase4-agents]] — история предыдущей интеграции.
|