codexapi 0.5.3__tar.gz → 0.5.5__tar.gz

{codexapi-0.5.3/src/codexapi.egg-info → codexapi-0.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.5.3
+Version: 0.5.5
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -73,7 +73,14 @@ echo "Say hello." | codexapi run
 ```bash
 codexapi task "Fix the failing tests." --max-iterations 5
 codexapi task -f task.yaml
+codexapi task -f task.yaml -i README.md
 ```
+Progress is shown by default for `codexapi task`; use `--quiet` to suppress it.
+When using `--item`, the task file must include at least one `{{item}}` placeholder.
+
+Task files default to using the standard check prompt for the task. Set `check: "None"` to skip verification.
+Use `max_iterations` in the task file to override the default attempt cap (0 means unlimited).
+Checks are wrapped with the verifier prompt, include the agent output, and expect JSON with `success`/`reason`.
 
 Show running sessions and their latest activity:
 
@@ -115,6 +122,8 @@ Run a task file across a list file:
 ```bash
 codexapi foreach list.txt task.yaml
 codexapi foreach list.txt task.yaml -n 4
+codexapi foreach list.txt task.yaml --retry-failed
+codexapi foreach list.txt task.yaml --retry-all
 ```
 
 ## API
@@ -139,26 +148,31 @@ the same conversation and returns only the agent's message.
 - `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
 - `flags` (str | None): extra CLI flags to pass to Codex.
 
-### `task(prompt, check=None, n=10, cwd=None, yolo=True, flags=None) -> str`
+### `task(prompt, check=None, max_iterations=10, cwd=None, yolo=True, flags=None, progress=False, set_up=None, tear_down=None, on_success=None, on_failure=None) -> str`
 
 Runs a task with checker-driven retries and returns the success summary.
 Raises `TaskFailed` when the maximum attempts are reached.
 
-- `check` (str | None | False): custom check prompt, default checker, or `False` to skip.
-- `n` (int): maximum number of retries after a failed check.
+- `check` (str | None | False): custom check prompt, default checker, or `False`/`"None"` to skip.
+- `max_iterations` (int): maximum number of task attempts (0 means unlimited).
+- `progress` (bool): print progress after each verification round.
+- `set_up`/`tear_down`/`on_success`/`on_failure` (str | None): optional hook prompts.
 
-### `task_result(prompt, check=None, n=10, cwd=None, yolo=True, flags=None) -> TaskResult`
+### `task_result(prompt, check=None, max_iterations=10, cwd=None, yolo=True, flags=None, progress=False, set_up=None, tear_down=None, on_success=None, on_failure=None) -> TaskResult`
 
 Runs a task with checker-driven retries and returns a `TaskResult` without
 raising `TaskFailed`.
+Arguments mirror `task()` (including hooks).
 
 ### `Task(prompt, max_attempts=10, cwd=None, yolo=True, thread_id=None, flags=None)`
 
 Runs a Codex task with checker-driven retries. Subclass it and implement
 `check()` to return an error string when the task is incomplete, or return
 `None`/`""` when the task passes.
+If you do not override `check()`, the default verifier wrapper runs with the
+default check prompt and includes the agent output.
 
-- `__call__() -> TaskResult`: run the task.
+- `__call__(debug=False, progress=False) -> TaskResult`: run the task.
 - `set_up()`: optional setup hook.
 - `tear_down()`: optional cleanup hook.
 - `check(output=None) -> str | None`: return an error description or `None`/`""`. `output` is the last agent response.
@@ -177,7 +191,7 @@ Simple result object returned by `Task.__call__`.
 
 ### `TaskFailed`
 
-Exception raised by `task()` when retries are exhausted.
+Exception raised by `task()` when attempts are exhausted.
 
 - `summary` (str): failure summary text.
 - `attempts` (int | None): attempts made when the task failed.

{codexapi-0.5.3 → codexapi-0.5.5}/README.md

@@ -59,7 +59,14 @@ echo "Say hello." | codexapi run
 ```bash
 codexapi task "Fix the failing tests." --max-iterations 5
 codexapi task -f task.yaml
+codexapi task -f task.yaml -i README.md
 ```
+Progress is shown by default for `codexapi task`; use `--quiet` to suppress it.
+When using `--item`, the task file must include at least one `{{item}}` placeholder.
+
+Task files default to using the standard check prompt for the task. Set `check: "None"` to skip verification.
+Use `max_iterations` in the task file to override the default attempt cap (0 means unlimited).
+Checks are wrapped with the verifier prompt, include the agent output, and expect JSON with `success`/`reason`.
 
 Show running sessions and their latest activity:
 
@@ -101,6 +108,8 @@ Run a task file across a list file:
 ```bash
 codexapi foreach list.txt task.yaml
 codexapi foreach list.txt task.yaml -n 4
+codexapi foreach list.txt task.yaml --retry-failed
+codexapi foreach list.txt task.yaml --retry-all
 ```
 
 ## API
@@ -125,26 +134,31 @@ the same conversation and returns only the agent's message.
 - `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
 - `flags` (str | None): extra CLI flags to pass to Codex.
 
-### `task(prompt, check=None, n=10, cwd=None, yolo=True, flags=None) -> str`
+### `task(prompt, check=None, max_iterations=10, cwd=None, yolo=True, flags=None, progress=False, set_up=None, tear_down=None, on_success=None, on_failure=None) -> str`
 
 Runs a task with checker-driven retries and returns the success summary.
 Raises `TaskFailed` when the maximum attempts are reached.
 
-- `check` (str | None | False): custom check prompt, default checker, or `False` to skip.
-- `n` (int): maximum number of retries after a failed check.
+- `check` (str | None | False): custom check prompt, default checker, or `False`/`"None"` to skip.
+- `max_iterations` (int): maximum number of task attempts (0 means unlimited).
+- `progress` (bool): print progress after each verification round.
+- `set_up`/`tear_down`/`on_success`/`on_failure` (str | None): optional hook prompts.
 
-### `task_result(prompt, check=None, n=10, cwd=None, yolo=True, flags=None) -> TaskResult`
+### `task_result(prompt, check=None, max_iterations=10, cwd=None, yolo=True, flags=None, progress=False, set_up=None, tear_down=None, on_success=None, on_failure=None) -> TaskResult`
 
 Runs a task with checker-driven retries and returns a `TaskResult` without
 raising `TaskFailed`.
+Arguments mirror `task()` (including hooks).
 
 ### `Task(prompt, max_attempts=10, cwd=None, yolo=True, thread_id=None, flags=None)`
 
 Runs a Codex task with checker-driven retries. Subclass it and implement
 `check()` to return an error string when the task is incomplete, or return
 `None`/`""` when the task passes.
+If you do not override `check()`, the default verifier wrapper runs with the
+default check prompt and includes the agent output.
 
-- `__call__() -> TaskResult`: run the task.
+- `__call__(debug=False, progress=False) -> TaskResult`: run the task.
 - `set_up()`: optional setup hook.
 - `tear_down()`: optional cleanup hook.
 - `check(output=None) -> str | None`: return an error description or `None`/`""`. `output` is the last agent response.
@@ -163,7 +177,7 @@ Simple result object returned by `Task.__call__`.
 
 ### `TaskFailed`
 
-Exception raised by `task()` when retries are exhausted.
+Exception raised by `task()` when attempts are exhausted.
 
 - `summary` (str): failure summary text.
 - `attempts` (int | None): attempts made when the task failed.

{codexapi-0.5.3 → codexapi-0.5.5}/pyproject.toml

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

{codexapi-0.5.3 → codexapi-0.5.5}/src/codexapi/__init__.py

@@ -15,4 +15,4 @@ __all__ = [
     "task",
     "task_result",
 ]
-__version__ = "0.5.3"
+__version__ = "0.5.5"

{codexapi-0.5.3 → codexapi-0.5.5}/src/codexapi/cli.py

@@ -14,8 +14,8 @@ 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
+from .task import DEFAULT_MAX_ITERATIONS, TaskFailed, task
+from .taskfile import TaskFile, load_task_file, task_def_uses_item
 
 _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}"
@@ -62,6 +62,7 @@ _COLUMN_TITLES = {
     "perm": "PERM",
     "cwd": "CWD",
 }
+_FOREACH_STATUS_MARKERS = {"⏳", "✅", "❌"}
 
 
 def _read_prompt(prompt):
@@ -871,6 +872,37 @@ def _print_top_once(show):
         print(_format_session(session, layout))
 
 
+def _clean_foreach_list(path, retry_failed, retry_all):
+    with open(path, "r", encoding="utf-8") as handle:
+        data = handle.read()
+    ends_with_newline = data.endswith("\n")
+    lines = data.splitlines()
+
+    cleaned = []
+    changed = False
+    for line in lines:
+        new_line = line
+        if retry_all or (retry_failed and new_line.startswith("❌")):
+            if new_line and new_line[0] in _FOREACH_STATUS_MARKERS:
+                new_line = new_line[1:]
+                if new_line.startswith(" "):
+                    new_line = new_line[1:]
+            pipe = new_line.find("|")
+            if pipe != -1:
+                new_line = new_line[:pipe].rstrip()
+        if new_line != line:
+            changed = True
+        cleaned.append(new_line)
+
+    if not changed:
+        return
+    text = "\n".join(cleaned)
+    if ends_with_newline:
+        text += "\n"
+    with open(path, "w", encoding="utf-8") as handle:
+        handle.write(text)
+
+
 def _run_top(argv):
     if argv and argv[0] in ("-h", "--help"):
         print("usage: codexapi top")
@@ -995,6 +1027,11 @@ def main(argv=None):
         "--task-file",
         help="YAML task file to run.",
     )
+    task_parser.add_argument(
+        "-i",
+        "--item",
+        help="Item value for task files that use {{item}} placeholders.",
+    )
     task_parser.add_argument(
         "prompt",
         nargs="?",
@@ -1008,7 +1045,10 @@ def main(argv=None):
         "--max-iterations",
         type=int,
         default=None,
-        help="Max verification retries after a failed check (0 means no retries). Defaults to 10.",
+        help=(
+            "Max agent attempts (0 means unlimited). "
+            f"Defaults to {DEFAULT_MAX_ITERATIONS}."
+        ),
     )
     task_parser.add_argument("--cwd", help="Working directory for the Codex session.")
     task_parser.add_argument(
@@ -1022,9 +1062,9 @@ def main(argv=None):
         help="Additional raw CLI flags to pass to Codex (quoted as needed).",
     )
     task_parser.add_argument(
-        "--progress",
+        "--quiet",
         action="store_true",
-        help="Print progress after each verification round.",
+        help="Suppress progress output during verification.",
     )
 
     ralph_parser = subparsers.add_parser(
@@ -1145,6 +1185,17 @@ def main(argv=None):
         "task_file",
         help="Path to the YAML task file.",
     )
+    foreach_retry_group = foreach_parser.add_mutually_exclusive_group()
+    foreach_retry_group.add_argument(
+        "--retry-failed",
+        action="store_true",
+        help="Reset failed (❌) items for re-run.",
+    )
+    foreach_retry_group.add_argument(
+        "--retry-all",
+        action="store_true",
+        help="Reset all items for re-run.",
+    )
     foreach_parser.add_argument(
         "-n",
         type=int,
@@ -1178,6 +1229,12 @@ def main(argv=None):
     if args.command == "foreach":
         if args.n is not None and args.n < 1:
             raise SystemExit("-n must be >= 1.")
+        if args.retry_failed or args.retry_all:
+            _clean_foreach_list(
+                args.list_file,
+                args.retry_failed,
+                args.retry_all,
+            )
         result = foreach(
             args.list_file,
             args.task_file,
@@ -1222,21 +1279,25 @@ def main(argv=None):
     if args.command == "task" and args.task_file:
         if args.prompt:
             raise SystemExit("task -f does not take a prompt.")
+        if args.item is not None:
+            task_def = load_task_file(args.task_file)
+            if not task_def_uses_item(task_def):
+                raise SystemExit(
+                    "task -f --item requires {{item}} in the task file."
+                )
         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,
+        task_runner = TaskFile(
+            args.task_file,
+            args.item,
+            cwd=args.cwd,
+            yolo=args.yolo,
+            thread_id=None,
+            flags=args.flags,
         )
-        result = task_runner()
+        result = task_runner(progress=not args.quiet)
         print(result.summary)
         if not result.success:
             raise SystemExit(1)
@@ -1278,11 +1339,13 @@ def main(argv=None):
         )
         return
     if args.command == "task":
+        if args.item is not None:
+            raise SystemExit("--item is only supported with -f.")
         if args.max_iterations is None:
-            args.max_iterations = 10
+            args.max_iterations = DEFAULT_MAX_ITERATIONS
         if args.max_iterations < 0:
             raise SystemExit("--max-iterations must be >= 0.")
-        check = args.check if args.check is not None else prompt
+        check = args.check
         try:
             message = task(
                 prompt,
@@ -1291,7 +1354,7 @@ def main(argv=None):
                 args.cwd,
                 args.yolo,
                 args.flags,
-                args.progress,
+                not args.quiet,
             )
         except TaskFailed as exc:
             message = exc.summary

{codexapi-0.5.3 → codexapi-0.5.5}/src/codexapi/foreach.py

@@ -6,7 +6,7 @@ from concurrent.futures import ThreadPoolExecutor, as_completed
 
 from tqdm import tqdm
 
-from .taskfile import AutoTask, load_task_file
+from .taskfile import TaskFile
 
 _STATUS_RUNNING = "⏳"
 _STATUS_SUCCESS = "✅"
@@ -43,7 +43,6 @@ def foreach(
     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)
 
@@ -69,7 +68,7 @@ def foreach(
                         _run_item,
                         index,
                         item,
-                        task_def,
+                        task_file,
                         lines,
                         ends_with_newline,
                         list_file,
@@ -165,7 +164,7 @@ def _format_turns(used, total):
 def _run_item(
     index,
     item,
-    task_def,
+    task_file,
     lines,
     ends_with_newline,
     list_file,
@@ -189,14 +188,13 @@ def _run_item(
     attempts = None
     max_attempts = None
     try:
-        task = AutoTask(
-            task_def,
+        task = TaskFile(
+            task_file,
             item,
-            10,
-            cwd,
-            yolo,
-            None,
-            flags,
+            cwd=cwd,
+            yolo=yolo,
+            thread_id=None,
+            flags=flags,
         )
         max_attempts = task.max_attempts
         result = task()

{codexapi-0.5.3 → codexapi-0.5.5}/src/codexapi/task.py

@@ -10,9 +10,12 @@ _logger = logging.getLogger(__name__)
 
 _CHECK_PREFIX = (
     "You are a verification agent. Explore this workspace and carefully evaluate it "
-    "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"
+    "against the instructions below. Collect evidence by running any tests and/or "
+    "reading and tracing through code, but do not change any of the code.\n"
+    "You will receive the task or check instructions first, then the agent output "
+    "under the heading 'AGENT OUTPUT', which is provided for context and does not "
+    "replace or supersede collecting your own evidence unless it is clear from the "
+    "instructions that the agent's output IS the expected output of the task.\n"
     "Return only JSON with keys: success (boolean) and reason (string).\n"
     "Set success to true only if everything matches the intent."
 )
@@ -23,6 +26,7 @@ _PROGRESS_PROMPT = (
     "Each value must be a single line with no newlines.\n"
     "Do not run commands or change any files."
 )
+DEFAULT_MAX_ITERATIONS = 10
 
 
 def _default_check(prompt):
@@ -35,8 +39,27 @@ def _default_check(prompt):
     )
 
 
-def _build_check_prompt(check):
-    return f"{_CHECK_PREFIX}\n\n{check}\n\n{_CHECK_SUFFIX}"
+def _build_check_prompt(check, agent_output):
+    output = agent_output or ""
+    return (
+        f"{_CHECK_PREFIX}\n\n"
+        f"{check}\n\n"
+        "AGENT OUTPUT:\n"
+        f"{output}\n\n"
+        f"{_CHECK_SUFFIX}"
+    )
+
+
+def _resolve_check_text(prompt, check):
+    if check is False:
+        return None, True
+    if check is None:
+        return _default_check(prompt), False
+    if not isinstance(check, str):
+        raise TypeError("check must be a string or False")
+    if check.strip() == "None":
+        return None, True
+    return check, False
 
 
 def _build_progress_prompt(agent_output, check_output):
@@ -111,7 +134,17 @@ def _format_duration(seconds):
     return " ".join(parts)
 
 
-def _print_progress(
+def _progress_round_label(attempt, total):
+    if not total:
+        return f"Round {attempt}/unlimited"
+    return f"Round {attempt}/{total}"
+
+
+def _print_progress_start(attempt, total):
+    print(_progress_round_label(attempt, total), flush=True)
+
+
+def _print_progress_result(
     attempt,
     total,
     start_time,
@@ -120,24 +153,27 @@ def _print_progress(
     cwd,
     yolo,
     flags,
+    success,
 ):
     elapsed = time.monotonic() - start_time
     remaining = 0
-    if attempt:
+    remaining_text = "unknown"
+    if total and attempt:
         remaining = (elapsed / attempt) * (total - attempt)
+        remaining_text = _format_duration(remaining)
 
     summary_prompt = _build_progress_prompt(agent_output, check_output)
     summary = agent(summary_prompt, cwd, yolo, flags)
     agent_summary, check_summary = _progress_result(summary)
 
     elapsed_text = _format_duration(elapsed)
-    remaining_text = _format_duration(remaining)
+    print(f"Agent: {agent_summary}", flush=True)
+    print(f"Check: {check_summary}", flush=True)
+    verdict = "success" if success else "failure"
     print(
-        f"Round {attempt}/{total} ({elapsed_text} elapsed, {remaining_text} remaining)",
+        f"Verdict: {verdict} ({elapsed_text} elapsed, {remaining_text} remaining)",
         flush=True,
     )
-    print(f"Agent: {agent_summary}", flush=True)
-    print(f"Check: {check_summary}", flush=True)
     print("", flush=True)
 
 def _fix_prompt(error):
@@ -174,26 +210,42 @@ class TaskFailed(RuntimeError):
         self.errors = errors
 
 
+def _validate_hook(name, value):
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return value
+    raise TypeError(f"{name} must be a string or None")
+
+
 def task(
     prompt,
     check=None,
-    n=10,
+    max_iterations=DEFAULT_MAX_ITERATIONS,
     cwd=None,
     yolo=True,
     flags=None,
     progress=False,
+    set_up=None,
+    tear_down=None,
+    on_success=None,
+    on_failure=None,
 ):
     """Run a prompt with optional checker-driven retries.
 
     Args:
         prompt: The task prompt to run.
         check: False to skip verification, None for the default check, or
-            a string check prompt.
-        n: Maximum number of retries after a failed check.
+            a string check prompt. The string "None" skips verification.
+        max_iterations: Maximum number of task attempts (0 means unlimited).
         cwd: Optional working directory for the Codex session.
         yolo: Whether to pass --yolo to Codex.
         flags: Additional raw CLI flags to pass to Codex.
         progress: Whether to print progress after each verification round.
+        set_up: Optional setup prompt to run before the task.
+        tear_down: Optional cleanup prompt to run after the task.
+        on_success: Optional prompt to run after a successful task.
+        on_failure: Optional prompt to run after a failed task.
 
     Returns:
         The agent's response text when the task succeeds.
@@ -201,7 +253,19 @@ def task(
     Raises:
         TaskFailed: when the task reaches the maximum attempts without success.
     """
-    result = task_result(prompt, check, n, cwd, yolo, flags, progress)
+    result = task_result(
+        prompt,
+        check,
+        max_iterations,
+        cwd,
+        yolo,
+        flags,
+        progress,
+        set_up,
+        tear_down,
+        on_success,
+        on_failure,
+    )
     if result.success:
         return result.summary
     raise TaskFailed(result.summary, result.attempts, result.errors)
@@ -210,78 +274,46 @@ def task(
 def task_result(
     prompt,
     check=None,
-    n=10,
+    max_iterations=DEFAULT_MAX_ITERATIONS,
     cwd=None,
     yolo=True,
     flags=None,
     progress=False,
+    set_up=None,
+    tear_down=None,
+    on_success=None,
+    on_failure=None,
 ):
     """Run a prompt with optional checker-driven retries and return TaskResult.
 
     The runner keeps a single session. Each verification attempt uses a fresh,
     stateless agent call. When progress is True, print a summary each round.
+
+    Hook strings mirror task file keys: set_up, tear_down, on_success, on_failure.
     """
-    if check is False:
-        runner = Agent(cwd, yolo, None, flags)
-        start_time = time.monotonic()
-        summary = runner(prompt)
-        if progress:
-            _print_progress(
-                1,
-                1,
-                start_time,
-                summary,
-                "Verification skipped.",
-                cwd,
-                yolo,
-                flags,
-            )
-        return TaskResult(True, summary, 1, None, runner.thread_id)
-    if check is None:
-        check = _default_check(prompt)
-    if not isinstance(check, str):
+    if max_iterations < 0:
+        raise ValueError("max_iterations must be >= 0")
+    if not (check is None or check is False or isinstance(check, str)):
         raise TypeError("check must be a string or False")
-    if n < 0:
-        raise ValueError("n must be >= 0")
-
-    runner = Agent(cwd, yolo, None, flags)
-    start_time = time.monotonic()
-    last_output = runner(prompt)
-    check_prompt = _build_check_prompt(check)
 
-    for attempt in range(n + 1):
-        check_output = agent(check_prompt, cwd, yolo, flags)
-        success, reason = _check_result(check_output)
-        if progress:
-            _print_progress(
-                attempt + 1,
-                n + 1,
-                start_time,
-                last_output,
-                check_output,
-                cwd,
-                yolo,
-                flags,
-            )
-        if success:
-            summary = runner(_success_prompt())
-            return TaskResult(
-                True,
-                summary,
-                attempt + 1,
-                None,
-                runner.thread_id,
-            )
-        if attempt == n:
-            summary = runner(_failure_prompt(reason))
-            return TaskResult(
-                False,
-                summary,
-                attempt + 1,
-                reason,
-                runner.thread_id,
-            )
-        last_output = runner(_fix_prompt(reason))
+    set_up_text = _validate_hook("set_up", set_up)
+    tear_down_text = _validate_hook("tear_down", tear_down)
+    on_success_text = _validate_hook("on_success", on_success)
+    on_failure_text = _validate_hook("on_failure", on_failure)
+    runner = AutoTask(
+        prompt,
+        check,
+        max_iterations,
+        cwd,
+        yolo,
+        None,
+        flags,
+        set_up=set_up_text,
+        tear_down=tear_down_text,
+        on_success=on_success_text,
+        on_failure=on_failure_text,
+    )
+    return runner(progress=progress)
 
 
 class TaskResult:
@@ -320,18 +352,23 @@ class Task:
     def __init__(
         self,
         prompt,
-        max_attempts=10,
+        max_attempts=DEFAULT_MAX_ITERATIONS,
         cwd=None,
         yolo=True,
         thread_id=None,
         flags=None,
     ):
-        if max_attempts < 1:
-            raise ValueError("max_attempts must be >= 1")
+        if max_attempts < 0:
+            raise ValueError("max_attempts must be >= 0")
         self.prompt = prompt
         self.max_attempts = max_attempts
         self.cwd = cwd
         self.last_output = None
+        self.last_check_output = None
+        self.check_skipped = False
+        self.check_text = None
+        self._yolo = yolo
+        self._flags = flags
         self.agent = Agent(
             cwd,
             yolo,
@@ -346,11 +383,26 @@ class Task:
         """Delete the directory etc."""
 
     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.
-         """
+        """Check if the task is done, return a string describing problems if not.
+
+        The default implementation runs the verifier agent with the standard
+        check wrapper and expects JSON output.
+        """
+        self.last_check_output = None
+        self.check_skipped = False
+        check_text, skip = _resolve_check_text(self.prompt, self.check_text)
+        if skip:
+            self.check_skipped = True
+            return None
+        last_output = output if output is not None else self.last_output
+        last_output = last_output or ""
+        check_prompt = _build_check_prompt(check_text, last_output)
+        check_output = agent(check_prompt, self.cwd, self._yolo, self._flags)
+        self.last_check_output = check_output
+        success, reason = _check_result(check_output)
+        if success:
+            return None
+        return reason
 
     def on_success(self, result):
         """Hook called after a successful task, e.g. commit the changes."""
@@ -365,23 +417,22 @@ class Task:
             f"{error}\n\n"
             "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."
+            "progress towards our original goal and intent. Don't propose next steps, "
+            "use your best judgement and work towards the goal!"
         )
 
     def success_prompt(self):
         """Ask the agent to summarize what it did."""
-        return "Awesome - great job! Can you please produce a short summary of what you've done?"
+        return _success_prompt()
 
     def failure_prompt(self, error):
         """Ask the agent to summarize remaining issues after retries."""
-        return (
-            "We ran out of attempts. Can you please look back at everything you tried and summarize what it was that made this task too hard to complete, including anything you wish you'd known at the start that would have helped improve things?\n\n"
-            f"Outstanding issues:\n{error}"
-        )
+        return _failure_prompt(error)
 
-    def __call__(self, debug=False):
+    def __call__(self, debug=False, progress=False):
         """Run the task with checker-driven retries.
             If debug is True, log debug messages.
+            If progress is True, print progress after each verification round.
         """
         try:
             # If this fails in the middle we will still try to tear down
@@ -392,35 +443,112 @@ class Task:
             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):
+            start_time = time.monotonic()
+            error = None
+            attempt = 0
+            while True:
+                attempt += 1
+                if progress:
+                    _print_progress_start(
+                        attempt,
+                        self.max_attempts,
+                    )
                 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:
-                    # otherwise get a summary of what was done and run on_success
+
+                if progress:
+                    check_output = self.last_check_output
+                    if self.check_skipped:
+                        check_output = "Verification skipped."
+                    _print_progress_result(
+                        attempt,
+                        self.max_attempts,
+                        start_time,
+                        self.last_output,
+                        check_output or "",
+                        self.cwd,
+                        self._yolo,
+                        self._flags,
+                        not error,
+                    )
+                if not error:
                     summary = self.agent(self.success_prompt())
                     if debug:
                         _logger.debug("Success summary: %s", summary)
-                    result = TaskResult(True, summary, attempt + 1, error, self.agent.thread_id)
+                    result = TaskResult(
+                        True,
+                        summary,
+                        attempt,
+                        None,
+                        self.agent.thread_id,
+                    )
                     self.on_success(result)
                     return result
-
-            # Ran out of attempts - get a reason why and run on_failure
-            summary = self.agent(self.failure_prompt(error))
-            if debug:
-                _logger.debug("Failure summary: %s", summary)
-            result = TaskResult(False, summary, attempt + 1, error, self.agent.thread_id)
-            self.on_failure(result)
-            return result
+                if self.max_attempts and attempt >= self.max_attempts:
+                    summary = self.agent(self.failure_prompt(error))
+                    if debug:
+                        _logger.debug("Failure summary: %s", summary)
+                    result = TaskResult(
+                        False,
+                        summary,
+                        attempt,
+                        error,
+                        self.agent.thread_id,
+                    )
+                    self.on_failure(result)
+                    return result
+                output = self.agent(self.fix_prompt(error))
+                self.last_output = output
+                if debug:
+                    _logger.debug("Fix output: %s", output)
         finally:
             # No matter what, once we have set_up we will always tear_down
             self.tear_down()
+
+
+class AutoTask(Task):
+    """Task subclass that maps prompt strings onto Task hooks."""
+
+    def __init__(
+        self,
+        prompt,
+        check=None,
+        max_attempts=DEFAULT_MAX_ITERATIONS,
+        cwd=None,
+        yolo=True,
+        thread_id=None,
+        flags=None,
+        set_up=None,
+        tear_down=None,
+        on_success=None,
+        on_failure=None,
+    ):
+        if not (check is None or check is False or isinstance(check, str)):
+            raise TypeError("check must be a string or False")
+        if max_attempts < 0:
+            raise ValueError("max_attempts must be >= 0")
+        super().__init__(prompt, max_attempts, cwd, yolo, thread_id, flags)
+        self.check_text = check
+        self._set_up = _validate_hook("set_up", set_up)
+        self._tear_down = _validate_hook("tear_down", tear_down)
+        self._on_success = _validate_hook("on_success", on_success)
+        self._on_failure = _validate_hook("on_failure", on_failure)
+
+    def _run_hook(self, text):
+        if text:
+            agent(text, self.cwd, self._yolo, self._flags)
+
+    def set_up(self):
+        self._run_hook(self._set_up)
+
+    def tear_down(self):
+        self._run_hook(self._tear_down)
+
+    def on_success(self, result):
+        self._run_hook(self._on_success)
+
+    def on_failure(self, result):
+        self._run_hook(self._on_failure)

codexapi-0.5.5/src/codexapi/taskfile.py

@@ -0,0 +1,123 @@
+"""Load YAML task files and map them onto Task hooks."""
+
+import yaml
+
+from .task import AutoTask
+
+_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'.")
+
+    max_iterations = data.get("max_iterations")
+    if max_iterations is not None:
+        if not isinstance(max_iterations, int):
+            raise ValueError("Task file max_iterations must be an integer.")
+        if max_iterations < 0:
+            raise ValueError("Task file max_iterations must be >= 0.")
+
+    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")),
+        "max_iterations": max_iterations,
+    }
+
+
+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)
+
+
+def task_def_uses_item(task_def):
+    """Return True if a task definition includes the {{item}} placeholder."""
+    if not isinstance(task_def, dict):
+        raise TypeError("task definition must be a dict")
+    for key in ("prompt", "set_up", "tear_down", "check", "on_success", "on_failure"):
+        value = task_def.get(key)
+        if isinstance(value, str) and _ITEM_TOKEN in value:
+            return True
+    return False
+
+
+class TaskFile(AutoTask):
+    """Task subclass that maps a YAML task file onto Task hooks."""
+
+    def __init__(
+        self,
+        path,
+        item=None,
+        max_iterations=None,
+        cwd=None,
+        yolo=True,
+        thread_id=None,
+        flags=None,
+    ):
+        task_def = load_task_file(path)
+        if max_iterations is None:
+            max_iterations = task_def.get("max_iterations")
+        elif not isinstance(max_iterations, int):
+            raise ValueError("max_iterations must be an integer.")
+        elif max_iterations < 0:
+            raise ValueError("max_iterations must be >= 0.")
+        item_text = "" if item is None else str(item)
+        rendered = {
+            "prompt": _render(task_def.get("prompt"), item_text),
+            "set_up": _render(task_def.get("set_up"), item_text),
+            "tear_down": _render(task_def.get("tear_down"), item_text),
+            "check": _render(task_def.get("check"), item_text),
+            "on_success": _render(task_def.get("on_success"), item_text),
+            "on_failure": _render(task_def.get("on_failure"), item_text),
+        }
+        if max_iterations is None:
+            super().__init__(
+                rendered["prompt"],
+                rendered["check"],
+                cwd=cwd,
+                yolo=yolo,
+                thread_id=thread_id,
+                flags=flags,
+                set_up=rendered["set_up"],
+                tear_down=rendered["tear_down"],
+                on_success=rendered["on_success"],
+                on_failure=rendered["on_failure"],
+            )
+            return
+        super().__init__(
+            rendered["prompt"],
+            rendered["check"],
+            max_iterations,
+            cwd,
+            yolo,
+            thread_id,
+            flags,
+            set_up=rendered["set_up"],
+            tear_down=rendered["tear_down"],
+            on_success=rendered["on_success"],
+            on_failure=rendered["on_failure"],
+        )

{codexapi-0.5.3 → codexapi-0.5.5/src/codexapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.5.3
+Version: 0.5.5
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -73,7 +73,14 @@ echo "Say hello." | codexapi run
 ```bash
 codexapi task "Fix the failing tests." --max-iterations 5
 codexapi task -f task.yaml
+codexapi task -f task.yaml -i README.md
 ```
+Progress is shown by default for `codexapi task`; use `--quiet` to suppress it.
+When using `--item`, the task file must include at least one `{{item}}` placeholder.
+
+Task files default to using the standard check prompt for the task. Set `check: "None"` to skip verification.
+Use `max_iterations` in the task file to override the default attempt cap (0 means unlimited).
+Checks are wrapped with the verifier prompt, include the agent output, and expect JSON with `success`/`reason`.
 
 Show running sessions and their latest activity:
 
@@ -115,6 +122,8 @@ Run a task file across a list file:
 ```bash
 codexapi foreach list.txt task.yaml
 codexapi foreach list.txt task.yaml -n 4
+codexapi foreach list.txt task.yaml --retry-failed
+codexapi foreach list.txt task.yaml --retry-all
 ```
 
 ## API
@@ -139,26 +148,31 @@ the same conversation and returns only the agent's message.
 - `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
 - `flags` (str | None): extra CLI flags to pass to Codex.
 
-### `task(prompt, check=None, n=10, cwd=None, yolo=True, flags=None) -> str`
+### `task(prompt, check=None, max_iterations=10, cwd=None, yolo=True, flags=None, progress=False, set_up=None, tear_down=None, on_success=None, on_failure=None) -> str`
 
 Runs a task with checker-driven retries and returns the success summary.
 Raises `TaskFailed` when the maximum attempts are reached.
 
-- `check` (str | None | False): custom check prompt, default checker, or `False` to skip.
-- `n` (int): maximum number of retries after a failed check.
+- `check` (str | None | False): custom check prompt, default checker, or `False`/`"None"` to skip.
+- `max_iterations` (int): maximum number of task attempts (0 means unlimited).
+- `progress` (bool): print progress after each verification round.
+- `set_up`/`tear_down`/`on_success`/`on_failure` (str | None): optional hook prompts.
 
-### `task_result(prompt, check=None, n=10, cwd=None, yolo=True, flags=None) -> TaskResult`
+### `task_result(prompt, check=None, max_iterations=10, cwd=None, yolo=True, flags=None, progress=False, set_up=None, tear_down=None, on_success=None, on_failure=None) -> TaskResult`
 
 Runs a task with checker-driven retries and returns a `TaskResult` without
 raising `TaskFailed`.
+Arguments mirror `task()` (including hooks).
 
 ### `Task(prompt, max_attempts=10, cwd=None, yolo=True, thread_id=None, flags=None)`
 
 Runs a Codex task with checker-driven retries. Subclass it and implement
 `check()` to return an error string when the task is incomplete, or return
 `None`/`""` when the task passes.
+If you do not override `check()`, the default verifier wrapper runs with the
+default check prompt and includes the agent output.
 
-- `__call__() -> TaskResult`: run the task.
+- `__call__(debug=False, progress=False) -> TaskResult`: run the task.
 - `set_up()`: optional setup hook.
 - `tear_down()`: optional cleanup hook.
 - `check(output=None) -> str | None`: return an error description or `None`/`""`. `output` is the last agent response.
@@ -177,7 +191,7 @@ Simple result object returned by `Task.__call__`.
 
 ### `TaskFailed`
 
-Exception raised by `task()` when retries are exhausted.
+Exception raised by `task()` when attempts are exhausted.
 
 - `summary` (str): failure summary text.
 - `attempts` (int | None): attempts made when the task failed.

codexapi-0.5.3/src/codexapi/taskfile.py

@@ -1,108 +0,0 @@
-"""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)