Durable agents (экспериментально)

Экспериментальная. Протокол, SDK и эта страница могут измениться, либо возможность может быть удалена в следующем минорном релизе. На данный момент протокол используют только собственные примеры Collie. В Выход описано, от чего зависит сохранение этой возможности. Если не подключать durable-агент, Collie выглядит и работает как раньше.

Если вы создали durable-агент с помощью Pi Durable или любой другой программы, поддерживающей этот протокол, Collie может отобразить его на телефоне. Он получает запросы на подтверждение действий, историю и окно чата без какого-либо кода пользовательского интерфейса.

Durable-агент — один из источников сессия, и каждый его диалог — это одна сессия. Определения приведены в Терминология. Collie не хранит ключи моделей: durable-агент использует собственный API-ключ или вход через ChatGPT, а подписку Anthropic нельзя использовать через сторонние оболочки.

Быстрый старт

Durable-агент из десяти строк, один collie durable attach и карточка с вопросом на телефоне.

Требуется запущенный Collie 1.22.0 или новее на этой машине с привязанным телефоном (Установка).

Durable-агент работает на Linux или macOS с Node 22.19 или новее либо Bun 1.4 или новее. Установите SDK в папку durable-агента:

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

Пакет опубликован под тегом npm dist-tag experimental, но не latest, и следует сценарию отказа из ADR 0104: если протокол durable wire прекращает существование, пакет объявляется устаревшим (ADR 0105).

Точка входа Pi Durable в SDK протестирована с Pi Durable 1.1.0 и 1.2.0. Node 22.19 — минимальная версия для Pi Durable 1.2.0.

Сохраните этот durable-агент как hello.mjs. В нём десять строк:

import { openCollie } from "@colliepwa/durable-sdk";

const socket = process.env.COLLIE_DURABLE_SOCKET ?? `${process.env.XDG_RUNTIME_DIR}/hello/app.sock`;
const collie = await openCollie({ socket, hostName: "hello", caps: { asks: true } });
const pane = collie.workspace("hello", { title: "Hello" }).tab("main", { title: "Questions" }).pane("deploy", { title: "Deploy", harness: "hello" });
collie.ready();
console.log(`listening ${collie.address}`);
const options = [{ id: "yes", label: "Yes" }, { id: "no", label: "No" }];
const answer = await pane.ask({ kind: "choice", toolCallId: "deploy-1", itemId: "deploy-1", title: "Deploy to staging?", options });
console.log(`answer: ${answer.optionIds[0]}`);
await collie.close();

Запустите его с помощью node hello.mjs или bun hello.mjs. Он выведет listening /run/user/1000/hello/app.sock и будет ожидать. Тот же durable-агент находится в examples/durable-member/hello.ts в клоне Collie.

В Node сначала выводится ещё одна строка: Node не может определить, кто подключается к сокету durable-агента, поэтому любой процесс вашего пользователя может ответить на его вопрос. Bun на Linux умеет это и отклоняет ответ от самого durable-агента или от запущенного им процесса.

На macOS запускайте его через Node. Для Bun там требуется callerCheck: "off", который этот durable-агент не задаёт. В macOS нет XDG_RUNTIME_DIR, поэтому сначала задайте абсолютный путь в COLLIE_DURABLE_SOCKET.

Во втором терминале подключите его к Collie, затем перезапустите, чтобы Collie прочитал новую запись:

collie durable attach hello --socket /run/user/1000/hello/app.sock
collie restart

Используйте путь, выведенный durable-агентом. Добавьте --restart к первой команде, чтобы перезапустить за один шаг. --restart перезапускает мост Collie: телефон переподключится через несколько секунд, а сессии терминала продолжат работать.

Откройте Collie на телефоне. В разделе Durable agents появится одна строка, hello, со значком Experimental и одним ожидающим вопросом. Нажмите на строку: откроется список диалогов durable-агента, где ожидает диалог Deploy с вопросом «Deploy to staging?». Откройте его и нажмите Yes или No. Durable-агент выведет ответ и завершит работу.

Чтобы написать собственный durable-агент, прочитайте Durable SDK и Протокол durable wire.

Подключение durable-агента

Каждый durable-агент — это одна запись в sources.json, и collie durable attach записывает её.

collie durable attach desk --socket /run/user/1000/desk/app.sock
export EDGE_TOKEN=your-32-byte-random-token-here
collie durable attach edge --url https://edge.example.com --token-env EDGE_TOKEN
collie restart

В Windows доступен только вариант с HTTPS: attach --socket завершается с кодом 2 и сообщает использовать --url и --token-env, так как приватному сокету требуются идентификаторы пользователей Unix.

sources.json находится в папке конфигурации рядом с .env: в папке конфигурации плагина Herdr (~/.config/herdr/plugins/config/herdr.collie/) при установке под управлением Herdr, иначе ~/.config/collie/. attach выводит записанный путь. Две команды выше создают этот файл:

[
  { "name": "desk", "kind": "durable", "socket": "/run/user/1000/desk/app.sock" },
  {
    "name": "edge",
    "kind": "durable",
    "url": "https://edge.example.com",
    "token": "your-32-byte-random-token-here"
  }
]

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

Collie строго проверяет файл, потому что молча пропущенный durable agent так и не появился бы:

• —
  Поле, не указанное в таблице, останавливает мост. То же самое вызовет неверный kind, имя с нарушением правил, дважды использованное имя, одновременное указание socket и url, отсутствие обоих параметров или url без token.
• —
  Некорректный файл останавливает мост при запуске одной строкой ошибки. Строка начинается с [bridge] FATAL: и указывает запись и поле. collie logs показывает её. attach и detach также отказываются перезаписывать файл, который не могут прочесть, поэтому опечатка не затронет остальные записи.
• —
  Файл сохраняется с правами доступа 0600. attach записывает его именно так. Если у файла более широкие права, мост ограничивает их при запуске и сообщает об этом в логе.
• —
  Имя не может совпадать с именем вашей терминальной сессии. В большинстве установок это default, а на инстансе, работающем только с durable agents, default является именем его собственного durable agent. Мост останавливается при запуске и указывает эту запись.
• —
  Durable agent сохраняет своё имя при совпадении с сессией Herdr. Если сессия Herdr называется так же, как durable agent, телефон показывает durable agent, скрывает эту сессию Herdr, и лог сообщает об этом один раз.

attach проверяет путь к сокету, URL и токен по правилам ниже. Запись, сделанная вручную, проверяется при обращении моста к durable agent: в случае нарушения durable agent помечается как недоступный с указанием причины.

Два способа связи с durable agent

Транспорт через сокет предназначен для Linux и macOS. В Windows используйте URL и токен. Путь к сокету должен быть абсолютным и не длиннее 103 байт. Держите его в $XDG_RUNTIME_DIR, а не в /tmp: сервис Collie в Linux запускается с изолированным /tmp.

Collie подключается к сокету только тогда, когда весь путь является приватным, поскольку сокет не передаёт токен. Сокет принадлежит вам без прав для группы и остальных пользователей. Его каталог принадлежит вам с правами доступа 0700. Никакая часть пути не является симлинком, и ни один вышестоящий каталог не доступен для записи группе или остальным, кроме каталогов со sticky bit, таких как /tmp. SDK создаёт каталог сокета с правами доступа 0700, если он отсутствует.

URL должен начинаться с https://. Единственное исключение: http://127.0.0.1:<port> или http://localhost:<port> с портом для durable agent на той же машине. Collie отклоняет любые другие адреса http://, поскольку токен передавался бы по сети без шифрования.

Внимание. При работе через https токен остаётся единственной защитой. Любой обладатель токена может читать все диалоги и отвечать на любые вопросы, а хост видит этот текст. Durable agent, доступный таким способом, должен предлагать только Allow и Deny и никогда не использовать постоянное разрешение.

Безопасность durable agents определяет, что может делать durable agent и что фиксирует Collie.

Каждый опрос по https — это запрос, который ваш хостинг может тарифицировать, и ответ об отсутствии изменений тоже учитывается. Без открытого телефона опрос в фоновом режиме происходит каждые 10 с, то есть Collie делает 8 640 запросов в день. Проверьте условия вашего тарифа на хостинге.

Durable agent за URL должен поддерживать протокол Collie и проверять bearer-токен. Стандартное демо Pi Durable не делает ни того, ни другого, поэтому Collie не может подключить его в исходном виде.

Collie опрашивает размещённый на хостинге durable agent. Опрос выполняется каждые 2 с при активном телефоне, иначе — каждые 10 с. Каждый опрос будит находящийся в спящем режиме Durable Object, поэтому размещённый объект остаётся активным, пока открыт Collie. Протокол не использует WebSocket, поэтому функции гибернации и WebSocket в Durable Objects здесь не помогают.

Пример для Cloudflare законсервирован и не входит в релиз. Он находится в experiments/durable-member-cloudflare/.

Три глагола

attach, detach и list изменяют или читают sources.json и ничего не перезапускают без явного запроса.

collie durable attach <name> --socket <path> [--restart]
collie durable attach <name> --url <url> --token-env <VAR> [--restart]
collie durable detach <name> [--restart]
collie durable list

collie durable без команды или с неизвестной командой выводит справку и завершается с кодом 2. С --restart команды attach и detach выполняют такой же перезапуск, как и collie restart.

list опрашивает запущенный мост о каждой записи и ждёт ответа не более 3 с:

Если durable agent не появляется, выполните collie doctor, которая укажет на непройденную проверку. Три типичные причины: запись ещё не загружена (перезапустите), сокет не является приватным (socket-not-private) или остался устаревший файл сокета после сбоя (connection refused: удалите его и запустите durable agent). Устранение неполадок durable agent описывает случаи с durable agent. Устранение неполадок относится к Collie в целом.

Токены

Запись url содержит свой токен, и этот токен — единственная защита.

openssl rand -hex 32

Результат состоит из 64 шестнадцатеричных символов, что превышает нижний порог в 32 байта.

Сделайте токен длиной не менее 32 случайных байт, как указано выше, и передайте durable agent то же значение. attach считывает его из переменной, указанной в --token-env, поэтому токен не попадает в командную строку и историю оболочки. Эта переменная должна быть задана при запуске attach.

attach копирует значение в sources.json в открытом виде. Поэтому файл требует такой же секретности, как и сам токен: Collie хранит его с правами доступа 0600, а резервная копия или синхронизация папки конфигурации переносит токен. Collie отправляет токен с каждым запросом и никогда не выводит его: list сообщает (token set).

Срок действия токена не ограничен. Чтобы изменить его, повторно выполните attach с тем же именем и новым токеном, затем перезапустите:

export EDGE_TOKEN=your-new-32-byte-random-token-here
collie durable attach edge --url https://edge.example.com --token-env EDGE_TOKEN
collie restart

attach выводит updated edge. Передайте durable agent новый токен до перезапуска Collie, иначе телефон сообщит, что durable agent отклонил токен. Durable agent может принимать второй токен во время ротации, чтобы ни одна из сторон не потеряла доступ. В примере с припаркованным Cloudflare принимаются COLLIE_TOKEN и, пока она задана, COLLIE_TOKEN_NEXT (ADR 0103). Укажите новый токен как COLLIE_TOKEN_NEXT на durable agent, повторно выполните attach и перезапустите Collie, затем переместите значение в COLLIE_TOKEN и сбросьте COLLIE_TOKEN_NEXT.

Один durable agent в одном экземпляре Collie

Экземпляр без терминала, такой как хост Windows или размещённый durable agent, может управлять одним durable agent из своего .env.

# a durable agent on this machine, as you
COLLIE_MUX=durable
COLLIE_DURABLE_SOCKET=/run/user/1000/durable/session.sock

# or a durable agent you deployed behind TLS
COLLIE_MUX=durable
COLLIE_DURABLE_URL=https://durable-member.example.com
COLLIE_DURABLE_TOKEN=your-32-byte-random-token-here

Такой экземпляр называет своего durable agent default, и этот durable agent служит его основной сессией. Записи в sources.json по-прежнему работают параллельно с ним под другими именами.

Укажите сокет или URL с токеном, но ни в коем случае не оба сразу. Указание обоих параметров, URL без токена или токена без URL считается ошибкой конфигурации: Collie запустится, запишет ошибку в лог и покажет durable agent как недоступный с указанием этой причины.

В более старой сборке логи экземпляра, работающего только в режиме durable, хранились прямо в <state>/durable/. При первом запуске этой сборки они один раз переносятся в durable/default/ с записью одной строки в лог.

Чтобы сменить токен, разверните новый токен на durable agent, укажите его в .env и выполните collie restart. Экземпляр, работающий только в режиме durable, подключается к crew под своим именем хоста, поэтому задайте ему имя с помощью collie crew join <lead-address> --label durable, если он находится на одном хосте с lead.

Чтобы временно отключить все durable agent из sources.json, задайте COLLIE_PROGRAMS=off в .env и выполните collie restart. Тогда мост проигнорирует файл, запишет одну строку в лог и запустится как установка без durable agent, поэтому на телефоне не будет раздела Durable agents. collie doctor и collie durable list сообщают, что durable agent выключены. Файл остаётся без изменений: удалите переменную и перезапустите сервис, чтобы вернуть durable agent. Переменная не влияет на старый формат переменных окружения, описанный выше.

Где Collie хранит данные durable agent

Durable agent хранит историю своих разговоров. Collie хранит кэш, квитанции и память push-уведомлений в своей папке состояния.

Папка состояния: ~/.local/state/collie/ или COLLIE_STATE_DIR, если эта переменная задана. <program> — это имя в sources.json или default. Папка каждого durable agent имеет права доступа 0700, а каждый лог — права 0600.

Благодаря кэшу Chat открывается быстро и работает, даже когда durable agent медлит. Закрытый разговор всегда считывается из durable agent, а не из кэша.

Durable agent сохраняет только самую свежую часть длинного разговора. Если он удалил начало разговора до того, как Collie успел его прочитать, Chat выводит вместо него одну строку: «Older messages were left out: the durable agent no longer keeps them.» На вашем телефоне ничего не пропало: у Collie этих сообщений никогда не было.

Что показывает телефон

Раздел Durable agents на панели управления, а для каждого durable agent — список его разговоров.

Каждый durable agent занимает одну строку в разделе Durable agents, где отображаются его имя, значок Experimental, среда выполнения и признак того, запущен ли он здесь или в другом месте. Справа показано количество его открытых разговоров и цветом needs-you выделены те, которые ждут ваших действий. Пока вопрос ожидает ответа, этот раздел поднимается выше ваших пространств. Durable agent, который запускается или недоступен, сообщает об этом вместо счётчиков. Для отклонённого токена и неподдерживаемой версии протокола на телефоне выводятся свои сообщения; collie doctor сообщает о любой другой причине.

Нажмите на строку, чтобы открыть список разговоров durable agent, похожий на список чатов в мессенджере. Сначала отображается то, что ждёт ваших действий, затем остальные открытые разговоры, а после них — закрытые под меткой Closed. Открытый разговор загружается в Chat, а закрытый доступен только для чтения. Durable agent в приветственном сообщении сообщает, что он умеет делать (asks, starters, send, steer, abort, rename, close, actions, history, reopen), и телефон отрисовывает элементы управления только для заявленных возможностей. У durable agent нет экрана, поэтому у него нет режима Terminal и ввода с клавиатуры.

При отправке durable agent метка queued — это собственная трактовка очереди со стороны Collie. Collie не показывает, что ожидает во входящих у Pi. Задача, которая ожидает наступления дедлайна, отображается как idle или working, но никогда как waiting. Подробности см. в Сессии.

Карточка вопроса указывает имя durable agent и показывает оставшееся время, если durable agent установил таймер. Вопрос, решённый внутри durable agent или закрытый по таймауту, оставляет строку в чате. Durable agents на телефоне показывает каждый вариант на рисунке.

Send и Ask через мост

У durable agent нет экрана, поэтому Collie не читает для него экран. Вместо этого мост читает собственное состояние. Durable agent получает те же Send и Ask, что и панель терминала.

• —
  Состояние. Очередь хода берётся из состояния панели. Вопрос берётся из самого старого открытого ask. Поле ввода всегда пустое, потому что у durable agent нет поля ввода. Телефон получает это состояние с каждой панелью в том же формате, что и для панели терминала.
• —
  Отправка. POST /api/send принимает request id с телефона. Мост записывает запрос на диск и блокирует беседу. Затем он один раз отправляет текст в durable agent для прочитанного хода. Ответ служит подтверждением, а квитанция указывает принятый request id. Во время хода durable agent сохраняет текст на потом, и в квитанции указано queued.
• —
  Результаты. Отправка завершается со статусом sent, refused с указанием причины или unknown. unknown означает, что durable agent не подтвердил приём текста. Прочитайте чат перед повторной отправкой. Отправка переходит в статус effective, когда durable agent записывает её в беседу. Элемент user указывает request id этой отправки. Обычная отправка отклоняется, пока открыт любой вопрос, даже тот, который Collie не может прочитать. Ответьте на вопрос или используйте Steer или Stop. Ход, начавшийся после вашего просмотра, отклоняет отправку, и текст не доходит до durable agent.
• —
  Вопрос. POST /api/ask/<id> отвечает на него. Идентификатор ask id предназначен только для однократного использования. Ответ содержит хеш вопроса, который вы видели. Мост сравнивает его с вопросом, который durable agent возвращает сейчас. Если они не совпадают, durable agent ничего не получает. Ответ моста показывает вопрос в текущем виде. Ответ уходит в durable agent по его собственному ask id. Никакие ключи не передаются. Квитанция содержит channel: program и сохраняет хеш.
• —
  Что остаётся на карточке. Некоторые вопросы не подходят под одно нажатие, поэтому состояние показывает их как вопрос, который Collie не может прочитать (modal: unreadable). Вы отвечаете на них на отдельной карточке. - Текстовый вопрос остаётся на карточке durable agent, так как ответом служит вводимая строка. - Выбор нескольких вариантов остаётся на карточке durable agent, так как ответом служит больше одного пункта. - Форма остаётся на карточке durable agent, так как ответом служит набор полей. - Вариант «Всегда разрешать» не входит в контракт. Его действие продолжается после этого вопроса. Поэтому карточка durable agent сначала требует второе нажатие, и одно нажатие через /api/ask не должно его пропускать.
• —
  Счётчики. collie doctor подсчитывает эти чтения и результаты в одной строке, program.

На этой машине телефон использует следующие маршруты. Обычная отправка идёт через /api/send, а нажатие на карточке вопроса идёт через /api/ask. Поле ввода показывает результат под пальцем словами durable agent. Когда вопрос блокирует отправку, кнопка ведёт на его карточку. Список Recent sends панели показывает каждую квитанцию, а для отправки в очереди указывает соответствующий статус. Steer и Stop остаются на собственных маршрутах беседы, так как steer не входит в Send Protocol. Durable agent на crew member сохраняет собственные маршруты беседы для всех записей. Каждый маршрут проверяет ход до того, как текст дойдёт до durable agent. Все операции записи в одну беседу используют одну блокировку. Пока выполняется отправка, Steer и ответ на карточке отклоняются из-за занятости. Stop ожидает блокировку максимум до своего лимита времени, поэтому зависшая отправка не заблокирует Stop.

Версии

Collie и durable agent согласовывают сетевую версию протокола при рукопожатии hello; на сегодняшний день существует одна версия: версия 1.

Collie использует 1..1. Когда выйдет версия 2, Collie продолжит поддерживать версию 1 в течение одного минорного релиза, а следующий минорный релиз удалит её. Сейчас предыдущих версий для поддержки нет.

Если диапазоны не пересекаются, Collie больше ничего не читает из durable agent. В его журнал добавляется по одной строке на каждый отклонённый диапазон, например [durable] The durable agent speaks wire v2, this Collie speaks v1. Update Collie, or the agent's SDK.. Главный экран durable agent на телефоне показывает ту же фразу в блоке предупреждения, а его строка на дашборде показывает Version mismatch вместо Unreachable. collie doctor показывает оба диапазона в строке durable-hello: incompatible: the durable agent speaks 2..3, this Collie speaks 1..1. Один раз за запуск durable agent Collie также отправляет ему один hello со своей версией, чтобы durable agent мог зафиксировать несовпадение в своём журнале. Обновите более старую сторону.

Выход

Функция останется только в том случае, если ей пользуется кто-то за пределами этого репозитория.

К релизу 1.24.0 должно выполняться хотя бы одно из двух условий: существует публичный репозиторий с поддержкой этого сетевого протокола либо существует внешний issue или discussion о durable agent. Если ни того, ни другого нет, код durable удаляется из релиза в experiments/, а эта страница удаляется (ADR 0104). При удалении запись sources.json игнорируется с одной строкой в журнале на протяжении одного релиза, сокет продолжает работать для вашего durable agent, а пакет npm помечается устаревшим, но не удаляется (ADR 0105).