pi-agent-browser-native 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.3 - 2026-04-12
+
+### Changed
+- when `BRAVE_API_KEY` is present and non-empty, the extension now tells agents to prefer the Brave Search API via `bash`/`curl` for URL discovery and then open the chosen destination with `agent_browser` instead of driving a search engine results page in the browser
+- when `BRAVE_API_KEY` is absent, the extension behavior remains unchanged
+- added a small runtime helper and unit coverage for the `BRAVE_API_KEY` gate so the change stays explicit and minimal
+
+## 0.1.2 - 2026-04-11
+
+### Changed
+- renamed the public GitHub repository to `pi-agent-browser-native` so the repo name, npm package name, install docs, and package metadata all align
+- updated package metadata and install guidance to use the new GitHub source path `https://github.com/fitchmultz/pi-agent-browser-native`
+- switched the local global pi install from the repo checkout path to the published npm package `pi-agent-browser-native`
+
 ## 0.1.1 - 2026-04-11
 
 ### Changed

package/README.md

@@ -1,4 +1,4 @@
-# pi-agent-browser
+# pi-agent-browser-native
 
 Native `pi` integration for [`agent-browser`](https://agent-browser.dev/).
 
@@ -66,13 +66,13 @@ pi -e npm:pi-agent-browser-native
 For the source install path, prefer the repository URL:
 
 ```bash
-pi install https://github.com/fitchmultz/pi-agent-browser
+pi install https://github.com/fitchmultz/pi-agent-browser-native
 ```
 
 To try the GitHub source without installing it permanently:
 
 ```bash
-pi -e https://github.com/fitchmultz/pi-agent-browser
+pi -e https://github.com/fitchmultz/pi-agent-browser-native
 ```
 
 ### Current practical local-checkout flow
@@ -80,13 +80,13 @@ pi -e https://github.com/fitchmultz/pi-agent-browser
 Until you are using a published package release, install from a checkout:
 
 ```bash
-pi install /absolute/path/to/pi-agent-browser
+pi install /absolute/path/to/pi-agent-browser-native
 ```
 
 Or try it for one session only:
 
 ```bash
-pi -e /absolute/path/to/pi-agent-browser
+pi -e /absolute/path/to/pi-agent-browser-native
 ```
 
 The native tool exposed to the agent is named `agent_browser`.

package/docs/ARCHITECTURE.md

@@ -104,7 +104,7 @@ This keeps the product centered on native tool usage instead of auxiliary skill
 
 ## Responsibility split
 
-### `pi-agent-browser` owns
+### `pi-agent-browser-native` owns
 
 - tool registration and schema
 - subprocess execution and JSON parsing

package/docs/RELEASE.md

@@ -8,7 +8,7 @@ Related docs:
 
 ## Purpose
 
-Provide one concrete maintainer workflow for validating repo state, package contents, and install guidance before publishing `pi-agent-browser`.
+Provide one concrete maintainer workflow for validating repo state, package contents, and install guidance before publishing `pi-agent-browser-native`.
 
 ## Pre-release checks
 

package/docs/REQUIREMENTS.md

@@ -8,7 +8,7 @@ Related docs:
 
 ## Purpose
 
-Define the product requirements and constraints for `pi-agent-browser`.
+Define the product requirements and constraints for `pi-agent-browser-native`.
 
 ## Product requirements
 
@@ -45,7 +45,7 @@ Define the product requirements and constraints for `pi-agent-browser`.
 
 - Prioritize the package install path first.
 - User-facing install docs should lead with `pi install npm:pi-agent-browser-native` and `pi -e npm:pi-agent-browser-native` once releases exist.
-- User-facing install docs should also include the GitHub source path `pi install https://github.com/fitchmultz/pi-agent-browser`.
+- User-facing install docs should also include the GitHub source path `pi install https://github.com/fitchmultz/pi-agent-browser-native`.
 - Keep the current local-checkout path documented as the practical pre-release and development flow.
 - Most users will install this extension globally rather than as a project-local extension.
 - Repo-local `.pi/` wiring is for development convenience only and should not drive the product design.

package/extensions/agent-browser/index.ts

@@ -19,6 +19,7 @@ import {
 	createEphemeralSessionSeed,
 	createImplicitSessionName,
 	getLatestUserPrompt,
+	hasUsableBraveApiKey,
 	validateToolArgs,
 } from "./lib/runtime.js";
 import { cleanupSecureTempArtifacts } from "./lib/temp.js";
@@ -78,8 +79,14 @@ function buildInspectionDeflectionMessage(): string {
 	].join("\n");
 }
 
+function buildBraveSearchGuidance(hasBraveApiKey: boolean): string {
+	if (!hasBraveApiKey) return "";
+	return "\n- A non-empty `BRAVE_API_KEY` is available in the current environment. For web search or URL discovery, prefer the Brave Search API via `bash`/`curl` to find the destination URL, then open that URL with `agent_browser` instead of using browser automation to drive Google or another search engine results page. If the Brave request fails, fall back to the normal workflow.";
+}
+
 export default function agentBrowserExtension(pi: ExtensionAPI) {
 	const ephemeralSessionSeed = createEphemeralSessionSeed();
+	const braveSearchGuidance = buildBraveSearchGuidance(hasUsableBraveApiKey());
 	let implicitSessionActive = false;
 	let implicitSessionName = createImplicitSessionName(undefined, process.cwd(), ephemeralSessionSeed);
 	let implicitSessionCwd = process.cwd();
@@ -112,7 +119,8 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 		return {
 			systemPrompt:
 				event.systemPrompt +
-				"\n\nProject rule: when browser automation is needed, prefer the native `agent_browser` tool. Do not run direct `agent-browser` bash commands unless the user explicitly asks for a bash-oriented workflow or browser-integration debugging.\n\nBrowser operating playbook:\n- Standard workflow: open the page, then snapshot -i, then interact via refs, then re-snapshot after navigation or major DOM changes.\n- For user-specific or authenticated content like feeds, inboxes, dashboards, and accounts, start with an authenticated browser strategy instead of public browsing. Prefer `--profile Default` on the first browser call and let the current implicit session carry continuity. Use `--auto-connect` only if profile-based reuse is unavailable or the task is specifically about attaching to a running debug-enabled browser.\n- Do not invent fixed explicit session names for routine tasks. Use the implicit session unless you truly need multiple isolated browser sessions in the same conversation.\n- When using startup-scoped flags like `--profile`, `--session-name`, or `--cdp`, put them on the first command for that session. If you intentionally use an explicit `--session`, keep using that same explicit session for follow-ups.\n- If a session lands on the wrong page or tab, an interaction changes origin unexpectedly, or an `open` call returns blocked, blank, or otherwise unexpected results, use `tab list`, `tab <n>`, and `snapshot -i` to recover state before retrying different URLs or fallback strategies. Only use `wait` with an explicit argument like milliseconds, `--load`, `--url`, `--fn`, or `--text`.\n- For feed, timeline, or inbox reading tasks, focus on the main timeline/list region and read the first item there rather than unrelated composer or sidebar content.\n- For read-only browsing tasks, prefer extracting the answer from the current snapshot, structured ref labels, or `eval --stdin` on the current page before navigating away. Only click into media viewers, detail routes, or new pages when the current view does not contain the needed information.\n- When using `eval --stdin`, scope checks and actions to the target element or route whenever possible instead of relying on broad page-wide text heuristics.\n- When using `eval --stdin` for extraction, return the value you want instead of relying on `console.log` as the primary result channel.\n- Do not use `agent_browser --help` for normal browsing tasks.",
+				"\n\nProject rule: when browser automation is needed, prefer the native `agent_browser` tool. Do not run direct `agent-browser` bash commands unless the user explicitly asks for a bash-oriented workflow or browser-integration debugging.\n\nBrowser operating playbook:\n- Standard workflow: open the page, then snapshot -i, then interact via refs, then re-snapshot after navigation or major DOM changes.\n- For user-specific or authenticated content like feeds, inboxes, dashboards, and accounts, start with an authenticated browser strategy instead of public browsing. Prefer `--profile Default` on the first browser call and let the current implicit session carry continuity. Use `--auto-connect` only if profile-based reuse is unavailable or the task is specifically about attaching to a running debug-enabled browser.\n- Do not invent fixed explicit session names for routine tasks. Use the implicit session unless you truly need multiple isolated browser sessions in the same conversation.\n- When using startup-scoped flags like `--profile`, `--session-name`, or `--cdp`, put them on the first command for that session. If you intentionally use an explicit `--session`, keep using that same explicit session for follow-ups.\n- If a session lands on the wrong page or tab, an interaction changes origin unexpectedly, or an `open` call returns blocked, blank, or otherwise unexpected results, use `tab list`, `tab <n>`, and `snapshot -i` to recover state before retrying different URLs or fallback strategies. Only use `wait` with an explicit argument like milliseconds, `--load`, `--url`, `--fn`, or `--text`.\n- For feed, timeline, or inbox reading tasks, focus on the main timeline/list region and read the first item there rather than unrelated composer or sidebar content.\n- For read-only browsing tasks, prefer extracting the answer from the current snapshot, structured ref labels, or `eval --stdin` on the current page before navigating away. Only click into media viewers, detail routes, or new pages when the current view does not contain the needed information.\n- When using `eval --stdin`, scope checks and actions to the target element or route whenever possible instead of relying on broad page-wide text heuristics.\n- When using `eval --stdin` for extraction, return the value you want instead of relying on `console.log` as the primary result channel.\n- Do not use `agent_browser --help` for normal browsing tasks." +
+				braveSearchGuidance,
 		};
 	});
 
@@ -141,6 +149,11 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 		promptGuidelines: [
 			"Use this tool whenever the task requires a real browser or live web content.",
 			"Standard workflow: open the page, snapshot -i, interact using refs, and re-snapshot after navigation or major DOM changes.",
+			...(braveSearchGuidance
+				? [
+					"When a non-empty BRAVE_API_KEY is available in the current environment, prefer the Brave Search API via bash/curl to discover specific destination URLs, then open the chosen URL with agent_browser instead of browsing a search engine results page just to find the target.",
+				  ]
+				: []),
 			"For authenticated or user-specific content like feeds, inboxes, dashboards, and accounts, prefer --profile Default on the first browser call and let the implicit session carry continuity. Use --auto-connect only if profile-based reuse is unavailable or the task is specifically about attaching to a running debug-enabled browser.",
 			"Do not invent fixed explicit session names for routine tasks. Use the implicit session unless you truly need multiple isolated browser sessions in the same conversation.",
 			"When using --profile, --session-name, or --cdp, put them on the first command for that session. If you intentionally use an explicit --session, keep using that same explicit session for follow-ups.",

package/extensions/agent-browser/lib/runtime.ts

@@ -10,6 +10,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { basename } from "node:path";
 
 const STARTUP_SCOPED_FLAGS = ["--cdp", "--profile", "--session-name"] as const;
+const BRAVE_API_KEY_ENV = "BRAVE_API_KEY";
 const INSPECTION_ALLOW_PATTERNS = [
 	/\bagent[_ -]?browser\s+--(?:help|version)\b/i,
 	/\bagent[_ -]?browser\b.*\b(?:help|version|docs?|documentation|tool contract|tool guidance|tool description)\b/i,
@@ -77,6 +78,10 @@ export interface PromptPolicy {
 	allowLegacyAgentBrowserBash: boolean;
 }
 
+export function hasUsableBraveApiKey(apiKey: string | null | undefined = process.env[BRAVE_API_KEY_ENV]): boolean {
+	return typeof apiKey === "string" && apiKey.trim().length > 0;
+}
+
 export function createEphemeralSessionSeed(): string {
 	return randomUUID();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Native pi integration for agent-browser",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
@@ -15,11 +15,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/fitchmultz/pi-agent-browser.git"
+    "url": "git+https://github.com/fitchmultz/pi-agent-browser-native.git"
   },
-  "homepage": "https://github.com/fitchmultz/pi-agent-browser#readme",
+  "homepage": "https://github.com/fitchmultz/pi-agent-browser-native#readme",
   "bugs": {
-    "url": "https://github.com/fitchmultz/pi-agent-browser/issues"
+    "url": "https://github.com/fitchmultz/pi-agent-browser-native/issues"
   },
   "engines": {
     "node": ">=20.6.0"