An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
docs(tools): document page_findSearch and page_searchSite
Shahriarda07bc0976d4
diff --git a/README.md b/README.mdindex 6547737..2381906 100644--- a/README.md+++ b/README.md@@ -8,7 +8,7 @@ Hand your real, logged-in browser to the AI agent you already run. Browsentic is- **Your Real Browser, Not a Headless One**: Drives the tab in front of you, in your own profile, with your own logins and sessions- **Bring Your Own Agent**: Runs on the agent CLI you already pay for and are already signed in to — switch between Claude Code, Codex and Antigravity with one click-- **35 Page Capabilities**: Reading, clicking, typing, dragging, form submission, navigation, screenshots, captchas, theming and accessibility, and background progress monitoring+- **37 Page Capabilities**: Reading, clicking, typing, dragging, on-site search, form submission, navigation, screenshots, captchas, theming and accessibility, and background progress monitoring- **Voice, Text, or Demonstration**: Dictate in the side panel, type anywhere, or record yourself doing a job once and later say "do it like last time"- **Teach It a Site Once**: Point it at a site and it explores and writes reusable notes, so every later session already knows its way around- **Instant Commands**: "Go back", "scroll to the top", "open github.com" run in the browser in milliseconds instead of becoming an agent round trip@@ -62,7 +62,7 @@ The extension dials out to the daemon, because a Manifest V3 service worker cann- 📚 [Documentation](docs/)- 🚀 [Install and Pair](docs/guide/install.md)- ✨ [Features](docs/guide/features/)-- 🧰 [All 35 Page Tools](docs/reference/tools.md)+- 🧰 [All 37 Page Tools](docs/reference/tools.md)- 🔌 [Use It From Claude Code, Cursor or Zed](docs/guide/mcp-clients.md)- 🛡️ [Approvals and Guardrails](docs/guide/approvals.md)- 🏗️ [Architecture](docs/internals/)diff --git a/docs/README.md b/docs/README.mdindex 5a6bf13..21b0ba8 100644--- a/docs/README.md+++ b/docs/README.md@@ -50,7 +50,7 @@ How the pieces actually work, for contributors and for anyone integrating.| | || --- | --- |-| [Tools](reference/tools.md) | All 35 MCP tools with their parameters, plus the resources |+| [Tools](reference/tools.md) | All 37 MCP tools with their parameters, plus the resources || [CLI](reference/cli.md) | Every `browsentic-mcp` command || [Errors](reference/errors.md) | Every error code, what caused it, what to do |diff --git a/docs/guide/features/README.md b/docs/guide/features/README.mdindex fb99638..b09084c 100644--- a/docs/guide/features/README.md+++ b/docs/guide/features/README.md@@ -17,7 +17,7 @@ first.| | || --- | --- |-| [Page actions](page-actions.md) | The 35 things it can do to a page, grouped by what you would want |+| [Page actions](page-actions.md) | The 37 things it can do to a page, grouped by what you would want || [Screenshots](screenshots.md) | Viewport, full page, or one element — and when a capture touches disk || [Theming](theming.md) | Dark mode on a site that has none, and a real WCAG contrast audit || [Captchas](captcha.md) | What it will and will not do at a "verify you are human" block |diff --git a/docs/guide/features/page-actions.md b/docs/guide/features/page-actions.mdindex 5933c14..6e6f347 100644--- a/docs/guide/features/page-actions.md+++ b/docs/guide/features/page-actions.md@@ -1,6 +1,6 @@# Page actions-The 35 things Browsentic can do to a page. You never have to name these — you say what you want and+The 37 things Browsentic can do to a page. You never have to name these — you say what you want andthe agent picks — but knowing what exists tells you what is worth asking for.Exact parameters for every one: [reference/tools.md](../../reference/tools.md).@@ -25,6 +25,7 @@ by **visible text** survives redesigns that break CSS paths.| `page_extractText` | Rendered text of an element or the whole page. Raw HTML is [denied by default](../approvals.md) || `page_waitForElement` | Wait until an element is attached, visible, hidden or detached || `page_findProgress` | Scan for progress signals worth [monitoring](monitoring.md) |+| `page_findSearch` | Report whether this site has a search of its own, where its box is, and the URL a search lands on || `page_screenshot` | See [Screenshots](screenshots.md) |## Clicking and typing@@ -48,6 +49,7 @@ by **visible text** survives redesigns that break CSS paths.| | || --- | --- |+| `page_searchSite` | Search this site with its own search, by its search URL or its search box, and land on the results || `page_navigate` | Go to a URL, or back / forward / reload || `page_scrollTo` | To an element, an absolute position, or by one viewport || `page_openTab` | Open a URL in a new tab, which becomes the target for later actions unless `active: false` |diff --git a/docs/guide/mcp-clients.md b/docs/guide/mcp-clients.mdindex 81ea2f8..bdbd542 100644--- a/docs/guide/mcp-clients.md+++ b/docs/guide/mcp-clients.md@@ -44,7 +44,7 @@ Tools missing from a session you registered mid-flight is the single most common## What the client gets-- **35 page tools** — every one listed with its parameters in [reference/tools.md](../reference/tools.md)+- **37 page tools** — every one listed with its parameters in [reference/tools.md](../reference/tools.md)- **`browsentic_status`** — whether the extension is connected, its version, the active tab, anyrunning monitors, and a `hint` naming the fix when something is wrong. Call it first when a pagetool fails.diff --git a/docs/internals/registry.md b/docs/internals/registry.mdindex ac2c213..01146b8 100644--- a/docs/internals/registry.md+++ b/docs/internals/registry.md@@ -6,7 +6,7 @@ One definition, compiled into two bundles.## One array, two consumers-There are **35 page capabilities**. They are defined once, in+There are **37 page capabilities**. They are defined once, in[`lib/actions/registry.ts`](../../lib/actions/registry.ts), and that array is compiled into **both**the extension and the daemon.diff --git a/docs/reference/README.md b/docs/reference/README.mdindex ca43afe..bcc6bc6 100644--- a/docs/reference/README.md+++ b/docs/reference/README.md@@ -5,7 +5,7 @@ Lookup tables. Nothing here explains a workflow — see the [user guide](../guid| | || --- | --- |-| [Tools](tools.md) | All 35 MCP tools with their parameters, the three read-only resources, and the reserved actions that never become tools |+| [Tools](tools.md) | All 37 MCP tools with their parameters, the three read-only resources, and the reserved actions that never become tools || [CLI](cli.md) | Every `browsentic-mcp` command || [Errors](errors.md) | Every error code, where it comes from, and what to do about it |diff --git a/docs/reference/errors.md b/docs/reference/errors.mdindex f4bef75..5cb74fc 100644--- a/docs/reference/errors.md+++ b/docs/reference/errors.md@@ -61,7 +61,7 @@ repeatedly: failures carry the *fix* in the message, and a failed tool call neve| --- | --- | --- || `DECLINED` | Approval gate | The user said no. **Final** — do not seek another route to the same effect || `BLOCKED` | Policy | A `deny` rule matched, or a `confirm` with nobody to answer it. The message names why. [Guide](../guide/approvals.md) |-| `MAPPING_READ_ONLY` | Mapping gate | A mapping run may only call the 13 read-only actions (plus `page_clickElement` when `allowClicks` is on) |+| `MAPPING_READ_ONLY` | Mapping gate | A mapping run may only call the 14 read-only actions (plus `page_clickElement` when `allowClicks` is on) || `MAPPING_OFF_SITE` | Mapping gate | Navigation must be an absolute URL on the mapped origin — `back` and `forward` included || `MAPPING_BUDGET` | Mapping gate | The page or screenshot budget is spent || `MAPPING_TAB_CHANGED` | Mapping gate | The tab the run was pinned to is gone |diff --git a/docs/reference/tools.md b/docs/reference/tools.mdindex 5cb9a99..401fcc3 100644--- a/docs/reference/tools.md+++ b/docs/reference/tools.md@@ -21,9 +21,9 @@ The surface, at a glance:| Group | Tools || --- | --- || [Status](#status) | `browsentic_status` |-| [Reading](#reading) | `page_getPageInfo`, `page_extractText`, `page_waitForElement`, `page_findProgress`, `page_screenshot` |+| [Reading](#reading) | `page_getPageInfo`, `page_extractText`, `page_waitForElement`, `page_findProgress`, `page_findSearch`, `page_screenshot` || [Acting](#acting) | `page_clickElement`, `page_trustedClick`, `page_findCaptcha`, `page_solveCaptcha`, `page_hoverElement`, `page_dragElement`, `page_focusInput`, `page_fillInput`, `page_typeText`, `page_selectOption`, `page_selectText`, `page_pressKey`, `page_submitForm`, `page_highlightElement` |-| [Moving](#moving) | `page_navigate`, `page_scrollTo`, `page_openTab`, `page_switchTab`, `page_closeTab` |+| [Moving](#moving) | `page_searchSite`, `page_navigate`, `page_scrollTo`, `page_openTab`, `page_switchTab`, `page_closeTab` || [Theming](#theming) | `page_readTheme`, `page_auditContrast`, `page_applyTheme` || [Monitoring](#monitoring) | `page_startMonitor`, `page_monitorStatus`, `page_awaitMonitor`, `page_stopMonitor` || [Files](#files) | `page_listFiles`, `page_attachFile` |@@ -127,6 +127,26 @@ like instead of starting a monitor.| --- | --- | --- | --- || `maxCandidates` | integer | `10` | Cap on candidates returned, strongest signals first |+### page_findSearch++Report how this site can be searched from where you are: the search boxes on the page — including+one hidden behind a header toggle — the buttons that reveal them, links to a search page, and the+URL template a search would land on, with `{query}` where the words go. Read-only: it never types+and never navigates.++`searchable: false` with empty lists is the honest answer that this site has no search of its own.+`template` comes from the site's own GET search form where there is one (`templateFrom: "form"`),+otherwise from the current address when it already carries a search parameter+(`templateFrom: "address"`), which is how a re-search keeps the filters you are looking at. A field+reported with `hidden: true` is in the DOM but not on screen — click the `toggles` entry first.++It is one of the read-only actions a [site-mapping run](#mapping-runs-only) may call, so a map can+record where a site's search lives. `page_searchSite` is not — it navigates.++| Parameter | Type | Default | Purpose |+| --- | --- | --- | --- |+| `maxPerKind` | integer | `5` | Cap on search boxes, toggles and links listed per kind, most likely first |+### page_screenshotCapture the tab as a JPEG or PNG — the current viewport, the full scroll view, or a single@@ -380,6 +400,30 @@ the user what was found.## Moving+### page_searchSite++Search the site you are on, using that site's own search rather than a web search engine. It works+out how this site searches and does it in one call: `strategy: "auto"` goes straight to the URL the+site's search form would land on when one can be derived — which skips the autocomplete overlay+entirely — and types into the search box when it cannot.++It stays on the current site. If this site hands its search to another host the call is refused with+`UNSUPPORTED` naming the URL, so that navigation goes through `page_navigate` and the guardrails+that judge it. `query` is capped at 200 characters: this is a search box, not a channel for sending+a site a payload.++The result reports `via` (`"url"` or `"field"`), `landedOn` — the tab's URL once the search settled,+which is how you confirm it ran — and `loaded`. It does **not** read the results: snapshot with+`page_getPageInfo` or `page_extractText` afterwards. Two refusals name their own fix: a hidden+search box names the toggle to click first, and a page with no search at all points at+`page_findSearch`.++| Parameter | Type | Default | Purpose |+| --- | --- | --- | --- |+| `query` | string | required | What to look for on this site. 1–200 characters |+| `strategy` | `"auto"` \| `"url"` \| `"field"` | `"auto"` | `"url"` insists on the search URL, `"field"` insists on typing — which is what a box that filters as you type needs |+| `target` | [target](#element-targets) | — | The search box to use, when the page has several or the one picked was wrong |+### page_navigateNavigate the current tab to a URL, or go back, forward, or reload in its history. Give one of