codexapi 0.5.6__tar.gz → 0.5.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.5.6
+Version: 0.5.8
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -79,9 +79,19 @@ 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
@@ -157,10 +167,10 @@ 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).
+- `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.
 
@@ -170,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
@@ -185,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.6 → codexapi-0.5.8}/README.md

@@ -65,9 +65,19 @@ 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
@@ -143,10 +153,10 @@ 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).
+- `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.
 
@@ -156,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
@@ -171,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.6 → codexapi-0.5.8}/pyproject.toml

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

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

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

{codexapi-0.5.6 → 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)
@@ -1303,11 +1351,13 @@ def main(argv=None):
         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
 
@@ -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,6 +1399,12 @@ def main(argv=None):
             raise SystemExit("--max-iterations must be >= 0.")
         check = args.check
         try:
+            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,

{codexapi-0.5.6 → 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.6 → codexapi-0.5.8}/src/codexapi/task.py

@@ -152,15 +152,17 @@ def _format_elapsed(seconds):
     return f"{hours}h{minutes:02d}m{seconds:02d}s"
 
 
-def _format_turns(attempt, total):
+def _format_turns(iteration, total):
     if total:
-        width = max(2, len(str(total)))
+        width = len(str(total))
         total_text = str(total)
     else:
-        width = 2
+        width = len(str(iteration))
         total_text = "∞"
-    attempt_text = f"{attempt:0{width}d}"
-    return f"{attempt_text}/{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):
@@ -190,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
 
 
@@ -235,7 +237,7 @@ 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.
@@ -249,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,
@@ -266,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(
@@ -284,7 +286,7 @@ 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,
+    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.
@@ -317,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
 
@@ -328,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}"
@@ -350,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
@@ -368,8 +370,10 @@ class Task:
         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,
@@ -463,8 +467,9 @@ class Task:
             # 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:
+            if progress_updates:
                 remaining, _summary = estimate(
                     self.prompt,
                     "",
@@ -476,15 +481,17 @@ class Task:
                 )
                 self._progress_total = remaining
                 start_time = time.monotonic()
+                self._progress_start = start_time
                 self.on_progress(
                     0,
-                    self.max_attempts,
+                    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)
@@ -492,16 +499,16 @@ class Task:
             if debug:
                 _logger.debug("Initial output: %s", output)
 
-            # Try correcting it up to max_attempts times
+            # Try correcting it up to max_iterations times
             error = None
-            attempt = 0
+            iteration = 0
             while True:
-                attempt += 1
+                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."
@@ -520,18 +527,18 @@ class Task:
                     self._progress_total = total_estimate
                     elapsed = _format_elapsed(time.monotonic() - start_time)
                     status_prefix = (
-                        f"[{_format_turns(attempt, self.max_attempts)} @ {elapsed}]"
+                        f"[{_format_turns(iteration, self.max_iterations)} @ {elapsed}]"
                     )
                     is_final = not error or (
-                        self.max_attempts and attempt >= self.max_attempts
+                        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(
-                        attempt,
-                        self.max_attempts,
+                        iteration,
+                        self.max_iterations,
                         total_estimate,
                         remaining,
                         status_line,
@@ -543,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,
                     )
@@ -580,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,
@@ -592,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.6 → codexapi-0.5.8/src/codexapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.5.6
+Version: 0.5.8
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -79,9 +79,19 @@ 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
@@ -157,10 +167,10 @@ 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).
+- `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.
 
@@ -170,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
@@ -185,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.6 → 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