Improve queued command UX for agents

yieldthought · yieldthought · commit 14d38bf7cc36 · 2026-03-15T17:05:04.000+01:00
diff --git a/README.md b/README.md
@@ -213,10 +213,16 @@ codexapi agent delete ci-fixer
 `codexapi agent resume` can reopen a `done` agent. Sending to a `done` or
 `canceled` agent still triggers a one-off wake on the next tick so you can get
 a reply without putting the agent back into continuous heartbeat mode.
+For local-owned agents, `send`, `wake`, and `resume` now also nudge an
+immediate non-blocking wake even without `--wait`; `--wait` only changes
+whether the CLI blocks for completion.
 `codexapi agent recover` is for a different failure mode: a local wake that is
 still marked `running` but has stopped making rollout progress. `agent list`,
 `agent show`, and `agent status` now surface stale running wakes, and `recover`
 terminates the stuck local wake, marks it recoverable, and queues a fresh one.
+`agent list` also surfaces queued operator intent for local commands, so a
+paused agent with a queued `resume` shows as `resuming` with separate queued
+message and queued command counts.
 
 Create a child agent explicitly:
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codexapi"
-version = "0.12.1"
+version = "0.12.2"
 description = "Minimal Python API for running the Codex CLI."
 readme = "README.md"
 requires-python = ">=3.8"
diff --git a/src/codexapi/__init__.py b/src/codexapi/__init__.py
@@ -27,4 +27,4 @@
     "task_result",
     "lead",
 ]
-__version__ = "0.12.1"
+__version__ = "0.12.2"
diff --git a/src/codexapi/agents.py b/src/codexapi/agents.py
@@ -230,6 +230,8 @@ def show_agent(agent_ref, home=None):
     snapshot["state"] = _read_json(agent_dir / "state.json")
     snapshot["state"]["child_ids"] = snapshot["child_ids"]
     snapshot["state"]["unread_message_count"] = snapshot["unread_message_count"]
+    snapshot["state"]["pending_command_count"] = snapshot["pending_command_count"]
+    snapshot["state"]["pending_commands"] = snapshot["pending_commands"]
     snapshot["state"]["run_lock_held"] = snapshot["run_lock_held"]
     snapshot["state"]["last_event_at"] = snapshot["last_event_at"]
     snapshot["state"]["stale"] = snapshot["stale"]
@@ -256,7 +258,8 @@ def status_agent(agent_ref, home=None, include_actions=False):
     result = {
         "id": snapshot["id"],
         "name": snapshot["name"],
-        "agent_status": snapshot["status"],
+        "agent_status": snapshot["display_status"],
+        "state_status": snapshot["status"],
         "thread_id": session.get("thread_id") or snapshot.get("thread_id") or "",
         "rollout_path": str(rollout_path) if rollout_path else "",
         "turn_id": "",
@@ -273,6 +276,9 @@ def status_agent(agent_ref, home=None, include_actions=False):
         "stale": snapshot["stale"],
         "stale_after_seconds": snapshot["stale_after_seconds"],
         "stale_for_seconds": snapshot["stale_for_seconds"],
+        "pending_command_count": snapshot["pending_command_count"],
+        "pending_commands": snapshot["pending_commands"],
+        "queued_message_count": snapshot["unread_message_count"],
     }
     if rollout_path is None or not rollout_path.exists():
         return result
@@ -1097,13 +1103,17 @@ def _snapshot(agent_dir, child_map=None):
     state = _read_json(agent_dir / "state.json")
     session = _read_session(agent_dir)
     runtime = _agent_runtime(agent_dir, meta, state, session)
+    queued = _queued_commands(agent_dir)
+    queued_controls = [item for item in queued if item.get("kind") != "send"]
+    queued_kinds = [item.get("kind") or "" for item in queued_controls if item.get("kind")]
     if child_map is None:
         child_ids = _child_map(agent_dir.parents[1]).get(meta["id"], [])
     else:
         child_ids = child_map.get(meta["id"], [])
     unread = int(state.get("unread_message_count") or 0) + len(
-        _queued_send_commands(agent_dir)
+        [item for item in queued if item.get("kind") == "send"]
     )
+    status = state.get("status") or ""
     return {
         "id": meta["id"],
         "name": meta["name"],
@@ -1114,13 +1124,21 @@ def _snapshot(agent_dir, child_map=None):
         "cwd": meta["cwd"],
         "stop_policy": meta["stop_policy"],
         "heartbeat_minutes": meta["heartbeat_minutes"],
-        "status": state.get("status") or "",
+        "status": status,
+        "display_status": _display_status(
+            status,
+            queued_kinds,
+            runtime["run_lock_held"],
+            runtime["stale"],
+        ),
         "thread_id": state.get("thread_id") or "",
         "last_wake_at": state.get("last_wake_at") or "",
         "last_success_at": state.get("last_success_at") or "",
         "next_wake_at": state.get("next_wake_at") or "",
         "wake_requested_at": state.get("wake_requested_at") or "",
         "unread_message_count": unread,
+        "pending_command_count": len(queued_controls),
+        "pending_commands": queued_kinds,
         "input_tokens": int(state.get("input_tokens") or 0),
         "output_tokens": int(state.get("output_tokens") or 0),
         "total_tokens": int(state.get("total_tokens") or 0),
@@ -1554,7 +1572,29 @@ def _usage_int(value):
     return None
 
 
-def _queued_send_commands(agent_dir):
+def _display_status(status, pending_commands, run_lock_held, stale):
+    """Return a user-facing status that includes queued control intent."""
+    state = str(status or "")
+    commands = [str(kind or "") for kind in pending_commands or [] if kind]
+    if stale:
+        return "stale"
+    if commands:
+        last = commands[-1]
+        if last == "resume" and state in ("paused", "done"):
+            return "resuming"
+        if last == "pause" and state in ("ready", "error", "running"):
+            return "pausing"
+        if last == "cancel" and state != "canceled":
+            return "canceling"
+        if last == "wake" and state in ("ready", "error"):
+            return "waking"
+    if run_lock_held and state == "running":
+        return "running"
+    return state or ""
+
+
+def _queued_commands(agent_dir, kind=None):
+    """Return queued command payloads from commands/new."""
     queued = []
     new_dir = agent_dir / "commands" / "new"
     if not new_dir.exists():
@@ -1566,11 +1606,17 @@ def _queued_send_commands(agent_dir):
             payload = _read_json(path)
         except (FileNotFoundError, json.JSONDecodeError):
             continue
-        if payload.get("kind") == "send":
-            queued.append(payload)
+        payload_kind = payload.get("kind") or ""
+        if kind and payload_kind != kind:
+            continue
+        queued.append(payload)
     return queued
 
 
+def _queued_send_commands(agent_dir):
+    return _queued_commands(agent_dir, "send")
+
+
 def _has_new_commands(agent_dir):
     new_dir = agent_dir / "commands" / "new"
     if not new_dir.exists():
diff --git a/src/codexapi/cli.py b/src/codexapi/cli.py
@@ -158,20 +158,21 @@ def _print_managed_agent_list(items):
     if not items:
         print("No agents.")
         return
-    print("ID       STAT     POL  HOST         UNR TOKENS  TOK/H   NEXT REPO         NAME")
+    print("ID       STAT      POL  HOST         QMSG QCMD TOKENS  TOK/H   NEXT REPO         NAME")
     for item in items:
         ident = item["id"][:8]
-        status = _truncate_head(item["status"] or "-", 8)
+        status = _truncate_head(item.get("display_status") or item.get("status") or "-", 9)
         policy = _truncate_head(_policy_label(item.get("stop_policy")), 4)
         host = _truncate_head(item["hostname"] or "-", 12)
-        unread = str(item["unread_message_count"])
+        queued_messages = str(item["unread_message_count"])
+        queued_commands = str(int(item.get("pending_command_count") or 0))
         tokens = _format_token_total(item["total_tokens"])
         tok_h = _format_token_rate(item.get("avg_tokens_per_hour"))
         next_wake = _truncate_head(_next_wake_label(item), 6)
         repo = _truncate_head(_repo_label(item.get("cwd")), 12)
         name = item["name"]
         print(
-            f"{ident:<8} {status:<8} {policy:<4} {host:<12} {unread:>3} {tokens:>6} {tok_h:>7} {next_wake:>6} {repo:<12} {name}"
+            f"{ident:<8} {status:<9} {policy:<4} {host:<12} {queued_messages:>4} {queued_commands:>4} {tokens:>6} {tok_h:>7} {next_wake:>6} {repo:<12} {name}"
         )
 
 
@@ -196,6 +197,7 @@ def _print_managed_agent_read(result):
 def _print_managed_agent_status(result, include_actions=False):
     print(f"{result['name']} [{result['agent_status'] or '-'}]")
     print(f"ID: {result['id']}")
+    print(f"State: {result.get('state_status') or '-'}")
     print(f"Thread: {result.get('thread_id') or '-'}")
     print(f"Turn: {result.get('turn_id') or '-'} [{result.get('turn_state') or '-'}]")
     print(f"Started: {result.get('started_at') or '-'}")
@@ -204,6 +206,8 @@ def _print_managed_agent_status(result, include_actions=False):
     print(f"Rollout: {result.get('rollout_path') or '-'}")
     print(f"Last event: {result.get('last_event_at') or '-'}")
     print(f"Stale: {_stale_text(result)}")
+    print(f"Queued messages: {result.get('queued_message_count') or 0}")
+    print(f"Pending commands: {_pending_commands_text(result.get('pending_commands'))}")
     progress = result.get("progress") or []
     print("Progress:")
     if not progress:
@@ -310,20 +314,22 @@ def _send_reply_info(agent_ref, message_id):
 def _print_managed_agent_show(result):
     meta = result["meta"]
     state = result["state"]
-    print(f"{meta['name']} [{state.get('status') or '-'}]")
+    print(f"{meta['name']} [{result.get('display_status') or state.get('status') or '-'}]")
     print(f"ID: {meta['id']}")
     print(f"Host: {meta['hostname']}")
     print(f"Created: {meta['created_at']} by {meta['created_by']}")
     print(f"Parent: {_related_label(result.get('parent'))}")
     print(f"Children: {_children_label(result.get('children'))}")
     print(
-        f"Policy: {meta['stop_policy']}  Heartbeat: {meta['heartbeat_minutes']}m  Unread: {result['unread_message_count']}"
+        f"Policy: {meta['stop_policy']}  Heartbeat: {meta['heartbeat_minutes']}m  Qmsg: {result['unread_message_count']}  Qcmd: {result.get('pending_command_count') or 0}"
     )
     print(f"CWD: {meta['cwd']}")
     print(f"Agentbook: {result.get('agentbook_path') or '-'}")
+    print(f"State: {state.get('status') or '-'}")
     print(f"Thread: {state.get('thread_id') or '-'}")
     print(f"Last event: {result.get('last_event_at') or '-'}")
     print(f"Stale: {_stale_text(result)}")
+    print(f"Pending commands: {_pending_commands_text(result.get('pending_commands'))}")
     print(
         "Tokens: "
         f"{_format_token_total(state.get('total_tokens'))} total "
@@ -416,12 +422,15 @@ def _policy_label(stop_policy):
 
 def _next_wake_label(item):
     status = item.get("status") or ""
+    display_status = item.get("display_status") or status
     if status == "running":
         if item.get("stale"):
             return "stale"
         if item.get("run_lock_held"):
             return "run"
         return "lost"
+    if display_status in ("resuming", "waking", "pausing", "canceling"):
+        return "wake"
     if status in ("done", "canceled"):
         return "-"
     if status == "paused":
@@ -472,6 +481,13 @@ def _stale_text(item):
     return f"no ({idle} idle; threshold {threshold})"
 
 
+def _pending_commands_text(value):
+    commands = [str(item or "") for item in value or [] if str(item or "").strip()]
+    if not commands:
+        return "-"
+    return ", ".join(commands)
+
+
 def _format_managed_agent_run(run):
     started = run.get("started_at") or "-"
     reason = run.get("wake_reason") or "-"
@@ -2047,8 +2063,8 @@ def main(argv=None):
         if args.agent_command == "send":
             result = send_agent(args.agent_ref, args.message, args.author)
             result["waited"] = bool(args.wait)
+            result["nudge"] = nudge_agent(args.agent_ref, wait=bool(args.wait))
             if args.wait:
-                result["nudge"] = nudge_agent(args.agent_ref, wait=True)
                 reply_info = _send_reply_info(args.agent_ref, result["id"])
                 if reply_info:
                     result.update(reply_info)
@@ -2061,8 +2077,7 @@ def main(argv=None):
                 args.author,
             )
             result["waited"] = bool(args.wait)
-            if args.wait:
-                result["nudge"] = nudge_agent(args.agent_ref, wait=True)
+            result["nudge"] = nudge_agent(args.agent_ref, wait=bool(args.wait))
             print(json.dumps(result, indent=2, sort_keys=True))
             return
         if args.agent_command in ("pause", "cancel"):
diff --git a/tests/test_agents.py b/tests/test_agents.py
@@ -1051,6 +1051,8 @@ def fake_runner(meta, session, prompt):
             with redirect_stdout(list_out):
                 _print_managed_agent_list([shown])
             self.assertIn("POL", list_out.getvalue())
+            self.assertIn("QMSG", list_out.getvalue())
+            self.assertIn("QCMD", list_out.getvalue())
             self.assertIn("REPO", list_out.getvalue())
             self.assertIn("done", list_out.getvalue())
             self.assertIn("codexapi", list_out.getvalue())
@@ -1060,6 +1062,7 @@ def fake_runner(meta, session, prompt):
                 _print_managed_agent_show(shown)
             text = show_out.getvalue()
             self.assertIn("Policy: until_done", text)
+            self.assertIn("Qmsg: 0  Qcmd: 0", text)
             self.assertIn("Tokens: 50 total (30 in, 20 out, 50.0/h)", text)
             self.assertIn("Prompt: Handle messages.", text)
             self.assertIn("Recent runs:", text)
@@ -1087,15 +1090,71 @@ def test_cli_send_queues_by_default(self):
                     hostname="host-a",
                 )
                 output = io.StringIO()
-                with redirect_stdout(output):
-                    cli_main(["agent", "send", agent["id"], "status"])
+                with patch(
+                    "codexapi.cli.nudge_agent",
+                    return_value={"ran": True, "woken": 1, "spawned": True},
+                ) as nudge_mock:
+                    with redirect_stdout(output):
+                        cli_main(["agent", "send", agent["id"], "status"])
                 payload = json.loads(output.getvalue())
                 self.assertFalse(payload["waited"])
-                self.assertNotIn("nudge", payload)
+                self.assertTrue(payload["nudge"]["spawned"])
+                nudge_mock.assert_called_once_with(agent["id"], wait=False)
                 shown = show_agent(agent["id"])
                 self.assertEqual(shown["unread_message_count"], 1)
                 self.assertEqual(shown["state"]["status"], "ready")
 
+    def test_cli_resume_without_wait_async_nudges_and_list_shows_resuming(self):
+        def fake_runner(meta, session, prompt):
+            return {
+                "message": json.dumps(
+                    {
+                        "status": "Still running",
+                        "continue": True,
+                        "reply": "Continuing.",
+                    }
+                ),
+                "thread_id": "thread-resume-ui",
+            }
+
+        with _temp_home():
+            agent = start_agent("Keep an eye on this.", hostname="host-a")
+            control_agent(agent["id"], "pause", hostname="host-a")
+            tick(hostname="host-a", runner=fake_runner)
+
+            output = io.StringIO()
+            with patch(
+                "codexapi.cli.nudge_agent",
+                return_value={"ran": True, "woken": 1, "spawned": True},
+            ) as nudge_mock:
+                with redirect_stdout(output):
+                    cli_main(["agent", "resume", agent["id"]])
+            payload = json.loads(output.getvalue())
+            self.assertFalse(payload["waited"])
+            self.assertTrue(payload["nudge"]["spawned"])
+            nudge_mock.assert_called_once_with(agent["id"], wait=False)
+
+            shown = show_agent(agent["id"])
+            self.assertEqual(shown["state"]["status"], "paused")
+            self.assertEqual(shown["display_status"], "resuming")
+            self.assertEqual(shown["pending_commands"], ["resume"])
+            self.assertEqual(shown["pending_command_count"], 1)
+
+            list_out = io.StringIO()
+            with redirect_stdout(list_out):
+                _print_managed_agent_list([shown])
+            self.assertIn("resuming", list_out.getvalue())
+            self.assertIn("QMSG", list_out.getvalue())
+            self.assertIn("QCMD", list_out.getvalue())
+
+            show_out = io.StringIO()
+            with redirect_stdout(show_out):
+                _print_managed_agent_show(shown)
+            text = show_out.getvalue()
+            self.assertIn("[resuming]", text)
+            self.assertIn("State: paused", text)
+            self.assertIn("Pending commands: resume", text)
+
     def test_cli_send_wait_shows_immediate_agent_reply(self):
         with _temp_home():
             with patch.dict(os.environ, {"CODEXAPI_HOSTNAME": "host-a"}, clear=False):

Original file line number	Diff line number	Diff line change
`@@ -27,4 +27,4 @@`
`27`	`27`	`"task_result",`
`28`	`28`	`"lead",`
`29`	`29`	`]`
`30`		`-__version__ = "0.12.1"`
	`30`	`+__version__ = "0.12.2"`