codex-chatgpt-control 0.1.0-alpha.1

package/contracts/v1/fixtures/run-browser-bridge-blocker.json

@@ -0,0 +1,180 @@
+{
+  "result": {
+    "activeAgentName": "reviewer",
+    "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"
+    },
+    "data": {
+      "outputText": ""
+    },
+    "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
+    },
+    "interruptions": [
+      {
+        "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
+            }
+          ],
+          "resumable": false
+        },
+        "command": "session.bootstrap",
+        "fix": {
+          "steps": [
+            "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.",
+            "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 }).",
+            "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.",
+            "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."
+          ],
+          "summary": "Resolve the reported blocker before resuming."
+        },
+        "id": "interruption_fixed",
+        "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.",
+        "resume": {
+          "reason": "The underlying browser-control command did not mark this blocker as resumable.",
+          "supported": false
+        },
+        "status": "partial",
+        "type": "unsupported"
+      }
+    ],
+    "lastAgentName": "reviewer",
+    "newItems": [
+      {
+        "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
+            }
+          ],
+          "resumable": false
+        },
+        "type": "run.blocked"
+      }
+    ],
+    "ok": false,
+    "output": [
+      {
+        "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
+            }
+          ],
+          "resumable": false
+        },
+        "type": "run.blocked"
+      }
+    ],
+    "output_text": "",
+    "state": {
+      "id": "run_fixed",
+      "resumable": false
+    },
+    "status": "partial",
+    "steps": [
+      {
+        "command": "session.bootstrap",
+        "endedAt": "2026-06-06T00:00:00.000Z",
+        "id": "bootstrap",
+        "ok": false,
+        "startedAt": "2026-06-06T00:00:00.000Z",
+        "status": "blocked",
+        "warnings": []
+      }
+    ],
+    "warnings": []
+  },
+  "schemaVersion": "chatgpt.browser_control.run_result.v1"
+}

package/contracts/v1/fixtures/run-file-attach-success.json

@@ -0,0 +1,63 @@
+{
+  "schemaVersion": "chatgpt.browser_control.run_result.v1",
+  "result": {
+    "ok": true,
+    "status": "ok",
+    "output_text": "I reviewed brief.md.",
+    "finalOutput": "I reviewed brief.md.",
+    "output": [
+      {
+        "type": "thread.opened",
+        "thread": {
+          "url": "https://chatgpt.com/c/example-file",
+          "conversationId": "example-file"
+        }
+      },
+      {
+        "type": "file.attached",
+        "file": {
+          "path": "[redacted]/brief.md",
+          "name": "brief.md",
+          "bytes": 1842
+        }
+      },
+      {
+        "type": "message.completed",
+        "role": "assistant",
+        "output_text": "I reviewed brief.md.",
+        "format": "markdown"
+      }
+    ],
+    "newItems": [
+      {
+        "type": "file.attached",
+        "file": {
+          "path": "[redacted]/brief.md",
+          "name": "brief.md",
+          "bytes": 1842
+        }
+      },
+      {
+        "type": "message.completed",
+        "role": "assistant",
+        "output_text": "I reviewed brief.md.",
+        "format": "markdown"
+      }
+    ],
+    "interruptions": [],
+    "state": {
+      "id": "state-file-success",
+      "resumable": false,
+      "thread": {
+        "url": "https://chatgpt.com/c/example-file",
+        "conversationId": "example-file"
+      }
+    },
+    "activeAgentName": "reviewer",
+    "lastAgentName": "reviewer",
+    "warnings": [],
+    "context": {
+      "timestamp": "2026-06-05T00:00:00.000Z"
+    }
+  }
+}

package/contracts/v1/fixtures/run-report-redacted.json

@@ -0,0 +1,52 @@
+{
+  "schemaVersion": "chatgpt.browser_control.run_result.v1",
+  "result": {
+    "ok": true,
+    "status": "ok",
+    "output_text": "Report written.",
+    "finalOutput": "Report written.",
+    "output": [
+      {
+        "type": "message.submitted",
+        "role": "user",
+        "preview": "[redacted]",
+        "redacted": true
+      },
+      {
+        "type": "report.created",
+        "path": "reports/runs/redacted-run.json",
+        "contentPolicy": {
+          "includeContent": false,
+          "maxPreviewChars": 0,
+          "redacted": true
+        }
+      }
+    ],
+    "newItems": [
+      {
+        "type": "report.created",
+        "path": "reports/runs/redacted-run.json",
+        "contentPolicy": {
+          "includeContent": false,
+          "maxPreviewChars": 0,
+          "redacted": true
+        }
+      }
+    ],
+    "interruptions": [],
+    "state": {
+      "id": "state-report-redacted",
+      "resumable": false
+    },
+    "activeAgentName": "reporter",
+    "lastAgentName": "reporter",
+    "warnings": [],
+    "reportPath": "reports/runs/redacted-run.json",
+    "data": {
+      "reportPath": "reports/runs/redacted-run.json"
+    },
+    "context": {
+      "timestamp": "2026-06-05T00:00:00.000Z"
+    }
+  }
+}

package/contracts/v1/fixtures/run-selector-drift-blocker.json

@@ -0,0 +1,60 @@
+{
+  "schemaVersion": "chatgpt.browser_control.run_result.v1",
+  "result": {
+    "ok": false,
+    "status": "unsupported",
+    "output_text": "",
+    "output": [
+      {
+        "type": "run.blocked",
+        "blocker": {
+          "kind": "selector_drift",
+          "message": "No unique visible ChatGPT mode matched the requested label.",
+          "candidates": [
+            {
+              "label": "Auto"
+            },
+            {
+              "label": "Extended"
+            }
+          ]
+        }
+      }
+    ],
+    "newItems": [],
+    "interruptions": [
+      {
+        "id": "interrupt-selector-drift",
+        "type": "selector_drift",
+        "status": "unsupported",
+        "message": "No unique visible ChatGPT mode matched the requested label.",
+        "resume": {
+          "supported": false,
+          "reason": "Visible candidate selection must be resolved by the caller."
+        }
+      }
+    ],
+    "state": {
+      "id": "state-selector-drift",
+      "resumable": false
+    },
+    "activeAgentName": "reviewer",
+    "lastAgentName": "reviewer",
+    "warnings": [],
+    "blocker": {
+      "kind": "selector_drift",
+      "message": "No unique visible ChatGPT mode matched the requested label.",
+      "candidates": [
+        {
+          "label": "Auto"
+        },
+        {
+          "label": "Extended"
+        }
+      ]
+    },
+    "context": {
+      "timestamp": "2026-06-05T00:00:00.000Z"
+    }
+  }
+}

package/contracts/v1/fixtures/run-timeout-partial.json

@@ -0,0 +1,81 @@
+{
+  "schemaVersion": "chatgpt.browser_control.run_result.v1",
+  "result": {
+    "ok": false,
+    "status": "partial",
+    "output_text": "Partial assistant text captured before timeout.",
+    "finalOutput": "Partial assistant text captured before timeout.",
+    "output": [
+      {
+        "type": "thread.opened",
+        "thread": {
+          "url": "https://chatgpt.com/c/example-timeout",
+          "conversationId": "example-timeout"
+        }
+      },
+      {
+        "type": "message.submitted",
+        "role": "user",
+        "preview": "[redacted]",
+        "redacted": true
+      },
+      {
+        "type": "message.completed",
+        "role": "assistant",
+        "output_text": "Partial assistant text captured before timeout.",
+        "format": "markdown"
+      }
+    ],
+    "newItems": [
+      {
+        "type": "message.completed",
+        "role": "assistant",
+        "output_text": "Partial assistant text captured before timeout.",
+        "format": "markdown"
+      }
+    ],
+    "interruptions": [
+      {
+        "id": "interrupt-timeout",
+        "type": "timeout",
+        "status": "timeout",
+        "message": "The assistant response did not stabilize before the configured timeout.",
+        "resume": {
+          "supported": true,
+          "stateId": "state-timeout-partial"
+        }
+      }
+    ],
+    "state": {
+      "id": "state-timeout-partial",
+      "resumable": true,
+      "thread": {
+        "url": "https://chatgpt.com/c/example-timeout",
+        "conversationId": "example-timeout"
+      },
+      "nextStepId": "read-latest"
+    },
+    "activeAgentName": "reviewer",
+    "lastAgentName": "reviewer",
+    "warnings": [
+      "Response may still be generating in the visible ChatGPT thread."
+    ],
+    "steps": [
+      {
+        "id": "open",
+        "command": "threads.open",
+        "status": "ok",
+        "ok": true
+      },
+      {
+        "id": "ask",
+        "command": "messages.ask",
+        "status": "timeout",
+        "ok": false
+      }
+    ],
+    "context": {
+      "timestamp": "2026-06-05T00:00:00.000Z"
+    }
+  }
+}

package/contracts/v1/fixtures/run-two-turn-success.json

@@ -0,0 +1,83 @@
+{
+  "schemaVersion": "chatgpt.browser_control.run_result.v1",
+  "result": {
+    "ok": true,
+    "status": "ok",
+    "output_text": "second answer",
+    "finalOutput": "second answer",
+    "output": [
+      {
+        "type": "thread.opened",
+        "thread": {
+          "url": "https://chatgpt.com/c/example-two-turn",
+          "conversationId": "example-two-turn"
+        }
+      },
+      {
+        "type": "message.submitted",
+        "role": "user",
+        "preview": "first",
+        "redacted": false
+      },
+      {
+        "type": "message.completed",
+        "role": "assistant",
+        "output_text": "first answer",
+        "format": "markdown"
+      },
+      {
+        "type": "message.submitted",
+        "role": "user",
+        "preview": "second",
+        "redacted": false
+      },
+      {
+        "type": "message.completed",
+        "role": "assistant",
+        "output_text": "second answer",
+        "format": "markdown"
+      }
+    ],
+    "newItems": [
+      {
+        "type": "message.submitted",
+        "role": "user",
+        "preview": "first",
+        "redacted": false
+      },
+      {
+        "type": "message.completed",
+        "role": "assistant",
+        "output_text": "first answer",
+        "format": "markdown"
+      },
+      {
+        "type": "message.submitted",
+        "role": "user",
+        "preview": "second",
+        "redacted": false
+      },
+      {
+        "type": "message.completed",
+        "role": "assistant",
+        "output_text": "second answer",
+        "format": "markdown"
+      }
+    ],
+    "interruptions": [],
+    "state": {
+      "id": "state-two-turn-success",
+      "resumable": false,
+      "thread": {
+        "url": "https://chatgpt.com/c/example-two-turn",
+        "conversationId": "example-two-turn"
+      }
+    },
+    "activeAgentName": "reviewer",
+    "lastAgentName": "reviewer",
+    "warnings": [],
+    "context": {
+      "timestamp": "2026-06-05T00:00:00.000Z"
+    }
+  }
+}

package/contracts/v1/fixtures/run-upload-permission-blocker.json

@@ -0,0 +1,56 @@
+{
+  "schemaVersion": "chatgpt.browser_control.run_result.v1",
+  "result": {
+    "ok": false,
+    "status": "blocked",
+    "output_text": "",
+    "output": [
+      {
+        "type": "run.blocked",
+        "blocker": {
+          "kind": "permission",
+          "message": "A browser or ChatGPT permission is required before continuing."
+        }
+      }
+    ],
+    "newItems": [],
+    "interruptions": [
+      {
+        "id": "interrupt-upload-permission",
+        "type": "permission_required",
+        "status": "blocked",
+        "message": "A browser or ChatGPT permission is required before continuing.",
+        "resume": {
+          "supported": false,
+          "reason": "The user must update local browser or Codex permission settings."
+        }
+      }
+    ],
+    "state": {
+      "id": "state-upload-permission",
+      "resumable": false
+    },
+    "activeAgentName": "reviewer",
+    "lastAgentName": "reviewer",
+    "warnings": [],
+    "blocker": {
+      "kind": "permission",
+      "message": "A browser or ChatGPT permission is required before continuing.",
+      "remediation": [
+        {
+          "label": "Enable Codex upload permission",
+          "instruction": "Open Codex Settings > Computer Use > Chrome > Permissions and set Uploads to Always allow.",
+          "userActionRequired": true
+        },
+        {
+          "label": "Allow Chrome extension file URLs",
+          "instruction": "Open chrome://extensions, select the Codex extension, and enable Allow access to file URLs.",
+          "userActionRequired": true
+        }
+      ]
+    },
+    "context": {
+      "timestamp": "2026-06-05T00:00:00.000Z"
+    }
+  }
+}