ローカル Agent による WebChat 操作

ローカルの coding Agent が herdr-mcp 経由で、対応する WebChat セッションを作成・継続・引き継ぎ・観測する方法。

このページはローカル Agent 側、つまり Pi、Codex、Claude など、この開発マシン上で動き、ChatGPT/WebChat に作業の一部を任せたい coding Agent 向けです。答える問いは一つです。

私はローカル Agent です。どういうとき herdr-mcp 経由で Web 会話を操作すべきで、実際に何ができて、どう進めれば identity・冪等性・delivery evidence を壊さないのか。

Web AI は Herdr のブラウザ能力の唯一の呼び出し元ではありません。このページは、ユーザーが個別の API 名を教えなくてもローカル Agent が正しい能力に到達できるようにするためにあります。

1. これは何か#

Herdr-MCP には二つの方向があり、契約は別物です。

コピーWeb AI（planner）                      ローカル coding Agent（planner/executor）
      │                                          │
      │ MCP + OAuth Connector                    │ herdr-mcp CLI
      ▼                                          ▼
                    herdr-mcp（制御と状態の境界）
                        ├─ Continuity / Work Memory
                        └─ Browser / WebChat control
                                    │ ローカルの信頼経路
                                    │（Native Messaging → 0600 socket）
                                    ▼
                        Chrome extension / 登録済み browser endpoint
                                    │
                                    ▼
                            ChatGPT / 対応 WebChat

• Web AI → herdr-mcp → 開発マシン：Web AI が計画し、herdr-mcp がこのマシンのツールを与えます。
• ローカル Agent → herdr-mcp → WebChat/browser：ローカル Agent が計画と実行を担い、herdr-mcp が Web 会話への制御された経路を与えます。

どちらも同じ runtime、同じ Continuity journal、同じ browser registry に着地します。新しいメッセージバスは導入されず、第二のタスク状態権威もありません。ローカル Agent は既存の Continuity journal、Work Memory パーティション、browser リソース、browser control plane を再利用します。

Web 会話はターン単位の遠隔コラボレータです。Herdr-MCP は境界付きのメッセージを送り、それが配送されたかを記録し、永続タスク状態は Continuity に置きます。ページではありません。

2. いつ使うか#

ローカル Agent の典型的な用途：

• 同じ ChatGPT Project 内で新しい会話を開始し、作業を一箇所に保つ。
• すでに binding された WebChat 会話で作業を続ける。
• 既存の binding 済み session に次のメッセージを dispatch する。
• 依存する前に browser/WebChat session が生きているかを確認する。
• ローカル文脈が満杯に近いとき、または作業を Web AI 側へ渡すときに canonical handoff を行う。
• Continuity/Work Memory で境界付きに履歴を復元し、その後会話で続ける。
• ローカル Agent のコード変更後、Web AI planner に引き継ぐ。

複数 WebChat / 複数アカウントの範囲は、返された browser registry と同じ広さです。検査した endpoint について herdr-mcp webchat resources が返した session_ref だけが操作対象で、返らないものは addressable ではありません。明記がない限り実験的機能として扱うものはありません（現在の境界 を参照）。

3. 使わない場合#

• 一般の Web サイトのスクレイピング、対応 WebChat 以外のページ。
• ファイルのダウンロードやマシン間のデータ移送（extension はファイル転送路ではありません）。
• Playwright / Selenium / AppleScript の汎用代替としての利用。
• アカウント認可、consent プロンプト、extension の制御スイッチの回避。
• Project / アカウント / 会話 / session 識別子の推測。
• ユーザーの非公開 ChatGPT 履歴本文の読み出し。ローカル journal に取り込まれていない会話は MCP だけでは取得できません。
• 無関係な作業でユーザーの通常ブラウジングを操作すること。

4. 前提条件#

以下はすべて実際の前提であり、形式要件ではありません。

1. このマシンの herdr-mcp runtime が健全であること。

   コピーherdr-mcp status
   herdr-mcp doctor
   

   ソース開発 runtime の場合、まず herdr-mcp dev status でチャネルを確認し、どの runtime バイナリと話しているかを把握してください。CLI は常に現在有効な runtime だけと通信し、リポジトリのビルド成果物は使いません。
2. browser extension がインストールされ、その runtime に接続されていること。

   コピーherdr-mcp native-host status
   herdr-mcp extension standalone status
   

   ブラウザ操作は extension が省略できない場面の一つです。extension がブラウザ側の実行境界です（Web AI → 開発マシンの主要経路は extension なしでも動作しますが、こちらは違います）。
3. WebChat 制御に同意した登録済み endpoint。

   コピーherdr-mcp webchat endpoints
   

   登録済み endpoint は既定で consent.webchat_control: true を報告し、ローカルの WebChat Control スイッチはありません。consent.tool_bridge と consent.tool_bridge_workstation_mutation は別機能（ページ内 Web AI ツール呼び出し）の独立 gate のままで、ここでは不要です。
4. extension が観測した、サインイン済み provider アカウント。 アカウント、ChatGPT Project（space リソース）、会話（session リソース）はこの endpoint 配下のリソースとして現れます。
5. 資格情報を手で扱わないこと。 herdr-mcp CLI は first-party のローカルクライアントであり、信頼されたローカル呼び出し grant を自身で付与します。runtime bearer、ブラウザ cookie、Connector 資格情報を表示・コピー・要求してはいけません。

ChatGPT Connector（OAuth MCP）はもう一方の方向です。ローカル Agent が binding 済み WebChat を操作するのに Connector は不要で、Connector を入れてもブラウザ操作権が自動で得られるわけではありません。

HERDR_ENV はこの面とは無関係です。ネイティブ Herdr の pane/tab/workspace 操作を制御するもので、webchat・continuity・memory には影響しません。

5. 能力の検出#

ハードコードされた API 名や記憶の中の *_ref から始めないでください。まず現在の能力と identity 集合を検出します。

コピー# 1. 登録・同意済みのブラウザはどれか
herdr-mcp webchat endpoints --limit 5

# 2. その endpoint 配下に何があるか
herdr-mcp webchat resources --kind account
herdr-mcp webchat resources --kind space
herdr-mcp webchat resources --kind session --parent-ref SPACE_REF

# 3. このオブジェクトは何で、いま操作可能か
herdr-mcp webchat inspect SESSION_REF

読み方：

herdr-mcp webchat resources は actuation_evaluated: false と actuation_reason: "not_evaluated_by_list" を返します。リスト結果は健全性や consent の signal ではありません。

私有メソッド herdr_mcp.browser_endpoint.inspect は extension が宣言した能力操作（capabilities.operations）と入力契約（テキストのみ、サイズ上限、添付非対応）も公開します。機械可読な能力詳細が必要なときに使い、リソース単位の結論には herdr-mcp webchat inspect を使います。

現在サポートされる browser 変更操作（それ以外は fail closed で code: "unsupported" を返します）：

能力が無い場合は正直に報告し、別の自動化スタックへ黙って切り替えないでください。

6. 基本ワークフロー#

ワークフロー A —— 既存の WebChat/browser session を確認する#

コピーherdr-mcp webchat endpoints --limit 5
herdr-mcp webchat resources --kind space
herdr-mcp webchat resources --kind session --parent-ref SPACE_REF --limit 10
herdr-mcp webchat inspect SESSION_REF

実際に使った identity チェーン（endpoint → account → Project（space）→ session）と observation_generation を報告してください。session ref / Project ref はこのマシンに束縛された値（br_*/bep_*）で、可搬な名前ではなく、ラベルから推測してはいけません。

関連する Work Memory パーティションがある場合、その locator（project_ref、repo_id、work_chain_id）は herdr-mcp memory / Continuity の結果から得ます。browser ref から得ることも、リポジトリパスから合成することもありません。

ワークフロー B —— 既存 Project 内に新しい会話を作る#

コピーherdr-mcp webchat create \
  --endpoint-ref ENDPOINT_REF \
  --provider chatgpt \
  --account-ref ACCOUNT_REF \
  --space-ref SPACE_REF \
  --display-label "短いタスクラベル" \
  --message "新しい会話の最初のメッセージ" \
  --expected-generation OBSERVATION_GENERATION \
  --idempotency-key ONE_STABLE_KEY \
  [--work-chain-id WORK_CHAIN_ID]

補足：

• --space-ref は ChatGPT Project です。アカウント既定の会話を本当に意図する場合のみ省略します。
• --display-label はラベルであり identity ではありません。identity は返された session ref です。
• --expected-generation は対象スコープで観測した generation を渡します。古い generation は誤った対象に適用されず拒否されます。
• --work-chain-id は既存の Work Memory チェーンへの紐付けです。捏造しないでください。
• 一つの意図 = 一つの idempotency key。送信前に記録し、再試行判断でも同じ key を使います。
• 現在非対応の能力（browser_space.create 経由の Project 作成、composer の reasoning/apps 選択など）を別ツールで模擬してはいけません。

成功時は ok: true と作成されたリソース／delivery state が返ります。自分で組み立てた URL ではなく、返された session_ref を報告してください。

ワークフロー C —— メッセージを dispatch し結果を観測する#

コピーherdr-mcp webchat send \
  --session-ref SESSION_REF \
  --message "次の指示" \
  --expected-generation OBSERVATION_GENERATION \
  --idempotency-key ONE_STABLE_KEY \
  [--work-chain-id WORK_CHAIN_ID]

herdr-mcp webchat dispatch-status DISPATCH_ID

send は dispatch オブジェクトを返します。

タイムアウト後の「再開」は再送ではありません。同じ dispatch_id で dispatch-status を読み、uncertain なら herdr-mcp webchat inspect SESSION_REF と実際のページを再観測してから判断します。browser_offline / resource_unavailable は対象が現在到達不能という意味です。待って再観測し、生存確認のために idempotency key を変えないでください。browser_session.create では、返された証拠が message_submitted=false かつ retry_safe=true を明示的に証明する一時的な resource_unavailable に限り、再観測後に同じ key で再 actuation できます。Runtime はその reservation を not_applied として永続化します。uncertain は reconciliation 専用のままで、source_session_unavailable が自動的に別の対象へ切り替わることもありません。

実行中ターンの停止は別の私有操作（herdr_mcp.browser_dispatch.stop）で、現在 CLI ラッパーはありません。CLI しか無い場合はその境界を正直に報告し、停止したふりをしないでください。

ワークフロー D —— Canonical handoff#

canonical handoff の準備は読み取り専用の私有メソッド herdr_mcp.browser_handoff.prepare です。

コピーcontinuity_id（永続タスク状態）
   └─ herdr_mcp.browser_handoff.prepare { continuity_id, source_url, [objective], [work_chain_id], [handoff_id] }
        ├─ handoff.message                                   （唯一の canonical メッセージ）
        ├─ automatic_delivery.params = { source_url, message, work_chain_id }
        ├─ manual_delivery.copy_prompt  == handoff.message    （バイト単位で同一）
        └─ herdr_mcp.browser_session.create（automatic_delivery.params をそのまま渡す）
             └─ 対象会話の最初の手順は continuity.resume <continuity_id>

安全を担保する規則：

• prepare は読み取り専用で、登録済みのソース会話から対象ルート（account/Project）を導出します。endpoint、account、Project、generation、device id を先に列挙しません。
• 自動配送と手動の Copy Prompt は同じ canonical メッセージを使います。二つ目の handoff メッセージを書いたり、エンコード・難読化したり、transport を変えたり、拒否された payload を再帰的に包んだりしてはいけません。
• 対象会話は既存の continuity_id を continuity.resume で再開することから始めます。handoff は二つ目の Continuity チェーンを作らず、ページはタスク状態権威になりません。
• 再開後、対象は live な workspace / Git / runtime を再確認します。journal は履歴であり、live な真実ではありません。
• 自動配送が Herdr の execution/result フィールドを一切返さない場合、その結果だけからワークステーション実行を推測してはいけません。準備済みの Copy Prompt を使うか、明示的な dispatch が存在する場合はその dispatch を再観測します。
• delivery が不確実な間は、reconciliation で最初の試行が適用されていないと証明されるまで Copy Prompt 経路を開きません。したがって推測で二つ目の会話を作ることはできません。

正式な入口：

コピーherdr-mcp webchat handoff \
  --continuity-id hc:... \
  --source-url 'https://chatgpt.com/g/g-p-.../c/...' \
  [--objective TEXT] [--work-chain-id ID] [--handoff-id ID] \
  [--idempotency-key KEY] [--prepare-only]

webchat handoff は上記 canonical 実装の薄いローカルラッパーであり、二つ目の handoff 実装ではありません。

• Web planner と extension HUD と同じ経路で runtime に canonical packet（herdr_mcp.browser_handoff.prepare）を要求します。
• その packet 自身の automatic_delivery.params をそのまま source ベースの browser_session.create に渡します。CLI がメッセージを組み立てたり、書き換えたり、再エンコードしたりすることはありません。
• --source-url は監査アンカーであり唯一のルート入力です。runtime が登録済み会話から既存 WebChat ルート（endpoint / account / Project）を解決するため、コマンドラインに routing id は不要です。
• --objective / --work-chain-id / --handoff-id は同じ prepare 入力に対応します。--handoff-id は packet に安定した identity を与えます。

出力は canonical packet と配送証拠です。

冪等性：一つの logical handoff は一つの key を使います。--idempotency-key を渡さない場合、CLI は canonical な handoff_id を再利用します。配送状態を探るために key を変えず、automatic_delivery と、dispatch がある場合は dispatch-status を確認してください。CLI は uncertain な配送を自動再試行しません。

--prepare-only は配送をスキップし、packet のみを返します（automatic_delivery.attempted=false、reason="prepare_only"）。

準備済みは配送済みではありません。 ソース会話が未登録、または browser control が利用できない場合でも packet と manual_delivery.copy_prompt は返り、automatic_delivery.attempted=false と runtime の理由が付きます。これは手動継続に使える結果ですが、完了した handoff ではありません。実際に会話が作成されたのは automatic_delivery.completed=true（つまり delivery_state=applied）のときだけです。uncertain はそのまま報告され、自動再試行はしません。

herdr-mcp webchat create --source-url URL は、正確な source-window affinity のために source ベースの経路を利用し、呼び出し側が endpoint/provider/account ref を指定する必要はありません。ローカル CLI は trusted Unix IPC 経由で Runtime に同じ canonical source resolver を使わせ、exact route から trusted local grant を作ります。create payload の route 入力は引き続き source_url だけで、Runtime は mutation 前にもう一度解決・検証します。同じ canonical URL を複数の browser session が観測している場合は曖昧とみなし、browser_canonical_url_ambiguous で fail closed します（source-anchored create が別 profile/account の session に解決されることはありません）。その間に route が変われば exact grant が一致せず fail closed となり、古い endpoint へ誤配送しません。明示的な direct create では endpoint/provider/account と generation が引き続き必要です。

7. ローカル Agent の例#

ローカル Agent への依頼例：

「binding 済みの ChatGPT Project に新しい会話を作り、永続 continuity hc:... を引き継ぎ、対象会話にまず resume させてから、そちらで現在のタスクを続けて。」

Agent は次の順で進めます。

1. 能力検出 —— herdr-mcp webchat endpoints、herdr-mcp webchat resources --kind space、herdr-mcp webchat inspect SPACE_REF。登録済み endpoint は consent.webchat_control: true を報告します。observation_generation と観測済みの正確な identity を記録します。
2. identity の解決 —— 返されたリソースから正確な endpoint_ref / account_ref / space_ref を選びます。推測せず、別マシン・別 Project の ref を再利用しません。
3. 永続状態の解決 —— herdr-mcp continuity resume hc:...（先に境界付きの herdr-mcp continuity search ... --project-path <checkout> でも可。ただし confirmation_required に従うこと）。これがタスク永続状態の唯一の情報源です。
4. canonical handoff を実行 —— herdr-mcp webchat handoff --continuity-id hc:... --source-url '<正確な会話 URL>'（チェーンに work chain があれば --work-chain-id を追加）。canonical な準備と自動配送を一度に行います。--prepare-only は packet だけを返します。
5. 配送の検証 —— automatic_delivery.completed / delivery_state を読みます。completed=false なら何も作成されていません。manual_delivery.copy_prompt を使い、dispatch がある場合は herdr-mcp webchat dispatch-status <dispatch_id> で確認します。新しい --idempotency-key で再試行しないでください。
6. 報告 —— 正確な session_ref、delivery state、対象に依頼した内容を返します。continuity.resume は対象側で実行されること、準備済みは完了した handoff ではないことを明示します。

実際のアカウント id、トークン、本番 secret を計画・メッセージ・報告に含めないでください。CLI が返す ref は不透明な識別子で、CLI に戻したりユーザーに報告してよいものですが、資格情報ではありません。

8. 配送と再試行のセマンティクス#

追加規則：

• 一つの意図 = 一つの idempotency key。 同じ key の再実行は記録済み dispatch（replayed: true）を返し、二重実行しません。
• identity を合成しない。 account、Project、session、generation、Continuity/work-chain の識別子はすべて返された結果から取得します。
• delivery evidence は楽観より優先。 タイムアウトは配送ではなく、エラー欠如も配送ではなく、端末や会話のスクロールバックは settlement 証拠ではありません。
• 変更は account スコープで直列化されます。競合する変更を並列化しないでください。
• 第二の状態権威を作らない。 ページ、Project、会話は Continuity/Work Memory の代替になりません。

9. Continuity / Work Memory / Browser session の違い#

典型的な失敗は、これらを一つの「session id」に潰すことです。continuity_id、work_chain_id、session_ref、space_ref、endpoint_ref、Herdr pane/workspace id は別の名前空間で、寿命も異なります。

10. トラブルシューティング#

11. 現在の境界#

存在しない能力に対して文書や実装を積み上げないよう、ここを明示します。

• 非対応の browser 操作（runtime は code: "unsupported" を返す）：browser_space.create、browser_space.open、browser_message.append、browser_composer.set_reasoning、browser_composer.set_apps、および reasoning_effort か required_apps を伴う browser_dispatch.submit。
• 対応しているが現在 CLI ラッパーが無いもの：browser_dispatch.stop、browser_endpoint.inspect、browser_space.inspect。runtime MCP の私有メソッド境界から到達できます。browser_session.open は herdr-mcp webchat open で利用できます。
• Handoff：canonical な準備経路は herdr_mcp.browser_handoff.prepare で、ローカル Agent は herdr-mcp webchat handoff から使います（再利用し、続けて source ベースの配送を行う）。Web planner と extension HUD は引き続き私有メソッドを直接呼びます。通常の webchat create も正確な source-window affinity のため --source-url を受け取れますが、handoff packet の生成や書き換えは行いません。
• ego-browser は開発/UAT インフラで、ユーザー依存でも、この control plane の代替でもありません。
• 公開されていないもの：ユーザーの非公開 ChatGPT 履歴本文の読み出し、dispatch 契約での添付送信、任意の DOM アクセス、registry が報告しない provider。

これは roadmap の約束ではなく実装の事実です。依存する前に、インストール済み runtime で必ず確認してください。

関連ドキュメント#

• ブラウザ連続性 — ページ側の continuity、Auto/Queue、手動 handoff と Copy Prompt。
• Browser Control Center — Chrome Side Panel の workspace/pane/binding 状態。
• ブラウザ拡張 — extension の identity、ローカルセキュリティ境界、JSON → MCP bridge。
• CLI リファレンス — herdr-mcp の全コマンド面。
• トラブルシューティング — runtime、link、ブラウザの診断。