@underactive/pi-topping-web-tools 0.2.9 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-21
+
+### Changed
+
+- Tested against pi 1.4.0. No break: the extension-facing declaration surface (`ExtensionAPI`, `ToolDefinition`, `ExtensionContext`, `ExtensionUIContext`) is unchanged, pi-ai and pi-tui changes are additive or internal, and the provider-header, summary and classifier changes do not reach these tools. Concurrent extension dialogs no longer replace each other on 1.4.0, so parallel host-permission prompts from several tool calls all settle.
+- Bumped the pinned `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` devDependencies from 1.3.0 to 1.4.0.
+- Depend on `@underactive/pi-topping-primitives` `^0.10.0` (was `^0.9.0`). Nothing it imports changed in between: 0.10.0 removed only the `pi-topping-compact` entry names from `./contracts`, which it never referenced. Every topping now asks for the same range, so an install of several shares one copy of the library. No visible change.
+- Tool-exposure settings are read through the shared `@underactive/pi-topping-primitives` 0.2.0 settings store, and the permission grant store writes through its `atomicWriteFile` (unique temp names, cleaned up on failure). An empty `PI_WEB_TOOLS_SETTINGS_FILE` is now treated as unset instead of as a path. The grant store keeps its own lock file and format.
+- `web_browser`: source the session-feed entry type and payload from `@underactive/pi-topping-primitives` 0.1.0; the feed's wire format is unchanged.
+- Depend on `@underactive/pi-topping-primitives` `^0.9.0`. The environment-flag helpers (`isTruthyEnvFlag`, `suppressNotifications`) and `combineSignals` now come from its `./env` and `./abort` subpaths. Behaviour is unchanged except that a timeout above 2^31 - 1 ms is clamped to that instead of aborting the request after about a millisecond, and a timeout that `AbortSignal.timeout` rejects no longer leaves a stale entry in the active-fetch set.
+- `web_browser`: keep the event loop open while `close()` waits on a stalled cleanup, preventing the process from hanging on shutdown.
+
 ## [0.2.9] - 2026-10-16
 
 ### Added

package/README.md

@@ -309,7 +309,7 @@ Commands:
 ## Security model (shared)
 
 - **Preapproved hosts**: common documentation and dev sites are allowed without prompting. The allowlist lives in `src/permissions.ts` and is shared by all three tools.
-- **User confirmation**: other hosts prompt Allow once / Allow for this session / Allow for 1 day / Allow for 1 week / Allow for 30 days / Deny. For `web_browser` navigation, Allow once becomes a browser-session grant because request-level enforcement must authorize the loaded document's later requests.
+- **User confirmation**: other hosts prompt Allow once / Allow for this session / Allow for 1 day / Allow for 1 week / Allow for 30 days / Deny. For `web_browser` navigation, Allow once becomes a browser-session grant because request-level enforcement must authorize the loaded document's later requests. Parallel tool calls that each need a prompt rely on pi 1.4.0, which stacks concurrent extension dialogs so each one settles; on older pi a second dialog replaced the first and the first prompt never settled.
 - **Tool annotations**: on pi 0.99+, `fetch_markdown` and `pdf_extract` declare `readOnlyHint` and `openWorldHint`, and `web_browser` declares `openWorldHint` with `readOnlyHint: false`, for permission extensions that confirm calls by hint. The host confirmation above applies regardless of how another extension treats the hints.
 - **URL validation**: all tools reject embedded credentials and overlong URLs. `fetch_markdown` and `pdf_extract` additionally reject loopback, private, and link-local hosts and any non-HTTP(S) scheme on a `url`. `web_browser` accepts `localhost`, private IPs, and `file://` paths so it can drive local dev servers and local HTML — each still prompts for confirmation unless session-approved or covered by a saved durable grant.
 - **Local file resolution**: `pdf_extract` resolves a `path` through `realpath` before any check, so a symlink pointing outside the working directory is treated as outside and prompts. Directories, FIFOs, and devices are rejected, and the size limit is enforced from `stat` before any bytes are read. `web_browser` `upload_file` follows the same rule: files outside the working directory prompt for confirmation (session-scoped) before they are read.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@underactive/pi-topping-web-tools",
-	"version": "0.2.9",
+	"version": "0.3.0",
 	"description": "Pi extensions for the web: fetch_markdown (URL to markdown, cached, keyless), pdf_extract (PDF text extraction) and web_browser (headless Playwright automation), sharing a preapproved-host allowlist.",
 	"keywords": ["pi-package", "pi-extension"],
 	"license": "MIT",
@@ -28,7 +28,7 @@
 	],
 	"scripts": {
 		"typecheck": "tsc --noEmit",
-		"test": "node --test test/*.test.ts"
+		"test": "node -C compiled --test test/*.test.ts"
 	},
 	"pi": {
 		"extensions": [
@@ -40,6 +40,7 @@
 	},
 	"dependencies": {
 		"@mozilla/readability": "^0.6.0",
+		"@underactive/pi-topping-primitives": "^0.10.0",
 		"linkedom": "^0.18.13",
 		"lru-cache": "^11.0.0",
 		"playwright": "^1.52.0",
@@ -53,9 +54,9 @@
 		"typebox": "*"
 	},
 	"devDependencies": {
-		"@earendil-works/pi-ai": "1.3.0",
-		"@earendil-works/pi-coding-agent": "1.3.0",
-		"@earendil-works/pi-tui": "1.3.0",
+		"@earendil-works/pi-ai": "1.4.0",
+		"@earendil-works/pi-coding-agent": "1.4.0",
+		"@earendil-works/pi-tui": "1.4.0",
 		"@types/node": "^24.0.0",
 		"@types/turndown": "^5.0.5",
 		"typebox": "^1.3.3",

package/src/abort-utils.ts

@@ -1,17 +1,3 @@
-export function combineSignals(
-	userSignal: AbortSignal | undefined,
-	timeoutMs: number,
-	activeFetches: Set<AbortController>,
-): { signal: AbortSignal; cleanup: () => void } {
-	const controller = new AbortController();
-	// Register so the caller's cleanup can abort this request during shutdown/reload.
-	activeFetches.add(controller);
-	const signals: AbortSignal[] = [controller.signal, AbortSignal.timeout(timeoutMs)];
-	if (userSignal) signals.push(userSignal);
-	return {
-		signal: AbortSignal.any(signals),
-		cleanup: () => {
-			activeFetches.delete(controller);
-		},
-	};
-}
+// A request signal that aborts on the caller, a timeout, or shutdown, shared. The callers here
+// keep importing from this file.
+export { combineSignals } from "@underactive/pi-topping-primitives/abort";

package/src/env.ts

@@ -1,10 +1,6 @@
-// Same truthiness rules as pi core's isTruthyEnvFlag.
-export function isTruthyEnvFlag(value: string | undefined): boolean {
-	if (!value) return false;
-	return value === "1" || value.toLowerCase() === "true" || value.toLowerCase() === "yes";
-}
-
-/** Set when pi suppresses non-essential notifications. */
-export function suppressNotifications(env: NodeJS.ProcessEnv = process.env): boolean {
-	return isTruthyEnvFlag(env.PI_SUPPRESS_NOTIFICATIONS);
-}
+// Pi's environment-flag rule and the notification switch, shared. The callers here keep
+// importing from this file.
+export {
+	isTruthyEnvFlag,
+	suppressNotifications,
+} from "@underactive/pi-topping-primitives/env";

package/src/permission-store.ts

@@ -8,8 +8,9 @@
 
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { readFileSync } from "node:fs";
-import { mkdir, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { stat, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { atomicWriteFile } from "@underactive/pi-topping-primitives/settings";
 import { permissionKey } from "./permissions.ts";
 
 export type PermissionScope = "fetch_markdown" | "pdf_extract" | "web_browser";
@@ -169,13 +170,8 @@ async function releaseLock(): Promise<void> {
 }
 
 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());
+	atomicWriteFile(storePath(), JSON.stringify(file, null, "\t"));
 }
 
 /** Add a durable grant. Returns false if the lock could not be acquired. */

package/src/tool-exposure.ts

@@ -3,9 +3,8 @@
  * Default remains Pi's direct registration. Other modes are opt-in via settings.json.
  */
 
-import { getAgentDir, type ExtensionAPI, type ToolDefinition, type ToolExposure, type ToolNamespace } from "@earendil-works/pi-coding-agent";
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import type { ExtensionAPI, ToolDefinition, ToolExposure, ToolNamespace } from "@earendil-works/pi-coding-agent";
+import { createSettingsStore, sanitize, toppingSettingsPath } from "@underactive/pi-topping-primitives/settings";
 
 export type WebToolsExposureMode = "direct" | "codemode" | "deferred";
 
@@ -23,8 +22,13 @@ export const WEB_TOOLS_NAMESPACE: ToolNamespace = {
 
 const MAX_SETTINGS_BYTES = 64 * 1024;
 
+const defaultSettingsPath = toppingSettingsPath("pi-topping-web-tools");
+const SETTINGS_PATH_ENV = "PI_WEB_TOOLS_SETTINGS_FILE";
+
+/** `PI_WEB_TOOLS_SETTINGS_FILE` wins when non-empty; otherwise the agent-dir default. */
 export function settingsPath(): string {
-	return process.env.PI_WEB_TOOLS_SETTINGS_FILE ?? join(getAgentDir(), "pi-topping-web-tools", "settings.json");
+	const override = process.env[SETTINGS_PATH_ENV];
+	return override ? override : defaultSettingsPath();
 }
 
 export function parseToolExposureMode(value: unknown): WebToolsExposureMode {
@@ -34,30 +38,20 @@ export function parseToolExposureMode(value: unknown): WebToolsExposureMode {
 	return "direct";
 }
 
-export function loadToolExposureMode(path: string = settingsPath()): WebToolsExposureMode {
-	let raw: string;
-	try {
-		raw = readFileSync(path, "utf-8");
-	} catch {
-		return "direct";
-	}
-
-	if (Buffer.byteLength(raw) > MAX_SETTINGS_BYTES) {
-		return "direct";
-	}
-
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(raw);
-	} catch {
-		return "direct";
-	}
-
-	if (typeof parsed !== "object" || parsed === null) {
-		return "direct";
-	}
+function exposureStore(path?: string) {
+	return createSettingsStore<WebToolsExposureMode>({
+		path: path === undefined ? defaultSettingsPath : () => path,
+		...(path === undefined ? { pathEnv: SETTINGS_PATH_ENV } : {}),
+		maxBytes: MAX_SETTINGS_BYTES,
+		codec: {
+			sanitize: (raw) => (sanitize.isRecord(raw) ? parseToolExposureMode(raw.toolExposure) : "direct"),
+		},
+	});
+}
 
-	return parseToolExposureMode((parsed as { toolExposure?: unknown }).toolExposure);
+/** A missing, oversized, corrupt or unrecognised file means Pi's direct registration. */
+export function loadToolExposureMode(path?: string): WebToolsExposureMode {
+	return exposureStore(path).read();
 }
 
 export function webToolPresentation(mode: WebToolsExposureMode = loadToolExposureMode()): {

package/src/web-browser/feeds.ts

@@ -1,11 +1,5 @@
 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;
-}
+import { ENTRY_TYPES, type BrowserFeedPayload } from "@underactive/pi-topping-primitives/contracts";
 
 let extension: ExtensionAPI | undefined;
 let latestPayload: BrowserFeedPayload | undefined;
@@ -19,7 +13,7 @@ function samePayload(left: BrowserFeedPayload | undefined, right: BrowserFeedPay
 function emitBrowserState(force = false): void {
 	if (!extension || !latestPayload || (!force && samePayload(emittedPayload, latestPayload))) return;
 	try {
-		extension.appendEntry(BROWSER_FEED_TYPE, latestPayload);
+		extension.appendEntry(ENTRY_TYPES.browser, latestPayload);
 		emittedPayload = latestPayload;
 	} catch {
 		// Feed publication is best effort; leave emitted state unchanged for retry.