@oh-my-pi/omp-stats 16.3.0 → 16.3.2

package/src/db.ts

@@ -19,6 +19,11 @@ import type {
 	ModelStats,
 	ModelTimeSeriesPoint,
 	TimeSeriesPoint,
+	ToolCallStats,
+	ToolModelStats,
+	ToolResultLink,
+	ToolTimeSeriesPoint,
+	ToolUsageStats,
 	UserMessageLink,
 	UserMessageStats,
 } from "./types";
@@ -46,6 +51,7 @@ const USER_MESSAGE_LINKS_REPAIR_KEY = "user_message_links_v1";
 const PRIORITY_PREMIUM_REQUESTS_BACKFILL_KEY = "premium_requests_priority_v1";
 const AGENT_TYPE_BACKFILL_KEY = "agent_type_v1";
 const FORK_DEDUPE_KEY = "fork_dedupe_v1";
+const TOOL_CALLS_BACKFILL_KEY = "tool_calls_v1";
 function shouldResetBackfill(value: string | undefined): boolean {
 	return value !== BACKFILL_COMPLETE && value !== BACKFILL_PENDING;
 }
@@ -135,6 +141,27 @@ export async function initDb(): Promise<Database> {
 		CREATE INDEX IF NOT EXISTS idx_user_messages_timestamp ON user_messages(timestamp);
 		CREATE INDEX IF NOT EXISTS idx_user_messages_timestamp_model ON user_messages(timestamp, model, provider);
 
+		CREATE TABLE IF NOT EXISTS tool_calls (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			session_file TEXT NOT NULL,
+			entry_id TEXT NOT NULL,
+			tool_call_id TEXT NOT NULL,
+			folder TEXT NOT NULL,
+			tool_name TEXT NOT NULL,
+			model TEXT NOT NULL,
+			provider TEXT NOT NULL,
+			timestamp INTEGER NOT NULL,
+			agent_type TEXT NOT NULL DEFAULT 'main',
+			calls_in_turn INTEGER NOT NULL DEFAULT 1,
+			args_chars INTEGER NOT NULL DEFAULT 0,
+			result_chars INTEGER,
+			is_error INTEGER,
+			UNIQUE(session_file, tool_call_id)
+		);
+
+		CREATE INDEX IF NOT EXISTS idx_tool_calls_timestamp ON tool_calls(timestamp);
+		CREATE INDEX IF NOT EXISTS idx_tool_calls_tool_timestamp ON tool_calls(tool_name, timestamp);
+
 		CREATE TABLE IF NOT EXISTS meta (
 			key TEXT PRIMARY KEY,
 			value TEXT NOT NULL
@@ -215,6 +242,7 @@ export async function initDb(): Promise<Database> {
 		`);
 	}
 	backfillUserMessages(db);
+	backfillToolCalls(db);
 	repairUserMessageLinks(db);
 	backfillPriorityPremiumRequests(db);
 	backfillAgentType(db);
@@ -881,6 +909,27 @@ function backfillUserMessages(database: Database): void {
 		.run(USER_MESSAGES_BACKFILL_KEY, BACKFILL_PENDING);
 }
 
+/**
+ * One-shot wipe of `tool_calls` + `file_offsets` when the `tool_calls` table
+ * is introduced (or its schema version bumps), so the next sync re-parses
+ * every session and ingests historical tool calls. `messages` and
+ * `user_messages` re-inserts are idempotent, so the offset reset is safe.
+ * Same sentinel protocol as {@link backfillUserMessages}: the PENDING value
+ * written here prevents re-wiping on subsequent inits.
+ */
+function backfillToolCalls(database: Database): void {
+	const row = database.prepare("SELECT value FROM meta WHERE key = ?").get(TOOL_CALLS_BACKFILL_KEY) as
+		| { value: string }
+		| undefined;
+	if (!shouldResetBackfill(row?.value)) return;
+
+	database.run("DELETE FROM tool_calls");
+	database.run("DELETE FROM file_offsets");
+	database
+		.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)")
+		.run(TOOL_CALLS_BACKFILL_KEY, BACKFILL_PENDING);
+}
+
 /**
  * Reclassify pre-existing `messages` rows by agent type once, after the
  * `agent_type` column is added to an older database (every prior row defaulted
@@ -1276,3 +1325,206 @@ export function getBehaviorByModel(cutoff?: number | null): BehaviorModelStats[]
 		lastTimestamp: row.last_timestamp ?? 0,
 	}));
 }
+
+/**
+ * Insert tool-call rows. Idempotent via UNIQUE(session_file, tool_call_id);
+ * the `WHERE NOT EXISTS` guard mirrors {@link insertMessageStats}: forked
+ * sessions deep-copy assistant entries (same `entry_id`, `timestamp`, and
+ * tool-call ids under a new file), so first-write-wins across the lineage
+ * keeps aggregates from double counting. Keyed on the assistant entry
+ * identity, not the call id alone — provider call ids are not a global
+ * namespace across unrelated sessions.
+ */
+export function insertToolCalls(calls: ToolCallStats[]): number {
+	if (!db || calls.length === 0) return 0;
+
+	const stmt = db.prepare(`
+		INSERT OR IGNORE INTO tool_calls (
+			session_file, entry_id, tool_call_id, folder, tool_name,
+			model, provider, timestamp, agent_type, calls_in_turn, args_chars
+		)
+		SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
+		WHERE NOT EXISTS (
+			SELECT 1 FROM tool_calls
+			WHERE entry_id = ? AND timestamp = ? AND tool_call_id = ? AND session_file <> ?
+		)
+	`);
+
+	let inserted = 0;
+	const insert = db.transaction(() => {
+		for (const c of calls) {
+			const result = stmt.run(
+				c.sessionFile,
+				c.entryId,
+				c.toolCallId,
+				c.folder,
+				c.toolName,
+				c.model,
+				c.provider,
+				c.timestamp,
+				c.agentType,
+				c.callsInTurn,
+				c.argsChars,
+				// `WHERE NOT EXISTS` binds: skip when a different session_file
+				// already holds this (entry_id, timestamp, tool_call_id).
+				c.entryId,
+				c.timestamp,
+				c.toolCallId,
+				c.sessionFile,
+			);
+			if (result.changes > 0) inserted++;
+		}
+	});
+	insert();
+	return inserted;
+}
+
+/**
+ * Attach result size / error flag to persisted tool-call rows. Results can
+ * land in a later incremental sync pass than the call that produced them, so
+ * this is an UPDATE keyed by (session_file, tool_call_id). The `IS NULL`
+ * guard makes re-syncs idempotent; rows skipped by the fork guard simply
+ * never match.
+ */
+export function updateToolResults(links: ToolResultLink[]): number {
+	if (!db || links.length === 0) return 0;
+
+	const stmt = db.prepare(`
+		UPDATE tool_calls
+		SET result_chars = ?, is_error = ?
+		WHERE session_file = ? AND tool_call_id = ? AND result_chars IS NULL
+	`);
+
+	let updated = 0;
+	const apply = db.transaction(() => {
+		for (const link of links) {
+			const result = stmt.run(link.resultChars, link.isError ? 1 : 0, link.sessionFile, link.toolCallId);
+			updated += result.changes;
+		}
+	});
+	apply();
+	return updated;
+}
+
+/**
+ * Shared SELECT list for tool aggregates. Real provider usage comes from the
+ * invoking assistant turn (`messages` join) divided by `calls_in_turn`, so
+ * per-tool token/cost shares stay additive across tools.
+ */
+const TOOL_AGGREGATE_COLUMNS = `
+	COUNT(*) as calls,
+	SUM(CASE WHEN t.is_error = 1 THEN 1 ELSE 0 END) as errors,
+	SUM(t.args_chars) as args_chars,
+	SUM(COALESCE(t.result_chars, 0)) as result_chars,
+	SUM(COALESCE(m.total_tokens, 0) * 1.0 / t.calls_in_turn) as total_tokens_share,
+	SUM(COALESCE(m.output_tokens, 0) * 1.0 / t.calls_in_turn) as output_tokens_share,
+	SUM(COALESCE(m.cost_total, 0) / t.calls_in_turn) as cost_share,
+	MAX(t.timestamp) as last_used
+`;
+
+interface ToolAggregateRow {
+	tool_name: string;
+	model?: string;
+	provider?: string;
+	calls: number;
+	errors: number;
+	args_chars: number | null;
+	result_chars: number | null;
+	total_tokens_share: number | null;
+	output_tokens_share: number | null;
+	cost_share: number | null;
+	last_used: number;
+}
+
+function rowToToolUsage(row: ToolAggregateRow): ToolUsageStats {
+	return {
+		tool: row.tool_name,
+		calls: row.calls,
+		errors: row.errors,
+		argsChars: row.args_chars ?? 0,
+		resultChars: row.result_chars ?? 0,
+		totalTokensShare: row.total_tokens_share ?? 0,
+		outputTokensShare: row.output_tokens_share ?? 0,
+		costShare: row.cost_share ?? 0,
+		lastUsed: row.last_used,
+	};
+}
+
+/**
+ * Get tool usage aggregated by tool name.
+ */
+export function getToolStats(cutoff?: number): ToolUsageStats[] {
+	if (!db) return [];
+
+	const hasCutoff = cutoff !== undefined && cutoff > 0;
+	const stmt = db.prepare(`
+		SELECT t.tool_name, ${TOOL_AGGREGATE_COLUMNS}
+		FROM tool_calls t
+		LEFT JOIN messages m ON m.session_file = t.session_file AND m.entry_id = t.entry_id
+		${hasCutoff ? "WHERE t.timestamp >= ?" : ""}
+		GROUP BY t.tool_name
+		ORDER BY calls DESC
+	`);
+
+	const rows = (hasCutoff ? stmt.all(cutoff) : stmt.all()) as ToolAggregateRow[];
+	return rows.map(rowToToolUsage);
+}
+
+/**
+ * Get tool usage aggregated by (tool, model, provider).
+ */
+export function getToolStatsByModel(cutoff?: number): ToolModelStats[] {
+	if (!db) return [];
+
+	const hasCutoff = cutoff !== undefined && cutoff > 0;
+	const stmt = db.prepare(`
+		SELECT t.tool_name, t.model, t.provider, ${TOOL_AGGREGATE_COLUMNS}
+		FROM tool_calls t
+		LEFT JOIN messages m ON m.session_file = t.session_file AND m.entry_id = t.entry_id
+		${hasCutoff ? "WHERE t.timestamp >= ?" : ""}
+		GROUP BY t.tool_name, t.model, t.provider
+		ORDER BY calls DESC
+	`);
+
+	const rows = (hasCutoff ? stmt.all(cutoff) : stmt.all()) as ToolAggregateRow[];
+	return rows.map(row => ({
+		...rowToToolUsage(row),
+		model: row.model ?? "",
+		provider: row.provider ?? "",
+	}));
+}
+
+/**
+ * Get tool-call time series (one point per bucket per tool).
+ */
+export function getToolTimeSeries(
+	days = 14,
+	cutoff?: number | null,
+	bucketMs = 24 * 60 * 60 * 1000,
+): ToolTimeSeriesPoint[] {
+	if (!db) return [];
+
+	const hasCutoff = cutoff !== null;
+	const seriesCutoff = hasCutoff ? (cutoff ?? Date.now() - days * 24 * 60 * 60 * 1000) : 0;
+
+	const stmt = db.prepare(`
+		SELECT
+			(timestamp / ?) * ? as bucket,
+			tool_name,
+			COUNT(*) as calls,
+			SUM(CASE WHEN is_error = 1 THEN 1 ELSE 0 END) as errors
+		FROM tool_calls
+		${hasCutoff ? "WHERE timestamp >= ?" : ""}
+		GROUP BY bucket, tool_name
+		ORDER BY bucket ASC
+	`);
+
+	const rowsRaw = hasCutoff ? stmt.all(bucketMs, bucketMs, seriesCutoff) : stmt.all(bucketMs, bucketMs);
+	const rows = rowsRaw as Array<{ bucket: number; tool_name: string; calls: number; errors: number }>;
+	return rows.map(row => ({
+		timestamp: row.bucket,
+		tool: row.tool_name,
+		calls: row.calls,
+		errors: row.errors,
+	}));
+}

package/src/index.ts

@@ -8,6 +8,7 @@ import { startServer } from "./server";
 
 export {
 	getDashboardStats,
+	getToolDashboardStats,
 	getTotalMessageCount,
 	type SyncOptions,
 	type SyncProgress,
@@ -32,6 +33,10 @@ export type {
 	ModelStats,
 	ModelTimeSeriesPoint,
 	TimeSeriesPoint,
+	ToolDashboardStats,
+	ToolModelStats,
+	ToolTimeSeriesPoint,
+	ToolUsageStats,
 } from "./types";
 
 /**

package/src/parser.ts

@@ -6,6 +6,7 @@ import {
 	getPriorityPremiumRequests,
 	resolveModelServiceTier,
 	type ServiceTierByFamily,
+	type ToolResultMessage,
 } from "@oh-my-pi/pi-ai";
 import { getSessionsDir, isEnoent } from "@oh-my-pi/pi-utils";
 import type {
@@ -14,6 +15,8 @@ import type {
 	SessionEntry,
 	SessionMessageEntry,
 	SessionServiceTierChangeEntry,
+	ToolCallStats,
+	ToolResultLink,
 	UserMessageLink,
 	UserMessageStats,
 } from "./types";
@@ -85,6 +88,14 @@ function isServiceTierChange(entry: SessionEntry): entry is SessionServiceTierCh
 	return entry.type === "service_tier_change";
 }
 
+/**
+ * Check if an entry is a tool-result message.
+ */
+function isToolResultMessage(entry: SessionEntry): entry is SessionMessageEntry {
+	if (entry.type !== "message") return false;
+	return (entry as SessionMessageEntry).message?.role === "toolResult";
+}
+
 /**
  * Extract plain text from a user message content payload.
  */
@@ -171,6 +182,66 @@ function extractStats(
 	};
 }
 
+/**
+ * Extract one {@link ToolCallStats} per `toolCall` content block of an
+ * assistant message. Returns an empty array for turns without tool calls.
+ */
+function extractToolCalls(
+	sessionFile: string,
+	folder: string,
+	entry: SessionMessageEntry,
+	agentType: AgentType,
+): ToolCallStats[] {
+	const msg = entry.message as AssistantMessage;
+	if (msg?.role !== "assistant" || !Array.isArray(msg.content)) return [];
+
+	const blocks = msg.content.filter(block => block.type === "toolCall");
+	if (blocks.length === 0) return [];
+
+	return blocks.map(block => {
+		let argsChars = 0;
+		try {
+			argsChars = JSON.stringify(block.arguments ?? {}).length;
+		} catch {
+			// Non-serializable arguments (shouldn't happen in persisted JSONL); size unknown.
+		}
+		return {
+			sessionFile,
+			entryId: entry.id,
+			toolCallId: block.id,
+			folder,
+			toolName: block.name,
+			model: msg.model,
+			provider: msg.provider,
+			timestamp: msg.timestamp,
+			agentType,
+			callsInTurn: blocks.length,
+			argsChars,
+		};
+	});
+}
+
+/**
+ * Build the result linkage for a `toolResult` entry: text characters fed back
+ * into context plus the error flag, keyed to the originating call.
+ */
+function extractToolResultLink(sessionFile: string, entry: SessionMessageEntry): ToolResultLink | null {
+	const msg = entry.message as ToolResultMessage;
+	if (msg.role !== "toolResult" || typeof msg.toolCallId !== "string" || msg.toolCallId.length === 0) return null;
+	let resultChars = 0;
+	if (Array.isArray(msg.content)) {
+		for (const block of msg.content) {
+			if (block.type === "text" && typeof block.text === "string") resultChars += block.text.length;
+		}
+	}
+	return {
+		sessionFile,
+		toolCallId: msg.toolCallId,
+		resultChars,
+		isError: msg.isError === true,
+	};
+}
+
 const LF = 0x0a;
 const CR = 0x0d;
 const jsonLineDecoder = new TextDecoder();
@@ -241,6 +312,8 @@ export interface ParseSessionResult {
 	stats: MessageStats[];
 	userStats: UserMessageStats[];
 	userLinks: UserMessageLink[];
+	toolCalls: ToolCallStats[];
+	toolResults: ToolResultLink[];
 	newOffset: number;
 }
 export async function parseSessionFile(sessionPath: string, fromOffset = 0): Promise<ParseSessionResult> {
@@ -248,7 +321,8 @@ export async function parseSessionFile(sessionPath: string, fromOffset = 0): Pro
 	try {
 		bytes = await Bun.file(sessionPath).bytes();
 	} catch (err) {
-		if (isEnoent(err)) return { stats: [], userStats: [], userLinks: [], newOffset: fromOffset };
+		if (isEnoent(err))
+			return { stats: [], userStats: [], userLinks: [], toolCalls: [], toolResults: [], newOffset: fromOffset };
 		throw err;
 	}
 
@@ -257,6 +331,8 @@ export async function parseSessionFile(sessionPath: string, fromOffset = 0): Pro
 	const stats: MessageStats[] = [];
 	const userStats: UserMessageStats[] = [];
 	const userLinks: UserMessageLink[] = [];
+	const toolCalls: ToolCallStats[] = [];
+	const toolResults: ToolResultLink[] = [];
 	const userByEntryId = new Map<string, UserMessageStats>();
 	const start = Math.max(0, Math.min(fromOffset, bytes.length));
 	const unprocessed = bytes.subarray(start);
@@ -278,9 +354,15 @@ export async function parseSessionFile(sessionPath: string, fromOffset = 0): Pro
 			}
 			continue;
 		}
+		if (isToolResultMessage(entry)) {
+			const link = extractToolResultLink(sessionPath, entry);
+			if (link) toolResults.push(link);
+			continue;
+		}
 		if (isAssistantMessage(entry)) {
 			const msgStats = extractStats(sessionPath, folder, entry, currentServiceTier, agentType);
 			if (msgStats) stats.push(msgStats);
+			toolCalls.push(...extractToolCalls(sessionPath, folder, entry, agentType));
 			// Link assistant's responding model back to the user message it answered.
 			const parentId = (entry as SessionMessageEntry).parentId;
 			if (parentId) {
@@ -303,7 +385,7 @@ export async function parseSessionFile(sessionPath: string, fromOffset = 0): Pro
 		}
 	}
 
-	return { stats, userStats, userLinks, newOffset: start + read };
+	return { stats, userStats, userLinks, toolCalls, toolResults, newOffset: start + read };
 }
 
 /**

package/src/server.ts

@@ -13,6 +13,7 @@ import {
 	getRecentErrors,
 	getRecentRequests,
 	getRequestDetails,
+	getToolDashboardStats,
 	getTotalMessageCount,
 	syncAllSessions,
 } from "./aggregator";
@@ -215,6 +216,11 @@ async function handleApi(req: Request): Promise<Response> {
 		return Response.json(stats);
 	}
 
+	if (path === "/api/stats/tools") {
+		const stats = await getToolDashboardStats(range);
+		return Response.json(stats);
+	}
+
 	if (path === "/api/stats/recent") {
 		const limit = url.searchParams.get("limit");
 		const stats = await getRecentRequests(limit ? parseInt(limit, 10) : undefined);

package/src/shared-types.ts

@@ -269,3 +269,55 @@ export interface GainDashboardStats {
 	/** All distinct projects seen in the data, for the selector. */
 	projects: string[];
 }
+
+/**
+ * Aggregated usage for a single tool over the active range.
+ *
+ * Token/cost fields are the *real* provider usage of the assistant turns that
+ * invoked the tool, split evenly across that turn's tool calls so the numbers
+ * stay additive (a turn with 3 calls contributes a third of its usage to each
+ * tool). Payload fields (`argsChars`/`resultChars`) are raw character counts
+ * of the serialized arguments and the text fed back into context — a size
+ * proxy, not provider-counted tokens.
+ */
+export interface ToolUsageStats {
+	/** Tool name as recorded on the tool call. */
+	tool: string;
+	/** Number of tool calls. */
+	calls: number;
+	/** Calls whose result came back with `isError`. */
+	errors: number;
+	/** Serialized tool-call argument characters. */
+	argsChars: number;
+	/** Text characters of tool results fed back into context. */
+	resultChars: number;
+	/** Total provider tokens of invoking turns, attributed per call share. */
+	totalTokensShare: number;
+	/** Output tokens of invoking turns, attributed per call share. */
+	outputTokensShare: number;
+	/** Cost (USD) of invoking turns, attributed per call share. */
+	costShare: number;
+	/** Unix ms of the most recent call in range. */
+	lastUsed: number;
+}
+
+/** Per-(tool, model) breakdown with the same attribution as {@link ToolUsageStats}. */
+export interface ToolModelStats extends ToolUsageStats {
+	model: string;
+	provider: string;
+}
+
+/** Tool-call time-series point (one bucket per tool). */
+export interface ToolTimeSeriesPoint {
+	timestamp: number;
+	tool: string;
+	calls: number;
+	errors: number;
+}
+
+/** Complete tools dashboard payload. */
+export interface ToolDashboardStats {
+	byTool: ToolUsageStats[];
+	byToolModel: ToolModelStats[];
+	series: ToolTimeSeriesPoint[];
+}

package/src/types.ts

@@ -126,3 +126,46 @@ export interface UserMessageLink {
 	model: string;
 	provider: string;
 }
+
+/**
+ * One tool call extracted from an assistant message's `toolCall` content
+ * blocks. `callsInTurn` records how many calls that assistant turn contained
+ * so aggregation can split the turn's real provider usage evenly per call.
+ */
+export interface ToolCallStats {
+	/** Session file path */
+	sessionFile: string;
+	/** Assistant-message entry ID that emitted the call */
+	entryId: string;
+	/** Provider-assigned tool call ID (unique within a session) */
+	toolCallId: string;
+	/** Folder/project path (extracted from session filename) */
+	folder: string;
+	/** Tool name */
+	toolName: string;
+	/** Model that emitted the call */
+	model: string;
+	/** Provider name */
+	provider: string;
+	/** Assistant-message timestamp (Unix ms) */
+	timestamp: number;
+	/** Which agent produced the call */
+	agentType: AgentType;
+	/** Total tool calls in the same assistant turn (>= 1) */
+	callsInTurn: number;
+	/** Serialized argument characters */
+	argsChars: number;
+}
+
+/**
+ * Result linkage emitted when the parser sees a `toolResult` message entry.
+ * Applied as an UPDATE on the persisted tool-call row — results can land in a
+ * later incremental sync pass than the call that produced them.
+ */
+export interface ToolResultLink {
+	sessionFile: string;
+	toolCallId: string;
+	/** Text characters fed back into context */
+	resultChars: number;
+	isError: boolean;
+}