pi-lean-portal 0.1.0

package/core/shared/url-safety.ts

@@ -0,0 +1,164 @@
+/**
+ * URL Safety Checks
+ *
+ * Prevents SSRF (Server-Side Request Forgery) and secret exfiltration
+ * by validating URLs before navigation.
+ *
+ * Patterns from hermes-agent's url_safety.py.
+ */
+
+// ─── Blocked hostnames ───────────────────────────────────────────────
+
+/** Internal/private network ranges that should never be accessed */
+const BLOCKED_HOSTNAMES = [
+	"localhost",
+	"127.0.0.1",
+	"0.0.0.0",
+	"::1",
+	"169.254.169.254", // AWS/GCP metadata endpoint
+	"metadata.google.internal",
+	"100.100.100.200", // Alibaba Cloud metadata
+];
+
+/** Regex for private IP ranges (10.x, 172.16-31.x, 192.168.x) */
+const PRIVATE_IP_REGEX = /^(10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.)/;
+
+// ─── Blocked URL patterns ─────────────────────────────────────────────
+
+/** File-like schemes that shouldn't be followed */
+const BLOCKED_SCHEMES = ["file:", "ftp:", "data:", "javascript:", "vbscript:"];
+
+// ─── Secret detection ────────────────────────────────────────────────
+
+/**
+ * Patterns that look like API keys, tokens, or passwords in URLs.
+ * Follows hermes-agent's approach: checks for known key prefixes rather
+ * than generic length-based patterns, reducing false positives.
+ * Also checks the percent-decoded URL for encoded secrets.
+ */
+const SECRET_PATTERNS = [
+	// Generic API keys in query params (specific param names)
+	/[?&](api[_-]?key|token|secret|password|passwd|auth|credential|private[_-]?key|access[_-]?key)=/i,
+	// Bearer tokens in headers (unlikely in URLs but check anyway)
+	/Bearer\s+[A-Za-z0-9\-._~+/]{20,}=*/i,
+	// GitHub tokens: ghp_, ghs_, ghg_, gho_, ghu_
+	/gh[psogu]_[A-Za-z0-9_]{36}/,
+	// Slack tokens: xoxb-, xoxp-, xoxa-, xoxs-, xoxr-
+	/xox[bpras]-[A-Za-z0-9-]+/,
+	// Stripe: sk_live_, sk_test_, pk_live_, pk_test_, whsec_
+	/(sk|pk)_(live|test)_[A-Za-z0-9]+/,
+	/whsec_[A-Za-z0-9]+/,
+	// AWS access key ID (starts with AKIA)
+	/AKIA[A-Z0-9]{16}/,
+	// Google API keys (AIza prefix)
+	/AIza[0-9A-Za-z\-_]{35}/,
+	// Discord bot tokens
+	/[MN][A-Za-z\d]{23}\.[XZ][A-Za-z\d]{6}\.[A-Za-z\d]{27}/,
+	// SendGrid API keys (SG. prefix)
+	/SG\.[A-Za-z0-9-_]{22}\.[A-Za-z0-9-_]{43}/,
+	// HubSpot API keys
+	/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/,
+	// Generic secret in URL path segment (e.g., "secret=..." in path)
+	/\/secret(?:s)?\//i,
+];
+
+// ─── Types ────────────────────────────────────────────────────────────
+
+export interface UrlSafetyResult {
+	/** Whether the URL is safe to navigate to */
+	safe: boolean;
+	/** Human-readable reason if not safe */
+	reason?: string;
+	/** The specific issue category */
+	category?: "ssrf" | "scheme" | "secret" | "malformed";
+}
+
+// ─── Validation ───────────────────────────────────────────────────────
+
+export function validateUrl(rawUrl: string): UrlSafetyResult {
+	let parsed: URL;
+	try {
+		parsed = new URL(rawUrl);
+	} catch {
+		return { safe: false, reason: "Malformed URL", category: "malformed" };
+	}
+
+	// Check scheme
+	const scheme = parsed.protocol.toLowerCase();
+	if (BLOCKED_SCHEMES.includes(scheme)) {
+		return {
+			safe: false,
+			reason: `Blocked scheme: ${scheme}`,
+			category: "scheme",
+		};
+	}
+
+	if (scheme !== "http:" && scheme !== "https:") {
+		return {
+			safe: false,
+			reason: `Unsupported scheme: ${scheme}. Only http and https are allowed.`,
+			category: "scheme",
+		};
+	}
+
+	// Check hostname against blocked list
+	const hostname = parsed.hostname.toLowerCase();
+	for (const blocked of BLOCKED_HOSTNAMES) {
+		if (hostname === blocked || hostname.endsWith("." + blocked)) {
+			return {
+				safe: false,
+				reason: `Blocked hostname: ${hostname} (private/internal network)`,
+				category: "ssrf",
+			};
+		}
+	}
+
+	// Check for private IP ranges
+	if (PRIVATE_IP_REGEX.test(hostname)) {
+		return {
+			safe: false,
+			reason: `Blocked IP range: ${hostname} (private network)`,
+			category: "ssrf",
+		};
+	}
+
+	// Check for IPv6 loopback
+	if (
+		hostname.startsWith("[") &&
+		(hostname.includes("::1") || hostname.includes("::ffff:127"))
+	) {
+		return {
+			safe: false,
+			reason: `Blocked IPv6 address: ${hostname} (loopback)`,
+			category: "ssrf",
+		};
+	}
+
+	// Check for secrets in URL (raw and percent-decoded)
+	const urlStr = parsed.toString();
+	try {
+		const decodedUrl = decodeURIComponent(urlStr);
+		for (const pattern of SECRET_PATTERNS) {
+			if (pattern.test(urlStr) || pattern.test(decodedUrl)) {
+				return {
+					safe: false,
+					reason: `Potential secret detected in URL. Remove sensitive parameters before navigating.`,
+					category: "secret",
+				};
+			}
+		}
+	} catch {
+		// If decoding fails, just check the raw URL
+		for (const pattern of SECRET_PATTERNS) {
+			if (pattern.test(urlStr)) {
+				return {
+					safe: false,
+					reason: `Potential secret detected in URL. Remove sensitive parameters before navigating.`,
+					category: "secret",
+				};
+			}
+		}
+	}
+
+	return { safe: true };
+}

package/index.ts

@@ -0,0 +1,253 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import * as router from "./core/router.js";
+
+import { cleanupFetchTempFiles } from "./core/fetch-backend.js";
+import { pluginRegistry } from "./core/plugin-registry.js";
+import {
+	loadPluginConfig,
+	detectPluginType,
+	DEFAULT_BACKENDS_ROOT,
+	invalidateConfigCache,
+} from "./core/plugin-config.js";
+import { ChromiumPlugin } from "./backends/chromium/index.js";
+import { PythonPluginAdapter } from "./backends/python-adapter.js";
+import type { PythonBridgeConfig } from "./backends/python-adapter.js";
+
+import { sessionManager } from "./core/shared/session-manager.js";
+import { removeAllSnapshotFiles } from "./core/shared/snapshot-cache.js";
+import initBrowserToggle from "./browser-toggle.js";
+import { updateFooterStatus, getLastCtx, setLastCtx } from "./tools/utils.js";
+import { deleteSessionKey, resetTaskIds } from "./core/shared/task-id.js";
+import { resetToggleModuleState } from "./browser-toggle.js";
+
+// ─── Tool definitions ────────────────────────────────────────────
+
+import {
+	browserNavigateTool,
+	browserSnapshotTool,
+	browserClickTool,
+	browserTypeTool,
+	browserScrollTool,
+	browserBackTool,
+	browserPressTool,
+	browserConsoleTool,
+	browserInspectTool,
+	webFetchTool,
+	webGuideTool,
+	webLearnTool,
+} from "./tools/index.js";
+
+// ============================================================
+// Extension entry point
+// ============================================================
+export default function (pi: ExtensionAPI) {
+	// --- Ensure idempotent re-invocation ----------------------------
+	// pi reuses the cached extension factory on /resume (same cwd),
+	// which re-invokes this function with the same module-level
+	// singletons. Reset them here so the second load is safe.
+	pluginRegistry.clear();
+	invalidateConfigCache();
+	resetTaskIds();
+	resetToggleModuleState();
+
+	// --- Plugin registration ----------------------------------------
+	const { plugins: pluginConfigs, errors: configErrors } = loadPluginConfig();
+
+	// Log config errors
+	for (const err of configErrors) {
+		console.warn(`[pi-lean-portal] Plugin config error: ${err}`);
+	}
+
+	// ── First pass: collect and validate all configs ──────────────
+	// (synchronous — ensures config array order is captured before any async work)
+	const validConfigs: Array<{
+		config: (typeof pluginConfigs)[number];
+		detection: import("./core/plugin-config.js").PluginDetection;
+	}> = [];
+
+	for (const config of pluginConfigs) {
+		let detection;
+		try {
+			detection = detectPluginType(config.dir, DEFAULT_BACKENDS_ROOT);
+		} catch (err) {
+			console.error(
+				`[pi-lean-portal] Plugin '${config.name}' (dir: '${config.dir}'): ${err instanceof Error ? err.message : String(err)}`,
+			);
+			continue;
+		}
+		validConfigs.push({ config, detection });
+	}
+
+	// ── Seed registry with config array order ────────────────────
+	// This preserves the user's declared priority even when some
+	// plugins load asynchronously (Node via dynamic import) while
+	// others register synchronously (Python adapter).
+	if (validConfigs.length > 0) {
+		pluginRegistry.seedOrder(validConfigs.map(({ config }) => config.name));
+	} else {
+		// Fallback: no valid configs → register default Chromium plugin
+		const plugin = new ChromiumPlugin();
+		try {
+			pluginRegistry.register(plugin, {
+				name: "chromium",
+				dir: "chromium",
+				enabled: true,
+				config: {},
+			});
+		} catch (err) {
+			console.error(
+				"[pi-lean-portal] Failed to register default Chromium plugin:",
+				err,
+			);
+		}
+		plugin.init({}).catch((err: unknown) => {
+			console.error(
+				"[pi-lean-portal] Failed to init default Chromium plugin:",
+				err,
+			);
+		});
+	}
+
+	// ── Second pass: load and register plugins ───────────────────
+	// Node plugins register asynchronously (after dynamic import resolves).
+	// Python plugins register synchronously here.
+	// The pre-seeded ordering ensures all plugins get the correct priority level
+	// regardless of when register() is called.
+	for (const { config, detection } of validConfigs) {
+		if (detection.type === "node") {
+			// Node-based backend — dynamically import the detected plugin
+			(async () => {
+				try {
+					const mod: any = await import(detection.entryPoint);
+					const PluginClass: new () => import("./core/plugin-api.js").BrowserPlugin =
+						mod.default;
+					if (!PluginClass || typeof PluginClass !== "function") {
+						throw new Error(
+							`Plugin '${config.name}' (${detection.entryPoint}) must export a default class implementing BrowserPlugin`,
+						);
+					}
+					const plugin = new PluginClass();
+					pluginRegistry.register(plugin, config);
+					plugin.init?.(config.config).catch((err: unknown) => {
+						console.error(
+							`[pi-lean-portal] Failed to init plugin '${config.name}':`,
+							err,
+						);
+					});
+				} catch (err: unknown) {
+					console.error(
+						`[pi-lean-portal] Failed to load Node plugin '${config.name}' (dir: '${config.dir}'): ${err instanceof Error ? err.message : String(err)}`,
+					);
+				}
+			})();
+		} else if (detection.type === "python") {
+			// Python-based backend via JSON-RPC bridge
+			const bridgeConfig: PythonBridgeConfig = {
+				bridgeScript: detection.entryPoint,
+			};
+			// Merge any user-provided config overrides
+			if (config.config) {
+				const userConfig = config.config as Partial<PythonBridgeConfig>;
+				if (userConfig.pythonPath)
+					bridgeConfig.pythonPath = userConfig.pythonPath;
+				if (userConfig.pythonArgs)
+					bridgeConfig.pythonArgs = userConfig.pythonArgs;
+				if (userConfig.capabilities)
+					bridgeConfig.capabilities = userConfig.capabilities;
+				if (userConfig.transportTimeoutMs)
+					bridgeConfig.transportTimeoutMs = userConfig.transportTimeoutMs;
+			}
+			const adapter = new PythonPluginAdapter(config.name, bridgeConfig);
+			try {
+				pluginRegistry.register(adapter, config);
+			} catch (err) {
+				console.error(
+					`[pi-lean-portal] Failed to register Python plugin '${config.name}':`,
+					err,
+				);
+			}
+			adapter.init(config.config).catch((err: unknown) => {
+				console.error(
+					`[pi-lean-portal] Failed to init Python plugin '${config.name}':`,
+					err,
+				);
+			});
+		} else {
+			// Exhaustiveness guard — PluginType is currently "node" | "python"
+			const _exhaustive: never = detection.type;
+			console.warn(
+				`[pi-lean-portal] Plugin '${config.name}' has unknown type '${_exhaustive as string}'.`,
+			);
+		}
+	}
+
+	// --- Register tools ---------------------------------------------
+	pi.registerTool(webFetchTool);
+	pi.registerTool(browserNavigateTool);
+	pi.registerTool(browserSnapshotTool);
+	pi.registerTool(browserClickTool);
+	pi.registerTool(browserTypeTool);
+	pi.registerTool(browserScrollTool);
+	pi.registerTool(browserBackTool);
+	pi.registerTool(browserPressTool);
+	pi.registerTool(browserConsoleTool);
+	pi.registerTool(browserInspectTool);
+	pi.registerTool(webGuideTool);
+	pi.registerTool(webLearnTool);
+
+	// --- Register commands ------------------------------------------
+	initBrowserToggle(pi);
+
+	// --- Profile change callback for TUI status updates ------------
+	router.setOnProfileChange((taskId, profileName, profileMode) => {
+		// Update TUI status bar on any profile lifecycle event
+		const lastCtx = getLastCtx();
+		if (lastCtx) {
+			updateFooterStatus(lastCtx);
+		}
+
+		// Debug logging when BROWSER_DEBUG is set
+		if (process.env.BROWSER_DEBUG) {
+			const parts = [`[browser] profile_changed: task=${taskId}`];
+			if (profileName) parts.push(`profile=${profileName}`);
+			if (profileMode) parts.push(`mode=${profileMode}`);
+			console.error(parts.join(" "));
+		}
+	});
+
+	// --- Startup ----------------------------------------------------
+	pi.on("session_start", async (_event, ctx) => {
+		const pluginNames = pluginRegistry.available().join(", ");
+		ctx.ui.notify(
+			`🌐 Browser extension loaded (plugins: ${pluginNames}). Try: web-fetch for static pages or browser-navigate for interactive browsing.`,
+			"info",
+		);
+		updateFooterStatus(ctx);
+	});
+
+	// --- Cleanup ----------------------------------------------------
+	pi.on("session_shutdown", async (_event, ctx) => {
+		setLastCtx(null);
+		const piSessionId = (ctx as any)?.sessionManager?.getSessionId?.();
+		if (piSessionId) {
+			deleteSessionKey(piSessionId);
+			// Per-conversation fetch cleanup — prevents cross-conversation eviction
+			const tid = sessionManager.getTaskIdForPiSessionId(piSessionId);
+			if (tid) cleanupFetchTempFiles(tid);
+		}
+
+		// Clean up all registered plugins
+		const ordered = pluginRegistry.getOrdered();
+		for (const { plugin } of ordered) {
+			await plugin.cleanupAll().catch(() => {});
+		}
+
+		await sessionManager.removeAll();
+		removeAllSnapshotFiles();
+		try {
+			ctx?.ui?.setStatus?.("browser", "");
+		} catch {
+			// ctx.ui may not be available during shutdown
+		}
+	});
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+	"name": "pi-lean-portal",
+	"version": "0.1.0",
+	"description": "Pi extension. Interactive web browsing for Pi — Playwright Chromium/Firefox, accessibility-tree snapshots, profiles, cookies, guides. Owns the /web command.",
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"browser",
+		"playwright",
+		"web"
+	],
+	"license": "AGPL-3.0-only",
+	"author": "",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/coreyryanhanson/pi-lean-dimension.git",
+		"directory": "packages/pi-lean-portal"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"index.ts",
+		"browser-toggle.ts",
+		"browser-profile.ts",
+		"browser-cookies.ts",
+		"browser-status.ts",
+		"LICENSE",
+		"backends/",
+		"!backends/python-base/.venv/",
+		"!backends/python-base/**/__pycache__/",
+		"!backends/python-base/**/*.pyc",
+		"!backends/python-base/tests/",
+		"!backends/python-base/**/*.egg-info/",
+		"core/",
+		"tools/",
+		"verify-ship-manifest.ts",
+		".npmrc",
+		"README.md",
+		"ship-manifest.test.ts"
+	],
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"scripts": {
+		"prepack": "cp ../../LICENSE ./LICENSE",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"node-html-parser": "^6.1.0",
+		"playwright": "^1.60.0",
+		"turndown": "^7.2.0"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"typebox": "*"
+	}
+}

package/ship-manifest.test.ts

@@ -0,0 +1,12 @@
+import { verifyShipManifest } from "./verify-ship-manifest.js";
+import { describe, expect, it } from "vitest";
+
+describe("publish manifest", () => {
+	it("`package.json` `files` array covers every production .ts module across the tree", () => {
+		expect(verifyShipManifest(import.meta.url).missing).toEqual([]);
+	});
+
+	it("every `files` entry points at something on disk — a stale entry ships nothing", () => {
+		expect(verifyShipManifest(import.meta.url).stale).toEqual([]);
+	});
+});

package/tools/browser-back.ts

@@ -0,0 +1,50 @@
+/**
+ * browser-back tool definition.
+ */
+
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@earendil-works/pi-ai";
+import { Text } from "@earendil-works/pi-tui";
+import * as router from "../core/router.js";
+import { executeInteractionTool } from "./utils.js";
+
+export const browserBackTool = defineTool({
+	name: "browser-back",
+	label: "Go Back",
+	description: "Navigate back in browser history.",
+	parameters: Type.Object({}),
+
+	async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+		return executeInteractionTool(
+			ctx,
+			"Go back",
+			(tid) => router.goBack(tid),
+			(result) => ({
+				message: `Went back to: ${result.newUrl || "?"}`,
+				details: {
+					newUrl: result.newUrl,
+					newTitle: result.newTitle,
+					elementCount: result.elementCount,
+				},
+			}),
+		);
+	},
+
+	renderCall(_args, theme, _context) {
+		return new Text(theme.fg("toolTitle", theme.bold("browser-back")), 0, 0);
+	},
+
+	renderResult(result, _options, theme, _context) {
+		const d = result.details as Record<string, unknown> | undefined;
+		if (d?.error) return new Text(theme.fg("error", "Go back failed"), 0, 0);
+		const ec = d?.elementCount as number | undefined;
+		return new Text(
+			theme.fg(
+				"dim",
+				`← ${(d?.newUrl as string) || ""}${ec !== undefined ? ` · ${ec} elements` : ""}`,
+			),
+			0,
+			0,
+		);
+	},
+});

package/tools/browser-click.ts

@@ -0,0 +1,74 @@
+/**
+ * browser-click tool definition.
+ */
+
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@earendil-works/pi-ai";
+import { Text } from "@earendil-works/pi-tui";
+import * as router from "../core/router.js";
+import { executeInteractionTool } from "./utils.js";
+
+export const browserClickTool = defineTool({
+	name: "browser-click",
+	label: "Click Element",
+	description:
+		"Click an element on the page by its @e reference ID (e.g., @e5). " +
+		"Use element references from browser-navigate or browser-snapshot output.",
+	parameters: Type.Object({
+		ref: Type.String({
+			description: "Element reference like @e5 (from the accessibility tree)",
+		}),
+	}),
+
+	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		const { ref } = params as { ref: string };
+		return executeInteractionTool(
+			ctx,
+			"Click",
+			(tid) => router.click(tid, ref),
+			(result) => ({
+				message: [
+					`Clicked ${ref}`,
+					result.newUrl ? `URL: ${result.newUrl}` : "",
+					result.newTitle ? `Title: ${result.newTitle}` : "",
+				]
+					.filter(Boolean)
+					.join("\n"),
+				details: {
+					newUrl: result.newUrl,
+					newTitle: result.newTitle,
+					elementCount: result.elementCount,
+				},
+			}),
+		);
+	},
+
+	renderCall(args, theme, _context) {
+		return new Text(
+			`${theme.fg("toolTitle", theme.bold("browser-click"))} ${theme.fg("accent", args.ref)}`,
+			0,
+			0,
+		);
+	},
+
+	renderResult(result, _options, theme, _context) {
+		const d = result.details as Record<string, unknown> | undefined;
+		if (d?.error)
+			return new Text(theme.fg("error", `Click failed: ${d.error}`), 0, 0);
+		const newUrl = d?.newUrl as string | undefined;
+		const ec = d?.elementCount as number | undefined;
+		if (newUrl) {
+			let text = theme.fg("success", `✅ → ${newUrl}`);
+			if (ec !== undefined) text += ` · ${ec} elements`;
+			return new Text(text, 0, 0);
+		}
+		return new Text(
+			theme.fg(
+				"success",
+				`✅ clicked${ec !== undefined ? ` · ${ec} elements` : ""}`,
+			),
+			0,
+			0,
+		);
+	},
+});