Skip to content

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

Python

fix(browser): persist DOMShell lane across non-daemon _call_execute calls

apirenoe3e14dd3dc99
diff --git a/browser/agent-harness/cli_anything/browser/browser_cli.py b/browser/agent-harness/cli_anything/browser/browser_cli.py
index e482c8b7d..d0751a953 100644
--- a/browser/agent-harness/cli_anything/browser/browser_cli.py
+++ b/browser/agent-harness/cli_anything/browser/browser_cli.py
@@ -304,7 +304,7 @@ def act_click(path):
"""Click an element at the given path."""
sess = get_session()
use_daemon = sess.daemon_mode
- result = backend.click(path, use_daemon=use_daemon)
+ result = backend.click(path, use_daemon=use_daemon, session=sess)
output(result, f"Clicked: {path}")
@@ -316,7 +316,7 @@ def act_type(path, text):
"""Type text into an input element."""
sess = get_session()
use_daemon = sess.daemon_mode
- result = backend.type_text(path, text, use_daemon=use_daemon)
+ result = backend.type_text(path, text, use_daemon=use_daemon, session=sess)
output(result, f"Typed into: {path}")
diff --git a/browser/agent-harness/cli_anything/browser/core/fs.py b/browser/agent-harness/cli_anything/browser/core/fs.py
index a3e1c6ab9..eced7b991 100644
--- a/browser/agent-harness/cli_anything/browser/core/fs.py
+++ b/browser/agent-harness/cli_anything/browser/core/fs.py
@@ -32,7 +32,7 @@ def list_elements(session: "Session", path: str = "") -> dict:
"""
target_path = path if path else session.working_dir
use_daemon = session.daemon_mode
- return backend.ls(target_path, use_daemon=use_daemon)
+ return backend.ls(target_path, use_daemon=use_daemon, session=session)
def change_directory(session: "Session", path: str) -> dict:
@@ -69,7 +69,7 @@ def change_directory(session: "Session", path: str) -> dict:
path = session.working_dir.rstrip("/") + "/" + path
use_daemon = session.daemon_mode
- result = backend.cd(path, use_daemon=use_daemon)
+ result = backend.cd(path, use_daemon=use_daemon, session=session)
# Only update working_dir if backend succeeded
if isinstance(result, dict) and "error" not in result:
new_working_dir = result.get("path", path)
@@ -93,7 +93,7 @@ def read_element(session: "Session", path: str = "") -> dict:
"""
target_path = path if path else session.working_dir
use_daemon = session.daemon_mode
- return backend.cat(target_path, use_daemon=use_daemon)
+ return backend.cat(target_path, use_daemon=use_daemon, session=session)
def grep_elements(session: "Session", pattern: str, path: str = "") -> dict:
@@ -115,5 +115,9 @@ def grep_elements(session: "Session", pattern: str, path: str = "") -> dict:
use_daemon = session.daemon_mode
prev = session.working_dir or "/"
return backend.grep(
- pattern, path=target_path, prev=prev, use_daemon=use_daemon
+ pattern,
+ path=target_path,
+ prev=prev,
+ use_daemon=use_daemon,
+ session=session,
)
diff --git a/browser/agent-harness/cli_anything/browser/core/page.py b/browser/agent-harness/cli_anything/browser/core/page.py
index 92a939eeb..c4439ad24 100644
--- a/browser/agent-harness/cli_anything/browser/core/page.py
+++ b/browser/agent-harness/cli_anything/browser/core/page.py
@@ -42,7 +42,7 @@ def open_page(session: "Session", url: str) -> dict:
raise ValueError(error_msg)
use_daemon = session.daemon_mode
- result = backend.open_url(url, use_daemon=use_daemon)
+ result = backend.open_url(url, use_daemon=use_daemon, session=session)
session.set_url(url)
session.set_working_dir("/") # Reset to root on new page
return result
@@ -62,7 +62,7 @@ def reload_page(session: "Session") -> dict:
{"status": "reloaded", "url": "https://example.com"}
"""
use_daemon = session.daemon_mode
- result = backend.reload(use_daemon=use_daemon)
+ result = backend.reload(use_daemon=use_daemon, session=session)
return result
@@ -80,7 +80,7 @@ def go_back(session: "Session") -> dict:
{"url": "https://previous.com", "status": "navigated"}
"""
use_daemon = session.daemon_mode
- result = backend.back(use_daemon=use_daemon)
+ result = backend.back(use_daemon=use_daemon, session=session)
# Update session state if backend returned a URL
if isinstance(result, dict) and "url" in result:
@@ -103,7 +103,7 @@ def go_forward(session: "Session") -> dict:
{"url": "https://next.com", "status": "navigated"}
"""
use_daemon = session.daemon_mode
- result = backend.forward(use_daemon=use_daemon)
+ result = backend.forward(use_daemon=use_daemon, session=session)
# Update session state if backend returned a URL
if isinstance(result, dict) and "url" in result:
diff --git a/browser/agent-harness/cli_anything/browser/core/session.py b/browser/agent-harness/cli_anything/browser/core/session.py
index 3422f0373..e8a5b1cb9 100644
--- a/browser/agent-harness/cli_anything/browser/core/session.py
+++ b/browser/agent-harness/cli_anything/browser/core/session.py
@@ -21,6 +21,11 @@ class Session:
- history: Stack of URLs for back navigation
- forward_stack: Stack of URLs for forward navigation
- daemon_mode: Whether persistent daemon connection is active
+ - domshell_lane_id: The DOMShell 2.x lane (Chrome tab-group) the harness
+ has been pinned to. ``None`` until the first ``_call_execute`` reply
+ arrives carrying a ``[lane: <id>]`` marker; thereafter passed as
+ ``group_id`` on every subsequent call so browser state (current tab,
+ cwd, focus) persists across REPL commands in non-daemon mode.
"""
current_url: str = ""
@@ -28,6 +33,7 @@ class Session:
history: list[str] = field(default_factory=list)
forward_stack: list[str] = field(default_factory=list)
daemon_mode: bool = False
+ domshell_lane_id: Optional[str] = None
def set_url(self, url: str, record_history: bool = True) -> None:
"""Set the current URL and update history.
@@ -95,4 +101,5 @@ class Session:
"history_length": len(self.history),
"forward_stack_length": len(self.forward_stack),
"daemon_mode": self.daemon_mode,
+ "domshell_lane_id": self.domshell_lane_id,
}
diff --git a/browser/agent-harness/cli_anything/browser/tests/test_core.py b/browser/agent-harness/cli_anything/browser/tests/test_core.py
index 0b11a2da2..ae44a613e 100644
--- a/browser/agent-harness/cli_anything/browser/tests/test_core.py
+++ b/browser/agent-harness/cli_anything/browser/tests/test_core.py
@@ -216,7 +216,7 @@ class TestFsModule:
result = fs.list_elements(sess)
- mock_ls.assert_called_once_with("/main", use_daemon=False)
+ mock_ls.assert_called_once_with("/main", use_daemon=False, session=sess)
def test_list_elements_with_path(self):
"""Listing elements with explicit path overrides working_dir."""
@@ -228,7 +228,7 @@ class TestFsModule:
result = fs.list_elements(sess, "/div")
- mock_ls.assert_called_once_with("/div", use_daemon=False)
+ mock_ls.assert_called_once_with("/div", use_daemon=False, session=sess)
def test_list_elements_empty_path_uses_working_dir(self):
"""Listing with empty path uses session working_dir."""
@@ -240,7 +240,7 @@ class TestFsModule:
result = fs.list_elements(sess, "")
- mock_ls.assert_called_once_with("/main", use_daemon=False)
+ mock_ls.assert_called_once_with("/main", use_daemon=False, session=sess)
def test_change_directory_absolute_path(self):
"""Changing to absolute path updates working_dir."""
@@ -252,7 +252,7 @@ class TestFsModule:
result = fs.change_directory(sess, "/main")
assert sess.working_dir == "/main"
- mock_cd.assert_called_once_with("/main", use_daemon=False)
+ mock_cd.assert_called_once_with("/main", use_daemon=False, session=sess)
def test_change_directory_relative_parent(self):
"""Changing to .. goes up one level."""
@@ -265,7 +265,7 @@ class TestFsModule:
result = fs.change_directory(sess, "..")
assert sess.working_dir == "/main"
- mock_cd.assert_called_once_with("/main", use_daemon=False)
+ mock_cd.assert_called_once_with("/main", use_daemon=False, session=sess)
def test_change_directory_parent_from_root(self):
"""Changing to .. from root stays at root."""
@@ -300,7 +300,7 @@ class TestFsModule:
result = fs.change_directory(sess, "div[0]")
assert sess.working_dir == "/main/div[0]"
- mock_cd.assert_called_once_with("/main/div[0]", use_daemon=False)
+ mock_cd.assert_called_once_with("/main/div[0]", use_daemon=False, session=sess)
def test_read_element(self):
"""Reading element calls backend."""
@@ -315,7 +315,7 @@ class TestFsModule:
result = fs.read_element(sess, "/main/button[0]")
- mock_cat.assert_called_once_with("/main/button[0]", use_daemon=False)
+ mock_cat.assert_called_once_with("/main/button[0]", use_daemon=False, session=sess)
def test_read_element_empty_path_uses_working_dir(self):
"""Reading with empty path uses session working_dir."""
@@ -327,7 +327,7 @@ class TestFsModule:
result = fs.read_element(sess, "")
- mock_cat.assert_called_once_with("/main", use_daemon=False)
+ mock_cat.assert_called_once_with("/main", use_daemon=False, session=sess)
def test_grep_elements(self):
"""Grepping calls backend with pattern and session cwd as path."""
@@ -341,7 +341,7 @@ class TestFsModule:
result = fs.grep_elements(sess, "Login")
mock_grep.assert_called_once_with(
- "Login", path="/", prev="/", use_daemon=False
+ "Login", path="/", prev="/", use_daemon=False, session=sess
)
def test_grep_elements_with_path(self):
@@ -354,7 +354,7 @@ class TestFsModule:
result = fs.grep_elements(sess, "Login", "/main")
mock_grep.assert_called_once_with(
- "Login", path="/main", prev="/", use_daemon=False
+ "Login", path="/main", prev="/", use_daemon=False, session=sess
)
@@ -373,7 +373,7 @@ class TestDaemonMode:
result = fs.list_elements(sess)
- mock_ls.assert_called_once_with("/", use_daemon=True)
+ mock_ls.assert_called_once_with("/", use_daemon=True, session=sess)
def test_normal_mode_does_not_use_daemon(self):
"""Commands don't use daemon mode when session.daemon_mode is False."""
@@ -385,4 +385,4 @@ class TestDaemonMode:
result = fs.list_elements(sess)
- mock_ls.assert_called_once_with("/", use_daemon=False)
+ mock_ls.assert_called_once_with("/", use_daemon=False, session=sess)
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 f0660d67e..0b00b253c 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
@@ -22,7 +22,8 @@ def test_grep_unrooted_produces_single_grep_call(mock_call):
backend.grep("Login")
- assert mock_call.call_args_list == [call("grep Login", False)]
+ # session=None when no session is passed (default).
+ assert mock_call.call_args_list == [call("grep Login", False, session=None)]
@patch.object(backend, "_call_execute", new_callable=AsyncMock)
@@ -40,7 +41,7 @@ def test_grep_rooted_emits_single_multiline_call(mock_call):
backend.grep("Login", path="/main", prev="/")
assert mock_call.call_args_list == [
- call("cd /main\ngrep Login\ncd /", False),
+ call("cd /main\ngrep Login\ncd /", False, session=None),
]
@@ -108,7 +109,7 @@ def test_grep_keyword_use_daemon_still_works():
with patch.object(backend, "_call_execute", new_callable=AsyncMock) as mock_call:
mock_call.return_value = {}
backend.grep("Login", use_daemon=True)
- assert mock_call.call_args_list == [call("grep Login", True)]
+ assert mock_call.call_args_list == [call("grep Login", True, session=None)]
# ── type_text: focus+type pairing and newline injection guard ─────────
@@ -122,7 +123,7 @@ def test_type_text_emits_focus_then_type_in_one_call(mock_call):
backend.type_text("search_input", "machine learning")
assert mock_call.call_args_list == [
- call("focus search_input\ntype 'machine learning'", False),
+ call("focus search_input\ntype 'machine learning'", False, session=None),
]
@@ -218,3 +219,196 @@ def test_cd_rejects_newlines(mock_call):
mock_call.return_value = {}
with pytest.raises(ValueError, match="[Nn]ewline"):
backend.cd("/main\nclick /admin")
+
+
+# ── DOMShell lane persistence across _call_execute calls ─────────────
+#
+# DOMShell 2.x assigns a fresh lane (Chrome tab-group) to every new MCP
+# session. In non-daemon mode each _call_execute opens its own stdio
+# ClientSession, so without explicit group_id every command would land
+# in a brand-new lane and lose browser state from the previous call.
+# The fix: parse the trailing "[lane: <id>]" marker DOMShell appends to
+# each reply, store it on the harness Session, and pass group_id=<id>
+# on every subsequent call.
+
+
+from types import SimpleNamespace
+
+from cli_anything.browser.core.session import Session
+
+
+def _make_result(text: str):
+ """Build a fake CallToolResult whose ``content[0].text`` is ``text``."""
+ return SimpleNamespace(content=[SimpleNamespace(text=text)])
+
+
+# ── _extract_lane_id ────────────────────────────────────────────────
+
+
+def test_extract_lane_id_parses_trailing_marker():
+ assert backend._extract_lane_id(_make_result("✓ ls done\n[lane: 12345]")) == "12345"
+
+
+def test_extract_lane_id_handles_trailing_whitespace():
+ assert backend._extract_lane_id(_make_result("✓ ls done\n[lane: lane-abc]\n")) == "lane-abc"
+
+
+def test_extract_lane_id_ignores_shared_marker():
+ """`[lane: shared]` is DOMShell's no-isolation sentinel — must not pin to it."""
+ assert backend._extract_lane_id(_make_result("✓ ls done\n[lane: shared]")) is None
+
+
+def test_extract_lane_id_returns_none_when_marker_absent():
+ assert backend._extract_lane_id(_make_result("✓ ls done")) is None
+
+
+def test_extract_lane_id_returns_none_for_empty_text():
+ assert backend._extract_lane_id(_make_result("")) is None
+
+
+def test_extract_lane_id_returns_none_when_content_missing():
+ assert backend._extract_lane_id(SimpleNamespace()) is None
+
+
+# ── lane capture + propagation ──────────────────────────────────────
+
+
[email protected](backend, "_call_execute", new_callable=AsyncMock)
+def test_first_call_omits_group_id_and_captures_lane(mock_call):
+ """A session with no stored lane: first call has no group_id, captures the returned lane."""
+ sess = Session() # domshell_lane_id starts as None
+ mock_call.return_value = _make_result("✓\n[lane: 12345]")
+
+ backend.click("submit_btn", session=sess)
+
+ # The session= kwarg the wrapper passes is the Session object itself;
+ # _call_execute is responsible for translating session.domshell_lane_id
+ # into the wire-format group_id. We only assert the call signature here.
+ assert mock_call.call_args == call("click submit_btn", False, session=sess)
+ # _call_execute is mocked, so we exercise _capture_lane directly to
+ # verify the parser hookup that the real _call_execute would do.
+ backend._capture_lane(sess, mock_call.return_value)
+ assert sess.domshell_lane_id == "12345"
+
+
+def test_capture_lane_updates_session():
+ sess = Session()
+ backend._capture_lane(sess, _make_result("✓\n[lane: lane-XYZ]"))
+ assert sess.domshell_lane_id == "lane-XYZ"
+
+
+def test_capture_lane_no_op_when_session_is_none():
+ """Direct backend callers without a session must not crash."""
+ backend._capture_lane(None, _make_result("✓\n[lane: 12345]")) # no exception
+
+
+def test_capture_lane_no_op_when_marker_missing():
+ sess = Session()
+ sess.domshell_lane_id = "preexisting"
+ backend._capture_lane(sess, _make_result("✓ done"))
+ # No marker → don't clobber the previously-captured lane.
+ assert sess.domshell_lane_id == "preexisting"
+
+
+def test_capture_lane_ignores_shared_marker():
+ sess = Session()
+ sess.domshell_lane_id = "preexisting"
+ backend._capture_lane(sess, _make_result("✓\n[lane: shared]"))
+ assert sess.domshell_lane_id == "preexisting"
+
+
+# ── End-to-end: lane reuse on subsequent calls ───────────────────────
+
+
+def test_call_execute_includes_group_id_when_lane_is_set():
+ """When session.domshell_lane_id is set, _call_execute sends it as group_id.
+
+ We bypass the stdio_client / ClientSession plumbing entirely by patching
+ them — what we want to assert is the arguments dict that gets passed to
+ ``call_tool``.
+ """
+ sess = Session()
+ sess.domshell_lane_id = "lane-7"
+
+ fake_tool = AsyncMock(return_value=_make_result("✓\n[lane: lane-7]"))
+
+ fake_mcp_session = AsyncMock()
+ fake_mcp_session.__aenter__.return_value = fake_mcp_session
+ fake_mcp_session.__aexit__.return_value = None
+ fake_mcp_session.initialize = AsyncMock()
+ fake_mcp_session.call_tool = fake_tool
+
+ fake_stdio = AsyncMock()
+ fake_stdio.__aenter__.return_value = (object(), object())
+ fake_stdio.__aexit__.return_value = None
+
+ with patch.object(backend, "stdio_client", return_value=fake_stdio), \
+ patch.object(backend, "ClientSession", return_value=fake_mcp_session), \
+ patch.object(backend, "_build_server_args", return_value=[]):
+ import asyncio as _aio
+ _aio.run(backend._call_execute("ls /", session=sess))
+
+ name, arguments = fake_tool.call_args.args
+ assert name == "domshell_execute"
+ assert arguments == {"command": "ls /", "group_id": "lane-7"}
+
+
+def test_call_execute_omits_group_id_when_lane_is_none():
+ """First-call shape: no stored lane → no group_id; DOMShell auto-assigns."""
+ sess = Session() # lane is None
+ fake_tool = AsyncMock(return_value=_make_result("✓\n[lane: brand-new]"))
+
+ fake_mcp_session = AsyncMock()
+ fake_mcp_session.__aenter__.return_value = fake_mcp_session
+ fake_mcp_session.__aexit__.return_value = None
+ fake_mcp_session.initialize = AsyncMock()
+ fake_mcp_session.call_tool = fake_tool
+
+ fake_stdio = AsyncMock()
+ fake_stdio.__aenter__.return_value = (object(), object())
+ fake_stdio.__aexit__.return_value = None
+
+ with patch.object(backend, "stdio_client", return_value=fake_stdio), \
+ patch.object(backend, "ClientSession", return_value=fake_mcp_session), \
+ patch.object(backend, "_build_server_args", return_value=[]):
+ import asyncio as _aio
+ _aio.run(backend._call_execute("ls /", session=sess))
+
+ arguments = fake_tool.call_args.args[1]
+ assert "group_id" not in arguments
+ # The auto-assigned lane gets captured for next time.
+ assert sess.domshell_lane_id == "brand-new"
+
+
+def test_distinct_sessions_have_isolated_lanes():
+ """Two sessions track lanes independently — no cross-contamination."""
+ s1 = Session()
+ s2 = Session()
+ backend._capture_lane(s1, _make_result("✓\n[lane: lane-A]"))
+ backend._capture_lane(s2, _make_result("✓\n[lane: lane-B]"))
+ assert s1.domshell_lane_id == "lane-A"
+ assert s2.domshell_lane_id == "lane-B"
+
+
+# ── Keyword-only enforcement on session= ─────────────────────────────
+
+
+def test_session_is_keyword_only_on_click():
+ """Discipline matches grep's earlier keyword-only fix."""
+ with pytest.raises(TypeError):
+ backend.click("submit_btn", False, None) # type: ignore[misc]
+
+
+def test_session_is_keyword_only_on_ls():
+ with pytest.raises(TypeError):
+ backend.ls("/", False, None) # type: ignore[misc]
+
+
+def test_session_is_keyword_only_on_type_text():
+ with pytest.raises(TypeError):
+ backend.type_text("input", "hello", False, None) # type: ignore[misc]
+
+
+def test_session_is_keyword_only_on_open_url():
+ with pytest.raises(TypeError):
+ backend.open_url("https://example.com", False, None) # type: ignore[misc]
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 9247225b5..c2055245a 100644
--- a/browser/agent-harness/cli_anything/browser/utils/domshell_backend.py
+++ b/browser/agent-harness/cli_anything/browser/utils/domshell_backend.py
@@ -19,6 +19,7 @@ that single tool.
import asyncio
import os
+import re
import shlex
import subprocess
import shutil
@@ -140,6 +141,47 @@ def _q(arg: str) -> str:
return shlex.quote(arg)
+# DOMShell 2.x appends a "[lane: <id>]" marker as the last line of every
+# domshell_execute reply. We parse it out and store it on the harness
+# Session so subsequent calls can pass group_id=<id> and stay pinned to
+# the same Chrome tab-group (i.e. same browser state).
+_LANE_LINE = re.compile(r"\[lane:\s*([^\]\s]+)\s*\]\s*$")
+
+
+def _extract_lane_id(result: Any) -> Optional[str]:
+ """Parse the trailing ``[lane: <id>]`` marker DOMShell appends to replies.
+
+ Returns the lane id, or ``None`` if no marker is present, the text is
+ empty, or the marker reports the default "shared" lane (which is
+ DOMShell's no-isolation sentinel and not something we want to pin to).
+ """
+ text = ""
+ content = getattr(result, "content", None)
+ if content:
+ for c in content:
+ piece = getattr(c, "text", None)
+ if piece:
+ text += piece
+ if not text:
+ return None
+ m = _LANE_LINE.search(text.strip())
+ if not m:
+ return None
+ lane = m.group(1).strip()
+ if not lane or lane == "shared":
+ return None
+ return lane
+
+
+def _capture_lane(session: Any, result: Any) -> None:
+ """Update ``session.domshell_lane_id`` from a ``_call_execute`` result."""
+ if session is None:
+ return
+ lane = _extract_lane_id(result)
+ if lane:
+ session.domshell_lane_id = lane
+
+
def _assert_single_line(field: str, value: str) -> None:
"""Reject newline characters in a user-supplied string.
@@ -156,13 +198,22 @@ def _assert_single_line(field: str, value: str) -> None:
)
-async def _call_execute(command: str, use_daemon: bool = False) -> Any:
+async def _call_execute(
+ command: str,
+ use_daemon: bool = False,
+ *,
+ session: Any = None,
+) -> Any:
"""Run a DOMShell command via the single `domshell_execute` MCP tool.
Args:
command: DOMShell command string. May contain newlines for multi-command
execution — each line runs in order in the same shell state.
use_daemon: If True, use persistent daemon connection (if available)
+ session: Harness ``Session`` whose ``domshell_lane_id`` should be
+ forwarded as ``group_id`` (when set) and updated from the result
+ (when DOMShell returns a ``[lane: <id>]`` marker). Pass ``None``
+ for one-off direct calls that don't need cross-call state.
Returns:
Tool result as returned by MCP server
@@ -172,12 +223,24 @@ async def _call_execute(command: str, use_daemon: bool = False) -> Any:
"""
global _daemon_session, _daemon_read, _daemon_write
+ arguments: dict[str, Any] = {"command": command}
+ # Reuse the previously-captured DOMShell lane so this call lands in the
+ # same Chrome tab-group as the prior commands in this session. Without
+ # this, every fresh stdio ClientSession would be assigned a brand-new
+ # lane and `page open` / `fs ls` etc. would run in disjoint browser
+ # state. The very first call leaves group_id unset so DOMShell
+ # auto-assigns; _capture_lane stores that id on the session for the
+ # next call.
+ if session is not None and getattr(session, "domshell_lane_id", None):
+ arguments["group_id"] = session.domshell_lane_id
+
if use_daemon and _daemon_session is not None:
# Use persistent daemon connection
try:
result = await _daemon_session.call_tool(
- "domshell_execute", {"command": command}
+ "domshell_execute", arguments
)
+ _capture_lane(session, result)
return result
except Exception:
# Daemon died, fall back to spawning new server
@@ -191,11 +254,12 @@ async def _call_execute(command: str, use_daemon: bool = False) -> Any:
try:
async with stdio_client(server_params) as (read, write):
- async with ClientSession(read, write) as session:
- await session.initialize()
- result = await session.call_tool(
- "domshell_execute", {"command": command}
+ async with ClientSession(read, write) as mcp_session:
+ await mcp_session.initialize()
+ result = await mcp_session.call_tool(
+ "domshell_execute", arguments
)
+ _capture_lane(session, result)
return result
except Exception as e:
raise RuntimeError(
@@ -275,12 +339,13 @@ def daemon_started() -> bool:
# `domshell_execute`. The public Python API is unchanged from the
# pre-2.0.0 per-tool wrappers.
-def ls(path: str = "/", use_daemon: bool = False) -> dict:
+def ls(path: str = "/", *, use_daemon: bool = False, session: Any = None) -> dict:
"""List directory contents in the accessibility tree.
Args:
path: Path in accessibility tree (e.g., "/", "/main", "/main/div[0]")
use_daemon: Use persistent daemon connection if available
+ session: Harness session whose DOMShell lane id is reused / updated
Returns:
Dict with 'entries' key containing list of accessible elements
@@ -290,15 +355,16 @@ def ls(path: str = "/", use_daemon: bool = False) -> dict:
{"path": "/", "entries": [{"name": "main", "role": "landmark", ...}]}
"""
command = f"ls {_q(path)}" if path else "ls"
- return asyncio.run(_call_execute(command, use_daemon))
+ return asyncio.run(_call_execute(command, use_daemon, session=session))
-def cd(path: str, use_daemon: bool = False) -> dict:
+def cd(path: str, *, use_daemon: bool = False, session: Any = None) -> dict:
"""Change directory in the accessibility tree.
Args:
path: Target path
use_daemon: Use persistent daemon connection if available
+ session: Harness session whose DOMShell lane id is reused / updated
Returns:
Dict with 'path' key confirming current location
@@ -307,15 +373,16 @@ def cd(path: str, use_daemon: bool = False) -> dict:
>>> cd("/main/div[0]")
{"path": "/main/div[0]", "element": {...}}
"""
- return asyncio.run(_call_execute(f"cd {_q(path)}", use_daemon))
+ return asyncio.run(_call_execute(f"cd {_q(path)}", use_daemon, session=session))
-def cat(path: str, use_daemon: bool = False) -> dict:
+def cat(path: str, *, use_daemon: bool = False, session: Any = None) -> dict:
"""Read element content from the accessibility tree.
Args:
path: Path to element
use_daemon: Use persistent daemon connection if available
+ session: Harness session whose DOMShell lane id is reused / updated
Returns:
Dict with element details including text, role, attributes
@@ -324,7 +391,7 @@ def cat(path: str, use_daemon: bool = False) -> dict:
>>> cat("/main/button[0]")
{"name": "Submit", "role": "button", "text": "Submit", ...}
"""
- return asyncio.run(_call_execute(f"cat {_q(path)}", use_daemon))
+ return asyncio.run(_call_execute(f"cat {_q(path)}", use_daemon, session=session))
def grep(
@@ -333,6 +400,7 @@ def grep(
path: str = "",
prev: str = "/",
use_daemon: bool = False,
+ session: Any = None,
) -> dict:
"""Search for pattern in the accessibility tree.
@@ -373,16 +441,19 @@ def grep(
_assert_single_line("path", path)
_assert_single_line("prev", prev)
command = f"cd {_q(path)}\ngrep {_q(pattern)}\ncd {_q(prev)}"
- return asyncio.run(_call_execute(command, use_daemon))
- return asyncio.run(_call_execute(f"grep {_q(pattern)}", use_daemon))
+ return asyncio.run(_call_execute(command, use_daemon, session=session))
+ return asyncio.run(
+ _call_execute(f"grep {_q(pattern)}", use_daemon, session=session)
+ )
-def click(path: str, use_daemon: bool = False) -> dict:
+def click(path: str, *, use_daemon: bool = False, session: Any = None) -> dict:
"""Click an element in the accessibility tree.
Args:
path: Path to element to click
use_daemon: Use persistent daemon connection if available
+ session: Harness session whose DOMShell lane id is reused / updated
Returns:
Dict with action result
@@ -391,15 +462,18 @@ def click(path: str, use_daemon: bool = False) -> dict:
>>> click("/main/button[0]")
{"action": "click", "path": "/main/button[0]", "status": "success"}
"""
- return asyncio.run(_call_execute(f"click {_q(path)}", use_daemon))
+ return asyncio.run(
+ _call_execute(f"click {_q(path)}", use_daemon, session=session)
+ )
-def open_url(url: str, use_daemon: bool = False) -> dict:
+def open_url(url: str, *, use_daemon: bool = False, session: Any = None) -> dict:
"""Navigate to a URL in Chrome.
Args:
url: URL to navigate to
use_daemon: Use persistent daemon connection if available
+ session: Harness session whose DOMShell lane id is reused / updated
Returns:
Dict with navigation result
@@ -408,46 +482,57 @@ def open_url(url: str, use_daemon: bool = False) -> dict:
>>> open_url("https://example.com")
{"url": "https://example.com", "status": "loaded"}
"""
- return asyncio.run(_call_execute(f"open {_q(url)}", use_daemon))
+ return asyncio.run(
+ _call_execute(f"open {_q(url)}", use_daemon, session=session)
+ )
-def reload(use_daemon: bool = False) -> dict:
+def reload(*, use_daemon: bool = False, session: Any = None) -> dict:
"""Reload the current page.
Args:
use_daemon: Use persistent daemon connection if available
+ session: Harness session whose DOMShell lane id is reused / updated
Returns:
Dict with reload result
"""
- return asyncio.run(_call_execute("refresh", use_daemon))
+ return asyncio.run(_call_execute("refresh", use_daemon, session=session))
-def back(use_daemon: bool = False) -> dict:
+def back(*, use_daemon: bool = False, session: Any = None) -> dict:
"""Navigate back in history.
Args:
use_daemon: Use persistent daemon connection if available
+ session: Harness session whose DOMShell lane id is reused / updated
Returns:
Dict with navigation result
"""
- return asyncio.run(_call_execute("back", use_daemon))
+ return asyncio.run(_call_execute("back", use_daemon, session=session))
-def forward(use_daemon: bool = False) -> dict:
+def forward(*, use_daemon: bool = False, session: Any = None) -> dict:
"""Navigate forward in history.
Args:
use_daemon: Use persistent daemon connection if available
+ session: Harness session whose DOMShell lane id is reused / updated
Returns:
Dict with navigation result
"""
- return asyncio.run(_call_execute("forward", use_daemon))
+ return asyncio.run(_call_execute("forward", use_daemon, session=session))
-def type_text(path: str, text: str, use_daemon: bool = False) -> dict:
+def type_text(
+ path: str,
+ text: str,
+ *,
+ use_daemon: bool = False,
+ session: Any = None,
+) -> dict:
"""Type text into an input element.
Focuses the element and types in a single ``domshell_execute`` call so
@@ -471,7 +556,7 @@ def type_text(path: str, text: str, use_daemon: bool = False) -> dict:
_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))
+ return asyncio.run(_call_execute(command, use_daemon, session=session))
# ── Daemon control functions ───────────────────────────────────────────