@roberttlange/agentlens 0.2.2 → 0.3.0

package/node_modules/@agentlens/server/dist/activity.js

@@ -13,6 +13,8 @@ const MAX_WEEK_DAY_COUNT = 366;
 const DEFAULT_WEEK_SLOT_MINUTES = 30;
 const DEFAULT_WEEK_HOUR_START_LOCAL = 0;
 const DEFAULT_WEEK_HOUR_END_LOCAL = 24;
+const DEFAULT_YEAR_SLOT_MINUTES = 30;
+const DEFAULT_YEAR_HOUR_START_LOCAL = 7;
 const MIN_TZ_OFFSET_MINUTES = -14 * 60;
 const MAX_TZ_OFFSET_MINUTES = 14 * 60;
 const DAY_MS = 24 * 60 * 60 * 1000;
@@ -106,6 +108,184 @@ function createEmptyEventKindCounts() {
         meta: 0,
     };
 }
+function createUsageSummaryRow(agent) {
+    return {
+        agent,
+        sessionHours: 0,
+        sessionSharePct: 0,
+        uniqueSessions: 0,
+        activeSlots: 0,
+        activeDays: 0,
+        peakConcurrentSessions: 0,
+        inputTokens: 0,
+        cacheTokens: 0,
+        outputTokens: 0,
+    };
+}
+function createUsageAccumulator() {
+    const usageByAgent = new Map();
+    const uniqueSessionIdsByAgent = new Map();
+    for (const agent of AGENT_KIND_KEYS) {
+        usageByAgent.set(agent, createUsageSummaryRow(agent));
+        uniqueSessionIdsByAgent.set(agent, new Set());
+    }
+    return {
+        usageByAgent,
+        uniqueSessionIdsByAgent,
+        totalUniqueSessionIds: new Set(),
+        peakAllAgentConcurrency: 0,
+    };
+}
+function createEmptyHeatmapMetricValues() {
+    return {
+        sessions: 0,
+        output_tokens: 0,
+        total_cost_usd: 0,
+    };
+}
+function sanitizeTokenValue(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+function sanitizeCostValue(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+function normalizeHexColor(value) {
+    const trimmed = value.trim();
+    const shortMatch = /^#([0-9a-fA-F]{3})$/.exec(trimmed);
+    if (shortMatch) {
+        const digits = shortMatch[1] ?? "";
+        return `#${digits
+            .split("")
+            .map((digit) => `${digit}${digit}`)
+            .join("")
+            .toLowerCase()}`;
+    }
+    const longMatch = /^#([0-9a-fA-F]{6})$/.exec(trimmed);
+    if (longMatch) {
+        return `#${(longMatch[1] ?? "").toLowerCase()}`;
+    }
+    return "#dc2626";
+}
+function hexChannel(color, start) {
+    return Number.parseInt(color.slice(start, start + 2), 16);
+}
+function toHexChannel(value) {
+    return Math.round(clamp(value, 0, 255))
+        .toString(16)
+        .padStart(2, "0");
+}
+function mixHexColor(color, colorWeight) {
+    const normalized = normalizeHexColor(color);
+    const baseWeight = clamp(colorWeight, 0, 1);
+    const whiteWeight = 1 - baseWeight;
+    const red = hexChannel(normalized, 1) * baseWeight + 255 * whiteWeight;
+    const green = hexChannel(normalized, 3) * baseWeight + 255 * whiteWeight;
+    const blue = hexChannel(normalized, 5) * baseWeight + 255 * whiteWeight;
+    return `#${toHexChannel(red)}${toHexChannel(green)}${toHexChannel(blue)}`;
+}
+function buildHeatmapPresentation(metric, color) {
+    const normalizedColor = normalizeHexColor(color);
+    return {
+        metric,
+        color: normalizedColor,
+        palette: [
+            "#ffffff",
+            mixHexColor(normalizedColor, 0.18),
+            mixHexColor(normalizedColor, 0.38),
+            mixHexColor(normalizedColor, 0.62),
+            mixHexColor(normalizedColor, 0.82),
+        ],
+    };
+}
+function sumHeatmapMetricForBins(bins, metric) {
+    return bins.reduce((sum, bin) => {
+        if (metric === "sessions")
+            return sum + (bin.heatmapValues?.sessions ?? bin.activeSessionCount);
+        if (metric === "output_tokens")
+            return sum + (bin.heatmapValues?.output_tokens ?? 0);
+        return sum + (bin.heatmapValues?.total_cost_usd ?? 0);
+    }, 0);
+}
+function totalEventCountForBins(bins) {
+    return bins.reduce((sum, bin) => sum + bin.eventCount, 0);
+}
+function finalizeUsageSummary(accumulator) {
+    for (const agent of AGENT_KIND_KEYS) {
+        const row = accumulator.usageByAgent.get(agent);
+        const sessions = accumulator.uniqueSessionIdsByAgent.get(agent);
+        if (!row || !sessions)
+            continue;
+        row.uniqueSessions = sessions.size;
+    }
+    const totalSessionHours = AGENT_KIND_KEYS.reduce((sum, agent) => sum + (accumulator.usageByAgent.get(agent)?.sessionHours ?? 0), 0);
+    const rows = AGENT_KIND_KEYS.map((agent) => accumulator.usageByAgent.get(agent))
+        .filter((row) => row.sessionHours > 0 || row.uniqueSessions > 0 || row.activeSlots > 0)
+        .map((row) => ({
+        ...row,
+        sessionSharePct: totalSessionHours > 0 ? (row.sessionHours / totalSessionHours) * 100 : 0,
+    }))
+        .sort((left, right) => right.sessionHours - left.sessionHours || right.uniqueSessions - left.uniqueSessions || left.agent.localeCompare(right.agent));
+    return {
+        rows,
+        totals: {
+            totalUniqueSessions: accumulator.totalUniqueSessionIds.size,
+            totalSessionHours,
+            peakAllAgentConcurrency: accumulator.peakAllAgentConcurrency,
+            mostUsedAgent: rows[0]?.agent ?? null,
+        },
+    };
+}
+function applyUsagePointToRow(row, point) {
+    row.inputTokens += sanitizeTokenValue(point.inputTokens);
+    row.cacheTokens += sanitizeTokenValue(point.cachedReadTokens) + sanitizeTokenValue(point.cachedCreateTokens);
+    row.outputTokens += sanitizeTokenValue(point.outputTokens);
+}
+function buildWeeklyUsageSummaryFromDays(traceIndex, days) {
+    const accumulator = createUsageAccumulator();
+    const summaryById = new Map(traceIndex.getSummaries().map((summary) => [summary.id, summary]));
+    for (const day of days) {
+        const activeAgentsToday = new Set();
+        for (const bin of day.bins) {
+            accumulator.peakAllAgentConcurrency = Math.max(accumulator.peakAllAgentConcurrency, bin.activeSessionCount);
+            const binHours = Math.max(0, bin.endMs - bin.startMs) / 3_600_000;
+            for (const agent of AGENT_KIND_KEYS) {
+                const agentSessionsInBin = bin.activeByAgent[agent] ?? 0;
+                if (agentSessionsInBin <= 0)
+                    continue;
+                const row = accumulator.usageByAgent.get(agent);
+                if (!row)
+                    continue;
+                row.sessionHours += agentSessionsInBin * binHours;
+                row.activeSlots += 1;
+                row.peakConcurrentSessions = Math.max(row.peakConcurrentSessions, agentSessionsInBin);
+                activeAgentsToday.add(agent);
+            }
+            for (const traceId of bin.activeTraceIds) {
+                accumulator.totalUniqueSessionIds.add(traceId);
+                const normalizedAgent = summaryById.get(traceId)?.agent ?? "unknown";
+                accumulator.uniqueSessionIdsByAgent.get(normalizedAgent)?.add(traceId);
+            }
+        }
+        for (const agent of activeAgentsToday) {
+            const row = accumulator.usageByAgent.get(agent);
+            if (!row)
+                continue;
+            row.activeDays += 1;
+        }
+    }
+    for (const summary of summaryById.values()) {
+        const usageArtifacts = traceIndex.getSessionUsageArtifacts(summary.id);
+        const row = accumulator.usageByAgent.get(summary.agent);
+        if (!row)
+            continue;
+        for (const point of usageArtifacts.usagePoints) {
+            if (!days.some((day) => point.timestampMs >= day.windowStartMs && point.timestampMs < day.windowEndMs))
+                continue;
+            applyUsagePointToRow(row, point);
+        }
+    }
+    return finalizeUsageSummary(accumulator);
+}
 function resolveSessionSpan(summary) {
     const baseStart = summary.firstEventTs ?? summary.lastEventTs ?? summary.mtimeMs;
     const baseEnd = summary.lastEventTs ?? summary.mtimeMs;
@@ -113,35 +293,6 @@ function resolveSessionSpan(summary) {
     const endMs = Math.max(baseStart, baseEnd);
     return { startMs, endMs };
 }
-function collectTimestampMs(events) {
-    const timestamps = [];
-    for (const event of events) {
-        const timestampMs = event.timestampMs;
-        if (timestampMs === null || !Number.isFinite(timestampMs) || timestampMs <= 0)
-            continue;
-        timestamps.push(timestampMs);
-    }
-    timestamps.sort((left, right) => left - right);
-    return timestamps;
-}
-function buildActiveSegmentsFromEventTimestamps(eventTimestamps) {
-    if (eventTimestamps.length === 0)
-        return [];
-    const segments = [];
-    let segmentStartMs = eventTimestamps[0] ?? 0;
-    let previousTsMs = segmentStartMs;
-    for (let index = 1; index < eventTimestamps.length; index += 1) {
-        const nextTsMs = eventTimestamps[index] ?? previousTsMs;
-        const gapMs = Math.max(0, nextTsMs - previousTsMs);
-        if (gapMs > ACTIVE_IDLE_GAP_MS) {
-            segments.push({ startMs: segmentStartMs, endMs: previousTsMs });
-            segmentStartMs = nextTsMs;
-        }
-        previousTsMs = nextTsMs;
-    }
-    segments.push({ startMs: segmentStartMs, endMs: previousTsMs });
-    return segments;
-}
 function pickDominantAgent(counts) {
     let dominant = "none";
     let dominantCount = 0;
@@ -208,7 +359,7 @@ function applyBreakMarkers(bins, breakMinutes) {
     }
     markRunIfBreak(runStart, bins.length);
 }
-function buildWindowActivity(traceIndex, windowStartMs, windowEndMs, binMinutes, breakMinutes) {
+function computeWindowActivity(traceIndex, windowStartMs, windowEndMs, binMinutes, breakMinutes, heatmapMetric) {
     const binMs = binMinutes * 60_000;
     const totalWindowMs = Math.max(0, windowEndMs - windowStartMs);
     const binCount = totalWindowMs <= 0 ? 0 : Math.ceil(totalWindowMs / binMs);
@@ -220,6 +371,8 @@ function buildWindowActivity(traceIndex, windowStartMs, windowEndMs, binMinutes,
             startMs,
             endMs,
             activeSessionCount: 0,
+            heatmapValue: 0,
+            heatmapValues: createEmptyHeatmapMetricValues(),
             activeTraceIds: [],
             primaryTraceId: "",
             activeByAgent: createEmptyAgentCounts(),
@@ -244,8 +397,8 @@ function buildWindowActivity(traceIndex, windowStartMs, windowEndMs, binMinutes,
     if (binCount > 0) {
         for (const summary of inWindowSummaries) {
             const detail = traceIndex.getSessionDetail(summary.id);
-            const eventTimestamps = collectTimestampMs(detail.events);
-            const activeSegments = buildActiveSegmentsFromEventTimestamps(eventTimestamps);
+            const activityArtifacts = traceIndex.getSessionActivityArtifacts(summary.id);
+            const activeSegments = activityArtifacts.activeSegments;
             for (const segment of activeSegments) {
                 if (segment.endMs < windowStartMs || segment.startMs >= windowEndMs)
                     continue;
@@ -263,6 +416,7 @@ function buildWindowActivity(traceIndex, windowStartMs, windowEndMs, binMinutes,
                         bin.activeTraceIds.push(summary.id);
                         bin.activeSessionCount += 1;
                         bin.activeByAgent[summary.agent] += 1;
+                        bin.heatmapValues ??= createEmptyHeatmapMetricValues();
                         contributingSessionIds.add(summary.id);
                     }
                 }
@@ -278,6 +432,18 @@ function buildWindowActivity(traceIndex, windowStartMs, windowEndMs, binMinutes,
                 bin.eventCount += 1;
                 bin.eventKindCounts[event.eventKind] += 1;
             }
+            const usageArtifacts = traceIndex.getSessionUsageArtifacts(summary.id);
+            for (const point of usageArtifacts.usagePoints) {
+                if (point.timestampMs < windowStartMs || point.timestampMs >= windowEndMs)
+                    continue;
+                const binIndex = computeBinIndex(windowStartMs, binMs, binCount, point.timestampMs);
+                const bin = bins[binIndex];
+                if (!bin)
+                    continue;
+                bin.heatmapValues ??= createEmptyHeatmapMetricValues();
+                bin.heatmapValues.output_tokens += sanitizeTokenValue(point.outputTokens);
+                bin.heatmapValues.total_cost_usd += sanitizeCostValue(point.costUsd);
+            }
         }
     }
     let peakConcurrentSessions = 0;
@@ -293,6 +459,17 @@ function buildWindowActivity(traceIndex, windowStartMs, windowEndMs, binMinutes,
             });
             bin.primaryTraceId = bin.activeTraceIds[0] ?? "";
         }
+        if (heatmapMetric === "sessions") {
+            bin.heatmapValue = bin.activeSessionCount;
+        }
+        bin.heatmapValues ??= createEmptyHeatmapMetricValues();
+        bin.heatmapValues.sessions = bin.activeSessionCount;
+        bin.heatmapValue =
+            heatmapMetric === "sessions"
+                ? bin.heatmapValues.sessions
+                : heatmapMetric === "output_tokens"
+                    ? bin.heatmapValues.output_tokens
+                    : bin.heatmapValues.total_cost_usd;
         bin.dominantAgent = pickDominantAgent(bin.activeByAgent);
         bin.dominantEventKind = pickDominantEventKind(bin.eventKindCounts);
         if (bin.activeSessionCount > peakConcurrentSessions) {
@@ -308,6 +485,65 @@ function buildWindowActivity(traceIndex, windowStartMs, windowEndMs, binMinutes,
         peakConcurrentAtMs,
     };
 }
+function buildWindowActivity(traceIndex, windowStartMs, windowEndMs, binMinutes, breakMinutes, options, heatmapMetric) {
+    if (!options.cache || options.cacheVersion === undefined) {
+        return computeWindowActivity(traceIndex, windowStartMs, windowEndMs, binMinutes, breakMinutes, heatmapMetric);
+    }
+    return options.cache.getOrBuildWindow(options.cacheVersion, options.nowMs, {
+        windowStartMs,
+        windowEndMs,
+        binMinutes,
+        breakMinutes,
+        heatmapMetric,
+    }, () => computeWindowActivity(traceIndex, windowStartMs, windowEndMs, binMinutes, breakMinutes, heatmapMetric));
+}
+export function resolveAgentActivityDayWindow(options = {}) {
+    const nowMs = typeof options.nowMs === "number" && Number.isFinite(options.nowMs) ? options.nowMs : Date.now();
+    const requestedTzOffset = validateInt(options.tzOffsetMinutes, "tz_offset_min");
+    const tzOffsetMinutes = clamp(requestedTzOffset ?? new Date(nowMs).getTimezoneOffset(), MIN_TZ_OFFSET_MINUTES, MAX_TZ_OFFSET_MINUTES);
+    const requestedDateLocal = options.dateLocal?.trim() ?? "";
+    const dateLocal = requestedDateLocal || toLocalDateString(nowMs, tzOffsetMinutes);
+    parseDateLocal(dateLocal);
+    const dayStartMs = windowStartMsForDateLocal(dateLocal, tzOffsetMinutes);
+    return {
+        windowStartMs: dayStartMs + DEFAULT_DAY_HOUR_START_LOCAL * 60 * 60_000,
+    };
+}
+export function resolveAgentActivityWeekWindow(options = {}) {
+    const nowMs = typeof options.nowMs === "number" && Number.isFinite(options.nowMs) ? options.nowMs : Date.now();
+    const requestedTzOffset = validateInt(options.tzOffsetMinutes, "tz_offset_min");
+    const tzOffsetMinutes = clamp(requestedTzOffset ?? new Date(nowMs).getTimezoneOffset(), MIN_TZ_OFFSET_MINUTES, MAX_TZ_OFFSET_MINUTES);
+    const requestedEndDateLocal = options.endDateLocal?.trim() ?? "";
+    const endDateLocal = requestedEndDateLocal || toLocalDateString(nowMs, tzOffsetMinutes);
+    parseDateLocal(endDateLocal);
+    const requestedDayCount = validateInt(options.dayCount, "day_count");
+    const dayCount = clamp(requestedDayCount ?? DEFAULT_WEEK_DAY_COUNT, MIN_WEEK_DAY_COUNT, MAX_WEEK_DAY_COUNT);
+    const startDateLocal = shiftDateLocal(endDateLocal, -(dayCount - 1));
+    const requestedHourStart = validateInt(options.hourStartLocal, "hour_start");
+    const hourStartLocal = clamp(requestedHourStart ?? DEFAULT_WEEK_HOUR_START_LOCAL, 0, 23);
+    const dayStartMs = windowStartMsForDateLocal(startDateLocal, tzOffsetMinutes);
+    return {
+        windowStartMs: dayStartMs + hourStartLocal * 60 * 60_000,
+    };
+}
+export function resolveAgentActivityYearWindow(options = {}) {
+    const nowMs = typeof options.nowMs === "number" && Number.isFinite(options.nowMs) ? options.nowMs : Date.now();
+    const requestedTzOffset = validateInt(options.tzOffsetMinutes, "tz_offset_min");
+    const tzOffsetMinutes = clamp(requestedTzOffset ?? new Date(nowMs).getTimezoneOffset(), MIN_TZ_OFFSET_MINUTES, MAX_TZ_OFFSET_MINUTES);
+    const requestedEndDateLocal = options.endDateLocal?.trim() ?? "";
+    const endDateLocal = requestedEndDateLocal || toLocalDateString(nowMs, tzOffsetMinutes);
+    parseDateLocal(endDateLocal);
+    const requestedDayCount = validateInt(options.dayCount, "day_count");
+    const maxDayCount = clamp(requestedDayCount ?? MAX_WEEK_DAY_COUNT, MIN_WEEK_DAY_COUNT, MAX_WEEK_DAY_COUNT);
+    const yearStartDateLocal = `${endDateLocal.slice(0, 4)}-01-01`;
+    const nominalRangeDayCount = Math.floor((windowStartMsForDateLocal(endDateLocal, 0) - windowStartMsForDateLocal(yearStartDateLocal, 0)) / DAY_MS) + 1;
+    const dayCount = clamp(nominalRangeDayCount, MIN_WEEK_DAY_COUNT, Math.min(MAX_WEEK_DAY_COUNT, maxDayCount));
+    const startDateLocal = shiftDateLocal(endDateLocal, -(dayCount - 1));
+    const dayStartMs = windowStartMsForDateLocal(startDateLocal, tzOffsetMinutes);
+    return {
+        windowStartMs: dayStartMs + DEFAULT_YEAR_HOUR_START_LOCAL * 60 * 60_000,
+    };
+}
 export function buildAgentActivityDay(traceIndex, options = {}) {
     const nowMs = typeof options.nowMs === "number" && Number.isFinite(options.nowMs) ? options.nowMs : Date.now();
     const requestedTzOffset = validateInt(options.tzOffsetMinutes, "tz_offset_min");
@@ -319,12 +555,30 @@ export function buildAgentActivityDay(traceIndex, options = {}) {
     const requestedBreakMinutes = validateInt(options.breakMinutes, "break_min");
     const binMinutes = clamp(requestedBinMinutes ?? DEFAULT_BIN_MINUTES, MIN_BIN_MINUTES, MAX_BIN_MINUTES);
     const breakMinutes = clamp(requestedBreakMinutes ?? DEFAULT_BREAK_MINUTES, MIN_BREAK_MINUTES, MAX_BREAK_MINUTES);
+    if (options.cache && options.cacheVersion !== undefined) {
+        const { cache: _cache, cacheVersion: _cacheVersion, ...uncachedOptions } = options;
+        return options.cache.getOrBuildDay(options.cacheVersion, nowMs, {
+            dateLocal,
+            tzOffsetMinutes,
+            binMinutes,
+            breakMinutes,
+        }, () => buildAgentActivityDay(traceIndex, {
+            ...uncachedOptions,
+            nowMs,
+            dateLocal,
+            tzOffsetMinutes,
+            binMinutes,
+            breakMinutes,
+        }));
+    }
     const dayStartMs = windowStartMsForDateLocal(dateLocal, tzOffsetMinutes);
     const windowStartMs = dayStartMs + DEFAULT_DAY_HOUR_START_LOCAL * 60 * 60_000;
     const windowEndOfDayMs = windowStartMs + DAY_MS;
     const todayLocal = toLocalDateString(nowMs, tzOffsetMinutes);
     const windowEndMs = dateLocal === todayLocal ? Math.max(windowStartMs, Math.min(windowEndOfDayMs, nowMs)) : windowEndOfDayMs;
-    const windowActivity = buildWindowActivity(traceIndex, windowStartMs, windowEndMs, binMinutes, breakMinutes);
+    const windowActivity = buildWindowActivity(traceIndex, windowStartMs, windowEndMs, binMinutes, breakMinutes, options.cache && options.cacheVersion !== undefined
+        ? { cache: options.cache, cacheVersion: options.cacheVersion, nowMs }
+        : { nowMs }, "sessions");
     return {
         dateLocal,
         tzOffsetMinutes,
@@ -335,6 +589,7 @@ export function buildAgentActivityDay(traceIndex, options = {}) {
         totalSessionsInWindow: windowActivity.totalSessionsInWindow,
         peakConcurrentSessions: windowActivity.peakConcurrentSessions,
         peakConcurrentAtMs: windowActivity.peakConcurrentAtMs,
+        totalEventCount: totalEventCountForBins(windowActivity.bins),
         bins: windowActivity.bins,
     };
 }
@@ -345,6 +600,8 @@ export function buildAgentActivityWeek(traceIndex, options = {}) {
     const requestedEndDateLocal = options.endDateLocal?.trim() ?? "";
     const endDateLocal = requestedEndDateLocal || toLocalDateString(nowMs, tzOffsetMinutes);
     parseDateLocal(endDateLocal);
+    const heatmapMetric = options.heatmapMetric ?? traceIndex.getConfig().activityHeatmap.metric;
+    const heatmapColor = options.heatmapColor ?? traceIndex.getConfig().activityHeatmap.color;
     const requestedDayCount = validateInt(options.dayCount, "day_count");
     const dayCount = clamp(requestedDayCount ?? DEFAULT_WEEK_DAY_COUNT, MIN_WEEK_DAY_COUNT, MAX_WEEK_DAY_COUNT);
     const startDateLocal = shiftDateLocal(endDateLocal, -(dayCount - 1));
@@ -361,6 +618,30 @@ export function buildAgentActivityWeek(traceIndex, options = {}) {
     if (slotMinutes > windowMinutes) {
         throw new Error("slot_min too large for hour window");
     }
+    if (options.cache && options.cacheVersion !== undefined) {
+        const { cache: _cache, cacheVersion: _cacheVersion, ...uncachedOptions } = options;
+        return options.cache.getOrBuildWeek(options.cacheVersion, nowMs, {
+            endDateLocal,
+            tzOffsetMinutes,
+            dayCount,
+            slotMinutes,
+            hourStartLocal,
+            hourEndLocal,
+            heatmapMetric,
+            heatmapColor,
+        }, () => buildAgentActivityWeek(traceIndex, {
+            ...uncachedOptions,
+            nowMs,
+            endDateLocal,
+            tzOffsetMinutes,
+            dayCount,
+            slotMinutes,
+            hourStartLocal,
+            hourEndLocal,
+            heatmapMetric,
+            heatmapColor,
+        }));
+    }
     const windowDurationMs = windowMinutes * 60_000;
     const days = [];
     const todayLocal = toLocalDateString(nowMs, tzOffsetMinutes);
@@ -372,18 +653,30 @@ export function buildAgentActivityWeek(traceIndex, options = {}) {
         const windowEndMs = dateLocal === todayLocal
             ? Math.max(windowStartMs, Math.min(nominalWindowEndMs, nowMs))
             : nominalWindowEndMs;
-        const windowActivity = buildWindowActivity(traceIndex, windowStartMs, windowEndMs, slotMinutes, DEFAULT_BREAK_MINUTES);
+        const windowActivity = buildWindowActivity(traceIndex, windowStartMs, windowEndMs, slotMinutes, DEFAULT_BREAK_MINUTES, options.cache && options.cacheVersion !== undefined
+            ? { cache: options.cache, cacheVersion: options.cacheVersion, nowMs }
+            : { nowMs }, heatmapMetric);
         days.push({
             dateLocal,
             windowStartMs,
             windowEndMs,
             totalSessionsInWindow: windowActivity.totalSessionsInWindow,
+            heatmapValue: heatmapMetric === "sessions"
+                ? windowActivity.totalSessionsInWindow
+                : sumHeatmapMetricForBins(windowActivity.bins, heatmapMetric),
+            heatmapValues: {
+                sessions: windowActivity.totalSessionsInWindow,
+                output_tokens: sumHeatmapMetricForBins(windowActivity.bins, "output_tokens"),
+                total_cost_usd: sumHeatmapMetricForBins(windowActivity.bins, "total_cost_usd"),
+            },
             peakConcurrentSessions: windowActivity.peakConcurrentSessions,
             peakConcurrentAtMs: windowActivity.peakConcurrentAtMs,
+            totalEventCount: totalEventCountForBins(windowActivity.bins),
             bins: windowActivity.bins,
         });
     }
     return {
+        presentation: buildHeatmapPresentation(heatmapMetric, heatmapColor),
         tzOffsetMinutes,
         dayCount,
         slotMinutes,
@@ -392,6 +685,211 @@ export function buildAgentActivityWeek(traceIndex, options = {}) {
         startDateLocal,
         endDateLocal,
         days,
+        usageSummary: buildWeeklyUsageSummaryFromDays(traceIndex, days),
+    };
+}
+export function buildAgentActivityYear(traceIndex, options = {}) {
+    const nowMs = typeof options.nowMs === "number" && Number.isFinite(options.nowMs) ? options.nowMs : Date.now();
+    const requestedTzOffset = validateInt(options.tzOffsetMinutes, "tz_offset_min");
+    const tzOffsetMinutes = clamp(requestedTzOffset ?? new Date(nowMs).getTimezoneOffset(), MIN_TZ_OFFSET_MINUTES, MAX_TZ_OFFSET_MINUTES);
+    const requestedEndDateLocal = options.endDateLocal?.trim() ?? "";
+    const endDateLocal = requestedEndDateLocal || toLocalDateString(nowMs, tzOffsetMinutes);
+    parseDateLocal(endDateLocal);
+    const heatmapMetric = options.heatmapMetric ?? traceIndex.getConfig().activityHeatmap.metric;
+    const heatmapColor = options.heatmapColor ?? traceIndex.getConfig().activityHeatmap.color;
+    const requestedDayCount = validateInt(options.dayCount, "day_count");
+    const maxDayCount = clamp(requestedDayCount ?? MAX_WEEK_DAY_COUNT, MIN_WEEK_DAY_COUNT, MAX_WEEK_DAY_COUNT);
+    const yearStartDateLocal = `${endDateLocal.slice(0, 4)}-01-01`;
+    const todayLocal = toLocalDateString(nowMs, tzOffsetMinutes);
+    const nominalRangeDayCount = Math.floor((windowStartMsForDateLocal(endDateLocal, 0) - windowStartMsForDateLocal(yearStartDateLocal, 0)) / DAY_MS) + 1;
+    const dayCount = clamp(nominalRangeDayCount, MIN_WEEK_DAY_COUNT, Math.min(MAX_WEEK_DAY_COUNT, maxDayCount));
+    const provisionalStartDateLocal = shiftDateLocal(endDateLocal, -(dayCount - 1));
+    const summaryById = new Map(traceIndex.getSummaries().map((summary) => [summary.id, summary]));
+    let earliestActiveDateLocal = null;
+    for (const summary of summaryById.values()) {
+        const activeAtMs = Math.max(summary.firstEventTs ?? 0, 1);
+        if (activeAtMs <= 0)
+            continue;
+        const activeDateLocal = toLocalDateString(activeAtMs, tzOffsetMinutes);
+        if (activeDateLocal < provisionalStartDateLocal || activeDateLocal > endDateLocal)
+            continue;
+        if (earliestActiveDateLocal === null || activeDateLocal < earliestActiveDateLocal) {
+            earliestActiveDateLocal = activeDateLocal;
+        }
+    }
+    const startDateLocal = earliestActiveDateLocal ?? provisionalStartDateLocal;
+    const effectiveDayCount = Math.floor((windowStartMsForDateLocal(endDateLocal, 0) - windowStartMsForDateLocal(startDateLocal, 0)) / DAY_MS) + 1;
+    if (options.cache && options.cacheVersion !== undefined) {
+        const { cache: _cache, cacheVersion: _cacheVersion, ...uncachedOptions } = options;
+        return options.cache.getOrBuildYear(options.cacheVersion, nowMs, {
+            endDateLocal,
+            tzOffsetMinutes,
+            dayCount: effectiveDayCount,
+            heatmapMetric,
+            heatmapColor,
+        }, () => buildAgentActivityYear(traceIndex, {
+            ...uncachedOptions,
+            nowMs,
+            endDateLocal,
+            tzOffsetMinutes,
+            dayCount: effectiveDayCount,
+            heatmapMetric,
+            heatmapColor,
+        }));
+    }
+    const windowDurationMs = computeWeekWindowMinutes(DEFAULT_YEAR_HOUR_START_LOCAL, DEFAULT_YEAR_HOUR_START_LOCAL) * 60_000;
+    const slotMs = DEFAULT_YEAR_SLOT_MINUTES * 60_000;
+    const slotCount = Math.max(1, Math.ceil(windowDurationMs / slotMs));
+    const dayStates = [];
+    for (let offset = 0; offset < effectiveDayCount; offset += 1) {
+        const dateLocal = shiftDateLocal(startDateLocal, offset);
+        const dayStartMs = windowStartMsForDateLocal(dateLocal, tzOffsetMinutes);
+        const windowStartMs = dayStartMs + DEFAULT_YEAR_HOUR_START_LOCAL * 60 * 60_000;
+        const nominalWindowEndMs = windowStartMs + windowDurationMs;
+        const windowEndMs = dateLocal === todayLocal ? Math.max(windowStartMs, Math.min(nominalWindowEndMs, nowMs)) : nominalWindowEndMs;
+        dayStates.push({
+            dateLocal,
+            windowStartMs,
+            windowEndMs,
+            totalSessionIds: new Set(),
+            heatmapValue: 0,
+            heatmapValues: createEmptyHeatmapMetricValues(),
+            totalEventCount: 0,
+            boundaryEvents: [],
+            agentSlotCounts: Array.from({ length: slotCount }, () => createEmptyAgentCounts()),
+        });
+    }
+    const overallStartMs = dayStates[0]?.windowStartMs ?? 0;
+    const overallEndMs = dayStates[dayStates.length - 1]?.windowEndMs ?? overallStartMs;
+    const usageAccumulator = createUsageAccumulator();
+    for (const summary of summaryById.values()) {
+        const span = resolveSessionSpan(summary);
+        if (span.endMs < overallStartMs || span.startMs >= overallEndMs)
+            continue;
+        const activityArtifacts = traceIndex.getSessionActivityArtifacts(summary.id);
+        let summaryContributed = false;
+        for (const timestampMs of activityArtifacts.eventTimestamps) {
+            if (timestampMs < overallStartMs || timestampMs >= overallEndMs)
+                continue;
+            const dayIndex = Math.floor((timestampMs - overallStartMs) / DAY_MS);
+            const dayState = dayStates[dayIndex];
+            if (!dayState)
+                continue;
+            if (timestampMs >= dayState.windowEndMs)
+                continue;
+            dayState.totalEventCount += 1;
+        }
+        for (const segment of activityArtifacts.activeSegments) {
+            if (segment.endMs < overallStartMs || segment.startMs >= overallEndMs)
+                continue;
+            const clampedStartMs = Math.max(segment.startMs, overallStartMs);
+            const clampedEndExclusiveMs = Math.min(segment.endMs + 1, overallEndMs);
+            if (clampedEndExclusiveMs <= clampedStartMs)
+                continue;
+            summaryContributed = true;
+            const startDayIndex = Math.max(0, Math.floor((clampedStartMs - overallStartMs) / DAY_MS));
+            const endDayIndex = Math.max(0, Math.floor((clampedEndExclusiveMs - 1 - overallStartMs) / DAY_MS));
+            for (let dayIndex = startDayIndex; dayIndex <= endDayIndex; dayIndex += 1) {
+                const dayState = dayStates[dayIndex];
+                if (!dayState)
+                    continue;
+                const overlapStartMs = Math.max(clampedStartMs, dayState.windowStartMs);
+                const overlapEndExclusiveMs = Math.min(clampedEndExclusiveMs, dayState.windowEndMs);
+                if (overlapEndExclusiveMs <= overlapStartMs)
+                    continue;
+                dayState.totalSessionIds.add(summary.id);
+                dayState.boundaryEvents.push({ atMs: overlapStartMs, delta: 1 });
+                dayState.boundaryEvents.push({ atMs: overlapEndExclusiveMs, delta: -1 });
+                const startSlotIndex = computeBinIndex(dayState.windowStartMs, slotMs, slotCount, overlapStartMs);
+                const endSlotIndex = computeBinIndex(dayState.windowStartMs, slotMs, slotCount, Math.max(overlapStartMs, overlapEndExclusiveMs - 1));
+                for (let slotIndex = startSlotIndex; slotIndex <= endSlotIndex; slotIndex += 1) {
+                    dayState.agentSlotCounts[slotIndex][summary.agent] += 1;
+                }
+            }
+        }
+        if (!summaryContributed)
+            continue;
+        usageAccumulator.totalUniqueSessionIds.add(summary.id);
+        usageAccumulator.uniqueSessionIdsByAgent.get(summary.agent)?.add(summary.id);
+    }
+    for (const summary of summaryById.values()) {
+        const row = usageAccumulator.usageByAgent.get(summary.agent);
+        if (!row)
+            continue;
+        const usageArtifacts = traceIndex.getSessionUsageArtifacts(summary.id);
+        for (const point of usageArtifacts.usagePoints) {
+            if (point.timestampMs < overallStartMs || point.timestampMs >= overallEndMs)
+                continue;
+            const dayIndex = Math.floor((point.timestampMs - overallStartMs) / DAY_MS);
+            const dayState = dayStates[dayIndex];
+            if (!dayState)
+                continue;
+            if (point.timestampMs < dayState.windowStartMs || point.timestampMs >= dayState.windowEndMs)
+                continue;
+            dayState.heatmapValues.output_tokens += sanitizeTokenValue(point.outputTokens);
+            dayState.heatmapValues.total_cost_usd += sanitizeCostValue(point.costUsd);
+            applyUsagePointToRow(row, point);
+        }
+    }
+    const days = dayStates.map((dayState) => {
+        let peakConcurrentSessions = 0;
+        let peakConcurrentAtMs = null;
+        let concurrentSessions = 0;
+        const sortedBoundaryEvents = [...dayState.boundaryEvents].sort((left, right) => left.atMs - right.atMs || left.delta - right.delta);
+        for (const boundaryEvent of sortedBoundaryEvents) {
+            concurrentSessions += boundaryEvent.delta;
+            if (concurrentSessions > peakConcurrentSessions) {
+                peakConcurrentSessions = concurrentSessions;
+                peakConcurrentAtMs = boundaryEvent.atMs;
+            }
+        }
+        usageAccumulator.peakAllAgentConcurrency = Math.max(usageAccumulator.peakAllAgentConcurrency, peakConcurrentSessions);
+        for (const agent of AGENT_KIND_KEYS) {
+            const row = usageAccumulator.usageByAgent.get(agent);
+            if (!row)
+                continue;
+            let activeToday = false;
+            for (const slotCounts of dayState.agentSlotCounts) {
+                const concurrentAgentSessions = slotCounts[agent] ?? 0;
+                if (concurrentAgentSessions <= 0)
+                    continue;
+                activeToday = true;
+                row.sessionHours += concurrentAgentSessions * (slotMs / 3_600_000);
+                row.activeSlots += 1;
+                row.peakConcurrentSessions = Math.max(row.peakConcurrentSessions, concurrentAgentSessions);
+            }
+            if (activeToday) {
+                row.activeDays += 1;
+            }
+        }
+        return {
+            dateLocal: dayState.dateLocal,
+            windowStartMs: dayState.windowStartMs,
+            windowEndMs: dayState.windowEndMs,
+            totalSessionsInWindow: dayState.totalSessionIds.size,
+            heatmapValue: heatmapMetric === "sessions"
+                ? dayState.totalSessionIds.size
+                : heatmapMetric === "output_tokens"
+                    ? dayState.heatmapValues.output_tokens
+                    : dayState.heatmapValues.total_cost_usd,
+            heatmapValues: {
+                sessions: dayState.totalSessionIds.size,
+                output_tokens: dayState.heatmapValues.output_tokens,
+                total_cost_usd: dayState.heatmapValues.total_cost_usd,
+            },
+            peakConcurrentSessions,
+            peakConcurrentAtMs,
+            totalEventCount: dayState.totalEventCount,
+        };
+    });
+    return {
+        presentation: buildHeatmapPresentation(heatmapMetric, heatmapColor),
+        tzOffsetMinutes,
+        dayCount: effectiveDayCount,
+        startDateLocal,
+        endDateLocal,
+        days,
+        usageSummary: finalizeUsageSummary(usageAccumulator),
     };
 }
 //# sourceMappingURL=activity.js.map