agent-runtime-kit 0.5.2__tar.gz → 0.5.3__tar.gz

{agent_runtime_kit-0.5.2 → agent_runtime_kit-0.5.3}/CHANGELOG.md

@@ -5,6 +5,32 @@ 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.3 - 2026-10-02
+
+### Added
+
+- Codex tasks can request provider-native named permission profiles through
+  `PermissionProfile(native_profile="...")`, with conflicting settings rejected
+  and the effective policy preserved across reused sessions.
+- Claude runtime exposes opt-in `verbatim_prompts=True` for literal composed
+  goals, with a typed refusal if the installed SDK cannot honor the option.
+
+### Changed
+
+- Updated tested Claude Agent SDK to `0.2.163`, Google Antigravity SDK to
+  `0.1.20`, and the exactly coupled Codex SDK and CLI to `0.160.0`.
+- Raised the Codex SDK minimum to `0.157.1` for native named-profile support.
+- Quickstart and examples now provide runnable offline, structured-output,
+  event-streaming, diagnostics, and provider-task flows.
+
+### Fixed
+
+- Codex named permission profiles no longer receive a legacy sandbox override
+  that could bypass the requested profile.
+- Antigravity explicit read-only allowlists retain directory/search tools after
+  the SDK removes them from default tool collections, without re-enabling them
+  by default or admitting deprecated write tools.
+
 ## 0.5.2 - 2026-09-19
 
 ### Changed

agent_runtime_kit-0.5.3/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: agent-runtime-kit
+Version: 0.5.3
+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
+Project-URL: Issues, https://github.com/ebarti/agent-runtime-kit/issues
+Author: Eloi Barti
+License-Expression: MIT
+License-File: LICENSE
+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
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+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
+Requires-Dist: tomli<3,>=2; python_version < '3.11'
+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'
+Requires-Dist: openai-codex<0.161,>=0.157.1; extra == 'all'
+Provides-Extra: antigravity
+Requires-Dist: google-antigravity<0.2,>=0.1.2; extra == 'antigravity'
+Provides-Extra: claude
+Requires-Dist: claude-agent-sdk<0.3,>=0.2.87; extra == 'claude'
+Provides-Extra: codex
+Requires-Dist: openai-codex<0.161,>=0.157.1; extra == 'codex'
+Description-Content-Type: text/markdown
+
+# agent-runtime-kit
+
+`agent-runtime-kit` gives Python 3.10+ applications one typed, async API for
+running coding-agent tasks with Claude Agent SDK, OpenAI Codex SDK, or Google
+Antigravity SDK. It exposes capability checks, events, diagnostics, and results
+while keeping each provider's permissions and supported inputs explicit.
+
+## Install and try it offline
+
+The core install has no vendor SDK or credential requirement:
+
+```bash
+python -m pip install agent-runtime-kit
+```
+
+```python
+import asyncio
+
+from agent_runtime_kit import AgentKit, FakeAgentRuntime
+
+
+async def main() -> None:
+    async with AgentKit() as kit:
+        result = await kit.run(
+            FakeAgentRuntime(output="offline example complete"),
+            goal="Demonstrate a task result",
+        )
+        if not result.is_success:
+            raise RuntimeError(result.error or result.finish_reason)
+        print(result.output)
+
+
+asyncio.run(main())
+```
+
+This prints `offline example complete`. The fake runtime returns a deterministic
+result; it does not inspect the repository or contact a provider. Run the file
+version with `python -m examples.basic_offline` from a source checkout.
+
+## Run a real provider
+
+Install only the provider you use, then configure its supported authentication:
+
+```bash
+python -m pip install "agent-runtime-kit[claude]"      # Claude Agent SDK
+python -m pip install "agent-runtime-kit[codex]"       # OpenAI Codex SDK
+python -m pip install "agent-runtime-kit[antigravity]" # Google Antigravity SDK
+```
+
+`agent-runtime-kit[all]` installs all three. A real task may use a paid provider
+and may invoke tools. After setting up the chosen provider, run one explicitly
+from a source checkout:
+
+```bash
+python -m examples.provider_task claude
+```
+
+Choose `codex` or `antigravity` instead to use that runtime. The example checks
+package availability, probes setup, requests read-only filesystem access, and
+checks `result.is_success`. Readiness only indicates whether a task is worth
+attempting; it cannot guarantee the provider will accept the request.
+
+The adapters share `AgentTask` and `AgentResult`, but inputs are not silently
+discarded. For example, Claude supports per-task MCP servers and a cost budget;
+Codex does not expose either per task; Antigravity supports MCP servers without
+per-server environment values. Unsupported inputs raise typed errors. The
+provider's native model selection is used unless you set a model explicitly.
+
+## Guides
+
+- [Quickstart](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/quickstart.md): install, offline result, and first provider run
+- [Examples](https://github.com/ebarti/agent-runtime-kit/blob/main/examples/README.md): runnable commands and expected results
+- [Recipes](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/recipes.md): results, events, preflight, permissions, sessions, and MCP
+- [Provider diagnostics](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/providers.md) and [capability matrix](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/capability-matrix.md)
+- [Deadlines and cancellation](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/task-control.md) and [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) and [SDK evolution agent](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/sdk-evolution-agent.md)
+
+The package is a runtime layer, not a router, queue, hosted service, or full
+agent framework. Applications choose when and where to run a task.

agent_runtime_kit-0.5.3/README.md

@@ -0,0 +1,79 @@
+# agent-runtime-kit
+
+`agent-runtime-kit` gives Python 3.10+ applications one typed, async API for
+running coding-agent tasks with Claude Agent SDK, OpenAI Codex SDK, or Google
+Antigravity SDK. It exposes capability checks, events, diagnostics, and results
+while keeping each provider's permissions and supported inputs explicit.
+
+## Install and try it offline
+
+The core install has no vendor SDK or credential requirement:
+
+```bash
+python -m pip install agent-runtime-kit
+```
+
+```python
+import asyncio
+
+from agent_runtime_kit import AgentKit, FakeAgentRuntime
+
+
+async def main() -> None:
+    async with AgentKit() as kit:
+        result = await kit.run(
+            FakeAgentRuntime(output="offline example complete"),
+            goal="Demonstrate a task result",
+        )
+        if not result.is_success:
+            raise RuntimeError(result.error or result.finish_reason)
+        print(result.output)
+
+
+asyncio.run(main())
+```
+
+This prints `offline example complete`. The fake runtime returns a deterministic
+result; it does not inspect the repository or contact a provider. Run the file
+version with `python -m examples.basic_offline` from a source checkout.
+
+## Run a real provider
+
+Install only the provider you use, then configure its supported authentication:
+
+```bash
+python -m pip install "agent-runtime-kit[claude]"      # Claude Agent SDK
+python -m pip install "agent-runtime-kit[codex]"       # OpenAI Codex SDK
+python -m pip install "agent-runtime-kit[antigravity]" # Google Antigravity SDK
+```
+
+`agent-runtime-kit[all]` installs all three. A real task may use a paid provider
+and may invoke tools. After setting up the chosen provider, run one explicitly
+from a source checkout:
+
+```bash
+python -m examples.provider_task claude
+```
+
+Choose `codex` or `antigravity` instead to use that runtime. The example checks
+package availability, probes setup, requests read-only filesystem access, and
+checks `result.is_success`. Readiness only indicates whether a task is worth
+attempting; it cannot guarantee the provider will accept the request.
+
+The adapters share `AgentTask` and `AgentResult`, but inputs are not silently
+discarded. For example, Claude supports per-task MCP servers and a cost budget;
+Codex does not expose either per task; Antigravity supports MCP servers without
+per-server environment values. Unsupported inputs raise typed errors. The
+provider's native model selection is used unless you set a model explicitly.
+
+## Guides
+
+- [Quickstart](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/quickstart.md): install, offline result, and first provider run
+- [Examples](https://github.com/ebarti/agent-runtime-kit/blob/main/examples/README.md): runnable commands and expected results
+- [Recipes](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/recipes.md): results, events, preflight, permissions, sessions, and MCP
+- [Provider diagnostics](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/providers.md) and [capability matrix](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/capability-matrix.md)
+- [Deadlines and cancellation](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/task-control.md) and [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) and [SDK evolution agent](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/sdk-evolution-agent.md)
+
+The package is a runtime layer, not a router, queue, hosted service, or full
+agent framework. Applications choose when and where to run a task.

{agent_runtime_kit-0.5.2 → agent_runtime_kit-0.5.3}/docs/providers.md

@@ -153,6 +153,17 @@ per-query session id. `AgentResult.metadata["sdk_process_reuse_scope"]` reports
 `"conversation"` or `"shared"` accordingly. The runtime restarts the SDK process
 when the option fingerprint changes and evicts it after SDK exceptions.
 
+With Claude Agent SDK 0.2.158 or newer, pass
+`ClaudeAgentRuntime(verbatim_prompts=True)` when goals contain composed or
+third-party text. This opts into the SDK's literal prompt delivery: `@path`
+mentions and slash commands are not expanded or dispatched. The default stays
+`False`. An older SDK that cannot accept the requested option raises
+`UnsupportedTaskInputError` before dispatch. The bundled Claude CLI must be
+2.1.248 or newer; older custom CLIs may ignore the option. Verbatim delivery also
+skips the CLI's initial attachment pass, including MCP mentions, nested
+`CLAUDE.md`/rules, and skill/tool listings; some context arrives after the first
+tool call instead. It applies to both one-shot and reused-process execution.
+
 Codex uses the `openai-codex` package and maps working directory, session
 resume, approval mode, sandbox, structured output, model, and reasoning effort.
 Approval mode follows `PermissionMode`: `STRICT`/`CAUTIOUS` → `deny_all` (never
@@ -233,6 +244,13 @@ dropped only for `STRICT`. When an explicit `allowed_tools` list is combined wit
 a `READ_ONLY` filesystem, any non-read-only tool in it is rejected rather than
 silently granted.
 
+Antigravity 0.1.20 removes `list_directory`, `search_directory`, and `find_file`
+from its default read-only and nondestructive collections. Request them
+explicitly through `allowed_tools` when needed; they remain valid under
+`READ_ONLY` or `STRICT`. Default and deny-list baselines continue to follow the
+SDK's collections. The SDK also adds `schedule` to those collections; callers
+that need a narrower toolset should provide an explicit allow-list.
+
 A deny-list under a `READ_ONLY` filesystem (or `STRICT`) subtracts from the
 read-only toolset, and under `DEFAULT`/`CAUTIOUS` from the nondestructive
 toolset — `disabled_tools` alone would re-enable every unnamed write or

agent_runtime_kit-0.5.3/docs/quickstart.md

@@ -0,0 +1,114 @@
+# Quickstart
+
+`agent-runtime-kit` requires Python 3.10 or newer. Install the core package to
+run the credential-free example:
+
+```bash
+python -m pip install agent-runtime-kit
+```
+
+If you cloned the repository, run examples from its root with
+`python -m examples.basic_offline`. For a standalone script, save the following
+as `offline.py` and run `python offline.py`:
+
+```python
+import asyncio
+
+from agent_runtime_kit import AgentKit, FakeAgentRuntime
+
+
+async def main() -> None:
+    async with AgentKit() as kit:
+        result = await kit.run(
+            FakeAgentRuntime(output="offline example complete"),
+            goal="Demonstrate a task result",
+        )
+        if not result.is_success:
+            raise RuntimeError(result.error or result.finish_reason)
+        print(result.output)
+
+
+asyncio.run(main())
+```
+
+Expected output: `offline example complete`. `FakeAgentRuntime` is a
+deterministic test runtime. Its goal is carried through the API, but it does not
+read files or call a model.
+
+## Choose a provider
+
+Install exactly the extra you need, or use `agent-runtime-kit[all]`:
+
+```bash
+python -m pip install "agent-runtime-kit[claude]"
+python -m pip install "agent-runtime-kit[codex]"
+python -m pip install "agent-runtime-kit[antigravity]"
+```
+
+Set up authentication with the provider's supported mechanism: [Claude Agent
+SDK](https://code.claude.com/docs/en/agent-sdk/overview), [Codex
+authentication](https://learn.chatgpt.com/docs/auth), or [Antigravity SDK
+setup](https://github.com/google-antigravity/antigravity-sdk-python). For
+example, Codex supports `codex login` and `codex login status`; Antigravity's
+API-key path uses `GEMINI_API_KEY`. See [provider notes](providers.md) for this
+package's exact adapter mappings.
+
+From a source checkout, run one chosen provider:
+
+```bash
+python -m examples.provider_task claude
+```
+
+The command takes `claude`, `codex`, or `antigravity`. It may make a paid model
+call. It checks the installed package and bounded readiness probe, then asks
+the provider to summarize the current directory with explicit read-only
+filesystem access. A confirmed `NOT_READY` result stops the example;
+`INDETERMINATE` also stops until you explicitly pass `--attempt-indeterminate`.
+That flag is a caller policy choice, not proof of readiness.
+
+## Use the API directly
+
+```python
+import asyncio
+from pathlib import Path
+
+from agent_runtime_kit import AgentKit, ReadinessStatus
+
+
+async def main() -> None:
+    async with AgentKit() as kit:
+        provider = "claude"
+        availability = kit.availability_for(provider)
+        if not availability.available:
+            raise RuntimeError(availability.message)
+
+        readiness = await kit.readiness_for(provider)
+        if readiness.status is not ReadinessStatus.READY_TO_ATTEMPT:
+            raise RuntimeError(readiness.message)
+
+        result = await kit.run(
+            provider,
+            goal="Summarize the purpose of this repository in one paragraph.",
+            working_directory=Path.cwd(),
+            permissions="strict",
+            filesystem="read-only",
+        )
+        if not result.is_success:
+            raise RuntimeError(result.error or result.finish_reason)
+        print(result.output)
+
+
+asyncio.run(main())
+```
+
+`AgentKit` lazily resolves and caches built-in runtimes; `async with` closes
+those it created. A runtime instance passed directly to `run` remains the
+caller's responsibility to close. `permissions="strict"` alone does not
+request read-only filesystem access: the default filesystem posture is
+`workspace-write`. Each provider maps permission requests through its own SDK,
+so check the [capability matrix](capability-matrix.md) before relying on a
+particular tool posture.
+
+For typed output and event examples, see the [runnable example
+index](../examples/README.md). The [recipes](recipes.md) explain result
+semantics, compatibility preflight, sessions, and MCP.

agent_runtime_kit-0.5.3/docs/recipes.md

@@ -0,0 +1,125 @@
+# Practical recipes
+
+These recipes use the public API. Start with the [quickstart](quickstart.md)
+and [runnable examples](../examples/README.md).
+
+## Handle results and errors
+
+`run()` can raise for invalid or unsupported inputs, missing runtimes, and
+deadlines. It can also return an `AgentResult` whose `finish_reason` is not
+`done` or whose `error` is set. Always check `is_success` before using output:
+
+```python
+result = await kit.run(
+    "claude",
+    goal="Summarize this repository",
+    permissions="strict",
+    filesystem="read-only",
+)
+if not result.is_success:
+    raise RuntimeError(result.error or result.finish_reason)
+print(result.output)
+```
+
+For `output_type=Summary`, `result.parsed` is a validated instance on a
+successful non-null result. A mismatched payload becomes a failed result.
+Use `result.parsed_output_available` to distinguish an absent structured
+payload from valid JSON `null`; both have `parsed_output is None`. Usage and
+cost fields are `None` when the provider does not report them, while reported
+zero stays zero. Built-in runtimes currently leave `artifacts` empty.
+
+## Separate preflight from setup
+
+Use `kit.validate_task(provider, task)` to list statically detectable
+unsupported fields without dispatching a task. Use
+`kit.availability_for(provider)` for a synchronous, package-only check. Use
+`await kit.readiness_for(provider)` for a bounded setup probe:
+
+```python
+from agent_runtime_kit import AgentTask, ReadinessStatus
+
+task = AgentTask(goal="Summarize this repository")
+report = kit.validate_task("codex", task)
+if not report.supported:
+    for issue in report.issues:
+        print(issue.field, issue.message)
+
+availability = kit.availability_for("codex")
+if availability.available:
+    readiness = await kit.readiness_for("codex")
+    if readiness.status is ReadinessStatus.READY_TO_ATTEMPT:
+        print("Setup detected; a task may be attempted")
+```
+
+These checks answer different questions. Static support does not prove that a
+package is installed. Package availability does not prove credentials or
+network access. `READY_TO_ATTEMPT` means setup was detected, not that a task
+will succeed. `INDETERMINATE` requires an application policy decision; it is
+not a positive readiness result. The [provider diagnostics](providers.md)
+describe safe probe behavior.
+
+## Request permissions explicitly
+
+```python
+result = await kit.run(
+    "claude",
+    goal="Summarize this repository",
+    permissions="strict",
+    filesystem="read-only",
+)
+```
+
+The default filesystem request is `workspace-write`, even under `strict`.
+Adapters map both settings to vendor controls; they are not a universal OS
+sandbox guarantee. `permissions.network` has no supported per-task mapping in
+the built-in adapters and is rejected. Tool allow/deny lists and approval
+behavior differ by provider. Read the [capability matrix](capability-matrix.md)
+before requesting a more permissive posture.
+
+`sdk_executions` is an informational task/event field, not a portable turn or
+spend cap. Only Claude maps `budget_usd`; Codex and Antigravity reject it.
+Use [deadlines and cancellation](task-control.md) to bound a task's duration.
+
+## Observe events
+
+`AgentKit.on()` registers a sync or async handler for normalized event names.
+Register before dispatch. Handler failures are swallowed so logging cannot
+break a run; send events to your own durable sink if they must be retained.
+
+```python
+@kit.on("agent.tool.completed")
+def log_tool(event):
+    print(event["summary"])
+```
+
+See `python -m examples.events` for a complete offline run. Events may contain
+redacted or truncated attributes; a tool audit is best-effort evidence of what
+the vendor reported, not proof that no other side effect occurred.
+
+## Resume a session when supported
+
+Pass `session_id` or `resume_from` on a task, but not both. Save a returned
+`result.session_id` if you need it later, and check session support for the
+chosen runtime before reuse. An omitted handle starts a task-isolated
+conversation; process reuse does not imply session reuse. Provider-specific
+session behavior is documented in [provider notes](providers.md).
+
+## Configure an MCP server where supported
+
+```python
+from agent_runtime_kit import AgentTask, McpServerConfig
+
+task = AgentTask(
+    goal="Use the local documentation server",
+    mcp_servers=(McpServerConfig(name="docs", command="my-docs-mcp"),),
+)
+report = kit.validate_task("claude", task)
+if not report.supported:
+    raise ValueError(report.issues)
+```
+
+Claude and Antigravity accept per-task stdio MCP servers; Codex rejects
+per-task MCP configuration. Antigravity does not accept per-server `env` values.
+The command starts only when a real task is dispatched. Choose and trust the
+server executable as you would any local process. See the [capability
+matrix](capability-matrix.md) for other differences.

{agent_runtime_kit-0.5.2 → agent_runtime_kit-0.5.3}/docs/task-control.md

@@ -10,7 +10,10 @@ deadline at call time.
 from agent_runtime_kit import AgentKit, AgentTaskTimeoutError
 
 try:
-    result = await kit.run("codex", goal="Refactor the parser", timeout=30)
+    result = await kit.run(
+        "codex", goal="Inspect the parser", timeout=30,
+        permissions="strict", filesystem="read-only",
+    )
 except AgentTaskTimeoutError as exc:
     print(exc.task_id, exc.deadline)
 ```
@@ -25,23 +28,55 @@ that grace, the runtime instance is quarantined and rejects new runs rather than
 overlapping them; it becomes reusable when the detached cleanup finally settles.
 
 To cancel a task started through `AgentKit`, keep its task id and use the same
-runtime instance or cached kind:
+runtime instance or cached kind. Wait for its started event (or for an early
+completion) before calling `cancel()`; scheduling `kit.run()` with
+`asyncio.create_task()` does not guarantee that it has registered the run yet.
+This example makes a real provider call and may incur charges:
 
 ```python
 import asyncio
 
-task_id = "index-repository"
-running = asyncio.create_task(
-    kit.run("claude", goal="Index the repository", task_id=task_id)
-)
-receipt = await kit.cancel("claude", task_id)
+from agent_runtime_kit import AgentKit
+
+
+async def main() -> None:
+    task_id = "index-repository"
+    started = asyncio.Event()
+    async with AgentKit() as kit:
+
+        @kit.on("agent.task.started")
+        def on_started(event):
+            if event["attributes"]["task_id"] == task_id:
+                started.set()
+
+        running = asyncio.create_task(
+            kit.run(
+                "claude", goal="Index the repository", task_id=task_id,
+                permissions="strict", filesystem="read-only",
+            )
+        )
+        start_wait = asyncio.create_task(started.wait())
+        try:
+            done, _ = await asyncio.wait(
+                {running, start_wait}, return_when=asyncio.FIRST_COMPLETED
+            )
+            if running in done:
+                result = await running  # completed or failed before cancellation
+                print(result.finish_reason)
+                return
+            receipt = await kit.cancel("claude", task_id)
+            print(receipt.disposition)
+            try:
+                result = await running
+                print(result.finish_reason)  # it may finish before cancellation takes effect
+            except asyncio.CancelledError:
+                print("cancelled")
+        finally:
+            start_wait.cancel()
+            await asyncio.gather(start_wait, return_exceptions=True)
 
-try:
-    await running
-except asyncio.CancelledError:
-    pass
 
-print(receipt.disposition)
+asyncio.run(main())
 ```
 
 `cancel()` does not construct a runtime that has not already been cached, and

agent_runtime_kit-0.5.3/examples/README.md

@@ -0,0 +1,41 @@
+# Runnable examples
+
+Run these commands from the repository root with Python 3.10+ after installing
+the package locally (`python -m pip install -e .`), or use `uv run --locked`
+before each `python` command. The commands in this table use the core package,
+need no credentials, and make no provider calls.
+
+| Command | Expected behavior |
+| --- | --- |
+| `python -m examples.basic_offline` | Prints `offline example complete`. The fake returns a fixture; it does not read files. |
+| `python -m examples.structured_output` | Prints `example: Python` after validating a dataclass result. |
+| `python -m examples.events` | Prints `agent.task.started`, `agent.tool.completed`, then `agent.task.completed`. |
+| `python -m examples.diagnostics fake --probe-readiness` | Prints available package and `ready-to-attempt`; no task runs. |
+| `python -m examples.diagnostics codex` | Reports package availability only and exits nonzero if missing. This does not inspect credentials or run a task. |
+
+The following commands use a real vendor runtime. Install its extra and follow
+the [provider setup guide](../docs/quickstart.md#choose-a-provider). A provider
+call may incur charges and may run tools; the examples request strict,
+read-only filesystem access through the adapter. Check the [permission
+mapping](../docs/capability-matrix.md) for each provider's exact behavior.
+
+| Command | Expected behavior |
+| --- | --- |
+| `python -m examples.diagnostics claude --probe-readiness` | Prints package and setup readiness, exiting zero only for `ready-to-attempt`, without running an agent task. |
+| `python -m examples.provider_task claude` | Checks setup and runs one Claude task if ready; prints its output on success. |
+| `python -m examples.provider_task codex` | Runs one Codex task after the same checks. |
+| `python -m examples.provider_task antigravity` | Runs one Antigravity task after the same checks. |
+| `python -m examples.run_same_task claude codex` | Runs the same task sequentially through the two named providers. Nothing runs unless you name it. |
+
+For diagnostics, `not-ready` and `indeterminate` readiness both return a nonzero
+status; applications can choose their own policy for `indeterminate`. Use
+`--attempt-indeterminate` with the provider task or comparison command to
+explicitly attempt a provider whose bounded setup probe could not determine
+readiness. A confirmed `not-ready` status still stops. Missing extras, failed
+results, and provider exceptions print an error and yield a nonzero exit code.
+The commands choose the provider's native model default; set a task model in
+your application when you need a fixed model.
+
+The comparison command closes cached runtime resources at the end of the run.
+No example stores secrets or starts a paid call during import or `--help`.
+See [recipes](../docs/recipes.md) for error handling and input compatibility.

agent_runtime_kit-0.5.3/examples/basic_offline.py

@@ -0,0 +1,20 @@
+"""Run one deterministic task with the vendor-SDK-free core package."""
+
+import asyncio
+
+from agent_runtime_kit import AgentKit, FakeAgentRuntime
+
+
+async def main() -> None:
+    async with AgentKit() as kit:
+        result = await kit.run(
+            FakeAgentRuntime(output="offline example complete"),
+            goal="Demonstrate a task result",
+        )
+        if not result.is_success:
+            raise RuntimeError(result.error or result.finish_reason)
+        print(result.output)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agent_runtime_kit-0.5.3/examples/diagnostics.py

@@ -0,0 +1,33 @@
+"""Inspect package availability and, optionally, bounded setup readiness."""
+
+import argparse
+import asyncio
+
+from agent_runtime_kit import AgentKit, ReadinessStatus
+
+
+async def main(provider: str, probe_readiness: bool) -> int:
+    async with AgentKit() as kit:
+        availability = kit.availability_for(provider)
+        print(f"{provider} package: {'available' if availability.available else 'unavailable'}")
+        if not availability.available:
+            print(availability.message)
+        success = availability.available
+        if probe_readiness:
+            readiness = await kit.readiness_for(provider)
+            print(f"{provider} readiness: {readiness.status.value}")
+            print(readiness.message)
+            success = success and readiness.status is ReadinessStatus.READY_TO_ATTEMPT
+        return 0 if success else 1
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("provider", choices=("fake", "claude", "codex", "antigravity"))
+    parser.add_argument(
+        "--probe-readiness",
+        action="store_true",
+        help="probe provider setup without running an agent task",
+    )
+    arguments = parser.parse_args()
+    raise SystemExit(asyncio.run(main(arguments.provider, arguments.probe_readiness)))