@underactive/pi-topping-web-tools 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [0.2.6] - 2026-10-02
+
+### Changed
+
+- Tested against pi 1.0.0. No break: the extension-facing declaration surface (`ToolDefinition`, `ExtensionAPI`, `ExtensionContext`, `ExtensionUIContext`, `defineTool`) is unchanged, `pi-ai`'s declaration surface is unchanged, and pi-tui's three changed declaration files are additive. The codemode tool description for each declared tool is now one line instead of a rendered TypeScript declaration, which shortens the prompt without changing what `promptGuidelines` contribute. `web_browser`'s `browser` status line is unaffected by the `tuiMode` default moving to `fullscreen`: the footer that renders it is mounted unconditionally and its renderer is unchanged.
+- Bumped the pinned `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` devDependencies from 0.99.2 to 1.0.0.
+- `web_browser`: added a prompt guideline that image content is not visible to a codemode script, so `screenshot` should be called directly, or with `toFile=true` to get a path the script can read.
+
+### Fixed
+
+- `fetch_markdown`, `pdf_extract`, `web_browser`: expanded result previews are bounded in wrapped rows at the render width instead of in characters. The 0.2.5 bound of 10 logical lines of 200 characters still rendered about 43 rows at 80 columns and 76 at 40; the body is now capped at 20 rows at any terminal width, using pi's `truncateToVisualLines`.
+
+## [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

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:
@@ -135,6 +142,8 @@ When `screenshot` returns an inline result (`toFile` omitted or `false`), `web_b
 
 `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.
 
+In codemode, a tool result exposes only its text blocks, so an inline `screenshot` reaches the script as its caption with no image bytes. Call `screenshot` directly from the session, or pass `toFile=true` and read the saved path from the script.
+
 The resize fields are:
 
 - `maxWidth` / `maxHeight`: pixel bounds (pi defaults to 2000×2000)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@underactive/pi-topping-web-tools",
-	"version": "0.2.4",
+	"version": "0.2.6",
 	"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.99.1",
-		"@earendil-works/pi-coding-agent": "0.99.1",
-		"@earendil-works/pi-tui": "0.99.1",
+		"@earendil-works/pi-ai": "1.0.0",
+		"@earendil-works/pi-coding-agent": "1.0.0",
+		"@earendil-works/pi-tui": "1.0.0",
 		"@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 { BoundedPreview, clipField, resultText } from "./render-preview.ts";
 import { MAX_URL_LENGTH, isLocalOrPrivateHost, upgradeHttpToHttps } from "./web-browser/permissions.ts";
 
 const MAX_HTTP_CONTENT_LENGTH = 25 * 1024 * 1024;
@@ -557,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");
 		}
@@ -571,16 +572,7 @@ 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)")}`;
-				}
-			}
+			return new BoundedPreview({ header: text, body: resultText(result.content), marker: "… (truncated)", theme });
 		}
 
 		return new Text(text, 0, 0);

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 { BoundedPreview, clipField, resultText } from "./render-preview.ts";
 import { getWithPermittedRedirects, isPermittedRedirect, sliceContent, validateURL } from "./fetch-markdown.ts";
 import { upgradeHttpToHttps } from "./web-browser/permissions.ts";
 
@@ -409,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)`);
@@ -423,16 +423,7 @@ 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)")}`;
-				}
-			}
+			return new BoundedPreview({ header: text, body: resultText(result.content), marker: "… (truncated)", theme });
 		}
 
 		return new Text(text, 0, 0);

package/src/render-preview.ts

@@ -0,0 +1,107 @@
+/**
+ * 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.
+ *
+ * `renderResult` is not handed a width, so header fields and collapsed bodies are
+ * bounded in characters. The width does reach the component it returns, through
+ * `render(width)`, so an expanded body is bounded in rows there: `BoundedPreview`
+ * wraps it with the host's `truncateToVisualLines`, which keeps its height the same
+ * at every terminal width.
+ */
+
+import { truncateToVisualLines, type Theme } from "@earendil-works/pi-coding-agent";
+import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+import { Text, type Component } from "@earendil-works/pi-tui";
+
+/** Body rows in an expanded preview, counted after wrapping at the render width. */
+export const MAX_VISUAL_PREVIEW_LINES = 20;
+
+/** Body characters handed to the wrapper: fills the row cap up to 400 columns without wrapping a 100K result on every redraw. */
+export const MAX_PREVIEW_CHARS = 8_000;
+
+/** Characters kept from a single unbounded field: a header value, status field, or collapsed body. */
+export const MAX_FIELD_CHARS = 200;
+
+/** 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;
+}
+
+export interface BoundedPreviewOptions {
+	/** Styled summary; its attacker-controlled fields are already clipped. */
+	header: string;
+	/** Raw result text, styled dim per logical line. */
+	body: string;
+	/** Raw marker shown muted when the body was cut. */
+	marker: string;
+	/** Raw line shown dim after the body whether or not it was cut. */
+	trailer?: string;
+	theme: Theme;
+}
+
+/**
+ * Expanded tool result: header, at most {@link MAX_VISUAL_PREVIEW_LINES} body rows, then the
+ * marker and trailer. Rows depend on the width, which only `render` sees; lines are cached per
+ * width because the transcript renders every result on every frame.
+ */
+export class BoundedPreview implements Component {
+	private readonly header: string;
+	private readonly body: string;
+	private readonly marker: string;
+	private readonly trailer: string | undefined;
+	private readonly cut: boolean;
+	private cachedWidth: number | undefined;
+	private cachedLines: string[] | undefined;
+
+	constructor(options: BoundedPreviewOptions) {
+		const { theme } = options;
+		this.header = options.header;
+		this.cut = options.body.length > MAX_PREVIEW_CHARS;
+		// Slice the raw text before styling so the cap never cuts an escape sequence. Every logical
+		// line takes at least one row, so one line past the cap is enough for the skip to register.
+		this.body = options.body
+			.slice(0, MAX_PREVIEW_CHARS)
+			.split("\n", MAX_VISUAL_PREVIEW_LINES + 1)
+			.map((line) => theme.fg("dim", line))
+			.join("\n");
+		this.marker = theme.fg("muted", options.marker);
+		this.trailer = options.trailer === undefined ? undefined : theme.fg("dim", options.trailer);
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines === undefined || this.cachedWidth !== width) {
+			// paddingX 0 keeps the geometry of the `new Text(text, 0, 0)` this replaces.
+			const { visualLines, skippedCount } = truncateToVisualLines(
+				this.body,
+				MAX_VISUAL_PREVIEW_LINES,
+				width,
+				0,
+				"start",
+			);
+			const lines = [...new Text(this.header, 0, 0).render(width), ...visualLines];
+			if (this.cut || skippedCount > 0) lines.push(...new Text(this.marker, 0, 0).render(width));
+			if (this.trailer !== undefined) lines.push(...new Text(this.trailer, 0, 0).render(width));
+			this.cachedLines = lines;
+			this.cachedWidth = width;
+		}
+		return this.cachedLines;
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+}

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 { BoundedPreview, clipField, 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}`,
@@ -342,6 +343,7 @@ export default function (pi: ExtensionAPI) {
 			"Use get_content only when DOM structure or attributes are needed; it returns raw HTML.",
 			"On SPA sites, use wait_for after navigate (selector/state or networkidle) before click/type.",
 			"Use screenshot for visual verification (requires a vision-capable model); use toFile=true to save PNG to disk instead of base64.",
+			"Image content is not visible to a codemode script: a script receives only a tool result's text blocks, so a screenshot taken from one returns its caption without the pixels. Call screenshot directly, or with toFile=true to get a file path the script can read.",
 			"Use get_console_logs when JavaScript errors or console output may explain page behavior.",
 			"Use get_network_logs when failed, egress-blocked, or 4xx/5xx requests may explain page behavior. Navigate directly to a blocked origin to request approval.",
 			"Use set_cookies to inject cookies for authenticated flows after manual login.",
@@ -1042,7 +1044,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");
@@ -1062,9 +1064,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":
@@ -1095,19 +1102,13 @@ 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", "…")}`;
-					}
-				}
-				if (details.fullOutputPath) {
-					text += `\n${theme.fg("dim", `Full: ${details.fullOutputPath}`)}`;
-				}
+				return new BoundedPreview({
+					header: text,
+					body: resultText(result.content),
+					marker: "…",
+					trailer: details.fullOutputPath ? `Full: ${details.fullOutputPath}` : undefined,
+					theme,
+				});
 			}
 
 			return new Text(text, 0, 0);