持久 SDK（实验性）

实验性功能。 该软件包、其 API 以及它所使用的传输协议可能会在后续次要版本中发生变更，该功能也可能会被移除。版本 说明了这对你的 durable agent 意味着什么。

@colliepwa/durable-sdk 是 durable agent 用来通过 Collie 在手机上展示自身的 npm 软件包。本页列出了它的所有组成部分。持久 agent 提供了快速上手指南以及 Collie 端的设置，durable 线路 解释了两者之间传输的内容。

安装与入口

一次安装提供五个入口：适用于大多数 durable agent 的根导入，以及适用于更特殊需求的四个入口。

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

该包需要 Node 22.19 或更高版本，或 Bun 1.4 或更高版本，且没有运行时依赖。./pi 需要 @earendil-works/pi-durable、@earendil-works/pi-ai 和 @earendil-works/chord，版本需为 1.1 或更高且低于 2。入口文件已在 Pi Durable 1.1.0 和 1.2.0 上测试。这三个包为可选对等依赖：从不导入 ./pi 的 durable agent 无需安装任何一个。

运行时决定 durable agent 能否判断应答者身份。后代检查会拒绝来自 durable agent 本身或其启动进程的操作，返回 403 caller-refused。它涵盖 answer、send、stop、action、rename、close、reopen 和 starter。读取操作保持打开状态。

如果不进行检查，当前用户的任何进程都可以应答卡片，包括 agent 运行的工具。请在无法访问套接字的沙箱中运行 agent 的工具。该套接字需要支持文件所有者的系统，因此在 Windows 上 openCollie 会在启动时停止。在 Windows 上，durable agent 改为在 TLS 后通过令牌提供 ./core 服务 (访问 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：关机并不算作回复，由持久化 agent 决定如何处理等待该 ask 的工作。

存在对应 ID 的窗格时，tab.pane(id, { title, harness, cwd?, sessionId? }) 会返回该窗格，因此持久化 agent 无需第二个窗格即可将同一会话显示两次。标题截断至 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 毫秒一次），并在窗格离开 working 之前，以不带 partial 的最终文本再次写入一次。

超出限制的文本会被截断，控制字符和不可见字符会被移除。无效的 lang、无效的 href、无效的徽章或无效的进度会被改为 TypeError 或 RangeError，因为 Collie 会将其丢弃。durable agent 本身不得追加 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)，推送提示为“refund needs a yes”，按钮为 Allow 和 Deny。它返回 { approved, decidedBy, decidedAt, askId }。拒绝、超时、停止和中止均返回 approved: false。

callSummary(name, args) 和 argumentsView(args) 是它使用的两个部分：单行的调用信息，以及作为 key: value 键值对的参数，每个值均为 JSON。

pane.ask(input) 接受四种类型之一。Promise 会解析为对应类型结构的结果。

每种类型均接受 toolCallId、itemId 和 title（256 字节）。还可以接受 reason（2 KiB）、tool、push: { title?, line? }（60 和 120 个字符，通知文本）以及 expiresAt（Date 或带时区的 ISO 8601 字符串）。

省略 id。SDK 会通过 askIdFor(paneId, toolCallId) 推导该值：对两个 ID 计算 SHA-256 并取前 32 个十六进制字符。因此重启后再次发起的相同工具调用会获得相同 ID，手机在重启期间发送的回答也能正确送达。发起一个已处于打开状态的 ID 会返回 TypeError。

decidedBy 为 phone、program 或 timeout。询问超过其 expiresAt 后会关闭，判定结果为 timeout：ask() 拒绝并抛出 AskClosed，其 decidedBy 为 timeout。卡片显示截止前的剩余时间。超时或在持久化 agent 中决定的问题会在 Chat 中留下一行内容，例如“超时未回答：refund 想要运行”。

中止的 signal、pane.close() 以及手机端的关闭操作都会关闭该询问，判定结果为 program，且 ask() 拒绝并抛出 AskClosed。

注意。 带有 allow-always 的选项在回答一次后会放行后续的所有调用。在 https 下，token 是唯一的校验屏障，因此持久化 agent 在此时仅提供“允许”和“拒绝”。带有 allowAlways: false 的 createCore 会使 allow-always 选项变为 TypeError。对于文本被截断、清理，或者未指定工具名称的询问，手机端不会提供 allow-always。

手机端发起的每个动作都带有请求 ID，核心层会保留其回执：重复请求不会执行任何操作，而是直接返回第一次的回复并带有 replayed: true。默认的 MemoryReceiptStore 会为每个窗格保留最新的 RECEIPTS_PER_GROUP（1000 个），并为启动项、重命名、关闭和重新打开操作按组保留相应数量。若重复请求已被丢弃的 ID，则会收到 500 receipt-dropped 且不执行任何操作。该存储会随进程一起消失。

若要在重启后保留回执，请编写一个包含 get(requestId) 和 put(requestId, record, group) 的 ReceiptStore，并将其作为 receipts 传给 createCore。openCollie 始终将其保存在内存中。

钩子与历史记录

hook 是承接手机端所发送动作的唯一具名入口，history provider 则用于提供你自己的记录。

hook 仅在其对应 cap 处于开启状态且请求 ID 为全新时才会运行。拒绝请求不会存储任何内容，因此相同的请求 ID 可以再次尝试。窗格专属的 handler 优先级高于 hook。两者均未配置的窗格在收到发送、停止或点击操作时，会回复 409 not-supported。

SDK 会自行应用已被接受的动作。重命名操作会设置标题。关闭操作会移除目标及其内部的所有内容，并将其未完成的请求按已停止状态关闭。在没有 hook 的情况下，重新打开操作会恢复当前进程关闭的窗格；在重启前关闭的会话则需要 onReopen。界面布局在每次启动时都会重新生成，因此如果 durable agent 希望标题或关闭状态在进程退出后继续保留，应将其存储在自己的 hook 中。

collie.history(provider) 会从 durable agent 自身的存储中提供所有已打开和已关闭的会话。当省略 caps 或指定为 history: true 时，它会开启 history cap。

一行对应 { id, title, subtitle?, workspaceId?, tabId?, startedAt, endedAt?, state, items }，其中 state 为 open 或 closed，items 为数量。游标（after、next）为你自定义的字符串，由 1 到 512 字节的不含空格的可打印 ASCII 字符组成。缺少 next 即表示列表结束。

设置 provider 之后，每个窗格的 sessionId 即为其窗格 ID，history 会在该 ID 下提供该窗格的会话。向 tab.pane() 传入 sessionId 可以指定其他 ID，如果在重启后无法保持相同则传入 null。

tailLimit 不是 history。它是每个窗格为 Collie 读取事件保留的原始末尾记录，默认保留 500 个事件。落后于该记录的读取端将转而获取该窗格当前的完整视图，最多为最新的 2000 个条目。

能力集 (Caps)

cap 表示 durable agent 具备执行某项操作的能力，手机端仅会针对 durable agent 声明过的 cap 绘制对应控件。

若省略，caps 会启用 SDK 能执行的所有功能，且一旦 history 拥有 provider 也会启用 history()。若指定，则为完整列表：未列出的 cap 会被关闭，因此 { asks: true } 仅声明 ask。若要关闭某项并保留其余项，请展开 ALL_CAPS：{ ...ALL_CAPS, steer: false }。cap 已关闭的路由会返回 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 agent 主页上用 Collie 自己的提示语说明不匹配情况。请更新较旧的一方。

该软件包发布在 npm dist-tag experimental 下，绝不会发布为 latest。如果 durable 有线协议弃用并停留在 退出，该软件包将被弃用（ADR 0105）。