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

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,146 @@ _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
+
+        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 _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 +247,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

@@ -15,41 +15,17 @@ 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"""
-
-
 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)
-"""
-
-
 def _seed_doc(path: Path, force: bool, content: str) -> None:
     if path.exists() and not force:
         return
@@ -82,6 +58,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,21 +93,25 @@ 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, "# Decisions\n\n")
+    _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,
     )