codex-autorunner 0.1.2__py3-none-any.whl → 1.1.0__py3-none-any.whl

codex_autorunner/agents/opencode/supervisor.py

@@ -11,6 +11,7 @@ from typing import Any, Mapping, Optional, Sequence
 import httpx
 
 from ...core.logging_utils import log_event
+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
@@ -53,20 +54,28 @@ class OpenCodeSupervisor:
         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._session_stall_timeout_seconds = session_stall_timeout_seconds
         if password and not username:
             username = "opencode"
-        self._auth = (username, password) if password else None
+        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)
@@ -79,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:
@@ -98,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
@@ -108,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
@@ -187,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()
@@ -287,7 +296,7 @@ class OpenCodeSupervisor:
                     logging.WARNING,
                     "opencode.openapi.fetch_failed",
                     base_url=base_url,
-                    exc=str(exc),
+                    exc=exc,
                 )
                 handle.openapi_spec = {}
             handle.started = True
@@ -356,7 +365,7 @@ class OpenCodeSupervisor:
                     logging.WARNING,
                     "opencode.openapi.fetch_failed",
                     base_url=base_url,
-                    exc=str(exc),
+                    exc=exc,
                 )
                 handle.openapi_spec = {}
             self._start_stdout_drain(handle)
@@ -468,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

@@ -1,9 +1,11 @@
 from __future__ import annotations
 
+import importlib.metadata
 import logging
 from dataclasses import dataclass
-from typing import Any, Callable, Literal, Optional
+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
@@ -22,11 +24,20 @@ AgentCapability = Literal[
 
 @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:
@@ -54,7 +65,7 @@ def _check_opencode_health(ctx: Any) -> bool:
     return supervisor is not None
 
 
-_REGISTERED_AGENTS: dict[str, AgentDescriptor] = {
+_BUILTIN_AGENTS: dict[str, AgentDescriptor] = {
     "codex": AgentDescriptor(
         id="codex",
         name="Codex",
@@ -88,32 +99,165 @@ _REGISTERED_AGENTS: dict[str, AgentDescriptor] = {
     ),
 }
 
+# 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
+
+        api_version_raw = getattr(descriptor, "plugin_api_version", None)
+        try:
+            api_version = int(api_version_raw)
+        except Exception:
+            api_version = None
+        if api_version is None:
+            _logger.warning(
+                "Ignoring agent plugin %s: invalid api_version %s",
+                agent_id,
+                api_version_raw,
+            )
+            continue
+        if api_version > CAR_PLUGIN_API_VERSION:
+            _logger.warning(
+                "Ignoring agent plugin %s (api_version=%s) requires newer core (%s)",
+                agent_id,
+                api_version,
+                CAR_PLUGIN_API_VERSION,
+            )
+            continue
+        if api_version < CAR_PLUGIN_API_VERSION:
+            _logger.info(
+                "Loaded agent plugin %s with older api_version=%s (current=%s)",
+                agent_id,
+                api_version,
+                CAR_PLUGIN_API_VERSION,
+            )
+
+        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 _REGISTERED_AGENTS.copy()
+    return _all_agents().copy()
 
 
 def get_available_agents(app_ctx: Any) -> dict[str, AgentDescriptor]:
-    available = {}
-    for agent_id, descriptor in _REGISTERED_AGENTS.items():
+    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]:
-    return _REGISTERED_AGENTS.get(agent_id)
+    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 _REGISTERED_AGENTS:
+    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 = _REGISTERED_AGENTS.get(agent_id)
+    descriptor = get_agent_descriptor(agent_id)
     if descriptor is None:
         return False
     return capability in descriptor.capabilities
@@ -122,9 +266,12 @@ def has_capability(agent_id: str, capability: AgentCapability) -> bool:
 __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/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",
+]

codex_autorunner/bootstrap.py

@@ -11,43 +11,21 @@ from .core.config import (
     resolve_hub_config_data,
 )
 from .core.state import RunnerState, save_state
+from .core.ticket_linter_cli import ensure_ticket_linter
+from .core.ticket_manager_cli import ensure_ticket_manager
 from .core.utils import atomic_write
 from .manifest import load_manifest
 
 GITIGNORE_CONTENT = "*"
+GENERATED_CONFIG_HEADER = "# GENERATED by CAR - DO NOT EDIT\n"
 
 
 def sample_todo() -> str:
-    return """# TODO\n\n- [ ] Replace this item with your first task\n- [ ] Add another task\n- [x] Example completed item\n"""
-
-
-def sample_opinions() -> str:
-    return """# Opinions\n\n- Prefer small, well-tested changes.\n- Keep docs in sync with code.\n- Avoid unnecessary dependencies.\n"""
+    return ""
 
 
 def sample_spec() -> str:
-    return """# Spec\n\n## Context\n- Add project background and goals here.\n\n## Requirements\n- Requirement 1\n- Requirement 2\n\n## Non-goals\n- Out of scope items\n"""
-
-
-def sample_summary() -> str:
-    return """# Summary
-
-This doc is the **user-facing report and handoff** for work done by CAR agents.
-
-Use it for:
-- Anything that requires **user action** or an **external party** (not agents).
-- Unresolved decisions or blockers that agents can’t finish autonomously.
-- A final condensed report once TODO is complete.
-
-## External/user actions
-- (none)
-
-## Open questions / blockers
-- (none)
-
-## Final report
-- (pending)
-"""
+    return ""
 
 
 def _seed_doc(path: Path, force: bool, content: str) -> None:
@@ -82,6 +60,7 @@ def write_hub_config(hub_root: Path, force: bool = False) -> Path:
         return config_path
     config_path.parent.mkdir(parents=True, exist_ok=True)
     with config_path.open("w", encoding="utf-8") as f:
+        f.write(GENERATED_CONFIG_HEADER)
         yaml.safe_dump(
             resolve_hub_config_data(hub_root),
             f,
@@ -116,24 +95,30 @@ def seed_repo_files(
     if not log_path.exists() or force:
         log_path.write_text("", encoding="utf-8")
 
-    _seed_doc(ca_dir / "TODO.md", force, sample_todo())
-    _seed_doc(ca_dir / "PROGRESS.md", force, "# Progress\n\n")
-    _seed_doc(ca_dir / "OPINIONS.md", force, sample_opinions())
-    _seed_doc(ca_dir / "SPEC.md", force, sample_spec())
-    _seed_doc(ca_dir / "SUMMARY.md", force, sample_summary())
+    tickets_dir = ca_dir / "tickets"
+    if not tickets_dir.exists() or force:
+        tickets_dir.mkdir(parents=True, exist_ok=True)
+
+    workspace_dir = ca_dir / "workspace"
+    if not workspace_dir.exists() or force:
+        workspace_dir.mkdir(parents=True, exist_ok=True)
+
+    _seed_doc(workspace_dir / "active_context.md", force, sample_todo())
+    _seed_doc(workspace_dir / "decisions.md", force, "")
+    _seed_doc(workspace_dir / "spec.md", force, sample_spec())
 
     # Seed an always-available briefing doc for interactive Codex sessions.
     ensure_about_car_file_for_repo(
         repo_root,
         doc_paths={
-            "todo": ca_dir / "TODO.md",
-            "progress": ca_dir / "PROGRESS.md",
-            "opinions": ca_dir / "OPINIONS.md",
-            "spec": ca_dir / "SPEC.md",
-            "summary": ca_dir / "SUMMARY.md",
+            "active_context": workspace_dir / "active_context.md",
+            "decisions": workspace_dir / "decisions.md",
+            "spec": workspace_dir / "spec.md",
         },
         force=force,
     )
+    ensure_ticket_linter(repo_root, force=force)
+    ensure_ticket_manager(repo_root, force=force)
 
 
 def seed_hub_files(hub_root: Path, force: bool = False) -> None: