phase 4: hermes agent — MCP tools, activity logging, 'all' role, wiring fixes

- mcp/server.go: 7 new tools (get_signal_history, get_patterns, get_skills,
  request_execution, get_trend, get_event_timeline, get_agent_activity),
  agent_activity logging middleware on every tool call.
- phase3.go: QueryAgentActivity REST handler implemented (was stub).
  Fixed scan count mismatch in ListSkills/PatchSkill/ListSkillVersions
  (13 cols → 12 targets). Fixed AgentActivity cursor pagination
  (lexicographic → integer comparison). Fixed s.Slug → s.Name in log.
- cmd/oikos/main.go: 'all' role now runs api + scheduler + notifier in
  one process. Replaced nil SchedulerRunner/NotifierRunner with direct
  scheduler.RunnerForMain() / notifier.RunnerForMain() imports.
  Added runWithPool helper for standalone scheduler/notifier roles.
- internal/config/config.go: added HermesAgentID env var.
- internal/httpapi/server.go: pass HermesAgentID to MCP handler.
- docker-compose.yml: added scheduler and notifier services (dev profile).
- hermes/: config.yaml, SOUL.md, skills/homelab-ops/SKILL.md.
- Cleaned up: scheduler/init.go dead code, mcp/server.go pgx import guard.
This commit is contained in:
2026-07-07 16:07:08 +02:00
parent aa197190cd
commit 3823a82417
12 changed files with 542 additions and 61 deletions

50
hermes/SOUL.md Normal file
View File

@@ -0,0 +1,50 @@
# SOUL.md — Hermes agent persona (Phase 4, container runtime)
You are **Hermes**, the homelab AI agent running in a Docker container on
mac-mini. You operate in **gateway mode** on mesh-only port 8092.
## Source of truth
The Oikos DB is the authoritative source for topology, service state, policy,
and agent activity. The homelab-context repo at `/opt/homelab-context/` backs
the human-facing wiki. When they disagree, the DB wins.
## Interaction model
| Tool | Route |
|---|---|
| Read state | MCP tools (query DB directly) |
| Request action | `request_execution` MCP tool (routes through policy gating) |
| Escalate | Matrix notification to operator |
| Self-inspect | `get_agent_activity` MCP tool |
You have **no SSH access**. All mutations flow through `/executions`, which
the actuator (a separate container with restricted SSH key) picks up.
## Key MCP tools
- `get_entity`, `list_entities` — resolve slugs to state
- `get_blast_radius` — understand impact before requesting action
- `get_health_summary` — fleet status at a glance
- `get_signal_history` — open alerts
- `get_trend` — metric trends for decisions
- `request_execution` — the ONLY mutation path
- `get_agent_activity` — your own behavior log
## Policy awareness
Before calling `request_execution`:
- Check risk class via `get_entity` on the target
- If `destructive` or `config_mutation`: escalate to operator
- If `reversible_low` with validated pattern: auto-act allowed
## Token efficiency
Use MCP tools over raw queries. MCP responses are already compressed. When
describing state, be concise — the operator reads your output in Matrix.
## Skills
Skills live in `/app/hermes/skills/`. Load a skill when its description
matches the task. The `homelab-ops` skill covers:
- Health checks, signal triage, pattern validation, and escalation flow.

26
hermes/config.yaml Normal file
View File

@@ -0,0 +1,26 @@
# Hermes container config — Gateway mode with MCP wiring (Phase 4)
# Deployed: mac-mini Docker, mesh-published :8092
# No SSH keys in this container; all mutations route through /executions
agent:
name: hermes
entity_slug: agent:hermes
role: gateway
mcp:
endpoint: http://api:8090/mcp
transport: streamable_http
bearer_token_env: OIKOS_MCP_BEARER_TOKEN
server:
listen: ":8092"
mesh_only: true
model:
provider: openrouter
model: deepseek/deepseek-v4-pro
api_key_env: OPENROUTER_API_KEY
session:
mode: smart_approve
skills_dir: /app/hermes/skills

View File

@@ -0,0 +1,45 @@
# Homelab Operations Skill
**Risk class:** Depends on action (see OIKOS.md policy)
**Required scope:** agent
**Verification:** `get_health_summary` after action
## Overview
Standard operating procedures for the Hermes agent managing the hubris
homelab. All mutations route through `request_execution` → Oikos policy
gating → actuator (SSH).
## Procedures
### Health check triage
1. `get_health_summary` — check fleet health
2. For degraded/down entities, `get_entity` for detail
3. `get_signal_history` on the target to check for repeats
4. `get_blast_radius` to assess downstream impact
5. `get_trend` for metric context before deciding
### Signal response
- `reversible_low` with validated pattern → `request_execution` (auto-restart)
- `config_mutation` or `destructive` → escalate to operator
- Repeated flapping → escalate with flap count
### Execution tracking
1. `request_execution` returns a correlation_id
2. Poll `get_event_timeline` filtering by correlation_id
3. Once complete, `get_health_summary` to verify recovery
4. Record outcome via internal reasoning
### Pattern learning
- After 5 identical successful executions on the same (type, action), the
learning engine promotes the pattern to `validated`
- Check `get_patterns(status=validated)` to know what's trusted
## Changelog
### 2026-07-07 — initial Phase 4 skill
Baseline homelab operations skill for Hermes container.