Pular para o conteúdo principal
O Narya roda agentes de código atrás de uma API HTTP. Um host de vida longa 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 prompt para um pipeline. Um cliente que você escreve conduz as mesmas operações com um token próprio.

​
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.
  • Workflows: programas JavaScript que orquestram agentes.
  • Monitores: comandos de longa duração ao lado de uma sessão, cuja saída chega à conversa. Um monitor iniciado com wake definido como true começa um turno quando a saída dele chega enquanto a conversa está ociosa. Quem o iniciou paga por esse turno.
  • Perguntas de permissão: as perguntas antes de uma chamada de ferramenta e as respostas que você devolve.

​
Chegar ao host

Na sua própria máquina, o host escuta em um socket Unix na sua pasta Narya. O Narya cria o socket apenas para o dono, e o socket não usa TLS. A requisição de uma pessoa carrega um bearer token do provedor de identidade definido nas suas configurações [identity]. O host verifica a assinatura, o emissor, a expiração, e a pessoa e a organização que o token nomeia. Uma requisição com um token que não é válido recebe 401 com NRY-0011. Um chamador cujo papel não tem a permissão que uma operação exige recebe 403 com NRY-0028. Uma operação que declara outro esquema de segurança também aceita essa credencial: o stream de eventos aceita a requisição assinada de uma extensão registrada. Na sua própria máquina, o host também aceita uma requisição sem token do seu próprio usuário do sistema operacional. Essa requisição recebe 401 com NRY-0011 no trabalho que chega à sua organização além desta máquina. Rodar o Narya diz quando o host exige autenticação. Qualquer outra requisição sem credencial recebe 401 com NRY-0011. Quando você está autenticado, os clientes que a Lerian entrega apresentam o token que o narya login guardou. 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

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. Envie uma idempotencyKey com uma mensagem, e um reenvio cuja resposta se perdeu não começa um segundo turno. Novas faixas, agendamentos, execuções de workflow e resumos também aceitam uma chave. 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. 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.