Rodar o Narya

O Narya se divide entre um host e seus clientes. O host é dono do armazenamento, das sessões e das conexões com os modelos. Na sua própria máquina, um cliente envia uma mensagem e lê o resultado pelo socket local. Um cliente interativo começa um host quando nenhum host responde, e depois o conduz pela mesma API HTTP que todos os outros clientes.

​

Autentique-se na sua organização

---

Na sua própria máquina, o host aceita o seu próprio usuário do sistema operacional sem autenticação. Autentique-se na sua organização para o trabalho que chega a ela além desta máquina: compartilhamentos, os repositórios GitHub da sua organização, e registrar, alterar ou chamar extensões. O primeiro trabalho autenticado em um home reivindica o home para a sua organização. A pessoa autenticada passa a ser dona do trabalho feito ali antes. Depois disso, o host recusa uma requisição sem token enquanto esta máquina não está autenticada nessa organização. Preencha a tabela [identity] no config.toml com os valores que a sua organização fornece: issuer, jwks_url, auth_url, device_url e client_id. Um host sem issuer ou jwks_url recusa todo token. O host aplica uma mudança em [identity] no seu próximo início depois que uma pessoa permite o novo config.toml em uma conversa acompanhada. Veja Quando uma mudança de configuração vale.

• O narya login imprime uma URL e um código curto. Abra a URL em qualquer máquina com navegador e digite o código.
• O narya whoami informa com qual identidade esta máquina está autenticada, sem chamada de rede.
• O narya logout remove a autenticação.

O Narya guarda os tokens e os renova quando expiram. O cliente interativo e todo comando que fala com o host em execução os apresentam.

​

O host

---

​

Manter o host vivo entre logins

---

O narya daemon install grava um serviço de login e o carrega: um LaunchAgent no macOS e uma unit systemd de usuário no Linux. Os dois rodam narya host start e o reiniciam depois de uma falha. O Narya grava a unit com permissões 0600. Ele define NARYA_HOME dentro da unit em vez de herdar o valor. O narya daemon status responde três perguntas em separado: registrado, carregado e servindo. O narya daemon uninstall remove a unit e nada mais. Suas sessões, seu armazenamento e sua configuração continuam. O host e cada sessão dentro dele sobrevivem a um terminal fechado. Um narya -p posterior se conecta ao host em execução em vez de abrir o armazenamento por conta própria.

​

Sessões

---

Cada sessão se liga a um caminho de repositório. Retome uma com narya -s <session-id> ou com narya -p --session <session-id>.

• O narya session list lista as sessões no armazenamento.
• O narya export <session-id> grava uma transcrição na saída padrão. Escolha --format markdown ou --format jsonl. Adicione --reasoning e --tool-output para mais detalhe.
• O narya import <file> --repository <absolute path> lê uma transcrição de outra ferramenta. Defina --format claudecode ou --format opencode.
• O narya session promote <session-id> entrega a sessão ao host em execução, então uma pergunta de permissão posterior nela é recusada e registrada.
• O narya session share <session-id> copia a sessão para o home da sua organização. Adicione sync para continuar enviando as entradas posteriores.

​

Compartilhar uma sessão

---

Um compartilhamento copia uma sessão para o home da sua organização, onde sua equipe a lê. O host mascara as entradas antes que elas saiam da sua máquina. Você define as regras de mascaramento na tabela [sharing.redaction] do config.toml. Dois campos da publicação são opcionais:

• O expiresAt define quando o compartilhamento termina. Sem ele, vale a janela do host. Defina essa janela com default_expiry na tabela [sharing].
• O recipients nomeia os colegas para quem o compartilhamento é. Sem ele, o compartilhamento é para a organização inteira. Apenas o dono da sessão pode nomear destinatários.

Um 503 com NRY-0029 significa que o host registrou o compartilhamento e enfileirou as entradas dele, mas o home da organização não respondeu. O host envia as entradas mais tarde. Cada publicação cria um novo compartilhamento, então uma segunda publicação da mesma sessão cria um segundo compartilhamento.

• O GET /v1/sessions/{sessionId}/share lista os compartilhamentos ativos da sessão que você pode alterar.
• O PUT /v1/shares/{shareId}/recipients altera para quem um compartilhamento é.
• O DELETE /v1/sessions/{sessionId}/share revoga todos os compartilhamentos da sessão e apaga a cópia no home da organização. Um 503 com NRY-0029 significa que a cópia ainda está lá. Envie a requisição de novo quando o home responder.
• O GET /v1/shares no home da organização lista os compartilhamentos que você pode ler lá.

Um compartilhamento revogado não volta. Para compartilhar a sessão de novo, publique-a de novo, o que cria um novo compartilhamento.

​

Rodar uma sessão em um ambiente

---

Um ambiente é um contêiner que o host provisiona para as suas sessões. Uma sessão que não nomeia nenhum ambiente roda na máquina do host. O host provisiona ambientes apenas quando a variável de ambiente NARYA_SANDBOX_IMAGE nomeia a imagem a rodar. O host os roda no Docker Engine 23 ou posterior, e a imagem já deve estar no daemon do Docker. Adicione --container ao narya ou ao narya -p para abrir uma nova conversa em um contêiner próprio, conversation-<sessionId>. Pela API, defina container como true no POST /v1/sessions. Este contêiner, e todo contêiner de um home hospedado, para depois de 15 minutos sem uso, mantém os seus arquivos e volta a rodar na próxima mensagem. Arquivar a conversa remove o contêiner.

• O POST /v1/environments cria um ambiente. Apenas o id é obrigatório. O setupScript roda uma vez dentro do novo ambiente. O repository nomeia um repositório que sua organização selecionou no GitHub App do Narya, como owner/name, e o host o clona no ambiente.
• O GET /v1/environments lista os seus ambientes, e o GET /v1/environments/{environmentId} lê um deles.
• O DELETE /v1/environments/{environmentId} destrói um ambiente.

Para rodar uma sessão em um ambiente, coloque o id do ambiente no campo environment do POST /v1/sessions. Uma criação é idempotente no id. Quando você envia um id que já criou, o host responde 200 com esse ambiente. Ele não provisiona nada e não roda nenhum script de configuração. Quando o script de configuração retorna, o host para cada processo que o script deixou rodando. Um processo que saiu do grupo de processos do script, por exemplo com setsid, e ainda roda faz a configuração falhar. Quando o script de configuração falha ou passa do limite de tempo do host, o ambiente fica unusable. O campo setup dele traz o resultado e a saída do script. Uma sessão não pode rodar em um ambiente unusable. Destrua-o e depois crie-o de novo com um script corrigido.

​

Um home que a Lerian hospeda

---

A Lerian também roda o Narya como um home hospedado, um para cada organização. O home hospedado serve a mesma API do host. Cada sessão nele roda em um contêiner.

• Uma sessão que não nomeia nenhum environment, clone ou container recebe o seu contêiner, conversation-<sessionId>, no primeiro turno. Com clone, ou com container definido como true, a sessão recebe o seu contêiner na criação.
• Defina clone no POST /v1/sessions para clonar um repositório no contêiner quando a sessão é criada. Nomeie um repositório que sua organização selecionou no GitHub App do Narya, como owner/name. A sessão trabalha no próprio branch, narya/conversation-<sessionId>.
• Depois do clone, o .narya/setup.sh do repositório roda uma vez no contêiner. O setupScript o substitui. Um clone ou uma configuração que falha não abre nenhuma sessão.
• O caminho repository de uma sessão é relativo ao workspace do home.
• Arquivar a conversa remove o contêiner, o clone e o branch dela. Um branch que a sessão enviou continua no GitHub.

Quando a configuração de um repositório dá certo, o home salva uma cópia desse contêiner, chamada snapshot. O próximo contêiner do mesmo repositório e da mesma configuração começa do snapshot, no branch padrão, e não roda nenhuma configuração. O home descarta um snapshot depois de 24 horas, ou quando o .narya/setup.sh do repositório muda, e tira um novo na próxima configuração que dá certo. Se a configuração editar um arquivo que o git rastreia, o home não guarda nenhum snapshot. Um home hospedado recusa estas requisições com 422:

• Uma instalação de pacote. Registre uma extensão em um endereço HTTPS no lugar.
• Um login subscription.
• Uma resposta de confiança. Uma sessão nele recebe a confiança do seu contêiner.
• Um worktree em uma nova sessão.

​

Checkpoints e rebobinagens

---

Dentro de um repositório git, o Narya registra pontos de restauração da sua árvore de trabalho em um repositório git sombra ao lado do seu checkout. Seu próprio histórico git nunca muda. Nenhum temporizador remove um checkpoint. Fora de um repositório git, o Narya não registra nenhum, e recusa uma rebobinagem dos arquivos. Uma rebobinagem leva uma sessão para trás na conversa, nos arquivos, ou em ambos. Diga o escopo, porque ele não tem padrão. Antes de uma rebobinagem mover arquivos, o Narya registra a árvore como ela está, então o estado que você deixa vira um ponto de restauração próprio.

​

Saúde e reparo

---

O narya doctor percorre a instalação e informa o que encontra:

• a pasta raiz e a configuração
• o host e o armazenamento
• as sessões, os jobs de pacotes e os servidores de ferramentas
• as credenciais
• o binário e o terminal

Ele não repara nada. Cada achado nomeia o comando que o corrige. O narya repair <session-id> é a saída de uma quarentena. Na inicialização, o Narya recupera cada sessão que um desligamento sujo deixou rodando e coloca em quarentena a que ele não consegue reproduzir. Esse comando tenta essa recuperação de novo. Adicione --retire para arquivar a sessão em vez disso, com a transcrição mantida.

​

Retenção

---

O Narya apaga os eventos de um turno depois que o turno termina, e a transcrição mantém o turno. O Narya guarda todo o resto até você dizer o contrário. Defina uma idade máxima por classe em [retention] no config.toml.

• O narya retention status informa o que uma varredura removeria.
• O narya retention run faz a varredura.
• O narya purge <session-id> --yes apaga uma sessão e a transcrição dela. Ele recusa enquanto a sessão tem um compartilhamento ativo, então revogue o compartilhamento antes.

O narya repair, o narya retention e o narya purge abrem o armazenamento por conta própria, então recusam enquanto um host roda. Pare o host antes com narya host stop.