Agenti durevoli (sperimentale)

Sperimentale. Il protocollo wire, l'SDK e questa pagina potrebbero cambiare, o la funzionalità potrebbe essere rimossa, in una versione minore successiva. Attualmente solo gli esempi interni di Collie utilizzano il protocollo wire. L'uscita descrive i criteri che determinano il suo mantenimento. Se non si collega alcun agente permanente, l'aspetto e il funzionamento di Collie restano invariati.

Se è stato creato un agente permanente con Pi Durable o con un programma che implementa il protocollo wire, Collie può visualizzarlo sullo smartphone. Riceve richieste di approvazione, cronologia e una vista chat senza alcun codice UI.

Un agente durevole è una delle origini possibili di un sessione, e ciascuna delle sue conversazioni costituisce una sessione. Le parole si trovano in Terminologia. Collie non memorizza alcuna chiave del modello: un agente durevole usa una propria chiave API o un accesso ChatGPT, e un abbonamento Anthropic non può essere utilizzato tramite un harness di terze parti.

Guida rapida

Un agente durevole di dieci righe, un collie durable attach e una scheda con una domanda sul telefono.

È necessario che Collie 1.22.0 o successivo sia in esecuzione su questa macchina, con il telefono associato (Installazione).

Un agente durevole viene eseguito su Linux o macOS, con Node 22.19 o successivo oppure Bun 1.4 o successivo. Installare l'SDK nella cartella dell'agente durevole:

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

Il pacchetto è pubblicato con il dist-tag npm experimental, mai latest, e segue il criterio di dismissione in ADR 0104: se il wire durevole viene ritirato, il pacchetto viene deprecato (ADR 0105).

L'entry Pi Durable dell'SDK è testata con Pi Durable 1.1.0 e 1.2.0. Node 22.19 rappresenta il requisito minimo di Pi Durable 1.2.0.

Salvare questo agente durevole come hello.mjs. È composto da dieci righe:

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();

Eseguirlo con node hello.mjs o bun hello.mjs. Stampa listening /run/user/1000/hello/app.sock e rimane in attesa. Lo stesso agente durevole corrisponde a examples/durable-member/hello.ts in un clone di Collie.

Su Node stampa prima un'altra riga: Node non può verificare chi si connette al socket dell'agente durevole, pertanto qualsiasi processo del proprio utente può rispondere alla domanda. Bun su Linux è in grado di farlo, e rifiuta una risposta proveniente dall'agente durevole stesso o da un processo da esso avviato.

Su macOS, eseguirlo con Node. Lì Bun richiede callerCheck: "off", che questo agente durevole non imposta. macOS non dispone di XDG_RUNTIME_DIR, pertanto impostare prima COLLIE_DURABLE_SOCKET su un percorso assoluto.

In un secondo terminale, collegarlo alla propria istanza di Collie, quindi riavviare in modo che Collie legga la nuova voce:

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

Usare il percorso stampato dall'agente durevole. Aggiungere --restart al primo comando per riavviare nello stesso passaggio. --restart riavvia il bridge di Collie: il telefono si riconnette in pochi secondi e le sessioni del terminale rimangono attive.

Aprire Collie sul telefono. La sezione Durable agents mostra una riga, hello, con un badge Experimental e una domanda in attesa. Toccare la riga: si apre l'elenco delle conversazioni dell'agente durevole, in cui la conversazione Deploy attende con "Deploy to staging?". Aprirla e toccare Yes o No. L'agente durevole stampa la risposta ed esce.

Per scrivere un proprio agente durevole, consultare L'SDK durevole e Il wire durevole.

Collegare un agente durevole

Ciascun agente durevole corrisponde a una voce in sources.json, e collie durable attach la scrive.

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

Su Windows è disponibile solo la modalità HTTPS: attach --socket rifiuta l'operazione con codice di uscita 2 e indica di usare --url e --token-env, poiché un socket privato richiede gli ID utente Unix.

sources.json si trova nella cartella di configurazione accanto a .env: la cartella di configurazione del plugin Herdr (~/.config/herdr/plugins/config/herdr.collie/) in un'installazione gestita da Herdr, altrimenti ~/.config/collie/. attach stampa il percorso scritto. I due comandi precedenti scrivono questo file:

[
  { "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"
  }
]

Il bridge legge il file all'avvio, quindi una voce diventa effettiva dopo un riavvio. I terminali appaiono e funzionano come prima, a fianco dei durable agent.

Collie gestisce il file in modo rigoroso, poiché un durable agent ignorato in silenzio non apparirebbe mai:

• —
  Un campo non indicato nella tabella arresta il bridge. Lo stesso vale per un kind errato, un nome che viola le regole, un nome usato due volte, sia socket che url, nessuno dei due, oppure un url senza token.
• —
  Un file non valido arresta il bridge all'avvio con una singola riga. La riga inizia con [bridge] FATAL: e indica la voce e il campo. collie logs lo mostra. Anche attach e detach rifiutano di sovrascrivere un file illeggibile, evitando che un refuso comprometta le altre voci.
• —
  Il file è mantenuto con modalità 0600. attach lo scrive in questo modo. Se i permessi del file sono più estesi, il bridge li restringe all'avvio segnalandolo nel log.
• —
  Un nome non può coincidere con quello della sessione di terminale. Corrisponde a default sulla maggior parte delle installazioni, e su un'istanza solo durable default è il nome del proprio durable agent. Il bridge si arresta all'avvio e indica la voce.
• —
  Un durable agent mantiene il proprio nome rispetto a una sessione Herdr. Quando una sessione Herdr ha il nome di un durable agent, il telefono mostra il durable agent, nasconde la sessione Herdr e il log lo segnala una volta.

attach verifica il percorso del socket, l'URL e il token secondo le regole seguenti. Una voce scritta a mano viene verificata quando il bridge contatta il durable agent: una regola violata mostrerà quindi il durable agent come non raggiungibile indicandone il motivo.

Due modi per raggiungere un durable agent

Il trasporto via socket è per Linux e macOS. Su Windows usare l'URL e il token. Il percorso del socket deve essere assoluto e di massimo 103 byte. Mantenerlo sotto $XDG_RUNTIME_DIR, non sotto /tmp: il servizio Collie su Linux viene eseguito con una /tmp privata.

Collie si connette a un socket solo quando l'intero percorso è privato, poiché il socket non trasmette alcun token. Il socket appartiene all'utente senza permessi di gruppo o per altri. La sua cartella appartiene all'utente con modalità 0700. Nessuna parte del percorso è un symlink e nessuna cartella superiore è scrivibile da gruppo o altri, a eccezione di una con sticky bit come /tmp. L'SDK crea la cartella del socket con modalità 0700 se non presente.

L'URL deve iniziare con https://. L'unica eccezione è http://127.0.0.1:<port> o http://localhost:<port>, con una porta, per un durable agent sulla stessa macchina. Collie rifiuta qualsiasi altro indirizzo http://, poiché il token attraverserebbe la rete senza crittografia.

Attenzione. Su https il token è l'unico controllo di accesso. Chiunque lo possieda può leggere ogni conversazione e rispondere a ogni domanda, e l'host vede il testo. Un durable agent raggiunto in questo modo dovrebbe offrire solo Allow e Deny, mai un'autorizzazione permanente.

Sicurezza dei durable agent definisce le operazioni permesse a un durable agent e ciò che Collie registra nei log.

Ogni polling su https è una richiesta che l'host potrebbe fatturare, e anche una risposta "nothing changed" viene conteggiata. Senza telefoni aperti il polling inattivo viene eseguito ogni 10 s, quindi Collie effettua 8.640 richieste al giorno. Verificare le condizioni del piano dell'host a questo riguardo.

Un durable agent dietro un URL deve gestire il protocollo di Collie e verificare il bearer token. Una demo stock di Pi Durable non fa nessuna delle due cose, quindi Collie non può collegarvisi così com'è.

Collie esegue il polling di un durable agent ospitato su host remoto. Esegue una richiesta ogni 2 s se un telefono è attivo, altrimenti ogni 10 s. Ogni polling riattiva un Durable Object in ibernazione, quindi un oggetto remoto rimane attivo finché Collie lo osserva. Il protocollo non usa WebSocket, pertanto le funzionalità di ibernazione e WebSocket dei Durable Objects non sono utili in questo contesto.

L'esempio Cloudflare è archiviato e non fa parte di una release. Si trova in experiments/durable-member-cloudflare/.

I tre verbi

attach, detach e list modificano o leggono sources.json, e non riavviano nulla se non richiesto.

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 senza verbi, o con un verbo sconosciuto, stampa le istruzioni d'uso ed esce con 2. Con --restart, attach e detach eseguono lo stesso riavvio di collie restart.

list interroga il bridge in esecuzione su ciascuna voce e attende al massimo 3 s per ciascuna:

Quando un durable agent non compare, eseguire collie doctor, che indica il controllo non riuscito. Le tre cause più comuni sono una voce non ancora caricata (riavviare), un socket non privato (socket-not-private) e un file socket obsoleto lasciato da un arresto anomalo (connection refused: eliminarlo e avviare il durable agent). Risoluzione dei problemi dei durable agent copre i casi relativi al durable agent. Risoluzione dei problemi copre Collie nel suo complesso.

Token

Una voce url contiene il proprio token, e il token costituisce l'intero controllo degli accessi.

openssl rand -hex 32

Il risultato è di 64 caratteri esadecimali, oltre la soglia minima di 32 byte.

Impostare per il token 32 o più byte casuali, come indicato sopra, e assegnare al durable agent lo stesso valore. attach lo legge dalla variabile specificata da --token-env, evitando così che compaia nella riga di comando o nella cronologia della shell. Questa variabile deve essere impostata quando si esegue attach.

attach copia il valore in sources.json in testo normale. Il file è quindi segreto quanto il token: Collie lo mantiene con permessi 0600, e un backup o una sincronizzazione della cartella di configurazione trasferisce il token. Collie invia il token con ogni richiesta e non lo stampa mai: list indica (token set).

Il token non ha scadenza. Per modificarlo, eseguire nuovamente attach con lo stesso nome e il nuovo token, quindi riavviare:

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 stampa updated edge. Assegnare il nuovo token al durable agent prima di riavviare Collie, altrimenti il telefono segnalerà che il durable agent ha rifiutato il token. Un durable agent può accettare un secondo token durante una rotazione, evitando il blocco di entrambi i lati. L'esempio parcheggiato di Cloudflare accetta COLLIE_TOKEN e, finché è impostato, COLLIE_TOKEN_NEXT (ADR 0103). Impostare il nuovo token come COLLIE_TOKEN_NEXT sul durable agent, eseguire nuovamente attach e riavviare Collie, quindi spostare il valore in COLLIE_TOKEN e rimuovere COLLIE_TOKEN_NEXT.

Un durable agent singolo in un'unica istanza di Collie

Un'istanza priva di terminale, come un host Windows o un durable agent ospitato, può gestire un durable agent dal proprio .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

Un'istanza di questo tipo assegna al proprio durable agent il nome default, e tale durable agent funge da sessione primaria. Le voci in sources.json continuano a essere eseguite al suo fianco, sotto altri nomi.

Impostare il socket, oppure l'URL con il relativo token, mai entrambi. La presenza di entrambi, di un URL senza token o di un token senza URL costituisce un errore di configurazione: Collie si avvia, riporta l'errore nel registro e mostra il durable agent come non raggiungibile indicando tale motivo.

Una build precedente conservava i log di un'istanza durable-only direttamente in <state>/durable/. Al primo avvio di questa build vengono spostati una sola volta in durable/default/, con una riga nel log.

Per modificare il token, distribuire quello nuovo al durable agent, impostarlo in .env ed eseguire collie restart. Un'istanza durable-only si unisce a un crew con il proprio nome host, pertanto è necessario assegnarle un nome con collie crew join <lead-address> --label durable quando condivide l'host con il lead.

Per disattivare temporaneamente ogni durable agent da sources.json, impostare COLLIE_PROGRAMS=off in .env ed eseguire collie restart. Il bridge ignora quindi il file, scrive una riga di log e opera come un'installazione senza durable agent, evitando che il telefono mostri la sezione Durable agents. collie doctor e collie durable list segnalano che i durable agent sono disattivati. Il file rimane invariato: rimuovere la variabile e riavviare per ripristinare i durable agent. La variabile non influisce sul vecchio formato di variabili di ambiente sopra descritto.

Dove Collie conserva i dati di un durable agent

Il durable agent conserva lo storico delle proprie conversazioni. Collie mantiene una cache, le relative ricevute e la memoria di push nella propria cartella di stato.

La cartella di stato è ~/.local/state/collie/, oppure COLLIE_STATE_DIR se impostata. <program> è il nome in sources.json, oppure default. La cartella di ciascun durable agent ha permessi 0700, e ciascun log ha permessi 0600.

La cache permette a Chat di aprirsi rapidamente e di funzionare anche quando il durable agent è lento. Una conversazione chiusa viene sempre letta dal durable agent, mai dalla cache.

Un durable agent conserva solo la parte più recente di una conversazione lunga. Se la parte iniziale di una conversazione è stata scartata prima che Collie la leggesse, Chat mostra una singola riga al suo posto: "Older messages were left out: the durable agent no longer keeps them." Nessun dato sul telefono è andato perduto: Collie non ha mai ricevuto quei messaggi.

Cosa mostra il telefono

Una sezione Durable agents nella dashboard e, per ciascun durable agent, l'elenco delle relative conversazioni.

Ciascun durable agent occupa una riga nella sezione Durable agents, con il proprio nome, un badge Experimental, il relativo runtime e l'indicazione se sia in esecuzione localmente o altrove. A destra mostra il conteggio delle conversazioni aperte e, con il colore per gli elementi in attesa di intervento, quelle in attesa dell'utente. La sezione si sposta sopra gli spazi personali quando una domanda è in attesa. Un durable agent in fase di avvio o non raggiungibile segnala tale stato al posto dei conteggi. Un token rifiutato o una versione wire non accettata mostrano un messaggio dedicato sul telefono; collie doctor riporta qualsiasi altro motivo.

Toccare una riga per aprire l'elenco delle conversazioni del durable agent, in modo analogo all'elenco delle chat di un'applicazione di messaggistica. Gli elementi in attesa dell'utente compaiono per primi, seguiti dalle altre conversazioni aperte e infine da quelle chiuse sotto l'etichetta Closed. Una conversazione aperta si avvia in Chat, mentre una chiusa si apre in sola lettura. Un durable agent comunica nel proprio messaggio di saluto le operazioni supportate (asks, starters, send, steer, abort, rename, close, actions, history, reopen), e il telefono mostra un comando solo per quelle dichiarate. Un durable agent non dispone di schermo, pertanto non include una vista Terminal né la digitazione di tasti.

All'invio verso un durable agent, l'etichetta queued rappresenta l'interpretazione del turno da parte di Collie. Collie non mostra gli elementi in attesa nella casella di posta di Pi. Un'attività sospesa in attesa di una scadenza appare come inattiva o in esecuzione, mai come in attesa. Maggiori dettagli in Sessioni.

Una scheda della domanda indica il nome del durable agent e mostra il tempo rimanente quando il durable agent ne ha impostato uno. Una domanda decisa nel durable agent, o scaduta, lascia una riga nella chat. Agenti durevoli sul telefono mostra ciascuno di questi casi con una figura.

Send e Ask tramite il bridge

Un durable agent non ha alcuno schermo, quindi Collie non legge alcuno schermo per esso. Il bridge legge invece il proprio stato. Un durable agent riceve gli stessi Send e Ask di un riquadro di terminale.

• —
  Lo stato. Il turno proviene dallo stato del suo riquadro. Una domanda proviene dalla sua richiesta aperta più vecchia. La casella di input è sempre vuota, poiché un durable agent non dispone di alcuna casella. Il telefono riceve questo stato a ogni riquadro, nella stessa forma usata per un riquadro di terminale.
• —
  Un invio. POST /api/send riceve un ID richiesta dal telefono. Il bridge scrive la richiesta su disco e blocca la conversazione. Invia quindi il testo al durable agent una sola volta, per il turno letto. La sua risposta costituisce la prova, e la ricevuta riporta l'ID richiesta preso in carico. Durante un turno il durable agent conserva il testo per il periodo successivo a tale turno, e la ricevuta indica queued.
• —
  I risultati. Un invio termina con sent, refused con un motivo, o unknown. unknown indica che il durable agent non ha confermato la ricezione del testo. Rileggere la chat prima di inviarlo nuovamente. Un invio diventa effective quando il durable agent lo scrive nella conversazione. Il suo elemento user indica l'ID richiesta di tale invio. Un invio normale viene rifiutato se è presente una qualsiasi domanda aperta, anche una che Collie non può leggere. Rispondere alla domanda, oppure usare Steer o Stop. Un turno avviato dopo la consultazione rifiuta l'invio, e nulla raggiunge il durable agent.
• —
  Una domanda. POST /api/ask/<id> vi risponde. L'ID richiesta può essere usato una sola volta. La risposta contiene l'hash della domanda visualizzata. Il bridge lo confronta con la domanda attualmente elencata dal durable agent. Qualora i due differiscano, nulla raggiunge il durable agent. La risposta mostra la domanda nello stato corrente. La risposta viene inoltrata al durable agent tramite il proprio ID richiesta. Non viene mai inviata alcuna chiave. La ricevuta indica channel: program e conserva l'hash.
• —
  Cosa rimane sulla scheda. Alcune domande non sono gestibili con un solo tocco, pertanto lo stato le mostra come domande illeggibili per Collie (modal: unreadable). Si risponde a esse sulla relativa scheda. - Una domanda testuale resta sulla scheda specifica del durable agent, poiché la risposta è una riga digitata. - Una scelta multipla resta sulla scheda specifica del durable agent, poiché la risposta prevede più opzioni. - Un modulo resta sulla scheda specifica del durable agent, poiché la risposta è un insieme di campi. - L'opzione Consenti sempre non è mai inclusa nel contratto. La relativa autorizzazione dura oltre la domanda corrente. Pertanto la scheda del durable agent richiede prima un secondo tocco, e un tocco singolo tramite /api/ask non deve saltare tale passaggio.
• —
  I contatori. collie doctor conta queste letture e questi risultati in un'unica riga, program.

Su questa macchina il telefono usa queste route. Un invio normale passa attraverso /api/send, mentre un tocco sulla scheda della domanda passa attraverso /api/ask. Il composer comunica l'esito sotto il pollice con le parole del durable agent. Quando una domanda blocca l'invio, un pulsante rimanda alla relativa scheda. L'elenco Recent sends del riquadro mostra ogni ricevuta, segnalando gli invii in coda. Steer e Stop rimangono sulle route proprie della conversazione, poiché uno steer non fa parte del Send Protocol. Un durable agent su un membro della crew mantiene le route proprie della conversazione per tutte le scritture. Ciascuna route verifica il turno prima che il testo raggiunga il durable agent. Tutte le scritture su una conversazione condividono un unico blocco. Durante l'esecuzione di un invio, Steer e una risposta dalla scheda vengono rifiutati con stato occupato. Stop attende il blocco, al massimo fino al proprio limite di tempo, affinché un invio bloccato non impedisca mai l'esecuzione di Stop.

Versioni

Collie e un durable agent concordano una versione di protocollo nell'hello; a oggi ne esiste una: versione 1.

Collie parla 1..1. Al rilascio di una versione 2, Collie accetterà la versione 1 per una minor release successiva, per poi rimuoverla nella minor ancora seguente. A oggi non vi è alcuna versione precedente da accettare.

Quando i due intervalli non coincidono, Collie non legge più nulla dal durable agent. Il log riceve una riga per ogni intervallo rifiutato, come [durable] The durable agent speaks wire v2, this Collie speaks v1. Update Collie, or the agent's SDK. La home del durable agent sul telefono mostra la stessa frase in un riquadro di avviso, e la relativa riga sulla dashboard indica Version mismatch al posto di Unreachable. collie doctor mostra entrambi gli intervalli sulla riga durable-hello: incompatible: the durable agent speaks 2..3, this Collie speaks 1..1. Una volta per ogni avvio del durable agent, Collie gli invia inoltre un hello con la propria versione, affinché il durable agent possa registrare la mancata corrispondenza sul proprio lato. Aggiornare il componente meno recente.

L'uscita

La funzionalità rimane solo se usata da qualcuno esterno a questo repository.

Entro la versione 1.24.0, deve verificarsi una di due condizioni: l'esistenza di un repository pubblico che supporti il protocollo, oppure l'esistenza di una issue o discussione esterna relativa a un durable agent. In caso contrario, il codice durable verrà escluso dalla release e spostato in experiments/, e questa pagina verrà rimossa (ADR 0104). Al momento della rimozione, una voce sources.json verrà ignorata con una riga di log per una sola release, il socket continuerà a funzionare per il durable agent e il pacchetto npm verrà deprecato, non eliminato (ADR 0105).