pi-lean-search 0.4.0 → 0.6.0

package/README.md

@@ -1,4 +1,4 @@
-# pi-lean-search
+# pi-lean-search User Guide
 
 > SearXNG search tool for Pi. Pairs with [pi-lean-portal](https://www.npmjs.com/package/pi-lean-portal)'s
 > `/web` toggle — search-only installs are valid, or add it to a portal install
@@ -8,17 +8,31 @@
 
 ## Quick start
 
+`web-search` needs a SearXNG instance to talk to. If you don't have one,
+the fastest route is the official Docker image:
+
 ```bash
-pi install npm:pi-lean-portal   # recommended: browser + /web toggle
-pi install npm:pi-lean-search   # adds web-search to /web on|off
+docker run -d --name searxng -p 8888:8080 searxng/searxng
 ```
 
-Or get the full suite in one command:
+Any reachable SearXNG instance works — self-hosted or public. See the
+[SearXNG docs](https://docs.searxng.org/) for other install methods and
+instance administration.
+
+Then install the tool:
 
 ```bash
-pi install npm:pi-lean-dimension # portal + search, requires SearXNG server
+pi install npm:pi-lean-search
 ```
 
+Pair with [pi-lean-portal](https://www.npmjs.com/package/pi-lean-portal) for
+browser tools + the `/web` toggle, or install
+[pi-lean-dimension](https://www.npmjs.com/package/pi-lean-dimension) to get
+both in one command.
+
+Finally, point the tool at your instance — [Configuration](#configuration)
+below.
+
 ## Usage
 
 | Command / Tool | Description |
@@ -45,8 +59,29 @@ Set the URL of your SearXNG instance in your Pi settings file:
 ```
 
 - **Self-hosted SearXNG:** Run your own instance ([docs](https://docs.searxng.org/)).
+- **Public instance:** Any SearXNG instance you can reach works — set its URL here. Check the instance's terms or rate limits before pointing an automated tool at it.
 - No URL configured? The tool returns a setup message on its first call — no errors, no broken prompts.
 
+### Example output
+
+A `web-search` call renders as a numbered list the agent reads:
+
+```text
+1. Example result title
+   https://example.com/page
+   one-line snippet from the page
+   [engine] | score: 1.00
+2. …
+```
+
+The snippet line is omitted when the page has no content. The
+`[engine] | score:` suffix appears when the result carries engine/score
+metadata; the engine tag itself is shown only when multiple results are
+requested.
+
+SearXNG instant answers (calculator, weather, translations) are passed
+through when the query triggers them.
+
 ## Graceful degradation
 
 If SearXNG is unreachable or unconfigured, the `web-search` tool returns a clear
@@ -54,6 +89,8 @@ message pointing you toward setup instructions. It never throws or breaks the ag
 
 ## Tests
 
+From the [monorepo root](https://github.com/coreyryanhanson/pi-lean-dimension):
+
 ```bash
 npx vitest run packages/pi-lean-search/
 ```

package/index.ts

@@ -23,7 +23,7 @@ import {
 } from "pi-tool-masking";
 import type { ToolsetSpec, ToolsetChangedEvent } from "pi-tool-masking";
 import { readSearxngUrl } from "./search-config.js";
-import { webSearchTool } from "./web-search-tool.js";
+import { webSearchTool, normalizeBaseUrl } from "./web-search-tool.js";
 
 // ─── Toolset spec ────────────────────────────────────────────────
 
@@ -54,63 +54,34 @@ let _lastCtx: ExtensionContext | null = null;
 // ─── Health probes ───────────────────────────────────────────────
 
 /**
- * Lightweight server probe — fetches the SearXNG root HTML page.
- * Fast (~ms) because it only needs the HTTP response, not the full
- * aggregation pipeline.
+ * Shared probe — fetch a URL with a timeout, report reachability.
+ * With `parseJson`, additionally require the body to parse as JSON
+ * (full-pipeline check: triggers SearXNG upstream aggregation, slower).
  */
-async function checkServerReachable(
+async function probe(
 	url: string,
-	signal?: AbortSignal,
+	timeoutMs: number,
+	signal: AbortSignal | undefined,
+	opts?: { parseJson?: boolean },
 ): Promise<boolean> {
 	try {
 		const controller = new AbortController();
-		const timeoutId = setTimeout(() => controller.abort(), 2000);
+		const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
 
 		let res: Response;
 		try {
 			const mergedSignal = signal
 				? AbortSignal.any([signal, controller.signal])
 				: controller.signal;
-			res = await fetch(url, { signal: mergedSignal });
+			const init: RequestInit = { signal: mergedSignal };
+			if (opts?.parseJson) init.headers = { Accept: "application/json" };
+			res = await fetch(url, init);
 		} finally {
 			clearTimeout(timeoutId);
 		}
 
-		return res.ok && res.status === 200;
-	} catch {
-		return false;
-	}
-}
-
-/**
- * Full-pipeline probe — verifies the search API actually works end-to-end.
- * Triggers upstream engine aggregation, so it takes longer (5s timeout).
- */
-async function checkSearchReachable(
-	url: string,
-	signal?: AbortSignal,
-): Promise<boolean> {
-	const normalized = url.replace(/\/+$/, "");
-	const searchUrl = `${normalized}/search?q=ping&format=json`;
-
-	try {
-		const controller = new AbortController();
-		const timeoutId = setTimeout(() => controller.abort(), 5000);
-
-		let res: Response;
-		try {
-			const mergedSignal = signal
-				? AbortSignal.any([signal, controller.signal])
-				: controller.signal;
-			res = await fetch(searchUrl, {
-				signal: mergedSignal,
-				headers: { Accept: "application/json" },
-			});
-		} finally {
-			clearTimeout(timeoutId);
-		}
-
-		if (!res.ok || res.status !== 200) return false;
+		if (!res.ok) return false;
+		if (!opts?.parseJson) return true;
 		const text = await res.text();
 		if (!text) return false;
 		JSON.parse(text);
@@ -120,6 +91,21 @@ async function checkSearchReachable(
 	}
 }
 
+/** Lightweight server probe — SearXNG root page, HTTP response only. */
+function checkServerReachable(url: string, signal?: AbortSignal) {
+	return probe(url, 2000, signal);
+}
+
+/** Full-pipeline probe — `/search?q=ping&format=json`, JSON body required. */
+function checkSearchReachable(url: string, signal?: AbortSignal) {
+	return probe(
+		`${normalizeBaseUrl(url)}/search?q=ping&format=json`,
+		5000,
+		signal,
+		{ parseJson: true },
+	);
+}
+
 // ─── Status slot helpers ─────────────────────────────────────────
 
 /**
@@ -191,9 +177,6 @@ export { _resetStateForTest };
 // ─── Extension entry point ───────────────────────────────────────
 
 export default function (pi: ExtensionAPI) {
-	// Read config at startup
-	_searxngUrl = readSearxngUrl();
-
 	// ── Register the web-search tool ─────────────────────────
 	pi.registerTool(webSearchTool);
 
@@ -202,7 +185,7 @@ export default function (pi: ExtensionAPI) {
 	const searchToolset = defineToolset(pi, SEARCH_WEB_SPEC);
 
 	// ── Co-activation: mirror pi-lean-dimension.web changed events ─
-	// Listen on changed ONLY, not restored (§10.1).
+	// Listen on changed ONLY, not restored.
 	//
 	// Focus-mode guard: while allowlist focus holds the line, skip
 	// co-activation. The focus set is authoritative, so a web `changed` event
@@ -232,7 +215,7 @@ export default function (pi: ExtensionAPI) {
 	pi.events.on(TOOLSET_EVENTS.restored, syncSearchState);
 
 	// ── Session start: health probe + glyph ──────────────────
-	pi.on("session_start", async (_event, ctx) => {
+	pi.on("session_start", async (event, ctx) => {
 		_lastCtx = ctx;
 
 		// Re-read config in case it changed between sessions
@@ -241,6 +224,15 @@ export default function (pi: ExtensionAPI) {
 		if (!_searxngUrl) {
 			_lastHealth = null;
 			renderSearchGlyph(ctx);
+			// Discoverability hint only on Pi process boot — not on /new,
+			// /resume, or /fork, where it would be repeated noise.
+			if (event.reason === "startup") {
+				ctx.ui.notify(
+					"SearXNG is not configured (set `searxng.url` in settings.json) — " +
+						"web-search is disabled. Run /searxng-status after configuring.",
+					"warning",
+				);
+			}
 			return;
 		}
 
@@ -302,7 +294,7 @@ export default function (pi: ExtensionAPI) {
 						"Set `searxng.url` in your Pi settings.json.",
 					"error",
 				);
-				_lastHealth = false;
+				_lastHealth = null;
 				renderSearchGlyph(ctx);
 				return;
 			}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-lean-search",
-	"version": "0.4.0",
-	"description": "Pi extension. SearXNG search tool for Pi — pairs with pi-lean-portal's /web toggle; search-only installs are valid, or add it to a portal install for the full web-tools suite.",
+	"version": "0.6.0",
+	"description": "SearXNG web search for Pi. Self-hosted or public instance, no API keys or quotas; returns a setup message instead of erroring when unreachable. Pairs with pi-lean-portal's /web toggle or works standalone.",
 	"keywords": [
 		"pi-package",
 		"pi-extension",
@@ -24,8 +24,6 @@
 		"LICENSE",
 		"web-search-tool.ts",
 		"search-config.ts",
-		"verify-ship-manifest.ts",
-		"ship-manifest.test.ts",
 		"README.md"
 	],
 	"pi": {
@@ -38,14 +36,13 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"pi-tool-masking": "^1.2.0"
+		"pi-tool-masking": "^1.3.0"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",
 		"@earendil-works/pi-coding-agent": "*",
 		"@earendil-works/pi-tui": "*",
-		"pi-lean-portal": "*",
-		"typebox": "*"
+		"pi-lean-portal": "*"
 	},
 	"peerDependenciesMeta": {
 		"pi-lean-portal": {

package/search-config.ts

@@ -2,7 +2,11 @@
  * Config reader for pi-lean-search.
  *
  * Reads `searxng.url` from Pi's merged settings.json files
- * (global ~/.pi/agent/settings.json + project-local .pi/settings.json).
+ * (global settings.json + project-local .pi/settings.json).
+ *
+ * The global path honors `PI_CODING_AGENT_DIR`, matching pi-tool-masking's
+ * `settingsPath()` — otherwise a relocated agent dir would read its toolset
+ * defaults from one file and `searxng.url` from another.
  *
  * The expected shape in settings.json:
  * ```json
@@ -10,14 +14,16 @@
  * ```
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
 // ─── Config paths ─────────────────────────────────────────────────
 
-/** Global pi settings path. */
-const GLOBAL_SETTINGS_PATH = join(homedir(), ".pi", "agent", "settings.json");
+/** Global pi settings dir (`$PI_CODING_AGENT_DIR` or `~/.pi/agent`). */
+function globalSettingsDir(): string {
+ return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+}
 
 /** Project-local pi settings path (relative to cwd). */
 const PROJECT_SETTINGS_PATH = ".pi/settings.json";
@@ -25,24 +31,24 @@ const PROJECT_SETTINGS_PATH = ".pi/settings.json";
 // ─── Reader ───────────────────────────────────────────────────────
 
 function readSettingsFile(path: string): Record<string, unknown> {
-	try {
-		if (!existsSync(path)) return {};
-		const raw = readFileSync(path, "utf-8");
-		const parsed = JSON.parse(raw);
-		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-			return parsed as Record<string, unknown>;
-		}
-		return {};
-	} catch {
-		return {};
-	}
+ try {
+  // Missing/invalid files throw and fall through to the catch → {}.
+  const raw = readFileSync(path, "utf-8");
+  const parsed = JSON.parse(raw);
+  if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+   return parsed as Record<string, unknown>;
+  }
+  return {};
+ } catch {
+  return {};
+ }
 }
 
 /**
  * Read the configured SearXNG URL from merged Pi settings.
  *
  * Looks up `searxng.url` in:
- *   1. `~/.pi/agent/settings.json` (global)
+ *   1. `<agent dir>/settings.json` (global; `PI_CODING_AGENT_DIR` or `~/.pi/agent`)
  *   2. `.pi/settings.json` (project-local, overrides global)
  *
  * Returns the URL string if configured, or `undefined` if absent
@@ -50,14 +56,14 @@ function readSettingsFile(path: string): Record<string, unknown> {
  * message when no URL is configured).
  */
 export function readSearxngUrl(): string | undefined {
-	const global = readSettingsFile(GLOBAL_SETTINGS_PATH);
-	const project = readSettingsFile(PROJECT_SETTINGS_PATH);
-	const merged = { ...global, ...project };
-
-	const searxng = merged.searxng;
-	if (searxng && typeof searxng === "object" && !Array.isArray(searxng)) {
-		const url = (searxng as Record<string, unknown>).url;
-		if (typeof url === "string" && url.length > 0) return url;
-	}
-	return undefined;
+ const global = readSettingsFile(join(globalSettingsDir(), "settings.json"));
+ const project = readSettingsFile(PROJECT_SETTINGS_PATH);
+ const merged = { ...global, ...project };
+
+ const searxng = merged.searxng;
+ if (searxng && typeof searxng === "object" && !Array.isArray(searxng)) {
+  const url = (searxng as Record<string, unknown>).url;
+  if (typeof url === "string" && url.length > 0) return url;
+ }
+ return undefined;
 }

package/web-search-tool.ts

@@ -27,10 +27,7 @@ interface SearXNGAnswerLegacy {
 
 interface SearXNGAnswerTranslationItem {
 	text: string;
-	transliteration?: string;
-	definitions?: string[];
 	synonyms?: string[];
-	examples?: string[];
 }
 
 interface SearXNGAnswerTranslations {
@@ -45,7 +42,7 @@ interface SearXNGWeatherQuantity {
 }
 
 interface SearXNGWeatherItem {
-	location?: { name: string; latitude?: number; longitude?: number };
+	location?: { name: string };
 	temperature?: SearXNGWeatherQuantity;
 	condition?: string;
 	summary?: string;
@@ -58,7 +55,6 @@ interface SearXNGWeatherItem {
 interface SearXNGAnswerWeather {
 	template: "answer/weather.html";
 	current: SearXNGWeatherItem;
-	forecasts?: SearXNGWeatherItem[];
 	service?: string;
 }
 
@@ -75,6 +71,21 @@ interface SearXNGResponse {
 
 // ─── Answer rendering ────────────────────────────────────────────
 
+// Duck-types an unknown SearXNG answer template so it still renders.
+function unknownAnswerFallback(a: SearXNGAnswer): {
+	template: string;
+	answer?: string;
+} {
+	// SAFETY: SearXNG can return answer templates not in the union above;
+	// the payload is untyped JSON, so duck-type it as a generic record and
+	// pick up a bare `answer` string if present.
+	const f = a as unknown as Record<string, unknown>;
+	return {
+		template: String(f.template ?? "?"),
+		...(typeof f.answer === "string" ? { answer: f.answer } : {}),
+	};
+}
+
 // Box width (chars). Title row: `┌─ <title> ` + dashes to reach BOX_W.
 const BOX_W = 40;
 
@@ -101,7 +112,8 @@ function windLine(c: SearXNGWeatherItem): string {
 function renderAnswers(answers: SearXNGAnswer[]): string {
 	const blocks: string[] = [];
 
-	for (const a of answers.slice(0, 3)) {
+	// Callers pre-slice to 3 — don't cap again here.
+	for (const a of answers) {
 		let title: string;
 		let lines: string[];
 		switch (a.template) {
@@ -157,14 +169,13 @@ function renderAnswers(answers: SearXNGAnswer[]): string {
 				break;
 			}
 			default: {
-				const f = a as unknown as Record<string, unknown>;
-				if ("answer" in f && typeof f.answer === "string") {
-					title = "Answer";
-					lines = [trunc(f.answer as string, 500)];
-				} else {
-					blocks.push(`[answer: ${String(f.template ?? "?")}]`);
+				const fallback = unknownAnswerFallback(a);
+				if (fallback.answer === undefined) {
+					blocks.push(`[answer: ${fallback.template}]`);
 					continue;
 				}
+				title = "Answer";
+				lines = [trunc(fallback.answer, 500)];
 			}
 		}
 		blocks.push(box(title, lines));
@@ -194,19 +205,23 @@ function answerDetail(a: SearXNGAnswer): {
 		case "answer/weather.html":
 			return { template: a.template, text: a.current?.summary ?? "" };
 		default: {
-			const f = a as unknown as Record<string, unknown>;
-			return { template: String(f.template ?? "?"), text: "" };
+			const fallback = unknownAnswerFallback(a);
+			return { template: fallback.template, text: fallback.answer ?? "" };
 		}
 	}
 }
 
 // ─── URL building ─────────────────────────────────────────────────
 
-function buildSearchUrl(
+/** Strip trailing slashes so `${base}/search` never double-slashes. */
+export function normalizeBaseUrl(baseUrl: string): string {
+	return baseUrl.replace(/\/+$/, "");
+}
+
+export function buildSearchUrl(
 	baseUrl: string,
 	query: string,
 	options: {
-		count: number;
 		pageno: number;
 		language: string;
 		safesearch: string;
@@ -215,14 +230,12 @@ function buildSearchUrl(
 		engines: string;
 	},
 ): string {
-	const normalized = baseUrl.replace(/\/+$/, "");
+	const normalized = normalizeBaseUrl(baseUrl);
 	const params = new URLSearchParams({
 		format: "json",
 		q: query,
 	});
 
-	params.set("limit", String(options.count));
-
 	if (options.language) params.set("language", options.language);
 	if (options.safesearch) params.set("safesearch", options.safesearch);
 	if (options.time_range) params.set("time_range", options.time_range);
@@ -235,6 +248,14 @@ function buildSearchUrl(
 
 // ─── Tool definition ──────────────────────────────────────────────
 
+/** Uniform failure return: a text block plus tool details. */
+function fail<T extends object>(text: string, details: T) {
+	return {
+		content: [{ type: "text" as const, text }],
+		details,
+	};
+}
+
 export const webSearchTool = defineTool({
 	name: "web-search",
 	label: "Web Search",
@@ -309,8 +330,7 @@ export const webSearchTool = defineTool({
 		),
 		engines: Type.Optional(
 			Type.String({
-				description:
-					'Comma-separated upstream search engines (e.g. "google,bing")',
+				description: 'Comma-separated upstream search engines (e.g. "google,bing")',
 			}),
 		),
 	}),
@@ -331,21 +351,15 @@ export const webSearchTool = defineTool({
 		// ── Config check: graceful degradation when unconfigured ──
 		const searxngUrl = readSearxngUrl();
 		if (!searxngUrl) {
-			return {
-				content: [
-					{
-						type: "text" as const,
-						text:
-							"Web search is not configured. " +
-							"Set `searxng.url` in `~/.pi/agent/settings.json` " +
-							"or `.pi/settings.json` to your SearXNG instance URL. " +
-							"For example:\n" +
-							'  ```json\n  { "searxng": { "url": "http://localhost:8888" } }\n  ```\n' +
-							"See the pi-lean-search README for self-host vs public instance options.",
-					},
-				],
-				details: { error: true, unconfigured: true },
-			};
+			return fail(
+				"Web search is not configured. " +
+					"Set `searxng.url` in `~/.pi/agent/settings.json` " +
+					"or `.pi/settings.json` to your SearXNG instance URL. " +
+					"For example:\n" +
+					'  ```json\n  { "searxng": { "url": "http://localhost:8888" } }\n  ```\n' +
+					"See the pi-lean-search README for self-host vs public instance options.",
+				{ unconfigured: true },
+			);
 		}
 
 		// ── Timeout ──
@@ -353,7 +367,6 @@ export const webSearchTool = defineTool({
 
 		// ── Build URL ──
 		const url = buildSearchUrl(searxngUrl, query, {
-			count,
 			pageno,
 			language,
 			safesearch,
@@ -372,10 +385,7 @@ export const webSearchTool = defineTool({
 			});
 		}
 		if (_signal?.aborted) {
-			return {
-				content: [{ type: "text" as const, text: "Web search cancelled." }],
-				details: { cancelled: true },
-			};
+			return fail("Web search cancelled.", { cancelled: true });
 		}
 
 		const timeoutId = setTimeout(() => {
@@ -383,6 +393,19 @@ export const webSearchTool = defineTool({
 			controller.abort();
 		}, timeoutSeconds * 1000);
 
+		// Abort can surface in either fetch or the body read; label it correctly.
+		const abortFail = () => {
+			if (timedOut) {
+				return fail(
+					`Web search timed out after ${timeoutSeconds}s. ` +
+						`The SearXNG instance at \`${searxngUrl}\` may be slow ` +
+						"or unresponsive.",
+					{ timedOut: true, timeout: timeoutSeconds },
+				);
+			}
+			return fail("Web search was cancelled.", { cancelled: true });
+		};
+
 		try {
 			// ── Layer 1: Connection-level error handling ──
 			let response: Response;
@@ -392,67 +415,27 @@ export const webSearchTool = defineTool({
 					headers: { Accept: "application/json" },
 				});
 			} catch (connectionErr) {
-				clearTimeout(timeoutId);
 				if (
 					connectionErr instanceof DOMException &&
 					connectionErr.name === "AbortError"
 				) {
-					if (timedOut) {
-						return {
-							content: [
-								{
-									type: "text" as const,
-									text:
-										`Web search timed out after ${timeoutSeconds}s. ` +
-										`The SearXNG instance at \`${searxngUrl}\` may be slow ` +
-										"or unresponsive.",
-								},
-							],
-							details: {
-								error: true,
-								timedOut: true,
-								timeout: timeoutSeconds,
-							},
-						};
-					}
-					return {
-						content: [
-							{
-								type: "text" as const,
-								text: "Web search was cancelled.",
-							},
-						],
-						details: { cancelled: true },
-					};
+					return abortFail();
 				}
-				return {
-					content: [
-						{
-							type: "text" as const,
-							text:
-								"Web search connection failed: " +
-								(connectionErr instanceof Error
-									? connectionErr.message
-									: String(connectionErr)),
-						},
-					],
-					details: { error: true, connectionError: true },
-				};
+				return fail(
+					"Web search connection failed: " +
+						(connectionErr instanceof Error
+							? connectionErr.message
+							: String(connectionErr)),
+					{ connectionError: true },
+				);
 			}
 
-			clearTimeout(timeoutId);
-
 			// ── Layer 2: HTTP error handling ──
 			if (!response.ok) {
-				return {
-					content: [
-						{
-							type: "text" as const,
-							text: `SearXNG error: HTTP ${response.status} ${response.statusText}`,
-						},
-					],
-					details: { error: true, status: response.status },
-				};
+				return fail(
+					`SearXNG error: HTTP ${response.status} ${response.statusText}`,
+					{ status: response.status },
+				);
 			}
 
 			// ── Layer 3: JSON parse error handling ──
@@ -463,20 +446,16 @@ export const webSearchTool = defineTool({
 					? (JSON.parse(text) as SearXNGResponse)
 					: { results: [], answers: [], suggestions: [] };
 			} catch (parseErr) {
-				return {
-					content: [
-						{
-							type: "text" as const,
-							text:
-								"Web search returned unexpected response format. " +
-								"SearXNG may be misconfigured. Error: " +
-								(parseErr instanceof Error
-									? parseErr.message
-									: String(parseErr)),
-						},
-					],
-					details: { error: true, parseError: true },
-				};
+				// Abort can surface here if the body read stalls past the timeout.
+				if (parseErr instanceof DOMException && parseErr.name === "AbortError") {
+					return abortFail();
+				}
+				return fail(
+					"Web search returned unexpected response format. " +
+						"SearXNG may be misconfigured. Error: " +
+						(parseErr instanceof Error ? parseErr.message : String(parseErr)),
+					{ parseError: true },
+				);
 			}
 
 			// ── Deduplicate results by URL ──
@@ -492,8 +471,8 @@ export const webSearchTool = defineTool({
 				(a, b) => (b.score ?? 0) - (a.score ?? 0),
 			);
 
-			// Slice to requested count
-			const results = sortedResults.slice(0, Math.min(count, 100));
+			// Slice to requested count (schema caps `count` at 100, enforced by runtime validation)
+			const results = sortedResults.slice(0, count);
 
 			// Render answer blocks (before empty-results check so answers show even with zero web results)
 			const renderedAnswers = (data.answers ?? []).slice(0, 3);
@@ -551,8 +530,7 @@ export const webSearchTool = defineTool({
 
 			// Suggestions section
 			if (data.suggestions?.length) {
-				const suggestionCount = Math.min(data.suggestions.length, 3);
-				output += `Suggestions: ${data.suggestions.slice(0, suggestionCount).join(", ")}`;
+				output += `Suggestions: ${data.suggestions.slice(0, 3).join(", ")}`;
 			}
 
 			return {
@@ -573,20 +551,17 @@ export const webSearchTool = defineTool({
 				},
 			};
 		} catch (unexpectedErr) {
+			return fail(
+				"An unexpected error occurred during web search: " +
+					(unexpectedErr instanceof Error
+						? unexpectedErr.message
+						: String(unexpectedErr)),
+				{ unexpectedError: true },
+			);
+		} finally {
+			// Timer stays armed through the body read, so `timeout` bounds the
+			// whole request, not just the response headers.
 			clearTimeout(timeoutId);
-			return {
-				content: [
-					{
-						type: "text" as const,
-						text:
-							"An unexpected error occurred during web search: " +
-							(unexpectedErr instanceof Error
-								? unexpectedErr.message
-								: String(unexpectedErr)),
-					},
-				],
-				details: { error: true, unexpectedError: true },
-			};
 		}
 	},
 

package/ship-manifest.test.ts

@@ -1,12 +0,0 @@
-import { verifyShipManifest } from "./verify-ship-manifest.js";
-import { describe, expect, it } from "vitest";
-
-describe("publish manifest", () => {
-	it("`package.json` `files` array covers every production .ts module across the tree", () => {
-		expect(verifyShipManifest(import.meta.url).missing).toEqual([]);
-	});
-
-	it("every `files` entry points at something on disk — a stale entry ships nothing", () => {
-		expect(verifyShipManifest(import.meta.url).stale).toEqual([]);
-	});
-});

package/verify-ship-manifest.ts

@@ -1,10 +0,0 @@
-/**
- * Ship-manifest verification helper (thin re-export).
- *
- * Re-exports the shared {@link verifyShipManifest} from pi-lean-portal's
- * core/shared/ship-manifest.ts. Kept so `ship-manifest.test.ts` can import
- * from a local path without depending on a specific cross-package layout.
- */
-
-export type { ShipManifestResult } from "../pi-lean-portal/core/shared/ship-manifest.js";
-export { verifyShipManifest } from "../pi-lean-portal/core/shared/ship-manifest.js";