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

codex_autorunner/core/context_awareness.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Literal
+
+CAR_AWARENESS_BLOCK = """<injected context>
+You are operating inside a Codex Autorunner (CAR) managed repo.
+
+CAR’s durable control-plane lives under `.codex-autorunner/`:
+- `.codex-autorunner/ABOUT_CAR.md` — short repo-local briefing (ticket/workspace conventions + helper scripts).
+- `.codex-autorunner/tickets/` — ordered ticket queue (`TICKET-###*.md`) used by the ticket flow runner.
+- `.codex-autorunner/workspace/` — shared context docs:
+  - `active_context.md` — current “north star” context; kept fresh for ongoing work.
+  - `spec.md` — longer spec / acceptance criteria when needed.
+  - `decisions.md` — prior decisions / tradeoffs when relevant.
+
+Intent signals: if the user mentions tickets, “dispatch”, “resume”, workspace docs, or `.codex-autorunner/`, they are likely referring to CAR artifacts/workflow rather than generic repo files.
+
+Use the above as orientation. If you need the operational details (exact helper commands, what CAR auto-generates), read `.codex-autorunner/ABOUT_CAR.md`.
+</injected context>"""
+
+ROLE_ADDENDUM_START = "<role addendum>"
+ROLE_ADDENDUM_END = "</role addendum>"
+
+
+def format_file_role_addendum(
+    kind: Literal["ticket", "workspace", "other"],
+    rel_path: str,
+) -> str:
+    """Format a short role-specific addendum for prompts."""
+    if kind == "ticket":
+        text = f"This target is a CAR ticket at `{rel_path}`."
+    elif kind == "workspace":
+        text = f"This target is a CAR workspace doc at `{rel_path}`."
+    elif kind == "other":
+        text = f"This target file is `{rel_path}`."
+    else:
+        raise ValueError(f"Unsupported role addendum kind: {kind}")
+    return f"{ROLE_ADDENDUM_START}\n{text}\n{ROLE_ADDENDUM_END}"

codex_autorunner/core/docs.py

@@ -1,122 +0,0 @@
-import re
-from pathlib import Path
-from typing import List, Tuple
-
-from .config import Config
-
-_TODO_LINE_RE = re.compile(r"^\s*[-*]\s*\[(?P<state>[ xX])\]\s*(?P<text>.*)$")
-
-
-def _iter_meaningful_lines(content: str):
-    in_code_fence = False
-    in_html_comment = False
-    html_comment_pattern = re.compile(r"<!--.*?-->", re.DOTALL)
-
-    for line in content.splitlines():
-        stripped = line.strip()
-
-        if stripped.startswith("```"):
-            in_code_fence = not in_code_fence
-            continue
-
-        if in_code_fence:
-            continue
-
-        if line.lstrip().startswith("<!--"):
-            if "-->" in line:
-                if html_comment_pattern.search(line):
-                    continue
-            else:
-                in_html_comment = True
-                continue
-
-        if in_html_comment:
-            if "-->" in line:
-                in_html_comment = False
-            continue
-
-        yield line
-
-
-def parse_todos(content: str) -> Tuple[List[str], List[str]]:
-    outstanding: List[str] = []
-    done: List[str] = []
-    if not content:
-        return outstanding, done
-
-    for line in _iter_meaningful_lines(content):
-        match = _TODO_LINE_RE.match(line)
-        if match:
-            state = match.group("state")
-            text = match.group("text").strip()
-            if state in (" ",):
-                outstanding.append(text)
-            elif state in ("x", "X"):
-                done.append(text)
-    return outstanding, done
-
-
-_TODO_CHECKBOX_RE = re.compile(r"^\s*[-*]\s*\[(?P<state>[ xX])\]\s+\S")
-_TODO_BULLET_RE = re.compile(r"^\s*[-*]\s+")
-
-
-def validate_todo_markdown(content: str) -> List[str]:
-    """
-    Validate that TODO content contains tasks as markdown checkboxes.
-
-    Rules:
-    - If the file has any non-heading, non-empty content, it must include at least one checkbox line.
-    - Any bullet line must be a checkbox bullet (no plain '-' bullets for tasks).
-    """
-    errors: List[str] = []
-    if content is None:
-        return ["TODO is missing"]
-    lines = list(_iter_meaningful_lines(content))
-    meaningful = [
-        line for line in lines if line.strip() and not line.lstrip().startswith("#")
-    ]
-    if not meaningful:
-        return []
-    checkbox_lines = [line for line in meaningful if _TODO_CHECKBOX_RE.match(line)]
-    if not checkbox_lines:
-        errors.append(
-            "TODO must contain at least one markdown checkbox task line like `- [ ] ...`."
-        )
-    bullet_lines = [line for line in meaningful if _TODO_BULLET_RE.match(line)]
-    non_checkbox_bullets = [
-        line for line in bullet_lines if not _TODO_CHECKBOX_RE.match(line)
-    ]
-    if non_checkbox_bullets:
-        sample = non_checkbox_bullets[0].strip()
-        errors.append(
-            "TODO contains non-checkbox bullet(s); use `- [ ] ...` instead. "
-            f"Example: `{sample}`"
-        )
-    return errors
-
-
-class DocsManager:
-    def __init__(self, config: Config):
-        self.config = config
-
-    def read_doc(self, key: str) -> str:
-        try:
-            path = self.config.doc_path(key)
-        except KeyError:
-            return ""
-        return path.read_text(encoding="utf-8") if path.exists() else ""
-
-    def todos(self) -> Tuple[List[str], List[str]]:
-        # Legacy helper retained for backward compatibility; newer configs may not
-        # have a TODO doc at all.
-        try:
-            todo_path: Path = self.config.doc_path("todo")
-        except KeyError:
-            return [], []
-        if not todo_path.exists():
-            return [], []
-        return parse_todos(todo_path.read_text(encoding="utf-8"))
-
-    def todos_done(self) -> bool:
-        outstanding, _ = self.todos()
-        return len(outstanding) == 0

codex_autorunner/core/drafts.py

@@ -2,12 +2,18 @@ from __future__ import annotations
 
 import hashlib
 import json
+import logging
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, Optional
 
 from .utils import atomic_write
 
 FILE_CHAT_STATE_NAME = "file_chat_state.json"
+FILE_CHAT_STATE_CORRUPT_SUFFIX = ".corrupt"
+FILE_CHAT_STATE_NOTICE_SUFFIX = ".corrupt.json"
+
+logger = logging.getLogger(__name__)
 
 
 def state_path(repo_root: Path) -> Path:
@@ -23,12 +29,19 @@ def load_state(repo_root: Path) -> Dict[str, Any]:
     if not path.exists():
         return {"drafts": {}}
     try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-        if isinstance(data, dict):
-            return data
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        logger.warning("Failed to read file chat state at %s: %s", path, exc)
         return {"drafts": {}}
-    except Exception:
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        _handle_corrupt_state(path, str(exc))
+        return {"drafts": {}}
+    if not isinstance(data, dict):
+        _handle_corrupt_state(path, f"Expected JSON object, got {type(data).__name__}")
         return {"drafts": {}}
+    return data
 
 
 def save_state(repo_root: Path, state: Dict[str, Any]) -> None:
@@ -80,3 +93,44 @@ def invalidate_drafts_for_path(repo_root: Path, rel_path: str) -> list[str]:
     if removed_keys:
         save_drafts(repo_root, drafts)
     return removed_keys
+
+
+def _stamp() -> str:
+    return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+
+
+def _notice_path(path: Path) -> Path:
+    return path.with_name(f"{path.name}{FILE_CHAT_STATE_NOTICE_SUFFIX}")
+
+
+def _handle_corrupt_state(path: Path, detail: str) -> None:
+    stamp = _stamp()
+    backup_path = path.with_name(f"{path.name}{FILE_CHAT_STATE_CORRUPT_SUFFIX}.{stamp}")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        path.replace(backup_path)
+        backup_value = str(backup_path)
+    except OSError:
+        backup_value = ""
+    notice = {
+        "status": "corrupt",
+        "message": "Draft state reset due to corrupted file_chat_state.json.",
+        "detail": detail,
+        "detected_at": stamp,
+        "backup_path": backup_value,
+    }
+    notice_path = _notice_path(path)
+    try:
+        atomic_write(notice_path, json.dumps(notice, indent=2) + "\n")
+    except Exception:
+        logger.warning("Failed to write draft corruption notice at %s", notice_path)
+    try:
+        atomic_write(path, json.dumps({"drafts": {}}, indent=2) + "\n")
+    except Exception:
+        logger.warning("Failed to reset draft state at %s", path)
+    logger.warning(
+        "Corrupted file chat state detected; backup=%s notice=%s detail=%s",
+        backup_value or "unavailable",
+        notice_path,
+        detail,
+    )

codex_autorunner/core/exceptions.py

@@ -58,3 +58,7 @@ class CircuitOpenError(CriticalError):
             msg,
             user_message=f"{service_name} is temporarily unavailable. Please try again later.",
         )
+
+
+class AppServerError(CodexError):
+    pass

codex_autorunner/core/filebox.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, Iterable, List, Tuple
+
+
+@dataclass(frozen=True)
+class FileBoxEntry:
+    name: str
+    box: str  # "inbox" | "outbox"
+    size: int | None
+    modified_at: str | None
+    source: str  # "filebox", "pma", "telegram"
+    path: Path
+
+
+BOXES = ("inbox", "outbox")
+
+
+def filebox_root(repo_root: Path) -> Path:
+    return Path(repo_root) / ".codex-autorunner" / "filebox"
+
+
+def inbox_dir(repo_root: Path) -> Path:
+    return filebox_root(repo_root) / "inbox"
+
+
+def outbox_dir(repo_root: Path) -> Path:
+    return filebox_root(repo_root) / "outbox"
+
+
+def outbox_pending_dir(repo_root: Path) -> Path:
+    # Preserves Telegram pending semantics while keeping everything under the shared FileBox.
+    return outbox_dir(repo_root) / "pending"
+
+
+def outbox_sent_dir(repo_root: Path) -> Path:
+    return outbox_dir(repo_root) / "sent"
+
+
+def ensure_structure(repo_root: Path) -> None:
+    for path in (
+        inbox_dir(repo_root),
+        outbox_dir(repo_root),
+        outbox_pending_dir(repo_root),
+        outbox_sent_dir(repo_root),
+    ):
+        path.mkdir(parents=True, exist_ok=True)
+
+
+def sanitize_filename(name: str) -> str:
+    base = Path(name or "").name
+    if not base or base in {".", ".."}:
+        raise ValueError("Missing filename")
+    # Reject any path separators or traversal segments up-front.
+    if name != base or "/" in name or "\\" in name:
+        raise ValueError("Invalid filename")
+    parts = Path(base).parts
+    if any(part in {"", ".", ".."} for part in parts):
+        raise ValueError("Invalid filename")
+    return base
+
+
+def _legacy_paths(repo_root: Path, box: str) -> List[Tuple[str, Path]]:
+    root = Path(repo_root)
+    paths: List[Tuple[str, Path]] = []
+    if box not in BOXES:
+        return paths
+
+    # PMA legacy paths
+    pma_dir = root / ".codex-autorunner" / "pma" / box
+    paths.append(("pma", pma_dir))
+
+    # Telegram legacy paths (topic-scoped). We merge inbox and outbox/pending|sent.
+    telegram_root = root / ".codex-autorunner" / "uploads" / "telegram-files"
+    if telegram_root.exists():
+        for topic in telegram_root.iterdir():
+            if not topic.is_dir():
+                continue
+            if box == "inbox":
+                paths.append(("telegram", topic / "inbox"))
+            elif box == "outbox":
+                paths.append(("telegram", topic / "outbox" / "pending"))
+                paths.append(("telegram", topic / "outbox" / "sent"))
+    return paths
+
+
+def _gather_files(entries: Iterable[Tuple[str, Path]], box: str) -> List[FileBoxEntry]:
+    collected: List[FileBoxEntry] = []
+    for source, folder in entries:
+        if not folder.exists():
+            continue
+        try:
+            for path in folder.iterdir():
+                try:
+                    if not path.is_file():
+                        continue
+                    stat = path.stat()
+                    collected.append(
+                        FileBoxEntry(
+                            name=path.name,
+                            box=box,
+                            size=stat.st_size if stat else None,
+                            modified_at=_format_mtime(stat.st_mtime) if stat else None,
+                            source=source,
+                            path=path,
+                        )
+                    )
+                except OSError:
+                    continue
+        except OSError:
+            continue
+    return collected
+
+
+def _dedupe(entries: List[FileBoxEntry]) -> List[FileBoxEntry]:
+    # Prefer primary filebox entries over legacy duplicates.
+    deduped: Dict[Tuple[str, str], FileBoxEntry] = {}
+    for entry in entries:
+        key = (entry.box, entry.name)
+        existing = deduped.get(key)
+        if existing is None:
+            deduped[key] = entry
+            continue
+        if existing.source != "filebox" and entry.source == "filebox":
+            deduped[key] = entry
+    return list(deduped.values())
+
+
+def _format_mtime(ts: float | None) -> str | None:
+    if ts is None:
+        return None
+    try:
+        return datetime.fromtimestamp(ts, tz=timezone.utc).isoformat()
+    except Exception:
+        return None
+
+
+def list_filebox(
+    repo_root: Path, *, include_legacy: bool = True
+) -> Dict[str, List[FileBoxEntry]]:
+    ensure_structure(repo_root)
+    results: Dict[str, List[FileBoxEntry]] = {}
+    for box in BOXES:
+        primaries = _gather_files([("filebox", _box_dir(repo_root, box))], box)
+        legacy = (
+            _gather_files(_legacy_paths(repo_root, box), box) if include_legacy else []
+        )
+        results[box] = _dedupe(primaries + legacy)
+    return results
+
+
+def _box_dir(repo_root: Path, box: str) -> Path:
+    if box == "inbox":
+        return inbox_dir(repo_root)
+    if box == "outbox":
+        return outbox_dir(repo_root)
+    raise ValueError("Invalid filebox")
+
+
+def _target_path(repo_root: Path, box: str, filename: str) -> Path:
+    """Return a resolved path within the FileBox, rejecting traversal attempts."""
+
+    safe_name = sanitize_filename(filename)
+    target_dir = _box_dir(repo_root, box)
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    root = target_dir.resolve()
+    candidate = (root / safe_name).resolve()
+    try:
+        candidate.relative_to(root)
+    except ValueError as exc:
+        raise ValueError("Invalid filename") from exc
+    if candidate.parent != root:
+        # Disallow sneaky path tricks that resolve inside nested folders.
+        raise ValueError("Invalid filename")
+    return candidate
+
+
+def save_file(repo_root: Path, box: str, filename: str, data: bytes) -> Path:
+    if box not in BOXES:
+        raise ValueError("Invalid box")
+    ensure_structure(repo_root)
+    path = _target_path(repo_root, box, filename)
+    path.write_bytes(data)
+    return path
+
+
+def resolve_file(repo_root: Path, box: str, filename: str) -> FileBoxEntry | None:
+    if box not in BOXES:
+        return None
+    safe_name = sanitize_filename(filename)
+    paths: List[Tuple[str, Path]] = [("filebox", _box_dir(repo_root, box))]
+    paths.extend(_legacy_paths(repo_root, box))
+    candidates = _gather_files(paths, box)
+    for entry in candidates:
+        if entry.name == safe_name:
+            return entry
+    return None
+
+
+def delete_file(repo_root: Path, box: str, filename: str) -> bool:
+    if box not in BOXES:
+        return False
+    safe_name = sanitize_filename(filename)
+    paths: List[Tuple[str, Path]] = [("filebox", _box_dir(repo_root, box))]
+    paths.extend(_legacy_paths(repo_root, box))
+    candidates = _gather_files(paths, box)
+    removed = False
+    for entry in candidates:
+        if entry.name != safe_name:
+            continue
+        try:
+            entry.path.unlink()
+            removed = True
+        except OSError:
+            continue
+    return removed
+
+
+def migrate_legacy(repo_root: Path) -> int:
+    """
+    Opportunistically copy legacy PMA/Telegram files into the shared FileBox.
+    Returns the number of files copied.
+    """
+    copied = 0
+    ensure_structure(repo_root)
+    for box in BOXES:
+        target_dir = _box_dir(repo_root, box)
+        target_dir.mkdir(parents=True, exist_ok=True)
+        for _source, folder in _legacy_paths(repo_root, box):
+            if not folder.exists():
+                continue
+            for path in folder.iterdir():
+                try:
+                    if not path.is_file():
+                        continue
+                    dest = target_dir / path.name
+                    if dest.exists():
+                        continue
+                    shutil.copy2(path, dest)
+                    copied += 1
+                except OSError:
+                    continue
+    return copied
+
+
+__all__ = [
+    "BOXES",
+    "FileBoxEntry",
+    "delete_file",
+    "filebox_root",
+    "inbox_dir",
+    "list_filebox",
+    "migrate_legacy",
+    "outbox_dir",
+    "outbox_pending_dir",
+    "outbox_sent_dir",
+    "resolve_file",
+    "sanitize_filename",
+    "save_file",
+]

codex_autorunner/core/flows/controller.py

@@ -4,11 +4,31 @@ import uuid
 from pathlib import Path
 from typing import Any, AsyncGenerator, Callable, Dict, Optional, Set
 
+from ..lifecycle_events import LifecycleEventEmitter
+from ..utils import find_repo_root
 from .definition import FlowDefinition
 from .models import FlowEvent, FlowRunRecord, FlowRunStatus
 from .runtime import FlowRuntime
 from .store import FlowStore
 
+
+def _find_hub_root(repo_root: Optional[Path] = None) -> Optional[Path]:
+    if repo_root is None:
+        repo_root = find_repo_root()
+    if repo_root is None:
+        return None
+    current = repo_root
+    for _ in range(5):
+        manifest_path = current / ".codex-autorunner" / "manifest.yml"
+        if manifest_path.exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            break
+        current = parent
+    return None
+
+
 _logger = logging.getLogger(__name__)
 
 
@@ -18,13 +38,24 @@ class FlowController:
         definition: FlowDefinition,
         db_path: Path,
         artifacts_root: Path,
+        durable: bool = False,
+        hub_root: Optional[Path] = None,
     ):
         self.definition = definition
         self.db_path = db_path
         self.artifacts_root = artifacts_root
-        self.store = FlowStore(db_path)
+        self.store = FlowStore(db_path, durable=durable)
         self._event_listeners: Set[Callable[[FlowEvent], None]] = set()
+        self._lifecycle_event_listeners: Set[Callable[[str, str, str, dict], None]] = (
+            set()
+        )
         self._lock = asyncio.Lock()
+        self._lifecycle_emitter: Optional[LifecycleEventEmitter] = None
+        if hub_root is None:
+            hub_root = _find_hub_root(db_path.parent.parent if db_path else None)
+        if hub_root is not None:
+            self._lifecycle_emitter = LifecycleEventEmitter(hub_root)
+            self.add_lifecycle_event_listener(self._emit_to_lifecycle_store)
 
     def initialize(self) -> None:
         self.artifacts_root.mkdir(parents=True, exist_ok=True)
@@ -70,6 +101,7 @@ class FlowController:
             definition=self.definition,
             store=self.store,
             emit_event=self._emit_event,
+            emit_lifecycle_event=self._emit_lifecycle,
         )
         return await runtime.run_flow(run_id=run_id, initial_state=initial_state)
 
@@ -103,7 +135,33 @@ class FlowController:
             cleared = self.store.set_stop_requested(run_id, False)
             if not cleared:
                 raise RuntimeError(f"Failed to clear stop flag for run {run_id}")
-            return cleared
+            if record.status == FlowRunStatus.COMPLETED:
+                return cleared
+            state = dict(record.state or {})
+            engine = state.get("ticket_engine")
+            if isinstance(engine, dict):
+                engine = dict(engine)
+                if engine.get("reason_code") == "max_turns":
+                    engine["total_turns"] = 0
+                engine["status"] = "running"
+                engine.pop("reason", None)
+                engine.pop("reason_details", None)
+                engine.pop("reason_code", None)
+                state["ticket_engine"] = engine
+            state.pop("reason_summary", None)
+
+            updated = self.store.update_flow_run_status(
+                run_id=run_id,
+                status=FlowRunStatus.RUNNING,
+                state=state,
+            )
+            if updated:
+                return updated
+
+            updated = self.store.get_flow_run(run_id)
+            if not updated:
+                raise RuntimeError(f"Failed to get record for run {run_id}")
+            return updated
 
     def get_status(self, run_id: str) -> Optional[FlowRunRecord]:
         return self.store.get_flow_run(run_id)
@@ -150,6 +208,42 @@ class FlowController:
     def remove_event_listener(self, listener: Callable[[FlowEvent], None]) -> None:
         self._event_listeners.discard(listener)
 
+    def add_lifecycle_event_listener(
+        self, listener: Callable[[str, str, str, dict], None]
+    ) -> None:
+        self._lifecycle_event_listeners.add(listener)
+
+    def remove_lifecycle_event_listener(
+        self, listener: Callable[[str, str, str, dict], None]
+    ) -> None:
+        self._lifecycle_event_listeners.discard(listener)
+
+    def _emit_lifecycle(
+        self, event_type: str, repo_id: str, run_id: str, data: Dict[str, Any]
+    ) -> None:
+        for listener in self._lifecycle_event_listeners:
+            try:
+                listener(event_type, repo_id, run_id, data)
+            except Exception as e:
+                _logger.exception("Error in lifecycle event listener: %s", e)
+
+    def _emit_to_lifecycle_store(
+        self, event_type: str, repo_id: str, run_id: str, data: Dict[str, Any]
+    ) -> None:
+        if self._lifecycle_emitter is None:
+            return
+        try:
+            if event_type == "flow_paused":
+                self._lifecycle_emitter.emit_flow_paused(repo_id, run_id, data=data)
+            elif event_type == "flow_completed":
+                self._lifecycle_emitter.emit_flow_completed(repo_id, run_id, data=data)
+            elif event_type == "flow_failed":
+                self._lifecycle_emitter.emit_flow_failed(repo_id, run_id, data=data)
+            elif event_type == "flow_stopped":
+                self._lifecycle_emitter.emit_flow_stopped(repo_id, run_id, data=data)
+        except Exception as exc:
+            _logger.exception("Error emitting to lifecycle store: %s", exc)
+
     def _emit_event(self, event: FlowEvent) -> None:
         for listener in self._event_listeners:
             try:

codex_autorunner/core/flows/models.py

@@ -32,13 +32,26 @@ class FlowEventType(str, Enum):
     STEP_COMPLETED = "step_completed"
     STEP_FAILED = "step_failed"
     AGENT_STREAM_DELTA = "agent_stream_delta"
+    AGENT_MESSAGE_COMPLETE = "agent_message_complete"
+    AGENT_FAILED = "agent_failed"
     APP_SERVER_EVENT = "app_server_event"
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    APPROVAL_REQUESTED = "approval_requested"
     TOKEN_USAGE = "token_usage"
     FLOW_STARTED = "flow_started"
     FLOW_STOPPED = "flow_stopped"
     FLOW_RESUMED = "flow_resumed"
     FLOW_COMPLETED = "flow_completed"
     FLOW_FAILED = "flow_failed"
+    RUN_STARTED = "run_started"
+    RUN_FINISHED = "run_finished"
+    RUN_STATE_CHANGED = "run_state_changed"
+    RUN_NO_PROGRESS = "run_no_progress"
+    PLAN_UPDATED = "plan_updated"
+    DIFF_UPDATED = "diff_updated"
+    RUN_TIMEOUT = "run_timeout"
+    RUN_CANCELLED = "run_cancelled"
 
 
 class FlowRunRecord(BaseModel):