codex-sdk-python 0.105.0__tar.gz → 0.114.0__tar.gz

{codex_sdk_python-0.105.0 → codex_sdk_python-0.114.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: codex-sdk-python
-Version: 0.105.0
+Version: 0.114.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,9 +18,9 @@ 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 ; extra == 'logfire'
+Requires-Dist: logfire-api>=4 ; extra == 'logfire'
 Requires-Dist: pydantic>=2 ; extra == 'pydantic'
-Requires-Dist: pydantic-ai ; python_full_version >= '3.10' and extra == 'pydantic-ai'
+Requires-Dist: pydantic-ai>=1.68.0,<2 ; python_full_version >= '3.10' and extra == 'pydantic-ai'
 Maintainer: Vectorfy Co
 Maintainer-email: Vectorfy Co <git@vectorfy.co>
 Requires-Python: >=3.8
@@ -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.105.0-6b7280?style=flat&logo=pypi&logoColor=white" alt="Release 0.105.0 badge" />
+        <img src="https://img.shields.io/badge/Release-0.114.0-6b7280?style=flat&logo=pypi&logoColor=white" alt="Release 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>
@@ -73,7 +73,7 @@ Embed the Codex agent in Python workflows. This SDK wraps the bundled `codex` CL
 </div>
 
 - Runtime dependency-free: uses only the Python standard library.
-- Codex CLI binaries can be sourced either from the vendored `src/codex_sdk/vendor/` tree (when present) or from a system-installed `codex` binary (`codex_path_override` supported).
+- Codex CLI binaries are downloaded separately; use `scripts/setup_binary.py` from the repo or install the Codex CLI and set `codex_path_override`.
 - Async-first API with sync helpers, streaming events, and structured output.
 - Python 3.8/3.9 support is deprecated and will be removed in a future release; use Python 3.10+.
 
@@ -168,8 +168,6 @@ python examples/app_server_turn_session.py
 python examples/config_overrides.py
 python examples/hooks_streaming.py
 python examples/notify_hook.py
-python examples/pydantic_ai_run_compat.py
-python examples/pydantic_ai_run_stream_compat.py
 ```
 
 <a id="features"></a>
@@ -187,15 +185,6 @@ python examples/pydantic_ai_run_stream_compat.py
 | ![Abort](https://img.shields.io/badge/Abort-Signals-ef4444?style=flat&logo=gnubash&logoColor=white)                | Cancel running turns via `AbortController` and `AbortSignal`.           |
 | ![Telemetry](https://img.shields.io/badge/Telemetry-Logfire%20Spans-f97316?style=flat&logo=simpleicons&logoColor=white) | Optional spans if Logfire is installed and initialized.                 |
 
-### Execution surfaces and transports
-
-| Surface | Primary transport | Typical use |
-| ------- | ----------------- | ----------- |
-| `Codex` + `Thread` | `codex exec --experimental-json` (JSONL over stdio) | Conversational turns, streaming item events, structured output (`run_json` / `run_pydantic`). |
-| `AppServerClient` | `codex app-server` (JSON-RPC over stdio) | Full app-server protocol: thread management, turn sessions, approvals, account/config/skills APIs. |
-| `CodexModel` (PydanticAI provider) | `codex app-server` (JSON-RPC over stdio) | Tool-call planning + text generation through app-server turn sessions with incremental stream events. |
-| `codex_handoff_tool` (PydanticAI tool) | `Thread.run(...)` on top of `codex exec` | Delegate repository-aware tasks from another model to Codex. |
-
 <a id="configuration"></a>
 ## ![Configuration](https://img.shields.io/badge/Configuration-Options%20%26%20Env-0ea5e9?style=for-the-badge&logo=json&logoColor=white)
 
@@ -323,10 +312,6 @@ For richer integrations (thread fork, requirements, explicit skill input), use t
 protocol. The client handles the initialize/initialized handshake and gives you access to
 JSON-RPC notifications.
 
-`AppServerClient` starts `codex app-server` and multiplexes notifications + server-initiated
-requests (for example approval requests in `turn_session(...)`) on top of the same stdio
-connection.
-
 ```python
 import asyncio
 from codex_sdk import AppServerClient, AppServerOptions
@@ -362,15 +347,20 @@ default prompt) for richer UI integrations.
 The SDK also exposes helpers for most app-server endpoints:
 
 - Threads: `thread_start`, `thread_resume`, `thread_fork`, `thread_list`, `thread_loaded_list`,
-  `thread_read`, `thread_archive`, `thread_unarchive`, `thread_name_set`,
-  `thread_compact_start`, `thread_rollback`
+  `thread_read`, `thread_archive`, `thread_unsubscribe`, `thread_unarchive`,
+  `thread_name_set`, `thread_compact_start`, `thread_rollback`, `thread_metadata_update`
 - Config: `config_read`, `config_value_write`, `config_batch_write`, `config_requirements_read`
-- Skills: `skills_list`, `skills_remote_read`, `skills_remote_write`, `skills_config_write`
-- Turns/review: `turn_start`, `turn_interrupt`, `review_start`, `turn_session`
-- Models: `model_list`
+- Skills: `skills_list`, `skills_remote_list`, `skills_remote_export`, `skills_remote_read` (alias),
+  `skills_remote_write` (alias), `skills_config_write`
+- Turns/review: `turn_start`, `turn_steer`, `turn_interrupt`, `review_start`, `turn_session`
+- Models: `model_list`, `experimental_feature_list`
 - Collaboration modes: `collaboration_mode_list` (experimental)
-- One-off commands: `command_exec`
+- Plugins: `plugin_list`, `plugin_install`, `plugin_uninstall`
+- One-off commands: `command_exec`, `command_exec_write`, `command_exec_resize`,
+  `command_exec_terminate`
 - MCP auth/status: `mcp_server_oauth_login`, `mcp_server_refresh`, `mcp_server_status_list`
+- External agent config: `external_agent_config_detect`, `external_agent_config_import`
+- Windows sandbox: `windows_sandbox_setup_start`
 - Account: `account_login_start`, `account_login_cancel`, `account_logout`,
   `account_rate_limits_read`, `account_read`
 - Feedback: `feedback_upload`
@@ -381,21 +371,11 @@ for payload shapes and event semantics.
 Note: some endpoints and fields are gated behind an experimental capability; set
 `AppServerOptions(experimental_api_enabled=True)` to opt in.
 
-`thread_list` supports `archived`, `sort_key`, and `source_kinds` filters (unchanged), and now also accepts `cwd`
-for scoped thread queries. `config_read` accepts an optional `cwd` to compute effective layered config for a specific
-working directory.
+`ApprovalDecisions` also supports `permissions_request` for auto-responding to
+`item/permissions/requestApproval` server requests during `turn_session()`.
 
-`skills_remote_read` supports `cwds`, `enabled`, `hazelnut_scope`, and `product_surface` filters. `model_list` accepts
-an optional `include_hidden` flag.
-
-```python
-threads = await app.thread_list(archived=False, sort_key="updatedAt", source_kinds=["local"], cwd=".")
-config = await app.config_read(include_layers=True, cwd=".")
-skills = await app.skills_remote_read(
-    cwds=["."], enabled=True, hazelnut_scope="user", product_surface="codex_desktop"
-)
-models = await app.model_list(limit=20, include_hidden=False)
-```
+`thread_list` supports `archived`, `sort_key`, and `source_kinds` filters, and `config_read` accepts an optional `cwd`
+to compute the effective layered config for a specific working directory.
 
 ### Observability (OTEL) and notify
 
@@ -438,14 +418,8 @@ 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` to fetch and assemble the platform `@openai/codex`
-artifacts into `src/codex_sdk/vendor/`.
-
-`scripts/setup_binary.py` behavior:
-- Resolves `CODEX_NPM_VERSION` when set; otherwise resolves latest `@openai/codex`.
-- Tries legacy `@openai/codex-sdk` package first, then falls back to per-target `@openai/codex@<version>-<suffix>` artifacts.
-- Rebuilds `src/codex_sdk/vendor/` for all supported targets and validates current-platform binary presence.
+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.
 
 <a id="auth"></a>
 ## ![Auth](https://img.shields.io/badge/Auth%20%26%20Credentials-Access-2563eb?style=for-the-badge&logo=gnubash&logoColor=white)
@@ -538,6 +512,7 @@ print(turn.final_response)
 - `command_execution`
 - `file_change`
 - `mcp_tool_call`
+- `collab_tool_call`
 - `web_search`
 - `todo_list`
 - `error`
@@ -614,7 +589,8 @@ last_thread = codex.resume_last_thread()
 ### Turn helpers
 
 Each `Turn` provides convenience filters: `agent_messages()`, `reasoning()`, `commands()`,
-`file_changes()`, `mcp_tool_calls()`, `web_searches()`, `todo_lists()`, and `errors()`.
+`file_changes()`, `mcp_tool_calls()`, `collab_tool_calls()`, `web_searches()`,
+`todo_lists()`, and `errors()`.
 
 <a id="api"></a>
 ## ![API Reference](https://img.shields.io/badge/API-Reference-6366f1?style=for-the-badge&logo=python&logoColor=white)
@@ -635,7 +611,12 @@ Exceptions:
 Typed events and items:
 - `ThreadEvent` union of `thread.*`, `turn.*`, `item.*`, and `error` events.
 - `ThreadItem` union of `agent_message`, `reasoning`, `command_execution`, `file_change`,
-  `mcp_tool_call`, `web_search`, `todo_list`, `error`.
+  `mcp_tool_call`, `collab_tool_call`, `web_search`, `todo_list`, `error`.
+- `CollabToolCallItem`: typed item for `collab_tool_call` thread history entries.
+- `CollabToolCallStatus`: typed status values for collaboration tool calls.
+- `CollabTool`: collaboration tool metadata attached to `CollabToolCallItem`.
+- `CollabAgentStatus`: agent lifecycle status attached to collaboration state updates.
+- `CollabAgentState`: agent metadata/state payload emitted for collaboration items.
 
 <a id="examples"></a>
 ## ![Examples](https://img.shields.io/badge/Examples-Reference%20Scripts-6366f1?style=for-the-badge&logo=python&logoColor=white)
@@ -652,9 +633,8 @@ Example scripts under `examples/`:
 - `hooks_streaming.py`: event hooks for streaming runs.
 - `notify_hook.py`: notify script for CLI callbacks.
 - `pydantic_ai_model_provider.py`: Codex as a PydanticAI model provider.
+- `pydantic_ai_model_provider_streaming.py`: live PydanticAI text streaming over `CodexModel`.
 - `pydantic_ai_handoff.py`: Codex as a PydanticAI tool.
-- `pydantic_ai_run_compat.py`: minimal compatibility harness for `Agent.run(...)`.
-- `pydantic_ai_run_stream_compat.py`: minimal compatibility harness for `Agent.run_stream(...)`.
 
 <a id="sandbox"></a>
 ## ![Sandbox](https://img.shields.io/badge/Sandbox-Permissions%20%26%20Safety-1f2937?style=for-the-badge&logo=gnubash&logoColor=white)
@@ -677,9 +657,6 @@ Additional controls:
 
 This SDK offers two ways to integrate with PydanticAI:
 
-Note: starting in `0.105.0`, `CodexModel` is app-server-only and no longer supports
-the legacy `CodexModel(codex=...)` fallback path.
-
 ### 1) Codex as a PydanticAI model provider
 
 Use `CodexModel` to delegate tool-call planning and text generation to Codex, while PydanticAI executes tools and validates outputs.
@@ -706,21 +683,30 @@ result = agent.run_sync("What's 19 + 23? Use the add tool.")
 print(result.output)
 ```
 
+For live text streaming in a terminal or web UI:
+
+```python
+from pydantic_ai import Agent
+
+from codex_sdk.integrations.pydantic_ai_model import CodexModel
+
+agent = Agent(CodexModel(), output_type=str)
+
+async with agent.run_stream("Explain why the sky is blue.") as result:
+    async for delta in result.stream_text(delta=True, debounce_by=None):
+        print(delta, end="", flush=True)
+```
+
 How it works:
-- `CodexModel` keeps a persistent app-server session and starts/reuses threads based on
-  `thread_reuse_mode` (`"run"` by default, `"always"` optional).
 - `CodexModel` builds a JSON schema envelope with `tool_calls` and `final`.
 - Codex emits tool calls as JSON strings; PydanticAI runs them.
 - If `allow_text_output` is true, Codex can place final text in `final`.
-- Streaming APIs emit incremental events while app-server turn notifications arrive.
-
-Provider options:
-- `performance_profile`: `"balanced"` (default) or `"max"`.
-- `thread_reuse_mode`: `"run"` (default) or `"always"`.
-
-Lifecycle:
-- `CodexModel` owns an app-server client by default; call `await model.close()` in
-  long-lived processes to release resources.
+- This SDK targets the current PydanticAI release line (`>=1.68.0,<2`).
+- `Agent.run_stream()`, `Agent.run_stream_events()`, and `Agent.run_stream_sync()`
+  work with `CodexModel`.
+- Text deltas are forwarded live from agent-message updates when Codex emits them, including
+  envelope-backed `final` text. Tool calls are forwarded as soon as Codex produces a valid
+  envelope update, and `streamed.get()` is reconciled to the canonical final turn result.
 
 Safety defaults (you can override with your own `ThreadOptions`):
 - `sandbox_mode="read-only"`
@@ -783,49 +769,38 @@ If `logfire` is installed and initialized, the SDK emits spans:
 If Logfire is missing or not initialized, the span context manager is a no-op.
 
 <a id="architecture"></a>
+<a id="acheature"></a>
 ## ![Architecture](https://img.shields.io/badge/Architecture-Stack%20map-1f2937?style=for-the-badge&logo=serverless&logoColor=white)
 
-### System components and transport paths
+### System components
 
 ```mermaid
 flowchart LR
   subgraph App[Your Python App]
     U[User Code]
-    T[Codex + Thread API]
-    A[AppServerClient API]
-    PM[PydanticAI CodexModel]
-    PH[PydanticAI codex_handoff_tool]
+    T[Thread API]
   end
 
   subgraph SDK[Codex SDK]
     C[Codex]
     E[CodexExec]
-    P[Thread Event Parser]
-    R[JSON-RPC Client]
+    P[Event Parser]
   end
 
-  subgraph CLI[Codex CLI]
+  subgraph CLI[Bundled Codex CLI]
     X["codex exec --experimental-json"]
-    S["codex app-server"]
   end
 
   FS[(Filesystem)]
   NET[(Network)]
 
   U --> T --> C --> E --> X
-  U --> A --> R --> S
-  U --> PM --> R
-  U --> PH --> C
   X -->|JSONL events| P --> T
-  S -->|JSON-RPC messages| R --> A
-  S -->|JSON-RPC messages| R --> PM
   X --> FS
   X --> NET
-  S --> FS
-  S --> NET
 ```
 
-### Thread API streaming lifecycle (`codex exec`)
+### Streaming event lifecycle
 
 ```mermaid
 sequenceDiagram
@@ -848,41 +823,21 @@ sequenceDiagram
   Thread-->>Dev: turn.completed / turn.failed
 ```
 
-### App-server lifecycle (`codex app-server`)
-
-```mermaid
-sequenceDiagram
-  participant Dev as Developer
-  participant App as AppServerClient
-  participant CLI as codex app-server
-
-  Dev->>App: start()
-  App->>CLI: spawn process
-  App->>CLI: initialize
-  CLI-->>App: initialize result
-  App->>CLI: initialized (notification)
-  Dev->>App: turn_session(thread_id, input)
-  App->>CLI: turn/start
-  CLI-->>App: thread/turn/item notifications
-  CLI-->>App: request (approval needed)
-  App-->>CLI: response (approve/reject)
-  CLI-->>App: turn completed notification
-  App-->>Dev: final turn payload
-```
-
-### PydanticAI model-provider loop (current implementation)
+### PydanticAI model-provider loop
 
 ```mermaid
 sequenceDiagram
   participant Agent as PydanticAI Agent
   participant Model as CodexModel
-  participant App as Codex app-server
+  participant SDK as Codex SDK
+  participant CLI as codex exec
   participant Tools as User Tools
 
   Agent->>Model: request(messages, tools)
-  Model->>App: thread/start (if needed)
-  Model->>App: turn/session(input + output_schema envelope)
-  App-->>Model: item/updated + turn/completed notifications
+  Model->>SDK: start_thread + run_json(prompt, output_schema)
+  SDK->>CLI: codex exec --output-schema
+  CLI-->>SDK: JSON envelope {tool_calls, final}
+  SDK-->>Model: ParsedTurn
   alt tool_calls present
     Model-->>Agent: ToolCallPart(s)
     Agent->>Tools: execute tool(s)
@@ -898,18 +853,12 @@ sequenceDiagram
 flowchart LR
   Agent[PydanticAI Agent] --> Tool[codex_handoff_tool]
   Tool --> SDK[Codex SDK Thread]
-  SDK --> CLI[codex exec]
+  SDK --> CLI[Codex CLI]
   CLI --> SDK
   SDK --> Tool
   Tool --> Agent
 ```
 
-### Streaming semantics summary
-
-- `Thread.run_streamed()` and `Thread.run_streamed_events()` stream incremental `ThreadEvent` values as JSONL lines arrive from `codex exec`.
-- `AppServerClient.notifications()` streams incremental JSON-RPC notifications from `codex app-server`.
-- `CodexModel.request_stream(...)` emits incremental events from app-server turn notifications, with compatibility handling for current and legacy PydanticAI stream interfaces.
-
 <a id="testing"></a>
 ## ![Testing](https://img.shields.io/badge/Testing-Pytest%20%26%20Coverage-2563eb?style=for-the-badge&logo=pytest&logoColor=white)
 
@@ -918,12 +867,9 @@ This repo uses unit tests with mocked CLI processes to keep the test suite fast
 Test focus areas:
 - `tests/test_exec.py`: CLI invocation, environment handling, config flags, abort behavior.
 - `tests/test_thread.py`: parsing, streaming, JSON schema, Pydantic validation, input normalization.
-- `tests/test_app_server.py` and `tests/test_app_server_session.py`: JSON-RPC lifecycle, method wrappers, turn-session approvals/notifications.
 - `tests/test_codex.py`: resume helpers and option wiring.
-- `tests/test_config_overrides.py`: `--config` serialization and merge behavior.
 - `tests/test_abort.py`: abort signal semantics.
 - `tests/test_telemetry.py`: Logfire span behavior.
-- `tests/test_tool_envelope.py`: tool envelope parsing and schema normalization helpers.
 - `tests/test_pydantic_ai_*`: PydanticAI model provider and handoff integration.
 
 ### Run tests
@@ -965,21 +911,10 @@ uv run mypy src
 ## ![CI/CD](https://img.shields.io/badge/CI%2FCD-Overview-1F4B99?style=for-the-badge&logo=gnubash&logoColor=white)
 
 This repository includes GitHub Actions workflows under `.github/workflows/`.
-
-Current workflows:
-- `ci.yml`: lint (`black`, `isort`, `flake8`), type-check (`mypy`), and tests (`pytest --cov=codex_sdk`) on Python 3.10/3.11/3.12.
-- `release.yml`: extracts release notes from `CHANGELOG_SDK.md` and creates a GitHub Release for `vX.Y.Z`.
-- `publish.yml`: builds (`uv build --no-sources`) and publishes to PyPI on release publish (or successful release workflow).
-- `docs-deploy.yml`: optional docs deployment (gated by `DOCS_DEPLOY_ENABLED`).
-- `uv-lock-update.yml`: scheduled weekly lockfile refresh PR.
-
-`ci.yml` test jobs install Node.js and run:
-
-```bash
-python scripts/setup_binary.py
-```
-
-before `pytest`, so test runs do not depend on committed vendor binary updates.
+The CI pipeline runs linting, type checks, and `pytest --cov=codex_sdk`.
+Release automation creates GitHub releases from `CHANGELOG_SDK.md` when you push a
+`vX.Y.Z` tag or manually dispatch the workflow, then the publish workflow uploads
+the package to PyPI on release publish.
 
 <a id="operations"></a>
 ## ![Operations](https://img.shields.io/badge/Operations-Health%20%26%20Sessions-10b981?style=for-the-badge&logo=serverless&logoColor=white)