agent-runtime-kit 0.1.0__tar.gz → 0.2.0__tar.gz

{agent_runtime_kit-0.1.0 → agent_runtime_kit-0.2.0}/.gitignore

@@ -12,5 +12,8 @@ wheels/
 htmlcov/
 .DS_Store
 
+# Local generated reports
+reports/sdk-evolution/
+
 # Virtual environments
 .venv

{agent_runtime_kit-0.1.0 → agent_runtime_kit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-runtime-kit
-Version: 0.1.0
+Version: 0.2.0
 Summary: One typed runtime API for Claude, Codex, and Antigravity agent SDKs.
 Project-URL: Homepage, https://github.com/ebarti/agent-runtime-kit
 Project-URL: Repository, https://github.com/ebarti/agent-runtime-kit
@@ -11,7 +11,6 @@ License-File: LICENSE
 Keywords: agents,antigravity,claude,codex,sdk
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -22,13 +21,13 @@ Requires-Python: >=3.10
 Provides-Extra: all
 Requires-Dist: claude-agent-sdk>=0.2.87; extra == 'all'
 Requires-Dist: google-antigravity>=0.1.2; extra == 'all'
-Requires-Dist: openai-codex>=0.1.0b2; extra == 'all'
+Requires-Dist: openai-codex>=0.1.0b3; extra == 'all'
 Provides-Extra: antigravity
 Requires-Dist: google-antigravity>=0.1.2; extra == 'antigravity'
 Provides-Extra: claude
 Requires-Dist: claude-agent-sdk>=0.2.87; extra == 'claude'
 Provides-Extra: codex
-Requires-Dist: openai-codex>=0.1.0b2; extra == 'codex'
+Requires-Dist: openai-codex>=0.1.0b3; extra == 'codex'
 Description-Content-Type: text/markdown
 
 # agent-runtime-kit
@@ -103,16 +102,19 @@ 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)
+- [SDK evolution agent](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/sdk-evolution-agent.md)

{agent_runtime_kit-0.1.0 → agent_runtime_kit-0.2.0}/README.md

@@ -70,16 +70,19 @@ 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)
+- [SDK evolution agent](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/sdk-evolution-agent.md)

agent_runtime_kit-0.2.0/docs/capability-matrix.md

@@ -0,0 +1,72 @@
+# Capability Matrix
+
+| Capability | Claude Agent SDK | OpenAI Codex SDK | Google Antigravity SDK |
+|------------|------------------|------------------|------------------------|
+| Optional extra | `claude` | `codex` | `antigravity` |
+| Core import without extra | Yes | Yes | Yes |
+| Working directory | Yes | Yes | Yes |
+| Session resume | Yes | Yes | Yes |
+| 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 | 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, including API key, Bedrock, Vertex, AWS, and Azure modes | Provider-owned/local auth, including ChatGPT/API key/custom providers/Bedrock | API key or Google ADC / Vertex config |
+| Live smoke test | Opt-in | Opt-in | Opt-in |
+
+The matrix is intentionally not a lowest-common-denominator contract. Adapters
+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=...)`.

agent_runtime_kit-0.2.0/docs/live-smoke.md

@@ -0,0 +1,35 @@
+# Live Smoke Tests
+
+Default tests never call live providers. Live smoke tests are skipped unless
+you opt in explicitly:
+
+```bash
+AGENT_RUNTIME_KIT_LIVE=1 AGENT_RUNTIME_KIT_LIVE_PROVIDER=claude uv run pytest -m live
+```
+
+Provider values:
+
+- `claude`
+- `codex`
+- `antigravity`
+- `all`
+
+Expected setup:
+
+- Claude: install `agent-runtime-kit[claude]` and configure Claude Agent SDK
+  auth according to vendor docs. Supported provider modes include Anthropic API
+  key auth, Amazon Bedrock via `CLAUDE_CODE_USE_BEDROCK=1` and the AWS SDK
+  credential chain, Google Vertex AI, Claude Platform on AWS, and Azure AI
+  Foundry.
+- Codex: install `agent-runtime-kit[codex]` and configure local Codex auth/app
+  server according to vendor docs. Codex can use ChatGPT sign-in, API-key
+  sign-in, access-token setup, custom model providers, and the built-in
+  `amazon-bedrock` model provider.
+- Antigravity: install `agent-runtime-kit[antigravity]` and either set
+  `GEMINI_API_KEY` / `GOOGLE_API_KEY` or configure Google Application Default
+  Credentials for Vertex AI. When using ADC, provide a project through ADC or
+  `GOOGLE_CLOUD_PROJECT`; the adapter defaults location to `global` unless
+  `GOOGLE_CLOUD_LOCATION`, `GOOGLE_CLOUD_REGION`, or `CLOUD_ML_REGION` is set.
+
+The smoke prompt is intentionally small. It verifies adapter construction,
+availability diagnostics, one task invocation, and a non-empty result.

agent_runtime_kit-0.2.0/docs/providers.md

@@ -0,0 +1,73 @@
+# Provider Diagnostics
+
+`agent-runtime-kit` keeps provider setup checks explicit. Each runtime exposes
+`availability()` and returns a `RuntimeAvailability` value with:
+
+- runtime kind
+- availability flag
+- reason
+- message
+- package name
+- installed version when discoverable
+
+Claude uses the `claude-agent-sdk` package and maps working directory,
+permissions, MCP servers, sessions, structured output, tool allow/deny lists,
+runtime environment, 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.
+Claude auth is provider-owned: use Anthropic API key auth, or configure
+third-party provider modes through Claude Code environment/settings such as
+`CLAUDE_CODE_USE_BEDROCK=1` with the AWS SDK credential chain,
+`CLAUDE_CODE_USE_VERTEX=1` with Google credentials,
+`CLAUDE_CODE_USE_ANTHROPIC_AWS=1`, or `CLAUDE_CODE_USE_FOUNDRY=1`.
+`ClaudeAgentRuntime(env=...)` passes those provider-specific environment values
+to the SDK subprocess without scraping credential files. 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.
+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. Codex auth is owned by the local Codex runtime:
+ChatGPT sign-in, API-key sign-in, access-token setup, and custom providers stay
+in Codex config. For Amazon Bedrock, pass Codex config overrides such as
+`model_provider=amazon-bedrock` and provider-specific model/profile/region
+settings, and pass AWS environment values with `CodexAgentRuntime(env=...)` when
+they should be scoped to the SDK subprocess.
+
+Antigravity uses the `google-antigravity` package and maps API-key or Google
+Application Default Credentials auth, workspace, permission-derived
+capabilities/policies, MCP stdio servers, conversation id, structured output,
+session directories, model, and tool events. API-key auth comes from the
+constructor, `GEMINI_API_KEY`, or `GOOGLE_API_KEY`. Without an API key, the
+adapter uses Vertex AI config with Google ADC when a project can be discovered
+from ADC, `GOOGLE_CLOUD_PROJECT`, or `GCLOUD_PROJECT`; location defaults to
+`global` unless `GOOGLE_CLOUD_LOCATION`, `GOOGLE_CLOUD_REGION`, or
+`CLOUD_ML_REGION` is set. `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=...)`.

agent_runtime_kit-0.2.0/docs/publish-checklist.md

@@ -0,0 +1,77 @@
+# Publish Checklist
+
+`agent-runtime-kit` is not published yet.
+
+## Current Name Check
+
+Checked on 2026-06-10 from this workspace:
+
+```bash
+python - <<'PY'
+import urllib.error, urllib.request
+try:
+    urllib.request.urlopen("https://pypi.org/pypi/agent-runtime-kit/json", timeout=10)
+    print("TAKEN")
+except urllib.error.HTTPError as exc:
+    print("FREE" if exc.code == 404 else f"HTTP_{exc.code}")
+PY
+```
+
+Result: `FREE`.
+
+Re-run this immediately before publishing. A 404 means the name is still
+available; any 200 response means it has been claimed.
+
+## Release Gate
+
+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`
+
+## Trusted Publishing Setup
+
+Use PyPI Trusted Publishing rather than a long-lived API token.
+
+For a new package, create a pending publisher on PyPI with:
+
+- PyPI project name: `agent-runtime-kit`
+- Owner: `ebarti`
+- Repository name: `agent-runtime-kit`
+- Workflow name: `publish-pypi.yml`
+- Environment name: `pypi`
+
+The workflow is `.github/workflows/publish-pypi.yml`. It publishes when a
+GitHub release is published and also supports manual dispatch with a release
+tag such as `v0.1.0`.
+
+## Metadata Gate
+
+- Confirm `pyproject.toml` package name is `agent-runtime-kit`.
+- Confirm Python support remains `>=3.10`.
+- Confirm optional extras resolve for `claude`, `codex`, `antigravity`, and
+  `all`.
+- Confirm README links render on PyPI.
+- Confirm `LICENSE` is included.
+
+## Publish
+
+After configuring the pending publisher on PyPI, publish the existing first
+release by manually running the `Publish to PyPI` workflow with:
+
+```text
+tag = v0.1.0
+```
+
+Do not publish until the release gate passes and the PyPI name check is fresh.