Skip to content
Python

Rename `openworker run --root` to `--add-dir` (OPE-196)

Devika Verma31fac7049ac5
diff --git a/coworker/headless/runner.py b/coworker/headless/runner.py
index 0a170770..33aaa7dc 100644
--- a/coworker/headless/runner.py
+++ b/coworker/headless/runner.py
@@ -62,15 +62,16 @@ def parse_args(argv: Optional[list[str]] = None) -> argparse.Namespace:
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",
+ "--add-dir",
+ dest="add_dir",
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.",
+ "e.g. --add-dir /output. The file tools only write inside the session's folders, 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"
@@ -593,13 +594,13 @@ 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
+def _extra_dirs(args: argparse.Namespace, workspace: Path) -> list:
+ """The `--add-dir 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 []:
+ for raw in args.add_dir or []:
path = Path(raw).expanduser().resolve()
if path == workspace or any(path == r.path for r in found):
continue
@@ -629,11 +630,11 @@ def run(args: argparse.Namespace) -> int:
workspace = 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 None
+ # `--add-dir 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_dirs = _extra_dirs(args, workspace)
+ roots = [RootDir(path=workspace, writable=True), *extra_dirs] if extra_dirs else None
model = normalize_model(args.model)
mode = Mode(args.mode)
run_id = uuid.uuid4().hex[:12]
@@ -1042,7 +1043,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 [])],
+ "extra_dirs": [str(Path(r).expanduser().resolve()) for r in (args.add_dir or [])],
"scripted": bool(args.scripted),
},
"isolation": isolation,
diff --git a/docs/headless.md b/docs/headless.md
index f6aad948..d96f2856 100644
--- a/docs/headless.md
+++ b/docs/headless.md
@@ -71,7 +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`. |
+| `--add-dir 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. `--add-dir /output`. The file tools only write inside the session's folders, 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.extra_dirs` 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.py
index 57684f79..4492ef74 100644
--- a/tests/test_headless_run.py
+++ b/tests/test_headless_run.py
@@ -307,7 +307,7 @@ def test_large_tool_result_is_bounded_and_spilled(tmp_path: Path) -> None:
assert _summary(out)["tool_results_bounded"] == 1
-# -- extra roots (--root) -------------------------------------------------------------------
+# -- extra folders (--add-dir) --------------------------------------------------------------
def _patch_script(target: Path) -> list[dict]:
@@ -317,33 +317,33 @@ def _patch_script(target: Path) -> list[dict]:
]
-def test_root_lets_the_file_tools_write_outside_the_workspace(tmp_path: Path) -> None:
+def test_add_dir_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)]
+ tmp_path, "bypass-approvals", _patch_script(target), extra=["--add-dir", 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())]
+ assert summary["args"]["extra_dirs"] == [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:
+def test_without_add_dir_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"] == []
+ assert _summary(out)["args"]["extra_dirs"] == []
def test_run_help_and_the_top_level_help_mention_the_command() -> None: