codex-app-server-sdk 0.3.2__tar.gz → 0.4.1__tar.gz

codex_app_server_sdk-0.4.1/.github/workflows/ci.yml

@@ -0,0 +1,100 @@
+name: ci
+
+on:
+  pull_request:
+    branches: [main, master]
+  push:
+    branches: [main, master]
+  workflow_call:
+    inputs:
+      base_ref:
+        description: Previous release tag for changed-file quality checks
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+env:
+  CODEX_SDK_LIVE_TESTS: "0"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: actions/setup-python@v7.0.0
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          version: "0.11.18"
+      - run: uv sync --locked --group dev
+      - run: uv run --locked python -m pytest -q
+
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v7.0.0
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          version: "0.11.18"
+      - run: uv sync --locked --group dev
+      - name: Check changed Python files in parallel
+        env:
+          BASE_REF: ${{ inputs.base_ref || github.event.pull_request.base.sha || github.event.before }}
+        run: uv run --locked python scripts/check_quality.py --base "$BASE_REF"
+
+  package:
+    needs: [test, quality]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: actions/setup-python@v7.0.0
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          version: "0.11.18"
+      - run: uv sync --locked --group dev
+      - name: Check documentation
+        run: |
+          uv run --locked python scripts/check_chat_method_links.py
+          uv run --locked zensical build
+      - name: Build and validate distributions
+        run: |
+          uv build --no-sources
+          uv run --locked twine check --strict dist/*
+          uv run --locked python scripts/check_release.py --dist-dir dist
+      - name: Smoke test the installed wheel outside the source environment
+        run: |
+          export EXPECTED_VERSION
+          EXPECTED_VERSION=$(uv version --short)
+          wheels=(dist/*.whl)
+          uv run --isolated --no-project --with "${wheels[0]}" python -I - <<'PY'
+          import os
+          from importlib.metadata import version
+          from importlib.resources import files
+          from codex_app_server_sdk import CodexClient, __version__
+
+          assert __version__ == version("codex-app-server-sdk") == os.environ["EXPECTED_VERSION"]
+          assert files("codex_app_server_sdk").joinpath("py.typed").is_file()
+          assert callable(CodexClient.connect_stdio)
+          PY
+      - name: Reject conflicting artifacts already on PyPI
+        if: startsWith(github.ref, 'refs/tags/')
+        run: uv run --locked python scripts/check_release.py --dist-dir dist --check-pypi
+      - uses: actions/upload-artifact@v7.0.1
+        with:
+          name: dist
+          path: dist/*
+          if-no-files-found: error

{codex_app_server_sdk-0.3.2 → codex_app_server_sdk-0.4.1}/.github/workflows/docs.yml

@@ -12,24 +12,26 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7.0.1
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7.0.0
         with:
           python-version: "3.12"
 
       - name: Setup uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v10.2.0
+        with:
+          version: "0.11.18"
 
       - name: Install dependencies
-        run: uv sync --group dev
+        run: uv sync --locked --group dev
 
       - name: Check method links
-        run: uv run python scripts/check_chat_method_links.py
+        run: uv run --locked python scripts/check_chat_method_links.py
 
       - name: Build docs
-        run: uv run zensical build
+        run: uv run --locked zensical build
 
       - name: Link check
         uses: lycheeverse/lychee-action@v2
@@ -58,21 +60,23 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7.0.1
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7.0.0
         with:
           python-version: "3.12"
 
       - name: Setup uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v10.2.0
+        with:
+          version: "0.11.18"
 
       - name: Install dependencies
-        run: uv sync --group dev
+        run: uv sync --locked --group dev
 
       - name: Build docs
-        run: uv run zensical build
+        run: uv run --locked zensical build
 
       - name: Configure Pages
         uses: actions/configure-pages@v5

codex_app_server_sdk-0.4.1/.github/workflows/publish.yml

@@ -0,0 +1,110 @@
+name: publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.release.outputs.version }}
+      base_ref: ${{ steps.release.outputs.base_ref }}
+      prerelease: ${{ steps.release.outputs.prerelease }}
+    steps:
+      - name: Require a tag, including for manual runs
+        env:
+          REF_TYPE: ${{ github.ref_type }}
+        run: test "$REF_TYPE" = tag
+      - uses: actions/checkout@v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v7.0.0
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          version: "0.11.18"
+      - run: uv sync --locked --group dev
+      - name: Validate version, tag commit, and release notes
+        id: release
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: >-
+          uv run --locked python scripts/check_release.py
+          --tag "$RELEASE_TAG" --require-tag
+          --notes-file release-notes.md --github-output "$GITHUB_OUTPUT"
+      - uses: actions/upload-artifact@v7.0.1
+        with:
+          name: release-notes
+          path: release-notes.md
+          if-no-files-found: error
+
+  checks:
+    needs: validate
+    uses: ./.github/workflows/ci.yml
+    with:
+      base_ref: ${{ needs.validate.outputs.base_ref }}
+
+  publish:
+    needs: checks
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/codex-app-server-sdk
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8.0.1
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # The package job first rejects same-name files with different hashes.
+          skip-existing: true
+
+  github-release:
+    needs: [validate, publish]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      GH_TOKEN: ${{ github.token }}
+      GH_REPO: ${{ github.repository }}
+      RELEASE_TAG: ${{ github.ref_name }}
+      PRERELEASE: ${{ needs.validate.outputs.prerelease }}
+    steps:
+      - uses: actions/download-artifact@v8.0.1
+        with:
+          name: dist
+          path: dist
+      - uses: actions/download-artifact@v8.0.1
+        with:
+          name: release-notes
+      - name: Publish release notes and the exact PyPI artifacts
+        run: |
+          if draft_status=$(gh release view "$RELEASE_TAG" --json isDraft --jq .isDraft 2>/dev/null); then
+            if [ "$draft_status" = false ]; then
+              echo "GitHub Release already published: $RELEASE_TAG"
+              exit 0
+            fi
+          else
+            gh release create "$RELEASE_TAG" --verify-tag --draft \
+              --title "$RELEASE_TAG" --notes-file release-notes.md
+          fi
+          gh release upload "$RELEASE_TAG" dist/* --clobber
+          gh release edit "$RELEASE_TAG" --draft=false \
+            --prerelease="$PRERELEASE" --notes-file release-notes.md

codex_app_server_sdk-0.4.1/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+Version headings identify prepared releases. Publication dates and artifacts
+are recorded in GitHub Releases and PyPI.
+
+## 0.4.1
+
+### Fixed
+
+- Convert the README's relative changelog and release-procedure links to
+  version-tagged GitHub URLs when building the PyPI description. The source
+  README keeps its relative links.
+
+### Compatibility
+
+- Packaging/documentation patch; the SDK API and behavior are unchanged from 0.4.0.
+  The 0.4.0 migration requirements below still apply.
+- Source builds now use `hatch-fancy-pypi-readme` as a build dependency. Isolated
+  builds install it automatically; builds without isolation must provide it.
+  Wheel runtime dependencies are unchanged.
+
+## 0.4.0
+
+### Compatibility and required migration
+
+**This release is not a drop-in behavior-compatible upgrade from 0.3.2.**
+Read the [complete migration guide](https://emsi.github.io/codex-app-server-sdk/migration-0.4.0/)
+before deploying an existing application. Existing public methods and imports
+remain available, but callers may need the following changes:
+
+- **Manual approvals:** set `approval_mode="manual"` when responding through
+  `approval_requests()` without a callback. Previously, these responses raced
+  automatic decline. The default still declines without a handler; a callback
+  handles requests in either mode. Consuming the stream does not select manual
+  mode. Late, duplicate, server-resolved, or mismatched approval responses now
+  fail stricter pending-request checks.
+- **Unsuccessful turns:** both conversation APIs raise `CodexProtocolError`
+  for failed/interrupted terminal statuses, even after partial output. A stream
+  can yield steps before raising; partial assistant text is not proof of success.
+- **Cancellation errors and ownership:** `cancel()` propagates interrupt RPC,
+  request-timeout, and transport failures. Missing terminal confirmation raises
+  `CodexTurnInactiveError` with the original continuation and cursor. It rejects
+  tokens for turns no longer retained by the same client, including repeated
+  cancellation after cleanup. Retain tokens on errors, but do not assume a
+  failed transport remains usable.
+- **Cancellation results:** `was_interrupted` requires confirmed interruption;
+  `was_completed` means successful completion. Both can be false for a failed
+  terminal turn. An interrupt acknowledgement alone is not confirmation.
+- **Low-level interruption:** pass `thread_id` to `interrupt_turn()` for turns
+  the SDK does not track. Missing or conflicting thread IDs raise `ValueError`.
+- **Initialization:** the first successful call is cached. Later `initialize()`
+  calls return the same result and ignore new parameters/timeouts. Supply custom
+  settings before implicit initialization. Custom servers and tests must accept
+  the new `initialized` notification and the installed SDK version in default
+  `clientInfo.version`, replacing the hardcoded `0.1.0`.
+- **Unanswered user questions:** `item/tool/requestUserInput` now waits up to
+  300 seconds without a callback or manual response, instead of immediately
+  returning unsupported-method error `-32601`. The default 180-second turn
+  inactivity timeout can fire first. Unattended clients can set
+  `user_input_response_timeout=0.0` for a prompt error response (`-32000`, not
+  the old code); manual UIs may use `None` with an active response loop.
+- **Events and transports:** routing uses explicit turn/thread identifiers,
+  not arbitrary nested content. Ambiguous terminal events no longer complete
+  arbitrary turns. Raw event counts/timing can change; all waiting consumers
+  now receive connection failures. Custom transports and fixtures may need
+  updated envelopes and handshake expectations.
+- **Installation and model shape:** package imports require installed
+  distribution metadata; use `uv sync` or an editable/wheel install rather
+  than copying source alone. `TurnOverrides` adds a field, affecting fixed
+  dataclass snapshots and tuple unpacking. Python and runtime dependency
+  requirements are unchanged.
+
+### Added
+
+- Collaboration mode configuration (`default` and `plan`) through turn overrides.
+- Human input requests, typed answers, callbacks, and manual response streams.
+- Explicit `approval_mode="manual"` for applications that collect approval
+  decisions from a person or UI.
+- Public `__version__`, read from installed package metadata and used in the
+  app-server initialization handshake.
+- Release validation shared with PR CI: Python 3.12–3.14 tests, changed-file
+  quality checks, package checks, and an isolated wheel import.
+- Automated GitHub Releases with changelog notes and the same artifacts as
+  PyPI, with version/tag checks and recovery for interrupted uploads.
+
+### Fixed
+
+- Concurrent turns receive their own notifications, including events that
+  arrive before the turn-start response. Connection failures wake all waiters.
+- Concurrent first calls initialize the connection once and send `initialized`.
+- Failed and interrupted turns raise `CodexProtocolError` from both conversation
+  APIs, including when partial assistant text has already arrived.
+- Interrupt requests include both thread and turn identifiers. Cancellation
+  retains continuations on errors or timeouts and cleans up after confirmation.
+- Approval responses reject duplicate or already-resolved requests.
+- Update release tooling to validate current Hatchling's core metadata 2.5.
+- Make basedpyright warnings non-fatal consistently in local and GitHub
+  Actions checks; type errors remain a release gate.
+
+### Validation
+
+- Added deterministic regression tests and an opt-in live smoke test using
+  only `gpt-6-luna`. Concurrent turns and cancellation were tested with Codex
+  CLI 0.156.1; this does not imply complete coverage of its protocol.

{codex_app_server_sdk-0.3.2 → codex_app_server_sdk-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: codex-app-server-sdk
-Version: 0.3.2
+Version: 0.4.1
 Summary: Async Python client for Codex app-server over stdio and websocket.
 Project-URL: Documentation, https://emsi.github.io/codex-app-server-sdk/
 Project-URL: Repository, https://github.com/emsi/codex-app-server-sdk
@@ -674,6 +674,7 @@ Classifier: License :: OSI Approved :: GNU Affero General Public License v3
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: pydantic>=2.8.0
@@ -682,7 +683,7 @@ Provides-Extra: dev
 Requires-Dist: build>=1.2.2; extra == 'dev'
 Requires-Dist: mkdocstrings-python>=1.18.2; extra == 'dev'
 Requires-Dist: pytest>=8.2.0; extra == 'dev'
-Requires-Dist: twine>=6.0.1; extra == 'dev'
+Requires-Dist: twine>=7.0.0; extra == 'dev'
 Requires-Dist: zensical>=0.0.23; extra == 'dev'
 Description-Content-Type: text/markdown
 
@@ -694,6 +695,13 @@ It gives you a convenient conversation API over `stdio` or `websocket` without h
 
 Documentation: https://emsi.github.io/codex-app-server-sdk/
 
+> **Upgrading to 0.4.0? Behavior changes require review.** Read the
+> [0.3.2 → 0.4.0 migration guide](https://emsi.github.io/codex-app-server-sdk/migration-0.4.0/)
+> before upgrading.
+> Stream-based approval responders must set `approval_mode="manual"`.
+> Failed/interrupted turns now raise; cancellation, initialization, unanswered
+> user questions, and custom transport expectations also change.
+
 ## Highlights
 
 - simple one-shot turns with `chat_once(...)`
@@ -702,8 +710,46 @@ Documentation: https://emsi.github.io/codex-app-server-sdk/
 - thread-scoped config + forking via `ThreadHandle`
 - inactivity timeout continuation for long-running turns
 - turn cancellation with unread-step/event drain via `cancel(...)`
+- collaboration mode overrides (`default`/`plan`) via `TurnOverrides`
+- human-in-the-loop user input handling (`item/tool/requestUserInput`)
 - optional low-level `request(...)` access when needed
 
+## Why use this client?
+
+Protocol I/O and callbacks run directly on your application's `asyncio` event
+loop, using asynchronous subprocess pipes or WebSockets. Thread handles share
+one connection, and approvals can integrate with an async callback or a manual
+UI response loop.
+
+You control the Codex runtime: launch your chosen executable or connect to an
+existing WebSocket server. The conversation API adds completed-step streaming,
+resumable inactivity timeouts, and cancellation with unread-event recovery.
+The `Transport` interface and raw `request(...)` method remain available for
+application-specific integrations.
+
+### Compared with `openai-codex`
+
+Both libraries use the Codex app-server protocol. Their integration choices differ:
+
+| Area | `codex-app-server-sdk` | `openai-codex` |
+| --- | --- | --- |
+| Execution | Native `asyncio` client; asynchronous protocol I/O on your event loop | Synchronous client with an async wrapper that offloads blocking operations to background threads |
+| Transport | Public, replaceable `Transport`; built-in stdio and WebSocket support | SDK-managed subprocess communicating through line-delimited JSON over stdio |
+| Protocol access | Flexible dictionary-based RPC via `request(...)`, plus high-level conversation models | Extensive generated types, typed responses, and typed notifications |
+| Runtime management | You supply and manage Codex; choose an executable or connect to an existing WebSocket server | Installs an exactly pinned Codex runtime dependency by default |
+
+This client fits applications that need native async I/O, custom transports,
+connections to an existing server, or independent control over runtime upgrades.
+The official SDK offers broader generated type coverage and a reproducible
+runtime default. You are responsible for installing and updating Codex when
+using this client.
+
+Comparison verified against the published
+[`openai-codex` 0.156.1](https://pypi.org/project/openai-codex/0.156.1/)
+source and package metadata on 2026-09-23. The official SDK also supports a
+[`CodexConfig(codex_bin=...)` override](https://learn.chatgpt.com/docs/codex-sdk)
+for selecting a different local executable.
+
 ## Install
 
 Install `uv` (if needed):
@@ -728,6 +774,10 @@ uv pip install codex-app-server-sdk
 
 - Docs site: https://emsi.github.io/codex-app-server-sdk/
 - PyPI: https://pypi.org/project/codex-app-server-sdk/
+- Human-in-the-loop guide: https://emsi.github.io/codex-app-server-sdk/human-in-the-loop/
+- Release procedure: [RELEASE.md](https://github.com/emsi/codex-app-server-sdk/blob/v0.4.1/RELEASE.md)
+- Upgrading from 0.3.2: [0.4.0 migration guide](https://emsi.github.io/codex-app-server-sdk/migration-0.4.0/)
+- Release notes and migration guidance: [CHANGELOG.md](https://github.com/emsi/codex-app-server-sdk/blob/v0.4.1/CHANGELOG.md)
 
 ## Quick start
 
@@ -1083,13 +1133,13 @@ uv run python examples/chat_session_websocket.py
 - `compact_thread(thread_id)`: request context compaction.
 - `chat(...)` (`text=None, thread_id=None, user=None, metadata=None, thread_config=None, turn_overrides=None, inactivity_timeout=None, continuation=None`): async iterator yielding completed non-delta step blocks.
 - `chat_once(...)` (`text=None, thread_id=None, user=None, metadata=None, thread_config=None, turn_overrides=None, inactivity_timeout=None, continuation=None`): send one user message and wait for completed turn.
-- `cancel(continuation, timeout=None)`: interrupt running turn, return unread steps/events, and clean turn state.
+- `cancel(continuation, timeout=None)`: interrupt a turn and return unread steps/events after terminal confirmation; retain the continuation if cancellation fails or times out.
 - `steer_turn(thread_id=..., expected_turn_id=..., input_items=...)`: steer active turn input.
 - `start_review(thread_id=..., target=..., delivery=None)`: run review mode.
 - `list_models(...)`: discover available models.
 - `exec_command(command, ...)`: run one command via server command API.
 - `read_config(...)`, `read_config_requirements()`, `write_config_value(...)`, `batch_write_config(...)`: config APIs.
-- `interrupt_turn(turn_id, timeout=None)`: low-level turn interruption request.
+- `interrupt_turn(turn_id, thread_id=None, timeout=None)`: low-level interruption request; infer the thread for tracked turns or pass it explicitly.
 - `close()`: cancel receive loop and close transport.
 
 ### `Transport` and implementations (`src/codex_app_server_sdk/transport.py`)
@@ -1138,7 +1188,9 @@ uv run python examples/chat_session_websocket.py
 - `chat_once(...)` resolves final text from completed `agentMessage` items (`item/completed`), with `thread/read(includeTurns=true)` fallback.
 - `turn_timeout` is intentionally removed to avoid conflicting timeout semantics.
 - Turn waits are controlled by `inactivity_timeout` (or unbounded when `None`).
-- `cancel(...)` interrupts a continuation turn, returns unread buffered data, and cleans internal session state so the same thread can be reused safely.
+- `cancel(...)` releases turn state only after a terminal event. RPC failures propagate; a confirmation timeout raises `CodexTurnInactiveError` with the original continuation.
+- Failed or interrupted turns raise `CodexProtocolError` from both chat APIs, even if partial assistant text was received.
+- Use `approval_mode="manual"` on either connection factory to answer `approval_requests()` yourself. Without a callback, the default `"auto"` mode declines requests.
 - Advanced thread-level config/fork uses protocol v2 methods (`thread/start`, `thread/resume`, `thread/fork`) exposed via `ThreadHandle` and `ThreadConfig`.
 - `metadata` is applied on `turn/start` payloads for message turns; thread-level config uses schema-aligned fields on thread methods.
 - preferred lifecycle is `async with CodexClient.connect_*() as client:`; manual `start()/close()` remains available for advanced control.
@@ -1157,14 +1209,16 @@ uv run python examples/chat_session_websocket.py
 
 ### Default initialize payload
 
-When `params=None`, the client sends:
+When `params=None`, the client sends the following payload. The version
+placeholder is replaced with the installed package version, also available as
+`codex_app_server_sdk.__version__`:
 
 ```json
 {
   "protocolVersion": "1",
   "clientInfo": {
     "name": "codex-app-server-sdk",
-    "version": "0.1.0"
+    "version": "<installed SDK version>"
   },
   "capabilities": {
     "optOutNotificationMethods": [
@@ -1206,6 +1260,9 @@ Merge rules:
 
 ### Example: explicit initialize
 
+The custom `clientInfo.version` below identifies your application, independently
+of the SDK version.
+
 ```python
 import asyncio
 from codex_app_server_sdk import CodexClient

{codex_app_server_sdk-0.3.2 → codex_app_server_sdk-0.4.1}/README.md

@@ -6,6 +6,13 @@ It gives you a convenient conversation API over `stdio` or `websocket` without h
 
 Documentation: https://emsi.github.io/codex-app-server-sdk/
 
+> **Upgrading to 0.4.0? Behavior changes require review.** Read the
+> [0.3.2 → 0.4.0 migration guide](https://emsi.github.io/codex-app-server-sdk/migration-0.4.0/)
+> before upgrading.
+> Stream-based approval responders must set `approval_mode="manual"`.
+> Failed/interrupted turns now raise; cancellation, initialization, unanswered
+> user questions, and custom transport expectations also change.
+
 ## Highlights
 
 - simple one-shot turns with `chat_once(...)`
@@ -14,8 +21,46 @@ Documentation: https://emsi.github.io/codex-app-server-sdk/
 - thread-scoped config + forking via `ThreadHandle`
 - inactivity timeout continuation for long-running turns
 - turn cancellation with unread-step/event drain via `cancel(...)`
+- collaboration mode overrides (`default`/`plan`) via `TurnOverrides`
+- human-in-the-loop user input handling (`item/tool/requestUserInput`)
 - optional low-level `request(...)` access when needed
 
+## Why use this client?
+
+Protocol I/O and callbacks run directly on your application's `asyncio` event
+loop, using asynchronous subprocess pipes or WebSockets. Thread handles share
+one connection, and approvals can integrate with an async callback or a manual
+UI response loop.
+
+You control the Codex runtime: launch your chosen executable or connect to an
+existing WebSocket server. The conversation API adds completed-step streaming,
+resumable inactivity timeouts, and cancellation with unread-event recovery.
+The `Transport` interface and raw `request(...)` method remain available for
+application-specific integrations.
+
+### Compared with `openai-codex`
+
+Both libraries use the Codex app-server protocol. Their integration choices differ:
+
+| Area | `codex-app-server-sdk` | `openai-codex` |
+| --- | --- | --- |
+| Execution | Native `asyncio` client; asynchronous protocol I/O on your event loop | Synchronous client with an async wrapper that offloads blocking operations to background threads |
+| Transport | Public, replaceable `Transport`; built-in stdio and WebSocket support | SDK-managed subprocess communicating through line-delimited JSON over stdio |
+| Protocol access | Flexible dictionary-based RPC via `request(...)`, plus high-level conversation models | Extensive generated types, typed responses, and typed notifications |
+| Runtime management | You supply and manage Codex; choose an executable or connect to an existing WebSocket server | Installs an exactly pinned Codex runtime dependency by default |
+
+This client fits applications that need native async I/O, custom transports,
+connections to an existing server, or independent control over runtime upgrades.
+The official SDK offers broader generated type coverage and a reproducible
+runtime default. You are responsible for installing and updating Codex when
+using this client.
+
+Comparison verified against the published
+[`openai-codex` 0.156.1](https://pypi.org/project/openai-codex/0.156.1/)
+source and package metadata on 2026-09-23. The official SDK also supports a
+[`CodexConfig(codex_bin=...)` override](https://learn.chatgpt.com/docs/codex-sdk)
+for selecting a different local executable.
+
 ## Install
 
 Install `uv` (if needed):
@@ -40,6 +85,10 @@ uv pip install codex-app-server-sdk
 
 - Docs site: https://emsi.github.io/codex-app-server-sdk/
 - PyPI: https://pypi.org/project/codex-app-server-sdk/
+- Human-in-the-loop guide: https://emsi.github.io/codex-app-server-sdk/human-in-the-loop/
+- Release procedure: [RELEASE.md](RELEASE.md)
+- Upgrading from 0.3.2: [0.4.0 migration guide](https://emsi.github.io/codex-app-server-sdk/migration-0.4.0/)
+- Release notes and migration guidance: [CHANGELOG.md](CHANGELOG.md)
 
 ## Quick start
 
@@ -395,13 +444,13 @@ uv run python examples/chat_session_websocket.py
 - `compact_thread(thread_id)`: request context compaction.
 - `chat(...)` (`text=None, thread_id=None, user=None, metadata=None, thread_config=None, turn_overrides=None, inactivity_timeout=None, continuation=None`): async iterator yielding completed non-delta step blocks.
 - `chat_once(...)` (`text=None, thread_id=None, user=None, metadata=None, thread_config=None, turn_overrides=None, inactivity_timeout=None, continuation=None`): send one user message and wait for completed turn.
-- `cancel(continuation, timeout=None)`: interrupt running turn, return unread steps/events, and clean turn state.
+- `cancel(continuation, timeout=None)`: interrupt a turn and return unread steps/events after terminal confirmation; retain the continuation if cancellation fails or times out.
 - `steer_turn(thread_id=..., expected_turn_id=..., input_items=...)`: steer active turn input.
 - `start_review(thread_id=..., target=..., delivery=None)`: run review mode.
 - `list_models(...)`: discover available models.
 - `exec_command(command, ...)`: run one command via server command API.
 - `read_config(...)`, `read_config_requirements()`, `write_config_value(...)`, `batch_write_config(...)`: config APIs.
-- `interrupt_turn(turn_id, timeout=None)`: low-level turn interruption request.
+- `interrupt_turn(turn_id, thread_id=None, timeout=None)`: low-level interruption request; infer the thread for tracked turns or pass it explicitly.
 - `close()`: cancel receive loop and close transport.
 
 ### `Transport` and implementations (`src/codex_app_server_sdk/transport.py`)
@@ -450,7 +499,9 @@ uv run python examples/chat_session_websocket.py
 - `chat_once(...)` resolves final text from completed `agentMessage` items (`item/completed`), with `thread/read(includeTurns=true)` fallback.
 - `turn_timeout` is intentionally removed to avoid conflicting timeout semantics.
 - Turn waits are controlled by `inactivity_timeout` (or unbounded when `None`).
-- `cancel(...)` interrupts a continuation turn, returns unread buffered data, and cleans internal session state so the same thread can be reused safely.
+- `cancel(...)` releases turn state only after a terminal event. RPC failures propagate; a confirmation timeout raises `CodexTurnInactiveError` with the original continuation.
+- Failed or interrupted turns raise `CodexProtocolError` from both chat APIs, even if partial assistant text was received.
+- Use `approval_mode="manual"` on either connection factory to answer `approval_requests()` yourself. Without a callback, the default `"auto"` mode declines requests.
 - Advanced thread-level config/fork uses protocol v2 methods (`thread/start`, `thread/resume`, `thread/fork`) exposed via `ThreadHandle` and `ThreadConfig`.
 - `metadata` is applied on `turn/start` payloads for message turns; thread-level config uses schema-aligned fields on thread methods.
 - preferred lifecycle is `async with CodexClient.connect_*() as client:`; manual `start()/close()` remains available for advanced control.
@@ -469,14 +520,16 @@ uv run python examples/chat_session_websocket.py
 
 ### Default initialize payload
 
-When `params=None`, the client sends:
+When `params=None`, the client sends the following payload. The version
+placeholder is replaced with the installed package version, also available as
+`codex_app_server_sdk.__version__`:
 
 ```json
 {
   "protocolVersion": "1",
   "clientInfo": {
     "name": "codex-app-server-sdk",
-    "version": "0.1.0"
+    "version": "<installed SDK version>"
   },
   "capabilities": {
     "optOutNotificationMethods": [
@@ -518,6 +571,9 @@ Merge rules:
 
 ### Example: explicit initialize
 
+The custom `clientInfo.version` below identifies your application, independently
+of the SDK version.
+
 ```python
 import asyncio
 from codex_app_server_sdk import CodexClient

codex_app_server_sdk-0.4.1/RELEASE.md

@@ -0,0 +1,9 @@
+# Releasing codex-app-server-sdk
+
+The maintained procedure is in [the release guide](docs/releasing.md), also
+published on the [documentation site](https://emsi.github.io/codex-app-server-sdk/releasing/).
+
+Prepare the version and changelog locally, then push the reviewed version tag.
+GitHub Actions validates, builds, publishes to PyPI, and creates a GitHub Release
+with the same distributions. Do not manually upload packages before pushing the
+tag: the tag already triggers publication.