[1/8] Pin Python SDK runtime dependency (#21891)

## Why

The Python SDK depends on the app-server runtime package for the bundled
`codex` binary and schema source of truth. That relationship should be
explicit in package metadata instead of inferred from matching version
numbers, so installers, lockfiles, and reviewers can see exactly which
runtime the SDK expects.

## What

- Declare `openai-codex-cli-bin==0.131.0a4` as a Python SDK dependency.
- Update runtime setup helpers to resolve the runtime version from the
declared dependency pin.
- Refresh the SDK lockfile for the pinned runtime wheel.
- Update package/runtime tests and docs that describe where the runtime
version comes from.

## Stack

1. This PR `[1/8]` Pin Python SDK runtime dependency
2. #21893 `[2/8]` Generate Python SDK types from pinned runtime
3. #21895 `[3/8]` Run Python SDK tests in CI
4. #21896 `[4/8]` Define Python SDK public API surface
5. #21905 `[5/8]` Rename Python SDK package to `openai-codex`
6. #21910 `[6/8]` Add high-level Python SDK approval mode
7. #22014 `[7/8]` Add Python SDK app-server integration harness
8. #22021 `[8/8]` Add Python SDK Ruff formatting

## Verification

- Added coverage for the SDK runtime dependency pin and runtime
distribution naming.

---------

Co-authored-by: Codex <noreply@openai.com>

sdk/python/tests/test_artifact_workflow_and_binaries.py

@@ -163,8 +163,9 @@ def test_runtime_package_template_has_no_checked_in_binaries() -> None:
 
 
 def test_examples_readme_points_to_runtime_version_source_of_truth() -> None:
+    """Document that examples should point at the dependency pin, not release lore."""
     readme = (ROOT / "examples" / "README.md").read_text()
-    assert "The pinned runtime version comes from the SDK package version." in readme
+    assert "The pinned runtime version comes from the SDK package dependency." in readme
 
 
 def test_runtime_distribution_name_is_consistent() -> None:
@@ -211,12 +212,33 @@ def test_release_metadata_retries_without_invalid_auth(
     assert authorizations == ["Bearer invalid-token", None]
 
 
+def test_source_sdk_package_pins_published_runtime() -> None:
+    """The source package metadata should pin the runtime wheel that ships schemas."""
+    pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text())
+
+    assert {
+        "sdk_version": pyproject["project"]["version"],
+        "dependencies": pyproject["project"]["dependencies"],
+    } == {
+        "sdk_version": "0.131.0a4",
+        "dependencies": [
+            "pydantic>=2.12",
+            "openai-codex-cli-bin==0.131.0a4",
+        ],
+    }
+
+
 def test_runtime_setup_uses_pep440_package_version_and_codex_release_tags() -> None:
+    """The SDK uses PEP 440 package pins and converts only when fetching releases."""
     runtime_setup = _load_runtime_setup_module()
     pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text())
 
     assert runtime_setup.PACKAGE_NAME == "openai-codex-cli-bin"
     assert runtime_setup.pinned_runtime_version() == pyproject["project"]["version"]
+    assert (
+        f"{runtime_setup.PACKAGE_NAME}=={pyproject['project']['version']}"
+        in pyproject["project"]["dependencies"]
+    )
     assert (
         runtime_setup._normalized_package_version("rust-v0.116.0-alpha.1")
         == "0.116.0a1"
@@ -352,6 +374,7 @@ def test_stage_runtime_release_can_pin_wheel_platform_tag(tmp_path: Path) -> Non
 
 
 def test_stage_runtime_release_copies_resource_binaries(tmp_path: Path) -> None:
+    """Runtime staging should copy every helper binary into the wheel bin dir."""
     script = _load_update_script_module()
     fake_binary = tmp_path / script.runtime_binary_name()
     helper = tmp_path / "helper"
@@ -382,6 +405,7 @@ def test_stage_runtime_release_copies_resource_binaries(tmp_path: Path) -> None:
 def test_runtime_resource_binaries_are_included_by_wheel_config(
     tmp_path: Path,
 ) -> None:
+    """The runtime wheel config should include helper binaries beside Codex."""
     script = _load_update_script_module()
     fake_binary = tmp_path / script.runtime_binary_name()
     helper = tmp_path / "helper"

sdk/python/tests/test_async_client_behavior.py

@@ -13,12 +13,15 @@ from codex_app_server.models import Notification, UnknownNotification
 
 
 def test_async_client_allows_concurrent_transport_calls() -> None:
+    """Async wrappers should offload sync calls so concurrent awaits can overlap."""
     async def scenario() -> int:
+        """Run two blocking sync calls and report peak overlap."""
         client = AsyncAppServerClient()
         active = 0
         max_active = 0
 
         def fake_model_list(include_hidden: bool = False) -> bool:
+            """Simulate a blocking sync transport call."""
             nonlocal active, max_active
             active += 1
             max_active = max(max_active, active)
@@ -34,16 +37,20 @@ def test_async_client_allows_concurrent_transport_calls() -> None:
 
 
 def test_async_stream_text_is_incremental_without_blocking_parallel_calls() -> None:
+    """Async text streaming should yield incrementally without blocking other calls."""
     async def scenario() -> tuple[str, list[str], bool]:
+        """Start a stream, then prove another async client call can finish."""
         client = AsyncAppServerClient()
 
         def fake_stream_text(thread_id: str, text: str, params=None):  # type: ignore[no-untyped-def]
+            """Yield one item before sleeping so the async wrapper can interleave."""
             yield "first"
             time.sleep(0.03)
             yield "second"
             yield "third"
 
         def fake_model_list(include_hidden: bool = False) -> str:
+            """Return immediately to prove the event loop was not monopolized."""
             return "done"
 
         client._sync.stream_text = fake_stream_text  # type: ignore[method-assign]
@@ -70,7 +77,9 @@ def test_async_stream_text_is_incremental_without_blocking_parallel_calls() -> N
 
 
 def test_async_client_turn_notification_methods_delegate_to_sync_client() -> None:
+    """Async turn routing methods should preserve sync-client registration semantics."""
     async def scenario() -> tuple[list[tuple[str, str]], Notification, str]:
+        """Record the sync-client calls made by async turn notification wrappers."""
         client = AsyncAppServerClient()
         event = Notification(
             method="unknown/direct",
@@ -85,16 +94,20 @@ def test_async_client_turn_notification_methods_delegate_to_sync_client() -> Non
         calls: list[tuple[str, str]] = []
 
         def fake_register(turn_id: str) -> None:
+            """Record turn registration through the wrapped sync client."""
             calls.append(("register", turn_id))
 
         def fake_unregister(turn_id: str) -> None:
+            """Record turn unregistration through the wrapped sync client."""
             calls.append(("unregister", turn_id))
 
         def fake_next(turn_id: str) -> Notification:
+            """Return one routed notification through the wrapped sync client."""
             calls.append(("next", turn_id))
             return event
 
         def fake_wait(turn_id: str) -> TurnCompletedNotification:
+            """Return one completion through the wrapped sync client."""
             calls.append(("wait", turn_id))
             return completed
 
@@ -132,7 +145,9 @@ def test_async_client_turn_notification_methods_delegate_to_sync_client() -> Non
 
 
 def test_async_stream_text_uses_sync_turn_routing() -> None:
+    """Async text streaming should consume the same per-turn routing path as sync."""
     async def scenario() -> tuple[list[tuple[str, str]], list[str]]:
+        """Record routing calls while streaming two deltas and one completion."""
         client = AsyncAppServerClient()
         notifications = [
             Notification(
@@ -170,17 +185,21 @@ def test_async_stream_text_uses_sync_turn_routing() -> None:
         calls: list[tuple[str, str]] = []
 
         def fake_turn_start(thread_id: str, text: str, *, params=None):  # type: ignore[no-untyped-def]
+            """Return a started turn id while recording the request thread."""
             calls.append(("turn_start", thread_id))
             return SimpleNamespace(turn=SimpleNamespace(id="turn-1"))
 
         def fake_register(turn_id: str) -> None:
+            """Record stream registration for the started turn."""
             calls.append(("register", turn_id))
 
         def fake_next(turn_id: str) -> Notification:
+            """Return the next queued turn notification."""
             calls.append(("next", turn_id))
             return notifications.pop(0)
 
         def fake_unregister(turn_id: str) -> None:
+            """Record stream cleanup for the started turn."""
             calls.append(("unregister", turn_id))
 
         client._sync.turn_start = fake_turn_start  # type: ignore[method-assign]

sdk/python/tests/test_client_rpc_methods.py

@@ -135,6 +135,7 @@ def test_invalid_notification_payload_falls_back_to_unknown() -> None:
 
 
 def test_generated_notification_turn_id_handles_known_payload_shapes() -> None:
+    """Generated routing metadata should cover direct, nested, and unscoped payloads."""
     direct = AgentMessageDeltaNotification.model_validate(
         {
             "delta": "hello",
@@ -159,6 +160,7 @@ def test_generated_notification_turn_id_handles_known_payload_shapes() -> None:
 
 
 def test_turn_notification_router_demuxes_registered_turns() -> None:
+    """The router should deliver out-of-order turn events to the matching queues."""
     client = AppServerClient()
     client.register_turn_notifications("turn-1")
     client.register_turn_notifications("turn-2")
@@ -201,6 +203,7 @@ def test_turn_notification_router_demuxes_registered_turns() -> None:
 
 
 def test_client_reader_routes_interleaved_turn_notifications_by_turn_id() -> None:
+    """Reader-loop routing should preserve order within each interleaved turn stream."""
     client = AppServerClient()
     client.register_turn_notifications("turn-1")
     client.register_turn_notifications("turn-2")
@@ -245,6 +248,7 @@ def test_client_reader_routes_interleaved_turn_notifications_by_turn_id() -> Non
     ]
 
     def fake_read_message() -> dict[str, object]:
+        """Feed the reader loop a realistic interleaved stdout sequence."""
         if messages:
             return messages.pop(0)
         raise EOFError
@@ -278,6 +282,7 @@ def test_client_reader_routes_interleaved_turn_notifications_by_turn_id() -> Non
 
 
 def test_turn_notification_router_buffers_events_before_registration() -> None:
+    """Early turn events should be replayed once their TurnHandle registers."""
     client = AppServerClient()
     client._router.route_notification(
         client._coerce_notification(
@@ -302,6 +307,7 @@ def test_turn_notification_router_buffers_events_before_registration() -> None:
 
 
 def test_turn_notification_router_clears_unregistered_turn_when_completed() -> None:
+    """A completed unregistered turn should not leave a pending queue behind."""
     client = AppServerClient()
     client._router.route_notification(
         client._coerce_notification(
@@ -328,6 +334,7 @@ def test_turn_notification_router_clears_unregistered_turn_when_completed() -> N
 
 
 def test_turn_notification_router_routes_unknown_turn_notifications() -> None:
+    """Unknown notifications should still route when their raw params carry a turn id."""
     client = AppServerClient()
     client.register_turn_notifications("turn-1")
     client.register_turn_notifications("turn-2")

sdk/python/tests/test_public_api_runtime_behavior.py

@@ -227,6 +227,7 @@ def test_async_codex_initializes_only_once_under_concurrency() -> None:
 
 
 def test_turn_streams_can_consume_multiple_turns_on_one_client() -> None:
+    """Two sync TurnHandle streams should advance independently on one client."""
     client = AppServerClient()
     notifications: dict[str, deque[Notification]] = {
         "turn-1": deque(
@@ -257,10 +258,13 @@ def test_turn_streams_can_consume_multiple_turns_on_one_client() -> None:
 
 
 def test_async_turn_streams_can_consume_multiple_turns_on_one_client() -> None:
+    """Two async TurnHandle streams should advance independently on one client."""
     async def scenario() -> None:
+        """Interleave two async streams backed by separate per-turn queues."""
         codex = AsyncCodex()
 
         async def fake_ensure_initialized() -> None:
+            """Avoid starting a real app-server process for this stream test."""
             return None
 
         notifications: dict[str, deque[Notification]] = {
@@ -279,6 +283,7 @@ def test_async_turn_streams_can_consume_multiple_turns_on_one_client() -> None:
         }
 
         async def fake_next_notification(turn_id: str) -> Notification:
+            """Return the next notification from the requested per-turn queue."""
             return notifications[turn_id].popleft()
 
         codex._ensure_initialized = fake_ensure_initialized  # type: ignore[method-assign]
@@ -468,6 +473,7 @@ def test_thread_run_raises_on_failed_turn() -> None:
 
 
 def test_stream_text_registers_and_consumes_turn_notifications() -> None:
+    """stream_text should register, consume, and unregister one turn queue."""
     client = AppServerClient()
     notifications: deque[Notification] = deque(
         [
@@ -482,13 +488,16 @@ def test_stream_text_registers_and_consumes_turn_notifications() -> None:
     )
 
     def fake_register(turn_id: str) -> None:
+        """Record registration for the turn created by stream_text."""
         calls.append(("register", turn_id))
 
     def fake_next(turn_id: str) -> Notification:
+        """Return the next queued notification for stream_text."""
         calls.append(("next", turn_id))
         return notifications.popleft()
 
     def fake_unregister(turn_id: str) -> None:
+        """Record cleanup for the turn created by stream_text."""
         calls.append(("unregister", turn_id))
 
     client.register_turn_notifications = fake_register  # type: ignore[method-assign]
@@ -510,10 +519,13 @@ def test_stream_text_registers_and_consumes_turn_notifications() -> None:
 
 
 def test_async_thread_run_accepts_string_input_and_returns_run_result() -> None:
+    """Async Thread.run should normalize string input and collect routed results."""
     async def scenario() -> None:
+        """Feed item, usage, and completion events through the async turn stream."""
         codex = AsyncCodex()
 
         async def fake_ensure_initialized() -> None:
+            """Avoid starting a real app-server process for this run test."""
             return None
 
         item_notification = _item_completed_notification(text="Hello async.")
@@ -528,12 +540,14 @@ def test_async_thread_run_accepts_string_input_and_returns_run_result() -> None:
         seen: dict[str, object] = {}
 
         async def fake_turn_start(thread_id: str, wire_input: object, *, params=None):  # noqa: ANN001,ANN202
+            """Capture normalized input and return a synthetic turn id."""
             seen["thread_id"] = thread_id
             seen["wire_input"] = wire_input
             seen["params"] = params
             return SimpleNamespace(turn=SimpleNamespace(id="turn-1"))
 
         async def fake_next_notification(_turn_id: str) -> Notification:
+            """Return the next queued notification for the synthetic turn."""
             return notifications.popleft()
 
         codex._ensure_initialized = fake_ensure_initialized  # type: ignore[method-assign]
@@ -556,10 +570,13 @@ def test_async_thread_run_accepts_string_input_and_returns_run_result() -> None:
 def test_async_thread_run_uses_last_completed_assistant_message_as_final_response() -> (
     None
 ):
+    """Async run should use the last final assistant message as the response text."""
     async def scenario() -> None:
+        """Feed two completed agent messages through the async per-turn stream."""
         codex = AsyncCodex()
 
         async def fake_ensure_initialized() -> None:
+            """Avoid starting a real app-server process for this run test."""
             return None
 
         first_item_notification = _item_completed_notification(
@@ -577,9 +594,11 @@ def test_async_thread_run_uses_last_completed_assistant_message_as_final_respons
         )
 
         async def fake_turn_start(thread_id: str, wire_input: object, *, params=None):  # noqa: ANN001,ANN202,ARG001
+            """Return a synthetic turn id after AsyncThread.run builds input."""
             return SimpleNamespace(turn=SimpleNamespace(id="turn-1"))
 
         async def fake_next_notification(_turn_id: str) -> Notification:
+            """Return the next queued notification for that synthetic turn."""
             return notifications.popleft()
 
         codex._ensure_initialized = fake_ensure_initialized  # type: ignore[method-assign]
@@ -598,10 +617,13 @@ def test_async_thread_run_uses_last_completed_assistant_message_as_final_respons
 
 
 def test_async_thread_run_returns_none_when_only_commentary_messages_complete() -> None:
+    """Async Thread.run should ignore commentary-only messages for final text."""
     async def scenario() -> None:
+        """Feed a commentary item and completion through the async turn stream."""
         codex = AsyncCodex()
 
         async def fake_ensure_initialized() -> None:
+            """Avoid starting a real app-server process for this run test."""
             return None
 
         commentary_notification = _item_completed_notification(
@@ -616,9 +638,11 @@ def test_async_thread_run_returns_none_when_only_commentary_messages_complete()
         )
 
         async def fake_turn_start(thread_id: str, wire_input: object, *, params=None):  # noqa: ANN001,ANN202,ARG001
+            """Return a synthetic turn id for commentary-only output."""
             return SimpleNamespace(turn=SimpleNamespace(id="turn-1"))
 
         async def fake_next_notification(_turn_id: str) -> Notification:
+            """Return the next queued commentary/completion notification."""
             return notifications.popleft()
 
         codex._ensure_initialized = fake_ensure_initialized  # type: ignore[method-assign]