durable agentのトラブルシューティング

実験的。 通信プロトコル、SDK、およびこのページは、今後のマイナーリリースで変更されるか、機能自体が削除される可能性があります。機能が存続するかどうかの判断基準についてはdurable agentを参照してください。

durable agentが表示されない、Unreachableと表示される、またはタップに応答しない場合、3つのコマンドで原因を特定し、原因一覧表と事例リストで解決策を確認できます。Collie全体についてはトラブルシューティングで扱っています。

最初の確認

次の3つをこの順序で実行します:

collie durable list
collie doctor
collie logs

スマートフォン側の表示はより簡潔です。durable agentの行にはStartingまたはUnreachableと表示され、理由は示されません。プロトコルバージョンの拒絶には固有の表記（Version mismatch）があり、durable agentのホームに警告ボックスが表示されます。拒否されたトークンには接続バーに独自の文言が表示されます。その他のあらゆる理由はcollie doctorとcollie logsに示されます。

原因一覧

Collieがdurable agentに接続できない場合でも、Collieの他の部分はそのまま起動し、durable agentは1つの理由とともに到達不能として表示されます。

durable agentがsources.jsonのエントリである場合でも、原因には環境変数名が表示されます。COLLIE_DURABLE_SOCKETはエントリのsocket、COLLIE_DURABLE_URLはそのurl、COLLIE_DURABLE_TOKENはそのtokenと読み替えてください。エントリの修正はsources.jsonで行います。durable単体形式の修正は.envで行い、その後にcollie restartを実行します。

設定がルールに違反しています

Collieはdurable agentへ接続を試みることなくこれらを報告します。sources.jsonエントリに存在するルール違反も、ブリッジの開始時に拒否されます（sources.jsonの入力ミス）。

durable agentが応答しないか、誤った応答を返します

durable agent向けのDoctor行

collie doctor は、bridge と同じ順序で、bridge と同じ問い合わせを各 durable agent に対して実行します。送信するのは hello のみです。

sources.json の各エントリには 6 行のブロックが 1 つ割り当てられ、desk という名前の durable agent には durable-socket:desk と出力されます。ブロックの前にある sources 行でファイルをチェックし、後ろに durable-lead 行が 1 行続きます。durable 専用の Collie は接尾辞なしで同じ 6 行を出力し、mux 行には durable, see the durable-* lines と表示されます。

1つの行が失敗すると、それ以降の行は停止します。それらは理由fix the row above firstとともにスキップとして出力されます。Collieは、プライバシーチェックに失敗したソケット経由や、ルールに違反するトークンを使ってdurable agentに問い合わせることはないためです。スキップされた行は障害ではありません。

ケース一覧

各ケースでは、発生する事象、原因、解決方法を説明します。

sources.jsonの入力ミス

1つのdurable agentだけでなく、Collie自体が停止してスマートフォンから接続できなくなります。collie logsの末尾に[bridge] FATAL:、ファイルパス、エントリ、フィールドが出力されます。

bridgeは起動時にsources.jsonを読み込み、不明なフィールド、durableではないkind、ルールに違反する名前、重複した名前、socketとurlの同時指定、どちらも指定されていない構成、tokenのないurl、socketのあるtokenを検出すると停止します。ファイルを修正し、collie restartを実行してください。collie doctorのsources行にも同じメッセージが表示されます。

bridgeがエントリ名を特定できない場合（オブジェクトではない、不明なフィールドがある、または名前がルールに違反している場合）、0からカウントし、2番目のエントリにはentry 1と出力します。collie durable attachは1からカウントし、同じエントリにentry 2と出力します。どちらも対象フィールドを示します。名前が有効になると、bridgeはその名前（entry "desk"）を出力します。

attachおよびdetachは、読み取れないファイルへの書き込みを行いません。入力ミスによって他のエントリが失われるのを防ぐためです。これらは終了コード1で停止します。

attach後にdurable agentが表示されない

スマートフォン上にdurable agentが表示されず、collie durable listにnot loaded (restart to apply)と表示されます。

attachとdetachはsources.jsonへの書き込みのみを行います。bridgeはこれを起動時に読み込みます。collie restartを実行するか、次回からコマンドに--restartを追加してください。再起動後もnot loadedが残る場合は、collie logsを確認してください。listでは、bridgeからのHTTP 400が404と同じ文面で表示されます。

プライバシーチェックに失敗しました

socket-not-private: the socket's folder /tmp/hello has mode 0755, not 0700が表示され、doctorの行durable-socketが赤くなります。

Collieは、パス全体がプライベートな場合にのみソケットに接続します。主な原因は、モードが0755のフォルダ、/tmpなどの共有フォルダ直下にあるソケット、パス内のシンボリックリンクです。シンボリックリンクは見落としがちです。多くのLinux環境で/var/runは/runにリンクしているため、/var/run/で始まるパスは/var/run is a symlinkで失敗します。実パスを使用してください。

ソケットが存在するフォルダに対してchmod 700を実行するか、ソケットを$XDG_RUNTIME_DIR以下に移動してください。ルールはdurable agentのセキュリティに記載されています。SDKで作成されたdurable agentは、モードが0700ではない既存フォルダでは起動を拒否し、その旨を自身で出力します。

古いソケットファイル

ソケット上にconnection refusedと表示され、ファイルは存在しています。

クラッシュしたdurable agentはソケットファイルを残しますが、そのソケットをリッスンするプロセスはありません。durable agentを再起動してください。SDKはリッスンを開始する前に不要なソケットファイルを削除し、ソケットが稼働中の場合はanother instance is already listeningで停止します。durable agentがファイルを削除しない場合にのみ、手動でファイルを削除してください。

ターミナルセッションと重複する名前

bridgeが起動時にthe name is the terminal session's own; pick anotherで停止するか、スマートフォン上にターミナルセッションが表示されません。

durable agentには、Collieの実行元ターミナルと同じ名前を付けることはできません。多くのインストール環境でその名前はdefaultであり、durable専用のCollieではdefaultがそのdurable agentの名前になります。bridgeは起動時に停止し、該当エントリ名を出力します。Herdrセッションがdurable agentと同じ名前を持つ場合も同様です。durable agentがその名前を保持し、スマートフォンには該当セッションが表示されず、ログに一度出力されます。どちらかの名前を変更してください。

durable-readyの警告が消えない

collie doctorを実行するたびにdurable-readyが警告として表示されます。

durable agentがhelloと応答し、ready: falseと出力します。スマートフォン上では「Starting」と表示されます。durable agentは、会話を展開し、未解決の質問を再提示した後にのみ準備完了状態になります。何が待機されているかについては、durable agent自身のログを確認してください。

子孫プロセスのチェックでdurable agentが起動時に停止する

durable agentが起動時にthe descendant check needs Bun on Linux to read the peer of a socket; pass callerCheck: "off" to run without itで停止します。

このチェックにはLinux上のBunが必要です。macOSではNodeでdurable agentを実行するか、openCollieにcallerCheck: "off"を渡して事前にこのチェックが保護する対象を確認してください。このエラーはdurable agent側から発生しており、Collieは関与していません。

再起動後に質問が再度表示される

durable agentの再起動後に同じ質問が再度表示されるか、すでに回答済みと書かれたカードが表示されます。

再起動前の質問に対する回答は too-late を受け取り、カードはその旨を表示して消えます。ツール呼び出しから質問IDを生成するdurable agentは同じ質問を再提示するため、再起動を挟んで送信された回答が適用され、ツールが1回実行されます。毎回新しいIDを生成するdurable agentは、同じツール呼び出しに対して新しい質問を作成します。カードにはそれが表示され、プッシュガードがツール呼び出しをキーとするため、Collieは2回目のプッシュを送信しません。このガードはまた、会話ごとに毎分3回、ホストごとに毎分10回、ホストごとに毎時30回のプッシュを許可します。1時間の中で31回目となるプッシュはそのホストへの1件の要約プッシュとなり、そのホストはその後1時間が経過するまでプッシュを送信しません。カードは常に表示されます。

403 caller-refused

回答またはメッセージが拒否されたと電話機に表示され、durable agentの理由は 403 caller-refused です。

durable agentの子孫プロセス確認により呼び出し元が拒否されました。この確認は、durable agent自体、durable agentが起動したプロセス、およびそれらと区別できない呼び出し元を拒否します。durable agentまたはそれが実行したツールがCollieプロセスを起動し、そのプロセスがまだ子プロセスである場合、Collieはdurable agent側とみなされます。durable agentの外部からCollieを起動してから、やり直してください。

「やり直す」、および適用された可能性がある回答

「回答が届いたか不明です」と「やり直す」ボタンが表示され、タップ後に「すでに適用されている可能性があります。チャットを確認してください。」と表示されます。

回答送信後のタイムアウト、接続切断、または5xxエラーは、回答が届いた可能性があることを意味します。「やり直す」は同じリクエストIDを送信するため、durable agentは replayed と応答し、質問を2回解決することはありません。質問がすでに閉じられている場合、最初の試行で閉じられた可能性があるため、電話機にはチャットを確認するよう表示されます。送信、停止、ボタンタップもそれぞれの文言で同様のことを示します。

durable agent がトークンを拒否しました

接続バーに「durable agentがトークンを拒否しました。このピアのCOLLIE_DURABLE_TOKENを確認してください。」と表示され、理由は token-refused です。

durable agentがトークンに対して401または403を返しました。最も一般的な原因は、一方のトークンが先に変更されたローテーションです。電話機の文言は sources.json のエントリであっても COLLIE_DURABLE_TOKEN と表記します。そのエントリの token と読み替えてください。Collieを再起動する前に、新しいトークンをdurable agentに渡してください。トークン にローテーションの手順があります。403は、durable agentの前面にあるアクセスプロキシが原因である場合もあります。

2回の読み取りを経てUnreachableへ切り替わる

durable agentの読み取りが1回失敗してもReadyのまま維持され、その後Unreachableに切り替わります。

成功した読み取りの後に1回失敗した場合、そのポーリングでは直前のレイアウトが維持されます。2回連続で失敗すると、durable agentが切り替わります。拒否されたトークンも同じルールに従います。プライバシーチェックに失敗したソケットパスが唯一の例外で、即座に表示されます。

https経由では、ダウンしているかトークンを拒否したdurable agentへの問い合わせは最大で10秒に1回です。各試行が課金対象のリクエストとなるためです。ソケット経由では、ダウンしているdurable agentの2回の読み取り間の最小間隔は250ミリ秒です。

crew内

crewのメンバー上のdurable agentはリードの電話機に表示されるため、リードはdurable agentが何であるかを認識している必要があります。

1.21.0より前のリードは、質問カードなしでdurable agentの会話を一覧表示し、そのTerminalタブはターミナルのない会話をポーリングします。メンバー側ではこれを修正できません。メンバー自身がその旨を示します。collie doctor が durable-lead 内で警告し、ログには検出したリリースごとに1行、[durable] the lead is 1.20.1; it shows durable panes without the question card and its Terminal tab polls; update the lead が記録されます。リードを更新してください。

リードより古いメンバーには逆の問題があります。電話機に「このマシンは古いCollieを実行しているため、ここでは回答を受け取れません。更新するか、durable agent内で回答してください。」と表示されます。そのメンバーを更新してください。