Dayanıklı SDK (deneysel)

Deneysel. Paket, API'si ve konuştuğu hat ileriki bir ikincil sürümde değişebilir veya bu özellik kaldırılabilir. Sürümler, bunun kalıcı ajanınız için ne anlama geldiğini açıklar.

@colliepwa/durable-sdk, kalıcı bir ajanın Collie aracılığıyla telefonunuzda kendini göstermek için kullandığı npm paketidir. Bu sayfa paketin tüm parçalarını listeler. Dayanıklı aracılar hızlı başlangıcı ve Collie tarafındaki kurulumu içerir; Durable wire ise ikisi arasında nelerin aktarıldığını açıklar.

Kurulum ve girişler

Tek bir kurulum beş giriş sağlar: çoğu kalıcı ajan için kök içe aktarma ve daha özel bir ihtiyaç için dört giriş.

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

Paket, Node 22.19 veya üzerini ya da Bun 1.4 veya üzerini gerektirir ve çalışma zamanı bağımlılığı yoktur. ./pi; 1.1 veya üzeri ve 2'nin altında @earendil-works/pi-durable, @earendil-works/pi-ai ve @earendil-works/chord gerektirir. Giriş noktası Pi Durable 1.1.0 ve 1.2.0 ile test edilmiştir. Bu üçü isteğe bağlı eş bağımlılıklardır: ./pi içe aktarmayan dayanıklı bir ajan hiçbirini yüklemez.

Çalışma zamanı, dayanıklı ajanın kimin yanıt verdiğini anlayıp anlayamayacağına karar verir. Alt süreç denetimi, dayanıklı ajanın kendisinden veya başlattığı bir süreçten gelen eylemleri 403 caller-refused ile reddeder. answer, send, stop, action, rename, close, reopen ve starter eylemlerini kapsar. Okuma işlemleri açık kalır.

Denetim olmadan, kullanıcınızın herhangi bir süreci bir kartı yanıtlayabilir; ajanın çalıştırdığı araçlar da buna dahildir. Ajanın araçlarını sokete erişemeyen bir yalıtılmış alanda çalıştırın. Soket, dosya sahipleri olan bir sisteme ihtiyaç duyar; bu nedenle Windows üzerinde openCollie başlangıçta durur. Oradaki dayanıklı bir ajan, bunun yerine bir belirteç ile TLS arkasında ./core sunar (Bir durable agent'a ulaşmanın iki yolu).

Bir bağlantı açın

openCollie özel soketi oluşturur ve döndürdüğü tanıtıcı telefonun ne göstereceğini düzenler.

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

socket seçeneği olmadığında yol, Collie tarafından da okunan değişken olan COLLIE_DURABLE_SOCKET değerinden gelir.

Yalnızca createCore üzerinde bulunan, openCollie üzerinde bulunmayan iki seçenek daha vardır: receipts ve allowAlways (Sorular).

close() açık soruları bilerek açık bırakır: kapatma bir yanıt değildir ve bunlardan birini bekleyen işe ne olacağına kalıcı aracı karar verir.

tab.pane(id, { title, harness, cwd?, sessionId? }), varsa bu kimliğe sahip bölmeyi döndürür; böylece kalıcı bir aracı, ikinci bir bölme olmadan bir konuşmayı iki kez gösterebilir. Başlıklar 256 bayt ve harness 64 bayt ile sınırlandırılır. cwd mutlak bir yoldur, aksi takdirde atlanır.

Her kimlik, kimlik kuralına uyar: 1 ila 128 bayt, kontrol karakteri yok, boşluk yok ve /, ? veya # karakterlerinden hiçbiri bulunmaz. Geçersiz bir kimlik TypeError durumudur. Bir çalışma alanı veya sekme kimliği : içeremez, çünkü kablo bir sekmeyi <workspace>:<tab> olarak adlandırır.

Bölmeler

Bir bölme tek bir konuşmadır ve yöntemleri telefonun bu konuşma için ne göstereceğini belirler.

Bir bölmede ayrıca dört salt okunur alan bulunur: id, sessionId, turnId (çalışan tur veya sonuncusu) ve openAsks. Bir eylemin icon alanı play, pause, check, x, refresh, archive, flag, star, send, note, search ve more değerlerinden biridir. Başka bir ad simge çizmez.

Bir item olayı, bir id ve isteğe bağlı bir ts içeren bir öge taşır. Bilinen kimliğe sahip bir öge, önceki ögenin yerini alır.

Bir reply, thinking, notice veya markdown ögesi, metni büyürken partial: true taşıyabilir. Bölme working durumundan ayrılmadan önce, metin büyüdükçe en fazla 250 ms'de bir aynı kimliği yeniden yazın; ardından son metinle ve partial olmadan bir kez daha yazın.

Sınırını aşan metin kesilir; denetim karakterleri ve görünmeyen karakterler kaldırılır. Hatalı bir lang, hatalı bir href, hatalı bir rozet veya hatalı bir ilerleme, Collie onu bırakacağı için bunun yerine bir TypeError veya RangeError olur. Dayanıklı bir ajan kendisi ask, ask-closed veya state olayları ekleyemez: bunları ask() ve state() yazar.

Sorular

pane.ask bir kart gösterir ve yanıtla çözümlenir; requireApproval ise tek bir satırda tek bir araç çağrısını sorar.

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), kartı modelin bununla ilgili sözlerinden değil, çağrının ne olduğundan oluşturur. Başlık "refund wants to run", araç satırı refund(order: "5521", amount: 40), anlık bildirim "refund needs a yes" şeklindedir ve butonlar Allow ile Deny şeklindedir. { approved, decidedBy, decidedAt, askId } döndürür. Reddetme, zaman aşımı, durdurma ve iptal durumlarının tümü approved: false döndürür.

callSummary(name, args) ve argumentsView(args) kullandığı iki parçadır: tek satırda çağrı ve her bir değeri JSON olan key: value çiftleri biçimindeki bağımsız değişkenler.

pane.ask(input) dört türden birini alır. Promise, türün biçimindeki yanıt ile çözümlenir.

Her tür toolCallId, itemId ve title (256 bayt) alır. reason (2 KiB), tool, push: { title?, line? } (60 ve 120 karakter, bildirimin metinleri) ve expiresAt (bir Date veya saat dilimi içeren bir ISO 8601 dizesi) alabilir.

id alanını hariç tutun. SDK bunu askIdFor(paneId, toolCallId) ile türetir: iki kimlik üzerinden SHA-256, ilk 32 onaltılık karakter. Bu nedenle yeniden başlatmanın ardından tekrar oluşturulan aynı araç çağrısı aynı kimliği alır ve telefonun yeniden başlatma öncesinde veya sırasında gönderdiği bir yanıt yerine ulaşır. Zaten açık olan bir kimliği oluşturmak bir TypeError hatasıdır.

decidedBy; phone, program veya timeout değerini alır. Bir sorma işlemi expiresAt süresini geçer ve timeout tarafından kararlaştırıldığı şekilde kapanır: ask(), decidedBy değeri timeout olan AskClosed ile reddedilir. Kart o zamana kadar kalan süreyi gösterir. Zaman aşımına uğrayan veya durable agent içinde karara bağlanan bir soru, Chat içinde "Timed out before an answer: refund wants to run" gibi tek bir satır bırakır.

İptal edilen bir signal, pane.close() ve telefondan gelen bir kapatma işlemi sormayı program tarafından kararlaştırıldığı şekilde kapatır ve ask(), AskClosed ile reddedilir.

Dikkat. Bir allow-always seçeneği, tek bir yanıttan sonraki tüm çağrılara izin verir. https üzerinden token tek geçittir, bu nedenle oradaki bir durable agent yalnızca İzin Ver ve Reddet seçeneklerini sunar. allowAlways: false ile createCore, bir allow-always seçeneğini TypeError yapar. Telefon, sözcükleri kesilmiş veya temizlenmiş ya da hiçbir aracı adlandırmayan bir sormada hiçbir allow-always sunmaz.

Telefondan gelen her eylem bir istek kimliği taşır ve çekirdek bunun makbuzunu saklar: tekrarlanan bir istek hiçbir şey çalıştırmaz ve replayed: true ile ilk yanıtı tekrar alır. Varsayılan MemoryReceiptStore, bölme başına ve başlatıcılar, yeniden adlandırmalar, kapatmalar ve yeniden açmalar için grup başına en yeni RECEIPTS_PER_GROUP (1000) öğeyi saklar. Bıraktığı bir kimliğin tekrarı 500 receipt-dropped alır ve hiçbir şey çalıştırmaz. Depo, işlemle birlikte kaybolur.

Makbuzları yeniden başlatma sonrasında da korumak için get(requestId) ve put(requestId, record, group) içeren bir ReceiptStore yazın ve bunu createCore içine receipts olarak geçirin. openCollie bunları her zaman bellekte tutar.

Kancalar ve geçmiş

Hook, telefonun gönderdiği bir eylem için belirlenmiş tek adlandırılmış yerdir; geçmiş sağlayıcısı ise kendi kaydınızı sunar.

Bir hook yalnızca yeteneği etkin olduğunda ve istek kimliği yeni olduğunda çalışır. Reddetme hiçbir şey depolamaz, bu nedenle aynı istek kimliği tekrar deneyebilir. Bölme başına işleyiciler hook'a göre önceliklidir. İkisine de sahip olmayan bir bölme; gönderme, durdurma veya dokunmaya 409 not-supported yanıtı verir.

SDK kabul edilen bir eylemi kendisi uygular. Yeniden adlandırma başlığı ayarlar. Kapatma, hedefi ve içindeki her şeyi kaldırır, açık isteklerini durduruldu olarak kapatır. Hook olmadan yeniden açma, bu işlemin kapattığı bir bölmeyi geri yükler; yeniden başlatmadan önce kapatılan bir konuşma onReopen gerektirir. Düzen her başlangıçta yeniden oluşturulur, bu nedenle bir başlığın veya kapatmanın işlemden sonra da kalmasını isteyen dayanıklı bir aracı bunu kendi hook'unda depolar.

collie.history(provider), açık ve kapalı her konuşmayı dayanıklı aracının kendi deposundan sunar. caps atlandığında veya history: true belirtildiğinde history yeteneğini etkinleştirir.

Bir satır { id, title, subtitle?, workspaceId?, tabId?, startedAt, endedAt?, state, items } biçimindedir; state open veya closed değerine sahiptir ve items sayıdır. İmleç (after, next) boşluk içermeyen, 1 ila 512 baytlık yazdırılabilir ASCII olan kendi dizginizdir. next bulunmadığında liste sona erer.

Bir sağlayıcı ayarlandıktan sonra her bölmenin sessionId değeri kendi bölme kimliğidir ve geçmiş, bölmenin konuşmasını bunun altında sunar. Başka bir kimlik belirtmek için tab.pane() içine sessionId geçirin veya yeniden başlatma sonrasında aynı kalamadığında null geçirin.

tailLimit geçmiş değildir. Her bölmenin Collie'nin olay okumaları için tuttuğu ham kuyruktur, varsayılan olarak 500 olaydır. Bunun gerisinde kalan bir okuyucu, bunun yerine bölmenin tüm geçerli görünümünü, en fazla en yeni 2000 öğeyi alır.

Kabiliyetler

Yetenek, dayanıklı aracının bir şeyi yapabileceğini belirtir ve telefon yalnızca dayanıklı aracının bildirdiği bir yetenek için denetim çizer.

Belirtilmezse caps, SDK'nın yapabileceği her şeyi ve history() bir sağlayıcıya sahip olduğunda history özelliğini açar. Belirtilirse tüm listedir: adlandırmadığı bir sınır kapalıdır, bu nedenle { asks: true } yalnızca sormaları bildirir. Birini kapatıp kalanları tutmak için ALL_CAPS öğesini yayın: { ...ALL_CAPS, steer: false }. Sınırı kapalı olan bir rota 409 not-supported yanıtı verir. terminal her zaman false değerindedir.

Yardımcılar ve sabitler

Kök içe aktarımı, openCollie bileşeninin oluştuğu parçaları ve uyguladığı kuralları da dışa aktarır.

Kablo üzerindeki her tür ve her kanca yükü de src/core/types.ts üzerinden dışa aktarılır.

Pi yardımcıları

./pi, bir Pi Durable konuşmasını bir bölmeye, riskli bir araç çağrısını bir karta ve Pi deposunu geçmişe dönüştürür.

Kartın gösterdiği sözcükler seçenek olarak gelir; bu nedenle ./pi, bu iki sabit dışında örneğe ait hiçbir metin barındırmaz. Pi Durable 1.1.0 sürümüne göre yazılmıştır. examples/durable-member/ içindeki destek masası tüm parçaları bir araya getirir.

Sürümler

Paketin Collie'den ayrı kendi sürümü vardır ve konuştuğu kablo sürümünü belirtir.

Collie tek bir kablo sürümünü konuşur ve yeni bir sürüm çıktıktan sonraki bir ikincil sürüm boyunca bir öncekini kabul eder. Bir Collie sürümlerinizin hiçbirini konuşmadığında çekirdek, her sürüm için bir kez olmak üzere warn üzerinden tek bir satır yazar, örneğin collie: Collie speaks wire v2, this durable agent speaks v1. Update the agent's SDK, or Collie.. Telefon, durable agent'ın ana ekranında uyumsuzluğu Collie'nin kendi sözcükleriyle belirtir. Eski tarafı güncelleyin.

Paket npm dist-tag experimental altında yayımlanır, hiçbir zaman latest altında yayımlanmaz. Durable kablo çıkış üzerinde kaldırılırsa paket kullanımdan kaldırılır (ADR 0105).