Automação e CI

Rode o Narya a partir de um pipeline com um comando e um código de saída, coloque trabalho no relógio e orquestre vários agentes a partir de um script.

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>" envia um prompt, espera a sessão ficar ociosa e responde na saída padrão. Ele também espera cada monitor armado com wake e os turnos que esse monitor inicia. O texto enviado por pipe ou redirecionado para a entrada padrão vai antes do prompt, com uma linha em branco entre eles, como em git diff | narya -p "Review this change.". O Narya lê a entrada padrão até o fim, a menos que ela seja um terminal. Adicione < /dev/null a uma execução que não deve lê-la.

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. O Narya primeiro entrega ao host, como desacompanhada, uma sessão que uma pessoa abriu, como faz narya session promote. As perguntas de permissão dela passam a ser recusadas, também quando a pessoa a reabre com narya -s. Em um diretório em que ninguém confia, o Narya recusa a entrega e a execução sai com 1. Uma sessão que o narya -p criou continua em qualquer diretório.
• --style <name> nomeia um estilo de resposta que você declarou como [styles.<name>] em config.toml. Ele não pode se juntar a --session.
• --instructions <file> acrescenta um arquivo de instruções ao prompt de sistema. Repita para mais arquivos. Uma execução que vai para um host em execução recusa essa opção.
• --json muda a saída para um formato de máquina.
• --allow <action>:<resource> deixa a execução fazer essa ação sem perguntar até o host parar, como faz uma regra allow do permissions.toml. Repita a flag para mais, como --allow "shell:make deploy" ou --allow network:docs.rs. O Narya recusa uma regra que o permissions.toml recusaria e sai com 2. Com permission_mode = "custom", ele também recusa uma regra que alcança um deny no seu permissions.toml.

​

Códigos de saída

---

Código	Significado
0	O turno rodou até o fim. A resposta está na saída padrão. Um turno que foi concluído sem prosa, depois de pelo menos uma chamada de ferramenta, e cujas chamadas rodaram todas também sai com 0, e a saída de erro padrão diz isso.
1	O turno falhou, ou terminou sem texto de resposta, a menos que tenha sido concluído, feito pelo menos uma chamada de ferramenta e toda chamada tenha rodado. Uma chave que o provedor rejeitou cai aqui.
2	Uso, configuração, um modelo que o Narya não consegue resolver 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 com texto de resposta 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. Quando uma rodada atinge o teto de saída, ou seu stream cai, o Narya pede ao modelo que continue, no máximo duas vezes, antes de encerrar o turno. Uma parada do filtro de conteúdo nunca continua. O código de saída sozinho não pode distinguir uma resposta cortada de uma completa. O Narya nomeia cada final na saída de erro padrão, e --json o carrega 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 resposta ao seu prompt. 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.

Alguns comandos publicam o próprio documento em caso de sucesso e imprimem o envelope apenas em caso de falha, entre eles o narya export e os verbos de narya schedule. Ramifique pelo código de saída nesses, 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 provedor lê essa variável do próprio ambiente. Em um runner sem host rodando, esse processo é o próprio narya -p. O Narya não salva essa chave no keychain nem no arquivo por provedor.

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.

Um config.toml ou permissions.toml alterado vale depois que uma pessoa o permite em uma conversa acompanhada. O narya -p e os agendamentos nunca perguntam, então mantêm a última versão permitida. Isso vale em um runner cuja pasta Narya persiste entre execuções. Um arquivo que o usuário do host não pode alterar vale como está escrito, como o de um mount somente leitura. Veja Quando uma mudança de configuração vale.

​

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> cancela um.
• narya schedule budget <schedule-id> on <usd> muda quanto um disparo de um agendamento existente pode gastar. off impede o agendamento de disparar até você definir um número de novo. none remove o teto.

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.

Um agendamento tem um teto de gasto apenas quando você define um. Se você não define --budget, o agendamento assume [schedules] ceiling_usd do config.toml. Sem essa chave, o agendamento não tem teto. Um disparo sem teto pode delegar trabalho, rodar narya a partir do shell e acordar por monitores. 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. Nomeie o repository em que a execução trabalha. Um caminho de script deve ficar dentro desse repositório. O Narya recusa um programa inválido antes de qualquer coisa rodar.

Um programa de workflow chama cinco capacidades:

• agent(step, agent, task) roda um agente.
• agents([...]) roda uma onda, lida na ordem que você pediu.
• step(name, value) registra um step.
• callTool(name, args) roda uma ferramenta na própria sessão da execução, como um step. Ela segue as mesmas regras de permissão e os mesmos hooks que a chamada de um modelo. Uma chamada recusada, ou uma ferramenta que falha, lança um erro que o script pode capturar.
• args entrega ao programa os argumentos da própria execução.

Uma execução assume o clientKind que você envia ao iniciá-la, e api sem ele. Ninguém acompanha uma sessão do tipo api, então o Narya recusa uma pergunta de permissão nela e registra um motivo. Em um diretório em que ninguém confia, os turnos dela falham, e a mensagem diz como confiar no diretório. Envie inline ou tui quando uma pessoa responde às perguntas. Veja Sessões acompanhadas e desacompanhadas.

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.