aboutsummaryrefslogtreecommitdiff
path: root/src/domains/search/web-search.ts
diff options
context:
space:
mode:
authoramankumarsingh77 <amankumarsingh7702@gmail.com>2026-07-08 21:13:15 +0530
committeramankumarsingh77 <amankumarsingh7702@gmail.com>2026-07-08 21:13:15 +0530
commitc5c42df5976ed63faac2adcf3b04a4ad2f519b32 (patch)
tree77d389a590864eaf5c2408c9bc99ed07f55343d8 /src/domains/search/web-search.ts
parent7826c950adee89512162185d07fee565ab0e96cc (diff)
feat: add browser_web_search tool (real-Chrome SERP scrape, no API key)
Thin query→ranked-links primitive. Isolated-attach tab lifecycle mirroring browser_open_urls (never touches the user's current tab); pure Google SERP parser with semantic (a h3) extraction and redirect unwrapping; CAPTCHA and no-results surfaced as invalid_state + details.reason. Fixture-based parser tests (9 scenarios). Establishes the isolated-tab lifecycle and tsx+fixture test convention that browser_read_page and deep-research build on. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Diffstat (limited to 'src/domains/search/web-search.ts')
-rw-r--r--src/domains/search/web-search.ts106
1 files changed, 106 insertions, 0 deletions
diff --git a/src/domains/search/web-search.ts b/src/domains/search/web-search.ts
new file mode 100644
index 0000000..e5d343d
--- /dev/null
+++ b/src/domains/search/web-search.ts
@@ -0,0 +1,106 @@
+import { Type } from "typebox";
+import { type Result, err, ok } from "../../util/result";
+import { applyTruncation } from "../../util/truncate";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../../util/tool";
+import {
+ closeIsolatedTab,
+ evalInIsolatedTab,
+ navigateIsolatedTab,
+ openIsolatedTab,
+ waitForIsolatedLoad,
+} from "../isolated-tab";
+import { buildSerpExtractionExpr } from "./extract";
+import { classifySerp, parseGoogleSerp, type SearchResult, type SerpExtraction } from "./google-serp";
+
+const LOAD_TIMEOUT_MS = 15_000;
+
+const WebSearchArgs = Type.Object({
+ query: Type.String({ description: "The search query." }),
+ limit: Type.Optional(
+ Type.Integer({ default: 10, minimum: 1, maximum: 30, description: "Max results to return. Default: 10." }),
+ ),
+});
+
+const buildSerpUrl = (query: string, limit: number): string =>
+ `https://www.google.com/search?q=${encodeURIComponent(query)}&num=${limit}&hl=en`;
+
+const isSerpExtraction = (value: unknown): value is SerpExtraction => {
+ if (typeof value !== "object" || value === null) return false;
+ const v = value as Record<string, unknown>;
+ return Array.isArray(v["anchors"]) && typeof v["pageText"] === "string";
+};
+
+const formatResults = (query: string, results: ReadonlyArray<SearchResult>): string => {
+ const lines = results.map((r) => `${r.rank}. ${r.title}\n ${r.url}\n ${r.snippet}`);
+ return `${results.length} result(s) for "${query}":\n\n${lines.join("\n\n")}`;
+};
+
+export const webSearchTool = defineBrowserTool({
+ name: "browser_web_search",
+ label: "Browser Web Search",
+ description:
+ "Search the web and return ranked results (title, url, snippet, rank). Scrapes a Google results page in the real Chrome — no API key. Returns links only; use browser_read_page to read a result's content.",
+ promptSnippet: "Search the web for a query",
+ promptGuidelines: [
+ "Returns ranked {title, url, snippet, rank} — links only, no page content. Follow up with browser_read_page.",
+ "On a CAPTCHA / bot wall the call fails with kind:'invalid_state' and details.reason:'captcha' (plus serpUrl) — surface it to the user; do not retry in a tight loop.",
+ "On zero results it fails with details.reason:'no_results' — rephrase the query and try again.",
+ "Runs in its own isolated tab and never disturbs the user's current tab.",
+ ],
+ parameters: WebSearchArgs,
+ async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
+ const limit = args.limit ?? 10;
+ const serpUrl = buildSerpUrl(args.query, limit);
+
+ const opened = await openIsolatedTab(client);
+ if (!opened.success) return err(opened.error);
+ const tab = opened.data;
+
+ try {
+ const navigated = await navigateIsolatedTab(client, tab, serpUrl);
+ if (!navigated.success) return err(navigated.error);
+
+ const loaded = await waitForIsolatedLoad(client, tab, LOAD_TIMEOUT_MS, signal);
+ if (!loaded.success) return err(loaded.error);
+
+ const extracted = await evalInIsolatedTab(client, tab, buildSerpExtractionExpr());
+ if (!extracted.success) return err(extracted.error);
+
+ const parsedJson = typeof extracted.data === "string" ? safeParse(extracted.data) : extracted.data;
+ if (!isSerpExtraction(parsedJson)) {
+ return err({ kind: "internal", message: "SERP extraction returned an unexpected shape" });
+ }
+
+ const results = parseGoogleSerp(parsedJson.anchors, limit);
+ const verdict = classifySerp(parsedJson.pageText, results.length);
+ if (verdict !== "ok") {
+ return err({
+ kind: "invalid_state",
+ message: verdict === "captcha" ? "Google served a CAPTCHA / bot wall" : "no results found",
+ details: { reason: verdict, serpUrl },
+ });
+ }
+
+ const truncated = await applyTruncation(formatResults(args.query, results), "search");
+ return ok({
+ text: truncated.text,
+ details: {
+ results,
+ engine: "google",
+ query: args.query,
+ ...(truncated.fullOutputPath !== undefined ? { fullOutputPath: truncated.fullOutputPath } : {}),
+ },
+ });
+ } finally {
+ await closeIsolatedTab(client, tab);
+ }
+ },
+});
+
+const safeParse = (text: string): unknown => {
+ try {
+ return JSON.parse(text) as unknown;
+ } catch {
+ return undefined;
+ }
+};