pi-agent-browser-native 0.9.3 → 0.9.4

package/scripts/agent-browser-target.mjs

@@ -13,9 +13,13 @@ function stableVersionParts(version) {
 export function isSupportedAgentBrowserVersion(version) {
 	const actual = stableVersionParts(version);
 	const minimum = stableVersionParts(MINIMUM_AGENT_BROWSER_VERSION);
-	if (!actual || !minimum) return false;
+	if (!actual || !minimum) {
+		return false;
+	}
 	for (let index = 0; index < minimum.length; index += 1) {
-		if (actual[index] !== minimum[index]) return actual[index] > minimum[index];
+		if (actual[index] !== minimum[index]) {
+			return actual[index] > minimum[index];
+		}
 	}
 	return true;
 }

package/scripts/build.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 /**
  * Purpose: Produce the compiled runtime files that the published Pi package loads.
- * Responsibilities: Remove stale dist output, run TypeScript emit, and fail with clear build output.
+ * Responsibilities: Remove stale dist output, emit runtime assets, bundle the native entrypoint, and fail with clear build output.
  * Scope: Maintainer/package build only; runtime behavior remains in extensions/agent-browser TypeScript sources.
  * Usage: `npm run build` before package verification, lifecycle validation, and npm pack/publish.
- * Invariants/Assumptions: `node_modules` provides `typescript`; Termux supplies Android-native `tsgo` on PATH. `dist/` is generated output.
+ * Invariants/Assumptions: `node_modules` provides `typescript` and `esbuild`; Termux supplies Android-native `tsgo` on PATH. `dist/` is generated output.
  */
 
 import { execFile as execFileCallback } from "node:child_process";
@@ -12,14 +12,23 @@ import { rm } from "node:fs/promises";
 import { join } from "node:path";
 import process from "node:process";
 import { promisify } from "node:util";
+import { build } from "esbuild";
 
 const execFile = promisify(execFileCallback);
 const binSuffix = process.platform === "win32" ? ".cmd" : "";
 // TypeScript's npm binaries do not support Android; Termux supplies native tsgo.
-const tscPath = process.platform === "android" ? "tsgo" : join(process.cwd(), "node_modules", ".bin", `tsc${binSuffix}`);
+const tscPath =
+	process.platform === "android"
+		? "tsgo"
+		: join(process.cwd(), "node_modules", ".bin", `tsc${binSuffix}`);
 
 async function main() {
-	await rm(join(process.cwd(), "dist"), { force: true, maxRetries: 5, recursive: true, retryDelay: 100 });
+	await rm(join(process.cwd(), "dist"), {
+		force: true,
+		maxRetries: 5,
+		recursive: true,
+		retryDelay: 100,
+	});
 	const options = process.platform === "win32" ? { shell: true } : {};
 	try {
 		const { stderr, stdout } = await execFile(tscPath, ["-p", "tsconfig.build.json"], {
@@ -27,13 +36,33 @@ async function main() {
 			cwd: process.cwd(),
 			maxBuffer: 10 * 1024 * 1024,
 		});
-		if (stdout) process.stdout.write(stdout);
-		if (stderr) process.stderr.write(stderr);
+		if (stdout) {
+			process.stdout.write(stdout);
+		}
+		if (stderr) {
+			process.stderr.write(stderr);
+		}
 	} catch (error) {
-		if (error?.stdout) process.stdout.write(error.stdout);
-		if (error?.stderr) process.stderr.write(error.stderr);
+		if (error?.stdout) {
+			process.stdout.write(error.stdout);
+		}
+		if (error?.stderr) {
+			process.stderr.write(error.stderr);
+		}
 		throw error;
 	}
+	// Retain emitted workers and CLI modules; bundle the extension's reachable modules with package imports external.
+	const entrypoint = join(process.cwd(), "dist", "extensions", "agent-browser", "index.js");
+	await build({
+		allowOverwrite: true,
+		bundle: true,
+		entryPoints: [entrypoint],
+		format: "esm",
+		outfile: entrypoint,
+		packages: "external",
+		platform: "node",
+		target: "node24.21",
+	});
 }
 
 main().catch((error) => {

package/scripts/capability-core-commands.mjs

@@ -0,0 +1,193 @@
+/** Core page/element/navigation/extraction help and human-document tokens. */
+import { root, section } from "./capability-section.mjs";
+export const coreCommands = section(
+	"core-commands",
+	"Core page, element, navigation, and extraction commands",
+	[
+		"open [url]",
+		"open <url>",
+		"goto <url>",
+		"navigate <url>",
+		"read [url]",
+		"read <url> --raw",
+		"read <url> --require-md",
+		"read <url> --llms <index|full>",
+		"read <url> --outline",
+		"read <url> --filter <text>",
+		"read <url> --timeout <ms>",
+		"click <sel>",
+		"click <sel> --new-tab",
+		"dblclick <sel>",
+		"type <sel> <text>",
+		"fill <sel> <text>",
+		"press <key>",
+		"key <key>",
+		"keydown <key>",
+		"keyup <key>",
+		"keyboard type <text>",
+		"keyboard inserttext <text>",
+		"keydown Shift",
+		"keyup Shift",
+		"hover <sel>",
+		"focus <sel>",
+		"check <sel>",
+		"uncheck <sel>",
+		"select <sel> <val...>",
+		"drag <src> <dst>",
+		"upload <sel> <files...>",
+		"download <sel> <path>",
+		"scroll <dir> [px]",
+		"scroll <dir> [px] --selector <sel>",
+		"scrollintoview <sel>",
+		"scrollinto <sel>",
+		"wait <sel|ms>",
+		"wait --url <pattern>",
+		"wait --load <state>",
+		"wait --fn <expression>",
+		"wait --text <text>",
+		"wait --download [path]",
+		"screenshot [selector] [path]",
+		"screenshot [path]",
+		"screenshot --full",
+		"screenshot --annotate",
+		"screenshot --if-changed",
+		"screenshot --threshold <0-1>",
+		"snapshot --delta",
+		"snapshot --delta --full",
+		"click <sel> --human",
+		"drag <src> <dst> --human",
+		"mouse move <x> <y> --duration <ms> --steps <n> --human --seed <n>",
+		"pdf <path>",
+		"snapshot",
+		"snapshot --cursor",
+		"snapshot --interactive",
+		"snapshot --urls",
+		"snapshot --compact",
+		"snapshot --depth <n>",
+		"snapshot --selector <sel>",
+		"eval <js>",
+		"eval --stdin",
+		"eval -b <base64>",
+		"connect <port|url>",
+		"close [--all]",
+		"quit",
+		"exit",
+		"back",
+		"forward",
+		"reload",
+		"pushstate <url>",
+		"get <what> [selector]",
+		"get cdp-url",
+		"get box <selector>",
+		"get styles <selector>",
+		"is <what> <selector>",
+		"find <locator> <value> <action>",
+		"find first <sel>",
+		"find last <sel>",
+		"find nth <n> <sel>",
+		"find role <role> --name <name>",
+		"find role heading text --name",
+		"find ... --exact",
+		"mouse <action> [args]",
+		"set <setting> [value]",
+		"set media <features>",
+		"tap <selector>",
+		"swipe <direction> [distance]",
+	],
+	[
+		["open help", "open [url]"],
+		["open help", "aliases still require a URL."],
+		["open help", "agent-browser webmcp list"],
+		root("open <url>"),
+		root("read [url]"),
+		["read help", "read [url]"],
+		["read help", "--raw"],
+		["read help", "--require-md"],
+		["read help", "--llms <index|full>"],
+		["read help", "--outline"],
+		["read help", "--filter <text>"],
+		["read help", "--timeout <ms>"],
+		root("click <sel>"),
+		["click help", "--new-tab"],
+		root("dblclick <sel>"),
+		root("type <sel> <text>"),
+		root("fill <sel> <text>"),
+		root("press <key>"),
+		["key help", "Aliases: key"],
+		["keydown help", "keydown <key>"],
+		["keyup help", "keyup <key>"],
+		root("keyboard type <text>"),
+		root("keyboard inserttext <text>"),
+		root("hover <sel>"),
+		root("focus <sel>"),
+		root("check <sel>"),
+		root("uncheck <sel>"),
+		root("select <sel> <val...>"),
+		root("drag <src> <dst>"),
+		root("upload <sel> <files...>"),
+		root("download <sel> <path>"),
+		root("scroll <dir> [px]"),
+		["scroll help", "--selector <sel>"],
+		root("scrollintoview <sel>"),
+		["scrollinto help", "Aliases: scrollinto"],
+		root("wait <sel|ms>"),
+		["wait help", "--url <pattern>"],
+		["wait help", "--load <state>"],
+		["wait help", "--fn <expression>"],
+		["wait help", "--text <text>"],
+		["wait help", "--download [path]"],
+		root("screenshot [path]"),
+		["screenshot help", "screenshot [selector] [path]"],
+		root("pdf <path>"),
+		["pdf help", "Save page as PDF"],
+		root("snapshot"),
+		["snapshot help", "--interactive"],
+		["snapshot help", "--urls"],
+		["snapshot help", "--compact"],
+		["snapshot help", "--depth <n>"],
+		["snapshot help", "--selector <sel>"],
+		root("eval <js>"),
+		["eval help", "--stdin"],
+		["eval help", "-b, --base64"],
+		root("connect <port|url>"),
+		root("close [--all]"),
+		["close help", "Aliases: quit, exit"],
+		root("back"),
+		root("forward"),
+		root("reload"),
+		root("pushstate <url>"),
+		root("Get Info:  agent-browser get <what> [selector]"),
+		["get help", "box <selector>"],
+		["get help", "styles <selector>"],
+		["get help", "cdp-url"],
+		root("Check State:  agent-browser is <what> <selector>"),
+		root("Find Elements:  agent-browser find <locator> <value> <action> [text]"),
+		["find help", "first <selector>"],
+		["find help", "last <selector>"],
+		["find help", "nth <index> <selector>"],
+		["find help", "--name <name>"],
+		["find help", "--exact"],
+		["find help", "case-insensitive"],
+		["find help", "click, fill, check, hover, text"],
+		root("Mouse:  agent-browser mouse <action> [args]"),
+		root("Browser Settings:  agent-browser set <setting> [value]"),
+		["set help", "media [dark|light]"],
+		["keyboard help", "type <text>"],
+		["keyboard help", "inserttext <text>"],
+		["screenshot help", "--full, -f"],
+		["screenshot help", "--annotate"],
+		["screenshot help", "--if-changed"],
+		["screenshot help", "--threshold <0-1>"],
+		["snapshot help", "--delta"],
+		["snapshot help", "--full"],
+		["click help", "--human"],
+		["drag help", "--human"],
+		["mouse help", "--duration <ms>"],
+		["mouse help", "--steps <n>"],
+		["mouse help", "--seed <n>"],
+		["find help", "role <role>"],
+		["find help", "testid <id>"],
+		["tap help", "tap <selector>"],
+		["swipe help", "swipe <direction> [distance]"],
+	],
+);

package/scripts/capability-options.mjs

@@ -0,0 +1,283 @@
+/** Global native flags, launch configuration, provider, policy, and environment inventory. */
+import { root, section } from "./capability-section.mjs";
+export const optionsAndEnv = section(
+	"options-and-env",
+	"Global flags, config, providers, policy, and environment",
+	[
+		"--profile <name|path>",
+		"AGENT_BROWSER_PROFILE",
+		"--session <name>",
+		"AGENT_BROWSER_SESSION",
+		"--namespace <name>",
+		"AGENT_BROWSER_NAMESPACE",
+		"--restore [name]",
+		"AGENT_BROWSER_RESTORE",
+		"--restore-save <policy>",
+		"AGENT_BROWSER_RESTORE_SAVE",
+		"--restore-check-url <glob>",
+		"AGENT_BROWSER_RESTORE_CHECK_URL",
+		"--restore-check-text <txt>",
+		"AGENT_BROWSER_RESTORE_CHECK_TEXT",
+		"--restore-check-fn <js>",
+		"AGENT_BROWSER_RESTORE_CHECK_FN",
+		"--session-name <name>",
+		"AGENT_BROWSER_SESSION_NAME",
+		"--state <path>",
+		"AGENT_BROWSER_STATE",
+		"--auto-connect",
+		"AGENT_BROWSER_AUTO_CONNECT",
+		"--pin-tab",
+		"--no-pin-tab",
+		"AGENT_BROWSER_PIN_TAB",
+		"--headers <json>",
+		"--init-script <path>",
+		"AGENT_BROWSER_INIT_SCRIPTS",
+		"--enable <feature>",
+		"AGENT_BROWSER_ENABLE",
+		"--executable-path <path>",
+		"AGENT_BROWSER_EXECUTABLE_PATH",
+		"--extension <path>",
+		"AGENT_BROWSER_EXTENSIONS",
+		"--args <args>",
+		"AGENT_BROWSER_ARGS",
+		"--user-agent <ua>",
+		"AGENT_BROWSER_USER_AGENT",
+		"--proxy <server>",
+		"AGENT_BROWSER_PROXY",
+		"HTTP_PROXY",
+		"HTTPS_PROXY",
+		"ALL_PROXY",
+		"--proxy-bypass <hosts>",
+		"AGENT_BROWSER_PROXY_BYPASS",
+		"NO_PROXY",
+		"--ignore-https-errors",
+		"AGENT_BROWSER_IGNORE_HTTPS_ERRORS",
+		"--ca-cert <path>",
+		"--no-ca-cert",
+		"AGENT_BROWSER_CA_CERT",
+		"AGENT_BROWSER_CLEAR_CA_CERT",
+		"--allow-file-access",
+		"AGENT_BROWSER_ALLOW_FILE_ACCESS",
+		"--hide-scrollbars <bool>",
+		"--headed",
+		"AGENT_BROWSER_HEADED",
+		"--webgpu",
+		"AGENT_BROWSER_WEBGPU",
+		"--no-webmcp",
+		"AGENT_BROWSER_NO_WEBMCP",
+		"noWebmcp",
+		"AGENT_BROWSER_NO_XVFB",
+		'"webgpu": true',
+		"--cdp <port|url>",
+		"--color-scheme <scheme>",
+		"AGENT_BROWSER_COLOR_SCHEME",
+		"--download-path <path>",
+		"AGENT_BROWSER_DOWNLOAD_PATH",
+		"--engine <name>",
+		"AGENT_BROWSER_ENGINE",
+		"--input-mode <mode>",
+		"--no-auto-dialog",
+		"AGENT_BROWSER_NO_AUTO_DIALOG",
+		"--json",
+		"AGENT_BROWSER_JSON",
+		"--annotate",
+		"AGENT_BROWSER_ANNOTATE",
+		"--screenshot-dir <path>",
+		"AGENT_BROWSER_SCREENSHOT_DIR",
+		"--screenshot-quality <n>",
+		"AGENT_BROWSER_SCREENSHOT_QUALITY",
+		"--screenshot-format <fmt>",
+		"AGENT_BROWSER_SCREENSHOT_FORMAT",
+		"--content-boundaries",
+		"AGENT_BROWSER_CONTENT_BOUNDARIES",
+		"--max-output <chars>",
+		"AGENT_BROWSER_MAX_OUTPUT",
+		"--allowed-domains <list>",
+		"AGENT_BROWSER_ALLOWED_DOMAINS",
+		"--action-policy <path>",
+		"AGENT_BROWSER_ACTION_POLICY",
+		"--confirm-actions <list>",
+		"AGENT_BROWSER_CONFIRM_ACTIONS",
+		"--confirm-interactive",
+		"AGENT_BROWSER_CONFIRM_INTERACTIVE",
+		"-p, --provider <name>",
+		"AGENT_BROWSER_PROVIDER",
+		"AGENT_BROWSER_PLUGINS",
+		"browserbase",
+		"kernel",
+		"browseruse",
+		"browserless",
+		"agentcore",
+		"--device <name>",
+		"AGENT_BROWSER_IOS_DEVICE",
+		"agent-browser -p ios device list",
+		"agent-browser -p ios swipe up",
+		"agent-browser -p ios tap @e1",
+		"--model <name>",
+		"AI_GATEWAY_MODEL",
+		"-v, --verbose",
+		"-q, --quiet",
+		"--debug",
+		"AGENT_BROWSER_DEBUG",
+		"AGENT_BROWSER_CONFIG",
+		"AGENT_BROWSER_DEFAULT_TIMEOUT",
+		"--idle-timeout <ms>",
+		"AGENT_BROWSER_AUTOSAVE_INTERVAL_MS",
+		"AGENT_BROWSER_STREAM_PORT",
+		"AGENT_BROWSER_STREAM_QUALITY",
+		"AGENT_BROWSER_STREAM_MAX_WIDTH",
+		"AGENT_BROWSER_STREAM_MAX_HEIGHT",
+		"AGENT_BROWSER_IDLE_TIMEOUT_MS",
+		"AGENT_BROWSER_ENCRYPTION_KEY",
+		"AGENT_BROWSER_STATE_EXPIRE_DAYS",
+		"AGENT_BROWSER_IOS_UDID",
+		"AI_GATEWAY_URL",
+		"AI_GATEWAY_API_KEY",
+		"BROWSERBASE_API_KEY",
+		"BROWSERBASE_PROJECT_ID",
+		"BROWSERLESS_API_KEY",
+		"BROWSERLESS_API_URL",
+		"BROWSERLESS_BROWSER_TYPE",
+		"BROWSERLESS_STEALTH",
+		"BROWSERLESS_TTL",
+		"BROWSER_USE_API_KEY",
+		"KERNEL_API_KEY",
+		"KERNEL_HEADLESS",
+		"KERNEL_STEALTH",
+		"KERNEL_TIMEOUT_SECONDS",
+		"KERNEL_PROFILE_NAME",
+		"AGENTCORE_API_KEY",
+		"AGENTCORE_REGION",
+		"AGENTCORE_BROWSER_ID",
+		"AGENTCORE_PROFILE_ID",
+		"AGENTCORE_SESSION_TIMEOUT",
+		"AWS_PROFILE",
+		"AWS_ACCESS_KEY_ID",
+		"AWS_SECRET_ACCESS_KEY",
+		"AWS_SESSION_TOKEN",
+		"AWS_REGION",
+		"AWS_DEFAULT_REGION",
+	],
+	[
+		root("--profile <name|path>"),
+		root("AGENT_BROWSER_PROFILE"),
+		root("--session <name>"),
+		root("AGENT_BROWSER_SESSION"),
+		root("--namespace <name>"),
+		root("AGENT_BROWSER_NAMESPACE"),
+		root("--restore [name]"),
+		root("AGENT_BROWSER_RESTORE"),
+		root("--restore-save <policy>"),
+		root("AGENT_BROWSER_RESTORE_SAVE"),
+		root("--restore-check-url <glob>"),
+		root("AGENT_BROWSER_RESTORE_CHECK_URL"),
+		root("--restore-check-text <txt>"),
+		root("AGENT_BROWSER_RESTORE_CHECK_TEXT"),
+		root("--restore-check-fn <js>"),
+		root("AGENT_BROWSER_RESTORE_CHECK_FN"),
+		root("--session-name <name>"),
+		root("AGENT_BROWSER_SESSION_NAME"),
+		root("--state <path>"),
+		root("AGENT_BROWSER_STATE"),
+		root("--auto-connect"),
+		root("AGENT_BROWSER_AUTO_CONNECT"),
+		root("--pin-tab"),
+		root("--no-pin-tab"),
+		root("AGENT_BROWSER_PIN_TAB"),
+		root("--headers <json>"),
+		root("--init-script <path>"),
+		root("AGENT_BROWSER_INIT_SCRIPTS"),
+		root("--enable <feature>"),
+		root("AGENT_BROWSER_ENABLE"),
+		root("--executable-path <path>"),
+		root("AGENT_BROWSER_EXECUTABLE_PATH"),
+		root("--extension <path>"),
+		root("AGENT_BROWSER_EXTENSIONS"),
+		root("--args <args>"),
+		root("AGENT_BROWSER_ARGS"),
+		root("--user-agent <ua>"),
+		root("AGENT_BROWSER_USER_AGENT"),
+		root("--proxy <server>"),
+		root("AGENT_BROWSER_PROXY"),
+		root("HTTP_PROXY / HTTPS_PROXY"),
+		root("ALL_PROXY"),
+		root("--proxy-bypass <hosts>"),
+		root("AGENT_BROWSER_PROXY_BYPASS"),
+		root("NO_PROXY"),
+		root("--ignore-https-errors"),
+		root("AGENT_BROWSER_IGNORE_HTTPS_ERRORS"),
+		root("--ca-cert <path>"),
+		root("--no-ca-cert"),
+		root("AGENT_BROWSER_CA_CERT"),
+		root("AGENT_BROWSER_CLEAR_CA_CERT"),
+		root("--allow-file-access"),
+		root("AGENT_BROWSER_ALLOW_FILE_ACCESS"),
+		root("--hide-scrollbars <bool>"),
+		root("--headed"),
+		root("AGENT_BROWSER_HEADED"),
+		root("--webgpu"),
+		root("AGENT_BROWSER_WEBGPU"),
+		root("--no-webmcp"),
+		root("AGENT_BROWSER_NO_WEBMCP"),
+		root("--cdp <port|url>"),
+		root("--color-scheme <scheme>"),
+		root("AGENT_BROWSER_COLOR_SCHEME"),
+		root("--download-path <path>"),
+		root("AGENT_BROWSER_DOWNLOAD_PATH"),
+		root("--engine <name>"),
+		root("AGENT_BROWSER_ENGINE"),
+		root("--input-mode <mode>"),
+		root("--no-auto-dialog"),
+		root("AGENT_BROWSER_NO_AUTO_DIALOG"),
+		root("--json"),
+		root("AGENT_BROWSER_JSON"),
+		root("--annotate"),
+		root("AGENT_BROWSER_ANNOTATE"),
+		root("--screenshot-dir <path>"),
+		root("AGENT_BROWSER_SCREENSHOT_DIR"),
+		root("--screenshot-quality <n>"),
+		root("AGENT_BROWSER_SCREENSHOT_QUALITY"),
+		root("--screenshot-format <fmt>"),
+		root("AGENT_BROWSER_SCREENSHOT_FORMAT"),
+		root("--content-boundaries"),
+		root("AGENT_BROWSER_CONTENT_BOUNDARIES"),
+		root("--max-output <chars>"),
+		root("AGENT_BROWSER_MAX_OUTPUT"),
+		root("--allowed-domains <list>"),
+		root("AGENT_BROWSER_ALLOWED_DOMAINS"),
+		root("--action-policy <path>"),
+		root("AGENT_BROWSER_ACTION_POLICY"),
+		root("--confirm-actions <list>"),
+		root("AGENT_BROWSER_CONFIRM_ACTIONS"),
+		root("--confirm-interactive"),
+		root("AGENT_BROWSER_CONFIRM_INTERACTIVE"),
+		root("--provider <name>"),
+		root("AGENT_BROWSER_PROVIDER"),
+		root("AGENT_BROWSER_PLUGINS"),
+		root("agent-browser -p ios device list"),
+		root("agent-browser -p ios swipe up"),
+		root("agent-browser -p ios tap @e1"),
+		root("--device <name>"),
+		root("AGENT_BROWSER_IOS_DEVICE"),
+		root("--model <name>"),
+		root("AI_GATEWAY_MODEL"),
+		root("--verbose"),
+		root("--quiet"),
+		root("--debug"),
+		root("AGENT_BROWSER_DEBUG"),
+		root("--config <path>"),
+		root("AGENT_BROWSER_CONFIG"),
+		root("AGENT_BROWSER_DEFAULT_TIMEOUT"),
+		root("AGENT_BROWSER_AUTOSAVE_INTERVAL_MS"),
+		root("AGENT_BROWSER_STREAM_PORT"),
+		root("AGENT_BROWSER_STREAM_QUALITY"),
+		root("AGENT_BROWSER_STREAM_MAX_WIDTH"),
+		root("AGENT_BROWSER_STREAM_MAX_HEIGHT"),
+		root("AGENT_BROWSER_IDLE_TIMEOUT_MS"),
+		root("AGENT_BROWSER_ENCRYPTION_KEY"),
+		root("AGENT_BROWSER_STATE_EXPIRE_DAYS"),
+		root("AGENT_BROWSER_IOS_UDID"),
+		root("AI_GATEWAY_URL"),
+		root("AI_GATEWAY_API_KEY"),
+	],
+);