Aller au contenu

Docs · Internals

Quel provider fait tourner cette session ?

Quand une session de chat s'ouvre, le backend doit choisir un provider. La règle est une courte liste ordonnée, stricte sur le moment où elle peut changer d'avis.

Ce que ça fait

Une session qui existe déjà garde son provider toute sa vie. Sinon le premier niveau qui nomme un provider gagne : requête, tâche, persona, run, règle de projet, règle globale, puis le défaut configuré.

Un choix explicite n'est jamais remplacé. Un provider inconnu, interdit ou malsain est une erreur, pas un repli discret.

Seul le rôle exécutant peut se replier sur le niveau suivant, et jamais vers une instance non autorisée.

Le schéma

Comment le provider d'une session est résoluSchéma de flux. L'ouverture d'une session demande d'abord si la session existe. Si oui, son provider est figé et une requête qui en nomme un autre est refusée avec provider_conflict. Sinon, les niveaux sont parcourus dans l'ordre : requête, tâche, persona, run, règle de projet, règle globale, défaut configuré. Un choix explicite inutilisable est refusé avec provider_unknown, endpoint_not_allowed ou provider_unavailable. Sinon le rôle décide : un pilote ne se replie jamais, un exécutant peut se replier sur le niveau suivant. Sans rien de configuré, claude-code est utilisé s'il existe, est sain et autorisé, sinon no_provider. Chaque chemin finit par l'ouverture de la session, qui peut échouer avec une erreur typée.yesyes + other providernodecider installedyes, not usablenono level setchain exhaustedyes, usableopen a chat sessionsession already exists?provider frozen on the sessionrouted_by = sessionnever resolved again409 provider_conflictrequest names another providerlevels, in order: request, task, persona, run,project rule, global rule, configured defaultthe first level that names a provider winsauto level, routed_by = autoonly when a decider is installed and mode and stage applymixed: executors · full: everyone · advisory: executors ·shadow/primary: neverfills the project rule slot: below run, above the global rulethe ticked models (routing_pool) are the only candidates atopennever replaces request, task, persona or runexplicit choice?request, task, personanever substitutedprovider_unknown 404endpoint_not_allowed 403provider_unavailable 503rolepilotno fallback at any levelexecutorunhealthy or forbidden level: next levelrouted_by = fallbacknever to a forbidden instancenothing configuredclaude-code if it exists, is healthy, allowed and its CLI is on theserverelse 409 no_provideropen the session on the chosen providertyped failures: cli_not_found 424, credentials_locked 423,unauthorized 502, model_no_tools 422, rate_limited 429, ...switch provider on the same sessionrefusals typed: empty_message 400, same_provider 400,invalid id 400, unknown session 404, else the new session’sopening refusal

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.

DézoomerZoomerPlein écran
Redessiné depuis le diagramme vérifié po-chat-provider (vérifié 878281ca). Les libellés sont les noms utilisés dans le code.
Description textuelle du schéma

Schéma de flux. L'ouverture d'une session demande d'abord si la session existe. Si oui, son provider est figé et une requête qui en nomme un autre est refusée avec provider_conflict. Sinon, les niveaux sont parcourus dans l'ordre : requête, tâche, persona, run, règle de projet, règle globale, défaut configuré. Un choix explicite inutilisable est refusé avec provider_unknown, endpoint_not_allowed ou provider_unavailable. Sinon le rôle décide : un pilote ne se replie jamais, un exécutant peut se replier sur le niveau suivant. Sans rien de configuré, claude-code est utilisé s'il existe, est sain et autorisé, sinon no_provider. Chaque chemin finit par l'ouverture de la session, qui peut échouer avec une erreur typée.

Lecture guidée

  1. Étape 1. La session existe-t-elle déjà ?

    Si oui, son provider est figé (routed_by vaut session) et n'est jamais résolu de nouveau. Une requête qui nomme un autre provider reçoit 409 provider_conflict.

  2. Étape 2. Parcourir les niveaux

    Sinon les niveaux sont essayés dans l'ordre : requête, tâche, persona, run, règle de projet, règle globale, défaut configuré. Le premier niveau qui a un provider gagne.

  3. Étape 3. Un choix explicite est définitif

    Un choix fait dans la requête, la tâche ou la persona n'est jamais remplacé. Inconnu donne 404 provider_unknown, interdit donne 403 endpoint_not_allowed, malsain donne 503 provider_unavailable.

  4. Étape 4. Le niveau auto, facultatif

    Quand un décideur cognitif est installé et que le mode et l'étape le permettent, le provider et le modèle choisis prennent la place de la règle de projet, sous le run et au-dessus de la règle globale, et la session enregistre routed_by auto avec une raison lisible. Une requête, une tâche, une persona ou un run qui nomme un provider n'est jamais remplacé. Sans décideur, rien ne change.

  5. Étape 5. Les rôles

    Le rôle pilote ne se replie jamais, à aucun niveau. Pour un exécutant, un niveau non explicite malsain ou interdit passe la main au niveau suivant, et la session note qu'elle a été routée par repli. Une instance interdite n'est jamais choisie.

  6. Étape 6. Le défaut intégré

    Si rien n'est configuré, ou si la chaîne de l'exécutant est épuisée, claude-code est utilisé quand il existe, est sain et autorisé pour le projet. Sinon la réponse est 409 no_provider.

  7. Étape 7. L'ouverture peut encore échouer, avec un code

    Chaque échec a un code et un statut HTTP : cli_not_found 424, credentials_locked 423, unauthorized 502 (jamais 401), model_no_tools 422, rate_limited 429, etc. Un CLI absent répond 424 avec un code au lieu d'un 500 muet.

  8. Étape 8. Faire passer une conversation à un autre provider

    Une session ne change jamais de provider : faire passer une conversation (POST /api/chat/sessions/{id}/switch-provider) ouvre une nouvelle session sur la cible et ne ferme l'ancienne qu'une fois la nouvelle ouverte. L'historique stocké est rendu en texte, un appel d'outil devenant une ligne au résultat borné, et placé devant ton message. Au-delà de 40 % de la fenêtre de la cible, les entrées les plus anciennes sautent et le relais le dit ; aucun modèle ne résume quoi que ce soit. Un événement conversation_relayed le dit sur les deux fils. Le consentement, la garde d'endpoint et la porte de sécurité jouent comme pour tout choix explicite, et un refus laisse l'ancienne session ouverte. Un outil en cours au moment du basculement n'est pas transporté.

Pourquoi c'est conçu ainsi

Fixé par session

Résoudre de nouveau sur une conversation en cours pourrait la faire passer chez un autre fournisseur au milieu. Un provider figé garde l'historique, le coût et les jetons de reprise cohérents.

Explicite veut dire explicite

Si tu as choisi un provider, en substituer un autre changerait le coût et la destination de tes données sans te le dire.

Le pilote ne se replie pas

Le pilote est celui à qui tu parles, et un changement discret modifierait qui répond. Les exécutants qui font un travail délégué peuvent prendre le niveau configuré suivant, et le changement est noté.

Un coffre verrouillé est une erreur

Les identifiants sont des références résolues depuis le coffre au moment voulu. Un coffre verrouillé répond credentials_locked ; il ne bascule jamais vers un provider qui n'aurait besoin d'aucun identifiant.

Ce qui n'est pas établi

  • Non établi : un basculement de provider n'a jamais été rejoué contre un vrai Claude Code ni un vrai Codex, seulement contre des faux.