pi-lean-portal 0.2.1 → 0.2.3

package/README.md

@@ -6,9 +6,7 @@
 > domain. A `/web` toggle removes the tools from the agent's context when
 > switched off, so web browsing doesn't consume tokens on sessions that aren't
 > doing web work. If a site blocks the shipped browsers, drop in your own
-> backend (e.g. [Camoufox](https://github.com/daijro/camoufox)) - as far as
-> we're aware, no other Pi web plugin lets you run a browser backend you wrote
-> yourself.
+> backend (e.g. [Camoufox](https://github.com/daijro/camoufox)).
 >
 > Part of the [pi-lean-dimension](https://github.com/coreyryanhanson/pi-lean-dimension)
 > web-tools suite. For SearXNG search support, install
@@ -42,7 +40,7 @@ npx playwright install chromium firefox
 
 Once loaded, you'll see a notification like:
 
-> 🌐 Browser extension loaded (plugins: chromium, firefox)
+> 🌐 Browser extension loaded (plugins: chromium, firefox). Try: web-fetch for static pages or browser-navigate for interactive browsing.
 
 The browser tools are **enabled by default**. You can:
 
@@ -122,7 +120,8 @@ which defaults to `true`).
 **Auto-captured screenshots:** `browser-navigate` and `browser-snapshot` automatically
 capture a screenshot to a temp file (`/tmp/pi-lean-portal/screenshot-<taskId>.jpg`).
 Use the `read` tool to visually inspect the page when the accessibility tree isn't enough.
-No viewport resizing occurs — screenshots are captured at the native 1280px width.
+Screenshots capture the 1280×720 viewport (not full-page) — the same viewport the
+browser uses for navigation.
 
 ### 1. `browser-navigate` — Visit a Page
 
@@ -201,7 +200,7 @@ Navigates back in browser history. Returns the previous page's snapshot.
 browser-press key="Enter"
 ```
 
-Useful keys: `Enter`, `Tab`, `Escape`, `ArrowDown`, `ArrowUp`, `/`.
+Useful keys: `Enter`, `Tab`, `Escape`, `ArrowDown`, `ArrowUp`, `Backspace`.
 
 ### 8. `browser-console` — Read Console / Run JS
 
@@ -285,7 +284,7 @@ navigation guidance for specific sites using `web-learn`.
 web-learn domain="reddit.com" content="…guidance text…"
 ```
 
-This creates a `.md` file with YAML frontmatter in the `guides/` directory.
+This creates a `.md` file with YAML frontmatter in `~/.pi/agent/pi-lean-portal/web-guides/`.
 The guide becomes available immediately via `web-guide` and appears in the guide footer on
 future navigations to that domain.
 
@@ -306,12 +305,13 @@ Shows everything about the browser runtime in one notification:
 🌐 Browser tools: ✅ on  |  📖 Learn mode: ❌ off
 ────────────────────────────────────────
 Status: idle
-Plugins: chromium
+Plugins: chromium, firefox, chromium-py (disabled), firefox-py (disabled)
+Use web-fetch for stateless HTTP fetches.
 Active sessions: 1
   PW [chromium] https://example.com — Example Domain [profile: session]
-Profiles: 2 on disk
-  📋 session  (2.1 KB) ← active
-  shopping  (0.3 KB)
+Profiles: 1 on disk (named)
+  shopping  (0.3 KB) ← active
+Session profiles: 1 (manage with /web profile)
 ```
 
 Covers:
@@ -320,7 +320,9 @@ Covers:
 - **Backend health** — idle, busy, or error state
 - **All registered plugins** — enabled/disabled status
 - **Active sessions** — current URL, title, profile name per session
-- **Profiles on disk** — state size and which one is currently active
+- **Profiles on disk** — named profiles with state size and which is
+  currently active; session profiles are collapsed into a single count line
+  (inspect individually with `/web profile list`)
 
 When `pi-lean-search` is also installed, the status bar shows two independent
 glyphs: `● idle` (browser state) and `● searxng` (search health/state).
@@ -593,7 +595,7 @@ Size threshold for profile state warnings (default: 10 MB):
 ```jsonc
 {
   "browser": {
-    "maxStorageStateSize": 10485760  
+    "maxStorageStateSize": 10485760
   }
 }
 ```
@@ -614,8 +616,9 @@ Size threshold for profile state warnings (default: 10 MB):
 ### Working with `@e` Element References
 
 - `@e1`, `@e2`, etc. are assigned based on the accessibility tree order
-- After clicking or scrolling, **always take a fresh snapshot** — old `@e`
-  refs become stale
+- `browser-click`/`type`/`scroll` already return a fresh snapshot and cache
+  the full tree to disk — no separate `browser-snapshot` needed unless you
+  want the uncompacted tree (`full=true`) or a screenshot
 - `browser-inspect` is cheaper than `browser-snapshot full=true` for finding
   specific elements
 
@@ -623,8 +626,9 @@ Size threshold for profile state warnings (default: 10 MB):
 
 - Snapshots are automatically compacted to ~2500 characters
 - Very large pages (>8000 chars) preserve the top ~2000 chars
-- The **full tree is cached to disk** at `/tmp/pi-lean-portal/snapshot-*.txt` —
-  you can use `read` on the cache file with offset/limit
+- The **full tree is cached to disk** at `/tmp/pi-lean-portal/snapshot-*.txt`
+  when it would otherwise be truncated — use `read` on the cache file with
+  offset/limit to retrieve the complete tree
 - `browser-inspect text=true query="keyword"` finds specific content without
   loading the full tree
 
@@ -636,8 +640,14 @@ When a page triggers anti-automation:
 2. The **bot-detection guide** footer appears with strategies available via `web-guide`
 3. If very few elements are detected (<5), the navigation is treated as
    a hard failure — the agent won't try to interact with a challenge page
-4. Try `web-fetch` on the same URL — it sometimes succeeds where the
-   interactive browser doesn't
+4. Retry with a stealth backend — the `browser-navigate` `strategy`
+   parameter lists registered backend names; a stealth backend (e.g.
+   `strategy="camoufox"`) can pass challenges the default `chromium`/
+   `firefox` triggers. Only names listed in the `strategy` description
+   are valid — there is no `"stealth"` alias
+5. Try `web-fetch` on the same URL — it skips JS execution, so it can
+   retrieve raw HTML on pages that block the interactive browser via
+   client-side fingerprinting (it won't help against server-side WAFs)
 
 ### Guide Creation Discipline
 

package/backends/playwright-base/playwright-plugin.ts

@@ -31,6 +31,7 @@ import { NAV_SETTLE } from "../../core/shared/browser-data.js";
 import { join } from "node:path";
 import { mkdirSync } from "node:fs";
 import { persistSessionState } from "../../core/shared/storage-state.js";
+import { loadFullConfig } from "../../core/plugin-config.js";
 import type {
 	BrowserPlugin,
 	PluginCapabilities,
@@ -422,7 +423,12 @@ export abstract class PlaywrightPluginBase implements BrowserPlugin {
 		context: BrowserContext,
 	): Promise<{ cookies: unknown[]; origins: unknown[] } | undefined> {
 		const session = sessionManager.getSession(taskId);
-		return persistSessionState(session, () => context.storageState());
+		return persistSessionState(
+			session,
+			() => context.storageState(),
+			"",
+			loadFullConfig().browser.maxStorageStateSize,
+		);
 	}
 
 	private async takeSnapshot(
@@ -656,19 +662,28 @@ export abstract class PlaywrightPluginBase implements BrowserPlugin {
 			};
 		}
 
-		return this._logOp("snapshot", { taskId }, async () => {
-			const {
-				snapshot: snapText,
-				elementCount,
-				dialogEvents,
-			} = await this.takeSnapshot(taskId, page);
-			return {
-				success: true,
-				snapshot: snapText,
-				elementCount,
-				dialogEvents,
-			};
-		}, (r) => ({ elementCount: r.elementCount, dialogEvents: r.dialogEvents.length, fingerprint: r.snapshot.slice(0, 16) }));
+		return this._logOp(
+			"snapshot",
+			{ taskId },
+			async () => {
+				const {
+					snapshot: snapText,
+					elementCount,
+					dialogEvents,
+				} = await this.takeSnapshot(taskId, page);
+				return {
+					success: true,
+					snapshot: snapText,
+					elementCount,
+					dialogEvents,
+				};
+			},
+			(r) => ({
+				elementCount: r.elementCount,
+				dialogEvents: r.dialogEvents.length,
+				fingerprint: r.snapshot.slice(0, 16),
+			}),
+		);
 	}
 
 	// ── Interaction ────────────────────────────────────────────
@@ -713,39 +728,46 @@ export abstract class PlaywrightPluginBase implements BrowserPlugin {
 			};
 		}
 
-		return this._logOp("click", { taskId, ref, role: node.role, name: node.name }, async () => {
-			try {
-				const urlBefore = page.url();
-				await locator.click({ timeout: 5000 });
-
-				// Wait for potential navigation to settle (replaces fixed sleep)
-				const { navigated: _navigated } = await waitForNavigationSettle(page, urlBefore);
-
-				const newUrl = page.url();
-				const newTitle = await page.title();
-				sessionManager.updateSession(taskId, {
-					currentUrl: newUrl,
-					currentTitle: newTitle,
-				});
-
-				// Auto-snapshot
-				const snapResult = await this.takeSnapshot(taskId, page);
+		return this._logOp(
+			"click",
+			{ taskId, ref, role: node.role, name: node.name },
+			async () => {
+				try {
+					const urlBefore = page.url();
+					await locator.click({ timeout: 5000 });
+
+					// Wait for potential navigation to settle (replaces fixed sleep)
+					const { navigated: _navigated } = await waitForNavigationSettle(
+						page,
+						urlBefore,
+					);
+
+					const newUrl = page.url();
+					const newTitle = await page.title();
+					sessionManager.updateSession(taskId, {
+						currentUrl: newUrl,
+						currentTitle: newTitle,
+					});
 
-				return {
-					success: true,
-					newUrl,
-					newTitle,
-					snapshot: snapResult.snapshot,
-					elementCount: snapResult.elementCount,
-					dialogEvents: snapResult.dialogEvents,
-				};
-			} catch (err: unknown) {
-				return {
-					success: false,
-					error: `Click failed: ${err instanceof Error ? err.message : String(err)}`,
-				};
-			}
-		});
+					// Auto-snapshot
+					const snapResult = await this.takeSnapshot(taskId, page);
+
+					return {
+						success: true,
+						newUrl,
+						newTitle,
+						snapshot: snapResult.snapshot,
+						elementCount: snapResult.elementCount,
+						dialogEvents: snapResult.dialogEvents,
+					};
+				} catch (err: unknown) {
+					return {
+						success: false,
+						error: `Click failed: ${err instanceof Error ? err.message : String(err)}`,
+					};
+				}
+			},
+		);
 	}
 
 	async type(
@@ -792,27 +814,32 @@ export abstract class PlaywrightPluginBase implements BrowserPlugin {
 			};
 		}
 
-		return this._logOp("type", { taskId, ref, role: node.role, name: node.name }, async () => {
-			try {
-				await locator.click({ timeout: 5000 }); // Focus first
-				await locator.fill(text);
-
-				// Auto-snapshot
-				const snapResult = await this.takeSnapshot(taskId, page);
-
-				return {
-					success: true,
-					snapshot: snapResult.snapshot,
-					elementCount: snapResult.elementCount,
-					dialogEvents: snapResult.dialogEvents,
-				};
-			} catch (err: unknown) {
-				return {
-					success: false,
-					error: `Type failed: ${err instanceof Error ? err.message : String(err)}`,
-				};
-			}
-		}, (r) => ({ elementCount: r.elementCount }));
+		return this._logOp(
+			"type",
+			{ taskId, ref, role: node.role, name: node.name },
+			async () => {
+				try {
+					await locator.click({ timeout: 5000 }); // Focus first
+					await locator.fill(text);
+
+					// Auto-snapshot
+					const snapResult = await this.takeSnapshot(taskId, page);
+
+					return {
+						success: true,
+						snapshot: snapResult.snapshot,
+						elementCount: snapResult.elementCount,
+						dialogEvents: snapResult.dialogEvents,
+					};
+				} catch (err: unknown) {
+					return {
+						success: false,
+						error: `Type failed: ${err instanceof Error ? err.message : String(err)}`,
+					};
+				}
+			},
+			(r) => ({ elementCount: r.elementCount }),
+		);
 	}
 
 	async scroll(
@@ -824,29 +851,34 @@ export abstract class PlaywrightPluginBase implements BrowserPlugin {
 			return { success: false, error: "No active session" };
 		}
 
-		return this._logOp("scroll", { taskId, direction }, async () => {
-			try {
-				const delta = direction === "down" ? 800 : -800;
-				await page.evaluate(
-					`window.scrollBy({ top: ${delta}, behavior: "smooth" })`,
-				);
-				await page.waitForTimeout(200);
-
-				const snapResult = await this.takeSnapshot(taskId, page);
-
-				return {
-					success: true,
-					snapshot: snapResult.snapshot,
-					elementCount: snapResult.elementCount,
-					dialogEvents: snapResult.dialogEvents,
-				};
-			} catch (err: unknown) {
-				return {
-					success: false,
-					error: `Scroll failed: ${err instanceof Error ? err.message : String(err)}`,
-				};
-			}
-		}, (r) => ({ elementCount: r.elementCount }));
+		return this._logOp(
+			"scroll",
+			{ taskId, direction },
+			async () => {
+				try {
+					const delta = direction === "down" ? 800 : -800;
+					await page.evaluate(
+						`window.scrollBy({ top: ${delta}, behavior: "smooth" })`,
+					);
+					await page.waitForTimeout(200);
+
+					const snapResult = await this.takeSnapshot(taskId, page);
+
+					return {
+						success: true,
+						snapshot: snapResult.snapshot,
+						elementCount: snapResult.elementCount,
+						dialogEvents: snapResult.dialogEvents,
+					};
+				} catch (err: unknown) {
+					return {
+						success: false,
+						error: `Scroll failed: ${err instanceof Error ? err.message : String(err)}`,
+					};
+				}
+			},
+			(r) => ({ elementCount: r.elementCount }),
+		);
 	}
 
 	async goBack(taskId: string): Promise<InteractionResult> {
@@ -855,35 +887,40 @@ export abstract class PlaywrightPluginBase implements BrowserPlugin {
 			return { success: false, error: "No active session" };
 		}
 
-		return this._logOp("goBack", { taskId }, async () => {
-			try {
-				await page.goBack({ waitUntil: "networkidle" });
-				await page.waitForTimeout(300);
-
-				const newUrl = page.url();
-				const newTitle = await page.title();
-				sessionManager.updateSession(taskId, {
-					currentUrl: newUrl,
-					currentTitle: newTitle,
-				});
-
-				const snapResult = await this.takeSnapshot(taskId, page);
+		return this._logOp(
+			"goBack",
+			{ taskId },
+			async () => {
+				try {
+					await page.goBack({ waitUntil: "networkidle" });
+					await page.waitForTimeout(300);
+
+					const newUrl = page.url();
+					const newTitle = await page.title();
+					sessionManager.updateSession(taskId, {
+						currentUrl: newUrl,
+						currentTitle: newTitle,
+					});
 
-				return {
-					success: true,
-					newUrl,
-					newTitle,
-					snapshot: snapResult.snapshot,
-					elementCount: snapResult.elementCount,
-					dialogEvents: snapResult.dialogEvents,
-				};
-			} catch (err: unknown) {
-				return {
-					success: false,
-					error: `GoBack failed: ${err instanceof Error ? err.message : String(err)}`,
-				};
-			}
-		}, (r) => ({ elementCount: r.elementCount }));
+					const snapResult = await this.takeSnapshot(taskId, page);
+
+					return {
+						success: true,
+						newUrl,
+						newTitle,
+						snapshot: snapResult.snapshot,
+						elementCount: snapResult.elementCount,
+						dialogEvents: snapResult.dialogEvents,
+					};
+				} catch (err: unknown) {
+					return {
+						success: false,
+						error: `GoBack failed: ${err instanceof Error ? err.message : String(err)}`,
+					};
+				}
+			},
+			(r) => ({ elementCount: r.elementCount }),
+		);
 	}
 
 	async press(taskId: string, key: string): Promise<InteractionResult> {
@@ -892,41 +929,50 @@ export abstract class PlaywrightPluginBase implements BrowserPlugin {
 			return { success: false, error: "No active session" };
 		}
 
-		return this._logOp("press", { taskId, key }, async () => {
-			try {
-				const urlBefore = page.url();
-				await page.keyboard.press(key);
-
-				// Wait for potential navigation to settle (replaces fixed sleep).
-				// Shorter nav timeout since Enter-on-link nav is typically fast.
-				const { navigated: _navigated } = await waitForNavigationSettle(page, urlBefore, {
-					navTimeoutMs: 3000,
-				});
-
-				const newUrl = page.url();
-				const newTitle = await page.title();
-				sessionManager.updateSession(taskId, {
-					currentUrl: newUrl,
-					currentTitle: newTitle,
-				});
-
-				const snapResult = await this.takeSnapshot(taskId, page);
+		return this._logOp(
+			"press",
+			{ taskId, key },
+			async () => {
+				try {
+					const urlBefore = page.url();
+					await page.keyboard.press(key);
+
+					// Wait for potential navigation to settle (replaces fixed sleep).
+					// Shorter nav timeout since Enter-on-link nav is typically fast.
+					const { navigated: _navigated } = await waitForNavigationSettle(
+						page,
+						urlBefore,
+						{
+							navTimeoutMs: 3000,
+						},
+					);
+
+					const newUrl = page.url();
+					const newTitle = await page.title();
+					sessionManager.updateSession(taskId, {
+						currentUrl: newUrl,
+						currentTitle: newTitle,
+					});
 
-				return {
-					success: true,
-					newUrl,
-					newTitle,
-					snapshot: snapResult.snapshot,
-					elementCount: snapResult.elementCount,
-					dialogEvents: snapResult.dialogEvents,
-				};
-			} catch (err: unknown) {
-				return {
-					success: false,
-					error: `Press failed: ${err instanceof Error ? err.message : String(err)}`,
-				};
-			}
-		}, (r) => ({ elementCount: r.elementCount }));
+					const snapResult = await this.takeSnapshot(taskId, page);
+
+					return {
+						success: true,
+						newUrl,
+						newTitle,
+						snapshot: snapResult.snapshot,
+						elementCount: snapResult.elementCount,
+						dialogEvents: snapResult.dialogEvents,
+					};
+				} catch (err: unknown) {
+					return {
+						success: false,
+						error: `Press failed: ${err instanceof Error ? err.message : String(err)}`,
+					};
+				}
+			},
+			(r) => ({ elementCount: r.elementCount }),
+		);
 	}
 
 	// ── Media ──────────────────────────────────────────────────
@@ -1002,18 +1048,23 @@ export abstract class PlaywrightPluginBase implements BrowserPlugin {
 			return { success: false, cookies: [], error: "No active session" };
 		}
 
-		return this._logOp("getCookies", { taskId }, async () => {
-			try {
-				const cookies = await entry.context.cookies(urls);
-				return { success: true, cookies };
-			} catch (err: unknown) {
-				return {
-					success: false,
-					cookies: [],
-					error: err instanceof Error ? err.message : String(err),
-				};
-			}
-		}, (r) => ({ count: r.cookies.length }));
+		return this._logOp(
+			"getCookies",
+			{ taskId },
+			async () => {
+				try {
+					const cookies = await entry.context.cookies(urls);
+					return { success: true, cookies };
+				} catch (err: unknown) {
+					return {
+						success: false,
+						cookies: [],
+						error: err instanceof Error ? err.message : String(err),
+					};
+				}
+			},
+			(r) => ({ count: r.cookies.length }),
+		);
 	}
 
 	async addCookies(taskId: string, cookies: Cookie[]): Promise<ResultBase> {
@@ -1072,23 +1123,28 @@ export abstract class PlaywrightPluginBase implements BrowserPlugin {
 			};
 		}
 
-		return this._logOp("getStorageState", { taskId }, async () => {
-			try {
-				const state = await entry.context.storageState();
-				return {
-					success: true,
-					cookies: state.cookies,
-					origins: state.origins,
-				};
-			} catch (err: unknown) {
-				return {
-					success: false,
-					cookies: [],
-					origins: [],
-					error: err instanceof Error ? err.message : String(err),
-				};
-			}
-		}, (r) => ({ cookies: r.cookies.length, origins: r.origins.length }));
+		return this._logOp(
+			"getStorageState",
+			{ taskId },
+			async () => {
+				try {
+					const state = await entry.context.storageState();
+					return {
+						success: true,
+						cookies: state.cookies,
+						origins: state.origins,
+					};
+				} catch (err: unknown) {
+					return {
+						success: false,
+						cookies: [],
+						origins: [],
+						error: err instanceof Error ? err.message : String(err),
+					};
+				}
+			},
+			(r) => ({ cookies: r.cookies.length, origins: r.origins.length }),
+		);
 	}
 
 	// ── Per-task cleanup ───────────────────────────────────────

package/backends/python-adapter.ts

@@ -10,7 +10,10 @@ import { join, delimiter as pathDelimiter } from "node:path";
 
 import { sessionManager } from "../core/shared/session-manager.js";
 import { persistSessionState } from "../core/shared/storage-state.js";
-import { DEFAULT_BACKENDS_ROOT } from "../core/plugin-config.js";
+import {
+	DEFAULT_BACKENDS_ROOT,
+	loadFullConfig,
+} from "../core/plugin-config.js";
 
 import {
 	DEFAULT_CAPABILITIES,
@@ -957,7 +960,8 @@ export class PythonPluginAdapter implements BrowserPlugin {
 				skip_default_viewport: !!raw.skip_default_viewport,
 				skip_networkidle: !!raw.skip_networkidle,
 				wrap_mw_eval_in_eval: !!raw.wrap_mw_eval_in_eval,
-				csp_safe_readonly_via_init_script: !!raw.csp_safe_readonly_via_init_script,
+				csp_safe_readonly_via_init_script:
+					!!raw.csp_safe_readonly_via_init_script,
 			}),
 			(error): QuirksDescriptor => ({
 				success: false,
@@ -1116,6 +1120,7 @@ export class PythonPluginAdapter implements BrowserPlugin {
 				};
 			},
 			"via Python bridge",
+			loadFullConfig().browser.maxStorageStateSize,
 		);
 	}
 

package/core/fetch-backend.ts

@@ -250,14 +250,8 @@ function writeFetchTempFile(content: string, taskId: string): string {
 
 function trackFetchFile(taskId: string, filePath: string): void {
 	const existing = activeFetchFiles.get(taskId) ?? [];
-	for (const oldPath of existing) {
-		try {
-			rmSync(oldPath, { force: true });
-		} catch {
-			/* best-effort */
-		}
-	}
-	activeFetchFiles.set(taskId, [filePath]);
+	if (!existing.includes(filePath)) existing.push(filePath);
+	activeFetchFiles.set(taskId, existing);
 }
 
 interface CappedFetchContent {

package/core/guides.ts

@@ -90,8 +90,7 @@ export const BUILTIN_GUIDES: Record<string, Guide> = {
 			"",
 			"### Backend Strategy",
 			"- The default `chromium` / `firefox` backends are detected by many anti-automation systems",
-			'- A stealth browser backend may be available — try `browser-navigate` with `strategy="stealth"` if the default backend is blocked',
-			"- If no stealth backend is configured, this will fail with a clear error — no harm in trying",
+			'- A stealth browser backend may be available — the `browser-navigate` `strategy` parameter lists the registered backend names; retry with a stealth backend name listed there (e.g. `strategy="camoufox"`) if the default is blocked',
 			"",
 			"### Verifying the Page After a Challenge",
 			'- Use `browser-inspect role="dialog"` to check if a challenge dialog is still present — cheaper than a full snapshot',

package/core/plugin-config.ts

@@ -8,6 +8,11 @@
 import { existsSync } from "node:fs";
 import { join, isAbsolute } from "node:path";
 import { USER_BACKENDS_DIR } from "./shared/paths.js";
+import {
+	sanitizeProfileName,
+	DEFAULT_MAX_STORAGE_STATE_SIZE,
+} from "./shared/storage-state.js";
+import { readMergedSettings } from "./shared/settings-reader.js";
 // ─── Plugin Config types ──────────────────────────────────────────
 
 /** A single plugin entry from the user's settings.json */
@@ -34,9 +39,6 @@ export interface PluginDetection {
 	/** 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 ────────────────────────────────────────
 
 /**
@@ -51,6 +53,12 @@ export interface BrowserConfig {
 	 * - A named profile string (e.g. "shopping", "work")
 	 */
 	defaultProfile: "none" | "session" | string;
+	/**
+	 * Byte threshold before a profile's saved storage state logs a size
+	 * warning (still saved). Defaults to 10 MB (`DEFAULT_MAX_STORAGE_STATE_SIZE`).
+	 * Set via `browser.maxStorageStateSize` in settings.json.
+	 */
+	maxStorageStateSize: number;
 }
 
 /** Raw plugin entry from settings.json (before validation) */
@@ -87,6 +95,7 @@ function parseBrowserConfig(
 	// Defaults
 	const config: BrowserConfig = {
 		defaultProfile: "session",
+		maxStorageStateSize: DEFAULT_MAX_STORAGE_STATE_SIZE,
 	};
 
 	if (!raw) return config;
@@ -114,6 +123,21 @@ function parseBrowserConfig(
 		}
 	}
 
+	// ── maxStorageStateSize ─────────────────────────────────────
+	if (raw.maxStorageStateSize !== undefined) {
+		if (
+			typeof raw.maxStorageStateSize === "number" &&
+			Number.isFinite(raw.maxStorageStateSize) &&
+			raw.maxStorageStateSize > 0
+		) {
+			config.maxStorageStateSize = Math.floor(raw.maxStorageStateSize);
+		} else {
+			errors.push(
+				`browser.maxStorageStateSize: expected a positive finite number, got ${JSON.stringify(raw.maxStorageStateSize)}`,
+			);
+		}
+	}
+
 	// Log validation errors (non-fatal, but surfaced in return)
 	for (const err of errors) {
 		console.warn(`[pi-lean-portal] Config warning: ${err}`);

package/core/router.ts

@@ -580,7 +580,8 @@ export async function navigate(
 				elementCount: 0,
 				error:
 					"Page appears to be blocked by anti-automation protection. " +
-					"The page may require JavaScript execution or browser interaction to render.",
+					"Retry `browser-navigate` with a stealth backend name from the `strategy` parameter's listed backends, " +
+					"or try `web-fetch` for the raw HTML (it skips JS fingerprinting but loses interactivity).",
 				backendUsed: plugin.name,
 				botDetectionWarning: true,
 			} as NavigateResult & {

package/core/shared/storage-state.ts

@@ -32,7 +32,7 @@ export const PROFILE_DIR = join(PORTAL_DATA_DIR, "browser-state");
 const STORAGE_STATE_VERSION = 1;
 
 /** Default size limit (10 MB) before a warning is logged on save. */
-const DEFAULT_MAX_STORAGE_STATE_SIZE = 10 * 1024 * 1024;
+export const DEFAULT_MAX_STORAGE_STATE_SIZE = 10 * 1024 * 1024;
 
 /** Profile name validation regex. */
 const PROFILE_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
@@ -468,6 +468,9 @@ export function deleteStorageState(profileName: string): void {
  * @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.
+ * @param maxSizeBytes - Optional byte threshold for the size warning
+ *                       (defaults to `DEFAULT_MAX_STORAGE_STATE_SIZE` when
+ *                       omitted).
  * @returns The raw state object, or `undefined` if the session is
  *          non-persistent or the save failed.
  */
@@ -475,12 +478,13 @@ export async function persistSessionState(
 	session: { persistState?: boolean; profileName?: string } | null | undefined,
 	getStorageState: () => Promise<{ cookies: unknown[]; origins: unknown[] }>,
 	viaLabel: string = "",
+	maxSizeBytes?: number,
 ): Promise<{ cookies: unknown[]; origins: unknown[] } | undefined> {
 	if (!session?.persistState) return undefined;
 	const name = session.profileName ?? "default";
 	try {
 		const state = await getStorageState();
-		saveStorageState(name, state);
+		saveStorageState(name, state, maxSizeBytes);
 		return state;
 	} catch (err) {
 		console.warn(

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-lean-portal",
-	"version": "0.2.1",
+	"version": "0.2.3",
 	"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",