@relayburn/sdk 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to `@relayburn/sdk`.
 
 ## [Unreleased]
 
+## [1.10.0] - 2026-05-03
+
+### Breaking Changes
+
+- `hotspots()` now returns a discriminated union (`{ kind: 'attribution' | 'bash' | 'bash-verb' | 'file' | 'subagent' | 'findings' }`) instead of either an attribution blob or a raw findings array. Callers must branch on `kind`. The default (no `groupBy`, no `patterns`) returns the `attribution` shape that mirrors `burn hotspots --json`. Pass `patterns` to get `findings`. Pass `groupBy` to narrow attribution to one axis (`bash` / `bash-verb` / `file` / `subagent`). Warrants the SDK major bump.
+
+### Added
+
+- `hotspots({ groupBy })` narrows attribution to one aggregation axis: `bash`, `bash-verb`, `file`, or `subagent`. Useful for MCP tools and embedders that only want a single per-axis cut.
+- `hotspots({ project, since })` accept the same forwarded options the other SDK queries do (project filter + ISO/relative `since` window normalization).
+- `hotspots()` reads through the SQLite archive by default with transparent fallback to the JSONL ledger walk on archive failure. Pass `onLog` to capture the fallback reason.
+- `hotspots()` surfaces a coverage-refusal shape (`refused: true` + `refusalReason`) when every matched turn lacks the tool-call/tool-result coverage `attributeHotspots` needs, so presenters can map it to the user-facing exit-2 + stderr message.
+
 ## [1.9.0] - 2026-05-03
 
 ### Added

package/README.md

@@ -35,9 +35,16 @@ const cmp = await compare({
 const oh = await overhead({ project: '/path/to/repo', since: '30d' });
 const trim = await overheadTrim({ project: '/path/to/repo', top: 3 });
 
+// Per-axis hotspot attribution + pattern findings. Returns a discriminated
+// union — branch on `kind`:
+//   { kind: 'attribution', files, bashVerbs, bash, subagents, sessions, … }
+//   { kind: 'bash' | 'bash-verb' | 'file' | 'subagent', rows: [...] }
+//   { kind: 'findings', findings: WasteFinding[], summary }
+const attribution = await hotspots({ session: 'session-id' });
+const fileRows = await hotspots({ session: 'session-id', groupBy: 'file' });
 const findings = await hotspots({ session: 'session-id', patterns: ['retry-loop'] });
 ```
 
-`summary`, `sessionCost`, `compare`, `overhead`, and `overheadTrim` read through the SQLite archive when available, transparently falling back to the JSONL ledger walk if the archive can't be opened. Pass `onLog` to surface fallback messages in your host's log channel.
+`summary`, `sessionCost`, `compare`, `overhead`, `overheadTrim`, and `hotspots` read through the SQLite archive when available, transparently falling back to the JSONL ledger walk if the archive can't be opened. Pass `onLog` to surface fallback messages in your host's log channel.
 
 `overheadTrim` includes a unified-diff string per recommendation by default (matches `burn overhead trim --json`); pass `includeDiff: false` to skip the per-file disk reads when you only need the recommendation rows.

package/index.d.ts

@@ -140,8 +140,19 @@ export interface OverheadTrimResult {
 /** Trim recommendations for high-cost overhead-file sections. Powers `burn overhead trim`. */
 export declare function overheadTrim(opts?: OverheadTrimOptions): Promise<OverheadTrimResult>
 
+export type HotspotsGroupBy = 'attribution' | 'bash' | 'bash-verb' | 'file' | 'subagent';
+
 export interface HotspotsOptions {
   session?: string;
+  project?: string;
+  /** ISO timestamp (e.g. `2026-04-01T00:00:00Z`) or relative range (`24h`, `7d`, `4w`, `2m`). */
+  since?: string;
+  /**
+   * Narrow the attribution result to a single aggregation axis. When omitted
+   * (or `'attribution'`), the full attribution shape is returned. Ignored
+   * when `patterns` is set — patterns always returns the `findings` shape.
+   */
+  groupBy?: HotspotsGroupBy;
   /**
    * Pattern kinds to detect. Supported kinds:
    *   - core (via `detectPatterns`): `retry-loop`, `failure-run`,
@@ -149,13 +160,126 @@ export interface HotspotsOptions {
    *     `skill-recall-dup`, `skill-pruning-protection`, `system-prompt-tax`
    *   - side-channel: `tool-output-bloat`, `ghost-surface`, `tool-call-pattern`
    *
-   * When omitted or empty, returns the attribution result instead of a
-   * findings array.
+   * When omitted or empty, returns the attribution result instead of the
+   * findings shape.
    */
   patterns?: string[];
   ledgerHome?: string;
+  /** Optional logger invoked when the SQLite archive read fails and the SDK falls back to a full ledger walk. */
+  onLog?: (msg: string) => void;
 }
-export declare function hotspots(opts?: HotspotsOptions): Promise<unknown>
+
+/** Per-axis aggregation row (file). */
+export interface HotspotsFileRow {
+  path: string;
+  firstEmitTurnIndex: number;
+  initialTokens: number;
+  persistenceTokens: number;
+  ridingTurns: number;
+  totalCost: number;
+}
+
+/** Per-axis aggregation row (bash, exact command). */
+export interface HotspotsBashRow {
+  command: string | undefined;
+  argsHash: string;
+  callCount: number;
+  initialTokens: number;
+  persistenceTokens: number;
+  totalCost: number;
+}
+
+/** Per-axis aggregation row (bash, by leading verb). */
+export interface HotspotsBashVerbRow {
+  verb: string;
+  callCount: number;
+  distinctCommands: number;
+  initialTokens: number;
+  persistenceTokens: number;
+  avgPersistenceTurns: number;
+  totalCost: number;
+  topExamples: string[];
+}
+
+/** Per-axis aggregation row (subagent / Agent / Task). */
+export interface HotspotsSubagentRow {
+  subagentType: string;
+  callCount: number;
+  initialTokens: number;
+  persistenceTokens: number;
+  totalCost: number;
+}
+
+export interface HotspotsSessionTotal {
+  sessionId: string;
+  grandCost: number;
+  attributedCost: number;
+  unattributedCost: number;
+  attributionMethod: 'sized' | 'even-split';
+}
+
+export interface HotspotsFidelityBlock {
+  analyzed: number;
+  excluded: number;
+  /** Aggregate fidelity summary for the matched-window turns (analyzed + excluded). */
+  summary: unknown;
+  refused: boolean;
+}
+
+/** Full attribution shape — mirrors the CLI's `burn hotspots --json`. */
+export interface HotspotsAttributionResult {
+  kind: 'attribution';
+  turnsAnalyzed: number;
+  grandTotal: number;
+  attributedTotal: number;
+  unattributedTotal: number;
+  attributionDegraded: boolean;
+  sessions: HotspotsSessionTotal[];
+  files: HotspotsFileRow[];
+  bashVerbs: HotspotsBashVerbRow[];
+  bash: HotspotsBashRow[];
+  subagents: HotspotsSubagentRow[];
+  fidelity: HotspotsFidelityBlock;
+  /** Set when every matched turn lacked the coverage attribution needs. */
+  refused?: boolean;
+  refusalReason?: string;
+}
+
+/** Narrowed shapes — one aggregation axis only. */
+export interface HotspotsBashResult { kind: 'bash'; rows: HotspotsBashRow[]; refused?: boolean; refusalReason?: string }
+export interface HotspotsBashVerbResult { kind: 'bash-verb'; rows: HotspotsBashVerbRow[]; refused?: boolean; refusalReason?: string }
+export interface HotspotsFileResult { kind: 'file'; rows: HotspotsFileRow[]; refused?: boolean; refusalReason?: string }
+export interface HotspotsSubagentResult { kind: 'subagent'; rows: HotspotsSubagentRow[]; refused?: boolean; refusalReason?: string }
+
+export interface HotspotsFinding {
+  kind: string;
+  severity: string;
+  sessionId: string;
+  title: string;
+  estimatedSavings: { usdPerSession?: number; [k: string]: unknown };
+  [k: string]: unknown;
+}
+
+export interface HotspotsFindingsResult {
+  kind: 'findings';
+  findings: HotspotsFinding[];
+  /** Aggregate fidelity summary for the matched-window turns. */
+  summary: unknown;
+}
+
+export type HotspotsResult =
+  | HotspotsAttributionResult
+  | HotspotsBashResult
+  | HotspotsBashVerbResult
+  | HotspotsFileResult
+  | HotspotsSubagentResult
+  | HotspotsFindingsResult;
+
+/**
+ * Per-axis hotspot attribution + pattern-finding queries. Returns a
+ * discriminated union — see `HotspotsResult`.
+ */
+export declare function hotspots(opts?: HotspotsOptions): Promise<HotspotsResult>
 
 export type FidelityClass = 'full' | 'usage-only' | 'aggregate-only' | 'cost-only' | 'partial';
 

package/index.js

@@ -7,6 +7,10 @@ import {
   queryToolResultEvents,
 } from '@relayburn/ledger';
 import {
+  aggregateByBash,
+  aggregateByBashVerb,
+  aggregateByFile,
+  aggregateBySubagent,
   attributeOverhead,
   buildCompareTable,
   buildGhostSurfaceInputs,
@@ -36,7 +40,7 @@ import {
   userClaudeSettingsPath,
 } from '@relayburn/analyze';
 import { ingestAll } from '@relayburn/ingest';
-import { resolveProject } from '@relayburn/reader';
+import { parseBashCommand, resolveProject } from '@relayburn/reader';
 import { readFile } from 'node:fs/promises';
 import * as path from 'node:path';
 
@@ -228,59 +232,261 @@ export async function sessionCost(opts = {}) {
   });
 }
 
+// Coverage flags `attributeHotspots` and the matching aggregators need.
+// Records without `fidelity` (older ledger writers, foreign sources) are
+// treated as best-effort full and pass the gate. Mirrors
+// `ATTRIBUTION_REQUIRED` + `turnPassesCoverage` in the CLI.
+const HOTSPOTS_ATTRIBUTION_REQUIRED = ['hasToolCalls', 'hasToolResultEvents'];
+
+function turnPassesCoverage(turn, required) {
+  const f = turn.fidelity;
+  if (!f) return true;
+  for (const key of required) {
+    if (!f.coverage[key]) return false;
+  }
+  return true;
+}
+
+const VALID_HOTSPOTS_GROUP_BY = ['attribution', 'bash', 'bash-verb', 'file', 'subagent'];
+
+// Expanded hotspots(): returns a discriminated union covering every shape the
+// CLI's `burn hotspots --json` (and a few narrower programmatic cuts) need.
+//
+//   { kind: 'attribution' }                       — full per-axis aggregations
+//   { kind: 'bash' | 'bash-verb' | 'file' |
+//          'subagent' }                           — narrow to one aggregation
+//   { kind: 'findings' }                          — pattern findings (when
+//                                                   `patterns` is set)
+//
+// `groupBy` and `patterns` are mutually exclusive: passing `patterns` always
+// returns the findings shape and `groupBy` is ignored.
+//
+// Pattern detectors that need extra data (Claude settings, tool-result events,
+// on-disk ghost surface) are loaded lazily based on the requested patterns,
+// the same way the CLI does — so passing only `['retry-loop']` won't pay for
+// a settings.json read.
 export async function hotspots(opts = {}) {
   return withHome(opts.ledgerHome, async () => {
-    const turns = await queryAll({ sessionId: opts.session });
-    const userTurns = await queryUserTurns({ sessionId: opts.session });
+    const usingPatterns = opts.patterns && opts.patterns.length > 0;
+
+    // Only validate `groupBy` when it actually steers the result. Per the
+    // documented mutual-exclusivity, passing `patterns` always returns
+    // findings and `groupBy` is ignored — including when its value is
+    // unknown — so callers that pass through a stale `groupBy` alongside
+    // `patterns` keep working.
+    if (
+      !usingPatterns &&
+      opts.groupBy !== undefined &&
+      !VALID_HOTSPOTS_GROUP_BY.includes(opts.groupBy)
+    ) {
+      throw new Error(
+        `invalid hotspots groupBy: ${JSON.stringify(opts.groupBy)} ` +
+          `(expected one of: ${VALID_HOTSPOTS_GROUP_BY.join(', ')})`,
+      );
+    }
+
+    const q = q_(opts);
+    const turns = await loadTurnsViaArchive(q, opts.onLog);
     const pricing = await loadPricing();
-    const userTurnsBySession = bucketBySession(userTurns);
-    const attribution = attributeHotspots(turns, { pricing, userTurnsBySession });
 
-    if (!opts.patterns || opts.patterns.length === 0) return attribution;
+    if (usingPatterns) {
+      return runHotspotsFindings(turns, pricing, opts, q);
+    }
 
-    const wanted = new Set(opts.patterns);
-    const findings = [];
+    return runHotspotsAttribution(turns, pricing, opts, q);
+  });
+}
 
-    // Core patterns (retries, failures, edit-heavy, etc.) flow through
-    // detectPatterns + findingsFromPatterns; non-matching kinds are filtered.
-    const detected = detectPatterns(turns, { pricing, userTurnsBySession });
-    for (const f of findingsFromPatterns(detected)) {
-      if (wanted.has(f.kind)) findings.push(f);
-    }
+async function runHotspotsAttribution(turns, pricing, opts, q = {}) {
+  const eligible = [];
+  const excluded = [];
+  for (const t of turns) {
+    if (turnPassesCoverage(t, HOTSPOTS_ATTRIBUTION_REQUIRED)) eligible.push(t);
+    else excluded.push(t);
+  }
 
-    // Side-channel detectors live outside detectPatterns. Each one reads its
-    // own slice of state, so we run them lazily based on `wanted`.
-
-    if (wanted.has('tool-output-bloat')) {
-      const settings = [];
-      const userLoaded = await loadClaudeSettings(userClaudeSettingsPath());
-      if (userLoaded) settings.push(userLoaded);
-      const projectLoaded = await loadClaudeSettings(projectClaudeSettingsPath());
-      if (projectLoaded) settings.push(projectLoaded);
-      const toolResultEvents = await queryToolResultEvents({ sessionId: opts.session });
-      const bloats = detectToolOutputBloat({
-        settings,
-        toolResultEvents,
-        userTurns,
-        turns,
-        pricing,
-      });
-      for (const b of bloats) findings.push(toolOutputBloatToFinding(b));
-    }
+  const fidelitySummary = summarizeFidelity(turns);
 
-    if (wanted.has('ghost-surface')) {
-      const ghostInputs = await buildGhostSurfaceInputs(turns, pricing);
-      const ghosts = await detectGhostSurface(ghostInputs);
-      for (const g of ghosts) findings.push(ghostSurfaceToFinding(g));
+  // Refusal: nothing to attribute. Mirror the CLI's refused-shape so callers
+  // can branch on `refused` without re-deriving the reason.
+  if (turns.length > 0 && eligible.length === 0) {
+    const refusalReason =
+      `${turns.length}/${turns.length} turns lack tool-call/tool-result coverage required for hotspots attribution`;
+    const groupBy = opts.groupBy ?? 'attribution';
+    if (groupBy !== 'attribution') {
+      return { kind: groupBy, rows: [], refused: true, refusalReason };
     }
+    return {
+      kind: 'attribution',
+      turnsAnalyzed: 0,
+      grandTotal: 0,
+      attributedTotal: 0,
+      unattributedTotal: 0,
+      attributionDegraded: false,
+      sessions: [],
+      files: [],
+      bashVerbs: [],
+      bash: [],
+      subagents: [],
+      fidelity: {
+        analyzed: 0,
+        excluded: turns.length,
+        summary: fidelitySummary,
+        refused: true,
+      },
+      refused: true,
+      refusalReason,
+    };
+  }
 
-    if (wanted.has('tool-call-pattern')) {
-      const patterns = detectToolCallPatterns(turns, { pricing });
-      for (const p of patterns) findings.push(toolCallPatternToFinding(p));
-    }
+  const sessionIds = new Set(eligible.map((t) => t.sessionId));
+  // Reuse the precomputed `q` from the caller — `normalizeSince()` calls
+  // `Date.now()` for relative ranges, so re-deriving here would cut the
+  // user-turn window at a slightly later boundary than the turn slice and
+  // drop borderline records.
+  const userTurnsBySession = await bulkUserTurnsBySession(sessionIds, q);
+  const result = attributeHotspots(eligible, { pricing, userTurnsBySession });
+
+  const groupBy = opts.groupBy ?? 'attribution';
+  if (groupBy === 'bash') {
+    return { kind: 'bash', rows: aggregateByBash(result.attributions) };
+  }
+  if (groupBy === 'bash-verb') {
+    return {
+      kind: 'bash-verb',
+      rows: aggregateByBashVerb(result.attributions, parseBashCommand),
+    };
+  }
+  if (groupBy === 'file') {
+    return { kind: 'file', rows: aggregateByFile(result.attributions) };
+  }
+  if (groupBy === 'subagent') {
+    return { kind: 'subagent', rows: aggregateBySubagent(result.attributions) };
+  }
 
-    return findings;
-  });
+  const files = aggregateByFile(result.attributions);
+  const bashVerbs = aggregateByBashVerb(result.attributions, parseBashCommand);
+  const bash = aggregateByBash(result.attributions);
+  const subagents = aggregateBySubagent(result.attributions);
+  const evenSplit = result.sessionTotals.filter(
+    (s) => s.attributionMethod === 'even-split',
+  ).length;
+  const attributionDegraded =
+    result.sessionTotals.length > 0 &&
+    evenSplit / result.sessionTotals.length >= 0.5;
+
+  return {
+    kind: 'attribution',
+    turnsAnalyzed: eligible.length,
+    grandTotal: result.grandTotal,
+    attributedTotal: result.attributedTotal,
+    unattributedTotal: result.unattributedTotal,
+    attributionDegraded,
+    sessions: result.sessionTotals,
+    files,
+    bashVerbs,
+    bash,
+    subagents,
+    fidelity: {
+      analyzed: eligible.length,
+      excluded: excluded.length,
+      summary: fidelitySummary,
+      refused: false,
+    },
+  };
+}
+
+async function runHotspotsFindings(turns, pricing, opts, q = {}) {
+  const wanted = new Set(opts.patterns);
+  const findings = [];
+  // Forward `since` (and `sessionId`) so the user-turn + tool-result-event
+  // streams stay inside the same matched window the turn slice uses.
+  // Without this, detectors that read user-turn or tool-result-event state
+  // (system-prompt-tax, tool-output-bloat, retry/failure/cancellation graph
+  // walks) would mix older pre-window events into windowed analysis and
+  // surface false findings on long-lived sessions.
+  const sideQuery = {};
+  if (q.sessionId !== undefined) sideQuery.sessionId = q.sessionId;
+  if (q.since !== undefined) sideQuery.since = q.since;
+  const userTurns = await queryUserTurns(sideQuery);
+  const userTurnsBySession = bucketBySession(userTurns);
+
+  // Core patterns (retries, failures, edit-heavy, etc.) flow through
+  // detectPatterns + findingsFromPatterns; non-matching kinds are filtered.
+  const detected = detectPatterns(turns, { pricing, userTurnsBySession });
+  for (const f of findingsFromPatterns(detected)) {
+    if (wanted.has(f.kind)) findings.push(f);
+  }
+
+  // Side-channel detectors live outside detectPatterns. Each one reads its
+  // own slice of state, so we run them lazily based on `wanted`.
+
+  if (wanted.has('tool-output-bloat')) {
+    const settings = [];
+    const userLoaded = await loadClaudeSettings(userClaudeSettingsPath());
+    if (userLoaded) settings.push(userLoaded);
+    const projectLoaded = await loadClaudeSettings(projectClaudeSettingsPath());
+    if (projectLoaded) settings.push(projectLoaded);
+    const toolResultEvents = await queryToolResultEvents(sideQuery);
+    const bloats = detectToolOutputBloat({
+      settings,
+      toolResultEvents,
+      userTurns,
+      turns,
+      pricing,
+    });
+    for (const b of bloats) findings.push(toolOutputBloatToFinding(b));
+  }
+
+  if (wanted.has('ghost-surface')) {
+    const ghostInputs = await buildGhostSurfaceInputs(turns, pricing);
+    const ghosts = await detectGhostSurface(ghostInputs);
+    for (const g of ghosts) findings.push(ghostSurfaceToFinding(g));
+  }
+
+  if (wanted.has('tool-call-pattern')) {
+    const patterns = detectToolCallPatterns(turns, { pricing });
+    for (const p of patterns) findings.push(toolCallPatternToFinding(p));
+  }
+
+  return {
+    kind: 'findings',
+    findings,
+    summary: summarizeFidelity(turns),
+  };
+}
+
+// Build the ledger Query from SDK opts. Used by the bulk user-turn loader so
+// it narrows by `since`/`source` during streaming rather than buffering the
+// entire historical ledger. Mirrors the CLI's same trick.
+function q_(opts) {
+  const q = {};
+  if (opts.session) q.sessionId = opts.session;
+  if (opts.project) q.project = opts.project;
+  const since = normalizeSince(opts.since);
+  if (since) q.since = since;
+  return q;
+}
+
+// One ledger pass + in-memory bucket. Mirrors the CLI's `bulkUserTurnsBySession`:
+// the per-session form `queryUserTurns({sessionId})` re-streams the entire
+// ledger.jsonl on every call, so we issue a single bulk pass here and bucket
+// by sessionId. `since`/`source` are forwarded so the streaming filter narrows
+// the in-memory buffer to the same window the eligible turns live in.
+async function bulkUserTurnsBySession(sessionIds, q = {}) {
+  const out = new Map();
+  if (sessionIds.size === 0) return out;
+  const filter = {};
+  if (q.since !== undefined) filter.since = q.since;
+  if (q.source !== undefined) filter.source = q.source;
+  const all = await queryUserTurns(filter);
+  for (const ut of all) {
+    if (!sessionIds.has(ut.sessionId)) continue;
+    const list = out.get(ut.sessionId);
+    if (list) list.push(ut);
+    else out.set(ut.sessionId, [ut]);
+  }
+  return out;
 }
 
 function bucketBySession(userTurns) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayburn/sdk",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Embeddable Relayburn SDK for in-process ingest, summary, and hotspots queries",
   "type": "module",
   "main": "./index.js",
@@ -16,10 +16,10 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@relayburn/analyze": "1.9.0",
-    "@relayburn/ingest": "1.9.0",
-    "@relayburn/ledger": "1.9.0",
-    "@relayburn/reader": "1.9.0"
+    "@relayburn/analyze": "1.10.0",
+    "@relayburn/ingest": "1.10.0",
+    "@relayburn/ledger": "1.10.0",
+    "@relayburn/reader": "1.10.0"
   },
   "repository": {
     "type": "git",