Durable agents (experimental)

Experimental. O wire, o SDK e esta página podem mudar, ou o recurso pode ser removido, em uma versão secundária posterior. Hoje apenas os próprios exemplos do Collie falam o wire. A saída diz o que decide se ele permanece. Se você não anexar nenhum agente durável, o Collie tem a mesma aparência e funciona como antes.

Se você criou um agente durável com o Pi Durable ou qualquer programa que forneça o wire, o Collie pode exibi-lo no seu celular. Ele recebe solicitações de aprovação, histórico e uma visualização de chat sem qualquer código de UI.

Um agente durável é um dos lugares de onde uma sessão pode vir, e cada uma de suas conversas é uma sessão. As palavras estão em Terminologia. O Collie não armazena chaves de modelos: um agente durável usa a própria chave de API ou um login do ChatGPT, e uma assinatura da Anthropic não pode ser usada por meio de um harness de terceiros.

Início rápido

Um agente durável de dez linhas, uma collie durable attach e um card de pergunta no seu celular.

Você precisa do Collie 1.22.0 ou posterior em execução nesta máquina, com o celular pareado (Instalação).

Um agente durável roda no Linux ou macOS, com Node 22.19 ou posterior ou Bun 1.4 ou posterior. Instale o SDK na pasta do seu agente durável:

npm install @colliepwa/durable-sdk@experimental
# or
bun add @colliepwa/durable-sdk@experimental

O pacote é publicado sob a dist-tag experimental do npm, nunca latest, e segue a saída em ADR 0104: se o durable wire deixar de existir, o pacote será descontinuado (ADR 0105).

A entrada Pi Durable do SDK é testada com Pi Durable 1.1.0 e 1.2.0. O Node 22.19 é o requisito mínimo do Pi Durable 1.2.0.

Salve este agente durável como hello.mjs. Ele tem dez linhas:

import { openCollie } from "@colliepwa/durable-sdk";

const socket = process.env.COLLIE_DURABLE_SOCKET ?? `${process.env.XDG_RUNTIME_DIR}/hello/app.sock`;
const collie = await openCollie({ socket, hostName: "hello", caps: { asks: true } });
const pane = collie.workspace("hello", { title: "Hello" }).tab("main", { title: "Questions" }).pane("deploy", { title: "Deploy", harness: "hello" });
collie.ready();
console.log(`listening ${collie.address}`);
const options = [{ id: "yes", label: "Yes" }, { id: "no", label: "No" }];
const answer = await pane.ask({ kind: "choice", toolCallId: "deploy-1", itemId: "deploy-1", title: "Deploy to staging?", options });
console.log(`answer: ${answer.optionIds[0]}`);
await collie.close();

Execute-o com node hello.mjs ou bun hello.mjs. Ele imprime listening /run/user/1000/hello/app.sock e aguarda. O mesmo agente durável é examples/durable-member/hello.ts em um clone do Collie.

No Node, ele grava primeiro mais uma linha: o Node não consegue ler quem se conecta ao socket do agente durável, portanto qualquer processo do seu usuário pode responder à pergunta. O Bun no Linux consegue, e recusa uma resposta vinda do próprio agente durável ou de um processo iniciado por ele.

No macOS, execute-o com Node. O Bun lá precisa de callerCheck: "off", que este agente durável não define. O macOS não tem XDG_RUNTIME_DIR, então defina COLLIE_DURABLE_SOCKET como um caminho absoluto antes.

Em um segundo terminal, anexe-o ao seu Collie e reinicie para que o Collie leia a nova entrada:

collie durable attach hello --socket /run/user/1000/hello/app.sock
collie restart

Use o caminho exibido pelo seu agente durável. Adicione --restart ao primeiro comando para reiniciar na mesma etapa. --restart reinicia a bridge do Collie: o celular reconecta em poucos segundos e as sessões do terminal continuam rodando.

Abra o Collie no celular. Uma seção Durable agents exibe uma linha, hello, com uma tag Experimental e uma pergunta aguardando. Toque na linha: ela abre na lista de conversas do agente durável, onde a conversa Deploy aguarda com "Deploy to staging?". Abra e toque em Yes ou No. O agente durável imprime a resposta e encerra.

Para escrever seu próprio agente durável, leia O SDK durável e O durable wire.

Anexar um agente durável

Cada agente durável é uma entrada em sources.json, e collie durable attach a grava.

collie durable attach desk --socket /run/user/1000/desk/app.sock
export EDGE_TOKEN=your-32-byte-random-token-here
collie durable attach edge --url https://edge.example.com --token-env EDGE_TOKEN
collie restart

No Windows, apenas o formato HTTPS está disponível: attach --socket recusa com código de saída 2 e informa para usar --url e --token-env, pois um socket privado precisa de IDs de usuário Unix.

sources.json fica na pasta de configuração ao lado do seu .env: a pasta de configuração do plugin Herdr (~/.config/herdr/plugins/config/herdr.collie/) em uma instalação gerenciada pelo Herdr, caso contrário ~/.config/collie/. attach imprime o caminho gravado. Os dois comandos acima gravam este arquivo:

[
  { "name": "desk", "kind": "durable", "socket": "/run/user/1000/desk/app.sock" },
  {
    "name": "edge",
    "kind": "durable",
    "url": "https://edge.example.com",
    "token": "your-32-byte-random-token-here"
  }
]

A bridge lê o arquivo na inicialização, portanto uma entrada entra em vigor após uma reinicialização. Seus terminais continuam com a mesma aparência e funcionamento de antes, ao lado dos agentes duráveis.

O Collie é rigoroso com o arquivo, pois um agente durável ignorado em silêncio nunca apareceria:

• —
  Um campo que a tabela não menciona interrompe a bridge. O mesmo vale para um kind incorreto, um nome que viole a regra, um nome usado duas vezes, ambos socket e url, nenhum dos dois, ou um url sem token.
• —
  Um arquivo inválido interrompe a bridge na inicialização com uma única linha. A linha começa com [bridge] FATAL: e informa a entrada e o campo. collie logs mostra isso. attach e detach também se recusam a sobrescrever um arquivo que não conseguem ler, de modo que um erro de digitação nunca custa suas outras entradas.
• —
  O arquivo é mantido no modo 0600. attach grava dessa forma. Quando o arquivo tem permissões mais amplas, a bridge as restringe na inicialização e informa isso em seu log.
• —
  Um nome não pode ser igual ao da sua sessão de terminal. Esse é default na maioria das instalações, e em uma instância exclusiva para agentes duráveis, default é o nome do seu próprio agente durável. A bridge para na inicialização e informa o nome da entrada.
• —
  Um agente durável mantém seu nome contra uma sessão do Herdr. Quando uma sessão do Herdr tem o nome de um agente durável, o telefone mostra o agente durável, oculta essa sessão do Herdr, e o log informa isso uma vez.

attach verifica o caminho do socket, a URL e o token pelas regras abaixo. Uma entrada criada manualmente é verificada quando a bridge acessa o agente durável: uma regra violada faz com que o agente durável apareça como inacessível com o motivo.

Duas formas de acessar um agente durável

O transporte por socket é para Linux e macOS. No Windows, use a URL e o token. O caminho do socket precisa ser absoluto e ter no máximo 103 bytes. Mantenha-o sob $XDG_RUNTIME_DIR, não /tmp: o serviço do Collie no Linux roda com um /tmp privado.

O Collie conecta a um socket somente quando todo o caminho é privado, pois o socket não transmite token. O socket pertence a você, sem permissão para grupo ou outros. Sua pasta pertence a você com o modo 0700. Nenhuma parte do caminho é um link simbólico, e nenhuma pasta acima dele tem permissão de escrita para grupo ou outros, exceto uma pasta com sticky bit como /tmp. O SDK cria a pasta do socket com o modo 0700 quando ela não existe.

A URL precisa começar com https://. A única exceção é http://127.0.0.1:<port> ou http://localhost:<port>, com uma porta, para um agente durável na mesma máquina. O Collie recusa qualquer outro endereço http://, pois o token trafegaria pela rede sem criptografia.

Atenção. Por https, o token é o único controle de acesso. Qualquer pessoa com ele pode ler todas as conversas e responder a todas as perguntas, e o host vê o texto. Um agente durável acessado dessa forma deve oferecer apenas Permitir e Negar, nunca uma permissão permanente.

Segurança dos agentes duráveis informa o que um agente durável pode fazer e o que o Collie registra em log.

Cada sondagem via https é uma requisição que seu host pode faturar, e uma resposta "nada mudou" também conta. Sem nenhum telefone aberto, a sondagem ociosa roda a cada 10 s, portanto o Collie faz perguntas 8.640 vezes ao dia. Verifique o que o plano do seu host permite para isso.

Um agente durável atrás de uma URL precisa atender ao protocolo do Collie e verificar o bearer token. Uma demonstração padrão do Pi Durable não faz nenhum dos dois, portanto o Collie não consegue conectá-la como está.

O Collie faz polling em um agente durável hospedado. Ele consulta a cada 2 s enquanto um telefone monitora; caso contrário, a cada 10 s. Cada sondagem desperta um Durable Object hibernando, de modo que um objeto hospedado permanece acordado enquanto o Collie monitora. O protocolo não usa WebSocket, portanto os recursos de hibernação e WebSocket dos Durable Objects não ajudam aqui.

O exemplo do Cloudflare está pausado e não faz parte de um release. Ele fica em experiments/durable-member-cloudflare/.

Os três verbos

attach, detach e list alteram ou leem sources.json, e não reiniciam nada a menos que solicitado.

collie durable attach <name> --socket <path> [--restart]
collie durable attach <name> --url <url> --token-env <VAR> [--restart]
collie durable detach <name> [--restart]
collie durable list

collie durable sem nenhum verbo, ou com um verbo desconhecido, imprime o uso e sai com 2. Com --restart, attach e detach executam o mesmo restart que collie restart.

list consulta a bridge em execução sobre cada entrada e aguarda no máximo 3 s por ela:

Quando um durable agent não aparecer, execute collie doctor, que indica a verificação com falha. As três causas comuns são uma entrada ainda não carregada (restart), um socket que não é privado (socket-not-private) e um arquivo de socket órfão deixado por uma falha (connection refused: exclua-o e inicie o durable agent). Solução de problemas de durable agents cobre os casos de durable agent. Solução de problemas cobre o Collie como um todo.

Tokens

Uma entrada url contém seu token, e o token é todo o controle de acesso.

openssl rand -hex 32

O resultado tem 64 caracteres hexadecimais, acima do mínimo de 32 bytes.

Gere um token de 32 bytes aleatórios ou mais, como acima, e forneça o mesmo valor ao durable agent. attach lê esse valor a partir da variável indicada por --token-env, para que não fique em nenhuma linha de comando nem no histórico do shell. Essa variável deve estar definida quando você executar attach.

attach copia o valor para sources.json em texto simples. O arquivo é, portanto, tão secreto quanto o token: o Collie o mantém no modo 0600, e um backup ou sincronização da pasta de configuração carrega o token. O Collie envia o token a cada requisição e nunca o imprime: list informa (token set).

O token não expira. Para alterá-lo, execute attach novamente com o mesmo nome e o novo token, depois reinicie:

export EDGE_TOKEN=your-new-32-byte-random-token-here
collie durable attach edge --url https://edge.example.com --token-env EDGE_TOKEN
collie restart

attach imprime updated edge. Forneça o novo token ao durable agent antes de reiniciar o Collie, caso contrário o celular informará que o durable agent recusou o token. Um durable agent pode aceitar um segundo token enquanto uma rotação ocorre, para que nenhum dos lados fique bloqueado. O exemplo parked da Cloudflare aceita COLLIE_TOKEN e, enquanto estiver definido, COLLIE_TOKEN_NEXT (ADR 0103). Defina o novo token como COLLIE_TOKEN_NEXT no durable agent, execute attach novamente e reinicie o Collie, depois mova o valor para COLLIE_TOKEN e desfaça a definição de COLLIE_TOKEN_NEXT.

Um durable agent isolado em um Collie

Uma instância sem terminal, como um host Windows ou um durable agent hospedado, pode controlar um durable agent a partir de seu .env.

# a durable agent on this machine, as you
COLLIE_MUX=durable
COLLIE_DURABLE_SOCKET=/run/user/1000/durable/session.sock

# or a durable agent you deployed behind TLS
COLLIE_MUX=durable
COLLIE_DURABLE_URL=https://durable-member.example.com
COLLIE_DURABLE_TOKEN=your-32-byte-random-token-here

Uma instância desse tipo dá a seu durable agent o nome default, e esse durable agent é sua sessão primária. As entradas em sources.json continuam rodando ao lado dele, sob outros nomes.

Defina o socket ou a URL com o token, nunca ambos. Definir ambos, uma URL sem token ou um token sem URL é um erro de configuração: o Collie inicializa, detalha o erro em seu log e indica o durable agent como inacessível com esse motivo.

Uma build anterior mantinha os logs de uma instância durable-only diretamente em <state>/durable/. Na primeira inicialização desta build, eles são movidos de forma definitiva para durable/default/, com uma linha informando no log.

Para alterar o token, envie o novo para o durable agent, configure-o no .env e execute collie restart. Uma instância durable-only entra em um crew usando seu hostname; por isso, defina um nome com collie crew join <lead-address> --label durable quando ela compartilhar um host com a líder.

Para desativar temporariamente todos os durable agents de sources.json, configure COLLIE_PROGRAMS=off no .env e execute collie restart. A bridge então ignora o arquivo, registra uma linha no log e roda como uma instalação sem durable agents, de modo que o telefone não exibe a seção Durable agents. collie doctor e collie durable list informam que os durable agents estão desativados. O arquivo permanece intacto: remova a variável e reinicie para reativar os durable agents. A variável não interfere na forma antiga de variável de ambiente citada acima.

Onde o Collie mantém os dados de um durable agent

O durable agent mantém o histórico de suas conversas. O Collie guarda um cache, seus recibos e a memória de push em sua pasta de estado.

A pasta de estado é ~/.local/state/collie/, ou COLLIE_STATE_DIR se essa variável estiver definida. <program> é o nome em sources.json, ou default. A pasta de cada durable agent tem permissão 0700, e cada log tem permissão 0600.

O cache é o motivo pelo qual o Chat abre rápido e continua funcionando mesmo se o durable agent estiver lento. Uma conversa encerrada é sempre lida do durable agent, nunca do cache.

Um durable agent retém apenas o trecho mais recente de uma conversa longa. Se ele descartou o início de uma conversa antes de o Collie lê-la, o Chat exibe uma linha no lugar: "Older messages were left out: the durable agent no longer keeps them." Nada foi perdido no seu telefone: o Collie nunca teve essas mensagens.

O que o celular exibe

Uma seção Durable agents no dashboard e, para cada durable agent, uma lista de suas conversas.

Cada durable agent ocupa uma linha na seção Durable agents, exibindo seu nome, uma etiqueta Experimental, seu runtime e se roda localmente ou em outro host. À direita, exibe a contagem de conversas abertas e, na cor de pendência, aquelas que aguardam você. A seção se desloca para cima de seus spaces enquanto houver uma pergunta pendente. Se um durable agent estiver iniciando ou inacessível, esse status substitui a contagem. Tokens ou versões de protocolo recusados recebem mensagens próprias no telefone; collie doctor informa qualquer outro motivo.

Toque em uma linha para abrir a lista de conversas do durable agent, como na listagem de um app de mensagens. As pendências para você aparecem primeiro, seguidas pelas outras conversas abertas e, por fim, as encerradas sob o rótulo Closed. As abertas são exibidas no Chat, e as encerradas abrem em modo somente leitura. O durable agent informa no hello o que suporta (asks, starters, send, steer, abort, rename, close, actions, history, reopen), e o telefone renderiza controles apenas para os recursos informados. Um durable agent não tem tela, portanto não possui visualização de Terminal nem digitação direta.

Ao enviar para um durable agent, o rótulo queued reflete o estado do turno monitorado pelo Collie. O Collie não exibe a fila interna da caixa de entrada do Pi. Uma tarefa em espera até um prazo limite aparece como ociosa ou em execução, nunca como em espera. Sessões traz mais detalhes.

O card de pergunta identifica o durable agent e mostra o tempo restante quando o durable agent define um. Uma pergunta decidida no durable agent, ou expirada por tempo limite, deixa uma linha no chat. Durable agents no telefone mostra cada um desses casos com uma figura.

Envio e Perguntas através da bridge

Um durable agent não tem tela, então o Collie não lê tela para ele. Em vez disso, a bridge lê seu próprio estado. Um durable agent recebe os mesmos comandos Send e Ask que um painel de terminal.

• —
  O estado. O turno vem do estado do seu painel. Uma pergunta vem do ask aberto mais antigo dele. A caixa de entrada está sempre vazia, porque um durable agent não tem caixa. O celular recebe esse estado a cada painel, no mesmo formato usado para um painel de terminal.
• —
  Um envio. POST /api/send recebe um ID de requisição do celular. A bridge grava a requisição em disco e bloqueia a conversa. Depois, ela envia o texto para o durable agent uma única vez, correspondente ao turno que ela leu. A resposta dele é a confirmação, e o recibo traz o ID da requisição que foi processada. Durante um turno, o durable agent guarda o texto para depois desse turno, e o recibo informa queued.
• —
  Os resultados. Um envio termina com sent, refused acompanhado de um motivo, ou unknown. unknown significa que o durable agent não confirmou o recebimento do texto. Leia o chat antes de enviar novamente. Um envio passa para effective quando o durable agent o registra na conversa. O item user correspondente traz o ID da requisição desse envio. Um envio simples é recusado enquanto qualquer pergunta estiver aberta, até mesmo uma que o Collie não consiga ler. Responda à pergunta ou use Steer ou Stop. Um turno iniciado depois da sua visualização recusa o envio, e nada chega ao durable agent.
• —
  Uma pergunta. POST /api/ask/<id> responde a ela. O ID do ask serve para uso único. A resposta carrega o hash da pergunta que você viu. A bridge o compara com a pergunta listada pelo durable agent no momento. Se forem diferentes, nada chega ao durable agent. A resposta mostra a pergunta como ela está agora. A resposta vai para o durable agent pelo seu próprio ID de ask. Nenhuma chave é enviada. O recibo informa channel: program e mantém o hash.
• —
  O que fica no card. Algumas perguntas não cabem em um único toque, então o estado as exibe como uma pergunta que o Collie não consegue ler (modal: unreadable). Você responde a elas no próprio card. - Uma pergunta de texto fica no card do próprio durable agent, porque a resposta é uma linha digitada por você. - Uma escolha múltipla fica no card do próprio durable agent, porque a resposta envolve mais de uma seleção. - Um formulário fica no card do próprio durable agent, porque a resposta é um conjunto de campos. - Always allow nunca é uma opção de contrato. Sua concessão continua válida após essa pergunta. Portanto, o card do durable agent pede um segundo toque antes, e um toque por /api/ask não pode ignorar esse toque.
• —
  Os contadores. collie doctor contabiliza essas leituras e resultados em uma única linha, program.

Nesta máquina, o celular usa estas rotas. Um envio simples passa por /api/send, e um toque no card de pergunta passa por /api/ask. O compositor informa o resultado sob o polegar usando as palavras do durable agent. Quando uma pergunta bloqueia o envio, um botão leva ao card dela. A lista de envios recentes do painel mostra cada recibo, e um envio em fila indica esse estado. Steer e Stop permanecem nas rotas da própria conversa, pois um steer não faz parte do Send Protocol. Um durable agent em um crew member mantém as rotas da própria conversa para todas as gravações. Cada rota verifica o turno antes que o texto chegue ao durable agent. Todas as gravações para uma mesma conversa compartilham um único bloqueio. Enquanto um envio é executado, Steer e uma resposta via card são recusados por ocupação. Stop aguarda a liberação do bloqueio, no máximo até seu limite de tempo, garantindo que um envio travado nunca impeça o Stop.

Versões

O Collie e um durable agent combinam uma versão de comunicação no hello e, atualmente, existe apenas uma: versão 1.

O Collie opera com 1..1. Quando uma versão 2 for lançada, o Collie aceitará a versão 1 por mais uma versão secundária posterior e, na versão secundária seguinte, deixará de aceitá-la. Hoje não existe versão anterior para aceitar.

Quando os dois intervalos não coincidem, o Collie não lê mais nada do durable agent. Seu log recebe uma linha para cada intervalo recusado, como [durable] The durable agent speaks wire v2, this Collie speaks v1. Update Collie, or the agent's SDK. A tela inicial do durable agent no celular exibe a mesma frase em um aviso de atenção, e sua linha no dashboard mostra Version mismatch em vez de Unreachable. collie doctor mostra ambos os intervalos em sua linha durable-hello: incompatible: the durable agent speaks 2..3, this Collie speaks 1..1. Uma vez a cada inicialização do durable agent, o Collie também envia um hello com sua própria versão, para que o durable agent possa registrar a incompatibilidade do lado dele. Atualize o lado desatualizado.

A saída

O recurso permanecerá apenas se alguém fora deste repositório o utilizar.

Até o lançamento da versão 1.24.0, uma de duas condições deve ser atendida: existir um repositório público compatível com o protocolo ou existir uma issue ou discussão externa sobre um durable agent. Se nenhuma acontecer, o código do durable será movido da release para experiments/, e esta página será removida (ADR 0104). Na remoção, uma entrada sources.json será ignorada com uma linha de log durante uma release, o socket continuará funcionando para o seu durable agent e o pacote npm será descontinuado, não excluído (ADR 0105).