L'SDK durevole (sperimentale)

Sperimentale. Il pacchetto, la relativa API e il protocollo di rete utilizzato potrebbero cambiare, oppure la funzionalità potrebbe essere rimossa, in una versione minor successiva. Versioni illustra cosa comporta per il proprio durable agent.

@colliepwa/durable-sdk è il pacchetto npm utilizzato da un durable agent per mostrarsi sul telefono tramite Collie. Questa pagina ne elenca ogni parte. Agenti durevoli contiene la guida rapida e la configurazione lato Collie, mentre Il wire durevole spiega cosa transita tra i due.

Installazione ed entry point

Una sola installazione fornisce cinque entry point: l'import radice per la maggior parte dei durable agent e quattro per esigenze più specifiche.

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

Il pacchetto richiede Node 22.19 o versioni successive, oppure Bun 1.4 o versioni successive, e non ha dipendenze di runtime. ./pi richiede @earendil-works/pi-durable, @earendil-works/pi-ai e @earendil-works/chord, versione 1.1 o successiva e inferiore a 2. L'entry point è testato con Pi Durable 1.1.0 e 1.2.0. I tre pacchetti sono peer dependency opzionali: un agente durevole che non importa mai ./pi non ne installa alcuno.

Il runtime determina se l'agente durevole può identificare chi risponde. Il controllo dei discendenti rifiuta un'azione proveniente dall'agente durevole stesso o da un processo da esso avviato, restituendo 403 caller-refused. Si applica a answer, send, stop, action, rename, close, reopen e starter. Le letture rimangono aperte.

Senza il controllo, qualsiasi processo del proprio utente può rispondere a una card, compreso uno strumento eseguito dall'agente. Eseguire gli strumenti dell'agente in una sandbox che non possa raggiungere il socket. Il socket richiede un sistema dotato di proprietari dei file, quindi su Windows openCollie si arresta all'avvio. In tale ambiente, un agente durevole espone ./core protetto da TLS con un token (Due modi per raggiungere un durable agent).

Aprire una connessione

openCollie crea il socket privato e l'handle restituito definisce la disposizione degli elementi mostrati dal telefono.

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

Senza l'opzione socket, il percorso proviene da COLLIE_DURABLE_SOCKET, la variabile letta anche da Collie.

Esistono altre due opzioni solo su createCore, non su openCollie: receipts e allowAlways (Domande).

close() lascia intenzionalmente aperte le richieste aperte: un arresto non è una risposta, e l'agente durevole decide cosa succede al lavoro in attesa di una risposta.

tab.pane(id, { title, harness, cwd?, sessionId? }) restituisce il riquadro con quell'id quando esiste, permettendo a un agente durevole di mostrare una conversazione due volte senza un secondo riquadro. I titoli sono troncati a 256 byte e harness a 64. cwd è un percorso assoluto, altrimenti viene omesso.

Ogni id segue la regola degli id: da 1 a 128 byte, nessun carattere di controllo, nessuno spazio bianco e nessuno tra /, ? o #. Un id non valido è un TypeError. L'id di un'area di lavoro o di una scheda non può contenere :, perché a livello di protocollo una scheda è denominata <workspace>:<tab>.

Riquadri

Un riquadro corrisponde a una conversazione, e i suoi metodi impostano ciò che il telefono mostra per essa.

Un riquadro ha anche quattro campi di sola lettura: id, sessionId, turnId (il turno in esecuzione, o l'ultimo) e openAsks. Il icon di un'azione è uno tra play, pause, check, x, refresh, archive, flag, star, send, note, search e more. Un altro nome non disegna alcuna icona.

Un evento item contiene un elemento con un id e un ts facoltativo. Un elemento con un ID noto sostituisce sul posto quello precedente.

Un elemento reply, thinking, notice o markdown può contenere partial: true mentre il suo testo cresce. Scrivere nuovamente lo stesso ID man mano che cresce, al massimo ogni 250 ms, poi un'ultima volta con il testo finale e senza partial, prima che il riquadro esca da working.

Il testo che supera il limite viene troncato, e i caratteri di controllo e invisibili vengono rimossi. Un valore non valido per lang, href, badge o progress diventa invece un TypeError o un RangeError, poiché Collie lo scarterebbe. Un agente durevole non può aggiungere autonomamente eventi ask, ask-closed o state: questi vengono scritti da ask() e state().

Domande

pane.ask mostra una scheda e si risolve con la risposta, mentre requireApproval chiede informazioni su una singola chiamata di strumento in una riga.

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) costruisce la scheda a partire dall'effettiva chiamata, mai dalle parole usate dal modello per descriverla. Il titolo è "refund wants to run", la riga dello strumento è refund(order: "5521", amount: 40), la notifica push indica "refund needs a yes", e i pulsanti sono Allow e Deny. Restituisce { approved, decidedBy, decidedAt, askId }. Un rifiuto, un timeout, un'interruzione e un annullamento restituiscono tutti approved: false.

callSummary(name, args) e argumentsView(args) sono i due elementi utilizzati: la chiamata su una sola riga e gli argomenti come coppie key: value con ogni valore in formato JSON.

pane.ask(input) accetta uno di quattro tipi. La promise si risolve con la risposta nel formato del tipo indicato.

Ciascun tipo accetta toolCallId, itemId e title (256 byte). Può accettare reason (2 KiB), tool, push: { title?, line? } (60 e 120 caratteri, il testo della notifica) e expiresAt (un Date o una stringa ISO 8601 con fuso orario).

Omettere id. L'SDK lo ricava con askIdFor(paneId, toolCallId): SHA-256 sui due id, prendendo i primi 32 caratteri esadecimali. La stessa chiamata dello strumento riproposta dopo un riavvio riceve quindi lo stesso id, e la risposta inviata dal telefono durante il riavvio va a buon fine. Proporre un id già aperto genera un TypeError.

decidedBy è phone, program o timeout. Una richiesta supera il suo expiresAt e si chiude con decisione presa da timeout: ask() rifiuta con AskClosed, la cui proprietà decidedBy è timeout. La scheda mostra il tempo rimanente fino a quel momento. Una domanda scaduta o decisa nell'agente durevole lascia una riga in Chat, come "Timed out before an answer: refund wants to run".

Un signal interrotto, pane.close() e una chiusura dal telefono chiudono la richiesta con decisione presa da program, e ask() rifiuta con AskClosed.

Attenzione. L'opzione allow-always lascia passare ogni chiamata successiva dopo una risposta. Su https il token è l'unico punto di controllo, quindi un durable agent in tale contesto offre solo Allow e Deny. createCore con allowAlways: false trasforma l'opzione allow-always in TypeError. Il telefono non offre allow-always per una richiesta le cui parole sono state tagliate o ripulite, o che non nomina alcuno strumento.

Ogni azione inviata dal telefono include un id di richiesta e il core ne conserva la ricevuta: una ripetizione non esegue nulla e riceve nuovamente la prima risposta con replayed: true. Il valore predefinito di MemoryReceiptStore conserva i RECEIPTS_PER_GROUP più recenti (1000) per pannello, e per gruppo nel caso di starter, ridenominazioni, chiusure e riaperture. La ripetizione di un id eliminato riceve 500 receipt-dropped e non esegue nulla. Lo store scompare con il processo.

Per conservare le ricevute dopo un riavvio, scrivere un ReceiptStore con get(requestId) e put(requestId, record, group), e passarlo a createCore come receipts. openCollie le conserva sempre in memoria.

Hook e cronologia

Un hook è l'unico punto con nome per un'azione inviata dal telefono, mentre un provider di cronologia gestisce le registrazioni proprie.

Un hook viene eseguito solo quando la sua cap è abilitata e il suo id di richiesta è nuovo. Un rifiuto non memorizza nulla, quindi lo stesso id di richiesta può riprovare. I gestori per singolo pannello hanno la precedenza su un hook. Un pannello privo di entrambi risponde con 409 not-supported a un invio, un'interruzione o un tocco.

L'SDK applica direttamente un'azione accettata. Una ridenominazione imposta il titolo. Una chiusura rimuove la destinazione e tutto ciò che contiene, e chiude le relative richieste aperte come interrotte. Una riapertura senza hook ripristina un pannello chiuso da questo processo; una conversazione chiusa prima di un riavvio richiede onReopen. Il layout viene ricreato a ogni avvio, quindi un durable agent che vuole preservare un titolo o una chiusura oltre il processo li memorizza nel proprio hook.

collie.history(provider) fornisce ogni conversazione, aperta e chiusa, dallo store proprio del durable agent. Abilita la cap history quando caps viene omesso o indica history: true.

Una riga è { id, title, subtitle?, workspaceId?, tabId?, startedAt, endedAt?, state, items }, con state open o closed e items come conteggio. Un cursore (after, next) è una stringa personalizzata, da 1 a 512 byte in ASCII stampabile senza spazi. L'assenza di next indica la fine dell'elenco.

Una volta impostato un provider, il valore sessionId di ogni pannello è il suo id pannello, e la cronologia fornisce la conversazione del pannello sotto tale id. Passare sessionId a tab.pane() per indicare un altro id, oppure null quando questo non può rimanere invariato dopo un riavvio.

tailLimit non è la cronologia. È la coda grezza conservata da ogni pannello per le letture degli eventi di Collie, 500 eventi per impostazione predefinita. Un lettore rimasto indietro riceve invece l'intera vista corrente del pannello, al massimo i 2000 elementi più recenti.

Caps

Una cap indica che il durable agent può compiere una determinata azione, e il telefono mostra un controllo solo per una cap dichiarata dal durable agent.

Se omesso, caps abilita tutto ciò che l'SDK può fare, e history non appena history() dispone di un provider. Se specificato, costituisce l'elenco completo: una cap non indicata è disabilitata, quindi { asks: true } dichiara unicamente gli ask. Per disabilitarne una e mantenere le altre, usare lo spread di ALL_CAPS: { ...ALL_CAPS, steer: false }. Una route con cap disabilitata risponde con 409 not-supported. terminal è sempre false.

Funzioni di supporto e costanti

L'import radice esporta anche i componenti di cui openCollie è composto e le regole applicate.

Anche ogni tipo sul wire e ogni payload degli hook viene esportato, da src/core/types.ts.

Gli helper di Pi

./pi trasforma una conversazione Pi Durable in un riquadro, una chiamata a uno strumento rischioso in una scheda e lo store di Pi nella cronologia.

Le parole mostrate da una scheda arrivano come opzioni, quindi ./pi non contiene testo dell'esempio ad eccezione di quelle due costanti. È scritto per Pi Durable 1.1.0. L'assistenza in examples/durable-member/ unisce tutte le parti.

Versioni

Il pacchetto ha una propria versione, separata da quella di Collie, e specifica la versione wire supportata.

Collie supporta una versione wire e accetta quella precedente per una release minor successiva al rilascio di una nuova versione. Quando un'istanza di Collie non supporta alcuna delle versioni usate, il core scrive una riga tramite warn, una volta per versione, ad esempio collie: Collie speaks wire v2, this durable agent speaks v1. Update the agent's SDK, or Collie. Il telefono segnala la mancata corrispondenza nella home dell'agente durable, con i messaggi di Collie. Aggiornare il componente meno recente.

Il pacchetto è pubblicato con il dist-tag npm experimental, mai latest. Se il wire durable passa a l'uscita, il pacchetto viene deprecato (ADR 0105).