@browserwright/pi 0.0.1

package/index.ts

@@ -0,0 +1,276 @@
+/**
+ * @browserwright/pi — `web_fetch` and `web_search` for pi, backed by
+ * declarative providers that drive browserwright.
+ *
+ * A provider is a JSON file in providers/; adding one needs no code change.
+ * This package ships only the browserwright rungs, which are the ones that
+ * carry the user's login state. Drop your own JSON in to add a cheaper or
+ * anonymous rung ahead of them. See README.md for the contract.
+ */
+
+import { Type } from "typebox";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { makeExecutor, runChain } from "./core/chain.ts";
+import { EXTENSION_DIR, loadConfig, loadProviders } from "./core/config.ts";
+import { renderFailure, renderResults, renderSuccess } from "./core/format.ts";
+import { inspectSearch, inspectText, providersForRole } from "./core/predicates.ts";
+import { formatProbeReport, loadProbeCases, runProbe, saveProbeEvidence } from "./core/probe.ts";
+import type { PiConfig, Provider, Role, SearchPayload } from "./core/types.ts";
+
+/**
+ * A chain failure is reported by THROWING, not by returning a flag.
+ *
+ * `AgentToolResult` has no `isError` field: pi's agent loop hardcodes
+ * `isError: false` on the normal return path and only sets it in the catch
+ * around `execute`. Returning `{isError: true}` therefore records a failed call
+ * as a successful one — the TUI does not mark it, and observers of the
+ * `tool_result` event see `isError: false`.
+ */
+class ToolFailure extends Error {}
+
+export default function (pi: ExtensionAPI) {
+	const config = loadConfig();
+	const providers = loadProviders();
+
+	const namesFor = (role: Role): string[] => [...providersForRole(providers, role).keys()];
+	const fetchNames = namesFor("fetch");
+	const searchNames = namesFor("search");
+
+	if (fetchNames.length === 0 && searchNames.length === 0) {
+		console.error("[browserwright-pi] no provider declarations found in providers/ — both tools will always fail");
+	}
+
+	// setStatus is TUI/RPC only; print and json modes have no UI to update.
+	const statusReporter =
+		(ctx: ExtensionContext, onUpdate?: (partial: { content: Array<{ type: "text"; text: string }> }) => void) =>
+		(text: string) => {
+			if (ctx.hasUI) ctx.ui.setStatus("browserwright", text);
+			onUpdate?.({ content: [{ type: "text", text: `*${text}*` }] });
+		};
+
+	// ---- web_fetch ---------------------------------------------------------
+
+	pi.registerTool({
+		name: "web_fetch",
+		label: "Fetch Web Page",
+		description:
+			"Fetch a URL and return its content as Markdown. " +
+			`Tries providers in order until one returns usable content: ${config.order.fetch.join(" → ")}. ` +
+			"The response header states which provider answered and what format the body is in. " +
+			"Output over 50KB is truncated and the full text written to a temp file whose path is given.",
+		promptSnippet: "Fetch a URL as markdown, through the user's real browser",
+		promptGuidelines: [
+			"Prefer `web_fetch` over curl or a shell HTTP client for reading web pages — it renders JavaScript " +
+				"and carries the user's login state, so it can read pages an anonymous request cannot.",
+		],
+		parameters: Type.Object({
+			url: Type.String({ description: "HTTP(S) URL to fetch" }),
+			provider: Type.Optional(
+				Type.String({
+					description:
+						`Force one provider instead of the automatic chain (${fetchNames.join(", ") || "none declared"}). ` +
+						"Forcing disables fallback.",
+				}),
+			),
+		}),
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			const url = /^https?:\/\//i.test(params.url) ? params.url : `https://${params.url}`;
+			const setStatus = statusReporter(ctx, onUpdate);
+
+			const result = await runChain<string>({
+				providers,
+				config,
+				role: "fetch",
+				subject: url,
+				inspect: inspectText,
+				forced: params.provider,
+				executor: makeExecutor<string>(config, { dir: EXTENSION_DIR, role: "fetch", signal }),
+				onAttempt: (provider, index, total) =>
+					setStatus(`🌐 ${provider.label ?? provider.name} (${index + 1}/${total})`),
+			});
+
+			if (ctx.hasUI) ctx.ui.setStatus("browserwright", "");
+
+			if (!result.ok) {
+				throw new ToolFailure(renderFailure(result, url, { tool: "web_fetch", alternatives: fetchNames }));
+			}
+
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: renderSuccess(result, { url, maxBytes: config.maxBytes, maxLines: config.maxLines }),
+					},
+				],
+				details: {
+					url,
+					provider: result.provider,
+					format: result.format,
+					chars: result.content?.length ?? 0,
+					attempts: result.attempts,
+				},
+			};
+		},
+	});
+
+	// ---- web_search --------------------------------------------------------
+
+	pi.registerTool({
+		name: "web_search",
+		label: "Search the Web",
+		description:
+			"Search the web and return ranked results as title, URL, snippet and date. " +
+			`Providers in order: ${config.order.search.join(" → ")}. ` +
+			"Also returns the engine's own AI Overview, knowledge panel, 'people also ask' and " +
+			"related searches when that query triggered them. Returns links, never page bodies — " +
+			"call web_fetch on the ones worth reading.",
+		promptSnippet: "Search the web and get back ranked links",
+		promptGuidelines: [
+			"`web_search` returns links, not page contents. After searching, call `web_fetch` on the one or two " +
+				"results actually worth reading rather than fetching all of them.",
+		],
+		parameters: Type.Object({
+			query: Type.String({ description: "What to search for" }),
+			provider: Type.Optional(
+				Type.String({
+					description:
+						`Force one provider instead of the automatic chain (${searchNames.join(", ") || "none declared"}). ` +
+						"Forcing disables fallback.",
+				}),
+			),
+		}),
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			const query = params.query.trim();
+			if (!query) throw new ToolFailure("web_search needs a non-empty query");
+			const setStatus = statusReporter(ctx, onUpdate);
+
+			const result = await runChain<SearchPayload>({
+				providers,
+				config,
+				role: "search",
+				subject: query,
+				inspect: inspectSearch,
+				forced: params.provider,
+				executor: makeExecutor<SearchPayload>(config, {
+					dir: EXTENSION_DIR,
+					role: "search",
+					signal,
+					// Only module providers stream, and the search rung is why
+					// that capability exists: it is slow enough that the user
+					// deserves to see which phase it is in.
+					onProgress: (text) => setStatus(`🔎 ${text}`),
+				}),
+				onAttempt: (provider, index, total) =>
+					setStatus(`🔎 ${provider.label ?? provider.name} (${index + 1}/${total})`),
+			});
+
+			if (ctx.hasUI) ctx.ui.setStatus("browserwright", "");
+
+			if (!result.ok) {
+				throw new ToolFailure(renderFailure(result, query, { tool: "web_search", alternatives: searchNames }));
+			}
+
+			return {
+				content: [{ type: "text" as const, text: renderResults(result, query) }],
+				details: {
+					query,
+					provider: result.provider,
+					count: result.content?.results.length ?? 0,
+					features: {
+						answerBox: Boolean(result.content?.answerBox),
+						knowledgeGraph: Boolean(result.content?.knowledgeGraph),
+						peopleAlsoAsk: result.content?.peopleAlsoAsk?.length ?? 0,
+						relatedSearches: result.content?.relatedSearches?.length ?? 0,
+					},
+					attempts: result.attempts,
+				},
+			};
+		},
+	});
+
+	// ---- /browserwright ----------------------------------------------------
+
+	pi.registerCommand("browserwright", {
+		description:
+			"Inspect providers (/browserwright list) or probe one against real URLs (/browserwright probe <provider>)",
+		handler: async (args, ctx) => {
+			const [subcommand, target] = args.trim().split(/\s+/);
+
+			if (!subcommand || subcommand === "list") {
+				ctx.ui.notify(describeProviders(config, providers), "info");
+				return;
+			}
+
+			if (subcommand !== "probe") {
+				ctx.ui.notify(`Unknown subcommand "${subcommand}". Use "list" or "probe <provider>".`, "error");
+				return;
+			}
+
+			// Probing only makes sense for fetch providers — the cases are URLs.
+			const chosen = target ? [target] : fetchNames;
+			const unknown = chosen.filter((name) => !fetchNames.includes(name));
+			if (unknown.length > 0) {
+				ctx.ui.notify(`Not a probeable fetch provider: ${unknown.join(", ")}`, "error");
+				return;
+			}
+
+			// Probe hits real sites and opens tabs in the user's daily Chrome.
+			// It never runs without an explicit yes.
+			if (!ctx.hasUI) return;
+			const cases = loadProbeCases();
+			const ok = await ctx.ui.confirm(
+				"Run probe?",
+				`Hits ${cases.length} real URLs for: ${chosen.join(", ")}.\n\nThis opens tabs in your daily Chrome.`,
+			);
+			if (!ok) return;
+
+			for (const name of chosen) {
+				const provider = providers.get(name) as Provider;
+				ctx.ui.setStatus("browserwright", `🔬 probing ${name}…`);
+				const rows = await runProbe(provider, cases, {
+					config,
+					dir: EXTENSION_DIR,
+					onCase: (probeCase, index) =>
+						ctx.ui.setStatus("browserwright", `🔬 ${name} ${index + 1}/${cases.length}: ${probeCase.name}`),
+				});
+				const path = saveProbeEvidence(name, rows);
+				// deliverAs "steer" so the report renders as soon as the probe
+				// finishes. "nextTurn" would queue it invisibly until the user
+				// typed something else, which defeats the point of a report.
+				pi.sendMessage(
+					{
+						customType: "browserwright-probe",
+						content: `${formatProbeReport(name, rows)}\n\nEvidence written to ${path}`,
+						display: true,
+					},
+					{ deliverAs: "steer" },
+				);
+			}
+
+			ctx.ui.setStatus("browserwright", "");
+		},
+	});
+}
+
+function describeProviders(config: PiConfig, providers: Map<string, Provider>): string {
+	const lines: string[] = [];
+	for (const role of ["fetch", "search"] as Role[]) {
+		const scoped = providersForRole(providers, role);
+		lines.push(`${role}:`);
+		if (scoped.size === 0) {
+			lines.push("  (none declared)");
+			continue;
+		}
+		const order = config.order[role] ?? [];
+		const names = [...order.filter((n) => scoped.has(n)), ...[...scoped.keys()].filter((n) => !order.includes(n))];
+		for (const [index, name] of names.entries()) {
+			const provider = scoped.get(name);
+			if (!provider) continue;
+			const flags = [provider.kind, `returns=${provider.returns}`];
+			if (provider.enabled === false) flags.push("disabled");
+			if (provider.when) flags.push("conditional");
+			lines.push(`  ${index + 1}. ${name} (${flags.join(", ")})`);
+		}
+	}
+	return lines.join("\n");
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@browserwright/pi",
+  "version": "0.0.1",
+  "description": "web_fetch and web_search for the pi coding agent, driving the user's real browser through browserwright",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "browserwright",
+    "web-fetch",
+    "web-search",
+    "browser-automation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/broven/browserwright.git",
+    "directory": "pi-extension"
+  },
+  "homepage": "https://github.com/broven/browserwright/tree/main/pi-extension#readme",
+  "bugs": {
+    "url": "https://github.com/broven/browserwright/issues"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "verify.ts",
+    "probe-run.ts",
+    "core/",
+    "!core/*.test.ts",
+    "providers/",
+    "config.json",
+    "probe-cases.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "test": "node --test 'core/*.test.ts'"
+  }
+}

package/probe-cases.json

@@ -0,0 +1,22 @@
+[
+  { "name": "article", "url": "https://en.wikipedia.org/wiki/Markdown", "expose": "normal long article" },
+  { "name": "spa-shell", "url": "https://web.telegram.org/", "expose": "client-rendered shell, no server HTML" },
+  { "name": "bot-wall", "url": "https://www.g2.com/", "expose": "bot challenge / interstitial" },
+  { "name": "login-wall", "url": "https://x.com/elonmusk", "expose": "needs the user's session cookies" },
+  { "name": "not-found", "url": "https://example.com/definitely-not-here", "expose": "404 handling" },
+  {
+    "name": "huge",
+    "url": "https://en.wikipedia.org/wiki/List_of_Latin_phrases_(full)",
+    "expose": "page far past the 50KB truncation limit"
+  },
+  {
+    "name": "pdf",
+    "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
+    "expose": "non-HTML content type"
+  },
+  {
+    "name": "localhost",
+    "url": "http://localhost:3000/",
+    "expose": "local dev server — remote providers cannot reach it, curl and browserwright can"
+  }
+]

package/probe-run.ts

@@ -0,0 +1,34 @@
+/**
+ * Headless probe runner — the same code path as `/webfetch probe`, without pi's
+ * confirmation dialog. Use it when you want the evidence matrix captured to a
+ * file rather than rendered into a session.
+ *
+ *   node probe-run.ts                 # every provider
+ *   node probe-run.ts jina curl       # only these
+ */
+
+import { EXTENSION_DIR, loadConfig, loadProviders } from "./core/config.ts";
+import { formatProbeReport, loadProbeCases, runProbe, saveProbeEvidence } from "./core/probe.ts";
+
+const config = loadConfig();
+const providers = loadProviders();
+const cases = loadProbeCases();
+const requested = process.argv.slice(2);
+const names = requested.length > 0 ? requested : [...providers.keys()];
+
+console.log(`probing ${names.join(", ")} against ${cases.length} real URLs\n`);
+
+for (const name of names) {
+	const provider = providers.get(name);
+	if (!provider) {
+		console.log(`unknown provider: ${name}\n`);
+		continue;
+	}
+	const rows = await runProbe(provider, cases, {
+		config,
+		dir: EXTENSION_DIR,
+		onCase: (probeCase, index) => console.error(`  [${name}] ${index + 1}/${cases.length} ${probeCase.name}`),
+	});
+	console.log(formatProbeReport(name, rows));
+	console.log(`evidence: ${saveProbeEvidence(name, rows)}\n`);
+}

package/providers/browserwright-search.json

@@ -0,0 +1,56 @@
+{
+  "name": "browserwright-search",
+  "label": "Google via your Chrome",
+  "role": "search",
+  "kind": "module",
+  "module": "./providers/browserwright-search.ts",
+  "returns": "results",
+  "timeoutMs": 120000,
+  "options": {
+    "limit": 10,
+    "searchUrl": "https://www.google.com/search?q={queryEncoded}&hl=en&num={limit}"
+  },
+  "failWhen": {
+    "matches": [],
+    "minResults": 1
+  },
+  "_note": [
+    "kind: \"module\" rather than \"command\" because a search is a lifecycle, not",
+    "one shot at a subprocess: mint a session, navigate, extract, retry once on an",
+    "executor death, tear down in a finally. See the header of the .ts runner for",
+    "the six measured executor behaviours it is designed around.",
+    "timeoutMs is 120s, well above the measured cost. Google through a real",
+    "browser took 10-21s warm on 2026-08-09 (page.goto's own settle wait accounts",
+    "for ~2.5s of that; the rest is Google's page never going network-quiet).",
+    "Slow is accepted here — this rung exists for correctness and login state, not",
+    "for throughput.",
+    "failWhen.matches is [] because the extraction returns rows, not prose: the",
+    "default needles ('captcha', 'just a moment') would be matched against result",
+    "titles and snippets, where they appear legitimately in any query about them.",
+    "The runner detects real interstitials from the page HTML instead and reports",
+    "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.",
+    "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-",
+    "rendered for organic rows, but the AI Overview body is NOT in the initial HTML",
+    "at all — it streams in afterwards. That is why extraction runs against the",
+    "live DOM and not the document response. browserwright's page.goto already",
+    "waits long enough: both organic and the AI Overview were present 0.02s after",
+    "it returned.",
+    "Each extractor is independently guarded, because the realistic failure is one",
+    "restyled container taking the whole search down with it. Anchors used, worst",
+    "to best: AI Overview has no stable hook at all, so it anchors on the",
+    "accessible heading and walks up; the knowledge panel uses data-attrid, which",
+    "is semantic markup rather than a styling class and is the sturdiest hook on",
+    "the page; PAA uses data-q (which also carries the query itself, so that is",
+    "filtered); related searches are scoped to #botstuff because the same href",
+    "pattern at the top of the page is Google's own tab bar.",
+    "Known noise that is cleaned: snippets end with the 'Read more' expander text,",
+    "dates are prefixed onto snippets with either an em dash or a middot, the AI",
+    "Overview splices citation counters ('+2') into its prose, and pagination",
+    "renders 'Next' through the related-searches selector."
+  ]
+}