@finchagentic/mcp 4.0.0

package/dist/index.js

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const server_js_1 = require("./server.js");
+const tool_filter_js_1 = require("./tool-filter.js");
+const wallet_js_1 = require("./wallet.js");
+const config_js_1 = require("./config.js");
+const clink_input_js_1 = require("./clink-input.js");
+const readline = __importStar(require("readline"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// Always read the version from package.json so banner + boot strings stay in
+// sync after every npm publish - no more hand-edits in three places.
+const PKG_VERSION = (() => {
+    try {
+        // dist/index.js -> ../package.json (CJS so __dirname is available)
+        const raw = fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8");
+        return JSON.parse(raw).version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+})();
+const CONVEX_SITE = process.env.FINCH_CONVEX_URL ?? "https://befitting-porcupine-276.convex.site";
+// ── ANSI helpers ──────────────────────────────────────────────────────────────
+const C = {
+    cyan: "\x1b[36m",
+    dim: "\x1b[90m",
+    white: "\x1b[97m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+};
+const BANNER = `
+${C.cyan}
+  ███╗   ██╗ ██████╗ ███████╗██╗      ██████╗██╗      █████╗ ██╗    ██╗
+  ████╗  ██║██╔═══██╗██╔════╝██║     ██╔════╝██║     ██╔══██╗██║    ██║
+  ██╔██╗ ██║██║   ██║█████╗  ██║     ██║     ██║     ███████║██║ █╗ ██║
+  ██║╚██╗██║██║   ██║██╔══╝  ██║     ██║     ██║     ██╔══██║██║███╗██║
+  ██║ ╚████║╚██████╔╝███████╗███████╗╚██████╗███████╗██║  ██║╚███╔███╔╝
+  ╚═╝  ╚═══╝ ╚═════╝ ╚══════╝╚══════╝ ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝
+${C.reset}`;
+function line(label, value, color = C.cyan) {
+    const pad = " ".repeat(Math.max(0, 12 - label.length));
+    process.stderr.write(`  ${color}▸ ${label}${C.reset}${pad}${value}\n`);
+}
+function divider() {
+    process.stderr.write(`  ${C.dim}${"─".repeat(58)}${C.reset}\n`);
+}
+async function checkForUpdate(current) {
+    try {
+        const res = await fetch("https://registry.npmjs.org/@finchagentic/mcp/latest", {
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!res.ok)
+            return;
+        const data = await res.json();
+        const latest = data.version;
+        if (!latest || latest === current)
+            return;
+        // Show update notice to stderr - visible in Claude Desktop logs and terminal.
+        const sep = `  ${"─".repeat(58)}`;
+        process.stderr.write(`\n${sep}\n` +
+            `  ${C.yellow}⚠${C.reset}  Update available: ${C.yellow}v${current}${C.reset} → ${C.cyan}v${latest}${C.reset}\n` +
+            `     ${C.dim}npm install -g @finchagentic/mcp@${latest}${C.reset}  ${C.dim}or restart your MCP client${C.reset}\n` +
+            `${sep}\n\n`);
+    }
+    catch {
+        // Non-blocking - silently ignore network errors
+    }
+}
+async function main() {
+    (0, config_js_1.hydrateEnvFromConfig)();
+    process.stderr.write(BANNER);
+    const CAT_RULES = [
+        { label: "Market", match: n => /^(get_market_data|get_token_data|compare_tokens|market_overview|token_history)$/.test(n) },
+        { label: "Insight", match: n => /^(ask_finch|market_thesis|trade_plan)$/.test(n) },
+        { label: "DeFi", match: n => n === "get_defi_yields" },
+        { label: "Base MCP", match: n => n.startsWith("base_mcp_") },
+        { label: "RH MCP", match: n => n.startsWith("rh_") },
+        { label: "Automation", match: n => /^(create_automation|list_automations|pause_automation|delete_automation|get_automation_runs|run_automation)$/.test(n) },
+        { label: "Framework", match: n => /^(list_playbooks|run_playbook|get_finch_ledger)$/.test(n) },
+        { label: "Vault", match: n => n.startsWith("vault_") },
+        { label: "Wallet", match: n => /^(get_wallet_address|get_wallet_balance|wallet_sign_message)$/.test(n) },
+        { label: "MiroShark", match: n => n.startsWith("miroshark_") },
+        { label: "Scanner", match: n => /^(scan_market|score_token|check_token)$/.test(n) },
+        { label: "Agents", match: n => n.startsWith("agent_") || n === "list_agents" || n === "hire_agent" },
+        { label: "Coder", match: n => n === "audit_contract" },
+        { label: "Base", match: n => /^(query_vaults|list_markets|prepare_deposit|chain_stats)$/.test(n) },
+        { label: "Memory", match: n => n.startsWith("memory_") },
+        { label: "OS", match: n => /^(finch_status|finch_diagnostics|finch_shell_chat)$/.test(n) },
+        { label: "Research", match: n => /^(web_scrape|web_search|deep_research|research_compare|research_chain)$/.test(n) },
+        { label: "Monitor", match: n => /^(schedule_research|create_monitor|list_monitors|cancel_monitor)$/.test(n) },
+        { label: "GitHub", match: n => n.startsWith("github_") },
+        { label: "Chronicle", match: n => n.startsWith("chronicle_") },
+        { label: "Packets", match: n => n.startsWith("packet_") },
+    ];
+    const categories = CAT_RULES
+        .map(rule => {
+        const names = server_js_1.ALL_TOOLS.map(t => t.name).filter(rule.match);
+        return { label: rule.label, count: names.length, tools: names.join(" · ") };
+    })
+        .filter(c => c.count > 0);
+    const total = server_js_1.ALL_TOOLS.length;
+    // What the connected client actually sees - the LIST response is filtered by
+    // FINCH_TOOLS (default "core"). Showing this next to the registered total
+    // stops the banner from claiming 121 while the client only sees the core set.
+    const exposed = (0, tool_filter_js_1.filterTools)(server_js_1.ALL_TOOLS).length;
+    const toolMode = process.env.FINCH_TOOLS ?? "core";
+    divider();
+    process.stderr.write(`\n`);
+    // Tools don't run inference - the connected client's model does. A provider
+    // is shown only because the CLI agent loop and scheduled agents use one; its
+    // absence is the normal, fully-working state for an MCP client.
+    const model = process.env.FINCH_MODEL ?? "claude-haiku-4-5-20251001";
+    const aiMode = process.env.BANKR_API_KEY
+        ? `Bankr  ${C.dim}${model}${C.reset}`
+        : process.env.ANTHROPIC_API_KEY
+            ? `Anthropic  ${C.dim}${model}${C.reset}`
+            : process.env.OPENAI_API_KEY
+                ? `OpenAI  ${C.dim}${model}${C.reset}`
+                : `your client's model  ${C.dim}no key needed${C.reset}`;
+    line("version", `v${PKG_VERSION}`);
+    line("ai", aiMode);
+    const toolDetail = exposed === total
+        ? `${C.white}${C.bold}${total} tools exposed${C.reset}  ${C.dim}across ${categories.length} categories${C.reset}`
+        : `${C.white}${C.bold}${exposed} tools exposed${C.reset}  ${C.dim}(${toolMode} of ${total} registered · set FINCH_TOOLS=all for every tool)${C.reset}`;
+    line("tools", toolDetail);
+    process.stderr.write(`\n`);
+    divider();
+    process.stderr.write(`\n`);
+    // ── Categories grid ────────────────────────────────────────────────────────
+    for (const cat of categories) {
+        const countStr = `${cat.count}`.padStart(2);
+        process.stderr.write(`  ${C.dim}│${C.reset} ${C.cyan}${cat.label.padEnd(11)}${C.reset} ${C.dim}${countStr}x${C.reset}  ${C.dim}${cat.tools}${C.reset}\n`);
+    }
+    process.stderr.write(`\n`);
+    divider();
+    // ── Wallet + start ─────────────────────────────────────────────────────────
+    await (0, server_js_1.startServer)();
+    const hasAuth = !!(0, config_js_1.getSavedToken)();
+    try {
+        const wallet = await (0, wallet_js_1.getOrCreateWallet)();
+        process.stderr.write(`\n`);
+        line("wallet", wallet.address);
+        if (hasAuth) {
+            line("auth", `${C.green}signed in${C.reset}  ${C.dim}all ${server_js_1.ALL_TOOLS.length} tools unlocked${C.reset}`, C.green);
+        }
+        else {
+            line("auth", `${C.yellow}not signed in${C.reset}  ${C.dim}run 'finch login' to unlock premium tools${C.reset}`, C.yellow);
+        }
+        line("status", `${C.green}ready${C.reset}  ${C.dim}waiting for MCP client...${C.reset}`, C.green);
+        process.stderr.write(`\n`);
+    }
+    catch {
+        process.stderr.write(`\n`);
+        line("wallet", `${C.yellow}not configured${C.reset}  ${C.dim}run 'finch login' to set up${C.reset}`, C.yellow);
+        line("status", `${C.green}ready${C.reset}  ${C.dim}wallet tools require setup${C.reset}`, C.green);
+        process.stderr.write(`\n`);
+    }
+    // Check for updates async - fires 3s after startup so it doesn't delay boot
+    setTimeout(() => { checkForUpdate(PKG_VERSION).catch(() => { }); }, 3000);
+}
+// Interactive sign-in for the `finch-mcp login` path. Kept identical to the
+// canonical `finch login` (cli.ts): both accept a Finch API key
+// (finch_sk_...) and exchange it for a session token at /auth/apikey/login.
+// Earlier this asked for a raw "session token" against /auth/me - a different
+// credential users never actually generate, so the two bins disagreed on what
+// "login" meant.
+async function loginFlow() {
+    process.stderr.write(`\n  ${C.cyan}▸ finch login${C.reset}\n\n`);
+    process.stderr.write(`  Generate an API key at ${C.cyan}app.finchagentic.com${C.reset} → Settings → API Keys\n\n`);
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    let apiKey = await new Promise((resolve) => {
+        rl.question(`  API key (finch_sk_... / noel_sk_...): `, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+    // Deduplicate doubled input from a known Clink terminal bug + strip non-ASCII.
+    apiKey = (0, clink_input_js_1.dedupClinkInput)(apiKey).replace(/[^\x20-\x7E]/g, "").trim();
+    if (!(0, config_js_1.isApiKey)(apiKey)) {
+        process.stderr.write(`\n  ${C.yellow}✗ Invalid key — should start with finch_sk_ or noel_sk_${C.reset}\n\n`);
+        process.exit(1);
+    }
+    try {
+        const res = await fetch(`${CONVEX_SITE}/auth/apikey/login`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ apiKey }),
+            signal: AbortSignal.timeout(8000),
+        });
+        const data = await res.json();
+        if (!res.ok || !data.token) {
+            process.stderr.write(`\n  ${C.yellow}✗ ${data.error ?? "Invalid API key"} — check it at app.finchagentic.com${C.reset}\n\n`);
+            process.exit(1);
+        }
+        (0, config_js_1.writeConfig)({ sessionToken: data.token, email: data.email, name: data.displayName ?? undefined });
+        process.stderr.write(`\n  ${C.green}✓ Signed in as ${data.email ?? data.displayName ?? "user"}${C.reset}\n`);
+        process.stderr.write(`  ${C.dim}Token saved to ~/.finch/config.json${C.reset}\n`);
+        process.stderr.write(`  ${C.dim}All ${server_js_1.ALL_TOOLS.length} tools now unlocked.${C.reset}\n\n`);
+    }
+    catch (err) {
+        process.stderr.write(`\n  ${C.red}✗ Login failed: ${err.message}${C.reset}\n\n`);
+        process.exit(1);
+    }
+    process.exit(0);
+}
+const cmd = process.argv[2];
+if (cmd === "login") {
+    loginFlow().catch((err) => {
+        process.stderr.write(`[finch] login error: ${err}\n`);
+        process.exit(1);
+    });
+}
+else {
+    main().catch((err) => {
+        process.stderr.write(`[finch] fatal: ${err}\n`);
+        process.exit(1);
+    });
+}

package/dist/llm.js

@@ -0,0 +1,323 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasDirectLLMKey = hasDirectLLMKey;
+exports.grokLiveSearchHits = grokLiveSearchHits;
+exports.isGrokActive = isGrokActive;
+exports.callLLM = callLLM;
+const wallet_js_1 = require("./wallet.js");
+const config_js_1 = require("./config.js");
+const ANTHROPIC_URL = "https://api.anthropic.com/v1/messages";
+const BANKR_URL = "https://llm.bankr.bot/v1/chat/completions";
+const GROK_URL = "https://api.x.ai/v1/chat/completions";
+const OPENAI_URL = "https://api.openai.com/v1/chat/completions";
+const CONVEX_SITE = process.env.FINCH_CONVEX_URL ?? "https://befitting-porcupine-276.convex.site";
+/**
+ * Returns true if Grok is the currently active LLM provider, based on env.
+ * Useful for tools that want to conditionally enable Grok-specific features
+ * like Live Search.
+ */
+/**
+ * True if any BYOK provider key (Bankr/Anthropic/OpenAI/Grok) is set. Callers
+ * that must never fall through to callViaConvex() - e.g. local-memory mode,
+ * which promises zero Convex involvement - should check this first and fail
+ * clearly instead of letting callLLM() silently proxy through Finch.
+ */
+function hasDirectLLMKey() {
+    return !!(process.env.BANKR_API_KEY || process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY || process.env.GROK_API_KEY);
+}
+/**
+ * Grok Live Search used purely as a RETRIEVAL layer.
+ *
+ * X/news content is the one thing an MCP client genuinely cannot reach on its
+ * own, which makes fetching it real tool work. Interpreting it is not — so this
+ * asks Grok to return the found items verbatim and hands them upward as sources.
+ * The caller's model decides what any of it means.
+ *
+ * Returns [] on any failure: live search is an augmentation, never a hard
+ * dependency, and research must still work without a Grok key.
+ */
+async function grokLiveSearchHits(query, sources = ["x", "news", "web"], days, maxResults = 10) {
+    const apiKey = process.env.GROK_API_KEY;
+    if (!apiKey)
+        return [];
+    const body = {
+        model: process.env.FINCH_GROK_MODEL ?? "grok-4.3",
+        max_tokens: 2000,
+        messages: [
+            {
+                role: "system",
+                content: "You are a retrieval tool, not an analyst. Return what you find verbatim. " +
+                    "Never summarise, interpret, rank by opinion, or add commentary.",
+            },
+            {
+                role: "user",
+                content: `Search for: ${query}\n\n` +
+                    `Return up to ${maxResults} of the most relevant recent items, one per line, ` +
+                    `in exactly this format:\n\n` +
+                    `URL :: verbatim quote or post text (max 400 chars)\n\n` +
+                    `Rules: quote the source's own words. Do not paraphrase. Do not add analysis, ` +
+                    `conclusions, or your own framing. If an item has no URL, use "-" for the URL.`,
+            },
+        ],
+        search_parameters: {
+            mode: "on",
+            sources: sources.map((type) => ({ type })),
+            max_search_results: maxResults,
+            ...(days ? { from_date: new Date(Date.now() - days * 86400000).toISOString().slice(0, 10) } : {}),
+        },
+    };
+    try {
+        const res = await fetch(GROK_URL, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(45000),
+        });
+        if (!res.ok)
+            return [];
+        const data = (await res.json());
+        const content = data.choices?.[0]?.message?.content ?? "";
+        const hits = [];
+        for (const line of content.split("\n")) {
+            const idx = line.indexOf("::");
+            if (idx === -1)
+                continue;
+            const url = line.slice(0, idx).trim().replace(/^[-*\d.\s]+/, "");
+            const excerpt = line.slice(idx + 2).trim();
+            if (excerpt.length < 20)
+                continue;
+            hits.push({ url: /^https?:\/\//.test(url) ? url : "", excerpt });
+        }
+        // If the model ignored the format, fall back to bare citations so the
+        // caller still receives the URLs rather than nothing.
+        if (hits.length === 0 && data.citations?.length) {
+            return data.citations.slice(0, maxResults).map((url) => ({ url, excerpt: "" }));
+        }
+        return hits.slice(0, maxResults);
+    }
+    catch {
+        return [];
+    }
+}
+function isGrokActive() {
+    const provider = process.env.FINCH_PROVIDER?.toLowerCase().trim();
+    if (provider === "grok")
+        return !!process.env.GROK_API_KEY;
+    if (provider === "bankr" || provider === "anthropic" || provider === "openai")
+        return false;
+    // Auto-priority - Grok is only active if it's the only key present
+    if (process.env.BANKR_API_KEY || process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY)
+        return false;
+    return !!process.env.GROK_API_KEY;
+}
+/**
+ * Call the best available LLM.
+ *
+ * Provider auto-priority (when FINCH_PROVIDER unset):
+ *   BANKR_API_KEY → ANTHROPIC_API_KEY → OPENAI_API_KEY → GROK_API_KEY → Convex backend
+ *
+ * Force a provider via FINCH_PROVIDER: "bankr" | "anthropic" | "openai" | "grok"
+ *
+ * Model selection (first wins):
+ *   FINCH_MODEL → {provider}_MODEL → provider default
+ */
+async function callLLM(systemPrompt, userPrompt, maxTokens = 1024, history = [], timeoutMs = 60000, options = {}) {
+    const provider = process.env.FINCH_PROVIDER?.toLowerCase().trim();
+    const bankrKey = process.env.BANKR_API_KEY;
+    const anthropicKey = process.env.ANTHROPIC_API_KEY;
+    const openaiKey = process.env.OPENAI_API_KEY;
+    const grokKey = process.env.GROK_API_KEY;
+    // Explicit provider override - user picked one
+    if (provider === "grok" && grokKey)
+        return callGrok(grokKey, systemPrompt, userPrompt, maxTokens, history, timeoutMs, options.liveSearch, options.model);
+    if (provider === "anthropic" && anthropicKey)
+        return callAnthropic(anthropicKey, systemPrompt, userPrompt, maxTokens, history, timeoutMs, options.model);
+    if (provider === "openai" && openaiKey)
+        return callOpenAI(openaiKey, systemPrompt, userPrompt, maxTokens, history, timeoutMs, options.model);
+    if (provider === "bankr" && bankrKey)
+        return callBankr(bankrKey, systemPrompt, userPrompt, maxTokens, history, timeoutMs, options.model);
+    // Auto priority
+    if (bankrKey)
+        return callBankr(bankrKey, systemPrompt, userPrompt, maxTokens, history, timeoutMs, options.model);
+    if (anthropicKey)
+        return callAnthropic(anthropicKey, systemPrompt, userPrompt, maxTokens, history, timeoutMs, options.model);
+    if (openaiKey)
+        return callOpenAI(openaiKey, systemPrompt, userPrompt, maxTokens, history, timeoutMs, options.model);
+    if (grokKey)
+        return callGrok(grokKey, systemPrompt, userPrompt, maxTokens, history, timeoutMs, options.liveSearch, options.model);
+    // Fallback: route through Convex backend - owner covers cost
+    return callViaConvex(systemPrompt, userPrompt, history, timeoutMs);
+}
+async function callViaConvex(systemPrompt, userPrompt, history, timeoutMs) {
+    const fullQuestion = systemPrompt
+        ? `[System: ${systemPrompt}]\n\n${userPrompt}`
+        : userPrompt;
+    const headers = { "Content-Type": "application/json" };
+    const apiKey = process.env.FINCH_API_KEY;
+    let sessionToken = process.env.FINCH_SESSION_TOKEN;
+    // Read from config file — this is the resolved session token after login
+    try {
+        const cfg = (0, config_js_1.readConfig)();
+        if (cfg.sessionToken)
+            sessionToken = cfg.sessionToken;
+    }
+    catch { /* ignore */ }
+    // Prefer session token (resolved by backend) over API key for /mcp/chat
+    if (sessionToken) {
+        headers["Authorization"] = `Bearer ${sessionToken}`;
+    }
+    else if (apiKey) {
+        headers["Authorization"] = `Bearer ${apiKey}`;
+    }
+    else {
+        try {
+            const { address, signature, timestamp } = await (0, wallet_js_1.signRequest)("ask_finch");
+            headers["X-Wallet-Address"] = address;
+            headers["X-Wallet-Signature"] = signature;
+            headers["X-Wallet-Timestamp"] = timestamp;
+        }
+        catch { /* proceed without wallet auth */ }
+    }
+    const res = await fetch(`${CONVEX_SITE}/mcp/chat`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ question: fullQuestion, messages: history }),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`LLM error ${res.status}: ${body.slice(0, 200)}`);
+    }
+    const data = await res.json();
+    return data.answer ?? "";
+}
+async function callAnthropic(apiKey, systemPrompt, userPrompt, maxTokens, history, timeoutMs, modelOverride) {
+    const messages = [...history, { role: "user", content: userPrompt }];
+    const model = modelOverride ?? process.env.FINCH_MODEL ?? process.env.ANTHROPIC_MODEL ?? "claude-haiku-4-5-20251001";
+    const res = await fetch(ANTHROPIC_URL, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "x-api-key": apiKey,
+            "anthropic-version": "2023-06-01",
+        },
+        body: JSON.stringify({ model, max_tokens: maxTokens, system: systemPrompt, messages }),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`Anthropic error ${res.status}: ${body.slice(0, 200)}`);
+    }
+    const data = await res.json();
+    return data.content?.find(b => b.type === "text")?.text ?? "";
+}
+async function callBankr(apiKey, systemPrompt, userPrompt, maxTokens, history, timeoutMs, modelOverride) {
+    const model = modelOverride ?? process.env.FINCH_MODEL ?? process.env.BANKR_MODEL ?? "claude-haiku-4-5-20251001";
+    const res = await fetch(BANKR_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "X-API-Key": apiKey },
+        body: JSON.stringify({
+            model,
+            messages: [
+                { role: "system", content: systemPrompt },
+                ...history,
+                { role: "user", content: userPrompt },
+            ],
+            max_tokens: maxTokens,
+        }),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`Bankr error ${res.status}: ${body.slice(0, 200)}`);
+    }
+    const data = await res.json();
+    return data.choices?.[0]?.message?.content ?? "";
+}
+// OPENAI_BASE_URL lets this point at any OpenAI Chat Completions-compatible
+// endpoint instead of api.openai.com - self-hosted gateways (LiteLLM, vLLM,
+// Ollama, LocalAI) and aggregators (OpenRouter) all speak this same API
+// shape, so no separate provider code is needed for them.
+function openAiChatUrl() {
+    const base = process.env.OPENAI_BASE_URL?.replace(/\/+$/, "");
+    return base ? `${base}/chat/completions` : OPENAI_URL;
+}
+async function callOpenAI(apiKey, systemPrompt, userPrompt, maxTokens, history, timeoutMs, modelOverride) {
+    const model = modelOverride ?? process.env.FINCH_MODEL ?? process.env.OPENAI_MODEL ?? "gpt-4o-mini";
+    const res = await fetch(openAiChatUrl(), {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+        body: JSON.stringify({
+            model,
+            messages: [
+                { role: "system", content: systemPrompt },
+                ...history,
+                { role: "user", content: userPrompt },
+            ],
+            max_tokens: maxTokens,
+        }),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`OpenAI error ${res.status}: ${body.slice(0, 200)}`);
+    }
+    const data = await res.json();
+    return data.choices?.[0]?.message?.content ?? "";
+}
+async function callGrok(apiKey, systemPrompt, userPrompt, maxTokens, history, timeoutMs, liveSearch, modelOverride) {
+    const model = modelOverride ?? process.env.FINCH_MODEL ?? process.env.GROK_MODEL ?? "grok-4-fast-reasoning";
+    const body = {
+        model,
+        messages: [
+            { role: "system", content: systemPrompt },
+            ...history,
+            { role: "user", content: userPrompt },
+        ],
+        max_tokens: maxTokens,
+        stream: false,
+    };
+    // xAI Live Search - pulls real-time results from web/X/news/RSS during inference.
+    // Docs: https://docs.x.ai/docs/guides/live-search
+    // Note: as of late 2026 xAI deprecated this in favor of Agent Tools API
+    // (returns 410 Gone). We detect that and retry without search_parameters
+    // so synthesis still succeeds - just without the real-time augmentation.
+    if (liveSearch) {
+        body.search_parameters = {
+            mode: liveSearch.mode,
+            sources: liveSearch.sources.map((type) => ({ type })),
+            max_search_results: liveSearch.maxResults ?? 10,
+            ...(liveSearch.fromDate ? { from_date: liveSearch.fromDate } : {}),
+            ...(liveSearch.toDate ? { to_date: liveSearch.toDate } : {}),
+        };
+    }
+    let res = await fetch(GROK_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "Authorization": `Bearer ${apiKey}` },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    // Live Search deprecated → strip search_parameters and retry
+    if (res.status === 410 && liveSearch) {
+        delete body.search_parameters;
+        res = await fetch(GROK_URL, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "Authorization": `Bearer ${apiKey}` },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    if (!res.ok) {
+        const errBody = await res.text().catch(() => "");
+        throw new Error(`Grok error ${res.status}: ${errBody.slice(0, 200)}`);
+    }
+    const data = await res.json();
+    const content = data.choices?.[0]?.message?.content ?? "";
+    // When Live Search ran (and was not deprecated), append the citations as a
+    // parsable block at the bottom - downstream consumers (deep_research) can
+    // read these and merge into the final source list.
+    if (liveSearch && data.citations && data.citations.length > 0) {
+        return `${content}\n\n<!--GROK_LIVE_CITATIONS\n${data.citations.join("\n")}\nGROK_LIVE_CITATIONS-->`;
+    }
+    return content;
+}