opencode-usage-insights 0.0.0-stage → 0.1.0

package/dist/stats/db.d.ts

@@ -0,0 +1,108 @@
+import { Database } from "bun:sqlite";
+import type { EndpointInfo } from "../endpoint";
+/**
+ * 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 = 8;
+/** 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;
+    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;
+    /** Gateway routing endpoint that served the request (`orcarouter-dsv4.1flash`). */
+    router?: 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. Non-null fields
+ * discovered later (the routing endpoint) survive a re-record with `NULL`
+ * through COALESCE.
+ */
+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;
+/**
+ * Attach the endpoint discovered after the step was recorded. A step that
+ * already carries the same endpoint is left alone: the recorder runs on the
+ * request path, and a no-op write there is a cost with no reader.
+ */
+export declare function setStepRouter(db: Database, messageID: string, info: EndpointInfo): void;
+/**
+ * Apply the endpoint learned from a compaction to every step of that session
+ * and model that still lacks one. Returns the number of rows touched.
+ */
+export declare function setStepRouterForSessionModel(db: Database, sessionID: string, modelID: string | undefined, info: EndpointInfo): number;
+/** 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;

package/dist/stats/queries.d.ts

@@ -0,0 +1,259 @@
+import type { Database } from "bun:sqlite";
+/**
+ * Read side of the stats engine: every function takes an open database and
+ * returns plain rows for the TUI panel, the report script and the NDJSON
+ * exports. Aggregations stay in SQL; comparisons and percentiles that would
+ * need window functions or custom SQLite builds are computed in JS.
+ */
+/** Event kind written by the recorder when a compaction completes. */
+export declare const COMPACTION_KIND = "compaction";
+/**
+ * Idle gap above which a cache reuse loss is attributed to provider-side
+ * expiry rather than to a mid-session event. Heuristic: the empirical TTL
+ * evidence view narrows this down with real observations.
+ */
+export declare const DEFAULT_TTL_HINT_MS: number;
+export type Range = {
+    from?: number | undefined;
+    to?: number | undefined;
+};
+/**
+ * Panel filters. They narrow every aggregation to one model, one endpoint or
+ * one session, and are applied with the same `WHERE` builder the range uses so
+ * a filtered view and a drill-down agree.
+ */
+export type Filters = {
+    /** Model id, variant excluded. */
+    modelID?: string | undefined;
+    /**
+     * One model *and* its variant, as `modelKey` builds it (`m1#max`). A variant
+     * is a different model to the provider, so a drill-down into one variant must
+     * not pick up its family.
+     */
+    modelKey?: string | undefined;
+    /**
+     * The routing endpoint that served the request (`router`). It is the one
+     * identity that answers "who ran this inference": the provider you configured
+     * says where the request came from, which is evidence, not an answer.
+     */
+    router?: string | undefined;
+    /**
+     * One session, exactly. Used by the `session` range and by the overview's
+     * "this session" block, which must not pick up the steps of every other
+     * session that happened to run after it started.
+     */
+    sessionID?: string | undefined;
+};
+export type Usage = {
+    steps: number;
+    input: number;
+    cached: number;
+    cacheWrite: number;
+    output: number;
+    reasoning: number;
+    cost: number;
+};
+export declare const STEP_TIME = "COALESCE(created_at, recorded_at)";
+/**
+ * The identity of a model *and* its variant, in SQL: `modelKey` says a variant
+ * is a different model to the provider, so a variant never shares a row with
+ * its family. The JS twin is `modelKey` below; both have to agree.
+ */
+export declare const MODEL_KEY_SQL = "COALESCE(model_id, '(unknown)') || '#' || COALESCE(variant, '')";
+/** `modelKey(modelID, variant)`: the family, with the variant as a suffix. */
+export declare function modelKey(modelID: string, variant: string | undefined): string;
+/** Human label of a model key or a model id and variant. */
+export declare function modelLabel(modelID: string, variant: string | undefined): string;
+/**
+ * `WHERE` for a range plus the panel filters. Shared with the analysis layer so
+ * a filtered view and a drill-down agree on what is in scope.
+ */
+export declare function buildWhere(range: Range | undefined, filters?: Filters | undefined, column?: string): {
+    where: string;
+    params: (string | number)[];
+};
+/**
+ * Share of the whole prompt that came from the cache. The denominator is what
+ * the provider saw: cache reads, fresh input and cache writes.
+ */
+export declare function cacheHitRatio(usage: Pick<Usage, "input" | "cached" | "cacheWrite">): number | undefined;
+export type Overview = Usage & {
+    sessions: number;
+    prompts: number;
+    firstAt: number | undefined;
+    lastAt: number | undefined;
+    cacheHitRatio: number | undefined;
+    /**
+     * Tokens generated per second of streaming, over the whole selection: the
+     * produced tokens divided by the summed streaming windows. A weighted average,
+     * not the mean of the per-step rates the latency view reports as p50.
+     */
+    tps: number | undefined;
+};
+export declare function overview(db: Database, range?: Range, filters?: Filters): Overview;
+export type ProviderUsage = Usage & {
+    providerID: string;
+    /** Gateway routing endpoints that served the requests. */
+    routers: string[];
+    firstAt: number | undefined;
+    lastAt: number | undefined;
+};
+export type ModelUsage = {
+    modelID: string;
+    variant: string | undefined;
+    providers: ProviderUsage[];
+    totals: Usage;
+};
+/**
+ * Usage per model, each with the providers that served it. This is the view
+ * that answers "which inference providers is this model actually coming from
+ * over the selected period".
+ */
+export declare function models(db: Database, range?: Range, filters?: Filters): ModelUsage[];
+export type TimelineBucket = {
+    at: number;
+} & Usage;
+/** Usage aggregated into fixed time buckets (for example one hour or day). */
+export declare function timeline(db: Database, range: Range | undefined, bucketMs: number): TimelineBucket[];
+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;
+};
+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;
+};
+export type LatencyStats = {
+    count: number;
+    p50: number | undefined;
+    p90: number | undefined;
+    p99: number | undefined;
+};
+export type LatencyReport = {
+    /** Milliseconds from request to completed response. */
+    wall: LatencyStats;
+    /** Milliseconds from request to the last streamed chunk (the streaming window). */
+    stream: LatencyStats;
+    /** Output-plus-reasoning tokens per second over that window. */
+    tps: LatencyStats;
+};
+/** Nearest-rank percentile over an unsorted sample. */
+export declare function percentile(values: readonly number[], p: number): number | undefined;
+export declare function latencyStats(values: number[]): LatencyStats;
+export type SessionUsage = Usage & {
+    sessionID: string;
+    parentID: string | undefined;
+    title: string | undefined;
+    directory: string | undefined;
+    providers: string[];
+    models: string[];
+    prompts: number;
+    firstAt: number | undefined;
+    lastAt: number | undefined;
+    cacheHitRatio: number | undefined;
+};
+export declare function sessions(db: Database, options?: {
+    range?: Range;
+    filters?: Filters;
+    limit?: number;
+    sessionIDs?: readonly string[];
+}): SessionUsage[];
+/** Sessions whose parent is `parentID`: the subagents of one session. */
+export declare function childSessionIDs(db: Database, parentID: string): string[];
+/** Session usage rows for a specific set of sessions (subagent rollups). */
+export declare function sessionUsageOf(db: Database, sessionIDs: readonly string[]): SessionUsage[];
+export type TurnDrop = {
+    messageID: string;
+    tokens: number;
+    gapMs: number | undefined;
+};
+/**
+ * One finished turn of a session, built from the recorded steps and prompts. It
+ * carries the same buckets the telemetry line uses, so the panel can render the
+ * per-prompt history with the line's own formatter.
+ */
+export type TurnUsage = {
+    sessionID: string;
+    /** Creation time of the prompt that opened the turn, when it was recorded. */
+    promptAt: number | undefined;
+    endAt: number | undefined;
+    /** Time between the previous prompt of the session and this turn's prompt. */
+    promptGapMs: number | undefined;
+    providerID: string | undefined;
+    modelID: string | undefined;
+    variant: string | undefined;
+    router: string | undefined;
+    /** The displayed identity differs from the previous turn of the session. */
+    routerChanged: boolean;
+    providerChanged: boolean;
+    modelChanged: boolean;
+    steps: number;
+    /** Raw buckets of the last step: the prompt the turn ended with. */
+    latest: Usage;
+    /** Raw buckets summed over every step of the turn. */
+    totals: Usage;
+    drops: TurnDrop[];
+    /** Finish reason of the turn's last step. */
+    finish: string | undefined;
+    /**
+     * Tokens generated per second of streaming over the turn's steps: produced
+     * tokens divided by their summed streaming windows. For a one-step turn it is
+     * that step's rate.
+     */
+    tps: number | undefined;
+};
+/**
+ * Finished turns, newest first. Steps belong to the newest prompt recorded at or
+ * before them; a turn whose last step asked for tools is dropped, because it is
+ * still running — the same rule the telemetry line follows.
+ *
+ * For one session the read is bounded by a window: only the steps at or after
+ * the `limit`-th newest prompt are loaded, so a session with tens of thousands
+ * of steps costs the same as a short one. The extra prompt is kept as the
+ * reference the oldest returned turn measures its gap against.
+ */
+export declare function turns(db: Database, options?: {
+    sessionID?: string | undefined;
+    range?: Range | undefined;
+    filters?: Filters | undefined;
+    limit?: number | undefined;
+}): TurnUsage[];
+/**
+ * Routing endpoint of the newest step recorded before `at`. The TUI compares
+ * it with the endpoint of the turn it is about to render, because the same
+ * provider and model can be routed to a different endpoint per request.
+ */
+export declare function routerBefore(db: Database, sessionID: string, at: number | undefined): string | undefined;
+/**
+ * Routing endpoint of one turn: the newest endpoint the recorder stored for
+ * the given steps of a session. The TUI reads this for the telemetry line
+ * because the line renders from the TUI process while the recorder (the server
+ * process) is still writing the step that just finished. Scoped to the turn's
+ * own steps on purpose: the same provider and model can be routed to a
+ * different endpoint per request, so the newest endpoint of the session is not
+ * necessarily the one that served the turn being rendered.
+ */
+export declare function routerForSteps(db: Database, sessionID: string, messageIDs: readonly string[]): string | undefined;
+export type FilterOption = {
+    value: string;
+    steps: number;
+};
+/** Distinct models and endpoints, most used first. */
+export declare function filterOptions(db: Database): {
+    models: FilterOption[];
+    endpoints: FilterOption[];
+};

package/dist/text.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Text hygiene for everything that reaches a terminal.
+ *
+ * Some of what the plugin displays is not written by the user: a gateway names
+ * its own endpoint in a response header, a model writes a session title, an
+ * NDJSON export can come from anywhere. A control character in any of those is
+ * interpreted by the terminal that renders it (title changes, cursor moves,
+ * colours), so every such string is stripped of control characters before it
+ * is stored or drawn.
+ *
+ * The rule is deliberately blunt: drop C0 controls, DEL and the C1 block, keep
+ * everything else (the text is otherwise arbitrary Unicode), and cap the
+ * length so a hostile value cannot bloat the database or the frame. Layout is
+ * never touched: whitespace is preserved, because callers build indentation
+ * into the strings they truncate.
+ */
+/** Longest value kept by default: a title, an id or a path, not a document. */
+export declare const TEXT_LIMIT = 512;
+/**
+ * Strip control characters and cap the length. Newlines and tabs go too: a
+ * line is one line, and the renderers lay out their own spacing.
+ */
+export declare function sanitizeText(value: string, limit?: number): string;
+/** `sanitizeText` without the layout, for a stored label: trimmed as well. */
+export declare function sanitizeLabel(value: string, limit?: number): string;
+export declare function isToken(value: string, limit?: number): boolean;
+/** The lowercase form of a token identity, so the same endpoint groups once. */
+export declare function normalizeToken(value: string, limit?: number): string | undefined;

package/dist/tui.d.ts

@@ -0,0 +1,58 @@
+/** @jsxImportSource @opentui/solid */
+import { Plugin } from "@opencode/plugin/tui";
+import { type LineFields, type LineIdentity, type LineLabels, type TurnStats, type TurnTotalsView } from "./core";
+import { type PanelView, type RangeKey } from "./panel-data";
+/**
+ * TUI side of the plugin. Two contributions:
+ *
+ * - `session.composer.top`: one telemetry line after every turn with the end
+ *   time, the delta since the previous prompt, the endpoint that served it,
+ *   turn and session token totals, and cache warnings.
+ * - `session.panel` + the `/stats` slash command: the statistics panel over
+ *   the database written by the server entry.
+ *
+ * The database is opened lazily and read-only in spirit: the TUI never
+ * writes usage. When the database cannot be opened, the line falls back to
+ * host data only and the panel explains itself.
+ */
+export type Options = {
+    /** Turn the TUI side off: no line and no panel. */
+    enabled?: boolean | undefined;
+    /** SQLite database path override; must match the server entry. */
+    db?: string | undefined;
+    /**
+     * Which identity the line leads with: `endpoint` (default) shows the gateway
+     * endpoint that served the turn (`orcarouter-dsv4.1flash`) and warns when it
+     * changes; `model` shows `provider/model#variant` as before.
+     */
+    identity?: LineIdentity | undefined;
+    /**
+     * How the turn segment counts prompt usage: `latest` (default) shows the
+     * prompt size the turn ended with, `sum` adds every step of the turn.
+     */
+    turnTotals?: TurnTotalsView | undefined;
+    /** Telemetry line field toggles. */
+    fields?: Partial<LineFields> | undefined;
+    /** Telemetry line label overrides. */
+    labels?: Partial<LineLabels> | undefined;
+    /** Show the per-prompt history in the session sidebar (default true). */
+    sidebar?: boolean | undefined;
+    /** How many turns the sidebar history shows (default 5). */
+    sidebarTurns?: number | undefined;
+    /**
+     * Show the `/usage` statistics panel and its command (default true).
+     * `false` keeps the live line and the sidebar history.
+     */
+    panel?: boolean | undefined;
+};
+export declare const __test: {
+    line: ((sessionID: string) => TurnStats | undefined) | undefined;
+    lineText: ((sessionID: string) => string) | undefined;
+    open: ((input?: string) => boolean) | undefined;
+    state: (() => {
+        view: PanelView;
+        range: RangeKey;
+    }) | undefined;
+};
+declare const _default: Plugin.Definition;
+export default _default;