Skip to main content
O Narya roda agentes de código atrás de uma API HTTP. Um host de vida longa na sua máquina faz o trabalho, e todo cliente conduz essa mesma API. A API tem um documento OpenAPI 3.1. A Lerian gera o servidor do host e seu próprio cliente Go a partir desse documento. Três tipos de cliente a falam. O cliente de terminal que a Lerian entrega abre uma sessão interativa. O comando de execução única narya -p roda um turno para um pipeline. Um cliente que você escreve conduz as mesmas operações, sem passo de login na frente.

​
De que o host é dono

  • Sessões: conversas duradouras, cada uma ligada a um caminho de repositório.
  • Faixas: as trilhas paralelas dentro de uma sessão.
  • Checkpoints e rebobinagens: pontos de restauração da sua árvore de trabalho e os movimentos de volta até eles.
  • O armazenamento: o banco de dados que guarda as sessões e as decisões. O host toma o lock dele.
  • Conexões com os modelos: o host chama o fornecedor do modelo com a sua credencial.
  • Agendamentos: prompts no relógio do host, sob um teto de gasto.
  • Workflows: programas JavaScript que orquestram agentes.
  • Monitores: comandos de longa duração ao lado de uma sessão, cuja saída chega à conversa.
  • Perguntas de permissão: as perguntas antes de uma chamada de ferramenta e as respostas que você devolve.

​
Chegar ao host

O host escuta em um socket Unix na sua pasta Narya. O Narya cria o socket apenas para o dono, e as permissões de arquivo são toda a autorização. Não há senha, não há token e não há TLS. Qualquer processo que rode sob a sua conta tem a API inteira. O socket é o narya.sock dentro da sua pasta Narya, que é ~/.config/narya por padrão. Defina NARYA_HOME para mudá-la de lugar. Sobre esse socket o host fala HTTP/1.1 e responde JSON com campos em camelCase. A autoridade na URL não carrega nada, então qualquer nome funciona ali.
Quando um host está rodando, o comando de execução única é ele próprio um cliente dessa API. Uma execução única que não encontra host abre o armazenamento por conta própria, quando nenhum outro processo Narya o segura.

​
Os resultados chegam pelo stream de eventos

Um resultado nunca volta na requisição que o causou. Uma mensagem responde 202 com um id de turno. Tudo o que esse turno produz chega a você em GET /v1/events como server-sent events. Um quadro é uma linha id:, depois uma linha data:, depois uma linha em branco. A linha data carrega um envelope JSON. O campo type dele diz qual é esse evento: um delta de texto, uma chamada de ferramenta, uma pergunta de permissão, um turno terminado. Um cliente lê um formato e se ramifica por type. Envie um header Last-Event-ID para retomar de onde parou. Um cursor que nomeia um evento mais novo que o armazenamento responde 409. Um consumidor lento demais para acompanhar perde a própria conexão, e todos os outros clientes seguem recebendo o stream. Dois parâmetros de query estreitam o stream. O sessionId mantém uma sessão. O hostEvents=true acrescenta os eventos que não pertencem a nenhuma sessão, e apenas se aplica ao lado do sessionId. O narya -p --json imprime esses mesmos envelopes, um por linha. Um pipeline e um cliente leem um formato só. Veja Automação e CI.

​
Um formato para listas e erros

Uma lista paginada responde um envelope de cursor: items, limit e um nextCursor quando ainda resta algo. Os cursores são opacos, e a API não oferece paginação por offset. O armazenamento recebe muitas inserções, então um offset se desloca sob uma escrita concorrente. Um envelope de erro: code, title e message, mais fields em um 422. Um código é NRY- e quatro dígitos. A lista de erros nomeia cada código e o que fazer com ele.

​
Leia a referência

Visão geral da API do host do Narya

Visão geral da API do host do Narya: transporte, streaming, envelopes e cada operação.

Lista de erros da API do host do Narya

Cada código com que o host responde, o que o dispara e a saída.