@goodandready/dsh-context-lens 0.1.16 → 0.1.18

package/lib/index.js

@@ -1,8 +1,15 @@
 import z from '@deepseek-ai/schemastery';
-import { compressLog, estimateTokens as estLog } from './compression/log-compressor.js';
-import { skeletonize } from './ast/skeletonizer.js';
 import * as tracker from './tokens/tracker.js';
-import { shouldAutoCompress } from './auto-compress.js';
+import { compressLog } from './compression/log-compressor.js';
+import { writeJson, readBody, isTrustedRequest } from './http.js';
+import { registerPluginUpdater } from './updater.js';
+import {
+  renderOutput,
+  registerTools,
+  getFocus,
+  clearFocus,
+  getLastActiveSession
+} from './tools.js';
 
 export const name = '@goodandready/dsh-context-lens';
 export const inject = ['tools', 'settings', 'webServer'];
@@ -13,235 +20,174 @@ export const Config = z.object({
   tokenSavingsTracking: z.boolean().default(true).description('Track and display token budget savings'),
   autoCompressThreshold: z.number().default(4000).description('Auto-compress threshold in chars (0 to disable)'),
   budgetLimit: z.number().default(100000).description('Session token budget; compressions stop counting after this limit'),
+  budgetAlertPercent: z.number().default(90).description('Budget percentage threshold (50-99%) for warning alert'),
   autoCollapse: z.boolean().default(true).description('Warn in UI when budget is nearly exhausted (does not force-close the settings card)')
 });
 
 const NS = '@goodandready/dsh-context-lens';
 
-// #37/#18: focus keyed by session id (not process-global singleton)
-const focusBySession = new Map();
-let lastActiveSession = '__default__';
-
-function sessionKey(params, meta) {
-  const k = (
-    (params && (params.sessionId || params.session_id)) ||
-    (meta && (meta.sessionId || meta.session_id || (meta.session && meta.session.id))) ||
-    '__default__'
-  );
-  if (k !== '__default__') lastActiveSession = k;
-  return k;
-}
-
-function getFocus(key) {
-  if (!focusBySession.has(key)) focusBySession.set(key, { paths: [], updatedAt: null });
-  return focusBySession.get(key);
-}
-
-const OUTPUT_SCHEMA = { type: 'object', properties: { success: { type: 'boolean' } }, additionalProperties: true };
-const renderOutput = (_args, result) => JSON.stringify(result, null, 2);
+export { renderOutput };
 
 export function apply(ctx, config) {
   let getConfig = () => config;
 
   ctx.inject(['settings'], (sctx) => {
-    const scope = sctx.settings.register(NS, Config, { base: config });
-    getConfig = () => scope.get() ?? config;
+    if (typeof sctx.effect === 'function') {
+      sctx.effect(() => {
+        const scope = sctx.settings.register(NS, Config, { base: config });
+        getConfig = () => scope.get() ?? config;
+        return () => {
+          if (typeof scope?.dispose === 'function') scope.dispose();
+          getConfig = () => config;
+        };
+      }, 'dsh-context-lens: settings');
+    } else {
+      const scope = sctx.settings.register(NS, Config, { base: config });
+      getConfig = () => scope.get() ?? config;
+    }
   });
 
   function maybeTrack(original, compressed) {
-    try {
-      const cfg = getConfig();
-      if (cfg && cfg.tokenSavingsTracking === false) return null;
-      if (cfg && typeof cfg.budgetLimit === 'number') tracker.setBudgetLimit(cfg.budgetLimit);
-      return tracker.record(original, compressed);
-    } catch {
-      // #39: never record on config/read errors
-      return null;
-    }
+    const cfg = getConfig();
+    if (cfg.tokenSavingsTracking === false) return;
+    tracker.record(original, compressed);
   }
 
+  // Register AI agent tools
   if (ctx.tools) {
-    ctx.tools.register({
-      name: 'context_lens_focus',
-      description: 'Set focus files/folders for a session; other context will be auto-collapsed via skeletonizer',
-      parameters: {
-        type: 'object',
-        properties: {
-          paths: { type: 'array', items: { type: 'string' }, description: 'Focused file/folder paths' },
-          maxDepth: { type: 'number', description: 'Max skeleton depth (overrides settings)' },
-          sessionId: { type: 'string', description: 'Session id (defaults to host session when available)' }
-        },
-        required: ['paths']
-      },
-      output: { schema: OUTPUT_SCHEMA, render: renderOutput },
-      execute: async (params, meta) => {
-        const key = sessionKey(params, meta);
-        const paths = Array.isArray(params.paths) ? params.paths : [];
-        const focus = { paths, updatedAt: new Date().toISOString() };
-        focusBySession.set(key, focus);
-        return { success: true, sessionId: key, focus, hint: 'Use skeletonize helper via compress or read files with focus set' };
-      }
-    });
-
-    ctx.tools.register({
-      name: 'context_lens_compress_log',
-      description: 'Compress a large log/test output block, keeping failures and stacktraces (Jest/Pytest/Go/npm)',
-      parameters: {
-        type: 'object',
-        properties: {
-          text: { type: 'string', description: 'Raw log text to compress' },
-          log: { type: 'string', description: 'Alias for text' },
-          mode: { type: 'string', enum: ['raw', 'balanced', 'aggressive'], description: 'Compression aggressiveness' },
-          maxLines: { type: 'number', description: 'Max output lines' },
-          auto: { type: 'boolean', description: 'Auto-compress if large (uses threshold); keeps configured compressionMode' }
-        }
-      },
-      output: { schema: OUTPUT_SCHEMA, render: renderOutput },
-      execute: async (params) => {
-        const cfg = getConfig();
-        const inputText = params.text || params.log || '';
-        const mode = params.mode || cfg.compressionMode || 'balanced';
-        const maxLines = params.maxLines || 400;
-        const threshold = cfg.autoCompressThreshold ?? 4000;
-        const useAuto = params.auto !== false && shouldAutoCompress(inputText, threshold);
-        // #33: never force balanced — keep configured/explicit mode
-        const effectiveMode = mode;
-        const res = compressLog(inputText, { mode: effectiveMode, maxLines });
-        maybeTrack(inputText, res.compressed);
-        return { success: true, mode: effectiveMode, autoCompressed: useAuto, ...res };
-      }
-    });
-
-    ctx.tools.register({
-      name: 'context_lens_compress_code',
-      description: 'Generate AST skeleton for a large source file (JS/TS/Python/Go/Rust/Java) to save context',
-      parameters: {
-        type: 'object',
-        properties: {
-          code: { type: 'string', description: 'Source code to skeletonize' },
-          language: { type: 'string', enum: ['js', 'ts', 'py', 'python', 'go', 'rust', 'java'], description: 'Language hint' },
-          maxDepth: { type: 'number', description: 'Max depth' },
-          filePath: { type: 'string', description: 'File path to check focus (if in focus, returns full code)' },
-          sessionId: { type: 'string', description: 'Session id for focus lookup' }
-        },
-        required: ['code']
-      },
-      output: { schema: OUTPUT_SCHEMA, render: renderOutput },
-      execute: async (params, meta) => {
-        const cfg = getConfig();
-        const maxDepth = params.maxDepth ?? cfg.astSkeletonMaxDepth ?? 3;
-        const key = sessionKey(params, meta);
-        const focusState = getFocus(key);
-        const isFocused = params.filePath && focusState.paths.length > 0
-          ? focusState.paths.some(p => params.filePath.includes(p) || p.includes(params.filePath))
-          : false;
-        if (isFocused) {
-          maybeTrack(params.code, params.code);
-          return { success: true, skeleton: params.code, originalTokens: estLog(params.code), skeletonTokens: estLog(params.code), maxDepth, focused: true, sessionId: key, hint: 'File is in focus, returned full code' };
-        }
-        const skeleton = skeletonize(params.code, { maxDepth, language: params.language });
-        maybeTrack(params.code, skeleton);
-        return { success: true, skeleton, originalTokens: estLog(params.code), skeletonTokens: estLog(skeleton), maxDepth, focused: false, sessionId: key };
-      }
-    });
-
-    ctx.tools.register({
-      name: 'context_lens_reset',
-      description: 'Reset context-lens savings stats and history (e.g. at the start of a new task)',
-      parameters: {
-        type: 'object',
-        properties: {
-          sessionId: { type: 'string', description: 'Optional session id to also reset session focus' }
-        }
-      },
-      output: { schema: OUTPUT_SCHEMA, render: renderOutput },
-      execute: async (params, meta) => {
-        tracker.reset();
-        const key = sessionKey(params || {}, meta);
-        if (params && params.sessionId) {
-          focusBySession.delete(key);
-        }
-        return { success: true, message: 'Context lens stats and history reset', sessionId: key };
-      }
-    });
-
-    ctx.tools.register({
-      name: 'context_lens_stats',
-      description: 'Show session token savings stats for context-lens',
-      parameters: {
-        type: 'object',
-        properties: {
-          sessionId: { type: 'string', description: 'Session id for focus snapshot' }
-        }
-      },
-      output: { schema: OUTPUT_SCHEMA, render: renderOutput },
-      execute: async (params, meta) => {
-        const cfg = getConfig();
-        if (typeof cfg.budgetLimit === 'number') tracker.setBudgetLimit(cfg.budgetLimit);
-        const stats = tracker.getStats(cfg.budgetLimit);
-        const history = tracker.getHistory();
-        const key = sessionKey(params || {}, meta);
-        return {
-          success: true,
-          ...stats,
-          history,
-          trackingEnabled: cfg.tokenSavingsTracking !== false,
-          autoCollapse: cfg.autoCollapse !== false,
-          focus: getFocus(key),
-          sessionId: key,
-          autoCompressThreshold: cfg.autoCompressThreshold
-        };
-      }
-    });
+    registerTools(ctx, { getConfig, maybeTrack });
   }
 
   if (ctx.webServer) {
+    // #61: One-click plugin updater endpoint (/api/dsh-context-lens/update)
+    const mountUpdater = () => registerPluginUpdater(ctx, {
+      packageName: '@goodandready/dsh-context-lens',
+      manifestUrl: new URL('../package.json', import.meta.url),
+      endpoint: '/api/dsh-context-lens/update'
+    });
+    if (typeof ctx.effect === 'function') {
+      ctx.effect(mountUpdater, 'dsh-context-lens: updater');
+    } else {
+      mountUpdater();
+    }
+
+    // Status route (#70: explicit URL parsing and validation)
     ctx.effect(() => ctx.webServer.register({
       kind: 'exact',
       path: '/dsh-context-lens/status',
       handler: (req, res) => {
         const cfg = getConfig();
         if (typeof cfg.budgetLimit === 'number') tracker.setBudgetLimit(cfg.budgetLimit);
-        let sId = '__default__';
+        if (typeof cfg.budgetAlertPercent === 'number') tracker.setBudgetAlertPercent(cfg.budgetAlertPercent);
+        let sId = getLastActiveSession() || '__default__';
         try {
           const u = new URL(req.url, 'http://127.0.0.1');
-          sId = u.searchParams.get('sessionId') || u.searchParams.get('session_id') || lastActiveSession || '__default__';
-        } catch {}
-        res.setHeader('content-type', 'application/json');
-        res.end(JSON.stringify({
+          const qId = u.searchParams.get('sessionId') || u.searchParams.get('session_id');
+          if (qId !== null) {
+            if (!qId || typeof qId !== 'string' || qId.trim() === '') {
+              writeJson(res, 400, { ok: false, error: 'Invalid sessionId parameter' });
+              return;
+            }
+            sId = qId.trim();
+          }
+        } catch (err) {
+          ctx.logger?.warn?.('dsh-context-lens: failed to parse request url in status', err);
+          writeJson(res, 400, { ok: false, error: 'Malformed request URL' });
+          return;
+        }
+
+        writeJson(res, 200, {
           ok: true,
           plugin: 'dsh-context-lens',
-          stats: tracker.getStats(cfg.budgetLimit),
+          stats: tracker.getStats(cfg.budgetLimit, cfg.budgetAlertPercent),
           history: tracker.getHistory(),
           focus: getFocus(sId),
           sessionId: sId
-        }));
+        });
       }
     }), 'dsh-context-lens status route');
 
-    // #45: server-backed preview (same compressor as tools)
+    // Quick clear-focus API route (#62: POST only, trusted origin check; #70: clean URL error handling)
+    ctx.effect(() => ctx.webServer.register({
+      kind: 'exact',
+      path: '/dsh-context-lens/clear-focus',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') {
+          res.writeHead(405, { Allow: 'POST', 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'Method Not Allowed: POST required' }));
+          return;
+        }
+        if (!isTrustedRequest(req)) {
+          writeJson(res, 403, { ok: false, error: 'Forbidden: untrusted request origin' });
+          return;
+        }
+
+        let sId = getLastActiveSession() || '__default__';
+        try {
+          const u = new URL(req.url, 'http://127.0.0.1');
+          const qId = u.searchParams.get('sessionId') || u.searchParams.get('session_id');
+          if (qId !== null) {
+            if (!qId || typeof qId !== 'string' || qId.trim() === '') {
+              writeJson(res, 400, { ok: false, error: 'Invalid sessionId parameter' });
+              return;
+            }
+            sId = qId.trim();
+          }
+        } catch (err) {
+          ctx.logger?.warn?.('dsh-context-lens: failed to parse request url in clear-focus', err);
+          writeJson(res, 400, { ok: false, error: 'Malformed request URL' });
+          return;
+        }
+
+        clearFocus(sId);
+        writeJson(res, 200, { ok: true, sessionId: sId, focus: getFocus(sId) });
+      }
+    }), 'dsh-context-lens clear-focus route');
+
+    // Server-backed preview (#63: POST only, trusted origin, bounded body size, clamped maxLines)
     ctx.effect(() => ctx.webServer.register({
       kind: 'exact',
       path: '/dsh-context-lens/compress-preview',
       handler: async (req, res) => {
+        if (req.method !== 'POST') {
+          res.writeHead(405, { Allow: 'POST', 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'Method Not Allowed: POST required' }));
+          return;
+        }
+        if (!isTrustedRequest(req)) {
+          writeJson(res, 403, { ok: false, error: 'Forbidden: untrusted request origin' });
+          return;
+        }
+
+        let body;
         try {
-          const chunks = [];
-          for await (const c of req) chunks.push(c);
-          const body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
-          const cfg = getConfig();
-          const mode = body.mode || cfg.compressionMode || 'balanced';
-          const text = body.text || '';
-          const out = compressLog(text, { mode, maxLines: body.maxLines || 400 });
-          res.setHeader('content-type', 'application/json');
-          res.end(JSON.stringify({ ok: true, mode, ...out }));
+          const raw = await readBody(req, 256 * 1024);
+          body = JSON.parse(raw.toString('utf8') || '{}');
         } catch (e) {
-          res.statusCode = 400;
-          res.setHeader('content-type', 'application/json');
-          res.end(JSON.stringify({ ok: false, error: e && e.message || String(e) }));
+          if (e?.message === 'body too large') {
+            writeJson(res, 413, { ok: false, error: 'Payload Too Large: maximum 256KB allowed' });
+            return;
+          }
+          writeJson(res, 400, { ok: false, error: 'Malformed JSON body' });
+          return;
+        }
+
+        let maxLines = 400;
+        if (body.maxLines !== undefined) {
+          const parsed = Number(body.maxLines);
+          if (Number.isNaN(parsed) || parsed < 1 || parsed > 5000) {
+            writeJson(res, 400, { ok: false, error: 'maxLines must be a number between 1 and 5000' });
+            return;
+          }
+          maxLines = Math.floor(parsed);
         }
+
+        const cfg = getConfig();
+        const mode = body.mode || cfg.compressionMode || 'balanced';
+        const text = typeof body.text === 'string' ? body.text : '';
+        const out = compressLog(text, { mode, maxLines });
+        writeJson(res, 200, { ok: true, mode, ...out });
       }
     }), 'dsh-context-lens compress-preview route');
   }
-}
-
-export { compressLog, skeletonize, shouldAutoCompress };
+}

package/lib/tokens/tracker.js

@@ -7,6 +7,7 @@ let calls = 0;
 const history = []; // last 10
 const MAX_HISTORY = 10;
 let defaultBudgetLimit = 100000; // tokens
+let defaultBudgetAlertPercent = 90; // threshold percent for low budget warning
 
 export { estimateTokens };
 
@@ -16,6 +17,12 @@ export function setBudgetLimit(limit) {
   }
 }
 
+export function setBudgetAlertPercent(percent) {
+  if (typeof percent === 'number' && percent >= 50 && percent <= 99) {
+    defaultBudgetAlertPercent = percent;
+  }
+}
+
 export function record(originalText, compressedText) {
   const o = estimateTokens(originalText);
   const c = estimateTokens(compressedText);
@@ -41,16 +48,19 @@ export function record(originalText, compressedText) {
   return { originalTokens: o, compressedTokens: c, savedTokens: saved };
 }
 
-export function getStats(budgetLimitOverride) {
+export function getStats(budgetLimitOverride, budgetAlertPercentOverride) {
   const limit = (typeof budgetLimitOverride === 'number' && budgetLimitOverride > 0)
     ? budgetLimitOverride
     : defaultBudgetLimit;
+  const alertPercent = (typeof budgetAlertPercentOverride === 'number' && budgetAlertPercentOverride >= 50 && budgetAlertPercentOverride <= 99)
+    ? budgetAlertPercentOverride
+    : defaultBudgetAlertPercent;
   const saved = Math.max(0, totalOriginal - totalCompressed);
   const pct = totalOriginal ? Math.round((1 - totalCompressed / totalOriginal) * 100) : 0;
   const budgetUsed = totalCompressed;
   const budgetRemaining = Math.max(0, limit - budgetUsed);
   const budgetPercent = Math.min(100, Math.round((budgetUsed / limit) * 100));
-  const lowBudget = budgetPercent > 90;
+  const lowBudget = budgetPercent >= alertPercent;
   return {
     totalOriginal,
     totalCompressed,
@@ -62,6 +72,7 @@ export function getStats(budgetLimitOverride) {
     budgetPercent,
     lowBudget,
     budgetLimit: limit,
+    budgetAlertPercent: alertPercent,
     countingStopped: budgetUsed >= limit
   };
 }
@@ -79,7 +90,4 @@ export function reset() {
   totalCompressed = 0;
   calls = 0;
   history.length = 0;
-  defaultBudgetLimit = 100000;
-}
-
-export default { estimateTokens, setBudgetLimit, record, getStats, getHistory, clearHistory, reset };
+}

package/lib/tools.js

@@ -0,0 +1,179 @@
+import { compressLog, estimateTokens as estLog } from './compression/log-compressor.js';
+import { skeletonize } from './ast/skeletonizer.js';
+import * as tracker from './tokens/tracker.js';
+import { shouldAutoCompress } from './auto-compress.js';
+
+export const OUTPUT_SCHEMA = { type: 'object', properties: { success: { type: 'boolean' } }, additionalProperties: true };
+
+// #71 (GH #2): output.render MUST return ContentBlock[] [{ type: 'text', text: ... }]
+export const renderOutput = (_args, result) => [
+  { type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result, null, 2) }
+];
+
+const focusBySession = new Map();
+let lastActiveSession = '__default__';
+
+export function sessionKey(params, meta) {
+  const k = (
+    (params && (params.sessionId || params.session_id)) ||
+    (meta && (meta.sessionId || meta.session_id || (meta.session && meta.session.id))) ||
+    '__default__'
+  );
+  if (k !== '__default__') lastActiveSession = k;
+  return k;
+}
+
+export function getFocus(key) {
+  if (!focusBySession.has(key)) focusBySession.set(key, { paths: [], updatedAt: null });
+  return focusBySession.get(key);
+}
+
+export function clearFocus(key) {
+  if (key) {
+    focusBySession.set(key, { paths: [], updatedAt: new Date().toISOString() });
+  } else {
+    focusBySession.clear();
+  }
+}
+
+export function getLastActiveSession() {
+  return lastActiveSession;
+}
+
+export function registerTools(ctx, { getConfig, maybeTrack }) {
+  if (!ctx?.tools?.register) return;
+
+  ctx.tools.register({
+    name: 'context_lens_focus',
+    description: 'Set active file paths for current session focus (these files skip AST compression)',
+    parameters: {
+      type: 'object',
+      properties: {
+        paths: { type: 'array', items: { type: 'string' }, description: 'File paths or patterns currently in focus' },
+        sessionId: { type: 'string', description: 'Session id (uses active session if omitted)' }
+      },
+      required: ['paths']
+    },
+    output: { schema: OUTPUT_SCHEMA, render: renderOutput },
+    execute: async (params, meta) => {
+      const key = sessionKey(params, meta);
+      const paths = Array.isArray(params.paths) ? params.paths : [];
+      const state = getFocus(key);
+      state.paths = paths;
+      state.updatedAt = new Date().toISOString();
+      return { success: true, sessionId: key, focus: state };
+    }
+  });
+
+  ctx.tools.register({
+    name: 'context_lens_compress_log',
+    description: 'Compress a large log/test output block, keeping failures and stacktraces (Jest/Pytest/Go/npm)',
+    parameters: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'Raw log text to compress' },
+        log: { type: 'string', description: 'Alias for text' },
+        mode: { type: 'string', enum: ['raw', 'balanced', 'aggressive'], description: 'Compression aggressiveness' },
+        maxLines: { type: 'number', description: 'Max output lines' },
+        auto: { type: 'boolean', description: 'Auto-compress if large (uses threshold); keeps configured compressionMode' }
+      }
+    },
+    output: { schema: OUTPUT_SCHEMA, render: renderOutput },
+    execute: async (params) => {
+      const cfg = getConfig();
+      const inputText = params.text || params.log || '';
+      const mode = params.mode || cfg.compressionMode || 'balanced';
+      const maxLines = params.maxLines || 400;
+      const threshold = cfg.autoCompressThreshold ?? 4000;
+      const useAuto = params.auto !== false && shouldAutoCompress(inputText, threshold);
+      const effectiveMode = mode;
+      const res = compressLog(inputText, { mode: effectiveMode, maxLines });
+      maybeTrack(inputText, res.compressed);
+      return { success: true, mode: effectiveMode, autoCompressed: useAuto, ...res };
+    }
+  });
+
+  ctx.tools.register({
+    name: 'context_lens_compress_code',
+    description: 'Generate AST skeleton for a large source file (JS/TS/Python/Go/Rust/Java/C/C++/SQL) to save context',
+    parameters: {
+      type: 'object',
+      properties: {
+        code: { type: 'string', description: 'Source code to skeletonize' },
+        language: { type: 'string', enum: ['js', 'ts', 'py', 'python', 'go', 'rust', 'java', 'c', 'cpp', 'sql'], description: 'Language hint' },
+        maxDepth: { type: 'number', description: 'Max depth' },
+        filePath: { type: 'string', description: 'File path to check focus (if in focus, returns full code)' },
+        sessionId: { type: 'string', description: 'Session id for focus lookup' }
+      },
+      required: ['code']
+    },
+    output: { schema: OUTPUT_SCHEMA, render: renderOutput },
+    execute: async (params, meta) => {
+      const cfg = getConfig();
+      const maxDepth = params.maxDepth ?? cfg.astSkeletonMaxDepth ?? 3;
+      const key = sessionKey(params, meta);
+      const focusState = getFocus(key);
+      const isFocused = params.filePath && focusState.paths.length > 0
+        ? focusState.paths.some(p => params.filePath.includes(p) || p.includes(params.filePath))
+        : false;
+      if (isFocused) {
+        maybeTrack(params.code, params.code);
+        return { success: true, skeleton: params.code, originalTokens: estLog(params.code), skeletonTokens: estLog(params.code), maxDepth, focused: true, sessionId: key, hint: 'File is in focus, returned full code' };
+      }
+      const skeleton = skeletonize(params.code, { maxDepth, language: params.language });
+      maybeTrack(params.code, skeleton);
+      return { success: true, skeleton, originalTokens: estLog(params.code), skeletonTokens: estLog(skeleton), maxDepth, focused: false, sessionId: key };
+    }
+  });
+
+  ctx.tools.register({
+    name: 'context_lens_reset',
+    description: 'Reset context-lens savings stats and history (e.g. at the start of a new task)',
+    parameters: {
+      type: 'object',
+      properties: {
+        sessionId: { type: 'string', description: 'Optional session id to also reset session focus' }
+      }
+    },
+    output: { schema: OUTPUT_SCHEMA, render: renderOutput },
+    execute: async (params, meta) => {
+      tracker.reset();
+      const key = sessionKey(params || {}, meta);
+      if (params && params.sessionId) {
+        focusBySession.delete(key);
+      }
+      return { success: true, message: 'Context lens stats and history reset', sessionId: key };
+    }
+  });
+
+  ctx.tools.register({
+    name: 'context_lens_stats',
+    description: 'Show session token savings stats for context-lens',
+    parameters: {
+      type: 'object',
+      properties: {
+        sessionId: { type: 'string', description: 'Session id for focus snapshot' }
+      }
+    },
+    output: { schema: OUTPUT_SCHEMA, render: renderOutput },
+    execute: async (params, meta) => {
+      const cfg = getConfig();
+      if (typeof cfg.budgetLimit === 'number') tracker.setBudgetLimit(cfg.budgetLimit);
+      if (typeof cfg.budgetAlertPercent === 'number') tracker.setBudgetAlertPercent(cfg.budgetAlertPercent);
+      const stats = tracker.getStats(cfg.budgetLimit, cfg.budgetAlertPercent);
+      const history = tracker.getHistory();
+      const key = sessionKey(params || {}, meta);
+      return {
+        success: true,
+        ...stats,
+        history,
+        trackingEnabled: cfg.tokenSavingsTracking !== false,
+        autoCollapse: cfg.autoCollapse !== false,
+        focus: getFocus(key),
+        sessionId: key,
+        autoCompressThreshold: cfg.autoCompressThreshold,
+        budgetAlertPercent: cfg.budgetAlertPercent ?? 90
+      };
+    }
+  });
+}