claude-orchestrator

Sonde de vivacité. Jamais protégée par le token.

{ "status": "ok", "nodeId": "mac-a1b2c3", "uptimeSeconds": 412,
  "sessions": { "live": 2, "total": 5 } }

Identité du nœud (nodeId, hostname, platform, sdkVersion, claudeCodeVersion, startedAt) et configuration publique : maxLiveSessions, allowedCwdRoots, sessionStore, cible S3, claudeCodePath, eventLogSize, permissionTimeoutMs.

Le nodeId est persisté dans data/node-id : il survit aux redémarrages et étiquette chaque événement.

config.projectRoots est le nombre de racines configurées, pas leur chemin : la liste des projets ouvrables se lit sur GET /v1/projects.

Les projets dans lesquels une session peut s'ouvrir : les répertoires de premier niveau des racines configurées. C'est la liste des valeurs acceptables pour le cwd de POST /v1/sessions. Les répertoires cachés sont ignorés.

{ "projects": [
    { "name": "mon-projet",    "git": true },
    { "name": "autre-projet",  "git": false },
    { "name": "homonyme",      "git": true, "ambiguous": true }
] }

git indique la présence d'un .git. ambiguous marque un nom présent sous plusieurs racines : il est refusé à la création, il faut désigner le projet autrement. Aucun chemin absolu n'apparaît dans cette réponse.

Liste vide si aucune racine n'est configurée — aucune session ne peut alors démarrer.

Crée une session, en reprend une (resume) ou la branche (resume + fork). Les clés inconnues sont refusées — une faute de frappe est une erreur 400, pas un silence.

curl -s -X POST $NODE/v1/sessions -H "$AUTH" -H 'content-type: application/json' -d '{
  "cwd": "mon-projet",
  "prompt": "Analyse le module auth et propose un plan de refactoring.",
  "permissionMode": "default",
  "maxTurns": 50,
  "title": "Refacto auth"
}'
# → 201 { "sessionId": "…", "state": "starting", "session": { … } }

Où une session peut s'ouvrir

Le cwd est un nom de projet relatif, jamais un chemin : mon-projet, ou mon-projet/sous-dossier pour travailler plus bas dans l'arborescence. Un chemin absolu est refusé en 400. Le nœud le résout contre ses racines configurées (ALLOWED_CWD_ROOTS) et lance le subprocess claude dans le répertoire obtenu.

Les valeurs acceptables se lisent sur GET /v1/projects. L'arborescence du nœud ne sort jamais de l'API : un client ne peut ni lire un chemin absolu dans une réponse, ni en imposer un, donc ni sonder le disque hors des racines.

Ce contrôle borne le répertoire de démarrage, pas la portée des outils : le subprocess tourne sous l'utilisateur du nœud, et un outil invoqué avec un chemin absolu sort de l'arborescence. Le garde-fou réel est permissionMode: "default", qui fait passer chaque outil non pré-approuvé par l'API de permissions.

Sessions présentes sur ce nœud, vivantes ou récemment terminées. Pour les sessions d'autres nœuds, voir le store.

Instantané : state, cwd, model, permissionMode, title, createdAt, stats (tours, coût, erreurs de miroir), demandes de permission en attente, error le cas échéant.

Change le mode de permission ou le modèle à chaud. Au moins un des deux champs est requis.

{ "permissionMode": "acceptEdits" }        // ou { "model": "claude-sonnet-5" }

bypassPermissions est refusé ici : on n'élève pas les privilèges d'une session en vol.

Met un message en file. Le CLI les traite séquentiellement ; la réponse est immédiate et porte l'uuid attribué au message. Les frames assistant et result qui en découlent le citent dans user_message_uuids — c'est ainsi qu'on corrèle un envoi à sa réponse.

{ "content": "Applique le plan, étape 1 seulement." }
{ "content": [ { "type": "text", "text": "…" }, { "type": "image", "source": { … } } ] }

Historique conversationnel lu depuis le store : la chaîne effective après compaction, pas le journal brut.

Interrompt le tour en cours. La session reste vivante et repasse en idle.

Arrêt gracieux : ferme la file d'entrée et laisse le subprocess terminer. { "force": true } le tue à la place.

Arrête la session et la retire du registre du nœud. Avec ?purge=true, supprime aussi le transcript du store — irréversible, et la session n'est alors plus reprenable nulle part.

Demandes en attente : requestId, nom de l'outil, entrée proposée, suggestions du SDK.

{ "behavior": "allow", "updatedInput": { … }, "remember": true }
{ "behavior": "deny",  "message": "Pas ce fichier", "interrupt": true }

updatedInput remplace l'entrée de l'outil. remember réutilise les suggestions du SDK mais toujours à portée de session : rien n'est écrit dans les settings de la machine. interrupt coupe le tour en plus de refuser.

Replay depuis ?since=<seq> ou l'en-tête Last-Event-ID, puis temps réel. Le tampon par session est borné par EVENT_LOG_SIZE ; si la reprise demande plus ancien que le tampon, un événement gap précède le replay — c'est le signal qu'il faut relire l'historique via /messages plutôt que de supposer la continuité.

curl -N -H "$AUTH" "$NODE/v1/sessions/$SESSION_ID/events?since=41"

Flux global : tous les événements de toutes les sessions du nœud, même enveloppe.

Les projectKey présents dans le store.

Sessions stockées d'un projet : résumé SDK, métadonnées de nœud (qui l'a créée, quand), et si elle est vivante ici.

cwd est ici aussi un nom de projet relatif. projectKey reste accepté comme identifiant direct.

curl -s -H "$AUTH" "$NODE/v1/store/sessions?cwd=mon-projet"

Une session stockée.

Historique d'une session stockée, sans la reprendre.

Supprime du store. 409 si la session est vivante sur ce nœud : l'arrêter d'abord.