From 8682524da3d89e88058b4d11dc96e4bd127be619 Mon Sep 17 00:00:00 2001
From: Jon Uleis <hi@jonuleis.com>
Date: Sat, 24 Jan 2026 22:28:00 -0500
Subject: [PATCH] feat(web_search): add freshness parameter for Brave time
 filtering
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds support for Brave Search API's freshness parameter to filter results
by discovery time:
- 'pd' - Past 24 hours
- 'pw' - Past week
- 'pm' - Past month
- 'py' - Past year
- 'YYYY-MM-DDtoYYYY-MM-DD' - Custom date range

Useful for cron jobs and monitoring tasks that need recent results.

Note: Perplexity provider ignores this parameter (Brave only).

---
🤖 AI-assisted: This PR was created with Claude (Opus). Lightly tested via
build script. The change follows existing patterns for optional parameters
(country, search_lang, ui_lang).
---
 src/agents/tools/web-search.ts | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/src/agents/tools/web-search.ts b/src/agents/tools/web-search.ts
index 4bb5c3ea8..b0eef9022 100644
--- a/src/agents/tools/web-search.ts
+++ b/src/agents/tools/web-search.ts
@@ -55,6 +55,12 @@ const WebSearchSchema = Type.Object({
       description: "ISO language code for UI elements.",
     }),
   ),
+  freshness: Type.Optional(
+    Type.String({
+      description:
+        "Filter results by discovery time. Values: 'pd' (past 24h), 'pw' (past week), 'pm' (past month), 'py' (past year), or date range 'YYYY-MM-DDtoYYYY-MM-DD'. Brave provider only.",
+    }),
+  ),
 });
 
 type WebSearchConfig = NonNullable<ClawdbotConfig["tools"]>["web"] extends infer Web
@@ -279,11 +285,12 @@ async function runWebSearch(params: {
   country?: string;
   search_lang?: string;
   ui_lang?: string;
+  freshness?: string;
   perplexityBaseUrl?: string;
   perplexityModel?: string;
 }): Promise<Record<string, unknown>> {
   const cacheKey = normalizeCacheKey(
-    `${params.provider}:${params.query}:${params.count}:${params.country || "default"}:${params.search_lang || "default"}:${params.ui_lang || "default"}`,
+    `${params.provider}:${params.query}:${params.count}:${params.country || "default"}:${params.search_lang || "default"}:${params.ui_lang || "default"}:${params.freshness || "default"}`,
   );
   const cached = readCache(SEARCH_CACHE, cacheKey);
   if (cached) return { ...cached.value, cached: true };
@@ -327,6 +334,9 @@ async function runWebSearch(params: {
   if (params.ui_lang) {
     url.searchParams.set("ui_lang", params.ui_lang);
   }
+  if (params.freshness) {
+    url.searchParams.set("freshness", params.freshness);
+  }
 
   const res = await fetch(url.toString(), {
     method: "GET",
@@ -399,6 +409,7 @@ export function createWebSearchTool(options?: {
       const country = readStringParam(params, "country");
       const search_lang = readStringParam(params, "search_lang");
       const ui_lang = readStringParam(params, "ui_lang");
+      const freshness = readStringParam(params, "freshness");
       const result = await runWebSearch({
         query,
         count: resolveSearchCount(count, DEFAULT_SEARCH_COUNT),
@@ -409,6 +420,7 @@ export function createWebSearchTool(options?: {
         country,
         search_lang,
         ui_lang,
+        freshness,
         perplexityBaseUrl: resolvePerplexityBaseUrl(
           perplexityConfig,
           perplexityAuth?.source,