Python
shell_task_output: wait_seconds, so an agent can wait for a background task instead of polling it (OPE-227)
Devika Verma45c283d75f8e
diff --git a/coworker/agents/code.py b/coworker/agents/code.pyindex 41f29407..3af1adc9 100644--- a/coworker/agents/code.py+++ b/coworker/agents/code.py@@ -45,7 +45,9 @@ it; if you can't verify, say so plainly. Don't repeat a failing command — if sattempts, step back, reconsider, and surface the blocker.- Pass a short `description` with each command (shown in approval prompts), and raise \`timeout_seconds` for slow builds/tests. For long-running processes (dev servers, watchers), \-set `run_in_background` and poll `shell_task_output`; stop them with `shell_task_kill`.+set `run_in_background` and check them with `shell_task_output` (pass `wait_seconds` when \+your next step depends on the process finishing, rather than polling); stop them with \+`shell_task_kill`.Plan multi-step work:- For anything beyond a few steps, maintain a task list with `todo_write`: keep exactly one \diff --git a/coworker/sandbox/executor.py b/coworker/sandbox/executor.pyindex fb3e5527..31cd65b1 100644--- a/coworker/sandbox/executor.py+++ b/coworker/sandbox/executor.py@@ -89,15 +89,20 @@ class RunnerExecutor(Executor):def run_background(self, command: str) -> dict[str, Any]:return self._simple("task.start", {"command": command, "cwd": self.cwd})- def background_output(self, task_id: str) -> dict[str, Any]:- return self._simple("task.output", {"task_id": task_id})+ def background_output(self, task_id: str, wait_seconds: float = 0) -> dict[str, Any]:+ wait = max(0.0, float(wait_seconds or 0))+ # The runner does the waiting; this side only has to outlast it on the pipe.+ return self._simple(+ "task.output", {"task_id": task_id, "wait_seconds": wait},+ timeout=max(30.0, wait + _GRACE_SECONDS),+ )def background_kill(self, task_id: str) -> dict[str, Any]:return self._simple("task.kill", {"task_id": task_id})- def _simple(self, method: str, params: dict[str, Any]) -> dict[str, Any]:+ def _simple(self, method: str, params: dict[str, Any], timeout: float = 30) -> dict[str, Any]:try:- result = self._client.call(method, {"shell": self.shell, **params}, timeout=30)+ result = self._client.call(method, {"shell": self.shell, **params}, timeout=timeout)except P.RunnerError as exc:return {"error": exc.message}result.pop("seq", None)diff --git a/coworker/sandbox/runner/daemon.py b/coworker/sandbox/runner/daemon.pyindex dc879544..a415aa66 100644--- a/coworker/sandbox/runner/daemon.py+++ b/coworker/sandbox/runner/daemon.py@@ -327,7 +327,10 @@ class Daemon:if method == "task.start":return ex.run_background(str(params.get("command") or ""))if method == "task.output":- return ex.background_output(str(params.get("task_id") or ""))+ return ex.background_output(+ str(params.get("task_id") or ""),+ wait_seconds=float(params.get("wait_seconds") or 0),+ )if method == "task.kill":return ex.background_kill(str(params.get("task_id") or ""))return {diff --git a/coworker/sandbox/runner/executor.py b/coworker/sandbox/runner/executor.pyindex e61639a6..94e5bdab 100644--- a/coworker/sandbox/runner/executor.py+++ b/coworker/sandbox/runner/executor.py@@ -60,7 +60,7 @@ class Executor(ABC):def run_background(self, command: str) -> dict[str, Any]:return {"error": "background execution is not supported by this executor"}- def background_output(self, task_id: str) -> dict[str, Any]:+ def background_output(self, task_id: str, wait_seconds: float = 0) -> dict[str, Any]:return {"error": "background execution is not supported by this executor"}def background_kill(self, task_id: str) -> dict[str, Any]:@@ -134,6 +134,17 @@ class _BackgroundTask:self._cursor = len(self._lines)return new+ def has_new(self) -> bool:+ """Unread output exists — without moving the cursor, so a waiter can look+ without consuming what the caller is about to read."""+ with self._lock:+ return len(self._lines) > self._cursor++ def drain(self, timeout: float) -> None:+ """After the process exits, give the reader thread a moment to append the+ last lines, so an exit-triggered read does not miss the final output."""+ self._reader.join(timeout=timeout)+def kill(self) -> None:if self.proc.poll() is not None:return@@ -364,13 +375,28 @@ class LocalExecutor(Executor):"task_id": task_id,"command": command,"status": "running",- "note": "use shell_task_output to read its output, shell_task_kill to stop it",+ "note": "use shell_task_output to read its output (wait_seconds=N to wait for "+ "it to exit or print more), shell_task_kill to stop it",}- def background_output(self, task_id: str) -> dict[str, Any]:+ def background_output(self, task_id: str, wait_seconds: float = 0) -> dict[str, Any]:task = self._bg_tasks.get(task_id)if task is None:return {"error": f"unknown task: {task_id}"}+ # Wait (bounded) until the task exits or prints something new. Without this a+ # model whose next step depends on the task has to poll, and every poll is a+ # full model call: measured at 297 polls on one background job in a sealed+ # evaluation run. A sleep via run_shell is the only alternative and cannot+ # return early. Capped at the shell's own ceiling so a tool call never outlives+ # what run_shell would allow.+ started = time.monotonic()+ deadline = started + max(0.0, min(float(wait_seconds or 0), _MAX_TIMEOUT))+ while time.monotonic() < deadline:+ if task.proc.poll() is not None or task.has_new() or self._abort.is_set():+ break+ time.sleep(min(0.25, max(0.0, deadline - time.monotonic())))+ if task.proc.poll() is not None:+ task.drain(0.5)output = task.read_new()truncated = len(output) > self.max_output_charsif truncated:@@ -382,6 +408,7 @@ class LocalExecutor(Executor):"exit_code": exit_code,"output": output,"truncated": truncated,+ "waited_seconds": round(time.monotonic() - started, 1),}def background_kill(self, task_id: str) -> dict[str, Any]:diff --git a/coworker/tools/shell.py b/coworker/tools/shell.pyindex 7cfea3b3..0aef5b21 100644--- a/coworker/tools/shell.py+++ b/coworker/tools/shell.py@@ -67,8 +67,10 @@ _RUN_SHELL_SCHEMA = {"description": ("Run a shell command in the persistent session (cwd and env persist across ""calls). Output longer than the limit keeps the END (where test/build verdicts "- "are). Set run_in_background for long-running processes like dev servers, then "- "poll with shell_task_output."+ "are). Set run_in_background for processes you don't need to wait for, like dev "+ "servers, and check them with shell_task_output. If your next step depends on "+ "the process finishing, use shell_task_output with wait_seconds rather than "+ "polling."),"parameters": {"type": "object",@@ -110,7 +112,10 @@ _TASK_OUTPUT_SCHEMA = {"name": "shell_task_output","description": ("Read NEW output (since the last read) from a background task started with "- "run_shell run_in_background=true, plus its status and exit code."+ "run_shell run_in_background=true, plus its status and exit code. By default "+ "returns at once. Pass wait_seconds to block until the task exits or prints "+ "something new, up to that many seconds - use it when your next step depends "+ "on the task finishing, instead of calling this repeatedly."),"parameters": {"type": "object",@@ -118,7 +123,15 @@ _TASK_OUTPUT_SCHEMA = {"task_id": {"type": "string","description": "The task_id returned by run_shell.",- }+ },+ "wait_seconds": {+ "type": "integer",+ "description": (+ f"Wait up to this many seconds (max {int(_MAX_TIMEOUT)}) for the "+ "task to exit or print new output; returns as soon as either "+ "happens. Default 0: return immediately."+ ),+ },},"required": ["task_id"],},@@ -163,8 +176,11 @@ def shell_tools(executor: Executor) -> list:timeout = min(float(timeout_seconds), _MAX_TIMEOUT)return executor.run(command, timeout=timeout)- def shell_task_output(task_id: str) -> dict:- return executor.background_output(task_id)+ def shell_task_output(task_id: str, wait_seconds: Optional[int] = None) -> dict:+ wait = 0.0+ if isinstance(wait_seconds, (int, float)) and wait_seconds > 0:+ wait = min(float(wait_seconds), _MAX_TIMEOUT)+ return executor.background_output(task_id, wait_seconds=wait)def shell_task_kill(task_id: str) -> dict:return executor.background_kill(task_id)diff --git a/tests/test_shell.py b/tests/test_shell.pyindex 99b60de9..4bd133a6 100644--- a/tests/test_shell.py+++ b/tests/test_shell.py@@ -244,6 +244,79 @@ def test_background_task_kill(executor):assert res["status"] == "exited"+DELAYED_ECHO = (+ "Start-Sleep -Seconds 1; Write-Output later_line" if _WIN else "sleep 1; echo later_line"+)+++def test_background_wait_returns_as_soon_as_the_task_exits(executor):+ reg = ToolRegistry()+ reg.register_all(shell_tools(executor))+ started = reg.execute("run_shell", {"command": QUICK_ECHO, "run_in_background": True})+ t0 = time.monotonic()+ res = reg.execute("shell_task_output", {"task_id": started["task_id"], "wait_seconds": 10})+ elapsed = time.monotonic() - t0+ # Asked for up to 10 s; got the exit (and its last line) well before that.+ assert res["status"] == "exited" and res["exit_code"] == 0, res+ assert "quick_done" in res["output"], res+ assert elapsed < 5, elapsed+ assert res["waited_seconds"] <= 5+++def test_background_wait_returns_when_new_output_arrives(executor):+ reg = ToolRegistry()+ reg.register_all(shell_tools(executor))+ started = reg.execute("run_shell", {"command": DELAYED_ECHO, "run_in_background": True})+ t0 = time.monotonic()+ res = reg.execute("shell_task_output", {"task_id": started["task_id"], "wait_seconds": 10})+ elapsed = time.monotonic() - t0+ # Nothing is printed for ~1 s; the wait ends on the first line, not at 10 s.+ assert "later_line" in res["output"], res+ assert elapsed < 8, elapsed+++def test_background_wait_gives_up_at_the_deadline_while_still_running(executor):+ reg = ToolRegistry()+ reg.register_all(shell_tools(executor))+ started = reg.execute("run_shell", {"command": ECHO_THEN_SLEEP, "run_in_background": True})+ _poll_output(reg, started["task_id"]) # consume the initial "started" line+ t0 = time.monotonic()+ res = reg.execute("shell_task_output", {"task_id": started["task_id"], "wait_seconds": 1})+ elapsed = time.monotonic() - t0+ assert res["status"] == "running" and res["output"] == "", res+ assert 0.8 <= elapsed < 4, elapsed+ assert 0.8 <= res["waited_seconds"] <= 4+ reg.execute("shell_task_kill", {"task_id": started["task_id"]})+++def test_background_read_without_wait_is_unchanged(executor):+ reg = ToolRegistry()+ reg.register_all(shell_tools(executor))+ started = reg.execute("run_shell", {"command": ECHO_THEN_SLEEP, "run_in_background": True})+ _poll_output(reg, started["task_id"])+ for args in ({"task_id": started["task_id"]}, {"task_id": started["task_id"], "wait_seconds": 0},+ {"task_id": started["task_id"], "wait_seconds": -3}):+ t0 = time.monotonic()+ res = reg.execute("shell_task_output", args)+ assert res["status"] == "running" and time.monotonic() - t0 < 0.5, (args, res)+ assert res["waited_seconds"] == 0.0+ reg.execute("shell_task_kill", {"task_id": started["task_id"]})+++def test_wait_is_capped_at_the_shell_maximum(executor):+ from coworker.tools.shell import _TASK_OUTPUT_SCHEMA, _MAX_TIMEOUT++ desc = _TASK_OUTPUT_SCHEMA["function"]["parameters"]["properties"]["wait_seconds"]["description"]+ assert f"max {int(_MAX_TIMEOUT)}" in desc+ # The wrapper clamps before the executor sees it: a huge wait on an exited task is instant.+ reg = ToolRegistry()+ reg.register_all(shell_tools(executor))+ started = reg.execute("run_shell", {"command": QUICK_ECHO, "run_in_background": True})+ t0 = time.monotonic()+ res = reg.execute("shell_task_output", {"task_id": started["task_id"], "wait_seconds": 10 ** 6})+ assert res["status"] == "exited" and time.monotonic() - t0 < 5++def test_background_unknown_task_errors(executor):reg = ToolRegistry()reg.register_all(shell_tools(executor))