cito-mcp 0.1.0 → 0.2.2

package/dist/tools/insight.js

@@ -0,0 +1,1013 @@
+/**
+ * match_preview — pre-match briefing composite
+ */
+import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, } from '../client.js';
+import { errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
+import { normalizeMatch } from './normalize.js';
+import { boolSchema, gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from './types.js';
+async function loadSide(ctx, game, side, recentLimit, includeRosters) {
+    const partial = [];
+    let calls = 0;
+    let rateLimit = {};
+    let entity = { idOrSlug: side, name: side, game };
+    let roster = [];
+    let recentForm = [];
+    let keyPlayers = [];
+    if (game === 'ufc') {
+        const res = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(side)}`);
+        calls += 1;
+        rateLimit = res.headers;
+        if (res.ok) {
+            const data = asRecord(res.data) ?? {};
+            entity = {
+                id: pickString(data.id, side),
+                slug: pickString(data.slug, side),
+                name: pickString(data.name, side),
+                game,
+            };
+        }
+        else {
+            partial.push(partialFromRejection('side', {
+                code: mapHttpToCode(res.status),
+                message: `fighter ${side} HTTP ${res.status}`,
+                httpStatus: res.status,
+            }));
+        }
+        const stats = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(side)}/stats`);
+        calls += 1;
+        rateLimit = { ...rateLimit, ...stats.headers };
+        if (stats.ok)
+            recentForm = [stats.data];
+        return { entity, roster, recentForm, keyPlayers, calls, partial, rateLimit };
+    }
+    if (game === 'lol') {
+        const res = await fetchJson(ctx, `/lol/teams/${encodeURIComponent(side)}`);
+        calls += 1;
+        rateLimit = res.headers;
+        if (res.ok) {
+            const data = asRecord(res.data) ?? {};
+            entity = {
+                id: pickString(data.id, side),
+                slug: pickString(data.slug, side),
+                name: pickString(data.name, side),
+                game,
+            };
+        }
+        else {
+            partial.push(partialFromRejection('side', {
+                code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                message: `team ${side} HTTP ${res.status}`,
+                httpStatus: res.status,
+            }));
+        }
+        if (includeRosters) {
+            const rost = await fetchJson(ctx, `/lol/teams/${encodeURIComponent(side)}/roster`);
+            calls += 1;
+            rateLimit = { ...rateLimit, ...rost.headers };
+            if (rost.ok) {
+                roster = extractRows(rost.data);
+                keyPlayers = roster.slice(0, 5);
+            }
+            else {
+                partial.push(partialFromRejection('roster', {
+                    code: mapHttpToCode(rost.status),
+                    message: `roster HTTP ${rost.status}`,
+                    httpStatus: rost.status,
+                }));
+            }
+        }
+        const sched = await fetchJson(ctx, '/lol/schedule', {
+            query: { teamSlug: side, completed: 'true', limit: String(recentLimit) },
+        });
+        calls += 1;
+        rateLimit = { ...rateLimit, ...sched.headers };
+        if (sched.ok) {
+            recentForm = extractRows(sched.data)
+                .slice(0, recentLimit)
+                .map((row) => normalizeMatch('lol', row, 'completed'));
+        }
+        return { entity, roster, recentForm, keyPlayers, calls, partial, rateLimit };
+    }
+    if (game === 'cs2') {
+        if (includeRosters) {
+            const rost = await fetchJson(ctx, `/cs2/teams/${encodeURIComponent(side)}/roster-history`);
+            calls += 1;
+            rateLimit = rost.headers;
+            if (rost.ok) {
+                roster = extractRows(rost.data).slice(0, 10);
+                keyPlayers = roster.slice(0, 5);
+            }
+        }
+        const trends = await fetchJson(ctx, `/cs2/teams/${encodeURIComponent(side)}/trends`);
+        calls += 1;
+        rateLimit = { ...rateLimit, ...trends.headers };
+        if (trends.ok)
+            recentForm = [trends.data];
+        const matches = await fetchJson(ctx, '/cs2/matches', {
+            query: { team: side, limit: recentLimit },
+        });
+        calls += 1;
+        rateLimit = { ...rateLimit, ...matches.headers };
+        if (matches.ok) {
+            const m = extractRows(matches.data)
+                .slice(0, recentLimit)
+                .map((row) => normalizeMatch('cs2', row));
+            recentForm = [...recentForm, ...m];
+        }
+        entity = { idOrSlug: side, name: side, game };
+        return { entity, roster, recentForm, keyPlayers, calls, partial, rateLimit };
+    }
+    if (game === 'cod') {
+        const res = await fetchJson(ctx, `/cod/orgs/${encodeURIComponent(side)}`);
+        calls += 1;
+        rateLimit = res.headers;
+        if (res.ok) {
+            const data = asRecord(res.data) ?? {};
+            entity = {
+                id: pickString(data.id, side),
+                slug: pickString(data.slug, side),
+                name: pickString(data.name, side),
+                game,
+            };
+        }
+        if (includeRosters) {
+            const rost = await fetchJson(ctx, `/cod/orgs/${encodeURIComponent(side)}/roster`);
+            calls += 1;
+            rateLimit = { ...rateLimit, ...rost.headers };
+            if (rost.ok) {
+                roster = extractRows(rost.data);
+                keyPlayers = roster.slice(0, 5);
+            }
+        }
+        const matches = await fetchJson(ctx, '/cod/matches', {
+            query: { team: side, limit: recentLimit },
+        });
+        calls += 1;
+        rateLimit = { ...rateLimit, ...matches.headers };
+        if (matches.ok) {
+            recentForm = extractRows(matches.data)
+                .slice(0, recentLimit)
+                .map((row) => normalizeMatch('cod', row));
+        }
+        return { entity, roster, recentForm, keyPlayers, calls, partial, rateLimit };
+    }
+    if (game === 'dota2') {
+        const radar = await fetchJson(ctx, `/dota2/teams/${encodeURIComponent(side)}/radar`);
+        calls += 1;
+        rateLimit = radar.headers;
+        if (radar.ok)
+            recentForm = [radar.data];
+        else {
+            partial.push(partialFromRejection('form', {
+                code: mapHttpToCode(radar.status),
+                message: `radar HTTP ${radar.status}`,
+                httpStatus: radar.status,
+            }));
+        }
+        entity = { idOrSlug: side, name: side, game };
+        if (includeRosters) {
+            partial.push(partialFromRejection('roster', {
+                code: 'NOT_IMPLEMENTED',
+                message: 'Dota has no roster endpoint',
+            }));
+        }
+        return { entity, roster, recentForm, keyPlayers, calls, partial, rateLimit };
+    }
+    return { entity, roster, recentForm, keyPlayers, calls, partial, rateLimit };
+}
+function composeH2H(game, sideA, sideB, rows, limit) {
+    const al = sideA.toLowerCase();
+    const bl = sideB.toLowerCase();
+    const meetings = rows
+        .map((row) => normalizeMatch(game, row))
+        .filter((m) => {
+        const s1 = [m.team1?.id, m.team1?.slug, m.team1?.name].filter(Boolean).map((x) => String(x).toLowerCase());
+        const s2 = [m.team2?.id, m.team2?.slug, m.team2?.name].filter(Boolean).map((x) => String(x).toLowerCase());
+        const hasA1 = s1.some((x) => x.includes(al) || al.includes(x));
+        const hasB1 = s1.some((x) => x.includes(bl) || bl.includes(x));
+        const hasA2 = s2.some((x) => x.includes(al) || al.includes(x));
+        const hasB2 = s2.some((x) => x.includes(bl) || bl.includes(x));
+        return (hasA1 && hasB2) || (hasB1 && hasA2);
+    })
+        .slice(0, limit);
+    return {
+        meetings: meetings.length,
+        lastMeetings: meetings.slice(0, 5),
+        recordNote: meetings.length ? `${meetings.length} meetings found in window` : 'No H2H meetings in window',
+    };
+}
+export const matchPreview = {
+    name: 'match_preview',
+    description: `COMPOSITE pre-match briefing: sides, roster/form snippets, H2H stub, event context — for pick'ems, articles, and match-page before state.
+
+When to use:
+- Upcoming match deep link
+- "Who should I watch before this game?"
+- App scaffold for preview cards
+
+Prefer over: manually chaining team_profile ×2 + head_to_head + schedule.
+Prefer match_summary when match is completed; match_details for live in-game.
+
+Do not use when: user wants final score/recap of a finished match.
+
+Parallel-safe: yes. Upstream cost: 4–8.
+Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "recentLimit": 5 }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            matchId: stringSchema('Pass matchId OR (teamA + teamB).'),
+            teamA: stringSchema('Id/slug; UFC fighter slug when applicable.', 't1'),
+            teamB: stringSchema('Id/slug for side B.', 'gen-g'),
+            eventId: stringSchema('Optional event context (UFC).'),
+            includeH2H: boolSchema('Include composed H2H stub.', true),
+            includeRosters: boolSchema('Include roster snippets when available.', true),
+            recentLimit: limitSchema({ default: 5, max: 15, description: 'Form window per side (default 5, max 15).' }),
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        const gameParse = parseGame(args.game, { allowAll: false, required: true });
+        if (gameParse.error || !gameParse.game || !isPrimaryGame(gameParse.game)) {
+            return errorEnvelope({
+                code: gameParse.error?.includes('unsupported') ? 'UNSUPPORTED_GAME' : 'VALIDATION',
+                message: gameParse.error ?? 'game is required',
+                game: null,
+                source: 'match_preview',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        let matchId = typeof args.matchId === 'string' ? args.matchId.trim() : '';
+        let teamA = typeof args.teamA === 'string' ? args.teamA.trim() : '';
+        let teamB = typeof args.teamB === 'string' ? args.teamB.trim() : '';
+        const eventId = typeof args.eventId === 'string' ? args.eventId : undefined;
+        const includeH2H = args.includeH2H !== false;
+        const includeRosters = args.includeRosters !== false;
+        const recentLimit = clampInt(args.recentLimit, 5, 1, 15);
+        if (!matchId && (!teamA || !teamB)) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'Pass matchId OR both teamA and teamB',
+                game,
+                source: 'match_preview',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const partial = [];
+        let upstreamCalls = 0;
+        let rateLimit = {};
+        let context = {
+            matchId: matchId || null,
+            startTime: null,
+            event: eventId ? { id: eventId } : null,
+            league: null,
+            status: 'upcoming',
+        };
+        if (matchId) {
+            let path = '';
+            if (game === 'lol')
+                path = `/lol/matches/${encodeURIComponent(matchId)}`;
+            else if (game === 'cs2')
+                path = `/cs2/matches/${encodeURIComponent(matchId)}`;
+            else if (game === 'dota2')
+                path = `/dota2/matches/${encodeURIComponent(matchId)}`;
+            else if (game === 'cod')
+                path = `/cod/matches/${encodeURIComponent(matchId)}`;
+            else if (game === 'ufc')
+                path = `/ufc/bouts/${encodeURIComponent(matchId)}`;
+            const res = await fetchJson(ctx, path);
+            upstreamCalls += 1;
+            rateLimit = res.headers;
+            if (res.ok) {
+                const m = normalizeMatch(game, res.data, 'upcoming');
+                context = {
+                    matchId: m.matchId,
+                    startTime: m.startTime,
+                    event: m.event,
+                    league: m.league,
+                    status: m.status,
+                };
+                if (!teamA)
+                    teamA = m.team1?.slug || m.team1?.id || m.team1?.name || '';
+                if (!teamB)
+                    teamB = m.team2?.slug || m.team2?.id || m.team2?.name || '';
+            }
+            else {
+                partial.push(partialFromRejection('context', {
+                    code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                    message: `match context HTTP ${res.status}`,
+                    httpStatus: res.status,
+                }));
+            }
+        }
+        if (!teamA || !teamB) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'Could not resolve both sides; pass teamA and teamB',
+                game,
+                source: 'match_preview',
+                requestId,
+                tookMs: Date.now() - started,
+                upstreamCalls,
+            });
+        }
+        const [sideARes, sideBRes] = await Promise.all([
+            loadSide(ctx, game, teamA, recentLimit, includeRosters),
+            loadSide(ctx, game, teamB, recentLimit, includeRosters),
+        ]);
+        upstreamCalls += sideARes.calls + sideBRes.calls;
+        rateLimit = { ...rateLimit, ...sideARes.rateLimit, ...sideBRes.rateLimit };
+        partial.push(...sideARes.partial.map((p) => ({ ...p, section: `sideA.${p.section}` })));
+        partial.push(...sideBRes.partial.map((p) => ({ ...p, section: `sideB.${p.section}` })));
+        let h2h = null;
+        if (includeH2H) {
+            try {
+                let rows = [];
+                if (game === 'cs2') {
+                    const res = await fetchJson(ctx, '/cs2/matches', { query: { team: teamA, limit: 40 } });
+                    upstreamCalls += 1;
+                    rateLimit = { ...rateLimit, ...res.headers };
+                    if (res.ok)
+                        rows = extractRows(res.data);
+                    else {
+                        partial.push(partialFromRejection('h2h', {
+                            code: mapHttpToCode(res.status),
+                            message: `h2h HTTP ${res.status}`,
+                            httpStatus: res.status,
+                        }));
+                    }
+                }
+                else if (game === 'lol') {
+                    const res = await fetchJson(ctx, '/lol/schedule', {
+                        query: { teamSlug: teamA, completed: 'true', limit: '40' },
+                    });
+                    upstreamCalls += 1;
+                    rateLimit = { ...rateLimit, ...res.headers };
+                    if (res.ok)
+                        rows = extractRows(res.data);
+                }
+                else if (game === 'cod') {
+                    const res = await fetchJson(ctx, '/cod/matches', { query: { team: teamA, limit: 40 } });
+                    upstreamCalls += 1;
+                    rateLimit = { ...rateLimit, ...res.headers };
+                    if (res.ok)
+                        rows = extractRows(res.data);
+                }
+                else if (game === 'dota2') {
+                    const res = await fetchJson(ctx, '/dota2/matches/recent', { query: { limit: 40 } });
+                    upstreamCalls += 1;
+                    rateLimit = { ...rateLimit, ...res.headers };
+                    if (res.ok)
+                        rows = extractRows(res.data);
+                }
+                h2h = composeH2H(game, teamA, teamB, rows, 10);
+            }
+            catch (e) {
+                partial.push(partialFromRejection('h2h', {
+                    code: 'UPSTREAM',
+                    message: e.message,
+                }));
+            }
+        }
+        // Factual briefing lines only — never structural meta like "roster loaded".
+        const talkingPoints = [];
+        const sideAName = pickString(asRecord(sideARes.entity)?.name, teamA) ?? teamA;
+        const sideBName = pickString(asRecord(sideBRes.entity)?.name, teamB) ?? teamB;
+        if (context.startTime)
+            talkingPoints.push(`${sideAName} vs ${sideBName} scheduled for ${context.startTime}`);
+        if (context.eventName)
+            talkingPoints.push(`Event: ${context.eventName}`);
+        if (sideARes.recentForm.length) {
+            const w = sideARes.recentForm.filter((m) => asRecord(m)?.result === 'W' || asRecord(m)?.won === true).length;
+            talkingPoints.push(`${sideAName} recent sample: ${sideARes.recentForm.length} matches` + (w ? ` (~${w} marked wins in sample)` : ''));
+        }
+        if (sideBRes.recentForm.length) {
+            const w = sideBRes.recentForm.filter((m) => asRecord(m)?.result === 'W' || asRecord(m)?.won === true).length;
+            talkingPoints.push(`${sideBName} recent sample: ${sideBRes.recentForm.length} matches` + (w ? ` (~${w} marked wins in sample)` : ''));
+        }
+        if (sideARes.keyPlayers.length) {
+            const names = sideARes.keyPlayers
+                .slice(0, 3)
+                .map((p) => pickString(asRecord(p)?.name, asRecord(p)?.nickname, asRecord(p)?.handle))
+                .filter(Boolean);
+            if (names.length)
+                talkingPoints.push(`${sideAName} key names: ${names.join(', ')}`);
+        }
+        if (sideBRes.keyPlayers.length) {
+            const names = sideBRes.keyPlayers
+                .slice(0, 3)
+                .map((p) => pickString(asRecord(p)?.name, asRecord(p)?.nickname, asRecord(p)?.handle))
+                .filter(Boolean);
+            if (names.length)
+                talkingPoints.push(`${sideBName} key names: ${names.join(', ')}`);
+        }
+        const h2hRec = asRecord(h2h);
+        if (h2hRec?.recordNote)
+            talkingPoints.push(String(h2hRec.recordNote));
+        else if (Array.isArray(h2hRec?.meetings) && h2hRec.meetings.length) {
+            talkingPoints.push(`H2H sample includes ${h2hRec.meetings.length} prior meeting(s)`);
+        }
+        if (!talkingPoints.length) {
+            talkingPoints.push('Limited preview data — expand with head_to_head or team_profile for deeper form.');
+        }
+        return successEnvelope({
+            source: 'match_preview',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls,
+            rateLimit,
+            partial: partial.length ? partial : undefined,
+            entities: {
+                games: [game],
+                ids: {
+                    ...(matchId ? { matchId } : {}),
+                    teamA,
+                    teamB,
+                },
+            },
+            data: {
+                context,
+                sideA: {
+                    entity: sideARes.entity,
+                    roster: sideARes.roster,
+                    recentForm: sideARes.recentForm,
+                    keyPlayers: sideARes.keyPlayers,
+                },
+                sideB: {
+                    entity: sideBRes.entity,
+                    roster: sideBRes.roster,
+                    recentForm: sideBRes.recentForm,
+                    keyPlayers: sideBRes.keyPlayers,
+                },
+                h2h,
+                talkingPoints,
+            },
+        });
+    },
+};
+/**
+ * Resolve event id/slug from a free-text query via game event list.
+ */
+async function resolveEventKey(ctx, game, q) {
+    let calls = 0;
+    let rateLimit = {};
+    const needle = q.toLowerCase().trim();
+    if (!needle)
+        return { key: null, name: null, calls, rateLimit };
+    let path = '';
+    let query = { limit: 25, page: 1 };
+    if (game === 'ufc') {
+        path = '/ufc/events';
+        query = { q, limit: 25, page: 1 };
+    }
+    else if (game === 'cs2') {
+        path = '/cs2/events';
+        query = { q, limit: 25, page: 1 };
+    }
+    else if (game === 'lol') {
+        path = '/lol/tournaments';
+        query = { limit: '25' };
+    }
+    else if (game === 'cod') {
+        path = '/cod/tournaments';
+        query = { limit: 25 };
+    }
+    else if (game === 'dota2') {
+        path = '/dota2/tournaments';
+        query = { limit: 25 };
+    }
+    else {
+        return { key: null, name: null, calls, rateLimit };
+    }
+    const res = await fetchJson(ctx, path, { query });
+    calls += 1;
+    rateLimit = res.headers;
+    if (!res.ok)
+        return { key: null, name: null, calls, rateLimit };
+    const rows = extractRows(res.data);
+    let best = null;
+    for (const row of rows) {
+        const r = asRecord(row) ?? {};
+        const id = pickString(r.id, r.eventId, r.tournamentId) ?? '';
+        const slug = pickString(r.slug) ?? '';
+        const name = pickString(r.name, r.title, r.code, slug, id) ?? '';
+        const hay = `${name} ${slug} ${id}`.toLowerCase();
+        let score = 0;
+        if (hay === needle || slug.toLowerCase() === needle || id.toLowerCase() === needle)
+            score = 100;
+        else if (hay.includes(needle))
+            score = 50 + Math.min(20, needle.length);
+        else if (needle.split(/\s+/).every((t) => t && hay.includes(t)))
+            score = 30;
+        if (score > 0 && (!best || score > best.score)) {
+            best = { key: slug || id, name: name || slug || id, score };
+        }
+    }
+    return { key: best?.key ?? null, name: best?.name ?? null, calls, rateLimit };
+}
+export const eventCard = {
+    name: 'event_card',
+    description: `COMPOSITE event / fight-night card: identity, bout or match list, optional standings snippet.
+
+When to use:
+- UFC fight night / numbered event page ("UFC 300 card", "Fight Night")
+- CS2 event hub with match list
+- Tournament/event overview before match_preview drill-down
+
+Prefer over: agent-side resolve + call_api /ufc/events + bout expansion; N+1 match_summary for the card list only.
+
+Prefer match_preview for one bout/match briefing; match_summary for completed recaps; live_matches for live-only strips; standings alone for pure tables.
+
+Do not use when: you only need live scores (live_matches); single finished match recap (match_summary); no event name/id yet and game unknown.
+
+Parallel-safe: yes. Upstream cost: 1–4.
+Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeBouts": true, "includeStandings": false }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            eventIdOrSlug: stringSchema('Event or tournament id/slug. Prefer over q when known. Example: "ufc-300".', 'ufc-300'),
+            q: stringSchema('Free-text event name when id/slug unknown. Example: "UFC 300". Resolves within this tool — still prefer resolve_entity when disambiguating many hits.', 'UFC 300'),
+            includeBouts: boolSchema('Include bout/match list (default true).', true),
+            includeStandings: boolSchema('Include standings/rankings snippet when API supports event/tournament/division scope (default false).', false),
+            limit: limitSchema({
+                default: 20,
+                max: 50,
+                description: 'Max bouts/matches on the card (default 20, max 50).',
+            }),
+        },
+    },
+    handler: async (args, ctx) => {
+        const started = Date.now();
+        const requestId = newRequestId();
+        const gameParse = parseGame(args.game, { allowAll: false, required: true });
+        if (gameParse.error || !gameParse.game || !isPrimaryGame(gameParse.game)) {
+            return errorEnvelope({
+                code: gameParse.error?.includes('unsupported') ? 'UNSUPPORTED_GAME' : 'VALIDATION',
+                message: gameParse.error ?? 'game is required',
+                game: null,
+                source: 'event_card',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        let eventKey = typeof args.eventIdOrSlug === 'string' ? args.eventIdOrSlug.trim() : '';
+        const q = typeof args.q === 'string' ? args.q.trim() : '';
+        const includeBouts = args.includeBouts !== false;
+        const includeStandings = args.includeStandings === true;
+        const limit = clampInt(args.limit, 20, 1, 50);
+        if (!eventKey && !q) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'Pass eventIdOrSlug or q (event name)',
+                game,
+                source: 'event_card',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const partial = [];
+        let upstreamCalls = 0;
+        let rateLimit = {};
+        const warnings = [];
+        if (!eventKey && q) {
+            const resolved = await resolveEventKey(ctx, game, q);
+            upstreamCalls += resolved.calls;
+            rateLimit = { ...rateLimit, ...resolved.rateLimit };
+            if (resolved.key) {
+                eventKey = resolved.key;
+            }
+            else {
+                return errorEnvelope({
+                    code: 'NOT_FOUND',
+                    message: `No event matched q="${q}" for ${game}`,
+                    game,
+                    source: 'event_card',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    rateLimit,
+                    recover: [
+                        'Call resolve_entity { type: "event", game, q } or search_entities, then retry with eventIdOrSlug',
+                        'For next fight night without a name, use upcoming_schedule { game: "ufc" }',
+                    ],
+                });
+            }
+        }
+        let event = {
+            id: eventKey,
+            slug: eventKey,
+            name: q || eventKey,
+            game,
+        };
+        let bouts = [];
+        let standingsSnippet = null;
+        if (game === 'ufc') {
+            const detail = await fetchJson(ctx, `/ufc/events/${encodeURIComponent(eventKey)}`);
+            upstreamCalls += 1;
+            rateLimit = { ...rateLimit, ...detail.headers };
+            if (detail.ok) {
+                const data = asRecord(detail.data) ?? {};
+                const inner = asRecord(data.data) ?? data;
+                event = {
+                    id: pickString(inner.id, eventKey),
+                    slug: pickString(inner.slug, eventKey),
+                    name: pickString(inner.name, inner.title, q, eventKey),
+                    date: pickString(inner.date, inner.startTime, inner.startsAt),
+                    venue: pickString(inner.venue, asRecord(inner.location)?.name),
+                    location: pickString(inner.location, inner.city, inner.country),
+                    status: pickString(inner.status),
+                    game,
+                };
+                if (includeBouts) {
+                    const embedded = extractRows(inner.bouts ?? inner.fights ?? data.bouts);
+                    if (embedded.length) {
+                        bouts = embedded.slice(0, limit).map((row) => normalizeMatch('ufc', {
+                            ...(asRecord(row) ?? {}),
+                            eventName: event.name,
+                            eventId: event.id,
+                            eventSlug: event.slug,
+                        }, undefined));
+                    }
+                }
+            }
+            else if (detail.status === 404) {
+                return errorEnvelope({
+                    code: 'NOT_FOUND',
+                    message: `UFC event not found: ${eventKey}`,
+                    game,
+                    source: 'event_card',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    rateLimit,
+                    httpStatus: 404,
+                    recover: [
+                        'resolve_entity { game: "ufc", type: "event", q } then retry with returned id/slug',
+                        'upcoming_schedule { game: "ufc" } for the next fight nights',
+                    ],
+                });
+            }
+            else {
+                return errorEnvelope({
+                    code: mapHttpToCode(detail.status, { gameNotIncluded: gameNotIncludedHint(detail.data) }),
+                    message: `UFC event detail HTTP ${detail.status}`,
+                    game,
+                    source: 'event_card',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    rateLimit,
+                    httpStatus: detail.status,
+                });
+            }
+            if (includeBouts && bouts.length === 0) {
+                const boutsRes = await fetchJson(ctx, `/ufc/events/${encodeURIComponent(String(event.slug ?? eventKey))}/bouts`);
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...boutsRes.headers };
+                if (boutsRes.ok) {
+                    bouts = extractRows(boutsRes.data)
+                        .slice(0, limit)
+                        .map((row) => normalizeMatch('ufc', {
+                        ...(asRecord(row) ?? {}),
+                        eventName: event.name,
+                        eventId: event.id,
+                        eventSlug: event.slug,
+                    }, undefined));
+                }
+                else {
+                    partial.push(partialFromRejection('bouts', {
+                        code: mapHttpToCode(boutsRes.status),
+                        message: `event bouts HTTP ${boutsRes.status}`,
+                        httpStatus: boutsRes.status,
+                    }));
+                }
+            }
+            if (includeStandings) {
+                const ranks = await fetchJson(ctx, '/ufc/rankings');
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...ranks.headers };
+                if (ranks.ok) {
+                    standingsSnippet = {
+                        scope: 'division',
+                        note: 'UFC global rankings (not event-specific bracket)',
+                        raw: ranks.data,
+                    };
+                }
+                else {
+                    partial.push(partialFromRejection('standings', {
+                        code: mapHttpToCode(ranks.status),
+                        message: `rankings HTTP ${ranks.status}`,
+                        httpStatus: ranks.status,
+                    }));
+                }
+            }
+        }
+        else if (game === 'cs2') {
+            const detail = await fetchJson(ctx, `/cs2/events/${encodeURIComponent(eventKey)}`);
+            upstreamCalls += 1;
+            rateLimit = { ...rateLimit, ...detail.headers };
+            if (detail.ok) {
+                const data = asRecord(detail.data) ?? {};
+                const inner = asRecord(data.data) ?? data;
+                event = {
+                    id: pickString(inner.id, eventKey),
+                    slug: pickString(inner.slug, eventKey),
+                    name: pickString(inner.name, inner.title, q, eventKey),
+                    date: pickString(inner.startDate, inner.date, inner.startTime),
+                    status: pickString(inner.status),
+                    game,
+                };
+            }
+            else if (detail.status === 404) {
+                return errorEnvelope({
+                    code: 'NOT_FOUND',
+                    message: `CS2 event not found: ${eventKey}`,
+                    game,
+                    source: 'event_card',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    rateLimit,
+                    httpStatus: 404,
+                });
+            }
+            else {
+                partial.push(partialFromRejection('event', {
+                    code: mapHttpToCode(detail.status, { gameNotIncluded: gameNotIncludedHint(detail.data) }),
+                    message: `event detail HTTP ${detail.status}`,
+                    httpStatus: detail.status,
+                }));
+                warnings.push('Event detail failed; attempting matches list with event filter');
+            }
+            if (includeBouts) {
+                const matchesRes = await fetchJson(ctx, '/cs2/matches', {
+                    query: { event: eventKey, limit, page: 1 },
+                });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...matchesRes.headers };
+                if (matchesRes.ok) {
+                    bouts = extractRows(matchesRes.data)
+                        .slice(0, limit)
+                        .map((row) => normalizeMatch('cs2', row, undefined));
+                }
+                else {
+                    partial.push(partialFromRejection('bouts', {
+                        code: mapHttpToCode(matchesRes.status),
+                        message: `cs2 matches HTTP ${matchesRes.status}`,
+                        httpStatus: matchesRes.status,
+                    }));
+                }
+            }
+            if (includeStandings) {
+                const st = await fetchJson(ctx, `/cs2/events/${encodeURIComponent(eventKey)}/standings`);
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...st.headers };
+                if (st.ok)
+                    standingsSnippet = { scope: 'event', raw: st.data };
+                else {
+                    partial.push(partialFromRejection('standings', {
+                        code: mapHttpToCode(st.status),
+                        message: `event standings HTTP ${st.status}`,
+                        httpStatus: st.status,
+                    }));
+                }
+            }
+        }
+        else if (game === 'lol') {
+            const detail = await fetchJson(ctx, `/lol/tournaments/${encodeURIComponent(eventKey)}`);
+            upstreamCalls += 1;
+            rateLimit = { ...rateLimit, ...detail.headers };
+            if (detail.ok) {
+                const data = asRecord(detail.data) ?? {};
+                const inner = asRecord(data.data) ?? data;
+                event = {
+                    id: pickString(inner.id, eventKey),
+                    slug: pickString(inner.slug, eventKey),
+                    name: pickString(inner.name, inner.title, q, eventKey),
+                    date: pickString(inner.startDate, inner.date),
+                    status: pickString(inner.status),
+                    game,
+                };
+            }
+            else {
+                partial.push(partialFromRejection('event', {
+                    code: mapHttpToCode(detail.status, { gameNotIncluded: gameNotIncludedHint(detail.data) }),
+                    message: `tournament HTTP ${detail.status}`,
+                    httpStatus: detail.status,
+                }));
+                if (detail.status === 404) {
+                    return errorEnvelope({
+                        code: 'NOT_FOUND',
+                        message: `LoL tournament not found: ${eventKey}`,
+                        game,
+                        source: 'event_card',
+                        requestId,
+                        tookMs: Date.now() - started,
+                        upstreamCalls,
+                        rateLimit,
+                        httpStatus: 404,
+                    });
+                }
+            }
+            if (includeBouts) {
+                const sched = await fetchJson(ctx, '/lol/schedule', {
+                    query: { tournamentId: eventKey, limit: String(limit) },
+                });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...sched.headers };
+                if (sched.ok) {
+                    bouts = extractRows(sched.data)
+                        .slice(0, limit)
+                        .map((row) => normalizeMatch('lol', row, undefined));
+                }
+                else {
+                    partial.push(partialFromRejection('bouts', {
+                        code: mapHttpToCode(sched.status),
+                        message: `schedule HTTP ${sched.status}`,
+                        httpStatus: sched.status,
+                    }));
+                }
+            }
+            if (includeStandings) {
+                const st = await fetchJson(ctx, `/lol/tournaments/${encodeURIComponent(eventKey)}/standings`);
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...st.headers };
+                if (st.ok)
+                    standingsSnippet = { scope: 'tournament', raw: st.data };
+                else {
+                    partial.push(partialFromRejection('standings', {
+                        code: mapHttpToCode(st.status),
+                        message: `tournament standings HTTP ${st.status}`,
+                        httpStatus: st.status,
+                    }));
+                }
+            }
+        }
+        else if (game === 'cod') {
+            const detail = await fetchJson(ctx, `/cod/tournaments/${encodeURIComponent(eventKey)}`);
+            upstreamCalls += 1;
+            rateLimit = { ...rateLimit, ...detail.headers };
+            if (detail.ok) {
+                const data = asRecord(detail.data) ?? {};
+                const inner = asRecord(data.data) ?? data;
+                event = {
+                    id: pickString(inner.id, eventKey),
+                    slug: pickString(inner.slug, eventKey),
+                    name: pickString(inner.name, inner.title, q, eventKey),
+                    game,
+                };
+            }
+            else if (detail.status === 404) {
+                return errorEnvelope({
+                    code: 'NOT_FOUND',
+                    message: `COD tournament not found: ${eventKey}`,
+                    game,
+                    source: 'event_card',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    rateLimit,
+                    httpStatus: 404,
+                });
+            }
+            else {
+                partial.push(partialFromRejection('event', {
+                    code: mapHttpToCode(detail.status, { gameNotIncluded: gameNotIncludedHint(detail.data) }),
+                    message: `tournament HTTP ${detail.status}`,
+                    httpStatus: detail.status,
+                }));
+            }
+            if (includeBouts) {
+                const matchesRes = await fetchJson(ctx, '/cod/matches', {
+                    query: { tournamentId: eventKey, limit },
+                });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...matchesRes.headers };
+                if (matchesRes.ok) {
+                    bouts = extractRows(matchesRes.data)
+                        .slice(0, limit)
+                        .map((row) => normalizeMatch('cod', row, undefined));
+                }
+                else {
+                    partial.push(partialFromRejection('bouts', {
+                        code: mapHttpToCode(matchesRes.status),
+                        message: `cod matches HTTP ${matchesRes.status}`,
+                        httpStatus: matchesRes.status,
+                    }));
+                }
+            }
+            if (includeStandings) {
+                const st = await fetchJson(ctx, '/cod/standings', { query: { tournamentId: eventKey } });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...st.headers };
+                if (st.ok)
+                    standingsSnippet = { scope: 'tournament', raw: st.data };
+                else {
+                    partial.push(partialFromRejection('standings', {
+                        code: mapHttpToCode(st.status),
+                        message: `cod standings HTTP ${st.status}`,
+                        httpStatus: st.status,
+                    }));
+                }
+            }
+        }
+        else {
+            // dota2 — thin: tournament list + recent matches only
+            warnings.push('Dota2 event_card is thin; expect partial bouts/standings');
+            const detail = await fetchJson(ctx, `/dota2/tournaments/${encodeURIComponent(eventKey)}`);
+            upstreamCalls += 1;
+            rateLimit = { ...rateLimit, ...detail.headers };
+            if (detail.ok) {
+                const data = asRecord(detail.data) ?? {};
+                const inner = asRecord(data.data) ?? data;
+                event = {
+                    id: pickString(inner.id, eventKey),
+                    slug: pickString(inner.slug, eventKey),
+                    name: pickString(inner.name, inner.title, q, eventKey),
+                    game,
+                };
+            }
+            else {
+                partial.push(partialFromRejection('event', {
+                    code: mapHttpToCode(detail.status, { gameNotIncluded: gameNotIncludedHint(detail.data) }),
+                    message: `dota tournament HTTP ${detail.status}`,
+                    httpStatus: detail.status,
+                }));
+                event = { id: eventKey, slug: eventKey, name: q || eventKey, game };
+            }
+            if (includeBouts) {
+                const matchesRes = await fetchJson(ctx, '/dota2/matches/upcoming', { query: { limit } });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...matchesRes.headers };
+                if (matchesRes.ok) {
+                    const key = eventKey.toLowerCase();
+                    bouts = extractRows(matchesRes.data)
+                        .map((row) => normalizeMatch('dota2', row, 'upcoming'))
+                        .filter((m) => {
+                        const hay = `${m.event?.id ?? ''} ${m.event?.slug ?? ''} ${m.event?.name ?? ''}`.toLowerCase();
+                        return hay.includes(key) || !key;
+                    })
+                        .slice(0, limit);
+                    if (!bouts.length) {
+                        warnings.push('No dota upcoming matches matched this tournament filter');
+                    }
+                }
+                else {
+                    partial.push(partialFromRejection('bouts', {
+                        code: mapHttpToCode(matchesRes.status),
+                        message: `dota upcoming HTTP ${matchesRes.status}`,
+                        httpStatus: matchesRes.status,
+                    }));
+                }
+            }
+            if (includeStandings) {
+                warnings.push('Dota standings often NOT_IMPLEMENTED');
+                partial.push(partialFromRejection('standings', {
+                    code: 'NOT_IMPLEMENTED',
+                    message: 'Dota has no first-class event standings in curated surface',
+                }));
+            }
+        }
+        return successEnvelope({
+            source: 'event_card',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls,
+            rateLimit,
+            warnings: warnings.length ? warnings : undefined,
+            partial: partial.length ? partial : undefined,
+            entities: {
+                games: [game],
+                ids: {
+                    eventId: String(event.id ?? eventKey),
+                    ...(event.slug ? { eventSlug: String(event.slug) } : {}),
+                },
+            },
+            data: {
+                event,
+                bouts: includeBouts ? bouts : [],
+                boutCount: includeBouts ? bouts.length : 0,
+                standings: includeStandings ? standingsSnippet : null,
+                nextSteps: [
+                    'For a featured bout/match: match_preview { game, matchId } or teamA+teamB',
+                    'When live: live_matches then match_summary / match_details',
+                    'Completed recap: match_summary { game, matchId: boutId }',
+                ],
+                ...(warnings.length ? { warnings } : {}),
+            },
+        });
+    },
+};
+export const insightTools = [matchPreview, eventCard];