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

codex_autorunner/tickets/models.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+
+@dataclass(frozen=True)
+class TicketFrontmatter:
+    """Parsed, validated ticket frontmatter.
+
+    Only a minimal set of keys are required for orchestration. Additional
+    keys are preserved in `extra` for forward compatibility.
+    """
+
+    agent: str
+    done: bool
+    title: Optional[str] = None
+    goal: Optional[str] = None
+    # Optional model/reasoning overrides for this ticket.
+    model: Optional[str] = None
+    reasoning: Optional[str] = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class TicketDoc:
+    path: Path
+    index: int
+    frontmatter: TicketFrontmatter
+    body: str
+
+
+@dataclass(frozen=True)
+class Dispatch:
+    """Agent-to-human communication dispatched via the outbox.
+
+    A Dispatch is the canonical unit of agent→human communication. The mode
+    determines whether it's informational or requires human action:
+      - "notify": FYI, agent continues working
+      - "pause": Handoff, agent yields and awaits human reply
+    """
+
+    mode: str  # "notify" | "pause"
+    body: str
+    title: Optional[str] = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_handoff(self) -> bool:
+        """True if this dispatch requires human action (mode='pause')."""
+        return self.mode == "pause"
+
+
+@dataclass(frozen=True)
+class DispatchRecord:
+    """Archived dispatch with sequence number and file references.
+
+    This is the envelope/record created when a Dispatch is archived to the
+    dispatch history directory.
+    """
+
+    seq: int
+    dispatch: Dispatch
+    archived_dir: Path
+    archived_files: tuple[Path, ...]
+
+
+@dataclass(frozen=True)
+class TicketRunConfig:
+    ticket_dir: Path
+    runs_dir: Path
+    max_total_turns: int = 25
+    max_lint_retries: int = 3
+    max_commit_retries: int = 2
+    auto_commit: bool = True
+    checkpoint_message_template: str = (
+        "CAR checkpoint: run={run_id} turn={turn} agent={agent}"
+    )
+
+
+@dataclass(frozen=True)
+class TicketResult:
+    """Return value of a single TicketRunner.step() call."""
+
+    status: str  # "continue" | "paused" | "completed" | "failed"
+    state: dict[str, Any]
+    reason: Optional[str] = None
+    reason_details: Optional[str] = None  # Technical details (git status, etc.)
+    dispatch: Optional[DispatchRecord] = None
+    current_ticket: Optional[str] = None
+    agent_output: Optional[str] = None
+    agent_id: Optional[str] = None
+    agent_conversation_id: Optional[str] = None
+    agent_turn_id: Optional[str] = None

codex_autorunner/tickets/outbox.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from .frontmatter import parse_markdown_frontmatter
+from .lint import lint_dispatch_frontmatter
+from .models import Dispatch, DispatchRecord
+
+
+@dataclass(frozen=True)
+class OutboxPaths:
+    """Filesystem paths for the dispatch outbox."""
+
+    run_dir: Path
+    dispatch_dir: Path
+    dispatch_history_dir: Path
+    dispatch_path: Path
+
+
+def resolve_outbox_paths(
+    *, workspace_root: Path, runs_dir: Path, run_id: str
+) -> OutboxPaths:
+    run_dir = workspace_root / runs_dir / run_id
+    dispatch_dir = run_dir / "dispatch"
+    dispatch_history_dir = run_dir / "dispatch_history"
+    dispatch_path = run_dir / "DISPATCH.md"
+    return OutboxPaths(
+        run_dir=run_dir,
+        dispatch_dir=dispatch_dir,
+        dispatch_history_dir=dispatch_history_dir,
+        dispatch_path=dispatch_path,
+    )
+
+
+def ensure_outbox_dirs(paths: OutboxPaths) -> None:
+    paths.dispatch_dir.mkdir(parents=True, exist_ok=True)
+    paths.dispatch_history_dir.mkdir(parents=True, exist_ok=True)
+
+
+def _copy_item(src: Path, dst: Path) -> None:
+    if src.is_dir():
+        shutil.copytree(src, dst)
+    else:
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src, dst)
+
+
+def _list_dispatch_items(dispatch_dir: Path) -> list[Path]:
+    if not dispatch_dir.exists() or not dispatch_dir.is_dir():
+        return []
+    items: list[Path] = []
+    for child in sorted(dispatch_dir.iterdir(), key=lambda p: p.name):
+        if child.name.startswith("."):
+            continue
+        items.append(child)
+    return items
+
+
+def _delete_dispatch_items(items: list[Path]) -> None:
+    for item in items:
+        try:
+            if item.is_dir():
+                shutil.rmtree(item)
+            else:
+                item.unlink()
+        except OSError:
+            # Best-effort cleanup.
+            continue
+
+
+def parse_dispatch(path: Path) -> tuple[Optional[Dispatch], list[str]]:
+    """Parse a dispatch file (DISPATCH.md) into a Dispatch object."""
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        return None, [f"Failed to read dispatch file: {exc}"]
+
+    data, body = parse_markdown_frontmatter(raw)
+    normalized, errors = lint_dispatch_frontmatter(data)
+    if errors:
+        return None, errors
+
+    mode = normalized.get("mode", "notify")
+    title = normalized.get("title")
+    title_str = title.strip() if isinstance(title, str) and title.strip() else None
+    extra = dict(normalized)
+    extra.pop("mode", None)
+    extra.pop("title", None)
+    return (
+        Dispatch(mode=mode, body=body.lstrip("\n"), title=title_str, extra=extra),
+        [],
+    )
+
+
+def create_turn_summary(
+    paths: OutboxPaths,
+    *,
+    next_seq: int,
+    agent_output: str,
+    ticket_id: Optional[str] = None,
+    agent_id: Optional[str] = None,
+    turn_number: Optional[int] = None,
+) -> tuple[Optional[DispatchRecord], list[str]]:
+    """Create a turn summary dispatch record for the agent's final output.
+
+    This creates a synthetic dispatch with mode="turn_summary" to show
+    the agent's final turn output in the dispatch history panel.
+
+    Returns (DispatchRecord, []) on success.
+    Returns (None, errors) on failure.
+    """
+
+    if not agent_output or not agent_output.strip():
+        return None, []
+
+    extra: dict = {}
+    if ticket_id:
+        extra["ticket_id"] = ticket_id
+    if agent_id:
+        extra["agent_id"] = agent_id
+    if turn_number is not None:
+        extra["turn_number"] = turn_number
+    extra["is_turn_summary"] = True
+
+    dispatch = Dispatch(
+        mode="turn_summary",
+        body=agent_output.strip(),
+        title=None,
+        extra=extra,
+    )
+
+    dest = paths.dispatch_history_dir / f"{next_seq:04d}"
+    try:
+        dest.mkdir(parents=True, exist_ok=False)
+    except OSError as exc:
+        return None, [f"Failed to create turn summary dir: {exc}"]
+
+    # Write a synthetic DISPATCH.md for consistency
+    msg_dest = dest / "DISPATCH.md"
+    try:
+        # Write minimal frontmatter + body
+        content = f"---\nmode: turn_summary\n---\n\n{agent_output.strip()}\n"
+        msg_dest.write_text(content, encoding="utf-8")
+    except OSError as exc:
+        return None, [f"Failed to write turn summary: {exc}"]
+
+    return (
+        DispatchRecord(
+            seq=next_seq,
+            dispatch=dispatch,
+            archived_dir=dest,
+            archived_files=(msg_dest,),
+        ),
+        [],
+    )
+
+
+def archive_dispatch(
+    paths: OutboxPaths,
+    *,
+    next_seq: int,
+    ticket_id: Optional[str] = None,
+) -> tuple[Optional[DispatchRecord], list[str]]:
+    """Archive the current dispatch and attachments to the dispatch history.
+
+    Moves DISPATCH.md + attachments into dispatch_history/<seq>/.
+
+    Returns (DispatchRecord, []) on success.
+    Returns (None, []) when no dispatch file exists.
+    Returns (None, errors) on failure.
+    """
+
+    if not paths.dispatch_path.exists():
+        return None, []
+
+    dispatch, errors = parse_dispatch(paths.dispatch_path)
+    if errors or dispatch is None:
+        return None, errors
+
+    # Add ticket_id to extra if provided
+    if ticket_id and dispatch is not None:
+        extra = dict(dispatch.extra)
+        extra["ticket_id"] = ticket_id
+        dispatch = Dispatch(
+            mode=dispatch.mode,
+            body=dispatch.body,
+            title=dispatch.title,
+            extra=extra,
+        )
+
+    items = _list_dispatch_items(paths.dispatch_dir)
+    dest = paths.dispatch_history_dir / f"{next_seq:04d}"
+    try:
+        dest.mkdir(parents=True, exist_ok=False)
+    except OSError as exc:
+        return None, [f"Failed to create dispatch history dir: {exc}"]
+
+    archived: list[Path] = []
+    try:
+        # Archive the dispatch file.
+        msg_dest = dest / "DISPATCH.md"
+        _copy_item(paths.dispatch_path, msg_dest)
+        archived.append(msg_dest)
+
+        # Archive all attachments.
+        for item in items:
+            item_dest = dest / item.name
+            _copy_item(item, item_dest)
+            archived.append(item_dest)
+
+    except OSError as exc:
+        return None, [f"Failed to archive dispatch: {exc}"]
+
+    # Cleanup (best-effort).
+    try:
+        paths.dispatch_path.unlink()
+    except OSError:
+        pass
+    _delete_dispatch_items(items)
+
+    return (
+        DispatchRecord(
+            seq=next_seq,
+            dispatch=dispatch,
+            archived_dir=dest,
+            archived_files=tuple(archived),
+        ),
+        [],
+    )

codex_autorunner/tickets/replies.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import re
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from .frontmatter import parse_markdown_frontmatter
+
+
+@dataclass(frozen=True)
+class ReplyPaths:
+    run_dir: Path
+    reply_dir: Path
+    reply_history_dir: Path
+    user_reply_path: Path
+
+
+@dataclass(frozen=True)
+class UserReply:
+    body: str
+    title: Optional[str] = None
+    extra: dict = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ReplyDispatch:
+    seq: int
+    reply: UserReply
+    archived_dir: Path
+    archived_files: tuple[Path, ...]
+
+
+def resolve_reply_paths(
+    *, workspace_root: Path, runs_dir: Path, run_id: str
+) -> ReplyPaths:
+    run_dir = workspace_root / runs_dir / run_id
+    reply_dir = run_dir / "reply"
+    reply_history_dir = run_dir / "reply_history"
+    user_reply_path = run_dir / "USER_REPLY.md"
+    return ReplyPaths(
+        run_dir=run_dir,
+        reply_dir=reply_dir,
+        reply_history_dir=reply_history_dir,
+        user_reply_path=user_reply_path,
+    )
+
+
+def ensure_reply_dirs(paths: ReplyPaths) -> None:
+    paths.reply_dir.mkdir(parents=True, exist_ok=True)
+    paths.reply_history_dir.mkdir(parents=True, exist_ok=True)
+
+
+def parse_user_reply(path: Path) -> tuple[Optional[UserReply], list[str]]:
+    """Parse a USER_REPLY.md file.
+
+    USER_REPLY.md is intentionally permissive:
+    - frontmatter is optional
+    - we accept any YAML keys (stored in `extra`)
+    """
+
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        return None, [f"Failed to read USER_REPLY.md: {exc}"]
+
+    data, body = parse_markdown_frontmatter(raw)
+    title = data.get("title")
+    title_str = title.strip() if isinstance(title, str) and title.strip() else None
+    extra = dict(data)
+    extra.pop("title", None)
+
+    # Keep the body as-is, but normalize leading whitespace so it mirrors DISPATCH.md.
+    return UserReply(body=body.lstrip("\n"), title=title_str, extra=extra), []
+
+
+def _copy_item(src: Path, dst: Path) -> None:
+    if src.is_dir():
+        shutil.copytree(src, dst)
+    else:
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src, dst)
+
+
+def _list_reply_items(reply_dir: Path) -> list[Path]:
+    if not reply_dir.exists() or not reply_dir.is_dir():
+        return []
+    items: list[Path] = []
+    for child in sorted(reply_dir.iterdir(), key=lambda p: p.name):
+        if child.name.startswith("."):
+            continue
+        items.append(child)
+    return items
+
+
+def _delete_items(items: list[Path]) -> None:
+    for item in items:
+        try:
+            if item.is_dir():
+                shutil.rmtree(item)
+            else:
+                item.unlink()
+        except OSError:
+            continue
+
+
+_SEQ_RE = re.compile(r"^[0-9]{4}$")
+
+
+def next_reply_seq(reply_history_dir: Path) -> int:
+    """Return the next sequence number for reply_history."""
+
+    if not reply_history_dir.exists() or not reply_history_dir.is_dir():
+        return 1
+    existing: list[int] = []
+    for child in reply_history_dir.iterdir():
+        try:
+            if not child.is_dir():
+                continue
+            if not _SEQ_RE.fullmatch(child.name):
+                continue
+            existing.append(int(child.name))
+        except OSError:
+            continue
+    return (max(existing) + 1) if existing else 1
+
+
+def dispatch_reply(
+    paths: ReplyPaths, *, next_seq: int
+) -> tuple[Optional[ReplyDispatch], list[str]]:
+    """Archive USER_REPLY.md + reply/* into reply_history/<seq>/.
+
+    Returns (dispatch, errors). When USER_REPLY.md does not exist, returns (None, []).
+    """
+
+    if not paths.user_reply_path.exists():
+        return None, []
+
+    reply, errors = parse_user_reply(paths.user_reply_path)
+    if errors or reply is None:
+        return None, errors
+
+    items = _list_reply_items(paths.reply_dir)
+    dest = paths.reply_history_dir / f"{next_seq:04d}"
+    try:
+        dest.mkdir(parents=True, exist_ok=False)
+    except OSError as exc:
+        return None, [f"Failed to create reply history dir: {exc}"]
+
+    archived: list[Path] = []
+    try:
+        msg_dest = dest / "USER_REPLY.md"
+        _copy_item(paths.user_reply_path, msg_dest)
+        archived.append(msg_dest)
+
+        for item in items:
+            item_dest = dest / item.name
+            _copy_item(item, item_dest)
+            archived.append(item_dest)
+    except OSError as exc:
+        return None, [f"Failed to archive reply: {exc}"]
+
+    # Cleanup (best-effort).
+    try:
+        paths.user_reply_path.unlink()
+    except OSError:
+        pass
+    _delete_items(items)
+
+    return (
+        ReplyDispatch(
+            seq=next_seq,
+            reply=reply,
+            archived_dir=dest,
+            archived_files=tuple(archived),
+        ),
+        [],
+    )