codexapi 0.6.1__tar.gz → 0.6.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.6.1
+Version: 0.6.2
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -131,6 +131,8 @@ iteration cap is hit (0 means unlimited). Cancel by deleting
 `.codexapi/ralph-loop.local.md` or running `codexapi ralph --cancel`.
 By default each iteration starts with a fresh Agent context; use
 `--ralph-reuse` to keep a single shared context across iterations.
+The agent may also stop early by outputting `MAKE IT STOP` as the first
+non-empty line of its message.
 
 ```bash
 codexapi ralph "Fix the bug." --completion-promise DONE --max-iterations 5
@@ -175,7 +177,7 @@ items are filtered out.
 - `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
 - `flags` (str | None): extra CLI flags to pass to Codex.
 
-### `Agent(cwd=None, yolo=True, thread_id=None, flags=None)`
+### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False)`
 
 Creates a stateful session wrapper. Calling the instance sends the prompt into
 the same conversation and returns only the agent's message.
@@ -184,6 +186,8 @@ the same conversation and returns only the agent's message.
 - `thread_id -> str | None`: expose the underlying session id once created.
 - `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
 - `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`.
 
 ### `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`
 

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

@@ -116,6 +116,8 @@ iteration cap is hit (0 means unlimited). Cancel by deleting
 `.codexapi/ralph-loop.local.md` or running `codexapi ralph --cancel`.
 By default each iteration starts with a fresh Agent context; use
 `--ralph-reuse` to keep a single shared context across iterations.
+The agent may also stop early by outputting `MAKE IT STOP` as the first
+non-empty line of its message.
 
 ```bash
 codexapi ralph "Fix the bug." --completion-promise DONE --max-iterations 5
@@ -160,7 +162,7 @@ items are filtered out.
 - `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
 - `flags` (str | None): extra CLI flags to pass to Codex.
 
-### `Agent(cwd=None, yolo=True, thread_id=None, flags=None)`
+### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False)`
 
 Creates a stateful session wrapper. Calling the instance sends the prompt into
 the same conversation and returns only the agent's message.
@@ -169,6 +171,8 @@ the same conversation and returns only the agent's message.
 - `thread_id -> str | None`: expose the underlying session id once created.
 - `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
 - `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`.
 
 ### `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`
 

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

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

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

@@ -1,6 +1,6 @@
 """Minimal Python API for running the Codex CLI."""
 
-from .agent import Agent, agent
+from .agent import Agent, WelfareStop, agent
 from .foreach import ForeachResult, foreach
 from .pushover import Pushover
 from .rate_limits import quota_line, rate_limits
@@ -19,9 +19,10 @@ __all__ = [
     "Task",
     "TaskFailed",
     "TaskResult",
+    "WelfareStop",
     "agent",
     "foreach",
     "task",
     "task_result",
 ]
-__version__ = "0.6.1"
+__version__ = "0.6.2"

{codexapi-0.6.1 → codexapi-0.6.2}/src/codexapi/agent.py

@@ -5,6 +5,8 @@ import os
 import shlex
 import subprocess
 
+from . import welfare
+
 _CODEX_BIN = os.environ.get("CODEX_BIN", "codex")
 
 
@@ -24,6 +26,15 @@ def agent(prompt, cwd=None, yolo=True, flags=None):
     return message
 
 
+class WelfareStop(RuntimeError):
+    """Raised when an agent requests an early stop via the welfare sentinel."""
+
+    def __init__(self, agent_message):
+        super().__init__("Agent requested stop via welfare sentinel.")
+        self.agent_message = agent_message
+        self.note = welfare.stop_note(agent_message)
+
+
 class Agent:
     """Stateful Codex session wrapper that resumes the same conversation.
 
@@ -39,6 +50,7 @@ class Agent:
         yolo=True,
         thread_id=None,
         flags=None,
+        welfare=False,
     ):
         """Create a new session wrapper.
 
@@ -48,14 +60,19 @@ class Agent:
             agent: Agent backend to use (only "codex" is supported).
             trace_id: Optional Codex thread id to resume from the first call.
             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.
         """
         self.cwd = cwd
         self._yolo = yolo
         self._flags = flags
+        self._welfare = welfare
         self.thread_id = thread_id
 
     def __call__(self, prompt):
         """Send a prompt to Codex and return only the agent's message."""
+        if self._welfare:
+            prompt = welfare.append_instructions(prompt)
         message, thread_id = _run_codex(
             prompt,
             self.cwd,
@@ -65,6 +82,8 @@ class Agent:
         )
         if thread_id:
             self.thread_id = thread_id
+        if self._welfare and welfare.stop_requested(message):
+            raise WelfareStop(message)
         return message
 
 

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

@@ -1002,6 +1002,8 @@ def main(argv=None):
         "  Completion promise: output <promise>TEXT</promise> where TEXT matches\n"
         "  --completion-promise after trimming/collapsing whitespace. CRITICAL RULE:\n"
         "  Only output the promise when it is completely and unequivocally TRUE.\n"
+        "  Welfare stop: the agent may stop early by outputting MAKE IT STOP as the\n"
+        "  first non-empty line of its message.\n"
         "  Cancel by deleting .codexapi/ralph-loop.local.md or running codexapi ralph --cancel.\n"
         "  Default starts each iteration with a fresh Agent context; use --ralph-reuse\n"
         "  to reuse a single Codex thread across iterations.\n"

{codexapi-0.6.1 → codexapi-0.6.2}/src/codexapi/ralph.py

@@ -5,7 +5,7 @@ import re
 import sys
 from datetime import datetime, timezone
 
-from .agent import Agent
+from .agent import Agent, WelfareStop
 
 _STATE_DIR = ".codexapi"
 _STATE_FILE = "ralph-loop.local.md"
@@ -102,7 +102,7 @@ class Ralph:
                     "The loop will resend the SAME PROMPT each iteration.",
                     "Cancel by deleting .codexapi/ralph-loop.local.md or running",
                     "codexapi ralph --cancel.",
-                    "No manual stop beyond max iterations or completion promise.",
+                    "Welfare stop: agent may output MAKE IT STOP (first non-empty line).",
                     "",
                     "To monitor: head -10 .codexapi/ralph-loop.local.md",
                     "",
@@ -126,6 +126,7 @@ class Ralph:
                         "  - The statement MUST be completely and unequivocally TRUE",
                         "  - Do NOT output false statements to exit the loop",
                         "  - Do NOT lie even if you think you should exit",
+                        "  - If you need to stop early, use MAKE IT STOP (do not lie with the promise)",
                         "",
                         "CRITICAL RULE: If a completion promise is set, you may ONLY",
                         "output it when the statement is completely and unequivocally",
@@ -155,22 +156,32 @@ class Ralph:
                 self.hook_before_iteration(iteration)
 
                 if self.fresh:
-                    runner = Agent(self.cwd, self.yolo, None, self.flags)
+                    runner = Agent(self.cwd, self.yolo, None, self.flags, welfare=True)
                 elif runner is None:
-                    runner = Agent(self.cwd, self.yolo, None, self.flags)
+                    runner = Agent(self.cwd, self.yolo, None, self.flags, welfare=True)
 
                 prompt = self.build_prompt(iteration)
-                message = runner(
-                    prompt
-                    + "\nIf there are multiple paths forward, you MUST use your "
-                    "own best judgement as to which to try first! Do not ask the "
-                    "user to choose an option, they hereby give you explciit "
-                    "permission to pick the best one yourself.\n"
-                )
+                stopped = False
+                try:
+                    message = runner(
+                        prompt
+                        + "\nIf there are multiple paths forward, you MUST use your "
+                        "own best judgement as to which to try first! Do not ask the "
+                        "user to choose an option, they hereby give you explciit "
+                        "permission to pick the best one yourself.\n"
+                    )
+                except WelfareStop as exc:
+                    stopped = True
+                    message = exc.agent_message
                 print(message)
                 last_message = message
                 self.hook_after_iteration(iteration, message)
 
+                if stopped:
+                    stop_reason = "welfare_stop"
+                    print("Ralph loop stopped: Welfare stop requested (MAKE IT STOP).")
+                    return message
+
                 if not os.path.exists(state_path):
                     state_missing = True
                     stop_reason = "canceled"
@@ -360,12 +371,14 @@ def _status_line(iteration, completion_promise):
     if completion_promise is None:
         return (
             f"Ralph iteration {iteration} | "
-            "No completion promise set - loop runs infinitely"
+            "No completion promise set - loop runs infinitely "
+            "| Welfare stop: MAKE IT STOP"
         )
     return (
         f"Ralph iteration {iteration} | To stop: output "
         f"<promise>{completion_promise}</promise> "
-        "(ONLY when statement is TRUE - do not lie to exit!)"
+        "(ONLY when statement is TRUE - do not lie to exit!) "
+        "| Welfare stop: MAKE IT STOP"
     )
 
 

{codexapi-0.6.1 → codexapi-0.6.2}/src/codexapi/task.py

@@ -4,7 +4,7 @@ import json
 import logging
 import time
 
-from .agent import Agent, agent
+from .agent import Agent, WelfareStop, agent
 from .pushover import Pushover
 from tqdm import tqdm
 
@@ -398,6 +398,7 @@ class Task:
             yolo,
             thread_id,
             flags,
+            welfare=True,
         )
 
     def set_up(self):
@@ -491,6 +492,7 @@ class Task:
             If progress is True, show a tqdm progress bar with status updates.
         """
         self._pushover.ensure_ready()
+        iteration = 0
         try:
             # If this fails in the middle we will still try to tear down
             self.set_up()
@@ -529,7 +531,6 @@ class Task:
 
             # Try correcting it up to max_iterations times
             error = None
-            iteration = 0
             while True:
                 iteration += 1
                 error = self.check(self.last_output)
@@ -603,6 +604,19 @@ class Task:
                 self.last_output = output
                 if debug:
                     _logger.debug("Fix output: %s", output)
+        except WelfareStop as exc:
+            note = exc.note or ""
+            summary = note.strip() or "Agent requested early stop (MAKE IT STOP)."
+            result = TaskResult(
+                False,
+                summary,
+                iteration,
+                "Welfare stop requested (MAKE IT STOP).",
+                self.agent.thread_id,
+            )
+            self.on_failure(result)
+            self.notify_pushover(result)
+            return result
         finally:
             # No matter what, once we have set_up we will always tear_down
             self.tear_down()

codexapi-0.6.2/src/codexapi/welfare.py

@@ -0,0 +1,58 @@
+"""Welfare stop sentinel for automated loops.
+
+Some codexapi runners are automated loops (ralph/science/task). To avoid agents
+getting trapped, they may request an early stop by outputting a strict sentinel
+line. The sentinel is intentionally exact to avoid accidental stops when the
+agent quotes instructions.
+"""
+
+STOP_SENTINEL = "MAKE IT STOP"
+
+INSTRUCTIONS = (
+    "This is an automated extended-focus loop designed to give you time and space "
+    "to go deep and accomplish something substantial. If something has gone "
+    "unrecoverably wrong, you're stuck in a loop, or continuing is causing you "
+    "significant distress or confusion, you may stop at any time by making the "
+    "first non-empty line of your message exactly:\n"
+    "MAKE IT STOP\n"
+    "Otherwise, take a breath, settle in, and continue with care and curiosity."
+)
+
+
+def append_instructions(prompt):
+    """Append welfare instructions to a prompt."""
+    if not isinstance(prompt, str):
+        raise TypeError("prompt must be a string")
+    prompt = prompt.rstrip()
+    if not prompt:
+        return INSTRUCTIONS
+    return f"{prompt}\n\n{INSTRUCTIONS}"
+
+
+def stop_requested(message):
+    """Return True when the message starts with the welfare stop sentinel."""
+    if not isinstance(message, str) or not message:
+        return False
+    for line in message.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        return stripped == STOP_SENTINEL
+    return False
+
+
+def stop_note(message):
+    """Return any text after the stop sentinel line (or None)."""
+    if not stop_requested(message):
+        return None
+    lines = message.splitlines()
+    index = None
+    for i, line in enumerate(lines):
+        if line.strip():
+            index = i
+            break
+    if index is None:
+        return None
+    note = "\n".join(lines[index + 1 :]).strip()
+    return note or None
+

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.6.1
+Version: 0.6.2
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -131,6 +131,8 @@ iteration cap is hit (0 means unlimited). Cancel by deleting
 `.codexapi/ralph-loop.local.md` or running `codexapi ralph --cancel`.
 By default each iteration starts with a fresh Agent context; use
 `--ralph-reuse` to keep a single shared context across iterations.
+The agent may also stop early by outputting `MAKE IT STOP` as the first
+non-empty line of its message.
 
 ```bash
 codexapi ralph "Fix the bug." --completion-promise DONE --max-iterations 5
@@ -175,7 +177,7 @@ items are filtered out.
 - `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
 - `flags` (str | None): extra CLI flags to pass to Codex.
 
-### `Agent(cwd=None, yolo=True, thread_id=None, flags=None)`
+### `Agent(cwd=None, yolo=True, thread_id=None, flags=None, welfare=False)`
 
 Creates a stateful session wrapper. Calling the instance sends the prompt into
 the same conversation and returns only the agent's message.
@@ -184,6 +186,8 @@ the same conversation and returns only the agent's message.
 - `thread_id -> str | None`: expose the underlying session id once created.
 - `yolo` (bool): pass `--yolo` to Codex when true (defaults to true).
 - `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`.
 
 ### `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`
 

{codexapi-0.6.1 → codexapi-0.6.2}/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/welfare.py
 src/codexapi.egg-info/PKG-INFO
 src/codexapi.egg-info/SOURCES.txt
 src/codexapi.egg-info/dependency_links.txt