The durable SDK (experimental)

Experimental. The package, its API and the wire it speaks may change, or the feature may be removed, in a later minor release. Versions says what that means for your durable agent.

@colliepwa/durable-sdk is the npm package a durable agent uses to show itself on your phone through Collie. This page lists every part of it. Durable agents has the quickstart and the setup on the Collie side, and The durable wire explains what travels between the two.

Install and entries

One install gives five entries: the root import for most durable agents, and four for a narrower need.

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

The package needs Node 22.19 or later, or Bun 1.4 or later, and has no runtime dependency. ./pi needs @earendil-works/pi-durable, @earendil-works/pi-ai and @earendil-works/chord, 1.1 or later and below 2. The entry is tested with Pi Durable 1.1.0 and 1.2.0. The three are optional peer dependencies: a durable agent that never imports ./pi installs none.

The runtime decides whether the durable agent can tell who answers. The descendant check refuses an act from the durable agent itself or from a process it started, with 403 caller-refused. It covers answer, send, stop, action, rename, close, reopen and starter. Reads stay open.

Without the check, any process of your user can answer a card, a tool the agent runs included. Run the agent's tools in a sandbox that cannot reach the socket. The socket needs a system with file owners, so on Windows openCollie stops at start. A durable agent there serves ./core behind TLS with a token instead (Two ways to reach a durable agent).

Open a connection

openCollie makes the private socket, and the handle it returns lays out what the phone shows.

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

With no socket option, the path comes from COLLIE_DURABLE_SOCKET, the variable Collie reads too.

Two more options exist on createCore only, not on openCollie: receipts and allowAlways (Questions).

close() leaves open asks open on purpose: a shutdown is not an answer, and the durable agent decides what happens to the work that waits on one.

tab.pane(id, { title, harness, cwd?, sessionId? }) returns the pane that has that id when there is one, so a durable agent can show a conversation twice without a second pane. Titles are cut to 256 bytes and harness to 64. cwd is an absolute path, else it is left out.

Every id follows the id rule: 1 to 128 bytes, no control character, no whitespace, and none of /, ? or #. A bad id is a TypeError. A workspace or tab id may not hold :, because the wire names a tab <workspace>:<tab>.

Panes

A pane is one conversation, and its methods set what the phone shows for it.

A pane also has four read-only fields: id, sessionId, turnId (the running turn, or the last one) and openAsks. The icon of an action is one of play, pause, check, x, refresh, archive, flag, star, send, note, search and more. Another name draws no icon.

An item event carries one item with an id and an optional ts. An item with a known id replaces the earlier one in place.

A reply, thinking, notice or markdown item may carry partial: true while its text grows. Write the same id again as it grows, at most every 250 ms, then once more with the final text and no partial, before the pane leaves working.

Text over its limit is cut, and controls and invisible characters are removed. A bad lang, a bad href, a bad badge or a bad progress is a TypeError or a RangeError instead, because Collie would drop it. A durable agent may not append ask, ask-closed or state events itself: ask() and state() write those.

Questions

pane.ask shows a card and resolves with the answer, and requireApproval asks about one tool call in one line.

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) builds the card from what the call is, never from the model's words about it. The title is "refund wants to run", the tool line is refund(order: "5521", amount: 40), the push says "refund needs a yes", and the buttons are Allow and Deny. It returns { approved, decidedBy, decidedAt, askId }. A deny, a timeout, a stop and an abort all return approved: false.

callSummary(name, args) and argumentsView(args) are the two pieces it uses: the call in one line, and the arguments as key: value pairs with each value as JSON.

pane.ask(input) takes one of four kinds. The promise resolves with the answer in the shape of the kind.

Every kind takes toolCallId, itemId and title (256 bytes). It may take reason (2 KiB), tool, push: { title?, line? } (60 and 120 characters, the words of the notification) and expiresAt (a Date or an ISO 8601 string with a zone).

Leave id out. The SDK derives it with askIdFor(paneId, toolCallId): SHA-256 over the two ids, the first 32 hex characters. The same tool call raised again after a restart therefore gets the same id, and an answer the phone sent across the restart lands. Raising an id that is already open is a TypeError.

decidedBy is phone, program or timeout. An ask passes its expiresAt and closes as decided by timeout: ask() rejects with AskClosed, whose decidedBy is timeout. The card shows the time left until then. A question that timed out or was decided in the durable agent leaves one line in Chat, such as "Timed out before an answer: refund wants to run".

An aborted signal, pane.close() and a close from the phone close the ask as decided by program, and ask() rejects with AskClosed.

Caution. An allow-always option lets every later call through after one answer. Over https the token is the only gate, so a durable agent there offers Allow and Deny only. createCore with allowAlways: false makes an allow-always option a TypeError. The phone offers no allow-always on an ask whose words were cut or cleaned, or that names no tool.

Every act from the phone carries a request id, and the core keeps its receipt: a repeat runs nothing and gets the first reply again with replayed: true. The default MemoryReceiptStore keeps the newest RECEIPTS_PER_GROUP (1000) per pane, and per group for starters, renames, closes and reopens. A repeat of an id it dropped gets 500 receipt-dropped and runs nothing. The store is gone with the process.

To keep receipts across a restart, write a ReceiptStore with get(requestId) and put(requestId, record, group), and pass it to createCore as receipts. openCollie always keeps them in memory.

Hooks and history

A hook is the one named place for an act the phone sends, and a history provider serves your own record.

A hook runs only when its cap is on and its request id is new. A refusal stores nothing, so the same request id may try again. The per-pane handlers win over a hook. A pane with neither answers 409 not-supported to a send, a stop or a tap.

The SDK applies an accepted act itself. A rename sets the title. A close removes the target and everything inside it, and closes their open asks as stopped. A reopen without a hook puts back a pane this process closed; a conversation closed before a restart needs onReopen. The layout is made again on every start, so a durable agent that wants a title or a close to outlive the process stores it in its hook.

collie.history(provider) serves every conversation, open and closed, from the durable agent's own store. It turns the history cap on when caps is left out or names history: true.

A row is { id, title, subtitle?, workspaceId?, tabId?, startedAt, endedAt?, state, items }, with state open or closed and items the count. A cursor (after, next) is your own string, 1 to 512 bytes of printable ASCII with no space. next absent ends the list.

Once a provider is set, each pane's sessionId is its pane id, and the history serves the pane's conversation under it. Pass sessionId to tab.pane() to name another id, or null when it cannot stay the same across a restart.

tailLimit is not history. It is the raw tail each pane keeps for Collie's event reads, 500 events by default. A reader that fell behind it gets the pane's whole current view instead, at most the newest 2000 items.

Caps

A cap says the durable agent can do one thing, and the phone draws a control only for a cap the durable agent declared.

Left out, caps turns on everything the SDK can do, and history once history() has a provider. Given, it is the whole list: a cap it does not name is off, so { asks: true } declares asks alone. To turn one off and keep the rest, spread ALL_CAPS: { ...ALL_CAPS, steer: false }. A route whose cap is off answers 409 not-supported. terminal is always false.

Helpers and constants

The root import also exports the parts openCollie is made of, and the rules it applies.

Every type on the wire and every hook payload is exported too, from src/core/types.ts.

The Pi helpers

./pi turns a Pi Durable conversation into a pane, a risky tool call into a card, and Pi's store into history.

The words a card shows come in as options, so ./pi holds no text of the example but those two constants. It is written against Pi Durable 1.1.0. The support desk in examples/durable-member/ puts every part together.

Versions

The package has its own version, apart from Collie's, and names the wire version it speaks.

Collie speaks one wire version and accepts the one before it for one minor release after a new one ships. When a Collie speaks none of your versions, the core writes one line through warn, once per version, for example collie: Collie speaks wire v2, this durable agent speaks v1. Update the agent's SDK, or Collie. The phone says the mismatch on the durable agent's home, in Collie's own words. Update the older side.

The package is published under the npm dist-tag experimental, never latest. If the durable wire goes at the exit, the package is deprecated (ADR 0105).