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

codex_autorunner/codex_cli.py

@@ -1,84 +1,20 @@
-import subprocess
-from functools import lru_cache
-from typing import Iterable, Optional
-
-SUBCOMMAND_HINTS = ("exec", "resume")
-
-
-def extract_flag_value(args: Iterable[str], flag: str) -> Optional[str]:
-    if not args:
-        return None
-    for arg in args:
-        if not isinstance(arg, str):
-            continue
-        if arg.startswith(f"{flag}="):
-            return arg.split("=", 1)[1] or None
-    args_list = [str(a) for a in args]
-    for idx, arg in enumerate(args_list):
-        if arg == flag and idx + 1 < len(args_list):
-            return args_list[idx + 1]
-    return None
-
-
-def inject_flag(
-    args: Iterable[str],
-    flag: str,
-    value: Optional[str],
-    *,
-    subcommands: Iterable[str] = SUBCOMMAND_HINTS,
-) -> list[str]:
-    if not value:
-        return [str(a) for a in args]
-    args_list = [str(a) for a in args]
-    if extract_flag_value(args_list, flag):
-        return args_list
-    insert_at = None
-    for cmd in subcommands:
-        try:
-            insert_at = args_list.index(cmd)
-            break
-        except ValueError:
-            continue
-    if insert_at is None:
-        # `args` is sometimes a full argv that includes the binary at index 0,
-        # e.g. ["codex", "--yolo", ...]. In that case, never prepend flags before
-        # the binary or we'll turn argv[0] into e.g. "--model" and crash at spawn.
-        if args_list and not args_list[0].startswith("-"):
-            return [args_list[0], flag, value] + args_list[1:]
-        return [flag, value] + args_list
-    return args_list[:insert_at] + [flag, value] + args_list[insert_at:]
-
-
-def apply_codex_options(
-    args: Iterable[str],
-    *,
-    model: Optional[str] = None,
-    reasoning: Optional[str] = None,
-    supports_reasoning: Optional[bool] = None,
-) -> list[str]:
-    with_model = inject_flag(args, "--model", model)
-    if reasoning and supports_reasoning is False:
-        return with_model
-    return inject_flag(with_model, "--reasoning", reasoning)
-
-
-def _read_help_text(binary: str) -> str:
-    try:
-        result = subprocess.run(
-            [binary, "--help"],
-            capture_output=True,
-            text=True,
-            check=False,
-        )
-    except FileNotFoundError:
-        return ""
-    return "\n".join(filter(None, [result.stdout, result.stderr]))
-
-
-@lru_cache(maxsize=8)
-def supports_flag(binary: str, flag: str) -> bool:
-    return flag in _read_help_text(binary)
-
-
-def supports_reasoning(binary: str) -> bool:
-    return supports_flag(binary, "--reasoning")
+"""Backward-compatible Codex CLI helpers.
+
+Delegates to core.utils to avoid duplicated logic.
+"""
+
+from .core.utils import (  # noqa: F401
+    apply_codex_options,
+    extract_flag_value,
+    inject_flag,
+    supports_flag,
+    supports_reasoning,
+)
+
+__all__ = [
+    "apply_codex_options",
+    "extract_flag_value",
+    "inject_flag",
+    "supports_flag",
+    "supports_reasoning",
+]

codex_autorunner/core/__init__.py

@@ -1 +1,21 @@
 """Core runtime primitives."""
+
+from .archive import ArchiveResult, archive_worktree_snapshot
+from .context_awareness import CAR_AWARENESS_BLOCK, format_file_role_addendum
+from .lifecycle_events import (
+    LifecycleEvent,
+    LifecycleEventEmitter,
+    LifecycleEventStore,
+    LifecycleEventType,
+)
+
+__all__ = [
+    "ArchiveResult",
+    "archive_worktree_snapshot",
+    "CAR_AWARENESS_BLOCK",
+    "format_file_role_addendum",
+    "LifecycleEvent",
+    "LifecycleEventEmitter",
+    "LifecycleEventStore",
+    "LifecycleEventType",
+]

codex_autorunner/core/about_car.py

@@ -13,9 +13,19 @@ from .config import (
 
 ABOUT_CAR_BASENAME = "ABOUT_CAR.md"
 ABOUT_CAR_REL_PATH = Path(".codex-autorunner") / ABOUT_CAR_BASENAME
+TICKET_FLOW_QUICKSTART_BASENAME = "TICKET_FLOW_QUICKSTART.md"
+TICKET_FLOW_QUICKSTART_REL_PATH = (
+    Path(".codex-autorunner") / TICKET_FLOW_QUICKSTART_BASENAME
+)
+TICKETS_AGENTS_BASENAME = "AGENTS.md"
+TICKETS_AGENTS_REL_PATH = (
+    Path(".codex-autorunner") / "tickets" / TICKETS_AGENTS_BASENAME
+)
 
 # If this marker is present, codex-autorunner may safely refresh the file content.
 ABOUT_CAR_GENERATED_MARKER = "<!-- CAR:AUTOGENERATED -->"
+TICKET_FLOW_QUICKSTART_GENERATED_MARKER = "<!-- CAR:TICKET_FLOW_QUICKSTART -->"
+TICKETS_AGENTS_GENERATED_MARKER = "<!-- CAR:TICKETS_AGENTS -->"
 
 CAR_CONTEXT_KEYWORDS = (
     "car",
@@ -76,7 +86,11 @@ def build_about_car_markdown(
         "You are running inside **Codex Autorunner (CAR)**.\n\n"
         "CAR uses a ticket-first workflow.\n\n"
         "## Required for operation\n"
-        "- Tickets live under `.codex-autorunner/tickets/`.\n\n"
+        "- Tickets live under `.codex-autorunner/tickets/` (per-repo/worktree).\n"
+        "- If the user provides ticket files, place them in the repo's `.codex-autorunner/tickets/` folder.\n"
+        "- Lint ticket frontmatter after edits (runs against all tickets): `python3 .codex-autorunner/bin/lint_tickets.py`.\n\n"
+        "## Ticket flow quickstart\n"
+        f"- Read `{_display_path(repo_root, TICKET_FLOW_QUICKSTART_REL_PATH)}` for CLI entrypoints + gotchas.\n\n"
         "## Optional workspace docs\n"
         "- **Active context**: "
         f"`{active_context_disp}`\n"
@@ -91,6 +105,16 @@ def build_about_car_markdown(
         "- **Dispatch**: An update or message from the agent.\n"
         "- **Handoff**: Passing control from agent to user (or vice versa).\n"
         "- **Inbox**: Where the agent receives files/messages.\n\n"
+        "## Ticket helpers\n"
+        "- Use `.codex-autorunner/bin/ticket_tool.py` to list/create/insert/move tickets; it is portable and venv-free.\n"
+        '- Common workflows: insert gap before N (`python3 .codex-autorunner/bin/ticket_tool.py insert --before N`); move a block (`... move --start A --end B --to T`); create with auto-quoted frontmatter (`... create --title "Fix #123" --agent codex`).\n'
+        "- After any ticket edits, lint all tickets: `python3 .codex-autorunner/bin/lint_tickets.py`.\n\n"
+        "## Ticket templates (optional)\n"
+        "- CAR can fetch ticket templates from configured git repos (treat templates as code).\n"
+        "- Fetch (prints template to stdout): `car templates fetch <repo_id>:<path>[@<ref>]`\n"
+        "- Pin to a commit for determinism: `...@<commit_sha>`\n"
+        "- Trusted repos skip scanning. Untrusted repos are scanned (cached by blob SHA) before content is returned.\n"
+        "- If fetch or scan fails, pause and notify the user rather than guessing.\n\n"
         "## How CAR works (short)\n"
         "- The web UI provides ticket editing + unified file chat.\n"
         "- `car serve` starts the hub web UI. The **Terminal** tab launches the configured `codex` binary in a PTY.\n"
@@ -139,6 +163,54 @@ def ensure_about_car_file_for_repo(
     return path
 
 
+def build_ticket_flow_quickstart_markdown(*, repo_root: Path) -> str:
+    ticket_dir = ".codex-autorunner/tickets/"
+    return (
+        f"{TICKET_FLOW_QUICKSTART_GENERATED_MARKER}\n"
+        "# Ticket Flow Quickstart\n\n"
+        "## Start ticket flow via CLI\n"
+        "- Bootstrap the first run (creates TICKET-001 if needed):\n"
+        "  `car flow ticket_flow bootstrap --repo <path>`\n"
+        "  (alias: `car ticket-flow bootstrap --repo <path>`)\n"
+        "- Start/resume without seeding tickets:\n"
+        "  `car flow ticket_flow start --repo <path>`\n"
+        "- Check status:\n"
+        "  `car flow ticket_flow status --repo <path> [--run-id <uuid>]`\n"
+        "- Resume/stop:\n"
+        "  `car flow ticket_flow resume --repo <path> [--run-id <uuid>]`\n"
+        "  `car flow ticket_flow stop --repo <path> [--run-id <uuid>]`\n\n"
+        "## Where tickets live\n"
+        f"- Tickets are per-repo/worktree under `{ticket_dir}`.\n"
+        "- If the user provides ticket files, save them directly into that folder.\n\n"
+        "## Common gotchas\n"
+        "- Hub vs repo: ticket flows run per-repo; CLI commands need a repo path.\n"
+        "- `--repo` expects a filesystem path, not a hub repo_id.\n"
+        "- Each worktree has its own `.codex-autorunner/` directory.\n"
+        "- If this repo/worktree lives under a hub, it must be registered in the hub manifest to show up in the hub UI. Run: `car hub scan` (or create it via `car hub worktree create`).\n"
+    )
+
+
+def build_tickets_agents_markdown(*, repo_root: Path) -> str:
+    quickstart_path = _display_path(repo_root, TICKET_FLOW_QUICKSTART_REL_PATH)
+    return (
+        f"{TICKETS_AGENTS_GENERATED_MARKER}\n"
+        "# Tickets — AGENTS\n\n"
+        "This folder is the authoritative ticket queue for this repo/worktree.\n\n"
+        "## Ticket files\n"
+        "- Store work items as `TICKET-###*.md` (ordered by number).\n"
+        "- Keep frontmatter `done: true|false` in sync with completion.\n"
+        "- After edits, lint tickets: `python3 .codex-autorunner/bin/lint_tickets.py`.\n\n"
+        "## Ticket CLI (portable)\n"
+        "- List: `python3 .codex-autorunner/bin/ticket_tool.py list`\n"
+        '- Create: `python3 .codex-autorunner/bin/ticket_tool.py create --title "..." --agent codex`\n'
+        "- Insert gap: `python3 .codex-autorunner/bin/ticket_tool.py insert --before N`\n"
+        "- Move block: `python3 .codex-autorunner/bin/ticket_tool.py move --start A --end B --to T`\n"
+        "- Lint: `python3 .codex-autorunner/bin/ticket_tool.py lint`\n\n"
+        "## Ticket flow (runner)\n"
+        f"- See `{quickstart_path}` for `car flow ticket_flow ...` commands.\n"
+    )
+
+
 def ensure_about_car_file(config: Config, *, force: bool = False) -> Path:
     """Config-aware wrapper that uses configured doc paths."""
     repo_root = config.root
@@ -148,3 +220,49 @@ def ensure_about_car_file(config: Config, *, force: bool = False) -> Path:
         "spec": config.doc_path("spec"),
     }
     return ensure_about_car_file_for_repo(repo_root, doc_paths=docs, force=force)
+
+
+def ensure_ticket_flow_quickstart_file_for_repo(
+    repo_root: Path, *, force: bool = False
+) -> Path:
+    path = repo_root / TICKET_FLOW_QUICKSTART_REL_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    content = build_ticket_flow_quickstart_markdown(repo_root=repo_root)
+    if content and not content.endswith("\n"):
+        content += "\n"
+
+    if path.exists() and not force:
+        try:
+            existing = path.read_text(encoding="utf-8")
+        except OSError:
+            existing = ""
+        if TICKET_FLOW_QUICKSTART_GENERATED_MARKER not in existing:
+            return path
+        if existing == content:
+            return path
+
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def ensure_tickets_agents_file_for_repo(
+    repo_root: Path, *, force: bool = False
+) -> Path:
+    path = repo_root / TICKETS_AGENTS_REL_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    content = build_tickets_agents_markdown(repo_root=repo_root)
+    if content and not content.endswith("\n"):
+        content += "\n"
+
+    if path.exists() and not force:
+        try:
+            existing = path.read_text(encoding="utf-8")
+        except OSError:
+            existing = ""
+        if TICKETS_AGENTS_GENERATED_MARKER not in existing:
+            return path
+        if existing == content:
+            return path
+
+    path.write_text(content, encoding="utf-8")
+    return path

codex_autorunner/core/app_server_ids.py

@@ -0,0 +1,59 @@
+from typing import Any, Optional
+
+
+def extract_turn_id(payload: Any) -> Optional[str]:
+    if not isinstance(payload, dict):
+        return None
+    for key in ("turnId", "turn_id", "id"):
+        value = payload.get(key)
+        if isinstance(value, str):
+            return value
+    turn = payload.get("turn")
+    if isinstance(turn, dict):
+        for key in ("id", "turnId", "turn_id"):
+            value = turn.get(key)
+            if isinstance(value, str):
+                return value
+    return None
+
+
+def _extract_thread_id_from_container(payload: Any) -> Optional[str]:
+    if not isinstance(payload, dict):
+        return None
+    for key in ("threadId", "thread_id"):
+        value = payload.get(key)
+        if isinstance(value, str):
+            return value
+    thread = payload.get("thread")
+    if isinstance(thread, dict):
+        for key in ("id", "threadId", "thread_id"):
+            value = thread.get(key)
+            if isinstance(value, str):
+                return value
+    return None
+
+
+def extract_thread_id_for_turn(payload: Any) -> Optional[str]:
+    if not isinstance(payload, dict):
+        return None
+    for candidate in (payload, payload.get("turn"), payload.get("item")):
+        thread_id = _extract_thread_id_from_container(candidate)
+        if thread_id:
+            return thread_id
+    return None
+
+
+def extract_thread_id(payload: Any) -> Optional[str]:
+    if not isinstance(payload, dict):
+        return None
+    for key in ("threadId", "thread_id", "id"):
+        value = payload.get(key)
+        if isinstance(value, str):
+            return value
+    thread = payload.get("thread")
+    if isinstance(thread, dict):
+        for key in ("id", "threadId", "thread_id"):
+            value = thread.get(key)
+            if isinstance(value, str):
+                return value
+    return None

codex_autorunner/core/app_server_threads.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import logging
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
@@ -16,11 +17,17 @@ FILE_CHAT_KEY = "file_chat"
 FILE_CHAT_OPENCODE_KEY = "file_chat.opencode"
 FILE_CHAT_PREFIX = "file_chat."
 FILE_CHAT_OPENCODE_PREFIX = "file_chat.opencode."
+PMA_KEY = "pma"
+PMA_OPENCODE_KEY = "pma.opencode"
+
+LOGGER = logging.getLogger("codex_autorunner.app_server")
 
 # Static keys that can be reset/managed via the UI.
 FEATURE_KEYS = {
     FILE_CHAT_KEY,
     FILE_CHAT_OPENCODE_KEY,
+    PMA_KEY,
+    PMA_OPENCODE_KEY,
     "autorunner",
     "autorunner.opencode",
 }
@@ -89,6 +96,8 @@ class AppServerThreadRegistry:
             "file_chat_opencode": threads.get(FILE_CHAT_OPENCODE_KEY),
             "autorunner": threads.get("autorunner"),
             "autorunner_opencode": threads.get("autorunner.opencode"),
+            "pma": threads.get(PMA_KEY),
+            "pma_opencode": threads.get(PMA_OPENCODE_KEY),
         }
         notice = self.corruption_notice()
         if notice:
@@ -177,8 +186,14 @@ class AppServerThreadRegistry:
         try:
             atomic_write(self._notice_path(), json.dumps(notice, indent=2) + "\n")
         except Exception:
-            pass
+            LOGGER.warning(
+                "Failed to write app server thread corruption notice.",
+                exc_info=True,
+            )
         try:
             self._save_unlocked({})
         except Exception:
-            pass
+            LOGGER.warning(
+                "Failed to reset app server thread registry after corruption.",
+                exc_info=True,
+            )

codex_autorunner/core/app_server_utils.py

@@ -0,0 +1,165 @@
+import os
+from pathlib import Path
+from typing import Any, Optional, Sequence
+
+from .logging_utils import log_event
+from .utils import resolve_executable, subprocess_env
+
+
+def app_server_env(
+    command: Sequence[str],
+    cwd: Path,
+    *,
+    base_env: Optional[dict[str, str]] = None,
+) -> dict[str, str]:
+    extra_paths: list[str] = []
+    if command:
+        binary = command[0]
+        resolved = resolve_executable(binary, env=base_env)
+        candidate: Optional[Path] = Path(resolved) if resolved else None
+        if candidate is None:
+            candidate = Path(binary).expanduser()
+            if not candidate.is_absolute():
+                candidate = (cwd / candidate).resolve()
+        if candidate.exists():
+            extra_paths.append(str(candidate.parent))
+    return subprocess_env(extra_paths=extra_paths, base_env=base_env)
+
+
+def seed_codex_home(
+    codex_home: Path,
+    *,
+    logger: Any = None,
+    event_prefix: str = "app_server",
+) -> None:
+    logger = logger or __import__("logging").getLogger(__name__)
+    auth_path = codex_home / "auth.json"
+    source_root = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser()
+    if source_root.resolve() == codex_home.resolve():
+        return
+    source_auth = source_root / "auth.json"
+    if auth_path.exists():
+        if auth_path.is_symlink() and auth_path.resolve() == source_auth.resolve():
+            return
+        log_event(
+            logger,
+            __import__("logging").INFO,
+            f"{event_prefix}.codex_home.seed.skipped",
+            reason="auth_exists",
+            source=str(source_root),
+            target=str(codex_home),
+        )
+        return
+    if not source_root.exists():
+        log_event(
+            logger,
+            __import__("logging").WARNING,
+            f"{event_prefix}.codex_home.seed.skipped",
+            reason="source_missing",
+            source=str(source_root),
+            target=str(codex_home),
+        )
+        return
+    if not source_auth.exists():
+        log_event(
+            logger,
+            __import__("logging").WARNING,
+            f"{event_prefix}.codex_home.seed.skipped",
+            reason="auth_missing",
+            source=str(source_root),
+            target=str(codex_home),
+        )
+        return
+    try:
+        auth_path.symlink_to(source_auth)
+        log_event(
+            logger,
+            __import__("logging").INFO,
+            f"{event_prefix}.codex_home.seeded",
+            source=str(source_root),
+            target=str(codex_home),
+        )
+    except OSError as exc:
+        log_event(
+            logger,
+            __import__("logging").WARNING,
+            f"{event_prefix}.codex_home.seed.failed",
+            exc=exc,
+            source=str(source_root),
+            target=str(codex_home),
+        )
+
+
+def build_app_server_env(
+    command: Sequence[str],
+    workspace_root: Path,
+    state_dir: Path,
+    *,
+    logger: Any = None,
+    event_prefix: str = "app_server",
+    base_env: Optional[dict[str, str]] = None,
+) -> dict[str, str]:
+    env = app_server_env(command, workspace_root, base_env=base_env)
+    codex_home = state_dir / "codex_home"
+    codex_home.mkdir(parents=True, exist_ok=True)
+    seed_codex_home(codex_home, logger=logger, event_prefix=event_prefix)
+    env["CODEX_HOME"] = str(codex_home)
+    return env
+
+
+def _extract_turn_id(payload: Any) -> Optional[str]:
+    if not isinstance(payload, dict):
+        return None
+    for key in ("turnId", "turn_id", "id"):
+        value = payload.get(key)
+        if isinstance(value, str):
+            return value
+    turn = payload.get("turn")
+    if isinstance(turn, dict):
+        for key in ("id", "turnId", "turn_id"):
+            value = turn.get(key)
+            if isinstance(value, str):
+                return value
+    return None
+
+
+def _extract_thread_id_from_container(payload: Any) -> Optional[str]:
+    if not isinstance(payload, dict):
+        return None
+    for key in ("threadId", "thread_id"):
+        value = payload.get(key)
+        if isinstance(value, str):
+            return value
+    thread = payload.get("thread")
+    if isinstance(thread, dict):
+        for key in ("id", "threadId", "thread_id"):
+            value = thread.get(key)
+            if isinstance(value, str):
+                return value
+    return None
+
+
+def _extract_thread_id_for_turn(payload: Any) -> Optional[str]:
+    if not isinstance(payload, dict):
+        return None
+    for candidate in (payload, payload.get("turn"), payload.get("item")):
+        thread_id = _extract_thread_id_from_container(candidate)
+        if thread_id:
+            return thread_id
+    return None
+
+
+def _extract_thread_id(payload: Any) -> Optional[str]:
+    if not isinstance(payload, dict):
+        return None
+    for key in ("threadId", "thread_id", "id"):
+        value = payload.get(key)
+        if isinstance(value, str):
+            return value
+    thread = payload.get("thread")
+    if isinstance(thread, dict):
+        for key in ("id", "threadId", "thread_id"):
+            value = thread.get(key)
+            if isinstance(value, str):
+                return value
+    return None