Files
billion-context/docs/opencode-responses-websocket.ja.md

9.3 KiB
Raw Permalink Blame History

OpenCode V2 Responses WebSocket 統合(#1844)

承認済みスコープ

ユーザーは 2026-10-01 に、以前議論していた双方向 WebSocket ACP 統合の実装を承認した。OpenCode V2 は WebSocket 経由で bili に接続し、bili は選択された Responses アップストリームに WebSocket 経由で接続する。これには OpenAI API と ChatGPT OAuth/Codex エンドポイントを含む。Realtime、汎用の不透明 WebSocket パススルーは実装せず、ユーザーの OpenCode 設定も変更しない。

設計上の判断

  • V2 ハンドシェイクフックは、サポートされる Responses ソケットをプラグインアイデンティティとモデルメタデータ付きで既存の明示プロトコルトンネル経由でルーティングする。他のプロトコル、無効化されたプラグイン、古いホストは既存の挙動を維持する。
  • 初期はループバックのみ、協調的な OpenCode Responses アップグレードだけを許可する。宛先の許可は既存のトンネルガードを再利用する。未引受のアップグレードも引き続き既存の即時 426 を受け取る(PR #1472 と独立)。
  • Responses フレームはネットワーク HTTP ホップではなく、プロセス内の HTTP 形状エンベロープを経て既存のリクエストパイプラインに入る。非同期スコープの fetch トランスポートがモデルリクエスト、リトライ、プリフライトリクエストをアップストリーム WebSocket 上で実行する。既存の ACP ポリシー、ツール実行、使用量集計、散文フィルタリングが唯一の権威であり続ける。ツール引数字符列は決してクリーンアップされない。
  • クライアントとアップストリームの継続チェックポイントは別物:クライアントは元の履歴と可視出力を見る、アップストリームは ACP 処理済み履歴を見る。受信デルタは ACP 前に展開される。送信デルタは処理済み入力があるがままアップストリームチェックポイントを拡張する場合にのみ使われる。フォールドや他の履歴変更では previous_response_id なしの完全な処理済み入力を送る。これにより新しいソケットを必要とせずに新しいレスポンスチェーンを開始できる。view=ws-expanded とマークされたリクエストサイズログは再構築されたパイプラインエンベロープを記述するもので、増分 WebSocket ワイヤバイトではない。
  • 完了したレスポンスだけが継続チェックポイントを確立する。切断、キャンセル、失敗/不完全なレスポンス、未知のレスポンス ID は成功履歴を捏造しない。チェックポイントとキューイングされたペイロードには上限がある。
  • 両方のチェックポイントは出力インデックスごとに response.output_item.done アイテムを累積する。空・欠落・部分的な終端 response.output は完了済みツールコールを消去して次のデルタで孤立結果を残してはならない。終端アイテムはアイテム ID でマージされ、ストリーミングフレームは不変。デバッグログは復元されたチェックポイントアイテム数を報告し、内容は記録しない。
  • WS 診断はローカルソケットとセッション、失敗フェーズ(handshake、await-first-event、stream、または dispatch)、数値クローズコード、フル/デルタリクエストモード、チェックポイントのリセット/回復理由を識別する。認証ヘッダー、URL、クローズ理由テキスト、ペイロード、アップストリームエラーメッセージは省略する。正常なライフサイクル/回復の詳細は debug、失敗は warn を使う。
  • 設定フィールド、環境変数、パッケージバージョン、永続化形式、acp-kernel バージョンを追加も変更もしない。ソケットチェックポイントは接続ローカルであり、ACP 永続化は不変。ws 実装はバンドルされたビルド時依存であり、外置ランタイム要件ではない。

アーキテクチャ:汎用 WebSocket ブリッジ(#1467 phase-2 シェル)

WebSocket インターセプトはプロトコル非依存シェルとプロトコル毎のコーデックに分割される:

  • src/ws-bridge.ts(シェル)は許可(ループバックソース、x-bili-plugin レーンマーカ、x-bili-plugin-conversation セッションヘッダー、トンネル宛先ガード)、アップグレードハンドシェイク、接続毎の簿記、シャットダウン時のティアダウンを所有する。どんなワイルプロトコルも知らない。
  • src/responses-ws.ts(コーデック)は Responses 固有のすべてを所有する:フレーム検証、previous_response_id クライアント履歴契約、継続チェックポイントを持つアップストリーム WebSocket トランスポート、SSE レスポンスシンク。単一の配線箇所のコーデックテーブルに responsesCodec として登録される(src/server.ts の installWebSocketBridge(server, dispatch, log, [responsesCodec, codexResponsesCodec]))。

第 2 のワイルプロトコルは新しいコーデックファイル + テーブルエントリ 1 つ——シェルは変更しない。シェル契約は WsBridgeCodec(名前、プラグインマーカ、URL クレーム、セッションファクトリ)と WsBridgeSession(message/close/shutdown)。セッションはラベル付きロガー、アップグレードされたピア、アップグレードリクエスト、クレームされたアップストリーム URL、ACP パイプライン入口(dispatch)を受け取り、プロセス内でワイルプロトコル形状のエンベロープを再構築することが期待される。tests/ws-bridge.test.ts は合成の第 2 コーデックでシェルを駆動し、コーデックテーブルを誠実な状態に保つ。

第 2 の実コーデックは既にここにある:codexResponsesCodec は codex CLI の Responses-over-WebSocket ダイアル(/bili/<upstream>/responses、会話ヘッダー session-id、stream:true フレーム、パイプライン前後で逐語中継される generate:false の接続毎プレウォームプローブ)をクレームする。プレフィックスレーン:ワイヤにプラグインマーカがなく、許可はループバック + 会話ヘッダー + トンネルガードに基づく——プレフィックスモード HTTP と同じ信頼レベル。Codex は毎ターン完全な履歴を再生する(previous_response_id は送信されない)ので、フォールドは次の再生を単純に縮小する;tests/codex-responses-ws.test.ts を参照。

未知のプロトコルは圧縮できない(フォールディングには履歴がワイル形式のどこにあるかを知らなければならない);それらは #1472 の透明パススルーレーンにとどまり、このブリッジには触れられない。

検証

乱数ループバックポートと偽の Responses WebSocket アップストリームを使い、実際の認証情報やモデル使用量なしで。双方向が WebSocket の上にとどまること、通常の継続が増分であること、実際の ACP フォールドがアップストリーム履歴をリセットすること、ツール引数ペイロードが不変で生存すること、使用量が既存セッションに届くこと、終端出力が疎でもフォールド後も連続するツールコール/結果が履歴を進めること、未知のアップグレードが 426 を維持することを証明する。アップストリームプロキシルーティング、エラー、キャンセル、再接続、チェックポイントミス、セッション分離を検証する。隔離設定と成功した偽 WebSocket アップストリームで本物の OpenCode V2 バイナリを動かす;HTTP へフォールバックしただけの利用不能なソケットは許容できる証拠ではない。人間のレビュー対象 PR を提出する前に typecheck、完全なユニットスイート、ビルド、必要な Responses クライアント E2E を実行する。

失敗組合せのカバレッジには、切断前に届けられたツール引数、失敗/不完全な終端イベント、ローテーションした合成認証情報での新接続への直後のキャンセル、重複 create、有界リトライを伴う連続する継続/接続上限エラー、回復を伴うハンドシェイク拒否が含まれる。疎出力の実フォールドテストはさらにチェックポイント欠落、アイドル切断、接続上限ローテーションを連鎖させ、サマリーが生存し各完了コール/結果がアップストリームにちょうど 1 回ずつ現れることをアサートする。これらはトランスポート/履歴のアサーションであり、任意のホストツールの厳密なちょうど一度実行や実際の OAuth リフレッシュライフサイクルの証明ではない。