codexapi 0.6.8__tar.gz → 0.7.1__tar.gz

{codexapi-0.6.8/src/codexapi.egg-info → codexapi-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.6.8
+Version: 0.7.1
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -130,17 +130,32 @@ 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`.
 
-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:
+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
+setting `continue` to true/false in its JSON response. Each check-in 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
+JSON is invalid, lead asks the agent once to retry before stopping with an
+error. When `~/.pushover` is configured, lead sends a notification when it
 stops.
 
+Lead mode also uses a leadbook file as the agent's working page. By default this
+is `LEADBOOK.md` in the working directory. The leadbook content is injected into
+each check-in prompt and must be updated before the agent responds. Use
+`--leadbook PATH` to point at a different file, or `--no-leadbook` to disable.
+Use `-f/--prompt-file` to read the prompt from a file.
+If the leadbook does not exist, lead creates it with a template.
+
+```bash
+codexapi lead 5 "Run the benchmark and wait for results."
+
+Run without waiting between check-ins:
+
 ```bash
-codexapi watch 5 "Run the benchmark and wait for results."
+codexapi lead 0 "Do a rapid triage pass and report."
+```
 ```
 
 Ralph loop mode repeats the same prompt until a completion promise or a max
@@ -171,7 +186,7 @@ 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. Watch runs send a notification when the
+✅/❌ notification with the task summary. Lead runs send a notification when the
 loop stops.
 
 Run a task file across a list file:
@@ -185,7 +200,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.
@@ -194,8 +209,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.
@@ -206,15 +222,20 @@ 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.
 
-### `watch(minutes, prompt, cwd=None, yolo=True, flags=None) -> dict`
+### `lead(minutes, prompt, cwd=None, yolo=True, flags=None, leadbook=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:
+Runs a long-lived agent session and periodically checks in with the current
+local time and a reminder of `prompt`. Each check-in 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
+JSON is invalid, lead asks the agent once to retry. The loop stops when
 `continue` is false and sends a Pushover notification (when configured).
 
+Lead also injects the leadbook content into each prompt. By default it uses
+`LEADBOOK.md` in the working directory. Pass `leadbook=False` to disable or a
+path string to override the location.
+
 ### `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.
@@ -287,6 +308,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.6.8 → codexapi-0.7.1}/README.md

@@ -115,17 +115,32 @@ 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`.
 
-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:
+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
+setting `continue` to true/false in its JSON response. Each check-in 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
+JSON is invalid, lead asks the agent once to retry before stopping with an
+error. When `~/.pushover` is configured, lead sends a notification when it
 stops.
 
+Lead mode also uses a leadbook file as the agent's working page. By default this
+is `LEADBOOK.md` in the working directory. The leadbook content is injected into
+each check-in prompt and must be updated before the agent responds. Use
+`--leadbook PATH` to point at a different file, or `--no-leadbook` to disable.
+Use `-f/--prompt-file` to read the prompt from a file.
+If the leadbook does not exist, lead creates it with a template.
+
+```bash
+codexapi lead 5 "Run the benchmark and wait for results."
+
+Run without waiting between check-ins:
+
 ```bash
-codexapi watch 5 "Run the benchmark and wait for results."
+codexapi lead 0 "Do a rapid triage pass and report."
+```
 ```
 
 Ralph loop mode repeats the same prompt until a completion promise or a max
@@ -156,7 +171,7 @@ 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. Watch runs send a notification when the
+✅/❌ notification with the task summary. Lead runs send a notification when the
 loop stops.
 
 Run a task file across a list file:
@@ -170,7 +185,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.
@@ -179,8 +194,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.
@@ -191,15 +207,20 @@ 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.
 
-### `watch(minutes, prompt, cwd=None, yolo=True, flags=None) -> dict`
+### `lead(minutes, prompt, cwd=None, yolo=True, flags=None, leadbook=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:
+Runs a long-lived agent session and periodically checks in with the current
+local time and a reminder of `prompt`. Each check-in 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
+JSON is invalid, lead asks the agent once to retry. The loop stops when
 `continue` is false and sends a Pushover notification (when configured).
 
+Lead also injects the leadbook content into each prompt. By default it uses
+`LEADBOOK.md` in the working directory. Pass `leadbook=False` to disable or a
+path string to override the location.
+
 ### `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.
@@ -272,6 +293,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.6.8 → codexapi-0.7.1}/pyproject.toml

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

{codexapi-0.6.8 → codexapi-0.7.1}/src/codexapi/__init__.py

@@ -7,7 +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
+from .lead import lead
 
 __all__ = [
     "Agent",
@@ -25,6 +25,6 @@ __all__ = [
     "foreach",
     "task",
     "task_result",
-    "watch",
+    "lead",
 ]
-__version__ = "0.6.8"
+__version__ = "0.7.1"

{codexapi-0.6.8 → codexapi-0.7.1}/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.6.8 → codexapi-0.7.1}/src/codexapi/cli.py

@@ -19,7 +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
+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}"
@@ -92,6 +92,19 @@ def _read_prompt(prompt):
     return data
 
 
+def _read_prompt_file(path):
+    if not path or not str(path).strip():
+        raise SystemExit("Prompt file path is empty.")
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            data = handle.read()
+    except FileNotFoundError:
+        raise SystemExit(f"Prompt file not found: {path}") from None
+    if not data.strip():
+        raise SystemExit(f"Prompt file is empty: {path}")
+    return data
+
+
 def _single_line(text):
     if not text:
         return ""
@@ -1040,29 +1053,48 @@ 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.",
+    )
 
-    watch_parser = subparsers.add_parser(
-        "watch",
-        help="Periodically tick an agent for long-running work.",
+    lead_parser = subparsers.add_parser(
+        "lead",
+        help="Periodically check in to lead long-running work.",
     )
-    watch_parser.add_argument(
+    lead_parser.add_argument(
         "minutes",
         type=int,
-        help="Tick interval in minutes (integer, >= 1).",
+        help="Check-in interval in minutes (integer, >= 0).",
     )
-    watch_parser.add_argument(
+    lead_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(
+    lead_parser.add_argument(
+        "-f",
+        "--prompt-file",
+        help="Read the lead prompt from a file.",
+    )
+    lead_parser.add_argument("--cwd", help="Working directory for the Codex session.")
+    lead_parser.add_argument(
+        "--leadbook",
+        help="Path to the leadbook file (default: LEADBOOK.md in cwd).",
+    )
+    lead_parser.add_argument(
+        "--no-leadbook",
+        action="store_true",
+        help="Disable leadbook injection and checks.",
+    )
+    lead_parser.add_argument(
         "--no-yolo",
         action="store_false",
         dest="yolo",
         help="Disable --yolo and use --full-auto.",
     )
-    watch_parser.add_argument(
+    lead_parser.add_argument(
         "--flags",
         help="Additional raw CLI flags to pass to Codex (quoted as needed).",
     )
@@ -1517,11 +1549,16 @@ def main(argv=None):
 
     prompt_source = None
     prompt = None
-    if args.command in ("run", "ralph", "watch"):
-        prompt_source = args.prompt
+    if args.command in ("run", "ralph", "lead"):
+        if args.command == "lead" and args.prompt_file:
+            if args.prompt is not None:
+                raise SystemExit("lead --prompt-file cannot be used with a prompt arg.")
+            prompt = _read_prompt_file(args.prompt_file)
+        else:
+            prompt_source = args.prompt
     elif args.command == "science":
         prompt_source = args.task
-    if args.command != "task":
+    if args.command != "task" and prompt is None:
         prompt = _read_prompt(prompt_source)
     exit_code = 0
     message = None
@@ -1552,15 +1589,18 @@ def main(argv=None):
             args.ralph_fresh,
         )()
         return
-    if args.command == "watch":
-        if args.minutes < 1:
-            raise SystemExit("watch minutes must be >= 1.")
+    if args.command == "lead":
+        if args.minutes < 0:
+            raise SystemExit("lead minutes must be >= 0.")
         try:
-            watch(args.minutes, prompt, args.cwd, args.yolo, args.flags)
+            if args.no_leadbook and args.leadbook:
+                raise SystemExit("--leadbook and --no-leadbook are mutually exclusive.")
+            leadbook = False if args.no_leadbook else args.leadbook
+            lead(args.minutes, prompt, args.cwd, args.yolo, args.flags, leadbook)
         except KeyboardInterrupt:
             raise SystemExit(130)
         except Exception as exc:
-            raise SystemExit(str(exc) or "watch failed") from None
+            raise SystemExit(str(exc) or "lead failed") from None
         return
     if args.command == "task":
         if args.project:
@@ -1602,12 +1642,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)