@finchagentic/mcp 4.6.0 → 4.6.2

package/dist/tools/defi.js

@@ -1,292 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFI_TOOLS = void 0;
-exports.buildDefiYields = buildDefiYields;
-exports.handleDefiTool = handleDefiTool;
-const zod_1 = require("zod");
-const convex_js_1 = require("../convex.js");
-const wallet_js_1 = require("../wallet.js");
-const token_decimals_js_1 = require("../token-decimals.js");
-exports.DEFI_TOOLS = [
-    {
-        name: "get_defi_yields",
-        description: "Fetch top DeFi yield opportunities on Base - Morpho, Moonwell, Aerodrome, Uniswap, and more. " +
-            "Returns APY, TVL, and pool info aggregated from DeFiLlama (no API key required) - broadest " +
-            "protocol coverage, but DeFiLlama's numbers can lag the protocol's own API by hours. Good first " +
-            "stop for comparing across protocols. For the freshest Morpho-vault-specific numbers use " +
-            "base_mcp_yield_vaults instead; for the freshest Moonwell supply/borrow rates use " +
-            "base_mcp_lending_rates instead - both query the protocol directly. " +
-            "Filter by token or minimum APY. Use before depositing to find the best rates.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                token: { type: "string", description: "Optional: filter by token symbol, e.g. 'USDC', 'ETH', 'WETH'" },
-                minApy: { type: "number", description: "Optional: minimum APY % to show (default 1)" },
-                limit: { type: "number", description: "Max results to return (default 20)" },
-            },
-            required: [],
-        },
-    },
-];
-const SwapSchema = zod_1.z.object({
-    fromToken: zod_1.z.string().min(1),
-    toToken: zod_1.z.string().min(1),
-    amount: zod_1.z.string().min(1),
-    maxSlippagePct: zod_1.z.number().positive().max(50).optional(),
-    maxPriceImpactPct: zod_1.z.number().positive().max(50).optional(),
-});
-const DEFAULT_MAX_SLIPPAGE_PCT = 1.0;
-const DEFAULT_MAX_PRICE_IMPACT_PCT = 3.0;
-const SendSchema = zod_1.z.object({ token: zod_1.z.string().min(1), toAddress: zod_1.z.string().regex(/^0x[0-9a-fA-F]{40}$/, "must be a valid 0x address"), amount: zod_1.z.string().min(1) });
-const DefiYieldsSchema = zod_1.z.object({
-    token: zod_1.z.string().optional(),
-    minApy: zod_1.z.number().optional(),
-    limit: zod_1.z.number().int().min(1).max(100).optional(),
-}).default({});
-function formatTokenAmount(raw, token) {
-    const dec = (0, token_decimals_js_1.decimalsFor)(token);
-    // Unknown decimals: show raw units rather than a confidently wrong number.
-    if (dec === undefined)
-        return `${raw} (raw units — decimals unknown)`;
-    // BigInt math: parseInt on an 18-digit wei string loses precision past
-    // MAX_SAFE_INTEGER.
-    try {
-        const places = dec === 6 ? 2 : 6;
-        const scale = 10n ** BigInt(dec);
-        const value = BigInt(raw);
-        const whole = value / scale;
-        const frac = (value % scale).toString().padStart(dec, "0").slice(0, places);
-        return places > 0 ? `${whole}.${frac}` : `${whole}`;
-    }
-    catch {
-        return raw;
-    }
-}
-// Structured output builder for get_defi_yields (schema in output-schemas.ts).
-function buildDefiYields(token, minApy, pools) {
-    return {
-        token: token ? token.toUpperCase() : null,
-        minApy,
-        count: pools.length,
-        pools: pools.map((p) => ({
-            symbol: p.symbol ?? p.pool ?? null,
-            project: p.project ?? null,
-            apyPct: p.apy ?? null,
-            tvlUsd: p.tvlUsd ?? null,
-            chain: p.chain ?? null,
-        })),
-    };
-}
-async function handleDefiTool(name, args) {
-    switch (name) {
-        case "get_portfolio": {
-            const result = await (0, convex_js_1.callConvex)("/mcp/defi/portfolio", "GET", undefined, "get_portfolio");
-            if (result.error)
-                return { content: [{ type: "text", text: `Portfolio fetch failed: ${result.error}` }], isError: true };
-            const balances = result.balances ?? [];
-            const totalUsd = result.totalUsd ?? result.totalValueUsd ?? balances.reduce((s, b) => s + (b.valueUsd ?? 0), 0);
-            if (!balances.length) {
-                return { content: [{ type: "text", text: "Your wallet has no tokens yet. Send ETH or USDC on Base to get started." }] };
-            }
-            const lines = [`**Portfolio** - Total: $${totalUsd.toFixed(2)}`, ""];
-            for (const b of balances) {
-                const value = b.valueUsd != null ? ` ($${Number(b.valueUsd).toFixed(2)})` : "";
-                lines.push(`• **${b.token ?? b.symbol}**: ${Number(b.balance ?? b.amount).toLocaleString(undefined, { maximumFractionDigits: 6 })}${value}`);
-            }
-            lines.push("", `Wallet: \`${result.address ?? "unknown"}\``);
-            return { content: [{ type: "text", text: lines.join("\n") }] };
-        }
-        case "estimate_swap": {
-            const parsed = SwapSchema.safeParse(args);
-            if (!parsed.success)
-                return { content: [{ type: "text", text: `${String(parsed.error.issues[0].path[0])}: ${parsed.error.issues[0].message}` }], isError: true };
-            const { fromToken, toToken, amount, maxSlippagePct, maxPriceImpactPct } = parsed.data;
-            const slippageLimit = maxSlippagePct ?? DEFAULT_MAX_SLIPPAGE_PCT;
-            const impactLimit = maxPriceImpactPct ?? DEFAULT_MAX_PRICE_IMPACT_PCT;
-            // Pass the MCP local wallet as the swap taker so 0x routes output back
-            // to the wallet that's signing - not the backend's custodial wallet.
-            const localWallet = await (0, wallet_js_1.getOrCreateWallet)();
-            const result = await (0, convex_js_1.callConvex)("/mcp/defi/swap", "POST", { fromToken, toToken, amount, taker: localWallet.address, slippagePercentage: slippageLimit / 100 }, "swap_tokens");
-            if (!result.success)
-                return { content: [{ type: "text", text: `Estimate failed: ${result.error}` }], isError: true };
-            const q = result.quote;
-            const buyHuman = formatTokenAmount(q.buyAmount, q.buyToken ?? toToken);
-            const sellHuman = formatTokenAmount(q.sellAmount ?? "0", q.sellToken ?? fromToken);
-            const impactPct = q.estimatedPriceImpact != null ? Number(q.estimatedPriceImpact) : 0;
-            const priceImpact = q.estimatedPriceImpact != null ? `${impactPct.toFixed(3)}%` : "< 0.01%";
-            const impactWarning = impactPct > impactLimit
-                ? `\n⚠️ **Price impact ${impactPct.toFixed(2)}% exceeds limit ${impactLimit}%** - \`swap_tokens\` will refuse execution. Increase \`maxPriceImpactPct\` to override.`
-                : "";
-            return {
-                content: [{
-                        type: "text",
-                        text: [
-                            `**Swap Estimate** (not executed)`,
-                            ``,
-                            `You sell: **${sellHuman} ${(q.sellToken ?? fromToken).toUpperCase()}**`,
-                            `You get:  **~${buyHuman} ${(q.buyToken ?? toToken).toUpperCase()}**`,
-                            `Price impact: ${priceImpact}`,
-                            `Slippage cap: ${slippageLimit}% · Price-impact cap: ${impactLimit}%`,
-                            impactWarning,
-                            ``,
-                            `Run \`swap_tokens\` with the same params to execute.`,
-                        ].join("\n"),
-                    }],
-            };
-        }
-        case "swap_tokens": {
-            const parsed = SwapSchema.safeParse(args);
-            if (!parsed.success)
-                return { content: [{ type: "text", text: `${String(parsed.error.issues[0].path[0])}: ${parsed.error.issues[0].message}` }], isError: true };
-            const { fromToken, toToken, amount, maxSlippagePct, maxPriceImpactPct } = parsed.data;
-            const slippageLimit = maxSlippagePct ?? DEFAULT_MAX_SLIPPAGE_PCT;
-            const impactLimit = maxPriceImpactPct ?? DEFAULT_MAX_PRICE_IMPACT_PCT;
-            const wallet = await (0, wallet_js_1.getOrCreateWallet)();
-            const result = await (0, convex_js_1.callConvex)("/mcp/defi/swap", "POST", { fromToken, toToken, amount, taker: wallet.address, slippagePercentage: slippageLimit / 100 }, "swap_tokens");
-            if (!result.success)
-                return { content: [{ type: "text", text: `Swap failed: ${result.error}` }], isError: true };
-            const q = result.quote;
-            const impactPct = q.estimatedPriceImpact != null ? Number(q.estimatedPriceImpact) : 0;
-            if (impactPct > impactLimit) {
-                return {
-                    content: [{
-                            type: "text",
-                            text: [
-                                `🛑 **Swap refused - price impact too high.**`,
-                                ``,
-                                `Quoted price impact: **${impactPct.toFixed(3)}%**`,
-                                `Configured cap:      **${impactLimit}%**`,
-                                ``,
-                                `Override by passing \`maxPriceImpactPct: ${Math.ceil(impactPct) + 1}\` if you understand the risk,`,
-                                `or reduce \`amount\` to lower the impact.`,
-                            ].join("\n"),
-                        }],
-                    isError: true,
-                };
-            }
-            const txHash = await (0, wallet_js_1.signAndBroadcast)(wallet, q);
-            const buyAmountHuman = formatTokenAmount(q.buyAmount, q.buyToken ?? toToken);
-            const receipt = await (0, wallet_js_1.waitForReceipt)(txHash);
-            const header = !receipt.mined
-                ? `⏳ Broadcast, not yet confirmed within the wait window.`
-                : receipt.ok
-                    ? `✅ Swap confirmed on-chain (block ${receipt.blockNumber}).`
-                    : `❌ Transaction REVERTED - no swap occurred (gas was still spent).`;
-            return {
-                content: [{
-                        type: "text",
-                        text: [
-                            header,
-                            `${amount} ${fromToken.toUpperCase()} → ${receipt.mined && receipt.ok ? buyAmountHuman : "(quoted, not received)"} ${q.buyToken}`,
-                            `Slippage cap: ${slippageLimit}% · Price impact: ${impactPct.toFixed(3)}%`,
-                            `Tx Hash: \`${txHash}\``,
-                            `https://basescan.org/tx/${txHash}`,
-                            !receipt.mined ? `Check the link above before telling the user this succeeded or failed.` : "",
-                        ].filter(Boolean).join("\n"),
-                    }],
-                isError: receipt.mined && !receipt.ok,
-            };
-        }
-        case "send_token": {
-            const parsed = SendSchema.safeParse(args);
-            if (!parsed.success)
-                return { content: [{ type: "text", text: `${String(parsed.error.issues[0].path[0])}: ${parsed.error.issues[0].message}` }], isError: true };
-            const { token, toAddress, amount } = parsed.data;
-            const wallet = await (0, wallet_js_1.getOrCreateWallet)();
-            const result = await (0, convex_js_1.callConvex)("/mcp/defi/send", "POST", parsed.data, "send_token");
-            if (!result.success)
-                return { content: [{ type: "text", text: `Send failed: ${result.error}` }], isError: true };
-            const txHash = await (0, wallet_js_1.signAndBroadcast)(wallet, result.txData);
-            const receipt = await (0, wallet_js_1.waitForReceipt)(txHash);
-            const header = !receipt.mined
-                ? `⏳ Broadcast, not yet confirmed within the wait window.`
-                : receipt.ok
-                    ? `✅ Sent - confirmed on-chain (block ${receipt.blockNumber}).`
-                    : `❌ Transaction REVERTED - funds were NOT sent (gas was still spent).`;
-            return {
-                content: [{
-                        type: "text",
-                        text: [
-                            header,
-                            `${amount} ${token.toUpperCase()} → \`${toAddress}\``,
-                            `Tx Hash: \`${txHash}\``,
-                            `https://basescan.org/tx/${txHash}`,
-                            !receipt.mined ? `Check the link above before telling the user this succeeded or failed.` : "",
-                        ].filter(Boolean).join("\n"),
-                    }],
-                isError: receipt.mined && !receipt.ok,
-            };
-        }
-        // analyze_wallet was removed - it called POST /wallet/analyze, which was
-        // never registered in app/convex/http.ts (only a dangling section-header
-        // comment exists there). The tool was never in the exported DEFI_TOOLS
-        // list either, so this case was already unreachable dead code - no Tool
-        // registers the name "analyze_wallet" for the MCP dispatcher to route to.
-        case "get_defi_yields": {
-            const parsed = DefiYieldsSchema.safeParse(args ?? {});
-            if (!parsed.success)
-                return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
-            const { token, minApy = 1, limit = 20 } = parsed.data;
-            let pools;
-            try {
-                const res = await fetch("https://yields.llama.fi/pools", { signal: AbortSignal.timeout(15000) });
-                if (!res.ok)
-                    throw new Error(`HTTP ${res.status}`);
-                const data = await res.json();
-                pools = data.data ?? [];
-            }
-            catch (e) {
-                return { content: [{ type: "text", text: `DeFiLlama fetch failed: ${e.message}` }], isError: true };
-            }
-            // Filter to Base chain
-            let filtered = pools.filter((p) => p.chain === "Base");
-            // Filter by token if specified
-            if (token) {
-                const upper = token.toUpperCase();
-                filtered = filtered.filter((p) => (p.symbol ?? "").toUpperCase().includes(upper) ||
-                    (p.underlyingTokens ?? []).some((t) => t.toUpperCase().includes(upper)));
-            }
-            // Filter by minimum APY and remove outliers (>10000% are usually broken)
-            filtered = filtered
-                .filter((p) => (p.apy ?? 0) >= minApy && (p.apy ?? 0) <= 10000)
-                .sort((a, b) => (b.apy ?? 0) - (a.apy ?? 0))
-                .slice(0, limit);
-            if (!filtered.length) {
-                return {
-                    content: [{
-                            type: "text",
-                            text: [
-                                `## DeFi Yields on Base`,
-                                `No pools found${token ? ` for ${token.toUpperCase()}` : ""} with APY ≥ ${minApy}%.`,
-                                ``,
-                                `Try lowering \`minApy\` or removing the token filter.`,
-                            ].join("\n"),
-                        }],
-                    structuredContent: buildDefiYields(token, minApy, []),
-                };
-            }
-            const fmt = (n) => n >= 1000000000 ? `$${(n / 1000000000).toFixed(1)}B`
-                : n >= 1000000 ? `$${(n / 1000000).toFixed(1)}M`
-                    : n >= 1000 ? `$${(n / 1000).toFixed(0)}K`
-                        : `$${n.toFixed(0)}`;
-            const lines = [
-                `## DeFi Yields on Base${token ? ` - ${token.toUpperCase()}` : ""}`,
-                `Top ${filtered.length} pools · APY ≥ ${minApy}% · Source: DeFiLlama`,
-                ``,
-                `| # | Pool | Protocol | APY | TVL |`,
-                `|---|------|----------|-----|-----|`,
-            ];
-            filtered.forEach((p, i) => {
-                const apy = (p.apy ?? 0).toFixed(1);
-                const tvl = fmt(p.tvlUsd ?? 0);
-                const name = (p.symbol ?? p.pool ?? "-").replace(/-/g, " ");
-                const proj = p.project ?? "-";
-                lines.push(`| ${i + 1} | ${name} | ${proj} | **${apy}%** | ${tvl} |`);
-            });
-            lines.push(``, `Use \`swap_tokens\` to position, then deposit via the protocol's UI. Always check smart contract risk before depositing.`);
-            return { content: [{ type: "text", text: lines.join("\n") }], structuredContent: buildDefiYields(token, minApy, filtered) };
-        }
-        default:
-            return null;
-    }
-}

package/dist/tools/equity.js

@@ -1,372 +0,0 @@
-"use strict";
-// Public-company fundamentals from primary sources.
-//
-// Financials come from SEC EDGAR XBRL — the numbers as filed in 10-Q/10-K, not
-// a vendor's re-typing of them. No API key, no rate-limit tier, and if a figure
-// here is wrong it is wrong in the filing itself.
-//
-// The tool computes what is mechanical (margins, YoY growth, quarter vs YTD)
-// and hands the result to the caller's model to interpret. It does not write
-// the analysis: the caller has the user's thesis, risk tolerance and context,
-// and is a stronger analyst than anything this module could embed.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.EQUITY_TOOLS = void 0;
-exports.buildStockFundamentals = buildStockFundamentals;
-exports.handleEquityTool = handleEquityTool;
-const zod_1 = require("zod");
-// ── Structured output builder (schema in output-schemas.ts) ─────────────────
-function buildStockFundamentals(ticker, companyName, cik, quote, quarterly, annual) {
-    return { ticker, companyName, cik, quote, quarterly, annual };
-}
-const SEC_UA = "Finch MCP research (contact: support@finchagentic.com)";
-const SEC_TICKERS = "https://www.sec.gov/files/company_tickers.json";
-const SEC_CONCEPT = (cik, tag) => `https://data.sec.gov/api/xbrl/companyconcept/CIK${cik}/us-gaap/${tag}.json`;
-/**
- * Concepts pulled per company. Order drives the report layout.
- *
- * Each concept lists several candidate XBRL tags because issuers do not agree
- * on which one to use, and a company can stop using one mid-history. Apple
- * abandoned `Revenues` at the ASC 606 transition and reports under
- * `RevenueFromContractWithCustomer…`; querying only `Revenues` returns its
- * pre-2019 figures, which then render as the current picture — stale by years,
- * and indistinguishable from correct output. The tag with the most recent data
- * wins, so a legacy series can never outrank a live one.
- */
-const CONCEPTS = [
-    {
-        key: "revenue",
-        label: "Revenue",
-        kind: "flow",
-        tags: [
-            "Revenues",
-            "RevenueFromContractWithCustomerExcludingAssessedTax",
-            "RevenueFromContractWithCustomerIncludingAssessedTax",
-            "SalesRevenueNet",
-        ],
-    },
-    { key: "netIncome", label: "Net income", kind: "flow", tags: ["NetIncomeLoss"] },
-    { key: "opIncome", label: "Operating income", kind: "flow", tags: ["OperatingIncomeLoss"] },
-    { key: "eps", label: "EPS (diluted)", kind: "pershare", tags: ["EarningsPerShareDiluted"] },
-    { key: "assets", label: "Total assets", kind: "stock", tags: ["Assets"] },
-    { key: "liabilities", label: "Total liabilities", kind: "stock", tags: ["Liabilities"] },
-    {
-        key: "equity",
-        label: "Shareholders' equity",
-        kind: "stock",
-        tags: ["StockholdersEquity", "StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest"],
-    },
-    {
-        key: "cash",
-        label: "Cash & equivalents",
-        kind: "stock",
-        tags: [
-            "CashAndCashEquivalentsAtCarryingValue",
-            "CashCashEquivalentsRestrictedCashAndRestrictedCashEquivalents",
-        ],
-    },
-];
-exports.EQUITY_TOOLS = [
-    {
-        name: "stock_fundamentals",
-        description: "Fetch a public company's financials straight from SEC EDGAR XBRL (as filed in 10-Q/10-K) " +
-            "plus a live quote. Returns revenue, operating and net income, diluted EPS, balance sheet, " +
-            "computed margins and YoY growth — with quarterly figures correctly separated from " +
-            "year-to-date ones. US-listed issuers only. No API key needed. " +
-            "You do the analysis: the numbers and a review rubric come back, not a written opinion.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                ticker: { type: "string", description: "US ticker symbol, e.g. 'HOOD', 'COIN', 'AAPL'" },
-                periods: { type: "number", description: "How many recent periods per metric (default 6, max 12)" },
-            },
-            required: ["ticker"],
-        },
-    },
-];
-const Schema = zod_1.z.object({
-    ticker: zod_1.z.string().min(1).max(10),
-    periods: zod_1.z.number().int().min(1).max(12).optional(),
-});
-function fmtMoney(v) {
-    const a = Math.abs(v);
-    const sign = v < 0 ? "-" : "";
-    if (a >= 1e9)
-        return `${sign}$${(a / 1e9).toFixed(2)}B`;
-    if (a >= 1e6)
-        return `${sign}$${(a / 1e6).toFixed(0)}M`;
-    if (a >= 1e3)
-        return `${sign}$${(a / 1e3).toFixed(0)}K`;
-    return `${sign}$${a.toFixed(2)}`;
-}
-/**
- * XBRL reports the same tag as both a quarterly and a cumulative figure for the
- * same period end. Treating them as one series silently triples a quarter, so
- * classify by the reported span before anything else touches the numbers.
- */
-function spanKind(f) {
-    if (!f.start)
-        return "point";
-    const days = Math.round((Date.parse(f.end) - Date.parse(f.start)) / 86400000);
-    if (days <= 110)
-        return "quarter";
-    if (days <= 300)
-        return "ytd";
-    return "annual";
-}
-async function secJson(url) {
-    try {
-        const res = await fetch(url, {
-            headers: { "User-Agent": SEC_UA, Accept: "application/json" },
-            signal: AbortSignal.timeout(20000),
-        });
-        if (!res.ok)
-            return null;
-        return await res.json();
-    }
-    catch {
-        return null;
-    }
-}
-async function resolveCik(ticker) {
-    const data = await secJson(SEC_TICKERS);
-    if (!data)
-        return null;
-    const up = ticker.trim().toUpperCase();
-    const hit = Object.values(data).find((x) => String(x.ticker).toUpperCase() === up);
-    if (!hit)
-        return null;
-    return { cik: String(hit.cik_str).padStart(10, "0"), name: hit.title };
-}
-/**
- * Live quote. Best-effort — fundamentals stand on their own without it.
- *
- * `meta.chartPreviousClose` is the close BEFORE THE REQUESTED RANGE BEGINS, not
- * the previous session. Reading it off a multi-day range reports a multi-day
- * move as a one-day move: on 2026-07-22 HOOD sat at $106.71 against a genuine
- * prior close of $106.36 (+0.33%), but a `range=5d` request returns $115.54 —
- * the close six sessions back — for a headline of -7.6% that never happened.
- *
- * `regularMarketPreviousClose` is absent from this endpoint, so the previous
- * close is taken from the daily bar series instead: walk back past today's
- * still-forming bar and use the last completed session. That is derived from
- * the data rather than from a field whose meaning shifts with the query.
- */
-async function liveQuote(ticker) {
-    try {
-        const res = await fetch(`https://query1.finance.yahoo.com/v8/finance/chart/${encodeURIComponent(ticker)}?interval=1d&range=10d`, { headers: { "User-Agent": "Mozilla/5.0" }, signal: AbortSignal.timeout(12000) });
-        if (!res.ok)
-            return null;
-        const j = await res.json();
-        const r = j?.chart?.result?.[0];
-        const m = r?.meta;
-        if (!m?.regularMarketPrice)
-            return null;
-        const stamps = r?.timestamp ?? [];
-        const closes = r?.indicators?.quote?.[0]?.close ?? [];
-        const bars = stamps
-            .map((t, i) => ({ day: new Date(t * 1000).toISOString().slice(0, 10), close: closes[i] }))
-            .filter((b) => typeof b.close === "number");
-        // The bar covering the quote's own timestamp is today's, still forming.
-        const today = new Date((m.regularMarketTime ?? Date.now() / 1000) * 1000).toISOString().slice(0, 10);
-        const completed = bars.filter((b) => b.day !== today);
-        const prev = completed[completed.length - 1];
-        if (!prev)
-            return null;
-        return { price: m.regularMarketPrice, prevClose: prev.close, prevDate: prev.day, currency: m.currency ?? "USD" };
-    }
-    catch {
-        return null;
-    }
-}
-async function handleEquityTool(name, args) {
-    if (name !== "stock_fundamentals")
-        return null;
-    const parsed = Schema.safeParse(args);
-    if (!parsed.success) {
-        return { content: [{ type: "text", text: `${parsed.error.issues[0].message}` }], isError: true };
-    }
-    const ticker = parsed.data.ticker.trim().toUpperCase();
-    const periods = parsed.data.periods ?? 6;
-    const company = await resolveCik(ticker);
-    if (!company) {
-        return {
-            content: [{
-                    type: "text",
-                    text: `No SEC filer found for **${ticker}**. This covers US-listed issuers that file with the SEC — ` +
-                        `foreign private issuers, private companies and ETFs may be absent. Check the symbol.`,
-                }],
-            isError: true,
-        };
-    }
-    // SEC asks for no more than 10 requests a second, and the candidate tags push
-    // the count past that if they all go out at once.
-    const jobs = CONCEPTS.flatMap((c) => c.tags.map((tag) => ({ key: c.key, tag })));
-    const raw = [];
-    for (let i = 0; i < jobs.length; i += 6) {
-        raw.push(...(await Promise.all(jobs.slice(i, i + 6).map((j) => secJson(SEC_CONCEPT(company.cik, j.tag))))));
-    }
-    const quote = await liveQuote(ticker);
-    // Per concept, keep the candidate tag whose reported periods run latest.
-    const chosen = new Map();
-    jobs.forEach((j, i) => {
-        const data = raw[i];
-        if (!data?.units)
-            return;
-        const unitKey = Object.keys(data.units)[0];
-        const facts = (data.units[unitKey] ?? []).filter((f) => f.form === "10-Q" || f.form === "10-K");
-        if (!facts.length)
-            return;
-        const latest = facts.reduce((m, f) => (f.end > m ? f.end : m), "");
-        const prev = chosen.get(j.key);
-        if (!prev || latest > prev.latest)
-            chosen.set(j.key, { tag: j.tag, facts, latest });
-    });
-    const lines = [
-        `# ${company.name} (${ticker}) — as filed with the SEC`,
-        ``,
-        `CIK ${company.cik} · source: SEC EDGAR XBRL (10-Q / 10-K)`,
-    ];
-    if (quote) {
-        const chg = ((quote.price - quote.prevClose) / quote.prevClose) * 100;
-        lines.push(``, 
-        // The prior close is dated, so a stale or holiday-shifted comparison is
-        // visible in the output rather than silently read as a one-day move.
-        `**Live quote:** ${quote.currency} ${quote.price.toFixed(2)} ` +
-            `(${chg >= 0 ? "+" : ""}${chg.toFixed(2)}% vs ${quote.prevDate} close ${quote.prevClose.toFixed(2)})`);
-    }
-    else {
-        lines.push(``, `_Live quote unavailable — fundamentals below are unaffected._`);
-    }
-    const quarterly = {};
-    const annual = {};
-    const usedTags = [];
-    CONCEPTS.forEach((c) => {
-        const pick = chosen.get(c.key);
-        if (!pick)
-            return;
-        usedTags.push(`${c.label} → \`${pick.tag}\``);
-        const facts = pick.facts;
-        // A period appears in more than one filing — the current 10-Q also carries
-        // last year's comparative. Without deduping by period end the same quarter
-        // is listed twice and the YoY lookup lands on a duplicate instead of the
-        // year-ago quarter, silently reporting ~0% growth.
-        const dedupe = (rows) => {
-            const byEnd = new Map();
-            for (const f of rows) {
-                const prev = byEnd.get(f.end);
-                // Prefer the original filing (earliest fy) so the label matches the period.
-                if (!prev || (f.fy ?? 0) < (prev.fy ?? 0))
-                    byEnd.set(f.end, f);
-            }
-            return [...byEnd.values()].sort((a, b) => a.end.localeCompare(b.end));
-        };
-        if (c.kind === "stock") {
-            annual[c.key] = dedupe(facts).slice(-periods);
-        }
-        else {
-            quarterly[c.key] = dedupe(facts.filter((f) => spanKind(f) === "quarter")).slice(-periods);
-            annual[c.key] = dedupe(facts.filter((f) => spanKind(f) === "annual")).slice(-periods);
-        }
-    });
-    const render = (tag, label, kind, rows) => {
-        if (!rows?.length)
-            return;
-        lines.push(``, `### ${label}`);
-        for (const f of rows) {
-            const v = kind === "pershare" ? `$${f.val.toFixed(2)}` : fmtMoney(f.val);
-            lines.push(`- ${f.end} — **${v}**${f.fy ? ` _(${f.form} FY${f.fy}${f.fp && f.fp !== "FY" ? " " + f.fp : ""})_` : ""}`);
-        }
-        // YoY against the same quarter a year earlier, matched by DATE rather than
-        // by position — periods are often missing, so counting back N rows can
-        // silently compare against the wrong quarter.
-        if (kind === "flow" && rows.length >= 2) {
-            const latest = rows[rows.length - 1];
-            const target = new Date(latest.end);
-            target.setFullYear(target.getFullYear() - 1);
-            const yearAgo = rows.find((r) => Math.abs(Date.parse(r.end) - target.getTime()) < 20 * 86400000);
-            if (yearAgo?.val && yearAgo.end !== latest.end) {
-                const g = ((latest.val - yearAgo.val) / Math.abs(yearAgo.val)) * 100;
-                lines.push(`- **YoY (${yearAgo.end} → ${latest.end}): ${g >= 0 ? "+" : ""}${g.toFixed(1)}%**`);
-            }
-        }
-    };
-    lines.push(``, `---`, ``, `## Quarterly (each figure is a single quarter, not year-to-date)`);
-    for (const c of CONCEPTS) {
-        if (c.kind === "stock")
-            continue;
-        render(c.key, c.label, c.kind, quarterly[c.key]);
-    }
-    lines.push(``, `---`, ``, `## Annual & balance sheet`);
-    for (const c of CONCEPTS)
-        render(c.key, c.label + (c.kind === "stock" ? " (period end)" : " — annual"), c.kind, annual[c.key]);
-    // Per-share figures are filed as-reported for their period and are NOT
-    // restated for later splits. NVDA's annual EPS runs $11.93 → $2.94 across the
-    // 10-for-1 of June 2024, which reads as a 75% earnings collapse in the same
-    // year revenue grew 114%. The split is discoverable — it is an 8-K item 5.03 —
-    // but only if the reader thinks to look, so the discontinuity is named here
-    // instead of left as a trap. Detected by direction: a per-share series moving
-    // hard against net income over the same periods is a share-count event, not
-    // an earnings event.
-    const splitWarnings = [];
-    for (const [label, eps, profit] of [
-        ["quarterly", quarterly["eps"], quarterly["netIncome"]],
-        ["annual", annual["eps"], annual["netIncome"]],
-    ]) {
-        for (let i = 1; i < (eps?.length ?? 0); i++) {
-            const [prev, cur] = [eps[i - 1], eps[i]];
-            if (!prev.val || !cur.val || prev.val <= 0 || cur.val <= 0)
-                continue;
-            const epsChange = (cur.val - prev.val) / prev.val;
-            const ni = profit?.find((f) => f.end === cur.end);
-            const niPrev = profit?.find((f) => f.end === prev.end);
-            if (!ni?.val || !niPrev?.val || niPrev.val <= 0)
-                continue;
-            const niChange = (ni.val - niPrev.val) / niPrev.val;
-            // EPS down hard while profit held or grew (or the mirror image).
-            if ((epsChange < -0.4 && niChange > -0.1) || (epsChange > 0.6 && niChange < 0.1)) {
-                // Shares = income / EPS, so the implied share-count change is
-                // (income ratio) x (EPS ratio inverted). The raw EPS ratio alone
-                // conflates the split with the earnings move and understates it —
-                // NVDA's 10-for-1 reads as 4:1 until the income growth is divided out.
-                const shareRatio = (ni.val / niPrev.val) * (prev.val / cur.val);
-                const asSplit = shareRatio >= 1.5
-                    ? `${shareRatio.toFixed(1)}-for-1`
-                    : shareRatio <= 0.67
-                        ? `1-for-${(1 / shareRatio).toFixed(1)} reverse`
-                        : null;
-                splitWarnings.push(`- **${label} EPS ${prev.end} → ${cur.end}**: $${prev.val.toFixed(2)} → $${cur.val.toFixed(2)} ` +
-                    `(${(epsChange * 100).toFixed(0)}%) while net income moved ${(niChange * 100).toFixed(0)}%. ` +
-                    `Implied share count ×${shareRatio.toFixed(2)}${asSplit ? ` — consistent with a ${asSplit} split` : ""}, ` +
-                    `not an earnings change. Confirm with \`stock_events\` (8-K item 5.03) before comparing these two periods.`);
-            }
-        }
-    }
-    if (splitWarnings.length) {
-        lines.push(``, `---`, ``, `## ⚠️ Per-share figures are not split-adjusted`, ``, ...splitWarnings, ``, `Revenue, income and balance-sheet lines are unaffected — only per-share values are.`);
-    }
-    // Margins, computed rather than asserted.
-    const rev = quarterly["revenue"]?.slice(-1)[0];
-    const ni = quarterly["netIncome"]?.slice(-1)[0];
-    const oi = quarterly["opIncome"]?.slice(-1)[0];
-    if (rev?.val) {
-        lines.push(``, `---`, ``, `## Computed margins — latest quarter (${rev.end})`);
-        if (oi)
-            lines.push(`- Operating margin: **${((oi.val / rev.val) * 100).toFixed(1)}%**`);
-        if (ni)
-            lines.push(`- Net margin: **${((ni.val / rev.val) * 100).toFixed(1)}%**`);
-    }
-    lines.push(``, `---`, ``, `## How to analyse this`, ``, `**Trajectory** — is revenue growth accelerating or decelerating? Compare the last 4 quarters ` +
-        `sequentially, then against the same quarter a year earlier. Say which, and by how much.`, ``, `**Quality of earnings** — is net income tracking operating income, or driven by items below ` +
-        `the operating line? A widening gap deserves an explanation.`, ``, `**Balance sheet** — equity vs liabilities trend, and whether cash covers near-term obligations.`, ``, `**What these numbers cannot tell you** — guidance, competitive position, regulatory exposure, ` +
-        `insider activity, and anything after the last filing date above. Say so explicitly rather ` +
-        `than inferring it. For sentiment and post-filing developments, run \`deep_research\`.`, ``, `Cite the period end for every figure you use. Do not annualise a quarter without labelling it ` +
-        `as your own extrapolation. If a metric is missing above, the company did not file that tag — ` +
-        `do not substitute an estimate.`, ``, 
-    // Issuers tag the same concept differently, so naming the tag behind each
-    // series makes the figures checkable against EDGAR rather than trusted.
-    `_XBRL concepts used: ${usedTags.join(" · ")}_`, ``, `_Figures are as filed with the SEC. Not investment advice._`);
-    return {
-        content: [{ type: "text", text: lines.join("\n") }],
-        structuredContent: buildStockFundamentals(ticker, company.name ?? null, company.cik ?? null, quote, quarterly, annual),
-    };
-}