codexapi 0.1.7__tar.gz → 0.1.9__tar.gz

{codexapi-0.1.7/src/codexapi.egg-info → codexapi-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.1.7
+Version: 0.1.9
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -81,6 +81,16 @@ Resume a session and print the thread id to stderr:
 codexapi --thread-id THREAD_ID --print-thread-id "Continue where we left off."
 ```
 
+Ralph loop mode repeats the same prompt until a completion promise or a max
+iteration cap is hit (0 means unlimited). Cancel by deleting
+`.codexapi/ralph-loop.local.md` or running `codexapi --ralph-cancel`.
+
+```bash
+codexapi --ralph "Fix the bug." --completion-promise DONE --max-iterations 5
+codexapi --ralph --ralph-fresh "Try again from scratch." --max-iterations 3
+codexapi --ralph-cancel --cwd /path/to/project
+```
+
 ## API
 
 ### `agent(prompt, cwd=None, yolo=False, flags=None) -> str`

{codexapi-0.1.7 → codexapi-0.1.9}/README.md

@@ -69,6 +69,16 @@ Resume a session and print the thread id to stderr:
 codexapi --thread-id THREAD_ID --print-thread-id "Continue where we left off."
 ```
 
+Ralph loop mode repeats the same prompt until a completion promise or a max
+iteration cap is hit (0 means unlimited). Cancel by deleting
+`.codexapi/ralph-loop.local.md` or running `codexapi --ralph-cancel`.
+
+```bash
+codexapi --ralph "Fix the bug." --completion-promise DONE --max-iterations 5
+codexapi --ralph --ralph-fresh "Try again from scratch." --max-iterations 3
+codexapi --ralph-cancel --cwd /path/to/project
+```
+
 ## API
 
 ### `agent(prompt, cwd=None, yolo=False, flags=None) -> str`

{codexapi-0.1.7 → codexapi-0.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codexapi"
-version = "0.1.7"
+version = "0.1.9"
 description = "Minimal Python API for running the Codex CLI."
 readme = "README.md"
 requires-python = ">=3.8"

{codexapi-0.1.7 → codexapi-0.1.9}/src/codexapi/__init__.py

@@ -12,4 +12,4 @@ __all__ = [
     "task",
     "task_result",
 ]
-__version__ = "0.1.7"
+__version__ = "0.1.8"

{codexapi-0.1.7 → codexapi-0.1.9}/src/codexapi/cli.py

@@ -12,6 +12,7 @@ from datetime import datetime
 from pathlib import Path
 
 from .agent import Agent, agent
+from .ralph import cancel_ralph_loop, run_ralph_loop
 from .task import TaskFailed, task
 
 _SESSION_ID_RE = re.compile(
@@ -36,6 +37,7 @@ _COLUMN_TITLES = {
     "tok": "TOK/S",
     "in": "IN",
     "out": "OUT",
+    "turn": "TURN",
     "model": "MODEL",
     "effort": "EFF",
     "perm": "PERM",
@@ -309,6 +311,24 @@ def _format_token_total(value):
     return str(value)
 
 
+def _format_duration(seconds):
+    if seconds is None:
+        return "-"
+    if seconds < 0:
+        return "-"
+    total = int(seconds)
+    days, rem = divmod(total, 86400)
+    hours, rem = divmod(rem, 3600)
+    minutes, secs = divmod(rem, 60)
+    if days:
+        return f"{days}d{hours:02d}h"
+    if hours:
+        return f"{hours}h{minutes:02d}m"
+    if minutes:
+        return f"{minutes}m{secs:02d}s"
+    return f"{secs}s"
+
+
 def _summarize_session(path, mtime):
     prompt = None
     prompt_fallback = None
@@ -569,6 +589,7 @@ def _layout_columns(width, id_width, show):
         ("tok", ">"),
         ("in", ">"),
         ("out", ">"),
+        ("turn", ">"),
     ]
     widths = {
         "id": id_width,
@@ -576,6 +597,7 @@ def _layout_columns(width, id_width, show):
         "tok": 7,
         "in": 7,
         "out": 7,
+        "turn": 7,
     }
     mins = {}
 
@@ -638,6 +660,16 @@ def _format_session(session, layout):
     status = "RUN" if session.get("status") == "running" else "IDLE"
     tok_s = session["tok_s"]
     tok_s_str = "-" if tok_s is None else f"{tok_s:5.1f}"
+    last_user_ts = session.get("last_user_ts")
+    last_agent_ts = session.get("last_agent_ts")
+    if status == "RUN":
+        turn_seconds = (datetime.now() - last_user_ts).total_seconds() if last_user_ts else None
+    else:
+        if last_user_ts and last_agent_ts:
+            turn_seconds = (last_agent_ts - last_user_ts).total_seconds()
+        else:
+            turn_seconds = None
+    turn_str = _format_duration(turn_seconds)
     meta = session.get("meta") or {}
     model = meta.get("model") or meta.get("model_provider") or "-"
     effort = meta.get("effort") or "-"
@@ -655,6 +687,7 @@ def _format_session(session, layout):
         "tok": tok_s_str,
         "in": total_in,
         "out": total_out,
+        "turn": turn_str,
         "model": _truncate_head(str(model), widths.get("model", 0)),
         "effort": _truncate_head(str(effort), widths.get("effort", 0)),
         "perm": _truncate_head(str(perm), widths.get("perm", 0)),
@@ -837,9 +870,22 @@ def main(argv=None):
     if argv and argv[0] == "top":
         _run_top(argv[1:])
         return
+    ralph_help = (
+        "Ralph loop mode (--ralph):\n"
+        "  Repeats the exact same prompt each iteration until a completion promise\n"
+        "  is detected or --max-iterations is reached (0 means unlimited).\n"
+        "  Completion promise: output <promise>TEXT</promise> where TEXT matches\n"
+        "  --completion-promise after trimming/collapsing whitespace. CRITICAL RULE:\n"
+        "  Only output the promise when it is completely and unequivocally TRUE.\n"
+        "  Cancel by deleting .codexapi/ralph-loop.local.md or running --ralph-cancel.\n"
+        "  Default reuses a single Codex thread; use --ralph-fresh for a new Agent\n"
+        "  each iteration (no shared context).\n"
+    )
     parser = argparse.ArgumentParser(
         prog="codexapi",
         description="Run Codex via the codexapi wrapper.",
+        epilog=ralph_help,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     parser.add_argument(
         "prompt",
@@ -870,10 +916,67 @@ def main(argv=None):
         action="store_true",
         help="Print the current thread id to stderr after running.",
     )
+    parser.add_argument(
+        "--ralph",
+        action="store_true",
+        help="Run a Ralph loop that repeats the same prompt each iteration.",
+    )
+    parser.add_argument(
+        "--max-iterations",
+        type=int,
+        default=None,
+        help="Max iterations for --ralph (0 means unlimited).",
+    )
+    parser.add_argument(
+        "--completion-promise",
+        help="Promise text for --ralph to match in <promise>...</promise>.",
+    )
+    parser.add_argument(
+        "--ralph-fresh",
+        action="store_true",
+        help="With --ralph, start each iteration with a fresh Agent context.",
+    )
+    parser.add_argument(
+        "--ralph-cancel",
+        action="store_true",
+        help=(
+            "Cancel a Ralph loop by removing .codexapi/ralph-loop.local.md "
+            "(respects --cwd)."
+        ),
+    )
 
     args = parser.parse_args(argv)
+    if args.ralph_cancel:
+        if (
+            args.ralph
+            or args.task
+            or args.thread_id
+            or args.print_thread_id
+            or args.max_iterations is not None
+            or args.completion_promise is not None
+            or args.ralph_fresh
+            or args.check is not None
+            or args.prompt
+        ):
+            raise SystemExit(
+                "--ralph-cancel cannot be combined with prompts or other modes."
+            )
+        print(cancel_ralph_loop(args.cwd))
+        return
     if args.check is not None and not args.task:
         raise SystemExit("--check requires --task.")
+    if not args.ralph and (
+        args.max_iterations is not None
+        or args.completion_promise is not None
+        or args.ralph_fresh
+    ):
+        raise SystemExit(
+            "--max-iterations/--completion-promise/--ralph-fresh require --ralph."
+        )
+    if args.ralph and (args.task or args.thread_id or args.print_thread_id):
+        raise SystemExit(
+            "--task/--thread-id/--print-thread-id are not supported with --ralph."
+        )
     if args.task and (args.thread_id or args.print_thread_id):
         raise SystemExit("--thread-id/--print-thread-id are not supported with --task.")
 
@@ -881,6 +984,20 @@ def main(argv=None):
 
     exit_code = 0
 
+    if args.ralph:
+        max_iterations = args.max_iterations if args.max_iterations is not None else 0
+        if max_iterations < 0:
+            raise SystemExit("--max-iterations must be >= 0.")
+        run_ralph_loop(
+            prompt,
+            args.cwd,
+            args.yolo,
+            args.flags,
+            max_iterations,
+            args.completion_promise,
+            args.ralph_fresh,
+        )
+        return
     if args.task:
         check = args.check if args.check is not None else prompt
         try:

codexapi-0.1.9/src/codexapi/ralph.py

@@ -0,0 +1,333 @@
+"""Ralph Wiggum-style loop for Codex runs."""
+
+import os
+import re
+import sys
+from datetime import datetime, timezone
+
+from .agent import Agent
+
+_STATE_DIR = ".codexapi"
+_STATE_FILE = "ralph-loop.local.md"
+_PROMISE_RE = re.compile(r"<promise>(.*?)</promise>", re.DOTALL)
+
+
+def run_ralph_loop(
+    prompt,
+    cwd=None,
+    yolo=False,
+    flags=None,
+    max_iterations=0,
+    completion_promise=None,
+    fresh=False,
+):
+    """Run a Ralph Wiggum-style loop that repeats the same prompt.
+
+    The loop writes `.codexapi/ralph-loop.local.md` in the target cwd and keeps
+    sending the exact same prompt each iteration until one of these happens:
+    - A completion promise is matched.
+    - `max_iterations` is reached (0 means unlimited).
+    - The state file is removed (cancel).
+    - An error or KeyboardInterrupt.
+
+    To complete with a promise, the agent must output:
+        <promise>TEXT</promise>
+    `TEXT` is trimmed and whitespace-collapsed before an exact match against
+    `completion_promise`. CRITICAL RULE: If a completion promise is set, you
+    may ONLY output it when the statement is completely and unequivocally TRUE.
+    Do not output false promises to escape the loop.
+
+    By default a single Agent instance is reused for shared context. Set
+    `fresh=True` to create a new Agent each iteration for a clean context.
+    Cancel by deleting the state file or running `codexapi --ralph-cancel`.
+    """
+    if not isinstance(prompt, str) or not prompt.strip():
+        raise ValueError("prompt must be a non-empty string")
+    if completion_promise is not None and not isinstance(completion_promise, str):
+        raise TypeError("completion_promise must be a string or None")
+    if max_iterations < 0:
+        raise ValueError("max_iterations must be >= 0")
+
+    state_path = _state_path(cwd)
+    _ensure_state_dir(state_path)
+
+    started_at = _utc_now()
+    iteration = 1
+    _write_state(
+        state_path,
+        iteration,
+        max_iterations,
+        completion_promise,
+        started_at,
+        prompt,
+    )
+
+    max_label = str(max_iterations) if max_iterations > 0 else "unlimited"
+    if completion_promise is None:
+        promise_label = "none (runs forever)"
+    else:
+        promise_label = (
+            f"{completion_promise} (ONLY output when TRUE - do not lie!)"
+        )
+
+    print(
+        "\n".join(
+            [
+                "Ralph loop activated.",
+                "",
+                f"Iteration: {iteration}",
+                f"Max iterations: {max_label}",
+                f"Completion promise: {promise_label}",
+                "",
+                "The loop will resend the SAME PROMPT each iteration.",
+                "Cancel by deleting .codexapi/ralph-loop.local.md or running",
+                "codexapi --ralph-cancel.",
+                "No manual stop beyond max iterations or completion promise.",
+                "",
+                "To monitor: head -10 .codexapi/ralph-loop.local.md",
+                "",
+            ]
+        )
+    )
+    print(prompt)
+
+    if completion_promise is not None:
+        print(
+            "\n".join(
+                [
+                    "",
+                    "CRITICAL - Ralph Loop Completion Promise",
+                    "",
+                    "To complete this loop, output this EXACT text:",
+                    f"  <promise>{completion_promise}</promise>",
+                    "",
+                    "STRICT REQUIREMENTS (DO NOT VIOLATE):",
+                    "  - Use <promise> XML tags EXACTLY as shown above",
+                    "  - The statement MUST be completely and unequivocally TRUE",
+                    "  - Do NOT output false statements to exit the loop",
+                    "  - Do NOT lie even if you think you should exit",
+                    "",
+                    "CRITICAL RULE: If a completion promise is set, you may ONLY",
+                    "output it when the statement is completely and unequivocally",
+                    "TRUE. Do not output false promises to escape the loop, even if",
+                    "you think you're stuck or should exit for other reasons. The",
+                    "loop is designed to continue until genuine completion.",
+                    "",
+                ]
+            )
+        )
+
+    runner = None
+    last_message = None
+    state_missing = False
+
+    try:
+        while True:
+            if not os.path.exists(state_path):
+                state_missing = True
+                print("Ralph loop canceled: state file removed.")
+                return last_message
+
+            print(_status_line(iteration, completion_promise))
+
+            if fresh:
+                runner = Agent(cwd, yolo, None, flags)
+            elif runner is None:
+                runner = Agent(cwd, yolo, None, flags)
+
+            message = runner(prompt)
+            print(message)
+            last_message = message
+
+            if not os.path.exists(state_path):
+                state_missing = True
+                print("Ralph loop canceled: state file removed.")
+                return last_message
+
+            if max_iterations > 0 and iteration >= max_iterations:
+                print(f"Ralph loop: Max iterations ({max_iterations}) reached.")
+                return message
+
+            if promise_matches(message, completion_promise):
+                print(
+                    "Ralph loop: Detected "
+                    f"<promise>{completion_promise}</promise>"
+                )
+                return message
+
+            if not os.path.exists(state_path):
+                state_missing = True
+                print("Ralph loop canceled: state file removed.")
+                return last_message
+
+            iteration += 1
+            _write_state(
+                state_path,
+                iteration,
+                max_iterations,
+                completion_promise,
+                started_at,
+                prompt,
+            )
+    except KeyboardInterrupt:
+        print("Ralph loop interrupted.", file=sys.stderr)
+        raise SystemExit(130)
+    except Exception as exc:
+        print(f"Ralph loop stopped: {exc}", file=sys.stderr)
+        raise SystemExit(1)
+    finally:
+        if not state_missing:
+            _cleanup_state(state_path)
+
+
+def cancel_ralph_loop(cwd=None):
+    """Cancel the Ralph loop by removing the state file."""
+    state_path = _state_path(cwd)
+    if not os.path.exists(state_path):
+        return "No active Ralph loop state found."
+
+    iteration = None
+    try:
+        fields = _read_state_fields(state_path)
+        value = fields.get("iteration")
+        if value and value.isdigit():
+            iteration = int(value)
+    except OSError:
+        iteration = None
+
+    _cleanup_state(state_path)
+
+    if iteration is None:
+        return "Canceled Ralph loop."
+    return f"Canceled Ralph loop at iteration {iteration}."
+
+
+def promise_matches(message, completion_promise):
+    """Return True when the message contains the matching completion promise."""
+    if completion_promise is None:
+        return False
+    extracted = _extract_promise(message)
+    if extracted is None:
+        return False
+    return extracted == completion_promise
+
+
+def _extract_promise(message):
+    """Extract and normalize the first <promise>...</promise> tag from text."""
+    match = _PROMISE_RE.search(message)
+    if not match:
+        return None
+    return _normalize_whitespace(match.group(1))
+
+
+def _normalize_whitespace(text):
+    """Trim and collapse whitespace to match the Claude plugin behavior."""
+    return " ".join(text.split())
+
+
+def _state_path(cwd):
+    """Return the absolute path for the Ralph loop state file."""
+    root = os.fspath(cwd) if cwd else os.getcwd()
+    return os.path.join(root, _STATE_DIR, _STATE_FILE)
+
+
+def _ensure_state_dir(state_path):
+    """Ensure the Ralph loop state directory exists."""
+    os.makedirs(os.path.dirname(state_path), exist_ok=True)
+
+
+def _write_state(
+    state_path,
+    iteration,
+    max_iterations,
+    completion_promise,
+    started_at,
+    prompt,
+):
+    """Write the Ralph loop state file atomically."""
+    content = _state_content(
+        iteration,
+        max_iterations,
+        completion_promise,
+        started_at,
+        prompt,
+    )
+    temp_path = f"{state_path}.tmp.{os.getpid()}"
+    with open(temp_path, "w", encoding="utf-8") as handle:
+        handle.write(content)
+    os.replace(temp_path, state_path)
+
+
+def _state_content(
+    iteration,
+    max_iterations,
+    completion_promise,
+    started_at,
+    prompt,
+):
+    """Build the YAML frontmatter state file content."""
+    completion_value = _format_completion_promise(completion_promise)
+    lines = [
+        "---",
+        "active: true",
+        f"iteration: {iteration}",
+        f"max_iterations: {max_iterations}",
+        f"completion_promise: {completion_value}",
+        f"started_at: \"{started_at}\"",
+        "---",
+        "",
+        prompt,
+    ]
+    return "\n".join(lines)
+
+
+def _format_completion_promise(completion_promise):
+    """Format the completion promise to match the plugin frontmatter."""
+    if completion_promise is None:
+        return "null"
+    return f"\"{completion_promise}\""
+
+
+def _read_state_fields(state_path):
+    """Read YAML frontmatter fields from the Ralph loop state file."""
+    with open(state_path, "r", encoding="utf-8") as handle:
+        lines = handle.read().splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}
+
+    fields = {}
+    for line in lines[1:]:
+        if line.strip() == "---":
+            break
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        fields[key.strip()] = value.strip()
+    return fields
+
+
+def _cleanup_state(state_path):
+    """Remove the Ralph loop state file if it exists."""
+    try:
+        os.remove(state_path)
+    except FileNotFoundError:
+        return
+
+
+def _status_line(iteration, completion_promise):
+    """Build the per-iteration status line for the Ralph loop."""
+    if completion_promise is None:
+        return (
+            f"Ralph iteration {iteration} | "
+            "No completion promise set - loop runs infinitely"
+        )
+    return (
+        f"Ralph iteration {iteration} | To stop: output "
+        f"<promise>{completion_promise}</promise> "
+        "(ONLY when statement is TRUE - do not lie to exit!)"
+    )
+
+
+def _utc_now():
+    """Return a UTC timestamp string matching the Claude plugin."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

{codexapi-0.1.7 → codexapi-0.1.9/src/codexapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.1.7
+Version: 0.1.9
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -81,6 +81,16 @@ Resume a session and print the thread id to stderr:
 codexapi --thread-id THREAD_ID --print-thread-id "Continue where we left off."
 ```
 
+Ralph loop mode repeats the same prompt until a completion promise or a max
+iteration cap is hit (0 means unlimited). Cancel by deleting
+`.codexapi/ralph-loop.local.md` or running `codexapi --ralph-cancel`.
+
+```bash
+codexapi --ralph "Fix the bug." --completion-promise DONE --max-iterations 5
+codexapi --ralph --ralph-fresh "Try again from scratch." --max-iterations 3
+codexapi --ralph-cancel --cwd /path/to/project
+```
+
 ## API
 
 ### `agent(prompt, cwd=None, yolo=False, flags=None) -> str`

{codexapi-0.1.7 → codexapi-0.1.9}/src/codexapi.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ src/codexapi/__init__.py
 src/codexapi/__main__.py
 src/codexapi/agent.py
 src/codexapi/cli.py
+src/codexapi/ralph.py
 src/codexapi/task.py
 src/codexapi.egg-info/PKG-INFO
 src/codexapi.egg-info/SOURCES.txt