@browserwright/pi 0.12.0 → 0.14.0

package/README.md

@@ -4,8 +4,8 @@ Two tools for [pi](https://github.com/badlogic/pi-mono), backed by **declarative
 providers** that drive [browserwright](https://github.com/broven/browserwright):
 
 ```
-web_fetch(url, provider?)      → the page as Markdown
-web_search(query, provider?)   → ranked links + the SERP features Google showed
+bw_web_fetch(url, provider?)   → the page as Markdown
+bw_web_search(query, provider?) → ranked links + the SERP features Google showed
 ```
 
 Both run through the user's **own Chrome**, so they see what the user sees —
@@ -29,14 +29,18 @@ browserwright version check      # expect drift=equal
 The npm package and the Python package are cut from the same git tag, so their
 versions always match. Install them together.
 
+The names are `bw_`-prefixed rather than bare `web_fetch`/`web_search` because
+providers reserve generic tool names: grok rejects a custom function named
+`web_search` with a 400, so the prefix keeps every provider safe.
+
 ## The two tools
 
-`web_search` returns **links, never page bodies**. The model then calls
-`web_fetch` on the one or two worth reading. That split is deliberate: fetching
+`bw_web_search` returns **links, never page bodies**. The model then calls
+`bw_web_fetch` on the one or two worth reading. That split is deliberate: fetching
 all ten hits costs ~30 seconds and 50KB+ of context to answer a question that
 usually needs one of them.
 
-### What `web_search` returns
+### What `bw_web_search` returns
 
 | field | contents |
 |-------|----------|
@@ -106,11 +110,11 @@ This package ships **only the browserwright rungs**. There is one per tool:
 
 | tool | provider | kind |
 |------|----------|------|
-| `web_fetch` | `browserwright` | `command` — `browserwright markdown <url>` |
-| `web_search` | `browserwright-search` | `module` — a session lifecycle in TS |
+| `bw_web_fetch` | `browserwright` | `command` — `browserwright markdown <url>` |
+| `bw_web_search` | `browserwright-search` | `module` — a session lifecycle in TS |
 
 That is a real trade-off, and it points the wrong way for casual fetches: every
-`web_fetch` opens a tab in the daily browser and takes ~4-7s, where a hosted
+`bw_web_fetch` opens a tab in the daily browser and takes ~4-7s, where a hosted
 reader API answers in ~1s without touching Chrome. What you get for it is login
 state and full JS rendering, which no anonymous rung has.
 
@@ -247,11 +251,14 @@ worth repeating.
 ## Probe: rules from evidence, not guesses
 
 ```
-/browserwright list             # show both chains
-/browserwright probe            # every fetch provider
-/browserwright probe browserwright
+/bw list             # show both chains
+/bw probe            # every fetch provider
+/bw probe browserwright
 ```
 
+The slash command is `/bw` (not `/browserwright`) so it cannot be confused with
+pi's `browserwright` skill, which pi exposes as `/skill:browserwright`.
+
 Runs a provider against the real URLs in `probe-cases.json` — a normal article,
 a client-rendered shell, a bot wall, a login wall, a 404, a page past the
 truncation limit, a PDF, and localhost — then prints what came back and writes
@@ -304,7 +311,7 @@ the `tool_result` event see `isError: false`. So a chain failure here throws.
   attacker, and blocking private addresses would remove localhost fetching,
   which is a real workflow. The requested URL is printed so internal fetches
   stay visible in the transcript.
-- **No body fetching inside `web_search`.** See the two-tool split above.
+- **No body fetching inside `bw_web_search`.** See the two-tool split above.
 
 ## License
 

package/core/chain.ts

@@ -8,7 +8,7 @@
  *
  * The engine is payload-agnostic: it never looks inside `content`, it only asks
  * the caller-supplied `inspect` to reduce it to text plus an item count. That is
- * what lets one chain serve `web_fetch` (a Markdown blob) and `web_search`
+ * what lets one chain serve `bw_web_fetch` (a Markdown blob) and `bw_web_search`
  * (a list of results).
  */
 

package/core/config.ts

@@ -3,8 +3,8 @@
  *
  * Provider declarations are plain JSON files in providers/. Adding a provider
  * means dropping one file in there — no code change, no registration table.
- * A declaration that names no `role` serves `web_fetch`, which is what the
- * majority of reader APIs are.
+ * A declaration that names no `role` serves the fetch role (`bw_web_fetch`),
+ * which is what the majority of reader APIs are.
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
@@ -30,7 +30,7 @@ const DEFAULT_CONFIG: PiConfig = {
 	// The default line of defence. minChars stays 0 on purpose: a false positive
 	// escalates to a rung that opens a tab in the user's real Chrome, so
 	// over-eager rejection interrupts them. Per-provider thresholds are meant to
-	// come from `/browserwright probe` evidence, not from guesses.
+	// come from `/bw probe` evidence, not from guesses.
 	defaultFailWhen: {
 		minChars: 0,
 		minResults: 0,

package/core/exec-module.ts

@@ -25,7 +25,7 @@ import type { ModuleContext, ModuleProvider, ModuleRunner, ProviderOutcome, Role
 /**
  * Completed and in-flight loads, keyed by spec.
  *
- * This stores the PROMISE, not the resolved runner, on purpose. Two web_search
+ * This stores the PROMISE, not the resolved runner, on purpose. Two bw_web_search
  * calls fired in the same turn both miss a value cache and both import; under
  * pi's jiti runtime that race is not merely wasteful but wrong — the second
  * caller can observe a half-initialized module record and fail the load (see

package/core/format.ts

@@ -117,7 +117,7 @@ const ANSWER_BOX_CAP = 1200;
 
 /**
  * The search success path. Links plus whatever SERP features the query
- * triggered — but never page bodies: `web_fetch` already does that, and the
+ * triggered — but never page bodies: `bw_web_fetch` already does that, and the
  * model is in a better position to decide which two of ten links are worth the
  * tokens.
  *
@@ -171,7 +171,7 @@ export function renderResults(result: ChainResult<SearchPayload>, query: string)
 		out.push("## Related searches", payload.relatedSearches.join(" · "), "");
 	}
 
-	out.push("Use web_fetch on a URL above to read it.");
+	out.push("Use bw_web_fetch on a URL above to read it.");
 	return out.join("\n");
 }
 

package/index.ts

@@ -1,7 +1,11 @@
 /**
- * @browserwright/pi — `web_fetch` and `web_search` for pi, backed by
+ * @browserwright/pi — `bw_web_fetch` and `bw_web_search` for pi, backed by
  * declarative providers that drive browserwright.
  *
+ * Tool names are `bw_`-prefixed (not bare `web_fetch`/`web_search`) because
+ * providers reserve generic tool names: grok rejects a custom function named
+ * `web_search` with a 400. The prefix keeps every provider safe.
+ *
  * 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
@@ -48,10 +52,10 @@ export default function (pi: ExtensionAPI) {
 			onUpdate?.({ content: [{ type: "text", text: `*${text}*` }] });
 		};
 
-	// ---- web_fetch ---------------------------------------------------------
+	// ---- bw_web_fetch ------------------------------------------------------
 
 	pi.registerTool({
-		name: "web_fetch",
+		name: "bw_web_fetch",
 		label: "Fetch Web Page",
 		description:
 			"Fetch a URL and return its content as Markdown. " +
@@ -60,7 +64,7 @@ export default function (pi: ExtensionAPI) {
 			"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 " +
+			"Prefer `bw_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({
@@ -92,7 +96,7 @@ export default function (pi: ExtensionAPI) {
 			if (ctx.hasUI) ctx.ui.setStatus("browserwright", "");
 
 			if (!result.ok) {
-				throw new ToolFailure(renderFailure(result, url, { tool: "web_fetch", alternatives: fetchNames }));
+				throw new ToolFailure(renderFailure(result, url, { tool: "bw_web_fetch", alternatives: fetchNames }));
 			}
 
 			return {
@@ -113,20 +117,20 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	// ---- web_search --------------------------------------------------------
+	// ---- bw_web_search -----------------------------------------------------
 
 	pi.registerTool({
-		name: "web_search",
+		name: "bw_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.",
+			"call bw_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 " +
+			"`bw_web_search` returns links, not page contents. After searching, call `bw_web_fetch` on the one or two " +
 				"results actually worth reading rather than fetching all of them.",
 		],
 		parameters: Type.Object({
@@ -141,7 +145,7 @@ export default function (pi: ExtensionAPI) {
 		}),
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			const query = params.query.trim();
-			if (!query) throw new ToolFailure("web_search needs a non-empty query");
+			if (!query) throw new ToolFailure("bw_web_search needs a non-empty query");
 			const setStatus = statusReporter(ctx, onUpdate);
 
 			const result = await runChain<SearchPayload>({
@@ -167,7 +171,7 @@ export default function (pi: ExtensionAPI) {
 			if (ctx.hasUI) ctx.ui.setStatus("browserwright", "");
 
 			if (!result.ok) {
-				throw new ToolFailure(renderFailure(result, query, { tool: "web_search", alternatives: searchNames }));
+				throw new ToolFailure(renderFailure(result, query, { tool: "bw_web_search", alternatives: searchNames }));
 			}
 
 			return {
@@ -188,11 +192,13 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	// ---- /browserwright ----------------------------------------------------
+	// ---- /bw ---------------------------------------------------------------
+	// Named `/bw` (not `/browserwright`) so it cannot be confused with the
+	// `browserwright` skill, which pi exposes as `/skill:browserwright`.
 
-	pi.registerCommand("browserwright", {
+	pi.registerCommand("bw", {
 		description:
-			"Inspect providers (/browserwright list) or probe one against real URLs (/browserwright probe <provider>)",
+			"Inspect providers (/bw list) or probe one against real URLs (/bw probe <provider>)",
 		handler: async (args, ctx) => {
 			const [subcommand, target] = args.trim().split(/\s+/);
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@browserwright/pi",
-  "version": "0.12.0",
-  "description": "web_fetch and web_search for the pi coding agent, driving the user's real browser through browserwright",
+  "version": "0.14.0",
+  "description": "bw_web_fetch and bw_web_search for the pi coding agent, driving the user's real browser through browserwright",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [

package/probe-run.ts

@@ -1,5 +1,5 @@
 /**
- * Headless probe runner — the same code path as `/webfetch probe`, without pi's
+ * Headless probe runner — the same code path as `/bw probe`, without pi's
  * confirmation dialog. Use it when you want the evidence matrix captured to a
  * file rather than rendered into a session.
  *

package/providers/browserwright-search.ts

@@ -1,5 +1,5 @@
 /**
- * The `web_search` rung: drive a real search engine in the user's own Chrome.
+ * The `bw_web_search` rung: drive a real search engine in the user's own Chrome.
  *
  * This is a `kind: "module"` provider rather than a `kind: "command"` one
  * because a search is not one shot at a subprocess. It is: mint a session,

package/verify.ts

@@ -41,7 +41,7 @@ if (url !== undefined) {
 	console.log(
 		chained.ok
 			? `${renderSuccess(chained, { url, maxBytes: config.maxBytes, maxLines: config.maxLines }).slice(0, 600)}\n`
-			: `${renderFailure(chained, url, { tool: "web_fetch", alternatives: [...providersForRole(providers, "fetch").keys()] })}\n`,
+			: `${renderFailure(chained, url, { tool: "bw_web_fetch", alternatives: [...providersForRole(providers, "fetch").keys()] })}\n`,
 	);
 
 	console.log("── each fetch provider in isolation ──");
@@ -84,7 +84,7 @@ if (query !== undefined) {
 		searched.ok
 			? renderResults(searched, query)
 			: renderFailure(searched, query, {
-					tool: "web_search",
+					tool: "bw_web_search",
 					alternatives: [...providersForRole(providers, "search").keys()],
 				}),
 	);