El SDK durable (experimental)

Experimental. El paquete, su API y el protocolo que utiliza pueden cambiar, o la función puede eliminarse, en una versión menor posterior. Versiones indica lo que esto significa para su agente duradero.

@colliepwa/durable-sdk es el paquete npm que utiliza un agente duradero para mostrarse en el teléfono a través de Collie. Esta página enumera cada parte del mismo. Durable agents contiene el inicio rápido y la configuración del lado de Collie, y El protocolo durable explica lo que se transfiere entre ambos.

Instalación y puntos de entrada

Una instalación proporciona cinco puntos de entrada: la importación raíz para la mayoría de los agentes duraderos, y cuatro para necesidades más específicas.

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

El paquete requiere Node 22.19 o posterior, o Bun 1.4 o posterior, y no tiene dependencias de runtime. ./pi requiere @earendil-works/pi-durable, @earendil-works/pi-ai y @earendil-works/chord, 1.1 o posterior y menor que 2. La entrada está probada con Pi Durable 1.1.0 y 1.2.0. Los tres son dependencias de pares opcionales: un durable agent que nunca importe ./pi no instala ninguno.

El runtime decide si el durable agent puede determinar quién responde. La comprobación de descendientes rechaza una acción del propio durable agent o de un proceso iniciado por él, con 403 caller-refused. Cubre answer, send, stop, action, rename, close, reopen y starter. Las lecturas permanecen abiertas.

Sin la comprobación, cualquier proceso de su usuario puede responder a una tarjeta, incluida una herramienta que ejecute el agente. Ejecute las herramientas del agente en un sandbox que no pueda acceder al socket. El socket requiere un sistema con propietarios de archivos, por lo que en Windows openCollie se detiene al inicio. En su lugar, un durable agent allí sirve ./core detrás de TLS con un token (Dos formas de acceder a un agente duradero).

Abrir una conexión

openCollie crea el socket privado, y el identificador que devuelve define lo que muestra el teléfono.

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

Sin la opción socket, la ruta proviene de COLLIE_DURABLE_SOCKET, la variable que Collie también lee.

Existen dos opciones más solo en createCore, no en openCollie: receipts y allowAlways (Preguntas).

close() deja abiertas las solicitudes abiertas a propósito: un apagado no es una respuesta, y el agente persistente decide qué ocurre con el trabajo que espera una.

tab.pane(id, { title, harness, cwd?, sessionId? }) devuelve el panel que tiene ese id cuando existe, para que un agente persistente pueda mostrar una conversación dos veces sin un segundo panel. Los títulos se cortan a 256 bytes y harness a 64. cwd es una ruta absoluta; de lo contrario se omite.

Cada id sigue la regla de id: de 1 a 128 bytes, sin caracteres de control, sin espacios en blanco y ninguno de /, ? o #. Un id no válido es un TypeError. El id de un espacio de trabajo o pestaña no puede contener :, porque el protocolo nombra una pestaña como <workspace>:<tab>.

Paneles

Un panel es una conversación, y sus métodos definen lo que el teléfono muestra para ella.

Un panel también tiene cuatro campos de solo lectura: id, sessionId, turnId (el turno en ejecución, o el último) y openAsks. El icon de una acción es uno de play, pause, check, x, refresh, archive, flag, star, send, note, search y more. Otro nombre no dibuja ningún icono.

Un evento item transporta un elemento con un id y un ts opcional. Un elemento con un id conocido reemplaza al anterior en su lugar.

Un elemento reply, thinking, notice o markdown puede transportar partial: true mientras crece su texto. Escriba el mismo id de nuevo a medida que crezca, como máximo cada 250 ms, y luego una vez más con el texto final y sin partial, antes de que el panel salga de working.

El texto que excede su límite se recorta, y los controles y caracteres invisibles se eliminan. Un lang incorrecto, un href incorrecto, una insignia incorrecta o un progreso incorrecto se convierten en un TypeError o un RangeError, ya que Collie lo descartaría. Un agente duradero no puede anexar eventos ask, ask-closed o state por sí mismo: ask() y state() escriben estos.

Preguntas

pane.ask muestra una tarjeta y se resuelve con la respuesta, y requireApproval consulta sobre una llamada a herramienta en una sola línea.

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) construye la tarjeta a partir de lo que es la llamada, nunca a partir de las palabras del modelo sobre ella. El título es "refund wants to run", la línea de la herramienta es refund(order: "5521", amount: 40), la notificación dice "refund needs a yes", y los botones son Allow y Deny. Devuelve { approved, decidedBy, decidedAt, askId }. Una denegación, un tiempo de espera agotado, una detención y una anulación devuelven approved: false.

callSummary(name, args) y argumentsView(args) son las dos piezas que utiliza: la llamada en una sola línea y los argumentos como pares key: value con cada valor en formato JSON.

pane.ask(input) acepta una de cuatro clases. La promesa se resuelve con la respuesta en el formato de esa clase.

Cada clase admite toolCallId, itemId y title (256 bytes). Puede admitir reason (2 KiB), tool, push: { title?, line? } (60 y 120 caracteres, el texto de la notificación) y expiresAt (un Date o una cadena ISO 8601 con zona).

Omita id. El SDK lo deriva con askIdFor(paneId, toolCallId): SHA-256 sobre los dos identificadores, los primeros 32 caracteres hexadecimales. Por tanto, la misma llamada a la herramienta generada de nuevo tras un reinicio recibe el mismo id, y se procesa una respuesta enviada por el teléfono durante el reinicio. Generar un id ya abierto constituye un TypeError.

decidedBy es phone, program o timeout. Una solicitud supera su expiresAt y se cierra como decidida por timeout: ask() rechaza con AskClosed, cuyo decidedBy es timeout. La tarjeta muestra el tiempo restante hasta entonces. Una pregunta que agotó el tiempo de espera o se decidió en el agente persistente deja una línea en Chat, como por ejemplo "Timed out before an answer: refund wants to run".

Un signal abortado, pane.close() y un cierre desde el teléfono cierran la solicitud como decidida por program, y ask() rechaza con AskClosed.

Precaución. Una opción allow-always permite el paso de todas las llamadas posteriores tras una única respuesta. Mediante https el token es el único control de acceso, por lo que un agente persistente en ese entorno solo ofrece Permitir y Denegar. createCore con allowAlways: false convierte una opción allow-always en un TypeError. El teléfono no ofrece ningún allow-always en una solicitud cuyo texto fue recortado o limpiado, o que no especifica ninguna herramienta.

Cada acto desde el teléfono lleva un id de solicitud, y el núcleo guarda su recibo: una repetición no ejecuta nada y obtiene la primera respuesta nuevamente con replayed: true. El MemoryReceiptStore predeterminado conserva los RECEIPTS_PER_GROUP más recientes (1000) por panel, y por grupo para iniciadores, cambios de nombre, cierres y reaperturas. Una repetición de un id descartado obtiene 500 receipt-dropped y no ejecuta nada. El almacén desaparece con el proceso.

Para conservar los recibos tras un reinicio, escriba un ReceiptStore con get(requestId) y put(requestId, record, group), y páselo a createCore como receipts. openCollie siempre los conserva en memoria.

Hooks e historial

Un hook es el único lugar con nombre para un acto que envía el teléfono, y un proveedor de historial sirve su propio registro.

Un hook solo se ejecuta cuando su cap está activo y su id de solicitud es nuevo. Un rechazo no almacena nada, por lo que el mismo id de solicitud puede intentar de nuevo. Los controladores por panel tienen prioridad sobre un hook. Un panel sin ninguno de los dos responde 409 not-supported a un envío, una detención o un toque.

El SDK aplica un acto aceptado por sí mismo. Un cambio de nombre establece el título. Un cierre elimina el destino y todo lo que contiene, y cierra sus solicitudes abiertas como detenidas. Una reapertura sin hook restablece un panel que este proceso cerró; una conversación cerrada antes de un reinicio necesita onReopen. El diseño se vuelve a crear en cada inicio, por lo que un agente persistente que requiera que un título o un cierre sobreviva al proceso lo almacena en su hook.

collie.history(provider) sirve cada conversación, abierta y cerrada, desde el propio almacén del agente persistente. Activa el cap history cuando se omite caps o nombra a history: true.

Una fila es { id, title, subtitle?, workspaceId?, tabId?, startedAt, endedAt?, state, items }, con state open o closed y items el recuento. Un cursor (after, next) es su propia cadena, de 1 a 512 bytes de ASCII imprimible sin espacios. next ausente finaliza la lista.

Una vez configurado un proveedor, el sessionId de cada panel es su id de panel, y el historial sirve la conversación del panel bajo este. Pase sessionId a tab.pane() para nombrar otro id, o null cuando no pueda mantenerse igual tras un reinicio.

tailLimit no es historial. Es el registro final sin procesar que conserva cada panel para las lecturas de eventos de Collie, 500 eventos por defecto. Un lector que se haya quedado atrás obtiene en su lugar la vista actual completa del panel, como máximo los 2000 elementos más recientes.

Caps

Un cap indica que el agente persistente puede hacer una cosa, y el teléfono dibuja un control solo para un cap que el agente persistente declaró.

Si se omite, caps activa todo lo que el SDK puede hacer, y history una vez que history() tenga un proveedor. Si se proporciona, es la lista completa: una capacidad que no mencione está desactivada, por lo que { asks: true } declara únicamente solicitudes. Para desactivar una y mantener el resto, propague ALL_CAPS: { ...ALL_CAPS, steer: false }. Una ruta cuya capacidad esté desactivada responde 409 not-supported. terminal siempre es false.

Funciones auxiliares y constantes

La importación raíz también exporta las partes que componen openCollie y las reglas que aplica.

Cada tipo en el cable y cada carga útil de hook también se exportan, desde src/core/types.ts.

Los helpers de Pi

./pi convierte una conversación de Pi Durable en un panel, una llamada a herramienta riesgosa en una tarjeta y el almacén de Pi en historial.

Las palabras que muestra una tarjeta llegan como opciones, por lo que ./pi no contiene texto del ejemplo salvo esas dos constantes. Está escrito para Pi Durable 1.1.0. El centro de soporte en examples/durable-member/ reúne todas las partes.

Versiones

El paquete tiene su propia versión, aparte de la de Collie, e indica la versión de cable con la que se comunica.

Collie utiliza una versión de cable y acepta la anterior durante una versión menor tras publicar una nueva. Si un Collie no es compatible con ninguna de sus versiones, el núcleo escribe una línea mediante warn, una vez por versión, por ejemplo collie: Collie speaks wire v2, this durable agent speaks v1. Update the agent's SDK, or Collie. El teléfono muestra la discrepancia en el inicio del agente duradero, con las palabras de Collie. Actualice el extremo desactualizado.

El paquete se publica bajo la etiqueta de distribución de npm experimental, nunca latest. Si el cable duradero pasa a la salida, el paquete queda obsoleto (ADR 0105).