# 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