Skip to main content
Narya ejecuta agentes de programación detrás de una sola API HTTP. Un host de larga vida en tu máquina hace el trabajo, y cada cliente usa esa única API. La API tiene un documento OpenAPI 3.1. Lerian genera el servidor del host y su propio cliente Go a partir de este documento. Tres tipos de cliente la hablan. El cliente de terminal que entrega Lerian abre una sesión interactiva. El comando de un solo turno narya -p ejecuta un turno para un pipeline. Un cliente que tú escribas usa las mismas operaciones, sin un paso de inicio de sesión por delante.

​
Qué posee el host

  • Sesiones: conversaciones duraderas, cada una ligada a una ruta de repositorio.
  • Lanes: las vías paralelas dentro de una sesión.
  • Checkpoints y rewinds: puntos de restauración de tu árbol de trabajo, y los movimientos de vuelta a ellos.
  • El almacén: la base de datos que guarda las sesiones y las decisiones. El host toma su bloqueo.
  • Conexiones con los modelos: el host llama al proveedor del modelo con tu credencial.
  • Programaciones: prompts en el reloj del host, bajo un tope de gasto.
  • Workflows: programas JavaScript que orquestan agentes.
  • Monitores: comandos de larga duración junto a una sesión, cuya salida llega a la conversación.
  • Preguntas de permiso: las preguntas delante de una llamada a herramienta, y las respuestas que das.

​
Alcanza el host

El host escucha en un socket Unix en tu home de Narya. Narya crea el socket solo para su dueño, y los permisos del archivo son toda la autorización. No hay contraseña, ni token, ni TLS. Cualquier proceso que se ejecute bajo tu cuenta tiene la API completa. El socket es narya.sock dentro de tu home de Narya, que es ~/.config/narya de forma predeterminada. Define NARYA_HOME para moverlo. Sobre ese socket el host habla HTTP/1.1 y responde JSON con campos en camelCase. La autoridad de la URL no lleva nada, así que ahí sirve cualquier nombre.
Cuando un host está en ejecución, el comando de un solo turno es él mismo un cliente de esta API. Una ejecución de un solo turno que no encuentra host abre el almacén por sí misma, cuando ningún otro proceso de Narya lo tiene tomado.

​
Los resultados llegan por el stream de eventos

Un resultado nunca vuelve por la solicitud que lo causó. Un mensaje responde 202 con un id de turno. Todo lo que produce ese turno te llega en GET /v1/events como server-sent events. Un frame es una línea id:, luego una línea data:, luego una línea en blanco. La línea data lleva un envelope JSON. Su campo type dice de qué evento se trata: un delta de texto, una llamada a herramienta, una pregunta de permiso, un turno terminado. Un cliente lee una sola forma y se ramifica según type. Envía un header Last-Event-ID para retomar donde te detuviste. Un cursor que nombra un evento más nuevo que el almacén responde 409. Un consumidor demasiado lento para seguir el ritmo pierde su propia conexión, y todos los demás clientes siguen recibiendo el stream. Dos parámetros de consulta acotan el stream. sessionId mantiene una sesión. hostEvents=true agrega los eventos que no pertenecen a ninguna sesión, y solo se aplica junto a sessionId. narya -p --json imprime estos mismos envelopes, uno por línea. Un pipeline y un cliente leen un solo formato. Consulta Automatización y CI.

​
Una sola forma para listas y errores

Una lista paginada responde un envelope de cursor: items, limit y un nextCursor cuando queda más. Los cursores son opacos, y la API no ofrece paginación por offset. El almacén crece por anexado, así que un offset se desplaza ante una escritura concurrente. Un solo envelope de error: code, title y message, más fields en un 422. Un código es NRY- y cuatro dígitos. La lista de errores nombra cada código y qué hacer al respecto.

​
Lee la referencia

Resumen de la API del host de Narya

Resumen de la API del host de Narya: transporte, streaming, envelopes y cada operación.

Lista de errores de la API del host de Narya

Cada código con el que responde el host, qué lo provoca y la salida.