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

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

@@ -5,6 +5,82 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-runtime-kit
-Version: 0.4.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
@@ -115,7 +116,7 @@ caches them per kind, and turns Python types into structured output.
 import asyncio
 from dataclasses import dataclass
 
-from agent_runtime_kit import AgentKit
+from agent_runtime_kit import AgentKit, ReadinessStatus
 
 
 @dataclass
@@ -126,9 +127,9 @@ class RepoSummary:
 
 async def main() -> None:
     async with AgentKit() as kit:
-        diagnostic = kit.availability_for("claude")
-        if not diagnostic.available:
-            raise RuntimeError(diagnostic.message)
+        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",
@@ -146,15 +147,15 @@ 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)
 
@@ -173,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
 
@@ -185,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.4.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
@@ -83,7 +83,7 @@ caches them per kind, and turns Python types into structured output.
 import asyncio
 from dataclasses import dataclass
 
-from agent_runtime_kit import AgentKit
+from agent_runtime_kit import AgentKit, ReadinessStatus
 
 
 @dataclass
@@ -94,9 +94,9 @@ class RepoSummary:
 
 async def main() -> None:
     async with AgentKit() as kit:
-        diagnostic = kit.availability_for("claude")
-        if not diagnostic.available:
-            raise RuntimeError(diagnostic.message)
+        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",
@@ -114,15 +114,15 @@ 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)
 
@@ -141,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
 
@@ -153,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.4.0 → agent_runtime_kit-0.5.0}/docs/api-stability.md

@@ -23,6 +23,11 @@ import the names from the top-level package instead.
   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.
@@ -33,10 +38,37 @@ import the names from the top-level package instead.
   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
@@ -44,7 +76,14 @@ import the names from the top-level package instead.
   `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` when present).
+  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
 
@@ -58,6 +97,13 @@ 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

{agent_runtime_kit-0.4.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 |

{agent_runtime_kit-0.4.0 → agent_runtime_kit-0.5.0}/docs/providers.md

@@ -1,7 +1,8 @@
 # Provider Diagnostics
 
-`agent-runtime-kit` keeps provider setup checks explicit. Each runtime exposes
-`availability()` and returns a `RuntimeAvailability` value with:
+`agent-runtime-kit` separates cheap package discovery from provider setup
+probes. Each runtime's synchronous `availability()` is side-effect-free and
+package-only. It returns a `RuntimeAvailability` value with:
 
 - runtime kind
 - availability flag
@@ -10,9 +11,68 @@
 - package name
 - installed version when discoverable
 
+Availability never imports a vendor SDK, starts a subprocess, reads a
+credential store, calls Google ADC, or contacts a provider. Package presence is
+not a claim that execution will work.
+
+Use the public `await check_readiness(runtime, timeout=5.0)` for an explicit
+credential/setup probe. Registry and hub forms are also available:
+
+```python
+readiness = await registry.readiness_for("codex")
+readiness = await kit.readiness_for("codex")
+all_readiness = await kit.readiness()
+```
+
+`RuntimeReadiness.status` has three outcomes:
+
+- `READY_TO_ATTEMPT`: a supported setup or credential signal was positively
+  established. It does not promise that a later model/network request succeeds.
+- `NOT_READY`: a concrete problem such as a missing package, account, API key,
+  or ADC project was established.
+- `INDETERMINATE`: the runtime uses a provider/local credential chain that
+  cannot be verified safely, lacks the optional readiness extension, or the
+  bounded probe failed/timed out. The caller chooses whether to attempt work.
+
+The built-in probes never return credential values or raw exception messages.
+They report only safe categories such as auth source and exception type. The
+optional `RuntimeReadinessProvider` protocol does not change the required
+`AgentRuntime` protocol. For older third-party runtimes,
+`check_readiness()` maps negative availability to `NOT_READY` and positive
+package presence conservatively to `INDETERMINATE`.
+
+Provider behavior is deliberately specific:
+
+- Claude treats direct API key, OAuth-token, and Bedrock bearer-token signals
+  as `READY_TO_ATTEMPT`. Provider chains and provider-owned local login remain
+  `INDETERMINATE`; probing them would require starting a real task or scraping
+  unsupported credential stores.
+- Codex starts the supported `AsyncCodex` client, calls
+  `account(refresh_token=False)`, and always closes the app-server context. An
+  account is `READY_TO_ATTEMPT`, no account is `NOT_READY`, and startup/API/
+  cleanup failures are `INDETERMINATE`.
+- Antigravity accepts an explicit or ambient Gemini API key, otherwise probes
+  Google Application Default Credentials and project setup in a worker thread
+  so synchronous Google discovery cannot block the event loop. Missing setup
+  is `NOT_READY`; errors and timeouts are `INDETERMINATE`.
+
+For all built-ins at once, the existing sync collector stays package-only while
+the async collector performs bounded readiness checks:
+
+```python
+from agent_runtime_kit.adapters.diagnostics import (
+    collect_provider_diagnostics,
+    collect_provider_readiness,
+)
+
+packages = collect_provider_diagnostics()
+readiness = await collect_provider_readiness(timeout=5.0)
+```
+
 ## Install Model
 
-The plain `agent-runtime-kit` package is the dependency-free core. Use
+The plain `agent-runtime-kit` package is the vendor-SDK-free core and includes
+lightweight JSON Schema validation. Use
 `agent-runtime-kit[all]` when you want Claude, Codex, and Antigravity adapters
 available in one install, or use a single extra such as
 `agent-runtime-kit[codex]` when your application only needs one runtime.
@@ -27,16 +87,33 @@ to the exact missing extra.
 
 All three adapters map the task's system prompt (Claude `system_prompt`, Codex
 `developer_instructions`, Antigravity `system_instructions`) and the `model`
-field (falling back to the `metadata` aliases of the same names).
+field. Model precedence is `AgentTask.model` > legacy `metadata["model"]` > the
+adapter's `default_model=` constructor override > provider-native selection. At
+the final step the adapter omits the SDK model option; it does not impose a
+library-owned model that can go stale. Results always include
+`metadata["model_source"]` (`task`, `metadata`, `constructor`, or
+`provider-native`) and include `metadata["model"]` only when the selected value
+is known. When `supported_models=` is configured, provider-native selection is
+rejected as unverifiable until the caller chooses an explicit model.
 `reasoning_effort` maps to the Claude and Codex `effort` options; Antigravity
 has no reasoning-effort control and rejects the first-class field with a typed
-error (its legacy `metadata["reasoning_effort"]` alias stays ignored, as it
-always has been). Effort values are passed through to the vendor SDK rather
+error. Its legacy `metadata["reasoning_effort"]` alias is rejected too, rather
+than being silently ignored. Effort values are passed through to the vendor SDK rather
 than validated by this library — each vendor defines its own accepted
 vocabulary (for example `claude-agent-sdk` 0.2.x accepts
 `low`/`medium`/`high`/`xhigh`/`max`), and an SDK too old to accept `effort` at
 all records the drop in `AgentResult.metadata["dropped_options"]`.
 
+Usage fields are `None` when a provider omits its usage breakdown or cost.
+Provider-reported zeros remain numeric zero, so callers can distinguish a free
+or zero-token run from missing telemetry.
+
+Every built-in adapter exposes a pure `validate_task()` extension. The public
+`validate_task(runtime, task)`, registry, and `AgentKit` helpers call that richer
+validator when present and otherwise fall back to declared capabilities for
+older third-party runtimes. A report is a static preflight, not an availability
+or credential probe; installed-SDK drift can still make dispatch fail closed.
+
 Claude uses the `claude-agent-sdk` package and maps working directory,
 permissions, filesystem access (a `READ_ONLY` filesystem forces `plan` mode),
 MCP servers, sessions, structured output, tool allow/deny lists, runtime

{agent_runtime_kit-0.4.0 → agent_runtime_kit-0.5.0}/docs/quickstart.md

@@ -6,7 +6,7 @@ Install all first-party runtime adapters:
 pip install "agent-runtime-kit[all]"
 ```
 
-Or install only the dependency-free core:
+Or install only the vendor-SDK-free core:
 
 ```bash
 pip install agent-runtime-kit
@@ -51,9 +51,9 @@ asyncio.run(main())
 
 ## Typed structured output
 
-Pass a type instead of hand-writing JSON schema. Dataclasses and `TypedDict`s
-work out of the box (no dependency); Pydantic v2 models are used through their
-own `model_json_schema`/`model_validate` when you have Pydantic installed.
+Pass a type instead of hand-writing JSON Schema. Dataclasses and `TypedDict`s
+work without Pydantic; Pydantic v2 models are used through their own
+`model_json_schema`/`model_validate` methods and validated with `strict=True`.
 
 ```python
 from dataclasses import dataclass
@@ -75,17 +75,21 @@ async def main() -> None:
             goal="Summarize this repository",
             output_type=RepoSummary,
         )
-        if result.parsed is not None:
+        if result.parsed_output_available:
             print(result.parsed.languages)  # typed: list[str]
         else:
             print(result.error)
 ```
 
-A payload that does not conform yields `finish_reason="failed"` with the
-mismatch in `result.error` — the same convention the adapters use for
-unsatisfied structured output. Unsupported annotations (sets, plain unions,
-...) raise `OutputTypeError` at call time rather than sending a half-true
-schema.
+A malformed raw `output_schema` raises `OutputSchemaError` before execution.
+`AgentKit` strictly validates values requested with `output_type`; a mismatch
+yields `finish_reason="failed"` with the details in `result.error`.
+All built-in adapters also validate results requested with a raw
+`output_schema` and include the failing JSON path in `result.error`.
+Unsupported Python annotations (sets, plain unions, ...) raise
+`OutputTypeError` at call time. For nullable schemas,
+`parsed_output_available=True` with `parsed_output=None` represents valid JSON
+`null`.
 
 ## Events and custom runtimes
 
@@ -118,5 +122,10 @@ runtime = ClaudeAgentRuntime(default_model="claude-sonnet-4-6", reuse_process=Tr
 result = await runtime.run(AgentTask(goal="Summarize this repository"))
 ```
 
-Use `kit.availability()` (or `runtime.availability()`) before dispatching work
-in applications that need clear setup diagnostics.
+Use synchronous `kit.availability()` (or `runtime.availability()`) for a
+side-effect-free package check. Use `await kit.readiness()` or
+`await check_readiness(runtime)` when an application also needs a bounded
+credential/setup probe. Treat `ReadinessStatus.READY_TO_ATTEMPT` as permission
+to try — not a guarantee that the provider, model, or network will accept the
+next request. `NOT_READY` is a confirmed setup problem; `INDETERMINATE` leaves
+the attempt policy to the caller.