[Refactor] Driver architecture for browser_move

docs/en/2.Development Guide/API Docs/openjiuwen.harness/subagents/browser_agent.md

@@ -14,10 +14,10 @@ The tools available to the sub-agent — both the Playwright MCP primitives and
 | [Capability allowlist](#browser-capabilities) | Playwright tools are grouped into named capabilities (`core`, `pdf`, `vision`, `devtools`, `config`, `network`, `storage`, `testing`). The caller selects capabilities per task; only the expanded tool allowlist is exposed to the model. |
 | [Runtime helper tools](../tools/browser_tools.md#runtime-helper-tools) | Page probes, batch interaction, custom actions, cancellation, and health checks, injected alongside the Playwright primitives. |
 | [Browser options](#browser-options) | Headless vs. headed operation, browser engine choice, session persistence, viewport/device emulation, proxies, and output directories. |
-| [Browser instance isolation](#class-openjiuwenharnesstoolsbrowser_moveplaywright_runtimeconfigbrowserinstanceconfig) | `BrowserInstanceConfig` gives each agent its own browser (own MCP server, Chrome profile, and CDP port); agents sharing a key intentionally share one browser. |
+| [Browser instance isolation](#class-openjiuwenharnesstoolsbrowser_moveruntimeconfigbrowserinstanceconfig) | `BrowserInstanceConfig` gives each agent its own browser (own MCP server, Chrome profile, and CDP port); agents sharing a key intentionally share one browser. |
 | [Driver modes](#driver-modes) | `managed` (launch a dedicated local Chrome), `remote` (attach to an existing CDP endpoint), or `extension` (drive a running browser through the Playwright MCP extension bridge). |
-| [Progress and resumability](#class-openjiuwenharnesstoolsbrowser_moveplaywright_runtimeruntimebrowserruntimerail) | `BrowserRuntimeRail` persists task progress into the session, injects it back as continuation context on the next invocation, and converts incomplete runs into structured failure summaries. |
-| [Guardrails](#class-openjiuwenharnesstoolsbrowser_moveplaywright_runtimeconfigbrowserrunguardrails) | Step, failure, and timeout limits with automatic retry and optional resume after a max-iterations stop. |
+| [Progress and resumability](#class-openjiuwenharnesstoolsbrowser_moveruntimeruntimebrowserruntimerail) | `BrowserRuntimeRail` persists task progress into the session, injects it back as continuation context on the next invocation, and converts incomplete runs into structured failure summaries. |
+| [Guardrails](#class-openjiuwenharnesstoolsbrowser_moveruntimeconfigrunguardrails) | Step, failure, and timeout limits with automatic retry and optional resume after a max-iterations stop. |
 | [Observability](#observability) | A dedicated `logs/browser_agent.log` file and redacted structured status telemetry (`[BROWSER_SUBAGENT]` records). |
 
 ---
@@ -53,9 +53,9 @@ create_browser_agent(
 Create the browser sub-agent. On top of a plain deep agent, this factory:
 
 1. Resolves the requested `browser_capabilities` against the trusted capability catalog (unknown names raise `ValueError` listing the available capabilities).
-2. Builds a [`BrowserAgentRuntime`](#class-openjiuwenharnesstoolsbrowser_moveplaywright_runtimeruntimebrowseragentruntime) from `settings` (or from the model's client config / environment when `settings` is omitted).
+2. Builds a [`BrowserAgentRuntime`](#class-openjiuwenharnesstoolsbrowser_moveruntimeruntimebrowseragentruntime) from `settings` (or from the model's client config / environment when `settings` is omitted).
 3. Appends the [runtime helper tools](../tools/browser_tools.md#runtime-helper-tools) to any caller-provided `tools`.
-4. Appends a [`BrowserRuntimeRail`](#class-openjiuwenharnesstoolsbrowser_moveplaywright_runtimeruntimebrowserruntimerail) to any caller-provided `rails`.
+4. Appends a [`BrowserRuntimeRail`](#class-openjiuwenharnesstoolsbrowser_moveruntimeruntimebrowserruntimerail) to any caller-provided `rails`.
 
 The default system prompt (locale-specific, `cn`/`en`) instructs the agent to prefer compact probes over snapshots, to use `browser_run_code` only with a known selector, and to claim completion only when the outcome is evidenced on the page.
 
@@ -76,9 +76,9 @@ The default system prompt (locale-specific, `cn`/`en`) instructs the agent to pr
 - **sys_operation** (SysOperation, optional): System operation. Default: `None`.
 - **language** (str, optional): `"cn"` or `"en"`; anything else falls back to `"cn"`. Default: `None`.
 - **prompt_mode** (str, optional): Prompt mode. Default: `None`.
-- **settings** ([RuntimeSettings](#class-openjiuwenharnesstoolsbrowser_moveplaywright_runtimeconfigruntimesettings), optional): Full browser runtime override (provider, API key/base, model, MCP config, guardrails, instance). Default: resolved from `model` or environment variables.
+- **settings** ([RuntimeSettings](#class-openjiuwenharnesstoolsbrowser_moveruntimeconfigruntimesettings), optional): Full browser runtime override (provider, API key/base, model, MCP config, guardrails, instance). Default: resolved from `model` or environment variables.
 - **browser_key** (str, optional): Shorthand for `browser_instance=BrowserInstanceConfig(key=...)`. Default: `None`.
-- **browser_instance** ([BrowserInstanceConfig](#class-openjiuwenharnesstoolsbrowser_moveplaywright_runtimeconfigbrowserinstanceconfig) | dict, optional): Per-instance browser identity. A plain dict is accepted so the identity can travel as serializable `factory_kwargs`. Default: `None` (legacy shared, environment-driven browser).
+- **browser_instance** ([BrowserInstanceConfig](#class-openjiuwenharnesstoolsbrowser_moveruntimeconfigbrowserinstanceconfig) | dict, optional): Per-instance browser identity. A plain dict is accepted so the identity can travel as serializable `factory_kwargs`. Default: `None` (legacy shared, environment-driven browser).
 - **browser_capabilities** (list[str], optional): Task-scoped capability names from the [capability catalog](#browser-capabilities). `core` is always included. `None` means no allowlist restriction. Default: `None`.
 - ****config_kwargs**: Additional configuration arguments forwarded to `create_deep_agent`.
 
@@ -169,7 +169,7 @@ The sub-session ID for `browser_agent` is deterministic (`{parent_session}_sub_b
 
 ## Browser Capabilities
 
-Module: `openjiuwen.harness.tools.browser_move.playwright_runtime.browser_capabilities`
+Module: `openjiuwen.harness.tools.browser_move.surfaces.browser.capabilities`
 
 Playwright MCP tools are grouped into a trusted, explicit catalog of capabilities. Matching is by exact tool name — never by prefix — so a newly introduced Playwright tool is not exposed before its policy is reviewed. The main agent selects capability names per task; the resolver performs no task interpretation of its own.
 
@@ -249,7 +249,7 @@ Headed operation is the safer default for sites with bot detection and for debug
 ### Timeouts
 
 - **Per tool call**: `PLAYWRIGHT_MCP_TIMEOUT_S` / `BROWSER_TIMEOUT_S` (default `180`) bounds each MCP tool invocation.
-- **Per task attempt**: `BrowserRunGuardrails.timeout_s` (default `180`) bounds a whole delegated browser task; see [Guardrails](#class-openjiuwenharnesstoolsbrowser_moveplaywright_runtimeconfigbrowserrunguardrails).
+- **Per task attempt**: `RunGuardrails.timeout_s` (default `180`) bounds a whole delegated browser task; see [Guardrails](#class-openjiuwenharnesstoolsbrowser_moveruntimeconfigrunguardrails).
 - **Per batch step**: `browser_batch_interact` clamps step timeouts to 250–30000 ms with a global batch cap of 90 s.
 
 ### Output directories
@@ -258,7 +258,7 @@ The runtime resolves a working directory (`PLAYWRIGHT_RUNTIME_MCP_CWD`, default:
 
 ---
 
-## class openjiuwen.harness.tools.browser_move.playwright_runtime.config.BrowserInstanceConfig
+## class openjiuwen.harness.tools.browser_move.surfaces.browser.runner.settings.BrowserInstanceConfig
 
 ```python
 @dataclass(frozen=True)
@@ -276,6 +276,7 @@ Per-instance browser identity, used to isolate one browser per agent. All fields
 - **profile_name** (str): Managed profile name. Empty falls back to the key, then `BROWSER_PROFILE_NAME`.
 - **cdp_url** (str): Explicit CDP endpoint for remote mode; wins over the shared environment endpoint.
 - **browser_binary** (str): Optional Chrome binary path override.
+- **launch_args** (str): Playwright MCP launch arguments in the `PLAYWRIGHT_MCP_ARGS` format (a shell-style string or a JSON list). Empty defers to `PLAYWRIGHT_MCP_ARGS`, then the default; a caller that decides headless or isolated mode per run sets this instead of the environment.
 
 ### Driver Modes
 
@@ -285,7 +286,7 @@ Per-instance browser identity, used to isolate one browser per agent. All fields
 
 ---
 
-## class openjiuwen.harness.tools.browser_move.playwright_runtime.config.RuntimeSettings
+## class openjiuwen.harness.tools.browser_move.surfaces.browser.runner.settings.RuntimeSettings
 
 ```python
 @dataclass(frozen=True)
@@ -301,18 +302,18 @@ Resolved browser runtime settings, stored in `SubAgentConfig.factory_kwargs` and
 - **api_base** (str): Model API base URL.
 - **model_name** (str): Model name for the nested browser worker.
 - **mcp_cfg** (McpServerConfig): Playwright MCP server configuration (stdio; command defaults to `npx -y @playwright/mcp@0.0.78` with the full capability list enabled via `--caps=`).
-- **guardrails** ([BrowserRunGuardrails](#class-openjiuwenharnesstoolsbrowser_moveplaywright_runtimeconfigbrowserrunguardrails)): Run guardrails.
-- **instance** ([BrowserInstanceConfig](#class-openjiuwenharnesstoolsbrowser_moveplaywright_runtimeconfigbrowserinstanceconfig), optional): Per-instance browser identity.
+- **guardrails** ([RunGuardrails](#class-openjiuwenharnesstoolsbrowser_moveruntimeconfigrunguardrails)): Run guardrails.
+- **instance** ([BrowserInstanceConfig](#class-openjiuwenharnesstoolsbrowser_moveruntimeconfigbrowserinstanceconfig), optional): Per-instance browser identity.
 
 Use `build_runtime_settings(instance)` to resolve everything from environment variables, or let `create_browser_agent` derive provider/key/base/model from the `Model` object's client config.
 
 ---
 
-## class openjiuwen.harness.tools.browser_move.playwright_runtime.config.BrowserRunGuardrails
+## class openjiuwen.harness.tools.browser_move.runtime.config.RunGuardrails
 
 ```python
 @dataclass
-class BrowserRunGuardrails
+class RunGuardrails
 ```
 
 Limits applied to browser task runs. Built from environment variables by `build_browser_guardrails()`.
@@ -329,7 +330,7 @@ Retryable transport failures (detached frame, target closed, page crash, `net::E
 
 ---
 
-## class openjiuwen.harness.tools.browser_move.playwright_runtime.runtime.BrowserAgentRuntime
+## class openjiuwen.harness.tools.browser_move.surfaces.browser.runner.facade.BrowserAgentRuntime
 
 ```python
 class BrowserAgentRuntime(
@@ -338,7 +339,7 @@ class BrowserAgentRuntime(
     api_base: str,
     model_name: str,
     mcp_cfg: McpServerConfig,
-    guardrails: BrowserRunGuardrails,
+    guardrails: RunGuardrails,
     instance: BrowserInstanceConfig | None = None,
     allowed_tool_names: Iterable[str] | None = None,
 )
@@ -359,7 +360,7 @@ Runtime kernel shared by all browser helper tools. Owns the underlying `BrowserS
 
 ---
 
-## class openjiuwen.harness.tools.browser_move.playwright_runtime.runtime.BrowserRuntimeRail
+## class openjiuwen.harness.tools.browser_move.surfaces.browser.rails.runtime_rail.BrowserRuntimeRail
 
 ```python
 class BrowserRuntimeRail(runtime: BrowserAgentRuntime)

docs/en/2.Development Guide/API Docs/openjiuwen.harness/tools/browser_tools.md

@@ -112,9 +112,9 @@ Session-state access — cookies, localStorage, sessionStorage, and Playwright s
 
 ## Runtime Helper Tools
 
-Module: `openjiuwen.harness.tools.browser_move.playwright_runtime.runtime_tools`
+Module: `openjiuwen.harness.tools.browser_move.surfaces.browser.runner.tools`
 
-Deterministic helpers backed by the shared [`BrowserAgentRuntime`](../subagents/browser_agent.md#class-openjiuwenharnesstoolsbrowser_moveplaywright_runtimeruntimebrowseragentruntime). They are always injected, regardless of the capability selection.
+Deterministic helpers backed by the shared [`BrowserAgentRuntime`](../subagents/browser_agent.md#class-openjiuwenharnesstoolsbrowser_moveruntimeruntimebrowseragentruntime). They are always injected, regardless of the capability selection.
 
 | Tool | Description |
 |---|---|

docs/zh/2.开发指南/API文档/openjiuwen.harness/subagents/浏览器子智能体.md

@@ -17,7 +17,7 @@
 | [浏览器实例隔离](#class-browserinstanceconfig) | `BrowserInstanceConfig` 为每个智能体分配独立浏览器（独立 MCP 服务器、Chrome 配置目录和 CDP 端口）；使用相同 key 的智能体有意共享同一个浏览器。 |
 | [驱动模式](#驱动模式) | `managed`（启动专属本地 Chrome）、`remote`（连接已有 CDP 端点）、`extension`（通过 Playwright MCP 扩展桥驱动正在运行的浏览器）。 |
 | [进度与可恢复性](#class-browserruntimerail) | `BrowserRuntimeRail` 将任务进度持久化到会话中，在下次调用时作为延续上下文注入，并将未完成的运行转换为结构化失败摘要。 |
-| [Guardrails](#class-browserrunguardrails) | 步数、失败次数和超时限制，支持自动重试，以及在达到最大迭代后可选的恢复执行。 |
+| [Guardrails](#class-runguardrails) | 步数、失败次数和超时限制，支持自动重试，以及在达到最大迭代后可选的恢复执行。 |
 | [可观测性](#可观测性) | 专用日志文件 `logs/browser_agent.log` 和经过脱敏的结构化状态遥测（`[BROWSER_SUBAGENT]` 记录）。 |
 
 ---
@@ -167,7 +167,7 @@ main_agent = create_deep_agent(model=model, subagents=[browser_cfg])
 
 ## 浏览器能力（Capabilities）
 
-模块：`openjiuwen.harness.tools.browser_move.playwright_runtime.browser_capabilities`
+模块：`openjiuwen.harness.tools.browser_move.surfaces.browser.capabilities`
 
 Playwright MCP 工具按可信的显式能力目录分组。匹配按工具名精确进行 —— 从不使用前缀匹配 —— 因此新引入的 Playwright 工具在其策略审查之前不会被暴露。主智能体按任务选择能力名称；解析器本身不做任何任务语义解释。
 
@@ -245,7 +245,7 @@ Managed 模式注意事项：重连时，运行时会拒绝复用启动参数与
 ### 超时
 
 - **单次工具调用**：`PLAYWRIGHT_MCP_TIMEOUT_S` / `BROWSER_TIMEOUT_S`（默认 `180`）限制每次 MCP 工具调用。
-- **单次任务尝试**：`BrowserRunGuardrails.timeout_s`（默认 `180`）限制一次完整的委派浏览器任务；参见 [Guardrails](#class-browserrunguardrails)。
+- **单次任务尝试**：`RunGuardrails.timeout_s`（默认 `180`）限制一次完整的委派浏览器任务；参见 [Guardrails](#class-runguardrails)。
 - **批量步骤**：`browser_batch_interact` 将单步超时钳制在 250–30000 ms，整批上限 90 s。
 
 ### 输出目录
@@ -256,7 +256,7 @@ Managed 模式注意事项：重连时，运行时会拒绝复用启动参数与
 
 ## class BrowserInstanceConfig
 
-模块：`openjiuwen.harness.tools.browser_move.playwright_runtime.config`
+模块：`openjiuwen.harness.tools.browser_move.surfaces.browser.runner.settings`
 
 ```python
 @dataclass(frozen=True)
@@ -276,6 +276,7 @@ class BrowserInstanceConfig
 | `profile_name` | `str` | Managed profile 名。为空时回退到 key，再回退到 `BROWSER_PROFILE_NAME` |
 | `cdp_url` | `str` | Remote 模式的显式 CDP 端点；优先于共享环境端点 |
 | `browser_binary` | `str` | 可选的 Chrome 可执行文件路径覆盖 |
+| `launch_args` | `str` | Playwright MCP 启动参数，格式同 `PLAYWRIGHT_MCP_ARGS`（shell 风格字符串或 JSON 列表）。为空时遵循 `PLAYWRIGHT_MCP_ARGS`，再回退到默认值；按运行决定 headless 或 isolated 的调用方在此设置，而不写环境变量 |
 
 ### 驱动模式
 
@@ -287,7 +288,7 @@ class BrowserInstanceConfig
 
 ## class RuntimeSettings
 
-模块：`openjiuwen.harness.tools.browser_move.playwright_runtime.config`
+模块：`openjiuwen.harness.tools.browser_move.surfaces.browser.runner.settings`
 
 ```python
 @dataclass(frozen=True)
@@ -305,20 +306,20 @@ class RuntimeSettings
 | `api_base` | `str` | 模型 API base URL |
 | `model_name` | `str` | 嵌套 browser worker 使用的模型名 |
 | `mcp_cfg` | `McpServerConfig` | Playwright MCP 服务器配置（stdio；命令默认 `npx -y @playwright/mcp@0.0.78`，通过 `--caps=` 启用完整能力列表） |
-| `guardrails` | `BrowserRunGuardrails` | 运行 guardrails |
+| `guardrails` | `RunGuardrails` | 运行 guardrails |
 | `instance` | `Optional[BrowserInstanceConfig]` | 每实例浏览器身份 |
 
 使用 `build_runtime_settings(instance)` 从环境变量解析全部字段，或让 `create_browser_agent` 从 `Model` 对象的客户端配置推导 provider/key/base/model。
 
 ---
 
-## class BrowserRunGuardrails
+## class RunGuardrails
 
-模块：`openjiuwen.harness.tools.browser_move.playwright_runtime.config`
+模块：`openjiuwen.harness.tools.browser_move.runtime.config`
 
 ```python
 @dataclass
-class BrowserRunGuardrails
+class RunGuardrails
 ```
 
 浏览器任务运行的限制。由 `build_browser_guardrails()` 从环境变量构建。
@@ -339,7 +340,7 @@ class BrowserRunGuardrails
 
 ## class BrowserAgentRuntime
 
-模块：`openjiuwen.harness.tools.browser_move.playwright_runtime.runtime`
+模块：`openjiuwen.harness.tools.browser_move.surfaces.browser.runner.facade`
 
 ```python
 class BrowserAgentRuntime(
@@ -348,7 +349,7 @@ class BrowserAgentRuntime(
     api_base: str,
     model_name: str,
     mcp_cfg: McpServerConfig,
-    guardrails: BrowserRunGuardrails,
+    guardrails: RunGuardrails,
     instance: BrowserInstanceConfig | None = None,
     allowed_tool_names: Iterable[str] | None = None,
 )
@@ -371,7 +372,7 @@ class BrowserAgentRuntime(
 
 ## class BrowserRuntimeRail
 
-模块：`openjiuwen.harness.tools.browser_move.playwright_runtime.runtime`
+模块：`openjiuwen.harness.tools.browser_move.surfaces.browser.rails.runtime_rail`
 
 ```python
 class BrowserRuntimeRail(runtime: BrowserAgentRuntime)

docs/zh/2.开发指南/API文档/openjiuwen.harness/tools/浏览器子智能体工具.md

@@ -112,7 +112,7 @@
 
 ## 运行时辅助工具
 
-模块：`openjiuwen.harness.tools.browser_move.playwright_runtime.runtime_tools`
+模块：`openjiuwen.harness.tools.browser_move.surfaces.browser.runner.tools`
 
 由共享的 [`BrowserAgentRuntime`](../subagents/浏览器子智能体.md#class-browseragentruntime) 支撑的确定性辅助工具。无论能力如何选择，它们始终被注入。
 

openjiuwen/core/common/logging/tool_call.py

@@ -0,0 +1,24 @@
+# coding: utf-8
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+ToolNameMatcher = Callable[[str], bool]
+ToolCallLog = Callable[..., Any]
+
+# Process-wide like the loggers it routes to: agents are built by callers that never see the registrant.
+_TOOL_CALL_LOGGERS: dict[ToolNameMatcher, ToolCallLog] = {}
+
+
+def register_tool_call_logger(matches: ToolNameMatcher, log: ToolCallLog) -> None:
+    """Send the tool-call lines of tools whose name ``matches`` to ``log(message, *args)``."""
+    _TOOL_CALL_LOGGERS[matches] = log
+
+
+def tool_call_logger(tool_name: str) -> Optional[ToolCallLog]:
+    for matches, log in _TOOL_CALL_LOGGERS.items():
+        if matches(tool_name):
+            return log
+    return None