kundencenter/docs/night-agent.md

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.