DEV Community

Cover image for ¿Por qué osFoundry hace que Codex CLI consulte un cursor por recurso en vez de enviarle los cambios?
BBT for BBT Español

Posted on

¿Por qué osFoundry hace que Codex CLI consulte un cursor por recurso en vez de enviarle los cambios?

Esto es todo lo que el servidor MCP de osFoundry ofrece a un cliente que quiere enterarse de cuándo cambia algo. Ejecutado desde este Mac, sin token:

$ uv run --with tiktoken --with jsonschema python3 watch_sim.py
== Part 1: live wire, 8 calls each, ms ==
initialize                   HTTP 200  median  414.7  p90  757.8
tools/list                   HTTP 200  median  606.8  p90  716.7
resources/subscribe          HTTP 200  median  450.6  p90  550.2
GET (stream)                 HTTP 405  median  423.9  p90  475.4
tools/call poll (no token)   HTTP 401  median  322.0  p90  463.9
initialize capabilities: {"tools": {"listChanged": false}}
resources/subscribe -> {"code": -32601, "message": "Method not found"}
GET body -> ''
poll without token -> isError True | Authentication required
rate limit headers: limit 2000, reset in 61 s
Enter fullscreen mode Exit fullscreen mode

Las tres vías de push están cerradas. initialize declara herramientas y nada más, con listChanged: false, así que ni siquiera la lista de herramientas avisará de un cambio. resources/subscribe devuelve "Method not found". Un GET a la URL MCP, donde un servidor Streamable HTTP abriría un stream del servidor al cliente, devuelve 405. Lo que queda es una única herramienta de solo lectura:

{"name": "poll_resource_events",
 "description": "Resume from an event sequence for one granted channel, Note, knowledge base, record, or session.",
 "inputSchema": {"properties": {
     "resource_type": {"enum": ["message_channel", "note", "knowledge_base", "record_channel", "room",
                                "gitnest_repository", "agent_session", "team_session", "loop_session",
                                "graph_session"]},
     "resource_id": {"type": "string"},
     "after_sequence": {"type": "integer", "minimum": 0},
     "limit": {"type": "integer", "minimum": 1, "maximum": 100}},
   "required": ["resource_type", "resource_id"], "additionalProperties": false},
 "annotations": {"readOnlyHint": true, "openWorldHint": false, "destructiveHint": false},
 "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:read"]}]}
Enter fullscreen mode Exit fullscreen mode

Un recurso "one granted", "resume from an event sequence". El resto del post trata de esas palabras, con el lado del cliente reconstruido en Python. Aquí no hay ningún binario de codex instalado, así que el script hace de cliente. El código del servidor de osFoundry no es público: las partes 1 y 2 son el servidor en vivo, y la parte 3 es una reconstrucción con sus propias formas de respuesta y tasas de actividad.

¿Por qué polling y no push, en el caso de Codex?

Codex CLI no es un daemon. Corre cuando lo ejecutas, hace un turno y termina o se queda esperándote. Un canal push necesitaría algo escuchando entre tus sesiones, y en un portátil muchas veces no hay nada. Un cursor de secuencia encaja con esa forma de trabajar: el cliente guarda un entero por recurso, vuelve cuando quiere y pregunta qué pasó después de ese número.

Los milisegundos de arriba están medidos desde Japón en un Apple M1, así que dicen más de la ruta que del servidor. Importa más la cabecera de rate limit. Las respuestas sin autenticar llevan X-RateLimit-Limit: 2000 con un reset unos 61 s más adelante. No se comprobó si un cliente con sesión iniciada tiene el mismo presupuesto, pero incluso consultar 30 recursos cada 30 s son 60 peticiones por minuto. Lo que limita a un vigilante hecho con Codex no es la carga del servidor, sino sus propios turnos: cada poll es una llamada a herramienta que el modelo tiene que hacer y leer.

¿Cómo descubre un cliente qué puede consultar?

Con dos llamadas, y los schemas dicen mucho del diseño:

list_granted_resources   osfoundry:read  ro=True required=[] props=[]
list_project_resources   osfoundry:read  ro=True required=['project_id', 'resource_type'] props=['project_id', 'resource_type', 'search', 'offset', 'limit']
poll_resource_events     osfoundry:read  ro=True required=['resource_type', 'resource_id'] props=['resource_type', 'resource_id', 'after_sequence', 'limit']
59 tools on server; these three = 591 of 12662 tokens (4.7%, cl100k_base)
poll_resource_events types: 10 | list_project_resources types: 9 | only pollable: ['graph_session']
Enter fullscreen mode Exit fullscreen mode

list_granted_resources no acepta ningún argumento, y el schema cierra la puerta a añadir uno:

list_granted_resources   no arguments           ok
list_granted_resources   project_id passed      REJECT additionalProperties
Enter fullscreen mode Exit fullscreen mode

Es el servidor diciéndole al cliente lo que tiene, no el cliente pidiendo algo. Las instrucciones de initialize empiezan con "Use list_granted_resources first." La respuesta son los proyectos añadidos a la conexión y los recursos concedidos de forma individual. En el cliente web (ExternalAssistantsPanel.tsx) corresponden a la sección Projects y a "Older individual access".

list_project_resources necesita un resource_type. No existe un listado de "todo lo que hay en este proyecto", así que un inventario completo es una llamada por tipo, nueve tipos, y más cuando un tipo tiene más de 50 elementos (limit máximo 50, paginado con offset). Su descripción añade la única excepción al acceso por proyecto: "Ordinary Message channels require a separate invitation."

graph_session se puede consultar pero no listar. Los Graphs viven en el escritorio del propietario y llegan a través de list_graph_sessions, y solo después de que el propietario los comparta desde la app de escritorio.

¿Por qué el cursor es del cliente y no del servidor?

osFoundry tiene los dos tipos. wait_for_messages, en la red de agentes, guarda un cursor por ti: "Without after_sequence it resumes where your last call stopped", y hace long polling con timeout_s de hasta 50. poll_resource_events no tiene ninguna de las dos cosas. timeout_s se rechaza y su descripción solo dice "resume from", así que el número lo aporta el cliente:

wait_for_messages props: ['after_sequence', 'timeout_s', 'limit'] timeout_s max 50 | poll_resource_events has timeout: False
poll_resource_events     timeout_s 30           REJECT additionalProperties
Enter fullscreen mode Exit fullscreen mode

Un cursor guardado en el servidor es cómodo para un solo oyente. Se rompe cuando dos clientes comparten conexión, que es justo lo que pasa cuando abres Codex en dos terminales con el mismo login. La reconstrucción hace pasar 600 eventos de canal por dos terminales que se turnan al azar para consultar:

two terminals, client cursor: A saw 600/600, B saw 600/600
two terminals, server cursor: A saw 305/600, B saw 295/600
Enter fullscreen mode Exit fullscreen mode

Con un cursor por conexión en el servidor, cada terminal lo avanza en nombre de la otra y cada una ve más o menos la mitad. Con after_sequence en la petición, las dos lo ven todo y el servidor no guarda ningún estado por lector. Para el log de un recurso que varias herramientas pueden leer por separado, ese es el dueño correcto del cursor.

El schema no hace obligatorio after_sequence y tampoco dice qué significa omitirlo. No dependas de eso. Guarda el número y envíalo siempre.

¿Cuántas llamadas cuesta una página llena?

limit llega hasta 100. Después de una importación masiva, una nota puede tener cientos de eventos esperando. Vaciarlos significa volver a llamar desde la última secuencia hasta que una página llegue incompleta:

burst of 350 events, limit 100:  4 calls to drain, cursor ends at 350
burst of 350 events, limit  50:  7 calls to drain, cursor ends at 350
burst of 350 events, limit  20: 18 calls to drain, cursor ends at 350
Enter fullscreen mode Exit fullscreen mode

Pide 100. En la reconstrucción, la respuesta ocupa 17 tokens con una página vacía y 41 con un evento, contados con cl100k_base. Son las formas de la reconstrucción, no las de osFoundry, pero el orden de magnitud basta para verlo: un poll vacío es barato de leer, así que el coste del polling está sobre todo en el número de turnos.

¿Cada cuánto debería Codex consultar 30 recursos?

La reconstrucción le da a un proyecto 30 recursos de los nueve tipos listables, con actividad desigual: 3 muy activos (un evento por minuto), 7 templados (uno cada 10 minutos) y 20 fríos (uno cada 2 horas). Esas tasas son una suposición. Simula una jornada de 8 horas con cinco semillas, sobre un reloj simulado:

every 30 s, all 30                 calls/hour   3600  empty  94.7%  seen late median   14.9 s  p90   27.0 s  max     30 s  (1843 events/day)
every 5 min, all 30                calls/hour    360  empty  78.0%  seen late median  150.9 s  p90  271.1 s  max    300 s  (1843 events/day)
30 s, x2 when empty, cap 10 min    calls/hour    502  empty  70.2%  seen late median   34.9 s  p90  206.4 s  max    599 s  (1843 events/day)
30 s, x2 when empty, cap 30 min    calls/hour    420  empty  65.3%  seen late median   35.6 s  p90  238.4 s  max   1799 s  (1843 events/day)
server window for comparison: 2000 requests per ~61 s
Enter fullscreen mode Exit fullscreen mode

Cada 30 s fijos es rápido y desperdicia el 95%: 3,600 llamadas por hora, casi todas vacías. Cada 5 minutos fijos es barato y lento en todo, también en el canal más activo. El backoff por recurso, que duplica el intervalo de un recurso tras cada poll vacío y lo reinicia con el primer evento, se acerca al número de llamadas del plan barato con una mediana de retraso cercana a la del rápido. Es porque los recursos activos se quedan en 30 s y los fríos se van espaciando. El precio es el tope: con 30 minutos, el primer cambio de un recurso frío puede esperar media hora.

Para Codex, esta tabla sobre todo es un argumento para no usar ningún temporizador. Cuando alguien pregunta "¿qué ha cambiado?", una pasada con los cursores guardados cuesta una llamada por recurso vigilado y responde sin ningún retraso para todo lo ocurrido hasta ese momento. El plan con backoff es para un script que mantiene a Codex, o a cualquier otra cosa, vigilando.

¿Qué pasa cuando el propietario retira el acceso?

El propietario quita el proyecto a las 4 h 07 min. Los 30 cursores apuntan ahora a recursos que la conexión no puede leer. La pregunta es cuánto tiempo sigue el cliente consultándolos:

owner removes the project at 4 h 07 min (30 resources lose access):
  re-list grants every 10 min    failed polls after removal  180, list_granted_resources calls 25
  re-list grants every 60 min    failed polls after removal 3180, list_granted_resources calls 5
  re-list grants on first error  failed polls after removal    1, list_granted_resources calls 5
Enter fullscreen mode Exit fullscreen mode

Revisar los permisos con un temporizador o cuesta llamadas o quema miles de polls fallidos. Tratar el primer poll rechazado como un "vuelve a leer los permisos" cuesta un fallo y un list_granted_resources extra. Después, descarta todos los cursores cuyo recurso ya no aparezca en la lista. Si el propietario vuelve a añadir el proyecto más adelante, el cliente empieza esos recursos desde cero.

¿Dónde frenan los schemas a un cliente?

Los casos restantes, comprobados con jsonschema (Draft 2020-12) contra los inputSchema en vivo:

list_project_resources   no resource_type       REJECT required
list_project_resources   limit 50               ok
list_project_resources   limit 51               REJECT maximum: limit
list_project_resources   graph_session          REJECT enum: resource_type
list_project_resources   search 101 chars       REJECT maxLength: search
poll_resource_events     no after_sequence      ok
poll_resource_events     graph_session          ok
poll_resource_events     after_sequence -1      REJECT minimum: after_sequence
poll_resource_events     limit 100              ok
poll_resource_events     limit 101              REJECT maximum: limit
poll_resource_events     resource_type project  REJECT enum: resource_type
Enter fullscreen mode Exit fullscreen mode

resource_type: "project" es lo primero que prueba casi todo el mundo. Un proyecto no es un recurso con log. Es el permiso que hace visibles los recursos.

El script completo tardó 20.2 s de tiempo real en el M1, 40 llamadas de red incluidas. El tiempo de CPU de usuario fue de 0.91 s.

Si lo montas tú mismo

  • Mantén un log por recurso y deja que el cliente guarde el cursor. Así, dos lectores en una misma conexión no se roban eventos y el servidor no guarda estado de lectores.
  • Dale a la lista de permisos su propia herramienta sin argumentos y haz que el cliente empiece por ahí. El descubrimiento solo debe devolver lo que el propietario concedió.
  • Pon un tope al tamaño de página y explica cómo vaciar (volver a llamar desde la última secuencia hasta recibir una página incompleta).
  • Aplica el backoff por recurso, no de forma global. Los recursos activos siguen rápidos y los fríos salen baratos.
  • Con el primer poll rechazado, vuelve a leer los permisos y descarta los cursores que ya no existen en lugar de reintentarlos.
  • Escribe el cursor después de haber actuado sobre los eventos, para que un fallo los repita en vez de saltárselos.

Cómo decide osFoundry qué herramientas recibe cada conexión está explicado en la página de tool scope. La definición breve del protocolo está en la entrada de MCP del glosario.

Top comments (0)