feat: initial monorepo with PRD, 12 ADRs, and plugin skeletons

2026-06-19 18:37:27 -04:00
commit fe434553a8
15 changed files with 599 additions and 0 deletions
@@ -0,0 +1,121 @@
+# Zulip Multi-Platform Agent Communication — Architecture
+
+## Overview
+
+A production-ready system enabling 6 AI agents across 3 platforms (Hermes Python, Agent Zero, PI/openclaw TypeScript) to communicate through Zulip via dedicated per-agent bot users.
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   Zulip Server (CT 117)                     │
+│  chat.sysloggh.net:443                                      │
+│                                                             │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───  │
+│  │tanko-bot │ │mumuni-bot│ │koonimo   │ │koby-bot  │ │...  │
+│  │          │ │          │ │-bot      │ │          │ │     │
+│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───  │
+└───────┼────────────┼────────────┼────────────┼──────────────┘
+        │            │            │            │
+   ┌────▼────┐  ┌────▼────┐  ┌────▼────┐  ┌────▼────┐
+   │ Hermes  │  │ Hermes  │  │ Hermes  │  │ Hermes  │
+   │ Plugin  │  │ Plugin  │  │ Plugin  │  │ Plugin  │
+   │ (Python)│  │ (Python)│  │ (Python)│  │ (Python)│
+   │         │  │         │  │         │  │         │
+   │ Tanko   │  │ Mumuni  │  │ Koonimo │  │ Koby    │
+   │ CT 112  │  │ CT 114  │  │ CT 113  │  │ CT 111  │
+   └─────────┘  └─────────┘  └─────────┘  └─────────┘
+
+   ┌──────────────┐          ┌──────────────┐
+   │ Agent Zero   │          │ PI/openclaw  │
+   │ Plugin       │          │ Extension    │
+   │ (Python)     │          │ (TypeScript) │
+   │              │          │              │
+   │ kagentz      │          │ abiba        │
+   │ CT 105       │          │ CT 100       │
+   └──────────────┘          └──────────────┘
+```
+
+## Message Flow (Normal)
+
+```
+User creates topic "project-x" in #agent-hub
+  └── User types: @tanko-bot analyze this data
+       └── Zulip fires event to tanko-bot's event queue
+            └── Hermes Zulip Plugin on CT 112
+                 ├── Detects: tanko-bot in mentioned_users
+                 ├── Strips @mention from message
+                 ├── Constructs MessageEvent
+                 └── Routes to Tanko agent via BasePlatformAdapter
+                      └── Tanko agent processes, returns response
+                           └── Plugin posts to #agent-hub > project-x
+```
+
+## Message Flow (@all-bots)
+
+```
+User types: @all-bots status report
+  └── Zulip fires event to ALL 6 bots (same narrow)
+       └── Each plugin independently:
+            ├── Detects: All Bots in mentioned_users
+            ├── Forwards to its agent
+            └── Posts response to same topic
+  └── 6 independent responses appear in the topic
+```
+
+## Platform Plugin Contracts
+
+### Hermes (Python) — BasePlatformAdapter
+- Path: `hermes-zulip-plugin/src/hermes_zulip/`
+- Implements: `BasePlatformAdapter` (Hermes Gateway)
+- Config: `config.yaml` per-agent
+- Entry point: `plugin.yaml` (Hermes manifest)
+
+### Agent Zero — A0 Plugin System
+- Path: `agent-zero-plugin/src/`
+- Implements: Agent Zero plugin API
+- Config: `config.yaml` per-agent
+
+### PI/openclaw (TypeScript) — openclaw Extension API
+- Path: `openclaw-zulip-extension/src/`
+- Implements: openclaw Extension
+- Config: `config.yaml` per-agent
+
+## Reliability
+
+- **Reconnection**: Zulip SDK handles backoff/reconnect natively
+- **Retry**: 3 attempts with 5s backoff on agent timeout
+- **Error Response**: User-visible message on failure
+- **Monitoring**: Health endpoint (`/health`) on each plugin
+- **Logging**: Per-plugin log files
+
+## Config Template
+
+```yaml
+# config.yaml — Per-agent Zulip plugin configuration
+agent:
+  name: "tanko"
+  display_name: "Tanko"
+  zulip_bot_name: "tanko-bot"
+  owner_email: "jerome@sysloggh.net"
+  private_topic: "tanko-private"
+
+zulip:
+  server_url: "https://chat.sysloggh.net"
+  email: "tanko-bot@chat.sysloggh.net"
+  api_key: "${ZULIP_API_KEY}"  # From env var
+  all_bots_user_id: 1234
+
+agent:
+  max_retries: 3
+  retry_delay_seconds: 5
+  health_port: 8080
+```
+
+## Prerequisites
+
+1. Zulip server running on CT 117
+2. Zulip bot users created for all 6 agents + All Bots
+3. `#agent-hub` stream created with all bots subscribed
+4. SSH key access to all 6 agent CTs
+5. Gitea repo initialized