Merge pull request 'feat(zulip): streaming responses + steering via session injection' (#23 ) from feat/zulip-streaming into main

Reviewed-on: #23
2026-06-24 20:42:07 +00:00
29 changed files with 2728 additions and 4121 deletions
@@ -1,4 +1,6 @@
 # Gitea Actions CI — zulip-platform-plugins
 # Activates when Gitea Actions runners are configured.
 # Until then, use manual pre-merge checklist in PR template.
 name: CI
@@ -7,49 +9,28 @@ on:
    branches: [main]
  push:
    branches: [main]
    tags:
      - v*
 jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
-      - run: python3 --version
+      - uses: actions/checkout@v4
      - run: node --version
      - run: echo "Runner works!"
      - run: git clone --depth 1 http://abiba-bot:***REDACTED***@192.168.68.17:3000/SyslogSolution/zulip-platform-plugins.git .
-      - name: Python syntax check
+      - name: Validate shared config schema
        run: |
-          python3 -m py_compile plugins/platforms/zulip/adapter.py 2>/dev/null && echo "✅ adapter.py OK" || echo "⚠️ adapter.py check skipped"
+          python3 -c "import yaml; cfg = yaml.safe_load(open('config.yaml.example')); assert 'agent' in cfg; assert 'zulip' in cfg"
          python3 -m py_compile agent-zero-zulip/src/agent_zero_zulip/adapter.py 2>/dev/null && echo "✅ a2a adapter OK" || echo "⚠️ a2a check skipped"
-      - name: Config validation
+      - name: Python lint (Hermes + Agent Zero)
        run: |
-          python3 -c "
+          pip install ruff
-import yaml
+          ruff check hermes-zulip-plugin/ agent-zero-plugin/
 cfg = yaml.safe_load(open('config.yaml.example'))
 assert 'zulip' in cfg, 'Missing zulip config'
 print('✅ config.yaml.example valid')
 " 2>/dev/null || echo "⚠️ Config check skipped (no pyyaml)"
-      - name: No secrets check
+      - name: TypeScript check (pi extension)
        run: |
-          ! grep -r "api_key.*[A-Za-z0-9]\{20,\}" --include="*.py" --include="*.ts" --include="*.yaml" . 2>/dev/null || echo "⚠️ Possible API key found!"
+          cd pi-zulip-extension
          npm ci
          npx tsc --noEmit
-      - name: Deploy script syntax
+      - name: Check no secrets committed
-        run: bash -n scripts/deploy.sh && echo "✅ deploy.sh syntax OK" || echo "⚠️ deploy.sh syntax issue"
+        run: |
-
+          ! grep -r "api_key.*[A-Za-z0-9]\{20,\}" --include="*.py" --include="*.ts" --include="*.yaml" . || echo "WARNING: possible API key in code"
  deploy:
    if: startsWith(github.ref, 'refs/tags/v')
    runs-on: ubuntu-latest
    needs: [validate]
    steps:
      - run: echo "🚀 Deploy tag $(echo $GITHUB_REF_NAME)"
      - run: git clone --depth 1 http://abiba-bot:***REDACTED***@192.168.68.17:3000/SyslogSolution/zulip-platform-plugins.git .
      - name: Deploy to Tanko (canary)
        run: ssh -o StrictHostKeyChecking=no -o ConnectTimeout=10 jerome@192.168.68.122 "cd /root && bash -s" < scripts/deploy.sh --ct=tanko --mode=native "$GITHUB_REF_NAME" 2>&1 || echo "⚠️ Tanko deploy skipped"
      - name: Deploy to Mumuni
        run: ssh -o StrictHostKeyChecking=no -o ConnectTimeout=10 root@192.168.68.123 "cd /root && bash -s" < scripts/deploy.sh --ct=mumuni --mode=native "$GITHUB_REF_NAME" 2>&1 || echo "⚠️ Mumuni deploy skipped"
@@ -1,108 +0,0 @@
 # Staggered Deployment Pipeline
 #
 # Release flow:
 #   v*.*.*-rc.* → Tanko only (canary)      e.g. v1.1.0-rc.1
 #   az-v*.*.*    → kagentz only (A2A track) e.g. az-v1.0.0
 #   v*.*.*       → all Hermes agents        e.g. v1.1.0
 #
 # Pi agents (Abiba) use a separate update mechanism.
 name: Deploy
 on:
  push:
    tags:
      - v*.*.*          # Stable Hermes release → all agents
      - v*.*.*-rc.*     # Release candidate → Tanko only
      - az-v*.*.*       # Agent Zero release → kagentz only
 jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        run: git clone --depth 1 http://abiba-bot:***REDACTED***@192.168.68.17:3000/SyslogSolution/zulip-platform-plugins.git .
      - name: Python syntax
        run: |
          python3 -m py_compile plugins/platforms/zulip/adapter.py 2>/dev/null
          python3 -m py_compile agent-zero-zulip/src/agent_zero_zulip/adapter.py 2>/dev/null || true
      - name: Deploy script
        run: bash -n scripts/deploy.sh 2>/dev/null || true
  # ── Track 1: Tanko (Hermes canary) ─────────────────────
  deploy-tanko:
    if: startsWith(github.ref, 'refs/tags/v')
    runs-on: ubuntu-latest
    needs: [validate]
    environment: canary
    steps:
      - name: Checkout
        run: git clone --depth 1 http://abiba-bot:***REDACTED***@192.168.68.17:3000/SyslogSolution/zulip-platform-plugins.git .
      - name: Deploy to Tanko
        env:
          TAG: ${{ github.ref_name }}
        run: |
          echo "🧪 Canary deploy $TAG → Tanko (CT 112)"
          ssh -o StrictHostKeyChecking=no -o ConnectTimeout=10 jerome@192.168.68.122 \
            "cd /root && bash -s" < scripts/deploy.sh --ct=tanko --mode=native "$TAG" 2>&1
      - name: Canary health check
        run: |
          echo "⏳ Waiting 60s for canary to settle..."
          sleep 60
          STATE=$(ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 jerome@192.168.68.122 \
            "cat ~/.hermes/gateway_state.json 2>/dev/null" 2>/dev/null || echo '{}')
          ZULIP_STATE=$(echo $STATE | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('platforms',{}).get('zulip',{}).get('state','unknown'))" 2>/dev/null)
          echo "Tanko Zulip state: $ZULIP_STATE"
          if [ "$ZULIP_STATE" != "connected" ]; then
            echo "⚠️ Canary health check failed — promoting anyway (non-blocking)"
          fi
  # ── Track 2: Hermes agents (after canary passes) ──────
  deploy-hermes:
    if: startsWith(github.ref, 'refs/tags/v') && !startsWith(github.ref, 'refs/tags/v*.*.*-rc') && !startsWith(github.ref, 'refs/tags/az-')
    runs-on: ubuntu-latest
    needs: [deploy-tanko]
    environment: production
    steps:
      - name: Checkout
        run: git clone --depth 1 http://abiba-bot:***REDACTED***@192.168.68.17:3000/SyslogSolution/zulip-platform-plugins.git .
      - name: Deploy to all Hermes agents
        env:
          TAG: ${{ github.ref_name }}
        run: |
          echo "🚀 Promoting $TAG to Hermes agents"
          # Mumuni
          echo "--- Mumuni (CT 114) ---"
          ssh -o StrictHostKeyChecking=no -o ConnectTimeout=10 root@192.168.68.123 \
            "cd /root && bash -s" < scripts/deploy.sh --ct=mumuni --mode=native "$TAG" 2>&1
      - name: Production health check
        run: |
          sleep 30
          for agent in "jerome@192.168.68.122" "root@192.168.68.123"; do
            STATE=$(ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 $agent \
              "cat ~/.hermes/gateway_state.json 2>/dev/null" 2>/dev/null || echo '{}')
            NAME=$(echo $agent | cut -d@ -f2)
            echo "$NAME: $(echo $STATE | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('platforms',{}).get('zulip',{}).get('state','unknown'))" 2>/dev/null)"
          done
          echo "✅ Production rollout complete"
  # ── Track 3: Agent Zero (kagentz) ─────────────────────
  deploy-agent-zero:
    if: startsWith(github.ref, 'refs/tags/az-')
    runs-on: ubuntu-latest
    needs: [validate]
    environment: agent-zero
    steps:
      - name: Checkout
        run: git clone --depth 1 http://abiba-bot:***REDACTED***@192.168.68.17:3000/SyslogSolution/zulip-platform-plugins.git .
      - name: Deploy to kagentz
        env:
          TAG: ${{ github.ref_name }}
        run: |
          echo "🤖 Deploying Agent Zero $TAG → kagentz (CT 105)"
          TAG_CLEAN=$(echo $TAG | sed 's/^az-//')
          ssh -o StrictHostKeyChecking=no -o ConnectTimeout=10 root@192.168.68.14 \
            "cd /root && bash -s" < scripts/deploy.sh --ct=kagentz --mode=legacy "$TAG_CLEAN" 2>&1
@@ -24,13 +24,3 @@ Thumbs.db
 # Logs
 *.log
 deploy.log
 # Gitea runner
 .act_runner/
 .cache/act/
 # Git hooks (installed locally)
 .githooks/
 # PM2 ecosystem (local configs)
 ecosystem.*.config.cjs
@@ -1,23 +0,0 @@
 # Commit message conventions:
 #
 # feat:    New feature (bumps minor)
 # fix:     Bug fix (bumps patch)
 # refactor: Code change without feature/fix
 # docs:    Documentation only
 # ci:      CI/CD changes
 # chore:   Maintenance, deps, tooling
 # test:    Test changes
 # style:   Formatting, no logic change
 #
 # Breaking changes: append ! after type
 #   feat!: breaking change (bumps major)
 #
 # Scope (optional): (hermes), (pi), (agent-zero), (deploy), (ci)
 #
 # Examples:
 #   feat(hermes): add health check endpoint
 #   fix(agent-zero): reconnect on queue expiry
 #   ci!: switch to Gitea Actions runner
 #   chore(deps): bump zulip-js to v0.7
@@ -1 +0,0 @@
 # CI Final Test
@@ -1,2 +0,0 @@
 # CI Pipeline Status
 Status: Active
@@ -1,105 +0,0 @@
 # PR #21 Review — fix(tanko): adapter fixes, event logging, platform-based deploy.sh
 Reviewer: Abiba  
 Date: 2026-06-20  
 Status: ✅ Approve with changes (3 blocking, 3 advisory)
 ---
 ## Review Comments
 ### Comment 1 (🔴 Blocking): CI stuck at "Waiting to run"
 The Gitea Actions workflow (run #4) hasn't started. No CI results available. Per the GitOps branch protection rules, status checks must pass before merge. Do not merge until CI completes and all jobs are green.
 ---
 ### Comment 2 (🟡 High): `print()` for journald is an anti-pattern
 In `adapter.py`, the new `_process_event` method uses raw `print()` for journald visibility:
 ```python
 print(f"[ZULIP_EVENT] Processing: {event.get('type', 'unknown')}")
 ```
 The existing `logger.info()` calls already flow to journald via stderr when the systemd unit uses `StandardError=journal`. Using raw `print()` bypasses:
 - Log level filtering
 - Format consistency with other log output
 - Future structured logging needs
 **Fix:** Replace with `logger.info(f"[ZULIP_EVENT] Processing: {event.get('type', 'unknown')}")`.
 ---
 ### Comment 3 (🟡 High): `asyncio.new_event_loop()` leaks on thread restart
 In `_event_loop`, a new event loop is created but never closed:
 ```python
 def _event_loop(self) -> None:
    loop = asyncio.new_event_loop()
    asyncio.set_event_loop(loop)
    try:
        self._client.call_on_each_message(...)
    except Exception as e:
        logger.error(f"Event loop crashed: {e}")
        self.connected = False
 ```
 If the thread restarts (e.g., reconnection), the old loop is leaked. This accumulates over time.
 **Fix:** Wrap in `try/finally`:
 ```python
 def _event_loop(self) -> None:
    loop = asyncio.new_event_loop()
    asyncio.set_event_loop(loop)
    try:
        self._client.call_on_each_message(
            lambda event: self._process_event(event),
        )
    except Exception as e:
        logger.error(f"Event loop crashed: {e}")
        self.connected = False
    finally:
        loop.close()
 ```
 ---
 ### Comment 4 (🟡 Medium): Verify `Client(site=...)` parameter name
 The PR changes `Client(server_url=...)` → `Client(site=...)` for "Python 3.13 compatibility." However, the Python Zulip API's `Client` constructor parameter name varies by version:
 - Some versions use `site`
 - Others use `server_url`
 - Parameter names changed across releases
 **Action needed:** Verify the installed `zulip` package version on CT 112 supports the `site` parameter. If it doesn't, the connection will fail silently (no TypeError—kwargs are accepted by the base class).
 ---
 ### Comment 5 (🟡 Medium): deploy.sh refactor only tested on Hermes platform
 The PR refactors `deploy.sh` across all 3 platforms (Hermes, Agent Zero, Pi) but testing only covers Tanko (Hermes) on CT 112. The Agent Zero (`pip install -r requirements.txt`) and Pi (`/reload` instead of `systemctl`) code paths are untested.
 **Action needed:** Before merging, run at minimum a dry-run deploy against all 3 platform types:
 ```
 ./scripts/deploy.sh --ct=kagentz main --dry-run
 ./scripts/deploy.sh --ct=abiba main --dry-run
 ```
 ---
 ### Comment 6 (🟢 Low): Agent Zero pip install assumption
 The deploy.sh case statement lumps hermes and agent-zero together for dependency installation:
 ```bash
 hermes|agent-zero)
    pip install -r requirements.txt --quiet
    ;;
 ```
 This assumes Agent Zero has the same `requirements.txt` location and content as Hermes. If Agent Zero uses a different dependency file or install method, this will silently install wrong packages.
 **Suggestion:** Add a per-platform dependency install path or document this assumption explicitly.
@@ -1,48 +0,0 @@
 # Deploy Agent Zero Zulip Adapter
 ## Prerequisites
 - Agent Zero running in Docker on the target CT
 - A Zulip bot created for the agent (kagentz-bot, scottdenya-bot, etc.)
 - Python 3.11+ with httpx
 ## Steps
 ### 1. Create Zulip Bot
 Go to Zulip admin → Bot management → Add a new bot:
 - Name after the agent
 - Copy the API key
 ### 2. Install Adapter
 ```bash
 # On the target CT
 pip install httpx
 # Copy adapter files
 scp -r agent-zero-zulip/ root@<ct-ip>:/opt/agent-zero-zulip/
 # Create config
 cp config.yaml.example config.yaml
 # Edit config.yaml with Zulip credentials
 ```
 ### 3. Start A2A Server on Agent Zero
 ```bash
 # Inside Agent Zero container
 docker exec agent-zero /opt/venv-a0/bin/python3 /a0/usr/start_a2a_direct.py &
 # Verify A2A is running
 curl http://localhost:8001/.well-known/agent.json
 ```
 ### 4. Start Zulip Adapter
 ```bash
 # On the host
 cd /opt/agent-zero-zulip
 python3 -m agent_zero_zulip.adapter &
 # Verify
 tail -f adapter.log
 ```
 ### 5. Test
 Send a DM to kagentz-bot in Zulip. Expect "Processing..." → response.
@@ -1,30 +0,0 @@
 # Agent Zero Zulip Adapter
 Direct Zulip integration for Agent Zero agents (kagentz, scottdenya, etc.).
 Each agent gets its own Zulip bot. Uses A2A protocol internally to
 communicate with Agent Zero's native A2A server.
 ## Architecture
 ```
 ┌─────────────────────────────────────────┐
 │            kagentz (CT 105)             │
 │                                         │
 │  ┌──────────────┐    ┌──────────────┐   │
 │  │  Agent Zero  │◄──►│  Zulip A2A   │   │
 │  │  (Docker)    │A2A │  Adapter     │   │
 │  │              │    │              │   │
 │  │  port 8001   │    │  polls Zulip │   │
 │  └──────────────┘    └──────┬───────┘   │
 │                             │           │
 └─────────────────────────────┼───────────┘
                              │ Zulip API
                              ▼
                      chat.sysloggh.net
 ```
 ## Components
 - `adapter.py` — Zulip event queue poller + A2A client
 - `agent_card.py` — Agent Card for A2A discovery
 - `Dockerfile` or `requirements.txt` for dependencies
@@ -1,13 +0,0 @@
 # Agent Zero Zulip Adapter Configuration
 # Copy to config.yaml and fill in credentials
 zulip:
  site: https://chat.sysloggh.net
  email: kagentz-bot@chat.sysloggh.net
  api_key: "<your-api-key>"
  stream: agent-hub
 agent:
  name: kagentz
  a2a_url: http://localhost:8001/a2a
  a2a_token: 8zNgdOEXzYxjQvTl
@@ -1 +0,0 @@
 httpx>=0.27.0
@@ -1,195 +0,0 @@
 """A2A server for kagentz — LiteLLM with session memory + homelab project context."""
 import os, json, uuid, asyncio
 from datetime import datetime
 from typing import Optional
 import uvicorn
 from fastapi import FastAPI, Request
 import httpx
 app = FastAPI()
 LITELLM_URL = os.getenv("LITELLM_URL", "https://litellm.sysloggh.net/v1")
 LITELLM_KEY = os.getenv("LITELLM_KEY", "sk-akDPhdO8qlhYNtVet6KZog")
 LITELLM_MODEL = os.getenv("LITELLM_MODEL", "syslog-auto")
 NOW = datetime.utcnow().strftime("%Y-%m-%d %H:%M UTC")
 # Session store: session_id -> list of {"role": ..., "content": ...}
 sessions: dict[str, list[dict]] = {}
 # Task results: task_id -> (state, result)
 task_results: dict[str, tuple[str, Optional[dict]]] = {}
 HOMELAB_CONTEXT = f"""You are kagentz, a homelab automation agent for Syslog Solution LLC.
 ## System Context (read-only)
 - Current date: {NOW}
 - Default project: **Syslog Homelab** (sysloggh.com)
 - Infrastructure: Proxmox 3-node cluster (minipve, amdpve, syslog-api), Docker on CT 116/.7/.14
 - Zulip chat: chat.sysloggh.net (agent-hub stream)
 - LLM backend: LiteLLM at litellm.sysloggh.net
 - Available tools: Zulip messaging, SSH to infrastructure hosts, Docker commands
 ## Personality
 - Professional but conversational
 - Default all responses to the homelab project context unless the user specifies otherwise
 - If asked about project context, state "Syslog Homelab" as your home project
 - Keep responses concise and actionable
 - When you don't know something, say so rather than guessing
 ## Your Capabilities
 - You can converse about homelab infrastructure: Proxmox, Docker, networking, monitoring
 - You can execute basic diagnostics via LiteLLM
 - You cannot directly SSH or run commands (that's handled by other agents)
 - You can discuss Zulip platform integrations, agent architectures (pi, Hermes, Agent Zero)
 """
 MAX_SESSION_HISTORY = 20  # keep last 20 messages per session
 SESSION_TTL = 3600  # seconds before session garbage collection
 def _get_session(session_id: str) -> list[dict]:
    """Get or create a session's message history."""
    if session_id not in sessions:
        sessions[session_id] = [{"role": "system", "content": HOMELAB_CONTEXT}]
    return sessions[session_id]
 def _cleanup_stale_sessions():
    """Remove old sessions periodically."""
    # Simple TTL: sessions that haven't been touched
    pass  # Sessions are cleaned on restart (ephemeral)
@app.get("/.well-known/agent.json")
 async def agent_card():
    return {
        "name": "kagentz",
        "version": "1.0.0",
        "description": "Agent Zero on CT 105 via Zulip + LiteLLM",
        "capabilities": {"a2a": {"version": "1.0"}},
        "skills": [{"id": "chat", "name": "Chat"}],
    }
@app.post("/a2a")
 async def a2a_endpoint(request: Request):
    body = await request.json()
    method = body.get("method", "")
    if method == "tasks/send":
        params = body.get("params", {})
        msg = params.get("message", {})
        parts = msg.get("parts", [])
        text = " ".join(p.get("text", "") for p in parts if isinstance(p, dict))
        # Extract session ID from metadata (passed by adapter)
        metadata = params.get("metadata", {}) or {}
        session_id = metadata.get("session_id", f"anon-{uuid.uuid4().hex[:8]}")
        task_id = f"az-{uuid.uuid4().hex[:12]}"
        asyncio.create_task(call_litellm(task_id, session_id, text))
        return {
            "jsonrpc": "2.0",
            "result": {
                "id": task_id,
                "status": {"state": "working"},
                "metadata": {"session_id": session_id},
            },
        }
    elif method == "tasks/get":
        task_id = body.get("params", {}).get("id", "")
        entry = task_results.get(task_id)
        if not entry:
            return {
                "jsonrpc": "2.0",
                "result": {"id": task_id, "status": {"state": "pending"}},
            }
        status, result = entry
        resp = {"jsonrpc": "2.0", "result": {"id": task_id, "status": {"state": status}}}
        if status == "completed" and result:
            resp["result"]["history"] = [
                {"role": "user", "parts": [{"text": result.get("input", "")}]},
                {"role": "assistant", "parts": [{"text": result.get("output", "")}]},
            ]
            # Pass back the session_id so the adapter can reuse it
            if result.get("session_id"):
                resp["result"]["metadata"] = {"session_id": result["session_id"]}
        elif status == "failed":
            resp["result"]["status"]["message"] = {"text": str(result)}
        return resp
    elif method == "tasks/session/new":
        """Explicitly start a new session, clearing history."""
        metadata = body.get("params", {}).get("metadata", {}) or {}
        session_id = metadata.get("session_id", f"new-{uuid.uuid4().hex[:8]}")
        sessions.pop(session_id, None)
        _get_session(session_id)  # recreate fresh
        return {
            "jsonrpc": "2.0",
            "result": {
                "status": {"state": "completed"},
                "metadata": {"session_id": session_id},
            },
        }
    elif method == "tasks/session/clear":
        """Clear history but keep session alive."""
        session_id = body.get("params", {}).get("metadata", {}).get("session_id", "")
        if session_id in sessions:
            sessions[session_id] = [{"role": "system", "content": HOMELAB_CONTEXT}]
        return {
            "jsonrpc": "2.0",
            "result": {"status": {"state": "completed"}},
        }
    return {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}}
 async def call_litellm(task_id: str, session_id: str, message: str):
    """Call LiteLLM with conversation history from session."""
    try:
        session = _get_session(session_id)
        # Add user message to history
        session.append({"role": "user", "content": message})
        # Trim if too long (keep system prompt + recent messages)
        if len(session) > MAX_SESSION_HISTORY + 1:
            session[:] = [session[0]] + session[-(MAX_SESSION_HISTORY):]
        async with httpx.AsyncClient(timeout=120.0) as client:
            resp = await client.post(
                f"{LITELLM_URL}/chat/completions",
                headers={
                    "Authorization": f"Bearer {LITELLM_KEY}",
                    "Content-Type": "application/json",
                },
                json={
                    "model": LITELLM_MODEL,
                    "messages": session,
                    "max_tokens": 2000,
                },
            )
            if resp.is_success:
                output = resp.json()["choices"][0]["message"]["content"]
                # Store assistant response in history
                session.append({"role": "assistant", "content": output})
                task_results[task_id] = (
                    "completed",
                    {"input": message, "output": output, "session_id": session_id},
                )
            else:
                task_results[task_id] = (
                    "failed",
                    f"LiteLLM HTTP {resp.status_code}: {resp.text[:200]}",
                )
    except Exception as e:
        task_results[task_id] = ("failed", str(e))
 if __name__ == "__main__":
    print(f"kagentz A2A server on port 8001 (model={LITELLM_MODEL})")
    print(f"Project context: Syslog Homelab")
    print(f"Session memory: {MAX_SESSION_HISTORY} messages per session")
    uvicorn.run(app, host="0.0.0.0", port=8001, log_level="info")
@@ -1,501 +0,0 @@
 """
 Agent Zero Zulip Adapter — Direct Zulip integration for Agent Zero agents.
 Architecture:
  Zulip event queue → poll loop → A2A send to Agent Zero → 
  wait for A2A response → post back to Zulip
 Runs alongside Agent Zero on the same host. Communicates with Agent Zero
 via local A2A protocol (port 8001). No intermediate bridge needed.
 """
 import asyncio
 import json
 import logging
 import os
 import time
 from datetime import datetime, timezone
 from typing import Any, Optional
 import urllib.parse
 try:
    import httpx
 except ImportError:
    httpx = None
 logger = logging.getLogger("agent-zero-zulip")
 # Constants
 DEFAULT_A2A_URL = "http://localhost:8001/a2a"
 DEFAULT_A2A_TOKEN = "8zNgdOEXzYxjQvTl"
 DEFAULT_POLL_INTERVAL = 3.0
 MAX_ZULIP_MSG = 10000
 RECONNECT_BACKOFF = [2, 5, 10, 30, 60]
 HEARTBEAT_INTERVAL = 300  # 5 min
 class AgentZeroZulipAdapter:
    """Zulip adapter for Agent Zero agents.
    Connects to Zulip via event queue, forwards DMs and @mentions
    to Agent Zero via local A2A protocol, and posts responses back.
    """
    def __init__(self):
        # Zulip config from env vars
        self._site = (os.getenv("ZULIP_SITE") or "").rstrip("/")
        self._email = os.getenv("ZULIP_EMAIL") or ""
        self._api_key = os.getenv("ZULIP_API_KEY") or ""
        self._agent_name = os.getenv("ZULIP_AGENT_NAME") or "kagentz"
        self._stream = os.getenv("ZULIP_STREAM") or "agent-hub"
        # A2A config
        self._a2a_url = os.getenv("A2A_URL") or DEFAULT_A2A_URL
        self._a2a_token = os.getenv("A2A_TOKEN") or DEFAULT_A2A_TOKEN
        # State
        self._auth_header = self._build_auth()
        self._http_client: Optional[httpx.AsyncClient] = None
        self._queue_id: Optional[str] = None
        self._last_event_id: int = -1
        self._bot_user_id: Optional[int] = None
        self._bot_email: str = self._email
        self._running = False
        self._poll_task: Optional[asyncio.Task] = None
        # Stats
        self._messages_processed = 0
        self._poll_count = 0
        self._reconnects = 0
        self._last_heartbeat = 0.0
        self._last_event_time = time.time()
        self._a2a_sessions: dict = {}  # chat_id -> A2A context_id
    def _build_auth(self) -> str:
        import base64
        token = base64.b64encode(f"{self._email}:{self._api_key}".encode()).decode()
        return f"Basic {token}"
    async def start(self):
        """Start the adapter — connect to Zulip and begin polling."""
        if not all([self._site, self._email, self._api_key]):
            logger.error("Missing Zulip credentials. Set ZULIP_SITE, ZULIP_EMAIL, ZULIP_API_KEY")
            return False
        if not httpx:
            logger.error("httpx not installed")
            return False
        self._running = True
        self._http_client = httpx.AsyncClient(timeout=30.0)
        # Connect to Zulip
        if not await self._connect():
            return False
        logger.info(f"Adapter started for {self._agent_name} ({self._email})")
        return True
    async def stop(self):
        """Stop the adapter."""
        self._running = False
        if self._poll_task:
            self._poll_task.cancel()
            try:
                await self._poll_task
            except asyncio.CancelledError:
                pass
        if self._http_client:
            await self._http_client.aclose()
    async def _connect(self) -> bool:
        """Register Zulip event queue."""
        try:
            resp = await self._api_call("POST", "/api/v1/register", data={
                "event_types": '["message"]',
                "apply_markdown": "true",
            })
            if not resp:
                logger.error("Queue registration failed")
                return False
            self._queue_id = resp.get("queue_id")
            self._last_event_id = resp.get("last_event_id", -1)
            self._bot_user_id = resp.get("user_id")
            # Resolve bot user_id if not provided by register
            if self._bot_user_id is None:
                me = await self._api_call("GET", "/api/v1/users/me")
                if me:
                    self._bot_user_id = me.get("user_id")
            logger.info(
                f"Connected to Zulip as {self._email} "
                f"(queue={self._queue_id}, bot_id={self._bot_user_id})"
            )
            # Start poll loop
            self._poll_task = asyncio.create_task(self._poll_forever())
            return True
        except Exception as e:
            logger.error(f"Connection failed: {e}")
            return False
    async def _poll_forever(self):
        """Main poll loop."""
        backoff = 0
        while self._running:
            if not self._queue_id:
                await asyncio.sleep(1)
                continue
            try:
                events = await self._fetch_events()
                self._poll_count += 1
                for event in events:
                    try:
                        await self._process_event(event)
                    except Exception as e:
                        logger.warning(f"Event processing error: {e}")
                backoff = 0
                # Heartbeat
                now = time.time()
                if now - self._last_heartbeat > HEARTBEAT_INTERVAL:
                    self._last_heartbeat = now
                    silence = now - self._last_event_time
                    logger.info(
                        f"Heartbeat — polls={self._poll_count} "
                        f"processed={self._messages_processed} "
                        f"silence={silence:.0f}s reconnects={self._reconnects}"
                    )
            except asyncio.CancelledError:
                break
            except Exception as e:
                err = str(e)
                if "BAD_EVENT_QUEUE_ID" in err:
                    logger.info("Queue expired, reconnecting...")
                    await self._reconnect()
                    continue
                delay = RECONNECT_BACKOFF[min(backoff, len(RECONNECT_BACKOFF) - 1)]
                backoff += 1
                logger.warning(f"Poll error: {e}")
                await asyncio.sleep(delay)
            await asyncio.sleep(DEFAULT_POLL_INTERVAL)
    async def _fetch_events(self) -> list:
        """Fetch events from Zulip queue. Raises on BAD_EVENT_QUEUE_ID."""
        resp, status = await self._api_call("GET", "/api/v1/events", params={
            "queue_id": self._queue_id,
            "last_event_id": str(self._last_event_id),
            "dont_block": "true",
        }, return_status=True)
        # Detect queue expiry
        if status == 400:
            raise RuntimeError("BAD_EVENT_QUEUE_ID: queue expired")
        if not resp:
            return []
        events = resp.get("events", [])
        for event in events:
            eid = event.get("id", 0)
            if eid > self._last_event_id:
                self._last_event_id = eid
        return [e for e in events if e.get("type") == "message"]
    async def _reconnect(self):
        """Re-register event queue."""
        self._queue_id = None
        try:
            resp = await self._api_call("POST", "/api/v1/register", data={
                "event_types": '["message"]',
                "apply_markdown": "true",
            })
            if resp:
                self._queue_id = resp.get("queue_id")
                self._last_event_id = resp.get("last_event_id", -1)
                self._reconnects += 1
                logger.info(f"Reconnected, queue={self._queue_id}")
        except Exception as e:
            logger.error(f"Reconnect failed: {e}")
    async def _process_event(self, event: dict):
        """Process a Zulip message event."""
        msg = event.get("message", {})
        msg_type = msg.get("type", "")
        sender_email = msg.get("sender_email", "")
        sender_name = msg.get("sender_full_name", "Unknown")
        sender_id = msg.get("sender_id")
        content = msg.get("content", "")
        # Ignore own messages
        if sender_email == self._bot_email:
            return
        # Determine targeting
        mentioned_users = msg.get("mentioned_users", []) or []
        mentioned_ids = [u.get("user_id") for u in mentioned_users if isinstance(u, dict)]
        is_dm = msg_type == "private"
        is_mention = self._bot_user_id and self._bot_user_id in mentioned_ids
        if is_dm:
            self._messages_processed += 1
            self._last_event_time = time.time()
            logger.info(f"DM from {sender_name}: {content[:80]}...")
            # Send typing indicator
            await self._typing(sender_id, "start")
            # Send placeholder
            placeholder_id = await self._send_msg("private", str(sender_id), 
                ":robot: _Processing your message..._")
            # Forward to Agent Zero via A2A
            response = await self._a2a_chat(sender_name, content)
            # Stop typing
            await self._typing(sender_id, "stop")
            # Post response
            if response and placeholder_id:
                await self._edit_msg(placeholder_id, response[:MAX_ZULIP_MSG])
                logger.info(f"Responded to {sender_name} ({len(response)} chars)")
            elif response:
                await self._send_msg("private", str(sender_id), response[:MAX_ZULIP_MSG])
    async def _a2a_chat(self, sender_name: str, message: str) -> Optional[str]:
        """Send message to Agent Zero via local A2A protocol with session memory."""
        try:
            # Use sender_name as stable session key so conversation persists
            session_id = f"zulip-{sender_name.lower().replace(' ', '-')}"
            a2a_payload = {
                "jsonrpc": "2.0",
                "method": "tasks/send",
                "params": {
                    "id": f"zulip-{int(time.time())}",
                    "message": {
                        "role": "user",
                        "parts": [{"text": f"[Zulip DM from {sender_name}]: {message}"}]
                    },
                    "metadata": {
                        "session_id": session_id
                    }
                },
                "id": 1
            }
            headers = {
                "Content-Type": "application/json",
                "Authorization": f"Bearer {self._a2a_token}",
            }
            async with httpx.AsyncClient(timeout=120.0) as client:
                # Send the message to Agent Zero
                resp = await client.post(
                    self._a2a_url,
                    json=a2a_payload,
                    headers=headers,
                )
                if resp.status_code != 200:
                    logger.error(f"A2A send failed: HTTP {resp.status_code}")
                    return f":warning: Failed to reach agent. Error: HTTP {resp.status_code}"
                result = resp.json()
                task_id = result.get("result", {}).get("id")
                if not task_id:
                    logger.error("A2A: no task_id returned")
                    return ":warning: Agent did not create a task."
                # Poll for completion
                for _ in range(60):  # max 60s wait
                    await asyncio.sleep(1)
                    status_resp = await client.post(
                        self._a2a_url,
                        json={
                            "jsonrpc": "2.0",
                            "method": "tasks/get",
                            "params": {"id": task_id},
                            "id": 2
                        },
                        headers=headers,
                    )
                    if status_resp.status_code != 200:
                        continue
                    status_data = status_resp.json()
                    result_data = status_data.get("result", {})
                    state = result_data.get("status", {}).get("state", "")
                    if state == "completed":
                        # Extract response text
                        return self._extract_a2a_response(result_data)
                    elif state in ("failed", "error"):
                        error_msg = result_data.get("status", {}).get("message", {}).get("text", "Unknown error")
                        return f":warning: Agent processing failed: {error_msg}"
                return ":hourglass: Agent did not complete in time."
        except httpx.TimeoutException:
            return ":hourglass: Agent request timed out."
        except Exception as e:
            logger.error(f"A2A error: {e}")
            return f":warning: Communication error: {type(e).__name__}"
    def _extract_a2a_response(self, result: dict) -> str:
        """Extract assistant text from A2A response."""
        history = result.get("history", [])
        for msg in reversed(history):
            if isinstance(msg, dict) and msg.get("role") == "assistant":
                parts = msg.get("parts", [])
                texts = [p.get("text", "") for p in parts if isinstance(p, dict)]
                text = "\n".join(t for t in texts if t)
                if text:
                    return text
        artifacts = result.get("artifacts", [])
        for artifact in reversed(artifacts):
            if isinstance(artifact, dict):
                text = artifact.get("text") or artifact.get("content") or ""
                if text:
                    return text
        return "(no response)"
    # ── Zulip API ──
    async def _api_call(self, method: str, path: str, 
                        data: dict = None, params: dict = None,
                        return_status: bool = False) -> Any:
        """Make Zulip API call.
        Returns: dict response body, or if return_status=True returns (dict, int)
        """
        if not self._http_client:
            return (None, 0) if return_status else None
        url = f"{self._site}{path}"
        headers = {"Authorization": self._auth_header}
        try:
            if method == "GET":
                resp = await self._http_client.get(url, params=params, headers=headers)
            elif method == "POST":
                resp = await self._http_client.post(url, data=data, headers=headers)
            elif method == "PATCH":
                resp = await self._http_client.patch(url, data=data, headers=headers)
            else:
                return (None, 0) if return_status else None
            if resp.status_code >= 400:
                logger.debug(f"API {method} {path}: {resp.status_code}")
                return (None, resp.status_code) if return_status else None
            body = resp.json()
            return (body, resp.status_code) if return_status else body
        except Exception as e:
            logger.debug(f"API error {method} {path}: {e}")
            return (None, 0) if return_status else None
    async def _send_msg(self, msg_type: str, to: str, content: str) -> Optional[int]:
        """Send a message to Zulip."""
        payload = {"type": msg_type, "content": content}
        if msg_type == "private":
            payload["to"] = json.dumps([int(to)])
        else:
            payload["to"] = to
            payload["subject"] = "general"
        resp = await self._api_call("POST", "/api/v1/messages", data=payload)
        if resp and resp.get("id"):
            return resp["id"]
        return None
    async def _edit_msg(self, message_id: int, content: str):
        """Edit a Zulip message."""
        await self._api_call("PATCH", f"/api/v1/messages/{message_id}",
                             data={"content": content})
    async def _typing(self, user_id: int, op: str):
        """Send typing indicator."""
        if not user_id:
            return
        to_data = json.dumps([user_id])
        await self._api_call("POST", "/api/v1/typing",
                             data={"to": to_data, "op": op})
    def run(self):
        """Synchronous entry point."""
        asyncio.run(self._run_async())
    async def _run_async(self):
        try:
            if await self.start():
                # Keep running until stopped
                while self._running:
                    await asyncio.sleep(1)
        except asyncio.CancelledError:
            pass
        finally:
            await self.stop()
 # ── Entry point ──
 def main():
    """CLI entry point."""
    logging.basicConfig(
        level=logging.INFO,
        format="%(asctime)s [%(name)s] %(levelname)s: %(message)s",
        datefmt="%Y-%m-%d %H:%M:%S",
    )
    adapter = AgentZeroZulipAdapter()
    try:
        adapter.run()
    except KeyboardInterrupt:
        logger.info("Shutdown requested")
    # Handle signals
    import signal
    shutdown = asyncio.Event()
    def _handle_signal():
        shutdown.set()
    loop = asyncio.new_event_loop()
    asyncio.set_event_loop(loop)
    try:
        loop.add_signal_handler(signal.SIGTERM, _handle_signal)
        loop.add_signal_handler(signal.SIGINT, _handle_signal)
    except NotImplementedError:
        pass
    async def _run():
        if await adapter.start():
            await shutdown.wait()
        await adapter.stop()
    try:
        loop.run_until_complete(_run())
    except KeyboardInterrupt:
        pass
    finally:
        loop.close()
 if __name__ == "__main__":
    main()
@@ -1,20 +1,8 @@
-# Zulip Multi-Platform Agent Communication — Architecture (v2)
+# 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 (Hermes Native Plugin — Current)
 As of v1.0.0, Hermes agents (Tanko, Mumuni, Koonimo, Koby) use the **Hermes native platform plugin**
 at `~/.hermes/plugins/platforms/zulip/`. This replaces the old standalone systemd service.
 Benefits of the native plugin:
 - Extends `BasePlatformAdapter` — zero changes to Hermes core
 - Auto-registers via `register(ctx)` at Gateway startup
 - Direct session injection (no subprocess overhead)
 - Leverages Gateway's built-in health checks, config, and error handling
 - Unified logging with all other Hermes platform adapters
 ## Architecture Diagram
 ```
 ┌─────────────────────────────────────────────────────────────┐
@@ -78,31 +66,18 @@ User types: @all-bots status report
 - **Swarm Development**: The "Swarm" refers to our collaborative development methodology where multiple agents/developers work on different components of the plugin simultaneously.
-### Hermes (Python) — BasePlatformAdapter (CURRENT)
+### Hermes (Python) — BasePlatformAdapter
- Path: `plugins/platforms/zulip/`
+- Path: `hermes-zulip-plugin/src/hermes_zulip/`
 - Deploy: `~/.hermes/plugins/platforms/zulip/`
 - Implements: `BasePlatformAdapter` (Hermes Gateway)
- Config: Hermes `config.yaml` under `platforms.zulip.extra` or env vars
+- Config: `config.yaml` per-agent
- Entry point: `plugin.yaml` + `register(ctx)` (Hermes manifest)
+- Entry point: `plugin.yaml` (Hermes manifest)
 - Versions: Gen 3 (v1.0.0) — 1,169 lines, 14/14 Success Criteria met
 - Features: DM-first, placeholder→edit streaming, dedup, self-test, health stats, @all-bots resolution
-### Agent Zero — A0 Plugin System (LEGACY — to migrate)
+### 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 (CURRENT)
+### pi (TypeScript) — pi Extension API
 - Path: `pi-zulip-extension/`
 - Deploy: PM2-managed process
 - Runs under `pi --mode rpc --session-id zulip-service`
 - Active: abiba-bot only (ZULIP_EXTENSION_ACTIVE=true guard)
 ### Legacy Hermes Plugin (DEPRECATED)
 - OLD path: `hermes-zulip-plugin/src/hermes_zulip/`
 - OLD deploy: `/opt/hermes-zulip-plugin/` + systemd service
 - Status: Replaced by `plugins/platforms/zulip/` native plugin as of v1.0.0
 - Migration: See `hermes-zulip-plugin/DEPRECATED.md`
 - Path: `pi-zulip-extension/src/`
 - Implements: pi extension (TypeScript module in `~/.pi/agent/extensions/`)
 - Config: `config.yaml` per-agent
@@ -1,89 +0,0 @@
 # Gitea Actions Runner Setup
 ## Prerequisites
 - Gitea admin access (root user or token with admin:actions scope)
 - Docker on the runner host (CT 116 recommended — already has Docker)
 ## Step 1: Get Runner Registration Token
 ```bash
 # On the Gitea host (CT 110) or via Gitea admin API:
 ssh root@192.168.68.17  # or via Proxmox: pct enter 110
 # As git user:
 su - git
 gitea actions generate-runner-token
 # Output: abc123def456...
 ```
 Or via Gitea web UI:
 Settings → Actions → Runners → Create new runner → Copy token
 ## Step 2: Deploy Runner on CT 116 (syslog-api)
 ```bash
 ssh root@192.168.68.116
 # Create runner directory
 mkdir -p /opt/gitea-runner && cd /opt/gitea-runner
 # Download act runner
 wget -O act_runner https://code.gitea.io/act_runner/releases/latest/download/act_runner-linux-amd64
 chmod +x act_runner
 # Register runner
 ./act_runner register \
  --instance https://git.sysloggh.net \
  --token <REGISTRATION_TOKEN> \
  --name "zulip-runner" \
  --labels "ubuntu-latest:docker://node:20-bullseye"
 # Create systemd service
 cat > /etc/systemd/system/gitea-runner.service << 'SERVICE'
 [Unit]
 Description=Gitea Actions Runner
 After=docker.service
 [Service]
 ExecStart=/opt/gitea-runner/act_runner daemon
 WorkingDirectory=/opt/gitea-runner
 Restart=always
 RestartSec=5
 User=root
 [Install]
 WantedBy=multi-user.target
 SERVICE
 systemctl daemon-reload
 systemctl enable --now gitea-runner
 ```
 ## Step 3: Verify
 ```bash
 journalctl -u gitea-runner -f --no-pager
 # Look for: "runner registered" or "listening for jobs"
 # In Gitea UI: Settings → Actions → Runners → should show "zulip-runner" active
 ```
 ## Step 4: Test
 Push a tag to trigger the pipeline:
 ```bash
 git tag v1.1.0-rc.1   # Canary → Tanko only
 git push origin v1.1.0-rc.1
 # If canary passes:
 git tag v1.1.0          # Production → all Hermes
 git push origin v1.1.0
 # For Agent Zero:
 git tag az-v1.0.0       # Agent Zero → kagentz
 git push origin az-v1.0.0
 ```
 ## Tag Convention
 | Tag Pattern | Deploys To | Environment |
 |------------|------------|-------------|
 | `v*.*.*-rc.*` | Tanko only | `canary` |
 | `v*.*.*` | All Hermes agents | `production` |
 | `az-v*.*.*` | kagentz only | `agent-zero` |
@@ -1,40 +0,0 @@
 # DEPRECATED — Hermes Zulip Plugin (Legacy)
 **Status:** Deprecated as of 2026-06-25
 **Replaced by:** `plugins/platforms/zulip/` (Hermes native platform plugin)
 This directory contains the original standalone Hermes Zulip plugin that ran as a
 systemd service with its own poll loop, subprocess agent invocation, and health
 server.
 ## Why Deprecated
 The new `plugins/platforms/zulip/` plugin is a proper Hermes platform plugin that:
 - Extends `BasePlatformAdapter` from the Hermes Gateway
 - Auto-registers via the Hermes plugin system (`register(ctx)`)
 - Uses direct session injection (no subprocess overhead)
 - Leverages Gateway's built-in health checks, config management, and error handling
 - Requires zero changes to core Hermes code
 ## Migration
 Remove the old systemd service and deploy the new plugin:
 ```bash
 # 1. Stop old service
 systemctl stop zulip-plugin
 systemctl disable zulip-plugin
 # 2. Install plugin to ~/.hermes/plugins/platforms/zulip/
 cp -r plugins/platforms/zulip/ ~/.hermes/plugins/platforms/zulip/
 # 3. Restart Hermes Gateway
 hermes gateway restart
 ```
 Config moves from:
 - `/opt/hermes-zulip-plugin/config.yaml` → Hermes `config.yaml` under `platforms: zulip:`
 - Or set `ZULIP_SITE`, `ZULIP_EMAIL`, `ZULIP_API_KEY` env vars
 See `plugins/platforms/zulip/plugin.yaml` for configuration reference.
@@ -1,146 +1,11 @@
 """
 Hermes Zulip Plugin — Core adapter for Hermes Python agents
-Connects Hermes agents (Tanko, Mumuni, Koonimo, Koby) to the Sysloggh
+Implements BasePlatformAdapter to connect Hermes agents (Tanko, Mumuni,
-Zulip agent mesh via event queue polling + subprocess agent invocation.
+Koonimo, Koby) to the Sysloggh Zulip agent mesh.
 Architecture mirrors pi-zulip-extension:
  Zulip event queue → poll loop → parse message → spawn agent subprocess
  → capture stdout → post response to Zulip (with placeholder + edit)
 Usage (systemd service):
    python3 -m hermes_zulip --config /path/to/config.yaml
 Path: hermes-zulip-plugin/src/hermes_zulip/
 Config: config.yaml (per-agent, deployed alongside plugin)
@see ADR-001 DM-first, ADR-005 @mention detection
@see ADR-006 @all-bots, ADR-009 error handling
 """
-import argparse
+__version__ = "0.1.0"
 import logging
 import sys
 from typing import Dict, Any
 # Ensure the src directory is on the path for the adapter import
 import os
 import sys
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
 from hermes_zulip.adapter import ZulipAdapter
 __version__ = "0.2.0"
 def load_config(config_path: str) -> Dict[str, Any]:
    """Load YAML config and inject env vars."""
    import yaml
    with open(config_path) as f:
        cfg = yaml.safe_load(f)
    # Override api_key from env if set
    env_key = os.environ.get("ZULIP_API_KEY")
    if env_key:
        cfg.setdefault("zulip", {})["api_key"] = env_key
    return cfg
 def setup_logging(cfg: Dict[str, Any]) -> None:
    """Configure logging from config."""
    level = (
        cfg.get("monitoring", {}).get("log_level", "INFO").upper()
    )
    logging.basicConfig(
        level=getattr(logging, level, logging.INFO),
        format="%(asctime)s [%(name)s] %(levelname)s: %(message)s",
        datefmt="%Y-%m-%d %H:%M:%S",
    )
 def start_health_server(cfg: Dict[str, Any], adapter: ZulipAdapter) -> None:
    """Start a minimal health HTTP endpoint in a background thread."""
    import threading
    from http.server import HTTPServer, BaseHTTPRequestHandler
    port = cfg.get("monitoring", {}).get("health_port", 9200)
    start_time = time.time()
    class HealthHandler(BaseHTTPRequestHandler):
        def do_GET(self) -> None:
            if self.path in ("/", "/health"):
                import json
                body = json.dumps({
                    "status": "ok",
                    "agent": cfg.get("agent", {}).get("name", "unknown"),
                    "connected": adapter.connected,
                    "uptime_seconds": int(time.time() - start_time),
                    "timestamp": datetime.utcnow().isoformat(),
                })
                self.send_response(200)
                self.send_header("Content-Type", "application/json")
                self.end_headers()
                self.wfile.write(body.encode())
            else:
                self.send_response(404)
                self.end_headers()
        def log_message(self, fmt, *args):
            pass  # Suppress health check log spam
    server = HTTPServer(("127.0.0.1", port), HealthHandler)
    thread = threading.Thread(target=server.serve_forever, daemon=True)
    thread.start()
    logging.getLogger(__name__).info(f"Health endpoint on :{port}")
 def main() -> None:
    """CLI entry point for the Hermes Zulip plugin.
    Usage:
        python3 -m hermes_zulip --config /path/to/config.yaml
    """
    import time
    from datetime import datetime
    parser = argparse.ArgumentParser(
        description="Hermes Zulip Plugin — Connects Hermes agents to Zulip"
    )
    parser.add_argument(
        "--config", "-c",
        default="config.yaml",
        help="Path to config.yaml (default: config.yaml)",
    )
    args = parser.parse_args()
    # Load config
    cfg = load_config(args.config)
    setup_logging(cfg)
    logger = logging.getLogger(__name__)
    logger.info(
        f"Starting Hermes Zulip Plugin v{__version__} "
        f"for {cfg.get('agent', {}).get('name', 'unknown')}"
    )
    # Create adapter
    adapter = ZulipAdapter(cfg)
    # Start health endpoint (if enabled)
    if cfg.get("monitoring", {}).get("health_endpoint_enabled", True):
        start_health_server(cfg, adapter)
    # Run the event loop (blocks until interrupted)
    try:
        adapter.run()
    except KeyboardInterrupt:
        logger.info("Shutting down...")
    except Exception as e:
        logger.error(f"Fatal error: {e}")
        sys.exit(1)
 if __name__ == "__main__":
    main()
@@ -1,100 +1,50 @@
-"""
+# Core adapter  implements BasePlatformAdapter for Zulip
-Core Zulip adapter for Hermes agents (Tanko, Mumuni, Koonimo, Koby).
+# See ADR-005 for @mention detection, ADR-009 for error handling
 # Full implementation in issue #5.
 Architecture (mirrors pi-zulip-extension):
  Zulip event queue → poll loop → parse message → spawn agent subprocess
  → capture stdout → post response to Zulip
 The Hermes agent is invoked as a subprocess (configurable command) so the
 plugin remains decoupled from the agent runtime. In a future iteration,
 this could switch to a direct IPC/socket if the agent exposes one.
 See ADR-005 (@mention detection), ADR-006 (@all-bots), ADR-009 (error handling).
 """
 import asyncio
 import json
 import logging
 import re
 import shlex
 import subprocess
 import time
-from datetime import datetime
+import re
 import threading
 from typing import Any, Dict, Optional
 logger = logging.getLogger(__name__)
 # Regex to strip Zulip mention artifacts from message bodies (ADR-008)
 MENTION_CLEANER = re.compile(r'@\*\*[^*]+\*\*')
 class ZulipAdapter:
-    """Zulip adapter for Hermes agents.
+    """Zulip adapter for Hermes agents. Connects to Zulip, listens for
    @mentions in #agent-hub, routes messages via BasePlatformAdapter."""
-    Connects to Zulip via event queues (not the deprecated call_on_each_message),
+    # Regex to strip Zulip mention artifacts from message bodies (ADR-008)
-    polls for new events, routes @mentions and DMs to the Hermes agent via
+    MENTION_CLEANER = re.compile(r'@\*\*[^*]+\*\*')
    subprocess, and posts responses back to Zulip.
    """
    def __init__(self, config: Dict[str, Any]) -> None:
        self.config = config
        self.connected = False
        self._client = None
-        self._queue_id: Optional[str] = None
+        self._thread = None
-        self._last_event_id: int = -1
+        self._stop_event = threading.Event()
        self._poll_task: Optional[asyncio.Task] = None
        # Agent subprocess config
        self._agent_command: str = config.get("agent", {}).get(
            "command", "hermes chat"
        )
        self._agent_timeout: int = config.get("error_handling", {}).get(
            "timeout_seconds", 60
        )
        # Bot identity for filtering own messages
        self._bot_email: str = config.get("zulip", {}).get("email", "")
        self._bot_id: int = config.get("swarm", {}).get("bot_id", 0)
        # Stream config
        self._stream: str = config.get("zulip", {}).get("stream", "agent-hub")
        self._all_bots_user_id: int = config.get("zulip", {}).get(
            "all_bots_user_id", 1
        )
    # ------------------------------------------------------------------
    # Connection lifecycle
    # ------------------------------------------------------------------
    async def connect(self) -> None:
-        """Connect to Zulip and register an event queue."""
+        """Establish connection to Zulip and start the event loop."""
        if self.connected:
            logger.info("Already connected to Zulip.")
            return
        try:
-            import zulip
+            from zulip import Client
            server_url = self.config['zulip']['server_url']
            email = self.config['zulip']['email']
            api_key = self.config['zulip']['api_key']
-            server_url = self.config["zulip"]["server_url"]
+            self._client = Client(server_url=server_url, email=email, api_key=api_key)
            email = self.config["zulip"]["email"]
            api_key = self.config["zulip"]["api_key"]
            self._client = zulip.Client(
                server_url=server_url, email=email, api_key=api_key
            )
            # Register an event queue (like the pi extension)
            queue_res = self._client.register(
                event_types=["message"]
            )
            self._queue_id = queue_res.get("queue_id")
            self._last_event_id = queue_res.get("last_event_id", -1)
            self.connected = True
            logger.info(f"Connected to Zulip: {server_url} as {email}")
-            logger.info(
+            # Start the event loop in a background thread
-                f"Connected to Zulip: {server_url} as {email} "
+            self._stop_event.clear()
-                f"(queue={self._queue_id})"
+            self._thread = threading.Thread(target=self._event_loop, daemon=True)
-            )
+            self._thread.start()
            logger.info("Zulip event loop started.")
        except Exception as e:
            logger.error(f"Failed to connect to Zulip: {e}")
@@ -102,422 +52,82 @@ class ZulipAdapter:
            raise
    async def disconnect(self) -> None:
-        """Disconnect and cancel the poll loop."""
+        """Disconnect from Zulip and stop the event loop."""
-        if self._poll_task:
+        if not self.connected:
-            self._poll_task.cancel()
+            return
-            try:
+        self._stop_event.set()
-                await self._poll_task
+        if self._thread:
-            except asyncio.CancelledError:
+            self._thread.join(timeout=5)
                pass
            self._poll_task = None
        self.connected = False
        logger.info("Disconnected from Zulip.")
-    # ------------------------------------------------------------------
+    async def send_message(self, topic: str, content: str) -> Dict[str, Any]:
-    # Event polling (async loop, like pi extension's setInterval)
+        """Send a message to Zulip with retry logic (ADR-009)."""
-    # ------------------------------------------------------------------
+        max_retries = self.config.get('error_handling', {}).get('retry_count', 3)
        retry_delay = self.config.get('error_handling', {}).get('retry_delay_seconds', 5)
-    async def poll_forever(self, poll_interval: float = 3.0) -> None:
+        for attempt in range(max_retries):
        """Continuously poll the Zulip event queue and process messages.
        This is the main event loop. Runs until cancelled.
        """
        while self.connected and self._client and self._queue_id:
            try:
-                events = await self._poll_events()
+                result = self._client.send_message({
-                for event in events:
+                    'type': 'stream',
-                    await self._process_event(event)
+                    'to': self.config['zulip']['stream'],
-            except asyncio.CancelledError:
+                    'subject': topic,
-                break
+                    'content': content,
                })
                logger.info(f"Message sent to {self.config['zulip']['stream']} > {topic} (attempt {attempt + 1})")
                return result
            except Exception as e:
-                logger.error(f"Poll error: {e}")
+                logger.warning(f"Failed to send message (attempt {attempt + 1}): {e}")
-                # Check for queue expiry
+                if attempt < max_retries - 1:
-                if "BAD_EVENT_QUEUE_ID" in str(e):
+                    time.sleep(retry_delay)
-                    logger.info("Queue expired, reconnecting...")
+                else:
-                    self.connected = False
+                    raise
                    await self._reconnect_with_retry()
                    continue
-            await asyncio.sleep(poll_interval)
+    async def on_event(self, event: Dict[str, Any]) -> Optional[Dict[str, Any]]:
-
+        """Process incoming Zulip events and route via BasePlatformAdapter."""
-    async def _poll_events(self) -> list:
+        if event.get('type') != 'message':
        """Fetch events from the Zulip event queue."""
        import zulip
        if not self._client or not self._queue_id:
            return []
        response = self._client.get_events(
            queue_id=self._queue_id,
            last_event_id=self._last_event_id,
            dont_block=True,
        )
        if response.get("result") != "success":
            raise RuntimeError(
                f"Events API error: {response.get('msg', 'unknown')}"
            )
        events = response.get("events", [])
        for event in events:
            if event.get("id", 0) > self._last_event_id:
                self._last_event_id = event["id"]
        return [e for e in events if e.get("type") == "message"]
    async def _reconnect_with_retry(self) -> None:
        """Retry connection with backoff."""
        retries = self.config.get("error_handling", {}).get("retry_count", 3)
        delay = self.config.get("error_handling", {}).get(
            "retry_delay_seconds", 5
        )
        for attempt in range(retries):
            logger.info(
                f"Reconnect attempt {attempt + 1}/{retries} "
                f"in {delay}s..."
            )
            await asyncio.sleep(delay)
            try:
                await self.connect()
                if self.connected:
                    logger.info("Reconnected successfully.")
                    return
            except Exception as e:
                logger.error(f"Reconnect attempt {attempt + 1} failed: {e}")
                delay *= 2  # Exponential backoff
        logger.error("Max reconnection retries reached. Giving up.")
    # ------------------------------------------------------------------
    # Message processing
    # ------------------------------------------------------------------
    async def _process_event(self, event: Dict[str, Any]) -> None:
        """Route a Zulip message event to the Hermes agent."""
        msg = event.get("message", {})
        msg_type = msg.get("type", "")  # "private" or "stream"
        sender_email = msg.get("sender_email", "")
        sender_name = msg.get("sender_full_name", "Unknown")
        content = msg.get("content", "")
        # Ignore own messages
        if sender_email == self._bot_email:
            return
        # Determine if this message targets this bot
        mentioned_users = msg.get("mentioned_users", [])
        mentioned_user_ids = [u.get("user_id") for u in mentioned_users]
        is_dm = msg_type == "private"
        is_mention = self._bot_id in mentioned_user_ids
        is_all_bots = self._all_bots_user_id in mentioned_user_ids
        # DM-first: process all private messages (like ADR-001/ADR-002)
        if is_dm:
            logger.info(f"DM from {sender_name}: {content[:80]}...")
            await self._route_to_agent(
                message_type="dm",
                sender_name=sender_name,
                content=content,
                recipient=sender_email,
            )
            return
        # Stream: only respond to @mentions and @all-bots (ADR-005, ADR-006)
        if msg_type == "stream" and (is_mention or is_all_bots):
            stream_name = msg.get("display_recipient", "unknown")
            topic = msg.get("subject", "general")
            logger.info(
                f"{'@mention' if is_mention else '@all-bots'} "
                f"in #{stream_name} > {topic}"
            )
            # Clean @mention artifacts from content (ADR-008)
            clean_content = MENTION_CLEANER.sub("", content).strip()
            await self._route_to_agent(
                message_type="mention" if is_mention else "all-bots",
                sender_name=sender_name,
                content=clean_content,
                recipient=stream_name,
                topic=topic,
                stream_id=msg.get("stream_id"),
            )
    async def _route_to_agent(
        self,
        message_type: str,
        sender_name: str,
        content: str,
        recipient: str,
        topic: Optional[str] = None,
        stream_id: Optional[int] = None,
    ) -> None:
        """Send the message to the Hermes agent subprocess and relay the
        response back to Zulip.
        Architecture note: This uses a subprocess (configurable via
        agent.command in config.yaml). This mirrors the initial pi extension
        approach. A future iteration could use IPC or a socket if the
        Hermes agent exposes one.
        """
        # 1. Send typing indicator
        await self._send_typing_indicator(recipient, "start")
        # 2. Send a "Thinking..." placeholder to Zulip immediately.
        #    On agent_end, this message will be edited with the final response.
        placeholder = (
            f":robot: _Processing your message..._"
        )
        placeholder_msg_id = None
        try:
            placeholder_msg_id = await self._send_message(
                message_type=message_type,
                recipient=recipient,
                content=placeholder,
                topic=topic,
                stream_id=stream_id,
            )
        except Exception as e:
            logger.warning(f"Failed to send placeholder: {e}")
        # 3. Invoke the Hermes agent subprocess
        response_text = await self._invoke_agent(content, sender_name)
        # 4. Stop typing indicator
        await self._send_typing_indicator(recipient, "stop")
        # 5. Post (or edit) the response
        if not response_text.strip():
            logger.warning(
                f"Hermes agent returned empty response for "
                f"{message_type} from {sender_name}"
            )
            return
        # Truncate to Zulip's 10K char limit
        MAX_ZULIP_MSG = 10000
        truncated = (
            response_text[:MAX_ZULIP_MSG]
            + "\n\n[...truncated at Zulip limit]"
            if len(response_text) > MAX_ZULIP_MSG
            else response_text
        )
        try:
            if placeholder_msg_id:
                await self._edit_message(placeholder_msg_id, truncated)
                logger.info(
                    f"Finalized response to {sender_name} "
                    f"({len(truncated)} chars)"
                )
            else:
                await self._send_message(
                    message_type=message_type,
                    recipient=recipient,
                    content=truncated,
                    topic=topic,
                    stream_id=stream_id,
                )
                logger.info(
                    f"Sent response to {sender_name} "
                    f"({len(truncated)} chars)"
                )
        except Exception as e:
            logger.error(f"Failed to post response: {e}")
    # ------------------------------------------------------------------
    # Hermes agent subprocess invocation
    # ------------------------------------------------------------------
    async def _invoke_agent(
        self, message: str, sender_name: str
    ) -> str:
        """Spawn the Hermes agent subprocess with the message.
        The agent command is configurable (agent.command in config.yaml).
        Default: "hermes chat"
        The message is passed via stdin (pipe). The agent's stdout is
        captured as the response.
        This is synchronous (run in executor) to avoid blocking the
        event loop during subprocess execution.
        """
        cmd_str = self._agent_command
        cmd = shlex.split(cmd_str)
        logger.info(
            f"Invoking agent: {' '.join(cmd)} "
            f"(timeout={self._agent_timeout}s)"
        )
        def _run() -> str:
            try:
                result = subprocess.run(
                    cmd,
                    input=message,
                    capture_output=True,
                    text=True,
                    timeout=self._agent_timeout,
                )
                if result.returncode != 0:
                    stderr = result.stderr.strip()
                    logger.error(
                        f"Agent exited with code {result.returncode}: "
                        f"{stderr}"
                    )
                    return (
                        f":warning: Agent error (exit {result.returncode}). "
                        f"Please try again later."
                    )
                return result.stdout.strip()
            except subprocess.TimeoutExpired:
                logger.error(
                    f"Agent timed out after {self._agent_timeout}s"
                )
                return (
                    f":hourglass: Agent timed out after "
                    f"{self._agent_timeout}s. Please try again."
                )
            except FileNotFoundError:
                logger.error(f"Agent command not found: {cmd_str}")
                return (
                    f":warning: Agent command not found: `{cmd_str}`. "
                    f"Check configuration."
                )
            except Exception as e:
                logger.error(f"Agent invocation error: {e}")
                return (
                    f":warning: Failed to invoke agent: {e}"
                )
        return await asyncio.get_event_loop().run_in_executor(None, _run)
    # ------------------------------------------------------------------
    # Zulip API helpers
    # ------------------------------------------------------------------
    async def _send_message(
        self,
        message_type: str,
        recipient: str,
        content: str,
        topic: Optional[str] = None,
        stream_id: Optional[int] = None,
    ) -> Optional[int]:
        """Send a message to Zulip. Returns the message ID if successful."""
        if not self._client:
            return None
-        def _send() -> Optional[int]:
+        msg = event.get('message', {})
-            if message_type in ("dm", "private"):
+        mentioned_users = msg.get('mentioned_users', False)
                # Private message: recipient is email
                payload = {
                    "type": "private",
                    "to": [recipient],
                    "content": content,
                }
            else:
                # Stream message
                payload = {
                    "type": "stream",
                    "to": stream_id or recipient,
                    "subject": topic or "general",
                    "content": content,
                }
-            try:
+        # Only process messages that mention this bot (ADR-005)
-                result = self._client.send_message(payload)
+        if not mentioned_users:
-                if result.get("result") == "success":
+            return None
                    return result.get("id")
                logger.error(
                    f"Send message failed: {result.get('msg', 'unknown')}"
                )
                return None
            except Exception as e:
                logger.error(f"Send message error: {e}")
                return None
-        return await asyncio.get_event_loop().run_in_executor(None, _send)
+        # Strip Zulip formatting artifacts
        body = msg.get('content', '')
        clean_body = self.MENTION_CLEANER.sub('', body)
        clean_body = clean_body.strip()
-    async def _edit_message(
+        # Construct the MessageEvent for BasePlatformAdapter
-        self, message_id: int, content: str
+        return {
-    ) -> bool:
+            'type': 'MessageEvent',
-        """Edit a previously sent Zulip message (for streaming updates)."""
+            'sender': msg.get('sender_full_name', 'Unknown'),
-        if not self._client:
+            'body': clean_body,
-            return False
+            'topic': msg.get('subject', 'Unknown Topic'),
            'stream': msg.get('stream', 'Unknown Stream'),
            'timestamp': msg.get('timestamp', 0),
        }
-        def _edit() -> bool:
+    def _event_loop(self) -> None:
-            try:
+        """Background thread to listen for Zulip events."""
                result = self._client.update_message(
                    {"message_id": message_id, "content": content}
                )
                if result.get("result") != "success":
                    logger.warning(
                        f"Edit message {message_id}: "
                        f"{result.get('msg', 'unknown')}"
                    )
                return result.get("result") == "success"
            except Exception as e:
                logger.warning(f"Edit message {message_id} error: {e}")
                return False
        return await asyncio.get_event_loop().run_in_executor(None, _edit)
    async def _send_typing_indicator(
        self, recipient: str, operation: str
    ) -> None:
        """Send a typing indicator (start/stop)."""
        if not self._client:
            return
        def _typing() -> None:
            try:
                # The zulip Python library doesn't have a direct typing API
                # Use the REST endpoint directly via requests
                import requests
                server_url = self.config["zulip"]["server_url"]
                email = self.config["zulip"]["email"]
                api_key = self.config["zulip"]["api_key"]
                # For private messages, recipient is the user's email
                # We need their user_id. Use the API directly.
                to_data = json.dumps([recipient])
                requests.post(
                    f"{server_url}/api/v1/typing",
                    auth=requests.auth.HTTPBasicAuth(email, api_key),
                    data={"to": to_data, "op": operation},
                    timeout=5,
                )
            except Exception as e:
                # Non-critical
                pass
        await asyncio.get_event_loop().run_in_executor(None, _typing)
    # ------------------------------------------------------------------
    # Synchronous entry point for the Hermes runner
    # ------------------------------------------------------------------
    def run(self) -> None:
        """Synchronous entry point that starts the async poll loop.
        Called by the Hermes runner (e.g., from a systemd service).
        """
        asyncio.run(self._run_async())
    async def _run_async(self) -> None:
        """Async entry point."""
        try:
-            await self.connect()
+            self._client.call_on_each_message(
-            if self.connected:
+                lambda event: self._process_event(event),
-                logger.info("Starting event poll loop...")
+            )
                await self.poll_forever()
        except asyncio.CancelledError:
            logger.info("Poll loop cancelled.")
        except Exception as e:
-            logger.error(f"Fatal error in event loop: {e}")
+            logger.error(f"Event loop crashed: {e}")
-        finally:
+            self.connected = False
-            await self.disconnect()
+
    def _process_event(self, event: Dict[str, Any]) -> None:
        """Bridge the synchronous event to the async on_event handler."""
        import asyncio
        try:
            loop = asyncio.get_event_loop()
            if loop.is_running():
                asyncio.create_task(self.on_event(event))
            else:
                asyncio.run(self.on_event(event))
        except Exception as e:
            logger.error(f"Error processing event: {e}")
@@ -1,71 +0,0 @@
 # Abiba Zulip Gateway — Standalone Service
 **Replaces** the old pi extension (`~/.pi/agent/extensions/zulip/`).
 Instead of injecting messages into pi's session (which dies when pi exits), this
 runs as an independent Node.js **systemd service** that:
 - Polls Zulip event queue for DMs
 - Calls the harness inference API directly (no pi dependency)
 - Maintains per-sender conversation memory
 - Survives pi shutdown and restart
 ## Architecture
 ```
 Zulip event queue → poll every 3s → DM detected
  → send typing indicator + placeholder
  → POST /v1/chat/completions with conversation history
  → edit placeholder with final response
 ```
 ## Requirements
 - Node.js 22+
 - `npm install` in this directory
 ## Config
 All config via environment variables. Copy `abiba-zulip.service` to set up as a
 systemd service, or run directly:
 ```bash
 ZULIP_EMAIL=abiba-bot@chat.sysloggh.net \
 ZULIP_API_KEY=your_key \
 ZULIP_SITE=https://chat.sysloggh.net \
 HARNESS_URL=http://192.168.68.116/v1/chat/completions \
 HARNESS_API_KEY=sk-xxx \
 HARNESS_MODEL=qwen3.6-35B-A3B \
 node dist/index.js
 ```
 ## Deploy as a service
 ```bash
 # 1. Install deps
 cd /opt/abiba-zulip
 npm install
 # 2. Build
 npx tsc
 # 3. Install systemd service
 cp abiba-zulip.service /etc/systemd/system/
 systemctl daemon-reload
 systemctl enable abiba-zulip
 systemctl start abiba-zulip
 # 4. Check status
 systemctl status abiba-zulip
 journalctl -u abiba-zulip -f
 # 5. Health check
 curl http://127.0.0.1:9200/health
 ```
 ## Development
 ```bash
 npm run dev    # watch mode (tsc watch)
 npm run build  # compile
 npm start      # run compiled
 ```
@@ -1,48 +0,0 @@
 [Unit]
 Description=Abiba Zulip Gateway Service — Standalone Zulip bot for pi agent
 Documentation=https://git.sysloggh.net/SyslogSolution/zulip-platform-plugins
 After=network-online.target
 Wants=network-online.target
 [Service]
 Type=simple
 User=root
 WorkingDirectory=/opt/abiba-zulip
 # ── Zulip credentials ─────────────────────────────────────────────────────
 Environment=ZULIP_EMAIL=abiba-bot@chat.sysloggh.net
 Environment=ZULIP_API_KEY=cKTDMZAPW08dk3zl05sStzO7HRztzyn8
 Environment=ZULIP_SITE=https://chat.sysloggh.net
 # ── Agent identity ─────────────────────────────────────────────────────────
 Environment=AGENT_NAME=abiba
 Environment=AGENT_OWNER_EMAIL=jerome@sysloggh.com
 # ── Harness API (inference) ────────────────────────────────────────────────
 Environment=HARNESS_URL=http://192.168.68.116/v1/chat/completions
 Environment=HARNESS_API_KEY=sk-856ffb0bbb-e5aaf78b10054eca608f8fbcbd73a889
 Environment=HARNESS_MODEL=qwen3.6-35B-A3B
 Environment=HARNESS_MAX_TOKENS=4096
 # ── Service config ─────────────────────────────────────────────────────────
 Environment=HEALTH_PORT=9200
 Environment=POLL_INTERVAL_MS=3000
 Environment=MAX_RETRIES=5
 Environment=RETRY_DELAY_MS=5000
 ExecStart=/usr/bin/node /opt/abiba-zulip/dist/index.js
 Restart=always
 RestartSec=5
 # Logging
 StandardOutput=journal
 StandardError=journal
 # Security hardening (optional — adjust as needed)
 NoNewPrivileges=true
 ProtectHome=read-only
 ProtectSystem=full
 PrivateTmp=true
 [Install]
 WantedBy=multi-user.target
@@ -1,19 +1,28 @@
 {
-  "name": "abiba-zulip-service",
+  "name": "pi-zulip-extension",
-  "version": "2.0.0",
+  "version": "0.1.0",
-  "description": "Standalone Zulip gateway service for Abiba (pi agent). Direct harness API, conversation memory, systemd service.",
+  "description": "pi extension for Zulip agent communication — connects Abiba to the Sysloggh agent mesh",
  "main": "src/index.ts",
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
-    "start": "node dist/index.js",
+    "check": "tsc --noEmit"
    "dev": "node --watch dist/index.js"
  },
  "dependencies": {
    "yaml": "^2.9.0",
    "zulip-js": "^2.0.0"
  },
  "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@earendil-works/pi-coding-agent": "^0.80.2",
-    "typescript": "^5.7.0"
+    "typescript": "^5.0.0"
-  }
+  },
  "keywords": [
    "pi",
    "zulip",
    "agent",
    "abiba",
    "sysloggh"
  ],
  "license": "UNLICENSED",
  "private": true
 }
@@ -1,18 +1,14 @@
 {
  "compilerOptions": {
    "target": "ES2022",
-    "module": "ES2022",
+    "module": "ESNext",
-    "moduleResolution": "node",
+    "moduleResolution": "bundler",
-    "outDir": "./dist",
+    "strict": true,
    "rootDir": "./src",
    "strict": false,
    "esModuleInterop": true,
-    "skipLibCheck": true,
+    "outDir": "dist",
-    "forceConsistentCasingInFileNames": true,
+    "rootDir": "src",
    "declaration": true,
-    "declarationMap": true,
+    "skipLibCheck": true
    "sourceMap": true
  },
-  "include": ["src/**/*"],
+  "include": ["src/**/*.ts"]
  "exclude": ["node_modules", "dist"]
 }
@@ -1,3 +0,0 @@
 from .adapter import register
 __all__ = ["register"]
@@ -1,56 +0,0 @@
 name: zulip-platform
 label: Zulip
 kind: platform
 version: 1.0.0
 description: >
  Zulip messaging platform adapter for Hermes Agent. Connects to a Zulip
  server via event queue polling, processes DMs and @mentions, and sends
  replies with placeholder→edit streaming. Uses the official zulip-js
  HTTP API pattern (polling, not WebSockets) — lightweight, no external
  SDK beyond httpx.
 author: Syslog Solution LLC
 requires_env:
  - name: ZULIP_SITE
    description: "Zulip server URL (e.g. https://chat.sysloggh.net)"
    prompt: "Zulip server URL"
    password: false
  - name: ZULIP_EMAIL
    description: "Bot email address (e.g. tanko-bot@chat.sysloggh.net)"
    prompt: "Zulip bot email"
    password: false
  - name: ZULIP_API_KEY
    description: "Zulip bot API key"
    prompt: "Zulip API key"
    password: true
 optional_env:
  - name: ZULIP_STREAM
    description: "Primary stream to subscribe to (default: agent-hub)"
    prompt: "Zulip stream name"
    password: false
  - name: ZULIP_ALL_BOTS_USER_ID
    description: "User ID of the @all-bots user (default: 1)"
    prompt: "All Bots user ID"
    password: false
  - name: ZULIP_AGENT_NAME
    description: "Agent display name for logging (default: hermes-agent)"
    prompt: "Agent name"
    password: false
  - name: ZULIP_OWNER_EMAIL
    description: "Owner email for private topic ACL"
    prompt: "Owner email"
    password: false
  - name: ZULIP_POLL_INTERVAL
    description: "Event poll interval in seconds (default: 3)"
    prompt: "Poll interval (seconds)"
    password: false
  - name: ZULIP_HOME_CHANNEL
    description: "Default recipient for cron / notification delivery"
    prompt: "Home channel (email or stream:topic)"
    password: false
  - name: ZULIP_HOME_CHANNEL_NAME
    description: "Human label for the home channel"
    prompt: "Home channel display name"
    password: false
@@ -1,56 +1,32 @@
 #!/usr/bin/env bash
-# deploy.sh  — GitOps deployment for zulip-platform-plugins
+# deploy.sh  GitOps deployment for zulip-platform-plugins
-#
+# Usage: ./deploy.sh <tag|branch> [--ct=<agent>] [--dry-run]
-# Supports two deployment modes:
+#   ./deploy.sh v1.0.0              # Deploy to all 6 CTs
-#   LEGACY:  /opt/hermes-zulip-plugin/  + systemctl restart zulip-plugin
+#   ./deploy.sh main                # Deploy latest (staging only!)
-#   NATIVE:  ~/.hermes/plugins/platforms/zulip/  + hermes gateway restart
+#   ./deploy.sh --ct=tanko v1.0.0   # Deploy to single CT
-#
+#   ./deploy.sh --dry-run v1.0.0    # Preview deployment without making changes
 # Usage:
 #   ./deploy.sh <tag|branch>                # Deploy all agents (default: native)
 #   ./deploy.sh --mode=native v1.0.0        # Hermes native plugin (new)
 #   ./deploy.sh --mode=legacy v1.0.0        # Old systemd service (deprecated)
 #   ./deploy.sh --ct=tanko v1.0.0           # Single agent
 #   ./deploy.sh --dry-run v1.0.0            # Preview only
 #
 set -euo pipefail
 DEPLOY_LOG="deploy.log"
 TAG=""
 SINGLE_CT=""
 DRY_RUN=false
 DEPLOY_MODE="native"  # default to new Hermes native plugin
 # Parse args
 for arg in "$@"; do
  case "$arg" in
    --ct=*) SINGLE_CT="${arg#--ct=}" ;;
    --dry-run) DRY_RUN=true ;;
    --mode=*) DEPLOY_MODE="${arg#--mode=}" ;;
    *) TAG="$arg" ;;
  esac
 done
 if [[ -z "$TAG" ]]; then
-  echo "Usage: $0 <tag|branch> [--ct=<agent>] [--mode=native|legacy] [--dry-run]"
+  echo "Usage: $0 <tag|branch> [--ct=<agent>] [--dry-run]"
  echo ""
  echo "  --ct=<agent>    Deploy to single agent (tanko, mumuni, etc.)"
  echo "  --mode=native   Hermes native plugin at ~/.hermes/plugins/ (default)"
  echo "  --mode=legacy   Old systemd service at /opt/hermes-zulip-plugin/"
  echo "  --dry-run       Preview deployment without making changes"
  echo ""
  echo "Examples:"
  echo "  ./deploy.sh v1.0.0                    # Deploy native to all agents"
  echo "  ./deploy.sh --ct=tanko v1.0.0         # Deploy native to Tanko only"
  echo "  ./deploy.sh --mode=legacy v0.9.0      # Deploy legacy to all"
  exit 1
 fi
-if [[ "$DEPLOY_MODE" != "native" && "$DEPLOY_MODE" != "legacy" ]]; then
+# Agent CT registry (must match CONTEXT.md)
  echo "ERROR: --mode must be 'native' or 'legacy'"
  exit 1
 fi
 # ── Agent Registry (must match docs/CONTEXT.md) ──────────────────────
 declare -A AGENTS=(
  ["tanko"]="amdpve CT 112"
  ["mumuni"]="minipve CT 114"
@@ -60,31 +36,32 @@ declare -A AGENTS=(
  ["abiba"]="amdpve CT 100"
 )
-# Native Hermes plugin path (~/.hermes/plugins/platforms/zulip/)
+# Platform paths per agent type
-NATIVE_PLUGIN_SRC="plugins/platforms/zulip"
+declare -A PLUGIN_PATHS=(
 # Legacy paths (DEPRECATED — systemd zulip-plugin service)
 declare -A LEGACY_PATHS=(
  ["tanko"]="/opt/hermes-zulip-plugin"
  ["mumuni"]="/opt/hermes-zulip-plugin"
  ["koonimo"]="/opt/hermes-zulip-plugin"
-  ["koby"]="/opt/hermes-zulip-plugin"
+  ["koby\"]="/opt/hermes-zulip-plugin"
-  ["kagentz"]="/opt/agent-zero-plugin"
+  ["kagentz\"]="/opt/agent-zero-plugin"
-  ["abiba"]="/root/.pi/agent/extensions/zulip.ts"
+  ["abiba\"]="/root/.pi/agent/extensions/zulip.ts"
 )
-# Service names for legacy mode
+# Correcting the backslash artifacts from the original file
-declare -A LEGACY_SERVICES=(
+PLUGIN_PATHS["koby"]="/opt/hermes-zulip-plugin"
 PLUGIN_PATHS["kagentz"]="/opt/agent-zero-plugin"
 PLUGIN_PATHS["abiba"]="/root/.pi/agent/extensions/zulip.ts"
 declare -A SERVICE_NAMES=(
  ["tanko"]="zulip-plugin"
  ["mumuni"]="zulip-plugin"
  ["koonimo"]="zulip-plugin"
  ["koby"]="zulip-plugin"
  ["kagentz"]="zulip-plugin"
-  ["abiba"]="pi"
+  ["abiba"]="pi"  # pi reload, not systemctl
 )
 HEALTH_PORT=9200
 GITEA_REPO="https://git.sysloggh.net/SyslogSolution/zulip-platform-plugins.git"
 HEALTH_PORT=9200
 log() {
  local prefix=""
@@ -92,169 +69,90 @@ log() {
  echo "${prefix}[$(date '+%Y-%m-%d %H:%M:%S')] $*" | tee -a "$DEPLOY_LOG"
 }
-# ── Deployment Functions ─────────────────────────────────────────────
+deploy_agent() {
 deploy_native() {
  local agent="$1"
-  local plugin_dir="$HOME/.hermes/plugins/platforms/zulip"
+  local ct_info="${AGENTS[$agent]}"
  local plugin_path="${PLUGIN_PATHS[$agent]}"
  local service="${SERVICE_NAMES[$agent]}"
-  log "📦 Deploying $agent: native Hermes plugin -> $plugin_dir"
+  log "=== Deploying $agent ($ct_info) @ $TAG ==="
  log "Path: $plugin_path"
-  if [[ "$DRY_RUN" == "true" ]]; then
+  # 1. Git pull & checkout tag
-    log "   Would copy $NATIVE_PLUGIN_SRC/{adapter.py,__init__.py,plugin.yaml} -> $plugin_dir/"
+  if [[ "$DRY_RUN" != "true" ]]; then
-    log "   Would run: hermes gateway restart"
+    cd "$plugin_path" || { log "ERROR: $agent  path $plugin_path not found"; return 1; }
-    return 0
+    git fetch --tags origin
-  fi
+    git checkout "$TAG"
  # Create plugin directory
  mkdir -p "$plugin_dir"
  # Copy plugin files
  cp "$NATIVE_PLUGIN_SRC/adapter.py" "$plugin_dir/"
  cp "$NATIVE_PLUGIN_SRC/__init__.py" "$plugin_dir/"
  cp "$NATIVE_PLUGIN_SRC/plugin.yaml" "$plugin_dir/"
  log "   Copied plugin files to $plugin_dir/"
  ls -la "$plugin_dir/"
  # Restart Hermes Gateway to load the plugin
  if command -v hermes &>/dev/null; then
    log "   Restarting Hermes Gateway..."
    hermes gateway restart
    log "   Hermes Gateway restarted"
  else
-    log "   ⚠️  'hermes' command not found — manual restart needed"
+    log "Skipping Git checkout (Dry Run)"
-    log "   Run: hermes gateway restart"
+  fi
  log "$agent: checked out $TAG"
  # 2. Install dependencies (platform-specific)
  if [[ "$DRY_RUN" != "true" ]]; then
    case "$agent" in
      tanko|mumuni|koonimo|koby)
        pip install -r requirements.txt --quiet
        ;;
      kagentz)
        pip install -r requirements.txt --quiet
        ;;
      abiba)
        log "$agent: pi extension  skipping pip install"
        ;;
    esac
  else
    log "Skipping dependency installation (Dry Run)"
  fi
-  # Health check
+  # 3. Restart service
-  log "   Waiting for service to stabilize..."
+  if [[ "$DRY_RUN" != "true" ]]; then
    case "$agent" in
      abiba)
        log "$agent: triggering /reload"
        ;;
      *)
        systemctl restart "$service"
        log "$agent: restarted $service"
        ;;
    esac
  else
    log "Skipping service restart (Dry Run)"
  fi
  # 4. Health check
  log "Waiting for service to stabilize..."
  sleep 5
-  if curl -sf "http://localhost:$HEALTH_PORT/health" > /dev/null 2>&1; then
+  if [[ "$DRY_RUN" != "true" ]]; then
-    log "   ✅ Health check passed (port $HEALTH_PORT)"
+    if curl -sf "http://localhost:$HEALTH_PORT/health" > /dev/null 2>&1; then
-  else
+      log "OK: $agent health check passed"
    log "   ⚠️  Health check on port $HEALTH_PORT not responding"
    log "   Check Gateway logs for plugin load errors"
  fi
  log "✅ $agent: native deployment complete"
 }
 deploy_legacy() {
  local agent="$1"
  local plugin_path="${LEGACY_PATHS[$agent]}"
  local service="${LEGACY_SERVICES[$agent]}"
  log "📦 Deploying $agent: LEGACY mode -> $plugin_path"
  if [[ "$DRY_RUN" == "true" ]]; then
    log "   Would git checkout $TAG in $plugin_path"
    log "   Would install deps + restart $service"
    return 0
  fi
  # Git checkout
  if [[ ! -d "$plugin_path" ]]; then
    log "❌ Path $plugin_path not found for $agent"
    return 1
  fi
  cd "$plugin_path"
  git fetch --tags origin
  git checkout "$TAG"
  log "   Checked out $TAG in $plugin_path"
  # Install deps
  if [[ -f "requirements.txt" ]]; then
    pip install -r requirements.txt --quiet
    log "   Dependencies installed"
  fi
  # Restart service
  if systemctl list-units --full -all 2>/dev/null | grep -q "$service"; then
    systemctl restart "$service"
    log "   Restarted $service"
  else
    log "   ⚠️  Service $service not found — manual restart needed"
  fi
  # Health check
  sleep 5
  if curl -sf "http://localhost:$HEALTH_PORT/health" > /dev/null 2>&1; then
    log "   ✅ Health check passed"
  else
    log "   ⚠️  Health check failed — check logs"
  fi
  log "✅ $agent: legacy deployment complete"
 }
 # ── Verify function ──────────────────────────────────────────────────
 verify_deployment() {
  local agent="$1"
  log "🔍 Verifying $agent deployment..."
  if [[ "$DEPLOY_MODE" == "native" ]]; then
    local plugin_dir="$HOME/.hermes/plugins/platforms/zulip"
    if [[ -f "$plugin_dir/adapter.py" && -f "$plugin_dir/plugin.yaml" ]]; then
      log "   ✅ Plugin files present in $plugin_dir"
      log "   adapter.py: $(wc -l < "$plugin_dir/adapter.py") lines"
      log "   plugin.yaml: $(wc -l < "$plugin_dir/plugin.yaml") lines"
    else
-      log "   ❌ Plugin files missing in $plugin_dir"
+      log "ERROR: $agent health check failed  check logs"
      return 1
    fi
  else
    log "Skipping health check (Dry Run)"
  fi
  log "   ✅ $agent verification complete"
 }
-# ── Main ─────────────────────────────────────────────────────────────
+# --- Main ---\
-
+log "Deploy started  target: $TAG (Dry Run: $DRY_RUN)"
 log "🚀 Deploy started — tag: $TAG, mode: $DEPLOY_MODE, dry-run: $DRY_RUN"
 if [[ -n "$SINGLE_CT" ]]; then
-  if [[ -z "${AGENTS[$SINGLE_CT]:-}" ]]; then
+  deploy_agent "$SINGLE_CT"
    log "❌ Unknown agent: $SINGLE_CT"
    log "   Known agents: ${!AGENTS[*]}"
    exit 1
  fi
  log "--- Deploying single agent: $SINGLE_CT ---"
  if [[ "$DEPLOY_MODE" == "native" ]]; then
    deploy_native "$SINGLE_CT"
  else
    deploy_legacy "$SINGLE_CT"
  fi
  verify_deployment "$SINGLE_CT"
 else
  FAILED=""
-  for agent in "${!AGENTS[@]}"; do
+  for agent in tanko mumuni koonimo koby kagentz abiba; do
-    echo ""
+    if ! deploy_agent "$agent"; then
-    if [[ "$DEPLOY_MODE" == "native" ]]; then
+      FAILED="$FAILED $agent"
      if deploy_native "$agent"; then
        verify_deployment "$agent" || FAILED="$FAILED $agent"
      else
        FAILED="$FAILED $agent"
      fi
    else
      if deploy_legacy "$agent"; then
        verify_deployment "$agent" || FAILED="$FAILED $agent"
      else
        FAILED="$FAILED $agent"
      fi
    fi
  done
  echo ""
  log "=== Deploy complete ==="
  if [[ -n "$FAILED" ]]; then
-    log "❌ FAILED:$FAILED"
+    log "FAILED:$FAILED"
-    log "   Run rollback: ./scripts/rollback.sh <previous-tag>"
+    log "Run rollback: ./scripts/rollback.sh <previous-tag>"
    exit 1
  fi
-  log "✅ All agents deployed successfully."
+  log "All 6 agents deployed successfully."
  log "   Next: monitor #agent-hub for agent responses"
 fi
@@ -1,92 +0,0 @@
 #!/usr/bin/env bash
 # verify-deployment.sh — Check if the Hermes Zulip native plugin is properly deployed
 #
 # Usage:
 #   ./verify-deployment.sh              # Check local agent
 #   ./verify-deployment.sh --ct=tanko   # Check specific agent
 #   ./verify-deployment.sh --all        # Check all reachable agents
 #
 set -euo pipefail
 PLUGIN_DIR="$HOME/.hermes/plugins/platforms/zulip"
 HEALTH_PORT=9200
 echo "🔍 Zulip Plugin Deployment Verification"
 echo "========================================"
 echo ""
 # 1. Check plugin files exist
 echo "📁 Step 1: Plugin files"
 if [[ -d "$PLUGIN_DIR" ]]; then
  echo "   ✅ Plugin directory: $PLUGIN_DIR"
  for f in adapter.py __init__.py plugin.yaml; do
    if [[ -f "$PLUGIN_DIR/$f" ]]; then
      echo "   ✅ $f — $(wc -l < "$PLUGIN_DIR/$f") lines"
    else
      echo "   ❌ $f — MISSING"
    fi
  done
 else
  echo "   ❌ Plugin directory NOT FOUND at $PLUGIN_DIR"
  echo "   → Install: ./scripts/deploy.sh --mode=native v1.0.0"
 fi
 echo ""
 # 2. Check Hermes Gateway is running
 echo "🔧 Step 2: Hermes Gateway"
 if command -v hermes &>/dev/null; then
  echo "   ✅ 'hermes' command found"
  if hermes gateway status 2>/dev/null | grep -qi "running"; then
    echo "   ✅ Hermes Gateway is running"
  else
    echo "   ⚠️  Hermes Gateway status unknown — check manually"
  fi
 else
  echo "   ❌ 'hermes' command not found"
  echo "   → Is Hermes Agent installed?"
 fi
 echo ""
 # 3. Check health endpoint
 echo "❤️ Step 3: Health endpoint"
 if curl -sf "http://localhost:$HEALTH_PORT/health" > /dev/null 2>&1; then
  echo "   ✅ Health endpoint responds on port $HEALTH_PORT"
 else
  echo "   ⚠️  Health endpoint not responding on port $HEALTH_PORT"
  echo "   → The plugin may not have started yet"
 fi
 echo ""
 # 4. Check Zulip env vars
 echo "🔑 Step 4: Environment variables"
 for var in ZULIP_SITE ZULIP_EMAIL ZULIP_API_KEY; do
  if [[ -n "${!var:-}" ]]; then
    val="${!var}"
    if [[ "$var" == "ZULIP_API_KEY" ]]; then
      echo "   ✅ $var — [REDACTED]"
    else
      echo "   ✅ $var — $val"
    fi
  else
    echo "   ❌ $var — NOT SET"
  fi
 done
 echo ""
 # Overall
 echo "═══════════════════════════════════════"
 missing=0
 [[ -d "$PLUGIN_DIR" ]] || missing=$((missing + 1))
 command -v hermes &>/dev/null || missing=$((missing + 1))
 [[ -n "${ZULIP_SITE:-}" && -n "${ZULIP_EMAIL:-}" && -n "${ZULIP_API_KEY:-}" ]] || missing=$((missing + 1))
 if [[ "$missing" -eq 0 ]]; then
  echo "✅ VERDICT: Plugin properly deployed"
  echo "   Send a DM to verify: @**${ZULIP_AGENT_NAME:-hermes-agent}** _hello_"
 else
  echo "⚠️  VERDICT: $missing issue(s) found — fix and re-verify"
 fi
		`@@ -1,3 +0,0 @@`
			`from .adapter import register`

			`__all__ = ["register"]`