@finchagentic/mcp 4.6.0 → 4.6.2

package/dist/tools/deep-research.js

@@ -1,1421 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEEP_RESEARCH_TOOLS = void 0;
-exports.handleDeepResearch = handleDeepResearch;
-const zod_1 = require("zod");
-const llm_js_1 = require("../llm.js");
-const convex_js_1 = require("../convex.js");
-const signal_gate_js_1 = require("../signal-gate.js");
-const enrichment_router_js_1 = require("../enrichment-router.js");
-const memory_js_1 = require("./memory.js");
-// ─── Constants ────────────────────────────────────────────────────────────────
-const FC_BASE = "https://api.firecrawl.dev/v1";
-const MAX_PER_DOMAIN = 2; // source diversity - cap hits per domain
-const EXCERPT_CHARS_PER_CHUNK = 600;
-const EXCERPT_TOP_CHUNKS = 4; // pick top N relevant chunks per source
-// Quality scoring - higher = more trustworthy primary source
-const DOMAIN_TIER_BONUS = [
-    [/\.gov(\b|\/|$)/i, 4],
-    [/\.edu(\b|\/|$)/i, 3],
-    [/(?:nature|science|nih|arxiv|acm|ieee|sciencedirect)\.(?:org|com)/i, 3],
-    // Crypto primary-source boost - these are the authoritative data sources
-    // for protocol TVL, yields, prices, and on-chain analytics. Rank above
-    // generic news for crypto queries.
-    [/(?:defillama|tokenterminal|coingecko|coinmarketcap|dune|messari|artemis)\.(?:com|fi)/i, 3],
-    [/(?:etherscan|basescan|arbiscan|solscan|polygonscan|optimistic\.etherscan)\.(?:io|com)/i, 2],
-    [/(?:reuters|apnews|bbc|economist|ft|wsj|bloomberg)\.com/i, 2],
-    [/(?:coindesk|theblock|cointelegraph|decrypt|theinformation)\.(?:co|com|io)/i, 1],
-    [/(?:wikipedia|github|stackoverflow)\.(?:org|com)/i, 1],
-    [/(?:medium|substack|reddit|twitter|x)\.com/i, -1],
-];
-// News-domain bonus - applied additionally in fresh mode
-const NEWS_DOMAIN_BOOST_RE = /(?:reuters|apnews|bbc|economist|ft|wsj|bloomberg|cnbc|theverge|techcrunch|axios|coindesk|theinformation|nytimes|guardian|aljazeera)\.com/i;
-// Keywords that signal a time-sensitive query - trigger fresh mode auto.
-const FRESH_TRIGGER_RE = /\b(today|tonight|tomorrow|yesterday|this week|last week|past week|latest|breaking|just now|recent|currently|now|live|happening|this month|last month|past month|past \d+ days?|last \d+ days?|q[1-4]|h[12]|202[6-9])\b/i;
-// ─── Tool schema ──────────────────────────────────────────────────────────────
-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"],
-        },
-    },
-];
-const 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(),
-});
-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";
-}
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-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 DOMAIN_TIER_BONUS)
-        if (re.test(url))
-            return bonus;
-    return 0;
-}
-// Split markdown into ~600-char chunks at paragraph boundaries.
-function chunkMarkdown(md, chunkSize = 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, 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 && !STOPWORDS.has(t)))).slice(0, 10);
-}
-const STOPWORDS = new Set([
-    "the", "and", "for", "with", "that", "this", "what", "when", "where", "how", "why",
-    "have", "has", "had", "are", "was", "were", "will", "would", "could", "should", "does",
-    "did", "being", "been", "from", "into", "over", "under", "about", "into", "than", "then",
-    "your", "yours", "their", "they", "them", "there", "here", "just", "also", "more", "most",
-]);
-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()}`;
-}
-/**
- * Firecrawl returns either a flat array or a keyed object of result groups
- * (`{ web: [...], news: [...] }`). The proxy path assumed the flat shape and
- * handed an object to `.forEach`, which threw — invisible until now because
- * without an API key the run always died at the planner first.
- */
-function normalizeSearchHits(raw) {
-    if (Array.isArray(raw))
-        return raw;
-    if (raw && typeof raw === "object") {
-        const out = [];
-        for (const group of Object.values(raw)) {
-            if (Array.isArray(group))
-                out.push(...group);
-        }
-        return out;
-    }
-    return [];
-}
-async function fcSearch(query, limit) {
-    // BYOK path - direct call to Firecrawl with user's key. Fastest, no proxy hop.
-    const key = process.env.FIRECRAWL_API_KEY;
-    if (key) {
-        try {
-            const res = await fetch(`${FC_BASE}/search`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
-                body: JSON.stringify({ query, limit }),
-                signal: AbortSignal.timeout(15000),
-            });
-            if (res.ok) {
-                const data = (await res.json());
-                return normalizeSearchHits(data.data);
-            }
-        }
-        catch { /* fall through */ }
-    }
-    // Backend-proxy path - session-authed; Finch covers Firecrawl cost.
-    try {
-        const data = await (0, convex_js_1.callConvex)("/research/firecrawl-search", "POST", { query, limit }, "web_search", 20000);
-        return normalizeSearchHits(data?.results);
-    }
-    catch {
-        return [];
-    }
-}
-async function fcScrape(url) {
-    const key = process.env.FIRECRAWL_API_KEY;
-    if (key) {
-        try {
-            const res = await fetch(`${FC_BASE}/scrape`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
-                body: JSON.stringify({ url, formats: ["markdown"], onlyMainContent: true }),
-                signal: AbortSignal.timeout(20000),
-            });
-            if (res.ok) {
-                const data = (await res.json());
-                const md = data.data?.markdown;
-                if (md) {
-                    const meta = data.data?.metadata;
-                    const publishedAt = meta?.publishedAt ?? meta?.ogPublishedTime ?? meta?.["article:published_time"];
-                    return { markdown: md, publishedAt };
-                }
-            }
-        }
-        catch { /* fall through */ }
-    }
-    // Backend-proxy path. Returns markdown only - no metadata extraction yet,
-    // which means continueFrom can't auto-date proxied scrapes. Acceptable
-    // tradeoff for now; markdown is the primary signal.
-    try {
-        const data = await (0, convex_js_1.callConvex)("/research/firecrawl-scrape", "POST", { url }, "web_scrape", 25000);
-        if (data?.markdown)
-            return { markdown: data.markdown };
-    }
-    catch { /* swallow */ }
-    return null;
-}
-// ─── LLM stages ───────────────────────────────────────────────────────────────
-/**
- * Sub-queries without an LLM.
- *
- * The caller should normally pass `queries` — it is a model and plans better
- * than any heuristic. This exists so the evidence-pack path still works with
- * zero configuration, rather than failing when no API key is set.
- */
-function deriveSubQueries(query, n, focus, freshMode) {
-    const base = query.trim().replace(/\?+$/, "");
-    const recency = freshMode ? ` ${new Date().getFullYear()} latest` : "";
-    const lenses = focus
-        ? [focus, `${focus} risks`, `${focus} data`]
-        : ["overview", "latest developments", "risks and criticism", "data and numbers", "expert analysis"];
-    const out = [`${base}${recency}`];
-    for (const lens of lenses) {
-        if (out.length >= Math.max(2, n))
-            break;
-        out.push(`${base} ${lens}${recency}`);
-    }
-    return out;
-}
-async function planQueries(query, n, focus, priorContext, freshMode) {
-    const focusNote = focus ? ` Focus angle: ${focus}.` : "";
-    const sys = "You are a research planner. Output strict JSON only - no preamble, no markdown.";
-    const freshNote = freshMode
-        ? `
-
-⏱ FRESH MODE - last ${freshMode.days} days:
-- Add a recency hint to most sub-questions: "in ${currentYearMonth()}", "last ${freshMode.days} days", "this week", "as of ${todayISO()}", etc.
-- Prefer queries that surface news / press releases / X posts over evergreen background.
-- Skip generic background - the user wants what's CURRENT, not historical.
-- At least 70% of sub-questions must include a date or recency token.`
-        : "";
-    const continuationNote = priorContext
-        ? `
-
-⚠️ CONTINUATION MODE - there is a PRIOR research report on this topic:
-
-"""
-${priorContext.slice(0, 2500)}
-"""
-
-Your sub-questions must focus on:
-1. UPDATES - what has changed since the prior report (new releases, news, data revisions)
-2. GAPS - angles the prior report explicitly listed as open questions or follow-ups
-3. NEW developments - entities/events the prior report doesn't mention
-4. VERIFICATION - claims the prior report flagged as low-confidence or single-source
-
-DO NOT re-tread material already well-covered in the prior report. The user already has those answers.`
-        : "";
-    const user = `Decompose this research question into ${n} sub-questions that together cover the topic from different angles.${focusNote}${continuationNote}${freshNote}
-
-Rules:
-- Each sub-question must be a standalone web search query, under 90 chars.
-- Cover different facets: definition, current state, key actors, comparisons, counterarguments, recent news, forward outlook.
-- No duplicates, no near-paraphrases.
-
-ENTITY-HUNTING - at least HALF of your sub-questions must target queries likely to surface:
-- Specific company / product / framework names (e.g., "LangGraph adoption stats", "Manus orchestration funding")
-- Dollar amounts (acquisitions, funding rounds, revenue, ARR, market size)
-- Benchmark numbers (% adoption, latency ms, accuracy scores, MMLU/HumanEval/SWE-bench results)
-- Specific dates and timeline events (when X launched, when Y reached scale)
-- Named studies / surveys / reports (e.g., "Anthropic Economic Index 2026", "a16z AI infrastructure report")
-
-Bad: "what is X" → too generic, returns Wikipedia
-Good: "X adoption rate enterprise 2026 survey" → returns concrete stats
-
-Question: "${query}"
-
-Return: {"queries": ["...", "..."]} - exactly ${n} items.`;
-    let raw = "";
-    try {
-        raw = await (0, llm_js_1.callLLM)(sys, user, 500, [], 30000);
-    }
-    catch {
-        return [query];
-    }
-    const parsed = safeParseJson(raw, {});
-    if (!parsed.queries || !Array.isArray(parsed.queries))
-        return [query];
-    const queries = parsed.queries
-        .filter((s) => typeof s === "string")
-        .map((s) => s.trim())
-        .filter((s) => s.length > 0 && s.length <= 200)
-        .slice(0, n);
-    return queries.length > 0 ? queries : [query];
-}
-async function planAngles(query, n, focus, priorContext, freshMode) {
-    const focusNote = focus ? ` Focus angle: ${focus}.` : "";
-    const freshNote = freshMode
-        ? `\n\n⏱ FRESH MODE - last ${freshMode.days} days: bias each angle's queries toward news/recent press/dated reports.`
-        : "";
-    const continuationNote = priorContext
-        ? `\n\n⚠️ CONTINUATION - prior report exists. Angles must focus on UPDATES, GAPS, NEW developments since:\n"""\n${priorContext.slice(0, 1500)}\n"""`
-        : "";
-    const sys = "You are a research planner that decomposes topics into specialist angles. Output strict JSON only.";
-    const user = `Break this research topic into ${n} DIFFERENT specialist angles. Each angle gets its own 2-3 search queries.${focusNote}${continuationNote}${freshNote}
-
-Topic: "${query}"
-
-Pick angles that are GENUINELY different - not paraphrases of the same question. Good angle diversity examples:
-- data / quantitative metrics
-- competitive landscape
-- team / governance / actors
-- recent news / catalysts
-- counterarguments / risks / criticism
-- forward outlook / projections
-- historical context / origins
-- regulatory / policy angle
-- technical / mechanism
-- ecosystem partners
-
-Pick the ${n} angles that most fit THIS specific topic. Each angle should have a label (3-6 words) and rationale (1 sentence). Queries must be standalone, ≤90 chars, entity-rich (specific names, dollar amounts, dates, benchmark numbers - NOT generic background).
-
-Return strict JSON:
-{
-  "angles": [
-    {
-      "label": "...",
-      "rationale": "...",
-      "queries": ["...", "..."]
-    }
-  ]
-}
-
-Exactly ${n} angles. 2-3 queries per angle. No duplicate queries across angles.`;
-    let raw = "";
-    try {
-        raw = await (0, llm_js_1.callLLM)(sys, user, 1200, [], 30000);
-    }
-    catch {
-        return [];
-    }
-    const parsed = safeParseJson(raw, {});
-    if (!parsed.angles || !Array.isArray(parsed.angles))
-        return [];
-    const angles = [];
-    for (const a of parsed.angles) {
-        if (typeof a !== "object" || a === null)
-            continue;
-        const o = a;
-        if (typeof o.label !== "string" || typeof o.rationale !== "string")
-            continue;
-        if (!Array.isArray(o.queries))
-            continue;
-        const queries = o.queries
-            .filter((q) => typeof q === "string")
-            .map((q) => q.trim())
-            .filter((q) => q.length > 0 && q.length <= 200)
-            .slice(0, 3);
-        if (queries.length === 0)
-            continue;
-        angles.push({
-            label: o.label.trim().slice(0, 80),
-            rationale: o.rationale.trim().slice(0, 200),
-            queries,
-        });
-        if (angles.length >= n)
-            break;
-    }
-    return angles;
-}
-// Adversarial critic - only runs for depth=deep. Reads the draft + sources
-// already gathered and produces a structured challenge block: single-source
-// claims, contradictions across angles, speculation framed as fact. The
-// final synthesizer is told to incorporate or refute these challenges
-// explicitly, lifting the quality floor.
-async function runCritic(query, draft, angles, sourceCount) {
-    const sys = "You are an adversarial research critic. Be terse, specific, and unsparing. Output markdown.";
-    const angleLabels = angles.map((a, i) => `${i + 1}. ${a.label}`).join("\n");
-    const user = `Original question: "${query}"
-
-Specialist angles investigated:
-${angleLabels}
-
-Total sources gathered: ${sourceCount}
-
-Draft report:
-"""
-${draft.slice(0, 5000)}
-"""
-
-Audit the draft for quality problems. Be specific and quote spans where possible.
-
-Identify:
-1. **Single-source claims** - major assertions resting on one [N] citation that aren't widely corroborated
-2. **Contradictions** - places where different sources disagree but the draft doesn't surface the disagreement
-3. **Speculation framed as fact** - confident statements about future/intent/cause without evidence
-4. **Coverage gaps** - angles from the list above that got shallow treatment
-5. **Stale or weak sources** - dated material treated as current, blog posts cited as primary data
-
-Output format:
-## Critic notes
-- **[type]**: specific issue + relevant quote or claim. (1-2 sentences each)
-- Skip categories with no findings - don't pad.
-
-End with one line: "Net recommendation: [accept|revise|reject]"
-
-If the draft is solid, say so plainly - don't manufacture issues.`;
-    try {
-        const notes = await (0, llm_js_1.callLLM)(sys, user, 1500, [], 60000);
-        return notes.trim();
-    }
-    catch {
-        return ""; // critic failure shouldn't block final synth
-    }
-}
-async function reflectAndExtend(query, draft, existingQueries, n) {
-    const sys = "You are a research auditor. Find gaps in a draft report and propose follow-up search queries. Output strict JSON.";
-    const user = `Original question: "${query}"
-
-Queries already run:
-${existingQueries.map((q, i) => `${i + 1}. ${q}`).join("\n")}
-
-Draft report:
-"""
-${draft.slice(0, 4000)}
-"""
-
-Identify ${n} GAPS in the draft - angles missing, claims that need verification, counter-perspectives not represented, or recent developments not covered. For each gap, give ONE web search query (≤90 chars) that would fill it.
-
-Return: {"gap_queries": ["...", "..."]} - exactly ${n} items, no duplicates of existing queries.`;
-    let raw = "";
-    try {
-        raw = await (0, llm_js_1.callLLM)(sys, user, 500, [], 30000);
-    }
-    catch {
-        return [];
-    }
-    const parsed = safeParseJson(raw, {});
-    if (!parsed.gap_queries || !Array.isArray(parsed.gap_queries))
-        return [];
-    return parsed.gap_queries
-        .filter((s) => typeof s === "string")
-        .map((s) => s.trim())
-        .filter((s) => s.length > 0 && s.length <= 200)
-        .slice(0, n);
-}
-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 ${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;
-}
-// 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;
-}
-// 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();
-}
-// ─── Source ranking ───────────────────────────────────────────────────────────
-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 && 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 >= MAX_PER_DOMAIN)
-            continue;
-        seenUrl.add(c.url);
-        seenDomain.set(c.domain, count + 1);
-        result.push(c);
-    }
-    return result;
-}
-async function handleDeepResearch(name, args, onProgress) {
-    if (name !== "deep_research")
-        return null;
-    const parsed = InputSchema.safeParse(args);
-    if (!parsed.success) {
-        return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
-    }
-    const { query, focus, continueFrom } = parsed.data;
-    const clientQueries = parsed.data.queries ?? [];
-    // Default to the evidence pack: it always works (no key) and lets the caller
-    // do the synthesis it is better at. 'report' is the opt-in legacy path.
-    const sourcesMode = (parsed.data.mode ?? "sources") === "sources";
-    const depth = parsed.data.depth ?? "standard";
-    const saveToVault = parsed.data.saveToVault ?? true;
-    // Fresh mode: auto-detect from query unless explicitly set.
-    const freshModeAuto = FRESH_TRIGGER_RE.test(query);
-    const freshMode = parsed.data.freshMode ?? freshModeAuto;
-    const freshDays = parsed.data.freshDays ?? 14;
-    const freshConfig = freshMode ? { days: freshDays } : undefined;
-    // Live Search resolution - opt-in only when Grok is the active provider.
-    // Default: enable when Grok is active (smart default - they paid for the
-    // feature, use it), disable otherwise (other providers ignore it anyway).
-    const grokActive = (0, llm_js_1.isGrokActive)();
-    const liveSearchEnabled = (parsed.data.liveSearch ?? grokActive) && grokActive;
-    const liveSearch = liveSearchEnabled
-        ? {
-            mode: "on",
-            sources: parsed.data.liveSearchSources ?? ["web", "x", "news"],
-            maxResults: depth === "fast" ? 8 : depth === "deep" ? 18 : 12,
-            fromDate: parsed.data.liveSearchDays
-                ? new Date(Date.now() - parsed.data.liveSearchDays * 86400000).toISOString().slice(0, 10)
-                : undefined,
-        }
-        : undefined;
-    // No early FIRECRAWL_API_KEY gate - fcSearch/fcScrape transparently fall
-    // through to the Finch backend proxy when the user is signed in but
-    // has no local key. If both paths fail, the search loop returns an empty
-    // source list and the synthesis stage produces the "insufficient signal"
-    // skip report instead of a fake summary.
-    // Depth knobs
-    // Multi-agent mode (standard/deep): N angles × 2-3 queries each = effective
-    // sub-query count. Fast mode keeps the original flat-planner behavior.
-    const angleN = depth === "deep" ? 5 : 3;
-    const subN = depth === "fast" ? 3 : depth === "deep" ? 7 : 5;
-    const searchLimit = depth === "fast" ? 4 : depth === "deep" ? 6 : 5;
-    const maxScrape = depth === "fast" ? 10 : depth === "deep" ? 22 : 16;
-    const maxSources = depth === "fast" ? 10 : depth === "deep" ? 20 : 14;
-    const useReflection = depth !== "fast";
-    const useCritic = depth === "deep";
-    const useAngles = depth !== "fast";
-    const queryTerms = extractQueryTerms(query);
-    const progress = [];
-    // log() retains backwards-compat (collects messages for the final report
-    // footer), and also emits MCP progress notifications when the client
-    // opted in via _meta.progressToken (handled at the server.ts layer).
-    // Estimated total steps for fast/standard/deep - used as `total` in the
-    // notification so progress UIs can render a percentage.
-    const totalSteps = depth === "deep" ? 9 : depth === "standard" ? 8 : 6;
-    const log = (line) => {
-        progress.push(line);
-        if (onProgress) {
-            // Fire-and-forget - never let progress emission slow the pipeline.
-            Promise.resolve(onProgress(line.replace(/^[^\w]+/, "").trim(), totalSteps)).catch(() => { });
-        }
-    };
-    if (liveSearch) {
-        log(`🛰  Live Search: ON · sources=[${liveSearch.sources.join(", ")}] · max=${liveSearch.maxResults}${liveSearch.fromDate ? ` · since=${liveSearch.fromDate}` : ""}`);
-    }
-    if (freshMode) {
-        log(`⏱ Fresh mode: ON · last ${freshDays} days · news-domain boost active${freshModeAuto && !parsed.data.freshMode ? " (auto-detected from query)" : ""}`);
-    }
-    // ── Stage 0: load prior report (continueFrom) ──
-    let priorContext;
-    if (continueFrom) {
-        log(`📚 Loading prior report \`${continueFrom}\` to continue research thread...`);
-        try {
-            const prior = await (0, convex_js_1.callConvex)(`/vault/entry?key=${encodeURIComponent(continueFrom)}`, "GET", undefined, "vault_read");
-            if (prior?.content && prior.content.length > 100) {
-                priorContext = { key: prior.key ?? continueFrom, content: prior.content };
-                log(`✅ Loaded prior report (${prior.content.length} chars) - planner & synth will build on it.`);
-            }
-            else {
-                log(`⚠️ Prior report \`${continueFrom}\` not found or empty - proceeding as fresh research.`);
-            }
-        }
-        catch (err) {
-            log(`⚠️ Could not load prior report (${err.message ?? "error"}) - proceeding as fresh research.`);
-        }
-    }
-    // ── Stage 1: plan ──
-    // Multi-agent mode (standard/deep) decomposes into labeled angles. Each
-    // angle has 2-3 sub-queries - flatten them for the search stage but keep
-    // the angle structure for synthesis & critic prompts.
-    let angles = [];
-    let subQs;
-    if (clientQueries.length > 0) {
-        // The client is itself a strong model and knows the user's intent — when it
-        // supplies the angles we skip the planner entirely. No LLM call, no key,
-        // and the user can actually steer what gets researched.
-        subQs = clientQueries;
-        log(`🧭 Using ${subQs.length} caller-supplied queries (no planner call).`);
-    }
-    else if (!(0, llm_js_1.hasDirectLLMKey)() && !sourcesMode) {
-        subQs = deriveSubQueries(query, subN, focus, freshConfig);
-        log(`🧭 Derived ${subQs.length} sub-queries without a planner (no LLM key).`);
-    }
-    else if (sourcesMode) {
-        // Evidence-pack mode must never require a key. Derive locally.
-        subQs = deriveSubQueries(query, subN, focus, freshConfig);
-        log(`🧭 Derived ${subQs.length} sub-queries. Pass \`queries\` to control the angles yourself.`);
-    }
-    else if (useAngles) {
-        log(`🧭 Planning ${angleN} specialist angles${priorContext ? " (continuation mode)" : ""}${freshMode ? " (fresh mode)" : ""}...`);
-        angles = await planAngles(query, angleN, focus, priorContext?.content, freshConfig);
-        if (angles.length === 0) {
-            // Planner returned nothing usable - fall back to flat sub-query mode
-            log(`⚠️ Angle planner failed, falling back to flat sub-query planning.`);
-            subQs = await planQueries(query, subN, focus, priorContext?.content, freshConfig);
-        }
-        else {
-            const seen = new Set();
-            const flat = [];
-            for (const a of angles) {
-                for (const q of a.queries) {
-                    if (!seen.has(q.toLowerCase())) {
-                        seen.add(q.toLowerCase());
-                        flat.push(q);
-                    }
-                }
-            }
-            subQs = flat;
-            log(`📐 Angles: ${angles.map((a) => `"${a.label}"`).join(" · ")} → ${subQs.length} unique queries.`);
-        }
-    }
-    else {
-        log(`🧭 Planning ${subN} sub-questions${priorContext ? " (continuation mode)" : ""}${freshMode ? " (fresh mode)" : ""}...`);
-        subQs = await planQueries(query, subN, focus, priorContext?.content, freshConfig);
-    }
-    // ── Stage 2: parallel search ──
-    log(`🔎 Searching ${subQs.length} queries × ${searchLimit} results each...`);
-    const searchResults = await Promise.all(subQs.map((q) => fcSearch(q, searchLimit)));
-    // Flatten with rank info
-    const allCandidates = [];
-    for (const results of searchResults) {
-        results.forEach((r, idx) => {
-            if (r.url)
-                allCandidates.push({ url: r.url, title: r.title ?? r.url, desc: r.description ?? "", queryRank: idx });
-        });
-    }
-    if (allCandidates.length === 0) {
-        return { content: [{ type: "text", text: `No sources found for: "${query}". Try a more specific query or a different focus angle.` }], isError: true };
-    }
-    const ranked = rankAndDedupe(allCandidates, freshMode).slice(0, maxScrape);
-    log(`📊 Ranked ${allCandidates.length} candidates → ${ranked.length} after domain dedup (max ${MAX_PER_DOMAIN}/domain)${freshMode ? " + news-domain boost" : ""}.`);
-    // ── Stage 3: parallel scrape ──
-    log(`📥 Scraping ${ranked.length} sources in parallel...`);
-    // Track why sources drop out. Silently returning fewer sources makes a thin
-    // report look like a complete one — the user can't tell a well-supported
-    // finding from one built on two pages that happened to load.
-    let unreachable = 0;
-    let tooThin = 0;
-    const scraped = await Promise.all(ranked.map(async (c) => {
-        const r = await fcScrape(c.url);
-        if (!r) {
-            unreachable++;
-            return null;
-        }
-        const excerpt = pickBestExcerpt(r.markdown, queryTerms);
-        if (excerpt.length < 150) {
-            tooThin++;
-            return null;
-        }
-        return {
-            url: c.url,
-            domain: domainOf(c.url),
-            title: c.title,
-            excerpt,
-            publishedAt: r.publishedAt,
-            score: tierBonus(c.url),
-        };
-    }));
-    let sources = scraped
-        .filter((s) => s !== null)
-        .slice(0, maxSources)
-        .map((s, i) => ({ n: i + 1, ...s, class: classifySource(s.score) }));
-    const dropped = unreachable + tooThin;
-    if (dropped > 0) {
-        const parts = [];
-        if (unreachable)
-            parts.push(`${unreachable} unreachable/blocked`);
-        if (tooThin)
-            parts.push(`${tooThin} too thin to quote`);
-        log(`⚠️  ${dropped} of ${ranked.length} sources dropped (${parts.join(", ")}) — ` +
-            `report is based on ${sources.length}.`);
-    }
-    if (sources.length === 0) {
-        return { content: [{ type: "text", text: `Could not scrape any usable sources for: "${query}". Sites may be blocking or paywalled.` }], isError: true };
-    }
-    // ── Evidence-pack mode: hand the sources back and stop ──
-    // Everything below this point is the server writing prose. The caller is a
-    // model with the user's full context; it synthesises better, it can be
-    // steered mid-conversation, and it needs no API key to do it.
-    if (sourcesMode) {
-        // X / news via Grok Live Search — the one input the caller's model cannot
-        // fetch for itself. Retrieved verbatim and appended as ordinary numbered
-        // sources so the caller can weigh them (and discount anonymous accounts)
-        // rather than receiving a pre-filtered opinion. Skipped silently with no key.
-        let liveHits = [];
-        const liveSources = liveSearch?.sources ?? ["x", "news", "web"];
-        if (liveSearch) {
-            log(`📡 Grok Live Search (${liveSources.join(", ")}) for real-time X/news...`);
-            liveHits = await (0, llm_js_1.grokLiveSearchHits)(query, liveSources, parsed.data.liveSearchDays, depth === "fast" ? 6 : 10);
-            log(liveHits.length ? `📡 ${liveHits.length} live item(s) retrieved.` : `📡 Live Search returned nothing usable.`);
-        }
-        log(`📦 Returning ${sources.length + liveHits.length} sources as an evidence pack.`);
-        const pack = [
-            `# Research evidence — "${query}"`,
-            ``,
-            `**${sources.length} sources** · queries run: ${subQs.length}${dropped > 0 ? ` · ${dropped} dropped` : ""}`,
-            `_Synthesis is yours: cite with [N], and say if the evidence is thin or one-sided._`,
-            ``,
-            `**Queries searched:**`,
-            ...subQs.map((q) => `- ${q}`),
-            ``,
-            `---`,
-            ``,
-        ];
-        for (const s of sources) {
-            pack.push(`### [${s.n}] ${s.title}`, `${s.url}`, `_${s.domain}${s.publishedAt ? ` · ${String(s.publishedAt).slice(0, 10)}` : ""} · ${s.class}_`, ``, s.excerpt, ``);
-        }
-        if (liveHits.length) {
-            pack.push(`---`, ``, `## Real-time (${liveSources.join(" / ")}) — retrieved verbatim`, `_Unvetted social/news chatter. Weigh it yourself: check who is speaking, whether the claim is`, `corroborated by a numbered source above, and discount anonymous or promotional accounts._`, ``);
-            liveHits.forEach((h, idx) => {
-                pack.push(`### [L${idx + 1}] ${h.url || "(no url)"}`, ``, h.excerpt || "_(no excerpt returned)_`", ``);
-            });
-        }
-        pack.push(`---`, ``);
-        // Announce the capability rather than silently omitting it — a missing key
-        // should look like an unconfigured option, not like the feature never existed.
-        if (!liveSearch) {
-            pack.push(`ℹ️ **No real-time X / news in this pack.** Web sources only. Set \`GROK_API_KEY\` to add ` +
-                `live X and news items — it is optional, and everything above works without it.`, ``);
-        }
-        pack.push(`_Pass \`queries\` next time to control the angles. Use \`mode: "report"\` only if you want the server to write the prose (needs an LLM key)._`);
-        return { content: [{ type: "text", text: pack.join("\n") }] };
-    }
-    // ── Stage 4: draft synthesis (only if reflection enabled) ──
-    let draft = "";
-    if (useReflection) {
-        log(`✍️  Drafting initial report (will reflect & refine)...`);
-        try {
-            const draftResult = await synthesize(query, sources, false, liveSearch);
-            draft = draftResult.report;
-        }
-        catch {
-            // If draft fails, fall through to final synth with what we have
-            draft = "";
-        }
-    }
-    // ── Stage 5: reflection - find gaps, search again ──
-    if (useReflection && draft) {
-        log(`🤔 Auditing draft for gaps...`);
-        const gapQs = await reflectAndExtend(query, draft, subQs, depth === "deep" ? 3 : 2);
-        if (gapQs.length > 0) {
-            log(`🔁 Running ${gapQs.length} gap-search(es)...`);
-            const gapResults = await Promise.all(gapQs.map((q) => fcSearch(q, 3)));
-            const gapCandidates = [];
-            const existingUrls = new Set(sources.map((s) => s.url));
-            for (const results of gapResults) {
-                results.forEach((r, idx) => {
-                    if (r.url && !existingUrls.has(r.url)) {
-                        gapCandidates.push({ url: r.url, title: r.title ?? r.url, desc: r.description ?? "", queryRank: idx });
-                    }
-                });
-            }
-            const gapRanked = rankAndDedupe(gapCandidates, freshMode).slice(0, gapQs.length * 2);
-            const gapScraped = await Promise.all(gapRanked.map(async (c) => {
-                const r = await fcScrape(c.url);
-                if (!r || r.markdown.length < 200)
-                    return null;
-                return {
-                    url: c.url,
-                    domain: domainOf(c.url),
-                    title: c.title,
-                    excerpt: pickBestExcerpt(r.markdown, queryTerms),
-                    publishedAt: r.publishedAt,
-                    score: tierBonus(c.url),
-                };
-            }));
-            const newSources = gapScraped.filter((s) => s !== null);
-            const startN = sources.length;
-            const appended = newSources.map((s, i) => ({ n: startN + i + 1, ...s, class: classifySource(s.score) }));
-            sources = [...sources, ...appended].slice(0, maxSources + 4);
-            log(`✅ Added ${appended.length} gap-fill source(s).`);
-        }
-        else {
-            log(`✅ No gaps found - draft is complete.`);
-        }
-    }
-    // ── Stage 5b: critic (deep mode only) ──
-    // Adversarial pass over the draft. Critic notes get prepended to the
-    // final synthesizer's prompt so the model addresses concrete weaknesses.
-    let criticNotes = "";
-    if (useCritic && draft) {
-        log(`⚖️ Critic audit - challenging draft for single-source claims & contradictions...`);
-        criticNotes = await runCritic(query, draft, angles, sources.length);
-        if (criticNotes) {
-            // Tolerant verdict extraction - the critic LLM doesn't always honor
-            // the "Net recommendation: X" sentinel exactly. Look for any of the
-            // three verdict tokens near the end of the notes.
-            const tail = criticNotes.slice(-400).toLowerCase();
-            let verdict = "delivered";
-            if (/\brevise|\brewrite|\bweak|\bfix/i.test(tail))
-                verdict = "revise";
-            if (/\breject|\binsufficient|\bcannot/i.test(tail))
-                verdict = "reject";
-            if (/\baccept|\bsolid|\bsound|\bgood|\bcorrect/i.test(tail))
-                verdict = "accept";
-            log(`✅ Critic ${verdict} (${criticNotes.length} chars of notes).`);
-        }
-        else {
-            log(`⚠️ Critic returned no notes (LLM error or empty response).`);
-        }
-    }
-    // ── Stage 6: final synthesis ──
-    log(`📝 Writing final report from ${sources.length} sources${angles.length > 0 ? ` across ${angles.length} angle(s)` : ""}${criticNotes ? " (critic-audited)" : ""}${liveSearch ? " + Live Search" : ""}${priorContext ? ` (continuing \`${priorContext.key}\`)` : ""}${freshMode ? " (fresh)" : ""}...`);
-    let report;
-    let liveCitations = [];
-    try {
-        const finalResult = await synthesize(query, sources, true, liveSearch, priorContext, freshMode, angles, criticNotes);
-        report = finalResult.report;
-        liveCitations = finalResult.liveCitations;
-    }
-    catch (err) {
-        return { content: [{ type: "text", text: `Synthesis failed: ${err.message ?? err}` }], isError: true };
-    }
-    // ── Stage 6b: structural output validation ──
-    // Verify the report contains the required sections + adequate citation
-    // density. If 2+ checks fail, retry synthesis once with stricter prompt.
-    const issues = validateReportStructure(report);
-    if (issues.length >= 2) {
-        log(`🔧 Output validation found ${issues.length} issues (${issues.join(", ")}). Retrying synthesis with stricter prompt...`);
-        try {
-            const retryResult = await synthesize(query, sources, true, liveSearch, priorContext, freshMode, angles, criticNotes);
-            const retryIssues = validateReportStructure(retryResult.report);
-            if (retryIssues.length < issues.length) {
-                report = retryResult.report;
-                if (retryResult.liveCitations.length > 0)
-                    liveCitations = retryResult.liveCitations;
-                log(`✅ Retry improved - ${retryIssues.length} issues remaining.`);
-            }
-            else {
-                log(`⚠️ Retry didn't improve - keeping original.`);
-            }
-        }
-        catch {
-            log(`⚠️ Retry failed - keeping original output.`);
-        }
-    }
-    else if (issues.length > 0) {
-        log(`⚠️ Output has minor issues: ${issues.join(", ")}.`);
-    }
-    else {
-        log(`✅ Output structure validated.`);
-    }
-    // Append sources list with snippets
-    const sourcesSection = sources
-        .map((s) => {
-        const date = s.publishedAt ? ` (${s.publishedAt.slice(0, 10)})` : "";
-        const cls = s.class !== "unclassified" ? ` · ${s.class}` : "";
-        return `[${s.n}] **${s.title}** - ${s.domain}${date}${cls}\n   ${s.url}`;
-    })
-        .join("\n\n");
-    // Group live citations by source type for readability
-    const liveSection = liveCitations.length > 0
-        ? `\n\n### 🛰 Real-time sources (Live Search)\n\n${formatLiveCitations(liveCitations)}`
-        : "";
-    const fullReport = `${report.trim()}\n\n## Sources\n\n${sourcesSection}${liveSection}`;
-    // ── Stage 6.5: signal gate ──
-    // If the synthesis is thin (LLM admitted "search returned directory pages"
-    // or content has no concrete data), return an honest "insufficient signal"
-    // result instead of saving and citing a fake summary. The user can rerun
-    // with a sharper query.
-    const signal = (0, signal_gate_js_1.checkSignal)(report);
-    if (!signal.ok) {
-        const skipMsg = [
-            `## ⚠️ Insufficient signal`,
-            ``,
-            `**Query:** ${query}`,
-            `**Reason:** ${signal.reason}`,
-            `**Signal score:** ${signal.score.toFixed(2)} / 1.00`,
-            ``,
-            `The search results were too thin to produce a substantive report. Try a narrower or more recent query, or scope to a specific domain.`,
-            ``,
-            `<details><summary>Raw synthesis (saved for audit, not vault)</summary>`,
-            ``,
-            "```",
-            report.slice(0, 1500),
-            "```",
-            ``,
-            `</details>`,
-        ].join("\n");
-        return { content: [{ type: "text", text: skipMsg }] };
-    }
-    // ── Stage 7: vault save ──
-    let vaultKey = null;
-    if (saveToVault) {
-        try {
-            const r = (await (0, convex_js_1.callConvex)("/vault/save", "POST", {
-                type: "research",
-                title: priorContext
-                    ? `Deep Research (cont.): ${query.slice(0, 80)}`
-                    : `Deep Research: ${query.slice(0, 80)}`,
-                content: fullReport,
-                tags: [
-                    "deep-research",
-                    depth,
-                    ...(focus ? [focus] : []),
-                    ...(priorContext ? ["continuation"] : []),
-                ],
-                agentId: "research",
-                commitMsg: priorContext ? `deep_research continues ${priorContext.key}` : "deep_research run",
-            }, "vault_save"));
-            vaultKey = r?.key ?? null;
-        }
-        catch { /* keep going - return report inline */ }
-    }
-    // ── Stage 7b: link as continuation when continueFrom was used ──
-    if (vaultKey && priorContext) {
-        try {
-            await (0, convex_js_1.callConvex)("/vault/link", "POST", {
-                fromKey: vaultKey,
-                toKey: priorContext.key,
-                relation: "continues",
-            }, "vault_link");
-            log(`🧬 Linked new report as \`continues\` → \`${priorContext.key}\`.`);
-        }
-        catch {
-            log(`⚠️ Could not create continuation link.`);
-        }
-    }
-    // ── Stage 8: vault auto-linking - connect this report to related research ──
-    // This is what makes Finch deep_research compound over time. Every new
-    // report finds related past reports in your vault and creates typed links,
-    // so your knowledge base grows into a connected graph (vault_related to
-    // explore it). Best-effort - failure here never blocks the report.
-    const linkedKeys = [];
-    if (vaultKey && saveToVault) {
-        try {
-            const searchTerms = buildSearchTermsForLinking(query);
-            log(`🔗 Searching vault for related research (terms: ${searchTerms.slice(0, 60)}...)`);
-            const searchResult = (await (0, convex_js_1.callConvex)("/vault/search", "POST", {
-                q: searchTerms,
-                n: 8,
-            }, "vault_search"));
-            const hits = (searchResult?.results ?? [])
-                .map((r) => ({
-                // The /vault/search endpoint returns documents from the semantic
-                // memory layer, not vault keys directly. We need to extract vault
-                // keys from the metadata when present.
-                key: extractVaultKeyFromHit(r),
-                title: r.metadata?.title ?? "(untitled)",
-            }))
-                .filter((h) => !!h.key && h.key !== vaultKey)
-                .slice(0, 3);
-            if (hits.length > 0) {
-                for (const hit of hits) {
-                    try {
-                        await (0, convex_js_1.callConvex)("/vault/link", "POST", {
-                            fromKey: vaultKey,
-                            toKey: hit.key,
-                            relation: "related",
-                        }, "vault_link");
-                        linkedKeys.push(hit.key);
-                    }
-                    catch { /* skip individual link failures */ }
-                }
-                log(`✅ Linked to ${linkedKeys.length} related vault entr${linkedKeys.length === 1 ? "y" : "ies"}.`);
-            }
-            else {
-                log(`✅ No related vault entries found - this is a fresh research thread.`);
-            }
-        }
-        catch {
-            // Vault auto-linking is purely additive - silent failure is fine
-            log(`⚠️ Vault auto-link skipped (search unavailable).`);
-        }
-    }
-    const linkedSection = linkedKeys.length > 0
-        ? `🔗 Auto-linked to ${linkedKeys.length} related research entr${linkedKeys.length === 1 ? "y" : "ies"} in your vault:\n${linkedKeys.map((k) => `   • \`${k}\``).join("\n")}`
-        : "";
-    const continuationSection = priorContext
-        ? `🧬 **Continuation** of \`${priorContext.key}\` - linked as relation:continues`
-        : "";
-    const header = [
-        `🔬 **Deep Research v3** - depth: ${depth} · ${subQs.length} planned + ${useReflection ? "reflection" : "no reflection"} · ${sources.length} scraped sources${liveCitations.length > 0 ? ` · ${liveCitations.length} live` : ""}${liveSearch ? ` · 🛰 Live Search [${liveSearch.sources.join(",")}]` : ""}${freshMode ? ` · ⏱ fresh:${freshDays}d` : ""}`,
-        vaultKey ? `📁 Saved to vault: \`${vaultKey}\`` : (saveToVault ? `⚠️ Vault save skipped (not authenticated - sign in with \`finch login\`)` : ""),
-        continuationSection,
-        linkedSection,
-        ``,
-        `<details><summary>📋 Process log</summary>`,
-        ``,
-        progress.map((p) => `- ${p}`).join("\n"),
-        ``,
-        `</details>`,
-        ``,
-    ].filter(Boolean).join("\n");
-    return { content: [{ type: "text", text: `${header}\n${fullReport}` }] };
-}