codexapi 0.7.0__tar.gz → 0.7.2__tar.gz

{codexapi-0.7.0/src/codexapi.egg-info → codexapi-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.7.0
+Version: 0.7.2
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -130,6 +130,7 @@ codexapi run --thread-id THREAD_ID --print-thread-id "Continue where we left off
 ```
 
 Use `--no-yolo` to run Codex with `--full-auto` instead.
+Use `--include-thinking` to return all agent messages joined together for `codexapi run`.
 
 Lead mode periodically checks in on a long-running agent session with the
 current time and prints JSON status updates. The agent controls the loop by
@@ -174,17 +175,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.
 
@@ -199,7 +206,7 @@ codexapi foreach list.txt task.yaml --retry-all
 
 ## API
 
-### `agent(prompt, cwd=None, yolo=True, flags=None) -> str`
+### `agent(prompt, cwd=None, yolo=True, flags=None, include_thinking=False) -> str`
 
 Runs a single Codex turn and returns only the agent's message. Any reasoning
 items are filtered out.
@@ -208,8 +215,9 @@ items are filtered out.
 - `cwd` (str | PathLike | None): working directory for the Codex session.
 - `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
 - `flags` (str | None): extra CLI flags to pass to Codex.
+- `include_thinking` (bool): when true, return all agent messages joined.
 
-### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False)`
+### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False, include_thinking=False)`
 
 Creates a stateful session wrapper. Calling the instance sends the prompt into
 the same conversation and returns only the agent's message.
@@ -220,6 +228,7 @@ the same conversation and returns only the agent's message.
 - `flags` (str | None): extra CLI flags to pass to Codex.
 - `welfare` (bool): when true, append welfare stop instructions to each prompt
   and raise `WelfareStop` if the agent outputs `MAKE IT STOP`.
+- `include_thinking` (bool): when true, return all agent messages joined.
 
 ### `lead(minutes, prompt, cwd=None, yolo=True, flags=None, leadbook=None) -> dict`
 
@@ -305,6 +314,7 @@ Simple result object returned by `foreach()`.
 ## Behavior notes
 
 - Uses `codex exec --json` and parses JSONL events for `agent_message` items.
+- Returns the last `agent_message` by default; set `include_thinking=True` to join all messages.
 - Automatically passes `--skip-git-repo-check` so it can run outside a git repo.
 - Passes `--yolo` by default (use `--no-yolo` or `yolo=False` for `--full-auto`).
 - Raises `RuntimeError` if Codex exits non-zero or returns no agent message.

{codexapi-0.7.0 → codexapi-0.7.2}/README.md

@@ -115,6 +115,7 @@ codexapi run --thread-id THREAD_ID --print-thread-id "Continue where we left off
 ```
 
 Use `--no-yolo` to run Codex with `--full-auto` instead.
+Use `--include-thinking` to return all agent messages joined together for `codexapi run`.
 
 Lead mode periodically checks in on a long-running agent session with the
 current time and prints JSON status updates. The agent controls the loop by
@@ -159,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.
 
@@ -184,7 +191,7 @@ codexapi foreach list.txt task.yaml --retry-all
 
 ## API
 
-### `agent(prompt, cwd=None, yolo=True, flags=None) -> str`
+### `agent(prompt, cwd=None, yolo=True, flags=None, include_thinking=False) -> str`
 
 Runs a single Codex turn and returns only the agent's message. Any reasoning
 items are filtered out.
@@ -193,8 +200,9 @@ items are filtered out.
 - `cwd` (str | PathLike | None): working directory for the Codex session.
 - `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
 - `flags` (str | None): extra CLI flags to pass to Codex.
+- `include_thinking` (bool): when true, return all agent messages joined.
 
-### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False)`
+### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False, include_thinking=False)`
 
 Creates a stateful session wrapper. Calling the instance sends the prompt into
 the same conversation and returns only the agent's message.
@@ -205,6 +213,7 @@ the same conversation and returns only the agent's message.
 - `flags` (str | None): extra CLI flags to pass to Codex.
 - `welfare` (bool): when true, append welfare stop instructions to each prompt
   and raise `WelfareStop` if the agent outputs `MAKE IT STOP`.
+- `include_thinking` (bool): when true, return all agent messages joined.
 
 ### `lead(minutes, prompt, cwd=None, yolo=True, flags=None, leadbook=None) -> dict`
 
@@ -290,6 +299,7 @@ Simple result object returned by `foreach()`.
 ## Behavior notes
 
 - Uses `codex exec --json` and parses JSONL events for `agent_message` items.
+- Returns the last `agent_message` by default; set `include_thinking=True` to join all messages.
 - Automatically passes `--skip-git-repo-check` so it can run outside a git repo.
 - Passes `--yolo` by default (use `--no-yolo` or `yolo=False` for `--full-auto`).
 - Raises `RuntimeError` if Codex exits non-zero or returns no agent message.

{codexapi-0.7.0 → codexapi-0.7.2}/pyproject.toml

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

{codexapi-0.7.0 → codexapi-0.7.2}/src/codexapi/__init__.py

@@ -27,4 +27,4 @@ __all__ = [
     "task_result",
     "lead",
 ]
-__version__ = "0.7.0"
+__version__ = "0.7.2"

{codexapi-0.7.0 → codexapi-0.7.2}/src/codexapi/agent.py

@@ -10,7 +10,7 @@ from . import welfare
 _CODEX_BIN = os.environ.get("CODEX_BIN", "codex")
 
 
-def agent(prompt, cwd=None, yolo=True, flags=None):
+def agent(prompt, cwd=None, yolo=True, flags=None, include_thinking=False):
     """Run a single Codex turn and return only the agent's message.
 
     Args:
@@ -18,11 +18,14 @@ def agent(prompt, cwd=None, yolo=True, flags=None):
         cwd: Optional working directory for the Codex session.
         yolo: Whether to pass --yolo to Codex.
         flags: Additional raw CLI flags to pass to Codex.
+        include_thinking: When true, return all agent messages joined together.
 
     Returns:
         The agent's visible response text with reasoning traces removed.
     """
-    message, _thread_id = _run_codex(prompt, cwd, None, yolo, flags)
+    message, _thread_id = _run_codex(
+        prompt, cwd, None, yolo, flags, include_thinking
+    )
     return message
 
 
@@ -51,6 +54,7 @@ class Agent:
         thread_id=None,
         flags=None,
         welfare=False,
+        include_thinking=False,
     ):
         """Create a new session wrapper.
 
@@ -62,11 +66,13 @@ class Agent:
             flags: Additional raw CLI flags to pass to Codex.
             welfare: When true, append welfare stop instructions to each prompt
                 and raise WelfareStop if the agent outputs MAKE IT STOP.
+            include_thinking: When true, return all agent messages joined together.
         """
         self.cwd = cwd
         self._yolo = yolo
         self._flags = flags
         self._welfare = welfare
+        self._include_thinking = include_thinking
         self.thread_id = thread_id
 
     def __call__(self, prompt):
@@ -79,6 +85,7 @@ class Agent:
             self.thread_id,
             self._yolo,
             self._flags,
+            self._include_thinking,
         )
         if thread_id:
             self.thread_id = thread_id
@@ -87,7 +94,7 @@ class Agent:
         return message
 
 
-def _run_codex(prompt, cwd, thread_id, yolo, flags):
+def _run_codex(prompt, cwd, thread_id, yolo, flags, include_thinking):
     """Invoke the Codex CLI and return the message plus thread id (if any)."""
     command = [
         _CODEX_BIN,
@@ -124,10 +131,10 @@ def _run_codex(prompt, cwd, thread_id, yolo, flags):
             msg = f"{msg}\n{stderr}"
         raise RuntimeError(msg)
 
-    return _parse_jsonl(result.stdout)
+    return _parse_jsonl(result.stdout, include_thinking)
 
 
-def _parse_jsonl(output):
+def _parse_jsonl(output, include_thinking):
     """Extract agent messages and the latest thread id from Codex JSONL output."""
     thread_id = None
     messages = []
@@ -161,4 +168,6 @@ def _parse_jsonl(output):
             "Codex returned no agent message. Raw output:\n" + fallback
         )
 
-    return "\n\n".join(messages), thread_id
+    if include_thinking:
+        return "\n\n".join(messages), thread_id
+    return messages[-1], thread_id

{codexapi-0.7.0 → codexapi-0.7.2}/src/codexapi/cli.py

@@ -24,6 +24,7 @@ from .lead import lead
 _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",
@@ -1053,6 +1075,11 @@ def main(argv=None):
         "--flags",
         help="Additional raw CLI flags to pass to Codex (quoted as needed).",
     )
+    run_parser.add_argument(
+        "--include-thinking",
+        action="store_true",
+        help="Return all agent messages joined together.",
+    )
 
     lead_parser = subparsers.add_parser(
         "lead",
@@ -1250,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",
@@ -1435,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:
@@ -1574,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,
@@ -1582,6 +1619,7 @@ def main(argv=None):
             args.max_iterations,
             args.completion_promise,
             args.ralph_fresh,
+            max_duration_seconds,
         )()
         return
     if args.command == "lead":
@@ -1637,12 +1675,15 @@ def main(argv=None):
                 args.yolo,
                 args.thread_id,
                 args.flags,
+                include_thinking=args.include_thinking,
             )
             message = session(prompt)
             if args.print_thread_id:
                 print(f"thread_id={session.thread_id}", file=sys.stderr)
         else:
-            message = agent(prompt, args.cwd, args.yolo, args.flags)
+            message = agent(
+                prompt, args.cwd, args.yolo, args.flags, args.include_thinking
+            )
 
     if message is not None:
         print(message)

{codexapi-0.7.0 → codexapi-0.7.2}/src/codexapi/ralph.py

@@ -41,6 +41,7 @@ class Ralph:
         self.max_iterations = max_iterations
         self.completion_promise = completion_promise
         self.fresh = fresh
+        self.include_thinking = True
 
     def hook_before_loop(self):
         """Hook called once before the loop starts."""
@@ -156,9 +157,23 @@ class Ralph:
                 self.hook_before_iteration(iteration)
 
                 if self.fresh:
-                    runner = Agent(self.cwd, self.yolo, None, self.flags, welfare=True)
+                    runner = Agent(
+                        self.cwd,
+                        self.yolo,
+                        None,
+                        self.flags,
+                        welfare=True,
+                        include_thinking=self.include_thinking,
+                    )
                 elif runner is None:
-                    runner = Agent(self.cwd, self.yolo, None, self.flags, welfare=True)
+                    runner = Agent(
+                        self.cwd,
+                        self.yolo,
+                        None,
+                        self.flags,
+                        welfare=True,
+                        include_thinking=self.include_thinking,
+                    )
 
                 prompt = self.build_prompt(iteration)
                 stopped = False

{codexapi-0.7.0 → codexapi-0.7.2}/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 @@ _SCIENCE_TEMPLATE_B = (
     "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 @@ class Science(Ralph):
         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}"
@@ -110,17 +117,27 @@ class Science(Ralph):
             completion_promise,
             fresh,
         )
+        self.include_thinking = True
         self._prompt_a = prompt_a
         self._prompt_b = prompt_b
         self._logbook_path = _logbook_path(cwd)
         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:
@@ -130,8 +147,33 @@ class Science(Ralph):
 
     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)
@@ -185,6 +227,25 @@ class Science(Ralph):
             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):
@@ -299,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"

{codexapi-0.7.0 → codexapi-0.7.2/src/codexapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.7.0
+Version: 0.7.2
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -130,6 +130,7 @@ codexapi run --thread-id THREAD_ID --print-thread-id "Continue where we left off
 ```
 
 Use `--no-yolo` to run Codex with `--full-auto` instead.
+Use `--include-thinking` to return all agent messages joined together for `codexapi run`.
 
 Lead mode periodically checks in on a long-running agent session with the
 current time and prints JSON status updates. The agent controls the loop by
@@ -174,17 +175,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.
 
@@ -199,7 +206,7 @@ codexapi foreach list.txt task.yaml --retry-all
 
 ## API
 
-### `agent(prompt, cwd=None, yolo=True, flags=None) -> str`
+### `agent(prompt, cwd=None, yolo=True, flags=None, include_thinking=False) -> str`
 
 Runs a single Codex turn and returns only the agent's message. Any reasoning
 items are filtered out.
@@ -208,8 +215,9 @@ items are filtered out.
 - `cwd` (str | PathLike | None): working directory for the Codex session.
 - `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
 - `flags` (str | None): extra CLI flags to pass to Codex.
+- `include_thinking` (bool): when true, return all agent messages joined.
 
-### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False)`
+### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False, include_thinking=False)`
 
 Creates a stateful session wrapper. Calling the instance sends the prompt into
 the same conversation and returns only the agent's message.
@@ -220,6 +228,7 @@ the same conversation and returns only the agent's message.
 - `flags` (str | None): extra CLI flags to pass to Codex.
 - `welfare` (bool): when true, append welfare stop instructions to each prompt
   and raise `WelfareStop` if the agent outputs `MAKE IT STOP`.
+- `include_thinking` (bool): when true, return all agent messages joined.
 
 ### `lead(minutes, prompt, cwd=None, yolo=True, flags=None, leadbook=None) -> dict`
 
@@ -305,6 +314,7 @@ Simple result object returned by `foreach()`.
 ## Behavior notes
 
 - Uses `codex exec --json` and parses JSONL events for `agent_message` items.
+- Returns the last `agent_message` by default; set `include_thinking=True` to join all messages.
 - Automatically passes `--skip-git-repo-check` so it can run outside a git repo.
 - Passes `--yolo` by default (use `--no-yolo` or `yolo=False` for `--full-auto`).
 - Raises `RuntimeError` if Codex exits non-zero or returns no agent message.

{codexapi-0.7.0 → codexapi-0.7.2}/src/codexapi.egg-info/SOURCES.txt

@@ -21,4 +21,5 @@ src/codexapi.egg-info/dependency_links.txt
 src/codexapi.egg-info/entry_points.txt
 src/codexapi.egg-info/requires.txt
 src/codexapi.egg-info/top_level.txt
+tests/test_science.py
 tests/test_task_progress.py

codexapi-0.7.2/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()