Le SDK durable (expérimental)

Expérimental. Le paquet, son API et le protocole réseau utilisé peuvent changer, ou la fonctionnalité peut être supprimée, dans une version mineure ultérieure. Versions explique ce que cela implique pour votre agent durable.

@colliepwa/durable-sdk est le paquet npm qu'un agent durable utilise pour s'afficher sur votre téléphone via Collie. Cette page détaille chacun de ses composants. Agents durables contient le guide de démarrage rapide ainsi que la configuration côté Collie, et Le câble durable explique ce qui circule entre les deux.

Installation et points d'entrée

Une seule installation fournit cinq points d'entrée : l'import racine pour la plupart des agents durables, et quatre autres pour des besoins plus spécifiques.

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

Le paquet requiert Node 22.19 ou supérieur, ou Bun 1.4 ou supérieur, et ne possède aucune dépendance d'exécution. ./pi requiert @earendil-works/pi-durable, @earendil-works/pi-ai et @earendil-works/chord, version 1.1 ou supérieure et inférieure à 2. Le point d'entrée est testé avec Pi Durable 1.1.0 et 1.2.0. Les trois sont des peer dependencies optionnelles : un agent durable qui n'importe jamais ./pi n'en installe aucune.

L'environnement d'exécution détermine si l'agent durable peut identifier qui répond. La vérification de descendance refuse une action provenant de l'agent durable lui-même ou d'un processus qu'il a lancé, avec un code 403 caller-refused. Elle couvre answer, send, stop, action, rename, close, reopen et starter. Les lectures restent ouvertes.

Sans cette vérification, n'importe quel processus de votre utilisateur peut répondre à une carte, y compris un outil exécuté par l'agent. Exécutez les outils de l'agent dans un bac à sable qui ne peut pas atteindre le socket. Le socket nécessite un système gérant les propriétaires de fichiers, donc sur Windows, openCollie s'arrête au démarrage. Un agent durable y sert plutôt ./core derrière TLS avec un jeton (Deux façons de joindre un agent durable).

Ouvrir une connexion

openCollie crée le socket privé, et le handle retourné définit la disposition affichée par le téléphone.

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

const collie = await openCollie({ hostName: "desk" });
const space = collie.workspace("support", { title: "Support" });
const tab = space.tab("main", { title: "Tickets" });
const pane = tab.pane("ticket-1", { title: "Maria Lopez", harness: "desk" });
collie.ready();

Sans l'option socket, le chemin provient de COLLIE_DURABLE_SOCKET, la variable que Collie lit également.

Deux options supplémentaires existent uniquement sur createCore, pas sur openCollie : receipts et allowAlways (Questions).

close() laisse volontairement ouvertes les asks ouvertes : un arrêt n'est pas une réponse, et l'agent durable décide du sort du travail en attente.

tab.pane(id, { title, harness, cwd?, sessionId? }) renvoie le volet possédant cet ID s'il existe, afin qu'un agent durable puisse afficher deux fois une conversation sans second volet. Les titres sont coupés à 256 octets et harness à 64. cwd est un chemin absolu, sinon il est omis.

Chaque ID suit la règle des ID : 1 à 128 octets, aucun caractère de contrôle, aucun espace, et aucun parmi /, ? ou #. Un ID invalide donne un TypeError. Un ID de workspace ou d'onglet ne peut pas contenir :, car le protocole nomme un onglet <workspace>:<tab>.

Volets

Un volet représente une conversation, et ses méthodes définissent ce que le téléphone affiche pour celle-ci.

Un panneau possède également quatre champs en lecture seule : id, sessionId, turnId (le tour en cours, ou le dernier) et openAsks. Le champ icon d'une action est l'un des suivants : play, pause, check, x, refresh, archive, flag, star, send, note, search et more. Tout autre nom n'affiche aucune icône.

Un événement item transporte un élément avec un id et un ts facultatif. Un élément avec un identifiant connu remplace le précédent sur place.

Un élément reply, thinking, notice ou markdown peut porter partial: true pendant que son texte s'étoffe. Réécrivez le même identifiant au fur et à mesure qu'il grandit, au maximum toutes les 250 ms, puis une dernière fois avec le texte final et sans partial, avant que le panneau ne quitte working.

Le texte dépassant sa limite est tronqué, et les caractères de contrôle et invisibles sont supprimés. Un mauvais lang, un mauvais href, un mauvais badge ou une mauvaise progression devient un TypeError ou un RangeError à la place, car Collie l'abandonnerait. Un agent durable ne peut pas ajouter lui-même d'événements ask, ask-closed ou state : ask() et state() les écrivent.

Questions

pane.ask affiche une carte et se résout avec la réponse, et requireApproval pose une question sur un appel d'outil en une ligne.

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

const args = { order: "5521", amount: 40 };
const approval = await requireApproval("refund", args, {
  pane,
  toolCallId: "call-1",
  timeoutMs: 10 * 60_000,
});
if (!approval.approved) throw new Error(`refund not approved: ${approval.decidedBy}`);

requireApproval(toolName, args, options) construit la carte à partir de la nature de l'appel, jamais à partir des propos du modèle à son sujet. Le titre est "refund wants to run", la ligne d'outil est refund(order: "5521", amount: 40), la notification push indique "refund needs a yes", et les boutons sont Allow et Deny. Il renvoie { approved, decidedBy, decidedAt, askId }. Un refus, un délai d'attente dépassé, un arrêt et une interruption renvoient tous approved: false.

callSummary(name, args) et argumentsView(args) sont les deux éléments utilisés : l'appel sur une seule ligne, et les arguments sous forme de paires key: value avec chaque valeur en JSON.

pane.ask(input) accepte l'un des quatre types. La promesse est résolue avec la réponse sous la forme de ce type.

Chaque type accepte toolCallId, itemId et title (256 octets). Il peut accepter reason (2 Kio), tool, push: { title?, line? } (60 et 120 caractères, le texte de la notification) et expiresAt (un Date ou une chaîne ISO 8601 avec fuseau horaire).

Omettez id. Le SDK le dérive avec askIdFor(paneId, toolCallId) : SHA-256 sur les deux identifiants, les 32 premiers caractères hexadécimaux. Le même appel d'outil déclenché à nouveau après un redémarrage reçoit ainsi le même identifiant, et une réponse envoyée par le téléphone pendant le redémarrage aboutit. Déclencher un identifiant déjà ouvert constitue un TypeError.

decidedBy vaut phone, program ou timeout. Une demande dépasse son expiresAt et se ferme avec une décision prise par timeout : ask() est rejeté avec AskClosed, dont decidedBy est timeout. La carte affiche le temps restant jusque-là. Une question ayant expiré ou ayant été tranchée dans l'agent durable laisse une seule ligne dans Chat, par exemple "Timed out before an answer: refund wants to run".

Un signal interrompu, pane.close() et une fermeture depuis le téléphone ferment la demande avec une décision prise par program, et ask() est rejeté avec AskClosed.

Attention. Une option allow-always laisse passer tous les appels ultérieurs après une seule réponse. En https, le jeton constitue l'unique barrière, donc un agent durable n'y propose que Autoriser et Refuser. createCore avec allowAlways: false transforme une option allow-always en TypeError. Le téléphone ne propose aucune option allow-always sur une demande dont le texte a été tronqué ou nettoyé, ou qui ne nomme aucun outil.

Chaque action provenant du téléphone comporte un identifiant de requête, et le cœur en conserve l'accusé de réception : une répétition n'exécute rien et reçoit à nouveau la première réponse avec replayed: true. Le MemoryReceiptStore par défaut conserve les RECEIPTS_PER_GROUP plus récents (1000) par volet, ainsi que par groupe pour les démarrages, renommages, fermetures et réouvertures. Une répétition d'un identifiant abandonné reçoit 500 receipt-dropped et n'exécute rien. Le stockage disparaît avec le processus.

Pour conserver les accusés de réception après un redémarrage, écrivez un ReceiptStore avec get(requestId) et put(requestId, record, group), et transmettez-le à createCore sous le nom de receipts. openCollie les conserve toujours en mémoire.

Hooks et historique

Un hook est l'unique emplacement nommé pour une action envoyée par le téléphone, et un fournisseur d'historique sert votre propre registre.

Un hook ne s'exécute que lorsque sa capacité est activée et que son identifiant de requête est nouveau. Un refus ne stocke rien, de sorte que le même identifiant de requête peut faire une nouvelle tentative. Les gestionnaires par volet prévalent sur un hook. Un volet ne possédant ni l'un ni l'autre répond 409 not-supported à un envoi, un arrêt ou un appui.

Le SDK applique lui-même une action acceptée. Un renommage définit le titre. Une fermeture supprime la cible et tout son contenu, et ferme leurs demandes en cours comme interrompues. Une réouverture sans hook rétablit un volet fermé par ce processus ; une conversation fermée avant un redémarrage nécessite onReopen. La disposition est recréée à chaque démarrage, donc un agent durable souhaitant qu'un titre ou une fermeture survive au processus le stocke dans son hook.

collie.history(provider) sert chaque conversation, ouverte et fermée, depuis le stockage propre de l'agent durable. Il active la capacité history lorsque caps est omis ou nomme history: true.

Une ligne est { id, title, subtitle?, workspaceId?, tabId?, startedAt, endedAt?, state, items }, avec state open ou closed et items le décompte. Un curseur (after, next) est votre propre chaîne, de 1 à 512 octets d'ASCII imprimable sans espace. next absent termine la liste.

Dès qu'un fournisseur est défini, le sessionId de chaque volet correspond à son identifiant de volet, et l'historique sert la conversation du volet sous cet identifiant. Transmettez sessionId à tab.pane() pour désigner un autre identifiant, ou null lorsqu'il ne peut pas rester le même après un redémarrage.

tailLimit n'est pas un historique. C'est le flux brut de fin que chaque volet conserve pour les lectures d'événements de Collie, 500 événements par défaut. Un lecteur ayant pris du retard reçoit à la place l'intégralité de la vue actuelle du volet, au maximum les 2000 éléments les plus récents.

Capacités

Une capacité indique que l'agent durable peut effectuer une action, et le téléphone n'affiche un contrôle que pour une capacité déclarée par l'agent durable.

Omis, caps active tout ce que le SDK sait faire, ainsi que history dès que history() a un fournisseur. Défini, il s'agit de la liste complète : une capacité non mentionnée est désactivée, ainsi { asks: true } déclare uniquement les asks. Pour en désactiver une et conserver le reste, décomposez ALL_CAPS : { ...ALL_CAPS, steer: false }. Une route dont la capacité est désactivée renvoie 409 not-supported. terminal est toujours faux.

Utilitaires et constantes

L'import racine exporte aussi les éléments constituant openCollie, ainsi que les règles qu'il applique.

Chaque type sur le réseau et chaque payload de hook est également exporté, depuis src/core/types.ts.

Les assistants Pi

./pi transforme une conversation Pi Durable en panneau, un appel d'outil risqué en carte, et le magasin de Pi en historique.

Le texte affiché par une carte provient des options, ainsi ./pi ne contient aucun texte de l'exemple en dehors de ces deux constantes. Il est écrit pour Pi Durable 1.1.0. Le support desk dans examples/durable-member/ assemble chaque composant.

Versions

Le package possède sa propre version, distincte de celle de Collie, et indique la version du protocole réseau qu'il gère.

Collie gère une version du protocole réseau et accepte la précédente pendant une version mineure après la sortie d'une nouvelle version. Quand un Collie ne gère aucune de vos versions, le cœur écrit une ligne via warn, une fois par version, par exemple collie: Collie speaks wire v2, this durable agent speaks v1. Update the agent's SDK, or Collie. Le téléphone signale l'incompatibilité sur l'écran d'accueil de l'agent durable, avec les propres termes de Collie. Mettez à jour le composant le plus ancien.

Le package est publié sous le dist-tag npm experimental, jamais latest. Si le protocole réseau durable passe à la sortie, le package devient obsolète (ADR 0105).