codexapi 0.5.5__tar.gz → 0.5.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.5.5
+Version: 0.5.8
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -68,7 +68,7 @@ codexapi run --cwd /path/to/project "Fix the failing tests."
 echo "Say hello." | codexapi run
 ```
 
-`codexapi task` exits with code 0 on success and 1 on failure, printing the summary.
+`codexapi task` exits with code 0 on success and 1 on failure.
 
 ```bash
 codexapi task "Fix the failing tests." --max-iterations 5
@@ -79,9 +79,25 @@ 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).
+Use `max_iterations` in the task file to override the default iteration cap (0 means unlimited).
 Checks are wrapped with the verifier prompt, include the agent output, and expect JSON with `success`/`reason`.
 
+Take tasks from a GitHub Project (requires `gh-task`):
+
+```bash
+codexapi task -p owner/projects/3 -n "Your Name" -s Backlog task_a.yaml task_b.yaml
+```
+
+Task labels are derived from task filenames (basename without extension). The
+issue title/body become `{{item}}` after removing any existing `## Progress`
+section.
+
+Example task progress run:
+
+```bash
+./examples/example_task_progress.sh
+```
+
 Show running sessions and their latest activity:
 
 ```bash
@@ -151,11 +167,11 @@ the same conversation and returns only the agent's message.
 ### `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.
+Raises `TaskFailed` when the maximum iterations are reached.
 
 - `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.
+- `max_iterations` (int): maximum number of task iterations (0 means unlimited).
+- `progress` (bool): show a tqdm progress bar with a one-line status after each round.
 - `set_up`/`tear_down`/`on_success`/`on_failure` (str | None): optional hook prompts.
 
 ### `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`
@@ -164,7 +180,7 @@ 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)`
+### `Task(prompt, max_iterations=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
@@ -179,22 +195,22 @@ default check prompt and includes the agent output.
 - `on_success(result)`: optional success hook.
 - `on_failure(result)`: optional failure hook.
 
-### `TaskResult(success, summary, attempts, errors, thread_id)`
+### `TaskResult(success, summary, iterations, errors, thread_id)`
 
 Simple result object returned by `Task.__call__`.
 
 - `success` (bool): whether the task completed successfully.
 - `summary` (str): agent summary of what happened.
-- `attempts` (int): how many attempts were used.
+- `iterations` (int): how many iterations were used.
 - `errors` (str | None): last checker error, if any.
 - `thread_id` (str | None): Codex thread id for the session.
 
 ### `TaskFailed`
 
-Exception raised by `task()` when attempts are exhausted.
+Exception raised by `task()` when iterations are exhausted.
 
 - `summary` (str): failure summary text.
-- `attempts` (int | None): attempts made when the task failed.
+- `iterations` (int | None): iterations 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`

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

@@ -54,7 +54,7 @@ codexapi run --cwd /path/to/project "Fix the failing tests."
 echo "Say hello." | codexapi run
 ```
 
-`codexapi task` exits with code 0 on success and 1 on failure, printing the summary.
+`codexapi task` exits with code 0 on success and 1 on failure.
 
 ```bash
 codexapi task "Fix the failing tests." --max-iterations 5
@@ -65,9 +65,25 @@ 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).
+Use `max_iterations` in the task file to override the default iteration cap (0 means unlimited).
 Checks are wrapped with the verifier prompt, include the agent output, and expect JSON with `success`/`reason`.
 
+Take tasks from a GitHub Project (requires `gh-task`):
+
+```bash
+codexapi task -p owner/projects/3 -n "Your Name" -s Backlog task_a.yaml task_b.yaml
+```
+
+Task labels are derived from task filenames (basename without extension). The
+issue title/body become `{{item}}` after removing any existing `## Progress`
+section.
+
+Example task progress run:
+
+```bash
+./examples/example_task_progress.sh
+```
+
 Show running sessions and their latest activity:
 
 ```bash
@@ -137,11 +153,11 @@ the same conversation and returns only the agent's message.
 ### `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.
+Raises `TaskFailed` when the maximum iterations are reached.
 
 - `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.
+- `max_iterations` (int): maximum number of task iterations (0 means unlimited).
+- `progress` (bool): show a tqdm progress bar with a one-line status after each round.
 - `set_up`/`tear_down`/`on_success`/`on_failure` (str | None): optional hook prompts.
 
 ### `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`
@@ -150,7 +166,7 @@ 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)`
+### `Task(prompt, max_iterations=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
@@ -165,22 +181,22 @@ default check prompt and includes the agent output.
 - `on_success(result)`: optional success hook.
 - `on_failure(result)`: optional failure hook.
 
-### `TaskResult(success, summary, attempts, errors, thread_id)`
+### `TaskResult(success, summary, iterations, errors, thread_id)`
 
 Simple result object returned by `Task.__call__`.
 
 - `success` (bool): whether the task completed successfully.
 - `summary` (str): agent summary of what happened.
-- `attempts` (int): how many attempts were used.
+- `iterations` (int): how many iterations were used.
 - `errors` (str | None): last checker error, if any.
 - `thread_id` (str | None): Codex thread id for the session.
 
 ### `TaskFailed`
 
-Exception raised by `task()` when attempts are exhausted.
+Exception raised by `task()` when iterations are exhausted.
 
 - `summary` (str): failure summary text.
-- `attempts` (int | None): attempts made when the task failed.
+- `iterations` (int | None): iterations 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`

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

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

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

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

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

@@ -1033,9 +1033,25 @@ def main(argv=None):
         help="Item value for task files that use {{item}} placeholders.",
     )
     task_parser.add_argument(
-        "prompt",
-        nargs="?",
-        help="Prompt to send. Use '-' or omit to read from stdin.",
+        "-p",
+        "--project",
+        help="GitHub Project reference to pull tasks from.",
+    )
+    task_parser.add_argument(
+        "-s",
+        "--status",
+        default="Backlog",
+        help="Status name to take from when using --project (default: Backlog).",
+    )
+    task_parser.add_argument(
+        "-n",
+        "--name",
+        help="Owner label name for gh-task when using --project.",
+    )
+    task_parser.add_argument(
+        "task_args",
+        nargs="*",
+        help="Prompt to send (no --project) or task files (with --project).",
     )
     task_parser.add_argument(
         "--check",
@@ -1046,7 +1062,7 @@ def main(argv=None):
         type=int,
         default=None,
         help=(
-            "Max agent attempts (0 means unlimited). "
+            "Max agent iterations (0 means unlimited). "
             f"Defaults to {DEFAULT_MAX_ITERATIONS}."
         ),
     )
@@ -1276,8 +1292,40 @@ def main(argv=None):
         if args.ralph_fresh is None:
             args.ralph_fresh = True
 
+    if args.command == "task" and args.project:
+        if args.task_file:
+            raise SystemExit("task --project does not allow -f.")
+        if args.item is not None:
+            raise SystemExit("--item is only supported with -f.")
+        if args.check is not None:
+            raise SystemExit("--check is not allowed with --project.")
+        if args.max_iterations is not None:
+            raise SystemExit("--max-iterations is not allowed with --project.")
+        if not args.name:
+            raise SystemExit("--name is required with --project.")
+        if not args.task_args:
+            raise SystemExit("task --project requires one or more task files.")
+        try:
+            from .gh_integration import GhTaskRunner
+        except ImportError as exc:
+            raise SystemExit("gh-task is required for --project. Install it with pip.") from exc
+
+        task_runner = GhTaskRunner(
+            args.project,
+            args.name,
+            args.task_args,
+            args.status,
+            args.cwd,
+            args.yolo,
+            args.flags,
+        )
+        result = task_runner(progress=not args.quiet)
+        if not result.success:
+            raise SystemExit(1)
+        return
+
     if args.command == "task" and args.task_file:
-        if args.prompt:
+        if args.task_args:
             raise SystemExit("task -f does not take a prompt.")
         if args.item is not None:
             task_def = load_task_file(args.task_file)
@@ -1298,18 +1346,20 @@ def main(argv=None):
             flags=args.flags,
         )
         result = task_runner(progress=not args.quiet)
-        print(result.summary)
         if not result.success:
             raise SystemExit(1)
         return
 
     prompt_source = None
-    if args.command in ("run", "ralph", "task"):
+    prompt = None
+    if args.command in ("run", "ralph"):
         prompt_source = args.prompt
     elif args.command == "science":
         prompt_source = args.task
-    prompt = _read_prompt(prompt_source)
+    if args.command != "task":
+        prompt = _read_prompt(prompt_source)
     exit_code = 0
+    message = None
 
     if args.command == "ralph":
         if args.max_iterations < 0:
@@ -1339,6 +1389,8 @@ def main(argv=None):
         )
         return
     if args.command == "task":
+        if args.project:
+            raise SystemExit("task --project already handled earlier.")
         if args.item is not None:
             raise SystemExit("--item is only supported with -f.")
         if args.max_iterations is None:
@@ -1347,7 +1399,13 @@ def main(argv=None):
             raise SystemExit("--max-iterations must be >= 0.")
         check = args.check
         try:
-            message = task(
+            task_args = args.task_args or []
+            if len(task_args) > 1:
+                raise SystemExit("task takes a single prompt unless --project is used.")
+            if task_args:
+                prompt_source = task_args[0]
+            prompt = _read_prompt(prompt_source)
+            task(
                 prompt,
                 check,
                 args.max_iterations,
@@ -1357,7 +1415,6 @@ def main(argv=None):
                 not args.quiet,
             )
         except TaskFailed as exc:
-            message = exc.summary
             exit_code = 1
     else:
         use_session = args.thread_id or args.print_thread_id
@@ -1374,7 +1431,8 @@ def main(argv=None):
         else:
             message = agent(prompt, args.cwd, args.yolo, args.flags)
 
-    print(message)
+    if message is not None:
+        print(message)
     if exit_code:
         raise SystemExit(exit_code)
 

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

@@ -185,8 +185,8 @@ def _run_item(
 
     summary = ""
     success = False
-    attempts = None
-    max_attempts = None
+    iterations = None
+    max_iterations = None
     try:
         task = TaskFile(
             task_file,
@@ -196,17 +196,17 @@ def _run_item(
             thread_id=None,
             flags=flags,
         )
-        max_attempts = task.max_attempts
+        max_iterations = task.max_iterations
         result = task()
         success = result.success
-        attempts = result.attempts
+        iterations = result.iterations
         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)
+    turns = _format_turns(iterations, max_iterations)
     if summary:
         summary = f"{summary} {turns}"
     else:

codexapi-0.5.8/src/codexapi/gh_integration.py

@@ -0,0 +1,229 @@
+import logging
+import re
+import time
+from pathlib import Path
+
+from tqdm import tqdm
+
+from gh_task.project import Project
+
+from .taskfile import TaskFile
+
+
+_logger = logging.getLogger(__name__)
+
+_PROGRESS_HEADER = "## Progress"
+_SUCCESS_LABEL = "✓"
+_FAILURE_LABEL = "⨉"
+_SUCCESS_COLOR = "2da44e"
+_FAILURE_COLOR = "d73a4a"
+
+
+def _canonical_task_name(path):
+    return Path(path).stem
+
+
+def _task_file_map(task_files):
+    mapping = {}
+    for path in task_files:
+        name = _canonical_task_name(path)
+        if not name:
+            raise ValueError(f"Task file name is empty: {path}")
+        key = name.lower()
+        if key in mapping:
+            raise ValueError(f"Duplicate task name '{name}' for {path} and {mapping[key][1]}")
+        mapping[key] = (name, path)
+    if not mapping:
+        raise ValueError("At least one task file is required")
+    return mapping
+
+
+def _issue_url(issue):
+    if issue.url:
+        return issue.url
+    return f"https://github.com/{issue.repo}/issues/{issue.number}"
+
+
+def _match_task_file(issue, task_map):
+    labels = issue.labels or []
+    matches = []
+    for label in labels:
+        key = label.strip().lower()
+        if key in task_map:
+            matches.append((label, task_map[key][1]))
+    if not matches:
+        raise ValueError(f"Issue {_issue_url(issue)} has no matching task label")
+    if len(matches) > 1:
+        details = ", ".join(f"{label} -> {path}" for label, path in matches)
+        raise ValueError(
+            f"Issue {_issue_url(issue)} matches multiple task labels: {details}"
+        )
+    return matches[0][1]
+
+
+def _strip_progress_section(body):
+    if not body:
+        return ""
+    match = re.search(r"(?m)^## Progress\\s*$", body)
+    if not match:
+        return body.strip()
+    return body[:match.start()].rstrip()
+
+
+def _format_item_text(issue, description):
+    title = issue.title or ""
+    url = _issue_url(issue)
+    description = description or ""
+    return f"Issue: {url}\nTitle: {title}\nDescription: {description}\n"
+
+
+def _format_status_line(status_line):
+    match = re.match(r"^\\[(?P<turns>[^ ]+) @ (?P<elapsed>[^\\]]+)\\]:\\s*(?P<summary>.*)$", status_line)
+    if not match:
+        return status_line
+    summary = match.group("summary").strip()
+    prefix = f"`[{match.group('turns')} {match.group('elapsed')}]`"
+    if summary:
+        return f"{prefix} {summary}"
+    return prefix
+
+
+def _format_progress_bar(total, remaining, start_time):
+    if total is None:
+        total = 0
+    current = total - remaining
+    if current < 0:
+        current = 0
+    elapsed = 0.0
+    if start_time is not None:
+        elapsed = time.monotonic() - start_time
+    total_for_bar = total if total > 0 else 1
+    return tqdm.format_meter(current, total_for_bar, elapsed, ncols=80)
+
+
+def _render_progress_section(base_body, status_line, bar_text):
+    parts = [
+        _PROGRESS_HEADER,
+        "",
+        status_line,
+        "",
+        "```",
+        bar_text,
+        "```",
+    ]
+    section = "\n".join(parts).rstrip()
+    if base_body:
+        return f"{base_body.rstrip()}\n\n{section}\n"
+    return f"{section}\n"
+
+
+class GhTaskFile(TaskFile):
+    def __init__(
+        self,
+        path,
+        issue,
+        project,
+        item_text,
+        cwd=None,
+        yolo=True,
+        thread_id=None,
+        flags=None,
+    ):
+        super().__init__(path, item_text, None, cwd, yolo, thread_id, flags)
+        self.issue = issue
+        self.project = project
+        self._progress_updates = True
+
+    def on_progress(
+        self,
+        iterations,
+        max_iterations,
+        total_estimate,
+        remaining_estimate,
+        status_line,
+    ):
+        super().on_progress(
+            iterations,
+            max_iterations,
+            total_estimate,
+            remaining_estimate,
+            status_line,
+        )
+        try:
+            self.project.set_estimate(self.issue, remaining_estimate)
+        except Exception as exc:
+            _logger.warning("Failed to update estimate for issue %s", _issue_url(self.issue), exc_info=exc)
+        if not status_line:
+            return
+        try:
+            body = self.project.get_issue_body(self.issue)
+            base = _strip_progress_section(body)
+            status = _format_status_line(status_line)
+            bar_text = _format_progress_bar(total_estimate, remaining_estimate, self._progress_start)
+            updated = _render_progress_section(base, status, bar_text)
+            self.project.set_issue_body(self.issue, updated)
+        except Exception as exc:
+            _logger.warning("Failed to update issue progress for %s", _issue_url(self.issue), exc_info=exc)
+
+    def on_success(self, result):
+        super().on_success(result)
+        self.project.ensure_label(
+            self.issue.repo,
+            _SUCCESS_LABEL,
+            color=_SUCCESS_COLOR,
+            description="Task succeeded",
+        )
+        self.project.add_label(self.issue, _SUCCESS_LABEL)
+
+    def on_failure(self, result):
+        super().on_failure(result)
+        self.project.ensure_label(
+            self.issue.repo,
+            _FAILURE_LABEL,
+            color=_FAILURE_COLOR,
+            description="Task failed",
+        )
+        self.project.add_label(self.issue, _FAILURE_LABEL)
+
+    def tear_down(self):
+        super().tear_down()
+        self.project.move(self.issue, "In review")
+        self.project.release(self.issue)
+
+
+class GhTaskRunner:
+    def __init__(
+        self,
+        project,
+        name,
+        task_files,
+        status="Backlog",
+        cwd=None,
+        yolo=True,
+        flags=None,
+    ):
+        task_map = _task_file_map(task_files)
+        self.project = Project(project, name, has_label=list(task_map))
+        self.issue = self.project.take(status=status, return_issue=True)
+        self.issue = self.project.get_issue(self.issue)
+        try:
+            task_path = _match_task_file(self.issue, task_map)
+        except Exception:
+            self.project.release(self.issue)
+            raise
+        body = self.project.get_issue_body(self.issue)
+        description = _strip_progress_section(body)
+        item_text = _format_item_text(self.issue, description)
+        self.task = GhTaskFile(
+            task_path,
+            self.issue,
+            self.project,
+            item_text,
+            cwd,
+            yolo,
+            None,
+            flags,
+        )
+
+    def __call__(self, progress=False):
+        return self.task(progress=progress)

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

@@ -5,6 +5,7 @@ import logging
 import time
 
 from .agent import Agent, agent
+from tqdm import tqdm
 
 _logger = logging.getLogger(__name__)
 
@@ -20,11 +21,13 @@ _CHECK_PREFIX = (
     "Set success to true only if everything matches the intent."
 )
 _CHECK_SUFFIX = "JSON only. No markdown or extra text."
-_PROGRESS_PROMPT = (
-    "Summarize the outputs below in one line each.\n"
-    "Return only JSON with keys: agent (string) and check (string).\n"
-    "Each value must be a single line with no newlines.\n"
-    "Do not run commands or change any files."
+_ESTIMATE_PROMPT = (
+    "Estimate remaining work in story points for the task below.\n"
+    "You may inspect the repo (read files, git status/diff), but do not run tests.\n"
+    "Do not change any files.\n"
+    "Use the task prompt, current repo state, and latest agent/check outputs.\n"
+    "Return only JSON with keys: remaining (number) and summary (string).\n"
+    "summary must be a single line describing agent + verifier status."
 )
 DEFAULT_MAX_ITERATIONS = 10
 
@@ -62,14 +65,32 @@ def _resolve_check_text(prompt, check):
     return check, False
 
 
-def _build_progress_prompt(agent_output, check_output):
-    return (
-        f"{_PROGRESS_PROMPT}\n\n"
-        "AGENT OUTPUT:\n"
-        f"{agent_output}\n\n"
-        "CHECK OUTPUT:\n"
-        f"{check_output}"
+def _build_estimate_prompt(prompt, agent_output, check_output, previous_total):
+    agent_text = agent_output.strip() or "(no agent output yet)"
+    check_text = check_output.strip() or "(no check output yet)"
+    lines = [
+        _ESTIMATE_PROMPT,
+        "",
+        "TASK:",
+        "```",
+        prompt,
+        "```",
+    ]
+    if previous_total is not None:
+        lines.append(
+            f"This task was previously estimated at about {previous_total} story points."
+        )
+    lines.extend(
+        [
+            "",
+            "AGENT OUTPUT:",
+            agent_text,
+            "",
+            "CHECK OUTPUT:",
+            check_text,
+        ]
     )
+    return "\n".join(lines)
 
 
 def _check_result(output):
@@ -91,25 +112,29 @@ def _check_result(output):
     return success, reason.strip()
 
 
-def _progress_result(output):
+def _estimate_result(output):
     try:
         data = json.loads(output)
     except json.JSONDecodeError as exc:
         raise RuntimeError(
-            f"Progress summary returned invalid JSON: {exc}"
+            f"Estimate returned invalid JSON: {exc}"
         ) from exc
 
     if not isinstance(data, dict):
-        raise RuntimeError("Progress summary JSON must be an object.")
+        raise RuntimeError("Estimate JSON must be an object.")
+
+    remaining = data.get("remaining")
+    summary = data.get("summary")
+    if not isinstance(remaining, (int, float)):
+        raise RuntimeError("Estimate JSON missing numeric 'remaining'.")
+    if not isinstance(summary, str):
+        raise RuntimeError("Estimate JSON missing string 'summary'.")
 
-    agent_summary = data.get("agent")
-    check_summary = data.get("check")
-    if not isinstance(agent_summary, str):
-        raise RuntimeError("Progress summary JSON missing string 'agent'.")
-    if not isinstance(check_summary, str):
-        raise RuntimeError("Progress summary JSON missing string 'check'.")
+    remaining = int(round(remaining))
+    if remaining < 0:
+        remaining = 0
 
-    return _single_line(agent_summary), _single_line(check_summary)
+    return remaining, _single_line(summary)
 
 
 def _single_line(text):
@@ -118,63 +143,38 @@ def _single_line(text):
     return " ".join(text.replace("\r", " ").split())
 
 
-def _format_duration(seconds):
+def _format_elapsed(seconds):
     if seconds < 0:
         seconds = 0
     seconds = int(round(seconds))
     hours, remainder = divmod(seconds, 3600)
     minutes, seconds = divmod(remainder, 60)
-    parts = []
-    if hours:
-        parts.append(f"{hours}h")
-    if minutes or hours:
-        parts.append(f"{minutes}m")
-    if not hours:
-        parts.append(f"{seconds}s")
-    return " ".join(parts)
-
-
-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,
-    agent_output,
-    check_output,
-    cwd,
-    yolo,
-    flags,
-    success,
-):
-    elapsed = time.monotonic() - start_time
-    remaining = 0
-    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)
-    print(f"Agent: {agent_summary}", flush=True)
-    print(f"Check: {check_summary}", flush=True)
-    verdict = "success" if success else "failure"
-    print(
-        f"Verdict: {verdict} ({elapsed_text} elapsed, {remaining_text} remaining)",
-        flush=True,
+    return f"{hours}h{minutes:02d}m{seconds:02d}s"
+
+
+def _format_turns(iteration, total):
+    if total:
+        width = len(str(total))
+        total_text = str(total)
+    else:
+        width = len(str(iteration))
+        total_text = "∞"
+    if width < 1:
+        width = 1
+    iteration_text = f"{iteration:0{width}d}"
+    return f"{iteration_text}/{total_text}"
+
+
+def estimate(prompt, agent_output, check_output, cwd, yolo, flags, previous_total):
+    estimate_prompt = _build_estimate_prompt(
+        prompt,
+        agent_output or "",
+        check_output or "",
+        previous_total,
     )
-    print("", flush=True)
+    output = agent(estimate_prompt, cwd, yolo, flags)
+    return _estimate_result(output)
+
 
 def _fix_prompt(error):
     return (
@@ -192,21 +192,21 @@ def _success_prompt():
 
 def _failure_prompt(error):
     return (
-        "We ran out of attempts. Summarize what you did and what is still failing.\n\n"
+        "We ran out of iterations. Summarize what you did and what is still failing.\n\n"
         f"Outstanding issues:\n{error}"
     )
 
 
 class TaskFailed(RuntimeError):
-    """Raised when a task hits the maximum attempts without success."""
+    """Raised when a task hits the maximum iterations without success."""
 
-    def __init__(self, summary, attempts=None, errors=None):
-        message = "Task failed after maximum attempts."
+    def __init__(self, summary, iterations=None, errors=None):
+        message = "Task failed after maximum iterations."
         if summary:
             message = f"{message}\n{summary}"
         super().__init__(message)
         self.summary = summary
-        self.attempts = attempts
+        self.iterations = iterations
         self.errors = errors
 
 
@@ -237,11 +237,11 @@ def task(
         prompt: The task prompt to run.
         check: False to skip verification, None for the default check, or
             a string check prompt. The string "None" skips verification.
-        max_iterations: Maximum number of task attempts (0 means unlimited).
+        max_iterations: Maximum number of task iterations (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.
+        progress: Whether to show a tqdm progress bar with status updates.
         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.
@@ -251,7 +251,7 @@ def task(
         The agent's response text when the task succeeds.
 
     Raises:
-        TaskFailed: when the task reaches the maximum attempts without success.
+        TaskFailed: when the task reaches the maximum iterations without success.
     """
     result = task_result(
         prompt,
@@ -268,7 +268,7 @@ def task(
     )
     if result.success:
         return result.summary
-    raise TaskFailed(result.summary, result.attempts, result.errors)
+    raise TaskFailed(result.summary, result.iterations, result.errors)
 
 
 def task_result(
@@ -286,8 +286,8 @@ def task_result(
 ):
     """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.
+    The runner keeps a single session. Each verification iteration uses a fresh,
+    stateless agent call. When progress is True, show progress updates each round.
 
     Hook strings mirror task file keys: set_up, tear_down, on_success, on_failure.
     """
@@ -319,10 +319,10 @@ def task_result(
 class TaskResult:
     """Outcome summary for a task run."""
 
-    def __init__(self, success, summary, attempts, errors, thread_id):
+    def __init__(self, success, summary, iterations, errors, thread_id):
         self.success = success
         self.summary = summary
-        self.attempts = attempts
+        self.iterations = iterations
         self.errors = errors
         self.thread_id = thread_id
 
@@ -330,7 +330,7 @@ class TaskResult:
         return (
             "TaskResult("
             f"success={self.success}, "
-            f"attempts={self.attempts}, "
+            f"iterations={self.iterations}, "
             f"errors={self.errors!r}, "
             f"thread_id={self.thread_id!r}, "
             f"summary={self.summary!r}"
@@ -352,16 +352,16 @@ class Task:
     def __init__(
         self,
         prompt,
-        max_attempts=DEFAULT_MAX_ITERATIONS,
+        max_iterations=DEFAULT_MAX_ITERATIONS,
         cwd=None,
         yolo=True,
         thread_id=None,
         flags=None,
     ):
-        if max_attempts < 0:
-            raise ValueError("max_attempts must be >= 0")
+        if max_iterations < 0:
+            raise ValueError("max_iterations must be >= 0")
         self.prompt = prompt
-        self.max_attempts = max_attempts
+        self.max_iterations = max_iterations
         self.cwd = cwd
         self.last_output = None
         self.last_check_output = None
@@ -369,6 +369,11 @@ class Task:
         self.check_text = None
         self._yolo = yolo
         self._flags = flags
+        self._progress_enabled = False
+        self._progress_updates = False
+        self._progress_bar = None
+        self._progress_total = None
+        self._progress_start = None
         self.agent = Agent(
             cwd,
             yolo,
@@ -410,6 +415,30 @@ class Task:
     def on_failure(self, result):
         """Hook called after a failed run, e.g. log the failure reason."""
 
+    def on_progress(
+        self,
+        turns,
+        max_turns,
+        total_estimate,
+        remaining_estimate,
+        status_line,
+    ):
+        """Hook called with progress updates."""
+        if not self._progress_enabled:
+            return
+        if self._progress_bar is None:
+            self._progress_bar = tqdm(total=total_estimate)
+        if total_estimate != self._progress_bar.total:
+            self._progress_bar.total = total_estimate
+        current = total_estimate - remaining_estimate
+        if current < 0:
+            current = 0
+        if self._progress_bar.n != current:
+            self._progress_bar.n = current
+        self._progress_bar.refresh()
+        if status_line:
+            tqdm.write(status_line, file=self._progress_bar.fp)
+
     def fix_prompt(self, error):
         """Build a prompt that asks the agent to fix checker failures."""
         return (
@@ -432,47 +461,87 @@ class Task:
     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.
+            If progress is True, show a tqdm progress bar with status updates.
         """
         try:
             # If this fails in the middle we will still try to tear down
             self.set_up()
 
+            progress_updates = progress or self._progress_updates
+            self._progress_enabled = progress
+            if progress_updates:
+                remaining, _summary = estimate(
+                    self.prompt,
+                    "",
+                    "",
+                    self.cwd,
+                    self._yolo,
+                    self._flags,
+                    None,
+                )
+                self._progress_total = remaining
+                start_time = time.monotonic()
+                self._progress_start = start_time
+                self.on_progress(
+                    0,
+                    self.max_iterations,
+                    self._progress_total,
+                    remaining,
+                    None,
+                )
+            else:
+                start_time = time.monotonic()
+                self._progress_start = start_time
+
             # 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
-            start_time = time.monotonic()
+            # Try correcting it up to max_iterations times
             error = None
-            attempt = 0
+            iteration = 0
             while True:
-                attempt += 1
-                if progress:
-                    _print_progress_start(
-                        attempt,
-                        self.max_attempts,
-                    )
+                iteration += 1
                 error = self.check(self.last_output)
                 if debug:
                     _logger.debug("Check error: %s", error)
 
-                if progress:
+                if progress_updates:
                     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,
+                    remaining, summary = estimate(
+                        self.prompt,
+                        self.last_output or "",
                         check_output or "",
                         self.cwd,
                         self._yolo,
                         self._flags,
-                        not error,
+                        self._progress_total,
+                    )
+                    total_estimate = self._progress_total
+                    if total_estimate is None or remaining > total_estimate:
+                        total_estimate = remaining
+                    self._progress_total = total_estimate
+                    elapsed = _format_elapsed(time.monotonic() - start_time)
+                    status_prefix = (
+                        f"[{_format_turns(iteration, self.max_iterations)} @ {elapsed}]"
+                    )
+                    is_final = not error or (
+                        self.max_iterations and iteration >= self.max_iterations
+                    )
+                    if is_final:
+                        marker = "✅" if not error else "❌"
+                        summary = f"{marker} {summary}".strip()
+                    status_line = f"{status_prefix}: {summary}".rstrip()
+                    self.on_progress(
+                        iteration,
+                        self.max_iterations,
+                        total_estimate,
+                        remaining,
+                        status_line,
                     )
                 if not error:
                     summary = self.agent(self.success_prompt())
@@ -481,20 +550,20 @@ class Task:
                     result = TaskResult(
                         True,
                         summary,
-                        attempt,
+                        iteration,
                         None,
                         self.agent.thread_id,
                     )
                     self.on_success(result)
                     return result
-                if self.max_attempts and attempt >= self.max_attempts:
+                if self.max_iterations and iteration >= self.max_iterations:
                     summary = self.agent(self.failure_prompt(error))
                     if debug:
                         _logger.debug("Failure summary: %s", summary)
                     result = TaskResult(
                         False,
                         summary,
-                        attempt,
+                        iteration,
                         error,
                         self.agent.thread_id,
                     )
@@ -507,6 +576,8 @@ class Task:
         finally:
             # No matter what, once we have set_up we will always tear_down
             self.tear_down()
+            if self._progress_bar is not None:
+                self._progress_bar.close()
 
 
 class AutoTask(Task):
@@ -516,7 +587,7 @@ class AutoTask(Task):
         self,
         prompt,
         check=None,
-        max_attempts=DEFAULT_MAX_ITERATIONS,
+        max_iterations=DEFAULT_MAX_ITERATIONS,
         cwd=None,
         yolo=True,
         thread_id=None,
@@ -528,9 +599,9 @@ class AutoTask(Task):
     ):
         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)
+        if max_iterations < 0:
+            raise ValueError("max_iterations must be >= 0")
+        super().__init__(prompt, max_iterations, 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)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.5.5
+Version: 0.5.8
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -68,7 +68,7 @@ codexapi run --cwd /path/to/project "Fix the failing tests."
 echo "Say hello." | codexapi run
 ```
 
-`codexapi task` exits with code 0 on success and 1 on failure, printing the summary.
+`codexapi task` exits with code 0 on success and 1 on failure.
 
 ```bash
 codexapi task "Fix the failing tests." --max-iterations 5
@@ -79,9 +79,25 @@ 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).
+Use `max_iterations` in the task file to override the default iteration cap (0 means unlimited).
 Checks are wrapped with the verifier prompt, include the agent output, and expect JSON with `success`/`reason`.
 
+Take tasks from a GitHub Project (requires `gh-task`):
+
+```bash
+codexapi task -p owner/projects/3 -n "Your Name" -s Backlog task_a.yaml task_b.yaml
+```
+
+Task labels are derived from task filenames (basename without extension). The
+issue title/body become `{{item}}` after removing any existing `## Progress`
+section.
+
+Example task progress run:
+
+```bash
+./examples/example_task_progress.sh
+```
+
 Show running sessions and their latest activity:
 
 ```bash
@@ -151,11 +167,11 @@ the same conversation and returns only the agent's message.
 ### `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.
+Raises `TaskFailed` when the maximum iterations are reached.
 
 - `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.
+- `max_iterations` (int): maximum number of task iterations (0 means unlimited).
+- `progress` (bool): show a tqdm progress bar with a one-line status after each round.
 - `set_up`/`tear_down`/`on_success`/`on_failure` (str | None): optional hook prompts.
 
 ### `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`
@@ -164,7 +180,7 @@ 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)`
+### `Task(prompt, max_iterations=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
@@ -179,22 +195,22 @@ default check prompt and includes the agent output.
 - `on_success(result)`: optional success hook.
 - `on_failure(result)`: optional failure hook.
 
-### `TaskResult(success, summary, attempts, errors, thread_id)`
+### `TaskResult(success, summary, iterations, errors, thread_id)`
 
 Simple result object returned by `Task.__call__`.
 
 - `success` (bool): whether the task completed successfully.
 - `summary` (str): agent summary of what happened.
-- `attempts` (int): how many attempts were used.
+- `iterations` (int): how many iterations were used.
 - `errors` (str | None): last checker error, if any.
 - `thread_id` (str | None): Codex thread id for the session.
 
 ### `TaskFailed`
 
-Exception raised by `task()` when attempts are exhausted.
+Exception raised by `task()` when iterations are exhausted.
 
 - `summary` (str): failure summary text.
-- `attempts` (int | None): attempts made when the task failed.
+- `iterations` (int | None): iterations 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`

{codexapi-0.5.5 → codexapi-0.5.8}/src/codexapi.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ src/codexapi/__main__.py
 src/codexapi/agent.py
 src/codexapi/cli.py
 src/codexapi/foreach.py
+src/codexapi/gh_integration.py
 src/codexapi/ralph.py
 src/codexapi/task.py
 src/codexapi/taskfile.py