codex-backend-sdk 0.5.6__tar.gz → 0.5.8__tar.gz

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.8}/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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
+- Discover the latest stable Codex CLI version over credential-free HTTPS for
+  model catalogs instead of sending a stale fixed version that can hide models.
+  Share a 24-hour process cache, retain a verified fallback on registry failure,
+  and allow an explicit `extra_query` version without registry access.
+- Keep catalogs fetched with custom request options out of the default cache.
+
 ## [0.5.6] - 2026-10-22
 
 ### Fixed

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codex-backend-sdk
-Version: 0.5.6
+Version: 0.5.8
 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
@@ -278,6 +296,24 @@ for model in client.models.list():
 model = client.models.retrieve("gpt-5.5")
 ```
 
+Model discovery obtains the latest stable Codex CLI version over HTTPS from the
+public npm registry; Node, npm and the Codex binary are not required. The version
+is cached for 24 hours per process, shared across clients. The lookup uses a
+separate request without backend credentials and a three-second timeout. On
+failure it keeps the last known version (or a bundled verified fallback) and
+retries no sooner than five minutes later. This only updates the advertised
+catalog version, not the SDK's implementation of backend features.
+
+To pin the catalog version and skip registry access entirely:
+
+```python
+models = client.models.list(extra_query={"client_version": "0.159.2"})
+```
+
+`force_refresh=True` bypasses the five-minute model catalog cache, not the
+24-hour version cache. Requests with explicit options do not replace the default
+catalog cache. Other protocol and application version fields are independent.
+
 ### Upload a file
 
 ```python

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.8}/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
@@ -249,6 +267,24 @@ for model in client.models.list():
 model = client.models.retrieve("gpt-5.5")
 ```
 
+Model discovery obtains the latest stable Codex CLI version over HTTPS from the
+public npm registry; Node, npm and the Codex binary are not required. The version
+is cached for 24 hours per process, shared across clients. The lookup uses a
+separate request without backend credentials and a three-second timeout. On
+failure it keeps the last known version (or a bundled verified fallback) and
+retries no sooner than five minutes later. This only updates the advertised
+catalog version, not the SDK's implementation of backend features.
+
+To pin the catalog version and skip registry access entirely:
+
+```python
+models = client.models.list(extra_query={"client_version": "0.159.2"})
+```
+
+`force_refresh=True` bypasses the five-minute model catalog cache, not the
+24-hour version cache. Requests with explicit options do not replace the default
+catalog cache. Other protocol and application version fields are independent.
+
 ### Upload a file
 
 ```python

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.8}/codex_backend_sdk/__init__.py

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

codex_backend_sdk-0.5.8/codex_backend_sdk/_codex_version.py

@@ -0,0 +1,45 @@
+"""Shared discovery of the upstream Codex CLI version (not the SDK version)."""
+
+import re
+import threading
+import time
+
+import requests
+
+
+# Last verified upstream protocol version, used when discovery is unavailable.
+CLIENT_VERSION = "0.163.0"
+_RETRY_TTL = 300
+_VERSION_TTL = 24 * 60 * 60
+_VERSION_URL = "https://registry.npmjs.org/@openai/codex/latest"
+_version = CLIENT_VERSION
+_version_refresh_at = 0.0
+_version_lock = threading.Lock()
+
+
+def codex_client_version() -> str:
+    """Discover the stable CLI version without sharing backend credentials.
+
+    Cache across clients in this process. Failed refreshes retain the last known
+    version and wait five minutes before retrying, including on first use.
+    """
+    global _version, _version_refresh_at
+    with _version_lock:
+        if time.monotonic() < _version_refresh_at:
+            return _version
+        ttl = _VERSION_TTL
+        try:
+            with requests.get(_VERSION_URL, timeout=3) as response:
+                response.raise_for_status()
+                payload = response.json()
+            candidate = payload.get("version") if isinstance(payload, dict) else None
+            if not isinstance(candidate, str) or not re.fullmatch(
+                r"[0-9]+\.[0-9]+\.[0-9]+", candidate
+            ):
+                raise ValueError("Invalid stable Codex version")
+            _version = candidate
+        except (requests.RequestException, ValueError):
+            ttl = _RETRY_TTL
+        _version_refresh_at = time.monotonic() + ttl
+        return _version
+

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.8}/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.6 → codex_backend_sdk-0.5.8}/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.6 → codex_backend_sdk-0.5.8}/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.6 → codex_backend_sdk-0.5.8}/codex_backend_sdk/resources/models.py

@@ -5,18 +5,15 @@ from __future__ import annotations
 import time
 from typing import Any, TYPE_CHECKING
 
+from .._codex_version import codex_client_version
 from .._models import Model, SyncPage
 from .._utils import _UNSET, CodexBackendUnsupportedParameterError, _is_given
 
 if TYPE_CHECKING:
     from .._client import CodexClient
 
-# This is the upstream Codex CLI protocol/client version expected by the
-# ChatGPT backend, not the PyPI package version.
-CLIENT_VERSION = "0.130.0"
 _CACHE_TTL = 300
 
-
 class Models:
     def __init__(self, client: CodexClient) -> None:
         self._client = client
@@ -41,7 +38,9 @@ class Models:
             if time.time() - self._cache_fetched_at <= _CACHE_TTL:
                 return self._cache
 
-        params = {"client_version": CLIENT_VERSION, **(extra_query or {})}
+        params = dict(extra_query or {})
+        if "client_version" not in params:
+            params["client_version"] = codex_client_version()
         response = self._client._get_raw(
             "/models", params=params, headers=extra_headers, timeout=timeout
         )
@@ -49,8 +48,9 @@ class Models:
         models = [_model_from_backend(item) for item in data.get("models", [])]
         models.sort(key=lambda model: getattr(model, "priority", 0))
         page = SyncPage(data=models, etag=response.headers.get("ETag"))
-        self._cache = page
-        self._cache_fetched_at = time.time()
+        if not has_request_options:
+            self._cache = page
+            self._cache_fetched_at = time.time()
         return page
 
     def retrieve(

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.8}/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.6 → codex_backend_sdk-0.5.8}/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,17 +172,26 @@ 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
 
 | Method | Parameters | Returns |
 | --- | --- | --- |
-| `client.models.list(...)` | `force_refresh=False`, `extra_headers=None`, `extra_query=None`, `extra_body=None`, `timeout=UNSET` | iterable `SyncPage` with optional `etag`; cached for 5 minutes |
+| `client.models.list(...)` | `force_refresh=False`, `extra_headers=None`, `extra_query=None`, `extra_body=None`, `timeout=UNSET` | iterable `SyncPage` with optional `etag`; default catalog cached for 5 minutes; Codex version auto-discovered over HTTPS (24-hour process cache), or pinned via `extra_query["client_version"]` |
 | `client.models.retrieve(...)` | `model`, plus the same transport controls | one typed `Model`; raises `LookupError` if absent |
 
 `Model` preserves Codex fields including display metadata, context window,

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.8}/docs/backend-api.md

@@ -78,7 +78,11 @@ List models available to this account.
 **SDK method**: `client.models.list()` / `client.models.retrieve(model)`
 
 **Query params**
-- `client_version` — Codex CLI protocol/client version string (e.g. `"0.130.0"`).
+- `client_version` — Codex CLI version string. The SDK discovers the latest stable
+  version from the public npm registry over HTTPS (24-hour in-process cache;
+  three-second timeout; last-known/bundled fallback with five-minute retry
+  backoff). Override with `extra_query={"client_version": "0.159.2"}` to skip
+  discovery. No Node/npm installation is required.
 
 **Response** — JSON `{ "models": [ ModelObject, … ] }`
 

codex_backend_sdk-0.5.8/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.6 → codex_backend_sdk-0.5.8}/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.6 → codex_backend_sdk-0.5.8}/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.6 → codex_backend_sdk-0.5.8}/pyproject.toml

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

codex_backend_sdk-0.5.8/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.8/tests/test_codex_version.py

@@ -0,0 +1,88 @@
+"""Offline tests for upstream version discovery; no OAuth or npm binary."""
+
+from concurrent.futures import ThreadPoolExecutor
+from unittest.mock import MagicMock
+
+import pytest
+import requests
+
+from codex_backend_sdk import _codex_version as version
+
+
+@pytest.fixture
+def registry(monkeypatch):
+    clock = [100.0]
+    monkeypatch.setattr(version.time, "monotonic", lambda: clock[0])
+    monkeypatch.setattr(version, "_version", version.CLIENT_VERSION)
+    monkeypatch.setattr(version, "_version_refresh_at", 0.0)
+    response = MagicMock()
+    response.__enter__.return_value = response
+    response.json.return_value = {"version": "0.170.0"}
+    get = MagicMock(return_value=response)
+    monkeypatch.setattr(version.requests, "get", get)
+    return clock, get, response
+
+
+def test_version_uses_standalone_https_and_caches_for_24_hours(registry):
+    clock, get, response = registry
+    assert version.codex_client_version() == "0.170.0"
+    get.assert_called_once_with(version._VERSION_URL, timeout=3)
+    response.raise_for_status.assert_called_once()
+    response.__exit__.assert_called_once()
+    clock[0] += 86400 - 1
+    assert version.codex_client_version() == "0.170.0"
+    assert get.call_count == 1
+    clock[0] += 1
+    response.json.return_value = {"version": "0.171.0"}
+    assert version.codex_client_version() == "0.171.0"
+    assert get.call_count == 2
+
+
+@pytest.mark.parametrize("error", [requests.Timeout(), requests.HTTPError(), ValueError()])
+def test_first_failure_uses_verified_fallback_and_backs_off(registry, error):
+    clock, get, _ = registry
+    get.side_effect = error
+    assert version.codex_client_version() == version.CLIENT_VERSION
+    assert version.codex_client_version() == version.CLIENT_VERSION
+    assert get.call_count == 1
+    clock[0] += 300
+    get.side_effect = None
+    assert version.codex_client_version() == "0.170.0"
+    assert get.call_count == 2
+
+
+
+@pytest.mark.parametrize("stage", ["raise_for_status", "json"])
+def test_response_errors_close_request_and_use_fallback(registry, stage):
+    _, _, response = registry
+    error = requests.HTTPError() if stage == "raise_for_status" else ValueError()
+    getattr(response, stage).side_effect = error
+    assert version.codex_client_version() == version.CLIENT_VERSION
+    response.__exit__.assert_called_once()
+
+
+def test_refresh_failure_keeps_last_success(registry):
+    clock, get, _ = registry
+    assert version.codex_client_version() == "0.170.0"
+    clock[0] += 86400
+    get.side_effect = requests.ConnectionError()
+    assert version.codex_client_version() == "0.170.0"
+    assert version.codex_client_version() == "0.170.0"
+    assert get.call_count == 2
+
+
+@pytest.mark.parametrize("payload", [
+    None, [], {}, {"version": 123}, {"version": "0.170.0-beta.1"},
+    {"version": "garbage"}, {"version": "0.170.0\n"},
+])
+def test_invalid_registry_metadata_uses_fallback(registry, payload):
+    _, _, response = registry
+    response.json.return_value = payload
+    assert version.codex_client_version() == version.CLIENT_VERSION
+
+
+def test_concurrent_clients_share_one_lookup(registry):
+    _, get, _ = registry
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        assert list(pool.map(lambda _: version.codex_client_version(), range(16))) == ["0.170.0"] * 16
+    assert get.call_count == 1

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.8}/tests/test_responses_resource.py

@@ -5,6 +5,12 @@ import pytest
 from pydantic import BaseModel
 
 from codex_backend_sdk import OpenAI, ParsedResponse, Response
+from codex_backend_sdk.resources import models as models_resource
+
+
+@pytest.fixture(autouse=True)
+def stable_catalog_version(monkeypatch):
+    monkeypatch.setattr(models_resource, "codex_client_version", lambda: "0.163.0")
 
 
 class FakeSSE:
@@ -363,12 +369,33 @@ def test_models_resource_forwards_official_request_options():
 
     assert client.gets[1] == (
         "/models",
-        {"client_version": "0.130.0", "preview": "1"},
+        {"client_version": "0.163.0", "preview": "1"},
         {"x-test": "header"},
         19,
     )
 
 
+
+def test_explicit_catalog_version_skips_discovery_and_does_not_replace_default_cache(monkeypatch):
+    client = FakeClient()
+    default = client.models.list()
+    def unexpected_lookup():
+        raise AssertionError("Explicit version must not contact registry")
+    monkeypatch.setattr(models_resource, "codex_client_version", unexpected_lookup)
+    custom = client.models.list(extra_query={"client_version": "0.159.2"})
+    assert custom is not default
+    assert client.gets[-1][1] == {"client_version": "0.159.2"}
+    assert client.models.list() is default
+
+
+def test_forced_catalog_refresh_resolves_version_again(monkeypatch):
+    client = FakeClient()
+    client.models.list()
+    monkeypatch.setattr(models_resource, "codex_client_version", lambda: "0.171.0")
+    client.models.list(force_refresh=True)
+    assert client.gets[-1][1] == {"client_version": "0.171.0"}
+
+
 def test_responses_compact_sends_shared_request_fields():
     client = FakeClient()
 

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.8}/uv.lock

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