inspect-codex-app-server 2026.10.29.1__tar.gz

inspect_codex_app_server-2026.10.29.1/.github/workflows/ci.yml

@@ -0,0 +1,196 @@
+name: Compatibility and releases
+
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: '17 * * * *'
+  workflow_dispatch:
+    inputs:
+      release:
+        description: Publish a release even if dependency versions are unchanged
+        type: boolean
+        default: false
+  repository_dispatch:
+    types: [upstream-release]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: compatibility-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  check:
+    name: Check pinned or candidate dependencies
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    outputs:
+      changed: ${{ steps.candidate.outputs.changed }}
+      version: ${{ steps.candidate.outputs.version }}
+      tag: ${{ steps.candidate.outputs.tag }}
+      prerelease: ${{ steps.candidate.outputs.prerelease }}
+      base_sha: ${{ github.sha }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: '3.13'
+      - name: Install locked development dependencies
+        run: uv sync --locked --group dev
+      - name: Prepare dependency updates or a requested release
+        id: candidate
+        if: >-
+          github.ref_name == github.event.repository.default_branch &&
+          (github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' ||
+          github.event_name == 'repository_dispatch')
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_REQUESTED: ${{ github.event_name == 'workflow_dispatch' && inputs.release }}
+        run: |
+          release_args=()
+          if test "$RELEASE_REQUESTED" = true; then
+            release_args+=(--release)
+          fi
+          uv run --no-sync python scripts/update_dependencies.py --output-dir "$RUNNER_TEMP/release" "${release_args[@]}"
+      - name: Lock candidate dependencies and regenerate the native protocol
+        if: steps.candidate.outputs.changed == 'true'
+        run: |
+          uv lock
+          uv sync --locked --group dev
+          uv run --no-sync python scripts/generate_protocol.py
+      - name: Check protocol, lint, and types
+        if: steps.candidate.outputs.changed == 'true' || steps.candidate.outcome == 'skipped'
+        run: |
+          uv run --no-sync python scripts/generate_protocol.py --check
+          uv run --no-sync ruff check .
+          uv run --no-sync ty check
+      - name: Default tests, including the real pinned Codex executable
+        if: steps.candidate.outputs.changed == 'true' || steps.candidate.outcome == 'skipped'
+        run: uv run --no-sync pytest -q --keep-failed-artifacts="$RUNNER_TEMP/failures" --junitxml="$RUNNER_TEMP/default.xml"
+      - name: Prepare Docker acceptance
+        if: steps.candidate.outputs.changed == 'true' || steps.candidate.outcome == 'skipped'
+        run: docker pull python:3.13-slim
+      - name: Docker acceptance
+        if: steps.candidate.outputs.changed == 'true' || steps.candidate.outcome == 'skipped'
+        run: uv run --no-sync pytest -q -m containers --keep-failed-artifacts="$RUNNER_TEMP/failures" --junitxml="$RUNNER_TEMP/containers.xml"
+      - name: Build wheel and source archive
+        if: steps.candidate.outputs.changed == 'true' || steps.candidate.outcome == 'skipped'
+        run: uv build --no-sources --out-dir "$RUNNER_TEMP/release/dist"
+      - name: Save candidate source changes for review or publication
+        if: always() && steps.candidate.outputs.changed == 'true'
+        run: git diff --binary > "$RUNNER_TEMP/release/candidate.patch"
+      - name: Retain passing release candidate
+        if: steps.candidate.outputs.changed == 'true'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: release-candidate
+          path: ${{ runner.temp }}/release
+          if-no-files-found: error
+          retention-days: 14
+      - name: Retain failure diagnostics and candidate changes
+        if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: compatibility-failure
+          include-hidden-files: true
+          path: |
+            ${{ runner.temp }}/failures
+            ${{ runner.temp }}/*.xml
+            ${{ runner.temp }}/release
+          if-no-files-found: ignore
+          retention-days: 7
+
+  record:
+    name: Record tested pins and draft the GitHub release
+    needs: check
+    if: needs.check.outputs.changed == 'true'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.check.outputs.base_sha }}
+          fetch-depth: 0
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
+        with:
+          name: release-candidate
+          path: ${{ runner.temp }}/release
+      - name: Commit and tag exactly the tested source
+        env:
+          RELEASE_VERSION: ${{ needs.check.outputs.version }}
+          RELEASE_TAG: ${{ needs.check.outputs.tag }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          git apply --check "$RUNNER_TEMP/release/candidate.patch"
+          git apply "$RUNNER_TEMP/release/candidate.patch"
+          git add pyproject.toml uv.lock README.md src/inspect_codex_app_server/container.py src/inspect_codex_app_server/_generated_protocol.py src/inspect_codex_app_server/_generated_rpc.py
+          expected_tree=$(git write-tree)
+          if git show-ref --verify --quiet "refs/tags/$RELEASE_TAG"; then
+            # A rerun after a partial publication must reuse the tested tree.
+            test "$(git rev-parse "$RELEASE_TAG^{tree}")" = "$expected_tree"
+          else
+            git config user.name 'github-actions[bot]'
+            git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+            git commit -m "Release inspect-codex-app-server $RELEASE_VERSION"
+            git tag -a "$RELEASE_TAG" -m "Compatibility release $RELEASE_VERSION"
+            # A concurrent default-branch change rejects the entire push.
+            git push --atomic origin "HEAD:refs/heads/$DEFAULT_BRANCH" "refs/tags/$RELEASE_TAG"
+          fi
+      - name: Attach the tested distributions to a draft release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RELEASE_VERSION: ${{ needs.check.outputs.version }}
+          RELEASE_TAG: ${{ needs.check.outputs.tag }}
+          PRERELEASE: ${{ needs.check.outputs.prerelease }}
+        run: |
+          if gh release view "$RELEASE_TAG" --json isDraft > "$RUNNER_TEMP/existing-release.json"; then
+            if jq -e '.isDraft' "$RUNNER_TEMP/existing-release.json"; then
+              gh release upload "$RELEASE_TAG" "$RUNNER_TEMP"/release/dist/* --clobber
+            fi
+          else
+            options=(--verify-tag --draft --title "inspect-codex-app-server $RELEASE_VERSION" --notes-file "$RUNNER_TEMP/release/notes.md")
+            if test "$PRERELEASE" = true; then
+              options+=(--prerelease)
+            fi
+            gh release create "$RELEASE_TAG" "${options[@]}" "$RUNNER_TEMP"/release/dist/*
+          fi
+
+  publish:
+    name: Publish the tested distributions to PyPI
+    needs: record
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
+        with:
+          name: release-candidate
+          path: candidate
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
+        with:
+          packages-dir: candidate/dist
+          skip-existing: true
+
+  release:
+    name: Publish the GitHub release after PyPI succeeds
+    needs: [check, publish]
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - name: Publish the draft
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RELEASE_TAG: ${{ needs.check.outputs.tag }}
+        run: gh release edit "$RELEASE_TAG" --draft=false

inspect_codex_app_server-2026.10.29.1/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+dist/
+logs/

inspect_codex_app_server-2026.10.29.1/AGENTS.md

@@ -0,0 +1,5 @@
+# Inspect Codex package guidance
+
+Follow [TEST_POLICY.md](TEST_POLICY.md) when changing this package or its tests.
+
+Read [technical-notes.md](docs/technical-notes.md) for additional information about how this package works.

inspect_codex_app_server-2026.10.29.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ihor Makhynia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

inspect_codex_app_server-2026.10.29.1/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.5
+Name: inspect-codex-app-server
+Version: 2026.10.29.1
+Summary: Run native Codex app-server sessions in Inspect AI
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: anyio>=4
+Requires-Dist: inspect-ai==0.3.286
+Requires-Dist: pydantic>=2
+Requires-Dist: shortuuid>=1
+Requires-Dist: typing-extensions>=4.12
+Description-Content-Type: text/markdown
+
+# inspect-codex-app-server
+
+An [Inspect AI](https://inspect.aisi.org.uk/) solver and agent that run native Codex sessions inside Docker sandboxes via the Codex App Server JSON-RPC protocol.
+
+Codex manages inference, tool execution, and subagent orchestration, while Inspect AI manages evaluation, scoring, tool governance, and token, message, and time limits. Cost and model-generation turn limits are unsupported.
+
+## Key Features
+
+- **Use Your ChatGPT Subscription**: Run evaluations directly against your ChatGPT subscription plan (or API key) using native Codex authentication.
+- **Docker Sandbox Execution**: Runs Codex as root with full access inside Docker sandboxes, including filesystem tools, bash commands, and subagents.
+- **Inspect Agent**: `codex_agent()` composes with `as_solver()`, `as_tool()`, `handoff()` and `run()`, with react-style `submit`, `attempts`, `on_continue` and `retry_refusals`.
+- **Inspect Tool Bridging**: Exposes Inspect tools (`use_tools`, MCP tool sources) directly to Codex as dynamic tools with validation, approval and review handling.
+- **Inspect Approvals**: Routes Codex's native command and file-change approval requests to the active Inspect approver.
+- **Native Skills, Web Search and Roles**: Installs Inspect skills as Codex skills, sets the native web search mode, and declares agent roles for Codex's child agents.
+- **Operator Interruption and Checkpoints**: Responds to operator interrupts and messages through Inspect's agent channel, and resumes from Inspect checkpoints.
+- **Session & Quota Management**: Handles rate limits, quota pauses (`quota_hold_sec`), transient turn-start retries with backoff, and token budgeting.
+- **Transcript & Usage Tracking**: Reconstructs model activity, tool events, and subagent spans into Inspect transcripts with live metrics.
+- **Evidence & Artifact Capture**: Retains protocol transcripts, session databases, and execution manifests for debugging and auditability.
+
+## Prerequisites & Installation
+
+- Python 3.11+
+- Docker (with Inspect Docker sandbox support)
+- Node.js and npm when a compatible pinned Codex bundle is unavailable.
+
+For an npm-equipped container image, preinstall with
+`RUN npm install -g --prefix /opt/codex @openai/codex@0.165.0` and add
+`/opt/codex/bin` to `PATH`. See [provisioning constraints](docs/technical-notes.md#provisioning-and-authentication).
+
+Install the package:
+
+```bash
+pip install -e .
+```
+
+## Authentication
+
+Run `codex login` on your host and provide its `~/.codex/auth.json`, or select
+another file with `CODEX_AUTH_PATH` / `auth_path`.
+
+Supported authentication modes:
+- `"chatgpt"`: Uses ChatGPT subscription credentials.
+- `"api_key"`: Uses an OpenAI API key.
+- `"existing"`: Uses the container configuration and available credentials without enforcing an authentication mode.
+
+Credentials are copied into `/root/.cache/codex-inspect/auth.json` inside the
+container. See [configuration, credential storage, and logging details](docs/technical-notes.md#provisioning-and-authentication).
+
+## Quickstart
+
+Define a task using `codex_app_server`:
+
+```python
+from pathlib import Path
+from inspect_ai import Task, task
+from inspect_ai.dataset import Sample
+from inspect_ai.scorer import match
+from inspect_codex_app_server import codex_app_server
+
+@task
+def arithmetic():
+    return Task(
+        dataset=[Sample(input="What is 19 + 23? Reply with the number only.", target="42")],
+        solver=codex_app_server(
+            authentication="chatgpt",
+            timeout_sec=600,
+            max_child_agents=1,
+        ),
+        scorer=match(),
+        sandbox=("docker", str(Path(__file__).with_name("compose.yaml"))),
+    )
+```
+
+Run evaluation:
+
+```bash
+inspect eval examples/arithmetic.py --model codex/default
+```
+
+## Inspect Agent
+
+`codex_agent()` runs the same native session as an Inspect agent, so it composes like `react()`:
+
+```python
+from inspect_ai.agent import as_solver, as_tool
+from inspect_codex_app_server import CodexSubagent, codex_agent
+
+coder = codex_agent(
+    name="coder",
+    description="Solves programming tasks in the sandbox.",
+    prompt="Work carefully and verify your answer.",
+    submit=True,          # accept answers from the root submit tool
+    attempts=3,           # score each submission; steer onward when incorrect
+    subagents=[CodexSubagent(name="reviewer", description="Reviews changes.", token_limit=200_000)],
+)
+
+solver = as_solver(coder)   # or as_tool(coder), handoff(coder), run(coder, ...)
+```
+
+See the [Inspect feature mapping](docs/technical-notes.md#inspect-feature-mapping)
+and [model settings and input formats](docs/technical-notes.md#model-settings-and-conversation-input)
+for compatibility details.
+
+### Interruption and checkpoints
+
+Operator interrupts stop native work and wait for follow-up input. Inspect
+checkpoints can resume the root thread; scoring-only resume starts no Codex
+process. See [interruption and resume notes](docs/technical-notes.md#operator-interruption-and-checkpoint-resume).
+
+## Solver Options
+
+The `codex_app_server` solver accepts the following configuration parameters:
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `authentication` | `"existing"` \| `"chatgpt"` \| `"api_key"` | `"existing"` | Required authentication mode. |
+| `timeout_sec` | `float` | `600.0` | Run budget including setup; teardown runs separately. |
+| `max_child_agents` | `int` | `4` | Maximum concurrent subagents per sample. |
+| `developer_instructions` | `str \| None` | `None` | Thread developer instructions. |
+| `base_instructions` | `str \| None` | `None` | Replacement for Codex's base instructions. |
+| `reasoning_effort` | `str \| None` | `None` | Model reasoning effort (defaults to the evaluation's `GenerateConfig`). |
+| `reasoning_summary` | `str \| None` | `None` | Reasoning summary detail (defaults to the evaluation's `GenerateConfig`). |
+| `retry_refusals` | `int \| None` | `None` | Policy-blocked turns to continue before finishing with `content_filter`. |
+| `skills` | `list[str \| Path \| Skill] \| None` | `None` | Inspect skills installed as Codex skills. |
+| `web_search` | `"disabled"` \| `"cached"` \| `"indexed"` \| `"live"` \| `None` | `None` | Native web search mode. |
+| `subagents` | `list[CodexSubagent] \| None` | `None` | Native agent roles for Codex's child agents. |
+| `service_tier` | `str \| None` | `None` | Service tier requested on root turns (e.g. `"priority"`, `"flex"`). |
+| `cwd` | `str` | `"/app"` | Working directory inside the container. |
+| `transport` | `"stdio"` \| `"websocket"` | `"stdio"` | Transport protocol to communicate with the app server. |
+| `policy` | `RunPolicy \| None` | `None` | Custom execution lifecycle and completion policy. |
+| `codex_path` | `str \| None` | `None` | Host binary override (`CODEX_PATH` also works), taking precedence over image reuse. |
+| `auth_path` | `str \| None` | `None` | Explicit path to the host `auth.json`. |
+
+## Custom Lifecycle Policies (`RunPolicy`)
+
+`RunPolicy` configures completion rules, quota waits, setup hooks, and timed
+steering reminders. See the [lifecycle example and limits](docs/technical-notes.md#limits-and-lifecycle-policies).
+
+## Development & Testing
+
+The default suite includes real pinned Codex tests using local scripted model
+responses, without credentials or paid inference. Docker acceptance additionally
+requires a running Docker daemon and `docker pull python:3.13-slim`.
+
+```bash
+# Install development dependencies
+uv sync --group dev
+
+# Run the default suite, including native tests; excludes Docker acceptance
+uv run pytest -q
+
+# Run only tests that launch the real pinned Codex executable
+uv run pytest -q -m native
+
+# Run Docker acceptance separately
+uv run pytest -q -m containers
+
+# Run linter and type checker
+uv run ruff check .
+uv run ty check
+
+# Validate generated JSON-RPC protocol schemas
+uv run python scripts/generate_protocol.py --check
+```
+
+## Automated compatibility releases
+
+The [workflow](.github/workflows/ci.yml) checks pushes and pull requests, and can
+check upstream releases hourly and publish passing candidates to GitHub and
+PyPI. See [release setup, publication, and retry notes](docs/releases.md).
+
+## License
+
+[MIT](LICENSE)

inspect_codex_app_server-2026.10.29.1/README.md

@@ -0,0 +1,174 @@
+# inspect-codex-app-server
+
+An [Inspect AI](https://inspect.aisi.org.uk/) solver and agent that run native Codex sessions inside Docker sandboxes via the Codex App Server JSON-RPC protocol.
+
+Codex manages inference, tool execution, and subagent orchestration, while Inspect AI manages evaluation, scoring, tool governance, and token, message, and time limits. Cost and model-generation turn limits are unsupported.
+
+## Key Features
+
+- **Use Your ChatGPT Subscription**: Run evaluations directly against your ChatGPT subscription plan (or API key) using native Codex authentication.
+- **Docker Sandbox Execution**: Runs Codex as root with full access inside Docker sandboxes, including filesystem tools, bash commands, and subagents.
+- **Inspect Agent**: `codex_agent()` composes with `as_solver()`, `as_tool()`, `handoff()` and `run()`, with react-style `submit`, `attempts`, `on_continue` and `retry_refusals`.
+- **Inspect Tool Bridging**: Exposes Inspect tools (`use_tools`, MCP tool sources) directly to Codex as dynamic tools with validation, approval and review handling.
+- **Inspect Approvals**: Routes Codex's native command and file-change approval requests to the active Inspect approver.
+- **Native Skills, Web Search and Roles**: Installs Inspect skills as Codex skills, sets the native web search mode, and declares agent roles for Codex's child agents.
+- **Operator Interruption and Checkpoints**: Responds to operator interrupts and messages through Inspect's agent channel, and resumes from Inspect checkpoints.
+- **Session & Quota Management**: Handles rate limits, quota pauses (`quota_hold_sec`), transient turn-start retries with backoff, and token budgeting.
+- **Transcript & Usage Tracking**: Reconstructs model activity, tool events, and subagent spans into Inspect transcripts with live metrics.
+- **Evidence & Artifact Capture**: Retains protocol transcripts, session databases, and execution manifests for debugging and auditability.
+
+## Prerequisites & Installation
+
+- Python 3.11+
+- Docker (with Inspect Docker sandbox support)
+- Node.js and npm when a compatible pinned Codex bundle is unavailable.
+
+For an npm-equipped container image, preinstall with
+`RUN npm install -g --prefix /opt/codex @openai/codex@0.165.0` and add
+`/opt/codex/bin` to `PATH`. See [provisioning constraints](docs/technical-notes.md#provisioning-and-authentication).
+
+Install the package:
+
+```bash
+pip install -e .
+```
+
+## Authentication
+
+Run `codex login` on your host and provide its `~/.codex/auth.json`, or select
+another file with `CODEX_AUTH_PATH` / `auth_path`.
+
+Supported authentication modes:
+- `"chatgpt"`: Uses ChatGPT subscription credentials.
+- `"api_key"`: Uses an OpenAI API key.
+- `"existing"`: Uses the container configuration and available credentials without enforcing an authentication mode.
+
+Credentials are copied into `/root/.cache/codex-inspect/auth.json` inside the
+container. See [configuration, credential storage, and logging details](docs/technical-notes.md#provisioning-and-authentication).
+
+## Quickstart
+
+Define a task using `codex_app_server`:
+
+```python
+from pathlib import Path
+from inspect_ai import Task, task
+from inspect_ai.dataset import Sample
+from inspect_ai.scorer import match
+from inspect_codex_app_server import codex_app_server
+
+@task
+def arithmetic():
+    return Task(
+        dataset=[Sample(input="What is 19 + 23? Reply with the number only.", target="42")],
+        solver=codex_app_server(
+            authentication="chatgpt",
+            timeout_sec=600,
+            max_child_agents=1,
+        ),
+        scorer=match(),
+        sandbox=("docker", str(Path(__file__).with_name("compose.yaml"))),
+    )
+```
+
+Run evaluation:
+
+```bash
+inspect eval examples/arithmetic.py --model codex/default
+```
+
+## Inspect Agent
+
+`codex_agent()` runs the same native session as an Inspect agent, so it composes like `react()`:
+
+```python
+from inspect_ai.agent import as_solver, as_tool
+from inspect_codex_app_server import CodexSubagent, codex_agent
+
+coder = codex_agent(
+    name="coder",
+    description="Solves programming tasks in the sandbox.",
+    prompt="Work carefully and verify your answer.",
+    submit=True,          # accept answers from the root submit tool
+    attempts=3,           # score each submission; steer onward when incorrect
+    subagents=[CodexSubagent(name="reviewer", description="Reviews changes.", token_limit=200_000)],
+)
+
+solver = as_solver(coder)   # or as_tool(coder), handoff(coder), run(coder, ...)
+```
+
+See the [Inspect feature mapping](docs/technical-notes.md#inspect-feature-mapping)
+and [model settings and input formats](docs/technical-notes.md#model-settings-and-conversation-input)
+for compatibility details.
+
+### Interruption and checkpoints
+
+Operator interrupts stop native work and wait for follow-up input. Inspect
+checkpoints can resume the root thread; scoring-only resume starts no Codex
+process. See [interruption and resume notes](docs/technical-notes.md#operator-interruption-and-checkpoint-resume).
+
+## Solver Options
+
+The `codex_app_server` solver accepts the following configuration parameters:
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `authentication` | `"existing"` \| `"chatgpt"` \| `"api_key"` | `"existing"` | Required authentication mode. |
+| `timeout_sec` | `float` | `600.0` | Run budget including setup; teardown runs separately. |
+| `max_child_agents` | `int` | `4` | Maximum concurrent subagents per sample. |
+| `developer_instructions` | `str \| None` | `None` | Thread developer instructions. |
+| `base_instructions` | `str \| None` | `None` | Replacement for Codex's base instructions. |
+| `reasoning_effort` | `str \| None` | `None` | Model reasoning effort (defaults to the evaluation's `GenerateConfig`). |
+| `reasoning_summary` | `str \| None` | `None` | Reasoning summary detail (defaults to the evaluation's `GenerateConfig`). |
+| `retry_refusals` | `int \| None` | `None` | Policy-blocked turns to continue before finishing with `content_filter`. |
+| `skills` | `list[str \| Path \| Skill] \| None` | `None` | Inspect skills installed as Codex skills. |
+| `web_search` | `"disabled"` \| `"cached"` \| `"indexed"` \| `"live"` \| `None` | `None` | Native web search mode. |
+| `subagents` | `list[CodexSubagent] \| None` | `None` | Native agent roles for Codex's child agents. |
+| `service_tier` | `str \| None` | `None` | Service tier requested on root turns (e.g. `"priority"`, `"flex"`). |
+| `cwd` | `str` | `"/app"` | Working directory inside the container. |
+| `transport` | `"stdio"` \| `"websocket"` | `"stdio"` | Transport protocol to communicate with the app server. |
+| `policy` | `RunPolicy \| None` | `None` | Custom execution lifecycle and completion policy. |
+| `codex_path` | `str \| None` | `None` | Host binary override (`CODEX_PATH` also works), taking precedence over image reuse. |
+| `auth_path` | `str \| None` | `None` | Explicit path to the host `auth.json`. |
+
+## Custom Lifecycle Policies (`RunPolicy`)
+
+`RunPolicy` configures completion rules, quota waits, setup hooks, and timed
+steering reminders. See the [lifecycle example and limits](docs/technical-notes.md#limits-and-lifecycle-policies).
+
+## Development & Testing
+
+The default suite includes real pinned Codex tests using local scripted model
+responses, without credentials or paid inference. Docker acceptance additionally
+requires a running Docker daemon and `docker pull python:3.13-slim`.
+
+```bash
+# Install development dependencies
+uv sync --group dev
+
+# Run the default suite, including native tests; excludes Docker acceptance
+uv run pytest -q
+
+# Run only tests that launch the real pinned Codex executable
+uv run pytest -q -m native
+
+# Run Docker acceptance separately
+uv run pytest -q -m containers
+
+# Run linter and type checker
+uv run ruff check .
+uv run ty check
+
+# Validate generated JSON-RPC protocol schemas
+uv run python scripts/generate_protocol.py --check
+```
+
+## Automated compatibility releases
+
+The [workflow](.github/workflows/ci.yml) checks pushes and pull requests, and can
+check upstream releases hourly and publish passing candidates to GitHub and
+PyPI. See [release setup, publication, and retry notes](docs/releases.md).
+
+## License
+
+[MIT](LICENSE)

inspect_codex_app_server-2026.10.29.1/TEST_POLICY.md

@@ -0,0 +1,47 @@
+# Package test gates
+
+## Admission
+
+Extend an existing scenario first. Add a case only when it catches a named defect
+existing tests miss, with an independently derived expected result. For regressions,
+verify failure against the broken behavior when practical; report if unverified.
+
+## Required assertions by change
+
+| Changed behavior | Gate |
+| --- | --- |
+| Accounting / evidence | Duplicate wire and rollout records count once; unrelated threads contribute zero. Resume after 25 tokens, consume 5: recorded total 30, newly charged tokens 5. |
+| Completion / errors | Child answers cannot replace the root answer. Provider/transport failures persist as execution errors; refusals and limits retain distinct outcomes. |
+| Interruption | Interrupt active native and bridged work: tools stop before redirect. Operator wait exceeds remaining deadline: redirect still resumes. |
+| Shutdown | Stall a real process, close within a bounded timeout, verify its PID disappears and the final protocol record survives. |
+| Checkpoints | Fresh native home resumes the same thread with history, tools, and accurate usage. Scoring-only resume starts no Codex process. |
+| Native options / RPC | Installed pinned binary demonstrates the new assumption, with valid and invalid controls where applicable. A scripted app-server peer alone is insufficient. |
+
+Preserve or extend the affected row's evidence. Different ordering, ownership,
+or failure mechanisms justify separate cases; different numbers or model labels
+on the same path do not.
+
+## Checks before merge
+
+Run from this package directory:
+
+| Change | Required commands |
+| --- | --- |
+| Code / tests | `uv run pytest -q`; `uv run ruff check .`; `uv run ty check` |
+| Provisioning, transport, lifecycle, checkpoints; every release | Also `uv run pytest -q -m containers` |
+| Codex/Inspect pin, RPC schema, generator | All above plus `uv run python scripts/generate_protocol.py --check`; regenerate bindings |
+| Documentation only | Check changed links and commands |
+
+Default pytest includes native tests and excludes containers. Missing pinned-binary
+or Docker prerequisites must fail visibly. Report required checks left unrun.
+
+## Reject / prune
+
+Remove duplicate helper, forwarding, call-count, source-layout, and presentation
+checks unless they protect a distinct external contract. Keep behavior-preserving
+refactors assertion-neutral. No coverage quotas or mandatory tests per edit.
+
+Peers reject unexpected RPCs and never reproduce adapter accounting/recovery.
+Use real processes/files for lifecycle claims; own temporary homes, logs, tasks,
+and containers. Synchronize on events; bound teardown. No flaky-test retries,
+user-artifact cleanup, live credentials, or paid inference in correctness gates.