codexapi 0.6.2__tar.gz → 0.6.4__tar.gz

{codexapi-0.6.2/src/codexapi.egg-info → codexapi-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.6.2
+Version: 0.6.4
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -126,6 +126,18 @@ codexapi run --thread-id THREAD_ID --print-thread-id "Continue where we left off
 
 Use `--no-yolo` to run Codex with `--full-auto` instead.
 
+Watch mode periodically ticks a long-running agent session with the current time
+and prints JSON status updates. The agent controls the loop by setting
+`continue` to true/false in its JSON response. Each tick expects JSON keys:
+`status` (one line), `continue` (bool), and optional `comments` (string). If the
+JSON is invalid, watch asks the agent once to retry before stopping with an
+error. When `~/.pushover` is configured, watch sends a notification when it
+stops.
+
+```bash
+codexapi watch 5 "Run the benchmark and wait for results."
+```
+
 Ralph loop mode repeats the same prompt until a completion promise or a max
 iteration cap is hit (0 means unlimited). Cancel by deleting
 `.codexapi/ralph-loop.local.md` or running `codexapi ralph --cancel`.
@@ -154,7 +166,8 @@ Optional Pushover notifications: create `~/.pushover` with two non-empty lines.
 Line 1 is your user or group key, line 2 is the app API token. When this file
 exists, Science will send a notification whenever it detects a new best result,
 including the metric values and percent improvement. Task runs will also send a
-✅/❌ notification with the task summary.
+✅/❌ notification with the task summary. Watch runs send a notification when the
+loop stops.
 
 Run a task file across a list file:
 
@@ -189,6 +202,14 @@ the same conversation and returns only the agent's message.
 - `welfare` (bool): when true, append welfare stop instructions to each prompt
   and raise `WelfareStop` if the agent outputs `MAKE IT STOP`.
 
+### `watch(minutes, prompt, cwd=None, yolo=True, flags=None) -> dict`
+
+Runs a long-lived agent session and periodically "ticks" it with the current
+local time and a reminder of `prompt`. Each tick expects JSON with keys:
+`status` (one line), `continue` (bool), and optional `comments` (string). If the
+JSON is invalid, watch asks the agent once to retry. The loop stops when
+`continue` is false and sends a Pushover notification (when configured).
+
 ### `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.

{codexapi-0.6.2 → codexapi-0.6.4}/README.md

@@ -111,6 +111,18 @@ codexapi run --thread-id THREAD_ID --print-thread-id "Continue where we left off
 
 Use `--no-yolo` to run Codex with `--full-auto` instead.
 
+Watch mode periodically ticks a long-running agent session with the current time
+and prints JSON status updates. The agent controls the loop by setting
+`continue` to true/false in its JSON response. Each tick expects JSON keys:
+`status` (one line), `continue` (bool), and optional `comments` (string). If the
+JSON is invalid, watch asks the agent once to retry before stopping with an
+error. When `~/.pushover` is configured, watch sends a notification when it
+stops.
+
+```bash
+codexapi watch 5 "Run the benchmark and wait for results."
+```
+
 Ralph loop mode repeats the same prompt until a completion promise or a max
 iteration cap is hit (0 means unlimited). Cancel by deleting
 `.codexapi/ralph-loop.local.md` or running `codexapi ralph --cancel`.
@@ -139,7 +151,8 @@ Optional Pushover notifications: create `~/.pushover` with two non-empty lines.
 Line 1 is your user or group key, line 2 is the app API token. When this file
 exists, Science will send a notification whenever it detects a new best result,
 including the metric values and percent improvement. Task runs will also send a
-✅/❌ notification with the task summary.
+✅/❌ notification with the task summary. Watch runs send a notification when the
+loop stops.
 
 Run a task file across a list file:
 
@@ -174,6 +187,14 @@ the same conversation and returns only the agent's message.
 - `welfare` (bool): when true, append welfare stop instructions to each prompt
   and raise `WelfareStop` if the agent outputs `MAKE IT STOP`.
 
+### `watch(minutes, prompt, cwd=None, yolo=True, flags=None) -> dict`
+
+Runs a long-lived agent session and periodically "ticks" it with the current
+local time and a reminder of `prompt`. Each tick expects JSON with keys:
+`status` (one line), `continue` (bool), and optional `comments` (string). If the
+JSON is invalid, watch asks the agent once to retry. The loop stops when
+`continue` is false and sends a Pushover notification (when configured).
+
 ### `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.

{codexapi-0.6.2 → codexapi-0.6.4}/pyproject.toml

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

{codexapi-0.6.2 → codexapi-0.6.4}/src/codexapi/__init__.py

@@ -7,6 +7,7 @@ from .rate_limits import quota_line, rate_limits
 from .ralph import Ralph
 from .science import Science
 from .task import Task, TaskFailed, TaskResult, task, task_result
+from .watch import watch
 
 __all__ = [
     "Agent",
@@ -24,5 +25,6 @@ __all__ = [
     "foreach",
     "task",
     "task_result",
+    "watch",
 ]
-__version__ = "0.6.2"
+__version__ = "0.6.4"

{codexapi-0.6.2 → codexapi-0.6.4}/src/codexapi/cli.py

@@ -19,6 +19,7 @@ from .science import Science
 from .task import DEFAULT_MAX_ITERATIONS, TaskFailed, task
 from .taskfile import TaskFile, load_task_file, task_def_uses_item
 from .rate_limits import quota_line
+from .watch import watch
 
 _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}"
@@ -1039,6 +1040,32 @@ def main(argv=None):
         "--flags",
         help="Additional raw CLI flags to pass to Codex (quoted as needed).",
     )
+
+    watch_parser = subparsers.add_parser(
+        "watch",
+        help="Periodically tick an agent for long-running work.",
+    )
+    watch_parser.add_argument(
+        "minutes",
+        type=int,
+        help="Tick interval in minutes (integer, >= 1).",
+    )
+    watch_parser.add_argument(
+        "prompt",
+        nargs="?",
+        help="Prompt to send. Use '-' or omit to read from stdin.",
+    )
+    watch_parser.add_argument("--cwd", help="Working directory for the Codex session.")
+    watch_parser.add_argument(
+        "--no-yolo",
+        action="store_false",
+        dest="yolo",
+        help="Disable --yolo and use --full-auto.",
+    )
+    watch_parser.add_argument(
+        "--flags",
+        help="Additional raw CLI flags to pass to Codex (quoted as needed).",
+    )
     run_parser.add_argument(
         "--thread-id",
         help="Resume an existing Codex thread id.",
@@ -1474,7 +1501,7 @@ def main(argv=None):
 
     prompt_source = None
     prompt = None
-    if args.command in ("run", "ralph"):
+    if args.command in ("run", "ralph", "watch"):
         prompt_source = args.prompt
     elif args.command == "science":
         prompt_source = args.task
@@ -1509,6 +1536,16 @@ def main(argv=None):
             args.ralph_fresh,
         )()
         return
+    if args.command == "watch":
+        if args.minutes < 1:
+            raise SystemExit("watch minutes must be >= 1.")
+        try:
+            watch(args.minutes, prompt, args.cwd, args.yolo, args.flags)
+        except KeyboardInterrupt:
+            raise SystemExit(130)
+        except Exception as exc:
+            raise SystemExit(str(exc) or "watch failed") from None
+        return
     if args.command == "task":
         if args.project:
             raise SystemExit("task --project already handled earlier.")

{codexapi-0.6.2 → codexapi-0.6.4}/src/codexapi/pushover.py

@@ -15,7 +15,7 @@ _PUSHOVER_URL = "https://api.pushover.net/1/messages.json"
 _MAX_MESSAGE = 1024
 
 _STARTUP_MESSAGE = (
-    "Pushover user and app keys read, notifications for task and science enabled."
+    "Pushover user and app keys read, notifications for task/science/watch enabled."
 )
 
 

codexapi-0.6.4/src/codexapi/watch.py

@@ -0,0 +1,279 @@
+"""Periodic watch loop for long-running Codex work.
+
+watch keeps a single Codex thread alive and periodically "ticks" it with the
+current time and a reminder of the original instructions. Each tick expects a
+small JSON status payload so the loop can decide whether to continue.
+"""
+
+import json
+import sys
+import time
+from datetime import datetime
+
+from .agent import Agent
+from .pushover import Pushover
+
+_JSON_INSTRUCTIONS = (
+    "Respond with JSON only (no markdown/backticks/extra text).\n"
+    "Return a single JSON object with keys:\n"
+    "  status: string (one line)\n"
+    "  continue: boolean\n"
+    "  comments: string (optional)\n"
+    "To stop this watch loop, set continue to false."
+)
+
+
+def watch(minutes, prompt, cwd=None, yolo=True, flags=None):
+    """Run a periodic watch loop.
+
+    Args:
+        minutes: Tick interval in whole minutes (>= 1).
+        prompt: The original instruction prompt.
+        cwd: Optional working directory for the Codex session.
+        yolo: Whether to pass --yolo to Codex.
+        flags: Additional raw CLI flags to pass to Codex.
+
+    Returns:
+        The last parsed JSON status object.
+    """
+    if not isinstance(minutes, int):
+        raise TypeError("minutes must be an integer")
+    if minutes < 1:
+        raise ValueError("minutes must be >= 1")
+    if not isinstance(prompt, str) or not prompt.strip():
+        raise ValueError("prompt must be a non-empty string")
+
+    interval = minutes * 60
+    session = Agent(cwd, yolo, None, flags)
+    pushover = Pushover()
+    pushover.ensure_ready()
+    title = _format_title(prompt)
+
+    last_sent = None
+    last_result = None
+    tick = 0
+
+    while True:
+        tick += 1
+        sent_at = time.monotonic()
+        elapsed = None if last_sent is None else sent_at - last_sent
+        last_sent = sent_at
+
+        now = datetime.now().astimezone().isoformat(timespec="seconds")
+        message = _build_tick_prompt(prompt, now, elapsed, tick)
+        output = session(message)
+        try:
+            result = _parse_status(output)
+        except ValueError as exc:
+            print(
+                f"[watch {tick} {now}] Invalid JSON from agent, requesting retry: {exc}",
+                file=sys.stderr,
+            )
+            retry_prompt = _json_retry_prompt(prompt, tick, str(exc), output)
+            retry_output = session(retry_prompt)
+            try:
+                result = _parse_status(retry_output)
+            except ValueError as exc2:
+                details = _format_json_double_failure(
+                    str(exc),
+                    output,
+                    str(exc2),
+                    retry_output,
+                )
+                pushover.send(title, f"Watch stopped (invalid JSON).\n{details}")
+                raise RuntimeError(
+                    "Agent was unable to provide valid JSON output after retry.\n"
+                    + details
+                ) from None
+        last_result = result
+        _print_status(now, elapsed, tick, result)
+
+        if not result["continue"]:
+            pushover.send(title, _format_stop_message(tick, now, result))
+            return last_result
+
+        next_tick = sent_at + interval
+        sleep_seconds = next_tick - time.monotonic()
+        if sleep_seconds > 0:
+            time.sleep(sleep_seconds)
+
+
+def _build_tick_prompt(prompt, now, elapsed, tick):
+    lines = [
+        f"Tick {tick}.",
+        f"Local time now: {now}",
+    ]
+    if elapsed is not None:
+        lines.append(
+            "Time since last tick: "
+            f"{_format_minutes_seconds(elapsed)} ({int(round(elapsed))}s)"
+        )
+    lines.extend(
+        [
+            "",
+            "A reminder: your instructions are:",
+            prompt.strip(),
+            "",
+            _JSON_INSTRUCTIONS,
+        ]
+    )
+    return "\n".join(lines).strip()
+
+
+def _format_minutes_seconds(seconds):
+    if seconds is None:
+        return ""
+    seconds = int(round(seconds))
+    if seconds < 0:
+        seconds = 0
+    minutes, seconds = divmod(seconds, 60)
+    return f"{minutes}m{seconds:02d}s"
+
+
+def _parse_status(output):
+    text = _maybe_strip_code_fence(str(output or "").strip())
+    data = _try_parse_json(text)
+    if data is None:
+        snippet = text[:200].replace("\n", "\\n")
+        raise ValueError(f"Invalid JSON response. Snippet: {snippet}")
+    if not isinstance(data, dict):
+        raise ValueError("Status JSON must be an object.")
+
+    status = data.get("status")
+    cont = data.get("continue")
+    comments = data.get("comments")
+
+    if not isinstance(status, str):
+        raise ValueError("Status JSON missing string 'status'.")
+    if not isinstance(cont, bool):
+        raise ValueError("Status JSON missing boolean 'continue'.")
+    if comments is None:
+        comments = ""
+    if not isinstance(comments, str):
+        raise ValueError("Status JSON missing string 'comments'.")
+
+    return {
+        "status": _single_line(status),
+        "continue": cont,
+        "comments": comments,
+    }
+
+
+def _json_retry_prompt(prompt, tick, error, output):
+    snippet = _snippet(output, 600)
+    lines = [
+        f"Your last message (tick {tick}) was not valid JSON.",
+        f"Error: {error}",
+        "",
+        "Here is your previous output (truncated):",
+        snippet,
+        "",
+        "Please try again and respond with JSON only.",
+        "",
+        "A reminder: your instructions are:",
+        prompt.strip(),
+        "",
+        _JSON_INSTRUCTIONS,
+    ]
+    return "\n".join(lines).strip()
+
+
+def _format_title(prompt):
+    text = _single_line(prompt).strip() or "codexapi watch"
+    if len(text) > 60:
+        text = text[:57] + "..."
+    return f"Watch: {text}"
+
+
+def _format_stop_message(tick, now, result):
+    status = _single_line(result.get("status") or "").strip()
+    header = f"Watch stopped at tick {tick} ({now})."
+    if status:
+        header = f"{header} {status}"
+    comments = (result.get("comments") or "").strip()
+    if comments:
+        return f"{header}\n{comments}"
+    return header
+
+
+def _format_json_failure(error, output):
+    snippet = _snippet(output, 600)
+    return "\n".join(
+        [
+            f"Error: {error}",
+            "",
+            "Last output (truncated):",
+            snippet,
+        ]
+    ).strip()
+
+
+def _format_json_double_failure(error_1, output_1, error_2, output_2):
+    first = _format_json_failure(error_1, output_1)
+    second = _format_json_failure(error_2, output_2)
+    return "\n".join(
+        [
+            "First attempt:",
+            first,
+            "",
+            "Second attempt:",
+            second,
+        ]
+    ).strip()
+
+
+def _snippet(text, limit):
+    text = str(text or "").strip()
+    if not text:
+        return "(empty)"
+    if len(text) <= limit:
+        return text
+    return text[:limit].rstrip() + "..."
+
+
+def _maybe_strip_code_fence(text):
+    if not text.startswith("```"):
+        return text
+    lines = text.splitlines()
+    if not lines:
+        return text
+    if lines[0].startswith("```"):
+        lines = lines[1:]
+    if lines and lines[-1].strip() == "```":
+        lines = lines[:-1]
+    return "\n".join(lines).strip()
+
+
+def _try_parse_json(text):
+    if not text:
+        return None
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+
+    start = text.find("{")
+    end = text.rfind("}")
+    if start == -1 or end == -1 or end <= start:
+        return None
+    try:
+        return json.loads(text[start : end + 1])
+    except json.JSONDecodeError:
+        return None
+
+
+def _single_line(text):
+    return " ".join(text.replace("\r", " ").split())
+
+
+def _print_status(now, elapsed, tick, result):
+    delta = ""
+    if elapsed is not None:
+        delta = f" +{_format_minutes_seconds(elapsed)}"
+    status = result.get("status", "")
+    cont = result.get("continue")
+    line = f"[watch {tick} {now}{delta}] {status} (continue={cont})".rstrip()
+    print(line)
+    comments = result.get("comments") or ""
+    if comments.strip():
+        print(comments.rstrip())

{codexapi-0.6.2 → codexapi-0.6.4/src/codexapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.6.2
+Version: 0.6.4
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -126,6 +126,18 @@ codexapi run --thread-id THREAD_ID --print-thread-id "Continue where we left off
 
 Use `--no-yolo` to run Codex with `--full-auto` instead.
 
+Watch mode periodically ticks a long-running agent session with the current time
+and prints JSON status updates. The agent controls the loop by setting
+`continue` to true/false in its JSON response. Each tick expects JSON keys:
+`status` (one line), `continue` (bool), and optional `comments` (string). If the
+JSON is invalid, watch asks the agent once to retry before stopping with an
+error. When `~/.pushover` is configured, watch sends a notification when it
+stops.
+
+```bash
+codexapi watch 5 "Run the benchmark and wait for results."
+```
+
 Ralph loop mode repeats the same prompt until a completion promise or a max
 iteration cap is hit (0 means unlimited). Cancel by deleting
 `.codexapi/ralph-loop.local.md` or running `codexapi ralph --cancel`.
@@ -154,7 +166,8 @@ Optional Pushover notifications: create `~/.pushover` with two non-empty lines.
 Line 1 is your user or group key, line 2 is the app API token. When this file
 exists, Science will send a notification whenever it detects a new best result,
 including the metric values and percent improvement. Task runs will also send a
-✅/❌ notification with the task summary.
+✅/❌ notification with the task summary. Watch runs send a notification when the
+loop stops.
 
 Run a task file across a list file:
 
@@ -189,6 +202,14 @@ the same conversation and returns only the agent's message.
 - `welfare` (bool): when true, append welfare stop instructions to each prompt
   and raise `WelfareStop` if the agent outputs `MAKE IT STOP`.
 
+### `watch(minutes, prompt, cwd=None, yolo=True, flags=None) -> dict`
+
+Runs a long-lived agent session and periodically "ticks" it with the current
+local time and a reminder of `prompt`. Each tick expects JSON with keys:
+`status` (one line), `continue` (bool), and optional `comments` (string). If the
+JSON is invalid, watch asks the agent once to retry. The loop stops when
+`continue` is false and sends a Pushover notification (when configured).
+
 ### `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.

{codexapi-0.6.2 → codexapi-0.6.4}/src/codexapi.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ src/codexapi/rate_limits.py
 src/codexapi/science.py
 src/codexapi/task.py
 src/codexapi/taskfile.py
+src/codexapi/watch.py
 src/codexapi/welfare.py
 src/codexapi.egg-info/PKG-INFO
 src/codexapi.egg-info/SOURCES.txt