@goodandready/dsh-context-lens 0.1.0

package/LICENSE

@@ -0,0 +1,13 @@
+MIT License
+
+Copyright (c) 2026 GooDAnDReaDY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.

package/README.md

@@ -0,0 +1,35 @@
+# dsh-context-lens
+
+DSH plugin for AST context compression, test log filtering, and token budget guard for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
+
+Compresses noisy test output (Jest/Pytest/Go/Vitest/npm) to failures + stacktraces and generates compact AST skeletons for large source files to save context tokens.
+
+## Tools
+- `context_lens_focus` — set focused files/folders (other context collapsed)
+- `context_lens_compress_log` — compress a log block (`text`, `mode` raw/balanced/aggressive, `maxLines`)
+- `context_lens_compress_code` — skeletonize source code (`code`, `language` js/ts/py/go, `maxDepth`)
+- `context_lens_stats` — session token savings stats
+
+Status route: `GET /dsh-context-lens/status`
+
+## Settings
+Located in **Settings → Plugins → Context Lens & Token Guard**:
+- `compressionMode`: `raw` | `balanced` | `aggressive` (default `balanced`)
+- `astSkeletonMaxDepth`: max skeleton depth (default `3`)
+- `tokenSavingsTracking`: track savings (default `true`)
+
+Example config:
+```yaml
+# `compressionMode` — aggressiveness, `astSkeletonMaxDepth` — skeleton depth
+compressionMode: balanced
+astSkeletonMaxDepth: 3
+tokenSavingsTracking: true
+```
+
+## Verification
+```bash
+npm test
+```
+
+## License
+MIT

package/cordis.patch.yml

@@ -0,0 +1,2 @@
+- id: dsh-context-lens
+  name: '@goodandready/dsh-context-lens'

package/lib/ast/skeletonizer.js

@@ -0,0 +1,61 @@
+// ponytail: regex skeletons, no tree-sitter — handles JS/TS/Python/Go signatures
+const JS_FUNC_RE = /^\s*(export\s+)?(async\s+)?(function\s+(\w+)|const\s+(\w+)\s*=\s*(async\s+)?\([^)]*\)\s*=>|(\w+)\s*:\s*\([^)]*\)\s*=>|class\s+(\w+)|interface\s+(\w+)|type\s+(\w+)\s*=)/;
+const PY_RE = /^\s*(def\s+(\w+)\s*\([^)]*\)|class\s+(\w+).*?:|async def\s+(\w+)\s*\([^)]*\))/;
+const GO_RE = /^\s*(func\s+(\([^)]+\)\s+)?(\w+)\s*\([^)]*\)|type\s+(\w+)\s+(struct|interface))/;
+
+function indentDepth(line) {
+  const m = line.match(/^(\s*)/);
+  return m ? Math.floor(m[1].replace(/\t/g, '  ').length / 2) : 0;
+}
+
+export function skeletonize(text, { maxDepth = 3, language } = {}) {
+  if (!text || typeof text !== 'string') return '';
+  const lines = text.split(/\r?\n/);
+  const out = [];
+  let seen = new Set();
+  for (const raw of lines) {
+    const line = raw.trimEnd();
+    if (!line.trim()) continue;
+    const d = indentDepth(raw);
+    if (d > maxDepth) continue;
+    let sig = null;
+    // try JS/TS
+    if (!language || language === 'js' || language === 'ts') {
+      const m = line.match(/^\s*(export\s+)?(async\s+)?(function\s+\w+[^\n]*|const\s+\w+\s*=.*=>.*|class\s+\w+.*|interface\s+\w+.*|type\s+\w+\s*=.*|(?:public|private|protected)?\s*(async\s+)?\w+\s*\([^)]*\)\s*[:{])/);
+      if (m) sig = line.trim().replace(/\s*\{.*$/, '').replace(/\s+$/, '') + (line.trim().endsWith('{') ? '' : '');
+      // fallback simple
+      if (!sig && /^\s*(export\s+)?(async\s+)?function\s+\w+/.test(line)) sig = line.trim();
+      if (!sig && /^\s*class\s+\w+/.test(line)) sig = line.trim();
+    }
+    if (!sig && (!language || language === 'py' || language === 'python')) {
+      const m = line.match(PY_RE);
+      if (m) sig = line.trim();
+    }
+    if (!sig && (!language || language === 'go')) {
+      const m = line.match(GO_RE);
+      if (m) sig = line.trim();
+    }
+    // generic fallback: if no specific language, try all
+    if (!sig && !language) {
+      if (JS_FUNC_RE.test(line) || PY_RE.test(line) || GO_RE.test(line)) sig = line.trim();
+    }
+    if (sig) {
+      // normalize: trim trailing { : etc, keep signature short
+      sig = sig.replace(/\s*\{\s*$/, '').replace(/:\s*$/, '').trim();
+      if (sig.length > 120) sig = sig.slice(0, 117) + '...';
+      const key = sig;
+      if (!seen.has(key)) {
+        seen.add(key);
+        out.push('  '.repeat(Math.min(d, maxDepth)) + sig);
+      }
+    }
+  }
+  // if nothing found, fallback to first N non-empty lines truncated
+  if (out.length === 0) {
+    const fallback = lines.filter((l) => l.trim()).slice(0, Math.min(20, maxDepth * 6)).map((l) => l.trim().slice(0, 120));
+    return fallback.join('\n');
+  }
+  return out.join('\n');
+}
+
+export default { skeletonize };

package/lib/client.js

@@ -0,0 +1,223 @@
+window.__ModuleLoader__.load({
+  id: '@goodandready/dsh-context-lens',
+  factory: (require) => {
+    var module = { exports: {} };
+    const React = require('react');
+    const NS = '@goodandready/dsh-context-lens';
+
+    const en = {
+      title: 'Context Lens & Token Guard',
+      sub: 'AST compression, log filtering, token budget',
+      mode: 'Compression mode',
+      depth: 'AST max depth',
+      tracking: 'Track token savings',
+      preview: 'Log preview',
+      compress: 'Compress',
+      saved: 'Saved',
+      tokens: 'tokens',
+      placeholder: 'Paste Jest/Pytest log here…',
+      saving: 'Saving…',
+      ready: 'Ready'
+    };
+    const ru = {
+      title: 'Context Lens & Token Guard',
+      sub: 'Сжатие AST, фильтрация логов, контроль токенов',
+      mode: 'Режим сжатия',
+      depth: 'Глубина AST',
+      tracking: 'Считать экономию',
+      preview: 'Предпросмотр лога',
+      compress: 'Сжать',
+      saved: 'Сэкономлено',
+      tokens: 'токенов',
+      placeholder: 'Вставьте лог Jest/Pytest…',
+      saving: 'Сохранение…',
+      ready: 'Готово'
+    };
+
+    // ponytail: client-side replica of compressor for preview (no import)
+    function compressPreview(text, mode) {
+      if (!text) return '';
+      const KEEP = /(FAIL|FAILED|Error|AssertionError|Exception|Traceback|panic|npm ERR!|Expected|Received|at\s+.*:\d+:\d+)/i;
+      const lines = text.split(/\r?\n/);
+      const keep = new Array(lines.length).fill(false);
+      const ctx = mode === 'aggressive' ? 1 : 2;
+      for (let i = 0; i < lines.length; i++) if (KEEP.test(lines[i])) {
+        for (let j = Math.max(0, i - ctx); j <= Math.min(lines.length - 1, i + ctx); j++) keep[j] = true;
+      }
+      if (!keep.some(Boolean)) return lines.slice(0, 20).join('\n');
+      return lines.filter((_, i) => keep[i]).slice(0, 200).join('\n');
+    }
+
+    function PluginCard({ ctx: _ctx, t }) {
+      const [expanded, setExpanded] = React.useState(false);
+      // hooks must be before any return — React 310
+      const [draft, setDraft] = React.useState({ compressionMode: 'balanced', astSkeletonMaxDepth: 3, tokenSavingsTracking: true });
+      const [status, setStatus] = React.useState('loading');
+      const [saving, setSaving] = React.useState(false);
+      const [saveErr, setSaveErr] = React.useState('');
+      const [previewIn, setPreviewIn] = React.useState('FAIL  src/app.test.js\n  ● should handle\n    Expected 1 got 2\n    at Object.<anonymous> (src/app.test.js:10:5)\nPASS  src/ok.test.js\n');
+      const [previewOut, setPreviewOut] = React.useState('');
+      const [stats, setStats] = React.useState(null);
+
+      const scopeRef = React.useRef(null);
+      if (!scopeRef.current && _ctx && _ctx.settingsScope) {
+        try { scopeRef.current = _ctx.settingsScope.bind({ namespace: NS }); } catch (e) { scopeRef.current = null; }
+      }
+      const scope = scopeRef.current;
+
+      React.useEffect(() => {
+        if (!scope) { setStatus('unavailable'); return; }
+        let cancelled = false;
+        (async () => {
+          try {
+            const snap = await scope.get();
+            if (cancelled) return;
+            // check snapshot status if available
+            if (snap && typeof snap === 'object' && 'status' in snap) {
+              if (snap.status === 'loading') { setStatus('loading'); return; }
+              if (snap.status === 'unavailable') { setStatus('unavailable'); return; }
+            }
+            // snap is either values or wrapper with values
+            const vals = snap && snap.values ? snap.values : snap;
+            if (vals && typeof vals === 'object') {
+              setDraft((d) => ({ ...d, ...vals }));
+            }
+            setStatus('ready');
+          } catch (e) {
+            if (!cancelled) setStatus('unavailable');
+          }
+        })();
+        return () => { cancelled = true; };
+      }, [scope]);
+
+      React.useEffect(() => {
+        if (expanded) {
+          fetch('/dsh-context-lens/status').then((r) => r.ok ? r.json() : null).then((j) => { if (j && j.stats) setStats(j.stats); }).catch(() => {});
+        }
+      }, [expanded]);
+
+      const tt = t || ((k) => (en[k] || k));
+
+      let ChevronIcon = null;
+      try {
+        const prim = require('@deepseek-ai/dsh-client-ui-primitives');
+        ChevronIcon = prim && prim.IconChevronDownOutline14;
+      } catch (e) { ChevronIcon = null; }
+
+      const Chevron = ChevronIcon ? function ChevronNode(p) {
+        return React.createElement(ChevronIcon, { className: 'cl-chev' + (p.open ? ' cl-chev-open' : ''), style: { marginLeft: 'auto', color: 'var(--dsw-alias-label-tertiary)', transition: 'transform .16s', transform: p.open ? 'rotate(180deg)' : 'none' } });
+      } : function Fallback(p) {
+        return React.createElement('span', { className: 'cl-chev' + (p.open ? ' cl-chev-open' : ''), style: { marginLeft: 'auto', color: 'var(--dsw-alias-label-tertiary)' } }, '▼');
+      };
+
+      async function onSave() {
+        if (!scope) { setSaveErr('Settings unavailable'); return; }
+        setSaving(true); setSaveErr('');
+        const keys = Object.keys(draft);
+        const errs = [];
+        for (const k of keys) {
+          try { await scope.set(k, draft[k]); } catch (e) { errs.push(k + ': ' + (e && e.message || String(e))); }
+        }
+        setSaving(false);
+        if (errs.length) setSaveErr(errs.join('; '));
+      }
+
+      function onPreview() {
+        const mode = draft.compressionMode || 'balanced';
+        setPreviewOut(compressPreview(previewIn, mode));
+      }
+
+      // styles: ponytail minimal, theme vars only
+      return React.createElement('li', { className: 'cl-card', style: { border: '1px solid var(--dsw-alias-border-l2)', background: 'var(--dsw-alias-bg-layer-3)', borderRadius: 12, listStyle: 'none' } },
+        React.createElement('button', {
+          className: 'cl-head',
+          onClick: () => setExpanded(!expanded),
+          'aria-expanded': expanded,
+          style: { appearance: 'none', width: '100%', font: 'inherit', color: 'inherit', textAlign: 'left', cursor: 'pointer', background: '0 0', border: 0, borderRadius: 12, display: 'flex', alignItems: 'center', gap: 12, padding: '14px 16px' }
+        },
+          React.createElement('span', { style: { display: 'flex', flexDirection: 'column' } },
+            React.createElement('span', { className: 'cl-title', style: { color: 'var(--dsw-alias-label-primary)', fontSize: 15, fontWeight: 600, lineHeight: 1.4 } }, tt('title')),
+            React.createElement('span', { className: 'cl-sub', style: { color: 'var(--dsw-alias-label-secondary)', fontSize: 13 } }, tt('sub') + (stats ? ' · ' + tt('saved') + ' ' + (stats.savedTokens || 0) + ' ' + tt('tokens') + ' (' + (stats.savedPercent || 0) + '%)' : ''))
+          ),
+          React.createElement(Chevron, { open: expanded })
+        ),
+        expanded ? React.createElement('div', { className: 'cl-body', style: { borderTop: '1px solid var(--dsw-alias-border-l2)', margin: '0 16px', paddingBottom: 8 } },
+          status === 'loading' ? React.createElement('div', { style: { padding: 12, color: 'var(--dsw-alias-label-secondary)' } }, 'Loading…') :
+          status === 'unavailable' ? React.createElement('div', { style: { padding: 12, color: 'var(--dsw-alias-label-secondary)' } }, 'Settings unavailable — plugin not registered on host yet') :
+          React.createElement(React.Fragment, null,
+            React.createElement('div', { className: 'cl-field', style: { display: 'flex', flexDirection: 'column', gap: 6, padding: '12px 0' } },
+              React.createElement('label', { style: { fontSize: 13, color: 'var(--dsw-alias-label-secondary)' } }, tt('mode')),
+              React.createElement('select', {
+                className: 'cl-input',
+                value: draft.compressionMode,
+                onChange: (e) => setDraft((d) => ({ ...d, compressionMode: e.target.value })),
+                style: { height: 34, border: '1px solid var(--dsw-alias-border-l2)', background: 'var(--dsw-alias-bg-layer-3)', color: 'var(--dsw-alias-label-primary)', borderRadius: 8, padding: '0 12px', fontSize: 13 }
+              },
+                React.createElement('option', { value: 'raw' }, 'raw'),
+                React.createElement('option', { value: 'balanced' }, 'balanced'),
+                React.createElement('option', { value: 'aggressive' }, 'aggressive')
+              )
+            ),
+            React.createElement('div', { className: 'cl-field', style: { display: 'flex', flexDirection: 'column', gap: 6, padding: '12px 0' } },
+              React.createElement('label', { style: { fontSize: 13, color: 'var(--dsw-alias-label-secondary)' } }, tt('depth')),
+              React.createElement('input', {
+                className: 'cl-input',
+                type: 'number', min: 1, max: 10,
+                value: draft.astSkeletonMaxDepth,
+                onChange: (e) => setDraft((d) => ({ ...d, astSkeletonMaxDepth: parseInt(e.target.value, 10) || 3 })),
+                style: { height: 34, border: '1px solid var(--dsw-alias-border-l2)', background: 'var(--dsw-alias-bg-layer-3)', color: 'var(--dsw-alias-label-primary)', borderRadius: 8, padding: '0 12px', fontSize: 13 }
+              })
+            ),
+            React.createElement('div', { className: 'cl-field', style: { display: 'flex', flexDirection: 'row', alignItems: 'center', gap: 8, padding: '12px 0' } },
+              React.createElement('input', {
+                type: 'checkbox',
+                checked: !!draft.tokenSavingsTracking,
+                onChange: (e) => setDraft((d) => ({ ...d, tokenSavingsTracking: e.target.checked })),
+                id: 'cl-tracking'
+              }),
+              React.createElement('label', { htmlFor: 'cl-tracking', style: { fontSize: 13 } }, tt('tracking'))
+            ),
+            React.createElement('div', { className: 'cl-field', style: { display: 'flex', flexDirection: 'column', gap: 6, padding: '12px 0' } },
+              React.createElement('label', { style: { fontSize: 13, color: 'var(--dsw-alias-label-secondary)' } }, tt('preview')),
+              React.createElement('textarea', {
+                value: previewIn,
+                onChange: (e) => setPreviewIn(e.target.value),
+                placeholder: tt('placeholder'),
+                rows: 5,
+                style: { border: '1px solid var(--dsw-alias-border-l2)', background: 'var(--dsw-alias-bg-layer-3)', color: 'var(--dsw-alias-label-primary)', borderRadius: 8, padding: 12, fontSize: 12, fontFamily: 'monospace' }
+              }),
+              React.createElement('button', {
+                onClick: onPreview,
+                style: { appearance: 'none', font: 'inherit', cursor: 'pointer', border: '1px solid transparent', borderRadius: 8, padding: '5px 14px', fontSize: 13, background: 'var(--dsw-alias-label-primary)', color: 'var(--dsw-alias-bg-layer-3)', alignSelf: 'flex-start' }
+              }, tt('compress')),
+              previewOut ? React.createElement('pre', { style: { whiteSpace: 'pre-wrap', fontSize: 12, background: 'var(--dsw-alias-bg-layer-2, var(--dsw-alias-bg-layer-3))', padding: 12, borderRadius: 8, maxHeight: 200, overflow: 'auto' } }, previewOut) : null
+            ),
+            saveErr ? React.createElement('div', { style: { color: '#d73a4a', fontSize: 12, padding: '4px 0' } }, saveErr) : null,
+            React.createElement('div', { className: 'cl-foot', style: { borderTop: '1px solid var(--dsw-alias-border-l2)', display: 'flex', justifyContent: 'flex-end', alignItems: 'center', gap: 8, padding: '12px 0 4px' } },
+              React.createElement('button', {
+                className: 'cl-save',
+                onClick: onSave,
+                disabled: saving,
+                style: { appearance: 'none', font: 'inherit', cursor: 'pointer', border: '1px solid transparent', borderRadius: 8, padding: '5px 14px', fontSize: 13, background: 'var(--dsw-alias-label-primary)', color: 'var(--dsw-alias-bg-layer-3)', opacity: saving ? 0.6 : 1 }
+              }, saving ? tt('saving') : tt('ready'))
+            )
+          )
+        ) : null
+      );
+    }
+
+    module.exports.inject = ['slots', 'locale'];
+    module.exports.apply = function apply(ctx) {
+      try { ctx.locale.register(NS, { en, ru }); } catch (e) {}
+      if (ctx.slots) {
+        ctx.slots.register({
+          name: 'settings.plugin.item',
+          key: NS,
+          locale: NS,
+          inject: () => ({ ctx })
+        }, PluginCard);
+      }
+    };
+    return module.exports;
+  }
+});

package/lib/compression/log-compressor.js

@@ -0,0 +1,84 @@
+// ponytail: heuristic line filter, not ML — O(n) scan, no deps
+const KEEP_RE = /(FAIL|FAILED|Error|AssertionError|Exception|Traceback|panic|npm ERR!|ERR!|Expected|Received|missing|×|●|✕|FAIL:|--- FAIL|not ok|at\s+.*:\d+:\d+|stack|Caused by)/i;
+const PASS_RE = /^(PASS|\s*✓|\s*✔|\s*ok\s|…+\s*$|\s*\.\s*$)/i;
+const NOISE_RE = /^(npm (notice|warn|info)|Browserslist|cached|Downloading|Done in)/i;
+const STACK_RE = /^\s*(at\s+|File ".*", line \d+|#\d+\s+0x|goroutine \d+ \[)/;
+
+function keepLine(line, mode) {
+  if (KEEP_RE.test(line) || STACK_RE.test(line)) return true;
+  if (mode === 'raw') return !(PASS_RE.test(line) || NOISE_RE.test(line)) ? true : false;
+  // balanced/aggressive rely on context window, not bare line
+  return false;
+}
+
+export function estimateTokens(text) {
+  return Math.ceil((text || '').length / 4);
+}
+
+export function compressLog(text, { mode = 'balanced', maxLines = 400 } = {}) {
+  if (!text || typeof text !== 'string') return { compressed: '', originalTokens: 0, compressedTokens: 0, savedTokens: 0, savedPercent: 0, keptLines: 0, totalLines: 0 };
+  const lines = text.split(/\r?\n/);
+  const totalLines = lines.length;
+  if (mode === 'raw') {
+    // raw: drop only obvious noise, keep rest
+    const filtered = lines.filter((l) => !NOISE_RE.test(l) || KEEP_RE.test(l));
+    const truncated = filtered.length > maxLines ? [...filtered.slice(0, maxLines - 1), `… truncated ${filtered.length - maxLines + 1} lines`] : filtered;
+    const compressed = truncated.join('\n');
+    const originalTokens = estimateTokens(text);
+    const compressedTokens = estimateTokens(compressed);
+    return { compressed, originalTokens, compressedTokens, savedTokens: Math.max(0, originalTokens - compressedTokens), savedPercent: originalTokens ? Math.round((1 - compressedTokens / originalTokens) * 100) : 0, keptLines: truncated.length, totalLines };
+  }
+
+  const keep = new Array(lines.length).fill(false);
+  const context = mode === 'aggressive' ? 1 : 2;
+  for (let i = 0; i < lines.length; i++) {
+    if (keepLine(lines[i], mode)) {
+      const s = Math.max(0, i - context);
+      const e = Math.min(lines.length - 1, i + context);
+      for (let j = s; j <= e; j++) keep[j] = true;
+    }
+  }
+  // if nothing matched, keep first/last few lines as hint
+  if (!keep.some(Boolean)) {
+    const head = Math.min(6, lines.length);
+    for (let i = 0; i < head; i++) keep[i] = true;
+    if (lines.length > head) {
+      keep[lines.length - 1] = true;
+    }
+  }
+  // drop pure PASS/noise unless within keep window already marked via context
+  let out = [];
+  for (let i = 0; i < lines.length; i++) if (keep[i]) {
+    const l = lines[i];
+    // aggressive drops more noise even inside window
+    if (mode === 'aggressive' && (PASS_RE.test(l) || NOISE_RE.test(l)) && !KEEP_RE.test(l) && !STACK_RE.test(l)) continue;
+    out.push(l);
+  }
+
+  // collapse consecutive empty lines
+  const collapsed = [];
+  let emptyStreak = 0;
+  for (const l of out) {
+    if (l.trim() === '') { emptyStreak++; if (emptyStreak <= 1) collapsed.push(l); }
+    else { emptyStreak = 0; collapsed.push(l); }
+  }
+  out = collapsed;
+
+  // deduplicate repeated progress dots lines like "................"
+  out = out.filter((l, idx, arr) => {
+    if (/^[.\s]+$/.test(l) && l.length > 20) return false;
+    if (idx > 0 && l === arr[idx - 1] && l.trim() !== '') return false;
+    return true;
+  });
+
+  if (out.length > maxLines) {
+    const half = Math.floor((maxLines - 1) / 2);
+    out = [...out.slice(0, half), `… truncated ${out.length - maxLines + 1} lines …`, ...out.slice(out.length - half)];
+  }
+  const compressed = out.join('\n');
+  const originalTokens = estimateTokens(text);
+  const compressedTokens = estimateTokens(compressed);
+  return { compressed, originalTokens, compressedTokens, savedTokens: Math.max(0, originalTokens - compressedTokens), savedPercent: originalTokens ? Math.round((1 - compressedTokens / originalTokens) * 100) : 0, keptLines: out.length, totalLines };
+}
+
+export default { compressLog, estimateTokens };

package/lib/index.js

@@ -0,0 +1,124 @@
+import { Schema } 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';
+
+export const name = '@goodandready/dsh-context-lens';
+export const inject = ['tools', 'settings', 'webServer'];
+
+export const Config = Schema.object({
+  compressionMode: Schema.string().default('balanced').description('Log compression aggressiveness (raw/balanced/aggressive)'),
+  astSkeletonMaxDepth: Schema.number().default(3).description('Max depth for AST skeleton generation'),
+  tokenSavingsTracking: Schema.boolean().default(true).description('Track and display token budget savings')
+});
+
+const NS = '@goodandready/dsh-context-lens';
+
+// in-memory focus state
+let focusState = { paths: [], updatedAt: null };
+
+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;
+  });
+
+  // helper to record savings if enabled
+  function maybeTrack(original, compressed) {
+    try {
+      const cfg = getConfig();
+      if (cfg && cfg.tokenSavingsTracking === false) return null;
+      return tracker.record(original, compressed);
+    } catch { return tracker.record(original, compressed); }
+  }
+
+  if (ctx.tools) {
+    ctx.tools.register({
+      name: 'context_lens_focus',
+      description: 'Set focus files/folders; 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)' }
+        },
+        required: ['paths']
+      },
+      execute: async (params) => {
+        const paths = Array.isArray(params.paths) ? params.paths : [];
+        focusState = { paths, updatedAt: new Date().toISOString() };
+        return { success: true, focus: focusState, 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/nnpm)',
+      parameters: {
+        type: 'object',
+        properties: {
+          text: { type: 'string', description: 'Raw log text to compress' },
+          mode: { type: 'string', enum: ['raw', 'balanced', 'aggressive'], description: 'Compression aggressiveness' },
+          maxLines: { type: 'number', description: 'Max output lines' }
+        },
+        required: ['text']
+      },
+      execute: async (params) => {
+        const cfg = getConfig();
+        const mode = params.mode || cfg.compressionMode || 'balanced';
+        const maxLines = params.maxLines || 400;
+        const res = compressLog(params.text, { mode, maxLines });
+        maybeTrack(params.text, res.compressed);
+        return { success: true, mode, ...res };
+      }
+    });
+
+    ctx.tools.register({
+      name: 'context_lens_compress_code',
+      description: 'Generate AST skeleton for a large source file (JS/TS/Python/Go) to save context',
+      parameters: {
+        type: 'object',
+        properties: {
+          code: { type: 'string', description: 'Source code to skeletonize' },
+          language: { type: 'string', enum: ['js', 'ts', 'py', 'python', 'go'], description: 'Language hint' },
+          maxDepth: { type: 'number', description: 'Max depth' }
+        },
+        required: ['code']
+      },
+      execute: async (params) => {
+        const cfg = getConfig();
+        const maxDepth = params.maxDepth ?? cfg.astSkeletonMaxDepth ?? 3;
+        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 };
+      }
+    });
+
+    ctx.tools.register({
+      name: 'context_lens_stats',
+      description: 'Show session token savings stats for context-lens',
+      parameters: { type: 'object', properties: {} },
+      execute: async () => {
+        const stats = tracker.getStats();
+        const cfg = getConfig();
+        return { success: true, ...stats, trackingEnabled: cfg.tokenSavingsTracking !== false, focus: focusState };
+      }
+    });
+  }
+
+  // optional status route
+  if (ctx.webServer) {
+    ctx.effect(() => ctx.webServer.register({
+      kind: 'exact',
+      path: '/dsh-context-lens/status',
+      handler: (req, res) => {
+        res.setHeader('content-type', 'application/json');
+        res.end(JSON.stringify({ ok: true, plugin: 'dsh-context-lens', stats: tracker.getStats(), focus: focusState }));
+      }
+    }), 'dsh-context-lens status route');
+  }
+}
+
+export { compressLog, skeletonize };

package/lib/tokens/tracker.js

@@ -0,0 +1,31 @@
+// ponytail: in-memory per-process tracker, no DB
+let totalOriginal = 0;
+let totalCompressed = 0;
+let calls = 0;
+
+export function estimateTokens(text) {
+  return Math.ceil((text || '').length / 4);
+}
+
+export function record(originalText, compressedText) {
+  const o = estimateTokens(originalText);
+  const c = estimateTokens(compressedText);
+  totalOriginal += o;
+  totalCompressed += c;
+  calls++;
+  return { originalTokens: o, compressedTokens: c, savedTokens: Math.max(0, o - c) };
+}
+
+export function getStats() {
+  const saved = Math.max(0, totalOriginal - totalCompressed);
+  const pct = totalOriginal ? Math.round((1 - totalCompressed / totalOriginal) * 100) : 0;
+  return { totalOriginal, totalCompressed, savedTokens: saved, savedPercent: pct, calls };
+}
+
+export function reset() {
+  totalOriginal = 0;
+  totalCompressed = 0;
+  calls = 0;
+}
+
+export default { estimateTokens, record, getStats, reset };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@goodandready/dsh-context-lens",
+  "version": "0.1.0",
+  "description": "DSH plugin for AST context compression, test log filtering, and token budget guard",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "context",
+    "token-guard",
+    "ast-compression",
+    "log-filter"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GooDAnDReaDY/dsh-context-lens.git"
+  },
+  "homepage": "https://github.com/GooDAnDReaDY/dsh-context-lens#readme",
+  "bugs": {
+    "url": "https://github.com/GooDAnDReaDY/dsh-context-lens/issues"
+  },
+  "license": "MIT",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-slots"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  }
+}