prose-contracts/hermes-zulip-plugin.prose.md

---
kind: function
name: hermes-zulip-plugin
description: >
  Installs or updates the Zulip platform plugin for any Hermes agent from the
  canonical zulip-platform-plugins repo (master branch). Ensures the agent runs
  the latest adapter with all Zulip chat fixes (_strip_html, streaming, event
  recovery). Verifies the installation, restarts the gateway, and sends a relay
  success signal.
agent: abiba
version: 1.0.0
status: active
runtime_contract: 2
---

# Hermes Zulip Plugin — Install & Repair

Single-shot function that pulls the latest zulip-platform plugin from the
canonical git repo, installs it to the correct Hermes bundled plugin path,
verifies the installation, and signals completion.

Distinct from `hermes-zulip-restore`: this contract is focused on the plugin
layer and a targeted gateway restart. It does NOT verify env credentials or
run a live Zulip connection test. Use `hermes-zulip-restore` for full
connectivity recovery including end-to-end DM validation.

## Parameters

| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `target` | string | yes | — | Agent name: `mumuni`, `tanko`, `koby`, or `shumba` |
| `branch` | string | no | `master` | Git branch to pull (overridable for pinning) |

## Maintains

- plugin_installed: bool — Whether all three adapter files exist at the bundled path
- plugin_version: string — Git commit SHA of the installed version
- strip_html_present: bool — Whether `_strip_html` fix is in the installed adapter
- signal_sent: bool — Whether relay success message was dispatched

### Postconditions

- All three adapter files (`__init__.py`, `adapter.py`, `plugin.yaml`) present in `<HERMES_HOME>/hermes-agent/plugins/platforms/zulip/`
- `_strip_html` function exists in `adapter.py` (slash-command fix, commit `55ca15d`+)
- Installed version matches HEAD of the requested branch
- Relay success signal sent to Hermes agent's inbox

## Requires

- SSH access to target host (direct or via amdpve for CTs)
- Git repo at `https://git.sysloggh.net/SyslogSolution/zulip-platform-plugins.git`
- Python 3 with `httpx` installed on target

## Live-State Fields

| Host | CT | Proxmox | IP (direct) | Hermes Home | User |
|------|-----|---------|-------------|-------------|------|
| Mumuni | CT114 | — | 192.168.68.123 | /root/.hermes | root |
| Tanko | CT112 | amdpve | 192.168.68.122 | /home/jerome/.hermes | jerome |
| Koby | CT111 | amdpve | 192.168.68.129 | /root/.hermes | root |
| Shumba | — | — | 192.168.68.119 | /home/lucky/.hermes | lucky |

| Field | Value | Trust |
|-------|-------|-------|
| Git repo | `https://git.sysloggh.net/SyslogSolution/zulip-platform-plugins.git` | ✅ Verified |
| Default branch | `master` (contains all merged fixes including `feat/zulip-streaming`) | ✅ Verified |
| Bundled adapter path | `<HERMES_HOME>/hermes-agent/plugins/platforms/zulip/` | ✅ Verified |
| Adapter files | `__init__.py`, `adapter.py`, `plugin.yaml` | ✅ Verified |
| Strip-html commit | `55ca15d` (minimum) | ✅ Verified |

## Execution

### Step 1: Resolve Target

Map `target` to host, CT ID, hermes_home, and user from the live-state table.
For CT112 and CT111, route through `ssh root@amdpve` then `pct exec <id>`.

### Step 2: Pull Latest Plugin Source

On the target host:

```bash
# Ensure deploy scratch space
mkdir -p /tmp/zulip-deploy
cd /tmp/zulip-deploy

# Clone or pull
if [ -d zulip-platform-plugins ]; then
  cd zulip-platform-plugins
  git fetch origin
  git checkout {{branch}}
  git pull origin {{branch}}
else
  git clone --branch {{branch}} \
    https://git.sysloggh.net/SyslogSolution/zulip-platform-plugins.git
  cd zulip-platform-plugins
fi

# Capture installed version
INSTALLED_SHA=$(git rev-parse HEAD)
echo "Installed SHA: $INSTALLED_SHA"

# Verify we're at HEAD
HEAD_SHA=$(git rev-parse origin/{{branch}})
if [ "$INSTALLED_SHA" = "$HEAD_SHA" ]; then
  echo "At latest commit on {{branch}}"
else
  echo "WARNING: not at HEAD — $INSTALLED_SHA vs $HEAD_SHA"
fi
```

### Step 3: Install Plugin Files

```bash
# Ensure target directory exists
mkdir -p {{hermes_home}}/hermes-agent/plugins/platforms/zulip

# Copy adapter files
cp plugins/platforms/zulip/adapter.py \
   plugins/platforms/zulip/__init__.py \
   plugins/platforms/zulip/plugin.yaml \
   {{hermes_home}}/hermes-agent/plugins/platforms/zulip/

# Fix ownership (Tanko only — runs as jerome user)
[ "{{target}}" = "tanko" ] && chown -R jerome:jerome \
  {{hermes_home}}/hermes-agent/plugins/platforms/zulip/

echo "Plugin files installed"
```

### Step 4: Verify Installation

```bash
# Check all three files exist
for f in __init__.py adapter.py plugin.yaml; do
  if [ -f "{{hermes_home}}/hermes-agent/plugins/platforms/zulip/$f" ]; then
    echo "✅ $f present"
  else
    echo "❌ $f MISSING"
    exit 1
  fi
done

# Verify _strip_html fix
grep -q "_strip_html" {{hermes_home}}/hermes-agent/plugins/platforms/zulip/adapter.py \
  && echo "✅ _strip_html fix present" \
  || echo "❌ _strip_html MISSING — plugin may be stale"

# Show installed plugin.yaml version
grep "^version:" {{hermes_home}}/hermes-agent/plugins/platforms/zulip/plugin.yaml || true
```

### Step 5: Restart Gateway

Plugin changes require a gateway restart to take effect:

```bash
cd {{hermes_home}}/hermes-agent
# Use venv if available
python3 -m hermes_cli.main gateway restart 2>&1 || \
  venv/bin/python -m hermes_cli.main gateway restart 2>&1
```

Wait for restart to complete (up to 45s), then confirm:

```bash
grep "Gateway running" {{hermes_home}}/logs/gateway.log | tail -1
```

Expected: `Gateway running with N platform(s)` where N > 1 (includes zulip).

Quick smoke check — confirm zulip platform loaded:

```bash
grep -E "zulip.*loaded|zulip.*registered" {{hermes_home}}/logs/gateway.log | tail -3
```

If gateway fails to restart, check logs for the crash cause before proceeding.

### Step 6: Send Relay Success Signal

On the Abiba host (local), dispatch a relay message to the target agent:

```
ra-h-os-createRelayNode:
  title: "Zulip plugin updated — {{target}}"
  source: |
    Plugin installed from {{branch}} @ {{INSTALLED_SHA}}
    All 3 adapter files verified at {{hermes_home}}/hermes-agent/plugins/platforms/zulip/
    _strip_html fix: PRESENT
    Timestamp: {{timestamp}}

  description: "hermes-zulip-plugin completed for {{target}} — plugin layer healthy"
```

### Step 7: Report

Compile results into a single status block:

| Field | Value |
|-------|-------|
| Target | `{{target}}` |
| Branch | `{{branch}}` |
| Commit SHA | `{{INSTALLED_SHA}}` |
| Files installed | `__init__.py`, `adapter.py`, `plugin.yaml` |
| `_strip_html` | `{{present|missing}}` |
| Gateway restarted | `{{yes|no}}` |
| Signal sent | `{{yes|no}}` |

## Known Failure Modes

| Symptom | Root Cause | Recovery |
|---------|-----------|----------|
| Git clone fails | No network or repo unreachable | Check VPN/network, verify repo URL |
| Permission denied on copy | Wrong user for target | Use correct user (jerome for Tanko, root for others) |
| `_strip_html` missing after install | Branch doesn't include commit `55ca15d` | Switch to `feat/zulip-streaming` branch |
| Plugin files missing after copy | Target directory doesn't exist | Ensure `mkdir -p` ran successfully |
| Relay signal fails | MCP bridge unreachable | Signal manually via `ra-h-os-createRelayNode` |

## Edge Differences from hermes-zulip-restore

| Concern | hermes-zulip-restore | hermes-zulip-plugin |
|---------|---------------------|---------------------|
| Env credential check | ✅ Full ZULIP_* verification | ❌ Out of scope |
| Gateway restart | ✅ Full restart + state validation | ✅ Targeted restart + smoke check |
| Live connection test | ✅ Validates `zulip.state = connected` | ❌ Out of scope |
| Plugin deploy | ✅ Includes deploy as one step | ✅ Primary purpose |
| Version tracking | ❌ Implicit | ✅ Explicit SHA capture |
| Signal dispatch | ❌ None | ✅ Relay message to target |

For full connectivity recovery after a plugin install, chain this contract
with `hermes-zulip-restore` (skip its Step 2 to avoid redundant deploy).

---

**Last updated**: 2026-07-08 — Switched default branch to `master`; added
gateway restart step. If outstanding unmerged feature branches exist, address
them in a follow-up merge after this contract completes.