@finchagentic/mcp 4.7.1 → 4.7.3

package/dist/tools/deep-research-synthesis.js

@@ -0,0 +1,343 @@
+"use strict";
+// Report synthesis: source classification, the main LLM synthesis call,
+// citation-density retry, and the structural/citation quality checks that
+// gate whether a report ships as-is or gets one retry.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifySource = classifySource;
+exports.synthesize = synthesize;
+exports.extractLiveCitations = extractLiveCitations;
+exports.measureCitationDensity = measureCitationDensity;
+exports.validateReportStructure = validateReportStructure;
+exports.formatLiveCitations = formatLiveCitations;
+const llm_js_1 = require("../llm.js");
+const convex_js_1 = require("../convex.js");
+const enrichment_router_js_1 = require("../enrichment-router.js");
+const memory_js_1 = require("./memory.js");
+const deep_research_text_js_1 = require("./deep-research-text.js");
+function classifySource(score) {
+    if (score >= 3)
+        return "primary";
+    if (score === 2)
+        return "expert";
+    if (score === 1)
+        return "secondary";
+    if (score < 0)
+        return "market";
+    return "unclassified";
+}
+async function synthesize(query, sources, isFinal, liveSearch, priorContext, freshMode, angles, criticNotes) {
+    const sourceBlocks = sources
+        .map((s) => {
+        const dateNote = s.publishedAt ? ` (published ${s.publishedAt.slice(0, 10)})` : "";
+        const classNote = s.class !== "unclassified" ? ` [${s.class}]` : "";
+        return `[${s.n}]${classNote} ${s.title} - ${s.domain}${dateNote}\nURL: ${s.url}\n\n${s.excerpt}`;
+    })
+        .join("\n\n---\n\n");
+    // Multi-domain enrichment - auto-detect topic (crypto/tech/academic/general)
+    // and pull live primary-source data in parallel. Crypto routes to DefiLlama
+    // + CoinGecko; tech to HackerNews + GitHub; academic to arXiv; general to
+    // Wikipedia. The combined block prepends to source blocks and is tagged
+    // AUTHORITATIVE LIVE DATA so the LLM treats those numbers as ground truth.
+    const enrichment = isFinal ? await (0, enrichment_router_js_1.enrichQuery)(query) : { context: "", hasData: false, domains: [] };
+    // Profile + memory auto-injection - only on final synthesis.
+    // Profile: persistent identity/business/state from vault.
+    // Memory: top relevant memories for this query (personalizes report framing).
+    // Both run in parallel; either can fail without blocking synthesis.
+    let profileContext = "";
+    let memoryContext = "";
+    if (isFinal) {
+        const [profileData, memHits] = await Promise.allSettled([
+            (0, convex_js_1.callConvex)("/vault/profile-context?maxChars=1200", "GET", undefined, "vault_read"),
+            (0, memory_js_1.searchSupermemory)(query, 4),
+        ]);
+        if (profileData.status === "fulfilled") {
+            profileContext = (profileData.value?.context ?? "").trim();
+        }
+        if (memHits.status === "fulfilled" && memHits.value.length > 0) {
+            memoryContext = memHits.value
+                .map((r) => {
+                const title = r.metadata?.title ? `[${r.metadata.title}] ` : "";
+                return `- ${title}${r.content.slice(0, 200).replace(/\n/g, " ")}`;
+            })
+                .join("\n");
+        }
+    }
+    const liveSearchNote = liveSearch
+        ? `\n\nIMPORTANT - Real-time augmentation:
+You have Live Search enabled. In addition to the numbered sources above, you have access to **real-time results from ${liveSearch.sources.join(", ")}**. Use them to:
+1. Verify recent claims (last ${liveSearch.fromDate ? "from " + liveSearch.fromDate : "few weeks"})
+2. Add fresh data points the static sources may have missed
+3. Surface X (Twitter) posts when the topic is moving quickly
+4. Pull current numbers when the static sources are dated
+
+CITATION RULE for Live Search content:
+- Numbered sources [N] = static scraped sources at top of prompt
+- Real-time content from Live Search: cite inline as **(X post)** or **(news, [outlet])** WITHOUT [N] numbering - they'll be appended to the Sources section automatically
+- If a Live Search result contradicts a static source, FLAG it as "(real-time conflicts with [N])"`
+        : "";
+    const finalSections = isFinal
+        ? `## TL;DR
+2-3 sentences answering the question directly. No hedging unless evidence demands it.
+
+## At a Glance
+A Markdown table summarizing 4-8 key metrics, dimensions, or status indicators from the sources. Format:
+| Dimension | Value / Status | Source |
+|---|---|---|
+| (example) Production adoption | 57% have agents in production | [3] |
+
+Use tables whenever you have:
+- Comparison data (X vs Y vs Z)
+- Status snapshots (multiple metrics at one point in time)
+- Rankings or scorecards
+- Dollar amounts, percentages, dates side-by-side
+
+This section is REQUIRED whenever the sources contain quantitative data. Skip ONLY if the topic is purely qualitative.
+
+## Key Findings
+- 6-10 substantive bullets, each citing source numbers like [1] or [2,4]
+- Lead with specific named entities, dollar amounts, percentages, dates - not generalities
+- Mix angles - definition, current state, comparisons, criticisms
+- Tag each bullet with a confidence level at the end: \`(high)\` / \`(medium)\` / \`(low)\`
+- "high" means primary sources or strong consensus; "low" means single source or contested
+
+## Analysis
+3-5 paragraphs synthesizing the sources. Connect findings, note tensions and gaps, distinguish correlation from causation. Use inline citations throughout - every numerical claim or named entity must carry a [N].
+
+## Counterevidence & Limitations
+- 2-4 bullets listing what could change the conclusion: weak sources, missing data, conflicting findings, age of evidence
+- This section is required - never skip it
+
+## Follow-up Questions
+- 3-5 questions a curious reader would ask after reading this report
+- Make them concrete and answerable, not philosophical`
+        : `## Draft Summary
+Single paragraph synthesis covering the main findings from sources, with inline citations.`;
+    const profileBlock = profileContext
+        ? `\n\n<user_profile>\n${profileContext}\n</user_profile>\n`
+        : "";
+    const memoryBlock = memoryContext
+        ? `\n\n<user_memory>\nStored knowledge about this user — use to frame the report toward their known interests, not to fabricate facts:\n${memoryContext}\n</user_memory>\n`
+        : "";
+    const sys = `You are a senior analyst writing a structured research report from numbered web sources.
+
+${(0, enrichment_router_js_1.todayContext)()}${profileBlock}${memoryBlock}
+
+OUTPUT FORMAT (strict - exact Markdown sections, in this order):
+
+# {short concrete title - max 10 words}
+
+${finalSections}
+
+SOURCE CLASS TAGGING (mandatory in Key Findings):
+Each source in the list above is labeled [primary] / [expert] / [secondary] / [market].
+- [primary]: official docs, .gov/.edu, protocol data (DefiLlama, CoinGecko, etherscan), peer-reviewed
+- [expert]: named researchers, audit reports, tier-1 financial press (Reuters, FT, Bloomberg)
+- [secondary]: crypto media, newsletters, Wikipedia, GitHub
+- [market]: X/Twitter, Reddit, Substack, prediction markets - sentiment, not fact
+
+TAG RULES:
+- Every Key Findings bullet must end with the source class of its strongest citation, e.g. "[primary]" or "[market]"
+- Example: "Aerodrome TVL reached $2.1B in June 2026 [3] [primary]"
+- If a bullet's evidence mixes classes, use the LOWEST class: one Reddit citation drags the whole bullet to "[market]"
+
+CONTRADICTION RULES (mandatory):
+- When two sources disagree on a fact, do NOT average them. Surface the conflict explicitly:
+  "Source [N] says X; source [M] says not-X - reconciliation: ..."
+- Put irreconcilable contradictions in Counterevidence & Limitations, not Key Findings
+- A single uncontested source is flagged: "(single source [N])"
+
+CITATION DENSITY RULES:
+- Every numerical claim (percentage, dollar amount, count, date) MUST carry [N]
+- Every named entity (company, product, framework, person) MUST carry [N] on first mention
+- Target: at least 1 citation per 50 words in Key Findings and Analysis
+- Note source dates when relevant - older sources may be stale
+
+STYLE RULES:
+- Be specific: numbers, names, dates over vague claims
+- Lead with concrete entities, not abstract concepts
+- Tables > bullets when comparing dimensions
+- No filler ("it is important to note", "in conclusion", "in today's world", "navigate the landscape")
+- No hedging when evidence is strong; no false confidence when it's weak
+- Don't write a Sources section - that gets appended automatically`;
+    const freshBlock = freshMode && isFinal
+        ? `
+
+⏱ FRESH MODE active - today is ${(0, deep_research_text_js_1.todayISO)()}:
+- Prioritize claims dated within the last 30 days. If a source is older, only cite it if it's primary evidence (data, official statement).
+- In the At a Glance table, include a "Date" column showing the publish date for each metric.
+- In Key Findings, prefix each bullet with the source's publish date in brackets: [2026-MM-DD] Finding text [N].
+- In Counterevidence, flag any claim whose evidence is older than 60 days as "(potentially stale).".`
+        : "";
+    const continuationBlock = priorContext && isFinal
+        ? `
+
+PRIOR REPORT (you are CONTINUING this research, not starting fresh):
+
+\`\`\`
+${priorContext.content.slice(0, 3500)}
+\`\`\`
+
+CONTINUATION RULES:
+- Start the TL;DR with: "Update to prior report \`${priorContext.key}\` -" followed by the new takeaway.
+- The "At a Glance" table must include a column "Δ since prior" showing what changed.
+- Key Findings must mark each bullet with: \`(NEW)\` for genuinely new info, \`(UPDATED)\` for changed numbers/positions, or \`(CONFIRMED)\` for points the new sources reinforce.
+- Counterevidence section must explicitly say which prior claims are now weaker.
+- Follow-up Questions must build on the prior report's open questions if they're still relevant.
+
+Do not re-explain background already in the prior report. Assume the reader read it.`
+        : "";
+    const enrichmentBlock = enrichment.hasData
+        ? `\n\n${enrichment.context}\n\n`
+        : "";
+    // Specialist angles - when present, tell the synthesizer to mirror this
+    // structure in the report (Key Findings organized by angle, At a Glance
+    // table dimensions match the angles). Without this, the model blends
+    // every angle into a homogeneous narrative.
+    const anglesBlock = isFinal && angles && angles.length > 0
+        ? `\n\nSPECIALIST ANGLES INVESTIGATED:
+${angles.map((a, i) => `${i + 1}. **${a.label}** - ${a.rationale}`).join("\n")}
+
+Mirror this structure: Key Findings should group bullets by angle (use the angle label as a sub-header), and the At a Glance table dimensions should match the angles.`
+        : "";
+    // Critic notes (deep mode only) - explicit weaknesses surfaced during
+    // the audit pass. The synthesizer must address each one rather than
+    // simply ignoring it. This is the strongest single quality lever.
+    const criticBlock = isFinal && criticNotes && criticNotes.length > 50
+        ? `\n\nCRITIC AUDIT - concrete weaknesses found in the draft. You MUST address each one in the final report (either by revising the claim, surfacing the uncertainty, or providing additional support):
+
+${criticNotes}
+
+If a critic concern can't be resolved with the sources you have, surface it in Counterevidence & Limitations rather than burying it.`
+        : "";
+    const user = `RESEARCH QUESTION: ${query}
+${enrichmentBlock}
+SOURCES:
+${sourceBlocks}${liveSearchNote}${continuationBlock}${freshBlock}${anglesBlock}${criticBlock}
+
+Write the ${isFinal ? "final" : "draft"} report now. Markdown only - no preamble, no postamble.${enrichment.hasData
+        ? `\n\nIMPORTANT: The AUTHORITATIVE LIVE DATA block at the top contains current numbers from primary APIs (DefiLlama, CoinGecko). Lead with these numbers when they exist - they override any conflicting figures in the scraped sources below. Cite them as [DefiLlama] or [CoinGecko].`
+        : ""}`;
+    // Research synthesis uses FINCH_RESEARCH_MODEL when set. Default is
+    // `grok-4.3` - when Bankr is the active gateway this routes to Grok 4.3
+    // through Bankr (Grok handles fresh data better; Claude is the safer
+    // pick for reasoning, JSON, code). Override via env or pass the same
+    // model string to FINCH_MODEL to bypass.
+    const researchModel = process.env.FINCH_RESEARCH_MODEL ?? "grok-4.3";
+    // Deep mode (critic notes present, or the 5-angle planner ran) produces a
+    // longer report than the standard 6-section template - a fixed 4000-token
+    // budget was cutting deep reports off mid-sentence around risk #6-7 of 13+.
+    const isDeepMode = !!criticNotes || (angles?.length ?? 0) >= 5;
+    const finalTokens = isDeepMode ? 7000 : 4000;
+    const raw = await (0, llm_js_1.callLLM)(sys, user, isFinal ? finalTokens : 2000, [], 90000, { liveSearch, model: researchModel });
+    const { content: report, liveCitations } = extractLiveCitations(raw);
+    // Citation density check - only for final reports. If the report has many
+    // numerical claims but very few [N] citations, retry once with a stricter
+    // instruction. Cheap insurance against lazy synthesis.
+    if (!isFinal)
+        return { report, liveCitations };
+    const density = measureCitationDensity(report);
+    if (density.numericalClaims >= 5 && density.citations < Math.max(3, density.numericalClaims / 2)) {
+        const retryUser = `${user}
+
+⚠️ Your previous draft had ${density.numericalClaims} numerical claims but only ${density.citations} [N] citations. That ratio is too low. Rewrite with stricter citation density: every percentage, dollar amount, count, date, and named entity must carry [N]. Use the At a Glance table to anchor the key metrics.`;
+        try {
+            const rawRetry = await (0, llm_js_1.callLLM)(sys, retryUser, finalTokens, [], 90000, { liveSearch, model: researchModel });
+            const { content: retryReport, liveCitations: retryCitations } = extractLiveCitations(rawRetry);
+            return { report: retryReport, liveCitations: retryCitations.length > 0 ? retryCitations : liveCitations };
+        }
+        catch {
+            return { report, liveCitations };
+        }
+    }
+    return { report, liveCitations };
+}
+// Strip the GROK_LIVE_CITATIONS sentinel block (added by callGrok when Live
+// Search ran) and return the citation URLs separately.
+function extractLiveCitations(raw) {
+    const match = raw.match(/<!--GROK_LIVE_CITATIONS\n([\s\S]*?)\nGROK_LIVE_CITATIONS-->/);
+    if (!match)
+        return { content: raw, liveCitations: [] };
+    const urls = match[1].split("\n").map((u) => u.trim()).filter(Boolean);
+    return { content: raw.replace(match[0], "").trimEnd(), liveCitations: urls };
+}
+function measureCitationDensity(report) {
+    // Numerical claims: percentages, dollar amounts, large counts, years
+    const percentages = report.match(/\d+(?:\.\d+)?\s*%/g) ?? [];
+    const dollars = report.match(/\$\s*\d+(?:\.\d+)?\s*(?:[KkMmBbTt]|million|billion|trillion)?/g) ?? [];
+    const counts = report.match(/\b\d{1,3}(?:,\d{3})+\b/g) ?? [];
+    const years = report.match(/\b(?:19|20)\d{2}\b/g) ?? [];
+    const numericalClaims = percentages.length + dollars.length + counts.length + years.length;
+    // Inline citations
+    const citationsMatches = report.match(/\[\d+(?:\s*,\s*\d+)*\]/g) ?? [];
+    const citations = citationsMatches.length;
+    // Capitalized multi-word entities (proper nouns) - proxy for named entities
+    const namedEntities = (report.match(/\b[A-Z][a-z]+(?:[A-Z][a-z]+|\s+[A-Z][a-z]+)\b/g) ?? []).length;
+    return { numericalClaims, citations, namedEntities };
+}
+// Output structure validation - returns the names of any failed checks.
+// Used to decide whether the synthesis output is worth retrying.
+function validateReportStructure(report) {
+    const issues = [];
+    // 1. "At a Glance" section with a Markdown table
+    const atGlance = report.match(/##\s*At a Glance[\s\S]*?(?=\n##|\n#|$)/i);
+    if (!atGlance) {
+        issues.push("missing-at-a-glance");
+    }
+    else {
+        // Markdown table = at least 2 lines that start with `|`
+        const tableLines = (atGlance[0].match(/^\|.+\|.+$/gm) ?? []).length;
+        if (tableLines < 2)
+            issues.push("at-a-glance-no-table");
+    }
+    // 2. Counterevidence section must exist and be non-trivial
+    const counter = report.match(/##\s*Counterevidence[\s\S]*?(?=\n##|\n#|$)/i);
+    if (!counter) {
+        issues.push("missing-counterevidence");
+    }
+    else {
+        const counterText = counter[0].replace(/##.*$/m, "").trim();
+        if (counterText.length < 80)
+            issues.push("counterevidence-too-short");
+    }
+    // 3. Citation density - every 200 words should have at least 1 [N] citation
+    // in the Key Findings + Analysis sections
+    const findingsAndAnalysis = report
+        .replace(/^#.+$/m, "") // strip title
+        .replace(/##\s*(TL;DR|At a Glance|Sources|Follow-up Questions)[\s\S]*?(?=\n##|\n#|$)/gi, "")
+        .replace(/##\s*Counterevidence[\s\S]*?(?=\n##|\n#|$)/gi, "");
+    const wordCount = findingsAndAnalysis.split(/\s+/).filter(Boolean).length;
+    const citationCount = (findingsAndAnalysis.match(/\[\d+(?:\s*,\s*\d+)*\]/g) ?? []).length;
+    if (wordCount >= 200 && citationCount < Math.floor(wordCount / 200)) {
+        issues.push("low-citation-density");
+    }
+    // 4. Follow-up Questions section present
+    if (!report.match(/##\s*Follow-up Questions/i)) {
+        issues.push("missing-followups");
+    }
+    return issues;
+}
+// Group Live Search citations by source type (X, news, web) for readability.
+function formatLiveCitations(urls) {
+    const groups = { "X (Twitter)": [], "News": [], "Web": [] };
+    for (const url of urls) {
+        if (/x\.com|twitter\.com/i.test(url))
+            groups["X (Twitter)"].push(url);
+        else if (/(reuters|apnews|bbc|cnbc|bloomberg|theverge|techcrunch|wsj|ft|nytimes|coindesk|axios|economist)\.com/i.test(url))
+            groups["News"].push(url);
+        else
+            groups["Web"].push(url);
+    }
+    const lines = [];
+    for (const [label, list] of Object.entries(groups)) {
+        if (list.length === 0)
+            continue;
+        lines.push(`**${label}** (${list.length}):`);
+        for (const url of list.slice(0, 8)) {
+            lines.push(`- ${url}`);
+        }
+        if (list.length > 8)
+            lines.push(`- _…and ${list.length - 8} more_`);
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+}

package/dist/tools/deep-research-text.js

@@ -0,0 +1,158 @@
+"use strict";
+// Text utilities: JSON extraction, domain scoring, excerpt selection, query
+// terms, and source ranking/dedup - the parts of the pipeline with no LLM
+// or network call.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeParseJson = safeParseJson;
+exports.domainOf = domainOf;
+exports.tierBonus = tierBonus;
+exports.chunkMarkdown = chunkMarkdown;
+exports.chunkRelevance = chunkRelevance;
+exports.pickBestExcerpt = pickBestExcerpt;
+exports.extractQueryTerms = extractQueryTerms;
+exports.todayISO = todayISO;
+exports.currentYearMonth = currentYearMonth;
+exports.buildSearchTermsForLinking = buildSearchTermsForLinking;
+exports.extractVaultKeyFromHit = extractVaultKeyFromHit;
+exports.rankAndDedupe = rankAndDedupe;
+const deep_research_constants_js_1 = require("./deep-research-constants.js");
+function safeParseJson(raw, fallback) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch { /* try the next parse strategy */ }
+    const stripped = raw.replace(/^```(?:json)?\n?/m, "").replace(/\n?```$/m, "").trim();
+    try {
+        return JSON.parse(stripped);
+    }
+    catch { /* try the next parse strategy */ }
+    const arrMatch = stripped.match(/\[[\s\S]*\]/);
+    if (arrMatch) {
+        try {
+            return JSON.parse(arrMatch[0]);
+        }
+        catch { /* try the next parse strategy */ }
+    }
+    const objMatch = stripped.match(/\{[\s\S]*\}/);
+    if (objMatch) {
+        try {
+            return JSON.parse(objMatch[0]);
+        }
+        catch { /* try the next parse strategy */ }
+    }
+    return fallback;
+}
+function domainOf(url) {
+    try {
+        return new URL(url).hostname.replace(/^www\./, "");
+    }
+    catch {
+        return "unknown";
+    }
+}
+function tierBonus(url) {
+    for (const [re, bonus] of deep_research_constants_js_1.DOMAIN_TIER_BONUS)
+        if (re.test(url))
+            return bonus;
+    return 0;
+}
+// Split markdown into ~600-char chunks at paragraph boundaries.
+function chunkMarkdown(md, chunkSize = deep_research_constants_js_1.EXCERPT_CHARS_PER_CHUNK) {
+    const paragraphs = md.split(/\n{2,}/).map((p) => p.trim()).filter(Boolean);
+    const chunks = [];
+    let current = "";
+    for (const p of paragraphs) {
+        if (current.length + p.length + 2 <= chunkSize) {
+            current = current ? `${current}\n\n${p}` : p;
+        }
+        else {
+            if (current)
+                chunks.push(current);
+            current = p.slice(0, chunkSize * 2); // very long single paragraph → cap
+        }
+    }
+    if (current)
+        chunks.push(current);
+    return chunks;
+}
+// Score a chunk against the query using term overlap. Cheap, no LLM call.
+function chunkRelevance(chunk, queryTerms) {
+    const lower = chunk.toLowerCase();
+    let score = 0;
+    for (const term of queryTerms) {
+        const occurrences = lower.split(term).length - 1;
+        score += Math.min(occurrences, 5); // cap each term so a spammy page can't win
+    }
+    return score;
+}
+function pickBestExcerpt(md, queryTerms) {
+    const chunks = chunkMarkdown(md);
+    if (chunks.length === 0)
+        return md.slice(0, 1500);
+    const scored = chunks.map((c, i) => ({ c, i, score: chunkRelevance(c, queryTerms) }));
+    scored.sort((a, b) => b.score - a.score);
+    const top = scored.slice(0, deep_research_constants_js_1.EXCERPT_TOP_CHUNKS).sort((a, b) => a.i - b.i);
+    return top.map((t) => t.c).join("\n\n---\n\n");
+}
+function extractQueryTerms(query) {
+    return Array.from(new Set(query
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, " ")
+        .split(/\s+/)
+        .filter((t) => t.length >= 3 && !deep_research_constants_js_1.STOPWORDS.has(t)))).slice(0, 10);
+}
+function todayISO() {
+    return new Date().toISOString().slice(0, 10);
+}
+function currentYearMonth() {
+    const now = new Date();
+    const months = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+    return `${months[now.getMonth()]} ${now.getFullYear()}`;
+}
+// Build a search query for finding related vault entries. Prefer high-signal
+// terms from the user query, dropping common research filler words.
+function buildSearchTermsForLinking(query) {
+    const terms = extractQueryTerms(query);
+    return terms.length > 0 ? terms.join(" ") : query;
+}
+// Extract a vault key from a search hit. The /vault/search endpoint returns
+// semantic memory documents whose metadata may or may not contain a vault key.
+function extractVaultKeyFromHit(hit) {
+    // Heuristic 1: metadata.vaultKey or metadata.key
+    if (hit.metadata?.vaultKey && typeof hit.metadata.vaultKey === "string")
+        return hit.metadata.vaultKey;
+    if (hit.metadata?.key && typeof hit.metadata.key === "string")
+        return hit.metadata.key;
+    // Heuristic 2: content first line matches the vault key path pattern
+    const firstLine = (hit.content ?? "").split("\n", 1)[0];
+    const m = firstLine.match(/^(research|memory|workflow|prompt|execution|file|credential)\/[a-z0-9\-/]+/i);
+    if (m)
+        return m[0];
+    return null;
+}
+function rankAndDedupe(candidates, freshMode) {
+    // Score: search-rank inverse + domain tier bonus. Lower queryRank = higher.
+    // In fresh mode, give news domains an extra +2 boost so recent reporting
+    // ranks above evergreen content.
+    const scored = candidates.map((c) => ({
+        ...c,
+        score: -c.queryRank + tierBonus(c.url) + (freshMode && deep_research_constants_js_1.NEWS_DOMAIN_BOOST_RE.test(c.url) ? 2 : 0),
+        domain: domainOf(c.url),
+    }));
+    scored.sort((a, b) => b.score - a.score);
+    // Domain diversity - cap MAX_PER_DOMAIN sources from same domain
+    const seenDomain = new Map();
+    const seenUrl = new Set();
+    const result = [];
+    for (const c of scored) {
+        if (seenUrl.has(c.url))
+            continue;
+        const count = seenDomain.get(c.domain) ?? 0;
+        if (count >= deep_research_constants_js_1.MAX_PER_DOMAIN)
+            continue;
+        seenUrl.add(c.url);
+        seenDomain.set(c.domain, count + 1);
+        result.push(c);
+    }
+    return result;
+}

package/dist/tools/deep-research-tools.js

@@ -0,0 +1,90 @@
+"use strict";
+// Tool definition + input schema for deep_research. Pure data/validation,
+// no execution logic.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InputSchema = exports.DEEP_RESEARCH_TOOLS = void 0;
+const zod_1 = require("zod");
+exports.DEEP_RESEARCH_TOOLS = [
+    {
+        name: "deep_research",
+        description: "Web research engine: searches, scrapes, ranks and de-duplicates sources, then returns them " +
+            "as a numbered, citable evidence pack for YOU to synthesise. This is the default (mode='sources') " +
+            "and needs no API key. " +
+            "You are the analyst: pass your own sub-queries via `queries` for full control over the angles " +
+            "covered — otherwise they are derived from the topic. " +
+            "Set mode='report' only if you want the server to write the prose itself (requires an LLM key, " +
+            "and you cannot steer the result). " +
+            "Profile-aware, auto-saves to vault, auto-links to related past reports.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Research question. Be specific: 'state of Base chain TVL Q2 2026' beats 'Base chain'.",
+                },
+                queries: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "YOUR sub-queries to search (recommended). You know the topic and the user's intent, so plan " +
+                        "the angles yourself — 3-6 specific queries beat a generic decomposition. Omit to derive them.",
+                },
+                mode: {
+                    type: "string",
+                    enum: ["sources", "report"],
+                    description: "'sources' (default) returns the ranked evidence pack for you to synthesise — no API key needed. " +
+                        "'report' makes the server write the prose (needs an LLM key; you cannot steer it).",
+                },
+                depth: {
+                    type: "string",
+                    enum: ["fast", "standard", "deep"],
+                    description: "fast=flat planner, 3 sub-Qs, ~10 sources (~45s). standard=3 specialist angles, ~14 sources, reflection round (~90s). deep=5 angles + adversarial critic + reflection, ~20 sources (~180s). Default standard.",
+                },
+                focus: {
+                    type: "string",
+                    description: "Optional angle hint - 'technical', 'investment', 'news', 'comparison'. Steers planning.",
+                },
+                continueFrom: {
+                    type: "string",
+                    description: "Vault key of a previous deep_research report to build on. When provided, the planner focuses on UPDATES, GAPS, and NEW developments since that report - not re-treading covered ground. The new report explicitly references and extends the prior findings. Format: 'research/...' (use vault_list type:research to find candidates). This is the multi-session research feature - Perplexity / ChatGPT Deep Research don't have an equivalent.",
+                },
+                freshMode: {
+                    type: "boolean",
+                    description: "Force time-sensitive research mode: planner appends recency hints to sub-queries, source ranking boosts news domains (Reuters, AP, Bloomberg, etc.), and the synthesizer is told to prioritize current/recent claims. Auto-enabled when the query contains time-sensitive keywords (today, latest, breaking, this week, etc.).",
+                },
+                freshDays: {
+                    type: "number",
+                    description: "When freshMode is on, restrict to results from the last N days. Default 14 days. Capped at 90.",
+                },
+                liveSearch: {
+                    type: "boolean",
+                    description: "Enable Grok Live Search - pulls real-time results from X (Twitter), news, web, RSS during synthesis. Only works when Grok is the active LLM provider. Adds ~5-15s per Grok call. Default: auto (on when Grok is active).",
+                },
+                liveSearchSources: {
+                    type: "array",
+                    items: { type: "string", enum: ["web", "x", "news", "rss"] },
+                    description: "Which Live Search sources to pull from. Default: ['web', 'x', 'news']. Only respected when liveSearch is true and Grok is active.",
+                },
+                liveSearchDays: {
+                    type: "number",
+                    description: "Restrict Live Search to results from the last N days (max 365). Useful for time-sensitive queries. Default: no date filter.",
+                },
+                saveToVault: { type: "boolean", description: "Auto-save report to vault (default true)" },
+            },
+            required: ["query"],
+        },
+    },
+];
+exports.InputSchema = zod_1.z.object({
+    query: zod_1.z.string().min(3).max(500),
+    queries: zod_1.z.array(zod_1.z.string().min(3).max(300)).max(12).optional(),
+    mode: zod_1.z.enum(["sources", "report"]).optional(),
+    depth: zod_1.z.enum(["fast", "standard", "deep"]).optional(),
+    focus: zod_1.z.string().max(80).optional(),
+    continueFrom: zod_1.z.string().max(200).optional(),
+    freshMode: zod_1.z.boolean().optional(),
+    freshDays: zod_1.z.number().int().min(1).max(90).optional(),
+    liveSearch: zod_1.z.boolean().optional(),
+    liveSearchSources: zod_1.z.array(zod_1.z.enum(["web", "x", "news", "rss"])).optional(),
+    liveSearchDays: zod_1.z.number().int().min(1).max(365).optional(),
+    saveToVault: zod_1.z.boolean().optional(),
+});