pi-lean-portal 0.1.0

package/core/plugin-api.ts

@@ -0,0 +1,302 @@
+/**
+ * Plugin Architecture v2 — Core Interface & Unified Result Types
+ *
+ * This module defines the contract that every interactive browser backend
+ * must satisfy.  The 12 required operations map to the registered tools
+ * (screenshot is required internally for auto-capture). Lifecycle hooks
+ * (init, cleanupAll) are called by the framework.
+ *
+ * Plugins return **raw results**.  The router is responsible for
+ * cross-cutting transformations (truncation, count fields, botDetected
+ * warning injection, etc.).
+ */
+
+import type { AriaCachedNode } from "./shared/accessibility-tree.js";
+
+// ─── Capabilities ────────────────────────────────────────────────
+
+/**
+ * Read-only capabilities that a plugin advertises.  The router uses
+ * these to adapt behaviour (e.g. fall back from fullPage to viewport
+ * screenshot when unsupported).
+ */
+export interface PluginCapabilities {
+	/** Can take full-page screenshots */
+	supportsFullPageScreenshot: boolean;
+	/** Can capture console messages via CDP or equivalent */
+	supportsConsoleCapture: boolean;
+	/** Can evaluate arbitrary JavaScript in the page */
+	supportsJavaScriptEvaluate: boolean;
+	/** Can detect bot/anti-automation signals (Cloudflare, CAPTCHA, etc.) */
+	supportsBotDetection: boolean;
+	/** Can auto-dismiss JS dialogs (alert/confirm/prompt) */
+	supportsDialogAutoDismissal: boolean;
+	/** Can accept an AbortSignal for long-running navigations */
+	supportsAbortSignal: boolean;
+	/** Browser engine (used for display/debugging only) */
+	engine: "chromium" | "firefox" | "webkit" | string;
+}
+
+/** Default capabilities matching a full-featured Chromium backend. */
+export const DEFAULT_CAPABILITIES: PluginCapabilities = {
+	supportsFullPageScreenshot: true,
+	supportsConsoleCapture: true,
+	supportsJavaScriptEvaluate: true,
+	supportsBotDetection: true,
+	supportsDialogAutoDismissal: true,
+	supportsAbortSignal: true,
+	engine: "chromium",
+};
+
+// ─── Unified Result Types ─────────────────────────────────────────
+
+/**
+ * A JavaScript dialog event (alert, confirm, prompt, beforeunload) that was
+ * auto-dismissed by the browser plugin.  Returned as part of navigate,
+ * snapshot, and interaction results so the router can surface them to
+ * the agent without polluting the accessibility tree text.
+ */
+export interface DialogEvent {
+	/** Dialog type as reported by the browser */
+	type: string;
+	/** Dialog message text */
+	message: string;
+	/** How the dialog was handled (always "accepted" for auto-dismiss) */
+	handledAs: "accepted" | "dismissed";
+}
+
+/**
+ * Base shape shared by all result types.
+ * Operations return `{ success: false, error }` for expected failures.
+ * They **may throw** for infrastructure failures (process crash, OOM).
+ * The router catches throws and normalises them.
+ */
+export interface ResultBase {
+	success: boolean;
+	error?: string;
+}
+
+/** Result from browser-navigate */
+export interface NavigateResult extends ResultBase {
+	url: string;
+	title: string;
+	/** Accessibility-tree text with @e refs */
+	snapshot: string;
+	/** Number of interactive elements found */
+	elementCount: number;
+	/** Plugin-internal signal: page may be blocked by bot detection */
+	botDetected?: boolean;
+	/** Whether a dialog (role="dialog" or role="alertdialog") was detected in the parsed element cache */
+	dialogDetected?: boolean;
+	/** Auto-dismissed JavaScript dialogs (alert/confirm/prompt) since last navigate */
+	dialogEvents?: DialogEvent[];
+	/** The active profile mode for this session. */
+	profileMode?: "none" | "session" | "named";
+	/** Which profile was loaded for this session (if any) */
+	profileName?: string;
+}
+
+/** Result from browser-snapshot */
+export interface SnapshotResult extends ResultBase {
+	/** Accessibility-tree text with @e refs */
+	snapshot: string;
+	/** Number of interactive elements found */
+	elementCount: number;
+	/** Auto-dismissed JavaScript dialogs (alert/confirm/prompt) since last snapshot */
+	dialogEvents?: DialogEvent[];
+}
+
+/** Result from interaction tools (click, type, scroll, goBack, press) */
+export interface InteractionResult extends ResultBase {
+	/** URL after the interaction (if navigation occurred) */
+	newUrl?: string;
+	/** Title after the interaction (if navigation occurred) */
+	newTitle?: string;
+	/** Auto-captured snapshot after the interaction */
+	snapshot?: string;
+	/** Number of interactive elements in the auto-snapshot */
+	elementCount?: number;
+	/** Auto-dismissed JavaScript dialogs since the interaction */
+	dialogEvents?: DialogEvent[];
+}
+
+/** Result from plugin.screenshot() */
+export interface ScreenshotResult extends ResultBase {
+	/** JPEG data URI of the screenshot */
+	dataUri: string;
+}
+
+/** Result from getConsoleMessages */
+export interface ConsoleMessagesResult extends ResultBase {
+	messages: Array<{ type: string; text: string }>;
+}
+
+/** Result from evaluate (browser-console JS eval) */
+export interface EvaluateResult extends ResultBase {
+	result?: unknown;
+}
+
+// ─── Cookie & Storage State Types ─────────────────────────────────
+
+/**
+ * A single browser cookie, matching Playwright's Cookie shape.
+ * Fields are optional to accommodate both directions:
+ * - Reading (cookies() output): all fields are always populated
+ * - Writing (addCookies() input): domain and path are effectively required
+ *   at runtime by Playwright; sameSite defaults to browser policy (Lax).
+ */
+export interface Cookie {
+	name: string;
+	value: string;
+	domain?: string;
+	path?: string;
+	/** Unix timestamp in seconds; -1 for session cookies */
+	expires?: number;
+	httpOnly?: boolean;
+	secure?: boolean;
+	sameSite?: "Strict" | "Lax" | "None";
+}
+
+/** Result from browser-getCookies */
+export interface CookieResult extends ResultBase {
+	cookies: Cookie[];
+}
+
+/** Options for browser-clearCookies — all fields optional (omit all to clear everything) */
+export interface ClearCookiesOptions {
+	name?: string;
+	domain?: string;
+	path?: string;
+}
+
+/** Result from browser-getStorageState */
+export interface StorageStateResult extends ResultBase {
+	cookies: Cookie[];
+	origins: Array<{
+		origin: string;
+		localStorage: Array<{ name: string; value: string }>;
+	}>;
+}
+
+// ─── BrowserPlugin Interface ──────────────────────────────────────
+
+/**
+ * The contract every interactive browser backend must implement.
+ *
+ * The 12 required operations (plus getElementCache and cookie/storage
+ * methods) make up the full contract. Lifecycle hooks are called by
+ * the framework, not the agent.
+ */
+export interface BrowserPlugin {
+	// ── Identity ───────────────────────────────────────────────
+	/** Unique stable identifier (e.g. "chromium", "camoufox") */
+	readonly name: string;
+
+	/** Advertised capabilities — read by the router for adaptation */
+	readonly capabilities: PluginCapabilities;
+
+	// ── Lifecycle hooks (framework-triggered) ─────────────────
+
+	/**
+	 * Optional one-time initialisation.  Called once at plugin
+	 * registration (extension startup).  Receives the `config` bag
+	 * from `settings.json`.
+	 */
+	init?(config?: Record<string, unknown>): Promise<void>;
+
+	/**
+	 * Required shutdown hook.  Called on extension shutdown.
+	 * Cleans up ALL sessions and resources (browsers, subprocesses, etc.).
+	 */
+	cleanupAll(): Promise<void>;
+
+	// ── Navigation & state ────────────────────────────────────
+
+	navigate(
+		url: string,
+		taskId: string,
+		timeoutMs: number,
+		options?: {
+			signal?: AbortSignal;
+			/** Playwright storage state for profile-based session restoration */
+			storageState?: unknown;
+			/** Profile name for shared-context resolution */
+			profileName?: string;
+			/** Profile mode for shared-context resolution */
+			profileMode?: "none" | "session" | "named";
+		},
+	): Promise<NavigateResult>;
+
+	snapshot(taskId: string): Promise<SnapshotResult>;
+
+	// ── Cookies & storage state ────────────────────────────────
+
+	/**
+	 * Get all browser cookies for the session, optionally filtered by URL.
+	 */
+	getCookies(taskId: string, urls?: string[]): Promise<CookieResult>;
+
+	/**
+	 * Add cookies to the browser context.
+	 * Playwright requires name, value, domain, and path at runtime.
+	 */
+	addCookies(taskId: string, cookies: Cookie[]): Promise<ResultBase>;
+
+	/**
+	 * Clear cookies from the browser context.
+	 * With no options, ALL cookies are cleared (Playwright default).
+	 */
+	clearCookies(
+		taskId: string,
+		options?: ClearCookiesOptions,
+	): Promise<ResultBase>;
+
+	/**
+	 * Get the full storage state (cookies + localStorage + IndexedDB).
+	 * Primarily used by storage-state persistence.
+	 */
+	getStorageState(taskId: string): Promise<StorageStateResult>;
+
+	// ── Interaction ───────────────────────────────────────────
+
+	click(taskId: string, ref: string): Promise<InteractionResult>;
+
+	type(taskId: string, ref: string, text: string): Promise<InteractionResult>;
+
+	scroll(taskId: string, direction: "up" | "down"): Promise<InteractionResult>;
+
+	goBack(taskId: string): Promise<InteractionResult>;
+
+	press(taskId: string, key: string): Promise<InteractionResult>;
+
+	// ── Media ─────────────────────────────────────────────────
+
+	screenshot(
+		taskId: string,
+		options?: { fullPage?: boolean },
+	): Promise<ScreenshotResult>;
+
+	// ── Console & eval ────────────────────────────────────────
+
+	getConsoleMessages(taskId: string): Promise<ConsoleMessagesResult>;
+
+	clearConsole(taskId: string): Promise<void>;
+
+	evaluate(taskId: string, expression: string): Promise<EvaluateResult>;
+
+	// ── Element cache access ─────────────────────────────────
+
+	/**
+	 * Return the plugin's element cache for the given task.
+	 * Returns null if the session/task has no cache (navigate or snapshot
+	 * has not been called yet).
+	 */
+	getElementCache(taskId: string): Map<string, AriaCachedNode> | null;
+
+	// ── Per-task cleanup ──────────────────────────────────────
+
+	/**
+	 * Clean up resources for a specific task (browser context, page, etc.).
+	 */
+	cleanup(taskId: string): Promise<void>;
+}

package/core/plugin-config.ts

@@ -0,0 +1,388 @@
+/**
+ * Plugin Config Loader — reads browser.plugins from settings.json,
+ * validates entries, detects plugin type, and provides typed PluginConfig[].
+ *
+ * Config is read once at startup. Hot-reload is future work.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+// ─── 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 */
+	dir: string;
+	/** Whether this plugin is active (default: true) */
+	enabled: boolean;
+	/** Plugin-specific overrides passed to init() */
+	config: Record<string, unknown>;
+}
+
+/** Plugin type — determines how the plugin is loaded and run */
+export type PluginType = "node" | "python";
+
+/** Result of inspecting a plugin directory for type detection */
+export interface PluginDetection {
+	type: PluginType;
+	/** Absolute or relative path to the entry point */
+	entryPoint: string;
+}
+import { sanitizeProfileName } from "./shared/storage-state.js";
+import { readMergedSettings } from "./shared/settings-reader.js";
+
+// ─── Config types & loading ────────────────────────────────────────
+
+/**
+ * Parsed browser configuration from settings.json.
+ * Provides defaults for all fields — every field is always present.
+ */
+export interface BrowserConfig {
+	/**
+	 * Default profile mode or named profile when `browser-navigate` omits the `profile` parameter.
+	 * - "none": clean slate, no persistence
+	 * - "session": persist for this conversation
+	 * - A named profile string (e.g. "shopping", "work")
+	 */
+	defaultProfile: "none" | "session" | string;
+}
+
+/** Raw plugin entry from settings.json (before validation) */
+interface RawPluginEntry {
+	name?: unknown;
+	dir?: unknown;
+	enabled?: unknown;
+	config?: unknown;
+}
+
+/** Result of loading and validating the plugin config */
+export interface PluginConfigLoadResult {
+	/** Validated plugin configs in order */
+	plugins: PluginConfig[];
+	/** Validation errors (non-fatal — logged but not thrown) */
+	errors: string[];
+}
+
+/**
+ * Unified full configuration result — includes both browser and plugin config.
+ */
+export interface FullConfig {
+	browser: BrowserConfig;
+	plugins: PluginConfigLoadResult;
+}
+
+/** Internal cache for loadFullConfig() — invalidated via invalidateConfigCache() */
+let _fullConfigCache: FullConfig | null = null;
+
+/**
+ * Parse the browser config section from settings JSON.
+ * Extracts and validates defaultProfile.
+ */
+function parseBrowserConfig(
+	raw: Record<string, unknown> | undefined,
+): BrowserConfig {
+	const errors: string[] = [];
+
+	// Defaults
+	const config: BrowserConfig = {
+		defaultProfile: "session",
+	};
+
+	if (!raw) return config;
+
+	// ── defaultProfile ───────────────────────────────────────────
+	if (raw.defaultProfile !== undefined) {
+		if (typeof raw.defaultProfile === "string" && raw.defaultProfile.trim()) {
+			const v = raw.defaultProfile.trim();
+			// Validate: "none", "session", or a named profile
+			if (v === "none" || v === "session") {
+				config.defaultProfile = v;
+			} else {
+				try {
+					config.defaultProfile = sanitizeProfileName(v);
+				} catch (err) {
+					errors.push(
+						`browser.defaultProfile: ${err instanceof Error ? err.message : String(err)}`,
+					);
+				}
+			}
+		} else {
+			errors.push(
+				`browser.defaultProfile: expected a non-empty string, got ${typeof raw.defaultProfile}`,
+			);
+		}
+	}
+
+	// Log validation errors (non-fatal, but surfaced in return)
+	for (const err of errors) {
+		console.warn(`[pi-lean-portal] Config warning: ${err}`);
+	}
+
+	return config;
+}
+
+/**
+ * Parse and validate the plugin config section from settings JSON.
+ *
+ * Extracts and validates the `browser.plugins` array.
+ * If no plugins are configured, returns a single default Chromium plugin.
+ */
+function parsePluginConfig(
+	raw: Record<string, unknown> | undefined,
+	backendsRoot: string,
+): PluginConfigLoadResult {
+	const errors: string[] = [];
+
+	// Extract plugins from the raw browser config section
+	const rawPlugins = raw?.["plugins"];
+
+	// Default fallback: chromium + firefox enabled, python backends disabled
+	if (!Array.isArray(rawPlugins)) {
+		return {
+			plugins: [
+				{
+					name: "chromium",
+					dir: "chromium",
+					enabled: true,
+					config: {},
+				},
+				{
+					name: "firefox",
+					dir: "firefox",
+					enabled: true,
+					config: {},
+				},
+				{
+					name: "chromium-py",
+					dir: "chromium-py",
+					enabled: false,
+					config: {},
+				},
+				{
+					name: "firefox-py",
+					dir: "firefox-py",
+					enabled: false,
+					config: {},
+				},
+			],
+			errors: [],
+		};
+	}
+
+	// Validate each entry
+	const seenNames = new Set<string>();
+	const plugins: PluginConfig[] = [];
+
+	for (let i = 0; i < rawPlugins.length; i++) {
+		const validated = validateEntry(rawPlugins[i], i, errors, seenNames);
+		if (validated) {
+			// Also validate that the directory exists and is unambiguous
+			try {
+				detectPluginType(validated.dir, backendsRoot);
+			} catch (err) {
+				errors.push(
+					`plugins[${i}] ('${validated.name}'): ${err instanceof Error ? err.message : String(err)}`,
+				);
+				continue; // Skip this plugin
+			}
+			plugins.push(validated);
+		}
+	}
+
+	return { plugins, errors };
+}
+
+/**
+ * Read the merged browser config object from settings.json.
+ *
+ * Looks in:
+ *   1. `~/.pi/agent/settings.json` (global)
+ *   2. `.pi/settings.json` (project-local, overrides global)
+ *
+ * Returns the browser config object, or undefined if not present or invalid.
+ */
+function readBrowserConfigRaw(): Record<string, unknown> | undefined {
+	const merged = readMergedSettings();
+	const browserConfig = merged["browser"];
+
+	if (
+		!browserConfig ||
+		typeof browserConfig !== "object" ||
+		Array.isArray(browserConfig)
+	) {
+		return undefined;
+	}
+
+	return browserConfig as Record<string, unknown>;
+}
+
+/**
+ * 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.
+ */
+export function loadFullConfig(backendsRoot?: string): FullConfig {
+	if (_fullConfigCache) return _fullConfigCache;
+
+	const raw = readBrowserConfigRaw();
+
+	_fullConfigCache = {
+		browser: parseBrowserConfig(raw),
+		plugins: parsePluginConfig(raw, backendsRoot ?? DEFAULT_BACKENDS_ROOT),
+	};
+
+	return _fullConfigCache;
+}
+
+/**
+ * Invalidate the config cache — forces the next call to re-read from disk.
+ * Used in tests to reset state between test cases.
+ */
+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 ───────────────────────────────────────────────────
+
+/**
+ * Validate a single raw plugin entry from settings.json.
+ * Returns a PluginConfig if valid, or adds errors to the error list.
+ */
+function validateEntry(
+	raw: unknown,
+	index: number,
+	errors: string[],
+	seenNames: Set<string>,
+): PluginConfig | null {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+		errors.push(
+			`plugins[${index}]: Entry must be an object, got ${typeof raw}`,
+		);
+		return null;
+	}
+
+	const entry = raw as RawPluginEntry;
+
+	// name is required
+	if (typeof entry.name !== "string" || !entry.name.trim()) {
+		errors.push(
+			`plugins[${index}]: 'name' is required and must be a non-empty string`,
+		);
+		return null;
+	}
+
+	const name = entry.name.trim();
+
+	// Check for duplicate names
+	if (seenNames.has(name)) {
+		errors.push(`plugins[${index}]: Duplicate plugin name '${name}'`);
+		return null;
+	}
+	seenNames.add(name);
+
+	// dir is required
+	if (typeof entry.dir !== "string" || !entry.dir.trim()) {
+		errors.push(
+			`plugins[${index}]: 'dir' is required and must be a non-empty string`,
+		);
+		return null;
+	}
+
+	const dir = entry.dir.trim();
+
+	// enabled defaults to true
+	const enabled = typeof entry.enabled === "boolean" ? entry.enabled : true;
+
+	// config must be an object if provided
+	let config: Record<string, unknown> = {};
+	if (entry.config !== undefined) {
+		if (
+			typeof entry.config !== "object" ||
+			Array.isArray(entry.config) ||
+			entry.config === null
+		) {
+			errors.push(`plugins[${index}]: 'config' must be an object if provided`);
+		} else {
+			config = entry.config as Record<string, unknown>;
+		}
+	}
+
+	return { name, dir, enabled, config };
+}
+
+// ─── Plugin type detection ────────────────────────────────────────
+
+/**
+ * Detect the plugin type from the directory contents.
+ *
+ * - `backends/<dir>/index.ts` exists → Node plugin
+ * - `backends/<dir>/bridge.py` exists → Python plugin
+ * - Both exist → error (ambiguous)
+ * - Neither exists → error
+ */
+export function detectPluginType(
+	dir: string,
+	backendsRoot: string,
+): PluginDetection {
+	const dirPath = join(backendsRoot, dir);
+	const indexPath = join(dirPath, "index.ts");
+	const bridgePath = join(dirPath, "bridge.py");
+
+	const hasIndex = existsSync(indexPath);
+	const hasBridge = existsSync(bridgePath);
+
+	if (hasIndex && hasBridge) {
+		throw new Error(
+			`Plugin dir '${dir}' is ambiguous: both index.ts and bridge.py found. Remove one.`,
+		);
+	}
+
+	if (hasIndex) {
+		return { type: "node", entryPoint: indexPath };
+	}
+
+	if (hasBridge) {
+		return { type: "python", entryPoint: bridgePath };
+	}
+
+	throw new Error(
+		`Plugin dir '${dir}' has no entry point. Expected index.ts (Node) or bridge.py (Python).`,
+	);
+}
+
+// ─── Main loader ───────────────────────────────────────────────────
+
+/**
+ * Default backends root — relative to this file.
+ * core/plugin-config.ts → backends/ is ../../backends/
+ */
+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).
+ */
+export function loadPluginConfig(
+	backendsRoot: string = DEFAULT_BACKENDS_ROOT,
+): PluginConfigLoadResult {
+	return loadFullConfig(backendsRoot).plugins;
+}