@linxiraos/pi-stats 1.1.6 → 1.1.8

package/dist/types/client/traces/time-scale.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Virtual time axis for the trace flamegraph.
+ *
+ * All three axis modes are piecewise-linear monotonic maps over global wall
+ * time, so cross-track alignment is preserved in every mode:
+ * - `time`: identity, or idle-compressed (long gaps collapse to fixed bridges)
+ * - `turns`: each main-track turn interval gets equal virtual width
+ * - `calls`: each interval between consecutive span boundaries gets equal width
+ */
+import type { TraceTrack } from "../types.js";
+export type AxisMode = "time" | "turns" | "calls";
+export interface TraceScale {
+    /** ms epoch → virtual axis; monotonic non-decreasing. */
+    toU(t: number): number;
+    /** Inverse (clamped to domain). */
+    toT(u: number): number;
+    /** Virtual axis domain. */
+    domain: [number, number];
+    /** Idle bridges (time mode + compression): real gap [t0,t1] at virtual uMid. */
+    gaps: Array<{
+        t0: number;
+        t1: number;
+        uMid: number;
+    }>;
+}
+/** Build the axis map for the given mode over all tracks. */
+export declare function buildScale(tracks: TraceTrack[], mode: AxisMode, compressIdle: boolean): TraceScale;
+export interface Tick {
+    u: number;
+    label: string;
+    major: boolean;
+}
+/** Offset label from trace start: `+mm:ss.mmm`, hours prepended when needed. */
+export declare function formatOffset(deltaMs: number): string;
+/**
+ * Ruler ticks inside `[u0, u1]`. Ticks are placed at nice wall-time steps in
+ * the underlying t-space (per linear segment in compressed/sequence modes),
+ * with major ticks labelled as local wall clock and minors as offsets.
+ */
+export declare function buildTicks(scale: TraceScale, u0: number, u1: number, widthPx: number): Tick[];

package/dist/types/client/traces/trace-colors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Category palette + canvas chrome tokens for the trace flamegraph, keyed by
+ * resolved theme. Hues align with the dashboard chip palette; chrome tokens
+ * mirror `CHART_THEMES` so the canvas matches the chart.js surfaces.
+ */
+import type { TraceSpanKind } from "../types.js";
+export interface TraceTheme {
+    /** Span fill per category. */
+    category: Record<TraceSpanKind, string>;
+    /** Error fill tint + left-edge accent. */
+    error: string;
+    /** Marker diamond fill. */
+    marker: string;
+    /** Alternating turn-band fill. */
+    turnBand: string;
+    /** Canvas background. */
+    surface: string;
+    /** Ruler/lane hairlines. */
+    grid: string;
+    /** Ruler tick labels. */
+    tick: string;
+    /** Span label text drawn inside blocks. */
+    spanText: string;
+    /** Selection outline (brand cyan focus ring). */
+    selection: string;
+    tooltipBackground: string;
+    tooltipTitle: string;
+    tooltipBody: string;
+    tooltipBorder: string;
+}
+export declare const TRACE_THEMES: Record<"dark" | "light", TraceTheme>;

package/dist/types/db.d.ts

@@ -1,5 +1,5 @@
 import { Database } from "bun:sqlite";
-import type { AgentTypeStats, AggregatedStats, BehaviorModelStats, BehaviorOverallStats, BehaviorTimeSeriesPoint, CostTimeSeriesPoint, FolderStats, MessageStats, ModelPerformancePoint, ModelStats, ModelTimeSeriesPoint, ProviderAggregate, ProviderHourlyPoint, ProviderTimeSeriesPoint, TimeSeriesPoint, ToolCallStats, ToolModelStats, ToolResultLink, ToolTimeSeriesPoint, ToolUsageStats, UserMessageLink, UserMessageStats } from "./types.js";
+import type { AgentTypeStats, AggregatedStats, BehaviorModelStats, BehaviorOverallStats, BehaviorTimeSeriesPoint, CostTimeSeriesPoint, DailyActivityPoint, FolderStats, MessageStats, ModelPerformancePoint, ModelStats, ModelTimeSeriesPoint, ProviderAggregate, ProviderHourlyPoint, ProviderTimeSeriesPoint, TimeSeriesPoint, ToolCallStats, ToolModelStats, ToolResultLink, ToolTimeSeriesPoint, ToolUsageStats, UserMessageLink, UserMessageStats } from "./types.js";
 /**
  * Initialize the database and create tables.
  */
@@ -90,10 +90,33 @@ export declare function closeDb(): void;
 export declare function getRecentRequests(limit?: number): MessageStats[];
 export declare function getRecentErrors(limit?: number, cutoff?: number | null): MessageStats[];
 export declare function getMessageById(id: number): MessageStats | null;
+/** Per-transcript-file rollup for the Traces session list. */
+export interface SessionRollupRow {
+    sessionFile: string;
+    requests: number;
+    startedAt: number;
+    endedAt: number;
+    totalTokens: number;
+    costTotal: number;
+    /** Comma-joined DISTINCT models. */
+    models: string;
+}
+/** Aggregate every synced transcript file into one row (subagents unfolded). */
+export declare function getSessionRollups(): SessionRollupRow[];
+/** Tool-call counts keyed by transcript file, for the Traces session list. */
+export declare function getToolCallCountsBySession(): Map<string, number>;
 /**
  * Get daily cost time series data for the last N days, broken down by model.
  */
 export declare function getCostTimeSeries(days?: number, cutoff?: number | null): CostTimeSeriesPoint[];
+/**
+ * Per-local-day activity aggregates for the last `days` days, oldest first.
+ * Self-initializing (opens the stats DB on first use) so the coding-agent TUI
+ * can query without the dashboard server's init flow. Days use the machine's
+ * timezone — this is a localhost tool, same rationale as
+ * {@link getProviderHourlyBurn}.
+ */
+export declare function getDailyActivity(days?: number): Promise<DailyActivityPoint[]>;
 /**
  * Settle every full-session backfill after a successful sync pass.
  */

package/dist/types/index.d.ts

@@ -3,7 +3,7 @@ export { getDashboardStats, getToolDashboardStats, getTotalMessageCount, type Sy
 export { closeDb } from "./db.js";
 export { getGainDashboardStats } from "./gain-aggregator.js";
 export { formatStatsDashboardUrl, startServer } from "./server.js";
-export type { GainDashboardStats, GainSource, GainSourceTotals, GainTimeSeriesPoint, } from "./shared-types.js";
+export type { GainDashboardStats, GainSource, GainSourceTotals, GainTimeSeriesPoint } from "./shared-types.js";
 export type { AggregatedStats, DashboardStats, FolderStats, MessageStats, ModelPerformancePoint, ModelStats, ModelTimeSeriesPoint, TimeSeriesPoint, ToolDashboardStats, ToolModelStats, ToolTimeSeriesPoint, ToolUsageStats, } from "./types.js";
 /** Parsed arguments for the standalone `omp-stats` entry point. */
 export interface StandaloneStatsArgs {

package/dist/types/parser.d.ts

@@ -10,6 +10,14 @@ import type { AgentType, MessageStats, SessionEntry, ToolCallStats, ToolResultLi
  * is a task `subagent`.
  */
 export declare function classifyAgentType(sessionPath: string): AgentType;
+/**
+ * Extract folder name from session filename.
+ * Session files are named like: --work--pi--/timestamp_uuid.jsonl
+ * The folder part uses -- as path separator.
+ */
+export declare function extractFolderFromPath(sessionPath: string): string;
+/** Parse every well-formed entry in a transcript buffer (malformed lines skipped). */
+export declare function parseAllSessionEntries(bytes: Uint8Array): SessionEntry[];
 /**
  * Parse a session file and extract all assistant message stats.
  * Uses incremental reading with offset tracking.

package/dist/types/server.d.ts

@@ -7,8 +7,9 @@ export declare function formatStatsDashboardUrl(hostname: string, port: number):
 /**
  * Start the HTTP server, reusing a live dashboard or reclaiming a stale omp listener.
  */
-export declare function startServer(port?: number, hostname?: string): Promise<{
+export interface StatsServerHandle {
     hostname: string;
     port: number;
     stop: () => void;
-}>;
+}
+export declare function startServer(port?: number, hostname?: string): Promise<StatsServerHandle>;

package/dist/types/shared-types.d.ts

@@ -127,6 +127,20 @@ export interface CostTimeSeriesPoint {
     /** Request count */
     requests: number;
 }
+/**
+ * One local calendar day of aggregate request activity, for the `/usage`
+ * activity heatmap in the coding-agent TUI.
+ */
+export interface DailyActivityPoint {
+    /** Local calendar date, `YYYY-MM-DD`. */
+    day: string;
+    /** Summed API-equivalent cost for the day. */
+    cost: number;
+    /** Request count for the day. */
+    requests: number;
+    /** Total tokens (input + output + cache) for the day. */
+    totalTokens: number;
+}
 /**
  * Overall dashboard stats.
  */
@@ -419,3 +433,119 @@ export interface ProviderDashboardStats {
     usageSeries: UsageWindowSeries[];
     windowInsights: ProviderWindowInsight[];
 }
+/**
+ * One row of the Traces session list: a root session with every child
+ * transcript (task subagents, advisors) folded in.
+ */
+export interface SessionSummary {
+    /** Absolute root session file path (trace key). */
+    file: string;
+    /** Decoded project path (e.g. `/work/pi`). */
+    folder: string;
+    title: string | null;
+    /** ms epoch of first activity. */
+    startedAt: number;
+    /** ms epoch of last activity, children included. */
+    endedAt: number;
+    /** Assistant messages, children folded in. */
+    requests: number;
+    toolCalls: number;
+    /** Child transcript count. */
+    subagents: number;
+    totalTokens: number;
+    costTotal: number;
+    models: string[];
+}
+export type TraceSpanKind = "turn" | "model" | "tool" | "subagent" | "background";
+/** One rendered block on a trace track lane. */
+export interface TraceSpan {
+    /** `${track.id}:${entryId}` (+`:${toolCallId}` for tool spans); stable across refetch. */
+    id: string;
+    kind: TraceSpanKind;
+    /** ms epoch. */
+    start: number;
+    /** ms epoch, >= start. */
+    end: number;
+    /** ≤80 chars: tool name / model id / user-text head / agent name. */
+    label: string;
+    /** ≤160 chars: args projection / result head / task text. */
+    detail?: string;
+    /** Journal entry id for /api/session/entry. */
+    entryId?: string;
+    toolCallId?: string;
+    model?: string;
+    /** usage.totalTokens (model spans). */
+    tokens?: number;
+    /** usage.cost.total (model spans). */
+    cost?: number;
+    /** Time to first token, ms offset from start. */
+    ttft?: number;
+    isError?: boolean;
+    /** End synthesized (no result / pending at session exit). */
+    unterminated?: boolean;
+    /** Set on `subagent` spans whose child transcript became a track. */
+    childTrackId?: string;
+}
+/** Point event drawn on a track header row. */
+export interface TraceMarker {
+    /** ms epoch. */
+    time: number;
+    kind: "compaction" | "model_change" | "mode_change" | "reset" | "session_exit";
+    /** e.g. "compaction 142k→38k", model id, mode name, exit kind. */
+    label: string;
+}
+/** One transcript (main session, subagent, advisor) in a trace. */
+export interface TraceTrack {
+    /** "main" or slash-joined child key: "Scout1", "Scout1/Nested2", "__advisor". */
+    id: string;
+    parentId: string | null;
+    label: string;
+    /** session_init.agent when recorded. */
+    agent: string | null;
+    /** session_init.resolvedModel ?? first assistant model. */
+    model: string | null;
+    /** Absolute transcript path (for entry fetch). */
+    file: string;
+    /** Sorted by start. */
+    spans: TraceSpan[];
+    markers: TraceMarker[];
+}
+/** Per-tool duration aggregate across all tracks of one trace. */
+export interface TraceToolStat {
+    tool: string;
+    calls: number;
+    errors: number;
+    totalMs: number;
+    maxMs: number;
+}
+/** Headline aggregates for one trace. */
+export interface TraceSummary {
+    wallMs: number;
+    /** Summed model-span duration on the main track. */
+    modelMs: number;
+    /** Summed tool-span duration on the main track. */
+    toolMs: number;
+    /** Wall time not covered by any span on any track. */
+    idleMs: number;
+    turns: number;
+    requests: number;
+    toolCalls: number;
+    subagents: number;
+    totalTokens: number;
+    costTotal: number;
+    /** Sorted totalMs desc. */
+    toolStats: TraceToolStat[];
+}
+/** Complete span tree for one session, `/api/session/trace` payload. */
+export interface SessionTrace {
+    file: string;
+    title: string | null;
+    cwd: string | null;
+    startedAt: number;
+    endedAt: number;
+    /** Root transcript mtime; doubles as the ETag. */
+    mtimeMs: number;
+    /** DFS order, main first. */
+    tracks: TraceTrack[];
+    summary: TraceSummary;
+}

package/dist/types/trace.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Session trace assembly for the Traces dashboard section.
+ *
+ * Builds a span tree (turns, model calls, tool calls, subagents, background
+ * jobs) directly from raw session JSONL — the only source with tool start/end
+ * times — while stats.db supplies the session-list rollups. Entry shapes are
+ * mirrored structurally from the coding-agent journal (`tool_execution_start`,
+ * `session_exit`, task results, async-result batches); stats never imports
+ * coding-agent.
+ */
+import type { SessionEntry, SessionSummary, SessionTrace } from "./types.js";
+/** Client-supplied path escaped the sessions root or is not a transcript. Maps to HTTP 400. */
+export declare class TracePathError extends Error {
+}
+/**
+ * Trace payload schema/assembly revision, folded into the HTTP ETag. Bump when
+ * span assembly changes so browsers don't revalidate stale cached bodies
+ * against an unchanged transcript mtime.
+ */
+export declare const TRACE_ETAG_VERSION = 2;
+/**
+ * Assemble the full span tree for one root session transcript.
+ * Throws {@link TracePathError} for paths outside the sessions root; ENOENT
+ * passes through for the caller's 404 mapping.
+ */
+export declare function buildSessionTrace(fileParam: string): Promise<SessionTrace>;
+/** Fetch one full journal entry by id from a transcript, for the span drawer. */
+export declare function getTraceEntry(fileParam: string, entryId: string): Promise<SessionEntry | null>;
+/**
+ * List root sessions for the Traces section, folding every synced child
+ * transcript (subagents, advisors) into its root row.
+ */
+export declare function listSessionSummaries(limit?: number, q?: string): Promise<SessionSummary[]>;

package/dist/types/types.d.ts

@@ -70,7 +70,41 @@ export interface SessionServiceTierChangeEntry {
     timestamp: string;
     serviceTier: ServiceTierByFamily | ServiceTier | null;
 }
-export type SessionEntry = SessionHeader | SessionMessageEntry | SessionServiceTierChangeEntry | {
+export interface SessionModelUsageEntry {
+    type: "model_usage";
+    id: string;
+    parentId: string | null;
+    timestamp: string;
+    purpose: string;
+    role?: string;
+    api: string;
+    provider: string;
+    model: string;
+    usage: Usage;
+    stopReason?: StopReason;
+    errorMessage?: string;
+}
+/**
+ * Custom journal entry (`tool_execution_start`, `session_exit`, …). Mirrors
+ * the coding-agent shape structurally — stats never imports coding-agent.
+ */
+export interface SessionCustomEntry {
+    type: "custom";
+    id?: string;
+    parentId?: string | null;
+    timestamp?: string;
+    customType: string;
+    data?: Record<string, unknown>;
+}
+/** Structural variants the trace builder matches on beyond messages. */
+export interface SessionTypedEntry {
+    type: "session_init" | "compaction" | "model_change" | "mode_change" | "reset_boundary";
+    id?: string;
+    parentId?: string | null;
+    timestamp?: string;
+    [key: string]: unknown;
+}
+export type SessionEntry = SessionHeader | SessionMessageEntry | SessionServiceTierChangeEntry | SessionModelUsageEntry | SessionCustomEntry | SessionTypedEntry | {
     type: string;
 };
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@linxiraos/pi-stats",
-	"version": "1.1.6",
+	"version": "1.1.8",
 	"description": "Local observability dashboard for pi AI usage statistics",
 	"homepage": "https://linxira-os.github.io/zeta/",
 	"author": "Can Boluk",
@@ -39,9 +39,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@linxiraos/pi-ai": "1.1.6",
-		"@linxiraos/pi-catalog": "1.1.6",
-		"@linxiraos/pi-utils": "1.1.6",
+		"@linxiraos/pi-ai": "1.1.8",
+		"@linxiraos/pi-catalog": "1.1.8",
+		"@linxiraos/pi-utils": "1.1.8",
 		"@tailwindcss/node": "^4.3.2",
 		"chart.js": "^4.5.1",
 		"lucide-react": "^1.24.0",

package/src/client/App.tsx

@@ -13,11 +13,12 @@ import {
 	ProvidersRoute,
 	RequestsRoute,
 	ToolsRoute,
+	TracesRoute,
 } from "./routes";
 import { RequestDrawer } from "./ui/RequestDrawer";
 
 export default function App() {
-	const { section, setSection, range, setRange } = useHashRoute();
+	const { section, setSection, range, setRange, session, setSession } = useHashRoute();
 	const [refreshTrigger, setRefreshTrigger] = useState(0);
 	const [selectedRequestId, setSelectedRequestId] = useState<number | null>(null);
 	const [updatedAt, setUpdatedAt] = useState<number | null>(() => Date.now());
@@ -63,6 +64,15 @@ export default function App() {
 						onRequestClick={setSelectedRequestId}
 					/>
 				);
+			case "traces":
+				return (
+					<TracesRoute
+						active={isActive}
+						session={session}
+						onOpenSession={setSession}
+						refreshTrigger={refreshTrigger}
+					/>
+				);
 			case "errors":
 				return (
 					<ErrorsRoute

package/src/client/api.ts

@@ -8,6 +8,8 @@ import type {
 	OverviewStats,
 	ProviderDashboardStats,
 	RequestDetails,
+	SessionSummary,
+	SessionTrace,
 	TimeRange,
 	ToolDashboardStats,
 } from "./types";
@@ -116,3 +118,24 @@ export async function getProviderDashboardStats(
 		signal,
 	});
 }
+export async function getSessions(limit = 100, q?: string, signal?: AbortSignal): Promise<SessionSummary[]> {
+	const params = new URLSearchParams({ limit: String(limit) });
+	if (q) params.set("q", q);
+	return fetchJson<SessionSummary[]>(`${API_BASE}/sessions?${params}`, { signal });
+}
+
+export async function getSessionTrace(file: string, signal?: AbortSignal): Promise<SessionTrace> {
+	return fetchJson<SessionTrace>(`${API_BASE}/session/trace?file=${encodeURIComponent(file)}`, { signal });
+}
+
+/** Fetch one full journal entry for the span drawer. Entries are opaque JSON. */
+export async function getSessionEntryDetail(
+	file: string,
+	id: string,
+	signal?: AbortSignal,
+): Promise<{ entry: unknown }> {
+	return fetchJson<{ entry: unknown }>(
+		`${API_BASE}/session/entry?file=${encodeURIComponent(file)}&id=${encodeURIComponent(id)}`,
+		{ signal },
+	);
+}

package/src/client/app/routes.ts

@@ -5,6 +5,7 @@ import {
 	Cpu,
 	Folder,
 	LayoutDashboard,
+	ListTree,
 	Plug,
 	Smile,
 	TrendingUp,
@@ -15,6 +16,7 @@ import type React from "react";
 export type DashboardSection =
 	| "overview"
 	| "requests"
+	| "traces"
 	| "errors"
 	| "models"
 	| "providers"
@@ -42,6 +44,11 @@ export const routes: DashboardRoute[] = [
 		label: "Requests",
 		icon: Activity,
 	},
+	{
+		id: "traces",
+		label: "Traces",
+		icon: ListTree,
+	},
 	{
 		id: "errors",
 		label: "Errors",

package/src/client/data/useHashRoute.ts

@@ -5,6 +5,7 @@ import type { TimeRange } from "../types";
 const VALID_SECTIONS: DashboardSection[] = [
 	"overview",
 	"requests",
+	"traces",
 	"errors",
 	"models",
 	"providers",
@@ -17,7 +18,7 @@ const VALID_SECTIONS: DashboardSection[] = [
 
 const VALID_RANGES: TimeRange[] = ["1h", "24h", "7d", "30d", "90d", "all"];
 
-function parseHash(hash: string): { section: DashboardSection; range: TimeRange } {
+function parseHash(hash: string): { section: DashboardSection; range: TimeRange; session: string | null } {
 	const cleanHash = hash.replace(/^#\/?/, "");
 	const [pathPart, queryPart] = cleanHash.split("?");
 
@@ -26,15 +27,22 @@ function parseHash(hash: string): { section: DashboardSection; range: TimeRange
 		: "overview";
 
 	let range: TimeRange = "24h";
+	let session: string | null = null;
 	if (queryPart) {
 		const params = new URLSearchParams(queryPart);
 		const rangeParam = params.get("range") as TimeRange;
 		if (VALID_RANGES.includes(rangeParam)) {
 			range = rangeParam;
 		}
+		session = params.get("s");
 	}
 
-	return { section, range };
+	return { section, range, session };
+}
+
+function buildHash(section: string, range: TimeRange, session?: string | null): string {
+	const sessionPart = session ? `&s=${encodeURIComponent(session)}` : "";
+	return `/${section}?range=${range}${sessionPart}`;
 }
 
 export function useHashRoute() {
@@ -51,31 +59,39 @@ export function useHashRoute() {
 		};
 	}, []);
 
-	const updateHash = useCallback((section: string, range: TimeRange) => {
-		window.location.hash = `/${section}?range=${range}`;
+	const updateHash = useCallback((section: string, range: TimeRange, session?: string | null) => {
+		window.location.hash = buildHash(section, range, session);
 	}, []);
 
 	const setSection = useCallback(
 		(newSection: DashboardSection) => {
-			updateHash(newSection, route.range);
+			// The deep-linked session only applies to the traces view.
+			updateHash(newSection, route.range, newSection === "traces" ? route.session : null);
 		},
-		[route.range, updateHash],
+		[route.range, route.session, updateHash],
 	);
 
 	const setRange = useCallback(
 		(newRange: string) => {
 			const nextRange = VALID_RANGES.includes(newRange as TimeRange) ? (newRange as TimeRange) : "24h";
-			updateHash(route.section, nextRange);
+			updateHash(route.section, nextRange, route.session);
+		},
+		[route.section, route.session, updateHash],
+	);
+
+	const setSession = useCallback(
+		(file: string | null) => {
+			updateHash(route.section, route.range, file);
 		},
-		[route.section, updateHash],
+		[route.section, route.range, updateHash],
 	);
 
 	useEffect(() => {
 		const currentHash = window.location.hash;
 		const parsed = parseHash(currentHash);
-		const expectedHash = `#/${parsed.section}?range=${parsed.range}`;
+		const expectedHash = `#${buildHash(parsed.section, parsed.range, parsed.session)}`;
 		if (currentHash !== expectedHash) {
-			window.location.hash = `/${parsed.section}?range=${parsed.range}`;
+			window.location.hash = buildHash(parsed.section, parsed.range, parsed.session);
 		}
 	}, []);
 
@@ -84,5 +100,7 @@ export function useHashRoute() {
 		setSection,
 		range: route.range,
 		setRange,
+		session: route.session,
+		setSession,
 	};
 }

package/src/client/routes/ProvidersRoute.tsx

@@ -234,6 +234,7 @@ function PeakHoursPanel({ hourly, providers }: { hourly: ProviderHourlyPoint[];
 	const chartTheme = CHART_THEMES[theme];
 
 	const { tokensByHour, peakHour } = useMemo(() => {
+		// oxlint-disable-next-line unicorn/no-new-array -- length preallocation
 		const tokens = new Array<number>(24).fill(0);
 		for (const point of hourly) {
 			if (provider !== ALL_PROVIDERS && point.provider !== provider) continue;