# Балда / Валера — эксплуатация

## Расположение
- Repo: `~/Developer/balda/` (ветка `main`)
- Code: upstream `normahq/balda` + `feat/zulip-transport` влит, `normahq/norma` v0.0.10
- **Рабочий 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`
- Owner: `allowed_owners` в config.yaml (статически, `/start owner=` не нужен)

## Запуск / рестарт

```bash
cd ~/Docker/balda-agent
docker-compose restart              # без пересборки, только конфиг/env не менялись
docker-compose up -d                # пересоздать контейнер, перечитать .env

# Rebuild после изменений в коде:
cd ~/Docker/claudio-agent && docker-compose build
docker tag claudio-agent-claudio:latest balda-agent-valera:latest
cd ~/Docker/claudio-agent && docker-compose up -d
cd ~/Docker/balda-agent && docker-compose up -d
```

> Валера и Клавдий — **один образ** (`balda-agent-valera`), собирается из одного Dockerfile (`Dockerfile.claudio`). Разница только в конфиге (`config.yaml`) и `.env`, которые монтируются volumes. Сборка идёт из `~/Docker/claudio-agent/` — там есть build секция.

## Архитектура получения сообщений
Валера — **outgoing webhook bot** (bot_type=3). Zulip отправляет webhook только для @mention и DM.

- `events_polling.enabled: false` в config.yaml
- Сообщения приходят только через **outgoing webhook** (webhook_token в .env)
- После @mention создаётся сессия; последующие сообщения без @mention обрабатываются

**После перезапуска**: написать `@Валера <текст>` чтобы создать сессию.

## MCP Obsidian — конфиг
Balda через SSE подключается к obsidian-mcp. **URL обязательно с `/sse`**:

```yaml
runtime:
  mcp_servers:
    obsidian:
      type: sse
      url: http://obsidian-mcp:3101/sse   # <-- без /sse → 404 Not Found
      name: obsidian
```

## Контекст (история сообщений)
**Работает** (на upstream `normahq/balda` с поддержкой hosted LLM agent sessions). ADK inject'ит историю корректно для OpenAI-совместимых провайдеров.

Раньше не работало — исправлено в upstream `32e33a8 fix: support hosted MCP toolsets` / `d774c78 fix: use hosted llmagent sessions`.

## Диагностика молчания

### 1. MCP ошибка: `failed to list MCP tools: failed to connect: Not Found`
**Причина**: в config.yaml url без `/sse` на конце.
**Фикс**: `url: http://obsidian-mcp:3101/sse` → `docker-compose restart`.

### 2. В логах `command running → command handled` за секунду, без `received provider event`
**Причина**: стухший embedded NATS. Swarm внутри процесса не доставляет команду до session/task actor'ов.
**Фикс**: `docker-compose restart` (если не помогло → `up -d`).

### 3. Удалён / пустой state.db
После удаления balda не может зарегистрировать swarm акторы.
**Фикс**: `rm state.db` и `up -d` (balda создаст заново).

### 4. Нет owner
`handleMessage` выходит при `getOwnerID() == 0`.
**Фикс**: прописать `allowed_owners` в config.yaml (не нужен `/start owner=`).

### 5. stream_only_with_session
Сообщение в теме без сессии молча дропается.
**Фикс**: написать `@Валера <текст>` чтобы создать сессию.

### 6. Проверить webhook со стороны
```bash
curl -X POST http://localhost:8091/zulip/webhook \
  -H "Content-Type: application/json" \
  -d '{"type":"test"}'
```

## Ключевые грабли

### OPENAI_BASE_URL — обязательная env var
Norma не читает `base_url` из config.yaml для `provider: deepseek`. Читает env `OPENAI_BASE_URL`.
Без неё запросы уходят на `api.openai.com` (401).

**В `.env` обязательно:**
```
OPENAI_BASE_URL=https://api.deepseek.com/v1
```

### DOCKER_OPTS — пустая строка убивает старт
Должен быть валидный JSON:
```
DOCKER_OPTS={"max_tokens": 2048, "temperature": 0.7}
```

### composerestart vs compose up -d
- `restart` — не перечитывает `.env`
- `up -d` — пересоздаёт контейнер с обновлённым `.env`