@repo-os/repoos 0.5.45

package/dist/core/db.d.ts

@@ -0,0 +1,236 @@
+/**
+ * SQLite database layer for RepoOS.
+ *
+ * Provides durable storage for session stats (time, tokens, cost) across all
+ * agent types. Uses bun:sqlite (Bun) or node:sqlite (Node >= 22), with graceful
+ * degradation if neither is available.
+ *
+ * Zero runtime dependencies — sqlite is a platform builtin.
+ */
+/** Query result for a session. */
+export interface SessionRecord {
+    sessionId: string;
+    sessionType: string;
+    taskId: string | null;
+    agent: string;
+    model: string;
+    codingAgent: string;
+    startedAt: string;
+    endedAt: string | null;
+    elapsedMs: number;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    totalTokens: number | null;
+    /** Input tokens served from the provider's prompt cache; null if unreported. */
+    cacheReadTokens: number | null;
+    /** Input tokens written to the prompt cache this session; null if unreported. */
+    cacheCreationTokens: number | null;
+    /** Cumulative model round-trips ("turns") across every invocation; null if unreported. */
+    turns: number | null;
+    costUsd: number | null;
+    costSource: string;
+    status: string;
+    lastActivityAt: string;
+}
+/** Aggregation: per-task total stats. */
+export interface TaskStats {
+    taskId: string;
+    totalSessions: number;
+    totalElapsedMs: number;
+    totalInputTokens: number | null;
+    totalOutputTokens: number | null;
+    totalTokens: number | null;
+    totalCacheReadTokens: number | null;
+    totalCacheCreationTokens: number | null;
+    totalTurns: number | null;
+    totalCostUsd: number | null;
+    /** Representative cost source for the task's sessions ("none"/"estimate"/"extractUsage"/"kiro-credits"/"mixed"). */
+    costSource: string;
+    /** Role-level breakdown (engineer/pm/reviewer/cto/guide/…) for this task. */
+    roles: TaskRoleStats[];
+    /** Individual session rows for this task, newest first. */
+    sessions: SessionRecord[];
+}
+/** Aggregation: one role's share of a task's usage. */
+export interface TaskRoleStats {
+    role: string;
+    totalSessions: number;
+    totalElapsedMs: number;
+    totalInputTokens: number | null;
+    totalOutputTokens: number | null;
+    totalTokens: number | null;
+    totalCacheReadTokens: number | null;
+    totalCacheCreationTokens: number | null;
+    totalTurns: number | null;
+    totalCostUsd: number | null;
+    costSource: string;
+}
+/** Aggregation: one day's totals (server's local time). */
+export interface DailyTotals {
+    day: string;
+    totalSessions: number;
+    totalElapsedMs: number;
+    totalInputTokens: number | null;
+    totalOutputTokens: number | null;
+    totalTokens: number | null;
+    totalCostUsd: number | null;
+    costSource: string;
+}
+/** Aggregation: per-session-type total stats. */
+export interface SessionTypeStats {
+    sessionType: string;
+    role: string;
+    totalSessions: number;
+    totalElapsedMs: number;
+    totalInputTokens: number | null;
+    totalOutputTokens: number | null;
+    totalTokens: number | null;
+    totalCacheReadTokens: number | null;
+    totalCacheCreationTokens: number | null;
+    totalTurns: number | null;
+    totalCostUsd: number | null;
+    costSource: string;
+}
+/** Board-level summary stats. */
+export interface BoardStats {
+    totalSessions: number;
+    totalElapsedMs: number;
+    totalTokens: number | null;
+    totalCostUsd: number | null;
+    /** Representative cost source for the board ("none"/"estimate"/"extractUsage"/"kiro-credits"/"mixed"). */
+    costSource: string;
+    mostExpensiveSession: SessionRecord | null;
+    mostExpensiveTask: {
+        taskId: string;
+        costUsd: number;
+    } | null;
+    /** Per-role board totals (sessionType breakdown). */
+    roles: TaskRoleStats[];
+    /** Per-day board totals (server's local time). */
+    days: DailyTotals[];
+}
+/**
+ * Usage time window for board stats (0334): a trailing window anchored at
+ * "now", measured on `sessions.startedAt`. "all" is unfiltered and reproduces
+ * the pre-range behavior exactly — it is the default everywhere.
+ */
+export type UsageRange = "1d" | "7d" | "30d" | "all";
+/** Database wrapper providing high-level operations. */
+export declare class RepoOSDb {
+    private db;
+    private available;
+    /**
+     * Open or create the database. If SQLite is not available, sets available=false
+     * and all operations become no-ops (fail-soft).
+     */
+    constructor(repoRoot: string);
+    /** Apply pending migrations. Returns true only if the schema is in place. */
+    private runMigrations;
+    isAvailable(): boolean;
+    /**
+     * Create or update a session record. The sessionId is unique; multiple turns
+     * update the same record (idempotent).
+     */
+    upsertSession(session: {
+        sessionId: string;
+        sessionType: string;
+        taskId?: string | null;
+        agent: string;
+        model: string;
+        codingAgent: string;
+        startedAt: string;
+        endedAt?: string | null;
+        elapsedMs: number;
+        inputTokens?: number | null;
+        outputTokens?: number | null;
+        totalTokens?: number | null;
+        cacheReadTokens?: number | null;
+        cacheCreationTokens?: number | null;
+        turns?: number | null;
+        costUsd?: number | null;
+        costSource?: string;
+        status?: string;
+        lastActivityAt: string;
+    }): void;
+    /**
+     * Append one raw usage-bearing CLI event, exactly as reported, before it is
+     * folded into the `sessions` rollup. Best-effort and append-only: a failure
+     * here never disturbs the session record or the request.
+     */
+    recordUsageEvent(ev: {
+        sessionId: string;
+        taskId?: string | null;
+        agent?: string | null;
+        model?: string | null;
+        codingAgent?: string | null;
+        eventType?: string | null;
+        inputTokens?: number | null;
+        outputTokens?: number | null;
+        totalTokens?: number | null;
+        cacheReadTokens?: number | null;
+        cacheCreationTokens?: number | null;
+        costUsd?: number | null;
+        turns?: number | null;
+        raw: string;
+    }): void;
+    /** Retrieve a session record by ID. */
+    getSession(sessionId: string): SessionRecord | null;
+    /** Retrieve all sessions for a task. */
+    getTaskSessions(taskId: string): SessionRecord[];
+    /** Aggregate stats for a task (all sessions and review rounds). */
+    getTaskStats(taskId: string): TaskStats | null;
+    /**
+     * Cutoff ISO timestamp for a usage range's trailing window, or null for
+     * "all". `startedAt` is NOT NULL ISO text, so a lexicographic `>= ?`
+     * comparison against an ISO cutoff is correct — and `idx_sessions_startedAt`
+     * covers it.
+     */
+    private usageRangeSince;
+    /**
+     * Aggregate totals broken down by day, using the server's LOCAL time zone
+     * (the day a session's `endedAt` falls into on this machine). Done in JS so
+     * the grouping genuinely reflects local wall-clock days rather than SQLite's
+     * UTC `date()`.
+     *
+     * The optional range filters on `startedAt` (0334) — the same predicate the
+     * headline totals use — so the per-day table always agrees with the board
+     * summary for the selected window.
+     */
+    getDailyTotals(range?: UsageRange): DailyTotals[];
+    /** Aggregate stats grouped by session type, optionally scoped to a usage range (0334). */
+    getSessionTypeStats(range?: UsageRange): SessionTypeStats[];
+    /** Group sessions by a key, preserving insertion order of keys. */
+    private groupRows;
+    /** Build a single role's totals from a group of sessions. */
+    private toRoleStats;
+    /**
+     * Sum usage across a group of sessions. costSource is classified as "mixed"
+     * when the group's spend comes from more than one source, otherwise the
+     * single non-"none" source (or "none"). This drives honest labeling in the UI
+     * (estimates and Kiro credits are never silently shown as firm USD, 0230).
+     */
+    private aggregateRows;
+    /**
+     * Board-level summary: total spend, tokens, time, most expensive session/task.
+     * The optional range (0334) scopes every figure — headline totals, cost
+     * source, most-expensive lookups, roles, days — to sessions started within
+     * the trailing window, so all parts of the panel agree; "all" (the default)
+     * is the unfiltered pre-range behavior.
+     */
+    getBoardStats(range?: UsageRange): BoardStats;
+    /** Close the database connection. */
+    close(): void;
+}
+/**
+ * Get or create the singleton database instance for a repo root.
+ * Returns null if SQLite is not available (graceful degradation).
+ */
+export declare function getRepoOSDb(repoRoot: string): RepoOSDb | null;
+/** Reset the singleton (for tests). */
+export declare function resetDbInstance(): void;
+/** Convenience function to get task stats from the singleton database. */
+export declare function getTaskStats(repoRoot: string, taskId: string): TaskStats | null;
+/** Convenience function to get session type stats from the singleton database. */
+export declare function getSessionTypeStats(repoRoot: string): SessionTypeStats[];
+/** Convenience function to get board stats from the singleton database. */
+export declare function getBoardStats(repoRoot: string): BoardStats;