cito-mcp 0.4.4 → 0.4.6

package/dist/tools/live.js

@@ -1,26 +1,15 @@
-/**
- * live_matches + upcoming_schedule
- */
 import { clampInt, decodeCursor, encodeCursor, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, } from '../client.js';
 import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT, errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
 import { normalizeMatch, presentSides } from './normalize.js';
 import { boolSchema, gameSchema, isPrimaryGame, limitSchema, parseGame, PRIMARY_GAMES, stringSchema, } from './types.js';
 const LIVE_PATHS = {
     lol: '/lol/live',
-    cs2: '/cs2/live', // fixed: not /cs2/matches/live
+    cs2: '/cs2/live',
     dota2: '/dota2/matches/live',
     cod: '/cod/matches/live',
     ufc: '/ufc/live',
     tennis: '/tennis/matches/live',
 };
-/**
- * Extract live match/bout rows. UFC /ufc/live returns
- * { liveBouts, events, ... } — events are supervisor shells without fighters.
- * Prefer liveBouts (and nested tracking on events) over plain events[].
- * Never promote bare events[] to match rows (avoids fake "? vs ?").
- * Nested tracking with status armed is excluded from live items (use nextCard).
- * Exported for offline UFC projection tests.
- */
 export function extractLiveRows(data, game) {
     const root = asRecord(data);
     const payload = asRecord(root?.data) ?? root;
@@ -31,7 +20,6 @@ export function extractLiveRows(data, game) {
             for (const t of tracking) {
                 const tr = asRecord(t) ?? {};
                 const status = String(pickString(tr.status) ?? '').toLowerCase();
-                // Board items = live|watching only; armed is surfaced as nextCard, not items.
                 if (status === 'armed' || status === 'completed' || status === 'stale')
                     continue;
                 out.push({
@@ -41,12 +29,10 @@ export function extractLiveRows(data, game) {
                 });
             }
         };
-        // Prefer liveBouts when the key is present (including empty [] — honest empty board).
         if (Array.isArray(payload.liveBouts)) {
             const liveBouts = payload.liveBouts;
             if (liveBouts.length)
                 return liveBouts;
-            // Empty liveBouts: still check nested tracking, but never bare events[]
             const eventsWithEmptyLive = Array.isArray(payload.events)
                 ? payload.events
                 : [];
@@ -56,9 +42,8 @@ export function extractLiveRows(data, game) {
                 const tracking = Array.isArray(er?.tracking) ? er.tracking : [];
                 pushLiveTracking(tracking, er, nested);
             }
-            return nested; // [] when only supervisor shells / armed-only
+            return nested;
         }
-        // liveBouts key missing — try nested tracking under events
         const events = Array.isArray(payload.events) ? payload.events : [];
         const fromTracking = [];
         for (const ev of events) {
@@ -68,21 +53,15 @@ export function extractLiveRows(data, game) {
         }
         if (fromTracking.length)
             return fromTracking;
-        // Last resort: empty live board rather than fake ? vs ? event shells
         return [];
     }
     return extractRows(data);
 }
-/** Machine emptyReason codes from API health / meta (or inferred). */
 export function inferUfcEmptyReason(events, health, liveCount) {
     if (liveCount > 0)
         return undefined;
     const pulses = events.map((ev) => asRecord(ev) ?? {});
     const hotNow = pulses.some((p) => ['live', 'warming', 'between_bouts', 'degraded'].includes(String(pickString(p.status, p.eventStatus) ?? '').toLowerCase()));
-    // The API's own health block is trusted first, EXCEPT when it blames the
-    // worker on a day nothing is live. It computes worker_stale from heartbeat
-    // lag alone, so an idle Thursday reads the same as a dead worker on fight
-    // night. With no hot card there is nothing to be stale about.
     const fromHealth = pickString(health?.emptyReason);
     if (fromHealth && !(['worker_stale', 'worker_down_inferred'].includes(fromHealth) && !hotNow)) {
         return fromHealth;
@@ -100,10 +79,6 @@ export function inferUfcEmptyReason(events, health, liveCount) {
     const freshest = lags.length ? Math.min(...lags) : null;
     const workerAlive = health?.workerAlive ?? health?.workerStarted;
     const hot = statuses.some((s) => ['live', 'warming', 'between_bouts', 'degraded'].includes(s));
-    // Only a HOT card can be stale. On an idle day every event is "scheduled"
-    // and the heartbeat lags because there is nothing to beat about; reporting
-    // that as worker_stale made a quiet Thursday indistinguishable from a dead
-    // worker on fight night. freshest stays computed for the health block.
     void freshest;
     if (workerAlive === false && hot)
         return 'worker_stale';
@@ -119,7 +94,6 @@ export function inferUfcEmptyReason(events, health, liveCount) {
         return 'between_bouts';
     return 'not_fight_night';
 }
-/** Human note for empty UFC live section — never invent matchups. */
 export function humanUfcEmptyNote(emptyReason, health) {
     const alive = health?.workerAlive ?? health?.workerStarted;
     const lag = typeof health?.freshestHeartbeatLagSeconds === 'number'
@@ -136,8 +110,6 @@ export function humanUfcEmptyNote(emptyReason, health) {
         supervisor_warming: 'Card open / pre-gate; no bout live yet',
         between_bouts: 'Between bouts; next may be armed',
         armed_only: 'Next bout armed; not started',
-        // Customer-facing. The pm2/VPS operator hint used to be in here and went
-        // out in every empty board; health{} already carries the numbers for us.
         worker_stale: 'Live feed is behind; scores may lag',
         worker_down_inferred: 'Live feed unavailable right now',
         event_degraded: 'Sources empty clock / event degraded; not inventing stats',
@@ -174,8 +146,6 @@ function slimUfcNextCard(payload) {
         status: pickString(first.status) ?? 'armed',
         boutId: pickString(first.boutId, first.id) ?? null,
         eventSlug: pickString(first.eventSlug) ?? null,
-        fightMetricId: first.fightMetricId ?? null,
-        // Names only if API already provided them — never invent.
         red: first.red ?? null,
         blue: first.blue ?? null,
         degradedReason: pickString(first.degradedReason) ?? null,
@@ -184,20 +154,20 @@ function slimUfcNextCard(payload) {
 }
 export const liveMatches = {
     name: 'live_matches',
-    description: `Live matches board across primary games, or a single game filter. Normalized labels, scores, and matchIds.
-
-When to use:
-- "What's live right now?"
-- Ops/dashboard live strip
-
-Prefer over: sequential per-game call_api live probes.
-
-Do not use when: user wants upcoming fixtures → upcoming_schedule; historical results → match_summary.
-
-CS2 live path is /cs2/live; UFC is included in multi-game fan-out.
-UFC empty board: section.note + emptyReason + health (workerAlive/lag) + optional supervisor/nextCard (non-live); never fake match items from events[].
-
-Parallel-safe: yes. Upstream cost: 1–5 (allSettled).
+    description: `Live matches board across primary games, or a single game filter. Normalized labels, scores, and matchIds.
+
+When to use:
+- "What's live right now?"
+- Ops/dashboard live strip
+
+Prefer over: sequential per-game call_api live probes.
+
+Do not use when: user wants upcoming fixtures → upcoming_schedule; historical results → match_summary.
+
+CS2 live path is /cs2/live; UFC is included in multi-game fan-out.
+UFC empty board: section.note + emptyReason + health (workerAlive/lag) + optional supervisor/nextCard (non-live); never fake match items from events[].
+
+Parallel-safe: yes. Upstream cost: 1–5 (allSettled).
 Example: { "game": "all", "limitPerGame": 10 }`,
     inputSchema: {
         type: 'object',
@@ -260,7 +230,6 @@ Example: { "game": "all", "limitPerGame": 10 }`,
                 });
                 continue;
             }
-            // Prefer real match/bout rows over supervisor event shells (UFC /ufc/live).
             let rows = extractLiveRows(res.data, game);
             const root = asRecord(res.data);
             const payload = asRecord(root?.data) ?? root;
@@ -270,9 +239,6 @@ Example: { "game": "all", "limitPerGame": 10 }`,
             const normalized = rows
                 .slice(0, limitPerGame)
                 .map((row) => normalizeMatch(game, row, 'live'))
-                // Drop hollow UFC rows agents cannot use (placeholder labels / no sides).
-                // normalizeMatch already enriches label from eventSlug/weight/bout id when
-                // fighters are pending — keep those; drop pure "? vs ?" only.
                 .filter((m) => {
                 if (game !== 'ufc')
                     return true;
@@ -281,7 +247,6 @@ Example: { "game": "all", "limitPerGame": 10 }`,
                     return false;
                 if (m.team1?.name || m.team2?.name)
                     return true;
-                // Identity-only live row (enriched Bout {id} / event name) is ok
                 return Boolean(m.matchId && m.matchId !== 'unknown' && !String(m.matchId).startsWith('event'));
             });
             const items = labelsOnly
@@ -292,17 +257,10 @@ Example: { "game": "all", "limitPerGame": 10 }`,
                     label: m.label,
                     startTime: m.startTime,
                 }))
-                // Tennis has players, not teams: rename team1/team2 -> player1/player2
-                // at this boundary only. Every other game is untouched.
                 : normalized.map((m) => presentSides(m, m.game));
             if (game === 'ufc') {
                 const health = asRecord(meta?.health) ?? asRecord(payload?.health);
                 const events = Array.isArray(payload?.events) ? payload.events : [];
-                // One decision point. This used to short-circuit on the API's own
-                // emptyReason and only fall back to inferUfcEmptyReason when the API
-                // said nothing, so the idle-day rule inside it never ran: the API
-                // blames the worker on heartbeat lag alone and an empty Thursday came
-                // back as worker_stale. Hand the hint in and let the function weigh it.
                 const upstreamReason = pickString(meta?.emptyReason, health?.emptyReason);
                 const emptyReason = normalized.length === 0
                     ? inferUfcEmptyReason(events, { ...(health ?? {}), ...(upstreamReason ? { emptyReason: upstreamReason } : {}) }, normalized.length)
@@ -325,12 +283,6 @@ Example: { "game": "all", "limitPerGame": 10 }`,
                     : undefined;
                 const supervisor = normalized.length === 0 && events.length ? slimUfcSupervisorEvents(events) : undefined;
                 const nextCard = normalized.length === 0 ? slimUfcNextCard(payload) : undefined;
-                // A one-word answer to "is anything wrong?". health{} is the worker's
-                // raw view and on an idle day it reads ok:false / workerAlive:false,
-                // which looks broken. state says what the board means: idle (nothing
-                // on, nothing due), live, stale (a hot card with a dead feed), or
-                // degraded. nextEvent tells an idle board what comes next, fetched
-                // only when the board is empty so a live night pays nothing for it.
                 const state = normalized.length > 0 ? 'live'
                     : emptyReason === 'worker_stale' || emptyReason === 'worker_down_inferred' ? 'stale'
                         : emptyReason === 'event_degraded' ? 'degraded'
@@ -371,7 +323,6 @@ Example: { "game": "all", "limitPerGame": 10 }`,
             });
         }
         const totalLive = sections.reduce((sum, s) => sum + (s.ok ? s.count : 0), 0);
-        // Top-level note when single-game UFC empty so agents don't need deep section walk.
         const ufcSection = sections.find((s) => s.game === 'ufc');
         const dataNote = games.length === 1 && games[0] === 'ufc' && ufcSection && ufcSection.count === 0
             ? ufcSection.note
@@ -396,24 +347,24 @@ Example: { "game": "all", "limitPerGame": 10 }`,
 };
 export const upcomingSchedule = {
     name: 'upcoming_schedule',
-    description: `Upcoming matches/events for one game, with game-specific filters.
-
-When to use:
-- "What's on this week?"
-- Calendar UI; team next matches
-
-Prefer over: live_matches for not-yet-started fixtures.
-
-Do not use when: only in-progress matches needed → live_matches.
-
-Filter support (unsupported params are ignored with meta.warnings — do not assume filtering worked):
-- lol: hours, team (slug), league (slug)
-- cs2: team, from, to (ISO); hours not applied upstream
-- cod: team, tournamentId
-- dota2: limit/cursor primarily; team may be client-filtered where data allows
-- ufc: hours / from / to applied client-side after bout expansion (API has no hours); event shells labeled by event name; bouts use fighters[] corners
-
-Parallel-safe: yes. Upstream cost: 1–2.
+    description: `Upcoming matches/events for one game, with game-specific filters.
+
+When to use:
+- "What's on this week?"
+- Calendar UI; team next matches
+
+Prefer over: live_matches for not-yet-started fixtures.
+
+Do not use when: only in-progress matches needed → live_matches.
+
+Filter support (unsupported params are ignored with meta.warnings — do not assume filtering worked):
+- lol: hours, team (slug), league (slug)
+- cs2: team, from, to (ISO); hours not applied upstream
+- cod: team, tournamentId
+- dota2: limit/cursor primarily; team may be client-filtered where data allows
+- ufc: hours / from / to applied client-side after bout expansion (API has no hours); event shells labeled by event name; bouts use fighters[] corners
+
+Parallel-safe: yes. Upstream cost: 1–2.
 Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
     inputSchema: {
         type: 'object',
@@ -466,19 +417,10 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
             warnings.push(`Ignored filter "${param}": ${reason}`);
         };
         let path = '';
-        // Set when this tool, not the API, is responsible for the team filter. It
-        // also moves paging client-side, because an upstream offset would be
-        // counted against rows we are about to discard.
         let clientTeamFilter = false;
-        // Set when this tool, not the upstream, is responsible for paging.
         let clientDatePaging = false;
         let query = { limit, offset };
         lolBranch: if (game === 'lol') {
-            // from/to means a date WINDOW, which /lol/schedule/upcoming cannot serve:
-            // it only knows `hours` forward from now, so asking for last month
-            // silently returned next week's fixtures with an "ignored filter"
-            // warning. /lol/schedule does accept from/to, so route there instead and
-            // let callers list completed matches.
             if (from || to) {
                 path = '/lol/schedule';
                 clientDatePaging = true;
@@ -496,17 +438,8 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
                 break lolBranch;
             }
             path = '/lol/schedule/upcoming';
-            // The upstream accepts teamSlug but does not apply it: asking for t1
-            // returned Dplus KIA, Team WE and NightBirds. That is a silently wrong
-            // answer, which is worse than an error, so the filter is enforced below.
-            // Filtering client-side means the upstream offset would be counted
-            // against unfiltered rows, so when a team is named we over-fetch and page
-            // here instead.
             if (team)
                 clientTeamFilter = true;
-            // The upstream accepts `offset` and ignores it, so page two came back
-            // byte for byte identical to page one while the cursor advanced in the
-            // metadata. Over-fetch and slice here instead of trusting it.
             clientDatePaging = true;
             query = {
                 hours: String(hours),
@@ -571,13 +504,11 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
         }
         else if (game === 'ufc') {
             path = '/ufc/events/upcoming';
-            // Request more events than limit so client-side hours filter still has a card pool.
             query = {
                 limit: Math.min(50, Math.max(limit * 3, limit)),
                 page: Math.floor(offset / limit) + 1,
                 includeBouts: true,
             };
-            // hours / from / to applied client-side after expand (below) — do not warn as ignored.
             if (team)
                 noteIgnored('team', 'UFC uses fighter filters via resolve/event_card, not team on schedule');
             if (league)
@@ -586,8 +517,6 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
                 noteIgnored('tournamentId', 'pass event slug via event_card instead');
         }
         else if (game === 'tennis') {
-            // Scheduled fixtures for ~3 days out; ids are stable across
-            // upcoming -> live -> finished (same s365_{gid} id-space).
             path = '/tennis/matches/upcoming';
             query = { limit: Math.min(500, Math.max(limit, 1)) };
             if (league)
@@ -596,7 +525,6 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
                 noteIgnored('tournamentId', 'tennis fixtures have no tournamentId filter');
             if (team)
                 noteIgnored('team', 'tennis fixtures have no team filter; match player names client-side');
-            // hours / from / to applied client-side after fetch (below) — not warned as ignored.
         }
         const res = await fetchJson(ctx, path, { query });
         if (!res.ok) {
@@ -613,7 +541,6 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
             });
         }
         let rows = extractRows(res.data);
-        // UFC events → expand to bout rows (fighters[] shape) so labels are not "? vs ?"
         if (game === 'ufc') {
             const expanded = [];
             for (const event of rows) {
@@ -636,7 +563,6 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
                     }
                 }
                 else {
-                    // Keep event shell as a schedule card with a real label (not fighter matchup)
                     expanded.push({
                         id: eventId ?? eventSlug,
                         matchId: eventId ?? eventSlug,
@@ -652,7 +578,6 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
                 }
             }
             rows = expanded;
-            // Client-side hours / from / to window (API list has no hours param)
             const now = Date.now();
             const fromMs = from ? Date.parse(from) : now;
             const toMs = to
@@ -666,7 +591,7 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
                     const r = asRecord(row) ?? {};
                     const ts = pickString(r.startTime, r.date, r.startsAt, r.scheduledAt);
                     if (!ts)
-                        return true; // keep undated rows rather than drop whole card
+                        return true;
                     const t = Date.parse(ts);
                     if (!Number.isFinite(t))
                         return true;
@@ -677,7 +602,6 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
                 }
             }
         }
-        // Tennis: client-side hours / from / to window (fixtures list has no time params)
         if (game === 'tennis' && (args.hours !== undefined || from || to)) {
             const now = Date.now();
             const fromMs = from ? Date.parse(from) : now;
@@ -688,7 +612,7 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
                     const r = asRecord(row) ?? {};
                     const ts = pickString(r.startTime, r.start_time, r.startsAt);
                     if (!ts)
-                        return true; // keep undated rows rather than drop them
+                        return true;
                     const t = Date.parse(ts);
                     if (!Number.isFinite(t))
                         return true;
@@ -699,16 +623,10 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
                 }
             }
         }
-        // Client-side team filter when API ignored it
         let beforeTeamFilter = rows.length;
         if (team && (game === 'dota2' || game === 'cs2' || clientTeamFilter)) {
             beforeTeamFilter = rows.length;
             const t = team.toLowerCase();
-            // Exact identity first. A joined-substring match made "t1" hit "T1
-            // Esports Academy", so asking for T1 returned the academy's fixtures --
-            // a different team, quietly. Substring is still useful for partial names
-            // ("vitality"), so it stays as a fallback only when nothing matched
-            // exactly.
             const sides = (row) => {
                 const m = normalizeMatch(game, row, 'upcoming');
                 return [m.team1, m.team2];
@@ -718,11 +636,6 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
                 rows = exact;
             }
             else if (t.length <= 4) {
-                // A short term is an identifier, not a search phrase, so it is exact or
-                // nothing. T1 had no fixture in the window and the substring fallback
-                // answered with "T1 Esports Academy" (slugs t1a and t1-challengers) --
-                // a different team, presented as if it were the one asked for. An empty
-                // list is the correct answer here.
                 rows = [];
             }
             else {
@@ -738,8 +651,6 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
         const windowed = pageHere
             ? rows.slice(Number(offset), Number(offset) + Number(limit))
             : rows.slice(0, limit);
-        // A date window can contain finished matches, so do not force "upcoming"
-        // onto rows that already carry a real state.
         const items = windowed.map((row) => from || to ? normalizeMatch(game, row) : normalizeMatch(game, row, 'upcoming'));
         const obj = asRecord(res.data);
         const total = typeof obj?.total === 'number' ? obj.total : null;
@@ -761,8 +672,6 @@ Example: { "game": "lol", "hours": 72, "team": "t1", "limit": 20 }`,
                 nextCursor: hasMore ? encodeCursor({ offset: offset + limit }) : null,
                 prevCursor: offset > 0 ? encodeCursor({ offset: Math.max(0, offset - limit) }) : null,
             },
-            // Tennis has players, not teams: rename team1/team2 -> player1/player2
-            // at this boundary only. Every other game is untouched.
             data: { items: items.map((m) => presentSides(m, game)) },
         });
     },