squeezr-ai 1.81.2 → 1.99.2

package/dist/learn.js

@@ -0,0 +1,244 @@
+/**
+ * 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.
+ */
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+export const MIN_OCCURRENCES = 3;
+// ── Canonical signature ──────────────────────────────────────────────────────
+// Fragments that vary between re-fetches of "the same" query but don't change intent.
+const PAGINATION_PATTERNS = [
+    /\|\s*head\s+-?n?\s*\d+/gi, // | head -50 / | head -n 50
+    /\|\s*tail\s+-?n?\s*\d+/gi, // | tail -50
+    /\bhead\s+-n\s*\d+/gi,
+    /\btail\s+-n\s*\d+/gi,
+    /\b-n\s+\d+/gi, // -n 50
+    /\blimit\s+\d+/gi, // LIMIT 50
+    /\boffset\s+\d+/gi, // OFFSET 40
+    /--limit[=\s]+\d+/gi,
+    /--offset[=\s]+\d+/gi,
+    /[?&](?:per_page|page|limit|offset)=\d+/gi,
+];
+function inputToString(tool, input) {
+    if (input && typeof input === 'object') {
+        const obj = input;
+        if (typeof obj.command === 'string')
+            return obj.command;
+        // Deterministic: sort keys so the signature is stable.
+        const keys = Object.keys(obj).sort();
+        return keys.map(k => `${k}=${typeof obj[k] === 'object' ? JSON.stringify(obj[k]) : String(obj[k])}`).join(' ');
+    }
+    return String(input ?? '');
+}
+/** Stable, pagination-stripped signature. Same intent → same signature. */
+export function canonicalSignature(tool, input) {
+    let s = `${tool.toLowerCase()} ${inputToString(tool, input)}`;
+    for (const re of PAGINATION_PATTERNS)
+        s = s.replace(re, ' ');
+    s = s.replace(/\b\d+\b/g, 'N'); // collapse remaining bare integers
+    s = s.replace(/\s+/g, ' ').trim().toLowerCase();
+    return s;
+}
+// ── Parse Claude Code JSONL ──────────────────────────────────────────────────
+function contentBytes(content) {
+    if (typeof content === 'string')
+        return content.length;
+    if (Array.isArray(content))
+        return JSON.stringify(content).length;
+    if (content && typeof content === 'object')
+        return JSON.stringify(content).length;
+    return 0;
+}
+/**
+ * Extract normalized tool calls from Claude Code session JSONL lines. Tolerant of
+ * malformed lines and both string/array tool_result content shapes.
+ */
+export function extractToolCalls(lines) {
+    const uses = new Map();
+    const results = new Map();
+    const order = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        const msg = obj?.message;
+        const content = msg?.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (block?.type === 'tool_use' && typeof block.id === 'string' && typeof block.name === 'string') {
+                const raw = inputToString(block.name, block.input);
+                uses.set(block.id, { tool: block.name, raw, signature: canonicalSignature(block.name, block.input) });
+                order.push(block.id);
+            }
+            else if (block?.type === 'tool_result' && typeof block.tool_use_id === 'string') {
+                results.set(block.tool_use_id, {
+                    isError: !!block.is_error,
+                    outputBytes: contentBytes(block.content),
+                });
+            }
+        }
+    }
+    const calls = [];
+    for (const id of order) {
+        const u = uses.get(id);
+        if (!u)
+            continue;
+        const r = results.get(id);
+        calls.push({ tool: u.tool, signature: u.signature, raw: u.raw, isError: r?.isError ?? false, outputBytes: r?.outputBytes ?? 0 });
+    }
+    return calls;
+}
+// ── Loop detection ───────────────────────────────────────────────────────────
+export function detectLoops(calls, minOccurrences = MIN_OCCURRENCES) {
+    const groups = new Map();
+    for (const c of calls) {
+        const arr = groups.get(c.signature) ?? [];
+        arr.push(c);
+        groups.set(c.signature, arr);
+    }
+    const loops = [];
+    for (const [signature, arr] of groups) {
+        if (arr.length < minOccurrences)
+            continue;
+        const errors = arr.filter(c => c.isError);
+        if (errors.length >= minOccurrences) {
+            // Error loop: measured waste = every failed repetition's output.
+            loops.push({
+                kind: 'error',
+                signature,
+                count: errors.length,
+                wastedBytes: errors.reduce((s, c) => s + c.outputBytes, 0),
+                sampleRaw: errors[0].raw,
+                tool: errors[0].tool,
+            });
+            continue;
+        }
+        // Refetch loop: same signature, ≥2 distinct raw variants (pagination churn).
+        const distinctRaw = new Set(arr.map(c => c.raw));
+        if (distinctRaw.size >= 2) {
+            const sorted = [...arr].sort((a, b) => a.outputBytes - b.outputBytes);
+            // Redundant = all but the single legitimate fetch (the smallest).
+            const wastedBytes = sorted.slice(1).reduce((s, c) => s + c.outputBytes, 0);
+            loops.push({
+                kind: 'refetch',
+                signature,
+                count: arr.length,
+                wastedBytes,
+                sampleRaw: arr[0].raw,
+                tool: arr[0].tool,
+            });
+        }
+    }
+    return loops.sort((a, b) => b.wastedBytes - a.wastedBytes);
+}
+// ── Corrections + marker writer ──────────────────────────────────────────────
+export const LEARN_START = '<!-- squeezr:learn:start -->';
+export const LEARN_END = '<!-- squeezr:learn:end -->';
+function approxTokens(bytes) {
+    return Math.round(bytes / 4);
+}
+export function renderCorrections(loops) {
+    if (loops.length === 0)
+        return '';
+    const lines = [];
+    for (const l of loops) {
+        const tok = approxTokens(l.wastedBytes);
+        if (l.kind === 'error') {
+            lines.push(`- \`${l.sampleRaw}\` failed and was retried ${l.count}× (~${tok} tokens wasted). Fix the root cause before retrying, or don't re-run the identical failing command.`);
+        }
+        else {
+            lines.push(`- \`${l.sampleRaw}\` was re-fetched with growing pagination ${l.count}× (~${tok} tokens wasted). Ask for the full/needed range in ONE call instead of re-running with a bigger limit.`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * 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 function writeMarkerBlock(existing, rulesBody) {
+    const block = `${LEARN_START}\n## Squeezr learned rules (auto-generated — avoid these token-wasting loops)\n${rulesBody}\n${LEARN_END}`;
+    const re = new RegExp(`${LEARN_START}[\\s\\S]*?${LEARN_END}`);
+    if (re.test(existing)) {
+        return existing.replace(re, block);
+    }
+    const sep = existing.length === 0 || existing.endsWith('\n') ? '\n' : '\n\n';
+    return `${existing}${sep}${block}\n`;
+}
+function newestJsonl(dir, limit) {
+    const found = [];
+    const walk = (d) => {
+        let entries = [];
+        try {
+            entries = readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            const p = join(d, name);
+            let st;
+            try {
+                st = statSync(p);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory())
+                walk(p);
+            else if (name.endsWith('.jsonl'))
+                found.push({ path: p, mtime: st.mtimeMs });
+        }
+    };
+    walk(dir);
+    return found.sort((a, b) => b.mtime - a.mtime).slice(0, limit).map(f => f.path);
+}
+export function runLearn(opts = {}) {
+    const projectsDir = opts.projectsDir ?? join(homedir(), '.claude', 'projects');
+    const targetFile = opts.targetFile ?? join(process.cwd(), 'CLAUDE.local.md');
+    const limit = opts.maxSessions ?? 20;
+    const files = existsSync(projectsDir) ? newestJsonl(projectsDir, limit) : [];
+    const allCalls = [];
+    for (const f of files) {
+        try {
+            allCalls.push(...extractToolCalls(readFileSync(f, 'utf-8').split('\n')));
+        }
+        catch { /* skip */ }
+    }
+    const loops = detectLoops(allCalls);
+    const totalTokens = approxTokens(loops.reduce((s, l) => s + l.wastedBytes, 0));
+    const header = files.length === 0
+        ? `No Claude Code sessions found under ${projectsDir}.`
+        : `Scanned ${files.length} session(s), ${allCalls.length} tool call(s). Found ${loops.length} loop(s), ~${totalTokens} tokens wasted.`;
+    const report = loops.length ? `${header}\n\n${renderCorrections(loops)}` : header;
+    let applied = false;
+    if (opts.apply && loops.length > 0) {
+        const existing = existsSync(targetFile) ? readFileSync(targetFile, 'utf-8') : '';
+        writeFileSync(targetFile, writeMarkerBlock(existing, renderCorrections(loops)), 'utf-8');
+        applied = true;
+    }
+    return { sessionsScanned: files.length, loops, report, applied, targetFile };
+}

package/dist/outputSavings.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Output-savings signals — Squeezr's honest, no-counterfactual take on headroom's output
+ * measurement. The fully honest number (headroom's holdout A/B) needs a control arm; that
+ * is deferred. This ships the tier that needs NO counterfactual: the ECHO RATIO — how much
+ * of what the model just wrote merely restated context it was already given.
+ *
+ * High echo = wasted output tokens = exactly what verbosity steering (1.83) targets. Reading
+ * the response to measure this never changes the bytes we forward, so it's cache-safe.
+ */
+/** Word n-grams (set) of a text. */
+export declare function wordNgrams(text: string, n?: number): Set<string>;
+/**
+ * Fraction of the OUTPUT's n-grams that also appear in the CONTEXT (0..1). 1 = the model
+ * only restated what it was already shown; 0 = fully novel output.
+ */
+export declare function echoRatio(output: string, context: string, n?: number): number;
+/** Pull the assistant's text out of an Anthropic SSE stream (concatenated text_delta). */
+export declare function extractAssistantTextFromSse(sse: string): string;
+/** Assistant text from a non-streaming Anthropic response body's content blocks. */
+export declare function extractAssistantTextFromContent(content: unknown): string;

package/dist/outputSavings.js

@@ -0,0 +1,52 @@
+/**
+ * Output-savings signals — Squeezr's honest, no-counterfactual take on headroom's output
+ * measurement. The fully honest number (headroom's holdout A/B) needs a control arm; that
+ * is deferred. This ships the tier that needs NO counterfactual: the ECHO RATIO — how much
+ * of what the model just wrote merely restated context it was already given.
+ *
+ * High echo = wasted output tokens = exactly what verbosity steering (1.83) targets. Reading
+ * the response to measure this never changes the bytes we forward, so it's cache-safe.
+ */
+/** Word n-grams (set) of a text. */
+export function wordNgrams(text, n = 3) {
+    const words = text.toLowerCase().match(/[a-z0-9_]+/g) ?? [];
+    const set = new Set();
+    for (let i = 0; i + n <= words.length; i++)
+        set.add(words.slice(i, i + n).join(' '));
+    return set;
+}
+/**
+ * Fraction of the OUTPUT's n-grams that also appear in the CONTEXT (0..1). 1 = the model
+ * only restated what it was already shown; 0 = fully novel output.
+ */
+export function echoRatio(output, context, n = 3) {
+    const out = wordNgrams(output, n);
+    if (out.size === 0)
+        return 0;
+    const ctx = wordNgrams(context, n);
+    let echoed = 0;
+    for (const g of out)
+        if (ctx.has(g))
+            echoed++;
+    return echoed / out.size;
+}
+/** Pull the assistant's text out of an Anthropic SSE stream (concatenated text_delta). */
+export function extractAssistantTextFromSse(sse) {
+    let out = '';
+    for (const m of sse.matchAll(/"type":"text_delta","text":"((?:[^"\\]|\\.)*)"/g)) {
+        try {
+            out += JSON.parse(`"${m[1]}"`);
+        }
+        catch { /* skip malformed delta */ }
+    }
+    return out;
+}
+/** Assistant text from a non-streaming Anthropic response body's content blocks. */
+export function extractAssistantTextFromContent(content) {
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .filter(b => b && b.type === 'text' && typeof b.text === 'string')
+        .map(b => b.text)
+        .join('');
+}

package/dist/outputShaper.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Output-side token reduction.
+ *
+ * Everything else in Squeezr compresses what goes INTO the model. This module is
+ * the first lever on what comes OUT of it. The proxy never generates output
+ * tokens, so both levers work by RESHAPING THE REQUEST:
+ *
+ *  1. Verbosity steering — a byte-stable instruction block appended to the TAIL
+ *     of the system prompt (after any cache_control breakpoint, so the cached
+ *     prefix is never touched → Anthropic prompt cache still hits). Same append
+ *     pattern already proven safe by injectExpandDirectiveAnthropic().
+ *
+ *  2. Effort routing — agentic loops are mostly mechanical continuations (the
+ *     last message is a clean tool_result: a file read, a passing test). Thinking
+ *     bills as OUTPUT tokens (≈5× input on Opus). On mechanical turns we LOWER an
+ *     explicitly-present thinking budget / effort; on errors or new user asks we
+ *     leave it alone.
+ *
+ * Safety rules (each prevents a concrete failure mode):
+ *  - Never INJECT an effort lever the client didn't send (models without effort
+ *    support 400 on it). Only lowering an existing value is always valid.
+ *  - Never toggle thinking.type (disabling thinking while history carries thinking
+ *    blocks 400s on some models AND busts the messages cache tier).
+ *  - Steering text is byte-stable per level and applied idempotently, so repeated
+ *    requests keep an identical trailing block.
+ *
+ * Turn classification is purely STRUCTURAL (block types + is_error flags) — no
+ * content regexes, no keyword matching.
+ */
+export type TurnKind = 'mechanical' | 'new-ask' | 'error' | 'unknown';
+export type VerbosityLevel = 1 | 2 | 3 | 4;
+export interface OutputShaperSettings {
+    enabled: boolean;
+    verbositySteering: boolean;
+    level: VerbosityLevel;
+    effortRouting: boolean;
+    /** Floor to clamp an existing thinking.budget_tokens to on mechanical turns. */
+    mechanicalThinkingFloor: number;
+}
+export interface ShapeResult {
+    steered: boolean;
+    effortLowered: boolean;
+    turn: TurnKind;
+}
+export declare const STEERING_START = "<squeezr_output_shaping>";
+export declare const STEERING_END = "</squeezr_output_shaping>";
+/**
+ * Classify the latest turn structurally.
+ *   error       — the last user message carries a tool_result with is_error
+ *   new-ask     — the last user message carries real typed text (string, or a text block)
+ *   mechanical  — the last user message is only tool_result(s), none errored
+ *   unknown     — no messages, or the last message isn't a user turn
+ */
+export declare function classifyTurn(messages: unknown[]): TurnKind;
+/** Byte-stable steering block for a level, wrapped in the sentinel markers. */
+export declare function steeringText(level: VerbosityLevel): string;
+/**
+ * Append the steering block to the TAIL of the system prompt. Idempotent: any
+ * previous steering block is removed first, so re-applying the same level yields
+ * a byte-identical result and re-applying a new level replaces (never stacks).
+ * Returns true if a steering block is present after the call.
+ */
+export declare function applyVerbositySteering(body: Record<string, unknown>, level: VerbosityLevel): boolean;
+/**
+ * Lower an explicitly-present output lever. Never injects one. Two lever shapes:
+ *   - Anthropic legacy: thinking.budget_tokens  → clamp down to `floor`
+ *   - Newer: output_config.effort               → lower to MECHANICAL_EFFORT
+ * Returns true if it actually lowered something.
+ */
+export declare function routeEffort(body: Record<string, unknown>, floor: number): boolean;
+export declare function shapeRequest(body: Record<string, unknown>, settings: OutputShaperSettings): ShapeResult;

package/dist/outputShaper.js

@@ -0,0 +1,155 @@
+/**
+ * Output-side token reduction.
+ *
+ * Everything else in Squeezr compresses what goes INTO the model. This module is
+ * the first lever on what comes OUT of it. The proxy never generates output
+ * tokens, so both levers work by RESHAPING THE REQUEST:
+ *
+ *  1. Verbosity steering — a byte-stable instruction block appended to the TAIL
+ *     of the system prompt (after any cache_control breakpoint, so the cached
+ *     prefix is never touched → Anthropic prompt cache still hits). Same append
+ *     pattern already proven safe by injectExpandDirectiveAnthropic().
+ *
+ *  2. Effort routing — agentic loops are mostly mechanical continuations (the
+ *     last message is a clean tool_result: a file read, a passing test). Thinking
+ *     bills as OUTPUT tokens (≈5× input on Opus). On mechanical turns we LOWER an
+ *     explicitly-present thinking budget / effort; on errors or new user asks we
+ *     leave it alone.
+ *
+ * Safety rules (each prevents a concrete failure mode):
+ *  - Never INJECT an effort lever the client didn't send (models without effort
+ *    support 400 on it). Only lowering an existing value is always valid.
+ *  - Never toggle thinking.type (disabling thinking while history carries thinking
+ *    blocks 400s on some models AND busts the messages cache tier).
+ *  - Steering text is byte-stable per level and applied idempotently, so repeated
+ *    requests keep an identical trailing block.
+ *
+ * Turn classification is purely STRUCTURAL (block types + is_error flags) — no
+ * content regexes, no keyword matching.
+ */
+export const STEERING_START = '<squeezr_output_shaping>';
+export const STEERING_END = '</squeezr_output_shaping>';
+function blocksOf(content) {
+    return Array.isArray(content) ? content : [];
+}
+/**
+ * Classify the latest turn structurally.
+ *   error       — the last user message carries a tool_result with is_error
+ *   new-ask     — the last user message carries real typed text (string, or a text block)
+ *   mechanical  — the last user message is only tool_result(s), none errored
+ *   unknown     — no messages, or the last message isn't a user turn
+ */
+export function classifyTurn(messages) {
+    if (!Array.isArray(messages) || messages.length === 0)
+        return 'unknown';
+    const last = messages[messages.length - 1];
+    if (!last || last.role !== 'user')
+        return 'unknown';
+    if (typeof last.content === 'string') {
+        return last.content.trim().length > 0 ? 'new-ask' : 'unknown';
+    }
+    const blocks = blocksOf(last.content);
+    if (blocks.length === 0)
+        return 'unknown';
+    const hasErrorResult = blocks.some(b => b.type === 'tool_result' && !!b.is_error);
+    if (hasErrorResult)
+        return 'error';
+    const hasRealText = blocks.some(b => b.type === 'text' && typeof b.text === 'string' && b.text.trim().length > 0);
+    if (hasRealText)
+        return 'new-ask';
+    const hasToolResult = blocks.some(b => b.type === 'tool_result');
+    if (hasToolResult)
+        return 'mechanical';
+    return 'unknown';
+}
+// ── Verbosity steering ───────────────────────────────────────────────────────
+// Cumulative levels. Each string is a fixed literal → byte-stable per level,
+// which is what keeps the appended trailing block identical across requests.
+const LEVEL_RULES = {
+    1: [
+        'Skip preamble and postamble. Open with the substance, not with "Great" / "Sure" / "Let me".',
+    ],
+    2: [
+        'Skip preamble and postamble. Open with the substance, not with "Great" / "Sure" / "Let me".',
+        'Do not restate code, file contents, or tool output already visible in this conversation — reference it by path:line instead of reprinting it.',
+        'After a tool call succeeds, do not narrate what it did unless it changes the plan.',
+    ],
+    3: [
+        'Skip preamble and postamble. Open with the substance, not with "Great" / "Sure" / "Let me".',
+        'Do not restate code, file contents, or tool output already visible in this conversation — reference it by path:line instead of reprinting it.',
+        'After a tool call succeeds, do not narrate what it did unless it changes the plan.',
+        'Give conclusions, not step-by-step narration of routine work. Prefer the smallest edit over a full rewrite.',
+    ],
+    4: [
+        'Answer in the minimum number of tokens. Fragments over full sentences. No rationale unless explicitly asked. No restated context.',
+    ],
+};
+/** Byte-stable steering block for a level, wrapped in the sentinel markers. */
+export function steeringText(level) {
+    const rules = LEVEL_RULES[level] ?? LEVEL_RULES[2];
+    const body = rules.map(r => `- ${r}`).join('\n');
+    return `${STEERING_START}\nBe terse. Output tokens are expensive.\n${body}\n${STEERING_END}`;
+}
+function stripSteeringString(s) {
+    const re = new RegExp(`\\n*${STEERING_START}[\\s\\S]*?${STEERING_END}`, 'g');
+    return s.replace(re, '');
+}
+/**
+ * Append the steering block to the TAIL of the system prompt. Idempotent: any
+ * previous steering block is removed first, so re-applying the same level yields
+ * a byte-identical result and re-applying a new level replaces (never stacks).
+ * Returns true if a steering block is present after the call.
+ */
+export function applyVerbositySteering(body, level) {
+    const block = steeringText(level);
+    const sys = body.system;
+    if (typeof sys === 'string') {
+        body.system = `${stripSteeringString(sys)}\n\n${block}`;
+        return true;
+    }
+    if (Array.isArray(sys)) {
+        const arr = sys.filter(b => !(typeof b.text === 'string' && b.text.includes(STEERING_START)));
+        arr.push({ type: 'text', text: block });
+        body.system = arr;
+        return true;
+    }
+    // No system prompt at all (rare): create one carrying only the steering block.
+    body.system = block;
+    return true;
+}
+// ── Effort routing ───────────────────────────────────────────────────────────
+const EFFORT_RANK = { minimal: 0, low: 1, medium: 2, high: 3, xhigh: 4 };
+const MECHANICAL_EFFORT = 'low';
+/**
+ * Lower an explicitly-present output lever. Never injects one. Two lever shapes:
+ *   - Anthropic legacy: thinking.budget_tokens  → clamp down to `floor`
+ *   - Newer: output_config.effort               → lower to MECHANICAL_EFFORT
+ * Returns true if it actually lowered something.
+ */
+export function routeEffort(body, floor) {
+    let lowered = false;
+    const thinking = body.thinking;
+    if (thinking && typeof thinking.budget_tokens === 'number' && thinking.budget_tokens > floor) {
+        thinking.budget_tokens = floor;
+        lowered = true;
+    }
+    const oc = body.output_config;
+    if (oc && typeof oc.effort === 'string') {
+        const cur = EFFORT_RANK[oc.effort.toLowerCase()];
+        const target = EFFORT_RANK[MECHANICAL_EFFORT];
+        if (cur !== undefined && cur > target) {
+            oc.effort = MECHANICAL_EFFORT;
+            lowered = true;
+        }
+    }
+    return lowered;
+}
+// ── Orchestration ────────────────────────────────────────────────────────────
+export function shapeRequest(body, settings) {
+    if (!settings.enabled)
+        return { steered: false, effortLowered: false, turn: 'unknown' };
+    const turn = classifyTurn(body.messages ?? []);
+    const steered = settings.verbositySteering ? applyVerbositySteering(body, settings.level) : false;
+    const effortLowered = settings.effortRouting && turn === 'mechanical' ? routeEffort(body, settings.mechanicalThinkingFloor) : false;
+    return { steered, effortLowered, turn };
+}

package/dist/relevance.d.ts

@@ -0,0 +1,27 @@
+/**
+ * BM25 relevance scorer — a shared primitive so Squeezr's compressors can keep content
+ * by RELEVANCE to the current task, not just by position (head/tail) or recency.
+ *
+ * This is the single highest-leverage idea copied from headroom: their SmartCrusher,
+ * TextCrusher and CodeCompressor all route "what to keep" through one relevance scorer.
+ * Squeezr, until now, kept blindly. This module is that scorer — pure TS, zero deps,
+ * deterministic (→ cache-safe when used to drive byte-stable compression).
+ *
+ * BM25 (Okapi) is the standard, well-understood ranking function: term frequency with
+ * saturation (k1) and document-length normalization (b), weighted by inverse document
+ * frequency so rare query terms (an error code, a filename) count far more than common
+ * words. The idf uses +0.5 smoothing so it is always positive.
+ */
+export interface BM25Options {
+    k1?: number;
+    b?: number;
+}
+/** Lowercase, split on non-alphanumerics, keep tokens of length >= 2. */
+export declare function tokenize(text: string): string[];
+/**
+ * BM25 score of each doc in `docs` against `query`. One score per doc, in order.
+ * A doc with no query-term overlap scores exactly 0.
+ */
+export declare function bm25Scores(query: string, docs: string[], opts?: BM25Options): number[];
+/** Document indices sorted by descending relevance (ties keep original order). */
+export declare function rankByRelevance(query: string, docs: string[], opts?: BM25Options): number[];

package/dist/relevance.js

@@ -0,0 +1,78 @@
+/**
+ * BM25 relevance scorer — a shared primitive so Squeezr's compressors can keep content
+ * by RELEVANCE to the current task, not just by position (head/tail) or recency.
+ *
+ * This is the single highest-leverage idea copied from headroom: their SmartCrusher,
+ * TextCrusher and CodeCompressor all route "what to keep" through one relevance scorer.
+ * Squeezr, until now, kept blindly. This module is that scorer — pure TS, zero deps,
+ * deterministic (→ cache-safe when used to drive byte-stable compression).
+ *
+ * BM25 (Okapi) is the standard, well-understood ranking function: term frequency with
+ * saturation (k1) and document-length normalization (b), weighted by inverse document
+ * frequency so rare query terms (an error code, a filename) count far more than common
+ * words. The idf uses +0.5 smoothing so it is always positive.
+ */
+const DEFAULT_K1 = 1.5;
+const DEFAULT_B = 0.75;
+/** Lowercase, split on non-alphanumerics, keep tokens of length >= 2. */
+export function tokenize(text) {
+    const out = [];
+    for (const m of text.toLowerCase().matchAll(/[a-z0-9_]+/g)) {
+        if (m[0].length >= 2)
+            out.push(m[0]);
+    }
+    return out;
+}
+/**
+ * BM25 score of each doc in `docs` against `query`. One score per doc, in order.
+ * A doc with no query-term overlap scores exactly 0.
+ */
+export function bm25Scores(query, docs, opts = {}) {
+    const k1 = opts.k1 ?? DEFAULT_K1;
+    const b = opts.b ?? DEFAULT_B;
+    const queryTerms = [...new Set(tokenize(query))];
+    const N = docs.length;
+    if (queryTerms.length === 0 || N === 0)
+        return new Array(N).fill(0);
+    // Tokenize docs once; compute lengths and average length.
+    const docTokens = docs.map(tokenize);
+    const docLen = docTokens.map(t => t.length);
+    const avgdl = docLen.reduce((s, l) => s + l, 0) / N || 1;
+    // Per-doc term-frequency maps.
+    const tf = docTokens.map(tokens => {
+        const m = new Map();
+        for (const t of tokens)
+            m.set(t, (m.get(t) ?? 0) + 1);
+        return m;
+    });
+    // Document frequency + idf per query term.
+    const idf = new Map();
+    for (const term of queryTerms) {
+        let df = 0;
+        for (const m of tf)
+            if (m.has(term))
+                df++;
+        // Always-positive smoothed idf.
+        idf.set(term, Math.log(1 + (N - df + 0.5) / (df + 0.5)));
+    }
+    return docTokens.map((_, i) => {
+        let score = 0;
+        const len = docLen[i];
+        for (const term of queryTerms) {
+            const f = tf[i].get(term) ?? 0;
+            if (f === 0)
+                continue;
+            const denom = f + k1 * (1 - b + (b * len) / avgdl);
+            score += (idf.get(term) ?? 0) * ((f * (k1 + 1)) / denom);
+        }
+        return score;
+    });
+}
+/** Document indices sorted by descending relevance (ties keep original order). */
+export function rankByRelevance(query, docs, opts) {
+    const scores = bm25Scores(query, docs, opts);
+    return scores
+        .map((score, i) => ({ score, i }))
+        .sort((a, b) => (b.score - a.score) || (a.i - b.i))
+        .map(x => x.i);
+}