Skip to content

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.

docs(tools): document page_findSearch and page_searchSite

Shahriarda07bc0976d4
diff --git a/README.md b/README.md
index 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.md
index 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.md
index 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.md
index 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 and
the 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.md
index 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, any
running monitors, and a `hint` naming the fix when something is wrong. Call it first when a page
tool fails.
diff --git a/docs/internals/registry.md b/docs/internals/registry.md
index 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.md
index 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.md
index 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.md
index 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_screenshot
Capture 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_navigate
Navigate the current tab to a URL, or go back, forward, or reload in its history. Give one of