codex-chatgpt-control 0.1.0a1__tar.gz

codex_chatgpt_control-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Allcock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codex_chatgpt_control-0.1.0a1/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: codex-chatgpt-control
+Version: 0.1.0a1
+Summary: Python SDK for Codex agents controlling visible ChatGPT web sessions through a local backend.
+Author: Adam Allcock
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/adamallcock/codex-chatgpt-control
+Project-URL: Issues, https://github.com/adamallcock/codex-chatgpt-control/issues
+Project-URL: Source, https://github.com/adamallcock/codex-chatgpt-control
+Keywords: codex,chatgpt,browser-automation,visible-ui,agents,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3,>=2
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1.390; extra == "dev"
+Dynamic: license-file
+
+# codex-chatgpt-control Python SDK
+
+Python parity client for Codex agents controlling visible ChatGPT web sessions through the shared Node backend protocol.
+
+Unofficial project: not affiliated with, endorsed by, or sponsored by OpenAI. This is not an OpenAI API wrapper and does not call hidden or private ChatGPT endpoints.
+
+```text
+Python SDK -> backend protocol -> Node runtime -> browser bridge -> visible chatgpt.com session
+```
+
+The current browser-control runtime is Node/TypeScript. Python talks to it through a long-lived local stdio backend service. This is intentionally not a pure-Python browser-control runtime yet.
+
+## Install
+
+```bash
+python -m pip install codex-chatgpt-control
+```
+
+The Python package needs a Node backend command for browser-control workflows. Install or build the Node package too:
+
+```bash
+npm install codex-chatgpt-control
+```
+
+## Development Install
+
+Build the backend bundle first:
+
+```bash
+cd ../node
+npm ci
+npm run bundle:backend
+```
+
+Install the Python package:
+
+```bash
+cd ../python
+python -m pip install -e .[dev]
+```
+
+## Sync Usage
+
+```python
+from codex_chatgpt_control import Agent, BackendClient, Runner, StdioBackendTransport
+
+backend = BackendClient(StdioBackendTransport(
+    command=["node", "../node/dist/codex-chatgpt-control-backend.mjs"]
+))
+runner = Runner(backend)
+agent = Agent(name="reviewer", instructions="Review carefully.")
+
+try:
+    result = runner.run_sync(agent, {
+        "input": "Reply with hi.",
+        "thread": {"type": "new"},
+        "response": {"format": "markdown"},
+    })
+finally:
+    backend.close()
+
+print(result.status)
+print(result.output_text)
+```
+
+## Agents-Style API
+
+The Python SDK exposes OpenAI Agents SDK-inspired names where they fit the visible-session product:
+
+- `Agent`
+- `Runner.run`
+- `Runner.run_sync`
+- `Runner.run_streamed`
+- `RunResult`
+- `RunResultStreaming`
+
+The semantics are browser-control semantics, not OpenAI API semantics. Instructions are visible by default and are submitted to ChatGPT web as prompt text unless `instructions_mode="metadata_only"` is used.
+
+## Product-Specific API
+
+The `ChatGPT` facade exposes workflows and primitive command groups:
+
+- `chatgpt.responses.create(...)`
+- `chatgpt.ask(...)`, `ask_in_thread(...)`, `ask_with_files(...)`
+- `chatgpt.run_plan({"name": "new-ask-read", ...})`
+- `chatgpt.doctor(...)`
+- `chatgpt.reports.create(...)`
+- `chatgpt.session`, `threads`, `messages`, `files`, `modes`, `tools`, `response`
+- `chatgpt.commands()`, `describe(...)`, `help(...)`
+
+Unsupported OpenAI API-only Responses fields, such as `model`, `temperature`, and `previous_response_id`, return explicit unsupported responses instead of silently submitting misleading prompts.
+
+## Backend And Browser Bridge
+
+Ordinary shells can launch the backend and validate the protocol. Browser-required calls need a compatible browser bridge.
+
+Without a bridge, live browser operations should return:
+
+```json
+{
+  "kind": "browser_bridge_unavailable"
+}
+```
+
+That blocker is expected in ordinary shells. A real live browser pass requires a backend command with bridge access. A plain Python-spawned Node subprocess does not automatically inherit a Codex browser bridge.
+
+Override the backend command when needed:
+
+```bash
+CHATGPT_BROWSER_BACKEND_COMMAND="node /absolute/path/to/bridge-enabled-backend.mjs" \
+python scripts/live_smoke.py --mode browser-bridge
+```
+
+## Validation
+
+Run from `packages/python`:
+
+```bash
+python -m unittest discover -s tests
+python -m compileall -q src examples
+python -m pyright --pythonpath "$(which python)" src tests
+python scripts/live_smoke.py --mode ordinary-shell
+```
+
+The ordinary-shell smoke succeeds when the backend stays alive, `backend.health` succeeds, command descriptors load, and browser-required calls return `browser_bridge_unavailable`.

codex_chatgpt_control-0.1.0a1/README.md

@@ -0,0 +1,125 @@
+# codex-chatgpt-control Python SDK
+
+Python parity client for Codex agents controlling visible ChatGPT web sessions through the shared Node backend protocol.
+
+Unofficial project: not affiliated with, endorsed by, or sponsored by OpenAI. This is not an OpenAI API wrapper and does not call hidden or private ChatGPT endpoints.
+
+```text
+Python SDK -> backend protocol -> Node runtime -> browser bridge -> visible chatgpt.com session
+```
+
+The current browser-control runtime is Node/TypeScript. Python talks to it through a long-lived local stdio backend service. This is intentionally not a pure-Python browser-control runtime yet.
+
+## Install
+
+```bash
+python -m pip install codex-chatgpt-control
+```
+
+The Python package needs a Node backend command for browser-control workflows. Install or build the Node package too:
+
+```bash
+npm install codex-chatgpt-control
+```
+
+## Development Install
+
+Build the backend bundle first:
+
+```bash
+cd ../node
+npm ci
+npm run bundle:backend
+```
+
+Install the Python package:
+
+```bash
+cd ../python
+python -m pip install -e .[dev]
+```
+
+## Sync Usage
+
+```python
+from codex_chatgpt_control import Agent, BackendClient, Runner, StdioBackendTransport
+
+backend = BackendClient(StdioBackendTransport(
+    command=["node", "../node/dist/codex-chatgpt-control-backend.mjs"]
+))
+runner = Runner(backend)
+agent = Agent(name="reviewer", instructions="Review carefully.")
+
+try:
+    result = runner.run_sync(agent, {
+        "input": "Reply with hi.",
+        "thread": {"type": "new"},
+        "response": {"format": "markdown"},
+    })
+finally:
+    backend.close()
+
+print(result.status)
+print(result.output_text)
+```
+
+## Agents-Style API
+
+The Python SDK exposes OpenAI Agents SDK-inspired names where they fit the visible-session product:
+
+- `Agent`
+- `Runner.run`
+- `Runner.run_sync`
+- `Runner.run_streamed`
+- `RunResult`
+- `RunResultStreaming`
+
+The semantics are browser-control semantics, not OpenAI API semantics. Instructions are visible by default and are submitted to ChatGPT web as prompt text unless `instructions_mode="metadata_only"` is used.
+
+## Product-Specific API
+
+The `ChatGPT` facade exposes workflows and primitive command groups:
+
+- `chatgpt.responses.create(...)`
+- `chatgpt.ask(...)`, `ask_in_thread(...)`, `ask_with_files(...)`
+- `chatgpt.run_plan({"name": "new-ask-read", ...})`
+- `chatgpt.doctor(...)`
+- `chatgpt.reports.create(...)`
+- `chatgpt.session`, `threads`, `messages`, `files`, `modes`, `tools`, `response`
+- `chatgpt.commands()`, `describe(...)`, `help(...)`
+
+Unsupported OpenAI API-only Responses fields, such as `model`, `temperature`, and `previous_response_id`, return explicit unsupported responses instead of silently submitting misleading prompts.
+
+## Backend And Browser Bridge
+
+Ordinary shells can launch the backend and validate the protocol. Browser-required calls need a compatible browser bridge.
+
+Without a bridge, live browser operations should return:
+
+```json
+{
+  "kind": "browser_bridge_unavailable"
+}
+```
+
+That blocker is expected in ordinary shells. A real live browser pass requires a backend command with bridge access. A plain Python-spawned Node subprocess does not automatically inherit a Codex browser bridge.
+
+Override the backend command when needed:
+
+```bash
+CHATGPT_BROWSER_BACKEND_COMMAND="node /absolute/path/to/bridge-enabled-backend.mjs" \
+python scripts/live_smoke.py --mode browser-bridge
+```
+
+## Validation
+
+Run from `packages/python`:
+
+```bash
+python -m unittest discover -s tests
+python -m compileall -q src examples
+python -m pyright --pythonpath "$(which python)" src tests
+python scripts/live_smoke.py --mode ordinary-shell
+```
+
+The ordinary-shell smoke succeeds when the backend stays alive, `backend.health` succeeds, command descriptors load, and browser-required calls return `browser_bridge_unavailable`.

codex_chatgpt_control-0.1.0a1/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "codex-chatgpt-control"
+version = "0.1.0a1"
+description = "Python SDK for Codex agents controlling visible ChatGPT web sessions through a local backend."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "Adam Allcock" }
+]
+keywords = ["codex", "chatgpt", "browser-automation", "visible-ui", "agents", "sdk"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed"
+]
+dependencies = [
+  "pydantic>=2,<3"
+]
+
+[project.scripts]
+chatgpt-thread = "codex_chatgpt_control.thread_entrypoint:main"
+
+[project.urls]
+Homepage = "https://github.com/adamallcock/codex-chatgpt-control"
+Issues = "https://github.com/adamallcock/codex-chatgpt-control/issues"
+Source = "https://github.com/adamallcock/codex-chatgpt-control"
+
+[project.optional-dependencies]
+dev = [
+  "pyright>=1.1.390"
+]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+codex_chatgpt_control = ["py.typed"]

codex_chatgpt_control-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

codex_chatgpt_control-0.1.0a1/src/codex_chatgpt_control/__init__.py

@@ -0,0 +1,101 @@
+from .async_client import (
+    AsyncChatGPT,
+    AsyncChatGPTRunner,
+    AsyncCommandClient,
+    AsyncPrimitiveGroup,
+    AsyncReportsClient,
+    AsyncResponsesClient,
+    AsyncRunResultStreaming,
+    AsyncWorkflowClient,
+)
+from .agent import Agent, AgentConfig
+from .backend import (
+    BACKEND_EVENT_SCHEMA_VERSION,
+    BACKEND_REQUEST_SCHEMA_VERSION,
+    BACKEND_RESPONSE_SCHEMA_VERSION,
+    BackendClient,
+    BackendProtocolError,
+    BackendRequest,
+    BackendTransportError,
+    StdioBackendTransport,
+)
+from .client import ChatGPT, ChatGPTAgent, ChatGPTRunner
+from .commands import CommandClient
+from .models import (
+    BackendCapabilities,
+    BackendEvent,
+    BackendResponse,
+    ChatGPTAgentModel,
+    ChatGPTResponse,
+    ChatGPTRunInput,
+    ChatGPTRunResult,
+    ChatGPTRunState,
+    ChatGPTStreamEvent,
+    CommandDescriptor,
+    CommandResult,
+    DoctorReport,
+    RunReportData,
+    SequencePlan,
+)
+from .transport import NodeSidecarError, NodeSidecarTransport
+from .runner import RunResult, RunResultStreaming, RunState, Runner
+from .responses import ResponsesClient, ResponsesValidationResult
+from .primitives import FilesClient, MessagesClient, ModesClient, ResponseClient, SessionClient, ThreadsClient, ToolsClient
+from .reports import ReportsClient
+from .workflows import WorkflowClient
+
+__all__ = [
+    "Agent",
+    "AgentConfig",
+    "AsyncChatGPT",
+    "AsyncChatGPTRunner",
+    "AsyncCommandClient",
+    "AsyncPrimitiveGroup",
+    "AsyncReportsClient",
+    "AsyncResponsesClient",
+    "AsyncRunResultStreaming",
+    "AsyncWorkflowClient",
+    "BACKEND_EVENT_SCHEMA_VERSION",
+    "BACKEND_REQUEST_SCHEMA_VERSION",
+    "BACKEND_RESPONSE_SCHEMA_VERSION",
+    "BackendClient",
+    "BackendProtocolError",
+    "BackendRequest",
+    "BackendTransportError",
+    "BackendCapabilities",
+    "BackendEvent",
+    "BackendResponse",
+    "ChatGPT",
+    "ChatGPTAgentModel",
+    "ChatGPTAgent",
+    "ChatGPTRunner",
+    "ChatGPTRunInput",
+    "ChatGPTResponse",
+    "ChatGPTRunResult",
+    "ChatGPTRunState",
+    "ChatGPTStreamEvent",
+    "CommandClient",
+    "CommandDescriptor",
+    "CommandResult",
+    "DoctorReport",
+    "FilesClient",
+    "MessagesClient",
+    "ModesClient",
+    "NodeSidecarError",
+    "NodeSidecarTransport",
+    "ReportsClient",
+    "ResponseClient",
+    "RunReportData",
+    "RunResult",
+    "RunResultStreaming",
+    "RunState",
+    "Runner",
+    "ResponsesClient",
+    "ResponsesValidationResult",
+    "SessionClient",
+    "SequencePlan",
+    "StdioBackendTransport",
+    "ThreadsClient",
+    "ToolsClient",
+    "WorkflowClient",
+]

codex_chatgpt_control-0.1.0a1/src/codex_chatgpt_control/agent.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+
+InstructionsMode = Literal["visible_prefix", "visible_setup_message", "metadata_only"]
+
+
+@dataclass(frozen=True)
+class Agent:
+    name: str
+    instructions: str | None = None
+    instructions_mode: InstructionsMode = "visible_prefix"
+    defaults: dict[str, Any] = field(default_factory=dict)
+    tools: list[dict[str, Any]] = field(default_factory=list)
+    guardrails: list[dict[str, Any]] = field(default_factory=list)
+    output: dict[str, Any] | None = None
+    metadata: dict[str, Any] | None = None
+
+    def __post_init__(self) -> None:
+        normalized = self.name.strip()
+        if not normalized:
+            raise ValueError("Agent name must not be empty.")
+        object.__setattr__(self, "name", normalized)
+
+    def to_wire(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "kind": "chatgpt_browser_agent",
+            "name": self.name,
+            "instructionsMode": self.instructions_mode,
+            "defaults": self.defaults,
+            "tools": self.tools,
+            "guardrails": self.guardrails,
+        }
+        if self.instructions is not None:
+            payload["instructions"] = self.instructions
+        if self.output is not None:
+            payload["output"] = self.output
+        if self.metadata is not None:
+            payload["metadata"] = self.metadata
+        return payload
+
+
+AgentConfig = Agent