obsidian-vault/personal/projects/balda/balda.md

Balda (Валера) — AI Worker Bot

Актуальный статус — 2026-10-03. Mattermost-интеграция PR #8 уже в upstream. PR #12 по маршрутизации webhook открыт на 73e02156: 8/8 GitHub checks прошли; повторное ревью после исправления запрошенных изменений ещё ожидается. Balda запущена из чистого текущего HEAD PR 73e02156, и хеш бинарника в контейнере совпадает с собранным артефактом. Ревьюер запросил изменения в PR #12 из-за 404 при временном сбое lookup session. Исправление 73e02156 уже отправлено: теперь ответ 503, добавлен HTTP-тест; локальные race tests и lint прошли, все 8 checks нового HEAD прошли. До повторного сквозного прогона merge/release — NO-GO. Прежний вывод о другом SHA был ошибкой: d094943b относился к внешнему репозиторию Broker, а deepseekfix был старой меткой образа. Локальных правок кода Balda в текущем бинарнике нет; новый сквозной прогон ещё нужен. Приёмочный Broker run run-fbe2cb459fe2965554402aba1bd5fcd0 прошёл; Mattermost отправил апрув и финал в исходный тред. Результат 4dafb9d был доставлен в go-cli-test вручную через Broker API: Balda пропустила автоматическую публикацию. Broker теперь сам проверяет commit/quality/bundle без обязательного SHA от Balda; webhook и плагин rc.19 требуют публикацию до закрытия Story. Новый end-to-end прогон ещё не проведён. Общий release — NO-GO. Детали и текущие проверки: personal/plans/balda-callee-prism-plan. Ниже сохранена историческая документация; старые статусы PR и конфигурации не являются текущими.

Аналог Hermes. Go-сервис: берёт задачи из чата (Telegram или Zulip), запускает AI CLI и отвечает.

Репо

• Upstream: https://github.com/baldaworks/balda (старое имя normahq/balda — редирект)
• Fork: https://github.com/mallexxx/balda
• Local: ~/Developer/balda
• Ветка: feat/mattermost-channel (PR #8, OPEN, 8/8 CI, MERGEABLE)

🔴 Два репозитория — не путать

Репо	Что там	PR
baldaworks/balda	сам бот, транспорты (Mattermost, Zulip)	#8 Mattermost, OPEN · #1 Zulip, merged
normahq/runtime	библиотека рантайма (agentfactory, hostedagent)	#5 фикс MCP-тулинга, OPEN · CHANGES_REQUESTED (3 дефекта, план — personal/plans/runtime-pr5-toolset-dedup-review-fixes) · #4 OpenAI tool_calls, OPEN (4 дефекта закрыты, personal/plans/runtime-pr4-openai-toolcalls-fixes)

Форки: mallexxx/balda, mallexxx/runtime — разные, клоны тоже разные. Детали по runtime-PR → personal/projects/balda/balda-valera.

⚠️ PR из форка: CI не запускается сам. GitHub требует ручного подтверждения workflows владельцем репо («Approve and run workflows») → mergeStateStatus: UNSTABLE при check-runs: total_count 0. Это не поломка PR.

Архитектура

• NATS JetStream — event bus (embedded)
• SQLite — состояние (owner, sessions, tasks)
• Telegram — через polling или webhook
• Zulip — через outgoing webhook bot
• Providers: codex, opencode, copilot, gemini, claude (ACP protocol)

Zulip Integration

Полностью реализована. Webhook-based (не polling).
Тип бота: Outgoing webhook (не Generic bot).

Credentials (zulip.qentra.top)

• Bot email: balda-bot@zulip.qentra.top
• API key: AtC9FypdIl6F0hNICW0lcOzehrVrWhPr
• Server URL: https://zulip.qentra.top
• Webhook token: берётся из Settings → Bots → balda-bot → Edit → Token

Config (env vars)

BALDA_ZULIP_BOT_EMAIL=balda-bot@zulip.qentra.top
BALDA_ZULIP_API_KEY=AtC9FypdIl6F0hNICW0lcOzehrVrWhPr
BALDA_ZULIP_SERVER_URL=https://zulip.qentra.top
BALDA_ZULIP_WEBHOOK_TOKEN=<из настроек бота>
BALDA_ZULIP_WEBHOOK_ENABLED=true

Webhook setup в Zulip

1. Settings → Bots → balda-bot → Edit
2. Bot type: Outgoing webhook
3. Endpoint URL: http://<host>:8090/zulip/webhook
4. Скопировать token → BALDA_ZULIP_WEBHOOK_TOKEN

Авторизация

После запуска написать боту в DM:

/start owner=<BALDA_AUTH_TOKEN>

Реализованные команды (Telegram parity)

Команда	Статус
/start owner=<token>	✅
/start invite=<token>	✅
/goal <objective> / /goal clear	✅
/topic	✅ (создаёт сессию для нового топика)
/user add <email>	✅
/user list	✅ (с инвайтами + expiry)
Typing indicator	✅ (isDM-aware: true в DM, false в стримах)
plan_updates / SendDraftPlain	➖ no-op (нет аналога в Zulip)

Upcoming: mention-based thread takeover

Когда @balda-bot упоминается в топике без активной сессии — бот автоматически берёт топик под контроль.

Механизм (аналог whale-thread-guard в Hermes):

• Webhook payload поле trigger == "mention" → auto-create session
• allowed_owners список в конфиге: Zulip email без токена
• После захвата топик отвечает на все сообщения (обычная сессия)

Конфиг и инструкции

• balda/soul.md — soul (global_instruction) — редактировать здесь, синхронизировать в config.yaml
• balda/workspace-context.md — per-provider system_instructions (рабочий проект/стек)
• ~/Developer/balda/.config/balda/config.yaml — основной конфиг (runtime + balda)
• ~/Developer/balda/.env — секреты (Zulip API key, webhook token)

Запуск

cd ~/Developer/balda && ~/.local/bin/balda start

После первого запуска: из логов взять owner_token и отправить боту в Zulip DM:

/start owner=<token>

Docs

• docs/zulip-webhook.md — полное руководство по настройке
• docs/balda.md — техническая спецификация