codex-backend-sdk 0.5.7__tar.gz → 0.5.9__tar.gz

{codex_backend_sdk-0.5.7 → codex_backend_sdk-0.5.9}/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.9] - 2026-10-24
+
+### Added
+- OAuth transcription-only primary Realtime WebSocket with JSON events,
+  context-managed cleanup, bounded socket timeout, and no automatic audio replay.
+  Verified with synthetic PCM16LE mono 24 kHz speech, no developer API key.
+
+### Documentation
+- Distinguish verified Realtime transcription from the legacy batch route's
+  current HTTP 403 responses; OAuth success does not establish quota coverage.
+
+## [0.5.8] - 2026-10-22
+
+### Added
+- Responses WebSocket `interrupt()` with active-response tracking,
+  acknowledgement validation, and draining before socket reuse.
+- Source compatibility audit against Codex `0eb98b4617`, with native cloud
+  gRPC Resume/Attach explicitly inventoried as unsupported.
+
+### Fixed
+- Preserve message IDs, status, phase, encrypted content, and backend metadata
+  when replaying Responses history; retire abandoned WebSocket streams.
+- Serialize numeric custom reasoning effort strings as unsigned 64-bit JSON
+  integers and preserve reasoning context on attribute-based controls.
+- Send and validate installed-plugin pagination limits with scoped requests.
+
 ## [0.5.7] - 2026-10-22
 
 ### Fixed

{codex_backend_sdk-0.5.7 → codex_backend_sdk-0.5.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codex-backend-sdk
-Version: 0.5.7
+Version: 0.5.9
 Summary: Unofficial Python SDK for the ChatGPT Codex backend API
 License: MIT
 License-File: LICENSE
@@ -55,6 +55,12 @@ The package intentionally separates three kinds of API:
 pip install --upgrade codex-backend-sdk
 ```
 
+Version **0.5.8** aligns the SDK with Codex source commit `0eb98b4617`:
+WebSocket interruption, message replay fields, numeric reasoning efforts, and
+scoped installed-plugin pagination. See the [source audit](docs/codex-source-audit.md)
+for verified contracts and the separately inventoried, unsupported cloud gRPC
+transport.
+
 For an editable checkout:
 
 ```bash
@@ -185,6 +191,18 @@ with client.responses.websocket.connect() as ws:
             print(event.get("delta", ""), end="")
 ```
 
+To stop an active WebSocket response, call `ws.interrupt()` after receiving
+`response.created`, including from another thread. Keep consuming events until
+both `response.interrupt.accepted` and the terminal response event have arrived
+before reusing the connection. Closing an unfinished event iterator closes the
+connection. Replayed messages retain their IDs, phase, status, encrypted content,
+and backend metadata.
+
+Custom numeric reasoning budgets are also supported:
+`reasoning={"effort": 4096, "context": "all_turns"}`. Numeric strings such as
+`"4096"` are encoded as JSON integers, matching Codex; model support is determined
+by the backend.
+
 ### Maintain a multi-turn conversation
 
 The Codex backend does not expose `previous_response_id`; preserve prior items

{codex_backend_sdk-0.5.7 → codex_backend_sdk-0.5.9}/README.md

@@ -26,6 +26,12 @@ The package intentionally separates three kinds of API:
 pip install --upgrade codex-backend-sdk
 ```
 
+Version **0.5.8** aligns the SDK with Codex source commit `0eb98b4617`:
+WebSocket interruption, message replay fields, numeric reasoning efforts, and
+scoped installed-plugin pagination. See the [source audit](docs/codex-source-audit.md)
+for verified contracts and the separately inventoried, unsupported cloud gRPC
+transport.
+
 For an editable checkout:
 
 ```bash
@@ -156,6 +162,18 @@ with client.responses.websocket.connect() as ws:
             print(event.get("delta", ""), end="")
 ```
 
+To stop an active WebSocket response, call `ws.interrupt()` after receiving
+`response.created`, including from another thread. Keep consuming events until
+both `response.interrupt.accepted` and the terminal response event have arrived
+before reusing the connection. Closing an unfinished event iterator closes the
+connection. Replayed messages retain their IDs, phase, status, encrypted content,
+and backend metadata.
+
+Custom numeric reasoning budgets are also supported:
+`reasoning={"effort": 4096, "context": "all_turns"}`. Numeric strings such as
+`"4096"` are encoded as JSON integers, matching Codex; model support is determined
+by the backend.
+
 ### Maintain a multi-turn conversation
 
 The Codex backend does not expose `previous_response_id`; preserve prior items

{codex_backend_sdk-0.5.7 → codex_backend_sdk-0.5.9}/codex_backend_sdk/__init__.py

@@ -17,7 +17,7 @@ Quickstart:
     print(response.output_text)
 """
 
-__version__ = "0.5.7"
+__version__ = "0.5.9"
 
 from .oauth import (
     DeviceCode,

{codex_backend_sdk-0.5.7 → codex_backend_sdk-0.5.9}/codex_backend_sdk/_models.py

@@ -7,12 +7,12 @@ import time
 from collections.abc import Iterator
 from io import BytesIO
 from pathlib import Path
-from typing import Any, Generic, Literal, Optional, TypeVar
+from typing import Any, Generic, Literal, Optional, TypeVar, Union
 
 import requests
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
-ReasoningEffort = Literal["minimal", "low", "medium", "high", "xhigh"]
+ReasoningEffort = Union[Literal["none", "minimal", "low", "medium", "high", "xhigh"], str, int]
 ReasoningSummary = Literal["concise", "detailed", "auto"]
 Verbosity = Literal["low", "medium", "high"]
 ServiceTier = Literal["flex", "priority"]

{codex_backend_sdk-0.5.7 → codex_backend_sdk-0.5.9}/codex_backend_sdk/resources/_responses_payloads.py

@@ -16,7 +16,7 @@ from .._models import (
     ResponseUsage,
     TokenDetails,
 )
-from .._utils import _UNSET, _default, _is_given, _jsonable
+from .._utils import _default, _is_given, _jsonable
 
 
 class ResponsesCreateRequest(CodexBaseModel):
@@ -169,7 +169,15 @@ def normalize_input_item(item: Any) -> dict[str, Any]:
             {"type": "input_text", "text": part} if isinstance(part, str) else part
             for part in content
         ]
-    return _message(role, content)
+    message = _message(role, content)
+    # Preserve backend replay fields while still excluding local harness-only keys.
+    for key in (
+        "id", "status", "phase", "encrypted_content",
+        "internal_chat_message_metadata_passthrough",
+    ):
+        if key in raw:
+            message[key] = raw[key]
+    return message
 
 
 def normalize_tools(tools: Any) -> list[dict[str, Any]]:
@@ -181,12 +189,22 @@ def normalize_tools(tools: Any) -> list[dict[str, Any]]:
 def normalize_reasoning(reasoning: Any) -> dict[str, Any]:
     reasoning = _jsonable(reasoning)
     if isinstance(reasoning, dict):
-        return {key: value for key, value in reasoning.items() if value is not None}
-    return {
-        key: value
-        for key in ("effort", "summary")
-        if (value := getattr(reasoning, key, None)) is not None
-    }
+        normalized = {key: value for key, value in reasoning.items() if value is not None}
+    else:
+        normalized = {
+            key: value
+            for key in ("effort", "summary", "context")
+            if (value := getattr(reasoning, key, None)) is not None
+        }
+    effort = normalized.get("effort")
+    # Codex serializes numeric custom efforts as unsigned 64-bit JSON numbers.
+    if isinstance(effort, str) and effort.isascii():
+        digits = effort.removeprefix("+")
+        if digits.isdecimal() and len(digits.lstrip("0")) <= 20:
+            numeric = int(digits.lstrip("0") or "0")
+            if numeric <= 2**64 - 1:
+                normalized["effort"] = numeric
+    return normalized
 
 
 def normalize_text(text: Any) -> dict[str, Any]:

{codex_backend_sdk-0.5.7 → codex_backend_sdk-0.5.9}/codex_backend_sdk/resources/chatgpt_plugins.py

@@ -106,10 +106,8 @@ class ChatGPTPlugins:
         page_token: str | None = None,
         include_download_urls: bool = False,
     ) -> dict[str, Any]:
-        params: dict[str, Any] = {}
-        if scope is None:
-            params["limit"] = _positive(limit, "limit")
-        else:
+        params: dict[str, Any] = {"limit": _positive(limit, "limit")}
+        if scope is not None:
             params["scope"] = _scope(scope)
         if page_token is not None:
             params["pageToken"] = _required(page_token, "page_token")

{codex_backend_sdk-0.5.7 → codex_backend_sdk-0.5.9}/codex_backend_sdk/resources/realtime.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+from contextlib import contextmanager
 import threading
 import urllib.parse
 import uuid
@@ -33,6 +34,38 @@ class Realtime:
         self.sideband = RealtimeSideband(client)
 
 
+    @contextmanager
+    def connect(self, *, intent: str, timeout: Optional[float] = None):
+        """Open a transcription-only primary WebSocket with ChatGPT OAuth.
+
+        Events are JSON dictionaries sent/received with ``send``/``recv``.
+        There is no automatic retry or audio replay. Availability and usage
+        attribution depend on the backend; subscription coverage is not implied.
+        """
+        if intent != "transcription":
+            raise CodexBackendUnsupportedParameterError(
+                "Only intent='transcription' is supported by the OAuth primary socket."
+            )
+        store = self._client._store
+        if store is None or not store.access_token:
+            raise RuntimeError("Realtime transcription requires ChatGPT OAuth authentication.")
+        headers = {
+            "Authorization": f"Bearer {store.access_token}",
+            "originator": "codex_cli_rs",
+            "x-session-id": str(uuid.uuid4()),
+        }
+        if store.account_id:
+            headers["ChatGPT-Account-ID"] = store.account_id
+        socket = websocket.create_connection(
+            "wss://api.openai.com/v1/realtime?intent=transcription",
+            header=headers,
+            timeout=self._client._timeout if timeout is None else timeout,
+            redirect_limit=0,
+        )
+        with RealtimeConnection(socket) as connection:
+            yield connection
+
+
 class Live:
     """OpenAI-compatible Live resource backed by ChatGPT OAuth.
 
@@ -114,8 +147,8 @@ class Live:
         )
 
 
-class RealtimeSidebandConnection:
-    """JSON transport joined to an existing Realtime v3 WebRTC call."""
+class RealtimeConnection:
+    """Synchronous JSON event transport with deterministic socket cleanup."""
 
     def __init__(self, socket: Any, *, graceful_close: bool = False) -> None:
         self._socket = socket
@@ -125,20 +158,20 @@ class RealtimeSidebandConnection:
 
     def send(self, event: Any) -> None:
         if self.closed:
-            raise RuntimeError("Realtime sideband connection is closed.")
+            raise RuntimeError("Realtime connection is closed.")
         payload = json.dumps(_jsonable(event), ensure_ascii=False)
         with self._send_lock:
             self._socket.send(payload)
 
     def recv(self) -> dict[str, Any]:
         if self.closed:
-            raise RuntimeError("Realtime sideband connection is closed.")
+            raise RuntimeError("Realtime connection is closed.")
         payload = self._socket.recv()
         if isinstance(payload, bytes):
             payload = payload.decode("utf-8")
         event = json.loads(payload)
         if not isinstance(event, dict):
-            raise TypeError("Expected a Realtime sideband event to be a JSON object.")
+            raise TypeError("Expected a Realtime event to be a JSON object.")
         return event
 
     def close(self) -> None:
@@ -159,13 +192,17 @@ class RealtimeSidebandConnection:
             except (IndexError, StopIteration):
                 return
 
-    def __enter__(self) -> "RealtimeSidebandConnection":
+    def __enter__(self) -> "RealtimeConnection":
         return self
 
     def __exit__(self, *_: Any) -> None:
         self.close()
 
 
+class RealtimeSidebandConnection(RealtimeConnection):
+    """JSON transport joined to an existing Realtime v3 WebRTC call."""
+
+
 class LiveSidebandConnection(RealtimeSidebandConnection):
     """Live-shaped event stream over the Codex OAuth sideband dialect."""
 

{codex_backend_sdk-0.5.7 → codex_backend_sdk-0.5.9}/codex_backend_sdk/resources/responses_websocket.py

@@ -38,6 +38,10 @@ class ResponsesWebSocketConnection:
         self._socket = socket
         self.url = url
         self._request_lock = threading.Lock()
+        self._state_lock = threading.RLock()
+        self._response_id: str | None = None
+        self._interrupt_requested = False
+        self._interrupt_pending = False
         self.closed = False
         headers = _handshake_headers(socket)
         self.reasoning_included = "x-reasoning-included" in headers
@@ -68,32 +72,59 @@ class ResponsesWebSocketConnection:
             raise RuntimeError(
                 "Responses WebSocket connection already has an active response."
             )
+        finished = False
         try:
-            self._socket.send(encoded)
+            with self._state_lock:
+                self._response_id = None
+                self._interrupt_requested = False
+                self._interrupt_pending = False
+                self._socket.send(encoded)
+            terminal = False
             while True:
                 raw = self._socket.recv()
                 if raw in {None, "", b""}:
-                    self.closed = True
                     raise RuntimeError(
                         "Responses WebSocket closed before a terminal response event."
                     )
                 if isinstance(raw, bytes):
-                    self.closed = True
                     raise RuntimeError("Responses WebSocket returned unexpected binary data.")
                 try:
                     event = json.loads(raw)
                 except (TypeError, json.JSONDecodeError) as exc:
-                    self.closed = True
                     raise RuntimeError("Responses WebSocket returned invalid JSON.") from exc
                 if not isinstance(event, dict) or not isinstance(event.get("type"), str):
-                    self.closed = True
                     raise RuntimeError(
                         "Responses WebSocket returned an invalid event envelope."
                     )
                 if event["type"] == "error":
                     raise _event_error(event)
+                with self._state_lock:
+                    if event["type"] == "response.created":
+                        response = event.get("response")
+                        response_id = response.get("id") if isinstance(response, dict) else None
+                        if isinstance(response_id, str) and response_id:
+                            self._response_id = response_id
+                    elif event["type"] in {
+                        "response.interrupt.accepted", "response.interrupt.failed"
+                    }:
+                        if (
+                            not self._interrupt_pending
+                            or event.get("response_id") != self._response_id
+                        ):
+                            raise RuntimeError("Unexpected response interruption acknowledgement.")
+                        if event["type"] == "response.interrupt.failed":
+                            raise RuntimeError("Response interruption was rejected.")
+                        self._interrupt_pending = False
+                    if event["type"] in _TERMINAL_EVENTS:
+                        terminal = True
+                        # Prevent a late interrupt after completion while draining its ack.
+                        self._interrupt_requested = True
+                    done = terminal and not self._interrupt_pending
+                    if done:
+                        self._response_id = None
+                        finished = True
                 yield event
-                if event["type"] in _TERMINAL_EVENTS:
+                if done:
                     return
         except Exception:
             if not self.closed:
@@ -103,7 +134,37 @@ class ResponsesWebSocketConnection:
                     self.closed = True
             raise
         finally:
-            self._request_lock.release()
+            try:
+                with self._state_lock:
+                    self._response_id = None
+                    if not finished:
+                        self.close()
+            finally:
+                self._request_lock.release()
+
+    def interrupt(self) -> None:
+        """Interrupt the active response, discarding partial items.
+
+        Call after ``response.created``, including from another thread while
+        reading events. Continue consuming through both the acknowledgement
+        and terminal response event before reusing the connection.
+        """
+        with self._state_lock:
+            if self.closed:
+                raise RuntimeError("Responses WebSocket connection is closed.")
+            if self._response_id is None or self._interrupt_requested:
+                raise RuntimeError("No active response is available to interrupt.")
+            self._interrupt_requested = True
+            self._interrupt_pending = True
+            try:
+                self._socket.send(json.dumps({
+                    "type": "response.interrupt",
+                    "response_id": self._response_id,
+                    "mode": "discard_partial_items",
+                }, separators=(",", ":")))
+            except Exception:
+                self.close()
+                raise
 
     def create(self, request: Mapping[str, Any]) -> Iterator[dict[str, Any]]:
         """Alias for :meth:`events` using Responses resource terminology."""

{codex_backend_sdk-0.5.7 → codex_backend_sdk-0.5.9}/docs/api-reference.md

@@ -110,6 +110,13 @@ Supported backend fields are `input`, `model`, `instructions`, `include`,
 iterator; otherwise the SDK collects the mandatory backend SSE stream into a
 typed `Response`.
 
+`reasoning` dictionaries preserve additive backend controls such as
+`context="all_turns"`. Numeric custom effort strings (for example `"4096"`)
+are serialized as unsigned 64-bit JSON integers, matching Codex; named efforts
+remain strings. This also applies to compaction. Message history retains
+backend replay fields (`id`, `status`, `phase`, `encrypted_content`, and
+`internal_chat_message_metadata_passthrough`) and content-part metadata.
+
 For HTTP `create`, `parse` and `compact` requests, a nonempty `prompt_cache_key`
 also supplies the `session-id` header used by the ChatGPT backend for cache
 affinity. An explicit `session-id` in `extra_headers` takes precedence
@@ -165,11 +172,20 @@ Connection methods:
 | --- | --- | --- |
 | `create(request)` | raw Responses request mapping | iterator of raw event dictionaries |
 | `events(request)` | raw `response.create` event or request mapping | iterator through terminal completion/error |
+| `interrupt()` | none; active response must have emitted `response.created` | sends `response.interrupt` with `discard_partial_items` |
 | `close()` | none | `None` |
 
 The connection is a context manager and is reusable for sequential, not
 concurrent, turns. Backend error envelopes raise `ResponsesWebSocketError` with
-`code`, `message`, `event`, and optional `param`.
+`code`, the exception message, `event`, and optional `status`.
+
+After `interrupt()`, keep consuming events through both
+`response.interrupt.accepted` and the terminal response event. They may arrive
+in either order. The acknowledgement must match the active response ID;
+rejection or an invalid acknowledgement closes the connection. You can call
+`interrupt()` from another thread while consuming the stream. Abandoning an
+unfinished event iterator also closes the connection to prevent unread events
+from leaking into the next request.
 
 ### Models
 
@@ -234,7 +250,8 @@ content and a MIME type.
 Required: `file`, `model`. Supported optional backend parameters are `language`,
 `prompt`, `response_format` (`json` or `text`), `temperature`, `extra_headers`,
 `extra_query`, `extra_body`, and `timeout`. Returns typed `Transcription` for
-JSON or `str` for text.
+JSON or `str` for text. The legacy batch route returned HTTP 403 in live tests
+on October 24, 2026; prefer the verified transcription WebSocket below.
 
 The OpenAI-compatible signature rejects unsupported `chunking_strategy`,
 `include`, `known_speaker_names`, `known_speaker_references`, `stream`, and
@@ -255,6 +272,7 @@ Platform quota rather than the ChatGPT subscription.
 
 | Method | Parameters | Returns |
 | --- | --- | --- |
+| `client.realtime.connect(...)` | `intent="transcription"`, optional `timeout` | context manager yielding a JSON `RealtimeConnection` |
 | `client.live.create(...)` | official `session`, `transport`; standard request extensions | `LiveCreateResponse` with `session.id` and `transport.sdp` |
 | `client.live.sideband.connect(...)` | official sideband keywords including `session_id`, `graceful_close`, request/socket/retry options | lazy `LiveSidebandConnectionManager` context manager |
 | `client.realtime.calls.create_v3(...)` | `sdp`, `session`, optional `session_id`, `thread_id`, transport extensions | typed `RealtimeCallResponse` |
@@ -268,11 +286,11 @@ apply `response.transport.sdp`, then attach with
 adapter presents the backend call ID as the Live session ID. The connection is
 iterable and yields forward-compatible `LiveEvent` objects with attribute
 access. The public primary `client.live.connect()` transport raises an explicit
-unsupported error because ChatGPT OAuth currently exposes only WebRTC plus an
-attached sideband.
+unsupported error. This is distinct from the transcription-only primary
+`client.realtime.connect(intent="transcription")` socket, verified with OAuth
+on October 24, 2026. Its quota/billing attribution is not established.
 
-`create_v3()` requires the effective model to be `gpt-live-1-codex` or
-`gpt-live-1-boulder-alpha`, removes any caller-supplied session ID, generates
+`create_v3()` forwards the requested model and explicit correlation IDs, generates
 required backend correlation IDs when omitted, and applies the current Codex v3
 intent/architecture. The result exposes `answer_sdp`, `call_id`, raw `session`,
 and original response text. The sideband connection joins that call over
@@ -752,3 +770,25 @@ validation errors according to the boundary.
   mutations.
 - Commercial/admin, attestation, reporting, telemetry, analytics, beacon, and
   personal-access-token surfaces are outside the public SDK API.
+
+### Transcription-only OAuth WebSocket
+
+```python
+client.authenticate(interactive=False)
+with client.realtime.connect(intent="transcription", timeout=10) as connection:
+    connection.send({"type": "session.update", "session": {
+        "type": "transcription", "audio": {"input": {
+            "format": {"type": "audio/pcm", "rate": 24000},
+            "transcription": {"model": "gpt-4o-mini-transcribe", "language": "fr"},
+            "turn_detection": None,
+        }},
+    }})
+    # Wait for session.updated (handle error events), then send base64 PCM16LE
+    # mono chunks as input_audio_buffer.append and input_audio_buffer.commit.
+    # Receive conversation.item.input_audio_transcription.completed.
+```
+
+This synchronous raw-event surface has no automatic retry/replay, generated
+assistant response, tools, or output audio. Set a bounded socket timeout and an
+application-level total deadline. Context exit closes the socket even on failure.
+Only `intent="transcription"` is supported; model/session events remain caller-owned.

{codex_backend_sdk-0.5.7 → codex_backend_sdk-0.5.9}/docs/backend-api.md

@@ -402,7 +402,8 @@ low-level `client.realtime.sideband.connect(...)`) joins its
 JSON control/delegation channel at `/v1/live/{call_id}` with the current ChatGPT
 OAuth account. This transport is used for client-managed delegation events and
 context appends. The SDK intentionally does not expose the unrelated API-key
-Voice v2 WebSocket surface.
+Voice v2 conversation WebSocket surface. It separately exposes the verified
+transcription-only primary socket described below.
 
 ---
 
@@ -410,8 +411,10 @@ Voice v2 WebSocket surface.
 
 These OpenAI-shaped resources deliberately use different upstreams. Embeddings
 remain an OpenAI Platform call and consume the associated developer-account
-quota. Batch transcription uses the authenticated ChatGPT backend and does not
-require a developer API key.
+quota. Legacy batch transcription uses the authenticated ChatGPT backend but
+returned HTTP 403 in current live tests. The transcription-only Realtime socket
+accepts ChatGPT OAuth without a developer API key; its quota/billing attribution
+is not established.
 
 ### `POST /v1/embeddings`
 
@@ -437,13 +440,26 @@ subscription.
 
 **SDK method**: `client.audio.transcriptions.create(...)`
 
-**Status**: Supported for non-streaming ChatGPT batch transcription. The SDK
+**Status**: Legacy adapter present, but live tests with WebM and WAV returned
+HTTP 403 HTML on October 24, 2026. This is not proof of permanent removal. The SDK
 uploads multipart audio with the OAuth bearer and `ChatGPT-Account-ID`, and
 supports the `model`, `language`, `prompt`, `temperature`, and `json`/`text`
 response options used by Codex Agent. Streaming, timestamps, speaker references,
 chunking, SRT, and VTT are rejected locally rather than falling back to a
 billable Platform endpoint.
 
+### `WSS /v1/realtime?intent=transcription` (api.openai.com)
+
+**SDK method**: `client.realtime.connect(intent="transcription", timeout=...)`
+
+**Status**: Verified October 24, 2026 with a ChatGPT OAuth bearer, no API key.
+`session.update` with type `transcription`, PCM16LE mono 24 kHz,
+`gpt-4o-mini-transcribe`, and `turn_detection: null` accepted synthetic speech and
+returned the correct `conversation.item.input_audio_transcription.completed` text.
+The ChatGPT backend URL `/backend-api/codex/realtime?intent=transcription` instead
+returned HTTP 403. Subscription coverage and quota/billing attribution remain
+unverified; successful OAuth authentication alone does not establish either.
+
 ### `POST /backend-api/codex/images/generations`
 
 **SDK method**: `client.images.generate(...)`

codex_backend_sdk-0.5.9/docs/codex-source-audit.md

@@ -0,0 +1,61 @@
+# Codex source compatibility audit — 2026-10-22
+
+Compared `openai/codex` from the previously audited
+`7498521d288b9b3b96ffba4eedf089d8d6e06a84` to
+`0eb98b46176fd41fc285e5e2f82218bf0ccd70f5` (`origin/main`). The local checkout
+was updated by fast-forward and has no local changes. This is a source-contract
+audit; the packaged Desktop ASAR was not rescanned and no live backend requests
+were used to validate the new contracts.
+
+## Scope and method
+
+Reviewed changed production contracts in `codex-rs/codex-api`, `backend-client`,
+`core-plugins` remote catalog/search/sharing, `chatgpt` connectors,
+`app-server-transport` Remote Control, `login`, cloud tasks, and `cloud-client`.
+Searched changed Rust production sources across `codex-rs` for added backend
+route literals and checked request builders, response types, and protocol item
+changes. Local app-server JSON-RPC methods, CLI flags, and harness policy are
+outside this HTTP backend SDK's scope.
+
+## Findings and disposition
+
+| Upstream change | SDK disposition and verification |
+| --- | --- |
+| WebSocket `response.interrupt` with `response_id` and `mode: discard_partial_items` | Added `connection.interrupt()`. Tracks the active response, checks the acknowledgement ID, rejects failed/unsolicited acknowledgements, and drains both acknowledgement and terminal event before reuse. Closing an unfinished iterator retires the socket. Tests cover cross-thread interruption and completion arriving before acknowledgement. |
+| Numeric custom reasoning effort serialized as an unsigned 64-bit JSON number | HTTP Responses and compaction convert parseable numeric effort strings into integers, matching Codex. Existing numbers, named/custom string efforts, and additive dictionary options remain supported. Attribute-based controls retain `context`. Exported `ReasoningEffort` accepts strings and integers. |
+| Messages gain `encrypted_content` and `status`; `phase` gains `partial_answer`; output text gains `annotations`/`logprobs` | Message normalization now retains known replay fields, including `id`, `phase`, and metadata. Content parts and non-message items remain raw. A round-trip test protects opaque fields, empty arrays, `additional_tools`, and `configuration_update`. Local `kind`/`call_id` keys on ordinary messages remain filtered. |
+| Installed-plugin pagination always sends `limit`, including scoped requests | Fixed `.plugins.installed(scope=..., limit=...)`; validates and transmits the limit alongside the scope and cursor. Aggregation already rejects repeated cursors. |
+| Image edit references allow both `image_url` and `file_id` | Already supported; mixed references are contract-tested. HTTP failures retain the underlying response and headers, including nested ImageGen request IDs. |
+| Thread usage and groups gain `native_usage_usd_micros`; plugin release gains `onboarding_skill_name`; new plan names | Existing raw dictionaries preserve additive fields. Contract test distinguishes absent/null/zero/native amounts without estimating them. |
+| Base instructions move from the top-level field into developer input messages (`c9253c4977`) | Developer messages are supported, and their explicit IDs/metadata now survive normalization. The OpenAI-shaped `instructions=` argument keeps its existing top-level encoding for compatibility; removing it from Codex's own request struct does not establish backend rejection. No claim of live equivalence or retirement of the old field is made. |
+| Responses serializes `model`, `stream`, `service_tier` before large input (`ed0cc1a4ab`) | Values already supported; ordering is an upstream gateway optimization, not a newly required parameter. |
+| Provider-specific model catalog URLs and plugin product SKU become configurable | Provider/gateway configuration is outside the SDK's fixed ChatGPT backend routing. Catalog query overrides and plugin `codex` product headers remain supported. |
+| Realtime transcript handling, shared HTTP/network policy, proxy fallback, file PUT retries, OAuth storage/provenance changes | Existing endpoint paths and request schemas remain compatible. These client implementation/policy changes do not add required backend parameters. Realtime events and WebSocket envelopes remain raw. |
+| Native cloud ThreadService `Resume` and live `Attach` | **Inventory, unsupported.** Separate HTTP/2 gRPC/protobuf transport, not an HTTP JSON endpoint or app-server JSON-RPC. Upstream requires a caller-supplied trusted origin and explicitly does not establish production ingress. Do not guess a URL or send these payloads through the SDK's JSON transport. |
+
+Relevant source locations at the audited commit:
+
+- `codex-rs/codex-api/src/common.rs`
+- `codex-rs/codex-api/src/endpoint/responses_websocket.rs`
+- `codex-rs/core/src/client.rs` and `core/src/context/base_instructions.rs`
+- `codex-rs/protocol/src/models.rs`
+- `codex-rs/core-plugins/src/remote.rs`
+- `codex-rs/backend-client/src/client/thread_usage.rs`
+- `codex-rs/cloud-client/README.md`, `src/lib.rs`, and `src/wire.rs`
+
+No new HTTP route in the reviewed backend families requires a new SDK resource.
+The native gRPC surface is explicitly tracked above. Earlier Desktop-only
+coverage and exclusions remain as recorded in `desktop-endpoint-inventory.md`.
+
+## Validation
+
+Durable behavioral contracts added by this audit live in
+`tests/general/test_codex_source_contracts.py`. Existing local contract tests
+are also run; tests using the authenticated `client` fixture are excluded from
+the local-only run. No transient diagnostic tests are retained in
+`tests/agentic/`, and no backend mutation or inference is performed by these tests.
+
+Result: **310 passed, 12 live tests deselected**. Ruff's correctness rules
+(`E4`, `E7`, `E9`, `F`, Python 3.9 target) and `git diff --check` also pass for
+the changed Python files. The broader Ruff style rules report existing issues
+in these modules and are not a clean project baseline.

{codex_backend_sdk-0.5.7 → codex_backend_sdk-0.5.9}/docs/desktop-endpoint-inventory.md

@@ -5,6 +5,10 @@ routes referenced by the official Codex Desktop application but not necessarily
 by `codex-rs`. It is an implementation survey, not a stability guarantee or an
 assertion that every route is enabled for every account.
 
+For the later Codex checkout update through `0eb98b4617`, see the
+[2026-10-22 source audit](codex-source-audit.md). That audit does not replace or
+refresh the packaged Desktop snapshot recorded below.
+
 ## Audited snapshot and method
 
 - Codex checkout: `openai/codex` at

{codex_backend_sdk-0.5.7 → codex_backend_sdk-0.5.9}/docs/endpoint-coverage.md

@@ -4,6 +4,11 @@ This is the living implementation matrix for backend surfaces found in the
 official Codex and Codex Desktop clients. The source snapshot and discovery
 method are recorded in `desktop-endpoint-inventory.md`.
 
+The subsequent [2026-10-22 Codex source audit](codex-source-audit.md) records
+compatibility through `0eb98b46176fd41fc285e5e2f82218bf0ccd70f5`, including
+WebSocket interruption, message replay fields, numeric reasoning, scoped plugin
+pagination, and the separately inventoried native cloud gRPC transport.
+
 Statuses:
 
 - **live**: exercised against the backend with Codex OAuth;

{codex_backend_sdk-0.5.7 → codex_backend_sdk-0.5.9}/docs/openai-compatibility.md

@@ -20,7 +20,8 @@ parameter cannot disappear silently from the backend client surface.
 | `responses.compact` | Official parameters preserved; Codex tool/reasoning controls are additive | Supported request options and `extra_body` are forwarded | Stored-response continuation and explicit Platform prompt-cache controls are unavailable |
 | `models.list` / `retrieve` | Official parameters preserved; `force_refresh` is additive | Returns iterable OpenAI-shaped model pages | Catalog retrieval is a Codex endpoint and `retrieve` resolves from that catalog |
 | `embeddings.create` | Official signature preserved | Uses the OpenAI endpoint with the Codex OAuth bearer | Availability depends on OAuth scopes and account rollout |
-| `audio.transcriptions.create` | Official signature preserved | File inputs, JSON/text output, language, prompt, and temperature are supported | Streaming, diarization, timestamps, `keywords`, and multi-language hints raise explicitly |
+| `realtime.connect` | Transcription-only OAuth subset | Context manager, raw JSON send/recv, deterministic close | Only `intent="transcription"`; no automatic replay; quota attribution unverified |
+| `audio.transcriptions.create` | Official signature preserved | Legacy batch adapter retains file inputs and options; live route returned HTTP 403 on October 24, 2026 | Streaming, diarization, timestamps, `keywords`, and multi-language hints raise explicitly |
 | `images.generate` | Official signature preserved | GPT Image generation returns OpenAI-shaped base64 results | Codex always returns non-streamed PNG/base64 output; format/compression and Platform user attribution are unavailable |
 | `images.edit` | Official signature preserved | Single/multiple file inputs, URLs, data URLs, reference objects, and masks are normalized to Codex JSON | A mask targets the first image; `file_id` is contract-derived but not live-verified; Codex returns non-streamed PNG/base64 output |
 | `files.create` | Official signature is present | Not callable with Codex OAuth | Live probe returned missing `api.files.write`; the method raises a scope-specific unsupported error |

{codex_backend_sdk-0.5.7 → codex_backend_sdk-0.5.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codex-backend-sdk"
-version = "0.5.7"
+version = "0.5.9"
 description = "Unofficial Python SDK for the ChatGPT Codex backend API"
 readme = "README.md"
 license = { text = "MIT" }

codex_backend_sdk-0.5.9/tests/general/test_codex_source_contracts.py

@@ -0,0 +1,227 @@
+"""Durable wire guarantees for evolving Codex backend contracts."""
+
+import json
+from concurrent.futures import ThreadPoolExecutor
+from queue import Queue
+from threading import Event
+from types import SimpleNamespace
+
+import pytest
+
+from codex_backend_sdk import OpenAI, ResponsesWebSocketConnection
+
+
+class CapturingClient(OpenAI):
+    def __init__(self):
+        super().__init__(model="test-model")
+        self.calls = []
+
+    def _post(self, path, **kwargs):
+        self.calls.append((path, kwargs))
+        return SimpleNamespace(
+            iter_lines=lambda: iter([
+                b'data: {"type":"response.completed","response":{"id":"r1"}}', b""
+            ]),
+            close=lambda: None,
+        )
+
+    def _post_raw(self, path, **kwargs):
+        self.calls.append((path, kwargs))
+        return SimpleNamespace(json=lambda: {"created": 1, "data": []})
+
+    def _get_chatgpt(self, path, **kwargs):
+        self.calls.append((path, kwargs))
+        return {"plugins": [], "pagination": {"nextPageToken": None}}
+
+    def _post_wham(self, path, **kwargs):
+        self.calls.append((path, kwargs))
+        return {"threads": [{
+            "thread_id": "t1", "native_usage_usd_micros": None,
+            "groups": [{}, {"native_usage_usd_micros": 0}, {"native_usage_usd_micros": 250}],
+        }]}
+
+
+@pytest.mark.parametrize("effort,expected", [
+    (4096, 4096), ("4096", 4096), ("+4096", 4096), ("000", 0),
+    ("18446744073709551615", 2**64 - 1),
+    ("18446744073709551616", "18446744073709551616"),
+    ("high", "high"), ("custom-budget", "custom-budget"), ("-1", "-1"),
+])
+@pytest.mark.parametrize("compact", [False, True])
+def test_numeric_reasoning_and_context_reach_both_http_transports(effort, expected, compact):
+    client = CapturingClient()
+    reasoning = {"effort": effort, "context": "all_turns", "future_option": True}
+    if compact:
+        # Compaction needs an opaque result; inspect the request even if the fixture has none.
+        with pytest.raises(RuntimeError):
+            client.responses.compact(input=[], reasoning=reasoning)
+    else:
+        client.responses.create(input="hello", reasoning=reasoning)
+    assert client.calls[0][1]["body"]["reasoning"] == {
+        "effort": expected, "context": "all_turns", "future_option": True,
+    }
+    assert reasoning["effort"] == effort
+
+
+def test_reasoning_attribute_objects_preserve_context():
+    client = CapturingClient()
+    client.responses.create(
+        input="hello", reasoning=SimpleNamespace(effort="8192", context="current_turn")
+    )
+    assert client.calls[0][1]["body"]["reasoning"] == {
+        "effort": 8192, "context": "current_turn",
+    }
+
+
+def test_response_replay_preserves_opaque_message_fields_and_new_item_types():
+    client = CapturingClient()
+    items = [
+        {"type": "message", "id": "m1", "role": "developer", "content": [],
+         "internal_chat_message_metadata_passthrough": {
+             "content_item_kinds": ["model.base_instructions"],
+         }},
+        {"type": "message", "id": "m2", "role": "assistant", "status": "completed",
+         "phase": "partial_answer", "encrypted_content": "opaque", "content": [
+             {"type": "output_text", "text": "hello", "annotations": [], "logprobs": []},
+         ]},
+        {"type": "additional_tools", "role": "developer", "tools": []},
+        {"type": "configuration_update", "reasoning": {"effort": 4096}},
+    ]
+    client.responses.create(input=items)
+    assert client.calls[0][1]["body"]["input"] == items
+
+
+def test_installed_plugins_scope_keeps_limit_and_cursor():
+    client = CapturingClient()
+    client.chatgpt.plugins.installed(scope="WORKSPACE", limit=7, page_token="next")
+    assert client.calls[0][1]["params"] == {
+        "scope": "WORKSPACE", "limit": 7, "pageToken": "next",
+    }
+    with pytest.raises(ValueError):
+        client.chatgpt.plugins.installed(scope="WORKSPACE", limit=0)
+
+
+def test_image_file_references_and_native_usage_are_preserved():
+    client = CapturingClient()
+    images = [{"image_url": "data:image/png;base64,Zm9v"}, {"file_id": "file-image"}]
+    client.images.edit(image=images, prompt="add a red hat")
+    assert client.calls[0][1]["body"]["images"] == images
+    assert client.codex.usage_details.threads(["t1"]) == {"threads": [{
+        "thread_id": "t1", "native_usage_usd_micros": None,
+        "groups": [{}, {"native_usage_usd_micros": 0}, {"native_usage_usd_micros": 250}],
+    }]}
+
+
+class Socket:
+    def __init__(self, events):
+        self.events = iter(events)
+        self.sent = []
+        self.closed = False
+
+    def send(self, message):
+        self.sent.append(json.loads(message))
+
+    def recv(self):
+        event = next(self.events, None)
+        return "" if event is None else json.dumps(event)
+
+    def close(self):
+        self.closed = True
+
+
+@pytest.mark.parametrize("ack_first", [True, False])
+def test_interrupt_drains_ack_and_completion_before_socket_reuse(ack_first):
+    ack = {"type": "response.interrupt.accepted", "response_id": "r1"}
+    terminal = {"type": "response.completed", "response": {"id": "r1"}}
+    socket = Socket([
+        {"type": "response.created", "response": {"id": "r1"}},
+        *([ack, terminal] if ack_first else [terminal, ack]),
+        {"type": "response.completed", "response": {"id": "r2"}},
+    ])
+    connection = ResponsesWebSocketConnection(socket, url="wss://example.test")
+    with pytest.raises(RuntimeError, match="No active"):
+        connection.interrupt()
+    stream = connection.events({"model": "test-model"})
+    next(stream)
+    connection.interrupt()
+    assert socket.sent[-1] == {
+        "type": "response.interrupt", "response_id": "r1", "mode": "discard_partial_items",
+    }
+    with pytest.raises(RuntimeError, match="No active"):
+        connection.interrupt()
+    assert len(list(stream)) == 2
+    second = list(connection.events({"model": "test-model"}))
+    assert second[0]["response"]["id"] == "r2"
+    assert not socket.closed
+
+
+@pytest.mark.parametrize("ack", [
+    {"type": "response.interrupt.accepted", "response_id": "wrong"},
+    {"type": "response.interrupt.failed", "response_id": "r1"},
+    {"type": "response.interrupt.accepted"},
+])
+def test_invalid_interrupt_ack_retires_socket(ack):
+    socket = Socket([{"type": "response.created", "response": {"id": "r1"}}, ack])
+    connection = ResponsesWebSocketConnection(socket, url="wss://example.test")
+    stream = connection.events({"model": "test-model"})
+    next(stream)
+    connection.interrupt()
+    with pytest.raises(RuntimeError, match="interruption"):
+        list(stream)
+    assert socket.closed and connection.closed
+
+
+def test_abandoned_stream_cannot_reuse_socket_with_unread_events():
+    socket = Socket([{"type": "response.created", "response": {"id": "r1"}}])
+    connection = ResponsesWebSocketConnection(socket, url="wss://example.test")
+    stream = connection.events({"model": "test-model"})
+    next(stream)
+    stream.close()
+    assert socket.closed and connection.closed
+
+
+@pytest.mark.parametrize("remaining", [
+    [],
+    [{"type": "response.completed", "response": {"id": "r1"}}],
+    [{"type": "response.interrupt.accepted", "response_id": "r1"}],
+])
+def test_incomplete_interrupt_drain_closes_socket(remaining):
+    socket = Socket([{"type": "response.created", "response": {"id": "r1"}}, *remaining])
+    connection = ResponsesWebSocketConnection(socket, url="wss://example.test")
+    stream = connection.events({"model": "test-model"})
+    next(stream)
+    connection.interrupt()
+    with pytest.raises(RuntimeError, match="closed before"):
+        list(stream)
+    assert socket.closed and connection.closed
+
+
+def test_interrupt_from_another_thread_while_receiving():
+    ready = Event()
+    incoming = Queue()
+    incoming.put({"type": "response.created", "response": {"id": "r1"}})
+
+    class BlockingSocket(Socket):
+        def recv(self):
+            if len(self.sent) == 1 and incoming.empty():
+                ready.set()
+            return json.dumps(incoming.get(timeout=3))
+
+        def send(self, message):
+            super().send(message)
+            if self.sent[-1]["type"] == "response.interrupt":
+                incoming.put({"type": "response.interrupt.accepted", "response_id": "r1"})
+                incoming.put({"type": "response.completed", "response": {"id": "r1"}})
+
+    socket = BlockingSocket([])
+    connection = ResponsesWebSocketConnection(socket, url="wss://example.test")
+    with ThreadPoolExecutor(max_workers=1) as executor:
+        result = executor.submit(lambda: list(connection.events({"model": "test-model"})))
+        try:
+            assert ready.wait(timeout=3)
+            connection.interrupt()
+            assert [event["type"] for event in result.result(timeout=3)] == [
+                "response.created", "response.interrupt.accepted", "response.completed",
+            ]
+        finally:
+            connection.close()

{codex_backend_sdk-0.5.7 → codex_backend_sdk-0.5.9}/tests/test_realtime_resource.py

@@ -279,3 +279,37 @@ def test_realtime_call_response_requires_valid_location():
         assert "does not contain a valid call id" in str(exc)
     else:
         raise AssertionError("Expected invalid Location to fail")
+
+
+def test_primary_transcription_socket_uses_oauth_and_closes_on_failure(monkeypatch):
+    client = FakeRealtimeClient()
+    socket = FakeWebSocket([json.dumps({"type": "session.created"})])
+    captured = {}
+    def connect(url, **kwargs):
+        captured.update(url=url, **kwargs)
+        return socket
+    monkeypatch.setattr("codex_backend_sdk.resources.realtime.websocket.create_connection", connect)
+    with pytest.raises(ValueError, match="consumer"):
+        with client.realtime.connect(intent="transcription", timeout=12) as connection:
+            assert connection.recv() == {"type": "session.created"}
+            connection.send({"type": "input_audio_buffer.commit"})
+            raise ValueError("consumer")
+    assert captured["url"] == "wss://api.openai.com/v1/realtime?intent=transcription"
+    assert captured["header"]["Authorization"] == "Bearer chatgpt-token"
+    assert captured["header"]["ChatGPT-Account-ID"] == "account-id"
+    assert captured["header"]["x-session-id"]
+    assert captured["timeout"] == 12
+    assert captured["redirect_limit"] == 0
+    assert json.loads(socket.sent[0]) == {"type": "input_audio_buffer.commit"}
+    assert socket.closed
+
+
+def test_primary_socket_rejects_other_intents_and_missing_oauth():
+    client = FakeRealtimeClient()
+    with pytest.raises(NotImplementedError):
+        with client.realtime.connect(intent="realtime"):
+            pass
+    client._store = None
+    with pytest.raises(RuntimeError, match="ChatGPT OAuth"):
+        with client.realtime.connect(intent="transcription"):
+            pass

{codex_backend_sdk-0.5.7 → codex_backend_sdk-0.5.9}/uv.lock

@@ -162,7 +162,7 @@ wheels = [
 
 [[package]]
 name = "codex-backend-sdk"
-version = "0.5.7"
+version = "0.5.9"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },