Skip to content
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.py
index 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 s
attempts, 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.py
index 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.py
index 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.py
index 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_chars
if 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.py
index 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.py
index 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))