# Hermes Spec

Status: active / matches code.

"Hermes" is PodMan's **action layer** — the part that turns a detected problem
into something a teammate sees, hears, or gets done. It spans three things:

1. **Interventions** — cards, messages, and urgent voice in the pod room.
2. **Async jobs** — longer tasks delegated from the live conversation agent.
3. **Ops watchdog** — keeps the production services healthy.

The LiveKit identity for the main agent is `podman-hermes`.

---

## 1. Interventions

**Code:** `backend/src/agent/podman.ts`, `backend/src/action/hermes.ts`,
`backend/src/voice/live.ts`.

When the agent detects a collision, it runs the learning loop (recall → policy
gate; see `docs/cont_learning.md`) and then publishes the **least intrusive**
intervention that fits:

- **Card / message** — a data-channel packet on the `podman.intervention` topic
  (`publishHermesIntervention` / `publishHermesMessage`). Default path.
- **Urgent voice** — only for `critical` collisions. `speak()` generates Gemini
  TTS audio and publishes it as a LiveKit audio track.
- **Research overlap nudge** — a collaboration card when one engineer is editing
  a file while another is researching the same topic in docs/browser context.
  This uses `suggestedAction.kind = "ping_teammate"` and is spoken once for the
  demo beat, but it is explicitly **not** a merge conflict.

Intervention text is short and deterministic (template, not an LLM call):
`Conflict: alice + bob both on detector.ts (unpushed). Seen before.` The spoken
line is phrased for natural TTS prosody. Each intervention is persisted to the
`interventions` collection; the teammate's accept/dismiss returns via
`POST /api/outcome`.

Research-overlap text is also deterministic:
`🤝 bob is researching LiveKit agents (docs.livekit.io) while alice edits livekit.py — sync up before duplicating effort.`

A per-pod cooldown (`NUDGE_COOLDOWN_MS`, default 3 min) and a single-shot
"active conflict" guard prevent repeat nagging; a conflict re-arms once it
resolves.

---

## 2. Async Hermes jobs

**Code:** `backend/src/hermes/jobs.ts`. **Storage:** `hermes_jobs` +
`hermes_job_events` (see `docs/mongodb.md`).

The live conversation agent can hand a longer task to Hermes via its
`delegate_to_hermes` tool. Lifecycle:

```
queued → running → (waiting_for_confirmation) → completed | aborted | failed
```

`createHermesJob()` records the job, emits an `accepted` event, and kicks off
`runHermesJob()` in the background. The runner gathers context and runs scoped,
read-mostly steps based on the prompt and success criteria:

- always: `git status --short --branch`, `git diff --stat`
- if the ask mentions GitHub: a repo reachability check via the GitHub API
- if it mentions Mongo/memory/telemetry: collection counts
- if it mentions build/test/typecheck/broken: `pnpm typecheck`

**Confirmation gate:** if `riskLevel === 'deploy_allowed'` and
`requiresConfirmation`, the job parks at `waiting_for_confirmation` instead of
acting. **Abort:** `abortHermesJob()` signals the runner's `AbortController`.

Every step appends a `hermes_job_event` (redacted + truncated), which is both
stored and published live to the room as a `HERMES_JOB_EVENT` data message from a
short-lived `podman-hermes-job-*` identity. The conversation UI streams these via
`GET /api/.../hermes-job/events/stream`.

**Endpoints:** `POST /api/internal/hermes/jobs`,
`GET /api/internal/hermes/jobs/:jobId`, `.../abort`, `.../events`,
`.../events/stream`, plus the pod-scoped `.../live-conversation/:sessionId/hermes-job`.

---

## 3. Ops watchdog

**Code:** `scripts/hermes-watchdog.mjs`, `scripts/hermes-sync-deploy.mjs`,
`scripts/hermes-notify.mjs`. **Detail:** `docs/digitalocean.md`.

systemd supervises the app processes; Hermes owns the loop around them:

- `pnpm hermes:watchdog` checks systemd services, public routes, `/health`,
  `/api/pods`, and `pnpm deploy:doctor`. Failures trigger targeted restarts.
- `podman-hermes-watchdog.timer` runs it every 5 minutes.
- `podman-hermes-sync-deploy.timer` polls `origin/main` every 2 minutes and, on a
  clean tree, fast-forwards, builds, publishes `frontend/dist`, restarts
  API/agent/Caddy, and runs the strict watchdog.
- Reports go to `/var/log/podman/hermes-watchdog-latest.json`; set
  `PODMAN_ALERT_WEBHOOK_URL` to forward failures to Discord/Slack/webhook.

---

## What Hermes is NOT

- Not an autonomous code-writing agent. Job steps are scoped, read-mostly checks;
  deploy-level actions require explicit confirmation.
- Not a second collision detector. Detection is deterministic
  (`collision/detector.ts`); Hermes only acts on the result.