Automatización y CI

Un pipeline maneja Narya igual que tú: el binario, un prompt, una credencial en el entorno y un código de salida.

Un turno desde la línea de comandos

narya -p "<prompt>" ejecuta un turno y responde en la salida estándar. Sus flags:

--repo <path> define el repositorio de trabajo y, de forma predeterminada, usa el directorio de trabajo.
--model <id> elige el modelo.
--agent <name> ejecuta el turno bajo un agente con nombre.
--session <id> continúa una sesión existente.
--style <name> nombra un estilo de respuesta que declaraste como [styles.<name>] en config.toml. No puede combinarse con --session.
--json cambia la salida a un formato legible por máquinas.

Códigos de salida

Código	Significado
`0`	El turno se ejecutó hasta el final. La respuesta está en la salida estándar.
`1`	El turno falló. Una clave que el proveedor rechazó cae aquí.
`2`	Uso, configuración o un almacén que otro proceso de Narya retiene. No tener credencial para el proveedor resuelto cae aquí.
`130`	Interrumpido. La transcripción sobrevive, y `--session` la reanuda.

Las dos fallas de credencial llevan códigos distintos a propósito. Una clave ausente sale con 2, y una clave rechazada sale con 1. Reintenta con 1. Con 2, lee primero el mensaje: un almacén retenido se libera solo, y una credencial ausente no.

Un turno que se detiene antes de tiempo igual sale con 0. Tres finales hacen esto: un límite de salida, el filtro de contenido del proveedor y un límite de gasto. El código de salida por sí solo no puede distinguir una respuesta cortada de una completa. Narya nombra los dos primeros en el error estándar, y --json lleva los tres como stopReason en el evento turn-finished.

Las dos formas de `--json`

narya -p --json transmite un envelope de evento por línea en la salida estándar. Cada línea lleva id, type y timestamp. Una línea agrega sessionId y laneId cuando el evento pertenece a una sesión o a una lane. payload es null cuando el evento no lleva cuerpo. La salida simple lleva solo la lane principal. El stream lleva cada lane, así que selecciona por laneId. Estos son los mismos envelopes de evento que el host transmite en su API, así que un pipeline y un cliente leen un solo formato. Todos los demás comandos responden con un documento. Las acciones comparten un envelope:

{"command":"narya retention run","result":"swept","changed":{},"exitCode":0}

result es una palabra para ramificar. changed aparece solo en una ejecución que cambió algo. Una salida distinta de cero lleva reason en su lugar. narya schedule add, narya schedule rm, narya schedule budget y narya export publican su propio documento cuando tienen éxito, e imprimen el envelope solo cuando fallan. Ramifica por el código de salida para esos cuatro, nunca por result. Con --json, la salida estándar lleva el documento o el stream y nada más. Las frases para una persona van al error estándar.

La credencial en un runner

Pon la clave del proveedor en el almacén de secretos de tu CI y entrégala al paso como <PROVIDER>_API_KEY. El proceso que llama al proveedor lee esa variable de su propio entorno, así que un runner sin un host en ejecución no consulta ningún keychain y no almacena nada.

name: narya review

on: pull_request

permissions:
  contents: read

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false

      # Add a step here that places your licensed narya binary on PATH.
      - name: Ask Narya
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          # Pass the ref through env, never into the script text. A ref with
          # shell metacharacters would run as script on this runner.
          BASE_REF: ${{ github.base_ref }}
        run: |
          narya -p "Read the changes on this branch against origin/$BASE_REF.
          Name every change that breaks a caller, with the file and why."

El paso falla cuando Narya sale con un código distinto de cero, y la respuesta cae en el log del job.

Narya lee el historial propio de la rama, así que haz checkout de la rama completa.

Programaciones

Pon trabajo en el reloj del host.

narya schedule add "<prompt>" --every <duration> se repite en un intervalo, y --at <RFC3339> dispara una vez.
Agrega --repo <path>, --agent <name> o --budget <usd> a cualquiera de las dos formas.
narya schedule list lista lo que existe, y narya schedule rm <schedule-id> elimina una.
narya schedule budget <schedule-id> on <usd> o off cambia el límite de una programación existente.

Narya se niega a crear una programación en un directorio en el que nadie confía. Los cuatro verbos hablan con el host en ejecución. El límite de gasto está activo de forma predeterminada. Si no defines --budget, la programación toma el valor predeterminado del operador, $5.00 por disparo, como [schedules] ceiling_usd. Si defines un número, Narya lo conserva. Si defines 0, Narya guarda la programación y se niega a dispararla hasta que definas un presupuesto.

Workflows

Un workflow es un programa de JavaScript que orquesta agentes. Inicia uno por ruta o como código fuente en línea, a través de la API del host. Narya rechaza un programa inválido antes de que algo se ejecute. Un programa de workflow llama a cuatro capacidades:

agent(step, agent, task) ejecuta un agente.
agents([...]) ejecuta una tanda, que se lee en el orden que pediste.
step(name, value) registra un paso.
args entrega al programa los argumentos de su propia ejecución.

Tres límites son constantes, y ningún ajuste los cambia: 72 horas por ejecución, 4,096 llamadas al host y 4 horas por paso. Narya toma una instantánea del código fuente al enviarlo, así que una ejecución reanudada usa el código que se envió.

​Un turno desde la línea de comandos

​Códigos de salida

​Las dos formas de --json

​La credencial en un runner

​Programaciones

​Workflows

Un turno desde la línea de comandos

Códigos de salida

Las dos formas de `--json`

La credencial en un runner

Programaciones

Workflows