Merge pull request #6 from ebarti/fix/v0.1.1-code-review-findings

fix: address v0.1.0 code-review findings, prepare v0.1.1

Author: ebarti

.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }}, ${{ matrix.extras }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        extras: [core, all]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: |
+          if [ "${{ matrix.extras }}" = "all" ]; then
+            uv sync --all-extras
+          else
+            uv sync
+          fi
+
+      - name: Ruff
+        run: uv run ruff check .
+
+      - name: Mypy
+        run: uv run mypy
+
+      - name: Pytest
+        run: uv run pytest -q

.github/workflows/publish-pypi.yml

@@ -18,8 +18,51 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
+  test:
+    name: test (py${{ matrix.python-version }}, ${{ matrix.extras }})
+    runs-on: ubuntu-latest
+    env:
+      RELEASE_TAG: ${{ github.event_name == 'release' && github.event.release.tag_name || inputs.tag }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: "3.10"
+            extras: core
+          - python-version: "3.13"
+            extras: all
+
+    steps:
+      - name: Check out release tag
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ env.RELEASE_TAG }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: |
+          if [ "${{ matrix.extras }}" = "all" ]; then
+            uv sync --all-extras
+          else
+            uv sync
+          fi
+
+      - name: Ruff
+        run: uv run ruff check .
+
+      - name: Mypy
+        run: uv run mypy
+
+      - name: Pytest
+        run: uv run pytest -q
+
   build:
     name: Build distributions
+    needs: test
     runs-on: ubuntu-latest
     env:
       RELEASE_TAG: ${{ github.event_name == 'release' && github.event.release.tag_name || inputs.tag }}

CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.1.1 - 2026-06-11
+
+### Fixed
+
+- **Codex approval-mode mapping was inverted** and is now corrected. `STRICT` and
+  `CAUTIOUS` map to `deny_all` (never escalate beyond the sandbox); `DEFAULT` and
+  `PERMISSIVE` map to `auto_review` (escalations are auto-adjudicated). Previously a
+  `STRICT` caller could have escalations auto-approved and a `PERMISSIVE` caller had
+  them hard-denied — exactly backwards.
+- Antigravity MCP stdio server configuration no longer crashes: the required `name`
+  field is now passed to the SDK model.
+- The `mypy` strict gate now passes identically in core-only and all-extras
+  environments (per-module import overrides replace inline ignores).
+- Claude reports `finish_reason="max_turns"` when a turn is truncated by the
+  max-turns limit instead of a generic failure.
+- Codex honors `TurnResult.status`: a `failed` or `interrupted` turn maps to the
+  matching `finish_reason` and surfaces the structured error message instead of being
+  reported as success.
+
+### Changed
+
+- **Antigravity DEFAULT permission posture is now safer.** With no `allowed_tools`,
+  `DEFAULT` (and `CAUTIOUS`) now use the nondestructive toolset (no `run_command`)
+  instead of granting all tools plus an allow-all policy. `STRICT` (or any read-only
+  filesystem) uses the read-only toolset with no `allow_all` policy; `PERMISSIVE`
+  keeps all tools.
+- **Unsupported task fields now raise `UnsupportedTaskInputError` instead of being
+  silently ignored.** Codex rejects `allowed_tools`, `disallowed_tools`, `budget_usd`,
+  and `permissions.network` (MCP was already rejected); Antigravity rejects
+  `budget_usd` and `permissions.network`, and rejects combining an allow-list with a
+  deny-list (the SDK requires them to be mutually exclusive); Claude rejects
+  `permissions.network`. Only Claude maps `budget_usd`.
+- Missing-SDK and missing-credential paths now raise the typed
+  `AgentRuntimeUnavailableError` instead of a bare `RuntimeError`.
+- Antigravity session and app-data storage moved from a world-shared
+  `/tmp/agent-runtime-kit` path to `$XDG_CACHE_HOME/agent-runtime-kit` (default
+  `~/.cache/agent-runtime-kit`, created `0o700`), overridable via
+  `AntigravityAgentRuntime(data_dir=...)`. Sessions now survive reboots and are not
+  exposed to other users on multi-user machines.
+- Antigravity maps `disallowed_tools` to `CapabilitiesConfig.disabled_tools` and
+  validates tool names against the `BuiltinTools` enum, raising a typed error for an
+  unknown name instead of leaking a raw validation error.
+- Build now requires `hatchling>=1.26` (for the PEP 639 `license = "MIT"` string),
+  and the deprecated `License :: OSI Approved :: MIT License` classifier was removed.
+
+### Added
+
+- Claude streaming is now real: incremental output deltas and
+  `tool_requested`/`tool_completed` events are emitted while the SDK runs.
+- Codex tool audits are now produced, parsed from `TurnResult.items` (command
+  executions, MCP tool calls, dynamic tool calls, and web searches).
+- Claude records vendor-option kwargs it had to drop due to SDK drift in
+  `AgentResult.metadata["dropped_options"]`, keeping silent omissions observable.
+- A continuous-integration workflow runs `ruff`, `mypy`, and `pytest` across
+  Python 3.10–3.13 in both the core-only and all-extras dependency lanes, and the
+  PyPI publish workflow now gates on a test job before building.
+- `tests/test_sdk_contract.py` introspects the real vendor SDK surfaces and
+  auto-skips when the SDKs are not installed.
+- An sdist allowlist ensures only `src`, `tests`, `docs`, `examples`, `README.md`,
+  `LICENSE`, and `pyproject.toml` are packaged for PyPI (internal planning
+  artifacts, `uv.lock`, and caches are no longer shipped).
+
+## 0.1.0
+
+- Initial release: one typed async runtime API for the Claude, Codex, and
+  Antigravity agent SDKs, with capability diagnostics, event sinks, and adapters.

README.md

@@ -70,16 +70,18 @@ asyncio.run(main())
 
 `AgentTask` supports goal, system prompt, working directory, permission profile,
 MCP stdio servers, session/resume handles, output schema, budget, metadata, and
-an async event sink.
+an async event sink. Where a runtime cannot honor a field (for example only
+Claude maps `budget_usd`; Codex and Antigravity reject it with a typed
+`UnsupportedTaskInputError`) the adapter raises rather than silently dropping it.
 
 `AgentResult` returns output, finish reason, parsed structured output, usage,
 cost, session id, artifacts, tool-call audits, and provider metadata.
 
 ## Docs
 
-- [Quickstart](docs/quickstart.md)
-- [Provider diagnostics](docs/providers.md)
-- [Capability matrix](docs/capability-matrix.md)
-- [Live smoke tests](docs/live-smoke.md)
-- [Mestre migration notes](docs/mestre-migration.md)
-- [Publish checklist](docs/publish-checklist.md)
+- [Quickstart](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/quickstart.md)
+- [Provider diagnostics](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/providers.md)
+- [Capability matrix](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/capability-matrix.md)
+- [Live smoke tests](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/live-smoke.md)
+- [Mestre migration notes](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/mestre-migration.md)
+- [Publish checklist](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/publish-checklist.md)

docs/capability-matrix.md

@@ -9,11 +9,64 @@
 | Structured output | Native `output_format` when available | Native output schema / JSON parse fallback | Native response schema / JSON parse fallback |
 | MCP stdio servers | Yes | No per-task MCP config | Yes, without per-server env |
 | Permission mapping | `permission_mode` | approval mode + sandbox | capabilities + policies |
-| Streaming output events | From streamed SDK messages | Not enabled in v1 adapter | From response chunks |
-| Tool audit events | Best effort from message content | Best effort from result surface | From tool chunks |
-| Missing package diagnostics | Yes | Yes | Yes |
+| Streaming output events | Yes — incremental output/tool events while the SDK runs | Not enabled in v1 adapter | Yes — from response chunks |
+| Tool audit events | Yes — from streamed message blocks | Yes — parsed from `TurnResult` items | Yes — from tool chunks |
+| Missing package diagnostics | Yes (`AgentRuntimeUnavailableError`) | Yes (`AgentRuntimeUnavailableError`) | Yes (`AgentRuntimeUnavailableError`) |
 | Missing credential diagnostics | Provider-owned/local auth | Provider-owned/local auth | `GEMINI_API_KEY` or `GOOGLE_API_KEY` |
 | Live smoke test | Opt-in | Opt-in | Opt-in |
 
 The matrix is intentionally not a lowest-common-denominator contract. Adapters
-reject unsupported inputs when silently dropping them would be misleading.
+reject unsupported inputs (see below) when silently dropping them would be
+misleading.
+
+## Permission mapping
+
+A single portable `PermissionMode` maps to each vendor's native controls. The
+same profile yields different but intentionally aligned postures per runtime;
+review this table before assuming a mode is equivalent everywhere.
+
+| `PermissionMode` | Claude `permission_mode` | Codex `approval_mode` + sandbox | Antigravity toolset + policy |
+|------------------|--------------------------|---------------------------------|------------------------------|
+| `STRICT` | `plan` | `deny_all` (never escalate) | read-only toolset, no `allow_all` policy |
+| `CAUTIOUS` | `acceptEdits` | `deny_all` (never escalate) | nondestructive toolset (no `run_command`), `allow_all` policy |
+| `DEFAULT` | `default` | `auto_review` (escalations auto-adjudicated) | nondestructive toolset (no `run_command`), `allow_all` policy |
+| `PERMISSIVE` | `bypassPermissions` | `auto_review` (escalations auto-adjudicated) | all tools, `allow_all` policy |
+
+Codex sandbox is derived from `FilesystemAccess`, independent of the approval
+mode: `READ_ONLY` → `read_only`, `WORKSPACE_WRITE` → `workspace_write`,
+`FULL_ACCESS` → `full_access`.
+
+Antigravity toolset notes: the table above describes the default posture when
+`allowed_tools` is empty. A `READ_ONLY` filesystem forces the read-only toolset
+regardless of mode. User-supplied `allowed_tools`/`disallowed_tools` override the
+defaults and are validated against the `BuiltinTools` enum (for example
+`"view_file"`, not `"Read"`); an unknown name raises `UnsupportedTaskInputError`.
+
+## Rejected inputs
+
+Each adapter raises `UnsupportedTaskInputError` for task fields it has no SDK
+surface to honor, rather than dropping them silently.
+
+| Field | Claude | Codex | Antigravity |
+|-------|--------|-------|-------------|
+| `budget_usd` | Mapped (`max_budget_usd`) | Rejected | Rejected |
+| `permissions.network` | Rejected | Rejected | Rejected |
+| `allowed_tools` / `disallowed_tools` | Mapped | Rejected | Mapped (`disallowed_tools` → `disabled_tools`); allow-list and deny-list are mutually exclusive and rejected if combined |
+| `mcp_servers` | Mapped | Rejected (no per-task MCP) | Mapped, without per-server `env` |
+
+Two task fields are informational only and not enforced by any built-in adapter:
+`AgentTask.sdk_executions` (carried into events as a hint) and
+`SessionResumeState.transcript` (adapters resume by `session_id`).
+
+Claude additionally records any vendor-option kwargs it had to drop due to SDK
+drift in `AgentResult.metadata["dropped_options"]`, so silent omission stays
+observable.
+
+## Session storage (Antigravity)
+
+Antigravity session and app-data directories are written under
+`$XDG_CACHE_HOME/agent-runtime-kit` (default `~/.cache/agent-runtime-kit`),
+created with `0o700` permissions. This replaces the previous world-shared
+`/tmp` location so transcripts survive reboots and are not exposed to other
+users. Override the base directory with
+`AntigravityAgentRuntime(data_dir=...)`.

docs/providers.md

@@ -12,15 +12,44 @@
 
 Claude uses the `claude-agent-sdk` package and maps working directory,
 permissions, MCP servers, sessions, structured output, tool allow/deny lists,
-and budget where supported by the installed SDK.
+and budget where supported by the installed SDK. It streams incremental output
+and tool events while the SDK runs, and sets `finish_reason="max_turns"` when a
+turn is truncated by the max-turns limit. `permissions.network` has no SDK
+surface and is rejected with a typed error. Any option kwargs dropped because a
+future SDK renamed or removed them are recorded in
+`AgentResult.metadata["dropped_options"]` rather than discarded silently.
 
 Codex uses the `openai-codex` package and maps working directory, session
 resume, approval mode, sandbox, structured output, model, and reasoning effort.
-Codex does not currently support per-task MCP server configuration through this
-adapter, so `mcp_servers` is rejected with a typed error.
+Approval mode follows `PermissionMode`: `STRICT`/`CAUTIOUS` → `deny_all` (never
+escalate beyond the sandbox), `DEFAULT`/`PERMISSIVE` → `auto_review`
+(escalations auto-adjudicated). Tool audits are parsed from `TurnResult.items`
+(command executions, MCP tool calls, dynamic tool calls, web searches), and a
+`TurnResult.status` of `failed`/`interrupted` maps to the matching
+`finish_reason`. `budget_usd`, `permissions.network`, `allowed_tools`,
+`disallowed_tools`, and `mcp_servers` have no per-task SDK surface and are
+rejected with typed errors. The constructor defaults to
+`config_overrides=("features.plugins=false",)` so headless runs are
+deterministic and do not pick up host-local Codex plugin configuration; pass a
+different tuple to opt in.
 
 Antigravity uses the `google-antigravity` package and maps API key,
 workspace, permission-derived capabilities/policies, MCP stdio servers,
 conversation id, structured output, session directories, model, and tool
-events. Antigravity MCP server configs do not currently accept per-server env
-values through this adapter.
+events. `disallowed_tools` maps to `CapabilitiesConfig.disabled_tools`, and an
+allow-list and a deny-list are mutually exclusive (the SDK forbids combining
+enabled and disabled tool lists), so supplying both is rejected. Tool names are
+validated against the `BuiltinTools` enum (`"view_file"`, not `"Read"`).
+`budget_usd` and `permissions.network` are rejected with typed errors, and
+MCP server configs do not accept per-server env values. The default tool posture
+with no `allowed_tools` is:
+
+| `PermissionMode` (or `READ_ONLY` filesystem) | Toolset | Policy |
+|----------------------------------------------|---------|--------|
+| `STRICT`, or any `READ_ONLY` filesystem | read-only | none (no `allow_all`) |
+| `CAUTIOUS`, `DEFAULT` | nondestructive (no `run_command`) | `allow_all` |
+| `PERMISSIVE` | all tools | `allow_all` |
+
+Session and app-data directories are written under
+`$XDG_CACHE_HOME/agent-runtime-kit` (default `~/.cache/agent-runtime-kit`,
+`0o700`), overridable via `AntigravityAgentRuntime(data_dir=...)`.

docs/publish-checklist.md

@@ -24,9 +24,19 @@ available; any 200 response means it has been claimed.
 
 ## Release Gate
 
-- `uv run pytest`
+Continuous integration (`.github/workflows/ci.yml`) runs `ruff`, `mypy`, and
+`pytest` on every pull request and push to `main` across Python 3.10–3.13 in
+both the core-only and all-extras dependency lanes, so gate results no longer
+depend on which extras happen to be installed locally. The publish workflow
+itself also gates on tests: its `test` job (core on 3.10, all extras on 3.13)
+must pass before the `build` job runs, so a release cannot be built or published
+unless `ruff`/`mypy`/`pytest` are green against the release tag.
+
+To reproduce the gate locally before tagging:
+
 - `uv run ruff check .`
 - `uv run mypy`
+- `uv run pytest`
 - `uv run python -m build`
 - Optional: provider-specific live smoke tests from `docs/live-smoke.md`