Skip to content

"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/

Python

fix(browser): translate harness paths + split focus/type for safety (PR #308 round 5)

apireno5d2ceee28f0e
diff --git a/browser/agent-harness/cli_anything/browser/tests/test_domshell_backend.py b/browser/agent-harness/cli_anything/browser/tests/test_domshell_backend.py
index fcc8f095a..978c2e4b1 100644
--- a/browser/agent-harness/cli_anything/browser/tests/test_domshell_backend.py
+++ b/browser/agent-harness/cli_anything/browser/tests/test_domshell_backend.py
@@ -15,6 +15,126 @@ from cli_anything.browser.core.session import Session
from cli_anything.browser.utils import domshell_backend as backend
+# ── Path translation: harness `/` vs DOMShell `~/` ───────────────────
+
+
+def test_translate_path_root_maps_to_empty():
+ """Harness `/` (focused-tab AX root) → DOMShell empty (lane cwd)."""
+ assert backend._translate_path("/") == ""
+ assert backend._translate_path("") == ""
+
+
+def test_translate_path_strips_leading_slash():
+ assert backend._translate_path("/main") == "main"
+ assert backend._translate_path("/main/article") == "main/article"
+
+
+def test_translate_path_preserves_relative():
+ """Relative paths pass through unchanged — DOMShell handles them."""
+ assert backend._translate_path("main") == "main"
+ assert backend._translate_path("..") == ".."
+ assert backend._translate_path(".") == "."
+
+
[email protected](backend, "_call_execute", new_callable=AsyncMock)
+def test_ls_root_sends_bare_ls(mock_call):
+ """`ls /` (harness) → bare `ls` (DOMShell), operating on lane cwd."""
+ mock_call.return_value = _make_result("[lane: 1]")
+ backend.ls("/")
+ assert mock_call.call_args.args[0] == "ls"
+
+
[email protected](backend, "_call_execute", new_callable=AsyncMock)
+def test_ls_subpath_strips_leading_slash(mock_call):
+ mock_call.return_value = _make_result("[lane: 1]")
+ backend.ls("/main")
+ assert mock_call.call_args.args[0] == "ls main"
+
+
[email protected](backend, "_call_execute", new_callable=AsyncMock)
+def test_cd_root_uses_here(mock_call):
+ """`cd /` (harness) → `cd %here%` (DOMShell jump-to-tab-root)."""
+ mock_call.return_value = _make_result("[lane: 1]")
+ backend.cd("/")
+ assert mock_call.call_args.args[0] == "cd %here%"
+
+
[email protected](backend, "_call_execute", new_callable=AsyncMock)
+def test_cd_subpath_strips_leading_slash(mock_call):
+ mock_call.return_value = _make_result("[lane: 1]")
+ backend.cd("/main/div[0]")
+ assert mock_call.call_args.args[0] == "cd 'main/div[0]'"
+
+
[email protected](backend, "_call_execute", new_callable=AsyncMock)
+def test_cat_strips_leading_slash(mock_call):
+ mock_call.return_value = _make_result("[lane: 1]")
+ backend.cat("/main/button[0]")
+ assert mock_call.call_args.args[0] == "cat 'main/button[0]'"
+
+
+def test_cat_root_raises_value_error():
+ """Calling cat against the tab root is a programming error — fail clearly."""
+ with pytest.raises(ValueError, match="element name is required"):
+ backend.cat("/")
+ with pytest.raises(ValueError, match="element name is required"):
+ backend.cat("")
+
+
[email protected](backend, "_call_execute", new_callable=AsyncMock)
+def test_click_strips_leading_slash(mock_call):
+ mock_call.return_value = _make_result("[lane: 1]")
+ backend.click("/main/button[0]")
+ assert mock_call.call_args.args[0] == "click 'main/button[0]'"
+
+
+def test_click_root_raises_value_error():
+ with pytest.raises(ValueError, match="element name is required"):
+ backend.click("/")
+ with pytest.raises(ValueError, match="element name is required"):
+ backend.click("")
+
+
+def test_type_text_root_raises_value_error():
+ """Focusing the tab root is a programming error — same class as cat/click."""
+ with pytest.raises(ValueError, match="element name is required"):
+ backend.type_text("/", "hello")
+ with pytest.raises(ValueError, match="element name is required"):
+ backend.type_text("", "hello")
+
+
[email protected](backend, "_call_execute", new_callable=AsyncMock)
+def test_grep_rooted_with_subpath_prev_keeps_translated_restore(mock_call):
+ """A non-`/` prev should also be translated, not sent verbatim."""
+ mock_call.return_value = _make_result("[lane: 1]")
+ backend.grep("Login", path="/main/dialog", prev="/main")
+ assert mock_call.call_args.args[0] == "cd main/dialog\ngrep Login\ncd main"
+
+
+# ── _is_error helper ─────────────────────────────────────────────────
+
+
+def test_is_error_detects_isError_attribute():
+ assert backend._is_error(SimpleNamespace(isError=True)) is True
+ assert backend._is_error(SimpleNamespace(isError=False)) is False
+
+
+def test_is_error_detects_dict_keys():
+ assert backend._is_error({"isError": True}) is True
+ assert backend._is_error({"error": "boom"}) is True
+ assert backend._is_error({"path": "/main"}) is False
+
+
+def test_is_error_detects_error_prefixed_text():
+ assert backend._is_error(_make_result("Error: no such element")) is True
+ assert backend._is_error(_make_result("ERROR: case insensitive")) is True
+ assert backend._is_error(_make_result("✓ Focused\n[lane: 1]")) is False
+
+
+def test_is_error_handles_missing_content():
+ assert backend._is_error(SimpleNamespace()) is False
+
+
# ── grep: command string and call sequencing ──────────────────────────
@@ -43,8 +163,10 @@ def test_grep_rooted_emits_single_multiline_call(mock_call):
backend.grep("Login", path="/main", prev="/")
+ # Harness `/main` translates to DOMShell `main`; harness `/` (the
+ # default prev) translates to `cd %here%`.
assert mock_call.call_args_list == [
- call("cd /main\ngrep Login\ncd /", False, session=None),
+ call("cd main\ngrep Login\ncd %here%", False, session=None),
]
@@ -72,11 +194,12 @@ def test_grep_rooted_quotes_path_with_spaces(mock_call):
backend.grep("Login", path="/path with spaces", prev="/")
cmd = mock_call.call_args.args[0]
- # shlex.quote single-quotes anything containing whitespace; the rest
- # of the multi-line layout (grep + cd back) stays intact.
- assert cmd.startswith("cd '/path with spaces'\n")
+ # _translate_path strips the leading "/", then shlex.quote single-
+ # quotes the remainder; the multi-line layout (grep + cd back) stays
+ # intact, with the restore using `cd %here%` for the harness-`/` prev.
+ assert cmd.startswith("cd 'path with spaces'\n")
assert "\ngrep Login\n" in cmd
- assert cmd.endswith("\ncd /")
+ assert cmd.endswith("\ncd %here%")
@patch.object(backend, "_call_execute", new_callable=AsyncMock)
@@ -119,16 +242,39 @@ def test_grep_keyword_use_daemon_still_works():
@patch.object(backend, "_call_execute", new_callable=AsyncMock)
-def test_type_text_emits_focus_then_type_in_one_call(mock_call):
- """type_text builds a single multi-line ``focus … \\ntype …`` execute call."""
- mock_call.return_value = {}
+def test_type_text_uses_two_separate_calls(mock_call):
+ """type_text issues focus + type as two separate execute calls.
+
+ The split is for safety: DOMShell's multi-line splitter continues
+ past per-line errors, so a single ``focus path\\ntype text`` call
+ would dispatch keys into stale focus if ``focus`` failed. Two calls
+ with an error check between them prevents that.
+ """
+ mock_call.return_value = _make_result("✓ Focused\n[lane: 1]")
backend.type_text("search_input", "machine learning")
- assert mock_call.call_args_list == [
- call("focus search_input\ntype 'machine learning'", False, session=None),
+ assert mock_call.call_count == 2
+ assert mock_call.call_args_list[0].args[0] == "focus search_input"
+ assert mock_call.call_args_list[1].args[0] == "type 'machine learning'"
+
+
[email protected](backend, "_call_execute", new_callable=AsyncMock)
+def test_type_text_skips_type_on_focus_error(mock_call):
+ """If focus errors, type MUST NOT run — would land in stale focus."""
+ mock_call.side_effect = [
+ _make_result("Error: focus: No such element"),
+ _make_result("✓ Typed"), # should NOT be reached
]
+ result = backend.type_text("/stale/path", "secret_password")
+
+ # Only the focus call was made; the focus result was returned.
+ assert mock_call.call_count == 1
+ assert mock_call.call_args_list[0].args[0] == "focus stale/path"
+ # The focus result is returned verbatim so callers see the error.
+ assert result.content[0].text == "Error: focus: No such element"
+
def test_type_text_rejects_newline_in_text():
"""``\\n`` in text would inject a new DOMShell command — must raise."""
@@ -428,7 +574,8 @@ def test_session_is_keyword_only_on_open_url():
def test_use_daemon_positional_on_ls(mock_call):
mock_call.return_value = {}
backend.ls("/", True) # use_daemon=True positionally
- assert mock_call.call_args == call("ls /", True, session=None)
+ # Harness `/` translates to "" so ls sends the bare command.
+ assert mock_call.call_args == call("ls", True, session=None)
@patch.object(backend, "_call_execute", new_callable=AsyncMock)
@@ -447,8 +594,11 @@ def test_use_daemon_positional_on_reload(mock_call):
@patch.object(backend, "_call_execute", new_callable=AsyncMock)
def test_use_daemon_positional_on_type_text(mock_call):
- mock_call.return_value = {}
+ """Positional ``use_daemon`` flows through both halves of the split."""
+ mock_call.return_value = _make_result("✓\n[lane: 1]")
backend.type_text("input", "hello", True)
- assert mock_call.call_args == call(
- "focus input\ntype hello", True, session=None
- )
+ # Two calls (focus then type), both with use_daemon=True positionally.
+ assert mock_call.call_args_list == [
+ call("focus input", True, session=None),
+ call("type hello", True, session=None),
+ ]
diff --git a/browser/agent-harness/cli_anything/browser/utils/domshell_backend.py b/browser/agent-harness/cli_anything/browser/utils/domshell_backend.py
index 9ef830d53..80de67a8b 100644
--- a/browser/agent-harness/cli_anything/browser/utils/domshell_backend.py
+++ b/browser/agent-harness/cli_anything/browser/utils/domshell_backend.py
@@ -186,6 +186,55 @@ def _capture_lane(session: Any, result: Any) -> None:
session.domshell_lane_id = lane
+def _translate_path(harness_path: str) -> str:
+ """Translate a harness DOM path to a DOMShell command path.
+
+ The harness models ``/`` as the focused tab's AX root. DOMShell models
+ ``~/`` (and bare ``/``) as the BROWSER root — windows and tabs.
+ Sending ``ls /`` verbatim would list tabs, not page elements. Strip
+ the leading ``/`` so harness ``/main`` becomes DOMShell ``main``
+ (relative to the lane's cwd, which IS the focused tab's AX root once
+ ``page open`` has put the lane inside the tab).
+
+ - ``""`` and ``"/"`` → ``""`` (signal: operate on lane cwd; the
+ wrappers turn this into a bare command, e.g. ``ls`` or ``cd %here%``).
+ - ``"/main"`` → ``"main"``
+ - ``"/main/article"`` → ``"main/article"``
+ - ``"main"``, ``".."``, ``"."`` → passed through unchanged.
+ """
+ if not harness_path or harness_path == "/":
+ return ""
+ if harness_path.startswith("/"):
+ return harness_path[1:]
+ return harness_path
+
+
+def _is_error(result: Any) -> bool:
+ """Best-effort check that a ``domshell_execute`` result represents an error.
+
+ Inspects ``isError`` if the MCP SDK populated it, then ``isError`` /
+ ``error`` keys on dict-shaped test fixtures, and finally scans the
+ concatenated text content for a leading "error". Robust to the raw
+ ``CallToolResult`` and to the ``SimpleNamespace(content=[...])``
+ fixtures used in tests.
+ """
+ if hasattr(result, "isError") and result.isError:
+ return True
+ if isinstance(result, dict):
+ if result.get("isError"):
+ return True
+ if "error" in result:
+ return True
+ text = ""
+ content = getattr(result, "content", None)
+ if content:
+ for c in content:
+ piece = getattr(c, "text", None)
+ if piece:
+ text += piece
+ return text.strip().lower().startswith("error")
+
+
def _assert_single_line(field: str, value: str) -> None:
"""Reject newline characters in a user-supplied string.
@@ -358,7 +407,9 @@ def ls(path: str = "/", use_daemon: bool = False, *, session: Any = None) -> dic
>>> ls("/")
{"path": "/", "entries": [{"name": "main", "role": "landmark", ...}]}
"""
- return asyncio.run(_call_execute(f"ls {_q(path)}", use_daemon, session=session))
+ translated = _translate_path(path)
+ command = f"ls {_q(translated)}" if translated else "ls"
+ return asyncio.run(_call_execute(command, use_daemon, session=session))
def cd(path: str, use_daemon: bool = False, *, session: Any = None) -> dict:
@@ -376,7 +427,12 @@ def cd(path: str, use_daemon: bool = False, *, session: Any = None) -> dict:
>>> cd("/main/div[0]")
{"path": "/main/div[0]", "element": {...}}
"""
- return asyncio.run(_call_execute(f"cd {_q(path)}", use_daemon, session=session))
+ translated = _translate_path(path)
+ # Harness `cd /` means "back to focused-tab AX root" — DOMShell's
+ # equivalent is `cd %here%`, which jumps to the tab root regardless
+ # of where the lane wandered to.
+ command = "cd %here%" if not translated else f"cd {_q(translated)}"
+ return asyncio.run(_call_execute(command, use_daemon, session=session))
def cat(path: str, use_daemon: bool = False, *, session: Any = None) -> dict:
@@ -394,7 +450,13 @@ def cat(path: str, use_daemon: bool = False, *, session: Any = None) -> dict:
>>> cat("/main/button[0]")
{"name": "Submit", "role": "button", "text": "Submit", ...}
"""
- return asyncio.run(_call_execute(f"cat {_q(path)}", use_daemon, session=session))
+ translated = _translate_path(path)
+ if not translated:
+ raise ValueError(
+ "cat: an element name is required — cannot cat the tab root. "
+ "Use `ls` to list the root's children, or pass a specific name."
+ )
+ return asyncio.run(_call_execute(f"cat {_q(translated)}", use_daemon, session=session))
def grep(
@@ -440,10 +502,18 @@ def grep(
{"matches": ["/main/button[0]"]}
"""
_assert_single_line("pattern", pattern)
- if path and path != "/":
+ translated_path = _translate_path(path)
+ translated_prev = _translate_path(prev)
+ if translated_path:
_assert_single_line("path", path)
_assert_single_line("prev", prev)
- command = f"cd {_q(path)}\ngrep {_q(pattern)}\ncd {_q(prev)}"
+ # Harness `/` (the default for `prev`) means "back to focused-tab
+ # AX root", which is DOMShell's `cd %here%`. Any other restore
+ # path becomes `cd <translated>`.
+ restore = (
+ f"cd {_q(translated_prev)}" if translated_prev else "cd %here%"
+ )
+ command = f"cd {_q(translated_path)}\ngrep {_q(pattern)}\n{restore}"
return asyncio.run(_call_execute(command, use_daemon, session=session))
return asyncio.run(
_call_execute(f"grep {_q(pattern)}", use_daemon, session=session)
@@ -465,8 +535,13 @@ def click(path: str, use_daemon: bool = False, *, session: Any = None) -> dict:
>>> click("/main/button[0]")
{"action": "click", "path": "/main/button[0]", "status": "success"}
"""
+ translated = _translate_path(path)
+ if not translated:
+ raise ValueError(
+ "click: an element name is required — cannot click the tab root."
+ )
return asyncio.run(
- _call_execute(f"click {_q(path)}", use_daemon, session=session)
+ _call_execute(f"click {_q(translated)}", use_daemon, session=session)
)
@@ -538,17 +613,28 @@ def type_text(
) -> dict:
"""Type text into an input element.
- Focuses the element and types in a single ``domshell_execute`` call so
- focus state is guaranteed to be in place when ``type`` runs (one MCP
- round-trip, atomic).
+ Issued as two separate ``domshell_execute`` calls — ``focus``, check
+ for error, then ``type`` only if ``focus`` succeeded. Both share the
+ persisted lane id (via ``session``), so the focus state from the
+ first call carries into the second.
+
+ Why split: DOMShell's multi-line splitter continues past per-line
+ errors (apireno/DOMShell#46). That's the right semantic for cleanup
+ chains like ``cd / grep / cd back`` (the restore must always run)
+ but the WRONG semantic for safety chains like ``focus / type`` — a
+ failed ``focus`` followed by a successful ``type`` would dispatch
+ keys into whatever was previously focused (potentially a password
+ field). Halting between focus and type prevents that.
Args:
path: Path to input element
text: Text to type
use_daemon: Use persistent daemon connection if available
+ session: Harness session whose DOMShell lane id is reused / updated
Returns:
- Dict with action result
+ Dict with action result. If ``focus`` errors, returns the focus
+ result without calling ``type``.
Raises:
ValueError: If ``path`` or ``text`` contains a newline. DOMShell's
@@ -558,8 +644,24 @@ def type_text(
"""
_assert_single_line("path", path)
_assert_single_line("text", text)
- command = f"focus {_q(path)}\ntype {_q(text)}"
- return asyncio.run(_call_execute(command, use_daemon, session=session))
+ translated_path = _translate_path(path)
+ if not translated_path:
+ raise ValueError(
+ "type_text: an element name is required — cannot focus the tab root."
+ )
+ # Relies on DOMShell serializing commands within a lane: the `type`
+ # call below cannot be preempted by another agent's `focus` on the
+ # same lane between these two _call_execute boundaries. If that
+ # contract ever changes upstream, this needs to revert to a single
+ # multi-line call with an alternative safety story.
+ focus_result = asyncio.run(_call_execute(
+ f"focus {_q(translated_path)}", use_daemon, session=session,
+ ))
+ if _is_error(focus_result):
+ return focus_result # don't type — focus didn't land
+ return asyncio.run(_call_execute(
+ f"type {_q(text)}", use_daemon, session=session,
+ ))
# ── Daemon control functions ───────────────────────────────────────────