pi-agent-browser-native 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.4 - 2026-04-12
+
+### Changed
+- removed the tracked repo-local `.pi/extensions/agent-browser.ts` autoload shim because it conflicts with the globally installed package and blocks `pi` startup from this repository root
+- local checkout validation now uses explicit CLI loading with `pi --no-extensions -e .` instead of repo-local `.pi/extensions/` auto-discovery
+- aligned the package description and keywords with the GitHub repository metadata used for your other public `pi` extensions
+
+## 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

package/README.md

@@ -6,7 +6,7 @@ Native `pi` integration for [`agent-browser`](https://agent-browser.dev/).
 
 Early working scaffold.
 
-The package scaffold, native `agent_browser` tool, local typecheck/test setup, tracked repo-local development entrypoint, and release/package verification workflow are in place.
+The package scaffold, native `agent_browser` tool, local typecheck/test setup, and release/package verification workflow are in place.
 
 ## Goal
 
@@ -77,27 +77,28 @@ pi -e https://github.com/fitchmultz/pi-agent-browser-native
 
 ### Current practical local-checkout flow
 
-Until you are using a published package release, install from a checkout:
+Until you are using a published package release, prefer an explicit checkout-only run instead of installing the checkout into your normal `pi` package set:
 
 ```bash
-pi install /absolute/path/to/pi-agent-browser-native
+pi --no-extensions -e /absolute/path/to/pi-agent-browser-native
 ```
 
-Or try it for one session only:
-
-```bash
-pi -e /absolute/path/to/pi-agent-browser-native
-```
+This avoids duplicate `agent_browser` registrations if you also have the published package installed globally.
 
 The native tool exposed to the agent is named `agent_browser`.
 
 ## Local development
 
-This repository now tracks `.pi/extensions/agent-browser.ts` as a thin development entrypoint that re-exports the real extension from `extensions/agent-browser/index.ts`. That keeps repo-root `pi` launches working without changing the published package layout.
+Do not track or rely on a repo-local `.pi/extensions/agent-browser.ts` autoload shim for this package. When the package is also installed globally, that creates a duplicate `agent_browser` registration and blocks `pi` startup from this working directory.
 
 1. Install `agent-browser` separately via the upstream project.
 2. Run `npm install`.
-3. Launch `pi` from this repository root.
+3. Launch `pi` from this repository root with only the checkout extension loaded:
+
+```bash
+pi --no-extensions -e .
+```
+
 4. Prompt the agent to use `agent_browser`.
 
 Example prompt:

package/docs/ARCHITECTURE.md

@@ -9,7 +9,7 @@ Related docs:
 
 Build this as a **thin `pi` extension/package** that exposes `agent-browser` as one native tool while keeping upstream `agent-browser` as the source of truth.
 
-The package install path is the primary product path. Repo-local `.pi/` wiring exists only as a thin tracked development shim, while package-manifest behavior and packaged contents matter more.
+The package install path is the primary product path. Local checkout development should use explicit CLI loading, while package-manifest behavior and packaged contents matter more.
 
 ## Chosen shape
 
@@ -42,15 +42,15 @@ That means:
 - no manual user orchestration as the main workflow
 - any future slash commands should be minimal and secondary
 
-### Package layout versus repo-local development
+### Package layout versus local checkout development
 
 The published package should load from the `pi` manifest in `package.json`.
 
-Repo-local development should use one thin tracked shim at `.pi/extensions/agent-browser.ts` that re-exports `extensions/agent-browser/index.ts`.
+Local checkout development should use explicit CLI loading such as `pi --no-extensions -e .` from the repository root instead of repo-local `.pi/extensions/` auto-discovery.
 
 Why:
-- keeps repo-root `pi` launches working during development
-- avoids making local `.pi/` wiring the product contract
+- avoids duplicate `agent_browser` registrations when the package is also installed globally
+- keeps the product contract centered on the package manifest instead of repo-local autoload wiring
 - keeps the published tarball focused on the package manifest, extension code, canonical docs, and license
 
 The published package should exclude agent-only and superseded repo materials such as `AGENTS.md`, `docs/v1-tool-contract.md`, `docs/native-integration-design.md`, and other internal planning notes.

package/docs/RELEASE.md

@@ -28,7 +28,7 @@ npm run verify:release
 
 `npm run verify:package` confirms that:
 
-- the tracked repo-local development entrypoint exists at `.pi/extensions/agent-browser.ts`
+- no repo-local `.pi/extensions/agent-browser.ts` autoload shim is present
 - `LICENSE` exists in the repo and the packed tarball
 - canonical published docs are present
 - extension source files are present
@@ -51,11 +51,11 @@ node scripts/verify-package.mjs --list-files
 
 ## Local development validation
 
-Before publishing, also validate the repo-local development path:
+Before publishing, also validate the explicit local-checkout path:
 
 1. Install `agent-browser` separately.
-2. Launch `pi` from this repository root.
-3. Confirm the tracked `.pi/extensions/agent-browser.ts` shim loads the current extension code.
+2. Launch `pi --no-extensions -e .` from this repository root.
+3. Confirm the checkout extension loads from `extensions/agent-browser/index.ts`.
 4. Run a smoke prompt that exercises `agent_browser`.
 
 Example prompt:
@@ -81,6 +81,6 @@ Before publishing:
 
 - update `CHANGELOG.md`
 - confirm README install guidance still leads with the package-first flow
-- confirm local-checkout instructions still work for pre-release validation
+- confirm the explicit local-checkout instructions still work for pre-release validation
 - rerun `npm run verify:release`
 - publish only after the tarball contents match expectations

package/docs/REQUIREMENTS.md

@@ -48,8 +48,8 @@ Define the product requirements and constraints for `pi-agent-browser-native`.
 - 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.
-- The tracked repo-local development entrypoint should stay a thin re-export, not a second implementation path.
+- Local checkout development should use explicit CLI loading such as `pi --no-extensions -e .` or `pi --no-extensions -e /absolute/path/to/pi-agent-browser-native`.
+- Do **not** rely on repo-local `.pi/extensions/` auto-discovery for this package, because it conflicts with the global installed-package path.
 
 ### Native-tool preference
 
@@ -70,7 +70,7 @@ Define the product requirements and constraints for `pi-agent-browser-native`.
 ### Testing guidance
 
 - The primary confidence path is a real `pi` session driven in `tmux`.
-- Launch `pi` from the repository root for local development so the tracked `.pi` development entrypoint loads.
+- For local checkout validation, launch `pi --no-extensions -e .` from the repository root so only the checkout copy loads.
 - Prefer full `pi` restart over `/reload` when validating extension changes.
 - Use `/resume` when needed after restart.
 - Keep testing broader than a single smoke site like `example.com`.

package/extensions/agent-browser/index.ts

@@ -2,7 +2,7 @@
  * Purpose: Register the native agent_browser tool for pi so agents can invoke agent-browser without going through bash.
  * Responsibilities: Define the tool schema, inject thin wrapper behavior around the upstream CLI, manage implicit session convenience, and return pi-friendly content/details.
  * Scope: Native tool registration and orchestration only; the wrapper intentionally stays close to the upstream agent-browser CLI.
- * Usage: Loaded by pi through the package manifest or the local `.pi/extensions/agent-browser.ts` development entrypoint.
+ * Usage: Loaded by pi through the package manifest in this package, or explicitly via `pi --no-extensions -e .` during local checkout development.
  * Invariants/Assumptions: agent-browser is installed separately on PATH, the wrapper targets the current locally installed upstream version only, and no backward-compatibility shims are provided.
  */
 
@@ -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,7 +1,7 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.1.2",
-  "description": "Native pi integration for agent-browser",
+  "version": "0.1.4",
+  "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
   "keywords": [
@@ -10,7 +10,9 @@
     "pi-extension",
     "extension",
     "agent-browser",
-    "browser-automation"
+    "browser-automation",
+    "typescript",
+    "npm-package"
   ],
   "license": "MIT",
   "repository": {