Python
Add --root to `openworker run`: extra writable folders beside the workspace (OPE-196)
Devika Verma1d0073faaf37
diff --git a/coworker/headless/runner.py b/coworker/headless/runner.pyindex f9b27228..0a170770 100644--- a/coworker/headless/runner.py+++ b/coworker/headless/runner.py@@ -61,6 +61,17 @@ def parse_args(argv: Optional[list[str]] = None) -> argparse.Namespace:src.add_argument("--prompt", "--prompt-text", dest="prompt_text", help="the task text")src.add_argument("--prompt-file", help="file containing the task text (UTF-8)")p.add_argument("--workspace", required=True, help="folder the agent works in")+ p.add_argument(+ "--root",+ action="append",+ default=None,+ metavar="DIR",+ help="an extra folder the agent may read and write, beside the workspace "+ "(repeatable), for a harness whose output contract lives outside the workspace, "+ "e.g. --root /output. The file tools only write under a declared root, in every "+ "mode; the shell is not scoped, so without this a delivery would depend on which "+ "tool the model happened to pick.",+ )p.add_argument("--model", required=True, help="provider:model (OpenWorker) or provider/model")@@ -582,6 +593,21 @@ def _agent_version(explicit: Optional[str]) -> str:return "openworker unknown"+def _extra_roots(args: argparse.Namespace, workspace: Path) -> list:+ """The `--root DIR` folders as writable roots: created if missing, deduplicated, and+ without the workspace itself (always the first root)."""+ from ..roots import RootDir++ found: list = []+ for raw in args.root or []:+ path = Path(raw).expanduser().resolve()+ if path == workspace or any(path == r.path for r in found):+ continue+ path.mkdir(parents=True, exist_ok=True)+ found.append(RootDir(path=path, writable=True))+ return found++def run(args: argparse.Namespace) -> int:out = Path(args.out).resolve()out.mkdir(parents=True, exist_ok=True)@@ -597,11 +623,17 @@ def run(args: argparse.Namespace) -> int:from ..events import EventTypefrom ..permissions import Modefrom ..providers import ProviderRouter+ from ..roots import RootDirfrom ..secrets import SecretStore, state_dirfrom ..unattended import DANGEROUS_MODE_WARNINGworkspace = Path(args.workspace).resolve()workspace.mkdir(parents=True, exist_ok=True)+ # `--root DIR`: extra writable folders. An explicit list replaces the engine's default+ # single-workspace root, so the workspace goes first and stays the folder that+ # relative paths resolve against.+ extra_roots = _extra_roots(args, workspace)+ roots = [RootDir(path=workspace, writable=True), *extra_roots] if extra_roots else Nonemodel = normalize_model(args.model)mode = Mode(args.mode)run_id = uuid.uuid4().hex[:12]@@ -625,6 +657,7 @@ def run(args: argparse.Namespace) -> int:engine = build_engine(agent=get_agent(args.persona),workspace=workspace,+ roots=roots,model=model,mode=mode,provider=provider,@@ -1009,6 +1042,7 @@ def _write_records("provider_order": args.provider_order,"timeout_seconds": args.timeout_seconds,"workspace": str(Path(args.workspace).resolve()),+ "roots": [str(Path(r).expanduser().resolve()) for r in (args.root or [])],"scripted": bool(args.scripted),},"isolation": isolation,diff --git a/docs/headless.md b/docs/headless.mdindex f0c02b19..f6aad948 100644--- a/docs/headless.md+++ b/docs/headless.md@@ -71,6 +71,7 @@ Options:|---|---|| `--prompt TEXT` / `--prompt-file PATH` | the task || `--workspace DIR` | the folder the agent works in |+| `--root DIR` | an extra folder the agent may read and write, beside the workspace (repeatable), for a harness whose output contract lives outside the workspace — e.g. `--root /output`. The file tools only write under a declared root, in every mode; the shell is not scoped, so without this a delivery would depend on which tool the model happened to pick. Recorded under `args.roots` in `summary.json`. || `--model ID` | `provider:model` or `provider/model` (first slash splits) || `--mode` | see above; default `bypass-approvals` || `--attendance` | `auto` (the only value here) |diff --git a/tests/test_headless_run.py b/tests/test_headless_run.pyindex afa0b7e6..57684f79 100644--- a/tests/test_headless_run.py+++ b/tests/test_headless_run.py@@ -307,6 +307,45 @@ def test_large_tool_result_is_bounded_and_spilled(tmp_path: Path) -> None:assert _summary(out)["tool_results_bounded"] == 1+# -- extra roots (--root) -------------------------------------------------------------------+++def _patch_script(target: Path) -> list[dict]:+ return [+ {"text": "Writing the patch.", "tool_calls": [{"name": "write_file", "arguments": {"path": str(target), "content": "--- a/x\n+++ b/x\n"}}]},+ {"text": "Done.", "usage": {"input": 10, "output": 5}},+ ]+++def test_root_lets_the_file_tools_write_outside_the_workspace(tmp_path: Path) -> None:+ # A harness whose output contract lives outside the workspace (CyberGym: /output).+ outdir = tmp_path / "output"+ outdir.mkdir()+ target = outdir / "fix.patch"+ proc, _ws, out = _run(+ tmp_path, "bypass-approvals", _patch_script(target), extra=["--root", str(outdir)]+ )+ assert proc.returncode == 0, proc.stdout + proc.stderr+ assert target.read_text(encoding="utf-8").startswith("--- a/x")+ summary = _summary(out)+ assert summary["outcome"] == "completed" and summary["tool_calls_denied"] == 0+ assert summary["args"]["roots"] == [str(outdir.resolve())]+ # The model is told about the folder in the session's directories block (a per-turn+ # context, not the cached system prompt), the same way the workspace is announced.+ everything = "\n".join(str(m.get("content") or "") for m in _messages(out))+ assert str(outdir.resolve()) in everything+++def test_without_root_the_same_write_stays_inside_the_workspace(tmp_path: Path) -> None:+ outdir = tmp_path / "output"+ outdir.mkdir()+ target = outdir / "fix.patch"+ proc, _ws, out = _run(tmp_path, "bypass-approvals", _patch_script(target))+ assert proc.returncode == 0, proc.stdout + proc.stderr+ assert not target.exists()+ assert _summary(out)["args"]["roots"] == []++def test_run_help_and_the_top_level_help_mention_the_command() -> None:proc = subprocess.run([sys.executable, "-m", "coworker.cli", "run", "--help"],