relay_tool Nuevo en 0.9.4

Con relay_tool un agente trabaja con otras sesiones: las lista y las lee, le envía un prompt a una, inicia una nueva, espera la respuesta, responde a una pregunta que hizo el otro agente, detiene o archiva una sesión, y puede pedir que lo despierten cuando ocurre algo en las sesiones que vigila.

Llega a dos tipos de relay:

• Este relay, aquel en el que se ejecuta el propio agente. Un agente puede pasar partes de su tarea a otras sesiones de aquí. Desactivado hasta que lo activas. Nuevo en 0.9.7
• Relays emparejados, otros relays de OAR que has emparejado con este, por ejemplo el relay de tu estación de trabajo y el de un servidor. Bloqueados en cada conversación hasta que mencionas el relay.

La herramienta es la misma para todos los proveedores que la tienen; consulta Por proveedor para saber cuáles la tienen y con qué nombre.

El nombre Nuevo en 0.9.18 #

Hasta 0.9.17 la herramienta se llamaba remote_relay. Ahora aparece como relay_tool en todos los proveedores (el agente de Claude ve mcp__relay__relay_tool), con las mismas acciones y campos. Las líneas de herramienta escritas con el nombre antiguo se siguen mostrando como esta herramienta.

• Sesiones que estaban en marcha cuando actualizaste. El agente de una sesión recibe su lista de herramientas cuando arranca su worker, y los workers siguen ejecutándose durante el reinicio del relay. El agente de una sesión así sigue teniendo la herramienta como remote_relay hasta que su worker vuelve a arrancar, por ejemplo tras Kill session (Matar la sesión). Sus llamadas siguen funcionando: llegan al relay de la misma forma con cualquiera de los dos nombres. Donde el relay se ejecuta como servicio de Linux, los workers pueden detenerse con el relay y volver luego con el nombre nuevo.
• El propio servidor MCP de OAR, que usan Grok y el motor de extensión de Copilot, sigue ejecutando una llamada a remote_relay, pero ya no la lista.
• Tus propias instrucciones. Si tus instrucciones, reglas de permisos o hooks nombran remote_relay o mcp__relay__remote_relay, cámbialos a relay_tool o mcp__relay__relay_tool: fuera del servidor MCP de OAR el nombre antiguo se rechaza.

Lo que ves #

• Tarjetas de aprobación. Una tarjeta de pregunta te consulta antes de la primera sesión que un agente inicia en una conversación, antes de que vigile sesiones por primera vez, y antes de cada acción de escritura mientras la conversación está en el modo del relay ask o plan.
• La llamada a herramienta en la respuesta. La actividad del agente muestra cada llamada con un 🛰️, la acción, el relay y la sesión.
• «via agent» (vía agente). Una sesión que inició un agente lleva via agent · "title" en la lista de conversaciones y bajo su título, con el nombre de la conversación en la que se ejecuta el agente. Nuevo en 0.9.11 Queda en un grupo de sesiones bajo esa conversación, Nuevo en 0.9.16 o en un grupo existente que el agente nombró.
• «↗ from …» (de …). Un prompt que envió un agente lleva, en el lado que lo recibe, una insignia con el relay, la sesión y el modelo que lo enviaron.
• Vigilancia. Una conversación que vigila a otras muestra watching N sessions (vigila N sesiones) en su cabecera; el chip lista sus suscripciones, cada una con un botón Unsubscribe (Cancelar la suscripción). Una sesión vigilada muestra una insignia watched (vigilado).

Activarlo #

relay_tool se ofrece a los agentes cuando se cumple al menos una de estas condiciones:

Una sesión sabe si recibe la herramienta cuando arranca el proceso de su agente, así que una conversación que ya estaba en marcha puede no tenerla hasta que su agente haya vuelto a arrancar.

Nombrar un relay #

Todas las acciones salvo list_relays trabajan sobre un relay, nombrado en relay:

• "this", o el nombre propio de este relay, es el relay en el que se ejecuta el agente. No necesita mención.
• Un relay emparejado se nombra por su nombre de relay o por su host, tal como lo muestra list_relays.

En las cuatro acciones de suscripción, Nuevo en 0.9.16 las tres acciones de programación y las tres acciones de preguntas, relay se puede omitir y significa "this". Las programaciones solo funcionan en este relay.

Bloqueado y desbloqueado #

Un relay emparejado queda bloqueado en una conversación hasta que ocurre una de estas cosas:

• Lo mencionas en uno de tus mensajes: escribe @ y elígelo, o escribe su nombre o su nombre de host. Un relay cuyo nombre es una dirección IP o localhost solo cuenta con una @ delante.
• Un agente de ese relay escribe en la conversación. El relay queda entonces abierto para que el agente de aquí pueda responder.

Una vez desbloqueado, queda abierto durante el resto de la conversación. Un relay bloqueado rechaza todas las acciones salvo list_relays; al agente se le indica que te pida que menciones el relay.

Permisos y aprobaciones #

Lo que permite un relay emparejado #

Cada relay emparejado tiene un nivel Agents may (Los agentes pueden) en Settings → Relays. Los emparejamientos nuevos empiezan en Full (Acceso total).

list_relays no necesita nivel. Este propio relay cuenta siempre como Full.

Al otro lado, Accept prompts from other relays' agents (Aceptar prompts de agentes de otros relays; Settings → Relays en el relay emparejado) desactiva todo lo que los agentes de otro relay podrían cambiar o vigilar allí: enviar prompts, iniciar, responder, detener y archivar sesiones, y suscribirse a ellas. Listar y leer sesiones, leer la salida de tareas, esperar, relay_info y usage siguen funcionando.

Cuándo se te pregunta #

Reglas para las sesiones de este relay #

• Como mucho 4 trabajando. De las sesiones que inició el agente de una conversación, 4 pueden tener un turn en cola o en curso a la vez. Una quinta se rechaza hasta que una haya terminado.
• Un solo nivel. Una sesión que creó un agente no puede crear sesiones ella misma, Nuevo en 0.9.16 salvo que hayas activado para ella Agents in this conversation may start sessions (Los agentes de esta conversación pueden iniciar sesiones). list_sessions y read_session muestran entonces "mayCreateSessions": true. Ningún agente puede cambiar ese interruptor.
• No sobre sí mismo. Un agente no puede hacer send, wait, stop ni archive sobre la conversación en la que se ejecuta, ni responder a su propia pregunta, Nuevo en 0.9.16 ni cambiar sus ajustes.
• Tus cuentas. Las sesiones que inicia un agente usan las cuentas de proveedor de este relay y cuentan para su consumo.
• El relay nunca archiva estas sesiones por sí solo. Se quedan en tu lista hasta que las archivas o eliminas, o el agente archiva una.

Entre relays #

• Un prompt que ya ha cruzado dos relays no se pasa a un tercero salvo que hayas desbloqueado ese relay tú mismo. Leer y esperar nunca están limitados por esto.
• El prompt que recibe el otro agente empieza con una línea que dice que otro agente le está hablando: [Remote prompt from an agent on relay "…" · session "…" · model · acting for the user].
• Los turns iniciados así no envían ninguna notificación «reply ready» en el otro relay. Las tarjetas de pregunta siguen notificando.
• Las direcciones remotas tienen que usar https://. http:// sin cifrar solo se acepta para loopback y rangos de red privada.

Acciones #

Cada llamada nombra una action. La tabla muestra lo que necesita cada una; el nivel es el ajuste Agents may más bajo que la permite en un relay emparejado.

Un resultado es JSON. Una llamada que funcionó tiene "ok": true, el relay sobre el que trabajó y un summary de una línea; una llamada que falló tiene "ok": false, un code y un texto en error (Errores). Los ejemplos de abajo muestran los campos principales, con nombres e ids inventados.

Nuevo en 0.9.16 Un argumento que una acción no admite nunca se descarta sin avisar. create_session y update_session rechazan la llamada con REMOTE_RELAY_INVALID_INPUT, nombran sus propios argumentos y no cambian nada: create_session does not take: session. Its arguments: relay, text, provider, model, cwd, repo, branch, mode, effort, title, group, wait_seconds. Nothing was created. Todas las demás acciones se ejecutan igualmente y listan en ignored, en su resultado, los argumentos que no admitieron, hasta 20. Un valor vacío (null, "", false o una lista vacía) cuenta como ningún argumento, porque algunos proveedores envían todos los campos.

Encontrar relays y sesiones #

list_relays #

Lista los relays emparejados con name, url, online, version, permission y unlocked. Cuando las sesiones de agentes están activadas, este relay va primero, marcado con "self": true. También devuelve el límite de espera de este relay. Es la única acción que funciona sin mención y sin 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 #

Lo que ofrece un relay, para que el agente pueda elegir proveedor, modelo y carpeta para una sesión nueva: su nombre, versión y plataforma, si acepta prompts de agentes, cada proveedor con su modelo predeterminado, sus modelos y sus valores de reasoning effort, las carpetas de trabajo predeterminada y recientes, y los modos del relay.

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

Nuevo en 0.9.16 También lista en groups los grupos de sesiones del relay, los que puede nombrar un create_session allí: cada uno con id, name (lo que muestra la barra lateral; el título de la sesión de cabecera en un grupo sin nombre) y memberCount, primero el grupo con la actividad más reciente. Solo se listan los grupos con al menos una sesión no eliminada, como mucho 50; groupsTotal dice cuántos hay cuando hay más. No incluye los ids ni los títulos de los miembros. Cuando no se pueden leer los grupos del relay, por ejemplo porque ejecuta un OAR más antiguo, groups es null y groupsNote dice por qué y que create_session no puede admitir group allí.

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

usage Nuevo en 0.9.10 #

Lo que le queda al plan de cada proveedor en un relay, como en Check Usage (Ver consumo), para que un agente pueda comprobarlo antes de empezar un trabajo que cuesta: por proveedor, un estado y sus medidores (usado, asignación, restante, utilización, hora de reinicio), y si un límite de uso de Claude ha pausado los turns allí. Los proveedores que no están configurados o no se siguen lo indican. Nunca se incluyen nombres de cuenta, direcciones ni tokens.

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

list_sessions #

Lista sesiones con id, title, provider, model, state, cwd, la hora de la última actividad y un recuento de mensajes. state es running_turn, background_only (el agente ha respondido y sigue en marcha trabajo en segundo plano) o idle; tasks lista los agentes en segundo plano y las tareas de shell.

Nuevo en 0.9.11 Una sesión de un grupo de sesiones también tiene group: su id, su name y el role de la sesión en él, head o member. Nuevo en 0.9.16 create_session puede poner la sesión que crea en un grupo existente, y update_session puede mover una sesión a un grupo, también a uno nuevo, o sacarla de él. Renombrar, disolver y reorganizar grupos sigue siendo cosa tuya.

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

read_session #

Lee los mensajes más recientes de una sesión, junto con lo que está pasando allí: su state, una respuesta que aún se está escribiendo (inFlight), y cualquier pendingQuestions que espere respuesta (Nuevo en 0.9.16 cada una con kind: ask para una pregunta que no bloquea, ask_user para una tarjeta en la que espera la sesión). Nuevo en 0.9.11 Para una sesión de un grupo, group añade los demás miembros, hasta 50, cada uno con id, title, role, state y archived cuando está archivado.

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

Nuevo en 0.9.12 Cada una de las tasks de la sesión tiene también su taskId, output (si hay salida que leer con read_task_output) y, para un comando cuya salida está en un archivo, health: minutesSinceOutput, quiet y quietAfterMinutes (el ajuste de tarea silenciosa del relay) mientras se ejecuta, y los counts de la ejecución de tests cuando los hay.

read_task_output Nuevo en 0.9.12 #

Lee el final de la salida de un comando de shell o de un monitor en segundo plano, la misma salida que muestra la consola de tareas: mientras la tarea se ejecuta y durante una hora después de que termine. Un agente puede comprobar si una compilación en otro relay sigue ocupada, se ha quedado en silencio o tiene tests fallidos, sin preguntar al agente que la inició.

El resultado tiene task (descripción, tipo, inicio, status y exitCode), tail (las líneas, como texto sin formato y sin colores, con una línea repetida marcada como [×N]), truncated cuando hay más antes de ellas, stall (minutos desde la última salida, y quiet según el ajuste del relay) mientras la tarea se ejecuta, y counts con el runner y sus tests superados, fallidos y omitidos cuando la salida es una ejecución de tests. Las credenciales se ocultan como en la consola. Una note indica cuándo solo existe el final de la salida, cuándo la salida ya no está, o cuándo se le ha pedido al proceso del agente y hay que repetir la llamada en unos segundos.

{ "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
}

Una tarea que no se está ejecutando y no terminó en la última hora responde REMOTE_RELAY_NOT_FOUND; un relay anterior a 0.9.12 responde REMOTE_RELAY_UNSUPPORTED.

Enviar prompts #

send #

Pone un prompt en la queue de una sesión existente y espera la respuesta.

{ "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": "…" }
}

Cambiar la facturación de una sesión de Claude Nuevo en 0.9.18 #

send con provider pasa una sesión de Claude entre la suscripción y la clave de Claude API y envía el mensaje, en una sola llamada: un cambio rechazado no envía nada, y un mensaje rechazado no cambia nada. La otra facturación tiene que estar configurada en el relay de destino. La tarjeta de aprobación, cuando se pide una, dice Switches billing to API key o Switches billing to subscription.

• Un cambio que el relay de destino rechaza vuelve con REMOTE_RELAY_PROVIDER_UNAVAILABLE cuando Claude API o Claude no están configurados allí o se ha alcanzado el límite mensual, y con REMOTE_RELAY_UNKNOWN_MODEL cuando el modelo de la sesión no está en la lista del otro lado. remoteCode lleva el código propio del relay, por ejemplo CLAUDE_API_CAP_REACHED.
• Un relay anterior a 0.9.18 no puede cambiar: la llamada se rechaza con REMOTE_RELAY_UNSUPPORTED y no se envía nada.
• Sin provider, la sesión conserva su facturación. Un send a una sesión que usa la clave mientras se ha alcanzado el límite se rechaza y no se pone nada en cola: envía con provider: "claude" para pasarla a la suscripción, o pide al usuario que suba el límite.

create_session #

Inicia una sesión nueva y le da su primer prompt. La sesión nueva no sabe nada de la conversación desde la que se inició, así que el prompt tiene que entenderse por sí solo.

Admite text, wait_seconds, mode, model y effort como send, y además:

Lo que el agente omite sigue a la sesión en la que trabaja, en la medida en que el relay de destino lo ofrezca. Un chat de OpenAI Image no se puede iniciar así.

{
  "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."
}

Una sesión de Claude Cloud admite un repositorio en lugar de una carpeta:

{
  "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
}

El resultado es el mismo que en send, más aquello con lo que se inició la sesión: provider, model, mode, effort, title, y repo / branch en una sesión en la nube. Nuevo en 0.9.16 También tiene group, el grupo de sesiones en el que entró la sesión nueva, tal como lo muestra list_sessions (id, name, role), o null.

Ponerla en un grupo Nuevo en 0.9.16 #

Sin group, una sesión iniciada en este relay se une al grupo de la sesión que la inició, o abre un grupo con esa sesión como cabecera. Una sesión iniciada en un relay emparejado no entra en ningún grupo.

Con group, la sesión nueva entra en ese grupo existente, en este relay o en uno emparejado. El agente nombra el grupo por su id, o por su nombre tal como lo lista relay_info, sin distinguir mayúsculas. Un group vacío cuenta como ninguno.

{
  "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."
}

El relay busca el grupo en el destino antes de mostrar cualquier tarjeta de aprobación, igual que hace con el modelo, y la tarjeta lo nombra (Group: Release 2.4 (grp_…)). No se crea nada cuando:

• el destino no tiene ningún grupo con ese id o nombre. La llamada se rechaza con REMOTE_RELAY_UNKNOWN_GROUP, y error y groups listan los grupos de allí (hasta 20, con groupsTotal cuando hay más): Relay "build-box" has no session group "Relase". Groups there: Release 2.4 (grp_…), … No session was created.
• el nombre encaja con más de un grupo. El mismo código, con los grupos de ese nombre: … Pass the id.
• el grupo se disolvió entre la búsqueda y el inicio. El mismo código.
• no se pueden leer los grupos del destino. Un relay demasiado antiguo para group responde REMOTE_RELAY_UNSUPPORTED (The target relay doesn't support groups on create_session yet: …); uno que no responde o rechaza el token responde con su código habitual.

Cuando la sesión se creó pero no acabó en el grupo pedido, el resultado tiene groupWarning, su summary termina en (no group: …), y la note le pide al agente que te lo diga. Entonces puedes mover la sesión a mano.

create_session solo admite un grupo existente. Para poner la sesión en un grupo nuevo, el agente llama después a update_session con ese nombre. Renombrar, disolver y reorganizar grupos sigue siendo cosa tuya.

update_session Nuevo en 0.9.16 #

Cambia los ajustes de otra sesión para sus próximos turns, sin enviarle un prompt, y responde con los ajustes que tiene ahora y lo que cambió. Funciona en este relay y en uno emparejado.

Se necesita al menos un ajuste. Cualquier otro argumento se rechaza y no se cambia nada. mayCreateSessions no está entre los ajustes: 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 cambio a una carpeta nueva indica además si se reinició la CLI (relaunched), y un grupo nuevo vuelve como groupCreated. Una llamada que no cambiaría nada responde changed: [] y no pregunta a nadie. note lleva lo que el agente debe saber, por ejemplo una ventana tomada como la más cercana, o que la ventana y el razonamiento solo se aplican a sesiones de Claude (Nuevo en 0.9.18 incluidas las sesiones de Claude API) y no cambian nada en otro proveedor. Nuevo en 0.9.17 Una sesión de DeepSeek también recibe esa nota, pero allí la ventana sí tiene efecto, y 0 significa 400.000 tokens; thinking_enabled no, porque una sesión de DeepSeek siempre razona.

Quién puede cambiar qué. Un agente solo cambia libremente una sesión que inició su propia conversación: en este relay, o en un relay emparejado cuando ese relay registró esta conversación como la que la inició. Cualquier otra sesión, tuya, de otro agente o la que inició al agente, necesita antes tu Allow. Una tarjeta de pregunta te consulta una vez por conversación y relay, nombra la sesión y lista el cambio (Model: … · Effort: … · Group: …); Allow cubre los cambios posteriores de esa conversación en sesiones así de allí. Deny rechaza la llamada con REMOTE_RELAY_PERMISSION; una conversación sin un turn en curso en el que preguntar recibe REMOTE_RELAY_NO_ACTIVE_TURN. El otro relay aplica él mismo la misma regla. Un agente nunca cambia la conversación en la que se ejecuta. En los modos ask y plan se aplica además la tarjeta habitual de una acción de escritura.

Antes de que cambie nada, el relay comprueba toda la llamada en el destino: el modelo y el reasoning effort, el grupo, la carpeta y si hay que preguntarte. Un modelo desconocido, un id de grupo desconocido, un nombre de grupo que encaja con dos grupos, una carpeta que el relay no puede usar o una carpeta nueva para una sesión ocupada rechazan la llamada antes de cualquier tarjeta, y no se cambia nada.

Grupos.

• Un nombre que el relay no tiene crea un grupo nuevo con ese nombre. Un id de grupo tiene que existir (REMOTE_RELAY_UNKNOWN_GROUP).
• Un grupo que creaste tú nunca se elimina así. Cuando un agente saca su última sesión, el grupo se queda y aparece en tu barra lateral como group · empty (grupo · vacío): renómbralo o disuélvelo desde su menú, o deja que un agente vuelva a nombrarlo. Nada lo elimina por sí solo.
• Un grupo que creó un agente, por nombre o al iniciar sesiones, desaparece en cuanto queda vacío.

La carpeta. Un cwd nuevo reinicia la CLI de la sesión en esa carpeta. Se rechaza con REMOTE_RELAY_BUSY mientras haya un turn en cola o en curso allí, o se ejecute una tarea en segundo plano: The session cannot move to another folder now: …. La carpeta tiene que ser una que el relay pueda usar. Una sesión que aún no ha arrancado conserva la carpeta para su primer arranque. Si la CLI no se reinicia, la carpeta se guarda igualmente para su próximo arranque, y la respuesta lo dice. No para Claude Cloud, que trabaja sobre un clon de su repositorio.

El modo fijado así dura hasta el siguiente send que nombre otro modo o venga de alguien que llama en otro modo: un send sin mode transmite el modo propio de quien llama.

Si un paso falla después de que otros se hayan escrito, la respuesta sigue listando en changed lo que se escribió. Una página abierta muestra cada cambio al instante. Un relay que ejecuta un OAR más antiguo responde REMOTE_RELAY_UNSUPPORTED.

Qué modelos se aceptan Nuevo en 0.9.13 #

Un model en send o create_session se comprueba contra la lista que ofrece New Chat (Nuevo chat) para el proveedor en el relay de destino, la misma lista que muestra relay_info, antes de cualquier tarjeta de aprobación. Un modelo que no está en ella se rechaza con REMOTE_RELAY_UNKNOWN_MODEL, y no se crea ni se envía nada:

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

El resultado lleva también suggestions, las coincidencias cercanas, y models, los ids válidos. Antes de 0.9.13 un id así creaba una sesión con otro modelo, a la que las llamadas send posteriores con ese id no podían llegar.

Nuevo en 0.9.19 Los ids de modelo de Copilot llevan puntos: claude-opus-5.5, no el claude-opus-5-5 de Claude. Copilot rechaza el id de otro proveedor antes de crear nada: con COPILOT_MODEL_UNAVAILABLE y la coincidencia más cercana o, en create_session, con el código del único otro proveedor que lista ese id, como CLAUDE_PROVIDER_REQUIRED. Una sesión de Copilot nunca pasa a otro proveedor por el nombre de su modelo.

Cuando el modelo que se ejecuta difiere del que se pidió, el modelNote del resultado lo dice. Cuando el relay de destino aún no tiene lista para el proveedor (su detección de modelos no se ha ejecutado o ha fallado), el modelo sigue adelante sin comprobar y modelNote también lo dice. Un relay también rechaza un modelo de Copilot desconocido cuando el agente de otro relay inicia una sesión en él.

wait #

Sigue esperando una respuesta que send o create_session no recibieron a tiempo.

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

Esperar y lo que vuelve #

send, create_session y wait esperan la respuesta todo el tiempo que el agente pida en wait_seconds, hasta Longest wait per tool call (Espera máxima por llamada a herramienta) en el relay en el que se ejecuta el agente (Settings → Relays → Agent sessions): 10 minutos de forma predeterminada, ajustable de 2 a 60 minutos. Cuando una llamada pidió más de lo que permite el relay, el resultado lo dice en una note. Cuando se acaba el tiempo, el agente recibe lo que haya hasta entonces y puede volver a llamar a wait.

Un turn que espera sigue contando para Max turn duration (Duración máxima del turn) en Settings → General (Ajustes → General).

El status del resultado dice en qué punto está la otra sesión:

Cada uno de estos resultados lleva session y message_id, y openUrl, un enlace que abre la sesión, cuando el relay tiene uno.

Dirigir otra sesión #

answer_question #

Responde a una tarjeta de pregunta que espera en otra sesión. A los agentes se les indica que te pregunten primero, salvo que les hayas dicho que decidan ellos.

Se necesita choices o answer. Un agente no puede responder a su propia pregunta, ni a una tarjeta de aprobación de un relay: esas son tuyas. Nuevo en 0.9.16 Tampoco puede responder a una pregunta que no bloquea: answer_question la rechaza con REMOTE_RELAY_FORBIDDEN antes de llamar a nadie.

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

stop #

Detiene el turn que está en curso en una sesión, como hace Stop (Detener) en la interfaz. El resultado dice si se pidió una detención o si no había nada en curso.

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

archive #

Archiva una sesión.

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

Vigilar sesiones #

Nuevo en 0.9.10 En lugar de preguntar una y otra vez, un agente puede suscribirse a sesiones y que lo despierten cuando ocurre algo en ellas. Funciona en este relay (con las sesiones de agentes activadas) y en un relay emparejado.

Una suscripción solo notifica. No aprueba nada ni responde nada; lo que pide un evento se decide como antes, por ti o por el agente dentro de lo que puede hacer de todos modos.

subscribe #

Una conversación puede tener 20 suscripciones a la vez. La propia conversación del agente nunca se vigila.

{ "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
  }
}

Menos despertares Nuevo en 0.9.16 #

Cada despertar es un turn completo del agente que vigila. Tres opciones de subscribe piden menos. question_asked, question_answered y error nunca quedan retenidos por ninguna de ellas; todos los demás eventos, incluidos task_failed, stalled y all_idle, sí.

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

• digest_minutes. Los eventos de la suscripción se reúnen y llegan como un mensaje cada N minutos: como pronto N minutos después de crear la suscripción, y cada uno de los siguientes N minutos después del anterior. El mensaje dice Digest of 4 events (subscription sub_… every 30 min; questions and errors come at once):. Un resumen de un único evento se lee como ese evento.
• quiet_hours. Una ventana diaria de hora local en una zona horaria IANA. from y to son horas del día (HH:MM, de 00:00 a 23:59) y tienen que ser distintas; la ventana puede pasar de la medianoche. Lo que ocurre dentro espera y llega como un mensaje cuando termina la ventana, con la línea 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. Dentro no se genera ningún latido. Un evento que un resumen entregaría dentro de la ventana se mueve a su final.
• exclude. Una suscripción a todas las sesiones (all) ignora estas, también para all_idle, stalled y el latido. Con una lista de sesiones se rechaza: exclude goes with sessions ["all"] only; a list of sessions names what it watches.

Cambios de hora. La ventana sigue el reloj de la zona horaria. La noche en que se atrasan los relojes y to llega dos veces, la ventana termina la primera vez y no se vuelve a entrar en ella en la hora repetida. La noche en que se adelantan y se saltan to, termina en el momento del salto. Un límite conocido: un from dentro de la hora repetida abre la ventana en la primera pasada, y en la segunda pasada los minutos anteriores a from cuentan como fuera de ella.

Un valor incorrecto se rechaza diciendo qué está mal, por ejemplo 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, o quiet_hours tz "Berlin" is not an IANA time zone (for example "Europe/Berlin", "America/New_York", "UTC"). Un quiet_hours con todos los campos vacíos cuenta como ninguno.

• Con once. El evento que termina una suscripción de un solo disparo sigue respetando su resumen y sus horas de silencio: la suscripción termina al momento, y el evento llega cuando estos lo permiten.
• Varias suscripciones. Un evento que recogieron varias suscripciones del agente que vigila sale cuando la primera de ellas lo deja salir; una suscripción sin opciones lo deja salir al momento.
• El límite por hora de 20 despertares se mantiene por encima de las opciones (Cómo llegan los eventos).
• Los eventos retenidos, y cuándo tocan, sobreviven a un reinicio del relay.
• La tarjeta de aprobación nombra las opciones (digest every 30 min, quiet 23:00–06:00 Europe/Berlin, except 1 it leaves out).

Sin eco de los propios prompts del agente que vigila. Cuando el agente que vigila envía él mismo un prompt a una sesión con send o create_session y recibe la respuesta terminada de esa llamada o de un wait posterior, el turn_end de ese turn no lo despierta una segunda vez; mientras sigue esperando, el turn_end queda retenido. Los errores y las preguntas del turn siguen llegando. Un prompt que no esperó (wait_seconds: 0 y ningún wait) lo despierta con turn_end como antes, igual que un turn_end que termina una suscripción once.

Eventos #

Los eventos predeterminados Nuevo en 0.9.13 #

Una suscripción que no nombra events recibe question_asked, error, turn_end, subagent_finished, task_failed, stalled y all_idle. Un subagent en segundo plano que terminó despierta al agente que vigila, igual que cualquier tarea que falló o salió con un código distinto de cero, pero un comando de shell o un monitor que terminó bien no. Una sesión ocupada termina uno cada minuto más o menos, y cada uno le costaría al agente que vigila un turn sobre todo su contexto. Para recibir cada fin de tarea, nombra los eventos con task_finished en lugar de subagent_finished, y task_started para los inicios.

Las suscripciones creadas antes de 0.9.13 sin events pasan solas a este valor predeterminado; las que nombraron sus eventos los conservan. Un relay emparejado con un OAR más antiguo aplica su propio valor predeterminado y rechaza subagent_finished por nombre.

Cómo llegan los eventos #

OAR escribe un mensaje corto en la conversación que vigila. Se muestra como una fila de evento compacta, nunca como uno de tus mensajes, y empieza con una línea que dice qué es:

[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 el agente que vigila está inactivo, el mensaje inicia un turn nuevo. Si está en mitad de un turn, consulta la tabla de abajo.
• Los eventos que caen dentro de 30 segundos llegan como un solo mensaje.
• Pasados 20 despertares en una hora, el resto llega como un resumen cada 10 minutos. question_asked y error siguen llegando al momento (Nuevo en 0.9.16 y question_answered). Cuando este resumen y el digest_minutes de una suscripción coinciden, una sola línea Digest of nombra ambos.
• Nuevo en 0.9.16 El digest_minutes y las quiet_hours de una suscripción retienen más tiempo sus demás eventos.

En un relay emparejado #

El relay tiene que estar desbloqueado en la conversación y permitir al menos la lectura, y el otro relay tiene que aceptar agentes de otros relays. Basta con un emparejamiento en un sentido. Este relay recoge los eventos cada pocos segundos, y sus líneas empiezan con el nombre del otro relay:

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

Si se cae el enlace, el otro relay guarda lo que ocurre, hasta 500 eventos por suscripción durante 7 días, y lo entrega como una fila marcada como replayed (reproducido) en cuanto vuelve a responder, entre una línea link_lost y una link_restored. Un relay que ejecuta un OAR más antiguo responde que necesita una actualización.

Nuevo en 0.9.16 El resumen y las horas de silencio de una suscripción a un relay emparejado se aplican aquí, donde está el agente que vigila; exclude también se pasa al otro relay, para all_idle, stalled y el latido. Los eventos reproducidos respetan el resumen y las horas de silencio como cualquier otro; la línea link_restored dice entonces cuántos de ellos están retenidos y llegarán más tarde. Un relay emparejado con un OAR más antiguo no conoce exclude: este relay sigue descartando los eventos de esas sesiones, pero aquel relay los cuenta para all_idle, para las detenciones por silencio y en la lista del latido.

unsubscribe #

Termina una suscripción, o con "all" todas las suscripciones que la conversación tiene en el relay nombrado.

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

list_subscriptions #

Muestra las suscripciones de la conversación: las activas y las que terminaron en la última hora, con el motivo. Con watcher, muestra las suscripciones de otra conversación, que es como un agente las consulta antes de asumirlas.

{ "action": "list_subscriptions" }

Cada suscripción muestra sus sesiones, eventos, once, match, stalledMinutes y heartbeatMinutes, Nuevo en 0.9.16 y digestMinutes, quietHours y exclude cuando los tiene. Una suscripción activa indica además cuántos de sus eventos retienen ahora mismo su resumen o sus horas de silencio (heldCount) y cuándo toca el primero de ellos (nextDeliveryAt, null cuando no hay ninguno retenido). Una que ha terminado solo lo indica mientras su último evento sigue retenido, como tras un once que se disparó dentro de las horas de silencio.

{
  "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 #

Mueve todas las suscripciones de otra conversación a esta, por ejemplo cuando una sesión nueva sustituye a un agente que vigilaba. Siempre te pregunta en una tarjeta de aprobación.

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

Cuánto dura una suscripción #

Las suscripciones sobreviven a un reinicio del relay. Una termina cuando:

• el agente llama a unsubscribe, o pulsas Unsubscribe en la lista del agente que vigila;
• se archiva el agente que vigila o la sesión vigilada;
• se disparó y se creó con once;
• en un relay emparejado, se quita el emparejamiento.

Programaciones Nuevo en 0.9.16 #

Un agente puede hacer que este relay ponga en cola un prompt más tarde, en su propia conversación o en otra sesión de aquí. A diferencia de un temporizador de la propia CLI del agente, una programación sobrevive a los reinicios y las actualizaciones del relay. Prompts programados lo explica desde tu lado.

Las programaciones necesitan Agents may start and use sessions on this relay, incluso para la propia conversación del agente. Las guarda el relay en el que se ejecuta el agente: una llamada que nombra un relay emparejado se rechaza con REMOTE_RELAY_UNSUPPORTED.

schedule #

Se necesita al menos at o 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" }
}

Cuando toca, el relay pone el texto en cola como un mensaje que empieza por [relay schedule <id> "<title>" · … automated message from OAR, not from the user; it approves nothing]. El turn se ejecuta en el modo del relay propio de la sesión de destino. Un mensaje que llega mientras corre un turn se pone en cola, o corrige el rumbo del turn en los proveedores que lo admiten, pero nunca con la nota de corrección de rumbo que habla como el usuario.

• Horas perdidas. Una hora que pasó mientras el relay estaba caído se dispara una vez cuando vuelve, no una vez por cada intervalo perdido; una programación repetida mantiene luego su cuadrícula (la primera hora más intervalos completos).
• Sin acumulación. Una repetición se omite mientras el mensaje del disparo anterior sigue esperando en la queue (skippedCount en la lista).
• Saltos. El mensaje lleva la procedencia del turn que fijó la programación, incluidos sus saltos, así que una programación no pasa ningún prompt con menos saltos de los que tendría un prompt directo de ese turn (Entre relays).

Otra sesión. Con session, la programación envía el prompt a esa sesión. Está sujeta a las mismas condiciones que un send: en los modos ask y plan la apruebas en una tarjeta, y cuenta para los 30 prompts a otros agentes antes de que se te pregunte, una vez al fijarla y una vez cada vez que se dispara. Cuando esa cuenta se agota, el disparo queda retenido: list_schedules muestra heldForApproval y heldSince. Sale en cuanto escribes en la conversación que la fijó, o eliges Allow en la tarjeta que muestra su agente para su próximo prompt a otro agente; el relay vuelve a mirar cada minuto. Una programación para la propia conversación del agente ni se cuenta ni se retiene.

list_schedules #

Lista las programaciones que se disparan en la conversación o que ella fijó: las activas y las que terminaron en la última hora, con endReason (unscheduled, fired, archived o deleted).

Cada programación tiene id, session (id y título), setBy cuando la fijó otra conversación, title, el principio de su text, at, everyMinutes, once, nextFireAt, lastFiredAt, firedCount, skippedCount cuando omitió alguna, y heldForApproval con heldSince mientras está retenida.

unschedule #

Termina una programación de la conversación: una que se dispara en ella o que ella fijó.

Cuándo termina una programación #

Una programación termina tras dispararse cuando tiene once, con unschedule o con Cancel (Cancelar) en la lista ⏰ de la cabecera, y cuando se archiva o se elimina la sesión en la que se dispara o la conversación que la fijó. Una compactación mueve en cambio ambos tipos a la conversación nueva. Una conversación tiene como mucho 20 programaciones activas que se disparan en ella, y puede fijar como mucho 20 para otras sesiones; por encima, REMOTE_RELAY_SCHEDULE_LIMIT.

Preguntas que no bloquean Nuevo en 0.9.16 #

Un agente puede hacerte una pregunta y seguir trabajando: la pregunta aparece como una tarjeta en su sesión y en tu Inbox, y el agente conoce la respuesta más tarde. Preguntas y la Inbox lo explica desde tu lado.

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 vuelve enseguida con question_id y status: "pending". El agente debe seguir con lo que no depende de la respuesta y no volver a preguntar lo mismo mientras esté pendiente.

La respuesta. Cuando respondes o descartas la pregunta, el agente recibe el evento del relay question_answered, con question_id, tu answer, la choice que elegiste, dismissed cuando la descartaste, y via, el relay en el que respondiste: aquel en el que se guarda la pregunta, o un relay emparejado cuya Inbox usaste. No necesita suscripción. El evento es urgente: ningún resumen ni horas de silencio lo retienen. Es automático y no aprueba nada más, y no cuenta como un mensaje tuyo para la protección contra bucles: responder a una pregunta no reinicia la cuenta de prompts que los agentes pueden enviarse entre sí.

Quién responde. Solo tú, en la sesión o en una Inbox (la de este relay, o la de un relay emparejado con él). answer_question rechaza estas preguntas.

Condiciones.

• Una pregunta sobre la propia conversación del agente, list_questions y withdraw no necesitan ningún ajuste ni mención.
• Con session, el agente pregunta en nombre de otra sesión: en este relay con Agents may start and use sessions on this relay, en un relay emparejado con Agents may al menos en Read and prompt y el relay desbloqueado. Una pregunta así es una escritura: en los modos ask y plan la apruebas en una tarjeta, y respeta el límite de saltos (Entre relays). La protección contra bucles no la cuenta. La tarjeta aparece en esa sesión, y tanto ella como la conversación que pregunta reciben la respuesta.
• Una pregunta sobre una sesión de un relay emparejado se guarda en ese relay; este relay comprueba cada 5 segundos si tiene respuesta mientras está abierta (cada 30 segundos mientras aquel relay no responde). Un relay que ejecuta un OAR más antiguo responde REMOTE_RELAY_UNSUPPORTED.

Puede haber como mucho 20 preguntas pendientes por conversación que pregunta, y 20 por sesión sobre la que tratan; por encima, REMOTE_RELAY_QUESTION_LIMIT. Las preguntas no caducan.

list_questions #

Lista las preguntas de la conversación: las pendientes, y las respondidas, descartadas o retiradas en el último día, con su estado y su respuesta. Con session, las preguntas sobre otra sesión. En un relay emparejado lista las preguntas que esta conversación hizo allí; read_session allí lista todas las preguntas pendientes de una sesión.

withdraw #

Retira una pregunta que sigue pendiente. Solo la conversación que preguntó puede retirarla.

Una pregunta también termina cuando se archiva o se elimina su sesión (no se avisa a nadie), y cuando se quita el emparejamiento con el relay en el que se guarda. Una compactación mueve sus preguntas a la conversación nueva.

Límites #

Errores #

Una llamada rechazada vuelve con un code con el que el agente puede actuar.