pi-agent-browser-native 0.2.38 → 0.2.40

package/docs/TOOL_CONTRACT.md

@@ -10,9 +10,10 @@ Related docs:
 
 ## V1 tool
 
-V1 should expose one primary native tool:
+V1 exposes one primary native browser tool and one optional companion search tool:
 
 - `agent_browser`
+- `agent_browser_web_search` when a Brave Search credential source is configured or resolvable
 
 ## Why this tool shape
 
@@ -33,6 +34,49 @@ The native command reference in `docs/COMMAND_REFERENCE.md` is driven by the sam
 
 Agent-facing efficiency claims are measured with `npm run benchmark:agent-browser` or `npm run verify -- benchmark`. The benchmark is deterministic and does not launch a browser; it tracks representative workflow success, tool calls, model-visible output size, stale-ref failures and recoveries, artifact success, failure-category coverage, and elapsed-time estimates so future abstractions can prove they reduce agent work before replacing raw tool use.
 
+## Optional companion web search
+
+`agent_browser_web_search` is a separate custom tool, not an `agent_browser` input mode. It is registered only when the extension can see a configured Brave Search credential source from `~/.pi/config/pi-agent-browser-native/config.json`, `.pi/config/pi-agent-browser-native/config.json`, `PI_AGENT_BROWSER_CONFIG`, or the `BRAVE_API_KEY` environment fallback. Command credential sources such as `"!op read 'op://Private/Brave Search/API Key'"` are allowed only from trusted global or explicit-override config; they make the tool available without running the command at startup, and the key is resolved when the tool executes. Project-local config may use inert exact `$ENV_VAR` / `${ENV_VAR}` references only; interpolation literals and malformed `$` values are rejected.
+
+Use it when live/current external web information would help answer a task, find current docs/news, or discover candidate URLs. Use `agent_browser` when the task needs browser interaction, screenshots, authenticated/profile content, page inspection, or DOM work. The search tool is Brave-only today, namespaced to avoid colliding with generic `web_search`, and must not expose the resolved API key in content, details, errors, status output, docs examples, logs, or PR artifacts.
+
+Schema:
+
+```json
+{
+  "query": "search text",
+  "count": 5,
+  "offset": 0,
+  "country": "US",
+  "searchLang": "en-US",
+  "safesearch": "moderate",
+  "freshness": "pw"
+}
+```
+
+Result details:
+
+```json
+{
+  "provider": "brave",
+  "query": "search text",
+  "returnedQuery": "search text",
+  "count": 5,
+  "offset": 0,
+  "fetchedAt": "2026-06-02T00:00:00.000Z",
+  "results": [
+    {
+      "title": "Result title",
+      "url": "https://example.com/",
+      "description": "Compact summary",
+      "source": "Example",
+      "age": "1 day ago",
+      "language": "en"
+    }
+  ]
+}
+```
+
 ## Input mode chooser
 
 Use exactly one top-level input per call:
@@ -88,7 +132,7 @@ The extension always plans normal browser commands with `--json` prepended in `e
 - For Electron desktop apps, prefer top-level electron for wrapper-owned discovery, isolated launch, status, compact probe, and cleanup: list first, treat likely-sensitive annotations as hints rather than enforcement, launch with the default snapshot handoff unless handoff: "tabs" is the safer diagnostic starting point, use electron.probe or snapshot -i/qa.attached for current-session state, and always cleanup the returned launchId when done. electron.launch uses an isolated temporary profile; it does not reuse the app's normal signed-in profile or attach to an already-running authenticated app. For signed-in local app state, host-launch the normal app with --remote-debugging-port when appropriate, then use raw args connect <port|url>; after connect, inspect tab list, select the stable tab id such as tab t2, then run a condition wait or snapshot -i before using refs. close commands (`close`, `quit`, or `exit`) only close the browser/CDP session; leave manually launched app shutdown, profile cleanup, and explicit artifacts to the host owner.
 - For provider or specialized app workflows, load version-matched upstream guidance with skills get agentcore|electron|slack|dogfood|vercel-sandbox through the native tool; add --full when you need references/templates, and use skills get --all only for broad skill audits. Provider launches such as -p ios, --provider browserbase/kernel/browseruse/browserless/agentcore, and iOS --device are upstream-owned setup paths; use sessionMode fresh when switching providers and expect external credentials or local Appium/Xcode setup to be required.
 - For dialogs and frames, use dialog status/accept/dismiss and frame <selector|main> through native args; when --confirm-actions produces a pending confirmation, use details.nextActions or exact confirm <id> / deny <id> calls instead of inventing ids.
-- 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 <tab-id-or-label> / snapshot -i to recover state before retrying different URLs or fallback strategies. For headed demos, put --headed on the first launch with sessionMode=fresh and verify with screenshot/tab/get-url evidence because tool success cannot prove the OS window is visible to the user. For desktop readiness, prefer real conditions first: wait --text, wait --url, wait --fn, wait --load <state>, wait --download, or qa.attached; for disappearance checks in agent-browser 0.27.0, use wait --fn predicates instead of stale upstream-help examples like wait <selector> --state hidden. Use electron.probe/status for wrapper-owned launch health or target mismatch. Fixed waits are a last resort, must stay below the wrapper IPC budget (wait 30000 is intentionally blocked), and a successful payload like "waited":"timeout" means elapsed time only—verify completion with an observed condition, fresh snapshot, or screenshot.
+- 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 <tab-id-or-label> / snapshot -i to recover state before retrying different URLs or fallback strategies. For headed demos, put --headed on the first launch with sessionMode=fresh and verify with screenshot/tab/get-url evidence because tool success cannot prove the OS window is visible to the user. For desktop readiness, prefer real conditions first: wait --text, wait --url, wait --fn, wait --load <state>, wait --download, or qa.attached; for disappearance checks in agent-browser 0.27.1, use wait --fn predicates instead of stale upstream-help examples like wait <selector> --state hidden. Use electron.probe/status for wrapper-owned launch health or target mismatch. Fixed waits are a last resort, must stay below the wrapper IPC budget (wait 30000 is intentionally blocked), and a successful payload like "waited":"timeout" means elapsed time only—verify completion with an observed condition, fresh snapshot, or screenshot.
 - 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.
 - 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.
 - For downloads, prefer download <selector> <path> when an element click should save a file. Do not rely on click alone when you need the downloaded file on disk.

package/docs/platform-smoke.md

@@ -0,0 +1,176 @@
+# Platform smoke testing
+
+`pi-agent-browser-native` uses a Crabbox-backed local platform smoke gate to prove the package on macOS, Ubuntu Linux, and native Windows before release.
+
+This is a release-blocking gate. Missing Crabbox setup, Docker, macOS SSH, the native Windows template, upstream `agent-browser`, or browser runtime dependencies is a blocked release setup, not a skipped pass.
+
+## Required release gate
+
+Run the cheap harness checks first, then the full matrix:
+
+```sh
+npm run check:platform-smoke
+npm run smoke:platform:ubuntu-image
+npm run smoke:platform:all
+```
+
+`smoke:platform:all` runs `smoke:platform:doctor` before any target suite starts. The canonical `npm run verify -- release` gate also runs the same platform doctor and full `macos,ubuntu,windows-native` matrix after default verification and packaged Pi smoke, so `npm publish` cannot pass `prepublishOnly` without the platform gate.
+
+Per-target commands are for diagnosis:
+
+```sh
+npm run smoke:platform:macos
+npm run smoke:platform:ubuntu
+npm run smoke:platform:windows-native
+npm run verify -- platform-smoke run --target ubuntu --suite platform-build
+```
+
+## Targets
+
+| Target | Crabbox provider | Shell contract | Release status |
+| --- | --- | --- | --- |
+| `macos` | `ssh` static localhost | POSIX shell on macOS | Required |
+| `ubuntu` | `local-container` | POSIX shell in a Docker-compatible local container | Required |
+| `windows-native` | `parallels` | native Windows PowerShell over OpenSSH | Required |
+
+## Required environment
+
+Install Crabbox on the macOS maintainer host and keep it on `PATH`:
+
+```sh
+brew install openclaw/tap/crabbox
+crabbox --version
+crabbox providers
+```
+
+Use `PLATFORM_SMOKE_CRABBOX=/path/to/crabbox` only when testing a non-default Crabbox binary.
+
+Standard configuration knobs:
+
+```sh
+PLATFORM_SMOKE_MAC_HOST=localhost
+PLATFORM_SMOKE_MAC_USER="$USER"
+PLATFORM_SMOKE_MAC_WORK_ROOT="/Users/$USER/crabbox/pi-agent-browser-native"
+
+# Default local image built by npm run smoke:platform:ubuntu-image.
+PLATFORM_SMOKE_UBUNTU_IMAGE="pi-agent-browser-native-platform:node24-agent-browser0.27.1"
+
+PLATFORM_SMOKE_WINDOWS_VM="pi-extension-windows-template"
+PLATFORM_SMOKE_WINDOWS_SNAPSHOT="crabbox-ready"
+PLATFORM_SMOKE_WINDOWS_USER="<windows-ssh-user>"
+PLATFORM_SMOKE_WINDOWS_WORK_ROOT="C:\\crabbox\\pi-agent-browser-native"
+
+# Optional: names of secret env vars to redact/forward if future live suites need them.
+PLATFORM_SMOKE_AUTH_ENV=""
+```
+
+The Ubuntu target image is derived from `node:24-bookworm`, installs `agent-browser@0.27.1`, installs Debian Chromium through apt, creates a non-root `circleci` user, and sets `AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium`. Rebuild it after upstream rebaselining, or override `PLATFORM_SMOKE_UBUNTU_IMAGE` with an equivalent prepared local image. Do not install `agent-browser` ad hoc inside the Ubuntu smoke command.
+
+The configured upstream `agent-browser` baseline is imported from [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs). Target-local browser suites verify that exact `agent-browser` version before running. Bake the exact upstream CLI and browser runtime into the Windows template/snapshot for speed and reproducibility; missing or stale Windows `agent-browser` / browser readiness is a blocked setup, not something the smoke command repairs. The Windows browser suite checks the preinstalled browser cache and prewarms one short local file URL before the extension harness runs.
+
+## Target setup expectations
+
+Crabbox does not install project runtime tools. The macOS host, Ubuntu image, and Windows template must already provide:
+
+- Node/npm at or above the configured Node major baseline in [`platform-smoke.config.mjs`](../platform-smoke.config.mjs).
+- Git and `tar`.
+- Upstream `agent-browser` matching this wrapper’s capability baseline. The Ubuntu target gets it from [`scripts/platform-smoke/linux-image/Dockerfile`](../scripts/platform-smoke/linux-image/Dockerfile); the Windows template gets it from the shared `pi-extension-windows-template` / `crabbox-ready` snapshot.
+- Browser/runtime dependencies needed by upstream `agent-browser`.
+- Native PowerShell and OpenSSH Server on Windows.
+
+For Windows, reuse `pi-extension-windows-template` with the shared canonical `crabbox-ready` power-off snapshot. Do not create one-off project VMs. If a reusable tool is missing, update the shared template, verify from a fresh SSH session, remove caches/secrets/checkouts, shut down cleanly, and promote a known-good power-off snapshot.
+
+## What the suites prove
+
+Each required target runs `platform-build` and `browser-dogfood-smoke` on one Crabbox lease, serially.
+
+### `platform-build`
+
+1. Verify the target Node major version.
+2. Run `npm ci` in the synced checkout.
+3. Run `npm run verify -- platform-target`, a fast target-local gate covering generated docs, TypeScript, package/platform harness tests, and runtime planning. The full unit/fake suite still runs once in the host default gate before the release matrix starts; target-local smoke must not duplicate that full suite on every OS. Browser subprocess behavior is then exercised by the target-local `browser-dogfood-smoke` suite against the real upstream binary.
+4. Run `npm pack`.
+5. Create a clean target-local Pi project.
+6. Install the packed tarball with `npm install --no-save`.
+7. Run `pi install -l ./node_modules/pi-agent-browser-native` from the clean project.
+8. Run `pi list` and assert the package is registered from the packed install.
+9. Assert the release proof did not use `pi -e .` or `pi --extension .`.
+
+### `browser-dogfood-smoke`
+
+1. Run `npm ci` in the synced checkout if needed.
+2. Run the deterministic model-free browser smoke through `scripts/verify-agent-browser-dogfood.ts`.
+3. Exercise native wrapper surfaces against the deterministic local file fixture from `scripts/verify-agent-browser-dogfood.ts`: top-level `qa`, `semanticAction`, constrained `job`, screenshot artifact verification, and session close.
+4. Persist the dogfood JSON report and stdout/stderr evidence.
+5. Fail on missing browser artifacts, failed tool calls, leaked secrets, or unclosed sessions.
+
+The dogfood suite intentionally uses the checkout harness while `platform-build` proves packed Pi installation. Together they catch OS-specific packaging, install, path, process, browser, and wrapper bugs without using an LLM.
+
+## Artifact contract
+
+Every target suite writes host-side evidence under:
+
+```text
+.artifacts/platform-smoke/<run-id>/<target>/<suite>/
+```
+
+Required files include:
+
+```text
+summary.json
+artifact-manifest.json
+target.json
+suite.json
+command.txt
+exit-code.txt
+crabbox.stdout.txt
+crabbox.stderr.txt
+crabbox.timing.json
+assertions.json
+failures.md            # only when assertions fail
+```
+
+`platform-build` also writes:
+
+```text
+node-version.txt
+packed-tarball.txt
+packed-node-install.stdout.txt
+packed-node-install.stderr.txt
+pi-install.stdout.txt
+pi-install.stderr.txt
+pi-list.stdout.txt
+pi-list.stderr.txt
+```
+
+`browser-dogfood-smoke` also writes:
+
+```text
+node-version.txt
+dogfood-artifacts.txt
+dogfood.stdout.txt
+dogfood.stderr.txt
+dogfood-report.json
+```
+
+Each target also writes a `lease-cleanup` artifact directory with `crabbox.stop.*` files. Cleanup failures are failing test results. Ubuntu and Windows runs also invoke Crabbox cleanup for stale direct-provider state after stopping the owned lease.
+
+Passing suites must satisfy:
+
+```text
+summary.ok === assertions.ok
+artifact-manifest.missing.length === 0
+```
+
+The harness redacts configured secret values and token-like text from persisted artifacts, then fails if a redaction scan still finds raw secrets.
+
+## Source of truth
+
+- Config: [`platform-smoke.config.mjs`](../platform-smoke.config.mjs)
+- CLI: [`scripts/platform-smoke.mjs`](../scripts/platform-smoke.mjs)
+- Crabbox wrapper: [`scripts/platform-smoke/crabbox-runner.mjs`](../scripts/platform-smoke/crabbox-runner.mjs)
+- Target commands/assertions: [`scripts/platform-smoke/targets.mjs`](../scripts/platform-smoke/targets.mjs)
+- Platform doctor: [`scripts/platform-smoke/doctor.mjs`](../scripts/platform-smoke/doctor.mjs)
+- Artifact helpers: [`scripts/platform-smoke/artifacts.mjs`](../scripts/platform-smoke/artifacts.mjs)
+- Windows build suite: [`scripts/platform-smoke/platform-build-windows.ps1`](../scripts/platform-smoke/platform-build-windows.ps1)
+- Windows browser suite: [`scripts/platform-smoke/browser-dogfood-windows.ps1`](../scripts/platform-smoke/browser-dogfood-windows.ps1)

package/extensions/agent-browser/index.ts

@@ -41,7 +41,6 @@ import {
 	getImplicitSessionCloseTimeoutMs,
 	getImplicitSessionIdleTimeoutMs,
 	hasLaunchScopedTabCorrectionFlag,
-	hasUsableBraveApiKey,
 	extractExplicitSessionName,
 	redactInvocationArgs,
 	restoreManagedSessionStateFromBranch,
@@ -118,6 +117,8 @@ import {
 	type VisibleRefFallbackDiagnostic,
 } from "./lib/results/selector-recovery.js";
 import { withOptionalSessionArgs } from "./lib/results/next-actions.js";
+import { canRegisterWebSearchTool, loadAgentBrowserConfigSync } from "./lib/config.js";
+import { createAgentBrowserWebSearchTool } from "./lib/web-search.js";
 
 const DEFAULT_SESSION_MODE = "auto" as const;
 const DIRECT_AGENT_BROWSER_BASH_BYPASS_ENV = "PI_AGENT_BROWSER_ALLOW_DIRECT_BASH";
@@ -947,8 +948,13 @@ function getInstalledDocsPaths(): { readmePath: string; commandReferencePath: st
 
 export default function agentBrowserExtension(pi: ExtensionAPI) {
 	const ephemeralSessionSeed = createEphemeralSessionSeed();
-	const hasBraveApiKey = hasUsableBraveApiKey();
-	const toolPromptGuidelines = buildToolPromptGuidelines({ includeBraveSearch: hasBraveApiKey, docs: getInstalledDocsPaths() });
+	const agentBrowserConfig = loadAgentBrowserConfigSync({ cwd: process.cwd() });
+	const webSearchToolAvailable = canRegisterWebSearchTool(agentBrowserConfig);
+	const toolPromptGuidelines = buildToolPromptGuidelines({
+		browserDefaultProfile: agentBrowserConfig.browserDefaultProfile,
+		includeBraveSearch: webSearchToolAvailable,
+		docs: getInstalledDocsPaths(),
+	});
 	const implicitSessionIdleTimeoutMs = String(getImplicitSessionIdleTimeoutMs());
 	const implicitSessionCloseTimeoutMs = getImplicitSessionCloseTimeoutMs();
 	let managedSessionActive = false;
@@ -1267,4 +1273,8 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				: runBrowserCommand();
 		},
 	});
+
+	if (webSearchToolAvailable) {
+		pi.registerTool(createAgentBrowserWebSearchTool(agentBrowserConfig));
+	}
 }