codexapi 0.4.0__tar.gz → 0.5.1__tar.gz

{codexapi-0.4.0/src/codexapi.egg-info → codexapi-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.4.0
+Version: 0.5.1
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -9,6 +9,8 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tqdm>=4.64
 
 # CodexAPI
 
@@ -70,6 +72,7 @@ echo "Say hello." | codexapi run
 
 ```bash
 codexapi task "Fix the failing tests." --max-iterations 5
+codexapi task -f task.yaml
 ```
 
 Show running sessions and their latest activity:
@@ -90,13 +93,22 @@ Use `--no-yolo` to run Codex with `--full-auto` instead.
 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`.
+By default each iteration starts with a fresh Agent context; use
+`--ralph-reuse` to keep a single shared context across iterations.
 
 ```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 --ralph-reuse "Try again from the same context." --max-iterations 3
 codexapi ralph --cancel --cwd /path/to/project
 ```
 
+Run a task file across a list file:
+
+```bash
+codexapi foreach list.txt task.yaml
+codexapi foreach list.txt task.yaml -n 4
+```
+
 ## API
 
 ### `agent(prompt, cwd=None, yolo=True, flags=None) -> str`
@@ -141,7 +153,7 @@ Runs a Codex task with checker-driven retries. Subclass it and implement
 - `__call__() -> TaskResult`: run the task.
 - `set_up()`: optional setup hook.
 - `tear_down()`: optional cleanup hook.
-- `check() -> str | None`: return an error description or `None`/`""`.
+- `check(output=None) -> str | None`: return an error description or `None`/`""`. `output` is the last agent response.
 - `on_success(result)`: optional success hook.
 - `on_failure(result)`: optional failure hook.
 
@@ -163,6 +175,26 @@ Exception raised by `task()` when retries are exhausted.
 - `attempts` (int | None): attempts made when the task failed.
 - `errors` (str | None): last checker error, if any.
 
+### `foreach(list_file, task_file, n=None, cwd=None, yolo=True, flags=None) -> ForeachResult`
+
+Runs a task file over a list of items, updating the list file in place.
+
+- `list_file` (str | PathLike): path to the list file to process.
+- `task_file` (str | PathLike): YAML task file (must include `prompt`).
+- `n` (int | None): limit parallelism to N (default: run all items in parallel).
+- `cwd` (str | PathLike | None): working directory for the Codex session.
+- `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
+- `flags` (str | None): extra CLI flags to pass to Codex.
+
+### `ForeachResult(succeeded, failed, skipped, results)`
+
+Simple result object returned by `foreach()`.
+
+- `succeeded` (int): number of successful items.
+- `failed` (int): number of failed items.
+- `skipped` (int): number of items skipped (already marked in the list file).
+- `results` (list[tuple]): `(item, success, summary)` entries for items that ran.
+
 ## Behavior notes
 
 - Uses `codex exec --json` and parses JSONL events for `agent_message` items.

{codexapi-0.4.0 → codexapi-0.5.1}/README.md

@@ -58,6 +58,7 @@ echo "Say hello." | codexapi run
 
 ```bash
 codexapi task "Fix the failing tests." --max-iterations 5
+codexapi task -f task.yaml
 ```
 
 Show running sessions and their latest activity:
@@ -78,13 +79,22 @@ Use `--no-yolo` to run Codex with `--full-auto` instead.
 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`.
+By default each iteration starts with a fresh Agent context; use
+`--ralph-reuse` to keep a single shared context across iterations.
 
 ```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 --ralph-reuse "Try again from the same context." --max-iterations 3
 codexapi ralph --cancel --cwd /path/to/project
 ```
 
+Run a task file across a list file:
+
+```bash
+codexapi foreach list.txt task.yaml
+codexapi foreach list.txt task.yaml -n 4
+```
+
 ## API
 
 ### `agent(prompt, cwd=None, yolo=True, flags=None) -> str`
@@ -129,7 +139,7 @@ Runs a Codex task with checker-driven retries. Subclass it and implement
 - `__call__() -> TaskResult`: run the task.
 - `set_up()`: optional setup hook.
 - `tear_down()`: optional cleanup hook.
-- `check() -> str | None`: return an error description or `None`/`""`.
+- `check(output=None) -> str | None`: return an error description or `None`/`""`. `output` is the last agent response.
 - `on_success(result)`: optional success hook.
 - `on_failure(result)`: optional failure hook.
 
@@ -151,6 +161,26 @@ Exception raised by `task()` when retries are exhausted.
 - `attempts` (int | None): attempts made when the task failed.
 - `errors` (str | None): last checker error, if any.
 
+### `foreach(list_file, task_file, n=None, cwd=None, yolo=True, flags=None) -> ForeachResult`
+
+Runs a task file over a list of items, updating the list file in place.
+
+- `list_file` (str | PathLike): path to the list file to process.
+- `task_file` (str | PathLike): YAML task file (must include `prompt`).
+- `n` (int | None): limit parallelism to N (default: run all items in parallel).
+- `cwd` (str | PathLike | None): working directory for the Codex session.
+- `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
+- `flags` (str | None): extra CLI flags to pass to Codex.
+
+### `ForeachResult(succeeded, failed, skipped, results)`
+
+Simple result object returned by `foreach()`.
+
+- `succeeded` (int): number of successful items.
+- `failed` (int): number of failed items.
+- `skipped` (int): number of items skipped (already marked in the list file).
+- `results` (list[tuple]): `(item, success, summary)` entries for items that ran.
+
 ## Behavior notes
 
 - Uses `codex exec --json` and parses JSONL events for `agent_message` items.

{codexapi-0.4.0 → codexapi-0.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codexapi"
-version = "0.4.0"
+version = "0.5.1"
 description = "Minimal Python API for running the Codex CLI."
 readme = "README.md"
 requires-python = ">=3.8"
@@ -15,7 +15,10 @@ classifiers = [
   "Operating System :: OS Independent",
 ]
 
-dependencies = []
+dependencies = [
+  "PyYAML>=6.0",
+  "tqdm>=4.64",
+]
 
 [project.scripts]
 codexapi = "codexapi.cli:main"

{codexapi-0.4.0 → codexapi-0.5.1}/src/codexapi/__init__.py

@@ -1,15 +1,18 @@
 """Minimal Python API for running the Codex CLI."""
 
 from .agent import Agent, agent
+from .foreach import ForeachResult, foreach
 from .task import Task, TaskFailed, TaskResult, task, task_result
 
 __all__ = [
     "Agent",
+    "ForeachResult",
     "Task",
     "TaskFailed",
     "TaskResult",
     "agent",
+    "foreach",
     "task",
     "task_result",
 ]
-__version__ = "0.4.0"
+__version__ = "0.5.1"

{codexapi-0.4.0 → codexapi-0.5.1}/src/codexapi/cli.py

@@ -12,8 +12,10 @@ from datetime import datetime
 from pathlib import Path
 
 from .agent import Agent, agent
+from .foreach import foreach
 from .ralph import cancel_ralph_loop, run_ralph_loop
 from .task import TaskFailed, task
+from .taskfile import AutoTask, load_task_file
 
 _SESSION_ID_RE = re.compile(
     r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
@@ -38,6 +40,7 @@ _COLUMN_TITLES = {
     "in": "IN",
     "out": "OUT",
     "turn": "TURN",
+    "turns": "NTRN",
     "model": "MODEL",
     "effort": "EFF",
     "perm": "PERM",
@@ -121,6 +124,27 @@ def _tail_lines(path):
     return text.splitlines()
 
 
+def _count_turns(path):
+    event_count = 0
+    response_count = 0
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as handle:
+            for line in handle:
+                if "\"type\":\"event_msg\"" in line and "\"type\":\"user_message\"" in line:
+                    event_count += 1
+                    continue
+                if "\"type\":\"response_item\"" in line and "\"role\":\"user\"" in line and "\"type\":\"message\"" in line:
+                    response_count += 1
+    except OSError:
+        return None
+
+    if event_count:
+        return event_count
+    if response_count:
+        return response_count
+    return None
+
+
 def _extract_text(content):
     if isinstance(content, str):
         return content
@@ -364,6 +388,7 @@ def _summarize_session(path, mtime):
     total_usage = None
     meta = {}
     subagent = None
+    turns = _count_turns(path)
 
     for line in _tail_lines(path):
         try:
@@ -485,6 +510,7 @@ def _summarize_session(path, mtime):
         "last_user_ts": last_user_ts,
         "last_agent_ts": last_agent_ts,
         "last_event_kind": last_event_kind,
+        "turns": turns,
         "meta": meta,
     }
 
@@ -604,6 +630,7 @@ def _layout_columns(width, id_width, show):
         ("in", ">"),
         ("out", ">"),
         ("turn", ">"),
+        ("turns", ">"),
     ]
     widths = {
         "id": id_width,
@@ -612,6 +639,7 @@ def _layout_columns(width, id_width, show):
         "in": 7,
         "out": 7,
         "turn": 7,
+        "turns": 5,
     }
     mins = {}
 
@@ -684,6 +712,8 @@ def _format_session(session, layout):
         else:
             turn_seconds = None
     turn_str = _format_duration(turn_seconds)
+    turns = session.get("turns")
+    turns_str = "-" if turns is None else str(turns)
     meta = session.get("meta") or {}
     model = meta.get("model") or meta.get("model_provider") or "-"
     effort = meta.get("effort") or "-"
@@ -702,6 +732,7 @@ def _format_session(session, layout):
         "in": total_in,
         "out": total_out,
         "turn": turn_str,
+        "turns": _truncate_head(str(turns_str), widths.get("turns", 0)),
         "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)),
@@ -889,8 +920,8 @@ def main(argv=None):
         "  --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 codexapi ralph --cancel.\n"
-        "  Default reuses a single Codex thread; use --ralph-fresh for a new Agent\n"
-        "  each iteration (no shared context).\n"
+        "  Default starts each iteration with a fresh Agent context; use --ralph-reuse\n"
+        "  to reuse a single Codex thread across iterations.\n"
     )
     parser = argparse.ArgumentParser(
         prog="codexapi",
@@ -932,6 +963,11 @@ def main(argv=None):
         "task",
         help="Run a task with verification retries.",
     )
+    task_parser.add_argument(
+        "-f",
+        "--task-file",
+        help="YAML task file to run.",
+    )
     task_parser.add_argument(
         "prompt",
         nargs="?",
@@ -944,8 +980,8 @@ def main(argv=None):
     task_parser.add_argument(
         "--max-iterations",
         type=int,
-        default=10,
-        help="Max verification retries after a failed check (0 means no retries).",
+        default=None,
+        help="Max verification retries after a failed check (0 means no retries). Defaults to 10.",
     )
     task_parser.add_argument("--cwd", help="Working directory for the Codex session.")
     task_parser.add_argument(
@@ -990,10 +1026,20 @@ def main(argv=None):
         "--completion-promise",
         help="Promise text to match in <promise>...</promise>.",
     )
-    ralph_parser.add_argument(
+    ralph_fresh_group = ralph_parser.add_mutually_exclusive_group()
+    ralph_fresh_group.add_argument(
         "--ralph-fresh",
         action="store_true",
-        help="Start each iteration with a fresh Agent context.",
+        dest="ralph_fresh",
+        default=None,
+        help="Start each iteration with a fresh Agent context (default).",
+    )
+    ralph_fresh_group.add_argument(
+        "--ralph-reuse",
+        action="store_false",
+        dest="ralph_fresh",
+        default=None,
+        help="Reuse the same Agent context each iteration.",
     )
     ralph_parser.add_argument("--cwd", help="Working directory for the Codex session.")
     ralph_parser.add_argument(
@@ -1007,6 +1053,35 @@ def main(argv=None):
         help="Additional raw CLI flags to pass to Codex (quoted as needed).",
     )
 
+    foreach_parser = subparsers.add_parser(
+        "foreach",
+        help="Run a task file over a list file.",
+    )
+    foreach_parser.add_argument(
+        "list_file",
+        help="Path to the list file to process.",
+    )
+    foreach_parser.add_argument(
+        "task_file",
+        help="Path to the YAML task file.",
+    )
+    foreach_parser.add_argument(
+        "-n",
+        type=int,
+        help="Limit parallelism to N.",
+    )
+    foreach_parser.add_argument("--cwd", help="Working directory for the Codex session.")
+    foreach_parser.add_argument(
+        "--no-yolo",
+        action="store_false",
+        dest="yolo",
+        help="Disable --yolo and use --full-auto.",
+    )
+    foreach_parser.add_argument(
+        "--flags",
+        help="Additional raw CLI flags to pass to Codex (quoted as needed).",
+    )
+
     subparsers.add_parser(
         "top",
         help="Show running Codex sessions.",
@@ -1020,16 +1095,58 @@ def main(argv=None):
         _run_top([])
         return
 
+    if args.command == "foreach":
+        if args.n is not None and args.n < 1:
+            raise SystemExit("-n must be >= 1.")
+        result = foreach(
+            args.list_file,
+            args.task_file,
+            args.n,
+            args.cwd,
+            args.yolo,
+            args.flags,
+        )
+        if result.failed:
+            raise SystemExit(1)
+        return
+
     if args.command == "ralph":
         if args.cancel:
             if args.prompt:
                 raise SystemExit("ralph --cancel takes no prompt.")
-            if args.completion_promise or args.ralph_fresh:
-                raise SystemExit("--completion-promise/--ralph-fresh are not allowed with --cancel.")
+            if args.completion_promise or args.ralph_fresh is not None:
+                raise SystemExit(
+                    "--completion-promise/--ralph-fresh/--ralph-reuse are not allowed with --cancel."
+                )
             if args.max_iterations != 0:
                 raise SystemExit("--max-iterations is not allowed with --cancel.")
             print(cancel_ralph_loop(args.cwd))
             return
+        if args.ralph_fresh is None:
+            args.ralph_fresh = True
+
+    if args.command == "task" and args.task_file:
+        if args.prompt:
+            raise SystemExit("task -f does not take a prompt.")
+        if args.check is not None:
+            raise SystemExit("--check is not allowed with -f.")
+        if args.max_iterations is not None:
+            raise SystemExit("--max-iterations is not allowed with -f.")
+        task_def = load_task_file(args.task_file)
+        task_runner = AutoTask(
+            task_def,
+            None,
+            10,
+            args.cwd,
+            args.yolo,
+            None,
+            args.flags,
+        )
+        result = task_runner()
+        print(result.summary)
+        if not result.success:
+            raise SystemExit(1)
+        return
 
     prompt = _read_prompt(args.prompt)
     exit_code = 0
@@ -1048,6 +1165,8 @@ def main(argv=None):
         )
         return
     if args.command == "task":
+        if args.max_iterations is None:
+            args.max_iterations = 10
         if args.max_iterations < 0:
             raise SystemExit("--max-iterations must be >= 0.")
         check = args.check if args.check is not None else prompt

codexapi-0.5.1/src/codexapi/foreach.py

@@ -0,0 +1,230 @@
+"""Run a task file over a list of items with resumable progress."""
+
+import sys
+import threading
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+from tqdm import tqdm
+
+from .taskfile import AutoTask, load_task_file
+
+_STATUS_RUNNING = "⏳"
+_STATUS_SUCCESS = "✅"
+_STATUS_FAILED = "❌"
+_STATUS_SET = {_STATUS_RUNNING, _STATUS_SUCCESS, _STATUS_FAILED}
+
+
+class ForeachResult:
+    """Outcome summary for a foreach run."""
+
+    def __init__(self, succeeded, failed, skipped, results):
+        self.succeeded = succeeded
+        self.failed = failed
+        self.skipped = skipped
+        self.results = results
+
+    def __repr__(self):
+        return (
+            "ForeachResult("
+            f"succeeded={self.succeeded}, "
+            f"failed={self.failed}, "
+            f"skipped={self.skipped}, "
+            f"results={self.results!r}"
+            ")"
+        )
+
+
+def foreach(
+    list_file,
+    task_file,
+    n=None,
+    cwd=None,
+    yolo=True,
+    flags=None,
+):
+    """Run a task file over each item in list_file and update the file."""
+    task_def = load_task_file(task_file)
+    lines, ends_with_newline = _read_lines(list_file)
+    items, skipped = _collect_items(lines)
+
+    if not items:
+        return ForeachResult(0, 0, skipped, [])
+
+    max_workers = _max_workers(n, len(items))
+    lock = threading.Lock()
+    results = []
+    counts = {
+        "running": 0,
+        "success": 0,
+        "failed": 0,
+    }
+
+    progress = tqdm(total=len(items))
+    try:
+        with ThreadPoolExecutor(max_workers=max_workers) as executor:
+            futures = []
+            for index, item in items:
+                futures.append(
+                    executor.submit(
+                        _run_item,
+                        index,
+                        item,
+                        task_def,
+                        lines,
+                        ends_with_newline,
+                        list_file,
+                        cwd,
+                        yolo,
+                        flags,
+                        counts,
+                        results,
+                        progress,
+                        lock,
+                    )
+                )
+            for future in as_completed(futures):
+                future.result()
+    finally:
+        progress.close()
+
+    return ForeachResult(
+        counts["success"],
+        counts["failed"],
+        skipped,
+        results,
+    )
+
+
+def _max_workers(n, total):
+    if n is None:
+        return total
+    if n < 1:
+        raise ValueError("n must be >= 1")
+    if n > total:
+        return total
+    return n
+
+
+def _read_lines(path):
+    with open(path, "r", encoding="utf-8") as handle:
+        data = handle.read()
+    ends_with_newline = data.endswith("\n")
+    return data.splitlines(), ends_with_newline
+
+
+def _write_lines(path, lines, ends_with_newline):
+    text = "\n".join(lines)
+    if ends_with_newline:
+        text += "\n"
+    with open(path, "w", encoding="utf-8") as handle:
+        handle.write(text)
+
+
+def _collect_items(lines):
+    items = []
+    skipped = 0
+    for index, line in enumerate(lines):
+        if not line.strip():
+            continue
+        if _status_marker(line):
+            skipped += 1
+            continue
+        items.append((index, line))
+    return items, skipped
+
+
+def _status_marker(line):
+    if not line:
+        return None
+    marker = line[0]
+    if marker in _STATUS_SET:
+        return marker
+    return None
+
+
+def _status_text(counts):
+    return (
+        f"{_STATUS_RUNNING}: {counts['running']}, "
+        f"{_STATUS_SUCCESS}: {counts['success']}, "
+        f"{_STATUS_FAILED}: {counts['failed']}"
+    )
+
+
+def _single_line(text):
+    if not text:
+        return ""
+    return text.replace("\r", " ").replace("\n", " ")
+
+
+def _format_turns(used, total):
+    used_text = "?" if used is None else str(used)
+    total_text = "?" if total is None else str(total)
+    return f"[turns: {used_text}/{total_text}]"
+
+
+def _run_item(
+    index,
+    item,
+    task_def,
+    lines,
+    ends_with_newline,
+    list_file,
+    cwd,
+    yolo,
+    flags,
+    counts,
+    results,
+    progress,
+    lock,
+):
+    running_line = f"{_STATUS_RUNNING} {item}"
+    with lock:
+        lines[index] = running_line
+        _write_lines(list_file, lines, ends_with_newline)
+        counts["running"] += 1
+        progress.set_postfix_str(_status_text(counts))
+
+    summary = ""
+    success = False
+    attempts = None
+    max_attempts = None
+    try:
+        task = AutoTask(
+            task_def,
+            item,
+            10,
+            cwd,
+            yolo,
+            None,
+            flags,
+        )
+        max_attempts = task.max_attempts
+        result = task()
+        success = result.success
+        attempts = result.attempts
+        summary = result.summary or ""
+    except Exception as exc:
+        summary = f"{type(exc).__name__}: {exc}"
+        success = False
+
+    summary = _single_line(summary)
+    turns = _format_turns(attempts, max_attempts)
+    if summary:
+        summary = f"{summary} {turns}"
+    else:
+        summary = turns
+    status = _STATUS_SUCCESS if success else _STATUS_FAILED
+    final_line = f"{status} {item} | {summary}"
+
+    with lock:
+        lines[index] = final_line
+        _write_lines(list_file, lines, ends_with_newline)
+        counts["running"] -= 1
+        if success:
+            counts["success"] += 1
+        else:
+            counts["failed"] += 1
+        results.append((item, success, summary))
+        progress.update(1)
+        progress.set_postfix_str(_status_text(counts))
+        tqdm.write(final_line, file=sys.stdout)

{codexapi-0.4.0 → codexapi-0.5.1}/src/codexapi/ralph.py

@@ -19,7 +19,7 @@ def run_ralph_loop(
     flags=None,
     max_iterations=0,
     completion_promise=None,
-    fresh=False,
+    fresh=True,
 ):
     """Run a Ralph Wiggum-style loop that repeats the same prompt.
 
@@ -37,8 +37,8 @@ def run_ralph_loop(
     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.
+    By default each iteration uses a fresh Agent for a clean context. Set
+    `fresh=False` to reuse a single Agent instance for shared context.
     Cancel by deleting the state file or running `codexapi ralph --cancel`.
     """
     if not isinstance(prompt, str) or not prompt.strip():

{codexapi-0.4.0 → codexapi-0.5.1}/src/codexapi/task.py

@@ -10,8 +10,9 @@ _logger = logging.getLogger(__name__)
 
 _CHECK_PREFIX = (
     "You are a verification agent. Explore this workspace and carefully evaluate it "
-    "against the check below. Collect evidence by running any tests and/or reading "
+    "against the task below. Collect evidence by running any tests and/or reading "
     "and tracing through code, but do not change any of the code.\n"
+    "Act as a collaborator who wants to give the task owner all the information they need to succeed.\n"
     "Return only JSON with keys: success (boolean) and reason (string).\n"
     "Set success to true only if everything matches the intent."
 )
@@ -141,9 +142,11 @@ def _print_progress(
 
 def _fix_prompt(error):
     return (
-        "The verification check failed:\n"
+        "Thanks for your work. An automated verifier reported these issues:\n"
         f"{error}\n\n"
-        "Please fix the issues while staying close to the original intent."
+        "Take another look and see whether you agree and, if so, please take this "
+        "feedback into consideration and use it to continue to make progress "
+        "towards our original goal and intent."
     )
 
 
@@ -328,6 +331,7 @@ class Task:
         self.prompt = prompt
         self.max_attempts = max_attempts
         self.cwd = cwd
+        self.last_output = None
         self.agent = Agent(
             cwd,
             yolo,
@@ -341,8 +345,9 @@ class Task:
     def tear_down(self):
         """Delete the directory etc."""
 
-    def check(self):
+    def check(self, output=None):
         """ Check if the task is done, return a string describing the problems if not.
+            The output argument is the last agent response.
             This can be any combination of running tests, python code or running an agent
             with a specific prompt in self.cwd.
          """
@@ -356,9 +361,11 @@ class Task:
     def fix_prompt(self, error):
         """Build a prompt that asks the agent to fix checker failures."""
         return (
-            "The following checks failed:\n"
+            "Thanks for your work. An automated verifier reported these issues:\n"
             f"{error}\n\n"
-            "Can you please dive in and see if you agree with this assessment, then fix these issues while staying as close as you can to the spirit of the original task?"
+            "Take another look and see whether you agree and, if so, please take "
+            "this feedback into consideration and use it to continue to make "
+            "progress towards our original goal and intent."
         )
 
     def success_prompt(self):
@@ -382,18 +389,20 @@ class Task:
 
             # Start with the initial prompt
             output = self.agent(self.prompt)
+            self.last_output = output
             if debug:
                 _logger.debug("Initial output: %s", output)
             
             # Try correcting it up to max_attempts times
             for attempt in range(self.max_attempts):
-                error = self.check()
+                error = self.check(self.last_output)
                 if debug:
                     _logger.debug("Check error: %s", error)
                     
                 if error:
                     # if there were errors, tell the agent to fix them
                     output = self.agent(self.fix_prompt(error))
+                    self.last_output = output
                     if debug:
                         _logger.debug("Fix output: %s", output)
                 else:

codexapi-0.5.1/src/codexapi/taskfile.py

@@ -0,0 +1,108 @@
+"""Load YAML task files and map them onto Task hooks."""
+
+import yaml
+
+from .agent import agent
+from .task import Task
+
+_ITEM_TOKEN = "{{item}}"
+
+
+def load_task_file(path):
+    """Load a YAML task file and return a normalized task definition."""
+    if not path:
+        raise ValueError("task file path is required")
+    with open(path, "r", encoding="utf-8") as handle:
+        data = yaml.safe_load(handle) or {}
+    if not isinstance(data, dict):
+        raise ValueError("Task file must be a YAML mapping.")
+
+    prompt = data.get("prompt")
+    if not isinstance(prompt, str) or not prompt.strip():
+        raise ValueError("Task file missing non-empty 'prompt'.")
+
+    return {
+        "prompt": prompt,
+        "set_up": _optional_str(data.get("set_up")),
+        "tear_down": _optional_str(data.get("tear_down")),
+        "check": _optional_str(data.get("check")),
+        "on_success": _optional_str(data.get("on_success")),
+        "on_failure": _optional_str(data.get("on_failure")),
+    }
+
+
+def _optional_str(value):
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return value if value.strip() else None
+    raise ValueError("Task file values must be strings.")
+
+
+def _render(text, item):
+    if text is None:
+        return None
+    if item is None:
+        return text
+    return text.replace(_ITEM_TOKEN, item)
+
+
+class AutoTask(Task):
+    """Task subclass that maps YAML strings onto Task hooks."""
+
+    def __init__(
+        self,
+        config,
+        item=None,
+        max_attempts=10,
+        cwd=None,
+        yolo=True,
+        thread_id=None,
+        flags=None,
+    ):
+        if not isinstance(config, dict):
+            raise TypeError("config must be a task definition dict")
+        self._config = config
+        self._item = "" if item is None else str(item)
+        self._yolo = yolo
+        self._flags = flags
+        prompt = _render(config.get("prompt"), self._item)
+        super().__init__(prompt, max_attempts, cwd, yolo, thread_id, flags)
+
+    def _hook(self, name):
+        return _render(self._config.get(name), self._item)
+
+    def set_up(self):
+        text = self._hook("set_up")
+        if text:
+            agent(text, self.cwd, self._yolo, self._flags)
+
+    def tear_down(self):
+        text = self._hook("tear_down")
+        if text:
+            agent(text, self.cwd, self._yolo, self._flags)
+
+    def check(self, output=None):
+        text = self._hook("check")
+        if not text:
+            return None
+        last_output = output if output is not None else self.last_output
+        last_output = last_output or ""
+        if last_output:
+            prompt = f"{text}\n\nAGENT OUTPUT:\n{last_output}"
+        else:
+            prompt = text
+        result = agent(prompt, self.cwd, self._yolo, self._flags)
+        if not isinstance(result, str) or not result.strip():
+            return None
+        return result
+
+    def on_success(self, result):
+        text = self._hook("on_success")
+        if text:
+            agent(text, self.cwd, self._yolo, self._flags)
+
+    def on_failure(self, result):
+        text = self._hook("on_failure")
+        if text:
+            agent(text, self.cwd, self._yolo, self._flags)

{codexapi-0.4.0 → codexapi-0.5.1/src/codexapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.4.0
+Version: 0.5.1
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -9,6 +9,8 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tqdm>=4.64
 
 # CodexAPI
 
@@ -70,6 +72,7 @@ echo "Say hello." | codexapi run
 
 ```bash
 codexapi task "Fix the failing tests." --max-iterations 5
+codexapi task -f task.yaml
 ```
 
 Show running sessions and their latest activity:
@@ -90,13 +93,22 @@ Use `--no-yolo` to run Codex with `--full-auto` instead.
 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`.
+By default each iteration starts with a fresh Agent context; use
+`--ralph-reuse` to keep a single shared context across iterations.
 
 ```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 --ralph-reuse "Try again from the same context." --max-iterations 3
 codexapi ralph --cancel --cwd /path/to/project
 ```
 
+Run a task file across a list file:
+
+```bash
+codexapi foreach list.txt task.yaml
+codexapi foreach list.txt task.yaml -n 4
+```
+
 ## API
 
 ### `agent(prompt, cwd=None, yolo=True, flags=None) -> str`
@@ -141,7 +153,7 @@ Runs a Codex task with checker-driven retries. Subclass it and implement
 - `__call__() -> TaskResult`: run the task.
 - `set_up()`: optional setup hook.
 - `tear_down()`: optional cleanup hook.
-- `check() -> str | None`: return an error description or `None`/`""`.
+- `check(output=None) -> str | None`: return an error description or `None`/`""`. `output` is the last agent response.
 - `on_success(result)`: optional success hook.
 - `on_failure(result)`: optional failure hook.
 
@@ -163,6 +175,26 @@ Exception raised by `task()` when retries are exhausted.
 - `attempts` (int | None): attempts made when the task failed.
 - `errors` (str | None): last checker error, if any.
 
+### `foreach(list_file, task_file, n=None, cwd=None, yolo=True, flags=None) -> ForeachResult`
+
+Runs a task file over a list of items, updating the list file in place.
+
+- `list_file` (str | PathLike): path to the list file to process.
+- `task_file` (str | PathLike): YAML task file (must include `prompt`).
+- `n` (int | None): limit parallelism to N (default: run all items in parallel).
+- `cwd` (str | PathLike | None): working directory for the Codex session.
+- `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
+- `flags` (str | None): extra CLI flags to pass to Codex.
+
+### `ForeachResult(succeeded, failed, skipped, results)`
+
+Simple result object returned by `foreach()`.
+
+- `succeeded` (int): number of successful items.
+- `failed` (int): number of failed items.
+- `skipped` (int): number of items skipped (already marked in the list file).
+- `results` (list[tuple]): `(item, success, summary)` entries for items that ran.
+
 ## Behavior notes
 
 - Uses `codex exec --json` and parses JSONL events for `agent_message` items.

{codexapi-0.4.0 → codexapi-0.5.1}/src/codexapi.egg-info/SOURCES.txt

@@ -5,10 +5,13 @@ src/codexapi/__init__.py
 src/codexapi/__main__.py
 src/codexapi/agent.py
 src/codexapi/cli.py
+src/codexapi/foreach.py
 src/codexapi/ralph.py
 src/codexapi/task.py
+src/codexapi/taskfile.py
 src/codexapi.egg-info/PKG-INFO
 src/codexapi.egg-info/SOURCES.txt
 src/codexapi.egg-info/dependency_links.txt
 src/codexapi.egg-info/entry_points.txt
+src/codexapi.egg-info/requires.txt
 src/codexapi.egg-info/top_level.txt

codexapi-0.5.1/src/codexapi.egg-info/requires.txt

@@ -0,0 +1,2 @@
+PyYAML>=6.0
+tqdm>=4.64