@relayburn/sdk 1.6.2 → 1.7.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@relayburn/sdk`.
 
 ## [Unreleased]
 
+## [1.7.0] - 2026-05-02
+
+### Added
+
+- `hotspots({ patterns })` now also surfaces `tool-output-bloat`, `ghost-surface`, and `tool-call-pattern` findings (previously only the core `detectPatterns` set). Each side-channel detector loads its own inputs (Claude settings, tool-result events, on-disk surface) lazily based on the requested patterns.
+
 ## [1.5.0] - 2026-05-01
 
 ### Added

package/index.d.ts

@@ -7,5 +7,19 @@ export declare function ingest(opts?: IngestOptions): Promise<unknown>
 export interface SummaryOptions { session?: string; project?: string; since?: string; ledgerHome?: string }
 export declare function summary(opts?: SummaryOptions): Promise<{ totalTokens: number; totalCost: number; byTool: Array<{tool:string;tokens:number;cost:number;count:number}>; byModel: Array<{model:string;tokens:number;cost:number}> }>
 
-export interface HotspotsOptions { session?: string; patterns?: string[]; ledgerHome?: string }
+export interface HotspotsOptions {
+  session?: string;
+  /**
+   * Pattern kinds to detect. Supported kinds:
+   *   - core (via `detectPatterns`): `retry-loop`, `failure-run`,
+   *     `cancellation-run`, `compaction-loss`, `edit-revert`, `edit-heavy`,
+   *     `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.
+   */
+  patterns?: string[];
+  ledgerHome?: string;
+}
 export declare function hotspots(opts?: HotspotsOptions): Promise<unknown>

package/index.js

@@ -1,6 +1,21 @@
-import { queryAll, queryUserTurns } from '@relayburn/ledger';
-import { loadPricing, costForTurn, attributeHotspots, detectPatterns, findingsFromPatterns } from '@relayburn/analyze';
-import { ingestAll } from '@relayburn/cli';
+import { queryAll, queryUserTurns, queryToolResultEvents } from '@relayburn/ledger';
+import {
+  loadPricing,
+  costForTurn,
+  attributeHotspots,
+  detectPatterns,
+  findingsFromPatterns,
+  detectToolOutputBloat,
+  toolOutputBloatToFinding,
+  detectGhostSurface,
+  ghostSurfaceToFinding,
+  detectToolCallPatterns,
+  toolCallPatternToFinding,
+  loadClaudeSettings,
+  userClaudeSettingsPath,
+  projectClaudeSettingsPath,
+} from '@relayburn/analyze';
+import { ingestAll, buildGhostSurfaceInputs } from '@relayburn/cli';
 
 function withHome(home, fn) {
   const prev = process.env.RELAYBURN_HOME;
@@ -71,11 +86,63 @@ 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 attribution = attributeHotspots({ turns, userTurns });
+    const pricing = await loadPricing();
+    const userTurnsBySession = bucketBySession(userTurns);
+    const attribution = attributeHotspots(turns, { pricing, userTurnsBySession });
 
     if (!opts.patterns || opts.patterns.length === 0) return attribution;
 
-    const detected = detectPatterns({ turns, userTurns, hotspots: attribution });
-    return findingsFromPatterns(detected).filter((f) => opts.patterns.includes(f.kind));
+    const wanted = new Set(opts.patterns);
+    const findings = [];
+
+    // 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({ sessionId: opts.session });
+      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 findings;
   });
 }
+
+function bucketBySession(userTurns) {
+  const out = new Map();
+  for (const ut of userTurns) {
+    const list = out.get(ut.sessionId);
+    if (list) list.push(ut);
+    else out.set(ut.sessionId, [ut]);
+  }
+  return out;
+}

package/package.json

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