Saltar al contenido principal
Narya ejecuta agentes de programación detrás de una sola API HTTP. Un host de larga vida 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 prompt para un pipeline. Un cliente que tú escribas usa las mismas operaciones con un token propio.

​
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.
  • Workflows: programas JavaScript que orquestan agentes.
  • Monitores: comandos de larga duración junto a una sesión, cuya salida llega a la conversación. Un monitor iniciado con wake en true inicia un turno cuando su salida llega mientras la conversación está inactiva. Quien lo inició paga ese turno.
  • Preguntas de permiso: las preguntas delante de una llamada a herramienta, y las respuestas que das.

​
Alcanza el host

En tu propia máquina, el host escucha en un socket Unix en tu home de Narya. Narya crea el socket solo para su dueño, y el socket no usa TLS. La solicitud de una persona lleva un bearer token del proveedor de identidad definido en tu configuración [identity]. El host comprueba la firma, el emisor, la expiración, y la persona y la organización que nombra el token. Una solicitud con un token que no es válido recibe 401 con NRY-0011. Un llamador cuyo rol no tiene el permiso que exige una operación recibe 403 con NRY-0028. Una operación que declara otro esquema de seguridad también acepta esa credencial: el stream de eventos acepta la solicitud firmada de una extensión registrada. En tu propia máquina, el host también acepta una solicitud sin token de tu propio usuario del sistema operativo. Esa solicitud recibe 401 con NRY-0011 en el trabajo que llega a tu organización más allá de esta máquina. Ejecuta Narya dice cuándo el host exige autenticación. Cualquier otra solicitud sin credencial recibe 401 con NRY-0011. Cuando estás autenticado, los clientes que entrega Lerian presentan el token que guardó narya login. 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 mensaje responde 202 con un id de turno. Todo lo que produce ese turno te llega en GET /v1/events como server-sent events. Envía una idempotencyKey con un mensaje, y un reenvío cuya respuesta se perdió no inicia un segundo turno. Los lanes nuevos, las programaciones, las ejecuciones de workflow y los resúmenes también aceptan una clave. 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. 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.