spb/ka-guardian

1# KA Guardian — ka2 · ka4 · ka623Les trois agents gardiens autonomes du Groupe KA. Depuis le 2026-08-23, ka2/ka4/ka64ne sont plus des bots de cartographie web : ce sont des **agents de maintenance5autonomes des connecteurs** des plateformes ·Ka, bâtis sur Claude (CLI headless).67## Ce qu'ils font891. **Détection** — toutes les 5 min, chaque agent lit la supervision centralisée10   d'api-ka (`/api/v1/monitoring/connectors`, ~2 600 connecteurs classés11   ok/degraded/broken/stale toutes les 2 h). Un connecteur `broken` ou `stale`12   de son périmètre → incident.132. **Mission** — l'agent dépêche une mission au **runner** du nœud qui héberge14   l'app : `claude -p` headless, lancé dans le repo de l'app, avec un prompt de15   mission strict (diagnostiquer, reproduire, corriger minimalement, re-tester,16   `pm2 restart` du process de sync, commit `[kaX] fix connecteur …`, jamais de push).173. **Surveillance** — après réparation déclarée, l'incident passe en `watching`18   pendant 8 h. Connecteur de retour à `ok` → résolu.194. **Rollback automatique** — si l'app tombe (healthcheck) ou si le connecteur20   est toujours cassé après la fenêtre : retour au commit d'avant mission21   (`git reset --hard`/revert) + `pm2 restart`. 3 tentatives max, puis `abandoned`22   (intervention humaine).235. **Vitrine live** — chaque site (www.ka2.bot / www.ka4.bot / www.ka6.bot) est24   une salle de contrôle : flux SSE en direct de chaque action de l'agent25   (outils, réflexions, verdicts), board d'incidents, couverture par service,26   historique des missions avec transcript et coût.2728## Répartition2930| Agent | Domaine | Services surveillés |31|---|---|---|32| ka2 | www.ka2.bot :8799 | louka, immoka, restoka |33| ka4 | www.ka4.bot :8899 | autoka, foodka, sortika |34| ka6 | www.ka6.bot :8999 | fabrika, jobka, creaka + tout nouveau service (défaut) |3536## Architecture3738- `orchestrator/` — un process FastAPI par agent (M4M36, launchd39  `com.kaX.guardian`), SQLite `data/kaX.db`, dashboard servi sur le même port,40  tunnels ngrok existants conservés.41- `runner/` — un service par nœud d'app (M3U96a/b, M4M64a/b, port 7791, launchd42  `com.ka.guardian-runner`), 1 mission à la fois par nœud, transcripts dans43  `~/ka-guardian-runner/transcripts/`. Exécute `claude -p --output-format44  stream-json` et relaie chaque événement à l'orchestrateur (`/api/ingest`).45- `topology.json` — source de vérité : agents, services (nœud/dir/pm2/port),46  IP LAN, politique (fenêtres, cooldowns, modèle).47- Auth interne : token partagé `~/.ka-guardian.env` (orchestrateurs + runners),48  header `X-KA-Token`. Clé Anthropic + clés anti-bot : `~/.claude/.env` des nœuds.49- Communication **par le LAN 192.168.2.x** (SSH/Tailscale inter-nœuds bloqué).5051## Déploiement5253```bash54deploy/deploy.sh all          # runners + orchestrateurs55deploy/deploy.sh runners      # seulement les 4 runners56deploy/deploy.sh orchestrators57```5859## Admin (token requis)6061```bash62# mission manuelle sur un connecteur63curl -X POST http://M4M36.maclustr.io:8799/api/admin/mission \64  -H "X-KA-Token: $TOKEN" -d '{"service":"louka","source":"kijiji"}'65# pause / reprise d'un agent66curl -X POST http://M4M36.maclustr.io:8799/api/admin/pause -H "X-KA-Token: $TOKEN" -d '{"paused":true}'67```6869## Historique7071Les anciens bots (cartographie du web québécois / influenceurs) sont archivés :72`~/ka-bots-backup-20260823.tar.gz` sur M4M36 (code + bases SQLite complètes).73