@zeldrisho/pi-web-search 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,48 +1,70 @@
 # Changelog
-## [0.4.1](https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.4.0...pi-web-search-v0.4.1) (2026-08-03)
 
+All notable changes to this project will be documented in this file.
 
-### Bug fixes
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-- Address pull request review feedback ([3b05033](https://github.com/zeldrisho/pi-packages/commit/3b05033003d173809134d9e2d2a53e82e45050b6))
+## [Unreleased]
 
+## [0.5.0] - 2026-08-20
 
-### Documentation
+### Added
 
-- Clarify local package management ([f5b420e](https://github.com/zeldrisho/pi-packages/commit/f5b420eba246eb6a372a4b6a9036a060b9db623b))
+- Persist search results to a private cross-session disk cache (24h TTL) behind the existing in-memory cache
+- Report honest-evidence metadata (`evidence` summary and per-result `quality`) in `details`
 
+## [0.4.2] - 2026-08-05
 
-### Refactoring
+### Changed
 
-- Strengthen repository maintenance boundaries ([a44da67](https://github.com/zeldrisho/pi-packages/commit/a44da679b93ae6ea7ebdd77389bf84716b195e33))
+- Document runtime enforcement of the context query limit ([347b386](https://github.com/zeldrisho/pi-packages/commit/347b386c62f33d489b6be207aff2a96f491eced0))
 
-- Strengthen maintenance safety ([8a26436](https://github.com/zeldrisho/pi-packages/commit/8a26436780373f21535580224b59bc6dd2a4ad72))
+### Fixed
+
+- Emit provider-compatible object schema for tool parameters ([fe81916](https://github.com/zeldrisho/pi-packages/commit/fe819161e9cf61be09a0d68be713b63cb318155e))
 
+## [0.4.1] - 2026-08-03
 
-## [0.4.0](https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.3.1...pi-web-search-v0.4.0) (2026-07-25)
+### Changed
 
+- Clarify local package management ([f5b420e](https://github.com/zeldrisho/pi-packages/commit/f5b420eba246eb6a372a4b6a9036a060b9db623b))
+- Strengthen repository maintenance boundaries ([a44da67](https://github.com/zeldrisho/pi-packages/commit/a44da679b93ae6ea7ebdd77389bf84716b195e33))
+- Strengthen maintenance safety ([8a26436](https://github.com/zeldrisho/pi-packages/commit/8a26436780373f21535580224b59bc6dd2a4ad72))
 
-### Features
+### Fixed
+
+- Address pull request review feedback ([3b05033](https://github.com/zeldrisho/pi-packages/commit/3b05033003d173809134d9e2d2a53e82e45050b6))
 
-* **web-tools:** strengthen independent tool boundaries ([71aba47](https://github.com/zeldrisho/pi-packages/commit/71aba47db47483b6a75935796a1747603850aa96))
+## [0.4.0] - 2026-07-25
 
-## [0.3.1](https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.3.0...pi-web-search-v0.3.1) (2026-07-22)
+### Added
 
+- **web-tools:** strengthen independent tool boundaries ([71aba47](https://github.com/zeldrisho/pi-packages/commit/71aba47db47483b6a75935796a1747603850aa96))
 
-### Bug Fixes
+## [0.3.1] - 2026-07-22
 
-* address consolidated review feedback ([cea33a1](https://github.com/zeldrisho/pi-packages/commit/cea33a1f30783bd19231fe9dc69686c58f313785))
+### Fixed
 
-## [0.3.0](https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.2.0...pi-web-search-v0.3.0) (2026-07-20)
+- address consolidated review feedback ([cea33a1](https://github.com/zeldrisho/pi-packages/commit/cea33a1f30783bd19231fe9dc69686c58f313785))
 
+## [0.3.0] - 2026-07-20
 
-### Features
+### Added
 
-* **web:** Add collapsible web tool results ([e8664d6](https://github.com/zeldrisho/pi-packages/commit/e8664d6c07b719d92f18d9a0048b47cc1970b97c))
+- **web:** Add collapsible web tool results ([e8664d6](https://github.com/zeldrisho/pi-packages/commit/e8664d6c07b719d92f18d9a0048b47cc1970b97c))
 
-## 0.2.0 (2026-07-19)
+## [0.2.0] - 2026-07-19
 
+### Added
 
-### Features
+- Add bounded Brave web search ([cbc9491](https://github.com/zeldrisho/pi-packages/commit/cbc9491dce36555ab91b6bef203ec8b380596a89))
 
-* **web-search:** Add bounded Brave web search ([cbc9491](https://github.com/zeldrisho/pi-packages/commit/cbc9491dce36555ab91b6bef203ec8b380596a89))
+[Unreleased]: https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.5.0...HEAD
+[0.5.0]: https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.4.2...pi-web-search-v0.5.0
+[0.4.2]: https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.4.1...pi-web-search-v0.4.2
+[0.4.1]: https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.4.0...pi-web-search-v0.4.1
+[0.4.0]: https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.3.1...pi-web-search-v0.4.0
+[0.3.1]: https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.3.0...pi-web-search-v0.3.1
+[0.3.0]: https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.2.0...pi-web-search-v0.3.0
+[0.2.0]: https://github.com/zeldrisho/pi-packages/releases/tag/pi-web-search-v0.2.0

package/README.md

@@ -27,7 +27,7 @@ If Pi is already running when you set the environment variable, run `/reload` in
 
 ## Usage
 
-The `web_search` tool returns compact web results by default, making it suitable for discovering current sources and URLs. Set `mode` to `context` to call only Brave's LLM Context API and return provider-extracted snippets. Context queries are limited to 400 characters; web-mode queries are limited to 500 characters.
+The `web_search` tool returns compact web results by default, making it suitable for discovering current sources and URLs. Set `mode` to `context` to call only Brave's LLM Context API and return provider-extracted snippets. Context queries are limited to 400 characters; web-mode queries are limited to 500 characters. Because the provider rejects union schemas, the tool schema accepts up to the web-mode query length for either mode; the tighter context-mode limit is enforced at runtime when the request executes, not in the schema.
 
 Context snippets may not reflect the current live page. The tool does not fetch result URLs. When live-page inspection is needed, call `web_fetch` explicitly on the relevant URL.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeldrisho/pi-web-search",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Pi extension for bounded Brave web search and LLM context retrieval",
   "keywords": [
     "brave-search",
@@ -32,12 +32,13 @@
     "access": "public"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.80.10",
-    "@earendil-works/pi-coding-agent": "^0.80.10",
-    "@earendil-works/pi-tui": "^0.80.10",
+    "@earendil-works/pi-ai": "^0.84.0",
+    "@earendil-works/pi-coding-agent": "^0.84.0",
+    "@earendil-works/pi-tui": "^0.84.0",
     "typebox": "^1.1.24",
-    "typescript": "^5.0.0",
-    "vite-plus": "0.2.5"
+    "typescript": "^7.0.0",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.9",
+    "vite-plus": "0.2.9"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

package/src/brave.ts

@@ -10,10 +10,52 @@ export type Provider = "brave";
 export type Freshness = "day" | "week" | "month" | "year";
 export type SearchMode = "web" | "context";
 
+export type ResultQuality = "high" | "medium" | "low";
+
 export interface SearchResult {
   title: string;
   url: string;
   snippet: string;
+  /** Honest-evidence hint about how useful the result is likely to be as a citation. */
+  quality: ResultQuality;
+}
+
+interface BraveWebResult {
+  title?: string;
+  url?: string;
+  description?: string;
+}
+
+interface BraveWebResponse {
+  web?: { results?: BraveWebResult[] };
+}
+
+interface BraveSnippet {
+  caption?: string;
+  table?: Array<Record<string, string>>;
+}
+
+interface BraveContextResult {
+  title?: string;
+  url?: string;
+  snippets?: string[];
+}
+
+interface BraveContextResponse {
+  grounding?: { generic?: BraveContextResult[] };
+}
+
+/**
+ * Classifies a search result by how much usable, sourced information it carries.
+ *
+ * @param result - The result title and snippet to assess
+ * @returns A coarse quality hint for weighting citations
+ */
+export function classifyResultQuality(result: { title: string; snippet: string }): ResultQuality {
+  if (!result.title && !result.snippet) return "low";
+  if (result.snippet.length >= 80) return "high";
+  if (result.title || result.snippet) return "medium";
+  return "low";
 }
 
 const BRAVE_MAX_CONTEXT_TOKENS = 2_048;
@@ -49,11 +91,10 @@ export function validateProviderRequest(query: string, count: number, mode: Sear
 /**
  * Normalizes an HTTP or HTTPS URL and limits the result to 2,048 characters.
  *
- * @param value - The value to normalize
+ * @param value - The URL text to normalize
  * @returns The normalized URL, or an empty string for invalid values or unsupported protocols
  */
-function normalizeUrl(value: unknown): string {
-  if (typeof value !== "string") return "";
+function normalizeUrl(value: string): string {
   try {
     const url = new URL(value);
     return url.protocol === "http:" || url.protocol === "https:"
@@ -68,55 +109,37 @@ function escapeMarkdownLinkText(value: string): string {
   return value.replace(/([\\[\]])/g, "\\$1");
 }
 
-function escapeMarkdownCell(value: unknown): string {
-  let text = "";
-  if (typeof value === "string") text = value;
-  else if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
-    text = String(value);
-  } else if (value !== null && value !== undefined) {
-    try {
-      text = JSON.stringify(value) ?? "";
-    } catch {
-      text = "";
-    }
-  }
-  return text.replace(/\|/g, "\\|").replace(/\r?\n/g, "<br>");
+function escapeMarkdownCell(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, "<br>");
 }
 
-function structuredSnippetToMarkdown(value: unknown): string | undefined {
-  if (!value || typeof value !== "object") return undefined;
-  const record = value as { caption?: unknown; table?: unknown };
-  if (!Array.isArray(record.table) || record.table.length === 0) return undefined;
+function structuredSnippetToMarkdown(value: BraveSnippet): string | undefined {
+  const table = value.table;
+  if (!table || table.length === 0) return undefined;
 
-  const rows = record.table.filter(
-    (row): row is Record<string, unknown> => Boolean(row) && typeof row === "object",
-  );
+  const rows = table.filter(Boolean);
   const headers = [...new Set(rows.flatMap((row) => Object.keys(row)))];
   if (headers.length === 0) return undefined;
 
-  const caption =
-    typeof record.caption === "string" ? `**${escapeMarkdownLinkText(record.caption)}**\n\n` : "";
+  const caption = value.caption ? `**${escapeMarkdownLinkText(value.caption)}**\n\n` : "";
   const header = `| ${headers.map(escapeMarkdownCell).join(" | ")} |`;
   const separator = `| ${headers.map(() => "---").join(" | ")} |`;
   const body = rows
-    .map((row) => `| ${headers.map((key) => escapeMarkdownCell(row[key])).join(" | ")} |`)
+    .map((row) => `| ${headers.map((key) => escapeMarkdownCell(String(row[key]))).join(" | ")} |`)
     .join("\n");
   return `${caption}${header}\n${separator}\n${body}`;
 }
 
-function braveSnippetToMarkdown(value: unknown): string {
-  if (typeof value !== "string") return "";
-  const snippet = value.trim();
-  if (!snippet) return "";
-
+function braveSnippetToMarkdown(value: string): string {
   try {
-    const parsed = JSON.parse(snippet) as unknown;
-    return (
-      structuredSnippetToMarkdown(parsed) ??
-      `\`\`\`json\n${JSON.stringify(parsed, null, 2)}\n\`\`\``
-    ).slice(0, 8000);
+    const snippet = value.trim();
+    if (!snippet) return "";
+    const parsed: BraveSnippet = JSON.parse(snippet);
+    const rendered = structuredSnippetToMarkdown(parsed);
+    if (rendered !== undefined) return rendered.slice(0, 8000);
+    return `\`\`\`json\n${JSON.stringify(parsed, null, 2)}\n\`\`\``.slice(0, 8000);
   } catch {
-    return snippet
+    return String(value)
       .replace(/\r\n/g, "\n")
       .replace(/\n{4,}/g, "\n\n\n")
       .slice(0, 8000);
@@ -150,7 +173,7 @@ export async function searchBraveWeb(
       { day: "pd", week: "pw", month: "pm", year: "py" }[freshness],
     );
 
-  const data = (await requestJson(
+  const data = await requestJson<BraveWebResponse>(
     url,
     {
       headers: {
@@ -159,13 +182,18 @@ export async function searchBraveWeb(
       },
     },
     signal,
-  )) as { web?: { results?: Array<{ title?: unknown; url?: unknown; description?: unknown }> } };
+  );
 
-  return (data.web?.results ?? []).map((item) => ({
-    title: normalizeText(item.title, 300),
-    url: normalizeUrl(item.url),
-    snippet: normalizeText(item.description, 600),
-  }));
+  return (data.web?.results ?? []).map((item) => {
+    const title = normalizeText(item.title ?? "", 300);
+    const snippet = normalizeText(item.description ?? "", 600);
+    return {
+      title,
+      url: normalizeUrl(item.url ?? ""),
+      snippet,
+      quality: classifyResultQuality({ title, snippet }),
+    };
+  });
 }
 
 /**
@@ -198,7 +226,7 @@ export async function searchBraveContext(
       { day: "pd", week: "pw", month: "pm", year: "py" }[freshness],
     );
 
-  const data = (await requestJson(
+  const data = await requestJson<BraveContextResponse>(
     url,
     {
       headers: {
@@ -207,18 +235,19 @@ export async function searchBraveContext(
       },
     },
     signal,
-  )) as {
-    grounding?: { generic?: Array<{ title?: unknown; url?: unknown; snippets?: unknown[] }> };
-  };
+  );
 
   return (data.grounding?.generic ?? []).map((item) => {
     const snippets = [
       ...new Set((item.snippets ?? []).map(braveSnippetToMarkdown).filter(Boolean)),
     ];
+    const title = normalizeText(item.title ?? "", 300);
+    const snippet = snippets.slice(0, BRAVE_MAX_SNIPPETS_PER_URL).join("\n\n");
     return {
-      title: normalizeText(item.title, 300),
-      url: normalizeUrl(item.url),
-      snippet: snippets.slice(0, BRAVE_MAX_SNIPPETS_PER_URL).join("\n\n"),
+      title,
+      url: normalizeUrl(item.url ?? ""),
+      snippet,
+      quality: classifyResultQuality({ title, snippet }),
     };
   });
 }

package/src/cache.ts

@@ -1,9 +1,61 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import { createHash } from "node:crypto";
+
 interface ExpiringCacheEntry<V> {
   expiresAt: number;
   size: number;
   value: V;
 }
 
+/** A best-effort on-disk backing store for cache entries. */
+export interface CachePersistence<K, V> {
+  /** Directory that holds private cache files, created lazily with 0700 perms. */
+  readonly directory: string;
+  /** Serialize a value to bytes for on-disk storage. */
+  serialize(value: V): Uint8Array;
+  /** Deserialize bytes read from disk; throw on corrupt data so it is treated as a miss. */
+  deserialize(bytes: Uint8Array): V;
+  /** Map a logical cache key to a safe, collision-resistant on-disk filename. */
+  keyToPath(key: K): string;
+}
+
+/** Hashes a cache key into a safe, collision-resistant filename segment. */
+export function stableKeyHash(key: string): string {
+  return createHash("sha256").update(key).digest("hex");
+}
+
+/**
+ * Resolves a cache entry's on-disk path and refuses to escape the cache
+ * directory, guarding against a `keyToPath` that returns `..` segments. The
+ * `keyToPath` implementations in this repo return a hex SHA-256 digest, so this
+ * never triggers in normal operation but keeps best-effort persistence safe.
+ */
+export function resolveCachePath(directory: string, keyPath: string): string {
+  const base = resolve(directory);
+  const full = resolve(base, keyPath);
+  if (full !== base && !full.startsWith(base + sep)) {
+    throw new Error(`Refusing to write cache entry outside ${base}: ${keyPath}`);
+  }
+  return full;
+}
+
+function encodeExpiresAt(expiresAt: number): Uint8Array {
+  const out = new Uint8Array(8);
+  let value = BigInt(Math.round(expiresAt));
+  for (let index = 7; index >= 0; index -= 1) {
+    out[index] = Number(value & 0xffn);
+    value >>= 8n;
+  }
+  return out;
+}
+
+function decodeExpiresAt(bytes: Uint8Array): number {
+  let value = 0n;
+  for (let index = 0; index < 8; index += 1) value = (value << 8n) | BigInt(bytes[index]);
+  return Number(value);
+}
+
 /** An expiring least-recently-used cache bounded by entry count and aggregate bytes. */
 export class ExpiringLruCache<K, V> {
   readonly #entries = new Map<K, ExpiringCacheEntry<V>>();
@@ -14,6 +66,7 @@ export class ExpiringLruCache<K, V> {
     readonly maxBytes: number,
     readonly sizeOf: (value: V) => number,
     readonly now: () => number = Date.now,
+    readonly persistence?: CachePersistence<K, V>,
   ) {}
 
   get byteSize(): number {
@@ -26,14 +79,20 @@ export class ExpiringLruCache<K, V> {
 
   get(key: K): V | undefined {
     const entry = this.#entries.get(key);
-    if (!entry) return undefined;
-    if (entry.expiresAt <= this.now()) {
-      this.#delete(key);
-      return undefined;
+    if (entry) {
+      if (entry.expiresAt <= this.now()) {
+        this.#delete(key);
+        return undefined;
+      }
+      this.#entries.delete(key);
+      this.#entries.set(key, entry);
+      return entry.value;
     }
-    this.#entries.delete(key);
-    this.#entries.set(key, entry);
-    return entry.value;
+    if (this.persistence) {
+      const loaded = this.#loadFromDisk(key);
+      if (loaded !== undefined) return loaded.value;
+    }
+    return undefined;
   }
 
   set(key: K, value: V, expiresAt: number): boolean {
@@ -43,18 +102,82 @@ export class ExpiringLruCache<K, V> {
 
     this.#entries.set(key, { expiresAt, size, value });
     this.#byteSize += size;
+    this.#evict();
+    const stored = this.#entries.has(key);
+    if (stored && this.persistence) this.#writeToDisk(key, value, expiresAt);
+    return stored;
+  }
+
+  #loadFromDisk(key: K): ExpiringCacheEntry<V> | undefined {
+    let bytes: Uint8Array;
+    try {
+      const path = resolveCachePath(this.persistence!.directory, this.persistence!.keyToPath(key));
+      bytes = readFileSync(path);
+    } catch {
+      return undefined;
+    }
+    let entry: ExpiringCacheEntry<V>;
+    try {
+      if (bytes.byteLength < 8) throw new Error("cache file too small");
+      const expiresAt = decodeExpiresAt(bytes);
+      const value = this.persistence!.deserialize(bytes.subarray(8));
+      const size = this.sizeOf(value);
+      if (size > this.maxBytes) throw new Error("oversized cache entry");
+      entry = { expiresAt, size, value };
+    } catch {
+      this.#removeFromDisk(key);
+      return undefined;
+    }
+    if (entry.expiresAt <= this.now()) {
+      this.#removeFromDisk(key);
+      return undefined;
+    }
+    this.#entries.set(key, entry);
+    this.#byteSize += entry.size;
+    this.#evict();
+    return this.#entries.get(key);
+  }
+
+  #writeToDisk(key: K, value: V, expiresAt: number): void {
+    try {
+      const directory = this.persistence!.directory;
+      mkdirSync(directory, { recursive: true, mode: 0o700 });
+      chmodSync(directory, 0o700);
+      const payload = this.persistence!.serialize(value);
+      const path = resolveCachePath(directory, this.persistence!.keyToPath(key));
+      const temp = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+      writeFileSync(temp, Buffer.concat([encodeExpiresAt(expiresAt), payload]), { mode: 0o600 });
+      chmodSync(temp, 0o600);
+      renameSync(temp, path);
+    } catch {
+      // Best-effort persistence: a failed disk write never fails the caller.
+    }
+  }
+
+  #removeFromDisk(key: K): void {
+    try {
+      unlinkSync(resolveCachePath(this.persistence!.directory, this.persistence!.keyToPath(key)));
+    } catch {
+      // Ignore missing or undeletable files; a cache miss is the correct outcome.
+    }
+  }
+
+  #evict(): void {
     while (this.#entries.size > this.maxEntries || this.#byteSize > this.maxBytes) {
       const oldest = this.#entries.keys().next().value;
       if (oldest === undefined) break;
       this.#delete(oldest);
     }
-    return this.#entries.has(key);
   }
 
   #delete(key: K): void {
     const entry = this.#entries.get(key);
-    if (!entry) return;
+    if (!entry) {
+      if (this.persistence) this.#removeFromDisk(key);
+      return;
+    }
     this.#entries.delete(key);
     this.#byteSize -= entry.size;
+    if (this.persistence) this.#removeFromDisk(key);
   }
 }

package/src/index.ts

@@ -22,7 +22,19 @@ export {
   type SearchTruncationDetails,
 } from "./search";
 
-const commonSearchParameters = Type.Object({
+export const webSearchParameters = Type.Object({
+  query: Type.String({
+    minLength: 1,
+    maxLength: SEARCH_WEB_MAX_QUERY_CHARACTERS,
+    description: `The search query (maximum ${SEARCH_WEB_MAX_QUERY_CHARACTERS} characters; context mode limited to ${SEARCH_CONTEXT_MAX_QUERY_CHARACTERS})`,
+  }),
+  mode: Type.Optional(
+    StringEnum(["web", "context"] as const, {
+      description:
+        "Search mode: compact Brave web results (default) or Brave LLM context extraction",
+      default: "web",
+    }),
+  ),
   count: Type.Optional(
     Type.Integer({
       minimum: SEARCH_MIN_RESULT_COUNT,
@@ -44,32 +56,6 @@ const commonSearchParameters = Type.Object({
   ),
 });
 
-export const webSearchParameters = Type.Intersect([
-  commonSearchParameters,
-  Type.Union([
-    Type.Object({
-      query: Type.String({
-        minLength: 1,
-        maxLength: SEARCH_CONTEXT_MAX_QUERY_CHARACTERS,
-        description: `The Brave LLM Context query (maximum ${SEARCH_CONTEXT_MAX_QUERY_CHARACTERS} characters)`,
-      }),
-      mode: Type.Literal("context", {
-        description: "Return provider-extracted Brave LLM context",
-      }),
-    }),
-    Type.Object({
-      query: Type.String({
-        minLength: 1,
-        maxLength: SEARCH_WEB_MAX_QUERY_CHARACTERS,
-        description: `The web search query (maximum ${SEARCH_WEB_MAX_QUERY_CHARACTERS} characters)`,
-      }),
-      mode: Type.Optional(
-        Type.Literal("web", { description: "Return compact Brave web results (default)" }),
-      ),
-    }),
-  ]),
-]);
-
 export default function (pi: ExtensionAPI) {
   const runtime = new SearchRuntime();
   pi.on("session_shutdown", () => runtime.shutdown());

package/src/provider.ts

@@ -9,8 +9,7 @@ export function configuredProvider(): "brave" {
   return "brave";
 }
 
-export function normalizeText(value: unknown, maxLength: number): string {
-  if (typeof value !== "string") return "";
+export function normalizeText(value: string, maxLength: number): string {
   const text = value
     .replace(/<[^>]*>/g, " ")
     .replace(/\s+/g, " ")
@@ -72,11 +71,11 @@ async function readResponseText(
   return new TextDecoder().decode(await readResponseBytes(response, maxBytes, truncate));
 }
 
-export async function requestJson(
+export async function requestJson<T>(
   url: string | URL,
   init: RequestInit,
   signal: AbortSignal | undefined,
-): Promise<unknown> {
+): Promise<T> {
   const controller = new AbortController();
   let timedOut = false;
   const timeout = setTimeout(() => {
@@ -100,7 +99,8 @@ export async function requestJson(
       }
       throw new Error(`Search provider returned HTTP ${response.status}${body ? `: ${body}` : ""}`);
     }
-    return JSON.parse(await readResponseText(response, SEARCH_MAX_RESPONSE_BYTES)) as unknown;
+    // SAFETY: the caller supplies the expected response shape T; JSON.parse yields the decoded document.
+    return JSON.parse(await readResponseText(response, SEARCH_MAX_RESPONSE_BYTES)) as T;
   } catch (error) {
     if (timedOut)
       throw new Error(`Web search timed out after ${REQUEST_TIMEOUT_MS / 1000} seconds.`);

package/src/search.ts

@@ -1,5 +1,5 @@
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   DEFAULT_MAX_BYTES,
@@ -17,18 +17,35 @@ import {
   type SearchMode,
   type SearchResult,
 } from "./brave";
-import { ExpiringLruCache } from "./cache";
+import { ExpiringLruCache, stableKeyHash, type CachePersistence } from "./cache";
 import { formatResults } from "./format-results";
 import { InflightCoalescer } from "./inflight";
 import { SEARCH_DEFAULT_RESULT_COUNT } from "./limits";
 import { configuredProvider } from "./provider";
 
-const CACHE_TTL_MS = 10 * 60 * 1_000;
+const CACHE_TTL_MS = 24 * 60 * 60 * 1_000;
 const CACHE_MAX_ENTRIES = 100;
 const CACHE_MAX_RESULT_BYTES = 20 * 1_024 * 1_024;
 const MAX_INFLIGHT_REQUESTS = 100;
 const encoder = new TextEncoder();
 
+/** Honest-evidence summary comparing what was requested with what was returned. */
+export interface SearchEvidence {
+  requestedCount: number;
+  returnedCount: number;
+  dropped: number;
+  freshness?: Freshness;
+  truncated: boolean;
+}
+
+/** Resolves the private, cross-session cache directory for a web tool. */
+function resolveCacheDirectory(name: string): string {
+  const base = process.env.XDG_CACHE_HOME
+    ? join(process.env.XDG_CACHE_HOME, name)
+    : join(homedir(), ".cache", name);
+  return base;
+}
+
 export interface SearchParameters {
   query: string;
   count?: number;
@@ -53,6 +70,7 @@ export interface SearchDetails {
   mode: SearchMode;
   resultCount: number;
   results: SearchResult[];
+  evidence: SearchEvidence;
   cached: boolean;
   truncated: boolean;
   fullOutputPath?: string;
@@ -64,10 +82,20 @@ interface SearchUpdate {
   details: Record<string, never>;
 }
 
+const searchCachePersistence: CachePersistence<string, SearchResult[]> = {
+  directory: resolveCacheDirectory("pi-web-search"),
+  serialize: (results) => encoder.encode(JSON.stringify(results)),
+  // SAFETY: cache entries are written by this same serializer, so the decoded
+  // JSON always matches the SearchResult[] shape.
+  deserialize: (bytes) => JSON.parse(new TextDecoder().decode(bytes)) as SearchResult[],
+  keyToPath: (key) => stableKeyHash(key),
+};
 const searchCache = new ExpiringLruCache<string, SearchResult[]>(
   CACHE_MAX_ENTRIES,
   CACHE_MAX_RESULT_BYTES,
   (results) => encoder.encode(JSON.stringify(results)).byteLength,
+  undefined,
+  searchCachePersistence,
 );
 const inflightSearches = new InflightCoalescer<string, SearchResult[]>(MAX_INFLIGHT_REQUESTS);
 
@@ -145,6 +173,13 @@ export class SearchRuntime {
       maxLines: DEFAULT_MAX_LINES,
       maxBytes: DEFAULT_MAX_BYTES,
     });
+    const evidence: SearchEvidence = {
+      requestedCount: count,
+      returnedCount: results.length,
+      dropped: Math.max(0, results.length - count),
+      freshness: params.freshness,
+      truncated: truncation.truncated,
+    };
     let text = truncation.content;
     let fullOutputPath: string | undefined;
 
@@ -172,6 +207,7 @@ export class SearchRuntime {
         mode,
         resultCount: results.length,
         results,
+        evidence,
         cached,
         truncated: truncation.truncated,
         fullOutputPath,