feat(tools): add browser_wait_for

rexleimo · rexleimo · commit 0be63f1d5e4e · 2026-03-02T20:21:48.000+08:00
diff --git a/crates/rexos-tools/src/browser_bridge.py b/crates/rexos-tools/src/browser_bridge.py
@@ -116,6 +116,41 @@ def main() -> int:
                             },
                         }
                     )
+                elif action == "WaitFor":
+                    selector = cmd.get("selector", "")
+                    text = cmd.get("text", "")
+                    per_call_timeout = cmd.get("timeout_ms")
+                    try:
+                        per_call_timeout = int(per_call_timeout) if per_call_timeout else timeout_ms
+                    except Exception:
+                        per_call_timeout = timeout_ms
+
+                    waited_for = {}
+                    if selector:
+                        page.wait_for_selector(selector, timeout=per_call_timeout)
+                        waited_for["selector"] = selector
+                    if text:
+                        page.get_by_text(text, exact=False).first.wait_for(
+                            state="visible", timeout=per_call_timeout
+                        )
+                        waited_for["text"] = text
+
+                    if not waited_for:
+                        respond({"success": False, "error": "missing selector/text"})
+                        continue
+
+                    current_url = page.url if page.url else current_url
+                    respond(
+                        {
+                            "success": True,
+                            "data": {
+                                "waited_for": waited_for,
+                                "timeout_ms": per_call_timeout,
+                                "title": page.title(),
+                                "url": current_url,
+                            },
+                        }
+                    )
                 elif action == "ReadPage":
                     content = "(empty)"
                     try:
diff --git a/crates/rexos-tools/src/lib.rs b/crates/rexos-tools/src/lib.rs
@@ -90,6 +90,7 @@ impl Toolset {
             browser_click_def(),
             browser_type_def(),
             browser_press_key_def(),
+            browser_wait_for_def(),
             browser_read_page_def(),
             browser_screenshot_def(),
             browser_close_def(),
@@ -270,6 +271,16 @@ impl Toolset {
                 self.browser_press_key(args.selector.as_deref(), &args.key)
                     .await
             }
+            "browser_wait_for" => {
+                let args: BrowserWaitForArgs = serde_json::from_str(arguments_json)
+                    .context("parse browser_wait_for arguments")?;
+                self.browser_wait_for(
+                    args.selector.as_deref(),
+                    args.text.as_deref(),
+                    args.timeout_ms,
+                )
+                .await
+            }
             "browser_read_page" => {
                 let _args: serde_json::Value = serde_json::from_str(arguments_json)
                     .context("parse browser_read_page arguments")?;
@@ -1314,6 +1325,39 @@ impl Toolset {
         Ok(resp.into_tool_output()?)
     }
 
+    async fn browser_wait_for(
+        &self,
+        selector: Option<&str>,
+        text: Option<&str>,
+        timeout_ms: Option<u64>,
+    ) -> anyhow::Result<String> {
+        if selector.unwrap_or("").trim().is_empty() && text.unwrap_or("").trim().is_empty() {
+            bail!("browser_wait_for requires selector or text");
+        }
+
+        let mut guard = self.browser.lock().await;
+        let session = guard
+            .as_mut()
+            .context("browser session not started; call browser_navigate first")?;
+
+        let mut cmd = serde_json::json!({
+            "action": "WaitFor",
+        });
+
+        if let Some(selector) = selector {
+            cmd["selector"] = serde_json::Value::String(selector.to_string());
+        }
+        if let Some(text) = text {
+            cmd["text"] = serde_json::Value::String(text.to_string());
+        }
+        if let Some(timeout_ms) = timeout_ms {
+            cmd["timeout_ms"] = serde_json::Value::Number(timeout_ms.into());
+        }
+
+        let resp = session.send(cmd).await?;
+        Ok(resp.into_tool_output()?)
+    }
+
     async fn browser_read_page(&self) -> anyhow::Result<String> {
         let mut guard = self.browser.lock().await;
         let session = guard
@@ -1769,6 +1813,16 @@ struct BrowserPressKeyArgs {
     selector: Option<String>,
 }
 
+#[derive(Debug, serde::Deserialize)]
+struct BrowserWaitForArgs {
+    #[serde(default)]
+    selector: Option<String>,
+    #[serde(default)]
+    text: Option<String>,
+    #[serde(default)]
+    timeout_ms: Option<u64>,
+}
+
 #[derive(Debug, serde::Deserialize)]
 struct BrowserScreenshotArgs {
     #[serde(default)]
@@ -3236,6 +3290,25 @@ fn browser_press_key_def() -> ToolDefinition {
     }
 }
 
+fn browser_wait_for_def() -> ToolDefinition {
+    ToolDefinition {
+        kind: "function".to_string(),
+        function: ToolFunctionDefinition {
+            name: "browser_wait_for".to_string(),
+            description: "Wait for a selector or text to appear on the page.".to_string(),
+            parameters: serde_json::json!({
+                "type": "object",
+                "properties": {
+                    "selector": { "type": "string", "description": "Optional CSS selector to wait for." },
+                    "text": { "type": "string", "description": "Optional visible text to wait for." },
+                    "timeout_ms": { "type": "integer", "description": "Optional timeout in milliseconds.", "minimum": 1 }
+                },
+                "additionalProperties": false
+            }),
+        },
+    }
+}
+
 fn browser_read_page_def() -> ToolDefinition {
     ToolDefinition {
         kind: "function".to_string(),
@@ -3385,6 +3458,7 @@ mod tests {
             "browser_click",
             "browser_type",
             "browser_press_key",
+            "browser_wait_for",
             "browser_read_page",
             "browser_screenshot",
             "browser_close",
@@ -4074,6 +4148,22 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn browser_wait_for_requires_session() {
+        let tmp = tempfile::tempdir().unwrap();
+        let tools = Toolset::new(tmp.path().to_path_buf()).unwrap();
+
+        let err = tools
+            .call("browser_wait_for", r#"{ "text": "hello" }"#)
+            .await
+            .unwrap_err();
+        let msg = err.to_string();
+        assert!(
+            msg.contains("browser_navigate") || msg.contains("session"),
+            "{msg}"
+        );
+    }
+
     #[tokio::test]
     async fn browser_read_page_requires_session() {
         let tmp = tempfile::tempdir().unwrap();
@@ -4135,6 +4225,13 @@ mod tests {
         let v: serde_json::Value = serde_json::from_str(&out).unwrap();
         assert_eq!(v["key"], "Enter");
 
+        let out = tools
+            .call("browser_wait_for", r#"{ "text": "hello", "timeout_ms": 1 }"#)
+            .await
+            .unwrap();
+        let v: serde_json::Value = serde_json::from_str(&out).unwrap();
+        assert_eq!(v["waited_for"]["text"], "hello");
+
         let page = tools.call("browser_read_page", r#"{}"#).await.unwrap();
         let v: serde_json::Value = serde_json::from_str(&page).unwrap();
         assert_eq!(v["title"], "Stub");
@@ -4215,6 +4312,13 @@ for line in sys.stdin:
         resp = {"success": True, "data": {"typed": cmd.get("text", ""), "selector": cmd.get("selector", "")}}
     elif action == "PressKey":
         resp = {"success": True, "data": {"key": cmd.get("key", ""), "selector": cmd.get("selector", "")}}
+    elif action == "WaitFor":
+        waited_for = {}
+        if cmd.get("selector"):
+            waited_for["selector"] = cmd.get("selector", "")
+        if cmd.get("text"):
+            waited_for["text"] = cmd.get("text", "")
+        resp = {"success": True, "data": {"waited_for": waited_for, "timeout_ms": cmd.get("timeout_ms")}}
     elif action == "Close":
         resp = {"success": True, "data": {"status": "closed"}}
         sys.stdout.write(json.dumps(resp) + "\n")
diff --git a/docs-site/how-to/browser-automation.md b/docs-site/how-to/browser-automation.md
@@ -19,6 +19,7 @@ If your Python executable isn't `python3`, set `REXOS_BROWSER_PYTHON` (example:
 - `browser_click` — click by CSS selector (best-effort text fallback)
 - `browser_type` — fill an input
 - `browser_press_key` — press a key (example: `Enter` to submit a form)
+- `browser_wait_for` — wait for a selector/text to appear
 - `browser_read_page` — return `{title,url,content}` (content is truncated)
 - `browser_screenshot` — write a PNG to a workspace-relative path
 - `browser_close` — close the session (idempotent)
@@ -29,8 +30,9 @@ If your Python executable isn't `python3`, set `REXOS_BROWSER_PYTHON` (example:
 2. `browser_read_page` to confirm state
 3. One small action: `browser_click` or `browser_type`
    - If you need to submit a form, use `browser_press_key` with `Enter`.
-4. `browser_read_page` again to confirm the page changed
-5. Repeat until done, then `browser_screenshot` for evidence and `browser_close`
+4. If the page updates async, use `browser_wait_for` (selector/text) to wait for the new state
+5. `browser_read_page` again to confirm the page changed
+6. Repeat until done, then `browser_screenshot` for evidence and `browser_close`
 
 ## Selector tips
 
@@ -48,10 +50,11 @@ If a CSS selector fails, `browser_click` will try a **best-effort visible-text f
 Use this as a starting point for agent prompts:
 
 ```text
-You may use RexOS browser tools (browser_navigate/click/type/press_key/read_page/screenshot/close).
+You may use RexOS browser tools (browser_navigate/click/type/press_key/wait_for/read_page/screenshot/close).
 
 Rules:
-- Always call browser_read_page after navigate/click/type to verify page state before the next step.
+- Always call browser_read_page after navigate/click/type/press_key to verify page state before the next step.
+- If the page updates async, use browser_wait_for (selector/text) before browser_read_page.
 - Keep actions minimal and reversible. If selectors fail, read the page and adjust selectors.
 - Save a screenshot at the end to .rexos/browser/<topic>.png.
 - Do NOT enter credentials or complete purchases without explicit user confirmation.
diff --git a/docs-site/reference/tools.md b/docs-site/reference/tools.md
@@ -35,7 +35,7 @@ By default it rejects loopback/private IPs (basic SSRF protection). For local te
 
 Browser tools enable headless browser automation via a Python Playwright bridge:
 
-- `browser_navigate` / `browser_click` / `browser_type` / `browser_press_key` / `browser_read_page` / `browser_screenshot` / `browser_close`
+- `browser_navigate` / `browser_click` / `browser_type` / `browser_press_key` / `browser_wait_for` / `browser_read_page` / `browser_screenshot` / `browser_close`
 
 Notes:
 
diff --git a/docs-site/zh/how-to/browser-automation.md b/docs-site/zh/how-to/browser-automation.md
@@ -19,6 +19,7 @@ python3 -m playwright install chromium
 - `browser_click`：按 CSS selector 点击（会做尽力的可见文本 fallback）
 - `browser_type`：填写输入框
 - `browser_press_key`：按键（例如用 `Enter` 提交表单）
+- `browser_wait_for`：等待 selector/text 出现
 - `browser_read_page`：返回 `{title,url,content}`（content 会被截断）
 - `browser_screenshot`：把 PNG 写入 workspace 相对路径
 - `browser_close`：关闭 session（可重复调用）
@@ -29,8 +30,9 @@ python3 -m playwright install chromium
 2. `browser_read_page` 确认状态
 3. 每次只做一个小动作：`browser_click` 或 `browser_type`
    - 需要提交表单时，用 `browser_press_key` 按 `Enter`。
-4. 再次 `browser_read_page` 确认页面确实变化
-5. 直到完成，最后 `browser_screenshot` 留证并 `browser_close`
+4. 如果页面是异步更新，用 `browser_wait_for`（selector/text）等待新状态出现
+5. 再次 `browser_read_page` 确认页面确实变化
+6. 直到完成，最后 `browser_screenshot` 留证并 `browser_close`
 
 ## Selector 小技巧
 
@@ -46,10 +48,10 @@ python3 -m playwright install chromium
 ## Prompt 模板（可直接复制）
 
 ```text
-你可以使用 RexOS 的 browser 工具（browser_navigate/click/type/press_key/read_page/screenshot/close）。
+你可以使用 RexOS 的 browser 工具（browser_navigate/click/type/press_key/wait_for/read_page/screenshot/close）。
 
 规则：
-- navigate/click/type 之后必须立刻 browser_read_page，先验证页面状态再做下一步。
+- navigate/click/type/press_key 之后尽快 browser_read_page；如果页面异步更新，先 browser_wait_for 再 read_page。
 - 动作尽量少且可回滚。selector 失败时先读页面内容，再调整 selector。
 - 最后把截图保存到 .rexos/browser/<topic>.png。
 - 未经用户明确确认，不要输入账号密码，也不要进行任何付费/下单操作。
diff --git a/docs-site/zh/reference/tools.md b/docs-site/zh/reference/tools.md
@@ -35,7 +35,7 @@ RexOS 会强制超时，并使用尽量最小的环境。
 
 浏览器工具通过 Python Playwright bridge 提供无头浏览器自动化能力：
 
-- `browser_navigate` / `browser_click` / `browser_type` / `browser_press_key` / `browser_read_page` / `browser_screenshot` / `browser_close`
+- `browser_navigate` / `browser_click` / `browser_type` / `browser_press_key` / `browser_wait_for` / `browser_read_page` / `browser_screenshot` / `browser_close`
 
 说明：
 
