@gajae-code/stats 0.17.2 → 0.17.4

package/dist/types/db.d.ts

@@ -1,5 +1,5 @@
 import { Database } from "bun:sqlite";
-import type { AggregatedStats, BehaviorModelStats, BehaviorOverallStats, BehaviorTimeSeriesPoint, CostTimeSeriesPoint, FolderStats, MessageStats, ModelPerformancePoint, ModelStats, ModelTimeSeriesPoint, TimeSeriesPoint, UserMessageLink, UserMessageStats } from "./types";
+import type { AggregatedStats, BehaviorModelStats, BehaviorOverallStats, BehaviorTimeSeriesPoint, CostTimeSeriesPoint, FolderStats, MessageStats, ModelPerformancePoint, ModelStats, ModelTimeSeriesPoint, ParsedMessageStats, TimeSeriesPoint, UserMessageLink, UserMessageStats } from "./types";
 /**
  * Initialize the database and create tables.
  */
@@ -18,7 +18,7 @@ export declare function setFileOffset(sessionFile: string, offset: number, lastM
 /**
  * Insert message stats into the database.
  */
-export declare function insertMessageStats(stats: MessageStats[]): number;
+export declare function insertMessageStats(stats: ParsedMessageStats[]): number;
 /**
  * Get overall aggregated stats.
  */

package/dist/types/parser.d.ts

@@ -1,4 +1,4 @@
-import type { MessageStats, SessionEntry, UserMessageLink, UserMessageStats } from "./types";
+import type { ParsedMessageStats, SessionEntry, UserMessageLink, UserMessageStats } from "./types";
 /**
  * Parse a session file and extract all assistant message stats.
  * Uses incremental reading with offset tracking.
@@ -16,7 +16,7 @@ import type { MessageStats, SessionEntry, UserMessageLink, UserMessageStats } fr
  * entries, preserving offset-based memory behavior for large sessions.
  */
 export interface ParseSessionResult {
-    stats: MessageStats[];
+    stats: ParsedMessageStats[];
     userStats: UserMessageStats[];
     userLinks: UserMessageLink[];
     newOffset: number;

package/dist/types/types.d.ts

@@ -25,7 +25,7 @@ export interface MessageStats {
     /** Time to first token in milliseconds */
     ttft: number | null;
     /** Stop reason */
-    stopReason: StopReason;
+    stopReason: StopReason | "unknown";
     /** Error message if stopReason is error */
     errorMessage: string | null;
     /** Token usage */
@@ -51,12 +51,22 @@ export interface SessionHeader {
     cwd: string;
     title?: string;
 }
+/** Historical JSONL may contain missing, partial, or malformed cost payloads. */
+export type SessionAssistantMessage = Omit<AssistantMessage, "usage"> & {
+    usage: Omit<Usage, "cost"> & {
+        cost?: unknown;
+    };
+};
+/** Parser output retains untrusted costs until the database insertion boundary. */
+export type ParsedMessageStats = Omit<MessageStats, "usage"> & {
+    usage: SessionAssistantMessage["usage"];
+};
 export interface SessionMessageEntry {
     type: "message";
     id: string;
     parentId: string | null;
     timestamp: string;
-    message: AssistantMessage | {
+    message: SessionAssistantMessage | {
         role: "user" | "toolResult";
     };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/stats",
-	"version": "0.17.2",
+	"version": "0.17.4",
 	"description": "Local observability dashboard for pi AI usage statistics",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo",
@@ -38,8 +38,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/ai": "0.17.2",
-		"@gajae-code/utils": "0.17.2",
+		"@gajae-code/ai": "0.17.4",
+		"@gajae-code/utils": "0.17.4",
 		"@tailwindcss/node": "^4.2.4",
 		"chart.js": "^4.5.1",
 		"date-fns": "^4.1.0",

package/src/db.ts

@@ -13,6 +13,7 @@ import type {
 	ModelPerformancePoint,
 	ModelStats,
 	ModelTimeSeriesPoint,
+	ParsedMessageStats,
 	TimeSeriesPoint,
 	UserMessageLink,
 	UserMessageStats,
@@ -228,12 +229,32 @@ function calculateCatalogCost(provider: string, modelId: string, tokens: CostTok
 	};
 }
 
-function resolveStoredCost(stats: MessageStats): UsageCost {
-	if (stats.usage.cost.total !== 0) {
-		return stats.usage.cost;
-	}
-
-	return calculateCatalogCost(stats.provider, stats.model, stats.usage) ?? stats.usage.cost;
+function resolveStoredCost(stats: ParsedMessageStats): UsageCost {
+	const raw = stats.usage.cost;
+	const recorded = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
+	const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
+	const keys = ["input", "output", "cacheRead", "cacheWrite", "total"] as const;
+	// Complete zero-cost payloads historically request catalog pricing. A partial
+	// payload is different: preserve every valid recorded value, including zero.
+	const allZero = keys.every(key => recorded[key] === 0);
+	const catalog = calculateCatalogCost(stats.provider, stats.model, stats.usage);
+	const component = (key: keyof ModelCost): number => {
+		if (!allZero && finite(recorded[key])) return recorded[key];
+		const fallback = catalog?.[key];
+		return finite(fallback) ? fallback : 0;
+	};
+	const input = component("input");
+	const output = component("output");
+	const cacheRead = component("cacheRead");
+	const cacheWrite = component("cacheWrite");
+	const sum = input + output + cacheRead + cacheWrite;
+	return {
+		input,
+		output,
+		cacheRead,
+		cacheWrite,
+		total: !allZero && finite(recorded.total) ? recorded.total : finite(sum) ? sum : 0,
+	};
 }
 
 function backfillMissingCatalogCosts(database: Database): void {
@@ -242,6 +263,7 @@ function backfillMissingCatalogCosts(database: Database): void {
 			SELECT id, provider, model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens
 			FROM messages
 			WHERE cost_total = 0 AND total_tokens > 0
+				AND cost_input = 0 AND cost_output = 0 AND cost_cache_read = 0 AND cost_cache_write = 0
 		`)
 		.all() as CostBackfillRow[];
 
@@ -299,7 +321,7 @@ export function setFileOffset(sessionFile: string, offset: number, lastModified:
 /**
  * Insert message stats into the database.
  */
-export function insertMessageStats(stats: MessageStats[]): number {
+export function insertMessageStats(stats: ParsedMessageStats[]): number {
 	if (!db || stats.length === 0) return 0;
 
 	// Use UPSERT so a re-sync can fix up `premium_requests` for rows persisted

package/src/parser.ts

@@ -1,9 +1,10 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { type AssistantMessage, getPriorityPremiumRequests, type ServiceTier } from "@gajae-code/ai";
+import { getPriorityPremiumRequests, type ServiceTier } from "@gajae-code/ai";
 import { getSessionsDir, isEnoent } from "@gajae-code/utils";
 import type {
-	MessageStats,
+	ParsedMessageStats,
+	SessionAssistantMessage,
 	SessionEntry,
 	SessionMessageEntry,
 	SessionServiceTierChangeEntry,
@@ -25,34 +26,46 @@ function extractFolderFromPath(sessionPath: string): string {
 	return projectDir.replace(/^--/, "/").replace(/--/g, "/");
 }
 
+function isObject(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isNonemptyString(value: unknown): value is string {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+function isNonnegativeNumber(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
 /**
  * Check if an entry is an assistant message.
  */
 function isAssistantMessage(entry: SessionEntry): entry is SessionMessageEntry {
-	if (entry.type !== "message") return false;
+	if (!isObject(entry) || entry.type !== "message") return false;
 	const msgEntry = entry as SessionMessageEntry;
 	// Legacy sessions (pre-id tracking) recorded message entries without an `id`.
 	// They're not linkable and would violate the messages.entry_id NOT NULL
 	// constraint, so skip them at the parser boundary.
 	if (typeof msgEntry.id !== "string" || msgEntry.id.length === 0) return false;
-	return msgEntry.message?.role === "assistant";
+	return isObject(msgEntry.message) && msgEntry.message.role === "assistant";
 }
 
 /**
  * Check if an entry is a user message (non-toolResult).
  */
 function isUserMessage(entry: SessionEntry): entry is SessionMessageEntry {
-	if (entry.type !== "message") return false;
+	if (!isObject(entry) || entry.type !== "message") return false;
 	const msgEntry = entry as SessionMessageEntry;
 	if (typeof msgEntry.id !== "string" || msgEntry.id.length === 0) return false;
-	return msgEntry.message?.role === "user";
+	return isObject(msgEntry.message) && msgEntry.message.role === "user";
 }
 
 /**
  * Check if an entry is a service-tier change.
  */
 function isServiceTierChange(entry: SessionEntry): entry is SessionServiceTierChangeEntry {
-	return entry.type === "service_tier_change";
+	return isObject(entry) && entry.type === "service_tier_change";
 }
 
 /**
@@ -107,9 +120,21 @@ function extractStats(
 	folder: string,
 	entry: SessionMessageEntry,
 	currentServiceTier: ServiceTier | undefined,
-): MessageStats | null {
-	const msg = entry.message as AssistantMessage;
+): ParsedMessageStats | null {
+	const msg = entry.message as SessionAssistantMessage;
 	if (msg?.role !== "assistant") return null;
+	// Incomplete historical metadata cannot be safely attributed or counted.
+	// Skip malformed rows, as with legacy entries lacking an ID; do not invent usage.
+	if (!isNonemptyString(msg.model) || !isNonemptyString(msg.provider) || !isNonemptyString(msg.api)) return null;
+	if (!isNonnegativeNumber(msg.timestamp) || !isObject(msg.usage)) return null;
+	if (
+		!isNonnegativeNumber(msg.usage.input) ||
+		!isNonnegativeNumber(msg.usage.output) ||
+		!isNonnegativeNumber(msg.usage.cacheRead) ||
+		!isNonnegativeNumber(msg.usage.cacheWrite) ||
+		!isNonnegativeNumber(msg.usage.totalTokens)
+	)
+		return null;
 
 	// Backfill: when the session recorded `priority` as the active service tier
 	// at this point but the AI usage payload was captured before priority
@@ -117,9 +142,9 @@ function extractStats(
 	// "Premium Reqs" stat aggregates priority traffic on re-sync. Trust any
 	// non-zero value already in `usage.premiumRequests` (Copilot multipliers or
 	// the new AI code path) and only synthesise when the field is missing/zero.
-	const recorded = msg.usage.premiumRequests ?? 0;
+	const recorded = isNonnegativeNumber(msg.usage.premiumRequests) ? msg.usage.premiumRequests : 0;
 	const derived = recorded > 0 ? recorded : getPriorityPremiumRequests(currentServiceTier, msg.provider);
-	const usage = derived === recorded ? msg.usage : { ...msg.usage, premiumRequests: derived };
+	const usage = { ...msg.usage, premiumRequests: derived };
 
 	return {
 		sessionFile,
@@ -129,10 +154,12 @@ function extractStats(
 		provider: msg.provider,
 		api: msg.api,
 		timestamp: msg.timestamp,
-		duration: msg.duration ?? null,
-		ttft: msg.ttft ?? null,
-		stopReason: msg.stopReason,
-		errorMessage: msg.errorMessage ?? null,
+		duration: isNonnegativeNumber(msg.duration) ? msg.duration : null,
+		ttft: isNonnegativeNumber(msg.ttft) ? msg.ttft : null,
+		// Historical session entries may omit stopReason. Keep the stats schema
+		// non-nullable while preserving those requests instead of aborting sync.
+		stopReason: isNonemptyString(msg.stopReason) ? msg.stopReason : "unknown",
+		errorMessage: typeof msg.errorMessage === "string" ? msg.errorMessage : null,
 		usage,
 	};
 }
@@ -205,7 +232,7 @@ function scanLastServiceTier(bytes: Uint8Array): ServiceTier | undefined {
  * entries, preserving offset-based memory behavior for large sessions.
  */
 export interface ParseSessionResult {
-	stats: MessageStats[];
+	stats: ParsedMessageStats[];
 	userStats: UserMessageStats[];
 	userLinks: UserMessageLink[];
 	newOffset: number;
@@ -220,7 +247,7 @@ export async function parseSessionFile(sessionPath: string, fromOffset = 0): Pro
 	}
 
 	const folder = extractFolderFromPath(sessionPath);
-	const stats: MessageStats[] = [];
+	const stats: ParsedMessageStats[] = [];
 	const userStats: UserMessageStats[] = [];
 	const userLinks: UserMessageLink[] = [];
 	const userByEntryId = new Map<string, UserMessageStats>();
@@ -249,9 +276,9 @@ export async function parseSessionFile(sessionPath: string, fromOffset = 0): Pro
 			if (msgStats) stats.push(msgStats);
 			// Link assistant's responding model back to the user message it answered.
 			const parentId = (entry as SessionMessageEntry).parentId;
-			if (parentId) {
-				const msg = entry.message as AssistantMessage;
-				if (msg.model && msg.provider) {
+			if (isNonemptyString(parentId)) {
+				const msg = entry.message as SessionAssistantMessage;
+				if (isNonemptyString(msg.model) && isNonemptyString(msg.provider)) {
 					// Emit unconditionally. The aggregator's UPDATE is guarded by
 					// `model IS NULL` so this is idempotent: a no-op for already
 					// linked rows, a fix-up for fresh inserts (which start NULL
@@ -326,7 +353,7 @@ export async function getSessionEntry(sessionPath: string, entryId: string): Pro
 
 	const { entries } = parseSessionEntriesLenient(bytes);
 	for (const entry of entries) {
-		if ("id" in entry && entry.id === entryId) {
+		if (isObject(entry) && "id" in entry && entry.id === entryId) {
 			return entry;
 		}
 	}

package/src/types.ts

@@ -27,7 +27,7 @@ export interface MessageStats {
 	/** Time to first token in milliseconds */
 	ttft: number | null;
 	/** Stop reason */
-	stopReason: StopReason;
+	stopReason: StopReason | "unknown";
 	/** Error message if stopReason is error */
 	errorMessage: string | null;
 	/** Token usage */
@@ -56,12 +56,20 @@ export interface SessionHeader {
 	title?: string;
 }
 
+/** Historical JSONL may contain missing, partial, or malformed cost payloads. */
+export type SessionAssistantMessage = Omit<AssistantMessage, "usage"> & {
+	usage: Omit<Usage, "cost"> & { cost?: unknown };
+};
+
+/** Parser output retains untrusted costs until the database insertion boundary. */
+export type ParsedMessageStats = Omit<MessageStats, "usage"> & { usage: SessionAssistantMessage["usage"] };
+
 export interface SessionMessageEntry {
 	type: "message";
 	id: string;
 	parentId: string | null;
 	timestamp: string;
-	message: AssistantMessage | { role: "user" | "toolResult" };
+	message: SessionAssistantMessage | { role: "user" | "toolResult" };
 }
 
 export interface SessionServiceTierChangeEntry {