python-sdk: align pinned runtime bootstrap and drop sample image (2026-03-16)

- bump the repo-managed runtime bootstrap to rust-v0.116.0-alpha.1 so example and integration paths match the current SDK thread/start schema - make release artifact download more robust by retrying metadata lookups without stale auth and preferring deterministic release asset URLs - refresh generated Python artifacts and signature expectations so artifact drift tests pass on the current branch shape - replace the checked-in local image asset with a generated temporary PNG used by the examples and notebook local-image flow - add lightweight tests for pinned runtime doc drift and invalid-auth fallback in runtime metadata resolution Co-authored-by: Codex <noreply@openai.com>
2026-04-27 18:01:04 +03:00 · 2026-03-16 16:29:52 -07:00
parent cd84a3fd01
commit bb551e0342
11 changed files with 242 additions and 82 deletions
--- a/sdk/python/_runtime_setup.py
+++ b/sdk/python/_runtime_setup.py
@@ -16,7 +16,7 @@ import zipfile
 from pathlib import Path

 PACKAGE_NAME = "codex-cli-bin"
-PINNED_RUNTIME_VERSION = "0.115.0-alpha.11"
+PINNED_RUNTIME_VERSION = "0.116.0-alpha.1"
 REPO_SLUG = "openai/codex"


@@ -122,22 +122,53 @@ def _installed_runtime_version(python_executable: str | Path) -> str | None:

 def _release_metadata(version: str) -> dict[str, object]:
    url = f"https://api.github.com/repos/{REPO_SLUG}/releases/tags/rust-v{version}"
-    request = urllib.request.Request(
-        url,
-        headers=_github_api_headers("application/vnd.github+json"),
-    )
-    try:
-        with urllib.request.urlopen(request) as response:
-            return json.load(response)
-    except urllib.error.HTTPError as exc:
-        raise RuntimeSetupError(
-            f"Failed to resolve release metadata for rust-v{version} from {REPO_SLUG}: "
-            f"{exc.code} {exc.reason}"
-        ) from exc
+    token = _github_token()
+    attempts = [True, False] if token is not None else [False]
+    last_error: urllib.error.HTTPError | None = None
+
+    for include_auth in attempts:
+        headers = {
+            "Accept": "application/vnd.github+json",
+            "User-Agent": "codex-python-runtime-setup",
+        }
+        if include_auth and token is not None:
+            headers["Authorization"] = f"Bearer {token}"
+
+        request = urllib.request.Request(url, headers=headers)
+        try:
+            with urllib.request.urlopen(request) as response:
+                return json.load(response)
+        except urllib.error.HTTPError as exc:
+            last_error = exc
+            if include_auth and exc.code == 401:
+                continue
+            break
+
+    assert last_error is not None
+    raise RuntimeSetupError(
+        f"Failed to resolve release metadata for rust-v{version} from {REPO_SLUG}: "
+        f"{last_error.code} {last_error.reason}"
+    ) from last_error


 def _download_release_archive(version: str, temp_root: Path) -> Path:
    asset_name = platform_asset_name()
+    archive_path = temp_root / asset_name
+
+    browser_download_url = (
+        f"https://github.com/{REPO_SLUG}/releases/download/rust-v{version}/{asset_name}"
+    )
+    request = urllib.request.Request(
+        browser_download_url,
+        headers={"User-Agent": "codex-python-runtime-setup"},
+    )
+    try:
+        with urllib.request.urlopen(request) as response, archive_path.open("wb") as fh:
+            shutil.copyfileobj(response, fh)
+        return archive_path
+    except urllib.error.HTTPError:
+        pass
+
    metadata = _release_metadata(version)
    assets = metadata.get("assets")
    if not isinstance(assets, list):
@@ -155,13 +186,9 @@ def _download_release_archive(version: str, temp_root: Path) -> Path:
            f"Release rust-v{version} does not contain asset {asset_name} for this platform."
        )

-    archive_path = temp_root / asset_name
    api_url = asset.get("url")
-    browser_download_url = asset.get("browser_download_url")
    if not isinstance(api_url, str):
        api_url = None
-    if not isinstance(browser_download_url, str):
-        browser_download_url = None

    if api_url is not None:
        token = _github_token()
@@ -177,18 +204,6 @@ def _download_release_archive(version: str, temp_root: Path) -> Path:
            except urllib.error.HTTPError:
                pass

-    if browser_download_url is not None:
-        request = urllib.request.Request(
-            browser_download_url,
-            headers={"User-Agent": "codex-python-runtime-setup"},
-        )
-        try:
-            with urllib.request.urlopen(request) as response, archive_path.open("wb") as fh:
-                shutil.copyfileobj(response, fh)
-            return archive_path
-        except urllib.error.HTTPError:
-            pass
-
    if shutil.which("gh") is None:
        raise RuntimeSetupError(
            f"Unable to download {asset_name} for rust-v{version}. "
--- a/sdk/python/examples/08_local_image_and_text/async.py
+++ b/sdk/python/examples/08_local_image_and_text/async.py
@@ -10,6 +10,7 @@ from _bootstrap import (
    ensure_local_sdk_src,
    find_turn_by_id,
    runtime_config,
+    temporary_sample_image_path,
 )

 ensure_local_sdk_src()
@@ -18,27 +19,24 @@ import asyncio

 from codex_app_server import AsyncCodex, LocalImageInput, TextInput

-IMAGE_PATH = Path(__file__).resolve().parents[1] / "assets" / "sample_scene.png"
-if not IMAGE_PATH.exists():
-    raise FileNotFoundError(f"Missing bundled image: {IMAGE_PATH}")
-

 async def main() -> None:
-    async with AsyncCodex(config=runtime_config()) as codex:
-        thread = await codex.thread_start(model="gpt-5.4", config={"model_reasoning_effort": "high"})
+    with temporary_sample_image_path() as image_path:
+        async with AsyncCodex(config=runtime_config()) as codex:
+            thread = await codex.thread_start(model="gpt-5.4", config={"model_reasoning_effort": "high"})

-        turn = await thread.turn(
-            [
-                TextInput("Read this local image and summarize what you see in 2 bullets."),
-                LocalImageInput(str(IMAGE_PATH.resolve())),
-            ]
-        )
-        result = await turn.run()
-        persisted = await thread.read(include_turns=True)
-        persisted_turn = find_turn_by_id(persisted.thread.turns, result.id)
+            turn = await thread.turn(
+                [
+                    TextInput("Read this generated local image and summarize the colors/layout in 2 bullets."),
+                    LocalImageInput(str(image_path.resolve())),
+                ]
+            )
+            result = await turn.run()
+            persisted = await thread.read(include_turns=True)
+            persisted_turn = find_turn_by_id(persisted.thread.turns, result.id)

-        print("Status:", result.status)
-        print(assistant_text_from_turn(persisted_turn))
+            print("Status:", result.status)
+            print(assistant_text_from_turn(persisted_turn))


 if __name__ == "__main__":
--- a/sdk/python/examples/08_local_image_and_text/sync.py
+++ b/sdk/python/examples/08_local_image_and_text/sync.py
@@ -10,27 +10,25 @@ from _bootstrap import (
    ensure_local_sdk_src,
    find_turn_by_id,
    runtime_config,
+    temporary_sample_image_path,
 )

 ensure_local_sdk_src()

 from codex_app_server import Codex, LocalImageInput, TextInput

-IMAGE_PATH = Path(__file__).resolve().parents[1] / "assets" / "sample_scene.png"
-if not IMAGE_PATH.exists():
-    raise FileNotFoundError(f"Missing bundled image: {IMAGE_PATH}")
+with temporary_sample_image_path() as image_path:
+    with Codex(config=runtime_config()) as codex:
+        thread = codex.thread_start(model="gpt-5.4", config={"model_reasoning_effort": "high"})

-with Codex(config=runtime_config()) as codex:
-    thread = codex.thread_start(model="gpt-5.4", config={"model_reasoning_effort": "high"})
+        result = thread.turn(
+            [
+                TextInput("Read this generated local image and summarize the colors/layout in 2 bullets."),
+                LocalImageInput(str(image_path.resolve())),
+            ]
+        ).run()
+        persisted = thread.read(include_turns=True)
+        persisted_turn = find_turn_by_id(persisted.thread.turns, result.id)

-    result = thread.turn(
-        [
-            TextInput("Read this local image and summarize what you see in 2 bullets."),
-            LocalImageInput(str(IMAGE_PATH.resolve())),
-        ]
-    ).run()
-    persisted = thread.read(include_turns=True)
-    persisted_turn = find_turn_by_id(persisted.thread.turns, result.id)
-
-    print("Status:", result.status)
-    print(assistant_text_from_turn(persisted_turn))
+        print("Status:", result.status)
+        print(assistant_text_from_turn(persisted_turn))
--- a/sdk/python/examples/README.md
+++ b/sdk/python/examples/README.md
@@ -30,7 +30,7 @@ will download the matching GitHub release artifact, stage a temporary local
 `codex-cli-bin` package, install it into your active interpreter, and clean up
 the temporary files afterward.

-Current pinned runtime version: `0.115.0-alpha.11`
+Current pinned runtime version: `0.116.0-alpha.1`

 ## Run examples

@@ -70,7 +70,7 @@ python examples/01_quickstart_constructor/async.py
 - `07_image_and_text/`
  - remote image URL + text multimodal turn
 - `08_local_image_and_text/`
-  - local image + text multimodal turn using bundled sample image
+  - local image + text multimodal turn using a generated temporary sample image
 - `09_async_parity/`
  - parity-style sync flow (see async parity in other examples)
 - `10_error_handling_and_retry/`
--- a/sdk/python/examples/_bootstrap.py
+++ b/sdk/python/examples/_bootstrap.py
@@ -1,10 +1,13 @@
 from __future__ import annotations

+import contextlib
 import importlib.util
 import os
 import sys
+import tempfile
+import zlib
 from pathlib import Path
-from typing import Iterable
+from typing import Iterable, Iterator

 _SDK_PYTHON_DIR = Path(__file__).resolve().parents[1]
 _SDK_PYTHON_STR = str(_SDK_PYTHON_DIR)
@@ -52,6 +55,55 @@ def runtime_config():
    return AppServerConfig()


+def _png_chunk(chunk_type: bytes, data: bytes) -> bytes:
+    import struct
+
+    payload = chunk_type + data
+    checksum = zlib.crc32(payload) & 0xFFFFFFFF
+    return struct.pack(">I", len(data)) + payload + struct.pack(">I", checksum)
+
+
+def _generated_sample_png_bytes() -> bytes:
+    import struct
+
+    width = 96
+    height = 96
+    top_left = (120, 180, 255)
+    top_right = (255, 220, 90)
+    bottom_left = (90, 180, 95)
+    bottom_right = (180, 85, 85)
+
+    rows = bytearray()
+    for y in range(height):
+        rows.append(0)
+        for x in range(width):
+            if y < height // 2 and x < width // 2:
+                color = top_left
+            elif y < height // 2:
+                color = top_right
+            elif x < width // 2:
+                color = bottom_left
+            else:
+                color = bottom_right
+            rows.extend(color)
+
+    header = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)
+    return (
+        b"\x89PNG\r\n\x1a\n"
+        + _png_chunk(b"IHDR", header)
+        + _png_chunk(b"IDAT", zlib.compress(bytes(rows)))
+        + _png_chunk(b"IEND", b"")
+    )
+
+
+@contextlib.contextmanager
+def temporary_sample_image_path() -> Iterator[Path]:
+    with tempfile.TemporaryDirectory(prefix="codex-python-example-image-") as temp_root:
+        image_path = Path(temp_root) / "generated_sample.png"
+        image_path.write_bytes(_generated_sample_png_bytes())
+        yield image_path
+
+
 def server_label(metadata: object) -> str:
    server = getattr(metadata, "serverInfo", None)
    server_name = ((getattr(server, "name", None) or "") if server is not None else "").strip()
--- a/sdk/python/notebooks/sdk_walkthrough.ipynb
+++ b/sdk/python/notebooks/sdk_walkthrough.ipynb
@@ -400,22 +400,19 @@
   "metadata": {},
   "outputs": [],
   "source": [
-    "# Cell 7: multimodal with local image (bundled asset)\n",
-    "local_image_path = repo_python_dir / 'examples' / 'assets' / 'sample_scene.png'\n",
-    "if not local_image_path.exists():\n",
-    "    raise FileNotFoundError(f'Missing bundled image: {local_image_path}')\n",
+    "# Cell 7: multimodal with local image (generated temporary file)\n",
+    "with temporary_sample_image_path() as local_image_path:\n",
+    "    with Codex() as codex:\n",
+    "        thread = codex.thread_start(model='gpt-5.4', config={'model_reasoning_effort': 'high'})\n",
+    "        result = thread.turn([\n",
+    "            TextInput('Describe the colors and layout in this generated local image in 2 bullets.'),\n",
+    "            LocalImageInput(str(local_image_path.resolve())),\n",
+    "        ]).run()\n",
+    "        persisted = thread.read(include_turns=True)\n",
+    "        persisted_turn = find_turn_by_id(persisted.thread.turns, result.id)\n",
    "\n",
-    "with Codex() as codex:\n",
-    "    thread = codex.thread_start(model='gpt-5.4', config={'model_reasoning_effort': 'high'})\n",
-    "    result = thread.turn([\n",
-    "        TextInput('Describe this local image in 2 bullets.'),\n",
-    "        LocalImageInput(str(local_image_path.resolve())),\n",
-    "    ]).run()\n",
-    "    persisted = thread.read(include_turns=True)\n",
-    "    persisted_turn = find_turn_by_id(persisted.thread.turns, result.id)\n",
-    "\n",
-    "    print('status:', result.status)\n",
-    "    print(assistant_text_from_turn(persisted_turn))\n"
+    "        print('status:', result.status)\n",
+    "        print(assistant_text_from_turn(persisted_turn))\n"
   ]
  },
  {
--- a/sdk/python/src/codex_app_server/generated/v2_all.py
+++ b/sdk/python/src/codex_app_server/generated/v2_all.py
@@ -339,6 +339,7 @@ class CodexErrorInfo(
 class CollabAgentStatus(Enum):
    pending_init = "pendingInit"
    running = "running"
+    interrupted = "interrupted"
    completed = "completed"
    errored = "errored"
    shutdown = "shutdown"
@@ -746,6 +747,7 @@ class DynamicToolSpec(BaseModel):
    model_config = ConfigDict(
        populate_by_name=True,
    )
+    defer_loading: Annotated[bool | None, Field(alias="deferLoading")] = None
    description: str
    input_schema: Annotated[Any, Field(alias="inputSchema")]
    name: str
@@ -1657,7 +1659,13 @@ class PluginInterface(BaseModel):
    capabilities: list[str]
    category: str | None = None
    composer_icon: Annotated[AbsolutePathBuf | None, Field(alias="composerIcon")] = None
-    default_prompt: Annotated[str | None, Field(alias="defaultPrompt")] = None
+    default_prompt: Annotated[
+        list[str] | None,
+        Field(
+            alias="defaultPrompt",
+            description="Starter prompts for the plugin. Capped at 3 entries with a maximum of 128 characters per entry.",
+        ),
+    ] = None
    developer_name: Annotated[str | None, Field(alias="developerName")] = None
    display_name: Annotated[str | None, Field(alias="displayName")] = None
    logo: AbsolutePathBuf | None = None
--- a/sdk/python/src/codex_app_server/public_api.py
+++ b/sdk/python/src/codex_app_server/public_api.py
@@ -168,6 +168,7 @@ class Codex:
        self,
        *,
        approval_policy: AskForApproval | None = None,
+        approvals_reviewer: ApprovalsReviewer | None = None,
        base_instructions: str | None = None,
        config: JsonObject | None = None,
        cwd: str | None = None,
@@ -182,6 +183,7 @@ class Codex:
    ) -> Thread:
        params = ThreadStartParams(
            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
            base_instructions=base_instructions,
            config=config,
            cwd=cwd,
@@ -226,6 +228,7 @@ class Codex:
        thread_id: str,
        *,
        approval_policy: AskForApproval | None = None,
+        approvals_reviewer: ApprovalsReviewer | None = None,
        base_instructions: str | None = None,
        config: JsonObject | None = None,
        cwd: str | None = None,
@@ -239,6 +242,7 @@ class Codex:
        params = ThreadResumeParams(
            thread_id=thread_id,
            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
            base_instructions=base_instructions,
            config=config,
            cwd=cwd,
@@ -257,6 +261,7 @@ class Codex:
        thread_id: str,
        *,
        approval_policy: AskForApproval | None = None,
+        approvals_reviewer: ApprovalsReviewer | None = None,
        base_instructions: str | None = None,
        config: JsonObject | None = None,
        cwd: str | None = None,
@@ -270,6 +275,7 @@ class Codex:
        params = ThreadForkParams(
            thread_id=thread_id,
            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
            base_instructions=base_instructions,
            config=config,
            cwd=cwd,
@@ -352,6 +358,7 @@ class AsyncCodex:
        self,
        *,
        approval_policy: AskForApproval | None = None,
+        approvals_reviewer: ApprovalsReviewer | None = None,
        base_instructions: str | None = None,
        config: JsonObject | None = None,
        cwd: str | None = None,
@@ -367,6 +374,7 @@ class AsyncCodex:
        await self._ensure_initialized()
        params = ThreadStartParams(
            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
            base_instructions=base_instructions,
            config=config,
            cwd=cwd,
@@ -412,6 +420,7 @@ class AsyncCodex:
        thread_id: str,
        *,
        approval_policy: AskForApproval | None = None,
+        approvals_reviewer: ApprovalsReviewer | None = None,
        base_instructions: str | None = None,
        config: JsonObject | None = None,
        cwd: str | None = None,
@@ -426,6 +435,7 @@ class AsyncCodex:
        params = ThreadResumeParams(
            thread_id=thread_id,
            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
            base_instructions=base_instructions,
            config=config,
            cwd=cwd,
@@ -444,6 +454,7 @@ class AsyncCodex:
        thread_id: str,
        *,
        approval_policy: AskForApproval | None = None,
+        approvals_reviewer: ApprovalsReviewer | None = None,
        base_instructions: str | None = None,
        config: JsonObject | None = None,
        cwd: str | None = None,
@@ -458,6 +469,7 @@ class AsyncCodex:
        params = ThreadForkParams(
            thread_id=thread_id,
            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
            base_instructions=base_instructions,
            config=config,
            cwd=cwd,
@@ -497,6 +509,7 @@ class Thread:
        input: Input,
        *,
        approval_policy: AskForApproval | None = None,
+        approvals_reviewer: ApprovalsReviewer | None = None,
        cwd: str | None = None,
        effort: ReasoningEffort | None = None,
        model: str | None = None,
@@ -511,6 +524,7 @@ class Thread:
            thread_id=self.id,
            input=wire_input,
            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
            cwd=cwd,
            effort=effort,
            model=model,
@@ -545,6 +559,7 @@ class AsyncThread:
        input: Input,
        *,
        approval_policy: AskForApproval | None = None,
+        approvals_reviewer: ApprovalsReviewer | None = None,
        cwd: str | None = None,
        effort: ReasoningEffort | None = None,
        model: str | None = None,
@@ -560,6 +575,7 @@ class AsyncThread:
            thread_id=self.id,
            input=wire_input,
            approval_policy=approval_policy,
+            approvals_reviewer=approvals_reviewer,
            cwd=cwd,
            effort=effort,
            model=model,
--- a/sdk/python/tests/test_artifact_workflow_and_binaries.py
+++ b/sdk/python/tests/test_artifact_workflow_and_binaries.py
@@ -2,9 +2,11 @@ from __future__ import annotations

 import ast
 import importlib.util
+import io
 import json
 import sys
 import tomllib
+import urllib.error
 from pathlib import Path

 import pytest
@@ -23,6 +25,17 @@ def _load_update_script_module():
    return module


+def _load_runtime_setup_module():
+    runtime_setup_path = ROOT / "_runtime_setup.py"
+    spec = importlib.util.spec_from_file_location("_runtime_setup", runtime_setup_path)
+    if spec is None or spec.loader is None:
+        raise AssertionError(f"Failed to load runtime setup module: {runtime_setup_path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
 def test_generation_has_single_maintenance_entrypoint_script() -> None:
    scripts = sorted(p.name for p in (ROOT / "scripts").glob("*.py"))
    assert scripts == ["update_sdk_artifacts.py"]
@@ -146,6 +159,39 @@ def test_runtime_package_template_has_no_checked_in_binaries() -> None:
    ) == ["__init__.py"]


+def test_examples_readme_matches_pinned_runtime_version() -> None:
+    runtime_setup = _load_runtime_setup_module()
+    readme = (ROOT / "examples" / "README.md").read_text()
+    assert (
+        f"Current pinned runtime version: `{runtime_setup.pinned_runtime_version()}`"
+        in readme
+    )
+
+
+def test_release_metadata_retries_without_invalid_auth(monkeypatch: pytest.MonkeyPatch) -> None:
+    runtime_setup = _load_runtime_setup_module()
+    authorizations: list[str | None] = []
+
+    def fake_urlopen(request):
+        authorization = request.headers.get("Authorization")
+        authorizations.append(authorization)
+        if authorization is not None:
+            raise urllib.error.HTTPError(
+                request.full_url,
+                401,
+                "Unauthorized",
+                hdrs=None,
+                fp=None,
+            )
+        return io.StringIO('{"assets": []}')
+
+    monkeypatch.setenv("GH_TOKEN", "invalid-token")
+    monkeypatch.setattr(runtime_setup.urllib.request, "urlopen", fake_urlopen)
+
+    assert runtime_setup._release_metadata("1.2.3") == {"assets": []}
+    assert authorizations == ["Bearer invalid-token", None]
+
+
 def test_runtime_package_is_wheel_only_and_builds_platform_specific_wheels() -> None:
    pyproject = tomllib.loads(
        (ROOT.parent / "python-runtime" / "pyproject.toml").read_text()
--- a/sdk/python/tests/test_public_api_signatures.py
+++ b/sdk/python/tests/test_public_api_signatures.py
@@ -40,6 +40,7 @@ def test_generated_public_signatures_are_snake_case_and_typed() -> None:
    expected = {
        Codex.thread_start: [
            "approval_policy",
+            "approvals_reviewer",
            "base_instructions",
            "config",
            "cwd",
@@ -64,6 +65,7 @@ def test_generated_public_signatures_are_snake_case_and_typed() -> None:
        ],
        Codex.thread_resume: [
            "approval_policy",
+            "approvals_reviewer",
            "base_instructions",
            "config",
            "cwd",
@@ -76,6 +78,7 @@ def test_generated_public_signatures_are_snake_case_and_typed() -> None:
        ],
        Codex.thread_fork: [
            "approval_policy",
+            "approvals_reviewer",
            "base_instructions",
            "config",
            "cwd",
@@ -88,6 +91,7 @@ def test_generated_public_signatures_are_snake_case_and_typed() -> None:
        ],
        Thread.turn: [
            "approval_policy",
+            "approvals_reviewer",
            "cwd",
            "effort",
            "model",
@@ -99,6 +103,7 @@ def test_generated_public_signatures_are_snake_case_and_typed() -> None:
        ],
        AsyncCodex.thread_start: [
            "approval_policy",
+            "approvals_reviewer",
            "base_instructions",
            "config",
            "cwd",
@@ -123,6 +128,7 @@ def test_generated_public_signatures_are_snake_case_and_typed() -> None:
        ],
        AsyncCodex.thread_resume: [
            "approval_policy",
+            "approvals_reviewer",
            "base_instructions",
            "config",
            "cwd",
@@ -135,6 +141,7 @@ def test_generated_public_signatures_are_snake_case_and_typed() -> None:
        ],
        AsyncCodex.thread_fork: [
            "approval_policy",
+            "approvals_reviewer",
            "base_instructions",
            "config",
            "cwd",
@@ -147,6 +154,7 @@ def test_generated_public_signatures_are_snake_case_and_typed() -> None:
        ],
        AsyncThread.turn: [
            "approval_policy",
+            "approvals_reviewer",
            "cwd",
            "effort",
            "model",
--- a/sdk/python/tests/test_real_app_server_integration.py
+++ b/sdk/python/tests/test_real_app_server_integration.py
@@ -133,6 +133,24 @@ def _run_python(
    )


+def _runtime_compatibility_hint(
+    runtime_env: PreparedRuntimeEnv,
+    *,
+    stdout: str,
+    stderr: str,
+) -> str:
+    combined = f"{stdout}\n{stderr}"
+    if "ThreadStartResponse" in combined and "approvalsReviewer" in combined:
+        return (
+            "\nCompatibility hint:\n"
+            f"Pinned runtime {runtime_env.runtime_version} returned a thread/start payload "
+            "that is older than the current SDK schema and is missing "
+            "`approvalsReviewer`. Bump `sdk/python/_runtime_setup.py` to a matching "
+            "released runtime version.\n"
+        )
+    return ""
+
+
 def _run_json_python(
    runtime_env: PreparedRuntimeEnv,
    source: str,
@@ -142,7 +160,10 @@ def _run_json_python(
 ) -> dict[str, object]:
    result = _run_python(runtime_env, source, cwd=cwd, timeout_s=timeout_s)
    assert result.returncode == 0, (
-        f"Python snippet failed.\nSTDOUT:\n{result.stdout}\nSTDERR:\n{result.stderr}"
+        "Python snippet failed.\n"
+        f"STDOUT:\n{result.stdout}\n"
+        f"STDERR:\n{result.stderr}"
+        f"{_runtime_compatibility_hint(runtime_env, stdout=result.stdout, stderr=result.stderr)}"
    )
    return json.loads(result.stdout)

@@ -389,6 +410,7 @@ def test_real_examples_run_and_assert(
        f"Example failed: {folder}/{script}\n"
        f"STDOUT:\n{result.stdout}\n"
        f"STDERR:\n{result.stderr}"
+        f"{_runtime_compatibility_hint(runtime_env, stdout=result.stdout, stderr=result.stderr)}"
    )

    out = result.stdout