@tuan_son.dinh/gsd 2.6.0

package/src/resources/extensions/search-the-web/http.ts

@@ -0,0 +1,238 @@
+/**
+ * HTTP utilities: retry with backoff, abort signal merging, error types, timing.
+ */
+
+// =============================================================================
+// Error Types
+// =============================================================================
+
+/** Structured error for non-2xx HTTP responses. */
+export class HttpError extends Error {
+  readonly statusCode: number;
+  readonly response?: Response;
+
+  constructor(message: string, statusCode: number, response?: Response) {
+    super(message);
+    this.name = "HttpError";
+    this.statusCode = statusCode;
+    this.response = response;
+    Object.setPrototypeOf(this, HttpError.prototype);
+  }
+}
+
+/** Categorized error types for agent-friendly error handling. */
+export type SearchErrorKind =
+  | "auth_error"       // 401/403 — bad or missing API key
+  | "rate_limited"     // 429 — too many requests
+  | "network_error"    // DNS, timeout, connection refused
+  | "server_error"     // 5xx
+  | "invalid_request"  // 400, bad params
+  | "not_found"        // 404
+  | "unknown";
+
+export function classifyError(err: unknown): { kind: SearchErrorKind; message: string; retryAfterMs?: number } {
+  if (err instanceof HttpError) {
+    const code = err.statusCode;
+    if (code === 401 || code === 403) {
+      return { kind: "auth_error", message: `HTTP ${code}: Invalid or missing API key. Check your API key with secure_env_collect.` };
+    }
+    if (code === 429) {
+      let retryAfterMs: number | undefined;
+      const retryAfter = err.response?.headers.get("Retry-After");
+      if (retryAfter) {
+        const seconds = parseFloat(retryAfter);
+        if (!isNaN(seconds)) retryAfterMs = seconds * 1000;
+      }
+      return { kind: "rate_limited", message: `Rate limited (HTTP 429). ${retryAfterMs ? `Retry after ${Math.ceil(retryAfterMs / 1000)}s.` : "Wait before retrying."}`, retryAfterMs };
+    }
+    if (code === 400) {
+      return { kind: "invalid_request", message: `Bad request (HTTP 400): ${err.message}` };
+    }
+    if (code === 404) return { kind: "not_found", message: `Not found (HTTP 404)` };
+    if (code >= 500) return { kind: "server_error", message: `Server error (HTTP ${code}): ${err.message}` };
+    return { kind: "unknown", message: `HTTP ${code}: ${err.message}` };
+  }
+  if (err instanceof TypeError) {
+    return { kind: "network_error", message: `Network error: ${(err as Error).message}` };
+  }
+  const msg = (err as Error)?.message ?? String(err);
+  if (msg.includes("abort") || msg.includes("timeout")) {
+    return { kind: "network_error", message: `Request timed out` };
+  }
+  return { kind: "unknown", message: msg };
+}
+
+// =============================================================================
+// Rate Limit Info
+// =============================================================================
+
+export interface RateLimitInfo {
+  remaining?: number;
+  limit?: number;
+  reset?: number; // epoch seconds
+}
+
+/** Extract rate limit headers from a Brave API response. */
+export function extractRateLimitInfo(response: Response): RateLimitInfo | undefined {
+  const remaining = response.headers.get("x-ratelimit-remaining");
+  const limit = response.headers.get("x-ratelimit-limit");
+  const reset = response.headers.get("x-ratelimit-reset");
+  if (!remaining && !limit) return undefined;
+  return {
+    remaining: remaining ? parseInt(remaining, 10) : undefined,
+    limit: limit ? parseInt(limit, 10) : undefined,
+    reset: reset ? parseInt(reset, 10) : undefined,
+  };
+}
+
+// =============================================================================
+// Timing
+// =============================================================================
+
+export interface TimedResponse {
+  response: Response;
+  latencyMs: number;
+  rateLimit?: RateLimitInfo;
+}
+
+// =============================================================================
+// Retry Logic
+// =============================================================================
+
+function isRetryable(error: unknown): boolean {
+  if (error instanceof HttpError) {
+    return error.statusCode === 429 || error.statusCode >= 500;
+  }
+  if (error instanceof TypeError) return true;
+  return false;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Merge multiple AbortSignals — aborts as soon as any fires. */
+export function anySignal(signals: AbortSignal[]): AbortSignal {
+  const controller = new AbortController();
+  for (const sig of signals) {
+    if (sig.aborted) {
+      controller.abort(sig.reason);
+      break;
+    }
+    sig.addEventListener("abort", () => controller.abort(sig.reason), { once: true });
+  }
+  return controller.signal;
+}
+
+/**
+ * Fetch with automatic retry and full-jitter exponential backoff.
+ *
+ * - maxRetries: additional attempts after the first (total = maxRetries + 1)
+ * - Respects Retry-After header on 429 responses
+ * - Each attempt uses a 30-second AbortSignal timeout
+ * - Non-retryable errors thrown immediately
+ */
+export async function fetchWithRetry(
+  url: string,
+  options: RequestInit,
+  maxRetries: number = 2
+): Promise<Response> {
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const timeoutController = new AbortController();
+    const timeoutId = setTimeout(() => timeoutController.abort(), 30_000);
+
+    const callerSignal = options.signal as AbortSignal | undefined;
+    const signal = callerSignal
+      ? anySignal([callerSignal, timeoutController.signal])
+      : timeoutController.signal;
+
+    try {
+      const response = await fetch(url, { ...options, signal });
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        throw new HttpError(
+          `HTTP ${response.status}: ${response.statusText}`,
+          response.status,
+          response
+        );
+      }
+      return response;
+    } catch (err) {
+      clearTimeout(timeoutId);
+      lastError = err;
+
+      if (!isRetryable(err)) throw err;
+
+      if (attempt < maxRetries) {
+        let delayMs: number;
+        if (err instanceof HttpError && err.statusCode === 429 && err.response) {
+          const retryAfter = err.response.headers.get("Retry-After");
+          if (retryAfter) {
+            const seconds = parseFloat(retryAfter);
+            delayMs = isNaN(seconds) ? 1000 : seconds * 1000;
+          } else {
+            delayMs = Math.random() * Math.min(32_000, 1_000 * 2 ** attempt);
+          }
+        } else {
+          delayMs = Math.random() * Math.min(32_000, 1_000 * 2 ** attempt);
+        }
+        await sleep(delayMs);
+      }
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * Simple fetch with timeout, no retry. For content extraction where
+ * we want to fail fast.
+ */
+export async function fetchSimple(
+  url: string,
+  options: RequestInit & { timeoutMs?: number } = {}
+): Promise<Response> {
+  const { timeoutMs = 15_000, ...fetchOpts } = options;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  const callerSignal = fetchOpts.signal as AbortSignal | undefined;
+  const signal = callerSignal
+    ? anySignal([callerSignal, controller.signal])
+    : controller.signal;
+
+  try {
+    const response = await fetch(url, { ...fetchOpts, signal });
+    clearTimeout(timeoutId);
+    if (!response.ok) {
+      throw new HttpError(
+        `HTTP ${response.status}: ${response.statusText}`,
+        response.status,
+        response
+      );
+    }
+    return response;
+  } catch (err) {
+    clearTimeout(timeoutId);
+    throw err;
+  }
+}
+
+/**
+ * Fetch with retry AND timing/rate-limit extraction.
+ * Wraps fetchWithRetry and returns latency + rate limit info.
+ */
+export async function fetchWithRetryTimed(
+  url: string,
+  options: RequestInit,
+  maxRetries: number = 2
+): Promise<TimedResponse> {
+  const start = performance.now();
+  const response = await fetchWithRetry(url, options, maxRetries);
+  const latencyMs = Math.round(performance.now() - start);
+  const rateLimit = extractRateLimitInfo(response);
+  return { response, latencyMs, rateLimit };
+}

package/src/resources/extensions/search-the-web/index.ts

@@ -0,0 +1,65 @@
+/**
+ * Web Search Extension v4
+ *
+ * Provides three tools for grounding the agent in real-world web content:
+ *
+ *   search-the-web   — Rich web search with extra snippets, freshness filtering,
+ *                      domain scoping, AI summarizer, and compact output format.
+ *                      Returns links and snippets for selective browsing.
+ *
+ *   fetch_page       — Extract clean markdown from any URL via Jina Reader.
+ *                      Supports offset-based continuation, CSS selector targeting,
+ *                      and content-type-aware extraction.
+ *
+ *   search_and_read  — Single-call search + content extraction via Brave LLM Context API.
+ *                      Returns pre-extracted, relevance-scored page content.
+ *                      Best when you need content, not just links.
+ *
+ * v4: Native Anthropic web search
+ * - When using an Anthropic provider, injects the native `web_search_20250305`
+ *   server-side tool via `before_provider_request`. This eliminates the need for
+ *   a BRAVE_API_KEY when using Anthropic models — search is billed through the
+ *   existing Anthropic API key ($0.01/search).
+ * - Custom Brave-based tools (search-the-web, search_and_read) are disabled when
+ *   Anthropic + no BRAVE_API_KEY to avoid confusing the LLM with broken tools.
+ * - fetch_page (Jina) remains available — it works without a key at lower rate limits.
+ *
+ * v3 improvements over v2:
+ * - search_and_read: New tool — Brave LLM Context API (search + read in one call)
+ * - Structured error taxonomy: auth_error, rate_limited, network_error, etc.
+ * - Spellcheck surfacing: query corrections from Brave shown to agent
+ * - Latency tracking: API call timing in details for observability
+ * - Rate limit info: remaining quota surfaced when available
+ * - more_results_available: pagination hints from Brave
+ * - Adaptive snippet budget: snippet count adapts to result count
+ * - fetch_page offset: continuation reading for long pages
+ * - fetch_page selector: CSS selector targeting via Jina X-Target-Selector
+ * - fetch_page diagnostics: Jina failure reasons surfaced in details
+ * - Content-type awareness: JSON passthrough, PDF detection
+ * - Cache timer cleanup: purge timers use unref() to not block process exit
+ *
+ * Environment variables:
+ *   BRAVE_API_KEY  — Optional with Anthropic models (built-in search available).
+ *                    Required for non-Anthropic providers. Get one at brave.com/search/api
+ *   JINA_API_KEY   — Optional. Higher rate limits for page extraction.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registerSearchTool } from "./tool-search";
+import { registerFetchPageTool } from "./tool-fetch-page";
+import { registerLLMContextTool } from "./tool-llm-context";
+import { registerSearchProviderCommand } from "./command-search-provider.ts";
+import { registerNativeSearchHooks } from "./native-search";
+
+export default function (pi: ExtensionAPI) {
+  registerSearchTool(pi);
+  registerFetchPageTool(pi);
+  registerLLMContextTool(pi);
+
+
+  // Register slash commands
+  registerSearchProviderCommand(pi);
+
+  // Register native Anthropic web search hooks
+  registerNativeSearchHooks(pi);
+}

package/src/resources/extensions/search-the-web/native-search.ts

@@ -0,0 +1,157 @@
+/**
+ * Native Anthropic web search hook logic.
+ *
+ * Extracted from index.ts so it can be unit-tested without importing
+ * the heavy tool-registration modules.
+ */
+
+/** Tool names for the Brave-backed custom search tools */
+export const BRAVE_TOOL_NAMES = ["search-the-web", "search_and_read"];
+
+/** Thinking block types that require signature validation by the API */
+const THINKING_TYPES = new Set(["thinking", "redacted_thinking"]);
+
+/** Minimal interface matching the subset of ExtensionAPI we use */
+export interface NativeSearchPI {
+  on(event: string, handler: (...args: any[]) => any): void;
+  getActiveTools(): string[];
+  setActiveTools(tools: string[]): void;
+}
+
+/**
+ * Strip thinking/redacted_thinking blocks from assistant messages in the
+ * conversation history.
+ *
+ * Why: The Pi SDK's streaming parser drops `server_tool_use` and
+ * `web_search_tool_result` content blocks (unknown types). When the
+ * conversation is replayed, the assistant messages are incomplete — missing
+ * those blocks. The Anthropic API detects the modification and rejects the
+ * request with "thinking blocks cannot be modified."
+ *
+ * Fix: Remove thinking blocks from all assistant messages in the history.
+ * In Anthropic's Messages API, the messages array always ends with a user
+ * message, so every assistant message is from a previous turn that has been
+ * through a store/replay cycle. The model generates fresh thinking for the
+ * current turn regardless.
+ */
+export function stripThinkingFromHistory(
+  messages: Array<Record<string, unknown>>
+): void {
+  for (const msg of messages) {
+    if (msg.role !== "assistant") continue;
+
+    const content = msg.content;
+    if (!Array.isArray(content)) continue;
+
+    msg.content = content.filter(
+      (block: any) => !THINKING_TYPES.has(block?.type)
+    );
+  }
+}
+
+/**
+ * Register model_select, before_provider_request, and session_start hooks
+ * for native Anthropic web search injection.
+ *
+ * Returns the isAnthropicProvider getter for testing.
+ */
+export function registerNativeSearchHooks(pi: NativeSearchPI): { getIsAnthropic: () => boolean } {
+  let isAnthropicProvider = false;
+
+  // Track provider changes via model selection — also handles diagnostics
+  // since model_select fires AFTER session_start and knows the provider.
+  pi.on("model_select", async (event: any, ctx: any) => {
+    const wasAnthropic = isAnthropicProvider;
+    isAnthropicProvider = event.model.provider === "anthropic";
+
+    const hasBrave = !!process.env.BRAVE_API_KEY;
+
+    // When Anthropic + no Brave key: disable custom search tools (they'd fail)
+    if (isAnthropicProvider && !hasBrave) {
+      const active = pi.getActiveTools();
+      pi.setActiveTools(
+        active.filter((t: string) => !BRAVE_TOOL_NAMES.includes(t))
+      );
+    } else if (!isAnthropicProvider && wasAnthropic && !hasBrave) {
+      // Switching away from Anthropic without Brave — re-enable so the user
+      // sees the "missing key" error rather than tools silently vanishing.
+      // Only add tools not already active to avoid duplicates on repeated toggles.
+      const active = pi.getActiveTools();
+      const toAdd = BRAVE_TOOL_NAMES.filter((t) => !active.includes(t));
+      if (toAdd.length > 0) {
+        pi.setActiveTools([...active, ...toAdd]);
+      }
+    }
+
+    // Show provider-aware diagnostics on first selection or provider change
+    if (isAnthropicProvider && !wasAnthropic && event.source !== "restore") {
+      ctx.ui.notify("Native Anthropic web search active", "info");
+    } else if (!isAnthropicProvider && !hasBrave) {
+      ctx.ui.notify(
+        "Web search: Set BRAVE_API_KEY or use an Anthropic model for built-in search",
+        "warning"
+      );
+    }
+  });
+
+  // Inject native web search into Anthropic API requests
+  pi.on("before_provider_request", (event: any) => {
+    const payload = event.payload as Record<string, unknown>;
+    if (!payload) return;
+
+    // Detect Anthropic by model name prefix (works even before model_select fires)
+    const model = payload.model as string | undefined;
+    if (!model || !model.startsWith("claude")) return;
+
+    // Keep provider tracking in sync
+    isAnthropicProvider = true;
+
+    // Strip thinking blocks from history to avoid signature validation errors
+    // caused by the SDK dropping server_tool_use/web_search_tool_result blocks.
+    const messages = payload.messages as Array<Record<string, unknown>> | undefined;
+    if (Array.isArray(messages)) {
+      stripThinkingFromHistory(messages);
+    }
+
+    if (!Array.isArray(payload.tools)) payload.tools = [];
+
+    let tools = payload.tools as Array<Record<string, unknown>>;
+
+    // Don't double-inject if already present
+    if (tools.some((t) => t.type === "web_search_20250305")) return;
+
+    // When no Brave key, remove Brave-based search tool definitions from the
+    // payload so Claude doesn't see (and try to call) broken tools.
+    // This is more reliable than setActiveTools since model_select may not fire.
+    const hasBrave = !!process.env.BRAVE_API_KEY;
+    if (!hasBrave) {
+      tools = tools.filter(
+        (t) => !BRAVE_TOOL_NAMES.includes(t.name as string)
+      );
+      payload.tools = tools;
+    }
+
+    tools.push({
+      type: "web_search_20250305",
+      name: "web_search",
+    });
+
+    return payload;
+  });
+
+  // Basic startup diagnostics — provider-specific info comes from model_select
+  pi.on("session_start", async (_event: any, ctx: any) => {
+    const hasBrave = !!process.env.BRAVE_API_KEY;
+    const hasJina = !!process.env.JINA_API_KEY;
+    const hasAnswers = !!process.env.BRAVE_ANSWERS_KEY;
+
+    const parts: string[] = ["Web search v4 loaded"];
+    if (hasBrave) parts.push("Brave ✓");
+    if (hasAnswers) parts.push("Answers ✓");
+    if (hasJina) parts.push("Jina ✓");
+
+    ctx.ui.notify(parts.join(" · "), "info");
+  });
+
+  return { getIsAnthropic: () => isAnthropicProvider };
+}

package/src/resources/extensions/search-the-web/provider.ts

@@ -0,0 +1,118 @@
+/**
+ * Search provider selection and preference management.
+ *
+ * Single source of truth for which search backend (Tavily vs Brave) to use.
+ * Reads API keys from process.env at call time (not module load time) so
+ * hot-reloaded keys work. Preference is stored in auth.json under the
+ * synthetic provider key `search_provider` as { type: "api_key", key: "tavily" | "brave" | "auto" }.
+ *
+ * @see S01-RESEARCH.md for the storage decision rationale (D002).
+ */
+
+import { AuthStorage } from '@mariozechner/pi-coding-agent'
+import { homedir } from 'os'
+import { join } from 'path'
+
+// Compute authFilePath locally instead of importing from app-paths.ts,
+// because extensions are copied to ~/.gsd/agent/extensions/ at runtime
+// where the relative import '../../../app-paths.ts' doesn't resolve.
+const authFilePath = join(homedir(), '.gsd', 'agent', 'auth.json')
+
+export type SearchProvider = 'tavily' | 'brave'
+export type SearchProviderPreference = SearchProvider | 'auto'
+
+const VALID_PREFERENCES = new Set<string>(['tavily', 'brave', 'auto'])
+const PREFERENCE_KEY = 'search_provider'
+
+/** Returns the Tavily API key from the environment, or empty string if not set. */
+export function getTavilyApiKey(): string {
+  return process.env.TAVILY_API_KEY || ''
+}
+
+/** Returns the Brave API key from the environment, or empty string if not set. */
+export function getBraveApiKey(): string {
+  return process.env.BRAVE_API_KEY || ''
+}
+
+/**
+ * Read the user's search provider preference from auth.json.
+ * Returns 'auto' if no preference is stored or the stored value is invalid.
+ *
+ * @param authPath — Override auth.json path (for testing).
+ */
+export function getSearchProviderPreference(authPath?: string): SearchProviderPreference {
+  const auth = AuthStorage.create(authPath ?? authFilePath)
+  const cred = auth.get(PREFERENCE_KEY)
+  if (cred?.type === 'api_key' && typeof cred.key === 'string' && VALID_PREFERENCES.has(cred.key)) {
+    return cred.key as SearchProviderPreference
+  }
+  return 'auto'
+}
+
+/**
+ * Write the user's search provider preference to auth.json.
+ * Uses AuthStorage to go through file locking.
+ *
+ * @param pref — The preference to store.
+ * @param authPath — Override auth.json path (for testing).
+ */
+export function setSearchProviderPreference(pref: SearchProviderPreference, authPath?: string): void {
+  const auth = AuthStorage.create(authPath ?? authFilePath)
+  auth.set(PREFERENCE_KEY, { type: 'api_key', key: pref })
+}
+
+/**
+ * Resolve which search provider to use based on available API keys and user preference.
+ *
+ * Logic:
+ * 1. If an explicit override is given, use it — but only if that provider's key exists.
+ *    If the key doesn't exist, fall through to the other provider.
+ * 2. Otherwise, read the stored preference.
+ * 3. If preference is 'auto': prefer Tavily, then Brave.
+ * 4. If preference is a specific provider: use it if key exists, else fall back to the other.
+ * 5. Return null if neither key is available — explicit signal for "no provider".
+ *
+ * @param overridePreference — Optional override (e.g. from a tool parameter).
+ */
+export function resolveSearchProvider(overridePreference?: string): SearchProvider | null {
+  const tavilyKey = getTavilyApiKey()
+  const braveKey = getBraveApiKey()
+
+  const hasTavily = tavilyKey.length > 0
+  const hasBrave = braveKey.length > 0
+
+  // Determine effective preference
+  let pref: SearchProviderPreference
+  if (overridePreference && VALID_PREFERENCES.has(overridePreference)) {
+    pref = overridePreference as SearchProviderPreference
+  } else {
+    // Invalid override or no override — read stored preference
+    // If overridePreference is provided but invalid, treat as 'auto'
+    if (overridePreference !== undefined && !VALID_PREFERENCES.has(overridePreference)) {
+      pref = 'auto'
+    } else {
+      pref = getSearchProviderPreference()
+    }
+  }
+
+  // Resolve based on preference
+  if (pref === 'auto') {
+    if (hasTavily) return 'tavily'
+    if (hasBrave) return 'brave'
+    return null
+  }
+
+  if (pref === 'tavily') {
+    if (hasTavily) return 'tavily'
+    if (hasBrave) return 'brave'
+    return null
+  }
+
+  if (pref === 'brave') {
+    if (hasBrave) return 'brave'
+    if (hasTavily) return 'tavily'
+    return null
+  }
+
+  return null
+}

package/src/resources/extensions/search-the-web/tavily.ts

@@ -0,0 +1,116 @@
+/**
+ * Tavily API types and helper functions for normalizing Tavily search results
+ * into the shared SearchResultFormatted shape.
+ *
+ * Consumed by: tool-search.ts (S02), search_and_read Tavily path (S03).
+ * All exports are pure functions with no side effects.
+ */
+
+import type { SearchResultFormatted } from "./format.ts";
+
+// =============================================================================
+// Tavily API Types
+// =============================================================================
+
+/** A single result from the Tavily Search API. */
+export interface TavilyResult {
+  title: string;
+  url: string;
+  content: string;
+  score: number;
+  raw_content?: string | null;
+  published_date?: string | null;
+  favicon?: string | null;
+}
+
+/** Top-level response from POST https://api.tavily.com/search */
+export interface TavilySearchResponse {
+  query: string;
+  answer?: string | null;
+  results: TavilyResult[];
+  response_time: string | number;
+  usage?: { credits: number } | null;
+  request_id?: string | null;
+}
+
+// =============================================================================
+// Result Normalization
+// =============================================================================
+
+/**
+ * Map a single Tavily result to the shared SearchResultFormatted shape.
+ *
+ * - `content` → `description` (Tavily puts NLP summary or chunks inline)
+ * - `published_date` → `age` via publishedDateToAge()
+ * - No `extra_snippets` — Tavily's content already includes chunk data
+ */
+export function normalizeTavilyResult(r: TavilyResult): SearchResultFormatted {
+  return {
+    title: r.title || "(untitled)",
+    url: r.url,
+    description: r.content || "",
+    age: r.published_date ? publishedDateToAge(r.published_date) : undefined,
+  };
+}
+
+// =============================================================================
+// Date-to-Age Conversion
+// =============================================================================
+
+/**
+ * Convert an ISO 8601 date string to a human-readable relative age string.
+ *
+ * Examples: "3 days ago", "2 hours ago", "1 month ago", "just now"
+ * Returns undefined for unparseable dates or dates in the future.
+ */
+export function publishedDateToAge(isoDate: string): string | undefined {
+  const date = new Date(isoDate);
+  if (isNaN(date.getTime())) return undefined;
+
+  const now = Date.now();
+  const diffMs = now - date.getTime();
+
+  // Future dates — return undefined rather than negative ages
+  if (diffMs < 0) return undefined;
+
+  const seconds = Math.floor(diffMs / 1000);
+  if (seconds < 60) return "just now";
+
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes} ${minutes === 1 ? "minute" : "minutes"} ago`;
+
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours} ${hours === 1 ? "hour" : "hours"} ago`;
+
+  const days = Math.floor(hours / 24);
+  if (days < 30) return `${days} ${days === 1 ? "day" : "days"} ago`;
+
+  const months = Math.floor(days / 30);
+  if (months < 12) return `${months} ${months === 1 ? "month" : "months"} ago`;
+
+  const years = Math.floor(months / 12);
+  return `${years} ${years === 1 ? "year" : "years"} ago`;
+}
+
+// =============================================================================
+// Freshness Format Mapping
+// =============================================================================
+
+/** Brave freshness string → Tavily time_range value mapping. */
+const BRAVE_TO_TAVILY_FRESHNESS: Record<string, string> = {
+  pd: "day",
+  pw: "week",
+  pm: "month",
+  py: "year",
+};
+
+/**
+ * Convert a Brave-format freshness string (pd/pw/pm/py) to a Tavily
+ * `time_range` value (day/week/month/year).
+ *
+ * Returns null if input is null or not a recognized Brave freshness value.
+ */
+export function mapFreshnessToTavily(braveFreshness: string | null): string | null {
+  if (braveFreshness === null) return null;
+  return BRAVE_TO_TAVILY_FRESHNESS[braveFreshness] ?? null;
+}