obsidian-vault/personal/plans/balda-callee-prism-plan.md

Balda + Prism/Beads + Execution Broker + Callee + Codex

Обновлено: 2026-09-30 Статус: Virfield v2.0.0 опубликован. Этот план описывает целевую интеграцию Balda → Broker → VM → Runner/Callee; сквозная приёмка ещё не подтверждена. Текущий проект и runbook: personal/projects/virfield.

1. Цель

Balda принимает задачу в Mattermost, ведёт её состояние в Prism/Beads и запускает изолированное выполнение в одноразовой macOS VM.

Код, сборка, тесты и Xcode выполняются только внутри VM. Хост Mac управляет VM через Virfield, но не исполняет команды агента в основной системе.

Единственная целевая цепочка исполнения:

Mattermost
  → Balda
  → Execution Broker
  → Virfield на Mac
  → macOS VM
  → Callee workflow
  → Codex ACP sessions

Контур состояния задачи:

Balda
  → Prism adapter
  → bd
  → Dolt/Beads database

Обратный поток:

Codex
  → ACP result
  → Callee event
  → Broker event log
  → Balda
  → Prism/Beads + Mattermost

2. Подтверждённый статус и оставшаяся интеграция

Virfield v2.0.0 опубликован: Go daemon, leases/images, аутентифицированные HTTP/MCP, SSH isolation, tunnels и embedded console. Live golden/clone E2E и release CI прошли в объёме personal/projects/virfield. Установленные сервисы используют deployment вне checkout; публикация нового архива не обновляет runtime автоматически.

Для полной цепочки остаётся подтвердить:

• отдельные deployment и совместимость Execution Broker/Runner;
• доступ Broker к реализованному Virfield HTTP API: TLS/routing, credentials и SSH transport из контейнера;
• запуск Callee и обратный журнал событий до Balda;
• адаптер Balda → Prism/Beads;
• сквозной запуск Story → VM → build/test → отчёт с cleanup.

Статус остальных проектов и provider-конфигурация проверяются в их собственных источниках; релиз Virfield не является подтверждением их готовности.

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.

Аутентифицированный HTTP API /api/v1 и HTTP MCP /mcp реализованы; daemon слушает loopback. Для Broker остаются проверяемая сетевая доступность и integration contract. Произвольного 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:

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.

Минимальный запрос запуска:

{
  "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).

Минимальное событие:

{
  "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

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:

{
  "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.

Workspace и артефакты

Текущий recipe Virfield создаёт VM без shared host folders. Код, mutable workspace и Xcode build живут на локальном диске VM; перенос исходников/результатов — через scoped SSH и Git либо rsync/scp. Артефакты выгружаются до release lease и получают уникальный путь run_id/....

Добавление host mounts потребует отдельного решения по изоляции и проверки согласованности данных; это не часть принятого recipe.

Изменение других хостов

Задачи настройки 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. Как подключить Broker к реализованному Virfield API через TLS/routing и проверить lease/SSH contract из его окружения.

Требует проверки до 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 — реализовано и опубликовано

Релиз v2.0.0 опубликован 2026-09-30, commit ee3aa1d. Текущая карточка — personal/projects/virfield; команды и контракты принадлежат документации репозитория.

Реализованы единый Go control plane, SQLite journal, reconciliation, leases/idempotency, resource admission, image pipeline, scoped SSH, cleanup, CLI/MCP и embedded console. Лимит двух VM и неизвестные состояния обрабатываются явно; неопределённая мутация не повторяется автоматически. Personal SSH keys/PAT storage и client-side lifecycle fallback в текущей реализации отсутствуют.

Lume остаётся backend; используется закреплённый 0.5.3 с двумя проверенными исправлениями shutdown. Guest automation встроена и версионируется вместе с Go-кодом. Полный golden/clone E2E пройден на одном Mac; Linux/macOS CI и проверки переносимости/секретов прошли для release commit. Точные результаты и непринятый scope — в Verification.

Граница проектов и репозиториев — принятое решение

virfield и execution-broker — два независимых проекта. Их нельзя объединять в один репозиторий или один daemon.

Репозиторий virfield содержит host control plane: корневой Go module, cmd/virfieldd, cmd/virfield, cmd/virfield-mcp, cmd/virfield-lume, реализации в internal/, deployment в deploy/. Актуальная карта модулей — Architecture; отдельного каталога приложения v2 нет.

Целевая структура отдельного execution-broker (реализацию сверять в его репозитории):

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 /api/v1; текущие модели и маршруты — internal/domain, internal/httpapi, internal/client. Отдельная OpenAPI-спецификация Virfield в v2.0.0 не опубликована.
5. Общих Go-пакетов между репозиториями нет; совместимость обеспечивается API contract и contract tests.

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 остаётся правильной. Provider для Balda и профили исполнителей настраиваются в соответствующих проектах; конкретное назначение не фиксируется в плане Virfield.

Рекомендуемая раскладка:

• 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. Выполнено для Virfield: clone/start/stop/delete, SSH readiness и cleanup проверены live; повтор для полного Broker/Runner flow входит в сквозную приёмку.
2. Проверить передачу workspace/artifacts через Git/scoped SSH на локальный диск VM; shared host folders в recipe отсутствуют.
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: завершён 2026-09-30

Результат опубликован как v2.0.0: один владелец VM/images, durable jobs/events, API/CLI/MCP/UI, image automation и проверенная переносимая сборка. Выполненные задачи не остаются в backlog. Непринятые проверки перечислены в personal/projects/virfield и repository Verification.

Этап 3 — универсальный Runner

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

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

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. Создать Story из реального сообщения Mattermost.
2. Пройти specify/design/approval/implement/review/verify.
3. Собрать Xcode-проект и запустить тесты внутри VM.
4. Перезапустить Broker во время run и проверить восстановление.
5. Проверить terminal cleanup VM и доступность артефактов.

Результат: воспроизводимый end-to-end прогон без исполнения агентских команд на хосте.

Срок оставшихся этапов определяется после сверки текущего Broker/Runner и проверки Callee/Prism контрактов.

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/projects/virfield — текущий релиз, подтверждённый scope и каноническая документация.

• personal/tech/callee-prism — контракты Callee, ACP и Prism.