Browser Relay

Browser Relay

Use the user's existing browser and login state. Select an actual tab ID by URL and title; a foreground change must not redirect your work.

browser-relay tabs
browser-relay read --tab <id> --session <task-name>

Use a distinct session name for each independent task. Managed operations claim the tab for that session. Another owner must release or hand it off before you operate it; never stop someone else's session merely to gain access. These leases coordinate trusted clients, not access control against local software.

Choose the observation that answers the question

• Reading: read focuses on main content and preserves semantic groups, complete text and full URLs. read --ref <ref> reads an observed subtree.
• Operating: observe includes the whole page, controls, states and refs. Use it to find navigation, dialogs or controls outside the main content.
• Seeing: use screenshots for canvas, layout, missing accessible text or a semantic action with an unexpected outcome. In the runtime, tab.observe({mode:'both'}) returns a snapshot and screenshot together. With CLI use observe --mode both --output /tmp/page.png --tab <id> --session <name>.

Follow nextCursor (read --cursor <cursor>) when an observation is truncated. A cursor continues the same captured text; it is not a new live observation. After navigation it expires. If the page exceeds the cache limit, read a smaller subtree. Do not report a partial result as the complete page or article. Runtime output has a separate budget: if runtimeOutput.nextCursor is returned, run its readWith expression in the same session to recover the clipped output. Then follow any browser nextCursor it contains; a new diff cannot recover it. A site's “Show more” is separate from output pagination: expand the site control when the task needs the full article. Group parents, quoted material and replies remain distinct; do not count recommendations as comments or duplicate cards.

Read the returned title, URL, readiness and warnings. A loading shell, login page, verification page or unchanged feed is a state to handle, not completed reading. When scrolling returns contentChanged:false, do not count it as new content. That comparison detects changed text, not a guarantee of new records; use links or another content identity to deduplicate a feed.

Observe, act, verify

Use fresh refs, URLs or unique role/name targets from observed content. Refs expire on navigation or removal. Use within/parent context and scoped locators for repeated controls; use frameId for an iframe. Never guess refs or tab IDs.

Group actions whose targets and sequence are already known. For example, fill a known field, select an option, submit, and wait for an expected result. Stop the group before an unknown page, unexpected dialog or decision needing new evidence. Set per-action timeoutMs when a target is expected to appear, become enabled, stop moving or become uncovered. Readiness checks never replay dispatched input.

browser-relay actions --tab <id> --session <task-name> --stdin <<'JSON'
[
  {"type":"fill","target":{"role":"textbox","name":"Search"},"text":"invoice"},
  {"type":"click","target":{"role":"button","name":"Search records"}},
  {"type":"wait","target":{"role":"heading","name":"Results"},"timeoutMs":10000}
]
JSON

Actions return an updated observation; use it rather than immediately reading again. --diff --session <task-name> reduces unchanged state. A truncated initial observation does not advance the diff baseline past unread content; completing its continuation pages advances that baseline. If nothing changed, identify what you are waiting for before requesting the same state again. Navigation waits for document readiness by default, not for all site data. Add a wait for the observed result/control when the site loads content asynchronously.

Confirm success with the relevant page content, URL or business result. A control value or successful tool return alone does not prove a click/change handler ran. Failures retain completed results and identify an interrupted action when it may have partly executed. Inspect them before recovery; never replay a group blindly.