openai-codex 0.1.0b1__py3-none-any.whl

openai_codex/__init__.py

@@ -0,0 +1,93 @@
+"""Python SDK for running Codex workflows.
+
+Start with :class:`Codex` for synchronous applications or
+:class:`AsyncCodex` for async applications. Most programs create a thread and
+run a turn::
+
+    from openai_codex import Codex, Sandbox
+
+    with Codex() as codex:
+        thread = codex.thread_start(sandbox=Sandbox.workspace_write)
+        result = thread.run("Describe this project.")
+        print(result.final_response)
+"""
+
+from ._version import __version__
+from .api import (
+    ApprovalMode,
+    AsyncChatgptLoginHandle,
+    AsyncCodex,
+    AsyncDeviceCodeLoginHandle,
+    AsyncThread,
+    AsyncTurnHandle,
+    ChatgptLoginHandle,
+    Codex,
+    DeviceCodeLoginHandle,
+    ImageInput,
+    Input,
+    InputItem,
+    LocalImageInput,
+    MentionInput,
+    RunInput,
+    Sandbox,
+    SkillInput,
+    TextInput,
+    Thread,
+    TurnHandle,
+    TurnResult,
+)
+from .client import CodexConfig
+from .errors import (
+    CodexError,
+    CodexRpcError,
+    InternalRpcError,
+    InvalidParamsError,
+    InvalidRequestError,
+    JsonRpcError,
+    MethodNotFoundError,
+    ParseError,
+    RetryLimitExceededError,
+    ServerBusyError,
+    TransportClosedError,
+    is_retryable_error,
+)
+from .retry import retry_on_overload
+
+__all__ = [
+    "__version__",
+    "CodexConfig",
+    "Codex",
+    "AsyncCodex",
+    "ApprovalMode",
+    "Sandbox",
+    "ChatgptLoginHandle",
+    "DeviceCodeLoginHandle",
+    "AsyncChatgptLoginHandle",
+    "AsyncDeviceCodeLoginHandle",
+    "Thread",
+    "AsyncThread",
+    "TurnHandle",
+    "AsyncTurnHandle",
+    "TurnResult",
+    "Input",
+    "InputItem",
+    "RunInput",
+    "TextInput",
+    "ImageInput",
+    "LocalImageInput",
+    "SkillInput",
+    "MentionInput",
+    "retry_on_overload",
+    "CodexError",
+    "TransportClosedError",
+    "JsonRpcError",
+    "CodexRpcError",
+    "ParseError",
+    "InvalidRequestError",
+    "MethodNotFoundError",
+    "InvalidParamsError",
+    "InternalRpcError",
+    "ServerBusyError",
+    "RetryLimitExceededError",
+    "is_retryable_error",
+]

openai_codex/_approval_mode.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import NoReturn
+
+from .generated.v2_all import (
+    ApprovalsReviewer,
+    AskForApproval,
+    AskForApprovalValue,
+)
+
+
+class ApprovalMode(str, Enum):
+    """High-level approval behavior for escalated permission requests."""
+
+    deny_all = "deny_all"
+    auto_review = "auto_review"
+
+
+def _approval_mode_settings(
+    approval_mode: ApprovalMode,
+) -> tuple[AskForApproval, ApprovalsReviewer | None]:
+    """Map the public approval mode to generated app-server start params."""
+    if not isinstance(approval_mode, ApprovalMode):
+        supported = ", ".join(mode.value for mode in ApprovalMode)
+        raise ValueError(f"approval_mode must be one of: {supported}")
+
+    match approval_mode:
+        case ApprovalMode.auto_review:
+            return (
+                AskForApproval(root=AskForApprovalValue.on_request),
+                ApprovalsReviewer.auto_review,
+            )
+        case ApprovalMode.deny_all:
+            return AskForApproval(root=AskForApprovalValue.never), None
+        case _:
+            return _assert_never_approval_mode(approval_mode)
+
+
+def _assert_never_approval_mode(approval_mode: NoReturn) -> NoReturn:
+    """Make approval mode mapping exhaustive for static type checkers."""
+    raise AssertionError(f"Unhandled approval mode: {approval_mode!r}")
+
+
+def _approval_mode_override_settings(
+    approval_mode: ApprovalMode | None,
+) -> tuple[AskForApproval | None, ApprovalsReviewer | None]:
+    """Map an optional public approval mode to app-server override params."""
+    if approval_mode is None:
+        return None, None
+    return _approval_mode_settings(approval_mode)

openai_codex/_initialize_metadata.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from .models import InitializeResponse, ServerInfo
+
+
+def _split_user_agent(user_agent: str) -> tuple[str | None, str | None]:
+    raw = user_agent.strip()
+    if not raw:
+        return None, None
+    if "/" in raw:
+        name, version = raw.split("/", 1)
+        return (name or None), (version or None)
+    parts = raw.split(maxsplit=1)
+    if len(parts) == 2:
+        return parts[0], parts[1]
+    return raw, None
+
+
+def validate_initialize_metadata(payload: InitializeResponse) -> InitializeResponse:
+    user_agent = (payload.userAgent or "").strip()
+    server = payload.serverInfo
+
+    server_name: str | None = None
+    server_version: str | None = None
+
+    if server is not None:
+        server_name = (server.name or "").strip() or None
+        server_version = (server.version or "").strip() or None
+
+    if (server_name is None or server_version is None) and user_agent:
+        parsed_name, parsed_version = _split_user_agent(user_agent)
+        if server_name is None:
+            server_name = parsed_name
+        if server_version is None:
+            server_version = parsed_version
+
+    normalized_server_name = (server_name or "").strip()
+    normalized_server_version = (server_version or "").strip()
+    if not user_agent or not normalized_server_name or not normalized_server_version:
+        raise RuntimeError(
+            "initialize response missing required metadata "
+            f"(user_agent={user_agent!r}, server_name={normalized_server_name!r}, server_version={normalized_server_version!r})"
+        )
+
+    if server is None:
+        payload.serverInfo = ServerInfo(
+            name=normalized_server_name,
+            version=normalized_server_version,
+        )
+    else:
+        server.name = normalized_server_name
+        server.version = normalized_server_version
+
+    return payload

openai_codex/_inputs.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .models import JsonObject
+
+
+@dataclass(slots=True)
+class TextInput:
+    """Text supplied to a turn or steering request."""
+
+    text: str
+
+
+@dataclass(slots=True)
+class ImageInput:
+    """Remote image URL supplied as turn input."""
+
+    url: str
+
+
+@dataclass(slots=True)
+class LocalImageInput:
+    """Local image path supplied as turn input."""
+
+    path: str
+
+
+@dataclass(slots=True)
+class SkillInput:
+    """Named skill reference supplied as turn input."""
+
+    name: str
+    path: str
+
+
+@dataclass(slots=True)
+class MentionInput:
+    """Named resource mention supplied as turn input."""
+
+    name: str
+    path: str
+
+
+InputItem = TextInput | ImageInput | LocalImageInput | SkillInput | MentionInput
+Input = list[InputItem] | InputItem
+RunInput = Input | str
+
+
+def _to_wire_item(item: InputItem) -> JsonObject:
+    if isinstance(item, TextInput):
+        return {"type": "text", "text": item.text}
+    if isinstance(item, ImageInput):
+        return {"type": "image", "url": item.url}
+    if isinstance(item, LocalImageInput):
+        return {"type": "localImage", "path": item.path}
+    if isinstance(item, SkillInput):
+        return {"type": "skill", "name": item.name, "path": item.path}
+    if isinstance(item, MentionInput):
+        return {"type": "mention", "name": item.name, "path": item.path}
+    raise TypeError(f"unsupported input item: {type(item)!r}")
+
+
+def _to_wire_input(input: Input) -> list[JsonObject]:
+    if isinstance(input, list):
+        return [_to_wire_item(i) for i in input]
+    return [_to_wire_item(input)]
+
+
+def _normalize_run_input(input: RunInput) -> Input:
+    if isinstance(input, str):
+        return TextInput(input)
+    return input

openai_codex/_login.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from .async_client import AsyncCodexClient
+from .client import CodexClient
+from .generated.v2_all import (
+    AccountLoginCompletedNotification,
+    CancelLoginAccountResponse,
+    ChatgptDeviceCodeLoginAccountParams,
+    ChatgptDeviceCodeLoginAccountResponse,
+    ChatgptLoginAccountParams,
+    ChatgptLoginAccountResponse,
+    LoginAccountParams,
+)
+
+
+class _AsyncLoginOwner(Protocol):
+    """Subset of AsyncCodex needed by async login handles."""
+
+    _client: AsyncCodexClient
+
+    async def _ensure_initialized(self) -> None:
+        """Ensure the owning SDK client has a live Codex connection."""
+        ...
+
+
+def start_chatgpt_login(client: CodexClient) -> ChatgptLoginHandle:
+    """Start browser ChatGPT login and return the handle for that attempt."""
+    response = client.account_login_start(
+        LoginAccountParams(
+            root=ChatgptLoginAccountParams(type="chatgpt"),
+        )
+    )
+    response_root = response.root
+    if not isinstance(response_root, ChatgptLoginAccountResponse):
+        raise RuntimeError(f"unexpected ChatGPT login response: {response_root!r}")
+    return ChatgptLoginHandle(
+        client,
+        response_root.login_id,
+        response_root.auth_url,
+    )
+
+
+async def async_start_chatgpt_login(owner: _AsyncLoginOwner) -> AsyncChatgptLoginHandle:
+    """Start async browser ChatGPT login and return that attempt's handle."""
+    response = await owner._client.account_login_start(
+        LoginAccountParams(
+            root=ChatgptLoginAccountParams(type="chatgpt"),
+        )
+    )
+    response_root = response.root
+    if not isinstance(response_root, ChatgptLoginAccountResponse):
+        raise RuntimeError(f"unexpected ChatGPT login response: {response_root!r}")
+    return AsyncChatgptLoginHandle(
+        owner,
+        response_root.login_id,
+        response_root.auth_url,
+    )
+
+
+def start_device_code_login(client: CodexClient) -> DeviceCodeLoginHandle:
+    """Start device-code ChatGPT login and return the handle for that attempt."""
+    response = client.account_login_start(
+        LoginAccountParams(
+            root=ChatgptDeviceCodeLoginAccountParams(type="chatgptDeviceCode"),
+        )
+    )
+    response_root = response.root
+    if not isinstance(response_root, ChatgptDeviceCodeLoginAccountResponse):
+        raise RuntimeError(f"unexpected device-code login response: {response_root!r}")
+    return DeviceCodeLoginHandle(
+        client,
+        response_root.login_id,
+        response_root.verification_url,
+        response_root.user_code,
+    )
+
+
+async def async_start_device_code_login(
+    owner: _AsyncLoginOwner,
+) -> AsyncDeviceCodeLoginHandle:
+    """Start async device-code ChatGPT login and return that attempt's handle."""
+    response = await owner._client.account_login_start(
+        LoginAccountParams(
+            root=ChatgptDeviceCodeLoginAccountParams(type="chatgptDeviceCode"),
+        )
+    )
+    response_root = response.root
+    if not isinstance(response_root, ChatgptDeviceCodeLoginAccountResponse):
+        raise RuntimeError(f"unexpected device-code login response: {response_root!r}")
+    return AsyncDeviceCodeLoginHandle(
+        owner,
+        response_root.login_id,
+        response_root.verification_url,
+        response_root.user_code,
+    )
+
+
+@dataclass(slots=True)
+class ChatgptLoginHandle:
+    """Live browser-login attempt returned by `Codex.login_chatgpt()`."""
+
+    _client: CodexClient
+    login_id: str
+    auth_url: str
+
+    def wait(self) -> AccountLoginCompletedNotification:
+        """Wait for this browser login attempt's completion notification."""
+        return self._client.wait_for_login_completed(self.login_id)
+
+    def cancel(self) -> CancelLoginAccountResponse:
+        """Cancel this browser login attempt."""
+        return self._client.account_login_cancel(self.login_id)
+
+
+@dataclass(slots=True)
+class DeviceCodeLoginHandle:
+    """Live device-code login attempt returned by `Codex.login_chatgpt_device_code()`."""
+
+    _client: CodexClient
+    login_id: str
+    verification_url: str
+    user_code: str
+
+    def wait(self) -> AccountLoginCompletedNotification:
+        """Wait for this device-code login attempt's completion notification."""
+        return self._client.wait_for_login_completed(self.login_id)
+
+    def cancel(self) -> CancelLoginAccountResponse:
+        """Cancel this device-code login attempt."""
+        return self._client.account_login_cancel(self.login_id)
+
+
+@dataclass(slots=True)
+class AsyncChatgptLoginHandle:
+    """Live browser-login attempt returned by `AsyncCodex.login_chatgpt()`."""
+
+    _codex: _AsyncLoginOwner
+    login_id: str
+    auth_url: str
+
+    async def wait(self) -> AccountLoginCompletedNotification:
+        """Wait for this browser login attempt's completion notification."""
+        await self._codex._ensure_initialized()
+        return await self._codex._client.wait_for_login_completed(self.login_id)
+
+    async def cancel(self) -> CancelLoginAccountResponse:
+        """Cancel this browser login attempt."""
+        await self._codex._ensure_initialized()
+        return await self._codex._client.account_login_cancel(self.login_id)
+
+
+@dataclass(slots=True)
+class AsyncDeviceCodeLoginHandle:
+    """Live device-code attempt returned by `AsyncCodex.login_chatgpt_device_code()`."""
+
+    _codex: _AsyncLoginOwner
+    login_id: str
+    verification_url: str
+    user_code: str
+
+    async def wait(self) -> AccountLoginCompletedNotification:
+        """Wait for this device-code login attempt's completion notification."""
+        await self._codex._ensure_initialized()
+        return await self._codex._client.wait_for_login_completed(self.login_id)
+
+    async def cancel(self) -> CancelLoginAccountResponse:
+        """Cancel this device-code login attempt."""
+        await self._codex._ensure_initialized()
+        return await self._codex._client.account_login_cancel(self.login_id)

openai_codex/_message_router.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+import queue
+import threading
+from collections import deque
+
+from .errors import CodexError, map_jsonrpc_error
+from .generated.notification_registry import notification_turn_id
+from .generated.v2_all import AccountLoginCompletedNotification
+from .models import JsonValue, Notification, UnknownNotification
+
+ResponseQueueItem = JsonValue | BaseException
+NotificationQueueItem = Notification | BaseException
+
+
+class MessageRouter:
+    """Route reader-thread messages to the SDK operation waiting for them.
+
+    The app-server stdio transport is a single ordered stream, so only the
+    reader thread should consume stdout. This router keeps the rest of the SDK
+    from competing for that stream by giving each in-flight JSON-RPC request
+    and active turn stream its own queue.
+    """
+
+    def __init__(self) -> None:
+        """Create empty response, turn, and global notification queues."""
+        self._lock = threading.Lock()
+        self._response_waiters: dict[str, queue.Queue[ResponseQueueItem]] = {}
+        self._login_notifications: dict[str, queue.Queue[NotificationQueueItem]] = {}
+        self._pending_login_notifications: dict[str, deque[Notification]] = {}
+        self._turn_notifications: dict[str, queue.Queue[NotificationQueueItem]] = {}
+        self._pending_turn_notifications: dict[str, deque[Notification]] = {}
+        self._global_notifications: queue.Queue[NotificationQueueItem] = queue.Queue()
+
+    def create_response_waiter(self, request_id: str) -> queue.Queue[ResponseQueueItem]:
+        """Register a one-shot queue for a JSON-RPC response id."""
+
+        waiter: queue.Queue[ResponseQueueItem] = queue.Queue(maxsize=1)
+        with self._lock:
+            self._response_waiters[request_id] = waiter
+        return waiter
+
+    def discard_response_waiter(self, request_id: str) -> None:
+        """Remove a response waiter when the request could not be written."""
+
+        with self._lock:
+            self._response_waiters.pop(request_id, None)
+
+    def next_global_notification(self) -> Notification:
+        """Block until the next notification that is not scoped to a turn."""
+
+        item = self._global_notifications.get()
+        if isinstance(item, BaseException):
+            raise item
+        return item
+
+    def register_login(self, login_id: str) -> None:
+        """Register a queue for one interactive login attempt."""
+
+        login_queue: queue.Queue[NotificationQueueItem] = queue.Queue()
+        with self._lock:
+            if login_id in self._login_notifications:
+                return
+            pending = self._pending_login_notifications.pop(login_id, deque())
+            self._login_notifications[login_id] = login_queue
+        for notification in pending:
+            login_queue.put(notification)
+
+    def unregister_login(self, login_id: str) -> None:
+        """Stop routing future notifications for one login attempt."""
+
+        with self._lock:
+            self._login_notifications.pop(login_id, None)
+
+    def next_login_notification(self, login_id: str) -> Notification:
+        """Block until the next notification for a registered login attempt."""
+
+        with self._lock:
+            login_queue = self._login_notifications.get(login_id)
+        if login_queue is None:
+            raise RuntimeError(f"login {login_id!r} is not registered for waiting")
+        item = login_queue.get()
+        if isinstance(item, BaseException):
+            raise item
+        return item
+
+    def register_turn(self, turn_id: str) -> None:
+        """Register a queue for a turn stream and replay early events."""
+
+        turn_queue: queue.Queue[NotificationQueueItem] = queue.Queue()
+        with self._lock:
+            if turn_id in self._turn_notifications:
+                return
+            # A turn can emit events immediately after turn/start, before the
+            # caller receives the TurnHandle and starts streaming.
+            pending = self._pending_turn_notifications.pop(turn_id, deque())
+            self._turn_notifications[turn_id] = turn_queue
+        for notification in pending:
+            turn_queue.put(notification)
+
+    def unregister_turn(self, turn_id: str) -> None:
+        """Stop routing future turn events to the stream queue."""
+
+        with self._lock:
+            self._turn_notifications.pop(turn_id, None)
+
+    def next_turn_notification(self, turn_id: str) -> Notification:
+        """Block until the next notification for a registered turn."""
+
+        with self._lock:
+            turn_queue = self._turn_notifications.get(turn_id)
+        if turn_queue is None:
+            raise RuntimeError(f"turn {turn_id!r} is not registered for streaming")
+        item = turn_queue.get()
+        if isinstance(item, BaseException):
+            raise item
+        return item
+
+    def route_response(self, msg: dict[str, JsonValue]) -> None:
+        """Deliver a JSON-RPC response or error to its request waiter."""
+
+        request_id = msg.get("id")
+        with self._lock:
+            waiter = self._response_waiters.pop(str(request_id), None)
+        if waiter is None:
+            return
+
+        if "error" in msg:
+            err = msg["error"]
+            if isinstance(err, dict):
+                waiter.put(
+                    map_jsonrpc_error(
+                        int(err.get("code", -32000)),
+                        str(err.get("message", "unknown")),
+                        err.get("data"),
+                    )
+                )
+            else:
+                waiter.put(CodexError("Malformed JSON-RPC error response"))
+            return
+
+        waiter.put(msg.get("result"))
+
+    def route_notification(self, notification: Notification) -> None:
+        """Deliver a notification to a turn queue or the global queue."""
+
+        login_id = self._notification_login_id(notification)
+        if login_id is not None:
+            with self._lock:
+                login_queue = self._login_notifications.get(login_id)
+                if login_queue is None:
+                    self._pending_login_notifications.setdefault(login_id, deque()).append(
+                        notification
+                    )
+                    return
+            login_queue.put(notification)
+            return
+
+        turn_id = self._notification_turn_id(notification)
+        if turn_id is None:
+            self._global_notifications.put(notification)
+            return
+
+        with self._lock:
+            turn_queue = self._turn_notifications.get(turn_id)
+            if turn_queue is None:
+                if notification.method == "turn/completed":
+                    self._pending_turn_notifications.pop(turn_id, None)
+                    return
+                self._pending_turn_notifications.setdefault(turn_id, deque()).append(notification)
+                return
+        turn_queue.put(notification)
+
+    def fail_all(self, exc: BaseException) -> None:
+        """Wake every blocked waiter when the reader thread exits."""
+
+        with self._lock:
+            response_waiters = list(self._response_waiters.values())
+            self._response_waiters.clear()
+            login_queues = list(self._login_notifications.values())
+            self._login_notifications.clear()
+            self._pending_login_notifications.clear()
+            turn_queues = list(self._turn_notifications.values())
+            self._pending_turn_notifications.clear()
+        # Put the same transport failure into every queue so no SDK call blocks
+        # forever waiting for a response that cannot arrive.
+        for waiter in response_waiters:
+            waiter.put(exc)
+        for login_queue in login_queues:
+            login_queue.put(exc)
+        for turn_queue in turn_queues:
+            turn_queue.put(exc)
+        self._global_notifications.put(exc)
+
+    def _notification_login_id(self, notification: Notification) -> str | None:
+        """Extract the login attempt id from completion notifications."""
+        if notification.method != "account/login/completed":
+            return None
+
+        payload = notification.payload
+        if isinstance(payload, AccountLoginCompletedNotification):
+            return payload.login_id
+        if isinstance(payload, UnknownNotification):
+            raw_login_id = payload.params.get("loginId")
+            if isinstance(raw_login_id, str):
+                return raw_login_id
+        return None
+
+    def _notification_turn_id(self, notification: Notification) -> str | None:
+        """Extract routing ids from known generated payloads or raw unknown payloads."""
+        payload = notification.payload
+        if isinstance(payload, UnknownNotification):
+            raw_turn_id = payload.params.get("turnId")
+            if isinstance(raw_turn_id, str):
+                return raw_turn_id
+            raw_turn = payload.params.get("turn")
+            if isinstance(raw_turn, dict):
+                raw_nested_turn_id = raw_turn.get("id")
+                if isinstance(raw_nested_turn_id, str):
+                    return raw_nested_turn_id
+            return None
+        return notification_turn_id(payload)