@triplef/agent 0.1.10 → 0.1.12

package/README.md

@@ -16,7 +16,7 @@ The tripleF (3F) agent domain — structured-output schemas, prompt builders, an
 
 ## Subpath exports
 
-- `@triplef/agent/schemas` — Zod schemas and `z.infer` types for intent classification, response templates, and memory extraction/consolidation/profile, plus URL-trust and Zod-shape helpers (`formatZodShape`, `deriveSchemaKeys`) and the `LexiconSelectInput`/`LexiconSelectResult` retrieval-selection contract.
+- `@triplef/agent/schemas` — Zod schemas and `z.infer` types for intent classification, response templates, and memory extraction/consolidation/profile, plus URL-trust and Zod-shape helpers (`formatZodShape`, `deriveSchemaKeys`) and the `EncyclopediaSelectInput`/`EncyclopediaSelectResult` retrieval-selection contract.
 - `@triplef/agent/prompts` — harness and memory prompt builders, the snippet system, and `buildStructuredPrompt` (renders a schema's JSON shape into a prompt template).
 - `@triplef/agent/tools` — search/tool factories (Serper, Bright Data, YouTube, web-fetch, image-variants, memory) with a decoupled `ToolDependencies` contract.
 

package/dist/schemas/index.d.ts

@@ -6,6 +6,42 @@ declare const BLOCKED_IMAGE_HOSTS: Set<string>;
 declare const BLOCKED_URL_HOSTS: Set<string>;
 declare const NON_PAGE_EXTENSIONS: RegExp;
 
+interface EncyclopediaSourceDocument {
+    url?: string;
+    title?: string;
+    content: string;
+}
+interface EncyclopediaSelectedChunk {
+    url?: string;
+    title?: string;
+    content: string;
+    score: number;
+    sourceType?: 'content' | 'result';
+}
+interface EncyclopediaSearchResult {
+    url: string;
+    title?: string;
+    snippet: string;
+}
+interface EncyclopediaSelectInput {
+    query: string;
+    documents: EncyclopediaSourceDocument[];
+    searchResults?: EncyclopediaSearchResult[];
+    budgetChars?: number;
+    partitionScope?: string;
+    model?: string;
+}
+interface EncyclopediaSelectResult {
+    chunks: EncyclopediaSelectedChunk[];
+    consideredChunks: number;
+    selectedChunks: number;
+    droppedByThreshold: number;
+    inputChunksDropped: number;
+    pastChunks?: EncyclopediaSelectedChunk[];
+    reusedDocs?: number;
+    storedDocs?: number;
+}
+
 declare function categorizeTools(toolNames: readonly string[]): Record<string, string[]>;
 
 declare const VARIANT_NAMES: readonly ["grayscale", "denoised", "sharpened", "clahe"];
@@ -139,41 +175,6 @@ declare function deriveSchemaKeys(schema: z.ZodType): {
 
 declare function formatZodIssues(issues: z.ZodIssue[]): string;
 
-interface LexiconSourceDocument {
-    url?: string;
-    title?: string;
-    content: string;
-}
-interface LexiconSelectedChunk {
-    url?: string;
-    title?: string;
-    content: string;
-    score: number;
-    sourceType?: 'content' | 'result';
-}
-interface LexiconSearchResult {
-    url: string;
-    title?: string;
-    snippet: string;
-}
-interface LexiconSelectInput {
-    query: string;
-    documents: LexiconSourceDocument[];
-    searchResults?: LexiconSearchResult[];
-    budgetChars?: number;
-    partitionScope?: string;
-}
-interface LexiconSelectResult {
-    chunks: LexiconSelectedChunk[];
-    consideredChunks: number;
-    selectedChunks: number;
-    droppedByThreshold: number;
-    inputChunksDropped: number;
-    pastChunks?: LexiconSelectedChunk[];
-    reusedDocs?: number;
-    storedDocs?: number;
-}
-
 declare const ConsolidationVerdictSchema: z.ZodObject<{
     verdict: z.ZodEnum<{
         merge: "merge";
@@ -908,4 +909,4 @@ declare const videolistSchema: z.ZodObject<{
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 
-export { BLOCKED_IMAGE_HOSTS, BLOCKED_URL_HOSTS, BROWSER_TOOL_NAMES, COGNITION_LIMIT_DEFAULT, COGNITION_LIMIT_MAX, COGNITION_LIMIT_MIN, COGNITION_PURGE_BATCH, type ConsolidationVerdict, ConsolidationVerdictSchema, EPISODE_PROBE_LIMIT_DEFAULT, EPISODE_PROBE_LIMIT_MIN, EPISODE_RECENCY_MIDPOINT_DEFAULT, EPISODE_RECENCY_MIDPOINT_MAX, EPISODE_RECENCY_MIDPOINT_MIN, EPISODE_RECENCY_SCALE_SECONDS_DEFAULT, EPISODE_RECENCY_SCALE_SECONDS_MAX, EPISODE_RECENCY_SCALE_SECONDS_MIN, EPISODE_RECENCY_WEIGHT_DEFAULT, EPISODE_RECENCY_WEIGHT_MAX, EPISODE_RECENCY_WEIGHT_MIN, EPISODE_SCORE_THRESHOLD_DEFAULT, EPISODE_SCORE_THRESHOLD_MAX, EPISODE_SCORE_THRESHOLD_MIN, EPISODE_TAGS, EPISODE_TEXT_LIMIT, ExtractionSchema, HERO_VIDEO_TITLE_ISSUE, INSIGHTS_MAX_PER_TURN, INSIGHT_TAGS, INSIGHT_TEXT_LIMIT, type LexiconSearchResult, type LexiconSelectInput, type LexiconSelectResult, type LexiconSelectedChunk, type LexiconSourceDocument, MEMORY_TOOL_NAMES, type MemoryCognitionProfile, type MemoryEnrichment, MemoryEnrichmentSchema, type MemoryExtraction, type MemoryProfileInsight, type MemoryProfileResponse, NON_PAGE_EXTENSIONS, type ProviderConfig, TOOL_DESCRIPTIONS, TOOL_NAMES, type ToolName, VARIANT_NAMES, type VariantName, cardSchema, categorizeTools, clampCognitionLimit, clampEpisodeProbeLimit, clampEpisodeRecencyMidpoint, clampEpisodeRecencyScaleSeconds, clampEpisodeRecencyWeight, clampEpisodeScoreThreshold, compareSchema, createTextItemSchema, deriveSchemaKeys, describeSchema, discardedReferenceSchema, formatZodIssues, galleryItemSchema, hasBlockedImageHost, heroVideoHasTitle, imagelistSchema, internationalCoverageSchema, isAllFieldsNullWipe, isPrivateOrLocalhost, isTrustedImageUrl, isTrustedUrl, markerSchema, memoryProfileResponseSchema, mergeCognitionProfiles, normalizeInsightPath, ocrSchema, parseStoredProfile, productSchema, referenceGalleryItemSchema, referenceLineSchema, relatedStorySchema, safeMediaUrl, safeMediaUrlOrEmpty, safeUrl, safeVideoUrl, safeVideoUrlOrEmpty, shoplistSchema, sourceSchema, stockmarketItemSchema, stockmarketListSchema, summarySchema, videoGalleryItemSchema, videolistSchema };
+export { BLOCKED_IMAGE_HOSTS, BLOCKED_URL_HOSTS, BROWSER_TOOL_NAMES, COGNITION_LIMIT_DEFAULT, COGNITION_LIMIT_MAX, COGNITION_LIMIT_MIN, COGNITION_PURGE_BATCH, type ConsolidationVerdict, ConsolidationVerdictSchema, EPISODE_PROBE_LIMIT_DEFAULT, EPISODE_PROBE_LIMIT_MIN, EPISODE_RECENCY_MIDPOINT_DEFAULT, EPISODE_RECENCY_MIDPOINT_MAX, EPISODE_RECENCY_MIDPOINT_MIN, EPISODE_RECENCY_SCALE_SECONDS_DEFAULT, EPISODE_RECENCY_SCALE_SECONDS_MAX, EPISODE_RECENCY_SCALE_SECONDS_MIN, EPISODE_RECENCY_WEIGHT_DEFAULT, EPISODE_RECENCY_WEIGHT_MAX, EPISODE_RECENCY_WEIGHT_MIN, EPISODE_SCORE_THRESHOLD_DEFAULT, EPISODE_SCORE_THRESHOLD_MAX, EPISODE_SCORE_THRESHOLD_MIN, EPISODE_TAGS, EPISODE_TEXT_LIMIT, type EncyclopediaSearchResult, type EncyclopediaSelectInput, type EncyclopediaSelectResult, type EncyclopediaSelectedChunk, type EncyclopediaSourceDocument, ExtractionSchema, HERO_VIDEO_TITLE_ISSUE, INSIGHTS_MAX_PER_TURN, INSIGHT_TAGS, INSIGHT_TEXT_LIMIT, MEMORY_TOOL_NAMES, type MemoryCognitionProfile, type MemoryEnrichment, MemoryEnrichmentSchema, type MemoryExtraction, type MemoryProfileInsight, type MemoryProfileResponse, NON_PAGE_EXTENSIONS, type ProviderConfig, TOOL_DESCRIPTIONS, TOOL_NAMES, type ToolName, VARIANT_NAMES, type VariantName, cardSchema, categorizeTools, clampCognitionLimit, clampEpisodeProbeLimit, clampEpisodeRecencyMidpoint, clampEpisodeRecencyScaleSeconds, clampEpisodeRecencyWeight, clampEpisodeScoreThreshold, compareSchema, createTextItemSchema, deriveSchemaKeys, describeSchema, discardedReferenceSchema, formatZodIssues, galleryItemSchema, hasBlockedImageHost, heroVideoHasTitle, imagelistSchema, internationalCoverageSchema, isAllFieldsNullWipe, isPrivateOrLocalhost, isTrustedImageUrl, isTrustedUrl, markerSchema, memoryProfileResponseSchema, mergeCognitionProfiles, normalizeInsightPath, ocrSchema, parseStoredProfile, productSchema, referenceGalleryItemSchema, referenceLineSchema, relatedStorySchema, safeMediaUrl, safeMediaUrlOrEmpty, safeUrl, safeVideoUrl, safeVideoUrlOrEmpty, shoplistSchema, sourceSchema, stockmarketItemSchema, stockmarketListSchema, summarySchema, videoGalleryItemSchema, videolistSchema };

package/dist/tools/index.d.ts

@@ -401,6 +401,11 @@ interface MemoryPoint {
     path?: string;
     createdAt: string;
     score?: number;
+    isConsolidated?: boolean;
+    isReflected?: boolean;
+    isFriction?: boolean;
+    superseded?: boolean;
+    supersededBy?: string;
 }
 
 interface MemoryPartitionRecallDeps {

package/dist/tools/index.mjs

@@ -261,6 +261,21 @@ function tbsSizeLabelForPixels(pixels) {
   return selected.label;
 }
 
+// src/tools/bright-data/helpers/map-bright-data-image-result.helper.ts
+function mapBrightDataImageResult(r) {
+  return {
+    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: ""
+  };
+}
+
 // src/tools/bright-data/image-search.tool.ts
 function createBrightDataImageSearch(deps) {
   return tool({
@@ -304,17 +319,7 @@ function createBrightDataImageSearch(deps) {
           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) => {
+        const results = images.map(mapBrightDataImageResult).filter((r) => {
           if (!isTrustedImageUrl(r.imageUrl)) return false;
           const w = r.width ?? 0;
           const h = r.height ?? 0;
@@ -336,6 +341,20 @@ var brightDataNewsSearchSchema = z.object({
   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/bright-data/helpers/map-bright-data-news-result.helper.ts
+function mapBrightDataNewsResult(r) {
+  return {
+    title: r.title,
+    snippet: r.description || "",
+    url: r.link,
+    source: r.source || SOURCE,
+    date: r.date || "",
+    imageUrl: r.image_url || ""
+  };
+}
+
+// src/tools/bright-data/news-search.tool.ts
 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,
@@ -361,14 +380,7 @@ function createBrightDataNewsSearch(deps) {
         });
         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 || ""
-        }));
+        const results = news.map(mapBrightDataNewsResult);
         deps.logger.log(`Bright Data news returned ${results.length} results for "${query}"`);
         return { results };
       } catch (err) {
@@ -385,6 +397,23 @@ var brightDataPlacesSearchSchema = z.object({
   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)")
 });
+
+// src/tools/bright-data/helpers/map-bright-data-place-result.helper.ts
+function mapBrightDataPlaceResult(r) {
+  return {
+    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 || ""
+  };
+}
+
+// src/tools/bright-data/places-search.tool.ts
 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").',
@@ -415,17 +444,7 @@ function createBrightDataPlacesSearch(deps) {
           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 || ""
-        }));
+        const results = places.map(mapBrightDataPlaceResult);
         return { results };
       } catch (err) {
         deps.logger.warn(`Bright Data places search failed for "${query}": ${String(err)}`);
@@ -439,6 +458,22 @@ var brightDataShoppingSearchSchema = z.object({
   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)")
 });
+
+// src/tools/bright-data/helpers/map-bright-data-shopping-result.helper.ts
+function mapBrightDataShoppingResult(r) {
+  return {
+    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
+  };
+}
+
+// src/tools/bright-data/shopping-search.tool.ts
 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.',
@@ -469,16 +504,7 @@ function createBrightDataShoppingSearch(deps) {
           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
-        }));
+        const results = shopping.map(mapBrightDataShoppingResult);
         return { results };
       } catch (err) {
         deps.logger.warn(`Bright Data shopping search failed for "${query}": ${String(err)}`);
@@ -494,6 +520,24 @@ var brightDataVideoSearchSchema = z.object({
   lang: z.string().optional().describe("Two-letter ISO language code for result preference (e.g. en, de, ja)")
 });
 
+// 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/helpers/build-youtube-thumbnail-url.helper.ts
 var YOUTUBE_ID_PATTERN = /^[A-Za-z0-9_-]{11}$/;
 function extractYoutubeVideoId(url) {
@@ -521,22 +565,21 @@ function buildYoutubeThumbnailUrl(url) {
   return id ? `https://i.ytimg.com/vi/${id}/maxresdefault.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/helpers/map-bright-data-video-result.helper.ts
+function mapBrightDataVideoResult(r) {
+  return {
+    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
+  };
 }
 
 // src/tools/bright-data/video-search.tool.ts
@@ -571,19 +614,7 @@ function createBrightDataVideoSearch(deps) {
         });
         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
-        }));
+        const results = videos.map(mapBrightDataVideoResult);
         deps.logger.log(`Bright Data video search returned ${results.length} results for "${searchQuery}"`);
         return { results };
       } catch (err) {
@@ -598,6 +629,18 @@ var brightDataWebSearchSchema = z.object({
   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/bright-data/helpers/map-bright-data-web-result.helper.ts
+function mapBrightDataWebResult(r) {
+  return {
+    title: r.title,
+    snippet: r.description || "",
+    url: r.link,
+    source: SOURCE
+  };
+}
+
+// src/tools/bright-data/web-search.tool.ts
 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,
@@ -625,12 +668,7 @@ function createBrightDataWebSearch(deps) {
           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
-        }));
+        const results = organic.map(mapBrightDataWebResult);
         deps.logger.log(`Bright Data returned ${results.length} results for "${query}"`);
         return { results };
       } catch (err) {
@@ -705,6 +743,16 @@ function pickMerchantResult(results, storeToken) {
   return void 0;
 }
 
+// src/tools/helpers/apply-resolved-merchant-url.helper.ts
+function applyResolvedMerchantUrl(offer, merchantUrlByLink) {
+  return merchantUrlByLink.has(offer.link) ? { ...offer, link: merchantUrlByLink.get(offer.link) } : offer;
+}
+
+// src/tools/helpers/map-organic-entry-to-url.helper.ts
+function mapOrganicEntryToUrl(entry) {
+  return { url: entry.link };
+}
+
 // src/tools/helpers/store-host-token.helper.ts
 var NON_IDENTITY_TOKENS = /* @__PURE__ */ new Set([
   // company/legal forms
@@ -772,30 +820,9 @@ 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
+// src/tools/helpers/resolve-offer-merchant-url.helper.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;
@@ -819,14 +846,33 @@ async function fetchMerchantUrl(offer, deps) {
     );
     if (!res.ok) return void 0;
     const data = await res.json();
-    return pickMerchantResult(
-      (data.organic ?? []).map((entry) => ({ url: entry.link })),
-      token
-    );
+    return pickMerchantResult((data.organic ?? []).map(mapOrganicEntryToUrl), token);
   } catch {
     return void 0;
   }
 }
+async function resolveOfferMerchantUrl(offer, deps) {
+  return {
+    offer,
+    merchantUrl: await fetchMerchantUrl(offer, deps)
+  };
+}
+
+// src/tools/helpers/serper-shop-links.ts
+var MAX_LINK_RESOLUTIONS = 12;
+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((offer) => resolveOfferMerchantUrl(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) => applyResolvedMerchantUrl(offer, merchantUrlByLink));
+}
 var variantRequestSchema = z.object({});
 function createVariantRequestTool(variant) {
   const descriptions = {
@@ -950,7 +996,8 @@ function createMemoryPartitionRecallTool(deps) {
       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}`;
+        const contested = hit.isFriction ? " \u2014 \u26A0 CONTESTED (an open conflict exists; treat with caution)" : "";
+        return `- "${hit.text}" \u2014 stated by ${who}${when}${contested}`;
       });
       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")}`;
@@ -1000,6 +1047,18 @@ var serperBusinessReviewsSearchSchema = z.object({
   lang: z.string().optional().describe("Two-letter ISO language code for result preference (e.g. en, de, ja)")
 });
 
+// src/tools/serper/helpers/map-serper-review-result.helper.ts
+function mapSerperReviewResult(r, placeName) {
+  return {
+    author: r.user?.name || "",
+    snippet: r.snippet || "",
+    rating: r.rating,
+    date: r.isoDate || r.date || "",
+    likes: r.likes ?? 0,
+    place: placeName
+  };
+}
+
 // src/tools/serper/serper.constants.ts
 var HEADERS = (apiKey) => ({
   "X-API-KEY": apiKey,
@@ -1053,14 +1112,7 @@ function createSerperBusinessReviewsSearch(deps) {
         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
-      }));
+      const results = data.reviews.map((r) => mapSerperReviewResult(r, placeName));
       return {
         results,
         place: data.placeInfo ? {
@@ -1085,6 +1137,21 @@ var serperImageSearchSchema = z.object({
   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/tools/serper/helpers/map-serper-image-result.helper.ts
+function mapSerperImageResult(r) {
+  return {
+    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 || ""
+  };
+}
+
+// src/tools/serper/image-search.tool.ts
 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,
@@ -1131,15 +1198,7 @@ function createSerperImageSearch(deps) {
         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) => {
+      const results = data.images.map(mapSerperImageResult).filter((r) => {
         if (!isTrustedImageUrl(r.imageUrl)) return false;
         const w = r.width ?? 0;
         const h = r.height ?? 0;
@@ -1157,6 +1216,20 @@ var serperNewsSearchSchema = z.object({
   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/serper/helpers/map-serper-news-result.helper.ts
+function mapSerperNewsResult(r) {
+  return {
+    title: r.title,
+    snippet: r.snippet || "",
+    url: r.link,
+    source: r.source || "",
+    date: r.date || "",
+    imageUrl: r.imageUrl || ""
+  };
+}
+
+// src/tools/serper/news-search.tool.ts
 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,
@@ -1186,14 +1259,7 @@ function createSerperNewsSearch(deps) {
       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 || ""
-      }));
+      const results = data.news.map(mapSerperNewsResult);
       return { results };
     }
   });
@@ -1205,6 +1271,24 @@ var serperPlacesSearchSchema = z.object({
   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)")
 });
+
+// src/tools/serper/helpers/map-serper-place-result.helper.ts
+function mapSerperPlaceResult(r) {
+  return {
+    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 || ""
+  };
+}
+
+// src/tools/serper/places-search.tool.ts
 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").',
@@ -1235,18 +1319,7 @@ function createSerperPlacesSearch(deps) {
         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 || ""
-      }));
+      const results = data.places.map(mapSerperPlaceResult);
       return { results };
     }
   });
@@ -1258,6 +1331,22 @@ var serperShoppingSearchSchema = z.object({
   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)")
 });
+
+// src/tools/serper/helpers/map-serper-shopping-result.helper.ts
+function mapSerperShoppingResult(r) {
+  return {
+    title: r.title,
+    price: r.price || "",
+    link: r.link || "",
+    source: r.source || "",
+    imageUrl: r.imageUrl || "",
+    delivery: r.delivery || "",
+    rating: r.rating,
+    ratingCount: r.ratingCount
+  };
+}
+
+// src/tools/serper/shopping-search.tool.ts
 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.',
@@ -1290,16 +1379,7 @@ function createSerperShoppingSearch(deps) {
         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
-      }));
+      const results = data.shopping.map(mapSerperShoppingResult);
       return {
         results: await resolveSerperShopOfferLinks(results, {
           apiKey: cfg.apiKey,
@@ -1333,6 +1413,29 @@ function repairVideoLink(link) {
   return CONTAMINATION_PATTERN.test(link) ? void 0 : link;
 }
 
+// src/tools/serper/helpers/map-serper-video-result.helper.ts
+function mapSerperVideoResult(input) {
+  const { r, link } = input;
+  return {
+    title: r.title,
+    link,
+    // Keep the provider's original link when it had to be repaired —
+    // auditability for provider-side payload corruption.
+    ...link !== r.link ? { originalLink: 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.
+    // maxresdefault is not guaranteed to exist; consumers degrade to
+    // hqdefault/mqdefault on failure.
+    thumbnailUrl: buildYoutubeThumbnailUrl(link) ?? "",
+    source: r.source || "",
+    views: r.views ?? 0
+  };
+}
+
 // src/tools/serper/video-search.tool.ts
 function createSerperVideoSearch(deps) {
   return tool({
@@ -1368,24 +1471,7 @@ function createSerperVideoSearch(deps) {
       const results = data.videos.flatMap((r) => {
         const link = repairVideoLink(r.link);
         return link ? [{ r, link }] : [];
-      }).slice(0, num).map(({ r, link }) => ({
-        title: r.title,
-        link,
-        // Keep the provider's original link when it had to be repaired —
-        // auditability for provider-side payload corruption.
-        ...link !== r.link ? { originalLink: 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.
-        // maxresdefault is not guaranteed to exist; consumers degrade to
-        // hqdefault/mqdefault on failure.
-        thumbnailUrl: buildYoutubeThumbnailUrl(link) ?? "",
-        source: r.source || "",
-        views: r.views ?? 0
-      }));
+      }).slice(0, num).map(mapSerperVideoResult);
       deps.logger.log(`Serper.dev Video search returned ${results.length} results for "${searchQuery}"`);
       return { results };
     }
@@ -1396,6 +1482,18 @@ var serperWebSearchSchema = z.object({
   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/serper/helpers/map-serper-web-result.helper.ts
+function mapSerperWebResult(r) {
+  return {
+    title: r.title,
+    snippet: r.snippet || "",
+    url: r.link,
+    source: "serper"
+  };
+}
+
+// src/tools/serper/web-search.tool.ts
 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,
@@ -1430,12 +1528,7 @@ function createSerperWebSearch(deps) {
         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"
-      }));
+      const results = data.organic.map(mapSerperWebResult);
       deps.logger.log(`Serper.dev returned ${results.length} results for "${query}"`);
       return { results };
     }
@@ -1550,6 +1643,35 @@ function createWebFetchTool() {
     }
   });
 }
+
+// src/tools/youtube/helpers/map-youtube-video-result.helper.ts
+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)}`;
+}
+function mapYoutubeVideoResult(item, stats) {
+  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
+  };
+}
 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)"),
@@ -1580,15 +1702,6 @@ async function readErrorReason(res) {
     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",
@@ -1668,24 +1781,7 @@ function createYoutubeVideoSearch(deps) {
         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
-        };
-      });
+      const results = items.map((item) => mapYoutubeVideoResult(item, stats));
       deps.logger.log(`YouTube video search returned ${results.length} results for "${query}"`);
       return { results };
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@triplef/agent",
   "description": "tripleF (3F) agent domain — structured-output schemas, prompt builders, and model tools shared across the apps.",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "packageManager": "pnpm@11.25.0",
   "license": "MIT",
   "type": "module",
@@ -60,7 +60,7 @@
     "turndown": "^7.2.4"
   },
   "peerDependencies": {
-    "ai": "^7.0.85",
+    "ai": "^7.0.87",
     "zod": "^4.5.4"
   },
   "peerDependenciesMeta": {
@@ -92,7 +92,7 @@
     "ts-unused-exports": "^11.0.1",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.68.0",
+    "typescript-eslint": "^8.69.0",
     "vitest": "^4.1.11"
   }
 }