session-steward 0.7.0 → 0.9.0

package/lib/server.mjs

@@ -865,6 +865,9 @@ export async function startLocalServer({ claudeHome, codexHome, configDirectory,
           id,
           limit: getSessionEventLimit(requestUrl.searchParams.get("limit")),
           signal: controller.signal,
+          // The scan is already streaming the whole transcript, so the count
+          // comes back with it rather than costing a second pass over it.
+          tokens: true,
         });
 
         if (controller.signal.aborted) return;
@@ -878,6 +881,33 @@ export async function startLocalServer({ claudeHome, codexHome, configDirectory,
         return;
       }
 
+      if (request.method === "GET" && requestUrl.pathname === "/api/session-tokens") {
+        const controller = new AbortController();
+        const abortRead = () => controller.abort();
+        request.once("aborted", abortRead);
+        response.once("close", () => {
+          if (!response.writableEnded) abortRead();
+        });
+        const providerId = resolveProviderId(requestUrl.searchParams.get("provider"));
+        const provider = getProvider(providerId);
+        const id = getSessionId(requestUrl.searchParams.get("id"));
+        const tokens = await provider.readSessionTokens({
+          ...providerOptions(providerId, settings.getHome(providerId)),
+          id,
+          signal: controller.signal,
+        });
+
+        if (controller.signal.aborted) return;
+
+        if (!tokens) {
+          sendJson(response, 404, { error: "Session not found." });
+          return;
+        }
+
+        sendJson(response, 200, { tokens });
+        return;
+      }
+
       if (request.method === "GET" && requestUrl.pathname.startsWith("/api/sessions/")) {
         const providerId = resolveProviderId(requestUrl.searchParams.get("provider"));
         const provider = getProvider(providerId);

package/lib/session-events.mjs

@@ -318,6 +318,7 @@ export function createSessionEventsResult({
   header,
   reason = null,
   summary,
+  tokens = null,
   window = {},
 } = {}) {
   const normalizedCoverage = createSessionEventCoverage(coverage);
@@ -370,6 +371,9 @@ export function createSessionEventsResult({
     reason,
     composition: normalizedComposition,
     summary: normalizedSummary,
+    // Counted during this same pass, so the panel's header does not have to
+    // read the transcript a second time to fill in two fields.
+    tokens,
     window: {
       complete,
       end,

package/lib/session-token-cache.mjs

@@ -0,0 +1,76 @@
+import fs from "node:fs/promises";
+
+// A token count is a pure function of a transcript's bytes, so an unchanged
+// file never needs reading twice — which matters most for a fork, whose parent
+// is a whole extra file scanned only to find where the replay ends.
+//
+// Identity is dev+inode alongside size and mtime, mirroring
+// `transcriptActivityCache` (`lib/providers/claude-code/store.mjs:39`): a path
+// that has been replaced is a different file, not a stale entry. An active
+// session's mtime moves on every write, so it re-reads rather than serving a
+// count that has stopped growing.
+// Two limits, because entries are not the same size. A session summary is about
+// a kilobyte whatever the transcript weighed; a fork parent's signature
+// recording is 16 bytes a turn, so 512 of those is a number with no ceiling.
+// Counting entries bounds the bookkeeping, counting bytes bounds the memory.
+const MAX_ENTRIES = 512;
+const MAX_BYTES = 32 * 1024 * 1024;
+const cache = new Map();
+let cachedBytes = 0;
+
+export async function readFileStamp(filePath) {
+  if (!filePath) return null;
+  try {
+    const stats = await fs.stat(filePath);
+    return `${stats.dev ?? ""}:${stats.ino ?? ""}:${stats.size}:${stats.mtimeMs}`;
+  } catch {
+    return null;
+  }
+}
+
+export function readCachedTokens(kind, filePath, stamp) {
+  if (!stamp) return undefined;
+  const entry = cache.get(`${kind} ${filePath}`);
+  return entry?.stamp === stamp ? entry.value : undefined;
+}
+
+function evict(key) {
+  const entry = cache.get(key);
+  if (!entry) return;
+  cachedBytes -= entry.bytes;
+  cache.delete(key);
+}
+
+export function writeCachedTokens(kind, filePath, stamp, value, bytes = 1024) {
+  if (!stamp) return value;
+  // An entry that cannot fit inside the budget would evict everything else and
+  // then sit there alone. Reading it again is cheaper than that.
+  if (bytes > MAX_BYTES) return value;
+
+  const key = `${kind} ${filePath}`;
+  evict(key);
+  cache.set(key, { bytes, stamp, value });
+  cachedBytes += bytes;
+
+  while (cache.size > MAX_ENTRIES || cachedBytes > MAX_BYTES) {
+    const oldest = cache.keys().next().value;
+    if (oldest === key) break;
+    evict(oldest);
+  }
+
+  return value;
+}
+
+// Two numbers a turn, in arrays V8 stores unboxed.
+export function signatureBytes(signatures) {
+  return signatures ? signatures.runningTotals.length * 16 : 0;
+}
+
+export function sessionTokenCacheStats() {
+  return { bytes: cachedBytes, entries: cache.size, maxBytes: MAX_BYTES, maxEntries: MAX_ENTRIES };
+}
+
+export function clearSessionTokenCache() {
+  cache.clear();
+  cachedBytes = 0;
+}

package/lib/session-tokens.mjs

@@ -0,0 +1,73 @@
+// The shape both providers report in, and the derived figures the UI renders.
+//
+// Codex counts cached tokens inside its input figure and Anthropic counts them
+// beside it, so the providers cannot share a formula. They share this shape
+// instead: each collector resolves its own cache math and hands back the same
+// four buckets, which always sum to the total.
+export const TOKEN_SEGMENT_KEYS = Object.freeze(["freshInput", "cachedInput", "cacheWrites", "output"]);
+
+export function createTokenTotals() {
+  return { cachedInput: 0, cacheWrites: 0, freshInput: 0, output: 0, reasoning: 0, total: 0 };
+}
+
+export function addTokenTotals(target, usage) {
+  target.cachedInput += usage.cachedInput;
+  target.cacheWrites += usage.cacheWrites;
+  target.freshInput += usage.freshInput;
+  target.output += usage.output;
+  target.reasoning += usage.reasoning;
+  target.total += usage.total;
+  return target;
+}
+
+function share(part, whole) {
+  return whole > 0 ? part / whole : 0;
+}
+
+function inputTokens(totals) {
+  return totals.freshInput + totals.cachedInput + totals.cacheWrites;
+}
+
+// A fork's rollout replays its parent's turns before its own. The bar describes
+// what this session actually spent, so the inherited half is reported alongside
+// it rather than folded into it.
+export function summarizeSessionTokens(collected, { fork = null, forkParentMissing = false } = {}) {
+  if (!collected || collected.available !== true) {
+    return { available: false, reason: collected?.complete === false ? "incomplete" : "absent" };
+  }
+
+  const totals = fork ? fork.own : collected.totals;
+  const byModel = fork ? fork.ownByModel : collected.byModel;
+  const warnings = [];
+  if (collected.cacheWriteUnderflow) warnings.push("cache-write-underflow");
+  if (collected.complete === false) warnings.push("incomplete-scan");
+  // A fork whose parent is gone cannot be split, so the total still carries the
+  // inherited turns. Say so rather than presenting it as this session's spend.
+  if (forkParentMissing) warnings.push("fork-parent-missing");
+
+  return {
+    available: true,
+    byModel: (byModel ?? []).map(({ model, totals: modelTotals }) => ({
+      model,
+      share: share(modelTotals.total, totals.total),
+      tokens: modelTotals.total,
+    })),
+    // "N% of input was served from cache" — output is not part of the question.
+    cacheHitRate: inputTokens(totals) > 0 ? share(totals.cachedInput, inputTokens(totals)) : null,
+    compactions: collected.compactions ?? 0,
+    inherited: fork ? { tokens: fork.inherited.total, turns: fork.inheritedTurns } : null,
+    // Reasoning is part of output, so it is reported against output rather than
+    // as a segment of its own.
+    reasoning: totals.reasoning > 0
+      ? { share: share(totals.reasoning, totals.output), tokens: totals.reasoning }
+      : null,
+    segments: TOKEN_SEGMENT_KEYS.map((key) => ({
+      key,
+      share: share(totals[key], totals.total),
+      tokens: totals[key],
+    })),
+    total: totals.total,
+    totals,
+    warnings,
+  };
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "session-steward",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Codex and Claude Code session manager - browse, back up, and delete old sessions. Local browser UI + CLI.",
   "license": "MIT",
   "author": "Mallik Cheripally",
   "type": "module",
   "bin": {
     "session-steward": "bin/session-steward.mjs",
-    "session-steward-cli": "bin/session-steward-cli.mjs"
+    "session-steward-cli": "bin/session-steward-cli.mjs",
+    "session-steward-mcp": "bin/session-steward-mcp.mjs"
   },
   "repository": {
     "type": "git",
@@ -59,6 +60,7 @@
     "benchmark:overview": "node --expose-gc test/benchmarks/codex-overview.mjs",
     "benchmark:scale": "node --expose-gc test/benchmarks/codex-list.mjs",
     "benchmark:size": "node --expose-gc test/benchmarks/codex-size.mjs",
+    "benchmark:tokens": "node --expose-gc test/benchmarks/session-tokens.mjs",
     "benchmark:transcripts": "node --expose-gc test/benchmarks/codex-transcripts.mjs",
     "benchmark:versioned-stores": "node --expose-gc test/benchmarks/codex-versioned-stores.mjs",
     "prepack": "npm run build",
@@ -69,6 +71,7 @@
     "test": "node --test test/*.test.mjs test/providers/*.test.mjs"
   },
   "devDependencies": {
+    "@modelcontextprotocol/client": "^2.0.0",
     "@tailwindcss/vite": "^4.3.3",
     "@vitejs/plugin-react": "^6.0.5",
     "lucide-react": "^1.28.0",
@@ -76,5 +79,9 @@
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.3.3",
     "vite": "^8.2.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "zod": "^4.4.3"
   }
 }