@zeldrisho/pi-web-search 0.4.2 → 0.6.0

package/CHANGELOG.md

@@ -1,60 +1,78 @@
 # Changelog
-## [0.4.2](https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.4.1...pi-web-search-v0.4.2) (2026-08-05)
 
+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).
 
-- **web-search:** Emit provider-compatible object schema for tool parameters ([fe81916](https://github.com/zeldrisho/pi-packages/commit/fe819161e9cf61be09a0d68be713b63cb318155e))
+## [Unreleased]
 
+## [0.6.0] - 2026-08-24
 
-### Documentation
+### Added
 
-- **web-search:** Document runtime enforcement of the context query limit ([347b386](https://github.com/zeldrisho/pi-packages/commit/347b386c62f33d489b6be207aff2a96f491eced0))
+- Resolve `BRAVE_SEARCH_API_KEY` from the process environment, the workspace `.env`, or the agent-global `.env`, and report only the credential source in `details.apiKeySource`
+- Add web-mode search options: `country` code filter, `safesearch` level (`off`/`moderate`/`strict`, default `moderate`), and `extraSnippets` to append Brave's additional excerpts per result; using them in context mode now fails with a clear error
 
-## [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)
+## [0.5.0] - 2026-08-20
 
+### Added
 
-### Bug fixes
+- 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`
 
-- Address pull request review feedback ([3b05033](https://github.com/zeldrisho/pi-packages/commit/3b05033003d173809134d9e2d2a53e82e45050b6))
+## [0.4.2] - 2026-08-05
 
+### Changed
 
-### Documentation
+- Document runtime enforcement of the context query limit ([347b386](https://github.com/zeldrisho/pi-packages/commit/347b386c62f33d489b6be207aff2a96f491eced0))
 
-- Clarify local package management ([f5b420e](https://github.com/zeldrisho/pi-packages/commit/f5b420eba246eb6a372a4b6a9036a060b9db623b))
+### Fixed
 
+- Emit provider-compatible object schema for tool parameters ([fe81916](https://github.com/zeldrisho/pi-packages/commit/fe819161e9cf61be09a0d68be713b63cb318155e))
 
-### Refactoring
+## [0.4.1] - 2026-08-03
 
-- Strengthen repository maintenance boundaries ([a44da67](https://github.com/zeldrisho/pi-packages/commit/a44da679b93ae6ea7ebdd77389bf84716b195e33))
+### 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))
 
+### Fixed
 
-## [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)
-
-
-### Features
+- 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.6.0...HEAD
+[0.6.0]: https://github.com/zeldrisho/pi-packages/compare/pi-web-search-v0.5.0...pi-web-search-v0.6.0
+[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

@@ -23,15 +23,17 @@ export BRAVE_SEARCH_API_KEY="your-api-key"
 pi
 ```
 
-If Pi is already running when you set the environment variable, run `/reload` in that Pi session.
+If the environment variable is not set, the tool also resolves the key from a `BRAVE_SEARCH_API_KEY=` line in the workspace `.env`, and then in the agent-global `.env` (in that order). Only where the key was found is ever reported; the value itself never appears in output or errors.
+
+If Pi is already running when you set the key, run `/reload` in that Pi session.
 
 ## 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. 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.
+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 400 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.
 
-Searches accept an optional result count of up to 20, a freshness filter (`day`, `week`, `month`, or `year`), and a language code such as `en` or `en-US`.
+Searches accept an optional result count of up to 20, a freshness filter (`day`, `week`, `month`, or `year`), and a language code such as `en` or `en-US`. Web mode additionally accepts a country code (`US`, `DE`, …), a SafeSearch level (`off`, `moderate`, or `strict`; default `moderate`), and an `extraSnippets` flag that appends Brave's additional excerpt paragraphs to each result snippet. These three options apply only to web mode; requests that use them with `mode: "context"` fail with a clear error.
 
 Identical searches are cached in byte-bounded memory for a limited time. Concurrent identical searches share one provider request; cancelling one caller does not cancel work still needed by another. In Pi's interactive UI, results use Pi's standard collapsed preview; use the configured tool-expansion shortcut (`Ctrl+O` by default) to show all visible tool output. Output sent to the agent remains bounded, and when a result is truncated, the complete output is written to a temporary file that is removed when the Pi session shuts down.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeldrisho/pi-web-search",
-  "version": "0.4.2",
+  "version": "0.6.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.83.0",
-    "@earendil-works/pi-coding-agent": "^0.83.0",
-    "@earendil-works/pi-tui": "^0.83.0",
-    "typebox": "^1.1.24",
-    "typescript": "^5.0.0",
-    "vite-plus": "0.2.5"
+    "@earendil-works/pi-ai": "^0.84.2",
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-tui": "^0.84.2",
+    "typebox": "^1.3.16",
+    "typescript": "^7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0",
+    "vite-plus": "0.3.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

package/src/brave.ts

@@ -8,18 +8,70 @@ import { normalizeText, requestJson } from "./provider";
 
 export type Provider = "brave";
 export type Freshness = "day" | "week" | "month" | "year";
+export type SafesearchMode = "off" | "moderate" | "strict";
 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;
+  extra_snippets?: 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[] };
+}
+
+/** Web-mode-only search options that the context endpoint does not support. */
+export interface WebSearchExtras {
+  country?: string;
+  safesearch?: SafesearchMode;
+  extraSnippets?: boolean;
+}
+
+/**
+ * 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;
 const BRAVE_MAX_SNIPPETS = 15;
 const BRAVE_MAX_TOKENS_PER_URL = 1_024;
 const BRAVE_MAX_SNIPPETS_PER_URL = 3;
+const BRAVE_MAX_EXTRA_SNIPPETS = 5;
 
 /**
  * Validates a search query and requested result count against the provider limits.
@@ -29,7 +81,22 @@ const BRAVE_MAX_SNIPPETS_PER_URL = 3;
  * @param mode - The search mode whose query limit applies
  * @throws If the query exceeds the mode limit or the result count is outside the allowed range
  */
-export function validateProviderRequest(query: string, count: number, mode: SearchMode): void {
+export function validateProviderRequest(
+  query: string,
+  count: number,
+  mode: SearchMode,
+  extras?: WebSearchExtras,
+): void {
+  if (
+    mode === "context" &&
+    (extras?.country !== undefined ||
+      extras?.safesearch !== undefined ||
+      extras?.extraSnippets !== undefined)
+  ) {
+    throw new Error(
+      "The country, safesearch, and extraSnippets options are only supported in web mode.",
+    );
+  }
   const maximumQueryCharacters =
     mode === "context" ? SEARCH_CONTEXT_MAX_QUERY_CHARACTERS : SEARCH_WEB_MAX_QUERY_CHARACTERS;
   if (query.length > maximumQueryCharacters) {
@@ -49,11 +116,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 +134,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);
@@ -128,6 +176,8 @@ function braveSnippetToMarkdown(value: unknown): string {
  *
  * @param query - The search query
  * @param count - The requested number of results
+ * @param apiKey - The resolved Brave subscription token (never logged or echoed)
+ * @param extras - Optional web-mode filters: country, safesearch level, extra snippets
  * @returns Normalized web search results
  */
 export async function searchBraveWeb(
@@ -136,41 +186,60 @@ export async function searchBraveWeb(
   freshness: Freshness | undefined,
   language: string | undefined,
   signal: AbortSignal | undefined,
+  apiKey: string,
+  extras: WebSearchExtras = {},
 ): Promise<SearchResult[]> {
   validateProviderRequest(query, count, "web");
   const url = new URL("https://api.search.brave.com/res/v1/web/search");
   url.searchParams.set("q", query);
   url.searchParams.set("count", String(count));
-  url.searchParams.set("safesearch", "moderate");
+  url.searchParams.set("safesearch", extras.safesearch ?? "moderate");
   url.searchParams.set("text_decorations", "false");
   if (language) url.searchParams.set("search_lang", language);
+  if (extras.country) url.searchParams.set("country", extras.country);
+  if (extras.extraSnippets) url.searchParams.set("extra_snippets", "true");
   if (freshness)
     url.searchParams.set(
       "freshness",
       { day: "pd", week: "pw", month: "pm", year: "py" }[freshness],
     );
 
-  const data = (await requestJson(
+  const data = await requestJson<BraveWebResponse>(
     url,
     {
       headers: {
         Accept: "application/json",
-        "X-Subscription-Token": process.env.BRAVE_SEARCH_API_KEY!,
+        "X-Subscription-Token": apiKey,
       },
     },
     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);
+    let snippet = normalizeText(item.description ?? "", 600);
+    if (extras.extraSnippets && item.extra_snippets?.length) {
+      const additional = item.extra_snippets
+        .slice(0, BRAVE_MAX_EXTRA_SNIPPETS)
+        .map((value) => normalizeText(value ?? "", 300))
+        .filter(Boolean);
+      if (additional.length) {
+        snippet = normalizeText([snippet, ...additional].filter(Boolean).join("\n\n"), 2000);
+      }
+    }
+    return {
+      title,
+      url: normalizeUrl(item.url ?? ""),
+      snippet,
+      quality: classifyResultQuality({ title, snippet }),
+    };
+  });
 }
 
 /**
  * Searches Brave's context API and maps grounding results to normalized search results.
  *
+ * @param apiKey - The resolved Brave subscription token (never logged or echoed)
  * @returns Search results containing normalized titles and URLs with deduplicated Markdown snippets.
  */
 export async function searchBraveContext(
@@ -179,6 +248,7 @@ export async function searchBraveContext(
   freshness: Freshness | undefined,
   language: string | undefined,
   signal: AbortSignal | undefined,
+  apiKey: string,
 ): Promise<SearchResult[]> {
   validateProviderRequest(query, count, "context");
 
@@ -198,27 +268,28 @@ export async function searchBraveContext(
       { day: "pd", week: "pw", month: "pm", year: "py" }[freshness],
     );
 
-  const data = (await requestJson(
+  const data = await requestJson<BraveContextResponse>(
     url,
     {
       headers: {
         Accept: "application/json",
-        "X-Subscription-Token": process.env.BRAVE_SEARCH_API_KEY!,
+        "X-Subscription-Token": apiKey,
       },
     },
     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/credentials.ts

@@ -0,0 +1,72 @@
+import { open } from "node:fs/promises";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+
+export type ApiKeySource = "environment" | "workspace .env" | "agent .env";
+
+export interface ResolvedApiKey {
+  key: string;
+  /** Where the key was found; only the source is ever reported, never the value. */
+  source: ApiKeySource;
+}
+
+const KEY_NAME = "BRAVE_SEARCH_API_KEY";
+const MAX_DOT_ENV_BYTES = 64 * 1024;
+
+/**
+ * Extracts the Brave API key from untrusted `.env` text.
+ *
+ * Only the extracted value is used; file contents are never echoed into
+ * errors or tool output.
+ */
+export function extractKeyValue(text: string): string | undefined {
+  for (const line of text.split(/\r?\n/)) {
+    const match = line.match(/^\s*BRAVE_SEARCH_API_KEY\s*=\s*(.*)$/);
+    if (!match) continue;
+    let value = match[1].trim();
+    if (
+      value.length >= 2 &&
+      ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'")))
+    ) {
+      value = value.slice(1, -1);
+    }
+    return value || undefined;
+  }
+  return undefined;
+}
+
+async function readDotEnvKey(path: string): Promise<string | undefined> {
+  let handle: Awaited<ReturnType<typeof open>> | undefined;
+  try {
+    handle = await open(path, "r");
+    const buffer = Buffer.alloc(MAX_DOT_ENV_BYTES);
+    const { bytesRead } = await handle.read(buffer, 0, MAX_DOT_ENV_BYTES, 0);
+    return extractKeyValue(buffer.toString("utf8", 0, bytesRead));
+  } catch {
+    return undefined;
+  } finally {
+    await handle?.close().catch(() => undefined);
+  }
+}
+
+/**
+ * Resolves the Brave API key without exposing its value.
+ *
+ * Resolution order: process environment, workspace `.env`, agent-global `.env`.
+ *
+ * @param cwd - The workspace directory whose `.env` is consulted second
+ * @returns The key and its source, or `undefined` when no source provides one
+ */
+export async function resolveApiKey(cwd: string): Promise<ResolvedApiKey | undefined> {
+  const fromEnvironment = process.env[KEY_NAME];
+  if (fromEnvironment) return { key: fromEnvironment, source: "environment" };
+
+  const fromWorkspace = await readDotEnvKey(join(cwd, ".env"));
+  if (fromWorkspace) return { key: fromWorkspace, source: "workspace .env" };
+
+  const fromAgent = await readDotEnvKey(join(getAgentDir(), ".env"));
+  if (fromAgent) return { key: fromAgent, source: "agent .env" };
+
+  return undefined;
+}

package/src/index.ts

@@ -5,8 +5,10 @@ import { Type } from "typebox";
 import {
   SEARCH_CONTEXT_MAX_QUERY_CHARACTERS,
   SEARCH_DEFAULT_RESULT_COUNT,
+  SEARCH_MAX_COUNTRY_CHARACTERS,
   SEARCH_MAX_LANGUAGE_CHARACTERS,
   SEARCH_MAX_RESULT_COUNT,
+  SEARCH_MIN_COUNTRY_CHARACTERS,
   SEARCH_MIN_LANGUAGE_CHARACTERS,
   SEARCH_MIN_RESULT_COUNT,
   SEARCH_WEB_MAX_QUERY_CHARACTERS,
@@ -54,6 +56,25 @@ export const webSearchParameters = Type.Object({
       description: "Optional language code, such as en or en-US",
     }),
   ),
+  country: Type.Optional(
+    Type.String({
+      minLength: SEARCH_MIN_COUNTRY_CHARACTERS,
+      maxLength: SEARCH_MAX_COUNTRY_CHARACTERS,
+      description:
+        "Optional country code to boost or restrict results, such as US, DE, or CH (web mode only)",
+    }),
+  ),
+  safesearch: Type.Optional(
+    StringEnum(["off", "moderate", "strict"] as const, {
+      description: "Optional SafeSearch level (web mode only; default: moderate)",
+    }),
+  ),
+  extraSnippets: Type.Optional(
+    Type.Boolean({
+      description:
+        "Request additional excerpt paragraphs per web result when Brave has them, appended to each snippet (web mode only)",
+    }),
+  ),
 });
 
 export default function (pi: ExtensionAPI) {
@@ -81,8 +102,8 @@ export default function (pi: ExtensionAPI) {
       );
     },
 
-    async execute(_toolCallId, params, signal, onUpdate) {
-      return runtime.execute(params, signal, onUpdate);
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      return runtime.execute(params, signal, onUpdate, ctx?.cwd);
     },
 
     renderResult(result, { expanded, isPartial }, theme) {

package/src/limits.ts

@@ -2,6 +2,8 @@ export const SEARCH_DEFAULT_RESULT_COUNT = 5;
 export const SEARCH_MIN_RESULT_COUNT = 1;
 export const SEARCH_MAX_RESULT_COUNT = 20;
 export const SEARCH_CONTEXT_MAX_QUERY_CHARACTERS = 400;
-export const SEARCH_WEB_MAX_QUERY_CHARACTERS = 500;
+export const SEARCH_WEB_MAX_QUERY_CHARACTERS = 400;
 export const SEARCH_MIN_LANGUAGE_CHARACTERS = 2;
 export const SEARCH_MAX_LANGUAGE_CHARACTERS = 20;
+export const SEARCH_MIN_COUNTRY_CHARACTERS = 2;
+export const SEARCH_MAX_COUNTRY_CHARACTERS = 2;

package/src/provider.ts

@@ -2,15 +2,7 @@ const REQUEST_TIMEOUT_MS = 20_000;
 const SEARCH_MAX_RESPONSE_BYTES = 2_000_000;
 const SEARCH_ERROR_EXCERPT_BYTES = 8_192;
 
-export function configuredProvider(): "brave" {
-  if (!process.env.BRAVE_SEARCH_API_KEY) {
-    throw new Error("BRAVE_SEARCH_API_KEY is required for web search. Set it, then run /reload.");
-  }
-  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 +64,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 +92,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,
@@ -14,27 +14,48 @@ import {
   validateProviderRequest,
   type Freshness,
   type Provider,
+  type SafesearchMode,
   type SearchMode,
   type SearchResult,
 } from "./brave";
-import { ExpiringLruCache } from "./cache";
+import { ExpiringLruCache, stableKeyHash, type CachePersistence } from "./cache";
+import { resolveApiKey, type ApiKeySource } from "./credentials";
 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;
   freshness?: Freshness;
   mode?: SearchMode;
   language?: string;
+  country?: string;
+  safesearch?: SafesearchMode;
+  extraSnippets?: boolean;
 }
 
 export interface SearchTruncationDetails {
@@ -53,7 +74,10 @@ export interface SearchDetails {
   mode: SearchMode;
   resultCount: number;
   results: SearchResult[];
+  evidence: SearchEvidence;
   cached: boolean;
+  /** Where the Brave API key was found; the key value itself is never reported. */
+  apiKeySource: ApiKeySource;
   truncated: boolean;
   fullOutputPath?: string;
   truncation: SearchTruncationDetails;
@@ -64,10 +88,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);
 
@@ -86,14 +120,26 @@ export class SearchRuntime {
     params: SearchParameters,
     signal: AbortSignal | undefined,
     onUpdate: ((update: SearchUpdate) => void) | undefined,
+    cwd: string = process.cwd(),
   ) {
     const query = params.query.trim();
     if (!query) throw new Error("Search query cannot be empty.");
 
     const count = params.count ?? SEARCH_DEFAULT_RESULT_COUNT;
     const mode = params.mode ?? "web";
-    validateProviderRequest(query, count, mode);
-    const provider = configuredProvider();
+    const extras = {
+      country: params.country,
+      safesearch: params.safesearch,
+      extraSnippets: params.extraSnippets,
+    };
+    validateProviderRequest(query, count, mode, extras);
+    const credentials = await resolveApiKey(cwd);
+    if (!credentials) {
+      throw new Error(
+        "BRAVE_SEARCH_API_KEY is required for web search. Set it in the environment, the workspace .env, or the agent .env, then run /reload.",
+      );
+    }
+    const provider: Provider = "brave";
     const cacheKey = JSON.stringify({
       provider,
       mode,
@@ -101,6 +147,10 @@ export class SearchRuntime {
       count,
       freshness: params.freshness,
       language: params.language,
+      country: params.country,
+      safesearch: params.safesearch,
+      extraSnippets: params.extraSnippets,
+      cwd,
     });
     const cachedEntry = searchCache.get(cacheKey);
     const cached = cachedEntry !== undefined;
@@ -129,8 +179,17 @@ export class SearchRuntime {
                   params.freshness,
                   params.language,
                   sharedSignal,
+                  credentials.key,
                 )
-              : await searchBraveWeb(query, count, params.freshness, params.language, sharedSignal);
+              : await searchBraveWeb(
+                  query,
+                  count,
+                  params.freshness,
+                  params.language,
+                  sharedSignal,
+                  credentials.key,
+                  extras,
+                );
           const bounded = found.filter((result) => result.url).slice(0, count);
           searchCache.set(cacheKey, bounded, Date.now() + CACHE_TTL_MS);
           return bounded;
@@ -145,6 +204,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,7 +238,9 @@ export class SearchRuntime {
         mode,
         resultCount: results.length,
         results,
+        evidence,
         cached,
+        apiKeySource: credentials.source,
         truncated: truncation.truncated,
         fullOutputPath,
         truncation: {