codex-python 1.114.1__tar.gz → 1.122.0__tar.gz

{codex_python-1.114.1 → codex_python-1.122.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-python
-Version: 1.114.1
+Version: 1.122.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.12
@@ -66,13 +66,29 @@ Use `AppServerClient` when you want a deeper integration:
 ## Quickstart: `Codex`
 
 ```python
-from codex import Codex
+from codex import Codex, ThreadStartOptions
 
 client = Codex()
+
+# Simplest one-shot call.
 summary = client.run_text("Diagnose the failing tests and propose a fix")
 print(summary)
+
+# One-shot call with thread-scoped defaults for that run's fresh internal thread.
+summary = client.run_text(
+    "Diagnose the failing tests in this repo",
+    thread_options=ThreadStartOptions(
+        cwd="/repo",
+        model="gpt-5",
+    ),
+)
+print(summary)
 ```
 
+Use `thread_options=` on `run()`, `run_text()`, `run_json()`, and `run_model()` when you want to
+set defaults on the fresh internal thread created for that one-shot call. Use
+`start_thread()` / `resume_thread()` when later runs should share context.
+
 More `Codex` examples: [docs/exec_api.md](docs/exec_api.md)
 
 ## Quickstart: `AppServerClient`
@@ -97,6 +113,35 @@ with AppServerClient.connect_stdio(initialize_options=initialize_options) as cli
 More app-server examples: [docs/app_server.md](docs/app_server.md)
 For websocket transport, install the optional extra: `pip install "codex-python[websocket]"`.
 
+## Dynamic tools
+
+Decorator-driven dynamic tools are available on both SDK surfaces.
+
+### `Codex`
+
+```python
+from codex import Codex, dynamic_tool
+
+
+@dynamic_tool
+def lookup_ticket(id: str) -> str:
+    """Look up a support ticket by id."""
+    return f"Ticket {id}: Login requests time out in eu-west-1."
+
+
+client = Codex()
+summary = client.run_text(
+    "Use the lookup_ticket dynamic tool for ticket 123 and summarize the result.",
+    tools=[lookup_ticket],
+)
+print(summary)
+```
+
+### `AppServerClient`
+
+For a complete app-server example using the same decorator-driven flow, see
+[examples/app_server_dynamic_tool.py](examples/app_server_dynamic_tool.py).
+
 ## Structured output
 
 ### `Codex`
@@ -186,10 +231,12 @@ Advanced app-server usage, including typed stable RPC domains such as `client.mo
 ## Examples
 
 - [examples/basic_conversation.py](examples/basic_conversation.py): minimal `Codex` flow
+- [examples/basic_dynamic_tool.py](examples/basic_dynamic_tool.py): high-level `Codex` dynamic tool flow
 - [examples/app_server_conversation.py](examples/app_server_conversation.py): minimal app-server flow
 - [examples/app_server_websocket_conversation.py](examples/app_server_websocket_conversation.py): minimal websocket app-server flow
 - [examples/app_server_stream_events.py](examples/app_server_stream_events.py): protocol-native app-server streaming
 - [examples/app_server_tool_handler.py](examples/app_server_tool_handler.py): typed app-server request handling
+- [examples/app_server_dynamic_tool.py](examples/app_server_dynamic_tool.py): decorator-driven dynamic tool registration
 
 ## Bundled binary behavior
 

{codex_python-1.114.1 → codex_python-1.122.0}/README.md

@@ -44,13 +44,29 @@ Use `AppServerClient` when you want a deeper integration:
 ## Quickstart: `Codex`
 
 ```python
-from codex import Codex
+from codex import Codex, ThreadStartOptions
 
 client = Codex()
+
+# Simplest one-shot call.
 summary = client.run_text("Diagnose the failing tests and propose a fix")
 print(summary)
+
+# One-shot call with thread-scoped defaults for that run's fresh internal thread.
+summary = client.run_text(
+    "Diagnose the failing tests in this repo",
+    thread_options=ThreadStartOptions(
+        cwd="/repo",
+        model="gpt-5",
+    ),
+)
+print(summary)
 ```
 
+Use `thread_options=` on `run()`, `run_text()`, `run_json()`, and `run_model()` when you want to
+set defaults on the fresh internal thread created for that one-shot call. Use
+`start_thread()` / `resume_thread()` when later runs should share context.
+
 More `Codex` examples: [docs/exec_api.md](docs/exec_api.md)
 
 ## Quickstart: `AppServerClient`
@@ -75,6 +91,35 @@ with AppServerClient.connect_stdio(initialize_options=initialize_options) as cli
 More app-server examples: [docs/app_server.md](docs/app_server.md)
 For websocket transport, install the optional extra: `pip install "codex-python[websocket]"`.
 
+## Dynamic tools
+
+Decorator-driven dynamic tools are available on both SDK surfaces.
+
+### `Codex`
+
+```python
+from codex import Codex, dynamic_tool
+
+
+@dynamic_tool
+def lookup_ticket(id: str) -> str:
+    """Look up a support ticket by id."""
+    return f"Ticket {id}: Login requests time out in eu-west-1."
+
+
+client = Codex()
+summary = client.run_text(
+    "Use the lookup_ticket dynamic tool for ticket 123 and summarize the result.",
+    tools=[lookup_ticket],
+)
+print(summary)
+```
+
+### `AppServerClient`
+
+For a complete app-server example using the same decorator-driven flow, see
+[examples/app_server_dynamic_tool.py](examples/app_server_dynamic_tool.py).
+
 ## Structured output
 
 ### `Codex`
@@ -164,10 +209,12 @@ Advanced app-server usage, including typed stable RPC domains such as `client.mo
 ## Examples
 
 - [examples/basic_conversation.py](examples/basic_conversation.py): minimal `Codex` flow
+- [examples/basic_dynamic_tool.py](examples/basic_dynamic_tool.py): high-level `Codex` dynamic tool flow
 - [examples/app_server_conversation.py](examples/app_server_conversation.py): minimal app-server flow
 - [examples/app_server_websocket_conversation.py](examples/app_server_websocket_conversation.py): minimal websocket app-server flow
 - [examples/app_server_stream_events.py](examples/app_server_stream_events.py): protocol-native app-server streaming
 - [examples/app_server_tool_handler.py](examples/app_server_tool_handler.py): typed app-server request handling
+- [examples/app_server_dynamic_tool.py](examples/app_server_dynamic_tool.py): decorator-driven dynamic tool registration
 
 ## Bundled binary behavior
 

{codex_python-1.114.1 → codex_python-1.122.0}/codex/__init__.py

@@ -3,9 +3,11 @@
 from __future__ import annotations
 
 from codex.codex import Codex
+from codex.dynamic_tools import dynamic_tool
 from codex.errors import CodexError, CodexExecError, CodexParseError, ThreadRunError
 from codex.options import (
     CancelSignal,
+    CodexConfig,
     CodexConfigObject,
     CodexConfigValue,
     CodexOptions,
@@ -13,11 +15,16 @@ from codex.options import (
     ThreadStartOptions,
     TurnOptions,
 )
+from codex.thread import CodexTurnStream, Input, Thread
 
-__version__ = "1.114.1"
+__version__ = "1.122.0"
 
 __all__ = [
     "Codex",
+    "CodexTurnStream",
+    "Thread",
+    "Input",
+    "dynamic_tool",
     "CodexError",
     "CodexExecError",
     "CodexParseError",
@@ -26,6 +33,7 @@ __all__ = [
     "ThreadStartOptions",
     "ThreadResumeOptions",
     "TurnOptions",
+    "CodexConfig",
     "CodexConfigValue",
     "CodexConfigObject",
     "CancelSignal",

codex_python-1.122.0/codex/_config_types.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from codex.protocol import types as protocol
+
+type CodexConfigValue = (
+    str | int | float | bool | list["CodexConfigValue"] | dict[str, "CodexConfigValue"]
+)
+type CodexConfigObject = dict[str, CodexConfigValue]
+
+
+class CodexConfig(BaseModel):
+    """Typed top-level Codex config shape with forward-compatible extra keys."""
+
+    model_config = ConfigDict(extra="allow")
+    __pydantic_extra__: dict[str, CodexConfigValue]
+
+    analytics: CodexConfigObject | None = Field(
+        default=None,
+        description="Open-ended analytics configuration subtree.",
+    )
+    approval_policy: protocol.AskForApproval | None = Field(
+        default=None,
+        description="Default approval policy for new turns and commands.",
+    )
+    compact_prompt: str | None = Field(
+        default=None,
+        description="Prompt text used when the app-server compacts thread history.",
+    )
+    developer_instructions: str | None = Field(
+        default=None,
+        description="Default developer instructions applied to new turns.",
+    )
+    forced_chatgpt_workspace_id: str | None = Field(
+        default=None,
+        description="Workspace identifier to force for ChatGPT-managed auth flows.",
+    )
+    forced_login_method: Literal["chatgpt", "api"] | None = Field(
+        default=None,
+        description="Force Codex auth to ChatGPT or API-key mode.",
+    )
+    instructions: str | None = Field(
+        default=None,
+        description="Default user-visible instructions prepended to new conversations.",
+    )
+    model: str | None = Field(
+        default=None,
+        description="Default model id used when threads or turns do not override it.",
+    )
+    model_auto_compact_token_limit: int | None = Field(
+        default=None,
+        description="Token threshold that triggers automatic thread compaction.",
+    )
+    model_context_window: int | None = Field(
+        default=None,
+        description="Context window size override for the configured model.",
+    )
+    model_provider: str | None = Field(
+        default=None,
+        description="Default model provider name.",
+    )
+    model_reasoning_effort: protocol.ReasoningEffort | None = Field(
+        default=None,
+        description="Default reasoning effort for turns that do not override it.",
+    )
+    model_reasoning_summary: protocol.ReasoningSummary | None = Field(
+        default=None,
+        description="Default reasoning-summary behavior for supported models.",
+    )
+    model_verbosity: Literal["low", "medium", "high"] | None = Field(
+        default=None,
+        description="Default verbosity for supported models.",
+    )
+    profile: str | None = Field(
+        default=None,
+        description="Name of the active Codex profile.",
+    )
+    profiles: CodexConfigObject | None = Field(
+        default_factory=dict,
+        description="Open-ended profile definitions keyed by profile name.",
+    )
+    review_model: str | None = Field(
+        default=None,
+        description="Model override used for review flows.",
+    )
+    sandbox_mode: protocol.SandboxMode | None = Field(
+        default=None,
+        description="Default sandbox mode for new threads and turns.",
+    )
+    sandbox_workspace_write: CodexConfigObject | None = Field(
+        default=None,
+        description="Open-ended workspace-write sandbox configuration subtree.",
+    )
+    service_tier: protocol.ServiceTier | None = Field(
+        default=None,
+        description="Default service tier for requests that do not override it.",
+    )
+    tools: CodexConfigObject | None = Field(
+        default=None,
+        description="Open-ended tool configuration subtree.",
+    )
+    web_search: Literal["disabled", "cached", "live"] | None = Field(
+        default=None,
+        description="Default web-search mode.",
+    )

{codex_python-1.114.1 → codex_python-1.122.0}/codex/_runtime.py

@@ -7,7 +7,7 @@ from collections.abc import Callable, Mapping
 from pathlib import Path
 
 from codex._binary import BundledCodexNotFoundError
-from codex._config_types import CodexConfigObject, CodexConfigValue
+from codex._config_types import CodexConfig, CodexConfigObject, CodexConfigValue
 
 INTERNAL_ORIGINATOR_ENV = "CODEX_INTERNAL_ORIGINATOR_OVERRIDE"
 PYTHON_SDK_ORIGINATOR = "codex_sdk_py"
@@ -50,9 +50,14 @@ def resolve_codex_path(
         return system_codex
 
 
-def serialize_config_overrides(config_overrides: CodexConfigObject) -> list[str]:
+def serialize_config_overrides(config_overrides: CodexConfig | CodexConfigObject) -> list[str]:
     overrides: list[str] = []
-    _flatten_config_overrides(config_overrides, "", overrides)
+    root = (
+        config_overrides.model_dump(mode="python", exclude_none=True, exclude_unset=True)
+        if isinstance(config_overrides, CodexConfig)
+        else config_overrides
+    )
+    _flatten_config_overrides(root, "", overrides)
     return overrides
 
 

{codex_python-1.114.1 → codex_python-1.122.0}/codex/app_server/__init__.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from codex._config_types import CodexConfig
 from codex.app_server._async_client import AsyncAppServerClient, AsyncRpcClient
 from codex.app_server._async_threads import AsyncAppServerThread, AsyncTurnStream
 from codex.app_server._sync_client import AppServerClient, RpcClient
@@ -23,6 +24,7 @@ from codex.app_server.options import (
     AppServerTurnOptions,
     AppServerWebSocketOptions,
 )
+from codex.dynamic_tools import dynamic_tool
 
 __all__ = [
     "AsyncAppServerClient",
@@ -30,6 +32,7 @@ __all__ = [
     "AsyncRpcClient",
     "AsyncTurnStream",
     "AppServerClient",
+    "dynamic_tool",
     "AppServerThread",
     "RpcClient",
     "TurnStream",
@@ -40,6 +43,7 @@ __all__ = [
     "AppServerRpcError",
     "AppServerTurnError",
     "AppServerClientInfo",
+    "CodexConfig",
     "AppServerInitializeOptions",
     "AppServerProcessOptions",
     "AppServerWebSocketOptions",

{codex_python-1.114.1 → codex_python-1.122.0}/codex/app_server/_async_client.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from collections.abc import Collection, Mapping
+from collections.abc import Callable, Collection, Mapping
 from typing import TypeVar, cast
 
 from pydantic import BaseModel
@@ -43,6 +43,7 @@ from codex.app_server.transports import (
     AsyncStdioTransport,
     AsyncWebSocketTransport,
 )
+from codex.dynamic_tools import _DynamicToolRuntime, merge_dynamic_tool_specs, resolve_dynamic_tools
 from codex.protocol import types as protocol
 
 _ModelT = TypeVar("_ModelT", bound=BaseModel)
@@ -60,8 +61,9 @@ __all__ = [
 class AsyncRpcClient:
     """Low-level async JSON-RPC access to app-server methods."""
 
-    def __init__(self, session: _AsyncSession) -> None:
+    def __init__(self, session: _AsyncSession, dynamic_tools: _DynamicToolRuntime) -> None:
         self._session = session
+        self._dynamic_tools = dynamic_tools
 
     async def request(
         self,
@@ -92,6 +94,7 @@ class AsyncRpcClient:
         *,
         request_model: type[_RequestT] | None = None,
     ) -> None:
+        self._dynamic_tools.check_manual_handler_registration(method)
         self._session.on_request(method, handler, request_model=request_model)
 
 
@@ -114,7 +117,8 @@ class AsyncAppServerClient:
         initialize_options: AppServerInitializeOptions | None = None,
     ) -> None:
         self._session = _AsyncSession(transport, initialize_options)
-        self.rpc = AsyncRpcClient(self._session)
+        self._dynamic_tools = _DynamicToolRuntime(self._session.on_request)
+        self.rpc = AsyncRpcClient(self._session, self._dynamic_tools)
         self.events = AsyncEventsClient(self._session)
         self.models = AsyncModelsClient(self.rpc)
         self.apps = AsyncAppsClient(self.rpc)
@@ -167,12 +171,19 @@ class AsyncAppServerClient:
     async def start_thread(
         self,
         options: AppServerThreadStartOptions | None = None,
+        *,
+        tools: Collection[Callable[..., object]] | None = None,
     ) -> AsyncAppServerThread:
+        start_options = options or AppServerThreadStartOptions()
+        resolved_tools = resolve_dynamic_tools(list(tools or ()))
+        dynamic_tools = merge_dynamic_tool_specs(start_options.dynamic_tools, resolved_tools)
+        self._dynamic_tools.prepare_activation(resolved_tools)
         result = await self.rpc.request_typed(
             "thread/start",
-            (options or AppServerThreadStartOptions()).to_params(),
+            start_options.model_copy(update={"dynamic_tools": dynamic_tools}).to_params(),
             ThreadResult,
         )
+        self._dynamic_tools.activate(result.thread.id, resolved_tools)
         return AsyncAppServerThread(cast(_ThreadClient, self), result.thread)
 
     async def resume_thread(

{codex_python-1.114.1 → codex_python-1.122.0}/codex/app_server/_async_services.py

@@ -26,6 +26,7 @@ from codex.app_server.models import (
     ModelInfo,
     ModelListResult,
     SkillsConfigWriteResult,
+    SkillsListEntry,
     SkillsListResult,
     WindowsSandboxSetupStartResult,
 )
@@ -113,7 +114,7 @@ class AsyncSkillsClient(_AsyncServiceClient):
         cwds: Sequence[str] | None = None,
         force_reload: bool | None = None,
         per_cwd_extra_user_roots: Sequence[protocol.SkillsListExtraRootsForCwd] | None = None,
-    ) -> list[protocol.SkillsListEntry]:
+    ) -> list[SkillsListEntry]:
         return (
             await self.list_page(
                 cwds=cwds,
@@ -139,7 +140,10 @@ class AsyncSkillsClient(_AsyncServiceClient):
         return await self._rpc.request_typed("skills/list", params, SkillsListResult)
 
     async def write_config(self, *, path: str, enabled: bool) -> SkillsConfigWriteResult:
-        params = protocol.SkillsConfigWriteParams(path=path, enabled=enabled)
+        params = protocol.SkillsConfigWriteParams(
+            path=protocol.AbsolutePathBuf(path),
+            enabled=enabled,
+        )
         return await self._rpc.request_typed("skills/config/write", params, SkillsConfigWriteResult)
 
 
@@ -322,19 +326,80 @@ class AsyncCommandClient(_AsyncServiceClient):
         *,
         command: Sequence[str],
         cwd: str | None = None,
+        disable_output_cap: bool | None = None,
+        disable_timeout: bool | None = None,
+        env: Mapping[str, object | None] | None = None,
+        output_bytes_cap: int | None = None,
+        process_id: str | None = None,
         sandbox_policy: protocol.SandboxPolicy | None = None,
+        size: protocol.CommandExecTerminalSize | None = None,
+        stream_stdin: bool | None = None,
+        stream_stdout_stderr: bool | None = None,
         timeout_ms: int | None = None,
+        tty: bool | None = None,
     ) -> CommandExecResult:
         params = protocol.CommandExecParams(
             command=list(command),
             cwd=cwd,
+            disableOutputCap=disable_output_cap,
+            disableTimeout=disable_timeout,
+            env=dict(env) if env is not None else None,
+            outputBytesCap=output_bytes_cap,
+            processId=process_id,
             sandboxPolicy=sandbox_policy,
+            size=size,
+            streamStdin=stream_stdin,
+            streamStdoutStderr=stream_stdout_stderr,
             timeoutMs=timeout_ms,
+            tty=tty,
         )
         return await self._rpc.request_typed("command/exec", params, CommandExecResult)
 
     exec = execute
 
+    async def write_stdin(
+        self,
+        *,
+        process_id: str,
+        close_stdin: bool | None = None,
+        delta_base64: str | None = None,
+    ) -> EmptyResult:
+        """Write stdin bytes to a running `command/exec` process or close stdin.
+
+        This wraps the app-server `command/exec/write` request. `delta_base64`
+        is optional base64-encoded stdin data; `close_stdin` closes the
+        process stdin after the optional write.
+        """
+        params = protocol.CommandExecWriteParams(
+            closeStdin=close_stdin,
+            deltaBase64=delta_base64,
+            processId=process_id,
+        )
+        return await self._rpc.request_typed("command/exec/write", params, EmptyResult)
+
+    async def resize_terminal(
+        self,
+        *,
+        process_id: str,
+        size: protocol.CommandExecTerminalSize,
+    ) -> EmptyResult:
+        """Resize the terminal attached to a running `command/exec` process.
+
+        This wraps the app-server `command/exec/resize` request and sends the
+        new terminal dimensions as `cols` and `rows`.
+        """
+        params = protocol.CommandExecResizeParams(processId=process_id, size=size)
+        return await self._rpc.request_typed("command/exec/resize", params, EmptyResult)
+
+    async def terminate_process(self, *, process_id: str) -> EmptyResult:
+        """Terminate a running `command/exec` process.
+
+        This wraps the app-server `command/exec/terminate` request for the
+        client-supplied process id.
+        """
+        params = protocol.CommandExecTerminateParams(processId=process_id)
+        return await self._rpc.request_typed("command/exec/terminate", params, EmptyResult)
+
 
 class AsyncExternalAgentConfigClient(_AsyncServiceClient):
     async def detect(
@@ -369,7 +434,10 @@ class AsyncWindowsSandboxClient(_AsyncServiceClient):
         mode: protocol.WindowsSandboxSetupMode,
         cwd: str | None = None,
     ) -> WindowsSandboxSetupStartResult:
-        params = protocol.WindowsSandboxSetupStartParams(cwd=cwd, mode=mode)
+        params = protocol.WindowsSandboxSetupStartParams(
+            cwd=protocol.AbsolutePathBuf(cwd) if cwd is not None else None,
+            mode=mode,
+        )
         return await self._rpc.request_typed(
             "windowsSandbox/setupStart",
             params,

{codex_python-1.114.1 → codex_python-1.122.0}/codex/app_server/_async_threads.py

@@ -41,9 +41,13 @@ _TURN_STREAM_NOTIFICATION_METHODS = {
     "turn/completed",
     "turn/diff/updated",
     "turn/plan/updated",
+    "hook/started",
+    "hook/completed",
     "thread/tokenUsage/updated",
     "item/started",
     "item/completed",
+    "item/autoApprovalReview/started",
+    "item/autoApprovalReview/completed",
     "item/agentMessage/delta",
     "item/plan/delta",
     "item/reasoning/summaryTextDelta",
@@ -235,15 +239,21 @@ class AsyncTurnStream:
         self._require_terminal_turn()
         return self._final_message
 
-    async def steer(self, input: TurnInput) -> TurnIdResult:
+    async def steer(
+        self,
+        input: TurnInput,
+        *,
+        responsesapi_client_metadata: Mapping[str, object] | None = None,
+    ) -> TurnIdResult:
         """Append additional user input to the in-flight turn."""
-        params = protocol.TurnSteerParams.model_validate(
-            {
-                "threadId": self.thread_id,
-                "expectedTurnId": self.turn_id,
-                "input": normalize_turn_input(input),
-            }
-        )
+        payload: dict[str, object] = {
+            "threadId": self.thread_id,
+            "expectedTurnId": self.turn_id,
+            "input": normalize_turn_input(input),
+        }
+        if responsesapi_client_metadata is not None:
+            payload["responsesapiClientMetadata"] = dict(responsesapi_client_metadata)
+        params = protocol.TurnSteerParams.model_validate(payload)
         return await self._thread._client.rpc.request_typed("turn/steer", params, TurnIdResult)
 
     async def interrupt(self) -> EmptyResult:

{codex_python-1.114.1 → codex_python-1.122.0}/codex/app_server/_sync_client.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import asyncio
 import concurrent.futures
 import time
-from collections.abc import Coroutine, Mapping
+from collections.abc import Callable, Collection, Coroutine, Mapping
 from contextlib import suppress
 from threading import Thread
 from typing import Any, TypeVar, cast
@@ -311,9 +311,13 @@ class AppServerClient(_SyncRunner):
     def start_thread(
         self,
         options: AppServerThreadStartOptions | None = None,
+        *,
+        tools: Collection[Callable[..., object]] | None = None,
     ) -> AppServerThread:
         return AppServerThread(
-            cast(_AsyncThreadLike, self._run(self._async_client.start_thread(options))),
+            cast(
+                _AsyncThreadLike, self._run(self._async_client.start_thread(options, tools=tools))
+            ),
             self._run,
         )