@ericsanchezok/synergy-workbench 0.0.0-stage → 3.1.0

package/dist/stats/canonical.js

@@ -0,0 +1,89 @@
+import { Usage } from "@ericsanchezok/synergy-harness/usage";
+import { RolloutAccounting } from "@ericsanchezok/synergy-harness/session/rollout/accounting";
+import { ExecutionPresentation } from "../execution/presentation.js";
+export var CanonicalStats;
+(function (CanonicalStats) {
+    function projection(accounting) {
+        return {
+            ...RolloutAccounting.project(accounting),
+            cost: RolloutAccounting.knownExpense(accounting),
+            costPresentation: ExecutionPresentation.cost(accounting),
+            accounting,
+        };
+    }
+    async function apply(snapshot) {
+        const usage = await Usage.summary();
+        const days = new Map(snapshot.timeSeries.days.map((day) => [
+            day.day,
+            {
+                ...day,
+                ...projection(RolloutAccounting.empty()),
+                toolCalls: 0,
+            },
+        ]));
+        for (const day of usage.daily)
+            days.set(day.date, {
+                day: day.date,
+                sessions: 0,
+                turns: 0,
+                additions: 0,
+                deletions: 0,
+                files: 0,
+                errors: 0,
+                ...days.get(day.date),
+                ...projection(day.accounting),
+                toolCalls: day.toolCalls,
+            });
+        const total = projection(usage.accounting);
+        const turns = snapshot.overview.totalTurns;
+        const activeDays = usage.daily.filter((day) => day.accounting.calls || day.accounting.legacy.messages).length || 1;
+        return {
+            ...snapshot,
+            tokenCost: {
+                ...total,
+                cacheHitRate: usage.cache.ratio ?? usage.cache.observedRatio ?? 0,
+                avgCostPerTurn: turns ? total.cost / turns : 0,
+                avgTokensPerTurn: turns ? usage.accounting.tokens.total.known / turns : 0,
+                dailyCost: total.cost / activeDays,
+                dailyTokens: usage.accounting.tokens.total.known / activeDays,
+            },
+            models: {
+                models: usage.models.map((model) => {
+                    const previous = snapshot.models.models.find((value) => value.providerID === model.providerID && value.modelID === model.modelID);
+                    return {
+                        providerID: model.providerID,
+                        modelID: model.modelID,
+                        messages: previous?.messages ?? 0,
+                        turns: previous?.turns ?? 0,
+                        avgResponseMs: previous?.avgResponseMs ?? 0,
+                        ...projection(model.accounting),
+                    };
+                }),
+            },
+            agents: {
+                ...snapshot.agents,
+                agents: Object.entries(usage.agents).map(([agent, accounting]) => {
+                    const previous = snapshot.agents.agents.find((value) => value.agent === agent);
+                    return {
+                        agent,
+                        messages: previous?.messages ?? 0,
+                        sessions: previous?.sessions ?? 0,
+                        subagentInvocations: previous?.subagentInvocations ?? 0,
+                        ...projection(accounting),
+                    };
+                }),
+            },
+            tools: {
+                tools: usage.tools.map((tool) => ({
+                    tool: tool.tool,
+                    calls: tool.calls,
+                    successes: tool.completed,
+                    errors: tool.failed,
+                    avgDurationMs: tool.averageMs ?? 0,
+                })),
+            },
+            timeSeries: { ...snapshot.timeSeries, days: [...days.values()].sort((a, b) => a.day.localeCompare(b.day)) },
+        };
+    }
+    CanonicalStats.apply = apply;
+})(CanonicalStats || (CanonicalStats = {}));

package/dist/stats/cli/stats.js

@@ -0,0 +1,302 @@
+import { cmd } from "@ericsanchezok/synergy-util/cli-command";
+import { UI } from "@ericsanchezok/synergy-util/terminal";
+import { Engine } from "../index.js";
+import { RolloutQuery } from "@ericsanchezok/synergy-harness/session/rollout/query";
+export const StatsCommand = cmd({
+    command: "stats",
+    describe: "show token usage and cost statistics",
+    builder: (yargs) => {
+        return yargs
+            .option("run", { type: "string", describe: "Show one run and its descendant accounting" })
+            .option("compare", {
+            type: "string",
+            array: true,
+            nargs: 2,
+            describe: "Compare two runs without inferring task quality",
+        })
+            .option("days", {
+            describe: "show stats for the last N days (default: all time)",
+            type: "number",
+        })
+            .option("tools", {
+            describe: "number of tools to show (default: all)",
+            type: "number",
+        })
+            .option("models", {
+            describe: "show model statistics (default: hidden). Pass a number to show top N, otherwise shows all",
+        })
+            .option("project", {
+            describe: "filter by project (default: all projects, empty string: current project)",
+            type: "string",
+        })
+            .option("recompute", {
+            describe: "force full recompute from scratch",
+            type: "boolean",
+            default: false,
+        })
+            .option("json", {
+            describe: "output raw JSON instead of formatted display",
+            type: "boolean",
+            default: false,
+        });
+    },
+    handler: async (args) => {
+        if (args.run || args.compare) {
+            if (args.run && args.compare)
+                throw new Error("Use either --run or --compare");
+            const result = args.run
+                ? await RolloutQuery.find(args.run)
+                : await Promise.all(args.compare.map((id) => RolloutQuery.find(id)));
+            console.log(JSON.stringify(Array.isArray(result) ? RolloutQuery.compare(result[0], result[1]) : result, null, 2));
+            return;
+        }
+        const onProgress = (event) => {
+            if (args.json)
+                return;
+            const pct = event.total > 0 ? Math.round((event.current / event.total) * 100) : 0;
+            const bar = UI.progressBar({ ratio: event.current / Math.max(1, event.total), width: 30, brackets: true });
+            const msg = event.message ?? event.phase;
+            process.stdout.write(`\r  ${bar} ${pct}% ${msg}`);
+            if (event.current === event.total && event.phase === "snapshot") {
+                process.stdout.write("\r\x1B[K");
+            }
+        };
+        let snapshot;
+        if (args.project !== undefined) {
+            console.log("Note: project-scoped filtering requires full recomputation.");
+            snapshot = await Engine.recompute(onProgress);
+        }
+        else if (args.recompute) {
+            snapshot = await Engine.recompute(onProgress);
+        }
+        else {
+            snapshot = await Engine.update(onProgress);
+        }
+        // Apply --days filter client-side on time series
+        if (args.days !== undefined) {
+            snapshot = filterByDays(snapshot, args.days);
+        }
+        if (args.json) {
+            console.log(JSON.stringify(snapshot, null, 2));
+            return;
+        }
+        let modelLimit;
+        if (args.models === true) {
+            modelLimit = Infinity;
+        }
+        else if (typeof args.models === "number") {
+            modelLimit = args.models;
+        }
+        displayStats(snapshot, args.tools, modelLimit);
+    },
+});
+function filterByDays(snapshot, days) {
+    const MS_IN_DAY = 24 * 60 * 60 * 1000;
+    const cutoff = days === 0
+        ? (() => {
+            const d = new Date();
+            d.setHours(0, 0, 0, 0);
+            return d.getTime();
+        })()
+        : Date.now() - days * MS_IN_DAY;
+    const filteredDays = snapshot.timeSeries.days.filter((d) => new Date(d.day).getTime() >= cutoff);
+    return {
+        ...snapshot,
+        timeSeries: {
+            ...snapshot.timeSeries,
+            days: filteredDays,
+        },
+    };
+}
+export function displayStats(snapshot, toolLimit, modelLimit) {
+    const width = 72;
+    function renderRow(label, value) {
+        const availableWidth = width - 1;
+        const paddingNeeded = availableWidth - label.length - value.length;
+        const padding = Math.max(0, paddingNeeded);
+        return `│${label}${" ".repeat(padding)}${value} │`;
+    }
+    function renderHeader(title) {
+        const innerWidth = width - 2;
+        const padTotal = innerWidth - title.length;
+        const padLeft = Math.floor(padTotal / 2);
+        const padRight = padTotal - padLeft;
+        console.log(`│${" ".repeat(padLeft)}${title}${" ".repeat(padRight)}│`);
+    }
+    function topBorder() {
+        console.log(`┌${"─".repeat(width - 2)}┐`);
+    }
+    function divider() {
+        console.log(`├${"─".repeat(width - 2)}┤`);
+    }
+    function bottomBorder() {
+        console.log(`└${"─".repeat(width - 2)}┘`);
+    }
+    const { overview, tokenCost, models, agents, tools, codeChanges, lifecycle, channels } = snapshot;
+    // ── Overview ──────────────────────────────────────────────
+    topBorder();
+    renderHeader("OVERVIEW");
+    divider();
+    console.log(renderRow("Sessions", `${overview.totalSessions.toLocaleString()} (active: ${overview.activeSessions}, archived: ${overview.archivedSessions})`));
+    console.log(renderRow("Messages", overview.totalMessages.toLocaleString()));
+    console.log(renderRow("Turns", overview.totalTurns.toLocaleString()));
+    console.log(renderRow("Days Active", overview.totalDays.toString()));
+    console.log(renderRow("Longest Streak", overview.longestStreak.toString()));
+    console.log(renderRow("Current Streak", overview.currentStreak.toString()));
+    console.log(renderRow("Projects", overview.projectCount.toString()));
+    bottomBorder();
+    console.log();
+    // ── Tokens & Cost ─────────────────────────────────────────
+    topBorder();
+    renderHeader("TOKENS & COST");
+    divider();
+    console.log(renderRow("Known API Estimate", `$${tokenCost.cost.toFixed(2)}`));
+    if (tokenCost.accounting) {
+        const accounting = tokenCost.accounting;
+        console.log(renderRow("Unpriced API Attempts", accounting.apiEstimate.unknown.toString()));
+        console.log(renderRow("Unobserved Calls", accounting.unobservedCalls.toString()));
+        console.log(renderRow("Subscription API Equivalent", `$${accounting.subscriptionEquivalent.known.toFixed(4)}`));
+        console.log(renderRow("Unknown Subscription Estimates", accounting.subscriptionEquivalent.unknown.toString()));
+        console.log(renderRow("Historical Calculation", `$${accounting.legacy.cost.toFixed(4)}`));
+        for (const [currency, amount] of Object.entries(accounting.reported.currencies))
+            console.log(renderRow(`Provider Reported (${currency})`, amount.toFixed(4)));
+    }
+    console.log(renderRow("Avg Cost/Turn", `$${tokenCost.avgCostPerTurn.toFixed(4)}`));
+    console.log(renderRow("Daily Cost", `$${tokenCost.dailyCost.toFixed(2)}`));
+    console.log(renderRow("Input Tokens", formatNumber(tokenCost.tokens.input)));
+    console.log(renderRow("Output Tokens", formatNumber(tokenCost.tokens.output)));
+    console.log(renderRow("Reasoning (included in output)", formatNumber(tokenCost.tokens.reasoning)));
+    console.log(renderRow("Cache Read", formatNumber(tokenCost.tokens.cache.read)));
+    console.log(renderRow("Cache Write", formatNumber(tokenCost.tokens.cache.write)));
+    console.log(renderRow("Cache Hit Rate", `${(tokenCost.cacheHitRate * 100).toFixed(1)}%`));
+    console.log(renderRow("Avg Tokens/Turn", formatNumber(Math.round(tokenCost.avgTokensPerTurn))));
+    console.log(renderRow("Daily Tokens", formatNumber(Math.round(tokenCost.dailyTokens))));
+    bottomBorder();
+    console.log();
+    // ── Models ────────────────────────────────────────────────
+    if (modelLimit !== undefined && models.models.length > 0) {
+        const sorted = [...models.models].sort((a, b) => b.messages - a.messages);
+        const toDisplay = modelLimit === Infinity ? sorted : sorted.slice(0, modelLimit);
+        topBorder();
+        renderHeader("MODEL USAGE");
+        divider();
+        for (const m of toDisplay) {
+            const modelKey = `${m.providerID}/${m.modelID}`;
+            console.log(renderRow(modelKey, ""));
+            console.log(renderRow("  Messages", m.messages.toLocaleString()));
+            console.log(renderRow("  Input Tokens", formatNumber(m.tokens.input)));
+            console.log(renderRow("  Output Tokens", formatNumber(m.tokens.output)));
+            console.log(renderRow("  Known API Estimate", `$${m.cost.toFixed(4)}`));
+            console.log(renderRow("  Avg Response", `${m.avgResponseMs.toFixed(0)}ms`));
+            divider();
+        }
+        // Replace last divider with bottom border
+        process.stdout.write("\x1B[1A");
+        bottomBorder();
+        console.log();
+    }
+    // ── Agents ────────────────────────────────────────────────
+    if (agents.agents.length > 0) {
+        const sorted = [...agents.agents].sort((a, b) => b.messages - a.messages);
+        topBorder();
+        renderHeader("AGENT USAGE");
+        divider();
+        for (const a of sorted) {
+            console.log(renderRow(a.agent, ""));
+            console.log(renderRow("  Messages", a.messages.toLocaleString()));
+            console.log(renderRow("  Sessions", a.sessions.toLocaleString()));
+            console.log(renderRow("  Known API Estimate", `$${a.cost.toFixed(4)}`));
+            console.log(renderRow("  Subagent Calls", a.subagentInvocations.toLocaleString()));
+            divider();
+        }
+        process.stdout.write("\x1B[1A");
+        bottomBorder();
+        console.log();
+        if (agents.totalSubagentCalls > 0) {
+            console.log(`  Total subagent calls: ${agents.totalSubagentCalls.toLocaleString()}`);
+            console.log();
+        }
+    }
+    // ── Tools ─────────────────────────────────────────────────
+    if (tools.tools.length > 0) {
+        const sorted = [...tools.tools].sort((a, b) => b.calls - a.calls);
+        const toDisplay = toolLimit ? sorted.slice(0, toolLimit) : sorted;
+        const maxCalls = Math.max(...toDisplay.map((t) => t.calls));
+        const totalCalls = tools.tools.reduce((sum, t) => sum + t.calls, 0);
+        topBorder();
+        renderHeader("TOOL USAGE");
+        divider();
+        for (const t of toDisplay) {
+            const ratio = t.calls / maxCalls;
+            const bar = UI.progressBar({ ratio, width: 20, brackets: false });
+            const percentage = totalCalls > 0 ? ((t.calls / totalCalls) * 100).toFixed(1) : "0.0";
+            const successRate = t.calls > 0 ? ((t.successes / t.calls) * 100).toFixed(0) : "—";
+            const maxToolLength = 18;
+            const truncatedTool = t.tool.length > maxToolLength ? t.tool.substring(0, maxToolLength - 2) + ".." : t.tool;
+            const toolName = truncatedTool.padEnd(maxToolLength);
+            const content = ` ${toolName} ${bar.padEnd(20)} ${t.calls.toString().padStart(4)} (${percentage.padStart(4)}%) ${successRate.padStart(3)}%ok`;
+            const padding = Math.max(0, width - content.length - 1);
+            console.log(`│${content}${" ".repeat(padding)} │`);
+        }
+        divider();
+        const avgDurLine = ` Avg duration per tool (ms):`;
+        console.log(`│${avgDurLine}${" ".repeat(width - avgDurLine.length - 2)} │`);
+        for (const t of toDisplay) {
+            const durText = `   ${t.tool}: ${t.avgDurationMs.toFixed(0)}ms`;
+            const padding = Math.max(0, width - durText.length - 2);
+            console.log(`│${durText}${" ".repeat(padding)} │`);
+        }
+        bottomBorder();
+        console.log();
+    }
+    // ── Code Changes ──────────────────────────────────────────
+    if (codeChanges.totalAdditions > 0 || codeChanges.totalDeletions > 0) {
+        topBorder();
+        renderHeader("CODE CHANGES");
+        divider();
+        console.log(renderRow("Additions", formatNumber(codeChanges.totalAdditions)));
+        console.log(renderRow("Deletions", formatNumber(codeChanges.totalDeletions)));
+        console.log(renderRow("Net Lines", formatNumber(codeChanges.netLines)));
+        console.log(renderRow("Files Touched", formatNumber(codeChanges.totalFiles)));
+        console.log(renderRow("Daily Additions", formatNumber(Math.round(codeChanges.dailyAdditions))));
+        console.log(renderRow("Daily Deletions", formatNumber(Math.round(codeChanges.dailyDeletions))));
+        bottomBorder();
+        console.log();
+    }
+    // ── Lifecycle ─────────────────────────────────────────────
+    topBorder();
+    renderHeader("LIFECYCLE");
+    divider();
+    console.log(renderRow("Pinned Sessions", lifecycle.pinnedCount.toLocaleString()));
+    console.log(renderRow("Avg Turns/Session", lifecycle.avgTurnsPerSession.toFixed(1)));
+    console.log(renderRow("Median Turns/Session", lifecycle.medianTurnsPerSession.toFixed(1)));
+    console.log(renderRow("Compactions", lifecycle.compactionCount.toLocaleString()));
+    console.log(renderRow("Retries", lifecycle.retryCount.toLocaleString()));
+    console.log(renderRow("Error Rate", `${(lifecycle.errorRate * 100).toFixed(1)}%`));
+    console.log(renderRow("Duration (short/med/long)", `${lifecycle.durationBuckets.short}/${lifecycle.durationBuckets.medium}/${lifecycle.durationBuckets.long}`));
+    bottomBorder();
+    console.log();
+    // ── Channels ──────────────────────────────────────────────
+    if (channels.channels.length > 0) {
+        topBorder();
+        renderHeader("CHANNELS");
+        divider();
+        for (const c of channels.channels) {
+            console.log(renderRow(c.channel, `sessions: ${c.sessions}, messages: ${c.messages}`));
+        }
+        divider();
+        console.log(renderRow("Interactive", channels.interactiveSessions.toLocaleString()));
+        console.log(renderRow("Unattended", channels.unattendedSessions.toLocaleString()));
+        bottomBorder();
+        console.log();
+    }
+}
+function formatNumber(num) {
+    if (num >= 1000000) {
+        return (num / 1000000).toFixed(1) + "M";
+    }
+    else if (num >= 1000) {
+        return (num / 1000).toFixed(1) + "K";
+    }
+    return num.toString();
+}

package/dist/stats/engine.js

@@ -0,0 +1,176 @@
+import { RolloutSnapshot } from "@ericsanchezok/synergy-harness/session/rollout/snapshot";
+import { OperationDigest } from "./types.js";
+import { Lock } from "@ericsanchezok/synergy-harness/util/lock";
+import { readRolloutRevision } from "@ericsanchezok/synergy-harness/rollout";
+import { Storage } from "@ericsanchezok/synergy-harness/storage/storage";
+import { StoragePath } from "@ericsanchezok/synergy-harness/storage/path";
+import { Aggregator } from "./aggregator.js";
+import { StatsStorage } from "./storage.js";
+import { Rollup } from "./rollup.js";
+import { CanonicalStats } from "./canonical.js";
+import { Usage } from "@ericsanchezok/synergy-harness/usage";
+export var Engine;
+(function (Engine) {
+    // -----------------------------------------------------------------------
+    // Public API
+    // -----------------------------------------------------------------------
+    /**
+     * Run incremental stats update: scan sessions changed since watermark,
+     * update digests + daily buckets, recompute snapshot.
+     */
+    async function update(onProgress) {
+        return requestRefresh(false, onProgress);
+    }
+    Engine.update = update;
+    const jobs = Storage.state(() => new Map());
+    function requestRefresh(full, onProgress) {
+        const running = jobs();
+        const existing = running.get(full) ?? (!full ? running.get(true) : undefined);
+        if (existing) {
+            if (onProgress)
+                existing.listeners.add(onProgress);
+            return existing.promise.finally(() => {
+                if (onProgress)
+                    existing.listeners.delete(onProgress);
+            });
+        }
+        const listeners = new Set(onProgress ? [onProgress] : []);
+        const promise = refresh(full, (event) => {
+            for (const listener of listeners)
+                void Promise.resolve()
+                    .then(() => listener(event))
+                    .catch(() => listeners.delete(listener));
+        }).finally(() => running.delete(full));
+        running.set(full, { promise, listeners });
+        return promise;
+    }
+    async function operationDigests() {
+        const result = [];
+        const retained = new Set();
+        for (const scopeID of await Storage.scan(["operations"])) {
+            for (const operationID of await Storage.scan(["operations", scopeID])) {
+                const owner = { kind: "operation", scopeID, operationID };
+                const revision = await readRolloutRevision(owner);
+                if (!revision)
+                    continue;
+                const key = StoragePath.statsOperation(scopeID, operationID);
+                retained.add(key.join("/"));
+                const cached = await Storage.read(key).catch((error) => {
+                    if (error instanceof Storage.NotFoundError)
+                        return undefined;
+                    throw error;
+                });
+                const parsed = OperationDigest.safeParse(cached);
+                if (parsed.success && parsed.data.rolloutRevision === revision) {
+                    result.push(parsed.data);
+                    continue;
+                }
+                const digest = Aggregator.operation(await RolloutSnapshot.read(owner, { revision }));
+                await Storage.write(key, digest);
+                result.push(digest);
+            }
+        }
+        for (const scopeID of await Storage.scan(StoragePath.statsOperations()))
+            for (const id of await Storage.scan([...StoragePath.statsOperations(), scopeID])) {
+                const key = StoragePath.statsOperation(scopeID, id);
+                if (!retained.has(key.join("/")))
+                    await Storage.remove(key);
+            }
+        return result;
+    }
+    async function refresh(full, onProgress) {
+        using lock = await Lock.write("stats-update");
+        const watermark = full ? undefined : await StatsStorage.getWatermark();
+        onProgress?.({ phase: "scan", current: 0, total: 1, message: "Scanning sessions..." });
+        const allSessions = await getAllSessions();
+        let newOrUpdated;
+        let deletedIDs;
+        if (watermark) {
+            const knownSet = new Set(watermark.sessionIDs);
+            const currentMap = new Map(allSessions.map((s) => [s.id, s]));
+            // Sessions that are new or updated since watermark
+            newOrUpdated = [];
+            for (let offset = 0; offset < allSessions.length; offset += 20) {
+                const batch = allSessions.slice(offset, offset + 20);
+                const changed = await Promise.all(batch.map(async (session) => {
+                    if (!knownSet.has(session.id) || session.time.updated > watermark.lastUpdated)
+                        return true;
+                    const [digest, revision] = await Promise.all([
+                        StatsStorage.getDigest(session.id),
+                        readRolloutRevision({ kind: "session", scopeID: session.scope.id, sessionID: session.id }),
+                    ]);
+                    return digest?.rolloutRevision !== revision;
+                }));
+                newOrUpdated.push(...batch.filter((_, index) => changed[index]));
+            }
+            // Sessions that were known but no longer exist
+            deletedIDs = watermark.sessionIDs.filter((id) => !currentMap.has(id));
+        }
+        else {
+            newOrUpdated = allSessions;
+            deletedIDs = [];
+        }
+        // Digest new/updated sessions with progress
+        const freshDigests = await Aggregator.digestAll(newOrUpdated, (current, total) => {
+            onProgress?.({ phase: "digest", current, total, message: `Digesting sessions ${current}/${total}...` });
+        });
+        // Write new/updated digests
+        for (const d of freshDigests) {
+            await Usage.preserveOwner({ kind: "session", scopeID: d.scopeID, sessionID: d.sessionID });
+            await StatsStorage.setDigest(d);
+        }
+        // Remove digests for deleted sessions
+        for (const id of deletedIDs) {
+            await StatsStorage.removeDigest(id);
+        }
+        // Load all digests for full snapshot
+        onProgress?.({ phase: "snapshot", current: 0, total: 1, message: "Computing snapshot..." });
+        const allDigests = await StatsStorage.getAllDigests();
+        // Compute new watermark
+        const maxUpdated = allSessions.length > 0 ? Math.max(...allSessions.map((s) => s.time.updated)) : 0;
+        const newWatermark = {
+            lastUpdated: maxUpdated,
+            sessionIDs: allSessions.map((s) => s.id),
+            lastFullScanAt: Date.now(),
+        };
+        // Compute and store snapshot
+        const snapshot = await CanonicalStats.apply(Rollup.snapshot(allDigests, maxUpdated, await operationDigests()));
+        onProgress?.({
+            phase: "bucket",
+            current: 0,
+            total: snapshot.timeSeries.days.length,
+            message: "Updating daily buckets...",
+        });
+        const days = new Set(snapshot.timeSeries.days.map((day) => day.day));
+        for (const day of snapshot.timeSeries.days)
+            await StatsStorage.setDailyBucket(day.day, day);
+        for (const day of await StatsStorage.listDailyKeys()) {
+            if (!days.has(day))
+                await Storage.remove(StoragePath.statsDaily(day));
+        }
+        await StatsStorage.setSnapshot(snapshot);
+        await StatsStorage.setWatermark(newWatermark);
+        onProgress?.({ phase: "snapshot", current: 1, total: 1, message: "Done" });
+        return snapshot;
+    }
+    async function get() {
+        return (await StatsStorage.getSnapshot()) ?? null;
+    }
+    Engine.get = get;
+    /**
+     * Force full recompute from scratch (clears all cached stats).
+     */
+    async function recompute(onProgress) {
+        return requestRefresh(true, onProgress);
+    }
+    Engine.recompute = recompute;
+    // -----------------------------------------------------------------------
+    // Internal helpers
+    // -----------------------------------------------------------------------
+    async function getAllSessions() {
+        const sessions = [];
+        for await (const record of Storage.records({ kind: "session" }))
+            sessions.push(record.value);
+        return sessions;
+    }
+})(Engine || (Engine = {}));

package/dist/stats/index.js

@@ -0,0 +1,5 @@
+export { Engine } from "./engine.js";
+export { Aggregator } from "./aggregator.js";
+export { Rollup } from "./rollup.js";
+export { StatsStorage } from "./storage.js";
+export * from "./types.js";