Sallyport

Click an element via DOM .click(). selector can be a CSS selector or a @eN ref from snapshot. Refs are more reliable on SPAs. Try this first for buttons/links; if the click doesn't register (SPA pointer-event routers, canvas or drag-and-drop UIs), escalate to mouse_click, which fires a real pointer sequence. Refuses rather than reporting a no-op as success when the target cannot receive the click at all: element_disabled for a control carrying the HTML disabled attribute (Chrome dispatches nothing there — satisfy whatever enables it, e.g. wait_for it to become enabled, then retry), and bad_ref/not_found for a node detached from the document. A zero-size element IS still clicked (a hidden <input type=file> is a normal upload pattern) and merely comes back flagged hidden:true. waitFor polls for the click's effect (panel opened, item selected) in the same call.

Close a tab by tabId. tabId is required — there is no implicit fallback because closing the wrong tab destroys user work. Allowlist-gated: the tab's URL must be in the extension's allowlist, otherwise the call fails with domain_not_allowed (prevents an agent from closing non-allowlisted tabs it can still see via list_tabs).

Read the page's recent console errors/warnings and uncaught exceptions for a tab — so you can tell 'the click succeeded but the SPA's handler threw and the page is wedged' from a page that's merely slow. Returns {enabled, entries:[{ts, level, text, origin}], truncated?} (oldest→newest; level is 'error'|'warning'). OPT-IN: capture must be turned on in the extension popup (off by default) — when it's off you get {enabled:false, entries:[]}, NOT an error, so an empty result isn't misread as 'no errors'. Capture begins at the first bridge attach with the setting on — there is NO history replay, so errors thrown before then aren't captured. Entries are origin-filtered to the allowlist (a tab that navigated cross-origin won't leak a non-allowlisted origin's console). limit caps how many recent entries return (default 50, max 50). Structured CDP event capture only — no JS eval. Domain must be in allowlist.

Run arbitrary JavaScript in the page context. REQUIRES the domain to have evaluate explicitly enabled in the extension allowlist; otherwise fails with evaluate_not_allowed. Use sparingly — prefer click/fill/read_text.

Run fetch() from the page's JS context, with its cookies/auth. Use this to download image/binary URLs you found via snapshot or evaluate (e.g. card photos from a logged-in 2gis session), or to issue a fresh request. To read a response the page ALREADY fetched (canvas-dashboard data), use network_tail instead — no re-issue, and it works when a signed request can't be replayed. The page's host must be in the allowlist; does NOT require the per-domain evaluate flag because the function body is fixed (only URL/method/headers/body are interpolated). Returns {status, contentType, headers, mode, data} where mode is 'text' for text/json/html/xml content-types or 'base64' otherwise. Pass saveAs=<filename> to write the body straight into the download sandbox (~/Downloads/sallyport/) instead: the result becomes {status, contentType, mode, path, size, filename} with NO data field, so a multi-MB image or archive never enters your context — where it would cost you tokens on every later turn for bytes you cannot read anyway. Use saveAs whenever the body is binary or you only need the file (to upload it, or to hand the user a path); it also replaces the old fetch_in_page → save_to_file pair with one call, and it defaults returnAs to 'base64' so the bytes reach disk unchanged (the text path would UTF-8-decode them, which is lossy for anything binary). Omit it when you actually need to READ the response (JSON, HTML). Bodies over 9 MiB fail with fetch_too_large — saveAs does NOT raise that ceiling, because the body still crosses the bridge before the daemon writes it; fetch a smaller asset or use a Range header.

Type into an input/textarea/contenteditable. Refuses password fields unless allowPassword=true. method='value' (default) sets .value and dispatches input/change events, then READS THE VALUE BACK and auto-falls-back to insertText if a framework (React-controlled inputs) reverted it — so it never silently returns ok:true on an empty field; the fallback result carries mode='insertText', fallbackFrom='value'. method='insertText' clears the field and types through CDP Input.insertText with real input events — force it when the app ignores programmatic values or concatenates text (SPA editors: Telegram, Slack, draft.js). Both insertText paths read the field back afterwards and report applied plus len (the field's length after the write, never its contents): 'yes' = your text is in there; 'no' = the field is EMPTY, nothing landed, so retry differently; 'unclear' = UNVERIFIED — the field has content that isn't literally your text, and len says which way to read that. len < what you sent means characters were DROPPED (a maxlength or a filter) — treat it as a failure and check with get_state/read_text. len >= what you sent means it was most likely reformatted in place (an input mask like '+7 (912) 345-67-89'), where the fill did work — confirm before relying on it, but do not blindly retype. The read-back is skipped when allowPassword=true or the value is empty, and absent entirely if the probe could not run.

Semantic locator: snapshot the page and return @eN refs of interactive elements matching a predicate, instead of guessing CSS against hashed SPA classnames. Give any of: role (a string, or a list = match any one), name (substring; nameExact=true for an exact case-insensitive match), value (substring). Results are ranked (exact-name first) and capped by limit. Returns {source, matches:[{ref,role,name,value,type,score}], total, truncated?} (truncated set when the snapshot was capped). Empty matches is a normal not-found, not an error. Locating SEVERAL controls is one intention, not several: pass queries:[{role,name,…,limit?}, …] (up to 10) and get {source, results:[{query, matches, total}]} back from ONE call and ONE tree walk — three separate finds cost three model turns and three walks for the same answer. timeoutMs (default 0 = answer from one snapshot) polls until EVERY query has matched or the deadline passes, for the 'it has not rendered yet' case where you would otherwise wait_for a selector you do not have; the result then carries elapsedMs. Because the condition is every query, do NOT put a predicate you expect to find nothing into a batch with timeoutMs — it would wait out the whole deadline; use wait_for with absent:true to assert something is gone. Each tick is a whole accessibility tree, so it polls twice a second, not four times. The match runs in the extension over the snapshot — no page JS, no evaluate flag. Domain must be in allowlist.

Cheap element probe — answer 'is this still here / visible / where / what does it say' WITHOUT a full snapshot. selector is a CSS selector or an @eN ref, OR an array of up to 10 of them: a post-action check is usually several assertions at once ('the dialog is gone AND the row appeared AND Save is enabled'), and batching them costs one round-trip instead of one each. With an array the result is {elements:[{selector, …the same per-element shape}]}, in the order you asked; a malformed CSS selector anywhere in the batch fails the whole call with bad_args. Use it to verify an action's effect or re-check a ref after navigation in one tiny round-trip instead of re-snapshotting the whole page. It NEVER errors on a missing element: a vanished node returns {exists:false, reason} (reason is 'not_found' for a CSS miss, 'unknown_ref' for an @eN this tab never minted / lost on navigation, 'detached' for a ref whose node died) — so it is safe to poll. On a hit returns {exists:true, visible, tag, text, box?:{x,y,width,height}, inViewport?, ref?, role?, name?}: visible is true when the element has a laid-out box (matches wait_for); box/inViewport (viewport-relative CSS px, the same coordinates mouse_click's x/y take) appear only when visible; text is trimmed innerText capped at 2000 chars (override maxChars, max 20000; truncated/textLen mark a cut). Does NOT read input .value (so it can't expose a password field's contents — use snapshot's type or fill's read-back for field state). Structured CDP only, no evaluate flag. Domain must be in allowlist.

See and steer native JS dialogs (alert/confirm/prompt/beforeunload) on a tab. An open dialog FREEZES the page's JS — clicks and waits then time out — and the dialog is native browser UI no other tool can see or click. With handling enabled every dialog is answered automatically the moment it opens (alert → OK, confirm/prompt/beforeunload → cancel) and recorded. Call with no action to read what happened: {enabled, armed, recent:[{ts, type, message, origin, response:{accept, promptText?}, armed}]} (oldest→newest). Pass action:'accept'|'dismiss' (+promptText to answer a prompt()) to ARM the response for the NEXT dialog on the tab — a one-shot, consumed by the first dialog, replaced by re-arming: e.g. arm accept, THEN click the button that opens confirm('Delete?'); arm accept before a navigation blocked by a beforeunload handler. OPT-IN: handling must be turned on in the extension popup ('auto-handle JS dialogs', off by default) — when it's off you get {enabled:false}, NOT an error, and dialogs behave natively (the page stays frozen until a human clicks them). Handling begins at the first bridge attach with the setting on — a dialog already open before then is NOT answered. Recorded entries are origin-filtered to the allowlist. Structured CDP only — no JS eval. Domain must be in allowlist.

Go back or forward through a tab's own session history — the browser's back/forward buttons. Use it to return to the previous page after following a link, when you no longer have that page's URL to re-navigate to. direction:'back'|'forward'; steps hops several entries in ONE jump (default 1; intermediate pages never load). The LANDING entry is allowlist-checked before anything moves — going back can't reach a non-allowlisted page that happens to sit in the history (you get domain_not_allowed; the destination's hostname is NOT echoed, to avoid leaking non-allowlisted browsing-history hosts back to you). History that doesn't reach that far → no_history (the message says how far it does reach); a same-document hop (SPA pushState) may not fire a load at all. On a timeout, do NOT assume the hop failed — it may have already landed before the load watchdog fired; check where you are with read_text/snapshot before retrying. Conversely, if a beforeunload prompt on the page you're leaving gets dismissed (the default unless you armed handle_dialog to accept it), the hop is verified to have actually happened before success is reported — a cancelled hop fails with navigation_cancelled instead of silently claiming you moved. Refs from the previous snapshot are invalidated — re-snapshot after. waitFor polls for the landing page's element/text in the same call (SPAs render long after 'loaded'). Structured CDP only — no JS eval. Domain must be in allowlist.

Hover the pointer over an element/point WITHOUT clicking — a real Input.dispatchMouseEvent mouseMoved (the hover step mouse_click sends before pressing). Use it for CSS :hover-only dropdown menus, tooltips and 'show actions on row hover' UIs that a click would dismiss or mis-activate. Target is EITHER selector (CSS or @eN, auto-aimed like mouse_click — reports covered/hitTarget/hitTargetRef when an overlay sits on top) OR explicit viewport x+y (CSS px, rejected if outside the viewport). Pair with waitFor to hover-then-wait-for-the-menu in one call, then click the item. Strictly weaker than mouse_click: no press/release, nothing is activated. NOTE: the :hover state is transient — a synthetic mouseMoved holds it only until the next mouse move, so do the follow-up action promptly. Allowlist-gated. Returns {ok, tag?, x, y, covered?, hitTarget?, hitTargetRef?, wait?}.

Types into whatever element currently HAS FOCUS — it takes no selector and does not move focus. To put text in a named field use fill, which targets the element and checks its type first; reach for key_type only for an editor you have already focused (a click, or a fill that landed there). Inserts raw text via CDP Input.insertText, so no key events fire — use send_keys for Enter/Escape/shortcuts. Refuses when focus is on <input type=password> — pass allowPassword=true to override (mirrors fill's gate, since keystrokes would otherwise bypass it once the password field has focus). waitFor polls for the typing's effect (an autocomplete list, a validation message) in the same call.

List open browser tabs (tabId, url, title, active, windowId). In broker mode (a shared broker daemon serving several sessions) this is owner-scoped: it returns only the tabs THIS session created, never the human's or another session's tabs.

Click via real Input.dispatchMouseEvent as a full pointer sequence — hover move, then press and release with human-ish delays — so pointer-event routers (React SPAs) that ignore a bare press+release accept it. Use this when the regular click (DOM .click()) doesn't trip pointer-event listeners — common on canvas-heavy UIs, drag-and-drop libraries (react-dnd), and games. Target is EITHER selector (CSS or @eN ref) OR explicit viewport coordinates x+y (CSS px — manual aim from a screenshot or hit diagnostics; rejected if outside the viewport). With a selector, the click point is auto-aimed: center first, then four points toward the corners, picking one where the target is actually the topmost element. If every probe point is covered by another node (overlay), the click still fires at the center and the result reports covered: true, a hitTarget descriptor, and hitTargetRef — an @eN ref for the covering node, so the agent can click IT directly (the covering layer often owns the event handler). button is 'left' (default), 'middle', or 'right'. clickCount is 1..3 (double/triple click). Allowlist-gated. Refuses zero-size elements with not_visible.

Open a URL. The destination domain must be in the extension's allowlist or the call fails with domain_not_allowed. Set newTab=true to open a new tab; otherwise updates the tab passed in tabId, or the active tab in the current window if tabId is omitted. In broker mode (a shared broker daemon) there is no active-tab fallback: a navigate with no tabId opens a NEW tab you own, and a tabId must reference a tab you created (else tab_not_owned). waitFor polls after the load until a selector/text shows up — on SPAs 'loaded' rarely means 'rendered', so prefer navigate+waitFor over navigate then wait_for. Returns {tabId, url, wait?} where url is where the tab ACTUALLY landed, not the URL you asked for — plus redirectedFrom carrying your requested URL when they differ, which is how an SSO bounce, a consent wall, a shortener or an expired session announces itself. A navigate invalidates every @eN you hold, so a follow-up snapshot is otherwise unavoidable — pass observe:{snapshot:'compact'} to get the new page's actionable elements back with this call instead.

Read the page's recent XHR/fetch responses for a tab — the DATA behind canvas dashboards. A chart drawn on <canvas> (Yandex Metrika, Chart.js, ECharts, WebGL) has NO readable DOM, so snapshot/read_text find nothing and a screenshot needs slow, imprecise vision — but the numbers arrived as JSON on the wire, and this surfaces those response bodies so you pull exact figures instead. Returns {enabled, entries:[{ts, method, url, urlTruncated?, status, type, contentType, size, origin, body?, bodyTruncated?, bodyOmitted?}], truncated?} (oldest→newest; type is 'xhr'|'fetch'; origin is the response host; body is the response text, omitted for binary/unavailable; urlTruncated=true means url was clipped to ~4 KiB (a prefix — don't re-fetch that url)). OPT-IN: capture must be turned on in the extension popup ('capture API responses', off by default) — when it's off you get {enabled:false, entries:[]}, NOT an error. Capture begins at the first bridge attach with the setting on — there is NO history replay, so RELOAD the tab (or navigate) after enabling so the dashboard re-fetches its data, then read. Entries are origin-filtered to the allowlist (a dashboard whose data API is on another host needs THAT host allowlisted too). Use filter (URL substring, e.g. 'stat' or 'api') to narrow to the data endpoint; limit caps recent entries (default 20, max 100). Each body is capped (~256 KiB, bodyTruncated=true); if a big result would exceed the frame budget the OLDEST bodies drop to metadata (bodyOmitted=true) — so narrow with filter + a small limit to get one report's full body, or re-pull it with fetch_in_page on the same url (note: a signed same-origin RPC like Metrika's /i-proxy/ may not be replayable, so prefer filter+limit). Structured CDP event capture only — no JS eval. Domain must be in allowlist.

Render the page to a PDF and save it into the download sandbox (~/Downloads/sallyport/, or SALLYPORT_DOWNLOAD_DIR); returns {path, size, filename} — the PDF bytes never enter the model context. filename is optional (default print-<UTC timestamp>.pdf) and must be a single name with no path separators. landscape, printBackground (default true) and scale (0.1-2, default 1) map to Page.printToPDF. Works on hidden tabs — unlike screenshot, no rendered frame is needed — so broker-mode background agent tabs are printable. Allowlist-gated; no evaluate opt-in needed. Fails with pdf_too_large when the PDF would exceed the bridge frame cap (~9 MiB binary).

Read the text content of the page, or of a specific element if ref is given. No arbitrary JS — uses CDP's Runtime.callFunctionOn with a fixed function. Output is capped at 20000 chars by default (override with maxChars, max 200000); a cut result carries truncated=true, totalChars and nextOffset. To read on past the cut, call again with offset=<nextOffset> — do NOT re-read from zero with a bigger maxChars, that pays for the same characters twice and leaves both copies in your context. Prefer ref / a scoped target over whole-page reads on chat-style SPAs.

Reload a tab. Pass bypassCache=true to force a hard reload that skips the HTTP cache (equivalent to Ctrl/Cmd+Shift+R). The destination must already be in the allowlist; refs from the previous snapshot are invalidated, so pass waitFor to poll for the reloaded page's content in the same call rather than spending a second one on wait_for. Returns {tabId, url, bypassCache} where url is where the tab ACTUALLY ended up — plus redirectedFrom when that differs from the page you reloaded, which is the usual tell that the session expired and the app bounced you to a login page. Refs are invalidated, so pass observe:{snapshot:'compact'} to get fresh ones back here rather than spending a snapshot call on it.

Scroll a virtualized container and re-snapshot until a target element appears (gets an @eN), so off-screen list items become actionable. container is the scrollport (CSS selector — more robust than @eN across re-renders). The target predicate is the same as find (role/name/nameExact/value). Scrolls in direction ('down' default / 'up') up to maxSteps (<=40) or timeoutMs (<=30000), whichever comes first. Terminates on: found, stall (reached the end), max_steps, or timeout. Returns {found, matches?, steps, reason?, source?} (source only on the found path). NOTE: this scrolls the page. Structured CDP only (fixed scroll probe), no evaluate flag. Domain must be in allowlist.

Save a base64-encoded blob to ~/Downloads/sallyport/<filename>. Runs entirely in the daemon (no extension round-trip), sandboxed: filename must be a single component with no path separators or leading dot. Override the download directory with SALLYPORT_DOWNLOAD_DIR. Returns {path, size}. Use it for a blob you already hold; to download one, prefer fetch_in_page with saveAs, which writes it without the bytes ever passing through your context.

Take a screenshot of the viewport, returned as a native MCP image block (rendered directly — no base64 handling needed). format is 'png' (default) or 'jpeg' (smaller; quality 1-100, default 80). maxWidth downscales so the returned IMAGE is at most that many pixels wide (e.g. 800) — it accounts for the display's device pixel ratio and for any set_viewport emulation, so it bounds the payload directly. region={x,y,width,height} crops to a viewport-relative CSS-px rectangle (getBoundingClientRect coordinates); it is intersected with the viewport. In broker mode your tabs live in an unfocused window of their own, so screenshot makes the target tab the active tab OF THAT WINDOW before capturing — which costs the user no focus at all — and captures normally. If the tab still can't produce a frame (window fully occluded or minimised, display asleep) the call fails with tab_not_visible after a short deadline rather than hanging; snapshot/read_text need no frame and print_to_pdf renders a hidden tab. bringToFront=true really does foreground the tab and its window and is refused in broker mode (bringtofront_forbidden). Prefer snapshot/read_text for understanding page structure.

Deterministic scrolling — the predicate-less companion to reveal (which only scrolls while hunting a target and stops on match). Two modes. (1) Bring an element into view: pass selector (CSS or @eN) with no dx/dy/to — scrollIntoView({block:'center'}); returns {mode:'into_view', x, y}. (2) Scroll the page, or a container if selector is given, by a delta or to an edge: dx/dy are CSS-px deltas (negative = left/up), OR to='top'|'bottom' jumps to the edge (don't combine to with dx/dy). Use it to trigger lazy-load / infinite-scroll feeds (page down repeatedly) — the result {mode, x, y, scrollHeight, atBottom} tells you when you've bottomed out so the loop can stop, and waitFor polls for the newly loaded content in the same call so a harvest loop costs one call per screenful instead of two. Structured CDP only (fixed scroll probe), no evaluate flag. Domain must be in allowlist.

Set the value of a NATIVE <select> dropdown (single or multiple) WITHOUT opening the OS popup — it sets the selection in the DOM and fires input+change. Use this for <select>: the OS dropdown popup is drawn by the operating system, not the page, so it cannot be driven via clicks/keys (keys are ignored, Escape just closes it); this is the reliable path. selector is a CSS selector or @eN ref. Give EXACTLY ONE of: value (option value), label (visible option text, trimmed), or index (0-based). Pass an array for <select multiple> (e.g. value=['a','c']); a single string/int selects one. Errors: wrong_element when the target is not a real <select> — custom JS comboboxes (react-select, MUI, Radix) live in the DOM, so open them with click/mouse_click and pick the option with click (find/reveal locate it) instead; not_found lists the available options; bad_args for a disabled option/select or an array against a single-select. waitFor polls after the change lands. Returns {ok, tag, multiple, selected:[{index,value,label}], wait?}.

Dispatch key events to whatever element currently HAS FOCUS — it takes no selector. Use it for keystrokes with no element target: Enter to submit, Escape to dismiss, Tab to move on, shortcuts. To write text into a named field use fill instead. Examples: 'Enter', 'Escape', 'Mod+A' (Cmd on macOS, Ctrl elsewhere), 'Shift+Tab', 'Enter Escape' (multiple, space-separated). Refuses when focus is on <input type=password> — pass allowPassword=true to override. waitFor polls for what the keystroke triggered (search results, a submitted form's next page) in the same call — prefer it over following send_keys with a separate wait_for.

Emulate a device viewport for ONE tab — DevTools device mode, not a window resize, so it disturbs neither the human's windows nor the session's other tabs, works in broker mode's unfocused window, and can produce a device pixel ratio and mobile <meta viewport> handling no window size can. preset: mobile-small (375x667), mobile (393x852), mobile-large (412x915), tablet (820x1180), desktop (1280x800), desktop-wide (1920x1080) — named by BREAKPOINT, not by device. Or give width+height in CSS px. Optional deviceScaleFactor (<=3), mobile, touch, orientation ('portrait'/'landscape' orients the size you gave). mobile:true is what makes the page honour its <meta name=viewport>; touch:true is what makes (pointer:coarse)/(hover:none)/ontouchstart match — both are real layout inputs. The mobile presets also present a mobile Chrome user agent with matching client hints (mobileUserAgent:false opts out), because a server that branches on the UA would otherwise send its desktop bundle and you would measure that — so SET IT BEFORE navigating (or reload after), since the UA and the mobile flag decide what the server sends and how the page's load-time JS branches. The override survives navigate/reload on this tab until reset:true, the tab closes, or the bridge detaches; a NEW tab starts unemulated. touch:true is feature detection only — mouse_click/hover still dispatch real mouse events, never taps. reset:true (alone) restores the real viewport; NO arguments reads what the page currently sees. Every set is a complete statement of the UA — a desktop preset clears a mobile one. Bounded at 4096 px/side, dpr<=3, 4096^2 device px (the emulated size x dpr IS a later screenshot's pixel size). Reports the PAGE's reading, not your request, plus a note when the page's own <meta viewport> sets the layout width; the dimensions live under page ({mode, requested?, page:{width, height, deviceScaleFactor, screenWidth, screenHeight, orientation, touch, maxTouchPoints, userAgent}, note?}). Invalidates @eN refs — a breakpoint change remounts DOM. Structured CDP only, no evaluate flag. Domain must be in allowlist.

Wait until the DOM stops changing for stableMs (element count AND body size both hold steady) — the adaptive replacement for a blind sleep after an action on a busy SPA. Use this when you have NO concrete thing to wait for; when you do (a selector appearing, a spinner leaving, text showing up), wait_for is a sharper signal. Polls every 250 ms up to timeoutMs (capped at 30000); stableMs is capped at 10000. Returns {settled, elapsedMs}. A page that never quiesces (live feed, animation loop), or whose probe never yields a reading, returns settled=false at the cap — not an error. Structured CDP only (fixed quiescence probe), no evaluate flag needed. Domain must be in allowlist.

Return the accessibility tree of the current/target tab. Interactive elements get stable refs like @e1, @e2 which other tools accept in place of CSS selectors. If the a11y tree exposes suspiciously few interactive elements (canvas-style SPAs like Telegram Web render an empty or stale tree), a DOM walk runs as a cross-check and whichever side finds more actionable elements wins — visible text + interactive elements with the same @eN refs; the result's source field says which path won ('a11y' or 'dom'). mode forces a path: 'auto' (default), 'a11y', 'dom'. compact=true returns a flat elements list of just the actionable elements ({ref, role, name, value?, type?}) instead of the full tree — much smaller; use it when you need something to click, not the page text. type (DOM-sourced snapshots) is the input's HTML type, so a field that reads as textbox but is actually type=password is visible before you fill it. selector (CSS or @eN) scopes the snapshot to one subtree (always a DOM walk, source='dom') — on big SPAs snapshot just the panel you work with (chat list, composer) instead of the whole page; combine with compact for the smallest result. To locate a few specific elements by role/name, find is cheaper than scanning a full snapshot. Domain must be in allowlist.

Instant daemon/extension health check — answered by the daemon itself, no browser round-trip, and it never queues behind a running tool call (it takes neither a lane nor a browser slot). Returns {connected, mode, version, port, pendingCalls, maxConcurrentCalls, uptimeS, lastCalls, lastError, lastHandshakeError, lastHandshakeErrorAt}. mode is 'broker' (a shared broker daemon serving several sessions — every act/read tool needs an explicit tabId you own, and navigate with no tabId opens a new owned tab) or 'standalone' (the active-tab fallback applies). lastCalls is the last few tool OUTCOMES (oldest→newest) as {tool, ok, ms, code?} — outcomes only, never the args — and lastError is the most recent failure {tool, code, error} or null, so you can attribute 'it just timed out' to a specific tool/code. lastCalls, lastError and pendingCalls are YOUR session's only; maxConcurrentCalls is how many calls the browser runs at once across all sessions, which is what a busy failure means you were queued behind. When connected=false, lastHandshakeError says WHY the extension leg last failed to attach (wrong secret, clock skew, no hello) — tells 'extension rejected / never attached' apart from 'attached but slow'. Use it as loop-iteration preflight: if connected=false, skip the browser work instead of burning a 60 s timeout.

Attach local files to an <input type=file>. selector is a CSS selector or a @eN ref from snapshot. paths is a non-empty array of ABSOLUTE filesystem paths (no '..' segments) — Chrome reads them via the debugger from the user's disk. The page's domain must be in the allowlist AND each path must resolve to a location under the daemon sandbox (~/Downloads/sallyport by default, override via SALLYPORT_DOWNLOAD_DIR — same dir save_to_file writes to). Paths outside the sandbox fail with unsafe_path; symlink escapes are caught by Path.resolve(). Non-file-input targets fail with wrong_element. Typical flow: fetch_in_page with saveAs=<filename> → upload from ~/Downloads/sallyport/ (saveAs keeps the bytes out of your context; the older fetch_in_page → save_to_file pair still works).

Wait until a CSS selector (or @eN ref) is present AND visible, and/or until the page's visible text contains a substring — the replacement for blind sleeps between actions. absent=true inverts both: wait until the selector/text is GONE (spinner finished, modal closed). Polls every 250 ms up to timeoutMs (default 10000, capped at 30000). At least one of selector/text is required; if both are given, both must hold. Returns {found, elapsedMs, reason?}; a timeout returns found=false (reason='timeout') rather than an error. NOTE: when the wait directly follows a navigate/click/mouse_click/fill, pass waitFor on that call instead — one round-trip less. Domain must be in allowlist.