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

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

Репо

Upstream: https://github.com/normahq/balda
Fork: https://github.com/mallexxx/balda
Local: ~/Developer/balda
Ветка: feat/zulip-transport

Архитектура

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

Settings → Bots → balda-bot → Edit
Bot type: Outgoing webhook
Endpoint URL: http://<host>:8090/zulip/webhook
Скопировать 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 — техническая спецификация

3.6 KiB Raw Blame History Unescape Escape