@gajae-code/stats 0.17.4 → 0.17.6

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, ParsedMessageStats, 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.
  */
@@ -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

@@ -3,17 +3,13 @@ import type { ParsedMessageStats, SessionEntry, UserMessageLink, UserMessageStat
  * 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: ParsedMessageStats[];

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 */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/stats",
-	"version": "0.17.4",
+	"version": "0.17.6",
 	"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.4",
-		"@gajae-code/utils": "0.17.4",
+		"@gajae-code/ai": "0.17.6",
+		"@gajae-code/utils": "0.17.6",
 		"@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,
@@ -33,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";
@@ -61,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,
@@ -130,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
@@ -179,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);
@@ -324,21 +350,19 @@ export function setFileOffset(sessionFile: string, offset: number, lastModified:
 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;
@@ -348,6 +372,7 @@ export function insertMessageStats(stats: ParsedMessageStats[]): number {
 			const result = stmt.run(
 				s.sessionFile,
 				s.entryId,
+				s.agent,
 				s.folder,
 				s.model,
 				s.provider,
@@ -536,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.
  */
@@ -680,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,
@@ -829,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

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import { getPriorityPremiumRequests, type ServiceTier } from "@gajae-code/ai";
 import { getSessionsDir, isEnoent } from "@gajae-code/utils";
 import type {
+	AgentRole,
 	ParsedMessageStats,
 	SessionAssistantMessage,
 	SessionEntry,
@@ -68,6 +69,30 @@ function isServiceTierChange(entry: SessionEntry): entry is SessionServiceTierCh
 	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";
+	}
+}
+
 /**
  * Extract plain text from a user message content payload.
  */
@@ -120,6 +145,7 @@ function extractStats(
 	folder: string,
 	entry: SessionMessageEntry,
 	currentServiceTier: ServiceTier | undefined,
+	agentRole: AgentRole,
 ): ParsedMessageStats | null {
 	const msg = entry.message as SessionAssistantMessage;
 	if (msg?.role !== "assistant") return null;
@@ -150,6 +176,7 @@ function extractStats(
 		sessionFile,
 		entryId: entry.id,
 		folder,
+		agent: agentRole,
 		model: msg.model,
 		provider: msg.provider,
 		api: msg.api,
@@ -191,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) {
@@ -213,23 +246,19 @@ 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: ParsedMessageStats[];
@@ -252,17 +281,26 @@ export async function parseSessionFile(sessionPath: string, fromOffset = 0): Pro
 	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) {
@@ -272,7 +310,7 @@ 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;

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 */