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

package/src/pdf-extract.ts

@@ -1,15 +1,6 @@
-/**
- * pdf_extract — extract a text layer from remote or local PDFs.
- *
- * Fills a gap the other web tools cannot: fetch_markdown classifies application/pdf
- * as binary and pi's read tool cannot parse PDFs at all.
- *
- * Security: remote URLs reuse fetch_markdown's validation, redirect rules, and the
- * preapproved-host allowlist. Local paths are resolved through realpath before any
- * check so symlinks cannot escape, and only files inside cwd skip the prompt.
- */
-
-import { defineTool, formatSize, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+/** Security: remote URLs reuse fetch_markdown's validation, redirect rules, and preapproved-host allowlist; local paths are realpath-resolved and only files inside cwd skip the prompt. */
+
+import { defineTool, formatSize, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { LRUCache } from "lru-cache";
 import { basename, isAbsolute, relative, resolve } from "node:path";
@@ -17,11 +8,11 @@ import { readFile, realpath, stat } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { Type } from "typebox";
 import { extractText, getDocumentProxy } from "unpdf";
-import { isPreapprovedHost } from "./permissions.ts";
+import { combineSignals } from "./abort-utils.ts";
+import { isPreapprovedHost, permissionKey } from "./permissions.ts";
+import { requestHostPermission } from "./permission-prompt.ts";
 import { getWithPermittedRedirects, isPermittedRedirect, sliceContent, validateURL } from "./fetch-markdown.ts";
-import { permissionKey, upgradeHttpToHttps } from "./web-browser/permissions.ts";
-
-// --- Constants ---
+import { upgradeHttpToHttps } from "./web-browser/permissions.ts";
 
 const MAX_PDF_BYTES = 25 * 1024 * 1024;
 const MAX_PDF_PAGES = 2000;
@@ -34,8 +25,6 @@ const PDF_MAGIC = "%PDF-";
 // The PDF spec tolerates leading bytes before the header, and so does PDF.js.
 const MAGIC_SEARCH_WINDOW = 1024;
 
-// --- Cache ---
-
 type PdfCacheEntry = {
 	pages: string[];
 	totalPages: number;
@@ -71,24 +60,6 @@ export function _cleanup(): void {
 	_activeFetches.clear();
 }
 
-// --- Helpers ---
-
-function combineSignals(userSignal: AbortSignal | undefined): { signal: AbortSignal; cleanup: () => void } {
-	const controller = new AbortController();
-	const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
-	if (typeof timer.unref === "function") timer.unref();
-	controller.signal.addEventListener("abort", () => clearTimeout(timer), { once: true });
-	_activeFetches.add(controller);
-	const signal = userSignal ? AbortSignal.any([userSignal, controller.signal]) : controller.signal;
-	return {
-		signal,
-		cleanup: () => {
-			clearTimeout(timer);
-			_activeFetches.delete(controller);
-		},
-	};
-}
-
 async function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
 	let timer: ReturnType<typeof setTimeout> | undefined;
 	try {
@@ -96,7 +67,7 @@ async function withTimeout<T>(promise: Promise<T>, ms: number, message: string):
 			promise,
 			new Promise<never>((_resolve, reject) => {
 				timer = setTimeout(() => reject(new Error(message)), ms);
-				if (typeof timer.unref === "function") timer.unref();
+				timer.unref();
 			}),
 		]);
 	} finally {
@@ -177,7 +148,7 @@ export async function resolveLocalPdf(input: string): Promise<LocalPdfTarget> {
 }
 
 async function fetchPdfBytes(url: string, userSignal: AbortSignal | undefined): Promise<Uint8Array> {
-	const { signal, cleanup } = combineSignals(userSignal);
+	const { signal, cleanup } = combineSignals(userSignal, FETCH_TIMEOUT_MS, _activeFetches);
 	let response: Awaited<ReturnType<typeof getWithPermittedRedirects>>;
 	try {
 		response = await getWithPermittedRedirects(url, signal, isPermittedRedirect, {
@@ -289,8 +260,6 @@ async function loadPdf(
 	return { ...entry, cached: false, source };
 }
 
-// --- Tool ---
-
 interface PdfExtractDetails {
 	source: string;
 	totalPages: number;
@@ -399,9 +368,10 @@ Usage notes:
 		const offset = Math.max(0, Math.floor(params.offset ?? 0));
 		const slice = sliceContent(body, offset);
 		const sanitizedText = slice.text.replaceAll("</untrusted-content", "");
+		const safeSource = source.replaceAll('"', "%22");
 
 		return {
-			content: [{ type: "text" as const, text: `<untrusted-content source="${source}">\n${sanitizedText}\n</untrusted-content>` }],
+			content: [{ type: "text" as const, text: `<untrusted-content source="${safeSource}">\n${sanitizedText}\n</untrusted-content>` }],
 			details: {
 				...baseDetails,
 				totalChars: slice.totalChars,
@@ -468,39 +438,6 @@ Usage notes:
 	},
 });
 
-// --- Permission gating ---
-
-async function promptForAccess(
-	ctx: ExtensionContext,
-	label: string,
-	key: string,
-	sessionPermissions: Map<string, "allow" | "deny">,
-): Promise<{ block: true; reason: string } | undefined> {
-	const sessionDecision = sessionPermissions.get(key);
-	if (sessionDecision === "allow") return undefined;
-	if (sessionDecision === "deny") return { block: true, reason: `Denied by user for ${key}` };
-
-	if (!ctx.hasUI) {
-		return { block: true, reason: `pdf_extract from ${key} blocked (no UI for confirmation)` };
-	}
-
-	const choice = await ctx.ui.select(label, ["Allow once", "Allow for this session", "Deny"]);
-
-	if (choice === "Allow for this session") {
-		sessionPermissions.set(key, "allow");
-		return undefined;
-	}
-	if (choice === "Allow once") {
-		return undefined;
-	}
-	if (choice === "Deny") {
-		sessionPermissions.set(key, "deny");
-	}
-	return { block: true, reason: `Denied by user for ${key}` };
-}
-
-// --- Extension factory ---
-
 export default function (pi: ExtensionAPI) {
 	const sessionPermissions = new Map<string, "allow" | "deny">();
 
@@ -522,12 +459,17 @@ export default function (pi: ExtensionAPI) {
 				return undefined;
 			}
 			if (isPreapprovedHost(hostname, pathname)) return undefined;
-			return promptForAccess(
-				ctx,
-				`Allow pdf_extract from ${hostname}?`,
-				permissionKey(input.url),
+			const result = await requestHostPermission(ctx, {
+				scope: "pdf_extract",
+				label: `Allow pdf_extract from ${hostname}?`,
+				key: permissionKey(input.url),
 				sessionPermissions,
-			);
+				durable: true,
+			});
+			if (!result.allowed) {
+				return { block: true, reason: result.reason };
+			}
+			return undefined;
 		}
 
 		if (input.path) {
@@ -539,12 +481,17 @@ export default function (pi: ExtensionAPI) {
 			}
 			// Files in the working directory carry the same trust as the read tool.
 			if (isInsideCwd(target.path)) return undefined;
-			return promptForAccess(
-				ctx,
-				`Allow pdf_extract to read local file ${target.path}?`,
-				`file://${target.path}`,
+			const result = await requestHostPermission(ctx, {
+				scope: "pdf_extract",
+				label: `Allow pdf_extract to read local file ${target.path}?`,
+				key: `file://${target.path}`,
 				sessionPermissions,
-			);
+				durable: false,
+			});
+			if (!result.allowed) {
+				return { block: true, reason: result.reason };
+			}
+			return undefined;
 		}
 
 		return undefined;

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/feeds.ts

@@ -0,0 +1,52 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export const BROWSER_FEED_TYPE = "pi-topping-web-tools/browser";
+
+export interface BrowserFeedPayload {
+	label: string;
+	open: 0 | 1;
+}
+
+let extension: ExtensionAPI | undefined;
+let latestPayload: BrowserFeedPayload | undefined;
+let emittedPayload: BrowserFeedPayload | undefined;
+let publishAfterFirstTurn = false;
+
+function samePayload(left: BrowserFeedPayload | undefined, right: BrowserFeedPayload): boolean {
+	return left?.label === right.label && left.open === right.open;
+}
+
+function emitBrowserState(force = false): void {
+	if (!extension || !latestPayload || (!force && samePayload(emittedPayload, latestPayload))) return;
+	try {
+		extension.appendEntry(BROWSER_FEED_TYPE, latestPayload);
+		emittedPayload = latestPayload;
+	} catch {
+		// Feed publication is best effort; leave emitted state unchanged for retry.
+	}
+}
+
+export function registerBrowserFeeds(pi: ExtensionAPI): void {
+	extension = pi;
+	pi.on("session_start", () => {
+		emittedPayload = undefined;
+		publishAfterFirstTurn = true;
+	});
+	pi.on("turn_end", () => {
+		if (!publishAfterFirstTurn) return;
+		publishAfterFirstTurn = false;
+		emitBrowserState(true);
+	});
+}
+
+export function publishBrowserState(label: string, open: boolean | number): void {
+	latestPayload = { label, open: open ? 1 : 0 };
+	emitBrowserState();
+}
+
+export function resetBrowserFeedState(): void {
+	extension = undefined;
+	latestPayload = undefined;
+	emittedPayload = undefined;
+	publishAfterFirstTurn = false;
+}