@underactive/pi-topping-web-tools 0.1.0 → 0.2.0

package/src/permission-prompt.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared host-permission prompt for web tools.
+ *
+ * Replaces the duplicated select/session-map logic in fetch_markdown,
+ * pdf_extract, and web_browser. Supports durable grants for http/https origins
+ * and session-only prompts for file:// origins.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isGranted, addGrant, type PermissionScope, DAY_MS, WEEK_MS, MONTH_MS } from "./permission-store.ts";
+
+export type PermissionPromptResult = { allowed: true } | { allowed: false; reason: string };
+
+type SessionPermissions = Map<string, "allow" | "deny">;
+
+/** Prompt the user for host access; `durable` adds 1-day/1-week/30-day options, otherwise session-only. */
+export async function requestHostPermission(
+	ctx: ExtensionContext,
+	{
+		scope,
+		label,
+		key,
+		sessionPermissions,
+		durable,
+	}: {
+		scope: PermissionScope;
+		label: string;
+		key: string;
+		sessionPermissions: SessionPermissions;
+		durable: boolean;
+	},
+): Promise<PermissionPromptResult> {
+	// Session deny
+	const sessionDecision = sessionPermissions.get(key);
+	if (sessionDecision === "deny") {
+		return { allowed: false, reason: `Denied by user for ${key}` };
+	}
+
+	// Session allow
+	if (sessionDecision === "allow") {
+		return { allowed: true };
+	}
+
+	// Durable grant
+	if (durable && isGranted(scope, key)) {
+		return { allowed: true };
+	}
+
+	// No UI — block
+	if (!ctx.hasUI) {
+		return { allowed: false, reason: `${scope} to ${key} blocked (no UI for confirmation)` };
+	}
+
+	// Prompt
+	const options = durable
+		? ["Allow once", "Allow for this session", "Allow for 1 day", "Allow for 1 week", "Allow for 30 days", "Deny"]
+		: ["Allow once", "Allow for this session", "Deny"];
+
+	const choice = await ctx.ui.select(label, options);
+
+	if (choice === "Allow for this session") {
+		sessionPermissions.set(key, "allow");
+		return { allowed: true };
+	}
+
+	if (choice === "Allow once") {
+		return { allowed: true };
+	}
+
+	if (choice === "Deny") {
+		sessionPermissions.set(key, "deny");
+		return { allowed: false, reason: `Denied by user for ${key}` };
+	}
+
+	// Durable duration choices
+	let ttlMs: number | undefined;
+	if (choice === "Allow for 1 day") ttlMs = DAY_MS;
+	else if (choice === "Allow for 1 week") ttlMs = WEEK_MS;
+	else if (choice === "Allow for 30 days") ttlMs = MONTH_MS;
+
+	if (ttlMs !== undefined) {
+		const persisted = await addGrant(scope, key, ttlMs);
+		if (!persisted) {
+			// Persist failure — downgrade to session grant.
+			sessionPermissions.set(key, "allow");
+			ctx.ui.notify(
+				`Could not save durable permission; allowing for this session only.`,
+				"warning",
+			);
+		}
+		return { allowed: true };
+	}
+
+	// Fallback (unexpected choice)
+	sessionPermissions.set(key, "deny");
+	return { allowed: false, reason: `Denied by user for ${key}` };
+}

package/src/permission-store.ts

@@ -0,0 +1,203 @@
+/**
+ * Durable permission store for web tools.
+ *
+ * Persists user-approved host grants to a JSON file in the agent config
+ * directory. Grants expire after their TTL and are pruned on read/write.
+ * Storage is global (not cwd-scoped) so cwd-scoped write tools cannot reach it.
+ */
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+import { mkdir, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { permissionKey } from "./permissions.ts";
+
+export type PermissionScope = "fetch_markdown" | "pdf_extract" | "web_browser";
+
+export type Grant = {
+	scope: PermissionScope;
+	origin: string;
+	grantedAt: number;
+	expiresAt: number;
+};
+
+type StoreFile = {
+	version: 1;
+	grants: Grant[];
+};
+
+export const DAY_MS = 24 * 60 * 60 * 1000;
+export const WEEK_MS = 7 * DAY_MS;
+export const MONTH_MS = 30 * DAY_MS;
+
+const MAX_FILE_BYTES = 1024 * 1024; // 1 MB
+const MAX_GRANTS = 500;
+const LOCK_RETRY_MS = 50;
+const LOCK_RETRIES = 20; // ~1 s total
+const LOCK_STALE_MS = 10_000;
+
+function storePath(): string {
+	return process.env.PI_WEB_TOOLS_PERMISSIONS_FILE ?? join(getAgentDir(), "web-permissions.json");
+}
+
+function lockPath(): string {
+	return `${storePath()}.lock`;
+}
+
+function normalizeOrigin(origin: string): string {
+	// Round-trip through permissionKey to enforce consistent format.
+	return permissionKey(origin);
+}
+
+function isValidScope(scope: string): scope is PermissionScope {
+	return scope === "fetch_markdown" || scope === "pdf_extract" || scope === "web_browser";
+}
+
+/** Read and validate the store file. Returns empty list on any parse/validation failure. */
+export function listGrants(): Grant[] {
+	let raw: string;
+	try {
+		raw = readFileSync(storePath(), "utf-8");
+	} catch {
+		return [];
+	}
+
+	if (Buffer.byteLength(raw) > MAX_FILE_BYTES) {
+		return [];
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return [];
+	}
+
+	if (typeof parsed !== "object" || parsed === null) return [];
+	const file = parsed as StoreFile;
+	if (file.version !== 1 || !Array.isArray(file.grants)) return [];
+
+	const now = Date.now();
+	const valid: Grant[] = [];
+	for (const entry of file.grants) {
+		if (typeof entry !== "object" || entry === null) continue;
+		const g = entry as Record<string, unknown>;
+		if (!isValidScope(g.scope as string)) continue;
+		if (typeof g.origin !== "string") continue;
+		if (typeof g.grantedAt !== "number" || !Number.isFinite(g.grantedAt)) continue;
+		if (typeof g.expiresAt !== "number" || !Number.isFinite(g.expiresAt)) continue;
+		if (g.expiresAt <= now) continue; // expired
+		if (normalizeOrigin(g.origin as string) !== g.origin) continue; // malformed
+		valid.push({
+			scope: g.scope as PermissionScope,
+			origin: g.origin as string,
+			grantedAt: g.grantedAt as number,
+			expiresAt: g.expiresAt as number,
+		});
+	}
+
+	return valid;
+}
+
+/** Check whether a specific scope+origin has an active durable grant. */
+export function isGranted(scope: PermissionScope, origin: string): boolean {
+	const key = normalizeOrigin(origin);
+	return listGrants().some((g) => g.scope === scope && g.origin === key);
+}
+
+/** Prune expired entries from a grant list. */
+function pruneExpired(grants: Grant[]): Grant[] {
+	const now = Date.now();
+	return grants.filter((g) => g.expiresAt > now);
+}
+
+/** Attempt to acquire a lock file. Returns true if acquired. */
+async function acquireLock(): Promise<boolean> {
+	const lp = lockPath();
+	for (let i = 0; i < LOCK_RETRIES; i++) {
+		try {
+			// wx fails if the file already exists.
+			await writeFile(lp, String(process.pid), { flag: "wx" });
+			return true;
+		} catch {
+			// Check for stale lock.
+			try {
+				const { mtimeMs } = await stat(lp);
+				if (Date.now() - mtimeMs > LOCK_STALE_MS) {
+					// Stale lock — take it over.
+					await writeFile(lp, String(process.pid), { flag: "w" });
+					// Verify the takeover won (another process may have raced us).
+					if (readFileSync(lp, "utf-8") !== String(process.pid)) continue;
+					return true;
+				}
+			} catch {
+				// Lock file disappeared between check and stat — retry.
+			}
+			await new Promise((r) => setTimeout(r, LOCK_RETRY_MS));
+		}
+	}
+	return false;
+}
+
+async function releaseLock(): Promise<void> {
+	try {
+		await unlink(lockPath());
+	} catch {
+		// ignore
+	}
+}
+
+async function writeStore(grants: Grant[]): Promise<void> {
+	const dir = join(storePath(), "..");
+	await mkdir(dir, { recursive: true });
+
+	const file: StoreFile = { version: 1, grants };
+	const tmp = `${storePath()}.tmp`;
+	await writeFile(tmp, JSON.stringify(file, null, "\t"), { mode: 0o600 });
+	await rename(tmp, storePath());
+}
+
+/** Add a durable grant. Returns false if the lock could not be acquired. */
+export async function addGrant(scope: PermissionScope, origin: string, ttlMs: number): Promise<boolean> {
+	const normalized = normalizeOrigin(origin);
+	const locked = await acquireLock();
+	if (!locked) return false;
+
+	try {
+		const grants = pruneExpired(listGrants());
+
+		// Remove existing grant for same scope+origin.
+		const filtered = grants.filter((g) => !(g.scope === scope && g.origin === normalized));
+
+		const now = Date.now();
+		filtered.push({
+			scope,
+			origin: normalized,
+			grantedAt: now,
+			expiresAt: now + Math.min(ttlMs, MONTH_MS),
+		});
+
+		// Cap at MAX_GRANTS.
+		const capped = filtered.length > MAX_GRANTS ? filtered.slice(-MAX_GRANTS) : filtered;
+		await writeStore(capped);
+		return true;
+	} finally {
+		await releaseLock();
+	}
+}
+
+/** Remove a durable grant. Returns false if the lock could not be acquired. */
+export async function removeGrant(scope: PermissionScope, origin: string): Promise<boolean> {
+	const normalized = normalizeOrigin(origin);
+	const locked = await acquireLock();
+	if (!locked) return false;
+
+	try {
+		const grants = pruneExpired(listGrants());
+		const filtered = grants.filter((g) => !(g.scope === scope && g.origin === normalized));
+		await writeStore(filtered);
+		return true;
+	} finally {
+		await releaseLock();
+	}
+}

package/src/permissions.ts

@@ -115,6 +115,18 @@ const { HOSTNAME_ONLY, PATH_PREFIXES } = (() => {
 	return { HOSTNAME_ONLY: hosts, PATH_PREFIXES: paths };
 })();
 
+export function permissionKey(url: string): string {
+	try {
+		const parsed = new URL(url);
+		if (parsed.protocol === "file:") {
+			return `file://${parsed.pathname}`;
+		}
+		return `${parsed.protocol}//${parsed.host}`;
+	} catch {
+		return url;
+	}
+}
+
 export function isPreapprovedHost(hostname: string, pathname: string): boolean {
 	if (HOSTNAME_ONLY.has(hostname)) return true;
 	const prefixes = PATH_PREFIXES.get(hostname);

package/src/web-browser/browser-manager.ts

@@ -100,12 +100,6 @@ export type ScreenshotResult = {
 	fullPage: boolean;
 };
 
-/**
- * Async mutex that serializes browser operations.
- *
- * NOTE: `close()` and `forceClose()` bypass this mutex so shutdown is
- * never blocked by a queued or in-flight operation.
- */
 export class AsyncMutex {
 	private chain: Promise<void> = Promise.resolve();
 
@@ -714,15 +708,13 @@ export class BrowserManager {
 		let timerId: ReturnType<typeof setTimeout> | undefined;
 		const timer =
 			timeoutMs > 0
-				? Promise.resolve().then(
-						() =>
-							new Promise<never>((_, reject) => {
-								timerId = setTimeout(
-									() => reject(new Error("Close timed out")),
-									timeoutMs,
-								);
-							}),
-				  )
+				? new Promise<never>((_, reject) => {
+						timerId = setTimeout(
+							() => reject(new Error("Close timed out")),
+							timeoutMs,
+						);
+						if (typeof timerId.unref === "function") timerId.unref();
+				  })
 				: Promise.resolve();
 
 		try {
@@ -814,7 +806,8 @@ export class BrowserManager {
 		const diagnostics = await this.selectorDiagnostics(page, selector, frame);
 		const snippet = await this.pageSnippet(page);
 		const frameNote = frame ? ` within frame "${frame}"` : "";
-		return `No element matches selector "${selector}"${frameNote}. ${diagnostics}\nPage snippet:\n<untrusted-content url="${page.url()}">\n${snippet.replaceAll("</untrusted-content", "")}\n</untrusted-content>`;
+		const safeUrl = page.url().replaceAll('"', "%22");
+		return `No element matches selector "${selector}"${frameNote}. ${diagnostics}\nPage snippet:\n<untrusted-content url="${safeUrl}">\n${snippet.replaceAll("</untrusted-content", "")}\n</untrusted-content>`;
 	}
 
 	private async ensureLaunched(): Promise<void> {
@@ -910,12 +903,6 @@ export class BrowserManager {
 		});
 	}
 
-	/**
-	 * Registering a `dialog` listener switches Playwright from auto-dismiss
-	 * to "must be resolved" — an unhandled dialog freezes all further
-	 * actions on the page, so this unconditionally accepts or dismisses
-	 * based on the configured session behavior.
-	 */
 	private attachDialogListener(page: Page): void {
 		page.on("dialog", (dialog) => {
 			const entry: DialogEntry = {
@@ -939,22 +926,22 @@ export class BrowserManager {
 
 	private pushConsole(entry: ConsoleEntry): void {
 		this.consoleBuffer.push(entry);
-		if (this.consoleBuffer.length > MAX_BUFFER_ENTRIES) {
-			this.consoleBuffer.shift();
+		if (this.consoleBuffer.length >= MAX_BUFFER_ENTRIES) {
+			this.consoleBuffer = this.consoleBuffer.slice(MAX_BUFFER_ENTRIES >> 1);
 		}
 	}
 
 	private pushNetwork(entry: NetworkEntry): void {
 		this.networkBuffer.push(entry);
-		if (this.networkBuffer.length > MAX_BUFFER_ENTRIES) {
-			this.networkBuffer.shift();
+		if (this.networkBuffer.length >= MAX_BUFFER_ENTRIES) {
+			this.networkBuffer = this.networkBuffer.slice(MAX_BUFFER_ENTRIES >> 1);
 		}
 	}
 
 	private pushDialog(entry: DialogEntry): void {
 		this.dialogBuffer.push(entry);
-		if (this.dialogBuffer.length > MAX_BUFFER_ENTRIES) {
-			this.dialogBuffer.shift();
+		if (this.dialogBuffer.length >= MAX_BUFFER_ENTRIES) {
+			this.dialogBuffer = this.dialogBuffer.slice(MAX_BUFFER_ENTRIES >> 1);
 		}
 	}
 

package/src/web-browser/index.ts

@@ -13,14 +13,13 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Text } from "@earendil-works/pi-tui";
-import { mkdtemp, writeFile } from "node:fs/promises";
+import { mkdtemp, realpath, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { Type } from "typebox";
 import {
 	closeBrowserManager,
 	getBrowserManager,
-	type BrowserManager,
 	type ConsoleEntry,
 	type DialogEntry,
 	type NavigateResult,
@@ -30,6 +29,9 @@ import {
 	type TabInfo,
 } from "./browser-manager.ts";
 import { checkUrlPermission, upgradeHttpToHttps, validateURL } from "./permissions.ts";
+import { requestHostPermission } from "../permission-prompt.ts";
+import { listGrants } from "../permission-store.ts";
+import { isInsideCwd } from "../pdf-extract.ts";
 
 const ACTIONS = [
 	"navigate",
@@ -128,15 +130,27 @@ function formatTabs(tabs: TabInfo[]): string {
 		.join("\n");
 }
 
-async function wrapUntrustedContent(mgr: BrowserManager, text: string): Promise<string> {
-	const info = await mgr.getPageInfoAsync();
-	return `<untrusted-content url="${info.url}">\n${text}\n</untrusted-content>`;
+function wrapUntrustedContent(url: string, text: string): string {
+	const safeUrl = url.replaceAll('"', "%22");
+	return `<untrusted-content url="${safeUrl}">\n${text}\n</untrusted-content>`;
 }
 
 function isAbortError(err: unknown): boolean {
 	return err instanceof Error && (err.name === "AbortError" || err.message.includes("Aborted"));
 }
 
+function blockReason(permission: string): string {
+	return permission.startsWith("block:") ? permission.slice("block:".length) : permission;
+}
+
+async function resolveLocalFilePath(input: string): Promise<string> {
+	try {
+		return await realpath(resolve(input));
+	} catch {
+		throw new Error(`Cannot upload file: no such file "${input}"`);
+	}
+}
+
 async function truncateTextResult(
 	text: string,
 	details: WebBrowserDetails,
@@ -214,7 +228,7 @@ export default function (pi: ExtensionAPI) {
 		if (input.action === "navigate" && input.url) {
 			const permission = await checkUrlPermission(input.url, ctx, sessionPermissions);
 			if (permission !== "allow") {
-				return { block: true, reason: permission.slice(6) };
+				return { block: true, reason: blockReason(permission) };
 			}
 
 			return undefined;
@@ -224,7 +238,7 @@ export default function (pi: ExtensionAPI) {
 			const info = await getBrowserManager().getPageInfoAsync();
 			const permission = await checkUrlPermission(info.url, ctx, sessionPermissions);
 			if (permission !== "allow") {
-				return { block: true, reason: permission.slice(6) };
+				return { block: true, reason: blockReason(permission) };
 			}
 		}
 
@@ -247,6 +261,7 @@ export default function (pi: ExtensionAPI) {
 				`  Network issues: ${info.networkCount}`,
 				`  Dialogs captured: ${info.dialogCount}`,
 				`  Session-approved hosts: ${sessionPermissions.size}`,
+				`  Saved hosts: ${listGrants().filter((g) => g.scope === "web_browser").length}`,
 			];
 			ctx.ui.notify(lines.join("\n"), "info");
 		},
@@ -630,8 +645,9 @@ export default function (pi: ExtensionAPI) {
 						const value = await mgr.evaluate(params.script, { signal });
 						const text = typeof value === "string" ? value : JSON.stringify(value, null, 2) ?? String(value);
 						const truncated = await truncateTextResult(text, { action });
+						const info = await mgr.getPageInfoAsync();
 						return {
-							content: [{ type: "text", text: await wrapUntrustedContent(mgr, truncated.text) }],
+							content: [{ type: "text", text: wrapUntrustedContent(info.url, truncated.text) }],
 							details: truncated.details,
 						};
 					}
@@ -639,8 +655,9 @@ export default function (pi: ExtensionAPI) {
 					case "get_content": {
 						const html = await mgr.content({ signal });
 						const truncated = await truncateTextResult(html, { action });
+						const info = await mgr.getPageInfoAsync();
 						return {
-							content: [{ type: "text", text: await wrapUntrustedContent(mgr, truncated.text) }],
+							content: [{ type: "text", text: wrapUntrustedContent(info.url, truncated.text) }],
 							details: truncated.details,
 						};
 					}
@@ -648,8 +665,9 @@ export default function (pi: ExtensionAPI) {
 					case "get_text": {
 						const text = await mgr.getText(params.selector, { timeout, signal, frame: params.frame });
 						const truncated = await truncateTextResult(text, { action });
+						const info = await mgr.getPageInfoAsync();
 						return {
-							content: [{ type: "text", text: await wrapUntrustedContent(mgr, truncated.text) }],
+							content: [{ type: "text", text: wrapUntrustedContent(info.url, truncated.text) }],
 							details: truncated.details,
 						};
 					}
@@ -657,8 +675,9 @@ export default function (pi: ExtensionAPI) {
 					case "get_markdown": {
 						const md = await mgr.getMarkdown({ timeout, signal });
 						const truncated = await truncateTextResult(md, { action });
+						const info = await mgr.getPageInfoAsync();
 						return {
-							content: [{ type: "text", text: await wrapUntrustedContent(mgr, truncated.text) }],
+							content: [{ type: "text", text: wrapUntrustedContent(info.url, truncated.text) }],
 							details: truncated.details,
 						};
 					}
@@ -694,8 +713,9 @@ export default function (pi: ExtensionAPI) {
 							frame: params.frame,
 						});
 						const truncated = await truncateTextResult(snapshot, { action });
+						const info = await mgr.getPageInfoAsync();
 						return {
-							content: [{ type: "text", text: await wrapUntrustedContent(mgr, truncated.text) }],
+							content: [{ type: "text", text: wrapUntrustedContent(info.url, truncated.text) }],
 							details: truncated.details,
 						};
 					}
@@ -707,8 +727,9 @@ export default function (pi: ExtensionAPI) {
 							action,
 							consoleCount: entries.length,
 						});
+						const info = await mgr.getPageInfoAsync();
 						return {
-							content: [{ type: "text", text: await wrapUntrustedContent(mgr, truncated.text) }],
+							content: [{ type: "text", text: wrapUntrustedContent(info.url, truncated.text) }],
 							details: truncated.details,
 						};
 					}
@@ -720,8 +741,9 @@ export default function (pi: ExtensionAPI) {
 							action,
 							networkCount: entries.length,
 						});
+						const info = await mgr.getPageInfoAsync();
 						return {
-							content: [{ type: "text", text: await wrapUntrustedContent(mgr, truncated.text) }],
+							content: [{ type: "text", text: wrapUntrustedContent(info.url, truncated.text) }],
 							details: truncated.details,
 						};
 					}
@@ -759,8 +781,8 @@ export default function (pi: ExtensionAPI) {
 							const permission = await checkUrlPermission(cookieUrl, ctx, sessionPermissions);
 							if (permission !== "allow") {
 								return {
-									content: [{ type: "text", text: permission.slice(6) }],
-									details: { action, error: permission.slice(6) } satisfies WebBrowserDetails,
+									content: [{ type: "text", text: blockReason(permission) }],
+									details: { action, error: blockReason(permission) } satisfies WebBrowserDetails,
 									isError: true,
 								};
 							}
@@ -841,6 +863,24 @@ export default function (pi: ExtensionAPI) {
 								isError: true,
 							};
 						}
+						for (const file of params.files) {
+							const resolved = await resolveLocalFilePath(file);
+							if (isInsideCwd(resolved)) continue;
+							const permission = await requestHostPermission(ctx, {
+								scope: "web_browser",
+								label: `Allow web_browser to upload local file ${resolved}?`,
+								key: `file://${resolved}`,
+								sessionPermissions,
+								durable: false,
+							});
+							if (!permission.allowed) {
+								return {
+									content: [{ type: "text", text: permission.reason }],
+									details: { action, error: permission.reason } satisfies WebBrowserDetails,
+									isError: true,
+								};
+							}
+						}
 						const msg = await mgr.uploadFile(params.selector, params.files, {
 							frame: params.frame,
 							timeout,
@@ -870,8 +910,9 @@ export default function (pi: ExtensionAPI) {
 							action,
 							dialogCount: entries.length,
 						});
+						const info = await mgr.getPageInfoAsync();
 						return {
-							content: [{ type: "text", text: await wrapUntrustedContent(mgr, truncated.text) }],
+							content: [{ type: "text", text: wrapUntrustedContent(info.url, truncated.text) }],
 							details: truncated.details,
 						};
 					}