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

{agent_runtime_kit-0.3.0 → agent_runtime_kit-0.5.0}/CHANGELOG.md

@@ -5,6 +5,108 @@ 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.5.0 - 2026-07-11
+
+### Added
+
+- Core JSON Schema validation via `jsonschema`, including construction-time
+  schema checks and `OutputSchemaError` for malformed definitions.
+- `AgentResult.parsed_output_available` distinguishes a valid JSON `null` from
+  absent or rejected structured output.
+- All built-in adapters and public fake runtimes now validate returned values
+  against `output_schema` locally, including textual JSON fallbacks.
+- `AgentResult.is_success` provides one canonical success predicate.
+- `TaskSupportReport`, `TaskSupportProvider`, and `validate_task()` provide
+  side-effect-free task preflight without adding a requirement to the
+  `AgentRuntime` protocol. Registry and `AgentKit` helpers preserve custom
+  runtime validation and capability-based fallback for older runtimes.
+- `COMPATIBILITY_MANIFEST` records each built-in adapter's install extra,
+  import module, accepted SDK range, tested lockfile version, and runtime binary
+  versions such as `openai-codex-cli-bin`.
+- `RuntimeReadiness`, `ReadinessStatus`, the optional
+  `RuntimeReadinessProvider`, and bounded async `check_readiness()` probes
+  distinguish `READY_TO_ATTEMPT`, `NOT_READY`, and `INDETERMINATE` without
+  running an agent task. Registry, `AgentKit`, and provider-diagnostics helpers
+  expose the same async checks.
+- Absolute `AgentTask.deadline` values, `AgentKit.run(timeout=...)`, typed
+  `AgentTaskTimeoutError`, and `FinishReason.TIMED_OUT` provide bounded task
+  execution across provider startup and reused-process queueing.
+- Built-in runtimes and `AgentKit.cancel()` now return immutable
+  `CancellationReceipt` values with explicit request dispositions; legacy
+  third-party `cancel()` methods returning `None` remain supported.
+
+### Changed
+
+- BREAKING: built-in adapters no longer pin library-owned default model names.
+  Model selection now follows task field > legacy metadata > `default_model=`
+  constructor override > provider-native configuration. Provider-native calls
+  omit the model kwarg; results expose `model_source` and only report a model
+  value when known. Existing constructor overrides remain supported.
+- Pydantic structured-output parsing now requests strict validation, so values
+  such as `"42"` no longer coerce into integer fields.
+- BREAKING: task and value-object constructors now reject blank identities,
+  non-positive execution hints, invalid budgets, ambiguous session inputs,
+  duplicate MCP names, and conflicting tool filters.
+- BREAKING: unknown `Usage` values, including cost, are `None` rather than zero;
+  an explicit provider-reported zero remains `0`/`0.0`.
+- Capability declarations now distinguish budget, reasoning-effort, network,
+  tool-filter, and per-MCP-server environment support. Built-in `run()` methods
+  consume the same support report used by preflight, eliminating divergent
+  rejection paths.
+- `availability()` is now strictly package-only and side-effect-free. Credential
+  and setup checks moved to async readiness probes: Codex uses the supported
+  account API with guaranteed cleanup, and Antigravity runs Google ADC discovery
+  off the event loop. Probe failures/timeouts are secret-safe and indeterminate.
+
+### Fixed
+
+- `AgentKit.run(task=...)` now rejects every explicitly supplied per-field task
+  argument, including default-valued `sdk_executions=1` and empty tool lists,
+  instead of silently ignoring it.
+- `ParsedResult[T]` clears an adapter's raw `parsed_output` when the adapter
+  reports failure, so the typed result surface never exposes unvalidated data.
+- `AgentKit.aclose()` attempts to close every cached runtime before reraising
+  the first close error, preventing later resources from leaking.
+- Permission- and budget-critical vendor options must now be explicit,
+  introspectable SDK parameters; opaque `**kwargs`, positional-only options,
+  and uninspectable callables fail closed.
+- Configured model allow-lists, Antigravity MCP name syntax, disjoint
+  allow/deny lists, and Antigravity's legacy reasoning-effort alias are rejected
+  during static preflight instead of surfacing later or being silently ignored.
+- A configured model allow-list now fails closed when model selection is
+  provider-native and therefore cannot be verified locally.
+- Cancellation now binds to one active task generation, unregisters without a
+  cancellable lock window, emits at most one timeout/cancellation terminal, and
+  gives reusable provider-process teardown a bounded grace period under repeated
+  cancellation. Runtime instances stay quarantined from new work while detached
+  teardown remains pending.
+
+## 0.4.0 - 2026-07-02
+
+### Added
+
+- `AgentKit`, a FastAPI-flavored hub over the registry: keyword-native
+  `await kit.run("claude", goal=..., permissions="strict", ...)` assembling
+  the frozen `AgentTask` internally (a prebuilt `task=` still passes through),
+  short aliases for the built-in kinds via the documented `KIND_ALIASES`
+  mapping, per-kind runtime caching closed by `aclose()`/`async with`,
+  `@kit.on(...)` sync/async event handlers that tee alongside a task's own
+  sink and can never break a run, and `@kit.runtime(...)` decorator
+  registration for third-party kinds.
+- Typed structured output: `kit.run(..., output_type=SomeType)` derives the
+  wire schema from a dataclass/`TypedDict` (dependency-free, bounded subset,
+  fail-closed via the new `OutputTypeError`) or from a Pydantic-style model's
+  own `model_json_schema`, and validates `parsed_output` back into the type.
+  The result is `ParsedResult[T]` — a runtime-identical `AgentResult`
+  subclass with a typed `parsed` accessor; `AgentResult` itself stays
+  non-generic. Non-conforming payloads yield `finish_reason="failed"`, the
+  adapters' own structured-output convention.
+- `PermissionProfile` accepts string literals for `mode`/`filesystem`
+  ("strict", "read-only", ...) and coerces them to real enum members at
+  construction; unknown values raise `ValueError` listing the vocabulary.
+  Previously a bare string silently matched none of the adapters' identity
+  checks and ran at the default posture.
+
 ## 0.3.0 - 2026-07-02
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-runtime-kit
-Version: 0.3.0
+Version: 0.5.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
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
+Requires-Dist: jsonschema<5,>=4.18
 Provides-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'
@@ -46,7 +47,7 @@ capabilities visible.
 `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.
+tool audits, package/readiness diagnostics, and typed results.
 
 The library keeps vendor differences visible. Claude, Codex, and Antigravity
 still expose different capabilities, permission models, setup requirements, and
@@ -55,7 +56,7 @@ 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
+systems: task models, runtime capabilities, event sinks, package/readiness
 diagnostics, and adapters.
 
 ## Install
@@ -66,7 +67,7 @@ If you want all first-party runtimes available, install the `all` extra:
 pip install "agent-runtime-kit[all]"
 ```
 
-Install the dependency-free core when you only need the public models, fake
+Install the vendor-SDK-free core when you only need the public models, fake
 runtime, registry, diagnostics types, or you plan to add provider SDKs later:
 
 ```bash
@@ -108,18 +109,53 @@ are added through optional extras.
 
 ## Real Providers
 
+`AgentKit` is the keyword-native hub: it registers the built-in runtimes,
+caches them per kind, and turns Python types into structured output.
+
+```python
+import asyncio
+from dataclasses import dataclass
+
+from agent_runtime_kit import AgentKit, ReadinessStatus
+
+
+@dataclass
+class RepoSummary:
+    name: str
+    languages: list[str]
+
+
+async def main() -> None:
+    async with AgentKit() as kit:
+        readiness = await kit.readiness_for("claude")
+        if readiness.status is ReadinessStatus.NOT_READY:
+            raise RuntimeError(readiness.message)
+        result = await kit.run(
+            "claude",
+            goal="Summarize this repository",
+            permissions="strict",
+            output_type=RepoSummary,
+        )
+        print(result.parsed.languages if result.parsed else result.error)
+
+
+asyncio.run(main())
+```
+
+Adapters also work standalone when you need vendor-specific configuration:
+
 ```python
 import asyncio
 
-from agent_runtime_kit import AgentTask
+from agent_runtime_kit import AgentTask, ReadinessStatus, check_readiness
 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)
+    readiness = await check_readiness(runtime)
+    if readiness.status is ReadinessStatus.NOT_READY:
+        raise RuntimeError(readiness.message)
     result = await runtime.run(AgentTask(goal="Summarize this repository"))
     print(result.output)
 
@@ -138,10 +174,35 @@ 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.
+Model selection follows one explicit precedence chain: `AgentTask.model`, then
+legacy `metadata["model"]`, then an adapter's `default_model=` constructor
+override, then the provider's native configuration/default. Adapters omit the
+vendor model option at the final step rather than pinning a library-owned model.
+Results record `metadata["model_source"]`; `metadata["model"]` appears only when
+the kit knows the selected value.
+
+Call `validate_task(runtime, task)` (or `kit.validate_task("codex", task)`) to
+inspect every statically detectable incompatibility before dispatch. The
+returned `TaskSupportReport` is side-effect-free and lists source fields such as
+`budget_usd` and `permissions.network`; `run()` still fails closed on the first
+issue. Third-party runtimes can opt into provider-specific checks with the
+`TaskSupportProvider` protocol, while older `AgentRuntime` implementations
+continue to work through capability-based fallback checks.
+
+`availability()` is deliberately synchronous, side-effect-free, and package-only.
+Use `await check_readiness(runtime)` (or `kit.readiness_for(...)`) for an explicit,
+bounded credential/setup probe. `READY_TO_ATTEMPT` means setup was positively
+detected, not that a future provider call is guaranteed to succeed;
+`INDETERMINATE` lets callers decide whether to attempt provider-chain or local
+login authentication. Probe failures and timeouts never include credential values.
+
+`AgentResult` returns output, finish reason (see `FinishReason`), locally
+validated structured output, usage, cost, session id, tool-call audits, and
+provider metadata. `is_success` is true only for a natural, error-free
+completion. Unknown usage and cost fields are `None`; reported zero remains
+distinct. `parsed_output_available` distinguishes an absent payload from valid
+JSON `null` (both use `parsed_output=None`). `artifacts` is a reserved field: no
+built-in runtime populates it yet, so it is always an empty tuple today.
 
 ## Docs
 
@@ -150,5 +211,5 @@ so it is always an empty tuple today.
 - [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)
+- [Deadlines and cancellation](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/task-control.md)
 - [SDK evolution agent](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/sdk-evolution-agent.md)

{agent_runtime_kit-0.3.0 → agent_runtime_kit-0.5.0}/README.md

@@ -14,7 +14,7 @@ capabilities visible.
 `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.
+tool audits, package/readiness diagnostics, and typed results.
 
 The library keeps vendor differences visible. Claude, Codex, and Antigravity
 still expose different capabilities, permission models, setup requirements, and
@@ -23,7 +23,7 @@ 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
+systems: task models, runtime capabilities, event sinks, package/readiness
 diagnostics, and adapters.
 
 ## Install
@@ -34,7 +34,7 @@ If you want all first-party runtimes available, install the `all` extra:
 pip install "agent-runtime-kit[all]"
 ```
 
-Install the dependency-free core when you only need the public models, fake
+Install the vendor-SDK-free core when you only need the public models, fake
 runtime, registry, diagnostics types, or you plan to add provider SDKs later:
 
 ```bash
@@ -76,18 +76,53 @@ are added through optional extras.
 
 ## Real Providers
 
+`AgentKit` is the keyword-native hub: it registers the built-in runtimes,
+caches them per kind, and turns Python types into structured output.
+
+```python
+import asyncio
+from dataclasses import dataclass
+
+from agent_runtime_kit import AgentKit, ReadinessStatus
+
+
+@dataclass
+class RepoSummary:
+    name: str
+    languages: list[str]
+
+
+async def main() -> None:
+    async with AgentKit() as kit:
+        readiness = await kit.readiness_for("claude")
+        if readiness.status is ReadinessStatus.NOT_READY:
+            raise RuntimeError(readiness.message)
+        result = await kit.run(
+            "claude",
+            goal="Summarize this repository",
+            permissions="strict",
+            output_type=RepoSummary,
+        )
+        print(result.parsed.languages if result.parsed else result.error)
+
+
+asyncio.run(main())
+```
+
+Adapters also work standalone when you need vendor-specific configuration:
+
 ```python
 import asyncio
 
-from agent_runtime_kit import AgentTask
+from agent_runtime_kit import AgentTask, ReadinessStatus, check_readiness
 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)
+    readiness = await check_readiness(runtime)
+    if readiness.status is ReadinessStatus.NOT_READY:
+        raise RuntimeError(readiness.message)
     result = await runtime.run(AgentTask(goal="Summarize this repository"))
     print(result.output)
 
@@ -106,10 +141,35 @@ 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.
+Model selection follows one explicit precedence chain: `AgentTask.model`, then
+legacy `metadata["model"]`, then an adapter's `default_model=` constructor
+override, then the provider's native configuration/default. Adapters omit the
+vendor model option at the final step rather than pinning a library-owned model.
+Results record `metadata["model_source"]`; `metadata["model"]` appears only when
+the kit knows the selected value.
+
+Call `validate_task(runtime, task)` (or `kit.validate_task("codex", task)`) to
+inspect every statically detectable incompatibility before dispatch. The
+returned `TaskSupportReport` is side-effect-free and lists source fields such as
+`budget_usd` and `permissions.network`; `run()` still fails closed on the first
+issue. Third-party runtimes can opt into provider-specific checks with the
+`TaskSupportProvider` protocol, while older `AgentRuntime` implementations
+continue to work through capability-based fallback checks.
+
+`availability()` is deliberately synchronous, side-effect-free, and package-only.
+Use `await check_readiness(runtime)` (or `kit.readiness_for(...)`) for an explicit,
+bounded credential/setup probe. `READY_TO_ATTEMPT` means setup was positively
+detected, not that a future provider call is guaranteed to succeed;
+`INDETERMINATE` lets callers decide whether to attempt provider-chain or local
+login authentication. Probe failures and timeouts never include credential values.
+
+`AgentResult` returns output, finish reason (see `FinishReason`), locally
+validated structured output, usage, cost, session id, tool-call audits, and
+provider metadata. `is_success` is true only for a natural, error-free
+completion. Unknown usage and cost fields are `None`; reported zero remains
+distinct. `parsed_output_available` distinguishes an absent payload from valid
+JSON `null` (both use `parsed_output=None`). `artifacts` is a reserved field: no
+built-in runtime populates it yet, so it is always an empty tuple today.
 
 ## Docs
 
@@ -118,5 +178,5 @@ so it is always an empty tuple today.
 - [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)
+- [Deadlines and cancellation](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/task-control.md)
 - [SDK evolution agent](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/sdk-evolution-agent.md)

agent_runtime_kit-0.5.0/docs/api-stability.md

@@ -0,0 +1,110 @@
+# 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.
+- **Cancellation receipts describe requests, not rollback.** Built-in runtimes
+  return an immutable `CancellationReceipt`; the protocol still permits `None`
+  for existing third-party runtimes, which `AgentKit` reports as
+  `LEGACY_UNCONFIRMED`. `AgentTask.deadline` is keyword-only and an expired task
+  raises `AgentTaskTimeoutError` with `FinishReason.TIMED_OUT` event semantics.
+- **`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.
+- **Constructors enforce domain invariants.** Goals and identifiers are
+  non-blank; execution hints are positive; counts and monetary values are
+  finite and non-negative; session start and resume inputs are mutually
+  exclusive; MCP server names and tool filters are unambiguous.
+- **Unknown telemetry is not zero.** Every `Usage` field is nullable. `None`
+  means the provider did not report a value; `0` and `0.0` mean it explicitly
+  reported zero.
+- **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.
+- **Task support can be inspected without dispatch.** `validate_task(runtime,
+  task)`, `RuntimeRegistry.validate_task_for(...)`, and `AgentKit.validate_task(...)`
+  return every statically detectable incompatibility as a `TaskSupportReport`.
+  `TaskSupportProvider` is an optional extension, not a new requirement on the
+  `AgentRuntime` protocol, so existing third-party runtimes retain structural
+  compatibility and use capability-based fallback checks.
+- **Package availability and execution readiness are separate.** Synchronous
+  `availability()` is package-only and side-effect-free. The bounded async
+  `check_readiness()` helper uses the optional `RuntimeReadinessProvider`
+  extension without changing the `AgentRuntime` protocol. A third-party runtime
+  without the extension maps a missing package to `NOT_READY` and present
+  package to `INDETERMINATE`. `READY_TO_ATTEMPT` establishes only that known
+  setup signals are present; it is not a guarantee of future execution.
+- **Providers own the default model.** With no task, legacy metadata, or
+  `default_model=` override, built-in adapters omit the SDK model option and let
+  the provider's supported configuration select it. The effective precedence is
+  task field, metadata alias, constructor override, provider-native. Result
+  metadata always records `model_source` and records `model` only when known.
+  A configured `supported_models` allow-list requires an explicit/verifiable
+  selection and fails closed on provider-native selection.
+- **`AgentKit` is sugar, not a second API.** The hub assembles the same frozen
+  `AgentTask` and returns the same `AgentResult` the runtimes produce
+  (`ParsedResult` is a runtime-identical subclass adding only the typed
+  `parsed` accessor). Kind aliases are limited to the documented
+  `KIND_ALIASES` mapping; exact kind strings always work. `output_type=`
+  supports a bounded, documented subset of the typing system and raises
+  `OutputTypeError` on anything outside it (Pydantic-style models are used
+  through their own `model_json_schema`/`model_validate(strict=True)` when
+  present). Raw schemas are checked at construction and again at dispatch
+  because their nested values are only shallow-frozen. Every built-in adapter
+  validates returned structured values locally.
+- **Structured-output presence is explicit.** `parsed_output_available` is true
+  for a validated payload, including JSON `null`. Existing non-null custom
+  runtime results opt in automatically; a custom runtime returning valid null
+  must set the flag explicitly.
+
+## 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.
+
+`COMPATIBILITY_MANIFEST` is the machine-readable form of that policy. Each entry
+records the install extra, import module, accepted SDK range, exact lockfile
+version exercised by the repository, and any separately versioned runtime binary
+(currently `openai-codex-cli-bin`). The manifest is tested against both
+`pyproject.toml` and `uv.lock`; it is evidence of the committed test baseline,
+not a claim that every version in the accepted range was exhaustively tested.
+
+## 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.3.0 → agent_runtime_kit-0.5.0}/docs/capability-matrix.md

@@ -4,6 +4,7 @@
 |------------|------------------|------------------|------------------------|
 | Optional extra | `claude` | `codex` | `antigravity` |
 | Core import without extra | Yes | Yes | Yes |
+| Model selection | Provider-native unless task/metadata/constructor overrides it | Provider-native unless task/metadata/constructor overrides it | Provider-native unless task/metadata/constructor overrides it |
 | 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 |
@@ -11,15 +12,33 @@
 | Permission mapping | `permission_mode` | approval mode + sandbox | capabilities + policies |
 | 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 |
+| Deadlines and cancellation | Absolute deadline + coroutine cancellation | Absolute deadline + coroutine cancellation | Absolute deadline + coroutine cancellation |
 | `vendor.turn` events | No | No | Yes — from thought/unknown chunks |
-| Missing package diagnostics | Yes (`AgentRuntimeUnavailableError`) | Yes (`AgentRuntimeUnavailableError`) | Yes (`AgentRuntimeUnavailableError`) |
-| 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 |
+| Package availability | Sync, side-effect-free, package-only | Sync, side-effect-free, package-only | Sync, side-effect-free, package-only; never calls ADC |
+| Async readiness | Direct API key/OAuth/Bedrock bearer signal → `READY_TO_ATTEMPT`; provider/local chains → `INDETERMINATE` | Supported `AsyncCodex.account(refresh_token=False)` probe; absent account → `NOT_READY` | API key or off-loop ADC/project probe; missing → `NOT_READY` |
+| Probe failure/timeout | `INDETERMINATE` | `INDETERMINATE`, app-server always closed | `INDETERMINATE` |
 | 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.
 
+The public `AgentCapabilities` value also advertises the granular task controls
+used by preflight: `budget`, `reasoning_effort`, `network_control`,
+`tool_filters`, and `mcp_server_env`. Use `validate_task(runtime, task)` when a
+concrete task is available; unlike a raw capability flag, its
+`TaskSupportReport` preserves instance-specific rules such as a configured model
+allow-list and reports all detectable issues at once.
+
+For every provider, malformed schemas are rejected locally before dispatch and
+returned structured values are validated locally after the SDK completes.
+`parsed_output_available` distinguishes valid JSON `null` from no parsed value.
+
+Deadlines cover provider startup and waits for a reused process. Cancellation
+receipts acknowledge a request at the coroutine boundary; they do not imply
+rollback of tool side effects that already completed. See
+[Deadlines and cancellation](task-control.md).
+
 ## Permission mapping
 
 A single portable `PermissionMode` maps to each vendor's native controls. The
@@ -59,6 +78,13 @@ tool, uses the SDK's `disabled_tools` route).
 Each adapter raises `UnsupportedTaskInputError` for task fields it has no SDK
 surface to honor, rather than dropping them silently.
 
+The same fields can be checked before dispatch through `validate_task`,
+`RuntimeRegistry.validate_task_for`, or `AgentKit.validate_task`. Built-in
+adapters additionally preflight configured model allow-lists. Antigravity also
+checks its MCP server-name syntax and the SDK's prohibition on combining an
+allow-list with a deny-list. SDK-version-dependent Antigravity tool vocabulary
+is still validated at dispatch, after the installed SDK supplies its enum.
+
 | Field | Claude | Codex | Antigravity |
 |-------|--------|-------|-------------|
 | `budget_usd` | Mapped (`max_budget_usd`, fails closed under SDK drift) | Rejected | Rejected |