SyslogSolution/zulip-platform-plugins
7
0
Fork 0
Code Issues 19 Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 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
This commit is contained in:
Abiba (pi)
2026-06-19 23:55:19 +00:00
parent fe434553a8
commit 66c6d4966e
13 changed files with 320 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ARCHITECTURE.md
+41 -43
View File
@@ -1,20 +1,18 @@
# 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.
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 │
│ Zulip Server (CT 117) │
│ chat.sysloggh.net:443 │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─── │
│ │tanko-bot │ │mumuni-bot│ │koonimo │ │koby-bot │ │... │
│ │ │ │ │ │-bot │ │ │ │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └─── │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─── │
│ │tanko-bot │ │mumuni-bot│ │koonimo │ │koby-bot │ │... │
│ │ │ │ │ │-bot │ │ │ │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └─── │
└───────┼────────────┼────────────┼────────────┼──────────────┘
│ │ │ │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐ ┌────▼────┐
@@ -26,41 +24,39 @@ A production-ready system enabling 6 AI agents across 3 platforms (Hermes Python
│ CT 112 │ │ CT 114 │ │ CT 113 │ │ CT 111 │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
┌──────────────┐ ┌──────────────┐
│ Agent Zero │ │ PI/openclaw │
│ Plugin │ │ Extension │
│ (Python) │ │ (TypeScript) │
│ │ │ │
│ kagentz │ │ abiba │
│ CT 105 │ │ CT 100 │
└──────────────┘ └──────────────┘
┌──────────────┐ ┌──────────────┐
│ 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
└── 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
└── 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
@@ -76,21 +72,20 @@ User types: @all-bots status report
- Implements: Agent Zero plugin API
- Config: `config.yaml` per-agent
### PI/openclaw (TypeScript) — openclaw Extension API
- Path: `openclaw-zulip-extension/src/`
- Implements: openclaw Extension
### 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
- **Monitoring**: Health endpoint (`/health`) on each plugin (port 9200)
- **Logging**: Per-plugin log files
## Config Template
```yaml
# config.yaml — Per-agent Zulip plugin configuration
agent:
@@ -106,16 +101,19 @@ zulip:
api_key: "${ZULIP_API_KEY}" # From env var
all_bots_user_id: 1234
agent:
max_retries: 3
error_handling:
timeout_seconds: 30
retry_count: 3
retry_delay_seconds: 5
health_port: 8080
monitoring:
health_endpoint_enabled: true
health_port: 9200
```
## 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
5. Gitea repo initialized at `git@git.sysloggh.net:SyslogSolution/zulip-platform-plugins.git`