codexapi 0.6.2__tar.gz → 0.6.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.6.2
+Version: 0.6.3
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -126,6 +126,14 @@ 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.
+
+```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`.
@@ -189,6 +197,13 @@ 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 `comments` (string). The loop stops
+when `continue` is false.
+
 ### `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.3}/README.md

@@ -111,6 +111,14 @@ 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.
+
+```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`.
@@ -174,6 +182,13 @@ 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 `comments` (string). The loop stops
+when `continue` is false.
+
 ### `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.3}/pyproject.toml

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

{codexapi-0.6.2 → codexapi-0.6.3}/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.3"

{codexapi-0.6.2 → codexapi-0.6.3}/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,14 @@ 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)
+        return
     if args.command == "task":
         if args.project:
             raise SystemExit("task --project already handled earlier.")

codexapi-0.6.3/src/codexapi/watch.py

@@ -0,0 +1,180 @@
+"""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 time
+from datetime import datetime
+
+from .agent import Agent
+
+_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\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)
+
+    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)
+        result = _parse_status(output)
+        last_result = result
+        _print_status(now, elapsed, tick, result)
+
+        if not result["continue"]:
+            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 _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.3/src/codexapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.6.2
+Version: 0.6.3
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -126,6 +126,14 @@ 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.
+
+```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`.
@@ -189,6 +197,13 @@ 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 `comments` (string). The loop stops
+when `continue` is false.
+
 ### `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.3}/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