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

codex_autorunner/core/flows/ux_helpers.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Optional, Protocol
+
+from ...tickets.files import list_ticket_paths
+from .models import FlowEventType, FlowRunRecord
+from .store import FlowStore
+from .worker_process import (
+    check_worker_health,
+    clear_worker_metadata,
+    spawn_flow_worker,
+)
+
+
+@dataclass(frozen=True)
+class BootstrapCheckResult:
+    status: str
+    github_available: Optional[bool] = None
+    repo_slug: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class IssueSeedResult:
+    content: str
+    issue_number: int
+    repo_slug: str
+
+
+class GitHubServiceProtocol(Protocol):
+    def gh_available(self) -> bool: ...
+
+    def gh_authenticated(self) -> bool: ...
+
+    def repo_info(self) -> Any: ...
+
+    def validate_issue_same_repo(self, issue_ref: str) -> int: ...
+
+    def issue_view(self, number: int) -> dict: ...
+
+
+def issue_md_path(repo_root: Path) -> Path:
+    return repo_root.resolve() / ".codex-autorunner" / "ISSUE.md"
+
+
+def issue_md_has_content(repo_root: Path) -> bool:
+    issue_path = issue_md_path(repo_root)
+    if not issue_path.exists():
+        return False
+    try:
+        return bool(issue_path.read_text(encoding="utf-8").strip())
+    except OSError:
+        return False
+
+
+def _ticket_dir(repo_root: Path) -> Path:
+    return repo_root.resolve() / ".codex-autorunner" / "tickets"
+
+
+def bootstrap_check(
+    repo_root: Path,
+    github_service_factory: Optional[Callable[[Path], GitHubServiceProtocol]] = None,
+) -> BootstrapCheckResult:
+    if list_ticket_paths(_ticket_dir(repo_root)):
+        return BootstrapCheckResult(status="ready")
+
+    if issue_md_has_content(repo_root):
+        return BootstrapCheckResult(status="ready")
+
+    gh_available = False
+    repo_slug: Optional[str] = None
+    if github_service_factory is not None:
+        try:
+            gh = github_service_factory(repo_root)
+            gh_available = gh.gh_available() and gh.gh_authenticated()
+            if gh_available:
+                repo_info = gh.repo_info()
+                repo_slug = getattr(repo_info, "name_with_owner", None)
+        except Exception:
+            gh_available = False
+            repo_slug = None
+
+    return BootstrapCheckResult(
+        status="needs_issue", github_available=gh_available, repo_slug=repo_slug
+    )
+
+
+def format_issue_as_markdown(issue: dict, repo_slug: Optional[str] = None) -> str:
+    number = issue.get("number")
+    title = issue.get("title") or ""
+    url = issue.get("url") or ""
+    state = issue.get("state") or ""
+    author = issue.get("author") or {}
+    author_name = (
+        author.get("login") if isinstance(author, dict) else str(author or "unknown")
+    )
+    labels = issue.get("labels")
+    label_names: list[str] = []
+    if isinstance(labels, list):
+        for label in labels:
+            if isinstance(label, dict):
+                name = label.get("name")
+            else:
+                name = label
+            if name:
+                label_names.append(str(name))
+    comments = issue.get("comments")
+    comment_count = None
+    if isinstance(comments, dict):
+        total = comments.get("totalCount")
+        if isinstance(total, int):
+            comment_count = total
+
+    body = issue.get("body") or "(no description)"
+    lines = [
+        f"# Issue #{number}: {title}".strip(),
+        "",
+        f"**Repo:** {repo_slug or 'unknown'}",
+        f"**URL:** {url}",
+        f"**State:** {state}",
+        f"**Author:** {author_name}",
+    ]
+    if label_names:
+        lines.append(f"**Labels:** {', '.join(label_names)}")
+    if comment_count is not None:
+        lines.append(f"**Comments:** {comment_count}")
+    lines.extend(["", "## Description", "", str(body).strip(), ""])
+    return "\n".join(lines)
+
+
+def seed_issue_from_github(
+    repo_root: Path,
+    issue_ref: str,
+    github_service_factory: Optional[Callable[[Path], GitHubServiceProtocol]] = None,
+) -> IssueSeedResult:
+    if github_service_factory is None:
+        raise RuntimeError("GitHub service unavailable.")
+    gh = github_service_factory(repo_root)
+    if not (gh.gh_available() and gh.gh_authenticated()):
+        raise RuntimeError("GitHub CLI is not available or not authenticated.")
+    number = gh.validate_issue_same_repo(issue_ref)
+    issue = gh.issue_view(number=number)
+    repo_info = gh.repo_info()
+    content = format_issue_as_markdown(issue, repo_info.name_with_owner)
+    return IssueSeedResult(
+        content=content, issue_number=number, repo_slug=repo_info.name_with_owner
+    )
+
+
+def seed_issue_from_text(plan_text: str) -> str:
+    return f"# Issue\n\n{plan_text.strip()}\n"
+
+
+def _derive_effective_current_ticket(
+    record: FlowRunRecord, store: Optional[FlowStore]
+) -> Optional[str]:
+    if store is None:
+        return None
+    try:
+        if (
+            getattr(record, "flow_type", None) != "ticket_flow"
+            or not record.status.is_active()
+        ):
+            return None
+        last_started = store.get_last_event_seq_by_types(
+            record.id, [FlowEventType.STEP_STARTED]
+        )
+        last_finished = store.get_last_event_seq_by_types(
+            record.id, [FlowEventType.STEP_COMPLETED, FlowEventType.STEP_FAILED]
+        )
+        in_progress = bool(
+            last_started is not None
+            and (last_finished is None or last_started > last_finished)
+        )
+        if not in_progress:
+            return None
+        return store.get_latest_step_progress_current_ticket(
+            record.id, after_seq=last_finished
+        )
+    except Exception:
+        return None
+
+
+def build_flow_status_snapshot(
+    repo_root: Path, record: FlowRunRecord, store: Optional[FlowStore]
+) -> dict:
+    last_event_seq = None
+    last_event_at = None
+    if store:
+        try:
+            last_event_seq, last_event_at = store.get_last_event_meta(record.id)
+        except Exception:
+            last_event_seq, last_event_at = None, None
+    health = check_worker_health(repo_root, record.id)
+
+    state = record.state or {}
+    current_ticket = None
+    if isinstance(state, dict):
+        ticket_engine = state.get("ticket_engine")
+        if isinstance(ticket_engine, dict):
+            current_ticket = ticket_engine.get("current_ticket")
+            if not (isinstance(current_ticket, str) and current_ticket.strip()):
+                current_ticket = None
+    effective_ticket = current_ticket
+    if not effective_ticket:
+        effective_ticket = _derive_effective_current_ticket(record, store)
+
+    updated_state: Optional[dict] = None
+    if effective_ticket and not current_ticket and isinstance(state, dict):
+        ticket_engine = state.get("ticket_engine")
+        ticket_engine = dict(ticket_engine) if isinstance(ticket_engine, dict) else {}
+        ticket_engine["current_ticket"] = effective_ticket
+        updated_state = dict(state)
+        updated_state["ticket_engine"] = ticket_engine
+
+    return {
+        "last_event_seq": last_event_seq,
+        "last_event_at": last_event_at,
+        "worker_health": health,
+        "effective_current_ticket": effective_ticket,
+        "state": updated_state,
+    }
+
+
+def ensure_worker(repo_root: Path, run_id: str) -> dict:
+    health = check_worker_health(repo_root, run_id)
+    if health.status in {"dead", "mismatch", "invalid"}:
+        try:
+            clear_worker_metadata(health.artifact_path.parent)
+        except Exception:
+            pass
+    if health.is_alive:
+        return {"status": "reused", "health": health}
+
+    proc, stdout_handle, stderr_handle = spawn_flow_worker(repo_root, run_id)
+    return {
+        "status": "spawned",
+        "health": health,
+        "proc": proc,
+        "stdout": stdout_handle,
+        "stderr": stderr_handle,
+    }
+
+
+__all__ = [
+    "BootstrapCheckResult",
+    "IssueSeedResult",
+    "bootstrap_check",
+    "build_flow_status_snapshot",
+    "ensure_worker",
+    "format_issue_as_markdown",
+    "issue_md_has_content",
+    "issue_md_path",
+    "seed_issue_from_github",
+    "seed_issue_from_text",
+]

codex_autorunner/core/git_utils.py

@@ -232,3 +232,65 @@ def git_default_branch(repo_root: Path) -> Optional[str]:
     if raw.startswith("origin/"):
         return raw.split("/", 1)[1]
     return raw
+
+
+def git_diff_stats(
+    repo_root: Path, from_ref: Optional[str] = None, *, include_staged: bool = True
+) -> Optional[dict]:
+    """
+    Get diff statistics (insertions/deletions) for changes.
+
+    Args:
+        repo_root: Repository root path
+        from_ref: Compare against this ref (e.g., a commit SHA). If None, compares
+                  working tree against HEAD.
+        include_staged: When from_ref is None, include staged changes in the diff.
+
+    Returns:
+        Dict with insertions, deletions, files_changed, or None on error.
+        Example: {"insertions": 47, "deletions": 12, "files_changed": 5}
+    """
+    try:
+        if from_ref:
+            # Compare from_ref to working tree (includes all changes: committed + staged + unstaged)
+            proc = run_git(["diff", "--numstat", from_ref], repo_root)
+        elif include_staged:
+            # Working tree + staged vs HEAD
+            proc = run_git(["diff", "--numstat", "HEAD"], repo_root)
+        else:
+            # Only unstaged changes
+            proc = run_git(["diff", "--numstat"], repo_root)
+    except GitError:
+        return None
+    if proc.returncode != 0:
+        return None
+
+    insertions = 0
+    deletions = 0
+    files_changed = 0
+
+    for line in (proc.stdout or "").strip().splitlines():
+        if not line:
+            continue
+        parts = line.split("\t")
+        if len(parts) < 2:
+            continue
+        # Binary files show "-" for both counts
+        add_str, del_str = parts[0], parts[1]
+        if add_str != "-":
+            try:
+                insertions += int(add_str)
+            except ValueError:
+                pass
+        if del_str != "-":
+            try:
+                deletions += int(del_str)
+            except ValueError:
+                pass
+        files_changed += 1
+
+    return {
+        "insertions": insertions,
+        "deletions": deletions,
+        "files_changed": files_changed,
+    }

codex_autorunner/core/hub.py

@@ -5,7 +5,7 @@ import re
 import shutil
 import time
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple
+from typing import Callable, Dict, List, Optional, Tuple
 
 from ..bootstrap import seed_repo_files
 from ..discovery import DiscoveryRecord, discover_and_init
@@ -16,12 +16,15 @@ from ..manifest import (
     sanitize_repo_id,
     save_manifest,
 )
+from .archive import archive_worktree_snapshot, build_snapshot_id
 from .config import HubConfig, RepoConfig, derive_repo_config, load_hub_config
-from .engine import Engine
+from .engine import AppServerSupervisorFactory, BackendFactory, Engine
 from .git_utils import (
     GitError,
     git_available,
+    git_branch,
     git_default_branch,
+    git_head_sha,
     git_is_clean,
     git_upstream_status,
     run_git,
@@ -33,6 +36,9 @@ from .utils import atomic_write
 
 logger = logging.getLogger("codex_autorunner.hub")
 
+BackendFactoryBuilder = Callable[[Path, RepoConfig], BackendFactory]
+AppServerSupervisorFactoryBuilder = Callable[[RepoConfig], AppServerSupervisorFactory]
+
 
 def _git_failure_detail(proc) -> str:
     return (proc.stderr or proc.stdout or "").strip() or f"exit {proc.returncode}"
@@ -195,9 +201,30 @@ class RepoRunner:
         *,
         repo_config: RepoConfig,
         spawn_fn: Optional[SpawnRunnerFn] = None,
+        backend_factory_builder: Optional[BackendFactoryBuilder] = None,
+        app_server_supervisor_factory_builder: Optional[
+            AppServerSupervisorFactoryBuilder
+        ] = None,
+        agent_id_validator: Optional[Callable[[str], str]] = None,
     ):
         self.repo_id = repo_id
-        self._engine = Engine(repo_root, config=repo_config)
+        backend_factory = (
+            backend_factory_builder(repo_root, repo_config)
+            if backend_factory_builder is not None
+            else None
+        )
+        app_server_supervisor_factory = (
+            app_server_supervisor_factory_builder(repo_config)
+            if app_server_supervisor_factory_builder is not None
+            else None
+        )
+        self._engine = Engine(
+            repo_root,
+            config=repo_config,
+            backend_factory=backend_factory,
+            app_server_supervisor_factory=app_server_supervisor_factory,
+            agent_id_validator=agent_id_validator,
+        )
         self._controller = ProcessRunnerController(self._engine, spawn_fn=spawn_fn)
 
     @property
@@ -219,21 +246,46 @@ class RepoRunner:
 
 class HubSupervisor:
     def __init__(
-        self, hub_config: HubConfig, *, spawn_fn: Optional[SpawnRunnerFn] = None
+        self,
+        hub_config: HubConfig,
+        *,
+        spawn_fn: Optional[SpawnRunnerFn] = None,
+        backend_factory_builder: Optional[BackendFactoryBuilder] = None,
+        app_server_supervisor_factory_builder: Optional[
+            AppServerSupervisorFactoryBuilder
+        ] = None,
+        agent_id_validator: Optional[Callable[[str], str]] = None,
     ):
         self.hub_config = hub_config
         self.state_path = hub_config.root / ".codex-autorunner" / "hub_state.json"
         self._runners: Dict[str, RepoRunner] = {}
         self._spawn_fn = spawn_fn
+        self._backend_factory_builder = backend_factory_builder
+        self._app_server_supervisor_factory_builder = (
+            app_server_supervisor_factory_builder
+        )
+        self._agent_id_validator = agent_id_validator
         self.state = load_hub_state(self.state_path, self.hub_config.root)
         self._list_cache_at: Optional[float] = None
         self._list_cache: Optional[List[RepoSnapshot]] = None
         self._reconcile_startup()
 
     @classmethod
-    def from_path(cls, path: Path) -> "HubSupervisor":
+    def from_path(
+        cls,
+        path: Path,
+        *,
+        backend_factory_builder: Optional[BackendFactoryBuilder] = None,
+        app_server_supervisor_factory_builder: Optional[
+            AppServerSupervisorFactoryBuilder
+        ] = None,
+    ) -> "HubSupervisor":
         config = load_hub_config(path)
-        return cls(config)
+        return cls(
+            config,
+            backend_factory_builder=backend_factory_builder,
+            app_server_supervisor_factory_builder=app_server_supervisor_factory_builder,
+        )
 
     def scan(self) -> List[RepoSnapshot]:
         self._invalidate_list_cache()
@@ -268,8 +320,24 @@ class HubSupervisor:
                 repo_config = derive_repo_config(
                     self.hub_config, record.absolute_path, load_env=False
                 )
+                backend_factory = (
+                    self._backend_factory_builder(record.absolute_path, repo_config)
+                    if self._backend_factory_builder is not None
+                    else None
+                )
+                app_server_supervisor_factory = (
+                    self._app_server_supervisor_factory_builder(repo_config)
+                    if self._app_server_supervisor_factory_builder is not None
+                    else None
+                )
                 controller = ProcessRunnerController(
-                    Engine(record.absolute_path, config=repo_config)
+                    Engine(
+                        record.absolute_path,
+                        config=repo_config,
+                        backend_factory=backend_factory,
+                        app_server_supervisor_factory=app_server_supervisor_factory,
+                        agent_id_validator=self._agent_id_validator,
+                    )
                 )
                 controller.reconcile()
             except Exception as exc:
@@ -593,6 +661,9 @@ class HubSupervisor:
         worktree_repo_id: str,
         delete_branch: bool = False,
         delete_remote: bool = False,
+        archive: bool = True,
+        force_archive: bool = False,
+        archive_note: Optional[str] = None,
     ) -> None:
         self._invalidate_list_cache()
         manifest = load_manifest(self.hub_config.manifest_path, self.hub_config.root)
@@ -613,6 +684,44 @@ class HubSupervisor:
         if runner:
             runner.stop()
 
+        if archive:
+            branch_name = entry.branch or git_branch(worktree_path) or "unknown"
+            head_sha = git_head_sha(worktree_path) or "unknown"
+            snapshot_id = build_snapshot_id(branch_name, head_sha)
+            logger.info(
+                "Hub archive worktree start id=%s snapshot_id=%s",
+                worktree_repo_id,
+                snapshot_id,
+            )
+            try:
+                result = archive_worktree_snapshot(
+                    base_repo_root=base_path,
+                    base_repo_id=base.id,
+                    worktree_repo_root=worktree_path,
+                    worktree_repo_id=worktree_repo_id,
+                    branch=branch_name,
+                    worktree_of=entry.worktree_of,
+                    note=archive_note,
+                    snapshot_id=snapshot_id,
+                    head_sha=head_sha,
+                    source_path=entry.path,
+                )
+            except Exception as exc:
+                logger.exception(
+                    "Hub archive worktree failed id=%s snapshot_id=%s",
+                    worktree_repo_id,
+                    snapshot_id,
+                )
+                if not force_archive:
+                    raise ValueError(f"Worktree archive failed: {exc}") from exc
+            else:
+                logger.info(
+                    "Hub archive worktree complete id=%s snapshot_id=%s status=%s",
+                    worktree_repo_id,
+                    result.snapshot_id,
+                    result.status,
+                )
+
         # Remove worktree from base repo.
         try:
             proc = run_git(
@@ -777,6 +886,11 @@ class HubSupervisor:
             repo_root,
             repo_config=repo_config,
             spawn_fn=self._spawn_fn,
+            backend_factory_builder=self._backend_factory_builder,
+            app_server_supervisor_factory_builder=(
+                self._app_server_supervisor_factory_builder
+            ),
+            agent_id_validator=self._agent_id_validator,
         )
         self._runners[repo_id] = runner
         return runner

codex_autorunner/core/notifications.py

@@ -23,6 +23,18 @@ class NotificationManager:
         self._warned_missing: set[str] = set()
         self._enabled_mode = self._parse_enabled(self._cfg.get("enabled"))
         self._events = self._normalize_events(self._cfg.get("events"))
+        timeout_raw = self._cfg.get("timeout_seconds", DEFAULT_TIMEOUT_SECONDS)
+        try:
+            timeout_seconds = (
+                float(timeout_raw)
+                if timeout_raw is not None
+                else DEFAULT_TIMEOUT_SECONDS
+            )
+        except (TypeError, ValueError):
+            timeout_seconds = DEFAULT_TIMEOUT_SECONDS
+        if timeout_seconds <= 0:
+            timeout_seconds = DEFAULT_TIMEOUT_SECONDS
+        self._timeout_seconds = timeout_seconds
         self._warn_unknown_events(self._events)
         discord_cfg = self._cfg.get("discord")
         self._discord: Dict[str, Any] = (
@@ -202,7 +214,7 @@ class NotificationManager:
         if not targets:
             return
         try:
-            with httpx.Client(timeout=DEFAULT_TIMEOUT_SECONDS) as client:
+            with httpx.Client(timeout=self._timeout_seconds) as client:
                 self._send_sync(client, targets, message)
         except Exception as exc:
             self._log_warning("Notification delivery failed", exc)
@@ -216,7 +228,7 @@ class NotificationManager:
         if not targets:
             return
         try:
-            async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT_SECONDS) as client:
+            async with httpx.AsyncClient(timeout=self._timeout_seconds) as client:
                 await self._send_async(client, targets, message)
         except Exception as exc:
             self._log_warning("Notification delivery failed", exc)

codex_autorunner/core/ports/__init__.py

@@ -0,0 +1,28 @@
+from .agent_backend import AgentBackend, AgentEvent, AgentEventType, now_iso
+from .run_event import (
+    ApprovalRequested,
+    Completed,
+    Failed,
+    OutputDelta,
+    RunEvent,
+    RunNotice,
+    Started,
+    TokenUsage,
+    ToolCall,
+)
+
+__all__ = [
+    "AgentBackend",
+    "AgentEvent",
+    "AgentEventType",
+    "now_iso",
+    "RunEvent",
+    "Started",
+    "OutputDelta",
+    "ToolCall",
+    "ApprovalRequested",
+    "TokenUsage",
+    "RunNotice",
+    "Completed",
+    "Failed",
+]

codex_autorunner/{integrations/agents → core/ports}/agent_backend.py

@@ -117,15 +117,15 @@ class AgentBackend:
     async def start_session(self, target: dict, context: dict) -> str:
         raise NotImplementedError
 
-    async def run_turn(
+    def run_turn(
         self, session_id: str, message: str
     ) -> AsyncGenerator[AgentEvent, None]:
         raise NotImplementedError
 
-    async def stream_events(self, session_id: str) -> AsyncGenerator[AgentEvent, None]:
+    def stream_events(self, session_id: str) -> AsyncGenerator[AgentEvent, None]:
         raise NotImplementedError
 
-    async def run_turn_events(
+    def run_turn_events(
         self, session_id: str, message: str
     ) -> AsyncGenerator[Any, None]:
         raise NotImplementedError
@@ -140,3 +140,11 @@ class AgentBackend:
         self, description: str, context: Optional[Dict[str, Any]] = None
     ) -> bool:
         raise NotImplementedError
+
+
+__all__ = [
+    "AgentBackend",
+    "AgentEvent",
+    "AgentEventType",
+    "now_iso",
+]

codex_autorunner/core/ports/backend_orchestrator.py

@@ -0,0 +1,41 @@
+"""Protocol for backend orchestrators used by the Engine."""
+
+from __future__ import annotations
+
+from typing import Any, AsyncGenerator, Optional, Protocol
+
+from .run_event import RunEvent
+
+
+class BackendOrchestrator(Protocol):
+    def run_turn(
+        self,
+        *,
+        agent_id: str,
+        state: Any,
+        prompt: str,
+        model: Optional[str],
+        reasoning: Optional[str],
+        session_key: str,
+    ) -> AsyncGenerator[RunEvent, None]: ...
+
+    async def interrupt(self, agent_id: str, state: Any) -> None: ...
+
+    def get_thread_id(self, session_key: str) -> Optional[str]: ...
+
+    def set_thread_id(self, session_key: str, thread_id: str) -> None: ...
+
+    def build_app_server_supervisor(
+        self,
+        *,
+        event_prefix: str,
+        notification_handler: Optional[Any] = None,
+    ) -> Optional[Any]: ...
+
+    def ensure_opencode_supervisor(self) -> Optional[Any]: ...
+
+    def get_last_turn_id(self) -> Optional[str]: ...
+
+    def get_last_thread_info(self) -> Optional[dict[str, Any]]: ...
+
+    def get_last_token_total(self) -> Optional[dict[str, Any]]: ...