Add science max-duration and final pushover status; bump v0.7.2

Author: yieldthought

README.md

@@ -160,17 +160,23 @@ codexapi ralph --cancel --cwd /path/to/project
 Science mode wraps a short task in a science prompt and runs it through the
 Ralph loop. It defaults to `--yolo` and expects progress notes in `SCIENCE.md`.
 Each iteration appends the agent output to `LOGBOOK.md` and the runner extracts
-any improved figures of merit for optional notifications.
+any improved figures of merit for optional notifications. You can also set
+`--max-duration` to stop after the current iteration once a time limit is hit.
+The default science wrapper also tells the agent to create/use a local git
+branch when in a repo and make local commits for worthwhile improvements, while
+never committing or resetting `LOGBOOK.md` or `SCIENCE.md`.
 
 ```bash
 codexapi science "hyper-optimize the kernel cycles"
 codexapi science --no-yolo "hyper-optimize the kernel cycles" --max-iterations 3
+codexapi science "hyper-optimize the kernel cycles" --max-duration 90m
 ```
 
 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
+including the metric values and percent improvement, plus a final run-end status.
+Task runs will also send a
 ✅/❌ notification with the task summary. Lead runs send a notification when the
 loop stops.
 

pyproject.toml

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

src/codexapi/__init__.py

@@ -27,4 +27,4 @@
     "task_result",
     "lead",
 ]
-__version__ = "0.7.1"
+__version__ = "0.7.2"

src/codexapi/cli.py

@@ -24,6 +24,7 @@
 _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}"
 )
+_DURATION_RE = re.compile(r"^\s*(\d+(?:\.\d+)?)([smhdSMHD]?)\s*$")
 _TAIL_BYTES = 256 * 1024
 _TAIL_MAX_BYTES = 4 * 1024 * 1024
 _TAIL_MIN_LINES = 200
@@ -92,6 +93,25 @@ def _read_prompt(prompt):
     return data
 
 
+def _parse_duration_seconds(value, flag_name):
+    if value is None:
+        return 0.0
+    text = str(value).strip()
+    if not text:
+        raise SystemExit(f"{flag_name} cannot be empty.")
+    match = _DURATION_RE.match(text)
+    if not match:
+        raise SystemExit(
+            f"{flag_name} must be a number with optional unit s/m/h/d (example: 90m)."
+        )
+    amount = float(match.group(1))
+    unit = (match.group(2) or "m").lower()
+    if amount < 0:
+        raise SystemExit(f"{flag_name} must be >= 0.")
+    multiplier = {"s": 1, "m": 60, "h": 3600, "d": 86400}[unit]
+    return amount * multiplier
+
+
 def _read_prompt_file(path):
     if not path or not str(path).strip():
         raise SystemExit("Prompt file path is empty.")
@@ -1026,6 +1046,8 @@ def main(argv=None):
         "Science mode (science command):\n"
         "  Wraps your short task in a science prompt and runs it via the Ralph loop.\n"
         "  Default uses --yolo. Use --no-yolo to run --full-auto instead.\n"
+        "  Optional --max-duration stops before starting the next iteration once\n"
+        "  the duration limit is reached (e.g. 90m, 2h, 45s; default unit is minutes).\n"
     )
     parser = argparse.ArgumentParser(
         prog="codexapi",
@@ -1255,6 +1277,13 @@ def main(argv=None):
         default=0,
         help="Max iterations for the loop (0 means unlimited).",
     )
+    science_parser.add_argument(
+        "--max-duration",
+        help=(
+            "Maximum loop runtime. Stops after the current iteration when reached. "
+            "Accepts s/m/h/d units (e.g. 90m, 2h, 45s); default unit is minutes."
+        ),
+    )
     science_parser.add_argument(
         "--cancel",
         action="store_true",
@@ -1440,6 +1469,8 @@ def main(argv=None):
                 )
             if args.max_iterations != 0:
                 raise SystemExit("--max-iterations is not allowed with --cancel.")
+            if args.max_duration:
+                raise SystemExit("--max-duration is not allowed with --cancel.")
             print(cancel_ralph_loop(args.cwd))
             return
         if args.ralph_fresh is None:
@@ -1579,6 +1610,7 @@ def main(argv=None):
     if args.command == "science":
         if args.max_iterations < 0:
             raise SystemExit("--max-iterations must be >= 0.")
+        max_duration_seconds = _parse_duration_seconds(args.max_duration, "--max-duration")
         Science(
             prompt,
             args.cwd,
@@ -1587,6 +1619,7 @@ def main(argv=None):
             args.max_iterations,
             args.completion_promise,
             args.ralph_fresh,
+            max_duration_seconds,
         )()
         return
     if args.command == "lead":

src/codexapi/science.py

@@ -3,6 +3,7 @@
 import json
 import os
 import sys
+import time
 from datetime import datetime, timezone
 
 from .agent import agent
@@ -29,7 +30,10 @@
     "Try your best and have fun with this one! If you "
     "think of several options, pick one and run with it - I will not be available "
     "to make decisions for you, I give you my full permission to explore and make "
-    "your own best judgement towards our goal! Remember to update SCIENCE.md. "
+    "your own best judgement towards our goal! If you are in a git repository, "
+    "create and use a local branch for this run. Make local commits for improvements "
+    "worth keeping, but never commit or reset LOGBOOK.md or SCIENCE.md. "
+    "Remember to update SCIENCE.md. "
     "Good hunting!"
 )
 _LOGBOOK_NAME = "LOGBOOK.md"
@@ -97,7 +101,10 @@ def __init__(
         max_iterations=0,
         completion_promise=None,
         fresh=True,
+        max_duration_seconds=0,
     ):
+        if max_duration_seconds < 0:
+            raise ValueError("max_duration_seconds must be >= 0")
         self._task = task.strip() if isinstance(task, str) else task
         prompt_a, prompt_b = _science_parts(task)
         prompt = f"{prompt_a}{prompt_b}"
@@ -117,11 +124,20 @@ def __init__(
         self._best_metrics = None
         self._run_title = None
         self._pushover = Pushover()
+        self._pushover_enabled = False
+        self._max_duration_seconds = float(max_duration_seconds)
+        self._loop_started_monotonic = None
+        self._duration_limit_hit = False
+        self._last_iteration = 0
 
     def hook_before_loop(self):
         super().hook_before_loop()
-        self._pushover.ensure_ready()
-        self._run_title = self._build_run_title()
+        self._loop_started_monotonic = time.monotonic()
+        self._pushover_enabled = self._pushover.ensure_ready()
+        if self._pushover_enabled:
+            self._run_title = self._build_run_title()
+        else:
+            self._run_title = _fallback_title(self._task)
 
     def build_prompt(self, iteration):
         if iteration <= 1:
@@ -131,8 +147,33 @@ def build_prompt(self, iteration):
 
     def hook_after_iteration(self, iteration, message):
         super().hook_after_iteration(iteration, message)
+        self._last_iteration = iteration
         self._append_logbook(iteration, message)
         self._extract_and_notify(message)
+        self._mark_duration_stop(iteration)
+
+    def hook_after_loop(self, last_message, stop_reason):
+        super().hook_after_loop(last_message, stop_reason)
+        if not self._pushover_enabled:
+            return
+        status = _format_final_status(
+            stop_reason,
+            self.max_iterations,
+            self.completion_promise,
+            self._duration_limit_hit,
+        )
+        lines = [
+            f"Science run ended: {status}",
+            f"Iterations completed: {self._last_iteration}",
+        ]
+        if self._best_metrics:
+            summary = _single_line(self._best_metrics.get("summary", "")).strip()
+            metrics_text = _format_metrics(self._best_metrics.get("metrics") or [])
+            if summary:
+                lines.append(f"Best summary: {summary}")
+            if metrics_text:
+                lines.append(f"Best metrics: {metrics_text}")
+        self._pushover.send(self._run_title, "\n".join(lines))
 
     def hook_new_best(self, result):
         super().hook_new_best(result)
@@ -186,6 +227,25 @@ def _build_run_title(self):
             title = _fallback_title(self._task)
         return title
 
+    def _mark_duration_stop(self, iteration):
+        if self._duration_limit_hit:
+            return
+        if self._max_duration_seconds <= 0:
+            return
+        if self._loop_started_monotonic is None:
+            return
+        elapsed = time.monotonic() - self._loop_started_monotonic
+        if elapsed < self._max_duration_seconds:
+            return
+        self._duration_limit_hit = True
+        self.max_iterations = (
+            iteration if self.max_iterations == 0 else min(self.max_iterations, iteration)
+        )
+        print(
+            "Science loop: Max duration reached; "
+            "stopping after the current iteration."
+        )
+
 
 
 def _build_metrics_prompt(task, message, previous_best):
@@ -300,3 +360,30 @@ def _fallback_title(task):
 
 def _warn(message):
     print(message, file=sys.stderr)
+
+
+def _format_final_status(
+    stop_reason,
+    max_iterations,
+    completion_promise,
+    duration_limit_hit,
+):
+    if stop_reason == "max_iterations":
+        if duration_limit_hit:
+            return "max duration reached"
+        return f"max iterations reached ({max_iterations})"
+    if stop_reason == "promise":
+        if completion_promise:
+            return f"completion promise met ({completion_promise})"
+        return "completion promise met"
+    if stop_reason == "welfare_stop":
+        return "agent requested welfare stop"
+    if stop_reason == "canceled":
+        return "loop canceled"
+    if stop_reason == "interrupted":
+        return "interrupted"
+    if stop_reason == "error":
+        return "stopped due to error"
+    if stop_reason:
+        return _single_line(stop_reason)
+    return "finished"

tests/test_science.py

@@ -0,0 +1,97 @@
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from codexapi.science import Science, _science_parts
+
+
+class _FakePushover:
+    def __init__(self, enabled):
+        self.enabled = enabled
+        self.sent = []
+
+    def ensure_ready(self, announce=True):
+        return self.enabled
+
+    def send(self, title, message):
+        self.sent.append((title, message))
+        return True
+
+
+class _TestScience(Science):
+    def _append_logbook(self, iteration, message):
+        return None
+
+    def _extract_and_notify(self, message):
+        return None
+
+    def _build_run_title(self):
+        return "test-run"
+
+
+class _FakeAgent:
+    calls = 0
+
+    def __init__(
+        self,
+        cwd=None,
+        yolo=True,
+        thread_id=None,
+        flags=None,
+        welfare=False,
+        include_thinking=False,
+    ):
+        pass
+
+    def __call__(self, prompt):
+        _FakeAgent.calls += 1
+        return f"message {_FakeAgent.calls}"
+
+
+class ScienceTests(unittest.TestCase):
+    def test_science_prompt_includes_git_commit_guidance(self):
+        _prompt_a, prompt_b = _science_parts("improve performance")
+        self.assertIn("create and use a local branch", prompt_b)
+        self.assertIn("never commit or reset LOGBOOK.md or SCIENCE.md", prompt_b)
+
+    def test_max_duration_stops_after_current_iteration(self):
+        _FakeAgent.calls = 0
+        with tempfile.TemporaryDirectory() as tmpdir:
+            runner = _TestScience(
+                "improve performance",
+                cwd=tmpdir,
+                max_duration_seconds=60,
+            )
+            runner._pushover = _FakePushover(enabled=False)
+            with patch("codexapi.ralph.Agent", _FakeAgent):
+                with patch("codexapi.science.time.monotonic", side_effect=[0, 30, 61]):
+                    runner()
+        self.assertEqual(_FakeAgent.calls, 2)
+        self.assertTrue(runner._duration_limit_hit)
+        self.assertEqual(runner._last_iteration, 2)
+
+    def test_final_pushover_update_sent_when_enabled(self):
+        _FakeAgent.calls = 0
+        with tempfile.TemporaryDirectory() as tmpdir:
+            runner = _TestScience(
+                "improve performance",
+                cwd=tmpdir,
+                max_iterations=1,
+            )
+            fake_pushover = _FakePushover(enabled=True)
+            runner._pushover = fake_pushover
+            with patch("codexapi.ralph.Agent", _FakeAgent):
+                runner()
+        self.assertEqual(len(fake_pushover.sent), 1)
+        title, message = fake_pushover.sent[0]
+        self.assertEqual(title, "test-run")
+        self.assertIn("Science run ended: max iterations reached (1)", message)
+        self.assertIn("Iterations completed: 1", message)
+
+
+if __name__ == "__main__":
+    unittest.main()