From d4abcddc8d89615cc72b04a28bfd72e341df8d61 Mon Sep 17 00:00:00 2001
From: Alexey Martemyanov <mallexxx@gmail.com>
Date: Wed, 17 Jun 2026 15:40:59 +0600
Subject: [PATCH] [2026-06-17] hermes-eagle-mac.md: add routing schema, who
 receives what

---
 family/how-to/hermes-eagle-mac.md | 45 +++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/family/how-to/hermes-eagle-mac.md b/family/how-to/hermes-eagle-mac.md
index a219f6fd..8de35754 100644
--- a/family/how-to/hermes-eagle-mac.md
+++ b/family/how-to/hermes-eagle-mac.md
@@ -227,6 +227,51 @@ Claude падает с "Failed to spawn process". Проверить логи:
 
 ---
 
+---
+
+## Схема маршрутизации сообщений
+
+```
+Zulip Events API
+    ↓ poll (credentials Eagle)
+[zulip-router] (Go, Docker)
+    │
+    ├── @Валера → trigger=owner → POST balda-agent:8091
+    ├── @Клавдий → trigger=owner → POST claudio-agent:8092
+    ├── @Орёл → trigger=owner → POST host.docker.internal:8645/webhooks/eagle
+    ├── @Кит → trigger=owner → POST host.docker.internal:8646/webhooks/whale
+    └── ответы от ботов → в Zulip (боты пишут сами через API)
+```
+
+### Кто что получает
+
+| Компонент | Получает сообщения через | Шлёт ответы через |
+|-----------|-------------------------|-------------------|
+| **Eagle (Hermes gateway)** | zulip-router → POST `/webhooks/eagle` | Zulip API напрямую (бот `eagle-bot`) |
+| **Кит (Hermes gateway)** | zulip-router → POST `/webhooks/whale` | Zulip API напрямую (бот `whale-bot`) |
+| **Валера (balda-agent)** | zulip-router → POST `/zulip/webhook` | Zulip API напрямую (бот `valera-bot`) |
+| **Клавдий (claudio-agent)** | zulip-router → POST `/zulip/webhook` | Zulip API напрямую (бот `claudio-bot`) |
+
+**Важно:** `@**Орёл**` и `@**Кит**` НЕ регистрируют свои event queue в Zulip.
+Все сообщения приходят **только через zulip-router**. Роутер использует
+credentials Eagle для поллинга Zulip Events API, но Eagle сам в Zulip
+не поллит.
+
+### Что не так (проблема trigger=owner)
+
+Роутер после установки ownership шлёт ВСЕ сообщения из треда владельцу,
+даже если @mention адресован другому боту. Пример:
+
+1. Пользователь пишет `@Валера привет` → ownership = Валера
+2. Пользователь пишет `@Кит а как там` → роутер всё ещё шлёт Валере
+   (trigger=owner), хотя @mention адресован Киту
+
+**Должно быть:** если @mention другого бота — ownership обновляется,
+НО НЕ форвардить. Бот получит сообщение через свой outgoing webhook
+(от Zulip напрямую).
+
+---
+
 ## План работ: миграция портов Eagle и Whale (2026-06-17)
 
 ### Текущее состояние