pi-lean-dimension 0.1.0 → 0.2.1

package/node_modules/pi-lean-portal/core/plugin-config.ts

@@ -6,14 +6,18 @@
  */
 
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { join, isAbsolute } from "node:path";
+import { USER_BACKENDS_DIR } from "./shared/paths.js";
 // ─── Plugin Config types ──────────────────────────────────────────
 
 /** A single plugin entry from the user's settings.json */
 export interface PluginConfig {
 	/** Stable identifier used in strategy param, session tracking, errors */
 	name: string;
-	/** Directory name under backends/ containing the plugin code */
+	/** Directory name (or absolute path) containing the plugin code.
+	 * Resolved by `detectPluginType` against the configured roots: an
+	 * absolute path short-circuits; otherwise the shipped `backends/`
+	 * root is tried first, then the user `user-backends/` tree. */
 	dir: string;
 	/** Whether this plugin is active (default: true) */
 	enabled: boolean;
@@ -65,16 +69,11 @@ export interface PluginConfigLoadResult {
 	errors: string[];
 }
 
-/**
- * Unified full configuration result — includes both browser and plugin config.
- */
-export interface FullConfig {
+/** Internal cache for loadFullConfig() — invalidated via invalidateConfigCache() */
+let _fullConfigCache: {
 	browser: BrowserConfig;
 	plugins: PluginConfigLoadResult;
-}
-
-/** Internal cache for loadFullConfig() — invalidated via invalidateConfigCache() */
-let _fullConfigCache: FullConfig | null = null;
+} | null = null;
 
 /**
  * Parse the browser config section from settings JSON.
@@ -129,9 +128,10 @@ function parseBrowserConfig(
  * Extracts and validates the `browser.plugins` array.
  * If no plugins are configured, returns a single default Chromium plugin.
  */
-function parsePluginConfig(
+/** @internal */
+export function parsePluginConfig(
 	raw: Record<string, unknown> | undefined,
-	backendsRoot: string,
+	roots: readonly string[],
 ): PluginConfigLoadResult {
 	const errors: string[] = [];
 
@@ -180,7 +180,7 @@ function parsePluginConfig(
 		if (validated) {
 			// Also validate that the directory exists and is unambiguous
 			try {
-				detectPluginType(validated.dir, backendsRoot);
+				detectPluginType(validated.dir, roots);
 			} catch (err) {
 				errors.push(
 					`plugins[${i}] ('${validated.name}'): ${err instanceof Error ? err.message : String(err)}`,
@@ -222,17 +222,20 @@ function readBrowserConfigRaw(): Record<string, unknown> | undefined {
  * Load and cache the full browser configuration from settings.json.
  *
  * Reads settings.json once on first call and caches the result for
- * subsequent calls. Both `loadBrowserConfig()` and `loadPluginConfig()`
- * delegate to this function.
+ * subsequent calls.
  */
-export function loadFullConfig(backendsRoot?: string): FullConfig {
+export function loadFullConfig(roots?: readonly string[]): {
+	browser: BrowserConfig;
+	plugins: PluginConfigLoadResult;
+} {
 	if (_fullConfigCache) return _fullConfigCache;
 
 	const raw = readBrowserConfigRaw();
+	const effectiveRoots = roots ?? DEFAULT_BACKEND_ROOTS;
 
 	_fullConfigCache = {
 		browser: parseBrowserConfig(raw),
-		plugins: parsePluginConfig(raw, backendsRoot ?? DEFAULT_BACKENDS_ROOT),
+		plugins: parsePluginConfig(raw, effectiveRoots),
 	};
 
 	return _fullConfigCache;
@@ -246,19 +249,6 @@ export function invalidateConfigCache(): void {
 	_fullConfigCache = null;
 }
 
-/**
- * Convenience wrapper — returns the `defaultProfile` setting from the
- * cached browser configuration. Delegates to `loadFullConfig()` which
- * reads `settings.json` once and caches the result.
- *
- * The `browser.defaultProfile` field controls what happens when
- * `browser-navigate` is called without an explicit `profile` parameter.
- * See `BrowserConfig` for valid values.
- */
-export function loadBrowserConfig(): BrowserConfig {
-	return loadFullConfig().browser;
-}
-
 // ─── Validation ───────────────────────────────────────────────────
 
 /**
@@ -332,38 +322,66 @@ function validateEntry(
 /**
  * Detect the plugin type from the directory contents.
  *
+ * Resolution order for `dir`:
+ *   1. **Absolute path** — if `dir` is absolute, it is used directly
+ *      (skips all roots; useful for development / power users).
+ *   2. **Each root in `roots`, in order** — `join(root, dir)`. The first
+ *      root that contains an unambiguous entry point wins.
+ *
+ * Per-root ambiguity: if a single resolved dir contains *both*
+ * `index.ts` and `bridge.py`, that is an error (the original behaviour).
+ * If the first root has `index.ts` and a later root has `bridge.py`, the
+ * first root wins — that is a legitimate multi-root layout, not ambiguity.
+ *
+ * If no resolved dir has any entry point, throws an error naming every
+ * root searched so users can see where the loader looked.
+ *
  * - `backends/<dir>/index.ts` exists → Node plugin
  * - `backends/<dir>/bridge.py` exists → Python plugin
- * - Both exist → error (ambiguous)
- * - Neither exists → error
+ * - Both exist in the same resolved dir → error (ambiguous)
+ * - Neither exists anywhere → error
  */
 export function detectPluginType(
 	dir: string,
-	backendsRoot: string,
+	roots: readonly string[],
 ): PluginDetection {
-	const dirPath = join(backendsRoot, dir);
-	const indexPath = join(dirPath, "index.ts");
-	const bridgePath = join(dirPath, "bridge.py");
+	const candidatePaths: string[] = [];
+	if (isAbsolute(dir)) {
+		candidatePaths.push(dir);
+	} else {
+		for (const root of roots) {
+			candidatePaths.push(join(root, dir));
+		}
+	}
 
-	const hasIndex = existsSync(indexPath);
-	const hasBridge = existsSync(bridgePath);
+	for (const dirPath of candidatePaths) {
+		const indexPath = join(dirPath, "index.ts");
+		const bridgePath = join(dirPath, "bridge.py");
 
-	if (hasIndex && hasBridge) {
-		throw new Error(
-			`Plugin dir '${dir}' is ambiguous: both index.ts and bridge.py found. Remove one.`,
-		);
-	}
+		const hasIndex = existsSync(indexPath);
+		const hasBridge = existsSync(bridgePath);
 
-	if (hasIndex) {
-		return { type: "node", entryPoint: indexPath };
-	}
+		if (hasIndex && hasBridge) {
+			throw new Error(
+				`Plugin dir '${dir}' is ambiguous: both index.ts and bridge.py found in ${dirPath}. Remove one.`,
+			);
+		}
+
+		if (hasIndex) {
+			return { type: "node", entryPoint: indexPath };
+		}
 
-	if (hasBridge) {
-		return { type: "python", entryPoint: bridgePath };
+		if (hasBridge) {
+			return { type: "python", entryPoint: bridgePath };
+		}
 	}
 
+	const searched = candidatePaths.length
+		? candidatePaths.join(", ")
+		: "(no roots provided)";
 	throw new Error(
-		`Plugin dir '${dir}' has no entry point. Expected index.ts (Node) or bridge.py (Python).`,
+		`Plugin dir '${dir}' has no entry point. Expected index.ts (Node) or bridge.py (Python). ` +
+			`Searched: ${searched}`,
 	);
 }
 
@@ -376,13 +394,12 @@ export function detectPluginType(
 export const DEFAULT_BACKENDS_ROOT = join(__dirname, "..", "backends");
 
 /**
- * Load and validate the plugin configuration.
- *
- * If no `browser.plugins` config exists, returns the default fallback
- * (chromium + firefox enabled, chromium-py + firefox-py disabled).
+ * Default root search order for plugin discovery: the shipped package
+ * `backends/` first, then the user-writable `user-backends/` tree under
+ * `~/.pi/agent/pi-lean-portal/`.  Callers may pass a custom `roots`
+ * array (e.g. tests with temp dirs); when omitted, this default is used.
  */
-export function loadPluginConfig(
-	backendsRoot: string = DEFAULT_BACKENDS_ROOT,
-): PluginConfigLoadResult {
-	return loadFullConfig(backendsRoot).plugins;
-}
+export const DEFAULT_BACKEND_ROOTS: readonly string[] = [
+	DEFAULT_BACKENDS_ROOT,
+	USER_BACKENDS_DIR,
+];

package/node_modules/pi-lean-portal/core/plugin-registry.ts

@@ -49,8 +49,6 @@ export function validatePlugin(plugin: BrowserPlugin): string[] {
 /** Internal tracking for a registered plugin */
 interface RegistryEntry {
 	plugin: BrowserPlugin;
-	/** Position in the user's plugins config array (lower = higher priority, used for LLM escalation hints) */
-	level: number;
 	/** Whether this plugin is enabled */
 	enabled: boolean;
 }
@@ -61,7 +59,7 @@ export class PluginRegistry {
 	/** Map of plugin name → registry entry */
 	private entries = new Map<string, RegistryEntry>();
 
-	/** Ordered list of plugin names from config (defines escalation priority — lower index = recommended first) */
+	/** Ordered list of plugin names from config (lower index = higher priority / recommended first) */
 	private orderedNames: string[] = [];
 
 	/**
@@ -72,8 +70,8 @@ export class PluginRegistry {
 	 * plugins loaded via dynamic `import()` vs Python plugins registered
 	 * synchronously).
 	 *
-	 * If `register()` finds its name already in the seeded order, it uses the
-	 * existing position as the priority level instead of appending.
+	 * If `register()` finds its name already in the seeded order, it keeps
+	 * that position instead of appending.
 	 *
 	 * @param names - Plugin names in the desired priority order (typically
 	 *                 the order from the user's `browser.plugins` config array).
@@ -85,9 +83,8 @@ export class PluginRegistry {
 	/**
 	 * Register a plugin with its config.
 	 *
-	 * If the plugin name was pre-seeded via `seedOrder()`, its priority level
-	 * is taken from that pre-determined position. Otherwise it is appended at
-	 * the end.
+	 * If the plugin name was pre-seeded via `seedOrder()`, it keeps that
+	 * position in the ordered list. Otherwise it is appended at the end.
 	 *
 	 * @throws if a plugin with the same name is already registered
 	 * @throws if the plugin is missing required operations
@@ -107,23 +104,17 @@ export class PluginRegistry {
 			);
 		}
 
-		// Determine the level from the pre-seeded orderedNames, or append
-		let level = this.orderedNames.indexOf(plugin.name);
-		if (level === -1) {
-			level = this.orderedNames.length;
+		// Preserve pre-seeded order (from seedOrder); otherwise append.
+		if (!this.orderedNames.includes(plugin.name)) {
 			this.orderedNames.push(plugin.name);
 		}
 
 		this.entries.set(plugin.name, {
 			plugin,
-			level,
 			enabled: config.enabled,
 		});
 	}
 
-	/**
-	 * Get a plugin by name. Returns undefined if not registered or disabled.
-	 */
 	get(name: string): BrowserPlugin | undefined {
 		const entry = this.entries.get(name);
 		if (!entry || !entry.enabled) return undefined;
@@ -152,14 +143,13 @@ export class PluginRegistry {
 
 	/**
 	 * Get all enabled plugins in config order (priority order).
-	 * Each entry includes the plugin and its priority level (lower = recommended first).
 	 */
-	getOrdered(): Array<{ plugin: BrowserPlugin; level: number }> {
-		const result: Array<{ plugin: BrowserPlugin; level: number }> = [];
+	getOrdered(): BrowserPlugin[] {
+		const result: BrowserPlugin[] = [];
 		for (const name of this.orderedNames) {
 			const entry = this.entries.get(name);
 			if (entry?.enabled) {
-				result.push({ plugin: entry.plugin, level: entry.level });
+				result.push(entry.plugin);
 			}
 		}
 		return result;
@@ -169,7 +159,7 @@ export class PluginRegistry {
 	 * List all registered plugin names (enabled only).
 	 */
 	available(): string[] {
-		return this.getOrdered().map((e) => e.plugin.name);
+		return this.getOrdered().map((p) => p.name);
 	}
 
 	/**
@@ -182,26 +172,6 @@ export class PluginRegistry {
 		});
 	}
 
-	/**
-	 * Get the priority level for a plugin (lower = recommended first).
-	 * Used by the LLM to decide whether to escalate to a different backend.
-	 * Returns undefined if the plugin is not registered.
-	 */
-	getLevel(name: string): number | undefined {
-		return this.entries.get(name)?.level;
-	}
-
-	/**
-	 * Get plugins at higher priority levels (further in the backup chain) than the given level.
-	 * Used to suggest alternative backends when bot detection fires.
-	 */
-	getHigherStealth(currentLevel: number): Array<{
-		plugin: BrowserPlugin;
-		level: number;
-	}> {
-		return this.getOrdered().filter((e) => e.level > currentLevel);
-	}
-
 	/**
 	 * Resolve a strategy value to a plugin.
 	 *
@@ -248,16 +218,8 @@ export class PluginRegistry {
 		this.entries.clear();
 		this.orderedNames = [];
 	}
-
-	/**
-	 * Number of registered plugins (enabled and disabled).
-	 */
-	get size(): number {
-		return this.entries.size;
-	}
 }
 
 // ─── Singleton ────────────────────────────────────────────────────
 
-/** Global plugin registry instance */
 export const pluginRegistry = new PluginRegistry();

package/node_modules/pi-lean-portal/core/router.ts

@@ -1,14 +1,6 @@
 /**
  * Plugin Router — registry-based dispatch for interactive browser operations.
- *
- * All dispatch goes through the PluginRegistry, which resolves
- * the correct plugin based on the `strategy` parameter.
- *
- * Cross-cutting concerns handled here (not in plugins):
- * - Snapshot truncation (compactSnapshot)
- * - URL safety validation
- * - Session lifecycle (via sessionManager)
- * - Auto-recovery from crashed sessions (via lastNav)
+ * Handles snapshot truncation, URL safety, session lifecycle, and crash recovery.
  */
 
 import { writeFileSync } from "node:fs";
@@ -30,7 +22,7 @@ import {
 	sanitizeProfileName,
 	sessionProfileName,
 } from "./shared/storage-state.js";
-import { loadBrowserConfig } from "./plugin-config.js";
+import { loadFullConfig } from "./plugin-config.js";
 import {
 	runExtractor,
 	correlateElements,
@@ -38,6 +30,7 @@ import {
 	formatElementList,
 	formatRoleCountSummary,
 	type ExtractResult,
+	type QueryStatus,
 } from "./shared/dom-extractor.js";
 import type {
 	DialogEvent,
@@ -228,16 +221,6 @@ async function requireInteractiveSession(taskId: string): Promise<{
 	return null;
 }
 
-/**
- * Get the plugin for a given session. Returns undefined if the session
- * doesn't exist or the plugin is not available.
- */
-function getPluginForSession(
-	session: BrowserSession,
-): import("./plugin-api.js").BrowserPlugin | undefined {
-	return pluginRegistry.get(session.pluginName);
-}
-
 interface ResolvedSession {
 	tid: string;
 	session: BrowserSession;
@@ -255,7 +238,7 @@ async function resolveSession(
 	const tid = taskId ?? "default";
 	const sr = await requireInteractiveSession(tid);
 	if (!sr) return null;
-	const plugin = getPluginForSession(sr.session);
+	const plugin = pluginRegistry.get(sr.session.pluginName);
 	if (!plugin) return null;
 	return {
 		tid,
@@ -463,7 +446,7 @@ export async function navigate(
 	let resolvedProfileName: string | undefined;
 	let profileMode: "none" | "session" | "named" | undefined;
 
-	const browserConfig = loadBrowserConfig();
+	const browserConfig = loadFullConfig().browser;
 	const profileInput = options.profile ?? browserConfig.defaultProfile;
 
 	if (profileInput === "none") {
@@ -731,13 +714,16 @@ export async function snapshot(
 
 // ─── Interaction tools ──────────────────────────────────────────────
 
-export async function click(
+/** Shared shape for the 5 ref-based interaction tools (click/type/scroll/goBack/press). */
+async function wrapInteraction(
 	taskId: string | undefined,
-	ref: string,
+	run: (
+		plugin: import("./plugin-api.js").BrowserPlugin,
+		tid: string,
+	) => Promise<InteractionResult>,
 ): Promise<InteractionResult> {
 	const resolved = await resolveSession(taskId);
 	if (!resolved) return noSessionError();
-
 	return refBasedInteractionOrSnapshot(
 		resolved.tid,
 		resolved.wasAutoCreated,
@@ -745,83 +731,44 @@ export async function click(
 		async () =>
 			compactInteractionResult(
 				resolved.tid,
-				await resolved.plugin.click(resolved.tid, ref),
+				await run(resolved.plugin, resolved.tid),
 			),
 	);
 }
 
+export async function click(
+	taskId: string | undefined,
+	ref: string,
+): Promise<InteractionResult> {
+	return wrapInteraction(taskId, (plugin, tid) => plugin.click(tid, ref));
+}
+
 export async function type(
 	taskId: string | undefined,
 	ref: string,
 	text: string,
 ): Promise<InteractionResult> {
-	const resolved = await resolveSession(taskId);
-	if (!resolved) return noSessionError();
-
-	return refBasedInteractionOrSnapshot(
-		resolved.tid,
-		resolved.wasAutoCreated,
-		resolved.plugin,
-		async () =>
-			compactInteractionResult(
-				resolved.tid,
-				await resolved.plugin.type(resolved.tid, ref, text),
-			),
-	);
+	return wrapInteraction(taskId, (plugin, tid) => plugin.type(tid, ref, text));
 }
 
 export async function scroll(
 	taskId: string | undefined,
 	direction: "up" | "down",
 ): Promise<InteractionResult> {
-	const resolved = await resolveSession(taskId);
-	if (!resolved) return noSessionError();
-
-	return refBasedInteractionOrSnapshot(
-		resolved.tid,
-		resolved.wasAutoCreated,
-		resolved.plugin,
-		async () =>
-			compactInteractionResult(
-				resolved.tid,
-				await resolved.plugin.scroll(resolved.tid, direction),
-			),
+	return wrapInteraction(taskId, (plugin, tid) =>
+		plugin.scroll(tid, direction),
 	);
 }
 
 export async function goBack(taskId?: string): Promise<InteractionResult> {
-	const resolved = await resolveSession(taskId);
-	if (!resolved) return noSessionError();
-
-	return refBasedInteractionOrSnapshot(
-		resolved.tid,
-		resolved.wasAutoCreated,
-		resolved.plugin,
-		async () =>
-			compactInteractionResult(
-				resolved.tid,
-				await resolved.plugin.goBack(resolved.tid),
-			),
-	);
+	return wrapInteraction(taskId, (plugin, tid) => plugin.goBack(tid));
 }
 
 export async function press(
 	taskId: string | undefined,
 	key: string,
 ): Promise<InteractionResult> {
-	const resolved = await resolveSession(taskId);
-	if (!resolved) return noSessionError();
-
-	return refBasedInteractionOrSnapshot(
-		resolved.tid,
-		resolved.wasAutoCreated,
-		resolved.plugin,
-		async () =>
-			compactInteractionResult(
-				resolved.tid,
-				await resolved.plugin.press(resolved.tid, key),
-			),
-	);
+	return wrapInteraction(taskId, (plugin, tid) => plugin.press(tid, key));
 }
 
 /**
@@ -992,17 +939,24 @@ export async function browserInspect(
 			};
 		}
 
-		// Run the DOM extractor
-		const extracted = await runExtractor(tid, plugin);
-		if (!extracted) {
+		// Run the DOM extractor. The !cacheExists guard above guarantees
+		// cache is non-null and non-empty here, so we always route to the
+		// live-cache query hint on failure.
+		const outcome = await runExtractor(tid, plugin);
+		if (!outcome.ok) {
 			return {
 				success: false,
 				content: "",
 				error:
-					"Text extraction returned no content. The page may be empty, blocked, or strict CSP prevents DOM access. Use browser-snapshot to inspect visually.",
+					`Text extraction failed: ${outcome.error}. ` +
+					`A live element cache (${cache!.size} elements) is available — ` +
+					"use browser-inspect with role=, name=, or ref= to query it, " +
+					"or browser-snapshot to refresh.",
 			};
 		}
 
+		const extracted = outcome.result;
+
 		// Keyword filtering — case-insensitive substring match on extracted text
 		if (params.query) {
 			applyQueryFilter(extracted, params.query);
@@ -1044,16 +998,30 @@ export async function browserInspect(
 			};
 		}
 
-		const filtered = queryElementCache(cache!, {
-			...(params.role !== undefined ? { role: params.role } : {}),
-			...(params.name !== undefined ? { name: params.name } : {}),
-			...(params.ref !== undefined ? { ref: params.ref } : {}),
-			...(params.subtree !== undefined ? { subtree: params.subtree } : {}),
-		});
+		const status: QueryStatus = {};
+		const filtered = queryElementCache(
+			cache!,
+			{
+				...(params.role !== undefined ? { role: params.role } : {}),
+				...(params.name !== undefined ? { name: params.name } : {}),
+				...(params.ref !== undefined ? { ref: params.ref } : {}),
+				...(params.subtree !== undefined ? { subtree: params.subtree } : {}),
+			},
+			status,
+		);
 
-		const content = formatElementList(filtered, {
-			...(params.ref !== undefined ? { ref: params.ref } : {}),
-		});
+		let content: string;
+		if (filtered.length === 0 && status.refFilteredOut) {
+			const { node, filter, value } = status.refFilteredOut;
+			content =
+				`Element @${node.ref} found in cache (role=${node.role}` +
+				`${node.name ? `, name="${node.name}"` : ""}) but does not match ` +
+				`filter ${filter}="${value}". Drop the ${filter} filter or adjust it.`;
+		} else {
+			content = formatElementList(filtered, {
+				...(params.ref !== undefined ? { ref: params.ref } : {}),
+			});
+		}
 
 		return {
 			success: true,
@@ -1090,13 +1058,6 @@ export async function browserInspect(
 function applyQueryFilter(extracted: ExtractResult, query: string): void {
 	const q = query.toLowerCase();
 
-	const beforeCount =
-		extracted.headings.length +
-		extracted.paragraphs.length +
-		extracted.links.length +
-		extracted.images.length +
-		extracted.interactive.length;
-
 	extracted.headings = extracted.headings.filter((h) =>
 		h.text.toLowerCase().includes(q),
 	);
@@ -1122,7 +1083,7 @@ function applyQueryFilter(extracted: ExtractResult, query: string): void {
 		extracted.interactive.length;
 
 	// Signal empty results so the agent doesn't get a silent empty page
-	if (beforeCount > 0 && afterCount === 0) {
+	if (afterCount === 0) {
 		extracted.paragraphs.push({
 			text: `⚠ No content matched "${query}". Try a different keyword or remove the query parameter.`,
 		});