@gajae-code/stats 0.17.2 → 0.17.5

package/README.md

@@ -8,6 +8,7 @@ Local observability dashboard for AI usage statistics.
 - **SQLite aggregation**: Efficient stats storage and querying using `bun:sqlite`
 - **Web dashboard**: Real-time metrics visualization with Chart.js
 - **Incremental sync**: Only processes new/modified log entries
+- **Role usage breakdown**: `gjc stats --summary` and JSON report usage by default, executor, planner, architect, and critic; custom roles and legacy sessions without identity metadata are grouped as `other` or `unknown`
 
 ## Metrics Tracked
 
@@ -50,6 +51,7 @@ const { processed, files } = await syncAllSessions();
 const stats = await getDashboardStats();
 console.log(stats.overall.totalCost);
 console.log(stats.byModel[0].avgTokensPerSecond);
+console.log(stats.byAgent.find(agent => agent.agent === "executor")?.totalCost);
 ```
 
 ## API Endpoints

package/dist/types/client/types.d.ts

@@ -11,7 +11,7 @@
  *   - `TimeRange`, `OverviewStats`, `ModelDashboardStats`,
  *     `CostDashboardStats` are UI-only view shapes the server never produces.
  */
-import type { AggregatedStats, CostTimeSeriesPoint, ModelPerformancePoint, ModelStats, ModelTimeSeriesPoint, TimeSeriesPoint } from "../shared-types";
+import type { AgentRole, AggregatedStats, CostTimeSeriesPoint, ModelPerformancePoint, ModelStats, ModelTimeSeriesPoint, TimeSeriesPoint } from "../shared-types";
 export * from "../shared-types";
 export interface Usage {
     input: number;
@@ -33,6 +33,7 @@ export interface MessageStats {
     sessionFile: string;
     entryId: string;
     folder: string;
+    agent: AgentRole;
     model: string;
     provider: string;
     api: string;

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 { AgentStats, 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.
  */
@@ -31,6 +31,10 @@ export declare function getStatsByModel(cutoff?: number): ModelStats[];
  * Get stats grouped by folder.
  */
 export declare function getStatsByFolder(cutoff?: number): FolderStats[];
+/**
+ * Get stats grouped by the persisted agent role.
+ */
+export declare function getStatsByAgent(cutoff?: number): AgentStats[];
 /**
  * Get time series data.
  */

package/dist/types/index.d.ts

@@ -2,4 +2,4 @@
 export { getDashboardStats, getTotalMessageCount, type SyncOptions, type SyncProgress, smokeTestSyncWorker, syncAllSessions, } from "./aggregator";
 export { closeDb } from "./db";
 export { startServer } from "./server";
-export type { AggregatedStats, DashboardStats, FolderStats, MessageStats, ModelPerformancePoint, ModelStats, ModelTimeSeriesPoint, TimeSeriesPoint, } from "./types";
+export type { AgentRole, AgentStats, AggregatedStats, DashboardStats, FolderStats, MessageStats, ModelPerformancePoint, ModelStats, ModelTimeSeriesPoint, TimeSeriesPoint, } from "./types";

package/dist/types/parser.d.ts

@@ -1,22 +1,18 @@
-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.
  *
- * Service-tier carry-over: `currentServiceTier` is a session-scoped piece of
- * state derived from `service_tier_change` entries that affects whether
- * subsequent OpenAI assistant replies count as premium requests. Incremental
- * syncs that resume past the most-recent tier change would otherwise lose
- * that state and silently record `premiumRequests = 0` for priority traffic
- * (the coding-agent stopped folding the tier into `usage.premiumRequests`
- * after 13f59162e — the parser is now the sole source of truth). When
- * `fromOffset > 0` we therefore scan the bytes preceding `fromOffset`
- * for the latest service-tier value before parsing the unprocessed tail.
- * The scan only keeps the current tier and does not materialize prefix
- * entries, preserving offset-based memory behavior for large sessions.
+ * Service-tier and agent-role carry-over are session-scoped state. Incremental
+ * syncs that resume after either metadata entry would otherwise lose the
+ * context needed to attribute priority requests and assistant usage. When
+ * `fromOffset > 0`, scan the prefix for the current values before parsing the
+ * unprocessed tail. The scan keeps only current metadata and does not
+ * materialize prefix 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/shared-types.d.ts

@@ -5,7 +5,7 @@
  * without dragging server dependencies into its bundle.
  */
 /**
- * Aggregated stats for a model or folder.
+ * Aggregated stats for a model, folder, or agent role.
  */
 export interface AggregatedStats {
     /** Total number of requests */
@@ -53,6 +53,12 @@ export interface ModelStats extends AggregatedStats {
 export interface FolderStats extends AggregatedStats {
     folder: string;
 }
+/** Agent role attributed from the session transcript. */
+export type AgentRole = "default" | "executor" | "planner" | "architect" | "critic" | "other" | "unknown";
+/** Stats grouped by the agent role that produced the assistant request. */
+export interface AgentStats extends AggregatedStats {
+    agent: AgentRole;
+}
 /**
  * Time series data point.
  */
@@ -125,6 +131,7 @@ export interface DashboardStats {
     overall: AggregatedStats;
     byModel: ModelStats[];
     byFolder: FolderStats[];
+    byAgent: AgentStats[];
     timeSeries: TimeSeriesPoint[];
     modelSeries: ModelTimeSeriesPoint[];
     modelPerformanceSeries: ModelPerformancePoint[];

package/dist/types/types.d.ts

@@ -1,4 +1,5 @@
 import type { AssistantMessage, ServiceTier, StopReason, Usage } from "@gajae-code/ai";
+import type { AgentRole } from "./shared-types";
 export * from "./shared-types";
 /**
  * Extracted stats from an assistant message.
@@ -12,6 +13,8 @@ export interface MessageStats {
     entryId: string;
     /** Folder/project path (extracted from session filename) */
     folder: string;
+    /** Agent role inferred from the persisted session identity. */
+    agent: AgentRole;
     /** Model ID */
     model: string;
     /** Provider name */
@@ -25,7 +28,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 +54,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.5",
 	"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.5",
+		"@gajae-code/utils": "0.17.5",
 		"@tailwindcss/node": "^4.2.4",
 		"chart.js": "^4.5.1",
 		"date-fns": "^4.1.0",

package/src/aggregator.ts

@@ -13,6 +13,7 @@ import {
 	getModelPerformanceSeries,
 	getModelTimeSeries,
 	getOverallStats,
+	getStatsByAgent,
 	getStatsByFolder,
 	getStatsByModel,
 	getTimeSeries,
@@ -367,6 +368,7 @@ export async function getDashboardStats(range?: string | null): Promise<Dashboar
 		overall: getOverallStats(cutoff ?? undefined),
 		byModel: getStatsByModel(cutoff ?? undefined),
 		byFolder: getStatsByFolder(cutoff ?? undefined),
+		byAgent: getStatsByAgent(cutoff ?? undefined),
 		timeSeries: getTimeSeries(timeSeriesHours, cutoff, timeSeriesBucketMs),
 		modelSeries: getModelTimeSeries(modelSeriesDays, cutoff, modelSeriesBucketMs),
 		modelPerformanceSeries: getModelPerformanceSeries(modelPerformanceDays, cutoff, modelPerformanceBucketMs),

package/src/client/types.ts

@@ -13,6 +13,7 @@
  */
 
 import type {
+	AgentRole,
 	AggregatedStats,
 	CostTimeSeriesPoint,
 	ModelPerformancePoint,
@@ -44,6 +45,7 @@ export interface MessageStats {
 	sessionFile: string;
 	entryId: string;
 	folder: string;
+	agent: AgentRole;
 	model: string;
 	provider: string;
 	api: string;

package/src/db.ts

@@ -3,6 +3,8 @@ import * as fs from "node:fs/promises";
 import { type GeneratedProvider, getBundledModel, type Usage } from "@gajae-code/ai";
 import { getConfigRootDir, getStatsDbPath } from "@gajae-code/utils";
 import type {
+	AgentRole,
+	AgentStats,
 	AggregatedStats,
 	BehaviorModelStats,
 	BehaviorOverallStats,
@@ -13,6 +15,7 @@ import type {
 	ModelPerformancePoint,
 	ModelStats,
 	ModelTimeSeriesPoint,
+	ParsedMessageStats,
 	TimeSeriesPoint,
 	UserMessageLink,
 	UserMessageStats,
@@ -32,10 +35,28 @@ interface CostBackfillRow {
 	cache_write_tokens: number;
 }
 
+interface AgentStatsRow {
+	agent: AgentRole;
+	total_requests: number;
+	failed_requests: number;
+	total_input_tokens: number | null;
+	total_output_tokens: number | null;
+	total_cache_read_tokens: number | null;
+	total_cache_write_tokens: number | null;
+	total_premium_requests: number | null;
+	total_cost: number | null;
+	avg_duration: number | null;
+	avg_ttft: number | null;
+	avg_tokens_per_second: number | null;
+	first_timestamp: number | null;
+	last_timestamp: number | null;
+}
+
 let db: Database | null = null;
 
 const BACKFILL_COMPLETE = "complete";
 const BACKFILL_PENDING = "pending";
+const AGENT_ROLE_BACKFILL_KEY = "agent_role_attribution_v1";
 const USER_MESSAGES_BACKFILL_KEY = "user_messages_v5";
 const USER_MESSAGE_LINKS_REPAIR_KEY = "user_message_links_v1";
 const PRIORITY_PREMIUM_REQUESTS_BACKFILL_KEY = "premium_requests_priority_v1";
@@ -60,6 +81,7 @@ export async function initDb(): Promise<Database> {
 			id INTEGER PRIMARY KEY AUTOINCREMENT,
 			session_file TEXT NOT NULL,
 			entry_id TEXT NOT NULL,
+			agent TEXT NOT NULL DEFAULT 'unknown',
 			folder TEXT NOT NULL,
 			model TEXT NOT NULL,
 			provider TEXT NOT NULL,
@@ -129,6 +151,10 @@ export async function initDb(): Promise<Database> {
 	if (!messageColumns.some(column => column.name === "premium_requests")) {
 		db.exec("ALTER TABLE messages ADD COLUMN premium_requests REAL NOT NULL DEFAULT 0");
 	}
+	if (!messageColumns.some(column => column.name === "agent")) {
+		db.exec("ALTER TABLE messages ADD COLUMN agent TEXT NOT NULL DEFAULT 'unknown'");
+	}
+	db.exec("CREATE INDEX IF NOT EXISTS idx_messages_agent ON messages(agent)");
 	db.exec("UPDATE messages SET premium_requests = 0 WHERE premium_requests IS NULL");
 	// Each behavior-metric bump invalidates previously-ingested rows. We detect
 	// the stale schema by column name and drop the table; `IF NOT EXISTS` above
@@ -178,6 +204,7 @@ export async function initDb(): Promise<Database> {
 			CREATE INDEX IF NOT EXISTS idx_user_messages_timestamp_model ON user_messages(timestamp, model, provider);
 		`);
 	}
+	backfillAgentRoleAttribution(db);
 	backfillUserMessages(db);
 	repairUserMessageLinks(db);
 	backfillPriorityPremiumRequests(db);
@@ -228,12 +255,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 +289,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,24 +347,22 @@ 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
-	// before priority service-tier traffic was counted as premium. The guard
-	// `WHERE messages.premium_requests < excluded.premium_requests` keeps every
-	// other column immutable and never demotes an existing count (e.g. when a
-	// later parse drops back to 0 for the same row).
+	// Re-syncs repair role attribution for existing rows and only promote
+	// `premium_requests`; every other message field stays immutable.
 	const stmt = db.prepare(`
 		INSERT INTO messages (
-			session_file, entry_id, folder, model, provider, api, timestamp,
+			session_file, entry_id, agent, folder, model, provider, api, timestamp,
 			duration, ttft, stop_reason, error_message,
 			input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, total_tokens, premium_requests,
 			cost_input, cost_output, cost_cache_read, cost_cache_write, cost_total
-		) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 		ON CONFLICT(session_file, entry_id) DO UPDATE SET
-			premium_requests = excluded.premium_requests
-		WHERE messages.premium_requests < excluded.premium_requests
+			agent = excluded.agent,
+			premium_requests = MAX(messages.premium_requests, excluded.premium_requests)
+		WHERE messages.agent <> excluded.agent OR messages.premium_requests < excluded.premium_requests
 	`);
 
 	let inserted = 0;
@@ -326,6 +372,7 @@ export function insertMessageStats(stats: MessageStats[]): number {
 			const result = stmt.run(
 				s.sessionFile,
 				s.entryId,
+				s.agent,
 				s.folder,
 				s.model,
 				s.provider,
@@ -514,6 +561,41 @@ export function getStatsByFolder(cutoff?: number): FolderStats[] {
 	}));
 }
 
+/**
+ * Get stats grouped by the persisted agent role.
+ */
+export function getStatsByAgent(cutoff?: number): AgentStats[] {
+	if (!db) return [];
+
+	const hasCutoff = cutoff !== undefined && cutoff > 0;
+	const stmt = db.prepare(`
+		SELECT
+			agent,
+			COUNT(*) as total_requests,
+			SUM(CASE WHEN stop_reason = 'error' THEN 1 ELSE 0 END) as failed_requests,
+			SUM(input_tokens) as total_input_tokens,
+			SUM(output_tokens) as total_output_tokens,
+			SUM(cache_read_tokens) as total_cache_read_tokens,
+			SUM(cache_write_tokens) as total_cache_write_tokens,
+			SUM(premium_requests) as total_premium_requests,
+			SUM(cost_total) as total_cost,
+			AVG(duration) as avg_duration,
+			AVG(ttft) as avg_ttft,
+			AVG(CASE WHEN duration > 0 THEN output_tokens * 1000.0 / duration ELSE NULL END) as avg_tokens_per_second,
+			MIN(timestamp) as first_timestamp,
+			MAX(timestamp) as last_timestamp
+		FROM messages
+		${hasCutoff ? "WHERE timestamp >= ?" : ""}
+		GROUP BY agent
+		ORDER BY total_requests DESC, agent ASC
+	`);
+	const rows = (hasCutoff ? stmt.all(cutoff) : stmt.all()) as AgentStatsRow[];
+	return rows.map(row => ({
+		agent: row.agent,
+		...buildAggregatedStats([row]),
+	}));
+}
+
 /**
  * Get time series data.
  */
@@ -658,6 +740,7 @@ function rowToMessageStats(row: any): MessageStats {
 		sessionFile: row.session_file,
 		entryId: row.entry_id,
 		folder: row.folder,
+		agent: row.agent as AgentRole,
 		model: row.model,
 		provider: row.provider,
 		api: row.api,
@@ -807,6 +890,19 @@ function repairUserMessageLinks(database: Database): void {
 		.run(USER_MESSAGE_LINKS_REPAIR_KEY, BACKFILL_PENDING);
 }
 
+/** Reparse existing sessions so stored assistant rows gain role attribution. */
+function backfillAgentRoleAttribution(database: Database): void {
+	const row = database.prepare("SELECT value FROM meta WHERE key = ?").get(AGENT_ROLE_BACKFILL_KEY) as
+		| { value: string }
+		| undefined;
+	if (!shouldResetBackfill(row?.value)) return;
+
+	database.exec("DELETE FROM file_offsets");
+	database
+		.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)")
+		.run(AGENT_ROLE_BACKFILL_KEY, BACKFILL_PENDING);
+}
+
 /**
  * One-shot wipe of `file_offsets` so the next sync re-parses every session
  * and re-derives `premium_requests` from recorded `service_tier_change`

package/src/index.ts

@@ -17,6 +17,8 @@ export {
 export { closeDb } from "./db";
 export { startServer } from "./server";
 export type {
+	AgentRole,
+	AgentStats,
 	AggregatedStats,
 	DashboardStats,
 	FolderStats,
@@ -45,7 +47,7 @@ function normalizePremiumRequests(n: number): number {
  */
 async function printStats(): Promise<void> {
 	const stats = await getDashboardStats();
-	const { overall, byModel, byFolder } = stats;
+	const { overall, byModel, byFolder, byAgent } = stats;
 
 	console.log("\n=== AI Usage Statistics ===\n");
 
@@ -73,6 +75,15 @@ async function printStats(): Promise<void> {
 		}
 	}
 
+	if (byAgent.length > 0) {
+		console.log("\nBy Agent Role:");
+		for (const agent of byAgent) {
+			console.log(
+				`  ${agent.agent}: ${formatNumber(agent.totalRequests)} reqs, ${formatNumber(agent.totalInputTokens)} input / ${formatNumber(agent.totalOutputTokens)} output, ${formatPercent(agent.cacheRate)} cache, ${formatCost(agent.totalCost)}`,
+			);
+		}
+	}
+
 	if (byFolder.length > 0) {
 		console.log("\nBy Folder:");
 		for (const f of byFolder.slice(0, 10)) {

package/src/parser.ts

@@ -1,9 +1,11 @@
 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,
+	AgentRole,
+	ParsedMessageStats,
+	SessionAssistantMessage,
 	SessionEntry,
 	SessionMessageEntry,
 	SessionServiceTierChangeEntry,
@@ -25,34 +27,70 @@ 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";
+}
+
+function inferAgentRoleFromPath(sessionPath: string): AgentRole {
+	const relativePath = path.relative(getSessionsDir(), sessionPath);
+	const pathDepth = relativePath.split(path.sep).filter(Boolean).length;
+	// Root transcripts live directly under a project directory. Task transcripts
+	// live in a directory nested beneath their parent transcript, so legacy child
+	// sessions without a persisted identity must not be mistaken for `default`.
+	return pathDepth <= 2 ? "default" : "unknown";
+}
+
+function agentRoleFromSessionEntry(entry: unknown): AgentRole | undefined {
+	if (!isObject(entry) || entry.type !== "configured_model_chain") return undefined;
+	if (entry.role !== "default" || entry.origin !== "subagent") return undefined;
+	if (!isNonemptyString(entry.identity)) return "unknown";
+	switch (entry.identity) {
+		case "executor":
+		case "planner":
+		case "architect":
+		case "critic":
+			return entry.identity;
+		default:
+			return "other";
+	}
 }
 
 /**
@@ -107,9 +145,22 @@ function extractStats(
 	folder: string,
 	entry: SessionMessageEntry,
 	currentServiceTier: ServiceTier | undefined,
-): MessageStats | null {
-	const msg = entry.message as AssistantMessage;
+	agentRole: AgentRole,
+): 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,22 +168,25 @@ 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,
 		entryId: entry.id,
 		folder,
+		agent: agentRole,
 		model: msg.model,
 		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,
 	};
 }
@@ -164,14 +218,20 @@ function parseSessionEntriesLenient(bytes: Uint8Array): { entries: SessionEntry[
 	return { entries, read: cursor };
 }
 
-function scanLastServiceTier(bytes: Uint8Array): ServiceTier | undefined {
+function scanSessionMetadata(
+	bytes: Uint8Array,
+	initialAgentRole: AgentRole,
+): { serviceTier: ServiceTier | undefined; agentRole: AgentRole } {
 	let cursor = 0;
 	let currentServiceTier: ServiceTier | undefined;
+	let currentAgentRole = initialAgentRole;
 
 	while (cursor < bytes.length) {
 		const { values, error, read, done } = Bun.JSONL.parseChunk(bytes, cursor, bytes.length);
 		for (const value of values as SessionEntry[]) {
 			if (isServiceTierChange(value)) currentServiceTier = value.serviceTier ?? undefined;
+			const agentRole = agentRoleFromSessionEntry(value);
+			if (agentRole !== undefined) currentAgentRole = agentRole;
 		}
 
 		if (error) {
@@ -186,26 +246,22 @@ function scanLastServiceTier(bytes: Uint8Array): ServiceTier | undefined {
 		if (done) break;
 	}
 
-	return currentServiceTier;
+	return { serviceTier: currentServiceTier, agentRole: currentAgentRole };
 }
 /**
  * Parse a session file and extract all assistant message stats.
  * Uses incremental reading with offset tracking.
  *
- * Service-tier carry-over: `currentServiceTier` is a session-scoped piece of
- * state derived from `service_tier_change` entries that affects whether
- * subsequent OpenAI assistant replies count as premium requests. Incremental
- * syncs that resume past the most-recent tier change would otherwise lose
- * that state and silently record `premiumRequests = 0` for priority traffic
- * (the coding-agent stopped folding the tier into `usage.premiumRequests`
- * after 13f59162e — the parser is now the sole source of truth). When
- * `fromOffset > 0` we therefore scan the bytes preceding `fromOffset`
- * for the latest service-tier value before parsing the unprocessed tail.
- * The scan only keeps the current tier and does not materialize prefix
- * entries, preserving offset-based memory behavior for large sessions.
+ * Service-tier and agent-role carry-over are session-scoped state. Incremental
+ * syncs that resume after either metadata entry would otherwise lose the
+ * context needed to attribute priority requests and assistant usage. When
+ * `fromOffset > 0`, scan the prefix for the current values before parsing the
+ * unprocessed tail. The scan keeps only current metadata and does not
+ * materialize prefix entries, preserving offset-based memory behavior for
+ * large sessions.
  */
 export interface ParseSessionResult {
-	stats: MessageStats[];
+	stats: ParsedMessageStats[];
 	userStats: UserMessageStats[];
 	userLinks: UserMessageLink[];
 	newOffset: number;
@@ -220,22 +276,31 @@ 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>();
 	const start = Math.max(0, Math.min(fromOffset, bytes.length));
+	const initialAgentRole = inferAgentRoleFromPath(sessionPath);
 	const unprocessed = bytes.subarray(start);
 	const { entries, read } = parseSessionEntriesLenient(unprocessed);
 	let currentServiceTier: ServiceTier | undefined;
+	let currentAgentRole = initialAgentRole;
 	if (start > 0) {
-		currentServiceTier = scanLastServiceTier(bytes.subarray(0, start));
+		const metadata = scanSessionMetadata(bytes.subarray(0, start), initialAgentRole);
+		currentServiceTier = metadata.serviceTier;
+		currentAgentRole = metadata.agentRole;
 	}
 	for (const entry of entries) {
 		if (isServiceTierChange(entry)) {
 			currentServiceTier = entry.serviceTier ?? undefined;
 			continue;
 		}
+		const agentRole = agentRoleFromSessionEntry(entry);
+		if (agentRole !== undefined) {
+			currentAgentRole = agentRole;
+			continue;
+		}
 		if (isUserMessage(entry)) {
 			const userMsg = extractUserStats(sessionPath, folder, entry);
 			if (userMsg) {
@@ -245,13 +310,13 @@ export async function parseSessionFile(sessionPath: string, fromOffset = 0): Pro
 			continue;
 		}
 		if (isAssistantMessage(entry)) {
-			const msgStats = extractStats(sessionPath, folder, entry, currentServiceTier);
+			const msgStats = extractStats(sessionPath, folder, entry, currentServiceTier, currentAgentRole);
 			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 +391,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/shared-types.ts

@@ -6,7 +6,7 @@
  */
 
 /**
- * Aggregated stats for a model or folder.
+ * Aggregated stats for a model, folder, or agent role.
  */
 export interface AggregatedStats {
 	/** Total number of requests */
@@ -57,6 +57,14 @@ export interface FolderStats extends AggregatedStats {
 	folder: string;
 }
 
+/** Agent role attributed from the session transcript. */
+export type AgentRole = "default" | "executor" | "planner" | "architect" | "critic" | "other" | "unknown";
+
+/** Stats grouped by the agent role that produced the assistant request. */
+export interface AgentStats extends AggregatedStats {
+	agent: AgentRole;
+}
+
 /**
  * Time series data point.
  */
@@ -133,6 +141,7 @@ export interface DashboardStats {
 	overall: AggregatedStats;
 	byModel: ModelStats[];
 	byFolder: FolderStats[];
+	byAgent: AgentStats[];
 	timeSeries: TimeSeriesPoint[];
 	modelSeries: ModelTimeSeriesPoint[];
 	modelPerformanceSeries: ModelPerformancePoint[];

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { AssistantMessage, ServiceTier, StopReason, Usage } from "@gajae-code/ai";
+import type { AgentRole } from "./shared-types";
 
 export * from "./shared-types";
 
@@ -14,6 +15,8 @@ export interface MessageStats {
 	entryId: string;
 	/** Folder/project path (extracted from session filename) */
 	folder: string;
+	/** Agent role inferred from the persisted session identity. */
+	agent: AgentRole;
 	/** Model ID */
 	model: string;
 	/** Provider name */
@@ -27,7 +30,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 +59,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 {