pi-agent-browser-native 0.2.58 → 0.2.60

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+## 0.2.60 - 2026-06-24
+
+### Changed
+
+- Removed a dead `as never` cast and unreachable try/catch from the `agent_browser` collapsed-output "to expand" keybinding hint. `app.tools.expand` is a host-registered keybinding id (coding-agent augments pi-tui's `Keybindings` via declaration merging), so the id is resolved cast-free via `getKeybindings().getKeys(...)` with the stock `ctrl+o` fallback preserved for bare-node test contexts. No behavior change; the `pi-coding-agent` package stays type-only in the entrypoint import path so startup tax is unchanged.
+
+### Validation
+
+- Ran `npm run verify` (default gate: docs, typecheck, 575/575 unit, command-reference baseline + live drift), `npm run verify -- startup-profile --samples 3` (median 50.1ms, < 250ms budget), `npm run verify -- real-upstream`, `npm run verify -- lifecycle`, `npm run verify -- dogfood`, `npm run verify -- pre-pr`, and `npm run doctor` against the local checkout.
+- Ran an independent reviewer subagent over the diff; no blockers found and the compaction-orphan audit claim was confirmed disproven against Pi 0.80.2 source.
+
+## 0.2.59 - 2026-06-24
+
+### Changed
+
+- Shortened the always-on `agent_browser` prompt guidance by over 1KB while preserving the native-tool trigger, open → `snapshot -i` workflow, `sessionMode=fresh`, artifact verification, and extraction rules.
+- Moved the quick live-search guidance onto `agent_browser_web_search` so browser-search routing stays available without duplicating that guidance in the main browser tool prompt.
+
+### Validation
+
+- Ran `npm run verify -- release`, `npm run doctor`, and `npm run verify -- startup-profile --samples 3` against the local checkout.
+- Ran tmux-driven Pi checkout smoke with `pi --approve --model zai/glm-5.2:high --no-extensions --no-skills --session-dir <tmp> -e .`, confirming the model chose `agent_browser` for `open` + `snapshot -i`, chose `agent_browser_web_search` for live search, and closed the managed browser session.
+- Ran an independent reviewer subagent over the diff; no blockers found.
+
 ## 0.2.58 - 2026-06-23
 
 ### Changed

package/dist/extensions/agent-browser/lib/pi-tool-rendering.js

@@ -73,16 +73,13 @@ function colorizeToolOutputLines(outputText, theme, isError) {
         return isError ? theme.fg("error", line) : theme.fg("toolOutput", line);
     });
 }
+// ponytail: "app.tools.expand" is a host-registered keybinding id (coding-agent augments pi-tui's
+// Keybindings via declaration merging); getKeys returns [] before the host registers its ids
+// (bare-node tests), so fall back to the stock ctrl+o. pi-tui is already a runtime import at
+// the entrypoint, so getKeybindings() adds no startup tax.
 function formatExpandHint(theme) {
-    try {
-        const [key] = getKeybindings().getKeys("app.tools.expand");
-        if (key)
-            return `${theme.fg("dim", key)} ${theme.fg("muted", "to expand")}`;
-    }
-    catch {
-        // Fall through to the built-in default key when coding-agent keybindings are unavailable.
-    }
-    return `${theme.fg("dim", "ctrl+o")} ${theme.fg("muted", "to expand")}`;
+    const key = getKeybindings().getKeys("app.tools.expand")[0] ?? "ctrl+o";
+    return `${theme.fg("dim", key)} ${theme.fg("muted", "to expand")}`;
 }
 function formatVisualTruncationNotice(remainingLines, totalLines, theme, width) {
     const notice = `${theme.fg("muted", `... (${remainingLines} more lines, ${totalLines} total, `)}${formatExpandHint(theme)}${theme.fg("muted", ")")}`;

package/dist/extensions/agent-browser/lib/playbook.js

@@ -8,10 +8,10 @@ import { LAUNCH_SCOPED_FLAG_LABEL } from "./launch-scoped-flags.js";
  */
 export const PROJECT_RULE_PROMPT = "Project 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.";
 export const TOOL_PROMPT_GUIDELINES_PREFIX = [
-    "Use agent_browser whenever the task requires a real browser or live web content.",
+    "Use agent_browser for real browser or live web content.",
 ];
 export function buildInstalledDocsGuideline(paths) {
-    return `For deeper agent_browser guidance without bloating context, read installed package docs on demand: ${paths.readmePath} for setup/external dependencies, ${paths.commandReferencePath} for command workflows, and ${paths.toolContractPath} for result/details contracts. Do not load the full command reference unless needed; prefer targeted sections.`;
+    return `For detailed agent_browser docs, read targeted sections: ${paths.readmePath} (setup), ${paths.commandReferencePath} (commands), ${paths.toolContractPath} (result/details). Do not load the full command reference unless needed.`;
 }
 export const QUICK_START_GUIDELINES = [
     `Quick start mental model: use exactly one of args (exact agent-browser CLI args after the binary), semanticAction (a thin shorthand compiled to find argv for locator actions, direct selector/ref click/check/fill, or select argv for native dropdowns), job (a constrained short-workflow schema compiled to batch --bail by default; set failFast:false only when later diagnostics should continue after a failed step), qa (a lightweight fail-fast QA preset built on batch --bail with bounded visible expected-text checks, including qa.attached for current sessions), electron (desktop Electron list/launch/status/cleanup/probe), or the experimental sourceLookup / networkSourceLookup helpers (candidates only; each compiled to batch); stdin is only for batch, eval --stdin, auth save --password-stdin, and wrapper-generated batch stdin from job, qa, sourceLookup, or networkSourceLookup, and is rejected with electron; sessionMode=fresh switches the extension-managed pi-scoped session to a fresh upstream launch when you need new launch-scoped flags (${LAUNCH_SCOPED_FLAG_LABEL}) to apply. Use outputPath for durable eval/get/snapshot captures. Do not pass --json in args; the wrapper injects it.`,
@@ -24,7 +24,7 @@ export const QUICK_START_GUIDELINES = [
     "For artifact-producing commands, read the visible artifact block and details.artifactVerification before using files: check requested path, absolute path, existence, size bytes, artifact kind, optional mediaType, status, optional limitation, and verified/missing/pending/unverified counts. details.artifacts contains per-file metadata; record start rows are pending/openRecording until record stop writes the target. The wrapper creates parent directories for direct artifact paths and can save simple loopback HTTP(S) anchor downloads directly to the requested path before upstream download fallback. Browser close does not delete explicit saved files; if close reports details.artifactCleanup, use host file tools to remove paths listed in explicitArtifactPaths (when non-empty) after inspection. If close fails with details.promptGuard.reason=requested-artifacts-missing-before-close, save the exact required artifact path before closing. For annotated screenshots inside batch, put --annotate in top-level args (for example { args: [\"--annotate\", \"batch\"], stdin: \"[[\\\"screenshot\\\",\\\"/tmp/page.png\\\"]]\" }) rather than inside the screenshot step; if annotation labels crowd a dense page, use a scoped or non-annotated screenshot plus snapshot refs instead.",
     "When details.nextActions is present, prefer those exact native agent_browser follow-up payloads over prose guidance; they may include args, stdin, sessionMode, networkSourceLookup, safety notes, or artifactPath for saved files.",
 ];
-export const WEB_SEARCH_PROMPT_GUIDELINE = "Use agent_browser_web_search for quick live search/URL discovery; prefer it over browser-automating public search-engine forms, which can hit anti-bot/CAPTCHA-gated pages. Use agent_browser for interaction/DOM/screenshots/auth after you have a target URL. One query, inspect, one follow-up max; on HTTP 429 stop/report limits.";
+export const WEB_SEARCH_PROMPT_GUIDELINE = "Use agent_browser_web_search for quick live search/URL discovery; prefer it over public search-engine forms that can hit anti-bot/CAPTCHA-gated pages. Use agent_browser after you have a target URL; one query, one follow-up max; stop on HTTP 429.";
 export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
     "Standard workflow: open the page, snapshot -i, interact using current @refs from that snapshot, and re-snapshot after navigation, scrolling, rerendering, or other major DOM changes because refs are page-scoped; the wrapper fails mutation-prone stale/recycled refs before upstream can silently target a different current-page element. On dense pages, use wrapper-side snapshot -i --search <text> or snapshot -i --filter role=<role> to render matching refs while preserving the full ref map in details.refSnapshot, add snapshot --viewport when scroll position or above/below-fold context matters, and add snapshot --diff when a quick before/after ref-map delta would prevent reading a full spill file.",
     "For ordinary forms from one snapshot, batch multiple fill @refs before the submit/click step to avoid serial tool calls; if a fill may autosubmit, navigate, or rerender later fields, split the flow and refresh refs first.",
@@ -60,8 +60,7 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
     "Do not call --help or other exploratory inspection commands unless the user explicitly asks for them or debugging the browser integration is necessary.",
 ];
 export const TOOL_PROMPT_GUIDELINES_SUFFIX = [
-    "Prefer agent_browser over bash for opening sites, docs, clicking, filling, screenshots, eval, and batch workflows.",
-    "Do not fall back to osascript, AppleScript, or generic browser-driving bash commands when agent_browser can do the job.",
+    "Prefer agent_browser over bash, osascript, AppleScript, or generic browser-driving shell for sites, docs, clicking, filling, screenshots, eval, and batch workflows.",
     "Pass exact agent-browser CLI arguments in agent_browser args when you are not using semanticAction, job, or qa, excluding the binary name and --json (agent_browser injects --json automatically).",
     "Use agent_browser stdin only for eval --stdin, batch, auth save --password-stdin, or wrapper-generated job/qa batches instead of shell heredocs or password args; other command/stdin combinations are rejected before launch.",
     `Let the agent_browser extension-managed session handle the common path unless you explicitly need a fresh launch for launch-scoped flags (${LAUNCH_SCOPED_FLAG_LABEL}).`,
@@ -86,12 +85,12 @@ export function buildSharedBrowserPlaybookGuidelines(options) {
 }
 /** Tier A: always-on tool promptGuidelines (keep small; Tier B lives in SHARED_BROWSER_PLAYBOOK_GUIDELINES and docs). */
 export const RUNTIME_PROMPT_GUIDELINES = [
-    "Use agent_browser with exactly one input mode: args, semanticAction, job, qa, sourceLookup/networkSourceLookup, or electron. stdin only for batch/eval/auth or wrapper batch; electron rejects stdin. Do not pass --json in args; agent_browser injects it.",
-    "For agent_browser, the common flow is open, snapshot -i, use current @refs or semanticAction, then re-snapshot after navigation/scroll/rerender/DOM change. Batch same-snapshot forms unless they may submit/navigate/rerender. Keep job flows short around navigation/click/rerender boundaries on dynamic apps. Respect explicit stop boundaries: stop before order/post/purchase/submit.",
-    "Use agent_browser top-level sessionMode=fresh for launch-scoped flags; never put --session-mode in args. For signed-in/account-specific content, use requested/configured profiles, never assume --profile Default; on profile failures, run profiles/doctor and tell the user what to configure. Use --executable-path for configured Chromium. Profile content is model-visible.",
-    "For agent_browser artifacts, save the exact user path and verify details.artifactVerification/details.artifacts before claiming success. If close is blocked by details.promptGuard, save the required artifact first. record stop needs ffmpeg; close does not delete saved files; waited:timeout is not proof.",
-    "When agent_browser details.nextActions is present, prefer exact payloads over prose/guessed selectors. For dense snapshots, check Omitted high-value controls/details.data.highValueControlRefIds. For dashboards, verify scroll with screenshot/snapshot; if nothing moved, target the real scroll region.",
-    "For agent_browser extraction, prefer get title/url/text/html/value/attr/count or eval --stdin with plain expression, not console.log. Batch three or more known refs/selectors (e.g. [[\"get\",\"text\",\"@e1\"],[\"get\",\"text\",\"@e2\"]]); selector visibility warnings → visible @refs/nextActions.",
+    "Use agent_browser with one input mode: args, semanticAction, job, qa, sourceLookup/networkSourceLookup, or electron. stdin only for batch/eval/auth/wrapper batch; electron rejects stdin; never pass --json.",
+    "For agent_browser, use open → snapshot -i → current @refs or semanticAction → re-snapshot after navigation/scroll/rerender. Batch same-snapshot forms; split before navigation/submits. Stop before order/post/purchase/submit.",
+    "Use agent_browser sessionMode=fresh for launch-scoped flags; never put --session-mode in args. Use requested/configured profiles only; on profile failures run profiles/doctor. Profile content is model-visible.",
+    "For agent_browser artifacts, use exact user paths and verify details.artifactVerification/details.artifacts before claiming success. Save details.promptGuard-required artifacts before close; record stop needs ffmpeg; close keeps files; waited:timeout is not proof.",
+    "When agent_browser details.nextActions exists, use exact payloads over guessed selectors/prose. Dense snapshots: check Omitted high-value controls/highValueControlRefIds. Dashboards: verify scroll with screenshot/snapshot.",
+    "For agent_browser extraction, prefer get title/url/text/html/value/attr/count or eval --stdin returning a plain value, not console.log. Batch three-plus known reads; selector visibility warnings mean use visible @refs/nextActions.",
 ];
 export function buildBrowserExecutablePathGuideline(executablePath) {
     if (!executablePath)
@@ -115,8 +114,6 @@ export function buildToolPromptGuidelines(options) {
         ...RUNTIME_PROMPT_GUIDELINES,
         ...(browserExecutablePathGuideline ? [browserExecutablePathGuideline] : []),
         ...(browserDefaultProfileGuideline ? [browserDefaultProfileGuideline] : []),
-        ...(options.includeWebSearch ? [WEB_SEARCH_PROMPT_GUIDELINE] : []),
         TOOL_PROMPT_GUIDELINES_SUFFIX[0],
-        TOOL_PROMPT_GUIDELINES_SUFFIX[1],
     ];
 }

package/dist/extensions/agent-browser/lib/web-search.js

@@ -4,6 +4,7 @@
  * Scope: Live web search only; browser automation remains in the `agent_browser` tool.
  */
 import { JsonSchema } from "./json-schema.js";
+import { WEB_SEARCH_PROMPT_GUIDELINE } from "./playbook.js";
 import { StringEnum as localStringEnum } from "./string-enum-schema.js";
 import { DEFAULT_WEB_SEARCH_PROVIDER, WEB_SEARCH_PROVIDERS, resolvePreferredWebSearchCredential, } from "./config.js";
 export const AGENT_BROWSER_WEB_SEARCH_TOOL_NAME = "agent_browser_web_search";
@@ -505,7 +506,7 @@ export function createAgentBrowserWebSearchTool(configState, options = {}) {
         description: `Search the web with Exa or Brave when configured. Returns up to ${MAX_SEARCH_RESULT_COUNT} concise web results.`,
         promptSnippet: "Search the live web with Exa or Brave for current or external information.",
         promptGuidelines: [
-            "Use agent_browser_web_search when live web search would help answer the task, find current external information, or discover candidate URLs for agent_browser.",
+            WEB_SEARCH_PROMPT_GUIDELINE,
             "agent_browser_web_search chooses Exa or Brave from configured keys; when both are available, Exa is preferred by default unless webSearch.preferredProvider says otherwise. Use provider only when the user/config calls for a specific provider.",
             "Prefer agent_browser_web_search over opening or typing into public search engine result pages with agent_browser when a quick result list is enough; browser-automated search forms are often anti-bot/CAPTCHA-gated, and this tool is the fallback for discovery rather than a CAPTCHA bypass.",
             "Do not issue parallel or repeated agent_browser_web_search calls; use one high-signal query, inspect the results, then only run a focused follow-up if needed. If the provider returns HTTP 429, stop searching and tell the user the API plan/rate limit needs time or a plan change.",

package/package.json

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