@phi-code-admin/phi-code 0.76.2 → 0.76.4

package/extensions/phi/browser.ts

@@ -116,7 +116,15 @@ export default function browserExtension(pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "browser_navigate",
 		description:
-			"Open a URL in a Camoufox tab. If `tabId` is omitted, a new tab is created. Returns the tab id, the final URL and the HTTP status when available.",
+			"Open a URL in a real anti-detect Firefox browser (Camoufox). " +
+			"Use this as the FIRST STEP whenever you need to interact with a page " +
+			"(click, fill a form, take a screenshot) or when a previous `fetch_url` " +
+			"returned empty/minimal content (sign that the page is JavaScript-rendered " +
+			"or behind bot protection like Cloudflare). " +
+			"Returns `tabId` to chain with `browser_extract` / `browser_snapshot` / " +
+			"`browser_click` / `browser_type` / `browser_screenshot` / `browser_scroll`. " +
+			"Slower than `fetch_url` (~3-5s boot on first call) — do not use for plain " +
+			"static HTML pages where `fetch_url` already works.",
 		parameters: Type.Object({
 			url: Type.String({ description: "Full URL (https://...)" }),
 			tabId: Type.Optional(Type.String()),
@@ -140,7 +148,16 @@ export default function browserExtension(pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "browser_extract",
 		description:
-			"Return the readable content of a page (Mozilla Readability under the hood). Works on SPA / JS-heavy sites. Pass either `tabId` (existing tab) or `url` (opens a fresh tab).",
+			"Extract readable text from a fully rendered page using Mozilla Readability. " +
+			"**PREFER THIS OVER `fetch_url`** when the target URL is: " +
+			"(1) a JavaScript SPA (React, Vue, Svelte, Next.js client-side, etc.), " +
+			"(2) behind Cloudflare / Akamai / PerimeterX bot protection, " +
+			"(3) a site where `fetch_url` returned the shell HTML only (title + empty body, " +
+			"or a noscript fallback). Also use this when you've already called " +
+			"`browser_navigate` and want the page content. " +
+			"Either pass `tabId` (continues in an existing tab) or `url` (opens a fresh " +
+			"tab and extracts in one call). Slower than `fetch_url` — keep `fetch_url` as " +
+			"the default for plain static pages, docs, blog posts, etc.",
 		parameters: Type.Object({
 			tabId: Type.Optional(Type.String()),
 			url: Type.Optional(Type.String()),
@@ -163,7 +180,12 @@ export default function browserExtension(pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "browser_screenshot",
 		description:
-			"Capture a screenshot of the current tab as a PNG. The image bytes are returned base64-encoded under `bytesBase64`.",
+			"Capture a PNG screenshot of an open tab. Use this whenever the user asks " +
+			"to *see* a page, when a visual proof is requested (e.g. \"show me what " +
+			"this looks like\", \"is the layout broken\", \"did the bot detection page " +
+			"trigger?\"), or to confirm a UI state after `browser_click` / " +
+			"`browser_type`. Requires a `tabId` from a prior `browser_navigate`. " +
+			"Returns the image as base64 under `bytesBase64` with `mimeType: image/png`.",
 		parameters: Type.Object({
 			tabId: Type.String(),
 			fullPage: Type.Optional(Type.Boolean()),
@@ -179,7 +201,14 @@ export default function browserExtension(pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "browser_search",
 		description:
-			"Run a web search through the Camoufox browser (anti-detect Firefox) and return the readability extraction of the results page. Useful when scraping Google directly is rate-limited.",
+			"Search the web *through* a real anti-detect Firefox browser, then return " +
+			"the readability extraction of the results page. " +
+			"**Fallback for `web_search`** — use this only when `web_search` " +
+			"rate-limited, returned a CAPTCHA / 429 / 403, or you specifically need " +
+			"the rendered search engine UI (e.g. featured snippets, knowledge cards, " +
+			"AI Overview boxes). Slower than `web_search` and requires the Camoufox " +
+			"browser to boot. Defaults to DuckDuckGo (least restrictive); pass " +
+			"`engine: \"google\"` only when you need Google-specific results.",
 		parameters: Type.Object({
 			query: Type.String(),
 			engine: Type.Optional(
@@ -201,7 +230,15 @@ export default function browserExtension(pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "browser_click",
 		description:
-			"Click an element. Pass either `ref` (returned by browser_snapshot) or `selector` (CSS).",
+			"Click an element on an open tab — buttons, links, checkboxes, modal " +
+			"close icons, etc. Use this for any interactive workflow: accepting " +
+			"cookies, dismissing popups, opening menus, submitting forms (alongside " +
+			"`browser_type`), pagination, etc. Resolve the target with either " +
+			"`ref` (from `browser_snapshot`, semantically stable across renders — " +
+			"PREFERRED) or `selector` (CSS, fragile if the site changes). Requires " +
+			"a `tabId` from `browser_navigate`. No interactive equivalent exists in " +
+			"`fetch_url` / `web_search` — this tool is only available via the bundled " +
+			"browser.",
 		parameters: Type.Object({
 			tabId: Type.String(),
 			ref: Type.Optional(Type.String()),
@@ -225,7 +262,13 @@ export default function browserExtension(pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "browser_type",
 		description:
-			"Type text into an element. Pass `ref` or `selector` to target a specific input; otherwise types into the currently focused element. Set `pressEnter: true` to submit a form.",
+			"Type text into an input or contenteditable on an open tab — search boxes, " +
+			"login forms, chat composers, etc. Target with `ref` (PREFERRED, from " +
+			"`browser_snapshot`) or `selector` (CSS). Without either, types into the " +
+			"currently focused element. Set `pressEnter: true` to submit a form / " +
+			"trigger a search. Combine with `browser_click` for full form workflows " +
+			"(click field → type → click submit). No equivalent in `fetch_url` or " +
+			"`web_search`.",
 		parameters: Type.Object({
 			tabId: Type.String(),
 			text: Type.String(),
@@ -245,7 +288,12 @@ export default function browserExtension(pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "browser_scroll",
 		description:
-			"Scroll the page (or a specific element by `ref`) by `pixels` in the given direction.",
+			"Scroll an open tab to reveal more content. Essential for infinite-scroll " +
+			"feeds (Twitter/X, Reddit, news sites, e-commerce listings), lazy-loaded " +
+			"images, and dropdowns inside scrollable containers. Defaults to scrolling " +
+			"the page; pass `ref` to scroll inside a specific element. After scrolling, " +
+			"re-run `browser_snapshot` or `browser_extract` to see the newly loaded " +
+			"content.",
 		parameters: Type.Object({
 			tabId: Type.String(),
 			direction: Type.Union([
@@ -268,7 +316,13 @@ export default function browserExtension(pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "browser_snapshot",
 		description:
-			"Return the accessibility tree for the current tab. Each node carries a `ref` that can be passed back to browser_click / browser_type / browser_scroll. Cheaper than parsing HTML.",
+			"Return the accessibility tree of the current tab — a structured outline of " +
+			"every interactive element (links, buttons, inputs, headings) with a stable " +
+			"`ref` you can pass back to `browser_click` / `browser_type` / " +
+			"`browser_scroll`. **Use this BEFORE clicking or typing** to discover the " +
+			"`ref` of the target element — much more reliable than guessing CSS " +
+			"selectors. Lighter and more semantic than raw HTML. " +
+			"Requires a `tabId` from `browser_navigate`.",
 		parameters: Type.Object({
 			tabId: Type.String(),
 		}),
@@ -282,7 +336,11 @@ export default function browserExtension(pi: ExtensionAPI) {
 	// ─── browser_close_tab ────────────────────────────────────────────
 	pi.registerTool({
 		name: "browser_close_tab",
-		description: "Close a single tab. The browser process stays warm.",
+		description:
+			"Close a single browser tab once you no longer need it. " +
+			"**Always call this at the end of a browsing workflow** to free memory — " +
+			"a Camoufox tab can hold 50-200 MB. The underlying Firefox process stays " +
+			"warm for the next `browser_navigate`, so this is cheap (no re-boot cost).",
 		parameters: Type.Object({
 			tabId: Type.String(),
 		}),
@@ -296,7 +354,11 @@ export default function browserExtension(pi: ExtensionAPI) {
 	// ─── browser_list_tabs ────────────────────────────────────────────
 	pi.registerTool({
 		name: "browser_list_tabs",
-		description: "List open tabs for the current user.",
+		description:
+			"List all open tabs in the current browser session with their URL, title, " +
+			"and `tabId`. Use this to recover a `tabId` if you lost track of which tab " +
+			"holds which page (e.g. across multi-step workflows that opened several " +
+			"tabs). Cheap — no Firefox interaction required.",
 		parameters: Type.Object({
 			userId: Type.Optional(Type.String()),
 		}),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@phi-code-admin/phi-code",
-	"version": "0.76.2",
+	"version": "0.76.4",
 	"description": "Coding agent CLI with persistent memory, sub-agents, intelligent routing, and orchestration",
 	"type": "module",
 	"piConfig": {
@@ -47,7 +47,7 @@
 	},
 	"dependencies": {
 		"@mariozechner/jiti": "^2.6.5",
-		"@phi-code-admin/browser": "^1.0.1",
+		"@phi-code-admin/browser": "^1.0.2",
 		"@silvia-odwyer/photon-node": "^0.3.4",
 		"chalk": "^5.5.0",
 		"cli-highlight": "^2.1.11",