relay_tool Ajouté en 0.9.4

Avec relay_tool, un agent travaille avec d’autres sessions : il les liste et les lit, envoie un prompt à l’une d’elles, en démarre une nouvelle, attend la réponse, répond à une question posée par l’autre agent, arrête ou archive une session, et peut demander à être réveillé quand quelque chose se passe dans les sessions qu’il surveille.

Il atteint deux sortes de relais :

• Ce relais, celui sur lequel l’agent lui-même tourne. Un agent peut confier des parties de sa tâche à d’autres sessions ici. Désactivé tant que vous ne l’activez pas. Ajouté en 0.9.7
• Les relais associés, d’autres relais OAR que vous avez associés à celui-ci, par exemple le relais de votre poste de travail et celui d’un serveur. Verrouillés dans chaque conversation tant que vous ne mentionnez pas le relais.

L’outil est le même pour tous les fournisseurs qui le proposent ; voir Par fournisseur pour savoir lesquels, et sous quel nom.

Le nom Ajouté en 0.9.18 #

Jusqu’à 0.9.17, l’outil s’appelait remote_relay. Il est désormais listé sous relay_tool chez tous les fournisseurs (l’agent de Claude voit mcp__relay__relay_tool), avec les mêmes actions et les mêmes champs. Les lignes d’outil écrites sous l’ancien nom s’affichent toujours comme cet outil.

• Les sessions qui tournaient pendant la mise à jour. L’agent d’une session reçoit sa liste d’outils au démarrage de son worker, et les workers continuent de tourner pendant le redémarrage du relais. L’agent d’une telle session a toujours l’outil sous le nom remote_relay jusqu’au prochain démarrage de son worker, par exemple après Kill session (Tuer la session). Ses appels continuent de fonctionner : ils atteignent le relais de la même façon sous l’un ou l’autre nom. Là où le relais tourne comme service Linux, les workers peuvent s’arrêter avec le relais, puis revenir avec le nouveau nom.
• Le serveur MCP propre à OAR, qu’utilisent Grok et le moteur d’extension de Copilot, exécute toujours un appel à remote_relay, mais ne le liste plus.
• Vos propres instructions. Si vos instructions, vos règles de permission ou vos hooks nomment remote_relay ou mcp__relay__remote_relay, remplacez-les par relay_tool ou mcp__relay__relay_tool : en dehors du serveur MCP d’OAR, l’ancien nom est refusé.

Ce que vous voyez #

• Cartes d’approbation. Une carte de question demande avant la première session qu’un agent démarre dans une conversation, avant qu’il surveille des sessions pour la première fois, et avant chaque action d’écriture tant que la conversation est dans le mode du relais ask ou plan.
• L’appel d’outil dans la réponse. L’activité de l’agent affiche chaque appel avec un 🛰️, l’action, le relais et la session.
• "via agent" (via un agent). Une session qu’un agent a démarrée porte via agent · "title" dans la liste des conversations et sous son titre, qui nomme la conversation dans laquelle l’agent tourne. Ajouté en 0.9.11 Elle se trouve dans un groupe de sessions sous cette conversation, Ajouté en 0.9.16 ou dans un groupe existant que l’agent a nommé.
• "↗ from …" (de …). Un prompt envoyé par un agent porte, côté destinataire, un badge avec le relais, la session et le modèle qui l’ont envoyé.
• Surveillance. Une conversation qui en surveille d’autres affiche watching N sessions (surveille N sessions) dans son en-tête ; la puce liste ses abonnements, chacun avec un bouton Unsubscribe (Se désabonner). Une session surveillée affiche un badge watched (surveillé).

L’activer #

relay_tool est proposé aux agents dès qu’au moins une de ces conditions est remplie :

Une session apprend si elle reçoit l’outil au démarrage du processus de son agent ; une conversation qui tournait déjà peut donc ne pas l’avoir tant que son agent n’a pas redémarré.

Nommer un relais #

Toutes les actions sauf list_relays travaillent sur un seul relais, nommé dans relay :

• "this", ou le nom propre de ce relais, désigne le relais sur lequel tourne l’agent. Il n’a pas besoin d’être mentionné.
• Un relais associé est désigné par son nom de relais ou son hôte, tels que list_relays les affiche.

Pour les quatre actions d’abonnement, Ajouté en 0.9.16 les trois actions de planification et les trois actions de question, relay peut être omis et vaut alors "this". Les planifications ne fonctionnent que sur ce relais.

Verrouillé et déverrouillé #

Un relais associé reste verrouillé dans une conversation jusqu’à ce que l’une de ces choses se produise :

• Vous le mentionnez dans l’un de vos messages : tapez @ et choisissez-le, ou écrivez son nom ou son nom d’hôte. Un relais dont le nom est une adresse IP ou localhost ne compte qu’avec un @ devant.
• Un agent de ce relais-là écrit dans la conversation. Le relais est alors ouvert pour que l’agent d’ici puisse répondre.

Une fois déverrouillé, il reste ouvert pour le reste de la conversation. Un relais verrouillé refuse toute action sauf list_relays ; l’agent reçoit la consigne de vous demander de mentionner le relais.

Permissions et approbations #

Ce qu’autorise un relais associé #

Chaque relais associé a un niveau Agents may (Les agents peuvent) sous Settings → Relays. Les nouvelles associations commencent à Full (Accès complet).

list_relays ne demande aucun niveau. Ce relais lui-même compte toujours comme Full.

De l’autre côté, Accept prompts from other relays' agents (Accepter les prompts des agents d’autres relais) (Settings → Relays sur le relais associé) désactive tout ce que les agents d’un autre relais pourraient y modifier ou surveiller : envoyer des prompts, démarrer, répondre, arrêter et archiver des sessions, et s’y abonner. Lister et lire les sessions, lire la sortie des tâches, attendre, relay_info et usage fonctionnent toujours.

Quand on vous demande #

Règles pour les sessions sur ce relais #

• Au plus 4 au travail. Parmi les sessions démarrées par l’agent d’une conversation, 4 peuvent avoir un turn en file ou en cours en même temps. Une cinquième est refusée jusqu’à ce que l’une d’elles ait terminé.
• Un seul niveau. Une session créée par un agent ne peut pas créer de sessions elle-même, Ajouté en 0.9.16 sauf si vous avez activé Agents in this conversation may start sessions (Les agents de cette conversation peuvent démarrer des sessions) pour elle. list_sessions et read_session affichent alors "mayCreateSessions": true. Aucun agent ne peut régler cet interrupteur.
• Pas sur elle-même. Un agent ne peut pas utiliser send, wait, stop ni archive sur la conversation dans laquelle il tourne, ni répondre à sa propre question, Ajouté en 0.9.16 ni modifier ses réglages.
• Vos comptes. Les sessions qu’un agent démarre utilisent les comptes fournisseur de ce relais et entrent dans leur consommation.
• Le relais n’archive jamais ces sessions de lui-même. Elles restent dans votre liste jusqu’à ce que vous les archiviez ou les supprimiez, ou que l’agent en archive une.

D’un relais à l’autre #

• Un prompt qui a déjà traversé deux relais n’est pas transmis à un troisième, sauf si vous avez déverrouillé ce relais-là vous-même. La lecture et l’attente ne sont jamais limitées par cette règle.
• Le prompt que reçoit l’autre agent commence par une ligne qui indique qu’un autre agent lui parle : [Remote prompt from an agent on relay "…" · session "…" · model · acting for the user].
• Les turns démarrés ainsi n’envoient aucune notification « reply ready » sur l’autre relais. Les cartes de question notifient toujours.
• Les adresses distantes doivent utiliser https://. Le simple http:// n’est accepté que pour l’adresse de bouclage et les plages de réseau privé.

Actions #

Chaque appel nomme une action. Le tableau montre ce dont chacune a besoin ; le niveau est le réglage Agents may le plus bas qui l’autorise sur un relais associé.

Un résultat est du JSON. Un appel réussi contient "ok": true, le relay sur lequel il a travaillé et un summary d’une ligne ; un appel échoué contient "ok": false, un code et un texte error (Erreurs). Les exemples ci-dessous montrent les champs principaux, avec des noms et des ids inventés.

Ajouté en 0.9.16 Un argument qu’une action ne prend pas n’est jamais écarté en silence. create_session et update_session refusent l’appel avec REMOTE_RELAY_INVALID_INPUT, nomment leurs propres arguments et ne changent rien : create_session does not take: session. Its arguments: relay, text, provider, model, cwd, repo, branch, mode, effort, title, group, wait_seconds. Nothing was created. Toutes les autres actions s’exécutent quand même et listent les arguments qu’elles n’ont pas pris dans le champ ignored de leur résultat, jusqu’à 20. Une valeur vide (null, "", false ou une liste vide) compte comme une absence d’argument, car certains fournisseurs envoient tous les champs.

Trouver relais et sessions #

list_relays #

Liste les relais associés avec name, url, online, version, permission et unlocked. Quand les sessions d’agent sont activées, ce relais vient en premier, marqué "self": true. Renvoie aussi la limite d’attente de ce relais. C’est la seule action qui fonctionne sans mention et sans relay.

{ "action": "list_relays" }

{
  "ok": true,
  "summary": "list_relays: 2 relays, 1 unlocked",
  "self": { "name": "desk" },
  "relays": [
    { "name": "desk", "self": true, "online": true, "version": "0.9.19", "permission": "full", "unlocked": true },
    { "name": "build-box", "url": "https://build-box.example.com", "online": true, "version": "0.9.19", "permission": "full", "unlocked": false }
  ],
  "limits": { "maxWaitSeconds": 600, "maxActiveSessions": 4 }
}

relay_info #

Ce qu’offre un relais, pour que l’agent puisse choisir un fournisseur, un modèle et un dossier pour une nouvelle session : son nom, sa version et sa plateforme, s’il accepte les prompts d’agents, chaque fournisseur avec son modèle par défaut, ses modèles et ses efforts de raisonnement, les dossiers de travail par défaut et récents, et les modes du relais.

{ "action": "relay_info", "relay": "build-box" }

Ajouté en 0.9.16 Il liste aussi les groupes de sessions du relais dans groups, ceux qu’un create_session sur ce relais peut nommer : chacun avec id, name (ce qu’affiche la barre latérale ; le titre de la session de tête pour un groupe que personne n’a nommé) et memberCount, le groupe à l’activité la plus récente en premier. Seuls les groupes ayant au moins une session non supprimée sont listés, 50 au plus ; groupsTotal indique leur nombre quand il y en a davantage. Les ids et les titres des membres n’y figurent pas. Quand les groupes du relais ne peuvent pas être lus, par exemple parce qu’il fait tourner un OAR plus ancien, groups vaut null et groupsNote indique pourquoi, et que create_session ne peut pas y prendre group.

"groups": [
  { "id": "grp_…", "name": "Release 2.4", "memberCount": 3 },
  { "id": "grp_…", "name": "Review: server/", "memberCount": 2 }
]

usage Ajouté en 0.9.10 #

Ce qui reste au forfait de chaque fournisseur sur un relais, comme dans Check Usage (Vérifier la consommation), pour qu’un agent puisse vérifier avant de lancer un travail qui coûte : par fournisseur, un statut et ses compteurs (consommé, allocation, restant, taux d’utilisation, heure de remise à zéro), et si une limite d’utilisation de Claude a mis les turns en pause sur ce relais. Les fournisseurs non configurés ou non suivis l’indiquent. Les noms de compte, les adresses et les tokens ne sont jamais inclus.

{ "action": "usage", "relay": "this" }

list_sessions #

Liste les sessions avec id, title, provider, model, state, cwd, l’heure de la dernière activité et un nombre de messages. state vaut running_turn, background_only (l’agent a répondu, un travail de fond tourne encore) ou idle ; tasks liste les agents en arrière-plan et les tâches shell.

Ajouté en 0.9.11 Une session d’un groupe de sessions a aussi group : son id, son name et le role de la session dans le groupe, head ou member. Ajouté en 0.9.16 create_session peut placer la session qu’il crée dans un groupe existant, et update_session peut déplacer une session dans un groupe, y compris un nouveau, ou l’en sortir. Renommer, dissoudre et réorganiser les groupes restent de votre ressort.

{ "action": "list_sessions", "relay": "build-box", "scope": "active" }

read_session #

Lit les messages les plus récents d’une session, avec ce qui s’y passe : son state, une réponse encore en cours d’écriture (inFlight), et les pendingQuestions qui attendent une réponse (Ajouté en 0.9.16 chacune avec kind : ask pour une question non bloquante, ask_user pour une carte sur laquelle la session attend). Ajouté en 0.9.11 Pour une session d’un groupe, group ajoute les autres membres, jusqu’à 50, chacun avec id, title, role, state et archived quand il est archivé.

{ "action": "read_session", "relay": "build-box", "session": "3f9c…", "last": 5 }

Ajouté en 0.9.12 Chacune des tasks de la session a aussi son taskId, output (s’il y a une sortie à lire avec read_task_output) et, pour une commande dont la sortie est dans un fichier, health : minutesSinceOutput, quiet et quietAfterMinutes (le réglage de silence du relais) tant qu’elle tourne, et les counts de l’exécution de tests quand il y en a.

read_task_output Ajouté en 0.9.12 #

Lit la fin de la sortie d’une commande shell de fond ou d’un moniteur, la même sortie que celle qu’affiche la console de tâche : pendant que la tâche tourne, et pendant une heure après sa fin. Un agent peut ainsi vérifier si une compilation sur un autre relais est encore occupée, est devenue silencieuse ou a des tests en échec, sans demander à l’agent qui l’a lancée.

Le résultat contient task (description, type, début, status et exitCode), tail (les lignes, en texte brut sans couleurs, une ligne répétée étant marquée [×N]), truncated quand il y a davantage avant elles, stall (les minutes depuis la dernière sortie, et quiet par rapport au réglage du relais) tant que la tâche tourne, et counts avec l’exécuteur de tests et ses tests réussis, échoués et ignorés quand la sortie est une exécution de tests. Les identifiants sont masqués comme dans la console. Une note indique quand seule la fin de la sortie existe, quand la sortie n’est plus là, ou quand le processus de l’agent a été sollicité et que l’appel doit être répété dans quelques secondes.

{ "action": "read_task_output", "relay": "build-box", "session": "3f9c…", "task_id": "b7k2…", "lines": 50 }

{
  "ok": true,
  "summary": "read_task_output → build-box session 3f9c2a1e task b7k2m9q4: 50 lines, running, last output 14 min ago, 412 passed, 2 failed",
  "task": { "id": "b7k2…", "description": "npm test", "type": "local_bash", "status": "running", "exitCode": null },
  "stall": { "minutes": 14, "since": "2026-10-18T09:12:00.000Z", "quiet": true, "quietAfterMinutes": 10 },
  "counts": { "runner": "vitest", "passed": 412, "failed": 2, "skipped": 0, "final": false },
  "tail": ["…"],
  "truncated": true
}

Une tâche qui ne tourne pas et ne s’est pas terminée dans la dernière heure renvoie REMOTE_RELAY_NOT_FOUND ; un relais antérieur à 0.9.12 renvoie REMOTE_RELAY_UNSUPPORTED.

Envoyer des prompts #

send #

Met un prompt en file dans une session existante et attend la réponse.

{ "action": "send", "relay": "build-box", "session": "3f9c…", "text": "Did last night's deploy go through? Answer in two lines." }

{
  "ok": true,
  "relay": "build-box",
  "status": "done",
  "session": "3f9c…",
  "message_id": "b41e…",
  "reply": { "text": "Yes. The deploy finished at 02:14 and the health check is green.", "model": "…" }
}

Changer la facturation d’une session Claude Ajouté en 0.9.18 #

send avec provider fait passer une session Claude de l’abonnement à la clé Claude API, ou l’inverse, et envoie le message, en un seul appel : un changement refusé n’envoie rien, et un message refusé ne change rien. L’autre facturation doit être configurée sur le relais cible. La carte d’approbation, quand il y en a une, indique Switches billing to API key ou Switches billing to subscription.

• Un changement que le relais cible refuse revient avec REMOTE_RELAY_PROVIDER_UNAVAILABLE quand Claude API ou Claude n’y est pas configuré ou que le plafond mensuel est atteint, et avec REMOTE_RELAY_UNKNOWN_MODEL quand le modèle de la session ne figure pas dans la liste de l’autre côté. remoteCode porte le code propre au relais, par exemple CLAUDE_API_CAP_REACHED.
• Un relais antérieur à 0.9.18 ne peut pas changer de facturation : l’appel est refusé avec REMOTE_RELAY_UNSUPPORTED, et rien n’est envoyé.
• Sans provider, la session garde sa facturation. Un send à une session sur la clé alors que le plafond est atteint est refusé, et rien n’est mis en file : envoyez avec provider: "claude" pour la faire passer sur l’abonnement, ou demandez à l’utilisateur de relever le plafond.

create_session #

Démarre une nouvelle session et lui donne son premier prompt. La nouvelle session ne sait rien de la conversation depuis laquelle elle a été démarrée : le prompt doit donc se suffire à lui-même.

Prend text, wait_seconds, mode, model et effort comme send, et :

Ce que l’agent omet suit la session dans laquelle il travaille, dans la mesure où le relais cible le propose. Un chat OpenAI Image ne peut pas être démarré de cette façon.

{
  "action": "create_session",
  "relay": "this",
  "title": "Review: server/",
  "cwd": "/home/dev/projects/shop",
  "text": "Review the code under server/ for missing input checks. List findings with file and line. Change nothing."
}

Une session Claude Cloud prend un dépôt au lieu d’un dossier :

{
  "action": "create_session",
  "relay": "this",
  "provider": "claude-cloud",
  "repo": "example-org/sample-repo",
  "branch": "feature/banner",
  "text": "On branch feature/banner, change the sample banner text to \"Hello\" and push. Report what changed.",
  "wait_seconds": 60
}

Le résultat est le même que pour send, plus ce avec quoi la session a été démarrée : provider, model, mode, effort, title, et repo / branch pour une session cloud. Ajouté en 0.9.16 Il contient aussi group, le groupe de sessions dans lequel la nouvelle session est allée, tel que list_sessions l’affiche (id, name, role), ou null.

La placer dans un groupe Ajouté en 0.9.16 #

Sans group, une session démarrée sur ce relais rejoint le groupe de la session qui l’a démarrée, ou crée un groupe dont cette session est la tête. Une session démarrée sur un relais associé ne va dans aucun groupe.

Avec group, la nouvelle session va plutôt dans ce groupe existant, sur ce relais ou sur un relais associé. L’agent désigne le groupe par son id, ou par son nom tel que relay_info le liste, sans tenir compte de la casse. Un group vide compte comme aucun.

{
  "action": "create_session",
  "relay": "build-box",
  "group": "Release 2.4",
  "text": "Run the release checklist in docs/RELEASE.md up to the tag. Report each step."
}

Le relais recherche le groupe sur la cible avant d’afficher toute carte d’approbation, comme il le fait pour le modèle, et la carte le nomme (Group: Release 2.4 (grp_…)). Rien n’est créé quand :

• la cible n’a aucun groupe avec cet id ou ce nom. L’appel est refusé avec REMOTE_RELAY_UNKNOWN_GROUP, et error et groups listent les groupes qui s’y trouvent (jusqu’à 20, groupsTotal quand il y en a davantage) : Relay "build-box" has no session group "Relase". Groups there: Release 2.4 (grp_…), … No session was created.
• le nom correspond à plus d’un groupe. Même code, avec les groupes de ce nom : … Pass the id.
• le groupe a été dissous entre la recherche et le démarrage. Même code.
• les groupes de la cible ne peuvent pas être lus. Un relais trop ancien pour group renvoie REMOTE_RELAY_UNSUPPORTED (The target relay doesn't support groups on create_session yet: …) ; un relais qui ne répond pas ou refuse le token renvoie son code habituel.

Quand la session a été créée mais n’a pas atterri dans le groupe demandé, le résultat contient groupWarning, son summary se termine par (no group: …), et la note demande à l’agent de vous le dire. Vous pouvez alors déplacer la session à la main.

create_session ne prend qu’un groupe existant. Pour placer la session dans un nouveau groupe, l’agent appelle ensuite update_session avec ce nom. Renommer, dissoudre et réorganiser les groupes restent de votre ressort.

update_session Ajouté en 0.9.16 #

Modifie les réglages d’une autre session pour ses prochains turns, sans lui envoyer de prompt, et renvoie les réglages qu’elle a maintenant et ce qui a changé. Fonctionne sur ce relais et sur un relais associé.

Il faut au moins un réglage. Tout autre argument est refusé et rien n’est modifié. mayCreateSessions ne fait pas partie des réglages : Whether a session may start sessions is the owner's setting alone.

{ "action": "update_session", "relay": "this", "session": "3f9c…", "model": "claude-sonnet-5-5", "effort": "low", "group": "Release 2.4" }

{
  "ok": true,
  "summary": "update_session → desk session 3f9c2a1e: model, effort, group",
  "session": "3f9c…",
  "settings": {
    "model": "claude-sonnet-5-5", "effort": "low", "mode": "agent", "auto_compact_window": "auto",
    "title": "Review: server/", "group": { "id": "grp_…", "name": "Release 2.4", "role": "member" },
    "thinking_enabled": true, "thinking_display": "summarized", "cwd": "/home/dev/projects/shop"
  },
  "changed": ["model", "effort", "group"]
}

Un changement de dossier indique aussi si la CLI a été redémarrée (relaunched), et un nouveau groupe revient sous la forme groupCreated. Un appel qui ne changerait rien renvoie changed: [] et ne demande rien à personne. note porte ce que l’agent doit savoir, par exemple une fenêtre ramenée à la plus proche, ou que la fenêtre et le thinking ne s’appliquent qu’aux sessions Claude (Ajouté en 0.9.18 sessions Claude API comprises) et ne changent rien chez un autre fournisseur. Ajouté en 0.9.17 Une session DeepSeek reçoit aussi cette note, mais la fenêtre y prend bien effet, et 0 y signifie 400 000 tokens ; thinking_enabled non, car une session DeepSeek utilise toujours le thinking.

Qui peut modifier quoi. Un agent ne modifie librement qu’une session que sa propre conversation a démarrée : sur ce relais, ou sur un relais associé quand ce relais-là a enregistré cette conversation comme celle qui l’a démarrée. Toute autre session, la vôtre, celle d’un autre agent ou celle qui a démarré l’agent, demande d’abord votre Allow. Une carte de question demande une fois par conversation et par relais, nomme la session et liste la modification (Model: … · Effort: … · Group: …) ; Allow couvre les modifications ultérieures de cette conversation sur de telles sessions de ce relais-là. Deny refuse l’appel avec REMOTE_RELAY_PERMISSION ; une conversation sans turn en cours dans lequel demander reçoit REMOTE_RELAY_NO_ACTIVE_TURN. L’autre relais applique lui-même la même règle. Un agent ne modifie jamais la conversation dans laquelle il tourne. Dans les modes ask et plan, la carte habituelle d’une action d’écriture s’applique en plus.

Avant toute modification, le relais vérifie l’appel entier sur la cible : le modèle et l’effort, le groupe, le dossier, et s’il faut vous demander. Un modèle inconnu, un id de groupe inconnu, un nom de groupe qui correspond à deux groupes, un dossier que le relais n’a pas le droit d’utiliser, ou un nouveau dossier pour une session occupée font refuser l’appel avant toute carte, et rien n’est modifié.

Groupes.

• Un nom que le relais n’a pas crée un nouveau groupe portant ce nom. Un id de groupe doit exister (REMOTE_RELAY_UNKNOWN_GROUP).
• Un groupe que vous avez créé n’est jamais supprimé de cette façon. Quand un agent en retire la dernière session, le groupe reste et s’affiche dans votre barre latérale comme group · empty (groupe · vide) : renommez-le ou dissolvez-le depuis son menu, ou laissez un agent le nommer à nouveau. Rien ne le supprime de lui-même.
• Un groupe créé par un agent, par son nom ou en démarrant des sessions, disparaît dès qu’il est vide.

Le dossier. Un nouveau cwd redémarre la CLI de la session dans ce dossier. Il est refusé avec REMOTE_RELAY_BUSY tant qu’un turn y est en file ou en cours, ou qu’une tâche de fond tourne : The session cannot move to another folder now: …. Le dossier doit être un dossier que le relais a le droit d’utiliser. Une session qui n’a pas encore démarré garde le dossier pour son premier démarrage. Si la CLI ne redémarre pas, le dossier est quand même enregistré pour son prochain démarrage, et la réponse le dit. Pas pour Claude Cloud, qui travaille sur un clone de son dépôt.

Le mode réglé ainsi dure jusqu’au prochain send qui nomme un autre mode ou qui vient d’un appelant dans un autre mode : un send sans mode transmet le mode propre de l’appelant.

Si une étape échoue après que d’autres ont été écrites, la réponse liste quand même dans changed ce qui a été écrit. Une page ouverte affiche toutes les modifications d’un coup. Un relais qui fait tourner un OAR plus ancien renvoie REMOTE_RELAY_UNSUPPORTED.

Quels modèles sont acceptés Ajouté en 0.9.13 #

Un model dans send ou create_session est vérifié par rapport à la liste que New Chat (Nouveau chat) propose pour le fournisseur sur le relais cible, la même liste que celle qu’affiche relay_info, avant toute carte d’approbation. Un modèle qui n’y figure pas est refusé avec REMOTE_RELAY_UNKNOWN_MODEL, et rien n’est créé ni envoyé :

Unknown model 'gpt-5-4' for Copilot on relay "build-box"; did you mean 'gpt-5.4'? Valid ids: … Nothing was sent.

Le résultat contient aussi suggestions, les correspondances proches, et models, les ids valides. Avant 0.9.13, un tel id créait une session sur un autre modèle, que les appels send suivants avec cet id ne pouvaient pas atteindre.

Ajouté en 0.9.19 Les ids de modèle de Copilot utilisent des points : claude-opus-5.5, et non le claude-opus-5-5 de Claude. Copilot refuse l’id d’un autre fournisseur avant de créer quoi que ce soit : avec COPILOT_MODEL_UNAVAILABLE et la correspondance la plus proche ou, dans create_session, avec le code du seul autre fournisseur qui liste cet id, comme CLAUDE_PROVIDER_REQUIRED. Une session Copilot ne passe jamais à un autre fournisseur à cause du nom de son modèle.

Quand le modèle qui tourne diffère de celui demandé, le modelNote du résultat le signale. Quand le relais cible n’a pas encore de liste pour le fournisseur (sa découverte des modèles n’a pas tourné ou a échoué), le modèle passe sans vérification et modelNote le signale aussi. Un relais refuse aussi un modèle Copilot inconnu quand l’agent d’un autre relais y démarre une session.

wait #

Continue d’attendre une réponse que send ou create_session n’a pas obtenue à temps.

{ "action": "wait", "relay": "build-box", "session": "3f9c…", "message_id": "b41e…", "wait_seconds": 300 }

L’attente et ce qui revient #

send, create_session et wait attendent la réponse aussi longtemps que l’agent le demande dans wait_seconds, jusqu’à Longest wait per tool call (Attente maximale par appel d’outil) sur le relais où tourne l’agent (Settings → Relays → Agent sessions) : 10 minutes par défaut, réglable de 2 à 60 minutes. Quand un appel a demandé plus que ce que le relais permet, le résultat le dit dans une note. Quand le temps est écoulé, l’agent reçoit ce qu’il y a jusque-là et peut rappeler wait.

Un turn qui attend compte quand même dans Max turn duration (Durée maximale d’un turn) sous Settings → General (Réglages → Général).

Le status du résultat indique où en est l’autre session :

Chacun de ces résultats porte session et message_id, ainsi que openUrl, un lien qui ouvre la session, quand le relais en a un.

Piloter une autre session #

answer_question #

Répond à une carte de question qui attend dans une autre session. Les agents ont pour consigne de vous demander d’abord, sauf si vous leur avez dit de décider eux-mêmes.

L’un de choices et answer est requis. Un agent ne peut pas répondre à sa propre question, ni à la carte d’approbation d’un relais : celles-là vous reviennent. Ajouté en 0.9.16 Il ne peut pas non plus répondre à une question non bloquante : answer_question la refuse avec REMOTE_RELAY_FORBIDDEN avant d’appeler qui que ce soit.

{ "action": "answer_question", "relay": "build-box", "question_id": "q_7d2…", "choices": ["Merge"] }

stop #

Arrête le turn qui tourne dans une session, comme le fait Stop (Arrêter) dans l’interface. Le résultat indique si un arrêt a été demandé ou si rien ne tournait.

{ "action": "stop", "relay": "this", "session": "3f9c…" }

archive #

Archive une session.

{ "action": "archive", "relay": "this", "session": "3f9c…" }

Surveiller des sessions #

Ajouté en 0.9.10 Au lieu de redemander encore et encore, un agent peut s’abonner à des sessions et être réveillé quand quelque chose s’y passe. Cela fonctionne sur ce relais (avec les sessions d’agent activées) et sur un relais associé.

Un abonnement ne fait que notifier. Il n’approuve rien et ne répond à rien ; ce que demande un événement est décidé comme avant, par vous ou par l’agent dans les limites de ce qu’il peut faire de toute façon.

subscribe #

Une conversation peut détenir 20 abonnements à la fois. La propre conversation de l’agent n’est jamais surveillée.

{ "action": "subscribe", "sessions": ["3f9c…", "a12b…"], "events": ["question_asked", "error", "all_idle"] }

{
  "ok": true,
  "summary": "subscribe → desk: 2 sessions (sub_ab12cd34ef)",
  "subscription": {
    "id": "sub_ab12cd34ef",
    "sessions": [ { "id": "3f9c…", "title": "Review: server/" }, { "id": "a12b…", "title": "Review: web/" } ],
    "events": ["question_asked", "error", "all_idle"],
    "once": false,
    "stalledMinutes": 15
  }
}

Moins de réveils Ajouté en 0.9.16 #

Chaque réveil est un turn complet de l’agent qui surveille. Trois options de subscribe permettent d’en demander moins. question_asked, question_answered et error ne sont jamais retenus par aucune d’elles ; tous les autres événements le sont, task_failed, stalled et all_idle compris.

{
  "action": "subscribe",
  "sessions": ["all"],
  "exclude": ["77aa…"],
  "digest_minutes": 30,
  "quiet_hours": { "from": "23:00", "to": "06:00", "tz": "Europe/Berlin" }
}

• digest_minutes. Les événements de l’abonnement sont rassemblés et arrivent en un seul message toutes les N minutes : le premier au plus tôt N minutes après la création de l’abonnement, chacun des suivants N minutes après le précédent. Le message dit Digest of 4 events (subscription sub_… every 30 min; questions and errors come at once):. Un récapitulatif d’un seul événement se lit comme cet événement.
• quiet_hours. Une plage quotidienne en heure locale, dans un fuseau horaire IANA. from et to sont des heures de la journée (HH:MM, de 00:00 à 23:59) et doivent être différentes ; la plage peut passer minuit. Ce qui se passe dedans attend et arrive en un seul message à la fin de la plage, avec la ligne Held during quiet hours (23:00–06:00 Europe/Berlin): 3 events, delivered now that the window has ended; questions and errors came at once. Aucun signal de vie n’est produit dans la plage. Un événement qu’un récapitulatif remettrait dans la plage est reporté à sa fin.
• exclude. Un abonnement à toutes les sessions (all) ignore ces sessions, y compris pour all_idle, stalled et le signal de vie. Avec une liste de sessions, il est refusé : exclude goes with sessions ["all"] only; a list of sessions names what it watches.

Changements d’heure. La plage suit l’horloge du fuseau horaire. La nuit où l’on recule les horloges et où to survient deux fois, la plage se termine la première fois et n’est pas rouverte pendant l’heure répétée. La nuit où l’on avance les horloges et où to est sauté, elle se termine au moment du saut. Une limite connue : un from situé dans l’heure répétée ouvre la plage au premier passage, et au second passage, les minutes avant from comptent comme en dehors de la plage.

Une valeur erronée est refusée avec ce qui ne va pas, par exemple quiet_hours from and to must be times of day as "HH:MM" (00:00 to 23:59), quiet_hours from and to must differ, ou quiet_hours tz "Berlin" is not an IANA time zone (for example "Europe/Berlin", "America/New_York", "UTC"). Un quiet_hours dont tous les champs sont vides compte comme aucun.

• Avec once. L’événement qui met fin à un abonnement à usage unique respecte quand même son récapitulatif et ses heures calmes : l’abonnement se termine aussitôt, l’événement arrive quand ils le permettent.
• Plusieurs abonnements. Un événement pris par plusieurs abonnements de l’agent qui surveille part dès que le premier d’entre eux le laisse partir ; un abonnement sans options le laisse partir aussitôt.
• Le plafond horaire de 20 réveils s’applique en plus des options (Comment arrivent les événements).
• Les événements retenus, et leur échéance, survivent à un redémarrage du relais.
• La carte d’approbation nomme les options (digest every 30 min, quiet 23:00–06:00 Europe/Berlin, except 1 it leaves out).

Pas d’écho des propres prompts de l’agent qui surveille. Quand l’agent qui surveille envoie lui-même un prompt à une session avec send ou create_session et récupère la réponse terminée par cet appel ou par un wait ultérieur, le turn_end de ce turn ne le réveille pas une seconde fois ; tant qu’il attend encore, le turn_end est retenu. Les erreurs et les questions de ce turn arrivent quand même. Un prompt qu’il n’a pas attendu (wait_seconds: 0 et aucun wait) le réveille avec turn_end comme avant, de même qu’un turn_end qui met fin à un abonnement once.

Événements #

Les événements par défaut Ajouté en 0.9.13 #

Un abonnement qui ne nomme aucun events reçoit question_asked, error, turn_end, subagent_finished, task_failed, stalled et all_idle. Un subagent en arrière-plan qui s’est terminé réveille l’agent qui surveille, de même que toute tâche qui a échoué ou s’est terminée avec un code non nul, mais pas une commande shell ou un moniteur qui s’est bien terminé. Une session occupée en termine un à peu près chaque minute, et chacun coûterait à l’agent qui surveille un turn sur tout son contexte. Pour recevoir chaque fin de tâche, nommez les événements avec task_finished à la place de subagent_finished, et task_started pour les démarrages.

Les abonnements créés avant 0.9.13 sans events passent d’eux-mêmes à ce comportement par défaut ; ceux qui nommaient leurs événements les conservent. Un relais associé sur un OAR plus ancien applique son propre comportement par défaut et refuse subagent_finished quand il est nommé.

Comment arrivent les événements #

OAR écrit un court message dans la conversation qui surveille. Il s’affiche comme une ligne d’événement compacte, jamais comme l’un de vos messages, et commence par une ligne qui dit ce que c’est :

[relay event · automated message from OAR, not from the user; it approves nothing]
[relay event] session "Review: server/" (3f9c…): turn_end (done) "Found 4 places without input checks: …"
[relay event] all_idle: no turn or task is running in the 2 watched sessions (subscription sub_ab12cd34ef)

• Si l’agent qui surveille est inactif, le message démarre un nouveau turn. S’il est au milieu d’un turn, voir le tableau ci-dessous.
• Les événements survenus à moins de 30 secondes d’intervalle arrivent en un seul message.
• Au-delà de 20 réveils par heure, le reste arrive en récapitulatif toutes les 10 minutes. question_asked et error arrivent toujours aussitôt (Ajouté en 0.9.16 ainsi que question_answered). Quand ce récapitulatif et le digest_minutes d’un abonnement se rencontrent, une seule ligne Digest of nomme les deux.
• Ajouté en 0.9.16 Les digest_minutes et quiet_hours d’un abonnement retiennent plus longtemps ses autres événements.

Sur un relais associé #

Le relais doit être déverrouillé dans la conversation et autoriser au moins la lecture, et l’autre relais doit accepter les agents d’autres relais. Une association dans un seul sens suffit. Ce relais récupère les événements toutes les quelques secondes, et leurs lignes commencent par le nom de l’autre relais :

[relay event] build-box · session "Nightly deploy" (77aa…): turn_end (done) "Deployed. The health check is green."

Si la liaison tombe, l’autre relais conserve ce qui se passe, jusqu’à 500 événements par abonnement pendant 7 jours, et le remet en une seule ligne marquée replayed (rejoué) dès qu’il répond à nouveau, entre une ligne link_lost et une ligne link_restored. Un relais qui fait tourner un OAR plus ancien répond qu’il a besoin d’une mise à jour.

Ajouté en 0.9.16 Le récapitulatif et les heures calmes d’un abonnement à un relais associé sont appliqués ici, là où se trouve l’agent qui surveille ; exclude est aussi transmis à l’autre relais, pour all_idle, stalled et le signal de vie. Les événements rejoués respectent le récapitulatif et les heures calmes comme les autres ; la ligne link_restored indique alors combien d’entre eux sont retenus et arriveront plus tard. Un relais associé sur un OAR plus ancien ne connaît pas exclude : ce relais-ci écarte quand même les événements de ces sessions, mais ce relais-là les compte pour all_idle, pour les blocages et dans la liste du signal de vie.

unsubscribe #

Met fin à un abonnement, ou, avec "all", à tous les abonnements que la conversation détient sur le relais nommé.

{ "action": "unsubscribe", "subscription_id": "sub_ab12cd34ef" }

list_subscriptions #

Affiche les abonnements de la conversation : les actifs et ceux qui ont pris fin dans la dernière heure, avec la raison. Avec watcher, affiche les abonnements d’une autre conversation ; c’est ainsi qu’un agent regarde avant de les reprendre.

{ "action": "list_subscriptions" }

Chaque abonnement affiche ses sessions, ses événements, once, match, stalledMinutes et heartbeatMinutes, Ajouté en 0.9.16 ainsi que digestMinutes, quietHours et exclude quand il en a. Un abonnement actif indique aussi combien de ses événements son récapitulatif ou ses heures calmes retiennent en ce moment (heldCount) et quand le premier d’entre eux est dû (nextDeliveryAt, null quand aucun n’est retenu). Un abonnement terminé ne l’indique que tant que son dernier événement est encore retenu, comme après un once qui s’est déclenché pendant les heures calmes.

{
  "id": "sub_ab12cd34ef",
  "scope": "all",
  "sessions": "all",
  "digestMinutes": 30,
  "quietHours": { "from": "23:00", "to": "06:00", "tz": "Europe/Berlin" },
  "exclude": ["77aa…"],
  "heldCount": 3,
  "nextDeliveryAt": "2026-10-24T04:00:00.000Z"
}

transfer_subscriptions #

Déplace tous les abonnements d’une autre conversation vers celle-ci, par exemple quand une nouvelle session remplace un ancien agent qui surveille. Vous demande toujours votre accord sur une carte d’approbation.

{ "action": "transfer_subscriptions", "from": "c0de…" }

Durée de vie d’un abonnement #

Les abonnements survivent à un redémarrage du relais. Un abonnement prend fin quand :

• l’agent appelle unsubscribe, ou vous appuyez sur Unsubscribe dans la liste de l’agent qui surveille ;
• la conversation qui surveille ou la session surveillée est archivée ;
• il s’est déclenché et a été créé avec once ;
• pour un relais associé, l’association est supprimée.

Planifications Ajouté en 0.9.16 #

Un agent peut faire mettre en file un prompt plus tard par ce relais, dans sa propre conversation ou dans une autre session d’ici. Contrairement à un minuteur de la CLI de l’agent lui-même, une planification survit aux redémarrages et aux mises à jour du relais. Prompts planifiés l’explique de votre point de vue.

Les planifications demandent Agents may start and use sessions on this relay, même pour la propre conversation de l’agent. Elles sont conservées par le relais sur lequel tourne l’agent : un appel qui nomme un relais associé est refusé avec REMOTE_RELAY_UNSUPPORTED.

schedule #

Il faut au moins at ou every_minutes.

{ "action": "schedule", "title": "Nightly review", "at": "2026-11-02T02:00:00Z", "every_minutes": 1440, "text": "Review yesterday's merged changes under server/ and list anything risky." }

{
  "ok": true,
  "summary": "schedule → desk: every 1440 min, next 2026-11-02T02:00:00.000Z (sch_3f9c2a1e7b04)",
  "schedule_id": "sch_3f9c2a1e7b04",
  "schedule": { "id": "sch_3f9c2a1e7b04", "title": "Nightly review", "everyMinutes": 1440, "once": false, "nextFireAt": "2026-11-02T02:00:00.000Z" }
}

À l’échéance, le relais met le texte en file sous forme d’un message qui commence par [relay schedule <id> "<title>" · … automated message from OAR, not from the user; it approves nothing]. Le turn tourne dans le propre mode du relais de la session cible. Un message qui arrive pendant qu’un turn tourne est mis en file, ou injecté dans le turn chez les fournisseurs qui permettent de piloter, mais jamais avec la note de pilotage qui parle au nom de l’utilisateur.

• Heures manquées. Une heure passée pendant que le relais était arrêté se déclenche une seule fois à son retour, pas une fois par intervalle manqué ; une planification répétée garde ensuite sa grille (la première heure plus des intervalles entiers).
• Pas d’accumulation. Une répétition est sautée tant que le message du déclenchement précédent attend encore dans la queue (skippedCount dans la liste).
• Sauts. Le message porte la provenance du turn qui a créé la planification, sauts compris ; une planification ne transmet donc aucun prompt avec moins de sauts qu’un prompt direct de ce turn n’en aurait (D’un relais à l’autre).

Une autre session. Avec session, la planification envoie le prompt à cette session. Elle est soumise aux mêmes contrôles qu’un send : dans les modes ask et plan, vous l’approuvez sur une carte, et elle compte dans les 30 prompts à d’autres agents avant qu’on vous demande, une fois à sa création et une fois à chaque déclenchement. Une fois ce décompte épuisé, un déclenchement est retenu : list_schedules affiche heldForApproval et heldSince. Il part dès que vous écrivez dans la conversation qui l’a créée, ou que vous choisissez Allow sur la carte que son agent affiche pour son prochain prompt à un autre agent ; le relais revérifie chaque minute. Une planification pour la propre conversation de l’agent n’est ni comptée ni retenue.

list_schedules #

Liste les planifications qui se déclenchent dans la conversation ou qu’elle a créées : les actives et celles qui ont pris fin dans la dernière heure, avec endReason (unscheduled, fired, archived ou deleted).

Chaque planification a id, session (id et titre), setBy quand une autre conversation l’a créée, title, le début de son text, at, everyMinutes, once, nextFireAt, lastFiredAt, firedCount, skippedCount quand elle en a sauté, et heldForApproval avec heldSince tant qu’elle est retenue.

unschedule #

Met fin à une planification de la conversation : une qui s’y déclenche ou qu’elle a créée.

Quand une planification prend fin #

Une planification prend fin après son déclenchement si elle est once, sur unschedule ou Cancel (Annuler) dans la liste ⏰ de l’en-tête, et quand la session dans laquelle elle se déclenche ou la conversation qui l’a créée est archivée ou supprimée. Un compactage déplace plutôt les deux sortes vers la nouvelle conversation. Une conversation détient au plus 20 planifications actives qui s’y déclenchent, et peut en créer au plus 20 pour d’autres sessions ; au-delà, REMOTE_RELAY_SCHEDULE_LIMIT.

Les questions non bloquantes Ajouté en 0.9.16 #

Un agent peut vous poser une question et continuer à travailler : la question s’affiche comme une carte dans sa session et dans votre Inbox (Boîte de réception), et l’agent apprend la réponse plus tard. Questions et Inbox l’explique de votre point de vue.

ask #

{ "action": "ask", "question": "Ship the migration tonight or wait for the review?", "options": ["Tonight", "Wait"], "recommendation": "Wait", "detail": "The review covers the index change; the rest is tested." }

{ "ok": true, "question_id": "ask_7d2…", "status": "pending", "summary": "ask → desk: question ask_7d2… pending" }

ask rend la main aussitôt avec question_id et status: "pending". L’agent doit poursuivre ce qui ne dépend pas de la réponse et ne pas reposer la même question tant qu’elle est en attente.

La réponse. Quand vous répondez à la question ou l’ignorez, l’agent reçoit l’événement du relais question_answered, avec question_id, votre answer, le choice que vous avez choisi, dismissed quand vous l’avez ignorée, et via, le relais sur lequel vous avez répondu : celui où la question est conservée, ou un relais associé dont vous avez utilisé l’Inbox. Il n’a besoin d’aucun abonnement. L’événement est urgent : aucun récapitulatif ni aucunes heures calmes ne le retiennent. Il est automatique et n’approuve rien d’autre, et il ne compte pas comme un message de votre part pour le garde-fou anti-boucle : répondre à une question non bloquante ne remet pas à zéro le décompte des prompts que les agents peuvent s’envoyer.

Qui répond. Vous seul, dans la session ou dans une Inbox (celle de ce relais, ou celle d’un relais associé à celui-ci). answer_question refuse une question non bloquante.

Contrôles.

• Une question sur la propre conversation de l’agent, list_questions et withdraw ne demandent ni réglage ni mention.
• Avec session, l’agent demande au nom d’une autre session : sur ce relais avec Agents may start and use sessions on this relay, sur un relais associé avec Agents may au moins à Read and prompt et le relais déverrouillé. Une telle question est une écriture : dans les modes ask et plan, vous l’approuvez sur une carte, et elle respecte la limite de sauts (D’un relais à l’autre). Le garde-fou anti-boucle ne la compte pas. La carte s’affiche dans cette session, et celle-ci comme la conversation qui demande reçoivent la réponse.
• Une question sur une session d’un relais associé est conservée sur ce relais-là ; ce relais-ci vérifie toutes les 5 secondes si elle a une réponse tant qu’elle est ouverte (toutes les 30 secondes tant que ce relais-là ne répond pas). Un relais qui fait tourner un OAR plus ancien renvoie REMOTE_RELAY_UNSUPPORTED.

Au plus 20 questions non bloquantes peuvent être en attente par conversation qui demande, et 20 par session concernée ; au-delà, REMOTE_RELAY_QUESTION_LIMIT. Les questions non bloquantes n’expirent pas.

list_questions #

Liste les questions non bloquantes de la conversation : celles en attente, et celles auxquelles vous avez répondu, que vous avez ignorées ou qui ont été retirées dans la dernière journée, avec leur statut et leur réponse. Avec session, les questions sur une autre session. Sur un relais associé, liste les questions que cette conversation y a posées ; read_session sur ce relais liste toutes les questions en attente d’une session.

withdraw #

Retire une question non bloquante encore en attente. Seule la conversation qui l’a posée peut la retirer.

Une question non bloquante prend aussi fin quand sa session est archivée ou supprimée (personne n’est prévenu), et quand l’association avec le relais où elle est conservée est supprimée. Un compactage déplace ses questions vers la nouvelle conversation.

Limites #

Erreurs #

Un appel refusé revient avec un code sur lequel l’agent peut agir.