Wisp talks to the Browser Runtime. Shared mode uses the user's daily\nChrome via the unpacked extension — every action runs in their real\nprofile: existing cookies, logins, extensions, and normal fingerprint all\napply. Workspace mode can launch a separate Chrome profile. If both are\nconnected, pass session: \"shared\" or session: \"workspace\". If\nSettings → Browser has Open browser automatically enabled (the\ndefault) and no extension is connected, Wisp may start the installed\nChrome/Chromium/Edge so the extension can reconnect. That is still the\nuser's profile, not Playwright or Selenium.
Shared is the default; workspace is not a fallback. Google Chrome 137\nand later ignore --load-extension, so on a machine with only branded\nChrome the workspace window cannot load the Wisp extension at all.\nbrowser_setup {\"action\":\"start_workspace\"} therefore returns only once\nthe workspace extension has connected, and otherwise closes the window\nand fails with WORKSPACE_EXTENSION_BLOCKED. On that error: relay the\nmessage, do not retry start_workspace, do not claim any workspace page\nwas opened or read, and get the shared session working instead.
For figures/code extraction use web_scan with mode: \"article\" then\nweb_save_assets. For ChatGPT web one-shot use web_agent_send,\nweb_agent_wait, web_agent_read on an already-logged-in tab.
Every web_scan and web_execute_js call needs the user's approval by\ndesign. Do not treat that as a bug to route around.
Call browser_setup. If status is not connected (or live_retrieval\nis false), relay its steps (load the unpacked extension from\nextension_path, verbatim) and stop. Do not answer live, latest,\ncurrent, or URL-specific questions from prior knowledge. Tell the user\nthis turn contains no live web retrieval and wait until the popup shows\nConnected to Wisp. Only continue from memory if they explicitly ask\nfor a knowledge-only answer. Never invent the path.
Two fields say why a browser that looks connected is not usable —\nnever report a bare \"not connected\" when either is set:
\nrefused_connection — something reached the bridge port and Wisp\nrefused it (usually a different extension id, or another loopback\nbridge holding the port). Its popup can still read Connected to Wisp.\nRelay refused_connection.explanation.reload_required — a connected extension is older than the protocol\nthis build needs. Have the user open chrome://extensions and\nReload Wisp Real Browser Bridge from extension_path; Chrome does\nnot auto-update an unpacked extension.One exception: the user says the extension is already installed. Chrome\nsuspends its service worker when idle and reconnects on a one-minute\nalarm, so disconnected can just be a sleeping worker. Try web_open_tab\nor web_scan once — a successful call proves the bridge is live — and\nrelay the install steps only if that call fails too.
web_open_tab {url} — open the page (works even with no tab\nopen yet). Waits until the document is complete, then returns the new\ntab id plus ready. If ready is false, the load timed out — call\nweb_scan before acting.web_scan — read the page (after waiting for document complete).\nReturns page.text, page.title, page.ready_state, and\npage.elements[], where each element carries a unique selector,\nits visible text/aria_label, and a rect [x,y,w,h]. Use these\nselectors directly — do not guess. If ready is false, scan again;\ndo not click a partial page. Use tabs_only:true first when you are\nunsure which tab to target; pass switch_tab_id:<id> to pin one.web_execute_js — act, then re-scan to confirm the effect. The\nextension waits for complete before running the script, and again if\nthe script navigates.web_execute_js script)| Goal | \nscript | \n
|---|---|
| Click | \ndocument.querySelector('<selector>').click() | \n
| Type into a field | \nconst e=document.querySelector('<sel>'); e.value='text'; e.dispatchEvent(new Event('input',{bubbles:true})); e.dispatchEvent(new Event('change',{bubbles:true})) | \n
| Submit a form | \nclick the submit control by its selector, then re-scan | \n
| Navigate current tab | \nlocation.href='https://example.com' | \n
| Read a value | \ndocument.querySelector('<sel>').textContent | \n
script may instead be a JSON command:
| Goal | \nJSON command | \n
|---|---|
| Switch to & focus a tab (so the user sees it) | \n{\"cmd\":\"tabs\",\"method\":\"switch\",\"tabId\":<id>} | \n
| List tabs | \n{\"cmd\":\"tabs\"} (or just web_scan tabs_only) | \n
| Close tabs you opened | \n{\"cmd\":\"tabs\",\"method\":\"close\",\"tabIds\":[<id>,...]} — returns closed + remaining | \n
Trusted click when .click() is ignored | \n{\"cmd\":\"cdp\",\"method\":\"Input.dispatchMouseEvent\",\"params\":{\"type\":\"mousePressed\",\"x\":<x>,\"y\":<y>,\"button\":\"left\",\"clickCount\":1}} then the same with \"type\":\"mouseReleased\" — use the element's rect centre from web_scan | \n
Prefer plain JS. Reach for cmd:cdp only when a page blocks synthetic\nevents or you truly need trusted input.
web_screenshotweb_scan gives text and elements; web_screenshot gives sight. Use it\nwhen structure isn't enough: rendered layout, a chart or diagram, a\ncanvas/WebGL page, a QR code, a PDF or image viewer, or a page that looks\nbroken. It captures the visible viewport of the tab — to see below the\nfold, scroll first (web_execute_js scrollTo(0, 1200)) and capture again.\nPass question to say what to read out of it, e.g.\n{\"question\":\"is the login QR code visible and not expired?\"}.
It goes through the configured vision model, so web_scan stays the cheaper\ndefault — screenshot when you need eyes, not for every step.
Browsing tasks (searching papers, opening a dozen results) leave the user\nwith a pile of tabs to close by hand. So:
\nweb_open_tab returns tab.id. Keep a running list of the ids\nyou opened in this task, in your own message text — e.g. after a batch\nwrite opened tabs: 1234, 1235, 1236. {\"cmd\":\"tabs\"} cannot tell you\nwhich tabs are yours, only what exists.{\"cmd\":\"tabs\",\"method\":\"close\",\"tabIds\":[1234,1235,1236]}. Report\nclosed; ids already gone are skipped silently.Close only ids you opened yourself. Tabs the user had open, or ones\nthey opened during the task, are theirs — never include them, and never\nclose a tab mid-task that later steps still need.
\nweb_scan returns\nhuman_intervention.required=true, stop, ask the user to complete the\nchallenge in the visible tab, and wait for their confirmation before\nscanning again.browser_setup (download_automation) and wait for the\nuser to confirm; until then trigger at most one download.web_open_tab or a navigational web_execute_js\nfails with blocked by user URL filter, do not retry that site. Read\nbrowser_setup.url_filters.block for the current list. Prefer entries in\nurl_filters.prefer for literature search and similar retrieval; other\nsites are still allowed.