Das SDK für persistente Agenten (experimentell)

Experimentell. Das Paket, seine API und das Protokoll, das es spricht, können sich in einer späteren Minor-Version ändern, oder die Funktion kann entfernt werden. Versionen beschreibt, was das für Ihren Durable Agent bedeutet.

@colliepwa/durable-sdk ist das npm-Paket, das ein Durable Agent nutzt, um sich über Collie auf Ihrem Smartphone anzuzeigen. Diese Seite führt alle Bestandteile auf. Persistente Agenten enthält die Schnellanleitung sowie die Einrichtung auf Collie-Seite, und Das Durable-Wire erklärt die Übertragung zwischen beiden.

Installation und Einstiegspunkte

Eine Installation liefert fünf Einstiegspunkte: den Root-Import für die meisten Durable Agents und vier für spezifischere Anforderungen.

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

Das Paket erfordert Node 22.19 oder neuer oder Bun 1.4 oder neuer und hat keine Laufzeitabhängigkeit. ./pi erfordert @earendil-works/pi-durable, @earendil-works/pi-ai und @earendil-works/chord, 1.1 oder neuer und unter 2. Der Einstiegspunkt ist mit Pi Durable 1.1.0 und 1.2.0 getestet. Die drei sind optionale Peer-Abhängigkeiten: Ein langlebiger Agent, der ./pi nie importiert, installiert keine davon.

Die Laufzeitumgebung entscheidet, ob der langlebige Agent erkennen kann, wer antwortet. Die Nachfahrenprüfung verweigert Aktionen des langlebigen Agenten selbst oder eines von ihm gestarteten Prozesses mit 403 caller-refused. Sie deckt answer, send, stop, action, rename, close, reopen und starter ab. Lesezugriffe bleiben offen.

Ohne die Prüfung kann jeder Prozess Ihres Benutzers eine Karte beantworten, einschließlich eines vom Agenten ausgeführten Werkzeugs. Führen Sie die Werkzeuge des Agenten in einer Sandbox aus, die den Socket nicht erreichen kann. Der Socket erfordert ein System mit Dateieigentümern; unter Windows bricht openCollie daher beim Start ab. Ein langlebiger Agent stellt dort stattdessen ./core hinter TLS mit einem Token bereit (Zwei Wege, einen langlebigen Agenten zu erreichen).

Verbindung öffnen

openCollie erstellt den privaten Socket, und das zurückgegebene Handle bestimmt das Layout der Smartphone-Anzeige.

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

Ohne die Option socket stammt der Pfad aus COLLIE_DURABLE_SOCKET, der Variable, die auch Collie liest.

Zwei weitere Optionen existieren nur bei createCore, nicht bei openCollie: receipts und allowAlways (Fragen).

close() lässt offene Anfragen absichtlich offen: Ein Herunterfahren ist keine Antwort, und der dauerhafte Agent entscheidet, was mit der darauf wartenden Arbeit geschieht.

tab.pane(id, { title, harness, cwd?, sessionId? }) gibt den Bereich mit dieser ID zurück, falls vorhanden, sodass ein dauerhafter Agent eine Konversation zweimal ohne zweiten Bereich anzeigen kann. Titel werden auf 256 Bytes gekürzt und harness auf 64. cwd ist ein absoluter Pfad, andernfalls wird er weggelassen.

Jede ID folgt der ID-Regel: 1 bis 128 Bytes, kein Steuerzeichen, kein Leerraum und keines von /, ? oder #. Eine ungültige ID ist ein TypeError. Eine Arbeitsbereichs- oder Tab-ID darf : nicht enthalten, da das Wire einen Tab als <workspace>:<tab> benennt.

Bereiche

Ein Bereich entspricht einer Konversation, und seine Methoden legen fest, was das Telefon dafür anzeigt.

Ein Bereich hat außerdem vier schreibgeschützte Felder: id, sessionId, turnId (der laufende Durchlauf oder der letzte) und openAsks. Das icon einer Aktion ist eines von play, pause, check, x, refresh, archive, flag, star, send, note, search und more. Ein anderer Name zeichnet kein Symbol.

Ein item-Ereignis überträgt ein Element mit einer id und einem optionalen ts. Ein Element mit einer bekannten ID ersetzt das frühere Element an Ort und Stelle.

Ein reply-, thinking-, notice- oder markdown-Element darf partial: true tragen, während sein Text wächst. Schreiben Sie dieselbe ID erneut, während er wächst, höchstens alle 250 ms, danach noch einmal mit dem finalen Text und ohne partial, bevor der Bereich working verlässt.

Text oberhalb des Limits wird abgeschnitten, und Steuerzeichen sowie unsichtbare Zeichen werden entfernt. Ein ungültiges lang, ein ungültiges href, ein ungültiges Badge oder ein ungültiger Fortschritt wird stattdessen zu einem TypeError oder einem RangeError, da Collie es sonst verwerfen würde. Ein persistenter Agent darf ask-, ask-closed- oder state-Ereignisse nicht selbst anhängen: ask() und state() schreiben diese.

Fragen

pane.ask zeigt eine Karte an und löst mit der Antwort auf, und requireApproval fragt nach einem Werkzeugaufruf in einer einzelnen Zeile.

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) erstellt die Karte anhand des Aufrufinhalts, niemals anhand der Worte des Modells darüber. Der Titel lautet "refund wants to run", die Werkzeugzeile ist refund(order: "5521", amount: 40), die Push-Nachricht lautet "refund needs a yes", und die Schaltflächen sind Allow und Deny. Es gibt { approved, decidedBy, decidedAt, askId } zurück. Ablehnung, Zeitüberschreitung, Stopp und Abbruch geben alle approved: false zurück.

callSummary(name, args) und argumentsView(args) sind die beiden Teile, die es verwendet: der Aufruf in einer Zeile und die Argumente als key: value-Paare mit jedem Wert als JSON.

pane.ask(input) akzeptiert eine von vier Arten. Das Promise wird mit der Antwort in der Form der Art aufgelöst.

Jede Art akzeptiert toolCallId, itemId und title (256 Bytes). Sie kann reason (2 KiB), tool, push: { title?, line? } (60 und 120 Zeichen, der Text der Benachrichtigung) und expiresAt (ein Date oder eine ISO-8601-Zeichenkette mit Zeitzone) akzeptieren.

Lassen Sie id weg. Das SDK leitet es mit askIdFor(paneId, toolCallId) ab: SHA-256 über die beiden IDs, die ersten 32 Hex-Zeichen. Derselbe nach einem Neustart erneut ausgelöste Tool-Aufruf erhält daher dieselbe ID, und eine Antwort, die das Telefon über den Neustart hinweg gesendet hat, kommt an. Das Auslösen einer bereits offenen ID ist ein TypeError.

decidedBy ist phone, program oder timeout. Eine Anfrage überschreitet ihr expiresAt und schließt als entschieden von timeout: ask() schlägt fehl mit AskClosed, dessen decidedBy timeout ist. Die Karte zeigt die verbleibende Zeit bis dahin an. Eine Frage, die abgelaufen ist oder im Durable Agent entschieden wurde, hinterlässt eine Zeile im Chat, wie etwa „Vor einer Antwort abgelaufen: refund möchte ausgeführt werden“.

Ein abgebrochenes signal, pane.close() und ein Schließen vom Telefon schließen die Anfrage als entschieden von program, und ask() schlägt fehl mit AskClosed.

Achtung. Eine allow-always-Option lässt nach einer einzigen Antwort jeden späteren Aufruf durch. Über https ist das Token das einzige Zugangstor, daher bietet ein Durable Agent dort nur Erlauben und Verweigern an. createCore mit allowAlways: false macht eine allow-always-Option zu einem TypeError. Das Telefon bietet kein allow-always bei einer Anfrage an, deren Text gekürzt oder bereinigt wurde oder die kein Tool benennt.

Jede Aktion des Telefons enthält eine Anfrage-ID, und der Core behält deren Beleg: Eine Wiederholung führt nichts aus und erhält die erste Antwort erneut mit replayed: true. Der Standard-MemoryReceiptStore behält die neuesten RECEIPTS_PER_GROUP (1000) pro Bereich sowie pro Gruppe für Starter, Umbenennungen, Schließungen und Wiederöffnungen. Eine Wiederholung einer ID, die er verworfen hat, erhält 500 receipt-dropped und führt nichts aus. Der Speicher verschwindet mit dem Prozess.

Um Belege über einen Neustart hinweg zu behalten, schreiben Sie einen ReceiptStore mit get(requestId) und put(requestId, record, group) und übergeben Sie ihn an createCore als receipts. openCollie behält sie immer im Arbeitsspeicher.

Hooks und Verlauf

Ein Hook ist der einzige benannte Ort für eine Aktion, die das Telefon sendet, und ein Verlaufsprovider liefert Ihren eigenen Datensatz aus.

Ein Hook wird nur ausgeführt, wenn seine Cap aktiviert und seine Anfrage-ID neu ist. Eine Ablehnung speichert nichts, daher kann dieselbe Anfrage-ID einen erneuten Versuch starten. Die Handler pro Bereich haben Vorrang vor einem Hook. Ein Bereich mit keinem von beiden antwortet mit 409 not-supported auf ein Senden, einen Stopp oder einen Klick.

Das SDK wendet eine akzeptierte Aktion selbst an. Eine Umbenennung setzt den Titel. Ein Schließen entfernt das Ziel samt Inhalt und schließt dessen offene Anfragen als gestoppt. Ein Wiederöffnen ohne Hook stellt einen Bereich wieder her, den dieser Prozess geschlossen hat; eine vor einem Neustart geschlossene Konversation benötigt onReopen. Das Layout wird bei jedem Start neu erstellt. Ein langlebiger Agent, dessen Titel oder Schließung den Prozess überdauern soll, speichert dies daher in seinem Hook.

collie.history(provider) liefert jede Konversation, offen wie geschlossen, aus dem eigenen Speicher des langlebigen Agenten aus. Es aktiviert die history-Cap, wenn caps weggelassen wird oder history: true benennt.

Eine Zeile ist { id, title, subtitle?, workspaceId?, tabId?, startedAt, endedAt?, state, items }, mit state open oder closed und items als Anzahl. Ein Cursor (after, next) ist Ihre eigene Zeichenkette, 1 bis 512 Byte druckbares ASCII ohne Leerzeichen. Ein fehlendes next beendet die Liste.

Sobald ein Provider gesetzt ist, entspricht sessionId jedes Bereichs dessen Bereichs-ID, und der Verlauf liefert die Konversation des Bereichs darunter aus. Übergeben Sie sessionId an tab.pane(), um eine andere ID anzugeben, oder null, wenn sie über einen Neustart hinweg nicht gleich bleiben kann.

tailLimit ist kein Verlauf. Es ist das reine Protokollende, das jeder Bereich für Collies Ereignisabfragen behält, standardmäßig 500 Ereignisse. Ein Leser, der dahinter zurückgefallen ist, erhält stattdessen die gesamte aktuelle Ansicht des Bereichs, maximal die neuesten 2000 Einträge.

Fähigkeiten

Eine Cap besagt, dass der langlebige Agent eine bestimmte Sache ausführen kann, und das Telefon stellt ein Steuerelement nur für eine Cap dar, die der langlebige Agent deklariert hat.

Wird er weggelassen, schaltet caps alles ein, was das SDK unterstützt, und history, sobald history() einen Provider hat. Wird er angegeben, gilt die vollständige Liste: Eine Funktionseinschränkung (Cap), die er nicht nennt, ist deaktiviert; { asks: true } deklariert somit allein Anfragen. Um eine zu deaktivieren und den Rest zu behalten, wenden Sie Spread auf ALL_CAPS an: { ...ALL_CAPS, steer: false }. Eine Route mit deaktivierter Funktionseinschränkung antwortet mit 409 not-supported. terminal ist immer false.

Hilfsfunktionen und Konstanten

Der Root-Import exportiert auch die Bausteine, aus denen openCollie besteht, und die Regeln, die es anwendet.

Jeder Typ auf der Leitung und jede Hook-Nutzlast wird ebenfalls exportiert, aus src/core/types.ts.

Die Pi-Hilfsfunktionen

./pi wandelt eine Pi-Durable-Unterhaltung in einen Bereich um, einen riskanten Werkzeugaufruf in eine Karte und den Pi-Speicher in den Verlauf.

Die Wörter, die eine Karte anzeigt, werden als Optionen übergeben, daher enthält ./pi keinen Text des Beispiels außer diesen beiden Konstanten. Es wurde für Pi Durable 1.1.0 geschrieben. Der Support-Desk in examples/durable-member/ setzt alle Teile zusammen.

Versionen

Das Paket hat eine eigene Version, unabhängig von der von Collie, und nennt die Leitungsversion, die es spricht.

Collie spricht eine Leitungsversion und akzeptiert die vorherige für ein Minor-Release nach der Veröffentlichung einer neuen. Wenn ein Collie keine Ihrer Versionen spricht, schreibt der Kern eine Zeile über warn, einmal pro Version, zum Beispiel collie: Collie speaks wire v2, this durable agent speaks v1. Update the agent's SDK, or Collie. Das Telefon meldet die Abweichung auf der Startseite des Durable-Agenten mit Collies eigenen Worten. Aktualisieren Sie die ältere Seite.

Das Paket wird unter dem npm-dist-tag experimental veröffentlicht, niemals unter latest. Wenn die Durable-Leitung bei das Beenden eingestellt wird, wird das Paket als veraltet markiert (ADR 0105).