codex-autorunner 0.1.1__py3-none-any.whl → 1.0.0__py3-none-any.whl

codex_autorunner/agents/opencode/supervisor.py

@@ -2,19 +2,21 @@ from __future__ import annotations
 
 import asyncio
 import logging
-import os
 import re
 import time
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Optional, Sequence
+from typing import Any, Mapping, Optional, Sequence
+
+import httpx
 
 from ...core.logging_utils import log_event
-from ...core.utils import subprocess_env
+from ...core.supervisor_utils import evict_lru_handle_locked, pop_idle_handles_locked
+from ...core.utils import infer_home_from_workspace, subprocess_env
 from ...workspace import canonical_workspace_root, workspace_id_for_path
 from .client import OpenCodeClient
 
-_LISTENING_RE = re.compile(r"listening on (http://[^\s]+)")
+_LISTENING_RE = re.compile(r"listening on (https?://[^\s]+)")
 
 
 class OpenCodeSupervisorError(Exception):
@@ -28,6 +30,9 @@ class OpenCodeHandle:
     process: Optional[asyncio.subprocess.Process]
     client: Optional[OpenCodeClient]
     base_url: Optional[str]
+    health_info: Optional[dict[str, Any]]
+    version: Optional[str]
+    openapi_spec: Optional[dict[str, Any]]
     start_lock: asyncio.Lock
     stdout_task: Optional[asyncio.Task[None]] = None
     started: bool = False
@@ -46,15 +51,31 @@ class OpenCodeSupervisor:
         idle_ttl_seconds: Optional[float] = None,
         username: Optional[str] = None,
         password: Optional[str] = None,
+        base_env: Optional[Mapping[str, str]] = None,
+        base_url: Optional[str] = None,
+        subagent_models: Optional[Mapping[str, str]] = None,
+        session_stall_timeout_seconds: Optional[float] = None,
     ) -> None:
         self._command = [str(arg) for arg in command]
         self._logger = logger or logging.getLogger(__name__)
         self._request_timeout = request_timeout
         self._max_handles = max_handles
         self._idle_ttl_seconds = idle_ttl_seconds
-        self._auth = (username, password) if username and password else None
+        self._session_stall_timeout_seconds = session_stall_timeout_seconds
+        if password and not username:
+            username = "opencode"
+        self._auth: Optional[tuple[str, str]] = (
+            (username, password) if password and username else None
+        )
+        self._base_env = base_env
+        self._base_url = base_url
+        self._subagent_models = subagent_models or {}
         self._handles: dict[str, OpenCodeHandle] = {}
-        self._lock = asyncio.Lock()
+        self._lock: Optional[asyncio.Lock] = None
+
+    @property
+    def session_stall_timeout_seconds(self) -> Optional[float]:
+        return self._session_stall_timeout_seconds
 
     async def get_client(self, workspace_root: Path) -> OpenCodeClient:
         canonical_root = canonical_workspace_root(workspace_root)
@@ -67,7 +88,7 @@ class OpenCodeSupervisor:
         return handle.client
 
     async def close_all(self) -> None:
-        async with self._lock:
+        async with self._get_lock():
             handles = list(self._handles.values())
             self._handles = {}
         for handle in handles:
@@ -86,7 +107,7 @@ class OpenCodeSupervisor:
     async def mark_turn_started(self, workspace_root: Path) -> None:
         canonical_root = canonical_workspace_root(workspace_root)
         workspace_id = workspace_id_for_path(canonical_root)
-        async with self._lock:
+        async with self._get_lock():
             handle = self._handles.get(workspace_id)
             if handle is None:
                 return
@@ -96,7 +117,7 @@ class OpenCodeSupervisor:
     async def mark_turn_finished(self, workspace_root: Path) -> None:
         canonical_root = canonical_workspace_root(workspace_root)
         workspace_id = workspace_id_for_path(canonical_root)
-        async with self._lock:
+        async with self._get_lock():
             handle = self._handles.get(workspace_id)
             if handle is None:
                 return
@@ -104,6 +125,34 @@ class OpenCodeSupervisor:
                 handle.active_turns -= 1
             handle.last_used_at = time.monotonic()
 
+    async def ensure_subagent_config(
+        self,
+        workspace_root: Path,
+        agent_id: str,
+        model: Optional[str] = None,
+    ) -> None:
+        """Ensure subagent agent config file exists with correct model.
+
+        Args:
+            workspace_root: Path to workspace root
+            agent_id: Agent ID to configure (e.g., "subagent")
+            model: Optional model override (defaults to subagent_models if not provided)
+        """
+        if model is None:
+            model = self._subagent_models.get(agent_id)
+        if not model:
+            return
+
+        from .agent_config import ensure_agent_config
+
+        await ensure_agent_config(
+            workspace_root=workspace_root,
+            agent_id=agent_id,
+            model=model,
+            title=agent_id,
+            description=f"Subagent for {agent_id} tasks",
+        )
+
     async def _close_handle(self, handle: OpenCodeHandle, *, reason: str) -> None:
         try:
             idle_seconds = None
@@ -147,7 +196,7 @@ class OpenCodeSupervisor:
     ) -> OpenCodeHandle:
         handles_to_close: list[OpenCodeHandle] = []
         evicted_id: Optional[str] = None
-        async with self._lock:
+        async with self._get_lock():
             existing = self._handles.get(workspace_id)
             if existing is not None:
                 existing.last_used_at = time.monotonic()
@@ -163,6 +212,9 @@ class OpenCodeSupervisor:
                 process=None,
                 client=None,
                 base_url=None,
+                health_info=None,
+                version=None,
+                openapi_spec=None,
                 start_lock=asyncio.Lock(),
                 stdout_task=None,
                 last_used_at=time.monotonic(),
@@ -181,9 +233,97 @@ class OpenCodeSupervisor:
         async with handle.start_lock:
             if handle.started and handle.process and handle.process.returncode is None:
                 return
-            await self._start_process(handle)
+            if self._base_url:
+                await self._ensure_started_base_url(handle)
+            else:
+                await self._start_process(handle)
+
+    async def _ensure_started_base_url(self, handle: OpenCodeHandle) -> None:
+        base_url = self._base_url
+        handle.health_info = None
+        handle.version = None
+
+        if not base_url:
+            return
+
+        try:
+            health_url = f"{base_url.rstrip('/')}/global/health"
+            async with httpx.AsyncClient(
+                timeout=self._request_timeout or 10.0
+            ) as client:
+                response = await client.get(health_url)
+                response.raise_for_status()
+
+            try:
+                handle.health_info = response.json() if response.content else {}
+            except Exception:
+                handle.health_info = {}
+
+            handle.version = str(handle.health_info.get("version", "unknown"))
+
+            log_event(
+                self._logger,
+                logging.INFO,
+                "opencode.health_check",
+                base_url=base_url,
+                version=handle.version,
+                health_info=bool(handle.health_info),
+                exc=None,
+            )
+            handle.base_url = base_url
+            handle.client = OpenCodeClient(
+                base_url,
+                auth=self._auth,
+                timeout=self._request_timeout,
+                logger=self._logger,
+            )
+            try:
+                handle.openapi_spec = await handle.client.fetch_openapi_spec()
+                log_event(
+                    self._logger,
+                    logging.INFO,
+                    "opencode.openapi.fetched",
+                    base_url=base_url,
+                    endpoints=(
+                        len(handle.openapi_spec.get("paths", {}))
+                        if isinstance(handle.openapi_spec, dict)
+                        else 0
+                    ),
+                )
+            except Exception as exc:
+                log_event(
+                    self._logger,
+                    logging.WARNING,
+                    "opencode.openapi.fetch_failed",
+                    base_url=base_url,
+                    exc=exc,
+                )
+                handle.openapi_spec = {}
+            handle.started = True
+        except Exception as exc:
+            log_event(
+                self._logger,
+                logging.WARNING,
+                "opencode.health_check.failed",
+                base_url=base_url,
+                exc=exc,
+            )
+            raise OpenCodeSupervisorError(
+                f"OpenCode health check failed: {exc}"
+            ) from exc
 
     async def _start_process(self, handle: OpenCodeHandle) -> None:
+        if self._base_url:
+            handle.health_info = {}
+            handle.version = "external"
+            log_event(
+                self._logger,
+                logging.INFO,
+                "opencode.external_mode",
+                base_url=self._base_url,
+            )
+            return
+
         env = self._build_opencode_env(handle.workspace_root)
         process = await asyncio.create_subprocess_exec(
             *self._command,
@@ -206,6 +346,28 @@ class OpenCodeSupervisor:
                 timeout=self._request_timeout,
                 logger=self._logger,
             )
+            try:
+                handle.openapi_spec = await handle.client.fetch_openapi_spec()
+                log_event(
+                    self._logger,
+                    logging.INFO,
+                    "opencode.openapi.fetched",
+                    base_url=base_url,
+                    endpoints=(
+                        len(handle.openapi_spec.get("paths", {}))
+                        if isinstance(handle.openapi_spec, dict)
+                        else 0
+                    ),
+                )
+            except Exception as exc:
+                log_event(
+                    self._logger,
+                    logging.WARNING,
+                    "opencode.openapi.fetch_failed",
+                    base_url=base_url,
+                    exc=exc,
+                )
+                handle.openapi_spec = {}
             self._start_stdout_drain(handle)
             handle.started = True
         except Exception:
@@ -219,8 +381,8 @@ class OpenCodeSupervisor:
             raise
 
     def _build_opencode_env(self, workspace_root: Path) -> dict[str, str]:
-        env = subprocess_env()
-        inferred_home = self._infer_home_from_workspace(workspace_root)
+        env = subprocess_env(base_env=self._base_env)
+        inferred_home = infer_home_from_workspace(workspace_root)
         if inferred_home is None:
             return env
         inferred_auth = inferred_home / ".local" / "share" / "opencode" / "auth.json"
@@ -241,21 +403,6 @@ class OpenCodeSupervisor:
         )
         return env
 
-    def _infer_home_from_workspace(self, workspace_root: Path) -> Optional[Path]:
-        resolved = workspace_root.resolve()
-        parts = resolved.parts
-        if (
-            len(parts) >= 3
-            and parts[0] == os.path.sep
-            and parts[1]
-            in (
-                "Users",
-                "home",
-            )
-        ):
-            return Path(parts[0]) / parts[1] / parts[2]
-        return None
-
     def _opencode_auth_path_for_env(self, env: dict[str, str]) -> Optional[Path]:
         data_home = env.get("XDG_DATA_HOME")
         if not data_home:
@@ -330,53 +477,32 @@ class OpenCodeSupervisor:
                 return match.group(1)
 
     async def _pop_idle_handles(self) -> list[OpenCodeHandle]:
-        async with self._lock:
+        async with self._get_lock():
             return self._pop_idle_handles_locked()
 
+    def _get_lock(self) -> asyncio.Lock:
+        if self._lock is None:
+            self._lock = asyncio.Lock()
+        return self._lock
+
     def _pop_idle_handles_locked(self) -> list[OpenCodeHandle]:
-        if not self._idle_ttl_seconds or self._idle_ttl_seconds <= 0:
-            return []
-        cutoff = time.monotonic() - self._idle_ttl_seconds
-        stale: list[OpenCodeHandle] = []
-        for handle in list(self._handles.values()):
-            if handle.active_turns:
-                log_event(
-                    self._logger,
-                    logging.INFO,
-                    "opencode.handle.prune.skipped",
-                    reason="active_turns",
-                    workspace_id=handle.workspace_id,
-                    workspace_root=str(handle.workspace_root),
-                    active_turns=handle.active_turns,
-                )
-                continue
-            if handle.last_used_at and handle.last_used_at < cutoff:
-                self._handles.pop(handle.workspace_id, None)
-                stale.append(handle)
-        return stale
+        return pop_idle_handles_locked(
+            self._handles,
+            self._idle_ttl_seconds,
+            self._logger,
+            "opencode",
+            last_used_at_getter=lambda h: h.last_used_at,
+            should_skip_prune=lambda h: h.active_turns > 0,
+        )
 
     def _evict_lru_handle_locked(self) -> Optional[OpenCodeHandle]:
-        if not self._max_handles or self._max_handles <= 0:
-            return None
-        if len(self._handles) < self._max_handles:
-            return None
-        lru_handle = min(
-            self._handles.values(),
-            key=lambda handle: handle.last_used_at or 0.0,
-        )
-        log_event(
+        return evict_lru_handle_locked(
+            self._handles,
+            self._max_handles,
             self._logger,
-            logging.INFO,
-            "opencode.handle.evicted",
-            reason="max_handles",
-            workspace_id=lru_handle.workspace_id,
-            workspace_root=str(lru_handle.workspace_root),
-            max_handles=self._max_handles,
-            handle_count=len(self._handles),
-            last_used_at=lru_handle.last_used_at,
+            "opencode",
+            last_used_at_getter=lambda h: h.last_used_at or 0.0,
         )
-        self._handles.pop(lru_handle.workspace_id, None)
-        return lru_handle
 
 
 __all__ = ["OpenCodeHandle", "OpenCodeSupervisor", "OpenCodeSupervisorError"]

codex_autorunner/agents/registry.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+import importlib.metadata
+import logging
+from dataclasses import dataclass
+from typing import Any, Callable, Iterable, Literal, Optional
+
+from ..plugin_api import CAR_AGENT_ENTRYPOINT_GROUP, CAR_PLUGIN_API_VERSION
+from .base import AgentHarness
+from .codex.harness import CodexHarness
+from .opencode.harness import OpenCodeHarness
+
+_logger = logging.getLogger(__name__)
+
+AgentCapability = Literal[
+    "threads",
+    "turns",
+    "review",
+    "model_listing",
+    "event_streaming",
+    "approvals",
+]
+
+
+@dataclass(frozen=True)
+class AgentDescriptor:
+    """A registered agent backend.
+
+    Built-in backends live in `_BUILTIN_AGENTS`. Additional backends MAY be loaded
+    via Python entry points (see `CAR_AGENT_ENTRYPOINT_GROUP`).
+
+    Plugins SHOULD set `plugin_api_version` to `CAR_PLUGIN_API_VERSION`.
+    """
+
+    id: str
+    name: str
+    capabilities: frozenset[AgentCapability]
+    make_harness: Callable[[Any], AgentHarness]
+    healthcheck: Optional[Callable[[Any], bool]] = None
+    plugin_api_version: int = CAR_PLUGIN_API_VERSION
+
+
+def _make_codex_harness(ctx: Any) -> AgentHarness:
+    supervisor = ctx.app_server_supervisor
+    events = ctx.app_server_events
+    if supervisor is None or events is None:
+        raise RuntimeError("Codex harness unavailable: supervisor or events missing")
+    return CodexHarness(supervisor, events)
+
+
+def _make_opencode_harness(ctx: Any) -> AgentHarness:
+    supervisor = ctx.opencode_supervisor
+    if supervisor is None:
+        raise RuntimeError("OpenCode harness unavailable: supervisor missing")
+    return OpenCodeHarness(supervisor)
+
+
+def _check_codex_health(ctx: Any) -> bool:
+    supervisor = ctx.app_server_supervisor
+    return supervisor is not None
+
+
+def _check_opencode_health(ctx: Any) -> bool:
+    supervisor = ctx.opencode_supervisor
+    return supervisor is not None
+
+
+_BUILTIN_AGENTS: dict[str, AgentDescriptor] = {
+    "codex": AgentDescriptor(
+        id="codex",
+        name="Codex",
+        capabilities=frozenset(
+            [
+                "threads",
+                "turns",
+                "review",
+                "model_listing",
+                "event_streaming",
+                "approvals",
+            ]
+        ),
+        make_harness=_make_codex_harness,
+        healthcheck=_check_codex_health,
+    ),
+    "opencode": AgentDescriptor(
+        id="opencode",
+        name="OpenCode",
+        capabilities=frozenset(
+            [
+                "threads",
+                "turns",
+                "review",
+                "model_listing",
+                "event_streaming",
+            ]
+        ),
+        make_harness=_make_opencode_harness,
+        healthcheck=_check_opencode_health,
+    ),
+}
+
+# Lazy-loaded cache of built-in + plugin agents.
+_AGENT_CACHE: Optional[dict[str, AgentDescriptor]] = None
+
+
+def _select_entry_points(group: str) -> Iterable[importlib.metadata.EntryPoint]:
+    """Compatibility wrapper for `importlib.metadata.entry_points()` across py versions."""
+
+    eps = importlib.metadata.entry_points()
+    # Python 3.9: may return a dict
+    if isinstance(eps, dict):
+        return eps.get(group, [])
+    if hasattr(eps, "select"):
+        return list(eps.select(group=group))
+    return []
+
+
+def _load_agent_plugins() -> dict[str, AgentDescriptor]:
+    loaded: dict[str, AgentDescriptor] = {}
+    for ep in _select_entry_points(CAR_AGENT_ENTRYPOINT_GROUP):
+        try:
+            obj = ep.load()
+        except Exception as exc:  # noqa: BLE001
+            _logger.warning(
+                "Failed to load agent plugin entry point %s:%s: %s",
+                ep.group,
+                ep.name,
+                exc,
+            )
+            continue
+
+        descriptor: Optional[AgentDescriptor] = None
+        if isinstance(obj, AgentDescriptor):
+            descriptor = obj
+        elif callable(obj):
+            try:
+                maybe = obj()
+            except Exception as exc:  # noqa: BLE001
+                _logger.warning(
+                    "Agent plugin entry point %s:%s factory failed: %s",
+                    ep.group,
+                    ep.name,
+                    exc,
+                )
+                continue
+            if isinstance(maybe, AgentDescriptor):
+                descriptor = maybe
+
+        if descriptor is None:
+            _logger.warning(
+                "Ignoring agent plugin entry point %s:%s: expected AgentDescriptor or factory",
+                ep.group,
+                ep.name,
+            )
+            continue
+
+        agent_id = (descriptor.id or "").strip().lower()
+        if not agent_id:
+            _logger.warning(
+                "Ignoring agent plugin entry point %s:%s: missing id",
+                ep.group,
+                ep.name,
+            )
+            continue
+
+        if descriptor.plugin_api_version != CAR_PLUGIN_API_VERSION:
+            _logger.warning(
+                "Ignoring agent plugin %s (api_version=%s): expected %s",
+                agent_id,
+                descriptor.plugin_api_version,
+                CAR_PLUGIN_API_VERSION,
+            )
+            continue
+
+        if agent_id in _BUILTIN_AGENTS:
+            _logger.warning(
+                "Ignoring agent plugin %s: conflicts with built-in agent id",
+                agent_id,
+            )
+            continue
+        if agent_id in loaded:
+            _logger.warning(
+                "Ignoring duplicate agent plugin id %s from entry point %s:%s",
+                agent_id,
+                ep.group,
+                ep.name,
+            )
+            continue
+
+        loaded[agent_id] = descriptor
+        _logger.info("Loaded agent plugin: %s (%s)", agent_id, descriptor.name)
+
+    return loaded
+
+
+def _all_agents() -> dict[str, AgentDescriptor]:
+    global _AGENT_CACHE
+    if _AGENT_CACHE is None:
+        agents = _BUILTIN_AGENTS.copy()
+        agents.update(_load_agent_plugins())
+        _AGENT_CACHE = agents
+    return _AGENT_CACHE
+
+
+def reload_agents() -> dict[str, AgentDescriptor]:
+    """Clear the plugin cache and reload agent backends.
+
+    This is primarily useful for tests and local development.
+    """
+
+    global _AGENT_CACHE
+    _AGENT_CACHE = None
+    return get_registered_agents()
+
+
+def get_registered_agents() -> dict[str, AgentDescriptor]:
+    return _all_agents().copy()
+
+
+def get_available_agents(app_ctx: Any) -> dict[str, AgentDescriptor]:
+    available: dict[str, AgentDescriptor] = {}
+    for agent_id, descriptor in _all_agents().items():
+        if descriptor.healthcheck is None or descriptor.healthcheck(app_ctx):
+            available[agent_id] = descriptor
+    return available
+
+
+def get_agent_descriptor(agent_id: str) -> Optional[AgentDescriptor]:
+    normalized = (agent_id or "").strip().lower()
+    return _all_agents().get(normalized)
+
+
+def validate_agent_id(agent_id: str) -> str:
+    normalized = (agent_id or "").strip().lower()
+    if normalized not in _all_agents():
+        raise ValueError(f"Unknown agent: {agent_id!r}")
+    return normalized
+
+
+def has_capability(agent_id: str, capability: AgentCapability) -> bool:
+    descriptor = get_agent_descriptor(agent_id)
+    if descriptor is None:
+        return False
+    return capability in descriptor.capabilities
+
+
+__all__ = [
+    "AgentCapability",
+    "AgentDescriptor",
+    "CAR_PLUGIN_API_VERSION",
+    "CAR_AGENT_ENTRYPOINT_GROUP",
+    "get_registered_agents",
+    "get_available_agents",
+    "get_agent_descriptor",
+    "validate_agent_id",
+    "has_capability",
+    "reload_agents",
+]

codex_autorunner/agents/types.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Literal
+from typing import NewType
 
 # When adding agents, update core/config.py agents defaults + validation (config-driven).
-AgentId = Literal["codex", "opencode"]
+AgentId = NewType("AgentId", str)
 
 
 @dataclass(frozen=True)

codex_autorunner/api.py

@@ -0,0 +1,25 @@
+"""Stable public API for Codex Autorunner plugins.
+
+Everything else in the codebase should be treated as internal unless documented.
+"""
+
+from __future__ import annotations
+
+from .agents.base import AgentHarness
+from .agents.registry import AgentCapability, AgentDescriptor, reload_agents
+from .agents.types import AgentId, ConversationRef, ModelCatalog, ModelSpec, TurnRef
+from .plugin_api import CAR_AGENT_ENTRYPOINT_GROUP, CAR_PLUGIN_API_VERSION
+
+__all__ = [
+    "AgentCapability",
+    "AgentDescriptor",
+    "AgentHarness",
+    "AgentId",
+    "ConversationRef",
+    "ModelCatalog",
+    "ModelSpec",
+    "TurnRef",
+    "CAR_AGENT_ENTRYPOINT_GROUP",
+    "CAR_PLUGIN_API_VERSION",
+    "reload_agents",
+]