# 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

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

### Запуск

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

После первого запуска: из логов взять `owner_token` и отправить боту в Zulip DM:
```
/start owner=<token>
```

## Docs

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