Release v0.10.0

Author: yieldthought

README.md

@@ -158,13 +158,22 @@ codexapi agent whoami
 codexapi agent install-cron
 ```
 
+If you skip `install-cron`, `codexapi agent start` warns on stderr because
+background wakes will not run until the scheduler hook is installed.
+When `gh` is installed and authenticated, `agent start` also captures a
+background-safe `GH_TOKEN` automatically if your shell did not already export
+`GH_TOKEN` or `GITHUB_TOKEN`.
+
 Start a goal-directed agent that decides for itself when it is done:
 
 ```bash
 codexapi agent start --name ci-fixer \
   "Watch CI, fix failing tests, open or update a PR, and stop when the work is done."
 ```
 
+Add `--wait` if you want `start` to block for the first local wake instead of
+just scheduling it.
+
 Start a persistent watcher that keeps running until you stop it:
 
 ```bash
@@ -182,9 +191,12 @@ codexapi agent show ci-fixer
 codexapi agent read ci-fixer
 codexapi agent book ci-fixer
 codexapi agent send ci-fixer "Prefer the smallest safe fix."
+codexapi agent send --wait ci-fixer "Reply now if you can handle this immediately."
 codexapi agent wake ci-fixer
+codexapi agent wake --wait ci-fixer
 codexapi agent pause ci-fixer
 codexapi agent resume ci-fixer
+codexapi agent resume --wait ci-fixer
 codexapi agent cancel ci-fixer
 codexapi agent delete ci-fixer
 ```

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codexapi"
-version = "0.9.0"
+version = "0.10.0"
 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.9.0"
+__version__ = "0.10.0"

src/codexapi/agents.py

@@ -412,6 +412,17 @@ 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."""
+    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()
+
+
 def uninstall_cron(home=None, hostname=None):
     """Remove the cron entry for this home and host."""
     home = _resolve_home(home)
@@ -915,13 +926,31 @@ def _resolve_cwd(cwd):
 
 def _capture_env():
     env = {}
-    for key in ("PATH", "VIRTUAL_ENV"):
-        value = os.environ.get(key)
-        if value:
-            env[key] = value
+    for key, value in os.environ.items():
+        if key in ("CODEXAPI_AGENT_ID", "CODEXAPI_AGENT_NAME", "CODEXAPI_AGENT_PARENT_ID"):
+            continue
+        env[key] = value
+    if not (env.get("GH_TOKEN") or env.get("GITHUB_TOKEN")):
+        gh_token = _gh_auth_token()
+        if gh_token:
+            env["GH_TOKEN"] = gh_token
     return env
 
 
+def _gh_auth_token():
+    """Return the active gh auth token when available."""
+    if shutil.which("gh") is None:
+        return ""
+    result = subprocess.run(
+        ["gh", "auth", "token"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return ""
+    return (result.stdout or "").strip()
+
+
 def _parent_identity(home, parent_ref):
     """Return the resolved parent agent id and name, if any."""
     if parent_ref is not None and str(parent_ref).strip():

src/codexapi/cli.py

@@ -3,6 +3,7 @@
 import os
 import re
 import select
+import shlex
 import shutil
 import subprocess
 import sys
@@ -17,6 +18,7 @@
 from .agents import (
     codexapi_home,
     control_agent,
+    cron_installed as agent_cron_installed,
     current_hostname,
     delete_agent as delete_managed_agent,
     install_cron as install_agent_cron,
@@ -194,6 +196,39 @@ def _print_managed_agent_identity():
     print(f"Home: {codexapi_home()}")
 
 
+def _agent_install_cron_command():
+    parts = []
+    home = os.environ.get("CODEXAPI_HOME", "").strip()
+    host = os.environ.get("CODEXAPI_HOSTNAME", "").strip()
+    if home:
+        parts.append(f"CODEXAPI_HOME={shlex.quote(home)}")
+    if host:
+        parts.append(f"CODEXAPI_HOSTNAME={shlex.quote(host)}")
+    parts.extend(["codexapi", "agent", "install-cron"])
+    return " ".join(parts)
+
+
+def _warn_agent_scheduler_missing():
+    try:
+        installed = agent_cron_installed()
+    except Exception as exc:
+        print(
+            "Warning: could not verify whether the codexapi agent scheduler hook is installed.",
+            file=sys.stderr,
+        )
+        print(f"Reason: {exc}", file=sys.stderr)
+        print(f"Install it with: {_agent_install_cron_command()}", file=sys.stderr)
+        return
+    if installed:
+        return
+    print(
+        "Warning: no codexapi agent scheduler hook is installed for this CODEXAPI_HOME. "
+        "Background agent wakes will not run until you install it.",
+        file=sys.stderr,
+    )
+    print(f"Install it with: {_agent_install_cron_command()}", file=sys.stderr)
+
+
 def _send_reply_info(agent_ref, message_id):
     """Return the matching run reply for one sent message, if already delivered."""
     shown = show_managed_agent(agent_ref)
@@ -1401,7 +1436,7 @@ def main(argv=None):
 
     agent_start = agent_subparsers.add_parser(
         "start",
-        help="Create a durable agent.",
+        help="Create a durable agent and return immediately unless --wait is set.",
     )
     agent_start.add_argument(
         "prompt",
@@ -1445,6 +1480,11 @@ def main(argv=None):
         "--flags",
         help="Additional raw CLI flags to pass to the backend.",
     )
+    agent_start.add_argument(
+        "--wait",
+        action="store_true",
+        help="Wait for the first local wake to finish instead of just scheduling it.",
+    )
 
     agent_subparsers.add_parser(
         "list",
@@ -1481,21 +1521,32 @@ def main(argv=None):
 
     agent_send = agent_subparsers.add_parser(
         "send",
-        help="Queue a message for an agent.",
+        help="Queue a message for an agent and return immediately unless --wait is set.",
     )
     agent_send.add_argument("agent_ref", help="Agent id, unique prefix, or name.")
     agent_send.add_argument("message", help="Message to queue.")
     agent_send.add_argument("--author", help="Author label for the message.")
+    agent_send.add_argument(
+        "--wait",
+        action="store_true",
+        help="Wait for a local wake after queueing the message.",
+    )
 
     for subcommand, help_text in (
-        ("wake", "Request an extra wake for an agent."),
+        ("wake", "Request an extra wake for an agent and return immediately unless --wait is set."),
         ("pause", "Pause an agent."),
-        ("resume", "Resume a paused agent."),
+        ("resume", "Resume a paused agent and return immediately unless --wait is set."),
         ("cancel", "Cancel an agent."),
     ):
         subparser = agent_subparsers.add_parser(subcommand, help=help_text)
         subparser.add_argument("agent_ref", help="Agent id, unique prefix, or name.")
         subparser.add_argument("--author", help="Author label for the command.")
+        if subcommand in ("wake", "resume"):
+            subparser.add_argument(
+                "--wait",
+                action="store_true",
+                help="Wait for a local wake after queueing the command.",
+            )
 
     agent_delete = agent_subparsers.add_parser(
         "delete",
@@ -1834,6 +1885,10 @@ def main(argv=None):
                 args.yolo,
                 args.flags,
             )
+            result["waited"] = bool(args.wait)
+            if args.wait:
+                result["nudge"] = nudge_agent(result["id"])
+            _warn_agent_scheduler_missing()
             print(json.dumps(result, indent=2, sort_keys=True))
             return
         if args.agent_command == "list":
@@ -1855,18 +1910,32 @@ def main(argv=None):
             return
         if args.agent_command == "send":
             result = send_agent(args.agent_ref, args.message, args.author)
-            result["nudge"] = nudge_agent(args.agent_ref)
-            reply_info = _send_reply_info(args.agent_ref, result["id"])
-            if reply_info:
-                result.update(reply_info)
+            result["waited"] = bool(args.wait)
+            if args.wait:
+                result["nudge"] = nudge_agent(args.agent_ref)
+                reply_info = _send_reply_info(args.agent_ref, result["id"])
+                if reply_info:
+                    result.update(reply_info)
+            print(json.dumps(result, indent=2, sort_keys=True))
+            return
+        if args.agent_command in ("wake", "resume"):
+            result = control_agent(
+                args.agent_ref,
+                args.agent_command,
+                args.author,
+            )
+            result["waited"] = bool(args.wait)
+            if args.wait:
+                result["nudge"] = nudge_agent(args.agent_ref)
             print(json.dumps(result, indent=2, sort_keys=True))
             return
-        if args.agent_command in ("wake", "pause", "resume", "cancel"):
+        if args.agent_command in ("pause", "cancel"):
             result = control_agent(
                 args.agent_ref,
                 args.agent_command,
                 args.author,
             )
+            result["waited"] = False
             result["nudge"] = nudge_agent(args.agent_ref)
             print(json.dumps(result, indent=2, sort_keys=True))
             return