durable SDK（実験的機能）

実験的。 パッケージ、API、使用されるプロトコルは、今後のマイナーリリースで変更されるか、機能が削除される可能性があります。durable agentへの影響についてはバージョンを参照してください。

@colliepwa/durable-sdkは、durable agentがCollieを介してスマートフォン上に表示されるために使用するnpmパッケージです。このページでは、そのすべての構成要素を一覧で示します。durable agentにはクイックスタートとCollie側のセットアップ手順があり、durable wireでは両者間で送受信されるデータについて説明しています。

インストールとエントリ

1回インストールすると、ほとんどのdurable agent向けルートインポートと、特定の用途向けの4つのエントリの計5つのエントリが利用可能になります。

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 でテストされています。これら3つはオプショナルの peer dependencies であり、./pi をインポートしない durable agent には何もインストールされません。

ランタイムは、durable agent が応答者を判別できるかどうかを決定します。子孫プロセスのチェックは、durable agent 自身またはそれが起動したプロセスからの操作を拒否し、403 caller-refused を返します。これには answer、send、stop、action、rename、close、reopen、starter が含まれます。読み取り操作は継続して許可されます。

このチェックがない場合、エージェントが実行するツールを含め、同一ユーザーのすべてのプロセスがカードに応答できるようになります。エージェントのツールは、ソケットにアクセスできないサンドボックス内で実行してください。ソケットにはファイルの所有権を扱えるシステムが必要なため、Windows では openCollie が起動時に停止します。Windows 上の durable agent は、代わりにトークン付きの TLS の背後で ./core を配信します（durable agentへ接続する2つの方法）。

接続を開く

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 も読み取る変数 COLLIE_DURABLE_SOCKET から取得されます。

openCollieにはなく、createCoreにのみ存在するオプションがさらに2つあります: receiptsおよびallowAlways (質問)。

close()は未解決のaskを意図的に開いたままにします。シャットダウンは応答ではないため、その結果を待つ処理の扱いは永続エージェントが決定します。

tab.pane(id, { title, harness, cwd?, sessionId? })は、該当するIDのペインが存在する場合はそれを返します。これにより、永続エージェントはペインを重複して作成することなく会話を再表示できます。タイトルは256バイト、harnessは64バイトに切り詰められます。cwdは絶対パスである必要があり、そうでない場合は除外されます。

すべてのIDはID規則に従います: 1〜128バイト、制御文字なし、空白文字なし、/、?、#のいずれも不可。不正なIDはTypeErrorとなります。プロトコル上でタブが<workspace>:<tab>と命名されるため、ワークスペースやタブのIDに:を含めることはできません。

ペイン

ペインは1つの会話であり、そのメソッドによって電話側に表示される内容を設定します。

ペインには読み取り専用の4つのフィールドもあります: id、sessionId、turnId (実行中のターン、または最後のターン)、openAsks。アクションのiconは、play、pause、check、x、refresh、archive、flag、star、send、note、search、moreのいずれかです。それ以外の名前ではアイコンは描画されません。

itemイベントは、idと任意のtsを持つアイテムを1つ含みます。既存のIDを持つアイテムは、その場で前のアイテムと置き換えられます。

reply、thinking、notice、またはmarkdownのアイテムは、テキストの追加中にpartial: trueを含めることができます。テキストの増加に伴い、最短250ミリ秒ごとに同じIDを再書き込みし、ペインがworkingを離れる前に、最終テキストを含めpartialを付けずに再度書き込みます。

上限を超えたテキストは切り詰められ、制御文字や不可視文字は削除されます。Collieによって破棄されるため、不正なlang、不正なhref、不正なバッジ、または不正な進捗状況は、代わりにTypeErrorまたはRangeErrorになります。常駐エージェントはask、ask-closed、またはstateイベントを自身で追加することはできません。これらはask()とstate()が書き込みます。

質問

pane.askはカードを表示して回答を返し、requireApprovalは1回のツール呼び出しについて1行で問い合わせます。

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を返します。

使用する2つの要素は callSummary(name, args) と argumentsView(args) です。呼び出しを1行で表し、引数は各値をJSONとする key: value ペアで表します。

pane.ask(input) には4つの種類のいずれかを指定します。promiseは、その種類に応じた形式の回答で解決されます。

すべての種類で toolCallId、itemId、title（256バイト）を受け取ります。また、reason（2 KiB）、tool、push: { title?, line? }（通知の文面、60文字と120文字）、expiresAt（Date またはタイムゾーン付きISO 8601文字列）を受け取ることもできます。

id は省略してください。SDKが askIdFor(paneId, toolCallId) を使ってこれを導出します。2つのIDに対するSHA-256の先頭32文字の16進数です。そのため、再起動後に同じツール呼び出しが再度発生しても同じIDが割り当てられ、再起動を挟んでスマートフォンから送信された回答も正しく届きます。すでに開いているIDを再度発生させると TypeError になります。

decidedBy は phone、program、timeout のいずれかです。askが expiresAt を過ぎると、timeout による決定として閉じられます。ask() は AskClosed で拒否され、その decidedBy は timeout になります。カードにはそれまでの残り時間が表示されます。タイムアウトしたか、durable agent内で決定された質問は、Chatに「回答前にタイムアウトしました: refund を実行しようとしています」のような1行を残します。

中断された signal、pane.close()、およびスマートフォンからのクローズによって、askは program による決定として閉じられ、ask() は AskClosed で拒否されます。

注意。 allow-always オプションを使うと、1回の回答でそれ以降のすべての呼び出しが通過するようになります。https経由ではトークンのみが保護手段となるため、そこでのdurable agentは「許可」と「拒否」のみを提供します。createCore で allowAlways: false を指定すると、allow-always オプションは TypeError になります。文面が切り詰められたりクリーンアップされたask、またはツール名が指定されていないaskに対しては、スマートフォンは allow-always を表示しません。

スマートフォンからの各操作にはリクエストIDが付与され、コアはその受領記録を保持します。重複実行は行われず、replayed: true とともに初回と同じ応答を返します。デフォルトの MemoryReceiptStore は、ペインごと、またstarter、名前変更、閉じる、再度開く操作のグループごとに最新の RECEIPTS_PER_GROUP 件（1000件）を保持します。破棄されたIDが再送信された場合は 500 receipt-dropped を返し、何も実行しません。プロセスが終了するとストアは破棄されます。

再起動後も受領記録を維持するには、get(requestId) と put(requestId, record, group) を実装した ReceiptStore を作成し、createCore に receipts として渡します。openCollie はこれらを常にメモリ上に保持します。

フックと履歴

フックはスマートフォンから送られる操作を処理する名前付きエンドポイントであり、history providerは独自に保持する履歴を提供します。

フックは、対応するcapが有効で、リクエストIDが新規の場合にのみ実行されます。拒否された場合は何も保存されないため、同じリクエストIDで再試行できます。ペイン個別のハンドラはフックよりも優先されます。どちらも設定されていないペインへの送信、停止、タップ操作には 409 not-supported が返されます。

SDKは承認された操作を自ら適用します。名前変更ではタイトルを設定します。閉じる操作では対象とその内部のすべてを削除し、未解決の問い合わせを停止状態として閉じます。フックなしで再度開く操作は、現在のプロセスが閉じたペインを復元します。再起動前に閉じられた会話には onReopen が必要です。レイアウトは起動ごとに再構築されるため、タイトルや閉じた状態をプロセス終了後も保持したいdurable agentは、フック内でそれを保存します。

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となり、履歴はそのIDのもとでペインの会話を提供します。別のIDを指定する場合は sessionId を tab.pane() に渡し、再起動をまたいで維持できない場合は null を渡します。

tailLimit は履歴ではありません。Collieのイベント読み取り用に各ペインが保持する生の末尾データであり、デフォルトで500イベントです。追いつけなくなったリーダーは、代わりにペインの現在のビュー全体（最新の最大2000アイテム）を取得します。

機能一覧

capはdurable agentが対応可能な機能を示します。スマートフォンは、durable agentが宣言したcapに対するコントロールのみを描画します。

省略した場合、capsはSDKの全機能を有効化し、history()にプロバイダが設定されるとhistoryも有効化します。指定した場合、それが全リストとなります。記載のない機能は無効になるため、{ asks: true }はaskのみを宣言します。1つだけ無効にして残りを保持するには、ALL_CAPSを展開してください: { ...ALL_CAPS, steer: false }。機能が無効化されたルートは409 not-supportedを返します。terminalは常にfalseです。

ヘルパーと定数

ルートのインポートからは、openCollieを構成するパーツや、適用されるルールもエクスポートされます。

すべてのワイヤタイプとフックペイロードもsrc/core/types.tsからエクスポートされます。

Pi ヘルパー

./piは、Pi Durableの会話をペインに、危険なツール呼び出しをカードに、Piのストアを履歴に変換します。

カードに表示される文言はオプションとして渡されるため、./piにはそれら2つの定数以外のサンプルテキストは含まれません。Pi Durable 1.1.0向けに記述されています。examples/durable-member/のサポートデスクがすべてのパーツを統合します。

バージョン

このパッケージにはCollieとは別の独自バージョンがあり、対応するワイヤバージョンを指定します。

Collieは1つのワイヤバージョンに対応し、新しいバージョンがリリースされた後の1マイナーリリースの間は1つ前のバージョンも受け入れます。Collieがいずれのバージョンにも対応していない場合、コアはwarn経由でバージョンごとに1行（例: 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）。