durable agent（実験的機能）

実験的。 ワイヤー、SDK、およびこのページは変更される可能性があり、今後のマイナーリリースで機能が削除される場合があります。現在、このワイヤーに対応しているのはCollie自身のサンプルのみです。残るかどうかを判断する基準については出口を参照してください。durableエージェントをアタッチしない場合、Collieの見た目と動作は以前のままです。

Pi Durableまたはワイヤーを提供するプログラムでdurableエージェントを構築した場合、Collieはそれをスマートフォン上に表示できます。UIコードを一切書かずに、承認プロンプト、履歴、チャットビューを利用できます。

durable agentはsessionの提供元のひとつであり、その各会話が1つのセッションになります。用語の定義は用語集にあります。CollieはモデルのAPIキーを保持しません。durable agentは自身独自のAPIキーまたはChatGPTログインを使用し、Anthropicのサブスクリプションをサードパーティ製ハーネス経由で使用することはできません。

クイックスタート

10行のdurable agent、1つのcollie durable attach、そしてスマートフォン上の質問カード。

このマシンでCollie 1.22.0以降が実行されており、スマートフォンがペアリングされている必要があります（インストール）。

durable agentはLinuxまたはmacOS上で動作し、Node 22.19以降またはBun 1.4以降が必要です。durable agentのフォルダーにSDKをインストールします。

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

このパッケージはnpmのdist-tag experimentalで公開されており、latestでは公開されません。また、ADR 0104の終了方針に従います。durable wireが廃止されると、パッケージも非推奨になります（ADR 0105）。

SDKのPi Durableエントリは、Pi Durable 1.1.0および1.2.0でテストされています。Node 22.19はPi Durable 1.2.0の最小要件です。

このdurable agentをhello.mjsとして保存します。コードは10行です。

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 agentは、Collieのクローン内ではexamples/durable-member/hello.tsにあります。

Node環境では、最初にもう1行出力されます。Nodeはdurable agentのソケットへの接続元を特定できないため、同一ユーザーの任意のプロセスがその質問に回答できます。Linux上のBunは接続元を特定できるため、durable agent自身やその起動プロセスからの回答を拒否します。

macOSではNodeで実行してください。macOS上のBunにはcallerCheck: "off"が必要ですが、このdurable agentでは設定していません。macOSにはXDG_RUNTIME_DIRがないため、事前にCOLLIE_DURABLE_SOCKETを絶対パスに設定してください。

2つ目のターミナルでCollieにアタッチし、Collieを再起動して新しいエントリを読み込ませます。

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

durable agentが出力したパスを使用してください。最初のコマンドに--restartを追加すると、同じステップで再起動できます。--restartを実行するとCollieブリッジが再起動します。スマートフォンは数秒で再接続され、ターミナルセッションはそのまま継続します。

スマートフォンでCollieを開きます。「Durable agents」セクションに1行（hello）が表示され、「Experimental」バッジと1件の待機中メッセージが表示されます。この行をタップすると、durable agentの会話リストが開き、「Deploy」という会話で「Deploy to staging?」が待機しています。それを開いて「Yes」または「No」をタップします。durable agentは回答を出力して終了します。

独自のdurable agentを作成するには、durable SDKとdurable wireを参照してください。

durable agentのアタッチ

各durable agentはsources.json内の1つのエントリであり、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形式のみ利用可能です。プライベートソケットにはUnixユーザーIDが必要なため、attach --socketは終了コード2で失敗し、--urlと--token-envを使用するよう案内します。

sources.jsonは.envと同じ設定フォルダーに配置されます。Herdr管理下のインストールの場合はHerdrプラグイン設定フォルダー（~/.config/herdr/plugins/config/herdr.collie/）、それ以外は~/.config/collie/です。attachは書き込んだパスを出力します。上記の2つのコマンドは以下のファイルを書き込みます。

[
  { "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 agentと並んで、これまでどおり表示され動作します。

Collieはこのファイルに対して厳格です。durable agentを暗黙のうちにスキップすると、そのエントリが一切表示されなくなるためです。

• —
  テーブルに定義されていないフィールドがあると、ブリッジは停止します。 不正なkind、命名規則違反、重複した名前、socketとurlの同時指定、どちらも未指定、あるいはtokenのないurlでも同様です。
• —
  ファイルに問題がある場合、ブリッジは起動時に1行のエラーを出して停止します。 該当行は[bridge] FATAL:で始まり、エントリ名とフィールド名を示します。collie logsで確認できます。attachとdetachも、読み取れないファイルの上書きを拒否するため、タイポによって他のエントリが失われることはありません。
• —
  ファイルはモード0600で保持されます。 attachはこのパーミッションで書き込みます。ファイルのパーミッションがこれより緩い場合、ブリッジは起動時にパーミッションを絞り込み、ログにその旨を記録します。
• —
  ターミナルセッションと同じ名前は使用できません。 ほとんどの環境ではdefaultが該当し、durable専用インスタンスではdefaultが自身のリバースプロキシ用durable agent名となります。ブリッジは起動時に停止し、該当エントリ名を出力します。
• —
  Herdrセッションと名前が重複した場合、durable agentの名前が優先されます。 Herdrセッションの名前がdurable agentと重複している場合、スマートフォン側にはdurable agentが表示されてHerdrセッションは隠蔽され、ログに一度だけその旨が出力されます。

attachは、以下の規則に従ってソケットパス、URL、トークンを検証します。手動で記述されたエントリは、ブリッジがdurable agentに到達した時点で検証されます。規則違反がある場合、durable agentは到達不能として理由とともに表示されます。

durable agentへ接続する2つの方法

ソケット通信はLinuxとmacOS用です。WindowsではURLとトークンを使用してください。ソケットパスは絶対パスで、最大103バイトにする必要があります。/tmpではなく$XDG_RUNTIME_DIR配下に配置してください。Linux上のCollieサービスはプライベートな/tmpで実行されるためです。

ソケットにはトークンが含まれないため、Collieはパス全体がプライベートな場合にのみソケットへ接続します。ソケットの所有者はユーザー自身であり、グループや他のユーザーの権限があってはなりません。ディレクトリもユーザー所有かつモード0700である必要があります。パスのいずれの箇所にもシンボリックリンクを含めることはできず、/tmpなどのスティッキービット付きディレクトリを除き、上位ディレクトリがグループや他ユーザーから書き込み可能であってはなりません。ディレクトリが存在しない場合、SDKがモード0700でソケットのディレクトリを作成します。

URLはhttps://で始まる必要があります。同一マシン上のdurable agent向けにポート番号を指定したhttp://127.0.0.1:<port>またはhttp://localhost:<port>のみが例外です。トークンが暗号化されずにネットワーク上を流れるのを防ぐため、Collieはそれ以外のhttp://アドレスを拒否します。

注意。 https経由の場合、アクセス制御はトークンのみに依存します。トークンを持つ者は誰でもすべての会話を閲覧し、すべての質問に応答でき、ホスト側にもテキストが見えます。この方法で接続するdurable agentでは、常時許可は絶対に提供せず、AllowとDenyのみを提供するようにしてください。

durable agentのセキュリティは、durable agentで実行可能な操作とCollieがログに記録する内容を定義します。

https経由のポーリングは毎回ホスト側で課金対象となる可能性があり、「変更なし」の応答も回数に含まれます。スマートフォンを開いていない待機状態でも10秒ごとにポーリングが行われるため、Collieは1日に8,640回リクエストを送信します。利用しているホストのプランがこれに対応しているか確認してください。

URL経由で配置されたdurable agentは、Collieの通信仕様を満たし、Bearerトークンを検証する必要があります。標準のPi Durableデモはどちらも満たしていないため、Collieをそのまま接続することはできません。

Collieはホスト上のdurable agentをポーリングします。スマートフォンで表示中は2秒ごと、それ以外は10秒ごとにリクエストを送信します。ポーリングのたびにハイバネート状態のDurable Objectが起動するため、Collieが監視している間、ホスト上のオブジェクトは起動したままになります。通信仕様にWebSocketが含まれないため、Durable Objectsのハイバネーション機能やWebSocket機能はここでは効果を発揮しません。

Cloudflareのサンプルはアーカイブされており、リリースには含まれていません。experiments/durable-member-cloudflare/に配置されています。

3つのコマンド

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を実行してください。失敗したチェック項目が表示されます。主な原因は3つあります。エントリがまだ読み込まれていない（再起動）、ソケットがプライベートでない（socket-not-private）、クラッシュによって古いソケットファイルが残っている（connection refused: 削除してdurable agentを起動）。durable agentのトラブルシューティングはdurable agentに関するケースを扱います。トラブルシューティングはCollie全体を扱います。

トークン

urlエントリにはトークンが含まれており、認証はこのトークンのみで行われます。

openssl rand -hex 32

結果は64文字の16進文字列となり、下限の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を出力します。Collieを再起動する前に、新しいトークンをdurable agentに設定してください。設定しない場合、スマートフォンにはdurable agentがトークンを拒否した旨が表示されます。ローテーションの実行中にdurable agentが2つ目のトークンを受け入れるように設定すれば、どちら側もアクセス不能になりません。保管されているCloudflareの例ではCOLLIE_TOKENを受け入れ、設定されている間はCOLLIE_TOKEN_NEXTも受け入れます（ADR 0103）。durable agentで新しいトークンをCOLLIE_TOKEN_NEXTとして設定し、attachを再実行してCollieを再起動した後、その値をCOLLIE_TOKENに移動してCOLLIE_TOKEN_NEXTの設定を解除してください。

単一のCollie内の独立したdurable agent

Windowsホストやホストされたdurable agentなど、ターミナルのないインスタンスでも、.envから1つのdurable agentを操作できます。

# 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/に直接保持していました。このビルドの初回起動時に、ログに1行出力された上でdurable/default/へ一度だけ移動されます。

トークンを変更するには、新しいトークンをdurable agentにデプロイし、.envに設定して、collie restartを実行します。durable専用インスタンスはホスト名でcrewに参加するため、リードとホストを共有する場合はcollie crew join <lead-address> --label durableで名前を指定してください。

sources.jsonのすべてのdurable agentを一時的に無効にするには、.envでCOLLIE_PROGRAMS=offを設定し、collie restartを実行します。ブリッジはそのファイルを無視して1行ログを出力し、durable agentのない環境として動作するため、スマートフォンにはDurable agentsセクションが表示されなくなります。collie doctorとcollie durable listにはdurable agentが無効である旨が表示されます。ファイルはそのまま残ります。変数を解除して再起動すればdurable agentが復帰します。この変数は上記の古い環境変数形式には影響しません。

Collieがdurable agentのデータを保持する場所

durable agentは会話の記録を保持します。Collieは状態フォルダ内にキャッシュ、レシート、プッシュメモリを保持します。

状態フォルダは~/.local/state/collie/、またはそれが設定されている場合はCOLLIE_STATE_DIRです。<program>はsources.json内の名前、またはdefaultです。各durable agentのフォルダはモード0700、各ログはモード0600です。

キャッシュがあるため、Chatは素早く開き、durable agentの動作が遅い間も機能します。クローズされた会話は常にdurable agentから読み取られ、キャッシュからは読み取られません。

durable agentは長い会話の最新部分のみを保持します。Collieが読み取る前に会話の先頭部分が破棄されていた場合、Chatはその場所に1行表示します。「古いメッセージは除外されました。durable agentはそれらを保持していません。」スマートフォン上のデータは失われていません。Collieがそのメッセージを取得したことはありません。

スマートフォンの表示

ダッシュボードのDurable agentsセクション、および各durable agentの会話リスト。

各durable agentはDurable agentsセクションの1行として表示され、名前、Experimentalバッジ、ランタイム、ローカルまたはリモートのどちらで実行されているかが示されます。右側にはオープンな会話数と、対応待ちの会話数がneeds-youの色でカウントされます。質問の待機中は、このセクションがスペースの上に移動します。起動中または到達不能なdurable agentには、カウントの代わりにその状態が表示されます。トークンの拒否と通信プロトコルバージョンの拒否にはスマートフォン上で固有の文言が表示され、その他の理由はすべてcollie doctorに示されます。

行をタップすると、メッセージングアプリのチャットリストのようにdurable agentの会話リストが開きます。あなたの対応を待っているものが先頭に表示され、次に他のオープンな会話、その後にClosedラベルの下にクローズされた会話が表示されます。オープンな会話はChatで開き、クローズされた会話は読み取り専用で開きます。durable agentはhelloの中で自身が実行可能な操作（asks、starters、send、steer、abort、rename、close、actions、history、reopen）を通知し、スマートフォンは通知された操作のコントロールのみを描画します。durable agentには画面がないため、Terminalビューやキー入力はありません。

durable agentへの送信時、queuedというラベルはCollie自身によるターンの解釈です。CollieはPiの受信箱で待機している内容を表示しません。期限までスリープしているタスクは、waitingではなくidleまたはworkingとして表示されます。詳細はセッションを参照してください。

質問カードにはdurable agentの名前が表示され、durable agentが制限時間を設定した場合は残り時間が表示されます。durable agent内で決定された質問や、タイムアウトした質問は、チャットに1行残ります。スマートフォンでのdurable agentの表示ではこれらを図とともに示します。

bridge経由でのSendとAsk

durable agentには画面がないため、Collieはその画面を読み取りません。代わりにbridgeが独自の状態を読み取ります。durable agentは、ターミナルペインと同じSendおよびAskを受け取ります。

• —
  状態。 ターンはペインの状態から取得されます。質問は、保留中の最も古いaskから取得されます。durable agentには入力欄がないため、入力ボックスは常に空です。スマートフォンはこの状態を各ペインとともに、ターミナルペインと同じ形式で取得します。
• —
  送信。 POST /api/sendはスマートフォンからリクエストIDを受け取ります。bridgeはリクエストをディスクに書き込み、会話をロックします。その後、読み取ったターンに対して、テキストをdurable agentに1回送信します。その応答が送信の証明となり、レシートには受け取ったリクエストIDが記録されます。ターン中、durable agentはテキストをそのターンの後まで保持し、レシートにはqueuedと記録されます。
• —
  結果。 送信の結果はsent、理由付きのrefused、またはunknownのいずれかになります。unknownは、durable agentがテキストの受け取りを応答しなかったことを意味します。再送信する前にチャットを確認してください。送信は、durable agentが会話に書き込んだ時点でeffectiveになります。そのuser項目には、該当する送信のリクエストIDが記録されます。いずれかの質問が未解決の間は、Collieが読み取れない質問であっても、通常の送信は拒否されます。質問に回答するか、SteerまたはStopを使用してください。確認後に開始されたターンは送信を拒否し、durable agentには何も届きません。
• —
  質問。 POST /api/ask/<id>が回答します。ask IDは1回限り有効です。回答には、表示された質問のハッシュが含まれます。bridgeはそれをdurable agentが現在リストしている質問と比較します。2つが一致しない場合、durable agentには何も届きません。応答には現在の質問が表示されます。回答は自身のask IDによってdurable agentに送られます。キーが送信されることはありません。レシートにはchannel: programと記録され、ハッシュが保持されます。
• —
  カードにとどまるもの。 一部の質問は1回のタップに収まらないため、状態上はCollieが読み取れない質問（modal: unreadable）として表示されます。これらは専用のカード上で回答します。- テキスト質問は、回答を入力する1行のテキストであるため、durable agent自身のカードにとどまります。- 複数の選択肢は、回答が複数の選択となるため、durable agent自身のカードにとどまります。- フォームは、回答が一連のフィールドであるため、durable agent自身のカードにとどまります。- 常時許可（Always allow）は契約の選択肢にはなりません。その付与はこの質問の後も継続します。そのため、durable agentのカードはまず2回目のタップを要求し、/api/ask経由の1回のタップでそのタップをスキップしてはなりません。
• —
  カウンター。 collie doctorは、これらの読み取りと結果を1行（program）でカウントします。

このマシンでは、スマートフォンは以下のルートを使用します。通常の送信は/api/sendを経由し、質問カードのタップは/api/askを経由します。コンポーザーは、手元の操作位置にdurable agentの言葉で結果を表示します。質問が送信をブロックしている場合、そのカードへのボタンが表示されます。ペインの最近の送信リストには各レシートが表示され、キューに入った送信にはその旨が表示されます。steerはSend Protocolの一部ではないため、SteerとStopは会話自体のルートにとどまります。crewメンバー上のdurable agentは、すべての書き込みで会話自体のルートを維持します。各ルートは、テキストがdurable agentに届く前にターンを確認します。1つの会話へのすべての書き込みは1つのロックを共有します。送信の実行中、Steerとカードの回答はbusyとして拒否されます。Stopは最大でも制限時間までロックを待機するため、ハングした送信によってStopが締め出されることはありません。

バージョン

Collieとdurable agentはhelloの中でwireバージョンに合意します。現在存在するバージョンはバージョン1の1つのみです。

Collieは1..1をサポートします。バージョン2がリリースされた場合、Collieはその後の1つのマイナーリリースでバージョン1を受け入れ、その次のマイナーリリースで廃止します。現在、受け入れるべき過去のバージョンはありません。

2つの範囲が一致しない場合、Collieはdurable agentからそれ以上何も読み取りません。Collieのログには拒否した範囲ごとに[durable] The durable agent speaks wire v2, this Collie speaks v1. Update Collie, or the agent's SDK.のような行が1行出力されます。スマートフォンのdurable agentのホームには注意ボックス内に同じ文が表示され、ダッシュボードの行にはUnreachableの代わりにVersion mismatchと表示されます。collie doctorではdurable-hello行に両方の範囲が表示されます: incompatible: the durable agent speaks 2..3, this Collie speaks 1..1。durable agentの起動ごとに1回、Collieは自身のバージョンを含むhelloも送信するため、durable agent側でも不一致をログに記録できます。古い側を更新してください。

出口

この機能は、このリポジトリの外部で誰かが使用している場合にのみ残されます。

1.24.0リリースまでに、wireを話す公開リポジトリが存在するか、durable agentに関する外部のIssueまたはディスカッションが存在する、という条件のいずれかを満たす必要があります。どちらも満たさない場合、durableのコードはリリースからexperiments/へ移動し、このページは削除されます（ADR 0104）。削除時、sources.jsonエントリは1つのマイナーリリースの間1行のログ出力とともに無視され、ソケットはdurable agentに対して動作し続け、npmパッケージは削除されずに非推奨化されます（ADR 0105）。