pi-agent-browser-native 0.8.1 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.8.2 - 2026-09-27
+
+### Added
+
+- Supply extension-owned browser discovery metadata on capable Pi hosts, including conditional web search, without a user-maintained settings inventory. Official Pi retains its ordinary entry tools and lazy advanced loader.
+
+### Fixed
+
+- Prepare complete deferred browser instructions for generic prompts so same-run discovery reveals them before the first browser action.
+
 ## 0.8.1 - 2026-09-26
 
 ### Fixed

package/README.md

@@ -45,7 +45,7 @@ The agent gets a native tool, not a bash workaround:
 { "args": ["find", "text", "Learn React", "click"] }
 ```
 
-Use native commands for individual actions, `batch --bail` for fixed sequences, and `agent_browser_code` for loops or branches. Specialized tools are available through `agent_browser_tools`; see [common calls](#common-agent-calls).
+Use native commands for individual actions, `batch --bail` for fixed sequences, and `agent_browser_code` for loops or branches. Specialized tools are available through `agent_browser_tools`; see [common calls](#common-agent-calls). On hosts supporting extension-owned discovery, enable the `browser` group through `discover_tools` first. The extension supplies its own membership and instructions; no user-maintained tool inventory is needed. Official Pi keeps the ordinary direct/code/loader surface.
 
 The result is optimized for agent work:
 

package/dist/extensions/agent-browser/index.js

@@ -34,7 +34,7 @@ import { buildValidationFailureResult, resolveAgentBrowserInput } from "./lib/or
 import { applyAgentBrowserOutputPath, canWriteAgentBrowserOutput, normalizeRequestedOutputPath } from "./lib/orchestration/output-file.js";
 import { appendScriptSessionLease, createBrowserCodeOutput, getScriptSessionLeasesFromBranch } from "./lib/orchestration/script-mode.js";
 import { resolveBrowserExecutionIdentity, withBrowserExecutionLock, withBrowserExecutionLocks } from "./lib/managed-session-policy-lock.js";
-import { registerAgentBrowserToolSurface } from "./lib/tool-surface.js";
+import { AGENT_BROWSER_DISCOVERY_GROUP, registerAgentBrowserToolSurface } from "./lib/tool-surface.js";
 import { formatSessionArtifactRetentionSummary, getSessionArtifactManifestEntryKey, isPendingRecordingCommand, isSessionArtifactManifest, mergeSessionArtifactManifest, retirePendingRecordingManifestEntries } from "./lib/results/artifact-manifest.js";
 import { appendUniqueAgentBrowserNextActions, applyNamespaceToNextActions, applySessionToNextActions, buildNextToolAction } from "./lib/results/next-actions.js";
 import { canRegisterWebSearchTool, loadAgentBrowserConfigSync } from "./lib/config.js";
@@ -1229,14 +1229,17 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
     const registerWebSearchToolIfAvailable = (configState) => {
         if (webSearchToolRegistered || !canRegisterWebSearchTool(configState))
             return;
-        pi.registerTool(createAgentBrowserWebSearchTool(configState, {
-            loadConfigState(ctx) {
-                return loadAgentBrowserConfigSync({
-                    cwd: ctx.cwd,
-                    includeProjectConfig: shouldIncludeProjectConfig(ctx),
-                });
-            },
-        }));
+        pi.registerTool({
+            ...{ discovery: { group: AGENT_BROWSER_DISCOVERY_GROUP, role: "entry" } },
+            ...createAgentBrowserWebSearchTool(configState, {
+                loadConfigState(ctx) {
+                    return loadAgentBrowserConfigSync({
+                        cwd: ctx.cwd,
+                        includeProjectConfig: shouldIncludeProjectConfig(ctx),
+                    });
+                },
+            }),
+        });
         webSearchToolRegistered = true;
     };
     pi.on("session_start", async (_event, ctx) => {
@@ -1400,7 +1403,8 @@ export default function agentBrowserExtension(pi, { beforeExecute } = {}) {
         await cleanupSecureTempArtifacts({ preservePaths: preservedElectronProfileDirs });
     });
     pi.on("before_agent_start", async (event, ctx) => {
-        if (!shouldAppendBrowserSystemPrompt(event.prompt)) {
+        const sectionTools = event.systemPromptOptions?.sectionTools;
+        if (!Object.hasOwn(sectionTools ?? {}, "agent_browser") && !shouldAppendBrowserSystemPrompt(event.prompt)) {
             return undefined;
         }
         const runtimeConfig = loadAgentBrowserConfigSync({

package/dist/extensions/agent-browser/lib/tool-surface.js

@@ -9,10 +9,18 @@ export const AGENT_BROWSER_TOOL_INVENTORY = {
     source: { name: "agent_browser_source", description: "Find experimental DOM/React/local-source candidates with a bounded workspace scan." },
     network: { name: "agent_browser_network_source", description: "Correlate failed requests with initiator and local-source candidates." },
 };
+export const AGENT_BROWSER_DISCOVERY_GROUP = {
+    name: "browser",
+    description: "Search the web, browse and interact with pages, verify browser UI, and inspect Electron apps.",
+    sections: ["agent_browser"],
+};
+const entryDiscovery = { discovery: { group: AGENT_BROWSER_DISCOVERY_GROUP, role: "entry" } };
+const advancedDiscovery = { discovery: { group: AGENT_BROWSER_DISCOVERY_GROUP, role: "advanced" } };
 const advancedNames = new Set(Object.values(AGENT_BROWSER_TOOL_INVENTORY).map(({ name }) => name));
 /** Register once; advanced calls adapt only their input shape and reuse the ordinary executor. */
 export function registerAgentBrowserToolSurface(pi, options) {
     pi.registerTool({
+        ...entryDiscovery,
         name: "agent_browser",
         label: "Agent Browser",
         description: "Browse and interact through native agent-browser commands. One command in args; fixed sequences use batch --bail and JSON-array stdin. Use agent_browser_code for loops/branches and agent_browser_tools for advanced capabilities.",
@@ -25,6 +33,7 @@ export function registerAgentBrowserToolSurface(pi, options) {
         executionMode: options.executionMode,
     });
     pi.registerTool({
+        ...entryDiscovery,
         name: "agent_browser_code",
         label: "Agent Browser Code",
         description: "Run fresh JavaScript against a persistent browser. await browser({args,stdin?,timeoutMs?}) returns success/data/error/nextActions and imageObservations; emit(selected JSON) and emitImage(image handle) explicitly choose output. No host APIs or imports. Use native batch for fixed sequences.",
@@ -40,6 +49,7 @@ export function registerAgentBrowserToolSurface(pi, options) {
         renderResult: options.renderResult,
     });
     pi.registerTool({
+        ...advancedDiscovery,
         ...AGENT_BROWSER_TOOL_INVENTORY.action,
         label: "Browser Action",
         promptGuidelines: [...ADVANCED_TOOL_PROMPT_GUIDELINES.action],
@@ -51,6 +61,7 @@ export function registerAgentBrowserToolSurface(pi, options) {
         },
     });
     pi.registerTool({
+        ...advancedDiscovery,
         ...AGENT_BROWSER_TOOL_INVENTORY.qa,
         label: "Browser QA",
         promptGuidelines: [...ADVANCED_TOOL_PROMPT_GUIDELINES.qa],
@@ -62,6 +73,7 @@ export function registerAgentBrowserToolSurface(pi, options) {
         },
     });
     pi.registerTool({
+        ...advancedDiscovery,
         ...AGENT_BROWSER_TOOL_INVENTORY.electron,
         label: "Browser Electron",
         promptGuidelines: [...ADVANCED_TOOL_PROMPT_GUIDELINES.electron],
@@ -73,6 +85,7 @@ export function registerAgentBrowserToolSurface(pi, options) {
         },
     });
     pi.registerTool({
+        ...advancedDiscovery,
         ...AGENT_BROWSER_TOOL_INVENTORY.source,
         label: "Browser Source",
         promptGuidelines: [...ADVANCED_TOOL_PROMPT_GUIDELINES.source],
@@ -84,6 +97,7 @@ export function registerAgentBrowserToolSurface(pi, options) {
         },
     });
     pi.registerTool({
+        ...advancedDiscovery,
         ...AGENT_BROWSER_TOOL_INVENTORY.network,
         label: "Browser Network Source",
         promptGuidelines: [...ADVANCED_TOOL_PROMPT_GUIDELINES.network],
@@ -95,6 +109,7 @@ export function registerAgentBrowserToolSurface(pi, options) {
         },
     });
     pi.registerTool({
+        ...entryDiscovery,
         name: "agent_browser_tools",
         label: "Browser Tools",
         description: "List or enable advanced browser tools: action → agent_browser_action; qa → agent_browser_qa; electron → agent_browser_electron; source → agent_browser_source; network → agent_browser_network_source. Omit enable for inventory. Activation only adds tools; it preserves other active tools.",

package/docs/ARCHITECTURE.md

@@ -23,6 +23,10 @@ The package install path is the primary product path. Local checkout development
 
 Optional `agent_browser_web_search` remains separately credential/config gated and independent of browser state.
 
+Registration-owned `discovery` metadata uses one `AGENT_BROWSER_DISCOVERY_GROUP` descriptor in `lib/tool-surface.ts` (`browser`, section `agent_browser`). Direct, code, loader, and conditional/late web search registrations are entry tools; the existing five specialized registrations are advanced tools. Capable hosts derive membership from the permitted registry, without another name catalog or user configuration. Official Pi ignores the metadata. The advanced loader and native selected-tool history remain unchanged.
+
+`before_agent_start` prepares the complete browser section when `systemPromptOptions.sectionTools` has its own `agent_browser` key, including generic prompts. An empty map, another extension's key, or an inherited key does not trigger it. Without that ownership, the existing keyword gate applies. The host retains hidden section text and reveals it during same-run discovery; the extension never reruns the hook or replaces an opaque full system prompt. Project guidance and all execution guards retain their existing paths.
+
 ### Direct subprocess execution
 
 The extension should:

package/docs/COMMAND_REFERENCE.md

@@ -230,6 +230,8 @@ Call `agent_browser_tools {}` for inventory, then enable required capabilities:
 { "enable": ["action", "qa", "electron", "source", "network"] }
 ```
 
+On hosts supporting extension-owned discovery, first enable the `browser` group with `discover_tools`; its entry surface includes direct commands, code, this advanced loader, and web search when configured. The group is defined by registrations, not a user-maintained inventory. Official Pi exposes the ordinary entry tools without this host-level discovery step.
+
 Activation is additive and uses native Pi selected-tool history. Omit CLI `--tools` for normal lazy activation, or include desired advanced tools in that explicit selection; excluded tools remain unavailable. The tools take flat input:
 
 | Tool | Example |

package/docs/SUPPORT_MATRIX.md

@@ -40,7 +40,7 @@ The compact direct/code/loader surface replaces public multimode inputs while re
 | RQ-0142 code | Fresh permissioned Node child over persistent parent-selected browser; explicit JSON/current-cell image output, visible failures/counts, ordinary auth/config/environment, ordered Pi intent/completion transitions, child cancellation/reaping, no legacy public execution. |
 | Shared ordering | Actual socket/namespace/session lock spans helper/action or entire cell; sorted identity sets for replacement/cleanup and namespace barrier for direct close-all. Requires every participating Pi to run the updated package; no human/third-party/older-version guarantee or transaction. |
 | Observation and geometry | Canonical bounded JSON/prose/code observations expose exact recovery and receipts; complete observation spills preserve large output. Image dimensions/CSS viewport/DPR/crop/scroll/frame evidence is measured or explicitly unknown; no viewport-coordinate assumptions for full-page/element images. |
-| Pi integration | Native additive activation/history and prompt sections on independently qualified official Pi 0.87 and fork; optional checkpoint hooks, no provider payload/image-detail overrides. |
+| Pi integration | Native additive activation/history and prompt sections on independently qualified official Pi 0.87 and fork; registration-owned `browser` discovery metadata on capable hosts, ordinary exposure on official hosts. Generic prompts prepare the deferred browser section before same-run activation; `test/agent-browser.discovery.test.ts` covers own-key gating and startup/late registration, with pipeline coverage in `test/agent-browser.pi-pipeline.test.ts`. Optional checkpoint hooks, no provider payload/image-detail overrides. |
 
 See [migration](TOOL_CONTRACT.md#07-migration), [canonical observations](TOOL_CONTRACT.md#canonical-observation), and [release qualification/rollback](RELEASE.md#07-upgrade-and-rollback). Routine GitHub Actions runs official/fork Linux compatibility, a macOS packed-Pi smoke, and native Linux checkpoints on PRs to `main`; Windows CI is excluded. Release/platform evidence and review remain separate from these focused checks.
 

package/docs/TOOL_CONTRACT.md

@@ -10,7 +10,9 @@ Related docs:
 
 ## Browser tools
 
-Always-on tools are `agent_browser` (native argv), `agent_browser_code` (fresh JavaScript over a persistent browser), and `agent_browser_tools` (advanced capability discovery/activation). Optional credential-backed `agent_browser_web_search` remains independent.
+Entry tools are `agent_browser` (native argv), `agent_browser_code` (fresh JavaScript over a persistent browser), and `agent_browser_tools` (advanced capability discovery/activation). Optional credential-backed `agent_browser_web_search` remains independent of browser state and joins the entry surface only when registered.
+
+On hosts supporting extension-owned discovery, these registrations belong to the `browser` group: `discover_tools` enables the entry tools, and `agent_browser_tools` still enables the five advanced tools below. Tool selection, exclusions, and restored activation remain host-owned. No user-maintained group inventory is required. Discovery metadata is host-only, not a tool parameter or provider request field. Official Pi ignores the optional metadata and retains ordinary entry-tool exposure. The extension prepares its complete `agent_browser` prompt section even for a generic user prompt when the host identifies that section as deferred; the host reveals it on activation in the same run, before browser execution. Hosts without that section ownership retain keyword-triggered prompt guidance.
 
 Pi 0.87.0 or newer is required; official and fork qualification is independent. Five specialized tools are registered but initially inactive: `agent_browser_action`, `agent_browser_qa`, `agent_browser_electron`, `agent_browser_source`, and `agent_browser_network_source`. Explicit CLI allowlists, filtered SDK catalogs, and restored Pi tool history are respected. Omit CLI `--tools` for lazy activation, or include every desired advanced tool in its allowlist; the loader reports excluded tools as unavailable rather than bypassing host selection. Pi 0.87 does not distinguish an SDK explicitly selecting the complete browser catalog from its default catalog; SDK hosts choosing activation for that complete catalog can call `session.setActiveToolsByName(...)` after `bindExtensions()`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",