SDK для durable (экспериментально)

Экспериментальная. Пакет, его API и сетевой протокол могут измениться, либо функциональность может быть удалена в следующем минорном релизе. Версии поясняет, что это означает для вашего durable agent.

@colliepwa/durable-sdk — это npm-пакет, с помощью которого durable agent отображает себя на вашем телефоне через Collie. На этой странице перечислены все его части. В Durable agents приведено краткое руководство и настройка на стороне Collie, а в Протокол durable wire объясняется, что передаётся между ними.

Установка и точки входа

Одна установка даёт пять точек входа: корневой импорт для большинства durable agents и четыре для более специфических задач.

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

Пакету требуется Node 22.19 или новее, либо Bun 1.4 или новее, и у него нет runtime-зависимостей. Для ./pi нужны @earendil-works/pi-durable, @earendil-works/pi-ai и @earendil-works/chord версий от 1.1 до 2. Точка входа протестирована с Pi Durable 1.1.0 и 1.2.0. Эти три пакета являются опциональными peer-зависимостями: durable-агент, который не импортирует ./pi, не устанавливает ни одной из них.

Рантайм определяет, может ли durable-агент распознать автора ответа. Проверка потомков отклоняет действие от самого durable-агента или запущенного им процесса с кодом 403 caller-refused. Она распространяется на answer, send, stop, action, rename, close, reopen и starter. Чтение остаётся доступным.

Без этой проверки любой процесс вашего пользователя может ответить на карточку, включая запущенный агентом инструмент. Запускайте инструменты агента в песочнице, у которой нет доступа к сокету. Для сокета требуется система с владельцами файлов, поэтому на Windows openCollie завершает работу при старте. Вместо этого durable-агент там раздаёт ./core через TLS с токеном (Два способа связи с durable agent).

Открыть соединение

openCollie создаёт приватный сокет, а возвращённый дескриптор задаёт разметку для отображения на телефоне.

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 не задана, путь берётся из COLLIE_DURABLE_SOCKET — переменной, которую также читает Collie.

Ещё два параметра существуют только в createCore, но не в openCollie: receipts и allowAlways (Вопросы).

close() намеренно оставляет открытые ask открытыми: остановка не является ответом, и долговечный агент сам решает, что происходит с ожидающей их работой.

tab.pane(id, { title, harness, cwd?, sessionId? }) возвращает панель с этим id, если она существует, чтобы долговечный агент мог показать беседу дважды без создания второй панели. Заголовки усекаются до 256 байт, а harness — до 64. cwd должен быть абсолютным путём, иначе он опускается.

Каждый id следует правилу для id: от 1 до 128 байт, без управляющих символов, без пробелов и без /, ? или #. Недопустимый id возвращает TypeError. Id рабочего пространства или вкладки не может содержать :, так как в протоколе вкладка называется <workspace>:<tab>.

Панели

Панель — это одна беседа, и её методы определяют, что телефон отображает для неё.

У панели также есть четыре поля только для чтения: id, sessionId, turnId (текущий шаг выполнения или последний) и openAsks. Поле icon действия принимает одно из значений: play, pause, check, x, refresh, archive, flag, star, send, note, search и more. При другом имени значок не отображается.

Событие item содержит один элемент с id и необязательным ts. Элемент с известным id заменяет предыдущий на месте.

Элемент reply, thinking, notice или markdown может содержать partial: true, пока его текст увеличивается. Передавайте тот же id по мере роста текста не чаще чем каждые 250 мс, затем ещё один раз с итоговым текстом и без partial, до того как панель покинет working.

Текст сверх лимита обрезается, а управляющие и невидимые символы удаляются. Некорректный lang, некорректный href, некорректный badge или некорректный progress заменяются на TypeError или RangeError, так как Collie отбросил бы их. Долгоживущий агент не может сам добавлять события ask, ask-closed или state: их записывают ask() и state().

Вопросы

pane.ask показывает карточку и возвращает ответ, а requireApproval запрашивает подтверждение для одного вызова инструмента в одну строку.

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) формирует карточку на основе самого вызова, а не на основе слов модели о нём. Заголовок — «refund wants to run», строка инструмента — refund(order: "5521", amount: 40), в push-уведомлении указано «refund needs a yes», а кнопки — Allow и Deny. Возвращает { approved, decidedBy, decidedAt, askId }. Отклонение, тайм-аут, остановка и прерывание возвращают approved: false.

Используются две части, callSummary(name, args) и argumentsView(args): вызов в одну строку и аргументы в виде пар key: value, где каждое значение представлено в JSON.

pane.ask(input) принимает один из четырёх видов. Промис разрешается ответом в форме этого вида.

Каждый вид принимает toolCallId, itemId и title (256 байт). Может принимать reason (2 КиБ), tool, push: { title?, line? } (60 и 120 символов, текст уведомления) и expiresAt (Date или строка ISO 8601 с часовым поясом).

Опустите id. SDK вычисляет его через askIdFor(paneId, toolCallId): SHA-256 от двух id, первые 32 шестнадцатеричных символа. Тот же вызов инструмента, повторённый после перезапуска, получает тот же id, и ответ, отправленный телефоном во время перезапуска, будет доставлен. Повторный вызов с уже открытым id возвращает TypeError.

decidedBy имеет значение phone, program или timeout. Запрос преодолевает свой expiresAt и закрывается с решением от timeout: ask() отклоняется с AskClosed, у которого decidedBy равен timeout. Карточка показывает оставшееся до этого момента время. Запрос, завершившийся по таймауту или разрешённый в durable-агенте, оставляет одну строку в Chat, например: «Timed out before an answer: refund wants to run».

Прерванный signal, pane.close() и закрытие с телефона закрывают запрос с решением от program, а ask() отклоняется с AskClosed.

Внимание. Вариант allow-always пропускает все последующие вызовы после одного ответа. По https токен служит единственной защитой, поэтому durable agent там предлагает только Allow и Deny. createCore с allowAlways: false превращает вариант allow-always в TypeError. Телефон не предлагает allow-always для запроса, слова которого были обрезаны или очищены, либо в котором не указан инструмент.

Каждое действие с телефона содержит request id, и ядро сохраняет квитанцию: повторный вызов ничего не запускает и возвращает первый ответ с replayed: true. Стандартный MemoryReceiptStore хранит самые свежие RECEIPTS_PER_GROUP (1000) для каждой панели, а также для каждой группы для стартеров, переименований, закрытий и повторных открытий. Повтор сброшенного id возвращает 500 receipt-dropped и ничего не запускает. Хранилище сбрасывается вместе с процессом.

Чтобы сохранять квитанции между перезапусками, напишите ReceiptStore с get(requestId) и put(requestId, record, group) и передайте его в createCore как receipts. openCollie всегда хранит их в памяти.

Хуки и история

Хук — это единая точка для действия, отправленного телефоном, а history provider отдаёт вашу собственную историю.

Хук выполняется, только если включён соответствующий cap и его request id ещё не встречался. Отказ ничего не сохраняет, поэтому тот же request id может повторить попытку. Обработчики уровня панели имеют приоритет над хуком. Панель без того и другого отвечает 409 not-supported на отправку, остановку или нажатие.

SDK применяет принятое действие самостоятельно. Переименование задаёт заголовок. Закрытие удаляет цель со всем содержимым и закрывает их открытые запросы как остановленные. Повторное открытие без хука восстанавливает панель, закрытую этим процессом; для беседы, закрытой до перезапуска, требуется onReopen. Разметка создаётся заново при каждом запуске, поэтому durable agent, которому нужно сохранить заголовок или факт закрытия после завершения процесса, сохраняет это в своём хуке.

collie.history(provider) отдаёт все беседы, открытые и закрытые, из собственного хранилища durable agent. Включает cap history, если caps опущен или указывает на history: true.

Строка представляет собой { id, title, subtitle?, workspaceId?, tabId?, startedAt, endedAt?, state, items }, где state имеет значение open или closed, а items указывает количество. Курсор (after, next) — это ваша собственная строка от 1 до 512 байт печатных символов ASCII без пробелов. Отсутствие next завершает список.

Когда провайдер задан, sessionId каждой панели совпадает с её pane id, и история отдаёт под ним беседу панели. Передайте sessionId в tab.pane(), чтобы указать другой id, или null, если он не может оставаться неизменным между перезапусками.

tailLimit — это не история. Это необработанный хвост событий, который каждая панель хранит для чтения событий в Collie, по умолчанию 500 событий. Читатель, отставший от него, получает вместо этого весь текущий снимок панели целиком, не более 2000 самых свежих элементов.

Возможности

Cap указывает, что durable agent умеет выполнять одно действие, а телефон отображает элемент управления только для cap, объявленного durable agent.

Если параметр опущен, caps включает всё, что умеет SDK, а также history, как только у history() появится провайдер. Если указан, он задаёт весь список целиком: неназванное право отключается, поэтому { asks: true } объявляет только запросы. Чтобы отключить одно право и оставить остальные, разверните ALL_CAPS: { ...ALL_CAPS, steer: false }. Маршрут с отключённым правом возвращает 409 not-supported. Значение terminal всегда равно false.

Вспомогательные функции и константы

Корневой импорт также экспортирует части, из которых состоит openCollie, и применяемые им правила.

Каждый тип сетевого протокола и полезная нагрузка каждого хука также экспортируются из src/core/types.ts.

Вспомогательные функции Pi

./pi превращает диалог Pi Durable в панель, вызов рискованного инструмента — в карточку, а хранилище Pi — в историю.

Текст на карточке передаётся через параметры, поэтому ./pi не содержит текста из примера, кроме этих двух констант. Он написан для Pi Durable 1.1.0. Служба поддержки в examples/durable-member/ объединяет все части воедино.

Версии

Пакет имеет собственную версию, независимую от версии Collie, и указывает версию сетевого протокола, с которой он работает.

Collie работает с одной версией сетевого протокола и принимает предыдущую в течение одного минорного релиза после выхода новой. Если Collie не поддерживает ни одну из ваших версий, ядро выводит одну строку через warn, по разу на версию, например collie: Collie speaks wire v2, this durable agent speaks v1. Update the agent's SDK, or Collie. Телефон сообщает о несоответствии на главной странице durable-агента словами самого Collie. Обновите более старую сторону.

Пакет публикуется под npm dist-tag experimental, но никогда под latest. Если сетевой протокол durable будет удалён в выход, пакет объявляется устаревшим (ADR 0105).