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

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## [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
+
+- Optional `toolExposure` setting (`direct` default, or `codemode` / `deferred`) in `~/.pi/agent/pi-topping-web-tools/settings.json`. All three tools share the `pi-topping-web-tools` namespace. At each session start, a non-`direct` mode activates the loader it needs with `pi.setActiveTools()`: `codemode` for `codemode`, and `tool_search` (or `codemode` when `tool_search` is not registered) for `deferred`. `defaultTools` needs no `+codemode` / `+tool_search` entry. When `--tools` or `--exclude-tools` leaves the loader out, the extension notifies once instead.
+- README settings profiles for default direct tools, codemode-minimal (`inlineBudget: 0`), and deferred + `tool_search`. Clarified that a large `inlineBudget` moves declarations into the `codemode` description instead of shrinking them.
+
+### Changed
+
+- Tested against pi 1.2.0. No break: the 1.2.0 breaking changes (`before_agent_start` for `triggerTurn` runs, busy session during run start, theme schema validation, `pi mcp list --json` shape) touch APIs and resources this package does not use.
+- Bumped the pinned `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` devDependencies from 1.1.0 to 1.2.0.
+- Tested against pi 1.3.0. No break: the extension-facing declaration surface (`ExtensionAPI`, `ToolDefinition`, `ExtensionContext`, `ExtensionUIContext`) is unchanged, pi-ai only adds optional `ToolCall.argumentsError`, and pi-tui is unchanged. Provider, `/share`, and model-switching changes do not reach these tools.
+- Bumped the pinned `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` devDependencies from 1.2.0 to 1.3.0.
+
+### Fixed
+
+- `web_browser`: the `mode`, `state`, `cookies[].sameSite`, and `dialogAction` parameter schemas now pass `as const` arrays to `StringEnum`, so their inferred types are the literal unions instead of `string`. This fixes four `tsc` errors; runtime validation is unchanged.
+
 ## [0.2.8] - 2026-10-12
 
 ### Added

package/README.md

@@ -54,16 +54,68 @@ Start with `fetch_markdown` for efficient static content; use `web_browser` when
 | `pdf_extract` | Extract the text layer from a remote or local PDF, with page markers |
 | `web_browser` | Headless Chromium automation — navigate, click, type, screenshot, evaluate, logs, cookies |
 
-All three tools are `direct`-exposure and pi activates those on registration (`defaultActive` defaults to true), so nothing needs to be enabled.
+By default all three tools use `direct` exposure. Pi activates those on registration (`defaultActive` defaults to true), so a default install needs no extra `defaultTools` entry.
+
+### Tool exposure (optional)
+
+A single setting controls how the model reaches all three tools. It does not change host allowlists, permission prompts, or `--exclude-tools` / `defaultTools` filtering. Set it in `~/.pi/agent/pi-topping-web-tools/settings.json` (no TUI control):
+
+```json
+{
+  "toolExposure": "direct"
+}
+```
+
+| `toolExposure` | Tool `exposure` | Loader the extension activates |
+|----------------|-----------------|--------------------------------|
+| `direct` (default) | `direct`, active on register | None |
+| `codemode` | `codemode` | `codemode` |
+| `deferred` | `deferred` | `tool_search`, or `codemode` when `tool_search` is not available |
+
+All three tools share the `pi-topping-web-tools` namespace so `searchTools()` and `describeNamespace("pi-topping-web-tools")` can find them when they are not listed inline.
+
+Needs pi ≥0.99.0 for `codemode` / `tool_search` / `exposure`. Screenshot inspection from a script needs pi ≥1.0.4 (`toFile=true`, then `tools.read` and `image()`).
+
+At every session start (startup, reload, new, resume, and fork), the extension activates the loader with `pi.setActiveTools()`, as Pi's MCP support does for MCP servers. You do not need `+codemode` or `+tool_search` in `defaultTools`. The loader is a session-wide Pi tool, so the model can also use it for the other tools in the session, not only for these three. `--tools` and `--exclude-tools` unregister a loader they leave out. The extension does not activate that loader. It notifies once at session start instead, because the model cannot reach the tools.
+
+`codemode.mode: "only"` is a session-wide Pi setting. While it is on, the model must call bash/read/edit/write through `codemode` as well, not only these web tools. `--tools` still applies, for example `pi --tools +codemode,-web_browser`.
 
 ### Enabling and disabling tools
 
 - To hide a tool for a session, name it in `--exclude-tools` (or start with `--no-tools` and re-add what you want with `--tools`).
 - To change the startup set in your `settings.json`, use `defaultTools`. Bare names **replace** pi's defaults, so write `"+fetch_markdown"` to add a tool without dropping `read`, `bash`, `edit`, and `write`. On pi 0.99.2+, `/reload` activates tools **newly added** to `defaultTools` without a restart. The reverse does not follow: a tool **removed** from `defaultTools` stays active until you restart, and a tool you turned off during the session stays off. `--tools`, `--no-tools`, and `--no-builtin-tools` still override the setting, on reload as well.
 
+### Settings profiles for smaller prompts
+
+These snippets go in `~/.pi/agent/settings.json`. They are optional. Default installs can omit them.
+
+**Default (unchanged).** Direct tools. No codemode. Full tool schemas stay in the prompt.
+
+**Codemode-minimal.** Hide direct declarations and keep the `codemode` description small. `inlineBudget: 0` lists namespaces only. Scripts find tools with `searchTools()` / `describeTool()` / `describeNamespace()`. `inlineBudget: 4096` (or more) instead copies the full seven-tool catalog into the `codemode` description. That **moves** the schemas; it does not shrink them. Use `0` (or a small budget such as `512` for `fetch_markdown` / `pdf_extract` only) when the goal is fewer prompt tokens.
+
+```json
+{
+  "defaultTools": ["+codemode"],
+  "codemode.mode": "only",
+  "codemode.inlineBudget": 0
+}
+```
+
+With `toolExposure` still `direct`, `mode: "only"` hides the active declarations while they stay callable from scripts. Set `"toolExposure": "codemode"` in the extension settings file if you also want these three tools off the active set unless a loader activates them.
+
+**Deferred + tool_search.** Register the tools as `deferred` and let `tool_search` load a schema on the next turn. The extension activates `tool_search`, so `~/.pi/agent/settings.json` needs no change.
+
+`~/.pi/agent/pi-topping-web-tools/settings.json`:
+
+```json
+{
+  "toolExposure": "deferred"
+}
+```
+
 ### Codemode tool listing
 
-With `codemode.mode: "only"`, pi hides the direct declarations of active tools, so the model calls them from `codemode` scripts, and the `codemode` description lists each callable tool instead, with its prompt guidelines on pi 1.0.4+. Listed tools share `codemode.inlineBudget`, which defaults to 3000 estimated tokens (characters / 4); tools that do not fit are left out and are reached with `searchTools()` or `describeTool()`. On pi 1.0.4+, the seven-tool catalog `fetch_markdown`, `pdf_extract`, `web_browser`, plus built-in `read`, `bash`, `edit`, and `write` needs about 3,700 tokens as of pi 1.1.0 — `web_browser` alone is about 1,600, the largest section — so the default budget drops `web_browser` from that list. Set the budget to 4096 or more if you use `only` with these tools; real sessions that load more extensions need more.
+With `codemode.mode: "only"`, pi hides the direct declarations of active tools, so the model calls them from `codemode` scripts, and the `codemode` description lists each callable tool instead, with its prompt guidelines on pi 1.0.4+. Listed tools share `codemode.inlineBudget`, which defaults to 3000 estimated tokens (characters / 4); tools that do not fit are left out and are reached with `searchTools()` or `describeTool()`. `0` lists only namespaces. On pi 1.0.4+, the seven-tool catalog `fetch_markdown`, `pdf_extract`, `web_browser`, plus built-in `read`, `bash`, `edit`, and `write` needs about 3,700 tokens as of pi 1.1.0 — `web_browser` alone is about 1,600, the largest section — so the default budget drops `web_browser` from that list. Set the budget to 4096 or more if you use `only` and want every tool inline; real sessions that load more extensions need more. Use `0` when you want the smallest `codemode` description.
 
 ```json
 {
@@ -257,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.8",
+	"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.1.0",
-		"@earendil-works/pi-coding-agent": "1.1.0",
-		"@earendil-works/pi-tui": "1.1.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/fetch-markdown.ts

@@ -13,6 +13,7 @@ import { getBrowserHeaders } from "./browser-headers.ts";
 import { isPreapprovedHost, permissionKey } from "./permissions.ts";
 import { requestHostPermission } from "./permission-prompt.ts";
 import { BoundedPreview, clipField, resultText } from "./render-preview.ts";
+import { attachExposureLoader, registerWebTool } from "./tool-exposure.ts";
 import { MAX_URL_LENGTH, isLocalOrPrivateHost, upgradeHttpToHttps } from "./web-browser/permissions.ts";
 
 const MAX_HTTP_CONTENT_LENGTH = 25 * 1024 * 1024;
@@ -582,7 +583,8 @@ To complete your request, I need to fetch content from the redirected URL. Pleas
 export default function (pi: ExtensionAPI) {
 	const sessionPermissions = new Map<string, "allow" | "deny">();
 
-	pi.registerTool(fetchMarkdownTool);
+	registerWebTool(pi, fetchMarkdownTool);
+	attachExposureLoader(pi);
 
 	pi.on("tool_call", async (event, ctx) => {
 		if (event.toolName !== "fetch_markdown") return undefined;

package/src/pdf-extract.ts

@@ -12,6 +12,7 @@ import { combineSignals } from "./abort-utils.ts";
 import { isInsideCwd, isPreapprovedHost, permissionKey } from "./permissions.ts";
 import { requestHostPermission } from "./permission-prompt.ts";
 import { BoundedPreview, clipField, resultText } from "./render-preview.ts";
+import { attachExposureLoader, registerWebTool } from "./tool-exposure.ts";
 import { getWithPermittedRedirects, isPermittedRedirect, sliceContent, validateURL } from "./fetch-markdown.ts";
 import { upgradeHttpToHttps } from "./web-browser/permissions.ts";
 
@@ -428,7 +429,8 @@ Usage notes:
 export default function (pi: ExtensionAPI) {
 	const sessionPermissions = new Map<string, "allow" | "deny">();
 
-	pi.registerTool(pdfExtractTool);
+	registerWebTool(pi, pdfExtractTool);
+	attachExposureLoader(pi);
 
 	pi.on("tool_call", async (event, ctx) => {
 		if (event.toolName !== "pdf_extract") return undefined;

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

@@ -0,0 +1,131 @@
+/**
+ * Shared ToolExposure + namespace for fetch_markdown, pdf_extract, and web_browser.
+ * Default remains Pi's direct registration. Other modes are opt-in via settings.json.
+ */
+
+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";
+
+export const WEB_TOOLS_NAMESPACE: ToolNamespace = {
+	name: "pi-topping-web-tools",
+	description: "Keyless fetch_markdown, pdf_extract, and headless web_browser.",
+	instructions: [
+		"Use fetch_markdown for public HTML documentation, READMEs, and articles when you want turndown markdown and a 15-minute cache.",
+		"Use pdf_extract for a remote or local PDF. fetch_markdown and web_fetch cannot read PDF text.",
+		"Use web_browser for JavaScript-rendered pages, local servers, screenshots, and interaction.",
+		"Host allowlist and permission prompts still apply. Exposure only changes how the model sees the tools, not what they may execute.",
+		"See the package README sections for fetch_markdown, pdf_extract, and web_browser.",
+	].join("\n"),
+};
+
+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 {
+	const override = process.env[SETTINGS_PATH_ENV];
+	return override ? override : defaultSettingsPath();
+}
+
+export function parseToolExposureMode(value: unknown): WebToolsExposureMode {
+	if (value === "codemode" || value === "deferred" || value === "direct") {
+		return value;
+	}
+	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"),
+		},
+	});
+}
+
+/** 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()): {
+	exposure: ToolExposure;
+	namespace: ToolNamespace;
+} {
+	return {
+		exposure: mode,
+		namespace: WEB_TOOLS_NAMESPACE,
+	};
+}
+
+export function registerWebTool(pi: ExtensionAPI, tool: ToolDefinition): void {
+	pi.registerTool({ ...tool, ...webToolPresentation() });
+}
+
+let didNotifyPrerequisites = false;
+
+export function _resetExposureNoticeForTests(): void {
+	didNotifyPrerequisites = false;
+}
+
+/** Loader tools that reach tools with this exposure, in the order to activate them. */
+function exposureLoaders(mode: WebToolsExposureMode): readonly string[] {
+	if (mode === "codemode") return ["codemode"];
+	if (mode === "deferred") return ["tool_search", "codemode"];
+	return [];
+}
+
+/**
+ * The registered loader tool to activate so the model can reach the web tools, or undefined when a
+ * loader is already active or none is registered. `--tools` and `--exclude-tools` unregister tools,
+ * so an excluded loader is never activated.
+ */
+export function exposureLoaderToActivate(
+	mode: WebToolsExposureMode,
+	activeTools: readonly string[],
+	registeredTools: readonly string[],
+): string | undefined {
+	const loaders = exposureLoaders(mode);
+	if (loaders.some((name) => activeTools.includes(name))) return undefined;
+	return loaders.find((name) => registeredTools.includes(name));
+}
+
+export function exposurePrerequisiteNotice(
+	mode: WebToolsExposureMode,
+	activeTools: readonly string[],
+): string | undefined {
+	if (mode === "direct") return undefined;
+	if (exposureLoaders(mode).some((name) => activeTools.includes(name))) return undefined;
+	if (mode === "codemode") {
+		return 'pi-topping-web-tools toolExposure is "codemode", but the codemode tool is not available, so the model cannot reach the tools. Check --tools and --exclude-tools, or set toolExposure to "direct".';
+	}
+	return 'pi-topping-web-tools toolExposure is "deferred", but neither tool_search nor codemode is available, so the model cannot reach the tools. Check --tools and --exclude-tools, or set toolExposure to "direct".';
+}
+
+/**
+ * On every session start, activate the loader tool the configured exposure needs, as Pi's MCP support
+ * does for MCP servers. Notify once when no loader can be activated.
+ */
+export function attachExposureLoader(pi: ExtensionAPI): void {
+	pi.on("session_start", (_event, ctx) => {
+		const mode = loadToolExposureMode();
+		if (mode === "direct") return;
+		if (typeof pi.getActiveTools !== "function") return;
+		const active = pi.getActiveTools();
+		const loader = exposureLoaderToActivate(mode, active, pi.getAllTools().map((tool) => tool.name));
+		if (loader) pi.setActiveTools([...active, loader]);
+		if (didNotifyPrerequisites) return;
+		const message = exposurePrerequisiteNotice(mode, pi.getActiveTools());
+		if (!message) return;
+		didNotifyPrerequisites = true;
+		if (ctx.hasUI) {
+			ctx.ui.notify(message, "warning");
+		}
+	});
+}

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.

package/src/web-browser/index.ts

@@ -34,6 +34,7 @@ import { listGrants } from "../permission-store.ts";
 import { isInsideCwd, permissionKey } from "../permissions.ts";
 import { suppressNotifications } from "../env.ts";
 import { publishBrowserState, registerBrowserFeeds } from "./feeds.ts";
+import { attachExposureLoader, webToolPresentation } from "../tool-exposure.ts";
 
 const ACTIONS = [
 	"navigate",
@@ -228,6 +229,7 @@ export default function (pi: ExtensionAPI) {
 		return manager;
 	};
 	registerBrowserFeeds(pi);
+	attachExposureLoader(pi);
 
 	pi.on("session_start", async (_event, ctx) => {
 		const info = await getConfiguredBrowserManager().getPageInfoAsync();
@@ -322,9 +324,12 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	const presentation = webToolPresentation();
 	pi.registerTool({
 		name: "web_browser",
 		label: "Web Browser",
+		exposure: presentation.exposure,
+		namespace: presentation.namespace,
 		promptSnippet:
 			"Automate a headless browser to navigate sites, click/type, capture screenshots, evaluate JS, and read console logs.",
 		promptGuidelines: [
@@ -389,7 +394,7 @@ export default function (pi: ExtensionAPI) {
 				Type.Number({ description: "Tab index to switch to, from list_tabs (action: switch_tab)" }),
 			),
 			dialogAction: Type.Optional(
-				StringEnum(["accept", "dismiss"], {
+				StringEnum(["accept", "dismiss"] as const, {
 					description:
 						"How to resolve future JS dialogs (alert/confirm/prompt) for the rest of the session (action: set_dialog_behavior, default dismiss)",
 				}),
@@ -418,13 +423,13 @@ export default function (pi: ExtensionAPI) {
 				Type.Number({ description: "Viewport height in pixels (action: set_viewport)" }),
 			),
 			mode: Type.Optional(
-				StringEnum(["fill", "press"], {
+				StringEnum(["fill", "press"] as const, {
 					description:
 						"Typing mode (action: type, default fill). fill clears the field first; press types key-by-key and appends to existing input.",
 				}),
 			),
 			state: Type.Optional(
-				StringEnum(["visible", "hidden", "attached", "detached"], {
+				StringEnum(["visible", "hidden", "attached", "detached"] as const, {
 					description: "Wait state (action: wait_for, default visible)",
 				}),
 			),
@@ -453,7 +458,7 @@ export default function (pi: ExtensionAPI) {
 						path: Type.Optional(Type.String()),
 						httpOnly: Type.Optional(Type.Boolean()),
 						secure: Type.Optional(Type.Boolean()),
-						sameSite: Type.Optional(StringEnum(["Strict", "Lax", "None"])),
+						sameSite: Type.Optional(StringEnum(["Strict", "Lax", "None"] as const)),
 					}),
 					{ description: "Cookies to set (action: set_cookies); each needs url or domain+path" },
 				),