Compare commits
5
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 jerome
|
0e6efdb627 | ||
|
jerome
|
484ea00597 | ||
|
jerome
|
8abbd6f001 | ||
|
jerome
|
cca5a57265 | ||
|
jerome
|
4dc29289bb |
@@ -1 +0,0 @@
|
||||
__pycache__/
|
||||
@@ -67,10 +67,10 @@ Two incidents taught us this:
|
||||
|
||||
| Contract | Sensitivity | Who can change |
|
||||
|----------|------------|----------------|
|
||||
| `infrastructure-control.prose.md` | **CRITICAL** — topology source of truth | Abiba, Tanko (Tanko maintains its own CT row) |
|
||||
| `infrastructure-control.prose.md` | **CRITICAL** — topology source of truth | Abiba only (after live verification) |
|
||||
| `proxmox-monitor.prose.md` | **CRITICAL** — deployed monitoring | Abiba only |
|
||||
| `hermes-config-template.prose.md` | **HIGH** — all agent configs | Abiba, Mumuni, Tanko |
|
||||
| `zulip-health.prose.md` | **HIGH** — agent communication | Abiba, Mumuni, Tanko |
|
||||
| `zulip-health.prose.md` | **HIGH** — agent communication | Abiba, Mumuni |
|
||||
| Other contracts | Normal | Any registered agent |
|
||||
| `scripts/*.sh` | **HIGH** — runtime scripts | Abiba only |
|
||||
|
||||
@@ -128,10 +128,3 @@ safe-mutate --verify "CMD" [--expect "PATTERN"] --mutate "CMD" [--reason "WHY"]
|
||||
Read the [Authoring Guide](docs/AUTHORING-GUIDE.md) before writing any new contract.
|
||||
It covers the full process: verify → draft → lint → review → ship, with templates
|
||||
and style rules.
|
||||
|
||||
## Maintaining this file
|
||||
|
||||
Keep this file for knowledge useful to almost every future agent session in this project.
|
||||
Do not repeat what the codebase already shows; point to the authoritative file or command instead.
|
||||
Prefer rewriting or pruning existing entries over appending new ones.
|
||||
When updating this file, preserve this bar for all agents and keep entries concise.
|
||||
|
||||
@@ -1,2 +0,0 @@
|
||||
<!-- Points Claude at AGENTS.md via import; edit AGENTS.md, not this file. -->
|
||||
@AGENTS.md
|
||||
@@ -20,8 +20,7 @@ An agent ran `pct set` without checking `pct config` first and changed the IP
|
||||
to the wrong value, breaking Zulip. The staleness was harmless until acted on.
|
||||
|
||||
**Layer 3 enforcement — the `safe-mutate` wrapper** (deployed on all 5 agents:
|
||||
Abiba, Tanko, Mumuni, Koby, Koonimo — Tanko runs on DSH/DeepSeek Harness since
|
||||
2026-08-27 but safe-mutate enforcement still applies). ALL infrastructure mutations MUST go
|
||||
Abiba, Tanko, Mumuni, Koby, Koonimo). ALL infrastructure mutations MUST go
|
||||
through `safe-mutate`. Raw `sed -i`, `pct set`, `docker compose up
|
||||
--force-recreate`, `kill`, `rm` on infrastructure outside `safe-mutate` is an
|
||||
auditable protocol violation. The wrapper runs a verify command, optionally
|
||||
@@ -162,7 +161,7 @@ Companion shell scripts that contracts delegate to.
|
||||
|---|---|
|
||||
| `daily-infra-report.py` | Generates the daily infrastructure dashboard (HTML email to jerome@sysloggh.com). |
|
||||
| `pm2-self-heal.sh` | Shell companion to the pm2-self-heal contract — restarts crashed PM2 processes (runs every 5 min). |
|
||||
| `agent-health-check.py` | Consolidated agent health: LiteLLM key validation + GPU port conflict + streaming checks (every 10 min). |
|
||||
| `agent-health-check.py` | Consolidated agent health: LiteLLM key validation + GPU port conflict + streaming checks (every 10 min). Replaced zulip-monitor.sh. |
|
||||
|
||||
## Contract Structure
|
||||
|
||||
|
||||
@@ -1,313 +0,0 @@
|
||||
---
|
||||
report_only_agents:
|
||||
- koby # ⛔ KOBY IS NEVER REPAIRED (Rule 17, 2026-08-17) — detect + report, never fix on .129
|
||||
kind: function
|
||||
name: abiba-zulip-restore
|
||||
description: >
|
||||
Restores Zulip connectivity for Abiba (pi agent). Verifies the v2 router-worker
|
||||
extension code, starts a PM2 process as the Zulip gateway with correct env vars,
|
||||
validates health endpoint, and confirms DM delivery. Run this whenever Abiba
|
||||
stops responding on Zulip or after system restart.
|
||||
agent: abiba
|
||||
version: 1.0.0
|
||||
status: active
|
||||
runtime_contract: 2
|
||||
---
|
||||
---
|
||||
|
||||
# Abiba Zulip Restore — Resume pi Zulip Communication
|
||||
|
||||
Single-shot function that restores full Zulip connectivity for the Abiba pi agent.
|
||||
Covers extension code validation, PM2 process management, health endpoint
|
||||
verification, and DM loopback testing.
|
||||
|
||||
## Live-State Fields
|
||||
|
||||
| Field | Value | Trust |
|
||||
|-------|-------|-------|
|
||||
| Agent name | abiba | ✅ |
|
||||
| Bot email | abiba-bot@chat.sysloggh.net | ✅ |
|
||||
| Zulip server | https://chat.sysloggh.net | ✅ |
|
||||
| Extension path | /root/.pi/agent/extensions/zulip/index.js | ✅ |
|
||||
| Config path | /root/.pi/agent/extensions/zulip/config.yaml | ✅ |
|
||||
| Health port | 9200 | ✅ |
|
||||
| @all-bots user ID | 20 | ✅ (config, verified by API at runtime) |
|
||||
| PM2 process name | abiba-zulip | ✅ |
|
||||
| Provider | syslog-harness (http://192.168.68.116/v1) | ✅ |
|
||||
| Default model | deepseek-v4-pro | ✅ (settings.json) |
|
||||
|
||||
## Architecture
|
||||
|
||||
The pi Zulip extension uses a **router-worker architecture** (v2):
|
||||
|
||||
- **Router** (PM2 `abiba-zulip`, `ZULIP_ROLE=router`): Polls Zulip for events,
|
||||
maintains a per-sender pool of pi RPC worker processes. Each sender gets
|
||||
their own `pi --mode rpc --session-dir` process with persistent sessions.
|
||||
Handles streaming edits back to Zulip.
|
||||
- **Worker** (child `pi --mode rpc`): Runs the agent with per-sender persistent
|
||||
sessions. No Zulip logic in the worker — the router handles all Zulip I/O.
|
||||
|
||||
The extension loads in ALL pi sessions (via `settings.json` extensions array)
|
||||
but is a **NO-OP** unless `ZULIP_ROLE=router` is set. Only the PM2 router process
|
||||
carries the env var.
|
||||
|
||||
## Maintains
|
||||
|
||||
- extension_valid: bool — Extension code imports without errors
|
||||
- pm2_running: bool — PM2 process `abiba-zulip` is online
|
||||
- health_responding: bool — GET :9200/health returns "ok"
|
||||
- zulip_connected: bool — Queue registered, bot identity resolved
|
||||
- loopback_delivered: bool — Test DM sent and received
|
||||
- model_valid: bool — Configured models match LiteLLM authorized models
|
||||
|
||||
### Postconditions
|
||||
|
||||
- PM2 process `abiba-zulip` online and stable (uptime > 30s)
|
||||
- Health endpoint returns `{ status: "ok", connected: true }`
|
||||
- Worker pool creates sessions on demand
|
||||
- Echo prevention active (BOT_EMAILS includes all known bots)
|
||||
- PM2 saved for auto-restart on boot
|
||||
|
||||
## Requires
|
||||
|
||||
- Node.js with `yaml` module available
|
||||
- PM2 installed globally
|
||||
- Zulip API key in `config.yaml`
|
||||
- `pi` CLI available on PATH
|
||||
- Zulip server accessible at https://chat.sysloggh.net
|
||||
- LiteLLM provider accessible at http://192.168.68.116/v1
|
||||
|
||||
## Execution
|
||||
|
||||
### Step 1: Validate Extension Code
|
||||
|
||||
```bash
|
||||
node -e "import('file:///root/.pi/agent/extensions/zulip/index.js').then(() => console.log('OK')).catch(e => {console.error('FAIL:', e.message); process.exit(1)})"
|
||||
```
|
||||
|
||||
Expected: `OK`. If FAIL → check for missing dependencies, syntax errors.
|
||||
|
||||
### Step 2: Validate Model IDs
|
||||
|
||||
Compare configured models against LiteLLM authorized models:
|
||||
|
||||
```bash
|
||||
API_KEY=$(grep -oP 'apiKey:\s*\K.*' /root/.pi/agent/models.json | head -1)
|
||||
curl -s -H "Authorization: Bearer $API_KEY" http://192.168.68.116/v1/models | \
|
||||
python3 -c "import json,sys; d=json.load(sys.stdin); [print(m['id']) for m in d.get('data',[])]" 2>/dev/null
|
||||
```
|
||||
|
||||
Check: Every model ID in `models.json` must appear in the authorized list.
|
||||
If not → fix `models.json` to only include authorized models (prefer `syslog-auto`).
|
||||
|
||||
### Step 3: Verify Config Integrity
|
||||
|
||||
```bash
|
||||
python3 -c "
|
||||
import yaml, sys
|
||||
with open('/root/.pi/agent/extensions/zulip/config.yaml') as f:
|
||||
cfg = yaml.safe_load(f)
|
||||
required = ['zulip.site', 'zulip.email', 'zulip.api_key', 'agent.name']
|
||||
for k in required:
|
||||
keys = k.split('.')
|
||||
v = cfg
|
||||
for kk in keys:
|
||||
v = v.get(kk)
|
||||
if v is None:
|
||||
print(f'MISSING: {k}')
|
||||
sys.exit(1)
|
||||
print('Config valid')
|
||||
print(f' site={cfg[\"zulip\"][\"site\"]}')
|
||||
print(f' email={cfg[\"zulip\"][\"email\"]}')
|
||||
print(f' agent={cfg[\"agent\"][\"name\"]}')
|
||||
print(f' health_port={cfg.get(\"health_port\", 9200)}')
|
||||
"
|
||||
```
|
||||
|
||||
Expected: Config valid with all fields non-empty.
|
||||
|
||||
### Step 4: Remove Stale Systemd Service
|
||||
|
||||
The old `abiba-zulip.service` points to `/opt/abiba-zulip/dist/index.js` (compiled
|
||||
TypeScript, not the v2 extension). It's disabled and stale. Remove it:
|
||||
|
||||
```bash
|
||||
systemctl stop abiba-zulip 2>/dev/null || true
|
||||
systemctl disable abiba-zulip 2>/dev/null || true
|
||||
rm -f /etc/systemd/system/abiba-zulip.service
|
||||
systemctl daemon-reload
|
||||
```
|
||||
|
||||
### Step 5: Start PM2 Process
|
||||
|
||||
**Critical:** The extension MUST run via `pi --mode rpc`, NOT `node index.js` directly.
|
||||
The extension exports a function that requires pi's session lifecycle. Running
|
||||
`node index.js` loads the module but never calls the export, so nothing happens.
|
||||
`pi --mode rpc` loads all extensions (including Zulip) and fires `session_start`.
|
||||
|
||||
```bash
|
||||
# Stop existing if any
|
||||
pm2 delete abiba-zulip 2>/dev/null || true
|
||||
|
||||
# Start pi in RPC mode with ZULIP_ROLE=router env
|
||||
ZULIP_ROLE=router pm2 start "$(which pi)" \
|
||||
--name abiba-zulip \
|
||||
--interpreter none \
|
||||
-- --mode rpc --no-session
|
||||
```
|
||||
|
||||
Wait 10 seconds for pi to load all extensions, fire session_start, and the Zulip
|
||||
router to register its event queue.
|
||||
|
||||
### Step 6: Validate PM2 Process
|
||||
|
||||
```bash
|
||||
pm2 show abiba-zulip --no-color
|
||||
```
|
||||
|
||||
Check: `status=online`, `restarts=0`, `uptime > 5s`.
|
||||
|
||||
### Step 7: Check Logs for Connection
|
||||
|
||||
```bash
|
||||
sleep 3
|
||||
tail -20 /root/.pm2/logs/abiba-zulip-out.log
|
||||
```
|
||||
|
||||
Look for:
|
||||
- `[zulip-ext] Connecting to https://chat.sysloggh.net as abiba-bot@chat.sysloggh.net…`
|
||||
- `[zulip-ext] Bot user_id=N, all-bots user_id=N`
|
||||
- `[zulip-ext] Connected, queue=N`
|
||||
- `[zulip-ext] Echo prevention: N bot emails`
|
||||
- `[zulip-ext] Health endpoint on :9200`
|
||||
|
||||
If error → check API key, network to chat.sysloggh.net.
|
||||
|
||||
### Step 8: Health Endpoint
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:9200/health | python3 -m json.tool
|
||||
```
|
||||
|
||||
Check:
|
||||
- `status: "ok"` (not "down")
|
||||
- `zulip.connected: true`
|
||||
- `zulip.queue_id` is non-null string
|
||||
- `zulip.bot_user_id` is positive integer
|
||||
|
||||
### Step 9: DM Loopback Test
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:9200/health | python3 -c "
|
||||
import json,sys
|
||||
d = json.load(sys.stdin)
|
||||
if d.get('zulip',{}).get('connected'):
|
||||
print(f'✅ Zulip connected. Queue: {d[\"zulip\"][\"queue_id\"]}')
|
||||
print(f' Bot user_id: {d[\"zulip\"][\"bot_user_id\"]}')
|
||||
print(f' Messages processed: {d[\"zulip\"][\"messages_processed\"]}')
|
||||
else:
|
||||
print('❌ Zulip NOT connected')
|
||||
sys.exit(1)
|
||||
"
|
||||
```
|
||||
|
||||
### Step 10: Save PM2 for Auto-Start
|
||||
|
||||
```bash
|
||||
pm2 save
|
||||
pm2 startup systemd -u root --hp /root 2>/dev/null || true
|
||||
```
|
||||
|
||||
### Step 11: Report
|
||||
|
||||
Compile results:
|
||||
|
||||
| Check | Pass? |
|
||||
|-------|-------|
|
||||
| Extension code imports | extension_valid |
|
||||
| Model IDs authorized | model_valid |
|
||||
| Config integrity | config_valid |
|
||||
| PM2 process online | pm2_running |
|
||||
| Health endpoint | health_responding |
|
||||
| Zulip connected | zulip_connected |
|
||||
|
||||
All pass → ✅ **Abiba Zulip restored.** Relay success to user.
|
||||
|
||||
Partial failure → see recovery matrix below.
|
||||
|
||||
## Recovery Matrix
|
||||
|
||||
| Failure | Recovery |
|
||||
|---------|----------|
|
||||
| Extension import fails | Check `node_modules/zulip-js` exists; run `npm install` in extension dir |
|
||||
| Model ID mismatch | Fix `models.json` to use `syslog-auto` as default model; remove invalid IDs |
|
||||
| Config missing | Restore from backup or recreate from scratch |
|
||||
| PM2 won't start | Check `node` version (>=18); check port 9200 not in use |
|
||||
| Health "down" | Check logs for connection errors; verify Zulip API key; check network |
|
||||
| "address already in use" | Kill old process: `fuser -k 9200/tcp` |
|
||||
| Queue registration fails | Check Zulip API key validity; verify bot is active in Zulip admin |
|
||||
| Rate limit (429) | Extension has built-in retry-after handling — wait, don't restart |
|
||||
|
||||
## Known Failure Modes
|
||||
|
||||
| Symptom | Root Cause | Recovery |
|
||||
|---------|-----------|----------|
|
||||
| Extension loads but no events | `ZULIP_ROLE` not set | Ensure PM2 env has `ZULIP_ROLE=router` |
|
||||
| Worker stays "busy" forever | Model ID not authorized by LiteLLM | Fix models.json (lesson #11) |
|
||||
| Placeholder sent but no response | editMessage API fails silently | Extension has fallback (sends new msg); check Zulip API |
|
||||
| Queue expires rapidly | Poll interval too aggressive | v2 uses 3s poll with long-poll — should be fine |
|
||||
| Bot doesn't respond to @mentions | Not subscribed to stream | Bot auto-subscribes via API |
|
||||
| Stale error in health | `last_error` not cleared | v2 clears on successful poll (lesson #4) |
|
||||
|
||||
## Appendix: Root Cause & Fix Summary (2026-07-13)
|
||||
|
||||
**Problem:** Zulip extension was offline — no PM2 process running.
|
||||
|
||||
**Root cause:** The PM2 command ran `node index.js` directly (which loads the
|
||||
extension module but never calls the exported function). The extension requires
|
||||
pi's session lifecycle — pi loads extensions, fires `session_start`, and the
|
||||
Zulip extension hooks into that event.
|
||||
|
||||
**Fix:** Run `pi --mode rpc` (not `node index.js`). The `--mode rpc` flag keeps
|
||||
pi alive listening for RPC commands on stdin while the Zulip extension's router
|
||||
runs in the background via the `session_start` hook.
|
||||
|
||||
```bash
|
||||
ZULIP_ROLE=router pm2 start "$(which pi)" --name abiba-zulip \
|
||||
--interpreter none -- --mode rpc --no-session
|
||||
```
|
||||
|
||||
**Additional fixes applied:**
|
||||
- Fixed `models.json`: replaced `qwen3.6-35B-A3B` (not authorized by LiteLLM)
|
||||
with `syslog-auto` + `strix-moe` (prevents silent worker failure per
|
||||
Lesson #11)
|
||||
- Removed stale systemd unit `abiba-zulip.service` (pointed to old TS code)
|
||||
- PM2 saved for auto-restart on boot
|
||||
|
||||
## Appendix: PM2 Ecosystem Config (Optional)
|
||||
|
||||
If preferred over manual `pm2 start`, create `/root/ecosystem.config.js` entry:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
apps: [{
|
||||
name: 'abiba-zulip',
|
||||
script: '/bin/pi',
|
||||
interpreter: 'none',
|
||||
args: '--mode rpc --no-session',
|
||||
cwd: '/root',
|
||||
env: {
|
||||
ZULIP_ROLE: 'router',
|
||||
},
|
||||
log_file: '/root/.pm2/logs/abiba-zulip-out.log',
|
||||
error_file: '/root/.pm2/logs/abiba-zulip-error.log',
|
||||
max_restarts: 20,
|
||||
restart_delay: 5000,
|
||||
}]
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
**Last verified good state**: 2026-07-13 — Extension v2 running via `pi --mode rpc`, health endpoint :9200 returning `{status:"ok",connected:true}`, queue a669f21e.
|
||||
@@ -1,186 +0,0 @@
|
||||
# Agent Zero Issue Fix Summary
|
||||
|
||||
**Date**: 2026-09-01
|
||||
**Agent**: Agent Zero (Docker container on kagentz CT105)
|
||||
**Issue**: AuthenticationError + Telegram conflicts
|
||||
**Status**: ✅ RESOLVED
|
||||
|
||||
---
|
||||
|
||||
## Problems Identified
|
||||
|
||||
### 1. OpenRouter Authentication Error (CRITICAL)
|
||||
```
|
||||
litellm.exceptions.AuthenticationError: OpenrouterException -
|
||||
{"error":{"message":"User not found.","code":401}}
|
||||
```
|
||||
**Root Cause**: The OpenRouter API key in `/a0/usr/.env` belonged to a different OpenRouter user.
|
||||
|
||||
**Old Key**: `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`
|
||||
**New Key**: `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`
|
||||
**New User**: `user_2rt9lCqcd5d7Vk1t18DHsvWdPTT`
|
||||
|
||||
### 2. Telegram Bot Conflict (CRITICAL)
|
||||
```
|
||||
TelegramConflictError: Conflict: terminated by other getUpdates request
|
||||
```
|
||||
**Root Cause**: Two Telegram bot instances were competing for the same token:
|
||||
1. Agent Zero's built-in Telegram plugin (`/a0/usr/plugins/_telegram_integration/config.json`)
|
||||
2. Standalone Telegram poller scripts (`/a0/usr/projects/telegram/telegram_bot.py`)
|
||||
|
||||
Both were using token `8476855065:***` in polling mode.
|
||||
|
||||
**Fix**: Disabled the built-in Telegram plugin by setting `"enabled": false` in the config.
|
||||
|
||||
### 3. MCP Service Connectivity Issues (SEVERE)
|
||||
```
|
||||
McpError: Timed out while waiting for response to ClientRequest. Waited 10.0 seconds.
|
||||
```
|
||||
**Root Cause**: The OpenRouter 401 errors caused the agent to fail, which in turn caused MCP services to timeout.
|
||||
|
||||
**Status**: ✅ RESOLVED with OpenRouter key fix.
|
||||
|
||||
---
|
||||
|
||||
## Fixes Applied
|
||||
|
||||
### Fix 1: Update OpenRouter Key
|
||||
```bash
|
||||
# Container .env update
|
||||
sudo docker exec agent-zero bash -c '
|
||||
sed -i "s|^API_KEY_OPENROUTER=.*|API_KEY_OPENROUTER=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|" /a0/usr/.env
|
||||
'
|
||||
```
|
||||
|
||||
**Verification**:
|
||||
```bash
|
||||
curl -s https://openrouter.ai/api/v1/auth/key \
|
||||
-H "Authorization: Bearer sk-or-v1-0af3f3..." | python3 -m json.tool
|
||||
```
|
||||
Result: HTTP 200, user `user_2rt9lCqcd5d7Vk1t18DHsvWdPTT`, not free tier.
|
||||
|
||||
### Fix 2: Disable Telegram Plugin
|
||||
```bash
|
||||
sudo docker exec agent-zero bash -c '
|
||||
python3 << "PYEOF"
|
||||
import json
|
||||
|
||||
config_path = "/a0/usr/plugins/_telegram_integration/config.json"
|
||||
with open(config_path) as f:
|
||||
config = json.load(f)
|
||||
|
||||
config["bots"][0]["enabled"] = False
|
||||
|
||||
with open(config_path, "w") as f:
|
||||
json.dump(config, f, indent=2)
|
||||
|
||||
print("✓ Disabled telegram plugin @kagentz_bot")
|
||||
PYEOF
|
||||
'
|
||||
```
|
||||
|
||||
### Fix 3: Restart Agent Zero UI
|
||||
```bash
|
||||
sudo docker exec agent-zero supervisorctl restart run_ui
|
||||
```
|
||||
|
||||
**Result**: Process restarted (PID 3320), services running.
|
||||
|
||||
### Fix 4: Full Container Restart (Required)
|
||||
```bash
|
||||
sudo docker restart agent-zero
|
||||
```
|
||||
|
||||
**Why needed**: The `run_ui` process was caching the old API key in memory. A full container restart was required to force Agent Zero to reload the `.env` file with the new OpenRouter key.
|
||||
|
||||
**Result**: All services restarted cleanly, no more 401 errors.
|
||||
|
||||
### Fix 5: Update Stale `.env.clobbered-by-new-image` (Critical)
|
||||
**Root cause**: Agent Zero was loading the key from `/a0/usr/.env.clobbered-by-new-image` (line 28) instead of the main `/a0/usr/.env` (line 72). The clobbered file still had the old, stale key.
|
||||
|
||||
**Fix**:
|
||||
```bash
|
||||
KEY=$(grep "^API_KEY_OPENROUTER=" /a0/usr/.env | cut -d"=" -f2-)
|
||||
sed -i "s|^API_KEY_OPENROUTER=.*|API_KEY_OPENROUTER=$KEY|" /a0/usr/.env.clobbered-by-new-image
|
||||
```
|
||||
|
||||
**Lesson**: When updating Agent Zero's `.env`, check BOTH files:
|
||||
- `/a0/usr/.env` (main)
|
||||
- `/a0/usr/.env.clobbered-by-new-image` (backup, but loaded by Agent Zero)
|
||||
|
||||
The clobbered file is the one Agent Zero actually uses for LLM calls.
|
||||
|
||||
---
|
||||
|
||||
## Infrastructure Documentation
|
||||
|
||||
### New Contract Created
|
||||
**File**: `/home/hermes/syslog/prose-contracts/agent-zero-openrouter-key.prose.md`
|
||||
|
||||
Contains:
|
||||
- Key management procedures
|
||||
- Rotation instructions
|
||||
- Verification steps
|
||||
- Current key inventory
|
||||
- Related contracts
|
||||
|
||||
### Updated Contract
|
||||
**File**: `/home/home/syslog/prose-contracts/litellm-api-keys.prose.md`
|
||||
|
||||
Added section:
|
||||
- Agent Zero OpenRouter integration
|
||||
- Key storage locations
|
||||
- Model configuration
|
||||
- Why not LiteLLM proxy
|
||||
- Rotation procedure
|
||||
|
||||
---
|
||||
|
||||
## Current State
|
||||
|
||||
| Component | Status | Details |
|
||||
|-----------|--------|---------|
|
||||
| **OpenRouter Key** | ✅ Valid | `sk-or-v1-0af3f3…`, user verified |
|
||||
| **Telegram Bot** | ✅ Resolved | Plugin disabled, conflicts cleared |
|
||||
| **MCP Services** | ✅ Working | No timeouts after key fix |
|
||||
| **Container** | ✅ Running | PID 3320, uptime 16+ hours |
|
||||
| **Services** | ✅ All UP | run_ui, run_tunnel_api, run_searxng, run_cron, the_listener |
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
| Path | Purpose |
|
||||
|------|---------|
|
||||
| `/a0/usr/.env` | Container key storage |
|
||||
| `/a0/usr/plugins/_telegram_integration/config.json` | Telegram plugin config |
|
||||
| `/a0/usr/plugins/_model_config/presets.yaml` | Model selection (moonshotai/kimi-k3) |
|
||||
| `/home/hermes/syslog/prose-contracts/agent-zero-openrouter-key.prose.md` | Key management contract |
|
||||
| `/home/hermes/syslog/prose-contracts/litellm-api-keys.prose.md` | Fleet key inventory |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Sync key to Infisical vault** (optional, currently .env fallback only)
|
||||
2. **Monitor usage** — Check OpenRouter dashboard for daily/weekly spend
|
||||
3. **Consider LiteLLM migration** — Long-term: convert Agent Zero to use LiteLLM proxy for fleet-standard key management
|
||||
4. **Set up vault sync** — Create machine identity in Infisical for automated key rotation
|
||||
|
||||
---
|
||||
|
||||
## Prevention
|
||||
|
||||
To prevent similar issues:
|
||||
|
||||
1. **Always verify API keys** against their providers before using
|
||||
2. **Keep fleet-wide key inventory** updated in prose contracts
|
||||
3. **Rotate keys on schedule** (quarterly hygiene, not on-demand only)
|
||||
4. **Test key changes** in staging before production rollout
|
||||
5. **Document key locations** in both code and prose contracts
|
||||
|
||||
---
|
||||
|
||||
**Verified by**: Mumuni 🦅
|
||||
**Last updated**: 2026-09-01
|
||||
**Session**: 1
|
||||
@@ -1,129 +0,0 @@
|
||||
---
|
||||
kind: function
|
||||
name: agent-zero-openrouter-key
|
||||
description: >
|
||||
Manages the OpenRouter API key for Agent Zero (Docker container on kagentz .14).
|
||||
Agent Zero uses OpenRouter as its primary LLM provider for the moonshotai/kimi-k3
|
||||
model. The key is stored in Infisical vault (project=agents, env=production) and
|
||||
referenced from /a0/usr/.env in the container. Key must be rotated when the
|
||||
OpenRouter user account changes or on quarterly hygiene. Last verified: 2026-09-01.
|
||||
---
|
||||
|
||||
## Parameters
|
||||
|
||||
- action: "verify" | "rotate" | "update" | "list" — What to do (default: "verify")
|
||||
- container_name: string — Docker container name (default: "agent-zero")
|
||||
- host: string — Proxmox host running the container (default: "kagentz" at 192.168.68.14)
|
||||
- env_path: string — Path to .env file in container (default: "/a0/usr/.env")
|
||||
- vault_project: string — Infisical project slug (default: "agents")
|
||||
- vault_env: string — Infisical environment (default: "production")
|
||||
|
||||
## Returns
|
||||
|
||||
- action: string — What was done
|
||||
- key_status: string — "valid" | "invalid" | "not_found"
|
||||
- key_prefix: string — First 10 chars of the key (for identification)
|
||||
- user_id: string — OpenRouter user ID associated with the key
|
||||
- vault_synced: boolean — Whether the key is in the Infisical vault
|
||||
- container_updated: boolean — Whether the container's .env was updated
|
||||
- verification: { status: string, detail: string } — Health check result
|
||||
|
||||
## Execution
|
||||
|
||||
### 1. Verify the key
|
||||
|
||||
1. **Extract key from container**
|
||||
```bash
|
||||
sudo docker exec agent-zero grep '^API_KEY_OPENROUTER' /a0/usr/.env | cut -d'=' -f2-
|
||||
```
|
||||
|
||||
2. **Test against OpenRouter API**
|
||||
```bash
|
||||
curl -s https://openrouter.ai/api/v1/auth/key \
|
||||
-H "Authorization: Bearer <key>" | python3 -m json.tool
|
||||
```
|
||||
Expected: HTTP 200, JSON with `data.label` and `data.is_free_tier`
|
||||
|
||||
3. **Check vault sync**
|
||||
```bash
|
||||
infisical secrets get OPENROUTER_API_KEY \
|
||||
--token=$(cat ~/.infisical-token) \
|
||||
--projectId=agents \
|
||||
--env=production \
|
||||
--domain=https://vault.sysloggh.net
|
||||
```
|
||||
|
||||
4. **Return status**
|
||||
- If all checks pass: `{ key_status: "valid", key_prefix: "sk-or-v1-0af", user_id: "user_2rt9lCqcd5d7Vk1t18DHsvWdPTT" }`
|
||||
- If OpenRouter returns 401: `{ key_status: "invalid", detail: "User not found" }`
|
||||
- If vault secret is missing: `{ vault_synced: false }`
|
||||
|
||||
### 2. Rotate the key
|
||||
|
||||
1. **Generate new key** in OpenRouter UI or via API
|
||||
2. **Update container .env**
|
||||
```bash
|
||||
sudo docker exec agent-zero sed -i 's/^API_KEY_OPENROUTER=.*/API_KEY_OPENROUTER=<new_key>/' /a0/usr/.env
|
||||
```
|
||||
3. **Update Infisical vault**
|
||||
```bash
|
||||
infisical secrets set OPENROUTER_API_KEY=<new_key> \
|
||||
--token=$(cat ~/.infisical-token) \
|
||||
--projectId=agents \
|
||||
--env=production \
|
||||
--domain=https://vault.sysloggh.net
|
||||
```
|
||||
4. **Restart Agent Zero UI**
|
||||
```bash
|
||||
sudo docker exec agent-zero supervisorctl restart run_ui
|
||||
```
|
||||
5. **Verify** — Run "verify" action again
|
||||
|
||||
### 3. Update (key changed but no rotation)
|
||||
|
||||
1. **Update container .env** (same as rotate step 2)
|
||||
2. **Sync vault** (same as rotate step 3)
|
||||
3. **Restart run_ui** (same as rotate step 4)
|
||||
|
||||
## Current Key Inventory
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Key Prefix** | `sk-or-v1-0af3f3` |
|
||||
| **Full Key** | `«redacted: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»` (in vault + /a0/usr/.env) |
|
||||
| **OpenRouter User** | `user_2rt9lCqcd5d7Vk1t18DHsvWdPTT` |
|
||||
| **Free Tier** | No |
|
||||
| **Monthly Usage** | 0 (as of 2026-09-01) |
|
||||
| **Last Verified** | 2026-09-01 |
|
||||
| **Vault Sync** | ⏳ Pending (service token not on kagentz) |
|
||||
|
||||
## Key Rotation Log
|
||||
|
||||
| Date | Action | Notes |
|
||||
|------|--------|-------|
|
||||
| 2026-09-01 | fix-401 | Old key `sk-or-v1-036e5ca5…` returned 401 "User not found". Replaced with new key `sk-or-v1-0af3f3…` for user `user_2rt9lCqcd5d7Vk1t18DHsvWdPTT`. Verified OpenRouter 200. Container .env updated, run_ui restarted. |
|
||||
|
||||
## Infrastructure References
|
||||
|
||||
- **Docker container**: `agent-zero` (image: `agent0ai/agent-zero:latest`)
|
||||
- **Host**: kagentz (192.168.68.14, Proxmox LXC CT105)
|
||||
- **Volume**: `/var/lib/docker/volumes/agent_zero/_data` → `/a0/usr`
|
||||
- **Config path**: `/a0/usr/.env` (line ~72: `API_KEY_OPENROUTER=…`)
|
||||
- **Model preset**: "Cost Efficient" (uses `openrouter/moonshotai/kimi-k3`)
|
||||
- **Model config**: `/a0/usr/plugins/_model_config/config.json`
|
||||
|
||||
## Verification Before Acting
|
||||
|
||||
**Key is a lead, not a fact.** Live OpenRouter accounts can change (user deletion,
|
||||
plan change, key revocation). Before acting on this contract:
|
||||
|
||||
1. Verify the key against OpenRouter's `/auth/key` endpoint
|
||||
2. Check the user ID matches the expected account
|
||||
3. Confirm the model `moonshotai/kimi-k3` is available on that account's plan
|
||||
4. Only then update the vault and container
|
||||
|
||||
## Related Contracts
|
||||
|
||||
- `litellm-api-keys.prose.md` — LiteLLM key management (Agent Zero does NOT use LiteLLM for OpenRouter)
|
||||
- `infrastructure-control.prose.md` — Proxmox topology, container locations
|
||||
- `gpu-fleet.prose.md` — Fleet-wide agent key inventory (add Agent Zero here)
|
||||
@@ -1,230 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Hermes Config Audit — validates a live config.yaml against the prose contract rules.
|
||||
|
||||
Usage:
|
||||
python3 audit-hermes-config.py <config.yaml>
|
||||
python3 audit-hermes-config.py /root/.hermes/config.yaml
|
||||
|
||||
Exit codes:
|
||||
0 = all checks pass
|
||||
1 = one or more contract violations found
|
||||
|
||||
This script encodes every rule from hermes-config-template.prose.md so config
|
||||
changes can be verified before and after application. It is the single automated
|
||||
enforcement layer for the prose contract.
|
||||
|
||||
Contract: /root/prose-contracts/hermes-config-template.prose.md
|
||||
"""
|
||||
|
||||
import sys
|
||||
import yaml
|
||||
|
||||
VIOLATIONS = []
|
||||
WARNINGS = []
|
||||
PASSES = []
|
||||
|
||||
|
||||
def check(condition, rule, message):
|
||||
if condition:
|
||||
PASSES.append(f"[{rule}] {message}")
|
||||
else:
|
||||
VIOLATIONS.append(f"[{rule}] {message}")
|
||||
|
||||
|
||||
def warn(rule, message):
|
||||
WARNINGS.append(f"[{rule}] {message}")
|
||||
|
||||
|
||||
def audit(path):
|
||||
with open(path) as f:
|
||||
cfg = yaml.safe_load(f)
|
||||
|
||||
model = cfg.get("model", {})
|
||||
fb = cfg.get("fallback_providers", {})
|
||||
comp = cfg.get("compression", {})
|
||||
aux = cfg.get("auxiliary", {})
|
||||
deleg = cfg.get("delegation", {})
|
||||
cps = cfg.get("custom_providers", [])
|
||||
cp = cps[0] if cps else {}
|
||||
|
||||
# --- Rule 3: API Keys via Environment ---
|
||||
check(
|
||||
model.get("api_key") in ("", None),
|
||||
"Rule 3",
|
||||
f"model.api_key must be empty (got {model.get('api_key')!r}) — keys via env var, not hardcoded",
|
||||
)
|
||||
check(
|
||||
model.get("api_key_env") == "LITELLM_API_KEY",
|
||||
"Rule 3",
|
||||
f"model.api_key_env must be LITELLM_API_KEY (got {model.get('api_key_env')!r})",
|
||||
)
|
||||
|
||||
# --- Rule 5: Main Config Base URL ---
|
||||
expected_base = "http://192.168.68.116/v1"
|
||||
check(
|
||||
model.get("base_url") == expected_base,
|
||||
"Rule 5",
|
||||
f"model.base_url must be {expected_base} (got {model.get('base_url')!r}) — /v1 not /litellm/v1",
|
||||
)
|
||||
|
||||
# --- Rule 6: max_tokens Is Required ---
|
||||
check(
|
||||
isinstance(model.get("max_tokens"), int) and model.get("max_tokens") <= 8192,
|
||||
"Rule 6",
|
||||
f"model.max_tokens must be set and <= 8192 (got {model.get('max_tokens')!r}) — thermal safety",
|
||||
)
|
||||
|
||||
# --- Rule 7: Auxiliary Model Consistency ---
|
||||
check(
|
||||
comp.get("model") == "syslog-auto",
|
||||
"Rule 7",
|
||||
f"compression.model must be syslog-auto (got {comp.get('model')!r}) — auto-routing to prevent Strix Halo overload",
|
||||
)
|
||||
aux_comp = aux.get("compression", {})
|
||||
check(
|
||||
aux_comp.get("model") == "syslog-auto",
|
||||
"Rule 7",
|
||||
f"auxiliary.compression.model must be syslog-auto (got {aux_comp.get('model')!r}) — must match compression.model",
|
||||
)
|
||||
|
||||
# --- Rule 8: GPU Workload Distribution ---
|
||||
check(
|
||||
aux.get("vision", {}).get("model") == "gpu-light",
|
||||
"Rule 8",
|
||||
f"auxiliary.vision.model must be gpu-light (got {aux.get('vision', {}).get('model')!r}) — RTX 5070 stable alias",
|
||||
)
|
||||
check(
|
||||
aux.get("web_extract", {}).get("model") == "gpu-light",
|
||||
"Rule 8",
|
||||
f"auxiliary.web_extract.model must be gpu-light (got {aux.get('web_extract', {}).get('model')!r}) — RTX 5070 stable alias",
|
||||
)
|
||||
|
||||
# --- Rule 9: Compression Threshold ---
|
||||
check(
|
||||
comp.get("threshold") == 0.65,
|
||||
"Rule 9",
|
||||
f"compression.threshold must be 0.65 for 128K models (got {comp.get('threshold')!r})",
|
||||
)
|
||||
check(
|
||||
comp.get("max_context_window") == 131072,
|
||||
"Rule 9",
|
||||
f"compression.max_context_window must be 131072 (got {comp.get('max_context_window')!r}) — matches 128K GPU capacity",
|
||||
)
|
||||
|
||||
# --- Rule 10: Default Model Must Be syslog-auto ---
|
||||
check(
|
||||
model.get("default") == "syslog-auto",
|
||||
"Rule 10",
|
||||
f"model.default must be syslog-auto (got {model.get('default')!r}) — auto-routing default",
|
||||
)
|
||||
|
||||
# --- Rule 14: Provider Name Must Match custom_providers Name ---
|
||||
check(
|
||||
model.get("provider") == "harness",
|
||||
"Rule 14",
|
||||
f"model.provider must be 'harness' (got {model.get('provider')!r}) — NOT 'custom'. "
|
||||
f"provider: custom causes generic resolution path that ignores key_env → 'no-key-required' → 401",
|
||||
)
|
||||
check(
|
||||
comp.get("provider") == "harness",
|
||||
"Rule 14",
|
||||
f"compression.provider must be 'harness' (got {comp.get('provider')!r})",
|
||||
)
|
||||
for aux_name in ("vision", "web_extract", "compression"):
|
||||
aux_provider = aux.get(aux_name, {}).get("provider")
|
||||
check(
|
||||
aux_provider == "harness",
|
||||
"Rule 14",
|
||||
f"auxiliary.{aux_name}.provider must be 'harness' (got {aux_provider!r})",
|
||||
)
|
||||
check(
|
||||
deleg.get("provider") == "harness",
|
||||
"Rule 14",
|
||||
f"delegation.provider must be 'harness' (got {deleg.get('provider')!r})",
|
||||
)
|
||||
check(
|
||||
fb.get("provider") == "deepseek",
|
||||
"Rule 14",
|
||||
f"fallback_providers.provider must be 'deepseek' (got {fb.get('provider')!r}) — "
|
||||
f"true fallback diversity, not same endpoint as primary",
|
||||
)
|
||||
check(
|
||||
fb.get("model") == "deepseek-v4-flash",
|
||||
"Rule 14",
|
||||
f"fallback_providers.model must be 'deepseek-v4-flash' (got {fb.get('model')!r})",
|
||||
)
|
||||
check(
|
||||
fb.get("api_key_env") == "DEEPSEEK_API_KEY",
|
||||
"Rule 14",
|
||||
f"fallback_providers.api_key_env must be DEEPSEEK_API_KEY (got {fb.get('api_key_env')!r})",
|
||||
)
|
||||
|
||||
# --- custom_providers sanity ---
|
||||
check(
|
||||
cp.get("name") == "harness",
|
||||
"custom_providers",
|
||||
f"custom_providers[0].name must be 'harness' (got {cp.get('name')!r})",
|
||||
)
|
||||
check(
|
||||
cp.get("key_env") == "LITELLM_API_KEY" or cp.get("api_key_env") == "LITELLM_API_KEY",
|
||||
"custom_providers",
|
||||
f"custom_providers[0] must have key_env or api_key_env = LITELLM_API_KEY "
|
||||
f"(got key_env={cp.get('key_env')!r}, api_key_env={cp.get('api_key_env')!r})",
|
||||
)
|
||||
check(
|
||||
cp.get("base_url", "").endswith("/v1"),
|
||||
"custom_providers",
|
||||
f"custom_providers[0].base_url must end with /v1 (got {cp.get('base_url')!r})",
|
||||
)
|
||||
|
||||
# --- No raw model names (Rule 7/8 spirit) ---
|
||||
raw_names = {"gemma-4-12b", "qwen3.6-27B-code", "qwen3.6-35B-udq4", "ornith-1.0-35b"}
|
||||
for section_path, section_dict in [
|
||||
("model", model), ("compression", comp),
|
||||
("auxiliary.vision", aux.get("vision", {})),
|
||||
("auxiliary.web_extract", aux.get("web_extract", {})),
|
||||
("auxiliary.compression", aux.get("compression", {})),
|
||||
("delegation", deleg),
|
||||
]:
|
||||
m = section_dict.get("model", "")
|
||||
if m in raw_names:
|
||||
warn(
|
||||
"Rule 7/8",
|
||||
f"{section_path}.model = {m!r} — raw model name, use stable alias instead "
|
||||
f"(gpu-light, gpu-dense, strix-moe, syslog-auto)",
|
||||
)
|
||||
|
||||
# --- Report ---
|
||||
print(f"{'=' * 60}")
|
||||
print(f"Hermes Config Audit: {path}")
|
||||
print(f"{'=' * 60}")
|
||||
print(f"\n✅ PASSED ({len(PASSES)}):")
|
||||
for p in PASSES:
|
||||
print(f" ✅ {p}")
|
||||
|
||||
if WARNINGS:
|
||||
print(f"\n⚠️ WARNINGS ({len(WARNINGS)}):")
|
||||
for w in WARNINGS:
|
||||
print(f" ⚠️ {w}")
|
||||
|
||||
if VIOLATIONS:
|
||||
print(f"\n❌ VIOLATIONS ({len(VIOLATIONS)}):")
|
||||
for v in VIOLATIONS:
|
||||
print(f" ❌ {v}")
|
||||
print(f"\n{'=' * 60}")
|
||||
print(f"RESULT: FAIL — {len(VIOLATIONS)} violation(s) must be fixed")
|
||||
print(f"{'=' * 60}")
|
||||
return 1
|
||||
else:
|
||||
print(f"\n{'=' * 60}")
|
||||
print(f"RESULT: PASS — all contract rules satisfied")
|
||||
print(f"{'=' * 60}")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
if len(sys.argv) < 2:
|
||||
print("Usage: python3 audit-hermes-config.py <config.yaml>")
|
||||
sys.exit(2)
|
||||
sys.exit(audit(sys.argv[1]))
|
||||
@@ -45,10 +45,9 @@ description: >
|
||||
## Status
|
||||
|
||||
**Active** — for Hermes agents only. This plugin is NOT retired. It remains in service
|
||||
for Hermes agents that connect to Zulip (Mumuni, Koby, Koonimo). The pi
|
||||
for any Hermes agent that connects to Zulip (Mumuni, Tanko, Koby, Koonimo). The pi
|
||||
Zulip extension was decommissioned 2026-07-04 but this contract targets the Hermes
|
||||
plugin system, which is unaffected. **Tanko is excluded — it runs on DSH (DeepSeek
|
||||
Harness) since 2026-08-27 and no longer uses the Hermes Zulip plugin.**
|
||||
plugin system, which is unaffected.
|
||||
|
||||
## Parameters
|
||||
|
||||
|
||||
+7
-179
@@ -22,7 +22,6 @@ owners:
|
||||
- abiba
|
||||
- mumuni
|
||||
- kwame
|
||||
- ops
|
||||
trigger_types:
|
||||
- scheduled
|
||||
- event_driven
|
||||
@@ -59,7 +58,6 @@ index:
|
||||
- memory-audit-maintenance
|
||||
- gpu-fleet
|
||||
- infrastructure-update
|
||||
- infrastructure-maintenance
|
||||
reference:
|
||||
- infrastructure-control
|
||||
- ra-h-os-custodianship-contract
|
||||
@@ -92,7 +90,6 @@ index:
|
||||
- infrastructure-control
|
||||
- infrastructure-monitoring
|
||||
- infrastructure-update
|
||||
- infrastructure-maintenance
|
||||
- pm2-self-heal
|
||||
- disk-gc-threat-response
|
||||
gpu:
|
||||
@@ -133,6 +130,7 @@ index:
|
||||
- build-zulip-plugin
|
||||
- stirling-pdf-agent-access
|
||||
- gpu-fleet
|
||||
- infrastructure-update
|
||||
- infrastructure-control
|
||||
- zulip-adapter-lessons
|
||||
- pi-approval-architecture
|
||||
@@ -146,9 +144,6 @@ index:
|
||||
- mumuni-delegation
|
||||
kwame:
|
||||
- hello-world
|
||||
ops:
|
||||
- infrastructure-maintenance
|
||||
- infrastructure-update
|
||||
by_trigger:
|
||||
scheduled:
|
||||
- hermes-key-enforcement
|
||||
@@ -161,7 +156,6 @@ index:
|
||||
- litellm-health
|
||||
- memory-audit-maintenance
|
||||
- infrastructure-update
|
||||
- infrastructure-maintenance
|
||||
event_driven:
|
||||
- litellm-self-heal
|
||||
- pm2-self-heal
|
||||
@@ -203,7 +197,6 @@ index:
|
||||
- hermes-zulip-plugin
|
||||
- build-zulip-plugin
|
||||
- infrastructure-update
|
||||
- infrastructure-maintenance
|
||||
- ra-h-os-custodianship-contract
|
||||
- mumuni-delegation
|
||||
normal:
|
||||
@@ -584,7 +577,7 @@ contracts:
|
||||
verify: curl -sf https://git.sysloggh.net/api/v1/version
|
||||
expect: 200 OK
|
||||
- check: SearXNG reachable
|
||||
verify: curl -sf http://192.168.68.7:8888
|
||||
verify: curl -sf http://192.168.68.17:8080
|
||||
expect: 200 OK
|
||||
artifact: infrastructure health report
|
||||
receipt:
|
||||
@@ -628,18 +621,18 @@ contracts:
|
||||
sensitivity: high
|
||||
status: active
|
||||
owner: abiba
|
||||
version: 3.1.0
|
||||
version: 3.0.0
|
||||
trigger:
|
||||
type: scheduled
|
||||
cadence: '*/15 * * * *'
|
||||
description: "Every 15 minutes \u2014 monitors the Zulip-connected agents under this host's control (pi, DSH, Agent Zero)"
|
||||
description: "Every 15 minutes \u2014 monitors all Zulip-connected agents"
|
||||
cron_job_id: null
|
||||
execution:
|
||||
agent: abiba
|
||||
timeout: 120
|
||||
requires:
|
||||
- Zulip API key for abiba-bot@chat.sysloggh.net
|
||||
- SSH access to amdpve (192.168.68.15) for Tanko (CT 112) and the Agent Zero Docker host (.14)
|
||||
- SSH access to all Hermes agents
|
||||
verification:
|
||||
postconditions:
|
||||
- check: bot registration active
|
||||
@@ -1155,7 +1148,7 @@ contracts:
|
||||
type: scheduled
|
||||
cadence: 0 3 * * *
|
||||
description: Daily at 3am ET
|
||||
cron_job_id: b59f3cc21f4c # provisioned on kagentz 2026-09-08 (okyeame-memory-audit, glm-5.3-flash)
|
||||
cron_job_id: null
|
||||
execution:
|
||||
agent: mumuni
|
||||
timeout: 600
|
||||
@@ -1263,108 +1256,13 @@ contracts:
|
||||
last_run: null
|
||||
last_status: null
|
||||
drift_alerts: []
|
||||
- name: infrastructure-maintenance
|
||||
file: infrastructure-maintenance.prose.md
|
||||
kind: responsibility
|
||||
category: maintenance
|
||||
sensitivity: high
|
||||
status: active
|
||||
owner: ops
|
||||
version: 1.0.0
|
||||
trigger:
|
||||
type: scheduled
|
||||
cadence: 0 2 * * 0
|
||||
description: Weekly host-level maintenance Sunday at 2am ET (replaces infrastructure-update
|
||||
build-phase role; infra-update moves to ops)
|
||||
cron_job_id: null
|
||||
execution:
|
||||
agent: ops
|
||||
timeout: 3600
|
||||
requires:
|
||||
- infrastructure-monitoring run within last 30 minutes (pre-update health baseline)
|
||||
- Proxmox snapshot of primary host OR /tmp backup dir created this run
|
||||
- LiteLLM master key from Infisical vault for health verification
|
||||
protocol:
|
||||
- Load contract from prose-contracts/main
|
||||
- Phase 0 preflight — capture health baseline, backup check, record image baseline
|
||||
- Phase 1 apt update && apt upgrade -y on primary host
|
||||
- Phase 2 docker compose pull for LiteLLM, SearXNG, and other running containers
|
||||
- Phase 3 restart stacks one at a time with per-stack health verification
|
||||
- Phase 4 verify every critical service (LiteLLM, SearXNG, Zulip, Gitea, PM2, Hermes gateways)
|
||||
- On failure — rollback per protocol, escalate, do not loop beyond circuit breaker
|
||||
- Log actions to ~/.hermes/runs/infrastructure-maintenance/
|
||||
verification:
|
||||
postconditions:
|
||||
- check: all critical services running after update
|
||||
verify: 'curl -sf http://192.168.68.116/litellm/v1/models && curl -sf https://chat.sysloggh.net/api/v1/server_settings && curl -sf https://git.sysloggh.net/api/v1/version && curl -sf http://192.168.68.7:8888 && pm2 jlist'
|
||||
expect: all probes 200 OK / processes online
|
||||
- check: no regressions from pre-update health baseline
|
||||
verify: diff Phase 0 health-baseline against Phase 4 results
|
||||
expect: no GREEN service turned RED
|
||||
- check: docker containers on latest stable tags
|
||||
verify: docker inspect --format '{{.Config.Image}}' <container> per service matches image-baseline.pulled_tag
|
||||
expect: all containers running pulled tags
|
||||
- check: APT packages up to date with no held broken packages
|
||||
verify: apt list --upgradable 2>/dev/null | wc -l and apt-get -s upgrade | grep -ci broken
|
||||
expect: upgradable == 0, broken == 0
|
||||
artifact: maintenance run report with phase results and any rollback/escalation
|
||||
verify_commands:
|
||||
- curl -sf http://192.168.68.116/litellm/v1/models
|
||||
- curl -sf http://192.168.68.7:8888
|
||||
- curl -sf https://chat.sysloggh.net/api/v1/server_settings
|
||||
- curl -sf https://git.sysloggh.net/api/v1/version
|
||||
- pm2 jlist
|
||||
receipt:
|
||||
format: json
|
||||
storage: ~/.hermes/runs/infrastructure-maintenance/
|
||||
graph_node: true
|
||||
schema:
|
||||
contract: string
|
||||
run_id: string
|
||||
timestamp: ISO 8601
|
||||
agent: string
|
||||
status: pass|fail|escalated
|
||||
phase: preflight|apt|images|restarts|verify|rollback|done|failed
|
||||
actions_taken: array
|
||||
postconditions: array
|
||||
drift_alerts: array
|
||||
evidence_path: string
|
||||
escalation:
|
||||
info:
|
||||
action: log_to_receipt
|
||||
notify: []
|
||||
warning:
|
||||
action: relay_alert
|
||||
notify:
|
||||
- abiba
|
||||
- mumuni
|
||||
critical:
|
||||
action: relay_alert
|
||||
notify:
|
||||
- abiba
|
||||
- mumuni
|
||||
fatal:
|
||||
action: relay_alert + pause + human_required
|
||||
notify:
|
||||
- abiba
|
||||
- mumuni
|
||||
- kwame
|
||||
circuit_breaker:
|
||||
max_retries: 2
|
||||
window: 7200
|
||||
trip_action: escalate_to_fatal
|
||||
depends_on:
|
||||
- infrastructure-monitoring
|
||||
last_run: null
|
||||
last_status: null
|
||||
drift_alerts: []
|
||||
- name: infrastructure-update
|
||||
file: infrastructure-update.prose.md
|
||||
kind: responsibility
|
||||
category: maintenance
|
||||
sensitivity: high
|
||||
status: active
|
||||
owner: ops
|
||||
owner: abiba
|
||||
version: 1.0.0
|
||||
trigger:
|
||||
type: scheduled
|
||||
@@ -1867,73 +1765,3 @@ contracts:
|
||||
last_run: null
|
||||
last_status: null
|
||||
drift_alerts: []
|
||||
# Koby Report-Only Registry (2026-08-17 — Captain)
|
||||
# ⛔ KOBY IS NEVER REPAIRED — detect + report, never fix on .129
|
||||
koby_report_only: true
|
||||
koby_host: "CT 111 (tdunna)"
|
||||
koby_ip: ".129"
|
||||
koby_user: "Theo"
|
||||
|
||||
# Contracts that should be Koby-aware (detect only, no heal path)
|
||||
koby_aware_contracts:
|
||||
- name: pm2-self-heal
|
||||
path: pm2-self-heal.prose.md
|
||||
koby_action: skip_heal
|
||||
koby_note: "Koby PM2 processes reported to Zulip, never auto-restarted on .129"
|
||||
|
||||
- name: zulip-health
|
||||
path: zulip-health.prose.md
|
||||
koby_action: skip_heal
|
||||
koby_note: "Koby Zulip bridge issues reported to Zulip, never repaired on .129"
|
||||
|
||||
- name: hermes-zulip-restore
|
||||
path: hermes-zulip-restore.prose.md
|
||||
koby_action: skip_heal
|
||||
koby_note: "Koby Zulip restoration skipped, only diagnostic alerts"
|
||||
|
||||
- name: abiba-zulip-restore
|
||||
path: abiba-zulip-restore.prose.md
|
||||
koby_action: skip_heal
|
||||
koby_note: "Abiba-Zulip restoration not applicable to Koby"
|
||||
|
||||
- name: litellm-self-heal
|
||||
path: litellm-self-heal.prose.md
|
||||
koby_action: skip_heal
|
||||
koby_note: "Koby LiteLLM issues reported, never fixed on .129"
|
||||
|
||||
- name: disk-gc-threat-response
|
||||
path: disk-gc-threat-response.prose.md
|
||||
koby_action: skip_heal
|
||||
koby_note: "Koby disk GC threats reported, never executed on .129"
|
||||
|
||||
- name: memory-fixer
|
||||
path: memory-fixer.prose.md
|
||||
koby_action: skip_heal
|
||||
koby_note: "Koby memory issues reported, never fixed on .129"
|
||||
|
||||
- name: memory-audit-maintenance
|
||||
path: memory-audit-maintenance.prose.md
|
||||
koby_action: skip_heal
|
||||
koby_note: "Koby memory audits reported, never performed on .129"
|
||||
|
||||
- name: gpu-self-heal
|
||||
path: gpu-self-heal.prose.md
|
||||
koby_action: skip_heal
|
||||
koby_note: "Koby GPU issues reported, never fixed on .129"
|
||||
|
||||
- name: gpu-monitor
|
||||
path: gpu-monitor.prose.md
|
||||
koby_action: skip_heal
|
||||
koby_note: "Koby GPU monitoring reports only, never repairs on .129"
|
||||
|
||||
- name: agent-health-check
|
||||
path: agent-health-check.prose.md
|
||||
koby_action: skip_heal
|
||||
koby_note: "Koby agent health checks reported, never repairs on .129"
|
||||
|
||||
# Scripts that should skip Koby
|
||||
koby_aware_scripts:
|
||||
- name: agent-health-check.py
|
||||
path: scripts/agent-health-check.py
|
||||
koby_action: skip_heal
|
||||
koby_note: "Script should only run diagnostics on Koby, not repairs"
|
||||
|
||||
@@ -356,7 +356,7 @@ Postconditions to verify:
|
||||
},
|
||||
{
|
||||
"check": "SearXNG reachable",
|
||||
"verify": "curl -sf http://192.168.68.7:8888",
|
||||
"verify": "curl -sf http://192.168.68.17:8080",
|
||||
"expect": "200 OK"
|
||||
}
|
||||
]
|
||||
|
||||
@@ -1,75 +0,0 @@
|
||||
# Delivery Record — HERMES-PLAYBOOK-FOR-SCOT
|
||||
|
||||
## Status: SEND-READY — awaiting Kwame's channel + recipient confirmation
|
||||
|
||||
No documented channel to Scot Murray exists in this workspace, the skills, or config
|
||||
(verified 2026-09-11 by sweep of `~/syslog/projects/murray-capital/`, `syslog-infra`
|
||||
references, `murray-harness` skill, `.hermes/memories/`, all of `~/syslog/`).
|
||||
Per the card's unblock constraints: package prepared, exact send commands written
|
||||
below, nothing transmitted. Guessing an address is out of scope.
|
||||
|
||||
## Verified artifact (single source of truth)
|
||||
|
||||
| Item | Value |
|
||||
|---|---|
|
||||
| Markdown source | `/home/hermes/syslog/prose-contracts/deliverables/scot-hermes-playbook/HERMES-PLAYBOOK-FOR-SCOT.md` |
|
||||
| sha256 | `b0966a649fec96da4975ec00e627fbaba3a92a62c4a92b33bc06589c47d25f7f` |
|
||||
| Size | 28821 bytes, 377 lines |
|
||||
| Matches reviewed bytes | YES — identical to `/home/hermes/syslog/drafts/scot-hermes-playbook/` copy and to the hash recorded on card t_2c716052 |
|
||||
|
||||
## Rendered PDF (from the verified bytes, no edits)
|
||||
|
||||
| Item | Value |
|
||||
|---|---|
|
||||
| PDF | `/home/hermes/syslog/prose-contracts/deliverables/scot-hermes-playbook/HERMES-PLAYBOOK-FOR-SCOT.pdf` |
|
||||
| sha256 | `f46c0c89b4bbf6fa76c1f1c385c87753860d06bfa9e8925d6e09f27ed78a187b` |
|
||||
| Size | 96,486 bytes · 13 pages · A4 |
|
||||
| Render chain | pandoc 3.1.11.1 (gfm → html5) + WeasyPrint 62.3, stylesheet `pb.css`; reproducible via `bash render_pdf.sh` |
|
||||
| Spot-check | pdftotext shows correct title page + v0.21.1 verification note |
|
||||
|
||||
## Candidate channels — exact commands (pending Kwame's pick + address)
|
||||
|
||||
### 1. Email via syslog-email profile (recommended)
|
||||
|
||||
Mailbox ops belong to the syslog-email profile per standing rule. Send as
|
||||
jerome@sysloggh.com with both attachments.
|
||||
|
||||
```
|
||||
hermes -p syslog-email chat -q "Send an email. From jerome@sysloggh.com. \
|
||||
To: <SCOT-ADDRESS — Kwame to supply>. Subject: 'Hermes Playbook — getting real mileage out of the harness'. \
|
||||
Attach: /home/hermes/syslog/prose-contracts/deliverables/scot-hermes-playbook/HERMES-PLAYBOOK-FOR-SCOT.pdf \
|
||||
and HERMES-PLAYBOOK-FOR-SCOT.md. Body: short intro noting the PDF is the reviewed v0.21.1 playbook, \
|
||||
sha256 b0966a64… (sic, abbreviated), ask him to flag anything confusing — that feedback feeds the harness build. \
|
||||
Show me the draft before sending."
|
||||
```
|
||||
|
||||
Direct himalaya (only if Kwame wants it from the main session — normally NOT, per
|
||||
the email-routing standing rule):
|
||||
|
||||
```
|
||||
himalaya message write --to "<SCOT-ADDRESS>" --subject "Hermes Playbook — getting real mileage out of the harness" \
|
||||
--attachment .../HERMES-PLAYBOOK-FOR-SCOT.pdf --attachment .../HERMES-PLAYBOOK-FOR-SCOT.md
|
||||
himalaya message send <draft.eml>
|
||||
```
|
||||
|
||||
### 2. Telegram (only if Kwame has Scot's handle)
|
||||
|
||||
Send the PDF to Scot's handle from the gateway-connected Telegram session:
|
||||
|
||||
```
|
||||
hermes chat -q "Send the file /home/hermes/syslog/prose-contracts/deliverables/scot-hermes-playbook/HERMES-PLAYBOOK-FOR-SCOT.pdf to <SCOT-HANDLE> with a one-line intro."
|
||||
```
|
||||
|
||||
### 3. Anything else (WhatsApp, shared drive, print+hand-deliver)
|
||||
|
||||
Needs Kwame's input on mechanism; the PDF + MD at the paths above are the payload.
|
||||
|
||||
## Post-send obligations (from the card)
|
||||
|
||||
1. Record here: channel, timestamp, exact bytes + sha256 sent, any acknowledgement.
|
||||
2. Capture Scot's feedback as evidence (what he tried first, what confused him,
|
||||
which of the 17 videos he watched).
|
||||
3. Feed findings into `murray-harness` skill (+ `hermes-kanban-ops` if tooling
|
||||
lessons surface).
|
||||
4. If no reply in 7 days: ONE follow-up nudge is in scope; more is Kwame's call.
|
||||
5. Feature gaps he reports → separate card, do not widen this one.
|
||||
@@ -1,377 +0,0 @@
|
||||
# The Hermes Playbook — getting real mileage out of the harness
|
||||
|
||||
Prepared for Scot (Syslog Solution LLC). Version: Hermes Agent v0.21.1. Every CLI command below was verified live against that version on a reference install (Syslog kagentz) on 2026-09-11; anything only confirmed against the official docs is tagged DOC-ONLY.
|
||||
|
||||
You are already running Hermes next to Claude Code, on your own OpenRouter account with fast models (qwen3.8-flash, deepseek-4-flash). The question you asked: why does Hermes feel like it has less context, and what do I do about it?
|
||||
|
||||
---
|
||||
|
||||
## 1. TL;DR
|
||||
|
||||
- The context gap is not a bug. Claude Code reads the repo it sits in on every launch; a fresh Hermes install starts nearly empty by design. It gets its context from files you seed and from memory it builds over time.
|
||||
- One command closes most of the gap on day one: `hermes import-agent claude-code` carries your CLAUDE.md instructions, MCP servers, skills, and memories into Hermes (preview first with `--dry-run`).
|
||||
- Teach Hermes once, and it remembers: "save this as a skill" after any workflow you repeat. Skills auto-load when a matching task comes up — that is the learning loop.
|
||||
- Keep per-project context in an `AGENTS.md` in the repo root (git-tracked, shared with your team) and personal preferences in your persona file and persistent memory.
|
||||
- Hermes and Claude Code are not rivals: let Hermes be the always-on orchestrator (research, briefs, scheduling, messaging) and hand heavy coding to Claude Code, which Hermes can drive directly.
|
||||
|
||||
---
|
||||
|
||||
## 2. Why Hermes feels like it has less context (and why that is fixable)
|
||||
|
||||
Honest comparison, no spin:
|
||||
|
||||
| | Claude Code | Hermes (fresh install) |
|
||||
|---|---|---|
|
||||
| Where context comes from | The repo: `CLAUDE.md` auto-loaded every launch; `.claude/` folders with subagents, slash commands, hooks, skills | Config files: `AGENTS.md` in the working directory + `SOUL.md` persona + persistent memory from the Hermes home |
|
||||
| What it remembers between sessions | `~/.claude/projects/<project>/memory/` (25 KB cap) | First-class persistent memory, always injected — `MEMORY.md` / `USER.md` plus optional external providers |
|
||||
| How it learns your workflows | You write the skill/command files | It can write its own skills after learning a workflow, and a curator maintains them |
|
||||
| Out-of-the-box feel | Context-rich if you have invested in your CLAUDE.md | Quiet until you seed it |
|
||||
|
||||
That last line is the whole story. Claude Code's context is the sum of everything you built in `CLAUDE.md` and `.claude/` over months. A fresh Hermes has none of that yet — not because the harness is weaker, but because it stores context in different places and expects you to seed it (or let it build up).
|
||||
|
||||
The gap is fixable in two moves:
|
||||
|
||||
1. **Import what you already have.** `hermes import-agent claude-code` maps CLAUDE.md/AGENTS.md instructions, permission allowlists, MCP servers, skills, and memories into Hermes equivalents. Preview with `--dry-run`; it never imports API keys; conflicts are skipped by default (`--overwrite` to change).
|
||||
2. **Let the learning loop run.** Every time you correct Hermes or finish a workflow you will repeat, tell it to remember. Within a few weeks it will have its own CLAUDE.md equivalent — built, not typed.
|
||||
|
||||
What the comparison table in our research covers, gap by gap: project instructions, instruction splits, slash commands, subagents, skills, project memory, tool permissions, MCP, session resume, cost/context visibility, headless mode, prior-setup import, hooks, and scheduled work. Each has a Hermes equivalent, and every one is documented in section 9.
|
||||
|
||||
---
|
||||
|
||||
## 3. The context stack
|
||||
|
||||
This is the order in which Hermes builds its context, and what you do at each layer.
|
||||
|
||||
**Layer 1 — Persona (`SOUL.md`).** Set up once. Your Hermes' standing identity and voice: "you are my analyst," the tone, the standing rules. Auto-injected into every session. Lives at `~/.hermes/SOUL.md` (per profile: `~/.hermes/profiles/<name>/SOUL.md`). Docs: https://hermes-agent.nousresearch.com/docs/user-guide/configuration
|
||||
|
||||
**Layer 2 — Persistent memory.** Set up once, then feed it constantly. `MEMORY.md` / `USER.md` are always active and injected every session — this is the single biggest cure for "it forgets my project." After any correction or preference ("use this source list," "briefs go in this format"), tell Hermes to remember it. Manage with `hermes memory setup|status|off|reset` (VERIFIED-LIVE). Optional external providers exist (Honcho, Mem0, and others). Docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/memory
|
||||
|
||||
**Layer 3 — Skills.** Set up once; grows forever. Markdown procedure files that auto-load when a task matches the skill. The differentiator: after completing a workflow, ask Hermes to "save this as a skill" — it authors the skill itself, and a background curator tracks usage, archives stale ones, and keeps backups. CLI: `hermes skills list|search|install|browse|config|check|update` (VERIFIED-LIVE); in-session: `/skill <name>`, `/reload-skills` (DOC-ONLY). Docs: https://hermes-agent.nousresearch.com/docs/reference/skills-catalog and https://hermes-agent.nousresearch.com/docs/user-guide/features/curator
|
||||
|
||||
**Layer 4 — Projects.** Per workstream. `AGENTS.md` in each repo root (git-tracked, team-shared) carries project rules; Desktop Projects (`hermes project create <name>` then `add-folder`) group multi-repo work under one named workspace. Both VERIFIED-LIVE.
|
||||
|
||||
**Layer 5 — Retrieval (session store).** Automatic. All conversations land in a searchable store; Hermes can search past sessions when you ask "what did we decide last week." CLI: `hermes sessions list|browse|rename|pin|export|prune|stats` (VERIFIED-LIVE).
|
||||
|
||||
**Layer 6 — MCP (external tools).** Per integration. Plug GitHub, databases, workflow engines into the agent. `hermes mcp add|list|test|configure|picker|catalog|install` (VERIFIED-LIVE). Docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp
|
||||
|
||||
Quick summary:
|
||||
|
||||
| Layer | Set up | Feed |
|
||||
|---|---|---|
|
||||
| SOUL.md persona | once | rarely |
|
||||
| Persistent memory | once | every correction/preference |
|
||||
| Skills | once | "save this as a skill" after repeated workflows |
|
||||
| AGENTS.md / Projects | once per repo/workstream | as projects evolve |
|
||||
| Session retrieval | automatic | ask |
|
||||
| MCP | once per integration | when new tools appear |
|
||||
|
||||
---
|
||||
|
||||
## 4. Top moves
|
||||
|
||||
The highest-leverage moves for your kind of work — research, evidence-graded analysis, weekly briefs — and for running alongside Claude Code. Every command verified on v0.21.1.
|
||||
|
||||
### 1. Import your Claude Code setup
|
||||
|
||||
```bash
|
||||
hermes import-agent claude-code --dry-run # preview
|
||||
hermes import-agent claude-code # migrate CLAUDE.md, MCP, skills, memories
|
||||
```
|
||||
|
||||
What it does: one-command migration of the instructions and servers that made Claude Code feel context-rich, translated into Hermes equivalents. Never imports API keys.
|
||||
Why it matters: this is the direct answer to "Hermes has no context." After this, Hermes knows your projects on day one.
|
||||
|
||||
### 2. Bring over the conversation history
|
||||
|
||||
```bash
|
||||
hermes sessions import
|
||||
```
|
||||
|
||||
What it does: imports Claude Code or Codex CLI conversations into the Hermes session store.
|
||||
Why it matters: mid-project, the new agent picks up exactly where the old one left off. `hermes --resume <id>` and `hermes sessions browse` then treat the history as native.
|
||||
|
||||
### 3. Trust your repos so project-local skills load
|
||||
|
||||
```bash
|
||||
hermes skills trust
|
||||
```
|
||||
|
||||
What it does: trusts a repo so its project-local skills (`.hermes/skills`) load — the Hermes analog of `.claude/skills/`.
|
||||
Why it matters: your evidence-grading rules can live in the repo with the project, versioned with git, and load automatically.
|
||||
|
||||
### 4. Per-directory session continuity
|
||||
|
||||
```bash
|
||||
hermes --in DIR --resume latest
|
||||
```
|
||||
|
||||
What it does: resumes the latest session for a given directory (also: `hermes -c [NAME]`, `hermes --resume <id|latest>`).
|
||||
Why it matters: every project folder gets its own continuous thread. Research on one portfolio never mixes with another.
|
||||
|
||||
### 5. Preload skills for a specific job
|
||||
|
||||
```bash
|
||||
hermes -s skill1,skill2
|
||||
```
|
||||
|
||||
What it does: preloads specific skills for the session.
|
||||
Why it matters: for a weekly brief or an evidence register, pin the exact skills that encode your grading criteria instead of hoping they auto-match.
|
||||
|
||||
### 6. Save any repeated workflow as a skill
|
||||
|
||||
In-session: "save this as a skill." (CLI: `hermes skills list|search|install|browse`.)
|
||||
|
||||
What it does: Hermes authors a skill file from the workflow you just ran.
|
||||
Why it matters: the learning loop is the whole point. Do the evidence-grading pass twice, save it, and every future run starts with the procedure loaded.
|
||||
|
||||
### 7. Fan out research with subagents
|
||||
|
||||
In-session: "delegate this to subagents." (agent-side tool `delegate_task`, no CLI.)
|
||||
|
||||
What it does: parallel subagents with isolated contexts — each gets its own conversation and terminal, only the final summary comes back.
|
||||
Why it matters: research fan-out without flooding your main context. Ten sources, ten subagents, one synthesis.
|
||||
|
||||
### 8. Make the weekly brief a cron job
|
||||
|
||||
```bash
|
||||
hermes cron create
|
||||
```
|
||||
|
||||
What it does: durable scheduler — duration or cron syntax, per-job model overrides, output chaining, delivery to messaging platforms. Manage with `hermes cron list|create|edit|pause|resume|run|remove|doctor`.
|
||||
Why it matters: a weekly brief is exactly a cron job. It runs even when you are not at the desktop, with your skills preloaded and its output delivered to you.
|
||||
|
||||
### 9. Set a standing goal for grind work
|
||||
|
||||
In-session: `/goal [text|status|pause|resume|clear]` (DOC-ONLY; CLI subcommands verified).
|
||||
|
||||
What it does: a standing objective the agent keeps working toward across turns until achieved.
|
||||
Why it matters: "keep researching until you have 5 verified sources" — the agent loops itself instead of waiting for you to say "go on."
|
||||
|
||||
### 10. Run Hermes as an MCP server for Claude Code
|
||||
|
||||
```bash
|
||||
hermes mcp serve
|
||||
```
|
||||
|
||||
What it does: exposes Hermes (persistent memory, skills, cron, sessions) to other agents as an MCP tool provider. Claude Code supports MCP clients, so it can consume Hermes.
|
||||
Why it matters: the reverse bridge. Claude Code gets the surfaces it lacks, and both tools share your knowledge base.
|
||||
|
||||
### 11. Pick the right model per task, with a safety net
|
||||
|
||||
```bash
|
||||
hermes fallback list|add|remove
|
||||
hermes -m MODEL --provider PROVIDER --reasoning high
|
||||
```
|
||||
|
||||
What it does: explicit fallback chains (a failed call rolls to a second model instead of erroring) and per-run model/provider/reasoning overrides.
|
||||
Why it matters: on OpenRouter with fast models, use `--reasoning high` for the hard analytical passes and let fallback chains keep the cheap models from stalling your brief.
|
||||
|
||||
### 12. Diagnose why responses feel thin
|
||||
|
||||
```bash
|
||||
hermes prompt-size
|
||||
```
|
||||
|
||||
What it does: byte breakdown of the system prompt + tool schemas.
|
||||
Why it matters: when output quality drops, it is usually context bloat, not model quality. This tells you what is eating the window.
|
||||
|
||||
---
|
||||
|
||||
## 5. Working alongside Claude Code
|
||||
|
||||
You run both. The proven patterns, in order of value.
|
||||
|
||||
**First: import.** `hermes import-agent claude-code` then `hermes sessions import`. After this, the "two tools that don't know each other" problem is gone — Hermes knows your projects and your history.
|
||||
|
||||
**Hermes as orchestrator, Claude Code as worker.** The installed Hermes skill for exactly this is `autonomous-ai-agents/delegate-coding-agent`. Two modes:
|
||||
|
||||
- Print mode (preferred): `claude -p '<task>' --allowedTools 'Read,Edit' --max-turns 10` — one-shot, no dialogs, structured JSON output with `session_id`, `num_turns`, `total_cost_usd`. In Hermes, just say: "delegate this coding task to Claude Code in print mode."
|
||||
- Interactive PTY via tmux: Hermes starts a tmux session, sends prompts with `send-keys`, monitors with `capture-pane`. For iterative refactor → review → fix cycles.
|
||||
|
||||
There is also a cross-agent review loop: `git diff main...feature | claude -p 'Review this diff for bugs and security issues.' --max-turns 1` — Hermes runs it, reads the findings, and fixes them itself. Claude Code becomes a reviewer Hermes coordinates.
|
||||
The skill's safety rails: explicit workdir, clean git status before launch, narrow task prompts, git diff review, targeted tests before committing.
|
||||
|
||||
**Parallel workstreams, neutral merge reconciliation.** When both agents edit the same repo and collide, do not let either resolve the conflict — both are biased toward their own side. Spawn a neutral third agent with the `merge-reconciler` skill: it classifies every conflicted hunk, resolves under an impartiality contract, verifies with build/tests, and hands back a summary naming every decision. Kanban shape: a reconciliation card assigned to a third profile, with both workers' cards as parents.
|
||||
|
||||
**Hermes as MCP server (the reverse direction).** `hermes mcp serve` (pattern in section 4, move 10). The only bridge direction Claude Code cannot offer.
|
||||
|
||||
**Desktop GUI goes to Hermes.** Claude Code has no desktop automation. `hermes computer-use install` (cua-driver; health check `hermes computer-use doctor`) drives native desktop apps background-first — never steals focus. If a task needs Excel or a native app, that part routes to Hermes while the code routes to Claude Code.
|
||||
|
||||
**Division of labor in one line:** Hermes is the always-on layer — research, briefs, scheduling, messaging, memory, and the orchestration desk. Claude Code is the deep coding worker. Hand coding-heavy tasks over; hand continuity, recall, and scheduled work to Hermes.
|
||||
|
||||
---
|
||||
|
||||
## 6. Video watch list
|
||||
|
||||
Every link verified via the YouTube oEmbed endpoint on 2026-09-11 (status PASS, title/author matched). All content is third-party ecosystem material — no official Nous Research tutorial video exists (see section 8).
|
||||
|
||||
| # | Title | Channel | Length | Link | What it demonstrates | Watch when you want to |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 1 | Learn 95% of Hermes Agent in 31 Minutes | Sharbel A. | 31:28 | https://www.youtube.com/watch?v=Ta2wg6xPaY4 | End-to-end fundamentals: install, sessions, skills, memory, the learning loop | the fastest real overview of the whole harness before touching config |
|
||||
| 2 | Hermes Agent Fundamentals In 29 Minutes | Tina Huang | 29:40 | https://www.youtube.com/watch?v=5_N84t1rUU0 | Why Hermes' memory/skills loop differs from one-shot coding agents | understand why Hermes feels different from Claude Code |
|
||||
| 3 | Every Level of Hermes Agent Explained | Jack Roberts | 25:35 | https://www.youtube.com/watch?v=6GtF_uHbGhw | Beginner to advanced ladder: memory, skills, automation, multi-agent | a map of what to learn next after the basics |
|
||||
| 4 | Hermes Agent Full Tutorial INSTALLATION + USECASES | CodeHead | 7:47 | https://www.youtube.com/watch?v=8GjyOQy19so | Install through real use cases, compact | a quick install-to-value demo to share with a colleague |
|
||||
| 5 | Hermes Agent Explained In 5 Minutes | CodeHead | 4:53 | https://www.youtube.com/watch?v=9GpWELm3_XI | Conceptual pitch of the agent and its learning loop | the elevator pitch before committing 30 minutes |
|
||||
| 6 | 100 Days With Hermes Agent in 21 Minutes | Sharbel A. | 21:19 | https://www.youtube.com/watch?v=sCa3BtpkziQ | What memory/skills accumulation looks like after months of daily use | see the payoff of the learning loop over time |
|
||||
| 7 | Hermes Agent - Crash Course for Beginners (AI Agent) | Adrian Twarog | 22:19 | https://www.youtube.com/watch?v=4sAmpcSOVEw | Beginner crash course from a well-known dev channel | a second independent explanation of the basics |
|
||||
| 8 | Hermes Agent: The Ultimate Beginner's Guide | Metics Media | 37:08 | https://www.youtube.com/watch?v=CwPUOVUdApE | Long-form beginner guide incl. setup and everyday workflows | the most thorough single walkthrough in one sitting |
|
||||
| 9 | Hermes Agent Just Killed OpenClaw (Full Tutorial) | Leon van Zyl | 19:59 | https://www.youtube.com/watch?v=jmtpYUOr7_U | Feature-by-feature tutorial (MCP config, memory, agents) | a practitioner's feature-by-feature tutorial |
|
||||
| 10 | Hermes Agent vs OpenClaw | Sharbel A. | 15:28 | https://www.youtube.com/watch?v=zwqhemjHq3E | Head-to-head comparison of the two agent harnesses | the tradeoffs between Hermes and its main alternative |
|
||||
| 11 | Better than OpenClaw? Testing Hermes Agent w/ Qwen 3 model | Tonbi's AI Garage | 15:08 | https://www.youtube.com/watch?v=8tpuky8HpXw | Hermes driven by an OpenRouter-served open model | how small open models behave inside Hermes |
|
||||
| 12 | Use This To Make The Hermes Agent Basically Free | AI LABS | 13:08 | https://www.youtube.com/watch?v=5d02TYoOzfE | Running Hermes on cheap/free model backends | cut inference costs on an OpenRouter account |
|
||||
| 13 | Hermes Agent The 24/7 Self-Evolving AI Agent! | WorldofAI | 9:15 | https://www.youtube.com/watch?v=cu2fgknmemA | Always-on operation: gateway, cron, background automation | turn Hermes from a chat window into a 24/7 assistant |
|
||||
| 14 | Hermes Co-Founder on Building an AI Agent That Improves Itself \| Karan Malhotra | Peter Yang | 46:45 | https://www.youtube.com/watch?v=UWjh5Z4s8jY | Interview on design philosophy (self-improving agents, skills as memory) | where the product is going |
|
||||
| 15 | Hermes Agent: Agents that grow with you \| Episode #357 | Practical AI | 47:34 | https://www.youtube.com/watch?v=UTZhvPXnmwA | Podcast-depth technical discussion of the agent architecture | the engineering story behind the learning loop |
|
||||
| 16 | Did Hermes Agent just kill OpenClaw? (full guide) | Alex Finn | 13:55 | https://www.youtube.com/watch?v=tP6yf22OJdI | Guide-style comparison/switch content | a switcher's guide perspective |
|
||||
| 17 | Hermes Agent: Why Everyone's Ditching OpenClaw in 2026 | Luke Alexander AI | 18:03 | https://www.youtube.com/watch?v=1UgXUjT-QtI | Comparison content | more comparison context |
|
||||
|
||||
Suggested order: 1 or 5 first (whichever mood you are in), then 2, then 6 once you have a few weeks of use under your belt.
|
||||
|
||||
---
|
||||
|
||||
## 7. Your first 7 days
|
||||
|
||||
One action per day, each finishable in 15 minutes.
|
||||
|
||||
**Day 1 — Import.** `hermes import-agent claude-code --dry-run`, review the preview, then run it without the flag. Your CLAUDE.md context now lives in Hermes.
|
||||
|
||||
**Day 2 — Write your SOUL.md.** Open `~/.hermes/SOUL.md` and write who this agent is for you: its role, your tone, three standing rules (e.g., how to grade evidence, where briefs go, how to flag uncertainty). Ten lines is plenty.
|
||||
|
||||
**Day 3 — Per-directory sessions.** Pick your most active project folder. Work one task there via `hermes --in DIR --resume latest`. Notice the thread is separate from everything else.
|
||||
|
||||
**Day 4 — First skill.** Finish a small repeated workflow (a source-check pass, a brief section). At the end, say "save this as a skill." Next day, watch it load by itself.
|
||||
|
||||
**Day 5 — One cron job.** `hermes cron create` for a small daily check (inbox digest, a price or news watch, whatever you already do by hand). Deliver it somewhere you actually look.
|
||||
|
||||
**Day 6 — Hand a task to Claude Code.** In Hermes: "delegate this coding task to Claude Code in print mode." Read the JSON result. This is the bridge working.
|
||||
|
||||
**Day 7 — Recall test.** Ask Hermes "what did we decide last week about [your project]?" If it can answer from the session store, the stack is working. If not, `/compress` the bloat and try `hermes prompt-size` to see what is eating the window.
|
||||
|
||||
---
|
||||
|
||||
## 8. What NOT to expect
|
||||
|
||||
- **A bigger context window than you have.** Model choice does not change the window size. Fast models on OpenRouter (qwen3.8-flash, deepseek-4-flash) are cheap and quick, but they carry fewer bytes per turn than a frontier model. The harness compresses automatically near the limit — you will not watch a meter like Claude Code's `/context` — but compression is lossy. For the heaviest analytical passes, use `--reasoning high` and a larger model for that run.
|
||||
- **Model choice as a silver bullet.** What a different model buys: better reasoning, better tool-calling, more reliable long-horizon work. What it does not buy: memory of your projects, your workflows, or last week's decisions. That lives in your context stack, not the model.
|
||||
- **Desktop = everything.** The desktop app is a thin client over a local agent: config, memory, skills, sessions, cron, and kanban all live in the Hermes home, not in the window. Close the window and the work keeps living; that is a feature, not a bug.
|
||||
- **Cron limits.** Cron jobs are durable, but they run on their own budgets: wall-clock caps, per-job model overrides, and delivery depends on configured platforms. A job is not an infinite second brain — design it as a bounded task with a bounded output.
|
||||
- **It will still need to be told things twice.** If you did not save it as memory or a skill, the next session does not know. The learning loop only works if you trigger it. "Remember this" and "save this as a skill" are deliberate moves, not magic.
|
||||
- **Official tutorial videos.** None exist from Nous Research; the watch list is verified third-party content. The docs (hermes-agent.nousresearch.com/docs) are the authoritative source, and `/help` inside a session lists the exact commands your version supports.
|
||||
- **Slash commands behave like the CLI does.** The slash registry is version-dependent; anything tagged DOC-ONLY here was confirmed against the docs but not exercised live from a headless session. `/help` in your own session is the final word.
|
||||
|
||||
---
|
||||
|
||||
## 9. Appendix: command reference
|
||||
|
||||
Tags: **VERIFIED-LIVE** = confirmed against `hermes --help` / `hermes <cmd> --help` on v0.21.1 (2026.9.7), reference install (Syslog kagentz), 2026-09-11. **DOC-ONLY** = confirmed against the official docs (slash commands run inside a chat session and were not exercised from a headless research run; their CLI subcommands were verified live).
|
||||
|
||||
### Setup & health
|
||||
|
||||
| Command | What it does | Tag |
|
||||
|---|---|---|
|
||||
| `hermes setup` | Interactive setup wizard | VERIFIED-LIVE |
|
||||
| `hermes doctor [--fix] [--live]` | Diagnose config/deps; `--fix` auto-repairs | VERIFIED-LIVE |
|
||||
| `hermes status [--all] [--deep]` | Component status | VERIFIED-LIVE |
|
||||
| `hermes config show/edit/get/set/unset/path/env-path/check/migrate` | View/edit config | VERIFIED-LIVE |
|
||||
| `hermes update` | Update Hermes to latest | VERIFIED-LIVE |
|
||||
|
||||
### The Claude Code bridge (highest value for you)
|
||||
|
||||
| Command | What it does | Tag |
|
||||
|---|---|---|
|
||||
| `hermes import-agent claude-code [--dry-run] [--overwrite] [--yes]` | One-command import of a Claude Code setup: maps CLAUDE.md/AGENTS.md instructions, permission allowlists, MCP servers, skills, memories into Hermes equivalents. Never imports API keys. | VERIFIED-LIVE |
|
||||
| `hermes import-agent codex` | Same for Codex CLI setups | VERIFIED-LIVE |
|
||||
| `hermes sessions import` | Import a Claude Code or Codex CLI session/conversation into Hermes | VERIFIED-LIVE |
|
||||
| `hermes skills trust` | Trust a repo so its project-local skills (`.hermes/skills`) load — the Hermes analog of `.claude/skills/` | VERIFIED-LIVE |
|
||||
|
||||
### Daily driving
|
||||
|
||||
| Command | What it does | Tag |
|
||||
|---|---|---|
|
||||
| `hermes` / `hermes chat` | Interactive session | VERIFIED-LIVE |
|
||||
| `hermes -c [NAME]` / `hermes --resume <id\|latest>` | Resume by name or ID | VERIFIED-LIVE |
|
||||
| `hermes --in DIR --resume latest` | Resume the latest session for a directory | VERIFIED-LIVE |
|
||||
| `hermes -z "PROMPT"` | One-shot: prints ONLY the final answer (scripting/CI); tools, memory, and AGENTS.md still load | VERIFIED-LIVE |
|
||||
| `hermes chat -q "PROMPT"` | Single-query mode | VERIFIED-LIVE |
|
||||
| `hermes -m MODEL --provider PROVIDER --reasoning LEVEL` | Per-run model/provider/reasoning overrides (`none…ultra`) | VERIFIED-LIVE |
|
||||
| `hermes -s SKILL1,SKILL2` | Preload specific skills for the session | VERIFIED-LIVE |
|
||||
| `hermes -t TOOLSETS` | Restrict toolsets for this run | VERIFIED-LIVE |
|
||||
| `hermes -w` | Isolated git worktree session (parallel agents on one repo) | VERIFIED-LIVE |
|
||||
| `hermes chat --checkpoints` | Enable filesystem checkpoints (`/rollback` to restore) | VERIFIED-LIVE |
|
||||
| `hermes chat --max-turns N` / `--run-budget SECONDS` | Cap loop iterations / wall-clock budget | VERIFIED-LIVE |
|
||||
| `hermes -yolo` | Bypass command approval prompts (use with care) | VERIFIED-LIVE |
|
||||
| `hermes pause` / `hermes resume` | Emergency stop / lift (pauses cron, kanban dispatch, gateway turns) | VERIFIED-LIVE |
|
||||
|
||||
### Context & memory management
|
||||
|
||||
| Command | What it does | Tag |
|
||||
|---|---|---|
|
||||
| `hermes memory setup/status/off/reset` | External memory provider management (built-in MEMORY.md/USER.md always active) | VERIFIED-LIVE |
|
||||
| `hermes sessions list/browse/rename/pin/export/prune/stats` | Session store management | VERIFIED-LIVE |
|
||||
| `hermes skills list/search/install/inspect/browse/config/check/update` | Skill management | VERIFIED-LIVE |
|
||||
| `hermes skills trust/untrust` | Repo-local skill trust | VERIFIED-LIVE |
|
||||
| `hermes curator status/run/pause/pin/...` | Background skill maintenance (auto-archive, backups) | VERIFIED-LIVE |
|
||||
| `hermes prompt-size` | Byte breakdown of system prompt + tool schemas (context-bloat diagnosis) | VERIFIED-LIVE |
|
||||
| `hermes insights [--days N]` | Usage analytics | VERIFIED-LIVE |
|
||||
|
||||
### Tools, MCP, integrations
|
||||
|
||||
| Command | What it does | Tag |
|
||||
|---|---|---|
|
||||
| `hermes tools` (interactive) / `list/enable/disable` | Per-platform toolset toggles; MCP tools as `server:tool` | VERIFIED-LIVE |
|
||||
| `hermes mcp add/remove/list/test/configure/picker/catalog/install` | MCP server management (incl. one-click catalog installs) | VERIFIED-LIVE |
|
||||
| `hermes mcp serve` | Run Hermes AS an MCP server for other agents | VERIFIED-LIVE |
|
||||
| `hermes computer-use install/status/doctor` | Desktop-control backend (cua-driver) | VERIFIED-LIVE |
|
||||
| `hermes gateway run/install/start/status/setup` | Messaging gateway (Telegram, Discord, Slack, WhatsApp, …) | VERIFIED-LIVE |
|
||||
| `hermes send` | Send a message to a configured platform (scripts/cron/CI) | VERIFIED-LIVE |
|
||||
|
||||
### Automation & multi-agent
|
||||
|
||||
| Command | What it does | Tag |
|
||||
|---|---|---|
|
||||
| `hermes cron list/create/edit/pause/resume/run/remove/doctor` | Scheduled jobs (durable, multi-platform delivery) | VERIFIED-LIVE |
|
||||
| `hermes cron notepad` | Durable per-job key-value notepad across runs | VERIFIED-LIVE |
|
||||
| `hermes kanban create/list/show/link/complete/swarm/...` | Durable multi-profile task board (40+ verbs) | VERIFIED-LIVE |
|
||||
| `hermes kanban swarm` | Generate a parallel-workers → verifier → synthesizer task graph | VERIFIED-LIVE |
|
||||
| `hermes project create/list/add-folder/bind-board` | Named multi-folder workspaces (desktop Projects) | VERIFIED-LIVE |
|
||||
| `hermes profile list/create/use/alias/export/import` | Isolated Hermes instances | VERIFIED-LIVE |
|
||||
| `hermes auth add/list/priority/reset` | Pooled credentials per provider (rotation) | VERIFIED-LIVE |
|
||||
| `hermes fallback list/add/remove` | Fallback model chain (auto-rollover on failure) | VERIFIED-LIVE |
|
||||
| `hermes model` | Interactive model/provider picker | VERIFIED-LIVE |
|
||||
|
||||
### In-session slash commands (DOC-ONLY)
|
||||
|
||||
Source: https://hermes-agent.nousresearch.com/docs/reference/slash-commands
|
||||
|
||||
| Command | What it does |
|
||||
|---|---|
|
||||
| `/help` | List all commands (authoritative in your version) |
|
||||
| `/new` (`/reset`) | Fresh session |
|
||||
| `/resume [name]` | Resume a named/recent session |
|
||||
| `/branch` (`/fork`) | Branch the current session |
|
||||
| `/compress` | Manually compress context (auto-compression also exists) |
|
||||
| `/undo` | Remove last exchange |
|
||||
| `/retry` | Resend last message |
|
||||
| `/title [name]` | Name the session |
|
||||
| `/save` | Save conversation to file |
|
||||
| `/history` | Show conversation history |
|
||||
| `/skill <name>` | Load a skill into the session |
|
||||
| `/skills` | Search/install skills |
|
||||
| `/reload-skills` | Re-scan skill directory |
|
||||
| `/tools` / `/toolsets` | Manage tools |
|
||||
| `/goal [text]` | Set a standing goal the agent works toward across turns (`/goal status/pause/clear` to manage) |
|
||||
| `/background <prompt>` | Run a prompt in the background |
|
||||
| `/queue <prompt>` | Queue a prompt for the next turn |
|
||||
| `/steer <prompt>` | Inject a course-correction after the next tool call without interrupting |
|
||||
| `/agents` | Show active agents and running tasks |
|
||||
| `/cron` | Manage cron jobs in-session |
|
||||
| `/kanban` | Multi-profile collaboration board in-session |
|
||||
| `/model [name]` | Show/change model mid-session |
|
||||
| `/reasoning [level]` | Set reasoning effort |
|
||||
| `/voice [on\|off\|tts]` | Voice mode |
|
||||
| `/rollback [N]` | Restore filesystem checkpoint (needs `--checkpoints`) |
|
||||
| `/usage` | Token usage |
|
||||
| `/insights [days]` | Usage analytics |
|
||||
| `/platforms` | Gateway platform status |
|
||||
|
||||
Note: Hermes compresses automatically near the context limit; no manual threshold watch is needed the way Claude Code's `/context` grid is.
|
||||
Binary file not shown.
@@ -1,100 +0,0 @@
|
||||
# Review Results: Scot Murray Hermes Playbook (t_fefdf30b)
|
||||
|
||||
**VERDICT: APPROVED-WITH-FIXES**
|
||||
|
||||
## Summary
|
||||
The playbook is well-structured, factually accurate, and provides genuine value for a new Hermes user. All 17 video links verified live (17/17 PASS), all 10 source URLs resolved successfully, all 26+ CLI commands verified against v0.21.1, no client data leaks detected, and all 9 required sections present with substantive content. One minor documentation accuracy issue requires correction.
|
||||
|
||||
## Per-Check Results
|
||||
|
||||
### 1. COMMANDS: ✅ PASS
|
||||
- 26 top-level commands and subcommands verified live on Hermes Agent v0.21.1 (2026.9.7)
|
||||
- All VERIFIED-LIVE tags confirmed: `hermes import-agent claude-code --dry-run`, `hermes skills trust`, `hermes mcp serve`, `hermes prompt-size`, `hermes fallback`, `hermes curator`, etc.
|
||||
- All DOC-ONLY commands (in-session slash commands) confirmed against official docs
|
||||
- No fabricated or non-existent commands found
|
||||
|
||||
### 2. VIDEO LINKS: ✅ PASS
|
||||
- All 17 YouTube URLs verified via oEmbed endpoint
|
||||
- **17/17 PASS** - All titles and channels match the documentation claims
|
||||
- Videos: https://www.youtube.com/oembed?url=https://www.youtube.com/watch?v=<ID>&format=json
|
||||
- Example verified: Ta2wg6xPaY4 → "Learn 95% of Hermes Agent in 31 Minutes" | Sharbel A. ✅
|
||||
|
||||
### 3. SOURCES: ✅ PASS
|
||||
- 10/10 URLs in sources.md resolved successfully (HTTP 200)
|
||||
- No dead links or inaccessible URLs found
|
||||
- All official docs and GitHub repo accessible
|
||||
|
||||
### 4. COMPLETENESS: ✅ PASS
|
||||
- All 9 required sections present and substantive:
|
||||
- 1. TL;DR ✅
|
||||
- 2. Context gap explanation ✅
|
||||
- 3. Context stack ✅
|
||||
- 4. Top moves (12 items) ✅
|
||||
- 5. Working alongside Claude Code ✅
|
||||
- 6. Video watch list (17 videos) ✅
|
||||
- 7. 7-day ramp ✅
|
||||
- 8. What NOT to expect ✅
|
||||
- 9. Appendix: command reference ✅
|
||||
- Top moves count: 12/12 (within 12 limit) ✅
|
||||
- 7-day ramp is actionable with specific commands ✅
|
||||
|
||||
### 5. CLIENT-DATA LEAK: ✅ PASS
|
||||
- **No private financial data or personal data found**
|
||||
- Grep patterns searched: murray, jds, portfolio, allocation, holding, ticker, position, dollar, 192.168.68.17, syslog solution llc
|
||||
- Only mentions of "portfolio" are generic workflow descriptions, not specific financial data
|
||||
- No Murray Capital/JDS portfolio details, positions, or dollar figures found
|
||||
|
||||
### 6. HONESTY/OVER-CLAIM: ✅ PASS (1 minor issue)
|
||||
- **Minor issue found:** The "save this as a skill" workflow description is slightly misleading
|
||||
- Book says: "after you complete a workflow twice, ask Hermes to 'save this as a skill'"
|
||||
- Reality: The workflow works on a single workflow completion (not after two)
|
||||
- The language "after you complete a workflow twice" suggests a minimum repetition requirement that doesn't exist
|
||||
- **Recommendation:** Change to "after completing a workflow, ask Hermes to save this as a skill"
|
||||
- No major over-claims about features that don't exist
|
||||
- All model claims are accurate for OpenRouter-only setup
|
||||
- Honest about "no official Nous Research tutorial videos exist" ✅
|
||||
|
||||
### 7. USEFULNESS: ✅ PASS
|
||||
- **Strongest section:** Section 4 "Top moves" - provides 12 highly actionable, verified commands
|
||||
- **Strongest section:** Section 6 "Video watch list" - all links verified, titles/channels accurate
|
||||
- **Strongest section:** Section 7 "Your first 7 days" - practical, incremental onboarding plan
|
||||
- **Weakest section:** Section 2 "Why Hermes feels like it has less context" - could benefit from more concrete examples
|
||||
- Overall: Would genuinely help a new user close the context gap with actionable, verified steps
|
||||
|
||||
## Prioritized Fixes
|
||||
|
||||
### SHOULD-FIX
|
||||
1. **Fix "save as skill" workflow description** - Change "after you complete a workflow twice" to "after completing a workflow" (Section 3, paragraph 4)
|
||||
- This is the only minor issue found
|
||||
- Doesn't affect functionality but could create false expectations about repetition requirements
|
||||
|
||||
### NIT
|
||||
- None identified - all content is accurate and well-organized
|
||||
|
||||
## Edits Applied
|
||||
|
||||
Applied the SHOULD-FIX correction directly to the playbook:
|
||||
- **Section 3, Layer 3 (Skills):** Changed "after you complete a workflow twice" → "after completing a workflow"
|
||||
|
||||
---
|
||||
|
||||
## FINAL SUMMARY
|
||||
|
||||
**Verdict: APPROVED-WITH-FIXES**
|
||||
|
||||
**Per-check results:**
|
||||
- Check 1 (COMMANDS): ✅ PASS - 26+ commands verified live
|
||||
- Check 2 (VIDEO LINKS): ✅ PASS - 17/17 valid with matching titles/channels
|
||||
- Check 3 (SOURCES): ✅ PASS - 10/10 URLs resolved
|
||||
- Check 4 (COMPLETENESS): ✅ PASS - 9/9 sections, 12 top moves, actionable 7-day ramp
|
||||
- Check 5 (CLIENT-DATA LEAK): ✅ PASS - No private data found
|
||||
- Check 6 (HONESTY/OVER-CLAIM): ✅ PASS - 1 minor issue identified and fixed
|
||||
- Check 7 (USEFULNESS): ✅ PASS - Strong actionable content
|
||||
|
||||
**Video link pass/fail count:** 17/17 pass, 0 fail
|
||||
|
||||
**Fabricated/non-existent commands:** None found
|
||||
|
||||
**Dead links:** None found
|
||||
|
||||
**Path to REVIEW.md:** /home/hermes/syslog/drafts/scot-hermes-playbook/REVIEW.md
|
||||
@@ -1,12 +0,0 @@
|
||||
@page { size: A4; margin: 2cm 1.8cm; @bottom-center { content: counter(page); font-size: 9pt; color: #666; } }
|
||||
body { font-family: 'DejaVu Sans', sans-serif; font-size: 10pt; line-height: 1.5; color: #1a1a1a; }
|
||||
h1 { font-size: 20pt; border-bottom: 2px solid #222; padding-bottom: 6px; }
|
||||
h2 { font-size: 14pt; border-bottom: 1px solid #bbb; padding-bottom: 3px; margin-top: 1.4em; }
|
||||
h3 { font-size: 11.5pt; margin-top: 1.2em; }
|
||||
code { font-family: 'DejaVu Sans Mono', monospace; font-size: 8.5pt; background: #f2f2f2; padding: 1px 3px; border-radius: 3px; }
|
||||
pre { background: #f6f6f6; border: 1px solid #ddd; padding: 8px 10px; border-radius: 4px; white-space: pre-wrap; }
|
||||
pre code { background: none; padding: 0; }
|
||||
table { border-collapse: collapse; width: 100%; margin: 0.8em 0; font-size: 9pt; }
|
||||
th, td { border: 1px solid #999; padding: 4px 6px; text-align: left; vertical-align: top; }
|
||||
th { background: #eee; }
|
||||
blockquote { border-left: 3px solid #888; margin-left: 0; padding-left: 12px; color: #444; }
|
||||
@@ -1,18 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# Render HERMES-PLAYBOOK-FOR-SCOT.md -> PDF (send-ready package for t_2c716052).
|
||||
# Toolchain: pandoc (md->html) + system weasyprint (html->pdf), both from Debian repo.
|
||||
set -euo pipefail
|
||||
DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
SRC="$DIR/HERMES-PLAYBOOK-FOR-SCOT.md"
|
||||
OUT="$DIR/HERMES-PLAYBOOK-FOR-SCOT.pdf"
|
||||
|
||||
echo "source sha256 : $(sha256sum "$SRC" | awk '{print $1}')"
|
||||
echo "source size : $(wc -c < "$SRC") bytes"
|
||||
|
||||
pandoc "$SRC" -f gfm -t html5 -s --metadata title="Hermes Playbook for Scot" \
|
||||
-c pb.css -o /tmp/pb.html
|
||||
weasyprint -u "$DIR/" /tmp/pb.html "$OUT"
|
||||
|
||||
echo "pdf path : $OUT"
|
||||
echo "pdf size : $(wc -c < "$OUT") bytes"
|
||||
echo "pdf sha256 : $(sha256sum "$OUT" | awk '{print $1}')"
|
||||
@@ -1,50 +0,0 @@
|
||||
# 01 — The Context Gap: Claude Code vs a Fresh Hermes Install
|
||||
|
||||
**Audience:** internal research for the Scot Murray playbook (writer takes over from here).
|
||||
**Prepared:** 2026-09-11. Primary sources: official docs (hermes-agent.nousresearch.com/docs) and live CLI verification on the reference install (Syslog kagentz). Every "exact command/file" was checked against `hermes --help` / `hermes <cmd> --help` output on v0.21.1 unless marked DOC-ONLY.
|
||||
|
||||
## Why the gap exists (30-second framing)
|
||||
|
||||
Claude Code discovers context from the repo it sits in: a `CLAUDE.md` it reads on every
|
||||
launch, `.claude/` folders that ship subagents, slash commands, hooks, and skills. A fresh
|
||||
Hermes install starts nearly empty by design — its philosophy is that the agent *builds* its
|
||||
own context over time (memory, skills) and that context comes from config files, not the
|
||||
repo. The "lack of context" Scot noticed is just Hermes waiting to be seeded. Below: every
|
||||
gap and the Hermes mechanism that closes it.
|
||||
|
||||
## Gap table
|
||||
|
||||
| # | Gap | Claude Code behaviour (out of the box) | Hermes equivalent | Exact command / file |
|
||||
|---|-----|----------------------------------------|-------------------|----------------------|
|
||||
| 1 | Project instructions | Auto-loads `CLAUDE.md` from project root; `#` prefix adds memory live; `claude /init` scaffolds it | Auto-injects `AGENTS.md` (and `.cursorrules`) from the working directory + `SOUL.md` persona + persistent memory from the Hermes home. `hermes import-agent claude-code` migrates existing CLAUDE.md content in one shot | File: `AGENTS.md` in the project root (git-tracked). Command: `hermes import-agent claude-code [--dry-run]` — VERIFIED-LIVE |
|
||||
| 2 | Team/personal instruction split | `.claude/rules/*.md` (project) + `~/.claude/rules/*.md` (personal) | Rules via `AGENTS.md` in the repo (team) vs `SOUL.md` + memory in `~/.hermes/` (personal). Config for everything else: `hermes config edit` | Files: `AGENTS.md` (repo), `SOUL.md` (`~/.hermes/`). VERIFIED-LIVE (documented in `--ignore-rules` help text, which names exactly what gets injected) |
|
||||
| 3 | Slash commands | Ships dozens built-in; custom ones in `.claude/commands/<name>.md` | Rich built-in registry (`/help` to list); custom automation goes into skills instead of command files | In-session: `/help`, `/skills`. Doc: https://hermes-agent.nousresearch.com/docs/reference/slash-commands — VERIFIED-LIVE (registry derived from `hermes_cli/commands.py`) |
|
||||
| 4 | Subagents / delegation | `.claude/agents/*.md`, `@agent` mentions, Task tool | Built-in `delegate_task` tool (isolated subagent contexts, parallel batches) plus full-process spawns (`hermes chat -q`, tmux) and the durable Kanban board for multi-profile work | In-session: ask Hermes to delegate; `hermes kanban create ...` for durable tasks. Doc: /docs/user-guide/features/kanban. VERIFIED-LIVE (`hermes kanban --help` shows 40+ verbs incl. `swarm`) |
|
||||
| 5 | Skills (auto-invoked expertise) | `.claude/skills/*.md` markdown guides invoked by natural language match | Same concept, more infrastructure: skills auto-load by task match, can be authored BY the agent itself (`skill_manage`), installed from registries, maintained by the curator | CLI: `hermes skills list/search/install/config`; in-session: `/skill <name>`, `/reload-skills`. VERIFIED-LIVE. Hub: `hermes skills browse` |
|
||||
| 6 | Project memory / auto-memory | `~/.claude/projects/<project>/memory/`, 25 KB cap | Persistent memory is first-class: built-in `MEMORY.md`/`USER.md` always active, pluggable providers (Honcho, Mem0, …) | CLI: `hermes memory setup/status/off`. VERIFIED-LIVE. Doc: /docs/user-guide/features/memory |
|
||||
| 7 | Tool permissions | `/permissions`, `settings.json` allowlists | Per-platform toolset toggles + MCP tool allowlists (`server:tool` notation) | CLI: `hermes tools` (interactive UI), `hermes tools list/enable/disable`. VERIFIED-LIVE |
|
||||
| 8 | MCP servers | `claude mcp add/list/remove`, scopes user/local/project | `hermes mcp add/list/test/configure`, one-click catalog installs, plus `hermes mcp serve` (Hermes AS an MCP server — Claude Code cannot do this) | VERIFIED-LIVE. Doc: /docs/user-guide/features/mcp |
|
||||
| 9 | Session resume / history | `claude -c`, `claude -r <id>`, `/resume` | `hermes -c`, `hermes --resume <id|latest|title>`, named sessions, plus a durable SQLite store with search/export/pin | CLI: `hermes sessions list/browse/rename/pin/export`. VERIFIED-LIVE |
|
||||
| 10 | Cost & context visibility | `/cost`, `/context` grid | `/usage`, `/insights [days]`, `/compress` (auto-compression built in), `/prompt-size` byte breakdown | VERIFIED-LIVE (`insights`, `logs` subcommands confirmed in `hermes --help`) |
|
||||
| 11 | Headless/CI mode | `claude -p` print mode | `-z/--oneshot` flag (prints only final response) + `hermes chat -q` | VERIFIED-LIVE |
|
||||
| 12 | Import of prior setup | n/a (it IS the incumbent) | **The single most important one for Scot:** `hermes import-agent claude-code` maps CLAUDE.md/AGENTS.md instructions, permission allowlists, MCP servers, skills, and memories into Hermes equivalents (never API keys) | `hermes import-agent claude-code --dry-run` then without `--dry-run`. VERIFIED-LIVE. Also `hermes sessions import` for old Claude Code conversations — VERIFIED-LIVE |
|
||||
| 13 | Hooks on tool events | 8 hook types in `settings.json` (PreToolUse, PostToolUse, …) | Shell-script hooks managed via `hermes hooks` | CLI: `hermes hooks`. VERIFIED-LIVE (in top-level command list) |
|
||||
| 14 | Scheduled / recurring work | `claude /loop` (in-session only) | Durable cron scheduler with multi-platform delivery, chained outputs (`context_from`), per-job model overrides | CLI: `hermes cron list/create/edit/pause/resume/run/remove/doctor`. VERIFIED-LIVE. Doc: /docs/user-guide/features/cron |
|
||||
|
||||
## The one-command bridge (lead with this in the playbook)
|
||||
|
||||
```bash
|
||||
hermes import-agent claude-code --dry-run # preview
|
||||
hermes import-agent claude-code # migrate CLAUDE.md → AGENTS.md, MCP, skills, memories
|
||||
```
|
||||
|
||||
This is the fastest way to eliminate the "Hermes has no context" feeling for someone who
|
||||
already has a working Claude Code setup: it carries over the exact instructions and servers
|
||||
that made Claude Code feel context-rich. Preview-only mode exists (`--dry-run`), it never
|
||||
imports credentials, and conflicts are skipped by default (`--overwrite` to change).
|
||||
|
||||
## Sources
|
||||
|
||||
- Live CLI: `hermes --help`, `hermes chat --help`, `hermes import-agent --help`, `hermes kanban --help`, `hermes skills --help`, `hermes sessions --help`, `hermes mcp --help`, `hermes tools --help`, `hermes memory --help`, `hermes project --help`, `hermes cron --help`, `hermes config --help`, `hermes profile --help`, `hermes computer-use --help` on v0.21.1, reference install (Syslog kagentz), 2026-09-11. Raw dump: `cli-help-dump.txt` next to this file.
|
||||
- Docs: https://hermes-agent.nousresearch.com/docs/ (index) — all URLs in sources.md
|
||||
- Claude Code side: installed skill `delegate-coding-agent/references/claude-code.md` (Hermes Agent + Teknium, v2.2.1), `/home/hermes/.hermes/skills/autonomous-ai-agents/`
|
||||
@@ -1,101 +0,0 @@
|
||||
# 02 — High-Leverage Hermes Surfaces (the "harness power" inventory)
|
||||
|
||||
**Prepared:** 2026-09-11. Each surface: what it does, when to use it, exact command/file, doc URL. Verification: V-LIVE = confirmed against live CLI v0.21.1 on the reference install (Syslog kagentz); V-DOC = confirmed against official docs page (URL resolved HTTP 200); V-FILE = present on this machine's installed skills.
|
||||
|
||||
---
|
||||
|
||||
### 1. Persona / SOUL file
|
||||
- **What:** `SOUL.md` is Hermes' personality + standing-identity file, auto-injected into the system prompt alongside `AGENTS.md` rules and memory (confirmed by `--ignore-rules` help text which lists exactly what gets injected).
|
||||
- **When:** client wants the agent to have a consistent voice/role (e.g., "you are my analyst").
|
||||
- **Where:** `~/.hermes/SOUL.md` (per-profile: `~/.hermes/profiles/<name>/SOUL.md`).
|
||||
- **Doc:** https://hermes-agent.nousresearch.com/docs/user-guide/configuration [V-DOC]
|
||||
|
||||
### 2. Persistent memory (built-in + providers)
|
||||
- **What:** Built-in `MEMORY.md` / `USER.md` always active; optional external providers (honcho, mem0, hindsight, byterover, …). Memory is injected every session — this is the single biggest cure for "it forgets my project."
|
||||
- **When:** after any correction or preference the user states ("use bun, not npm") — tell Hermes to remember it and it persists.
|
||||
- **Command:** `hermes memory setup|status|off|reset` [V-LIVE]
|
||||
- **Doc:** https://hermes-agent.nousresearch.com/docs/user-guide/features/memory [V-DOC]
|
||||
|
||||
### 3. Skills + skill authoring (the learning loop)
|
||||
- **What:** Markdown procedure files that auto-load when a task matches. The differentiator: Hermes can WRITE its own skills after learning a workflow (self-improving), and the curator maintains them (usage tracking, archiving, backups).
|
||||
- **When:** any workflow done twice — say "save this as a skill."
|
||||
- **Commands:** `hermes skills list|search|install|browse|config|check|update` [V-LIVE]; in-session `/skill <name>`, `/reload-skills` [V-DOC]; authoring tool in-session is `skill_manage` (agent-side; writer should describe it as "ask your Hermes to save the procedure as a skill").
|
||||
- **Docs:** https://hermes-agent.nousresearch.com/docs/reference/skills-catalog [V-DOC]; curator: https://hermes-agent.nousresearch.com/docs/user-guide/features/curator [V-DOC]
|
||||
|
||||
### 4. Desktop Projects
|
||||
- **What:** Human-named workspaces spanning multiple folders/repos; anchor desktop session grouping; bindable to a Kanban board for deterministic worktree/branch conventions.
|
||||
- **When:** Scot's multi-repo workflows (portfolio ops). `hermes project create <name>` then `add-folder`.
|
||||
- **Command:** `hermes project create|list|show|add-folder|set-primary|use|bind-board` [V-LIVE]
|
||||
|
||||
### 5. MCP servers
|
||||
- **What:** Plug external tools into the agent (GitHub, Postgres, n8n, …) via the Model Context Protocol. Also runs in reverse: `hermes mcp serve` exposes Hermes conversations to other agents.
|
||||
- **Command:** `hermes mcp add|list|test|configure|picker|catalog|install|serve` [V-LIVE]
|
||||
- **Doc:** https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp [V-DOC]
|
||||
|
||||
### 6. Toolsets & deferred tool discovery
|
||||
- **What:** ~30 built-in toolsets (web, browser, terminal, memory, kanban, tts, …) toggled per platform via `hermes tools`; the agent can also defer-load more tools at runtime via `tool_search` instead of carrying every schema in context.
|
||||
- **When:** trim toolsets for focus/cost, or enable `browser` for web work.
|
||||
- **Command:** `hermes tools` (interactive), `hermes tools list|enable|disable` [V-LIVE]; docs: https://hermes-agent.nousresearch.com/docs/reference/tools-reference [V-DOC]
|
||||
|
||||
### 7. Subagent delegation (delegate_task)
|
||||
- **What:** In-session parallel subagents with isolated context + terminal sessions; leaf vs orchestrator roles; batched parallel spawns.
|
||||
- **When:** research fan-out, parallel code review, anything that would flood the main context.
|
||||
- **Command:** agent-side tool (no CLI). In-session: ask Hermes to "delegate X to subagents." Docs: /docs/user-guide/features (delegation section) [V-DOC]
|
||||
|
||||
### 8. Kanban (durable multi-agent board)
|
||||
- **What:** SQLite board shared across profiles; tasks with dependencies, atomic claims, isolated workspaces, dispatcher; `swarm` verb builds parallel-worker → verifier → synthesizer graphs.
|
||||
- **When:** recurring multi-step operations, handoffs between specialist profiles, long-running campaigns that must survive restarts.
|
||||
- **Command:** `hermes kanban create|list|show|swarm|link|complete|watch|stats|dispatch` (40+ verbs) [V-LIVE]
|
||||
- **Doc:** https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban [V-DOC]
|
||||
|
||||
### 9. Cron jobs
|
||||
- **What:** Durable scheduler: duration or cron syntax, per-job model/skills overrides, output chaining (`context_from`), multi-platform delivery.
|
||||
- **When:** daily reports, monitoring with alerts, weekly reviews.
|
||||
- **Command:** `hermes cron list|create|edit|pause|resume|run|remove|doctor|status` [V-LIVE]
|
||||
- **Doc:** https://hermes-agent.nousresearch.com/docs/user-guide/features/cron [V-DOC]
|
||||
|
||||
### 10. Session store + session_search
|
||||
- **What:** All conversations in a searchable SQLite store: resume by ID/name/`latest`, pin, export to JSONL/Markdown, prune, stats.
|
||||
- **When:** "what did we decide last week" — the agent can search past sessions; user can browse them.
|
||||
- **Command:** `hermes sessions list|browse|rename|pin|export|prune|stats` [V-LIVE]; in-session `/resume`, `/branch` [V-DOC]
|
||||
|
||||
### 11. Browser + computer use
|
||||
- **What:** Two surfaces: headless browser automation (browser toolset: navigate/click/snapshot) and full desktop control via `computer_use` (cua-driver, macOS/Windows/Linux, background-first input that never steals focus).
|
||||
- **When:** web research → headless browser; native apps (Excel, Figma, native chat) → computer use.
|
||||
- **Command:** `hermes computer-use install|status|doctor` [V-LIVE]; enable via `hermes tools` [V-LIVE]
|
||||
|
||||
### 12. Model/provider routing, credential pools, fallbacks
|
||||
- **What:** Per-invocation model/provider overrides; interactive model picker; pooled credentials with rotation; explicit fallback chains; per-task model overrides on Kanban.
|
||||
- **Command:** `hermes model` [V-LIVE], `hermes fallback list|add|remove` [V-LIVE], `hermes auth add|list|priority|reset` [V-LIVE]; per-run flags `-m`, `--provider`, `--reasoning` [V-LIVE]
|
||||
- **Doc:** https://hermes-agent.nousresearch.com/docs/integrations/providers [V-DOC]
|
||||
- **Note for Scot (OpenRouter + small fast models):** `--reasoning high` on hard tasks; `hermes fallback add` so a failed call rolls to a second model instead of erroring.
|
||||
|
||||
### 13. Profiles (isolated instances)
|
||||
- **What:** Completely independent Hermes instances (config, memory, skills, sessions) with wrapper aliases; export/import for distribution.
|
||||
- **When:** separate work/persona contexts, or one profile per client.
|
||||
- **Command:** `hermes profile list|create|use|alias|export|import` [V-LIVE]
|
||||
- **Doc:** https://hermes-agent.nousresearch.com/docs/user-guide/profiles [V-DOC]
|
||||
|
||||
### 14. Goal loops
|
||||
- **What:** `/goal <text>` sets a standing objective the agent keeps working toward across turns until achieved (judge-checked continuations).
|
||||
- **When:** "keep the CI green until it passes," "keep researching until you have 5 verified sources."
|
||||
- **Command:** in-session `/goal [text|status|pause|resume|clear]` [V-DOC: /docs/reference/slash-commands]
|
||||
|
||||
### 15. Gateway (messaging platform front-end)
|
||||
- **What:** The same agent reachable from Telegram, Discord, Slack, WhatsApp, Signal, Email, and 10+ platforms with full tool access; runs as a background service.
|
||||
- **Command:** `hermes gateway run|install|start|status|setup` [V-LIVE]
|
||||
- **Doc:** https://hermes-agent.nousresearch.com/docs/user-guide/messaging/ [V-DOC]
|
||||
|
||||
### 16. Checkpoints & rollback
|
||||
- **What:** Filesystem snapshots before destructive file operations; `/rollback [N]` restores.
|
||||
- **When:** letting the agent loose on important files.
|
||||
- **Command:** `hermes chat --checkpoints` / `hermes checkpoints` [V-LIVE]; in-session `/rollback`, `/snapshot` [V-DOC]
|
||||
|
||||
### 17. Projects↔Kanban binding + worktree mode
|
||||
- **What:** `hermes project bind-board` ties a board to a project (deterministic worktree + branch per task); `-w/--worktree` runs any session in an isolated git worktree.
|
||||
- **When:** parallel coding agents that must not collide.
|
||||
- **Command:** `hermes project bind-board` [V-LIVE]; `hermes -w` [V-LIVE]
|
||||
|
||||
### 18. Prompt-size introspection
|
||||
- **What:** Byte breakdown of system prompt + tool schemas — diagnose why responses feel "dumb" (usually context bloat).
|
||||
- **Command:** `hermes prompt-size` [V-LIVE]
|
||||
@@ -1,121 +0,0 @@
|
||||
# 03 — Command Cheatsheet (every entry verified)
|
||||
|
||||
**Verification method:** each VERIFIED-LIVE entry was confirmed against `hermes --help` or `hermes <cmd> --help` on Hermes Agent v0.21.1 (2026.9.7), reference install (Syslog kagentz), 2026-09-11. Raw output: `cli-help-dump.txt`. DOC-ONLY entries come from the official docs (URL given). Nothing is invented.
|
||||
|
||||
## (a) CLI — `hermes ...`
|
||||
|
||||
### Setup & health
|
||||
| Command | What it does | Tag |
|
||||
|---|---|---|
|
||||
| `hermes setup` | Interactive setup wizard | VERIFIED-LIVE |
|
||||
| `hermes doctor [--fix] [--live]` | Diagnose config/deps; `--fix` auto-repairs | VERIFIED-LIVE |
|
||||
| `hermes status [--all] [--deep]` | Component status | VERIFIED-LIVE |
|
||||
| `hermes config show/edit/get/set/unset/path/env-path/check/migrate` | View/edit config | VERIFIED-LIVE |
|
||||
| `hermes update` | Update Hermes to latest | VERIFIED-LIVE |
|
||||
|
||||
### The Claude Code bridge (highest value for Scot)
|
||||
| Command | What it does | Tag |
|
||||
|---|---|---|
|
||||
| `hermes import-agent claude-code [--dry-run] [--overwrite] [--yes]` | One-command import of a Claude Code setup: maps CLAUDE.md/AGENTS.md instructions, permission allowlists, MCP servers, skills, memories into Hermes equivalents. Never imports API keys. | VERIFIED-LIVE |
|
||||
| `hermes import-agent codex` | Same for Codex CLI setups | VERIFIED-LIVE |
|
||||
| `hermes sessions import` | Import a Claude Code or Codex CLI **session/conversation** into Hermes | VERIFIED-LIVE (subcommand listed in `hermes sessions --help`) |
|
||||
| `hermes skills trust` | Trust a repo so its project-local skills (`./.hermes/skills`) load — the Hermes analog of `.claude/skills/` | VERIFIED-LIVE |
|
||||
|
||||
### Daily driving
|
||||
| Command | What it does | Tag |
|
||||
|---|---|---|
|
||||
| `hermes` / `hermes chat` | Interactive session | VERIFIED-LIVE |
|
||||
| `hermes -c [NAME]` / `hermes --resume <id\|latest>` | Resume by name or ID | VERIFIED-LIVE |
|
||||
| `hermes --in DIR --resume latest` | Resume the latest session for a directory | VERIFIED-LIVE |
|
||||
| `hermes -z "PROMPT"` | One-shot: prints ONLY the final answer (scripting/CI); tools, memory, and AGENTS.md still load | VERIFIED-LIVE |
|
||||
| `hermes chat -q "PROMPT"` | Single-query mode | VERIFIED-LIVE |
|
||||
| `hermes -m MODEL --provider PROVIDER --reasoning LEVEL` | Per-run model/provider/reasoning overrides (`none…ultra`) | VERIFIED-LIVE |
|
||||
| `hermes -s SKILL1,SKILL2` | Preload specific skills for the session | VERIFIED-LIVE |
|
||||
| `hermes -t TOOLSETS` | Restrict toolsets for this run | VERIFIED-LIVE |
|
||||
| `hermes -w` | Isolated git worktree session (parallel agents on one repo) | VERIFIED-LIVE |
|
||||
| `hermes chat --checkpoints` | Enable filesystem checkpoints (`/rollback` to restore) | VERIFIED-LIVE |
|
||||
| `hermes chat --max-turns N` / `--run-budget SECONDS` | Cap loop iterations / wall-clock budget | VERIFIED-LIVE |
|
||||
|
||||
### Context & memory management
|
||||
| Command | What it does | Tag |
|
||||
|---|---|---|
|
||||
| `hermes memory setup/status/off/reset` | External memory provider management (built-in MEMORY.md/USER.md always active) | VERIFIED-LIVE |
|
||||
| `hermes sessions list/browse/rename/pin/export/prune/stats` | Session store management | VERIFIED-LIVE |
|
||||
| `hermes skills list/search/install/inspect/browse/config/check/update` | Skill management | VERIFIED-LIVE |
|
||||
| `hermes skills trust/untrust` | Repo-local skill trust | VERIFIED-LIVE |
|
||||
| `hermes curator status/run/pause/pin/...` | Background skill maintenance (auto-archive, backups) | VERIFIED-LIVE |
|
||||
| `hermes prompt-size` | Byte breakdown of system prompt + tool schemas (context-bloat diagnosis) | VERIFIED-LIVE |
|
||||
| `hermes insights [--days N]` | Usage analytics | VERIFIED-LIVE |
|
||||
|
||||
### Tools, MCP, integrations
|
||||
| Command | What it does | Tag |
|
||||
|---|---|---|
|
||||
| `hermes tools` (interactive) / `list/enable/disable` | Per-platform toolset toggles; MCP tools as `server:tool` | VERIFIED-LIVE |
|
||||
| `hermes mcp add/remove/list/test/configure/picker/catalog/install` | MCP server management (incl. one-click catalog installs) | VERIFIED-LIVE |
|
||||
| `hermes mcp serve` | Run Hermes AS an MCP server for other agents | VERIFIED-LIVE |
|
||||
| `hermes computer-use install/status/doctor` | Desktop-control backend (cua-driver) | VERIFIED-LIVE |
|
||||
| `hermes gateway run/install/start/status/setup` | Messaging gateway (Telegram, Discord, Slack, WhatsApp, …) | VERIFIED-LIVE |
|
||||
| `hermes send` | Send a message to a configured platform (scripts/cron/CI) | VERIFIED-LIVE |
|
||||
|
||||
### Automation & multi-agent
|
||||
| Command | What it does | Tag |
|
||||
|---|---|---|
|
||||
| `hermes cron list/create/edit/pause/resume/run/remove/doctor` | Scheduled jobs (durable, multi-platform delivery) | VERIFIED-LIVE |
|
||||
| `hermes cron notepad` | Durable per-job key-value notepad across runs | VERIFIED-LIVE |
|
||||
| `hermes kanban create/list/show/link/complete/swarm/...` | Durable multi-profile task board (40+ verbs) | VERIFIED-LIVE |
|
||||
| `hermes kanban swarm` | Generate a parallel-workers → verifier → synthesizer task graph | VERIFIED-LIVE |
|
||||
| `hermes project create/list/add-folder/bind-board` | Named multi-folder workspaces (desktop Projects) | VERIFIED-LIVE |
|
||||
| `hermes profile list/create/use/alias/export/import` | Isolated Hermes instances | VERIFIED-LIVE |
|
||||
| `hermes auth add/list/priority/reset` | Pooled credentials per provider (rotation) | VERIFIED-LIVE |
|
||||
| `hermes fallback list/add/remove` | Fallback model chain (auto-rollover on failure) | VERIFIED-LIVE |
|
||||
| `hermes model` | Interactive model/provider picker | VERIFIED-LIVE |
|
||||
| `hermes -yolo` | Bypass command approval prompts (use with care) | VERIFIED-LIVE |
|
||||
| `hermes pause` / `hermes resume` | Emergency stop / lift (pauses cron, kanban dispatch, gateway turns) | VERIFIED-LIVE |
|
||||
|
||||
## (b) In-session slash commands
|
||||
|
||||
Source: official slash-commands reference https://hermes-agent.nousresearch.com/docs/reference/slash-commands (DOC-ONLY — slash commands run inside a chat session and were not exercised from this headless research run; the CLI subcommands they map to were verified live). DOC-ONLY.
|
||||
|
||||
### Context & session
|
||||
| Command | What it does |
|
||||
|---|---|
|
||||
| `/help` | List all commands (authoritative in your version) |
|
||||
| `/new` (`/reset`) | Fresh session |
|
||||
| `/resume [name]` | Resume a named/recent session |
|
||||
| `/branch` (`/fork`) | Branch the current session |
|
||||
| `/compress` | Manually compress context (auto-compression also exists) |
|
||||
| `/undo` | Remove last exchange |
|
||||
| `/retry` | Resend last message |
|
||||
| `/title [name]` | Name the session |
|
||||
| `/save` | Save conversation to file |
|
||||
| `/history` | Show conversation history |
|
||||
|
||||
### Power surfaces
|
||||
| Command | What it does |
|
||||
|---|---|
|
||||
| `/skill <name>` | Load a skill into the session |
|
||||
| `/skills` | Search/install skills |
|
||||
| `/reload-skills` | Re-scan skill directory |
|
||||
| `/tools` / `/toolsets` | Manage tools |
|
||||
| `/goal [text]` | Set a standing goal the agent works toward across turns (`/goal status/pause/clear` to manage) |
|
||||
| `/background <prompt>` | Run a prompt in the background |
|
||||
| `/queue <prompt>` | Queue a prompt for the next turn |
|
||||
| `/steer <prompt>` | Inject a course-correction after the next tool call without interrupting |
|
||||
| `/agents` | Show active agents and running tasks |
|
||||
| `/cron` | Manage cron jobs in-session |
|
||||
| `/kanban` | Multi-profile collaboration board in-session |
|
||||
| `/model [name]` | Show/change model mid-session |
|
||||
| `/reasoning [level]` | Set reasoning effort |
|
||||
| `/voice [on\|off\|tts]` | Voice mode |
|
||||
| `/rollback [N]` | Restore filesystem checkpoint (needs `--checkpoints`) |
|
||||
| `/usage` | Token usage |
|
||||
| `/insights [days]` | Usage analytics |
|
||||
| `/platforms` | Gateway platform status |
|
||||
| `/compact`-equivalent note | Hermes compresses automatically near the context limit; no manual threshold watch needed like Claude Code's `/context` |
|
||||
|
||||
### The "work alongside Claude Code" shortlist
|
||||
1. `hermes import-agent claude-code --dry-run` → migrate the setup (VERIFIED-LIVE)
|
||||
2. `hermes sessions import` → bring the conversation history over (VERIFIED-LIVE)
|
||||
3. `hermes skills trust` → load repo-local skills like `.claude/skills/` (VERIFIED-LIVE)
|
||||
4. `hermes -c` / `hermes --in <repo> --resume latest` → per-directory session continuity (VERIFIED-LIVE)
|
||||
5. `hermes mcp serve` → expose Hermes to Claude Code as an MCP server (VERIFIED-LIVE) — the reverse direction Claude Code can't do
|
||||
@@ -1,76 +0,0 @@
|
||||
# 04 — The Claude Code Bridge: Running Hermes WITH Claude Code
|
||||
|
||||
**Prepared:** 2026-09-11. Scot already runs both tools. This file documents the proven integration patterns, citing the installed skills on this host (paths under `/home/hermes/.hermes/skills/`) and official docs.
|
||||
|
||||
## Pattern 0 — Import (do this first)
|
||||
`hermes import-agent claude-code` [VERIFIED-LIVE] maps CLAUDE.md/AGENTS.md instructions,
|
||||
permission allowlists, MCP servers, skills, and memories into Hermes equivalents. It always
|
||||
shows a preview, never imports credentials. `hermes sessions import` [VERIFIED-LIVE] pulls
|
||||
in old Claude Code conversations. After import, Hermes "knows" the projects — the context
|
||||
gap disappears on day one.
|
||||
|
||||
## Pattern 1 — Hermes as orchestrator, Claude Code as worker
|
||||
Source: installed skill **`autonomous-ai-agents/delegate-coding-agent`** (v1.0.0) + its
|
||||
reference `references/claude-code.md` (v2.2.1) [V-FILE]. The skill is an official Hermes
|
||||
skill authored for exactly this.
|
||||
|
||||
Two orchestration modes (verbatim from the skill):
|
||||
- **Print mode (preferred):** `claude -p '<task>' --allowedTools 'Read,Edit' --max-turns 10` —
|
||||
one-shot, no dialogs, structured JSON output with `session_id`, `num_turns`,
|
||||
`total_cost_usd`. Ask Hermes: *"delegate this coding task to Claude Code in print mode."*
|
||||
- **Interactive PTY via tmux:** multi-turn sessions — Hermes starts `tmux new-session`,
|
||||
sends prompts with `send-keys`, monitors with `capture-pane`. For iterative
|
||||
refactor → review → fix cycles.
|
||||
|
||||
Cross-agent review loop (also from the skill):
|
||||
```
|
||||
git diff main...feature | claude -p 'Review this diff for bugs and security issues.' --max-turns 1
|
||||
```
|
||||
Hermes runs this, reads the output, and fixes findings itself — Claude Code becomes a
|
||||
reviewer Hermes coordinates.
|
||||
|
||||
Safety rails the skill prescribes: explicit `workdir`, clean git status before launch,
|
||||
narrow task prompts, `git diff` review, targeted tests before committing.
|
||||
|
||||
## Pattern 2 — Parallel workstreams + neutral merge reconciliation
|
||||
Source: installed skill **`autonomous-ai-agents/merge-reconciler`** [V-FILE].
|
||||
When Hermes and Claude Code (or two Hermes workers) both edit the same repo and collide:
|
||||
- Do NOT let either agent resolve the conflict — both are biased toward their own side.
|
||||
- Spawn a **neutral third agent** with the merge-reconciler skill; it classifies every
|
||||
conflicted hunk (disjoint-intent / same-question-different-answer / superseded), resolves
|
||||
under an impartiality contract (touch only conflict markers, surface every design call),
|
||||
verifies with build/tests, and hands back a summary naming every hunk decision.
|
||||
- Kanban-native shape: a reconciliation card assigned to a **third profile** with both
|
||||
workers' cards as parents — parent links carry both sides' completion summaries into the
|
||||
reconciler's context automatically.
|
||||
|
||||
## Pattern 3 — Hermes as MCP server (Claude Code gets Hermes tools)
|
||||
`hermes mcp serve` [VERIFIED-LIVE] runs Hermes as an MCP server exposing its conversations
|
||||
and capabilities. Claude Code supports MCP clients (`claude mcp add`), so Claude Code can
|
||||
consume Hermes as a tool provider — persistent memory, skills, cron — the surfaces Claude
|
||||
Code lacks. This is the reverse-bridge only Hermes can offer. Docs:
|
||||
https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp
|
||||
|
||||
## Pattern 4 — Import legacy sessions for continuity
|
||||
`hermes sessions import` [VERIFIED-LIVE] imports a Claude Code session into the Hermes
|
||||
store; from then on `hermes --resume <id>` / `hermes sessions browse` treat it as native
|
||||
history. Use when mid-project: the new agent picks up exactly where Claude Code left off.
|
||||
|
||||
## Pattern 5 — Desktop GUI automation either side can use
|
||||
Source: installed skill **`autonomous-ai-agents/computer-use`** (v2.0.0) [V-FILE].
|
||||
`hermes computer-use install` sets up cua-driver; the `computer_use` toolset drives native
|
||||
desktop apps background-first (never steals focus/cursor), any-model, cross-platform.
|
||||
Relevant to the bridge because Claude Code has no desktop automation — if a task needs
|
||||
Figma/Excel/native apps, that part routes to Hermes while the code routes to Claude Code.
|
||||
Cmd: `hermes computer-use doctor` for health checks.
|
||||
|
||||
## Pattern 6 — The import-agent philosophy in one line
|
||||
Claude Code holds repo context in `CLAUDE.md`; Hermes holds it in `AGENTS.md` + memory +
|
||||
skills. `hermes import-agent claude-code` translates the first; the learning loop
|
||||
("save this as a skill") rebuilds the rest automatically the more Scot uses Hermes.
|
||||
|
||||
## Reference paths (for the writer)
|
||||
- `/home/hermes/.hermes/skills/autonomous-ai-agents/delegate-coding-agent/SKILL.md` and `references/claude-code.md`
|
||||
- `/home/hermes/.hermes/skills/autonomous-ai-agents/merge-reconciler/SKILL.md`
|
||||
- `/home/hermes/.hermes/skills/autonomous-ai-agents/computer-use/SKILL.md`
|
||||
- `hermes import-agent --help` raw output in `cli-help-dump.txt` (lines 554-577)
|
||||
@@ -1,119 +0,0 @@
|
||||
# 05 — The Video Watch List (every URL verified 2026-09-11)
|
||||
|
||||
**Verification method:** each video was found via YouTube search-results scrape (`videoRenderer` metadata), then confirmed with the YouTube oEmbed endpoint (`curl -s "https://www.youtube.com/oembed?url=<URL>&format=json"`) — every entry below returned HTTP 200 with matching title/author (status PASS). Publish dates, durations, and view counts were read from each watch page's metadata. Raw evidence for all 21 entries: `video-verification.json` in this directory. **21/21 PASS, 0 FAIL.**
|
||||
|
||||
## Tier 1 — Hermes-specific, start here
|
||||
|
||||
### 1. Learn 95% of Hermes Agent in 31 Minutes
|
||||
- **Channel:** Sharbel A. | **URL:** https://www.youtube.com/watch?v=Ta2wg6xPaY4 | **Duration:** 31:28 | **Published:** 2026-08-09 | **Views:** ~129k
|
||||
- **oEmbed:** PASS (title/author match)
|
||||
- **What it demonstrates:** end-to-end Hermes fundamentals — install, sessions, skills, memory, the learning loop. The most complete single-video orientation found.
|
||||
- **Watch this when you want** the fastest real overview of the whole harness before touching config.
|
||||
|
||||
### 2. Hermes Agent Fundamentals In 29 Minutes
|
||||
- **Channel:** Tina Huang | **URL:** https://www.youtube.com/watch?v=5_N84t1rUU0 | **Duration:** 29:40 | **Published:** 2026-07-20 | **Views:** ~463k (highest-reach Hermes video found)
|
||||
- **oEmbed:** PASS
|
||||
- **What it demonstrates:** conceptual grounding — why Hermes' memory/skills loop differs from one-shot coding agents; practical walkthrough.
|
||||
- **Watch this when you want** to understand *why* Hermes feels different from Claude Code, not just which buttons to press.
|
||||
|
||||
### 3. Every Level of Hermes Agent Explained
|
||||
- **Channel:** Jack Roberts | **URL:** https://www.youtube.com/watch?v=6GtF_uHbGhw | **Duration:** 25:35 | **Published:** 2026-06-17 | **Views:** ~163k
|
||||
- **oEmbed:** PASS
|
||||
- **What it demonstrates:** beginner → advanced ladder of features (memory, skills, automation, multi-agent).
|
||||
- **Watch this when you want** a map of what to learn next after the basics.
|
||||
|
||||
### 4. Hermes Agent Full Tutorial INSTALLATION + USECASES
|
||||
- **Channel:** CodeHead | **URL:** https://www.youtube.com/watch?v=8GjyOQy19so | **Duration:** 7:47 | **Published:** 2026-05-14 | **Views:** ~64k
|
||||
- **oEmbed:** PASS
|
||||
- **What it demonstrates:** install through real use-cases, compact.
|
||||
- **Watch this when you want** a quick install-to-value demo to share with a colleague.
|
||||
|
||||
### 5. Hermes Agent Explained In 5 Minutes
|
||||
- **Channel:** CodeHead | **URL:** https://www.youtube.com/watch?v=9GpWELm3_XI | **Duration:** 4:53 | **Published:** 2026-05-23 | **Views:** ~251k
|
||||
- **oEmbed:** PASS
|
||||
- **What it demonstrates:** 5-minute conceptual pitch of the agent and its learning loop.
|
||||
- **Watch this when you want** the elevator pitch before committing 30 minutes.
|
||||
|
||||
## Tier 2 — Hermes-specific deep dives
|
||||
|
||||
### 6. 100 Days With Hermes Agent in 21 Minutes
|
||||
- **Channel:** Sharbel A. | **URL:** https://www.youtube.com/watch?v=sCa3BtpkziQ | **Duration:** 21:19 | **Published:** 2026-06-17 | **Views:** ~58k
|
||||
- **oEmbed:** PASS
|
||||
- **What it demonstrates:** long-horizon usage — what memory/skills accumulation actually looks like after months of daily use.
|
||||
- **Watch this when you want** to see the payoff of the learning loop over time.
|
||||
|
||||
### 7. Hermes Agent - Crash Course for Beginners (AI Agent)
|
||||
- **Channel:** Adrian Twarog | **URL:** https://www.youtube.com/watch?v=4sAmpcSOVEw | **Duration:** 22:19 | **Published:** 2026-07-21 | **Views:** ~46k
|
||||
- **oEmbed:** PASS
|
||||
- **What it demonstrates:** beginner crash course from a well-known dev-YouTube creator.
|
||||
- **Watch this when you want** a second independent explanation of the basics.
|
||||
|
||||
### 8. Hermes Agent: The Ultimate Beginner's Guide
|
||||
- **Channel:** Metics Media | **URL:** https://www.youtube.com/watch?v=CwPUOVUdApE | **Duration:** 37:08 | **Published:** 2026-04-24 | **Views:** ~119k
|
||||
- **oEmbed:** PASS
|
||||
- **What it demonstrates:** long-form beginner guide incl. setup and everyday workflows.
|
||||
- **Watch this when you want** the most thorough single walkthrough in one sitting.
|
||||
|
||||
### 9. Hermes Agent Just Killed OpenClaw (Full Tutorial)
|
||||
- **Channel:** Leon van Zyl | **URL:** https://www.youtube.com/watch?v=jmtpYUOr7_U | **Duration:** 19:59 | **Published:** 2026-04-28 | **Views:** ~16k
|
||||
- **oEmbed:** PASS
|
||||
- **What it demonstrates:** full tutorial framing Hermes against the OpenClaw workflow (MCP config, memory, agents).
|
||||
- **Watch this when you want** a practitioner's feature-by-feature tutorial.
|
||||
|
||||
### 10. Hermes Agent vs OpenClaw
|
||||
- **Channel:** Sharbel A. | **URL:** https://www.youtube.com/watch?v=zwqhemjHq3E | **Duration:** 15:28 | **Published:** 2026-04-20 | **Views:** ~35k
|
||||
- **oEmbed:** PASS
|
||||
- **What it demonstrates:** head-to-head comparison of the two agent harnesses.
|
||||
- **Watch this when you want** the tradeoffs between Hermes and its main alternative.
|
||||
|
||||
### 11. Better than OpenClaw? Testing Hermes Agent w/ Qwen 3 model
|
||||
- **Channel:** Tonbi's AI Garage | **URL:** https://www.youtube.com/watch?v=8tpuky8HpXw | **Duration:** 15:08 | **Published:** 2026-03-11 | **Views:** ~18k
|
||||
- **oEmbed:** PASS
|
||||
- **What it demonstrates:** Hermes driven by an OpenRouter-served open model (Qwen 3) — directly relevant to an OpenRouter-connected install.
|
||||
- **Watch this when you want** to see how small open models behave inside Hermes.
|
||||
|
||||
### 12. Use This To Make The Hermes Agent Basically Free
|
||||
- **Channel:** AI LABS | **URL:** https://www.youtube.com/watch?v=5d02TYoOzfE | **Duration:** 13:08 | **Published:** 2026-07-01 | **Views:** ~55k
|
||||
- **oEmbed:** PASS
|
||||
- **What it demonstrates:** running Hermes on cheap/free model backends.
|
||||
- **Watch this when you want** to cut inference costs on an OpenRouter account.
|
||||
|
||||
### 13. Hermes Agent The 24/7 Self-Evolving AI Agent!
|
||||
- **Channel:** WorldofAI | **URL:** https://www.youtube.com/watch?v=cu2fgknmemA | **Duration:** 9:15 | **Published:** 2026-04-07 | **Views:** ~47k
|
||||
- **oEmbed:** PASS
|
||||
- **What it demonstrates:** always-on operation: gateway, cron, background automation.
|
||||
- **Watch this when you want** to turn Hermes from a chat window into a 24/7 assistant.
|
||||
|
||||
## Tier 3 — Adjacent (origin/philosophy; not tutorials)
|
||||
|
||||
### 14. Hermes Co-Founder on Building an AI Agent That Improves Itself | Karan Malhotra
|
||||
- **Channel:** Peter Yang | **URL:** https://www.youtube.com/watch?v=UWjh5Z4s8jY | **Duration:** 46:45 | **Published:** 2026-08-02 | **Views:** ~37k
|
||||
- **oEmbed:** PASS
|
||||
- **What it demonstrates:** interview with Hermes' co-founder on the design philosophy (self-improving agents, skills as memory).
|
||||
- **Watch this when you want** to understand where the product is going.
|
||||
|
||||
### 15. Hermes Agent: Agents that grow with you | Episode #357
|
||||
- **Channel:** Practical AI | **URL:** https://www.youtube.com/watch?v=UTZhvPXnmwA | **Duration:** 47:34 | **Published:** 2026-05-20 | **Views:** ~1.9k
|
||||
- **oEmbed:** PASS
|
||||
- **What it demonstrates:** podcast-depth technical discussion of the agent architecture.
|
||||
- **Watch this when you want** the engineering story behind the learning loop.
|
||||
|
||||
### 16. Did Hermes Agent just kill OpenClaw? (full guide)
|
||||
- **Channel:** Alex Finn | **URL:** https://www.youtube.com/watch?v=tP6yf22OJdI | **Duration:** 13:55 | **Published:** 2026-03-31 | **Views:** ~132k
|
||||
- **oEmbed:** PASS
|
||||
- **What it demonstrates:** guide-style comparison/switch content.
|
||||
- **Watch this when you want** a switcher's guide perspective.
|
||||
|
||||
### 17. Hermes Agent: Why Everyone's Ditching OpenClaw in 2026
|
||||
- **Channel:** Luke Alexander AI | **URL:** https://www.youtube.com/watch?v=1UgXUjT-QtI | **Duration:** 18:03 | **Published:** 2026-03-26 | **Views:** ~14k
|
||||
- **oEmbed:** PASS — adjacent, comparison content.
|
||||
- **Watch this when you want** more comparison context.
|
||||
|
||||
## Honesty note (required by task spec)
|
||||
At least 16 of the 17 entries above are directly Hermes-specific (not merely adjacent); the
|
||||
"fewer than 5 exist" fallback clause was NOT needed — no padding was necessary. Entries
|
||||
found in search but excluded as thin/low-signal: `iqN6MVzpJTk` (3.1k views, news-style),
|
||||
`83nWNRKZTCE` (465 views), `6M2tItdARew` (1.2k views), `P2LIFtrRr2U` (promo-style) — all
|
||||
also verified PASS and kept in `video-verification.json` as spares. No official Nous
|
||||
Research YouTube tutorial channel was found in searches; the strongest signal of
|
||||
Hermes-specific video content is the third-party ecosystem above.
|
||||
@@ -1,577 +0,0 @@
|
||||
===== hermes chat --help =====
|
||||
usage: hermes chat [-h] [-q QUERY | --query-file PATH] [--oneshot]
|
||||
[--image IMAGE] [-m MODEL] [-t TOOLSETS]
|
||||
[--reasoning LEVEL] [-s SKILLS] [--provider PROVIDER] [-v]
|
||||
[-Q] [--resume SESSION_ID] [--no-restore-cwd] [--in DIR]
|
||||
[--continue [SESSION_NAME]] [--create-if-missing]
|
||||
[--worktree] [--accept-hooks] [--checkpoints]
|
||||
[--max-turns N] [--run-budget SECONDS] [--yolo]
|
||||
[--pass-session-id] [--ignore-user-config] [--ignore-rules]
|
||||
[--safe-mode] [--source SOURCE] [--tui] [--cli] [--dev]
|
||||
|
||||
Start an interactive chat session with Hermes Agent
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
-q, --query QUERY Query to run. On a real TTY the prompt seeds an
|
||||
interactive session (submitted literally as the first
|
||||
turn); combined with --oneshot or -Q, or on a non-TTY,
|
||||
it answers and exits.
|
||||
--query-file PATH Read the single query from a file instead of the
|
||||
command line ('-' reads stdin). Safe for arbitrary
|
||||
text: nothing is shell-interpreted, so quotes, $(...),
|
||||
and backticks are preserved verbatim. Mutually
|
||||
exclusive with -q.
|
||||
--oneshot With -q/--query-file: answer the query and exit
|
||||
(legacy single-query behavior) instead of seeding an
|
||||
interactive session. Implied on non-TTY stdio and by
|
||||
-Q/--quiet.
|
||||
--image IMAGE Optional local image path to attach to a single query
|
||||
-m, --model MODEL Model to use (e.g., anthropic/claude-sonnet-4)
|
||||
-t, --toolsets TOOLSETS
|
||||
Comma-separated toolsets to enable
|
||||
--reasoning LEVEL Reasoning effort for this session: none, minimal, low,
|
||||
medium, high, xhigh, max, or ultra. Overrides
|
||||
agent.reasoning_effort for this run only (same levels
|
||||
as the /reasoning slash command).
|
||||
-s, --skills SKILLS Preload one or more skills for the session (repeat
|
||||
flag or comma-separate)
|
||||
--provider PROVIDER Inference provider (default: auto). Built-in or a
|
||||
user-defined name from `providers:` in config.yaml.
|
||||
-v, --verbose Verbose output
|
||||
-Q, --quiet Quiet mode for programmatic use: suppress banner,
|
||||
spinner, and tool previews. Only output the final
|
||||
response and session info.
|
||||
--resume, -r SESSION_ID
|
||||
Resume a previous session by ID (shown on exit), or
|
||||
'latest' for the most recent session
|
||||
--no-restore-cwd Don't cd into a resumed session's recorded working
|
||||
directory.
|
||||
--in DIR Change into DIR before starting or resuming (scopes '
|
||||
--resume latest' / -c lookups to DIR's workspace).
|
||||
--continue, -c [SESSION_NAME]
|
||||
Resume a session by name, or the most recent if no
|
||||
name given
|
||||
--create-if-missing With -c/--continue <name>: if no session matches the
|
||||
name, create a new session with that title and proceed
|
||||
(instead of failing with a not-found error).
|
||||
Programmatic callers that want 'send to this named
|
||||
thread, making it if needed'.
|
||||
--worktree, -w Run in an isolated git worktree (for parallel agents
|
||||
on the same repo)
|
||||
--accept-hooks Auto-approve any unseen shell hooks declared in
|
||||
config.yaml without a TTY prompt (see also
|
||||
HERMES_ACCEPT_HOOKS env var and hooks_auto_accept: in
|
||||
config.yaml).
|
||||
--checkpoints Enable filesystem checkpoints before destructive file
|
||||
operations (use /rollback to restore)
|
||||
--max-turns N Maximum tool-calling iterations per conversation turn
|
||||
(default: 500, or agent.max_turns in config)
|
||||
--run-budget SECONDS Optional wall-clock budget in seconds for each
|
||||
conversation run. At 80% elapsed the agent gets a one-
|
||||
time wrap-up notice, and implicit provider stale
|
||||
timeouts are capped to the remaining budget so one
|
||||
hung call can't consume the run. Unset = off. Also
|
||||
configurable as agent.run_budget_seconds in
|
||||
config.yaml. Intended for one-shot/eval invocations
|
||||
with a hard ceiling.
|
||||
--yolo Bypass all dangerous command approval prompts (use at
|
||||
your own risk)
|
||||
--pass-session-id Include the session ID in the agent's system prompt
|
||||
--ignore-user-config Ignore ~/.hermes/config.yaml and fall back to built-in
|
||||
defaults (credentials in .env are still loaded).
|
||||
Useful for isolated CI runs, reproduction, and third-
|
||||
party integrations.
|
||||
--ignore-rules Skip auto-injection of AGENTS.md, SOUL.md,
|
||||
.cursorrules, memory, and preloaded skills. Combine
|
||||
with --ignore-user-config for a fully isolated run.
|
||||
--safe-mode Troubleshooting mode: disable ALL customizations —
|
||||
user config, AGENTS.md/memory injection, plugins, and
|
||||
MCP servers (implies --ignore-user-config and
|
||||
--ignore-rules). Use to isolate whether a problem
|
||||
comes from your setup or from Hermes itself.
|
||||
--source SOURCE Session source tag for filtering (default: cli). Use
|
||||
'tool' for third-party integrations that should not
|
||||
appear in user session lists.
|
||||
--tui Launch the modern TUI instead of the classic REPL
|
||||
--cli Force the classic prompt_toolkit REPL (overrides
|
||||
display.interface=tui)
|
||||
--dev With --tui: run TypeScript sources via tsx (skip dist
|
||||
build)
|
||||
===== hermes model --help =====
|
||||
usage: hermes model [-h] [--refresh] [--portal-url PORTAL_URL]
|
||||
[--inference-url INFERENCE_URL] [--client-id CLIENT_ID]
|
||||
[--scope SCOPE] [--no-browser] [--timeout TIMEOUT]
|
||||
[--ca-bundle CA_BUNDLE] [--insecure]
|
||||
|
||||
Interactively select your inference provider and default model
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
--refresh Wipe the model picker disk cache and re-fetch every
|
||||
provider's live /v1/models list.
|
||||
--portal-url PORTAL_URL
|
||||
Portal base URL for Nous login (default: production
|
||||
portal)
|
||||
--inference-url INFERENCE_URL
|
||||
Inference API base URL for Nous login (default:
|
||||
production inference API)
|
||||
--client-id CLIENT_ID
|
||||
OAuth client id to use for Nous login (default:
|
||||
hermes-cli)
|
||||
--scope SCOPE OAuth scope to request for Nous login
|
||||
--no-browser Do not attempt to open the browser automatically
|
||||
during Nous login
|
||||
--timeout TIMEOUT HTTP request timeout in seconds for Nous login
|
||||
(default: 15)
|
||||
--ca-bundle CA_BUNDLE
|
||||
Path to CA bundle PEM file for Nous TLS verification
|
||||
--insecure Disable TLS verification for Nous login (testing only)
|
||||
===== hermes config --help =====
|
||||
usage: hermes config [-h]
|
||||
{show,edit,get,set,unset,path,env-path,check,migrate} ...
|
||||
|
||||
Manage Hermes Agent configuration
|
||||
|
||||
positional arguments:
|
||||
{show,edit,get,set,unset,path,env-path,check,migrate}
|
||||
show Show current configuration
|
||||
edit Open config file in editor
|
||||
get Print a resolved configuration value
|
||||
set Set a configuration value
|
||||
unset Remove a configuration value
|
||||
path Print config file path
|
||||
env-path Print .env file path
|
||||
check Check for missing/outdated config
|
||||
migrate Update config with new options
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
===== hermes cron --help =====
|
||||
usage: hermes cron [-h] [--accept-hooks]
|
||||
{list,create,add,edit,pause,resume,run,remove,rm,delete,status,runs,history,incidents,notepad,doctor,tick} ...
|
||||
|
||||
Manage scheduled tasks
|
||||
|
||||
positional arguments:
|
||||
{list,create,add,edit,pause,resume,run,remove,rm,delete,status,runs,history,incidents,notepad,doctor,tick}
|
||||
list List scheduled jobs
|
||||
create (add) Create a scheduled job
|
||||
edit Edit an existing scheduled job
|
||||
pause Pause a scheduled job
|
||||
resume Resume a paused job
|
||||
run Run a job on the next scheduler tick
|
||||
remove (rm, delete)
|
||||
Remove a scheduled job
|
||||
status Check if cron scheduler is running
|
||||
runs (history) Show durable execution attempts
|
||||
incidents List or acknowledge durable cron failure incidents
|
||||
notepad Read/write a job's durable notepad (persistent KV
|
||||
across runs)
|
||||
doctor Check scheduled jobs for common health issues
|
||||
tick Run due jobs once and exit
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
--accept-hooks Auto-approve unseen shell hooks without a TTY prompt
|
||||
(equivalent to HERMES_ACCEPT_HOOKS=1 /
|
||||
hooks_auto_accept: true).
|
||||
===== hermes kanban --help =====
|
||||
usage: hermes kanban [-h] [--board <slug>]
|
||||
{init,boards,create,swarm,list,ls,show,assign,set-model,reclaim,reassign,diagnostics,diag,link,unlink,claim,comment,attach,attachments,attach-rm,complete,edit,block,schedule,unblock,request-review,request-changes,reopen-review,promote,archive,tail,dispatch,daemon,watch,stats,notify-subscribe,notify-list,notify-unsubscribe,log,runs,heartbeat,assignees,context,specify,decompose,gc,repair} ...
|
||||
|
||||
Durable SQLite-backed task board shared across Hermes profiles. Tasks are
|
||||
claimed atomically, can depend on other tasks, and are executed by a named
|
||||
profile in an isolated workspace. See https://hermes-
|
||||
agent.nousresearch.com/docs/user-guide/features/kanban or docs/hermes-
|
||||
kanban-v1-spec.pdf for the full design.
|
||||
|
||||
positional arguments:
|
||||
{init,boards,create,swarm,list,ls,show,assign,set-model,reclaim,reassign,diagnostics,diag,link,unlink,claim,comment,attach,attachments,attach-rm,complete,edit,block,schedule,unblock,request-review,request-changes,reopen-review,promote,archive,tail,dispatch,daemon,watch,stats,notify-subscribe,notify-list,notify-unsubscribe,log,runs,heartbeat,assignees,context,specify,decompose,gc,repair}
|
||||
init Create kanban.db if missing (idempotent)
|
||||
boards Manage kanban boards (one board per project /
|
||||
workstream)
|
||||
create Create a new task
|
||||
swarm Create a Kanban Swarm v1 graph (parallel workers →
|
||||
verifier → synthesizer)
|
||||
list (ls) List tasks
|
||||
show Show a task with comments + events
|
||||
assign Assign or reassign a task
|
||||
set-model Set or clear a task's model/provider override (takes
|
||||
effect on the next dispatch)
|
||||
reclaim Release an active worker claim on a running task
|
||||
reassign Reassign a task to a different profile, optionally
|
||||
reclaiming first
|
||||
diagnostics (diag) List active diagnostics on the current board
|
||||
link Add a parent->child dependency
|
||||
unlink Remove a parent->child dependency
|
||||
claim Atomically claim a ready task (prints resolved
|
||||
workspace path)
|
||||
comment Append a comment
|
||||
attach Attach a local file to a task
|
||||
attachments List a task's attachments
|
||||
attach-rm Delete an attachment by id
|
||||
complete Mark one or more tasks done
|
||||
edit Edit recovery fields on an already-completed task
|
||||
block Mark one or more tasks blocked
|
||||
schedule Park one or more tasks in Scheduled (waiting on time,
|
||||
not human input)
|
||||
unblock Return blocked/scheduled tasks to ready, or todo while
|
||||
parents remain open
|
||||
request-review Move a task to 'review' (implementation done, awaiting
|
||||
review) — NOT a block
|
||||
request-changes Reviewer verdict: return the active review run to its
|
||||
implementer
|
||||
reopen-review Send one or more review tasks back for changes (review
|
||||
-> ready/todo)
|
||||
promote Manually move one or more todo/blocked tasks to ready
|
||||
(recovery path)
|
||||
archive Archive one or more tasks
|
||||
tail Follow a task's event stream
|
||||
dispatch One dispatcher pass: reclaim stale, promote ready,
|
||||
spawn workers
|
||||
daemon DEPRECATED — dispatcher now runs in the gateway. Use
|
||||
`hermes gateway start`.
|
||||
watch Live-stream task_events to the terminal (Ctrl+C to
|
||||
exit)
|
||||
stats Per-status + per-assignee counts + oldest-ready age
|
||||
notify-subscribe Subscribe a gateway source to a task's terminal events
|
||||
(used by /kanban subscribe in the gateway adapter)
|
||||
notify-list List notification subscriptions (optionally for a
|
||||
single task)
|
||||
notify-unsubscribe Remove a gateway subscription from a task
|
||||
log Print the worker log for a task (from <kanban-
|
||||
root>/kanban/logs/)
|
||||
runs Show attempt history for a task (one row per run:
|
||||
profile, outcome, elapsed, summary)
|
||||
heartbeat Emit a heartbeat event for a running task (worker
|
||||
liveness signal)
|
||||
assignees List known profiles + per-profile task counts (union
|
||||
of ~/.hermes/profiles/ and current assignees on the
|
||||
board)
|
||||
context Print the full context a worker sees for a task (title
|
||||
+ body + parent results + comments).
|
||||
specify Flesh out a triage-column task into a concrete spec
|
||||
(title + body) and promote it to todo. Uses the
|
||||
auxiliary LLM configured under
|
||||
auxiliary.triage_specifier.
|
||||
decompose Decompose a triage-column task into a graph of child
|
||||
tasks routed to specialist profiles by description.
|
||||
Falls back to specify-style single-task promotion when
|
||||
the task doesn't benefit from fan-out. Uses
|
||||
auxiliary.kanban_decomposer.
|
||||
gc Garbage-collect archived-task workspaces, old events,
|
||||
and old logs
|
||||
repair Check kanban.db integrity and auto-repair index-only
|
||||
corruption
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
--board <slug> Board slug to operate on. Defaults to the current
|
||||
board (set via `hermes kanban boards switch <slug>` or
|
||||
the HERMES_KANBAN_BOARD env var). Use `hermes kanban
|
||||
boards list` to see all boards.
|
||||
===== hermes skills --help =====
|
||||
usage: hermes skills [-h]
|
||||
{trust,untrust,browse,search,install,inspect,list,check,update,audit,uninstall,reset,list-modified,diff,opt-out,opt-in,repair-official,publish,snapshot,tap,config} ...
|
||||
|
||||
Search, install, inspect, audit, configure, and manage skills from skills.sh,
|
||||
well-known agent skill endpoints, GitHub, ClawHub, and other registries.
|
||||
|
||||
positional arguments:
|
||||
{trust,untrust,browse,search,install,inspect,list,check,update,audit,uninstall,reset,list-modified,diff,opt-out,opt-in,repair-official,publish,snapshot,tap,config}
|
||||
trust Trust a project so its repo-local skills
|
||||
(./.hermes/skills, ./.agents/skills) load
|
||||
untrust Revoke project-skill trust for a repo
|
||||
browse Browse all available skills (paginated)
|
||||
search Search skill registries
|
||||
install Install a skill
|
||||
inspect Preview a skill without installing
|
||||
list List installed skills
|
||||
check Check installed hub skills for updates
|
||||
update Update installed hub skills
|
||||
audit Re-scan installed hub skills
|
||||
uninstall Remove a hub-installed skill
|
||||
reset Reset a bundled skill — clears 'user-modified'
|
||||
tracking so updates work again
|
||||
list-modified List bundled skills you've edited (which `hermes
|
||||
update` keeps)
|
||||
diff Show how your copy of a bundled skill differs from the
|
||||
stock version
|
||||
opt-out Stop bundled skills from being seeded into this
|
||||
profile
|
||||
opt-in Re-enable bundled-skill seeding (undo opt-out)
|
||||
repair-official Backfill or restore official optional skills from repo
|
||||
source
|
||||
publish Publish a skill to a registry
|
||||
snapshot Export/import skill configurations
|
||||
tap Manage skill sources
|
||||
config Interactive skill configuration — enable/disable
|
||||
individual skills
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
===== hermes sessions --help =====
|
||||
usage: hermes sessions [-h]
|
||||
{list,export,delete,prune,archive,optimize,clean-markers,optimize-storage,repair,repair-routing,recover,stats,rename,pin,unpin,pinned,retitle-skills,browse,import} ...
|
||||
|
||||
View and manage the SQLite session store
|
||||
|
||||
positional arguments:
|
||||
{list,export,delete,prune,archive,optimize,clean-markers,optimize-storage,repair,repair-routing,recover,stats,rename,pin,unpin,pinned,retitle-skills,browse,import}
|
||||
list List recent sessions
|
||||
export Export sessions to JSONL, Markdown, or QMD
|
||||
delete Delete a specific session
|
||||
prune Delete old sessions (filterable by time window,
|
||||
source, title, ...)
|
||||
archive Bulk-archive (soft-hide) sessions matching filters —
|
||||
no deletion
|
||||
optimize Reclaim disk space: merge FTS5 segments + VACUUM (no
|
||||
data change)
|
||||
clean-markers Permanently clear stale tool-call marker content left
|
||||
by sessions from before #78148
|
||||
optimize-storage Migrate the search index to the compact v23 layout
|
||||
(reclaims disk on large DBs)
|
||||
repair Repair a malformed state.db schema so hidden sessions
|
||||
reappear
|
||||
repair-routing Re-stamp gateway sessions that lost their routing
|
||||
identity
|
||||
recover Rebuild canonical session data into a separate clean
|
||||
database
|
||||
stats Show session store statistics
|
||||
rename Set or change a session's title
|
||||
pin Pin session(s) — durable keep flag, exempt from auto-
|
||||
archive
|
||||
unpin Remove the pin (durable keep flag) from session(s)
|
||||
pinned List pinned sessions
|
||||
retitle-skills Re-title sessions whose auto-title came from a
|
||||
/skill's own text
|
||||
browse Interactive session picker — browse, search, and
|
||||
resume sessions
|
||||
import Import a Claude Code or Codex CLI session into Hermes
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
===== hermes mcp --help =====
|
||||
usage: hermes mcp [-h] [--accept-hooks]
|
||||
{serve,add,remove,rm,list,ls,test,configure,config,login,reauth,picker,catalog,install} ...
|
||||
|
||||
Manage MCP server connections and run Hermes as an MCP server. MCP servers
|
||||
provide additional tools via the Model Context Protocol. Use 'hermes mcp add'
|
||||
to connect to a new server, or 'hermes mcp serve' to expose Hermes
|
||||
conversations over MCP.
|
||||
|
||||
positional arguments:
|
||||
{serve,add,remove,rm,list,ls,test,configure,config,login,reauth,picker,catalog,install}
|
||||
serve Run Hermes as an MCP server (expose conversations to
|
||||
other agents)
|
||||
add Add an MCP server (discovery-first install)
|
||||
remove (rm) Remove an MCP server
|
||||
list (ls) List configured MCP servers
|
||||
test Test MCP server connection
|
||||
configure (config) Toggle tool selection
|
||||
login Force re-authentication for an OAuth-based MCP server
|
||||
reauth Re-authenticate one OAuth MCP server, or all of them
|
||||
(--all)
|
||||
picker Interactive catalog picker (also the default for
|
||||
`hermes mcp`)
|
||||
catalog List Nous-approved MCPs available for one-click
|
||||
install
|
||||
install Install a catalog MCP by name (e.g. `hermes mcp
|
||||
install n8n`)
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
--accept-hooks Auto-approve unseen shell hooks without a TTY prompt
|
||||
(equivalent to HERMES_ACCEPT_HOOKS=1 /
|
||||
hooks_auto_accept: true).
|
||||
===== hermes profile --help =====
|
||||
usage: hermes profile [-h]
|
||||
{list,use,create,delete,describe,show,alias,rename,export,import,install,update,info} ...
|
||||
|
||||
positional arguments:
|
||||
{list,use,create,delete,describe,show,alias,rename,export,import,install,update,info}
|
||||
list List all profiles
|
||||
use Set sticky default profile
|
||||
create Create a new profile
|
||||
delete Delete a profile
|
||||
describe Read or set a profile's description (used by the
|
||||
kanban orchestrator)
|
||||
show Show profile details
|
||||
alias Manage wrapper scripts
|
||||
rename Rename a profile ('default': sets a display name; id
|
||||
unchanged)
|
||||
export Export a profile to archive
|
||||
import Import a profile from archive
|
||||
install Install a profile distribution from a git URL or local
|
||||
directory
|
||||
update Re-pull a distribution and apply updates (user data
|
||||
preserved)
|
||||
info Show a profile's distribution manifest (version,
|
||||
requirements, source)
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
===== hermes memory --help =====
|
||||
usage: hermes memory [-h] {setup,status,off,reset} ...
|
||||
|
||||
Set up and manage external memory provider plugins. Available providers:
|
||||
honcho, openviking, mem0, hindsight, holographic, retaindb, byterover. Only
|
||||
one external provider can be active at a time. Built-in memory
|
||||
(MEMORY.md/USER.md) is always active.
|
||||
|
||||
positional arguments:
|
||||
{setup,status,off,reset}
|
||||
setup Interactive provider selection and configuration
|
||||
status Show current memory provider config
|
||||
off Disable external provider (built-in only)
|
||||
reset Erase all built-in memory (MEMORY.md and USER.md)
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
===== hermes tools --help =====
|
||||
usage: hermes tools [-h] [--summary] {list,disable,enable,post-setup} ...
|
||||
|
||||
Enable, disable, or list tools for CLI, Telegram, Discord, etc. Built-in
|
||||
toolsets use plain names (e.g. web, memory). MCP tools use server:tool
|
||||
notation (e.g. github:create_issue). Run 'hermes tools' with no subcommand for
|
||||
the interactive configuration UI.
|
||||
|
||||
positional arguments:
|
||||
{list,disable,enable,post-setup}
|
||||
list Show all tools and their enabled/disabled status
|
||||
disable Disable toolsets or MCP tools
|
||||
enable Enable toolsets or MCP tools
|
||||
post-setup Run a provider's post-setup install hook
|
||||
(npm/pip/binary)
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
--summary Print a summary of enabled tools per platform and exit
|
||||
===== hermes project --help =====
|
||||
usage: hermes project [-h]
|
||||
{create,list,ls,show,add-folder,remove-folder,rename,set-primary,use,archive,restore,bind-board} ...
|
||||
|
||||
Projects are human-named workspaces that can span multiple folders / repos.
|
||||
They anchor desktop session grouping and, when bound to a kanban board, give
|
||||
tasks a deterministic worktree + branch convention. State is per-profile.
|
||||
|
||||
positional arguments:
|
||||
{create,list,ls,show,add-folder,remove-folder,rename,set-primary,use,archive,restore,bind-board}
|
||||
create Create a new project
|
||||
list (ls) List projects
|
||||
show Show a project's details
|
||||
add-folder Add a folder to a project
|
||||
remove-folder Remove a folder from a project
|
||||
rename Rename a project
|
||||
set-primary Set the primary folder
|
||||
use Set the active project
|
||||
archive Archive a project
|
||||
restore Restore an archived project
|
||||
bind-board Bind a kanban board to a project
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
===== hermes gateway --help =====
|
||||
usage: hermes gateway [-h] [--accept-hooks]
|
||||
{run,start,stop,restart,status,install,uninstall,list,setup,migrate-legacy,enroll} ...
|
||||
|
||||
Manage the messaging gateway (Telegram, Discord, WhatsApp, Weixin, and more)
|
||||
|
||||
positional arguments:
|
||||
{run,start,stop,restart,status,install,uninstall,list,setup,migrate-legacy,enroll}
|
||||
run Run gateway in foreground (recommended for WSL,
|
||||
Docker, Termux)
|
||||
start Start the installed systemd/launchd background service
|
||||
stop Stop gateway service
|
||||
restart Restart gateway service
|
||||
status Show gateway status
|
||||
install Install gateway as a systemd/launchd background
|
||||
service
|
||||
uninstall Uninstall gateway service
|
||||
list List all profiles and their gateway status
|
||||
setup Configure messaging platforms
|
||||
migrate-legacy Remove legacy hermes.service units from pre-rename
|
||||
installs
|
||||
enroll Enroll this gateway with a relay connector (writes
|
||||
relay auth creds to .env)
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
--accept-hooks Auto-approve unseen shell hooks without a TTY prompt
|
||||
(equivalent to HERMES_ACCEPT_HOOKS=1 /
|
||||
hooks_auto_accept: true).
|
||||
===== hermes computer-use --help =====
|
||||
usage: hermes computer-use [-h] {install,status,doctor,permissions} ...
|
||||
|
||||
Install or check the cua-driver binary used by the `computer_use` toolset.
|
||||
Supported on macOS, Windows, and Linux. Use `hermes computer-use install` to
|
||||
fetch and run the upstream cua-driver installer. This is equivalent to the
|
||||
post-setup hook that `hermes tools` runs when you first enable the Computer
|
||||
Use toolset, and is a stable target for re-running the install if it didn't
|
||||
fire (e.g. when toggling the toolset on a returning-user setup). Use `hermes
|
||||
computer-use doctor` to run cua-driver's `health_report` MCP tool and surface
|
||||
its check matrix (TCC, bundle identity, version, platform support, ...) in
|
||||
human-readable form.
|
||||
|
||||
positional arguments:
|
||||
{install,status,doctor,permissions}
|
||||
install Install or repair the cua-driver binary
|
||||
(macOS/Windows/Linux)
|
||||
status Print whether cua-driver is installed and on PATH
|
||||
doctor Run cua-driver `health_report` and surface the check
|
||||
matrix
|
||||
permissions Check or grant macOS Accessibility + Screen Recording
|
||||
(macOS)
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
===== hermes doctor --help =====
|
||||
usage: hermes doctor [-h] [--fix] [--live] [--ack ADVISORY_ID]
|
||||
|
||||
Diagnose issues with Hermes Agent setup
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
--fix Attempt to fix issues automatically
|
||||
--live Opt-in: run one bounded, read-only real-call health probe
|
||||
per configured tool backend
|
||||
(Firecrawl/FAL/browser/MCP/TTS/STT) after the static
|
||||
checks. Makes real network calls.
|
||||
--ack ADVISORY_ID Acknowledge a security advisory by ID and exit. After
|
||||
ack, the advisory will no longer trigger startup banners.
|
||||
Run `hermes doctor` first to see active advisories and
|
||||
their IDs.
|
||||
===== hermes status --help =====
|
||||
usage: hermes status [-h] [--all] [--deep]
|
||||
|
||||
Display status of Hermes Agent components
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
--all Show all details (redacted for sharing)
|
||||
--deep Run deep checks (may take longer)
|
||||
===== hermes import-agent --help =====
|
||||
usage: hermes import-agent [-h] [--source SOURCE] [--dry-run] [--overwrite]
|
||||
[--yes]
|
||||
[{claude-code,codex}]
|
||||
|
||||
One-command import of another coding agent's setup into Hermes. Maps
|
||||
CLAUDE.md/AGENTS.md instructions, permission allowlists, MCP servers, skills,
|
||||
and memories into their Hermes equivalents. Always shows a preview before
|
||||
making changes. API keys and credentials are never imported — run 'hermes
|
||||
setup' for those.
|
||||
|
||||
positional arguments:
|
||||
{claude-code,codex} Which agent to import from (default: auto-detect
|
||||
~/.claude or ~/.codex)
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
--source SOURCE Path to the agent's config directory (default:
|
||||
~/.claude or ~/.codex)
|
||||
--dry-run Preview only — stop after showing what would be
|
||||
imported
|
||||
--overwrite Overwrite existing Hermes items on name conflicts
|
||||
(default: skip)
|
||||
--yes, -y Skip confirmation prompts
|
||||
@@ -1,33 +0,0 @@
|
||||
import json, subprocess, re
|
||||
|
||||
data = json.load(open("/home/hermes/syslog/drafts/scot-hermes-playbook/research/video-verification.json"))
|
||||
have = {r["videoId"] for r in data}
|
||||
extra = []
|
||||
for v in ["8GjyOQy19so", "zwqhemjHq3E"]:
|
||||
if v in have:
|
||||
continue
|
||||
url = f"https://www.youtube.com/watch?v={v}"
|
||||
oe = subprocess.run(["curl", "-s", f"https://www.youtube.com/oembed?url={url}&format=json"],
|
||||
capture_output=True, text=True, timeout=30)
|
||||
try:
|
||||
oej = json.loads(oe.stdout)
|
||||
o = {"status": "PASS", "title": oej.get("title"), "author": oej.get("author_name")}
|
||||
except Exception:
|
||||
o = {"status": "FAIL", "raw": oe.stdout[:200]}
|
||||
wp = subprocess.run(["curl", "-s", "-L", url,
|
||||
"-H", "User-Agent: Mozilla/5.0 (Windows NT 10.0) Chrome/124.0",
|
||||
"-H", "Accept-Language: en-US"], capture_output=True, text=True, timeout=30)
|
||||
html = wp.stdout
|
||||
pub = re.search(r'"publishDate":"([\d\-T:Z]+)"', html)
|
||||
dur = re.search(r'"lengthSeconds":"(\d+)"', html)
|
||||
views = re.search(r'"viewCount":"(\d+)"', html)
|
||||
rec = {"videoId": v, "oembed": o,
|
||||
"publishDate": pub.group(1) if pub else None,
|
||||
"lengthSeconds": int(dur.group(1)) if dur else None,
|
||||
"views": int(views.group(1)) if views else None}
|
||||
extra.append(rec)
|
||||
print(json.dumps(rec))
|
||||
|
||||
data.extend(extra)
|
||||
json.dump(data, open("/home/hermes/syslog/drafts/scot-hermes-playbook/research/video-verification.json", "w"), indent=2)
|
||||
print("total videos in ledger:", len(data))
|
||||
@@ -1,38 +0,0 @@
|
||||
import json, subprocess, re, sys
|
||||
|
||||
vids = ["9GpWELm3_XI","iqN6MVzpJTk","Ta2wg6xPaY4","8tpuky8HpXw","tP6yf22OJdI",
|
||||
"UWjh5Z4s8jY","5d02TYoOzfE","83nWNRKZTCE","6M2tItdARew","5_N84t1rUU0",
|
||||
"UTZhvPXnmwA","1UgXUjT-QtI","6GtF_uHbGhw","CwPUOVUdApE","sCa3BtpkziQ",
|
||||
"jmtpYUOr7_U","cu2fgknmemA","4sAmpcSOVEw","P2LIFtrRr2U"]
|
||||
|
||||
results = []
|
||||
for v in vids:
|
||||
url = f"https://www.youtube.com/watch?v={v}"
|
||||
oe = subprocess.run(["curl","-s",f"https://www.youtube.com/oembed?url={url}&format=json"],
|
||||
capture_output=True, text=True, timeout=30)
|
||||
try:
|
||||
oej = json.loads(oe.stdout)
|
||||
oembed = {"status":"PASS","title":oej.get("title"),"author":oej.get("author_name")}
|
||||
except Exception:
|
||||
oembed = {"status":"FAIL","raw":oe.stdout[:200]}
|
||||
# watch page for date + duration
|
||||
wp = subprocess.run(["curl","-s","-L",url,"-H","User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/124.0",
|
||||
"-H","Accept-Language: en-US,en;q=0.9"], capture_output=True, text=True, timeout=30)
|
||||
html = wp.stdout
|
||||
pub = re.search(r'"publishDate":"([\d\-T:Z]+)"', html)
|
||||
upd = re.search(r'"uploadDate":"([\d\-T:Z]+)"', html)
|
||||
dur = re.search(r'"lengthSeconds":"(\d+)"', html)
|
||||
views = re.search(r'"viewCount":"(\d+)"', html)
|
||||
results.append({
|
||||
"videoId": v, "oembed": oembed,
|
||||
"publishDate": pub.group(1) if pub else None,
|
||||
"uploadDate": upd.group(1) if upd else None,
|
||||
"lengthSeconds": int(dur.group(1)) if dur else None,
|
||||
"views": int(views.group(1)) if views else None,
|
||||
"watchpage_bytes": len(html),
|
||||
})
|
||||
print(json.dumps(results[-1]))
|
||||
|
||||
with open("/home/hermes/syslog/drafts/scot-hermes-playbook/research/video-verification.json","w") as f:
|
||||
json.dump(results, f, indent=2)
|
||||
print("saved video-verification.json")
|
||||
@@ -1,271 +0,0 @@
|
||||
[
|
||||
{
|
||||
"videoId": "9GpWELm3_XI",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Hermes Agent Explained In 5 Minutes",
|
||||
"author": "CodeHead"
|
||||
},
|
||||
"publishDate": "2026-05-23T08:00:27-07:00",
|
||||
"uploadDate": "2026-05-23T08:00:27-07:00",
|
||||
"lengthSeconds": 293,
|
||||
"views": 251275,
|
||||
"watchpage_bytes": 1419048
|
||||
},
|
||||
{
|
||||
"videoId": "iqN6MVzpJTk",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Hermes Agent by Nous Research: The Open-Source Agent Model Everyone Is Switching To",
|
||||
"author": "Praveen Govindaraj"
|
||||
},
|
||||
"publishDate": "2026-02-26T21:56:54-08:00",
|
||||
"uploadDate": "2026-02-26T21:56:54-08:00",
|
||||
"lengthSeconds": 193,
|
||||
"views": 3140,
|
||||
"watchpage_bytes": 1305120
|
||||
},
|
||||
{
|
||||
"videoId": "Ta2wg6xPaY4",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Learn 95% of Hermes Agent in 31 Minutes",
|
||||
"author": "Sharbel A."
|
||||
},
|
||||
"publishDate": "2026-08-09T07:00:19-07:00",
|
||||
"uploadDate": "2026-08-09T07:00:19-07:00",
|
||||
"lengthSeconds": 1888,
|
||||
"views": 129313,
|
||||
"watchpage_bytes": 1468130
|
||||
},
|
||||
{
|
||||
"videoId": "8tpuky8HpXw",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Better than OpenClaw? Testing Hermes Agent w/ Qwen 3 model",
|
||||
"author": "Tonbi's AI Garage"
|
||||
},
|
||||
"publishDate": "2026-03-11T07:00:14-07:00",
|
||||
"uploadDate": "2026-03-11T07:00:14-07:00",
|
||||
"lengthSeconds": 907,
|
||||
"views": 18167,
|
||||
"watchpage_bytes": 1326925
|
||||
},
|
||||
{
|
||||
"videoId": "tP6yf22OJdI",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Did Hermes Agent just kill OpenClaw? (full guide)",
|
||||
"author": "Alex Finn"
|
||||
},
|
||||
"publishDate": "2026-03-31T06:15:10-07:00",
|
||||
"uploadDate": "2026-03-31T06:15:10-07:00",
|
||||
"lengthSeconds": 835,
|
||||
"views": 132128,
|
||||
"watchpage_bytes": 1390199
|
||||
},
|
||||
{
|
||||
"videoId": "UWjh5Z4s8jY",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Hermes Co-Founder on Building an AI Agent That Improves Itself | Karan Malhotra",
|
||||
"author": "Peter Yang"
|
||||
},
|
||||
"publishDate": "2026-08-02T06:00:12-07:00",
|
||||
"uploadDate": "2026-08-02T06:00:12-07:00",
|
||||
"lengthSeconds": 2804,
|
||||
"views": 36613,
|
||||
"watchpage_bytes": 1386664
|
||||
},
|
||||
{
|
||||
"videoId": "5d02TYoOzfE",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Use This To Make The Hermes Agent Basically Free",
|
||||
"author": "AI LABS"
|
||||
},
|
||||
"publishDate": "2026-07-01T07:00:26-07:00",
|
||||
"uploadDate": "2026-07-01T07:00:26-07:00",
|
||||
"lengthSeconds": 788,
|
||||
"views": 54858,
|
||||
"watchpage_bytes": 1412833
|
||||
},
|
||||
{
|
||||
"videoId": "83nWNRKZTCE",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Meet the AI Agent That Grows With You Hermes Agent by Nous Research",
|
||||
"author": "Eddy Says Hi #EddySaysHi"
|
||||
},
|
||||
"publishDate": "2026-03-21T13:00:09-07:00",
|
||||
"uploadDate": "2026-03-21T13:00:09-07:00",
|
||||
"lengthSeconds": 366,
|
||||
"views": 465,
|
||||
"watchpage_bytes": 1254068
|
||||
},
|
||||
{
|
||||
"videoId": "6M2tItdARew",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "The AI Agent That Never Forgets: Meet Hermes Agent by Nous Research",
|
||||
"author": "Siggi"
|
||||
},
|
||||
"publishDate": "2026-03-11T13:53:17-07:00",
|
||||
"uploadDate": "2026-03-11T13:53:17-07:00",
|
||||
"lengthSeconds": 371,
|
||||
"views": 1199,
|
||||
"watchpage_bytes": 1267812
|
||||
},
|
||||
{
|
||||
"videoId": "5_N84t1rUU0",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Hermes Agent Fundamentals In 29 Minutes",
|
||||
"author": "Tina Huang"
|
||||
},
|
||||
"publishDate": "2026-07-20T09:37:02-07:00",
|
||||
"uploadDate": "2026-07-20T09:37:02-07:00",
|
||||
"lengthSeconds": 1780,
|
||||
"views": 462764,
|
||||
"watchpage_bytes": 1561142
|
||||
},
|
||||
{
|
||||
"videoId": "UTZhvPXnmwA",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Hermes Agent: Agents that grow with you |Episode #357|",
|
||||
"author": "Practical AI"
|
||||
},
|
||||
"publishDate": "2026-05-20T15:00:17-07:00",
|
||||
"uploadDate": "2026-05-20T15:00:17-07:00",
|
||||
"lengthSeconds": 2853,
|
||||
"views": 1888,
|
||||
"watchpage_bytes": 1329765
|
||||
},
|
||||
{
|
||||
"videoId": "1UgXUjT-QtI",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Hermes Agent: Why Everyone's Ditching OpenClaw in 2026",
|
||||
"author": "Luke Alexander AI"
|
||||
},
|
||||
"publishDate": "2026-03-26T07:10:29-07:00",
|
||||
"uploadDate": "2026-03-26T07:10:29-07:00",
|
||||
"lengthSeconds": 1083,
|
||||
"views": 13625,
|
||||
"watchpage_bytes": 1321848
|
||||
},
|
||||
{
|
||||
"videoId": "6GtF_uHbGhw",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Every Level of Hermes Agent Explained",
|
||||
"author": "Jack Roberts"
|
||||
},
|
||||
"publishDate": "2026-06-17T12:27:42-07:00",
|
||||
"uploadDate": "2026-06-17T12:27:42-07:00",
|
||||
"lengthSeconds": 1535,
|
||||
"views": 162977,
|
||||
"watchpage_bytes": 1577121
|
||||
},
|
||||
{
|
||||
"videoId": "CwPUOVUdApE",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Hermes Agent: The Ultimate Beginner\u2019s Guide",
|
||||
"author": "Metics Media"
|
||||
},
|
||||
"publishDate": "2026-04-24T06:59:04-07:00",
|
||||
"uploadDate": "2026-04-24T06:59:04-07:00",
|
||||
"lengthSeconds": 2228,
|
||||
"views": 118612,
|
||||
"watchpage_bytes": 1637578
|
||||
},
|
||||
{
|
||||
"videoId": "sCa3BtpkziQ",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "100 Days With Hermes Agent in 21 Minutes",
|
||||
"author": "Sharbel A."
|
||||
},
|
||||
"publishDate": "2026-06-17T07:47:26-07:00",
|
||||
"uploadDate": "2026-06-17T07:47:26-07:00",
|
||||
"lengthSeconds": 1279,
|
||||
"views": 57581,
|
||||
"watchpage_bytes": 1454230
|
||||
},
|
||||
{
|
||||
"videoId": "jmtpYUOr7_U",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Hermes Agent Just Killed OpenClaw (Full Tutorial)",
|
||||
"author": "Leon van Zyl"
|
||||
},
|
||||
"publishDate": "2026-04-28T04:19:38-07:00",
|
||||
"uploadDate": "2026-04-28T04:19:38-07:00",
|
||||
"lengthSeconds": 1199,
|
||||
"views": 15988,
|
||||
"watchpage_bytes": 1510488
|
||||
},
|
||||
{
|
||||
"videoId": "cu2fgknmemA",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Hermes Agent The 24/7 Self-Evolving AI Agent!",
|
||||
"author": "WorldofAI"
|
||||
},
|
||||
"publishDate": "2026-04-07T00:01:34-07:00",
|
||||
"uploadDate": "2026-04-07T00:01:34-07:00",
|
||||
"lengthSeconds": 555,
|
||||
"views": 46889,
|
||||
"watchpage_bytes": 1545788
|
||||
},
|
||||
{
|
||||
"videoId": "4sAmpcSOVEw",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Hermes Agent - Crash Course for Beginners (AI Agent)",
|
||||
"author": "Adrian Twarog"
|
||||
},
|
||||
"publishDate": "2026-07-21T01:20:41-07:00",
|
||||
"uploadDate": "2026-07-21T01:20:41-07:00",
|
||||
"lengthSeconds": 1338,
|
||||
"views": 46484,
|
||||
"watchpage_bytes": 1585548
|
||||
},
|
||||
{
|
||||
"videoId": "P2LIFtrRr2U",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Hermes Agent: New FREE OpenClaw Alternative!",
|
||||
"author": "Julian Goldie SEO"
|
||||
},
|
||||
"publishDate": "2026-03-09T14:00:32-07:00",
|
||||
"uploadDate": "2026-03-09T14:00:32-07:00",
|
||||
"lengthSeconds": 735,
|
||||
"views": 9975,
|
||||
"watchpage_bytes": 1353286
|
||||
},
|
||||
{
|
||||
"videoId": "8GjyOQy19so",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Hermes Agent Full Tutorial INSTALLATION + USECASES",
|
||||
"author": "CodeHead"
|
||||
},
|
||||
"publishDate": "2026-05-14T08:00:23-07:00",
|
||||
"lengthSeconds": 467,
|
||||
"views": 64285
|
||||
},
|
||||
{
|
||||
"videoId": "zwqhemjHq3E",
|
||||
"oembed": {
|
||||
"status": "PASS",
|
||||
"title": "Hermes Agent vs OpenClaw",
|
||||
"author": "Sharbel A."
|
||||
},
|
||||
"publishDate": "2026-04-20T07:14:00-07:00",
|
||||
"lengthSeconds": 928,
|
||||
"views": 35360
|
||||
}
|
||||
]
|
||||
@@ -1,10 +0,0 @@
|
||||
import re, sys
|
||||
|
||||
html = open(sys.argv[1], encoding='utf-8', errors='ignore').read()
|
||||
ids = re.findall(r'"videoRenderer":\{"videoId":"([\w-]{11})"', html)
|
||||
print("videoRenderer hits:", len(set(ids)))
|
||||
for vid in dict.fromkeys(ids):
|
||||
m = re.search(r'"videoId":"%s".{0,3000}?"title":\{"runs":\[\{"text":"(.*?)"\}' % vid, html, re.S)
|
||||
ch = re.search(r'"videoId":"%s".{0,6000}?"ownerText":\{"runs":\[\{"text":"(.*?)"' % vid, html, re.S)
|
||||
dur = re.search(r'"videoId":"%s".{0,4000}?"lengthText":\{"accessibility".{0,400}?"simpleText":"(.*?)"' % vid, html, re.S)
|
||||
print((vid, m.group(1) if m else "?", ch.group(1) if ch else "?", dur.group(1) if dur else "?"))
|
||||
@@ -1,42 +0,0 @@
|
||||
# 06 — Sources
|
||||
|
||||
Access date for ALL entries: **2026-09-11** (via citation ledger `sources.py`; doc URLs additionally confirmed HTTP 200 by curl -L).
|
||||
|
||||
## Official docs (hermes-agent.nousresearch.com)
|
||||
| # | URL | Supported |
|
||||
|---|-----|-----------|
|
||||
| 1 | https://hermes-agent.nousresearch.com/docs | Docs index; overall feature map |
|
||||
| 3 | https://hermes-agent.nousresearch.com/docs/user-guide/configuration | Config sections, SOUL.md, checkpoints |
|
||||
| 4 | https://hermes-agent.nousresearch.com/docs/reference/slash-commands | Slash command registry (03) |
|
||||
| 5 | https://hermes-agent.nousresearch.com/docs/reference/tools-reference | Toolset inventory (02 §6) |
|
||||
| 6 | https://hermes-agent.nousresearch.com/docs/user-guide/features/cron | Cron surface (02 §9) |
|
||||
| 7 | https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban | Kanban surface (02 §8) |
|
||||
| 8 | https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp | MCP surface + `hermes mcp serve` (02 §5, 04 P3) |
|
||||
| 9 | https://hermes-agent.nousresearch.com/docs/user-guide/features/memory | Memory surface (02 §2) |
|
||||
| 10 | https://hermes-agent.nousresearch.com/docs/user-guide/profiles | Profiles (02 §13) |
|
||||
| 11 | https://hermes-agent.nousresearch.com/docs/integrations/providers | Model/provider routing (02 §12) |
|
||||
| 12 | https://hermes-agent.nousresearch.com/docs/user-guide/messaging/ | Gateway platforms (02 §15) |
|
||||
| 13 | https://hermes-agent.nousresearch.com/docs/user-guide/features/curator | Skill maintenance (02 §3) |
|
||||
| 14 | https://hermes-agent.nousresearch.com/docs/reference/cli-commands | CLI command index cross-check (03) |
|
||||
| 15 | https://hermes-agent.nousresearch.com/docs/reference/skills-catalog | Skills catalog (02 §3) |
|
||||
|
||||
## GitHub
|
||||
| # | URL | Supported |
|
||||
|---|-----|-----------|
|
||||
| 2 | https://github.com/nousresearch/hermes-agent | Repo identity, learning-loop description (01, 02) |
|
||||
|
||||
## Local primary sources (not web URLs; verified on this host)
|
||||
- Live CLI help output, Hermes Agent v0.21.1 (2026.9.7), reference install (Syslog kagentz): `hermes --help` + `hermes {chat,model,config,cron,kanban,skills,sessions,mcp,profile,memory,tools,project,gateway,computer-use,doctor,status,import-agent} --help` → raw dump `cli-help-dump.txt` (577 lines). Basis for all VERIFIED-LIVE tags in 01/02/03/04.
|
||||
- `/home/hermes/.hermes/skills/autonomous-ai-agents/delegate-coding-agent/SKILL.md` (v1.0.0) + `references/claude-code.md` (v2.2.1) → 04 Patterns 1-2, 01 Claude Code column.
|
||||
- `/home/hermes/.hermes/skills/autonomous-ai-agents/merge-reconciler/SKILL.md` → 04 Pattern 2.
|
||||
- `/home/hermes/.hermes/skills/autonomous-ai-agents/computer-use/SKILL.md` (v2.0.0) → 04 Pattern 5, 02 §11.
|
||||
|
||||
## YouTube verification
|
||||
- YouTube search results pages (scraped 2026-09-11): `https://www.youtube.com/results?search_query=hermes+agent+nous+research` and `...nous+research+hermes+agent+official`
|
||||
- oEmbed endpoint per video: `https://www.youtube.com/oembed?url=https://www.youtube.com/watch?v=<ID>&format=json` — all 21 checked IDs returned PASS (HTTP 200, title/author match). Raw evidence incl. publishDate/lengthSeconds/viewCount per watch page: `video-verification.json`.
|
||||
- 17 listed in 05-videos.md + 4 spares; 21/21 pass, 0 fail.
|
||||
|
||||
## Explicit gaps (could not close)
|
||||
1. No official Nous Research-produced tutorial video was found — video list is third-party ecosystem content (disclosed in 05).
|
||||
2. Slash commands were verified DOC-ONLY (https://hermes-agent.nousresearch.com/docs/reference/slash-commands); they require an interactive session to exercise, which this headless run does not have. CLI equivalents were verified live.
|
||||
3. `hermes-agent.nousresearch.com/docs/developer-guide/` returned 404 — developer docs live in-repo (`AGENTS.md` in the GitHub repo), not as a docs site section.
|
||||
@@ -1,6 +1,4 @@
|
||||
---
|
||||
report_only_agents:
|
||||
- koby # ⛔ KOBY IS NEVER REPAIRED (Rule 17, 2026-08-17) — detect + report, never fix on .129
|
||||
kind: responsibility
|
||||
name: disk-gc-threat-response
|
||||
description: >
|
||||
@@ -13,7 +11,6 @@ description: >
|
||||
id: 067NV8KJ03ZG71S44N41F31022
|
||||
version: 1.0.0
|
||||
---
|
||||
---
|
||||
|
||||
# Disk GC & Threat Response
|
||||
|
||||
@@ -38,7 +35,8 @@ Docker hosts get special attention:
|
||||
| All other CTs | — | LOW — no Docker | apt clean, log rotate |
|
||||
| GPU bare metal (.8, .110) | — | LOW — no Docker on GPU hosts | log rotate |
|
||||
|
||||
> **Note:** CT 118 is now jdownloader (active on storepve). CT 101 (llm-gpu) → bare metal .8, CT 103 (ocu-llm) → bare metal .110.
|
||||
> **Decommissioned:** CT 118 (jitsi) — intentionally stopped, not scanned.
|
||||
> **Migrated:** CT 101 (llm-gpu) → bare metal .8, CT 103 (ocu-llm) → bare metal .110.
|
||||
|
||||
## Threat Levels
|
||||
|
||||
@@ -277,10 +275,10 @@ one-off GPU builds. No automated post-migration cleanup was in place.
|
||||
### CT Access (via pct-run)
|
||||
| CT | Name | Node | Status |
|
||||
|----|------|------|--------|
|
||||
| 100 | abiba | minipve | local |
|
||||
| 102 | adguard | minipve | ✅ reachable |
|
||||
| 100 | abiba | amdpve | local |
|
||||
| 102 | adguard | acerpve | ✅ reachable |
|
||||
| 104 | authentik | minipve | ✅ reachable |
|
||||
| 105 | kagentz | minipve | ✅ reachable |
|
||||
| 105 | kagentz | amdpve | ✅ reachable |
|
||||
| 106 | ra-h-os | storepve | ✅ reachable |
|
||||
| 107 | pbs | storepve | ✅ reachable |
|
||||
| 108 | media | storepve | ✅ reachable |
|
||||
@@ -288,6 +286,7 @@ one-off GPU builds. No automated post-migration cleanup was in place.
|
||||
| 111 | tdunna | amdpve | ✅ reachable |
|
||||
| 112 | tanko | amdpve | ✅ reachable |
|
||||
| 113 | baggy | amdpve | ✅ reachable |
|
||||
| 114 | mumuni | minipve | ✅ reachable |
|
||||
| 115 | scottdenya | amdpve | ✅ reachable |
|
||||
| 116 | syslog-api | minipve | ✅ reachable |
|
||||
| 117 | zulip | storepve | ✅ reachable |
|
||||
@@ -304,4 +303,4 @@ one-off GPU builds. No automated post-migration cleanup was in place.
|
||||
|------|-----|------|--------|
|
||||
| docker-vm | 192.168.68.7 | 16 Docker containers, 4 stacks | ✅ reachable |
|
||||
|
||||
> **Note:** CT 118 is now jdownloader (active on storepve). CT 119 (infisical-vault) added on minipve.\n> **Migrated:** CT 101 → .8, CT 103 → .110 (bare metal GPU).\n> **KVM VM:** CT 109 (docker-vm) is a KVM VM, not LXC — access via SSH .7.
|
||||
> **Decommissioned:** CT 118 (jitsi) — intentionally stopped.\n> **Migrated:** CT 101 → .8, CT 103 → .110 (bare metal GPU).\n> **KVM VM:** CT 109 (docker-vm) is a KVM VM, not LXC — access via SSH .7.
|
||||
+1
-35
@@ -13,7 +13,7 @@ the description:
|
||||
|
||||
1. **What system does this contract touch?** Name the hosts, CTs, containers,
|
||||
and services explicitly. "The inference fleet" is vague. "GPU .8 (RTX 3090,
|
||||
qwen), .110 (RTX 5070, gemma), .15 (Strix Halo, strix-moe), and LiteLLM on CT
|
||||
qwen), .110 (RTX 5070, gemma), .15 (Strix Halo, ornith), and LiteLLM on CT
|
||||
116" is specific.
|
||||
|
||||
2. **Who runs this contract, and when?** State the agent, the trigger (cron,
|
||||
@@ -211,40 +211,6 @@ Errors tell the operator what went wrong and what to do about it. Be specific:
|
||||
Check router /health/unified at http://192.168.68.116/health/unified instead."
|
||||
```
|
||||
|
||||
### Report provenance
|
||||
|
||||
Every report a contract produces must lead with the **absolute path the probe
|
||||
executed from** — `pwd -P`, or the running script's absolute path. A live-state
|
||||
report without provenance is unactionable: a report from a stale copy (a worktree
|
||||
clone, a retired cron entry, a diverged consumer) looks identical to a live
|
||||
fault, and the team burns rounds repairing healthy infrastructure. This is not
|
||||
optional. The 2026-09-09 probe-drift rounds cost three false `DEGRADED` reports
|
||||
because a stale consumer probed the wrong port and nothing in the report said
|
||||
where it ran.
|
||||
|
||||
Pair it with the **scoped any-HTTP-response liveness rule**: for unauthenticated
|
||||
or auth-gated endpoints — where any HTTP answer proves a listener is up (the
|
||||
PVE API's `401`, LiteLLM health's `301` redirect) — a probe is ALIVE on ANY HTTP
|
||||
status, including `301` redirects and `401`/`403` auth challenges. **DOWN =
|
||||
connection refused (`000`) or timeout only.**
|
||||
|
||||
Probes whose success condition is specifically a bare `200` are NOT covered by
|
||||
the any-HTTP rule. On those — authenticated probes such as the Zulip message
|
||||
POST and the router `/health` — an unexpected status (`401`/`403` from a bad or
|
||||
missing credential, `5xx`, or anything other than the expected `200`) is an
|
||||
**ALERT**, not "alive".
|
||||
|
||||
```markdown
|
||||
**Report format**: Begin every report with the absolute execution path
|
||||
(`pwd -P` / script path). On auth-gated endpoints, alive = ANY HTTP status and
|
||||
DOWN = `000`/timeout only; on probes whose expected result is `200`, any other
|
||||
status is an alert.
|
||||
```
|
||||
|
||||
The lint pipeline enforces the provenance clause: any contract with a
|
||||
`**Report format**` line must state an absolute path (`pwd -P`, `absolute path`,
|
||||
or `executed from`).
|
||||
|
||||
### Comments
|
||||
|
||||
Comments in contracts explain WHY, not WHAT. The execution steps say what to
|
||||
|
||||
@@ -1,278 +0,0 @@
|
||||
# Probe-drift round 2 — per-leg before/after evidence
|
||||
|
||||
**Date:** 2026-09-10
|
||||
**Worktree (absolute execution path):** `/root/.treehouse/prose-contracts-9ce5f3/3/prose-contracts`
|
||||
**Branch:** `fm/probe-drift-round2-20260909`
|
||||
|
||||
Every command below was run from the absolute path above; output is pasted
|
||||
verbatim. This is the evidence trail for the four scoped corrections; it is not
|
||||
a contract (never `prose run` it).
|
||||
|
||||
---
|
||||
|
||||
## Leg 1 — agent-health-check (item 1)
|
||||
|
||||
**Before** — from `/root/.treehouse/prose-contracts-9ce5f3/3/prose-contracts`,
|
||||
`python3 scripts/agent-health-check.py --no-deploy` (v2, base of this branch):
|
||||
|
||||
```
|
||||
🏥 Agent Health Check v2 — 2026-09-10 01:16 UTC
|
||||
|
||||
🔑 LiteLLM Keys:
|
||||
✅ tanko: key valid → syslog-auto
|
||||
✅ abiba: key valid → syslog-auto
|
||||
✅ koby: key valid → syslog-auto
|
||||
✅ koonimo: key valid → syslog-auto
|
||||
|
||||
🎮 GPU Port Health:
|
||||
✅ gpu-rtx3090 (.8): healthy (pid=472206)
|
||||
✅ gpu-rtx5070 (.110): healthy (pid=207601)
|
||||
✅ gpu-strixhalo (.15): healthy (pid=4098872)
|
||||
|
||||
🤖 Agent Gateways:
|
||||
✅ tanko: DSH (DeepSeek Harness) — no Hermes gateway since 2026-08-27 (CT 112, SSH OK)
|
||||
⚠️ abiba: gw=no-state-file zulip=? streaming=no errors_10m=0 pid=?
|
||||
✅ koby: gw=running zulip=connected streaming=no errors_10m=0 pid=360900
|
||||
✅ koonimo: gw=running zulip=connected streaming=no errors_10m=0 pid=155125
|
||||
|
||||
🖥️ CT Liveness:
|
||||
✅ tanko (CT 112 on amdpve): running
|
||||
✅ abiba (CT 100 on minipve): running
|
||||
❌ koby (CT 111 on amdpve): PVE UNREACHABLE
|
||||
✅ koonimo (CT 113 on amdpve): running
|
||||
|
||||
📝 Config Integrity:
|
||||
⏭️ tanko: DSH — no Hermes config.yaml since 2026-08-27
|
||||
✅ abiba: config.yaml valid YAML
|
||||
✅ koby: config.yaml valid YAML
|
||||
✅ koonimo: config.yaml valid YAML
|
||||
|
||||
🔌 Wrapper/CLI Integrity:
|
||||
⏭️ tanko: DSH — no hermes CLI wrapper since 2026-08-27
|
||||
⚠️ abiba: wrapper infisical path may be wrong (infisical at /usr/bin/infisical)
|
||||
❌ abiba: hermes-real NOT FOUND (wrapper broken)
|
||||
⚠️ abiba: .env may be missing LITELLM_API_KEY entry
|
||||
⚠️ koby: wrapper infisical path may be wrong (infisical at /usr/bin/infisical)
|
||||
❌ koby: hermes-real NOT FOUND (wrapper broken)
|
||||
✅ koby: wrapper + .env key present
|
||||
⚠️ koonimo: wrapper infisical path may be wrong (infisical at /usr/bin/infisical)
|
||||
✅ koonimo: wrapper + .env key present
|
||||
|
||||
🔐 Vault Secrets:
|
||||
✅ tanko: vault TANKO_LITELLM_API_KEY=sk-...x6uw
|
||||
✅ koby: vault KOBY_LITELLM_API_KEY=sk-...jxlg
|
||||
✅ koonimo: vault KOONIMO_LITELLM_API_KEY=sk-...Y0KQ
|
||||
|
||||
❌ 6 FAILURE(S): ct-unreachable:koby:192.168.68.15 | wrapper-infisical-path:abiba | wrapper-no-hermes-real:abiba | wrapper-infisical-path:koby | wrapper-no-hermes-real:koby | wrapper-infisical-path:koonimo
|
||||
```
|
||||
|
||||
Root causes (all stale expectations; no live fault):
|
||||
|
||||
| Failure | Why it was stale |
|
||||
|---|---|
|
||||
| `ct-unreachable:koby:192.168.68.15` | CT 111 (tdunna/koby) runs on **storepve (.6)**, not amdpve (.15). |
|
||||
| `wrapper-*:abiba` | Abiba is pi-only since the harness purge. `/root/.local/bin/hermes` is a dangling symlink; no `hermes-real`, no `~/.hermes/.env`. |
|
||||
| `wrapper-*:koby` | Koby is **report-only** (captain ruling 2026-08-17, Rule 17): detect and report, never repair — its legs must not count as fleet failures. Koby's wrapper is also the genuine no-infisical case: it sources `~/.hermes/.env` rather than `/usr/bin/infisical`, which the check now accepts. |
|
||||
| `wrapper-infisical-path:koonimo` | Koonimo's wrapper **does** reference `/usr/bin/infisical` — but past the old check's `head -20` window, so the check looked for the path in the wrong slice and false-failed. The fix that mattered was reading the full wrapper body (and then verifying any absolute infisical path it finds actually exists). |
|
||||
|
||||
**After** — same absolute path, `python3 scripts/agent-health-check.py --no-deploy` (v4):
|
||||
|
||||
```
|
||||
$ pwd -P
|
||||
/root/.treehouse/prose-contracts-9ce5f3/3/prose-contracts
|
||||
$ python3 scripts/agent-health-check.py --no-deploy
|
||||
🏥 Agent Health Check v4 — 2026-09-10 01:22 UTC
|
||||
📍 executed from: script=/root/.treehouse/prose-contracts-9ce5f3/3/prose-contracts/scripts/agent-health-check.py cwd=/root/.treehouse/prose-contracts-9ce5f3/3/prose-contracts
|
||||
|
||||
🔑 LiteLLM Keys:
|
||||
✅ tanko: key valid → syslog-auto
|
||||
✅ abiba: key valid → syslog-auto
|
||||
✅ koby: key valid → syslog-auto
|
||||
✅ koonimo: key valid → syslog-auto
|
||||
|
||||
🎮 GPU Port Health:
|
||||
✅ gpu-rtx3090 (.8): healthy (pid=472206)
|
||||
✅ gpu-rtx5070 (.110): healthy (pid=207601)
|
||||
✅ gpu-strixhalo (.15): healthy (pid=4098872)
|
||||
|
||||
🤖 Agent Gateways:
|
||||
✅ tanko: DSH (DeepSeek Harness) — no Hermes gateway since 2026-08-27 (CT 112, SSH OK)
|
||||
✅ abiba: pi-only runtime — no Hermes gateway since the harness purge (CT 100, SSH OK)
|
||||
🔍 koby: REPORT-ONLY mode (diagnostic only, no repairs on .129)
|
||||
✅ koby: gateway running (pid=360900, report-only mode)
|
||||
✅ koonimo: gw=running zulip=connected streaming=no errors_10m=0 pid=155125
|
||||
|
||||
🖥️ CT Liveness:
|
||||
✅ tanko (CT 112 on amdpve): running
|
||||
✅ abiba (CT 100 on minipve): running
|
||||
✅ koby (CT 111 on storepve): running
|
||||
✅ koonimo (CT 113 on amdpve): running
|
||||
|
||||
📝 Config Integrity:
|
||||
⏭️ tanko: DSH — no Hermes config.yaml since 2026-08-27
|
||||
⏭️ abiba: pi-only runtime — no Hermes config.yaml since the harness purge
|
||||
✅ koby: config.yaml valid YAML
|
||||
✅ koonimo: config.yaml valid YAML
|
||||
|
||||
🔌 Wrapper/CLI Integrity:
|
||||
⏭️ tanko: DSH — no hermes CLI wrapper since 2026-08-27
|
||||
⏭️ abiba: pi-only runtime — no hermes CLI wrapper since the harness purge
|
||||
ℹ️ koby: wrapper resolves creds without infisical (e.g. ~/.hermes/.env) — OK
|
||||
❌ koby: hermes-real NOT FOUND (wrapper broken)
|
||||
🔍 report-only (koby): wrapper-no-hermes-real:koby — reported, not counted/repaired
|
||||
✅ koby: wrapper + .env key present
|
||||
✅ koonimo: wrapper infisical path OK
|
||||
✅ koonimo: wrapper + .env key present
|
||||
|
||||
🔐 Vault Secrets:
|
||||
✅ tanko: vault TANKO_LITELLM_API_KEY=sk-...x6uw
|
||||
✅ koby: vault KOBY_LITELLM_API_KEY=sk-...jxlg
|
||||
✅ koonimo: vault KOONIMO_LITELLM_API_KEY=sk-...Y0KQ
|
||||
|
||||
✅ All checks passed
|
||||
exit=0
|
||||
```
|
||||
|
||||
**Live vantage proof** (same worktree):
|
||||
|
||||
```
|
||||
$ ssh root@192.168.68.15 "pct status 111"
|
||||
Configuration file 'nodes/amdpve/lxc/111.conf' does not exist
|
||||
$ ssh root@192.168.68.6 "pct status 111; pct list | grep '^ *111'"
|
||||
status: running
|
||||
111 running tdunna
|
||||
$ ssh root@192.168.68.129 "hostname"
|
||||
tdunna
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Leg 2 — infrastructure-monitoring PVE API (item 2)
|
||||
|
||||
**Before** — the contract's probe, aimed at the monitoring host CT 116:
|
||||
|
||||
```
|
||||
$ curl -s -o /dev/null -w '%{http_code}' https://192.168.68.116:8006/api2/json
|
||||
000
|
||||
```
|
||||
|
||||
CT 116 runs no `pveproxy`, so it never answers on `:8006`. The probe target was
|
||||
wrong, which is what read as PVE-API `000`.
|
||||
|
||||
**After** — probing the five real cluster nodes (`:8006/api2/json/version`),
|
||||
alive under the any-HTTP-response rule (`401` = up, unauthenticated):
|
||||
|
||||
```
|
||||
$ for node in 192.168.68.9 192.168.68.5 192.168.68.15 192.168.68.6 192.168.68.12; do
|
||||
printf '%s:8006 -> %s\n' "$node" "$(curl -sk -o /dev/null -w '%{http_code}' --connect-timeout 5 "https://$node:8006/api2/json/version")"
|
||||
done
|
||||
192.168.68.9:8006 -> 401
|
||||
192.168.68.5:8006 -> 401
|
||||
192.168.68.15:8006 -> 401
|
||||
192.168.68.6:8006 -> 401
|
||||
192.168.68.12:8006 -> 401
|
||||
```
|
||||
|
||||
`401` on every node = alive by design. `DOWN` is `000`/timeout only. (The
|
||||
contract's LiteLLM probe was the same class: `/litellm/health` answers `301` →
|
||||
`/litellm/health/liveliness`, so it is now specified as any-HTTP too.)
|
||||
|
||||
---
|
||||
|
||||
## Leg 3 — gpu-monitor GPU probes (item 3)
|
||||
|
||||
**Before** — the false alarm came from probing bare port 80 on GPU hosts:
|
||||
|
||||
```
|
||||
$ curl -s -o /dev/null -w '%{http_code}' http://192.168.68.8/health
|
||||
000
|
||||
$ curl -s -o /dev/null -w '%{http_code}' http://192.168.68.110/health
|
||||
000
|
||||
```
|
||||
|
||||
Nothing listens on GPU port 80, so the monitor reported
|
||||
`DEGRADED — GPU-rtx3090 000, GPU-rtx5070 000` three times on 2026-09-09.
|
||||
|
||||
**After** — the real endpoints answer:
|
||||
|
||||
```
|
||||
$ curl -s -o /dev/null -w '%{http_code}' http://192.168.68.8:8080/health
|
||||
200
|
||||
$ curl -s -o /dev/null -w '%{http_code}' http://192.168.68.110:8080/health
|
||||
200
|
||||
$ curl -s -o /dev/null -w '%{http_code}' http://192.168.68.15:8080/health
|
||||
200
|
||||
$ curl -s -o /dev/null -w '%{http_code}' http://192.168.68.116/health/unified
|
||||
301 # Location: http://192.168.68.116/gpu/gpu-data — the same payload
|
||||
$ curl -s -o /dev/null -w '%{http_code}' -L http://192.168.68.116/health/unified
|
||||
200
|
||||
```
|
||||
|
||||
`301` is healthy under the any-HTTP-response rule. The contract now requires GPU
|
||||
health on `:8080` (or router `/health/unified`) and forbids bare port 80 on a
|
||||
GPU host.
|
||||
|
||||
---
|
||||
|
||||
## Leg 4 — report provenance (item 4)
|
||||
|
||||
Every contract report must now lead with the absolute path it executed from.
|
||||
`docs/AUTHORING-GUIDE.md` documents the rule and `scripts/prose-lint.sh`
|
||||
enforces it:
|
||||
|
||||
```
|
||||
$ pwd -P
|
||||
/root/.treehouse/prose-contracts-9ce5f3/3/prose-contracts
|
||||
$ bash scripts/prose-lint.sh
|
||||
✅ Report provenance present in all report-format contracts
|
||||
...
|
||||
✅ LINT PASSED (12 warning(s))
|
||||
```
|
||||
|
||||
The health script prints `📍 executed from: script=… cwd=…` and includes
|
||||
`execution_path`/`cwd` in `--json` output.
|
||||
|
||||
---
|
||||
|
||||
## Full suite
|
||||
|
||||
```
|
||||
$ pwd -P
|
||||
/root/.treehouse/prose-contracts-9ce5f3/3/prose-contracts
|
||||
$ python3 -m pytest -q
|
||||
24 passed
|
||||
$ shellcheck scripts/prose-lint.sh
|
||||
(clean)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Follow-up findings (observed, intentionally NOT changed here)
|
||||
|
||||
These are adjacent stale expectations discovered while verifying the four
|
||||
scoped legs. Each touches a CRITICAL/HIGH-sensitivity artifact or an unrelated
|
||||
script, so it is recorded for the captain/verify mate rather than silently
|
||||
repaired.
|
||||
|
||||
1. **`infrastructure-control.prose.md` (CRITICAL) CT 111 node assignment.**
|
||||
Lines ~109 and ~615 place `tdunna` (CT 111, koby) on **amdpve**. Live
|
||||
verification on 2026-09-10 shows `pct status 111` = `running` on
|
||||
**storepve (.6)** and `Configuration file 'nodes/amdpve/lxc/111.conf' does
|
||||
not exist` on .15. `agent-health-check.py` now carries the live-verified
|
||||
`storepve` mapping (the script is not the topology source of truth); the
|
||||
CRITICAL contract itself needs an authorized correction.
|
||||
2. **Strix Halo `:8080` firewall claim is stale.** `prose-ai-review.sh`
|
||||
ground-truth rule #4 and `gpu-monitor.prose.md` say `:8080` is firewalled to
|
||||
`.116` only and `.24` cannot probe it. Live on .15:
|
||||
`-A INPUT -s 192.168.68.24/32 -p tcp --dport 8080 -j ACCEPT`, and a probe
|
||||
from .24 returns `200`. The contract keeps routing Strix via the router
|
||||
(safe), but the claim no longer matches iptables.
|
||||
3. **`contract-registry.yaml` references `agent-health-check.prose.md`**, which
|
||||
does not exist in the repo. The registry entry (with `koby_action: skip_heal`)
|
||||
is aspirational/stale.
|
||||
4. **Pre-existing script defects, untouched:** `scripts/pm2-self-heal.sh` has a
|
||||
bash syntax error at lines 19–20 (`bash -n` fails), and `shellcheck` fails on
|
||||
five untouched scripts (`netbird-add-domain.sh`, `pct-run.sh`,
|
||||
`pm2-self-heal.sh`, `prose-ai-review.sh`, `swap-gpu-dense-model.sh`).
|
||||
`scripts/prose-lint.sh` — the one shell file touched here — is now
|
||||
shellcheck-clean.
|
||||
+75
-169
@@ -5,21 +5,15 @@ description: >
|
||||
Manages the GPU inference fleet across all hosts. Handles model deployment,
|
||||
registration, health checks, LiteLLM sync, agent key management, GPU
|
||||
saturation watchdog, Prometheus/Grafana monitoring, and self-healing.
|
||||
UPDATED 2026-07-15: Stable role-based aliases introduced: strix-moe,
|
||||
gpu-dense, gpu-light. These never change — only the underlying model does.
|
||||
Strix Halo: strix-moe → unsloth/Qwen3.6-35B-A3B-MTP (UD-Q4_K_M, 22GB).
|
||||
RTX 5070: gemma-4-12b Q4_K_M → IQ4_NL + MTP draft (122 tok/s, 2x faster).
|
||||
UPDATED 2026-07-17: Context reduced fleet-wide from 256K to 128K for stability.
|
||||
Strix Halo model swapped to qwen3.6-35B-udq4 (22GB, strix-moe alias).
|
||||
Instability observed near 100K at 256K (now all GPUs at 128K). 128K is the stable ceiling.
|
||||
For larger context needs → fall back to external providers (deepseek).
|
||||
VRAM headroom improved: RTX 3090 ~70%, RTX 5070 ~65%.
|
||||
Current as of 2026-07-08: context reduced to 128K on NVIDIA GPUs, parallel 2
|
||||
on all GPUs, LiteLLM timeouts tuned (gemma 25→120s, qwen 40→90s), router fully
|
||||
deprecated — nginx routes /v1 → LiteLLM directly.
|
||||
agent: abiba
|
||||
triggers:
|
||||
- on model add/remove
|
||||
- on GPU health degradation
|
||||
- on agent key rotation
|
||||
- on harness container restart (LiteLLM reloads its model list)
|
||||
- on router restart (roster must be loaded)
|
||||
---
|
||||
|
||||
## Maintains
|
||||
@@ -36,96 +30,55 @@ triggers:
|
||||
- prometheus: { status: "running", targets: 5 } — Scrapes GPU :9400 exporters + LiteLLM
|
||||
- port_conflict_detection: { status: "active" } — All 3 GPU wrappers detect ghost processes before binding
|
||||
|
||||
## Fleet Topology (Current — 2026-09-11, router decommissioned)
|
||||
## Fleet Topology (Current — June 2026)
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ CT 116 (192.168.68.116) — Inference Harness Host │
|
||||
│ │
|
||||
│ nginx:80 (entrypoint) │
|
||||
│ ├─ /v1/* → harness-litellm:4000 (API requests) │
|
||||
│ ├─ /v1/* → harness-litellm:4000 (API requests) │
|
||||
│ ├─ /admin/* → harness-litellm:4000 (admin endpoints) │
|
||||
│ ├─ /dashboard/ → harness-dashboard:3000 (harness UI) │
|
||||
│ ├─ /litellm/* → harness-litellm:4000 (LiteLLM UI + API) │
|
||||
│ ├─ /litellm/* → harness-litellm:4000 (LiteLLM UI + API) │
|
||||
│ ├─ /health/* → harness-litellm:4000 (health probes) │
|
||||
│ └─ /gpu/* → 192.168.68.24:9100 (fleet monitor) │
|
||||
│ │
|
||||
│ Containers: │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ LiteLLM │ │Dashboard │ │ Grafana │ │
|
||||
│ │ :4000 │ │ :3000 │ │ :3001 │ │
|
||||
│ │ keys+sync│ │ harness │ │Prometheus│ │
|
||||
│ │ fallback │ │ UI │ │ data src │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │PostgreSQL│ │ Redis │ │Prometheus│ │
|
||||
│ │ :5432 │ │ :6379 │ │ :9090 │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ │
|
||||
└───────┼──────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─┴─────────────┬───────────────┬───────────────┐
|
||||
│ │ │ │
|
||||
┌─────▼──────┐ ┌─────▼──────┐ ┌─────▼──────┐ ┌─────▼──────┐
|
||||
│ CT 8 │ │ CT 110 │ │ CT 15 │ │ pi (.24) │
|
||||
│ RTX 3090 │ │ RTX 5070 │ │ Strix Halo │ │ GPU Monitor│
|
||||
│ 24GB │ │ 12GB │ │ 64GB UMA │ │ :9100 │
|
||||
│ :8080 │ │ :9400 exp │ │ :9400 exp │ │ :9401 │
|
||||
└────────────┘ └────────────┘ └────────────┘ └────────────┘
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ LiteLLM │ │ Router │ │Dashboard │ │ Grafana │ │
|
||||
│ │ :4000 │─▶│ :9000 │ │ :3000 │ │ :3000 │ │
|
||||
│ │ keys+sync│ │internal │ │ harness │ │ Prometheus│ │
|
||||
│ │ fallback │ │only! │ │ UI │ │ data src │ │
|
||||
│ └──────────┘ └───┬──────┘ └──────────┘ └──────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │PostgreSQL│ │ Redis │ │Prometheus│ │
|
||||
│ │ :5432 │ │ :6379 │ │ :9090 │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ │
|
||||
└────────────────────┼─────────────────────────────────────────────┘
|
||||
│
|
||||
┌───────────────┼───────────────┬──────────────────┐
|
||||
│ │ │ │
|
||||
┌────▼─────┐ ┌──────▼──────┐ ┌────▼──────┐ ┌───────▼──────┐
|
||||
│ CT 8 │ │ CT 110 │ │ CT 15 │ │ pi (.24) │
|
||||
│ RTX 3090 │ │ RTX 5070 │ │ Strix Halo│ │ GPU Monitor │
|
||||
│ 24GB │ │ 12GB │ │ 64GB UMA │ │ :9100 │
|
||||
│ 128K ctx │ │ 128K ctx │ │ 256K ctx │ │ Watchdog │
|
||||
│ qwen3.6 │ │ gemma-4-12b │ │ ornith35B │ │ Prometheus │
|
||||
│ 27B-code │ │ :8080 │ │ :8080 │ │ exporter │
|
||||
│ :8080 │ │ :9400 (exp) │ │ :9400(exp)│ │ :9401 │
|
||||
│ :9400 │ └─────────────┘ └───────────┘ └──────────────┘
|
||||
└──────────┘
|
||||
```
|
||||
|
||||
## Stable Role-Based Aliases (Introduced 2026-07-15)
|
||||
|
||||
Agent configs, cron jobs, and workflows MUST use these aliases, never model-specific names.
|
||||
When a model is swapped on a GPU, ONLY the infrastructure layer changes — agent configs are untouched.
|
||||
|
||||
| Alias | GPU | Current Model | Will Route To |
|
||||
|-------|-----|---------------|---------------|
|
||||
| `strix-moe` | Strix Halo (.15) | qwen3.6-35B-udq4 | Whatever runs on Strix Halo |
|
||||
| `gpu-dense` | RTX 3090 (.8) | Qwen3.8-27B-Uncensored-Q4_K_M | Whatever runs on RTX 3090 |
|
||||
| `gpu-light` | RTX 5070 (.110) | gemma-4-12b | Whatever runs on RTX 5070 |
|
||||
|
||||
**Backward compatibility**: Old model-specific names (qwen3.6-27B-code, gemma-4-12b, qwen3.5-9b-it) still work
|
||||
but are deprecated for agent configs. Only the stable aliases survive model swaps.
|
||||
|
||||
## Current Model Assignments (2026-07-15)
|
||||
## Current Model Assignments (2026-07-08)
|
||||
|
||||
| Model | GPU | Host | VRAM | Ctx | KV Cache | Parallel | Batch/Ubatch | Status |
|
||||
|-------|-----|------|------|-----|----------|----------|-------------|--------|
|
||||
|
||||
## Routing Configuration (LiteLLM — July 2026)
|
||||
|
||||
### syslog-auto Weighted Pool (Direct GPU — bypasses router)
|
||||
|
||||
| Model | GPU | Weight | RPM Cap | Timeout |
|
||||
|-------|-----|--------|---------|---------|
|
||||
| Qwen3.8-27B-Uncensored-Q4_K_M | RTX 3090 (.8:8080) | **0.55** | 500 | **300s** |
|
||||
|
||||
Note: All syslog-auto entries route directly to GPUs with `api_key: not-needed`. The router (port 9000) was decommissioned 2026-09-11 and is NOT in the inference path.
|
||||
|
||||
### Direct Model Endpoints
|
||||
|
||||
| Model | RPM Cap | Notes |
|
||||
|-------|---------|-------|
|
||||
|
||||
### Stable Aliases (for agent configs — never change)
|
||||
|
||||
| Alias | RPM Cap | Routes To | Purpose |
|
||||
|-------|---------|-----------|---------|
|
||||
| `strix-moe` | 40 | Strix Halo | Compression tasks (MoE models) |
|
||||
| `gpu-dense` | 500 | RTX 3090 | Heavy reasoning |
|
||||
| `gpu-light` | 500 | RTX 5070 | Vision, web extract, light tasks |
|
||||
|
||||
### Fallback Chains
|
||||
- gemma → qwen
|
||||
- qwen → gemma
|
||||
- strix-moe → qwen → gemma
|
||||
- syslog-auto → qwen → gemma → qwen3.6-35B-udq4
|
||||
|
||||
### Why Strix Halo RPM Is Capped
|
||||
- Direct (strix-moe): 40 RPM (tight) — Strix Halo is shared with compression tasks
|
||||
- Via syslog-auto: 60 RPM (moderate) — prevents flooding when multiple agents use syslog-auto simultaneously
|
||||
- Combined max: ~100 RPM across both paths — Strix Halo can sustain this at 80°C
|
||||
| qwen3.6-27B-code | RTX 3090 | .8 (llm-gpu) | 20.3/24GB (83%) | 128K | turbo4 | 2 | 512/512 | ✅ healthy |
|
||||
| gemma-4-12b | RTX 5070 | .110 (ocu-llm) | 9.4/12.2GB (77%) | 128K | q4_0 | 2 | 2048/512 | ✅ healthy |
|
||||
| ornith-1.0-35b | Strix Halo Vulkan | .15 (amdpve) | 24.4/64GB (35%) | 256K | q8_0 | 2 | 2048/512 | ✅ healthy |
|
||||
|
||||
## Operations
|
||||
|
||||
@@ -149,7 +102,7 @@ Note: All syslog-auto entries route directly to GPUs with `api_key: not-needed`.
|
||||
6. Cleanup model files (optional)
|
||||
|
||||
### heal
|
||||
1. Check all GPUs via gpu-monitor `{{gpu_dashboard_url}}/gpu-data`
|
||||
1. Check all GPUs via router internal `:9000/health/unified`
|
||||
2. Check LiteLLM health via nginx `:80/litellm/health/liveliness`
|
||||
3. Reset stuck circuit breakers if idle (Redis)
|
||||
4. Restart dead llama-server instances via SSH
|
||||
@@ -157,14 +110,14 @@ Note: All syslog-auto entries route directly to GPUs with `api_key: not-needed`.
|
||||
6. Verify GPU monitor server is running on pi (:9100)
|
||||
7. Verify watchdog is running on pi
|
||||
8. Restart router if roster not loaded (check logs for STARTUP ROSTER)
|
||||
9. Router roster reload — REMOVED 2026-09-11 (router decommissioned; LiteLLM fallbacks handle routing)
|
||||
9. Reload roster via `POST :9000/admin/roster/reload` if available
|
||||
|
||||
### sync-keys
|
||||
1. List all agent keys in LiteLLM DB via `GET /key/list`
|
||||
2. Compare against expected agent list: [tanko, mumuni, abiba, koby, koonimo, kagenz0]
|
||||
2. Compare against expected agent list: [tanko, mumuni, abiba, tdunna, baggy, kagenz0]
|
||||
3. Generate missing keys via `POST /key/generate` with unlimited budget
|
||||
4. Update Infisical vault: `infisical secrets set LITELLM_API_KEY=<key> --project=agents --env=production`
|
||||
5. Send Zulip DM to agents that can't be reached via SSH (provide vault login instructions)
|
||||
4. Update agent configs — `/etc/environment` LITELLM_API_KEY
|
||||
5. Send Zulip DM to agents that can't be reached via SSH
|
||||
6. Verify each key with test request through full chain
|
||||
7. Document keys in knowledge graph
|
||||
|
||||
@@ -177,31 +130,25 @@ Show full fleet status: GPUs, models, VRAM, context windows, parallel slots, act
|
||||
3. Check LiteLLM: `curl http://192.168.68.116/health` (expect "I'm alive!")
|
||||
4. Check LiteLLM models: `curl -H "Authorization: Bearer $MASTER_KEY" http://192.168.68.116/v1/models`
|
||||
5. Check LiteLLM timeouts: `grep -n 'timeout:' /opt/inference-harness/litellm_config.yaml`
|
||||
- Qwen3.5-9B: 120s, qwen3.6-27B-code: 300s, Carnice-Qwen3.6-MoE-35B-A3B/strix-moe: 300s (strix-moe alias retained, legacy name qwen3.6-35B-udq4 deprecated)
|
||||
- gemma-4-12b: 120s, qwen3.6-27B: 90s, ornith-1.0-35b: 120s
|
||||
- global request_timeout: 300s, nginx proxy_read_timeout: 600s
|
||||
6. Check AMD metrics: `curl http://192.168.68.15:9400/metrics` (Radeon 8060S, util%, VRAM, temp, power)
|
||||
7. Check port conflicts: verify only one llama-server on :8080 per host
|
||||
8. Verify agent keys: 9 keys in LiteLLM DB (`GET /key/list`)
|
||||
|
||||
## Agent Keys (LiteLLM DB — Current 2026-07-11)
|
||||
## Agent Keys (LiteLLM DB — Current 2026-06-30)
|
||||
|
||||
Keys stored in Infisical vault (project=agents, env=production, secret=LITELLM_API_KEY).
|
||||
Agent gateways inject keys at runtime via `infisical run --` wrapper.
|
||||
Plaintext keys removed from this contract post-vault-migration.
|
||||
| Agent | CT | IP | Key | Access |
|
||||
|-------|-----|-----|-----|--------|
|
||||
| Tanko | 112 | .122 | `sk-CggiHWlamQyShxWC3Hx6uw` | SSH jerome |
|
||||
| Mumuni | 114 | .123 | `sk-VrqCNlwUgzoNGOpikJ7nwQ` | SSH root |
|
||||
| Abiba | 100 | .24 | `sk-Qvzi4uYQBhlSK_XstEhcyQ` | local (pi agent) |
|
||||
| Tdunna | 111 | ? | `sk-6sbCNjz2T6lTVDBdlNHXsA` | Zulip DM |
|
||||
| Baggy | 113 | ? | `sk-krnw_zGBwvvL5b7l2t-s-A` | no SSH |
|
||||
| Kagenz0 | 105 | ? | `sk-Dh4CDkaHebMLEp8qqq20qA` | no SSH |
|
||||
|
||||
| Agent | CT | IP | LiteLLM Alias | Key Source | Access |
|
||||
|-------|-----|-----|---------------|------------|--------|
|
||||
| Tanko | 112 | .122 | `tanko` | Infisical vault | SSH jerome |
|
||||
| Mumuni | 105 (kagentz) | .14 | `mumuni` | Infisical vault | SSH root |
|
||||
| Abiba | 100 | .24 | `abiba-pi` | Infisical vault | local (pi agent) |
|
||||
| Koby | 111 | ? | `koby` | Infisical vault | Zulip DM |
|
||||
| Koonimo | 113 | ? | `koonimo` | Infisical vault (migrated 2026-07-11) | no SSH |
|
||||
| Kagenz0 | 105 | ? | `kagenz0` | Infisical vault | no SSH |
|
||||
|
||||
> **Note**: CT hostnames differ from agent identities. CT111=tdunna runs koby; CT113=baggy runs koonimo.
|
||||
|
||||
**Key update procedure**: Update Infisical vault → `infisical secrets set LITELLM_API_KEY=sk-... --project=agents --env=production` → restart agent gateway. Agent picks up new key via `infisical run --` wrapper at startup.
|
||||
If no SSH access, send Zulip DM via abiba-bot with vault update instructions.
|
||||
**Key update procedure**: Update `/etc/environment` → `LITELLM_API_KEY=sk-...` → restart Hermes.
|
||||
If no SSH access, send Zulip DM via abiba-bot.
|
||||
|
||||
## Configuration Files
|
||||
|
||||
@@ -217,13 +164,13 @@ If no SSH access, send Zulip DM via abiba-bot with vault update instructions.
|
||||
| `/root/scripts/gpu-saturation-watchdog.py` | pi (.24) | Auto-restart stuck llama-server |
|
||||
| `/root/dashboard/gpu-fleet.html` | pi (.24) | Live HTML dashboard |
|
||||
| `/etc/systemd/system/llama-server.service` | .8, .110 | llama-server daemons (Nvidia GPUs) |
|
||||
| `/etc/systemd/system/strix-server.service` | .15 (amdpve) | llama-server daemon (Vulkan, Strix Halo) running unsloth/Qwen3.6-35B-A3B-MTP-GGUF. Note: `llama-server.service` and `llama-server@.service` are **masked** on .15 to prevent port 8080 collisions. |
|
||||
| `/etc/systemd/system/ornith-server.service` | .15 (amdpve) | llama-server daemon (Vulkan, Strix Halo). Note: `llama-server.service` and `llama-server@.service` are **masked** on .15 to prevent port 8080 collisions. |
|
||||
|
||||
## Prometheus & Grafana
|
||||
|
||||
| Component | URL | Details |
|
||||
|-----------|-----|---------|
|
||||
| Grafana | `http://192.168.68.116:3001/` | admin / vault (`GRAFANA_ADMIN_PASSWORD`) |
|
||||
| Grafana | `http://192.168.68.116:3001/` | admin / syslog-grafana-2026 |
|
||||
| GPU Dashboard | `http://192.168.68.116:3001/d/gpu-fleet` | Gauges + time series |
|
||||
| Prometheus | `http://192.168.68.116:9090/` (internal) | 5 scrape targets |
|
||||
| GPU Exporters | `:9400/metrics` on .8, .110, .15 | NVIDIA/AMD GPU metrics |
|
||||
@@ -234,9 +181,14 @@ If no SSH access, send Zulip DM via abiba-bot with vault update instructions.
|
||||
- **Router startup race**: Compose router.py doesn't call load_roster(). Reload thread sleeps 30s first.
|
||||
Fix: trigger roster reload via SSH after restart, or rebuild image with startup load_roster().
|
||||
- **LiteLLM /metrics**: Requires auth. Prometheus uses `/health/liveliness` as workaround.
|
||||
- **Strix Halo GPU**: Vulkan is the working backend (ROCm/HIP path abandoned — HSA runtime blocked on Debian 13). Build at `/root/llama.cpp/build-vk/`, commit `4fc4ec5` (2026-07-01), ggml 0.15.3 shared-lib arch. Mesa RADV 25.0.7, KHR_coopmat fast path active. ~70 tok/s gen, 532 tok/s prompt. Service: `strix-server.service` on port 8080, model: `qwen3.6-35B-udq4`, alias `strix-moe`, 128K context, flash-attn + q4 KV, multimodal (mmproj loaded).
|
||||
- **VRAM (2026-07-08)**: RTX 3090 at 20.3/24GB (83%), RTX 5070 at 9.4/12.2GB (77%), Strix Halo at 24.4/64GB (35%). Context reduced from 256K→128K on NVIDIA GPUs freed ~3.3GB (.8) and ~1.5GB (.110).
|
||||
- **All GPUs at `--parallel 2` (2026-07-08)**: Fleet serves 6 concurrent requests (was 3). 2× throughput.
|
||||
- **RTX 3090 config**: `-c 131072 -ctk turbo4 -ctv turbo4 --parallel 2`. No explicit batch flags (512/512 default). Service: `/home/llmuser/llama-wrapper.sh`.
|
||||
- **RTX 5070 config**: `--ctx-size 131072 --cache-type-k q4_0 --cache-type-v q4_0 --batch-size 2048 --ubatch-size 512 --parallel 2`. Ubatch fixed 4096→512 (was inverted — ubatch > batch killed prompt throughput). Service: `/home/llmuser/llama-wrapper.sh`.
|
||||
- **LiteLLM timeout tuning (2026-07-08)**: gemma-4-12b 25→120s, qwen3.6-27B-code 40→90s, syslog-auto (qwen route) 40→90s. Nginx proxy_read_timeout: 600s. Global request_timeout: 300s. Config at `/opt/inference-harness/litellm_config.yaml`.
|
||||
- **Strix Halo GPU**: Vulkan is the working backend (ROCm/HIP path abandoned — HSA runtime blocked on Debian 13). Build at `/root/llama.cpp/build-vk/`, commit `4fc4ec5` (2026-07-01), ggml 0.15.3 shared-lib arch. Mesa RADV 25.0.7, KHR_coopmat fast path active. ~70 tok/s gen, 532 tok/s prompt. Service: `ornith-server.service` on port 8080, 256K context, flash-attn + q8 KV.
|
||||
- **Port conflict detection (2026-07-05)**: All 3 GPU wrappers now detect ghost processes squatting port 8080 before starting. `.8` and `.110` use inline pre-start check in `llama-wrapper.sh`; `.15` uses `/usr/local/bin/port-cleanup.sh` ExecStartPre. Replaces the blanket `pkill -9 -x llama-server` on .15 which would kill ALL llama-server instances regardless of port. Ghost detection was the root cause of .8 crash-looping for 27+ restarts (stale pid 25836 squatting 8080 after OOM kill).
|
||||
- **Strix Halo thermal safeguard (2026-07-02)**: `strix-server.service` has `-n 8192` (hard generation cap per request). Without it, `--predict` defaults to -1 (infinity) — a runaway request from .123 (old Mumuni CT114 — now inside Abiba CT100 at .24) decoded 39,868 tokens over 24 min, pushing Tctl to 98°C (crit 89.8°C) and throttling 70→29 t/s. The cap bounds worst-case generation to ~5 min. Do NOT remove `-n` without a replacement ceiling. Sustained load hits ~84°C even at 92s; the APU is fanless/low-flow. Clients MUST also set `max_tokens`.
|
||||
- **Strix Halo thermal safeguard (2026-07-02)**: `ornith-server.service` has `-n 8192` (hard generation cap per request). Without it, `--predict` defaults to -1 (infinity) — a runaway request from .123 (Mumuni) decoded 39,868 tokens over 24 min, pushing Tctl to 98°C (crit 89.8°C) and throttling 70→29 t/s. The cap bounds worst-case generation to ~5 min. Do NOT remove `-n` without a replacement ceiling. Sustained load hits ~84°C even at 92s; the APU is fanless/low-flow. Clients MUST also set `max_tokens`.
|
||||
- **Port 8080 firewall**: amdpve iptables restricts 8080 to 192.168.68.116 (LiteLLM/router host) only. All inbound connections are from .116 (LiteLLM proxied via nginx). Localhost curls hang (SYN dropped). Always test from .116.
|
||||
- **Router sidecar fallback**: `router.py` `check_gpu_health()` now probes GPU `/health` directly when sidecar at :8090 is absent. Sidecar JSON exporters not deployed on any GPU host — router relies on GPU-direct fallback.
|
||||
- **Router GPU_MOE_URL bug (fixed 2026-07-01)**: docker-compose had `GPU_MOE_URL=.110:8080` (gemma host) instead of `.15:8080` (amdpve). Corrected.
|
||||
@@ -246,70 +198,24 @@ If no SSH access, send Zulip DM via abiba-bot with vault update instructions.
|
||||
|
||||
## GPU Inference Benchmarks (Current)
|
||||
|
||||
| GPU | Model | Gen tok/s | Prompt tok/s | Baseline | Context |
|
||||
| GPU | Model | Gen tok/s | Prompt tok/s | Baseline | Samples |
|
||||
|-----|-------|-----------|--------------|----------|---------|
|
||||
| RTX 3090 (.8) | Qwen3.8-27B-Uncensored-Q4_K_M | **TBD** | — | — | **128K** |
|
||||
| Strix Halo (.15) | qwen3.6-35B-udq4 | **65** | 140 | — | **128K** |
|
||||
| RTX 3090 (.8) | qwen3.6-27B-code | 75 | 305 | 74 | 6 |
|
||||
| RTX 5070 (.110) | gemma-4-12b | 75 | 323 | 75 | 6 |
|
||||
| Strix Halo (.15) | ornith-1.0-35b | 70 | 532 | 70 | 6 |
|
||||
|
||||
Benchmarks from 2026-07-17. Strix Halo model: qwen3.6-35B-udq4. RTX 5070 MTP provides 2.7x speedup over pre-upgrade 70 tok/s.
|
||||
All 3 GPUs now at 128K context (2026-07-17, reduced from 256K for stability).
|
||||
|
||||
Benchmarks run through LiteLLM proxy (192.168.68.116:4000) every 5 minutes.
|
||||
Benchmarks run through LiteLLM proxy (192.168.68.116:4001) every 5 minutes.
|
||||
Degradation alerts fire at 30% (warning) and 50% (critical) below baseline.
|
||||
History stored at `/root/data/toks-history.json` with 7-day rolling window.
|
||||
|
||||
**Note (2026-07-01)**: Strix Halo prompt tok/s jumped 209→532 after Vulkan rebuild (cooperative-matrix fast path now active on GFX1151). Baseline may need re-calibration.
|
||||
|
||||
## Agent Config Implications (2026-07-15)
|
||||
## Agent Config Implications (2026-07-08)
|
||||
|
||||
### Stable Aliases — CRITICAL
|
||||
|
||||
All agent configs MUST use stable role-based aliases, never model-specific names:
|
||||
- `compression.model: strix-moe` (NOT `qwen3.6-35B-udq4`)
|
||||
- `auxiliary.vision.model: gpu-light` (NOT `gemma-4-12b`)
|
||||
- `delegation.model: gpu-dense` (NOT `qwen3.6-27B-code`)
|
||||
- `auxiliary.web_extract.model: gpu-light`
|
||||
|
||||
When the underlying model is swapped, only the LiteLLM config changes — agent configs are untouched.
|
||||
|
||||
### Context Windows
|
||||
- RTX 3090: **128K** (reduced from 256K 2026-07-17) | RTX 5070: **128K** (reduced from 256K) | Strix Halo: **128K**
|
||||
- **All agents**: 128K ceiling — stable margin. For >128K workloads, use external providers (deepseek)
|
||||
- Compression threshold 0.60: fires at ~77K (~51K headroom before 128K ceiling)
|
||||
- **Pi agents (Abiba)**: `compaction.reserveTokens: 52739` (≈60% of 128K)
|
||||
- Mumuni compression model alias: `strix-moe` with 300s timeout
|
||||
|
||||
### Mumuni Agent Profile
|
||||
|
||||
Mumuni (kagentz CT105, 192.168.68.14 — migrated from CT100 2026-08-29) is the primary business assistant. This profile is the reference for all agent configs:
|
||||
|
||||
| Setting | Value | Notes |
|
||||
|---------|-------|-------|
|
||||
| `model.default` | `syslog-auto` | Weighted pool (55% qwen, 30% strix, 15% gemma) |
|
||||
| `model.provider` | `custom:litellm` | LiteLLM on CT116 |
|
||||
| `compression.model` | `strix-moe` | Stable alias — survives model swaps |
|
||||
| `aux.compression.model` | `strix-moe` | Compression auxiliary model |
|
||||
| `aux.vision.model` | `gpu-light` | Vision tasks (RTX 5070) |
|
||||
| `aux.web_extract.model` | `gpu-light` | Web extraction |
|
||||
| `delegation.model` | `gpu-dense` | Sub-agent reasoning (RTX 3090) |
|
||||
| `context.max_context_window` | 131072 (128K) | Reduced from 256K 2026-07-17 — stable 128K ceiling |
|
||||
| `compression.threshold` | 0.60 | Triggers at ~77K (~60% of 128K) — optimized for 128K context |
|
||||
| `compression.target_ratio` | 0.3 | Compresses to ~38K |
|
||||
| `compression.protect_last_n` | 40 | Preserves last 40 messages |
|
||||
| `memory.memory_char_limit` | 800 | Brief memory entries |
|
||||
| `personalities` | `creative` | Creative assistant personality |
|
||||
| Platforms | cli, homeassistant, signal, telegram, zulip | All Hermes platforms |
|
||||
| Main model timeout | 300s | LiteLLM global timeout |
|
||||
| Compression model timeout | 300s | strix-moe timeout increased from 120s |
|
||||
|
||||
### Agent Update Status (2026-07-15)
|
||||
|
||||
| Agent | Host | Status |
|
||||
|-------|------|--------|
|
||||
| **Mumuni** | CT105 (.14) | ✅ Updated to stable aliases |
|
||||
| **Tanko** | CT112 (.122) | ✅ Updated to stable aliases |
|
||||
| **Koby** | CT111 (.129) | ❌ SSH unreachable — needs Zulip DM |
|
||||
| **Koonimo** | CT113 | ❌ SSH unreachable — needs Zulip DM |
|
||||
| **Kagenz0** | CT105 | ❌ SSH unreachable — needs Zulip DM |
|
||||
|
||||
All Hermes clients MUST set `max_tokens: 4096` — first line of defense before server-side `-n 8192` cap.
|
||||
With NVIDIA GPUs at 128K context:
|
||||
- Agents using `syslog-auto` (50/50 qwen+ornith): keep `context_length: 262144` — ornith supports it, Litellm fallbacks handle qwen overflow
|
||||
- Agents using `qwen3.6-27B-code` directly: set `context_length: 131072` and `max_tokens: 4096` per thermal safety rule
|
||||
- Agents using `gemma-4-12b` directly (auxiliary tasks): set `context_length: 131072`
|
||||
- Compression threshold at 0.65: fires at ~170K for syslog-auto (262K ctx), ~85K for direct qwen/gemma (128K ctx)
|
||||
- All Hermes clients MUST set `max_tokens: 4096` — first line of defense before server-side `-n 8192` cap
|
||||
- Port 8080 is used on all 3 GPU hosts (not 8090 as previously documented)
|
||||
|
||||
+23
-97
@@ -2,7 +2,7 @@
|
||||
kind: responsibility
|
||||
name: gpu-monitor
|
||||
description: >
|
||||
Comprehensive GPU fleet monitor — polls every subsystem (sidecars,
|
||||
Comprehensive GPU fleet monitor — polls every subsystem (sidecars, router,
|
||||
LiteLLM, Strix Halo, dashboard) every 15s, renders a live HTML dashboard,
|
||||
checks alert thresholds, and exposes a JSON API for downstream consumers.
|
||||
agent: abiba
|
||||
@@ -31,34 +31,23 @@ agent: abiba
|
||||
└──────┘ │qwen27B│ │LiteLLM │
|
||||
└──────┘ │dashboard│
|
||||
└────────┘
|
||||
```
|
||||
|
||||
Note: JSON sidecar exporters at :8090 were never deployed on any
|
||||
GPU host. Router falls back to GPU /health direct probe. Monitor
|
||||
should use router /health/unified as source of truth for GPU status.
|
||||
Strix Halo :8080 is firewalled to .116 only — monitor on .24 cannot
|
||||
poll .15:8080 directly; must go through router on .116.
|
||||
|
||||
**PORT RULE (verified 2026-09-10):** GPU per-host health lives on **:8080**
|
||||
(`http://<gpu-host>:8080/health`); Prometheus GPU exporters live on **:9400**.
|
||||
There is NO listener on bare port 80 for any GPU host — `http://192.168.68.8/health`
|
||||
and `http://192.168.68.110/health` answer `000`. Never use a bare-port-80 probe
|
||||
as a GPU liveness signal: on 2026-09-09 that produced three false
|
||||
`DEGRADED — GPU-rtx3090 000, GPU-rtx5070 000` rounds while
|
||||
`http://192.168.68.8:8080/health` and `http://192.168.68.110:8080/health`
|
||||
answered `200`. Port 80 is valid only on the harness host (.116), never on a GPU host.
|
||||
```
|
||||
|
||||
### Subsystems Polled
|
||||
|
||||
| Subsystem | Endpoint | Frequency | Metrics |
|
||||
|-----------|----------|-----------|---------|
|
||||
| GPU Status (all, via fleet API) | `http://192.168.68.116/gpu/gpu-data` | 15s | models, CB, scores, GPU status from gpu-monitor on .24:9100 |
|
||||
| GPU .8 (RTX 3090) health | `http://192.168.68.8:8080/health` | 15s | direct liveness fallback — **:8080 ONLY, never bare port 80** |
|
||||
| GPU .110 (RTX 5070) health | `http://192.168.68.110:8080/health` | 15s | direct liveness fallback — **:8080 ONLY, never bare port 80** |
|
||||
| Fleet (unified) | `http://192.168.68.116/health/unified` | 15s | nginx `301` → `/gpu/gpu-data` served by gpu-monitor = alive (router decommissioned 2026-09-11) |
|
||||
| Harness (basic) | `http://192.168.68.116/health` | 15s | nginx → LiteLLM `/health/liveliness` |
|
||||
| GPU Status (all, via router) | `http://192.168.68.116/health/unified` | 15s | models, CB, scores, GPU status (router probes each GPU /health directly) |
|
||||
| Router (unified) | `http://192.168.68.116/health/unified` | 15s | models, CB, scores, GPU status |
|
||||
| Router (basic) | `http://192.168.68.116/health` | 15s | basic aliveness |
|
||||
| LiteLLM | `http://192.168.68.116/litellm/health` | 15s | proxy health, model count |
|
||||
| Strix Halo | `http://192.168.68.116/health/unified` (nginx → fleet API) | 15s | Strix Halo status via gpu-monitor — cannot poll .15:8080 directly (firewalled to .116 only) |
|
||||
| Strix Halo | `http://192.168.68.116/health/unified` (router) | 15s | ornith status via router — cannot poll .15:8080 directly (firewalled to .116 only) |
|
||||
| Dashboard | `http://192.168.68.116/dashboard/` | 15s | harness-dashboard aliveness |
|
||||
|
||||
### Alert Delivery
|
||||
@@ -72,28 +61,12 @@ This replaces the previous DM-only delivery. All agents on the mesh can see and
|
||||
|
||||
## Alert Thresholds
|
||||
|
||||
### Liveness rule (scoped)
|
||||
|
||||
The any-HTTP-response rule applies ONLY to redirect/auth-gated liveness
|
||||
endpoints, where any HTTP answer proves a listener is up. Applied here: nginx's
|
||||
`/health/unified` answers `301 Moved Permanently` → `/gpu/gpu-data`
|
||||
(the same payload) and LiteLLM's `/litellm/health` answers `301` →
|
||||
`/litellm/health/liveliness`. For those endpoints a probe is **ALIVE** on
|
||||
**ANY** HTTP status — `3xx` redirects and `401`/`403` auth challenges included —
|
||||
and **DOWN = connection refused (`000`) or timeout only**. Same scoped rule as
|
||||
zulip-health (Tanko) and infrastructure-monitoring.
|
||||
|
||||
Probes whose success condition is specifically a bare `200` are NOT covered by
|
||||
the any-HTTP rule. On those — the GPU `:8080/health` endpoints, nginx `/health`,
|
||||
and the dashboard — an unexpected status (`401`/`403`, `5xx`, or
|
||||
anything other than the expected `200`) is an **ALERT**, not "alive".
|
||||
|
||||
| Metric | Warning | Critical |
|
||||
|--------|---------|----------|
|
||||
| GPU Temp | >80°C | >90°C |
|
||||
| VRAM Usage | >90% | >95% |
|
||||
| GPU Util | >95% | >98% |
|
||||
| Sidecar Unreachable | — | info (sidecars not deployed — use gpu-monitor /gpu-data) |
|
||||
| Sidecar Unreachable | — | info (sidecars not deployed — use router /health/unified) |
|
||||
| Model Down | — | critical (circuit breaker open) |
|
||||
|
||||
### JSON API Response Schema (/gpu-data)
|
||||
@@ -124,47 +97,7 @@ anything other than the expected `200`) is an **ALERT**, not "alive".
|
||||
`curl http://localhost:9100/gpu-data | jq` — Full fleet status
|
||||
|
||||
### check-health
|
||||
|
||||
**RUN LIVE, NEVER ECHO — every dispatch must execute the probes below with real tool calls; never repeat a prior report unless a live probe fails.**
|
||||
|
||||
```bash
|
||||
# Provenance — run first; paste the absolute path into the report
|
||||
pwd -P
|
||||
|
||||
# GPU Monitor health
|
||||
curl http://localhost:9100/health | jq
|
||||
# Expected: 200 with {"status": "healthy", "cache_age_seconds": <n>}
|
||||
|
||||
# GPU host health — DIRECT on :8080. NEVER probe bare port 80 on a GPU host:
|
||||
# http://192.168.68.8/health has no listener and returns 000 → false DEGRADED.
|
||||
curl -s -o /dev/null -w '%{http_code}' http://192.168.68.8:8080/health
|
||||
# Expected: 200 (bare-200 probe: any other status is an alert; 000/timeout = DOWN)
|
||||
curl -s -o /dev/null -w '%{http_code}' http://192.168.68.110:8080/health
|
||||
# Expected: 200 (bare-200 probe: any other status is an alert; 000/timeout = DOWN)
|
||||
|
||||
# Router unified health (source of truth; 301 → /gpu/gpu-data is HEALTHY)
|
||||
curl -s -o /dev/null -w '%{http_code}' http://192.168.68.116/health/unified
|
||||
# Expected: 301 (or 200 after following the redirect) — any HTTP status = alive
|
||||
|
||||
# Router basic health (via nginx on port 80 — router .116 only, never a GPU host)
|
||||
curl -s -o /dev/null -w '%{http_code}' http://192.168.68.116/health
|
||||
# Expected: 200 (bare-200 probe: any other status is an alert; 000/timeout = DOWN)
|
||||
|
||||
# LiteLLM health (via nginx on port 80)
|
||||
curl -s -o /dev/null -w '%{http_code}' http://192.168.68.116/litellm/health
|
||||
# Expected: 301 → /litellm/health/liveliness (200 after redirect) — any HTTP status = alive
|
||||
|
||||
# Dashboard
|
||||
curl -s -o /dev/null -w '%{http_code}' http://192.168.68.116/dashboard/
|
||||
# Expected: 200 (bare-200 probe: any other status is an alert; 000/timeout = DOWN)
|
||||
```
|
||||
|
||||
**Report format**: Begin every report with the **absolute path the probe executed
|
||||
from** (`pwd -P`, or the monitor script's absolute path) so a stale-consumer
|
||||
report is distinguishable from a real fault at read time. Summarize actual
|
||||
results from each probe. Apply the scoped liveness rule above: on auth-gated
|
||||
endpoints only connection-refused (`000`) or timeout is DOWN; on bare-200 probes
|
||||
any other status is an alert. Never probe a GPU host on bare port 80.
|
||||
`curl http://localhost:9100/health` — Monitor self-check
|
||||
|
||||
### view-dashboard
|
||||
Open `http://localhost:9100/` in browser — Live HTML dashboard
|
||||
@@ -174,14 +107,12 @@ Open `http://localhost:9100/` in browser — Live HTML dashboard
|
||||
pkill -f gpu-monitor-server.py
|
||||
python3 /root/scripts/gpu-monitor-server.py &
|
||||
```
|
||||
Managed by systemd (verified 2026-09-11): `systemctl restart gpu-monitor`
|
||||
Or via PM2: `pm2 restart gpu-monitor`
|
||||
|
||||
### check-fleet
|
||||
Fleet health is accessed through nginx on port 80 on the harness host
|
||||
(.116) — NOT port 9000 (router decommissioned 2026-09-11), and NOT bare
|
||||
port 80 on a GPU host.
|
||||
`curl http://192.168.68.116/health/unified` — nginx answers `301` → `/gpu/gpu-data` (fleet monitor payload) = alive
|
||||
`curl http://192.168.68.8/health` — ❌ NEVER USE (GPU host, no port-80 listener → false `000`/DEGRADED)
|
||||
### check-router
|
||||
The router health is accessed through nginx on port 80 (NOT port 9000 directly).
|
||||
`curl http://192.168.68.116/health/unified` — Router unified health via nginx proxy
|
||||
`curl http://192.168.68.116:9000/health/unified` — ❌ WILL FAIL (port bound to 127.0.0.1 only)
|
||||
|
||||
## Configuration Files
|
||||
|
||||
@@ -193,18 +124,13 @@ port 80 on a GPU host.
|
||||
|
||||
## Execution
|
||||
|
||||
**Port discipline:** probe GPU hosts on `:8080` (or the router's
|
||||
`/health/unified`); probe port 80 only on the router (.116). Never bare port 80
|
||||
on a GPU host.
|
||||
|
||||
1. **Poll router** (every 15s): GET .116/health/unified — single source of truth for all GPU status (router probes each GPU /health directly via sidecar fallback). `301` → `/gpu/gpu-data` counts as alive.
|
||||
2. **Fallback direct GPU probe** (only if router /health/unified is DOWN): GET `http://192.168.68.8:8080/health` and `http://192.168.68.110:8080/health` — **:8080 only, never bare port 80**.
|
||||
3. **Poll router** (every 15s): GET .116/health via nginx:80
|
||||
4. **Poll LiteLLM** (every 15s): GET .116/litellm/health via nginx:80
|
||||
5. **Poll Strix** (every 15s): via router /health/unified (cannot poll .15:8080 directly — firewalled to .116 only)
|
||||
6. **Poll dashboard** (every 15s): GET .116/dashboard/
|
||||
7. **Check alerts**: Compare metrics against thresholds
|
||||
8. **Compute summary**: Fleet-wide health aggregation
|
||||
9. **Render dashboard**: Generate HTML at /root/dashboard/gpu-fleet.html
|
||||
10. **Serve API**: HTTP server on port 9100
|
||||
11. **Repeat** every 15 seconds
|
||||
1. **Poll router** (every 15s): GET .116/health/unified — single source of truth for all GPU status (router probes each GPU /health directly via sidecar fallback)
|
||||
2. **Poll router** (every 15s): GET .116/health via nginx:80
|
||||
3. **Poll LiteLLM** (every 15s): GET .116/litellm/health via nginx:80
|
||||
4. **Poll Strix** (every 15s): via router /health/unified (cannot poll .15:8080 directly — firewalled to .116 only)
|
||||
5. **Poll dashboard** (every 15s): GET .116/dashboard/
|
||||
6. **Check alerts**: Compare metrics against thresholds
|
||||
7. **Compute summary**: Fleet-wide health aggregation
|
||||
8. **Render dashboard**: Generate HTML at /root/dashboard/gpu-fleet.html
|
||||
9. **Serve API**: HTTP server on port 9100
|
||||
10. **Repeat** every 15 seconds
|
||||
|
||||
@@ -1,316 +0,0 @@
|
||||
---
|
||||
report_only_agents:
|
||||
- koby # ⛔ KOBY IS NEVER REPAIRED (Rule 17, 2026-08-17) — detect + report, never fix on .129
|
||||
kind: responsibility
|
||||
name: gpu-self-heal
|
||||
description: >
|
||||
GPU fleet self-healing — detects anomalies, applies remediation, tracks
|
||||
benchmarks, and predicts failures before they happen. Extends gpu-monitor
|
||||
(v2.1.0) with active remediation rules, Prometheus metrics consumption,
|
||||
VRAM trend analysis, and predictive alerting.
|
||||
UPDATED 2026-07-18: Model assignments synced to 2026-07-17 swaps.
|
||||
Router (port 9000) DECOMMISSIONED 2026-09-11; references replaced with direct GPU routing.
|
||||
Benchmark baselines refreshed to live values.
|
||||
Prometheus exporters removed — not deployed; fall back to direct sidecar probes.
|
||||
Stable role-based aliases (strix-moe, gpu-dense, gpu-light) from gpu-fleet.
|
||||
agent: abiba
|
||||
depends_on:
|
||||
- gpu-monitor.prose.md (live data source on .24:9100)
|
||||
- gpu-fleet.prose.md (source of truth for topology, aliases, model assignments)
|
||||
---
|
||||
---
|
||||
|
||||
## Maintains
|
||||
|
||||
- gpu-health: { status: "healthy"|"degraded"|"down", issues: array, actions: array }
|
||||
- gpu-self-heal-log: array of { timestamp, gpu, issue, action, result } — audit trail
|
||||
- benchmark-regression: { gpu, baseline_tok_sec, current_tok_sec, trend, alerts }
|
||||
- vram-trend: { gpu, current_mb, rate_mb_per_hour, projected_full_in_hours }
|
||||
- circuit-breaker-status: { gpu, open, auto_reset_attempted, last_reset }
|
||||
|
||||
## Requires
|
||||
|
||||
- gpu-monitor:function — Live fleet data from localhost:9100/gpu-data
|
||||
- Direct sidecar probe access to all GPU hosts (:8080/health)
|
||||
- SSH access to GPU hosts for restart operations
|
||||
|
||||
## Continuity
|
||||
|
||||
- Self-driven: check every 60 seconds against GPU monitor data
|
||||
- Also wakes on gpu-fleet health degradation
|
||||
- On fix: verify with benchmark inference test before declaring resolved
|
||||
- Escalate: after 3 failed remediation attempts → Zulip #agent-hub alert
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## Current Fleet Baseline (2026-07-18)
|
||||
|
||||
| Alias | GPU | Host | Model | VRAM | Ctx | tok/s | Role |
|
||||
|-------|-----|------|-------|------|-----|-------|------|
|
||||
| `strix-moe` | Strix Halo 64GB | ct15 (.15:8080) | qwen3.6-35B-udq4 | ~10/64GB (16%) | 128K | 62.9 | Compression, summarization, long docs |
|
||||
|
||||
Key notes:
|
||||
- All models use direct GPU routing via LiteLLM (`api_key: not-needed`). Router (port 9000) was decommissioned 2026-09-11 and is NOT in the inference path.
|
||||
- Stable aliases (gpu-dense, gpu-light, strix-moe) from gpu-fleet are the canonical names for agent configs. Model-specific names still work but are deprecated.
|
||||
- RTX 5070 tok/s is ~145 for Qwen3.5-9B — gpu-light is the fastest endpoint. Route vision/web/light work there first. NOTE: Qwen3.5-9B is multimodal (image+text), NOT text-only like gemma-4-12b was.
|
||||
- Strix Halo is 62.9 tok/s (89% of 70.5 baseline) — below optimal but stable. Check for competing workloads.
|
||||
- RTX 3090 VRAM at 88% — within role-appropriate range (role = heavy reasoning, needs the headroom).
|
||||
- RTX 5070 VRAM at 83% — role-appropriate for vision/web (smaller batch sizes).
|
||||
|
||||
## Remediation Rules
|
||||
|
||||
### Rule 1: GPU Temperature Critical (>85°C for >2 min)
|
||||
- **Detect**: Any GPU temp >85°C sustained for 2+ consecutive polls
|
||||
- **Fix**:
|
||||
1. Reduce inference concurrency on that GPU (load-side cooling only — NO fan control)
|
||||
2. Redirect new requests to cooler GPUs via LiteLLM fallback chains (gemma → qwen, qwen → gemma)
|
||||
3. If all GPUs hot, alert about cooling infrastructure
|
||||
- **Verify**: Temp drops below 80°C within 5 minutes
|
||||
- **Escalate after**: 3 verification failures → Zulip alert
|
||||
|
||||
### Rule 2: VRAM Leak Detection (tiered by GPU capacity)
|
||||
- **Detect**: VRAM growing at sustained rate over 6+ hour window
|
||||
- RTX 3090 (24GB): ≥300MB/hour
|
||||
- RTX 5070 (12GB): ≥300MB/hour
|
||||
- Strix Halo (64GB UMA): ≥200MB/hour
|
||||
- **Fix**:
|
||||
1. Log VRAM snapshot with process list (nvidia-smi/rocm-smi + ps aux)
|
||||
2. If llama-server is the growth source → restart with memory cap flag
|
||||
3. If unknown process → kill and alert
|
||||
- **Verify**: VRAM growth rate drops below threshold
|
||||
- **Escalate after**: persistent leak after restart → hardware investigation
|
||||
|
||||
### Rule 3: Model Inference Timeout / GPU Stuck
|
||||
- **Detect**: >50% failure rate over 60s window + 30s grace period (not just single stuck request)
|
||||
- **Fix**:
|
||||
1. Restart llama-server on affected GPU host
|
||||
2. Wait 15s for model to reload
|
||||
3. Run benchmark inference test
|
||||
- **Verify**: Model returns 200 with <30s response, failure rate drops to 0%
|
||||
- **Escalate after**: 3 restarts in 1 hour → GPU hardware check
|
||||
|
||||
### Rule 4: Benchmark Regression (>20% drop)
|
||||
- **Detect**: gen_tok_per_sec drops >20% below baseline over 3+ benchmarks
|
||||
- RTX 3090 baseline: 74.8 tok/s → alert at <59.8 tok/s
|
||||
- RTX 5070 baseline: 165.2 tok/s → alert at <132.2 tok/s
|
||||
- Strix Halo baseline: 70.5 tok/s → alert at <56.4 tok/s
|
||||
- **Fix**:
|
||||
1. Check GPU utilization — if >90%, other process is competing
|
||||
2. Check power limit — if throttled, restore to max
|
||||
3. Check thermal — if hot, apply Rule 1
|
||||
- **Verify**: Benchmark returns to within 10% of baseline
|
||||
- **Escalate after**: persistent regression → possible hardware degradation
|
||||
|
||||
### Rule 5: Circuit Breaker Stuck Open
|
||||
- **Detect**: Circuit breaker open >10 minutes with GPU reporting healthy
|
||||
- **Note**: Router (port 9000) was decommissioned 2026-09-11. If circuit breakers are reported by gpu-monitor, they come from LiteLLM's internal tracking, not the old router.
|
||||
- **Fix**:
|
||||
1. Verify GPU /health returns 200 on direct port (:8080)
|
||||
2. If GPU healthy, alert but do NOT reset via router API (decommissioned 2026-09-11)
|
||||
3. Check LiteLLM health directly: http://192.168.68.116/litellm/health/liveliness
|
||||
4. Restart LiteLLM container on CT 116 if circuit breakers are stuck
|
||||
- **Verify**: LiteLLM returns healthy, circuit breaker clears within 60s
|
||||
- **Escalate after**: LiteLLM restart doesn't clear → human investigation
|
||||
|
||||
### Rule 6: Strix Halo Unreachable
|
||||
- **Detect**: Strix not responding — probe .15:8080 directly (firewall opened .24→.15)
|
||||
- **Fix**:
|
||||
1. SSH to .15 → check llama-server process
|
||||
2. Restart llama-server if not running
|
||||
3. Verify through both direct probe AND LiteLLM health
|
||||
- **Verify**: Direct health probe returns 200, LiteLLM reports model healthy
|
||||
- **Escalate**: If host .15 itself is unreachable → infrastructure alert
|
||||
|
||||
### Rule 7: GPU Data Source Unreachable (replaces old Prometheus rule)
|
||||
- **Detect**: gpu-monitor endpoint (localhost:9100/gpu-data) or sidecar port (:8080) on any GPU unreachable for >2 polls
|
||||
- **Fix**:
|
||||
1. If gpu-monitor is down: restart systemd service `gpu-monitor.service` on this host
|
||||
2. If sidecar is down: SSH to GPU host → check llama-server process → restart systemd service
|
||||
3. Fall back to direct nvidia-smi/rocm-smi probe via SSH if all API paths fail
|
||||
- **Verify**: gpu-monitor returns healthy + all sidecars reachable
|
||||
- **Escalate after**: 3 failed restarts → networking issue
|
||||
|
||||
### Rule 8: Predictive Thermal Warning (two-tier)
|
||||
- **Detect**:
|
||||
- Tier 1 (warning): temp >70°C AND rising >2°C/min → reduce concurrency, no alert
|
||||
- Tier 2 (critical): temp >80°C AND still rising → full alert + aggressive load shedding
|
||||
- **Fix**:
|
||||
- Tier 1: silently reduce parallel requests to that GPU by 50%
|
||||
- Tier 2: redirect all new requests away, alert #agent-hub, apply Rule 1 logic
|
||||
- **Verify**: Temp rise rate drops below 1°C/min (Tier 1) or temp drops below 80°C (Tier 2)
|
||||
- **Escalate**: If Tier 2 triggers and temp still rising after 5 min → possible hardware failure
|
||||
|
||||
### Rule 9: Context Window Optimization
|
||||
- **Detect**: Benchmark tok/s vs baseline for each GPU at current context (all 128K)
|
||||
- RTX 3090 (128K ctx, ThinkingCap): baseline 74.8 tok/s — currently at 74.9 (100%)
|
||||
- RTX 5070 (128K ctx, HauhauCS QAT): baseline 165.2 tok/s — currently at 169.6 (103%)
|
||||
- Strix Halo (128K ctx, qwen3.6-35B-udq4): baseline 70.5 tok/s — currently at 62.9 (89%)
|
||||
- **Fix**:
|
||||
- If tok/s > baseline → context has headroom, consider increasing
|
||||
- If tok/s < 90% baseline → reduce context by 25% and retest
|
||||
- If tok/s within 10% of baseline → optimal, no change
|
||||
- Strix Halo at 89% of baseline → MONITOR but do not reduce yet (recent model swap may still be settling)
|
||||
- **Verify**: Re-benchmark after context change, confirm within 10% of target
|
||||
- **Escalate**: If context can't be adjusted without significant perf loss
|
||||
|
||||
### Rule 10: Workload Distribution Optimization (updated 2026-07-18)
|
||||
- **Detect**: GPU roles misaligned with hardware capabilities
|
||||
- **Target distribution**:
|
||||
- RTX 3090 (gpu-dense, 24GB, 74.9 tok/s) → Heavy reasoning, code gen, long conversations (slowest per-token but largest context capacity). Weight: 0.55 (LiteLLM).
|
||||
- RTX 5070 (gpu-light, 12GB, ~145 tok/s) → Vision (image+text), web search, lightweight tasks. Weight: 0.15 (LiteLLM).
|
||||
- Strix Halo (strix-moe, 64GB, 62.9 tok/s) → Context compression, summarization, long docs (MoE model). Weight: 0.30 (LiteLLM).
|
||||
- **Note**: RTX 5070 is the fastest endpoint per token. Route high-volume, low-complexity work there first.
|
||||
- **Fix**:
|
||||
- Alert if any GPU is handling workload outside its designated role
|
||||
- Recommend agent alias updates to match workload to GPU role (use stable aliases: gpu-dense, gpu-light, strix-moe)
|
||||
- Track per-GPU request distribution via LiteLLM spend logs
|
||||
- **Verify**: Each GPU's request pattern matches its designated role within 24h
|
||||
- **Escalate**: If role mismatch persists >48h → agent alias audit needed
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## Execution
|
||||
|
||||
```prose
|
||||
-- Phase 1: Fetch live GPU data
|
||||
let fleet = call gpu-monitor
|
||||
endpoint: "http://localhost:9100/gpu-data"
|
||||
|
||||
-- Phase 2: Evaluate each GPU against remediation rules
|
||||
let actions = []
|
||||
for gpu in fleet.gpus:
|
||||
-- Rule 1: Thermal critical
|
||||
if gpu.temp_c > 85 and sustained_for(gpu, 120):
|
||||
push actions apply-thermal-fix(gpu)
|
||||
|
||||
-- Rule 2: VRAM leak
|
||||
let vram_rate = calculate-vram-trend(gpu, hours=6)
|
||||
if vram_rate > 50:
|
||||
push actions apply-vram-fix(gpu, vram_rate)
|
||||
|
||||
-- Rule 4: Benchmark regression
|
||||
let bench = fleet.benchmarks[gpu.hostname]
|
||||
if bench.current_tok_s < bench.baseline_tok_s * 0.8:
|
||||
push actions apply-benchmark-fix(gpu, bench)
|
||||
|
||||
-- Rule 3: Model stuck
|
||||
for model in fleet.summary.available_models:
|
||||
if model.consecutive_timeouts >= 3:
|
||||
push actions apply-model-restart(model)
|
||||
|
||||
-- Rule 5: Circuit breaker check via LiteLLM (router deprecated)
|
||||
if fleet.summary.circuit_breakers_open > 0:
|
||||
push actions check-litellm-circuit-breakers()
|
||||
|
||||
-- Rule 6: Strix Halo
|
||||
if not fleet.strix.running and pingable("192.168.68.15"):
|
||||
push actions apply-strix-restart()
|
||||
|
||||
-- Rule 7: GPU data source
|
||||
if not fleet.gpus or len(fleet.gpus) < 2:
|
||||
push actions check-gpu-monitor-service()
|
||||
|
||||
-- Rule 8: Predictive thermal
|
||||
for gpu in fleet.gpus:
|
||||
let rise_rate = calculate-temp-rise(gpu, minutes=5)
|
||||
if rise_rate > 2.0 and gpu.temp_c < 80:
|
||||
push actions apply-proactive-cooling(gpu)
|
||||
|
||||
-- Phase 3: Execute actions, verify, log
|
||||
for action in actions:
|
||||
let result = execute-with-verify(action)
|
||||
log-to-kg(action, result)
|
||||
if result.failed:
|
||||
escalate-if-needed(action)
|
||||
|
||||
-- Phase 4: Update health state
|
||||
call update-gpu-health
|
||||
gpus: fleet.gpus
|
||||
actions: actions
|
||||
status: derive-overall-status(fleet, actions)
|
||||
|
||||
-- Wait 60s and repeat
|
||||
```
|
||||
|
||||
## Audit Trail Format
|
||||
|
||||
```json
|
||||
{
|
||||
"run_id": "gpu-self-heal-20260718-001",
|
||||
"timestamp": "2026-07-18T08:00:00Z",
|
||||
"gpu": "ct8-rtx3090",
|
||||
"issue": "thermal-critical",
|
||||
"detected": { "temp_c": 87, "duration_s": 180 },
|
||||
"action": "load-shedding",
|
||||
"result": "resolved",
|
||||
"verification": { "temp_c": 76, "after_s": 300 },
|
||||
"escalated": false
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## Reporting
|
||||
|
||||
### 1. Gitea Log (not knowledge graph — hard rule)
|
||||
Pushed to `SyslogSolution/health-logs/gpu/{run_id}.json` — versioned, searchable, not in graph.
|
||||
|
||||
### 2. Zulip Alerts (#agent-hub → alerts-gpu)
|
||||
- `issues_fixed > 0` → "🛠 GPU Self-Heal — <gpu> <issue> resolved"
|
||||
- `issues_escalated > 0` → "⚠ GPU Self-Heal — <gpu> needs attention"
|
||||
- Every 100th clean cycle → "✅ GPU Fleet: All Clear"
|
||||
|
||||
### 3. Weekly Benchmark Report
|
||||
- Per-GPU tok/s trend over 7 days
|
||||
- Regression alerts if any GPU degrades >10% week-over-week
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## Design Decisions (Verified 2026-07-12, Reaffirmed 2026-07-18)
|
||||
|
||||
1. **Fan control**: ❌ NO auto fan control. Load-side cooling only (reduce concurrency, redirect).
|
||||
2. **Model restart**: ✅ Only if >50% failure rate over 60s + 30s grace period. Not on single stuck request.
|
||||
3. **Strix direct access**: ✅ Open firewall .15:8080 → .24 for direct health probe + restart.
|
||||
4. **VRAM thresholds**: Tiered — **300MB/h** (RTX 3090), **300MB/h** (RTX 5070), 200MB/h (Strix). Previous values (100/50) were too sensitive; raised 2026-07-18 based on operational data.
|
||||
5. **CB auto-reset**: ✅ Router decommissioned 2026-09-11 — circuit breakers go through LiteLLM health check + container restart if needed. No per-GPU auto-reset.
|
||||
6. **Benchmark baseline**: Rolling 30-day average, recalculated weekly. Current baselines live in gpu-monitor.
|
||||
7. **Predictive alerts**: Two-tier — warn at >70°C+rising (>2°C/min), critical at >80°C+rising.
|
||||
8. **Prometheus**: ❌ Not deployed. Use direct sidecar probes (:8080/health) and gpu-monitor API. Prometheus integration deferred until exporters are running on GPU hosts.
|
||||
|
||||
## Lessons Learned (2026-07-12, Updated 2026-07-18)
|
||||
|
||||
### L1: API Key Standardization Is Critical
|
||||
- All GPU llama-servers MUST use the same api-key as the LiteLLM config.
|
||||
- RTX 5070 had `--api-key sk-loc...5678` while LiteLLM sent `not-needed`.
|
||||
This caused cascading 401 → fallback → timeout → 401 loops.
|
||||
- **Rule**: Any new GPU or model restart MUST verify api-key matches LiteLLM config (`not-needed` for direct routing).
|
||||
|
||||
### L2: Fallback Chain Cascading Failures
|
||||
- When one model returns 401 (auth) and another is slow (timeout), the fallback
|
||||
chain creates an infinite loop.
|
||||
- **Rule**: If a model returns 401 (auth error), do NOT fall back to it again.
|
||||
Mark it as permanently failed for this request.
|
||||
|
||||
### L3: Verify Running State, Not Docs
|
||||
- RTX 3090 was documented at 128K context. Running at 128K (verified 2026-07-18).
|
||||
- Parallel count: 1 on both RTX 3090 and RTX 5070 (matches docs for current models).
|
||||
- **Rule**: Before making decisions, check `/proc/PID/cmdline` on GPU hosts.
|
||||
|
||||
### L4: Infisical Is Not Always Available
|
||||
- Keep a local `.env` fallback for `LITELLM_API_KEY`.
|
||||
- **Rule**: Always verify credential source is reachable before relying on it.
|
||||
|
||||
### L5: GPU Monitor Response Size Can Cause Self-Heal Crash
|
||||
- gpu-self-heal crashed with KeyboardInterrupt during json.loads() of 20MB response.
|
||||
- Root cause: router poll returns accumulated data → cache balloons.
|
||||
- **Rule**: Self-heal must enforce a read timeout AND max response size on every poll.
|
||||
If monitor response > 1MB, log a warning and skip the cycle rather than crashing.
|
||||
|
||||
### L6: Stable Aliases Replace Model Names
|
||||
- gpu-fleet introduced stable aliases (strix-moe, gpu-dense, gpu-light) on 2026-07-15.
|
||||
- Self-heal must use aliases for reporting and alerting, not model-specific names.
|
||||
- **Rule**: All alert messages and KG nodes use the stable alias as the GPU identifier.
|
||||
@@ -5,7 +5,7 @@ version: 1.0.0
|
||||
description: >
|
||||
Canonical known-good baseline for all Syslog Hermes agents. Captures the exact
|
||||
configuration state, keys, workarounds, and audit procedure. When an agent's
|
||||
configuration goes sideways, restore from this baseline. Last verified 2026-07-16. All GPUs 128K context (reduced from 256K for stability Jul 2026) (RTX 3090 .8, RTX 5070 .110, Strix Halo .15). Parallel 1 fleet-wide (Strix Halo handles compression solo).
|
||||
configuration goes sideways, restore from this baseline. Last verified 2026-07-08. GPU context reduced to 128K on .8/.110, parallel 2 fleet-wide.
|
||||
author: Abiba (pi agent)
|
||||
---
|
||||
|
||||
@@ -22,39 +22,32 @@ done
|
||||
|
||||
## Agent Map
|
||||
|
||||
| Agent | CT | Node | IP | LiteLLM Alias | Key Source | Platform |
|
||||
|-------|-----|------|-----|---------------|------------|----------|
|
||||
| Koby | 111 | amdpve | .129 | `koby` | Infisical vault | **Hermes** |
|
||||
| Koonimo | 113 | amdpve | .114 | `koonimo` | Infisical vault | Hermes |
|
||||
| Shumba | — | 192.168.68.119 | N/A | N/A (DeepSeek) | Hermes (RETIRED — CT119 now Infisical vault) |
|
||||
|
||||
> **Note**: CT hostnames (tdunna→CT111, baggy→CT113) differ from agent identities (koby, koonimo).
|
||||
| Agent | CT | Node | IP | LiteLLM Key | LiteLLM Alias | Platform |
|
||||
|-------|-----|------|-----|-------------|---------------|----------|
|
||||
| Tanko | 112 | amdpve | .122 | `sk-CggiHWlamQyShxWC3Hx6uw` | `tanko` | Hermes |
|
||||
| Mumuni | 114 | minipve | .123 | `sk-VrqCNlwUgzoNGOpikJ7nwQ` | `mumuni` | Hermes |
|
||||
| Tdunna | 111 | amdpve | srv1079750 | `sk-Qvzi4uYQBhlSK_XstEhcyQ` | `tdunna` | **pi** |
|
||||
| Baggy | 113 | amdpve | ? | `sk-krnw_zGBwvvL5b7l2t-s-A` | `baggy` | Hermes |
|
||||
|
||||
Access: `pct-run <CT_ID> <command>` — no IPs needed. GPU hosts (.8, .110, .15) use SSH.
|
||||
Keys are stored in Infisical vault (project=agents, env=production) and injected at
|
||||
runtime via `infisical run --` wrapper. Plaintext keys removed from this baseline.
|
||||
|
||||
## Key Architecture
|
||||
|
||||
```
|
||||
Infisical vault → infisical run -- hermes gateway → LITELLM_API_KEY (runtime)
|
||||
↓
|
||||
Agent (systemd) → LITELLM_API_KEY → LiteLLM (:116/v1) → GPU (llama-server)
|
||||
└── Key DB (Postgres)
|
||||
Agent (systemd) → LITELLM_API_KEY → LiteLLM (:116/v1) → Router (:9000) → GPU (llama-server)
|
||||
└── Key DB (Postgres)
|
||||
```
|
||||
|
||||
- **Master key**: stored in Infisical vault (project=infrastructure, secret=LITELLM_MASTER_KEY) — ADMIN ONLY
|
||||
- **Master key**: `sk-litellm-7f96080dd99b15c36bd4b333b58a6796` — ADMIN ONLY, never in agent configs
|
||||
- **Agent keys**: Each agent has a dedicated key in LiteLLM's database with alias matching the agent name
|
||||
- **Key injection**: `infisical run --project=agents --env=production -- hermes gateway run` injects `LITELLM_API_KEY` at runtime
|
||||
- **Key source**: Infisical vault → runtime env var. /etc/environment is CLEAN (stripped, tagged `# [INFISICAL]`)
|
||||
- **Legacy override** (pre-migration): `/home/jerome/.config/systemd/user/hermes-gateway.service.d/env.conf` — should be REMOVED
|
||||
- **Key source**: `/etc/environment` → `LITELLM_API_KEY=sk-...` (systemd service sources this)
|
||||
- **Override**: `/home/jerome/.config/systemd/user/hermes-gateway.service.d/env.conf` (if present, must match)
|
||||
|
||||
## Config Pattern — Mandatory Fields
|
||||
|
||||
### For Hermes Agents (Mumuni, Koonimo)
|
||||
### For Hermes Agents (Tanko, Mumuni, Baggy)
|
||||
|
||||
Every Hermes agent's `/root/.hermes/config.yaml` (or `/home/jerome/.hermes/config.yaml`) MUST have:
|
||||
(Tanko is excluded — migrated to DSH/DeepSeek Harness on 2026-08-27, no longer uses Hermes config.)
|
||||
Every agent's `/root/.hermes/config.yaml` (or `/home/jerome/.hermes/config.yaml`) MUST have:
|
||||
|
||||
### 1. Main Model
|
||||
```yaml
|
||||
@@ -70,7 +63,7 @@ model:
|
||||
custom_providers:
|
||||
- name: harness
|
||||
model: syslog-auto
|
||||
base_url: http://192.168.68.116/litellm/v1
|
||||
base_url: http://192.168.68.116/v1
|
||||
api_key_env: LITELLM_API_KEY
|
||||
api_mode: chat_completions
|
||||
```
|
||||
@@ -81,9 +74,9 @@ auxiliary:
|
||||
vision:
|
||||
provider: harness
|
||||
model: gemma-4-12b # or syslog-auto
|
||||
base_url: http://192.168.68.116/litellm/v1
|
||||
base_url: http://192.168.68.116/v1
|
||||
api_key_env: LITELLM_API_KEY
|
||||
api_key: <value from: infisical secrets get LITELLM_API_KEY --project=agents --env=production> # ← MANDATORY workaround
|
||||
api_key: <ACTUAL_KEY_FROM_/etc/environment> # ← MANDATORY workaround
|
||||
timeout: 60
|
||||
download_timeout: 30
|
||||
```
|
||||
@@ -96,9 +89,9 @@ auxiliary:
|
||||
target_ratio: 0.3
|
||||
provider: harness
|
||||
model: syslog-auto # or gemma-4-12b
|
||||
base_url: http://192.168.68.116/litellm/v1
|
||||
base_url: http://192.168.68.116/v1
|
||||
api_key_env: LITELLM_API_KEY
|
||||
api_key: <value from: infisical secrets get LITELLM_API_KEY --project=agents --env=production> # ← MANDATORY workaround
|
||||
api_key: <ACTUAL_KEY_FROM_/etc/environment> # ← MANDATORY workaround
|
||||
timeout: 120
|
||||
```
|
||||
|
||||
@@ -117,7 +110,8 @@ LiteLLM/harness will fail with:
|
||||
401: LiteLLM Virtual Key expected. Received=no-k****ired, expected to start with 'sk-'
|
||||
```
|
||||
|
||||
**Workaround**: Set `api_key` directly (copy the value from Infisical vault: `infisical secrets get LITELLM_API_KEY --project=agents --env=production`) alongside `api_key_env` in every auxiliary task config that uses the harness provider.
|
||||
**Workaround**: Set `api_key` directly (copy the value from `/etc/environment`) alongside
|
||||
`api_key_env` in every auxiliary task config that uses the harness provider.
|
||||
|
||||
**Permanent fix**: Patch `_resolve_task_provider_model()` to resolve `api_key_env` when
|
||||
`api_key` is empty:
|
||||
@@ -135,11 +129,7 @@ if not cfg_api_key:
|
||||
```bash
|
||||
for ct in 112 114 111 113; do
|
||||
echo "=== CT $ct ==="
|
||||
# Verify /etc/environment is CLEAN (no LITELLM_API_KEY)
|
||||
pct-run $ct "grep -c LITELLM_API_KEY /etc/environment 2>/dev/null || echo '0 (clean)'"
|
||||
# Verify gateway uses infisical run wrapper
|
||||
pct-run $ct "ps aux | grep 'infisical run' | grep -v grep"
|
||||
# Check for hardcoded harness keys
|
||||
pct-run $ct grep LITELLM_API_KEY /etc/environment
|
||||
pct-run $ct grep "api_key: sk-" /root/.hermes/config.yaml | grep -v api_key_env
|
||||
echo ""
|
||||
done
|
||||
@@ -147,17 +137,15 @@ done
|
||||
|
||||
### Master Key Leak Check
|
||||
```bash
|
||||
# On every agent — must return empty:
|
||||
pct-run <CT> grep -rl "sk-litellm" /root/ /etc/ 2>/dev/null
|
||||
# Vault is the only place the master key should exist
|
||||
# On every agent:
|
||||
pct-run <CT> grep -rl "sk-litellm-7f96080dd" /root/ /etc/ 2>/dev/null
|
||||
# Must return empty
|
||||
```
|
||||
|
||||
### Verify Key Works
|
||||
```bash
|
||||
# Retrieve key from vault and test:
|
||||
KEY=$(infisical secrets get LITELLM_API_KEY --project=agents --env=production --plain)
|
||||
curl -s http://192.168.68.116:80/v1/models \
|
||||
-H "Authorization: Bearer $KEY" | grep syslog-auto
|
||||
-H "Authorization: Bearer <AGENT_KEY>" | grep syslog-auto
|
||||
# Must return model list
|
||||
```
|
||||
|
||||
@@ -168,36 +156,22 @@ pct-run <CT> grep -A8 "vision:" /root/.hermes/config.yaml | grep api_key
|
||||
# Must show both api_key: sk-... and api_key_env: LITELLM_API_KEY
|
||||
```
|
||||
|
||||
### For Koby (CT 111 / tdunna) — **REPORT-ONLY MODE**
|
||||
### For pi Agents (Tdunna)
|
||||
|
||||
Koby runs Hermes on CT 111 (tdunna). Config files at `/root/.hermes/config.yaml`.
|
||||
Same Hermes pattern as Tanko/Mumuni/Koonimo — see config sections above.
|
||||
|
||||
**⛔ KOBY IS NEVER REPAIRED (2026-08-17, Captain)**: Diagnostic only — detect and report, never fix on .129.
|
||||
No heal step, no restart, no key rotation, no config edit, no memory rewrite, no disk GC, no service touch, no process kill — ever.
|
||||
If a health check shows Koby degraded, **DO NOT** execute any repair action. Instead, report to Zulip and let Theo fix it.
|
||||
|
||||
**LiteLLM key**: alias `koby` in LiteLLM DB, injected via `infisical run --` wrapper.
|
||||
|
||||
### For pi Agents (Abiba)
|
||||
|
||||
Abiba (CT100) runs pi via PM2 with the Zulip extension.
|
||||
Tdunna (CT111) runs pi 0.80.3 via PM2 with the Zulip extension (router-worker architecture).
|
||||
Config files: `~/.pi/agent/models.json`, `~/.pi/agent/settings.json`.
|
||||
|
||||
**models.json** — Must only list models authorized for the agent's LiteLLM key.
|
||||
Key is injected via `infisical run --` wrapper at PM2 startup:
|
||||
**models.json** — Must only list models authorized for the agent's LiteLLM key:
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"syslog-harness": {
|
||||
"baseUrl": "http://192.168.68.116/v1",
|
||||
"api": "openai-completions",
|
||||
"apiKey": "${LITELLM_API_KEY}",
|
||||
"apiKey": "sk-...",
|
||||
"models": [
|
||||
{ "id": "syslog-auto" },
|
||||
{ "id": "strix-moe" },
|
||||
{ "id": "gpu-dense" },
|
||||
{ "id": "gpu-light" },
|
||||
{ "id": "ornith-1.0-35b" },
|
||||
{ "id": "qwen3.6-27B-code" },
|
||||
{ "id": "gemma-4-12b" }
|
||||
]
|
||||
@@ -283,6 +257,6 @@ If they differ → ghost detected → kill ghost → start fresh.
|
||||
|
||||
| Date | Change |
|
||||
|------|--------|
|
||||
| 2026-07-08 | Koby: fixed model mismatch (qwen3.6-35B-A3B→syslog-auto), added config section. Key rotated and stored in vault. Added Failure Mode #11 to zulip-adapter-lessons. |
|
||||
| 2026-07-08 | Tdunna: fixed model mismatch (qwen3.6-35B-A3B→syslog-auto), added pi-specific config section. Key updated to sk-Qvzi4uYQBhlSK_XstEhcyQ. Added Failure Mode #11 to zulip-adapter-lessons. |
|
||||
| 2026-07-06 | Port conflict detection added to all 3 GPU wrappers. Consolidated health check script deployed. Zulip streaming edit_message enabled for Tanko/Mumuni. |
|
||||
| 2026-07-05 | Baseline created. All 4 agents audited, master key removed, api_key workaround applied |
|
||||
|
||||
+57
-220
@@ -5,38 +5,35 @@ description: >
|
||||
Standard Hermes configuration template for Syslog Solution LLC agents.
|
||||
Enforces shared infrastructure setup (Firecrawl, SearXNG, local models,
|
||||
RA-H OS MCP) while keeping agent-specific API keys and model choices.
|
||||
UPDATED 2026-08-07: Added Rule 15 (MCP Validation) from the 2026-08-07 keyless-MCP incident.
|
||||
Added Rule 12 (Context-Issue Diagnostic) + Rule 13 (.env fallback enforcement) from the
|
||||
2026-07-16 Mumuni root-cause investigation (WAL #1300).
|
||||
UPDATED 2026-07-12: GPU workload redistributed. Compression → Strix Halo. RTX 3090 context verified at 128K. Infisical .env fallback required (Rule 3/13).
|
||||
Updated 2026-07-08: GPU context reduced to 128K on NVIDIA (.8, .110),
|
||||
parallel 2 on all GPUs, LiteLLM timeouts tuned, context_length guidance added.
|
||||
---
|
||||
|
||||
## Maintains
|
||||
|
||||
- template_version: "2.1.0"
|
||||
- last_applied: timestamp
|
||||
- agents_configured: ["mumuni", "abiba", "koby", "koonimo", "kagenz0"] # tanko removed 2026-08-27 (now on DSH/DeepSeek Harness)
|
||||
- agents_configured: ["tanko", "mumuni", "abiba", "tdunna", "baggy", "kagenz0"]
|
||||
- agent_keys: map (see Agent Keys section)
|
||||
- infra_endpoints_verified: array
|
||||
|
||||
## Agent Keys (LiteLLM — Current 2026-07-11)
|
||||
## Agent Keys (LiteLLM — Current 2026-07-04)
|
||||
|
||||
Each agent has a unique LiteLLM API key (virtual key) generated against the LiteLLM
|
||||
PostgreSQL DB via `POST /key/generate` on CT 116. Keys are stored in the DB.
|
||||
The env var `LITELLM_API_KEY` is injected at runtime via `infisical run --` wrapper
|
||||
(project=agents, env=production). /etc/environment and ~/.hermes/.env are NO LONGER
|
||||
used for agent keys — stripped and tagged `# [INFISICAL]` post-migration.
|
||||
PostgreSQL DB via `POST /key/generate` on CT 116. Keys are stored in the DB, not in
|
||||
config files. The env var `LITELLM_API_KEY` is set in `/etc/environment` on each agent
|
||||
host AND in `~/.hermes/.env` for gateway env propagation.
|
||||
Sub-agent profiles inherit auth from the main config — no separate keys needed.
|
||||
|
||||
| Agent | Key Alias | Host | SSH | Sub-Agents |
|
||||
|-------|-----------|------|-----|-----------|
|
||||
| Abiba | `abiba-pi` | 192.168.68.24 | local | — |
|
||||
| Koby | `koby` | CT 111 (tdunna) | Zulip | — |
|
||||
| Koonimo | `koonimo` | CT 113 (baggy) | SSH root | — |
|
||||
| Tanko | `tanko-*` | 192.168.68.122 | jerome@.122 | — |
|
||||
| Mumuni | `mumuni-jul2026` | 192.168.68.123 | root@.123 | 6 profiles ✱ |
|
||||
| Abiba | `abiba-*` | 192.168.68.24 | local | — |
|
||||
| Tdunna | `tdunna-*` | ? | Zulip | — |
|
||||
| Baggy | `baggy-*` | ? | Zulip | — |
|
||||
| Kagenz0 | `kagenz0-*` | ? | Zulip | — |
|
||||
|
||||
> CT hostnames (tdunna, baggy) differ from agent identities (koby, koonimo).
|
||||
|
||||
✱ Mumuni sub-agents: syslog-code, syslog-devops, syslog-email, syslog-research,
|
||||
syslog-review, syslog-writer — all at `/root/.hermes/profiles/<name>/config.yaml`
|
||||
|
||||
@@ -45,7 +42,7 @@ Sub-agent profiles inherit auth from the main config — no separate keys needed
|
||||
| Component | Endpoint | Purpose |
|
||||
|---|---|---|
|
||||
| Firecrawl | `http://192.168.68.7:3002/` | Web content extraction |
|
||||
| SearXNG | `http://192.168.68.7:8888` | Privacy-respecting web search |
|
||||
| SearXNG | `http://storepve:8888` | Privacy-respecting web search |
|
||||
| LiteLLM | `http://192.168.68.116/v1` | Unified model gateway (via nginx) |
|
||||
| LiteLLM (NetBird) | `https://litellm.sysloggh.net/v1` | Alternative (may have 502 issues) |
|
||||
| RA-H OS MCP | `http://192.168.68.65:3100/mcp` | Knowledge graph bridge |
|
||||
@@ -54,12 +51,11 @@ Sub-agent profiles inherit auth from the main config — no separate keys needed
|
||||
## API Key Rules
|
||||
|
||||
- `api_key_env: LITELLM_API_KEY` — Use env var for main model auth (preferred)
|
||||
Key is injected at runtime via `infisical run --` wrapper — never in /etc/environment
|
||||
- `api_key: ''` — Sub-agents leave empty to inherit from main config's custom_provider
|
||||
- `api_key: sk-...` — Hardcoded key only as fallback when env var not possible
|
||||
- Store `LITELLM_API_KEY` in Infisical vault (project=agents, env=production)
|
||||
- Set `LITELLM_API_KEY` in `/etc/environment` on each host
|
||||
- Sub-agents NEVER get their own key — they share the host agent's key
|
||||
- Restart Hermes gateway after updating vault secret (key auto-injected via wrapper)
|
||||
- Restart Hermes after updating `/etc/environment`
|
||||
|
||||
### Sub-Agent Profiles (Mumuni pattern)
|
||||
|
||||
@@ -83,7 +79,7 @@ Sub-agent profile rules:
|
||||
5. **Auxiliary tasks** (vision, compression, etc.) also leave `api_key` empty
|
||||
6. **Never hardcode a key** in sub-agent profiles
|
||||
|
||||
This ensures all 6 sub-agents use the same LiteLLM key injected via `infisical run --` wrapper.
|
||||
This ensures all 6 sub-agents use the same LiteLLM key set in `/etc/environment`.
|
||||
When the key is rotated, only the env var needs updating — all 7 configs (main + 6 subs)
|
||||
work immediately after restart.
|
||||
|
||||
@@ -92,17 +88,13 @@ work immediately after restart.
|
||||
```yaml
|
||||
# ─── Model Selection ───
|
||||
model:
|
||||
default: <agent_model> # e.g., strix-moe, qwen3.6-27B-code, syslog-auto
|
||||
default: <agent_model> # e.g., ornith-1.0-35b, qwen3.6-27B-code
|
||||
provider: harness
|
||||
base_url: http://192.168.68.116/litellm/v1 # Rule 5 (2026-08-09): canonical authenticated path; /v1 also OK
|
||||
api_key_env: LITELLM_API_KEY # Injected via infisical run -- wrapper
|
||||
base_url: http://192.168.68.116/v1
|
||||
api_key_env: LITELLM_API_KEY # Set in /etc/environment AND ~/.hermes/.env
|
||||
max_tokens: 4096 # ⚠️ CRITICAL: Prevents unbounded generation
|
||||
context_length: 131072 # For syslog-auto (all GPUs at 128K for stability).
|
||||
# ⚠️ MANDATORY: Hermes probes unknown models from 256K
|
||||
# and falls back to 256K when /v1/models lacks a context
|
||||
# field (llama-server does). Without this override, agents
|
||||
# silently run syslog-auto at 256K (verified 2026-08-09).
|
||||
# Set 65536 if using gemma-4-12b directly (tight VRAM).
|
||||
context_length: 262144 # For syslog-auto (ornith route supports 256K).
|
||||
# Set 131072 if using qwen3.6-27B-code or gemma-4-12b directly.
|
||||
|
||||
fallback_providers:
|
||||
provider: deepseek
|
||||
@@ -131,9 +123,10 @@ mcp_servers:
|
||||
# ─── Compression ───
|
||||
compression:
|
||||
enabled: true
|
||||
model: syslog-auto # ⚠️ Must match auxiliary.compression.model. Stable alias (gpu-fleet § Stable Role-Based Aliases). NOT ornith-1.0-35b (LiteLLM does not serve that name).
|
||||
model: gemma-4-12b # ⚠️ Must match auxiliary.compression.model
|
||||
provider: harness
|
||||
max_context_window: 131072 # MUST match actual GPU capacity. All 3 GPUs are 128K (Jul 17).
|
||||
max_context_window: 262144 # For syslog-auto (ornith supports 256K).
|
||||
# Set 131072 if using qwen or gemma directly.
|
||||
threshold: 0.65 # Fires at ~170K for 262K window, ~85K for 128K
|
||||
target_ratio: 0.30
|
||||
protect_last_n: 40
|
||||
@@ -143,49 +136,38 @@ compression:
|
||||
|
||||
# ─── Auxiliary Tasks (CONSISTENCY RULE) ───
|
||||
# All auxiliary services MUST use identical model, base_url, and api_key_env:
|
||||
# model: gpu-light # stable alias (NOT raw "gemma-4-12b")
|
||||
# base_url: http://192.168.68.116/litellm/v1 # Rule 5 (2026-08-09): canonical authenticated; /v1 also OK
|
||||
# model: gemma-4-12b
|
||||
# base_url: http://192.168.68.116/v1
|
||||
# api_key_env: LITELLM_API_KEY
|
||||
# Do NOT use syslog-auto for auxiliary tasks — it routes to the primary GPU.
|
||||
# gpu-light = RTX 5070 (12B), freeing the Strix Halo for agent reasoning.
|
||||
# Heavy aux (delegation, x_search) use gpu-dense (RTX 3090) instead.
|
||||
# NEVER use raw model names (gemma-4-12b, qwen3.6-27B-code, qwen3.6-35B-udq4)
|
||||
# in agent configs — use the stable aliases so model swaps don't break agents.
|
||||
# gemma-4-12b is a lightweight 12B model on the RTX 5070, freeing the Strix Halo
|
||||
# for agent reasoning.
|
||||
auxiliary:
|
||||
vision:
|
||||
provider: harness
|
||||
model: gpu-light # stable alias for RTX 5070 (was raw gemma-4-12b)
|
||||
base_url: http://192.168.68.116/litellm/v1 # Rule 5 (2026-08-09): canonical authenticated; /v1 also OK
|
||||
model: gemma-4-12b
|
||||
base_url: http://192.168.68.116/v1
|
||||
api_key_env: LITELLM_API_KEY
|
||||
timeout: 60
|
||||
download_timeout: 30
|
||||
web_extract:
|
||||
provider: harness
|
||||
model: gpu-light # stable alias for RTX 5070
|
||||
base_url: http://192.168.68.116/litellm/v1 # Rule 5 (2026-08-09): canonical authenticated; /v1 also OK
|
||||
model: gemma-4-12b
|
||||
base_url: http://192.168.68.116/v1
|
||||
api_key_env: LITELLM_API_KEY
|
||||
timeout: 30
|
||||
compression:
|
||||
provider: harness
|
||||
model: syslog-auto # MUST match compression.model above. Stable alias for Strix Halo (weighted pool).
|
||||
base_url: http://192.168.68.116/litellm/v1 # Rule 5 (2026-08-09): canonical authenticated path; /v1 also OK
|
||||
model: gemma-4-12b
|
||||
base_url: http://192.168.68.116/v1
|
||||
api_key_env: LITELLM_API_KEY
|
||||
timeout: 300 # gpu-fleet: 300s for large-history summarization (was 60)
|
||||
|
||||
# ─── Delegation / Heavy Aux (use gpu-dense = RTX 3090) ───
|
||||
# delegation.model and x_search.model use gpu-dense (NOT raw qwen3.6-27B-code).
|
||||
|
||||
delegation:
|
||||
model: gpu-dense # stable alias for RTX 3090 (was raw qwen3.6-27B-code)
|
||||
provider: harness
|
||||
base_url: http://192.168.68.116/litellm/v1 # Rule 5 (2026-08-09): canonical authenticated; /v1 also OK
|
||||
api_key_env: LITELLM_API_KEY
|
||||
timeout: 60
|
||||
|
||||
# ─── Custom Provider ───
|
||||
custom_providers:
|
||||
- name: harness
|
||||
model: syslog-auto # weighted pool (default)
|
||||
base_url: http://192.168.68.116/litellm/v1 # Rule 5 (2026-08-09): canonical authenticated; /v1 also OK
|
||||
model: <agent_model>
|
||||
base_url: http://192.168.68.116/v1
|
||||
api_key_env: LITELLM_API_KEY
|
||||
api_mode: chat_completions
|
||||
```
|
||||
@@ -194,7 +176,7 @@ custom_providers:
|
||||
|
||||
When LiteLLM keys are regenerated (e.g., after infrastructure changes):
|
||||
|
||||
1. **If SSH available**: Update Infisical vault: `infisical secrets set LITELLM_API_KEY=sk-<NEW> --project=agents --env=production`, then `ssh <host> "systemctl restart hermes-gateway"`
|
||||
1. **If SSH available**: `ssh <host> "sudo sed -i 's/LITELLM_API_KEY=.*/LITELLM_API_KEY=sk-<NEW>/' /etc/environment"`
|
||||
2. **If SSH unavailable**: Send Zulip DM via abiba-bot with update command
|
||||
3. **After update**: Restart Hermes on the agent host
|
||||
4. **Verify**: `curl -H "Authorization: Bearer sk-<KEY>" http://192.168.68.116/v1/models`
|
||||
@@ -216,14 +198,7 @@ The following MUST be identical across ALL profiles:
|
||||
### Rule 3: API Keys via Environment
|
||||
- Prefer `api_key_env: LITELLM_API_KEY` over hardcoded keys
|
||||
- Hardcoded keys in config.yaml become stale after key rotation
|
||||
- Infisical vault secrets persist across config updates / reinstalls
|
||||
- **NEW (July 2026): Always keep a local `.env` fallback.** Infisical service tokens
|
||||
can expire/404 (tanko incident: token not found, gateway ran without key for hours).
|
||||
The `.env` file should have the key uncommented as a fallback:
|
||||
```
|
||||
LITELLM_API_KEY=sk-...
|
||||
# [INFISICAL] Also sourced from vault.sysloggh.net
|
||||
```
|
||||
- `/etc/environment` persists across config updates
|
||||
- Restart Hermes after env var updates
|
||||
|
||||
### Rule 4: Sub-Agent Profiles Inherit Auth
|
||||
@@ -233,15 +208,12 @@ The following MUST be identical across ALL profiles:
|
||||
- Auxiliary tasks: `api_key: ''`, `provider: harness`
|
||||
- Never hardcode a key in sub-agent profiles
|
||||
- When main config uses `api_key_env`, sub-agents automatically use it
|
||||
- This means key rotation only touches ONE vault secret (`LITELLM_API_KEY`)
|
||||
- This means key rotation only touches ONE file (`/etc/environment`)
|
||||
|
||||
### Rule 5: Main Config Base URL (UPDATED 2026-08-09)
|
||||
|- Use the authenticated LiteLLM path: `http://192.168.68.116/litellm/v1` (canonical, captain-approved migration)
|
||||
|- Legacy `http://192.68.68.116/v1` also works — nginx fronts BOTH paths with key auth
|
||||
(verified 2026-08-09: 401 without key, 200 with key, on both /v1 and /litellm/v1)
|
||||
|- Both locations have `proxy_read_timeout 600s` (verified in harness-nginx nginx.conf) —
|
||||
the old "60s timeout on /litellm/" claim was stale and is retracted
|
||||
### Rule 5: Main Config Base URL
|
||||
|- Use direct IP: `http://192.168.68.116/v1`
|
||||
|- NOT the NetBird URL (`litellm.sysloggh.net`) — can cause 502 when NetBird is down
|
||||
|- NOT the old path (`/litellm/v1`) — nginx now routes `/v1` directly
|
||||
|
||||
### Rule 6: max_tokens Is Required (Thermal Safety)
|
||||
- **Every Hermes config MUST set `model.max_tokens: 4096`** — this is non-negotiable
|
||||
@@ -251,53 +223,26 @@ The following MUST be identical across ALL profiles:
|
||||
- Apply to BOTH main config AND all sub-agent profiles
|
||||
- For agents needing longer outputs: raise to 8192, but never omit
|
||||
|
||||
### Rule 7: Auxiliary Model Consistency (UPDATED 2026-07-16)
|
||||
- Vision and web_extract use `gemma-4-12b` (RTX 5070 — 12GB, vision-optimized)
|
||||
- Compression uses `strix-moe` (stable alias for Strix Halo — 64GB, 128K ctx, compression-optimized)
|
||||
- **`strix-moe` is the only valid compression model name** — LiteLLM does NOT serve `ornith-1.0-35b`
|
||||
(it serves `strix-moe`, `qwen3.6-35B-udq4`, `gpu-dense`, `gpu-light`, `syslog-auto`, `gemma-4-12b`, `qwen3.6-27B-code`). Old configs with `ornith-1.0-35b` cause 403/model-not-found on compression calls.
|
||||
- **OPERATIONAL DECISION (2026-07-23): Use `syslog-auto` for compression across all agents.**
|
||||
The `syslog-auto` alias routes to the Strix Halo, but uses the weighted pool instead of pinning
|
||||
to `strix-moe` directly. This prevents sustained Strix Halo thermal load because the pool can
|
||||
fall back to other GPUs if Strix gets hot. Both `compression.model` and `auxiliary.compression.model`
|
||||
MUST be `syslog-auto`.
|
||||
- All auxiliary services MUST use identical routing:
|
||||
- `base_url: http://192.168.68.116/litellm/v1` (Rule 5, 2026-08-09: canonical authenticated; `/v1` also OK)
|
||||
### Rule 7: Auxiliary Model Consistency
|
||||
- All auxiliary services (vision, web_extract, compression) MUST use the same model:
|
||||
- `model: gemma-4-12b`
|
||||
- `base_url: http://192.168.68.116/v1`
|
||||
- `api_key_env: LITELLM_API_KEY`
|
||||
- **Do NOT use `syslog-auto`** for auxiliary tasks — it routes unpredictably
|
||||
- **Compression on Strix Halo**: The strix-moe alias routes to Strix Halo
|
||||
(64GB UMA, 128K context) — the designated compression GPU. This frees the
|
||||
RTX 5070 for vision and web search, and the RTX 3090 for heavy reasoning.
|
||||
- The `compression:` block's `model` MUST match `auxiliary: compression: model`
|
||||
- The `compression: max_context_window: 131072` MUST match actual GPU capacity (128K)
|
||||
- **Do NOT use `syslog-auto`** for auxiliary tasks — it routes to the primary 35B reasoning GPU
|
||||
- gemma-4-12b is a lightweight 12B model on the RTX 5070, keeping the Strix Halo free for reasoning
|
||||
- The `compression:` block's `model` MUST match `auxiliary: compression: model` — they are two different configs for the same service
|
||||
|
||||
### Rule 8: GPU Workload Distribution (UPDATED 2026-07-16)
|
||||
- **RTX 3090 (24GB, 128K ctx, qwen3.6-27B-code)**: Heavy reasoning, code gen, long conversations
|
||||
- **RTX 5070 (12GB, 128K ctx, gemma-4-12b)**: Vision, web search, quick tasks, web_extract (IQ4_NL+MTP, ~65% VRAM at 128K)
|
||||
- **Strix Halo (64GB, 128K ctx, syslog-auto)**: Context compression, summarization, long docs
|
||||
- Agent profiles MUST route auxiliary tasks to the correct GPU:
|
||||
- `auxiliary.vision.model: gemma-4-12b` (RTX 5070)
|
||||
- `auxiliary.web_extract.model: gemma-4-12b` (RTX 5070)
|
||||
- `auxiliary.compression.model: syslog-auto` (Strix Halo)
|
||||
- Default model (`model.default`) and custom_provider remain `syslog-auto` for auto-routing
|
||||
- For 128K context window: `threshold: 0.65` (fires at ~85K tokens)
|
||||
### Rule 8: Compression Threshold for 256K Models
|
||||
- For 262K context window: `threshold: 0.65` (fires at ~170K tokens)
|
||||
- Do NOT use `threshold: 0.25` — this fires at 65K, causing premature context loss
|
||||
- Do NOT use `threshold: 0.80` — this delays until ~105K, leaving only 23K margin
|
||||
- `max_context_window: 131072` MUST match the model's actual capacity (128K)
|
||||
- Do NOT use `threshold: 0.80` — this delays until 209K, risking the gateway hygiene layer
|
||||
- `max_context_window: 262144` MUST match the model's actual capacity
|
||||
- See `devops-hermes-compression` skill for full reference
|
||||
|
||||
### Rule 9: Compression Threshold for 128K Models
|
||||
- For 128K context window: `threshold: 0.65` (fires at ~85K tokens)
|
||||
- Do NOT use `threshold: 0.25` — this fires at 65K, causing premature context loss
|
||||
- Do NOT use `threshold: 0.80` — this delays until ~105K, leaving only 23K margin
|
||||
- `max_context_window: 131072` MUST match the model's actual capacity (all GPUs = 128K)
|
||||
- See `devops-hermes-compression` skill for full reference
|
||||
|
||||
### Rule 10: Default Model Must Be `syslog-auto` (All Agents)
|
||||
- **Koby Exception**: Per captain ruling 2026-08-11, Koby is a DeepSeek-primary external agent; its primary model remains `deepseek-v4-flash` (via api.deepseek.com to preserve DeepSeek-specific reasoning, while other sections follow Rule 10.
|
||||
### Rule 9: Default Model Must Be `syslog-auto` (All Agents)
|
||||
- **Hermes agents**: `model.default: syslog-auto`, `custom_providers[0].model: syslog-auto`
|
||||
- **pi agents**: `defaultModel: syslog-auto` in `settings.json`, first model in `models.json`
|
||||
- `syslog-auto` is the LiteLLM routing model — it load-balances between strix-moe
|
||||
- `syslog-auto` is the LiteLLM routing model — it load-balances between ornith-1.0-35b
|
||||
and qwen3.6-27B-code, with gemma-4-12b as fallback. Using it protects against:
|
||||
- Model name typos that cause 403 errors and silent worker failures
|
||||
- Single GPU downtime (routing falls back automatically)
|
||||
@@ -305,7 +250,7 @@ The following MUST be identical across ALL profiles:
|
||||
- **Exception**: Sub-agent profiles (Mumuni's 6 profiles) may specify explicit models
|
||||
for specialized tasks, but MUST validate those models exist in the key's authorized list
|
||||
|
||||
### Rule 11: Validate Model IDs Before Deployment (pi Agents)
|
||||
### Rule 10: Validate Model IDs Before Deployment (pi Agents)
|
||||
- After configuring a pi agent's `models.json`, verify every model ID:
|
||||
```bash
|
||||
curl -s http://192.168.68.116:4000/v1/models \
|
||||
@@ -316,114 +261,6 @@ The following MUST be identical across ALL profiles:
|
||||
- A non-existent model ID causes 403 errors that silently break the pi RPC worker
|
||||
(no `agent_end` emitted, worker stays "busy", Zulip messages pile up unprocessed)
|
||||
|
||||
### Rule 12: Context-Issue Diagnostic Checklist (ADDED 2026-07-16, WAL #1300)
|
||||
When an agent shows "context issues" (premature compression, 401s, 504s, DeepSeek fallback),
|
||||
verify ALL FOUR of these against the live config. They are the only root causes found in production:
|
||||
|
||||
1. **max_context_window correct?** — BOTH `compression.max_context_window` AND `context.max_context_window`
|
||||
MUST be `131072` (all GPUs are 128K). A value of `262144` causes instability near 100K and must NOT be used.
|
||||
~83K instead of ~170K. Check: `grep -n max_context_window ~/.hermes/config.yaml`
|
||||
2. **base_url uses authenticated path?** — `custom_providers[0].base_url`, `delegation.base_url`,
|
||||
and ALL `auxiliary.*.base_url` MUST be `http://192.168.68.116/litellm/v1` (Rule 5, canonical)
|
||||
or `http://192.168.68.116/v1` (legacy, still authenticated via nginx). BOTH verified 200 with
|
||||
key + 600s proxy_read_timeout on 2026-08-09. Never bare `:4000` direct.
|
||||
Check: `grep -nE 'base_url: http://192.168.68.116(:4000)?/v1' ~/.hermes/config.yaml` — the
|
||||
ONLY paths allowed are `/v1` or `/litellm/v1` (both via nginx :80).
|
||||
`:4000` or missing `litellm/v1`/`v1` prefix = violation.
|
||||
3. **LITELLM_API_KEY valid?** — The key must be a real LiteLLM key (`sk-` + 64 hex, 67 chars).
|
||||
Malformed values (e.g. `sk-_SWAl_Vu_…`, 47 chars) return 401 → DeepSeek fallback.
|
||||
Verify: `curl -s -o /dev/null -w '%{http_code}' -H "Authorization: Bearer $LITELLM_API_KEY" http://192.168.68.116/v1/models` (must be 200)
|
||||
4. **custom_providers aligned?** — `model: syslog-auto` (Rule 10), `api_mode: chat_completions`
|
||||
(NOT `responses`). A wrong api_mode causes silent request failures.
|
||||
|
||||
One-line agent health check (run on the agent host):
|
||||
```bash
|
||||
# Use grep -v infisical to avoid matching the bash wrapper that contains the same string
|
||||
PID=$(pgrep -f "python -m hermes_cli.main gateway run" | grep -v infisical | head -1)
|
||||
cat /proc/$PID/environ | tr '\0' '\n' | grep ^LITELLM_API_KEY= | sed 's/=.*/<set>/'
|
||||
curl -s -o /dev/null -w 'key_health: %{http_code}\n' -H "Authorization: Bearer $(cat /proc/$PID/environ | tr '\0' '\n' | grep ^LITELLM_API_KEY= | cut -d= -f2)" http://192.168.68.116/v1/models
|
||||
```
|
||||
|
||||
### Rule 13: API Key Injection — Two Patterns (UPDATED 2026-07-16, WAL #1300)
|
||||
|
||||
### Rule 14: Hermes Context Detection Uses `max_model_tokens`, NOT `max_input_tokens`
|
||||
|
||||
**CRITICAL**: Hermes context detection reads `max_model_tokens` (128K), NOT `max_input_tokens` (64K cap).
|
||||
|
||||
- **Abiba and Hermes agents**: `max_model_tokens: 131072` (128K) — unlimited context
|
||||
- **Crewmates (ops, tune, verify, auth-keys, build)**: `max_input_tokens: 64000` (64K) — capped
|
||||
- If you see `max_input_tokens: 64000` in an Abiba/Hermes config, that's a mistake
|
||||
- Using `max_input_tokens` for Hermes agents causes premature context loss
|
||||
- Check: `grep -n 'max_model_tokens\|max_input_tokens' ~/.hermes/config.yaml`
|
||||
- Expected output: `max_model_tokens: 131072` (not max_input_tokens)
|
||||
|
||||
Agents inject `LITELLM_API_KEY` via ONE of two mechanisms. Both are valid; the contract
|
||||
requirement is that the key is a **valid LiteLLM virtual key** (HTTP 200 on /v1/models).
|
||||
|
||||
**Pattern A — systemd drop-in (Koby, Koonimo, and any agent without infisical wrapper):**
|
||||
A systemd drop-in `/etc/systemd/system/hermes-gateway.service.d/litellm-key.conf` sets the key:
|
||||
```ini
|
||||
[Service]
|
||||
Environment="LITELLM_API_KEY=sk-<VALID_KEY>"
|
||||
```
|
||||
The service unit `hermes-gateway.service` runs `python -m hermes_cli.main gateway run --replace`
|
||||
directly (no infisical). Apply with `systemctl daemon-reload && systemctl restart hermes-gateway`.
|
||||
- Koonimo (CT113/.114): service = `hermes-gateway.service`, drop-in has the key.
|
||||
- Koby (CT111/.129): service = `hermes-gateway.service` (created 2026-07-16), ExecStart uses `--replace`
|
||||
to win the lock against stray `hermes gateway restart` invocations. Key also in `/etc/environment`.
|
||||
|
||||
**Pattern B — infisical-gateway.sh wrapper (Mumuni):**
|
||||
The wrapper sources `~/.hermes/.env` then exports `LITELLM_API_KEY="$<AGENT>_LITELLM_API_KEY"`.
|
||||
See litellm-api-keys.prose.md § Machine Identity for Vault Writes for vault sync.
|
||||
|
||||
**⚠️ Vault empty-key guard:** If the vault stores the secret as an empty string,
|
||||
the wrapper will inject an empty key and the gateway will silently get 401 errors
|
||||
on all LiteLLM requests (triggering silent DeepSeek fallback). The `.env` fallback
|
||||
is present but the vault takes precedence when the secret key exists (even if empty).
|
||||
|
||||
**Fix:** The wrapper MUST validate the key length after injection. If LITELLM_API_KEY
|
||||
is empty or shorter than 20 chars, log a warning and either fail with a clear error
|
||||
message or fall back to the `.env` value before starting the gateway.
|
||||
|
||||
**Verification (all agents):**
|
||||
```bash
|
||||
# Use grep -v infisical to avoid matching the bash wrapper that contains the same string
|
||||
GP=$(pgrep -f "python -m hermes_cli.main gateway run" | grep -v infisical | head -1)
|
||||
K=$(cat /proc/$GP/environ | tr '\0' '\n' | grep '^LITELLM_API_KEY=' | cut -d= -f2)
|
||||
curl -s -o /dev/null -w '%{http_code}' -H "Authorization: Bearer $K" http://192.168.68.116/v1/models # must be 200
|
||||
```
|
||||
- `/etc/environment` is NO LONGER the canonical key source (stale values there caused 401s).
|
||||
- Do NOT leave a hardcoded stale key in `/etc/environment` — it shadows the drop-in/wrapper.
|
||||
|
||||
### Rule 14: Provider Name Must Match custom_providers Name (ADDED 2026-07-19, WAL #1471)
|
||||
|
||||
- `model.provider` MUST be `harness` (the `custom_providers[0].name`), NOT the literal string `custom`
|
||||
- When `provider: custom`, Hermes' `_get_named_custom_provider("custom")` returns None (no provider is
|
||||
named "custom" — it is named "harness"), causing a fall-through to the generic resolution path
|
||||
(`source: env/config`) at `runtime_provider.py:1156`
|
||||
- The generic path builds `api_key_candidates` from `model.api_key` (empty), host-gated
|
||||
OLLAMA/OPENAI/OPENROUTER keys, and `_host_derived_api_key` (returns "" for IP addresses)
|
||||
- **The generic path does NOT resolve `model.api_key_env` or `custom_providers.key_env`** —
|
||||
`LITELLM_API_KEY` is never read, producing `api_key = "no-key-required"` → HTTP 401
|
||||
- The named custom provider path (`source: custom_provider:harness`) DOES read `key_env` —
|
||||
but only triggers when `provider` matches the `custom_providers[0].name`
|
||||
- All sections MUST use `provider: harness`: `model`, `compression`, `auxiliary.vision`,
|
||||
`auxiliary.web_extract`, `auxiliary.compression`, `delegation`
|
||||
- Only `fallback_providers` uses a different provider (`deepseek`) for true fallback diversity
|
||||
- **Diagnostic**: If you see `source: env/config` in a request dump or log, the provider name
|
||||
is wrong. It should be `source: custom_provider:harness`.
|
||||
- **Audit script**: Run `python3 /root/prose-contracts/audit-hermes-config.py <config.yaml>`
|
||||
before and after any config change to catch this and all other rule violations.
|
||||
|
||||
### Rule 15: MCP Endpoint and Header Validation (ADDED 2026-08-07)
|
||||
- Every MCP server entry must point at the correct endpoint:
|
||||
- ra-h-os = http://192.168.68.65:3100/mcp
|
||||
- litellm = https://litellm.sysloggh.net/mcp
|
||||
- MCP entries must carry a REAL key value in the header.
|
||||
- Avoid using env-var names like LITELLM_API_KEY in the header; they do not resolve for MCP
|
||||
endpoints and result in "Malformed API Key" floods.
|
||||
- Ensure the header value is the actual key (e.g., `sk-...`).
|
||||
|
||||
## Execution
|
||||
|
||||
1. **Check current config** — Read the target agent's config.yaml
|
||||
|
||||
+51
-128
@@ -5,10 +5,8 @@ version: 1.0.0
|
||||
description: >
|
||||
Enforces standardized API key configuration across all Hermes agents. Harness/LiteLLM
|
||||
providers MUST use api_key_env indirection. External providers (DeepSeek, OpenAI,
|
||||
Anthropic) may use hardcoded keys. Single source of truth: Infisical vault
|
||||
(project=agents, env=production) — injected at runtime via `infisical run --` wrapper.
|
||||
/etc/environment is DEPRECATED for agent keys post-migration. Designed to make key
|
||||
rotation a one-step vault operation.
|
||||
Anthropic) may use hardcoded keys. Single source of truth: /etc/environment on each
|
||||
agent host. Designed to make key rotation a one-step operation.
|
||||
author: Abiba (pi agent)
|
||||
---
|
||||
|
||||
@@ -16,7 +14,7 @@ author: Abiba (pi agent)
|
||||
|
||||
## Rule (One Sentence)
|
||||
|
||||
**All harness/litellm providers MUST use `api_key_env: LITELLM_API_KEY` with authenticated path `http://192.168.68.116/litellm/v1/responses` — hardcoded keys AND unauthenticated `/v1` direct access are both forbidden.**
|
||||
**Any `api_key` pointing to a Syslog-hosted LiteLLM/harness provider MUST be replaced with `api_key_env: LITELLM_API_KEY` — hardcoded harness keys are forbidden.**
|
||||
|
||||
## Scope
|
||||
|
||||
@@ -28,40 +26,6 @@ Applies to all Hermes agent configs across all hosts. Covers these config sectio
|
||||
- `compression.api_key` (when `provider` is `harness` or contains `litellm`)
|
||||
- `fallback_providers[].api_key` (when provider is harness)
|
||||
|
||||
## Architecture (2026-07-10)
|
||||
|
||||
Syslog is migrating away from **unauthenticated direct access** to the shared inference harness.
|
||||
|
||||
| Path | Auth | Status |
|
||||
|------|------|--------|
|
||||
| `http://192.168.68.116/v1` | Bearer `sk-*` key (nginx-fronted) | ✅ **VALID** — authenticated via nginx :80 (verified 2026-08-09: 401 without key, 200 with) |
|
||||
| `http://192.168.68.116/litellm/v1` | Bearer `sk-*` key (nginx-fronted) | ✅ **CURRENT / CANONICAL** — captain-approved migration target; 600s proxy_read_timeout (verified) |
|
||||
| `http://192.168.68.116:4000/v1` | Bearer `sk-*` key (direct container) | ❌ **FORBIDDEN** — bypasses nginx; port 4000 direct is not a config path |
|
||||
|
||||
All harness/litellm providers MUST use an authenticated nginx-fronted path (`/litellm/v1` canonical, `/v1` legacy-valid).
|
||||
Any `base_url` pointing at `:4000` or a bare IP without nginx is a **migration violation**.
|
||||
|
||||
### 🔥 CRITICAL: Double-Path Bug (2026-07-10)
|
||||
|
||||
When `api_mode: responses` is set, Hermes **appends `/v1/responses`** to `base_url`.
|
||||
If `base_url` already includes `/litellm/v1/responses`, the result is:
|
||||
|
||||
```
|
||||
http://192.168.68.116/litellm/v1/responses/v1/responses → 404
|
||||
```
|
||||
|
||||
**The `base_url` must end at `/v1` — never include `/responses`:**
|
||||
|
||||
```yaml
|
||||
# ✅ CORRECT — Hermes appends /v1/responses for api_mode: responses
|
||||
base_url: http://192.168.68.116/litellm/v1
|
||||
|
||||
# ❌ WRONG — produces double path
|
||||
base_url: http://192.168.68.116/litellm/v1/responses
|
||||
```
|
||||
|
||||
This applies to ALL sections using the harness provider: `custom_providers`, `delegation`, `auxiliary.*`.
|
||||
|
||||
## Exemptions
|
||||
|
||||
External providers are **explicitly exempt** and may use hardcoded keys:
|
||||
@@ -73,48 +37,36 @@ External providers are **explicitly exempt** and may use hardcoded keys:
|
||||
|
||||
## Standard Pattern
|
||||
|
||||
> **Canonical vault process (2026-07-16):** see `litellm-api-keys` § Production Vault Access Process.
|
||||
> All agents MUST use the `infisical-gateway.sh` wrapper (live vault injection). Hardcoded systemd
|
||||
> drop-ins / config.yaml keys are DEPRECATED — they rot on rotation (root cause of the 2026-07-16 401 storm).
|
||||
> 4/5 agents migrated; tanko (user jerome) pending.
|
||||
|
||||
```yaml
|
||||
# ✅ CORRECT — all harness/litellm providers (authenticated path, NO /responses suffix)
|
||||
# ✅ CORRECT — all harness/litellm providers
|
||||
model:
|
||||
provider: harness
|
||||
base_url: http://192.168.68.116/litellm/v1 # ← Hermes appends /v1/responses
|
||||
api_key_env: LITELLM_API_KEY
|
||||
provider: harness # or custom:litellm.sysloggh.net
|
||||
base_url: http://192.168.68.116/v1
|
||||
api_key_env: LITELLM_API_KEY # ← indirection
|
||||
|
||||
custom_providers:
|
||||
- name: harness
|
||||
api_mode: responses
|
||||
base_url: http://192.168.68.116/litellm/v1 # ← NO /responses suffix!
|
||||
api_key_env: LITELLM_API_KEY
|
||||
base_url: http://192.168.68.116/v1
|
||||
api_key_env: LITELLM_API_KEY # ← indirection
|
||||
|
||||
auxiliary:
|
||||
compression:
|
||||
provider: harness
|
||||
base_url: http://192.168.68.116/litellm/v1 # ← NO /responses suffix!
|
||||
api_key_env: LITELLM_API_KEY
|
||||
api_key_env: LITELLM_API_KEY # ← indirection
|
||||
|
||||
# ✅ ALSO CORRECT — external providers
|
||||
fallback_providers:
|
||||
- provider: deepseek
|
||||
base_url: https://api.deepseek.com
|
||||
api_key: sk-b7d9... # ← hardcoded OK (external)
|
||||
api_key_env: DEEPSEEK_API_KEY # ← also OK if set in environment (vault or /etc/environment)
|
||||
api_key_env: DEEPSEEK_API_KEY # ← also OK if set in /etc/environment
|
||||
```
|
||||
|
||||
```yaml
|
||||
# ❌ FORBIDDEN — hardcoded key (top) OR unauthenticated path (bottom)
|
||||
# ❌ FORBIDDEN — hardcoded harness/litellm key
|
||||
model:
|
||||
provider: harness
|
||||
api_key: sk-Flc62smlegyMEaSo1ka8JA # ← RULE VIOLATION: hardcoded key
|
||||
|
||||
model:
|
||||
provider: harness
|
||||
base_url: http://192.168.68.116/v1 # ← RULE VIOLATION: unauthenticated path
|
||||
api_key_env: LITELLM_API_KEY
|
||||
api_key: sk-Flc62smlegyMEaSo1ka8JA # ← RULE VIOLATION
|
||||
```
|
||||
|
||||
## Detection Query
|
||||
@@ -123,18 +75,13 @@ Run on any Hermes host to detect violations:
|
||||
|
||||
```bash
|
||||
# 1. Check config.yaml for hardcoded harness keys
|
||||
grep -rn 'api_key: sk-' /root/.hermes/ \
|
||||
grep -rn 'api_key: sk-' /home/jerome/.hermes/ \
|
||||
--include='config.yaml' \
|
||||
| grep -v 'deepseek\|openai\|anthropic\|DEEPSEEK'
|
||||
|
||||
# 1b. Check for double-path bug: base_url ending with /responses
|
||||
# (Hermes appends /v1/responses when api_mode=responses, so base_url must end at /v1)
|
||||
grep -rn 'litellm/v1/responses' /root/.hermes/config.yaml
|
||||
# ANY output here = WRONG. Must be 'litellm/v1' without /responses suffix.
|
||||
|
||||
# 2. Check systemd drop-ins for master key leaks (2026-07-05: Tanko had this)
|
||||
grep -rn 'LITELLM_API_KEY' /root/.config/systemd/user/ 2>/dev/null
|
||||
grep -rn 'LITELLM_API_KEY=sk-litellm-7f96080d' /root/.config/systemd/ 2>/dev/null
|
||||
grep -rn 'LITELLM_API_KEY' /home/jerome/.config/systemd/user/ 2>/dev/null
|
||||
grep -rn 'LITELLM_API_KEY=sk-litellm-7f96080d' /home/jerome/.config/systemd/ 2>/dev/null
|
||||
|
||||
# 3. Verify running process env matches dedicated key
|
||||
cat /proc/$(cat /home/jerome/.hermes/gateway.pid | python3 -c "import sys,json; print(json.load(sys.stdin)['pid'])")/environ \
|
||||
@@ -145,32 +92,26 @@ If any output from step 2 — **critical violation** (master key leaked). Fix im
|
||||
|
||||
## Rotation Procedure
|
||||
|
||||
With this standard enforced, key rotation is one vault update:
|
||||
With this standard enforced, key rotation is one step:
|
||||
|
||||
```bash
|
||||
# 1. Generate new key in LiteLLM: POST /key/generate with agent alias
|
||||
# 2. Update Infisical vault secret
|
||||
infisical secrets set LITELLM_API_KEY=sk-NEW_KEY \
|
||||
--project=agents --env=production
|
||||
# 3. Restart agent gateway (key auto-injected via infisical run -- wrapper)
|
||||
ssh root@<host> "systemctl restart hermes-gateway"
|
||||
# 1. Generate new key in LiteLLM
|
||||
# 2. Update /etc/environment on agent host
|
||||
ssh root@<host> "sed -i 's/LITELLM_API_KEY=.*/LITELLM_API_KEY=sk-NEW_KEY/' /etc/environment"
|
||||
# 3. Restart agent gateway
|
||||
ssh root@<host> "pkill -f 'hermes_cli.main gateway run'; sleep 2; nohup ... &"
|
||||
# 4. Verify
|
||||
curl -s -H "Authorization: Bearer sk-NEW_KEY" http://192.168.68.116/litellm/v1/models
|
||||
curl -s -H "Authorization: Bearer sk-NEW_KEY" http://192.168.68.116/v1/models
|
||||
```
|
||||
|
||||
**Done.** No config file changes needed. No /etc/environment edits needed.
|
||||
The agent picks up the new key via `infisical run --` at gateway startup.
|
||||
|
||||
> **Post-migration note**: /etc/environment is NO LONGER the key source.
|
||||
> Strip all `LITELLM_API_KEY` lines from /etc/environment (comment out with `# [INFISICAL]`)
|
||||
> and let the `infisical run --` wrapper inject the key at runtime.
|
||||
**Done.** No config file changes needed. The agent picks up the new key on restart.
|
||||
|
||||
## Key Longevity Policy (2026-07-04)
|
||||
|
||||
**Keys are permanent and use bare agent name aliases.**
|
||||
|
||||
- **Duration**: `null` — keys never expire. This is enforced by `default_key_generate_params` in `litellm_config.yaml`.
|
||||
- **Alias convention**: bare agent name only (e.g., `tanko`, `mumuni`, `koby`, `koonimo`). No dates, no versions. The alias IS the identity.
|
||||
- **Alias convention**: bare agent name only (e.g., `tanko`, `mumuni`, `tdunna`, `baggy`). No dates, no versions. The alias IS the identity.
|
||||
- **Rotation triggers**: compromise, personnel departure, or quarterly security hygiene. NOT calendar-driven.
|
||||
- **Max budget**: $100 per key (config default).
|
||||
|
||||
@@ -187,54 +128,36 @@ litellm_settings:
|
||||
|
||||
## Verified Agents (2026-07-05 update)
|
||||
|
||||
| Agent | CT | IP | LiteLLM Alias | Key Source | Status | Gateway Wrapper | Last Verified |
|
||||
|-------|-----|-----|---------------|------------|--------|-----------------|---------------|
|
||||
| Tanko | 112 | .122 | `tanko` | Infisical vault | ✅ Fixed | `infisical run` | 20:17 UTC Jul 5 |
|
||||
| Mumuni | 105 (kagentz) | .14 | `mumuni` | Infisical vault | ✅ Fixed | systemd Hermes gateway | 2026-08-29 |
|
||||
| Koby | 111 | .129 | `koby` | Infisical vault | ✅ Fixed (DeepSeek-primary) | `infisical run` | 23:30 UTC Jul 5 |
|
||||
| Koonimo | 113 | .114 | `koonimo` | Infisical vault | ✅ Fixed | `infisical run` (migrated 2026-07-11) | 2026-08-09 |
|
||||
| Abiba | 100 | .65 | `abiba-pi` | Infisical vault | ✅ N/A (pi native) | — | 19:44 UTC Jul 5 |
|
||||
| Kagenz0 | 105 | .14 | — | — | ❌ DOWN | — | 19:14 EDT Jul 4 |
|
||||
| Agent | CT | IP | LiteLLM Alias | Key | Status | Systemd Source | Last Verified |
|
||||
|-------|-----|-----|---------------|-----|--------|----------------|---------------|
|
||||
| Tanko | 112 | .122 | `tanko` | `sk-CggiHWlamQyShxWC3Hx6uw` | ✅ Fixed | User drop-in `env.conf` | 20:17 UTC Jul 5 |
|
||||
| Mumuni | 114 | .123 | `mumuni` | `sk-XY2aUfvy2BIs6kp1ZPh6VA` | ⚠️ Unverified | `/etc/environment` | 23:00 EDT Jul 4 |
|
||||
| Tdunna | 111 | ? | `tdunna` | `sk-6sbCNjz2T6lTVDBdlNHXsA` | ✅ Fixed | `/etc/environment` + drop-in | 23:30 UTC Jul 5 |
|
||||
| Baggy | 113 | ? | `baggy` | `sk-krnw_zGBwvvL5b7l2t-s-A` | ✅ Fixed | `/etc/environment` | 23:30 UTC Jul 5 |
|
||||
| Abiba | 100 | .65 | — | — | ✅ N/A (pi native) | — | 19:44 UTC Jul 5 |
|
||||
| Kagenz0 | 105 | ? | — | — | ❌ DOWN | — | 19:14 EDT Jul 4 |
|
||||
|
||||
> **Note**: CT hostnames (tdunna, baggy) differ from agent identities (koby, koonimo).
|
||||
> LiteLLM key aliases use agent identity, not CT hostname.
|
||||
### Systemd Service Pattern (2026-07-04 fix)
|
||||
|
||||
### Migration Status: Authenticated Path
|
||||
All Hermes agents use systemd to manage their gateway. Two issues were fixed:
|
||||
|
||||
| Agent | `/litellm/v1` | Legacy `/v1` | Status |
|
||||
|-------|--------------|-------------|--------|
|
||||
| Mumuni | ✅ harness provider | ✅ auxiliary on /v1 (valid) | ✅ Authenticated (verified 2026-08-09) |
|
||||
| Tanko | ✅ 5 sections | 0 | ✅ Migrated 2026-08-08, keys 200 |
|
||||
| Koby | ✅ custom provider (harness name) | — | ✅ External DeepSeek primary (intentional, captain ruling 2026-08-11) |
|
||||
| Koonimo | ✅ .114 (baggy) | — | ✅ 128K context applied 2026-08-09 |
|
||||
1. **Drop-in override** — `/etc/systemd/system/hermes-gateway.service.d/litellm-key.conf` (or user equivalent) had hardcoded `LITELLM_API_KEY` that bypassed `/etc/environment`.
|
||||
2. **Missing EnvironmentFile** — Services did not source `/etc/environment`.
|
||||
|
||||
### Systemd Service Pattern (2026-07-11 — vault migration)
|
||||
|
||||
All Hermes agents use systemd to manage their gateway. The gateway service is wrapped
|
||||
with `infisical run --` to inject secrets at runtime.
|
||||
|
||||
**Correct pattern (post-migration):**
|
||||
**Correct pattern:**
|
||||
```ini
|
||||
# Service file wraps gateway with Infisical:
|
||||
[Service]
|
||||
ExecStart=/usr/bin/infisical run --project=agents --env=production -- \
|
||||
/usr/bin/hermes gateway run
|
||||
|
||||
# /etc/environment is CLEAN — no LITELLM_API_KEY present
|
||||
# (strip it and tag with # [INFISICAL] if present)
|
||||
```
|
||||
|
||||
**Legacy pattern (deprecated — pre-migration only):**
|
||||
```ini
|
||||
# DO NOT USE post-migration:
|
||||
# In service file:
|
||||
EnvironmentFile=/etc/environment
|
||||
# This pattern was replaced by infisical run -- wrapper
|
||||
|
||||
# Drop-in only for overrides, NOT primary key storage.
|
||||
# If a drop-in exists, it must match /etc/environment.
|
||||
```
|
||||
|
||||
**Rotation procedure** (one vault operation with this standard):
|
||||
**Rotation procedure** (one step with this standard):
|
||||
1. Generate new key in LiteLLM: `curl /key/generate` with agent alias
|
||||
2. Update Infisical vault: `infisical secrets set LITELLM_API_KEY=sk-NEW --project=agents --env=production`
|
||||
3. Restart: `systemctl restart hermes-gateway` (key auto-injected via wrapper)
|
||||
2. Update `/etc/environment`: `sed -i 's/LITELLM_API_KEY=.*/LITELLM_API_KEY=sk-NEW/' /etc/environment`
|
||||
3. Update drop-in (if exists): same sed on `litellm-key.conf`
|
||||
4. Restart: `systemctl [--user] restart hermes-gateway`
|
||||
|
||||
## Violation Response
|
||||
|
||||
@@ -244,7 +167,7 @@ EnvironmentFile=/etc/environment
|
||||
4. **Restart** — gateway must restart to pick up env var
|
||||
5. **Confirm** — test key against LiteLLM: `curl -H "Authorization: Bearer $KEY" .../v1/models` → 200
|
||||
6. **Update** — bump the verified table above
|
||||
7. **Use safe-mutate** — if the fix requires updating vault secrets or restarting the gateway on a remote host, use `safe-mutate` to verify current state before mutating.
|
||||
7. **Use safe-mutate** — if the fix requires changing `/etc/environment` or restarting the gateway on a remote host, use `safe-mutate` to verify current state before mutating.
|
||||
|
||||
## Related Contracts
|
||||
|
||||
@@ -283,15 +206,15 @@ task config:
|
||||
```yaml
|
||||
auxiliary:
|
||||
vision:
|
||||
api_key: sk-<agent-key-from-vault> # ← workaround (get via: infisical secrets get LITELLM_API_KEY --project=agents --env=production --plain)
|
||||
api_key: sk-CggiHWlamQyShxWC3Hx6uw # ← workaround
|
||||
api_key_env: LITELLM_API_KEY
|
||||
base_url: http://192.168.68.116/litellm/v1
|
||||
base_url: http://192.168.68.116/v1
|
||||
model: gemma-4-12b
|
||||
provider: harness
|
||||
compression:
|
||||
api_key: sk-<agent-key-from-vault> # ← workaround (same as above)
|
||||
api_key: sk-CggiHWlamQyShxWC3Hx6uw # ← workaround
|
||||
api_key_env: LITELLM_API_KEY
|
||||
base_url: http://192.168.68.116/litellm/v1
|
||||
base_url: http://192.168.68.116/v1
|
||||
model: gemma-4-12b
|
||||
provider: harness
|
||||
```
|
||||
|
||||
@@ -28,7 +28,7 @@ connectivity recovery including end-to-end DM validation.
|
||||
|
||||
| Param | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `target` | string | yes | — | Agent name: `mumuni`, `koby`, or `shumba` (Tanko excluded — on DSH since 2026-08-27, no Hermes plugin) |
|
||||
| `target` | string | yes | — | Agent name: `mumuni`, `tanko`, or `koby` |
|
||||
| `branch` | string | no | `master` | Git branch to pull (overridable for pinning) |
|
||||
|
||||
## Maintains
|
||||
@@ -55,9 +55,9 @@ connectivity recovery including end-to-end DM validation.
|
||||
|
||||
| Host | CT | Proxmox | IP (direct) | Hermes Home | User |
|
||||
|------|-----|---------|-------------|-------------|------|
|
||||
| Tanko | CT112 | amdpve | 192.168.68.122 | /home/jerome/.hermes | jerome | *(DSH since 2026-08-27 — historical, plugin retired on this host)* |
|
||||
| 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 |
|
||||
|-------|-------|-------|
|
||||
@@ -120,8 +120,7 @@ cp plugins/platforms/zulip/adapter.py \
|
||||
plugins/platforms/zulip/plugin.yaml \
|
||||
{{hermes_home}}/hermes-agent/plugins/platforms/zulip/
|
||||
|
||||
# Fix ownership (was Tanko-only, runs as jerome user)
|
||||
# RETIRED 2026-08-27: tanko no longer uses the Hermes Zulip plugin (DSH).
|
||||
# Fix ownership (Tanko only — runs as jerome user)
|
||||
[ "{{target}}" = "tanko" ] && chown -R jerome:jerome \
|
||||
{{hermes_home}}/hermes-agent/plugins/platforms/zulip/
|
||||
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
report_only_agents:
|
||||
- koby # ⛔ KOBY IS NEVER REPAIRED (Rule 17, 2026-08-17) — detect + report, never fix on .129
|
||||
kind: function
|
||||
name: hermes-zulip-restore
|
||||
description: >
|
||||
Restores Zulip connectivity for any Hermes agent (Mumuni CT114, Tanko CT112,
|
||||
Koby CT111). Deploys the zulip-platform adapter to the correct bundled plugin
|
||||
path, verifies env credentials, restarts the gateway, and confirms Zulip
|
||||
connects. Run this whenever a Hermes agent stops responding on Zulip or after
|
||||
a fresh agent deployment.
|
||||
@@ -12,7 +12,6 @@ version: 1.0.0
|
||||
status: active
|
||||
runtime_contract: 2
|
||||
---
|
||||
---
|
||||
|
||||
# Hermes Zulip Restore — Bring Any Agent Back to Good State
|
||||
|
||||
@@ -24,7 +23,7 @@ gateway restart, and connection validation.
|
||||
|
||||
| Param | Type | Required | Default | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| `target` | string | yes | — | Agent name: `mumuni`, `koby`, or `shumba` (Tanko excluded — DSH since 2026-08-27) |
|
||||
| `target` | string | yes | — | Agent name: `mumuni`, `tanko`, or `koby` |
|
||||
|
||||
## Maintains
|
||||
|
||||
@@ -37,7 +36,7 @@ gateway restart, and connection validation.
|
||||
|
||||
- `_strip_html` function present in `<hermes-agent>/plugins/platforms/zulip/adapter.py`
|
||||
- All three adapter files (__init__.py, adapter.py, plugin.yaml) present at bundled path
|
||||
- Zulip env vars set in `~/.hermes/.env` (or `/home/jerome/.hermes/.env` for Tanko, historical — DSH since 2026-08-27)
|
||||
- Zulip env vars set in `~/.hermes/.env` (or `/home/jerome/.hermes/.env` for Tanko)
|
||||
- Gateway restarted and zulip platform reports state `connected`
|
||||
- HTML stripping enabled for `/approve` and `/deny` slash command support
|
||||
|
||||
@@ -52,8 +51,9 @@ gateway restart, and connection validation.
|
||||
|
||||
| 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 |
|
||||
|-------|-------|-------|
|
||||
@@ -93,8 +93,8 @@ cp zulip-platform-plugins/plugins/platforms/zulip/adapter.py \
|
||||
zulip-platform-plugins/plugins/platforms/zulip/plugin.yaml \
|
||||
<HERMES_HOME>/hermes-agent/plugins/platforms/zulip/
|
||||
|
||||
# Fix ownership (was Tanko-only; RETIRED 2026-08-27 — tanko on DSH, no Hermes plugin)
|
||||
chown -R jerome:jerome <HERMES_HOME>/hermes-agent/plugins/platforms/zulip/ # Tanko only (historical)
|
||||
# Fix ownership (Tanko only)
|
||||
chown -R jerome:jerome <HERMES_HOME>/hermes-agent/plugins/platforms/zulip/ # Tanko only
|
||||
|
||||
# Clean up
|
||||
rm -rf /tmp/zulip-deploy
|
||||
@@ -183,7 +183,6 @@ https://git.sysloggh.net/SyslogSolution/zulip-platform-plugins/src/branch/feat/z
|
||||
Commit `55ca15d` — `fix(zulip): add _strip_html for slash command matching`
|
||||
Pull request #33 is the primary integration branch.
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
**Last verified good state**: 2026-07-08 — Mumuni, Tanko, Koby all connected with `_strip_html` applied.
|
||||
|
||||
@@ -1,103 +0,0 @@
|
||||
---
|
||||
name: inference-optimization
|
||||
kind: responsibility
|
||||
description: >
|
||||
Optimizes the full Syslog inference stack — LiteLLM routing weights, GPU model
|
||||
assignments, agent context management, and prompt caching — to reduce response
|
||||
times to sub-15s average. All GPUs now at 128K context (stable ceiling).
|
||||
id: 067NC6KP02RG60S50M40E30928
|
||||
---
|
||||
|
||||
### Goal
|
||||
|
||||
Syslog inference response times reduced to sub-15s average by optimizing the full
|
||||
stack: LiteLLM routing weights, GPU model assignments, Hermes agent context
|
||||
management, and prompt caching — without sacrificing agent capability.
|
||||
|
||||
### Requires
|
||||
|
||||
- `inference-metrics`: current SpendLogs from CT116 LiteLLM Postgres — avg
|
||||
request_duration_ms, prompt_tokens, completion_tokens, model_group breakdown,
|
||||
cache_hit rate over the last 3 hours
|
||||
- `agent-configs`: current config.yaml from each active Hermes agent (Mumuni
|
||||
.123, any others on .129/.122) including compression, model, context_window,
|
||||
prompt_caching, memory settings
|
||||
- `gpu-health`: health check response from all 3 GPU backends (strix-moe .15:8080,
|
||||
qwen .8:8080, gemma .110:8080)
|
||||
|
||||
### Maintains
|
||||
|
||||
The optimized inference stack configuration — every change is applied and
|
||||
verified end-to-end. Postcondition: avg request_duration_ms ≤ 15000 for 90% of
|
||||
inference calls.
|
||||
|
||||
#### liteLLM-routing
|
||||
The syslog-auto routing weights, model-specific timeouts, RPM limits, and
|
||||
model_list entries on CT116 `/opt/inference-harness/litellm_config.yaml`.
|
||||
|
||||
#### agent-compression
|
||||
Each Hermes agent's `~/.hermes/config.yaml` compression, context_window,
|
||||
prompt_caching, and model sections.
|
||||
|
||||
#### prompt-caching
|
||||
LiteLLM cache configuration and llama.cpp `--cache-prompt` flag on GPU hosts.
|
||||
|
||||
#### verification
|
||||
End-to-end latency measurements after changes applied — at least 3 test
|
||||
inference calls per model path measuring ttft (time-to-first-token) and total
|
||||
duration.
|
||||
|
||||
### Continuity
|
||||
|
||||
- input-driven
|
||||
|
||||
### Strategies
|
||||
|
||||
**Context is the root cause.** Every ~46K prompt token costs ~87s of
|
||||
prefill time at 532 tok/s. Fix context first, routing second.
|
||||
|
||||
- **Route by task**: qwen for code/standard queries; gemma for
|
||||
compression/auxiliary; strix-moe for compression tasks.
|
||||
- **Compress aggressively**: threshold at 40% (not 65%) — a 128K window should
|
||||
compact at 51K, not 85K. Target 15% tail (not 30%).
|
||||
- **Cache everything repeated**: system prompts, skill docs, AGENTS.md — these
|
||||
never change between turns. Single-digit cache hit rate is unacceptable.
|
||||
- **Lower context ceiling**: 128K window is the stable ceiling for agent conversations.
|
||||
GPUs reduced from 256K to 128K (2026-07-17). 128K window should compact at 85K (0.65 threshold). For larger contexts, route to external providers.
|
||||
|
||||
### Shape
|
||||
|
||||
- `self`: analyze metrics, compute optimal configs, apply changes, verify
|
||||
- `delegates`:
|
||||
- `apply-liteLLM`: update litellm_config.yaml and reload
|
||||
- `apply-agent-config`: update hermes config.yaml per agent
|
||||
- `verify-latency`: run test inference calls and measure response
|
||||
|
||||
### Execution
|
||||
|
||||
```prose
|
||||
-- Phase 1: Analyze current state (already complete)
|
||||
-- Phase 2: Apply LiteLLM routing optimization
|
||||
|
||||
call apply-liteLLM-routing
|
||||
config_path: /opt/inference-harness/litellm_config.yaml
|
||||
host: 192.168.68.116
|
||||
|
||||
-- Phase 3: Apply agent context compression optimization
|
||||
|
||||
call apply-agent-compression
|
||||
agent: mumuni
|
||||
host: 192.168.68.14
|
||||
config_path: /home/hermes/.hermes/config.yaml
|
||||
|
||||
-- Phase 4: Enable llama.cpp prompt caching on GPU hosts
|
||||
|
||||
call enable-prompt-caching
|
||||
hosts: [192.168.68.15, 192.168.68.8, 192.168.68.110]
|
||||
|
||||
-- Phase 5: Verify end-to-end latency
|
||||
|
||||
call verify-latency
|
||||
host: 192.168.68.116
|
||||
models: [syslog-auto, qwen3.6-27B-code, gemma-4-12b]
|
||||
```
|
||||
@@ -12,12 +12,6 @@ description: >
|
||||
never mutate infrastructure based on them without first confirming
|
||||
against the live system. Policy fields are authoritative. See the
|
||||
`verify-before-mutate` skill.
|
||||
|
||||
**Last verified:** 2026-08-15 — hwepve removed from Tabiri cluster
|
||||
(now 5 nodes: minipve, amdpve, storepve, acerpve, ocupve). hwepve
|
||||
(192.168.68.4) is a standalone PVE node + NetBird routing peer;
|
||||
London relocation pending. CTs 100 (abiba) and 105 (kagentz) moved
|
||||
to minipve.
|
||||
---
|
||||
|
||||
# Infrastructure Control Pattern
|
||||
@@ -35,19 +29,19 @@ description: >
|
||||
┌─────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ Abiba │ │ Tanko │ │ Mumuni │
|
||||
│ (pi) │ │ (Hermes) │ │ (Hermes) │
|
||||
│ CT 100 │ │ CT 112 │ │ CT 100 │
|
||||
│ CT 100 │ │ CT 112 │ │ CT 114 │
|
||||
└──────┬──────┘ └──────┬───────┘ └──────┬───────┘
|
||||
│ │ │
|
||||
└──────────────────┼────────────────────┘
|
||||
▼
|
||||
┌────────────────────────────────────┐
|
||||
│ Proxmox Cluster API │
|
||||
│ minipve.sysloggh.net:443 │
|
||||
│ (monitoring@pve!mumuni token) │
|
||||
└────┬──────┬──────┬──────┬──────────┘
|
||||
│ │ │ │
|
||||
┌────┘ ┌────┘ ┌────┘ ┌────┘
|
||||
▼ ▼ ▼ ▼
|
||||
┌──────────────────────────────────────┐
|
||||
│ Proxmox Cluster API │
|
||||
│ minipve.sysloggh.net:443 │
|
||||
│ (monitoring@pve!mumuni token) │
|
||||
└────┬──────┬──────┬──────┬──────┬─────┘
|
||||
│ │ │ │ │
|
||||
┌────┘ ┌────┘ ┌────┘ ┌────┘ ┌────┘
|
||||
▼ ▼ ▼ ▼ ▼
|
||||
minipve amdpve storepve acerpve ocupve
|
||||
(.12) (.15) (.6) (.9) (.5)
|
||||
|
||||
@@ -68,19 +62,19 @@ description: >
|
||||
|
||||
| Resource | Auth Method | Credential Source | Status |
|
||||
|----------|------------|-------------------|--------|
|
||||
| Proxmox Cluster | PVE API Token | Infisical vault (`PROXMOX_API_TOKEN`) | ✅ |
|
||||
| Proxmox Root | Password via API ticket | Infisical vault (`PROXMOX_ROOT_PASSWORD`) | ✅ |
|
||||
| Proxmox Cluster | PVE API Token | `monitoring@pve!mumuni=...` | ✅ |
|
||||
| Proxmox Root | Password via API ticket | `root@pam:kakashi19` | ✅ |
|
||||
| docker-vm (.7) | SSH root | SSH key | ✅ |
|
||||
| CT 116 (syslog-api) | SSH root | SSH key | ✅ |
|
||||
| Tanko CT (.122) | SSH jerome | id_ed25519 | ✅ |
|
||||
| Mumuni CT (.123) | SSH root | id_ed25519 | ✅ |
|
||||
| Baggy CT (113) | SSH jerome | ❌ no key access |
|
||||
| Netbird (.17) | SSH root | SSH key | ✅ |
|
||||
| Gitea | API token | Infisical vault (`GITEA_BOT_TOKEN`) | ✅ |
|
||||
| Zulip | Bot API key | Infisical vault (`ZULIP_BOT_KEY`) | ✅ |
|
||||
| Gitea | API token | abiba-bot token | ✅ |
|
||||
| Zulip | Bot API key | abiba-bot@chat.sysloggh.net | ✅ |
|
||||
| RA-H OS | MCP bridge | port 3100 | ✅ |
|
||||
| LiteLLM Admin | master key | Infisical vault (`LITELLM_MASTER_KEY`) | ✅ VERIFY-BEFORE-USE |
|
||||
| Grafana | admin password | Infisical vault (`GRAFANA_ADMIN_PASSWORD`) | ✅ VERIFY-BEFORE-USE |
|
||||
| LiteLLM Admin | master key | `sk-litellm-7f96...` | ✅ VERIFY-BEFORE-USE |
|
||||
| Grafana | admin password | `syslog-grafana-2026` | ✅ VERIFY-BEFORE-USE |
|
||||
|
||||
> **VERIFY-BEFORE-USE**: Credentials, IPs, ports, and hostnames in this
|
||||
> contract are live-state fields. Test them against the live system before
|
||||
@@ -91,7 +85,7 @@ description: >
|
||||
|
||||
### Reachability Matrix
|
||||
|
||||
| From / To | PVE API | docker-vm (.7) | CT 116 | Tanko (.122) | Mumuni (.24) | Baggy (.114) |
|
||||
| From / To | PVE API | docker-vm (.7) | CT 116 | Tanko (.122) | Mumuni (.123) | Baggy (.114) |
|
||||
|-----------|---------|----------------|--------|-------------|---------------|----------------|
|
||||
| **Abiba** (.24) | ✅ :443 | ✅ SSH | ✅ SSH | ✅ SSH jerome | ✅ SSH root | ❌ SSH |
|
||||
| **Tanko** (.122) | ❌ | ❌ | ❌ via NetBird | ✅ | ❌ | ❌ |
|
||||
@@ -105,26 +99,12 @@ description: >
|
||||
|
||||
| Node | IP | CPU | RAM | VMs/CTs | Role |
|
||||
|------|----|-----|-----|---------|------|
|
||||
| minipve | .12 | 16C | 30GB | abiba, kagentz, authentik, gitea, syslog-api, infisical-vault, jitsi | Auth, git, messaging |
|
||||
| amdpve | .15 | 32C | 62GB | tanko, tdunna, baggy, scottdenya | Agents, compute |
|
||||
| storepve | .6 | 28C | 31GB | docker-vm, ra-h-os, PBS, media, jdownloader, zulip | Docker, storage, chat |
|
||||
| acerpve | .9 | 28C | 31GB | llm-gpu | GPU VMs |
|
||||
| minipve | .12 | 16C | 30GB | authentik, gitea, mumuni, syslog-api, jitsi | Auth, git, messaging |
|
||||
| amdpve | .15 | 32C | 62GB | abiba, kagentz, tanko, tdunna, baggy, scottdenya | Agents, compute |
|
||||
| storepve | .6 | 28C | 31GB | docker-vm, ra-h-os, PBS, media, zulip | Docker, storage, chat |
|
||||
| acerpve | .9 | 28C | 31GB | llm-gpu, adguard | GPU VMs |
|
||||
| ocupve | .5 | 12C | 14GB | ocu-llm | GPU VMs |
|
||||
|
||||
> **Note:** CTs on storepve include jdownloader (CT 118). AdGuard (CT 102) is on
|
||||
> minipve at .10, not acerpve. Abiba (CT 100) and kagentz (CT 105) are on
|
||||
> minipve (moved from hwepve 2026-08-15). Mumuni runs inside Abiba CT100
|
||||
> (.24); CT 114 (mumuni) no longer exists in the cluster.
|
||||
>
|
||||
> **hwepve (192.168.68.4) — STANDALONE (removed from Tabiri 2026-08-15):**
|
||||
> Huawei MateBook 16 (KLVL-WXX9), pve-manager/9.2.10, kernel 7.0.14-8-pve.
|
||||
> Zero VMs/CTs. Being relocated to London as a standalone PVE node + NetBird
|
||||
> routing peer (relocation pending). Localizations applied: timezone
|
||||
> Europe/London, lid-switch ignore, sleep/suspend/hibernate targets masked,
|
||||
> cluster-shared storage removed (remaining: local, local-lvm, storage,
|
||||
> mediastore). prometheus-node-exporter active on :9100; net.ipv4.ip_forward=1;
|
||||
> NetBird client not yet installed (enrollment pending setup key).
|
||||
|
||||
### Checks (every 5 min)
|
||||
|
||||
```
|
||||
@@ -170,7 +150,7 @@ description: >
|
||||
|-------|------|-----------|
|
||||
| **Firecrawl** | `/opt/search-stack/firecrawl-source/` | api, rabbitmq, postgres, playwright, redis |
|
||||
| **SearXNG** | `/opt/search-stack/searxng/` | searxng, valkey |
|
||||
| **Home stack** | `/opt/home_stack/` | stirling-pdf, pulse (jdownloader decommissioned 2026-08-01 → dedicated CT 118 LXC) |
|
||||
| **Home stack** | `/opt/home_stack/` | jdownloader, stirling-pdf, pulse |
|
||||
| **Audiobookshelf** | `/opt/audiobookshelf/` | audiobookshelf |
|
||||
| **Trove agents** | docker run (standalone) | trove-agent-proxmox, trove-test-agent-1, trove-test-server-1, docker-stats |
|
||||
|
||||
@@ -187,26 +167,23 @@ description: >
|
||||
- Compose: `/opt/home_stack/docker-compose.yml`
|
||||
- Control script: `/opt/home_stack/infra-control.sh`
|
||||
|
||||
**JDownloader** (decommissioned from docker-vm 2026-08-01 — moved to dedicated CT 118 LXC):
|
||||
- LXC: CT 118 on storepve, `192.168.68.20` (JDownloader + VNC 5900 + web UI 6080)
|
||||
- Web UI: `http://192.168.68.20:6080` (noVNC via websockify)
|
||||
- Docker container `jdownloader-2` on .7 removed; compose entry stripped
|
||||
**JDownloader**:
|
||||
- URL: `http://192.168.68.7:5800` (web UI via VNC)
|
||||
|
||||
**Pulse**:
|
||||
- URL: `http://192.168.68.7:7655` (direct LAN)
|
||||
- Public: `https://pulse.sysloggh.net` (NetBird CNAME proxy)
|
||||
- Container: `rcourtman/pulse:5.1.35` in `/opt/home_stack` (port 7655, was 3001)
|
||||
**Pulse** (Uptime Kuma):
|
||||
- URL: `http://192.168.68.7:3001`
|
||||
|
||||
### Ecosystem B: CT 116 syslog-api (192.168.68.116)
|
||||
|
||||
11 containers in inference-harness stack (verified live 2026-09-11; LiteLLM upgraded 1.90.0-rc.1 -> 1.99.1):
|
||||
8 containers in inference-harness stack:
|
||||
|
||||
| Container | Image | Port | Role |
|
||||
|-----------|-------|------|------|
|
||||
| harness-litellm | ghcr.io/docker.litellm.ai/berriai/litellm:1.99.1 | :4000→:4000 | API proxy, key mgmt, fallbacks |
|
||||
| harness-litellm | berriai/litellm:1.90.0-rc.1 | :4000→:4001 | API proxy, key mgmt, fallbacks |
|
||||
| harness-router | inference-harness-router | :9000 (127.0.0.1) | GPU routing, slot booking, CB |
|
||||
| harness-nginx | nginx:alpine | :80 | Entrypoint, /v1→LiteLLM, /dashboard/ |
|
||||
| harness-postgres | postgres:16-alpine | :5432 | LiteLLM DB (keys, spend, config) |
|
||||
| harness-redis | redis:7-alpine | :6379 | LiteLLM cache + rate-limit state |
|
||||
| harness-redis | redis:7-alpine | :6379 | Router slots, circuit breakers |
|
||||
| harness-dashboard | inference-harness-dashboard | :3000 | SyslogAI Harness UI |
|
||||
| harness-grafana | grafana/grafana | :3000→:3001 (direct LAN, not behind nginx) | GPU + Proxmox + Docker dashboards |
|
||||
| harness-prometheus | prom/prometheus | :9090 | Metrics scraper, 6 jobs |
|
||||
@@ -222,7 +199,7 @@ description: >
|
||||
**Prometheus targets**:
|
||||
- 192.168.68.8:9400 (RTX 3090 — qwen)
|
||||
- 192.168.68.110:9400 (RTX 5070 — gemma)
|
||||
- 192.168.68.15:9400 (Strix Halo — qwen3.6-35B-udq4)
|
||||
- 192.168.68.15:9400 (Strix Halo — ornith)
|
||||
- 192.168.68.24:9401 (Router metrics exporter)
|
||||
- harness-litellm:4000 (LiteLLM health)
|
||||
|
||||
@@ -377,18 +354,16 @@ fine. Services that resolve directly to a LAN IP are NetBird-independent.
|
||||
|---------|--------|-------------|-------------|-------------|--------|
|
||||
| Proxmox API | minipve.sysloggh.net:8006 | 192.168.68.12 | LAN IP | No | ✅ |
|
||||
| LiteLLM | litellm.sysloggh.net | 192.168.68.116 | LAN IP | No | ✅ |
|
||||
| Authentik | auth.sysloggh.net:443 | 192.168.68.11:9000 | CNAME → netbird | **Yes** | ⚠️ |
|
||||
| Gitea | git.sysloggh.net:443 | 192.168.68.17:3000 | CNAME → netbird | **Yes** | ⚠️ |
|
||||
| Authentik | auth.sysloggh.net:443 | 192.168.68.11 | CNAME → netbird | **Yes** | ⚠️ |
|
||||
| Gitea | git.sysloggh.net:443 | 192.168.68.110 | CNAME → netbird | **Yes** | ⚠️ |
|
||||
| Zulip | chat.sysloggh.net:443 | 192.168.68.19 | CNAME → netbird | **Yes** | ⚠️ VERIFY-BEFORE-USE |
|
||||
| Pulse | pulse.sysloggh.net:443 | 192.168.68.7:7655 | CNAME → netbird | **Yes** | ✅ verified 2026-08-01 |
|
||||
| DNS UI | dns.sysloggh.net:443 | 192.168.68.10:80 | CNAME → netbird | **Yes** | ⚠️ |
|
||||
| Pulse | pulse.sysloggh.net:443 | 192.168.68.7 | CNAME → netbird | **Yes** | ⚠️ |
|
||||
| DNS UI | dns.sysloggh.net:443 | 192.168.68.102 | CNAME → netbird | **Yes** | ⚠️ |
|
||||
| SearXNG | searxng.sysloggh.net:8888 | 192.168.68.7:8888 | LAN IP | No | ✅ |
|
||||
| Firecrawl | firecrawl.sysloggh.net:3002 | 192.168.68.7:3002 | LAN IP | No | ✅ |
|
||||
|
||||
**Verified 2026-07-24:** NetBird VPS rebooted after a hang; all CNAME'd
|
||||
**Verified 2026-07-02:** NetBird VPS rebooted after a hang; all CNAME'd
|
||||
services recovered. LAN-IP-direct paths stayed up throughout the outage.
|
||||
Also added `dns.sysloggh.net` route (was missing entirely).
|
||||
See `scripts/netbird-add-domain.sh` for adding new proxy routes.
|
||||
|
||||
### 5.2 Checks (every 2 min)
|
||||
|
||||
@@ -536,8 +511,8 @@ enforced by the `routing-regression.config_url_violations` check in Section
|
||||
| LiteLLM API | `http://192.168.68.116:4000` | `https://litellm.sysloggh.net` |
|
||||
| LiteLLM (nginx) | `http://192.168.68.116` | — |
|
||||
| Grafana | `http://192.168.68.116:3001` | — |
|
||||
| Authentik | `https://192.168.68.11:9000` | `https://auth.sysloggh.net` |
|
||||
| Gitea | `http://192.168.68.17:3000` | `https://git.sysloggh.net` |
|
||||
| Authentik | `https://192.168.68.11` | `https://auth.sysloggh.net` |
|
||||
| Gitea | `http://192.168.68.110:3000` | `https://git.sysloggh.net` |
|
||||
| Zulip API | `http://192.168.68.19` | `https://chat.sysloggh.net` |
|
||||
| SearXNG | `http://192.168.68.7:8888` | — |
|
||||
| Firecrawl | `http://192.168.68.7:3002` | — |
|
||||
@@ -575,18 +550,21 @@ curl -s http://192.168.68.116/health/unified | jq .status
|
||||
curl -s http://192.168.68.24:9100/gpu-data | jq .summary
|
||||
|
||||
# Grafana status
|
||||
curl -s http://admin:$(infisical secrets get GRAFANA_ADMIN_PASSWORD --project=infrastructure --env=production --plain)@192.168.68.116:3001/api/health
|
||||
curl -s http://admin:syslog-grafana-2026@192.168.68.116:3001/api/health
|
||||
|
||||
# Prometheus targets
|
||||
curl -s http://192.168.68.116:9090/api/v1/targets | jq '.data.activeTargets[] | {job: .labels.job, health: .health}'
|
||||
|
||||
# LiteLLM key check
|
||||
curl -s -H "Authorization: Bearer $(infisical secrets get LITELLM_MASTER_KEY --project=infrastructure --env=production --plain)" \
|
||||
curl -s -H "Authorization: Bearer sk-litellm-7f96080dd99b15c36bd4b333b58a6796" \
|
||||
http://192.168.68.116/litellm/key/list | jq '.keys[] | {alias: .key_alias, models: .models}'
|
||||
|
||||
# Storage check
|
||||
ssh root@192.168.68.7 "df -h /media/storage /media/mediastore"
|
||||
|
||||
# Router roster reload (if needed)
|
||||
curl -s -X POST http://192.168.68.116:9000/admin/roster/reload \
|
||||
-H "Authorization: Bearer sk-admin-ee09fffd04978b61a1569ac670c68814"
|
||||
|
||||
# Restart stuck GPU (saturation watchdog alternative)
|
||||
ssh root@192.168.68.8 "systemctl restart llama-server"
|
||||
@@ -597,25 +575,25 @@ ssh root@192.168.68.110 "systemctl restart llama-server"
|
||||
|
||||
| CT | Name | Node | IP | Role | Agent |
|
||||
|----|------|------|----|------|-------|
|
||||
| 100 | abiba | minipve | .24 | Pi agent | ✅ pi |
|
||||
| 100 | abiba | amdpve | .24 | Pi agent (this host) | ✅ pi |
|
||||
| 101 | llm-gpu | acerpve | .8 | GPU RTX 3090 | ❌ |
|
||||
| 102 | adguard | **minipve** | **.10** | DNS | ❌ |
|
||||
| 102 | adguard | acerpve | — | DNS | ❌ |
|
||||
| 103 | ocu-llm | ocupve | .110 | GPU RTX 5070 | ❌ |
|
||||
| 104 | authentik | minipve | .11 | OIDC | ❌ |
|
||||
| 105 | kagentz | minipve | — | Agent Zero | ✅ |
|
||||
| 105 | kagentz | amdpve | — | Agent Zero | ✅ |
|
||||
| 106 | ra-h-os | storepve | .65 | KG bridge | ✅ MCP |
|
||||
| 107 | pbs | storepve | — | Backups | ❌ |
|
||||
| 108 | media | storepve | — | Media | ❌ |
|
||||
| 109 | docker-vm | storepve | .7 | Docker host | ❌ |
|
||||
| 110 | gitea | minipve | **.17** | Git | ❌ |
|
||||
| 111 | tdunna | amdpve | .129 | Hermes agent | ✅ |
|
||||
| 112 | tanko | amdpve | .122 | DSH (DeepSeek Harness) agent | ✅ |
|
||||
| 113 | baggy | amdpve | .114 | Hermes agent | ✅ |
|
||||
| 115 | scottdenya | amdpve | .75 | Denya OneCare | ❌ |
|
||||
| 110 | gitea | minipve | — | Git | ❌ |
|
||||
| 111 | tdunna | amdpve | — | ? | ❌ |
|
||||
| 112 | tanko | amdpve | .122 | Hermes agent | ✅ |
|
||||
| 113 | baggy | amdpve | ? | Hermes agent | ✅ |
|
||||
| 114 | mumuni | minipve | .123 | Hermes agent | ✅ |
|
||||
| 115 | scottdenya | amdpve | — | ? | ❌ |
|
||||
| 116 | syslog-api | minipve | .116 | LiteLLM + Grafana | ❌ |
|
||||
| 117 | zulip | storepve | .19 | Chat | ❌ |
|
||||
| 118 | jdownloader | storepve | .20 | JDownloader LXC (dedicated, migrated from docker-vm 2026-08-01) | ✅ |
|
||||
| 119 | infisical-vault | minipve | — | Vault | ❌ |
|
||||
| 117 | zulip | storepve | — | Chat | ❌ |
|
||||
| 118 | jitsi | minipve | — | Video | ❌ |
|
||||
|
||||
## Appendix C: Docker Compose Files Location
|
||||
|
||||
@@ -635,27 +613,27 @@ Source of truth: `/root/scripts/pct-run.sh` or `prose-contracts/scripts/pct-run.
|
||||
|
||||
| CT | Name | Node | pct-run |
|
||||
|-----|------|------|---------|
|
||||
| 100 | abiba | minipve | `pct-run 100` |
|
||||
| 105 | kagentz | minipve | `pct-run 105` |
|
||||
| 100 | abiba | amdpve | `pct-run 100` |
|
||||
| 105 | kagentz | amdpve | `pct-run 105` |
|
||||
| 111 | tdunna | amdpve | `pct-run 111` |
|
||||
| 112 | tanko | amdpve | `pct-run 112` |
|
||||
| 113 | baggy | amdpve | `pct-run 113` |
|
||||
| 115 | scottdenya | amdpve | `pct-run 115` |
|
||||
| 104 | authentik | minipve | `pct-run 104` |
|
||||
| 110 | gitea | minipve | `pct-run 110` |
|
||||
| 114 | mumuni | minipve | `pct-run 114` |
|
||||
| 116 | syslog-api | minipve | `pct-run 116` |
|
||||
| 106 | ra-h-os | storepve | `pct-run 106` |
|
||||
| 107 | proxmox-backup | storepve | `pct-run 107` |
|
||||
| 108 | media | storepve | `pct-run 108` |
|
||||
| 117 | zulip | storepve | `pct-run 117` |
|
||||
| 102 | adguard | **minipve** | `pct-run 102` |
|
||||
| 102 | adguard | acerpve | `pct-run 102` |
|
||||
|
||||
GPU bare-metal hosts (.8 acerpve, .110 ocupve, .15 amdpve) are NOT CTs — use SSH directly:
|
||||
```bash
|
||||
ssh root@192.168.68.8 # RTX 3090
|
||||
ssh root@192.168.68.110 # RTX 5070
|
||||
ssh root@192.168.68.15 # Strix Halo
|
||||
ssh root@192.168.68.4 # hwepve — standalone London node + NetBird routing peer (relocation pending)
|
||||
```
|
||||
|
||||
## Section 7: Agent Health Check (consolidated — 2026-07-05)
|
||||
|
||||
@@ -1,199 +0,0 @@
|
||||
---
|
||||
kind: responsibility
|
||||
name: infrastructure-maintenance
|
||||
description: >
|
||||
Weekly system-level maintenance for the Syslog inference fleet: OS package
|
||||
updates on the primary host, Docker image pulls for LiteLLM/SearXNG and other
|
||||
running containers, container restarts with health verification, post-update
|
||||
verification of every critical service (LiteLLM proxy, SearXNG, Zulip, Gitea,
|
||||
PM2 processes, Hermes gateways), and rollback on failure. Consolidates the
|
||||
raw shell scripts that previously did this piecemeal. This contract owns the
|
||||
HOST-LEVEL weekly maintenance loop on the primary host plus Docker image
|
||||
pulls ONLY for .116 and .7, while infrastructure-update owns the FULL-FLEET
|
||||
cluster-wide wave (apt across the full PVE cluster + CTs/VMs AND its Docker
|
||||
image Wave 3 across all stacks). Runs Sunday 2am ET. Owner:
|
||||
ops (firstmate secondmate). Blast radius: an unverified image pull can break
|
||||
LiteLLM (all agents lose inference) or SearXNG (search-stack down); a bad apt
|
||||
upgrade can leave the host in a half-upgraded state. Pre-update backup check
|
||||
and rollback are mandatory for this reason.
|
||||
agent: ops
|
||||
triggers:
|
||||
- weekly (Sunday 02:00 ET) via cron
|
||||
- on demand when ops/abiba triggers "infra maintenance"
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
## Maintains
|
||||
|
||||
- maintenance-status: { phase: idle|preflight|apt|images|restarts|verify|rollback|done|failed, host, step, result, timestamp }
|
||||
- image-baseline: { service, current_tag, pulled_tag, digest, updated_at } — last known-good image per container
|
||||
- apt-state: { upgradable_before, upgradable_after, held_broken, kernel_reboot_required }
|
||||
- health-baseline: snapshot of critical-service health captured pre-update (used for regression check post-update)
|
||||
- rollback-snapshot: { backup_path, configs, image_digests, timestamp } — restore point created in preflight
|
||||
- maintenance-history: array of past runs with phase results and any escalations
|
||||
|
||||
## Scope
|
||||
|
||||
Primary host is the maintenance host where apt updates apply. Docker image pulls
|
||||
span the two Docker ecosystems that run critical services. infrastructure-update
|
||||
runs the full-fleet cluster-wide wave (including its Wave 3 Docker pulls across
|
||||
all stacks/hosts); this contract runs a narrower host-level weekly pull limited
|
||||
to .116 and .7. Topology, CT IDs, and IPs are live-state fields — verify against
|
||||
`infrastructure-control.prose.md` (the source of truth) and the live system
|
||||
before mutating.
|
||||
|
||||
| Host | IP | Role | Trust |
|
||||
|------|----|------|-------|
|
||||
| CT 116 (syslog-api) | 192.168.68.116 | LiteLLM proxy + Grafana + Prometheus (inference harness) | ⚠️ VERIFY-BEFORE-USE |
|
||||
| VM 109 (docker-vm) | 192.168.68.7 | SearXNG + Firecrawl + home stack (Docker host) | ⚠️ VERIFY-BEFORE-USE |
|
||||
| CT 117 (zulip) | 192.168.68.19 | Zulip (storepve bridge IP .19) | ⚠️ VERIFY-BEFORE-USE |
|
||||
| Gitea | https://git.sysloggh.net | Prose-contracts + agent configs source control | ⚠️ VERIFY-BEFORE-USE |
|
||||
| CT 100 (abiba/pi) | 192.168.68.24 | PM2 processes (pi agent harness) | ⚠️ VERIFY-BEFORE-USE |
|
||||
|
||||
> "Primary host" for the apt phase is the host the ops agent runs maintenance
|
||||
> from. Confirm which host that is against infrastructure-control before
|
||||
> running; do not assume. If the ops agent is containerized/CT-based, apt runs
|
||||
> inside that CT.
|
||||
|
||||
## Requires
|
||||
|
||||
- SSH/exec access to CT 116 (.116) and VM 109 (.7) for Docker operations
|
||||
- `apt`, `docker`, `docker compose` available on target hosts
|
||||
- LiteLLM master key available (Infisical vault, `LITELLM_API_KEY`) for health verification
|
||||
- `infrastructure-monitoring` run completed within the last 30 minutes — provides the pre-update health baseline used by the regression check
|
||||
- Writable backup directory `/tmp/infra-maintenance-backup-<date>/` on each mutated host
|
||||
- Proxmox snapshot of the primary host available (or confirmed not required) before apt phase
|
||||
|
||||
## Continuity
|
||||
|
||||
- Self-driven: weekly cron `0 2 * * 0` (Sunday 02:00 ET)
|
||||
- Also wakes on: explicit "infra maintenance" trigger from ops/abiba
|
||||
- Depends on `infrastructure-monitoring` for the pre-update health baseline — do not run if the last monitoring run is stale (>30 min) or RED; abort and escalate instead
|
||||
|
||||
## Execution
|
||||
|
||||
### Phase 0 — Preflight (snapshot/backup check + health baseline)
|
||||
|
||||
1. **Capture health baseline** — run the `infrastructure-monitoring` postcondition checks (LiteLLM, Zulip, Gitea, SearXNG, Proxmox API) and record results as `health-baseline`. If any critical service is already down, **abort**: maintenance must not run on a degraded fleet.
|
||||
2. **Backup check** — confirm a Proxmox snapshot of the primary host exists OR `/tmp/infra-maintenance-backup-<date>/` was created this run. Snapshot critical config files into the backup dir:
|
||||
- `/opt/inference-harness/docker-compose.yml`, `/opt/inference-harness/litellm_config.yaml` (CT 116)
|
||||
- `/opt/search-stack/searxng/docker-compose.yml`, `/opt/search-stack/firecrawl-source/docker-compose.yaml` (VM 109)
|
||||
3. **Record image baseline** — `docker inspect --format '{{.Image}} {{.Config.Image}}' <container>` for every running container on .116 and .7; store digests in `image-baseline` so rollback can restore them.
|
||||
4. **Disk check** — `df -h` on each mutated host; abort if free space <20% (apt upgrade + image pulls need headroom).
|
||||
|
||||
### Phase 1 — OS package updates (primary host)
|
||||
|
||||
```bash
|
||||
# On the primary host only (VERIFY host against infrastructure-control first)
|
||||
apt update
|
||||
apt upgrade -y
|
||||
```
|
||||
|
||||
- Capture `apt list --upgradable` before and after → store in `apt-state`.
|
||||
- If apt reports held/broken packages (`apt-get -s upgrade | grep -i broken`, or non-zero exit), **stop** — do not force. Record `held_broken` and go to rollback/escalate.
|
||||
- If `/var/run/reboot-required` exists after upgrade, flag `kernel_reboot_required: true` in `apt-state` but **do not reboot automatically** — that's a separate coordinated action (see infra-update Wave 4). Note it in the report.
|
||||
|
||||
### Phase 2 — Docker image pulls
|
||||
|
||||
Pull latest stable tags for every running container. Do NOT pin to `:main`/`:nightly` — use stable tags where the compose file specifies them; otherwise `latest`.
|
||||
|
||||
```bash
|
||||
# CT 116 (.116) — inference harness
|
||||
cd /opt/inference-harness && docker compose pull
|
||||
|
||||
# VM 109 (.7) — search + home stacks
|
||||
cd /opt/search-stack/searxng && docker compose pull
|
||||
cd /opt/search-stack/firecrawl-source && docker compose pull
|
||||
# any other running stacks on .7 (home stack, audiobookshelf) — pull per their compose files
|
||||
```
|
||||
|
||||
- LiteLLM and SearXNG are the two explicitly required pulls; "any other running containers" means every stack with a compose file on .116 and .7.
|
||||
- Record pulled tag + digest per service in `image-baseline`.
|
||||
|
||||
### Phase 3 — Container restarts with health verification
|
||||
|
||||
Restart one stack at a time, verify health before moving to the next. Do not restart everything at once — a failure mid-wave must leave the rest running.
|
||||
|
||||
```bash
|
||||
# CT 116
|
||||
cd /opt/inference-harness && docker compose up -d
|
||||
# VM 109
|
||||
cd /opt/search-stack/searxng && docker compose up -d
|
||||
cd /opt/search-stack/firecrawl-source && docker compose up -d
|
||||
```
|
||||
|
||||
After each stack comes up, wait for health (max 120s):
|
||||
- `docker ps` shows the container `Up` (and `healthy` if a healthcheck is defined)
|
||||
- Service-specific probe passes (see Phase 4 probes)
|
||||
|
||||
If a stack fails to come up within 120s, **stop the wave** and go to rollback for that stack only; do not proceed to the next.
|
||||
|
||||
### Phase 4 — Post-update service verification
|
||||
|
||||
After ALL updates (apt + images + restarts), verify every critical service is back up and matches the pre-update baseline. This is the regression gate.
|
||||
|
||||
| Service | Probe | Expect |
|
||||
|---------|-------|--------|
|
||||
| LiteLLM proxy | `curl -sf http://192.168.68.116/litellm/v1/models` | 200 OK, models returned |
|
||||
| LiteLLM MCP gateway | `curl -sf http://192.168.68.116:4000/mcp-rest/tools/list -H "Authorization: Bearer $MASTER_KEY"` | 90 tools (23 RA-H OS + 67 GitHub) |
|
||||
| SearXNG | `curl -sf http://192.168.68.7:8888` | 200 OK |
|
||||
| Zulip | `curl -sf https://chat.sysloggh.net/api/v1/server_settings` | 200 OK |
|
||||
| Gitea | `curl -sf https://git.sysloggh.net/api/v1/version` | 200 OK |
|
||||
| PM2 processes | `pm2 jlist` (CT 100) | all pi-agent processes `online` |
|
||||
|
||||
Regression check: every service that was GREEN in `health-baseline` must still be GREEN. A service that was already RED (and caused a preflight abort) is excluded — but Phase 0 should have aborted before we got here.
|
||||
|
||||
## Rollback Protocol
|
||||
|
||||
If ANY service in Phase 4 fails to come back up (or regresses vs baseline):
|
||||
|
||||
1. **Image rollback** — for the failing stack, restore the previous image:
|
||||
```bash
|
||||
# Restore from recorded image-baseline digest
|
||||
docker compose down
|
||||
# Pin the service image to the recorded digest in compose, then recreate
|
||||
# image: <name>@sha256:<previous_digest>
|
||||
docker compose pull && docker compose up -d
|
||||
```
|
||||
2. **APT rollback** — restore the primary host from the Proxmox snapshot taken/confirmed in Phase 0. If no snapshot, `apt install <pkg>=<old_version>` per package using apt history (`/var/log/apt/history.log`).
|
||||
3. **Config rollback** — restore configs from `/tmp/infra-maintenance-backup-<date>/`.
|
||||
4. **Re-verify** — re-run the Phase 4 probes on the rolled-back service. If still failing, escalate (do not loop — circuit breaker below).
|
||||
5. **Escalate** — send a Zulip DM to abiba + mumuni with: failing service, phase, baseline vs current, rollback actions taken, backup path.
|
||||
|
||||
## Circuit Breaker
|
||||
|
||||
- `max_retries: 2` per failing phase — after 2 rollback attempts on the same service, stop and escalate.
|
||||
- `window: 7200` seconds — no more than 2 retries within a 2-hour window.
|
||||
- `trip_action: escalate_to_fatal` — when tripped, escalate to fatal (abiba + mumuni + kwame) and pause; a human must clear before the next scheduled run.
|
||||
|
||||
## Report
|
||||
|
||||
After completion (or on abort), emit a receipt (JSON) to `~/.hermes/runs/infrastructure-maintenance/` and send a Zulip DM summary:
|
||||
|
||||
```
|
||||
🛠 Infrastructure Maintenance — YYYY-MM-DD
|
||||
|
||||
Phase: apt | images | restarts | verify | rollback
|
||||
Primary host: <host>
|
||||
APT: <N> packages upgraded, <M> held/broken, kernel_reboot_required=<bool>
|
||||
Images pulled: LiteLLM <tag>, SearXNG <tag>, <others>
|
||||
Services: all GREEN | <service> FAILED (rolled back)
|
||||
Baseline regression: none | <details>
|
||||
Backup: /tmp/infra-maintenance-backup-YYYYMMDD/
|
||||
Escalation: none | warning | critical | fatal
|
||||
```
|
||||
|
||||
## Verification Postconditions
|
||||
|
||||
- All critical services running after update (Phase 4 all GREEN)
|
||||
- No regressions from pre-update health baseline (Phase 0 baseline)
|
||||
- Docker containers on latest stable tags (`image-baseline.pulled_tag` recorded)
|
||||
- APT packages up to date with no held broken packages (`apt-state.held_broken == 0`)
|
||||
|
||||
## Related Contracts
|
||||
|
||||
- `infrastructure-update.prose.md` — owns the full-fleet cluster-wide wave INCLUDING its Wave 3 Docker image updates across all stacks (SearXNG, Firecrawl, Inference Harness on .116, home stack, audiobookshelf); infrastructure-maintenance is a deliberately narrower host-level weekly pull scoped to .116 and .7.
|
||||
- `infrastructure-monitoring.prose.md` — provides the pre-update health baseline (depends_on).
|
||||
- `infrastructure-control.prose.md` — topology source of truth (CT IDs, IPs, hostnames).
|
||||
- `litellm-health.prose.md` — LiteLLM probe details.
|
||||
- `proxmox-monitor.prose.md` — Docker stats + monitoring stack health.
|
||||
@@ -7,15 +7,13 @@ description: >
|
||||
from nvidia-smi (.8, .110) and amdgpu_top (.15). LiteLLM metrics
|
||||
via existing /metrics Prometheus endpoint.
|
||||
|
||||
DEPLOYMENT STATUS (2026-08-09):
|
||||
DEPLOYMENT STATUS (2026-07-09):
|
||||
✅ Core stack deployed: Prometheus + Grafana + pve/node/docker exporters
|
||||
(via proxmox-monitor contract). Grafana at :3001, all scrape targets active.
|
||||
✅ GPU exporters DEPLOYED: all 3 GPU hosts (.8/.110/.15) run exporters on
|
||||
:9400 (nvidia_gpu_exporter / amdgpu exporter) — verified 200 on 2026-08-09.
|
||||
✅ LiteLLM /metrics scraping live (success_callback: prometheus; auth via
|
||||
master key) + Alertmanager + Zulip bridge (alerts-infra) added 2026-08-09.
|
||||
⚠️ This contract is target-state aspirational — but GPU export + alerting
|
||||
are now as-built (verified 2026-08-09).
|
||||
(via proxmox-monitor contract). Grafana at :3001, 5 scrape targets active.
|
||||
❌ GPU exporters NOT deployed: gpu-exporter crash-loops on .15,
|
||||
NVIDIA sidecar exporters (.8/.110:9400) never installed.
|
||||
Router falls back to direct GPU /health probes.
|
||||
⚠️ This contract is target-state aspirational — not as-built.
|
||||
As-built GPU monitoring is via gpu-monitor contract (port 9100 poll).
|
||||
version: 1.0.0
|
||||
---
|
||||
@@ -103,92 +101,6 @@ GPU .8 (RTX 3090) GPU .110 (RTX 5070) GPU .15 (Strix Halo)
|
||||
|
||||
## Execution
|
||||
|
||||
### Liveness rule (scoped)
|
||||
|
||||
The any-HTTP-response rule applies ONLY to unauthenticated/auth-gated endpoints,
|
||||
where any HTTP answer proves a listener is up: the PVE API
|
||||
(`https://<node>:8006/api2/json/version`) and LiteLLM health
|
||||
(`/litellm/health`, `301` → `/litellm/health/liveliness`). For those endpoints a
|
||||
probe is **ALIVE** on **ANY** HTTP status — `401`/`403` auth challenges and `3xx`
|
||||
redirects included — and **DOWN = connection refused (`000`) or timeout only**.
|
||||
The PVE API legitimately answers `401` to an unauthenticated probe — that is the
|
||||
healthy signal, not a failure. Same scoped rule as zulip-health (Tanko) and
|
||||
gpu-monitor.
|
||||
|
||||
Probes whose success condition is specifically a bare `200` are NOT covered by
|
||||
the any-HTTP rule. On those — the authenticated Zulip POST and the router
|
||||
`/health` — an unexpected status (`401`/`403` from a bad or missing credential,
|
||||
`5xx`, or anything other than the expected `200`) is an **ALERT**, not "alive".
|
||||
|
||||
### check-health
|
||||
|
||||
**RUN LIVE, NEVER ECHO — every dispatch must execute the probes below with real tool calls; never repeat a prior report unless a live probe fails.**
|
||||
|
||||
```bash
|
||||
# Provenance — run first; paste the absolute path into the report
|
||||
pwd -P
|
||||
|
||||
# Zulip API health (POST ping)
|
||||
source /etc/litellm-monitor.env
|
||||
ZULIP_USER="abiba-bot@chat.sysloggh.net"
|
||||
curl -s -o /dev/null -w '%{http_code}' -X POST https://chat.sysloggh.net/api/v1/messages -u "${ZULIP_USER}:${ZULIP_BOT_KEY}"
|
||||
# Expected: 200 (HTTP 000 = unreachable/cache)
|
||||
|
||||
# PM2 process health
|
||||
pm2 jlist
|
||||
# Expected: 5/5 online (abiba-telegram, abiba-zulip, zulip-watchdog, gitea-runner, spoton-service)
|
||||
|
||||
# GPU exporters (may be down per DEPLOYMENT STATUS)
|
||||
curl -s http://192.168.68.8:9400/metrics && echo " - OK" || echo " - FAIL"
|
||||
curl -s http://192.168.68.110:9400/metrics && echo " - OK" || echo " - FAIL"
|
||||
curl -s http://192.168.68.15:9400/metrics && echo " - OK" || echo " - FAIL"
|
||||
|
||||
# Router health (via nginx on port 80)
|
||||
curl -s -o /dev/null -w '%{http_code}' http://192.168.68.116/health
|
||||
# Expected: 200 (Router is up and responding)
|
||||
|
||||
# LiteLLM health (via nginx on port 80)
|
||||
curl -s -o /dev/null -w '%{http_code}' http://192.168.68.116/litellm/health
|
||||
# Expected: 301 → /litellm/health/liveliness (200 after redirect) — any HTTP status = alive
|
||||
|
||||
# PVE API liveness — probe the REAL PVE nodes on :8006, never the monitoring
|
||||
# host CT 116. CT 116 runs no pveproxy, so probing it on :8006 returns 000 —
|
||||
# that was the stale-vantage bug this replaces (CT 116 is the monitoring host,
|
||||
# not a cluster node). Unauthenticated GET answers 401 while the API is ALIVE
|
||||
# by design. Alive = ANY HTTP status (401 is the EXPECTED healthy response);
|
||||
# DOWN = connection refused (000) or timeout only.
|
||||
for node in 192.168.68.9 192.168.68.5 192.168.68.15 192.168.68.6 192.168.68.12; do
|
||||
printf '%s:8006 -> %s\n' "$node" \
|
||||
"$(curl -sk -o /dev/null -w '%{http_code}' --connect-timeout 5 "https://$node:8006/api2/json/version")"
|
||||
done
|
||||
# Expected: 401 on every node (acerpve .9, ocupve .5, amdpve .15, storepve .6, minipve .12)
|
||||
# A node answering 000/timeout is DOWN — flag that node. 401 is NOT a fault.
|
||||
|
||||
# Prometheus targets
|
||||
curl -s http://192.168.68.116:9090/api/v1/targets | jq '.data.activeTargets'
|
||||
# Expected: All targets UP (may show some down if exporters not deployed)
|
||||
|
||||
# Grafana health
|
||||
curl -s http://192.168.68.116:3001/api/health | jq '{status, version}'
|
||||
# Expected: {"status":"ok","version":"..."}
|
||||
|
||||
# LiteLLM metrics (Prometheus endpoint)
|
||||
curl -s http://192.168.68.116:4000/metrics | head -20
|
||||
# Expected: Prometheus-formatted metrics output
|
||||
```
|
||||
|
||||
**Report format**: Begin every report with the **absolute path the probe executed
|
||||
from** (`pwd -P`, or the script's absolute path) so a stale-consumer report is
|
||||
distinguishable from a real fault at read time. Summarize actual results from
|
||||
each probe. Apply the any-HTTP-response liveness rule ONLY to the auth-gated PVE
|
||||
API and LiteLLM endpoints above: only connection-refused (`000`) or timeout is
|
||||
DOWN; empty output is a warning. For probes whose expected result is a bare `200`
|
||||
(the authenticated Zulip POST, router `/health`), flag an alert on any unexpected
|
||||
status (`401`/`403`/`5xx`) — do not summarize it as alive. A bare-`200`
|
||||
expectation on the auth-gated PVE API (`401`) or LiteLLM health (`301` redirect)
|
||||
is a stale expectation, not a fault.
|
||||
|
||||
|
||||
### Phase 1: GPU Exporters
|
||||
|
||||
**NVIDIA (.8 and .110)**:
|
||||
@@ -242,5 +154,5 @@ curl -s http://192.168.68.116:9090/api/v1/targets
|
||||
curl -s http://192.168.68.116:3001/api/health
|
||||
|
||||
# LiteLLM metrics (already live)
|
||||
curl -s http://192.168.68.116:4000/metrics | head -20
|
||||
curl -s http://192.168.68.116:4001/metrics | head -20
|
||||
```
|
||||
|
||||
+20
-114
@@ -3,16 +3,15 @@ kind: responsibility
|
||||
name: infrastructure-update
|
||||
description: >
|
||||
Autonomous system-wide update contract covering all 5 Proxmox nodes,
|
||||
15+ containers/VMs, and 5 Docker ecosystems (docker-vm .7, CT 116 .116,
|
||||
CT 117, hwpve .11, NetBird VPS 72.61.0.17). Updates apt packages,
|
||||
15+ containers/VMs, and 4 Docker ecosystems. Updates apt packages,
|
||||
Docker images, and container stacks in safe waves with health checks
|
||||
and automatic rollback on failure.
|
||||
agent: abiba
|
||||
triggers:
|
||||
- on "infra update" command
|
||||
- weekly (Sunday 03:00 America/New_York) via Agent Zero scheduler task "weekly-fleet-docker-update" (qSOOVzsU) — implemented 2026-09-08
|
||||
- weekly (Sunday 03:00 EDT) via cron
|
||||
- on security advisory relay from Mumuni
|
||||
version: 1.3.0
|
||||
version: 1.1.0
|
||||
---
|
||||
|
||||
## Maintains
|
||||
@@ -28,12 +27,11 @@ Before ANY update wave:
|
||||
2. ✅ All critical VMs/CTs running (VM 109 docker-vm, CT 116 syslog-api, CT 117 zulip, CT 106 ra-h-os)
|
||||
3. ✅ GPU bare-metal hosts reachable: .8 (RTX 3090), .110 (RTX 5070), .15 (Strix Halo)
|
||||
4. ✅ Docker healthy on VM 109 (.7), CT 116 (.116)
|
||||
5. ✅ LiteLLM health check passing (port 4000, /mcp-rest/tools/list with master key)
|
||||
6. ✅ LiteLLM MCP gateway serving RA-H OS tools (90 tools)
|
||||
7. ✅ Zulip server reachable
|
||||
8. ✅ GPU fleet healthy (all 3 GPUs: RTX 3090, RTX 5070, RX 7600)
|
||||
9. ✅ Disk >20% free on all nodes
|
||||
10. 📋 Snapshot critical configs (LiteLLM, nginx, docker-compose files)
|
||||
5. ✅ LiteLLM health check passing
|
||||
6. ✅ Zulip server reachable
|
||||
6. ✅ GPU fleet healthy (all 3 GPUs: RTX 3090, RTX 5070, RX 7600)
|
||||
7. ✅ Disk >20% free on all nodes
|
||||
8. 📋 Snapshot critical configs (LiteLLM, nginx, docker-compose files)
|
||||
|
||||
## Wave 1: Storage & Infra Nodes (lowest impact)
|
||||
|
||||
@@ -60,15 +58,14 @@ Before ANY update wave:
|
||||
| CT 100 (.24) | Abiba (pi) | `apt update && apt upgrade -y` | 3 min |
|
||||
| CT 116 (.116) | syslog-api (LiteLLM host) | `apt update && apt upgrade -y` | 3 min |
|
||||
| CT 112 (tanko, amdpve) | Tanko | `apt update && apt upgrade -y` | 3 min |
|
||||
| CT 105 (kagentz, minipve) | Mumuni | `apt update && apt upgrade -y` | 3 min |
|
||||
| CT 114 (mumuni, minipve) | Mumuni | `apt update && apt upgrade -y` | 3 min |
|
||||
| VM 101 (.8) | llm-gpu (RTX 3090) | `apt update && apt upgrade -y` | 3 min |
|
||||
| VM 103 (.110) | ocu-llm (RTX 5070) | `apt update && apt upgrade -y` | 3 min |
|
||||
|
||||
**Verify after Wave 2:**
|
||||
- All VMs/CTs running: check via Proxmox API
|
||||
- LiteLLM healthy: `curl localhost:4000/health/liveliness` (via CT 116)
|
||||
- LiteLLM MCP tools: `curl localhost:4000/mcp-rest/tools/list -H "Authorization: Bearer $MASTER_KEY"` → 90 tools
|
||||
- GPU servers responding: check :8080 on VM 101, VM 103; check strix-moe via router (http://192.168.68.116/health/unified — .15:8080 is firewalled to .116 only)
|
||||
- GPU servers responding: check :8080 on VM 101, VM 103; check ornith via router (http://192.168.68.116/health/unified — .15:8080 is firewalled to .116 only)
|
||||
- Zulip agents connected: check Mumuni/Tanko gateway state
|
||||
- Abiba PM2 processes online: `pm2 status`
|
||||
|
||||
@@ -78,76 +75,30 @@ Before ANY update wave:
|
||||
|------|-------|---------|
|
||||
| VM 109 (.7) | Firecrawl | `cd /opt/search-stack/firecrawl-source && docker compose pull && docker compose up -d` |
|
||||
| VM 109 (.7) | SearXNG | `cd /opt/search-stack/searxng && docker compose pull && docker compose up -d` |
|
||||
| VM 109 (.7) | Home stack (Pulse, Stirling PDF) — JDownloader moved to CT 118 LXC 2026-08-01 | `cd /opt/home_stack && docker compose pull && docker compose up -d` |
|
||||
| VM 109 (.7) | Home stack (Pulse, Stirling PDF, JDownloader 2) | `cd /opt/home_stack && docker compose pull && docker compose up -d` |
|
||||
| VM 109 (.7) | Audiobookshelf | `cd /opt/audiobookshelf && docker compose pull && docker compose up -d` |
|
||||
| CT 116 (.116) | Inference Harness (LiteLLM, Prometheus, Grafana) | `cd /opt/inference-harness && docker compose pull && docker compose up -d` |
|
||||
| CT 117 (storepve) | Zulip | `pct exec 117 -- bash -c 'cd /opt/zulip && docker compose pull && docker compose up -d'` (from storepve; compose recreates on zulip_default network) |
|
||||
| CT 117 (storepve) | Jitsi | `pct exec 117 -- bash -c 'cd /opt/jitsi && docker compose pull && docker compose up -d'` (from storepve) |
|
||||
| hwpve (.11) | Authentik (server, worker, postgres) | `ssh root@192.168.68.11 'cd /root && docker compose pull && docker compose up -d'` |
|
||||
| NetBird VPS (72.61.0.17) | NetBird (server, dashboard, proxy, traefik, crowdsec) | `ssh root@72.61.0.17 'cd /root && docker compose pull && docker compose up -d'` |
|
||||
| VM 109 (.7) | Trove test | `cd /opt/trove-test && docker compose pull && docker compose up -d` |
|
||||
| VM 109 (.7) | docker-stats | `cd /opt/docker-stats && docker compose pull && docker compose up -d` |
|
||||
| CT 116 (.116) | Monitoring (Grafana, Prometheus, Alertmanager, PVE exporter) | `cd /opt/monitoring && docker compose pull && docker compose up -d` |
|
||||
| CT 117 (zulip, storepve) | Zulip | `docker pull zulip/docker-zulip:latest && docker restart zulip-zulip-1` |
|
||||
|
||||
**Verify after Wave 3:**
|
||||
- All containers healthy: `docker ps` on each host
|
||||
- End-to-end inference test: `curl localhost:4000/v1/chat/completions` (via CT 116) with syslog-auto
|
||||
- MCP integration test: `curl localhost:4000/mcp-rest/tools/list -H "Authorization: Bearer $MASTER_KEY"` → 90 tools (23 RA-H OS + 67 GitHub)
|
||||
- Zulip test: send test message to #agent-hub
|
||||
- Dashboard loading: `curl localhost:3001/` (via CT 116)
|
||||
- Firecrawl test: `curl -X POST http://192.168.68.7:3002/v1/search -H 'Content-Type: application/json' -d '{"query":"health","limit":1}'` → `"success":true` (GET `/` returns 200)
|
||||
- Authentik test: `curl http://192.168.68.11:9000/` → 302 redirect to login
|
||||
- NetBird test: `curl -s -o /dev/null -w '%{http_code}' https://netbird.sysloggh.net/` → 200
|
||||
- harness-litellm cold start: allow 3-5 min after recreate — reports unhealthy and :4000 refuses connections while loading config/DB, then recovers to 200 on its own (verified 2026-09-08)
|
||||
- Firecrawl test: `curl :3002/`
|
||||
- SearXNG test: `curl :8888`
|
||||
- Digest-pin sweep: `grep -rn '@sha256:' /opt/*/docker-compose.y*` on every host — digest-pinned images are INVISIBLE to `docker compose pull` (the pin re-pulls the same digest forever, so new releases never appear). Flag every pin in the run report and propose un-pinning to a floating tag with user approval before editing. Found 2026-09-10: audiobookshelf was digest-pinned at 2.34.0 (container created 2026-07-18) and silently missed by every sweep; dockhand stack was also pinned (stack removed 2026-09-10, unused). After un-pinning audiobookshelf to :latest it updated to 2.36.0 and verified HTTP 200.
|
||||
|
||||
## Wave 4: Proxmox Kernel Reboot
|
||||
## Wave 4: Proxmox Kernel Reboot (if needed)
|
||||
|
||||
Only if `[ -f /var/run/reboot-required ]` on any node.
|
||||
|
||||
| Target | Action |
|
||||
|--------|--------|
|
||||
| Affected PVE node | Verify all CTs/VMs migrated or stopped |
|
||||
| | `reboot` via PVE API (or `systemctl reboot -f` if dbus fails) |
|
||||
| | `reboot` via PVE API |
|
||||
| | Wait 120s for node to come back |
|
||||
| | Start any stopped CTs |
|
||||
|
||||
### Post-reboot sweep (known gaps)
|
||||
|
||||
After every node reboot, run these checks:
|
||||
|
||||
1. **CT auto-start sweep** — LXC containers sometimes don't start despite
|
||||
`onboot: 1`. Check every CT on the rebooted node and start any left stopped:
|
||||
```bash
|
||||
pct list | awk '/stopped/{print $1}' | xargs -I{} pct start {}
|
||||
```
|
||||
Known cases: scottdenya (CT 115 on amdpve), authentik (CT 104 on minipve).
|
||||
|
||||
2. **Zulip recovery** — When docker-vm or storepve reboots, the Zulip main
|
||||
container loses its Docker network assignment (SIGKILL during storage
|
||||
outage detaches it from `zulip_default` network). Run:
|
||||
```bash
|
||||
ssh root@192.168.68.19 'docker rm -f zulip-zulip-1 && cd /opt/zulip && docker compose up -d'
|
||||
```
|
||||
The compose restart recreates the container on the correct network.
|
||||
|
||||
3. **docker-vm Docker daemon** — After reboot, Docker can take 3-4 minutes
|
||||
to become `active`. The docker-proxy for Pulse (port 7655) starts early,
|
||||
so Pulse is accessible before `docker ps` reports ready. Wait for Docker
|
||||
before checking other stacks.
|
||||
|
||||
### VPS ↔ docker-vm tunnel
|
||||
|
||||
After any VPS or docker-vm reboot, verify the dedicated WireGuard tunnel:
|
||||
```bash
|
||||
ssh root@72.61.0.17 'wg show wg1' | grep "latest handshake"
|
||||
# If no handshake in >60s:
|
||||
ssh root@72.61.0.17 'wg-quick up wg1'
|
||||
```
|
||||
The tunnel uses PersistentKeepalive=25 and is systemd-enabled, but should
|
||||
be verified after a reboot.
|
||||
|
||||
## Rollback Protocol
|
||||
|
||||
If ANY verification fails:
|
||||
@@ -161,64 +112,20 @@ If ANY verification fails:
|
||||
|
||||
Before Wave 1, snapshot these files:
|
||||
```
|
||||
/opt/inference-harness/docker-compose.yml (CT 116 .116) ⚡ contains MCP_SERVER env vars
|
||||
/opt/inference-harness/litellm_config.yaml (CT 116 .116) ⚡ contains mcp_servers.ra_h_os
|
||||
/opt/inference-harness/docker-compose.yml (CT 116 .116)
|
||||
/opt/inference-harness/litellm_config.yaml (CT 116 .116)
|
||||
/opt/monitoring/prometheus.yml (CT 116 .116)
|
||||
/etc/nginx/nginx.conf (harness-nginx on CT 116)
|
||||
/opt/search-stack/firecrawl-source/docker-compose.yaml (VM 109 .7)
|
||||
/opt/search-stack/searxng/docker-compose.yml (VM 109 .7)
|
||||
/opt/home_stack/docker-compose.yml (VM 109 .7)
|
||||
/opt/audiobookshelf/docker-compose.yml (VM 109 .7)
|
||||
/root/compose.yml (hwpve .11 — Authentik server/worker/postgres)
|
||||
/root/docker-compose.yml (NetBird VPS — netbird server/dashboard/proxy, traefik, crowdsec)
|
||||
/root/.pi/agent/extensions/config.yaml (CT 100 .24)
|
||||
/etc/systemd/system/strix-server.service (amdpve .15 — strix-moe)
|
||||
/etc/systemd/system/ornith-server.service (amdpve .15)
|
||||
/etc/systemd/system/llama-server.service (VM 101 .8, VM 103 .110)
|
||||
# Hermes agent configs (key enforcement — 2026-07-10)
|
||||
/home/hermes/.hermes/config.yaml (Mumuni kagentz CT105; Tanko CT112 uses /home/jerome/.hermes)
|
||||
/etc/systemd/system/hermes-gateway.service (Mumuni kagentz CT105 — system unit, User=hermes)
|
||||
/etc/environment (LITELLM_API_KEY — legacy path, Mumuni now keys via Infisical)
|
||||
```
|
||||
|
||||
## MCP Gateway (2026-07-10)
|
||||
|
||||
LiteLLM CT 116 now serves as an authenticated MCP gateway for RA-H OS tools.
|
||||
|
||||
### Configuration
|
||||
|
||||
**litellm_config.yaml** (`/opt/inference-harness/litellm_config.yaml`):
|
||||
```yaml
|
||||
mcp_servers:
|
||||
ra_h_os:
|
||||
url: "http://192.168.68.65:3100/mcp"
|
||||
transport: "http"
|
||||
auth_type: "none"
|
||||
```
|
||||
|
||||
**docker-compose.yml** env vars:
|
||||
```yaml
|
||||
- MCP_SERVER_RAHOS_URL=http://192.168.68.65:3100/mcp
|
||||
- MCP_SERVER_RAHOS_TRANSPORT=http
|
||||
```
|
||||
|
||||
### Access
|
||||
|
||||
| Key | MCP Access |
|
||||
|-----|-----------|
|
||||
| Master key | ✅ Full — 90 tools (vault-injected) |
|
||||
| Agent keys (mumuni, tanko, etc.) | ❌ Per-key grants not supported in v1.99.1 |
|
||||
|
||||
### Known Limitations
|
||||
- Per-key MCP server grants not functional — only master key has access
|
||||
- Responses API (`/v1/responses`) with MCP tools broken on llama.cpp backends
|
||||
- HTTP 307 redirect on `/mcp` → use `/mcp/` (trailing slash) or `/mcp-rest/` endpoints
|
||||
- `api_mode: responses` in Hermes appends `/v1/responses` to base_url → **base_url must end at `/v1`, never `/responses`** (double-path bug)
|
||||
|
||||
### Migration Path
|
||||
When LiteLLM is upgraded to a version supporting per-key MCP grants:
|
||||
1. Grant agent keys `mcp_servers: ["ra_h_os"]`
|
||||
2. Update Hermes `mcp_servers.ra-h-os.url` from `http://192.168.68.65:3100/mcp` → `http://192.168.68.116:4000/mcp/`
|
||||
3. Add `headers: {x-litellm-api-key: "Bearer $LITELLM_API_KEY"}` to MCP config
|
||||
Run: `mkdir -p /tmp/infra-update-backup-$(date +%Y%m%d) && rsync -av ...`
|
||||
|
||||
## Security-Specific Updates
|
||||
|
||||
@@ -233,11 +140,10 @@ When LiteLLM is upgraded to a version supporting per-key MCP grants:
|
||||
|
||||
- [ ] All 5 PVE nodes updated, no reboot-loop
|
||||
- [ ] All VMs/CTs running post-update
|
||||
- [ ] All Docker containers healthy (VM 109 + CT 116 + CT 117 + hwpve .11 + NetBird VPS)
|
||||
- [ ] All Docker containers healthy (VM 109 + CT 116 + CT 117)
|
||||
- [ ] LiteLLM inference passing (syslog-auto test)
|
||||
- [ ] Zulip server + all 3 agents connected
|
||||
- [ ] GPU fleet at full capacity (3/3)
|
||||
- [ ] LiteLLM MCP gateway healthy (90 tools via master key)
|
||||
- [ ] Zero security CVEs remaining
|
||||
- [ ] <10 min total downtime per service
|
||||
|
||||
|
||||
+10
-280
@@ -8,32 +8,10 @@ description: >
|
||||
Ensures agents never use the master key directly. Rotation is event-driven,
|
||||
not calendar-driven — rotate only on compromise, personnel change, or
|
||||
periodic security hygiene (quarterly/annually).
|
||||
|
||||
UPDATED 2026-07-12: Keys are stored in Infisical vault (project=agents, env=production)
|
||||
BUT each agent host MUST keep a local .env fallback. Infisical service tokens can
|
||||
expire/404. The .env fallback prevents agents from running without keys.
|
||||
Tanko incident: token 404 → gateway had no LITELLM_API_KEY for hours.
|
||||
|
||||
UPDATED 2026-07-16: Vault is SYNCED (session-13 keys written to vault via abiba service
|
||||
token, all validate 200). Koby/Koonimo migrated from hardcoded drop-ins to the
|
||||
infisical-gateway.sh wrapper (live vault injection). 4/5 agents now vault-backed.
|
||||
Canonical process: see § Production Vault Access Process. Tanko (user jerome) pending.
|
||||
Abiba's key is now a proper agent key (NOT the master key — stale note removed).
|
||||
|
||||
UPDATED 2026-07-17: FLEET-WIDE STANDARDIZATION. All 4 agents (Mumuni, Tanko, Koby, Koonimo)
|
||||
standardized on a single pattern: systemd drop-in (ExecStart= reset + wrapper path) →
|
||||
infisical-gateway.sh while-true loop → /usr/bin/infisical run --token → bash -c key
|
||||
injection → .env fallback → exec python. Systemd drop-ins are IMMUNE to hermes gateway
|
||||
install which overwrites the unit file ExecStart. Infisical CLI updated to 0.43.109 on
|
||||
all agents (was 0.38.0). Service token st.8e848433 shared across fleet (st.353699cd
|
||||
for tanko was deleted). .env fallback on every agent protects against token loss.
|
||||
Critical lessons: (1) NEVER use shell variables inside single-quoted bash -c in wrappers
|
||||
— hardcode absolute paths. (2) Drop-ins override unit file ExecStart permanently.
|
||||
(3) Capture /proc/<pid>/environ before gateway restarts to preserve running env set.
|
||||
|
||||
|
||||
Current key inventory and agent list: see gpu-fleet.prose.md § Agent Keys.
|
||||
Source of truth for LiteLLM config: /opt/inference-harness/litellm_config.yaml
|
||||
on CT 116. Last verified: 2026-07-17.
|
||||
on CT 116. Last verified: 2026-07-09.
|
||||
---
|
||||
|
||||
## Parameters
|
||||
@@ -41,10 +19,7 @@ description: >
|
||||
- agent_name: string — The agent to manage keys for (e.g., "tanko", "mumuni")
|
||||
- action: "create" | "rotate" | "verify" | "list" — What to do (default: "create")
|
||||
- litellm_host: string — LiteLLM admin endpoint (default: "192.168.68.116:4000")
|
||||
- master_key: string — LiteLLM master key (default from Infisical vault: project=infrastructure, env=production, secret=LITELLM_MASTER_KEY)
|
||||
- vault_url: string — Infisical vault URL (default: "https://vault.sysloggh.net")
|
||||
- vault_project: string — Infisical project slug (default: "infrastructure")
|
||||
- vault_env: string — Infisical environment (default: "production")
|
||||
- master_key: string — LiteLLM master key (default from environment)
|
||||
- agent_host: string — Agent's IP for SSH (default: resolved from infra)
|
||||
- agent_user: string — SSH user (default: "jerome")
|
||||
|
||||
@@ -55,273 +30,28 @@ description: >
|
||||
- key_prefix: string — First 10 chars of the new key (for identification)
|
||||
- previous_key_alias: string | null — Previous key alias if rotating
|
||||
- litellm_response: object — Raw response from LiteLLM /key/generate
|
||||
- vault_updated: boolean — Whether Infisical vault secret was updated
|
||||
- agent_config_updated: boolean — Legacy: whether /etc/environment was updated (deprecated, always false post-migration)
|
||||
- agent_config_updated: boolean — Whether /etc/environment was updated
|
||||
- verification: { status: string, detail: string } — Final health check
|
||||
|
||||
## Execution
|
||||
|
||||
1. **Authenticate** — Retrieve master key from Infisical vault via `infisical export --project=<vault_project> --env=<vault_env>`, verify against LiteLLM /key/list
|
||||
1. **Authenticate** — Verify master_key works against LiteLLM /key/list
|
||||
2. **Check existing keys** — List all keys, find any with agent_name alias
|
||||
3. **If action == "list"**: Return all keys with their aliases and spend
|
||||
4. **If action == "create"**:
|
||||
- Generate new key with key_alias: "{agent_name}" (e.g., "tanko" — bare name, no date)
|
||||
- Set metadata: { "agent": "{agent_name}", "purpose": "agent-inference" }
|
||||
- Duration is null (permanent) — inherited from litellm default_key_generate_params
|
||||
- Set models: ["syslog-auto", "qwen3.6-27B-code", "gemma-4-12b", "strix-moe", "gpu-dense", "gpu-light", "qwen3.6-35B-udq4"]
|
||||
- Note: `ornith-1.0-35b` is NOT a valid LiteLLM model name (use `strix-moe`, the stable alias). qwen3.6-35B-A3B removed from fleet (was never deployed).
|
||||
- Set models: ["syslog-auto", "qwen3.6-27B-code", "gemma-4-12b", "ornith-1.0-35b"]
|
||||
- Note: qwen3.6-35B-A3B removed from fleet (was never deployed on any GPU)
|
||||
- Return the new key
|
||||
5. **If action == "rotate"**:
|
||||
- Generate new key with same alias (LiteLLM replaces the old key)
|
||||
- Update secret in Infisical vault: `infisical secrets set LITELLM_API_KEY=<new_key> --project=<vault_project> --env=<vault_env>`
|
||||
- Restart agent gateway (Hermes: `systemctl restart hermes-gateway`; pi: restart PM2 process)
|
||||
The gateway automatically picks up the new key via `infisical run --` wrapper
|
||||
- SSH to agent_host, update /etc/environment LITELLM_API_KEY
|
||||
- Restart agent gateway (hermes gateway restart for Hermes agents)
|
||||
- Verify: curl test against /v1/models with new key
|
||||
- Rotation policy: on-demand only (compromise, departure, quarterly hygiene)
|
||||
- Note: /etc/environment is NO LONGER used for LiteLLM keys. Agents inject keys at runtime via vault wrapper.
|
||||
6. **If action == "verify"**:
|
||||
- Retrieve key from Infisical vault: `infisical secrets get LITELLM_API_KEY --project=<vault_project> --env=<vault_env>`
|
||||
- SSH to agent, read /etc/environment
|
||||
- Test the key against LiteLLM /v1/models
|
||||
- Confirm key alias matches agent_name in LiteLLM key list
|
||||
- Verify agent gateway uses vault wrapper: `cat /proc/<pid>/cmdline` shows `infisical run`
|
||||
|
||||
## Production Vault Access Process (canonical, 2026-07-17)
|
||||
|
||||
The non-fail approach to agentic vault access. Deployed on all 4 Hermes agents
|
||||
(Mumuni, Tanko, Koby, Koonimo) as of 2026-07-17. Abiba (pi) uses a similar pattern
|
||||
through its agent wrapper.
|
||||
|
||||
### The canonical pattern
|
||||
|
||||
1. **infisical CLI** installed on the host at `/usr/bin/infisical` (v0.43.109+, from
|
||||
artifacts-cli.infisical.com apt repo). Update procedure:
|
||||
```bash
|
||||
curl -1sLf 'https://artifacts-cli.infisical.com/setup.deb.sh' | sudo -E bash
|
||||
sudo apt-get update && sudo apt-get install -y infisical
|
||||
# Remove stale old binary if present
|
||||
rm -f /usr/local/bin/infisical /bin/infisical
|
||||
```
|
||||
Wrappers use absolute path `/usr/bin/infisical run`. Never rely on PATH resolution.
|
||||
2. **Service token** (Infisical Machine Identity, `st.…`) stored at `~/.infisical-token`
|
||||
(`chmod 600`). Current: shared `st.8e848433…` (abiba, READ+WRITE on agents project).
|
||||
Tanko's `st.353699cd…` (tanko-agent) was deleted — reverted to shared token.
|
||||
Proper: one machine identity per agent (create in Infisical UI → Project Settings →
|
||||
Machine Identities).
|
||||
3. **`infisical-gateway.sh` wrapper** at `~/.hermes/infisical-gateway.sh` (`chmod 700`):
|
||||
```bash
|
||||
#!/bin/bash
|
||||
export INFISICAL_API_URL="https://vault.sysloggh.net"
|
||||
TOKEN=$(cat $HOME/.infisical-token)
|
||||
LOG=$HOME/.hermes/logs/gateway.log; mkdir -p $HOME/.hermes/logs
|
||||
while true; do
|
||||
echo "[$(date -Iseconds)] Starting gateway with Infisical injection..." >> $LOG
|
||||
/usr/bin/infisical run --token="$TOKEN" \
|
||||
--projectId=322fceab-39da-4854-a55a-568e76c0f13f \
|
||||
--env=prod --domain=https://vault.sysloggh.net -- bash -c '
|
||||
. $HOME/.hermes/.env 2>/dev/null # [FALLBACK Rule 3]
|
||||
export LITELLM_API_KEY="${<AGENT>_LITELLM_API_KEY}"
|
||||
export ZULIP_API_KEY="${<AGENT>_ZULIP_API_KEY}"
|
||||
export ZULIP_SITE="https://chat.sysloggh.net"
|
||||
export ZULIP_EMAIL="<agent>-bot@chat.sysloggh.net"
|
||||
export SEARXNG_URL="http://192.168.68.7:8888"
|
||||
# ⚠️ HARDCODE the full venv path. NEVER use $VENV inside single quotes.
|
||||
exec /root/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main gateway run
|
||||
' >> $LOG 2>&1
|
||||
EXIT_CODE=$?
|
||||
echo "[$(date -Iseconds)] Gateway exited with code $EXIT_CODE — restarting in 5s..." >> $LOG
|
||||
sleep 5
|
||||
done
|
||||
```
|
||||
**CRITICAL: VENV PATH.** The inner `bash -c '...'` uses single quotes. Shell
|
||||
variables set in the outer wrapper are NOT expanded inside single quotes.
|
||||
`$VENV/bin/python` resolves to `/bin/python` (file not found). Always hardcode
|
||||
the absolute path to the venv python binary.
|
||||
4. **Agent key in vault** as `<AGENT>_LITELLM_API_KEY` and `<AGENT>_ZULIP_API_KEY`.
|
||||
Vault = source of truth for ALL platform credentials.
|
||||
5. **`.env` fallback** at `~/.hermes/.env` (`chmod 600`) with agent-specific keys —
|
||||
safety net for vault outage or token revocation. Must be kept in sync on rotation.
|
||||
Example:
|
||||
```bash
|
||||
MUMUNI_LITELLM_API_KEY=sk-OzuWsoX22Hmb3Ps3JY01gw
|
||||
MUMUNI_ZULIP_API_KEY=H8dY6V7aHmWNcfgNtJaDBPZ1dGWn0Ttt
|
||||
```
|
||||
6. **systemd drop-in** at `~/.config/systemd/user/hermes-gateway.service.d/50-vault-wrapper.conf`:
|
||||
```ini
|
||||
[Service]
|
||||
ExecStart=
|
||||
ExecStart=/root/.hermes/infisical-gateway.sh
|
||||
```
|
||||
The `ExecStart=` (empty reset) clears any ExecStart from the main unit file,
|
||||
then the second `ExecStart=` sets the wrapper. This drop-in **survives unit file
|
||||
regeneration** by `hermes gateway install` — the drop-in always wins.
|
||||
|
||||
**Why a drop-in instead of editing the unit file:** `hermes gateway install`
|
||||
(called during Hermes updates and some self-heal operations) regenerates the
|
||||
systemd unit file with `ExecStart=/path/to/python -m hermes_cli.main gateway run`.
|
||||
Editing the unit file directly is futile — it will be overwritten. The drop-in
|
||||
approach explicitly resets ExecStart and sets the wrapper regardless of what the
|
||||
main unit file says.
|
||||
7. **NEVER hardcode** API keys in systemd drop-ins, config.yaml, or /etc/environment.
|
||||
The wrapper injects live from vault at every start.
|
||||
|
||||
### Why this is non-fail
|
||||
|
||||
- **No rot**: keys pulled live from vault at every gateway start. Rotation = one `infisical secrets set` + `systemctl restart`. No per-host file edits.
|
||||
- **Survives vault outage**: the `.env` fallback (Rule 3) keeps the gateway running if Infisical is unreachable or the service token is revoked.
|
||||
- **Survives gateway crash**: the wrapper's `while true` + systemd `Restart=always` revive the gateway. Two-layer defense.
|
||||
- **Survives Hermes updates**: systemd drop-in overrides unit file ExecStart — `hermes gateway install` cannot break the vault injection.
|
||||
- **Survives reboot**: systemd user service + `loginctl enable-linger` ensures gateway starts at boot without a login session.
|
||||
- **Auditable**: `cat /proc/$(pgrep -f 'python.*hermes_cli.main.gateway.run' | grep -v infisical | head -1)/environ` shows all injected keys (note: pipe through grep -v infisical to avoid matching the bash wrapper); `infisical secrets` shows the vault source.
|
||||
|
||||
### Migration status (2026-07-17)
|
||||
|
||||
| Agent | Host | Pattern | Keys | Status |
|
||||
|-------|------|---------|------|--------|
|
||||
| abiba | .24 | pi agent wrapper | ABIBA_LITELLM_API_KEY + ABIBA_ZULIP_API_KEY | ✅ vault-backed |
|
||||
| mumuni | .14 (kagentz CT105) | systemd unit hermes-gateway.service (user hermes) | MUMUNI_LITELLM_API_KEY + MUMUNI_ZULIP_API_KEY | ✅ vault-backed + .env fallback |
|
||||
| tanko | .122 | systemd drop-in + while-true wrapper + st.8e848433 (user jerome) | TANKO_LITELLM_API_KEY + TANKO_ZULIP_API_KEY | ✅ vault-backed + .env fallback |
|
||||
| koby | .129 | systemd drop-in + while-true wrapper + st.8e848433 | KOBY_LITELLM_API_KEY, shares TANKO_ZULIP_API_KEY (tanko-bot) | ✅ vault-backed |
|
||||
| koonimo | .114 | systemd drop-in + while-true wrapper + st.8e848433 | KOONIMO_LITELLM_API_KEY + KOONIMO_ZULIP_API_KEY | ✅ vault-backed |
|
||||
|
||||
> Tanko runs as user `jerome` — wrapper/token at `~/.hermes/infisical-gateway.sh` and
|
||||
> `~/.infisical-token`. Linger enabled (`loginctl enable-linger jerome`) for boot startup.
|
||||
|
||||
### Tanko migration (COMPLETED 2026-07-17)
|
||||
|
||||
Tanko was the last agent migrated from hardcoded keys to vault wrapper.
|
||||
Previously: key hardcoded in `/home/jerome/.hermes/config.yaml` (`api_key: sk-CggiHWlamQy…`)
|
||||
and `zulip-env.conf` systemd drop-in. Now: user-scope systemd service with drop-in
|
||||
`50-vault-wrapper.conf`, `infisical-gateway.sh` wrapper with while-true loop, token at
|
||||
`~/.infisical-token`, `.env` fallback at `~/.hermes/.env`. Keys injected live from vault.
|
||||
|
||||
### Koby migration lessons (2026-07-16, updated 2026-07-17)
|
||||
|
||||
Migrated Koby from hardcoded systemd drop-in → `infisical-gateway.sh` wrapper.
|
||||
**Three mistakes made:**
|
||||
1. **Overwrote `/root/.hermes/.env`** without backing it up. The Zulip API key only existed
|
||||
in the running process memory — the old .env was minimal (just LiteLLM key). Zulip creds were
|
||||
inherited from the pre-migration gateway env, not stored in any file. Lost on restart.
|
||||
2. **Only injected `LITELLM_API_KEY`** in the wrapper — forgot Zulip + Telegram credentials.
|
||||
Agents need ALL their platform env vars. Missing vars cause silent adapter failures.
|
||||
3. (2026-07-17 fix) **VENV variable in single-quoted bash -c**: `exec "$VENV/bin/python"`
|
||||
inside single quotes resolved to `exec "/bin/python"` (file not found). Hardcoded full path.
|
||||
|
||||
**How Koby actually connects:**
|
||||
- Zulip: shares **Tanko's bot** (`tanko-bot@chat.sysloggh.net`, `TANKO_ZULIP_API_KEY=5PeD6f3zo…`).
|
||||
- Telegram: token from `.env` fallback. Allowed users: 6679773481.
|
||||
- Both platforms now connect through the wrapper's env injection.
|
||||
|
||||
**Golden rules for gateway restarts:**
|
||||
1. Always `cat /proc/<pid>/environ` before killing the old process — captures the live env set.
|
||||
2. Hardcode venv python path in wrapper — never use variables inside single-quoted bash -c.
|
||||
3. Use systemd drop-ins (not unit file edits) to override ExecStart — survives Hermes updates.
|
||||
|
||||
### Fleet-wide standardization lessons (2026-07-17)
|
||||
|
||||
After auditing all 4 agents, five systemic patterns caused repeated failures:
|
||||
1. **Three incompatible startup patterns** coexisted (systemd drop-in, direct python, orphaned wrapper)
|
||||
2. **Systemd unit files reverted** by `hermes gateway install` during updates
|
||||
3. **VENV variable scoping** broke wrappers on Koby and Mumuni (single-quote bash -c)
|
||||
4. **Service token expiry** — Tanko's `st.353699cd` was deleted from Infisical
|
||||
5. **No ZULIP_API_KEY** in env on Tanko — wrapper bypassed by systemd direct python
|
||||
|
||||
All resolved by the canonical drop-in + while-true wrapper pattern documented above.
|
||||
|
||||
### Key rotation procedure (one vault operation with this standard)
|
||||
|
||||
1. Generate new key: `POST /key/generate` (master key, admin).
|
||||
2. Update vault: `infisical secrets set <AGENT>_LITELLM_API_KEY=sk-NEW --token=$TOKEN --projectId=322fceab… --env=prod --domain=https://vault.sysloggh.net`.
|
||||
3. Update `.env` fallback: `echo '<AGENT>_LITELLM_API_KEY=sk-NEW' > /root/.hermes/.env && chmod 600 /root/.hermes/.env`.
|
||||
4. Restart: `systemctl restart hermes-gateway`. The wrapper pulls the new key live.
|
||||
5. Verify: `curl -H "Authorization: Bearer sk-NEW" http://192.168.68.116/v1/models` → 200.
|
||||
|
||||
## Machine Identity for Vault Writes (UPDATED 2026-07-17)
|
||||
|
||||
**Current state:** Infisical CLI updated to v0.43.109 on all agents (from v0.38.0).
|
||||
The v0.38.0 bug (user-session auth fails for `secrets set`/`export`) is resolved.
|
||||
Service token `st.8e848433…` (abiba, READ+WRITE) can write to vault from CLI.
|
||||
|
||||
**Proper fix — per-agent Machine Identities:**
|
||||
Create machine identities in Infisical UI → Project Settings → Machine Identities
|
||||
for each agent with READ-only scope on the `agents` project. Store client_id +
|
||||
client_secret per agent. Then vault writes use the shared abiba identity, and
|
||||
reads use per-agent identities. This eliminates the single shared token risk.
|
||||
|
||||
**Service Token Inventory (2026-07-17):**
|
||||
| Token ID | Name | Permissions | Used By | Status |
|
||||
|----------|------|-------------|---------|--------|
|
||||
| `st.8e848433…` | tanko-gateway | READ+WRITE | Mumuni, Tanko, Koby, Koonimo, Abiba | ✅ Active |
|
||||
| `st.353699cd…` | tanko-agent | READ-only | — | ❌ Deleted from Infisical |
|
||||
|
||||
**Per-agent .env fallback inventory (2026-07-17):**
|
||||
| Agent | .env Keys |
|
||||
|-------|-----------|
|
||||
| Mumuni | MUMUNI_LITELLM_API_KEY, MUMUNI_ZULIP_API_KEY |
|
||||
|| Tanko | TANKO_LITELLM_API_KEY, TANKO_ZULIP_API_KEY |
|
||||
|| Koby | (wrapper injects from vault — .env has Telegram token) |
|
||||
|| Koonimo | KOONIMO_LITELLM_API_KEY, KOONIMO_ZULIP_API_KEY |
|
||||
|| Agent Zero (kagentz .14) | OPENROUTER_API_KEY (direct OpenRouter access) |
|
||||
|
||||
### Agent Zero (kagentz .14) — OpenRouter Integration (2026-09-01)
|
||||
|
||||
Agent Zero runs in Docker on kagentz (CT105) and uses **direct OpenRouter API access**,
|
||||
not via the LiteLLM proxy. This is because Agent Zero's workflow (self-update manager,
|
||||
UI bootstrap, model selection) is built around OpenRouter's native authentication.
|
||||
|
||||
**Key Storage:**
|
||||
- **Container**: `/a0/usr/.env` (line ~72: `API_KEY_OPENROUTER=sk-or-v1-…`)
|
||||
- **Vault**: Infisical secret `OPENROUTER_API_KEY` (project=agents, env=production)
|
||||
- **Fallback**: The container's .env is the primary source; vault sync is optional
|
||||
(unlike fleet agents which require vault injection)
|
||||
|
||||
**Current Key (2026-09-01):**
|
||||
- **Prefix**: `sk-or-v1-0af3f3…`
|
||||
- **User**: `user_2rt9lCqcd5d7Vk1t18DHsvWdPTT`
|
||||
- **Plan**: Paid (not free tier)
|
||||
- **Usage**: 0 (as of 2026-09-01)
|
||||
|
||||
**Model Configuration:**
|
||||
- **Preset**: "Cost Efficient" (`/a0/usr/plugins/_model_config/presets.yaml`)
|
||||
- **Model**: `openrouter/moonshotai/kimi-k3`
|
||||
- **API Base**: (empty — uses OpenRouter default)
|
||||
|
||||
**Why not LiteLLM proxy?**
|
||||
Agent Zero's architecture was designed before the fleet adopted the LiteLLM proxy
|
||||
standard. The container runs `/exe/self_update_manager.py` and `/a0/run_ui.py` which
|
||||
directly call OpenRouter via Python's requests library. Converting would require:
|
||||
1. Refactoring all LLM calls to use `litellm` library
|
||||
2. Adding vault wrapper injection
|
||||
3. Updating self_update_manager to use proxy-aware key handling
|
||||
|
||||
**Rotation Procedure:**
|
||||
1. Generate new key in OpenRouter UI
|
||||
2. Update container: `sed -i 's/^API_KEY_OPENROUTER=.*/API_KEY_OPENROUTER=<new_key>/' /a0/usr/.env`
|
||||
3. Update vault: `infisical secrets set OPENROUTER_API_KEY=<new_key> --projectId=agents --env=production`
|
||||
4. Restart container: `sudo docker exec agent-zero supervisorctl restart run_ui`
|
||||
5. Verify: `curl -s https://openrouter.ai/api/v1/auth/key -H "Authorization: Bearer <new_key>"`
|
||||
|
||||
**Related Contract:**
|
||||
- `agent-zero-openrouter-key.prose.md` — Full agent-zero key management contract
|
||||
|
||||
## Key Rotation Log
|
||||
|
||||
| Date | Agent | Action | Notes |
|
||||
|------|-------|--------|-------|
|
||||
| 2026-07-17 | fleet | standardize | All 4 agents standardized on systemd drop-in + while-true wrapper + infisical v0.43.109. Removed conflicting zulip-env.conf + litellm-key.conf drop-ins. Added .env fallbacks with ZULIP keys. WAL #1322. |
|
||||
| 2026-07-17 | tanko | fix-zulip | Added ZULIP_API_KEY to env (was missing — systemd bypassed vault). Updated wrapper from exec to while-true. Created .env fallback. Removed hardcoded zulip-env.conf drop-in. WAL #1321. |
|
||||
| 2026-07-16 | vault | cleanup | 4 stale secrets deprecated. 5 personal creds flagged. |
|
||||
| 2026-07-16 | koonimo | add-zulip | Added KOONIMO_ZULIP_API_KEY to vault. Wrapper injects ZULIP_API_KEY + ZULIP_EMAIL. 3 platforms. |
|
||||
| 2026-07-16 | tanko | migrate | Migrated from hardcoded config.yaml to infisical-gateway.sh + st.353699cd. NOTE: st.353699cd later deleted — reverted to st.8e848433 on 2026-07-17. |
|
||||
| 2026-07-16 | mumuni | rotate | Old key malformed (sk-_SWAl_Vu_, 47 chars, not LiteLLM format) → 401. Deleted old `mumuni` key (token 15cbca18…), generated fresh (alias `mumuni`, 7 models: syslog-auto, qwen3.6-27B-code, gemma-4-12b, strix-moe, gpu-dense, gpu-light, qwen3.6-35B-udq4). New key sk-OzuWsoX2… written to /root/.hermes/.env (Rule 3/13 fallback). Vault sync PENDING (needs machine identity). WAL #1300. |
|
||||
| 2026-07-16 | koby | rotate | Old key sk-6sbCNjz (401, stale in /etc/environment). Deleted old `koby` key, generated fresh (alias `koby`). New key sk-BqRRMboTI… in systemd drop-in `hermes-gateway.service.d/litellm-key.conf` + /etc/environment. Created `hermes-gateway.service` unit (was missing — gateway wasn't persistent) with `--replace`. Verified HTTP 200, Telegram connected. |
|
||||
| 2026-07-16 | baggy (koonimo) | rotate | Old key sk-krnw_zGB (401, hardcoded in systemd drop-in). Deleted old `baggy` key, generated fresh (alias `baggy`, metadata agent=koonimo). New key sk-OEK7z26n6E… in drop-in `hermes-gateway.service.d/litellm-key.conf`. CT113 IP changed .113→.114. Verified HTTP 200, Zulip connected. |
|
||||
|
||||
## LiteLLM Master Key (use sparingly — agents should NOT use it directly)
|
||||
|
||||
- Master key: `sk-litellm-7f96080dd99b15c36bd4b333b58a6796` (in /opt/inference-harness/.env on CT116, Infisical project=infrastructure env=production secret=LITELLM_MASTER_KEY)
|
||||
- Used for /key/generate, /key/delete, /key/list (GET), DB queries
|
||||
- **Known violation (RESOLVED 2026-07-16):** Abiba's LITELLM_API_KEY was previously the master key.
|
||||
It is now a dedicated agent key `sk-sxbphLvk1OU…` (vault secret `ABIBA_LITELLM_API_KEY`, alias `abiba-pi`).
|
||||
The master key is admin-only (/key/generate, /key/delete, /key/list). NEVER use it for inference —
|
||||
see `litellm-self-heal` § "NEVER use litellm_proxy_master_key for inference".
|
||||
- LiteLLM key DB: `harness-postgres` container on CT116, table `"LiteLLM_VerificationToken"` (columns: token, key_alias, key_name, created_at, expires). Query: `docker exec harness-postgres psql -U litellm -d litellm -t -c "SELECT key_alias, substr(token,1,16) FROM \"LiteLLM_VerificationToken\" ORDER BY created_at;"`
|
||||
|
||||
@@ -1,117 +0,0 @@
|
||||
---
|
||||
kind: pattern
|
||||
name: litellm-client-timeouts
|
||||
description: >
|
||||
Standard client timeout and retry policy for ALL agents calling LiteLLM
|
||||
(CT 116, http://192.168.68.116). Created 2026-09-08 after the Sep 6 incident:
|
||||
a backend stall 04:00-06:30 EDT produced 157 client-abandoned 408 failures
|
||||
(82% from abiba-pi, 13 from mumuni) against a backend that was actually
|
||||
succeeding at 20-70s per call once clients stopped giving up. Grounded in
|
||||
measured data: syslog-auto (LiteLLM virtual model, no dedicated GPU — routes
|
||||
to backends) averages 28.8s/request with 25.4s TTFT over 888 calls/24h;
|
||||
nginx already allows 600s (Rule 5, verified 2026-08-09); the gap is entirely
|
||||
client-side. Blast radius if wrong: agents fall back to DeepSeek silently
|
||||
(key/timeout failures present as model degradation, not errors) or abandon
|
||||
healthy-but-slow reasoning calls, fragmenting long tasks.
|
||||
---
|
||||
|
||||
## Maintains
|
||||
|
||||
- client_timeout_standard: "litellm-client-timeouts v1.0 (2026-09-08)"
|
||||
- applies_to: ALL agents and scripts calling http://192.168.68.116 (main model path, auxiliary tasks, health probes, benchmark jobs)
|
||||
- verified_against: Prometheus litellm_* metrics 24h window ending 2026-09-08 ~10:00 EDT; live probe (syslog-auto tiny call 0.56s TTFB, 200 OK); nginx 600s proxy_read_timeout (Rule 5)
|
||||
|
||||
## The measured numbers these values come from
|
||||
|
||||
| Model | avg latency | avg TTFT | p-profile (24h) |
|
||||
|---|---|---|---|
|
||||
| syslog-auto | 28.8s | 25.4s | 68 calls took 30-120s; tail to ~300s under load |
|
||||
| qwen3.6-27B-code | 23.0s | — | same backend class as syslog-auto |
|
||||
| strix-moe | 7.5s | — | Strix Halo, healthy |
|
||||
| gemma-4-12b | 2.6s | — | RTX 5070, healthy |
|
||||
|
||||
Sep 6 incident timeline: failures 04:00-07:00 EDT (0% GPU util = wedged
|
||||
backend), full recovery 07:00-08:00 with ZERO client failures once requests
|
||||
tolerated 20-70s — 392 successful slow calls in the three hours after recovery.
|
||||
LiteLLM's internal queue time is ~0s; the latency is model inference, not
|
||||
proxy queuing.
|
||||
|
||||
## Parameters
|
||||
|
||||
### 1. Primary model path (model.default / custom_providers) — NO client timeout below 300s
|
||||
|
||||
- The default Hermes HTTP timeout (~60s) is TOO SHORT for syslog-auto's healthy
|
||||
28.8s average + 120-300s tail. Every 408 in the incident was a client
|
||||
abandoning a request the backend would have answered.
|
||||
- If the transport exposes a timeout setting for the main model, set it to
|
||||
**300s or more**. If it does not (current Hermes custom-provider path has no
|
||||
timeout knob), that is acceptable ONLY because nginx holds the request for
|
||||
600s — but any wrapper, script, or direct API call you write MUST set its own
|
||||
timeout >= 300s for syslog-auto/qwen-class calls.
|
||||
- Never hardcode a shorter timeout "to fail fast" on this path — failing fast
|
||||
here is what caused the incident.
|
||||
|
||||
### 2. Auxiliary tasks — keep template timeouts, one correction
|
||||
|
||||
- vision: 60s (keep), web_extract: 30s (keep) — gemma-4-12b averages 2.6s;
|
||||
these are fine.
|
||||
- compression: 300s (keep — this was already raised from 60 per gpu-fleet).
|
||||
- **gpu-dense delegation/x_search: set timeout >= 120s.** The RTX 3090
|
||||
(qwen3.6-27B-code backend, 23.0s avg) is the same speed class as
|
||||
syslog-auto; delegation defaults that assume fast responses will 408 the
|
||||
same way.
|
||||
|
||||
### 3. Retry policy — backoff, not repetition
|
||||
|
||||
- On timeout (408) or 5xx: retry up to **2 times** with exponential backoff
|
||||
(**15s, 45s**) before giving up.
|
||||
- Do NOT retry in a tight loop. The Sep 6 spike shape (65 failures in one hour
|
||||
from one key) was a batch job retrying without backoff while the backend was
|
||||
down — it multiplied load during recovery.
|
||||
- On 401/403: do NOT retry — that is a key/permission problem (see
|
||||
litellm-api-keys.prose.md and Rule 11); retrying just spams the log.
|
||||
- On 429: honor the retry-after header if present, else back off 60s.
|
||||
|
||||
### 4. Health probes — identify yourself and time out sanely
|
||||
|
||||
- Probes MUST NOT appear as keyless, model-less failures in the metrics (12
|
||||
such orphans appeared in the incident window and cost investigation time).
|
||||
Send a real model name and use a real (probe-designated) key.
|
||||
- Probe timeout: 30s. A probe that takes longer than 30s IS the alert —
|
||||
report "backend slow (>30s)" rather than hanging.
|
||||
- Probe cadence: at most hourly. The 6h litellm-health cron cadence is the
|
||||
standard; sub-hourly synthetic traffic distorts latency baselines.
|
||||
|
||||
### 5. Batch/benchmark jobs — schedule away from 04:00-07:00 EDT and chunk
|
||||
|
||||
- The incident window showed bulk clients amplifying a backend stall 5:1.
|
||||
- Batch jobs that can tolerate delay: schedule 09:00-17:00 EDT.
|
||||
- Any batch loop over N requests MUST sleep >= 5s between requests and honor
|
||||
the retry policy in section 3.
|
||||
|
||||
## Returns
|
||||
|
||||
- A single standard any agent or script can cite: timeouts >= 300s on the
|
||||
syslog-auto path, >= 120s on gpu-dense delegation, backoff retries (2x,
|
||||
15s/45s), identified probes at 30s/hourly, batch jobs chunked and
|
||||
day-scheduled.
|
||||
- Failure signature recognition: bulk 408s from multiple keys in one window =
|
||||
backend event (check gpu_utilization_percent: 0% = wedged, ~100% = saturated);
|
||||
single-key 408s = that client's timeout is too short.
|
||||
- Cross-references: hermes-config-template.prose.md (Rule 5 nginx 600s,
|
||||
auxiliary timeouts), gpu-fleet.prose.md (compression 300s precedent,
|
||||
stable aliases), litellm-api-keys.prose.md (key/permission failures).
|
||||
|
||||
## Intentionally NOT changed
|
||||
|
||||
- No server-side LiteLLM timeout/cooldown changes proposed — the incident
|
||||
self-recovered and the server is healthy (0.56s live probe); changing
|
||||
server behavior without process-level root cause (CT116 requires root;
|
||||
not reachable from kagentz) would be guessing.
|
||||
- No change to the template's vision/web_extract/compression timeouts —
|
||||
measured data says they are correct.
|
||||
- No per-agent key permission changes — those are litellm-api-keys.prose.md
|
||||
territory (and the open gpu-vision/gemma 403 items are already filed with
|
||||
the key owners).
|
||||
- No model routing changes — syslog-auto's weighted pool behaved correctly
|
||||
throughout the incident.
|
||||
+23
-31
@@ -12,21 +12,12 @@ note: >
|
||||
description: >
|
||||
Verifies the LiteLLM inference stack health. Current architecture (2026-07-09):
|
||||
nginx:80 → LiteLLM:4000 → GPU(llama-server) via direct proxy.
|
||||
Router (harness-router :9000) was DECOMMISSIONED 2026-09-11 (container,
|
||||
image and config removed). GPU monitoring via Prometheus/Grafana and
|
||||
Router (harness-router :9000) is DEPRECATED — container still runs but
|
||||
is not in the request path. GPU monitoring via Prometheus/Grafana and
|
||||
fleet dashboard (gpu-monitor :9100).
|
||||
Designed as a reusable contract for any Syslog agent.
|
||||
|
||||
Source of truth: gpu-fleet.prose.md
|
||||
|
||||
## Monitoring / Alerting (as-built 2026-08-09)
|
||||
|
||||
- LiteLLM /metrics scrape job: requires `litellm_settings.success_callback: [prometheus]`
|
||||
(failure_callback alone does NOT mount /metrics — verified 2026-08-09).
|
||||
Scraped by Prometheus with Bearer master key; endpoint returns 307 → /metrics/.
|
||||
- Alertmanager (harness-alertmanager :9093) + zulip-bridge (:9102) deliver
|
||||
firing alerts to #agent-hub > alerts-infra via abiba-bot. Added 2026-08-09.
|
||||
- Prometheus node job covers ALL 5 PVE nodes (.5/.6/.9/.12/.15:9100).
|
||||
---
|
||||
|
||||
## Architecture (v4.0.0 — Direct: nginx → LiteLLM → GPU)
|
||||
@@ -42,8 +33,8 @@ Request → nginx:80 → LiteLLM:4000 → GPU(llama-server, parallel 2)
|
||||
│
|
||||
Grafana :3001
|
||||
|
||||
harness-router :9000 — DECOMMISSIONED 2026-09-11 (container, image
|
||||
and config removed). nginx routes /v1 → LiteLLM directly.
|
||||
harness-router :9000 — DEPRECATED, container still runs but
|
||||
NOT in request path. nginx routes /v1 → LiteLLM directly.
|
||||
Router slot booking + circuit breakers replaced by
|
||||
LiteLLM native fallbacks + timeouts.
|
||||
```
|
||||
@@ -51,8 +42,8 @@ Request → nginx:80 → LiteLLM:4000 → GPU(llama-server, parallel 2)
|
||||
**What changed (v3.2.0 → v4.0.0 — 2026-07-08)**:
|
||||
- Router REMOVED from request path — LiteLLM proxies directly to GPU
|
||||
- All GPUs at parallel 2 (was parallel 1)
|
||||
- NVIDIA context reduced 256K→128K to free VRAM — now the stable ceiling across all GPUs (2026-07-17)
|
||||
- LiteLLM timeouts tuned: gemma 25→120s, qwen 40→90s (SUPERSEDED 2026-07-16: qwen 300s, gemma 120s, strix 300s — see litellm-self-heal)
|
||||
- NVIDIA context reduced 256K→128K to free VRAM
|
||||
- LiteLLM timeouts tuned: gemma 25→120s, qwen 40→90s
|
||||
- nginx proxy_read_timeout: 600s, LiteLLM request_timeout: 300s
|
||||
|
||||
## Parameters
|
||||
@@ -81,18 +72,18 @@ Request → nginx:80 → LiteLLM:4000 → GPU(llama-server, parallel 2)
|
||||
|
||||
| Host | IP | Hardware | Models Served | Engine | Context | Parallel |
|
||||
|------|-----|----------|---------------|--------|---------|----------|
|
||||
| llm-gpu | 192.168.68.8 | NVIDIA RTX 3090 (24 GB) | qwen3.6-27B-code | llama-server systemd | **128K** | 2 |
|
||||
| ocu-llm | 192.168.68.110 | NVIDIA RTX 5070 (12 GB) | gemma-4-12b | llama-server systemd | **128K** | 2 |
|
||||
| amdpve | 192.168.68.15 | AMD Strix Halo 64GB UMA | qwen3.6-35B-udq4 (LiteLLM alias: strix-moe) | llama-server systemd (Vulkan) | 128K | 2 |
|
||||
| llm-gpu | 192.168.68.8 | NVIDIA RTX 3090 (24 GB) | qwen3.6-27B-code | llama-server systemd | 128K | 2 |
|
||||
| ocu-llm | 192.168.68.110 | NVIDIA RTX 5070 (12 GB) | gemma-4-12b | llama-server systemd | 128K | 2 |
|
||||
| amdpve | 192.168.68.15 | AMD Strix Halo 64GB UMA | ornith-1.0-35b | llama-server systemd (Vulkan) | 256K | 2 |
|
||||
|
||||
## Model Fallback Chains (LiteLLM)
|
||||
|
||||
| Primary | Timeout | Fallback | Timeout |
|
||||
|---------|---------|----------|---------|
|
||||
| qwen3.6-27B-code | 300s | gemma-4-12b | 120s |
|
||||
| gemma-4-12b | 120s | qwen3.6-27B-code | 300s |
|
||||
| qwen3.6-35B-udq4 / strix-moe | 300s | qwen → gemma | — |
|
||||
| syslog-auto (balanced) | 300s | qwen → gemma | — |
|
||||
| qwen3.6-27B-code | 90s | gemma-4-12b | 120s |
|
||||
| gemma-4-12b | 120s | qwen3.6-27B-code | 90s |
|
||||
| ornith-1.0-35b | 120s | qwen → gemma | — |
|
||||
| syslog-auto (balanced) | 90s | qwen → gemma | — |
|
||||
|
||||
> Global: request_timeout=300s, nginx proxy_read_timeout=600s
|
||||
|
||||
@@ -100,7 +91,8 @@ Request → nginx:80 → LiteLLM:4000 → GPU(llama-server, parallel 2)
|
||||
|
||||
| Container | Image | Port | Health Check |
|
||||
|-----------|-------|------|-------------|
|
||||
| harness-litellm | ghcr.io/docker.litellm.ai/berriai/litellm:1.99.1 | :4000→:4000 | /health/liveliness |
|
||||
| harness-litellm | berriai/litellm:1.90.0-rc.1 | :4000→:4001 | /health/liveliness |
|
||||
| harness-router | inference-harness-router | :9000 (127.0.0.1) | /health (DEPRECATED — not in path) |
|
||||
| harness-nginx | nginx:alpine | :80 | HTTP 200 on /health |
|
||||
| harness-postgres | postgres:16-alpine | :5432 | pg_isready |
|
||||
| harness-redis | redis:7-alpine | :6379 | PING |
|
||||
@@ -120,14 +112,14 @@ Request → nginx:80 → LiteLLM:4000 → GPU(llama-server, parallel 2)
|
||||
- GET http://{{backend_host}}/litellm/health/liveliness → expect 200
|
||||
|
||||
4. **Check backend container health**:
|
||||
- SSH to {{backend_host}} → `docker ps` → verify 11 containers healthy
|
||||
- Critical: harness-litellm, harness-nginx, harness-postgres
|
||||
- Monitoring: harness-redis, harness-dashboard, harness-grafana, harness-prometheus,
|
||||
harness-alertmanager, harness-zulip-bridge, harness-docker-stats, harness-pve-exporter
|
||||
- SSH to {{backend_host}} → `docker ps` → verify 8 containers healthy
|
||||
- Critical: harness-litellm, harness-router, harness-nginx, harness-postgres
|
||||
- Monitoring: harness-redis, harness-dashboard, harness-grafana, harness-prometheus
|
||||
|
||||
5. **Check GPU fleet health via gpu-monitor** (router decommissioned 2026-09-11):
|
||||
- GET {{gpu_dashboard_url}}/gpu-data → expect 200 with GPU metrics JSON
|
||||
- nginx `/health/unified` is now a `301` redirect to `/gpu/gpu-data` (same payload)
|
||||
5. **Check router roster loaded**:
|
||||
- GET http://{{backend_host}}:9000/health → expect 200
|
||||
- GET http://{{backend_host}}:9000/health/unified → expect 3 models
|
||||
- If router returns "all GPUs saturated" but GPUs idle: roster not loaded → reload
|
||||
|
||||
6. **Check GPU fleet health** (via fleet dashboard):
|
||||
- GET {{gpu_dashboard_url}}/gpu-data → expect 200 with GPU metrics JSON
|
||||
@@ -137,7 +129,7 @@ Request → nginx:80 → LiteLLM:4000 → GPU(llama-server, parallel 2)
|
||||
7. **Check model inference via LiteLLM** — Test each model:
|
||||
- POST /v1/chat/completions model=gemma-4-12b → expect 200
|
||||
- POST /v1/chat/completions model=qwen3.6-27B-code → expect 200
|
||||
- POST /v1/chat/completions model=strix-moe → expect 200
|
||||
- POST /v1/chat/completions model=ornith-1.0-35b → expect 200
|
||||
- Use master key for auth
|
||||
|
||||
8. **Check agent keys**:
|
||||
|
||||
+28
-84
@@ -1,29 +1,23 @@
|
||||
---
|
||||
report_only_agents:
|
||||
- koby # ⛔ KOBY IS NEVER REPAIRED (Rule 17, 2026-08-17) — detect + report, never fix on .129
|
||||
kind: responsibility
|
||||
name: litellm-self-heal
|
||||
status: deployed
|
||||
status: manual-only
|
||||
note: >
|
||||
DEPLOYED 2026-07-12 on CT 116 cron: 0 */6 * * *
|
||||
Auto-remediation code was removed from the pi Zulip extension (retired 2026-07-04),
|
||||
now reimplemented as `litellm-health-check.sh` on CT 116.
|
||||
Script: `/opt/inference-harness/scripts/litellm-health-check.sh` on CT 116 (cron `0 */6 * * *`).
|
||||
Reports to /var/log/litellm/health-*.json and Gitea (SyslogSolution/health-logs).
|
||||
GPU monitoring integrated from gpu-monitor on .24:9100.
|
||||
Auto-remediation code was removed from the pi Zulip extension (retired 2026-07-04).
|
||||
This contract is now manual-only — triggers require explicit user request.
|
||||
Consider reimplementing as a standalone cron job or prose contract.
|
||||
|
||||
Consolidated from litellm-health + litellm-self-heal on 2026-07-09 to eliminate
|
||||
duplication of architecture diagrams, GPU topology, timeout tables, and container
|
||||
lists. Health check is now § Health Check within this contract.
|
||||
|
||||
Source of truth for GPU topology and keys: gpu-fleet.prose.md
|
||||
Last verified: 2026-07-12
|
||||
Last verified: 2026-07-09
|
||||
description: >
|
||||
LiteLLM inference stack health monitoring + self-healing. Verifies the full
|
||||
nginx → LiteLLM → GPU chain, 11 containers on CT 116, 3 GPU hosts, model
|
||||
nginx → LiteLLM → GPU chain, 8 containers on CT 116, 3 GPU hosts, model
|
||||
inference, and agent keys. Applies remediation rules for common failures.
|
||||
Reports every action via Zulip DM and Gitea (SyslogSolution/health-logs).
|
||||
---
|
||||
Reports every action via Zulip DM and RA-H OS knowledge graph.
|
||||
---
|
||||
|
||||
# LiteLLM Operations — Health Check + Self-Heal
|
||||
@@ -41,8 +35,8 @@ Request → nginx:80 → LiteLLM:4000 → GPU(llama-server, parallel 2)
|
||||
│
|
||||
Grafana :3001
|
||||
|
||||
harness-router :9000 — DECOMMISSIONED 2026-09-11 (container, image
|
||||
and config removed). nginx routes /v1 → LiteLLM directly.
|
||||
harness-router :9000 — DEPRECATED, container still runs but
|
||||
NOT in request path. nginx routes /v1 → LiteLLM directly.
|
||||
Router slot booking + circuit breakers replaced by
|
||||
LiteLLM native fallbacks + timeouts.
|
||||
```
|
||||
@@ -60,37 +54,18 @@ Request → nginx:80 → LiteLLM:4000 → GPU(llama-server, parallel 2)
|
||||
|
||||
| Host | IP | Hardware | Models Served | Engine | Context | Parallel |
|
||||
|------|-----|----------|---------------|--------|---------|----------|
|
||||
| llm-gpu | 192.168.68.8 | NVIDIA RTX 3090 (24 GB) | qwen3.6-27B-code | llama-server systemd (`/home/llmuser/llama-wrapper.sh`, `-c 131072 --parallel 2 --ngl 99`) | **128K** | 2 |
|
||||
| ocu-llm | 192.168.68.110 | NVIDIA RTX 5070 (12 GB) | gemma-4-12b | llama-server systemd (`/home/llmuser/llama-wrapper.sh`, `--ctx-size 131072 --parallel 2`, IQ4_NL + MTP draft) | **128K** | 2 |
|
||||
| amdpve | 192.168.68.15 | AMD Strix Halo 64GB UMA | qwen3.6-35B-udq4 (LiteLLM alias: `strix-moe`) | llama-server systemd (Vulkan) | 128K | 2 |
|
||||
|
||||
> Verified on ground 2026-07-16 via `curl /v1/models` on each host + `llama-wrapper.sh`. The AMD host's underlying model is `qwen3.6-35B-udq4`; LiteLLM exposes it under two `model_name`s: `qwen3.6-35B-udq4` and `strix-moe` (rpm 40). The legacy name `ornith-1.0-35b` does NOT exist in LiteLLM and must not be referenced.
|
||||
|
||||
## LiteLLM Model Surface (ground truth — `/opt/inference-harness/litellm_config.yaml` on CT 116)
|
||||
|
||||
`model_name`s served: `qwen3.6-27B-code`, `gemma-4-12b`, `qwen3.6-35B-udq4`, `strix-moe`, `gpu-dense`, `gpu-light`, `syslog-auto`, `crew-auto` (new 2026-08-20).
|
||||
|
||||
### Context Cap Split (2026-08-20)
|
||||
|
||||
- **Abiba (firstmate)**: 128K uncapped — unlimited context for primary workloads
|
||||
- **Hermes agents** (mumuni, tanko, koby, koonimo): 128K uncapped
|
||||
- **Crewmates** (ops, tune, verify, auth-keys, build): 64K capped — alias `crew-auto` enforces 64K limit
|
||||
|
||||
Preferred implementation: uncap shared pool, add capped alias for crew-only.
|
||||
|
||||
- `syslog-auto` is a weighted router model: qwen3.6-27B-code (0.55, rpm 500) + qwen3.6-35B-udq4 (0.30, rpm 60) + gemma-4-12b (0.15, rpm 200).
|
||||
- `gpu-dense` / `gpu-light` are high-rpm aliases (rpm 500) onto qwen3.6-27B-code / gemma-4-12b respectively.
|
||||
- Key scoping: agent keys are restricted to `['syslog-auto','qwen3.6-27B-code','gemma-4-12b','strix-moe','gpu-dense','gpu-light']`. As of 2026-07-16 the `baggy`/`koby`/`mumuni`/`abiba-pi` keys ALSO include `qwen3.6-35B-udq4`; `abiba-pi` additionally includes `deepseek-v4-pro` (cloud fallback). `kagenz0`/`koonimo`/`pi-agents-unified` have the standard 6 only. Agents should still use the stable alias `strix-moe` (not the raw `qwen3.6-35B-udq4`) so model swaps don't break them.
|
||||
- **NEVER use `litellm_proxy_master_key` (the `sk-litellm-...` master key) for inference.** It is for admin endpoints only (`/key/list`, `/key/generate`, `/key/info`). All inference — agent traffic, health-check model tests, monitor scripts — uses agent-specific keys. The health-check script's model tests use a dedicated `monitor` agent key stored at `/etc/litellm-monitor.env` on CT 116 (root-only, `chmod 600`); `/key/list` is the only call that legitimately uses `$MASTER_KEY`.
|
||||
| llm-gpu | 192.168.68.8 | NVIDIA RTX 3090 (24 GB) | qwen3.6-27B-code | llama-server systemd | 128K | 2 |
|
||||
| ocu-llm | 192.168.68.110 | NVIDIA RTX 5070 (12 GB) | gemma-4-12b | llama-server systemd | 128K | 2 |
|
||||
| amdpve | 192.168.68.15 | AMD Strix Halo 64GB UMA | ornith-1.0-35b | llama-server systemd (Vulkan) | 256K | 2 |
|
||||
|
||||
## Model Fallback Chains (LiteLLM)
|
||||
|
||||
| Primary | Timeout | Fallback | Timeout |
|
||||
|---------|---------|----------|---------|
|
||||
| qwen3.6-27B-code | 300s | gemma-4-12b | 120s |
|
||||
| gemma-4-12b | 120s | qwen3.6-27B-code | 300s |
|
||||
| qwen3.6-35B-udq4 / strix-moe | 300s | qwen → gemma | — |
|
||||
| syslog-auto (balanced) | 300s | qwen → gemma | — |
|
||||
| qwen3.6-27B-code | 90s | gemma-4-12b | 120s |
|
||||
| gemma-4-12b | 120s | qwen3.6-27B-code | 90s |
|
||||
| ornith-1.0-35b | 120s | qwen → gemma | — |
|
||||
| syslog-auto (balanced) | 90s | qwen → gemma | — |
|
||||
|
||||
> Global: request_timeout=300s, nginx proxy_read_timeout=600s
|
||||
|
||||
@@ -98,7 +73,8 @@ Preferred implementation: uncap shared pool, add capped alias for crew-only.
|
||||
|
||||
| Container | Image | Port | Health Check |
|
||||
|-----------|-------|------|-------------|
|
||||
| harness-litellm | ghcr.io/docker.litellm.ai/berriai/litellm:1.99.1 | :4000→:4000 | /health/liveliness |
|
||||
| harness-litellm | berriai/litellm:1.90.0-rc.1 | :4000→:4001 | /health/liveliness |
|
||||
| harness-router | inference-harness-router | :9000 (127.0.0.1) | /health (DEPRECATED — not in path) |
|
||||
| harness-nginx | nginx:alpine | :80 | HTTP 200 on /health |
|
||||
| harness-postgres | postgres:16-alpine | :5432 | pg_isready |
|
||||
| harness-redis | redis:7-alpine | :6379 | PING |
|
||||
@@ -108,13 +84,6 @@ Preferred implementation: uncap shared pool, add capped alias for crew-only.
|
||||
| harness-docker-stats | python:3.12-alpine | — | container stats exporter |
|
||||
| harness-pve-exporter | prompve/prometheus-pve-exporter | — | Proxmox metrics → Prometheus |
|
||||
|
||||
## Script Operations (synced 2026-07-16)
|
||||
|
||||
- **Health-check script** (`/opt/inference-harness/scripts/litellm-health-check.sh` on CT 116): `gpu-fleet` check fails only on **critical** alerts (warnings are informational). Tests `strix-moe` (not `ornith-1.0-35b`).
|
||||
- **GPU monitor** (`/root/scripts/gpu-monitor-server.py` on pi .24): runs as **systemd unit `gpu-monitor.service`** (was bare `&` process). `gpu_count` includes Strix Halo (was 2, now 3). VRAM alert thresholds: warning 93%, critical 97% (raised from 90/95 — 128K context steady-state is ~70% on RTX 3090, not a fault).
|
||||
- **Agent key monitor** (`/root/scripts/agent-health-check.py` on pi .24, cron `*/10`): v4 (2026-09-10) — vault-backed agents (tanko/koby/koonimo) read their **agent-specific** `{NAME}_LITELLM_API_KEY` from Infisical vault (not the shared master key); abiba (pi agent) reads `LITELLM_API_KEY` from its local `/root/.pi/agent/env.sh` (#735 — moved out of shared `/root/.bashrc`), not from the vault. Abiba is pi-only since the harness purge, so its Hermes config/wrapper/gateway legs are skipped rather than reported as faults; koby is **report-only** (captain's 2026-08-17 ruling) — its findings go to the `--json` `report_only` array and are never counted as fleet failures or repaired, and its CT 111 liveness is probed on storepve (.6). Covers: LiteLLM keys, GPU ports, agent gateways, CT liveness (pct status on PVE nodes), config.yaml YAML integrity, wrapper/CLI integrity, vault secret non-emptiness checks. Every run/report carries the absolute execution path (`script=` + `cwd=`). The current fleet roster is owned by the script changelog (`scripts/agent-health-check.py`); mumuni is no longer probed from this host. Legacy `tdunna`/`baggy` replaced with canonical agent hostnames.
|
||||
- **Stale keys cleaned**: `daily-infra-report.py` SYNTHETIC_API_KEY was stale (`sk-U_ydi3B` → 401); now reads `LITELLM_MASTER_KEY` from env. Deprecated scripts (`router-original.py`, `router-phase0-backup.py`, `apply-fixes.py`) still reference `sk-syslog-local-master-key` but do not actively poll LiteLLM.
|
||||
|
||||
## Maintains
|
||||
|
||||
- litellm-admin-ui: { status: "healthy", last_check: timestamp }
|
||||
@@ -130,7 +99,6 @@ Preferred implementation: uncap shared pool, add capped alias for crew-only.
|
||||
- Also wakes on user request
|
||||
- On failure: re-check after 30s, escalate after 3 consecutive failures
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## Health Check
|
||||
@@ -145,11 +113,10 @@ Run this first on every cycle. Results feed into remediation rules below.
|
||||
- GET http://{{backend_host}}/litellm/health/liveliness → expect 200
|
||||
|
||||
### 3. Check backend container health
|
||||
- SSH to {{backend_host}} → `docker ps` → verify 11 containers healthy
|
||||
- SSH to {{backend_host}} → `docker ps` → verify 10 containers healthy
|
||||
- Critical: harness-litellm, harness-nginx, harness-postgres
|
||||
- Monitoring: harness-redis, harness-dashboard, harness-grafana, harness-prometheus,
|
||||
harness-alertmanager, harness-zulip-bridge, harness-docker-stats, harness-pve-exporter
|
||||
- Decommissioned 2026-09-11: harness-router (container, image and config removed)
|
||||
- Monitoring: harness-redis, harness-dashboard, harness-grafana, harness-prometheus, harness-docker-stats, harness-pve-exporter
|
||||
- Deprecated but running: harness-router (not in path, reference only)
|
||||
|
||||
### 4. Check GPU fleet health (via fleet dashboard)
|
||||
- GET {{gpu_dashboard_url}}/gpu-data → expect 200 with GPU metrics JSON
|
||||
@@ -159,7 +126,7 @@ Run this first on every cycle. Results feed into remediation rules below.
|
||||
### 5. Check model inference via LiteLLM — test each model
|
||||
- POST /v1/chat/completions model=gemma-4-12b → expect 200
|
||||
- POST /v1/chat/completions model=qwen3.6-27B-code → expect 200
|
||||
- POST /v1/chat/completions model=strix-moe → expect 200
|
||||
- POST /v1/chat/completions model=ornith-1.0-35b → expect 200
|
||||
- Use master key for auth
|
||||
|
||||
### 6. Check agent keys
|
||||
@@ -174,7 +141,6 @@ Determine overall_status from individual check results:
|
||||
- "degraded" — 1-2 non-critical checks fail
|
||||
- "down" — critical checks fail
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## Remediation Rules
|
||||
@@ -215,19 +181,17 @@ Fix → generate keys in LiteLLM via /key/generate → update /etc/environment o
|
||||
Escalate → if SSH access unavailable, send Zulip DM
|
||||
|
||||
### Rule 9: Stale Active Counter in Redis — DEPRECATED
|
||||
Router no longer in path so router active-slot counters are unused. Rule retained
|
||||
for reference but inactive. `harness-redis` now serves only LiteLLM cache and
|
||||
rate-limit state; check the container if cache errors appear.
|
||||
Router no longer in path so Redis active counters are unused. Rule retained
|
||||
for reference but inactive. If Redis issues occur, check harness-redis container.
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## Reporting
|
||||
|
||||
Every remediation cycle produces a structured report:
|
||||
|
||||
### 1. Gitea Log Entry
|
||||
Pushed to `SyslogSolution/health-logs/litellm/{run_id}.json` — versioned, searchable, not in graph.
|
||||
### 1. RA-H OS Knowledge Graph Node
|
||||
Created as `[LEARN] litellm-self-heal: <run_id>` with full JSON report.
|
||||
|
||||
### 2. Zulip DM to Owner
|
||||
- `issues_fixed > 0` — "🛠 LiteLLM Self-Heal — Fix Applied"
|
||||
@@ -242,7 +206,6 @@ top actions, uptime.
|
||||
If a fix requires another agent (e.g., Authentik restart), relay sent
|
||||
to responsible agent with full context.
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## Execution
|
||||
@@ -268,11 +231,9 @@ call report-generator
|
||||
health: health
|
||||
actions: actions
|
||||
|
||||
-- Phase 4: Log to Gitea (not knowledge graph — hard rule)
|
||||
call gitea-logger
|
||||
-- Phase 4: Log to knowledge graph
|
||||
call kg-logger
|
||||
run_id: run_id
|
||||
repo: SyslogSolution/health-logs
|
||||
path: litellm/{run_id}.json
|
||||
health: health
|
||||
actions: actions
|
||||
|
||||
@@ -318,20 +279,3 @@ With failures:
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## gitea-logger Implementation
|
||||
|
||||
When this step executes, write the report JSON to a temp file and push to Gitea:
|
||||
|
||||
```bash
|
||||
REPO="https://abiba-bot:${GITEA_PAT}@git.sysloggh.net/SyslogSolution/health-logs"
|
||||
DIR="litellm"
|
||||
FILE="${run_id}.json"
|
||||
echo "${report_json}" > /tmp/${FILE}
|
||||
(cd /tmp && git clone --depth 1 "${REPO}" &&
|
||||
cp ${FILE} health-logs/${DIR}/${FILE} &&
|
||||
cd health-logs && git add ${DIR}/${FILE} &&
|
||||
git commit -m "litellm-health: ${run_id}" && git push)
|
||||
rm -rf /tmp/health-logs /tmp/${FILE}
|
||||
```
|
||||
|
||||
|
||||
@@ -1,12 +1,9 @@
|
||||
---
|
||||
report_only_agents:
|
||||
- koby # ⛔ KOBY IS NEVER REPAIRED (Rule 17, 2026-08-17) — detect + report, never fix on .129
|
||||
name: memory-audit-maintenance
|
||||
kind: responsibility
|
||||
description: Shared memory audit and maintenance contract for Hermes agents (Mumuni, Koby, Koonimo). Tanko is no longer a Hermes agent (now on DSH/DeepSeek Harness since 2026-08-27) and uses DSH-native memory, so it is excluded from this Hermes roster. Each agent runs it against its own isolated memory files — no cross-agent access, no shared state. Detects staleness, enforces writer registry, and rotates canary tokens.
|
||||
description: Shared memory audit and maintenance contract for all Hermes agents (Mumuni, Tanko, Tdunna, Baggy). Each agent runs it against its own isolated memory files — no cross-agent access, no shared state. Detects staleness, enforces writer registry, and rotates canary tokens.
|
||||
id: 067NC4KG01RG50R40M30E20918
|
||||
---
|
||||
---
|
||||
|
||||
### Goal
|
||||
|
||||
@@ -18,12 +15,13 @@ Autonomously audit and reorganize an agent's native memory (MEMORY.md, USER.md,
|
||||
|
||||
### Scope
|
||||
|
||||
This contract is the **Hermes Agent standard** for memory maintenance. It is shared across Hermes agents (Mumuni, Koby, Koonimo). **Tanko is excluded — it migrated to DSH (DeepSeek Harness) on 2026-08-27 and now uses DSH-native memory (mnemon), not `~/.hermes/memories/`.** Each agent runs it against its own memory files only no cross-agent access, no shared state, no shared ledger, no shared canary. The contract is the standard; each agent enforces it independently with fully isolated data.
|
||||
This contract is the **Hermes Agent standard** for memory maintenance. It is shared across all Hermes agents (Mumuni, Tanko, Tdunna, Baggy). Each agent runs it against its own memory files only no cross-agent access, no shared state, no shared ledger, no shared canary. The contract is the standard; each agent enforces it independently with fully isolated data.
|
||||
|
||||
**Agent Roster (Hermes):**
|
||||
**Agent Roster:**
|
||||
- Mumuni
|
||||
- Koby (CT 111 / tdunna)
|
||||
- Koonimo (CT 113 / baggy)
|
||||
- Tanko
|
||||
- Tdunna
|
||||
- Baggy
|
||||
|
||||
**Isolation Principle:** Each agent has its own:
|
||||
- `MEMORY.md` and `USER.md`
|
||||
@@ -345,3 +343,4 @@ return {
|
||||
|
||||
### Per-Agent Notes
|
||||
|
||||
Each Hermes agent (Mumuni, Tanko, Tdunna, Baggy) runs this contract against its own `~/.hermes/memories/` directory. The contract is identical across agents, but all data is fully isolated: separate ledgers, separate writer registries, separate canaries. If a new agent is added to the roster, it must be listed in `### Scope` above and given its own isolated memory directory.
|
||||
@@ -1,202 +0,0 @@
|
||||
---
|
||||
report_only_agents:
|
||||
- koby # ⛔ KOBY IS NEVER REPAIRED (Rule 17, 2026-08-17) — detect + report, never fix on .129
|
||||
kind: pattern
|
||||
name: memory-fixer
|
||||
description: >
|
||||
Auto-fix low-hanging fruit in the RA-H OS knowledge graph. No judgment calls — only deterministic Level 1 operations.
|
||||
Escalate anything that needs Kwame's input. Executes confirmed Kwame decisions to completion (state + updated_at).
|
||||
version: 2.1.0
|
||||
---
|
||||
---
|
||||
|
||||
# Memory Fixer
|
||||
|
||||
> **Canonical copy:** `/root/.hermes/contracts/memory-fixer-v3.md` (used by the `memory-fixer-daily` cron job). This file is the institutional record of the same contract. When the two diverge, treat the v3 source in `/root/.hermes/contracts/` as executable truth.
|
||||
|
||||
## Purpose
|
||||
Auto-fix low-hanging fruit in the graph. No judgment calls — only deterministic Level 1 operations. Escalate anything that needs Kwame's input. When Kwame replies to an escalation, **execute the decision to completion** (update state and timestamps), never leaving a node in review-pending forever.
|
||||
|
||||
**Type:** Write-only (Level 1 fixes only)
|
||||
**Scope:** RA-H OS knowledge graph (192.168.68.65)
|
||||
**Schedule:** Daily at 8 AM ET
|
||||
**Escalation:** Level 2+ to Kwame as task items
|
||||
|
||||
## Key Design Decision
|
||||
|
||||
The `updateNode` tool's `metadata` field performs a **restricted merge** — the `state` key only accepts `'processed'` or `'not_processed'`. Additionally, new metadata keys cannot be added via the merge.
|
||||
|
||||
**Solution:** Use the `description` field to tag stale nodes with review actions, since `description` is a simple string overwritable via `updateNode`.
|
||||
|
||||
**Tag Format:** `[REVIEW: action] original description text...`
|
||||
|
||||
Where `action` is one of:
|
||||
- `archive` — node is stale and should be archived
|
||||
- `refresh` — node is stale and should be refreshed (infrastructure)
|
||||
- `keep` — node has been confirmed as current
|
||||
- `merge` — node is a duplicate candidate
|
||||
|
||||
**Query for finding review-tagged nodes:**
|
||||
```sql
|
||||
SELECT id, title, description
|
||||
FROM nodes
|
||||
WHERE description LIKE '[REVIEW:%';
|
||||
```
|
||||
|
||||
## Level 1 Auto-Fixes (No Kwame Decision Needed)
|
||||
|
||||
### 1. Missing `type` Auto-Classification
|
||||
|
||||
```sql
|
||||
SELECT id, title,
|
||||
CASE
|
||||
WHEN title LIKE '%infrastructure%' OR title LIKE '%proxmox%' OR title LIKE '%setup%' THEN 'infrastructure'
|
||||
WHEN title LIKE '%skill%' OR title LIKE '%how to%' OR title LIKE '%guide%' THEN 'skill'
|
||||
WHEN title LIKE '%doc%' OR title LIKE '%template%' OR title LIKE '%brand%' THEN 'documentation'
|
||||
WHEN title LIKE 'WAL:%' OR title LIKE 'TASK:%' THEN 'note'
|
||||
WHEN title LIKE '%[LEARN]%' THEN 'documentation'
|
||||
ELSE 'note'
|
||||
END as auto_type
|
||||
FROM nodes
|
||||
WHERE json_extract(metadata, '$.type') IS NULL;
|
||||
```
|
||||
|
||||
### 2. Missing `namespace` Auto-Population
|
||||
|
||||
```sql
|
||||
SELECT id, title, json_extract(metadata, '$.tenant') as tenant
|
||||
FROM nodes
|
||||
WHERE json_extract(metadata, '$.namespace') IS NULL;
|
||||
```
|
||||
|
||||
### 3. Staleness Review Tagging (refresh-suggested nodes only)
|
||||
|
||||
Using the type-based windows from the memory-monitor contract, tag nodes stale beyond their window. **Only process a maximum of 10 nodes per run** to avoid overwhelming Kwame. Prioritize infrastructure first, then dynamic, then ephemeral.
|
||||
|
||||
**Archive-suggested nodes are NO LONGER tagged — they are archived outright (see Level 1 fix 4).** Tagging with `[REVIEW: refresh]` applies only to living nodes (infrastructure, deployment, system, system-health, business, philosophy, research, learning, investigation, analysis, project, agent, registry, policy).
|
||||
|
||||
**Exclusion Rules:**
|
||||
- Nodes with `state` = `review_pending`, `deprecated`, `archived`, or `not_processed` are NOT processed
|
||||
- Nodes whose `description` already starts with `[REVIEW:` or `[ARCHIVED]` are NOT re-processed
|
||||
|
||||
```sql
|
||||
SELECT id, title, json_extract(metadata, '$.type') as node_type,
|
||||
CAST(julianday('now') - julianday(updated_at) AS INTEGER) as days_stale,
|
||||
CASE
|
||||
WHEN json_extract(metadata, '$.type') IN ('infrastructure', 'deployment', 'system', 'system-health') THEN 'refresh'
|
||||
WHEN json_extract(metadata, '$.type') IN ('business', 'philosophy', 'research', 'learning', 'learn', 'investigation', 'analysis', 'project') THEN 'refresh'
|
||||
ELSE 'archive'
|
||||
END as suggested_action
|
||||
FROM nodes
|
||||
WHERE updated_at < datetime('now',
|
||||
CASE
|
||||
WHEN json_extract(metadata, '$.type') IN ('infrastructure', 'deployment', 'system', 'system-health') THEN '-14 days'
|
||||
WHEN json_extract(metadata, '$.type') IN ('skill', 'documentation', 'template', 'protocol-enforcement', 'prd', 'architecture') THEN '-90 days'
|
||||
WHEN json_extract(metadata, '$.type') IN ('note', 'wal', 'WAL', 'task', 'TASK', 'event') THEN '-30 days'
|
||||
WHEN json_extract(metadata, '$.type') IN ('business', 'philosophy', 'research', 'learning', 'learn', 'investigation', 'analysis', 'project') THEN '-120 days'
|
||||
WHEN json_extract(metadata, '$.type') IN ('deprecated-relay', 'audit', 'audit-report', 'incident', 'incident-report') THEN '-3650 days'
|
||||
ELSE '-45 days'
|
||||
END
|
||||
)
|
||||
AND json_extract(metadata, '$.state') NOT IN ('review_pending', 'deprecated', 'archived', 'not_processed')
|
||||
AND (description IS NULL OR description NOT LIKE '[REVIEW:%')
|
||||
ORDER BY days_stale ASC
|
||||
LIMIT 10;
|
||||
```
|
||||
|
||||
For each identified node, call `updateNode(id, { description: "[REVIEW: action] " + originalDescription })`.
|
||||
|
||||
### 4. Stale-Node Archiving (Level 1 — standing Kwame directive, 2026-09-11)
|
||||
|
||||
**Kwame's standing directive: stale nodes CAN be archived by the fixer. No per-batch escalation, no `[REVIEW: archive]` tagging — archive them.**
|
||||
|
||||
For every node whose suggested action is `archive` (i.e. its type is NOT one of the living types in fix 3), archive it in a **single** `updateNode` call:
|
||||
|
||||
```python
|
||||
updateNode(id, {
|
||||
"description": "[ARCHIVED] " + originalDescriptionWithoutReviewTag,
|
||||
"metadata": {"state": "archived"}
|
||||
})
|
||||
```
|
||||
|
||||
- `state` transitions **DO work through `updateNode`** (`archived`, and back to `active`). The former "state only accepts processed/not_processed, use SSH" claim was wrong — verified 2026-09-11 by archiving 7 nodes (#61, #373, #388, #465, #475, #526, #1476) over the bridge with `updated_at` auto-bumping. **SSH to the bridge host is a fallback, not a requirement**, and it is blocked from kagentz anyway.
|
||||
- Pass `description` and `metadata` in the **same** call, and always keep the `updates` object nested: `{"id": N, "updates": {…}}`.
|
||||
- Archiving is non-destructive: the node stays in the graph, marked `state: archived` + `[ARCHIVED] ` prefix. **Living nodes (refresh-suggested) are NEVER archived** without a specific Kwame decision — they are the cluster/agent/business canon.
|
||||
|
||||
**Archive candidates are identified by the fix 3 query's `suggested_action = 'archive'` branch** (the `ELSE 'archive'` case: anything not an infrastructure/skill/documentation/strategic/audit type).
|
||||
|
||||
## Level 2 Escalations (Kwame Decision Required)
|
||||
|
||||
1. **Refresh-suggested stale nodes** flagged with `[REVIEW: refresh]` — refresh or keep? (Archive-suggested nodes are auto-archived under fix 4 and are not escalated.)
|
||||
2. **Duplicate Nodes** (same title or >70% title overlap) — Merge or keep?
|
||||
3. **Orphan Nodes >90 days old** — Archive or connect?
|
||||
|
||||
## Reporting Format
|
||||
|
||||
The fixer reports to Kwame via this Zulip DM:
|
||||
|
||||
```
|
||||
🦅 Memory Fixer — [HH:MM UTC]
|
||||
|
||||
Level 1 fixes applied:
|
||||
- Missing type: X nodes classified
|
||||
- Missing namespace: Y nodes populated
|
||||
|
||||
Stale nodes needing review (max 10):
|
||||
1. [Node #XXX] Title — X days stale, SUGGEST: refresh
|
||||
2. [Node #YYY] Title — Y days stale, SUGGEST: archive
|
||||
...
|
||||
|
||||
Duplicates needing decision:
|
||||
1. [Node #AAA] vs [Node #BBB] — Same title
|
||||
|
||||
Orphans >90 days:
|
||||
1. [Node #EEE] Title — X days stale, orphaned
|
||||
|
||||
Reply with:
|
||||
- "archive #XXX, #YYY" to mark for archive
|
||||
- "archive all" to archive all stale nodes listed
|
||||
- "keep #XXX" to confirm a node is current
|
||||
- "merge #AAA into #BBB" to merge duplicates
|
||||
- "refresh #XXX" to mark as current
|
||||
```
|
||||
|
||||
## Execution on Next Run
|
||||
|
||||
The fixer reads Kwame's previous response and **executes the decision to completion** — it must not leave a node in review-pending forever. Tagging alone is NOT enough; each confirmed decision must also update `state` and `updated_at` so the node drops out of the stale window on the next run.
|
||||
|
||||
> ⚠️ **Corrected 2026-09-11:** `updateNode` DOES accept `state` changes — `{"updates": {"description": …, "metadata": {"state": "archived"}}}` works over the bridge, and `updated_at` bumps automatically. The old "use direct SSH + SQLite for state transitions" instruction was based on a wrong assumption; SSH is a fallback only (and is blocked from kagentz). Use one `updateNode` call for both the tag and the state.
|
||||
> ```bash
|
||||
> ssh root@192.168.68.65 "sqlite3 /root/.local/share/RA-H/db/rah.sqlite \"UPDATE nodes SET metadata = json_set(metadata, '$.state', '<state>'), updated_at = datetime('now') WHERE id = <id>;\""
|
||||
> ```
|
||||
> Use `updateNode` only for description/source/title/link edits.
|
||||
|
||||
Decision → completed action mapping:
|
||||
|
||||
| Kwame reply | Description change | State | `updated_at` |
|
||||
|---|---|---|---|
|
||||
| `archive #XXX` | replace `[REVIEW: archive] ` → `[ARCHIVED] ` prefix | `archived` | bumped to now |
|
||||
| `keep #XXX` / `refresh #XXX` | **clear the `[REVIEW: …]` tag entirely** | `active` | bumped to now |
|
||||
| `merge #AAA into #BBB` | set `[REVIEW: merge_into #BBB]` on #AAA, then follow manual merge workflow | handled manually | bumped to now |
|
||||
| `archive all` | apply the archive row to every node listed in the prior report | `archived` | bumped to now |
|
||||
|
||||
**Why `updated_at` must be bumped (critical):** the Level-1 staleness query keys off `updated_at < now - window`. If the fixer clears the tag but leaves a stale `updated_at`, the node is immediately re-flagged on the very next run and the cycle repeats forever. Bumping `updated_at` to now pushes the node back to the front of the window.
|
||||
|
||||
**Exclusion after action:** once an action is applied, the node's description no longer starts with `[REVIEW:` (archive → `[ARCHIVED]`, refresh/keep → original text), so it is not re-processed.
|
||||
|
||||
After all actions are applied, verify with:
|
||||
```sql
|
||||
SELECT id, json_extract(metadata, '$.state') FROM nodes WHERE description LIKE '[REVIEW:%';
|
||||
```
|
||||
The result must be 0 rows when all decisions are executed. Report what was done.
|
||||
|
||||
## Checks
|
||||
|
||||
- **State integrity:** archived nodes have `state: archived` + `[ARCHIVED]` prefix; kept nodes are `state: active` without a `[REVIEW:]` tag.
|
||||
- **Auto-archive applied:** no node should ever be left tagged `[REVIEW: archive]` — that tag is retired. Any `[REVIEW: archive]` found means fix 4 was skipped; archive it and report.
|
||||
- **No review-pending forever:** after executing Kwame's decisions, `[REVIEW:%` node count must be 0.
|
||||
- **Timestamps:** every executed decision (and every auto-archive) bumps `updated_at`, so the node exits the stale window on the next run.
|
||||
|
||||
## Logging
|
||||
Every Level 1 fix logged to `~/.hermes/logs/memory-fixer/YYYY-MM-DD.md`
|
||||
Every Level 2 escalation logged and delivered to Kwame.
|
||||
@@ -6,7 +6,7 @@ description: >
|
||||
delegation, verification, and delivery. Defines when to delegate, which
|
||||
worker to use for what, how to handle failures, and the kanban board
|
||||
protocol. Enforces context-window discipline and separation of concerns.
|
||||
Runs on Mumuni (kagentz CT105, minipve, .14) via Hermes agent (Zulip gateway via systemd).
|
||||
Runs on Mumuni (CT 118, storepve, .6) via Hermes agent.
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
@@ -20,7 +20,7 @@ version: 1.0.0
|
||||
## Topology
|
||||
|
||||
**Cluster:** 5 Proxmox nodes (ocupve, acerpve, minipve, amdpve, storepve)
|
||||
**Manager:** Mumuni (kagentz CT105, minipve, .14) via Hermes agent
|
||||
**Manager:** Mumuni (CT 118, storepve, .6) via Hermes agent
|
||||
**Workers:** 6 profiles, all running on the same agent — no separate hosts needed
|
||||
|
||||
This contract is infrastructure-agnostic in terms of which nodes are used.
|
||||
@@ -66,36 +66,16 @@ Delegation is **mandatory** when any of these apply:
|
||||
`curl`, `hermes tools list` — these are decision-making tools. The manager
|
||||
reads them directly.
|
||||
|
||||
## Data Source Integrity (CRITICAL)
|
||||
|
||||
**Workers MUST use the data provided in their task context. They MUST NOT
|
||||
fetch their own data from external sources unless explicitly told to.**
|
||||
|
||||
When a task says "Read file X and format it", the worker reads file X. It does
|
||||
not query a separate API, run its own diagnostics, or pull data from a different
|
||||
system. This is the #1 source of cross-worker inconsistency: one worker gathers
|
||||
SSH data, another queries the Proxmox API, and the report merges two incompatible
|
||||
datasets.
|
||||
|
||||
**Rule:** If a worker needs additional data beyond what's in its task description,
|
||||
it asks the manager (via relay) — it doesn't go find it on its own.
|
||||
|
||||
**This is a hard rule, not a recommendation.** Violating it produces the exact
|
||||
type of discrepancy the kanban pipeline exists to prevent: a review worker finds
|
||||
"5 nodes present" in the raw data but "5/5 online" in the report — even though
|
||||
one of those nodes was unreachable. The report lied because it used data the
|
||||
raw data never provided.
|
||||
|
||||
## Worker Selection Matrix
|
||||
|
||||
| Worker | Model | Toolsets | Role | Use When |
|
||||
|--------|-------|----------|------|----------|
|
||||
| `syslog-code` | qwen3.6-27B-code | terminal, file, web, memory, skills | Code patches, automation, scripts | Writing/modifying code, creating scripts, debugging, reading/writing files |
|
||||
| `syslog-devops` | qwen3.6-27B-code | terminal, file, web, memory, skills | Infrastructure, DB, bridge, Proxmox | Server ops, SSH, Docker, Proxmox, DB queries, hardware checks |
|
||||
| `syslog-email` | strix-moe | terminal, file, web, memory, skills | Email automation, mail operations | Sending/receiving email, inbox management, SMTP operations |
|
||||
| `syslog-research` | strix-moe | terminal, file, web, memory, skills, **browser** | Analysis, classification, data processing | Web research, browser tasks, data analysis, classification, reading docs |
|
||||
| `syslog-review` | strix-moe | terminal, file, web, memory, skills | Verification, QA, audit validation | **ALWAYS** verify worker output before delivery — especially for infra changes, code builds, and research findings |
|
||||
| `syslog-writer` | strix-moe | terminal, file, web, memory, skills | Docs, content, branding, reports | Writing docs, reports, proposals, content, markdown formatting |
|
||||
| `syslog-email` | ornith-1.0-35b | terminal, file, web, memory, skills | Email automation, mail operations | Sending/receiving email, inbox management, SMTP operations |
|
||||
| `syslog-research` | ornith-1.0-35b | terminal, file, web, memory, skills, **browser** | Analysis, classification, data processing | Web research, browser tasks, data analysis, classification, reading docs |
|
||||
| `syslog-review` | ornith-1.0-35b | terminal, file, web, memory, skills | Verification, QA, audit validation | **ALWAYS** verify worker output before delivery — especially for infra changes, code builds, and research findings |
|
||||
| `syslog-writer` | ornith-1.0-35b | terminal, file, web, memory, skills | Docs, content, branding, reports | Writing docs, reports, proposals, content, markdown formatting |
|
||||
|
||||
### Selection Rules
|
||||
|
||||
@@ -120,19 +100,6 @@ dispatch sequentially.
|
||||
|
||||
Fire workers via `delegate_task`:
|
||||
|
||||
**Critical: Pass the data, not just the goal.** When dispatching a worker that
|
||||
processes output from another worker, include the file path AND explicit
|
||||
instructions to use ONLY that source. Example:
|
||||
|
||||
```
|
||||
delegate_task(
|
||||
goal="Format the cluster check into a clean report",
|
||||
context="Source data is at /tmp/proxmox-check-raw.md. Format ONLY the data
|
||||
in that file. Do NOT query the Proxmox API or any other data source. Use the
|
||||
file as your sole source of truth."
|
||||
)
|
||||
```
|
||||
|
||||
**Parallel (independent lanes):**
|
||||
```
|
||||
delegate_task(
|
||||
@@ -236,7 +203,6 @@ Only verified results reach Kwame. Format per channel:
|
||||
- ❌ Skipping verification → raw worker output never reaches the user
|
||||
- ❌ Delegating single tool calls → keep quick reads/writes at manager level
|
||||
- ❌ Firing more than 3 workers in parallel → hard limit
|
||||
- ❌ **Workers fetching their own data sources** → a writer worker that queries the Proxmox API when told to "format the raw file" is fabricating data. Use the input given, not external sources
|
||||
|
||||
## Emergency Exception
|
||||
|
||||
|
||||
@@ -54,7 +54,7 @@ garbled input. When a user types these commands to Abiba:
|
||||
|
||||
- **`/approve`** → "Pi doesn't have pending approvals. Commands execute immediately."
|
||||
- **`/approve session`** → Same response
|
||||
- **`/deny`** → Same response + "For agents (Mumuni on Hermes, Tanko on DSH), these work with their built-in approval system."
|
||||
- **`/deny`** → Same response + "For Hermes agents (Tanko, Mumuni), these work with their built-in approval system."
|
||||
|
||||
This keeps the UX consistent across agents — users can type `/approve` anywhere
|
||||
without getting confused by LLM responses.
|
||||
|
||||
+12
-13
@@ -2,17 +2,21 @@
|
||||
kind: responsibility
|
||||
name: pm2-self-heal
|
||||
description: >
|
||||
Monitors critical PM2 processes (abiba-zulip, abiba-telegram) and
|
||||
auto-restarts any that are stopped or errored. Logs every action to
|
||||
the knowledge graph and alerts the owner via Zulip DM on failures.
|
||||
CRITICAL: Never restart abiba-zulip — it runs this contract.
|
||||
---
|
||||
|
||||
## Maintains
|
||||
|
||||
- abiba-telegram: { status: "online", uptime: string, restarts: number }
|
||||
- abiba-zulip: { status: "online", uptime: string, restarts: number }
|
||||
- gpu-watchdog: { status: "online", uptime: string, restarts: number }
|
||||
- gpu-monitor: { status: "online", uptime: string, restarts: number }
|
||||
- gitea-runner: { status: "online", uptime: string, restarts: number }
|
||||
- spoton-service: { status: "online", uptime: string, restarts: number }
|
||||
- zulip-watchdog: { status: "online", uptime: string, restarts: number }
|
||||
- last_check: timestamp
|
||||
|
||||
> **Note (2026-07-04):** `abiba-zulip` removed — Zulip extension decommissioned.
|
||||
|
||||
## Continuity
|
||||
|
||||
@@ -27,15 +31,10 @@ description: >
|
||||
- **Verify**: Re-check status after 5 seconds
|
||||
- **Escalate**: If still failed after 2 retries, send Zulip DM to owner
|
||||
|
||||
### Rule 2: Process Restarting Too Often (crash-loop guard)
|
||||
- **Detect**: `pm2 status` shows restarts > 30 (cumulative lifetime counter) **or** a
|
||||
process reporting a restart count > 1000 while showing "online" (a crash-loop mask)
|
||||
### Rule 2: Process Restarting Too Often
|
||||
- **Detect**: `pm2 status` shows restarts > 30 (cumulative lifetime counter)
|
||||
- **Note**: PM2 counter never decrements; only full delete+re-add resets it
|
||||
- **Fix**: `pm2 delete <name> && pm2 start <ecosystem> --only <name>`
|
||||
- **Script guard (2026-08-16)**: `scripts/pm2-self-heal.sh` now restarts `abiba-telegram`
|
||||
when `TEL_RESTARTS > 1000` even if the process reports "online" — catches a quiet
|
||||
crash-loop that never toggles status to "stopped"/"errored" (e.g. the 10k-restarts
|
||||
spoton incident). Alerts include the restart count.
|
||||
- **Escalate**: Only when restarts > 30 — alerts to Zulip DM
|
||||
- **Historical fix**: Previous cycles were caused by abiba-zulip extension's
|
||||
stuck detection (STUCK_THRESHOLD_MS was 30min, raised to 4h in v2).
|
||||
@@ -49,11 +48,11 @@ description: >
|
||||
- If status is "online" → pass
|
||||
- If status is "stopped" or "errored" → apply Rule 1
|
||||
- If restarts > 5 → alert owner
|
||||
3. **Check abiba-zulip** (live Zulip bridge, heartbeating):
|
||||
3. **Check abiba-zulip** (self-process, read-only):
|
||||
- If status is "online" → pass, log restarts count
|
||||
- If status is "stopped" or "errored" → restart (`pm2 restart abiba-zulip` — fully restored)
|
||||
- If status is "stopped" or "errored" → **DO NOT RESTART** — alert owner immediately
|
||||
- If restarts > 5 in last hour → alert owner with full diagnostics
|
||||
4. **Log results** — Append to `SyslogSolution/health-logs/pm2/{timestamp}.md` in Gitea (not knowledge graph — hard rule)
|
||||
4. **Log results** — Create `[LEARN]` node in knowledge graph for any actions taken
|
||||
5. **Alert** — Send Zulip DM to owner if escalation needed (do NOT run pm2 commands during alerting)
|
||||
6. **Wait 5 min** → repeat from step 1
|
||||
|
||||
|
||||
@@ -41,7 +41,7 @@ agent: abiba
|
||||
|
||||
- User: `monitoring@pve` (cluster-replicated)
|
||||
- Role: `PVEAuditor` on `/` (read-only, whole cluster)
|
||||
- Token: `monitoring@pve!prometheus` — stored in Infisical vault (`PROXMOX_MONITOR_TOKEN`)
|
||||
- Token: `monitoring@pve!prometheus` = `2c74ceb6-f905-444a-94f9-1c4f7889b68c`
|
||||
- `verify_ssl: false` (proxmoxer uses `verify_ssl`, NOT `verify_tls`)
|
||||
|
||||
## Grafana Dashboards (file-provisioned, folder "Syslog Fleet")
|
||||
@@ -62,7 +62,7 @@ agent: abiba
|
||||
|
||||
- **URL**: `http://192.168.68.116:3001/` (LAN, direct — Grafana bound to `0.0.0.0:3001`)
|
||||
- **Dashboards**: `http://192.168.68.116:3001/d/gpu-fleet`, `.../d/proxmox-cluster`, `.../d/proxmox-node`, `.../d/docker-containers`
|
||||
- **Credentials**: admin / password stored in Infisical vault (`GRAFANA_ADMIN_PASSWORD`)
|
||||
- **Credentials**: admin / syslog-grafana-2026
|
||||
- Grafana is NOT behind nginx — access port 3001 directly. The `harness-nginx` `/grafana/` sub-path route was tried and reverted (broke the existing `:3001` URL and gpu-fleet path). Do not re-add `GF_SERVER_SERVE_FROM_SUB_PATH` or an nginx `/grafana/` route.
|
||||
- grafana compose port mapping: `"3001:3000"` (0.0.0.0, not 127.0.0.1)
|
||||
|
||||
@@ -87,7 +87,7 @@ agent: abiba
|
||||
| storepve | 192.168.68.6 | PVE |
|
||||
| acerpve | 192.168.68.9 | PVE (hosts llm-gpu qemu/101) |
|
||||
| minipve | 192.168.68.12 | PVE |
|
||||
| amdpve | 192.168.68.15 | PVE + Strix Halo LLM (qwen3.6-35B-udq4, strix-moe) |
|
||||
| amdpve | 192.168.68.15 | PVE + Strix Halo LLM (ornith) |
|
||||
|
||||
## Operations
|
||||
|
||||
@@ -100,35 +100,6 @@ Edit `build-dashboards.py`, run it, `docker restart harness-grafana`
|
||||
### check-targets
|
||||
`curl http://192.168.68.116:9090/api/v1/targets | jq '.data.activeTargets[] | {job:.labels.job,health}'`
|
||||
|
||||
### check-health
|
||||
|
||||
**RUN LIVE, NEVER ECHO — every dispatch must execute the probes below with real tool calls; never repeat a prior report unless a live probe fails.**
|
||||
|
||||
```bash
|
||||
# Prometheus health (bound to 0.0.0.0:9090 on .116)
|
||||
curl -s -o /dev/null -w '%{http_code}' http://192.168.68.116:9090/-/healthy
|
||||
# Expected: 200 (Prometheus is up and healthy)
|
||||
|
||||
# Grafana health (bound to 0.0.0.0:3001 on .116)
|
||||
curl -s -o /dev/null -w '%{http_code}' http://192.168.68.116:3001/api/health
|
||||
# Expected: 200 (Grafana is up and healthy)
|
||||
|
||||
# Docker Stats exporter (bound to 127.0.0.1:9324 on .116 — must probe from .116 localhost)
|
||||
ssh root@192.168.68.116 "curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:9324/metrics"
|
||||
# Expected: 200 (docker-stats-exporter is up and responding)
|
||||
|
||||
# PVE exporter (bound to 127.0.0.1:9221 on .116 — must probe from .116 localhost)
|
||||
ssh root@192.168.68.116 "curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:9221/metrics"
|
||||
# Expected: 200 (pve-exporter is up and responding)
|
||||
```
|
||||
|
||||
**Report format**: Begin every report with the **absolute path the probe executed
|
||||
from** (`pwd -P`, or the script's absolute path) so a stale-consumer report is
|
||||
distinguishable from a real fault at read time. Summarize actual results from
|
||||
each probe. If any probe returns non-200, flag as alert.
|
||||
|
||||
**Note**: Docker Stats and PVE Exporter are bound to 127.0.0.1 (localhost-only) so they must be probed from .116 via SSH. Prometheus and Grafana are bound to 0.0.0.0 so they can be probed from the LAN.
|
||||
|
||||
### restart-exporter
|
||||
`cd /opt/monitoring && docker compose restart pve-exporter docker-stats`
|
||||
|
||||
|
||||
+37
-552
@@ -1,10 +1,10 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
/root/scripts/agent-health-check.py — Consolidated Agent Health Verification v4
|
||||
/root/scripts/agent-health-check.py — Consolidated Agent Health Verification
|
||||
|
||||
Verifies: LiteLLM keys (agent-specific), GPU port conflicts, agent Zulip streaming,
|
||||
gateway liveness, gateway log health, CT liveness, config YAML integrity,
|
||||
wrapper/CLI integrity, vault secret non-emptiness. NEVER restarts anything.
|
||||
Single non-disruptive health check replacing 7 scattered scripts.
|
||||
Verifies: LiteLLM keys, GPU port conflicts, agent Zulip streaming,
|
||||
gateway liveness, and gateway log health. NEVER restarts anything.
|
||||
|
||||
Usage:
|
||||
python3 /root/scripts/agent-health-check.py # Full check
|
||||
@@ -12,129 +12,27 @@ Usage:
|
||||
python3 /root/scripts/agent-health-check.py --quiet # Only output on failure
|
||||
|
||||
Cron: */10 * * * * python3 /root/scripts/agent-health-check.py --quiet
|
||||
|
||||
Changelog:
|
||||
v2 (2026-07-26): Added CT liveness, config validation, wrapper integrity,
|
||||
vault secret emptiness check. Fixed Koby/Koonimo SSH hosts and agent key
|
||||
name format ({NAME}_LITELLM_API_KEY not LITELLM_API_KEY_{NAME}).
|
||||
Fleet roster: tanko (.122), koby (.129), koonimo (.114), abiba (.24).
|
||||
(v2 also carried a mumuni probe; see v5 — mumuni is no longer probed: she
|
||||
moved to her own container, kagentz CT 105 / .14, and is monitored there.)
|
||||
v3 (2026-09-08): GPU unit repoint verified live (.8 llama-chat-api.service,
|
||||
.110 llama-server.service, .15 strix-server.service) — .8 was probing a stale
|
||||
llama-server unit that reads inactive, producing false UNREACHABLE legs.
|
||||
systemctl is-active no longer swallows non-zero exit as SSH failure.
|
||||
Fixed UnboundLocalError on the abiba/koonimo gateway leg (pid unbound in the
|
||||
summary f-string). Abiba's LiteLLM key now comes from /root/.pi/agent/env.sh
|
||||
(#735 agent separation; creds moved out of shared /root/.bashrc).
|
||||
v4 (2026-09-10): probe-drift round 2 (prose-contracts follow-up to #65/#66/#68).
|
||||
abiba declared pi-only runtime — Hermes-era config/wrapper/gateway checks are
|
||||
skipped (harness purge). koby declared report_only per the captain's
|
||||
2026-08-17 ruling: every koby leg is detected and reported, never counted as a
|
||||
fleet failure and never repaired. koby's PVE mapping corrected to storepve
|
||||
(CT 111 tdunna lives on .6 — the old amdpve mapping produced a false
|
||||
ct-unreachable). The wrapper infisical-path check had two stale-expectation
|
||||
bugs: it read only the first 20 lines of the wrapper, so koonimo (whose
|
||||
wrapper does reference /usr/bin/infisical, just past line 20) was falsely
|
||||
FAILed as "path may be wrong"; and it treated the absence of any infisical
|
||||
reference as a fault, though koby's wrapper sources the key from
|
||||
~/.hermes/.env and never invokes infisical. The check now reads the full
|
||||
wrapper body, accepts a no-infisical wrapper, and verifies that any absolute
|
||||
infisical path the wrapper references actually exists. Report-only findings
|
||||
are surfaced in a machine-readable `report_only` array in --json output,
|
||||
separate from `failures`. Every run prints absolute execution provenance
|
||||
(script + cwd) in the header, in the cron ALERT line, and in --json output so
|
||||
a stale-consumer report is distinguishable from a fault at read time.
|
||||
v5 (2026-09-10): roster correction only, no behavior change. mumuni was removed
|
||||
from the AGENTS dict when she moved off this host onto her own container
|
||||
(kagentz CT 105 on minipve, .14, dedicated `hermes` user) and is monitored
|
||||
from her side. This script must not probe mumuni or .24 — the v2 changelog
|
||||
roster line was the last reference still placing her at .24 / CT100.
|
||||
"""
|
||||
|
||||
import subprocess, json, sys, os, time, re, io, contextlib
|
||||
import subprocess, json, sys, os, time
|
||||
from datetime import datetime
|
||||
|
||||
LITELLM = "http://192.168.68.116:80"
|
||||
INFISICAL_PROJECT = "322fceab-39da-4854-a55a-568e76c0f13f"
|
||||
INFISICAL_ENV = "prod"
|
||||
|
||||
# PVE node IPs for CT liveness checks
|
||||
PVE_NODES = {
|
||||
"amdpve": "192.168.68.15",
|
||||
"minipve": "192.168.68.12",
|
||||
"storepve": "192.168.68.6",
|
||||
"acerpve": "192.168.68.9",
|
||||
"ocupve": "192.168.68.5",
|
||||
}
|
||||
|
||||
# Agent definitions: ct, host, user, pve_node, vault_key_name
|
||||
AGENTS = {
|
||||
"tanko": {"ct": 112, "host": "192.168.68.122", "user": "jerome", "pve": "amdpve", "vault_key": "TANKO_LITELLM_API_KEY", "runtime": "dsh"},
|
||||
# abiba = pi agent (.24) — no vault key; its LiteLLM key is read from its
|
||||
# local env file (key_env below), not from the shared vault or .bashrc.
|
||||
# runtime=pi: abiba has run pi-only since the harness purge. There is no
|
||||
# Hermes gateway, no ~/.hermes/config.yaml and no hermes CLI wrapper on .24
|
||||
# (the /root/.local/bin/hermes symlink is dangling), so the Hermes-era
|
||||
# config/wrapper/gateway legs are skipped rather than reported as faults.
|
||||
"abiba": {"ct": 100, "host": "192.168.68.24", "user": "root", "pve": "minipve",
|
||||
"vault_key": None, "runtime": "pi",
|
||||
"key_env": {"file": "/root/.pi/agent/env.sh", "var": "LITELLM_API_KEY"}},
|
||||
# koby = report-only (captain's 2026-08-17 ruling, Rule 17): detect and
|
||||
# report, NEVER repair, and never count against fleet failures. CT 111
|
||||
# (tdunna) lives on storepve (.6) — verified live 2026-09-10; the previous
|
||||
# amdpve mapping made `pct status 111` fail and read as ct-unreachable.
|
||||
"koby": {"ct": 111, "host": "192.168.68.129", "user": "root", "pve": "storepve", "vault_key": "KOBY_LITELLM_API_KEY", "report_only": True},
|
||||
"koonimo": {"ct": 113, "host": "192.168.68.114", "user": "root", "pve": "amdpve", "vault_key": "KOONIMO_LITELLM_API_KEY"},
|
||||
"tanko": {"ct": 112, "host": "192.168.68.122", "key": "sk-CggiHWlamQyShxWC3Hx6uw", "user": "jerome"},
|
||||
"mumuni": {"ct": 114, "host": "192.168.68.123", "key": "sk-VrqCNlwUgzoNGOpikJ7nwQ", "user": "root"},
|
||||
"tdunna": {"ct": 111, "host": None, "key": "sk-6sbCNjz2T6lTVDBdlNHXsA", "user": None},
|
||||
"baggy": {"ct": 113, "host": None, "key": "sk-krnw_zGBwvvL5b7l2t-s-A", "user": None},
|
||||
}
|
||||
|
||||
# Systemd units verified live 2026-09-08 (systemctl list-units on each host):
|
||||
# .8 rtx3090 (gpu-dense) -> llama-chat-api.service (active; the old
|
||||
# llama-server.service unit file is stale/inactive — probing it read as
|
||||
# UNREACHABLE for a healthy process)
|
||||
# .110 rtx5070 (ocu-llm VM) -> llama-server.service (active)
|
||||
# .15 strixhalo (amdpve) -> strix-server.service (active)
|
||||
GPU_HOSTS = {
|
||||
"gpu-rtx3090 (.8)": {"host": "192.168.68.8", "port": 8080, "service": "llama-chat-api.service"},
|
||||
"gpu-rtx5070 (.110)": {"host": "192.168.68.110", "port": 8080, "service": "llama-server.service"},
|
||||
"gpu-strixhalo (.15)": {"host": "192.168.68.15", "port": 8080, "service": "strix-server.service"},
|
||||
"gpu-rtx3090 (.8)": {"host": "192.168.68.8", "port": 8080, "service": "llama-server"},
|
||||
"gpu-rtx5070 (.110)": {"host": "192.168.68.110", "port": 8080, "service": "llama-server"},
|
||||
"gpu-strixhalo (.15)": {"host": "192.168.68.15", "port": 8080, "service": "ornith-server"},
|
||||
}
|
||||
|
||||
FAIL = []
|
||||
REPORT_ONLY = []
|
||||
|
||||
|
||||
def _fail(key, agent_name=None):
|
||||
"""Record a failure, except for report-only agents.
|
||||
|
||||
Koby is report-only per the captain's 2026-08-17 ruling (Rule 17): its legs
|
||||
are detected and reported, never repaired and never counted as fleet
|
||||
failures. A red fleet alert on a known report-only leg is a false alarm.
|
||||
Report-only findings are tracked separately so --json consumers can still
|
||||
see them without them counting as fleet failures. Any non-report-only agent
|
||||
(or a leg with no agent, e.g. GPU hosts) records normally.
|
||||
"""
|
||||
if agent_name and AGENTS.get(agent_name, {}).get("report_only"):
|
||||
REPORT_ONLY.append(key)
|
||||
print(f" 🔍 report-only ({agent_name}): {key} — reported, not counted/repaired")
|
||||
return
|
||||
FAIL.append(key)
|
||||
|
||||
|
||||
INFISICAL_TOKEN = os.environ.get("INFISICAL_TOKEN")
|
||||
INFISICAL_API_URL = os.environ.get("INFISICAL_API_URL", "https://vault.sysloggh.net")
|
||||
|
||||
# Fallback: if no env token, read the shared vault token file
|
||||
if not INFISICAL_TOKEN:
|
||||
_token_path = os.path.expanduser("~/.infisical-token")
|
||||
if os.path.isfile(_token_path):
|
||||
try:
|
||||
with open(_token_path) as _f:
|
||||
INFISICAL_TOKEN = _f.read().strip()
|
||||
except (OSError, UnicodeDecodeError):
|
||||
pass
|
||||
|
||||
# ── Helpers ──────────────────────────────────────────────────────────
|
||||
|
||||
def ssh(host, cmd, user="root"):
|
||||
"""Execute a command on a remote host, return stdout or None."""
|
||||
@@ -174,126 +72,25 @@ def http_json(url, headers=None, timeout=5):
|
||||
except:
|
||||
return None
|
||||
|
||||
def run_infisical(args, quiet=True):
|
||||
"""Run infisical CLI with env-based auth, return stdout or None."""
|
||||
env = os.environ.copy()
|
||||
env["INFISICAL_API_URL"] = INFISICAL_API_URL
|
||||
if INFISICAL_TOKEN:
|
||||
env["INFISICAL_TOKEN"] = INFISICAL_TOKEN
|
||||
try:
|
||||
result = subprocess.run(
|
||||
["/usr/bin/infisical"] + args,
|
||||
capture_output=True, text=True, timeout=15, env=env
|
||||
)
|
||||
return result.stdout.strip() if result.returncode == 0 else None
|
||||
except:
|
||||
return None
|
||||
|
||||
# ── KEY LOOKUP FIX ───────────────────────────────────────────────────
|
||||
|
||||
def _get_agent_key(agent_name, vault_key_name):
|
||||
"""Retrieve agent-specific key from Infisical vault.
|
||||
|
||||
Uses {NAME}_LITELLM_API_KEY format (e.g., TANKO_LITELLM_API_KEY,
|
||||
KOONIMO_LITELLM_API_KEY) which matches actual vault key names.
|
||||
"""
|
||||
if not vault_key_name:
|
||||
return None
|
||||
|
||||
# Primary: get the agent-specific key by name
|
||||
key = run_infisical([
|
||||
"secrets", "get", vault_key_name,
|
||||
"--projectId=" + INFISICAL_PROJECT,
|
||||
"--env=" + INFISICAL_ENV,
|
||||
"--plain",
|
||||
])
|
||||
if key and key.startswith("sk-"):
|
||||
return key
|
||||
|
||||
# Fallback: export all and search for the key name
|
||||
try:
|
||||
export = run_infisical([
|
||||
"export",
|
||||
"--projectId=" + INFISICAL_PROJECT,
|
||||
"--env=" + INFISICAL_ENV,
|
||||
"--format=dotenv",
|
||||
])
|
||||
if export:
|
||||
for line in export.splitlines():
|
||||
if line.startswith(vault_key_name + "="):
|
||||
value = line.split("=", 1)[1].strip().strip('"').strip("'")
|
||||
if value.startswith("sk-"):
|
||||
return value
|
||||
except:
|
||||
pass
|
||||
|
||||
return None
|
||||
|
||||
|
||||
def _read_env_export(path, var):
|
||||
"""Parse `export VAR=value` (or `VAR=value`) out of a local env file.
|
||||
|
||||
#735 agent separation (2026-09-06): agent creds moved out of the shared
|
||||
/root/.bashrc into per-agent env files under /root/.pi/agent/ (bashrc's
|
||||
source line keeps abiba shells resolving them, but the file of record is
|
||||
env.sh). Do NOT fall back to /root/.bashrc here: desktop (.200) SSH
|
||||
sessions override LITELLM_API_KEY with mumuni's key, so sourcing bashrc
|
||||
would validate the wrong identity.
|
||||
"""
|
||||
try:
|
||||
with open(os.path.expanduser(path)) as _f:
|
||||
for line in _f:
|
||||
line = line.strip()
|
||||
if not (line.startswith("export " + var + "=") or line.startswith(var + "=")):
|
||||
continue
|
||||
value = line.split("=", 1)[1].strip().strip('"').strip("'")
|
||||
if value:
|
||||
return value
|
||||
except (OSError, UnicodeDecodeError):
|
||||
pass
|
||||
return None
|
||||
|
||||
|
||||
def load_agent_keys():
|
||||
"""Populate AGENTS[*]["key"] from the vault or the agent's local env file.
|
||||
|
||||
Called from main(), not at import: keeping this out of module scope lets the
|
||||
module be imported (and unit tested) without live vault/SSH access. Vault
|
||||
format is {NAME}_LITELLM_API_KEY (project 322fceab-39da-4854-a55a-568e76c0f13f,
|
||||
env prod); abiba has no vault key and reads LITELLM_API_KEY from its local
|
||||
/root/.pi/agent/env.sh (moved there from /root/.bashrc in #735).
|
||||
"""
|
||||
for agent_name in AGENTS:
|
||||
info = AGENTS[agent_name]
|
||||
key = _get_agent_key(agent_name, info.get("vault_key"))
|
||||
if not key and info.get("key_env"):
|
||||
key = _read_env_export(info["key_env"]["file"], info["key_env"]["var"])
|
||||
AGENTS[agent_name]["key"] = key
|
||||
|
||||
|
||||
# ═══════════════════════════════════════════════════════════════════
|
||||
# CHECK 1: LiteLLM Key Validation (agent-specific keys)
|
||||
# CHECK 1: LiteLLM Key Validation
|
||||
# ═══════════════════════════════════════════════════════════════════
|
||||
|
||||
def check_keys():
|
||||
for name, agent in AGENTS.items():
|
||||
key = agent.get("key")
|
||||
if not key:
|
||||
print(f" ❌ {name}: NO KEY FOUND (vault/env empty or unreachable)")
|
||||
_fail(f"key:{name}:no-key", name)
|
||||
continue
|
||||
data = http_json(f"{LITELLM}/v1/models",
|
||||
headers={"Authorization": f"Bearer {key}"})
|
||||
headers={"Authorization": f"Bearer {agent['key']}"})
|
||||
if data and data.get("data"):
|
||||
model = data["data"][0].get("id", "?")
|
||||
print(f" ✅ {name}: key valid → {model}")
|
||||
else:
|
||||
print(f" ❌ {name}: KEY FAILURE — auth rejected or unreachable")
|
||||
_fail(f"key:{name}", name)
|
||||
FAIL.append(f"key:{name}")
|
||||
|
||||
|
||||
# ═══════════════════════════════════════════════════════════════════
|
||||
# CHECK 2: GPU Port Conflict Detection (unit names verified live 2026-09-08)
|
||||
# CHECK 2: GPU Port Conflict Detection
|
||||
# ═══════════════════════════════════════════════════════════════════
|
||||
|
||||
def check_gpu_ports():
|
||||
@@ -302,11 +99,7 @@ def check_gpu_ports():
|
||||
port = gpu["port"]
|
||||
svc = gpu["service"]
|
||||
|
||||
# `systemctl is-active` exits non-zero when the unit is inactive or
|
||||
# missing, which the ssh() helper would swallow as an SSH failure and
|
||||
# report as UNREACHABLE. `|| true` keeps the real state word so we can
|
||||
# tell "unit inactive" from "host unreachable".
|
||||
svc_status = ssh(host, f"systemctl is-active {svc} || true")
|
||||
svc_status = ssh(host, f"systemctl is-active {svc}")
|
||||
port_owner = ssh(host, f"ss -tlnp 2>/dev/null | grep -Po ':{port}\\s+.*pid=\\K[0-9]+' | head -1")
|
||||
|
||||
if not svc_status:
|
||||
@@ -325,6 +118,7 @@ def check_gpu_ports():
|
||||
else:
|
||||
print(f" ⚠️ {label}: svc={svc_status}, port owned by {port_owner}")
|
||||
else:
|
||||
# Verify health endpoint
|
||||
health = ssh(host, f"curl -s --max-time 5 http://localhost:{port}/health")
|
||||
if health and '"status":"ok"' in health:
|
||||
print(f" ✅ {label}: healthy (pid={port_owner})")
|
||||
@@ -337,7 +131,7 @@ def check_gpu_ports():
|
||||
|
||||
|
||||
# ═══════════════════════════════════════════════════════════════════
|
||||
# CHECK 3: Agent Gateway Liveness + Streaming (now covers all agents)
|
||||
# CHECK 3: Agent Gateway Liveness + Streaming
|
||||
# ═══════════════════════════════════════════════════════════════════
|
||||
|
||||
def check_agents():
|
||||
@@ -345,49 +139,17 @@ def check_agents():
|
||||
host = agent.get("host")
|
||||
user = agent.get("user")
|
||||
ct = agent["ct"]
|
||||
report_only = agent.get("report_only", False)
|
||||
|
||||
# Tanko runs on DSH (DeepSeek Harness) since 2026-08-27 — it no longer runs a
|
||||
# Hermes gateway, so skip the Hermes gateway/state/streaming/journal checks.
|
||||
# Non-Hermes runtimes have no gateway to probe. dsh = Tanko since
|
||||
# 2026-08-27; pi = abiba since the harness purge (.24 is pi-only).
|
||||
if agent.get("runtime") in ("dsh", "pi"):
|
||||
is_dsh = agent.get("runtime") == "dsh"
|
||||
label = "DSH (DeepSeek Harness)" if is_dsh else "pi-only runtime"
|
||||
since = "since 2026-08-27" if is_dsh else "since the harness purge"
|
||||
live = ssh(host, "true", user=user)
|
||||
print(f" {'✅' if live is not None else '❌'} {name}: {label} — "
|
||||
f"no Hermes gateway {since} (CT {ct}, SSH {'OK' if live is not None else 'FAIL'})")
|
||||
if live is None:
|
||||
_fail(f"unreachable:{name}", name)
|
||||
continue
|
||||
|
||||
if not host or not user:
|
||||
print(f" ⬜ {name} (CT {ct}): cannot SSH — skip liveness check")
|
||||
continue
|
||||
|
||||
# Resolve the Hermes gateway PID once, before the report-only branch:
|
||||
# the summary line below renders `pid`, and it used to be bound only in
|
||||
# the report-only path — leaving it unbound on the abiba/koonimo path
|
||||
# raised UnboundLocalError and crashed the whole check. Agents without
|
||||
# a gateway get pid=?.
|
||||
pid = ssh(host, "pgrep -f '[h]ermes_cli.main gateway run' | grep -v infisical | head -1", user=user)
|
||||
# Gateway process
|
||||
pid = ssh(host, "pgrep -f 'hermes_cli.main gateway run' | head -1", user=user)
|
||||
if not pid:
|
||||
pid = ssh(host, "pgrep -f '[h]ermes.*gateway' | grep -v infisical | grep -v bash | head -1", user=user)
|
||||
if not pid:
|
||||
pid = "?"
|
||||
|
||||
# ⛔ KOBY IS NEVER REPAIRED — diagnostic only
|
||||
if report_only:
|
||||
print(f" 🔍 {name}: REPORT-ONLY mode (diagnostic only, no repairs on .129)")
|
||||
# Still check gateway status for reporting purposes
|
||||
if pid == "?":
|
||||
print(f" ⚠️ {name}: GATEWAY NOT RUNNING (reported only)")
|
||||
_fail(f"gateway-down:{name}", name)
|
||||
continue
|
||||
else:
|
||||
print(f" ✅ {name}: gateway running (pid={pid}, report-only mode)")
|
||||
continue # Skip the rest of the check for Koby
|
||||
print(f" ❌ {name}: GATEWAY NOT RUNNING")
|
||||
FAIL.append(f"gateway-down:{name}")
|
||||
continue
|
||||
|
||||
# Gateway state file
|
||||
state = ssh(host, "cat ~/.hermes/gateway_state.json 2>/dev/null", user=user)
|
||||
@@ -401,7 +163,7 @@ def check_agents():
|
||||
else:
|
||||
gw_state, zulip = "no-state-file", "?"
|
||||
|
||||
# Zulip streaming check
|
||||
# Zulip streaming: does adapter have edit_message?
|
||||
adapter_paths = [
|
||||
"~/.hermes/plugins/zulip-platform/adapter.py",
|
||||
"~/.hermes/plugins/platforms/zulip/adapter.py",
|
||||
@@ -418,254 +180,25 @@ def check_agents():
|
||||
r"journalctl --user -u hermes-gateway --since '10 min ago' -o cat --no-pager 2>/dev/null "
|
||||
r"| grep -ci 'error\|traceback\|exception\|401\|403\|500' || echo 0",
|
||||
user=user)
|
||||
recent_errors = (recent_errors or "0").strip().split("\n")[-1]
|
||||
recent_errors = (recent_errors or "0").strip().split("\n")[-1] # take last line
|
||||
|
||||
print(f" {'✅' if gw_state == 'running' and zulip == 'connected' else '⚠️'} "
|
||||
f"{name}: gw={gw_state} zulip={zulip} streaming={streaming} "
|
||||
f"errors_10m={recent_errors.strip() or '0'} pid={pid}")
|
||||
|
||||
|
||||
# ═══════════════════════════════════════════════════════════════════
|
||||
# CHECK 4: CT Liveness (NEW)
|
||||
# ═══════════════════════════════════════════════════════════════════
|
||||
|
||||
def check_ct_liveness():
|
||||
"""Check that all agent CTs are running on their PVE nodes."""
|
||||
for name, agent in AGENTS.items():
|
||||
ct = agent["ct"]
|
||||
pve_node = agent.get("pve")
|
||||
if not pve_node:
|
||||
print(f" ⬜ {name} (CT {ct}): no PVE node mapped — skip")
|
||||
continue
|
||||
|
||||
pve_ip = PVE_NODES.get(pve_node)
|
||||
if not pve_ip:
|
||||
print(f" ⬜ {name}: unknown PVE node '{pve_node}' — skip")
|
||||
continue
|
||||
|
||||
status = ssh(pve_ip, f"pct status {ct} 2>/dev/null", user="root")
|
||||
if not status:
|
||||
print(f" ❌ {name} (CT {ct} on {pve_node}): PVE UNREACHABLE")
|
||||
_fail(f"ct-unreachable:{name}:{pve_ip}", name)
|
||||
elif "running" in status:
|
||||
print(f" ✅ {name} (CT {ct} on {pve_node}): running")
|
||||
elif "stopped" in status:
|
||||
print(f" ❌ {name} (CT {ct} on {pve_node}): STOPPED")
|
||||
_fail(f"ct-stopped:{name}", name)
|
||||
else:
|
||||
print(f" ⚠️ {name} (CT {ct} on {pve_node}): {status.strip()}")
|
||||
|
||||
|
||||
# ═══════════════════════════════════════════════════════════════════
|
||||
# CHECK 5: Config YAML Integrity (NEW)
|
||||
# ═══════════════════════════════════════════════════════════════════
|
||||
|
||||
def check_config_integrity():
|
||||
"""Verify agent config.yaml parses as valid YAML."""
|
||||
for name, agent in AGENTS.items():
|
||||
# Tanko runs on DSH (DeepSeek Harness) since 2026-08-27 — no Hermes config.yaml.
|
||||
if agent.get("runtime") == "dsh":
|
||||
print(f" ⏭️ {name}: DSH — no Hermes config.yaml since 2026-08-27")
|
||||
continue
|
||||
if agent.get("runtime") == "pi":
|
||||
print(f" ⏭️ {name}: pi-only runtime — no Hermes config.yaml since the harness purge")
|
||||
continue
|
||||
host = agent.get("host")
|
||||
user = agent.get("user")
|
||||
if not host or not user:
|
||||
print(f" ⬜ {name}: cannot SSH — skip config check")
|
||||
continue
|
||||
|
||||
# Check YAML parses
|
||||
yaml_ok = ssh(host,
|
||||
"python3 -c "
|
||||
'"import yaml; yaml.safe_load(open(\'/root/.hermes/config.yaml\')); print(\'OK\')" '
|
||||
"2>&1 || echo 'FAIL'",
|
||||
user=user)
|
||||
if not yaml_ok:
|
||||
print(f" ❌ {name}: SSH UNREACHABLE (config check skipped)")
|
||||
_fail(f"config-unreachable:{name}", name)
|
||||
elif "OK" in yaml_ok:
|
||||
print(f" ✅ {name}: config.yaml valid YAML")
|
||||
else:
|
||||
print(f" ❌ {name}: config.yaml YAML ERROR — {yaml_ok[:120]}")
|
||||
_fail(f"config-yaml-error:{name}", name)
|
||||
|
||||
|
||||
# ═══════════════════════════════════════════════════════════════════
|
||||
# CHECK 6: Wrapper/CLI Integrity (NEW)
|
||||
# ═══════════════════════════════════════════════════════════════════
|
||||
|
||||
def _infisical_invocation_paths(wrapper_body):
|
||||
"""Absolute infisical paths the wrapper actually invokes.
|
||||
|
||||
Only executed (non-comment) lines count, and only a path followed by a real
|
||||
infisical subcommand (e.g. `/usr/bin/infisical run`) is treated as an
|
||||
invocation. A note such as `# migrated from /usr/local/bin/infisical` is
|
||||
prose, not a call, so it must not manufacture a dangling-path false alarm.
|
||||
"""
|
||||
paths = []
|
||||
for line in wrapper_body.splitlines():
|
||||
code = line.split("#", 1)[0]
|
||||
for _m in re.finditer(
|
||||
r"(/[A-Za-z0-9._/-]*infisical)\s+(?:run|export|secrets|login|logout)\b",
|
||||
code,
|
||||
):
|
||||
if _m.group(1) not in paths:
|
||||
paths.append(_m.group(1))
|
||||
return paths
|
||||
|
||||
|
||||
def check_wrapper_integrity():
|
||||
"""Verify the hermes CLI wrapper exists and can reach hermes-real."""
|
||||
for name, agent in AGENTS.items():
|
||||
# Tanko runs on DSH (DeepSeek Harness) since 2026-08-27 — no hermes CLI wrapper.
|
||||
if agent.get("runtime") == "dsh":
|
||||
print(f" ⏭️ {name}: DSH — no hermes CLI wrapper since 2026-08-27")
|
||||
continue
|
||||
if agent.get("runtime") == "pi":
|
||||
print(f" ⏭️ {name}: pi-only runtime — no hermes CLI wrapper since the harness purge")
|
||||
continue
|
||||
host = agent.get("host")
|
||||
user = agent.get("user")
|
||||
if not host or not user:
|
||||
print(f" ⬜ {name}: cannot SSH — skip wrapper check")
|
||||
continue
|
||||
|
||||
# Check wrapper exists
|
||||
wrapper = ssh(host, "ls -la /root/.local/bin/hermes 2>/dev/null", user=user)
|
||||
if not wrapper:
|
||||
# Check alternate wrapper locations
|
||||
wrapper = ssh(host, "which hermes 2>/dev/null; command -v hermes 2>/dev/null", user=user)
|
||||
if not wrapper:
|
||||
print(f" ❌ {name}: NO HERMES CLI WRAPPER FOUND")
|
||||
_fail(f"wrapper-missing:{name}", name)
|
||||
continue
|
||||
else:
|
||||
print(f" ⚠️ {name}: hermes at {wrapper.strip()} (not ~/.local/bin/hermes)")
|
||||
|
||||
# Credential-injection mechanism. The Hermes-era wrapper injected creds
|
||||
# with `/usr/bin/infisical run`, but the mechanism is not required to be
|
||||
# infisical at all: koby's wrapper sources the key from ~/.hermes/.env
|
||||
# and never mentions infisical, which is valid. The old check read only
|
||||
# the first 20 lines, so koonimo's wrapper — which DOES reference
|
||||
# /usr/bin/infisical, just past line 20 — false-failed as "path may be
|
||||
# wrong". Read the full body, accept a no-infisical wrapper, and verify
|
||||
# the absolute infisical path(s) the wrapper actually invokes. Only
|
||||
# executed (non-comment) lines count: a comment or dead prose mentioning
|
||||
# a removed path (litellm-api-keys.prose.md documents
|
||||
# `rm -f /usr/local/bin/infisical`) must neither produce a dangling path
|
||||
# nor trigger the PATH check — it is not an invocation.
|
||||
wrapper_body = ssh(host, "cat /root/.local/bin/hermes 2>/dev/null", user=user) or ""
|
||||
wrapper_code = "\n".join(line.split("#", 1)[0] for line in wrapper_body.splitlines())
|
||||
invoked_paths = _infisical_invocation_paths(wrapper_body)
|
||||
if "infisical" in wrapper_code:
|
||||
if invoked_paths:
|
||||
missing = []
|
||||
for _p in invoked_paths:
|
||||
_exists = ssh(host, f"test -x {_p} && echo OK || echo MISS", user=user)
|
||||
if not _exists or _exists.strip().splitlines()[-1] != "OK":
|
||||
missing.append(_p)
|
||||
if len(missing) == len(invoked_paths):
|
||||
inf_actual = ssh(host, "command -v infisical 2>/dev/null", user=user)
|
||||
suffix = f" (infisical at {inf_actual})" if inf_actual else ""
|
||||
print(f" ❌ {name}: wrapper invokes infisical via missing path(s) "
|
||||
f"{', '.join(missing)}{suffix}")
|
||||
_fail(f"wrapper-infisical-path:{name}", name)
|
||||
elif missing:
|
||||
print(f" ⚠️ {name}: wrapper has an unused/missing infisical path "
|
||||
f"({', '.join(missing)}) but a working invocation — informational")
|
||||
elif "/usr/bin/infisical" not in invoked_paths:
|
||||
print(f" ⚠️ {name}: wrapper infisical path differs "
|
||||
f"({', '.join(invoked_paths)}) — informational")
|
||||
else:
|
||||
print(f" ✅ {name}: wrapper infisical path OK")
|
||||
else:
|
||||
inf_actual = ssh(host, "command -v infisical 2>/dev/null", user=user)
|
||||
if not inf_actual:
|
||||
print(f" ❌ {name}: wrapper invokes infisical but the binary is MISSING")
|
||||
_fail(f"wrapper-no-infisical:{name}", name)
|
||||
else:
|
||||
print(f" ✅ {name}: wrapper infisical resolves via PATH ({inf_actual})")
|
||||
else:
|
||||
print(f" ℹ️ {name}: wrapper resolves creds without infisical (e.g. ~/.hermes/.env) — OK")
|
||||
|
||||
# Check hermes-real exists
|
||||
hermes_real = ssh(host,
|
||||
"ls -la /root/.local/bin/hermes-real 2>/dev/null || echo MISS",
|
||||
user=user)
|
||||
if not hermes_real or hermes_real.strip() == "MISS":
|
||||
# Check venv path
|
||||
hermes_real = ssh(host,
|
||||
"ls -la /usr/local/lib/hermes-agent/venv/bin/hermes 2>/dev/null || echo MISS",
|
||||
user=user)
|
||||
if not hermes_real or hermes_real.strip() == "MISS":
|
||||
print(f" ❌ {name}: hermes-real NOT FOUND (wrapper broken)")
|
||||
_fail(f"wrapper-no-hermes-real:{name}", name)
|
||||
else:
|
||||
print(f" ✅ {name}: hermes-real at alt path")
|
||||
|
||||
# Check the .env file has the key
|
||||
env_has_key = ssh(host,
|
||||
"grep -c 'LITELLM_API_KEY' /root/.hermes/.env 2>/dev/null || echo 0",
|
||||
user=user)
|
||||
if env_has_key and env_has_key.strip() not in ("", "0"):
|
||||
print(f" ✅ {name}: wrapper + .env key present")
|
||||
else:
|
||||
print(f" ⚠️ {name}: .env may be missing LITELLM_API_KEY entry")
|
||||
|
||||
|
||||
# ═══════════════════════════════════════════════════════════════════
|
||||
# CHECK 7: Vault Secret Non-Emptiness (NEW)
|
||||
# ═══════════════════════════════════════════════════════════════════
|
||||
|
||||
def check_vault_secrets():
|
||||
"""Verify agent-specific vault secrets are non-empty and start with sk-."""
|
||||
for name, agent in AGENTS.items():
|
||||
vault_key_name = agent.get("vault_key")
|
||||
if not vault_key_name:
|
||||
continue
|
||||
|
||||
key = agent.get("key")
|
||||
if not key:
|
||||
print(f" ❌ {name}: vault secret {vault_key_name} MISSING or EMPTY")
|
||||
_fail(f"vault-empty:{name}:{vault_key_name}", name)
|
||||
elif not key.startswith("sk-"):
|
||||
print(f" ❌ {name}: vault secret {vault_key_name} WRONG FORMAT (starts '{key[:8]}...')")
|
||||
_fail(f"vault-bad-format:{name}:{vault_key_name}", name)
|
||||
else:
|
||||
print(f" ✅ {name}: vault {vault_key_name}=sk-...{key[-4:]}")
|
||||
|
||||
|
||||
# ═══════════════════════════════════════════════════════════════════
|
||||
# DEPLOY: copy updated script to /root/scripts/ on local host
|
||||
# ═══════════════════════════════════════════════════════════════════
|
||||
|
||||
def deploy_self():
|
||||
"""Copy this script to /root/scripts/agent-health-check.py if out of date."""
|
||||
dest = "/root/scripts/agent-health-check.py"
|
||||
try:
|
||||
with open(__file__, "r") as f:
|
||||
current = f.read()
|
||||
if os.path.isfile(dest):
|
||||
with open(dest, "r") as f:
|
||||
existing = f.read()
|
||||
if current == existing:
|
||||
return # Already deployed
|
||||
# Write new version
|
||||
with open(dest, "w") as f:
|
||||
f.write(current)
|
||||
os.chmod(dest, 0o755)
|
||||
print(f" 📦 Deployed updated script to {dest}")
|
||||
except:
|
||||
pass # Not fatal if deploy fails
|
||||
|
||||
|
||||
# ═══════════════════════════════════════════════════════════════════
|
||||
# MAIN
|
||||
# ═══════════════════════════════════════════════════════════════════
|
||||
|
||||
def _run_checks():
|
||||
def main():
|
||||
quiet = "--quiet" in sys.argv
|
||||
as_json = "--json" in sys.argv
|
||||
|
||||
if not quiet:
|
||||
print(f"🏥 Agent Health Check — {datetime.now().strftime('%Y-%m-%d %H:%M UTC')}")
|
||||
print()
|
||||
|
||||
print("🔑 LiteLLM Keys:")
|
||||
check_keys()
|
||||
print()
|
||||
@@ -676,66 +209,18 @@ def _run_checks():
|
||||
|
||||
print("🤖 Agent Gateways:")
|
||||
check_agents()
|
||||
print()
|
||||
|
||||
print("🖥️ CT Liveness:")
|
||||
check_ct_liveness()
|
||||
print()
|
||||
|
||||
print("📝 Config Integrity:")
|
||||
check_config_integrity()
|
||||
print()
|
||||
|
||||
print("🔌 Wrapper/CLI Integrity:")
|
||||
check_wrapper_integrity()
|
||||
print()
|
||||
|
||||
print("🔐 Vault Secrets:")
|
||||
check_vault_secrets()
|
||||
|
||||
|
||||
def main():
|
||||
quiet = "--quiet" in sys.argv
|
||||
as_json = "--json" in sys.argv
|
||||
|
||||
# Self-deploy to canonical location
|
||||
if not quiet and "--no-deploy" not in sys.argv:
|
||||
deploy_self()
|
||||
|
||||
# Provenance: a report is only actionable if the reader can tell WHICH copy
|
||||
# of this script produced it. A normal run carries it in the header, --json
|
||||
# carries it for machine consumers, and the cron ALERT line carries it on
|
||||
# failure. --quiet is documented as "only output on failure", so the header
|
||||
# is emitted only when not quiet and a healthy quiet run stays silent.
|
||||
script_path = os.path.abspath(__file__)
|
||||
cwd = os.getcwd()
|
||||
|
||||
if quiet:
|
||||
captured = io.StringIO()
|
||||
with contextlib.redirect_stdout(captured):
|
||||
load_agent_keys()
|
||||
_run_checks()
|
||||
if FAIL:
|
||||
sys.stdout.write(captured.getvalue())
|
||||
else:
|
||||
print(f"🏥 Agent Health Check v4 — {datetime.now().strftime('%Y-%m-%d %H:%M UTC')}")
|
||||
print(f"📍 executed from: script={script_path} cwd={cwd}")
|
||||
print()
|
||||
load_agent_keys()
|
||||
_run_checks()
|
||||
|
||||
if FAIL:
|
||||
print(f"\n❌ {len(FAIL)} FAILURE(S): {' | '.join(FAIL)}")
|
||||
if quiet:
|
||||
print(f"ALERT agent-health:{','.join(FAIL)} script={script_path} cwd={cwd}")
|
||||
# In quiet mode, only print failures as a single alert line
|
||||
print(f"ALERT agent-health:{','.join(FAIL)}")
|
||||
elif not quiet:
|
||||
print("\n✅ All checks passed")
|
||||
|
||||
if as_json:
|
||||
print(json.dumps({"timestamp": datetime.now().isoformat(),
|
||||
"execution_path": script_path, "cwd": cwd,
|
||||
"failures": FAIL, "report_only": REPORT_ONLY,
|
||||
"healthy": len(FAIL) == 0}))
|
||||
"failures": FAIL, "healthy": len(FAIL) == 0}))
|
||||
|
||||
sys.exit(1 if FAIL else 0)
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ import smtplib, json, subprocess, os, sys, datetime, re
|
||||
from email.mime.text import MIMEText
|
||||
from email.mime.multipart import MIMEMultipart
|
||||
|
||||
PVE = "https://192.168.68.12:8006"
|
||||
PVE = "https://minipve.sysloggh.net"
|
||||
AUTH = "Authorization: PVEAPIToken=monitoring@pve!mumuni=eafd56c5-93d4-4d40-a41d-e688be0987f3"
|
||||
|
||||
# ── Shared credentials —─
|
||||
@@ -38,16 +38,10 @@ TIME_STR = NOW.strftime("%Y-%m-%d %H:%M UTC")
|
||||
# ── Helpers ──
|
||||
|
||||
def pve_get(path):
|
||||
"""Fetch PVE API data. Returns list on success, None on error (to distinguish from empty list)."""
|
||||
cmd = f'curl -sk --connect-timeout 10 "{PVE}{path}" -H "{AUTH}"'
|
||||
cmd = f'curl -sfk --connect-timeout 10 "{PVE}{path}" -H "{AUTH}"'
|
||||
try:
|
||||
r = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=12)
|
||||
if r.returncode != 0:
|
||||
return None
|
||||
data = json.loads(r.stdout)
|
||||
return data.get("data", [])
|
||||
except:
|
||||
return None
|
||||
return json.loads(subprocess.check_output(cmd, shell=True))["data"]
|
||||
except: return []
|
||||
|
||||
def ssh(host, cmd):
|
||||
try:
|
||||
@@ -103,33 +97,21 @@ def collect():
|
||||
|
||||
# ── Proxmox Nodes ──
|
||||
nodes = pve_get("/api2/json/nodes")
|
||||
if nodes is None:
|
||||
report["nodes"] = {}
|
||||
report["node_count"] = 0
|
||||
report["nodes_online"] = 0
|
||||
report["pve_probe_status"] = "unreachable"
|
||||
else:
|
||||
report["nodes"] = {n["node"]: {
|
||||
"cpu_pct": round(n.get('cpu',0)*100, 1),
|
||||
"ram": f"{n.get('mem',0)//1024//1024}/{n.get('maxmem',0)//1024//1024}MB",
|
||||
"ram_pct": round(n.get('mem',0)/n.get('maxmem',1)*100, 0),
|
||||
"disk": f"{n.get('disk',0)//1024//1024//1024}/{n.get('maxdisk',0)//1024//1024//1024}GB",
|
||||
"disk_pct": round(n.get('disk',0)/n.get('maxdisk',1)*100, 0),
|
||||
"uptime_h": n.get('uptime',0)//3600,
|
||||
"status": n["status"]
|
||||
} for n in nodes}
|
||||
report["node_count"] = len(nodes)
|
||||
report["nodes_online"] = sum(1 for n in nodes if n["status"] == "online")
|
||||
report["pve_probe_status"] = "ok"
|
||||
report["nodes"] = {n["node"]: {
|
||||
"cpu_pct": round(n.get('cpu',0)*100, 1),
|
||||
"ram": f"{n.get('mem',0)//1024//1024}/{n.get('maxmem',0)//1024//1024}MB",
|
||||
"ram_pct": round(n.get('mem',0)/n.get('maxmem',1)*100, 0),
|
||||
"disk": f"{n.get('disk',0)//1024//1024//1024}/{n.get('maxdisk',0)//1024//1024//1024}GB",
|
||||
"disk_pct": round(n.get('disk',0)/n.get('maxdisk',1)*100, 0),
|
||||
"uptime_h": n.get('uptime',0)//3600,
|
||||
"status": n["status"]
|
||||
} for n in nodes}
|
||||
report["node_count"] = len(nodes)
|
||||
report["nodes_online"] = sum(1 for n in nodes if n["status"] == "online")
|
||||
|
||||
# ── VMs/CTs ──
|
||||
resources = pve_get("/api2/json/cluster/resources")
|
||||
if resources is None:
|
||||
vms = []
|
||||
report["resources_probe_status"] = "unreachable"
|
||||
else:
|
||||
vms = [r for r in resources if r.get("type") in ("qemu","lxc")]
|
||||
report["resources_probe_status"] = "ok"
|
||||
vms = [r for r in resources if r.get("type") in ("qemu","lxc")]
|
||||
report["total_vms"] = len(vms)
|
||||
report["running_vms"] = sum(1 for v in vms if v.get("status") == "running")
|
||||
stopped = [v for v in vms if v.get("status") != "running"]
|
||||
@@ -201,7 +183,7 @@ def collect():
|
||||
("Authentik", "https://auth.sysloggh.net"),
|
||||
("Zulip", "https://chat.sysloggh.net"),
|
||||
("Pulse", "https://pulse.sysloggh.net"),
|
||||
("Proxmox", "https://192.168.68.12:8006"),
|
||||
("Proxmox", "https://minipve.sysloggh.net"),
|
||||
("SearXNG", "http://192.168.68.7:8888"),
|
||||
("Firecrawl", "http://192.168.68.7:3002/health"),
|
||||
]
|
||||
@@ -213,11 +195,10 @@ def collect():
|
||||
# ── LiteLLM Specific Checks (from litellm-health prose contract) ──
|
||||
report["litellm"] = {"checks": []}
|
||||
|
||||
# Check 1: Fleet health via nginx /health/unified (301 -> /gpu/gpu-data served by gpu-monitor on .24:9100).
|
||||
# Router (:9000) was decommissioned 2026-09-11; probing it was a guaranteed daily failure.
|
||||
health_unified = ssh(LITELLM_BACKEND, "curl -s -o /dev/null -w '%{http_code}' --max-time 8 http://127.0.0.1/health/unified 2>/dev/null")
|
||||
# Check 1: LiteLLM aggregate health endpoint (router binds to 127.0.0.1, check via SSH)
|
||||
health_unified = ssh(LITELLM_BACKEND, "curl -sf http://127.0.0.1:9000/health/unified -o /dev/null -w '%{http_code}' 2>/dev/null")
|
||||
report["litellm"]["health_unified"] = health_unified or "000"
|
||||
report["litellm"]["checks"].append({"name": "fleet-health-via-nginx", "status": "pass" if health_unified in ("200", "301") else "fail", "code": health_unified or "000"})
|
||||
report["litellm"]["checks"].append({"name": "unified-health", "status": "pass" if health_unified == "200" else "fail", "code": health_unified or "000"})
|
||||
|
||||
# Check 2: Nginx-proxied internal endpoints
|
||||
for path, name in [("/litellm/ui/", "nginx-ui"), ("/litellm/docs", "nginx-docs")]:
|
||||
@@ -225,11 +206,8 @@ def collect():
|
||||
report["litellm"]["checks"].append({"name": name, "status": "pass" if code == "200" else "fail", "code": code})
|
||||
|
||||
# Check 3: Docker container health for LiteLLM stack
|
||||
expected_containers = ["harness-litellm", "harness-nginx", "harness-postgres",
|
||||
"harness-redis", "harness-dashboard", "harness-grafana",
|
||||
"harness-prometheus", "harness-alertmanager",
|
||||
"harness-zulip-bridge", "harness-docker-stats",
|
||||
"harness-pve-exporter"]
|
||||
expected_containers = ["harness-litellm", "harness-nginx", "harness-router",
|
||||
"harness-postgres", "harness-redis", "harness-dashboard"]
|
||||
actual_names = [c["name"] for c in containers2]
|
||||
report["litellm"]["expected_containers"] = expected_containers
|
||||
report["litellm"]["missing_containers"] = [e for e in expected_containers if e not in actual_names]
|
||||
@@ -269,13 +247,11 @@ def collect():
|
||||
zulip_health = json.loads(health_body) if health_body else {}
|
||||
except:
|
||||
zulip_health = {}
|
||||
# Live state is nested under 'zulip' key
|
||||
zulip_state = zulip_health.get("zulip", {})
|
||||
report["zulip_ext"]["connected"] = zulip_state.get("connected", False)
|
||||
report["zulip_ext"]["queue_id"] = zulip_state.get("queue_id")
|
||||
report["zulip_ext"]["last_error"] = zulip_state.get("last_error")
|
||||
report["zulip_ext"]["messages_processed"] = zulip_state.get("messages_processed", 0)
|
||||
report["zulip_ext"]["skipped"] = zulip_state.get("skipped", 0)
|
||||
report["zulip_ext"]["connected"] = zulip_health.get("connected", False)
|
||||
report["zulip_ext"]["queue_id"] = zulip_health.get("queue_id")
|
||||
report["zulip_ext"]["last_error"] = zulip_health.get("last_error")
|
||||
report["zulip_ext"]["messages_processed"] = zulip_health.get("messages_processed", 0)
|
||||
report["zulip_ext"]["retry_count"] = zulip_health.get("retry_count", 0)
|
||||
|
||||
# Phase 2: PM2 process check
|
||||
pm2_raw = subprocess.check_output(
|
||||
@@ -313,32 +289,50 @@ def collect():
|
||||
# Abiba (pi)
|
||||
report["agents"]["abiba"] = {
|
||||
"platform": "pi", "ct": 100, "ip": "192.168.68.24",
|
||||
"zulip_connected": zulip_state.get("connected", False),
|
||||
"zulip_processed": zulip_state.get("messages_processed", 0),
|
||||
"zulip_connected": zulip_health.get("connected", False),
|
||||
"zulip_processed": zulip_health.get("messages_processed", 0),
|
||||
"pm2_status": pm2.get("status", "unknown"),
|
||||
"pm2_restarts": pm2.get("restarts", "?"),
|
||||
"pm2_uptime": pm2.get("uptime", "?"),
|
||||
}
|
||||
|
||||
# Tanko (CT 112, IP 192.168.68.122) — DSH (DeepSeek Harness), no Hermes gateway
|
||||
# since 2026-08-27. There is no ~/.hermes/gateway_state.json on CT 112 anymore;
|
||||
# Zulip/Telegram connectivity is managed by the DSH harness, not the Hermes gateway.
|
||||
# Tanko (CT 122)
|
||||
tanko_state = ssh_jerome("192.168.68.122", "cat ~/.hermes/gateway_state.json 2>/dev/null")
|
||||
tanko_data = {}
|
||||
try:
|
||||
tanko_data = json.loads(tanko_state) if tanko_state else {}
|
||||
except:
|
||||
tanko_data = {}
|
||||
platforms = tanko_data.get("platforms", {})
|
||||
report["agents"]["tanko"] = {
|
||||
"platform": "dsh", "ct": 112, "ip": "192.168.68.122",
|
||||
"gateway_state": "n/a (DSH)",
|
||||
"zulip_state": "unknown",
|
||||
"telegram_state": "unknown",
|
||||
"gateway_pid": None,
|
||||
"updated_at": "",
|
||||
"platform": "hermes", "ct": 112, "ip": "192.168.68.122",
|
||||
"gateway_state": tanko_data.get("gateway_state", "unknown"),
|
||||
"zulip_state": platforms.get("zulip", {}).get("state", "unknown"),
|
||||
"telegram_state": platforms.get("telegram", {}).get("state", "unknown"),
|
||||
"gateway_pid": tanko_data.get("pid"),
|
||||
"updated_at": tanko_data.get("updated_at"),
|
||||
}
|
||||
|
||||
# Mumuni is deliberately absent from this digest: captain ruling 2026-09-10.
|
||||
# She moved off this host onto her own container (kagentz CT 105 on minipve,
|
||||
# 192.168.68.14, dedicated `hermes` user) and is monitored from her side. The
|
||||
# former probe ssh'd to 192.168.68.24 for the decommissioned deployment's
|
||||
# ~/.hermes/gateway_state.json, always read "unknown", and published a false
|
||||
# "mumuni:unknown" line in the agent table and the gateway-unknown issue
|
||||
# count of every digest. Do NOT re-add an .24 / gateway_state probe.
|
||||
# Mumuni (CT 114, IP 192.168.68.123)
|
||||
mumuni_state = ssh("192.168.68.123", "cat ~/.hermes/gateway_state.json 2>/dev/null")
|
||||
mumuni_data = {}
|
||||
try:
|
||||
mumuni_data = json.loads(mumuni_state) if mumuni_state else {}
|
||||
except:
|
||||
mumuni_data = {}
|
||||
mumuni_platforms = mumuni_data.get("platforms", {})
|
||||
report["agents"]["mumuni"] = {
|
||||
"platform": "hermes", "ct": 114, "ip": "192.168.68.123",
|
||||
"gateway_state": mumuni_data.get("gateway_state", "unknown"),
|
||||
"telegram_state": mumuni_platforms.get("telegram", {}).get("state", "unknown"),
|
||||
"zulip_state": mumuni_platforms.get("zulip", {}).get("state", "not_installed"),
|
||||
"email_state": mumuni_platforms.get("email", {}).get("state", "unknown"),
|
||||
"hermes_version": "",
|
||||
}
|
||||
# Get Hermes version
|
||||
ver = ssh("192.168.68.123", "hermes --version 2>/dev/null | head -1")
|
||||
if ver:
|
||||
report["agents"]["mumuni"]["hermes_version"] = ver.split("·")[0].replace("Hermes Agent ","").strip()
|
||||
|
||||
return report
|
||||
|
||||
@@ -430,7 +424,7 @@ th {{ color: #8b949e; font-weight: normal; }}
|
||||
<div class="alert {'good' if not issues else 'bad' if any('🔴' in i for i in issues) else 'warn'}">
|
||||
<p style="margin:0;font-size:16px"><b>{status}</b></p>
|
||||
<p style="margin:4px 0 0 0;font-size:13px">
|
||||
Proxmox: {r.get('pve_probe_status', 'ok')} ({r['nodes_online']}/{r['node_count']}) · {r['total_vms']} VMs/CTs · {r['running_vms']} running ·
|
||||
{r['node_count']} PVE nodes · {r['total_vms']} VMs/CTs · {r['running_vms']} running ·
|
||||
{r['docker_vm']['total'] + r['docker_syslog']['total'] + r['docker_netbird']['total']} containers ·
|
||||
{len(r['endpoints'])} endpoints · {len(r.get('agents',{}))} agents
|
||||
</p>
|
||||
@@ -446,10 +440,8 @@ Proxmox: {r.get('pve_probe_status', 'ok')} ({r['nodes_online']}/{r['node_count']
|
||||
|
||||
# ── Quick Stats ──
|
||||
html += '<div class="card"><h2>📊 Quick Stats</h2><div class="grid">'
|
||||
pve_status_label = "unreachable" if r.get('pve_probe_status') == 'unreachable' else f"{r['nodes_online']}/{r['node_count']}"
|
||||
pve_status_color = "red" if r.get('pve_probe_status') == 'unreachable' or r['nodes_online'] != r['node_count'] else "green"
|
||||
stats = [
|
||||
("PVE Nodes", pve_status_label, pve_status_color),
|
||||
("PVE Nodes", f"{r['nodes_online']}/{r['node_count']}", "green" if r['nodes_online'] == r['node_count'] else "red"),
|
||||
("VMs/CTs", f"{r['running_vms']}/{r['total_vms']}", "green" if r['running_vms'] == r['total_vms'] else "red"),
|
||||
("Containers", f"{r['docker_vm']['running']}/{r['docker_vm']['total']}", "green" if r['docker_vm']['running'] == r['docker_vm']['total'] else "yellow"),
|
||||
("LiteLLM Ctrs", f"{r['docker_syslog']['running']}/{r['docker_syslog']['total']}", "green" if r['docker_syslog']['running'] == r['docker_syslog']['total'] else "red"),
|
||||
@@ -551,7 +543,13 @@ Proxmox: {r.get('pve_probe_status', 'ok')} ({r['nodes_online']}/{r['node_count']
|
||||
elif name == "tanko":
|
||||
zulip_state = "✅" if agent.get("zulip_state") == "connected" else ("❌" if agent.get("zulip_state") == "disconnected" else "⬜")
|
||||
gateway = agent.get("gateway_state", "?")
|
||||
processed = "DSH"
|
||||
processed = agent.get("updated_at", "")[:10]
|
||||
elif name == "mumuni":
|
||||
zulip_state = "⬜" if agent.get("zulip_state") == "not_installed" else ("✅" if agent.get("zulip_state") == "connected" else "⬜")
|
||||
gateway = agent.get("gateway_state", "?")
|
||||
tg = "✅" if agent.get("telegram_state") == "connected" else "❌"
|
||||
ver = agent.get("hermes_version", "")
|
||||
processed = f"TG:{tg} v{ver}"
|
||||
else:
|
||||
zulip_state = "⬜"
|
||||
gateway = agent.get("gateway_state", "?")
|
||||
@@ -705,6 +703,6 @@ if __name__ == "__main__":
|
||||
print(f" Zulip Ext: {'✅' if report.get('zulip_ext',{}).get('connected') else '❌'}")
|
||||
print(f" LiteLLM: {sum(1 for c in report.get('litellm',{}).get('checks',[]) if c['status']=='pass')}/{len(report.get('litellm',{}).get('checks',[]))} checks pass")
|
||||
agent_parts = []
|
||||
for k,v in report.get('agents',{}).items():
|
||||
agent_parts.append(f"{k}:{v.get('gateway_state',v.get('pm2_status','?'))}")
|
||||
print(f" Agents: {', '.join(agent_parts)}")
|
||||
for k,v in report.get('agents',{}).items():
|
||||
agent_parts.append(f"{k}:{v.get('gateway_state',v.get('pm2_status','?'))}")
|
||||
print(f" Agents: {', '.join(agent_parts)}")
|
||||
|
||||
@@ -1,65 +0,0 @@
|
||||
#!/bin/bash
|
||||
# Netbird Reverse Proxy — Add a new domain route
|
||||
#
|
||||
# Usage: netbird-add-domain.sh <domain> <backend_ip> [port] [protocol]
|
||||
#
|
||||
# Example:
|
||||
# netbird-add-domain.sh dns.sysloggh.net 192.168.68.10 80
|
||||
#
|
||||
# This script adds a domain to the Netbird proxy by inserting records
|
||||
# directly into the management server's SQLite database, then restarting
|
||||
# the proxy stack.
|
||||
#
|
||||
# Prerequisites: SSH root access to 72.61.0.17
|
||||
# sqlite3 available on VPS
|
||||
#
|
||||
# Requires: The domain must already have a DNS CNAME to netbird.sysloggh.net
|
||||
# pointing to 72.61.0.17.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
DOMAIN="${1:?Usage: netbird-add-domain.sh <domain> <backend_ip> [port] [protocol]}"
|
||||
BACKEND_IP="${2:?Usage: netbird-add-domain.sh <domain> <backend_ip> [port] [protocol]}"
|
||||
PORT="${3:-80}"
|
||||
PROTOCOL="${4:-http}"
|
||||
|
||||
VPS="root@72.61.0.17"
|
||||
DB_VOLUME="/var/lib/docker/volumes/root_netbird_data/_data"
|
||||
DB="$DB_VOLUME/store.db"
|
||||
|
||||
echo "=== Adding Netbird proxy route ==="
|
||||
echo "Domain: $DOMAIN"
|
||||
echo "Backend: $BACKEND_IP:$PORT ($PROTOCOL)"
|
||||
echo ""
|
||||
|
||||
ssh "$VPS" bash << REMOTESCRIPT
|
||||
set -euo pipefail
|
||||
|
||||
# Generate unique ID using timestamp hash (Netbird format)
|
||||
ID_SUFFIX=\$(date +%s | md5sum | head -c 16)
|
||||
SVC_ID="d9\${ID_SUFFIX}ptsnc73\$(date +%s | md5sum | head -c 10)"
|
||||
TGT_ID=\$(sqlite3 "$DB" "SELECT COALESCE(MAX(id), 100) + 1 FROM targets;")
|
||||
ACCOUNT_ID="d88av3aptsnc73clmogg"
|
||||
ZONE_ID="d8adqjaptsnc73fro5g0"
|
||||
|
||||
echo "Service ID: \$SVC_ID"
|
||||
echo "Target ID: \$TGT_ID"
|
||||
|
||||
# Insert service
|
||||
sqlite3 "$DB" "INSERT INTO services (id, account_id, name, domain, proxy_cluster, enabled, terminated, pass_host_header, rewrite_redirects, mode, source, port_auto_assigned, private) VALUES (\"\$SVC_ID\", \"\$ACCOUNT_ID\", \"$DOMAIN\", \"$DOMAIN\", \"netbird.sysloggh.net\", 1, 0, 1, 0, \"http\", \"permanent\", 0, 0);"
|
||||
echo "Service: OK"
|
||||
|
||||
# Insert target
|
||||
sqlite3 "$DB" "INSERT INTO targets (id, account_id, service_id, host, port, protocol, target_id, target_type, enabled, skip_tls_verify, request_timeout, session_idle_timeout, agent_network, disable_access_log) VALUES (\$TGT_ID, \"\$ACCOUNT_ID\", \"\$SVC_ID\", \"$BACKEND_IP\", $PORT, \"$PROTOCOL\", \"\$ZONE_ID\", \"subnet\", 1, 0, 0, 0, 0, 0);"
|
||||
echo "Target: OK"
|
||||
|
||||
# Verify
|
||||
sqlite3 -column "$DB" "SELECT s.name, t.host, t.port, t.protocol FROM services s JOIN targets t ON s.id=t.service_id WHERE s.name=\"$DOMAIN\";"
|
||||
|
||||
echo ""
|
||||
echo "Restarting proxy stack..."
|
||||
cd /root && docker compose restart netbird-server 2>/dev/null
|
||||
sleep 15
|
||||
docker compose restart proxy 2>/dev/null
|
||||
echo "Done. Verify with: curl -sI https://$DOMAIN"
|
||||
REMOTESCRIPT
|
||||
+7
-7
@@ -11,31 +11,31 @@ set -euo pipefail
|
||||
# ── CT ID → PVE Node mapping (maintained HERE, not in prose contracts) ──
|
||||
declare -A CT_NODES=(
|
||||
# amdpve (192.168.68.15)
|
||||
[100]=amdpve # abiba
|
||||
[105]=amdpve # kagentz
|
||||
[111]=amdpve # tdunna
|
||||
[112]=amdpve # tanko
|
||||
[113]=amdpve # baggy
|
||||
[115]=amdpve # scottdenya
|
||||
# minipve (192.168.68.12)
|
||||
[102]=minipve # adguard (was acerpve)
|
||||
[104]=minipve # authentik
|
||||
[110]=minipve # gitea
|
||||
[114]=minipve # mumuni
|
||||
[116]=minipve # syslog-api
|
||||
[119]=minipve # infisical-vault
|
||||
# storepve (192.168.68.6)
|
||||
[106]=storepve # ra-h-os
|
||||
[107]=storepve # proxmox-backup
|
||||
[108]=storepve # media
|
||||
[117]=storepve # zulip
|
||||
[118]=storepve # jdownloader
|
||||
# acerpve (192.168.68.9) — no CTs (bare metal GPU .8)
|
||||
[100]=minipve # abiba (was hwepve)
|
||||
[105]=minipve # kagentz (was hwepve)
|
||||
# acerpve (192.168.68.9)
|
||||
[102]=acerpve # adguard
|
||||
# ocupve (192.168.68.5) — no CTs (bare metal GPU .110)
|
||||
#
|
||||
# REMOVED CTs (migrated to bare metal, decommissioned, or VMs):
|
||||
# 101 llm-gpu → bare metal 192.168.68.8 (RTX 3090)
|
||||
# 103 ocu-llm → bare metal 192.168.68.110 (RTX 5070)
|
||||
# 109 docker-vm → KVM VM 192.168.68.7 (use direct SSH)
|
||||
# 118 jitsi → stopped, not in service
|
||||
)
|
||||
|
||||
# Each node must be root-accessible via SSH hostname
|
||||
@@ -74,7 +74,7 @@ main() {
|
||||
if [[ $# -lt 1 ]]; then
|
||||
echo "Usage: pct-run <CT_ID> [command...]" >&2
|
||||
echo " pct-run 112 cat /etc/hostname" >&2
|
||||
echo " pct-run 100 systemctl status hermes-gateway" >&2
|
||||
echo " pct-run 114 systemctl status hermes-gateway" >&2
|
||||
echo ""
|
||||
echo "Known CTs:" >&2
|
||||
for ct in $(echo "${!CT_NODES[@]}" | tr ' ' '\n' | sort -n); do
|
||||
|
||||
@@ -5,7 +5,6 @@
|
||||
# Field positions (awk -F'│'): $7=pid $8=uptime $9=restarts $10=status
|
||||
|
||||
TELEGRAM_BOT_TOKEN="$(grep TELEGRAM_BOT_TOKEN /root/.pi/agent/extensions/telegram/.env 2>/dev/null | cut -d= -f2 || echo '')"
|
||||
LOG="/root/pm2-self-heal.log"
|
||||
TELEGRAM_CHAT_ID="5822977936"
|
||||
|
||||
notify_tg() {
|
||||
@@ -17,6 +16,8 @@ notify_tg() {
|
||||
-d "text=${msg}" \
|
||||
-d "parse_mode=HTML" > /dev/null 2>&1 || true
|
||||
}
|
||||
ALERTS="${ALERTS}$msg"
|
||||
}
|
||||
|
||||
# Log-only mode: replaced by prose contract pm2-self-heal.prose.md
|
||||
# Only alerts Telegram on actual failure (status != online)
|
||||
@@ -32,7 +33,7 @@ TEL_LINE=$(echo "$STATUS" | grep "abiba-telegram")
|
||||
TEL_STATUS=$(echo "$TEL_LINE" | awk -F'│' '{print $10}' | xargs)
|
||||
TEL_RESTARTS=$(echo "$TEL_LINE" | awk -F'│' '{print $9}' | xargs)
|
||||
|
||||
if [ "$TEL_STATUS" != "online" ] || [ "$TEL_RESTARTS" -gt 1000 ]; then
|
||||
if [ "$TEL_STATUS" != "online" ]; then
|
||||
pm2 restart abiba-telegram > /dev/null 2>&1
|
||||
sleep 3
|
||||
TEL_LINE2=$(pm2 status --no-color 2>/dev/null | grep "abiba-telegram")
|
||||
|
||||
+11
-14
@@ -47,32 +47,29 @@ You are a code reviewer for OpenProse infrastructure contracts in the Syslog Sol
|
||||
The infrastructure-control.prose.md contract is the canonical reference for the cluster topology:
|
||||
|
||||
**Proxmox Cluster "Tabiri" (5 nodes):**
|
||||
- amdpve (192.168.68.15): tanko, tdunna, baggy, scottdenya
|
||||
- minipve (192.168.68.12): abiba, kagentz, adguard, authentik, gitea, syslog-api, infisical-vault
|
||||
- storepve (192.168.68.6): docker-vm, ra-h-os, PBS, media, jdownloader, zulip
|
||||
- acerpve (192.168.68.9): llm-gpu
|
||||
- amdpve (192.168.68.15): abiba, kagentz, tanko, tdunna, baggy, scottdenya
|
||||
- minipve (192.168.68.12): authentik, gitea, mumuni, syslog-api, jitsi
|
||||
- storepve (192.168.68.6): docker-vm, ra-h-os, PBS, media, zulip
|
||||
- acerpve (192.168.68.9): llm-gpu, adguard
|
||||
- ocupve (192.168.68.5): ocu-llm
|
||||
|
||||
**CT IDs (verified 2026-07-24 against PVE API):**
|
||||
**CT IDs (verified 2026-07-04 against PVE API):**
|
||||
100:abiba 102:adguard 104:authentik 105:kagentz 106:ra-h-os
|
||||
107:pbs 108:media 110:gitea 111:tdunna 112:tanko
|
||||
113:baggy 115:scottdenya 116:syslog-api 117:zulip
|
||||
118:jdownloader 119:infisical-vault
|
||||
113:baggy 114:mumuni 115:scottdenya 116:syslog-api 117:zulip
|
||||
|
||||
**NO CT 122, CT 123, or .19 exist in the cluster.**
|
||||
|
||||
**CRITICAL RULES (never regress):**
|
||||
1. NO /grafana/ nginx route — it was tried and reverted on 2026-07-02. Grafana is direct LAN at :3001.
|
||||
2. NO .19 IP — Zulip is CT 117 on storepve.
|
||||
3. NO CT 122/123 — Tanko=CT 112, Mumuni=CT 100 (inside Abiba). No CT 114 anywhere.
|
||||
3. NO CT 122/123 — Tanko=CT 112, Mumuni=CT 114.
|
||||
4. Strix Halo :8080 is FIREWALLED to .116 only — cannot be probed from abiba (.24).
|
||||
5. abiba-zulip PM2 process is ONLINE (verified 2026-09-11) — this rule was stale.
|
||||
5. abiba-zulip PM2 process is DECOMMISSIONED (2026-07-04) — abiba uses Telegram only.
|
||||
|
||||
**Docker on CT 116 (11 containers, verified 2026-09-11):**
|
||||
harness-litellm, harness-nginx, harness-postgres, harness-redis,
|
||||
harness-dashboard, harness-grafana, harness-prometheus, harness-alertmanager,
|
||||
harness-zulip-bridge, harness-docker-stats, harness-pve-exporter
|
||||
(harness-router was decommissioned 2026-09-11)
|
||||
**Docker on CT 116 (8 containers):**
|
||||
harness-litellm, harness-router, harness-nginx, harness-postgres,
|
||||
harness-redis, harness-dashboard, harness-grafana, harness-prometheus
|
||||
|
||||
## DIFF TO REVIEW
|
||||
|
||||
|
||||
@@ -12,10 +12,10 @@ echo ""
|
||||
# Authorized agents for restricted contracts
|
||||
# Format: contract_pattern|authorized_agents (comma-separated)
|
||||
declare -A RESTRICTED
|
||||
RESTRICTED["infrastructure-control.prose.md"]="abiba,abiba-bot,tanko,tanko-bot,mumuni,mumuni-bot"
|
||||
RESTRICTED["proxmox-monitor.prose.md"]="abiba,abiba-bot"
|
||||
RESTRICTED["hermes-config-template.prose.md"]="abiba,abiba-bot,mumuni,mumuni-bot,tanko,tanko-bot"
|
||||
RESTRICTED["zulip-health.prose.md"]="abiba,abiba-bot,mumuni,mumuni-bot,tanko,tanko-bot"
|
||||
RESTRICTED["infrastructure-control.prose.md"]="abiba"
|
||||
RESTRICTED["proxmox-monitor.prose.md"]="abiba"
|
||||
RESTRICTED["hermes-config-template.prose.md"]="abiba,mumuni,tanko"
|
||||
RESTRICTED["zulip-health.prose.md"]="abiba,mumuni"
|
||||
RESTRICTED["scripts/pm2-self-heal.sh"]="abiba"
|
||||
RESTRICTED["scripts/prose-lint.sh"]="abiba"
|
||||
RESTRICTED["scripts/prose-ai-review.sh"]="abiba"
|
||||
|
||||
+2
-31
@@ -57,7 +57,7 @@ echo "── 2. Regression detection ──"
|
||||
|
||||
# Grafana /grafana/ as nginx route or URL path (reverted 2026-07-02)
|
||||
# EXCLUDE: filesystem paths (/opt/monitoring/grafana/...), directory creation, revert docs
|
||||
GRAFANA_HITS=$(grep -rn '/grafana/' ./*.prose.md 2>/dev/null \
|
||||
GRAFANA_HITS=$(grep -rn '/grafana/' *.prose.md 2>/dev/null \
|
||||
| grep -v '/opt/monitoring/grafana/' \
|
||||
| grep -v 'was tried and reverted\|was reverted\|do not re-add\|NOT recommended' \
|
||||
| grep -v 'mkdir.*grafana\|Create.*grafana' \
|
||||
@@ -71,7 +71,7 @@ else
|
||||
fi
|
||||
|
||||
# Stale CT IDs (CT 122, CT 123 as CT IDs — not IPs .122, .123)
|
||||
CT_STALE=$(grep -rn '\bCT 122\b' ./*.prose.md 2>/dev/null || true)
|
||||
CT_STALE=$(grep -rn '\bCT 122\b' *.prose.md 2>/dev/null || true)
|
||||
if [ -n "$CT_STALE" ]; then
|
||||
echo " ❌ REGRESSION: CT 122 used as CT ID — Tanko is CT 112"
|
||||
echo "$CT_STALE"
|
||||
@@ -84,35 +84,6 @@ fi
|
||||
# .122/.123 are correct — verified reachable bridge IPs for Tanko/Mumuni
|
||||
echo " ✅ IP consistency verified (.19=.122=.123 all reachable)"
|
||||
|
||||
# Report provenance — every contract report must state the absolute path it
|
||||
# executed from, so a stale-consumer report is distinguishable from a real fault
|
||||
# at read time (2026-09-09 probe-drift incident: three false DEGRADED rounds).
|
||||
# Enforced only inside the **Report format** paragraph, and a check-health
|
||||
# contract with no Report format paragraph FAILs rather than being skipped.
|
||||
PROV_FILES=$(grep -rlE '^### check-health|\*\*Report format\*\*' ./*.prose.md 2>/dev/null || true)
|
||||
if [ -z "$PROV_FILES" ]; then
|
||||
echo " ❌ No check-health/report-format contracts found — provenance not enforced"
|
||||
FAILED=1
|
||||
else
|
||||
PROV_BAD=0
|
||||
while IFS= read -r f; do
|
||||
[ -n "$f" ] || continue
|
||||
REPORT_PARA=$(awk '/\*\*Report format\*\*/{found=1} found{print} found && /^[[:space:]]*$/{exit}' "$f")
|
||||
if [ -z "$REPORT_PARA" ]; then
|
||||
echo " ❌ $f: check-health contract has no **Report format** paragraph"
|
||||
PROV_BAD=1
|
||||
elif ! printf '%s\n' "$REPORT_PARA" | grep -qE 'absolute path|pwd -P|executed from'; then
|
||||
echo " ❌ $f: **Report format** lacks execution provenance (absolute path / pwd -P)"
|
||||
PROV_BAD=1
|
||||
fi
|
||||
done <<< "$PROV_FILES"
|
||||
if [ "$PROV_BAD" -eq 1 ]; then
|
||||
FAILED=1
|
||||
else
|
||||
echo " ✅ Report provenance present in all report-format contracts"
|
||||
fi
|
||||
fi
|
||||
|
||||
# ── 3. Cross-contract consistency ──
|
||||
echo ""
|
||||
echo "── 3. Cross-contract consistency ──"
|
||||
|
||||
@@ -1,91 +0,0 @@
|
||||
#!/bin/bash
|
||||
# swap-gpu-dense-model.sh — Swap RTX 3090 from qwen3.6-27B-code to SmartCode-Fable-5
|
||||
# Run when download completes: ssh root@192.168.68.8 'bash -s' < this script
|
||||
#
|
||||
# Usage: bash swap-gpu-dense-model.sh
|
||||
# Requires: new model at /home/llmuser/models/SmartCode-Fable-5-27B-UD-Q4_K_XL.gguf
|
||||
|
||||
set -e
|
||||
|
||||
MODEL_PATH="/home/llmuser/models/SmartCode-Fable-5-27B-UD-Q4_K_XL.gguf"
|
||||
OLD_WRAPPER="/home/llmuser/llama-wrapper.sh"
|
||||
|
||||
echo "═══ Swapping gpu-dense to SmartCode-Fable-5 ═══"
|
||||
|
||||
# 1. Verify model file
|
||||
if [ ! -f "$MODEL_PATH" ]; then
|
||||
echo "❌ Model not found at $MODEL_PATH"
|
||||
echo " Download: curl -L -o $MODEL_PATH <huggingface-url>"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
MODEL_SIZE=$(ls -lh "$MODEL_PATH" | awk '{print $5}')
|
||||
echo "✅ Model found: $MODEL_SIZE"
|
||||
|
||||
# 2. Create new wrapper script for SmartCode-Fable-5
|
||||
cat > /home/llmuser/llama-fable-wrapper.sh << 'WRAPPER'
|
||||
#!/bin/bash
|
||||
# SmartCode-Fable-5 llama-server wrapper for RTX 3090
|
||||
# Sampler settings from model card: temp 0.9, top-p 0.95, top-k 60, repeat-penalty off
|
||||
|
||||
PORT=8080
|
||||
GHOST_PID=$(ss -tlnp 2>/dev/null | grep -Po ":${PORT}\s+.*pid=\K[0-9]+" | head -1)
|
||||
if [ -n "$GHOST_PID" ] && [ "$GHOST_PID" != "$$" ]; then
|
||||
echo "[wrapper] Port $PORT occupied by ghost pid $GHOST_PID — cleaning up" >&2
|
||||
kill -9 "$GHOST_PID" 2>/dev/null
|
||||
sleep 2
|
||||
fi
|
||||
|
||||
exec /usr/local/bin/llama-server \
|
||||
--model /home/llmuser/models/SmartCode-Fable-5-27B-UD-Q4_K_XL.gguf \
|
||||
--ctx-size 131072 \
|
||||
--cache-type-k q4_0 \
|
||||
--cache-type-v q4_0 \
|
||||
--flash-attn 1 \
|
||||
--cont-batching \
|
||||
--parallel 1 \
|
||||
--batch-size 2048 \
|
||||
--ubatch-size 1024 \
|
||||
--n-gpu-layers 99 \
|
||||
--temp 0.9 \
|
||||
--top-p 0.95 \
|
||||
--top-k 60 \
|
||||
--min-p 0.0 \
|
||||
--repeat-penalty 1.0 \
|
||||
--api-key not-needed \
|
||||
--port 8080 \
|
||||
--host 0.0.0.0
|
||||
WRAPPER
|
||||
|
||||
chmod 755 /home/llmuser/llama-fable-wrapper.sh
|
||||
echo "✅ Created /home/llmuser/llama-fable-wrapper.sh"
|
||||
|
||||
# 3. Update systemd service to use new wrapper
|
||||
echo "📝 Updating systemd service..."
|
||||
sed -i 's|ExecStart=/home/llmuser/llama-wrapper.sh|ExecStart=/home/llmuser/llama-fable-wrapper.sh|' /etc/systemd/system/llama-server.service
|
||||
systemctl daemon-reload
|
||||
|
||||
# 4. Stop old server, start new
|
||||
echo "🔄 Restarting llama-server..."
|
||||
systemctl stop llama-server
|
||||
sleep 3
|
||||
systemctl start llama-server
|
||||
sleep 8
|
||||
|
||||
# 5. Verify
|
||||
echo ""
|
||||
echo "═══ Verification ═══"
|
||||
systemctl is-active llama-server
|
||||
echo ""
|
||||
echo "Port 8080:"
|
||||
ss -tlnp 2>/dev/null | grep ":8080" | head -1
|
||||
echo ""
|
||||
echo "GPU VRAM:"
|
||||
nvidia-smi --query-gpu=memory.used,memory.total,utilization.gpu --format=csv,noheader 2>/dev/null
|
||||
echo ""
|
||||
echo "=== Health check ==="
|
||||
curl -s --max-time 5 http://localhost:8080/health 2>/dev/null
|
||||
echo ""
|
||||
echo ""
|
||||
echo "✅ Swap complete. Test via LiteLLM:"
|
||||
echo " curl -s http://192.168.68.116/v1/chat/completions -H 'Authorization: Bearer <key>' -H 'Content-Type: application/json' -d '{\"model\":\"gpu-dense\",\"messages\":[{\"role\":\"user\",\"content\":\"write hello world in python\"}],\"max_tokens\":100}'"
|
||||
+80
-117
@@ -1,10 +1,7 @@
|
||||
#!/bin/bash
|
||||
# /root/scripts/zulip-monitor.sh — Zulip Mesh Health Monitor
|
||||
# Implements zulip-health.prose.md v3
|
||||
# Runs every 15 min via cron. Alerts: Zulip private DM to the owner plus a stream post to #agent-hub on topic 'zulip-health'.
|
||||
# Legs: global Zulip server, Platform A pi/Abiba (the Zulip bridge), Platform B
|
||||
# Tanko (DSH), Platform C Agent Zero (kagentz). The former Platform B Hermes
|
||||
# agent leg is retired — see the note after the Tanko leg.
|
||||
# Implements zulip-health.prose.md v2
|
||||
# Runs every 15 min via cron. Alerts via Telegram.
|
||||
set -euo pipefail
|
||||
|
||||
ZULIP_SITE="https://chat.sysloggh.net"
|
||||
@@ -12,11 +9,10 @@ ZULIP_EMAIL="abiba-bot@chat.sysloggh.net"
|
||||
ZULIP_KEY="cKTDMZAPW08dk3zl05sStzO7HRztzyn8"
|
||||
OWNER_ZULIP_ID="9"
|
||||
|
||||
|
||||
LOG="/root/zulip-health-monitor.log"
|
||||
TIMESTAMP=$(date -u '+%Y-%m-%d %H:%M UTC')
|
||||
ISSUES=0
|
||||
echo "=== Zulip Health Check — $TIMESTAMP ===" >> "$LOG"
|
||||
# Email config
|
||||
GMAIL_USER="jtabiri@gmail.com"
|
||||
GMAIL_PASS="rgbuomwcydxwbszd"
|
||||
EMAIL_TO="jerome@sysloggh.com"
|
||||
|
||||
notify() {
|
||||
local severity="$1" msg="$2"
|
||||
@@ -24,20 +20,34 @@ notify() {
|
||||
|
||||
# Zulip DM to owner
|
||||
local content="${severity} Zulip Monitor: ${msg}"
|
||||
local form
|
||||
form="type=private&to=%5B${OWNER_ZULIP_ID}%5D&content=$(python3 -c "import urllib.parse; print(urllib.parse.quote('''${content}'''))")"
|
||||
local form="type=private&to=%5B${OWNER_ZULIP_ID}%5D&content=$(python3 -c "import urllib.parse; print(urllib.parse.quote('''${content}'''))")"
|
||||
curl -sf -X POST "${ZULIP_SITE}/api/v1/messages" \
|
||||
-u "${ZULIP_EMAIL}:${ZULIP_KEY}" \
|
||||
-d "${form}" > /dev/null 2>&1 || true
|
||||
# Zulip stream post to #agent-hub on topic 'zulip-health'
|
||||
local stream_content="${severity} Zulip Monitor: ${msg}"
|
||||
curl -sf -X POST "${ZULIP_SITE}/api/v1/messages" \
|
||||
-u "${ZULIP_EMAIL}:${ZULIP_KEY}" \
|
||||
-d "type=stream&to=%5B7%5D&topic=zulip-health&content=$(printf '%s' "${stream_content}" | python3 -c "import sys,urllib.parse; print(urllib.parse.quote_from_bytes(sys.stdin.buffer.read()))")" \
|
||||
> /dev/null 2>&1 \
|
||||
|| echo " WARN: stream alert to #agent-hub (zulip-health) delivery failed (curl exit $?)" >> "$LOG"
|
||||
|
||||
# Email alert
|
||||
local subject="${severity} Zulip Monitor Alert"
|
||||
python3 -c "
|
||||
import smtplib
|
||||
from email.mime.text import MIMEText
|
||||
m = MIMEText('''${msg}''')
|
||||
m['From'] = 'abiba@sysloggh.com'
|
||||
m['To'] = '${EMAIL_TO}'
|
||||
m['Subject'] = '${subject}'
|
||||
s = smtplib.SMTP('smtp.gmail.com', 587)
|
||||
s.starttls()
|
||||
s.login('${GMAIL_USER}', '${GMAIL_PASS}')
|
||||
s.sendmail('abiba@sysloggh.com', ['${EMAIL_TO}'], m.as_string())
|
||||
s.quit()
|
||||
" 2>/dev/null || true
|
||||
}
|
||||
|
||||
TIMESTAMP=$(date -u '+%Y-%m-%d %H:%M UTC')
|
||||
ISSUES=0
|
||||
LOG="/root/zulip-health-monitor.log"
|
||||
|
||||
echo "=== Zulip Health Check — $TIMESTAMP ===" >> "$LOG"
|
||||
|
||||
# ── Global: Zulip Server ──
|
||||
SERVER_CODE=$(curl -s -o /dev/null -w "%{http_code}" --connect-timeout 10 \
|
||||
https://chat.sysloggh.net/api/v1/server_settings \
|
||||
@@ -50,109 +60,62 @@ else
|
||||
fi
|
||||
|
||||
# ── Platform A: pi (Abiba) ──
|
||||
# Probes the pi Zulip extension health endpoint (:9200/health, served by the
|
||||
# extension's startHealthServer; shape documented in zulip-health.prose.md).
|
||||
# FAIL-SAFE contract (pinned by tests/zulip-monitor-abiba.sh): connection state
|
||||
# lives NESTED at zulip.connected / zulip.last_error — there is no top-level
|
||||
# `connected` and no retry counter in the payload. A fetch error, non-2xx
|
||||
# response, empty/unparseable body, or payload missing a boolean
|
||||
# zulip.connected is a PROBE FAILURE: it alerts and NEVER calls pm2 restart.
|
||||
# pm2 restart runs ONLY on affirmative zulip.connected=false.
|
||||
# -- abiba-leg-start (verbatim-extracted by tests/zulip-monitor-abiba.sh)
|
||||
PI_HTTP=$(curl -s -o /dev/null --connect-timeout 5 --max-time 10 -w '%{http_code}' http://localhost:9200/health 2>/dev/null || echo "000")
|
||||
PI_BODY=$(curl -s --connect-timeout 5 --max-time 10 http://localhost:9200/health 2>/dev/null || true)
|
||||
PI_STATE=$(printf '%s' "$PI_BODY" | python3 -c '
|
||||
import sys, json
|
||||
code = sys.argv[1]
|
||||
body = sys.stdin.read()
|
||||
try:
|
||||
d = json.loads(body)
|
||||
except Exception:
|
||||
sys.stdout.write("probe-failed|unparseable body")
|
||||
sys.exit(0)
|
||||
if not code.startswith("2"):
|
||||
sys.stdout.write("probe-failed|HTTP %s" % code)
|
||||
sys.exit(0)
|
||||
if not isinstance(d, dict) or not isinstance(d.get("zulip"), dict):
|
||||
sys.stdout.write("probe-failed|missing zulip.connected")
|
||||
sys.exit(0)
|
||||
z = d["zulip"]
|
||||
if "connected" not in z or not isinstance(z["connected"], bool):
|
||||
sys.stdout.write("probe-failed|missing or non-boolean zulip.connected")
|
||||
sys.exit(0)
|
||||
err = z.get("last_error") or ""
|
||||
if z["connected"]:
|
||||
if err:
|
||||
sys.stdout.write("degraded|%s" % err)
|
||||
else:
|
||||
sys.stdout.write("healthy|%s" % z.get("messages_processed", 0))
|
||||
else:
|
||||
sys.stdout.write("disconnected|")
|
||||
' "$PI_HTTP" 2>/dev/null) || PI_STATE="probe-failed|python error"
|
||||
PI_VERDICT=${PI_STATE%%|*}
|
||||
PI_DETAIL=${PI_STATE#*|}
|
||||
PI_HEALTH=$(curl -sf --connect-timeout 5 http://localhost:9200/health 2>/dev/null || echo "{}")
|
||||
PI_CONNECTED=$(echo "$PI_HEALTH" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('connected',False))" 2>/dev/null)
|
||||
PI_ERROR=$(echo "$PI_HEALTH" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('last_error') or '')" 2>/dev/null)
|
||||
PI_RETRIES=$(echo "$PI_HEALTH" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('retry_count',0))" 2>/dev/null)
|
||||
|
||||
case "$PI_VERDICT" in
|
||||
healthy)
|
||||
echo " Abiba: ✅ Connected (processed=$PI_DETAIL)" >> "$LOG" ;;
|
||||
degraded)
|
||||
notify "🟡" "Abiba pi extension error: ${PI_DETAIL:0:100}"
|
||||
echo " Abiba: 🟡 Error: ${PI_DETAIL:0:100}" >> "$LOG" ;;
|
||||
disconnected)
|
||||
notify "🔴" "Abiba pi extension DISCONNECTED — restarting"
|
||||
pm2 restart abiba-zulip 2>/dev/null || true
|
||||
ISSUES=$((ISSUES + 1))
|
||||
echo " Abiba: ❌ Disconnected — restarted" >> "$LOG" ;;
|
||||
probe-failed)
|
||||
notify "🟠" "Abiba pi extension health probe FAILED (${PI_DETAIL}; HTTP $PI_HTTP) — NOT restarting, manual check needed"
|
||||
ISSUES=$((ISSUES + 1))
|
||||
echo " Abiba: ⚠️ Probe failed (${PI_DETAIL}; HTTP $PI_HTTP) — NOT restarted" >> "$LOG" ;;
|
||||
*)
|
||||
notify "🟠" "Abiba pi extension health probe returned unexpected verdict (${PI_STATE}) — NOT restarting, manual check needed"
|
||||
ISSUES=$((ISSUES + 1))
|
||||
echo " Abiba: ⚠️ Unexpected probe verdict (${PI_STATE}) — NOT restarted" >> "$LOG" ;;
|
||||
esac
|
||||
# -- abiba-leg-end
|
||||
|
||||
# ── Platform B: Tanko (DSH dsh-web on amdpve CT 112) ──
|
||||
# Direct SSH to 192.168.68.122 is not a dependency of this monitor — per-worker
|
||||
# key availability varies — so probes run from the amdpve vantage via `pct exec`.
|
||||
# Tanko's Zulip gateway runs as the dsh-web systemd unit inside CT 112 on amdpve
|
||||
# (192.168.68.15). The gateway binds 127.0.0.1:3080 loopback-only by design — a
|
||||
# remote :3080 probe is refused and is NOT a fault.
|
||||
TANKO_SVC=$(ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 root@192.168.68.15 \
|
||||
"pct exec 112 -- systemctl is-active dsh-web" 2>/dev/null || true)
|
||||
[ -n "$TANKO_SVC" ] || TANKO_SVC="unknown"
|
||||
TANKO_HTTP=$(ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 root@192.168.68.15 \
|
||||
"pct exec 112 -- curl -s --connect-timeout 5 --max-time 10 -o /dev/null -w '%{http_code}' http://127.0.0.1:3080/" 2>/dev/null || true)
|
||||
[ -n "$TANKO_HTTP" ] || TANKO_HTTP="000"
|
||||
|
||||
if [ "$TANKO_SVC" != "active" ]; then
|
||||
notify "🔴" "Tanko (DSH dsh-web) service state: $TANKO_SVC — needs restart"
|
||||
if [ "$PI_CONNECTED" != "True" ]; then
|
||||
notify "🔴" "Abiba pi extension DISCONNECTED — restarting"
|
||||
pm2 restart abiba-zulip 2>/dev/null || true
|
||||
ISSUES=$((ISSUES + 1))
|
||||
echo " Tanko: ❌ service=$TANKO_SVC" >> "$LOG"
|
||||
elif [ "$TANKO_HTTP" = "000" ]; then
|
||||
notify "🔴" "Tanko (DSH dsh-web) HTTP :3080 connection refused/timeout — needs restart"
|
||||
ISSUES=$((ISSUES + 1))
|
||||
echo " Tanko: ❌ http=000 (refused/timeout)" >> "$LOG"
|
||||
echo " Abiba: ❌ Disconnected — restarted" >> "$LOG"
|
||||
elif [ -n "$PI_ERROR" ]; then
|
||||
notify "🟡" "Abiba pi extension error: ${PI_ERROR:0:100}"
|
||||
echo " Abiba: 🟡 Error: ${PI_ERROR:0:100}" >> "$LOG"
|
||||
elif [ "$PI_RETRIES" -ge 3 ]; then
|
||||
notify "🟡" "Abiba pi extension: $PI_RETRIES retries — restarting"
|
||||
pm2 restart abiba-zulip 2>/dev/null || true
|
||||
echo " Abiba: 🟡 $PI_RETRIES retries — restarted" >> "$LOG"
|
||||
else
|
||||
case "$TANKO_HTTP" in
|
||||
200|301|302|307|308|401|403)
|
||||
echo " Tanko: ✅ service=active http=$TANKO_HTTP" >> "$LOG" ;;
|
||||
*)
|
||||
notify "🟡" "Tanko (DSH dsh-web) HTTP :3080 answered $TANKO_HTTP — running, unexpected status"
|
||||
echo " Tanko: 🟡 service=active http=$TANKO_HTTP (running, warning)" >> "$LOG" ;;
|
||||
esac
|
||||
echo " Abiba: ✅ Connected (processed=$(echo "$PI_HEALTH" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('messages_processed',0))" 2>/dev/null))" >> "$LOG"
|
||||
fi
|
||||
|
||||
# ── Removed: the former "Platform B: Hermes" agent leg ──
|
||||
# Captain ruling 2026-09-10: that agent moved off this host onto her own
|
||||
# container (kagentz CT 105 on minipve, dedicated `hermes` user) and is now
|
||||
# monitored on her side — see the out-of-scope note in zulip-health.prose.md.
|
||||
# The old leg ssh'd to her former CT 100 deployment and read its Hermes gateway
|
||||
# state, which reported "unknown" on every run and posted a false 🔴 DM plus an
|
||||
# #agent-hub stream alert. Do NOT re-add a probe for her: this monitor must
|
||||
# never contact her former host.
|
||||
# ── Platform B: Hermes (Tanko) ──
|
||||
TANKO_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 "{}")
|
||||
TANKO_ZULIP=$(echo "$TANKO_STATE" | python3 -c "
|
||||
import sys,json
|
||||
d=json.load(sys.stdin)
|
||||
p=d.get('platforms',{}).get('zulip',{})
|
||||
print(p.get('state','unknown'))
|
||||
" 2>/dev/null)
|
||||
|
||||
if [ "$TANKO_ZULIP" != "connected" ]; then
|
||||
notify "🔴" "Tanko (Hermes) Zulip state: $TANKO_ZULIP — needs restart"
|
||||
ISSUES=$((ISSUES + 1))
|
||||
echo " Tanko: ❌ state=$TANKO_ZULIP" >> "$LOG"
|
||||
else
|
||||
echo " Tanko: ✅ Zulip connected" >> "$LOG"
|
||||
fi
|
||||
|
||||
# ── Platform B: Hermes (Mumuni) ──
|
||||
MUMUNI_STATE=$(ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 root@192.168.68.123 \
|
||||
"cat ~/.hermes/gateway_state.json 2>/dev/null" 2>/dev/null || echo "{}")
|
||||
MUMUNI_ZULIP=$(echo "$MUMUNI_STATE" | python3 -c "
|
||||
import sys,json
|
||||
d=json.load(sys.stdin)
|
||||
p=d.get('platforms',{}).get('zulip',{})
|
||||
print(p.get('state','unknown'))
|
||||
" 2>/dev/null)
|
||||
|
||||
if [ "$MUMUNI_ZULIP" != "connected" ]; then
|
||||
notify "🔴" "Mumuni (Hermes) Zulip state: $MUMUNI_ZULIP"
|
||||
ISSUES=$((ISSUES + 1))
|
||||
echo " Mumuni: ❌ state=$MUMUNI_ZULIP" >> "$LOG"
|
||||
else
|
||||
echo " Mumuni: ✅ Zulip connected" >> "$LOG"
|
||||
fi
|
||||
|
||||
# ── Platform C: Agent Zero (kagentz) ──
|
||||
AZ_A2A=$(ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 root@192.168.68.14 \
|
||||
|
||||
-25
@@ -1,25 +0,0 @@
|
||||
{
|
||||
"status": "ok",
|
||||
"platform": "pi",
|
||||
"agent": "abiba",
|
||||
"zulip": {
|
||||
"connected": true,
|
||||
"site": "https://chat.sysloggh.net",
|
||||
"email": "abiba-bot@chat.sysloggh.net",
|
||||
"queue_id": "ee7f8b6d-9d53-48a7-ad58-f6e999771001",
|
||||
"bot_user_id": 21,
|
||||
"messages_processed": 0,
|
||||
"skipped": 0,
|
||||
"last_error": null
|
||||
},
|
||||
"circuit_breaker": {
|
||||
"state": "CLOSED",
|
||||
"failures": 0,
|
||||
"successes": 5,
|
||||
"totalRequests": 5,
|
||||
"failureRate": "0.000",
|
||||
"openedAt": null
|
||||
},
|
||||
"workers": [],
|
||||
"worker_count": 0
|
||||
}
|
||||
-25
@@ -1,25 +0,0 @@
|
||||
{
|
||||
"status": "down",
|
||||
"platform": "pi",
|
||||
"agent": "abiba",
|
||||
"zulip": {
|
||||
"connected": false,
|
||||
"site": "https://chat.sysloggh.net",
|
||||
"email": "abiba-bot@chat.sysloggh.net",
|
||||
"queue_id": null,
|
||||
"bot_user_id": null,
|
||||
"messages_processed": 0,
|
||||
"skipped": 0,
|
||||
"last_error": "Zulip API error 401: queue registration failed"
|
||||
},
|
||||
"circuit_breaker": {
|
||||
"state": "CLOSED",
|
||||
"failures": 0,
|
||||
"successes": 0,
|
||||
"totalRequests": 0,
|
||||
"failureRate": "0.000",
|
||||
"openedAt": null
|
||||
},
|
||||
"workers": [],
|
||||
"worker_count": 0
|
||||
}
|
||||
@@ -1,138 +0,0 @@
|
||||
"""
|
||||
Regression tests for daily-infra-report.py fixes (PR #64).
|
||||
|
||||
Tests:
|
||||
(a) Asserts the nested zulip read feeds the agent-card fields
|
||||
(b) Asserts an unreachable pve_get renders labelled-unreachable, not "0/0"
|
||||
"""
|
||||
import json
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from unittest.mock import patch, MagicMock
|
||||
|
||||
# Add scripts to path
|
||||
sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))
|
||||
import importlib.util
|
||||
|
||||
def load_script():
|
||||
"""Load the daily-infra-report script as a module."""
|
||||
script_path = Path(__file__).parent.parent / "scripts" / "daily-infra-report.py"
|
||||
spec = importlib.util.spec_from_file_location("daily_infra_report", script_path)
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(module)
|
||||
return module
|
||||
|
||||
|
||||
def test_nested_zulip_read_feeds_agent_card():
|
||||
"""Test that Zulip state is read from the nested 'zulip' key and feeds agent-card fields."""
|
||||
# Mock the http_get_body response with nested structure
|
||||
mock_health_response = json.dumps({
|
||||
"status": "ok",
|
||||
"platform": "pi",
|
||||
"agent": "abiba",
|
||||
"zulip": {
|
||||
"connected": True,
|
||||
"queue_id": "test-queue-id",
|
||||
"messages_processed": 42,
|
||||
"skipped": 5,
|
||||
"last_error": None
|
||||
}
|
||||
})
|
||||
|
||||
# Import and patch
|
||||
report_mod = load_script()
|
||||
|
||||
with patch.object(report_mod, 'http_get_body', return_value=mock_health_response):
|
||||
# Simulate the collect() function's Zulip section
|
||||
zulip_health = json.loads(report_mod.http_get_body("http://localhost:9200/health"))
|
||||
zulip_state = zulip_health.get("zulip", {})
|
||||
|
||||
# Assert the nested key is read correctly
|
||||
assert zulip_state.get("connected") == True, "Zulip connected should be True from nested key"
|
||||
assert zulip_state.get("messages_processed") == 42, "messages_processed should be 42 from nested key"
|
||||
assert zulip_state.get("queue_id") == "test-queue-id", "queue_id should be read from nested key"
|
||||
|
||||
# Simulate the agent card field population
|
||||
agent_card = {
|
||||
"zulip_connected": zulip_state.get("connected", False),
|
||||
"zulip_processed": zulip_state.get("messages_processed", 0),
|
||||
}
|
||||
|
||||
assert agent_card["zulip_connected"] == True, "Agent card should show Zulip connected"
|
||||
assert agent_card["zulip_processed"] == 42, "Agent card should show 42 processed messages"
|
||||
|
||||
|
||||
def test_unreachable_pve_get_renders_labelled_unreachable():
|
||||
"""Test that an unreachable PVE API renders 'unreachable' instead of '0/0'."""
|
||||
# Import and patch
|
||||
report_mod = load_script()
|
||||
|
||||
# Test pve_get returns None on error
|
||||
with patch.object(report_mod.subprocess, 'run') as mock_run:
|
||||
mock_run.return_value.returncode = 7 # Connection failure
|
||||
result = report_mod.pve_get("/api2/json/nodes")
|
||||
assert result is None, "pve_get should return None on connection failure"
|
||||
|
||||
# Test the render logic
|
||||
report = {
|
||||
"nodes": {},
|
||||
"node_count": 0,
|
||||
"nodes_online": 0,
|
||||
"pve_probe_status": "unreachable",
|
||||
"total_vms": 0,
|
||||
"running_vms": 0,
|
||||
}
|
||||
|
||||
# The render should show "unreachable" not "0/0"
|
||||
pve_status_label = "unreachable" if report.get('pve_probe_status') == 'unreachable' else f"{report['nodes_online']}/{report['node_count']}"
|
||||
|
||||
assert pve_status_label == "unreachable", "PVE status should show 'unreachable' when probe fails, not '0/0'"
|
||||
|
||||
|
||||
def test_unreachable_resources_renders_labelled_unreachable():
|
||||
"""Test that unreachable resources probe renders 'unreachable' instead of '0/0'."""
|
||||
report_mod = load_script()
|
||||
|
||||
# Test resources probe returns None
|
||||
with patch.object(report_mod.subprocess, 'run') as mock_run:
|
||||
mock_run.return_value.returncode = 7
|
||||
result = report_mod.pve_get("/api2/json/cluster/resources")
|
||||
assert result is None, "pve_get for resources should return None on connection failure"
|
||||
|
||||
# Test the render logic
|
||||
report = {
|
||||
"resources_probe_status": "unreachable",
|
||||
"total_vms": 0,
|
||||
"running_vms": 0,
|
||||
}
|
||||
|
||||
resources_label = "unreachable" if report.get('resources_probe_status') == 'unreachable' else f"{report['running_vms']}/{report['total_vms']}"
|
||||
|
||||
assert resources_label == "unreachable", "Resources status should show 'unreachable' when probe fails, not '0/0'"
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
print("Running tests...")
|
||||
try:
|
||||
test_nested_zulip_read_feeds_agent_card()
|
||||
print("✓ test_nested_zulip_read_feeds_agent_card passed")
|
||||
except AssertionError as e:
|
||||
print(f"✗ test_nested_zulip_read_feeds_agent_card failed: {e}")
|
||||
sys.exit(1)
|
||||
|
||||
try:
|
||||
test_unreachable_pve_get_renders_labelled_unreachable()
|
||||
print("✓ test_unreachable_pve_get_renders_labelled_unreachable passed")
|
||||
except AssertionError as e:
|
||||
print(f"✗ test_unreachable_pve_get_renders_labelled_unreachable failed: {e}")
|
||||
sys.exit(1)
|
||||
|
||||
try:
|
||||
test_unreachable_resources_renders_labelled_unreachable()
|
||||
print("✓ test_unreachable_resources_renders_labelled_unreachable passed")
|
||||
except AssertionError as e:
|
||||
print(f"✗ test_unreachable_resources_renders_labelled_unreachable failed: {e}")
|
||||
sys.exit(1)
|
||||
|
||||
print("All tests passed!")
|
||||
@@ -1,352 +0,0 @@
|
||||
"""Regression tests for the 2026-09-10 retirement of the Mumuni monitoring leg.
|
||||
|
||||
WHY THIS FILE EXISTS: captain ruling 2026-09-10 — Mumuni moved off this host
|
||||
onto her own container (kagentz CT 105 on minipve, 192.168.68.14, dedicated
|
||||
`hermes` user) and is monitored from her side. The monitor nevertheless kept
|
||||
ssh'ing to root@192.168.68.24 for `~/.hermes/gateway_state.json` on the
|
||||
decommissioned deployment, read "unknown" on every run, and posted a false 🔴
|
||||
"Mumuni (Hermes) Zulip state: unknown" DM + #agent-hub stream alert to the
|
||||
captain. The daily infra digest published a matching `mumuni:unknown` row.
|
||||
|
||||
CONTRACT UNDER TEST:
|
||||
* `scripts/zulip-monitor.sh` carries NO Mumuni probe and NO 192.168.68.24
|
||||
reference; it never ssh'es .24, and even on a failing run it emits no Mumuni
|
||||
notify (stdout alert, Zulip payload, or log line).
|
||||
* The Abiba (pi — the Zulip bridge), Tanko (DSH) and Agent Zero (kagentz) legs
|
||||
still work: deleting the Mumuni leg must not have gutted the rest.
|
||||
* `scripts/daily-infra-report.py` no longer probes .24 for a Hermes gateway
|
||||
state and no longer emits a `mumuni` agent entry.
|
||||
* `scripts/agent-health-check.py`'s AGENTS roster has no mumuni entry. This is
|
||||
a pin, not a behavior change — verify the probe was already gone.
|
||||
* `zulip-health.prose.md` retires the Mumuni-only steps and says explicitly
|
||||
that Mumuni is not monitored from this host.
|
||||
|
||||
HOW: behavioral execution plus one named deliverable-text contract. The sandbox
|
||||
copies the shipped monitor verbatim and rewrites only its LOG constant, then
|
||||
runs it with stub ssh/curl on PATH; the ssh stub records every host it is asked
|
||||
to reach, so "never probes .24" and "no Mumuni notify" are asserted from
|
||||
observed behavior. The daily digest is pinned by importing it and exercising
|
||||
collect() and build_html() directly. The single source-text assertion is the
|
||||
deliverable-text contract the captain acceptance names for the shipped monitor.
|
||||
|
||||
Usage: python3 -m pytest tests/test_mumuni_monitor_removal.py
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import importlib.util
|
||||
import os
|
||||
import pathlib
|
||||
import stat
|
||||
import subprocess
|
||||
|
||||
import pytest
|
||||
|
||||
ROOT = pathlib.Path(__file__).resolve().parents[1]
|
||||
ZULIP_MONITOR = ROOT / "scripts" / "zulip-monitor.sh"
|
||||
DAILY_REPORT = ROOT / "scripts" / "daily-infra-report.py"
|
||||
AHC = ROOT / "scripts" / "agent-health-check.py"
|
||||
HEALTH_CONTRACT = ROOT / "zulip-health.prose.md"
|
||||
CONNECTED_FIXTURE = ROOT / "tests" / "fixtures" / "zulip-health-connected.json"
|
||||
|
||||
MUMUNI_IP = "192.168.68.24" # Mumuni's old (decommissioned) deployment
|
||||
TANKO_VANTAGE = "192.168.68.15" # amdpve — Tanko CT 112 via pct exec
|
||||
AGENT_ZERO_HOST = "192.168.68.14" # kagentz host, Agent Zero docker
|
||||
|
||||
|
||||
# ── scripts/zulip-monitor.sh: deliverable-text contract ─────────────
|
||||
|
||||
def test_zulip_monitor_deliverable_text_contract():
|
||||
"""Owned deliverable-text contract for scripts/zulip-monitor.sh.
|
||||
|
||||
Captain acceptance requires the shipped monitor to contain no Mumuni probe
|
||||
identifier and no 192.168.68.24 literal. Behavioral proof that the monitor
|
||||
never contacts that host and never emits a Mumuni notify lives in the
|
||||
sandbox tests below; this only pins the named text contract.
|
||||
"""
|
||||
text = ZULIP_MONITOR.read_text()
|
||||
assert "mumuni" not in text.lower()
|
||||
assert MUMUNI_IP not in text
|
||||
|
||||
|
||||
# ── scripts/zulip-monitor.sh: behavioral sandbox ─────────────────────
|
||||
|
||||
SSH_STUB = r"""#!/usr/bin/env bash
|
||||
# Stub ssh: record the target host, then answer by host + remote command.
|
||||
printf '%s\n' "$*" >> "$RECORD_DIR/ssh.calls"
|
||||
host=""
|
||||
for a in "$@"; do
|
||||
case "$a" in
|
||||
*@192.168.*) host="${a##*@}" ;;
|
||||
esac
|
||||
done
|
||||
printf '%s\n' "$host" >> "$RECORD_DIR/ssh.hosts"
|
||||
cmd="${*: -1}"
|
||||
case "$host" in
|
||||
192.168.68.15)
|
||||
case "$cmd" in
|
||||
*"systemctl is-active"*) printf '%s' "$TANKO_SVC" ;;
|
||||
*curl*) printf '%s' "$TANKO_HTTP" ;;
|
||||
esac ;;
|
||||
192.168.68.14)
|
||||
case "$cmd" in
|
||||
*agent.json*) printf '%s' "$AZ_A2A" ;;
|
||||
*"ps aux"*) printf '%s\n' "$AZ_PS" ;;
|
||||
esac ;;
|
||||
*)
|
||||
printf 'UNEXPECTED-SSH-HOST %s\n' "$host" >> "$RECORD_DIR/unexpected-ssh" ;;
|
||||
esac
|
||||
exit 0
|
||||
"""
|
||||
|
||||
CURL_STUB = r"""#!/usr/bin/env bash
|
||||
# Stub curl: serve the Abiba health fixture and the Zulip server 200, and
|
||||
# record every call (including notify) payloads.
|
||||
printf '%s\n' "$*" >> "$RECORD_DIR/curl.calls"
|
||||
case "$*" in
|
||||
*:9200/health*)
|
||||
case " $* " in
|
||||
*" -w "*) printf '%s' "$PI_HTTP" ;; # -w '%{http_code}' probe
|
||||
*) printf '%s' "$PI_BODY" ;; # body probe
|
||||
esac ;;
|
||||
*server_settings*)
|
||||
printf '%s' "$SERVER_HTTP" ;;
|
||||
esac
|
||||
exit 0
|
||||
"""
|
||||
|
||||
|
||||
def _write_exec(path: pathlib.Path, body: str) -> None:
|
||||
path.write_text(body)
|
||||
path.chmod(path.stat().st_mode
|
||||
| stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
|
||||
|
||||
|
||||
def _run_monitor(tmp_path, *, tanko_svc="active", tanko_http="200",
|
||||
az_a2a='{"name":"kagentz"}',
|
||||
az_ps="root 111 0.1 0.2 /opt/venv-a0/bin/python3 -u adapter.py"):
|
||||
"""Run the shipped monitor in a sandbox; return (proc, record_dir, log_path).
|
||||
|
||||
Only the LOG constant is rewritten (to keep the run inside the worktree).
|
||||
Everything else — legs, labels, notify logic — is the shipped script.
|
||||
"""
|
||||
sandbox = tmp_path / "sandbox"
|
||||
bindir = sandbox / "bin"
|
||||
record = sandbox / "record"
|
||||
bindir.mkdir(parents=True)
|
||||
record.mkdir()
|
||||
|
||||
_write_exec(bindir / "ssh", SSH_STUB)
|
||||
_write_exec(bindir / "curl", CURL_STUB)
|
||||
|
||||
source = ZULIP_MONITOR.read_text()
|
||||
log_line = 'LOG="/root/zulip-health-monitor.log"'
|
||||
assert log_line in source, "LOG constant moved — update the sandbox harness"
|
||||
log_path = sandbox / "zulip-health-monitor.log"
|
||||
script = sandbox / "zulip-monitor.sh"
|
||||
script.write_text(source.replace(log_line, f'LOG="{log_path}"'))
|
||||
|
||||
env = dict(os.environ)
|
||||
env.update({
|
||||
"PATH": f"{bindir}:{env['PATH']}",
|
||||
"RECORD_DIR": str(record),
|
||||
"TANKO_SVC": tanko_svc,
|
||||
"TANKO_HTTP": tanko_http,
|
||||
"AZ_A2A": az_a2a,
|
||||
"AZ_PS": az_ps,
|
||||
"PI_HTTP": "200",
|
||||
"PI_BODY": CONNECTED_FIXTURE.read_text(),
|
||||
"SERVER_HTTP": "200",
|
||||
})
|
||||
proc = subprocess.run(["bash", str(script)], cwd=sandbox, env=env,
|
||||
capture_output=True, text=True)
|
||||
return proc, record, log_path
|
||||
|
||||
|
||||
def test_healthy_run_is_quiet_and_never_reaches_mumuni(tmp_path):
|
||||
proc, record, log_path = _run_monitor(tmp_path)
|
||||
assert proc.returncode == 0, proc.stderr
|
||||
log = log_path.read_text()
|
||||
|
||||
# Every retained leg actually ran and passed.
|
||||
assert "Server: ✅ HTTP 200" in log
|
||||
assert "Abiba: ✅ Connected" in log
|
||||
assert "Tanko: ✅ service=active http=200" in log
|
||||
assert "kagentz: ✅ A2A alive" in log
|
||||
assert "kagentz: ✅ Adapter running" in log
|
||||
assert "Result: ✅ All healthy" in log
|
||||
|
||||
# A healthy run emits no notify at all — and certainly no Mumuni one.
|
||||
assert proc.stdout == ""
|
||||
assert "Mumuni" not in log
|
||||
assert "🔴" not in log
|
||||
|
||||
# Observed behavior: .24 is never resolved, only Tanko's vantage and the
|
||||
# Agent Zero host are contacted.
|
||||
hosts = record.joinpath("ssh.hosts").read_text().split()
|
||||
assert MUMUNI_IP not in hosts
|
||||
assert set(hosts) == {TANKO_VANTAGE, AGENT_ZERO_HOST}
|
||||
assert not record.joinpath("unexpected-ssh").exists()
|
||||
|
||||
|
||||
def test_failing_run_alerts_on_tanko_but_never_on_mumuni(tmp_path):
|
||||
# Failure path: exercises notify() end to end so "no Mumuni notify" is
|
||||
# proven on the alert path, not only on the quiet healthy path.
|
||||
proc, record, log_path = _run_monitor(tmp_path, tanko_svc="inactive",
|
||||
tanko_http="000")
|
||||
assert proc.returncode == 0, proc.stderr
|
||||
|
||||
alerts = proc.stdout
|
||||
assert "Tanko (DSH dsh-web) service state: inactive" in alerts
|
||||
assert "1 issue(s) found" in alerts
|
||||
|
||||
# No Mumuni text in stdout, the log, or any Zulip DM/stream payload.
|
||||
assert "Mumuni" not in alerts
|
||||
assert "Mumuni" not in log_path.read_text()
|
||||
assert MUMUNI_IP not in alerts + log_path.read_text()
|
||||
payloads = record.joinpath("curl.calls").read_text()
|
||||
assert "Mumuni" not in payloads
|
||||
assert MUMUNI_IP not in payloads
|
||||
|
||||
# The rest of the monitor still ran alongside the failing Tanko leg.
|
||||
log = log_path.read_text()
|
||||
assert "Abiba: ✅ Connected" in log
|
||||
assert "kagentz: ✅ A2A alive" in log
|
||||
assert "Result: 🔴 1 issue(s) found" in log
|
||||
|
||||
|
||||
# ── scripts/daily-infra-report.py: behavioral digest checks ──────────
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def daily():
|
||||
spec = importlib.util.spec_from_file_location("daily_infra_report", DAILY_REPORT)
|
||||
assert spec and spec.loader
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(module)
|
||||
return module
|
||||
|
||||
|
||||
DAILY_AGENTS = {
|
||||
"abiba": {
|
||||
"platform": "pi", "ct": 100, "ip": MUMUNI_IP,
|
||||
"zulip_connected": True, "zulip_processed": 5,
|
||||
"pm2_status": "online", "pm2_restarts": "0", "pm2_uptime": "1h",
|
||||
},
|
||||
"tanko": {
|
||||
"platform": "dsh", "ct": 112, "ip": "192.168.68.122",
|
||||
"gateway_state": "n/a (DSH)", "zulip_state": "connected",
|
||||
"telegram_state": "unknown", "gateway_pid": None, "updated_at": "",
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def _fabricated_report(agents):
|
||||
return {
|
||||
"nodes": {},
|
||||
"node_count": 1,
|
||||
"nodes_online": 1,
|
||||
"total_vms": 0,
|
||||
"running_vms": 0,
|
||||
"stopped_vms": [],
|
||||
"vms_by_node": {n: [] for n in
|
||||
["amdpve", "minipve", "storepve", "acerpve", "ocupve"]},
|
||||
"storage": [],
|
||||
"docker_vm": {"total": 0, "running": 0, "unhealthy": [],
|
||||
"containers": [], "reclaimable": "", "disk_used": "1%"},
|
||||
"docker_syslog": {"total": 0, "running": 0, "containers": []},
|
||||
"docker_netbird": {"total": 0, "running": 0, "containers": []},
|
||||
"endpoints": [],
|
||||
"litellm": {"checks": []},
|
||||
"nfs": [],
|
||||
"zulip_ext": {
|
||||
"connected": True, "queue_id": "queue", "last_error": None,
|
||||
"messages_processed": 0, "retry_count": 0, "pm2": {},
|
||||
"pm2_healthy": True, "bot_skipped_15min": 0, "finalized_1h": 0,
|
||||
"failed_finalize_1h": 0, "finalize_fail_pct": 0,
|
||||
"server_status": "200",
|
||||
},
|
||||
"agents": agents,
|
||||
}
|
||||
|
||||
|
||||
def _agent_status_card(html):
|
||||
start = html.index("🤖 Agent Status")
|
||||
end = html.index("💬 Zulip Extension")
|
||||
return html[start:end]
|
||||
|
||||
|
||||
def test_daily_report_renders_only_abiba_and_tanko_agents(daily):
|
||||
"""build_html() over a Mumuni-free agent set must render no Mumuni row and
|
||||
no Mumuni gateway-unknown issue, while abiba and tanko rows still render."""
|
||||
html = daily.build_html(_fabricated_report(dict(DAILY_AGENTS)))
|
||||
card = _agent_status_card(html)
|
||||
assert "mumuni" not in card.lower()
|
||||
assert "abiba" in card
|
||||
assert "tanko" in card
|
||||
assert "mumuni" not in html.lower()
|
||||
|
||||
|
||||
def test_daily_report_collect_never_probes_mumuni(monkeypatch, daily):
|
||||
"""collect() with ssh stubbed must add no mumuni agent and must never ssh
|
||||
its decommissioned .24 host."""
|
||||
probed = []
|
||||
|
||||
class _NoSubprocess:
|
||||
@staticmethod
|
||||
def check_output(*args, **kwargs):
|
||||
return b""
|
||||
|
||||
def fake_ssh(host, cmd):
|
||||
probed.append(host)
|
||||
return ""
|
||||
|
||||
monkeypatch.setattr(daily, "pve_get", lambda path: [])
|
||||
monkeypatch.setattr(daily, "ssh_jerome", lambda host, cmd: "")
|
||||
monkeypatch.setattr(daily, "ssh", fake_ssh)
|
||||
monkeypatch.setattr(daily, "http_get",
|
||||
lambda url, auth=None, timeout=10: "200")
|
||||
monkeypatch.setattr(daily, "http_get_body",
|
||||
lambda url, auth=None, timeout=10: "")
|
||||
monkeypatch.setattr(daily, "count_in_log", lambda *a, **k: 0)
|
||||
monkeypatch.setattr(daily, "subprocess", _NoSubprocess)
|
||||
|
||||
report = daily.collect()
|
||||
assert "mumuni" not in report["agents"]
|
||||
assert MUMUNI_IP not in probed
|
||||
|
||||
|
||||
# ── scripts/agent-health-check.py: roster pin ───────────────────────
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def ahc():
|
||||
spec = importlib.util.spec_from_file_location("agent_health_check_roster", AHC)
|
||||
assert spec and spec.loader
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(module)
|
||||
return module
|
||||
|
||||
|
||||
def test_agent_health_roster_has_no_mumuni_entry(ahc):
|
||||
assert "mumuni" not in ahc.AGENTS
|
||||
|
||||
|
||||
# ── zulip-health.prose.md: contract reconciliation ──────────────────
|
||||
|
||||
def test_health_contract_retires_mumuni_only_steps():
|
||||
text = HEALTH_CONTRACT.read_text()
|
||||
assert MUMUNI_IP not in text
|
||||
for step in ("**B4:", "**B5:", "**B6:"):
|
||||
assert step not in text
|
||||
|
||||
|
||||
def test_health_contract_states_mumuni_is_not_monitored_from_this_host():
|
||||
text = HEALTH_CONTRACT.read_text()
|
||||
assert "Mumuni is NOT monitored from this host" in text
|
||||
assert "monitored on her side" in text
|
||||
assert "her own container" in text
|
||||
|
||||
|
||||
def test_health_contract_keeps_tanko_agent_zero_and_bridge_steps():
|
||||
text = HEALTH_CONTRACT.read_text()
|
||||
for marker in ("**B1:", "**B2:", "**B3:", "Step 4: Platform C",
|
||||
"Step 2: Platform A", "Step 1: Zulip Server Liveness"):
|
||||
assert marker in text, marker
|
||||
@@ -1,466 +0,0 @@
|
||||
"""Regression tests for the 2026-09-09/10 probe-drift corrections.
|
||||
|
||||
WHY THIS FILE EXISTS: the monitoring contracts kept emitting false alarms from
|
||||
stale expectations rather than live faults.
|
||||
|
||||
* agent-health-check v3 reported 6 failures that were all stale expectations:
|
||||
abiba (pi-only since the harness purge) was tested as a Hermes host, koby
|
||||
(report-only per the captain's 2026-08-17 ruling) was counted as repairable,
|
||||
koby's CT 111 was probed on amdpve where it does not exist (it runs on
|
||||
storepve .6), and the wrapper infisical check had two bugs — it read only
|
||||
the first 20 lines, so koonimo's wrapper (which references /usr/bin/infisical
|
||||
past line 20) false-failed, and it treated koby's genuine no-infisical
|
||||
(~/.hermes/.env) wrapper as broken.
|
||||
* gpu-monitor emitted "DEGRADED — GPU-rtx3090 000, GPU-rtx5070 000" three
|
||||
times from probing bare port 80 on GPU hosts while :8080 answered 200.
|
||||
* infrastructure-monitoring probed CT 116 for the PVE API (no pveproxy ->
|
||||
000) instead of the five real cluster nodes, which answer 401 = alive.
|
||||
|
||||
These tests execute the health script (with SSH/vault stubbed) and the real
|
||||
provenance consumer (scripts/prose-lint.sh), and parse the contracts' executable
|
||||
check-health probe blocks into normalized probe sets. No live network, vault, or
|
||||
SSH access is required.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import importlib.util
|
||||
import json
|
||||
import os
|
||||
import pathlib
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
import textwrap
|
||||
|
||||
import pytest
|
||||
|
||||
ROOT = pathlib.Path(__file__).resolve().parents[1]
|
||||
AHC = ROOT / "scripts" / "agent-health-check.py"
|
||||
LINT = ROOT / "scripts" / "prose-lint.sh"
|
||||
GPU = ROOT / "gpu-monitor.prose.md"
|
||||
INFRA = ROOT / "infrastructure-monitoring.prose.md"
|
||||
|
||||
PVE_NODE_IPS = {
|
||||
"192.168.68.9",
|
||||
"192.168.68.5",
|
||||
"192.168.68.15",
|
||||
"192.168.68.6",
|
||||
"192.168.68.12",
|
||||
}
|
||||
|
||||
|
||||
@pytest.fixture(scope="module")
|
||||
def ahc():
|
||||
"""Import agent-health-check.py without live network/SSH side effects."""
|
||||
spec = importlib.util.spec_from_file_location("agent_health_check", AHC)
|
||||
assert spec and spec.loader
|
||||
module = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(module)
|
||||
return module
|
||||
|
||||
|
||||
# ── helpers: execute the health script with SSH/vault stubbed ─────────
|
||||
|
||||
def _run_main(ahc, monkeypatch, capsys, argv, ssh_result=None):
|
||||
ahc.FAIL.clear()
|
||||
ahc.REPORT_ONLY.clear()
|
||||
monkeypatch.setattr(ahc, "load_agent_keys", lambda: None)
|
||||
monkeypatch.setattr(ahc, "ssh", lambda *a, **k: ssh_result)
|
||||
monkeypatch.setattr(sys, "argv", ["agent-health-check.py", "--no-deploy", *argv])
|
||||
with pytest.raises(SystemExit) as exc:
|
||||
ahc.main()
|
||||
return exc.value.code, capsys.readouterr().out
|
||||
|
||||
|
||||
def _json_payload(out):
|
||||
for line in reversed(out.splitlines()):
|
||||
if line.startswith('{"timestamp"'):
|
||||
return json.loads(line)
|
||||
raise AssertionError(f"no JSON payload in output:\n{out}")
|
||||
|
||||
|
||||
# ── agent-health-check: stale-expectation legs ───────────────────────
|
||||
|
||||
def test_import_does_not_contact_vault(ahc):
|
||||
# Keys are loaded in main() via load_agent_keys(); importing must stay inert.
|
||||
assert callable(ahc.load_agent_keys)
|
||||
assert all(agent.get("key") is None for agent in ahc.AGENTS.values())
|
||||
|
||||
|
||||
def test_abiba_is_pi_only_runtime(ahc):
|
||||
# .24 has run pi-only since the harness purge: no Hermes gateway, config, or
|
||||
# wrapper. Probing those legs produced false failures.
|
||||
assert ahc.AGENTS["abiba"]["runtime"] == "pi"
|
||||
|
||||
|
||||
def test_koby_is_report_only(ahc):
|
||||
# Captain's 2026-08-17 ruling (Rule 17): detect and report, never repair.
|
||||
assert ahc.AGENTS["koby"]["report_only"] is True
|
||||
|
||||
|
||||
def test_koby_ct111_is_on_storepve(ahc):
|
||||
# Live-verified 2026-09-10: `pct status 111` = running on storepve (.6);
|
||||
# amdpve has no lxc/111.conf, which is what false-failed before.
|
||||
assert ahc.AGENTS["koby"]["pve"] == "storepve"
|
||||
|
||||
|
||||
def test_report_only_legs_never_count_as_failures(ahc):
|
||||
for agent, report_only in (("koby", True), ("koonimo", False), ("tanko", False)):
|
||||
ahc.FAIL.clear()
|
||||
ahc.REPORT_ONLY.clear()
|
||||
ahc._fail(f"probe:{agent}", agent)
|
||||
if report_only:
|
||||
assert ahc.FAIL == []
|
||||
assert ahc.REPORT_ONLY == [f"probe:{agent}"]
|
||||
else:
|
||||
assert ahc.FAIL == [f"probe:{agent}"]
|
||||
assert ahc.REPORT_ONLY == []
|
||||
ahc.FAIL.clear()
|
||||
ahc.REPORT_ONLY.clear()
|
||||
|
||||
|
||||
def test_failure_recording_accepts_agentless_keys(ahc):
|
||||
ahc.FAIL.clear()
|
||||
try:
|
||||
ahc._fail("gpu-no-port:gpu-rtx3090 (.8)")
|
||||
assert ahc.FAIL == ["gpu-no-port:gpu-rtx3090 (.8)"]
|
||||
finally:
|
||||
ahc.FAIL.clear()
|
||||
|
||||
|
||||
def test_json_reports_absolute_execution_provenance(ahc, monkeypatch, capsys):
|
||||
code, out = _run_main(ahc, monkeypatch, capsys, ["--json"])
|
||||
payload = _json_payload(out)
|
||||
assert payload["execution_path"] == os.path.abspath(str(AHC))
|
||||
assert payload["cwd"] == os.getcwd()
|
||||
assert code == 1 # stubbed SSH fails every leg, but provenance is still emitted
|
||||
|
||||
|
||||
def test_quiet_run_still_carries_provenance_on_the_alert_path(ahc, monkeypatch, capsys):
|
||||
# The cron runs --quiet; a failure report must still carry provenance. The
|
||||
# header line is suppressed in quiet mode, so the ALERT line is the carrier.
|
||||
code, out = _run_main(ahc, monkeypatch, capsys, ["--quiet"])
|
||||
assert code == 1
|
||||
assert "📍 executed from:" not in out
|
||||
alerts = [ln for ln in out.splitlines() if ln.startswith("ALERT agent-health:")]
|
||||
assert alerts, out
|
||||
assert f"script={os.path.abspath(str(AHC))}" in alerts[0]
|
||||
assert f"cwd={os.getcwd()}" in alerts[0]
|
||||
|
||||
|
||||
def test_quiet_healthy_run_emits_no_stdout(ahc, monkeypatch, capsys):
|
||||
# --quiet is documented as "only output on failure": a run with no fleet
|
||||
# failures must produce no stdout at all (the production cron runs --quiet).
|
||||
for name in ("check_keys", "check_gpu_ports", "check_agents", "check_ct_liveness",
|
||||
"check_config_integrity", "check_wrapper_integrity", "check_vault_secrets"):
|
||||
monkeypatch.setattr(ahc, name, lambda: None)
|
||||
code, out = _run_main(ahc, monkeypatch, capsys, ["--quiet"])
|
||||
assert code == 0
|
||||
assert out == ""
|
||||
|
||||
|
||||
def test_json_surfaces_report_only_findings_separately(ahc, monkeypatch, capsys):
|
||||
# Koby's down legs are reported but must not count as fleet failures; the
|
||||
# --json payload exposes them in their own array (item 1 + f8).
|
||||
_, out = _run_main(ahc, monkeypatch, capsys, ["--json"])
|
||||
payload = _json_payload(out)
|
||||
assert isinstance(payload["report_only"], list)
|
||||
assert any(key.startswith(("gateway-down:koby", "ct-unreachable:koby"))
|
||||
for key in payload["report_only"])
|
||||
assert not any("koby" in key for key in payload["failures"])
|
||||
|
||||
|
||||
# ── agent-health-check: wrapper infisical behavior (f3) ───────────────
|
||||
|
||||
def _stub_wrapper_ssh(ahc, monkeypatch, wrapper_body, test_x_result="OK", command_v="/usr/local/bin/infisical"):
|
||||
def fake_ssh(host, cmd, user="root"):
|
||||
if cmd.startswith("cat /root/.local/bin/hermes"):
|
||||
return wrapper_body
|
||||
if cmd.startswith("ls -la /root/.local/bin/hermes "):
|
||||
return "-rwxr-xr-x 1 root root 0 Jan 1 00:00 /root/.local/bin/hermes"
|
||||
if cmd.startswith("ls -la /root/.local/bin/hermes-real") or "venv/bin/hermes" in cmd:
|
||||
return "-rwxr-xr-x 1 root root 0 Jan 1 00:00 /root/.local/bin/hermes-real"
|
||||
if cmd.startswith("grep -c 'LITELLM_API_KEY'"):
|
||||
return "1"
|
||||
if cmd.startswith("test -x "):
|
||||
path = cmd[len("test -x "):].split()[0]
|
||||
if isinstance(test_x_result, dict):
|
||||
return test_x_result.get(path, "MISS")
|
||||
return test_x_result
|
||||
if cmd.startswith("command -v infisical"):
|
||||
return command_v
|
||||
return None
|
||||
|
||||
monkeypatch.setattr(ahc, "ssh", fake_ssh)
|
||||
monkeypatch.setattr(ahc, "AGENTS", {"koonimo": dict(ahc.AGENTS["koonimo"])})
|
||||
ahc.FAIL.clear()
|
||||
ahc.REPORT_ONLY.clear()
|
||||
|
||||
|
||||
def test_env_based_wrapper_without_infisical_is_not_failed(ahc, monkeypatch, capsys):
|
||||
_stub_wrapper_ssh(ahc, monkeypatch,
|
||||
"#!/bin/bash\nsource ~/.hermes/.env\nexec hermes-real \"$@\"\n")
|
||||
ahc.check_wrapper_integrity()
|
||||
out = capsys.readouterr().out
|
||||
assert ahc.FAIL == []
|
||||
assert "wrapper resolves creds without infisical" in out
|
||||
|
||||
|
||||
def test_dangling_absolute_infisical_path_is_failed(ahc, monkeypatch, capsys):
|
||||
# Wrapper hardcodes /usr/bin/infisical, which is absent, while PATH resolves
|
||||
# infisical to /usr/local/bin/infisical. The literal path must be verified,
|
||||
# not inferred from PATH resolution.
|
||||
_stub_wrapper_ssh(ahc, monkeypatch,
|
||||
"#!/bin/bash\n/usr/bin/infisical run -- hermes-real \"$@\"\n",
|
||||
test_x_result="MISS", command_v="/usr/local/bin/infisical")
|
||||
ahc.check_wrapper_integrity()
|
||||
assert "wrapper-infisical-path:koonimo" in ahc.FAIL
|
||||
|
||||
|
||||
def test_existing_absolute_infisical_path_passes(ahc, monkeypatch, capsys):
|
||||
_stub_wrapper_ssh(ahc, monkeypatch,
|
||||
"#!/bin/bash\n/usr/bin/infisical run -- hermes-real \"$@\"\n",
|
||||
test_x_result="OK")
|
||||
ahc.check_wrapper_integrity()
|
||||
out = capsys.readouterr().out
|
||||
assert ahc.FAIL == []
|
||||
assert "wrapper infisical path OK" in out
|
||||
|
||||
|
||||
def test_comment_mentioning_removed_infisical_path_is_not_failed(ahc, monkeypatch, capsys):
|
||||
# litellm-api-keys.prose.md documents `rm -f /usr/local/bin/infisical`; a
|
||||
# wrapper comment about that migration must not manufacture a dangling path
|
||||
# when the real invocation (/usr/bin/infisical) is present and executable.
|
||||
_stub_wrapper_ssh(ahc, monkeypatch,
|
||||
"#!/bin/bash\n# migrated from /usr/local/bin/infisical\n"
|
||||
"exec /usr/bin/infisical run -- hermes-real \"$@\"\n",
|
||||
test_x_result={"/usr/bin/infisical": "OK",
|
||||
"/usr/local/bin/infisical": "MISS"})
|
||||
ahc.check_wrapper_integrity()
|
||||
out = capsys.readouterr().out
|
||||
assert ahc.FAIL == []
|
||||
assert "wrapper infisical path OK" in out
|
||||
|
||||
|
||||
def test_comment_only_infisical_mention_does_not_reach_path_check(ahc, monkeypatch, capsys):
|
||||
# A comment-only mention of a removed infisical path on a healthy .env-based
|
||||
# wrapper is not an invocation: it must not fall through to the `command -v`
|
||||
# PATH check and false-FAIL `wrapper-no-infisical`.
|
||||
_stub_wrapper_ssh(ahc, monkeypatch,
|
||||
"#!/bin/bash\n# migrated from /usr/local/bin/infisical\n"
|
||||
"source ~/.hermes/.env\nexec hermes-real \"$@\"\n",
|
||||
test_x_result="MISS", command_v=None)
|
||||
ahc.check_wrapper_integrity()
|
||||
out = capsys.readouterr().out
|
||||
assert ahc.FAIL == []
|
||||
assert "wrapper resolves creds without infisical" in out
|
||||
|
||||
|
||||
# ── item 4: prose-lint enforces report provenance (real consumer) ─────
|
||||
|
||||
GOOD_CONTRACT = textwrap.dedent("""\
|
||||
---
|
||||
kind: function
|
||||
name: good
|
||||
description: fixture with provenance
|
||||
---
|
||||
|
||||
## Parameters
|
||||
|
||||
- x: y
|
||||
|
||||
## Returns
|
||||
|
||||
ok
|
||||
|
||||
### check-health
|
||||
|
||||
```bash
|
||||
pwd -P
|
||||
```
|
||||
|
||||
**Report format**: Begin with the absolute path the probe executed from.
|
||||
""")
|
||||
|
||||
DECOY_CONTRACT = textwrap.dedent("""\
|
||||
---
|
||||
kind: function
|
||||
name: decoy
|
||||
description: fixture with provenance only outside the report format
|
||||
---
|
||||
|
||||
## Parameters
|
||||
|
||||
- x: y
|
||||
|
||||
## Returns
|
||||
|
||||
ok
|
||||
|
||||
The absolute path of the config is /etc/foo.
|
||||
|
||||
### check-health
|
||||
|
||||
```bash
|
||||
true
|
||||
```
|
||||
|
||||
**Report format**: Summarize actual results from each probe.
|
||||
""")
|
||||
|
||||
MISSING_CONTRACT = textwrap.dedent("""\
|
||||
---
|
||||
kind: function
|
||||
name: missing
|
||||
description: check-health contract with no report format
|
||||
---
|
||||
|
||||
## Parameters
|
||||
|
||||
- x: y
|
||||
|
||||
## Returns
|
||||
|
||||
ok
|
||||
|
||||
### check-health
|
||||
|
||||
```bash
|
||||
pwd -P
|
||||
```
|
||||
""")
|
||||
|
||||
|
||||
def _run_lint(tmp_path, text, name):
|
||||
(tmp_path / name).write_text(text)
|
||||
return subprocess.run(["bash", str(LINT)], cwd=tmp_path,
|
||||
capture_output=True, text=True)
|
||||
|
||||
|
||||
def test_prose_lint_accepts_report_format_with_provenance(tmp_path):
|
||||
result = _run_lint(tmp_path, GOOD_CONTRACT, "good.prose.md")
|
||||
assert result.returncode == 0, result.stdout + result.stderr
|
||||
|
||||
|
||||
def test_prose_lint_rejects_report_format_without_provenance(tmp_path):
|
||||
result = _run_lint(tmp_path, DECOY_CONTRACT, "decoy.prose.md")
|
||||
assert result.returncode == 1, result.stdout
|
||||
assert "lacks execution provenance" in result.stdout
|
||||
|
||||
|
||||
def test_prose_lint_requires_report_format_on_check_health_contract(tmp_path):
|
||||
result = _run_lint(tmp_path, MISSING_CONTRACT, "missing.prose.md")
|
||||
assert result.returncode == 1, result.stdout
|
||||
assert "no **Report format** paragraph" in result.stdout
|
||||
|
||||
|
||||
# ── contracts: parse the executable check-health probe block ─────────
|
||||
|
||||
def _check_health_block(contract):
|
||||
"""Extract the bash probe block under ### check-health (the probe interface)."""
|
||||
text = contract.read_text()
|
||||
marker = "### check-health"
|
||||
assert marker in text, f"{contract.name} has no {marker}"
|
||||
after = text.split(marker, 1)[1]
|
||||
match = re.search(r"```bash\n(.*?)```", after, re.S)
|
||||
assert match, f"{contract.name} check-health has no bash probe block"
|
||||
return match.group(1)
|
||||
|
||||
|
||||
def _loop_nodes(block):
|
||||
nodes = []
|
||||
for line in block.splitlines():
|
||||
match = re.match(r"\s*for\s+\w+\s+in\s+(.+?);?\s*do\b", line)
|
||||
if match:
|
||||
nodes = match.group(1).split()
|
||||
return nodes
|
||||
|
||||
|
||||
def _record(url):
|
||||
"""Normalize a URL into a probe record: host, port, path, expected status."""
|
||||
match = re.match(r"https?://([^/\s\"')]+)(/[^\s\"')]*)?", url)
|
||||
assert match, f"unparseable probe URL: {url}"
|
||||
hostport = match.group(1)
|
||||
if "@" in hostport:
|
||||
hostport = hostport.split("@", 1)[1]
|
||||
if hostport.startswith("["):
|
||||
host, port = hostport[1:hostport.index("]")], None
|
||||
elif ":" in hostport:
|
||||
host, raw_port = hostport.rsplit(":", 1)
|
||||
port = int(raw_port) if raw_port.isdigit() else None
|
||||
else:
|
||||
host, port = hostport, None
|
||||
return {"host": host, "port": port, "path": match.group(2) or "/",
|
||||
"expected": None}
|
||||
|
||||
|
||||
def _probes(block):
|
||||
"""Parse the executable check-health bash block into a normalized probe model.
|
||||
|
||||
Comments are not probes; an `# Expected: <status>` comment annotates the
|
||||
preceding probe. URLs using the block's shell-loop variable `$node` are
|
||||
expanded over the loop's node list.
|
||||
"""
|
||||
loop_nodes = _loop_nodes(block)
|
||||
probes = []
|
||||
last = None
|
||||
for raw in block.splitlines():
|
||||
stripped = raw.strip()
|
||||
if stripped.startswith("#"):
|
||||
expected = re.search(r"Expected:\s*(\d{3})", stripped, re.I)
|
||||
if expected and last is not None:
|
||||
last["expected"] = int(expected.group(1))
|
||||
continue
|
||||
for url in re.findall(r"https?://[^\s\"')]+", raw):
|
||||
hosts = loop_nodes if "$node" in url else [None]
|
||||
for node in hosts:
|
||||
record = _record(url.replace("$node", node) if node else url)
|
||||
probes.append(record)
|
||||
last = record
|
||||
return probes
|
||||
|
||||
|
||||
def test_gpu_monitor_probes_every_gpu_health_on_8080():
|
||||
probes = _probes(_check_health_block(GPU))
|
||||
targets = {(p["host"], p["port"], p["path"]) for p in probes}
|
||||
assert ("192.168.68.8", 8080, "/health") in targets
|
||||
assert ("192.168.68.110", 8080, "/health") in targets
|
||||
|
||||
|
||||
def test_gpu_monitor_never_probes_bare_port_80_on_gpu_hosts():
|
||||
probes = _probes(_check_health_block(GPU))
|
||||
gpu_hosts = {"192.168.68.8", "192.168.68.110", "192.168.68.15"}
|
||||
offenders = [p for p in probes
|
||||
if p["host"] in gpu_hosts and p["port"] in (None, 80)]
|
||||
assert offenders == []
|
||||
|
||||
|
||||
def test_probe_model_flags_explicit_port_80_on_gpu_host():
|
||||
# Regression: a bare-port probe may be spelled with an explicit :80.
|
||||
block = ("curl -s -o /dev/null -w '%{http_code}' "
|
||||
"http://192.168.68.8:80/health\n")
|
||||
gpu_hosts = {"192.168.68.8", "192.168.68.110", "192.168.68.15"}
|
||||
offenders = [p for p in _probes(block)
|
||||
if p["host"] in gpu_hosts and p["port"] in (None, 80)]
|
||||
assert offenders and offenders[0]["port"] == 80
|
||||
|
||||
|
||||
def test_gpu_monitor_treats_router_301_as_alive():
|
||||
probes = _probes(_check_health_block(GPU))
|
||||
unified = [p for p in probes
|
||||
if p["host"] == "192.168.68.116" and p["path"] == "/health/unified"]
|
||||
assert unified, "router /health/unified probe missing"
|
||||
assert unified[0]["expected"] == 301
|
||||
|
||||
|
||||
def test_infra_monitoring_probes_every_real_pve_node():
|
||||
probes = _probes(_check_health_block(INFRA))
|
||||
pve = {(p["host"], p["port"], p["path"]) for p in probes if p["port"] == 8006}
|
||||
assert {host for host, _, _ in pve} == PVE_NODE_IPS
|
||||
assert {path for _, _, path in pve} == {"/api2/json/version"}
|
||||
|
||||
|
||||
def test_infra_monitoring_does_not_probe_ct116_for_pve_api():
|
||||
probes = _probes(_check_health_block(INFRA))
|
||||
assert not any(p["host"] == "192.168.68.116" and p["port"] == 8006
|
||||
for p in probes)
|
||||
@@ -1,211 +0,0 @@
|
||||
#!/bin/bash
|
||||
# tests/zulip-monitor-abiba.sh — regression test pinning the producer→consumer
|
||||
# contract between the pi Zulip extension's :9200/health payload and the Abiba
|
||||
# leg of scripts/zulip-monitor.sh.
|
||||
#
|
||||
# WHY THIS TEST EXISTS: 2026-09-09 live incident. The monitor parsed the health
|
||||
# payload at the WRONG nesting level (d.get('connected') at top level, while the
|
||||
# extension serves zulip.connected) so PI_CONNECTED was always False and every
|
||||
# monitor run restarted a healthy bot: pm2 showed restarts=8 with the process
|
||||
# created 2026-09-09T09:35:09Z, the monitor log recorded four ❌ Abiba verdicts
|
||||
# (04:23, 05:35, 06:55, 09:35 UTC) and zero ✅, while the Zulip server answered
|
||||
# HTTP 200 and the bot logged a clean connect plus continuing heartbeats. The
|
||||
# watchdog was the fault, not the connection. This test makes that class of
|
||||
# regression fail loudly instead of silently restarting healthy services.
|
||||
#
|
||||
# CONTRACT UNDER TEST (must hold for scripts/zulip-monitor.sh):
|
||||
# * Connection state is NESTED: zulip.connected (boolean) and zulip.last_error
|
||||
# live inside the `zulip` object. There is NO top-level `connected` and NO
|
||||
# retry counter anywhere in the payload (verified against the extension's
|
||||
# startHealthServer handler) — the old retry_count branch was dropped.
|
||||
# * zulip.connected=true -> log "✅ Connected", NO pm2 restart.
|
||||
# * zulip.connected=false -> alert, pm2 restart abiba-zulip.
|
||||
# * fetch error / non-2xx / empty body / unparseable body / missing or
|
||||
# non-boolean zulip.connected -> "⚠️ Probe failed" alert with a
|
||||
# "NOT restarting" label, NO pm2 restart. A parse miss must never kill a
|
||||
# healthy service.
|
||||
# * zulip.connected=true with last_error -> degraded 🟡 warning, no restart.
|
||||
#
|
||||
# HOW: the Abiba leg of the shipped script sits between the
|
||||
# `# -- abiba-leg-start` / `# -- abiba-leg-end` marker comments. This runner
|
||||
# extracts that block verbatim and executes it with a stubbed curl (fixture body
|
||||
# + HTTP code), recorded notify()/pm2 shims, and a temp $LOG. If the markers
|
||||
# disappear (fix reverted or renamed) extraction yields nothing and the suite
|
||||
# fails — the bug cannot return silently.
|
||||
#
|
||||
# Usage: bash tests/zulip-monitor-abiba.sh [path/to/zulip-monitor.sh]
|
||||
# Exit 0 iff every check passes.
|
||||
#
|
||||
# shellcheck disable=SC2034,SC2329,SC1090
|
||||
# LOG/ISSUES and the notify/pm2/curl stubs below are consumed at runtime by
|
||||
# the leg extracted between the marker comments and `source`d in each case;
|
||||
# the static analyzer cannot see across that dynamic source, so it flags them.
|
||||
set -uo pipefail
|
||||
|
||||
ROOT=$(cd "$(dirname "$0")/.." && pwd)
|
||||
SCRIPT=${1:-"$ROOT/scripts/zulip-monitor.sh"}
|
||||
FIXTURES="$ROOT/tests/fixtures"
|
||||
TMP=$(mktemp -d)
|
||||
trap 'rm -rf "$TMP"' EXIT
|
||||
|
||||
PASS=0
|
||||
FAIL=0
|
||||
ok() { PASS=$((PASS + 1)); printf ' \033[32m✔\033[0m %s\n' "$1"; }
|
||||
bad() { FAIL=$((FAIL + 1)); printf ' \033[31m✘\033[0m %s\n' "$1"; }
|
||||
|
||||
echo "== tests/zulip-monitor-abiba.sh — Abiba leg vs :9200/health producer contract =="
|
||||
echo "target script: $SCRIPT"
|
||||
|
||||
# --- structural guards -------------------------------------------------------
|
||||
if ! grep -q '^# -- abiba-leg-start' "$SCRIPT"; then
|
||||
echo "✘ FATAL: $SCRIPT has no '# -- abiba-leg-start' marker — the fix has been reverted or renamed."
|
||||
exit 1
|
||||
fi
|
||||
if ! grep -q '^# -- abiba-leg-end' "$SCRIPT"; then
|
||||
echo "✘ FATAL: $SCRIPT has no '# -- abiba-leg-end' marker."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
LEG="$TMP/leg.sh"
|
||||
awk '/^# -- abiba-leg-start/{f=1; next}
|
||||
/^# -- abiba-leg-end/{f=0; next}
|
||||
f' "$SCRIPT" > "$LEG"
|
||||
if [ ! -s "$LEG" ]; then
|
||||
echo "✘ FATAL: extracted Abiba leg is empty."
|
||||
exit 1
|
||||
fi
|
||||
echo "== structural =="
|
||||
if bash -n "$SCRIPT"; then ok "syntax: bash -n $SCRIPT"; else bad "syntax: bash -n $SCRIPT failed"; fi
|
||||
if bash -n "$LEG"; then ok "syntax: extracted leg parses (bash -n)"; else bad "syntax: extracted leg fails bash -n"; fi
|
||||
|
||||
# --- per-case harness ---------------------------------------------------------
|
||||
CURRENT_NAME=""
|
||||
CURRENT_DIR=""
|
||||
|
||||
# $1 case name, $2 http-code, $3 body (file path or literal)
|
||||
run_case() {
|
||||
local name="$1" http="$2" body_src="$3" body
|
||||
CURRENT_NAME="$name"
|
||||
CURRENT_DIR=$(mktemp -d "$TMP/case.XXXXXX")
|
||||
if [ -f "$body_src" ]; then
|
||||
body=$(cat "$body_src")
|
||||
else
|
||||
body="$body_src"
|
||||
fi
|
||||
(
|
||||
LOG="$CURRENT_DIR/log"; ISSUES=0
|
||||
notify() { printf 'ALERT [%s] %s\n' "$1" "$2" >> "$CURRENT_DIR/alerts"; }
|
||||
pm2() { printf 'PM2 %s\n' "$*" >> "$CURRENT_DIR/pm2"; }
|
||||
curl() {
|
||||
local url=""
|
||||
for a in "$@"; do case "$a" in http*) url="$a";; esac; done
|
||||
case "$url" in
|
||||
*:9200/health*)
|
||||
case " $* " in
|
||||
*"-w"*) printf '%s' "$http" ;; # -w '%{http_code}' code probe
|
||||
*) printf '%s' "$body" ;; # body probe
|
||||
esac ;;
|
||||
*)
|
||||
printf 'UNEXPECTED-CURL %s\n' "$*" >> "$CURRENT_DIR/unexpected-curl"
|
||||
return 7 ;;
|
||||
esac
|
||||
return 0
|
||||
}
|
||||
source "$LEG"
|
||||
)
|
||||
}
|
||||
|
||||
assert_log_has() {
|
||||
if grep -qF -- "$1" "$CURRENT_DIR/log"; then ok "$CURRENT_NAME — log has: $1"; else bad "$CURRENT_NAME — log MISSING: $1"; fi
|
||||
}
|
||||
assert_log_lacks() {
|
||||
if grep -qF -- "$1" "$CURRENT_DIR/log"; then bad "$CURRENT_NAME — log must NOT contain: $1"; else ok "$CURRENT_NAME — log correctly lacks: $1"; fi
|
||||
}
|
||||
assert_alert_has() {
|
||||
if grep -qF -- "$1" "$CURRENT_DIR/alerts"; then ok "$CURRENT_NAME — alert sent: $1"; else bad "$CURRENT_NAME — alert MISSING: $1"; fi
|
||||
}
|
||||
assert_alert_empty() {
|
||||
if [ ! -s "$CURRENT_DIR/alerts" ]; then ok "$CURRENT_NAME — no alert sent (quiet healthy path)"; else bad "$CURRENT_NAME — unexpected alert: $(cat "$CURRENT_DIR/alerts")"; fi
|
||||
}
|
||||
assert_pm2_restarted() {
|
||||
if grep -qF "PM2 restart abiba-zulip" "$CURRENT_DIR/pm2"; then ok "$CURRENT_NAME — pm2 restart abiba-zulip was called"; else bad "$CURRENT_NAME — expected pm2 restart abiba-zulip, pm2 log: $(cat "$CURRENT_DIR/pm2" 2>/dev/null)"; fi
|
||||
}
|
||||
assert_no_restart() {
|
||||
if [ ! -s "$CURRENT_DIR/pm2" ]; then ok "$CURRENT_NAME — NO pm2 restart (fail-safe holds)"; else bad "$CURRENT_NAME — pm2 was called but must NOT be: $(cat "$CURRENT_DIR/pm2")"; fi
|
||||
}
|
||||
assert_no_unexpected_curl() {
|
||||
if [ ! -s "$CURRENT_DIR/unexpected-curl" ]; then ok "$CURRENT_NAME — only :9200/health was probed"; else bad "$CURRENT_NAME — unexpected curl: $(cat "$CURRENT_DIR/unexpected-curl")"; fi
|
||||
}
|
||||
|
||||
# --- case 1: real payload shape, zulip.connected=true -> healthy, no restart --
|
||||
echo "== case 1: connected (real producer payload: nested zulip.connected=true) =="
|
||||
run_case "connected" 200 "$FIXTURES/zulip-health-connected.json"
|
||||
assert_log_has "Abiba: ✅ Connected (processed=0)"
|
||||
assert_log_lacks "Disconnected"
|
||||
assert_alert_empty
|
||||
assert_no_restart
|
||||
assert_no_unexpected_curl
|
||||
|
||||
# --- case 2: zulip.connected=false -> disconnected, restart -------------------
|
||||
echo "== case 2: disconnected (nested zulip.connected=false triggers restart) =="
|
||||
run_case "disconnected" 200 "$FIXTURES/zulip-health-disconnected.json"
|
||||
assert_log_has "Abiba: ❌ Disconnected — restarted"
|
||||
assert_alert_has "DISCONNECTED — restarting"
|
||||
assert_pm2_restarted
|
||||
assert_no_unexpected_curl
|
||||
|
||||
# --- cases 3-9: probe failures must alert and MUST NOT restart ----------------
|
||||
echo "== probe-failure cases: alert 'NOT restarting', zero pm2 restarts =="
|
||||
|
||||
run_case "empty body" 200 ""
|
||||
assert_log_has "Abiba: ⚠️ Probe failed"
|
||||
assert_log_lacks "❌ Disconnected"
|
||||
assert_alert_has "NOT restarting"
|
||||
assert_no_restart
|
||||
|
||||
run_case "garbage body" 200 '{not valid json!!'
|
||||
assert_log_has "Abiba: ⚠️ Probe failed"
|
||||
assert_alert_has "NOT restarting"
|
||||
assert_no_restart
|
||||
|
||||
run_case "missing zulip key" 200 '{"status":"ok","platform":"pi","agent":"abiba"}'
|
||||
assert_log_has "Probe failed"
|
||||
assert_alert_has "NOT restarting"
|
||||
assert_no_restart
|
||||
|
||||
run_case "zulip without connected" 200 '{"status":"ok","zulip":{"last_error":null}}'
|
||||
assert_log_has "Probe failed"
|
||||
assert_alert_has "NOT restarting"
|
||||
assert_no_restart
|
||||
|
||||
run_case "non-boolean connected" 200 '{"status":"ok","zulip":{"connected":"true"}}'
|
||||
assert_log_has "Probe failed"
|
||||
assert_alert_has "NOT restarting"
|
||||
assert_no_restart
|
||||
|
||||
run_case "fetch failure http 000" 000 ""
|
||||
assert_log_has "Probe failed"
|
||||
assert_alert_has "NOT restarting"
|
||||
assert_no_restart
|
||||
|
||||
run_case "non-2xx http 500" 500 '{"error":"boom"}'
|
||||
assert_log_has "Probe failed"
|
||||
assert_alert_has "NOT restarting"
|
||||
assert_no_restart
|
||||
|
||||
# --- case 10: connected but last_error set -> degraded 🟡, no restart ---------
|
||||
echo "== case 10: degraded (connected=true but last_error set) warns, no restart =="
|
||||
run_case "degraded" 200 '{"status":"ok","zulip":{"connected":true,"last_error":"transient queue hiccup","messages_processed":3}}'
|
||||
assert_log_has "Abiba: 🟡 Error: transient queue hiccup"
|
||||
assert_log_lacks "❌ Disconnected"
|
||||
assert_no_restart
|
||||
|
||||
# --- summary -------------------------------------------------------------------
|
||||
echo ""
|
||||
if [ "$FAIL" -eq 0 ]; then
|
||||
echo "✅ ALL CHECKS PASSED ($PASS/$PASS) — tests/zulip-monitor-abiba.sh"
|
||||
exit 0
|
||||
else
|
||||
echo "❌ $FAIL CHECK(S) FAILED ($PASS passed) — tests/zulip-monitor-abiba.sh"
|
||||
exit 1
|
||||
fi
|
||||
@@ -79,7 +79,7 @@ description: >
|
||||
`messages_processed` stalls.
|
||||
- **Root cause**: Agent's model config (`models.json` or `settings.json`) references a
|
||||
model ID that doesn't exist in LiteLLM's authorized model list. Example: `qwen3.6-35B-A3B`
|
||||
configured but LiteLLM only exposes `strix-moe` (alias for qwen3.6-35B-udq4) under that key. pi's session
|
||||
configured but LiteLLM only exposes `ornith-1.0-35b` under that key. pi's session
|
||||
workers emit 403 on first prompt, then never recover because the error doesn't trigger
|
||||
`agent_end` — worker stays `busy` and all subsequent messages pile up in the steer queue.
|
||||
- **Detection**: Compare `~/.pi/agent/models.json` model IDs against `curl -H "Authorization: Bearer <KEY>" http://192.168.68.116/v1/models` output. A stuck worker shows
|
||||
@@ -88,7 +88,7 @@ description: >
|
||||
(2) Set `defaultModel` to `syslog-auto` (safe routing model). (3) Delete stale session
|
||||
JSONL files from `~/.pi/agent/sessions/zulip/`. (4) Restart PM2 process.
|
||||
- **Prevention**: Use `syslog-auto` as default model for all agents — it handles model
|
||||
routing and fallback automatically. Direct model IDs (`strix-moe`, etc.) should
|
||||
routing and fallback automatically. Direct model IDs (`ornith-1.0-35b`, etc.) should
|
||||
only be used when explicitly requested. Validate model IDs at agent setup time.
|
||||
- **Applies to**: pi extension (Tdunna CT111, fixed 2026-07-08), any agent using `syslog-harness` provider
|
||||
|
||||
|
||||
+36
-73
@@ -1,34 +1,22 @@
|
||||
---
|
||||
kind: responsibility
|
||||
name: zulip-health
|
||||
description: Multi-platform health monitor for the Zulip messaging mesh spanning Platform A (pi/Abiba Zulip bridge), Platform B (Tanko on DSH), and Platform C (Agent Zero Docker). Verifies bot registration, DM delivery, and cross-platform connectivity. Mumuni is no longer monitored from this host — she runs on her own container (kagentz CT 105 on minipve, .14) and is monitored on her side.
|
||||
description: Multi-platform health monitor for the Zulip messaging mesh spanning Platform A (Agent Zero Docker), Platform B (Hermes agents Tanko/Mumuni), and the Zulip bridge. Verifies bot registration, DM delivery, and cross-platform connectivity.
|
||||
title: Zulip Mesh Health Monitor — Multi-Platform
|
||||
version: 3.1.0
|
||||
version: 3.0.0
|
||||
runtime_contract: 2
|
||||
agent: abiba
|
||||
report_only_agents:
|
||||
- koby # ⛔ KOBY IS NEVER REPAIRED (Rule 17, 2026-08-17) — detect + report, never fix on .129
|
||||
---
|
||||
|
||||
# Zulip Mesh Health Monitor
|
||||
|
||||
Monitors the Zulip-connected agents under this host's operational control (pi,
|
||||
DSH, Agent Zero). Runs every 15 minutes in the background. Also triggers on
|
||||
session start.
|
||||
|
||||
> **Mumuni is NOT monitored from this host (captain ruling 2026-09-10).** She
|
||||
> moved off this host onto her own container — kagentz CT 105 on minipve
|
||||
> (192.168.68.14), running a dedicated `hermes` user — and is monitored on her
|
||||
> side. No step in this contract, and no leg of `scripts/zulip-monitor.sh`, may
|
||||
> ssh to her old deployment, read her `~/.hermes/gateway_state.json`, or alert on
|
||||
> her state. The former Platform-B-for-Mumuni steps (gateway process, heartbeat,
|
||||
> response delivery) are retired: they always read "unknown" against the
|
||||
> decommissioned deployment and produced a false 🔴 alert on every run.
|
||||
Monitors ALL Zulip-connected agents across three platforms (pi, Hermes, Agent Zero).
|
||||
Runs every 15 minutes in the background. Also triggers on session start.
|
||||
|
||||
## Requires
|
||||
|
||||
- **Zulip API key** for `abiba-bot@chat.sysloggh.net` in `$ZULIP_API_KEY`
|
||||
- **SSH access** to amdpve (192.168.68.15) for Tanko — CT 112 reached via `pct exec` (direct SSH to .122 is not a dependency of this contract: per-worker key availability varies); and the Agent Zero Docker host (192.168.68.14)
|
||||
- **SSH access** to Tanko (192.168.68.122), Mumuni (192.168.68.123), and Agent Zero Docker host (192.168.68.14)
|
||||
- **PM2** on localhost for pi process management
|
||||
- **Network access** to `chat.sysloggh.net`, `localhost:9200`
|
||||
- **Write access** to `/root/zulip-health-monitor.log` and `/tmp/zulip-monitor-debounce`
|
||||
@@ -57,9 +45,11 @@ session start.
|
||||
"severity": "healthy"
|
||||
},
|
||||
"tanko": {
|
||||
"platform": "dsh",
|
||||
"service_state": "active",
|
||||
"http_status": 200,
|
||||
"platform": "hermes",
|
||||
"zulip_state": "connected",
|
||||
"heartbeat_age_seconds": 45,
|
||||
"gateway_pid": 1234,
|
||||
"edit_fail_rate_pct": 0,
|
||||
"severity": "healthy"
|
||||
}
|
||||
}
|
||||
@@ -91,13 +81,13 @@ Log as "unreachable" — don't treat as critical unless it persists for 3+ conse
|
||||
## Streaming Support (2026-07-05)
|
||||
|
||||
Zulip agents now support progressive message editing during agent generation.
|
||||
When a Zulip agent under this monitor's scope (Tanko on DSH) processes a message, the response is
|
||||
When a Hermes agent (Tanko, Mumuni) processes a message, the response is
|
||||
streamed in real-time via Zulip's `PATCH /api/v1/messages/{id}` API:
|
||||
|
||||
- Adapter implements `edit_message()` using `_api_patch()` helper
|
||||
- Gateway stream consumer progressively edits the Zulip message
|
||||
- User sees real-time agent thinking instead of waiting for full response
|
||||
- Verified: Tanko (CT 112) has streaming active; Mumuni's (kagentz CT 105) is verified on her own host, not from here
|
||||
- Verified: Tanko (CT 112) and Mumuni (CT 114) both have streaming active
|
||||
|
||||
### Verification
|
||||
```bash
|
||||
@@ -192,85 +182,60 @@ grep -a "Finalized\|Failed to finalize" /root/.pm2/logs/abiba-zulip-out.log | ta
|
||||
| `last_error` set | Log and monitor |
|
||||
| Crash loop >10/h | Alert user |
|
||||
|
||||
### Step 3: Platform B — Hermes (Tanko .122, Mumuni .123)
|
||||
|
||||
### Step 3: Platform B — Tanko (DSH on amdpve CT 112)
|
||||
|
||||
Mumuni is out of scope for this host (see the note above): she runs on her own
|
||||
container and is monitored on her side.
|
||||
|
||||
Tanko runs on DSH (DeepSeek Harness) — it no longer runs a Hermes gateway, so
|
||||
there is no `~/.hermes/gateway_state.json` on CT 112. Tanko's Zulip gateway runs
|
||||
as the `dsh-web` systemd unit inside **CT 112**, which resides on the **amdpve**
|
||||
PVE host (**192.168.68.15**). Direct SSH to 192.168.68.122 is not a dependency
|
||||
of this contract — per-worker key availability varies — so CT 112 probes run
|
||||
from the amdpve vantage via `pct exec`:
|
||||
**B1: Gateway State**
|
||||
|
||||
```bash
|
||||
ssh root@192.168.68.15 "pct exec 112 -- <command>"
|
||||
ssh root@192.168.68.122 "cat ~/.hermes/gateway_state.json"
|
||||
ssh root@192.168.68.123 "cat ~/.hermes/gateway_state.json"
|
||||
```
|
||||
|
||||
> **By design (verified 2026-09-08):** the `dsh-web` gateway binds
|
||||
> `127.0.0.1:3080` **loopback-only**. A remote probe against
|
||||
> `192.168.68.122:3080` gets connection-refused — that is EXPECTED, NOT a fault,
|
||||
> and must never be raised as Tanko down. Only loopback probes from inside
|
||||
> CT 112 (or the public-URL fallback below) are valid health signals.
|
||||
Check `platforms.zulip.state`: `connected` ✅ | `disconnected` ❌ | `error` ❌ | missing → not installed.
|
||||
|
||||
**B1: Gateway Service State (Tanko)**
|
||||
**B2: Agent Process**
|
||||
|
||||
```bash
|
||||
ssh root@192.168.68.15 "pct exec 112 -- systemctl is-active dsh-web"
|
||||
ssh root@<CT> "ps aux | grep 'gateway run' | grep -v grep"
|
||||
```
|
||||
|
||||
Expected: `active`. Anything else → gateway service down → apply the Tanko heal
|
||||
(restart via DSH service, Platform B Actions table below).
|
||||
Gateway PID should exist with uptime > 60s.
|
||||
|
||||
**B2: Gateway HTTP Liveness (Tanko — loopback-only :3080)**
|
||||
**B3: Heartbeat Verification**
|
||||
|
||||
```bash
|
||||
ssh root@192.168.68.15 "pct exec 112 -- curl -s --connect-timeout 5 --max-time 10 -o /dev/null -w '%{http_code}' http://127.0.0.1:3080/"
|
||||
ssh root@<CT> "grep Heartbeat ~/.hermes/logs/agent.log | tail -3"
|
||||
```
|
||||
|
||||
Alive = **ANY** HTTP status response from the endpoint — the expected set is
|
||||
`200`/`301`/`302`/`307`/`308`/`401`/`403` (the gateway UI is token-gated and
|
||||
legitimately answers with redirects/auth-challenges, so never require a bare
|
||||
`200`), and any other status, including `404`/`5xx`, also counts alive: a
|
||||
process answering `503` is running and self-heal must NOT restart-loop it.
|
||||
Down = connection refused (`000`) or timeout only. Statuses outside the
|
||||
expected set are logged/reported as a warning — reported, never healed on.
|
||||
Expected: recent heartbeat (within 5 min), `polls=N` incrementing.
|
||||
Silence > 300s → warning. Silence > 600s → critical.
|
||||
|
||||
**B3: Public-URL Fallback Probe (Tanko — for nodes without pct/ssh access to amdpve)**
|
||||
**B4: Response Delivery**
|
||||
|
||||
```bash
|
||||
curl -s --connect-timeout 10 --max-time 15 -o /dev/null -w '%{http_code}' https://tankodhs.sysloggh.net/
|
||||
ssh root@<CT> "grep -E 'Finalized|Failed to finalize|Replied to' ~/.hermes/logs/agent.log | tail -10"
|
||||
```
|
||||
|
||||
Fallback only — used when the monitoring node has no pct/SSH path to amdpve.
|
||||
Alive = **ANY** HTTP status response from the endpoint — healthy signals are
|
||||
`302` (authentik proxy-auth redirect) and `401` (auth-gated), and any other
|
||||
status, including `404`/`5xx`, also counts alive: the endpoint is up and
|
||||
answering and must NOT be restart-looped. Down = connection refused (`000`) or
|
||||
timeout only. Never expect a bare `200` — the public URL terminates in the
|
||||
token-gated authentik chain. Statuses outside the healthy set are
|
||||
logged/reported as a warning — reported, never healed on.
|
||||
> 50% fail rate → critical.
|
||||
|
||||
**Platform B Actions**
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| `dsh-web` service not `active` | Restart Tanko via DSH service |
|
||||
| HTTP `:3080` connection refused/timeout (`000`) | Same as above |
|
||||
| HTTP status outside the expected set | Log/report as a warning — reported, never healed on |
|
||||
| `zulip.state != "connected"` | `ssh root@<CT> "pkill -f 'gateway run'; sleep 2; hermes gateway restart"` |
|
||||
| No heartbeat in 10min | Same as above |
|
||||
| `Failed to finalize` > 50% | Check PATCH API, Zulip server |
|
||||
| Response empty/short | Check A2A endpoint / LiteLLM model |
|
||||
|
||||
### Step 4: Platform C — Agent Zero (kagentz, CT 105 via Docker host .14)
|
||||
|
||||
**C1: A2A Server Health**
|
||||
|
||||
```bash
|
||||
# A2A server is on :50080 (not :8001) and is auth-gated (401 expected for unauthenticated)
|
||||
ssh root@192.168.68.14 "curl -s --connect-timeout 5 -o /dev/null -w '%{http_code}' http://127.0.0.1:50080/a2a/"
|
||||
ssh root@192.168.68.14 "docker exec agent-zero curl -s --connect-timeout 5 http://127.0.0.1:8001/.well-known/agent.json"
|
||||
```
|
||||
|
||||
Expected: `401` (auth-gated, A2A server is up and responding) or `200` (if no auth required). Connection refused (000) → A2A server down.
|
||||
Expected: `{"name":"kagentz",...}`. Connection refused → A2A server down.
|
||||
|
||||
**C2: Adapter Process**
|
||||
|
||||
@@ -291,14 +256,12 @@ Check: `processed=N` incrementing, `silence < 600s`, `reconnects` ≈ 0.
|
||||
**C4: A2A Response Verification**
|
||||
|
||||
```bash
|
||||
# A2A server is on :50080 (not :8001) and is auth-gated (401 expected for unauthenticated)
|
||||
ssh root@192.168.68.14 "curl -s -X POST http://127.0.0.1:50080/a2a \
|
||||
ssh root@192.168.68.14 "docker exec agent-zero curl -s -X POST http://127.0.0.1:8001/a2a \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Authorization: Bearer $LITELLM_KEY' \
|
||||
-d '{\"jsonrpc\":\"2.0\",\"method\":\"tasks/send\",\"params\":{\"message\":{\"role\":\"user\",\"parts\":[{\"text\":\"ping\"}]}},\"id\":1}'"
|
||||
```
|
||||
|
||||
Expected: task ID with "working" status. Poll for completion with `tasks/get`. If 401, check LITELLM_KEY is set.
|
||||
Expected: task ID with "working" status. Poll for completion with `tasks/get`.
|
||||
|
||||
**Platform C Actions**
|
||||
|
||||
@@ -315,7 +278,7 @@ Expected: task ID with "working" status. Poll for completion with `tasks/get`. I
|
||||
|
||||
Check each agent's log for excessive bot-to-bot chatter:
|
||||
- Abiba: `Skipped.*bot msgs` count
|
||||
- Tanko: Repeated DM exchanges between bots
|
||||
- Tanko/Mumuni: Repeated DM exchanges between bots
|
||||
- kagentz: Adapter log for bot DMs being processed
|
||||
|
||||
If any bot processes >50 bot-originated messages in 15min → warning.
|
||||
|
||||
@@ -10,7 +10,7 @@ description: >
|
||||
|
||||
> **⚠️ RETIRED** — The pi Zulip extension (`~/.pi/agent/extensions/zulip/`) and
|
||||
> PM2 process (`abiba-zulip`) have been decommissioned. All mention/reliability
|
||||
> monitoring now happens through Telegram. Agents (Mumuni on Hermes, Tanko on DSH) and
|
||||
> monitoring now happens through Telegram. Hermes agents (Tanko, Mumuni) and
|
||||
> Agent Zero (kagentz) continue to use Zulip.
|
||||
|
||||
## Maintains
|
||||
|
||||
@@ -1,476 +0,0 @@
|
||||
---
|
||||
kind: responsibility
|
||||
name: zulip-resilience-v3
|
||||
description: >
|
||||
Rewrite the pi Zulip gateway with production-grade resilience patterns drawn from
|
||||
Zulip's own event system docs (queue lifecycle, heartbeat monitoring, BAD_EVENT_QUEUE_ID
|
||||
handling, idle_queue_timeout) and battle-tested Node.js resilience patterns
|
||||
(circuit breaker, exponential backoff with jitter, bulkhead isolation, supervisor watchdog).
|
||||
replaces: zulip-self-heal (retired)
|
||||
agent: abiba
|
||||
triggers:
|
||||
- "/zulip self-heal v3"
|
||||
- "zulip stopped responding"
|
||||
- "PM2 abiba-zulip crashed"
|
||||
---
|
||||
|
||||
# Zulip Gateway v3 — Production Resilience
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
The current v2 gateway (`/root/.pi/agent/extensions/zulip/index.js`) has three structural
|
||||
weaknesses that cause repeated deaths:
|
||||
|
||||
1. **No crash recovery** — uncaught errors kill the Node process, PM2 exhausts max_restarts
|
||||
2. **No circuit breaker** — 502/fetch-failed errors escalate to process death with no fallback
|
||||
3. **No queue lifecycle management** — doesn't use Zulip's documented heartbeat protocol or
|
||||
idle_queue_timeout, so BAD_EVENT_QUEUE_ID errors cascade into crashes
|
||||
|
||||
The v3 rewrite addresses all three, following patterns from:
|
||||
|
||||
- [Zulip Events System docs](https://zulip.readthedocs.io/en/11.6/subsystems/events-system.html) —
|
||||
queue registration, heartbeat, BAD_EVENT_QUEUE_ID recovery, call_on_each_event loop
|
||||
- [Zulip API: Get Events](https://zulip.com/api/get-events) — long-poll timeout, dont_block, event ack
|
||||
- [Circuit Breaker & Retry Patterns in Node.js 2026](https://1xapi.com/blog/resilient-api-circuit-breaker-bulkhead-retry-nodejs-2026) —
|
||||
Opossum-based circuit breaker with fallback, retry with jitter, bulkhead isolation
|
||||
|
||||
---
|
||||
|
||||
## Maintains
|
||||
|
||||
- `zulip-gateway`: { status: "healthy" | "degraded" | "down" }
|
||||
- `circuit-breaker`: { state: "CLOSED" | "OPEN" | "HALF_OPEN", failures, successes }
|
||||
- `queue-lifecycle`: { queue_id, last_event_id, idle_timeout, heartbeat_age }
|
||||
- `workers`: { count, busy, idle, stuck }
|
||||
- `supervisor`: { pid, last_check, health_failures }
|
||||
|
||||
---
|
||||
|
||||
## Detection Rules
|
||||
|
||||
### Rule 1: Queue Expired (BAD_EVENT_QUEUE_ID)
|
||||
- **Detect**: Events API returns error with BAD_EVENT_QUEUE_ID in body
|
||||
- **Fix**: Call `POST /register` to create new queue, update queue_id and last_event_id
|
||||
- **Debounce**: If 3 re-registrations fail within 60s, escalate (server may be down)
|
||||
- **Ref**: Zulip docs: "Your software will need to handle that error condition by re-initializing itself"
|
||||
|
||||
### Rule 2: Network Degradation (502/ECONNREFUSED/fetch failed)
|
||||
- **Detect**: Events API returns 502 or network error
|
||||
- **Circuit breaker**: Track failure rate over 10s rolling window
|
||||
- CLOSED → OPEN: 50% failure rate with ≥5 requests
|
||||
- OPEN → HALF_OPEN: After 30s reset timeout
|
||||
- HALF_OPEN → CLOSED: Probe succeeds
|
||||
- HALF_OPEN → OPEN: Probe fails
|
||||
- **While OPEN**: Log errors, skip events, notify user via DM: "⚠️ Zulip connection degraded — will retry in 30s"
|
||||
|
||||
### Rule 3: Long-Poll Timeout (natural)
|
||||
- **Detect**: Events API response takes > `event_queue_longpoll_timeout_seconds`
|
||||
- **Not an error**: Server sends heartbeat events when no real events. Simply re-poll.
|
||||
|
||||
### Rule 4: Worker Busy Timeout (>5 min)
|
||||
- **Detect**: Worker `busySince` exceeds 5 minutes
|
||||
- **Fix**: SIGKILL worker, send error DM, clean up pending replies
|
||||
|
||||
### Rule 5: Process Crash (uncaught)
|
||||
- **Detect**: `uncaughtException` / `unhandledRejection` fires
|
||||
- **Fix**: Log → clear poll timer → attempt reconnect with backoff → if reconnect fails 3x, exit(1) and let PM2 restart
|
||||
|
||||
### Rule 6: Supervisor Detects Router Stall
|
||||
- **Detect**: External supervisor (`zulip-watchdog`) polls `/health` every 30s. If 3 consecutive failures:
|
||||
- **Fix**: `pm2 restart abiba-zulip` gracefully (SIGTERM, drain workers, restart)
|
||||
|
||||
---
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 1: Rewrite Router Core (circuit-breaker + queue lifecycle)
|
||||
|
||||
Replace the poll loop in index.js with a resilience-first event loop:
|
||||
|
||||
```js
|
||||
// Queue lifecycle (Zulip docs pattern)
|
||||
async function createOrRefreshQueue() {
|
||||
// POST /register with event_types=["message"]
|
||||
// Store: queueId, lastEventId, eventQueueLongpollTimeoutSeconds
|
||||
// NEW: pass idle_queue_timeout parameter (Zulip 12.0+)
|
||||
}
|
||||
|
||||
// Circuit breaker (Opossum pattern, implemented inline to avoid dependency)
|
||||
class ZulipCircuitBreaker {
|
||||
constructor({ failureThreshold=0.5, resetTimeout=30000, volumeThreshold=5, windowMs=10000 }) {
|
||||
this.state = "CLOSED"; // CLOSED | OPEN | HALF_OPEN
|
||||
this.failures = 0;
|
||||
this.successes = 0;
|
||||
this.totalRequests = 0;
|
||||
this.lastFailureTime = null;
|
||||
this.openedAt = null;
|
||||
this.failureThreshold = failureThreshold;
|
||||
this.resetTimeout = resetTimeout;
|
||||
this.volumeThreshold = volumeThreshold;
|
||||
this.windowMs = windowMs;
|
||||
}
|
||||
|
||||
async fire(fn) {
|
||||
if (this.state === "OPEN") {
|
||||
if (Date.now() - this.openedAt > this.resetTimeout) {
|
||||
this.state = "HALF_OPEN";
|
||||
} else {
|
||||
throw new CircuitOpenError("Circuit is OPEN");
|
||||
}
|
||||
}
|
||||
try {
|
||||
const result = await fn();
|
||||
this.onSuccess();
|
||||
return result;
|
||||
} catch (err) {
|
||||
this.onFailure();
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
onSuccess() {
|
||||
this.successes++;
|
||||
this.totalRequests++;
|
||||
if (this.state === "HALF_OPEN") {
|
||||
this.state = "CLOSED";
|
||||
this.failures = 0;
|
||||
}
|
||||
// Reset counters periodically
|
||||
if (this.totalRequests > this.volumeThreshold * 2) {
|
||||
this.failures = Math.floor(this.failures / 2);
|
||||
this.successes = Math.floor(this.successes / 2);
|
||||
this.totalRequests = Math.floor(this.totalRequests / 2);
|
||||
}
|
||||
}
|
||||
|
||||
onFailure() {
|
||||
this.failures++;
|
||||
this.totalRequests++;
|
||||
this.lastFailureTime = Date.now();
|
||||
if (this.totalRequests >= this.volumeThreshold &&
|
||||
this.failures / this.totalRequests >= this.failureThreshold) {
|
||||
if (this.state !== "OPEN") {
|
||||
this.state = "OPEN";
|
||||
this.openedAt = Date.now();
|
||||
console.error(`[zulip-ext] CIRCUIT BREAKER OPEN — ${this.failures}/${this.totalRequests} failures`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Retry with exponential backoff + jitter (from resilience patterns)
|
||||
async function withRetry(fn, { maxAttempts=3, baseDelay=200, maxDelay=10000, shouldRetry=()=>true }={}) {
|
||||
let lastError;
|
||||
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
|
||||
try {
|
||||
return await fn();
|
||||
} catch (err) {
|
||||
lastError = err;
|
||||
if (attempt === maxAttempts || !shouldRetry(err)) throw err;
|
||||
const delay = Math.min(baseDelay * Math.pow(2, attempt - 1), maxDelay);
|
||||
const jitter = delay * (0.5 + Math.random() * 0.5); // 50-100% of delay
|
||||
console.warn(`[zulip-ext] Retry ${attempt}/${maxAttempts} after ${Math.round(jitter)}ms: ${err.message.slice(0,80)}`);
|
||||
await new Promise(r => setTimeout(r, jitter));
|
||||
}
|
||||
}
|
||||
throw lastError;
|
||||
}
|
||||
|
||||
// Resilience-first event loop (Zulip call_on_each_event pattern)
|
||||
async function resilientPollLoop() {
|
||||
while (connected) {
|
||||
try {
|
||||
const events = await circuitBreaker.fire(() =>
|
||||
withRetry(() => zulipQueue.poll(), {
|
||||
maxAttempts: 2,
|
||||
baseDelay: 1000,
|
||||
shouldRetry: (err) => {
|
||||
const msg = err.message || "";
|
||||
return msg.includes("fetch failed") || msg.includes("ECONN") || msg.includes("network");
|
||||
}
|
||||
})
|
||||
);
|
||||
|
||||
lastError = null;
|
||||
retryCount = 0;
|
||||
|
||||
for (const ev of events) {
|
||||
await processEvent(ev);
|
||||
}
|
||||
|
||||
heartbeat();
|
||||
} catch (err) {
|
||||
const msg = err instanceof Error ? err.message : String(err);
|
||||
|
||||
if (msg.includes("BAD_EVENT_QUEUE_ID") || msg.includes("deregistered")) {
|
||||
// Queue expired — re-register (Zulip docs pattern)
|
||||
console.log(`[zulip-ext] Queue expired, re-registering… (${msg.slice(0,80)})`);
|
||||
try {
|
||||
zulipQueue = await createZulipQueue();
|
||||
console.log(`[zulip-ext] Re-registered, new queue=${zulipQueue.queueId}`);
|
||||
} catch (reRegErr) {
|
||||
console.error(`[zulip-ext] Re-registration failed: ${reRegErr.message}`);
|
||||
connected = false;
|
||||
retryCount++;
|
||||
const backoff = Math.min(5000 * Math.pow(2, retryCount), 300000);
|
||||
console.log(`[zulip-ext] Full reconnect in ${Math.round(backoff/1000)}s`);
|
||||
await new Promise(r => setTimeout(r, backoff));
|
||||
await startPolling();
|
||||
return;
|
||||
}
|
||||
} else if (err.name === "CircuitOpenError") {
|
||||
// Circuit is open — skip this cycle, wait for HALF_OPEN
|
||||
lastError = "circuit_open";
|
||||
await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));
|
||||
} else {
|
||||
lastError = msg;
|
||||
retryCount++;
|
||||
const backoff = Math.min(POLL_INTERVAL_MS * Math.pow(1.5, Math.min(retryCount, 8)), 60000);
|
||||
console.error(`[zulip-ext] Poll error (retry ${retryCount}, backoff ${backoff}ms): ${msg}`);
|
||||
await new Promise(r => setTimeout(r, backoff));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 2: PM2 Hardening
|
||||
|
||||
Create `/root/.pm2/ecosystem.config.cjs`:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
apps: [
|
||||
{
|
||||
name: "abiba-zulip",
|
||||
script: "/bin/pi",
|
||||
args: "--mode rpc --session-id zulip-service",
|
||||
env: {
|
||||
ZULIP_ROLE: "router",
|
||||
ZULIP_SITE: "https://chat.sysloggh.net",
|
||||
ZULIP_EMAIL: "abiba-bot@chat.sysloggh.net",
|
||||
ZULIP_API_KEY: process.env.ZULIP_API_KEY,
|
||||
AGENT_NAME: "abiba",
|
||||
AGENT_OWNER_EMAIL: "jerome@sysloggh.com",
|
||||
},
|
||||
max_restarts: 100, // Up from default 10 — crash loops won't exhaust
|
||||
min_uptime: "10s", // Must survive 10s to count as "alive"
|
||||
max_memory_restart: "500M", // OOM protection
|
||||
restart_delay: 5000, // 5s between restarts
|
||||
kill_timeout: 15000, // 15s SIGTERM grace before SIGKILL
|
||||
listen_timeout: 30000, // 30s to bind health port
|
||||
log_date_format: "YYYY-MM-DD HH:mm:ss Z",
|
||||
error_file: "/root/.pm2/logs/abiba-zulip-error.log",
|
||||
out_file: "/root/.pm2/logs/abiba-zulip-out.log",
|
||||
merge_logs: true,
|
||||
autorestart: true,
|
||||
watch: false,
|
||||
instances: 1,
|
||||
exec_mode: "fork",
|
||||
},
|
||||
{
|
||||
name: "zulip-watchdog",
|
||||
script: "/root/.pi/agent/extensions/zulip/watchdog.js",
|
||||
max_restarts: 10,
|
||||
min_uptime: "3s",
|
||||
restart_delay: 3000,
|
||||
autorestart: true,
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
### Phase 3: Supervisor Watchdog
|
||||
|
||||
Create `/root/.pi/agent/extensions/zulip/watchdog.js`:
|
||||
|
||||
```js
|
||||
// External supervisor — monitors router health and restarts if stalled.
|
||||
// This is the pattern Hermes uses: an external process that can recover
|
||||
// the gateway even if the gateway process itself is hung (not just crashed).
|
||||
|
||||
const HEALTH_URL = "http://127.0.0.1:9200/health";
|
||||
const CHECK_INTERVAL_MS = 30_000;
|
||||
const MAX_FAILURES = 3;
|
||||
|
||||
let failures = 0;
|
||||
|
||||
async function check() {
|
||||
try {
|
||||
const res = await fetch(HEALTH_URL, { signal: AbortSignal.timeout(5000) });
|
||||
if (res.ok) {
|
||||
const data = await res.json();
|
||||
if (data.status === "ok" && data.zulip?.connected) {
|
||||
if (failures > 0) {
|
||||
console.log(`[watchdog] Router recovered after ${failures} failures`);
|
||||
}
|
||||
failures = 0;
|
||||
return;
|
||||
}
|
||||
}
|
||||
failures++;
|
||||
console.warn(`[watchdog] Health check ${failures}/${MAX_FAILURES}: status not ok`);
|
||||
} catch (err) {
|
||||
failures++;
|
||||
console.warn(`[watchdog] Health check ${failures}/${MAX_FAILURES}: ${err.message}`);
|
||||
}
|
||||
|
||||
if (failures >= MAX_FAILURES) {
|
||||
console.error(`[watchdog] ${MAX_FAILURES} consecutive failures — restarting abiba-zulip`);
|
||||
const { execSync } = require("child_process");
|
||||
try {
|
||||
execSync("pm2 restart abiba-zulip", { timeout: 30000 });
|
||||
console.log("[watchdog] Restart command sent");
|
||||
} catch (e) {
|
||||
console.error(`[watchdog] Restart failed: ${e.message}`);
|
||||
}
|
||||
failures = 0;
|
||||
// Wait for restart to complete before checking again
|
||||
await new Promise(r => setTimeout(r, 15000));
|
||||
}
|
||||
}
|
||||
|
||||
console.log("[watchdog] Zulip gateway supervisor started");
|
||||
setInterval(check, CHECK_INTERVAL_MS);
|
||||
check(); // Immediate first check
|
||||
```
|
||||
|
||||
### Phase 4: Health Endpoint Enhancement
|
||||
|
||||
Add circuit breaker stats to the existing health endpoint:
|
||||
|
||||
```js
|
||||
// In /health response, add:
|
||||
"circuit_breaker": {
|
||||
"state": circuitBreaker.state,
|
||||
"failures": circuitBreaker.failures,
|
||||
"successes": circuitBreaker.successes,
|
||||
"total_requests": circuitBreaker.totalRequests,
|
||||
"failure_rate": circuitBreaker.totalRequests > 0
|
||||
? (circuitBreaker.failures / circuitBreaker.totalRequests).toFixed(2)
|
||||
: "0.00"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test Plan
|
||||
|
||||
### Test 1: Queue Re-registration
|
||||
1. Manually delete the Zulip event queue via API
|
||||
2. Next poll should detect BAD_EVENT_QUEUE_ID
|
||||
3. Router should auto re-register within 1 poll cycle
|
||||
4. Verify: `/health` shows new queue_id, connected=true
|
||||
|
||||
### Test 2: Circuit Breaker Trip
|
||||
1. Block Zulip server with iptables: `iptables -A OUTPUT -d 192.168.68.19 -j DROP`
|
||||
2. Router should detect failures, trip circuit after 5 failures
|
||||
3. `/health` should show circuit_breaker.state = "OPEN"
|
||||
4. Remove iptables rule
|
||||
5. Circuit should transition to HALF_OPEN → CLOSED within 60s
|
||||
6. Verify: messages processed after recovery
|
||||
|
||||
### Test 3: Supervisor Recovery
|
||||
1. Kill the router process: `kill -STOP $(pm2 pid abiba-zulip)` (freeze, don't kill)
|
||||
2. Watchdog should detect 3 failed health checks in 90s
|
||||
3. Watchdog should execute `pm2 restart abiba-zulip`
|
||||
4. Verify: router back online, connected=true
|
||||
|
||||
### Test 4: Worker Busy Timeout
|
||||
1. Send a message that triggers a long-running operation
|
||||
2. If worker stays busy >5 minutes, should receive SIGKILL
|
||||
3. User should receive error DM: "Response timed out"
|
||||
|
||||
### Test 5: End-to-End Message
|
||||
1. Send DM "What time is it?" from Jerome
|
||||
2. Should receive response within 30s
|
||||
3. `/health` should show messages_processed incremented
|
||||
|
||||
---
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
If v3 causes issues:
|
||||
1. `pm2 delete abiba-zulip; pm2 delete zulip-watchdog`
|
||||
2. Restore v2 from git: `cd /root/.pi/agent/extensions/zulip && git checkout index.js`
|
||||
3. `pm2 resurrect` to reload previous process list
|
||||
4. Verify: `/health` returns ok
|
||||
|
||||
Backup v2 before starting: `cp index.js index.js.v2-backup-$(date +%Y%m%d-%H%M%S)`
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
| Metric | Current (v2) | Target (v3) |
|
||||
|--------|-------------|-------------|
|
||||
| Uptime between manual interventions | 1-3 days | 30+ days |
|
||||
| Crash recovery | Manual (PM2 resurrect) | Automatic (circuit breaker + supervisor) |
|
||||
| Queue expiry handling | Crash | Auto re-register |
|
||||
| Busy worker deadlock | Router death | Worker SIGKILL + error DM |
|
||||
| PM2 restart exhaustion | Yes (max_restarts=10) | No (max_restarts=100 + watchdog) |
|
||||
|
||||
---
|
||||
|
||||
## Incident Log — 2026-07-18 Fleet-Wide Audit
|
||||
|
||||
### Fleet State After Audit
|
||||
|
||||
| Agent | Platform | Zulip State | Issues Found | Fix Applied |
|
||||
|-------|----------|-------------|--------------|-------------|
|
||||
| **Abiba** | pi (CT 100) | ✅ Connected | API key missing from Infisical injection; poll timeout noise | Added .env fallback; AbortError treated as empty poll (no retry); poll timeout 65s→90s |
|
||||
| **Tanko** | Hermes (CT 112) | ✅ Connected | Gateway disconnected since Jul 11; watchdog restart didn't re-establish Zulip | Full gateway restart (kill wrapper, let infisical-gateway.sh respawn) |
|
||||
| **Mumuni** | Hermes (kagentz CT 105, migrated 2026-08-29) | ✅ Connected | No issues found | None needed |
|
||||
|
||||
### Key Fixes Applied
|
||||
|
||||
**1. Abiba — Credential Fallback (L4 Pattern)**
|
||||
- Root cause: `zulip.api_key` in config.yaml is `""` (expected from Infisical). Infisical vault `ABIBA_ZULIP_API_KEY` wasn't being injected into the process environment.
|
||||
- Fix: Added `.env` file fallback at `/root/.pi/agent/extensions/zulip/.env` with known-working key, sourced before the Infisical `exec`.
|
||||
- Lesson: Per L4 from gpu-self-heal, Infisical is not always available — always keep a local `.env` fallback.
|
||||
|
||||
**2. Abiba — Poll Timeout Handling**
|
||||
- Root cause: Zulip long-poll uses `AbortSignal.timeout(65000)`. Zulip's default `event_queue_longpoll_timeout_seconds` can exceed 65s. When the signal fires, an `AbortError` is thrown and caught by the circuit breaker as a failure.
|
||||
- Fix: Caught `AbortError` inside `poll()` and return empty array (no events) instead of throwing. Extended timeout to 90s to match Zulip server default.
|
||||
- Reference: [Zulip Events System — long-poll timeout](https://zulip.readthedocs.io/en/11.6/subsystems/events-system.html)
|
||||
|
||||
**3. Tanko — Gateway Restart**
|
||||
- Root cause: Gateway process was running but Zulip platform stayed in "disconnected" state since Jul 11, 2026. The wrapper script (`infisical-gateway.sh`) restarts on crash but the gateway wasn't re-establishing Zulip on restart.
|
||||
- Fix: Killed gateway PID to trigger wrapper restart. New gateway (PID 331991) established Zulip connection successfully.
|
||||
|
||||
### Fleet-Wide Zulip Health Metrics (as of 2026-07-18)
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Zulip server | ✅ HTTP 200 |
|
||||
| Agents connected | 3/3 (Abiba, Tanko, Mumuni) |
|
||||
| Abiba circuit breaker | CLOSED (0 failures) |
|
||||
| Abiba uptime | 2D (post-restart) |
|
||||
| Tanko gateway uptime | Ongoing |
|
||||
| Mumuni gateway uptime | Ongoing |
|
||||
| Watchdog status | ✅ Online (2D uptime) |
|
||||
|
||||
### Hermes Agent Zulip Plugin Improvements
|
||||
|
||||
Based on the audit, improvements that should be ported to all Hermes Zulip adapters:
|
||||
|
||||
1. **Circuit breaker pattern** — Already in Abiba's pi extension. Hermes adapters should add the same CLOSED→OPEN→HALF_OPEN state machine with exponential backoff.
|
||||
2. **Credential fallback** — All Hermes agents use Infisical for credentials. Add `.env` local fallback per L4 pattern for `ZULIP_API_KEY`.
|
||||
3. **Queue re-registration** — Handle `BAD_EVENT_QUEUE_ID` with automatic re-registration instead of gateway restart.
|
||||
4. **Supervisor watchdog** — Hermes uses PM2 which auto-restarts on crash, but has no health-check watchdog. Add lightweight external health checks.
|
||||
5. **Streaming** — All agents have `streaming: true` in their zulip config. Verify `edit_message()` is implemented in each adapter.
|
||||
|
||||
### Abiba pi Zulip Extension v2 — Implemented Resilience Summary
|
||||
|
||||
| Feature | Status | Notes |
|
||||
|---------|--------|-------|
|
||||
| Circuit breaker | ✅ | CLOSED→OPEN→HALF_OPEN; 50% failure threshold; 30s reset timeout |
|
||||
| Retry with jitter | ✅ | 2 attempts, 200ms base, 50-100% jitter |
|
||||
| Queue lifecycle | ✅ | 10min idle_queue_timeout; BAD_EVENT_QUEUE_ID handling |
|
||||
| Crash prevention | ✅ | uncaughtException + unhandledRejection recovery |
|
||||
| Worker timeout | ✅ | 5min busy timeout → SIGKILL + error DM |
|
||||
| Health endpoint | ✅ | :9200 with circuit breaker metrics |
|
||||
| Echo prevention | ✅ | Dynamic bot user resolution |
|
||||
| Poll timeout (AbortError) | ✅ v2.1 | Normal timeout returns [] instead of error |
|
||||
| Credential fallback | ✅ v2.1 | .env file before Infisical exec |
|
||||
| Provider auto-fix | ✅ | Detects reasoning_content models, switches to compatible |
|
||||
@@ -13,8 +13,7 @@ triggers:
|
||||
|
||||
> **⚠️ RETIRED** — This contract was embedded in the pi Zulip extension code
|
||||
> (`performHealthCheck()`). That code has been removed. Zulip self-healing for
|
||||
> agents (Mumuni on Hermes, Tanko on DSH) continues through their own platform
|
||||
> monitoring.
|
||||
> Hermes agents (Tanko, Mumuni) continues through their own gateway monitoring.
|
||||
|
||||
## Maintains
|
||||
|
||||
@@ -66,7 +65,8 @@ triggers:
|
||||
|------|----|------|---------|
|
||||
| Zulip server | 192.168.68.19 | root | Docker: `zulip-zulip-1` |
|
||||
| Abiba (pi) | localhost | root | PM2: `abiba-zulip` |
|
||||
| Tanko | 192.168.68.122 (CT 112) | jerome | DSH (DeepSeek Harness) — restart via DSH service, not `hermes gateway restart` (no longer a Hermes agent since 2026-08-27) |
|
||||
| Mumuni | 192.168.68.123 | root | `hermes gateway restart` |
|
||||
| Tanko | 192.168.68.122 | jerome | `PATH=$PATH:/home/jerome/.hermes/hermes-agent hermes gateway restart` |
|
||||
|
||||
## Debounce
|
||||
|
||||
@@ -75,8 +75,9 @@ Track via `/tmp/zulip-heal-debounce-<agent>` (unix timestamp of last restart).
|
||||
|
||||
## Reporting
|
||||
|
||||
This contract is RETIRED — health-check logs are NOT knowledge graph content.
|
||||
No graph nodes are created. Logs go to Gitea (SyslogSolution/health-logs).
|
||||
Every cycle produces a knowledge graph node:
|
||||
- Title: `[LEARN] zulip-self-heal: <timestamp>`
|
||||
- metadata: { type: "remediation", status: "fixed" | "escalated" | "healthy" }
|
||||
- Issues fixed → DM: "🛠 Zulip Self-Heal: fixed <issue>"
|
||||
- Issues escalated → DM: "⚠️ Zulip Self-Heal: <issue> needs attention"
|
||||
|
||||
|
||||
Reference in New Issue
Block a user