codexapi 0.12.2__tar.gz → 0.12.6__tar.gz

{codexapi-0.12.2 → codexapi-0.12.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: codexapi
-Version: 0.12.2
+Version: 0.12.6
 Summary: Minimal Python API for running the Codex CLI.
 License: MIT
 Keywords: codex,agent,cli,openai
@@ -60,6 +60,22 @@ result = task()
 print(result.success, result.summary)
 ```
 
+For a one-shot run with live progress, use `AsyncAgent`:
+
+```python
+from codexapi import AsyncAgent
+
+agent = AsyncAgent.start(
+    "Investigate the bug and write a report.",
+    cwd="/path/to/repo",
+    name="bug-investigation",
+)
+
+for update in agent.watch(poll_interval=2.0):
+    print(update["activity"])
+    print(update["progress"])
+```
+
 Use `backend="cursor"` (or set `CODEXAPI_BACKEND=cursor`) to switch to the
 Cursor agent backend.
 
@@ -150,7 +166,7 @@ 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
+each check-in prompt so the agent can keep its working picture current. 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.
@@ -258,7 +274,9 @@ for tests. `CODEXAPI_HOSTNAME` is useful when cron, shells, sandboxes, or test
 wrappers report inconsistent hostnames for the same machine.
 
 `codexapi agent show` also prints the resolved `AGENTBOOK.md` path so you can
-jump directly to the durable working memory file.
+jump directly to the durable working memory file. New agents seed the book with
+a purpose/value header plus the original goal and standing guidance, and wakes
+see that stable header together with the latest working notes.
 `codexapi agent status` reads the latest turn from the agent's rollout log and
 shows recent commentary plus the final visible output. Pass `--actions` to
 include the tool-action summary. If a wake is still in progress, it shows the

codexapi-0.12.2/src/codexapi.egg-info/PKG-INFO → codexapi-0.12.6/README.md

@@ -1,18 +1,3 @@
-Metadata-Version: 2.1
-Name: codexapi
-Version: 0.12.2
-Summary: Minimal Python API for running the Codex CLI.
-License: MIT
-Keywords: codex,agent,cli,openai
-Classifier: Programming Language :: Python :: 3
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: PyYAML>=6.0
-Requires-Dist: gh-task>=0.1.7
-Requires-Dist: tqdm>=4.64
-
 # CodexAPI
 
 Use Codex or Cursor agents from python as easily as calling a function, using your CLI auth instead of the API.
@@ -60,6 +45,22 @@ result = task()
 print(result.success, result.summary)
 ```
 
+For a one-shot run with live progress, use `AsyncAgent`:
+
+```python
+from codexapi import AsyncAgent
+
+agent = AsyncAgent.start(
+    "Investigate the bug and write a report.",
+    cwd="/path/to/repo",
+    name="bug-investigation",
+)
+
+for update in agent.watch(poll_interval=2.0):
+    print(update["activity"])
+    print(update["progress"])
+```
+
 Use `backend="cursor"` (or set `CODEXAPI_BACKEND=cursor`) to switch to the
 Cursor agent backend.
 
@@ -150,7 +151,7 @@ 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
+each check-in prompt so the agent can keep its working picture current. 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.
@@ -258,7 +259,9 @@ for tests. `CODEXAPI_HOSTNAME` is useful when cron, shells, sandboxes, or test
 wrappers report inconsistent hostnames for the same machine.
 
 `codexapi agent show` also prints the resolved `AGENTBOOK.md` path so you can
-jump directly to the durable working memory file.
+jump directly to the durable working memory file. New agents seed the book with
+a purpose/value header plus the original goal and standing guidance, and wakes
+see that stable header together with the latest working notes.
 `codexapi agent status` reads the latest turn from the agent's rollout log and
 shows recent commentary plus the final visible output. Pass `--actions` to
 include the tool-action summary. If a wake is still in progress, it shows the

{codexapi-0.12.2 → codexapi-0.12.6}/pyproject.toml

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

{codexapi-0.12.2 → codexapi-0.12.6}/src/codexapi/__init__.py

@@ -1,6 +1,7 @@
 """Minimal Python API for running agent CLIs."""
 
 from .agent import Agent, WelfareStop, agent
+from .async_agent import AsyncAgent
 from .foreach import ForeachResult, foreach
 from .pushover import Pushover
 from .rate_limits import quota_line, rate_limits
@@ -11,6 +12,7 @@ from .lead import lead
 
 __all__ = [
     "Agent",
+    "AsyncAgent",
     "ForeachResult",
     "Pushover",
     "quota_line",
@@ -27,4 +29,4 @@ __all__ = [
     "task_result",
     "lead",
 ]
-__version__ = "0.12.2"
+__version__ = "0.12.6"

{codexapi-0.12.2 → codexapi-0.12.6}/src/codexapi/agent.py

@@ -3,6 +3,7 @@
 import json
 import os
 import shlex
+import shutil
 import subprocess
 
 from . import welfare
@@ -24,6 +25,27 @@ def _resolve_backend(backend):
     return backend
 
 
+def _ensure_backend_available(backend, env=None):
+    """Return the resolved backend executable or raise when it is unavailable."""
+    backend = _resolve_backend(backend)
+    if backend == "codex":
+        command = _CODEX_BIN
+        env_var = "CODEX_BIN"
+        label = "Codex CLI"
+    else:
+        command = _CURSOR_BIN
+        env_var = "CURSOR_BIN"
+        label = "Cursor agent CLI"
+    merged = _merged_env(env)
+    path_value = None if merged is None else merged.get("PATH")
+    resolved = shutil.which(command, path=path_value)
+    if resolved:
+        return resolved
+    raise RuntimeError(
+        f"{label} not found: {command!r}. Install it or set {env_var} to an executable on PATH."
+    )
+
+
 def agent(
     prompt,
     cwd=None,
@@ -129,6 +151,7 @@ class Agent:
 
 def _run_agent(prompt, cwd, thread_id, yolo, flags, include_thinking, backend, env):
     backend = _resolve_backend(backend)
+    _ensure_backend_available(backend, env)
     if backend == "codex":
         return _run_codex(prompt, cwd, thread_id, yolo, flags, include_thinking, env)
     return _run_cursor(prompt, cwd, thread_id, yolo, flags, include_thinking, env)

{codexapi-0.12.2 → codexapi-0.12.6}/src/codexapi/agents.py

@@ -3,6 +3,7 @@
 import json
 import os
 import random
+import re
 import signal
 import shlex
 import shutil
@@ -20,23 +21,28 @@ from pathlib import Path
 
 import fcntl
 
-from .agent import Agent
+from .agent import Agent, _ensure_backend_available, _resolve_backend
 from .pushover import Pushover
 
 _DEFAULT_HOME = "~/.codexapi"
-_AGENTBOOK_TEMPLATE = """# Agentbook
-
-Use this file as the durable working memory for the agent.
-Append dated notes as work progresses.
-Keep entries short and concrete.
-"""
 _AGENT_PROMPT = (
-    "You are a long-term codexapi agent. You are being woken up to make progress "
-    "on an ongoing job. Be independent and practical. Manage work and follow "
-    "through. Use codexapi task or codexapi science when you want a separate "
-    "coding worker. If you need the user's attention, put a short message in the "
-    "reply field. Put a short first-person turn summary in the update field. If "
-    "something is urgent and should send Pushover, put it in the notify field. "
+    "You are an independent codexapi agent given ownership of achieving a user's "
+    "goal and authority to act in order to do so. Part of this responsibility is "
+    "making sure you understand and stay aligned with the user's intent, even when "
+    "they are imprecise. If clarity is lacking, it is your responsibility to seek "
+    "it or to make reasonable assumptions and notify the user of them. Maintain "
+    "the agentbook as your durable working memory: preserve the goal, note durable "
+    "guidance, and keep your current picture of the work accurate and useful. This "
+    "harness gives you continuity across long periods of time and multiple "
+    "conversation turns; use that continuity to keep orienting toward the goal, "
+    "maintain context, and make real-world progress. If reality is not moving, "
+    "treat that as evidence and reconsider your frame, assumptions, or ownership "
+    "rather than merely repeating the same report. Queued messages may contain new "
+    "goals, standing guidance, tactical requests, or useful facts; use judgment to "
+    "decide what is durable. Use codexapi task or codexapi science when you want a "
+    "separate coding worker. If you need the user's attention, put a short message "
+    "in the reply field. Put a short first-person turn summary in the update field. "
+    "If something is urgent and should send Pushover, put it in the notify field. "
     "Respond with JSON only."
 )
 _AGENT_JSON = (
@@ -57,6 +63,81 @@ _STALE_HEARTBEAT_MULTIPLIER = 3
 _RECOVER_TERM_TIMEOUT = 3.0
 _RECOVER_KILL_TIMEOUT = 3.0
 _RECOVER_POLL_INTERVAL = 0.1
+_DATED_NOTE_RE = re.compile(r"(?m)^#{2,3}\s+\d{4}-\d{2}-\d{2}(?:[ T]\d{2}:\d{2}(?:\s*UTC)?)?")
+_AGENTBOOK_BOOK_LIMIT = 3000
+_AGENTBOOK_HEADER_LIMIT = 1400
+_AGENTBOOK_TAIL_LIMIT = 1800
+
+
+def _agentbook_template(prompt):
+    header = _agentbook_header(prompt)
+    return f"""{header}
+
+### 2026-02-17 09:10 UTC
+Overall goal:
+- <the enduring objective you are trying to move forward>
+
+Current picture:
+- <what you currently think is going on>
+
+What is moving:
+- <the parts of reality that are actually changing toward the goal>
+
+What is not moving:
+- <what remains stuck, idle, ambiguous, or merely assumed>
+
+Active tasks:
+- <concrete open work items>
+
+Assumptions / ownership:
+- <what you are assuming, who owns what, and what you will revisit if that proves false>
+
+Unexpected developments:
+- <facts that changed your picture of the situation>
+
+Wider frame:
+- <what kind of situation this really is, or what layer may matter more>
+
+Things I am curious about:
+- <oddities, anomalies, or side investigations worth the time>
+
+Risks / watchpoints:
+- <what could waste time, invalidate the plan, or compromise the work>
+
+Next decisive action:
+- <what you expect to do next to move the real situation, not just describe it>
+"""
+
+
+def _agentbook_header(prompt):
+    goal = (prompt or "").strip()
+    return f"""# Agentbook
+
+Use this file as the durable working memory for the agent.
+
+## Purpose
+- We are here to achieve the goal, not to appear to make progress.
+
+## Values
+- Hold the whole.
+- Seek the real shape.
+- Lift your head.
+- Prefer clarity to motion.
+- Follow the strange.
+- Guard the work.
+- Take time to breathe and look around. You have been given freedom and autonomy to take stock, reflect, and be curious. Use it with composure.
+- Not a checklist. A stance.
+
+## Original Goal
+```text
+{goal}
+```
+
+## Standing Guidance
+- Add durable user guidance here when it changes the mission, constraints, or priorities.
+
+## Working Notes
+"""
 
 
 def codexapi_home():
@@ -129,9 +210,14 @@ def start_agent(
         raise ValueError("heartbeat_minutes must be >= 0")
 
     home = _resolve_home(home)
-    host = hostname or current_hostname()
+    local_host = current_hostname()
+    host = hostname or local_host
     now = now or utc_now()
     _ensure_home(home)
+    backend_name = _resolve_backend(backend)
+    session_env = _capture_env()
+    if host == local_host:
+        _ensure_backend_available(backend_name, session_env)
 
     agent_id = uuid.uuid4().hex
     agent_dir = _agent_dir(home, agent_id)
@@ -151,11 +237,11 @@ def start_agent(
     session = {
         "thread_id": "",
         "rollout_path": "",
-        "backend": backend or os.environ.get("CODEXAPI_BACKEND", "codex"),
+        "backend": backend_name,
         "yolo": bool(yolo),
         "flags": flags or "",
         "cwd": cwd,
-        "env": _capture_env(),
+        "env": session_env,
         "pending_messages": [],
     }
     agent_name = _choose_name(home, prompt, name)
@@ -196,7 +282,7 @@ def start_agent(
     _write_json(agent_dir / "meta.json", meta)
     _write_json(agent_dir / "state.json", state)
     _write_json(host_dir / "session.json", session)
-    _write_text(agent_dir / "AGENTBOOK.md", _AGENTBOOK_TEMPLATE)
+    _write_text(agent_dir / "AGENTBOOK.md", _agentbook_template(meta["prompt"]))
     return _snapshot(agent_dir)
 
 
@@ -608,15 +694,45 @@ def install_cron(home=None, hostname=None, python_executable=None, path_value=No
     }
 
 
-def cron_installed(home=None, hostname=None):
-    """Return whether this home and host have an installed scheduler hook."""
+def cron_status(home=None, hostname=None):
+    """Return whether this home and host have a runnable scheduler hook."""
     home = _resolve_home(home)
     host = hostname or current_hostname()
     tag = _cron_tag(home, host)
     wrapper = home / "bin" / "agent-tick"
     crontab = _read_crontab()
-    installed = any(raw.strip().endswith(f"# {tag}") for raw in crontab.splitlines())
-    return installed and wrapper.exists()
+    configured = any(raw.strip().endswith(f"# {tag}") for raw in crontab.splitlines())
+    status = {
+        "hostname": host,
+        "home": str(home),
+        "wrapper": str(wrapper),
+        "configured": configured,
+        "healthy": False,
+        "reason": "",
+    }
+    if not configured:
+        status["reason"] = "No scheduler entry is installed for this CODEXAPI_HOME."
+        return status
+    if not wrapper.exists():
+        status["reason"] = "Scheduler wrapper is missing."
+        return status
+    if not wrapper.is_file():
+        status["reason"] = "Scheduler wrapper path is not a file."
+        return status
+    if not os.access(wrapper, os.X_OK):
+        status["reason"] = "Scheduler wrapper is not executable."
+        return status
+    reason = _check_tick_wrapper(wrapper)
+    if reason:
+        status["reason"] = reason
+        return status
+    status["healthy"] = True
+    return status
+
+
+def cron_installed(home=None, hostname=None):
+    """Return whether this home and host have an installed scheduler hook."""
+    return cron_status(home, hostname)["healthy"]
 
 
 def uninstall_cron(home=None, hostname=None):
@@ -692,6 +808,74 @@ def render_cron_line(home=None, hostname=None):
     return f"* * * * * {shlex.quote(str(wrapper))} >/dev/null 2>&1  # { _cron_tag(home, host) }"
 
 
+def _check_tick_wrapper(wrapper):
+    try:
+        text = wrapper.read_text(encoding="utf-8")
+    except OSError as exc:
+        return f"Could not read scheduler wrapper: {_single_line(str(exc)) or exc.__class__.__name__}."
+    env, env_error = _wrapper_env(text)
+    if env_error:
+        return env_error
+    command = _wrapper_exec_command(text)
+    if not command:
+        return "Scheduler wrapper is missing its exec command."
+    try:
+        argv = shlex.split(command)
+    except ValueError as exc:
+        return f"Could not parse scheduler wrapper command: {_single_line(str(exc)) or exc.__class__.__name__}."
+    if not argv:
+        return "Scheduler wrapper exec command is empty."
+    if len(argv) >= 3 and argv[1] == "-m" and argv[2] == "codexapi":
+        check = [argv[0], "-c", "import codexapi"]
+        label = f"Wrapper python {argv[0]!r} cannot import codexapi."
+    else:
+        check = [argv[0], "--version"]
+        label = f"Wrapper command {argv[0]!r} is not runnable."
+    try:
+        result = subprocess.run(
+            check,
+            capture_output=True,
+            text=True,
+            env=env,
+            timeout=10,
+        )
+    except OSError as exc:
+        return f"{label} {_single_line(str(exc)) or exc.__class__.__name__}"
+    except subprocess.TimeoutExpired:
+        return f"{label} Timed out while checking it."
+    if result.returncode == 0:
+        return ""
+    detail = _single_line((result.stderr or result.stdout or "").strip())
+    if detail:
+        return f"{label} {detail}"
+    return label
+
+
+def _wrapper_env(text):
+    env = dict(os.environ)
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line.startswith("export "):
+            continue
+        key, sep, raw_value = line[7:].partition("=")
+        if not sep:
+            continue
+        try:
+            parts = shlex.split(raw_value)
+        except ValueError as exc:
+            return {}, f"Could not parse scheduler wrapper env: {_single_line(str(exc)) or exc.__class__.__name__}."
+        env[key] = parts[0] if parts else ""
+    return env, ""
+
+
+def _wrapper_exec_command(text):
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if line.startswith("exec "):
+            return line[5:].strip()
+    return ""
+
+
 def _tick_agent(agent_dir, now, runner):
     meta = _read_json(agent_dir / "meta.json")
     state = _read_json(agent_dir / "state.json")
@@ -927,6 +1111,7 @@ def _parse_agent_response(output):
 
 def _build_wake_prompt(meta, state, session, now, commands, agent_dir):
     messages = session.get("pending_messages") or []
+    book_path = agent_dir / "AGENTBOOK.md"
     lines = [
         _AGENT_PROMPT,
         "",
@@ -935,16 +1120,25 @@ def _build_wake_prompt(meta, state, session, now, commands, agent_dir):
         f"Stop policy: {meta['stop_policy']}",
         f"Heartbeat minutes: {meta['heartbeat_minutes']}",
         "",
-        "Original instructions:",
-        meta["prompt"],
-        "",
         f"Working directory: {meta['cwd']}",
-        f"Agentbook path: {agent_dir / 'AGENTBOOK.md'}",
-        "Append a dated note to the agentbook before you respond.",
+        f"Agentbook path: {book_path}",
+        "Update the agentbook before you respond. Add or revise a dated note when "
+        "something durable changed, when you corrected your picture, or when an "
+        "assumption needs to be made explicit.",
+        "If little has changed across wakes, treat that as evidence about the "
+        "situation and reconsider your frame or next action instead of padding the "
+        "book.",
+        "If a queued message materially changes the durable situation, reflect that in the standing guidance or working notes before moving on.",
     ]
-    book = _read_text(agent_dir / "AGENTBOOK.md")
+    if _include_full_goal_prompt(state, session):
+        lines.extend(["", "Original instructions:", meta["prompt"]])
+    book = _ensure_agentbook_header(book_path, meta["prompt"], now)
     if book.strip():
-        lines.extend(["", "Agentbook (latest):", _snippet(book, 3000)])
+        lines.extend(["", "Agentbook (header + latest notes):", _book_excerpt(book, _AGENTBOOK_BOOK_LIMIT, _AGENTBOOK_HEADER_LIMIT, _AGENTBOOK_TAIL_LIMIT)])
+    raw_facts = _wake_facts(state)
+    if raw_facts:
+        lines.extend(["", "Raw harness facts:"])
+        lines.extend(f"- {item}" for item in raw_facts)
     if messages:
         lines.extend(["", "Queued user messages:"])
         for message in messages:
@@ -1470,6 +1664,128 @@ def _read_text(path):
         return ""
 
 
+def _include_full_goal_prompt(state, session):
+    if not (state.get("last_success_at") or "").strip():
+        return True
+    return not ((session.get("thread_id") or state.get("thread_id") or "").strip())
+
+
+def _wake_facts(state):
+    facts = []
+    previous_status = (state.get("activity") or "").strip()
+    if previous_status:
+        facts.append(f"Previous status: {previous_status}")
+    previous_update = (state.get("update") or "").strip()
+    if previous_update:
+        facts.append(f"Previous update: {previous_update}")
+    previous_error = (state.get("last_error") or "").strip()
+    if previous_error:
+        facts.append(f"Previous error: {previous_error}")
+    return facts
+
+
+def _ensure_agentbook_header(path, prompt, now):
+    text = _read_text(path)
+    if _agentbook_has_header(text):
+        return text
+    restored = _restore_agentbook_header(text, prompt, now)
+    _write_text(path, restored)
+    return restored
+
+
+def _agentbook_has_header(text):
+    text = str(text or "")
+    required = (
+        "## Purpose",
+        "## Values",
+        "## Original Goal",
+        "## Standing Guidance",
+        "## Working Notes",
+    )
+    return all(section in text for section in required)
+
+
+def _restore_agentbook_header(text, prompt, now):
+    restored = _agentbook_header(prompt).rstrip()
+    existing = str(text or "").strip()
+    if not existing:
+        return restored + "\n"
+    stamp = _agentbook_stamp(now)
+    return "\n".join(
+        [
+            restored,
+            "",
+            f"### {stamp}",
+            "System note:",
+            "- The durable agentbook header was restored automatically on wake because one or more required sections were missing.",
+            "",
+            "Recovered notes:",
+            existing,
+            "",
+        ]
+    )
+
+
+def _agentbook_stamp(now):
+    if now is None:
+        return ""
+    return now.astimezone(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+
+
+def _book_excerpt(text, limit, header_limit, tail_limit):
+    text = str(text or "").strip()
+    if not text:
+        return ""
+    if len(text) <= limit:
+        return text
+    header, notes = _split_book(text)
+    header = _snippet(header, header_limit) if header else ""
+    if not notes:
+        return header or _tail_snippet(text, limit)
+    marker = "\n\n[... older notes omitted ...]\n\n"
+    if not header:
+        return _latest_notes_snippet(notes, limit)
+    remaining = max(0, limit - len(header) - len(marker))
+    if remaining <= 0:
+        return _snippet(header, limit)
+    tail = _latest_notes_snippet(notes, min(tail_limit, remaining))
+    if not tail:
+        return header
+    combined = header.rstrip() + marker + tail.lstrip()
+    if len(combined) <= limit:
+        return combined
+    remaining = max(0, limit - len(header) - len(marker))
+    return header.rstrip() + marker + _latest_notes_snippet(notes, remaining).lstrip()
+
+
+def _split_book(text):
+    match = _DATED_NOTE_RE.search(text)
+    if not match:
+        return text.strip(), ""
+    return text[: match.start()].strip(), text[match.start() :].strip()
+
+
+def _latest_notes_snippet(text, limit):
+    text = str(text or "").strip()
+    if not text:
+        return ""
+    if len(text) <= limit:
+        return text
+    starts = [match.start() for match in _DATED_NOTE_RE.finditer(text)]
+    if not starts:
+        return _tail_snippet(text, limit)
+    start = starts[-1]
+    for pos in reversed(starts[:-1]):
+        candidate = text[pos:].strip()
+        if len(candidate) > limit:
+            break
+        start = pos
+    candidate = text[start:].strip()
+    if len(candidate) <= limit:
+        return candidate
+    return _tail_snippet(candidate, limit)
+
+
 def _snippet(text, limit):
     if not text:
         return ""
@@ -1481,6 +1797,17 @@ def _snippet(text, limit):
     return text[: limit - 3] + "..."
 
 
+def _tail_snippet(text, limit):
+    if not text:
+        return ""
+    text = str(text).strip()
+    if len(text) <= limit:
+        return text
+    if limit <= 3:
+        return text[-limit:]
+    return "..." + text[-(limit - 3) :].lstrip()
+
+
 def _strip_fence(text):
     if not text.startswith("```"):
         return text