Files

T

Abiba (pi) 66c6d4966e fix: correct Abiba platform label (pi not openclaw), add plugin skeletons, shared config, fix health port

- Replace all 'openclaw' references with 'pi' (pi coding harness)
- Fix Git remote URL in CONTEXT.md
- Harmonize health port to 9200 across all docs
- Add config.yaml.example with full schema
- Add pi-zulip-extension skeleton (TypeScript, pi Extension API)
- Add hermes-zulip-plugin skeleton (Python, BasePlatformAdapter)
- Add agent-zero-plugin skeleton (Python, A0 plugin API)
- Update ADR-007 with pi extension docs reference
- Document private topic ACL v1 limitation in CONTEXT.md

2026-06-19 23:55:19 +00:00

5.3 KiB

Raw Blame History

Zulip Multi-Platform Agent Communication — Architecture

Overview

A production-ready system enabling 6 AI agents across 3 platforms (Hermes Python, Agent Zero, pi 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           │
   │ 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 (TypeScript) — pi Extension API

Path: pi-zulip-extension/src/
Implements: pi extension (TypeScript module in ~/.pi/agent/extensions/)
Config: config.yaml per-agent
Reference: pi extension docs at /usr/lib/node_modules/@earendil-works/pi-coding-agent/docs/extensions.md

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 (port 9200)
Logging: Per-plugin log files

Config Template

# 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

error_handling:
  timeout_seconds: 30
  retry_count: 3
  retry_delay_seconds: 5

monitoring:
  health_endpoint_enabled: true
  health_port: 9200

Prerequisites

Zulip server running on CT 117
Zulip bot users created for all 6 agents + All Bots
#agent-hub stream created with all bots subscribed
SSH key access to all 6 agent CTs
Gitea repo initialized at git@git.sysloggh.net:SyslogSolution/zulip-platform-plugins.git

5.3 KiB Raw Blame History