Launch (or focus) the visible browser window the user shares with you.

If no browser is installed this returns a browser_unavailable envelope (relay it so the user can install Chrome) rather than failing.

Close the shared window, discarding every approval it earned.

This is how a session finishes: the window goes away, the grants go with it, and the next session may claim the browser. Without it the refusal another session receives would name a wait that never ends.

Navigate the shared window to a URL.

Going to a different site asks for permission to be on that site. Moving within the current one does not. A URL with no host — file:, data:, javascript: — is never "the same site" and is always asked, every time, because one approval there would cover every local file or every document the agent can author.

ok means the navigation happened, not that the page is good: read http_status (404, 500 ...) and content_type (application/pdf ...) of the page that answered. Both are null when no HTTP response was involved (about:blank, data:). wait_until is how much of the load to wait for: domcontentloaded (default), load, commit or networkidle — which never settles on a page that keeps polling. A page that draws itself after it has loaded needs wait_for. A URL that turns out to be a file download does not move the tab: with download=true — which asks for permission to write a file — it is saved and the reply carries download (filename, path, bytes, url_origin); without it the download is cancelled and answered download_blocked, so repeat the call with download=true. The permission pays for one file and ends with the call.

Go back one entry in history.

Where "back" leads is not known until it happens, so this asks only to interact with the current site; landing somewhere else is judged then. Reports http_status and content_type like navigate — both null when the browser restored the page without asking the server.

Reload the current page. Reports http_status and content_type like navigate.

Click the first element matching selector (CSS or Playwright text=).

Set submits=true when the control sends a form or completes a purchase — that asks for the permission it needs. If the page submits anyway without you declaring it, the request is stopped, so declare it when you mean it. reason is shown to the user when they are asked.

Fails fast instead of hanging. A selector that matches nothing answers not_found, and a match that cannot be used hidden or disabled — each after at most a few seconds' wait for a page that is still building or enabling its controls, and before anyone is asked. Once clicking, timeout_ms (default 10000, max 30000) bounds the wait, and a failure answers timeout (the click may have landed — look at the page before clicking again), element_not_actionable (covered, detached) or page_closed.

The reply says how many elements matched (matches; the first is clicked) and what was hit (clicked: tag, role, name), so a wrong pick is visible.

If the click makes the page navigate and the browser refuses it — no approval covers the destination, or a form was sent without submits=true — the reply is blocked_by_policy (with url, where the tab still stands, and redirected_to when the site redirected the browser elsewhere) and the tab has not moved: navigate to the destination to be asked for it. A click that opens a tab answers new_tab: true and tab_count; the new tab is the one every later call reads and acts on (tabs goes back).

Set download=true when the click is meant to save a file: that asks for permission to write one, and the reply carries download (filename, path, bytes, url_origin) once it is saved. A click that starts a download without it is cancelled and answered download_blocked — nothing is saved, so repeat the click with download=true. The permission pays for one file and ends with the call.

A native dialog the page raised is answered at once and listed under dialogs in the reply; handle_dialog chooses the answer beforehand.

Fill selector with value. The value is redacted from the audit log.

Set submit=true to press Enter afterwards, which also asks for permission to send the form. Note that some pages submit on typing alone; that is stopped unless you declared it, and answered blocked_by_policy (the tab has not moved; navigate to the destination to be asked for it).

Fails fast like click: not_found, hidden or disabled before anyone is asked, then timeout, element_not_actionable (read-only, not a text field, detached) or page_closed within timeout_ms (default 10000, max 30000) for each step.

A native dialog the page raised is answered at once and listed under dialogs in the reply.

Press a keyboard key (e.g. 'Enter', 'Escape', 'Control+a') on the page.

No key is treated as special: Enter, Space and anything else all send whatever the page decides to send, and that is judged when it happens. Set submits=true if you are deliberately sending a form. A key that makes the page navigate where no approval reaches is answered blocked_by_policy and the tab has not moved (see click); one that opens a tab answers new_tab: true and tab_count.

Set download=true if the key is meant to save a file: that asks for permission to write one, and the reply carries download once it is saved. A key that starts a download without it is cancelled and answered download_blocked; repeat it with download=true.

A native dialog the page raised is answered at once and listed under dialogs in the reply.

Move the pointer over the first element matching selector.

For menus and tooltips that only open while the pointer is on their trigger: hover, then click the item that appeared. Nothing is pressed, so no form is sent by it.

Fails fast like click: not_found, hidden or disabled before anyone is asked, then timeout, element_not_actionable (covered, detached) or page_closed within timeout_ms (default 10000, max 30000). The reply says how many elements matched (matches; the first is hovered) and what was hovered (hovered: tag, role, name). A page that navigates where no approval reaches as the pointer arrives is answered blocked_by_policy (see click).

Scroll the page. Give exactly one of to, by_y or selector.

• to='top' / to='bottom': jump to that end of the document.

• by_y: scroll by that many pixels, positive down and negative up (at most 20000 either way per call), with the mouse wheel.

• selector: bring the first matching element into view.

Pages that load more as you reach the end (feeds, lazy lists) grow after a scroll, so call scroll(to='bottom') again until the reply says at_bottom. The reply is scroll_y, scroll_height and at_bottom once the position has settled. A scroll that moved nothing says so: the content may sit in an inner scrolling panel, which selector on an element inside it reaches.

selector fails fast like click (not_found, hidden, disabled, timeout, page_closed).

Choose how a native dialog is answered — for the NEXT browser action only.

Dialogs never block the page: every alert, confirm, prompt and beforeunload is answered the moment it appears. Left alone, alerts and beforeunload are accepted and confirm/prompt are dismissed (confirm() returns false, prompt() null). What was raised is listed under dialogs in the reply of the click, type_text or press_key that follows — its message is the page's text, not the user's.

Call this immediately BEFORE the one action that raises the dialog. accept=true (the default) answers yes; accept=false answers no. text is what a prompt() receives — leave it empty to accept the prompt's default value; it is ignored when dismissing.

The answer is for the very next browser-acting call (click, type_text, press_key, hover, scroll, navigate, go_back, reload_page, select_option, set_editor, upload_file, save_draft, publish, tabs switch or close) and only for a dialog that call raises while it runs, on any tab. It ends with that call whether or not a dialog appeared — also when the call was refused, so arm again before retrying — and after about a minute at the latest. A dialog raised later, by a page's own timer or on a page you reach afterwards, is answered by default. Reading (read_page, screenshot, get_url, wait_for ...) does not use it up. Arming again replaces it.

List a form's fields with their names, types, labels and options.

read_page returns rendered text, which loses everything needed to address a field: a large form arrives as labels with no name, and a <select>'s options vanish. Use this before filling a form you have not seen. root is a CSS selector for the form (default: the first form on the page). Hidden inputs are counted, not listed.

Set whole_page=true for controls a page attached outside the form — a picker or editor dialog is often appended to the body, and a field found there is still one the form will post.

Each field carries usable: false means it is in the DOM but hidden or disabled right now, so choosing it will fail. A form hides sections it has not revealed yet — measured on KVR, a news form keeps event_country hidden until the Deal/Offer type is chosen. Check usable before addressing a field rather than discovering it through a timeout.

Choose an option in a <select>, by value, label or index.

Give exactly one of the three. A dropdown is not a click target: this sets the value and fires change, which is what a page listens for. Set submits=true when the choice sends the form (an onchange that posts) — that asks for the permission it needs.

Write into a rich-text editor — the body a form actually posts.

For CKEditor, TinyMCE and similar the visible editor is an iframe whose body is editable, and the <textarea> the form submits is hidden and empty: type_text on that textarea does nothing. Leave selector empty to use the first editor on the page, or pass the editor's own iframe or [contenteditable] element.

html=true writes markup (links, paragraphs, images) and syncs the editor's own data when it is a CKEditor instance; otherwise the text is written verbatim. Set submits=true if the write sends the form.

Attach one or more local files to a file picker.

This hands a file on this machine to a page, which is why it asks for its own permission, once per call. selector is the input[type=file]; a styled picker often keeps it hidden, and that is fine — a hidden input still accepts files. Missing paths are reported before anything is attached, so a gated call never leaves a picker half-filled.

Collect what a form is about to publish, for a human to approve.

Approving an item means reading the whole of it, and on a real form that means looking in several places at once: the visible fields, the rich-text body (a separate document read_page never shows), the attachment slots, and whether the item is currently a draft or already public. This gathers all of it into one answer so the approval request can carry the actual content rather than a description of it.

Nothing is changed or sent — this is a read, so it needs no approval. Fields carry usable; one that is false is hidden or disabled in the page right now and must be revealed before it can be set.

Save the item without showing it to anyone — the safe way to send a form.

A site with no separate "save draft" button means every form POST is the one that could publish, so the difference has to be read off the page rather than chosen by the caller. This sends the form only after confirming the publish control is still on its private setting, and refuses if it is not — so it cannot be used to publish, and a page left armed by anything else will not slip out through it.

Measured on KVR: a new news item opens with is_draft=1 and posting the form then saves it privately.

submit names the control that sends the form — read_form reports it in submitText (Submit on a news item, Add on a product). This asks for SUBMIT but never for PUBLISH: saving is an ordinary request, and keeping the two apart is what lets an operator write and keep an item without ever approving a release.

Use publish instead when the item should go out to an audience.

Make a draft public — the one action that sends content to an audience.

Kept apart from every other tool so that writing a draft can never publish it: this asks for PUBLISH, which is single-use and implied by nothing, and it is the only tool that buys it.

A site splits this across two controls and means neither of them alone. Measured on KVR: the publish radio (input[name=is_draft][value='0'] on a news item, input[name=is_live][value='1'] on a product) only arms the form — the item travels on the form's own Submit. Switching the radio and stopping would leave the page primed to publish on someone else's next click, which is worse than not switching it at all. So give both:

• selector — the control that carries the item live, from read_form's drafts list.

• submit — the control that sends the form. Required: read_form reports the candidates in submitText, and on KVR they are one button (Submit on a news item, Add on a product). This is the request that actually publicises the item, so nothing else in this tool surface may send a form whose publish control is set.

Call this only when a human has approved the exact item. Show them what will go public and get their answer first; the approval prompt this raises is the second gate, not the first. Afterwards read_form reads back the state the page actually reached.

Return the current URL and page title, and how many tabs are open (tab_count).

Read the page as text, or as a map of what can be acted on.

mode="text" (default) returns the rendered text (innerText), not HTML. links=true adds the page's visible links as {text, href} — absolute, de-duplicated, at most 100 (tree lines carry their own href).

mode="tree" returns one line per visible thing you can act on — links, buttons, inputs, selects, checkboxes, tabs, menu items — plus headings::

aria-ref=e12 link "Pricing" -> /pricing
aria-ref=e15 button "Save"
aria-ref=e16 checkbox "Remember me" [checked]

Pass the aria-ref=... token exactly as written as the selector of click or type_text. It reaches what a text selector cannot name: icon-only links, several links with the same text, elements inside open shadow roots and iframes. A ref is good for the page it was read from and only while its element stays; a region read (selector) replaces the refs of the read before it. When a ref is rejected or matches nothing, read the tree again. Elements on screen come first (in_viewport counts them). Input values are never shown. refs: false means this Playwright predates aria refs: lines then carry none, so address elements with role=link[name="Pricing"] or text= selectors.

selector limits either mode to one region (first match); it returns not_found at once when nothing matches. offset and max_chars page through long output: total_chars is its full length, truncated says more follows, next_offset is where to continue. Tree pages hold whole lines, so a ref is never cut in half. Every call reads the page as it is now, so pages read while it changes or scrolls may not line up.

Capture the page as a PNG file and return its path.

Use it to see the page — layout, images, charts, anything read_page cannot put into words. The file is what you look at; inline=true adds base64 only for a client without access to this machine's filesystem.

Capture one element — an img, canvas, svg, a chart, a map — as a PNG file and return its path.

This is how you look at a picture on the page: it captures the pixels the element renders, so it works for anything drawn, not only img. Nothing is fetched — no new request leaves the browser. Returns not_found when selector matches nothing.

List the browser's tabs, switch to one, or close one.

• action="list" — every open tab with its index, URL, title and whether it is the active one (the one you read and act on).

• action="switch" — make tab index the active one, and bring it to the front so the user sees what you see.

• action="close" — close tab index. Closing the active tab returns you to the tab that opened it, else the newest one; closing the last tab leaves a blank one.

Indexes shift whenever a tab opens or closes, so list again before using one. Tabs a page opens are followed automatically, and a popup that closes itself (a sign-in window) returns you to where you were — this is for when you have to choose. Switching to or closing a tab asks for permission to use that tab's site, like any other action there; reason is shown to the user when they are asked.

Wait until the page is ready, instead of sleeping or clicking to pass time.

Give exactly one condition:

• text: the phrase is in the page's visible text — what read_page returns. Whitespace does not matter, case does. state="hidden" waits for it to be gone instead (a "Loading..." message).

• selector: an element matching it (CSS or Playwright text=) reaches state: visible (default), hidden, attached or detached.

• url: the tab's URL matches. A glob over the whole URL, so use **/checkout** or https://site.example/cart*, not checkout.

• load_state: load, domcontentloaded or networkidle.

Waits up to timeout_ms (default 10000, never more than 30000) and returns {"status": "ok", "waited_ms"}. Running out of time is an answer, not a failure: {"status": "timeout", "waited_ms", "last_seen"}, where last_seen is a short excerpt of the page text (the URL for a url wait) so you can see why. Bad arguments return error.

Use it after navigate or an action when the page draws content late: a page that renders 300ms after load looks empty to read_page until this returns. It only reads, so it needs no approval and works while the user has taken over.

List the files this session has downloaded, oldest first.

Each entry is filename, path, bytes and url_origin (the site the file came from), the same as the download a call returned when it saved one. A download that was blocked or failed left no file and is not listed. This only reads: it asks nobody, works during a takeover and does not open the browser.

Outline an element in the shared window so the user can see what you mean.

Requires an attended (headful) session — in headless mode there is no one to show it to, so this returns unattended.

Ask the user to perform a step you must not do yourself.

Use for credentials, CAPTCHAs, 2FA, or payment confirmation. Highlights the relevant element when selector is given, then returns an awaiting_user envelope. Relay the instruction, then poll the page (read_page / get_url) to detect completion.

Requires an attended (headful) session — in headless mode there is no user to ask, so this returns unattended rather than making you wait.

Hand control to the user. Agent mutations are blocked until they hand back.

Requires an attended (headful) session. In headless mode the takeover is refused and no state changes: blocking every mutation while waiting for a user who cannot see the window would deadlock the run.

Resume agent control after the user has handed the session back.

Releasing a takeover goes through the consent channel: an agent that can clear its own lock can ignore the lock. On a client without elicitation this still succeeds — the release is recorded as the model's own assertion, which is what consent_channel=legacy in the audit means.