Docs · Internals
Un contrat pour tous les agents de code
Project Orchestrator joint Claude Code, un modèle compatible OpenAI, Codex ou n'importe quel agent ACP par le même petit jeu de types. Cette page parcourt ce contrat, qui vit dans le SDK nexus.
Ce que ça fait
Le backend ne parle jamais le protocole d'un fournisseur. Il ouvre une session sur un provider et lit un flux d'événements neutres.
Chaque provider déclare ce qu'il sait faire, modèle par modèle. Quand une capacité manque, le contrat applique un repli écrit ou répond Unsupported, jamais un succès silencieux.
Les permissions, les erreurs et les jetons de reprise ont aussi une forme neutre : le tableau de bord montre les mêmes cartes quel que soit l'agent dessous.
Le schéma
Fais glisser pour te déplacer. Pince, Ctrl + molette ou les touches + et - pour zoomer ; flèches pour bouger ; 0 ou double-clic pour ajuster. Choisis un nœud pour allumer ses liens.
Description textuelle du schéma
Schéma de flux. Le ChatManager du backend demande un provider au ProviderRegistry. Le registre garde les fournisseurs de modèle à part des harnais et vérifie la paire avant tout lancement. Un AgentProvider ouvre ou reprend une AgentSession. La session produit des AgentEvent, applique une ToolPolicy et signale des ProviderError. Le provider expose des Capabilities par modèle et la session peut émettre un ResumeToken. En bas, les anciens types du client Claude Code sont rattachés aux types neutres.
Lecture guidée
Étape 1. Un seul registre
Un unique ProviderRegistry dans nexus associe un identifiant d'instance à un AgentProvider, construit à la demande et mis en cache. La configuration d'une instance ne contient aucun secret, seulement une référence : vault:nom, env:VAR ou none. L'instance claude-code intégrée ne peut pas être supprimée, et une configuration modifiée se recharge sans perturber les sessions déjà ouvertes.
Étape 2. Harnais et modèle sont appariés, et la paire est vérifiée
Un fournisseur de modèle est gardé à part du harnais. Avant tout lancement, open_session vérifie que le harnais consomme le protocole que parle le fournisseur de modèle (anthropic_messages, openai_chat ou openai_responses). Une paire incompatible est refusée avec model_protocol_mismatch.
Étape 3. AgentProvider
Un provider expose son identifiant et son genre, un contrôle de santé qui renvoie une valeur au lieu d'échouer, le catalogue de modèles, les capacités d'un modèle donné, et open ou resume pour créer une session.
Étape 4. AgentSession
Une session mène la conversation : send_turn, answer_permission, answer_question, interrupt et cancel_tools avec une portée, set_model, set_policy_mode, out_of_band et close. Un tour se termine par exactement un événement terminal, Done ou Error.
Étape 5. Les types neutres
AgentEvent a 17 variantes. ToolPolicy combine un mode avec des listes allow et deny, et deny l'emporte. Capabilities a 18 champs par modèle, chacun avec un repli écrit. Un ResumeToken est opaque pour tout sauf le provider qui l'a émis. ProviderError a 17 genres ; chacun sait s'il peut être réessayé, et ses détails sont expurgés.
Étape 6. Ce que le contrat enveloppe
Les boîtes de gauche sont le code qui existait avant : le client Claude Code, ses messages, ses modes de permission et ses erreurs. Chacune est rattachée à un type neutre, c'est ainsi que le premier provider a été écrit sans changer ce que reçoit le tableau de bord.
Pourquoi c'est conçu ainsi
Refuser plutôt que faire semblant
Une capacité absente renvoie Unsupported ou applique le repli écrit. Un provider qui ne sait pas annuler des outils le dit. Le contrat ne déclare jamais un succès qui n'a pas eu lieu.
Deny l'emporte, et une règle mal formée est une erreur
Dans une ToolPolicy, un deny l'emporte toujours sur un allow. Un motif mal formé ou un mode inconnu échoue à la construction : une règle deny perdue en silence élargirait la politique.
Une version testable
CONTRACT_VERSION monte dès qu'une forme sérialisée ou une signature de trait change. Les instantanés JSON des tests portent la version : changer une forme sans la faire monter casse le build. La constante vaut 3 aujourd'hui, et les montées jusqu'ici étaient additives.
Aucun secret dans la configuration
La configuration ne porte que des références. Le résolveur d'identifiants transforme vault:nom en secret au dernier moment. Un coffre verrouillé répond credentials_locked au lieu de basculer sur un autre provider, et les messages d'erreur ne répètent jamais un identifiant.
Un tour à la fois
send_turn pendant un tour actif renvoie turn_in_progress. Pas de file cachée, pas d'interruption implicite : la file d'attente reste dans le backend.
Ce qui n'est pas établi
- Le lien modèle-harnais n'est pas appliqué à Codex (sa configuration de fournisseur personnalisé n'a pas été vérifiée contre un vrai app-server) ni à ACP (l'agent choisit son modèle). Aucune vraie passerelle tierce n'a été essayée.
Sources publiques
Où vérifier chaque affirmation, dans les dépôts publics.