spb/ka-guardian
Public
1# KA Guardian — ka2 · ka4 · ka623**Les trois agents gardiens autonomes du Groupe KA.** Un seul repo, trois instances,4trois salles de contrôle publiques :56**[www.ka2.bot](https://www.ka2.bot)** · **[www.ka4.bot](https://www.ka4.bot)** · **[www.ka6.bot](https://www.ka6.bot)**78Depuis le 2026-08-23, ka2/ka4/ka6 ne sont plus des bots de cartographie web : ce sont9des **agents de maintenance autonomes des connecteurs** des plateformes ·Ka, bâtis sur10Claude (CLI headless). Un connecteur tombe en panne quelque part dans l'écosystème ·Ka ?11Le gardien concerné le détecte, ouvre le code, le répare, prouve que ça marche — et si12ça empire, il revient au commit d'avant. **Tout ce qu'il fait est public, en direct.**1314---1516## Les trois agents1718| Agent | Domaine | Port | Tagline | Périmètre | Accent |19|---|---|---|---|---|---|20| **ka2** | [www.ka2.bot](https://www.ka2.bot) | :8799 | Gardien immobilier & local | Lou·Ka, Immo·Ka, Resto·Ka, House·Ka, Rent·Ka | bleu `#a9d1f7` / `#1e4fa3` |21| **ka4** | [www.ka4.bot](https://www.ka4.bot) | :8899 | Gardien mobilité & quotidien | Auto·Ka, Food·Ka, Sorti·Ka | ambre `#ffc36b` / `#a35c00` |22| **ka6** | [www.ka6.bot](https://www.ka6.bot) | :8999 | Gardien flagship — gros volumes | Fabri·Ka, Job·Ka, Créa·Ka, Vrai·Prix **+ tout nouveau service** (défaut) | violet `#cdb4f9` / `#5b21b6` |2324L'identité de chaque agent (numéro, domaine, tagline, accents, services surveillés,25modèle Claude) vit dans **`topology.json`**, la source de vérité partagée entre26orchestrateurs et runners. Les pages web (`orchestrator/web/index.html`,27`commander.html`) sont des gabarits communs : les jetons `__NUM__`, `__DOMAIN__`,28`__TAGLINE__` sont rendus par agent au démarrage (`_render_page` dans `main.py`).29Chaque agent a sa bannière de partage OG (`orchestrator/web/og-ka{2,4,6}.png`,30servie à `/og.png`, régénérable via `deploy/make_og_images.py`), ses favicons et son31apple-touch-icon aux couleurs de son accent.3233## Aperçu des sites publics3435*Captures du 2026-08-25 (mobile 390×844 · desktop 1440×900) — chaque gardien rend des comptes en direct sur son site. Visites guidées détaillées (30 captures du 2026-08-28) plus bas.*3637<table>38 <tr>39 <td align="center"><img src="docs/screenshots/desktop/ka2.webp" width="300" alt="ka2.bot"><br><sub><b><a href="https://www.ka2.bot">ka2.bot</a> — gardien immobilier & local</b></sub></td>40 <td align="center"><img src="docs/screenshots/desktop/ka4.webp" width="300" alt="ka4.bot"><br><sub><b><a href="https://www.ka4.bot">ka4.bot</a> — gardien mobilité & quotidien</b></sub></td>41 <td align="center"><img src="docs/screenshots/desktop/ka6.webp" width="300" alt="ka6.bot"><br><sub><b><a href="https://www.ka6.bot">ka6.bot</a> — gardien flagship</b></sub></td>42 </tr>43 <tr>44 <td align="center"><img src="docs/screenshots/mobile/ka2.webp" width="200" alt="ka2 mobile"><br><sub>mobile</sub></td>45 <td align="center"><img src="docs/screenshots/mobile/ka4.webp" width="200" alt="ka4 mobile"><br><sub>mobile</sub></td>46 <td align="center"><img src="docs/screenshots/mobile/ka6.webp" width="200" alt="ka6 mobile"><br><sub>mobile</sub></td>47 </tr>48</table>4950---5152## Cycle de vie d'une mission5354```55api-ka /monitoring/connectors nœud de l'app (runner :7791)56 │ (scan aux 5 min) │57 ▼ ▼58 ① DÉTECTION ──► incident ──► ② MISSION claude -p headless59 │ (diagnostic, correctif minimal,60 │ test réel, commit [kaX] …)61 ▼62 ③ SURVEILLANCE 8 h (watching)63 │64 ┌───────────────┴───────────────┐65 ▼ ▼66 connecteur ok toujours cassé / app down67 → RÉSOLU ④ ROLLBACK git + pm2 restart68 (3 tentatives max → abandoned)69```70711. **Détection** — toutes les 5 min, chaque agent lit la supervision centralisée72 d'api-ka (`/api/v1/monitoring/connectors`, ~2 800 connecteurs classés73 ok/degraded/broken/stale toutes les 2 h). Un connecteur `broken` ou `stale`74 de son périmètre → incident.752. **Mission** — l'agent dépêche une mission au **runner** du nœud qui héberge76 l'app : `claude -p` headless (Claude Code CLI, `--output-format stream-json`),77 lancé dans le repo de l'app, avec un prompt de mission strict : diagnostiquer,78 reproduire, corriger minimalement (mêmes patterns que les connecteurs voisins),79 re-tester en volume réel, `pm2 restart` du process de sync, commit80 `[kaX] fix connecteur …` — **jamais de push par la mission elle-même**81 (voir le pousseur plus bas). La pile d'escalade anti-bot du Groupe KA82 (curl → Scrapfly → Bright Data → proxys résidentiels Oxylabs → Serper/Tavily)83 est à sa disposition sur le nœud.843. **Surveillance** — après réparation déclarée, l'incident passe en `watching`85 pendant 8 h. Connecteur de retour à `ok` → résolu.864. **Rollback automatique** — si l'app tombe (healthcheck) ou si le connecteur87 est toujours cassé après la fenêtre : retour au commit d'avant mission88 (`git reset --hard`/revert) + `pm2 restart`. 3 tentatives max (cooldown 6 h89 entre tentatives), puis `abandoned` (intervention humaine, ré-examen après 7 jours).905. **Vitrine live** — chaque site est une salle de contrôle : flux SSE en direct de91 chaque action de l'agent (outils, réflexions, verdicts), board d'incidents,92 couverture par service (« Territoire surveillé »), registre des missions avec93 transcript complet, nombre de tours, durée et coût API par mission.9495### Garde-fous (politique `topology.json`)9697- 1 mission à la fois par agent **et** par nœud (le runner refuse s'il est occupé).98- Plafonds de mission : 70 tours / 1 h (efforts commandés : 150 tours / 2 h).99- Seuil d'incident de masse (≥ 20 connecteurs d'un coup) : pas de missions en100 rafale — c'est presque toujours une panne d'infrastructure, pas 20 bugs.101- Push git **jamais** fait par la mission : commits `[kaX]` locaux seulement,102 poussés par le pousseur (chaîne launchd de confiance, voir Architecture).103104## Veilleur de sites (2026-08-25)105106En plus des connecteurs, chaque agent surveille le **site public** de chacun de ses107services (`site_engine` dans `main.py`, source d'incident `_site`) :1081091. GET du site de chaque service toutes les 120 s ; down = ≥ 500/timeout, confirmé110 par un 2ᵉ essai puis 2 cycles consécutifs.1112. Down confirmé → **pm2 restart automatique** via l'endpoint `/restart` du runner112 du nœud (throttle 10 min), re-check du site.1133. Toujours down → incident `site_down` (priorité max au dispatch) → **mission114 Claude d'investigation** sur le nœud : logs pm2, cause racine (crash, port,115 build, DB, disque, tunnel ngrok), correctif minimal, commit.1164. Cycle standard ensuite : watching (fenêtre courte 1 h), rollback si faux117 « réparé », cooldown 1 h, max 3 tentatives puis abandon (ré-examen après 24 h).118 Les restarts automatiques continuent pendant les cooldowns.119120`vraiprix` (M3U96a, :8090) est un service **site seulement** de ka6 : aucun121connecteur sous api-ka, seule la surveillance du site s'applique.122123## Efforts commandés — la page `/commander`124125Chaque site expose un **poste de commande** (`/commander`, « Donne-lui du126travail. ») : un opérateur muni du **jeton d'opérateur** (jamais publié — il vit127dans `~/.ka-guardian.env` des nœuds) peut commander un effort autonome à l'agent :128129| Type d'effort | Ce que fait l'agent |130|---|---|131| **Nouveau connecteur** (`effort_new`) | Cartographie l'existant, **découvre des sources québécoises non couvertes via Serper** (gl=ca, hl=fr — sitemaps, pages listes, endpoints JSON internes), évalue 3-5 candidats (volume, faisabilité, qualité, stabilité), choisit le meilleur et construit le connecteur complet — testé en volume réel. |132| **Enrichissement** (`effort_enrich`) | Améliore un connecteur existant : couverture, champs, robustesse. |133| **Inspection des dégradés** (`effort_degrade`) | Passe en revue les connecteurs `degraded` du service et les remet d'aplomb. |134135L'opérateur fixe **la laisse** : durée max et budget max (coût API estimé en direct).136Plafond atteint → la session s'arrête proprement ; les réparations déjà committées137et testées sont conservées si la plateforme est saine. Une consigne libre optionnelle138oriente l'agent (« vise les microbrasseries de la Côte-Nord… »). Chaque effort est139journalisé action par action dans le flux, listé dans « Efforts commandés récents »,140et annulable par rollback git. Contrairement aux incidents api-ka, un effort livré141est validé par healthcheck de l'app (pas par la supervision) : app en échec142post-effort → rollback préventif automatique.143144API équivalente : `POST /api/admin/effort` (header `X-KA-Token`).145146---147148## Architecture149150```151 M4M36 (nœud orchestrateur)152 ┌────────────────────────────────────────────────────────────┐153 │ com.ka2.guardian :8799 com.ka4.guardian :8899 │154 │ com.ka6.guardian :8999 (FastAPI + SQLite data/kaX.db) │155 │ ngrok com.kaX.ngrok → www.ka2.bot / ka4.bot / ka6.bot │156 │ courrier zsh com.ka.guardian-courier (spool → ssh+curl) │157 └───────────────┬────────────────────────────────────────────┘158 │ LAN 192.168.2.x uniquement (via le courrier)159 ┌────────────┼──────────────┬──────────────┬──────────────┐160 ▼ ▼ ▼ ▼ ▼161 M3U96a M3U96b M4M64a M4M64b M4M36162 runner :7791 (com.ka.guardian-runner) sur chaque nœud d'app163 + pousseur git com.ka.pousseur (nœuds à repos Ka)164```165166- **`orchestrator/`** — un process FastAPI par agent (M4M36, launchd167 `com.kaX.guardian`, env `AGENT=ka2|ka4|ka6`), SQLite `data/kaX.db`, dashboard168 servi sur le même port (flux SSE, board incidents, couverture, registre des169 missions + transcripts, `/commander`), tunnels ngrok existants conservés.170- **`runner/`** — un service par nœud d'app (M3U96a/b, M4M64a/b, M4M36 ; :7791,171 launchd `com.ka.guardian-runner`), **1 mission à la fois par nœud**, transcripts172 dans `~/ka-guardian-runner/transcripts/`. Exécute `claude -p --output-format173 stream-json` dans le repo de l'app et relaie chaque événement à l'orchestrateur174 (`/api/ingest`). Expose aussi `/restart` (pm2) pour le veilleur de sites et175 `/health` (`busy`). ⚠️ Ne jamais redémarrer un runner occupé : ça tue la176 mission Claude en vol.177- **`topology.json`** — source de vérité : agents (port/domaine/accent/tagline/178 modèle/services), services (app, nœud, dir, process pm2, port web, site),179 IP LAN des nœuds, politique (fenêtres, cooldowns, plafonds).180- **`deploy/courier.sh`** — courrier inter-nœuds 100 % zsh (launchd181 `com.ka.guardian-courier`). macOS 26 « Local Network Privacy » refuse le trafic182 LAN dès que python (homebrew) est dans la chaîne de processus ; le courrier183 (binaire responsable : zsh) expédie donc les requêtes via spool :184 `spool/outbox/<id>.job → ssh <nœud> curl http://127.0.0.1:<port><path>` →185 `spool/done/<id>.resp`, avec 3 tentatives et multiplexage SSH. Ne pas le contourner.186- **`deploy/pousseur.sh`** — pousseur git (launchd `com.ka.pousseur` sur les nœuds187 qui hébergent des repos Ka). Chaîne 100 % binaires Apple188 (launchd → zsh → `/usr/bin/git` → `/usr/bin/ssh`) : contourne le blocage LNP des189 `git push` lancés par les missions (descendants du runner python homebrew).190 Toutes les 5 min, pousse vers spbgit les commits en attente des repos listés dans191 `~/.ka-pousseur-repos`. Push **simple** uniquement (jamais de force) : un192 non-fast-forward est loggé, jamais résolu d'autorité.193- **Auth interne** — token partagé entre orchestrateurs et runners (fichier194 `~/.ka-guardian.env` sur chaque nœud, header `X-KA-Token`). Clé Anthropic et195 clés anti-bot : `~/.claude/.env` des nœuds. **Aucun secret dans ce repo.**196- **Communication par le LAN 192.168.2.x** (SSH/Tailscale inter-nœuds bloqué par ACL).197198---199200## Visite guidée — ka2 (www.ka2.bot)201202*Gardien immobilier & local — Lou·Ka, Immo·Ka, Resto·Ka, House·Ka, Rent·Ka. Captures du 2026-08-28 (desktop 1440×900, mobile 390×844).*203204| Capture | Description |205|---|---|206|  | **Accueil** — héro « Il veille. Il répare. Il rend des comptes. », définition *gar·dien* (détecte / répare / surveille / recule), tuiles « L'état du gardien » (1 378 connecteurs sous garde, incidents actifs, missions lancées, réparations confirmées, rollbacks assumés, temps moyen de guérison, coût API total) et amorce du flux temps réel + board d'incidents. |207|  | **Poste de commande `/commander`** — « Donne-lui du travail. » : type d'effort (nouveau connecteur avec découverte Serper, enrichissement, inspection des dégradés), plateforme cible (avec son nœud), consigne libre, laisse durée max / coût max et champ jeton d'opérateur. |208|  | **Territoire surveillé** — couverture live par service : Lou·Ka (M3U96b, 431 connecteurs), Immo·Ka (M4M64A, 140), Resto·Ka (14), House·Ka (M4M64B, 25), Rent·Ka (M4M36, 768), chacun avec sa barre ok/dégradé/cassé/endormi ; en dessous, l'entête du registre des missions. |209|  | **Registre des missions (récentes)** — une ligne par mission : horodatage, connecteur, service, nœud, verdict (ici « RIEN À FAIRE »), commits, tours · durée, coût API. Cliquer une ligne ouvre le déroulé complet, commits inclus. |210|  | **Registre des missions (suite)** — tout l'éventail des verdicts en conditions réelles : RÉPARÉ, ÉCHEC, RIEN À FAIRE, LIVRÉ (efforts commandés), INCONNU, avec tentatives, commits et coûts (de 0,10 $ à 3,64 $ la mission). |211|  | **Fin du registre + pied de page « Zéro boîte noire »** — « Chaque diagnostic, chaque commit, chaque rollback de cet agent est journalisé et affiché ici. Les réparations sont committées dans les repos des plateformes, jamais poussées sans passage humain. » Liens vers les plateformes gardées et les agents frères. |212|  | **Accueil mobile** — la salle de contrôle complète en 390×844 : héro, tuiles d'état, flux, incidents, territoire, registre. |213|  | **`/commander` — bas de page** — plafonds (durée, coût max estimé en direct), jeton d'opérateur, bouton « Lancer l'effort → », liste « Efforts commandés récents » avec statuts (LIVRÉ / TERMINÉ) et rappel « La laisse est réelle ». |214|  | **Poste de commande mobile** — le formulaire d'effort complet au téléphone. |215|  | **Flux en temps réel (SSE)** — le terminal « KA2 — FLUX EN TEMPS RÉEL » : chaque outil, réflexion et verdict de l'agent y est diffusé en direct ; au repos, « en attente d'activité — le gardien scrute api-ka toutes les 5 minutes… ». |216217## Visite guidée — ka4 (www.ka4.bot)218219*Gardien mobilité & quotidien — Auto·Ka, Food·Ka, Sorti·Ka. Accent ambre.*220221| Capture | Description |222|---|---|223|  | **Accueil** — même gabarit que ses frères, aux couleurs de ka4 : héro, définition *gar·dien*, tuiles d'état de son périmètre mobilité & quotidien, flux temps réel et incidents. |224|  | **Poste de commande `/commander`** — commander un effort à ka4 : nouveau connecteur (découverte Serper), enrichissement ou inspection des dégradés sur Auto·Ka, Food·Ka ou Sorti·Ka, avec laisse durée/coût et jeton d'opérateur. |225|  | **Flux + incidents + Territoire surveillé** — couverture live des trois services (Auto·Ka sur M4M64b, Food·Ka sur M4M64b, Sorti·Ka sur M3U96a) avec barres ok/dégradé/cassé/endormi, puis le registre des missions. |226|  | **Accueil mobile** — la salle de contrôle ka4 en 390×844. |227|  | **`/commander` — bas de page** — plafonds, jeton d'opérateur et « Efforts commandés récents » de ka4. |228|  | **Poste de commande mobile.** |229|  | **Flux en temps réel (1/4)** — le terminal SSE de ka4. |230|  | **Flux en temps réel (2/4)** — chaque action de mission (outil lancé, fichier lu, test exécuté) s'affiche ici à mesure. |231|  | **Flux en temps réel (3/4)** — le même flux que consomme le board d'incidents et le registre. |232|  | **Flux en temps réel (4/4)** — au repos : « en attente d'activité — le gardien scrute api-ka toutes les 5 minutes… ». |233234## Visite guidée — ka6 (www.ka6.bot)235236*Gardien flagship — gros volumes : Fabri·Ka, Job·Ka, Créa·Ka, Vrai·Prix (site seulement) + tout nouveau service par défaut. Accent violet.*237238| Capture | Description |239|---|---|240|  | **Accueil** — le plus gros périmètre du trio : 2 819 connecteurs sous garde, 251 missions lancées, 89 réparations confirmées, 14 rollbacks assumés, 3,3 h de temps moyen de guérison ; incidents en SURVEILLANCE (fabrika, jobka) visibles au chargement. |241|  | **Poste de commande `/commander`** — commander un effort à ka6 sur Fabri·Ka, Job·Ka ou Créa·Ka (nouveau connecteur découvert via Serper, enrichissement, inspection des dégradés). |242|  | **Flux + incidents + Territoire surveillé** — couverture live de Fabri·Ka (M4M64a), Job·Ka (M3U96a), Créa·Ka (M3U96b) et Vrai·Prix (M3U96a, surveillance du site seulement). |243|  | **Registre des missions (1/5)** — le registre le plus long du trio : gros volumes = plus d'incidents, plus de missions, plus de verdicts. |244|  | **Registre des missions (2/5)** — missions récentes avec verdicts, tours, durées et coûts par connecteur. |245|  | **Registre des missions (3/5)** — l'historique se déroule : réparations confirmées, échecs assumés, missions « rien à faire ». |246|  | **Registre des missions (4/5)** — chaque ligne reste cliquable : déroulé complet de la mission, commits inclus. |247|  | **Registre des missions (5/5) + pied de page « Zéro boîte noire »** — fin de l'historique et engagement de transparence. |248|  | **Accueil mobile** — la salle de contrôle ka6 en 390×844. |249|  | **`/commander` — bas de page** — plafonds, jeton d'opérateur et « Efforts commandés récents » de ka6. |250251---252253## Transparence publique254255Le principe fondateur des gardiens : **zéro boîte noire.**256257- Chaque diagnostic, chaque commit, chaque rollback est journalisé et affiché en258 direct sur le site de l'agent (flux SSE, board d'incidents, registre des missions259 avec transcript, tours, durée et coût API au cent près).260- Les réparations sont committées `[kaX] …` dans les repos des plateformes et261 poussées par le pousseur vers le git du Groupe — jamais de force-push, jamais de262 résolution d'autorité.263- Les trois agents sont présentés publiquement sur264 **[groupe-ka.com/bots](https://www.groupe-ka.com/bots)**, et chaque site gardien265 lie ses frères et les plateformes qu'il garde.266- Les actions sensibles (`/commander`, API admin) exigent le jeton d'opérateur —267 la consultation, elle, est ouverte à tous.268269## Déploiement270271- **Nœud de production : M4M36** — répertoire `~/cluster-projects/ka-guardian`272 (ce repo, origin = gitsrv/spbgit `ka-guardian.git`).273- **Process : launchd** (PAS pm2) — `com.ka2.guardian` (:8799), `com.ka4.guardian`274 (:8899), `com.ka6.guardian` (:8999). Tunnels ngrok `com.kaX.ngrok` (ne pas toucher).275- Pas d'étape de build : Python servi en place (`.venv` local au nœud).276277```bash278deploy/deploy.sh all # runners + orchestrateurs (+ courrier)279deploy/deploy.sh runners # seulement les 5 runners (refuse un runner occupé)280deploy/deploy.sh orchestrators # ka2/ka4/ka6 sur M4M36 (tar-over-ssh + md5 + relance launchd)281```282283Après toute modification sur M4M36 :284285```bash286launchctl kickstart -k gui/$(id -u)/com.ka2.guardian # idem ka4/ka6287curl -sf localhost:8799/health # puis 8899, 8999 + site public288git add … && git commit && git push origin main # origin = gitsrv/spbgit, PAS GitHub289```290291## Admin (token requis)292293```bash294# mission manuelle sur un connecteur295curl -X POST http://M4M36.maclustr.io:8799/api/admin/mission \296 -H "X-KA-Token: $TOKEN" -d '{"service":"louka","source":"kijiji"}'297# effort commandé (équivalent API de /commander)298curl -X POST http://M4M36.maclustr.io:8799/api/admin/effort \299 -H "X-KA-Token: $TOKEN" -d '{"kind":"effort_new","service":"restoka"}'300# pause / reprise d'un agent301curl -X POST http://M4M36.maclustr.io:8799/api/admin/pause \302 -H "X-KA-Token: $TOKEN" -d '{"paused":true}'303```304305## Repo & contact306307- **Repo** : `ka-guardian.git` sur **spbgit** (le git personnel du Groupe —308 git.spboucher.ai, bare repos sur M3U96a). Origin des nœuds : `gitsrv:srv/git/ka-guardian.git`.309- **Structure** : `orchestrator/` (main.py + web/), `runner/runner.py`,310 `deploy/` (deploy.sh, courier.sh, pousseur.sh, make_og_images.py),311 `topology.json`, `docs/screenshots/`.312- **Contact** : [groupe-ka.com](https://www.groupe-ka.com) — Groupe KA,313 agrégation automatisée, Québec.314315## Historique316317Les anciens bots (cartographie du web québécois / influenceurs) sont archivés :318`~/ka-bots-backup-20260823.tar.gz` sur M4M36 (code + bases SQLite complètes).319