@linxiraos/pi-stats 1.1.13 → 1.1.15

package/src/parser.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs/promises";
+import * as os from "node:os";
 import * as path from "node:path";
 import {
 	type AssistantMessage,
@@ -14,7 +15,7 @@ import { classifyModel } from "@linxiraos/pi-catalog/compat/taxonomy";
 import { getSessionsDir, isEnoent, readLines } from "@linxiraos/pi-utils";
 import type {
 	AgentType,
-	MessageStats,
+	MessageStatsInput,
 	SessionEntry,
 	SessionMessageEntry,
 	SessionModelUsageEntry,
@@ -62,6 +63,53 @@ export function extractFolderFromPath(sessionPath: string): string {
 	return projectDir.replace(/^--/, "/").replace(/--/g, "/");
 }
 
+/**
+ * Decode a session project folder name back to its source cwd, mirroring the
+ * encoder in the coding agent's session-paths module: home-relative cwds
+ * encode as `-<segments>`, temp-relative ones as `-tmp<segments>`, and legacy
+ * absolute ones as `--<absolute>--`, with `/`, `\`, and `:` collapsed to `-`.
+ * Returns null when the name carries no decodable cwd.
+ */
+export function decodeProjectFolderCwd(projectDir: string): string | null {
+	if (projectDir === "-tmp" || projectDir.startsWith("-tmp-")) return os.tmpdir();
+	if (projectDir.startsWith("--")) {
+		const inner = projectDir.replace(/^--/, "").replace(/--$/, "");
+		if (!inner) return path.resolve("/");
+		// POSIX legacy names had their leading `/` stripped, so restore it;
+		// Windows names collapsed a drive letter's `:` into a dash too
+		// (`C--Users` decodes to `C:\Users`), so re-attach the colon.
+		if (path.sep === "/") return path.resolve(`/${inner.replaceAll("-", "/")}`);
+		return path.resolve(inner.replaceAll("-", "\\").replace(/^([A-Za-z])\\/, "$1:\\"));
+	}
+	if (projectDir.startsWith("-")) {
+		const inner = projectDir.replace(/^-/, "");
+		return path.resolve(os.homedir(), inner.replaceAll("-", path.sep));
+	}
+	// Folder names without the leading marker predate the encoder; no cwd is
+	// recoverable, so they are never treated as temp.
+	return null;
+}
+
+/**
+ * Whether a session project folder decodes to a cwd inside the OS temp dir.
+ * Test suites spawn agents under `os.tmpdir()` and re-create their transcripts
+ * on every run; those sessions are throwaway usage that must not reach the
+ * stats DB. The `-` collapse in the encoder is lossy (a literal `-` inside a
+ * path segment is indistinguishable from a separator), which can only produce
+ * false positives here — a skipped ingestion, never a misattributed row.
+ */
+export function isTempProjectFolder(projectDir: string): boolean {
+	const decoded = decodeProjectFolderCwd(projectDir);
+	if (!decoded) return false;
+	const tmp = path.resolve(os.tmpdir());
+	const candidate = path.resolve(decoded);
+	// NTFS comparisons are case-insensitive; resolve() normalizes separators.
+	const caseFold = process.platform === "win32";
+	const normalizedTmp = caseFold ? tmp.toLowerCase() : tmp;
+	const normalizedCandidate = caseFold ? candidate.toLowerCase() : candidate;
+	return normalizedCandidate === normalizedTmp || normalizedCandidate.startsWith(normalizedTmp + path.sep);
+}
+
 /**
  * Check if an entry is an assistant message.
  */
@@ -150,6 +198,61 @@ function extractUserStats(sessionFile: string, folder: string, entry: SessionMes
 	};
 }
 
+/**
+ * Session JSONL is written by older versions and foreign producers, so a token
+ * counter is whatever was persisted, not what `Usage` declares. A non-numeric
+ * bucket (`input: "10"`) must never be parsed and must never be summed: `+`
+ * would concatenate it into the derived total and SQLite would coerce the
+ * resulting string to a different, far larger number. A non-finite one
+ * (`input: 1e999` is legal JSON) must not reach a NOT NULL column either.
+ * Malformed input counts as absent.
+ */
+function isFiniteCount(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value);
+}
+
+function finiteTokenCount(value: unknown): number {
+	return isFiniteCount(value) ? value : 0;
+}
+
+/**
+ * Token-bucket view for total derivation. Persisted session payloads are
+ * outside-controlled (old versions, foreign producers), so every counter is
+ * `unknown` and validated at read time.
+ */
+export interface UsageBucketView {
+	totalTokens?: unknown;
+	input?: unknown;
+	output?: unknown;
+	cacheRead?: unknown;
+	cacheWrite?: unknown;
+	orchestration?: { input?: unknown; output?: unknown; cacheRead?: unknown } | null;
+}
+
+/**
+ * Total tokens for one usage payload, per the documented contract: the
+ * conversation buckets plus provider-reported orchestration tokens. A present
+ * finite provider total stays authoritative; a missing or malformed one
+ * (absent, string, NaN) is derived from the buckets, which would otherwise
+ * persist a zero total next to real token counts. Shared by ingest and the
+ * trace builder so stored and displayed totals cannot disagree.
+ */
+export function resolveUsageTotal(usage: UsageBucketView | null | undefined): number {
+	if (typeof usage?.totalTokens === "number" && Number.isFinite(usage.totalTokens)) return usage.totalTokens;
+	if (!usage || typeof usage !== "object") return 0;
+	const orchestration =
+		usage.orchestration && typeof usage.orchestration === "object" ? usage.orchestration : undefined;
+	return (
+		finiteTokenCount(usage.input) +
+		finiteTokenCount(usage.output) +
+		finiteTokenCount(usage.cacheRead) +
+		finiteTokenCount(usage.cacheWrite) +
+		finiteTokenCount(orchestration?.input) +
+		finiteTokenCount(orchestration?.output) +
+		finiteTokenCount(orchestration?.cacheRead)
+	);
+}
+
 /**
  * Extract stats from an assistant message entry.
  *
@@ -167,7 +270,7 @@ function extractStats(
 	entry: SessionMessageEntry,
 	currentServiceTier: ServiceTierByFamily | undefined,
 	agentType: AgentType,
-): MessageStats | null {
+): MessageStatsInput | null {
 	const msg = entry.message as AssistantMessage;
 	if (msg?.role !== "assistant") return null;
 	if (typeof msg.model !== "string" || typeof msg.provider !== "string" || typeof msg.api !== "string") return null;
@@ -189,22 +292,27 @@ function extractStats(
 	const tier = resolveModelServiceTier(currentServiceTier, model);
 	const derived = recorded > 0 ? recorded : getPriorityPremiumRequests(tier, model);
 	const wellFormed =
-		typeof rawUsage.input === "number" &&
-		typeof rawUsage.output === "number" &&
-		typeof rawUsage.cacheRead === "number" &&
-		typeof rawUsage.cacheWrite === "number" &&
-		typeof rawUsage.totalTokens === "number";
-	const usage: Usage =
+		isFiniteCount(rawUsage.input) &&
+		isFiniteCount(rawUsage.output) &&
+		isFiniteCount(rawUsage.cacheRead) &&
+		isFiniteCount(rawUsage.cacheWrite) &&
+		isFiniteCount(rawUsage.totalTokens);
+	const usage: MessageStatsInput["usage"] =
 		wellFormed && derived === recorded
 			? (rawUsage as Usage)
 			: {
 					...rawUsage,
-					input: rawUsage.input ?? 0,
-					output: rawUsage.output ?? 0,
-					cacheRead: rawUsage.cacheRead ?? 0,
-					cacheWrite: rawUsage.cacheWrite ?? 0,
-					totalTokens: rawUsage.totalTokens ?? 0,
-					cost: rawUsage.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+					input: finiteTokenCount(rawUsage.input),
+					output: finiteTokenCount(rawUsage.output),
+					cacheRead: finiteTokenCount(rawUsage.cacheRead),
+					cacheWrite: finiteTokenCount(rawUsage.cacheWrite),
+					// A present finite provider total stays authoritative; a missing
+					// or malformed one (absent, string, NaN) is derived from the buckets.
+					totalTokens: resolveUsageTotal(rawUsage),
+					// An omitted `cost` must stay omitted: `resolveStoredCost` reads
+					// absence as "no recorded price" and estimates the request, while
+					// a zero would read as an explicitly free request.
+					cost: rawUsage.cost,
 					premiumRequests: derived,
 				};
 
@@ -232,7 +340,7 @@ function extractModelUsageStats(
 	folder: string,
 	entry: SessionModelUsageEntry,
 	agentType: AgentType,
-): MessageStats | null {
+): MessageStatsInput | null {
 	const timestamp = Date.parse(entry.timestamp);
 	return extractStats(
 		sessionFile,
@@ -261,7 +369,9 @@ function extractModelUsageStats(
 
 /** Message timestamp, falling back to the entry's ISO timestamp, then 0. */
 function coerceEntryTimestamp(timestamp: number | undefined, entry: SessionMessageEntry): number {
-	if (typeof timestamp === "number" && Number.isFinite(timestamp)) return timestamp;
+	// A stored zero is the "no timestamp" sentinel, not 1970: fall through to
+	// the entry envelope so a recoverable ISO time still selects its tariff.
+	if (typeof timestamp === "number" && Number.isFinite(timestamp) && timestamp > 0) return timestamp;
 	const ts = Date.parse(entry.timestamp);
 	return Number.isFinite(ts) ? ts : 0;
 }
@@ -409,7 +519,7 @@ function scanLastServiceTier(bytes: Uint8Array): ServiceTierByFamily | undefined
  * entries, preserving offset-based memory behavior for large sessions.
  */
 export interface ParseSessionResult {
-	stats: MessageStats[];
+	stats: MessageStatsInput[];
 	userStats: UserMessageStats[];
 	userLinks: UserMessageLink[];
 	toolCalls: ToolCallStats[];
@@ -428,7 +538,7 @@ export async function parseSessionFile(sessionPath: string, fromOffset = 0): Pro
 
 	const folder = extractFolderFromPath(sessionPath);
 	const agentType = classifyAgentType(sessionPath);
-	const stats: MessageStats[] = [];
+	const stats: MessageStatsInput[] = [];
 	const userStats: UserMessageStats[] = [];
 	const userLinks: UserMessageLink[] = [];
 	const toolCalls: ToolCallStats[] = [];
@@ -526,6 +636,9 @@ export async function listAllSessionFiles(): Promise<string[]> {
 	const allFiles: string[] = [];
 
 	for (const folder of folders) {
+		// Skip at enumeration: temp-cwd project folders re-create their
+		// transcripts on every test run and must never reach the parser or DB.
+		if (isTempProjectFolder(path.basename(folder))) continue;
 		const files = await listSessionFiles(folder);
 		allFiles.push(...files);
 	}

package/src/server.ts

@@ -180,7 +180,7 @@ const ensureClientBuild = async () => {
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>AI Usage Statistics</title>
+    <title>Zeta Stats</title>
     <link rel="stylesheet" href="styles.css">
 </head>
 <body>

package/src/shared-types.ts

@@ -484,6 +484,8 @@ export interface SessionSummary {
 	subagents: number;
 	totalTokens: number;
 	costTotal: number;
+	/** Requests whose zero cost is unknown spend (scheduled card, no timestamp). */
+	unpricedRequests: number;
 	models: string[];
 }
 
@@ -569,6 +571,8 @@ export interface TraceSummary {
 	subagents: number;
 	totalTokens: number;
 	costTotal: number;
+	/** Model requests whose zero cost is unknown spend, not free usage. */
+	unpricedRequests: number;
 	/** Sorted totalMs desc. */
 	toolStats: TraceToolStat[];
 }

package/src/trace.ts

@@ -11,9 +11,10 @@
 
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { getBundledModel, type GeneratedProvider } from "@linxiraos/pi-catalog/models";
 import { getSessionsDir, isEnoent } from "@linxiraos/pi-utils";
-import { getSessionRollups, getToolCallCountsBySession } from "./db";
-import { extractFolderFromPath, parseAllSessionEntries } from "./parser";
+import { getSessionRollups, getToolCallCountsBySession, isScheduledCatalogModel } from "./db";
+import { extractFolderFromPath, parseAllSessionEntries, resolveUsageTotal } from "./parser";
 import type {
 	SessionEntry,
 	SessionSummary,
@@ -32,7 +33,7 @@ export class TracePathError extends Error {}
  * span assembly changes so browsers don't revalidate stale cached bodies
  * against an unchanged transcript mtime.
  */
-export const TRACE_ETAG_VERSION = 2;
+export const TRACE_ETAG_VERSION = 3;
 
 const MAX_TRACK_DEPTH = 6;
 const LABEL_MAX = 80;
@@ -84,7 +85,15 @@ interface MessageView {
 	completedAt?: number;
 	duration?: number;
 	ttft?: number;
-	usage?: { totalTokens?: number; cost?: { total?: number } };
+	usage?: {
+		input?: unknown;
+		output?: unknown;
+		cacheRead?: unknown;
+		cacheWrite?: unknown;
+		totalTokens?: unknown;
+		orchestration?: { input?: unknown; output?: unknown; cacheRead?: unknown };
+		cost?: { total?: unknown };
+	};
 	model?: string;
 	provider?: string;
 	stopReason?: string;
@@ -115,13 +124,14 @@ interface TaskResultFact {
 	resultEntryId: string;
 	toolSpanEnd: number;
 }
-
 /** Everything one transcript contributes before cross-track assembly. */
 interface TrackScan {
 	track: TraceTrack;
 	taskResults: TaskResultFact[];
 	requests: number;
 	toolCalls: number;
+	/** Model requests whose zero cost is unknown spend (mirrors db's unpriced predicate). */
+	unpricedRequests: number;
 	cwd: string | null;
 	title: string | null;
 	/** Session-header envelope timestamp (ms), for spanless traces. */
@@ -284,6 +294,7 @@ function scanTranscript(
 	let initModel: string | null = null;
 	let firstAssistantModel: string | null = null;
 	let requests = 0;
+	let unpricedRequests = 0;
 	let lastChainTs = 0;
 
 	// Title slot and session header may sit outside the id chain — scan all entries.
@@ -358,6 +369,32 @@ function scanTranscript(
 
 		if (msg.role === "assistant") {
 			requests++;
+			// Mirror the db's unpriced predicate so the trace headline agrees
+			// with Costs/Recent Requests: a zero that is unknown spend, not free.
+			// Counted before the span-timing `continue` below so a fully
+			// dateless entry still surfaces as N/A rather than vanishing.
+			// Derive a missing total from the buckets via the shared ingest
+			// helper, so a legacy entry with tokens but no total still
+			// classifies as unpriced.
+			const totalTokens = resolveUsageTotal(msg.usage);
+			const costObj = msg.usage?.cost;
+			const costTotal =
+				typeof costObj?.total === "number" && Number.isFinite(costObj.total) ? costObj.total : undefined;
+			if (totalTokens > 0 && (costTotal === undefined || costTotal === 0)) {
+				const provider = typeof msg.provider === "string" ? msg.provider : "";
+				const model = typeof msg.model === "string" ? msg.model : "";
+				if (provider === "xai-oauth" && model) {
+					const ref = getBundledModel("xai" as GeneratedProvider, model)?.cost;
+					if (!(ref && (ref.input !== 0 || ref.output !== 0 || ref.cacheRead !== 0 || ref.cacheWrite !== 0))) {
+						unpricedRequests++;
+					}
+				} else if (costObj == null && provider && model) {
+					const hasTimestamp =
+						(typeof msg.timestamp === "number" && Number.isFinite(msg.timestamp) && msg.timestamp > 0) ||
+						envelopeTs !== undefined;
+					if (!hasTimestamp && isScheduledCatalogModel(provider, model)) unpricedRequests++;
+				}
+			}
 			let start = typeof msg.timestamp === "number" && Number.isFinite(msg.timestamp) ? msg.timestamp : undefined;
 			let end =
 				typeof msg.completedAt === "number" && Number.isFinite(msg.completedAt)
@@ -386,12 +423,12 @@ function scanTranscript(
 			if (detail) span.detail = detail;
 			if (entry.id) span.entryId = entry.id;
 			if (typeof msg.model === "string") span.model = msg.model;
-			if (typeof msg.usage?.totalTokens === "number") span.tokens = msg.usage.totalTokens;
-			if (typeof msg.usage?.cost?.total === "number") span.cost = msg.usage.cost.total;
+			if (totalTokens > 0) span.tokens = totalTokens;
+
+			if (costTotal !== undefined) span.cost = costTotal;
 			if (typeof msg.ttft === "number") span.ttft = msg.ttft;
 			if (msg.stopReason === "error" || msg.errorMessage) span.isError = true;
 			spans.push(span);
-
 			if (Array.isArray(msg.content)) {
 				for (const block of msg.content) {
 					if (!block || typeof block !== "object" || !("type" in block) || block.type !== "toolCall") continue;
@@ -572,6 +609,7 @@ function scanTranscript(
 		taskResults,
 		requests,
 		toolCalls: pendingTools.length,
+		unpricedRequests,
 		cwd,
 		title: slotTitle ?? headerTitle,
 		headerTs,
@@ -722,11 +760,13 @@ export async function buildSessionTrace(fileParam: string): Promise<SessionTrace
 	let requests = 0;
 	let totalTokens = 0;
 	let costTotal = 0;
+	let unpricedRequests = 0;
 	const toolStats = new Map<string, TraceToolStat>();
 
 	for (const scan of scans) {
 		requests += scan.requests;
 		toolCalls += scan.toolCalls;
+		unpricedRequests += scan.unpricedRequests;
 		for (const span of scan.track.spans) {
 			intervals.push([span.start, span.end]);
 			if (startedAt === undefined || span.start < startedAt) startedAt = span.start;
@@ -779,6 +819,7 @@ export async function buildSessionTrace(fileParam: string): Promise<SessionTrace
 		subagents: tracks.length - 1,
 		totalTokens,
 		costTotal,
+		unpricedRequests,
 		toolStats: [...toolStats.values()].sort((a, b) => b.totalMs - a.totalMs),
 	};
 
@@ -936,6 +977,7 @@ export async function listSessionSummaries(limit = 100, q?: string): Promise<Ses
 				subagents: 0,
 				totalTokens: 0,
 				costTotal: 0,
+				unpricedRequests: 0,
 				models: [],
 				modelSet: new Set(),
 			};
@@ -948,6 +990,7 @@ export async function listSessionSummaries(limit = 100, q?: string): Promise<Ses
 		if (row.endedAt > fold.endedAt) fold.endedAt = row.endedAt;
 		fold.totalTokens += row.totalTokens ?? 0;
 		fold.costTotal += row.costTotal ?? 0;
+		fold.unpricedRequests += row.unpricedRequests ?? 0;
 		if (row.models) {
 			for (const model of row.models.split(",")) {
 				if (model) fold.modelSet.add(model);
@@ -975,6 +1018,7 @@ export async function listSessionSummaries(limit = 100, q?: string): Promise<Ses
 			subagents: 0,
 			totalTokens: 0,
 			costTotal: 0,
+			unpricedRequests: 0,
 			models: [],
 			modelSet: new Set(),
 		});

package/src/types.ts

@@ -35,6 +35,26 @@ export interface MessageStats {
 	usage: Usage;
 	/** Which agent produced this message (main agent, task subagent, advisor) */
 	agentType: AgentType;
+	/**
+	 * Ingest refused to price this request: a scheduled (time-based) card with no
+	 * recoverable request timestamp, so `usage.cost.total` of 0 is unknown spend
+	 * rather than a free request. Always written by `rowToMessageStats`; optional
+	 * only because session fixtures that stand in for ingest input are typed as
+	 * `MessageStats` too.
+	 */
+	costUnpriced?: boolean;
+}
+
+/**
+ * Session-recorded token usage before pricing: counters are coerced to numbers
+ * because their columns are NOT NULL, but `cost` is only present when the
+ * session entry actually recorded one. Absence is meaningful — `resolveStoredCost`
+ * estimates a request with no recorded price, whereas a recorded zero is a real
+ * charge that scheduled cards freeze. `costUnpriced` is omitted because it is a
+ * decision of the ingest path, not something the parser or a caller supplies.
+ */
+export interface MessageStatsInput extends Omit<MessageStats, "usage" | "costUnpriced"> {
+	usage: Omit<Usage, "cost"> & { cost?: Partial<Usage["cost"]> };
 }
 
 /**