@underactive/pi-topping-web-tools 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [0.2.5] - 2026-09-30
+
+### Changed
+
+- Tested against pi 0.99.2. No break: the 0.99.1 to 0.99.2 extension API is additive only (`ToolNamespace.instructions`), and `pi-tui` and `pi-agent-core` declarations are unchanged.
+- Bumped the pinned `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` devDependencies from 0.99.1 to 0.99.2.
+
+### Fixed
+
+- Bounded tool result and status previews. A result that is one long logical line — minified JSON, raw HTML from `get_content` — rendered as a single unbounded logical line and word-wrapped into ~1250 screen lines. An expanded preview now keeps 10 logical lines of 200 characters, and a collapsed result whose `details` cannot be rendered is clipped to 200 characters.
+- `fetch_markdown`, `pdf_extract`, `web_browser`: attacker-controlled header fields are clipped to 200 characters before display. A hostile server could previously send a multi-megabyte HTTP reason phrase, and a page could carry a huge `<title>`; either one filled the screen from the collapsed one-line summary.
+
+## [0.2.4] - 2026-09-29
+
+### Added
+
+- Documented pi 0.87+ `inputLimits.images.resize` for `web_browser` inline screenshots: how the active model's resize profile applies to tool-result images, a cost-saving example profile, the resize note appended to resized images, and a warning that aggressive resizing can make small page text unreadable.
+- `fetch_markdown`, `pdf_extract`, `web_browser`: declare pi 0.99 tool `annotations` so permission extensions can decide which calls to confirm. `fetch_markdown` and `pdf_extract` set `readOnlyHint` and `openWorldHint`; `web_browser` sets `openWorldHint` and `readOnlyHint: false`. Older pi versions ignore the field.
+
+### Changed
+
+- Tested against pi 0.99; host-permission gates also apply to codemode script calls.
+- Bumped the pinned `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` devDependencies from 0.86.0 to 0.99.1 so `npm run typecheck` accepts tool `annotations`.
+
 ## [0.2.3] - 2026-09-20
 
 ### Changed

package/README.md

@@ -54,6 +54,13 @@ 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.
+
+### 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.
+
 ## `fetch_markdown`
 
 Complements pi's built-in search-backed `web_fetch` with a lightweight, keyless fetch path for public documentation, READMEs, and articles:
@@ -129,6 +136,47 @@ Single tool with an `action` parameter:
 
 Optional `timeout` (ms, default 30000) applies to navigation and to selector-based actions (click, type, hover, select_option, screenshot, get_text, get_markdown, wait_for, get_accessibility_snapshot, scroll, drag, upload_file). Other actions use Playwright defaults.
 
+### Screenshots and image resize
+
+When `screenshot` returns an inline result (`toFile` omitted or `false`), `web_browser` places the captured PNG in the conversation as a base64 image block. Base64 adds roughly one-third to the payload, and full-page PNGs can be several MiB. On pi 0.87+, the active model's `inputLimits.images.resize` profile is applied to these tool-result images before they enter history; the same profile covers `@file` attachments, `read`, and images returned by other tools. Images are encoded once when they enter history, so changing models later does not rewrite historical images.
+
+`toFile=true` and `/browser-screenshot` save the original PNG to disk and put only the path and dimensions in the tool result. The file is resized only if a later `read` or `@file` attachment sends it to the model.
+
+The resize fields are:
+
+- `maxWidth` / `maxHeight`: pixel bounds (pi defaults to 2000×2000)
+- `maxBytes`: maximum base64-encoded payload size (pi defaults to 4.5 MiB)
+- `jpegQuality`: JPEG quality when the PNG does not fit under `maxBytes` (pi defaults to 80)
+
+The default capture is the viewport (1280×720 unless `set_viewport` changed it); `fullPage: true` captures the whole document. `web_browser` applies a 1920px maximum-width clamp to the reported dimensions of full-page screenshots; this is metadata only, not image resizing—the returned PNG remains the original capture. Tall full-page screenshots regularly exceed the default 2000px height bound and are scaled before they enter history; for normal viewport screenshots, `maxBytes` is usually the effective cost lever.
+
+Configure a profile per model in `~/.pi/agent/models.json`; use the provider and model ID shown by `pi --list-models`. `modelOverrides.inputLimits` is deep-merged, so a resize override can be scoped to one model:
+
+```json
+{
+  "providers": {
+    "<provider>": {
+      "modelOverrides": {
+        "<model-id>": {
+          "inputLimits": {
+            "images": {
+              "resize": {
+                "maxWidth": 1568,
+                "maxHeight": 1568,
+                "maxBytes": 524288,
+                "jpegQuality": 75
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+This matches pi's documented example. It leaves a default 1280×720 viewport screenshot unscaled on the long edge, making `maxBytes` the practical size lever. When pi resizes an image, it adds a coordinate note such as `[Image: original 1280x4000, displayed at 800x2500. Multiply coordinates by 1.60 to map to original image.]`; the tool's own `Screenshot <dims>` line is only a summary of the capture, so the resize note is the authoritative account of the dimensions sent to the model. An overly tight `maxBytes` does not fail loudly: pi keeps shrinking dimensions until the encoded image fits. Aggressive values can make small page text (navigation labels, fine print, or code) unreadable, and JPEG fallback adds artifacts; prefer `get_text`, `get_markdown`, or `get_accessibility_snapshot` when the task is reading copy. Set `images.autoResize: false` in pi's settings to disable resizing globally.
+
 ### Browser network egress
 
 `web_browser` enforces its permissions inside every fresh browser context:
@@ -197,6 +245,7 @@ Commands:
 
 - **Preapproved hosts**: common documentation and dev sites are allowed without prompting. The allowlist lives in `src/permissions.ts` and is shared by both 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.
+- **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.
 - **Isolated browser context and routed egress**: each session uses a fresh Chromium context (no shared profile/cookies with your system browser). HTTP(S) requests, redirect targets, client navigations, popups, and WebSocket connections are checked against live `web_browser` permissions; service workers are disabled.
@@ -206,7 +255,7 @@ Commands:
 ## Limitations
 
 - `web_browser` requires the Chromium download.
-- Screenshots consume significant context on vision models — prefer `get_text`, `get_markdown`, or `get_accessibility_snapshot`.
+- Screenshots consume significant context on vision models — prefer `get_text`, `get_markdown`, or `get_accessibility_snapshot`. On pi 0.87+, a model-side resize profile ([Screenshots and image resize](#screenshots-and-image-resize)) can cut screenshot request size and cost; aggressive resizing can make small page text unreadable.
 - Network logs capture blocked/failed requests and 4xx/5xx responses, not successful traffic.
 - Request routing buffers HTTP(S) responses and blocks redirected subresources, so streaming endpoints and resources that rely on redirects may not behave like an unrestricted browser.
 - Playwright routing covers HTTP(S) and WebSockets, not browser transports such as WebRTC; OS-level egress sandboxing remains outside this extension's scope.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@underactive/pi-topping-web-tools",
-	"version": "0.2.3",
+	"version": "0.2.5",
 	"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": "0.86.0",
-		"@earendil-works/pi-coding-agent": "0.86.0",
-		"@earendil-works/pi-tui": "0.86.0",
+		"@earendil-works/pi-ai": "0.99.2",
+		"@earendil-works/pi-coding-agent": "0.99.2",
+		"@earendil-works/pi-tui": "0.99.2",
 		"@types/node": "^24.0.0",
 		"@types/turndown": "^5.0.5",
 		"typebox": "^1.3.3",

package/src/fetch-markdown.ts

@@ -12,6 +12,7 @@ import { combineSignals } from "./abort-utils.ts";
 import { getBrowserHeaders } from "./browser-headers.ts";
 import { isPreapprovedHost, permissionKey } from "./permissions.ts";
 import { requestHostPermission } from "./permission-prompt.ts";
+import { clipField, resultPreview, resultText } from "./render-preview.ts";
 import { MAX_URL_LENGTH, isLocalOrPrivateHost, upgradeHttpToHttps } from "./web-browser/permissions.ts";
 
 const MAX_HTTP_CONTENT_LENGTH = 25 * 1024 * 1024;
@@ -476,6 +477,7 @@ Usage notes:
 		"If fetch_markdown reports truncated content, call it again with the reported offset to read the next window.",
 	],
 	parameters: WebFetchParams,
+	annotations: { readOnlyHint: true, openWorldHint: true },
 
 	async execute(_toolCallId, params, signal, onUpdate) {
 		const start = Date.now();
@@ -556,12 +558,12 @@ To complete your request, I need to fetch content from the redirected URL. Pleas
 		}
 
 		if (!details || typeof details.bytes !== "number") {
-			const content = result.content[0];
-			return new Text(content?.type === "text" ? content.text : "", 0, 0);
+			return new Text(clipField(resultText(result.content)), 0, 0);
 		}
 
 		let text = theme.fg("success", `Received ${formatSize(details.bytes)}`);
-		text += theme.fg("muted", ` (${details.code} ${details.codeText})`);
+		// The HTTP reason phrase is attacker-controlled, so bound it like the body.
+		text += theme.fg("muted", ` (${details.code} ${clipField(details.codeText)})`);
 		if (details.cached) {
 			text += theme.fg("dim", " cached");
 		}
@@ -570,15 +572,12 @@ To complete your request, I need to fetch content from the redirected URL. Pleas
 		}
 
 		if (expanded) {
-			const content = result.content[0];
-			if (content?.type === "text") {
-				const lines = content.text.split("\n", 16);
-				for (const line of lines.slice(0, 15)) {
-					text += `\n${theme.fg("dim", line)}`;
-				}
-				if (lines.length > 15) {
-					text += `\n${theme.fg("muted", "… (truncated)")}`;
-				}
+			const preview = resultPreview(resultText(result.content));
+			for (const line of preview.lines) {
+				text += `\n${theme.fg("dim", line)}`;
+			}
+			if (preview.truncated) {
+				text += `\n${theme.fg("muted", "… (truncated)")}`;
 			}
 		}
 

package/src/pdf-extract.ts

@@ -11,6 +11,7 @@ import { extractText, getDocumentProxy } from "unpdf";
 import { combineSignals } from "./abort-utils.ts";
 import { isPreapprovedHost, permissionKey } from "./permissions.ts";
 import { requestHostPermission } from "./permission-prompt.ts";
+import { clipField, resultPreview, resultText } from "./render-preview.ts";
 import { getWithPermittedRedirects, isPermittedRedirect, sliceContent, validateURL } from "./fetch-markdown.ts";
 import { upgradeHttpToHttps } from "./web-browser/permissions.ts";
 
@@ -316,6 +317,7 @@ Usage notes:
 		"If pdf_extract reports no text layer, the PDF is scanned — say so rather than retrying.",
 	],
 	parameters: PdfExtractParams,
+	annotations: { readOnlyHint: true, openWorldHint: true },
 
 	async execute(_toolCallId, params, signal, onUpdate) {
 		const start = Date.now();
@@ -408,8 +410,7 @@ Usage notes:
 		}
 
 		if (!details || typeof details.pageCount !== "number") {
-			const content = result.content[0];
-			return new Text(content?.type === "text" ? content.text : "", 0, 0);
+			return new Text(clipField(resultText(result.content)), 0, 0);
 		}
 
 		let text = theme.fg("success", `Extracted ${details.pageCount} of ${details.totalPages} page(s)`);
@@ -422,15 +423,12 @@ Usage notes:
 		}
 
 		if (expanded) {
-			const content = result.content[0];
-			if (content?.type === "text") {
-				const lines = content.text.split("\n", 16);
-				for (const line of lines.slice(0, 15)) {
-					text += `\n${theme.fg("dim", line)}`;
-				}
-				if (lines.length > 15) {
-					text += `\n${theme.fg("muted", "… (truncated)")}`;
-				}
+			const preview = resultPreview(resultText(result.content));
+			for (const line of preview.lines) {
+				text += `\n${theme.fg("dim", line)}`;
+			}
+			if (preview.truncated) {
+				text += `\n${theme.fg("muted", "… (truncated)")}`;
 			}
 		}
 

package/src/render-preview.ts

@@ -0,0 +1,61 @@
+/**
+ * Bounded previews for tool results in the TUI.
+ *
+ * pi 0.99.2 fixed long single-line results filling the screen for bash, codemode,
+ * and MCP tool output, but that fix lives in the host's own renderers. Extension
+ * tools that supply a custom `renderResult` render whatever they return, so the
+ * same bound has to be applied here. Header fields need the same bound: an HTTP
+ * reason phrase and a page `<title>` are attacker-controlled and can be megabytes.
+ *
+ * Bounds are expressed in characters rather than visual lines because pi's `Text`
+ * word-wraps (and hard-breaks unspaced tokens) on render. That keeps the work
+ * independent of the terminal, but rendered height still scales as
+ * `characters / width`; the worst case here is about 43 lines at 80 columns and 76
+ * at 40, versus the ~1250 lines a 100K-character result produced before.
+ */
+
+import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+
+/** Logical lines shown in an expanded preview. */
+export const MAX_PREVIEW_LINES = 10;
+
+/** Characters kept per logical line in an expanded preview. */
+export const MAX_PREVIEW_LINE_CHARS = 200;
+
+/** Characters kept from a single unbounded field: a header value, status field, or collapsed body. */
+export const MAX_FIELD_CHARS = 200;
+
+export interface ResultPreview {
+	/** Logical lines to display, each already clipped to {@link MAX_PREVIEW_LINE_CHARS}. */
+	lines: string[];
+	/** Whether logical lines were dropped by the {@link MAX_PREVIEW_LINES} cap. */
+	truncated: boolean;
+}
+
+/** Concatenate a tool result's text blocks; empty when the result carries only images. */
+export function resultText(content: readonly (TextContent | ImageContent)[]): string {
+	return content
+		.filter((block): block is TextContent => block.type === "text")
+		.map((block) => block.text)
+		.join("\n");
+}
+
+/** Clip one attacker-controlled field to {@link MAX_FIELD_CHARS}, marking the cut with an ellipsis. */
+export function clipField(text: string): string {
+	return text.length > MAX_FIELD_CHARS ? `${text.slice(0, MAX_FIELD_CHARS)}…` : text;
+}
+
+/**
+ * Preview for an expanded tool result: at most {@link MAX_PREVIEW_LINES} logical lines,
+ * each clipped so one long line cannot fill the screen. A line long enough to hit the
+ * character cap loses its tail in the preview; the full text stays in the transcript.
+ */
+export function resultPreview(text: string): ResultPreview {
+	// The limit argument keeps the split bounded on a large body: one extra element is
+	// enough to detect that more lines existed.
+	const all = text.split("\n", MAX_PREVIEW_LINES + 1);
+	return {
+		lines: all.slice(0, MAX_PREVIEW_LINES).map((line) => clipField(line)),
+		truncated: all.length > MAX_PREVIEW_LINES,
+	};
+}

package/src/web-browser/index.ts

@@ -31,6 +31,7 @@ import {
 import { buildOriginChecker } from "./egress-policy.ts";
 import { checkUrlPermission, upgradeHttpToHttps, validateURL } from "./permissions.ts";
 import { requestHostPermission } from "../permission-prompt.ts";
+import { clipField, resultPreview, resultText } from "../render-preview.ts";
 import { listGrants } from "../permission-store.ts";
 import { permissionKey } from "../permissions.ts";
 import { isInsideCwd } from "../pdf-extract.ts";
@@ -291,8 +292,8 @@ export default function (pi: ExtensionAPI) {
 			const lines = [
 				"Web Browser:",
 				`  Status: ${info.isOpen ? "open" : "closed"}`,
-				`  URL: ${info.url || "(none)"}`,
-				`  Title: ${info.title?.replace(/[\u0000-\u001f\u007f]/g, " ") || "(none)"}`,
+				`  URL: ${info.url ? clipField(info.url) : "(none)"}`,
+				`  Title: ${info.title ? clipField(info.title.replace(/[\u0000-\u001f\u007f]/g, " ")) : "(none)"}`,
 				`  Tabs open: ${info.tabCount}`,
 				`  Console messages: ${info.consoleCount}`,
 				`  Network issues: ${info.networkCount}`,
@@ -469,6 +470,8 @@ export default function (pi: ExtensionAPI) {
 				Type.Number({ description: "Timeout in milliseconds for navigation/interaction (default 30000)" }),
 			),
 		}),
+		// Not read-only: click, type, evaluate, set_cookies, and upload_file act on the page.
+		annotations: { readOnlyHint: false, openWorldHint: true },
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			const action = params.action as WebBrowserAction;
@@ -1040,7 +1043,7 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (details.error) {
-				return new Text(theme.fg("error", details.error.slice(0, 120)), 0, 0);
+				return new Text(theme.fg("error", clipField(details.error)), 0, 0);
 			}
 
 			const imageBlock = result.content.find((c) => c.type === "image");
@@ -1060,9 +1063,14 @@ export default function (pi: ExtensionAPI) {
 			let text = "";
 			switch (details.action) {
 				case "navigate":
+					// The page title is attacker-controlled, so bound it like the body.
 					text = theme.fg(
 						"success",
-						`Navigated — ${details.title?.replace(/[\u0000-\u001f\u007f]/g, " ") ?? details.url ?? "ok"}`,
+						`Navigated — ${
+							details.title
+								? clipField(details.title.replace(/[\u0000-\u001f\u007f]/g, " "))
+								: clipField(details.url ?? "ok")
+						}`,
 					);
 					break;
 				case "get_content":
@@ -1093,15 +1101,12 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			if (expanded) {
-				const content = result.content.find((c) => c.type === "text");
-				if (content?.type === "text") {
-					const lines = content.text.split("\n", 16);
-					for (const line of lines.slice(0, 15)) {
-						text += `\n${theme.fg("dim", line)}`;
-					}
-					if (lines.length > 15) {
-						text += `\n${theme.fg("muted", "…")}`;
-					}
+				const preview = resultPreview(resultText(result.content));
+				for (const line of preview.lines) {
+					text += `\n${theme.fg("dim", line)}`;
+				}
+				if (preview.truncated) {
+					text += `\n${theme.fg("muted", "…")}`;
 				}
 				if (details.fullOutputPath) {
 					text += `\n${theme.fg("dim", `Full: ${details.fullOutputPath}`)}`;