gpt-connector

v0.16.3

Published

5 days ago

ログイン済みChatGPTとGrokのWeb runtimeへAIクライアントから相談するローカルconnector

0High
0Medium
0Low

quolu

GPT Connector

Claude・Codex・Grok・Cursorから、ログイン済みChatGPTとGrokの公式Web runtimeへ相談するローカルconnector。ChatGPTの通常Chat・画像生成と、Grok Chatの本文相談に対応する。

kitepon.devのクオが開発・メンテナンスしています。

所有境界

本repositoryはinstall、MCP設定、Chrome runtime、job/session、state、schema／migration、添付、 diagnostics、recovery、update、releaseを所有します。単独cloneでもこのrepository内のREADMEと docs/README.mdだけで導入・運用・復旧・公開まで完結します。 dotagentsは任意の工場統合、host別wire、製品間compatibilityと統合受入を担当しますが、gpt-connectorの運用を制御せず、実行時の必須依存でもありません。正規MCP IDはgpt_connectorです。 MarkItDownは別区分の第三者CLIです。

ブラウザは認証・integrity・attestation・conversation lifecycleの実行環境として使う。composer、送信button、回答DOM、React fiberは操作・参照しない。

[!WARNING] consumer Chatの非公開Web runtimeとminified bundleに依存する実験的実装。OpenAI／xAIの公開・安定APIではない。bundle contractが変わった場合はRUNTIME_DRIFTで停止し、別方式へ自動fallbackしない。

現在ソース版は[email protected]。setupがnpm導入・MCP登録・ブラウザ準備・CodexへのSteer接続・診断を所有します。通常Chatは指定を省略すると「最新」の右端を使います。選べる段階はchatgpt_modelsのlive catalogで確認します。公開済みversionは npm、ソースと変更履歴は GitHub repositoryを正とします。

成立済み機能

通常Chatのone-shot送信と自動archive。
受付時に返す会話IDによる複数turn継続。専用Chromeのpageを保持すればMCP再接続後も利用できる。
Codex（DesktopまたはCLI）からの相談を10秒ごとにコードで監視し、完了時に親へ自動Steer。Aitermのインストールは不要。
Cursor親（DesktopとCLI）からの相談は受付後に戻る。作業中は次のツール返りへ公式hookで差し込み、idleならreceiveCommand（parent_delivery.wait_process）を回した背景シェルの完了で起こす。配送はAitermと同じ共通パッケージが行う。
explicit closeとserver archive read-back。
Webの「最新」と一致する5段階の選択と、省略時の右端選択。
live catalog取得と、既存のmodel／thinking effort明示選択。
ChatGPT通常枠の画像生成、Library相関read-back、安全なローカル保存。
Work-only modelの除外。
非対応model／effortの送信前拒否。
全regular fileのChatGPT正規添付。known extensionは標準MIME、unknown extensionはapplication/octet-stream。
workspaceRoot境界、glob、MIME、size、秘密file denylistの送信前検証。
256KiB CDP chunk転送とpage側SHA-256照合。
server attachment metadata read-backとモデル読取確認。
caller既知slugによるconsult冪等性、terminal result回収、owner-only durable job台帳。
別のAIクライアントからの相談を同時に受け付け、各会話を独立して監視・配送する。
Grok公式Web runtimeの本文相談、同時送信、会話継続、Codex／Cursor親への完了通知。Grok Chatのmodeはauto・fast・expert・heavyから選べる。添付と画像生成は対象外。
upload／conversationを作らないdry-run、既存diagnostics、factory diagnostics。
CLIとstdio MCP adapter。

前提

Node.js 22以上とnpm（macOS・Windows・Linux）。
liveブラウザ機能にはmacOS、Windows、またはLinuxの公式Google Chromeと、利用するChatGPT／Grokへログインできるaccount。
Linuxの専用ChromeはローカルX11（XWaylandを含む）のDISPLAYで表示を確認する。X11が無いWayland専用セッションはlive未対応。
Windowsの操作シェルはPowerShell 7。
Codexへの自動SteerにはmacOS・Windows・Linuxの公式Codex Desktopの同梱CLI、無ければ通常のCodex CLI（どちらも0.154以上）。公式キューと同期hookを使い、Codexの起動設定を差し替えない。

sourceからbuildする場合だけpnpm 11以上も必要。

導入・更新

npx --yes gpt-connector@latest setup

初回も更新も同じ入口を使う。実行した版を公式npmでglobal installしてから、導入済みCLIへ処理を引き継ぐ。 Claude・Codex・Grok・Cursorのユーザー設定へgpt_connectorを登録し、MCP initialize／13 tools／診断応答とstate読取りを確認する。既存command、args、env、モデル、認証、他MCP、利用者のtimeout・無効化・ツール制限は保持する。変更前の設定は~/.gpt-connector/setup-backups/へtarで保存する。

Mac、Windows、LinuxではstartBrowser／showBrowserが専用Chromeを準備する。ログインが必要なら画面を表示し、 action_requiredで停止する。そのChromeで手動ログインしてから同じコマンドを再実行する。パスワード入力や認証challengeの自動化はしない。ログイン状態は~/.gpt-connector/browser-profile/へ保存し、通常の起動・更新では再利用する。ログアウトやChatGPTの認証失効時だけ再ログインする。 Grok初回利用時はgpt-connector browser start --provider grokで同じ専用ChromeにGrokのtabを準備する。Grok側のログインが必要なら表示した画面で手動ログインし、同じコマンドを再実行する。MCPのGrok toolはこの準備を自動で試みる。 SSH転送されたCDP endpointで既にGrok tabへログイン済みなら、Grok toolは転送先から直接接続する。Grok tabの初回準備と手動ログインはChromeを所有する端末で行う。 WindowsでSSHから同じ端末の専用Chromeを操作する場合、ログイン中の画面とSSHが別sessionでも、既存Chromeのwindow操作は製品が画面側のsessionで実行する。画面上のGrokログインは本人が行い、grok-doctorがreadyになってから送信する。

Codexを登録するMac、Windows、LinuxではSteer接続も準備する。codexSteer.status=restart_requiredならCodexを完全終了して再起動する。起動用の中継、ログイン時の設定、確認・解除まで本製品が所有する。Aitermなど別製品の導入は必要ない。詳細はCodexへの自動Steerを参照。

導入済み版での再実行と、読み取り専用の診断:

gpt-connector setup
gpt-connector setup --check

| 機能 | macOS | Windows | Linux | | --- | --- | --- | --- | | npm導入・4AIへのMCP登録 | 対応 | 対応 | 対応 | | MCP initialize・tools list・診断応答 | 対応 | 対応 | 対応 | | sessionsによる既存job読取り・state診断 | 対応 | 対応 | 対応 | | 専用Chrome起動・ChatGPTのlive model・Chat・画像・添付 | 対応 | 対応 | 対応（公式ChromeとX11） | | Grok Chatのmode取得・本文相談・会話継続 | 対応 | 対応 | 対応（公式ChromeとX11） | | Codexへの自動Steer | 対応 | 対応 | 対応 | | Cursor親への差し込みと背景受信 | 対応 | 対応 | 対応 |

setupはreadyで終了0、ログイン待ち・Codex再起動待ち・失敗で終了1、この端末でliveブラウザを準備できない（非対応OS、ChromeかX11の無いLinux、9223が他端末のChromeへの転送）が対応機能の確認は済みなら partialで終了2を返す。registrationsのAI別結果を読み、未対応を成功として扱わない。各AIは新しいセッションで設定を読み込む。setupのMCP確認と、既存AIセッションへの反映は別の確認項目である。

対象AIや既存Codex project設定を指定できる。

gpt-connector setup --ai claude,codex,grok,cursor
gpt-connector setup --ai codex --codex-config /absolute/project/.codex/config.toml

詳しい保存先、停止条件、移行契約はAI installer向けセットアップ契約を参照。

専用Chromeの運用

Macのbrowser startは正規専用PIDだけをAppKit hiddenへ移し、公式origin・認証・page bridge・WindowServer表示window 0件を確認する。 cold startでは窓なしChromeのCDP browser endpointからbackground ChatGPT targetを作る。 CDP minimizedは作成時のhintだけで、非表示の最終判定には使わない。通常ChromeやOracle profileは使用しない。

gpt-connector browser showは正規専用PIDを表示し、unhiddenかつ表示window 1件以上を確認する。 Chrome更新時のsmokeはbrowser start、models、hidden中のchat、必要時のbrowser showで行う。

Windowsでは標準WMIのprocess作成で、呼出元の終了jobに属さない専用Chromeを起動する。Codex等の終了にChromeを巻き込まない。 9223の所有PID・実行file・ネイティブ解析した引数を照合し、そのPIDのChrome windowだけをWin32 APIで非表示／再表示する。呼出元とChromeが別sessionなら、ログイン中の同じユーザーの対話sessionで一時taskを実行し、結果を呼出元へ返す。taskと一時記録は終了時に削除する。所有確認と表示状態の読戻しが成立してから成功を返す。

Linuxでは公式の/opt/google/chrome/chrome（無ければgoogle-chrome-stable／google-chrome）を新しいsessionで起動する。呼出元の終了後もChromeは残る。--ozone-platform=x11で専用ChromeのwindowをX11に固定する。 9223の所有は/proc/net/tcpの127.0.0.1待受と、/proc/<pid>/exe・cmdlineの専用profileで照合する。表示制御は、Chrome processのDISPLAY（/proc/<pid>/environ）、呼出元のDISPLAY、/tmp/.X11-unix上のローカルXを順に試し、そのPID（と子孫）のclass Google-chrome windowだけをUnmap／Mapする。再表示時は_NET_ACTIVE_WINDOWで前面へ出す。複数DISPLAYがあるホストでは、起動時に使うDISPLAY（例: エージェント画面の:12）を揃えるか、上記の探索に任せる。表示の正本はX11のmap stateであり、CDPのminimizedは作成時のhintのまま使わない。

source setup

git clone https://github.com/kitepon/gpt-connector.git
cd gpt-connector
pnpm install
pnpm check
pnpm build

read-only model smoke:

gpt-connector models --endpoint http://127.0.0.1:9223

one-shot Chat smoke:

gpt-connector chat \
  --endpoint http://127.0.0.1:9223 \
  --prompt '「確認済み」とだけ返信してください'

--level 高のように段階名を指定できます。--levelを省略すると「最新」の右端を使います。

Grok Chatの本文相談:

gpt-connector grok-doctor
gpt-connector grok-modes
gpt-connector grok-consult --prompt '設計案を検討してください' --slug grok-review-001 --mode expert --keep-open
gpt-connector grok-sessions --slug grok-review-001

同じGrok会話へ続ける時は、新しいslugと返されたsessionIdを--session-idへ渡す。最後はgrok-close --session-id <uuid>でGrok会話をsoft deleteする。keep-openを省略した新規相談はtemporary chatとして送る。

--modeはauto・fast・expert・heavyから選び、省略時はauto。buildはGrok Chatの送信対象外。Grokのmode一覧と現在の選択はgrok-modesで確認できる。回答のrequestedModeは送信したmode、reportedModelとresolvedEffortはGrokが回答に記録したモデルIDとエフォートを示す。Webの回答記録から自動modeの内側で使われた具体的なモデル名を確認できないため、resolvedModelはnullを返す。

CLIのchat／grok-chatはone-shot専用。consult／grok-consultのjobはdurable台帳へ残り、別processのsessions／grok-sessionsから回収できる。複数turnはCLI・MCPともにkeepOpenとsessionIdで継続する。

ChatGPT通常枠で画像を生成してworkspaceへ保存する。この経路はOpenAI APIを呼ばず、 OPENAI_API_KEYも使わない。利用可否と生成枠は、専用ChromeへログインしたChatGPT accountのplanに従う。

gpt-connector image \
  --endpoint http://127.0.0.1:9223 \
  --workspace-root "$PWD" \
  --output 'assets/generated/ad.png' \
  --prompt '白い背景に珊瑚色の円を置いた縦長広告素材' \
  --slug image-ad-001 \
  --model gpt-5-6-thinking \
  --effort min

caller timeout後は同じ画像promptを再送せず、sessions --slug image-ad-001でterminal stateを回収する。

正規添付のdry-run:

gpt-connector consult \
  --endpoint http://127.0.0.1:9223 \
  --workspace-root "$PWD" \
  --file 'docs/*.md' \
  --prompt '添付資料を監査してください' \
  --slug review-001 \
  --level 高 \
  --dry-run

--dry-runを外すと、検証済みbytesをChatGPTへ正規添付して通常Chatへ送る。caller timeout後は同じconsultを作り直さず、次で回収する。

gpt-connector sessions --slug review-001

診断:

gpt-connector doctor
gpt-connector --version

doctorはgpt-connector.diagnostics.v1 JSONを返します。接続可能ならoverall: "ready"、CDPや認証などが未準備ならoverall: "not_ready"と安定reasonCodeをstdoutへ返し、exit codeは非0です。診断はChromeの表示状態を変えず、uploadや会話作成も行いません。

更新・復旧・release

通常更新は公式npm packageだけを使います。更新後はversionと診断を確認し、Chromeを重複起動しません。

npx --yes gpt-connector@latest setup
gpt-connector setup --check

doctorがcdp_unavailableならbrowser startを使います。専用Chromeが止まっている時とChatGPT tabが閉じられている時は、MCPとCLIのChatGPT操作もこの準備を自動で試みます（9223が別の持ち主、たとえばSSH転送なら準備せず元の失敗を返します）。auth_requiredならbrowser showで専用Chromeを表示し、そこで手動ログインします。 runtime_driftなら製品更新または製品側修理が正規復旧です。別APIや通常Chromeへfallbackしません。 caller timeout後のconsult／画像jobは同じslugを再送せず、sessions --slug <slug>で既存jobを回収します。 process再起動前の非terminal jobはJOB_RECOVERY_UNAVAILABLEとなり、自動再送しません。非同期相談でCDP接続が失敗した場合は、その結果の保存と配送を終え、次の新しい要求で接続し直します。失敗した相談は再送しません。Chromeを再起動した場合、以前の会話IDは利用できません。

releaseの唯一の手順とgateはdocs/release.mdを正とします。工場へ切り離しても、 version同期、検証、main着地、npm公開、tag／GitHub Release、公開後smokeはこのrepositoryだけで実行できます。

BugHub factory 契約

既存の doctor と別に、factory consumer 用の versioned read-only JSON を提供します。

gpt-connector factory-diagnostics --json
gpt-connector runtime-errors diagnostics --json
gpt-connector runtime-errors snapshot --after-cursor 0 --limit 256 --json

factory-diagnostics は package version、既存 diagnostics schema、overall、consult job の state/job schema と migration、CDP、official origin、auth、runtime bridge、stdio MCP contractを固定 check ID で返します。Chrome/CDP/auth が未準備なら not_ready、live connector を提供しない host は unsupported、検査できない項目は unverified です。専用Chromeの未起動（cdpの reason chrome_idle）と、起動中ChromeでChatGPT tabが閉じられているだけの状態（chatgpt_tab_idle）は、次の利用で準備し直せる平常状態なので unverified です。ChatGPT tabにbridgeがまだ入っていない状態（runtime_bridgeの reason bridge_not_initialized）も、最初の操作で入るため unverified です。同じproviderのtabが複数開いている時は、bridgeが入っているtab（無ければtarget idの順で1枚）を選んで調べます。 MCPとCLIの操作も同じtabを使います。いずれも upload、conversation、archive、job 作成を行いません。

runtime-errors は product-owned local aggregate です。既定では収集も通信もしません。 collection を開始するのは次のどちらかの時だけです。

canonical dotagents factory config（POSIX: ~/.config/dotagents/factory-reporter.json、Windows native: %LOCALAPPDATA%\\dotagents\\factory-reporter\\config.json）が厳密な JSON shape で collection.enabled: true の時。
この端末で gpt-connector runtime-errors reporting enable --json を実行して、製品自身の送信を有効にした時。

自動登録は操作への影響・対処・復帰の観測で決めます。未送信の接続失敗、認証待ち、確認済みの取消は診断に残し、修理対象に登録しません。結果不明の操作失敗は原因未確定・復帰未確認としてhighを維持します。安全な復帰が確認された失敗はwarn、データ喪失・重複実行はhigh、サービス停止はfatalです。回数だけでは重大度を上げません。 gpt-connector runtime-errors events --jsonは直近128件のcode、時刻、原因の区分、影響、対処、復帰、登録判断を読み取ります。診断は端末内のprivateなruntime-errors.json.eventsに保存し、BugHubへ追加フィールドを送信しません。影響未確認は重大度nullです。新しい診断にはcontext.source（setup_live_checkまたはpublic_operation）と、最大4個の固定の失敗段階・契約タグを付けます。未知のタグはunknownにし、任意の例外本文・stack・URL・秘密値は残しません。setupのlive検査失敗はoperation_failedですが、相談失敗を観測した意味ではありません。原因・対処・復帰が未確定ならunknownとし、確認失敗と復帰未確認を根拠にhighを維持します。旧eventsは引き続き読めます。context付きeventsは0.16.2以前のstrict readerでは読めないため、巻き戻す前に診断ファイルを保全してください。集約store、snapshot、doctor/setupの公開JSON、BugHub送信形式は変更しません。原本、累計、時刻、fingerprintはこの分類変更で訂正しません。過去分の訂正は観測根拠を確認して正規のresolve/reopen入口から行います。通信環境の修理担当とアプリの修理担当は、診断を根拠に別途決めます。エラーコードだけでは責任を決めません。

factory config の reporting.enabled や、token/credential の存在だけでは collection を有効にしません。

実行時エラーをBugHubへ送る（既定は無効）

製品自身が、集めた実行時エラーをBugHubの受け口へ送れます。既定では通信しません。送るのは、次の2つがそろった端末だけです。

この端末で gpt-connector runtime-errors reporting enable --json を実行している。
BugHubの持ち主が置いた合鍵がある（POSIX: ~/.config/bughub/product-credentials/gpt-connector.json、 Windows native: %LOCALAPPDATA%\\bughub\\product-credentials\\gpt-connector.json。中身は url・key_id・secret）。本人所有・本人だけが読める・symlinkでないfileだけを使います。

送る中身は runtime-errors snapshot の記録（固定のcode・回数・時刻・版）だけです。prompt、path、生のerror、端末名は送りません。秘密値は通信に載せず、本文のHMAC-SHA256署名を付けます。受領済みにするのは、200・accepted: true・report_idの一致・応答の署名の一致がそろった時だけです。そろわない時は受領済みにせず、後からその時点の累計を送り直します。

自動で送るのは、未受領の記録がある時だけで、多くても1時間に1回です（errorを記録した時、MCP serverの起動時、 resolve／reopen の後）。認証や形の不正で断られた時は、合鍵か版が変わるまで自動では送り直しません。

gpt-connector runtime-errors reporting status --json   # 設定・合鍵の有無・直近の結果（秘密値と宛先は出さない）
gpt-connector runtime-errors reporting enable --json
gpt-connector runtime-errors reporting disable --json
gpt-connector runtime-errors report --json             # 今すぐ送る（1分に1回まで）

公開操作はすべて --json 必須です。

gpt-connector runtime-errors snapshot --json
gpt-connector runtime-errors diagnostics --json
gpt-connector runtime-errors ack 12 --json
gpt-connector runtime-errors resolve <sha256-fingerprint> --json
gpt-connector runtime-errors reopen <sha256-fingerprint> --json
gpt-connector runtime-errors compact --json

recordは固定 code/template、SHA-256 fingerprint、count、first/last seen、status、cursorだけを持ちます。 ack cursor は単調で、compact は retention を過ぎた resolved かつ ack 済み recordだけを削除します。 stateは製品所有directoryへ owner-only atomic writeし、symlink・権限 drift・schema改ざんを拒否します。 prompt、assistant response、file名/内容/digest、conversation/session/job ID、cookie/token、CDP dump、絶対path、生stack/stderrは入力・保存・出力できません。

AIクライアントとMCP

Claude・Codex・Grok・Cursorへの登録はsetupが担当する。Codexの既定登録先はユーザー設定。 trusted projectの.codex/config.tomlへ登録済みの場合は--codex-configにその絶対pathを指定する。 Codexへ不足時に補う設定の例（既存値は優先する）:

[mcp_servers.gpt_connector]
command = "gpt-connector-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 240
enabled = true
required = false
enabled_tools = ["chatgpt_models", "chatgpt_chat", "chatgpt_image", "chatgpt_close", "consult", "sessions", "diagnostics", "grok_modes", "grok_chat", "grok_consult", "grok_sessions", "grok_diagnostics", "grok_close"]

[mcp_servers.gpt_connector.env]
GPT_CONNECTOR_CDP_ENDPOINT = "http://127.0.0.1:9223"
# 任意。未指定時は $XDG_STATE_HOME/gpt-connector、
# XDG_STATE_HOME未設定時は ~/.local/state/gpt-connector
GPT_CONNECTOR_STATE_DIR = "/absolute/product-owned/state/gpt-connector"

設定の正本はOpenAI公式のModel Context Protocol設定。

npx --yes gpt-connector@latest setupを実行する。
ログインを求められたら専用Chromeでログインし、同じ入口を再実行する。
対象AIを新しいセッションで起動する。Codex project設定ではそのprojectを開く。
chatgpt_modelsでlive catalogを確認する。
second opinionはcaller既知slugを付けてconsultを呼ぶ。
画像生成はcaller既知slug、model、absolute workspaceRoot、relative outputを付けてchatgpt_imageを呼ぶ。
timeout時は再送せず、同じslugをsessionsへ渡す。
継続相談はkeepOpen=trueで会話を保持し、同じsessionIdと新しいslugで追加質問する。最後にchatgpt_closeを呼ぶ。Grokへ相談する場合はgrok_consultを使い、状態確認はgrok_sessions、終了はgrok_closeを使う。

MCP tools（consult／sessions／diagnosticsはChatGPT用。Grokにはgrok_で始まるtoolを使う）:

chatgpt_models: 「最新」の順序付きlevels、右端のdefaultLevelとdefaultModel、互換用model／effort一覧。
chatgpt_chat: 新規またはsession継続。既定keepOpen=falseで応答後archive。
chatgpt_image: 通常枠で画像を生成し、同一turnのLibrary fileを検証してworkspaceへ保存。
chatgpt_close: sessionをarchiveしてhandleを破棄。deleteは行わない。
consult: slug冪等化、会話の継続、任意の正規添付、level選択、dry-runを持つsecond opinion入口。wait=falseは回答完了前に受付結果を返す。
sessions: exact slug 1件の状態／sessionId／terminal resultを返す。uploadや会話を作らず、connector未起動時は台帳を直接読む。
diagnostics: 接続、bridge build、job／session／operation／upload buffer件数だけを返すread-only診断。
grok_modes: Grokのlive mode一覧と選択中のmode。Chat送信はauto・fast・expert・heavyに対応。
grok_chat: Grokへの本文送信。
grok_consult: 本文相談をslugで冪等化し、親への完了通知と会話継続に対応する。
grok_sessions: Grokの既知slugの状態と回答を返す。
grok_diagnostics: Grokの接続、bridge、jobを診断する。
grok_close: Grok会話をsoft deleteして継続を終える。

diagnosticsは専用Chrome未接続時もgpt-connector.diagnostics.v1のnot_ready結果を正常応答として返し、 read-only診断だけでruntime errorを記録しない。chatgpt_models、Chat、consult、画像生成など実操作の接続失敗は、引き続きruntime-error storeへ記録する。

正規server IDはgpt_connector。既存の別名登録はsetupが削除・改名しない。

同じChatGPT会話で相談を続ける

初回のconsultで前提を伝え、keepOpen=trueとwait=falseを指定する。

{"slug":"design-review-001","prompt":"この設計の前提は……。問題点を検討して。","keepOpen":true,"wait":false}

受付結果はstate="running"、result=nullと会話のsessionIdを返す。Codex親には完了時に自動Steerし、監視ループは不要。 Cursor親にはparent_deliveryとreceiveCommandが付く。作業を続ければ次のツール返りに回答が差し込まれ、ターンを終える前にreceiveCommandを背景シェルで回すとidle中の完了でも起きられる。監視ループは不要。他のクライアントでは回答をsessions({"slug":"design-review-001"})で取得する。 succeededを確認したら、返されたIDと新しいslugで追加質問する。

{"slug":"design-review-002","sessionId":"初回に返されたUUID","prompt":"その2案の保守費用を比較して。","keepOpen":true,"wait":false}

同じ会話に送った前提や資料の再送は不要。変更点と追加質問だけを渡せる。最後はchatgpt_close({"sessionId":"初回に返されたUUID"})で閉じる。 slugは1問い合わせの重複防止ID、sessionIdは複数問い合わせで共有する会話ID。 Codex親のconsultはwait指定にかかわらず受付後に戻り、コードが10秒ごとに完了を監視して自動Steerする。 Cursor親のconsultも受付後に戻る。ターンを終える前に、返ったreceiveCommandを背景シェルで回す。他のクライアントはwaitの既定がtrueで回答完了まで待つ。wait=falseの場合はsessionsで回収する。 CLIは回答完了まで待ち、consult --keep-openで得たIDを次回のconsult --session-id <uuid> --keep-openへ渡せる。

attachment contract

workspaceRootはabsolute directory、filesはそこからのrelative pathまたはglob。
spec順、glob内POSIX path順、realpath first occurrenceで決定的に解決する。
absolute file path、..、root外symlink、directory、empty fileを拒否する。
regular fileは形式を問わず元bytesのまま公式uploadへ渡す。一般的なtext、image、PDF、Office、archive、audio、videoには標準MIME、未知拡張子にはapplication/octet-streamを使う。localで内容解析・変換は行わず、ChatGPTが解釈できる形式かは公式runtimeが判断する。
最大20 file、20MiB/file、64MiB total。
.env*、key／certificate、credential／secret名など明白な秘密fileをoverrideなしで拒否する。
ChatGPTへ渡すのはbytes、basename、MIMEだけ。ローカルabsolute pathはpage contextやtool resultへ渡さない。
upload済みfileの削除手段は未成立。結果はretention=unknown、cleanup=not_supportedと返し、archiveをfile cleanupとは表現しない。
OpenAI公式は一般的なtext、spreadsheet、presentation、documentを対応対象として例示する一方、.gdocは非対応としている。pass-through可能であることは、モデルが内容を解釈できる保証ではない。

詳細はdocs/native-attachment-contract.md。

image generation contract

modelは必須。live catalogにないmodel／effortへfallbackせず、runtimeのresolved model／effortが requested selectionと完全一致しない場合もMODEL_RESOLUTION_MISMATCHで失敗する。
connectorが画像生成を明示する指示を加え、実画像が生成されなければIMAGE_NOT_GENERATEDで失敗する。
Libraryの「最新画像」は使わない。server conversationの同一turn_exchange_id／working_turn_idに属する tool messageと、Libraryのorigination_thread_id／origination_message_idが一致した画像だけを回収する。
MIME、byte数、dimensions、SHA-256をpage側とNode側で照合し、256KiB chunkで転送する。
workspaceRootはabsolute directory、outputはその配下のrelative .png／.jpg／.jpeg／.webp path。
root外path／symlink、MIMEと拡張子の不一致、既存file上書きを拒否する。複数枚はname-2.pngのように保存する。
local保存とdigest再検証が完了してから、生成元だけをChatGPT LibraryのRecently Deletedへ移す。成功時はretention=recently_deleted／cleanup=soft_deleted、失敗時はlibrary／failed、複数枚の一部だけ成功した場合はmixed／partialを返す。

session contract

session IDはconnector生成のopaque UUID。
server conversation IDやclient thread IDを含まない。
keepOpen=trueの会話は専用Chromeのpage bridgeが保持する。MCP切断・再接続後も同じIDで継続・closeできる。
page再読込、Chrome終了、bridge更新でIDは無効になる。SESSION_NOT_FOUNDを返し、新規会話への自動置換は行わない。
consult／grok_consultはkeepOpen=trueで受付時からsnapshot直下にsessionIdを保存する。成功結果のresult.sessionIdも同じ値。
次の質問は前の質問の成功後に送る。生成失敗時も受付IDは記録に残るが、初回生成の失敗では会話が破棄される。
同一sessionへの並行turnはSESSION_BUSY。
異なるAIクライアントのMCPプロセスから、別々のsessionへ同時に相談できる。
ChatGPTのone-shotとchatgpt_closeはserverのis_archived=trueをread-backしてから成功を返す。ChatGPTのdelete機能はない。
ChatGPTの回答生成後のarchive失敗はARCHIVE_FAILEDで返す。HTTPエラーの場合はstatusをメッセージへ含める。認証失敗はAUTH_REQUIREDを維持する。
Grokのone-shotはtemporary chatとして送る。保持した会話はgrok_closeでsoft deleteする。

consult／chatgpt_image／grok_consult jobは別契約:

callerが^[a-z0-9][a-z0-9._-]{2,63}$のslugを事前指定する。
同provider内の同slug／同fingerprintは既存snapshotを返し、再upload／再送しない。
同slugへ異なるinputはJOB_CONFLICT。
stateはqueued | uploading | submitted | running | succeeded | failed。
jobはowner-only JSONへatomic保存し、process再起動後もsessionsで回収できる。異なるMCPプロセスの更新は短いtransaction lockで順序付ける。
実行元が終了した非terminal jobだけをJOB_RECOVERY_UNAVAILABLEへ固定し、自動再送しない。他の実行元のjobは継続する。
ChatGPTとGrokは別のjob台帳を使う。既定のstate rootは$XDG_STATE_HOME/gpt-connector/（未設定時は~/.local/state/gpt-connector/）で、Grokの台帳はそのgrok/配下に置く。両方の台帳はversion 8で、version 1〜7を読み、初回書込み前にconsult-jobs.json.v<旧版>-backupへ元の台帳を保存する。旧版へ戻す場合は保存した台帳の復元が必要。
Codex／Cursor親への相談は配送状態も保存する。宛先情報は台帳の非公開項目で、MCP入力やsnapshotへ露出しない。

failure codes

INVALID_INPUT
AUTH_REQUIRED
CDP_UNAVAILABLE
RUNTIME_DRIFT
MODEL_NOT_AVAILABLE
EFFORT_NOT_SUPPORTED
MODEL_RESOLUTION_MISMATCH
FILE_NOT_FOUND
FILE_OUTSIDE_ROOT
SENSITIVE_FILE_BLOCKED
FILE_TYPE_NOT_SUPPORTED
FILE_EMPTY
FILE_LIMIT_EXCEEDED
UPLOAD_FAILED
UPLOAD_TIMEOUT
ATTACHMENT_READBACK_FAILED
IMAGE_NOT_GENERATED
IMAGE_READBACK_FAILED
IMAGE_DOWNLOAD_FAILED
IMAGE_OUTPUT_FAILED
IMAGE_CLEANUP_FAILED
CHAT_FAILED
STREAM_INCOMPLETE
SESSION_NOT_FOUND
SESSION_BUSY
ARCHIVE_FAILED
JOB_NOT_FOUND
JOB_CONFLICT
JOB_RECOVERY_UNAVAILABLE

秘密情報とログ

cookie、authorization、access／refresh token、integrity、attestation、conduit tokenを取得・保存しない。
CDP生dumpを保存しない。
server conversation IDをtool resultやlogへ出さない。
prompt、file本文、absolute pathをlogやjob台帳へ保存しない。
terminal assistant responseはcaller timeout後の回収に必要なため、fingerprint／状態／結果とともにowner-only job台帳へ保存する。
画像job台帳はrelative出力path、MIME、byte数、dimensions、SHA-256だけを保存し、Library ID、conversation ID、content URL、absolute pathを保存しない。
job台帳は製品所有state directoryに置き、他ツールの管理directoryやhookへ便乗しない。
.browser-profile/、log、temporary dumpはgit管理外。

architecture

AI client ──stdio MCP──> provider別connector ──CDP──> 専用Chrome
                            │                         ├─ ChatGPT page: Chat・添付・画像生成
                            │                         └─ Grok page: 本文Chat・mode選択
                            └─ provider別job台帳: slug・状態・回答・親への配送

異なるクライアントのjobは短いtransaction lockで台帳更新を順序付け、相談の実行中は各processが自分のjobを所有する。ChatGPTの添付は公式upload clientで送信し、画像はLibraryと回答の相関を確認して回収する。Grokは回答のサーバー読戻しで本文・mode・記録されたmodel／effortを照合する。

ChatGPTの現行runtimeは読み込まれたRspack module registryから、function source signature、object method shape、モデル一覧の読取りで必要な役割を一意検出する。候補が0件または複数なら実行しない。DOM selector、file input、React fiber、座標操作は本番経路に含まない。

license

MIT