@triplef/agent 0.1.0

package/dist/tools/index.mjs

@@ -0,0 +1,1637 @@
+import { z } from 'zod';
+import { tool } from 'ai';
+import { Readability } from '@mozilla/readability';
+import { parseHTML } from 'linkedom';
+import TurndownService from 'turndown';
+
+// src/tools/bright-data/bright-data.constants.ts
+var SOURCE = "brightData";
+function buildGoogleUrl(query, params) {
+  const search = new URLSearchParams();
+  search.set("q", query);
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null || value === "") continue;
+    search.set(key, String(value));
+  }
+  search.set("brd_json", "1");
+  return `https://www.google.com/search?${search.toString()}`;
+}
+function engineEnabled(deps, endpoint) {
+  const cfg = deps.getLiveConfig().brightData;
+  if (!cfg.enabled || !cfg.apiKey || !cfg.serpZone) return void 0;
+  const ep = cfg[endpoint];
+  if (typeof ep === "object" && ep !== null && "enabled" in ep && !ep.enabled) return void 0;
+  return cfg.apiKey;
+}
+
+// src/tools/constants/search-timeout.ts
+var SEARCH_TIMEOUT_MS = 1e4;
+var BRIGHT_DATA_TIMEOUT_MS = 3e4;
+var SEARCH_RETRIES = 1;
+
+// src/tools/helpers/fetch-with-timeout.ts
+async function fetchWithTimeout(url, init, options = {}) {
+  const timeoutMs = options.timeoutMs ?? SEARCH_TIMEOUT_MS;
+  const retries = options.retries ?? SEARCH_RETRIES;
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      const res = await fetch(url, {
+        ...init,
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      return res;
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      const isTransient = lastError.name === "AbortError" || lastError.name === "TimeoutError" || lastError.message.toLowerCase().includes("the operation was aborted due to timeout") || lastError.message.toLowerCase().includes("fetch failed");
+      if (!isTransient) throw lastError;
+    }
+  }
+  throw lastError ?? new Error(`Failed to fetch ${url}`);
+}
+
+// src/tools/bright-data/bright-data-client.ts
+var BRIGHT_DATA_ENDPOINT = "https://api.brightdata.com/request";
+async function requestBrightData(apiKey, zone, url, opts) {
+  const res = await fetchWithTimeout(
+    BRIGHT_DATA_ENDPOINT,
+    {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        zone,
+        url,
+        format: "raw",
+        ...opts.markdown ? { data_format: "markdown" } : {}
+      })
+    },
+    { timeoutMs: opts.timeoutMs }
+  );
+  if (!res.ok) throw new Error(`Bright Data returned HTTP ${res.status}`);
+  if (opts.markdown) return { text: await res.text() };
+  return res.json();
+}
+
+// src/tools/constants/recency.constants.ts
+var RECENCY_DESCRIPTION = "Restrict results to the given past period (day=24 hours, week=7 days, month=1 month, year=1 year). Use for fresh content such as news, recent releases, or trending topics; leave unset for evergreen, historical, or general queries.";
+
+// src/tools/constants/standalone-query.constants.ts
+var STANDALONE_QUERY_DESCRIPTION = 'A standalone, self-contained search query that explicitly names the subject (title, entity, brand, person, place, or topic). Never copy the user message verbatim: rewrite short follow-ups (e.g. "what do the reviews say?") into a full query that names the established subject from the conversation (e.g. "Neverness to Everness NTE reviews").';
+var STANDALONE_QUERY_TOOL_CLAUSE = "Always pass a standalone query that names the subject explicitly \u2014 never the user message verbatim.";
+
+// src/tools/bright-data/image-search.schema.ts
+var brightDataImageSearchSchema = z.object({
+  query: z.string().describe(`${STANDALONE_QUERY_DESCRIPTION} Add short visual qualifiers describing the subject.`),
+  count: z.number().optional().describe("Number of results (max 100)"),
+  minWidth: z.number().optional().describe("Minimum image width in pixels (floor 1280 / 720p)."),
+  minHeight: z.number().optional().describe("Minimum image height in pixels (floor 720 / 720p)."),
+  lang: z.string().optional().describe("Two-letter ISO language code for result preference (e.g. en, de, ja)"),
+  recency: z.enum(["day", "week", "month", "year"]).optional().describe(RECENCY_DESCRIPTION)
+});
+
+// src/schemas/constants/blocked-image-hosts.ts
+var BLOCKED_IMAGE_HOSTS = /* @__PURE__ */ new Set([
+  // Google thumbnail proxies (low-res, frequently 404 when hot-linked)
+  "encrypted-tbn0.gstatic.com",
+  "encrypted-tbn1.gstatic.com",
+  "encrypted-tbn2.gstatic.com",
+  "encrypted-tbn3.gstatic.com",
+  "t0.gstatic.com",
+  "t1.gstatic.com",
+  "t2.gstatic.com",
+  "t3.gstatic.com",
+  "t4.gstatic.com",
+  "t5.gstatic.com",
+  "t6.gstatic.com",
+  "t7.gstatic.com",
+  "t8.gstatic.com",
+  "t9.gstatic.com",
+  "t10.gstatic.com",
+  "news.gstatic.com",
+  "books.gstatic.com",
+  "maps.gstatic.com",
+  // Google user-content thumbnails
+  "lh1.googleusercontent.com",
+  "lh2.googleusercontent.com",
+  "lh3.googleusercontent.com",
+  "lh4.googleusercontent.com",
+  "lh5.googleusercontent.com",
+  "lh6.googleusercontent.com"
+]);
+
+// src/schemas/helpers/url-trust/is-trusted-image-url.helper.ts
+var TRUSTED_IMAGE_HOSTS = /* @__PURE__ */ new Set([
+  "i.imgur.com",
+  "i.redd.it",
+  "preview.redd.it",
+  "upload.wikimedia.org",
+  "commons.wikimedia.org",
+  "images.unsplash.com",
+  "images.pexels.com",
+  "cdn.pixabay.com",
+  "live.staticflickr.com",
+  "farm1.staticflickr.com",
+  "farm2.staticflickr.com",
+  "farm3.staticflickr.com",
+  "farm4.staticflickr.com",
+  "farm5.staticflickr.com",
+  "farm6.staticflickr.com",
+  "farm7.staticflickr.com",
+  "farm8.staticflickr.com",
+  "farm9.staticflickr.com",
+  "i.pinimg.com",
+  "media.istockphoto.com",
+  "assets.istockphoto.com",
+  "media.gettyimages.com",
+  "embed.gettyimages.com",
+  // Social image CDNs (images are generally embeddable, unlike videos)
+  "pbs.twimg.com",
+  "cdninstagram.com",
+  "scontent.cdninstagram.com",
+  "scontent-iad3-1.cdninstagram.com",
+  "graph.facebook.com",
+  "scontent-iad3-1.xx.fbcdn.net",
+  "scontent.xx.fbcdn.net",
+  "static.xx.fbcdn.net",
+  // Cloud/CDNs
+  "res.cloudinary.com",
+  "images.ctfassets.net",
+  "cdn.shopify.com",
+  "imgix.net",
+  "wpmedia.roomsketcher.com",
+  // Bing image CDN
+  "tse1.mm.bing.net",
+  "tse2.mm.bing.net",
+  "tse3.mm.bing.net",
+  "tse4.mm.bing.net"
+]);
+var DIRECT_IMAGE_EXTENSION = /\.(jpg|jpeg|png|gif|webp|bmp|tiff|tif|avif|svg|ico)(\?.*)?$/i;
+function isTrustedImageUrl(url) {
+  if (!url) return false;
+  if (url.startsWith("/") || url.startsWith("data:image/")) return true;
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
+  const hostname = parsed.hostname.toLowerCase();
+  if (BLOCKED_IMAGE_HOSTS.has(hostname)) return false;
+  if (TRUSTED_IMAGE_HOSTS.has(hostname)) return true;
+  if (DIRECT_IMAGE_EXTENSION.test(parsed.pathname)) return true;
+  return false;
+}
+
+// src/tools/constants/image-search.constants.ts
+var MIN_IMAGE_WIDTH = 1280;
+var MIN_IMAGE_HEIGHT = 720;
+function meetsMinimumImageDimensions(width, height, minWidth = MIN_IMAGE_WIDTH, minHeight = MIN_IMAGE_HEIGHT) {
+  if (!width || !height) return false;
+  return width >= minWidth && height >= minHeight;
+}
+
+// src/tools/helpers/apply-locale-params.helper.ts
+function applyLocaleParams(body, lang) {
+  if (!lang) return;
+  body.hl = lang;
+  const country = resolveLikelyCountry(lang);
+  if (country) body.gl = country;
+}
+function resolveLikelyCountry(lang) {
+  try {
+    const region = new Intl.Locale(lang).maximize().region;
+    return region ? region.toLowerCase() : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/tools/helpers/apply-recency-param.helper.ts
+var QDR_BY_RECENCY = {
+  day: "qdr:d",
+  week: "qdr:w",
+  month: "qdr:m",
+  year: "qdr:y"
+};
+function applyRecencyParam(body, recency) {
+  if (!recency) return;
+  const qdr = QDR_BY_RECENCY[recency];
+  const existing = typeof body.tbs === "string" ? body.tbs : "";
+  body.tbs = existing ? `${existing},${qdr}` : qdr;
+}
+
+// src/tools/helpers/image-size-buckets.ts
+var IMAGE_SIZE_BUCKETS = [
+  { mp: 0.12, label: "qsvga" },
+  // > 400×300
+  { mp: 0.307, label: "vga" },
+  // > 640×480
+  { mp: 0.48, label: "svga" },
+  // > 800×600
+  { mp: 0.786, label: "xga" },
+  // > 1024×768
+  { mp: 2, label: "2mp" },
+  // > 2 MP
+  { mp: 4, label: "4mp" },
+  // > 4 MP
+  { mp: 6, label: "6mp" },
+  // > 6 MP
+  { mp: 8, label: "8mp" },
+  // > 8 MP
+  { mp: 10, label: "10mp" },
+  // > 10 MP
+  { mp: 12, label: "12mp" },
+  // > 12 MP
+  { mp: 15, label: "15mp" },
+  // > 15 MP
+  { mp: 20, label: "20mp" },
+  // > 20 MP
+  { mp: 40, label: "40mp" },
+  // > 40 MP
+  { mp: 70, label: "70mp" }
+  // > 70 MP
+];
+function tbsSizeLabelForPixels(pixels) {
+  const targetMp = pixels / 1e6;
+  const selected = IMAGE_SIZE_BUCKETS.findLast((bucket) => bucket.mp <= targetMp) ?? IMAGE_SIZE_BUCKETS[IMAGE_SIZE_BUCKETS.length - 1];
+  return selected.label;
+}
+
+// src/tools/bright-data/image-search.tool.ts
+function createBrightDataImageSearch(deps) {
+  return tool({
+    description: "Search for images using Bright Data SERP API (Google Images). Returns image URLs and source pages. The tool passes the appropriate Google Images `tbs=isz:lt,islt:<bucket>` size filter server-side and trusts it for minimum resolution (Bright Data does not return pixel dimensions), while still rejecting untrusted domains such as Google thumbnail proxies (encrypted-tbn*.gstatic.com), data URIs, localhost, and private IPs. Pass minWidth/minHeight to request higher resolutions. " + STANDALONE_QUERY_TOOL_CLAUSE,
+    inputSchema: brightDataImageSearchSchema,
+    execute: async ({
+      query,
+      count: reqCount,
+      minWidth: requestedMinWidth,
+      minHeight: requestedMinHeight,
+      lang,
+      recency
+    }) => {
+      const cfg = deps.getLiveConfig().brightData;
+      const apiKey = engineEnabled(deps, "images");
+      if (!apiKey)
+        return {
+          results: [],
+          error: "Bright Data image search is not enabled"
+        };
+      const minWidth = Math.max(requestedMinWidth ?? 0, MIN_IMAGE_WIDTH);
+      const minHeight = Math.max(requestedMinHeight ?? 0, MIN_IMAGE_HEIGHT);
+      deps.logger.log(`Bright Data image search for "${query}" min ${minWidth}x${minHeight}`);
+      const body = {};
+      applyLocaleParams(body, lang);
+      applyRecencyParam(body, recency);
+      const tbs = `isz:lt,islt:${tbsSizeLabelForPixels(minWidth * minHeight)}`;
+      const url = buildGoogleUrl(query, {
+        udm: 2,
+        hl: body.hl,
+        gl: body.gl,
+        tbs: body.tbs ? `${body.tbs},${tbs}` : tbs,
+        num: reqCount ?? cfg.images.results
+      });
+      try {
+        const data = await requestBrightData(apiKey, cfg.serpZone, url, {
+          timeoutMs: BRIGHT_DATA_TIMEOUT_MS
+        });
+        const images = data.images ?? [];
+        if (!images.length) {
+          deps.logger.warn(`Bright Data image search returned 0 results for "${query}"`);
+          return { results: [] };
+        }
+        const results = images.map((r) => ({
+          title: r.title || "",
+          // Prefer the real image URL; `image` is a base64 thumbnail data
+          // URI that our trust rules reject.
+          imageUrl: r.original_image || r.image_url || r.imageUrl || r.link || "",
+          sourcePageUrl: r.source_link || r.link || "",
+          width: r.width,
+          height: r.height,
+          source: r.source || "",
+          domain: ""
+        })).filter((r) => {
+          if (!isTrustedImageUrl(r.imageUrl)) return false;
+          const w = r.width ?? 0;
+          const h = r.height ?? 0;
+          if (!w || !h) return true;
+          return meetsMinimumImageDimensions(w, h, minWidth, minHeight);
+        });
+        deps.logger.log(`Bright Data image search returned ${results.length} results for "${query}"`);
+        return { results };
+      } catch (err) {
+        deps.logger.warn(`Bright Data image search failed for "${query}": ${String(err)}`);
+        return { results: [] };
+      }
+    }
+  });
+}
+var brightDataNewsSearchSchema = z.object({
+  query: z.string().describe(`${STANDALONE_QUERY_DESCRIPTION} Include the newsworthy angle (announcement, release, event, update).`),
+  count: z.number().optional().describe("Number of results (max 100)"),
+  recency: z.enum(["day", "week", "month", "year"]).optional().describe(RECENCY_DESCRIPTION),
+  lang: z.string().optional().describe("Two-letter ISO language code for result preference (e.g. en, de, ja)")
+});
+function createBrightDataNewsSearch(deps) {
+  return tool({
+    description: 'Search the latest news using Bright Data SERP API. Returns headlines, sources, dates, and snippets. Pass recency ("day"|"week"|"month"|"year") to restrict to a recent period. ' + STANDALONE_QUERY_TOOL_CLAUSE,
+    inputSchema: brightDataNewsSearchSchema,
+    execute: async ({ query, count: reqCount, recency, lang }) => {
+      const cfg = deps.getLiveConfig().brightData;
+      const apiKey = engineEnabled(deps, "news");
+      if (!apiKey) return { results: [], error: "Bright Data news search is not enabled" };
+      deps.logger.log(`Bright Data news search for "${query}"`);
+      const body = {};
+      applyLocaleParams(body, lang ?? deps.defaultLang);
+      applyRecencyParam(body, recency);
+      const url = buildGoogleUrl(query, {
+        tbm: "nws",
+        hl: body.hl,
+        gl: body.gl,
+        tbs: body.tbs,
+        num: reqCount ?? cfg.news.results
+      });
+      try {
+        const data = await requestBrightData(apiKey, cfg.serpZone, url, {
+          timeoutMs: BRIGHT_DATA_TIMEOUT_MS
+        });
+        const news = data.news ?? [];
+        if (!news.length) return { results: [] };
+        const results = news.map((r) => ({
+          title: r.title,
+          snippet: r.description || "",
+          url: r.link,
+          source: r.source || SOURCE,
+          date: r.date || "",
+          imageUrl: r.image_url || ""
+        }));
+        deps.logger.log(`Bright Data news returned ${results.length} results for "${query}"`);
+        return { results };
+      } catch (err) {
+        deps.logger.warn(`Bright Data news search failed for "${query}": ${String(err)}`);
+        return { results: [] };
+      }
+    }
+  });
+}
+var brightDataPlacesSearchSchema = z.object({
+  query: z.string().describe(
+    'A standalone places search query that explicitly names the business or business type plus location (e.g. "MediaMarkt Berlin", "coffee shops in Munich").'
+  ),
+  count: z.number().optional().describe("Number of results (max 100)"),
+  lang: z.string().optional().describe("Two-letter ISO language code for result preference (e.g. en, de, ja)")
+});
+function createBrightDataPlacesSearch(deps) {
+  return tool({
+    description: 'Search for places and businesses using Bright Data SERP API (Google Maps local results). Returns names, addresses, ratings, review counts, and coordinates. Phrase the query like a Google Maps search: a business name, a business type, or a business type plus location (e.g. "MediaMarkt Berlin", "coffee shops in Munich").',
+    inputSchema: brightDataPlacesSearchSchema,
+    execute: async ({ query, count: reqCount, lang }) => {
+      const cfg = deps.getLiveConfig().brightData;
+      const apiKey = engineEnabled(deps, "places");
+      if (!apiKey)
+        return {
+          results: [],
+          error: "Bright Data places search is not enabled"
+        };
+      deps.logger.log(`Bright Data places search for "${query}"`);
+      const body = {};
+      applyLocaleParams(body, lang ?? deps.defaultLang);
+      const url = buildGoogleUrl(query, {
+        tbm: "lcl",
+        hl: body.hl,
+        gl: body.gl,
+        num: reqCount ?? cfg.places.results
+      });
+      try {
+        const data = await requestBrightData(apiKey, cfg.serpZone, url, {
+          timeoutMs: BRIGHT_DATA_TIMEOUT_MS
+        });
+        const places = data.local_results ?? data.places ?? [];
+        if (!places.length) {
+          deps.logger.warn(`Bright Data places returned 0 results for "${query}"`);
+          return { results: [] };
+        }
+        const results = places.map((r) => ({
+          title: r.title || "",
+          address: r.address || "",
+          phoneNumber: r.phone || "",
+          latitude: r.latitude,
+          longitude: r.longitude,
+          rating: r.rating,
+          ratingCount: r.reviews_cnt,
+          type: r.type || "",
+          website: r.website || ""
+        }));
+        return { results };
+      } catch (err) {
+        deps.logger.warn(`Bright Data places search failed for "${query}": ${String(err)}`);
+        return { results: [] };
+      }
+    }
+  });
+}
+var brightDataShoppingSearchSchema = z.object({
+  query: z.string().describe("The exact product name with model number, kept short and standalone."),
+  count: z.number().optional().describe("Number of results (max 100)"),
+  lang: z.string().optional().describe("Two-letter ISO language code for result preference (e.g. en, de, ja)")
+});
+function createBrightDataShoppingSearch(deps) {
+  return tool({
+    description: 'Search for products using Bright Data SERP API (Google Shopping). Returns prices, sellers, images, and ratings. Phrase the query as the bare product name with model number (e.g. "Sony WH-1000XM5") \u2014 do NOT add words like "review", "test", or long descriptive sentences.',
+    inputSchema: brightDataShoppingSearchSchema,
+    execute: async ({ query, count: reqCount, lang }) => {
+      const cfg = deps.getLiveConfig().brightData;
+      const apiKey = engineEnabled(deps, "shopping");
+      if (!apiKey)
+        return {
+          results: [],
+          error: "Bright Data shopping search is not enabled"
+        };
+      deps.logger.log(`Bright Data shopping search for "${query}"`);
+      const body = {};
+      applyLocaleParams(body, lang ?? deps.defaultLang);
+      const url = buildGoogleUrl(query, {
+        udm: 28,
+        hl: body.hl,
+        gl: body.gl,
+        num: reqCount ?? cfg.shopping.results
+      });
+      try {
+        const data = await requestBrightData(apiKey, cfg.serpZone, url, {
+          timeoutMs: BRIGHT_DATA_TIMEOUT_MS
+        });
+        const shopping = data.shopping ?? [];
+        if (!shopping.length) {
+          deps.logger.warn(`Bright Data shopping returned 0 results for "${query}"`);
+          return { results: [] };
+        }
+        const results = shopping.map((r) => ({
+          title: r.title || "",
+          price: r.price || "",
+          link: r.link || "",
+          source: r.source || "",
+          imageUrl: r.image_url || r.image || "",
+          delivery: r.delivery || "",
+          rating: r.rating,
+          ratingCount: r.rating_count
+        }));
+        return { results };
+      } catch (err) {
+        deps.logger.warn(`Bright Data shopping search failed for "${query}": ${String(err)}`);
+        return { results: [] };
+      }
+    }
+  });
+}
+var brightDataVideoSearchSchema = z.object({
+  query: z.string().describe(`${STANDALONE_QUERY_DESCRIPTION} Add the video type (e.g. review, trailer, tutorial, gameplay).`),
+  count: z.number().optional().describe("Number of results (max 100)"),
+  recency: z.enum(["day", "week", "month", "year"]).optional().describe(RECENCY_DESCRIPTION),
+  lang: z.string().optional().describe("Two-letter ISO language code for result preference (e.g. en, de, ja)")
+});
+
+// src/tools/helpers/build-youtube-thumbnail-url.helper.ts
+var YOUTUBE_ID_PATTERN = /^[A-Za-z0-9_-]{11}$/;
+function extractYoutubeVideoId(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return void 0;
+  }
+  const host = parsed.hostname.toLowerCase().replace(/^www\.|^m\./, "");
+  if (host === "youtu.be") {
+    const id = parsed.pathname.slice(1).split("/")[0];
+    return YOUTUBE_ID_PATTERN.test(id) ? id : void 0;
+  }
+  if (host === "youtube.com" || host === "youtube-nocookie.com") {
+    const watchId = parsed.searchParams.get("v");
+    if (watchId && YOUTUBE_ID_PATTERN.test(watchId)) return watchId;
+    const pathMatch = parsed.pathname.match(/^\/(shorts|embed|live)\/([A-Za-z0-9_-]{11})/);
+    if (pathMatch) return pathMatch[2];
+  }
+  return void 0;
+}
+function buildYoutubeThumbnailUrl(url) {
+  const id = extractYoutubeVideoId(url);
+  return id ? `https://i.ytimg.com/vi/${id}/hqdefault.jpg` : void 0;
+}
+
+// src/tools/helpers/localized-query-suffix.helper.ts
+function localizedQuerySuffix(lang) {
+  if (!lang) return "";
+  let code;
+  try {
+    code = new Intl.Locale(lang).language;
+  } catch {
+    return "";
+  }
+  if (!code || code === "en") return "";
+  try {
+    const name = new Intl.DisplayNames([code], { type: "language" }).of(code);
+    return !name || name === code ? "" : name;
+  } catch {
+    return "";
+  }
+}
+
+// src/tools/bright-data/video-search.tool.ts
+function createBrightDataVideoSearch(deps) {
+  return tool({
+    description: 'Search for videos using Bright Data SERP API (Google Videos). Returns titles, links, snippets, and duration. Only return URLs from supported embeddable providers: YouTube, Vimeo, Dailymotion, Loom, Wistia, or direct video files. Reject Instagram, Facebook, TikTok, Twitch, X/Twitter, and other unreliable platforms. Pass recency ("day"|"week"|"month"|"year") to restrict to recently uploaded videos. ' + STANDALONE_QUERY_TOOL_CLAUSE,
+    inputSchema: brightDataVideoSearchSchema,
+    execute: async ({ query, count: reqCount, recency, lang }) => {
+      const cfg = deps.getLiveConfig().brightData;
+      const apiKey = engineEnabled(deps, "videos");
+      if (!apiKey)
+        return {
+          results: [],
+          error: "Bright Data video search is not enabled"
+        };
+      const langSuffix = localizedQuerySuffix(lang ?? deps.defaultLang);
+      const searchQuery = langSuffix && !query.toLowerCase().includes(langSuffix.toLowerCase()) ? `${query} ${langSuffix}` : query;
+      deps.logger.log(`Bright Data video search for "${searchQuery}"`);
+      const body = {};
+      applyLocaleParams(body, lang ?? deps.defaultLang);
+      applyRecencyParam(body, recency);
+      const url = buildGoogleUrl(searchQuery, {
+        udm: 7,
+        hl: body.hl,
+        gl: body.gl,
+        tbs: body.tbs,
+        num: reqCount ?? cfg.videos.results
+      });
+      try {
+        const data = await requestBrightData(apiKey, cfg.serpZone, url, {
+          timeoutMs: BRIGHT_DATA_TIMEOUT_MS
+        });
+        const videos = data.organic ?? [];
+        if (!videos.length) return { results: [] };
+        const results = videos.map((r) => ({
+          title: r.title || "",
+          link: r.link || "",
+          snippet: r.description || "",
+          channel: "",
+          duration: r.duration || "",
+          date: "",
+          // `image` is an embedded base64 thumbnail — derive a direct YouTube
+          // thumbnail from the link instead.
+          thumbnailUrl: buildYoutubeThumbnailUrl(r.link || "") ?? "",
+          source: SOURCE,
+          views: 0
+        }));
+        deps.logger.log(`Bright Data video search returned ${results.length} results for "${searchQuery}"`);
+        return { results };
+      } catch (err) {
+        deps.logger.warn(`Bright Data video search failed for "${searchQuery}": ${String(err)}`);
+        return { results: [] };
+      }
+    }
+  });
+}
+var brightDataWebSearchSchema = z.object({
+  query: z.string().describe(STANDALONE_QUERY_DESCRIPTION),
+  recency: z.enum(["day", "week", "month", "year"]).optional().describe(RECENCY_DESCRIPTION),
+  lang: z.string().optional().describe("Two-letter ISO language code for result preference (e.g. en, de, ja)")
+});
+function createBrightDataWebSearch(deps) {
+  return tool({
+    description: 'Search the web using Bright Data SERP API (Google). Returns organic results with titles, snippets, and links. Pass recency ("day"|"week"|"month"|"year") to restrict to fresh results. ' + STANDALONE_QUERY_TOOL_CLAUSE,
+    inputSchema: brightDataWebSearchSchema,
+    execute: async ({ query, recency, lang }) => {
+      const cfg = deps.getLiveConfig().brightData;
+      const apiKey = engineEnabled(deps, "web");
+      if (!apiKey) return { results: [], error: "Bright Data web search is not enabled" };
+      deps.logger.log(`Bright Data web search for "${query}"`);
+      const body = {};
+      applyLocaleParams(body, lang ?? deps.defaultLang);
+      applyRecencyParam(body, recency);
+      const url = buildGoogleUrl(query, {
+        hl: body.hl,
+        gl: body.gl,
+        tbs: body.tbs,
+        num: cfg.web.results
+      });
+      try {
+        const data = await requestBrightData(apiKey, cfg.serpZone, url, {
+          timeoutMs: BRIGHT_DATA_TIMEOUT_MS
+        });
+        const organic = data.organic ?? [];
+        if (!organic.length) {
+          deps.logger.warn(`Bright Data returned 0 results for "${query}"`);
+          return { results: [] };
+        }
+        const results = organic.map((r) => ({
+          title: r.title,
+          snippet: r.description || "",
+          url: r.link,
+          source: SOURCE
+        }));
+        deps.logger.log(`Bright Data returned ${results.length} results for "${query}"`);
+        return { results };
+      } catch (err) {
+        deps.logger.warn(`Bright Data web search failed for "${query}": ${String(err)}`);
+        return { results: [] };
+      }
+    }
+  });
+}
+var brightDataWebpageScrapeSchema = z.object({
+  url: z.string().describe("The URL to fetch and render")
+});
+function createBrightDataWebpageScrape(deps) {
+  return tool({
+    description: "Fetch and render a full webpage using Bright Data Web Unlocker API. Returns clean Markdown text with its title. Use for pages behind anti-bot protection that plain fetch cannot reach.",
+    inputSchema: brightDataWebpageScrapeSchema,
+    execute: async ({ url }) => {
+      const cfg = deps.getLiveConfig().brightData;
+      if (!cfg.enabled || !cfg.apiKey || !cfg.unlockerZone) {
+        return {
+          content: "",
+          error: "Bright Data webpage scrape is not enabled"
+        };
+      }
+      if (!cfg.scrape.enabled) {
+        return {
+          content: "",
+          error: "Bright Data webpage scrape is not enabled"
+        };
+      }
+      deps.logger.log(`Bright Data webpage scrape for "${url}"`);
+      try {
+        const data = await requestBrightData(cfg.apiKey, cfg.unlockerZone, url, {
+          markdown: true,
+          timeoutMs: BRIGHT_DATA_TIMEOUT_MS
+        });
+        const content = data.text || "";
+        deps.logger.log(`Bright Data webpage scraped ${content.length} chars from "${url}"`);
+        return { content, title: "" };
+      } catch (err) {
+        deps.logger.warn(`Bright Data webpage scrape failed for "${url}": ${String(err)}`);
+        return { content: "", error: String(err) };
+      }
+    }
+  });
+}
+
+// src/tools/helpers/is-google-host-url.helper.ts
+function isGoogleHostUrl(url) {
+  try {
+    return /(^|\.)google\.[a-z.]+$/.test(new URL(url).hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
+// src/tools/helpers/pick-merchant-result.helper.ts
+function pickMerchantResult(results, storeToken) {
+  if (!storeToken) return void 0;
+  for (const { url } of results) {
+    if (!url) continue;
+    let hostname;
+    try {
+      hostname = new URL(url).hostname.toLowerCase().replace(/^www\./, "");
+    } catch {
+      continue;
+    }
+    if (hostname.replaceAll(".", "").includes(storeToken)) return url;
+    const labelMatch = hostname.split(".").some((label) => label.length >= 4 && storeToken.includes(label));
+    if (labelMatch) return url;
+  }
+  return void 0;
+}
+
+// src/tools/helpers/store-host-token.helper.ts
+var NON_IDENTITY_TOKENS = /* @__PURE__ */ new Set([
+  // company/legal forms
+  "gmbh",
+  "ag",
+  "se",
+  "kg",
+  "ohg",
+  "ug",
+  "ltd",
+  "inc",
+  "llc",
+  "sarl",
+  "sa",
+  "bv",
+  "oy",
+  "ab",
+  "as",
+  "spa",
+  "srl",
+  "pte",
+  "pty",
+  // tld and host labels
+  "com",
+  "de",
+  "at",
+  "ch",
+  "co",
+  "uk",
+  "net",
+  "org",
+  "io",
+  "eu",
+  "fr",
+  "nl",
+  "it",
+  "es",
+  "pl",
+  "no",
+  "fi",
+  "dk",
+  "us",
+  "ca",
+  "au",
+  "nz",
+  "jp",
+  "kr",
+  "cn",
+  "in",
+  "br",
+  "mx",
+  "ru",
+  "be",
+  "ie",
+  "cz",
+  "gr",
+  "pt",
+  "hu",
+  "ro",
+  "shop",
+  "store",
+  "online"
+]);
+function storeHostToken(source) {
+  return source.toLowerCase().split(/[^a-z0-9]+/).filter((token) => token.length > 0 && !NON_IDENTITY_TOKENS.has(token)).join("");
+}
+
+// src/tools/helpers/serper-shop-links.ts
+var SERPER_SEARCH_URL = "https://google.serper.dev/search";
+var MAX_LINK_RESOLUTIONS = 12;
+var RESOLUTION_RESULT_COUNT = 3;
+async function resolveSerperShopOfferLinks(offers, deps) {
+  const googleLinked = offers.filter((offer) => offer.link && isGoogleHostUrl(offer.link));
+  if (googleLinked.length === 0) return offers;
+  const resolvable = googleLinked.slice(0, MAX_LINK_RESOLUTIONS);
+  const resolutions = await Promise.all(
+    resolvable.map(async (offer) => ({
+      offer,
+      merchantUrl: await fetchMerchantUrl(offer, deps)
+    }))
+  );
+  const merchantUrlByLink = /* @__PURE__ */ new Map();
+  for (const { offer, merchantUrl } of resolutions) {
+    if (merchantUrl) merchantUrlByLink.set(offer.link, merchantUrl);
+  }
+  if (merchantUrlByLink.size === 0) return offers;
+  deps.logger.log(`Resolved ${merchantUrlByLink.size}/${googleLinked.length} Google shop link(s) to merchant URLs`);
+  return offers.map(
+    (offer) => merchantUrlByLink.has(offer.link) ? { ...offer, link: merchantUrlByLink.get(offer.link) } : offer
+  );
+}
+async function fetchMerchantUrl(offer, deps) {
+  const token = storeHostToken(offer.source ?? "");
+  if (!token || !offer.title) return void 0;
+  try {
+    const body = {
+      q: `${offer.title} ${offer.source}`,
+      num: RESOLUTION_RESULT_COUNT
+    };
+    applyLocaleParams(body, deps.lang);
+    const res = await fetchWithTimeout(
+      SERPER_SEARCH_URL,
+      {
+        method: "POST",
+        headers: {
+          "X-API-KEY": deps.apiKey,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(body)
+      },
+      { timeoutMs: SEARCH_TIMEOUT_MS }
+    );
+    if (!res.ok) return void 0;
+    const data = await res.json();
+    return pickMerchantResult(
+      (data.organic ?? []).map((entry) => ({ url: entry.link })),
+      token
+    );
+  } catch {
+    return void 0;
+  }
+}
+var variantRequestSchema = z.object({});
+function createVariantRequestTool(variant) {
+  const descriptions = {
+    grayscale: "Request a grayscale version of the images. Use when color noise or color information is irrelevant, for example when reading text or analyzing shapes.",
+    denoised: "Request a denoised (blurred) version of the images. Use when the original has noise, grain, or artifacts that hide details.",
+    sharpened: "Request a sharpened version of the images. Use when edges or fine details are blurry.",
+    clahe: "Request a CLAHE (contrast-enhanced) version of the images. Use when details are hidden in shadows or highlights."
+  };
+  return tool({
+    description: descriptions[variant],
+    inputSchema: variantRequestSchema,
+    execute: async () => ({ variant })
+  });
+}
+var memoryDeleteSchema = z.object({
+  text: z.string().min(3).max(2e3).optional().describe(
+    "The exact stored statement to delete, quoted verbatim from a memoryRecall result. Record texts are the record identity \u2014 no ids needed. Never paraphrase: recall first, then delete the exact text."
+  ),
+  cognition: z.boolean().optional().describe(
+    "Set true ONLY when the user asks you to forget your accumulated understanding of them (the cognition profile \u2014 your derived model of their traits, likes and dislikes) or to start over entirely. Cannot be combined with text."
+  )
+});
+function createMemoryDeleteTool(deps) {
+  return tool({
+    description: "Delete from YOUR long-term memory of this user. Pass text \u2014 one exact stored statement quoted verbatim from a memoryRecall result \u2014 to delete that fact record. Pass cognition:true ONLY when the user asks you to forget your learned understanding of them or to start over (wipes your entire cognition space of the user: the structured profile AND every derived insight). Never delete on a guess: recall first with memoryRecall, then delete the verbatim statement. Deletion is permanent; the result confirms exactly what was removed.",
+    inputSchema: memoryDeleteSchema,
+    execute: async ({ text, cognition }) => {
+      if (cognition === true) {
+        try {
+          const removed = await deps.deleteCognition(deps.scope.memoryCognition ?? deps.scope.memoryPartition);
+          return removed.length > 0 ? {
+            deleted: removed.length,
+            removed,
+            note: "Your cognition space of this user was wiped (profile and insights) \u2014 understanding is forgotten, fact records are untouched."
+          } : {
+            deleted: 0,
+            message: "No cognition exists for this user."
+          };
+        } catch (error) {
+          return {
+            deleted: 0,
+            error: error instanceof Error ? error.message : "cognition delete failed"
+          };
+        }
+      }
+      if (!text) {
+        return {
+          deleted: 0,
+          error: "Provide exactly one of the two modes: text (verbatim record) or cognition:true."
+        };
+      }
+      try {
+        const outcome = await deps.deleteRecords({
+          memoryPartition: deps.scope.memoryPartition,
+          text
+        });
+        return outcome.deleted > 0 ? { deleted: outcome.deleted, removed: outcome.texts } : {
+          deleted: 0,
+          message: "No stored record matches that exact text \u2014 use memoryRecall to find the verbatim statement first."
+        };
+      } catch (error) {
+        return {
+          deleted: 0,
+          error: error instanceof Error ? error.message : "memory delete failed"
+        };
+      }
+    }
+  });
+}
+var memoryRecallSchema = z.object({
+  query: z.string().min(1).max(1e3).describe('What to recall as a natural-language question, e.g. "What is Sams phone number?"'),
+  tags: z.array(z.string().min(1).max(40)).max(8).optional().describe('Restrict to records tagged with ANY of these topics, e.g. ["work"].'),
+  contains: z.string().max(200).optional().describe('Restrict to records whose text contains this exact phrase, e.g. "phone number".'),
+  topK: z.number().int().min(1).max(10).optional().describe("Maximum number of results to return (default 5).")
+});
+function createMemoryRecallTool(deps) {
+  return tool({
+    description: 'Retrieve from YOUR long-term memory of this user \u2014 things the user told you in past conversations or asked you to remember (contact details, preferences, decisions, past topics). These are trusted user statements, NOT public facts. Use when the user asks whether you remember something they told you or refers back to a statement from earlier conversations; the results are also the verbatim source for memoryDelete. For "where did we leave off" / "what were we doing recently" questions use your injected RECENT CONVERSATIONS notes instead \u2014 this lane holds what the user told you, not the log of your recent activity. Attribute what you find to the user ("you mentioned\u2026", "you asked me to remember\u2026") and prefer it over web-search results for anything personal. Retrieval is semantic and sentence-aware \u2014 ask in natural language. Optionally restrict by topic tags (e.g. ["contacts"]) or exact phrase containment.',
+    inputSchema: memoryRecallSchema,
+    execute: async ({ query, tags, contains, topK }) => {
+      const hits = await deps.searchByText({
+        memoryPartition: deps.scope.memoryPartition,
+        text: query,
+        tags,
+        contains,
+        limit: topK ?? 5
+      });
+      if (hits.length === 0) {
+        return "No memories found for this user on this topic.";
+      }
+      const lines = hits.map((hit) => {
+        const who = hit.role === "user" ? "the user" : "you (assistant)";
+        const when = hit.createdAt ? ` on ${new Date(hit.createdAt).toISOString().slice(0, 10)}` : "";
+        return `- "${hit.text}" \u2014 stated by ${who}${when}`;
+      });
+      return `YOUR MEMORY OF THIS USER (trusted statements they said or asked you to remember \u2014 answer from them and attribute them to the user; never present them as public web knowledge):
+${lines.join("\n")}`;
+    }
+  });
+}
+var memoryRememberSchema = z.object({
+  text: z.string().min(1).max(2e3).describe('The fact to remember, as a self-contained statement, e.g. "Sams phone number is 555-1234".'),
+  tags: z.array(z.string().min(1).max(40)).max(8).optional().describe(
+    'Optional topic labels (lowercase, reusable) so future recall can filter by topic, e.g. ["contacts", "sam"].'
+  )
+});
+function createMemoryRememberTool(deps) {
+  return tool({
+    description: 'Store into YOUR long-term memory of this user: notable facts about subjects they care about (favorites, interests, projects, followed stocks, people, past topics), preferences and durable details they state, and anything they explicitly ask you to remember. Storing gathered knowledge and noticed preferences is expected \u2014 do not wait for an explicit "remember" instruction. This memory outlives the conversation and is recalled later with memoryRecall. STORAGE MECHANICS: each record is embedded as a whole and matched sentence-by-sentence at recall time \u2014 write ONE self-contained statement per call (a single dense sentence is fine, subject up front), restating a record verbatim updates it in place, and tags are the recall filter vocabulary (lowercase, reusable).',
+    inputSchema: memoryRememberSchema,
+    execute: async ({ text, tags }) => {
+      try {
+        const id = await deps.storeRecord({
+          memoryPartition: deps.scope.memoryPartition,
+          sessionId: deps.scope.sessionId,
+          conversationId: deps.scope.conversationId,
+          requestId: deps.scope.requestId,
+          text,
+          tags
+        });
+        return { stored: true, id };
+      } catch (error) {
+        return {
+          stored: false,
+          error: error instanceof Error ? error.message : "memory store failed"
+        };
+      }
+    }
+  });
+}
+var serperBusinessReviewsSearchSchema = z.object({
+  query: z.string().optional().describe(
+    "The exact business or place name, ideally with its location, named explicitly and resolved from the conversation. Used when neither placeId nor cid is known."
+  ),
+  placeId: z.string().optional().describe("Google Place ID of the business. Most precise identifier \u2014 prefer it when available."),
+  cid: z.string().optional().describe("Google CID of the business, e.g. from a places search result."),
+  lang: z.string().optional().describe("Two-letter ISO language code for result preference (e.g. en, de, ja)")
+});
+
+// src/tools/serper/serper.constants.ts
+var HEADERS = (apiKey) => ({
+  "X-API-KEY": apiKey,
+  "Content-Type": "application/json"
+});
+
+// src/tools/serper/business-reviews-search.tool.ts
+function createSerperBusinessReviewsSearch(deps) {
+  return tool({
+    description: `Fetch Google Maps reviews for a specific business or place using Serper.dev. 
+      Returns individual reviewer snippets with author names, star ratings, dates, and likes. 
+      This endpoint reviews BUSINESSES (shops, restaurants, hotels, services) \u2014 it does not search editorial product reviews. 
+      Identify the business by its exact name plus location via query (e.g. "MediaMarkt Berlin Alexanderplatz"), 
+      or pass placeId/cid when a previous places search returned them. 
+      Use it to judge seller/business reputation; for product quality opinions use a *WebSearch tool with a "<product> review" query instead.`,
+    inputSchema: serperBusinessReviewsSearchSchema,
+    execute: async ({ query, placeId, cid, lang }) => {
+      const cfg = deps.getLiveConfig().serper;
+      if (!cfg.enabled || !cfg.apiKey || !cfg.reviews.enabled) {
+        return {
+          results: [],
+          error: "Serper.dev reviews is not enabled"
+        };
+      }
+      if (!placeId && !cid && !query?.trim()) {
+        return {
+          results: [],
+          error: "Provide a placeId, cid, or business name query"
+        };
+      }
+      const lookup = placeId ?? cid ?? query?.trim();
+      deps.logger.log(`Serper.dev Reviews search for "${lookup}"`);
+      const body = {};
+      if (placeId) body.placeId = placeId;
+      else if (cid) body.cid = cid;
+      else body.q = query.trim();
+      applyLocaleParams(body, lang ?? deps.defaultLang);
+      const res = await fetchWithTimeout(
+        "https://google.serper.dev/reviews",
+        {
+          method: "POST",
+          headers: HEADERS(cfg.apiKey),
+          body: JSON.stringify(body)
+        },
+        { timeoutMs: SEARCH_TIMEOUT_MS }
+      );
+      if (!res.ok) return { results: [], error: `HTTP ${res.status}` };
+      const data = await res.json();
+      if (!data.reviews?.length) {
+        deps.logger.warn(`Serper.dev Reviews returned 0 results for "${lookup}"`);
+        return { results: [] };
+      }
+      const placeName = data.placeInfo?.title || "";
+      const results = data.reviews.map((r) => ({
+        author: r.user?.name || "",
+        snippet: r.snippet || "",
+        rating: r.rating,
+        date: r.isoDate || r.date || "",
+        likes: r.likes ?? 0,
+        place: placeName
+      }));
+      return {
+        results,
+        place: data.placeInfo ? {
+          title: data.placeInfo.title || "",
+          address: data.placeInfo.address || "",
+          rating: data.placeInfo.rating,
+          ratingCount: data.placeInfo.ratingCount
+        } : void 0
+      };
+    }
+  });
+}
+var serperImageSearchSchema = z.object({
+  query: z.string().describe(`${STANDALONE_QUERY_DESCRIPTION} Add short visual qualifiers describing the subject.`),
+  count: z.number().optional().describe("Number of results (max 100)"),
+  minWidth: z.number().optional().describe(
+    "Minimum image width in pixels. Use 1920 when the user wants 1080p-quality images, 2560 for 1440p, 3840 for 4K. The tool always enforces a floor of 1280 (720p)."
+  ),
+  minHeight: z.number().optional().describe(
+    "Minimum image height in pixels. Use 1080 when the user wants 1080p-quality images, 1440 for 1440p, 2160 for 4K. The tool always enforces a floor of 720 (720p)."
+  ),
+  lang: z.string().optional().describe("Two-letter ISO language code for result preference (e.g. en, de, ja)"),
+  recency: z.enum(["day", "week", "month", "year"]).optional().describe(RECENCY_DESCRIPTION)
+});
+function createSerperImageSearch(deps) {
+  return tool({
+    description: 'Search for images using Serper.dev (Google Images). Returns image URLs, thumbnails, source pages, and dimensions. The tool prefers 2560\xD71440 (1440p) images and always enforces a minimum of 1280\xD7720 (720p). It passes the appropriate Google Images `tbs=isz:lt,islt:<bucket>` size filter server-side, drops any returned images whose dimensions are below 1280\xD7720, and rejects untrusted domains such as Google thumbnail proxies (encrypted-tbn*.gstatic.com, t*.gstatic.com), data URIs, localhost, and private IPs. You do not need to pass minWidth/minHeight for the default 720p floor. If the user asks for a higher resolution, pass minWidth/minHeight and the tool will pick the smallest Google bucket that can satisfy the requested area. Common reference: 1280\xD7720 (720p) ~0.9 MP, 1920\xD71080 (1080p) ~2 MP, 2560\xD71440 (1440p) ~3.7 MP, 3840\xD72160 (4K) ~8.3 MP. Pass recency ("day"|"week"|"month"|"year") to restrict to recently published images. ' + STANDALONE_QUERY_TOOL_CLAUSE,
+    inputSchema: serperImageSearchSchema,
+    execute: async ({
+      query,
+      count: reqCount,
+      minWidth: requestedMinWidth,
+      minHeight: requestedMinHeight,
+      lang,
+      recency
+    }) => {
+      const cfg = deps.getLiveConfig().serper;
+      if (!cfg.enabled || !cfg.apiKey || !cfg.images.enabled) {
+        return {
+          results: [],
+          error: "Serper.dev image search is not enabled"
+        };
+      }
+      const minWidth = Math.max(requestedMinWidth ?? 0, MIN_IMAGE_WIDTH);
+      const minHeight = Math.max(requestedMinHeight ?? 0, MIN_IMAGE_HEIGHT);
+      deps.logger.log(`Serper.dev Image Search for "${query}" min ${minWidth}x${minHeight}`);
+      const num = Math.min(reqCount ?? cfg.images.results, cfg.images.results);
+      const body = { q: query, num };
+      applyLocaleParams(body, lang);
+      const targetPixels = minWidth * minHeight;
+      body.tbs = `isz:lt,islt:${tbsSizeLabelForPixels(targetPixels)}`;
+      applyRecencyParam(body, recency);
+      const res = await fetchWithTimeout(
+        "https://google.serper.dev/images",
+        {
+          method: "POST",
+          headers: HEADERS(cfg.apiKey),
+          body: JSON.stringify(body)
+        },
+        { timeoutMs: SEARCH_TIMEOUT_MS }
+      );
+      if (!res.ok) {
+        deps.logger.warn(`Serper.dev Image Search returned ${res.status} for "${query}"`);
+        return { results: [] };
+      }
+      const data = await res.json();
+      if (!data.images?.length) {
+        deps.logger.warn(`Serper.dev Image Search returned 0 results for "${query}"`);
+        return { results: [] };
+      }
+      const results = data.images.map((r) => ({
+        title: r.title || "",
+        imageUrl: r.imageUrl || r.image || "",
+        sourcePageUrl: r.link || "",
+        width: r.imageWidth ?? r.width,
+        height: r.imageHeight ?? r.height,
+        source: r.source || "",
+        domain: r.domain || ""
+      })).filter((r) => {
+        if (!isTrustedImageUrl(r.imageUrl)) return false;
+        const w = r.width ?? 0;
+        const h = r.height ?? 0;
+        if (!w || !h) return true;
+        return meetsMinimumImageDimensions(w, h, minWidth, minHeight);
+      });
+      deps.logger.log(`Serper.dev Image Search returned ${results.length} results for "${query}"`);
+      return { results };
+    }
+  });
+}
+var serperNewsSearchSchema = z.object({
+  query: z.string().describe(`${STANDALONE_QUERY_DESCRIPTION} Include the newsworthy angle (announcement, release, event, update).`),
+  count: z.number().optional().describe("Number of results (max 100)"),
+  recency: z.enum(["day", "week", "month", "year"]).optional().describe(RECENCY_DESCRIPTION),
+  lang: z.string().optional().describe("Two-letter ISO language code for result preference (e.g. en, de, ja)")
+});
+function createSerperNewsSearch(deps) {
+  return tool({
+    description: 'Search the latest news using Serper.dev. Returns headlines, sources, dates, and snippets. Pass recency ("day"|"week"|"month"|"year") to restrict to a recent period. ' + STANDALONE_QUERY_TOOL_CLAUSE,
+    inputSchema: serperNewsSearchSchema,
+    execute: async ({ query, count: reqCount, recency, lang }) => {
+      const cfg = deps.getLiveConfig().serper;
+      if (!cfg.enabled || !cfg.apiKey || !cfg.news.enabled) {
+        return { results: [], error: "Serper.dev news is not enabled" };
+      }
+      deps.logger.log(`Serper.dev News search for "${query}"`);
+      const num = Math.min(reqCount ?? cfg.news.results, cfg.news.results);
+      const newsBody = {
+        q: query,
+        num
+      };
+      applyLocaleParams(newsBody, lang ?? deps.defaultLang);
+      applyRecencyParam(newsBody, recency);
+      const res = await fetchWithTimeout(
+        "https://google.serper.dev/news",
+        {
+          method: "POST",
+          headers: HEADERS(cfg.apiKey),
+          body: JSON.stringify(newsBody)
+        },
+        { timeoutMs: SEARCH_TIMEOUT_MS }
+      );
+      if (!res.ok) return { results: [] };
+      const data = await res.json();
+      if (!data.news?.length) return { results: [] };
+      const results = data.news.map((r) => ({
+        title: r.title,
+        snippet: r.snippet || "",
+        url: r.link,
+        source: r.source || "",
+        date: r.date || "",
+        imageUrl: r.imageUrl || ""
+      }));
+      return { results };
+    }
+  });
+}
+var serperPlacesSearchSchema = z.object({
+  query: z.string().describe(
+    'A standalone places search query that explicitly names the business or business type plus location (e.g. "MediaMarkt Berlin", "coffee shops in Munich") \u2014 resolve the subject from the conversation; never copy the user message verbatim.'
+  ),
+  count: z.number().optional().describe("Number of results (max 100)"),
+  lang: z.string().optional().describe("Two-letter ISO language code for result preference (e.g. en, de, ja)")
+});
+function createSerperPlacesSearch(deps) {
+  return tool({
+    description: 'Search for places and businesses using Serper.dev (Google Maps). Returns addresses, phone numbers, ratings, review counts, and coordinates. Phrase the query like a Google Maps search: a business name, a business type, or a business type plus location (e.g. "MediaMarkt Berlin", "coffee shops in Munich").',
+    inputSchema: serperPlacesSearchSchema,
+    execute: async ({ query, count: reqCount, lang }) => {
+      const cfg = deps.getLiveConfig().serper;
+      if (!cfg.enabled || !cfg.apiKey || !cfg.places.enabled) {
+        return { results: [], error: "Serper.dev places is not enabled" };
+      }
+      deps.logger.log(`Serper.dev Places search for "${query}"`);
+      const num = Math.min(reqCount ?? cfg.places.results, cfg.places.results);
+      const body = { q: query, num };
+      applyLocaleParams(body, lang ?? deps.defaultLang);
+      const res = await fetchWithTimeout(
+        "https://google.serper.dev/places",
+        {
+          method: "POST",
+          headers: HEADERS(cfg.apiKey),
+          body: JSON.stringify(body)
+        },
+        { timeoutMs: SEARCH_TIMEOUT_MS }
+      );
+      if (!res.ok) {
+        return { results: [], error: `HTTP ${res.status}` };
+      }
+      const data = await res.json();
+      if (!data.places?.length) {
+        deps.logger.warn(`Serper.dev Places returned 0 results for "${query}"`);
+        return { results: [] };
+      }
+      const results = data.places.map((r) => ({
+        title: r.title,
+        address: r.address || "",
+        phoneNumber: r.phoneNumber || "",
+        latitude: r.latitude,
+        longitude: r.longitude,
+        rating: r.rating,
+        ratingCount: r.ratingCount,
+        type: r.type || "",
+        website: r.website || "",
+        cid: r.cid || ""
+      }));
+      return { results };
+    }
+  });
+}
+var serperShoppingSearchSchema = z.object({
+  query: z.string().describe(
+    'The exact product name with model number, kept short and standalone \u2014 resolve product references from the conversation (e.g. "the headphones we discussed" becomes "Sony WH-1000XM5"). No extra words like "buy", "price", or "review".'
+  ),
+  count: z.number().optional().describe("Number of results (max 100)"),
+  lang: z.string().optional().describe("Two-letter ISO language code for result preference (e.g. en, de, ja)")
+});
+function createSerperShoppingSearch(deps) {
+  return tool({
+    description: 'Search for products using Serper.dev (Google Shopping). Returns prices, sellers, delivery info, images, and per-offer ratings. Phrase the query as the bare product name with model number (e.g. "Sony WH-1000XM5") \u2014 do NOT add words like "review", "test", or long descriptive sentences, they hurt shopping result quality.',
+    inputSchema: serperShoppingSearchSchema,
+    execute: async ({ query, count: reqCount, lang }) => {
+      const cfg = deps.getLiveConfig().serper;
+      if (!cfg.enabled || !cfg.apiKey || !cfg.shopping.enabled) {
+        return {
+          results: [],
+          error: "Serper.dev shopping is not enabled"
+        };
+      }
+      deps.logger.log(`Serper.dev Shopping search for "${query}"`);
+      const num = Math.min(reqCount ?? cfg.shopping.results, cfg.shopping.results);
+      const body = { q: query, num };
+      const effectiveLang = lang ?? deps.defaultLang;
+      applyLocaleParams(body, effectiveLang);
+      const res = await fetchWithTimeout(
+        "https://google.serper.dev/shopping",
+        {
+          method: "POST",
+          headers: HEADERS(cfg.apiKey),
+          body: JSON.stringify(body)
+        },
+        { timeoutMs: SEARCH_TIMEOUT_MS }
+      );
+      if (!res.ok) return { results: [], error: `HTTP ${res.status}` };
+      const data = await res.json();
+      if (!data.shopping?.length) {
+        deps.logger.warn(`Serper.dev Shopping returned 0 results for "${query}"`);
+        return { results: [] };
+      }
+      const results = data.shopping.map((r) => ({
+        title: r.title,
+        price: r.price || "",
+        link: r.link || "",
+        source: r.source || "",
+        imageUrl: r.imageUrl || "",
+        delivery: r.delivery || "",
+        rating: r.rating,
+        ratingCount: r.ratingCount
+      }));
+      return {
+        results: await resolveSerperShopOfferLinks(results, {
+          apiKey: cfg.apiKey,
+          lang: effectiveLang,
+          logger: deps.logger
+        })
+      };
+    }
+  });
+}
+var serperVideoSearchSchema = z.object({
+  query: z.string().describe(
+    `${STANDALONE_QUERY_DESCRIPTION} Add the video type (e.g. review, trailer, tutorial, gameplay). When the conversation language is not English, phrase the descriptive words in that language and append the language's own name (e.g. "Review Deutsch") to pull localized results.`
+  ),
+  count: z.number().optional().describe("Number of results (max 100)"),
+  recency: z.enum(["day", "week", "month", "year"]).optional().describe(RECENCY_DESCRIPTION),
+  lang: z.string().optional().describe("Two-letter ISO language code for result preference (e.g. en, de, ja)")
+});
+function createSerperVideoSearch(deps) {
+  return tool({
+    description: 'Search for videos using Serper.dev. Returns titles, links, channel names, duration, and publish dates. Only return URLs from supported embeddable providers: YouTube, Vimeo, Dailymotion, Loom, Wistia, or direct video files. Reject Instagram, Facebook, TikTok, Twitch, X/Twitter, and other unreliable platforms. Pass recency ("day"|"week"|"month"|"year") to restrict to recently uploaded videos. ' + STANDALONE_QUERY_TOOL_CLAUSE,
+    inputSchema: serperVideoSearchSchema,
+    execute: async ({ query, count: reqCount, recency, lang }) => {
+      const cfg = deps.getLiveConfig().serper;
+      if (!cfg.enabled || !cfg.apiKey || !cfg.videos.enabled) {
+        return { results: [], error: "Serper.dev videos is not enabled" };
+      }
+      const langSuffix = localizedQuerySuffix(lang ?? deps.defaultLang);
+      const searchQuery = langSuffix && !query.toLowerCase().includes(langSuffix.toLowerCase()) ? `${query} ${langSuffix}` : query;
+      deps.logger.log(`Serper.dev Video search for "${searchQuery}"`);
+      const num = Math.min(reqCount ?? cfg.videos.results, cfg.videos.results);
+      const videoBody = {
+        q: searchQuery,
+        num
+      };
+      applyLocaleParams(videoBody, lang ?? deps.defaultLang);
+      applyRecencyParam(videoBody, recency);
+      const res = await fetchWithTimeout(
+        "https://google.serper.dev/videos",
+        {
+          method: "POST",
+          headers: HEADERS(cfg.apiKey),
+          body: JSON.stringify(videoBody)
+        },
+        { timeoutMs: SEARCH_TIMEOUT_MS }
+      );
+      if (!res.ok) return { results: [] };
+      const data = await res.json();
+      if (!data.videos?.length) return { results: [] };
+      const results = data.videos.slice(0, num).map((r) => ({
+        title: r.title,
+        link: r.link,
+        snippet: r.snippet || "",
+        channel: r.channel || "",
+        duration: r.duration || "",
+        date: r.date || "",
+        // Serper thumbnails are Google proxy images (blocked by our image
+        // trust rules) — derive a direct thumbnail for YouTube instead.
+        thumbnailUrl: buildYoutubeThumbnailUrl(r.link) ?? "",
+        source: r.source || "",
+        views: r.views ?? 0
+      }));
+      deps.logger.log(`Serper.dev Video search returned ${results.length} results for "${searchQuery}"`);
+      return { results };
+    }
+  });
+}
+var serperWebSearchSchema = z.object({
+  query: z.string().describe(STANDALONE_QUERY_DESCRIPTION),
+  recency: z.enum(["day", "week", "month", "year"]).optional().describe(RECENCY_DESCRIPTION),
+  lang: z.string().optional().describe("Two-letter ISO language code for result preference (e.g. en, de, ja)")
+});
+function createSerperWebSearch(deps) {
+  return tool({
+    description: 'Search the web using Serper.dev (Google results). Returns organic results with titles, snippets, and links. Pass recency ("day"|"week"|"month"|"year") to restrict to fresh results. ' + STANDALONE_QUERY_TOOL_CLAUSE,
+    inputSchema: serperWebSearchSchema,
+    execute: async ({ query, recency, lang }) => {
+      const cfg = deps.getLiveConfig().serper;
+      if (!cfg.enabled || !cfg.apiKey || !cfg.web.enabled) {
+        return { results: [], error: "Serper.dev web search is not enabled" };
+      }
+      deps.logger.log(`Serper.dev search for "${query}"`);
+      const body = {
+        q: query,
+        num: cfg.web.results
+      };
+      applyLocaleParams(body, lang ?? deps.defaultLang);
+      applyRecencyParam(body, recency);
+      const res = await fetchWithTimeout(
+        "https://google.serper.dev/search",
+        {
+          method: "POST",
+          headers: HEADERS(cfg.apiKey),
+          body: JSON.stringify(body)
+        },
+        { timeoutMs: SEARCH_TIMEOUT_MS }
+      );
+      if (!res.ok) {
+        deps.logger.warn(`Serper.dev returned ${res.status} for "${query}"`);
+        return { results: [] };
+      }
+      const data = await res.json();
+      if (!data.organic?.length) {
+        deps.logger.warn(`Serper.dev returned 0 results for "${query}"`);
+        return { results: [] };
+      }
+      const results = data.organic.map((r) => ({
+        title: r.title,
+        snippet: r.snippet || "",
+        url: r.link,
+        source: "serper"
+      }));
+      deps.logger.log(`Serper.dev returned ${results.length} results for "${query}"`);
+      return { results };
+    }
+  });
+}
+var serperWebpageScrapeSchema = z.object({
+  url: z.string().describe("The URL to fetch and render")
+});
+function createSerperWebpageScrape(deps) {
+  return tool({
+    description: "Fetch and render a full webpage using Serper.dev scrape API. Returns clean rendered text with its title.",
+    inputSchema: serperWebpageScrapeSchema,
+    execute: async ({ url }) => {
+      const cfg = deps.getLiveConfig().serper;
+      if (!cfg.apiKey || !cfg.scrape.enabled) {
+        return {
+          content: "",
+          error: "Serper.dev webpage scrape is not enabled"
+        };
+      }
+      deps.logger.log(`Serper.dev Webpage scrape for "${url}"`);
+      const res = await fetchWithTimeout(
+        "https://scrape.serper.dev",
+        {
+          method: "POST",
+          headers: HEADERS(cfg.apiKey),
+          body: JSON.stringify({ url })
+        },
+        { timeoutMs: SEARCH_TIMEOUT_MS }
+      );
+      if (!res.ok) {
+        deps.logger.warn(`Serper.dev Webpage scrape returned ${res.status} for "${url}"`);
+        return { content: "", error: `HTTP ${res.status}` };
+      }
+      const data = await res.json();
+      const content = data.text || "";
+      const title = data.title || "";
+      deps.logger.log(`Serper.dev Webpage scraped ${content.length} chars from "${url}"`);
+      return { content, title };
+    }
+  });
+}
+
+// src/tools/tool-factory.ts
+function extractSources(results) {
+  const sources = /* @__PURE__ */ new Set();
+  for (const r of results) {
+    const src = r.source;
+    if (!src) continue;
+    sources.add(src);
+  }
+  return [...sources];
+}
+var summarizeResults = (data) => {
+  const results = data.results;
+  if (!Array.isArray(results)) return {};
+  return {
+    resultCount: results.length,
+    sources: extractSources(results),
+    sampleImageUrls: results.slice(0, 5).map((r) => r.imageUrl).filter((url) => typeof url === "string" && url.length > 0)
+  };
+};
+var summarizeContent = (data) => ({
+  contentLength: typeof data.content === "string" ? data.content.length : 0
+});
+var summarizeFound = (data) => ({
+  found: !!data.title || !!data.id
+});
+var defaultSummarize = (data) => {
+  if (Array.isArray(data.results)) return summarizeResults(data);
+  if (typeof data.content === "string") return summarizeContent(data);
+  return {};
+};
+function withSummary(tool22, summarize = defaultSummarize) {
+  const t = tool22;
+  t.summarize = summarize;
+  return t;
+}
+var webFetchSchema = z.object({
+  url: z.string().describe("The URL to fetch content from")
+});
+function extractArticleText(html) {
+  if (!html.trim()) return "";
+  const { document } = parseHTML(html);
+  const turndown = new TurndownService();
+  const article = document.documentElement ? new Readability(document).parse() : null;
+  const content = article?.content;
+  if (typeof content === "string" && content.trim()) {
+    return turndown.turndown(content);
+  }
+  return turndown.turndown(document.body?.innerHTML ?? "");
+}
+
+// src/tools/web-fetch/web-fetch.tool.ts
+function createWebFetchTool() {
+  return tool({
+    description: "Fetch the full content of a specific URL. Returns the main article text as Markdown (boilerplate removed). Use only when search snippets are insufficient.",
+    inputSchema: webFetchSchema,
+    execute: async ({ url }) => {
+      const response = await fetchWithTimeout(
+        url,
+        {
+          headers: {
+            "User-Agent": "Mozilla/5.0 (compatible; TriplefBot/1.0)",
+            Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
+          }
+        },
+        { timeoutMs: SEARCH_TIMEOUT_MS }
+      );
+      const html = await response.text();
+      return { content: extractArticleText(html) };
+    }
+  });
+}
+var youtubeVideoSearchSchema = z.object({
+  query: z.string().describe(`${STANDALONE_QUERY_DESCRIPTION} Add the video type (e.g. review, trailer, tutorial, gameplay).`),
+  count: z.number().optional().describe("Number of results (max 50)"),
+  recency: z.enum(["day", "week", "month", "year"]).optional().describe(
+    "Restrict results to the given past period (day=24 hours, week=7 days, month=1 month, year=1 year). Use for fresh content such as news, recent releases, or trending topics; leave unset for evergreen, historical, or general queries."
+  ),
+  lang: z.string().optional().describe("Two-letter ISO language code for result preference (e.g. en, de, ja)")
+});
+
+// src/tools/youtube/youtube.ts
+var SEARCH_URL = "https://www.googleapis.com/youtube/v3/search";
+var VIDEOS_URL = "https://www.googleapis.com/youtube/v3/videos";
+var RECENCY_DAYS = {
+  day: 1,
+  week: 7,
+  month: 30,
+  year: 365
+};
+function publishedAfterFor(recency) {
+  if (!recency) return void 0;
+  return new Date(Date.now() - RECENCY_DAYS[recency] * 864e5).toISOString();
+}
+async function readErrorReason(res) {
+  try {
+    const body = await res.json();
+    return body.error?.errors?.[0]?.reason;
+  } catch {
+    return void 0;
+  }
+}
+function formatIsoDuration(iso) {
+  const match = iso?.match(/^PT(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?$/);
+  if (!match) return "";
+  const hours = Number(match[1] ?? 0);
+  const minutes = Number(match[2] ?? 0);
+  const seconds = Number(match[3] ?? 0);
+  const pad = (n) => String(n).padStart(2, "0");
+  return hours ? `${hours}:${pad(minutes)}:${pad(seconds)}` : `${minutes}:${pad(seconds)}`;
+}
+async function fetchYoutubeVideoStats(videoIds, apiKey, logger) {
+  const params = new URLSearchParams({
+    part: "statistics,contentDetails,snippet",
+    id: videoIds.join(","),
+    key: apiKey
+  });
+  const res = await fetchWithTimeout(`${VIDEOS_URL}?${params}`, {}, { timeoutMs: SEARCH_TIMEOUT_MS }).catch(
+    (err) => {
+      logger.warn(`YouTube stats fetch failed: ${err instanceof Error ? `${err.name}: ${err.message}` : String(err)}`);
+      throw err;
+    }
+  );
+  const map = /* @__PURE__ */ new Map();
+  if (!res.ok) {
+    const reason = await readErrorReason(res);
+    logger.warn(`YouTube stats fetch failed \u2014 HTTP ${res.status}${reason ? ` (${reason})` : ""}`);
+    return map;
+  }
+  const data = await res.json();
+  for (const item of data.items ?? []) {
+    if (!item.id) continue;
+    map.set(item.id, {
+      viewCount: Number(item.statistics?.viewCount ?? 0),
+      duration: item.contentDetails?.duration,
+      lang: item.snippet?.defaultAudioLanguage ?? item.snippet?.defaultLanguage
+    });
+  }
+  return map;
+}
+function createYoutubeVideoSearch(deps) {
+  return tool({
+    description: 'Search YouTube for videos using the official YouTube Data API. Returns titles, links, channel names, durations, view counts, and upload dates with direct thumbnails. Every result is an embeddable YouTube video. Pass recency ("day"|"week"|"month"|"year") to restrict to recently uploaded videos. ' + STANDALONE_QUERY_TOOL_CLAUSE,
+    inputSchema: youtubeVideoSearchSchema,
+    execute: async ({ query, count: reqCount, recency, lang }) => {
+      const cfg = deps.getLiveConfig().youtube;
+      if (!cfg.enabled || !cfg.apiKey || !cfg.videos.enabled) {
+        return { results: [], error: "YouTube video search is not enabled" };
+      }
+      const num = Math.min(reqCount ?? cfg.videos.results, cfg.videos.results, 50);
+      const params = new URLSearchParams({
+        part: "snippet",
+        type: "video",
+        videoEmbeddable: "true",
+        q: query,
+        maxResults: String(num),
+        order: recency ? "date" : "relevance",
+        key: cfg.apiKey
+      });
+      const langParam = lang ?? deps.defaultLang;
+      if (langParam) params.set("relevanceLanguage", langParam);
+      const publishedAfter = publishedAfterFor(recency);
+      if (publishedAfter) params.set("publishedAfter", publishedAfter);
+      deps.logger.log(`YouTube video search for "${query}"`);
+      const res = await fetchWithTimeout(`${SEARCH_URL}?${params}`, {}, { timeoutMs: SEARCH_TIMEOUT_MS }).catch(
+        (err) => {
+          deps.logger.warn(
+            `YouTube video search failed for "${query}": ${err instanceof Error ? `${err.name}: ${err.message}` : String(err)}`
+          );
+          throw err;
+        }
+      );
+      if (!res.ok) {
+        const reason = await readErrorReason(res);
+        deps.logger.warn(
+          `YouTube video search failed for "${query}" \u2014 HTTP ${res.status}${reason ? ` (${reason})` : ""}`
+        );
+        return { results: [], error: `HTTP ${res.status}` };
+      }
+      const data = await res.json();
+      const items = (data.items ?? []).filter((item) => item.id?.videoId);
+      if (!items.length) {
+        deps.logger.warn(`YouTube returned 0 results for "${query}"`);
+        return { results: [] };
+      }
+      const stats = await fetchYoutubeVideoStats(
+        items.map((item) => item.id.videoId),
+        cfg.apiKey,
+        deps.logger
+      );
+      const results = items.map((item) => {
+        const snippet = item.snippet ?? {};
+        const id = item.id.videoId;
+        const detail = stats.get(id);
+        const thumbs = snippet.thumbnails ?? {};
+        return {
+          title: snippet.title ?? "",
+          link: `https://www.youtube.com/watch?v=${id}`,
+          snippet: snippet.description ?? "",
+          channel: snippet.channelTitle ?? "",
+          duration: formatIsoDuration(detail?.duration),
+          date: snippet.publishedAt ?? "",
+          thumbnailUrl: thumbs.maxres?.url ?? thumbs.high?.url ?? thumbs.medium?.url ?? "",
+          source: "youtube",
+          views: detail?.viewCount ?? 0,
+          lang: detail?.lang
+        };
+      });
+      deps.logger.log(`YouTube video search returned ${results.length} results for "${query}"`);
+      return { results };
+    }
+  });
+}
+
+export { BRIGHT_DATA_TIMEOUT_MS, HEADERS, MIN_IMAGE_HEIGHT, MIN_IMAGE_WIDTH, RECENCY_DESCRIPTION, SEARCH_RETRIES, SEARCH_TIMEOUT_MS, SOURCE, STANDALONE_QUERY_DESCRIPTION, STANDALONE_QUERY_TOOL_CLAUSE, applyLocaleParams, applyRecencyParam, brightDataImageSearchSchema, brightDataNewsSearchSchema, brightDataPlacesSearchSchema, brightDataShoppingSearchSchema, brightDataVideoSearchSchema, brightDataWebSearchSchema, brightDataWebpageScrapeSchema, buildGoogleUrl, buildYoutubeThumbnailUrl, createBrightDataImageSearch, createBrightDataNewsSearch, createBrightDataPlacesSearch, createBrightDataShoppingSearch, createBrightDataVideoSearch, createBrightDataWebSearch, createBrightDataWebpageScrape, createMemoryDeleteTool, createMemoryRecallTool, createMemoryRememberTool, createSerperBusinessReviewsSearch, createSerperImageSearch, createSerperNewsSearch, createSerperPlacesSearch, createSerperShoppingSearch, createSerperVideoSearch, createSerperWebSearch, createSerperWebpageScrape, createVariantRequestTool, createWebFetchTool, createYoutubeVideoSearch, defaultSummarize, engineEnabled, fetchWithTimeout, isGoogleHostUrl, localizedQuerySuffix, meetsMinimumImageDimensions, memoryDeleteSchema, memoryRecallSchema, memoryRememberSchema, pickMerchantResult, requestBrightData, resolveSerperShopOfferLinks, serperBusinessReviewsSearchSchema, serperImageSearchSchema, serperNewsSearchSchema, serperPlacesSearchSchema, serperShoppingSearchSchema, serperVideoSearchSchema, serperWebSearchSchema, serperWebpageScrapeSchema, storeHostToken, summarizeContent, summarizeFound, summarizeResults, tbsSizeLabelForPixels, variantRequestSchema, webFetchSchema, withSummary, youtubeVideoSearchSchema };