Automação e CI

Um pipeline conduz o Narya do mesmo jeito que você: o binário, um prompt, uma credencial no ambiente e um código de saída.

Um turno a partir da linha de comando

narya -p "<prompt>" roda um turno e responde na saída padrão. As flags dele:

--repo <path> define o repositório de trabalho, e assume por padrão o diretório de trabalho.
--model <id> escolhe o modelo.
--agent <name> roda o turno sob um agente nomeado.
--session <id> continua uma sessão existente.
--style <name> nomeia um estilo de resposta que você declarou como [styles.<name>] em config.toml. Ele não pode se juntar a --session.
--json muda a saída para um formato de máquina.

Códigos de saída

Código	Significado
`0`	O turno rodou até o fim. A resposta está na saída padrão.
`1`	O turno falhou. Uma chave que o provedor rejeitou cai aqui.
`2`	Uso, configuração ou um store que outro processo do Narya segura. A ausência de credencial para o provedor resolvido cai aqui.
`130`	Interrompido. A transcrição sobrevive, e `--session` a retoma.

As duas falhas de credencial carregam códigos diferentes de propósito. Uma chave ausente sai com 2, e uma chave rejeitada sai com 1. Tente de novo no 1. No 2, leia a mensagem primeiro: um store preso se libera sozinho, e uma credencial ausente não.

Um turno que para cedo ainda sai com 0. Três finais fazem isso: um teto de saída, o filtro de conteúdo do provedor e um teto de gasto. O código de saída sozinho não pode distinguir uma resposta cortada de uma completa. O Narya nomeia os dois primeiros na saída de erro padrão, e --json carrega os três como stopReason no evento turn-finished.

Os dois formatos de `--json`

narya -p --json transmite um envelope de evento por linha na saída padrão. Cada linha carrega id, type e timestamp. Uma linha acrescenta sessionId e laneId quando o evento pertence a uma sessão ou a uma lane. payload é null quando o evento não carrega corpo. A saída simples carrega apenas a lane principal. O stream carrega cada lane, então selecione por laneId. Estes são os mesmos envelopes de evento que o host transmite na API dele, então um pipeline e um cliente leem um único formato. Cada outro comando responde com um documento. As ações compartilham um envelope:

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

result é uma palavra para você ramificar. changed aparece apenas em uma execução que mudou algo. Uma saída diferente de zero carrega reason no lugar. narya schedule add, narya schedule rm, narya schedule budget e narya export publicam o próprio documento em caso de sucesso, e imprimem o envelope apenas em caso de falha. Ramifique pelo código de saída nesses quatro, nunca por result. Sob --json, a saída padrão carrega o documento ou o stream e nada mais. Frases para uma pessoa vão para a saída de erro padrão.

A credencial em um runner

Coloque a chave do provedor no secret store do seu CI e entregue-a ao step como <PROVIDER>_API_KEY. O processo que chama o fornecedor lê essa variável do próprio ambiente, então um runner sem host rodando não consulta nenhum keychain e não armazena 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."

O step falha quando o Narya sai com código diferente de zero, e a resposta cai no log do job.

O Narya lê o histórico da própria branch, então faça o checkout da branch inteira.

Agendamentos

Coloque trabalho no relógio do host.

narya schedule add "<prompt>" --every <duration> repete em um intervalo, e --at <RFC3339> dispara uma vez.
Acrescente --repo <path>, --agent <name> ou --budget <usd> a qualquer uma das formas.
narya schedule list lista o que existe, e narya schedule rm <schedule-id> remove um.
narya schedule budget <schedule-id> on <usd> ou off muda o teto de um agendamento existente.

O Narya recusa criar um agendamento em um diretório em que ninguém confia. Todos os quatro verbos falam com o host em execução. O teto de gasto vem ligado por padrão. Se você não define --budget, o agendamento assume o padrão do operador, $5.00 por disparo, como [schedules] ceiling_usd. Se você define um número, o Narya o mantém. Se você define 0, o Narya guarda o agendamento e recusa dispará-lo até você definir um orçamento.

Workflows

Um workflow é um programa JavaScript que orquestra agentes. Comece um por caminho ou como código inline, pela API do host. O Narya recusa um programa inválido antes de qualquer coisa rodar. Um programa de workflow chama quatro capacidades:

agent(step, agent, task) roda um agente.
agents([...]) roda uma onda, lida na ordem que você pediu.
step(name, value) registra um step.
args entrega ao programa os argumentos da própria execução.

Três tetos são constantes, e nenhuma configuração os muda: 72 horas por execução, 4.096 chamadas ao host e 4 horas por step. O Narya tira um snapshot do código no envio, então uma execução retomada usa o código que foi enviado.

​Um turno a partir da linha de comando

​Códigos de saída

​Os dois formatos de --json

​A credencial em um runner

​Agendamentos

​Workflows

Um turno a partir da linha de comando

Códigos de saída

Os dois formatos de `--json`

A credencial em um runner

Agendamentos

Workflows