@oh-my-pi/omp-stats 18.16.0 → 18.17.0

package/dist/types/client/api.d.ts

@@ -1,4 +1,4 @@
-import type { CostDashboardStats, FolderStats, FrustrationDashboardStats, FrustrationEstimate, FrustrationJobStatus, GainDashboardStats, LiveStatus, MessageStats, ModelDashboardStats, OverviewStats, ProviderDashboardStats, ProviderWindowStats, RequestDetails, SessionSummary, SessionTrace, TimeRange, ToolDashboardStats } from "./types.js";
+import type { CostDashboardStats, FolderStats, FrustrationDashboardStats, FrustrationEstimate, FrustrationJobStatus, GainDashboardStats, LiveStatus, MessageStats, ModelDashboardStats, OverviewStats, ProviderDashboardStats, ProviderWindowStats, RequestDetails, SessionSummary, SessionTrace, SpotlightAgentScope, SpotlightDashboardStats, SpotlightSessionContext, TimeRange, ToolDashboardStats } from "./types.js";
 export declare class ApiError extends Error {
     status: number;
     endpoint: string;
@@ -24,6 +24,9 @@ export declare function startFrustrationRun(range: TimeRange): Promise<Frustrati
 export declare function cancelFrustrationRun(): Promise<FrustrationJobStatus>;
 export declare function getFolderStats(range?: TimeRange, signal?: AbortSignal): Promise<FolderStats[]>;
 export declare function getGainDashboardStats(range?: TimeRange, project?: string | null, signal?: AbortSignal): Promise<GainDashboardStats>;
+export declare function getSpotlightDashboardStats(range?: TimeRange, agent?: SpotlightAgentScope, signal?: AbortSignal): Promise<SpotlightDashboardStats>;
+/** One experiment session's context per request, with and without shaping. */
+export declare function getSpotlightSessionContext(file: string, signal?: AbortSignal): Promise<SpotlightSessionContext>;
 export declare function getToolDashboardStats(range?: TimeRange, signal?: AbortSignal): Promise<ToolDashboardStats>;
 export declare function getProviderDashboardStats(range?: TimeRange, signal?: AbortSignal): Promise<ProviderDashboardStats>;
 /** Subscription-window insights (all providers) plus utilization series for `provider` only. */

package/dist/types/client/app/nav.d.ts

@@ -1,5 +1,5 @@
 import { type LucideIcon } from "lucide-react";
-export type DashboardSection = "overview" | "models" | "providers" | "costs" | "requests" | "errors" | "traces" | "tools" | "frustration" | "projects" | "gain";
+export type DashboardSection = "overview" | "models" | "providers" | "costs" | "requests" | "errors" | "traces" | "tools" | "frustration" | "projects" | "gain" | "spotlight";
 export interface NavItem {
     id: DashboardSection;
     label: string;

package/dist/types/client/charts/Chart.d.ts

@@ -1,13 +1,14 @@
 /**
- * Core SVG chart: categorical x slots, stacked or grouped bars, stacked areas
- * and lines, an optional right axis, a hover cursor and a floating tooltip.
- * Marks are crisp and unsmoothed — square bars, straight segments.
+ * Core SVG chart: categorical x slots, stacked or grouped bars, stacked areas,
+ * lines and dots, an optional right axis, a hover cursor and a floating tooltip.
+ * Marks are crisp and unsmoothed — square bars, straight segments. Negative
+ * values extend the axis below zero (bars hang down from the baseline).
  *
  * `TimeChart` wraps this for bucketed time series; use `Chart` directly for
  * categorical axes (hour of day, model names).
  */
 import { type ReactNode } from "react";
-import type { ChartKind, ChartSeries, ReferenceLine } from "./types.js";
+import type { ChartKind, ChartSeries, ReferenceLine, SlotMarker } from "./types.js";
 export interface ChartProps {
     /** Number of x positions; every series' `values` has this length. */
     slots: number;
@@ -35,15 +36,22 @@ export interface ChartProps {
     /** Show a total row in the tooltip. Default: stacked with 2+ series. */
     showTotal?: boolean;
     references?: readonly ReferenceLine[];
+    /** Vertical guides at x slots, labelled along the top edge. */
+    markers?: readonly SlotMarker[];
     onSelect?: (index: number) => void;
     /** Shown over empty axes when every visible value is zero. */
     emptyLabel?: ReactNode;
     /** Extra tooltip rows for a slot (below the series rows). */
     tooltipExtra?: (index: number) => ReactNode;
 }
-export declare function Chart({ slots, tickLabel, tooltipTitle, series, kind, stacked, height, format, formatRight, formatTooltip, yMax, yMaxRight, hidden, showTotal, references, onSelect, emptyLabel, tooltipExtra, }: ChartProps): import("react").JSX.Element;
-/** Round an axis maximum up to 1/2/2.5/5 × 10ⁿ and return evenly spaced ticks from 0. */
-export declare function niceScale(max: number): {
+export declare function Chart({ slots, tickLabel, tooltipTitle, series, kind, stacked, height, format, formatRight, formatTooltip, yMax, yMaxRight, hidden, showTotal, references, markers, onSelect, emptyLabel, tooltipExtra, }: ChartProps): import("react").JSX.Element;
+export interface AxisScale {
+    min: number;
     max: number;
     ticks: number[];
-};
+}
+/**
+ * Round an axis span out to 1/2/2.5/5 × 10ⁿ steps and return evenly spaced
+ * ticks. The span always includes zero; `min` (default 0) extends it below.
+ */
+export declare function niceScale(max: number, min?: number): AxisScale;

package/dist/types/client/charts/DotWhisker.d.ts

@@ -0,0 +1,50 @@
+import type { ReactNode } from "react";
+/** One estimate on a row: a point and its interval. */
+export interface DotWhiskerMark {
+    key: string;
+    value: number | null;
+    lo: number | null;
+    hi: number | null;
+    color: string;
+    /** `dot` (default) filled; `ring` hollow (a counterfactual); `diamond` a reference level; `square` a variant. */
+    shape?: "dot" | "ring" | "diamond" | "square";
+    /** Vertical offset from the row's center in px, to keep several marks of one row apart. */
+    offset?: number;
+    /** Hover text naming the mark. */
+    title?: string;
+}
+export interface DotWhiskerRow {
+    key: string;
+    label: ReactNode;
+    marks: readonly DotWhiskerMark[];
+    /** Right-column figure; defaults to the first mark's value. */
+    figure?: ReactNode;
+    /** Small print under the figure; defaults to the first mark's interval. */
+    detail?: ReactNode;
+}
+export interface DotWhiskerGuide {
+    key: string;
+    value: number;
+    color: string;
+}
+/** A shaded span through every row (e.g. a reference's interval). */
+export interface DotWhiskerBand {
+    lo: number;
+    hi: number;
+    color: string;
+}
+export interface DotWhiskerProps {
+    rows: readonly DotWhiskerRow[];
+    /** Vertical guides through every row (e.g. chance levels). */
+    guides?: readonly DotWhiskerGuide[];
+    band?: DotWhiskerBand;
+    format: (value: number) => string;
+    /** Axis tick formatter; defaults to `format`. */
+    formatTick?: (value: number) => string;
+}
+/**
+ * Point estimates with their intervals on one shared axis that always spans
+ * zero (and extends below it for signed values), one row per group. Layout is
+ * percentage-based, so it never measures the DOM.
+ */
+export declare function DotWhisker({ rows, guides, band, format, formatTick }: DotWhiskerProps): import("react").JSX.Element;

package/dist/types/client/charts/Sparkline.d.ts

@@ -7,5 +7,5 @@ export interface SparklineProps {
     /** Fill under the line. Default true. */
     area?: boolean;
 }
-/** Axis-free trend line for stat tiles and table cells. */
+/** Axis-free trend line for stat tiles and table cells; negative values dip below the zero line. */
 export declare function Sparkline({ values, color, height, width, area }: SparklineProps): import("react").JSX.Element;

package/dist/types/client/charts/Waterfall.d.ts

@@ -0,0 +1,26 @@
+import type { ReactNode } from "react";
+export interface WaterfallStep {
+    key: string;
+    label: ReactNode;
+    /** `total` bars start at zero and reset the running total; `delta` bars float from it. */
+    kind: "total" | "delta";
+    /** A total's level, or a delta's signed change. */
+    value: number;
+    /** Any CSS background (solid color or gradient). */
+    color: string;
+    /** Dim figure after the value (e.g. share of the first total). */
+    note?: ReactNode;
+    title?: string;
+}
+export interface WaterfallProps {
+    steps: readonly WaterfallStep[];
+    /** Formats magnitudes; deltas get their sign from the component. */
+    format: (value: number) => string;
+}
+/**
+ * Horizontal bridge chart: a total, the changes that eat into it, and the
+ * total left at the end. Rows read top to bottom; dashed connectors carry the
+ * running total from one bar to the next. Pure layout (percentages), so it
+ * never measures the DOM and reflows with its column.
+ */
+export declare function Waterfall({ steps, format }: WaterfallProps): import("react").JSX.Element;

package/dist/types/client/charts/index.d.ts

@@ -1,7 +1,9 @@
 export * from "./BarList.js";
 export * from "./Chart.js";
+export * from "./DotWhisker.js";
 export * from "./Legend.js";
 export * from "./ShareBar.js";
 export * from "./Sparkline.js";
 export * from "./TimeChart.js";
 export * from "./types.js";
+export * from "./Waterfall.js";

package/dist/types/client/charts/types.d.ts

@@ -11,12 +11,18 @@ export interface ChartSeries {
     axis?: "left" | "right";
     /** Diagonal hatching instead of a solid fill (bars/areas). */
     pattern?: "hatch";
-    /** Dashed stroke (lines). */
+    /** Dashed stroke (lines, area outlines). */
     dashed?: boolean;
     /** Leave this series out of the tooltip (e.g. a trend line that repeats a bar). */
     tooltip?: false;
 }
-export type ChartKind = "bars" | "area" | "line";
+/** `dots` marks each value with a point and no connecting segment (raw samples under a trend line). */
+export type ChartKind = "bars" | "area" | "line" | "dots";
+/** Vertical guide at an x slot (e.g. an experiment start or a compaction). */
+export interface SlotMarker {
+    index: number;
+    label?: string;
+}
 /** Horizontal guide drawn across the plot (e.g. a 100% capacity line). */
 export interface ReferenceLine {
     value: number;

package/dist/types/client/routes/SpotlightRoute.d.ts

@@ -0,0 +1,7 @@
+import type { TimeRange } from "../types.js";
+import "../spotlight/spotlight.css";
+export interface SpotlightRouteProps {
+    active: boolean;
+    range: TimeRange;
+}
+export declare function SpotlightRoute({ active, range }: SpotlightRouteProps): import("react").JSX.Element;

package/dist/types/client/routes/index.d.ts

@@ -7,5 +7,6 @@ export * from "./OverviewRoute.js";
 export * from "./ProjectsRoute.js";
 export * from "./ProvidersRoute.js";
 export * from "./RequestsRoute.js";
+export * from "./SpotlightRoute.js";
 export * from "./ToolsRoute.js";
 export * from "./TracesRoute.js";

package/dist/types/client/spotlight/Compounding.d.ts

@@ -0,0 +1,8 @@
+import type { SpotlightDashboardStats } from "../types.js";
+export interface CompoundingProps {
+    stats: SpotlightDashboardStats;
+    active: boolean;
+    stale: boolean;
+}
+/** A cut keeps paying: every later request would have re-read it. One session's context with and without shaping. */
+export declare function Compounding({ stats, active, stale }: CompoundingProps): import("react").JSX.Element;

package/dist/types/client/spotlight/Coverage.d.ts

@@ -0,0 +1,6 @@
+import type { SpotlightDashboardStats } from "../types.js";
+/** Which tools' output the models of experiment sessions saw, shaped and not: where shaping could reach next. */
+export declare function Coverage({ stats, stale }: {
+    stats: SpotlightDashboardStats;
+    stale: boolean;
+}): import("react").JSX.Element;

package/dist/types/client/spotlight/Economics.d.ts

@@ -0,0 +1,10 @@
+import type { SpotlightDashboardStats } from "../types.js";
+export interface EconomicsProps {
+    stats: SpotlightDashboardStats;
+    stale: boolean;
+}
+/**
+ * Per tool: what a hundred cuts earn after fetch-backs, extra turns and Spotlight's bill. Tools with cuts, the
+ * largest saving first; past the top ones the rest sum into one `other` column.
+ */
+export declare function Economics({ stats, stale }: EconomicsProps): import("react").JSX.Element;

package/dist/types/client/spotlight/FetchBack.d.ts

@@ -0,0 +1,9 @@
+import type { SpotlightDashboardStats } from "../types.js";
+export interface FetchBackProps {
+    stats: SpotlightDashboardStats;
+    stale: boolean;
+}
+/** Fetch-back rate per tool: the scored cut against the score-free one, the random holdout and the unchanged results. */
+export declare function FetchBack({ stats, stale }: FetchBackProps): import("react").JSX.Element;
+/** How many calls after the cut the agent fetched back, per tool, shortened against held out. */
+export declare function FetchBackGaps({ stats, stale }: FetchBackProps): import("react").JSX.Element;

package/dist/types/client/spotlight/Hero.d.ts

@@ -0,0 +1,12 @@
+import type { SpotlightDashboardStats } from "../types.js";
+export interface SpotlightHeroProps {
+    stats: SpotlightDashboardStats;
+    /** Prose window ("the last 7 days"). */
+    windowLabel: string;
+    stale: boolean;
+}
+/**
+ * Headline: the holdout-adjusted net (tokens and $, with intervals) against what `plain` would have shown, the old
+ * full-output figure struck through as the baseline note, then gross, the excess fetch-back and the sample.
+ */
+export declare function SpotlightHero({ stats, windowLabel, stale }: SpotlightHeroProps): import("react").JSX.Element;

package/dist/types/client/spotlight/Overhead.d.ts

@@ -0,0 +1,6 @@
+import type { SpotlightDashboardStats } from "../types.js";
+/** What shaping costs in latency, reliability and Spotlight's bill. */
+export declare function Overhead({ stats, stale }: {
+    stats: SpotlightDashboardStats;
+    stale: boolean;
+}): import("react").JSX.Element;

package/dist/types/client/spotlight/Ranking.d.ts

@@ -0,0 +1,6 @@
+import type { SpotlightDashboardStats } from "../types.js";
+/** Per-line ranking quality: Spotlight's heat and the cut against the lines the agent needed later. */
+export declare function Ranking({ stats, stale }: {
+    stats: SpotlightDashboardStats;
+    stale: boolean;
+}): import("react").JSX.Element;

package/dist/types/client/spotlight/ResultsFeed.d.ts

@@ -0,0 +1,6 @@
+import type { SpotlightResultRow } from "../types.js";
+/** The 60 newest shortened results; a row opens its recovery timeline. */
+export declare function ResultsFeed({ rows, stale }: {
+    rows: readonly SpotlightResultRow[];
+    stale: boolean;
+}): import("react").JSX.Element;

package/dist/types/client/spotlight/Savings.d.ts

@@ -0,0 +1,10 @@
+import type { SpotlightDashboardStats, TimeRange } from "../types.js";
+export interface SavingsProps {
+    stats: SpotlightDashboardStats;
+    range: TimeRange;
+    stale: boolean;
+}
+/** Cumulative gross vs net per bucket, with what recoveries took back hanging below zero. */
+export declare function SavingsOverTime({ stats, range, stale }: SavingsProps): import("react").JSX.Element;
+/** Bridge from gross to the holdout-adjusted net: every way the saving was undone, and what would have come back anyway. */
+export declare function WhereSavingsWent({ stats, stale }: Omit<SavingsProps, "range">): import("react").JSX.Element;

package/dist/types/client/spotlight/ShareTrend.d.ts

@@ -0,0 +1,8 @@
+import type { SpotlightDashboardStats, TimeRange } from "../types.js";
+export interface ShareTrendProps {
+    stats: SpotlightDashboardStats;
+    range: TimeRange;
+    stale: boolean;
+}
+/** Share of context that is tool output, per session group, raw per bucket and as a rolling ratio. */
+export declare function ShareTrend({ stats, range, stale }: ShareTrendProps): import("react").JSX.Element;

package/dist/types/client/spotlight/Steps.d.ts

@@ -0,0 +1,6 @@
+import type { SpotlightDashboardStats } from "../types.js";
+/** Tool × shaping steps × cut size: how much of each kind of cut's saving stays saved after fetch-backs. */
+export declare function Steps({ stats, stale }: {
+    stats: SpotlightDashboardStats;
+    stale: boolean;
+}): import("react").JSX.Element;

package/dist/types/client/spotlight/TimeCost.d.ts

@@ -0,0 +1,6 @@
+import type { SpotlightDashboardStats } from "../types.js";
+/** Share of the experiment's agent time spent on requests that only fetched cut output back, and on shaping. */
+export declare function TimeCost({ stats, stale }: {
+    stats: SpotlightDashboardStats;
+    stale: boolean;
+}): import("react").JSX.Element;

package/dist/types/client/spotlight/chips.d.ts

@@ -0,0 +1,16 @@
+import type { SpotlightCutGroup, SpotlightRecoveryKind } from "../types.js";
+/** Key to the fetch-back groups: each group's mark shape and color, its rule on hover. */
+export declare function GroupLegend({ groups }: {
+    groups: readonly SpotlightCutGroup[];
+}): import("react").JSX.Element;
+/** Shows or hides the tools a card folded away (see `foldTools`). */
+export declare function MoreTools({ hidden, expanded, onToggle, }: {
+    hidden: readonly string[];
+    expanded: boolean;
+    onToggle: () => void;
+}): import("react").JSX.Element;
+/** Recovery kind pill: icon, label (or a count) in the kind's color. */
+export declare function KindBadge({ kind, count }: {
+    kind: SpotlightRecoveryKind;
+    count?: number;
+}): import("react").JSX.Element;

package/dist/types/client/spotlight/meta.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Spotlight vocabulary shared by the page's sections: recovery-kind and
+ * tool labels, their colors (CSS variables from `spotlight.css`, so both
+ * themes resolve them) and signed number formatting.
+ */
+import { type LucideIcon } from "lucide-react";
+import type { SpotlightCutGroup, SpotlightDashboardStats, SpotlightEstimate, SpotlightGapBin, SpotlightRecoveryKind, SpotlightSizeBin, SpotlightTool } from "../types.js";
+export declare const RECOVERY_KINDS: readonly SpotlightRecoveryKind[];
+export interface RecoveryKindMeta {
+    label: string;
+    /** Plural, for waterfall steps and totals. */
+    plural: string;
+    icon: LucideIcon;
+    color: string;
+    /** One-line rule, for tooltips. */
+    rule: string;
+}
+export declare const RECOVERY_KIND: Record<SpotlightRecoveryKind, RecoveryKindMeta>;
+/** The range's evaluated tools, the largest saving first (the order of `gross.byTool`). */
+export declare function toolsBySaving(stats: SpotlightDashboardStats): SpotlightTool[];
+/** Tools a card lists by name before the rest fold into `other` (or behind a "more tools" toggle). */
+export declare const TOP_TOOLS = 6;
+/** The folded rest's label where tools are rows or columns. */
+export declare const OTHER_TOOLS = "other";
+/**
+ * Split tools (ordered) into the first `limit` a card lists and the rest it folds; a lone leftover is listed
+ * instead.
+ */
+export declare function foldTools<T>(items: readonly T[], limit?: number): {
+    listed: readonly T[];
+    rest: readonly T[];
+};
+export interface CutGroupMeta {
+    label: string;
+    color: string;
+    /** Its mark in dot-whisker charts. */
+    shape: "dot" | "ring" | "diamond" | "square";
+    /** One-line definition, for tooltips and legends. */
+    rule: string;
+}
+/**
+ * The fetch-back comparison's groups. The cut is vivid; the score-free cut
+ * (the same shaping without Spotlight's scores) takes its own hue; the two
+ * baselines are neutral inks, the held-out one (the true counterfactual) the
+ * stronger.
+ */
+export declare const CUT_GROUP: Record<SpotlightCutGroup, CutGroupMeta>;
+export declare const CUT_GROUPS: readonly SpotlightCutGroup[];
+export declare const SIZE_BINS: readonly SpotlightSizeBin[];
+export declare const GAP_BINS: readonly SpotlightGapBin[];
+/** A tool's icon; tools without one of their own (MCP and extension tools) get a generic wrench. */
+export declare function toolIcon(tool: SpotlightTool): LucideIcon;
+/** What one time bucket of the range is called in prose ("hour", "day"). */
+export declare function bucketNoun(bucketMs: number): string;
+/** Compact token count with a real minus sign. */
+export declare function formatSignedCompact(value: number): string;
+/** Dollar amount with a real minus sign (`formatCost` alone prints `$-0.12`). */
+export declare function formatSignedCost(value: number): string;
+/** A relative change as a signed percentage (`+12%`, `−3.5%`), `–` when undefined. */
+export declare function formatSignedShare(value: number | null): string;
+/** An estimate's 90% interval as `lo–hi`, empty when it has none. */
+export declare function formatInterval(estimate: SpotlightEstimate, format: (value: number) => string): string;
+/** Share as a whole or one-decimal percentage, `–` when undefined. */
+export declare function formatShare(value: number | null): string;

package/dist/types/db.d.ts

@@ -1,5 +1,6 @@
 import { Database } from "bun:sqlite";
 import { type ParseSessionResult, type SessionParserState } from "./parser.js";
+import { type SpotlightCallResultLink, type SpotlightCallRow, type SpotlightNeedRow, type SpotlightRequestRow, type SpotlightSessionRow, type SpotlightShapeRow } from "./spotlight-ingest.js";
 import type { DailyActivityPoint, FrustrationCounts, MessageStats, MessageStatsInput, ToolCallStats, ToolResultLink, UserMessageLink, UserMessageStats } from "./types.js";
 /**
  * Predicate counting one stored request as "unpriced" — the public rate card
@@ -188,3 +189,28 @@ export declare function insertToolCalls(calls: Iterable<ToolCallStats>): number;
  * never match.
  */
 export declare function updateToolResults(links: Iterable<ToolResultLink>): number;
+/** Record each experiment session's first Spotlight marker; a later one (a resumed session) never replaces it. */
+export declare function insertSpotlightSessions(rows: Iterable<SpotlightSessionRow>): number;
+export declare function updateSpotlightTitles(rows: Iterable<{
+    sessionFile: string;
+    title: string;
+}>): number;
+/**
+ * Upsert evaluated results. The shape entry and the result message can land in
+ * different tail parses: the shape entry brings Spotlight's usage and timing,
+ * the result's details the hidden lines and named artifacts, and either may
+ * come first. Fork copies of a call (same tool call id under another
+ * transcript) are skipped, first writer wins.
+ */
+export declare function upsertSpotlightShapes(rows: Iterable<SpotlightShapeRow>): number;
+/**
+ * Merge needed lines of shaped reads: ranges add to the stored ones (a tail parse brings only its own calls'),
+ * `open` takes the latest. A fork's copy of another transcript's read is skipped, first writer wins.
+ */
+export declare function upsertSpotlightNeeds(rows: Iterable<SpotlightNeedRow>): number;
+/** Insert experiment-session tool calls; fork copies are skipped as for `tool_calls`. */
+export declare function insertSpotlightCalls(rows: Iterable<SpotlightCallRow>): number;
+/** Attach result size and named artifacts to recorded calls (results can land in a later tail parse). */
+export declare function updateSpotlightCallResults(links: Iterable<SpotlightCallResultLink>): number;
+/** Insert experiment-session main-loop requests; fork copies are skipped as for `messages`. */
+export declare function insertSpotlightRequests(rows: Iterable<SpotlightRequestRow>): number;

package/dist/types/index.d.ts

@@ -5,7 +5,8 @@ export { refreshRollups } from "./rollup.js";
 export type { StatsJudge, StatsJudgeProvider } from "./frustration.js";
 export { getGainDashboardStats } from "./gain-aggregator.js";
 export { formatStatsDashboardUrl, type StartServerOptions, setStatsCloseHandler, startServer } from "./server.js";
-export type { GainDashboardStats, GainSource, GainSourceTotals, GainTimeSeriesPoint } from "./shared-types.js";
+export type { GainDashboardStats, GainSource, GainSourceTotals, GainTimeSeriesPoint, SpotlightAgentScope, SpotlightDashboardStats, SpotlightSessionContext, } from "./shared-types.js";
+export { getSpotlightDashboardStats, getSpotlightSessionContext } from "./spotlight-aggregator.js";
 export type { AggregatedStats, DashboardStats, FolderStats, MessageStats, ModelPerformancePoint, ModelStats, ModelTimeSeriesPoint, TimeSeriesPoint, ToolDashboardStats, ToolModelStats, ToolTimeSeriesPoint, ToolUsageStats, } from "./types.js";
 /**
  * Print the dashboard summary to the console. Shared by `omp stats --summary`

package/dist/types/parser.d.ts

@@ -1,6 +1,7 @@
 import type * as nodeFs from "node:fs";
 import { type ServiceTierByFamily } from "@oh-my-pi/pi-ai";
 import type { AgentType, MessageStatsInput, SessionEntry, ToolCallStats, ToolResultLink, UserMessageLink, UserMessageStats } from "./types.js";
+import { type SpotlightParseRows, type SpotlightParserState } from "./spotlight-ingest.js";
 /**
  * Classify which agent produced a transcript from its path within the sessions
  * directory. Layout: `<sessionsDir>/<project>/<file>.jsonl` is the `main`
@@ -56,6 +57,8 @@ export interface SessionParserState {
     mtimeMs: number;
     checkpoint: string;
     serviceTier: ServiceTierByFamily | null;
+    /** Absent in cursors persisted before the Spotlight tables; such a tail parse starts from an empty state. */
+    spotlight?: SpotlightParserState;
 }
 export interface ParseSessionResult {
     stats: MessageStatsInput[];
@@ -63,6 +66,7 @@ export interface ParseSessionResult {
     userLinks: UserMessageLink[];
     toolCalls: ToolCallStats[];
     toolResults: ToolResultLink[];
+    spotlight: SpotlightParseRows;
     newOffset: number;
     parserState?: SessionParserState;
     reset?: boolean;

package/dist/types/rollup.d.ts

@@ -25,7 +25,7 @@
  * (an hour of data is small and indexed by timestamp).
  */
 import type { Database } from "bun:sqlite";
-import type { AgentTypeStats, AggregatedStats, CostTimeSeriesPoint, DailyActivityPoint, FolderStats, ModelPerformancePoint, ModelStats, ModelTimeSeriesPoint, ProviderAggregate, ProviderHourlyPoint, ProviderTimeSeriesPoint, TimeSeriesPoint, ToolModelStats, ToolTimeSeriesPoint, ToolUsageStats } from "./types.js";
+import type { AgentType, AgentTypeStats, AggregatedStats, CostTimeSeriesPoint, DailyActivityPoint, FolderStats, ModelPerformancePoint, ModelStats, ModelTimeSeriesPoint, ProviderAggregate, ProviderHourlyPoint, ProviderTimeSeriesPoint, TimeSeriesPoint, ToolModelStats, ToolTimeSeriesPoint, ToolUsageStats } from "./types.js";
 /**
  * Create (or rebuild after a version bump) the rollup tables and the triggers
  * that mark hours dirty. Called from `initDb` after the raw tables exist.
@@ -121,3 +121,24 @@ export declare function getToolStats(cutoff?: number | null): ToolUsageStats[];
 export declare function getToolStatsByModel(cutoff?: number | null): ToolModelStats[];
 /** Calls and errors per bucket per tool. */
 export declare function getToolTimeSeries({ cutoff, bucketMs }: RangeWindow): ToolTimeSeriesPoint[];
+/** Per-bucket context facts of every transcript of one agent type: tool-result characters and output tokens. */
+export interface ContextFactPoint {
+    bucket: number;
+    agentType: AgentType;
+    resultChars: number;
+    outputTokens: number;
+}
+/** {@link ContextFactPoint}s over a window, from the rollups (exact while few hours are dirty). */
+export declare function getContextFactSeries(database: Database, { cutoff, bucketMs }: RangeWindow): ContextFactPoint[];
+/** A transcript's request span and its first request's prompt (input + cache read + cache write). */
+export interface SessionSpan {
+    sessionFile: string;
+    startedAt: number;
+    endedAt: number;
+    firstPrompt: number;
+}
+/**
+ * Spans of the transcripts with a request at or after `endedAfter` (all when null), from `session_rollup` with
+ * the same exactness rule as {@link getSessionRollups}.
+ */
+export declare function getSessionSpans(database: Database, endedAfter: number | null): SessionSpan[];