Nacht-Agent: automatische Bearbeitung von Plane-Tickets (Label agent)

docs/night-agent.md

@@ -0,0 +1,53 @@
+# Nacht-Agent
+
+Arbeitet einmal pro Nacht (01:00 Uhr, `kc-night-agent.timer`) offene Plane-Tickets mit dem Label
+**„agent“** ab, in den Status Backlog oder Todo. Ergebnis ist **immer** ein Branch auf der Forge
+(`https://forge.flessinghome.de/flessinglabs/kundencenter`), bei Erfolg zusätzlich ein Pull
+Request und Ticket-Status „In Review“. **Nichts wird automatisch gemergt oder live geschaltet** –
+das bleibt bei der morgendlichen Durchsicht durch den Assistenten bzw. den Nutzer.
+
+## Absicherung
+Der Agent läuft als Betriebssystembenutzer `kundencenter` (systemd-Dienst `kc-night-agent.service`,
+zusätzlich `ProtectSystem=strict`/`ProtectHome=true`, nur `/var/lib/kundencenter/night-agent`
+beschreibbar). Dieser Benutzer:
+- hat kein `sudo`, kann also kein `systemctl restart` und keine Dienste anfassen,
+- kann `/etc/kundencenter/*` nicht lesen (root:root, chmod 600) – keine Geheimnisse erreichbar,
+- arbeitet in einer **eigenen frischen Arbeitskopie** (`/var/lib/kundencenter/night-agent/work`),
+  niemals in `/srv/kundencenter` selbst.
+
+Zusätzlich bekommt jeder Lauf feste Leitplanken als System-Prompt
+(`ops/night-agent-guardrails.md`): ein Ticket = ein Branch, Tests müssen grün sein, keine
+Vermutungen bei fehlenden Zugangsdaten, kein Aufräumen außerhalb des Tickets.
+
+## Ablauf je Ticket
+1. Plane-Status → „In Progress“, Kommentar mit Branch-Namen.
+2. `claude -p` mit Ticket-Text + Leitplanken, Budget-Deckel (`--max-budget-usd`, Standard 3 $),
+   Zeit-Deckel (Standard 45 Min./Ticket, insgesamt max. 150 Min./Nacht).
+3. Unabhängig vom Agenten prüft das Skript selbst: `pnpm install && pnpm build && pnpm typecheck
+   && pnpm test` (Tests laufen automatisch gegen eine frische `kundencenter_test`, nie gegen die
+   produktive Datenbank).
+4. Grün + Agent meldet `AGENT_STATUS: ok` → Branch pushen, Pull Request eröffnen, Plane-Status
+   „In Review“, Kommentar mit PR-Link.
+5. Rot, oder Agent meldet `AGENT_STATUS: blocked`, oder keine Änderungen → Branch wird trotzdem
+   gepusht (nichts geht verloren), aber **kein** Pull Request; Kommentar in Plane beschreibt das
+   Problem. Status bleibt unverändert (kein automatisches „Wartet auf Input“, das entscheidet der
+   Mensch nach Lektüre des Kommentars).
+
+## Einrichtung
+- `/etc/kundencenter/night-agent.env` (chmod 600, root): `ANTHROPIC_API_KEY` (eigener, vom
+  interaktiven Zugang getrennter Schlüssel – siehe unten) sowie optionale Stellschrauben
+  (`NIGHT_AGENT_MAX_TICKETS`, `NIGHT_AGENT_BUDGET_USD`, `NIGHT_AGENT_DEADLINE_MIN`,
+  `NIGHT_AGENT_TICKET_TIMEOUT_MIN`).
+- `/etc/kundencenter/forge.env`: `FORGE_URL`, `FORGE_REPO` (`flessinglabs/kundencenter`),
+  `FORGE_TOKEN`.
+- Plane-Label „agent“ muss auf ein Ticket gesetzt sein, damit der Agent es aufgreifen darf.
+- Aktivieren: `systemctl enable --now kc-night-agent.timer`. Einmalig von Hand testen:
+  `systemctl start kc-night-agent.service` (Logs: `journalctl -u kc-night-agent` sowie
+  `/var/lib/kundencenter/night-agent/logs/`).
+
+## Bekannte Grenzen
+- `kundencenter_test` wird bei jedem `pnpm test` neu angelegt (siehe `apps/api/test/global-setup.ts`)
+  – Agent-Lauf und ein manueller Testlauf am Tag sollten sich nicht überschneiden.
+- Der Agent öffnet nie mehr als `NIGHT_AGENT_MAX_TICKETS` Pull Requests pro Nacht.
+- Kein Zugriff auf Anbieter-Testzugänge (z. B. KeyHelp, KCS) – bei Tickets, die das brauchen,
+  meldet der Agent `blocked`.