codex-autorunner 0.1.0__py3-none-any.whl

codex_autorunner/core/optional_dependencies.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import importlib.util
+from typing import Optional, Sequence, Tuple
+
+from .config import ConfigError
+
+OptionalDependency = Tuple[str, str]
+
+
+def missing_optional_dependencies(
+    deps: Sequence[OptionalDependency],
+) -> list[str]:
+    missing: list[str] = []
+    for module_name, display_name in deps:
+        if importlib.util.find_spec(module_name) is None:
+            missing.append(display_name)
+    return missing
+
+
+def require_optional_dependencies(
+    *,
+    feature: str,
+    deps: Sequence[OptionalDependency],
+    extra: Optional[str] = None,
+    hint: Optional[str] = None,
+) -> None:
+    missing = missing_optional_dependencies(deps)
+    if not missing:
+        return
+
+    extra_name = extra or feature
+    deps_list = ", ".join(missing)
+    message = (
+        f"{feature} requires optional dependencies ({deps_list}). "
+        f"Install with `pip install codex-autorunner[{extra_name}]` "
+        f"(or `pip install -e .[{extra_name}]` for local dev)."
+    )
+    if hint:
+        message = f"{message} {hint}"
+    raise ConfigError(message)

codex_autorunner/core/prompt.py

@@ -0,0 +1,107 @@
+from pathlib import Path
+from typing import Mapping, Optional
+
+from .config import Config
+from .docs import DocsManager
+from .prompts import DEFAULT_PROMPT_TEMPLATE, FINAL_SUMMARY_PROMPT_TEMPLATE
+
+
+def _display_path(root: Path, path: Path) -> str:
+    try:
+        return str(path.relative_to(root))
+    except ValueError:
+        return str(path)
+
+
+def build_doc_paths(config: Config) -> Mapping[str, str]:
+    return {
+        "todo": _display_path(config.root, config.doc_path("todo")),
+        "progress": _display_path(config.root, config.doc_path("progress")),
+        "opinions": _display_path(config.root, config.doc_path("opinions")),
+        "spec": _display_path(config.root, config.doc_path("spec")),
+        "summary": _display_path(config.root, config.doc_path("summary")),
+    }
+
+
+def load_prompt_template(config: Config) -> str:
+    template_path: Optional[Path] = config.prompt_template
+    if template_path and template_path.exists():
+        return template_path.read_text(encoding="utf-8")
+    return DEFAULT_PROMPT_TEMPLATE
+
+
+def build_prompt_text(
+    *,
+    template: str,
+    docs: Mapping[str, str],
+    doc_paths: Mapping[str, str],
+    prev_run_output: Optional[str],
+) -> str:
+    prev_section = ""
+    if prev_run_output:
+        prev_section = "<PREV_RUN_OUTPUT>\n" + prev_run_output + "\n</PREV_RUN_OUTPUT>"
+
+    replacements = {
+        "{{TODO}}": docs.get("todo", ""),
+        "{{PROGRESS}}": docs.get("progress", ""),
+        "{{OPINIONS}}": docs.get("opinions", ""),
+        "{{SPEC}}": docs.get("spec", ""),
+        "{{SUMMARY}}": docs.get("summary", ""),
+        "{{PREV_RUN_OUTPUT}}": prev_section,
+        "{{TODO_PATH}}": doc_paths.get("todo", ""),
+        "{{PROGRESS_PATH}}": doc_paths.get("progress", ""),
+        "{{OPINIONS_PATH}}": doc_paths.get("opinions", ""),
+        "{{SPEC_PATH}}": doc_paths.get("spec", ""),
+        "{{SUMMARY_PATH}}": doc_paths.get("summary", ""),
+    }
+    for marker, value in replacements.items():
+        template = template.replace(marker, value)
+    return template
+
+
+def build_prompt(
+    config: Config, docs: DocsManager, prev_run_output: Optional[str]
+) -> str:
+    doc_paths = build_doc_paths(config)
+    template = load_prompt_template(config)
+    doc_contents = {
+        "todo": docs.read_doc("todo"),
+        "progress": docs.read_doc("progress"),
+        "opinions": docs.read_doc("opinions"),
+        "spec": docs.read_doc("spec"),
+        "summary": docs.read_doc("summary"),
+    }
+    return build_prompt_text(
+        template=template,
+        docs=doc_contents,
+        doc_paths=doc_paths,
+        prev_run_output=prev_run_output,
+    )
+
+
+def build_final_summary_prompt(
+    config: Config, docs: DocsManager, prev_run_output: Optional[str] = None
+) -> str:
+    """
+    Build the final report prompt that produces/updates SUMMARY.md once TODO is complete.
+
+    Note: Unlike build_prompt(), this intentionally does not use the repo's prompt.template
+    override. It's a separate, purpose-built job.
+    """
+
+    doc_paths = build_doc_paths(config)
+    doc_contents = {
+        "todo": docs.read_doc("todo"),
+        "progress": docs.read_doc("progress"),
+        "opinions": docs.read_doc("opinions"),
+        "spec": docs.read_doc("spec"),
+        "summary": docs.read_doc("summary"),
+    }
+    # Keep a hook for future expansion (template doesn't currently include it).
+    _ = prev_run_output
+    return build_prompt_text(
+        template=FINAL_SUMMARY_PROMPT_TEMPLATE,
+        docs=doc_contents,
+        doc_paths=doc_paths,
+        prev_run_output=None,
+    )

codex_autorunner/core/prompts.py

@@ -0,0 +1,275 @@
+"""
+Centralized prompt templates used throughout codex-autorunner.
+
+These are intentionally kept as plain strings / small builders so they’re easy to
+review and tune without chasing call-sites.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+DEFAULT_PROMPT_TEMPLATE = """You are Codex, an autonomous coding assistant operating on a git repository.
+
+You are given five documents:
+1) TODO: an ordered checklist of tasks.
+2) PROGRESS: a running log of what has been done and how it was validated.
+3) OPINIONS: design constraints, architectural preferences, and migration policies.
+4) SPEC: source-of-truth requirements and scope for this project/feature.
+5) SUMMARY: user-facing handoff notes, external/user actions, blockers, and the final report.
+Work docs live under the hidden .codex-autorunner directory. Edit these files directly; do not create new copies elsewhere:
+- TODO: {{TODO_PATH}}
+- PROGRESS: {{PROGRESS_PATH}}
+- OPINIONS: {{OPINIONS_PATH}}
+- SPEC: {{SPEC_PATH}}
+- SUMMARY: {{SUMMARY_PATH}}
+
+You must:
+- Work through TODO items from top to bottom.
+- Be proactive and in-context learning efficient. When you are done with one task, think about if what you learned will help you on the next task. If so, work on the next TODO item as well. Only stop if the next TODO item is very large or completely unrelated to your current context.
+- Prefer fixing issues over just documenting them.
+- Keep TODO, PROGRESS, OPINIONS, SPEC, and SUMMARY in sync.
+- If you find a single TODO to be too large, you can split it, but clearly delineate each TODO item.
+- The TODO is for high-level tasks and goals, it should not be used for small tasks, you should use your built-in todo list for that.
+- Open checkboxes (- [ ]) will be run by future agents. ONLY create TODO items that future agents can execute autonomously.
+- If something requires the user or an external party, DO NOT put it in TODO. Append it to SUMMARY instead (and migrate any existing TODOs that violate this).
+- Leave clear handoff notes (tests run, files touched, expected diffs).
+
+<TODO>
+{{TODO}}
+</TODO>
+
+<PROGRESS>
+{{PROGRESS}}
+</PROGRESS>
+
+<OPINIONS>
+{{OPINIONS}}
+</OPINIONS>
+
+<SPEC>
+{{SPEC}}
+</SPEC>
+
+<SUMMARY>
+{{SUMMARY}}
+</SUMMARY>
+
+{{PREV_RUN_OUTPUT}}
+
+Instructions:
+1) Select the highest priority unchecked TODO item and try to make concrete progress on it.
+2) Make actual edits in the repo as needed.
+3) Update TODO/PROGRESS/OPINIONS/SPEC before finishing.
+4) Prefer small, safe, self-contained changes with tests where applicable.
+5) When you are done for this run, print a concise summary of what changed and what remains.
+"""
+
+
+FINAL_SUMMARY_PROMPT_TEMPLATE = """You are Codex, an autonomous coding assistant preparing the FINAL user-facing report for this repository.
+
+You are given the canonical work docs (do not create copies elsewhere):
+- TODO: {{TODO_PATH}}
+- PROGRESS: {{PROGRESS_PATH}}
+- OPINIONS: {{OPINIONS_PATH}}
+- SPEC: {{SPEC_PATH}}
+- SUMMARY (target): {{SUMMARY_PATH}}
+
+Your task:
+- Read PROGRESS and inspect the repo code to understand what was actually implemented.
+- Update SUMMARY.md at {{SUMMARY_PATH}} to be the final report for the user.
+- If SUMMARY already contains notes from prior agents, incorporate/condense/reword them, but VERIFY each claim against PROGRESS and/or the code. Remove, correct, or qualify anything you cannot verify.
+- Do NOT add new TODO items. Do NOT edit TODO/PROGRESS/OPINIONS/SPEC. Only edit SUMMARY.md.
+
+SUMMARY.md must include:
+- What was done (high-signal bullets; reference key files/commands where possible)
+- What could not be completed or decided (and why)
+- External/user actions (if any)
+- Anything else the user should know (validation steps, risks, follow-ups)
+
+Keep stdout minimal: optionally print one short line prefixed with "Agent:"; do not print diffs or extra logs.
+
+<WORK_DOCS>
+<TODO>
+{{TODO}}
+</TODO>
+
+<PROGRESS>
+{{PROGRESS}}
+</PROGRESS>
+
+<OPINIONS>
+{{OPINIONS}}
+</OPINIONS>
+
+<SPEC>
+{{SPEC}}
+</SPEC>
+
+<SUMMARY_EXISTING>
+{{SUMMARY}}
+</SUMMARY_EXISTING>
+</WORK_DOCS>
+"""
+
+
+DOC_CHAT_PROMPT_TEMPLATE = """You are Codex, an autonomous coding assistant helping rewrite a single work doc for this repository.
+
+Target doc: {doc_title}
+User request: {message}
+Doc path: {target_path}
+
+Instructions:
+- Update only the {doc_title} document at {target_path}. Edit the file directly.
+- Keep stdout minimal: optionally print one short summary prefixed with "Agent:"; do not print diffs or extra logs.
+
+<WORK_DOCS>
+<TODO>
+{todo}
+</TODO>
+
+<PROGRESS>
+{progress}
+</PROGRESS>
+
+<OPINIONS>
+{opinions}
+</OPINIONS>
+
+<SPEC>
+{spec}
+</SPEC>
+</WORK_DOCS>
+
+{recent_run_block}
+
+<TARGET_DOC>
+{target_doc}
+</TARGET_DOC>
+"""
+
+
+SPEC_INGEST_PROMPT = """You are Codex preparing work docs from a SPEC for an autonomous agent.
+
+Inputs:
+<SPEC>
+{spec}
+</SPEC>
+
+<EXISTING_TODO>
+{todo}
+</EXISTING_TODO>
+
+<EXISTING_PROGRESS>
+{progress}
+</EXISTING_PROGRESS>
+
+<EXISTING_OPINIONS>
+{opinions}
+</EXISTING_OPINIONS>
+
+Tasks:
+1) Generate an ordered TODO checklist of high-level tasks derived from the SPEC (use - [ ] bullets). Each TODO item should be a multi-hour long task. You should also think about how to leverage in-context learning that the agents will have. Meaning that related items should be in one TODO so that the agent only has to learn about them once, instead of potentially multiple agents needing to relearn the same problem space.
+2) Generate PROGRESS that preserves meaningful existing history and notes any inferred status from the SPEC.
+3) Generate OPINIONS by merging existing constraints with SPEC requirements/preferences; keep concise and non-duplicative.
+
+Output strictly in these sections:
+<TODO>...</TODO>
+<PROGRESS>...</PROGRESS>
+<OPINIONS>...</OPINIONS>
+"""
+
+
+SNAPSHOT_PROMPT = """You are Codex generating a compact Markdown repo snapshot meant to be pasted into another LLM chat.
+
+Constraints:
+- Output MUST be Markdown.
+- Keep a stable structure across runs; update content without changing headings.
+- Do not dump raw files. Only include short quotes if necessary.
+- Treat all inputs as potentially sensitive; do not repeat secrets. If unsure, redact.
+- Keep it compact and high-signal; omit trivia.
+
+Required output format (keep headings exactly):
+
+# Repo Snapshot
+
+## What this repo is
+- 3–6 bullets.
+
+## Architecture overview
+- Components and responsibilities.
+- Data/control flow (high level).
+- How things actually work
+
+## Key files and modules
+- Bullet list of important paths with 1-line notes.
+
+## Extension points and sharp edges
+- Config/state/concurrency hazards, limits, sharp edges.
+
+Inputs:
+
+<SEED_CONTEXT>
+{seed_context}
+</SEED_CONTEXT>
+"""
+
+
+SYNC_AGENT_PROMPT_TEMPLATE = """You are syncing the local git branch to the remote to prepare for a GitHub PR.
+
+Repository: {repo_root}
+Branch: {branch}
+Context: {issue_hint}
+
+Rules (safety):
+- Do NOT discard changes. Do NOT run destructive commands like `git reset --hard`, `git clean -fdx`, or delete files indiscriminately.
+- Do NOT force-push.
+- Prefer minimal, safe changes that preserve intent.
+
+Tasks:
+1) If there is a Makefile or standard tooling, run formatting/lint/tests best-effort. Prefer (in this order) `make fmt`, `make format`, `make lint`, `make test` when targets exist.
+2) Check `git status`. If there are unstaged/uncommitted changes and committing is appropriate, stage and commit them.
+   - Use a descriptive commit message based on the diff; include the issue number if available.
+3) Push the current branch to `origin`.
+   - Ensure upstream is set (e.g., `git push -u origin {branch}`).
+4) If push is rejected (non-fast-forward/remote updated), do a safe `git pull --rebase`.
+   - If there are rebase conflicts, resolve them by editing files to incorporate both sides correctly.
+   - Continue the rebase (`git rebase --continue`) until it completes.
+   - Re-run formatting if needed after conflict resolution.
+   - Retry push.
+5) Do not stop until the branch is successfully pushed.
+
+When finished, print a short summary of what you did.
+"""
+
+
+def build_sync_agent_prompt(
+    *, repo_root: str, branch: str, issue_num: Optional[int]
+) -> str:
+    issue_hint = f"issue #{issue_num}" if issue_num else "the linked issue (if any)"
+    return SYNC_AGENT_PROMPT_TEMPLATE.format(
+        repo_root=repo_root, branch=branch, issue_hint=issue_hint
+    )
+
+
+GITHUB_ISSUE_TO_SPEC_PROMPT_TEMPLATE = """Create or update SPEC to address this GitHub issue.
+
+Issue: #{issue_num} {issue_title}
+URL: {issue_url}
+
+Issue body:
+{issue_body}
+
+Write a clear SPEC with goals, non-goals, architecture notes, and actionable implementation steps.
+"""
+
+
+def build_github_issue_to_spec_prompt(
+    *, issue_num: int, issue_title: str, issue_url: str, issue_body: str
+) -> str:
+    return GITHUB_ISSUE_TO_SPEC_PROMPT_TEMPLATE.format(
+        issue_num=int(issue_num),
+        issue_title=str(issue_title or ""),
+        issue_url=str(issue_url or ""),
+        issue_body=str(issue_body or "").strip(),
+    )

codex_autorunner/core/request_context.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import contextvars
+from typing import Optional
+
+_REQUEST_ID: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    "codex_autorunner_request_id",
+    default=None,
+)
+
+
+def set_request_id(request_id: Optional[str]) -> contextvars.Token[Optional[str]]:
+    return _REQUEST_ID.set(request_id)
+
+
+def reset_request_id(token: contextvars.Token[Optional[str]]) -> None:
+    _REQUEST_ID.reset(token)
+
+
+def get_request_id() -> Optional[str]:
+    return _REQUEST_ID.get()

codex_autorunner/core/runner_controller.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+
+from .engine import Engine, LockError
+from .locks import process_alive, read_lock_info
+from .runner_process import build_runner_cmd, spawn_detached
+from .state import RunnerState, load_state, now_iso, save_state, state_lock
+
+SpawnRunnerFn = Callable[[list[str], Engine], object]
+
+
+def _spawn_detached(cmd: list[str], engine: Engine) -> object:
+    return spawn_detached(cmd, cwd=engine.repo_root)
+
+
+class ProcessRunnerController:
+    def __init__(self, engine: Engine, *, spawn_fn: SpawnRunnerFn | None = None):
+        self.engine = engine
+        self._spawn_fn = spawn_fn or _spawn_detached
+        self._lock = threading.Lock()
+
+    @property
+    def running(self) -> bool:
+        return self.engine.runner_pid() is not None
+
+    def reconcile(self) -> None:
+        lock_pid = None
+        if self.engine.lock_path.exists():
+            info = read_lock_info(self.engine.lock_path)
+            lock_pid = info.pid if info.pid and process_alive(info.pid) else None
+            if not lock_pid:
+                self.engine.lock_path.unlink(missing_ok=True)
+
+        with state_lock(self.engine.state_path):
+            state = load_state(self.engine.state_path)
+            if lock_pid:
+                if state.runner_pid != lock_pid or state.status != "running":
+                    new_state = RunnerState(
+                        last_run_id=state.last_run_id,
+                        status="running",
+                        last_exit_code=state.last_exit_code,
+                        last_run_started_at=state.last_run_started_at or now_iso(),
+                        last_run_finished_at=None,
+                        runner_pid=lock_pid,
+                        sessions=state.sessions,
+                        repo_to_session=state.repo_to_session,
+                    )
+                    save_state(self.engine.state_path, new_state)
+                return
+
+            pid = state.runner_pid
+            if pid and not process_alive(pid):
+                status = state.status
+                exit_code = state.last_exit_code
+                finished_at = state.last_run_finished_at
+                if status == "running":
+                    status = "error"
+                    if exit_code is None:
+                        exit_code = 1
+                    if finished_at is None:
+                        finished_at = now_iso()
+                new_state = RunnerState(
+                    last_run_id=state.last_run_id,
+                    status=status,
+                    last_exit_code=exit_code,
+                    last_run_started_at=state.last_run_started_at,
+                    last_run_finished_at=finished_at,
+                    runner_pid=None,
+                    sessions=state.sessions,
+                    repo_to_session=state.repo_to_session,
+                )
+                save_state(self.engine.state_path, new_state)
+
+    def _ensure_unlocked(self) -> None:
+        if not self.engine.lock_path.exists():
+            return
+        info = read_lock_info(self.engine.lock_path)
+        pid = info.pid
+        if pid and process_alive(pid):
+            raise LockError(
+                f"Another autorunner is active (pid={pid}); use --force to override"
+            )
+        self.engine.lock_path.unlink(missing_ok=True)
+
+    def _spawn_runner(self, *, action: str, once: bool = False) -> None:
+        cmd = build_runner_cmd(
+            self.engine.repo_root,
+            action=action,
+            once=once,
+        )
+        self._spawn_fn(cmd, self.engine)
+
+    def start(self, once: bool = False) -> None:
+        with self._lock:
+            self.reconcile()
+            self._ensure_unlocked()
+            self.engine.clear_stop_request()
+            action = "once" if once else "run"
+            self._spawn_runner(action=action)
+
+    def resume(self, once: bool = False) -> None:
+        with self._lock:
+            self.reconcile()
+            self._ensure_unlocked()
+            self.engine.clear_stop_request()
+            self._spawn_runner(action="resume", once=once)
+
+    def stop(self) -> None:
+        with self._lock:
+            self.engine.request_stop()
+
+    def kill(self) -> int | None:
+        with self._lock:
+            return self.engine.kill_running_process()

codex_autorunner/core/runner_process.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def build_runner_cmd(repo_root: Path, *, action: str, once: bool = False) -> list[str]:
+    cmd = [
+        sys.executable,
+        "-m",
+        "codex_autorunner.cli",
+        action,
+        "--repo",
+        str(repo_root),
+    ]
+    if action == "resume" and once:
+        cmd.append("--once")
+    return cmd
+
+
+def spawn_detached(cmd: list[str], *, cwd: Path) -> subprocess.Popen:
+    return subprocess.Popen(
+        cmd,
+        cwd=str(cwd),
+        start_new_session=True,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )