pi-lean-dimension 0.1.0 → 0.2.1

package/node_modules/pi-lean-portal/core/shared/dom-extractor.ts

@@ -7,7 +7,7 @@
  * - runExtractor() — calls the script and validates the result
  * - correlateElements() — matches extracted content against the element cache
  * - queryElementCache() — synchronous cache filtering
- * - formatCorrelatedOutput(), formatElementList(), formatRoleCountSummary()
+ * - correlateElements(), formatElementList(), formatRoleCountSummary()
  * - Boilerplate filtering constants
  */
 
@@ -49,7 +49,7 @@ export interface ExtractResult {
 }
 
 /** Output of the correlation step — text with @e annotations. */
-export interface CorrelatedResult {
+interface CorrelatedResult {
 	/** Formatted text output with @e annotations */
 	text: string;
 	/** Number of matched refs */
@@ -58,14 +58,33 @@ export interface CorrelatedResult {
 	staleCache: boolean;
 }
 
+/** Outcome of runExtractor — discriminated union. */
+type ExtractorOutcome =
+	| { ok: true; result: ExtractResult }
+	| { ok: false; error: string };
+
 /** Parameters for queryElementCache. */
-export interface ElementCacheQuery {
+interface ElementCacheQuery {
 	role?: string;
 	name?: string;
 	ref?: string;
 	subtree?: string;
 }
 
+/**
+ * Optional out-param for queryElementCache to signal when a ref was found
+ * but an extra role/name/subtree filter rejected it.
+ */
+export interface QueryStatus {
+	/** Set when filters.ref resolved to a cache node but an extra
+	 *  role/name/subtree filter rejected it. */
+	refFilteredOut?: {
+		node: AriaCachedNode;
+		filter: "role" | "name" | "subtree";
+		value: string;
+	};
+}
+
 // ─── EXTRACTOR_SCRIPT — runs in browser page context ──────────────
 
 /**
@@ -75,8 +94,14 @@ export interface ElementCacheQuery {
  * Playwright injects evaluate() at the DevTools protocol level,
  * bypassing page CSP. Sandboxed iframes without allow-scripts
  * are the only case that fails — the caller handles that.
+ *
+ * INVARIANT: EXTRACTOR_SCRIPT is pure DOM reads (no fetch/XHR/eval/
+ * writes). runExtractor() relies on this to pass read_only=true so
+ * the bridge routes it through the stable isolated-world context on
+ * Camoufox. If you add a write here, drop the `true` arg in
+ * runExtractor().
  */
-const EXTRACTOR_SCRIPT = `(() => {
+export const EXTRACTOR_SCRIPT = `(() => {
   'use strict';
   try {
     const result = {
@@ -182,18 +207,21 @@ const EXTRACTOR_SCRIPT = `(() => {
  * Run the DOM extractor in the page context via plugin.evaluate().
  *
  * The extractor runs purely on DOM properties — no fetch, no XHR, no eval.
- * Returns a parsed ExtractResult, or null on failure (including error
- * caught by the script itself, evaluate rejection, or invalid JSON).
+ * Returns an ExtractorOutcome with the parsed result on success or an
+ * error string on failure.
  */
 export async function runExtractor(
 	taskId: string,
 	plugin: BrowserPlugin,
-): Promise<ExtractResult | null> {
+): Promise<ExtractorOutcome> {
 	try {
-		const evalResult = await plugin.evaluate(taskId, EXTRACTOR_SCRIPT);
+		const evalResult = await plugin.evaluate(taskId, EXTRACTOR_SCRIPT, true);
 
 		if (!evalResult.success) {
-			return null;
+			return {
+				ok: false,
+				error: evalResult.error ?? "evaluate failed (no error detail)",
+			};
 		}
 
 		// The script returns a JSON string inside result.result
@@ -202,12 +230,23 @@ export async function runExtractor(
 				? evalResult.result
 				: JSON.stringify(evalResult.result);
 
-		const parsed = JSON.parse(rawJson) as ExtractResult;
+		let parsed: ExtractResult;
+		try {
+			parsed = JSON.parse(rawJson) as ExtractResult;
+		} catch (e: unknown) {
+			return {
+				ok: false,
+				error: `extractor returned invalid JSON: ${e instanceof Error ? e.message : String(e)}`,
+			};
+		}
 
 		// Check for script-level error
 		if (parsed.error) {
-			console.warn("[pi-lean-portal] DOM extractor script error:", parsed.error);
-			return null;
+			console.warn(
+				"[pi-lean-portal] DOM extractor script error:",
+				parsed.error,
+			);
+			return { ok: false, error: parsed.error };
 		}
 
 		// Validate shape (basic structural check)
@@ -219,12 +258,15 @@ export async function runExtractor(
 			!Array.isArray(parsed.images) ||
 			!Array.isArray(parsed.interactive)
 		) {
-			return null;
+			return { ok: false, error: "extractor returned malformed result" };
 		}
 
-		return parsed;
+		return { ok: true, result: parsed };
 	} catch {
-		return null;
+		return {
+			ok: false,
+			error: "evaluate failed (no error detail)",
+		};
 	}
 }
 
@@ -353,8 +395,18 @@ export function correlateElements(
 		);
 	}
 
+	// ── Empty-output notice ──
+	let text = lines.join("\n").trim();
+	if (text.length === 0) {
+		text =
+			"⚠ No extractable content found on the page. " +
+			"The page may be empty, render behind a challenge, or block DOM queries. " +
+			"Use browser-inspect { role/name/ref } against the element cache, " +
+			"or browser-snapshot to inspect visually.";
+	}
+
 	return {
-		text: lines.join("\n").trim(),
+		text,
 		matchedRefs: matchedRefs.size,
 		staleCache,
 	};
@@ -390,9 +442,15 @@ function annotateRefs(refs: string[], matchedRefs: Set<string>): string {
 export function queryElementCache(
 	cache: Map<string, AriaCachedNode>,
 	filters: ElementCacheQuery,
+	status?: QueryStatus,
 ): AriaCachedNode[] {
 	const results: AriaCachedNode[] = [];
 
+	// Pre-compute subtree ancestry map once (shared by ref + loop paths)
+	const subtreeAncestors = filters.subtree
+		? computeSubtreeAncestors(cache, filters.subtree)
+		: null;
+
 	// ref lookup: direct map access (cache keys are "e5" not "@e5")
 	if (filters.ref) {
 		const key = filters.ref.startsWith("@")
@@ -401,26 +459,38 @@ export function queryElementCache(
 		const node = cache.get(key);
 		if (node) {
 			// Apply additional filters if any
-			if (filters.role && !matchesRole(node, filters.role)) return [];
-			if (filters.name && !matchesName(node, filters.name)) return [];
-			if (filters.subtree && !matchesSubtree(node, cache, filters.subtree))
+			if (filters.role && !matchesRole(node, filters.role)) {
+				if (status)
+					status.refFilteredOut = { node, filter: "role", value: filters.role };
 				return [];
+			}
+			if (filters.name && !matchesName(node, filters.name)) {
+				if (status)
+					status.refFilteredOut = { node, filter: "name", value: filters.name };
+				return [];
+			}
+			if (
+				filters.subtree &&
+				subtreeAncestors &&
+				!subtreeAncestors.has(node.ref)
+			) {
+				if (status)
+					status.refFilteredOut = {
+						node,
+						filter: "subtree",
+						value: filters.subtree,
+					};
+				return [];
+			}
 			return [node];
 		}
 		return [];
 	}
 
-	// Pre-compute subtree ancestry map for subtree filter
-	const subtreeAncestors = filters.subtree
-		? computeSubtreeAncestors(cache, filters.subtree)
-		: null;
-
 	for (const [, node] of cache) {
 		if (filters.role && !matchesRole(node, filters.role)) continue;
 		if (filters.name && !matchesName(node, filters.name)) continue;
-		if (filters.subtree && subtreeAncestors) {
-			if (!subtreeAncestors.has(node.ref)) continue;
-		}
+		if (subtreeAncestors && !subtreeAncestors.has(node.ref)) continue;
 		results.push(node);
 	}
 
@@ -478,15 +548,6 @@ function computeSubtreeAncestors(
 	return insideRefs;
 }
 
-function matchesSubtree(
-	node: AriaCachedNode,
-	cache: Map<string, AriaCachedNode>,
-	containerRole: string,
-): boolean {
-	const ancestors = computeSubtreeAncestors(cache, containerRole);
-	return ancestors.has(node.ref);
-}
-
 // ─── Output formatting ────────────────────────────────────────────
 
 /**

package/node_modules/pi-lean-portal/core/shared/nav-settle.ts

@@ -1,19 +1,13 @@
 /**
- * Navigation settle detection for the browser extension.
+ * Navigation settle detection — waits for framenavigated event or DOM
+ * stabilisation after interactions, eliminating stale-@e-ref bugs from fixed sleeps.
  *
- * After a user interaction (click, press) that may or may not trigger
- * a page navigation, this module provides a reliable way to wait for
- * the page to settle before reading URL / title / snapshot.
- *
- * The core insight: instead of a fixed sleep (e.g. `waitForTimeout(300)`)
- * that races against navigation commit, we listen for the actual
- * `framenavigated` event and wait for page readiness (load + networkidle)
- * only when navigation has actually started.
- *
- * This eliminates the URL / DOM mismatch that causes stale-@e-ref and
- * mismatched URL/content bugs.
+ * Constants (timeouts, race window) are sourced from the shared
+ * ``browser-data.json`` so the TypeScript and Python sides never drift.
  */
 
+import { NAV_SETTLE } from "./browser-data.js";
+
 // ─── Public types ───────────────────────────────────────────────────
 
 /**
@@ -129,8 +123,8 @@ export async function waitForNavigationSettle(
 	urlBefore: string,
 	opts?: NavigationSettleOptions,
 ): Promise<NavigationSettleResult> {
-	const navTimeout = opts?.navTimeoutMs ?? 5000;
-	const settleTimeout = opts?.settleTimeoutMs ?? 400;
+	const navTimeout = opts?.navTimeoutMs ?? NAV_SETTLE.navTimeoutMs;
+	const settleTimeout = opts?.settleTimeoutMs ?? NAV_SETTLE.settleTimeoutMs;
 
 	let navigated = false;
 
@@ -156,7 +150,10 @@ export async function waitForNavigationSettle(
 		// Most link clicks and Enter presses trigger navigation within one
 		// event-loop tick; the race means we don't waste time when nav
 		// starts immediately.
-		await Promise.race([page.waitForTimeout(150), navStarted]);
+		await Promise.race([
+			page.waitForTimeout(NAV_SETTLE.settleRaceMs),
+			navStarted,
+		]);
 
 		let waitedForLoad = false;
 		if (navigated) {

package/node_modules/pi-lean-portal/core/shared/paths.ts

@@ -29,6 +29,9 @@ export const PORTAL_DATA_DIR = join(
 	"pi-lean-portal",
 );
 
+/** User-installed Python backend root; sibling of web-guides/ and browser-state/. */
+export const USER_BACKENDS_DIR = join(PORTAL_DATA_DIR, "user-backends");
+
 /**
  * Sanitize a taskId (or any string) for use in filenames.
  * Replaces any character that is not alphanumeric or hyphen with `_`.

package/node_modules/pi-lean-portal/core/shared/session-manager.ts

@@ -90,28 +90,14 @@ class SessionManager {
 		>,
 	): void {
 		const session = this.#sessions.get(taskId);
-		if (session) {
-			if (updates.currentUrl !== undefined)
-				session.currentUrl = updates.currentUrl;
-			if (updates.currentTitle !== undefined)
-				session.currentTitle = updates.currentTitle;
-			if (updates.pluginName !== undefined)
-				session.pluginName = updates.pluginName;
-			if (updates.crashed !== undefined) session.crashed = updates.crashed;
-			if (updates.currentSnapshotFingerprint !== undefined)
-				session.currentSnapshotFingerprint = updates.currentSnapshotFingerprint;
-			if (updates.cachePopulatedAt !== undefined)
-				session.cachePopulatedAt = updates.cachePopulatedAt;
-			if (updates.lastInteractionAt !== undefined)
-				session.lastInteractionAt = updates.lastInteractionAt;
-			if (updates.persistState !== undefined)
-				session.persistState = updates.persistState;
-			if (updates.profileName !== undefined)
-				session.profileName = updates.profileName;
-			if (updates.piSessionId !== undefined)
-				session.piSessionId = updates.piSessionId;
-			session.lastActive = Date.now();
+		if (!session) return;
+		// ponytail: the `as any` is bounded by the Partial<Pick<BrowserSession, …>>
+		// type above — only declared session fields can land here. Skip-undefined
+		// preserves existing fields (matches the prior per-field guards).
+		for (const [k, v] of Object.entries(updates)) {
+			if (v !== undefined) (session as any)[k] = v;
 		}
+		session.lastActive = Date.now();
 	}
 
 	// ─── Last navigation storage (for session auto-recovery) ───

package/node_modules/pi-lean-portal/{verify-ship-manifest.ts → core/shared/ship-manifest.ts}

@@ -13,7 +13,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-const SKIP_DIRS = new Set(["node_modules", "docs", "__tests__"]);
+const DEFAULT_SKIP_DIRS = ["node_modules", "docs", "__tests__"];
 const SKIP_FILES = new Set(["test-fixtures.ts"]);
 /** Entries that won't exist on disk at rest but are valid (generated at pack time, e.g. by prepack). */
 const SKIP_STALE = new Set(["LICENSE"]);
@@ -44,15 +44,38 @@ export interface ShipManifestResult {
  * would omit; `stale` flags `files` entries that point at nothing on disk
  * (asset entries like `README.md` count as present — staleness is plain
  * existence, not the production-`.ts` walk).
+ *
+ * @param opts.skipDirs - Additional directory names to skip beyond the defaults
+ *                        (`node_modules`, `docs`, `__tests__`).
  */
 export function verifyShipManifest(
 	packageDirOrUrl: string,
+	opts?: { skipDirs?: readonly string[] },
 ): ShipManifestResult {
 	const packageDir = packageDirOrUrl.startsWith("file:")
 		? dirname(fileURLToPath(packageDirOrUrl))
 		: packageDirOrUrl;
-	const pkgRaw = readFileSync(resolve(packageDir, "package.json"), "utf8");
-	const pkg = JSON.parse(pkgRaw) as { files?: string[] };
+	const skipDirs = new Set([...DEFAULT_SKIP_DIRS, ...(opts?.skipDirs ?? [])]);
+	let pkgRaw: string;
+	try {
+		pkgRaw = readFileSync(resolve(packageDir, "package.json"), "utf8");
+	} catch (err) {
+		throw new Error(
+			`verifyShipManifest: could not read package.json under "${packageDir}": ${
+				err instanceof Error ? err.message : String(err)
+			}`,
+		);
+	}
+	let pkg: { files?: string[] };
+	try {
+		pkg = JSON.parse(pkgRaw) as { files?: string[] };
+	} catch (err) {
+		throw new Error(
+			`verifyShipManifest: package.json under "${packageDir}" is not valid JSON: ${
+				err instanceof Error ? err.message : String(err)
+			}`,
+		);
+	}
 	const declared = pkg.files ?? [];
 	const exactFiles = new Set<string>();
 	const dirPrefixes: string[] = [];
@@ -72,7 +95,7 @@ export function verifyShipManifest(
 		else exactFiles.add(entry);
 	}
 
-	const onDisk = walkProductionTs(packageDir, packageDir);
+	const onDisk = walkProductionTs(packageDir, packageDir, skipDirs);
 	const missing = onDisk.filter((f) => !isCovered(f, exactFiles, dirPrefixes));
 	// Staleness: check only non-negation entries. Negation patterns (`!foo/`)
 	// have no on-disk counterpart.
@@ -90,8 +113,6 @@ function isDirOnDisk(packageDir: string, entry: string): boolean {
 	try {
 		return statSync(resolve(packageDir, entry)).isDirectory();
 	} catch {
-		// Entry not present on disk (e.g. an asset/extraneous `files` entry) —
-		// not a directory we can recurse into; the caller treats it as an exact file.
 		return false;
 	}
 }
@@ -108,14 +129,18 @@ function isCovered(
 	return false;
 }
 
-function walkProductionTs(root: string, dir: string): string[] {
+function walkProductionTs(
+	root: string,
+	dir: string,
+	skipDirs: Set<string>,
+): string[] {
 	const out: string[] = [];
 	for (const entry of readdirSync(dir, { withFileTypes: true })) {
 		if (entry.name.startsWith(".")) continue;
-		if (entry.isDirectory() && SKIP_DIRS.has(entry.name)) continue;
+		if (entry.isDirectory() && skipDirs.has(entry.name)) continue;
 		const abs = resolve(dir, entry.name);
 		if (entry.isDirectory()) {
-			out.push(...walkProductionTs(root, abs));
+			out.push(...walkProductionTs(root, abs, skipDirs));
 			continue;
 		}
 		if (!entry.isFile() || !entry.name.endsWith(".ts")) continue;

package/node_modules/pi-lean-portal/core/shared/snapshot-cache.ts

@@ -55,6 +55,9 @@ interface CacheEntry {
  */
 const activeSnapshotFiles = new Map<string, CacheEntry[]>();
 
+/** Monotonic file-index counter — guarantees unique filenames across writes. */
+let _snapshotIndexCounter = 0;
+
 // ─── Helpers ────────────────────────────────────────────────────────────
 
 /**
@@ -107,12 +110,10 @@ export function cacheSnapshot(
 		const digest = sha256Prefix(snapshot);
 		const existingEntries = activeSnapshotFiles.get(taskId) ?? [];
 
-		// Determine index: next sequential index based on existing files
-		const nextIndex = existingEntries.reduce((max, entry) => {
-			const match = entry.path.match(/-(\d+)\.txt$/);
-			const idx = match ? parseInt(match[1]!, 10) : -1;
-			return Math.max(max, idx + 1);
-		}, 0);
+		// Monotonic index — avoids filename collisions with currently-tracked
+		// entries (length would collide with surviving higher-index files
+		// after eviction; Date.now() can collide within the same ms).
+		const nextIndex = _snapshotIndexCounter++;
 
 		const filePath = buildCacheFilePath(taskId, digest, nextIndex);
 		writeFileSync(filePath, snapshot, "utf-8");

package/node_modules/pi-lean-portal/core/shared/storage-state.ts

@@ -26,7 +26,6 @@ import { PORTAL_DATA_DIR } from "./paths.js";
 
 // ─── Constants ────────────────────────────────────────────────────────
 
-/** Root directory for all browser profiles. */
 export const PROFILE_DIR = join(PORTAL_DATA_DIR, "browser-state");
 
 /** Current storage state version. Increment on breaking format changes. */
@@ -38,7 +37,6 @@ const DEFAULT_MAX_STORAGE_STATE_SIZE = 10 * 1024 * 1024;
 /** Profile name validation regex. */
 const PROFILE_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
 
-/** Reserved keywords that cannot be used as profile names. */
 const RESERVED_PROFILE_NAMES = new Set([
 	"none",
 	"session", // profile modes
@@ -52,7 +50,6 @@ const RESERVED_PROFILE_NAMES = new Set([
 /** Prefix for auto-generated session-scoped profiles. */
 const SESSION_PROFILE_PREFIX = "_session-";
 
-/** Directory where pi stores active session tracking files. */
 export const SESSIONS_DIR = join(homedir(), ".pi", "agent", "sessions");
 
 // ─── Types ────────────────────────────────────────────────────────────
@@ -69,13 +66,11 @@ interface StoredCookie {
 	sameSite: "Strict" | "Lax" | "None";
 }
 
-/** A localStorage entry for a given origin. */
 interface StoredLocalStorageEntry {
 	name: string;
 	value: string;
 }
 
-/** An origin with its localStorage data. */
 interface StoredOrigin {
 	origin: string;
 	localStorage: StoredLocalStorageEntry[];
@@ -153,9 +148,6 @@ export function profileDir(profileName: string): string {
 	return join(PROFILE_DIR, safe);
 }
 
-/**
- * Get the filesystem path to a profile's storage state file.
- */
 export function profileFilePath(profileName: string): string {
 	return join(profileDir(profileName), "storage-state.json");
 }
@@ -212,7 +204,6 @@ export function loadStorageState(
 
 // ─── Private Helpers ──────────────────────────────────────────────────
 
-/** Temp file prefix for atomic writes. */
 const TEMP_FILE_PREFIX = ".storage-state.";
 const TEMP_FILE_SUFFIX = ".tmp";
 
@@ -462,6 +453,46 @@ export function deleteStorageState(profileName: string): void {
 
 // ─── Session Profile Helpers ───────────────────────────────────────
 
+/**
+ * Persist storage state for a session if it is marked persistent.
+ *
+ * Shared by `PlaywrightPluginBase._persistState` (which reads state directly
+ * from a Playwright `BrowserContext`) and `PythonPluginAdapter._persistState`
+ * (which fetches state over JSON-RPC).  Both supply a `getStorageState`
+ * callback returning the raw `{ cookies, origins }` state; this helper owns
+ * the `persistState` gate, the `saveStorageState` call, and the
+ * warn-and-swallow error path so the two backends can't drift.
+ *
+ * @param session - The session-manager entry, or null/undefined. Only
+ *                  sessions with `persistState` true trigger a save.
+ * @param getStorageState - Callback that produces the raw storage state.
+ * @param viaLabel - Optional backend label inserted into the warning
+ *                   (e.g. `"via Python bridge"`) for diagnostic output.
+ * @returns The raw state object, or `undefined` if the session is
+ *          non-persistent or the save failed.
+ */
+export async function persistSessionState(
+	session: { persistState?: boolean; profileName?: string } | null | undefined,
+	getStorageState: () => Promise<{ cookies: unknown[]; origins: unknown[] }>,
+	viaLabel: string = "",
+): Promise<{ cookies: unknown[]; origins: unknown[] } | undefined> {
+	if (!session?.persistState) return undefined;
+	const name = session.profileName ?? "default";
+	try {
+		const state = await getStorageState();
+		saveStorageState(name, state);
+		return state;
+	} catch (err) {
+		console.warn(
+			`[pi-lean-portal] Failed to auto-save storage state for profile ` +
+				`'${name}'${viaLabel ? ` ${viaLabel}` : ""}: ` +
+				`${err instanceof Error ? err.message : String(err)}. ` +
+				"Session state may be lost.",
+		);
+		return undefined;
+	}
+}
+
 /**
  * Check whether a profile name follows the session-scoped naming convention.
  *

package/node_modules/pi-lean-portal/index.ts

@@ -4,9 +4,9 @@ import * as router from "./core/router.js";
 import { cleanupFetchTempFiles } from "./core/fetch-backend.js";
 import { pluginRegistry } from "./core/plugin-registry.js";
 import {
-	loadPluginConfig,
+	loadFullConfig,
 	detectPluginType,
-	DEFAULT_BACKENDS_ROOT,
+	DEFAULT_BACKEND_ROOTS,
 	invalidateConfigCache,
 } from "./core/plugin-config.js";
 import { ChromiumPlugin } from "./backends/chromium/index.js";
@@ -51,7 +51,12 @@ export default function (pi: ExtensionAPI) {
 	resetToggleModuleState();
 
 	// --- Plugin registration ----------------------------------------
-	const { plugins: pluginConfigs, errors: configErrors } = loadPluginConfig();
+	// Resolve plugin `dir` values against the shipped backends root first,
+	// then the user-writable `~/.pi/agent/pi-lean-portal/user-backends/`
+	// tree (Phase 0b).  An absolute `dir` short-circuits both roots.
+	const { plugins: pluginConfigs, errors: configErrors } = loadFullConfig(
+		DEFAULT_BACKEND_ROOTS,
+	).plugins;
 
 	// Log config errors
 	for (const err of configErrors) {
@@ -68,7 +73,7 @@ export default function (pi: ExtensionAPI) {
 	for (const config of pluginConfigs) {
 		let detection;
 		try {
-			detection = detectPluginType(config.dir, DEFAULT_BACKENDS_ROOT);
+			detection = detectPluginType(config.dir, DEFAULT_BACKEND_ROOTS);
 		} catch (err) {
 			console.error(
 				`[pi-lean-portal] Plugin '${config.name}' (dir: '${config.dir}'): ${err instanceof Error ? err.message : String(err)}`,
@@ -111,8 +116,8 @@ export default function (pi: ExtensionAPI) {
 	// ── 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.
+	// The pre-seeded ordering ensures all plugins keep their configured
+	// position regardless of when register() is called.
 	for (const { config, detection } of validConfigs) {
 		if (detection.type === "node") {
 			// Node-based backend — dynamically import the detected plugin
@@ -182,6 +187,36 @@ export default function (pi: ExtensionAPI) {
 	}
 
 	// --- Register tools ---------------------------------------------
+	// Patch the browser-navigate strategy description with the actually
+	// configured plugin names so the agent doesn't second-guess which
+	// strategies exist (matches what /web status reports).
+	const strategyPlugins =
+		validConfigs.length > 0
+			? validConfigs.map(({ config }) => ({
+					name: config.name,
+					enabled: config.enabled,
+				}))
+			: [{ name: "chromium", enabled: true }]; // fallback path
+	const enabledNames = strategyPlugins
+		.filter((p) => p.enabled)
+		.map((p) => p.name);
+	const disabledNames = strategyPlugins
+		.filter((p) => !p.enabled)
+		.map((p) => p.name);
+	const availList =
+		enabledNames.length > 0 ? enabledNames.join(", ") : "(none)";
+	const disabledClause =
+		disabledNames.length > 0 ? ` Disabled: ${disabledNames.join(", ")}.` : "";
+	(
+		browserNavigateTool as unknown as {
+			parameters: { properties: { strategy: { description: string } } };
+		}
+	).parameters.properties.strategy.description =
+		`Backend strategy: "auto" (default) uses the first available plugin; ` +
+		`specify a registered plugin name to use that backend. ` +
+		`Available: ${availList}.${disabledClause} ` +
+		`For stateless HTTP fetches, use web-fetch instead.`;
+
 	pi.registerTool(webFetchTool);
 	pi.registerTool(browserNavigateTool);
 	pi.registerTool(browserSnapshotTool);
@@ -238,7 +273,7 @@ export default function (pi: ExtensionAPI) {
 
 		// Clean up all registered plugins
 		const ordered = pluginRegistry.getOrdered();
-		for (const { plugin } of ordered) {
+		for (const plugin of ordered) {
 			await plugin.cleanupAll().catch(() => {});
 		}
 

package/node_modules/pi-lean-portal/package.json

@@ -1,7 +1,7 @@
 {
 	"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.",
+	"version": "0.2.1",
+	"description": "Pi extension. Interactive web browsing for Pi — a /web toggle removes the tools from context when switched off, Playwright Chromium/Firefox deliver accessibility-tree snapshots, persistent profiles, cookies, and domain-matched guides; custom/stealth backends (Camoufox) plug in when a site blocks the shipped browsers.",
 	"keywords": [
 		"pi-package",
 		"pi-extension",
@@ -20,6 +20,12 @@
 	"publishConfig": {
 		"access": "public"
 	},
+	"exports": {
+		".": {
+			"types": "./core/plugin-api.ts",
+			"default": "./index.ts"
+		}
+	},
 	"files": [
 		"index.ts",
 		"browser-toggle.ts",
@@ -35,7 +41,6 @@
 		"!backends/python-base/**/*.egg-info/",
 		"core/",
 		"tools/",
-		"verify-ship-manifest.ts",
 		".npmrc",
 		"README.md",
 		"ship-manifest.test.ts"