opencode-usage-insights 0.0.0-stage → 0.1.1

package/dist/panel.d.ts

@@ -0,0 +1,39 @@
+/** @jsxImportSource @opentui/solid */
+import type { Database } from "bun:sqlite";
+import type { Context, PanelInput } from "@opencode/plugin/tui/context";
+import { type LineFormatOptions, type PanelSettings } from "./panel-data";
+/**
+ * The `/usage` panel. One read-only view over the stats database at a time,
+ * driven entirely from the keyboard: a cursor over the selectable lines,
+ * Enter drills into the row under it, and the views, range, sort, bucket and
+ * filters are part of the state the host persists between openings.
+ *
+ * The panel owns input while it is open, so every key lives in the layer this
+ * component registers — the prompt is not involved.
+ */
+export type PanelDeps = {
+    /** Lazily opened stats database; undefined when it cannot be opened. */
+    db: () => Database | undefined;
+    /** Where that database lives, for the `db` view. */
+    dbPath: () => string;
+    /**
+     * Short-lived write connection for maintenance (prune, compact). The panel
+     * itself only reads; opening a writer on demand is what keeps a read from
+     * ever taking the recorder's lock. Undefined when the write cannot be made.
+     */
+    withWrite?: (<Value>(run: (db: Database) => Value) => Value | undefined) | undefined;
+    /** Injectable clock, for tests. */
+    now: () => number;
+    /** Creation time of a session, used by the `session` range. */
+    sessionStart: (sessionID: string) => number | undefined;
+    /** Bumped by the TUI when a step or an execution ends, so views re-read. */
+    refresh?: (() => number) | undefined;
+};
+export declare function Panel(props: {
+    readonly input: PanelInput;
+    readonly ctx: Context;
+    readonly deps: PanelDeps;
+    readonly settings: PanelSettings;
+    readonly update: (mutation: (draft: PanelSettings) => void) => void;
+    readonly format?: LineFormatOptions | undefined;
+}): any;

package/dist/recorder.d.ts

@@ -0,0 +1,69 @@
+import type { Database } from "bun:sqlite";
+/**
+ * Event-driven recorder. Every handler is idempotent and defensive: the
+ * plugin must never break a session because an event arrived in an
+ * unexpected shape, so unknown events are ignored and malformed payloads are
+ * dropped rather than thrown.
+ *
+ * Everything written comes from the event stream: the step's provider, model
+ * and variant, its tokens, its timing and its outcome. Pure with respect to
+ * its inputs (database plus events) so the whole recording policy can be
+ * unit-tested without the plugin runtime.
+ */
+export type SessionModelRef = {
+    id: string;
+    providerID: string;
+    variant?: string | undefined;
+};
+export type TokenUsageLike = {
+    input?: number | undefined;
+    output?: number | undefined;
+    reasoning?: number | undefined;
+    cache?: {
+        read?: number | undefined;
+        write?: number | undefined;
+    } | undefined;
+};
+export type RecorderEventData = {
+    sessionID?: string | undefined;
+    assistantMessageID?: string | undefined;
+    inboxID?: string | undefined;
+    item?: {
+        type?: string | undefined;
+    } | undefined;
+    started?: number | undefined;
+    model?: SessionModelRef | undefined;
+    previous?: SessionModelRef | undefined;
+    tokens?: TokenUsageLike | undefined;
+    cost?: number | undefined;
+    finish?: string | undefined;
+    rawFinish?: string | undefined;
+    reason?: string | undefined;
+    location?: {
+        directory?: string | undefined;
+    } | undefined;
+    parentID?: string | undefined;
+    title?: string | undefined;
+};
+export type RecorderEvent = {
+    type: string;
+    created?: number | undefined;
+    data?: RecorderEventData | undefined;
+};
+export type PendingStep = {
+    messageID: string;
+    sessionID: string;
+    started: number | undefined;
+    streamed: number | undefined;
+    model: SessionModelRef | undefined;
+};
+export type RecorderOptions = {
+    /** Clock override, for tests. */
+    now?: (() => number) | undefined;
+};
+export type Recorder = {
+    /** Apply one session event. Unknown or malformed events are ignored. */
+    handleEvent(event: RecorderEvent): void;
+    pendingFor(sessionID: string): PendingStep | undefined;
+};
+export declare function createRecorder(db: Database, options?: RecorderOptions): Recorder;

package/dist/sidebar.d.ts

@@ -0,0 +1,25 @@
+/** @jsxImportSource @opentui/solid */
+import type { Database } from "bun:sqlite";
+import type { Context } from "@opencode/plugin/tui/context";
+import { type LineFormatOptions } from "./panel-data";
+/**
+ * Sidebar history: the session's accumulated usage, then the last finished
+ * turns — when and through which provider, the model when it changed, and the
+ * prompt volumes. Reads the same database, the same buckets and the same
+ * formatter as the panel and the live line, and refreshes whenever a turn ends.
+ */
+export type TurnsSidebarDeps = {
+    db: () => Database | undefined;
+    /** Bumped by the TUI when a step or an execution ends. */
+    refresh: () => number;
+    /** How many turns to show. */
+    limit: number;
+    /** Column budget of the sidebar, shared with the summary. */
+    budget?: number | undefined;
+};
+export declare function TurnsSidebar(props: {
+    readonly sessionID: string;
+    readonly ctx: Context;
+    readonly deps: TurnsSidebarDeps;
+    readonly options?: LineFormatOptions | undefined;
+}): any;

package/dist/stats/aggregates.d.ts

@@ -0,0 +1,283 @@
+/**
+ * The analysis layer: the reports the panel and the CLI show.
+ *
+ * Two shapes, chosen by measurement rather than taste:
+ *
+ * 1. **Aggregates in SQLite** — totals, counts, distinct values. `coverageOf`
+ *    and the filter pickers never move a row into JavaScript.
+ * 2. **Narrow rows plus arithmetic in JS** — percentiles, pair rules, calendar
+ *    buckets. SQLite's window functions cost about 17 µs per row per report
+ *    here (a sort plus a materialisation), while reading the four to twelve
+ *    columns a report actually needs costs 1–4 µs per row. The percentiles and
+ *    the pair comparisons are therefore computed over lean projections: on the
+ *    audit's 120k-step database a whole view costs a few hundred milliseconds,
+ *    and on a normal one it is instant.
+ *
+ * The rules are not restated here. Cache reuse, idle gaps and the noise
+ * threshold come from `core.ts` — the same functions the live line uses — so
+ * the panel and the line can never disagree about what a cache loss is.
+ * `test/reports.test.ts` holds every report to those rules.
+ */
+import type { Database } from "bun:sqlite";
+import { type Filters, type LatencyStats, type Range, type Usage } from "./queries";
+/** The step's own clock, the expression the `steps_at` index covers. */
+export declare const STEP_AT = "COALESCE(created_at, recorded_at)";
+type Options = {
+    range?: Range | undefined;
+    filters?: Filters | undefined;
+};
+/** One recorded step, as the reports read it. */
+export type StepRow = {
+    messageID: string;
+    sessionID: string;
+    providerID: string | undefined;
+    modelID: string | undefined;
+    variant: string | undefined;
+    input: number;
+    cached: number;
+    cacheWrite: number;
+    output: number;
+    reasoning: number;
+    cost: number;
+    createdAt: number | undefined;
+    streamedAt: number | undefined;
+    completedAt: number | undefined;
+    /** `COALESCE(created_at, recorded_at)`: the ordering time of the step. */
+    at: number;
+    /** Set on the single step loaded before the range, as a reference. */
+    boundary?: boolean | undefined;
+};
+/**
+ * A step as the pair reports read it. Their projection leaves the generated
+ * tokens out (nothing they compute sums them), and the type says so: an
+ * aggregate that reads `output` cannot be handed a pair row by mistake.
+ */
+export type PairRow = Omit<StepRow, "output" | "reasoning">;
+/** The steps of the range, narrow. Ordering is only paid for where it is read. */
+export declare function stepRows(db: Database, options?: Options): StepRow[];
+/**
+ * The steps of the range plus, for every session with a step inside it, the one
+ * step before the range: the pair reports compare a step with the one that
+ * preceded it, so the first step of a range has to see it.
+ *
+ * The boundary is one seek per session on the `(session_id, time)` index — a
+ * few milliseconds for a far wider history — never the whole history of the
+ * sessions in range.
+ */
+export declare function cachePairs(db: Database, options?: Options): PairRow[];
+export type CoverageReport = {
+    steps: number;
+    models: number;
+    /** Providers the steps ran through. A step whose provider is unknown is counted nowhere. */
+    providers: number;
+    missingModel: number;
+    unsettled: number;
+    missingTps: number;
+    firstAt: number | undefined;
+    lastAt: number | undefined;
+};
+/**
+ * What the panel cannot answer honestly: how many steps lack a model, and how
+ * many never settled. A zero in the switch counts means "never switched" only
+ * when this coverage is complete.
+ */
+export declare function coverageOf(db: Database, options?: Options): CoverageReport;
+/** The steps a latency report is built from. It reads no generated tokens. */
+type GroupedRow = StepRow;
+export type LatencyReport = {
+    wall: LatencyStats;
+    stream: LatencyStats;
+    tps: LatencyStats;
+};
+/** The timings of the range: one read, shared by the overall report and the groups. */
+export declare function timingRows(db: Database, options?: Options): GroupedRow[];
+/** Overall wall time, streaming window and throughput percentiles. */
+export declare function latencyOf(rows: readonly StepRow[]): LatencyReport;
+export type LatencyGroupRow = {
+    key: string;
+    label: string;
+    count: number;
+    usage: Usage;
+    wall: LatencyStats;
+    stream: LatencyStats;
+    tps: LatencyStats;
+};
+export type Dimension = "model" | "provider";
+/** Wall, streaming window and throughput percentiles per group. */
+export declare function latencyGroupsOf(rows: readonly StepRow[], by: Dimension): LatencyGroupRow[];
+export type CacheStats = {
+    steps: number;
+    input: number;
+    cached: number;
+    cacheWrite: number;
+    /** The whole prompt the provider saw: `cached + input + cache_write`. */
+    prompt: number;
+    /** Token-weighted reuse over the whole selection. */
+    hit: number | undefined;
+    /** Median of the per-step reuse ratios: a few huge steps cannot hide a split pattern. */
+    hitP50: number | undefined;
+};
+/** Reuse of the prompt cache over the range, as one row. */
+export declare function cacheStatsOf(db: Database, options?: Options): CacheStats;
+export type CacheModelRow = {
+    modelID: string;
+    variant: string | undefined;
+    cache: CacheStats;
+};
+/**
+ * Reuse of the prompt cache per model, most cached first, over the steps of the
+ * range. A boundary step is not part of the range, so it is left out.
+ */
+export declare function cacheStatsByModel(rows: readonly PairRow[]): CacheModelRow[];
+export type SwitchRow = {
+    modelID: string;
+    variant: string | undefined;
+    steps: number;
+    pairs: number;
+    /** Steps whose model, variant or provider differed from the step before. */
+    changes: number;
+    /** Of those, the ones whose model (or variant) differed. */
+    modelChanges: number;
+    /** Of those, the ones whose provider differed. */
+    providerChanges: number;
+    /** Cache the changes cost: only a provider switch can forfeit a reusable cache. */
+    cacheLost: number;
+    cacheLostEvents: number;
+};
+export type SwitchReport = {
+    rows: SwitchRow[];
+    totals: {
+        pairs: number;
+        changes: number;
+        cacheLost: number;
+        cacheLostEvents: number;
+    };
+};
+/**
+ * Switches between consecutive steps of a session, by the two dimensions that
+ * decide which cache holds the work: the model (with its variant) and the
+ * provider.
+ *
+ * A switch is not by itself a fault — it is usually the user choosing another
+ * model — so the report only names a cost where one is measurable: a provider
+ * switch that leaves the model intact forfeits the cache the previous provider
+ * held. A model switch has no measurable cost by definition, because two models
+ * never share a cache to lose.
+ */
+export declare function switchesOf(rows: readonly PairRow[]): SwitchReport;
+export type GapBucket = {
+    label: string;
+    samples: number;
+    /** Pairs that still reused the prompt cache. */
+    retained: number;
+    drops: number;
+    lostTokens: number;
+    retainedRatio: number | undefined;
+};
+export type ProviderReuseRow = {
+    /** The provider, or `(unknown)` when a step ran without one. */
+    provider: string;
+    samples: number;
+    retained: number;
+    drops: number;
+    lostTokens: number;
+    retainedRatio: number | undefined;
+};
+export type GapReport = {
+    buckets: GapBucket[];
+    providers: ProviderReuseRow[];
+    samples: number;
+};
+/** Idle-gap buckets, coarse enough to read at a glance. */
+export declare const GAP_BUCKETS: ReadonlyArray<readonly [string, number, number | undefined]>;
+/**
+ * How long an idle gap the prompt cache survives, per gap bucket and per
+ * provider. Only pairs of the same model are comparable, which is exactly the
+ * set the cache rule already uses.
+ */
+export declare function gapReportOf(rows: readonly PairRow[]): GapReport;
+export type TtlEvidenceRow = {
+    providerID: string;
+    modelID: string;
+    samples: number;
+    /** Largest idle gap that still hit the cache. */
+    maxHitGapMs: number | undefined;
+    /** Smallest idle gap after which reuse was lost. */
+    minDropGapMs: number | undefined;
+};
+/**
+ * Empirical bounds on the provider cache TTL: the longest idle gap that still
+ * reused the cache, and the shortest gap that lost it. Comparing the two per
+ * provider turns TTL guesses into observations.
+ */
+export declare function ttlEvidenceOf(rows: readonly PairRow[]): TtlEvidenceRow[];
+export type DropReason = "compaction" | "expired" | "unknown";
+export type CacheDropRow = {
+    sessionID: string;
+    messageID: string;
+    providerID: string | undefined;
+    modelID: string | undefined;
+    variant: string | undefined;
+    at: number;
+    tokens: number;
+    gapMs: number | undefined;
+    prevCached: number;
+    reason: DropReason;
+};
+/**
+ * Cache reuse losses with a best-effort reason: a compaction in between, an
+ * idle gap long enough to be provider-side expiry, or unknown.
+ *
+ * Compactions come from the `events` table: one query for the sessions in
+ * play, never one per loss.
+ */
+export declare function cacheDropsOf(db: Database, rows: readonly PairRow[], options?: {
+    ttlHintMs?: number;
+}): CacheDropRow[];
+export type ProviderSummary = {
+    /** The provider, or undefined for steps recorded without one. */
+    provider: string | undefined;
+    /** Models this provider served. */
+    models: string[];
+    share: number;
+    usage: Usage;
+    cache: CacheStats;
+    tps: number | undefined;
+    wall: number | undefined;
+    firstAt: number | undefined;
+    lastAt: number | undefined;
+};
+export type ProviderRow = ProviderSummary & {
+    modelID: string;
+    variant: string | undefined;
+};
+/** One row per provider, over every model it served. */
+export declare function providerSummaryOf(rows: readonly StepRow[]): ProviderSummary[];
+/** One row per model × provider: through which provider each model ran, and how much. */
+export declare function providerBreakdownOf(rows: readonly StepRow[]): ProviderRow[];
+export type PeriodGranularity = "day" | "week" | "month";
+export type PeriodRow = {
+    key: string;
+    label: string;
+    /** Start of the bucket, local time. */
+    at: number;
+    steps: number;
+    sessions: number;
+    usage: Usage;
+    cache: CacheStats;
+};
+/** ISO-8601 week number and its Monday, in local time. */
+export declare function isoWeek(date: Date): {
+    year: number;
+    week: number;
+    monday: Date;
+};
+/** Key, label and local start of the period `at` falls in. */
+export declare function periodStart(at: number, granularity: PeriodGranularity): {
+    key: string;
+    label: string;
+    start: number;
+};
+/** Totals per local calendar day, week or month, oldest first. */
+export declare function periodsOf(rows: readonly StepRow[], granularity: PeriodGranularity): PeriodRow[];
+export {};

package/dist/stats/db.d.ts

@@ -0,0 +1,99 @@
+import { Database } from "bun:sqlite";
+/**
+ * Persistent usage store. One SQLite database holds every recorded step,
+ * prompt, event and session row — and nothing else: the recorder only writes
+ * what a view reads.
+ *
+ * The database is opened in WAL mode with a busy timeout so the server
+ * recorder process and the TUI reader process can share it safely. The two
+ * sides open it differently on purpose:
+ *
+ * - `openStatsDb` writes: schema, migrations and recording (the server).
+ * - `openStatsDbReadOnly` only reads (the TUI), so no view can change the file
+ *   and no reader pays for a schema write.
+ * - `openStatsDbWrite` is a short-lived maintenance connection (prune, vacuum)
+ *   that gives up quickly instead of holding the recorder up.
+ */
+export declare const SCHEMA_VERSION = 9;
+/** Tables carried by `exportNdjson` / `importNdjson`, in import-safe order. */
+export declare const TABLES: readonly ["sessions", "prompts", "events", "steps"];
+export type TableName = (typeof TABLES)[number];
+export type StepRecord = {
+    messageID: string;
+    sessionID: string;
+    parentID?: string | undefined;
+    /** The provider the model ran through, as OpenCode configured it (`opencode-go`). */
+    providerID?: string | undefined;
+    modelID?: string | undefined;
+    variant?: string | undefined;
+    input?: number | undefined;
+    output?: number | undefined;
+    reasoning?: number | undefined;
+    cacheRead?: number | undefined;
+    cacheWrite?: number | undefined;
+    cost?: number | undefined;
+    createdAt?: number | undefined;
+    streamedAt?: number | undefined;
+    completedAt?: number | undefined;
+    finish?: string | undefined;
+    /** Clock of the recording itself, defaults to `Date.now()`. */
+    recordedAt?: number | undefined;
+};
+export type PromptRecord = {
+    sessionID: string;
+    messageID: string;
+    createdAt?: number | undefined;
+};
+export type EventRecord = {
+    sessionID: string;
+    kind: string;
+    messageID?: string | undefined;
+    at?: number | undefined;
+    data?: unknown;
+};
+export type SessionRecord = {
+    sessionID: string;
+    parentID?: string | undefined;
+    directory?: string | undefined;
+    title?: string | undefined;
+    startedAt?: number | undefined;
+    updatedAt?: number | undefined;
+};
+/** Open (creating when needed) the stats database and apply the schema. */
+export declare function openStatsDb(path: string): Database;
+/**
+ * Reader connection for the TUI: no schema, no migration, no write. It throws
+ * when the database is absent or was never written by the recorder, so the
+ * caller can say so instead of showing an empty panel.
+ */
+export declare function openStatsDbReadOnly(path: string): Database;
+/**
+ * Short-lived write connection for maintenance. The busy timeout is short on
+ * purpose: a prune or a vacuum that cannot take the lock must fail in front of
+ * the user, not hold the recorder's response path for seconds.
+ */
+export declare function openStatsDbWrite(path: string): Database;
+/**
+ * Insert or refresh an assistant step. Idempotent by message ID so replayed
+ * events, restarts and NDJSON imports never duplicate usage. A non-null field
+ * (the provider, the model, the finish reason) survives a re-record with `NULL`
+ * through COALESCE.
+ *
+ * The provider is the identity every view groups by, so it is validated as a
+ * token before it is stored: a value that is not a provider id is recorded as
+ * absent instead of becoming a grouping key.
+ */
+export declare function recordStep(db: Database, record: StepRecord): void;
+export declare function recordPrompt(db: Database, record: PromptRecord): void;
+export declare function recordEvent(db: Database, record: EventRecord): void;
+export declare function upsertSession(db: Database, record: SessionRecord): void;
+/** Dump every table as NDJSON (`{"table": "...", "row": {...}}` per line). */
+export declare function exportNdjson(db: Database): string;
+/**
+ * Load an `exportNdjson` dump back in. Rows are inserted with `OR IGNORE`, so
+ * importing the same dump twice is harmless. Unknown tables and rows that are
+ * not objects are rejected; a row that cannot fill a required column is
+ * skipped rather than aborting the rest of the import. A column the row does
+ * not carry is left to its default, the same way a hand-written insert is.
+ */
+export declare function importNdjson(db: Database, text: string): number;

package/dist/stats/maintenance.d.ts

@@ -0,0 +1,49 @@
+import type { Database } from "bun:sqlite";
+import { type TableName } from "./db";
+/**
+ * Database maintenance: what the file holds, how much of it is worth keeping,
+ * and the two operations that give the space back.
+ *
+ * Everything is explicit — nothing here runs on its own. The panel's `db` view
+ * and `bun run report` are the only callers.
+ */
+export type TableSize = {
+    name: string;
+    rows: number;
+};
+export type DbInfo = {
+    path: string;
+    /** Size of the database file, in bytes. */
+    bytes: number;
+    /** Size of its write-ahead log, when one exists. */
+    walBytes: number | undefined;
+    schemaVersion: number;
+    tables: TableSize[];
+    /** Oldest and newest recorded step, the window the views can answer for. */
+    firstAt: number | undefined;
+    lastAt: number | undefined;
+    /** Steps a prune at each cutoff would remove, for the panel to offer choices. */
+    removable: Array<{
+        days: number;
+        steps: number;
+    }>;
+};
+export declare function dbInfo(db: Database, path: string, now?: number): DbInfo;
+export type PruneResult = {
+    steps: number;
+    prompts: number;
+    events: number;
+};
+/**
+ * Delete recorded usage older than `cutoff`. Steps, their prompts and the
+ * compaction events that explain their cache losses go together: a compaction
+ * that no step references answers nothing.
+ */
+export declare function pruneOlderThan(db: Database, cutoff: number): PruneResult;
+/** Reclaim the space a prune freed. Returns the bytes the database lost. */
+export declare function vacuum(db: Database, path: string): {
+    before: number;
+    after: number;
+    freed: number;
+};
+export type { TableName };

package/dist/stats/paths.d.ts

@@ -0,0 +1,35 @@
+/**
+ * SQLite database used when no `db` option is configured: the per-user state
+ * directory of the current OS, never a shared temp directory.
+ *
+ * The subdirectory is the plugin's package name, never a generic one: the
+ * `opencode` tree is shared with OpenCode itself and with every other plugin,
+ * so a `stats/` of our own would be a collision waiting to happen.
+ *
+ * - Windows: `%LOCALAPPDATA%\opencode\opencode-usage-insights\usage.db`
+ * - macOS: `~/Library/Application Support/opencode/opencode-usage-insights/usage.db`
+ * - Linux/other: `$XDG_STATE_HOME/opencode/opencode-usage-insights/usage.db`,
+ *   falling back to `~/.local/state/opencode/opencode-usage-insights/usage.db`
+ *
+ * Pure by design so every OS can be asserted from any machine.
+ */
+export declare function defaultDbPath(env?: Record<string, string | undefined>, platform?: string): string;
+/**
+ * Expand a leading `~` (or `~/`), so a configured path reads the way every
+ * shell does. Windows accepts the backslash form too.
+ */
+export declare function expandHome(path: string, home?: string): string;
+/**
+ * Resolve the effective database path: explicit plugin option first, then the
+ * `OPENCODE_USAGE_INSIGHTS_DB` escape hatch (handy for dev and tests), then
+ * the per-OS state directory. A leading `~` is expanded in all three.
+ */
+export declare function resolveDbPath(configured?: string | undefined, env?: Record<string, string | undefined>, platform?: string): string;
+/**
+ * A configured path must not be a directory, a device or a FIFO: SQLite would
+ * fail obscurely, or write where nobody expects it. Symlinks to a regular file
+ * are followed (`statSync`, not `lstat`) because moving the state directory to
+ * another disk is a legitimate setup. A missing file is fine — the plugin
+ * creates it.
+ */
+export declare function ensureRegularFile(path: string): void;