@browserwright/pi 0.18.2 → 0.18.4

package/README.md

@@ -228,9 +228,17 @@ legitimately inside raw HTML and inside search results *about* JavaScript.
 | field | applies to | note |
 |-------|-----------|------|
 | `minChars` | text payloads only | default 0 (off) |
-| `minResults` | list payloads only | an empty list is rejected regardless |
+| `minResults` | list payloads only | an empty list is rejected regardless, unless the engine asserted it |
 | `matches` | both | searched in the text, or in joined titles + snippets |
 
+The one exception is an **asserted** empty. When a search provider reports
+`noMatch: true` — Google says "did not match any documents" in prose, on an
+ordinary HTTP 200 page — the empty list is the engine's answer and is accepted,
+`minResults` included. Everything else empty is still rejected, because that is
+what a consent wall or a captcha looks like from here. Without the distinction a
+query the engine answered correctly reaches the model as `bw_web_search failed`,
+which reads as broken tooling rather than as a query worth rewriting.
+
 `minChars` is deliberately not applied to a list, and `minResults` not to text:
 the two floors measure different things, and applying both would reject a short
 but complete set of hits.

package/core/format.ts

@@ -154,6 +154,20 @@ export function renderResults(result: ChainResult<SearchPayload>, query: string)
 		if (lines.length > 0) out.push("", "## Knowledge panel", ...lines);
 	}
 
+	if (results.length === 0) {
+		// Reaching the success path with no rows means the engine said so itself
+		// (see SearchPayload.noMatch) — everything else is rejected upstream. Say
+		// which it was, and say what to do next: the model's move here is to
+		// rewrite the query, not to conclude the tool is broken.
+		out.push(
+			"",
+			payload.noMatch
+				? "The search engine states that nothing matched this query. That is its answer, not a failure — " +
+					"widen the query before retrying: drop a `site:` path, a quoted phrase, or the least essential keywords."
+				: "No rows were extracted from the results page.",
+		);
+	}
+
 	if (results.length > 0) {
 		out.push("");
 		for (const row of results) {
@@ -171,7 +185,7 @@ export function renderResults(result: ChainResult<SearchPayload>, query: string)
 		out.push("## Related searches", payload.relatedSearches.join(" · "), "");
 	}
 
-	out.push("Use bw_web_fetch on a URL above to read it.");
+	if (results.length > 0) out.push("Use bw_web_fetch on a URL above to read it.");
 	return out.join("\n");
 }
 

package/core/predicates.ts

@@ -74,6 +74,7 @@ export const inspectText: Inspector<string> = (content) => ({ text: content });
 export const inspectSearch: Inspector<SearchPayload> = (payload) => ({
 	count: payload.results.length,
 	text: payload.results.map((r) => `${r.title} ${r.snippet ?? ""}`).join("\n"),
+	authoritativeEmpty: payload.noMatch === true,
 });
 
 /**
@@ -89,9 +90,13 @@ export function failureReason<T>(value: T, rule: FailWhen, inspect: Inspector<T>
 	const count = inspected.count;
 
 	if (count !== undefined) {
-		// A search that parsed cleanly but found nothing is a failure worth
-		// falling through on: an interstitial usually yields a valid, empty list
-		// rather than an error.
+		// An engine that said "no documents matched" has answered the question.
+		// Accepting that is what stops a correctly-answered query from reaching
+		// the model as a failed tool call; the needle scan below is skipped with
+		// it, which costs nothing because the haystack is empty either way.
+		if (count === 0 && inspected.authoritativeEmpty) return undefined;
+		// Any other empty list is a failure worth falling through on: an
+		// interstitial usually yields a valid, empty list rather than an error.
 		if (count === 0) return "no results";
 		const minResults = rule.minResults ?? 0;
 		if (minResults > 0 && count < minResults) {

package/core/results.ts

@@ -20,6 +20,7 @@ const ANSWER_KEYS = ["answerBox", "answer_box", "answer", "featured_snippet"] as
 const KG_KEYS = ["knowledgeGraph", "knowledge_graph"] as const;
 const PAA_KEYS = ["peopleAlsoAsk", "people_also_ask", "relatedQuestions"] as const;
 const RELATED_KEYS = ["relatedSearches", "related_searches", "relatedQueries"] as const;
+const NO_MATCH_KEYS = ["noMatch", "no_match", "zeroResults"] as const;
 
 function firstValue(row: Record<string, unknown>, keys: readonly string[]): unknown {
 	for (const key of keys) {
@@ -137,5 +138,9 @@ export function normalizeSearchPayload(value: unknown): SearchPayload {
 	const relatedSearches = stringList(firstValue(body, RELATED_KEYS));
 	if (relatedSearches) payload.relatedSearches = relatedSearches;
 
+	// Only meaningful next to an empty list. A source claiming both rows and
+	// "nothing matched" is contradicting itself, and the rows are the evidence.
+	if (payload.results.length === 0 && firstValue(body, NO_MATCH_KEYS) === true) payload.noMatch = true;
+
 	return payload;
 }

package/core/types.ts

@@ -60,6 +60,18 @@ export interface KnowledgeGraph {
  */
 export interface SearchPayload {
 	results: SearchResult[];
+	/**
+	 * The engine stated, in so many words, that nothing matched.
+	 *
+	 * Only ever set alongside an empty `results`, and it is the one thing that
+	 * separates an honestly empty search from the failure mode that looks
+	 * identical from the outside: a captcha or consent wall parses perfectly and
+	 * also yields zero rows. Without this flag both have to be rejected, and a
+	 * query the engine answered correctly is reported to the model as a broken
+	 * tool — which is exactly what it then works around instead of rewriting the
+	 * query.
+	 */
+	noMatch?: boolean;
 	answerBox?: AnswerBox;
 	knowledgeGraph?: KnowledgeGraph;
 	peopleAlsoAsk?: string[];
@@ -236,6 +248,12 @@ export interface Inspected {
 	text: string;
 	/** Item count, for list payloads. Undefined for text payloads. */
 	count?: number;
+	/**
+	 * A zero count that the source asserted rather than one we inferred from a
+	 * payload we could not read. Lifts the blanket rejection of an empty list —
+	 * see `SearchPayload.noMatch`.
+	 */
+	authoritativeEmpty?: boolean;
 }
 
 export type Inspector<T> = (value: T) => Inspected;

package/index.ts

@@ -180,6 +180,9 @@ export default function (pi: ExtensionAPI) {
 					query,
 					provider: result.provider,
 					count: result.content?.results.length ?? 0,
+					// Zero rows is a success now, so the trace has to record which
+					// kind of zero it was.
+					noMatch: result.content?.noMatch === true,
 					features: {
 						answerBox: Boolean(result.content?.answerBox),
 						knowledgeGraph: Boolean(result.content?.knowledgeGraph),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserwright/pi",
-  "version": "0.18.2",
+  "version": "0.18.4",
   "description": "bw_web_fetch and bw_web_search for the pi coding agent, using browserwright plus a raw text fallback",
   "license": "AGPL-3.0-only",
   "type": "module",

package/providers/browserwright-search.json

@@ -31,7 +31,11 @@
     "them as a reason.",
     "minResults 1 is the real guard. A captcha or consent wall parses perfectly",
     "and yields an empty list, which is the failure mode that would otherwise be",
-    "indistinguishable from an honestly empty search.",
+    "indistinguishable from an honestly empty search. The extractor tells the two",
+    "apart by reading Google's own sentence ('did not match any documents') off",
+    "the page and setting noMatch, which lifts minResults for that one case: an",
+    "engine that says nothing matched has answered the query, and reporting that",
+    "as a tool failure only teaches the model to route around a working tool.",
     "searchUrl is a template so the engine can be swapped without touching code.",
     "{queryEncoded} and {limit} are the only substitutions.",
     "SERP features (measured 2026-08-10, see docs/adr/0008). The page is server-",

package/providers/browserwright-search.ts

@@ -246,6 +246,17 @@ function buildScript(query: string, limit: number, outPath: string, searchUrl: s
     return out.slice(0, 10);
   }, []);
 
+  // --- explicit "nothing matched" ---------------------------------------
+  // Google says this in prose on an otherwise ordinary page: no error, no
+  // interstitial, HTTP 200, zero rows. Reading the sentence is the only way to
+  // tell that empty list apart from the one a consent wall produces. Measured
+  // 2026-09-02 on a site:-with-path query, which is the shape that reaches zero
+  // most often.
+  const noMatch = attempt(() => {
+    const body = (document.body.innerText || '').toLowerCase();
+    return ['did not match any documents', 'no results found for'].some((n) => body.includes(n));
+  }, false);
+
   // --- related searches --------------------------------------------------
   // Scoped to #botstuff: the same href pattern at the top of the page is
   // Google's own tab bar ("Images", "News", "Past hour"), not a related query.
@@ -266,7 +277,7 @@ function buildScript(query: string, limit: number, outPath: string, searchUrl: s
     return out.slice(0, 10);
   }, []);
 
-  return { results, answerBox, knowledgeGraph, peopleAlsoAsk, relatedSearches };
+  return { results, answerBox, knowledgeGraph, peopleAlsoAsk, relatedSearches, noMatch };
 }`;
 
 	// json.dumps gives us correctly escaped Python string literals for free, so
@@ -310,6 +321,9 @@ function buildScript(query: string, limit: number, outPath: string, searchUrl: s
 		'            "knowledgeGraph": data.get("knowledgeGraph"),',
 		'            "peopleAlsoAsk": data.get("peopleAlsoAsk") or [],',
 		'            "relatedSearches": data.get("relatedSearches") or [],',
+		// Only ever consulted when rows is empty, but carried unconditionally so
+		// the shape of the payload does not depend on the outcome.
+		'            "noMatch": bool(data.get("noMatch")),',
 		"        }",
 		"        if not rows:",
 		// An interstitial parses fine and yields zero rows; say which kind it was.