oikos/plans/2026-07-08-nomos-resident-agent.md

# 2026-07-08 — Nomos resident agent (renames Hermes)

**Status:** In Progress — N0-N3 complete 2026-07-08

## Goal

Rename the gateway formerly known as **Hermes** to **Nomos** (from
*oikonomos*, the steward of the oikos — and avoiding confusion with Nous
Research's unrelated "Hermes Agent" product), and turn it from a keyword
router into a resident LLM-backed agent: a long-running service you converse
with, which reasons over the full 28-tool MCP surface, holds session context,
and is surfaced as the **main entry point of the control-room web UI**
([companion plan](2026-07-08-control-room-webui.md)). Oikos already has the
agentic substrate — policy classes, approval gating, `agent_activity`, an
OODA loop; this gives it the conversational front half.

## What exists vs what's added

Today `cmd/hermes/main.go` contains no LLM anywhere: `routeQuery` is
`strings.Contains` over ~6 phrases, `extractEntity` knows 5 hardcoded
services, and everything else silently falls back to `get_health_summary`.
But the hard plumbing already exists and is reused as-is:

- `mcpClient` (main.go:190) — working Streamable-HTTP MCP client
  (initialize → session → `tools/call` with SSE frame parsing).
- `listTools()` (main.go:318) — currently dead code; extended (below) it
  becomes the bridge that feeds MCP tool schemas to the LLM.
- `.agents/HERMES.md` / `hermes/SOUL.md` — the persona, becomes the system
  prompt (renamed in N0).
- `agent_activity` hypertable + `correlation_id` conventions — where tool
  calls get logged so the control room can show the agent working.

## Milestone N0 — the rename (Hermes → Nomos)

Do this first, as its own commit, before any agent code lands. Scope is the
**live service identity**; history (`archive/`, `plans/done/`, past
investigations) is never rewritten.

**Code & build**
- `cmd/hermes/` → `cmd/nomos/` (binary `nomos`; keep `serve` subcommand).
- Env vars in main.go: `HERMES_MCP_URL`, `HERMES_LISTEN`,
  `HERMES_AGENT_SLUG` → `NOMOS_*`. Default slug `agent:nomos`;
  `clientInfo.name` → `nomos`.
- `internal/config/config.go`: `HermesAgentSlug` field +
  `OIKOS_HERMES_AGENT_SLUG` → `NomosAgentSlug` / `OIKOS_NOMOS_AGENT_SLUG`;
  `hermesAgentID` in `internal/httpapi/server.go:140-149` renamed to match.
- `hermes/` directory → `nomos/` (`SOUL.md`, `config.yaml`,
  `skills/homelab-ops/`); `tools/setup-hermes-soul.sh` →
  `tools/setup-nomos-soul.sh` with paths updated.

**Deploy**
- `compose/hermes/Dockerfile` → `compose/nomos/Dockerfile`; docker-compose
  service `hermes:` → `nomos:` (docker-compose.yml:111, env at :63 and :121).
- Caddy: `hermes.hubris.network` vhost → `nomos.hubris.network`
  (compose/caddy/Caddyfile.oikos:26); keep the old hostname as a `redir`
  block for one transition window; add the DNS record. (These live in the
  external caddy-conf repo / DNS — operator step.)

**Data (identity-preserving — do NOT create a new entity)**
- Live DB: `UPDATE entities SET slug='agent:nomos',
  attributes = jsonb_set(attributes,'{name}','"nomos"') WHERE
  slug='agent:hermes';` — relationships/audit reference the UUID, so history
  survives the slug change. Ship as a migration so every environment gets it.
- `seeds/inventory.yaml:328` (`agent:hermes` entity) and `:541` (owns
  relationship) → `agent:nomos`. Seed upserts by slug, so the migration must
  run before seeding or the seed would mint a duplicate entity.

**Docs & persona**
- `.agents/HERMES.md` → `.agents/NOMOS.md`; update every referencing doc
  (`AGENTS.md`, `CLIENTS.md`, `README.md`, `CONTRIBUTING.md`,
  `.agents/operations/hermes-agent.md` → `nomos-agent.md`,
  `.agents/operations/commands.md`, skills docs).
- ADR-0012 (`docs/adr/0012-hermes-oikos-interactions.md`): append a
  "renamed to Nomos" note; don't rewrite the ADR.

**Explicitly out of scope**
- Matrix user `@hermes:hubris.network` (docker-compose.yml:103) — that's the
  notifier's homeserver account; renaming it is an operational Matrix task,
  optional and later.
- Legacy `bin/hermes` wrapper and `hermesd` on LXC 129 (referenced in
  `.sops.yaml:89,110`) — separate legacy systems, untouched. Note: that
  `.sops.yaml` entry shows an **OpenRouter API key path already exists** in
  the secrets tree — reuse it for N1.
- Historical knowledge/investigation pages and executed plans.

**Verify N0:** `go build ./...`; `docker compose --profile full config`
resolves; `curl nomos.hubris.network/healthz` (and the old vhost redirects);
`SELECT slug FROM entities WHERE slug LIKE 'agent:%'` shows `agent:nomos`
with its original UUID; `grep -ri hermes` returns only history/ADR/legacy
hits.

## Architecture decisions

### Hand-rolled tool loop, not a hosted connector or off-the-shelf agent

Three ways to get an LLM driving the tools; decision is (3):

1. **Hosted MCP connector** (e.g. Anthropic's `mcp_servers` param): zero
   loop code, but the provider's servers must reach the MCP endpoint over
   the public internet. `mcp.hubris.network` is currently exposed *without
   auth* — a hole the [gaps plan](2026-07-08-oikos-gaps-and-improvements.md)
   says to close, not to build on. Keeping the MCP surface mesh-private is
   the right posture for a homelab control plane.
2. **Off-the-shelf agent framework** (evaluated: Nous Research's
   [Hermes Agent](https://hermes-agent.nousresearch.com/) — MIT, self-hostable,
   multi-channel personal assistant with memory/subagents/browsing/code-exec;
   also the naming-collision motivation for N0). Rejected for this role: it
   is a desktop/personal-assistant framework with chat-platform frontends,
   not an embeddable service — there is no clean `/chat` API for the
   control-room UI to stream from; the oikos-native integration (sessions in
   Postgres, `agent_activity` + correlation-id joins, approval rail) would
   not exist; and its browsing/code-exec surface is far larger than a loop
   confined to the 28 MCP tools. It (or any MCP client) remains usable as an
   *external* agent against the MCP endpoint — orthogonal to the resident.
3. **Hand-rolled agent loop** (~200 lines): Nomos calls the LLM API with
   tool definitions translated from `tools/list`, executes returned tool
   calls through its *existing* `mcpClient` inside the mesh, feeds results
   back, repeats until the model answers in text. Only conversation text
   leaves the mesh; the tool transport stays private; the agent is confined
   to the MCP surface by construction.

### LLM provider: OpenRouter, default model DeepSeek V4 Flash

- **OpenRouter** (OpenAI-compatible Chat Completions API) rather than a
  single-vendor SDK: use the official `openai-go` client with
  `base_url=https://openrouter.ai/api/v1` and `OPENROUTER_API_KEY` (secret
  path already exists in `.sops.yaml`). Model choice becomes one env var.
- **Default model: `deepseek/deepseek-v4-flash`** — supports tool calling,
  1M context, $0.09/M input / $0.18/M output. Use OpenRouter's **Exacto**
  routing (highest measured tool-calling accuracy) since tool calls are this
  agent's entire job; low temperature; strict system prompt.
- MCP tool `inputSchema` is already JSON Schema — exactly what
  `tools[].function.parameters` expects — so translation is a field rename.
- **Privacy:** conversation text and tool results (hostnames, log excerpts)
  transit OpenRouter and the upstream provider. Pin OpenRouter provider
  preferences to ZDR / no-training providers in the request payload.
- A flash-class MoE will be weaker than frontier models on long multi-step
  chains; mitigations are the iteration cap, Exacto routing, and bumping
  `NOMOS_MODEL` per-deployment when a task warrants it.

## Design

### Agent loop (`cmd/nomos/agent.go`, new)

```
system prompt  = SOUL.md content (mounted; provisioned by tools/setup-nomos-soul.sh)
tools          = listToolsFull()   // extend listTools() to return name, description, inputSchema
loop (max 15 iterations):
  resp = chat.completions (OpenRouter, model, system, history, tools)
  if resp has tool_calls:
      for each: result = mcpClient.callTool(name, args)   // existing code path
                log to agent_activity (correlation_id = session turn id)
      append assistant msg + tool-role result msgs to history
  else: final text → stream to caller, persist turn
```

- Model: `deepseek/deepseek-v4-flash` default, `NOMOS_MODEL` override.
  `max_tokens` and iteration cap configurable; hard per-turn budget so a
  pathological loop can't burn the API bill.
- `OPENROUTER_API_KEY` from env / Infisical / SOPS (existing path).
- Mutations need no new guardrails: the agent's only write path is
  `request_execution`, which flows through the existing risk-class /
  approval machinery. The agent's actor identity is `agent:nomos`.
  **Depends on gaps-plan bug A1** (approvals FK) — without that fix the
  agent's config mutations dead-end silently, which is worse when a
  conversational agent confidently reports "queued for approval".

### HTTP surface (`cmd/nomos/main.go`)

- `POST /chat` `{session_id?, message}` → **SSE stream** of typed events:
  `text` (deltas), `tool_use` (name + args), `tool_result` (truncated),
  `done` (session_id, usage). The web UI renders tool calls as inline chips
  as they happen.
- `GET /sessions`, `GET /sessions/{id}` — history for the UI.
- `/query` kept for scripts/structured callers. The toy NLU is **removed**
  (per gaps plan §C): a `query` with no `tool` returns "natural language
  belongs to /chat" plus the tool list from the now-live `listTools()`.
- `/healthz` unchanged.

### Sessions (Postgres, new migration)

`agent_sessions (id, title, actor, created_at, last_active_at)` and
`agent_messages (id, session_id, role, content JSONB, created_at)` in the
shared oikos DB — Nomos gains a `DATABASE_URL` (it's in the same compose
stack). DB-backed rather than in-memory so conversations survive restarts
and the control room can list/replay them. Tool invocations additionally go
to `agent_activity` with the session's correlation_id, so the existing
agent-activity page and the ops ledger join up with zero new query paths.

### Connectivity & auth

- Compose: the `nomos` service (renamed in N0, `full` profile) gains
  `OPENROUTER_API_KEY`, `NOMOS_MODEL`, `DATABASE_URL` env.
- Caddy: route `oikos.hubris.network/agent/*` → `nomos:8092` **behind the
  same Authentik forward_auth** as the rest of the vhost, stripping the
  `/agent` prefix. The web UI then calls same-origin `/agent/chat` — no
  CORS, and EventSource/fetch-streaming work unmodified.
- Nomos enforces trusted-proxy headers (`X-Authentik-Username`) when
  `NOMOS_TRUSTED_PROXY=true`, and finally implements the `mesh_only: true`
  check that the config promises but `main.go` never enforces (gaps plan
  B3). Direct :8092 access stays mesh-only for agents/scripts.

### Web UI entry point (amends the control-room plan)

The agent chat becomes the **home view** of the control room (`/ui/#/`):

- Center: conversation pane (streamed text, expandable tool-call chips
  showing args/results, correlation-id links into the ops ledger).
- Right rail: live context — pending approvals with approve/deny buttons,
  recent events, health strip. When the agent's `request_execution` needs
  approval, the approval card appears in the rail *mid-conversation* (via
  the `approval.created` SSE event) and can be decided without leaving chat.
  That's the whole product in one screen: ask → watch it act → approve →
  watch it complete.
- A persistent chat drawer is available from every other page.
- Session list in the nav; sessions resumable.

### Later (explicitly out of scope for v1)

- Matrix bridge: Nomos as a Matrix bot in the operator room, reusing the
  notifier's homeserver credentials — same `/chat` loop, different frontend.
- Proactive mode: agent opens a session itself when a signal fires
  (escalation-with-context instead of a bare alert).

## Milestones

- **N0 — rename:** see above; standalone commit, deployable on its own.
- **N1 — loop:** `agent.go` + openai-go (OpenRouter base URL);
  `listToolsFull()`; `/chat` (non-streaming JSON first); remove toy NLU, fix
  `/query` fallback + help. Verify by curl: multi-tool question ("what's
  degraded and what depends on it?") produces chained
  `get_health_summary` → `get_blast_radius` calls.
- **N2 — state + streaming:** sessions migration, DB persistence, SSE
  streaming on `/chat`, `agent_activity` logging, budgets.
- **N3 — UI entry point:** home chat view + context rail + drawer in the
  control-room SPA (needs control-room M1; rail approvals need M2's
  `approval.created` event and gaps-plan A1).
- **N4 (optional):** Matrix bridge, proactive sessions.

## Files

```
cmd/nomos/{main.go, agent.go, store.go}   # renamed + loop + sessions
internal/config/config.go, internal/httpapi/server.go   # slug config rename
nomos/{SOUL.md, config.yaml, skills/}     # renamed dir; drop query_routing
tools/setup-nomos-soul.sh
migrations/0xx_rename_agent_hermes_to_nomos.up.sql
migrations/0xx_agent_sessions.up.sql
seeds/inventory.yaml
compose/nomos/Dockerfile, docker-compose.yml, Caddyfile.oikos (/agent route, vhost)
.agents/NOMOS.md + referencing docs; docs/adr/0012 note
web/src/pages/Chat.svelte + lib/stores/chat.ts   # control-room home view
go.mod                                    # openai-go
```

## Verification

- N0: see milestone N0 verify list.
- N1: `curl -N /agent/chat` with a question requiring 2+ tools; confirm the
  tool chain in the response and rows in `agent_activity`.
- N2: restart nomos mid-session, resume by session_id, history intact.
- N3: from the UI home, ask Nomos to restart a low-risk service; watch the
  tool chips stream, the execution appear in the rail, and (for a gated
  action) the approval card arrive and be decidable in place.