squeezr-ai 1.81.2 → 1.90.0

package/dist/__tests__/learn.test.js

@@ -0,0 +1,159 @@
+import { describe, it, expect } from 'vitest';
+import { canonicalSignature, extractToolCalls, detectLoops, renderCorrections, writeMarkerBlock, LEARN_START, LEARN_END, } from '../learn.js';
+// ── canonicalSignature ───────────────────────────────────────────────────────
+describe('canonicalSignature', () => {
+    it('strips pipe-head/tail pagination so variants collapse', () => {
+        const a = canonicalSignature('Bash', { command: 'grep foo src | head -50' });
+        const b = canonicalSignature('Bash', { command: 'grep foo src | head -100' });
+        expect(a).toBe(b);
+    });
+    it('collapses LIMIT/OFFSET and bare integers to N', () => {
+        const a = canonicalSignature('Bash', { command: 'psql -c "select * from t LIMIT 20 OFFSET 0"' });
+        const b = canonicalSignature('Bash', { command: 'psql -c "select * from t LIMIT 50 OFFSET 40"' });
+        expect(a).toBe(b);
+    });
+    it('distinguishes genuinely different commands', () => {
+        const a = canonicalSignature('Bash', { command: 'ls -la' });
+        const b = canonicalSignature('Bash', { command: 'cat file.txt' });
+        expect(a).not.toBe(b);
+    });
+    it('uses tool name + input for non-Bash tools', () => {
+        const a = canonicalSignature('Grep', { pattern: 'foo', path: 'src' });
+        const b = canonicalSignature('Read', { file_path: 'src' });
+        expect(a).not.toBe(b);
+        expect(a.startsWith('grep')).toBe(true);
+    });
+});
+// ── extractToolCalls ─────────────────────────────────────────────────────────
+describe('extractToolCalls', () => {
+    const lines = [
+        JSON.stringify({ type: 'user', message: { content: [{ type: 'text', text: 'hi' }] } }),
+        JSON.stringify({ type: 'assistant', message: { content: [{ type: 'tool_use', id: 't1', name: 'Bash', input: { command: 'npm test' } }] } }),
+        JSON.stringify({ type: 'user', message: { content: [{ type: 'tool_result', tool_use_id: 't1', content: 'FAIL', is_error: true }] } }),
+    ];
+    it('pairs tool_use with its tool_result (name, error flag, output size)', () => {
+        const calls = extractToolCalls(lines);
+        expect(calls.length).toBe(1);
+        expect(calls[0].tool).toBe('Bash');
+        expect(calls[0].isError).toBe(true);
+        expect(calls[0].outputBytes).toBe('FAIL'.length);
+    });
+    it('tolerates malformed / non-JSON lines', () => {
+        const calls = extractToolCalls([...lines, 'not json', '']);
+        expect(calls.length).toBe(1);
+    });
+    it('handles array-form tool_result content', () => {
+        const l = [
+            JSON.stringify({ type: 'assistant', message: { content: [{ type: 'tool_use', id: 'x', name: 'Read', input: { file_path: 'a' } }] } }),
+            JSON.stringify({ type: 'user', message: { content: [{ type: 'tool_result', tool_use_id: 'x', content: [{ type: 'text', text: 'hello' }] }] } }),
+        ];
+        const calls = extractToolCalls(l);
+        expect(calls[0].outputBytes).toBeGreaterThan(0);
+        expect(calls[0].isError).toBe(false);
+    });
+});
+// ── detectLoops ──────────────────────────────────────────────────────────────
+function call(tool, command, isError, outputBytes = 100) {
+    return { tool, signature: canonicalSignature(tool, { command }), raw: command, isError, outputBytes };
+}
+describe('detectLoops', () => {
+    it('flags an error loop when the same signature fails >=3 times', () => {
+        const calls = [
+            call('Bash', 'npm run build', true, 500),
+            call('Bash', 'npm run build', true, 500),
+            call('Bash', 'npm run build', true, 500),
+        ];
+        const loops = detectLoops(calls);
+        const err = loops.find(l => l.kind === 'error');
+        expect(err).toBeDefined();
+        expect(err.count).toBe(3);
+        expect(err.wastedBytes).toBe(1500);
+    });
+    it('does not flag fewer than the minimum occurrences', () => {
+        const calls = [call('Bash', 'npm run build', true), call('Bash', 'npm run build', true)];
+        expect(detectLoops(calls).length).toBe(0);
+    });
+    it('flags a refetch loop: same signature, different raw variants, all succeeding', () => {
+        const calls = [
+            call('Bash', 'grep foo src | head -50', false, 2000),
+            call('Bash', 'grep foo src | head -100', false, 4000),
+            call('Bash', 'grep foo src | head -200', false, 8000),
+        ];
+        const loops = detectLoops(calls);
+        const refetch = loops.find(l => l.kind === 'refetch');
+        expect(refetch).toBeDefined();
+        expect(refetch.count).toBe(3);
+        // wasted = redundant follow-ups (all but the first)
+        expect(refetch.wastedBytes).toBe(12000);
+    });
+    it('does not flag a refetch when the raw command is identical every time (that is caching, not a loop)', () => {
+        const calls = [
+            call('Bash', 'ls', false),
+            call('Bash', 'ls', false),
+            call('Bash', 'ls', false),
+        ];
+        expect(detectLoops(calls).find(l => l.kind === 'refetch')).toBeUndefined();
+    });
+    it('classifies a signature with errors as an error loop, not a refetch (even with raw variants)', () => {
+        // Same canonical signature (pagination stripped) + distinct raw + all errored:
+        // errors win → error loop, never also reported as a refetch.
+        const calls = [
+            call('Bash', 'grep foo | head -50', true),
+            call('Bash', 'grep foo | head -100', true),
+            call('Bash', 'grep foo | head -200', true),
+        ];
+        const loops = detectLoops(calls);
+        expect(loops.some(l => l.kind === 'error')).toBe(true);
+        expect(loops.some(l => l.kind === 'refetch')).toBe(false);
+    });
+    it('ranks loops by wasted bytes descending', () => {
+        const calls = [
+            call('Bash', 'small | head -1', false, 100),
+            call('Bash', 'small | head -2', false, 100),
+            call('Bash', 'small | head -3', false, 100),
+            call('Bash', 'big', true, 9000),
+            call('Bash', 'big', true, 9000),
+            call('Bash', 'big', true, 9000),
+        ];
+        const loops = detectLoops(calls);
+        expect(loops[0].wastedBytes).toBeGreaterThanOrEqual(loops[loops.length - 1].wastedBytes);
+    });
+});
+// ── renderCorrections ────────────────────────────────────────────────────────
+describe('renderCorrections', () => {
+    it('produces a bullet per loop mentioning the signature', () => {
+        const loops = detectLoops([
+            call('Bash', 'npm run build', true, 500),
+            call('Bash', 'npm run build', true, 500),
+            call('Bash', 'npm run build', true, 500),
+        ]);
+        const text = renderCorrections(loops);
+        expect(text.includes('npm run build')).toBe(true);
+        expect(text.split('\n').some(l => l.trim().startsWith('-'))).toBe(true);
+    });
+    it('returns empty string for no loops', () => {
+        expect(renderCorrections([])).toBe('');
+    });
+});
+// ── writeMarkerBlock ─────────────────────────────────────────────────────────
+describe('writeMarkerBlock', () => {
+    it('appends a marked block to fresh content', () => {
+        const out = writeMarkerBlock('# Project\n\nsome notes\n', 'rule one');
+        expect(out.includes(LEARN_START)).toBe(true);
+        expect(out.includes(LEARN_END)).toBe(true);
+        expect(out.includes('rule one')).toBe(true);
+        expect(out.startsWith('# Project')).toBe(true);
+    });
+    it('replaces an existing block instead of stacking (idempotent shape)', () => {
+        const first = writeMarkerBlock('base\n', 'rule one');
+        const second = writeMarkerBlock(first, 'rule two');
+        expect((second.match(new RegExp(LEARN_START, 'g')) ?? []).length).toBe(1);
+        expect(second.includes('rule two')).toBe(true);
+        expect(second.includes('rule one')).toBe(false);
+    });
+    it('re-applying the SAME block yields byte-identical content', () => {
+        const first = writeMarkerBlock('base\n', 'rule one');
+        const second = writeMarkerBlock(first, 'rule one');
+        expect(second).toBe(first);
+    });
+});

package/dist/__tests__/outputShaper.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/outputShaper.test.js

@@ -0,0 +1,216 @@
+import { describe, it, expect } from 'vitest';
+import { classifyTurn, steeringText, applyVerbositySteering, routeEffort, shapeRequest, STEERING_START, STEERING_END, } from '../outputShaper.js';
+const DEFAULTS = {
+    enabled: true,
+    verbositySteering: true,
+    level: 2,
+    effortRouting: true,
+    mechanicalThinkingFloor: 1024,
+};
+function userText(t) {
+    return { role: 'user', content: [{ type: 'text', text: t }] };
+}
+function toolResult(id, content = 'ok', isError = false) {
+    return {
+        role: 'user',
+        content: [{ type: 'tool_result', tool_use_id: id, content, is_error: isError }],
+    };
+}
+function assistantToolUse(id) {
+    return { role: 'assistant', content: [{ type: 'tool_use', id, name: 'Bash', input: {} }] };
+}
+// ── classifyTurn ─────────────────────────────────────────────────────────────
+describe('classifyTurn', () => {
+    it('a clean tool_result as the last message → mechanical', () => {
+        const msgs = [userText('do a thing'), assistantToolUse('t1'), toolResult('t1', 'file contents')];
+        expect(classifyTurn(msgs)).toBe('mechanical');
+    });
+    it('a tool_result with is_error → error', () => {
+        const msgs = [userText('do a thing'), assistantToolUse('t1'), toolResult('t1', 'boom', true)];
+        expect(classifyTurn(msgs)).toBe('error');
+    });
+    it('a fresh user text message → new-ask', () => {
+        const msgs = [userText('first'), assistantToolUse('t1'), toolResult('t1'), userText('now do this')];
+        expect(classifyTurn(msgs)).toBe('new-ask');
+    });
+    it('string user content → new-ask', () => {
+        const msgs = [{ role: 'user', content: 'hello there' }];
+        expect(classifyTurn(msgs)).toBe('new-ask');
+    });
+    it('tool_result string content field on error flag detected → error', () => {
+        const msgs = [
+            { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'x', content: 'err', is_error: true }] },
+        ];
+        expect(classifyTurn(msgs)).toBe('error');
+    });
+    it('empty messages → unknown', () => {
+        expect(classifyTurn([])).toBe('unknown');
+    });
+    it('last message is assistant → unknown', () => {
+        const msgs = [userText('hi'), assistantToolUse('t1')];
+        expect(classifyTurn(msgs)).toBe('unknown');
+    });
+});
+// ── steeringText ─────────────────────────────────────────────────────────────
+describe('steeringText', () => {
+    it('is byte-stable for the same level', () => {
+        expect(steeringText(2)).toBe(steeringText(2));
+    });
+    it('higher levels are more aggressive (longer or different)', () => {
+        expect(steeringText(1)).not.toBe(steeringText(4));
+    });
+    it('is wrapped in the sentinel markers', () => {
+        const t = steeringText(2);
+        expect(t.startsWith(STEERING_START)).toBe(true);
+        expect(t.trimEnd().endsWith(STEERING_END)).toBe(true);
+    });
+});
+// ── applyVerbositySteering ───────────────────────────────────────────────────
+describe('applyVerbositySteering', () => {
+    it('appends a text block to an array system prompt', () => {
+        const body = {
+            system: [{ type: 'text', text: 'You are Claude.', cache_control: { type: 'ephemeral' } }],
+        };
+        const changed = applyVerbositySteering(body, 2);
+        expect(changed).toBe(true);
+        const sys = body.system;
+        expect(sys.length).toBe(2);
+        expect(sys[1].text.includes(STEERING_START)).toBe(true);
+    });
+    it('never mutates the existing cache_control block', () => {
+        const body = {
+            system: [{ type: 'text', text: 'You are Claude.', cache_control: { type: 'ephemeral' } }],
+        };
+        applyVerbositySteering(body, 2);
+        const sys = body.system;
+        expect(sys[0].text).toBe('You are Claude.');
+        expect(sys[0].cache_control).toEqual({ type: 'ephemeral' });
+    });
+    it('appends to a string system prompt', () => {
+        const body = { system: 'You are Claude.' };
+        applyVerbositySteering(body, 2);
+        expect(body.system.startsWith('You are Claude.')).toBe(true);
+        expect(body.system.includes(STEERING_START)).toBe(true);
+    });
+    it('is idempotent — applying twice yields byte-identical system (cache-safe)', () => {
+        const body = {
+            system: [{ type: 'text', text: 'You are Claude.', cache_control: { type: 'ephemeral' } }],
+        };
+        applyVerbositySteering(body, 2);
+        const afterFirst = JSON.stringify(body.system);
+        applyVerbositySteering(body, 2);
+        const afterSecond = JSON.stringify(body.system);
+        expect(afterSecond).toBe(afterFirst);
+    });
+    it('re-steering at a new level replaces the old block (no stacking)', () => {
+        const body = {
+            system: [{ type: 'text', text: 'You are Claude.' }],
+        };
+        applyVerbositySteering(body, 2);
+        applyVerbositySteering(body, 4);
+        const sys = body.system;
+        const steeringBlocks = sys.filter(b => (b.text ?? '').includes(STEERING_START));
+        expect(steeringBlocks.length).toBe(1);
+        expect(steeringBlocks[0].text).toBe(steeringText(4));
+    });
+});
+// ── routeEffort ──────────────────────────────────────────────────────────────
+describe('routeEffort', () => {
+    it('lowers an existing thinking.budget_tokens to the floor', () => {
+        const body = { thinking: { type: 'enabled', budget_tokens: 16000 } };
+        const lowered = routeEffort(body, 1024);
+        expect(lowered).toBe(true);
+        expect(body.thinking.budget_tokens).toBe(1024);
+    });
+    it('never toggles thinking.type', () => {
+        const body = { thinking: { type: 'enabled', budget_tokens: 16000 } };
+        routeEffort(body, 1024);
+        expect(body.thinking.type).toBe('enabled');
+    });
+    it('does not raise a budget already below the floor', () => {
+        const body = { thinking: { type: 'enabled', budget_tokens: 512 } };
+        const lowered = routeEffort(body, 1024);
+        expect(lowered).toBe(false);
+        expect(body.thinking.budget_tokens).toBe(512);
+    });
+    it('lowers an explicit output_config.effort but never injects one', () => {
+        const withEffort = { output_config: { effort: 'xhigh' } };
+        expect(routeEffort(withEffort, 1024)).toBe(true);
+        expect(withEffort.output_config.effort).toBe('low');
+        const withoutEffort = {};
+        expect(routeEffort(withoutEffort, 1024)).toBe(false);
+        expect(withoutEffort.output_config).toBeUndefined();
+    });
+    it('does nothing when no effort levers are present', () => {
+        const body = {};
+        expect(routeEffort(body, 1024)).toBe(false);
+        expect(body.thinking).toBeUndefined();
+    });
+});
+// ── shapeRequest (orchestration) ─────────────────────────────────────────────
+describe('shapeRequest', () => {
+    it('no-op when disabled — body untouched', () => {
+        const body = {
+            system: [{ type: 'text', text: 'You are Claude.' }],
+            thinking: { type: 'enabled', budget_tokens: 16000 },
+            messages: [toolResult('t1')],
+        };
+        const before = JSON.stringify(body);
+        const r = shapeRequest(body, { ...DEFAULTS, enabled: false });
+        expect(r.steered).toBe(false);
+        expect(r.effortLowered).toBe(false);
+        expect(JSON.stringify(body)).toBe(before);
+    });
+    it('mechanical turn: both steers and lowers effort', () => {
+        const body = {
+            system: [{ type: 'text', text: 'You are Claude.' }],
+            thinking: { type: 'enabled', budget_tokens: 16000 },
+            messages: [userText('go'), assistantToolUse('t1'), toolResult('t1', 'contents')],
+        };
+        const r = shapeRequest(body, DEFAULTS);
+        expect(r.turn).toBe('mechanical');
+        expect(r.steered).toBe(true);
+        expect(r.effortLowered).toBe(true);
+        expect(body.thinking.budget_tokens).toBe(1024);
+    });
+    it('new-ask turn: steers but keeps full effort', () => {
+        const body = {
+            system: [{ type: 'text', text: 'You are Claude.' }],
+            thinking: { type: 'enabled', budget_tokens: 16000 },
+            messages: [toolResult('t1'), userText('new question')],
+        };
+        const r = shapeRequest(body, DEFAULTS);
+        expect(r.turn).toBe('new-ask');
+        expect(r.steered).toBe(true);
+        expect(r.effortLowered).toBe(false);
+        expect(body.thinking.budget_tokens).toBe(16000);
+    });
+    it('error turn: keeps full effort', () => {
+        const body = {
+            system: [{ type: 'text', text: 'You are Claude.' }],
+            thinking: { type: 'enabled', budget_tokens: 16000 },
+            messages: [assistantToolUse('t1'), toolResult('t1', 'boom', true)],
+        };
+        const r = shapeRequest(body, DEFAULTS);
+        expect(r.turn).toBe('error');
+        expect(r.effortLowered).toBe(false);
+    });
+    it('effort routing disabled: never lowers even on mechanical turns', () => {
+        const body = {
+            thinking: { type: 'enabled', budget_tokens: 16000 },
+            messages: [toolResult('t1')],
+        };
+        const r = shapeRequest(body, { ...DEFAULTS, effortRouting: false });
+        expect(r.effortLowered).toBe(false);
+        expect(body.thinking.budget_tokens).toBe(16000);
+    });
+    it('verbosity steering disabled: never touches the system prompt', () => {
+        const body = {
+            system: [{ type: 'text', text: 'You are Claude.' }],
+            messages: [toolResult('t1')],
+        };
+        const r = shapeRequest(body, { ...DEFAULTS, verbositySteering: false });
+        expect(r.steered).toBe(false);
+        expect(body.system.length).toBe(1);
+    });
+});

package/dist/__tests__/textCrusher.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/textCrusher.test.js

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import { crushText, normalizeLineKey } from '../textCrusher.js';
+describe('normalizeLineKey', () => {
+    it('collapses numbers, hex and timestamps so near-duplicates share a key', () => {
+        const a = normalizeLineKey('2026-07-21T10:00:01Z downloaded chunk 12 (0x1a2b)');
+        const b = normalizeLineKey('2026-07-21T11:22:33Z downloaded chunk 998 (0xff00)');
+        expect(a).toBe(b);
+    });
+    it('keeps genuinely different lines distinct', () => {
+        expect(normalizeLineKey('connecting to db')).not.toBe(normalizeLineKey('closing db handle'));
+    });
+});
+describe('crushText', () => {
+    function repetitiveLog(n) {
+        const lines = [];
+        for (let i = 0; i < n; i++)
+            lines.push(`[worker] processed record ${i} in ${i * 2}ms`);
+        return lines.join('\n');
+    }
+    it('returns short input unchanged', () => {
+        const input = 'line a\nline b\nline c';
+        expect(crushText(input, { maxLines: 60 }).text).toBe(input);
+    });
+    it('collapses near-duplicate lines that differ only in numbers', () => {
+        const input = repetitiveLog(200);
+        const res = crushText(input);
+        expect(res.dropped).toBeGreaterThan(0);
+        expect(res.text.length).toBeLessThan(input.length);
+        expect(res.text.split('\n').length).toBeLessThan(200);
+    });
+    it('always keeps lines carrying error/failure signal', () => {
+        const lines = [];
+        for (let i = 0; i < 150; i++)
+            lines.push(`[worker] processed record ${i} ok`);
+        lines.splice(75, 0, 'ERROR: database connection refused at db.example.com:5432');
+        const input = lines.join('\n');
+        const res = crushText(input);
+        expect(res.text.includes('ERROR: database connection refused at db.example.com:5432')).toBe(true);
+    });
+    it('keeps head and tail anchor lines', () => {
+        const lines = ['FIRST LINE MARKER'];
+        for (let i = 0; i < 150; i++)
+            lines.push(`noise line ${i} value ${i}`);
+        lines.push('LAST LINE MARKER');
+        const input = lines.join('\n');
+        const res = crushText(input, { headKeep: 3, tailKeep: 3 });
+        expect(res.text.includes('FIRST LINE MARKER')).toBe(true);
+        expect(res.text.includes('LAST LINE MARKER')).toBe(true);
+    });
+    it('respects the maxLines budget (plus the omitted-summary line)', () => {
+        const res = crushText(repetitiveLog(500), { maxLines: 40 });
+        // kept content lines should not wildly exceed the budget
+        expect(res.text.split('\n').length).toBeLessThanOrEqual(45);
+    });
+    it('preserves the original order of kept lines', () => {
+        const lines = ['alpha unique', ...Array.from({ length: 100 }, (_, i) => `dup ${i}`), 'omega unique'];
+        const res = crushText(lines.join('\n'), { headKeep: 2, tailKeep: 2 });
+        const idxA = res.text.indexOf('alpha unique');
+        const idxO = res.text.indexOf('omega unique');
+        expect(idxA).toBeGreaterThanOrEqual(0);
+        expect(idxO).toBeGreaterThan(idxA);
+    });
+    it('is deterministic', () => {
+        const input = repetitiveLog(300);
+        expect(crushText(input).text).toBe(crushText(input).text);
+    });
+    it('emits an omitted-count marker when it drops lines', () => {
+        const res = crushText(repetitiveLog(300));
+        expect(/\[\d+ lines omitted/.test(res.text)).toBe(true);
+    });
+});

package/dist/bench.d.ts

@@ -0,0 +1,45 @@
+/**
+ * squeezr bench — honest, reproducible compression+accuracy harness.
+ *
+ * Headroom's headline claim is "same answers, fewer tokens", proven by having an LLM
+ * answer questions over compressed data. That needs an API key and costs money, so it
+ * can't live in CI. This harness measures the same thing with a zero-cost, deterministic
+ * proxy for accuracy: FACT RECALL.
+ *
+ * For each fixture we declare the CRITICAL FACTS an answer would need (an error code, a
+ * filename, a specific value, a count). We compress the fixture through Squeezr's real
+ * deterministic pipeline and measure:
+ *
+ *   - compressionPct — chars removed / original chars.
+ *   - inlineRecall    — fraction of critical facts still present VERBATIM in the compressed
+ *                       output (i.e. answerable WITHOUT an expand round-trip).
+ *
+ * Recoverability is 100% by design (every compressed block stores its original in the
+ * expand store — see expand.test.ts), so the meaningful, honest metric is how much
+ * survives inline. A fixture that trades recall for ratio (huge-log head/tail) shows it
+ * here rather than hiding it.
+ */
+export interface Fixture {
+    name: string;
+    tool: string;
+    content: string;
+    facts: string[];
+}
+export interface BenchRow {
+    name: string;
+    originalChars: number;
+    compressedChars: number;
+    compressionPct: number;
+    inlineRecall: number;
+}
+export interface BenchSummary {
+    rows: BenchRow[];
+    avgCompressionPct: number;
+    avgInlineRecall: number;
+}
+/** Fraction of `facts` present verbatim in `text`. Empty fact list → 1 (nothing to lose). */
+export declare function factRecall(text: string, facts: string[]): number;
+export declare const FIXTURES: Fixture[];
+export declare function runBench(fixtures?: Fixture[]): BenchSummary;
+/** Human-readable table for the CLI. */
+export declare function formatBench(summary: BenchSummary): string;

package/dist/bench.js

@@ -0,0 +1,114 @@
+/**
+ * squeezr bench — honest, reproducible compression+accuracy harness.
+ *
+ * Headroom's headline claim is "same answers, fewer tokens", proven by having an LLM
+ * answer questions over compressed data. That needs an API key and costs money, so it
+ * can't live in CI. This harness measures the same thing with a zero-cost, deterministic
+ * proxy for accuracy: FACT RECALL.
+ *
+ * For each fixture we declare the CRITICAL FACTS an answer would need (an error code, a
+ * filename, a specific value, a count). We compress the fixture through Squeezr's real
+ * deterministic pipeline and measure:
+ *
+ *   - compressionPct — chars removed / original chars.
+ *   - inlineRecall    — fraction of critical facts still present VERBATIM in the compressed
+ *                       output (i.e. answerable WITHOUT an expand round-trip).
+ *
+ * Recoverability is 100% by design (every compressed block stores its original in the
+ * expand store — see expand.test.ts), so the meaningful, honest metric is how much
+ * survives inline. A fixture that trades recall for ratio (huge-log head/tail) shows it
+ * here rather than hiding it.
+ */
+import { preprocessForTool } from './deterministic.js';
+/** Fraction of `facts` present verbatim in `text`. Empty fact list → 1 (nothing to lose). */
+export function factRecall(text, facts) {
+    if (facts.length === 0)
+        return 1;
+    const present = facts.filter(f => text.includes(f)).length;
+    return present / facts.length;
+}
+// ── Fixtures ─────────────────────────────────────────────────────────────────
+function jsonArrayFixture() {
+    const rows = [];
+    for (let i = 0; i < 40; i++) {
+        rows.push({ id: i, service: `svc-${i}`, status: i === 17 ? 'CrashLoopBackOff' : 'Running', restarts: i === 17 ? 42 : 0, node: 'ip-10-0-1-5' });
+    }
+    return JSON.stringify(rows);
+}
+function buildLogFixture() {
+    const lines = [];
+    for (let i = 0; i < 60; i++)
+        lines.push('[webpack] compiling module... ok');
+    lines.push('ERROR in ./src/app.ts:128:14');
+    lines.push("TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.");
+    for (let i = 0; i < 60; i++)
+        lines.push('[webpack] compiling module... ok');
+    return lines.join('\n');
+}
+function grepFixture() {
+    const lines = [];
+    for (let f = 0; f < 30; f++) {
+        for (let l = 0; l < 5; l++)
+            lines.push(`src/mod${f}.ts:${l + 1}: const value = computeThing(${l})`);
+    }
+    lines.push('src/critical.ts:99: throw new FatalError("DISK_FULL")');
+    return lines.join('\n');
+}
+export const FIXTURES = [
+    {
+        name: 'json-array (k8s pods)',
+        tool: 'Bash',
+        content: jsonArrayFixture(),
+        // The one anomalous row an answer would need + its schema.
+        facts: ['CrashLoopBackOff', '42', 'svc-17', 'ip-10-0-1-5'],
+    },
+    {
+        name: 'build-log (tsc error in noise)',
+        tool: 'Bash',
+        content: buildLogFixture(),
+        facts: ['TS2345', './src/app.ts:128:14'],
+    },
+    {
+        name: 'grep-dump (fatal among matches)',
+        tool: 'Grep',
+        content: grepFixture(),
+        facts: ['DISK_FULL', 'src/critical.ts:99'],
+    },
+];
+// ── Runner ───────────────────────────────────────────────────────────────────
+export function runBench(fixtures = FIXTURES) {
+    const rows = fixtures.map(f => {
+        const compressed = preprocessForTool(f.content, f.tool, 0);
+        const originalChars = f.content.length;
+        const compressedChars = compressed.length;
+        const compressionPct = originalChars > 0 ? Math.max(0, ((originalChars - compressedChars) / originalChars) * 100) : 0;
+        return {
+            name: f.name,
+            originalChars,
+            compressedChars,
+            compressionPct: Math.round(compressionPct * 10) / 10,
+            inlineRecall: factRecall(compressed, f.facts),
+        };
+    });
+    const n = rows.length || 1;
+    return {
+        rows,
+        avgCompressionPct: Math.round((rows.reduce((s, r) => s + r.compressionPct, 0) / n) * 10) / 10,
+        avgInlineRecall: Math.round((rows.reduce((s, r) => s + r.inlineRecall, 0) / n) * 100) / 100,
+    };
+}
+/** Human-readable table for the CLI. */
+export function formatBench(summary) {
+    const lines = [];
+    lines.push('Squeezr compression + fact-recall benchmark');
+    lines.push('(recoverability is 100% by design via squeezr_expand; inline recall = answerable without expanding)');
+    lines.push('');
+    lines.push('fixture                              orig    comp   saved   inline-recall');
+    lines.push('─'.repeat(78));
+    for (const r of summary.rows) {
+        lines.push(`${r.name.padEnd(36)} ${String(r.originalChars).padStart(6)} ${String(r.compressedChars).padStart(6)} ${(r.compressionPct + '%').padStart(6)}   ${Math.round(r.inlineRecall * 100) + '%'}`);
+    }
+    lines.push('─'.repeat(78));
+    lines.push(`AVG: ${summary.avgCompressionPct}% compression · ${Math.round(summary.avgInlineRecall * 100)}% inline fact recall · 100% recoverable`);
+    return lines.join('\n');
+}

package/dist/cacheAligner.d.ts

@@ -0,0 +1,34 @@
+/**
+ * CacheAligner (detector-only) — Squeezr's take on headroom's CacheAligner.
+ *
+ * Anthropic bills the cached prefix at 0.1x, but ONLY if the prefix arrives byte-for-byte
+ * identical between requests. If the CLIENT's own system prompt embeds volatile content
+ * (a per-session UUID, a live timestamp, a build hash, a JWT) INSIDE the cached region,
+ * that prefix changes every request and the cache never hits — re-billing the whole
+ * context at full price. That is exactly the failure that once burned a 5h plan.
+ *
+ * Squeezr already monitors cache hit-health %; this tells you the likely CAUSE. It is a
+ * pure DETECTOR: it never mutates the prompt (mutating the cache hot zone is itself a
+ * cache-buster). It just surfaces "your prefix is unstable because of X".
+ *
+ * Detection is structural (shape-based regex over known volatile token forms), not
+ * semantic. Order matters: JWTs are matched before hashes so a JWT segment isn't
+ * miscounted as a hex hash.
+ */
+export type VolatileKind = 'uuid' | 'timestamp' | 'jwt' | 'hash';
+export interface VolatileFinding {
+    kind: VolatileKind;
+    count: number;
+}
+/** Structural scan for volatile tokens. Matched kinds are masked out before later
+ *  patterns run, so a JWT is never also counted as a hash. */
+export declare function detectVolatile(text: string): VolatileFinding[];
+export interface SystemAnalysis {
+    hasVolatile: boolean;
+    findings: VolatileFinding[];
+}
+export declare function analyzeSystemPrompt(system: unknown): SystemAnalysis;
+export declare function formatVolatileWarning(findings: VolatileFinding[]): string;
+/** Warn at most once per distinct finding signature. Returns true iff it warned now. */
+export declare function warnIfVolatile(system: unknown): boolean;
+export declare function _resetWarnedForTest(): void;