@zeldrisho/pi-web-search 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-08-24
+
+### Added
+
+- 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.5.0] - 2026-08-20
 
 ### Added
@@ -60,7 +67,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - 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
+[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

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.5.0",
+  "version": "0.6.0",
   "description": "Pi extension for bounded Brave web search and LLM context retrieval",
   "keywords": [
     "brave-search",
@@ -32,13 +32,13 @@
     "access": "public"
   },
   "devDependencies": {
-    "@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": "^7.0.0",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.9",
-    "vite-plus": "0.2.9"
+    "@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,6 +8,7 @@ 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";
@@ -24,6 +25,7 @@ interface BraveWebResult {
   title?: string;
   url?: string;
   description?: string;
+  extra_snippets?: string[];
 }
 
 interface BraveWebResponse {
@@ -45,6 +47,13 @@ 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.
  *
@@ -62,6 +71,7 @@ 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.
@@ -71,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) {
@@ -151,6 +176,8 @@ function braveSnippetToMarkdown(value: string): 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(
@@ -159,14 +186,18 @@ 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",
@@ -178,7 +209,7 @@ export async function searchBraveWeb(
     {
       headers: {
         Accept: "application/json",
-        "X-Subscription-Token": process.env.BRAVE_SEARCH_API_KEY!,
+        "X-Subscription-Token": apiKey,
       },
     },
     signal,
@@ -186,7 +217,16 @@ export async function searchBraveWeb(
 
   return (data.web?.results ?? []).map((item) => {
     const title = normalizeText(item.title ?? "", 300);
-    const snippet = normalizeText(item.description ?? "", 600);
+    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 ?? ""),
@@ -199,6 +239,7 @@ export async function searchBraveWeb(
 /**
  * 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(
@@ -207,6 +248,7 @@ export async function searchBraveContext(
   freshness: Freshness | undefined,
   language: string | undefined,
   signal: AbortSignal | undefined,
+  apiKey: string,
 ): Promise<SearchResult[]> {
   validateProviderRequest(query, count, "context");
 
@@ -231,7 +273,7 @@ export async function searchBraveContext(
     {
       headers: {
         Accept: "application/json",
-        "X-Subscription-Token": process.env.BRAVE_SEARCH_API_KEY!,
+        "X-Subscription-Token": apiKey,
       },
     },
     signal,

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,13 +2,6 @@ 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: string, maxLength: number): string {
   const text = value
     .replace(/<[^>]*>/g, " ")

package/src/search.ts

@@ -14,14 +14,15 @@ import {
   validateProviderRequest,
   type Freshness,
   type Provider,
+  type SafesearchMode,
   type SearchMode,
   type SearchResult,
 } from "./brave";
 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 = 24 * 60 * 60 * 1_000;
 const CACHE_MAX_ENTRIES = 100;
@@ -52,6 +53,9 @@ export interface SearchParameters {
   freshness?: Freshness;
   mode?: SearchMode;
   language?: string;
+  country?: string;
+  safesearch?: SafesearchMode;
+  extraSnippets?: boolean;
 }
 
 export interface SearchTruncationDetails {
@@ -72,6 +76,8 @@ export interface SearchDetails {
   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;
@@ -114,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,
@@ -129,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;
@@ -157,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;
@@ -209,6 +240,7 @@ export class SearchRuntime {
         results,
         evidence,
         cached,
+        apiKeySource: credentials.source,
         truncated: truncation.truncated,
         fullOutputPath,
         truncation: {