agent-runtime-kit 0.1.0__py3-none-any.whl

agent_runtime_kit/__init__.py

@@ -0,0 +1,72 @@
+"""Public API for agent-runtime-kit."""
+
+from agent_runtime_kit._errors import (
+    AgentRuntimeError,
+    AgentRuntimeUnavailableError,
+    RuntimeNotRegisteredError,
+    UnsupportedTaskInputError,
+)
+from agent_runtime_kit._runtime import FakeAgentRuntime
+from agent_runtime_kit._types import (
+    AgentCapabilities,
+    AgentResult,
+    AgentRuntime,
+    AgentRuntimeKind,
+    AgentTask,
+    ArtifactRef,
+    AvailabilityReason,
+    EventSink,
+    FilesystemAccess,
+    McpServerConfig,
+    PermissionMode,
+    PermissionProfile,
+    RuntimeAvailability,
+    SessionResumeState,
+    ToolCallAudit,
+    Usage,
+)
+from agent_runtime_kit.events import (
+    output_delta_event,
+    safe_emit,
+    task_completed_event,
+    task_failed_event,
+    task_started_event,
+    tool_completed_event,
+    tool_requested_event,
+    vendor_turn_event,
+)
+from agent_runtime_kit.registry import RuntimeRegistry, create_default_registry
+
+__all__ = [
+    "AgentCapabilities",
+    "AgentResult",
+    "AgentRuntime",
+    "AgentRuntimeError",
+    "AgentRuntimeKind",
+    "AgentRuntimeUnavailableError",
+    "AgentTask",
+    "ArtifactRef",
+    "AvailabilityReason",
+    "EventSink",
+    "FakeAgentRuntime",
+    "FilesystemAccess",
+    "McpServerConfig",
+    "PermissionMode",
+    "PermissionProfile",
+    "RuntimeAvailability",
+    "RuntimeNotRegisteredError",
+    "RuntimeRegistry",
+    "SessionResumeState",
+    "ToolCallAudit",
+    "UnsupportedTaskInputError",
+    "Usage",
+    "create_default_registry",
+    "output_delta_event",
+    "safe_emit",
+    "task_completed_event",
+    "task_failed_event",
+    "task_started_event",
+    "tool_completed_event",
+    "tool_requested_event",
+    "vendor_turn_event",
+]

agent_runtime_kit/_errors.py

@@ -0,0 +1,34 @@
+"""Typed errors raised by agent runtimes and registries."""
+
+from __future__ import annotations
+
+from agent_runtime_kit._types import AgentRuntimeKind
+
+
+class AgentRuntimeError(RuntimeError):
+    """Base class for runtime-layer failures."""
+
+
+class AgentRuntimeUnavailableError(AgentRuntimeError):
+    """A runtime cannot be constructed or used in the current environment."""
+
+    def __init__(self, kind: AgentRuntimeKind | str, message: str) -> None:
+        self.kind = AgentRuntimeKind.coerce(kind)
+        super().__init__(message)
+
+
+class UnsupportedTaskInputError(AgentRuntimeError, ValueError):
+    """A runtime was asked to honor an input it does not support."""
+
+    def __init__(self, kind: AgentRuntimeKind | str, field: str, message: str) -> None:
+        self.kind = AgentRuntimeKind.coerce(kind)
+        self.field = field
+        super().__init__(f"{self.kind.value} cannot honor {field}: {message}")
+
+
+class RuntimeNotRegisteredError(AgentRuntimeError, LookupError):
+    """No runtime factory is registered for the requested runtime kind."""
+
+    def __init__(self, kind: AgentRuntimeKind | str) -> None:
+        self.kind = AgentRuntimeKind.coerce(kind)
+        super().__init__(f"No runtime registered for {self.kind.value!r}")

agent_runtime_kit/_runtime.py

@@ -0,0 +1,139 @@
+"""Dependency-free runtime implementations used by tests and examples."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from agent_runtime_kit._errors import UnsupportedTaskInputError
+from agent_runtime_kit._types import (
+    AgentCapabilities,
+    AgentResult,
+    AgentRuntimeKind,
+    AgentTask,
+    RuntimeAvailability,
+    ToolCallAudit,
+)
+from agent_runtime_kit.events import (
+    output_delta_event,
+    safe_emit,
+    task_completed_event,
+    task_failed_event,
+    task_started_event,
+    tool_completed_event,
+    tool_requested_event,
+    vendor_turn_event,
+)
+
+
+class FakeAgentRuntime:
+    """Small deterministic runtime for tests and local examples."""
+
+    kind = AgentRuntimeKind.FAKE
+
+    def __init__(
+        self,
+        *,
+        output: str | None = None,
+        capabilities: AgentCapabilities | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> None:
+        self.capabilities = capabilities or AgentCapabilities(
+            mcp_support=True,
+            working_directory=True,
+            session_resume=True,
+            structured_output=True,
+            streaming=False,
+            tool_audit=True,
+            cancellation=True,
+        )
+        self._output = output
+        self._metadata = dict(metadata or {})
+        self.cancelled_task_ids: set[str] = set()
+
+    def availability(self) -> RuntimeAvailability:
+        """Fake runtime is always available."""
+
+        return RuntimeAvailability.ok(self.kind, package="agent-runtime-kit")
+
+    async def run(self, task: AgentTask) -> AgentResult:
+        """Return a deterministic result after validating capabilities."""
+
+        await safe_emit(task, task_started_event(task, self.kind))
+        try:
+            _ensure_supported(self.kind, self.capabilities, task)
+            output = self._output if self._output is not None else f"Fake result for: {task.goal}"
+            parsed = {"output": output} if task.output_schema is not None else None
+            tool_call = ToolCallAudit(
+                tool_name="fake",
+                arguments={"goal": task.goal},
+                result_preview=output,
+            )
+            await safe_emit(
+                task,
+                output_delta_event(task, self.kind, text=output),
+            )
+            await safe_emit(
+                task,
+                tool_requested_event(
+                    task,
+                    self.kind,
+                    tool_name="fake",
+                    arguments=tool_call.arguments,
+                ),
+            )
+            await safe_emit(task, tool_completed_event(task, self.kind, tool_call))
+            await safe_emit(
+                task,
+                vendor_turn_event(
+                    task,
+                    self.kind,
+                    payload={"runtime": "fake", "round": 1},
+                    summary="fake runtime completed one turn",
+                ),
+            )
+            result = AgentResult(
+                output=output,
+                parsed_output=parsed,
+                tool_calls=(tool_call,),
+                session_id=task.session_id or task.task_id,
+                rounds=1,
+                metadata={"task_id": task.task_id, **self._metadata},
+            )
+        except Exception as exc:
+            await safe_emit(task, task_failed_event(task, self.kind, error=str(exc)))
+            raise
+        await safe_emit(task, task_completed_event(task, self.kind, result))
+        return result
+
+    async def cancel(self, task_id: str) -> None:
+        """Record cancellation requests for assertions."""
+
+        self.cancelled_task_ids.add(task_id)
+
+
+def _ensure_supported(
+    kind: AgentRuntimeKind,
+    capabilities: AgentCapabilities,
+    task: AgentTask,
+) -> None:
+    if task.mcp_servers and not capabilities.mcp_support:
+        raise UnsupportedTaskInputError(kind, "mcp_servers", "runtime does not support MCP")
+    if task.working_directory is not None and not capabilities.working_directory:
+        raise UnsupportedTaskInputError(
+            kind,
+            "working_directory",
+            "runtime does not support per-task working directories",
+        )
+    if (task.session_id or task.resume_from) and not capabilities.session_resume:
+        raise UnsupportedTaskInputError(
+            kind,
+            "session_id",
+            "runtime does not support session resume",
+        )
+    if task.output_schema is not None and not capabilities.structured_output:
+        raise UnsupportedTaskInputError(
+            kind,
+            "output_schema",
+            "runtime does not support structured output",
+        )

agent_runtime_kit/_types.py

@@ -0,0 +1,251 @@
+"""Core public models and protocols."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+from uuid import uuid4
+
+
+class AgentRuntimeKind(str, Enum):
+    """Supported runtime families."""
+
+    FAKE = "fake"
+    CLAUDE_AGENT_SDK = "claude-agent-sdk"
+    CODEX_AGENT_SDK = "codex-agent-sdk"
+    ANTIGRAVITY_AGENT_SDK = "antigravity-agent-sdk"
+
+    @classmethod
+    def coerce(cls, value: AgentRuntimeKind | str) -> AgentRuntimeKind:
+        """Normalize a string or enum value into an ``AgentRuntimeKind``."""
+
+        if isinstance(value, cls):
+            return value
+        return cls(value)
+
+
+class AvailabilityReason(str, Enum):
+    """Why a runtime is, or is not, available."""
+
+    AVAILABLE = "available"
+    MISSING_PACKAGE = "missing-package"
+    MISSING_CREDENTIALS = "missing-credentials"
+    UNSUPPORTED_MODEL = "unsupported-model"
+    SETUP_FAILED = "setup-failed"
+    UNKNOWN = "unknown"
+
+
+class PermissionMode(str, Enum):
+    """High-level permission intent for vendor runtimes."""
+
+    DEFAULT = "default"
+    STRICT = "strict"
+    CAUTIOUS = "cautious"
+    PERMISSIVE = "permissive"
+
+
+class FilesystemAccess(str, Enum):
+    """Filesystem mutation level requested by a task."""
+
+    READ_ONLY = "read-only"
+    WORKSPACE_WRITE = "workspace-write"
+    FULL_ACCESS = "full-access"
+
+
+@runtime_checkable
+class EventSink(Protocol):
+    """Async destination for normalized runtime events."""
+
+    async def emit(self, event: Mapping[str, Any]) -> None:
+        """Receive one normalized event."""
+
+
+@dataclass(frozen=True)
+class AgentCapabilities:
+    """Runtime capability advertisement."""
+
+    mcp_support: bool = False
+    working_directory: bool = False
+    session_resume: bool = False
+    structured_output: bool = False
+    streaming: bool = False
+    tool_audit: bool = False
+    sdk_turn_limit: bool = False
+    cancellation: bool = False
+
+
+@dataclass(frozen=True)
+class RuntimeAvailability:
+    """Availability diagnostic for a runtime in the current environment."""
+
+    kind: AgentRuntimeKind
+    available: bool
+    reason: AvailabilityReason = AvailabilityReason.UNKNOWN
+    message: str = ""
+    package: str | None = None
+    version: str | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def ok(
+        cls,
+        kind: AgentRuntimeKind | str,
+        *,
+        package: str | None = None,
+        version: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> RuntimeAvailability:
+        """Build a positive availability result."""
+
+        return cls(
+            kind=AgentRuntimeKind.coerce(kind),
+            available=True,
+            reason=AvailabilityReason.AVAILABLE,
+            message="available",
+            package=package,
+            version=version,
+            metadata=dict(metadata or {}),
+        )
+
+    @classmethod
+    def unavailable(
+        cls,
+        kind: AgentRuntimeKind | str,
+        *,
+        reason: AvailabilityReason,
+        message: str,
+        package: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> RuntimeAvailability:
+        """Build a negative availability result."""
+
+        return cls(
+            kind=AgentRuntimeKind.coerce(kind),
+            available=False,
+            reason=reason,
+            message=message,
+            package=package,
+            metadata=dict(metadata or {}),
+        )
+
+
+@dataclass(frozen=True)
+class McpServerConfig:
+    """Configuration for a stdio MCP server owned by a vendor runtime."""
+
+    name: str
+    command: str
+    args: tuple[str, ...] = ()
+    env: Mapping[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class PermissionProfile:
+    """Portable permission request mapped by each adapter."""
+
+    mode: PermissionMode = PermissionMode.DEFAULT
+    filesystem: FilesystemAccess = FilesystemAccess.WORKSPACE_WRITE
+    allowed_tools: tuple[str, ...] = ()
+    disallowed_tools: tuple[str, ...] = ()
+    network: bool | None = None
+
+
+@dataclass(frozen=True)
+class ToolCallAudit:
+    """Best-effort audit entry for one vendor-observed tool invocation."""
+
+    tool_name: str
+    arguments: Mapping[str, Any] = field(default_factory=dict)
+    result_preview: str = ""
+    status: str = "ok"
+    duration_ms: int = 0
+
+
+@dataclass(frozen=True)
+class ArtifactRef:
+    """Reference to an artifact produced by a runtime."""
+
+    uri: str
+    kind: str = "file"
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class SessionResumeState:
+    """Opaque session handle carried between invocations."""
+
+    session_id: str
+    transcript: tuple[Any, ...] = ()
+
+
+@dataclass(frozen=True)
+class Usage:
+    """Token and cost metadata reported by a runtime."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_creation_tokens: int = 0
+    total_tokens: int | None = None
+    cost_usd: float = 0.0
+
+
+@dataclass(frozen=True)
+class AgentTask:
+    """One task dispatched to an agent runtime."""
+
+    goal: str
+    task_id: str = field(default_factory=lambda: f"task-{uuid4().hex}")
+    system: str | None = None
+    working_directory: Path | None = None
+    mcp_servers: tuple[McpServerConfig, ...] = ()
+    permissions: PermissionProfile = field(default_factory=PermissionProfile)
+    event_sink: EventSink | None = None
+    sdk_executions: int = 1
+    budget_usd: float | None = None
+    session_id: str | None = None
+    resume_from: SessionResumeState | None = None
+    output_schema: Mapping[str, Any] | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class AgentResult:
+    """Typed result returned by all runtimes."""
+
+    output: str
+    finish_reason: str = "done"
+    error: str | None = None
+    parsed_output: Any | None = None
+    usage: Usage = field(default_factory=Usage)
+    tool_calls: tuple[ToolCallAudit, ...] = ()
+    artifacts: tuple[ArtifactRef, ...] = ()
+    session_id: str | None = None
+    rounds: int = 0
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    @property
+    def cost_usd(self) -> float:
+        """Return the reported task cost in USD."""
+
+        return self.usage.cost_usd
+
+
+@runtime_checkable
+class AgentRuntime(Protocol):
+    """Async runtime that drives an ``AgentTask`` to completion."""
+
+    kind: AgentRuntimeKind
+    capabilities: AgentCapabilities
+
+    def availability(self) -> RuntimeAvailability:
+        """Report whether this runtime can execute in the current environment."""
+
+    async def run(self, task: AgentTask) -> AgentResult:
+        """Execute one task."""
+
+    async def cancel(self, task_id: str) -> None:
+        """Request cancellation for a task if supported."""

agent_runtime_kit/adapters/__init__.py

@@ -0,0 +1,26 @@
+"""Vendor adapter modules."""
+
+from agent_runtime_kit._types import AgentRuntimeKind
+from agent_runtime_kit.adapters.antigravity import AntigravityAgentRuntime
+from agent_runtime_kit.adapters.claude import ClaudeAgentRuntime
+from agent_runtime_kit.adapters.codex import CodexAgentRuntime
+from agent_runtime_kit.registry import RuntimeRegistry
+
+__all__ = [
+    "AntigravityAgentRuntime",
+    "ClaudeAgentRuntime",
+    "CodexAgentRuntime",
+    "register_adapters",
+]
+
+
+def register_adapters(registry: RuntimeRegistry, *, replace: bool = False) -> None:
+    """Register the built-in vendor adapters in a runtime registry."""
+
+    registry.register(AgentRuntimeKind.CLAUDE_AGENT_SDK, ClaudeAgentRuntime, replace=replace)
+    registry.register(AgentRuntimeKind.CODEX_AGENT_SDK, CodexAgentRuntime, replace=replace)
+    registry.register(
+        AgentRuntimeKind.ANTIGRAVITY_AGENT_SDK,
+        AntigravityAgentRuntime,
+        replace=replace,
+    )

agent_runtime_kit/adapters/_common.py

@@ -0,0 +1,123 @@
+"""Shared helpers for optional vendor adapters."""
+
+from __future__ import annotations
+
+import inspect
+import json
+from collections.abc import Mapping
+from importlib import metadata, util
+from typing import Any
+
+from agent_runtime_kit._errors import UnsupportedTaskInputError
+from agent_runtime_kit._types import (
+    AgentRuntimeKind,
+    AvailabilityReason,
+    RuntimeAvailability,
+)
+
+
+def package_availability(
+    kind: AgentRuntimeKind,
+    *,
+    module_name: str,
+    package_name: str,
+) -> RuntimeAvailability:
+    """Return import/package availability without importing the package."""
+
+    try:
+        module_spec = util.find_spec(module_name)
+    except ModuleNotFoundError:
+        module_spec = None
+    if module_spec is None:
+        return RuntimeAvailability.unavailable(
+            kind,
+            reason=AvailabilityReason.MISSING_PACKAGE,
+            message=f"Install the optional dependency: agent-runtime-kit[{_extra_name(kind)}]",
+            package=package_name,
+        )
+    return RuntimeAvailability.ok(
+        kind,
+        package=package_name,
+        version=package_version(package_name),
+    )
+
+
+def package_version(package_name: str) -> str | None:
+    """Return installed distribution version, if available."""
+
+    try:
+        return metadata.version(package_name)
+    except metadata.PackageNotFoundError:
+        return None
+
+
+def ensure_supported_model(
+    *,
+    kind: AgentRuntimeKind,
+    model: str,
+    supported_models: tuple[str, ...] | None,
+) -> None:
+    """Raise a typed error when a runtime was configured with an allow-list."""
+
+    if supported_models is None or model in supported_models:
+        return
+    supported = ", ".join(supported_models)
+    raise UnsupportedTaskInputError(
+        kind,
+        "metadata.model",
+        f"model {model!r} is not supported by this runtime; supported: {supported}",
+    )
+
+
+def metadata_str(metadata_values: Mapping[str, Any], key: str) -> str | None:
+    """Return a stripped string metadata value."""
+
+    value = metadata_values.get(key)
+    if not isinstance(value, str):
+        return None
+    stripped = value.strip()
+    return stripped or None
+
+
+def output_schema_from(
+    task_output_schema: Mapping[str, Any] | None,
+    metadata_values: Mapping[str, Any],
+) -> Mapping[str, Any] | None:
+    """Resolve output schema from first-class task field or metadata aliases."""
+
+    if task_output_schema is not None:
+        return task_output_schema
+    for key in ("output_schema", "json_schema"):
+        raw = metadata_values.get(key)
+        if isinstance(raw, Mapping):
+            return raw
+    return None
+
+
+def parse_json_output(output: str) -> Any | None:
+    """Best-effort JSON parsing for structured-output fallbacks."""
+
+    try:
+        return json.loads(output)
+    except json.JSONDecodeError:
+        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."""
+
+    try:
+        signature = inspect.signature(factory)
+    except (TypeError, ValueError):
+        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}
+
+
+def _extra_name(kind: AgentRuntimeKind) -> str:
+    return {
+        AgentRuntimeKind.CLAUDE_AGENT_SDK: "claude",
+        AgentRuntimeKind.CODEX_AGENT_SDK: "codex",
+        AgentRuntimeKind.ANTIGRAVITY_AGENT_SDK: "antigravity",
+    }.get(kind, "all")