codex-chatgpt-control 0.1.0-alpha.1

package/contracts/v1/fixtures/describe-runner-run.json

@@ -0,0 +1,31 @@
+{
+  "args": {
+    "existingTab": "true or explicit policy to claim a user-open Chrome tab instead of opening a replacement",
+    "prompt": "message to send or workflow-specific input",
+    "report": "optional redacted report settings",
+    "thread": "optional thread selector"
+  },
+  "blockers": [
+    "browser_bridge_unavailable",
+    "login_required",
+    "captcha",
+    "rate_limit",
+    "selector_drift"
+  ],
+  "defaults": {
+    "read": {
+      "format": "markdown"
+    },
+    "wait": true
+  },
+  "defaultTimeoutMs": 120000,
+  "examples": [
+    "const agent = chatgpt.agent({ name: \"reviewer\", instructions: \"Review deeply.\" }); await chatgpt.runner.run(agent, { input: \"Review this.\", thread: { type: \"new\" } });",
+    "await chatgpt.runner.run(agent, { input: \"Continue.\", thread: { type: \"url\", url: \"https://chatgpt.com/c/<conversation-id>\" }, existingTab: true });"
+  ],
+  "layer": "workflow",
+  "name": "runner.run",
+  "retryPolicy": "Return structured CommandResult failures; do not resubmit prompts unless the sequence policy permits unmatched-turn recovery.",
+  "risk": "medium",
+  "summary": "Agents-style facade: run a visible ChatGPT browser-control agent against input, files, thread, existing-tab, mode, and response options."
+}

package/contracts/v1/fixtures/doctor-bridge-upload.json

@@ -0,0 +1,34 @@
+{
+  "result": {
+    "context": {
+      "timestamp": "2026-06-06T00:00:00.000Z"
+    },
+    "data": {
+      "checks": {
+        "bridge": {
+          "message": "Codex cannot access the ChatGPT browser bridge from this backend process. In an ordinary shell this is expected; for a live Codex Chrome run, bootstrap the Chrome plugin runtime with setupBrowserRuntime({ globals: globalThis }) before using globalThis.agent.",
+          "remediation": [
+            "Ordinary shell: Treat browser_bridge_unavailable from a plain shell as an expected protocol/blocker-path result, not proof that Chrome, ChatGPT, or the Codex extension is broken.",
+            "Codex Chrome bootstrap: For a live run, initialize the Chrome plugin runtime in node_repl with setupBrowserRuntime({ globals: globalThis }), then set globalThis.browser = await agent.browsers.get(\"extension\") before calling createChatGPT({ agent: globalThis.agent }).",
+            "Python live bridge: For Python browser-bridge smokes, keep the bridge-hosted Node backend JS execution alive and run scripts/http_stdio_relay.mjs with CHATGPT_BROWSER_BACKEND_HTTP_URL; a plain Python-spawned Node subprocess cannot inherit globalThis.agent.",
+            "Extension availability: If this command was already running inside a bootstrapped bridge host, verify the Codex Chrome extension is installed and enabled, then restart Chrome or Codex before retrying."
+          ],
+          "status": "blocked"
+        },
+        "upload": {
+          "message": "Upload readiness requires a bootstrapped ChatGPT page.",
+          "remediation": [
+            "Codex Settings > Computer Use > Chrome > Permissions > Uploads: set to Always allow, or add chatgpt.com to the allowed upload domains.",
+            "Chrome chrome://extensions > Codex extension > Details: enable Allow access to file URLs."
+          ],
+          "status": "unknown"
+        }
+      },
+      "ready": false
+    },
+    "ok": true,
+    "status": "ok",
+    "warnings": []
+  },
+  "schemaVersion": "chatgpt.browser_control.command_result.v1"
+}

package/contracts/v1/fixtures/help-root.json

@@ -0,0 +1,6 @@
+{
+  "ok": true,
+  "requestId": "req_help",
+  "result": "ChatGPT browser-control SDK commands\n\nworkflow:\n- ask: Ask ChatGPT in a new or selected thread, optionally with files, wait/read, downloads, and reports.\n- askInThread: Open or claim an existing thread by URL, conversation id, title, or search query, then ask and read.\n- askWithFiles: Attach absolute local file paths, optionally set mode, ask, wait, and read.\n- askAndDownload: Ask ChatGPT to produce a visible downloadable output and save the latest exposed file.\n- runMessages: Run sequential prompts where later prompts can use earlier step data.\n- runner.run: Agents-style facade: run a visible ChatGPT browser-control agent against input, files, thread, existing-tab, mode, and response options.\n- responses.create: Narrow Responses-shaped adapter over the visible ChatGPT browser-control runner; rejects unsupported API-only fields before prompt submission.\n- copyLatest: Copy or DOM-read the latest assistant response with Markdown-first fidelity.\n- runPlan: Execute an inline SequencePlan or named macro through the existing sequence engine.\n- new-ask-read: Named macro: open a new thread, ask, wait, and read Markdown.\n- find-open-ask-read: Named macro: search history, open the first match, ask, wait, and read Markdown.\n- find-open-copy-latest: Named macro: search history, open the first match, and copy/read the latest response.\n- attach-ask-read: Named macro: open a new thread, attach files, ask, wait, and read Markdown.\n- ask-and-download: Named macro: ask in a new thread and download the latest file affordance.\n- two-turn: Named macro: run two sequential prompts in a new thread.\ndiagnostic:\n- doctor-upload: Named macro: preflight bridge, login, and upload permission remediation.\n- doctor: Preflight browser bridge, login, upload, download, clipboard, mode, and tool readiness.\nreport:\n- redacted-run-report: Named macro: create a redacted report for a supplied CommandResult.\n- createReport: Write a durable redacted run report for a command result.\nprimitive:\n- session.bootstrap: Attach to ChatGPT in Chrome and detect login/blocker state.\n- threads.new: Open a new ChatGPT thread.\n- threads.search: Search visible ChatGPT history by query.\n- threads.open: Open a thread by URL, conversation id, title, or search result.\n- messages.compose: Fill the composer without submitting.\n- messages.submit: Submit the current composer contents.\n- messages.ask: Compose, submit, optionally wait, and optionally read.\n- messages.wait: Wait for the latest assistant response to stabilize.\n- messages.readLatest: Read the latest message as Markdown, normalized text, blocks, or HTML.\n- messages.waitAndRead: Wait for completion and read the latest message.\n- files.attach: Attach absolute local file paths through visible ChatGPT upload controls.\n- files.downloadLatest: Download the latest visible ChatGPT file affordance.\n- response.copy: Click Copy response and return clipboard Markdown, with DOM fallback.\n- modes.set: Select a visible model or effort candidate when unambiguous.\n- tools.select: Select a visible ChatGPT tool when unambiguous.",
+  "schemaVersion": "chatgpt.browser_control.backend_response.v1"
+}

package/contracts/v1/fixtures/named-plan-two-turn.json

@@ -0,0 +1,39 @@
+{
+  "name": "run-messages",
+  "policy": {
+    "returnPartial": true,
+    "stopOnError": true
+  },
+  "steps": [
+    {
+      "command": "session.bootstrap",
+      "id": "bootstrap"
+    },
+    {
+      "command": "threads.new",
+      "id": "new"
+    },
+    {
+      "args": {
+        "read": {
+          "format": "markdown"
+        },
+        "text": "First visible turn.",
+        "wait": true
+      },
+      "command": "messages.ask",
+      "id": "first"
+    },
+    {
+      "args": {
+        "read": {
+          "format": "markdown"
+        },
+        "text": "Second visible turn.",
+        "wait": true
+      },
+      "command": "messages.ask",
+      "id": "second"
+    }
+  ]
+}

package/contracts/v1/fixtures/output-json-parse-success.json

@@ -0,0 +1,115 @@
+{
+  "result": {
+    "activeAgentName": "json-agent",
+    "context": {
+      "assistantTurnCount": 1,
+      "timestamp": "2026-06-06T00:00:00.000Z",
+      "title": "ChatGPT",
+      "turnCount": 2,
+      "url": "https://chatgpt.com/"
+    },
+    "data": {
+      "finalOutput": {
+        "score": 1,
+        "verdict": "ok"
+      },
+      "outputText": "{\"verdict\":\"ok\",\"score\":1}",
+      "thread": {
+        "title": "ChatGPT",
+        "url": "https://chatgpt.com/"
+      }
+    },
+    "finalOutput": {
+      "score": 1,
+      "verdict": "ok"
+    },
+    "interruptions": [],
+    "lastAgentName": "json-agent",
+    "newItems": [
+      {
+        "preview": "Return a JSON verdict.",
+        "redacted": true,
+        "role": "user",
+        "type": "message.submitted"
+      },
+      {
+        "format": "markdown",
+        "output_text": "{\"verdict\":\"ok\",\"score\":1}",
+        "role": "assistant",
+        "type": "message.completed"
+      }
+    ],
+    "ok": true,
+    "output": [
+      {
+        "preview": "Return a JSON verdict.",
+        "redacted": true,
+        "role": "user",
+        "type": "message.submitted"
+      },
+      {
+        "format": "markdown",
+        "output_text": "{\"verdict\":\"ok\",\"score\":1}",
+        "role": "assistant",
+        "type": "message.completed"
+      }
+    ],
+    "output_text": "{\"verdict\":\"ok\",\"score\":1}",
+    "state": {
+      "id": "run_fixed",
+      "resumable": false,
+      "thread": {
+        "title": "ChatGPT",
+        "url": "https://chatgpt.com/"
+      }
+    },
+    "status": "ok",
+    "steps": [
+      {
+        "command": "session.bootstrap",
+        "dataPreview": {
+          "browserName": "chrome",
+          "loggedIn": true,
+          "tabId": "unknown",
+          "url": "https://chatgpt.com/"
+        },
+        "endedAt": "2026-06-06T00:00:00.000Z",
+        "id": "bootstrap",
+        "ok": true,
+        "startedAt": "2026-06-06T00:00:00.000Z",
+        "status": "ok",
+        "warnings": []
+      },
+      {
+        "command": "threads.new",
+        "dataPreview": {
+          "title": "ChatGPT",
+          "url": "https://chatgpt.com/"
+        },
+        "endedAt": "2026-06-06T00:00:00.000Z",
+        "id": "new",
+        "ok": true,
+        "startedAt": "2026-06-06T00:00:00.000Z",
+        "status": "ok",
+        "warnings": []
+      },
+      {
+        "command": "messages.ask",
+        "dataPreview": {
+          "complete": true,
+          "prompt": "Return a JSON verdict.",
+          "responseText": "{\"verdict\":\"ok\",\"score\":1}",
+          "title": "ChatGPT"
+        },
+        "endedAt": "2026-06-06T00:00:00.000Z",
+        "id": "ask",
+        "ok": true,
+        "startedAt": "2026-06-06T00:00:00.000Z",
+        "status": "ok",
+        "warnings": []
+      }
+    ],
+    "warnings": []
+  },
+  "schemaVersion": "chatgpt.browser_control.run_result.v1"
+}

package/contracts/v1/fixtures/primitive-bootstrap-blocker.json

@@ -0,0 +1,43 @@
+{
+  "result": {
+    "blocker": {
+      "code": "codex_chrome_bridge_unavailable",
+      "kind": "browser_bridge_unavailable",
+      "message": "Codex cannot access the ChatGPT browser bridge from this backend process. In an ordinary shell this is expected; for a live Codex Chrome run, bootstrap the Chrome plugin runtime with setupBrowserRuntime({ globals: globalThis }) before using globalThis.agent.",
+      "remediation": [
+        {
+          "instruction": "Treat browser_bridge_unavailable from a plain shell as an expected protocol/blocker-path result, not proof that Chrome, ChatGPT, or the Codex extension is broken.",
+          "label": "Ordinary shell",
+          "userActionRequired": false
+        },
+        {
+          "instruction": "For a live run, initialize the Chrome plugin runtime in node_repl with setupBrowserRuntime({ globals: globalThis }), then set globalThis.browser = await agent.browsers.get(\"extension\") before calling createChatGPT({ agent: globalThis.agent }).",
+          "label": "Codex Chrome bootstrap",
+          "userActionRequired": false
+        },
+        {
+          "instruction": "For Python browser-bridge smokes, keep the bridge-hosted Node backend JS execution alive and run scripts/http_stdio_relay.mjs with CHATGPT_BROWSER_BACKEND_HTTP_URL; a plain Python-spawned Node subprocess cannot inherit globalThis.agent.",
+          "label": "Python live bridge",
+          "userActionRequired": false
+        },
+        {
+          "instruction": "If this command was already running inside a bootstrapped bridge host, verify the Codex Chrome extension is installed and enabled, then restart Chrome or Codex before retrying.",
+          "label": "Extension availability",
+          "userActionRequired": true
+        }
+      ]
+    },
+    "context": {
+      "timestamp": "2026-06-06T00:00:00.000Z"
+    },
+    "error": {
+      "message": "Codex cannot access the ChatGPT browser bridge from this backend process. In an ordinary shell this is expected; for a live Codex Chrome run, bootstrap the Chrome plugin runtime with setupBrowserRuntime({ globals: globalThis }) before using globalThis.agent.",
+      "name": "BrowserBridgeUnavailableError",
+      "recoverable": true
+    },
+    "ok": false,
+    "status": "blocked",
+    "warnings": []
+  },
+  "schemaVersion": "chatgpt.browser_control.command_result.v1"
+}

package/contracts/v1/fixtures/report-redaction-default.json

@@ -0,0 +1,16 @@
+{
+  "result": {
+    "context": {
+      "timestamp": "2026-06-06T00:00:00.000Z"
+    },
+    "data": {
+      "file": "[redacted:33 chars]",
+      "prompt": "[redacted:19 chars]",
+      "token": "[redacted:38 chars]"
+    },
+    "ok": true,
+    "status": "ok",
+    "warnings": []
+  },
+  "schemaVersion": "chatgpt.browser_control.command_result.v1"
+}

package/contracts/v1/fixtures/reports-create-redacted.json

@@ -0,0 +1,16 @@
+{
+  "result": {
+    "context": {
+      "timestamp": "2026-06-06T00:00:00.000Z"
+    },
+    "data": {
+      "bytes": 335,
+      "includeContent": false,
+      "path": "/tmp/codex-chatgpt-control/reports/contract-fixtures/fixed-contract-report.json"
+    },
+    "ok": true,
+    "status": "ok",
+    "warnings": []
+  },
+  "schemaVersion": "chatgpt.browser_control.command_result.v1"
+}

package/contracts/v1/fixtures/reports-summarize-redacted.json

@@ -0,0 +1,26 @@
+{
+  "result": {
+    "context": {
+      "timestamp": "2026-06-06T00:00:00.000Z"
+    },
+    "data": {
+      "blocker": {
+        "kind": "[redacted:26 chars]",
+        "message": "[redacted:258 chars]",
+        "visibleText": "[redacted:19 chars]"
+      },
+      "context": {
+        "timestamp": "2026-06-06T00:00:00.000Z"
+      },
+      "ok": false,
+      "status": "blocked",
+      "warnings": [
+        "[redacted:26 chars]"
+      ]
+    },
+    "ok": true,
+    "status": "ok",
+    "warnings": []
+  },
+  "schemaVersion": "chatgpt.browser_control.command_result.v1"
+}

package/contracts/v1/fixtures/responses-basic-success.json

@@ -0,0 +1,27 @@
+{
+  "schemaVersion": "chatgpt.browser_control.response.v1",
+  "response": {
+    "id": "chatgpt-browser-response-basic",
+    "object": "chatgpt.browser.response",
+    "created_at": 1780617600,
+    "status": "ok",
+    "output_text": "hi",
+    "output": [
+      {
+        "type": "message.completed",
+        "role": "assistant",
+        "output_text": "hi",
+        "format": "markdown"
+      }
+    ],
+    "browser_control": {
+      "visibleUi": true,
+      "resultStatus": "ok",
+      "thread": {
+        "url": "https://chatgpt.com/c/example-basic",
+        "conversationId": "example-basic",
+        "title": "Basic"
+      }
+    }
+  }
+}

package/contracts/v1/fixtures/responses-hidden-instructions-unsupported.json

@@ -0,0 +1,22 @@
+{
+  "response": {
+    "browser_control": {
+      "resultStatus": "unsupported",
+      "unsupported": [
+        {
+          "alternative": "Set instructionsMode: \"visible_prefix\" to send instructions visibly.",
+          "path": "instructions",
+          "reason": "Responses API instructions are hidden context, but ChatGPT browser control can only submit visible text."
+        }
+      ],
+      "visibleUi": true
+    },
+    "created_at": 1780704000,
+    "id": "chatgpt-browser-mq1l6o00",
+    "object": "chatgpt.browser.response",
+    "output": [],
+    "output_text": "",
+    "status": "unsupported"
+  },
+  "schemaVersion": "chatgpt.browser_control.response.v1"
+}

package/contracts/v1/fixtures/responses-unknown-field-unsupported.json

@@ -0,0 +1,22 @@
+{
+  "response": {
+    "browser_control": {
+      "resultStatus": "unsupported",
+      "unsupported": [
+        {
+          "alternative": "Use chatgpt.runner.run(...) for lower-level browser-control options.",
+          "path": "unknown_control",
+          "reason": "This field is not part of the narrow ChatGPT browser-control Responses adapter."
+        }
+      ],
+      "visibleUi": true
+    },
+    "created_at": 1780704000,
+    "id": "chatgpt-browser-mq1l6o00",
+    "object": "chatgpt.browser.response",
+    "output": [],
+    "output_text": "",
+    "status": "unsupported"
+  },
+  "schemaVersion": "chatgpt.browser_control.response.v1"
+}

package/contracts/v1/fixtures/responses-unsupported-previous-response-id.json

@@ -0,0 +1,22 @@
+{
+  "response": {
+    "browser_control": {
+      "resultStatus": "unsupported",
+      "unsupported": [
+        {
+          "alternative": "Use thread: { type: \"conversationId\", conversationId } or a ChatGPT thread URL.",
+          "path": "previous_response_id",
+          "reason": "This is an OpenAI API field that visible ChatGPT browser control cannot honestly support."
+        }
+      ],
+      "visibleUi": true
+    },
+    "created_at": 1780704000,
+    "id": "chatgpt-browser-mq1l6o00",
+    "object": "chatgpt.browser.response",
+    "output": [],
+    "output_text": "",
+    "status": "unsupported"
+  },
+  "schemaVersion": "chatgpt.browser_control.response.v1"
+}

package/contracts/v1/fixtures/responses-unsupported-temperature.json

@@ -0,0 +1,22 @@
+{
+  "response": {
+    "browser_control": {
+      "resultStatus": "unsupported",
+      "unsupported": [
+        {
+          "alternative": "No browser-control equivalent. ChatGPT web does not expose API temperature.",
+          "path": "temperature",
+          "reason": "This is an OpenAI API field that visible ChatGPT browser control cannot honestly support."
+        }
+      ],
+      "visibleUi": true
+    },
+    "created_at": 1780704000,
+    "id": "chatgpt-browser-mq1l6o00",
+    "object": "chatgpt.browser.response",
+    "output": [],
+    "output_text": "",
+    "status": "unsupported"
+  },
+  "schemaVersion": "chatgpt.browser_control.response.v1"
+}

package/contracts/v1/fixtures/run-basic-success.json

@@ -0,0 +1,36 @@
+{
+  "schemaVersion": "chatgpt.browser_control.run_result.v1",
+  "result": {
+    "ok": true,
+    "status": "ok",
+    "output_text": "hi",
+    "finalOutput": "hi",
+    "output": [
+      {
+        "type": "message.completed",
+        "role": "assistant",
+        "output_text": "hi",
+        "format": "markdown"
+      }
+    ],
+    "newItems": [
+      {
+        "type": "message.completed",
+        "role": "assistant",
+        "output_text": "hi",
+        "format": "markdown"
+      }
+    ],
+    "interruptions": [],
+    "state": {
+      "id": "state-basic-success",
+      "resumable": false
+    },
+    "activeAgentName": "reviewer",
+    "lastAgentName": "reviewer",
+    "warnings": [],
+    "context": {
+      "timestamp": "2026-06-05T00:00:00.000Z"
+    }
+  }
+}