squeezr-ai 1.81.2 → 1.99.2

package/dist/dashboard.js

@@ -430,7 +430,7 @@ code{font-family:'Cascadia Code','SF Mono',Consolas,monospace;font-size:.9em}
         <div class="hero-card">
           <div class="hc-label">Requests</div>
           <div class="hc-val" id="h-reqs">—</div>
-          <div class="hc-sub"><span id="h-comp">—</span> AI-compressed · det. always on</div>
+          <div class="hc-sub"><span id="h-comp">—</span> AI-compressed · det. always on<span id="h-bypassed"></span></div>
         </div>
       </div>
 
@@ -498,16 +498,16 @@ code{font-family:'Cascadia Code','SF Mono',Consolas,monospace;font-size:.9em}
             <div style="margin-top:8px;font-size:11px;color:var(--text3);text-align:center">0 here is normal when AI compression is off</div>
           </div>
         </div>
-        <!-- AI Compression -->
+        <!-- Output shaping (output-side token reduction) — pinned in the old AI-Compression slot -->
         <div class="section" style="margin:0">
-          <div class="section-head"><span class="section-title">AI Compression</span><span style="font-size:11px;color:var(--text3)">today · persisted</span></div>
+          <div class="section-head"><span class="section-title">Output</span><span style="font-size:11px;color:var(--text3)" id="out-note">what the model writes back · needs [output] enabled</span></div>
           <div class="section-body">
             <div class="cache-row">
-              <div class="cache-card"><div class="cache-label">Calls</div><div class="cache-val" id="ai-calls">—</div></div>
-              <div class="cache-card"><div class="cache-label">Saved</div><div class="cache-val" id="ai-saved" style="color:var(--brand2)">—</div></div>
-              <div class="cache-card"><div class="cache-label">Spent</div><div class="cache-val" id="ai-spent">—</div></div>
+              <div class="cache-card"><div class="cache-label">Echo (restated)</div><div class="cache-val" id="out-echo">—</div></div>
+              <div class="cache-card"><div class="cache-label">Steered</div><div class="cache-val" id="out-steered">—</div></div>
+              <div class="cache-card"><div class="cache-label">Effort lowered</div><div class="cache-val" id="out-effort">—</div></div>
             </div>
-            <div id="ai-net" style="margin-top:8px;font-size:11px;color:var(--text3);text-align:center">—</div>
+            <div style="margin-top:8px;font-size:11px;color:var(--text3);text-align:center">Echo = % of the model's output that merely restated context it was already given (lower is better).</div>
           </div>
         </div>
       </div>
@@ -1022,6 +1022,9 @@ function render(d) {
   document.getElementById('h-cost').textContent  = fmtUsd(tCost);
   document.getElementById('h-reqs').textContent  = fmt(tReqs);
   document.getElementById('h-comp').textContent  = fmt(tComps);
+  var byp = (d.bypassed_requests != null) ? d.bypassed_requests : 0;
+  var bypEl = document.getElementById('h-bypassed');
+  if (bypEl) bypEl.textContent = byp > 0 ? ' · ' + fmt(byp) + ' bypassed (not counted)' : '';
 var perEl = document.getElementById('overview-period');
   if (perEl && today.date) perEl.textContent = 'today · ' + today.date;
   // (No quality banner in the Overview — only genuine quality issues, high expand
@@ -1118,6 +1121,22 @@ var eff = (today.efficiency_pct != null) ? today.efficiency_pct : null;
       }
     }
   }
+  // Output shaping card (all-time; only meaningful when [output] enabled)
+  var out = d.output || {};
+  var setOut = function(id, v){ var e = document.getElementById(id); if(e) e.textContent = v; };
+  var echoEl = document.getElementById('out-echo');
+  if (echoEl) {
+    if (out.echo_samples > 0) {
+      echoEl.textContent = out.avg_echo_pct + '%';
+      // lower echo is better: green under 15%, amber 15-35%, red above
+      echoEl.style.color = out.avg_echo_pct <= 15 ? 'var(--brand2)' : out.avg_echo_pct <= 35 ? '#fbbf24' : 'var(--red, #e5484d)';
+    } else {
+      echoEl.textContent = '—';
+    }
+  }
+  setOut('out-steered', out.steered > 0 ? fmt(out.steered) : '—');
+  setOut('out-effort', out.effort_lowered > 0 ? fmt(out.effort_lowered) : '—');
+
   // Cost Comparison is OVERVIEW = TODAY: use today's tokens (not all-time), so the
   // sub-lines match the today money. (modelCosts already comes from today's models.)
   var cmpIn     = today.original_tokens || 0;

package/dist/deterministic.d.ts

@@ -31,4 +31,7 @@ export declare function hitPattern(pattern: string, count?: number): void;
 export declare function preprocess(text: string): string;
 export declare function preprocessRatio(original: string, processed: string): number;
 export declare function preprocessAssistant(text: string): string;
-export declare function preprocessForTool(text: string, toolName: string, pressure?: number): string;
+export type CodeLang = 'ts' | 'py' | 'go' | 'rs' | 'java' | 'c' | 'cpp';
+export declare function detectCodeLanguage(text: string): CodeLang | null;
+export declare function extractCodeStructure(text: string, lang: CodeLang): string;
+export declare function preprocessForTool(text: string, toolName: string, pressure?: number, query?: string): string;

package/dist/deterministic.js

@@ -27,6 +27,8 @@
  *      Glob — compact large file listings into directory summary
  */
 import { storeOriginal, storeSegments } from './expand.js';
+import { crushEmbeddedJson } from './contentRouter.js';
+import { crushText } from './textCrusher.js';
 // ── Pattern hit tracking (for squeezr discover) ───────────────────────────────
 export const detPatternHits = {};
 function hit(pattern) {
@@ -62,6 +64,12 @@ function looksCodeLine(raw) {
         return true; // markup / code punctuation
     if (/^[}\])>]+[,;]?$/.test(t) || /^[[({<]+$/.test(t))
         return true; // pure brackets
+    // Bare object/property key on its own line — `body:`, `"data":`, `items:` — whose
+    // value sits on following lines. No code punctuation, so the checks above miss it,
+    // yet folding repeated keys shatters the surrounding structure. A key has no spaces
+    // (rules out log prose like `ERROR: connection refused`).
+    if (/^["']?[\w$.-]+["']?:$/.test(t))
+        return true;
     return false;
 }
 function deduplicateLines(text) {
@@ -916,13 +924,21 @@ function extractGenericErrors(text) {
         return out.join('\n') + `\n... [${saved} non-error lines omitted]`;
     return text;
 }
-// Generic fallback: long unrecognised bash output — keep last N lines
-function truncateLongOutput(text, pressure = 0) {
+// Generic fallback: long unrecognised bash output. Prefer EXTRACTIVE crushing
+// (collapse near-duplicate spam, keep head/tail + high-signal lines) over blind
+// tail-keep — deterministic and cache-safe. Falls back to tail-keep if the crusher
+// can't beat it (e.g. all lines unique and low-signal).
+function truncateLongOutput(text, pressure = 0, query = '') {
     const threshold = pressure >= 0.9 ? 50 : 80;
     const keepLines = pressure >= 0.9 ? 30 : 50;
     const lines = text.split('\n');
     if (lines.length <= threshold)
         return text;
+    const crushed = crushText(text, { maxLines: keepLines, headKeep: 5, tailKeep: 8, query });
+    if (crushed.dropped > 0 && crushed.text.length < text.length) {
+        hit('textCrush');
+        return crushed.text;
+    }
     const omitted = lines.length - keepLines;
     return `... [${omitted} earlier lines omitted]\n` + lines.slice(-keepLines).join('\n');
 }
@@ -943,7 +959,7 @@ function compactFileListing(text) {
     const summary = Object.entries(byDir).sort(([, a], [, b]) => b - a).map(([d, n]) => `${d}/ (${n} files)`).join('\n');
     return `${lines.length} files total:\n${summary}`;
 }
-function applyBashPatterns(text, pressure = 0) {
+function applyBashPatterns(text, pressure = 0, query = '') {
     if (looksLikeGitDiff(text)) {
         hit('gitDiff');
         return compactGitDiff(text, pressure);
@@ -1067,7 +1083,7 @@ function applyBashPatterns(text, pressure = 0) {
         return errExtracted;
     }
     hit('truncated');
-    return truncateLongOutput(text, pressure);
+    return truncateLongOutput(text, pressure, query);
 }
 // ── Grep tool ─────────────────────────────────────────────────────────────────
 // Group matches by file, cap at MAX_PER_FILE lines each, truncate if too many files
@@ -1139,17 +1155,20 @@ function looksLikeLockfile(text) {
     const resolved = (text.match(/"resolved":|resolved "/g) ?? []).length;
     return integrity >= 10 || resolved >= 10;
 }
-// Detect source language from first 30 lines of content
-function detectCodeLanguage(text) {
+export function detectCodeLanguage(text) {
     const sample = text.split('\n').slice(0, 30).join('\n');
     if (/^import .+ from ['"]|^export (function|class|const|type|interface|default)\b|: (string|number|boolean|void|unknown)\b/.test(sample))
         return 'ts';
     if (/^from \S+ import |^def \w+\(|^class \w+[:(]/.test(sample))
         return 'py';
-    if (/^package \w+|^func \w+\(|^\s*import \(/.test(sample))
+    if (/^package \w+\n|^func \w+\(|^\s*import \(/.test(sample))
         return 'go';
     if (/^use (std|crate|self)::|^(pub\s+)?fn \w+\(|^impl\s+/.test(sample))
         return 'rs';
+    if (/^package [\w.]+;|^import [\w.]+;|^(public|private|protected|abstract|final|sealed)\s+(class|interface|enum|record)\s+\w+|public\s+static\s+void\s+main/.test(sample))
+        return 'java';
+    if (/#include\s*[<"]/.test(sample))
+        return /\b(std::|template\s*<|namespace\s|::\w|class\s+\w+)/.test(sample) ? 'cpp' : 'c';
     return null;
 }
 // Top-level structural line (column 0) per language.
@@ -1158,6 +1177,9 @@ const STRUCT_CHECKS = {
     py: (t) => /^(import |from .+ import|def |class |@\w)/.test(t),
     go: (t) => /^(import|func |type |var |const |package )\b/.test(t),
     rs: (t) => /^(use |pub |fn |struct |enum |impl |trait |mod |const |static )\b/.test(t),
+    java: (t) => /^(package |import |@\w|(public |private |protected |abstract |final |sealed |static )*\s*(class|interface|enum|record) )/.test(t),
+    c: (t) => /^(#include|#define|typedef |struct |enum |union |static |extern |const |void |int |char |long |double |float |unsigned |[A-Za-z_]\w*\s+\**[A-Za-z_]\w*\s*\()/.test(t),
+    cpp: (t) => /^(#include|#define|using |namespace |template|class |struct |enum |union |typedef |public:|private:|protected:|void |int |auto |[A-Za-z_][\w:<>]*\s+\**[A-Za-z_]\w*\s*\()/.test(t),
 };
 // An INDENTED member/method that opens a block — so we can segment per method,
 // not just per top-level symbol. Conservative: must open a block ('{' for brace
@@ -1181,7 +1203,7 @@ function isMemberOpen(line, lang) {
 // Extract structure (imports + signatures) and make each member's BODY recoverable
 // on its own via squeezr_expand("<id>~i") — so the model can pull back ONE function
 // instead of re-fetching the whole file. Segments are contiguous slices (safe).
-function extractCodeStructure(text, lang) {
+export function extractCodeStructure(text, lang) {
     const lines = text.split('\n');
     const check = STRUCT_CHECKS[lang];
     // Anchors = lines we KEEP (top-level structural + indented member openings).
@@ -1322,7 +1344,7 @@ function makeRecoverable(original, compacted) {
     const id = storeOriginal(original);
     return `${compacted}\n[squeezr_expand("${id}") — full untruncated output]`;
 }
-export function preprocessForTool(text, toolName, pressure = 0) {
+export function preprocessForTool(text, toolName, pressure = 0, query = '') {
     const tool = toolName.toLowerCase();
     // NEVER compress the result of an expand call. The whole point of squeezr_expand
     // is to deliver the FULL original back to the model; re-compacting it here (or
@@ -1332,9 +1354,20 @@ export function preprocessForTool(text, toolName, pressure = 0) {
     if (tool === 'read') {
         return makeRecoverable(text, compactReadOutput(preprocessRead(text)));
     }
+    // JSON array crush (deterministic, cache-safe, reversible). Now via the content router,
+    // so it fires on arrays of homogeneous objects whether they are the WHOLE result or
+    // EMBEDDED inside a larger one (gh api with a header, MCP envelopes, bash echo + json…).
+    // Repeated per-row keys collapse to a single header; each crushed span is self-recoverable
+    // (its marker carries squeezr_expand). Runs BEFORE the base pipeline so line-dedup/JSON-minify
+    // never touch the structured data; returned directly.
+    const crushed = crushEmbeddedJson(text);
+    if (crushed.savedChars > 0) {
+        hit('jsonTableCrush');
+        return crushed.text;
+    }
     let t = preprocess(text);
     if (tool === 'bash') {
-        t = applyBashPatterns(t, pressure);
+        t = applyBashPatterns(t, pressure, query);
     }
     else if (tool === 'grep') {
         const before = t;

package/dist/doctor.d.ts

@@ -0,0 +1,38 @@
+/**
+ * squeezr doctor — reconciles the state nothing else reconciles, because Squeezr's
+ * failure mode is SILENT: if the proxy dies, the env var drifts, or the running code is
+ * stale, you keep working — you just quietly stop saving tokens (or worse, route direct).
+ *
+ * Squeezr's take on headroom's `headroom doctor`. Each check is pass / warn / fail / skip;
+ * the process exit code is 0 (all good), 1 (warnings), or 2 (a failure) so it composes in
+ * scripts. The check LOGIC is pure and unit-tested; runDoctor() wires the real IO.
+ */
+export type CheckStatus = 'pass' | 'warn' | 'fail' | 'skip';
+export interface CheckResult {
+    name: string;
+    status: CheckStatus;
+    detail: string;
+}
+type Health = {
+    identity?: string;
+    version?: string;
+    bypassed?: boolean;
+    port?: number;
+    compression?: {
+        requests?: number;
+        savings_pct?: number;
+    };
+} | null;
+export declare function checkProxy(health: Health): CheckResult;
+export declare function checkVersion(installed: string, running: string | null): CheckResult;
+export declare function checkEnv(baseUrl: string | undefined, port: number): CheckResult;
+export declare function checkBypass(bypassed: boolean | undefined): CheckResult;
+export declare function checkSavings(requests: number | undefined, savingsPct: number | undefined): CheckResult;
+export declare function computeExitCode(checks: CheckResult[]): number;
+export declare function formatDoctor(checks: CheckResult[], exitCode: number): string;
+export declare function runDoctor(): Promise<{
+    checks: CheckResult[];
+    exitCode: number;
+    report: string;
+}>;
+export {};

package/dist/doctor.js

@@ -0,0 +1,113 @@
+/**
+ * squeezr doctor — reconciles the state nothing else reconciles, because Squeezr's
+ * failure mode is SILENT: if the proxy dies, the env var drifts, or the running code is
+ * stale, you keep working — you just quietly stop saving tokens (or worse, route direct).
+ *
+ * Squeezr's take on headroom's `headroom doctor`. Each check is pass / warn / fail / skip;
+ * the process exit code is 0 (all good), 1 (warnings), or 2 (a failure) so it composes in
+ * scripts. The check LOGIC is pure and unit-tested; runDoctor() wires the real IO.
+ */
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import http from 'node:http';
+// ── Pure check logic ─────────────────────────────────────────────────────────
+export function checkProxy(health) {
+    if (health && health.identity === 'squeezr') {
+        return { name: 'Proxy', status: 'pass', detail: `running v${health.version ?? '?'}${health.port ? ` on :${health.port}` : ''}` };
+    }
+    return { name: 'Proxy', status: 'fail', detail: 'not reachable — start it with "squeezr start"' };
+}
+export function checkVersion(installed, running) {
+    if (!running)
+        return { name: 'Version', status: 'skip', detail: 'proxy not running' };
+    if (installed === running)
+        return { name: 'Version', status: 'pass', detail: `installed and running both v${installed}` };
+    return { name: 'Version', status: 'warn', detail: `running proxy is STALE (v${running}) vs installed v${installed} — restart: "squeezr update" or "squeezr start"` };
+}
+export function checkEnv(baseUrl, port) {
+    if (!baseUrl) {
+        return { name: 'Routing', status: 'warn', detail: 'ANTHROPIC_BASE_URL is unset — traffic is NOT going through Squeezr (open a new terminal after setup)' };
+    }
+    const loopback = new RegExp(`^https?://(localhost|127\\.0\\.0\\.1):${port}(/|$)`);
+    if (loopback.test(baseUrl)) {
+        return { name: 'Routing', status: 'pass', detail: `ANTHROPIC_BASE_URL → ${baseUrl}` };
+    }
+    return { name: 'Routing', status: 'fail', detail: `ANTHROPIC_BASE_URL points elsewhere (${baseUrl}); expected http://localhost:${port}` };
+}
+export function checkBypass(bypassed) {
+    if (bypassed === undefined)
+        return { name: 'Bypass', status: 'skip', detail: 'proxy not running' };
+    if (bypassed)
+        return { name: 'Bypass', status: 'warn', detail: 'bypass is ON — compression is disabled (squeezr bypass --off to resume)' };
+    return { name: 'Bypass', status: 'pass', detail: 'compression active' };
+}
+export function checkSavings(requests, savingsPct) {
+    if (requests === undefined)
+        return { name: 'Savings', status: 'skip', detail: 'proxy not running' };
+    if (requests === 0)
+        return { name: 'Savings', status: 'skip', detail: 'no traffic yet' };
+    if (!savingsPct || savingsPct <= 0) {
+        return { name: 'Savings', status: 'warn', detail: `${requests} requests seen but ~0% saved — bypass on? stale build? all content incompressible?` };
+    }
+    return { name: 'Savings', status: 'pass', detail: `~${Math.round(savingsPct)}% saved over ${requests} requests` };
+}
+export function computeExitCode(checks) {
+    if (checks.some(c => c.status === 'fail'))
+        return 2;
+    if (checks.some(c => c.status === 'warn'))
+        return 1;
+    return 0;
+}
+const ICON = { pass: '[ok]', warn: '[warn]', fail: '[FAIL]', skip: '[skip]' };
+export function formatDoctor(checks, exitCode) {
+    const lines = ['Squeezr doctor', ''];
+    for (const c of checks)
+        lines.push(`  ${ICON[c.status].padEnd(7)} ${c.name.padEnd(9)} ${c.detail}`);
+    lines.push('');
+    lines.push(exitCode === 0 ? 'All good.' : exitCode === 1 ? 'Warnings — Squeezr works but may not be saving optimally.' : 'Failure — Squeezr is not in the request path. Fix the [FAIL] above.');
+    return lines.join('\n');
+}
+// ── IO orchestrator ──────────────────────────────────────────────────────────
+function installedVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        return require(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json')).version;
+    }
+    catch {
+        return '?';
+    }
+}
+function probeHealth(port, timeoutMs = 1500) {
+    return new Promise(resolve => {
+        const req = http.get({ host: '127.0.0.1', port, path: '/squeezr/health' }, res => {
+            let data = '';
+            res.on('data', c => { data += c; });
+            res.on('end', () => {
+                try {
+                    const json = JSON.parse(data);
+                    resolve(json && json.identity === 'squeezr' ? json : null);
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+        });
+        req.on('error', () => resolve(null));
+        req.setTimeout(timeoutMs, () => { req.destroy(); resolve(null); });
+    });
+}
+export async function runDoctor() {
+    const port = process.env.SQUEEZR_PORT ? parseInt(process.env.SQUEEZR_PORT) : 8080;
+    const health = await probeHealth(port);
+    const runningVersion = health?.version ?? null;
+    const checks = [
+        checkProxy(health),
+        checkVersion(installedVersion(), runningVersion),
+        checkEnv(process.env.ANTHROPIC_BASE_URL, health?.port ?? port),
+        checkBypass(health?.bypassed),
+        checkSavings(health?.compression?.requests, health?.compression?.savings_pct),
+    ];
+    const exitCode = computeExitCode(checks);
+    return { checks, exitCode, report: formatDoctor(checks, exitCode) };
+}

package/dist/index.js

@@ -46,7 +46,10 @@ if (PORT !== config.port) {
 const httpServer = createAdaptorServer({ fetch: app.fetch });
 // Persist caches every 60s so a crash doesn't lose more than a minute of work
 setInterval(() => { persistSessionCache(); persistExpandStore(); persistHistory(); }, 60_000).unref();
-httpServer.listen(PORT, () => {
+// Bind to loopback only: the proxy holds the user's API keys and exposes
+// state-changing control endpoints, so it must never be reachable from the LAN.
+// Matches the desktop proxy / MITM listeners, which already bind 127.0.0.1.
+httpServer.listen(PORT, '127.0.0.1', () => {
     console.log(`Squeezr v${VERSION} listening on http://localhost:${PORT}`);
     console.log(`Mode: ${config.dryRun ? 'dry-run' : 'active'}`);
     if (config.disabled)

package/dist/jsonCrush.d.ts

@@ -0,0 +1,34 @@
+/**
+ * JSON array crusher — Squeezr's take on headroom's SmartCrusher, deterministic path.
+ *
+ * A huge amount of tool output is an ARRAY OF HOMOGENEOUS OBJECTS: `gh api`, `curl`
+ * to a REST endpoint, MCP tools that return record lists, `kubectl get -o json`, etc.
+ * Minifying that JSON removes whitespace but leaves EVERY key repeated on EVERY row —
+ * `"id":`, `"name":`, `"status":`… ×N. The dominant cost is the repeated schema.
+ *
+ * This reshapes such an array into a compact table: the column names appear ONCE in a
+ * header, then one row of values per element. No key is repeated. It is:
+ *
+ *   - Deterministic  → same input → byte-identical output → prompt-cache safe.
+ *   - Reversible      → the full original JSON is stored in the expand store; the marker
+ *                       carries `squeezr_expand("<id>")` so the model can get exact JSON.
+ *   - Lossless (repr) → every value still appears in the table body; nothing is dropped.
+ *
+ * Conservative by design: it only fires when the WHOLE (trimmed) input is a JSON array of
+ * mostly-objects, there are enough rows, and the table actually saves a meaningful amount.
+ * Anything else is returned untouched. This is the low-risk, high-value core; row-dropping
+ * (the lossy SmartCrusher path) is intentionally NOT done here.
+ */
+export declare const TABLE_MARKER_RE: RegExp;
+/** 32-bit SimHash fingerprint of a text (bit-voting over its word tokens). Two texts
+ *  that share most tokens get fingerprints a small Hamming distance apart. */
+export declare function simhash32(text: string): number;
+export declare function hammingDistance(a: number, b: number): number;
+/**
+ * If `text` is (entirely) a crushable JSON array of objects, return the table form plus
+ * the char count saved. Otherwise return the input unchanged with savedChars = 0.
+ */
+export declare function crushJsonArrays(text: string): {
+    text: string;
+    savedChars: number;
+};

package/dist/jsonCrush.js

@@ -0,0 +1,177 @@
+/**
+ * JSON array crusher — Squeezr's take on headroom's SmartCrusher, deterministic path.
+ *
+ * A huge amount of tool output is an ARRAY OF HOMOGENEOUS OBJECTS: `gh api`, `curl`
+ * to a REST endpoint, MCP tools that return record lists, `kubectl get -o json`, etc.
+ * Minifying that JSON removes whitespace but leaves EVERY key repeated on EVERY row —
+ * `"id":`, `"name":`, `"status":`… ×N. The dominant cost is the repeated schema.
+ *
+ * This reshapes such an array into a compact table: the column names appear ONCE in a
+ * header, then one row of values per element. No key is repeated. It is:
+ *
+ *   - Deterministic  → same input → byte-identical output → prompt-cache safe.
+ *   - Reversible      → the full original JSON is stored in the expand store; the marker
+ *                       carries `squeezr_expand("<id>")` so the model can get exact JSON.
+ *   - Lossless (repr) → every value still appears in the table body; nothing is dropped.
+ *
+ * Conservative by design: it only fires when the WHOLE (trimmed) input is a JSON array of
+ * mostly-objects, there are enough rows, and the table actually saves a meaningful amount.
+ * Anything else is returned untouched. This is the low-risk, high-value core; row-dropping
+ * (the lossy SmartCrusher path) is intentionally NOT done here.
+ */
+import { storeOriginal } from './expand.js';
+const MIN_ITEMS = 5;
+const MIN_OBJECT_FRACTION = 0.8; // ≥80% of elements must be plain objects
+const MIN_SAVINGS_RATIO = 0.15; // only crush if it shaves ≥15% of the chars
+const LOSSY_ROW_THRESHOLD = 50; // above this many rows, drop near-duplicates (SimHash)
+const HAMMING_NEAR_DUP = 3; // rows within this 32-bit Hamming distance are "the same"
+const ROW_SIGNAL_RE = /\b(error|err|fail|failed|failure|exception|fatal|panic|denied|refused|timeout|critical|crash|oom|unhealthy|degraded)\b/i;
+// Recognises the table header this module emits (anywhere in the text, since the table
+// may be embedded in a larger tool result). Group 1 = the expand id.
+export const TABLE_MARKER_RE = /\[squeezr:table ([0-9a-f]{6,}(?:~\d+)?) —/;
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+// ── SimHash near-duplicate detection (deterministic, dependency-free) ─────────
+/** FNV-1a 32-bit hash of a token. */
+function fnv1a32(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+/** 32-bit SimHash fingerprint of a text (bit-voting over its word tokens). Two texts
+ *  that share most tokens get fingerprints a small Hamming distance apart. */
+export function simhash32(text) {
+    const tokens = text.toLowerCase().match(/[a-z0-9_]+/g) ?? [];
+    if (tokens.length === 0)
+        return 0;
+    const bits = new Array(32).fill(0);
+    for (const t of tokens) {
+        const h = fnv1a32(t);
+        for (let b = 0; b < 32; b++)
+            bits[b] += ((h >>> b) & 1) ? 1 : -1;
+    }
+    let f = 0;
+    for (let b = 0; b < 32; b++)
+        if (bits[b] > 0)
+            f |= (1 << b);
+    return f >>> 0;
+}
+export function hammingDistance(a, b) {
+    let x = (a ^ b) >>> 0;
+    let c = 0;
+    while (x) {
+        c += x & 1;
+        x >>>= 1;
+    }
+    return c;
+}
+/**
+ * Given the per-row rendered strings, return the indices to KEEP: one representative per
+ * SimHash cluster (near-duplicates dropped), plus every row that carries an error/anomaly
+ * signal (always kept). Order preserved. Deterministic.
+ */
+function selectRepresentativeRows(rowStrings) {
+    const reps = []; // simhash fingerprints of chosen representatives
+    const kept = [];
+    for (let i = 0; i < rowStrings.length; i++) {
+        if (ROW_SIGNAL_RE.test(rowStrings[i])) {
+            kept.push(i);
+            continue;
+        } // anomaly → always keep
+        const sig = simhash32(rowStrings[i]);
+        if (reps.some(r => hammingDistance(r, sig) <= HAMMING_NEAR_DUP))
+            continue; // near-dup → drop
+        reps.push(sig);
+        kept.push(i);
+    }
+    return kept;
+}
+/** Union of keys across rows, in first-seen order (deterministic). */
+function collectColumns(rows) {
+    const cols = [];
+    const seen = new Set();
+    for (const row of rows) {
+        if (!isPlainObject(row))
+            continue;
+        for (const k of Object.keys(row)) {
+            if (!seen.has(k)) {
+                seen.add(k);
+                cols.push(k);
+            }
+        }
+    }
+    return cols;
+}
+const CELL_DELIM = '\t';
+/** Render one cell. Scalars raw; strings raw unless they carry the delimiter/newline;
+ *  objects/arrays as compact JSON. Absent keys → empty cell. */
+function cell(value, present) {
+    if (!present)
+        return '';
+    if (value === null)
+        return 'null';
+    const t = typeof value;
+    if (t === 'number' || t === 'boolean')
+        return String(value);
+    if (t === 'string') {
+        const s = value;
+        return s.includes(CELL_DELIM) || s.includes('\n') ? JSON.stringify(s) : s;
+    }
+    return JSON.stringify(value);
+}
+/**
+ * If `text` is (entirely) a crushable JSON array of objects, return the table form plus
+ * the char count saved. Otherwise return the input unchanged with savedChars = 0.
+ */
+export function crushJsonArrays(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0 || (trimmed[0] !== '['))
+        return { text, savedChars: 0 };
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return { text, savedChars: 0 };
+    }
+    if (!Array.isArray(parsed) || parsed.length < MIN_ITEMS)
+        return { text, savedChars: 0 };
+    const objectCount = parsed.filter(isPlainObject).length;
+    if (objectCount / parsed.length < MIN_OBJECT_FRACTION)
+        return { text, savedChars: 0 };
+    const rows = parsed;
+    const cols = collectColumns(rows.filter(isPlainObject));
+    if (cols.length === 0)
+        return { text, savedChars: 0 };
+    const header = cols.join(CELL_DELIM);
+    const rowLines = rows.map(row => isPlainObject(row)
+        ? cols.map(c => cell(row[c], c in row)).join(CELL_DELIM)
+        // Non-object element inside a mostly-object array: keep it verbatim as JSON so
+        // nothing is lost (recoverable in full via expand anyway).
+        : JSON.stringify(row));
+    // Lossy row-drop for LARGE arrays: collapse near-duplicate rows (SimHash), always
+    // keeping anomaly/error rows. Deterministic → cache-safe. The full original is in the
+    // expand store, so dropped rows are recoverable. Small arrays keep every row.
+    let bodyLines = rowLines;
+    let omitted = 0;
+    if (rows.length > LOSSY_ROW_THRESHOLD) {
+        const kept = selectRepresentativeRows(rowLines);
+        if (kept.length < rowLines.length) {
+            bodyLines = kept.map(i => rowLines[i]);
+            omitted = rowLines.length - kept.length;
+        }
+    }
+    const id = storeOriginal(text);
+    const marker = omitted > 0
+        ? `[squeezr:table ${id} — showing ${bodyLines.length} of ${rows.length} rows × ${cols.length} cols; ${omitted} near-duplicate rows omitted; squeezr_expand("${id}") for original JSON]`
+        : `[squeezr:table ${id} — ${rows.length} rows × ${cols.length} cols; squeezr_expand("${id}") for original JSON]`;
+    const out = `${marker}\n${header}\n${bodyLines.join('\n')}`;
+    const savedChars = text.length - out.length;
+    if (savedChars <= 0 || savedChars / text.length < MIN_SAVINGS_RATIO)
+        return { text, savedChars: 0 };
+    return { text: out, savedChars };
+}

package/dist/learn.d.ts

@@ -0,0 +1,65 @@
+/**
+ * squeezr learn — offline mining of Claude Code sessions for wasteful LOOPS, writing
+ * corrections to CLAUDE.local.md. Squeezr's take on headroom's `headroom learn`.
+ *
+ * The highest-value, cheapest signal is loop detection (no LLM needed):
+ *   - error loops   — the same command fails and is retried ≥3× (the agent is stuck).
+ *   - refetch loops — the agent re-runs pagination VARIANTS of a command (`| head -50`
+ *     → `head -100` → `head -200`) because the output kept getting truncated. These
+ *     SUCCEED, so failure-only analysis misses them, yet each re-fetch re-bills the
+ *     whole (bigger) output. Canonicalising away the pagination fragment collapses the
+ *     variants to one signature so the loop becomes visible.
+ *
+ * Wasted bytes are a MEASURED lower bound from real tool-output sizes, not a guess.
+ *
+ * The pure functions here (canonicalSignature / extractToolCalls / detectLoops /
+ * renderCorrections / writeMarkerBlock) are unit-tested; runLearn() is the thin
+ * filesystem orchestrator the CLI calls.
+ */
+export interface ToolCall {
+    tool: string;
+    signature: string;
+    raw: string;
+    isError: boolean;
+    outputBytes: number;
+}
+export type LoopKind = 'error' | 'refetch';
+export interface Loop {
+    kind: LoopKind;
+    signature: string;
+    count: number;
+    wastedBytes: number;
+    sampleRaw: string;
+    tool: string;
+}
+export declare const MIN_OCCURRENCES = 3;
+/** Stable, pagination-stripped signature. Same intent → same signature. */
+export declare function canonicalSignature(tool: string, input: unknown): string;
+/**
+ * Extract normalized tool calls from Claude Code session JSONL lines. Tolerant of
+ * malformed lines and both string/array tool_result content shapes.
+ */
+export declare function extractToolCalls(lines: string[]): ToolCall[];
+export declare function detectLoops(calls: ToolCall[], minOccurrences?: number): Loop[];
+export declare const LEARN_START = "<!-- squeezr:learn:start -->";
+export declare const LEARN_END = "<!-- squeezr:learn:end -->";
+export declare function renderCorrections(loops: Loop[]): string;
+/**
+ * Insert/replace the squeezr-managed block in a CLAUDE.local.md-style file. Idempotent:
+ * re-applying the same rules yields byte-identical content; a new set replaces the old.
+ */
+export declare function writeMarkerBlock(existing: string, rulesBody: string): string;
+export interface LearnOptions {
+    apply?: boolean;
+    projectsDir?: string;
+    targetFile?: string;
+    maxSessions?: number;
+}
+export interface LearnResult {
+    sessionsScanned: number;
+    loops: Loop[];
+    report: string;
+    applied: boolean;
+    targetFile: string;
+}
+export declare function runLearn(opts?: LearnOptions): LearnResult;