@relayburn/sdk 2.8.7 → 2.10.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [2.10.0] - 2026-05-24
+
+### Added
+
+- `hotspots()` attribution result carries a new `mcpServers` field —
+  per-server rollup of `mcp__<server>__<tool>` tool calls with summed
+  cost/tokens/ride-turns and top representative tool basenames. (#424)
+
+## [2.9.0] - 2026-05-21
+
+### Added
+
+- `writeStamp({ sessionId | messageId, enrichment, ts?, ledgerHome? })` writes
+  a stamp by exact selector — companion to `writePendingStamp` for launchers
+  that preallocate the session id (Claude `--session-id`).
+
 ## [2.5.0] - 2026-05-08
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayburn/sdk",
-  "version": "2.8.7",
+  "version": "2.10.0",
   "description": "Embeddable Relayburn SDK — napi-rs bindings over the Rust relayburn-sdk crate (2.x). Drop-in replacement for the TS @relayburn/sdk@1.x.",
   "type": "module",
   "main": "./src/index.js",
@@ -43,10 +43,10 @@
     ]
   },
   "optionalDependencies": {
-    "@relayburn/sdk-darwin-arm64": "2.8.7",
-    "@relayburn/sdk-darwin-x64": "2.8.7",
-    "@relayburn/sdk-linux-arm64-gnu": "2.8.7",
-    "@relayburn/sdk-linux-x64-gnu": "2.8.7"
+    "@relayburn/sdk-darwin-arm64": "2.10.0",
+    "@relayburn/sdk-darwin-x64": "2.10.0",
+    "@relayburn/sdk-linux-arm64-gnu": "2.10.0",
+    "@relayburn/sdk-linux-x64-gnu": "2.10.0"
   },
   "devDependencies": {
     "@napi-rs/cli": "^2.18.4",

package/src/index.d.ts

@@ -58,6 +58,27 @@ export declare function writePendingStamp(
   opts: WritePendingStampOptions,
 ): Promise<PendingStampWriteResult>
 
+export interface WriteStampOptions {
+  /** Target a session by exact id. At least one of `sessionId` or `messageId` must be set. */
+  sessionId?: string;
+  /** Target a single turn by exact message id. At least one of `sessionId` or `messageId` must be set. */
+  messageId?: string;
+  /** Enrichment key/value pairs to fold onto matched turns. Must be non-empty. */
+  enrichment: Record<string, string>;
+  /** ISO timestamp the caller observed, e.g. `2026-05-21T12:00:00Z`. Defaults to now when omitted. */
+  ts?: string;
+  ledgerHome?: string;
+}
+
+/**
+ * Write a stamp targeting an exact session id or message id. Use when the
+ * launcher knows the session id up front — for example, a Claude launcher
+ * that preallocates `--session-id <uuid>` before spawn — so the
+ * enrichment lands by selector without going through the sidecar
+ * `writePendingStamp` manifest matching path.
+ */
+export declare function writeStamp(opts: WriteStampOptions): Promise<void>
+
 export interface SummaryOptions {
   session?: string;
   project?: string;
@@ -259,6 +280,18 @@ export interface HotspotsSubagentRow {
   totalCost: number;
 }
 
+export interface HotspotsMcpServerRow {
+  /** MCP server name (the `<server>` segment of `mcp__<server>__<tool>`). */
+  server: string;
+  callCount: number;
+  initialTokens: number | bigint;
+  persistenceTokens: number | bigint;
+  ridingTurns: number;
+  totalCost: number;
+  /** Up to three representative tool basenames (cost desc, then name asc). */
+  topTools: string[];
+}
+
 export interface HotspotsSessionTotal {
   sessionId: string;
   grandCost: number;
@@ -286,6 +319,7 @@ export interface HotspotsAttributionResult {
   bashVerbs: HotspotsBashVerbRow[];
   bash: HotspotsBashRow[];
   subagents: HotspotsSubagentRow[];
+  mcpServers: HotspotsMcpServerRow[];
   fidelity: HotspotsFidelityBlock;
   refused?: boolean;
   refusalReason?: string;

package/src/index.js

@@ -124,6 +124,10 @@ export async function writePendingStamp(opts) {
   return coerceBigInts(await binding.writePendingStamp(opts));
 }
 
+export async function writeStamp(opts) {
+  await binding.writeStamp(opts);
+}
+
 export function computeCompareExcluded(summary, minimum) {
   const out = { total: 0, aggregateOnly: 0, costOnly: 0, partial: 0, usageOnly: 0 };
   if (minimum === 'partial') return out;