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

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [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
 {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@underactive/pi-topping-web-tools",
-	"version": "0.2.8",
+	"version": "0.2.9",
 	"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",
@@ -53,9 +53,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.3.0",
+		"@earendil-works/pi-coding-agent": "1.3.0",
+		"@earendil-works/pi-tui": "1.3.0",
 		"@types/node": "^24.0.0",
 		"@types/turndown": "^5.0.5",
 		"typebox": "^1.3.3",

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/tool-exposure.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 { 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";
+
+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;
+
+export function settingsPath(): string {
+	return process.env.PI_WEB_TOOLS_SETTINGS_FILE ?? join(getAgentDir(), "pi-topping-web-tools", "settings.json");
+}
+
+export function parseToolExposureMode(value: unknown): WebToolsExposureMode {
+	if (value === "codemode" || value === "deferred" || value === "direct") {
+		return value;
+	}
+	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";
+	}
+
+	return parseToolExposureMode((parsed as { toolExposure?: unknown }).toolExposure);
+}
+
+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/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" },
 				),