Browser

Browser

Use Rudder's built-in Browser only when the user explicitly names or selects that surface, for example by saying Rudder Browser, Rudder's built-in Browser, or $browser, or by referring to a page or tab already open there. The request must identify the Rudder Browser as the intended surface; a generic request to browse the web, visit a URL, research a site, test localhost, take a screenshot, or interact with a page is not enough to invoke this skill.

When explicitly selected, the Browser may share signed-in website state from the local Rudder Browser profile. If the user does not explicitly select it, do not open, inspect, or interact with Rudder's Browser on the skill's behalf.

The Browser is a separate optional integration named rudder-browser. Do not look for Browser tools inside rudder-tools, launch another browser, or inspect Browser profile files to work around it.

Start With The Right State

1. Call rudder_browser_tabs once. Reuse a run-owned tab when it already has useful in-progress state.
2. Call rudder_browser_user_tabs only when the task refers to a page the user already has open in Rudder. It returns privacy-safe hostname and origin summaries, never the real title, path, query, fragment, or credentials. Results are read-only context; opaque ids cannot be passed to interaction tools. Open the returned origin only when it is sufficient. Otherwise ask the user for the exact URL instead of guessing a path.
3. Open a new run-owned tab with rudder_browser_open when no existing run tab fits. Navigate an existing tab only when replacing its current page is intentional.
4. Keep Browser work hidden by default. Use rudder_browser_visibility when the user asks to see the page or watching the interaction is useful.

If the Browser server is disabled or unavailable, follow Availability And Recovery. Do not silently substitute another browser surface.

Observe, Decide, Act

Before each interaction, understand the current visible state with the cheapest observation that answers the next question:

• Use rudder_browser_snapshot when you need DOM structure, accessible names, frame boundaries, locator ground truth, or node ids.
• Use rudder_browser_screenshot when layout, pixels, canvas content, visual regressions, or operator evidence matters.
• Use rudder_browser_locator for a small targeted state check when you already have a reliable locator.
• Avoid requesting both a full snapshot and a screenshot by default.

After clicking, typing, selecting, scrolling, or navigating, observe again only when the next decision requires it. A selected option, checked state, success message, expected URL, or other single authoritative signal is enough unless another visible signal contradicts it.

Read-Only Locator Recipe

Use rudder_browser_locator only for bounded semantic reads and waits. It never focuses an element, scrolls it, or dispatches mouse, keyboard, input, or change events.

1. Reuse the latest relevant snapshot while it still describes the target.
2. Build the locator only from that snapshot. Prefer, in order: test id, stable attribute or exact href, scoped role and accessible name, scoped label or placeholder, scoped text, then scoped CSS.
3. Use count, bounded text or attribute reads, state reads, or wait for attached, detached, visible, or hidden state.
4. For interaction, use an opaque ref from a fresh rudder_browser_read with rudder_browser_click or rudder_browser_type, or use an explicitly verified coordinate with rudder_browser_cua.
5. Perform the interaction once. Verify the narrow result needed next with a fresh read-only locator operation.

If count is zero, re-snapshot and rebuild the locator. If count is greater than one, scope it to a stable container. Do not use first, last, or index as a shortcut unless a preceding count established why that position is correct.

Do not retry the same failed locator. A timeout, ambiguity, stale reference, or selector error means the page or locator evidence must be refreshed.

Choose The Lowest-Level Tool Deliberately

• Prefer rudder_browser_read plus the high-level click/type tools for simple ordinary controls. Those refs are single-snapshot and single-interaction.
• Use rudder_browser_dom_cua only for a bounded read-only DOM snapshot. Node ids are evidence, not interaction handles; use a high-level ref or an explicit coordinate action to interact.
• Use rudder_browser_cua for controls not covered by high-level refs, canvas, hover paths, selection, scrolling, or other visual interaction. Use its elementInfo action before a coordinate action when the target is not already proven by the latest screenshot and snapshot.
• Arbitrary page JavaScript evaluation is intentionally unavailable. Use the bounded snapshot and declarative locator reads.
• Use rudder_browser_read, rudder_browser_click, and rudder_browser_type only for simple opaque-ref flows. Every interaction invalidates those refs.

Wait For Evidence, Not Time

Prefer rudder_browser_wait, read-only locator wait, or a targeted state read. Avoid fixed waits unless a known transition has no observable condition; keep such a wait short and verify a specific result immediately afterward.

Use rudder_browser_back, rudder_browser_forward, and rudder_browser_reload when preserving history matters. Do not navigate to the same URL merely to refresh a page.