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

{agent_runtime_kit-0.1.0 → agent_runtime_kit-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-runtime-kit
-Version: 0.1.0
+Version: 0.1.1
 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
@@ -11,7 +11,6 @@ License-File: LICENSE
 Keywords: agents,antigravity,claude,codex,sdk
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -22,13 +21,13 @@ Requires-Python: >=3.10
 Provides-Extra: all
 Requires-Dist: claude-agent-sdk>=0.2.87; extra == 'all'
 Requires-Dist: google-antigravity>=0.1.2; extra == 'all'
-Requires-Dist: openai-codex>=0.1.0b2; extra == 'all'
+Requires-Dist: openai-codex>=0.1.0b3; extra == 'all'
 Provides-Extra: antigravity
 Requires-Dist: google-antigravity>=0.1.2; extra == 'antigravity'
 Provides-Extra: claude
 Requires-Dist: claude-agent-sdk>=0.2.87; extra == 'claude'
 Provides-Extra: codex
-Requires-Dist: openai-codex>=0.1.0b2; extra == 'codex'
+Requires-Dist: openai-codex>=0.1.0b3; extra == 'codex'
 Description-Content-Type: text/markdown
 
 # agent-runtime-kit
@@ -103,16 +102,18 @@ asyncio.run(main())
 
 `AgentTask` supports goal, system prompt, working directory, permission profile,
 MCP stdio servers, session/resume handles, output schema, budget, metadata, and
-an async event sink.
+an async event sink. Where a runtime cannot honor a field (for example only
+Claude maps `budget_usd`; Codex and Antigravity reject it with a typed
+`UnsupportedTaskInputError`) the adapter raises rather than silently dropping it.
 
 `AgentResult` returns output, finish reason, parsed structured output, usage,
 cost, session id, artifacts, tool-call audits, and provider metadata.
 
 ## Docs
 
-- [Quickstart](docs/quickstart.md)
-- [Provider diagnostics](docs/providers.md)
-- [Capability matrix](docs/capability-matrix.md)
-- [Live smoke tests](docs/live-smoke.md)
-- [Mestre migration notes](docs/mestre-migration.md)
-- [Publish checklist](docs/publish-checklist.md)
+- [Quickstart](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/quickstart.md)
+- [Provider diagnostics](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/providers.md)
+- [Capability matrix](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/capability-matrix.md)
+- [Live smoke tests](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/live-smoke.md)
+- [Mestre migration notes](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/mestre-migration.md)
+- [Publish checklist](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/publish-checklist.md)

{agent_runtime_kit-0.1.0 → agent_runtime_kit-0.1.1}/README.md

@@ -70,16 +70,18 @@ asyncio.run(main())
 
 `AgentTask` supports goal, system prompt, working directory, permission profile,
 MCP stdio servers, session/resume handles, output schema, budget, metadata, and
-an async event sink.
+an async event sink. Where a runtime cannot honor a field (for example only
+Claude maps `budget_usd`; Codex and Antigravity reject it with a typed
+`UnsupportedTaskInputError`) the adapter raises rather than silently dropping it.
 
 `AgentResult` returns output, finish reason, parsed structured output, usage,
 cost, session id, artifacts, tool-call audits, and provider metadata.
 
 ## Docs
 
-- [Quickstart](docs/quickstart.md)
-- [Provider diagnostics](docs/providers.md)
-- [Capability matrix](docs/capability-matrix.md)
-- [Live smoke tests](docs/live-smoke.md)
-- [Mestre migration notes](docs/mestre-migration.md)
-- [Publish checklist](docs/publish-checklist.md)
+- [Quickstart](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/quickstart.md)
+- [Provider diagnostics](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/providers.md)
+- [Capability matrix](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/capability-matrix.md)
+- [Live smoke tests](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/live-smoke.md)
+- [Mestre migration notes](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/mestre-migration.md)
+- [Publish checklist](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/publish-checklist.md)

agent_runtime_kit-0.1.1/docs/capability-matrix.md

@@ -0,0 +1,72 @@
+# Capability Matrix
+
+| Capability | Claude Agent SDK | OpenAI Codex SDK | Google Antigravity SDK |
+|------------|------------------|------------------|------------------------|
+| Optional extra | `claude` | `codex` | `antigravity` |
+| Core import without extra | Yes | Yes | Yes |
+| 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 |
+| MCP stdio servers | Yes | No per-task MCP config | Yes, without per-server env |
+| Permission mapping | `permission_mode` | approval mode + sandbox | capabilities + policies |
+| Streaming output events | Yes — incremental output/tool events while the SDK runs | Not enabled in v1 adapter | Yes — from response chunks |
+| Tool audit events | Yes — from streamed message blocks | Yes — parsed from `TurnResult` items | Yes — from tool chunks |
+| Missing package diagnostics | Yes (`AgentRuntimeUnavailableError`) | Yes (`AgentRuntimeUnavailableError`) | Yes (`AgentRuntimeUnavailableError`) |
+| Missing credential diagnostics | Provider-owned/local auth | Provider-owned/local auth | `GEMINI_API_KEY` or `GOOGLE_API_KEY` |
+| 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.
+
+## Permission mapping
+
+A single portable `PermissionMode` maps to each vendor's native controls. The
+same profile yields different but intentionally aligned postures per runtime;
+review this table before assuming a mode is equivalent everywhere.
+
+| `PermissionMode` | Claude `permission_mode` | Codex `approval_mode` + sandbox | Antigravity toolset + policy |
+|------------------|--------------------------|---------------------------------|------------------------------|
+| `STRICT` | `plan` | `deny_all` (never escalate) | read-only toolset, no `allow_all` policy |
+| `CAUTIOUS` | `acceptEdits` | `deny_all` (never escalate) | nondestructive toolset (no `run_command`), `allow_all` policy |
+| `DEFAULT` | `default` | `auto_review` (escalations auto-adjudicated) | nondestructive toolset (no `run_command`), `allow_all` policy |
+| `PERMISSIVE` | `bypassPermissions` | `auto_review` (escalations auto-adjudicated) | all tools, `allow_all` policy |
+
+Codex sandbox is derived from `FilesystemAccess`, independent of the approval
+mode: `READ_ONLY` → `read_only`, `WORKSPACE_WRITE` → `workspace_write`,
+`FULL_ACCESS` → `full_access`.
+
+Antigravity toolset notes: the table above describes the default posture when
+`allowed_tools` is empty. A `READ_ONLY` filesystem forces the read-only toolset
+regardless of mode. User-supplied `allowed_tools`/`disallowed_tools` override the
+defaults and are validated against the `BuiltinTools` enum (for example
+`"view_file"`, not `"Read"`); an unknown name raises `UnsupportedTaskInputError`.
+
+## Rejected inputs
+
+Each adapter raises `UnsupportedTaskInputError` for task fields it has no SDK
+surface to honor, rather than dropping them silently.
+
+| Field | Claude | Codex | Antigravity |
+|-------|--------|-------|-------------|
+| `budget_usd` | Mapped (`max_budget_usd`) | Rejected | Rejected |
+| `permissions.network` | Rejected | Rejected | Rejected |
+| `allowed_tools` / `disallowed_tools` | Mapped | Rejected | Mapped (`disallowed_tools` → `disabled_tools`); allow-list and deny-list are mutually exclusive and rejected if combined |
+| `mcp_servers` | Mapped | Rejected (no per-task MCP) | Mapped, without per-server `env` |
+
+Two task fields are informational only and not enforced by any built-in adapter:
+`AgentTask.sdk_executions` (carried into events as a hint) and
+`SessionResumeState.transcript` (adapters resume by `session_id`).
+
+Claude additionally records any vendor-option kwargs it had to drop due to SDK
+drift in `AgentResult.metadata["dropped_options"]`, so silent omission stays
+observable.
+
+## Session storage (Antigravity)
+
+Antigravity session and app-data directories are written under
+`$XDG_CACHE_HOME/agent-runtime-kit` (default `~/.cache/agent-runtime-kit`),
+created with `0o700` permissions. This replaces the previous world-shared
+`/tmp` location so transcripts survive reboots and are not exposed to other
+users. Override the base directory with
+`AntigravityAgentRuntime(data_dir=...)`.

agent_runtime_kit-0.1.1/docs/providers.md

@@ -0,0 +1,55 @@
+# Provider Diagnostics
+
+`agent-runtime-kit` keeps provider setup checks explicit. Each runtime exposes
+`availability()` and returns a `RuntimeAvailability` value with:
+
+- runtime kind
+- availability flag
+- reason
+- message
+- package name
+- installed version when discoverable
+
+Claude uses the `claude-agent-sdk` package and maps working directory,
+permissions, MCP servers, sessions, structured output, tool allow/deny lists,
+and budget where supported by the installed SDK. It streams incremental output
+and tool events while the SDK runs, and sets `finish_reason="max_turns"` when a
+turn is truncated by the max-turns limit. `permissions.network` has no SDK
+surface and is rejected with a typed error. Any option kwargs dropped because a
+future SDK renamed or removed them are recorded in
+`AgentResult.metadata["dropped_options"]` rather than discarded silently.
+
+Codex uses the `openai-codex` package and maps working directory, session
+resume, approval mode, sandbox, structured output, model, and reasoning effort.
+Approval mode follows `PermissionMode`: `STRICT`/`CAUTIOUS` → `deny_all` (never
+escalate beyond the sandbox), `DEFAULT`/`PERMISSIVE` → `auto_review`
+(escalations auto-adjudicated). Tool audits are parsed from `TurnResult.items`
+(command executions, MCP tool calls, dynamic tool calls, web searches), and a
+`TurnResult.status` of `failed`/`interrupted` maps to the matching
+`finish_reason`. `budget_usd`, `permissions.network`, `allowed_tools`,
+`disallowed_tools`, and `mcp_servers` have no per-task SDK surface and are
+rejected with typed errors. The constructor defaults to
+`config_overrides=("features.plugins=false",)` so headless runs are
+deterministic and do not pick up host-local Codex plugin configuration; pass a
+different tuple to opt in.
+
+Antigravity uses the `google-antigravity` package and maps API key,
+workspace, permission-derived capabilities/policies, MCP stdio servers,
+conversation id, structured output, session directories, model, and tool
+events. `disallowed_tools` maps to `CapabilitiesConfig.disabled_tools`, and an
+allow-list and a deny-list are mutually exclusive (the SDK forbids combining
+enabled and disabled tool lists), so supplying both is rejected. Tool names are
+validated against the `BuiltinTools` enum (`"view_file"`, not `"Read"`).
+`budget_usd` and `permissions.network` are rejected with typed errors, and
+MCP server configs do not accept per-server env values. The default tool posture
+with no `allowed_tools` is:
+
+| `PermissionMode` (or `READ_ONLY` filesystem) | Toolset | Policy |
+|----------------------------------------------|---------|--------|
+| `STRICT`, or any `READ_ONLY` filesystem | read-only | none (no `allow_all`) |
+| `CAUTIOUS`, `DEFAULT` | nondestructive (no `run_command`) | `allow_all` |
+| `PERMISSIVE` | all tools | `allow_all` |
+
+Session and app-data directories are written under
+`$XDG_CACHE_HOME/agent-runtime-kit` (default `~/.cache/agent-runtime-kit`,
+`0o700`), overridable via `AntigravityAgentRuntime(data_dir=...)`.

agent_runtime_kit-0.1.1/docs/publish-checklist.md

@@ -0,0 +1,77 @@
+# Publish Checklist
+
+`agent-runtime-kit` is not published yet.
+
+## Current Name Check
+
+Checked on 2026-06-10 from this workspace:
+
+```bash
+python - <<'PY'
+import urllib.error, urllib.request
+try:
+    urllib.request.urlopen("https://pypi.org/pypi/agent-runtime-kit/json", timeout=10)
+    print("TAKEN")
+except urllib.error.HTTPError as exc:
+    print("FREE" if exc.code == 404 else f"HTTP_{exc.code}")
+PY
+```
+
+Result: `FREE`.
+
+Re-run this immediately before publishing. A 404 means the name is still
+available; any 200 response means it has been claimed.
+
+## Release Gate
+
+Continuous integration (`.github/workflows/ci.yml`) runs `ruff`, `mypy`, and
+`pytest` on every pull request and push to `main` across Python 3.10–3.13 in
+both the core-only and all-extras dependency lanes, so gate results no longer
+depend on which extras happen to be installed locally. The publish workflow
+itself also gates on tests: its `test` job (core on 3.10, all extras on 3.13)
+must pass before the `build` job runs, so a release cannot be built or published
+unless `ruff`/`mypy`/`pytest` are green against the release tag.
+
+To reproduce the gate locally before tagging:
+
+- `uv run ruff check .`
+- `uv run mypy`
+- `uv run pytest`
+- `uv run python -m build`
+- Optional: provider-specific live smoke tests from `docs/live-smoke.md`
+
+## Trusted Publishing Setup
+
+Use PyPI Trusted Publishing rather than a long-lived API token.
+
+For a new package, create a pending publisher on PyPI with:
+
+- PyPI project name: `agent-runtime-kit`
+- Owner: `ebarti`
+- Repository name: `agent-runtime-kit`
+- Workflow name: `publish-pypi.yml`
+- Environment name: `pypi`
+
+The workflow is `.github/workflows/publish-pypi.yml`. It publishes when a
+GitHub release is published and also supports manual dispatch with a release
+tag such as `v0.1.0`.
+
+## Metadata Gate
+
+- Confirm `pyproject.toml` package name is `agent-runtime-kit`.
+- Confirm Python support remains `>=3.10`.
+- Confirm optional extras resolve for `claude`, `codex`, `antigravity`, and
+  `all`.
+- Confirm README links render on PyPI.
+- Confirm `LICENSE` is included.
+
+## Publish
+
+After configuring the pending publisher on PyPI, publish the existing first
+release by manually running the `Publish to PyPI` workflow with:
+
+```text
+tag = v0.1.0
+```
+
+Do not publish until the release gate passes and the PyPI name check is fresh.

{agent_runtime_kit-0.1.0 → agent_runtime_kit-0.1.1}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["hatchling>=1.25"]
+requires = ["hatchling>=1.26"]
 build-backend = "hatchling.build"
 
 [project]
 name = "agent-runtime-kit"
-version = "0.1.0"
+version = "0.1.1"
 description = "One typed runtime API for Claude, Codex, and Antigravity agent SDKs."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -14,7 +14,6 @@ keywords = ["agents", "claude", "codex", "antigravity", "sdk"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
@@ -26,12 +25,14 @@ dependencies = []
 
 [project.optional-dependencies]
 claude = ["claude-agent-sdk>=0.2.87"]
-codex = ["openai-codex>=0.1.0b2"]
+# 0.1.0b3 floor: earlier betas pin a codex binary with no manylinux wheels,
+# making the extra uninstallable on glibc Linux.
+codex = ["openai-codex>=0.1.0b3"]
 antigravity = ["google-antigravity>=0.1.2"]
 all = [
     "claude-agent-sdk>=0.2.87",
     "google-antigravity>=0.1.2",
-    "openai-codex>=0.1.0b2",
+    "openai-codex>=0.1.0b3",
 ]
 
 [project.urls]
@@ -48,9 +49,23 @@ dev = [
     "ruff>=0.8",
 ]
 
+[tool.uv]
+# openai-codex-cli-bin ships per-platform binary wheels; require the platforms we
+# develop and run CI on so resolution never locks a version missing one of them.
+required-environments = [
+    "sys_platform == 'darwin' and platform_machine == 'arm64'",
+    "sys_platform == 'linux' and platform_machine == 'x86_64'",
+]
+# openai-codex pins exact pre-release builds of its CLI binary; the pre-release
+# marker here opts that one package into pre-release resolution.
+constraint-dependencies = ["openai-codex-cli-bin>=0.134.0a1"]
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/agent_runtime_kit"]
 
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "docs", "examples", "README.md", "LICENSE", "pyproject.toml"]
+
 [tool.ruff]
 line-length = 100
 target-version = "py310"
@@ -64,6 +79,10 @@ packages = ["agent_runtime_kit"]
 strict = true
 warn_unused_configs = true
 
+[[tool.mypy.overrides]]
+module = ["claude_agent_sdk.*", "openai_codex.*", "google.antigravity.*"]
+ignore_missing_imports = true
+
 [tool.pytest.ini_options]
 markers = [
     "live: optional provider smoke tests that require explicit credentials and opt-in flags",

{agent_runtime_kit-0.1.0 → agent_runtime_kit-0.1.1}/src/agent_runtime_kit/_types.py

@@ -175,7 +175,12 @@ class ArtifactRef:
 
 @dataclass(frozen=True)
 class SessionResumeState:
-    """Opaque session handle carried between invocations."""
+    """Opaque session handle carried between invocations.
+
+    ``transcript`` is informational only: it is an opaque payload a caller may
+    carry between turns. The built-in adapters do not consume it (they resume by
+    ``session_id``), so populating it does not change adapter behavior.
+    """
 
     session_id: str
     transcript: tuple[Any, ...] = ()
@@ -183,7 +188,15 @@ class SessionResumeState:
 
 @dataclass(frozen=True)
 class Usage:
-    """Token and cost metadata reported by a runtime."""
+    """Token and cost metadata reported by a runtime.
+
+    ``input_tokens`` counts prompt tokens excluding Anthropic-style cache reads and
+    cache creation, which are reported separately in ``cache_read_tokens`` and
+    ``cache_creation_tokens``. ``total_tokens`` is the vendor-reported total when the
+    runtime provides one, and ``None`` when it does not (so "unknown" is
+    distinguishable from zero). ``cost_usd`` is ``0.0`` when the provider reports no
+    cost.
+    """
 
     input_tokens: int = 0
     output_tokens: int = 0
@@ -204,6 +217,9 @@ class AgentTask:
     mcp_servers: tuple[McpServerConfig, ...] = ()
     permissions: PermissionProfile = field(default_factory=PermissionProfile)
     event_sink: EventSink | None = None
+    # Informational only: carried into task events for observability, not enforced
+    # by the built-in adapters (no vendor SDK exposes a portable turn-count limit
+    # this maps onto). Treated as a hint, never as a hard cap.
     sdk_executions: int = 1
     budget_usd: float | None = None
     session_id: str | None = None

{agent_runtime_kit-0.1.0 → agent_runtime_kit-0.1.1}/src/agent_runtime_kit/adapters/_common.py

@@ -11,6 +11,7 @@ from typing import Any
 from agent_runtime_kit._errors import UnsupportedTaskInputError
 from agent_runtime_kit._types import (
     AgentRuntimeKind,
+    AgentTask,
     AvailabilityReason,
     RuntimeAvailability,
 )
@@ -103,16 +104,73 @@ def parse_json_output(output: str) -> Any | None:
         return None
 
 
-def filter_supported_kwargs(factory: Any, kwargs: Mapping[str, Any]) -> dict[str, Any]:
-    """Drop kwargs unsupported by an injected or vendor options constructor."""
+def reject_unsupported_inputs(
+    kind: AgentRuntimeKind,
+    task: AgentTask,
+    *,
+    budget: bool,
+    network: bool,
+    tool_filters: bool,
+) -> None:
+    """Raise ``UnsupportedTaskInputError`` for task fields a runtime cannot honor.
+
+    Each flag selects a field whose silent omission would mislead the caller. The
+    project contract is to reject these inputs rather than drop them quietly, so an
+    adapter passes ``True`` only for fields it has no SDK surface to honor.
+    """
+
+    if budget and task.budget_usd is not None:
+        raise UnsupportedTaskInputError(
+            kind,
+            "budget_usd",
+            "this runtime does not expose a cost budget; remove budget_usd to proceed",
+        )
+    if network and task.permissions.network is not None:
+        raise UnsupportedTaskInputError(
+            kind,
+            "permissions.network",
+            "this runtime does not expose network access control",
+        )
+    if tool_filters:
+        if task.permissions.allowed_tools:
+            raise UnsupportedTaskInputError(
+                kind,
+                "permissions.allowed_tools",
+                "this runtime does not expose a tool allow-list",
+            )
+        if task.permissions.disallowed_tools:
+            raise UnsupportedTaskInputError(
+                kind,
+                "permissions.disallowed_tools",
+                "this runtime does not expose a tool deny-list",
+            )
+
+
+def filter_supported_kwargs(
+    factory: Any, kwargs: Mapping[str, Any]
+) -> tuple[dict[str, Any], list[str]]:
+    """Split kwargs into those the constructor accepts and those it does not.
+
+    This exists to tolerate vendor option drift: a future SDK version may rename or
+    remove an option this adapter builds. Rather than crash, unsupported keys are
+    dropped, but drops must be observable, so the dropped key names are returned
+    alongside the accepted kwargs and surfaced in ``AgentResult.metadata``.
+    """
 
     try:
         signature = inspect.signature(factory)
     except (TypeError, ValueError):
-        return dict(kwargs)
+        return dict(kwargs), []
     if any(param.kind is inspect.Parameter.VAR_KEYWORD for param in signature.parameters.values()):
-        return dict(kwargs)
-    return {key: value for key, value in kwargs.items() if key in signature.parameters}
+        return dict(kwargs), []
+    supported: dict[str, Any] = {}
+    dropped: list[str] = []
+    for key, value in kwargs.items():
+        if key in signature.parameters:
+            supported[key] = value
+        else:
+            dropped.append(key)
+    return supported, dropped
 
 
 def _extra_name(kind: AgentRuntimeKind) -> str: