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

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

@@ -13,7 +13,15 @@ htmlcov/
 .DS_Store
 
 # Local generated reports
-reports/sdk-evolution/
+reports/
+
+# Local review artifacts
+CODE-REVIEW.md
+REVIEW.md
+
+# Secrets / local environment
+.env
+.env.*
 
 # Virtual environments
 .venv

agent_runtime_kit-0.3.0/CHANGELOG.md

@@ -0,0 +1,218 @@
+# 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.3.0 - 2026-07-02
+
+### Added
+
+- Codex runtimes can now opt into reusable SDK process lifecycle with
+  `CodexAgentRuntime(reuse_process=True)`, `await runtime.aclose()`, or
+  `async with CodexAgentRuntime(..., reuse_process=True)`. Reuse keeps the Codex
+  app-server process alive across compatible tasks without implicitly reusing
+  Codex threads or sessions.
+- Claude and Antigravity runtimes can now opt into adapter-owned SDK process
+  lifecycle with the same `reuse_process=True`, `aclose()`, and async context
+  manager shape. Claude reuses `ClaudeSDKClient` while preserving per-task
+  stream session IDs; Antigravity only reuses for explicit conversation IDs
+  because its SDK process is conversation-scoped.
+- The SDK evolution agent now enables vendor process reuse for multi-stage
+  SDK-backed runs and closes internally owned runtimes when the run exits.
+- `FinishReason` enum of the canonical `finish_reason` values, plus first-class
+  `AgentTask.model` and `AgentTask.reasoning_effort` fields (keyword-only, so
+  the positional layout that predates them is unchanged; the
+  `metadata["model"]`/`metadata["reasoning_effort"]` aliases keep working).
+  `model` is honored by all three adapters. `reasoning_effort` maps to the
+  Claude and Codex `effort` options; Antigravity has no reasoning-effort
+  control and rejects the field with a typed error instead of silently
+  ignoring it.
+- Third-party runtime kinds: `AgentRuntimeKind.coerce` and the registry accept
+  namespaced strings (e.g. `"x-myorg-agent"`), and `runtime_kind_value()`
+  returns the wire form of either shape.
+- Tool observability parity: the Codex adapter emits `agent.tool.requested` /
+  `agent.tool.completed` events, Claude tool audits carry `result_preview`, and
+  Antigravity audits are recorded per call rather than collapsed by tool name.
+- Claude reports the effective vendor permission mode in
+  `AgentResult.metadata["permission_mode"]`, and the Codex/Antigravity adapters
+  record SDK kwargs dropped for compatibility in
+  `AgentResult.metadata["dropped_options"]`.
+- `docs/api-stability.md` documents the public surface, the 0.x compatibility
+  policy, and the vendor SDK pinning policy.
+
+### Changed
+
+- BREAKING: the `AgentRuntime` protocol now requires `aclose()` and async
+  context-manager support, and `kind` is typed `AgentRuntimeKind | str` so
+  third-party runtimes can conform without forking the enum.
+- BREAKING: mapping fields on `AgentTask`, `AgentResult`, and related models are
+  copied at construction and read-only at the top level afterwards (in-place
+  mutation of the mapping itself raises `TypeError`; the freeze is shallow, so
+  nested containers are not copied or frozen); `dataclasses.asdict`,
+  `copy.deepcopy`, `pickle`, and JSON serialization keep working.
+- Claude: `CAUTIOUS` now maps to the vendor `default` permission mode instead of
+  `acceptEdits` (it was looser than `DEFAULT`), and a `READ_ONLY` filesystem
+  forces `plan` mode.
+- Claude: an unsatisfied `output_schema` or an empty completion now returns
+  `finish_reason="failed"` instead of silent success.
+- Codex: `Usage` reports the executed turn rather than cumulative
+  across-the-thread totals when resuming sessions.
+- All adapters: `AgentResult.session_id` falls back to the task-supplied session
+  handle when the SDK response omits one.
+- Antigravity: explicit `vertex=True` takes precedence over ambient API keys,
+  combining a `READ_ONLY` filesystem or `STRICT` mode with non-read-only
+  `allowed_tools` is rejected instead of silently granted, and vendor stop
+  reasons map to `max_tokens`/`failed` finish reasons.
+- BREAKING: Antigravity deny-lists are now subtractive in every mode.
+  `disabled_tools` means "enable everything else", which re-enabled write and
+  destructive tools past the mode's baseline; now only `PERMISSIVE` (whose
+  baseline is every tool) still takes that route, while `READ_ONLY`/`STRICT`
+  get the read-only toolset minus the denied tools and `DEFAULT`/`CAUTIOUS`
+  the nondestructive toolset minus the denied tools.
+- Vendor SDK dependencies now carry pre-1.0 upper bounds (`claude-agent-sdk<0.3`,
+  `openai-codex<0.2`, `google-antigravity<0.2`) so a breaking upstream minor
+  cannot reach fresh installs before adapters are revalidated.
+- BREAKING: permission-critical SDK options fail closed under vendor drift. If
+  the installed SDK cannot accept Claude's `permission_mode` (or a requested
+  tool allow/deny list), Codex's `sandbox`/`approval_mode`, or Antigravity's
+  `capabilities`/`policies`/workspace scoping, `run()` raises
+  `UnsupportedTaskInputError` instead of silently running under the SDK's
+  default (more permissive) posture. A requested `budget_usd` fails closed the
+  same way if the installed Claude SDK stops accepting `max_budget_usd`, so a
+  spend cap can never silently vanish. Non-security drift is still tolerated
+  and recorded in `AgentResult.metadata["dropped_options"]`.
+
+- Installation docs now lead with `agent-runtime-kit[all]` for the easiest
+  full-provider setup and explain provider extras as dependency isolation, not a
+  separate API.
+- README and package metadata now include clearer About copy and searchable
+  tags for agent runtime, coding-agent, Claude Code, Codex, Antigravity, MCP,
+  typed Python, and async Python use cases.
+- The source distribution now allowlists individual public docs instead of the
+  whole `docs/` directory.
+
+### Removed
+
+- Removed the stale internal publish checklist from public documentation.
+- BREAKING: removed the dead `AgentCapabilities.sdk_turn_limit` field (no
+  adapter ever read it).
+
+### Fixed
+
+- Reused vendor SDK clients are evicted when a run is interrupted or cancelled
+  mid-flight, and `aclose()` no longer races an in-flight run on the same
+  runtime instance.
+- Codex: a turn ending in the SDK's non-terminal `inProgress` status — or any
+  future unknown status — now fails closed as `finish_reason="failed"` instead
+  of reading as success with partial output.
+- Codex: `Usage.input_tokens` now excludes cached input tokens, which are
+  reported separately in `cache_read_tokens` (matching the documented `Usage`
+  contract and the Antigravity adapter) instead of being double-counted across
+  both fields.
+- Event redaction now covers camelCase secret keys (e.g. `accessToken`) and
+  separator-less ones (e.g. `accesstoken`, `SESSIONTOKEN`) while keeping plural
+  usage counters (`inputTokens`, `totaltokens`) visible, and the event
+  sanitizer bounds recursion depth and detects reference cycles so pathological
+  metadata cannot abort a run.
+- SDK evolution example: inspecting candidate SDK versions (which pip-installs
+  and imports freshly downloaded upstream code) is now opt-in via
+  `--inspect-candidates` and runs in a credential-scrubbed environment — and
+  the behavior probes now honor the same gate and scrub instead of installing
+  candidates unconditionally with the caller's full environment (skipped
+  candidates are recorded explicitly). `--draft-pr` no longer fails when the
+  report directory is gitignored.
+- SDK evolution example: release-note links extracted from fetched pages are
+  only followed when they resolve to `https://github.com` (a protocol-relative
+  href in user-generated discussion markup could otherwise trigger an off-site
+  request), and a configured-but-failing GitHub GraphQL token now surfaces on
+  the source instead of silently downgrading to the unauthenticated scrape.
+
+## 0.2.0 - 2026-06-23
+
+### Added
+
+- Added the local SDK evolution agent example, including runtime-backed
+  direction analysis, architecture decision, reviewer stages, report generation,
+  and optional draft PR creation.
+- Added release-note collection, candidate API snapshots/diffs, behavior probes,
+  current-state promotion manifests, and deterministic implementation gates for
+  SDK update runs.
+- Added documentation for running the SDK evolution agent locally with supported
+  vendor credentials and reviewing generated evidence.
+
+### Changed
+
+- Updated the lockfile to the resolver-selected current Claude and Antigravity
+  SDK versions after the evolution agent validated adapter-contract behavior:
+  `claude-agent-sdk` 0.2.106 and `google-antigravity` 0.1.4.
+- SDK evolution current-state manifests now record repo-relative checked-in
+  artifact paths rather than machine-local absolute paths.
+
+## 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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-runtime-kit
-Version: 0.2.0
+Version: 0.3.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
@@ -8,7 +8,7 @@ Project-URL: Issues, https://github.com/ebarti/agent-runtime-kit/issues
 Author: Eloi Barti
 License-Expression: MIT
 License-File: LICENSE
-Keywords: agents,antigravity,claude,codex,sdk
+Keywords: agent-runtime,agent-sdk,agents,antigravity,async-python,claude,claude-code,codex,coding-agents,developer-tools,google-antigravity,mcp,openai-codex,runtime-api,sdk,typed-python
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -19,15 +19,15 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 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.0b3; extra == 'all'
+Requires-Dist: claude-agent-sdk<0.3,>=0.2.87; extra == 'all'
+Requires-Dist: google-antigravity<0.2,>=0.1.2; extra == 'all'
+Requires-Dist: openai-codex<0.2,>=0.1.0b3; extra == 'all'
 Provides-Extra: antigravity
-Requires-Dist: google-antigravity>=0.1.2; extra == 'antigravity'
+Requires-Dist: google-antigravity<0.2,>=0.1.2; extra == 'antigravity'
 Provides-Extra: claude
-Requires-Dist: claude-agent-sdk>=0.2.87; extra == 'claude'
+Requires-Dist: claude-agent-sdk<0.3,>=0.2.87; extra == 'claude'
 Provides-Extra: codex
-Requires-Dist: openai-codex>=0.1.0b3; extra == 'codex'
+Requires-Dist: openai-codex<0.2,>=0.1.0b3; extra == 'codex'
 Description-Content-Type: text/markdown
 
 # agent-runtime-kit
@@ -37,6 +37,22 @@ applications one typed async API for dispatching an agentic task through Claude
 Agent SDK, OpenAI Codex SDK, or Google Antigravity SDK while keeping provider
 capabilities visible.
 
+**Tags:** `agent-sdk` `agent-runtime` `coding-agents` `claude-code`
+`openai-codex` `google-antigravity` `mcp` `typed-python` `async-python`
+`developer-tools`
+
+## About
+
+`agent-runtime-kit` is for Python developers who want to run coding-agent tasks
+through vendor runtimes without rewriting their application around each SDK. It
+normalizes the runtime boundary: task inputs, capability checks, event streams,
+tool audits, availability diagnostics, and typed results.
+
+The library keeps vendor differences visible. Claude, Codex, and Antigravity
+still expose different capabilities, permission models, setup requirements, and
+unsupported fields. `agent-runtime-kit` gives those differences a consistent
+shape instead of hiding them behind a lowest-common-denominator wrapper.
+
 The package is intentionally not a router, benchmark harness, queue, hosted
 service, or full agent framework. It is the reusable layer underneath those
 systems: task models, runtime capabilities, event sinks, availability
@@ -44,21 +60,34 @@ diagnostics, and adapters.
 
 ## Install
 
-Core only:
+If you want all first-party runtimes available, install the `all` extra:
+
+```bash
+pip install "agent-runtime-kit[all]"
+```
+
+Install the dependency-free core when you only need the public models, fake
+runtime, registry, diagnostics types, or you plan to add provider SDKs later:
 
 ```bash
 pip install agent-runtime-kit
 ```
 
-Provider extras:
+Install a single provider extra when your application only dispatches through
+one vendor runtime:
 
 ```bash
 pip install "agent-runtime-kit[claude]"
 pip install "agent-runtime-kit[codex]"
 pip install "agent-runtime-kit[antigravity]"
-pip install "agent-runtime-kit[all]"
 ```
 
+Provider extras are a packaging boundary, not a separate API. They keep the
+core importable without vendor SDKs, avoid forcing every user to install every
+CLI binary or compiled runtime wheel, and contain dependency drift when one
+fast-moving vendor SDK changes independently of the others. Missing adapters
+raise typed setup errors that point to the matching extra.
+
 ```python
 import asyncio
 
@@ -100,21 +129,26 @@ asyncio.run(main())
 
 ## Runtime Fields
 
-`AgentTask` supports goal, system prompt, working directory, permission profile,
-MCP stdio servers, session/resume handles, output schema, budget, metadata, and
-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.
+`AgentTask` supports goal, system prompt, model, reasoning effort, working
+directory, permission profile, MCP stdio servers, session/resume handles, output
+schema, budget, metadata, and an async event sink. (`model` and
+`reasoning_effort` are first-class fields; the legacy `metadata["model"]` /
+`metadata["reasoning_effort"]` aliases still work.) 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.
+`AgentResult` returns output, finish reason (see `FinishReason`), parsed
+structured output, usage, cost, session id, tool-call audits, and provider
+metadata. `artifacts` is a reserved field: no built-in runtime populates it yet,
+so it is always an empty tuple today.
 
 ## Docs
 
 - [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)
+- [API stability](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/api-stability.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.3.0/README.md

@@ -0,0 +1,122 @@
+# agent-runtime-kit
+
+`agent-runtime-kit` is a small Python runtime layer for agent SDKs. It gives
+applications one typed async API for dispatching an agentic task through Claude
+Agent SDK, OpenAI Codex SDK, or Google Antigravity SDK while keeping provider
+capabilities visible.
+
+**Tags:** `agent-sdk` `agent-runtime` `coding-agents` `claude-code`
+`openai-codex` `google-antigravity` `mcp` `typed-python` `async-python`
+`developer-tools`
+
+## About
+
+`agent-runtime-kit` is for Python developers who want to run coding-agent tasks
+through vendor runtimes without rewriting their application around each SDK. It
+normalizes the runtime boundary: task inputs, capability checks, event streams,
+tool audits, availability diagnostics, and typed results.
+
+The library keeps vendor differences visible. Claude, Codex, and Antigravity
+still expose different capabilities, permission models, setup requirements, and
+unsupported fields. `agent-runtime-kit` gives those differences a consistent
+shape instead of hiding them behind a lowest-common-denominator wrapper.
+
+The package is intentionally not a router, benchmark harness, queue, hosted
+service, or full agent framework. It is the reusable layer underneath those
+systems: task models, runtime capabilities, event sinks, availability
+diagnostics, and adapters.
+
+## Install
+
+If you want all first-party runtimes available, install the `all` extra:
+
+```bash
+pip install "agent-runtime-kit[all]"
+```
+
+Install the dependency-free core when you only need the public models, fake
+runtime, registry, diagnostics types, or you plan to add provider SDKs later:
+
+```bash
+pip install agent-runtime-kit
+```
+
+Install a single provider extra when your application only dispatches through
+one vendor runtime:
+
+```bash
+pip install "agent-runtime-kit[claude]"
+pip install "agent-runtime-kit[codex]"
+pip install "agent-runtime-kit[antigravity]"
+```
+
+Provider extras are a packaging boundary, not a separate API. They keep the
+core importable without vendor SDKs, avoid forcing every user to install every
+CLI binary or compiled runtime wheel, and contain dependency drift when one
+fast-moving vendor SDK changes independently of the others. Missing adapters
+raise typed setup errors that point to the matching extra.
+
+```python
+import asyncio
+
+from agent_runtime_kit import AgentTask, FakeAgentRuntime
+
+
+async def main() -> None:
+    runtime = FakeAgentRuntime(output="done")
+    result = await runtime.run(AgentTask(goal="Summarize this repository"))
+    print(result.output)
+
+
+asyncio.run(main())
+```
+
+The core package has no Claude, Codex, or Antigravity dependency. Vendor SDKs
+are added through optional extras.
+
+## Real Providers
+
+```python
+import asyncio
+
+from agent_runtime_kit import AgentTask
+from agent_runtime_kit.adapters import ClaudeAgentRuntime
+
+
+async def main() -> None:
+    runtime = ClaudeAgentRuntime(default_model="claude-sonnet-4-6")
+    diagnostic = runtime.availability()
+    if not diagnostic.available:
+        raise RuntimeError(diagnostic.message)
+    result = await runtime.run(AgentTask(goal="Summarize this repository"))
+    print(result.output)
+
+
+asyncio.run(main())
+```
+
+## Runtime Fields
+
+`AgentTask` supports goal, system prompt, model, reasoning effort, working
+directory, permission profile, MCP stdio servers, session/resume handles, output
+schema, budget, metadata, and an async event sink. (`model` and
+`reasoning_effort` are first-class fields; the legacy `metadata["model"]` /
+`metadata["reasoning_effort"]` aliases still work.) 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 (see `FinishReason`), parsed
+structured output, usage, cost, session id, tool-call audits, and provider
+metadata. `artifacts` is a reserved field: no built-in runtime populates it yet,
+so it is always an empty tuple today.
+
+## Docs
+
+- [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)
+- [API stability](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/api-stability.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)
+- [SDK evolution agent](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/sdk-evolution-agent.md)

agent_runtime_kit-0.3.0/docs/api-stability.md

@@ -0,0 +1,56 @@
+# API stability & versioning
+
+`agent-runtime-kit` is pre-1.0 (`0.x`) and follows semantic versioning with the
+usual pre-1.0 caveat: **breaking changes may land in a minor release** (`0.N`)
+while the API is being shaped toward 1.0. Patch releases (`0.N.P`) are additive
+or bug-fix only.
+
+## Public API
+
+The supported surface is exactly what `agent_runtime_kit.__all__` exports (and
+the vendor adapters under `agent_runtime_kit.adapters`). Anything whose module or
+name begins with an underscore (`agent_runtime_kit._types`,
+`agent_runtime_kit._runtime`, etc.) is internal and may change without notice —
+import the names from the top-level package instead.
+
+`agent_runtime_kit.testing` is public and intended for downstream test suites
+(fake runtimes and event sinks).
+
+## Compatibility guarantees within a 0.x line
+
+- **Runtime kinds are open.** `AgentRuntimeKind.coerce` accepts namespaced
+  strings (e.g. `"x-myorg-agent"`), and the registry stores them, so a third
+  party can ship an adapter for a new runtime without forking the enum.
+- **Every runtime exposes the async lifecycle** (`aclose`, `async with`) declared
+  by the `AgentRuntime` protocol. Stateless runtimes implement it as a no-op.
+- **`finish_reason` values** come from `FinishReason`. The field is typed `str`
+  for forward-compatibility, so new reasons can be added without a type break;
+  compare against `FinishReason` members rather than bare literals.
+- **Result/task mappings are read-only at the top level.** `AgentTask`/`AgentResult`
+  copy `Mapping` fields into read-only dicts at construction; in-place writes to
+  the mapping itself raise `TypeError`. The freeze is shallow — nested containers
+  are not copied or frozen — so treat the whole structure as immutable by
+  convention and compare by value. The wrappers remain plain `dict` subclasses,
+  so `dataclasses.asdict`, `pickle`, `copy.deepcopy`, and JSON serialization
+  keep working.
+- **Unsupported inputs raise, they are not dropped.** An adapter that cannot honor
+  a task field raises `UnsupportedTaskInputError`; the one exception is
+  vendor-option drift, which is recorded in
+  `AgentResult.metadata["dropped_options"]` instead.
+
+## Vendor SDK version policy
+
+The vendor SDK extras are pinned with cautious upper bounds (e.g.
+`claude-agent-sdk>=0.2.87,<0.3`) because those SDKs are themselves pre-1.0 and
+have shipped breaking changes within a minor series. The bounds are raised
+deliberately — after the contract tests and the SDK-evolution agent verify a new
+version — rather than left unbounded. A weekly CI lane installs the latest vendor
+SDKs *within the declared caps*, so drift inside an allowed range surfaces before
+it reaches installed users; a release above a cap is by design invisible to that
+lane until the cap is raised. A separate lane installs every direct dependency at
+its declared floor so a stale minimum cannot sit undetected in the metadata.
+
+## Deprecation
+
+When a public name is slated for removal it will be kept working for at least one
+minor release with a `DeprecationWarning` before it is dropped.

{agent_runtime_kit-0.2.0 → agent_runtime_kit-0.3.0}/docs/capability-matrix.md

@@ -9,10 +9,11 @@
 | 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 |
+| Streaming output events | Yes — incremental `output.delta` while the SDK runs | No — a single `output.delta` at the end (non-streaming SDK) | Yes — from response chunks |
+| Tool audit events | Yes — streamed from message blocks | Yes — emitted from parsed `TurnResult` items after the turn | Yes — from tool chunks |
+| `vendor.turn` events | No | No | Yes — from thought/unknown 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 |
+| Missing credential diagnostics | No — `availability()` reports available with an `auth_source` label; auth failures surface at `run()` | No — same as Claude (`auth_source` label; deferred) | Yes — `availability()` returns `MISSING_CREDENTIALS` when no API key / ADC-Vertex project is configured |
 | Live smoke test | Opt-in | Opt-in | Opt-in |
 
 The matrix is intentionally not a lowest-common-denominator contract. Adapters
@@ -28,19 +29,30 @@ 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 |
+| `CAUTIOUS` | `default` | `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 |
 
+The ladder is monotonic: `CAUTIOUS` is never looser than `DEFAULT` on any
+backend. Claude has no distinct cautious-execution tier, so `CAUTIOUS` and
+`DEFAULT` both map to `default` (no auto-approval); `acceptEdits` is not used, as
+it would auto-approve edits and in-cwd deletes. Claude's effective
+`permission_mode` is echoed in `AgentResult.metadata["permission_mode"]`.
+
 Codex sandbox is derived from `FilesystemAccess`, independent of the approval
 mode: `READ_ONLY` → `read_only`, `WORKSPACE_WRITE` → `workspace_write`,
-`FULL_ACCESS` → `full_access`.
+`FULL_ACCESS` → `full_access`. On Claude, a `READ_ONLY` filesystem forces
+`plan` mode (no writes) regardless of `PermissionMode`.
 
 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`.
+regardless of mode. User-supplied `allowed_tools`/`disallowed_tools` are
+validated against the `BuiltinTools` enum (for example `"view_file"`, not
+`"Read"`); an unknown name raises `UnsupportedTaskInputError`. An allow-list
+naming a non-read-only tool under a `READ_ONLY` filesystem or `STRICT` mode is
+rejected, and a deny-list subtracts from the mode's baseline toolset rather
+than re-enabling everything else (only `PERMISSIVE`, whose baseline is every
+tool, uses the SDK's `disabled_tools` route).
 
 ## Rejected inputs
 
@@ -49,9 +61,10 @@ surface to honor, rather than dropping them silently.
 
 | Field | Claude | Codex | Antigravity |
 |-------|--------|-------|-------------|
-| `budget_usd` | Mapped (`max_budget_usd`) | Rejected | Rejected |
+| `budget_usd` | Mapped (`max_budget_usd`, fails closed under SDK drift) | Rejected | Rejected |
+| `reasoning_effort` | Mapped (`effort`) | Mapped (`effort`) | Rejected (no SDK surface) |
 | `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 |
+| `allowed_tools` / `disallowed_tools` | Mapped | Rejected | Mapped; deny-lists subtract from the mode's baseline (only `PERMISSIVE` uses `disabled_tools`), and allow-list plus deny-list together is rejected |
 | `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:
@@ -60,7 +73,9 @@ Two task fields are informational only and not enforced by any built-in adapter:
 
 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.
+observable. Permission-critical options are exempt from that drift tolerance:
+when the installed SDK cannot accept them, the run fails with a typed error
+rather than running with weaker permissions than requested.
 
 ## Session storage (Antigravity)