mirror of
https://github.com/andrewyng/openworker.git
synced 2026-11-20 20:37:44 +00:00
shell_task_output returned at once, and run_shell's description told the model to poll it. That is right for a dev server (nothing to wait for) and wrong for a build or test run the next step depends on: every poll is a full model call, and the only alternative, run_shell("sleep N"), is a blind wait capped at 600 s. Measured on a sealed evaluation run: 297 polls on one background job, ~$8.50 of cache reads and ~50 min of a 90-min clock spent asking whether it had finished.
wait_seconds (default 0 = unchanged) blocks until the task exits, prints new output, or the user interrupts, up to the shell's 600 s ceiling; the record gains waited_seconds. The sandbox path carries the wait over the socket and stretches the client's RPC timeout to cover it (it was a hard 30 s). Descriptions reworded, generically: check background processes with shell_task_output; if your next step depends on one finishing, pass wait_seconds rather than polling.
Tests, on both executor variants: returns early on exit (with the last line), returns early on new output, gives up at the deadline while running, wait_seconds 0 / negative / omitted unchanged, cap advertised and applied.
219 lines
8.3 KiB
Python
219 lines
8.3 KiB
Python
"""Persistent shell behind an `Executor` boundary.
|
|
|
|
`LocalExecutor` keeps one long-lived shell process, so `cd`, `export`, activated venvs,
|
|
etc. persist across `run_shell` calls (unlike a per-call `subprocess.run`). The `Executor`
|
|
interface is the hedge for a future `ContainerExecutor`/`VMExecutor` (sandboxing) without
|
|
touching the engine.
|
|
|
|
The shell is OS-native: `/bin/bash` on POSIX, `powershell.exe` (`-Command -` REPL) on
|
|
Windows. Each backend has its own marker/exit-code protocol and interrupt mechanism, but
|
|
the `Executor` contract (and the parsed `{marker} {exit_code} {cwd}` trailer) is identical.
|
|
|
|
Safety here is permission-gating (high-risk tool → approval) + per-command timeout +
|
|
best-effort non-interactive enforcement. A timed-out command is interrupted (SIGINT to the
|
|
foreground child on POSIX, Ctrl-Break to the child group on Windows); the shell survives so
|
|
session state is preserved.
|
|
|
|
Background tasks (`run_shell` with `run_in_background`) get their own detached process —
|
|
NOT the persistent shell — so a dev server can run while the session keeps working. They
|
|
are deliberately not killed by `close()` (which the timeout-recovery path calls); they end
|
|
when they exit or via `shell_task_kill`.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import os
|
|
from pathlib import Path
|
|
from typing import Optional
|
|
|
|
import aisuite as ai
|
|
|
|
from ..sandbox.runner.executor import (
|
|
_DEFAULT_TIMEOUT,
|
|
_MAX_TIMEOUT,
|
|
)
|
|
from ..sandbox.runner.executor import Executor as Executor
|
|
from ..sandbox.runner.executor import LocalExecutor as _StdlibLocalExecutor
|
|
|
|
_SIDECAR_ENV_VARS = ("COWORKER_API_TOKEN",)
|
|
|
|
|
|
def _shell_base_env() -> dict[str, str]:
|
|
"""The parent environment without OpenWorker's own API credential."""
|
|
return {k: v for k, v in os.environ.items() if k not in _SIDECAR_ENV_VARS}
|
|
|
|
|
|
class LocalExecutor(_StdlibLocalExecutor):
|
|
"""The in-process executor (direct mode). Same behaviour as before the move; the only
|
|
thing added here is the part that needs the rest of OpenWorker."""
|
|
|
|
def __init__(self, *, cwd: str | Path, **kwargs) -> None:
|
|
# Managed pinned tools (toolchain.install) land under one stable bin dir; putting
|
|
# it on PATH up front, even before anything is installed there, means a tool the
|
|
# user approves mid-session works in THIS shell immediately, by name, no respawn.
|
|
# Appended last: the user's own copies always win.
|
|
from .. import toolchain
|
|
|
|
extra = [*kwargs.pop("extra_path_dirs", ()), str(toolchain.bin_dir())]
|
|
super().__init__(
|
|
cwd=cwd, base_env=_shell_base_env(), extra_path_dirs=extra, **kwargs
|
|
)
|
|
|
|
|
|
_RUN_SHELL_SCHEMA = {
|
|
"type": "function",
|
|
"function": {
|
|
"name": "run_shell",
|
|
"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 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",
|
|
"properties": {
|
|
"command": {
|
|
"type": "string",
|
|
"description": "The command to run.",
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": (
|
|
"Short human-readable summary of what the command does (e.g. "
|
|
"'Install dependencies'), shown in approval prompts and logs."
|
|
),
|
|
},
|
|
"timeout_seconds": {
|
|
"type": "integer",
|
|
"description": (
|
|
f"Max seconds to wait (default {int(_DEFAULT_TIMEOUT)}, "
|
|
f"max {int(_MAX_TIMEOUT)}). Ignored for background tasks."
|
|
),
|
|
},
|
|
"run_in_background": {
|
|
"type": "boolean",
|
|
"description": (
|
|
"Run detached and return a task_id immediately instead of waiting. "
|
|
"Use for servers, watchers, and very long builds."
|
|
),
|
|
},
|
|
},
|
|
"required": ["command"],
|
|
},
|
|
},
|
|
}
|
|
|
|
_TASK_OUTPUT_SCHEMA = {
|
|
"type": "function",
|
|
"function": {
|
|
"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. 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",
|
|
"properties": {
|
|
"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"],
|
|
},
|
|
},
|
|
}
|
|
|
|
_TASK_KILL_SCHEMA = {
|
|
"type": "function",
|
|
"function": {
|
|
"name": "shell_task_kill",
|
|
"description": "Stop a background task started with run_shell run_in_background=true.",
|
|
"parameters": {
|
|
"type": "object",
|
|
"properties": {
|
|
"task_id": {
|
|
"type": "string",
|
|
"description": "The task_id returned by run_shell.",
|
|
}
|
|
},
|
|
"required": ["task_id"],
|
|
},
|
|
},
|
|
}
|
|
|
|
|
|
def shell_tools(executor: Executor) -> list:
|
|
"""Return the shell tools (`run_shell` + background-task helpers) bound to a
|
|
persistent executor."""
|
|
|
|
def run_shell(
|
|
command: str,
|
|
description: Optional[str] = None,
|
|
timeout_seconds: Optional[int] = None,
|
|
run_in_background: bool = False,
|
|
) -> dict:
|
|
# `description` is not used here on purpose: it rides along in the call arguments
|
|
# so approval prompts and the audit log can show intent, not just the raw command.
|
|
if run_in_background:
|
|
return executor.run_background(command)
|
|
timeout = None
|
|
if isinstance(timeout_seconds, (int, float)) and timeout_seconds > 0:
|
|
timeout = min(float(timeout_seconds), _MAX_TIMEOUT)
|
|
return executor.run(command, timeout=timeout)
|
|
|
|
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)
|
|
|
|
wrapped_run = ai.tool(
|
|
run_shell,
|
|
metadata=ai.ToolMetadata(
|
|
category="shell",
|
|
risk_level="high",
|
|
capabilities=["run_command"],
|
|
requires_approval=True,
|
|
),
|
|
)
|
|
wrapped_run.__coworker_schema__ = _RUN_SHELL_SCHEMA
|
|
wrapped_output = ai.tool(
|
|
shell_task_output,
|
|
metadata=ai.ToolMetadata(
|
|
category="shell",
|
|
risk_level="low",
|
|
capabilities=["run_command"],
|
|
requires_approval=False,
|
|
),
|
|
)
|
|
wrapped_output.__coworker_schema__ = _TASK_OUTPUT_SCHEMA
|
|
wrapped_kill = ai.tool(
|
|
shell_task_kill,
|
|
metadata=ai.ToolMetadata(
|
|
category="shell",
|
|
risk_level="low",
|
|
capabilities=["run_command"],
|
|
requires_approval=False,
|
|
),
|
|
)
|
|
wrapped_kill.__coworker_schema__ = _TASK_KILL_SCHEMA
|
|
return [wrapped_run, wrapped_output, wrapped_kill]
|