Interact with the page: click (left/right/middle, single or double), hover, type, press, or scroll. Address elements with a [ref=eN] handle from browser::snapshot (or a pick), or raw viewport coordinates.
actionstring*required
`click`, `hover`, `type`, `press`, or `scroll`.
buttonstring
Mouse button for `click`: `left` (default), `right`, or `middle`.
click_countinteger· uint32min 0
Clicks in the gesture: 2 double-clicks (`click` only, default 1).
delta_ynumber· double
Scroll distance in pixels; positive scrolls down (`scroll`).
keystring
Key name for `press`: Enter, Tab, Escape, Backspace, Delete, ArrowUp/Down/Left/Right, Home, End, PageUp, PageDown.
refstring
Element ref from `browser::snapshot` (`e3`) or `browser::picked` (`p1`). Refs die on navigation; re-snapshot after.
session_idstring*required
textstring
Text to insert (`type`).
xnumber· double
Viewport x, when acting by coordinates instead of ref.
ynumber· double
Viewport y, when acting by coordinates instead of ref.
detailstring*required
What was done, for the transcript.
browser::console::read
functionRead the session's captured console: console.* calls, uncaught exceptions, and browser-level log entries. Filter with pattern/level and page with since_seq instead of dumping everything.
levelstring
Only entries at this level: `log`, `info`, `warning`, `error`, `debug`, `exception`. `error` also matches `exception`.
limitinteger· uint64min 0
Maximum entries returned, newest kept (default 100).
patternstring
Regex applied to entry text. Use it: dumping an unfiltered console wastes the caller's context.
session_idstring*required
since_seqinteger· uint64min 0
Only entries with `seq` greater than this; resume from the cursor returned as `last_seq`.
droppedinteger· uint64*requiredmin 0
Entries evicted from the ring buffer since session start.
entriesobject[]*required
levelstring*required
`log`, `info`, `warning`, `error`, `debug`, or `exception`.
seqinteger· uint64*requiredmin 0
Monotonic per-session cursor; pass back as `since_seq`.
sourcestring
`url:line` of the emitting frame, when known.
timestampinteger· int64*required
last_seqinteger· uint64*requiredmin 0
Cursor for the next `since_seq`.
Read-only environment diagnostics: which Chromium the worker would launch, its version, session capacity, and any degraded capability with how to enable it. Never starts a browser.
active_sessionsinteger· uint64*requiredmin 0
allowed_schemesstring[]*required
headless_defaultboolean*required
issuesobject[]*required
enable_howstring*required
max_sessionsinteger· uint64*requiredmin 0
okboolean*required
True when sessions can start right now.
browser::dom::read
functionRead the DOM as a tree of tags with id/class and refs. Structure-oriented complement to browser::snapshot; read deep subtrees by passing a ref.
depthinteger· uint32min 0
Levels of children to include (default 3).
refstring
Subtree root from an earlier ref (`e3`/`p1`) or dom node. Omit for the document root.
session_idstring*required
rootobject*required
One DOM node in the outline. `ref` resolves in `browser::act`, `browser::styles::read`, and `browser::styles::write`.
child_countinteger· uint32*requiredmin 0
Total children in the document, which may exceed `children` returned at this depth.
tagstring*required
Lowercase tag (`div`, `button`) or node name (`#text`).
textstring
Trimmed text content for text nodes.
truncatedboolean*required
True when the node cap cut the tree short; read a subtree via `ref`.
browser::evaluate
functionEvaluate a JavaScript expression in the page and return its completion value. Use for reads the snapshot can't express; prefer browser::act for interactions.
expressionstring*required
JavaScript expression evaluated in the page. The completion value is returned by value; wrap statements in an IIFE.
session_idstring*required
timeout_msinteger· uint64min 0
Upper bound on evaluation; clamped to `max_timeout_ms`.
errorstring
Exception text when not `ok`.
valueunknown
JSON completion value when `ok`.
Run a multi-step async JavaScript script in the page: top-level await and return work, with log(...), sleep(ms), waitFor(selector), and a state object that persists across execute calls for the session. One call replaces a chain of act/evaluate round-trips; returns { result, logs, state }.
codestring*required
Async JavaScript body run in the page. Top-level `await` and `return` work. In scope: `state` (JSON object persisted across execute calls for the session), `log(...)` (collected into the response), `sleep(ms)`, and `waitFor(selector, { timeout })`. Return plain JSON.
session_idstring*required
timeout_msinteger· uint64min 0
Upper bound on the run; clamped to `max_timeout_ms`.
errorstring
Exception text when not `ok`. A "context destroyed" error usually means the script navigated; split the script at the navigation.
logsstring[]*required
`log(...)` output collected during the run, in order.
resultunknown
The script's return value when `ok`.
stateunknown*required
Session state after the run; the next execute call sees this as `state`.
Internal: newest screencast frame, or nothing when since_frame is still current. No capture round-trip; poll fast. Not an agent function.
session_idstring*required
since_frameinteger· uint64min 0
Frame cursor from the previous read; when the newest frame still has this seq the response omits `frame` (nothing changed, nothing to redraw).
activeboolean*required
False when no screencast is running (call screencast::start first).
framestring
Base64 JPEG of the newest frame; absent when `since_frame` is still current or no frame has arrived yet.
frame_seqinteger· uint64*requiredmin 0
heightinteger· uint32*requiredmin 0
Page-viewport height the frame maps to.
timestampinteger· int64*required
widthinteger· uint32*requiredmin 0
Page-viewport width the frame maps to (input coordinate space).
Pause a session for a step only a human can do (CAPTCHA, 2FA, payment): show an in-page continue banner and block until the human clicks it, a browser::handoff::confirm call resolves it, or the timeout elapses. Human acknowledgment is not proof — verify the expected page state after it returns.
instructionsstring*required
What the human must do before the call continues. Shown in the in-page banner and the handoff-requested event.
session_idstring*required
timeout_msinteger· uint64min 0
Give up after this long and return with `via: "timeout"`. Defaults to the config default; clamped to `max_timeout_ms`. Set generously; a human is slow.
confirmedboolean*required
True when a human confirmed; false when the wait timed out.
handoff_idstring*required
urlstring*required
The page URL when the wait ended, so the caller can verify the step actually landed (human acknowledgment is not proof).
viastring*required
How the confirmation arrived: `in_page`, `confirm_call`, or `timeout`.
Resolve a paused browser::handoff by handoff_id, or the one pending handoff for a session_id. The console calls this when the human confirms outside the page.
handoff_idstring
Confirm a specific handoff by id. Omit to confirm the one pending handoff for `session_id`.
okboolean*required
True when a pending handoff matched and was resolved.
Go back, go forward, or reload the session's page. Back/forward at the history edge is a no-op with moved=false.
actionstring*required
`back`, `forward`, or `reload`.
session_idstring*required
movedboolean*required
False when back/forward had no entry to move to.
urlstring*required
URL after the action. `back`/`forward` at the history edge is a no-op with ok=true.
browser::navigate
functionNavigate a session to a URL and wait for the page to load. Element refs from earlier snapshots are invalidated by navigation.
session_idstring*required
timeout_msinteger· uint64min 0
Upper bound on the navigation wait; clamped to `max_timeout_ms`.
urlstring*required
Absolute URL; scheme must be on the configured allowlist.
timed_outboolean*required
True when the load event did not fire inside the timeout; the page may still be usable; snapshot to check.
urlstring*required
URL after redirects.
browser::network::read
functionRead the session's captured network requests (method, URL, status, failures). failed_only=true is the fast path for 'what broke'.
failed_onlyboolean
Only failed requests (network error or status >= 400).
limitinteger· uint64min 0
Maximum entries returned, newest kept (default 100).
patternstring
Regex applied to the request URL.
session_idstring*required
since_seqinteger· uint64min 0
Only entries with `seq` greater than this.
droppedinteger· uint64*requiredmin 0
Entries evicted from the ring buffer since session start.
entriesobject[]*required
seqinteger· uint64*requiredmin 0
Monotonic per-session cursor; pass back as `since_seq`.
timestampinteger· int64*required
last_seqinteger· uint64*requiredmin 0
Cursor for the next `since_seq`.
Internal: reload browser settings from the authoritative configuration on change.
browser::pick::hint
functionInternal: element preview at a viewport point (tag, id, classes, bounds) so the console UI can draw a hover highlight in pick mode. Not an agent function.
session_idstring*required
xnumber· double*required
Viewport x of the cursor.
ynumber· double*required
Viewport y of the cursor.
boundsany of
Viewport-space box to draw the highlight over.
any of (2)
variant 1
heightnumber· double*required
widthnumber· double*required
hitboolean*required
False when no element sits at the point.
tagstring
Lowercase tag name.
browser::pick::resolve
functionInternal: resolve the element at a clicked viewport point and emit browser::picked. The console calls this on a pick-mode click. Not an agent function.
session_idstring*required
xnumber· double*required
Viewport x of the click.
ynumber· double*required
Viewport y of the click.
browser::pick::start
functionInternal: enter pick mode so the human can select an element in the console UI. Not an agent function.
session_idstring*required
browser::pick::stop
functionInternal: leave DevTools inspect mode without picking. Idempotent. Not an agent function.
session_idstring*required
Cancelling pick mode on an unknown session succeeds.
Internal: start pushing live viewport frames for browser::frame. Console-UI plumbing; agents use browser::screenshot. Not an agent function.
session_idstring*required
Internal: stop the live frame push. Idempotent. Not an agent function.
session_idstring*required
Stopping the screencast on an unknown session succeeds.
browser::screenshot
functionCapture the session viewport as a viewable JPEG. Use browser::snapshot for machine-readable structure; screenshot when layout or rendering matters.
full_pageboolean
Capture the full scrollable page instead of the viewport.
session_idstring*required
detailsobject*required
heightinteger· uint32*requiredmin 0
session_idstring*required
widthinteger· uint32*requiredmin 0
Attach a session to an already-running browser over CDP (start Chrome with --remote-debugging-port). Opens a fresh tab the session owns, or adopts an existing user tab by URL substring and releases it untouched on stop. Reaches the real profile with its logins; disabled unless allow_attach is set in config.
adopt_url_substringstring
Adopt the existing tab whose URL contains this substring, exclusively, and release it untouched on stop. Omit to open a fresh tab the session owns and closes on stop. Must match exactly one open tab.
cdp_urlstring*required
CDP endpoint of the running browser: `http://127.0.0.1:9222` (the worker resolves the WebSocket URL from `/json/version`) or a `ws://` debugger URL directly. Start Chrome with `--remote-debugging-port=9222` to expose one.
read_onlyboolean
Inspection-only session; see browser::sessions::start.
urlstring
URL to open in the fresh tab (ignored when adopting). Omit for about:blank.
adoptedboolean*required
True when the session adopted an existing user tab (released, not closed, on stop); false when it opened a fresh tab it owns.
read_onlyboolean*required
session_idstring*required
browser::sessions::list
functionList live browser sessions with their current URL and activity.
sessionsobject[]*required
console_entriesinteger· uint64*requiredmin 0
created_msinteger· int64*required
last_used_msinteger· int64*required
read_onlyboolean*required
session_idstring*required
browser::sessions::start
functionStart an interactive Chromium session and return its session_id. Sessions keep console and network history; stop them with browser::sessions::stop when done.
headfulboolean
Force a visible window for this session, overriding the configured `headless` default.
read_onlyboolean
Inspection-only session: act, evaluate, execute, and styles::write are rejected while navigation, snapshots, reads, and screenshots work. Immutable for the session's lifetime.
urlstring
URL to open immediately. Omit to start on about:blank.
read_onlyboolean*required
session_idstring*required
Pass this to every other browser function.
browser::sessions::stop
functionStop a browser session and its Chromium process. Idempotent: stopping an unknown or already-stopped session succeeds with was_running=false.
session_idstring*required
Session to stop. Stopping an unknown or already-stopped id succeeds.
was_runningboolean*required
False when the session was already gone.
browser::snapshot
functionRead the page as an accessibility-tree outline. Lines carry [ref=eN] handles that browser::act accepts; refs stay valid until the next navigation. Prefer this over browser::screenshot; it is cheaper and machine-readable.
diffboolean
Return only what changed since this session's previous snapshot instead of the full outline. Falls back to a full snapshot when there is no baseline (first snapshot, or first after a navigation).
session_idstring*required
diffany of
Present when the caller asked for `diff: true` and a baseline existed.
any of (2)
variant 1
unchangedinteger· uint64*requiredmin 0
generationinteger· uint64*requiredmin 0
Document generation the refs belong to; navigation advances it and kills every ref from earlier generations.
treestring*required
Indented outline; lines carry `[ref=eN]` handles for `browser::act`. Empty when `diff` is populated.
truncatedboolean*required
True when the tree hit `max_snapshot_nodes` and was cut short.
browser::styles::read
functionRead an element's computed styles (curated design set by default, or named properties) plus its inline style attribute.
propertiesstring[]
Computed property names to return. Omit for a curated design-panel set; pass `["*"]` for every computed property.
refstring*required
Element ref from `browser::snapshot`, `browser::dom::read`, or a pick.
session_idstring*required
inline_stylestring
The element's inline `style` attribute, when present.
propertiesobject[]*required
browser::styles::write
functionSet one inline CSS property on an element, live in the page. Visual experiment only: the page's source files are untouched, and the edit dies with the next navigation.
importantboolean
Apply with `!important`.
propertystring*required
CSS property name (`background-color`).
refstring*required
Element ref to edit.
session_idstring*required
valuestring*required
CSS value (`#101418`). Empty string removes the inline property.
inline_stylestring*required
The element's inline `style` attribute after the edit.
browser::tabs::list
functionList the open tabs of a running browser reachable at a CDP endpoint (url, title, and whether a session already adopted each). Read-only; adopt one with browser::sessions::attach.
cdp_urlstring*required
CDP endpoint of the running browser, as in browser::sessions::attach.
tabsobject[]*required
adoptedboolean*required
True when a session already adopted this tab; it cannot be adopted again until that session stops.
