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

agent_runtime_kit/adapters/codex.py

@@ -0,0 +1,298 @@
+"""OpenAI Codex SDK runtime adapter."""
+
+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,
+    FilesystemAccess,
+    PermissionMode,
+    RuntimeAvailability,
+    Usage,
+)
+from agent_runtime_kit.adapters._common import (
+    ensure_supported_model,
+    metadata_str,
+    output_schema_from,
+    package_availability,
+    parse_json_output,
+)
+from agent_runtime_kit.events import (
+    output_delta_event,
+    safe_emit,
+    task_completed_event,
+    task_failed_event,
+    task_started_event,
+)
+
+
+class CodexAgentRuntime:
+    """Run tasks through the official ``openai_codex`` Python SDK."""
+
+    kind = AgentRuntimeKind.CODEX_AGENT_SDK
+    capabilities = AgentCapabilities(
+        mcp_support=False,
+        working_directory=True,
+        session_resume=True,
+        structured_output=True,
+        streaming=False,
+        tool_audit=True,
+        cancellation=False,
+    )
+
+    def __init__(
+        self,
+        *,
+        default_model: str = "gpt-5.5",
+        supported_models: tuple[str, ...] | None = None,
+        codex_cls: Any | None = None,
+        config_cls: Any | None = None,
+        sandbox_cls: Any | None = None,
+        approval_mode_cls: Any | None = None,
+    ) -> None:
+        self._default_model = default_model
+        self._supported_models = supported_models
+        self._codex_cls = codex_cls
+        self._config_cls = config_cls
+        self._sandbox_cls = sandbox_cls
+        self._approval_mode_cls = approval_mode_cls
+
+    def availability(self) -> RuntimeAvailability:
+        """Report OpenAI Codex SDK package availability."""
+
+        if self._codex_cls is not None:
+            return RuntimeAvailability.ok(self.kind, package="openai-codex")
+        return package_availability(
+            self.kind,
+            module_name="openai_codex",
+            package_name="openai-codex",
+        )
+
+    async def run(self, task: AgentTask) -> AgentResult:
+        """Execute one task with the Codex SDK."""
+
+        await safe_emit(task, task_started_event(task, self.kind))
+        try:
+            if task.mcp_servers:
+                raise UnsupportedTaskInputError(
+                    self.kind,
+                    "mcp_servers",
+                    "openai_codex does not expose per-task MCP server configuration",
+                )
+            model = self._model(task)
+            ensure_supported_model(
+                kind=self.kind,
+                model=model,
+                supported_models=self._supported_models,
+            )
+            codex_cls, config_cls, sandbox_cls, approval_mode_cls = self._load_sdk()
+            result = await self._run_codex(
+                task,
+                model=model,
+                codex_cls=codex_cls,
+                config_cls=config_cls,
+                sandbox_cls=sandbox_cls,
+                approval_mode_cls=approval_mode_cls,
+            )
+        except Exception as exc:
+            await safe_emit(task, task_failed_event(task, self.kind, error=str(exc)))
+            raise
+
+        if result.output:
+            await safe_emit(task, output_delta_event(task, self.kind, text=result.output))
+        if result.error:
+            await safe_emit(task, task_failed_event(task, self.kind, error=result.error))
+        else:
+            await safe_emit(task, task_completed_event(task, self.kind, result))
+        return result
+
+    async def cancel(self, task_id: str) -> None:
+        """Codex SDK cancellation is not exposed through this portable adapter yet."""
+
+        del task_id
+
+    def _load_sdk(self) -> tuple[Any, Any, Any, Any]:
+        if self._codex_cls is not None and self._config_cls is not None:
+            return (
+                self._codex_cls,
+                self._config_cls,
+                self._sandbox_cls,
+                self._approval_mode_cls,
+            )
+        try:
+            from openai_codex import (  # type: ignore[import-not-found]
+                ApprovalMode,
+                AsyncCodex,
+                CodexConfig,
+                Sandbox,
+            )
+        except ImportError as exc:
+            raise RuntimeError(
+                "openai-codex is not installed. Install agent-runtime-kit[codex]."
+            ) from exc
+        return (
+            self._codex_cls or AsyncCodex,
+            self._config_cls or CodexConfig,
+            self._sandbox_cls or Sandbox,
+            self._approval_mode_cls or ApprovalMode,
+        )
+
+    async def _run_codex(
+        self,
+        task: AgentTask,
+        *,
+        model: str,
+        codex_cls: Any,
+        config_cls: Any,
+        sandbox_cls: Any,
+        approval_mode_cls: Any,
+    ) -> AgentResult:
+        cwd = str(task.working_directory) if task.working_directory else None
+        config = config_cls(cwd=cwd, config_overrides=("features.plugins=false",))
+        async with codex_cls(config=config) as codex:
+            thread = await self._start_or_resume_thread(
+                codex,
+                task,
+                model=model,
+                cwd=cwd,
+                sandbox_cls=sandbox_cls,
+                approval_mode_cls=approval_mode_cls,
+            )
+            run_kwargs = {
+                "cwd": cwd,
+                "model": model,
+                "approval_mode": _approval_mode(task.permissions.mode, approval_mode_cls),
+                "sandbox": _sandbox_mode(task.permissions.filesystem, sandbox_cls),
+            }
+            schema = output_schema_from(task.output_schema, task.metadata)
+            if schema is not None:
+                run_kwargs["output_schema"] = dict(schema)
+            effort = metadata_str(task.metadata, "reasoning_effort")
+            if effort:
+                run_kwargs["effort"] = effort
+            raw_result = await thread.run(task.goal, **run_kwargs)
+        return _translate_run_result(task, raw_result, model=model, session_id=_thread_id(thread))
+
+    async def _start_or_resume_thread(
+        self,
+        codex: Any,
+        task: AgentTask,
+        *,
+        model: str,
+        cwd: str | None,
+        sandbox_cls: Any,
+        approval_mode_cls: Any,
+    ) -> Any:
+        kwargs = {
+            "cwd": cwd,
+            "developer_instructions": task.system,
+            "model": model,
+            "approval_mode": _approval_mode(task.permissions.mode, approval_mode_cls),
+            "sandbox": _sandbox_mode(task.permissions.filesystem, sandbox_cls),
+        }
+        thread_id = task.resume_from.session_id if task.resume_from is not None else task.session_id
+        if thread_id:
+            return await codex.thread_resume(thread_id, **kwargs)
+        return await codex.thread_start(**kwargs)
+
+    def _model(self, task: AgentTask) -> str:
+        return metadata_str(task.metadata, "model") or self._default_model
+
+
+def _translate_run_result(
+    task: AgentTask,
+    raw_result: Any,
+    *,
+    model: str,
+    session_id: str | None,
+) -> AgentResult:
+    output = str(_field(raw_result, "final_response", "") or "")
+    usage = _codex_usage(_field(raw_result, "usage"))
+    schema = output_schema_from(task.output_schema, task.metadata)
+    parsed = parse_json_output(output) if schema is not None else None
+    if schema is not None and parsed is None:
+        return AgentResult(
+            output=output,
+            finish_reason="failed",
+            error="Codex SDK returned output that did not satisfy output_schema",
+            usage=usage,
+            session_id=session_id,
+            rounds=1,
+            metadata={"model": model, "sdk": "openai_codex"},
+        )
+    if not output:
+        return AgentResult(
+            output="",
+            finish_reason="failed",
+            error="Codex SDK completed without final_response",
+            usage=usage,
+            session_id=session_id,
+            metadata={"model": model, "sdk": "openai_codex"},
+        )
+    return AgentResult(
+        output=output,
+        parsed_output=parsed,
+        usage=usage,
+        session_id=session_id,
+        rounds=1,
+        metadata={"model": model, "sdk": "openai_codex"},
+    )
+
+
+def _codex_usage(value: Any) -> Usage:
+    total = _field(value, "total")
+    if total is None and isinstance(value, Mapping):
+        total = value.get("total", value)
+    input_tokens = _optional_int(_field(total, "input_tokens"))
+    output_tokens = _optional_int(_field(total, "output_tokens"))
+    cached = _optional_int(_field(total, "cached_input_tokens"))
+    total_tokens = _optional_int(_field(total, "total_tokens"))
+    return Usage(
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        cache_read_tokens=cached,
+        total_tokens=total_tokens or input_tokens + output_tokens + cached,
+    )
+
+
+def _approval_mode(mode: PermissionMode, approval_mode_cls: Any) -> Any:
+    if approval_mode_cls is None:
+        return "auto_review" if mode is not PermissionMode.PERMISSIVE else "deny_all"
+    if mode is PermissionMode.PERMISSIVE:
+        return getattr(approval_mode_cls, "deny_all", "deny_all")
+    return getattr(approval_mode_cls, "auto_review", "auto_review")
+
+
+def _sandbox_mode(filesystem: FilesystemAccess, sandbox_cls: Any) -> Any:
+    name = {
+        FilesystemAccess.READ_ONLY: "read_only",
+        FilesystemAccess.WORKSPACE_WRITE: "workspace_write",
+        FilesystemAccess.FULL_ACCESS: "full_access",
+    }[filesystem]
+    if sandbox_cls is None:
+        return name.replace("_", "-")
+    return getattr(sandbox_cls, name, name.replace("_", "-"))
+
+
+def _thread_id(thread: Any) -> str | None:
+    value = getattr(thread, "id", None)
+    return str(value) if value else None
+
+
+def _field(value: Any, name: str, default: Any = None) -> Any:
+    if isinstance(value, Mapping):
+        return value.get(name, default)
+    return getattr(value, name, default)
+
+
+def _optional_int(value: Any) -> int:
+    try:
+        return int(value or 0)
+    except (TypeError, ValueError):
+        return 0

agent_runtime_kit/adapters/diagnostics.py

@@ -0,0 +1,18 @@
+"""Provider adapter diagnostics."""
+
+from __future__ import annotations
+
+from agent_runtime_kit._types import RuntimeAvailability
+from agent_runtime_kit.adapters.antigravity import AntigravityAgentRuntime
+from agent_runtime_kit.adapters.claude import ClaudeAgentRuntime
+from agent_runtime_kit.adapters.codex import CodexAgentRuntime
+
+
+def collect_provider_diagnostics() -> tuple[RuntimeAvailability, ...]:
+    """Return availability diagnostics for installed provider adapters."""
+
+    return (
+        ClaudeAgentRuntime().availability(),
+        CodexAgentRuntime().availability(),
+        AntigravityAgentRuntime().availability(),
+    )

agent_runtime_kit/events.py

@@ -0,0 +1,224 @@
+"""Normalized runtime event helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from typing import Any
+
+from agent_runtime_kit._types import AgentResult, AgentRuntimeKind, AgentTask, ToolCallAudit
+
+DEFAULT_PREVIEW_CHARS = 1000
+SENSITIVE_KEY_PARTS = ("api_key", "apikey", "authorization", "password", "secret", "token")
+
+
+def task_started_event(
+    task: AgentTask,
+    kind: AgentRuntimeKind | str,
+    *,
+    summary: str | None = None,
+    extra: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build an ``agent.task.started`` event."""
+
+    attrs = {
+        "task_id": task.task_id,
+        "runtime_kind": AgentRuntimeKind.coerce(kind).value,
+        "session_id": task.session_id,
+        "task_goal": task.goal,
+        "system_prompt": task.system,
+        "working_directory": str(task.working_directory) if task.working_directory else None,
+        "sdk_executions": task.sdk_executions,
+        "budget_usd": task.budget_usd,
+        "metadata": dict(task.metadata),
+    }
+    if extra:
+        attrs.update(extra)
+    return _event("agent.task.started", summary or f"started task {task.task_id}", attrs)
+
+
+def task_completed_event(
+    task: AgentTask,
+    kind: AgentRuntimeKind | str,
+    result: AgentResult,
+    *,
+    summary: str | None = None,
+    extra: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build an ``agent.task.completed`` event."""
+
+    attrs = {
+        "task_id": task.task_id,
+        "runtime_kind": AgentRuntimeKind.coerce(kind).value,
+        "finish_reason": result.finish_reason,
+        "output": result.output,
+        "rounds": result.rounds,
+        "cost_usd": result.cost_usd,
+        "session_id": result.session_id,
+        "tool_call_count": len(result.tool_calls),
+        "result_metadata": dict(result.metadata),
+    }
+    if extra:
+        attrs.update(extra)
+    return _event(
+        "agent.task.completed",
+        summary or f"completed task {task.task_id} ({result.finish_reason})",
+        attrs,
+    )
+
+
+def task_failed_event(
+    task: AgentTask,
+    kind: AgentRuntimeKind | str,
+    *,
+    error: str,
+    finish_reason: str = "failed",
+    summary: str | None = None,
+    extra: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build an ``agent.task.failed`` event."""
+
+    attrs = {
+        "task_id": task.task_id,
+        "runtime_kind": AgentRuntimeKind.coerce(kind).value,
+        "finish_reason": finish_reason,
+        "error": error,
+    }
+    if extra:
+        attrs.update(extra)
+    return _event("agent.task.failed", summary or f"failed task {task.task_id}", attrs)
+
+
+def output_delta_event(
+    task: AgentTask,
+    kind: AgentRuntimeKind | str,
+    *,
+    text: str,
+    summary: str | None = None,
+    extra: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build an ``agent.output.delta`` event."""
+
+    preview, truncated = _preview(text)
+    attrs = {
+        "task_id": task.task_id,
+        "runtime_kind": AgentRuntimeKind.coerce(kind).value,
+        "text_delta": preview,
+        "text_delta_length": len(text),
+        "text_delta_truncated": truncated,
+    }
+    if extra:
+        attrs.update(extra)
+    return _event("agent.output.delta", summary or f"streamed {len(text)} chars", attrs)
+
+
+def tool_requested_event(
+    task: AgentTask,
+    kind: AgentRuntimeKind | str,
+    *,
+    tool_name: str,
+    arguments: Mapping[str, Any] | None = None,
+    summary: str | None = None,
+) -> dict[str, Any]:
+    """Build an ``agent.tool.requested`` event."""
+
+    attrs = {
+        "task_id": task.task_id,
+        "runtime_kind": AgentRuntimeKind.coerce(kind).value,
+        "tool_name": tool_name,
+        "argument_count": len(arguments or {}),
+        "argument_keys": sorted(str(key) for key in (arguments or {})),
+    }
+    return _event("agent.tool.requested", summary or f"tool requested: {tool_name}", attrs)
+
+
+def tool_completed_event(
+    task: AgentTask,
+    kind: AgentRuntimeKind | str,
+    audit: ToolCallAudit,
+    *,
+    summary: str | None = None,
+) -> dict[str, Any]:
+    """Build an ``agent.tool.completed`` event."""
+
+    attrs = {
+        "task_id": task.task_id,
+        "runtime_kind": AgentRuntimeKind.coerce(kind).value,
+        "tool_name": audit.tool_name,
+        "status": audit.status,
+        "duration_ms": audit.duration_ms,
+        "result_preview_length": len(audit.result_preview),
+    }
+    return _event(
+        "agent.tool.completed",
+        summary or f"tool completed: {audit.tool_name} ({audit.status})",
+        attrs,
+    )
+
+
+def vendor_turn_event(
+    task: AgentTask,
+    kind: AgentRuntimeKind | str,
+    *,
+    payload: Mapping[str, Any] | None = None,
+    turn_index: int | None = None,
+    summary: str | None = None,
+) -> dict[str, Any]:
+    """Build an ``agent.vendor.turn`` event."""
+
+    attrs = {
+        "task_id": task.task_id,
+        "runtime_kind": AgentRuntimeKind.coerce(kind).value,
+        "turn_index": turn_index,
+        "payload": dict(payload or {}),
+    }
+    return _event("agent.vendor.turn", summary or "vendor turn update", attrs)
+
+
+async def safe_emit(task: AgentTask, event: Mapping[str, Any]) -> None:
+    """Best-effort event emission that never aborts a runtime."""
+
+    if task.event_sink is None:
+        return
+    try:
+        await task.event_sink.emit(event)
+    except Exception:
+        return
+
+
+def _event(name: str, summary: str, attributes: Mapping[str, Any]) -> dict[str, Any]:
+    return {
+        "name": name,
+        "timestamp": datetime.now(tz=timezone.utc).isoformat(),
+        "summary": summary,
+        "attributes": _sanitize(attributes),
+    }
+
+
+def _sanitize(value: Any, *, key: str | None = None) -> Any:
+    if key is not None and _is_sensitive_key(key):
+        return "[redacted]"
+    if isinstance(value, Mapping):
+        return {
+            str(item_key): _sanitize(item_value, key=str(item_key))
+            for item_key, item_value in value.items()
+        }
+    if isinstance(value, tuple):
+        return tuple(_sanitize(item) for item in value)
+    if isinstance(value, list):
+        return [_sanitize(item) for item in value]
+    if isinstance(value, str):
+        preview, truncated = _preview(value)
+        return f"{preview}...[truncated]" if truncated else preview
+    return value
+
+
+def _preview(text: str) -> tuple[str, bool]:
+    if len(text) <= DEFAULT_PREVIEW_CHARS:
+        return text, False
+    return text[:DEFAULT_PREVIEW_CHARS], True
+
+
+def _is_sensitive_key(key: str) -> bool:
+    lowered = key.lower().replace("-", "_")
+    return any(part in lowered for part in SENSITIVE_KEY_PARTS)

agent_runtime_kit/py.typed

@@ -0,0 +1 @@
+

agent_runtime_kit/registry.py

@@ -0,0 +1,83 @@
+"""Runtime registry helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from agent_runtime_kit._errors import RuntimeNotRegisteredError
+from agent_runtime_kit._runtime import FakeAgentRuntime
+from agent_runtime_kit._types import (
+    AgentCapabilities,
+    AgentRuntime,
+    AgentRuntimeKind,
+    RuntimeAvailability,
+)
+
+RuntimeFactory = Callable[..., AgentRuntime]
+
+
+class RuntimeRegistry:
+    """Register and resolve runtime factories by kind."""
+
+    def __init__(self) -> None:
+        self._factories: dict[AgentRuntimeKind, RuntimeFactory] = {}
+
+    def register(
+        self,
+        kind: AgentRuntimeKind | str,
+        factory: RuntimeFactory,
+        *,
+        replace: bool = False,
+    ) -> None:
+        """Register a runtime factory."""
+
+        normalized = AgentRuntimeKind.coerce(kind)
+        if normalized in self._factories and not replace:
+            raise ValueError(f"Runtime already registered for {normalized.value!r}")
+        self._factories[normalized] = factory
+
+    def unregister(self, kind: AgentRuntimeKind | str) -> None:
+        """Remove a registered runtime factory."""
+
+        normalized = AgentRuntimeKind.coerce(kind)
+        self._factories.pop(normalized, None)
+
+    def kinds(self) -> tuple[AgentRuntimeKind, ...]:
+        """Return registered runtime kinds."""
+
+        return tuple(self._factories)
+
+    def resolve(self, kind: AgentRuntimeKind | str, **kwargs: Any) -> AgentRuntime:
+        """Construct a runtime for ``kind``."""
+
+        normalized = AgentRuntimeKind.coerce(kind)
+        factory = self._factories.get(normalized)
+        if factory is None:
+            raise RuntimeNotRegisteredError(normalized)
+        return factory(**kwargs)
+
+    def capabilities_for(self, kind: AgentRuntimeKind | str) -> AgentCapabilities:
+        """Construct a runtime and return its advertised capabilities."""
+
+        return self.resolve(kind).capabilities
+
+    def availability_for(self, kind: AgentRuntimeKind | str) -> RuntimeAvailability:
+        """Construct a runtime and return its availability diagnostic."""
+
+        return self.resolve(kind).availability()
+
+
+def create_default_registry(
+    *,
+    include_fake: bool = True,
+    extra_factories: Iterable[tuple[AgentRuntimeKind | str, RuntimeFactory]] = (),
+) -> RuntimeRegistry:
+    """Create a registry with built-in dependency-free runtimes."""
+
+    registry = RuntimeRegistry()
+    if include_fake:
+        registry.register(AgentRuntimeKind.FAKE, FakeAgentRuntime)
+    for kind, factory in extra_factories:
+        registry.register(kind, factory)
+    return registry

agent_runtime_kit/testing/__init__.py

@@ -0,0 +1,15 @@
+"""Testing helpers for adapter contract tests."""
+
+from agent_runtime_kit.testing.fakes import (
+    FakeSDKHarness,
+    FakeSDKRuntime,
+    FakeSDKScenario,
+    RecordingEventSink,
+)
+
+__all__ = [
+    "FakeSDKHarness",
+    "FakeSDKRuntime",
+    "FakeSDKScenario",
+    "RecordingEventSink",
+]