@linxiraos/pi-stats 1.0.0

package/dist/types/port-conflict.d.ts

@@ -0,0 +1,14 @@
+/** Header stamped on every dashboard response so reuse probes can identify us. */
+export declare const STATS_DASHBOARD_HEADER = "x-omp-stats-dashboard";
+/** Identity-header value for dashboards enforcing loopback-only, same-origin access. */
+export declare const STATS_DASHBOARD_SECURITY_VERSION = "2";
+/** IPv4 loopback address shared by the dashboard server and reuse probe. */
+export declare const STATS_DASHBOARD_HOSTNAME = "127.0.0.1";
+/**
+ * Reuse a secure dashboard or reclaim an insecure HTTP dashboard before binding.
+ * The preflight is needed on platforms that permit wildcard and loopback-specific
+ * listeners to coexist on one port.
+ */
+export declare function prepareStatsPort(port: number): Promise<"retry" | "reuse">;
+/** Reuse or reclaim a listener found after the server bind reports EADDRINUSE. */
+export declare function recoverStatsPort(port: number): Promise<"retry" | "reuse">;

package/dist/types/server.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Handle API requests.
+ */
+export declare function handleApi(req: Request): Promise<Response>;
+/**
+ * Start the HTTP server, reusing a live dashboard or reclaiming a stale omp listener.
+ */
+export declare function startServer(port?: number): Promise<{
+    hostname: string;
+    port: number;
+    stop: () => void;
+}>;

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

@@ -0,0 +1,403 @@
+/**
+ * Shared type definitions consumed by both the server-side stats code and the
+ * standalone client bundle. Keep this file free of any imports from server-only
+ * packages (e.g. `@linxiraos/pi-ai`, `bun:sqlite`) so the client can import it
+ * without dragging server dependencies into its bundle.
+ */
+/**
+ * Aggregated stats for a model or folder.
+ */
+export interface AggregatedStats {
+    /** Total number of requests */
+    totalRequests: number;
+    /** Number of successful requests */
+    successfulRequests: number;
+    /** Number of failed requests */
+    failedRequests: number;
+    /** Error rate (0-1) */
+    errorRate: number;
+    /** Total input tokens */
+    totalInputTokens: number;
+    /** Total output tokens */
+    totalOutputTokens: number;
+    /** Total cache read tokens */
+    totalCacheReadTokens: number;
+    /** Total cache write tokens */
+    totalCacheWriteTokens: number;
+    /** Cache hit rate (0-1) */
+    cacheRate: number;
+    /** Total cost */
+    totalCost: number;
+    /** Total premium requests */
+    totalPremiumRequests: number;
+    /** Average duration in ms */
+    avgDuration: number | null;
+    /** Average TTFT in ms */
+    avgTtft: number | null;
+    /** Average tokens per second (output tokens / duration) */
+    avgTokensPerSecond: number | null;
+    /** Time range */
+    firstTimestamp: number;
+    lastTimestamp: number;
+}
+/**
+ * Stats grouped by model.
+ */
+export interface ModelStats extends AggregatedStats {
+    model: string;
+    provider: string;
+}
+/**
+ * Stats grouped by folder.
+ */
+export interface FolderStats extends AggregatedStats {
+    folder: string;
+}
+/**
+ * Time series data point.
+ */
+export interface TimeSeriesPoint {
+    /** Bucket timestamp (start of hour/day) */
+    timestamp: number;
+    /** Request count */
+    requests: number;
+    /** Error count */
+    errors: number;
+    /** Total tokens */
+    tokens: number;
+    /** Total cost */
+    cost: number;
+}
+/**
+ * Model usage time series data point (daily buckets).
+ */
+export interface ModelTimeSeriesPoint {
+    /** Bucket timestamp (start of day) */
+    timestamp: number;
+    /** Model name */
+    model: string;
+    /** Provider name */
+    provider: string;
+    /** Request count */
+    requests: number;
+}
+/**
+ * Model performance time series data point (daily buckets).
+ */
+export interface ModelPerformancePoint {
+    /** Bucket timestamp (start of day) */
+    timestamp: number;
+    /** Model name */
+    model: string;
+    /** Provider name */
+    provider: string;
+    /** Request count */
+    requests: number;
+    /** Average TTFT in ms */
+    avgTtft: number | null;
+    /** Average tokens per second */
+    avgTokensPerSecond: number | null;
+}
+/**
+ * Cost time series data point (daily buckets).
+ */
+export interface CostTimeSeriesPoint {
+    /** Bucket timestamp (start of day) */
+    timestamp: number;
+    /** Model name */
+    model: string;
+    /** Provider name */
+    provider: string;
+    /** Total cost for this bucket */
+    cost: number;
+    /** Cost breakdown */
+    costInput: number;
+    costOutput: number;
+    costCacheRead: number;
+    costCacheWrite: number;
+    /** Request count */
+    requests: number;
+}
+/**
+ * Overall dashboard stats.
+ */
+export interface DashboardStats {
+    overall: AggregatedStats;
+    byModel: ModelStats[];
+    byFolder: FolderStats[];
+    byAgentType: AgentTypeStats[];
+    timeSeries: TimeSeriesPoint[];
+    modelSeries: ModelTimeSeriesPoint[];
+    modelPerformanceSeries: ModelPerformancePoint[];
+    costSeries: CostTimeSeriesPoint[];
+}
+/**
+ * Which agent produced a message, derived from its transcript file location
+ * inside the session directory: the top-level `<project>/<file>.jsonl` is the
+ * `main` agent, an `__advisor.jsonl` is the passive `advisor`, and any other
+ * nested transcript is a task `subagent`.
+ */
+export type AgentType = "main" | "subagent" | "advisor";
+/**
+ * Token usage aggregated by {@link AgentType} over the active range. Token
+ * columns are explicit so the dashboard's share denominator matches the
+ * counts it renders (input + output + cache read + cache write).
+ */
+export interface AgentTypeStats {
+    agentType: AgentType;
+    /** Total number of requests */
+    totalRequests: number;
+    /** Total input tokens */
+    totalInputTokens: number;
+    /** Total output tokens */
+    totalOutputTokens: number;
+    /** Total cache read tokens */
+    totalCacheReadTokens: number;
+    /** Total cache write tokens */
+    totalCacheWriteTokens: number;
+    /** Total cost */
+    totalCost: number;
+}
+/**
+ * Behavior time-series point (daily bucket, per responding model).
+ */
+export interface BehaviorTimeSeriesPoint {
+    /** Bucket timestamp (start of day) */
+    timestamp: number;
+    /** Responding model ("unknown" if user msg never got a reply) */
+    model: string;
+    /** Responding provider */
+    provider: string;
+    /** Number of user messages in bucket */
+    messages: number;
+    /** Total yelling sentences in bucket */
+    yelling: number;
+    /** Total profanity hits in bucket */
+    profanity: number;
+    /** Total anguish signal in bucket */
+    anguish: number;
+    /** Total corrective-negation hits in bucket */
+    negation: number;
+    /** Total user-repeating-themselves hits in bucket */
+    repetition: number;
+    /** Total second-person blame hits in bucket */
+    blame: number;
+    /** Total characters in bucket */
+    chars: number;
+}
+export interface BehaviorOverallStats {
+    totalMessages: number;
+    totalYelling: number;
+    totalProfanity: number;
+    totalAnguish: number;
+    totalNegation: number;
+    totalRepetition: number;
+    totalBlame: number;
+    totalChars: number;
+    firstTimestamp: number;
+    lastTimestamp: number;
+}
+/**
+ * Per-model behavioral aggregate over the active range.
+ */
+export interface BehaviorModelStats {
+    model: string;
+    provider: string;
+    totalMessages: number;
+    totalYelling: number;
+    totalProfanity: number;
+    totalAnguish: number;
+    totalNegation: number;
+    totalRepetition: number;
+    totalBlame: number;
+    totalChars: number;
+    lastTimestamp: number;
+}
+export interface BehaviorDashboardStats {
+    overall: BehaviorOverallStats;
+    byModel: BehaviorModelStats[];
+    behaviorSeries: BehaviorTimeSeriesPoint[];
+}
+/** Token savings from a single source type. */
+export interface GainSourceTotals {
+    savedTokens: number;
+    savedBytes: number;
+    hits: number;
+    /** originalBytes - savedBytes, when original is known */
+    outputBytes: number;
+    /** Total original bytes before compression, when known */
+    originalBytes: number;
+    /** savedBytes / originalBytes when both are known, else null */
+    reductionPercent: number | null;
+}
+/** Per-source breakdown. */
+export type GainSource = "snapcompact";
+/** Time-series point for gain (daily bucket). */
+export interface GainTimeSeriesPoint {
+    date: string;
+    snapcompact: number;
+    total: number;
+}
+/** Complete gain dashboard payload. */
+export interface GainDashboardStats {
+    /** Aggregate across all sources for the active range. */
+    overall: GainSourceTotals;
+    /** Per-source breakdown. */
+    bySource: Record<GainSource, GainSourceTotals>;
+    /** Daily time series. */
+    timeSeries: GainTimeSeriesPoint[];
+    /** Active project filter (cwd prefix), or null for all projects. */
+    project: string | null;
+    /** 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[];
+}
+/**
+ * Aggregated request/token/cost totals for one provider over the active range.
+ */
+export interface ProviderAggregate {
+    provider: string;
+    totalRequests: number;
+    failedRequests: number;
+    /** Distinct models used through this provider in the range. */
+    models: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCacheReadTokens: number;
+    totalCacheWriteTokens: number;
+    /** Uncached input + cache reads + cache writes + output. */
+    totalTokens: number;
+    totalCost: number;
+    totalPremiumRequests: number;
+    avgTokensPerSecond: number | null;
+}
+/**
+ * Token burn attributed to one local hour-of-day (0-23) for one provider.
+ * Powers the "peak burn hours" histogram.
+ */
+export interface ProviderHourlyPoint {
+    provider: string;
+    /** Local hour of day, 0-23. */
+    hour: number;
+    totalTokens: number;
+    outputTokens: number;
+    requests: number;
+}
+/** Provider token/cost time-series point (bucketed like the model series). */
+export interface ProviderTimeSeriesPoint {
+    timestamp: number;
+    provider: string;
+    totalTokens: number;
+    cost: number;
+    requests: number;
+}
+/** One recorded usage-limit snapshot for an (account, window) series. */
+export interface UsageWindowPoint {
+    timestamp: number;
+    /** Used fraction 0..1 (>1 = overage) when the provider reported one. */
+    usedFraction: number | null;
+    exhausted: boolean;
+}
+/**
+ * Utilization history for one (account, limit window) pair of a provider,
+ * sourced from the auth store's recorded usage-limit snapshots.
+ */
+export interface UsageWindowSeries {
+    provider: string;
+    accountKey: string;
+    /** Email/account id when known, else the stable account key. */
+    accountLabel: string;
+    /** Groups the same limit window across accounts (window label or limit id). */
+    windowKey: string;
+    windowLabel: string;
+    points: UsageWindowPoint[];
+}
+/**
+ * Derived subscription insight for one provider limit window across all
+ * accounts: how much of the window was consumed, what one window is worth in
+ * tokens, and how many accounts peak demand would have needed.
+ */
+export interface ProviderWindowInsight {
+    provider: string;
+    windowKey: string;
+    windowLabel: string;
+    /** Accounts with at least one snapshot for this window in range. */
+    accounts: number;
+    /** Window resets observed (drops in used fraction). */
+    cycles: number;
+    /**
+     * Subscription-window equivalents consumed in range: sum of positive
+     * used-fraction deltas across accounts (1.0 = one full window burned).
+     */
+    fractionConsumed: number;
+    /**
+     * Estimated tokens one full window buys: provider tokens burned in range
+     * divided by {@link fractionConsumed}. Null when too little of the window
+     * was consumed to extrapolate.
+     */
+    estTokensPerWindow: number | null;
+    /** Peak of sum-across-accounts used fraction at any sampled instant. */
+    peakConcurrentFraction: number;
+    /**
+     * Accounts needed to keep peak demand under 90% of fleet capacity:
+     * max(1, ceil(peakConcurrentFraction / 0.9)).
+     */
+    idealAccounts: number;
+    /** Transitions into an exhausted state observed in range. */
+    exhaustedEvents: number;
+}
+/** Complete providers dashboard payload. */
+export interface ProviderDashboardStats {
+    providers: ProviderAggregate[];
+    hourly: ProviderHourlyPoint[];
+    series: ProviderTimeSeriesPoint[];
+    usageSeries: UsageWindowSeries[];
+    windowInsights: ProviderWindowInsight[];
+}

package/dist/types/sync-worker.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Stateless parse worker for `syncAllSessions`. The main thread owns the
+ * SQLite handle; workers receive `{ sessionFile, fromOffset }`, run
+ * `parseSessionFile` (which is pure I/O + CPU, no DB), and post the
+ * structured-clone-safe result back. One in-flight request per worker so
+ * the main thread can fan jobs out 1:1 with the pool size.
+ *
+ * A `{ kind: "ping" }` request is also accepted and replies with
+ * `{ ok: true, kind: "pong" }` — used by `smokeTestSyncWorker` to prove the
+ * worker actually spawns and runs in compiled binaries (regression coverage
+ * for issue #1011 / PR #1027, where the worker silently failed to load).
+ */
+import { type ParseSessionResult } from "./parser.js";
+export type SyncWorkerRequest = {
+    kind?: "parse";
+    sessionFile: string;
+    fromOffset: number;
+} | {
+    kind: "ping";
+};
+export type SyncWorkerResponse = {
+    ok: true;
+    kind?: "parse";
+    result: ParseSessionResult;
+} | {
+    ok: true;
+    kind: "pong";
+} | {
+    ok: false;
+    error: string;
+};

package/dist/types/types.d.ts

@@ -0,0 +1,164 @@
+import type { AssistantMessage, ServiceTier, ServiceTierByFamily, StopReason, Usage } from "@linxiraos/pi-ai";
+import type { AgentType } from "./shared-types.js";
+export * from "./shared-types.js";
+/**
+ * Extracted stats from an assistant message.
+ */
+export interface MessageStats {
+    /** Database ID */
+    id?: number;
+    /** Session file path */
+    sessionFile: string;
+    /** Entry ID within the session */
+    entryId: string;
+    /** Folder/project path (extracted from session filename) */
+    folder: string;
+    /** Model ID */
+    model: string;
+    /** Provider name */
+    provider: string;
+    /** API type */
+    api: string;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Request duration in milliseconds */
+    duration: number | null;
+    /** Time to first token in milliseconds */
+    ttft: number | null;
+    /** Stop reason */
+    stopReason: StopReason;
+    /** Error message if stopReason is error */
+    errorMessage: string | null;
+    /** Token usage */
+    usage: Usage;
+    /** Which agent produced this message (main agent, task subagent, advisor) */
+    agentType: AgentType;
+}
+/**
+ * Full details of a request, including content.
+ */
+export interface RequestDetails extends MessageStats {
+    /** The full conversation history or just the last turn. */
+    messages: unknown[];
+    /** The model's response. */
+    output: unknown;
+}
+/**
+ * Session log entry types.
+ */
+export interface SessionHeader {
+    type: "session";
+    version: number;
+    id: string;
+    timestamp: string;
+    cwd: string;
+    title?: string;
+}
+export interface SessionMessageEntry {
+    type: "message";
+    id: string;
+    parentId: string | null;
+    timestamp: string;
+    message: AssistantMessage | {
+        role: "user" | "toolResult";
+    };
+}
+export interface SessionServiceTierChangeEntry {
+    type: "service_tier_change";
+    id: string;
+    parentId?: string | null;
+    timestamp: string;
+    serviceTier: ServiceTierByFamily | ServiceTier | null;
+}
+export type SessionEntry = SessionHeader | SessionMessageEntry | SessionServiceTierChangeEntry | {
+    type: string;
+};
+/**
+ * Behavioral stats extracted from a single user message.
+ */
+export interface UserMessageStats {
+    /** Database ID */
+    id?: number;
+    /** Session file path */
+    sessionFile: string;
+    /** Entry ID within the session */
+    entryId: string;
+    /** Folder/project path */
+    folder: string;
+    /** Unix timestamp in ms */
+    timestamp: number;
+    /** Model that responded to this user message, if linked */
+    model: string | null;
+    /** Provider that responded to this user message, if linked */
+    provider: string | null;
+    /** Total characters of message text */
+    chars: number;
+    /** Whitespace-delimited word count */
+    words: number;
+    /** Yelling sentences (> 50% uppercase letters) */
+    yelling: number;
+    /** Profanity hits */
+    profanity: number;
+    /** Catch-all upset signal: drama runs + `noooo`/`ughh`/... + `dude` + `:(` */
+    anguish: number;
+    /** Corrective negation ("no", "nope", "thats not what i meant") */
+    negation: number;
+    /** User repeating themselves ("i meant", "still doesnt work", "like i said") */
+    repetition: number;
+    /** Second-person reproach ("you didnt", "why did you", "stop X-ing") */
+    blame: number;
+}
+/**
+ * Pair emitted by the parser when it sees an assistant message whose
+ * `parentId` points to a user message that wasn't parsed in the same pass
+ * (e.g. user prompt landed in an earlier incremental sync). The aggregator
+ * applies the link to the persisted `user_messages` row so it stops showing
+ * up in the "unknown" model bucket.
+ */
+export interface UserMessageLink {
+    sessionFile: string;
+    entryId: string;
+    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;
+}

package/dist/types/usage-windows.d.ts

@@ -0,0 +1,45 @@
+import type { ProviderWindowInsight, UsageWindowSeries } from "./shared-types.js";
+/** Subset of a `usage_history` row consumed by the window analytics. */
+export interface UsageSnapshotRow {
+    /** Epoch ms the report was fetched. */
+    recordedAt: number;
+    provider: string;
+    /** Stable credential identity key. */
+    accountKey: string;
+    email: string | null;
+    accountId: string | null;
+    limitId: string;
+    label: string;
+    windowLabel: string | null;
+    /** Used fraction (0..1, >1 = overage) when the provider reported one. */
+    usedFraction: number | null;
+    status: string | null;
+}
+/** Utilization series + derived insights for every provider window in range. */
+export interface UsageWindowStats {
+    usageSeries: UsageWindowSeries[];
+    windowInsights: ProviderWindowInsight[];
+}
+/**
+ * Read usage-limit snapshots recorded at or after `sinceMs`, oldest first.
+ * Opens the agent DB read-only; returns `[]` when the DB or table is absent.
+ */
+export declare function readUsageSnapshots(sinceMs: number, dbPath?: string): UsageSnapshotRow[];
+/**
+ * Fetch usage snapshots from wherever they actually accumulate: the auth
+ * broker's durable history when a broker is configured (the broker performs
+ * every upstream usage fetch in that mode, so the local `usage_history` stays
+ * frozen), else the local agent DB. Broker errors fall back to the local read
+ * so the dashboard degrades to stale-but-present data instead of failing.
+ */
+export declare function fetchUsageSnapshots(sinceMs: number): Promise<UsageSnapshotRow[]>;
+/**
+ * Derive utilization series and per-window insights from raw snapshots.
+ *
+ * `tokensByProvider` supplies each provider's token burn over the same time
+ * range (from the local message stats); it converts consumed window fraction
+ * into an estimated token capacity per window. Attribution note: tokens are
+ * per provider, not per account, so the estimate treats the account fleet as
+ * one pooled subscription — which is exactly how round-robin auth uses it.
+ */
+export declare function computeUsageWindowStats(rows: UsageSnapshotRow[], tokensByProvider: ReadonlyMap<string, number>): UsageWindowStats;