agent-browser-relay

Agent Browser Relay

このスキルを使うと、明示的にアタッチされたブラウザータブでローカルリレーゲートウェイを介して操作し、読み取り前に準備状態を確認できます。また、直接的なブラウザー制御ツールに切り替えることなく、リースの適用範囲内でタブの並行ワークフローを維持できます。

ドキュメントで主な対象としているのは Chrome です。拡張機能を読み込める Chromium ベースのブラウザーでも動作する場合があります。1 つのリレーポートに複数のブラウザー／プロファイルの拡張機能クライアントを同時に接続でき、リレーのステータスには各ブラウザー ID とアタッチ済みの tabRef 値が表示されます。

クイックスタート

新しいマシンでのルール：

• skills add により、インストール済みスキルが ~/.agents/skills/agent-browser-relay に配置されることが保証されます
• skills add の後に保証される Chrome の読み込みパスは ~/.agents/skills/agent-browser-relay/extension です
• ~/agent-browser-relay/extension は、npm run extension:install で作成される任意の見やすい便利なコピーにすぎません
• npm run extension:path、npm run relay:start、npm run relay:global:install は、読み込むプライマリーフォルダーを表示します
• npm run extension:path は、エージェントが現在の作業ディレクトリに依存せず呼び出せるよう、read-active-tab.js と preflight.sh の安定した絶対パスも表示します
• リレーの起動後に拡張機能のポップアップを一度開くと、拡張機能が起動し、Chrome が実際に読み込んだことを npm run extension:status で確認できるようになります
• 新しいマシンでは、アタッチ／読み取りの手順に進む前に、人間が chrome://extensions でプライマリーパスを読み込む必要があります。見やすい便利なコピーが存在しないことを、サンドボックスやソケット権限の問題として扱わないでください。

デフォルト値はコード内で設定されています：

• ホスト：127.0.0.1
• ポート：18793
• アタッチのタイムアウト：120000 ms 必要に応じて、コマンドごとに --host、--port、--attach-timeout-ms で上書きしてください。

1. 依存関係をインストールしてリレーを起動する

   Chrome で読み込むプライマリーの Chrome 拡張機能パスを表示し、可能な場合は見やすい便利なコピーも更新します。

   npm run relay:start -- --status-timeout-ms 3000
   

   または、ホスト／ポートを明示的に指定します：

   npm run relay:start -- --host "127.0.0.1" --port "18793" --status-timeout-ms 3000
   

   relay:start は、停止するかプロセスが再起動されるまで実行され続けます。実行時間を制限する場合は、--auto-stop-ms を明示的に指定してください：

   node scripts/relay-manager.js start --auto-stop-ms 10800000
   

2. Chrome で拡張機能を読み込む

   • chrome://extensions
   • デベロッパーモードを有効にする
   • skills add の後に ~/.agents/skills/agent-browser-relay/extension からパッケージ化されていない拡張機能を読み込む
   • コマンドに拡張機能のパスが表示された場合は、その表示されたパスを正しいパスとして扱う
   • 正確なパスを再度表示したい場合は、インストール済みスキルのディレクトリから npm run extension:path を実行する
   • ~/agent-browser-relay/extension は任意です。見やすいショートカットが必要な場合は、npm run extension:install で作成してください

3. Chrome で拡張機能が読み込まれていることを確認する

   リレーの起動後に、ツールバーのポップアップを一度開いてください。ポップアップに Relay connected on <port> と表示されるはずです。

   エージェントの要件：新しいマシンでアタッチする前に、人間にポップアップを一度開いてもらい、次のコマンドで確認してください：

   npm run extension:status -- --port "18793" --wait-for-connected --connected-timeout-ms 120000
   

   これにより、リレーポートに接続されている各ブラウザのホスト／プロファイル ID が報告されます。

4. 拡張機能を対象のタブにアタッチする（ツールバーのポップアップを開いて「アタッチ」をクリック）

   通常の使用では、すべてのブラウザーでデフォルトのリレーポートを使い、各ブラウザーで対象のタブをアタッチしてください。リレーは tabRef（browserId:tabId）でタブを名前空間化します。 エージェント自身に最初のバックグラウンドタブを作成させる場合は、ポップアップで Allow agent to create new background tabs を有効にしてください。

   エージェントの要件：extension:status で Chrome に拡張機能が読み込まれていることを確認した後、一旦停止して人間にこのアタッチ手順を依頼し、確認を待ってから続行してください。

   git fetch または pull の後に .agents スキルフォルダーから extension/ がなくなった場合は、リポジトリから修復してください：

   cd ~/.agents/skills/agent-browser-relay 2>/dev/null || cd ~/.agents/skills/private/agent-browser-relay
   git sparse-checkout disable
   git config --unset-all core.sparseCheckout || true
   git config --unset-all core.sparseCheckoutCone || true
   git checkout -- .
   

5. 準備状態とアタッチ状態を確認する

   npm run relay:doctor -- --port "18793" --tab-id "<TAB_ID>" --json
   

   まずステータスから <TAB_ID> または <TAB_REF> を解決してください（npm run relay:status -- --all --status-timeout-ms 3000）。 すべてのエージェント実行では、割り当てられたタブ ID またはタブ参照を使用してください：

   npm run relay:doctor -- --host "127.0.0.1" --port "18793" --tab-id "<TAB_ID>" --json
   

   npm run relay:doctor -- --host "127.0.0.1" --port "18793" --tab-ref "<TAB_REF>" --json
   

   このコマンドが成功を返した場合にのみ続行してください。

複数ブラウザーでの動作

• 1つのリレーポートで、複数の接続済みブラウザー／プロファイル拡張クライアントをサポートします。
• アタッチ済みタブには、browserId:tabId 形式のブラウザー固有の tabRef が含まれます。
• アタッチ済みタブの中にその ID のタブが1つだけある場合は --tab-id を使用します。複数のブラウザーで同じ数値のタブ ID が使われている可能性がある場合は、--tab-ref を使用します。
• 複数のブラウザーで Target.createTarget が有効になっている場合は、使用するブラウザーを選択するために --browser-id を指定します。

高度なタブごとのリレーポートの動作

• デバッグや特殊なルーティング用に、複数のリレーポートを引き続き利用できます。
• 保存済みのリレーポートのマッピングがないタブでは、グローバルのデフォルトリレーポート（18793）を使用します。
• アタッチに成功すると、拡張機能はそのタブに割り当てられたリレーポートを保存し、以降は自動的に再利用します。
• 閉じたタブのマッピングは自動的に削除されます。

エージェントの必須動作

• このリポジトリにある固定コマンドを使用してください。別のスクリプト名を「探さない」でください。
• ゲートウェイのみを使用するルール：必ずローカルリレーゲートウェイ（/status と node scripts/read-active-tab.js）を介して通信してください。
• このワークフローでは、ブラウザーを直接制御するツール（Playwright、Puppeteer、Selenium、agent-browser、その場で作成した Chrome 制御スクリプトなど）は使用しないでください。
• ランダムな Chrome ウィンドウやプロファイルを操作しないでください。--tab-id または --tab-ref を使って割り当てられた、明示的に接続済みの対象タブのみを操作してください。
• 新しいマシンでは、接続や読み取りを試みる前に、npm run extension:path が示すプライマリ拡張機能のパスを読み込むよう人間に明示的に伝えてください。skills add の後であれば、通常は ~/.agents/skills/agent-browser-relay/extension です。
• 正式なコマンド：
  • npm run extension:path
  • npm run extension:status
  • npm run relay:start
  • npm run relay:status
  • npm run relay:doctor
  • npm run relay:stop
  • node scripts/read-active-tab.js
• リレーのヘルスチェックでは、ハングを避けるため、必ずタイムアウトを明示してください。
  • npm run relay:status -- --status-timeout-ms 3000
  • curl --max-time 3 -sS "http://127.0.0.1:18793/status"
  • npm run relay:status -- --all --status-timeout-ms 3000
• relay:start の後、一旦停止し、人間にポップアップを一度開くよう依頼してください。これにより、npm run extension:status -- --port "18793" --wait-for-connected --connected-timeout-ms 120000 で Chrome が実際に拡張機能を読み込んだことを確認できます。
• extension:status が成功した後に限り、読み取りの前に対象タブを接続するよう人間に依頼するか、最初のタブを作成するワークフローを開始する前に Allow agent to create new background tabs が有効になっていることを確認してください。
• 読み取りの前に npm run relay:doctor -- --host "127.0.0.1" --port "18793" --tab-id "<TAB_ID>" --json または npm run relay:doctor -- --host "127.0.0.1" --port "18793" --tab-ref "<TAB_REF>" --json を実行し、成功した場合にのみ続行してください。
• ワークフローで Target.createTarget によるタブの起動が必要な場合は、npm run relay:doctor -- --host "127.0.0.1" --port "18793" --require-target-create --json を実行し、成功した場合にのみ続行してください。
• すべてのエージェント実行（単独エージェントおよび並行実行）では、確認・読み取りコマンドに必ず --tab-id <tabId> または --tab-ref <browserId:tabId> を渡し、すべての操作をリースの対象範囲内にしてください。
• 並行実行では、接続済みタブはリレーの共有状態ですが、1つの接続済みタブに割り当てられるアクティブなリースは同時に1つだけです。次の --tab-id／--tab-ref を選ぶ際は、npm run relay:status -- --all --status-timeout-ms 3000 を確認し、leaseSummary.availableAttachedTabIds、attachedTabs[].tabRef、attachedTabs[].leasedSessionId を優先して参照してください。
• doctor が TAB_LEASED_BY_OTHER_SESSION を返した場合、引き継ぎを試みないでください。そのセッションの完了を待つか、アクティブなリースのない別の接続済みタブを使って再試行してください。
• Target.createTarget が有効な場合、人間が最初にタブを接続しなくても、拡張機能がセッション用のエージェント制御タブを最初に作成し、自動接続することがあります。
• 人間からの依頼、または明示的に復旧が必要な場合を除き、タスク中にリレーを停止・再起動しないでください。
• コードがローカルで更新されたという理由だけでリレーを再起動しないでください。更新は、人間が明示的に承認して再起動した次のタイミングで適用されます。
• 要求された tabId がリレーのステータスにある attachedTabs に見つからない場合は、停止し、続行する前にポップアップから対象タブを再接続するよう人間に依頼してください。
• relay:start がタイムアウトした場合は、実際のリレーログ／エラーを報告してください。コマンド出力に具体的な権限エラーが示されていない限り、サンドボックスの制限について推測しないでください。
• ページに人間による確認のゲート（「Are you human?」や CAPTCHA など）が表示された場合は、直ちに停止し、$attention-please を使って人間に知らせ、続行前に人間から明示的な確認があるまで待ってください。

5. 構造化されたタブのペイロードを読み取る

   node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --tab-id "<TAB_ID>"
   

6. 省略可能なワンコマンドのスモークテスト

   ./scripts/preflight.sh
   

これはローカルのスモークテスト用ラッパーです。エージェントのワークフローでは、タブに接続済みの場合は npm run relay:doctor -- --port "18793" --tab-id "<TAB_ID>" --json、最初のタブを作成するワークフローの場合は npm run relay:doctor -- --port "18793" --require-target-create --json が正式な事前チェックコマンドです。

現在の作業ディレクトリがインストール済みのスキルルートでない場合は、相対パスの node scripts/read-active-tab.js ではなく、npm run extension:path が出力する絶対パスの Stable read CLI path を使用してください。

機能

read-active-tab.js は、成功したすべてのペイロードで次の場所に機能メタデータを返します。

source.capabilities

バージョン互換性チェックの結果も source.extension に含まれます。

• installedVersion
• sourceVersion
• relayVersion
• observedExtensionVersion
• versionMismatch

不一致が検出された場合、コマンドは実行のたびに、人が読みやすい形式の更新ヒントも stderr に出力します。

• scripts/read-active-tab.js のデフォルト抽出項目：url、title、text、links、metaDescription。
• Relay セッションリース（--tab-id、--tab-ref）により、1 つの Relay ポート上でタブごとにエージェントを分離できます。
• --expression、--expression-file、または --expression-stdin を使った Runtime.evaluate 式モード。
• --screenshot によるスクリーンショット撮影モード（--screenshot-full-page、--screenshot-path は任意）。
• WhatsApp および汎用チャット監査用の、正規表現フィルターを備えたプリセット抽出。
• --check --wait-for-attach による接続状態のポーリング。

並行ワークフローに関する注意事項

• 並行実行でタブを選択する前に、npm run relay:status -- --all --status-timeout-ms 3000 を実行して確認してください。
• 現在使用可能な接続済みタブを把握するには、attachedTabs と leasedSessionId / tabLeases を確認してください。
• doctor が TAB_LEASED_BY_OTHER_SESSION を返した場合は、強制的に引き継がないでください。そのセッションがタブを解放するまで待つか、別の接続済み tabId を選択してください。
• リース分離により、接続済みタブごとに Relay コマンドのルーティングが分離されます。ブラウザープロファイルが別になるわけでも、ブラウザープロセスの分離が強化されるわけでもありません。

プリセットとフィルター

• --preset の値：default、whatsapp、wa、whatsapp-messages、chat-audit、chat。
• 正規表現フィルター：--text-regex、--exclude-text-regex、--link-text-regex、--link-href-regex。
• WhatsApp／チャット用フィルター：--message-regex、--exclude-message-regex、--sender-regex、--exclude-sender-regex。

コマンドの一般的な例

エージェントのワークフローでは、--tab-id または --tab-ref を指定する形式を使用してください。スコープを指定しないコマンドは、手動でのローカルデバッグ専用です。 複雑な JavaScript を指定する場合は、インラインの --expression よりも --expression-file または --expression-stdin を優先してください。

node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --pretty false
node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --tab-id 123 --pretty false
node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --tab-ref chrome-profile:123 --pretty false
node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --tab-id 123 --check --wait-for-attach --require-target-create --attach-timeout-ms 120000
node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --expression "document.documentElement.outerHTML"
node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --tab-id 123 --expression-file "./tmp/expression.js"
node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --tab-id 123 --expression-stdin < ./tmp/expression.js
node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --screenshot --screenshot-full-page --screenshot-path "./tmp/page.png"
node scripts/read-active-tab.js --host "127.0.0.1" --port "18793" --preset whatsapp-messages --max-messages 200 --selector "#main"
node scripts/read-active-tab.js --preset chat-audit --selector "body" --message-regex ".*"

成功したすべてのコマンドは、relayHost、relayPort、relayStatusUrl、relayWebSocketUrl を含む source オブジェクトを返します。

エージェントを使った推奨フロー

自動化ワークフローでデータを取得する前に、軽量な事前チェックを 1 回実行し、Relay と接続済みタブの状態が準備できていることを確認してください。

1 つの Relay で複数のエージェントを動かす場合：

• Relay のステータスからタブ ID を特定します（npm run relay:status -- --all --status-timeout-ms 3000）。
• エージェントごとにタブ ID を 1 つ割り当てます。
• そのエージェントの read-active-tab.js 呼び出しでは、すべて --tab-id または --tab-ref を使用します。
• 拡張機能のインスタンスは共有されるものとして扱います。リースにより、2 つのコントローラーセッションが同じ接続済みタブを操作することは防げますが、別々の Chrome プロファイルや拡張機能プロセスが作成されるわけではありません。
• relay:doctor が TAB_LEASED_BY_OTHER_SESSION を報告した場合は、attachedTabs、tabLeases、およびブロッカーの detail を確認し、別の接続済みタブを選ぶか、所有セッションがタブを解放するまで待ってください。