2026-06-15: update balda-valera runbook — events polling fix, compose location

family/how-to/balda-valera.md

@@ -1,30 +1,52 @@
 # Балда / Валера — эксплуатация
 
 ## Расположение
-- Repo: `/Users/admin/Developer/balda/`
-- Compose: `compose.valera.yaml`
-- Config (persistent): `.config/balda/config.yaml`
-- Env: `.env`
+- Repo: `~/Developer/balda/`
+- **Рабочий compose**: `~/Docker/balda-agent/docker-compose.yaml` → контейнер `balda-agent-valera-1`
+- Config (persistent): `~/Docker/balda-agent/.config/balda/config.yaml`
+- Env: `~/Docker/balda-agent/.env`
+- Дублирующий compose `~/Developer/balda/compose.valera.yaml` — НЕ использовать (сеть `balda_default` без DNS)
 
 ## Запуск / рестарт
-```
-cd /Users/admin/Developer/balda
-docker compose -f compose.valera.yaml restart
+```bash
+cd ~/Docker/balda-agent
+docker-compose restart
+
+# Rebuild после изменений в коде:
+docker-compose build && docker-compose up -d
 ```
 
+## Архитектура получения сообщений
+Валера — **outgoing webhook bot** (bot_type=3). Zulip отправляет webhook только для @mention и DM.
+
+Для получения всех сообщений в теме — Events API polling (горутина в коде):
+- `events_polling.enabled: true` в config.yaml
+- Очередь регистрируется с `all_public_streams=true`
+- Бот подписывается на все публичные стримы при старте (`SubscribeToPublicStreams`)
+- После @mention создаётся сессия; последующие сообщения без @mention обрабатываются
+
+**После перезапуска**: нужно один раз написать `@Валера <текст>` чтобы создать сессию в теме.
+
 ## Диагностика молчания
-1. Проверить логи: `docker logs balda-valera-1 --tail 50`
-2. Стухший NATS-таск → симптом: новые сообщения не порождают новые turn-ID  
-   Фикс: рестарт контейнера (NATS embedded, состояние в памяти)
-3. Неверный API endpoint → в логах: `"Incorrect API key / platform.openai.com"`  
-   Проверить config.yaml: `runtime.providers.deepseek.openai.base_url`  
-   Должно быть `https://api.deepseek.com/v1`
+1. Проверить логи: `docker logs balda-agent-valera-1 --tail 50`
+2. Проверить что Events API polling запустился: `zulip events queue registered` в логах
+3. Стухший NATS-таск (симптом: логов нет после @mention)  
+   Фикс: `docker-compose restart` (NATS embedded, состояние в памяти)
+4. Бот не подписан на стримы (симптом: `processing zulip message trigger=stream` не появляется):
+   ```bash
+   curl -u "<bot_email>:<api_key>" https://zulip.qentra.top/api/v1/users/me/subscriptions
+   ```
+   Если пустой — должен подписаться при следующем старте. Или вручную через API.
 
 ## Конфигурация провайдера
 В `config.yaml` обязательно:
 ```yaml
 balda:
   provider: deepseek
+  zulip:
+    events_polling:
+      enabled: true
+    stream_only_with_session: true
 runtime:
   providers:
     deepseek: