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

{agent_runtime_kit-0.1.1 → 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.1 → agent_runtime_kit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-runtime-kit
-Version: 0.1.1
+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
@@ -117,3 +117,4 @@ cost, session id, artifacts, tool-call audits, and provider metadata.
 - [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.1 → agent_runtime_kit-0.2.0}/README.md

@@ -85,3 +85,4 @@ cost, session id, artifacts, tool-call audits, and provider metadata.
 - [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.1 → agent_runtime_kit-0.2.0}/docs/capability-matrix.md

@@ -12,7 +12,7 @@
 | 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` |
+| 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

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=...)`.