opencode-usage-insights 0.0.0-stage → 0.1.1

package/dist/stats/queries.d.ts

@@ -0,0 +1,239 @@
+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 provider 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 provider the model ran through, as OpenCode configured it
+     * (`opencode-go`, `deepseek`, `deepinfra`). It is the identity every view
+     * groups by: a gateway may re-route the request, but the upstream that
+     * actually ran it is not observable.
+     */
+    provider?: 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;
+    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 "through which provider is this model actually coming, 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;
+    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[];
+export type FilterOption = {
+    value: string;
+    steps: number;
+};
+/** Distinct models and providers, most used first. */
+export declare function filterOptions(db: Database): {
+    models: FilterOption[];
+    providers: FilterOption[];
+};

package/dist/text.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Text hygiene for everything that reaches a terminal.
+ *
+ * Some of what the plugin displays is not written by the user: 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;

package/dist/tui.d.ts

@@ -0,0 +1,53 @@
+/** @jsxImportSource @opentui/solid */
+import { Plugin } from "@opencode/plugin/tui";
+import { type LineFields, 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 provider and model that ran
+ *   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 line is computed from the host's transcript alone; the database is opened
+ * lazily for the panel and the sidebar, read-only in spirit: the TUI never
+ * writes usage. When the database cannot be opened, the line still works 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;
+    /**
+     * 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;