prose-contracts/zulip-adapter-lessons.prose.md

kind, name, status, note, description

kind	name	status	note	description
pattern	zulip-adapter-lessons	historical	pi Zulip extension retired 2026-07-04. These lessons remain relevant for Hermes and Agent Zero Zulip adapters. Kept as institutional knowledge.	Lessons learned from building and debugging the pi Zulip extension and Hermes Zulip plugin. Documents failure modes, fixes, and patterns that apply across all Zulip adapters.

Known Failure Modes & Fixes

1. Queue Registration Content-Type

• Symptom: Event queue registered but delivers no stream events
• Root cause: multipart/form-data (from isomorphic-form-data / form-data npm pkgs) vs application/x-www-form-urlencoded
• Fix: Always use URLSearchParams / form-urlencoded for /api/v1/register
• Applies to: pi extension (fixed), Hermes adapter (httpx sends form-urlencoded by default ✅)

2. Missing bot_user_id for @mention Detection

• Symptom: Bot receives stream messages but doesn't respond to @mentions
• Root cause: /api/v1/register doesn't return user_id; mentioned_users check fails when bot ID is null
• Fix: Call GET /api/v1/users/me after registration to get user_id
• Applies to: pi extension (fixed), Hermes adapter (fixed via _resolve_bot_user_id() ✅)

3. Zero Stream Subscriptions

• Symptom: Bot can send to streams but never receives stream events
• Root cause: Bot user created with 0 stream subscriptions — only DMs arrive
• Fix: POST /api/v1/users/me/subscriptions with required stream names
• Applies to: pi extension (fixed), Hermes adapter (⚠️ needs check)

4. Stale Errors Never Cleared

• Symptom: Health monitor shows persistent error long after recovery
• Root cause: last_error set on failure but never cleared on successful poll
• Fix: Clear lastError on every successful poll (not just on reconnect)
• Applies to: pi extension (fixed), Hermes adapter (⚠️ needs check)

5. Stuck Detection Too Aggressive

• Symptom: Monitor restarts bot during quiet periods (nights/weekends)
• Root cause: 30-min stuck threshold doesn't account for low traffic
• Fix: Raise threshold to 4 hours — or remove stuck detection entirely
• Applies to: pi extension (fixed to 4h), Hermes gateway (uses own idle detection)

6. Env Var Name Mismatch (ZULIP_URL vs ZULIP_SITE)

• Symptom: Plugin not loading because check_fn returns False
• Root cause: Some deploy configs use ZULIP_URL, adapter code expects ZULIP_SITE
• Fix: Support both names in check_fn, validate_config, and env_enablement_fn
• Applies to: Hermes adapter (fixed ✅)

7. Poll Interval Too Aggressive

• Symptom: Queue expires faster than expected, reconnection cycling
• Root cause: 3s poll interval with dont_block=true creates many requests
• Fix: Use long-poll (no dont_block) with 30s+ server timeout
• Applies to: pi extension (uses long-poll ✅), Hermes adapter (uses long-poll ✅)

8. A2A Server Address Already In Use

• Symptom: A2A server fails to start with "[Errno 98] address already in use"
• Root cause: Previous process holds port after container restart
• Fix: Kill old process before starting, or use docker restart to clear state
• Applies to: kagentz Agent Zero deployment

9. Zulip API Rate Limiting During Reconnection

• Symptom: Extension gets 429 errors and can't reconnect — responses vanish
• Root cause: Rapid PM2 restarts cause multiple queue registrations, hitting Zulip's per-IP rate limit
• Fix: Read retry-after header and wait before retrying; increase backoff between retries
• Applies to: pi extension (fixed), Hermes adapter (has retry logic but should check retry-after)

10. Placeholder Edit Fails Silently (Streaming Vanishes)

• Symptom: User sees "Thinking..." placeholder but never gets the actual response
• Root cause: editMessage API call fails (e.g., message too old, rate limited) but no fallback
• Fix: If edit fails, send the response as a new message instead
• Applies to: pi extension (fixed), Hermes adapter (verify edit fallback exists)

Deployment Checklist

When deploying a new Zulip adapter, verify:

• Queue registered with form-urlencoded content type
• Bot user_id fetched from /api/v1/users/me
• Subscribed to all expected streams (check with /api/v1/users/me/subscriptions)
• last_error cleared on successful poll
• Env vars support both ZULIP_URL and ZULIP_SITE
• Stream @mentions detected via mentioned_users array
• @all-bots detected via configurable user_id
• Poll uses long-poll (not dont_block=true polling)
• Stuck/idle detection accounts for quiet periods