pi-agent-browser-native 0.2.39 → 0.2.40

package/extensions/agent-browser/lib/web-search.ts

@@ -0,0 +1,352 @@
+/**
+ * Purpose: Provide the optional Brave-backed `agent_browser_web_search` companion tool.
+ * Responsibilities: Define strict search input schema, resolve the configured Brave credential lazily, call Brave Search with cancellation/timeout, normalize compact results, and keep secrets out of content/details.
+ * Scope: Live web search only; browser automation remains in the `agent_browser` tool.
+ */
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { resolveBraveApiKey, type AgentBrowserConfigState } from "./config.js";
+
+export const AGENT_BROWSER_WEB_SEARCH_TOOL_NAME = "agent_browser_web_search";
+export const BRAVE_SEARCH_ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
+export const DEFAULT_SEARCH_RESULT_COUNT = 5;
+export const MAX_SEARCH_RESULT_COUNT = 10;
+export const SEARCH_REQUEST_TIMEOUT_MS = 15_000;
+
+export type BraveWebSearchResult = {
+	title?: unknown;
+	url?: unknown;
+	description?: unknown;
+	age?: unknown;
+	language?: unknown;
+	profile?: {
+		name?: unknown;
+		url?: unknown;
+	};
+	meta_url?: {
+		hostname?: unknown;
+	};
+};
+
+export type BraveWebSearchResponse = {
+	query?: {
+		original?: unknown;
+		altered?: unknown;
+	};
+	web?: {
+		results?: BraveWebSearchResult[];
+	};
+};
+
+export type NormalizedSearchResult = {
+	title: string;
+	url: string;
+	description?: string;
+	source?: string;
+	age?: string;
+	language?: string;
+};
+
+export const AgentBrowserWebSearchParams = Type.Object(
+	{
+		query: Type.String({
+			minLength: 1,
+			description: "Search query to run with Brave Search.",
+		}),
+		count: Type.Optional(
+			Type.Integer({
+				minimum: 1,
+				maximum: MAX_SEARCH_RESULT_COUNT,
+				description: `Number of web results to return. Defaults to ${DEFAULT_SEARCH_RESULT_COUNT}; max ${MAX_SEARCH_RESULT_COUNT}.`,
+			}),
+		),
+		offset: Type.Optional(
+			Type.Integer({
+				minimum: 0,
+				maximum: 9,
+				description: "Zero-based result offset for pagination. Defaults to 0.",
+			}),
+		),
+		country: Type.Optional(
+			Type.String({
+				pattern: "^[A-Za-z]{2}$",
+				description: "Optional 2-letter country code, such as US or GB.",
+			}),
+		),
+		searchLang: Type.Optional(
+			Type.String({
+				minLength: 2,
+				maxLength: 8,
+				description: "Optional search language code, such as en or en-US.",
+			}),
+		),
+		safesearch: Type.Optional(
+			StringEnum(["off", "moderate", "strict"] as const, {
+				description: "Optional Brave safe-search setting. Defaults to Brave's API default.",
+			}),
+		),
+		freshness: Type.Optional(
+			StringEnum(["pd", "pw", "pm", "py"] as const, {
+				description: "Optional freshness window: pd=past day, pw=past week, pm=past month, py=past year.",
+			}),
+		),
+	},
+	{ additionalProperties: false },
+);
+
+const HTML_ENTITY_REPLACEMENTS: Readonly<Record<string, string>> = {
+	amp: "&",
+	apos: "'",
+	gt: ">",
+	lt: "<",
+	nbsp: " ",
+	quot: '"',
+};
+
+const HTML_TAG_NAMES_TO_STRIP = new Set([
+	"a",
+	"abbr",
+	"address",
+	"article",
+	"aside",
+	"audio",
+	"b",
+	"base",
+	"blockquote",
+	"body",
+	"br",
+	"button",
+	"canvas",
+	"code",
+	"div",
+	"em",
+	"embed",
+	"footer",
+	"form",
+	"h1",
+	"h2",
+	"h3",
+	"h4",
+	"h5",
+	"h6",
+	"head",
+	"header",
+	"html",
+	"i",
+	"iframe",
+	"img",
+	"input",
+	"li",
+	"link",
+	"main",
+	"mark",
+	"math",
+	"meta",
+	"nav",
+	"object",
+	"ol",
+	"option",
+	"p",
+	"pre",
+	"script",
+	"section",
+	"select",
+	"source",
+	"span",
+	"strong",
+	"style",
+	"svg",
+	"table",
+	"tbody",
+	"td",
+	"textarea",
+	"tfoot",
+	"th",
+	"thead",
+	"tr",
+	"u",
+	"ul",
+	"video",
+]);
+
+function decodeHtmlEntity(entity: string): string {
+	const named = HTML_ENTITY_REPLACEMENTS[entity.toLowerCase()];
+	if (named !== undefined) return named;
+	const decimalMatch = /^#(\d+)$/.exec(entity);
+	const hexMatch = /^#x([0-9a-f]+)$/i.exec(entity);
+	const codePoint = decimalMatch ? Number.parseInt(decimalMatch[1] ?? "", 10) : hexMatch ? Number.parseInt(hexMatch[1] ?? "", 16) : undefined;
+	if (codePoint === undefined || !Number.isFinite(codePoint)) return `&${entity};`;
+	try {
+		return String.fromCodePoint(codePoint);
+	} catch {
+		return `&${entity};`;
+	}
+}
+
+export function decodeHtmlEntities(value: string): string {
+	return value.replace(/&([a-z][a-z0-9]+|#\d+|#x[0-9a-f]+);/gi, (_match, entity: string) => decodeHtmlEntity(entity));
+}
+
+function stripDecodedHtmlTags(value: string): string {
+	return value.replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1>/gi, " ").replace(/<\/?([a-z][a-z0-9-]*)(\s[^>]*)?>/gi, (match, tagName: string, attributes: string | undefined) => {
+		if (attributes || match.startsWith("</") || HTML_TAG_NAMES_TO_STRIP.has(tagName.toLowerCase())) return " ";
+		return match;
+	});
+}
+
+export function cleanSearchText(value: unknown, maxLength = 500): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const cleaned = stripDecodedHtmlTags(decodeHtmlEntities(value.replace(/<[^>]*>/g, " ")))
+		.replace(/\s+/g, " ")
+		.trim();
+	if (!cleaned) return undefined;
+	if (cleaned.length <= maxLength) return cleaned;
+	return `${cleaned.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
+}
+
+export function normalizeSearchUrl(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	try {
+		const url = new URL(value);
+		if (url.protocol !== "http:" && url.protocol !== "https:") return undefined;
+		return url.toString();
+	} catch {
+		return undefined;
+	}
+}
+
+export function normalizeSearchResult(result: BraveWebSearchResult): NormalizedSearchResult | undefined {
+	const title = cleanSearchText(result.title, 180);
+	const url = normalizeSearchUrl(result.url);
+	if (!title || !url) return undefined;
+	return {
+		title,
+		url,
+		description: cleanSearchText(result.description, 320),
+		source: cleanSearchText(result.profile?.name, 120) ?? cleanSearchText(result.meta_url?.hostname, 120),
+		age: cleanSearchText(result.age, 80),
+		language: cleanSearchText(result.language, 40),
+	};
+}
+
+export function formatSearchResults(query: string, results: NormalizedSearchResult[]): string {
+	if (results.length === 0) {
+		return `No Brave web results found for: ${query}`;
+	}
+	const lines = [`Brave web search results for: ${query}`, ""];
+	results.forEach((result, index) => {
+		lines.push(`${index + 1}. ${result.title}`);
+		lines.push(`   URL: ${result.url}`);
+		if (result.source) lines.push(`   Source: ${result.source}`);
+		if (result.age) lines.push(`   Age: ${result.age}`);
+		if (result.description) lines.push(`   Summary: ${result.description}`);
+		lines.push("");
+	});
+	return lines.join("\n").trimEnd();
+}
+
+export function buildBraveSearchUrl(params: {
+	query: string;
+	count: number;
+	offset: number;
+	country?: string;
+	searchLang?: string;
+	safesearch?: "off" | "moderate" | "strict";
+	freshness?: "pd" | "pw" | "pm" | "py";
+}): URL {
+	const url = new URL(BRAVE_SEARCH_ENDPOINT);
+	url.searchParams.set("q", params.query);
+	url.searchParams.set("count", String(params.count));
+	url.searchParams.set("offset", String(params.offset));
+	if (params.country) url.searchParams.set("country", params.country.toUpperCase());
+	if (params.searchLang) url.searchParams.set("search_lang", params.searchLang);
+	if (params.safesearch) url.searchParams.set("safesearch", params.safesearch);
+	if (params.freshness) url.searchParams.set("freshness", params.freshness);
+	return url;
+}
+
+function redactSearchSecret(text: string, apiKey: string): string {
+	return apiKey ? text.split(apiKey).join("[REDACTED]") : text;
+}
+
+export async function fetchBraveSearchJson(url: URL, apiKey: string, signal?: AbortSignal): Promise<BraveWebSearchResponse> {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(new Error("Brave search timed out")), SEARCH_REQUEST_TIMEOUT_MS);
+	const abort = () => controller.abort(signal?.reason ?? new Error("Brave search cancelled"));
+	signal?.addEventListener("abort", abort, { once: true });
+	try {
+		const response = await fetch(url, {
+			headers: {
+				Accept: "application/json",
+				"X-Subscription-Token": apiKey,
+			},
+			signal: controller.signal,
+		});
+		const text = await response.text();
+		if (!response.ok) {
+			const errorPreview = cleanSearchText(redactSearchSecret(text, apiKey), 300);
+			throw new Error(`Brave search failed with HTTP ${response.status}: ${errorPreview ? redactSearchSecret(errorPreview, apiKey) : response.statusText}`);
+		}
+		try {
+			return JSON.parse(text) as BraveWebSearchResponse;
+		} catch (error) {
+			throw new Error(`Brave search returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	} finally {
+		clearTimeout(timeout);
+		signal?.removeEventListener("abort", abort);
+	}
+}
+
+export function createAgentBrowserWebSearchTool(configState: AgentBrowserConfigState) {
+	return defineTool({
+		name: AGENT_BROWSER_WEB_SEARCH_TOOL_NAME,
+		label: "Agent Browser Web Search",
+		description: `Search the web with Brave Search when configured. Returns up to ${MAX_SEARCH_RESULT_COUNT} concise web results.`,
+		promptSnippet: "Search the live web with Brave Search for current or external web 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.",
+			"Prefer agent_browser_web_search over opening a search engine results page with agent_browser when a quick result list is enough.",
+			"After using agent_browser_web_search, cite result URLs in the final answer when web evidence informed the answer.",
+		],
+		parameters: AgentBrowserWebSearchParams,
+		async execute(_toolCallId, params, signal) {
+			const resolvedCredential = await resolveBraveApiKey(configState, { signal });
+			if (!resolvedCredential) {
+				throw new Error("Brave Search credential source is configured but did not resolve. Run pi-agent-browser-config web-search status for setup details.");
+			}
+			const query = params.query.trim();
+			if (!query) throw new Error("query must not be blank");
+			const count = Math.min(Math.max(params.count ?? DEFAULT_SEARCH_RESULT_COUNT, 1), MAX_SEARCH_RESULT_COUNT);
+			const offset = Math.max(params.offset ?? 0, 0);
+			const url = buildBraveSearchUrl({
+				query,
+				count,
+				offset,
+				country: params.country,
+				searchLang: params.searchLang,
+				safesearch: params.safesearch,
+				freshness: params.freshness,
+			});
+			const data = await fetchBraveSearchJson(url, resolvedCredential.value, signal);
+			const results = (data.web?.results ?? [])
+				.map(normalizeSearchResult)
+				.filter((result): result is NormalizedSearchResult => Boolean(result));
+			const returnedQuery = cleanSearchText(data.query?.altered, 300) ?? cleanSearchText(data.query?.original, 300) ?? query;
+			return {
+				content: [{ type: "text", text: formatSearchResults(returnedQuery, results) }],
+				details: {
+					provider: "brave",
+					query,
+					returnedQuery,
+					count,
+					offset,
+					fetchedAt: new Date().toISOString(),
+					results,
+				},
+			};
+		},
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.2.39",
+  "version": "0.2.40",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
@@ -27,11 +27,13 @@
     "node": ">=22.19.0"
   },
   "bin": {
+    "pi-agent-browser-config": "scripts/config.mjs",
     "pi-agent-browser-doctor": "scripts/doctor.mjs"
   },
   "files": [
     "extensions",
     "platform-smoke.config.mjs",
+    "scripts/config.mjs",
     "scripts/doctor.mjs",
     "scripts/agent-browser-capability-baseline.mjs",
     "scripts/platform-smoke.mjs",

package/scripts/config.mjs

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+/**
+ * Purpose: Manage pi-agent-browser-native package config under Pi-scoped config paths.
+ * Responsibilities: Print config paths/status, write redacted web-search and browser profile settings, preserve safe permissions, and avoid echoing secrets.
+ * Scope: Maintainer/user setup CLI only; extension runtime validation and tool execution live under extensions/agent-browser/lib/.
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import process from "node:process";
+
+const CONFIG_ENV = "PI_AGENT_BROWSER_CONFIG";
+const BRAVE_API_KEY_ENV = "BRAVE_API_KEY";
+const RELATIVE_CONFIG = [".pi", "config", "pi-agent-browser-native", "config.json"];
+const DEFAULT_CONFIG = { version: 1 };
+
+class UsageError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "UsageError";
+	}
+}
+
+function usage() {
+	return `pi-agent-browser-config
+
+Usage:
+  pi-agent-browser-config paths
+  pi-agent-browser-config show
+  pi-agent-browser-config web-search status
+  pi-agent-browser-config web-search set-key --stdin [--global]
+  pi-agent-browser-config web-search set-env <ENV_VAR> [--global|--project]
+  pi-agent-browser-config web-search set-command <command> [--global]
+  pi-agent-browser-config web-search clear [--global|--project]
+  pi-agent-browser-config browser profile status
+  pi-agent-browser-config browser profile set <name> [--policy explicit-only|authenticated-only|always] [--global|--project]
+  pi-agent-browser-config browser profile clear [--global|--project]
+
+Notes:
+  Global config:  ~/.pi/config/pi-agent-browser-native/config.json
+  Project config: .pi/config/pi-agent-browser-native/config.json
+  Override:       PI_AGENT_BROWSER_CONFIG=/path/to/config.json
+  Project-local plaintext, interpolation-literal, malformed, and command-backed web-search keys are refused; use exact set-env references there.
+`;
+}
+
+function getHome(env = process.env) {
+	return env.HOME?.trim() || env.USERPROFILE?.trim();
+}
+
+function getGlobalConfigPath(env = process.env) {
+	const home = getHome(env);
+	if (!home) throw new Error("Could not resolve home directory for global config.");
+	return resolve(home, ...RELATIVE_CONFIG);
+}
+
+function getProjectConfigPath(cwd = process.cwd()) {
+	return resolve(cwd, ...RELATIVE_CONFIG);
+}
+
+function getPaths(env = process.env, cwd = process.cwd()) {
+	const override = env[CONFIG_ENV]?.trim();
+	return {
+		global: getGlobalConfigPath(env),
+		project: getProjectConfigPath(cwd),
+		override: override ? resolve(override) : undefined,
+	};
+}
+
+function parseArgs(argv) {
+	const positional = [];
+	const flags = new Map();
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (!arg.startsWith("--")) {
+			positional.push(arg);
+			continue;
+		}
+		if (arg === "--global" || arg === "--project" || arg === "--stdin" || arg === "--help") {
+			flags.set(arg, true);
+			continue;
+		}
+		if (arg === "--policy") {
+			const value = argv[index + 1];
+			if (!value || value.startsWith("--")) throw new UsageError("--policy requires a value.");
+			flags.set(arg, value);
+			index += 1;
+			continue;
+		}
+		throw new UsageError(`Unknown option: ${arg}`);
+	}
+	if (flags.get("--global") && flags.get("--project")) throw new UsageError("Use only one of --global or --project.");
+	return { flags, positional };
+}
+
+function readConfig(path) {
+	if (!existsSync(path)) return { ...DEFAULT_CONFIG };
+	const parsed = JSON.parse(readFileSync(path, "utf8"));
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`${path} must contain a JSON object.`);
+	return { ...DEFAULT_CONFIG, ...parsed };
+}
+
+function writeConfig(path, config) {
+	mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+	writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+	try {
+		chmodSync(dirname(path), 0o700);
+		chmodSync(path, 0o600);
+	} catch {
+		// Best effort on platforms/filesystems that do not support POSIX modes.
+	}
+}
+
+function selectWritePath(flags) {
+	const paths = getPaths();
+	if (flags.get("--project")) return { path: paths.project, scope: "project" };
+	return { path: paths.global, scope: "global" };
+}
+
+function classifyCredential(rawValue) {
+	const trimmed = String(rawValue ?? "").trim();
+	if (!trimmed) return "not configured";
+	if (trimmed.startsWith("!")) return "configured via command";
+	if (trimmed.includes("$")) return "configured via environment interpolation";
+	return "configured as plaintext [redacted]";
+}
+
+function mergeConfig() {
+	const paths = getPaths();
+	const layers = [];
+	for (const [scope, path] of [["global", paths.global], ["project", paths.project], ...(paths.override ? [["override", paths.override]] : [])]) {
+		if (!existsSync(path)) continue;
+		layers.push({ scope, path, config: readConfig(path) });
+	}
+	const merged = layers.reduce((current, layer) => ({
+		...current,
+		...layer.config,
+		browser: { ...(current.browser ?? {}), ...(layer.config.browser ?? {}) },
+		webSearch: { ...(current.webSearch ?? {}), ...(layer.config.webSearch ?? {}) },
+	}), { ...DEFAULT_CONFIG });
+	return { layers, merged, paths };
+}
+
+function printPaths() {
+	const paths = getPaths();
+	console.log(`Global: ${paths.global}`);
+	console.log(`Project: ${paths.project}`);
+	console.log(`Override: ${paths.override ?? `${CONFIG_ENV} not set`}`);
+}
+
+function printStatus() {
+	const { layers, merged, paths } = mergeConfig();
+	printPaths();
+	console.log("");
+	console.log("Config files:");
+	for (const [scope, path] of [["global", paths.global], ["project", paths.project], ...(paths.override ? [["override", paths.override]] : [])]) {
+		console.log(`  ${scope}: ${path} ${existsSync(path) ? "[exists]" : "[missing]"}`);
+	}
+	console.log("");
+	console.log("Effective config:");
+	const source = merged.webSearch?.braveApiKey;
+	console.log(`  webSearch.braveApiKey: ${source ? classifyCredential(source) : process.env[BRAVE_API_KEY_ENV]?.trim() ? `configured via ${BRAVE_API_KEY_ENV} environment fallback` : "not configured"}`);
+	const profile = merged.browser?.defaultProfile;
+	console.log(`  browser.defaultProfile: ${profile?.name ? `${profile.name} (policy: ${profile.policy ?? "authenticated-only"})` : "not configured"}`);
+	if (layers.length === 0) console.log("  layers: none");
+}
+
+async function readSecretFromStdin(useStdin) {
+	if (!useStdin) throw new UsageError("set-key requires --stdin so the key is not passed through argv or an echoed prompt.");
+	let input = "";
+	for await (const chunk of process.stdin) input += chunk;
+	const value = input.trim();
+	if (!value) throw new UsageError("No key was provided on stdin.");
+	return value;
+}
+
+function mutateConfig(path, mutate) {
+	const config = readConfig(path);
+	mutate(config);
+	writeConfig(path, config);
+}
+
+async function handleWebSearch(args, flags) {
+	const action = args[0];
+	if (action === "status") {
+		printStatus();
+		return;
+	}
+	if (action === "set-key") {
+		if (flags.get("--project")) throw new UsageError("Plaintext Brave keys cannot be written to project-local config. Use set-env or set-command.");
+		const key = await readSecretFromStdin(Boolean(flags.get("--stdin")));
+		const { path } = selectWritePath(flags);
+		mutateConfig(path, (config) => {
+			config.webSearch = { ...(config.webSearch ?? {}), braveApiKey: key };
+		});
+		console.log(`Saved Brave Search key to global config: ${path}`);
+		return;
+	}
+	if (action === "set-env") {
+		const envName = args[1];
+		if (!envName || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(envName)) throw new UsageError("set-env requires a valid environment variable name.");
+		const { path, scope } = selectWritePath(flags);
+		mutateConfig(path, (config) => {
+			config.webSearch = { ...(config.webSearch ?? {}), braveApiKey: `$${envName}` };
+		});
+		console.log(`Saved Brave Search ${scope} env reference to: ${path}`);
+		return;
+	}
+	if (action === "set-command") {
+		if (flags.get("--project")) throw new UsageError("Command-backed Brave keys cannot be written to project-local config. Use set-env there.");
+		const command = args.slice(1).join(" ").trim();
+		if (!command) throw new UsageError("set-command requires a command string.");
+		const { path, scope } = selectWritePath(flags);
+		mutateConfig(path, (config) => {
+			config.webSearch = { ...(config.webSearch ?? {}), braveApiKey: `!${command}` };
+		});
+		console.log(`Saved Brave Search ${scope} command source to: ${path}`);
+		return;
+	}
+	if (action === "clear") {
+		const { path, scope } = selectWritePath(flags);
+		mutateConfig(path, (config) => {
+			if (config.webSearch) delete config.webSearch.braveApiKey;
+		});
+		console.log(`Cleared Brave Search credential source in ${scope} config: ${path}`);
+		return;
+	}
+	throw new UsageError(`Unsupported web-search action: ${action ?? ""}`);
+}
+
+function handleBrowser(args, flags) {
+	if (args[0] !== "profile") throw new UsageError(`Unsupported browser action: ${args[0] ?? ""}`);
+	const action = args[1];
+	if (action === "status") {
+		printStatus();
+		return;
+	}
+	if (action === "set") {
+		const name = args[2]?.trim();
+		if (!name) throw new UsageError("browser profile set requires a profile name.");
+		const policy = flags.get("--policy") || "authenticated-only";
+		if (!["explicit-only", "authenticated-only", "always"].includes(policy)) throw new UsageError("Invalid --policy value.");
+		const { path, scope } = selectWritePath(flags);
+		mutateConfig(path, (config) => {
+			config.browser = { ...(config.browser ?? {}), defaultProfile: { name, policy } };
+		});
+		console.log(`Saved browser default profile in ${scope} config: ${path}`);
+		return;
+	}
+	if (action === "clear") {
+		const { path, scope } = selectWritePath(flags);
+		mutateConfig(path, (config) => {
+			if (config.browser) delete config.browser.defaultProfile;
+		});
+		console.log(`Cleared browser default profile in ${scope} config: ${path}`);
+		return;
+	}
+	throw new UsageError(`Unsupported browser profile action: ${action ?? ""}`);
+}
+
+export async function main(argv = process.argv.slice(2)) {
+	const { flags, positional } = parseArgs(argv);
+	if (flags.get("--help") || positional.length === 0) {
+		console.log(usage());
+		return 0;
+	}
+	const command = positional[0];
+	if (command === "paths") {
+		printPaths();
+		return 0;
+	}
+	if (command === "show") {
+		printStatus();
+		return 0;
+	}
+	if (command === "web-search") {
+		await handleWebSearch(positional.slice(1), flags);
+		return 0;
+	}
+	if (command === "browser") {
+		handleBrowser(positional.slice(1), flags);
+		return 0;
+	}
+	throw new UsageError(`Unknown command: ${command}`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+	main().catch((error) => {
+		if (error instanceof UsageError) {
+			console.error(error.message);
+			console.error(usage());
+			process.exit(2);
+		}
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	});
+}