O SDK de durable agent (experimental)

Experimental. O pacote, sua API e o protocolo que ele utiliza podem mudar, ou o recurso pode ser removido, em uma versão secundária posterior. Versões explica o que isso significa para o seu durable agent.

@colliepwa/durable-sdk é o pacote npm que um durable agent usa para aparecer no seu telefone pelo Collie. Esta página lista todas as suas partes. Durable agents contém o guia rápido e a configuração no Collie, e O durable wire explica o que trafega entre os dois.

Instalação e pontos de entrada

Uma instalação fornece cinco pontos de entrada: a importação raiz para a maioria dos durable agents e quatro para necessidades mais específicas.

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

O pacote precisa do Node 22.19 ou posterior, ou Bun 1.4 ou posterior, e não tem dependência de tempo de execução. ./pi precisa de @earendil-works/pi-durable, @earendil-works/pi-ai e @earendil-works/chord, 1.1 ou posterior e abaixo de 2. O ponto de entrada é testado com Pi Durable 1.1.0 e 1.2.0. Os três são peer dependencies opcionais: um agente durável que nunca importa ./pi não instala nenhum.

O runtime decide se o agente durável pode identificar quem responde. A verificação de descendente recusa uma ação vinda do próprio agente durável ou de um processo iniciado por ele, com 403 caller-refused. Ela cobre answer, send, stop, action, rename, close, reopen e starter. As leituras continuam abertas.

Sem a verificação, qualquer processo do seu usuário pode responder a um card, incluindo uma ferramenta executada pelo agente. Execute as ferramentas do agente em um sandbox que não consiga alcançar o socket. O socket precisa de um sistema com proprietários de arquivos, então no Windows openCollie é interrompido na inicialização. Em vez disso, um agente durável nesse sistema serve ./core sob TLS com um token (Duas formas de acessar um agente durável).

Abra uma conexão

openCollie cria o socket privado, e o identificador retornado define o layout exibido no telefone.

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

Sem a opção socket, o caminho vem de COLLIE_DURABLE_SOCKET, a mesma variável que o Collie lê.

Mais duas opções existem apenas em createCore, não em openCollie: receipts e allowAlways (Perguntas).

close() deixa asks abertos abertos de propósito: um encerramento não é uma resposta, e o agente durável decide o que acontece com o trabalho que espera por um.

tab.pane(id, { title, harness, cwd?, sessionId? }) retorna o painel que possui esse id quando ele existe, para que um agente durável possa exibir uma conversa duas vezes sem um segundo painel. Títulos são cortados em 256 bytes e harness em 64. cwd é um caminho absoluto, caso contrário é omitido.

Todo id segue a regra de id: 1 a 128 bytes, sem caracteres de controle, sem espaço em branco e nenhum de /, ? ou #. Um id inválido é um TypeError. Um id de workspace ou aba não pode conter :, porque a conexão nomeia uma aba como <workspace>:<tab>.

Painéis

Um painel é uma conversa, e seus métodos definem o que o telefone exibe para ela.

Um painel também tem quatro campos somente leitura: id, sessionId, turnId (o turno em execução, ou o último) e openAsks. O icon de uma ação é um entre play, pause, check, x, refresh, archive, flag, star, send, note, search e more. Outro nome não desenha nenhum ícone.

Um evento item carrega um item com um id e um ts opcional. Um item com um id conhecido substitui o anterior no mesmo lugar.

Um item reply, thinking, notice ou markdown pode carregar partial: true enquanto seu texto cresce. Escreva o mesmo id novamente conforme ele cresce, no máximo a cada 250 ms, e depois mais uma vez com o texto final e sem partial, antes que o painel saia de working.

O texto além do limite é cortado, e caracteres de controle e invisíveis são removidos. Um lang inválido, um href inválido, um badge inválido ou um progresso inválido vira um TypeError ou um RangeError, porque o Collie o descartaria. Um agente durável não pode anexar eventos ask, ask-closed ou state por conta própria: ask() e state() escrevem esses eventos.

Perguntas

pane.ask mostra um cartão e resolve com a resposta, e requireApproval pergunta sobre uma chamada de ferramenta em uma linha.

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) constrói o cartão a partir do que a chamada é, nunca das palavras do modelo sobre ela. O título é "refund wants to run", a linha da ferramenta é refund(order: "5521", amount: 40), a notificação diz "refund needs a yes", e os botões são Allow e Deny. Retorna { approved, decidedBy, decidedAt, askId }. Uma negação, um tempo limite esgotado, uma parada e um cancelamento retornam approved: false.

callSummary(name, args) e argumentsView(args) são as duas partes que ele usa: a chamada em uma linha, e os argumentos como pares key: value com cada valor como JSON.

pane.ask(input) aceita um de quatro tipos. A promise é resolvida com a resposta no formato do tipo.

Cada tipo aceita toolCallId, itemId e title (256 bytes). Pode aceitar reason (2 KiB), tool, push: { title?, line? } (60 e 120 caracteres, o texto da notificação) e expiresAt (um Date ou uma string ISO 8601 com fuso).

Deixe id de fora. O SDK deriva isso com askIdFor(paneId, toolCallId): SHA-256 sobre os dois ids, os primeiros 32 caracteres hexadecimais. A mesma chamada de ferramenta feita novamente após uma reinicialização recebe, portanto, o mesmo id, e uma resposta que o telefone enviou durante a reinicialização é entregue. Fazer uma chamada com um id que já está aberto gera um TypeError.

decidedBy é phone, program ou timeout. Um ask passa do seu expiresAt e fecha como decidido por timeout: ask() rejeita com AskClosed, cujo decidedBy é timeout. O card mostra o tempo restante até lá. Uma pergunta que expirou ou foi decidida no agente durável deixa uma linha no Chat, como "Timed out before an answer: refund wants to run".

Um signal abortado, pane.close() e um fechamento a partir do telefone fecham o ask como decidido por program, e ask() rejeita com AskClosed.

Atenção. Uma opção allow-always permite todas as chamadas posteriores após uma resposta. Via https o token é a única barreira, portanto um agente durável nesse caso oferece apenas Allow e Deny. createCore com allowAlways: false torna uma opção allow-always um TypeError. O telefone não oferece allow-always em um ask cujo texto foi cortado ou limpo, ou que não nomeia ferramenta alguma.

Toda ação vinda do telefone traz um id de requisição, e o núcleo guarda seu recibo: uma repetição não executa nada e recebe a primeira resposta novamente com replayed: true. O MemoryReceiptStore padrão mantém os RECEIPTS_PER_GROUP mais recentes (1000) por painel, e por grupo para starters, renomeações, fechamentos e reaberturas. A repetição de um id descartado recebe 500 receipt-dropped e não executa nada. O armazenamento desaparece junto com o processo.

Para manter os recibos através de uma reinicialização, escreva um ReceiptStore com get(requestId) e put(requestId, record, group), e passe-o para createCore como receipts. O openCollie sempre os mantém na memória.

Hooks e histórico

Um hook é o local nomeado único para uma ação enviada pelo telefone, e um provedor de histórico serve seu próprio registro.

Um hook executa apenas quando sua cap está ativa e seu id de requisição é novo. Uma recusa não armazena nada, permitindo que o mesmo id de requisição tente novamente. Os handlers por painel têm precedência sobre um hook. Um painel sem nenhum dos dois responde 409 not-supported a um envio, parada ou toque.

O próprio SDK aplica uma ação aceita. Uma renomeação define o título. Um fechamento remove o destino e tudo dentro dele, e fecha suas solicitações em aberto como interrompidas. Uma reabertura sem um hook restaura um painel fechado por este processo; uma conversa fechada antes de uma reinicialização precisa de onReopen. O layout é recriado a cada inicialização, portanto um agente durável que deseja manter um título ou um fechamento além do processo deve salvá-lo em seu hook.

collie.history(provider) serve todas as conversas, abertas e fechadas, a partir do próprio armazenamento do agente durável. Ele ativa a cap history quando caps é omitido ou aponta para history: true.

Uma linha é { id, title, subtitle?, workspaceId?, tabId?, startedAt, endedAt?, state, items }, com state open ou closed e items a contagem. Um cursor (after, next) é sua própria string, de 1 a 512 bytes de ASCII imprimível sem espaços. A ausência de next encerra a lista.

Após definir um provedor, o sessionId de cada painel passa a ser seu id de painel, e o histórico serve a conversa do painel sob ele. Passe sessionId para tab.pane() para especificar outro id, ou null quando ele não puder permanecer o mesmo após uma reinicialização.

tailLimit não é histórico. É a cauda bruta que cada painel mantém para as leituras de eventos do Collie, por padrão 500 eventos. Um leitor que ficou para trás recebe a visualização atual inteira do painel, no máximo os 2000 itens mais recentes.

Caps

Uma cap indica que o agente durável pode realizar uma ação, e o telefone renderiza um controle apenas para uma cap declarada pelo agente durável.

Omitido, caps ativa tudo o que o SDK pode fazer, e history assim que history() tiver um provedor. Informado, representa a lista inteira: uma cap não mencionada fica desativada, portanto { asks: true } declara apenas asks. Para desativar uma e manter o restante, espalhe ALL_CAPS: { ...ALL_CAPS, steer: false }. Uma rota cuja cap está desativada responde 409 not-supported. terminal é sempre false.

Utilitários e constantes

A importação raiz também exporta as partes que compõem openCollie e as regras que ele aplica.

Todos os tipos transmitidos e todos os payloads de hooks também são exportados a partir de src/core/types.ts.

Os utilitários do Pi

./pi transforma uma conversa do Pi Durable em um painel, uma chamada de ferramenta arriscada em um card e o armazenamento do Pi em histórico.

As palavras exibidas em um card chegam como opções, portanto ./pi não contém nenhum texto do exemplo além dessas duas constantes. Foi escrito para o Pi Durable 1.1.0. O suporte em examples/durable-member/ junta todas as partes.

Versões

O pacote tem sua própria versão, separada da versão do Collie, e indica a versão do protocolo de comunicação que utiliza.

O Collie utiliza uma versão do protocolo e aceita a anterior por uma versão minor após o lançamento de uma nova. Quando um Collie não aceita nenhuma das suas versões, o núcleo grava uma linha através de warn, uma vez por versão, por exemplo collie: Collie speaks wire v2, this durable agent speaks v1. Update the agent's SDK, or Collie. O telefone indica a incompatibilidade na página inicial do agente durável, nas palavras do próprio Collie. Atualize o lado mais antigo.

O pacote é publicado sob a dist-tag experimental do npm, nunca latest. Se o protocolo durável for para a saída, o pacote será descontinuado (ADR 0105).