agent-file-stash 0.6.0 → 0.6.1

package/README.md

@@ -356,6 +356,20 @@ filestash status:
   Gross saved (all sessions): ~53,851 tokens
 ```
 
+Session counters are discarded when a closed session is pruned, so the status also keeps lifetime counters in the database: sessions, reads, what plain reads would have returned, what the stash returned, and the estimated tool-definition overhead of every session. `agent-file-stash status`, `status --all` (summed over every database found) and `stash_status` print them as a block:
+
+```
+  Lifetime (since 2026-10-09):
+    Sessions: 14, reads: 312
+    Would have sent (plain reads): ~410,200 tokens
+    Actually sent: ~188,900 tokens
+    Gross saved: ~221,300 tokens
+    Tool definitions overhead: ~3,878 tokens (est., 14 sessions)
+    Net saved: ~217,422 tokens (est.), ~15,530 per session
+```
+
+Net is gross saved minus the overhead of every counted session, so it shows whether the stash pays for its tool definitions on average; it can be negative. A session is counted once, when the MCP server starts; `status`, `reset` and `doctor` never count one. Counting starts when you upgrade to the release that introduced it, so on an older database `Gross saved (all sessions)` includes history the lifetime block does not, and the block is replaced by a note until the first session is counted. The overhead is an estimate (`ceil(characters / 4)` of the tool definitions), not a measurement. `stash_clear` resets the lifetime counters together with the other totals.
+
 ## Benchmark
 
 Tested on a real 268-file TypeScript codebase ([opencode](https://github.com/sst/opencode)) — same agent, same prompt, only the stash toggled:

package/dist/cli.mjs

@@ -304,6 +304,14 @@ var BINARY_SNIFF_CHARS = 8192;
 var SCOPE_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
 var SCOPE_DELIMITER = "::";
 var MAX_SCOPES_PER_SESSION = 32;
+var LIFETIME_KEYS = [
+  "reads_total",
+  "baseline_tokens_total",
+  "sent_tokens_total",
+  "sessions_total",
+  "overhead_tokens_total",
+  "counters_since"
+];
 function positiveOr(value, fallback) {
   return Number.isInteger(value) && value > 0 ? value : fallback;
 }
@@ -427,6 +435,7 @@ var StashStore = class {
   recoveryAttempted = false;
   recoveredFrom;
   reason;
+  sessionCounted = false;
   constructor(config) {
     this.dbPath = config.dbPath;
     this.sessionId = config.sessionId.replace(/:{2,}/g, "_");
@@ -859,6 +868,8 @@ var StashStore = class {
       const versionRow = queryOne(db, "SELECT COUNT(DISTINCT path) as c FROM file_versions");
       const tokenRow = queryOne(db, "SELECT value FROM stats WHERE key = 'tokens_saved'");
       const sessionStat = (key) => queryOne(db, "SELECT value FROM session_stats WHERE session_id = ? AND key = ?", [this.sessionId, key])?.value ?? 0;
+      const lifetime = (key) => queryOne(db, "SELECT value FROM stats WHERE key = ?", [key])?.value ?? 0;
+      const since = queryOne(db, "SELECT value FROM stats WHERE key = 'counters_since'")?.value;
       return {
         filesTracked: versionRow?.c ?? 0,
         tokensSaved: tokenRow?.value ?? 0,
@@ -866,6 +877,12 @@ var StashStore = class {
         sessionReads: sessionStat("reads"),
         sessionBaselineTokens: sessionStat("baseline_tokens"),
         sessionSentTokens: sessionStat("sent_tokens"),
+        lifetimeSessions: lifetime("sessions_total"),
+        lifetimeReads: lifetime("reads_total"),
+        lifetimeBaselineTokens: lifetime("baseline_tokens_total"),
+        lifetimeSentTokens: lifetime("sent_tokens_total"),
+        lifetimeOverheadTokens: lifetime("overhead_tokens_total"),
+        ...since !== void 0 && since > 0 && { countersSince: since },
         degraded: false,
         ...this.recoveredFrom && { recoveredFrom: this.recoveredFrom }
       };
@@ -878,6 +895,11 @@ var StashStore = class {
       sessionReads: 0,
       sessionBaselineTokens: 0,
       sessionSentTokens: 0,
+      lifetimeSessions: 0,
+      lifetimeReads: 0,
+      lifetimeBaselineTokens: 0,
+      lifetimeSentTokens: 0,
+      lifetimeOverheadTokens: 0,
       degraded: true,
       ...this.reason && { degradedReason: this.reason }
     };
@@ -890,6 +912,7 @@ var StashStore = class {
       db.prepare("DELETE FROM session_ranges").run();
       db.prepare("DELETE FROM session_stats").run();
       db.prepare("UPDATE stats SET value = 0").run();
+      db.prepare(`DELETE FROM stats WHERE key IN (${LIFETIME_KEYS.map(() => "?").join(", ")})`).run(...LIFETIME_KEYS);
     });
   }
   async resetReads() {
@@ -917,6 +940,19 @@ var StashStore = class {
     this.bumpSessionStat(db, "baseline_tokens", baseline);
     this.bumpSessionStat(db, "sent_tokens", sent);
     if (baseline > sent) this.addTokensSaved(db, baseline - sent);
+    this.bumpLifetime(db, { reads_total: 1, baseline_tokens_total: baseline, sent_tokens_total: sent });
+  }
+  bumpLifetime(db, counters) {
+    db.prepare("INSERT OR IGNORE INTO stats (key, value) VALUES ('counters_since', ?)").run(Date.now());
+    const bump = db.prepare("INSERT INTO stats (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = value + ?");
+    for (const [key, n] of Object.entries(counters)) bump.run(key, n, n);
+  }
+  async recordSessionStart(overheadTokens) {
+    await this.init();
+    if (this.sessionCounted) return;
+    this.sessionCounted = true;
+    const overhead = Number.isFinite(overheadTokens) && overheadTokens > 0 ? Math.round(overheadTokens) : 0;
+    this.guarded((db) => this.bumpLifetime(db, { sessions_total: 1, overhead_tokens_total: overhead }));
   }
   bumpSessionStat(db, key, n) {
     db.prepare(
@@ -1001,6 +1037,23 @@ var FileWatcher = class {
   }
 };
 
+// packages/sdk/src/lifetime.ts
+function lifetimeView(c) {
+  const grossSaved = c.lifetimeBaselineTokens - c.lifetimeSentTokens;
+  const netSaved = grossSaved - c.lifetimeOverheadTokens;
+  return {
+    empty: c.lifetimeSessions === 0 && c.lifetimeReads === 0,
+    sessions: c.lifetimeSessions,
+    reads: c.lifetimeReads,
+    baselineTokens: c.lifetimeBaselineTokens,
+    sentTokens: c.lifetimeSentTokens,
+    overheadTokens: c.lifetimeOverheadTokens,
+    grossSaved,
+    netSaved,
+    netPerSession: c.lifetimeSessions > 0 ? Math.round(netSaved / c.lifetimeSessions) || 0 : null
+  };
+}
+
 // packages/sdk/src/index.ts
 function createStash(config) {
   const stash = new StashStore(config);
@@ -1132,6 +1185,22 @@ function toolDefinitionTokens() {
 function degradedLine(reason2 = "unknown") {
   return `Mode: DEGRADED (${reason2}) - files are read normally, nothing is stashed`;
 }
+function formatLifetime(c, since, saved) {
+  const v = lifetimeView(c);
+  if (v.empty) return [`  Lifetime counters start with this version; ${saved} above includes older history.`];
+  const fmt = (n) => `~${n.toLocaleString()}`;
+  const date = since ? ` (since ${new Date(since).toISOString().slice(0, 10)})` : "";
+  const perSession = v.netPerSession === null ? "" : `, ${fmt(v.netPerSession)} per session`;
+  return [
+    `  Lifetime${date}:`,
+    `    Sessions: ${v.sessions}, reads: ${v.reads}`,
+    `    Would have sent (plain reads): ${fmt(v.baselineTokens)} tokens`,
+    `    Actually sent: ${fmt(v.sentTokens)} tokens`,
+    `    Gross saved: ${fmt(v.grossSaved)} tokens`,
+    `    Tool definitions overhead: ${fmt(v.overheadTokens)} tokens (est., ${v.sessions} sessions)`,
+    `    Net saved: ${fmt(v.netSaved)} tokens (est.)${perSession}`
+  ];
+}
 function formatStatus(stats, overheadTokens) {
   if (stats.degraded) return degradedLine(stats.degradedReason);
   const fmt = (n) => `~${n.toLocaleString()}`;
@@ -1146,7 +1215,8 @@ function formatStatus(stats, overheadTokens) {
     `    Gross saved: ${fmt(stats.sessionTokensSaved)} tokens`,
     `    Tool definitions overhead: ${fmt(overheadTokens)} tokens (est.)`,
     `    Net saved: ${fmt(net)} tokens (est.)`,
-    `  Gross saved (all sessions): ${fmt(stats.tokensSaved)} tokens`
+    `  Gross saved (all sessions): ${fmt(stats.tokensSaved)} tokens`,
+    ...formatLifetime(stats, stats.countersSince, `"Gross saved (all sessions)"`)
   ].join("\n");
 }
 function statsSuffix(grossSaved) {
@@ -1193,6 +1263,7 @@ async function startMcpServer() {
     ...limitOptions()
   });
   await stash.init();
+  await stash.recordSessionStart(toolDefinitionTokens());
   const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
   const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
   const server = new McpServer({
@@ -1268,7 +1339,8 @@ async function startMcpServer() {
           [`${META_NAMESPACE}/stats`]: {
             ...stats,
             toolDefinitionTokens: overhead,
-            netTokensSaved: stats.sessionTokensSaved - overhead
+            netTokensSaved: stats.sessionTokensSaved - overhead,
+            lifetime: lifetimeView(stats)
           }
         }
       };
@@ -1876,6 +1948,7 @@ async function runStatus() {
     console.log(`filestash status:`);
     console.log(`  Files tracked:          ${stats.filesTracked}`);
     console.log(`  Tokens saved (total):   ~${stats.tokensSaved.toLocaleString()}`);
+    console.log(formatLifetime(stats, stats.countersSince, `"Tokens saved (total)"`).join("\n"));
   } catch (e) {
     console.error(`filestash status failed for ${dbPath}: ${e instanceof Error ? e.message : String(e)}`);
     process.exitCode = 1;
@@ -1890,12 +1963,20 @@ async function runStatusAll(root) {
     return;
   }
   const rows = [];
+  const lifetime = { lifetimeSessions: 0, lifetimeReads: 0, lifetimeBaselineTokens: 0, lifetimeSentTokens: 0, lifetimeOverheadTokens: 0 };
+  let since;
   for (const dbPath of databases) {
     const { stash } = createStash({ dbPath, sessionId: CLI_STATUS_SESSION, recoverCorrupt: false, quiet: true });
     try {
       await stash.init();
       const stats = await stash.getStats();
       assertHealthy(stash);
+      lifetime.lifetimeSessions += stats.lifetimeSessions;
+      lifetime.lifetimeReads += stats.lifetimeReads;
+      lifetime.lifetimeBaselineTokens += stats.lifetimeBaselineTokens;
+      lifetime.lifetimeSentTokens += stats.lifetimeSentTokens;
+      lifetime.lifetimeOverheadTokens += stats.lifetimeOverheadTokens;
+      if (stats.countersSince !== void 0) since = Math.min(since ?? Infinity, stats.countersSince);
       rows.push({ project: resolve5(dbPath, "../..").replace(/\/\.vscode$/, ""), files: stats.filesTracked, tokens: stats.tokensSaved });
     } catch (e) {
       console.error(`  skipped ${dbPath}: ${e instanceof Error ? e.message : String(e)}`);
@@ -1911,6 +1992,7 @@ async function runStatusAll(root) {
     console.log(`  ~${r.tokens.toLocaleString().padStart(10)} tokens  ${String(r.files).padStart(5)} files  ${r.project}`);
   }
   console.log(`  ~${totalTokens.toLocaleString().padStart(10)} tokens  ${String(totalFiles).padStart(5)} files  TOTAL`);
+  console.log(formatLifetime(lifetime, since, "the per-project totals").join("\n"));
   console.log(`
 Savings count re-reads within a session (unchanged files and diffs); a new session always receives full content.`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-file-stash",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "mcpName": "io.github.atilio-ts/agent-file-stash",
   "description": "File stash with diff tracking for AI coding agents. Drop-in replacement for file reads that saves tokens.",
   "type": "module",