cito-mcp 0.1.0 → 0.2.2

package/dist/tools/team.js

@@ -0,0 +1,704 @@
+/**
+ * team_profile + head_to_head
+ */
+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';
+function teamIdentity(game, raw, idHint, slugHint) {
+    const r = asRecord(raw) ?? {};
+    const nested = asRecord(r.data) ?? r;
+    const id = pickString(nested.id, nested.teamId, idHint, slugHint) ?? 'unknown';
+    const slug = pickString(nested.slug, nested.orgSlug, slugHint);
+    const name = pickString(nested.name, nested.tag, nested.code, slug, id) ?? id;
+    return {
+        id,
+        slug,
+        name,
+        game,
+        region: pickString(nested.region, nested.country) ?? null,
+    };
+}
+export const teamProfile = {
+    name: 'team_profile',
+    description: `Team/org card: identity, roster, recent matches, and form/trends/radar when available.
+
+When to use:
+- Team page / "who is on this roster?"
+- Builder team screen sample
+
+Prefer over: separate roster + matches + detail via call_api.
+
+Do not use when: UFC fighters → player_profile; unknown name → resolve_entity first.
+Dota may return partial roster (API gap). Prefer slug for lol/cod; teamId for cs2.
+
+Parallel-safe: yes. Upstream cost: 2–4.
+Example: { "game": "lol", "slug": "t1", "recentLimit": 10 }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            teamId: stringSchema('Team id. Prefer for cs2. Pass teamId and/or slug (at least one required). Either works for dota2.'),
+            slug: stringSchema('Team/org slug. Prefer for lol and cod orgs. Pass teamId and/or slug (at least one required). Example: "t1".', 't1'),
+            recentLimit: limitSchema({ default: 10, max: 25 }),
+            includeFormer: boolSchema('COD roster former players.', false),
+            view: {
+                type: 'string',
+                enum: ['summary', 'full'],
+                default: 'summary',
+                description: 'Payload weight. Default summary.',
+            },
+        },
+    },
+    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: 'team_profile',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        if (game === 'ufc') {
+            return errorEnvelope({
+                code: 'NOT_IMPLEMENTED',
+                message: 'UFC has fighters, not team profiles',
+                game,
+                source: 'team_profile',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: [
+                    'Use player_profile with fighter slug',
+                    'Use standings with scope=division for rankings',
+                ],
+            });
+        }
+        const teamId = typeof args.teamId === 'string' ? args.teamId.trim() : '';
+        const slug = typeof args.slug === 'string' ? args.slug.trim() : '';
+        if (!teamId && !slug) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'Pass teamId and/or slug (at least one required)',
+                game,
+                source: 'team_profile',
+                requestId,
+                tookMs: Date.now() - started,
+                recover: [
+                    'Call resolve_entity with the team name and type=team',
+                    'Retry team_profile with the returned id or slug',
+                ],
+            });
+        }
+        const idOrSlug = teamId || slug;
+        const recentLimit = clampInt(args.recentLimit, 10, 1, 25);
+        const partial = [];
+        let upstreamCalls = 0;
+        let rateLimit = {};
+        let teamRaw = null;
+        if (game === 'lol') {
+            const res = await fetchJson(ctx, `/lol/teams/${encodeURIComponent(slug || idOrSlug)}`);
+            upstreamCalls += 1;
+            rateLimit = res.headers;
+            if (!res.ok) {
+                return errorEnvelope({
+                    code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                    message: `Team not found: ${idOrSlug}`,
+                    game,
+                    source: 'team_profile',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    httpStatus: res.status,
+                    rateLimit: res.headers,
+                });
+            }
+            teamRaw = res.data;
+        }
+        else if (game === 'cs2') {
+            const res = await fetchJson(ctx, '/cs2/teams', { query: { search: idOrSlug, limit: 5 } });
+            upstreamCalls += 1;
+            rateLimit = res.headers;
+            if (!res.ok) {
+                return errorEnvelope({
+                    code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                    message: `Team not found: ${idOrSlug}`,
+                    game,
+                    source: 'team_profile',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    httpStatus: res.status,
+                    rateLimit: res.headers,
+                    recover: [
+                        'Call resolve_entity with the team name and type=team',
+                        'Retry team_profile with the returned id/slug',
+                    ],
+                });
+            }
+            {
+                const rows = extractRows(res.data);
+                teamRaw =
+                    rows.find((row) => {
+                        const r = asRecord(row) ?? {};
+                        return [r.id, r.slug, r.name].map((x) => String(x ?? '').toLowerCase()).includes(idOrSlug.toLowerCase());
+                    }) ?? rows[0];
+                if (!teamRaw) {
+                    return errorEnvelope({
+                        code: 'NOT_FOUND',
+                        message: `Team not found: ${idOrSlug}`,
+                        game,
+                        source: 'team_profile',
+                        requestId,
+                        tookMs: Date.now() - started,
+                        upstreamCalls,
+                        rateLimit: res.headers,
+                        recover: [
+                            'Call resolve_entity with the team name and type=team',
+                            'Retry team_profile with the returned id/slug',
+                        ],
+                    });
+                }
+            }
+        }
+        else if (game === 'dota2') {
+            const res = await fetchJson(ctx, '/dota2/teams', { query: { search: idOrSlug, limit: 5 } });
+            upstreamCalls += 1;
+            rateLimit = res.headers;
+            if (!res.ok) {
+                return errorEnvelope({
+                    code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                    message: `Team not found: ${idOrSlug}`,
+                    game,
+                    source: 'team_profile',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    httpStatus: res.status,
+                    rateLimit: res.headers,
+                    recover: [
+                        'Call resolve_entity with the team name and type=team',
+                        'Retry team_profile with the returned id/slug',
+                    ],
+                });
+            }
+            {
+                const rows = extractRows(res.data);
+                teamRaw =
+                    rows.find((row) => {
+                        const r = asRecord(row) ?? {};
+                        return [r.id, r.slug, r.name].map((x) => String(x ?? '').toLowerCase()).includes(idOrSlug.toLowerCase());
+                    }) ?? rows[0];
+                if (!teamRaw) {
+                    return errorEnvelope({
+                        code: 'NOT_FOUND',
+                        message: `Team not found: ${idOrSlug}`,
+                        game,
+                        source: 'team_profile',
+                        requestId,
+                        tookMs: Date.now() - started,
+                        upstreamCalls,
+                        rateLimit: res.headers,
+                        recover: [
+                            'Call resolve_entity with the team name and type=team',
+                            'Retry team_profile with the returned id/slug',
+                        ],
+                    });
+                }
+            }
+        }
+        else if (game === 'cod') {
+            const res = await fetchJson(ctx, `/cod/orgs/${encodeURIComponent(slug || idOrSlug)}`);
+            upstreamCalls += 1;
+            rateLimit = res.headers;
+            if (!res.ok) {
+                return errorEnvelope({
+                    code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                    message: `Org not found: ${idOrSlug}`,
+                    game,
+                    source: 'team_profile',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    httpStatus: res.status,
+                    rateLimit: res.headers,
+                });
+            }
+            teamRaw = res.data;
+        }
+        const team = teamIdentity(game, teamRaw, teamId || undefined, slug || undefined);
+        let roster = {
+            items: [],
+            asOf: new Date().toISOString(),
+            quality: 'unknown',
+        };
+        let recentMatches = [];
+        let form = null;
+        const tasks = [];
+        if (game === 'lol') {
+            tasks.push((async () => {
+                const res = await fetchJson(ctx, `/lol/teams/${encodeURIComponent(team.slug || idOrSlug)}/roster`);
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (res.ok) {
+                    roster = {
+                        items: extractRows(res.data),
+                        asOf: new Date().toISOString(),
+                        quality: 'current',
+                    };
+                }
+                else {
+                    partial.push(partialFromRejection('roster', {
+                        code: mapHttpToCode(res.status),
+                        message: `roster HTTP ${res.status}`,
+                        httpStatus: res.status,
+                    }));
+                }
+            })());
+            tasks.push((async () => {
+                const res = await fetchJson(ctx, '/lol/schedule', {
+                    query: { teamSlug: team.slug || idOrSlug, completed: 'true', limit: String(recentLimit) },
+                });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (res.ok) {
+                    recentMatches = extractRows(res.data)
+                        .slice(0, recentLimit)
+                        .map((row) => normalizeMatch('lol', row, 'completed'));
+                }
+                else {
+                    partial.push(partialFromRejection('recentMatches', {
+                        code: mapHttpToCode(res.status),
+                        message: `schedule HTTP ${res.status}`,
+                        httpStatus: res.status,
+                    }));
+                }
+            })());
+        }
+        if (game === 'cs2') {
+            const tid = team.id !== 'unknown' ? team.id : idOrSlug;
+            tasks.push((async () => {
+                const res = await fetchJson(ctx, `/cs2/teams/${encodeURIComponent(tid)}/roster-history`);
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (res.ok) {
+                    roster = {
+                        items: extractRows(res.data).slice(0, 20),
+                        asOf: new Date().toISOString(),
+                        quality: 'history',
+                    };
+                }
+                else {
+                    partial.push(partialFromRejection('roster', {
+                        code: mapHttpToCode(res.status),
+                        message: `roster-history HTTP ${res.status}`,
+                        httpStatus: res.status,
+                    }));
+                }
+            })());
+            tasks.push((async () => {
+                const res = await fetchJson(ctx, `/cs2/teams/${encodeURIComponent(tid)}/trends`);
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (res.ok)
+                    form = res.data;
+                else {
+                    partial.push(partialFromRejection('form', {
+                        code: mapHttpToCode(res.status),
+                        message: `trends HTTP ${res.status}`,
+                        httpStatus: res.status,
+                    }));
+                }
+            })());
+            tasks.push((async () => {
+                const res = await fetchJson(ctx, '/cs2/matches', {
+                    query: { team: tid, limit: recentLimit, status: 'completed' },
+                });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (res.ok) {
+                    recentMatches = extractRows(res.data)
+                        .slice(0, recentLimit)
+                        .map((row) => normalizeMatch('cs2', row, 'completed'));
+                }
+                else {
+                    partial.push(partialFromRejection('recentMatches', {
+                        code: mapHttpToCode(res.status),
+                        message: `matches HTTP ${res.status}`,
+                        httpStatus: res.status,
+                    }));
+                }
+            })());
+        }
+        if (game === 'dota2') {
+            roster = { items: [], asOf: new Date().toISOString(), quality: 'unavailable' };
+            partial.push(partialFromRejection('roster', {
+                code: 'NOT_IMPLEMENTED',
+                message: 'Dota 2 has no dedicated roster endpoint',
+                recover: ['Use team radar and recent matches', 'Call call_api only if a new roster path ships'],
+            }));
+            tasks.push((async () => {
+                const res = await fetchJson(ctx, `/dota2/teams/${encodeURIComponent(idOrSlug)}/radar`);
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (res.ok)
+                    form = { radar: res.data };
+                else {
+                    partial.push(partialFromRejection('form', {
+                        code: mapHttpToCode(res.status),
+                        message: `radar HTTP ${res.status}`,
+                        httpStatus: res.status,
+                    }));
+                }
+            })());
+            tasks.push((async () => {
+                const res = await fetchJson(ctx, '/dota2/matches/recent', { query: { limit: recentLimit } });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (res.ok) {
+                    const t = idOrSlug.toLowerCase();
+                    recentMatches = extractRows(res.data)
+                        .map((row) => normalizeMatch('dota2', row, 'completed'))
+                        .filter((m) => {
+                        const hay = [m.team1?.id, m.team1?.name, m.team2?.id, m.team2?.name]
+                            .filter(Boolean)
+                            .join(' ')
+                            .toLowerCase();
+                        return hay.includes(t);
+                    })
+                        .slice(0, recentLimit);
+                }
+                else {
+                    partial.push(partialFromRejection('recentMatches', {
+                        code: mapHttpToCode(res.status),
+                        message: `recent matches HTTP ${res.status}`,
+                        httpStatus: res.status,
+                    }));
+                }
+            })());
+        }
+        if (game === 'cod') {
+            tasks.push((async () => {
+                const res = await fetchJson(ctx, `/cod/orgs/${encodeURIComponent(team.slug || idOrSlug)}/roster`, {
+                    query: { includeFormer: args.includeFormer === true },
+                });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (res.ok) {
+                    roster = {
+                        items: extractRows(res.data),
+                        asOf: new Date().toISOString(),
+                        quality: 'current',
+                    };
+                }
+                else {
+                    partial.push(partialFromRejection('roster', {
+                        code: mapHttpToCode(res.status),
+                        message: `roster HTTP ${res.status}`,
+                        httpStatus: res.status,
+                    }));
+                }
+            })());
+            tasks.push((async () => {
+                const res = await fetchJson(ctx, '/cod/matches', {
+                    query: { team: team.slug || idOrSlug, limit: recentLimit },
+                });
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...res.headers };
+                if (res.ok) {
+                    recentMatches = extractRows(res.data)
+                        .slice(0, recentLimit)
+                        .map((row) => normalizeMatch('cod', row));
+                }
+                else {
+                    partial.push(partialFromRejection('recentMatches', {
+                        code: mapHttpToCode(res.status),
+                        message: `matches HTTP ${res.status}`,
+                        httpStatus: res.status,
+                    }));
+                }
+            })());
+        }
+        await Promise.all(tasks);
+        return successEnvelope({
+            source: 'team_profile',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls,
+            rateLimit,
+            partial: partial.length ? partial : undefined,
+            entities: {
+                games: [game],
+                ids: {
+                    teamId: team.id,
+                    ...(team.slug ? { teamSlug: team.slug } : {}),
+                },
+            },
+            data: {
+                team,
+                roster,
+                recentMatches,
+                form,
+            },
+        });
+    },
+};
+function sidesMatch(match, a, b) {
+    const al = a.toLowerCase();
+    const bl = b.toLowerCase();
+    const s1 = [match.team1?.id, match.team1?.slug, match.team1?.name].filter(Boolean).map((x) => String(x).toLowerCase());
+    const s2 = [match.team2?.id, match.team2?.slug, match.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);
+}
+function winnerSide(match, a) {
+    const s1 = match.team1?.score;
+    const s2 = match.team2?.score;
+    if (s1 == null || s2 == null)
+        return 'unknown';
+    if (s1 === s2)
+        return 'draw';
+    const al = a.toLowerCase();
+    const t1 = [match.team1?.id, match.team1?.slug, match.team1?.name].filter(Boolean).map((x) => String(x).toLowerCase());
+    const aIsTeam1 = t1.some((x) => x.includes(al) || al.includes(x));
+    if (s1 > s2)
+        return aIsTeam1 ? 'A' : 'B';
+    return aIsTeam1 ? 'B' : 'A';
+}
+export const headToHead = {
+    name: 'head_to_head',
+    description: `Composed head-to-head record between two teams (or two UFC fighters). No first-class REST H2H exists — this tool filters match history server-side.
+
+When to use:
+- Rivalry / series record questions
+- Supporting context for previews
+
+Prefer over: agent-side double match-list filtering.
+
+Do not use when: single-side form only → team_profile or player_profile.
+
+Caveat: Dota filters are weaker; expect meta.warnings when data is sparse.
+
+Parallel-safe: yes. Upstream cost: 2–4.
+Example: { "game": "cs2", "sideA": "faze", "sideB": "navi", "limit": 20 }`,
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['game', 'sideA', 'sideB'],
+        properties: {
+            game: gameSchema({ allowAll: false, required: true }),
+            entityType: {
+                type: 'string',
+                enum: ['team', 'fighter'],
+                default: 'team',
+                description: 'team (default) or fighter (UFC).',
+            },
+            sideA: stringSchema('Id or slug for side A.', 'faze'),
+            sideB: stringSchema('Id or slug for side B.', 'navi'),
+            limit: limitSchema({ default: 20, max: 50, description: 'Max meetings returned.' }),
+            from: stringSchema('ISO-8601 lower bound on meeting startTime (client filter).'),
+            to: stringSchema('ISO-8601 upper bound on meeting startTime (client filter).'),
+        },
+    },
+    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: 'head_to_head',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const game = gameParse.game;
+        const sideA = typeof args.sideA === 'string' ? args.sideA.trim() : '';
+        const sideB = typeof args.sideB === 'string' ? args.sideB.trim() : '';
+        if (!sideA || !sideB) {
+            return errorEnvelope({
+                code: 'VALIDATION',
+                message: 'sideA and sideB are required',
+                game,
+                source: 'head_to_head',
+                requestId,
+                tookMs: Date.now() - started,
+            });
+        }
+        const limit = clampInt(args.limit, 20, 1, 50);
+        const fromIso = typeof args.from === 'string' ? args.from : undefined;
+        const toIso = typeof args.to === 'string' ? args.to : undefined;
+        const fromMs = fromIso ? Date.parse(fromIso) : NaN;
+        const toMs = toIso ? Date.parse(toIso) : NaN;
+        const warnings = [];
+        let upstreamCalls = 0;
+        let rateLimit = {};
+        let rows = [];
+        if (game === 'cs2') {
+            const res = await fetchJson(ctx, '/cs2/matches', { query: { team: sideA, limit: 50 } });
+            upstreamCalls += 1;
+            rateLimit = res.headers;
+            if (!res.ok) {
+                return errorEnvelope({
+                    code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
+                    message: `H2H match fetch failed (HTTP ${res.status})`,
+                    game,
+                    source: 'head_to_head',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    httpStatus: res.status,
+                    rateLimit: res.headers,
+                });
+            }
+            rows = extractRows(res.data);
+        }
+        else if (game === 'cod') {
+            const res = await fetchJson(ctx, '/cod/matches', { query: { team: sideA, limit: 50 } });
+            upstreamCalls += 1;
+            rateLimit = res.headers;
+            if (!res.ok) {
+                return errorEnvelope({
+                    code: mapHttpToCode(res.status),
+                    message: `H2H match fetch failed (HTTP ${res.status})`,
+                    game,
+                    source: 'head_to_head',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    httpStatus: res.status,
+                    rateLimit: res.headers,
+                });
+            }
+            rows = extractRows(res.data);
+        }
+        else if (game === 'lol') {
+            const res = await fetchJson(ctx, '/lol/schedule', {
+                query: { teamSlug: sideA, completed: 'true', limit: '50' },
+            });
+            upstreamCalls += 1;
+            rateLimit = res.headers;
+            if (!res.ok) {
+                return errorEnvelope({
+                    code: mapHttpToCode(res.status),
+                    message: `H2H schedule fetch failed (HTTP ${res.status})`,
+                    game,
+                    source: 'head_to_head',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    httpStatus: res.status,
+                    rateLimit: res.headers,
+                });
+            }
+            rows = extractRows(res.data);
+        }
+        else if (game === 'dota2') {
+            warnings.push('Dota H2H uses recent matches with weak filters; record may be incomplete');
+            const res = await fetchJson(ctx, '/dota2/matches/recent', { query: { limit: 50 } });
+            upstreamCalls += 1;
+            rateLimit = res.headers;
+            if (!res.ok) {
+                return errorEnvelope({
+                    code: mapHttpToCode(res.status),
+                    message: `H2H recent fetch failed (HTTP ${res.status})`,
+                    game,
+                    source: 'head_to_head',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    httpStatus: res.status,
+                    rateLimit: res.headers,
+                });
+            }
+            rows = extractRows(res.data);
+        }
+        else if (game === 'ufc') {
+            // try fighter stats + bouts list
+            const [aRes, bRes, boutsRes] = await Promise.all([
+                fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(sideA)}`),
+                fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(sideB)}`),
+                fetchJson(ctx, '/ufc/bouts', { query: { limit: 50, page: 1 } }),
+            ]);
+            upstreamCalls += 3;
+            rateLimit = { ...aRes.headers, ...bRes.headers, ...boutsRes.headers };
+            if (!aRes.ok || !bRes.ok) {
+                return errorEnvelope({
+                    code: 'NOT_FOUND',
+                    message: 'One or both fighters not found',
+                    game,
+                    source: 'head_to_head',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                });
+            }
+            rows = boutsRes.ok ? extractRows(boutsRes.data) : [];
+        }
+        const meetings = rows
+            .map((row) => normalizeMatch(game, row))
+            .filter((m) => sidesMatch(m, sideA, sideB))
+            .filter((m) => {
+            if (!fromIso && !toIso)
+                return true;
+            if (!m.startTime)
+                return true; // keep undated rows; date filter is best-effort
+            const t = Date.parse(m.startTime);
+            if (Number.isNaN(t))
+                return true;
+            if (!Number.isNaN(fromMs) && t < fromMs)
+                return false;
+            if (!Number.isNaN(toMs) && t > toMs)
+                return false;
+            return true;
+        })
+            .slice(0, limit);
+        let winsA = 0;
+        let winsB = 0;
+        let draws = 0;
+        for (const m of meetings) {
+            const w = winnerSide(m, sideA);
+            if (w === 'A')
+                winsA += 1;
+            else if (w === 'B')
+                winsB += 1;
+            else if (w === 'draw')
+                draws += 1;
+        }
+        return successEnvelope({
+            source: 'head_to_head',
+            game,
+            requestId,
+            tookMs: Date.now() - started,
+            upstreamCalls,
+            rateLimit,
+            warnings: warnings.length ? warnings : undefined,
+            data: {
+                sideA: { idOrSlug: sideA },
+                sideB: { idOrSlug: sideB },
+                record: { winsA, winsB, draws, meetings: meetings.length },
+                meetings,
+                lastMeeting: meetings[0] ?? null,
+                notes: warnings.length
+                    ? warnings
+                    : meetings.length === 0
+                        ? ['No meetings found in available history window']
+                        : [],
+            },
+        });
+    },
+};
+export const teamTools = [teamProfile, headToHead];