codex-sdk-python 0.98.0__tar.gz → 0.101.0__tar.gz

{codex_sdk_python-0.98.0 → codex_sdk_python-0.101.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: codex-sdk-python
-Version: 0.98.0
+Version: 0.101.0
 Summary: Python SDK for the Codex CLI agent with async threads, streaming events, and structured outputs
 Keywords: codex,sdk,python,api,cli,agent,async,streaming
 Author: Vectorfy Co
@@ -18,7 +18,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Software Development :: Build Tools
-Requires-Dist: logfire-api>=4 ; extra == 'logfire'
+Requires-Dist: logfire ; extra == 'logfire'
 Requires-Dist: pydantic>=2 ; extra == 'pydantic'
 Requires-Dist: pydantic-ai ; python_full_version >= '3.10' and extra == 'pydantic-ai'
 Maintainer: Vectorfy Co
@@ -44,7 +44,7 @@ Embed the Codex agent in Python workflows. This SDK wraps the bundled `codex` CL
       <td><strong>Lifecycle</strong></td>
       <td>
         <a href="#ci-cd"><img src="https://img.shields.io/badge/CI%2FCD-Active-16a34a?style=flat&logo=githubactions&logoColor=white" alt="CI/CD badge" /></a>
-        <img src="https://img.shields.io/badge/Release-0.98.0-6b7280?style=flat&logo=pypi&logoColor=white" alt="Release badge" />
+        <img src="https://img.shields.io/badge/Release-0.101.0-6b7280?style=flat&logo=pypi&logoColor=white" alt="Release 0.101.0 badge" />
         <a href="#license"><img src="https://img.shields.io/badge/License-Apache--2.0-0f766e?style=flat&logo=apache&logoColor=white" alt="License badge" /></a>
       </td>
     </tr>
@@ -410,8 +410,9 @@ Supported target triples:
 - macOS: `x86_64-apple-darwin`, `aarch64-apple-darwin`
 - Windows: `x86_64-pc-windows-msvc`, `aarch64-pc-windows-msvc`
 
-If you are working from source and the vendor directory is missing, run `python scripts/setup_binary.py`
-or follow `SETUP.md` to download the official npm package and copy the `vendor/` directory.
+If you are working from source and the vendor directory is missing, run
+`python scripts/setup_binary.py` to fetch and assemble the platform `@openai/codex`
+artifacts into `src/codex_sdk/vendor/`.
 
 <a id="auth"></a>
 ## ![Auth](https://img.shields.io/badge/Auth%20%26%20Credentials-Access-2563eb?style=for-the-badge&logo=gnubash&logoColor=white)

{codex_sdk_python-0.98.0 → codex_sdk_python-0.101.0}/README.md

@@ -8,7 +8,7 @@ Embed the Codex agent in Python workflows. This SDK wraps the bundled `codex` CL
       <td><strong>Lifecycle</strong></td>
       <td>
         <a href="#ci-cd"><img src="https://img.shields.io/badge/CI%2FCD-Active-16a34a?style=flat&logo=githubactions&logoColor=white" alt="CI/CD badge" /></a>
-        <img src="https://img.shields.io/badge/Release-0.98.0-6b7280?style=flat&logo=pypi&logoColor=white" alt="Release badge" />
+        <img src="https://img.shields.io/badge/Release-0.101.0-6b7280?style=flat&logo=pypi&logoColor=white" alt="Release 0.101.0 badge" />
         <a href="#license"><img src="https://img.shields.io/badge/License-Apache--2.0-0f766e?style=flat&logo=apache&logoColor=white" alt="License badge" /></a>
       </td>
     </tr>
@@ -374,8 +374,9 @@ Supported target triples:
 - macOS: `x86_64-apple-darwin`, `aarch64-apple-darwin`
 - Windows: `x86_64-pc-windows-msvc`, `aarch64-pc-windows-msvc`
 
-If you are working from source and the vendor directory is missing, run `python scripts/setup_binary.py`
-or follow `SETUP.md` to download the official npm package and copy the `vendor/` directory.
+If you are working from source and the vendor directory is missing, run
+`python scripts/setup_binary.py` to fetch and assemble the platform `@openai/codex`
+artifacts into `src/codex_sdk/vendor/`.
 
 <a id="auth"></a>
 ## ![Auth](https://img.shields.io/badge/Auth%20%26%20Credentials-Access-2563eb?style=for-the-badge&logo=gnubash&logoColor=white)

{codex_sdk_python-0.98.0 → codex_sdk_python-0.101.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "codex-sdk-python"
-version = "0.98.0"
+version = "0.101.0"
 description = "Python SDK for the Codex CLI agent with async threads, streaming events, and structured outputs"
 readme = "README.md"
 license = {text = "Apache-2.0"}
@@ -40,10 +40,7 @@ pydantic-ai = [
     "pydantic-ai; python_version >= '3.10'",
 ]
 logfire = [
-    # `pydantic-ai` imports the `logfire` module, which is provided by the
-    # `logfire-api` distribution. Avoid the unrelated legacy `logfire` package
-    # on PyPI which can shadow it and break imports.
-    "logfire-api>=4",
+    "logfire",
 ]
 
 [dependency-groups]

{codex_sdk_python-0.98.0 → codex_sdk_python-0.101.0}/src/codex_sdk/__init__.py

@@ -41,11 +41,6 @@ from .exceptions import (
 from .hooks import ThreadHooks
 from .items import (
     AgentMessageItem,
-    CollabAgentState,
-    CollabAgentStatus,
-    CollabTool,
-    CollabToolCallItem,
-    CollabToolCallStatus,
     CommandExecutionItem,
     CommandExecutionStatus,
     ErrorItem,
@@ -82,7 +77,7 @@ from .thread import (
     Turn,
 )
 
-__version__ = "0.98.0"
+__version__ = "0.101.0"
 
 __all__ = [
     "AbortController",
@@ -122,7 +117,6 @@ __all__ = [
     "CommandExecutionItem",
     "FileChangeItem",
     "McpToolCallItem",
-    "CollabToolCallItem",
     "McpToolCallItemResult",
     "McpToolCallItemError",
     "WebSearchItem",
@@ -132,10 +126,6 @@ __all__ = [
     "PatchChangeKind",
     "PatchApplyStatus",
     "McpToolCallStatus",
-    "CollabToolCallStatus",
-    "CollabTool",
-    "CollabAgentStatus",
-    "CollabAgentState",
     "TodoItem",
     "CodexOptions",
     "ThreadOptions",

{codex_sdk_python-0.98.0 → codex_sdk_python-0.101.0}/src/codex_sdk/app_server.py

@@ -636,14 +636,41 @@ class AppServerClient:
         """
         return await self._request_dict("thread/unarchive", {"threadId": thread_id})
 
-    async def thread_compact_start(self, thread_id: str) -> Dict[str, Any]:
+    async def thread_compact_start(
+        self, thread_id: str, *, instructions: Optional[str] = None
+    ) -> Dict[str, Any]:
         """
         Starts a compaction operation for the specified thread on the app-server.
 
+        Args:
+            thread_id: Identifier of the thread to compact.
+            instructions: Optional server hint for compaction behavior.
+
         Returns:
             dict: The app-server's result payload for the compaction start request.
         """
-        return await self._request_dict("thread/compact/start", {"threadId": thread_id})
+        payload: Dict[str, Any] = {"thread_id": thread_id}
+        if instructions is not None:
+            payload["instructions"] = instructions
+        return await self._request_dict("thread/compact/start", _coerce_keys(payload))
+
+    async def thread_background_terminals_clean(
+        self, thread_id: str, *, terminal_ids: Sequence[str]
+    ) -> Dict[str, Any]:
+        """
+        Clean up background terminal sessions for a thread.
+
+        Args:
+            thread_id: Identifier of the thread.
+            terminal_ids: Terminal ids to clean.
+
+        Returns:
+            App-server response payload.
+        """
+        payload = {"thread_id": thread_id, "terminal_ids": list(terminal_ids)}
+        return await self._request_dict(
+            "thread/backgroundTerminals/clean", _coerce_keys(payload)
+        )
 
     async def thread_rollback(
         self, thread_id: str, *, num_turns: int
@@ -741,43 +768,74 @@ class AppServerClient:
             payload["cwds"] = [str(path) for path in cwds]
         return await self._request_dict("skills/list", _coerce_keys(payload))
 
-    async def skills_remote_read(self) -> Dict[str, Any]:
+    async def skills_remote_read(
+        self, *, params: Optional[Mapping[str, Any]] = None
+    ) -> Dict[str, Any]:
         """
         Read remote skills metadata from the app server.
 
+        Args:
+            params: Optional request payload.
+
         Returns:
             result (Dict[str, Any]): The app-server response payload for the `skills/remote/read` request.
         """
-        return await self._request_dict("skills/remote/read", {})
+        payload = _coerce_keys(dict(params)) if params is not None else {}
+        return await self._request_dict("skills/remote/read", payload)
 
     async def skills_remote_write(
-        self, *, hazelnut_id: str, is_preload: bool
+        self,
+        *,
+        hazelnut_id: Optional[str] = None,
+        is_preload: Optional[bool] = None,
+        params: Optional[Mapping[str, Any]] = None,
     ) -> Dict[str, Any]:
         """
-        Start a remote skill write operation for a Hazelnut package.
+        Start a remote skill write operation.
 
         Args:
-            hazelnut_id: Identifier of the remote Hazelnut skill to write.
-            is_preload: Whether the skill should be marked as a preload.
+            hazelnut_id: Optional Hazelnut identifier.
+            is_preload: Optional preload flag.
+            params: Optional raw request payload.
 
         Returns:
             Result returned by the app-server for the "skills/remote/write" request.
         """
-        payload = {"hazelnut_id": hazelnut_id, "is_preload": is_preload}
-        return await self._request_dict("skills/remote/write", _coerce_keys(payload))
-
-    async def skills_config_write(self, *, path: str, enabled: bool) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {}
+        if params is not None:
+            payload.update(_coerce_keys(dict(params)))
+        if hazelnut_id is not None:
+            payload["hazelnut_id"] = hazelnut_id
+        if is_preload is not None:
+            payload["is_preload"] = is_preload
+        return await self._request_dict("skills/remote/write", payload)
+
+    async def skills_config_write(
+        self,
+        *,
+        path: Optional[str] = None,
+        enabled: Optional[bool] = None,
+        params: Optional["SkillsConfigWriteRequest"] = None,
+    ) -> Dict[str, Any]:
         """
-        Set the enabled state of a skill configuration at the given path.
+        Set skill configuration state.
 
         Args:
-            path: The configuration path identifying the skill.
-            enabled: True to enable the skill at the path, False to disable it.
+            path: Optional configuration path identifying the skill.
+            enabled: Optional enabled state for the skill.
+            params: Optional typed request payload for evolving protocol fields.
 
         Returns:
             The app-server response as a dictionary.
         """
-        payload = {"path": path, "enabled": enabled}
+        # TODO(app-server-schema): tighten request shape after protocol stabilizes.
+        payload: Dict[str, Any] = {}
+        if params is not None:
+            payload.update(_coerce_keys(dict(params)))
+        if path is not None:
+            payload["path"] = path
+        if enabled is not None:
+            payload["enabled"] = enabled
         return await self._request_dict("skills/config/write", payload)
 
     async def turn_start(
@@ -848,6 +906,23 @@ class AppServerClient:
             "turn/interrupt", {"threadId": thread_id, "turnId": turn_id}
         )
 
+    async def turn_steer(
+        self, thread_id: str, turn_id: str, *, prompt: str
+    ) -> Dict[str, Any]:
+        """
+        Send steering guidance to an in-progress turn.
+
+        Args:
+            thread_id: Identifier of the thread.
+            turn_id: Identifier of the turn.
+            prompt: Steering prompt text.
+
+        Returns:
+            App-server response payload.
+        """
+        payload = {"thread_id": thread_id, "turn_id": turn_id, "prompt": prompt}
+        return await self._request_dict("turn/steer", _coerce_keys(payload))
+
     async def model_list(
         self, *, cursor: Optional[str] = None, limit: Optional[int] = None
     ) -> Dict[str, Any]:
@@ -874,6 +949,26 @@ class AppServerClient:
         """List supported collaboration modes from the app-server."""
         return await self._request_dict("collaborationMode/list", {})
 
+    async def experimental_feature_list(
+        self, *, cursor: Optional[str] = None, limit: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """
+        List experimental features available from the app-server.
+
+        Args:
+            cursor: Optional pagination cursor.
+            limit: Optional page size.
+
+        Returns:
+            App-server response payload.
+        """
+        params: Dict[str, Any] = {}
+        if cursor is not None:
+            params["cursor"] = cursor
+        if limit is not None:
+            params["limit"] = limit
+        return await self._request_dict("experimentalFeature/list", params or None)
+
     async def command_exec(
         self,
         *,
@@ -938,6 +1033,103 @@ class AppServerClient:
             "account/read", {"refreshToken": refresh_token} if refresh_token else None
         )
 
+    async def account_chatgpt_auth_tokens_refresh(
+        self, *, params: Mapping[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Refresh ChatGPT auth tokens via the app-server.
+
+        Args:
+            params: Refresh payload (snake_case or camelCase keys are accepted).
+
+        Returns:
+            App-server response payload.
+        """
+        return await self._request_dict(
+            "account/chatgptAuthTokens/refresh", _coerce_keys(dict(params))
+        )
+
+    async def item_tool_call(self, *, params: "ItemToolCallRequest") -> Dict[str, Any]:
+        """
+        Send an item tool-call payload.
+
+        Args:
+            params: Typed request payload for `item/tool/call`.
+
+        Returns:
+            App-server response payload.
+        """
+        # TODO(app-server-schema): tighten request shape after protocol stabilizes.
+        return await self._request_dict("item/tool/call", _coerce_keys(dict(params)))
+
+    async def item_tool_request_user_input(
+        self, *, params: Mapping[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Send an item request-user-input payload.
+
+        Args:
+            params: Request payload for `item/tool/requestUserInput`.
+
+        Returns:
+            App-server response payload.
+        """
+        return await self._request_dict(
+            "item/tool/requestUserInput", _coerce_keys(dict(params))
+        )
+
+    async def item_command_execution_request_approval(
+        self, *, params: Mapping[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Send an item command-execution approval payload.
+
+        Args:
+            params: Request payload for `item/commandExecution/requestApproval`.
+
+        Returns:
+            App-server response payload.
+        """
+        return await self._request_dict(
+            "item/commandExecution/requestApproval", _coerce_keys(dict(params))
+        )
+
+    async def item_file_change_request_approval(
+        self, *, params: Mapping[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Send an item file-change approval payload.
+
+        Args:
+            params: Request payload for `item/fileChange/requestApproval`.
+
+        Returns:
+            App-server response payload.
+        """
+        return await self._request_dict(
+            "item/fileChange/requestApproval", _coerce_keys(dict(params))
+        )
+
+    async def mock_experimental_method(
+        self, *, params: Optional[Mapping[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Call a mock experimental app-server endpoint.
+
+        Args:
+            params: Optional request payload.
+
+        Returns:
+            App-server response payload.
+        """
+        if not self._options.experimental_api_enabled:
+            raise CodexError(
+                "`mock/experimentalMethod` requires "
+                "AppServerOptions(experimental_api_enabled=True)."
+            )
+        payload = _coerce_keys(dict(params)) if params is not None else {}
+        return await self._request_dict("mock/experimentalMethod", payload)
+
     async def feedback_upload(
         self,
         *,
@@ -1109,6 +1301,26 @@ class AppServerSkillInput(TypedDict):
     path: str
 
 
+class SkillsConfigWriteRequest(TypedDict, total=False):
+    """Typed payload for `skills/config/write` requests."""
+
+    path: str
+    enabled: bool
+    mode: str
+
+
+class ItemToolCallRequest(TypedDict, total=False):
+    """Typed payload for `item/tool/call` requests."""
+
+    name: str
+    tool_name: str
+    toolName: str
+    tool_call_id: str
+    toolCallId: str
+    arguments: Mapping[str, Any]
+    args: Mapping[str, Any]
+
+
 AppServerUserInput = Union[
     AppServerTextInput,
     AppServerImageInput,

{codex_sdk_python-0.98.0 → codex_sdk_python-0.101.0}/src/codex_sdk/integrations/pydantic_ai_model.py

@@ -13,9 +13,10 @@ validation), while Codex behaves like a "backend model" that emits either:
 from __future__ import annotations
 
 import json
+import logging
 from base64 import b64encode
 from contextlib import asynccontextmanager
-from dataclasses import InitVar, asdict, dataclass, field, is_dataclass
+from dataclasses import asdict, dataclass, is_dataclass
 from datetime import datetime, timezone
 from typing import Any, AsyncIterator, Dict, List, Optional, Sequence
 
@@ -37,7 +38,7 @@ try:
     from pydantic_ai.profiles import ModelProfile, ModelProfileSpec
     from pydantic_ai.settings import ModelSettings
     from pydantic_ai.tools import ToolDefinition
-    from pydantic_ai.usage import Usage as PydanticUsage
+    from pydantic_ai.usage import RequestUsage
 except ImportError as exc:  # pragma: no cover
     raise ImportError(
         "pydantic-ai is required for codex_sdk.integrations.pydantic_ai_model; "
@@ -45,6 +46,9 @@ except ImportError as exc:  # pragma: no cover
     ) from exc
 
 
+logger = logging.getLogger(__name__)
+
+
 @dataclass(frozen=True)
 class _ToolCallEnvelope:
     """Parsed tool-call envelope returned by Codex `--output-schema` turns."""
@@ -127,59 +131,49 @@ def _render_tool_definitions(
         The rendered, trimmed multi-line string describing the tools.
     """
     lines: List[str] = []
-    if function_tools:
-        lines.append("Function tools:")
-        for tool in function_tools:
-            lines.append(f"- {tool.name}")
-            if tool.description:
-                lines.append(f"  description: {tool.description}")
-            lines.append(f"  kind: {tool.kind}")
-            lines.append(
-                f"  parameters_json_schema: {_json_dumps(tool.parameters_json_schema)}"
-            )
-            if tool.outer_typed_dict_key:
-                lines.append(f"  outer_typed_dict_key: {tool.outer_typed_dict_key}")
-            if tool.strict is not None:
-                lines.append(f"  strict: {str(tool.strict).lower()}")
-            if getattr(tool, "sequential", False):
-                lines.append("  sequential: true")
-            metadata = getattr(tool, "metadata", None)
-            if metadata is not None:
-                lines.append(f"  metadata: {_json_dumps(metadata)}")
-            timeout = getattr(tool, "timeout", None)
-            if timeout is not None:
-                lines.append(f"  timeout: {timeout}")
-
+    lines.extend(_render_tool_section("Function tools:", function_tools))
     if output_tools:
         if lines:
             lines.append("")
-        lines.append(
-            "Output tools (use ONE of these to finish when text is not allowed):"
-        )
-        for tool in output_tools:
-            lines.append(f"- {tool.name}")
-            if tool.description:
-                lines.append(f"  description: {tool.description}")
-            lines.append(f"  kind: {tool.kind}")
-            lines.append(
-                f"  parameters_json_schema: {_json_dumps(tool.parameters_json_schema)}"
+        lines.extend(
+            _render_tool_section(
+                "Output tools (use ONE of these to finish when text is not allowed):",
+                output_tools,
             )
-            if tool.outer_typed_dict_key:
-                lines.append(f"  outer_typed_dict_key: {tool.outer_typed_dict_key}")
-            if tool.strict is not None:
-                lines.append(f"  strict: {str(tool.strict).lower()}")
-            if getattr(tool, "sequential", False):
-                lines.append("  sequential: true")
-            metadata = getattr(tool, "metadata", None)
-            if metadata is not None:
-                lines.append(f"  metadata: {_json_dumps(metadata)}")
-            timeout = getattr(tool, "timeout", None)
-            if timeout is not None:
-                lines.append(f"  timeout: {timeout}")
+        )
 
     return "\n".join(lines).strip()
 
 
+def _render_tool_section(title: str, tools: Sequence[ToolDefinition]) -> List[str]:
+    """Render one tool section to prompt lines."""
+    if not tools:
+        return []
+
+    lines: List[str] = [title]
+    for tool in tools:
+        lines.append(f"- {tool.name}")
+        if tool.description:
+            lines.append(f"  description: {tool.description}")
+        lines.append(f"  kind: {tool.kind}")
+        lines.append(
+            f"  parameters_json_schema: {_json_dumps(tool.parameters_json_schema)}"
+        )
+        if tool.outer_typed_dict_key:
+            lines.append(f"  outer_typed_dict_key: {tool.outer_typed_dict_key}")
+        if tool.strict is not None:
+            lines.append(f"  strict: {str(tool.strict).lower()}")
+        if getattr(tool, "sequential", False):
+            lines.append("  sequential: true")
+        metadata = getattr(tool, "metadata", None)
+        if metadata is not None:
+            lines.append(f"  metadata: {_json_dumps(metadata)}")
+        timeout = getattr(tool, "timeout", None)
+        if timeout is not None:
+            lines.append(f"  timeout: {timeout}")
+    return lines
+
+
 def _tool_calls_from_envelope(output: Any) -> List[_ToolCallEnvelope]:
     """Extract tool call envelopes from a Codex JSON turn output."""
     if not isinstance(output, dict):
@@ -290,24 +284,37 @@ def _now_utc() -> datetime:
     return datetime.now(timezone.utc)
 
 
-@dataclass
 class CodexStreamedResponse(StreamedResponse):
     """Minimal streamed response wrapper for Codex model provider."""
 
-    _model_name: str
-    _parts: Sequence[Any]
-    _thread_id: str
-    _usage_init: InitVar[PydanticUsage]
-    _timestamp: datetime = field(default_factory=_now_utc, init=False)
-
-    def __post_init__(self, _usage_init: PydanticUsage) -> None:
-        """
-        Save the provided PydanticUsage into the instance's _usage attribute.
+    def __init__(
+        self,
+        *,
+        model_request_parameters: ModelRequestParameters,
+        model_name: str,
+        provider_name: Optional[str],
+        parts: Sequence[Any],
+        thread_id: str,
+        usage: RequestUsage,
+    ) -> None:
+        """Create a streamed response wrapper around precomputed Codex output.
 
         Args:
-            _usage_init: Usage information supplied as the dataclass InitVar.
+            model_request_parameters: The request parameters used for the call.
+            model_name: The model identifier reported to PydanticAI.
+            provider_name: Optional provider/system identifier (e.g. "openai").
+            parts: Collected response parts (text/tool-call parts).
+            thread_id: Codex thread identifier for debugging/traceability.
+            usage: Request usage totals for the response.
         """
-        self._usage = _usage_init
+        # `StreamedResponse` requires model_request_parameters and owns the parts manager.
+        super().__init__(model_request_parameters=model_request_parameters)
+        self._model_name = model_name
+        self._provider_name = provider_name
+        self._parts = parts
+        self._thread_id = thread_id
+        self._usage = usage
+        self._timestamp = _now_utc()
 
     async def _get_event_iterator(
         self,
@@ -334,6 +341,14 @@ class CodexStreamedResponse(StreamedResponse):
                     tool_call_id=part.tool_call_id,
                 )
             else:
+                logger.debug(
+                    "Skipping unsupported streamed part",
+                    extra={
+                        "vendor_part_id": index,
+                        "part_type": type(part).__name__,
+                        "part_kind": getattr(part, "part_kind", None),
+                    },
+                )
                 event = None
 
             if event is not None:
@@ -344,14 +359,16 @@ class CodexStreamedResponse(StreamedResponse):
         Construct a complete model response from events received so far.
 
         Returns:
-            ModelResponse: Contains collected parts, the model name, timestamp, usage, and `vendor_details` with the Codex thread_id.
+            ModelResponse: Contains collected parts, the model name, timestamp, usage,
+            and `provider_details` with the Codex thread_id.
         """
         return ModelResponse(
             parts=self._parts_manager.get_parts(),
             model_name=self.model_name,
+            provider_name=self.provider_name,
             timestamp=self.timestamp,
             usage=self.usage(),
-            vendor_details={"thread_id": self._thread_id},
+            provider_details={"thread_id": self._thread_id},
         )
 
     @property
@@ -364,6 +381,16 @@ class CodexStreamedResponse(StreamedResponse):
         """
         return self._model_name
 
+    @property
+    def provider_name(self) -> Optional[str]:
+        """
+        Return the provider/system name for the response, if set.
+
+        PydanticAI models can optionally report a provider separate from the model name.
+        For Codex, this is typically the `system` identifier used for routing/metadata.
+        """
+        return self._provider_name
+
     @property
     def timestamp(self) -> datetime:
         """
@@ -376,7 +403,11 @@ class CodexStreamedResponse(StreamedResponse):
 
 
 class CodexModel(Model):
-    """Use Codex CLI as a PydanticAI model provider via structured output."""
+    """Use Codex CLI as a PydanticAI model provider via structured output.
+
+    Subclasses can override `prepare_request()` to mutate model settings and
+    request parameters before a Codex turn is executed.
+    """
 
     def __init__(
         self,
@@ -439,12 +470,20 @@ class CodexModel(Model):
         """Return the provider system identifier (vendor name)."""
         return self._system
 
+    def prepare_request(
+        self,
+        model_settings: Optional[ModelSettings],
+        model_request_parameters: ModelRequestParameters,
+    ) -> tuple[Optional[ModelSettings], ModelRequestParameters]:
+        """Hook to customize request settings/parameters before execution."""
+        return model_settings, model_request_parameters
+
     async def _run_codex_request(
         self,
         messages: list[ModelMessage],
         model_settings: Optional[ModelSettings],
         model_request_parameters: ModelRequestParameters,
-    ) -> tuple[List[Any], PydanticUsage, str, ModelRequestParameters]:
+    ) -> tuple[List[Any], RequestUsage, str, ModelRequestParameters]:
         """
         Run a Codex thread for the given conversation and request parameters, and parse the JSON envelope into response parts.
 
@@ -463,10 +502,10 @@ class CodexModel(Model):
             - `model_request_parameters`: The (possibly customized) request parameters
               actually used for the request.
         """
-        del model_settings
-        model_request_parameters = self.customize_request_parameters(
-            model_request_parameters
+        model_settings, model_request_parameters = self.prepare_request(
+            model_settings, model_request_parameters
         )
+        del model_settings
 
         tool_defs = [
             *model_request_parameters.function_tools,
@@ -520,16 +559,14 @@ class CodexModel(Model):
                 prompt, output_schema=output_schema, turn_options=TurnOptions()
             )
 
-        usage = PydanticUsage(requests=1)
+        usage = RequestUsage()
         if parsed_turn.turn.usage is not None:
             cached = parsed_turn.turn.usage.cached_input_tokens
-            details = {"cached_input_tokens": cached} if cached else None
-            usage = PydanticUsage(
-                requests=1,
-                request_tokens=parsed_turn.turn.usage.input_tokens,
-                response_tokens=parsed_turn.turn.usage.output_tokens,
-                total_tokens=parsed_turn.turn.usage.input_tokens
-                + parsed_turn.turn.usage.output_tokens,
+            details = {"cached_input_tokens": cached} if cached else {}
+            usage = RequestUsage(
+                input_tokens=parsed_turn.turn.usage.input_tokens,
+                cache_read_tokens=cached,
+                output_tokens=parsed_turn.turn.usage.output_tokens,
                 details=details,
             )
 
@@ -568,7 +605,8 @@ class CodexModel(Model):
             model_request_parameters: Request-specific parameters that influence Codex execution.
 
         Returns:
-            ModelResponse containing the generated parts, usage information, the model name, and vendor_details with the Codex `thread_id`.
+            ModelResponse containing the generated parts, usage information, the model name,
+            and provider_details with the Codex `thread_id`.
         """
         parts, usage, thread_id, _ = await self._run_codex_request(
             messages,
@@ -579,7 +617,8 @@ class CodexModel(Model):
             parts=parts,
             usage=usage,
             model_name=self.model_name,
-            vendor_details={"thread_id": thread_id},
+            provider_name=self.system,
+            provider_details={"thread_id": thread_id},
         )
 
     @asynccontextmanager
@@ -600,15 +639,17 @@ class CodexModel(Model):
         Returns:
             An async iterator that yields a single StreamedResponse (CodexStreamedResponse) containing the model name, response parts, usage information, and the Codex thread identifier.
         """
-        parts, usage, thread_id, _ = await self._run_codex_request(
+        parts, usage, thread_id, used_params = await self._run_codex_request(
             messages,
             model_settings,
             model_request_parameters,
         )
         streamed = CodexStreamedResponse(
-            _model_name=self.model_name,
-            _parts=parts,
-            _thread_id=thread_id,
-            _usage_init=usage,
+            model_request_parameters=used_params,
+            model_name=self.model_name,
+            provider_name=self.system,
+            parts=parts,
+            thread_id=thread_id,
+            usage=usage,
         )
         yield streamed

codex_sdk_python-0.101.0/src/codex_sdk/tool_envelope.py

@@ -0,0 +1,524 @@
+"""Shared helpers for model-driven tool-calling envelopes.
+
+This module standardizes how Codex structured output is interpreted for
+host-managed tool loops.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from base64 import b64encode
+from dataclasses import asdict, dataclass, is_dataclass
+from typing import Any, Dict, Literal, Mapping, Optional, Sequence, Tuple, Union
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ToolCallEnvelope:
+    """One planned tool call emitted by the model envelope."""
+
+    tool_call_id: str
+    tool_name: str
+    arguments_json: str
+
+
+@dataclass(frozen=True)
+class ToolPlan:
+    """Parsed planner output.
+
+    kind:
+      - ``tool_calls`` when one or more tool calls are requested.
+      - ``final`` when no tool call is requested and final text is provided.
+    """
+
+    kind: Literal["tool_calls", "final"]
+    calls: Tuple[ToolCallEnvelope, ...] = ()
+    content: str = ""
+
+
+class ToolPlanValidationError(ValueError):
+    """Raised for malformed envelope output or invalid tool-call plans."""
+
+    def __init__(self, code: str, message: str):
+        """Initialize a validation error with a stable error code."""
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+ToolChoice = Optional[Union[str, Mapping[str, Any]]]
+
+
+def jsonable(value: Any) -> Any:
+    """Convert common rich objects into JSON-serializable values."""
+    if is_dataclass(value) and not isinstance(value, type):
+        return asdict(value)
+
+    if hasattr(value, "model_dump") and callable(value.model_dump):
+        return value.model_dump(mode="json")
+
+    if isinstance(value, bytes):
+        return {"type": "bytes", "base64": b64encode(value).decode("ascii")}
+
+    if isinstance(value, dict):
+        return {str(key): jsonable(item) for key, item in value.items()}
+
+    if isinstance(value, (list, tuple)):
+        return [jsonable(item) for item in value]
+
+    return value
+
+
+def json_dumps(value: Any) -> str:
+    """Canonical JSON dump used in prompts and normalized tool arguments."""
+    try:
+        return json.dumps(
+            jsonable(value),
+            ensure_ascii=False,
+            separators=(",", ":"),
+            sort_keys=True,
+        )
+    except TypeError as exc:
+        logger.error(
+            "Failed to serialize value to JSON",
+            extra={"value_type": type(value).__name__, "error": str(exc)},
+        )
+        raise
+
+
+def build_envelope_schema(tool_names: Sequence[str]) -> Dict[str, Any]:
+    """Build constrained schema for planner output.
+
+    Output shape:
+      {"tool_calls": [...], "final": "..."}
+    """
+    name_schema: Dict[str, Any] = {"type": "string"}
+    if tool_names:
+        name_schema = {"type": "string", "enum": list(tool_names)}
+
+    return {
+        "type": "object",
+        "properties": {
+            "tool_calls": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "id": {"type": "string"},
+                        "name": name_schema,
+                        "arguments": {"type": "string"},
+                    },
+                    "required": ["id", "name", "arguments"],
+                    "additionalProperties": False,
+                },
+            },
+            "final": {"type": "string"},
+        },
+        "required": ["tool_calls", "final"],
+        "additionalProperties": False,
+    }
+
+
+def parse_tool_plan(output: Any) -> ToolPlan:
+    """Parse raw envelope output into a normalized ``ToolPlan``."""
+    if not isinstance(output, dict):
+        raise ToolPlanValidationError(
+            "invalid_envelope", "Planner output must be a JSON object."
+        )
+
+    if "tool_calls" not in output or "final" not in output:
+        raise ToolPlanValidationError(
+            "invalid_envelope",
+            "Planner output must contain both `tool_calls` and `final`.",
+        )
+
+    raw_calls = output.get("tool_calls")
+    final = output.get("final")
+    if not isinstance(raw_calls, list):
+        raise ToolPlanValidationError(
+            "invalid_envelope", "`tool_calls` must be an array."
+        )
+    if not isinstance(final, str):
+        raise ToolPlanValidationError("invalid_envelope", "`final` must be a string.")
+
+    calls = []
+    for index, call in enumerate(raw_calls):
+        if not isinstance(call, dict):
+            raise ToolPlanValidationError(
+                "invalid_envelope", f"tool_calls[{index}] must be an object."
+            )
+
+        tool_call_id = call.get("id")
+        tool_name = call.get("name")
+        arguments = call.get("arguments")
+        if not isinstance(tool_call_id, str):
+            raise ToolPlanValidationError(
+                "invalid_envelope", f"tool_calls[{index}].id must be a string."
+            )
+        if not isinstance(tool_name, str):
+            raise ToolPlanValidationError(
+                "invalid_envelope", f"tool_calls[{index}].name must be a string."
+            )
+        if not isinstance(arguments, str):
+            raise ToolPlanValidationError(
+                "invalid_envelope",
+                f"tool_calls[{index}].arguments must be a JSON string.",
+            )
+
+        calls.append(
+            ToolCallEnvelope(
+                tool_call_id=tool_call_id,
+                tool_name=tool_name,
+                arguments_json=arguments,
+            )
+        )
+
+    if calls and final.strip():
+        raise ToolPlanValidationError(
+            "invalid_envelope",
+            "Planner output cannot contain both non-empty `final` and `tool_calls`.",
+        )
+
+    if calls:
+        return ToolPlan(kind="tool_calls", calls=tuple(calls), content="")
+
+    return ToolPlan(kind="final", calls=(), content=final)
+
+
+def validate_tool_plan(
+    plan: ToolPlan,
+    *,
+    tool_schemas: Mapping[str, Any],
+    tool_choice: ToolChoice = None,
+    parallel_tool_calls: Optional[bool] = None,
+    max_tool_calls: Optional[int] = None,
+    strict_schema_validation: bool = True,
+    fallback_id_prefix: str = "call",
+) -> ToolPlan:
+    """Validate and normalize a parsed tool plan.
+
+    Normalizations:
+    - Rewrites argument JSON into canonical form.
+    - Replaces missing/blank tool-call IDs with deterministic fallback IDs.
+    """
+    choice_mode, choice_name = _normalize_tool_choice(tool_choice)
+
+    if plan.kind == "final":
+        if choice_mode in {"required", "function"}:
+            raise ToolPlanValidationError(
+                "tool_choice_mismatch",
+                "Model returned final text while tool_choice requires a tool call.",
+            )
+        return plan
+
+    calls = list(plan.calls)
+    if not calls:
+        raise ToolPlanValidationError(
+            "invalid_envelope", "`tool_calls` plan must contain at least one call."
+        )
+
+    if choice_mode == "none":
+        raise ToolPlanValidationError(
+            "tool_choice_mismatch",
+            "Model emitted tool calls while tool_choice is `none`.",
+        )
+
+    if max_tool_calls is not None and len(calls) > max_tool_calls:
+        raise ToolPlanValidationError(
+            "too_many_tool_calls",
+            f"Model emitted {len(calls)} tool calls (max {max_tool_calls}).",
+        )
+
+    if parallel_tool_calls is False and len(calls) > 1:
+        raise ToolPlanValidationError(
+            "parallel_tool_calls_disabled",
+            "Model emitted multiple tool calls while parallel_tool_calls is false.",
+        )
+
+    normalized_calls = []
+    for index, call in enumerate(calls):
+        call_id = (
+            call.tool_call_id.strip() if isinstance(call.tool_call_id, str) else ""
+        )
+        if not call_id:
+            call_id = f"{fallback_id_prefix}_{index}"
+
+        tool_name = call.tool_name.strip()
+        if not tool_name:
+            raise ToolPlanValidationError(
+                "unknown_tool", f"tool_calls[{index}] has empty tool name."
+            )
+
+        if choice_mode == "function" and choice_name and tool_name != choice_name:
+            raise ToolPlanValidationError(
+                "tool_choice_mismatch",
+                (
+                    "Model emitted tool "
+                    f"`{tool_name}` while tool_choice requires `{choice_name}`."
+                ),
+            )
+
+        schema = tool_schemas.get(tool_name)
+        if schema is None:
+            raise ToolPlanValidationError(
+                "unknown_tool", f"Model requested undeclared tool `{tool_name}`."
+            )
+
+        try:
+            parsed_args = json.loads(call.arguments_json)
+        except json.JSONDecodeError as exc:
+            raise ToolPlanValidationError(
+                "invalid_tool_arguments",
+                f"Tool `{tool_name}` arguments are not valid JSON: {exc.msg}",
+            ) from exc
+
+        if not isinstance(parsed_args, dict):
+            raise ToolPlanValidationError(
+                "invalid_tool_arguments",
+                f"Tool `{tool_name}` arguments must decode to a JSON object.",
+            )
+
+        if strict_schema_validation:
+            _validate_json_schema(parsed_args, schema, path=f"tool:{tool_name}")
+
+        normalized_calls.append(
+            ToolCallEnvelope(
+                tool_call_id=call_id,
+                tool_name=tool_name,
+                arguments_json=json_dumps(parsed_args),
+            )
+        )
+
+    return ToolPlan(kind="tool_calls", calls=tuple(normalized_calls), content="")
+
+
+def _normalize_tool_choice(tool_choice: ToolChoice) -> Tuple[str, Optional[str]]:
+    """Normalize tool choice into a `(mode, function_name)` tuple."""
+    if tool_choice is None:
+        return "auto", None
+
+    if isinstance(tool_choice, str):
+        mode = tool_choice.strip().lower()
+        if mode in {"auto", "none", "required"}:
+            return mode, None
+        raise ToolPlanValidationError(
+            "invalid_tool_choice",
+            f"Unsupported tool_choice string `{tool_choice}`.",
+        )
+
+    if not isinstance(tool_choice, Mapping):
+        raise ToolPlanValidationError(
+            "invalid_tool_choice", "tool_choice must be a string or object."
+        )
+
+    choice_type = tool_choice.get("type")
+    if choice_type != "function":
+        raise ToolPlanValidationError(
+            "invalid_tool_choice",
+            "tool_choice object must use type=`function`.",
+        )
+
+    function = tool_choice.get("function")
+    if not isinstance(function, Mapping):
+        raise ToolPlanValidationError(
+            "invalid_tool_choice", "tool_choice.function must be an object."
+        )
+
+    name = function.get("name")
+    if not isinstance(name, str) or not name.strip():
+        raise ToolPlanValidationError(
+            "invalid_tool_choice",
+            "tool_choice.function.name must be a non-empty string.",
+        )
+
+    return "function", name.strip()
+
+
+def _validate_json_schema(value: Any, schema: Any, *, path: str) -> None:
+    """Validate a value against a subset of JSON Schema used for tool arguments."""
+    if not isinstance(schema, Mapping):
+        return
+
+    # Generic enum support.
+    enum_values = schema.get("enum")
+    if isinstance(enum_values, list) and value not in enum_values:
+        raise ToolPlanValidationError(
+            "invalid_tool_arguments",
+            f"{path}: value {value!r} is not in enum {enum_values!r}.",
+        )
+
+    if "const" in schema and value != schema["const"]:
+        raise ToolPlanValidationError(
+            "invalid_tool_arguments",
+            f"{path}: value {value!r} does not match const {schema['const']!r}.",
+        )
+
+    schema_type = schema.get("type")
+    resolved_type: Optional[str] = None
+    if isinstance(schema_type, list):
+        # Support basic union form, e.g. ["string", "null"].
+        matched_types = [t for t in schema_type if _matches_type(value, t)]
+        if matched_types:
+            if "object" in matched_types and isinstance(value, dict):
+                resolved_type = "object"
+            elif "array" in matched_types and isinstance(value, list):
+                resolved_type = "array"
+            else:
+                first = matched_types[0]
+                resolved_type = first if isinstance(first, str) else None
+        else:
+            raise ToolPlanValidationError(
+                "invalid_tool_arguments",
+                f"{path}: expected one of types {schema_type!r}.",
+            )
+    elif isinstance(schema_type, str):
+        _require_type(value, schema_type, path=path)
+        resolved_type = schema_type
+
+    # Composite schemas.
+    any_of = schema.get("anyOf")
+    if isinstance(any_of, list) and any_of:
+        if not _validate_any_of(value, any_of, path=path):
+            raise ToolPlanValidationError(
+                "invalid_tool_arguments", f"{path}: no anyOf branch matched."
+            )
+
+    one_of = schema.get("oneOf")
+    if isinstance(one_of, list) and one_of:
+        matches = 0
+        for branch in one_of:
+            try:
+                _validate_json_schema(value, branch, path=path)
+            except ToolPlanValidationError:
+                continue
+            matches += 1
+        if matches != 1:
+            raise ToolPlanValidationError(
+                "invalid_tool_arguments",
+                f"{path}: expected exactly one oneOf branch match, got {matches}.",
+            )
+
+    all_of = schema.get("allOf")
+    if isinstance(all_of, list):
+        for branch in all_of:
+            _validate_json_schema(value, branch, path=path)
+
+    if resolved_type == "object":
+        _validate_object_schema(value, schema, path=path)
+    elif resolved_type == "array":
+        _validate_array_schema(value, schema, path=path)
+
+
+def _validate_any_of(value: Any, branches: Sequence[Any], *, path: str) -> bool:
+    """Return `True` when at least one branch validates without errors."""
+    for branch in branches:
+        try:
+            _validate_json_schema(value, branch, path=path)
+        except ToolPlanValidationError:
+            continue
+        return True
+    return False
+
+
+def _validate_object_schema(
+    value: Any, schema: Mapping[str, Any], *, path: str
+) -> None:
+    """Validate object constraints (`required`, properties, additionalProperties)."""
+    if not isinstance(value, dict):
+        raise ToolPlanValidationError(
+            "invalid_tool_arguments", f"{path}: expected object."
+        )
+
+    required = schema.get("required")
+    if isinstance(required, list):
+        for field in required:
+            if isinstance(field, str) and field not in value:
+                raise ToolPlanValidationError(
+                    "invalid_tool_arguments",
+                    f"{path}: missing required field `{field}`.",
+                )
+
+    properties = schema.get("properties")
+    property_schemas: Mapping[str, Any] = (
+        properties if isinstance(properties, Mapping) else {}
+    )
+
+    additional_properties = schema.get("additionalProperties", True)
+    if additional_properties is False:
+        unknown = [key for key in value.keys() if key not in property_schemas]
+        if unknown:
+            raise ToolPlanValidationError(
+                "invalid_tool_arguments",
+                f"{path}: unexpected fields {unknown!r}.",
+            )
+
+    for key, item in value.items():
+        prop_schema = property_schemas.get(key)
+        if prop_schema is not None:
+            _validate_json_schema(item, prop_schema, path=f"{path}.{key}")
+        elif isinstance(additional_properties, Mapping):
+            _validate_json_schema(
+                item,
+                additional_properties,
+                path=f"{path}.{key}",
+            )
+
+
+def _validate_array_schema(value: Any, schema: Mapping[str, Any], *, path: str) -> None:
+    """Validate array constraints (`items`, `minItems`, `maxItems`)."""
+    if not isinstance(value, list):
+        raise ToolPlanValidationError(
+            "invalid_tool_arguments", f"{path}: expected array."
+        )
+
+    items_schema = schema.get("items")
+    if items_schema is not None:
+        for index, item in enumerate(value):
+            _validate_json_schema(item, items_schema, path=f"{path}[{index}]")
+
+    min_items = schema.get("minItems")
+    if isinstance(min_items, int) and len(value) < min_items:
+        raise ToolPlanValidationError(
+            "invalid_tool_arguments",
+            f"{path}: expected at least {min_items} items.",
+        )
+
+    max_items = schema.get("maxItems")
+    if isinstance(max_items, int) and len(value) > max_items:
+        raise ToolPlanValidationError(
+            "invalid_tool_arguments",
+            f"{path}: expected at most {max_items} items.",
+        )
+
+
+def _matches_type(value: Any, schema_type: Any) -> bool:
+    """Return whether a value satisfies a JSON-schema primitive type label."""
+    if not isinstance(schema_type, str):
+        return False
+    if schema_type == "null":
+        return value is None
+    if schema_type == "boolean":
+        return isinstance(value, bool)
+    if schema_type == "integer":
+        return isinstance(value, int) and not isinstance(value, bool)
+    if schema_type == "number":
+        return (isinstance(value, int) and not isinstance(value, bool)) or isinstance(
+            value, float
+        )
+    if schema_type == "string":
+        return isinstance(value, str)
+    if schema_type == "array":
+        return isinstance(value, list)
+    if schema_type == "object":
+        return isinstance(value, dict)
+    return True
+
+
+def _require_type(value: Any, schema_type: str, *, path: str) -> None:
+    """Raise when a value does not satisfy a required JSON-schema type."""
+    if not _matches_type(value, schema_type):
+        raise ToolPlanValidationError(
+            "invalid_tool_arguments", f"{path}: expected type `{schema_type}`."
+        )