Agents durables (expérimental)

Expérimental. Le protocole réseau, le SDK et cette page peuvent changer, ou la fonctionnalité peut être retirée, dans une version mineure ultérieure. Aujourd'hui, seuls les exemples propres à Collie utilisent ce protocole. La sortie précise les critères qui décideront de son maintien. Si vous ne rattachez aucun agent persistant, Collie conserve son apparence et son fonctionnement habituels.

Si vous avez développé un agent persistant avec Pi Durable ou tout programme prenant en charge le protocole, Collie peut l'afficher sur votre téléphone. Il bénéficie de demandes d'approbation, d'un historique et d'une vue de discussion sans aucun code d'interface utilisateur.

Un agent durable est l'une des origines possibles d'un session, et chacune de ses conversations constitue une session. Les termes sont définis dans Terminologie. Collie ne conserve aucune clé de modèle : un agent durable utilise sa propre clé d'API ou une connexion ChatGPT, et un abonnement Anthropic ne peut pas être utilisé via un harness tiers.

Démarrage rapide

Un agent durable de dix lignes, un collie durable attach, et une carte de question sur votre téléphone.

Vous avez besoin de Collie 1.22.0 ou supérieur en cours d'exécution sur cette machine, avec votre téléphone appairé (Installer).

Un agent durable fonctionne sous Linux ou macOS, avec Node 22.19 ou supérieur ou Bun 1.4 ou supérieur. Installez le SDK dans le dossier de votre agent durable :

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

Le paquet est publié sous le dist-tag npm experimental, jamais latest, et il suit la sortie décrite dans ADR 0104 : si le câble durable disparaît, le paquet est déprécié (ADR 0105).

L'entrée Pi Durable du SDK est testée avec Pi Durable 1.1.0 et 1.2.0. Node 22.19 est la version minimale requise pour Pi Durable 1.2.0.

Enregistrez cet agent durable sous hello.mjs. Il fait dix lignes :

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

Exécutez-le avec node hello.mjs ou bun hello.mjs. Il affiche listening /run/user/1000/hello/app.sock et attend. Le même agent durable se trouve dans examples/durable-member/hello.ts au sein d'un clone de Collie.

Sous Node, il commence par écrire une ligne de plus : Node ne peut pas savoir qui se connecte au socket de l'agent durable, donc n'importe quel processus de votre utilisateur peut répondre à sa question. Bun sous Linux en est capable, et refuse toute réponse venant de l'agent durable lui-même ou d'un processus qu'il a lancé.

Sous macOS, exécutez-le avec Node. Bun y requiert callerCheck: "off", ce que cet agent durable ne définit pas. macOS ne dispose pas de XDG_RUNTIME_DIR, définissez donc d'abord COLLIE_DURABLE_SOCKET avec un chemin absolu.

Dans un second terminal, attachez-le à votre Collie, puis redémarrez pour que Collie charge la nouvelle entrée :

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

Utilisez le chemin affiché par votre agent durable. Ajoutez --restart à la première commande pour redémarrer au cours de la même étape. --restart redémarre le pont Collie : votre téléphone se reconnecte en quelques secondes et vos sessions de terminal continuent de tourner.

Ouvrez Collie sur votre téléphone. Une section Durable agents affiche une ligne, hello, avec un badge Experimental et une question en attente. Appuyez sur la ligne : elle s'ouvre sur la liste des conversations de l'agent durable, où la conversation Deploy attend avec "Deploy to staging?". Ouvrez-la et appuyez sur Yes ou No. L'agent durable affiche votre réponse et se termine.

Pour écrire votre propre agent durable, lisez Le SDK durable et Le câble durable.

Attacher un agent durable

Chaque agent durable est une entrée dans sources.json, et collie durable attach l'écrit.

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

Sous Windows, seule la forme HTTPS est disponible : attach --socket échoue avec le code de sortie 2 et indique d'utiliser --url et --token-env, car un socket privé nécessite des identifiants utilisateur Unix.

sources.json se trouve dans le dossier de configuration aux côtés de votre .env : le dossier de configuration du plugin Herdr (~/.config/herdr/plugins/config/herdr.collie/) sur une installation gérée par Herdr, sinon ~/.config/collie/. attach affiche le chemin qu'il a écrit. Les deux commandes ci-dessus écrivent ce fichier :

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

Le pont lit le fichier au démarrage, donc une entrée prend effet après un redémarrage. Vos terminaux ont la même apparence et fonctionnent comme avant, aux côtés des agents durables.

Collie est strict au sujet du fichier, car un agent durable qu'il ignorerait en silence n'apparaîtrait jamais :

• —
  Un champ que la table ne mentionne pas arrête le pont. Tout comme un kind incorrect, un nom qui enfreint la règle, un nom utilisé deux fois, à la fois socket et url, aucun des deux, ou un url sans token.
• —
  Un fichier incorrect arrête le pont au démarrage avec une seule ligne. La ligne commence par [bridge] FATAL: et indique l'entrée et le champ. collie logs l'affiche. attach et detach refusent aussi d'écraser un fichier qu'ils ne peuvent pas lire, afin qu'une faute de frappe ne compromette jamais vos autres entrées.
• —
  Le fichier est conservé avec le mode 0600. attach l'écrit de cette manière. Quand le fichier a des permissions plus larges, le pont les restreint au démarrage et l'indique dans son journal.
• —
  Un nom ne peut pas être celui de votre session de terminal. C'est default sur la plupart des installations, et sur une instance réservée aux agents durables, default est le nom de son propre agent durable. Le pont s'arrête au démarrage et nomme l'entrée.
• —
  Un agent durable conserve son nom face à une session Herdr. Quand une session Herdr porte le nom d'un agent durable, le téléphone affiche l'agent durable, masque cette session Herdr, et le journal le signale une fois.

attach vérifie le chemin du socket, l'URL et le jeton selon les règles ci-dessous. Une entrée rédigée à la main est vérifiée lorsque le pont tente de joindre l'agent durable : une règle enfreinte affiche alors l'agent durable comme injoignable en indiquant la raison.

Deux façons de joindre un agent durable

Le transport par socket est prévu pour Linux et macOS. Sur Windows, utilisez l'URL et le jeton. Le chemin du socket doit être absolu et comporter au maximum 103 octets. Gardez-le sous $XDG_RUNTIME_DIR, pas /tmp : le service Collie sous Linux s'exécute avec un /tmp privé.

Collie se connecte à un socket uniquement lorsque l'ensemble du chemin est privé, car le socket ne transporte aucun jeton. Le socket vous appartient, sans aucune permission pour le groupe ou les autres. Son dossier vous appartient avec le mode 0700. Aucune partie du chemin n'est un lien symbolique, et aucun dossier parent n'est modifiable par le groupe ou les autres, sauf s'il possède le bit sticky comme /tmp. Le SDK crée le dossier du socket avec le mode 0700 s'il n'existe pas.

L'URL doit commencer par https://. La seule exception est http://127.0.0.1:<port> ou http://localhost:<port>, avec un port, pour un agent durable sur la même machine. Collie refuse toute autre adresse http://, car le jeton transiterait sur le réseau sans chiffrement.

Attention. En https, le jeton est le seul contrôle d'accès. Quiconque le possède peut lire chaque conversation et répondre à chaque question, et l'hôte voit le texte. Un agent durable joint de cette façon ne doit proposer que Allow et Deny, jamais d'autorisation permanente.

Sécurité des agents durables définit ce qu'un agent durable peut faire et ce que Collie journalise.

Chaque interrogation en https est une requête que votre hébergeur peut facturer, et une réponse « rien n'a changé » compte aussi. Sans aucun téléphone ouvert, l'interrogation au repos a lieu toutes les 10 s, Collie fait donc 8 640 requêtes par jour. Vérifiez ce que le forfait de votre hébergeur autorise à cet égard.

Un agent durable derrière une URL doit servir le protocole Collie et vérifier le jeton bearer. Une démo standard de Pi Durable ne fait ni l'un ni l'autre, Collie ne peut donc pas s'y connecter en l'état.

Collie interroge régulièrement un agent durable hébergé. Il envoie une requête toutes les 2 s lorsqu'un téléphone l'observe, sinon toutes les 10 s. Chaque interrogation réveille un Durable Object en veille prolongée, un objet hébergé reste donc actif tant que Collie l'observe. Le protocole n'utilise pas de WebSocket, donc les fonctionnalités d'hibernation et de WebSocket des Durable Objects ne sont d'aucune utilité ici.

L'exemple Cloudflare est mis de côté et ne fait pas partie d'une version publiée. Il se trouve dans experiments/durable-member-cloudflare/.

Les trois verbes

attach, detach et list modifient ou lisent sources.json, et ne redémarrent rien sauf demande expresse.

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 sans verbe, ou avec un verbe inconnu, affiche l'utilisation et quitte avec 2. Avec --restart, attach et detach lancent le même redémarrage que collie restart.

list interroge le bridge en cours d'exécution pour chaque entrée et attend au maximum 3 s pour chacune :

Quand un durable agent n'apparaît pas, exécutez collie doctor, qui indique la vérification en échec. Les trois causes habituelles sont une entrée pas encore chargée (redémarrage), un socket qui n'est pas privé (socket-not-private), et un fichier de socket orphelin laissé par un crash (connection refused : supprimez-le et démarrez le durable agent). Dépannage des durable agents couvre les cas du durable agent. Dépannage couvre Collie dans son ensemble.

Jetons

Une entrée url contient son token, et le token constitue l'unique barrière d'accès.

openssl rand -hex 32

Le résultat compte 64 caractères hexadécimaux, au-dessus du minimum de 32 octets.

Définissez le token sur 32 octets aléatoires ou plus, comme ci-dessus, et donnez la même valeur au durable agent. attach le lit depuis la variable désignée par --token-env, afin qu'il ne figure dans aucune ligne de commande ni aucun historique shell. Cette variable doit être définie lorsque vous exécutez attach.

attach copie la valeur dans sources.json en clair. Le fichier est donc aussi secret que le token : Collie le conserve avec le mode 0600, et une sauvegarde ou une synchronisation du dossier de configuration emporte le token. Collie envoie le token avec chaque requête, et ne l'affiche jamais : list indique (token set).

Le token n'expire pas. Pour le modifier, réexécutez attach avec le même nom et le nouveau token, puis redémarrez :

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 affiche updated edge. Donnez le nouveau token au durable agent avant de redémarrer Collie, sinon le téléphone indique que le durable agent a refusé le token. Un durable agent peut accepter un second token pendant une rotation, afin qu'aucun côté ne soit bloqué. L'exemple Cloudflare parqué accepte COLLIE_TOKEN et, tant qu'il est défini, COLLIE_TOKEN_NEXT (ADR 0103). Définissez le nouveau token comme COLLIE_TOKEN_NEXT sur le durable agent, réexécutez attach et redémarrez Collie, puis déplacez la valeur vers COLLIE_TOKEN et supprimez COLLIE_TOKEN_NEXT.

Un durable agent seul dans un Collie

Une instance sans terminal, telle qu'un hôte Windows ou un durable agent hébergé, peut piloter un durable agent depuis son .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

Une telle instance nomme son agent durable default, et cet agent durable constitue sa session principale. Les entrées de sources.json s'exécutent toujours à côté, sous d'autres noms.

Définissez le socket, ou l'URL avec son token, jamais les deux. Définir les deux, une URL sans token ou un token sans URL constitue une erreur de configuration : Collie démarre, consigne l'erreur dans son journal et indique que l'agent durable est inaccessible avec cette raison.

Une version antérieure conservait les journaux d'une instance durable uniquement directement dans <state>/durable/. Au premier démarrage de cette version, ils sont déplacés une fois vers durable/default/, avec une ligne dans le journal.

Pour modifier le token, déployez le nouveau sur l'agent durable, définissez-le dans le .env et exécutez collie restart. Une instance durable uniquement rejoint un crew sous son nom d'hôte ; donnez-lui donc un nom avec collie crew join <lead-address> --label durable lorsqu'elle partage un hôte avec le lead.

Pour désactiver temporairement chaque agent durable de sources.json, définissez COLLIE_PROGRAMS=off dans le .env et exécutez collie restart. Le bridge ignore alors le fichier, consigne une ligne dans le journal et fonctionne comme une installation sans agent durable, de sorte que le téléphone n'affiche aucune section Agents durables. collie doctor et collie durable list indiquent que les agents durables sont désactivés. Le fichier reste inchangé : supprimez la variable et redémarrez pour réactiver les agents durables. La variable ne modifie pas l'ancien format d'environnement ci-dessus.

Emplacement où Collie conserve les données d'un agent durable

L'agent durable conserve l'historique de ses conversations. Collie conserve un cache, ses accusés et sa mémoire de push dans son dossier d'état.

Le dossier d'état est ~/.local/state/collie/, ou COLLIE_STATE_DIR s'il est défini. <program> est le nom dans sources.json, ou default. Le dossier de chaque agent durable est en mode 0700, et chaque journal est en mode 0600.

Le cache explique pourquoi Chat s'ouvre rapidement et fonctionne pendant que l'agent durable est lent. Une conversation fermée est toujours lue depuis l'agent durable, jamais depuis le cache.

Un agent durable ne conserve que la partie la plus récente d'une longue conversation. Lorsqu'il a supprimé le début d'une conversation avant que Collie ne l'ait lue, Chat affiche une ligne à la place : « Les messages plus anciens ont été ignorés : l'agent durable ne les conserve plus. » Rien n'a été perdu sur votre téléphone : Collie n'a jamais reçu ces messages.

Ce qu'affiche le téléphone

Une section Agents durables sur le tableau de bord, et pour chaque agent durable une liste de ses conversations.

Chaque agent durable correspond à une ligne dans la section Agents durables, avec son nom, un badge Expérimental, son runtime et s'il s'exécute ici ou ailleurs. À droite, il compte ses conversations ouvertes et, dans la couleur d'attention requise, celles qui vous attendent. La section se place au-dessus de vos espaces lorsqu'une question est en attente. Un agent durable qui démarre ou qui est inaccessible l'indique à la place des compteurs. Un token refusé et une version de protocole refusée ont leurs propres messages sur le téléphone ; collie doctor indique toute autre raison.

Appuyez sur une ligne pour ouvrir la liste des conversations de l'agent durable, semblable à la liste de discussion d'une application de messagerie. Ce qui vous attend apparaît en premier, puis les autres conversations ouvertes, puis celles fermées sous l'étiquette Fermé. Une conversation ouverte s'ouvre dans Chat, et une fermée s'ouvre en lecture seule. Un agent durable indique dans son hello ce qu'il peut faire (asks, starters, send, steer, abort, rename, close, actions, history, reopen), et le téléphone n'affiche un contrôle que pour ce qui a été annoncé. Un agent durable n'a pas d'écran ; il n'a donc pas de vue Terminal ni de touches saisies.

Lors d'un envoi à un agent durable, l'étiquette queued correspond à l'interprétation du tour par Collie. Collie n'affiche pas ce qui attend dans la boîte de réception de Pi. Une tâche en veille jusqu'à une échéance apparaît comme inactive ou au travail, jamais comme en attente. Sessions fournit plus de détails.

Une carte de question indique le nom du durable agent et affiche le temps restant lorsque le durable agent en a défini un. Une question tranchée dans le durable agent, ou ayant expiré, laisse une ligne dans le chat. Agents durables sur le téléphone illustre chacun de ces cas avec une figure.

Send et Ask via le bridge

Un durable agent n'a pas d'écran, Collie ne lit donc aucun écran pour lui. Le bridge lit son propre état à la place. Un durable agent reçoit les mêmes Send et Ask qu'un volet de terminal.

• —
  L'état. Le tour provient de l'état de son volet. Une question provient de son ask ouvert le plus ancien. Le champ de saisie est toujours vide, car un durable agent ne possède pas de champ. Le téléphone reçoit cet état avec chaque volet, sous la même forme que pour un volet de terminal.
• —
  Un envoi (send). POST /api/send prend un identifiant de requête provenant du téléphone. Le bridge écrit la requête sur le disque et verrouille la conversation. Ensuite, il envoie le texte au durable agent une seule fois, pour le tour qu'il a lu. Sa réponse constitue la preuve, et l'accusé de réception indique l'identifiant de requête qu'il a pris en charge. Pendant un tour, le durable agent conserve le texte pour après ce tour, et l'accusé de réception indique queued.
• —
  Les résultats. Un send se termine par sent, refused avec un motif, ou unknown. unknown signifie que le durable agent n'a pas indiqué avoir pris en charge le texte. Lisez le chat avant de l'envoyer à nouveau. Un send devient effective lorsque le durable agent l'écrit dans la conversation. Son élément user nomme l'identifiant de requête de ce send. Un send standard est refusé tant qu'une question est ouverte, même une question que Collie ne peut pas lire. Répondez à la question, ou utilisez Steer ou Stop. Un tour qui a débuté après votre consultation refuse le send, et rien ne parvient au durable agent.
• —
  Une question. POST /api/ask/<id> y répond. L'ask id est à usage unique. La réponse porte le hash de la question que vous avez vue. Le bridge le compare à la question que le durable agent liste actuellement. Lorsque les deux diffèrent, rien ne parvient au durable agent. La réponse présente la question telle qu'elle est maintenant. La réponse est transmise au durable agent via son propre ask id. Aucune clé n'est jamais envoyée. L'accusé de réception indique channel: program et conserve le hash.
• —
  Ce qui reste sur la carte. Certaines questions ne se prêtent pas à un simple appui, l'état les affiche donc comme une question que Collie ne peut pas lire (modal: unreadable). Vous y répondez sur sa propre carte. - Une question textuelle reste sur la propre carte du durable agent, car la réponse est une ligne à saisir. - Un choix multiple reste sur la propre carte du durable agent, car la réponse comporte plusieurs sélections. - Un formulaire reste sur la propre carte du durable agent, car la réponse est un ensemble de champs. - Always allow n'est jamais une option de contrat. Son autorisation perdure après cette question. La carte du durable agent demande donc d'abord un deuxième appui, et un appui via /api/ask ne doit pas contourner cet appui.
• —
  Les compteurs. collie doctor compte ces lectures et ces résultats sur une seule ligne, program.

Sur cette machine, le téléphone utilise ces routes. Un send standard passe par /api/send, et un appui sur la carte de question passe par /api/ask. La zone de composition affiche le résultat sous le pouce, avec les termes du durable agent. Lorsqu'une question bloque l'envoi, un bouton renvoie vers sa carte. La liste Recent sends du volet affiche chaque accusé de réception, et un send mis en file d'attente le signale. Steer et Stop restent sur les routes propres de la conversation, car un steer ne fait pas partie du protocole Send. Un durable agent affecté à un membre d'équipe conserve les routes propres de la conversation pour toutes les écritures. Chaque route vérifie le tour avant que le texte ne parvienne au durable agent. Toutes les écritures sur une même conversation partagent un verrou unique. Pendant l'exécution d'un send, Steer et une réponse par carte sont refusés pour cause d'occupation. Stop attend le verrou, au maximum jusqu'à son délai limite ; un send bloqué n'empêche donc jamais Stop d'intervenir.

Versions

Collie et un durable agent négocient une version de protocole dans le hello, et il n'en existe aujourd'hui qu'une seule : la version 1.

Collie prend en charge 1..1. Lorsqu'une version 2 sortira, Collie acceptera la version 1 pendant une version mineure supplémentaire, avant de l'abandonner à la mineure suivante. Aujourd'hui, il n'existe aucune version antérieure à accepter.

Lorsque les deux plages ne se recoupent pas, Collie ne lit plus rien provenant du durable agent. Son journal reçoit une ligne pour chaque plage qu'il refuse, telle que [durable] The durable agent speaks wire v2, this Collie speaks v1. Update Collie, or the agent's SDK. L'écran d'accueil du durable agent sur le téléphone affiche la même phrase dans un encadré d'avertissement, et sa ligne sur le tableau de bord indique Version mismatch au lieu de Unreachable. collie doctor affiche les deux plages sur sa ligne durable-hello : incompatible: the durable agent speaks 2..3, this Collie speaks 1..1. Une fois par démarrage du durable agent, Collie lui envoie également un hello avec sa propre version, afin que le durable agent puisse consigner l'incompatibilité de son côté. Mettez à jour le composant le plus ancien.

La sortie

La fonctionnalité n'est maintenue que si quelqu'un en dehors de ce dépôt l'utilise.

D'ici la version 1.24.0, l'une de ces deux conditions doit être remplie : un dépôt public utilisant ce protocole existe, ou une issue ou discussion externe concernant un durable agent existe. Si aucune n'est vérifiée, le code du durable agent est retiré de la publication pour aller dans experiments/, et cette page disparaît (ADR 0104). Lors de la suppression, une entrée sources.json est ignorée avec une ligne de journal pendant une version, le socket continue de fonctionner pour votre durable agent, et le paquet npm est déprécié, pas supprimé (ADR 0105).