@finchagentic/mcp 4.6.1 → 4.6.2

package/dist/tools/research-chain.js

@@ -1,226 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RESEARCH_CHAIN_TOOLS = void 0;
-exports.handleResearchChain = handleResearchChain;
-const zod_1 = require("zod");
-const convex_js_1 = require("../convex.js");
-// ─── Tool schema ──────────────────────────────────────────────────────────────
-exports.RESEARCH_CHAIN_TOOLS = [
-    {
-        name: "research_chain",
-        description: "Walk a research topic's timeline. Follows `continues` relations both backward and forward from a starting report and returns the chronological list with each report's date/title/TL;DR, plus the rubric for YOU to write the 'net evolution' — what shifted at each step. No API key needed.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                startKey: {
-                    type: "string",
-                    description: "Vault key of any research entry in the chain. The tool walks both directions from there. Format: 'research/...'",
-                },
-                maxDepth: {
-                    type: "number",
-                    description: "Max number of entries to walk in each direction. Default 8 (so up to 17 entries including start). Capped at 20.",
-                },
-                synthesize: {
-                    type: "boolean",
-                    description: "Append the 'net evolution' rubric after the timeline. Default true. Set false if you only want the raw timeline.",
-                },
-            },
-            required: ["startKey"],
-        },
-    },
-];
-const InputSchema = zod_1.z.object({
-    startKey: zod_1.z.string().min(3).max(200),
-    maxDepth: zod_1.z.number().int().min(1).max(20).optional(),
-    synthesize: zod_1.z.boolean().optional(),
-});
-async function loadEntry(key) {
-    try {
-        const e = (await (0, convex_js_1.callConvex)(`/vault/entry?key=${encodeURIComponent(key)}`, "GET", undefined, "vault_read"));
-        if (!e?.content)
-            return null;
-        return {
-            key: e.key ?? key,
-            title: e.title ?? key,
-            updatedAt: e.updatedAt,
-            content: e.content,
-            tldr: extractTLDR(e.content),
-        };
-    }
-    catch {
-        return null;
-    }
-}
-function extractTLDR(content) {
-    // Look for "## TL;DR" / "## Summary" section.
-    const m = content.match(/##\s*(TL;DR|Summary)[\s\S]*?(?=\n##|\n#|$)/i);
-    if (m) {
-        const body = m[0].replace(/^##.*$/m, "").trim();
-        return body.split("\n\n")[0].trim().slice(0, 320);
-    }
-    // Fallback: first non-header paragraph
-    const para = content
-        .split("\n\n")
-        .find((p) => p.trim() && !p.trim().startsWith("#") && !p.trim().startsWith("📁") && !p.trim().startsWith("🔬"));
-    return (para ?? "").trim().slice(0, 320);
-}
-async function getLinkedKeys(key, relation) {
-    // /vault/related returns linked entries via vault_related. Each result has
-    // direction "outbound" (this -> other) or "inbound" (other -> this).
-    // continues = outbound continues link → next-older report
-    // continued_by = inbound continues link → next-newer report
-    try {
-        const result = (await (0, convex_js_1.callConvex)(`/vault/related?key=${encodeURIComponent(key)}&relation=continues`, "GET", undefined, "vault_related"));
-        const wanted = relation === "continues" ? "outbound" : "inbound";
-        return (result?.related ?? [])
-            .filter((r) => r.direction === wanted)
-            .map((r) => r.key);
-    }
-    catch {
-        return [];
-    }
-}
-async function walkChain(startKey, maxDepth) {
-    const startEntry = await loadEntry(startKey);
-    if (!startEntry)
-        return [];
-    const visited = new Set([startKey]);
-    // Walk backward: follow outbound `continues` links (this report continues prior).
-    const backward = [];
-    let backCursor = startKey;
-    for (let i = 0; i < maxDepth; i++) {
-        const linkedKeys = await getLinkedKeys(backCursor, "continues");
-        const next = linkedKeys.find((k) => !visited.has(k));
-        if (!next)
-            break;
-        visited.add(next);
-        const entry = await loadEntry(next);
-        if (!entry)
-            break;
-        backward.unshift(entry); // oldest at front
-        backCursor = next;
-    }
-    // Walk forward: follow inbound `continues` links (other reports continue this one).
-    const forward = [];
-    let fwdCursor = startKey;
-    for (let i = 0; i < maxDepth; i++) {
-        const linkedKeys = await getLinkedKeys(fwdCursor, "continued_by");
-        const next = linkedKeys.find((k) => !visited.has(k));
-        if (!next)
-            break;
-        visited.add(next);
-        const entry = await loadEntry(next);
-        if (!entry)
-            break;
-        forward.push(entry);
-        fwdCursor = next;
-    }
-    return [...backward, startEntry, ...forward];
-}
-// The timeline is the tool's real work: walking `continues` relations in both
-// directions, loading each entry, extracting its TL;DR and ordering the stops.
-// Reading the arc off that timeline is model work, so the rubric travels with
-// the data instead of a server-side summary the caller can't steer.
-function evolutionRubric(chain) {
-    const spanDays = chain[0].updatedAt && chain[chain.length - 1].updatedAt
-        ? Math.round((chain[chain.length - 1].updatedAt - chain[0].updatedAt) / 86400000)
-        : null;
-    return [
-        `## Write the net evolution from this`,
-        ``,
-        `4-6 sentences on how the understanding evolved across these ${chain.length} stops` +
-            `${spanDays !== null ? ` (${spanDays} day${spanDays === 1 ? "" : "s"})` : ""}. Call out:`,
-        ``,
-        `- **Position shifts** — a claim that went from confident to weak, or the reverse`,
-        `- **New entities or data points** and the exact stop where they appeared`,
-        `- **Predictions** that came true or were falsified`,
-        `- **Current state vs starting state**`,
-        ``,
-        `Synthesize the arc — do not list the reports back. Emphasise what CHANGED, not what held steady. ` +
-            `Each TL;DR above is truncated: if the arc turns on a detail you can't see, read the full entry with ` +
-            `\`vault_read\` before writing.`,
-    ].join("\n");
-}
-// ─── Handler ──────────────────────────────────────────────────────────────────
-async function handleResearchChain(name, args) {
-    if (name !== "research_chain")
-        return null;
-    const parsed = InputSchema.safeParse(args);
-    if (!parsed.success) {
-        return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
-    }
-    const { startKey } = parsed.data;
-    const maxDepth = parsed.data.maxDepth ?? 8;
-    const synthesize = parsed.data.synthesize ?? true;
-    const progress = [];
-    const log = (line) => progress.push(line);
-    log(`🔍 Loading start entry: \`${startKey}\``);
-    log(`🧬 Walking continues chain (max ${maxDepth} steps each direction)...`);
-    const chain = await walkChain(startKey, maxDepth);
-    if (chain.length === 0) {
-        return {
-            content: [{
-                    type: "text",
-                    text: `Could not load \`${startKey}\` - check the vault key (use vault_list type:research) and make sure you're authenticated.`,
-                }],
-            isError: true,
-        };
-    }
-    if (chain.length === 1) {
-        return {
-            content: [{
-                    type: "text",
-                    text: `🧬 **Research Chain** - \`${startKey}\` is a standalone report.\n\n` +
-                        `No \`continues\` links found in either direction. To start building a chain, ` +
-                        `run \`deep_research\` again on the same topic with \`continueFrom="${startKey}"\` - ` +
-                        `that creates the temporal link.\n\n` +
-                        `Once you have 2+ continuations, this tool will walk and synthesize the evolution.`,
-                }],
-        };
-    }
-    log(`✅ Loaded ${chain.length} entries in chain.`);
-    // Render the timeline
-    const timelineLines = [];
-    for (let i = 0; i < chain.length; i++) {
-        const e = chain[i];
-        const date = e.updatedAt ? new Date(e.updatedAt).toISOString().slice(0, 10) : "-";
-        const marker = e.key === startKey ? " ← you are here" : "";
-        timelineLines.push(`### [${i + 1}/${chain.length}] ${date}${marker}`);
-        timelineLines.push(`**${e.title}**`);
-        timelineLines.push(`\`${e.key}\``);
-        timelineLines.push("");
-        timelineLines.push(e.tldr);
-        timelineLines.push("");
-        if (i < chain.length - 1) {
-            timelineLines.push("⬇ *continues into*");
-            timelineLines.push("");
-        }
-    }
-    if (synthesize && chain.length >= 2) {
-        log(`📐 Attached the net-evolution rubric for ${chain.length} stops.`);
-    }
-    const netEvolution = synthesize && chain.length >= 2 ? evolutionRubric(chain) : "";
-    const header = [
-        `🧬 **Research Chain** - ${chain.length} reports across the timeline`,
-        `📍 You are at: \`${startKey}\``,
-        chain[0].updatedAt && chain[chain.length - 1].updatedAt
-            ? `🗓 Spans ${new Date(chain[0].updatedAt).toISOString().slice(0, 10)} → ${new Date(chain[chain.length - 1].updatedAt).toISOString().slice(0, 10)}`
-            : "",
-        ``,
-        `<details><summary>📋 Process log</summary>`,
-        ``,
-        progress.map((p) => `- ${p}`).join("\n"),
-        ``,
-        `</details>`,
-        ``,
-    ].filter(Boolean).join("\n");
-    const evolutionBlock = netEvolution ? `\n---\n\n${netEvolution}\n` : "";
-    const text = [
-        header,
-        `## Timeline`,
-        ``,
-        timelineLines.join("\n"),
-        evolutionBlock,
-    ].join("\n");
-    return { content: [{ type: "text", text }] };
-}

package/dist/tools/research-compare.js

@@ -1,280 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RESEARCH_COMPARE_TOOLS = void 0;
-exports.handleResearchCompare = handleResearchCompare;
-const zod_1 = require("zod");
-const convex_js_1 = require("../convex.js");
-// ─── Tool schema ──────────────────────────────────────────────────────────────
-exports.RESEARCH_COMPARE_TOOLS = [
-    {
-        name: "research_compare",
-        description: "Diff two vault research reports. Two-pass, no API key needed. " +
-            "PASS 1 — call with keyA + keyB: loads both reports, extracts their section structure, and returns " +
-            "both bodies plus the comparison rubric for YOU to write. " +
-            "PASS 2 — call again with the same keys plus `comparison`: saves your write-up as type:research and " +
-            "auto-links it to both source reports.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                keyA: {
-                    type: "string",
-                    description: "Vault key of the FIRST (older / baseline) report. Format: 'research/...' - use vault_list type:research to find candidates.",
-                },
-                keyB: {
-                    type: "string",
-                    description: "Vault key of the SECOND (newer / current) report to compare against keyA.",
-                },
-                focus: {
-                    type: "string",
-                    description: "Optional aspect to focus the comparison on: 'numbers', 'sentiment', 'sources', 'predictions', 'consensus'. Default: all.",
-                },
-                comparison: {
-                    type: "string",
-                    description: "PASS 2 only. Your finished comparison in Markdown. Supplying it switches this tool from 'return the evidence' to 'save and link the result'.",
-                },
-                saveToVault: { type: "boolean", description: "Save the pass-2 comparison to vault (default true)" },
-                maxChars: {
-                    type: "number",
-                    description: "Max characters of each report body to return in pass 1 (default 12000, max 40000). Raise it if the reports are long and you need the full text.",
-                },
-            },
-            required: ["keyA", "keyB"],
-        },
-    },
-];
-const InputSchema = zod_1.z.object({
-    keyA: zod_1.z.string().min(3).max(200),
-    keyB: zod_1.z.string().min(3).max(200),
-    focus: zod_1.z.string().max(80).optional(),
-    comparison: zod_1.z.string().min(1).optional(),
-    saveToVault: zod_1.z.boolean().optional(),
-    maxChars: zod_1.z.number().int().min(1000).max(40000).optional(),
-});
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-async function loadVaultEntry(key) {
-    try {
-        const entry = await (0, convex_js_1.callConvex)(`/vault/entry?key=${encodeURIComponent(key)}`, "GET", undefined, "vault_read");
-        if (!entry?.content)
-            return null;
-        return {
-            key: entry.key ?? key,
-            title: entry.title ?? key,
-            content: entry.content,
-            updatedAt: entry.updatedAt,
-        };
-    }
-    catch {
-        return null;
-    }
-}
-function slugifyKey(key) {
-    return key.replace(/^research\//, "").replace(/[^a-z0-9-]/gi, "-").slice(0, 50);
-}
-// ─── Structural diff ──────────────────────────────────────────────────────────
-// Mechanical work the caller shouldn't have to eyeball: which sections exist in
-// one report and not the other, and how the bodies differ in size. It is not a
-// judgement about what changed - that's the caller's job - but it tells them
-// where to look first.
-function sectionHeadings(content) {
-    const out = [];
-    for (const line of content.split("\n")) {
-        const m = line.match(/^#{2,3}\s+(.+?)\s*$/);
-        if (m)
-            out.push(m[1].replace(/[*`]/g, "").trim());
-    }
-    return out;
-}
-function normHeading(h) {
-    return h.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
-}
-function diffStructure(a, b) {
-    const ha = sectionHeadings(a);
-    const hb = sectionHeadings(b);
-    const na = new Map(ha.map((h) => [normHeading(h), h]));
-    const nb = new Map(hb.map((h) => [normHeading(h), h]));
-    const onlyInA = [];
-    const onlyInB = [];
-    const shared = [];
-    for (const [k, h] of na)
-        (nb.has(k) ? shared : onlyInA).push(h);
-    for (const [k, h] of nb)
-        if (!na.has(k))
-            onlyInB.push(h);
-    return { onlyInA, onlyInB, shared };
-}
-// The discipline the old synthesis prompt enforced, moved into the output so
-// the user can see it and steer it. The "Weakened or Removed" section is the
-// one that matters most and the one a model skips first if not told to keep it.
-function comparisonRubric(dateA, dateB, focus) {
-    return [
-        `## Write the comparison from this`,
-        ``,
-        `Show what **changed** in the understanding — not a side-by-side rehash of both reports.`,
-        ``,
-        `### TL;DR`,
-        `2-3 sentences. Lead with the most important shift. No filler.`,
-        ``,
-        `### Net Direction`,
-        `One line: **STRENGTHENED** / **WEAKENED** / **PIVOTED** / **REFINED**, then 1-2 sentences on why.`,
-        ``,
-        `### At a Glance`,
-        `A table with exactly these columns, 5-8 rows of the most important shifts, ↑/↓/→/⚡/❓ in Change:`,
-        ``,
-        `| Dimension | ${dateA} (A) | ${dateB} (B) | Change |`,
-        `|---|---|---|---|`,
-        ``,
-        `### 🆕 New in B`,
-        `3-6 bullets — findings, entities or data points present in B and absent from A.`,
-        ``,
-        `### 🔄 Updated`,
-        `3-6 bullets, each as "{Claim}: was {A's position}, now {B's position}".`,
-        ``,
-        `### ⚠️ Weakened or Removed`,
-        `2-4 bullets — claims A made that B contradicts, drops, or is less confident about. ` +
-            `**Do not skip this section.** It is the "what we got wrong" record and it is the whole point of ` +
-            `comparing. If nothing weakened, say so explicitly rather than omitting the heading.`,
-        ``,
-        `### Confidence Shift`,
-        `Did overall confidence rise or fall? Are B's sources stronger? Are its predictions more grounded?`,
-        ``,
-        `### What to Watch Next`,
-        `3-4 forward-looking questions this comparison raised.`,
-        ``,
-        `**Rules:** quote actual numbers and names from both bodies. No hedging filler. If A was right and B ` +
-            `is worse-sourced, say that. Don't manufacture differences — an unchanged dimension gets one line.` +
-            (focus ? ` **Focus on ${focus}; down-weight everything else.**` : ""),
-        ``,
-        `When you're done, call \`research_compare\` again with the same keys plus \`comparison: "<your markdown>"\` ` +
-            `to save it to the vault and link it to both sources.`,
-    ].join("\n");
-}
-// ─── Handler ──────────────────────────────────────────────────────────────────
-async function handleResearchCompare(name, args) {
-    if (name !== "research_compare")
-        return null;
-    const parsed = InputSchema.safeParse(args);
-    if (!parsed.success) {
-        return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
-    }
-    const { keyA, keyB, focus, comparison } = parsed.data;
-    const saveToVault = parsed.data.saveToVault ?? true;
-    const maxChars = parsed.data.maxChars ?? 12000;
-    if (keyA === keyB) {
-        return { content: [{ type: "text", text: "keyA and keyB are the same - comparison needs two different reports." }], isError: true };
-    }
-    // Load both reports in parallel
-    const progress = [];
-    const log = (line) => progress.push(line);
-    log(`📂 Loading report A: \`${keyA}\``);
-    log(`📂 Loading report B: \`${keyB}\``);
-    const [reportA, reportB] = await Promise.all([loadVaultEntry(keyA), loadVaultEntry(keyB)]);
-    if (!reportA) {
-        return { content: [{ type: "text", text: `Could not load report A (\`${keyA}\`). Check the vault key is correct and you're authenticated. Use vault_list type:research to find candidates.` }], isError: true };
-    }
-    if (!reportB) {
-        return { content: [{ type: "text", text: `Could not load report B (\`${keyB}\`). Check the vault key is correct.` }], isError: true };
-    }
-    log(`✅ Loaded A (${reportA.content.length} chars) and B (${reportB.content.length} chars).`);
-    const dateA = reportA.updatedAt ? new Date(reportA.updatedAt).toISOString().slice(0, 10) : "earlier";
-    const dateB = reportB.updatedAt ? new Date(reportB.updatedAt).toISOString().slice(0, 10) : "later";
-    // ── PASS 2: caller brought the finished comparison - save it and link it ──
-    if (comparison) {
-        let compareKey = null;
-        if (saveToVault) {
-            try {
-                const titleA = reportA.title.replace(/^Deep Research(?:\s*\(cont\.\))?:\s*/i, "").slice(0, 30);
-                const titleB = reportB.title.replace(/^Deep Research(?:\s*\(cont\.\))?:\s*/i, "").slice(0, 30);
-                const r = (await (0, convex_js_1.callConvex)("/vault/save", "POST", {
-                    type: "research",
-                    title: `Compare: ${titleA} vs ${titleB}`,
-                    content: comparison,
-                    tags: ["research-compare", "comparison", ...(focus ? [`focus:${focus}`] : [])],
-                    agentId: "research",
-                    commitMsg: `compare ${slugifyKey(keyA)} vs ${slugifyKey(keyB)}`,
-                }, "vault_save"));
-                compareKey = r?.key ?? null;
-                log(`💾 Saved comparison to vault: \`${compareKey}\``);
-            }
-            catch {
-                log(`⚠️ Vault save skipped (not authenticated).`);
-            }
-        }
-        // Auto-link to both source reports
-        if (compareKey) {
-            for (const target of [keyA, keyB]) {
-                try {
-                    await (0, convex_js_1.callConvex)("/vault/link", "POST", {
-                        fromKey: compareKey,
-                        toKey: target,
-                        relation: "references",
-                    }, "vault_link");
-                }
-                catch { /* silent */ }
-            }
-            log(`🔗 Linked comparison → ${keyA} (references)`);
-            log(`🔗 Linked comparison → ${keyB} (references)`);
-        }
-        return {
-            content: [{
-                    type: "text",
-                    text: [
-                        compareKey
-                            ? `📊 **Comparison saved** — \`${compareKey}\`, linked to \`${keyA}\` and \`${keyB}\`.`
-                            : `📊 **Comparison not saved** — vault write unavailable (not authenticated) or \`saveToVault: false\`.`,
-                        `🧬 Your knowledge base is now queryable across time.`,
-                        ``,
-                        `<details><summary>📋 Process log</summary>`,
-                        ``,
-                        progress.map((p) => `- ${p}`).join("\n"),
-                        ``,
-                        `</details>`,
-                    ].join("\n"),
-                }],
-        };
-    }
-    // ── PASS 1: return both bodies + the structural diff + the rubric ────────
-    const struct = diffStructure(reportA.content, reportB.content);
-    log(`🔍 Structural diff: ${struct.shared.length} shared sections, ${struct.onlyInA.length} only in A, ${struct.onlyInB.length} only in B.`);
-    const clip = (s) => s.length > maxChars
-        ? `${s.slice(0, maxChars)}\n\n…[truncated ${s.length - maxChars} chars — raise \`maxChars\` for the rest]`
-        : s;
-    const structLines = [
-        `**Sections only in A:** ${struct.onlyInA.length ? struct.onlyInA.join(" · ") : "none"}`,
-        `**Sections only in B:** ${struct.onlyInB.length ? struct.onlyInB.join(" · ") : "none"}`,
-        `**Shared sections:** ${struct.shared.length ? struct.shared.join(" · ") : "none"}`,
-        `**Length:** A ${reportA.content.length.toLocaleString()} chars → B ${reportB.content.length.toLocaleString()} chars ` +
-            `(${reportB.content.length >= reportA.content.length ? "+" : ""}${(((reportB.content.length - reportA.content.length) / Math.max(reportA.content.length, 1)) * 100).toFixed(0)}%)`,
-    ].join("\n");
-    const text = [
-        `📊 **Research Compare** — \`${reportA.key}\` ⇄ \`${reportB.key}\``,
-        ``,
-        `<details><summary>📋 Process log</summary>`,
-        ``,
-        progress.map((p) => `- ${p}`).join("\n"),
-        ``,
-        `</details>`,
-        ``,
-        `## Structural diff`,
-        ``,
-        structLines,
-        ``,
-        `---`,
-        ``,
-        `## Report A — ${dateA} · ${reportA.title}`,
-        `\`${reportA.key}\``,
-        ``,
-        clip(reportA.content),
-        ``,
-        `---`,
-        ``,
-        `## Report B — ${dateB} · ${reportB.title}`,
-        `\`${reportB.key}\``,
-        ``,
-        clip(reportB.content),
-        ``,
-        `---`,
-        ``,
-        comparisonRubric(dateA, dateB, focus),
-    ].join("\n");
-    return { content: [{ type: "text", text }] };
-}