contract: Zulip extension verification report + cross-platform contract
- Full contract verification for pi (TypeScript) and Hermes (Python) Zulip plugins - Fixed @all-bots user_id (1→20) — now dynamically resolved from Zulip API - Fixed last_event_id stale display in health endpoint (B2) - Fixed display_recipient logging (B3) - Added bot_user_id and all_bots_user_id to health endpoint - Created OpenProse cross-platform verification contract (docs/contracts/) - Created Hermes plugin deployment script (scripts/deploy-hermes-zulip.py) Pi extension: 8/9 checks pass (LLM relay untested — no external DMs) Hermes adapter: 9/10 checks pass (deployment pending)
This commit is contained in:
@@ -0,0 +1,98 @@
|
||||
---
|
||||
kind: contract
|
||||
name: zulip-platform-verification
|
||||
version: 1.0.0
|
||||
description: >
|
||||
Cross-platform Zulip agent verification contract. Validates both pi (TypeScript
|
||||
extension) and Hermes (Python BasePlatformAdapter) plugins can connect to Zulip,
|
||||
receive DMs, filter own messages, resolve @all-bots, and relay LLM responses.
|
||||
Designed to run on schedule (daily) or on-demand by any Syslog agent.
|
||||
author: Abiba (pi agent)
|
||||
---
|
||||
|
||||
# Zulip Platform Verification Contract
|
||||
|
||||
## Platforms Under Contract
|
||||
|
||||
| Platform | Agent | Bot Email | Plugin Path | Health Port |
|
||||
|----------|-------|-----------|-------------|-------------|
|
||||
| pi | Abiba | abiba-bot@chat.sysloggh.net | `~/.pi/agent/extensions/zulip/` | :9200 |
|
||||
| Hermes | Tanko | tanko-bot@chat.sysloggh.net | `~/.hermes/plugins/platforms/zulip/` | :9201 |
|
||||
| Hermes | Mumuni | mumuni-bot@chat.sysloggh.net | `~/.hermes/plugins/platforms/zulip/` | :9202 |
|
||||
| Hermes | Koonimo | koonimo-bot@chat.sysloggh.net | `~/.hermes/plugins/platforms/zulip/` | :9203 |
|
||||
| Hermes | Koby | koby-bot@chat.sysloggh.net | `~/.hermes/plugins/platforms/zulip/` | :9204 |
|
||||
|
||||
## Parameters
|
||||
|
||||
- zulip_site: string — Zulip server URL (default: "https://chat.sysloggh.net")
|
||||
- agents: array — List of agent configs to verify (default: all)
|
||||
- test_message: string — Content to send in loopback DM (default: "🔬 Contract self-test")
|
||||
|
||||
## Checks (per agent)
|
||||
|
||||
### Check 1: Health Endpoint
|
||||
- GET {{health_port}}/health → expect 200, `{ status: "ok", connected: true }`
|
||||
|
||||
### Check 2: Queue Registered
|
||||
- Health response must include `queue_id` (non-null string)
|
||||
|
||||
### Check 3: Bot Identity Resolved
|
||||
- Health response must include `bot_user_id` (positive integer, not null)
|
||||
|
||||
### Check 4: @all-bots Resolved
|
||||
- Health response must include `all_bots_user_id` (positive integer, not null)
|
||||
- Must match the actual Zulip @all-bots user (resolve from `/api/v1/users`)
|
||||
|
||||
### Check 5: Poll Loop Active
|
||||
- `idle_seconds` < 300 (5 min) OR `stuck` = false
|
||||
- `silence_seconds` < 600 (10 min) for Hermes adapter
|
||||
|
||||
### Check 6: Event Reception (Loopback)
|
||||
- Send test DM via Zulip API from external account
|
||||
- Verify `idle_seconds` resets to <10s within 5s of DM
|
||||
- OR verify `messages_processed` increments (for external-source DMs)
|
||||
|
||||
### Check 7: Self-Test (if available)
|
||||
- Hermes: POST to adapter's `selftest()` method → expect verdict "healthy"
|
||||
- pi: Run `/zulip-test` command via RPC → expect "All checks passed"
|
||||
|
||||
### Check 8: Echo-Loop Prevention
|
||||
- Health endpoint must include mechanism to identify bot email
|
||||
- Own-sent messages must not trigger processing
|
||||
|
||||
## Returns
|
||||
|
||||
```json
|
||||
{
|
||||
"verdict": "healthy" | "degraded" | "critical",
|
||||
"timestamp": "ISO-8601",
|
||||
"agents": {
|
||||
"abiba": {
|
||||
"platform": "pi",
|
||||
"verdict": "healthy",
|
||||
"checks": { ... },
|
||||
"details": { ... }
|
||||
},
|
||||
"tanko": {
|
||||
"platform": "hermes",
|
||||
"verdict": "degraded",
|
||||
"checks": { ... },
|
||||
"details": { ... }
|
||||
}
|
||||
},
|
||||
"summary": {
|
||||
"total": 5,
|
||||
"healthy": 4,
|
||||
"degraded": 1,
|
||||
"critical": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Ensures
|
||||
|
||||
- Each agent is independently verified; one failure doesn't block others
|
||||
- @all-bots user_id is cross-validated against Zulip API (catches config drift)
|
||||
- Report is saved to vault at `/root/vault/contract-reports/zulip-verification-{date}.md`
|
||||
- Alert sent to owner if any agent is critical or >2 are degraded
|
||||
- Contract is self-documenting — results include raw health snapshots
|
||||
Reference in New Issue
Block a user