context-compress 2026.5.0 → 2026.7.0

package/dist/util/html-to-markdown.js

@@ -0,0 +1,66 @@
+/**
+ * Single source of truth for the HTML→markdown conversion snippet.
+ *
+ * Returns a dependency-free JS snippet that assumes a `html` string variable is
+ * already in scope, converts it to markdown, and `console.log`s the result.
+ * Shared by the fetch tool (which runs it inside the sandbox subprocess) and its
+ * tests, so the two copies can never drift.
+ *
+ * NOTE: This is a regex pipeline, not a full HTML parser — a real parser cannot
+ * be used because the snippet must run in the dependency-free sandbox. To bound
+ * worst-case backtracking, callers MUST size-limit `html` before running this
+ * (see `buildFetchCode`, which caps at 10MB). All patterns use bounded character
+ * classes (`[^>]`, `[^"]`) or lazy quantifiers separated by required literals,
+ * so none exhibit catastrophic (exponential) backtracking.
+ */
+export function htmlToMarkdownSnippet() {
+    return `
+// Strip unwanted tags
+let md = html
+  .replace(/<script[^>]*>[\\s\\S]*?<\\/script>/gi, "")
+  .replace(/<style[^>]*>[\\s\\S]*?<\\/style>/gi, "")
+  .replace(/<nav[^>]*>[\\s\\S]*?<\\/nav>/gi, "")
+  .replace(/<header[^>]*>[\\s\\S]*?<\\/header>/gi, "")
+  .replace(/<footer[^>]*>[\\s\\S]*?<\\/footer>/gi, "");
+
+// Convert headings
+md = md.replace(/<h1[^>]*>(.*?)<\\/h1>/gi, "# $1\\n");
+md = md.replace(/<h2[^>]*>(.*?)<\\/h2>/gi, "## $1\\n");
+md = md.replace(/<h3[^>]*>(.*?)<\\/h3>/gi, "### $1\\n");
+md = md.replace(/<h4[^>]*>(.*?)<\\/h4>/gi, "#### $1\\n");
+
+// Convert code blocks
+md = md.replace(/<pre[^>]*><code[^>]*>(.*?)<\\/code><\\/pre>/gis, "\`\`\`\\n$1\\n\`\`\`\\n");
+md = md.replace(/<code[^>]*>(.*?)<\\/code>/gi, "\`$1\`");
+
+// Convert links
+md = md.replace(/<a[^>]*href="([^"]*)"[^>]*>(.*?)<\\/a>/gi, "[$2]($1)");
+
+// Convert lists
+md = md.replace(/<li[^>]*>(.*?)<\\/li>/gi, "- $1\\n");
+
+// Convert paragraphs
+md = md.replace(/<p[^>]*>(.*?)<\\/p>/gis, "$1\\n\\n");
+md = md.replace(/<br\\s*\\/?>/gi, "\\n");
+
+// Strip remaining tags
+md = md.replace(/<[^>]+>/g, "");
+
+// Decode entities (&amp; LAST so we don't double-decode)
+md = md.replace(/&lt;/g, "<")
+  .replace(/&gt;/g, ">")
+  .replace(/&quot;/g, '"')
+  .replace(/&#39;/g, "'")
+  .replace(/&apos;/g, "'")
+  .replace(/&nbsp;/g, " ")
+  .replace(/&#(\\d+);/g, (_, n) => { const c = parseInt(n, 10); return c > 0 && c <= 0x10FFFF ? String.fromCodePoint(c) : ''; })
+  .replace(/&#x([0-9a-fA-F]+);/g, (_, h) => { const c = parseInt(h, 16); return c > 0 && c <= 0x10FFFF ? String.fromCodePoint(c) : ''; })
+  .replace(/&amp;/g, "&");
+
+// Clean whitespace
+md = md.replace(/\\n{3,}/g, "\\n\\n").trim();
+
+console.log(md);
+`;
+}
+//# sourceMappingURL=html-to-markdown.js.map

package/dist/util/html-to-markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"html-to-markdown.js","sourceRoot":"","sources":["../../src/util/html-to-markdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,qBAAqB;IACpC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+CP,CAAC;AACF,CAAC"}

package/dist/util/intent-filter.d.ts

@@ -7,9 +7,18 @@ interface IntentFilterDeps {
     tracker: SessionTracker;
 }
 /**
- * Index large output and return a compact summary keyed to `intent`.
- * For small output (<= config.intentSearchThreshold bytes), returns the
- * original output unchanged so callers don't pay for trivial filtering.
+ * Index large output and return a compact, *query-conditioned* summary keyed to
+ * `intent`. For small output (<= config.intentSearchThreshold bytes), returns
+ * the original output unchanged so callers don't pay for trivial filtering.
+ *
+ * Unlike a fixed-mode filter, this is variable-rate and query-aware (cf.
+ * ACC-RAG / AttnComp): the retrieval layer already produces query-focused
+ * excerpts, so instead of throwing them away and forcing a follow-up search()
+ * round-trip, we inline the top-ranked content up to `config.intentBudgetBytes`.
+ * Best-scoring sections get the most room; each is capped so one section can't
+ * crowd out the rest. Error/warning lines are always surfaced verbatim — they're
+ * usually the whole reason an intent was specified — so a summary never silently
+ * drops the one line the agent needed.
  */
 export declare function createIntentFilter(deps: IntentFilterDeps): (output: string, intent: string, sourceLabel: string) => string;
 export type ApplyIntentFilter = ReturnType<typeof createIntentFilter>;

package/dist/util/intent-filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intent-filter.d.ts","sourceRoot":"","sources":["../../src/util/intent-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,UAAU,gBAAgB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,cAAc,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,IAGtB,QAAQ,MAAM,EAAE,QAAQ,MAAM,EAAE,aAAa,MAAM,KAAG,MAAM,CAoB9F;AAED,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC"}
+{"version":3,"file":"intent-filter.d.ts","sourceRoot":"","sources":["../../src/util/intent-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,UAAU,gBAAgB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,cAAc,CAAC;CACxB;AASD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,IAGtB,QAAQ,MAAM,EAAE,QAAQ,MAAM,EAAE,aAAa,MAAM,KAAG,MAAM,CA0B9F;AAmCD,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/util/intent-filter.js

@@ -1,22 +1,43 @@
+import { extractErrorLines } from "../format-filter.js";
 import { compactLabel } from "./label.js";
+/** How many matching sections to consider (before the byte budget trims them). */
+const INTENT_SEARCH_LIMIT = 6;
+/** No single hit may consume more than this share of the budget. */
+const PER_HIT_CAP = 700;
+/** Minimum snippet bytes worth showing for a hit. */
+const PER_HIT_FLOOR = 120;
 /**
- * Index large output and return a compact summary keyed to `intent`.
- * For small output (<= config.intentSearchThreshold bytes), returns the
- * original output unchanged so callers don't pay for trivial filtering.
+ * Index large output and return a compact, *query-conditioned* summary keyed to
+ * `intent`. For small output (<= config.intentSearchThreshold bytes), returns
+ * the original output unchanged so callers don't pay for trivial filtering.
+ *
+ * Unlike a fixed-mode filter, this is variable-rate and query-aware (cf.
+ * ACC-RAG / AttnComp): the retrieval layer already produces query-focused
+ * excerpts, so instead of throwing them away and forcing a follow-up search()
+ * round-trip, we inline the top-ranked content up to `config.intentBudgetBytes`.
+ * Best-scoring sections get the most room; each is capped so one section can't
+ * crowd out the rest. Error/warning lines are always surfaced verbatim — they're
+ * usually the whole reason an intent was specified — so a summary never silently
+ * drops the one line the agent needed.
  */
 export function createIntentFilter(deps) {
     const { config, store, tracker } = deps;
     return function applyIntentFilter(output, intent, sourceLabel) {
-        if (Buffer.byteLength(output) <= config.intentSearchThreshold)
+        const outputBytes = Buffer.byteLength(output);
+        if (outputBytes <= config.intentSearchThreshold)
             return output;
         const indexed = store.index(output, sourceLabel);
-        tracker.trackIndexed(Buffer.byteLength(output));
-        const searchResults = store.search(intent, { limit: 3 });
+        tracker.trackIndexed(outputBytes);
+        const searchResults = store.search(intent, { limit: INTENT_SEARCH_LIMIT });
         const terms = store.getDistinctiveTerms(indexed.sourceId);
+        const errorLines = extractErrorLines(output);
         let filtered = `Indexed ${indexed.totalChunks} sections from ${sourceLabel}.\n`;
         filtered += `${searchResults.results.length} sections matched "${intent}":\n\n`;
-        for (const hit of searchResults.results) {
-            filtered += `  - **${hit.title}**: ${hit.snippet.slice(0, 200)}\n`;
+        filtered += renderHits(searchResults.results, config.intentBudgetBytes);
+        if (errorLines.length > 0) {
+            filtered += `\n⚠ ${errorLines.length} error/warning line(s) in output:\n`;
+            filtered += errorLines.map((l) => `  ${l}`).join("\n");
+            filtered += "\n";
         }
         if (terms.length > 0 && config.compressionLevel !== "ultra") {
             filtered += `\nSearchable terms: ${terms.join(", ")}\n`;
@@ -25,4 +46,36 @@ export function createIntentFilter(deps) {
         return compactLabel(filtered, config.compressionLevel);
     };
 }
+/**
+ * Render hits within a byte budget. Hits arrive best-first; each gets an even
+ * share of the remaining budget (capped and floored), and any unspent bytes
+ * roll forward to later hits. A hit skipped for lack of budget is still listed
+ * by title so the agent knows it exists and can search() for it.
+ */
+function renderHits(hits, budget) {
+    if (hits.length === 0)
+        return "  (no matching sections — try search() with different terms)\n";
+    const lines = [];
+    let remaining = budget;
+    for (let i = 0; i < hits.length; i++) {
+        const hit = hits[i];
+        const hitsLeft = hits.length - i;
+        const share = Math.min(PER_HIT_CAP, Math.floor(remaining / hitsLeft));
+        if (share < PER_HIT_FLOOR) {
+            lines.push(`  - **${hit.title}** (search to view)`);
+            continue;
+        }
+        const snippet = clip(hit.snippet.trim(), share);
+        remaining -= Buffer.byteLength(snippet);
+        lines.push(`  - **${hit.title}**: ${snippet}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Trim a snippet to at most `max` bytes, marking truncation. */
+function clip(s, max) {
+    if (Buffer.byteLength(s) <= max)
+        return s;
+    // Slice on characters; good enough for mostly-ASCII tool output.
+    return `${s.slice(0, Math.max(0, max - 1))}…`;
+}
 //# sourceMappingURL=intent-filter.js.map

package/dist/util/intent-filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"intent-filter.js","sourceRoot":"","sources":["../../src/util/intent-filter.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAQ1C;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAsB;IACxD,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAExC,OAAO,SAAS,iBAAiB,CAAC,MAAc,EAAE,MAAc,EAAE,WAAmB;QACpF,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,qBAAqB;YAAE,OAAO,MAAM,CAAC;QAE7E,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QACjD,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;QAEhD,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;QACzD,MAAM,KAAK,GAAG,KAAK,CAAC,mBAAmB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAE1D,IAAI,QAAQ,GAAG,WAAW,OAAO,CAAC,WAAW,kBAAkB,WAAW,KAAK,CAAC;QAChF,QAAQ,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,MAAM,sBAAsB,MAAM,QAAQ,CAAC;QAChF,KAAK,MAAM,GAAG,IAAI,aAAa,CAAC,OAAO,EAAE,CAAC;YACzC,QAAQ,IAAI,SAAS,GAAG,CAAC,KAAK,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC;QACpE,CAAC;QACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,gBAAgB,KAAK,OAAO,EAAE,CAAC;YAC7D,QAAQ,IAAI,uBAAuB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;QACzD,CAAC;QACD,QAAQ,IAAI,uEAAuE,CAAC;QACpF,OAAO,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACxD,CAAC,CAAC;AACH,CAAC"}
+{"version":3,"file":"intent-filter.js","sourceRoot":"","sources":["../../src/util/intent-filter.ts"],"names":[],"mappings":"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"}

package/dist/util/regret.d.ts

@@ -0,0 +1,54 @@
+/**
+ * ACON-style self-improving compression policy.
+ *
+ * ACON (Kang et al., 2026) optimizes a compression *guideline* in natural-language
+ * space by analyzing cases where the full context succeeds but the compressed
+ * context fails, then refines the guideline — no model fine-tuning. We can't run
+ * paired trajectories at runtime, but we can approximate the failure signal from
+ * the agent's own behavior: if a command is compressed aggressively and then
+ * *re-run almost immediately*, the aggressive summary probably hid something the
+ * agent needed. That's a "compression regret".
+ *
+ * The policy this drives is deliberately narrow and safe:
+ *   - We only count a regret for a FAST re-run (default ≤ 30s) that followed an
+ *     AGGRESSIVE compression. Balanced/conservative are never blamed — they
+ *     rarely drop task-critical data, and normal edit→rerun loops (which are
+ *     slower and usually ran under balanced) shouldn't be misread as regret.
+ *   - The only adjustment is a one-step DOWNGRADE (aggressive → balanced) once a
+ *     fingerprint's regret rate is high over enough samples. Downgrading only
+ *     ever *reduces* compression, so a false positive costs a few tokens, never
+ *     correctness. It never makes anything more aggressive on its own.
+ *
+ * State is a small JSON map at ~/.context-compress/regret.json, keyed by the same
+ * command fingerprint the auto-mode cache uses, so it persists across sessions.
+ */
+import type { FilterMode } from "../filters.js";
+export interface RegretOptions {
+    path?: string;
+    /** Injectable clock (epoch ms) for deterministic tests. */
+    now?: number;
+    /** Re-run window in ms; a re-run within this counts toward regret. */
+    windowMs?: number;
+}
+export interface RegretDecision {
+    /** Mode after any regret-driven adjustment. */
+    mode: FilterMode;
+    /** True when the chosen mode was downgraded due to regret. */
+    adjusted: boolean;
+    /** Current regret rate for this fingerprint (0–1). */
+    regretRate: number;
+}
+/**
+ * Record this compression decision, detect regret from a fast re-run, and return
+ * a possibly-downgraded mode. Call this once per auto-mode decision (including
+ * cache hits) so the re-run timeline stays accurate.
+ */
+export declare function observeAndAdjust(fingerprint: string, chosenMode: FilterMode, opts?: RegretOptions): RegretDecision;
+/** Read-only view of regret stats, for the `stats` tool / observability. */
+export declare function regretSummary(opts?: RegretOptions): Array<{
+    fingerprint: string;
+    observations: number;
+    regrets: number;
+    regretRate: number;
+}>;
+//# sourceMappingURL=regret.d.ts.map

package/dist/util/regret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regret.d.ts","sourceRoot":"","sources":["../../src/util/regret.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAyBhD,MAAM,WAAW,aAAa;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC9B,+CAA+C;IAC/C,IAAI,EAAE,UAAU,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;CACnB;AA0BD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC/B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,UAAU,EACtB,IAAI,GAAE,aAAkB,GACtB,cAAc,CA8BhB;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,KAAK,CAAC;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACnB,CAAC,CAWD"}

package/dist/util/regret.js

@@ -0,0 +1,107 @@
+/**
+ * ACON-style self-improving compression policy.
+ *
+ * ACON (Kang et al., 2026) optimizes a compression *guideline* in natural-language
+ * space by analyzing cases where the full context succeeds but the compressed
+ * context fails, then refines the guideline — no model fine-tuning. We can't run
+ * paired trajectories at runtime, but we can approximate the failure signal from
+ * the agent's own behavior: if a command is compressed aggressively and then
+ * *re-run almost immediately*, the aggressive summary probably hid something the
+ * agent needed. That's a "compression regret".
+ *
+ * The policy this drives is deliberately narrow and safe:
+ *   - We only count a regret for a FAST re-run (default ≤ 30s) that followed an
+ *     AGGRESSIVE compression. Balanced/conservative are never blamed — they
+ *     rarely drop task-critical data, and normal edit→rerun loops (which are
+ *     slower and usually ran under balanced) shouldn't be misread as regret.
+ *   - The only adjustment is a one-step DOWNGRADE (aggressive → balanced) once a
+ *     fingerprint's regret rate is high over enough samples. Downgrading only
+ *     ever *reduces* compression, so a false positive costs a few tokens, never
+ *     correctness. It never makes anything more aggressive on its own.
+ *
+ * State is a small JSON map at ~/.context-compress/regret.json, keyed by the same
+ * command fingerprint the auto-mode cache uses, so it persists across sessions.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+const DEFAULT_PATH = join(homedir(), ".context-compress", "regret.json");
+const RERUN_WINDOW_MS = 30_000;
+/**
+ * Absolute number of aggressive-mode fast re-runs before we downgrade. Using a
+ * count (not a decaying rate) gives hysteresis: once a fingerprint has proven
+ * aggressive is a bad fit, it stays downgraded instead of oscillating back the
+ * moment the re-runs stop (they stop *because* we downgraded).
+ */
+const REGRET_MIN_COUNT = 3;
+function load(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function save(path, map) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(map, null, 2));
+    }
+    catch {
+        /* best-effort */
+    }
+}
+function downgrade(mode) {
+    if (mode === "aggressive")
+        return "balanced";
+    if (mode === "balanced")
+        return "conservative";
+    return "conservative";
+}
+/**
+ * Record this compression decision, detect regret from a fast re-run, and return
+ * a possibly-downgraded mode. Call this once per auto-mode decision (including
+ * cache hits) so the re-run timeline stays accurate.
+ */
+export function observeAndAdjust(fingerprint, chosenMode, opts = {}) {
+    const path = opts.path ?? DEFAULT_PATH;
+    const now = opts.now ?? Date.now();
+    const window = opts.windowMs ?? RERUN_WINDOW_MS;
+    const map = load(path);
+    const rec = map[fingerprint] ?? {
+        lastMode: chosenMode,
+        lastSeen: 0,
+        observations: 0,
+        regrets: 0,
+    };
+    // A fast re-run after an aggressive compression is our regret signal.
+    const isFastRerun = rec.lastSeen > 0 && now - rec.lastSeen <= window;
+    if (isFastRerun && rec.lastMode === "aggressive") {
+        rec.regrets++;
+    }
+    rec.observations++;
+    const regretRate = rec.observations > 0 ? rec.regrets / rec.observations : 0;
+    const shouldAdjust = chosenMode === "aggressive" && rec.regrets >= REGRET_MIN_COUNT;
+    const mode = shouldAdjust ? downgrade(chosenMode) : chosenMode;
+    rec.lastMode = mode;
+    rec.lastSeen = now;
+    map[fingerprint] = rec;
+    save(path, map);
+    return { mode, adjusted: mode !== chosenMode, regretRate };
+}
+/** Read-only view of regret stats, for the `stats` tool / observability. */
+export function regretSummary(opts = {}) {
+    const map = load(opts.path ?? DEFAULT_PATH);
+    return Object.entries(map)
+        .map(([fingerprint, r]) => ({
+        fingerprint,
+        observations: r.observations,
+        regrets: r.regrets,
+        regretRate: r.observations > 0 ? r.regrets / r.observations : 0,
+    }))
+        .filter((r) => r.regrets > 0)
+        .sort((a, b) => b.regretRate - a.regretRate);
+}
+//# sourceMappingURL=regret.js.map

package/dist/util/regret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"regret.js","sourceRoot":"","sources":["../../src/util/regret.ts"],"names":[],"mappings":"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"}

package/docs/agentic-benchmark.md

@@ -0,0 +1,110 @@
+# Agentic Benchmark Plan
+
+This benchmark measures context-compress in real agent sessions, not synthetic command output alone.
+
+The claim to test:
+
+> Large tool output should stay searchable outside the conversation, while the agent still solves the same task with less context pressure.
+
+## Why This Exists
+
+`docs/token-reduction-report.md` measures byte and token reduction for common operations. That is necessary, but it does not fully answer whether an agent remains effective across a real coding task.
+
+This benchmark adds the missing layer: run the same task with and without context-compress, isolate each arm, and compare context usage, task success, cost, and time.
+
+## Arms
+
+| Arm | Setup | Purpose |
+| --- | --- | --- |
+| `baseline` | No context-compress MCP, no hook | Measures normal agent behavior. |
+| `mcp-only` | MCP server registered, no PreToolUse hook | Measures explicit tool adoption. |
+| `hook-balanced` | MCP plus PreToolUse hook, `CONTEXT_COMPRESS_MODE=balanced` | Default recommended setup. |
+| `hook-aggressive` | MCP plus PreToolUse hook, `CONTEXT_COMPRESS_MODE=aggressive` | Maximum compression trade-off. |
+
+Each arm must run in a fresh workspace with isolated agent settings. Do not allow global plugins, global MCP servers, or previous conversation state to leak into the run.
+
+## Task Set
+
+Use tasks that naturally produce large outputs:
+
+1. Diagnose a failing test suite and patch the root cause.
+2. Review a multi-commit diff and summarize risky changes.
+3. Inspect a large API response and implement one missing field mapping.
+4. Analyze a generated Playwright snapshot and fix one selector bug.
+5. Audit dependency output and identify one vulnerable or outdated package.
+6. Search a large log file and explain the first recurring failure.
+
+Pin every input repository and fixture by commit hash. Preserve every run directory so metrics can be recomputed.
+
+## Metrics
+
+| Metric | How to collect |
+| --- | --- |
+| Context bytes returned by tools | Sum raw tool payloads in agent logs. |
+| Compressed bytes returned | Sum context-compress tool responses. |
+| Indexed bytes | Use `stats` output and session DB stats. |
+| Task success | Deterministic test, assertion, or scorer per task. |
+| Cost/time | Agent runner JSON output when available. |
+| Follow-up retrieval quality | Count whether the final answer cites indexed/search results when needed. |
+
+Report raw numbers and relative deltas. Do not only report the best percentage.
+
+## Isolation Rules
+
+- Use a new temp workspace for every `(task, arm, run)` cell.
+- Disable user/global plugin sources for the baseline arm.
+- Install exactly the intended plugin or MCP config for non-baseline arms.
+- Clear persistent context-compress DBs between runs unless the task explicitly tests persistence.
+- Keep model, prompt, timeout, and working tree identical across arms.
+- Record the exact agent version, model, OS, Node version, and context-compress version.
+
+## Safety Checks
+
+Compression must not hide important failures. Every task needs one deterministic scorer:
+
+- tests pass after the agent patch,
+- expected files changed and unrelated files did not,
+- security-relevant details are still retrievable with `search`,
+- final answer includes the actual root cause, not just a compressed summary.
+
+If an arm uses fewer tokens but fails the scorer, mark it as a failure, not a win.
+
+## Reporting Template
+
+```md
+# Agentic benchmark: context-compress on real coding tasks
+
+Date:
+Agent:
+Model:
+context-compress:
+Repo/fixture commits:
+
+## Summary
+
+| Arm | Success | Tool bytes in context | Indexed bytes | Cost | Time |
+| --- | ---: | ---: | ---: | ---: | ---: |
+
+## Per-task Results
+
+| Task | Arm | Success | Tool bytes | Indexed bytes | Notes |
+| --- | --- | ---: | ---: | ---: | --- |
+
+## Failures And Limits
+
+- What failed:
+- What this benchmark does not prove:
+- Known nondeterminism:
+```
+
+## Reproduce
+
+Until this harness is automated, run the benchmark manually with:
+
+```bash
+npm run build
+context-compress setup --auto
+CONTEXT_COMPRESS_MODE=balanced context-compress doctor
+```
+
+Then run each task in isolated agent settings and attach the resulting logs plus `context-compress stats` output to the benchmark result.

package/docs/quality-regression-report.md

@@ -0,0 +1,20 @@
+<!-- Generated by `npm run bench:quality` — do not edit by hand. -->
+
+# Quality-Regression Benchmark
+
+| Case | Mode | Reduction | Survival | Valid JSON |
+|------|------|-----------|----------|------------|
+| pretty-json (unrecognized cmd) | conservative | 0% | 100% | — |
+| pretty-json (unrecognized cmd) | balanced | 37% | 100% | ✓ |
+| pretty-json (unrecognized cmd) | aggressive | 96% | 100% | — |
+| ndjson stream | conservative | 0% | 100% | — |
+| ndjson stream | balanced | 93% | 100% | — |
+| ndjson stream | aggressive | 93% | 100% | — |
+| app logs with an error | conservative | 0% | 100% | — |
+| app logs with an error | balanced | 98% | 100% | — |
+| app logs with an error | aggressive | 98% | 100% | — |
+| git log | conservative | 0% | 100% | — |
+| git log | balanced | 0% | 100% | — |
+| git log | aggressive | 59% | 100% | — |
+
+_Reduction = bytes removed. Survival = fraction of task-critical substrings still present after compression. Valid JSON = balanced-mode output still parses._

package/hooks/claude-codex-hooks.json

@@ -0,0 +1,19 @@
+{
+  "description": "context-compress PreToolUse hooks for Claude-compatible plugin hosts",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Read|Grep|WebFetch|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "command -v node >/dev/null 2>&1 && CONTEXT_COMPRESS_FILTER_BASH=1 CONTEXT_COMPRESS_BIN=\"node ${CLAUDE_PLUGIN_ROOT}/dist/cli/index.js\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse.mjs\" || exit 0",
+            "commandWindows": "if (Get-Command node -ErrorAction SilentlyContinue) { $env:CONTEXT_COMPRESS_FILTER_BASH='1'; $env:CONTEXT_COMPRESS_BIN='context-compress'; node \"$env:CLAUDE_PLUGIN_ROOT\\hooks\\pretooluse.mjs\" }",
+            "timeout": 5,
+            "statusMessage": "Protecting context window..."
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-compress",
-  "version": "2026.5.0",
+  "version": "2026.7.0",
   "description": "Context-aware MCP server that compresses tool output for Claude Code",
   "type": "module",
   "main": "dist/server.js",
@@ -17,6 +17,7 @@
     "test": "node --import tsx --test tests/**/*.test.ts",
     "test:unit": "node --import tsx --test tests/unit/*.test.ts",
     "test:integration": "node --import tsx --test tests/integration/*.test.ts",
+    "bench:quality": "tsx src/bench/run.ts",
     "clean": "rm -rf dist dist-bin",
     "build:bin": "bun build --compile --target=bun-darwin-arm64 ./src/cli/lite.ts --outfile=./dist-bin/cc-lite-darwin-arm64 && bun build --compile --target=bun-darwin-x64 ./src/cli/lite.ts --outfile=./dist-bin/cc-lite-darwin-x64 && bun build --compile --target=bun-linux-x64 ./src/cli/lite.ts --outfile=./dist-bin/cc-lite-linux-x64 && bun build --compile --target=bun-linux-arm64 ./src/cli/lite.ts --outfile=./dist-bin/cc-lite-linux-arm64",
     "prepublishOnly": "npm run lint && npm run test && npm run build"
@@ -38,6 +39,9 @@
     "typescript": "^5.7.0"
   },
   "files": [
+    ".codex-plugin/",
+    ".claude-plugin/",
+    ".mcp.json",
     "dist/",
     "docs/",
     "hooks/",
@@ -46,10 +50,10 @@
     "README.md"
   ],
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Open330/context-compress"
-  },
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Open330/context-compress.git"
+	},
   "keywords": [
     "mcp",
     "claude",

package/skills/context-compress-audit/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: context-compress-audit
+description: Audit a repository, plugin setup, or agent session for raw Bash, Read, WebFetch, and MCP outputs that should be routed through context-compress instead. Use when asked to find context waste, raw tool output waste, missing plugin routing, or places where large command/file/web output still enters the agent context window.
+---
+
+# Context-Compress Audit
+
+Find places where large raw output can still enter the agent context window.
+
+## Procedure
+
+1. Run `mcp__context-compress__stats` first if the tool is available.
+2. Inspect setup surfaces that control routing:
+   - `.codex-plugin/plugin.json`
+   - `.claude-plugin/plugin.json`
+   - `.mcp.json`
+   - `hooks/`
+   - `skills/`
+   - README install instructions
+3. Search for risky guidance or examples that encourage raw output:
+   - `Bash` for tests, logs, `git log`, `git diff`, `curl`, `kubectl`, `docker`, `npm test`
+   - `Read` for large logs, bundled files, snapshots, CSV/JSON dumps
+   - `WebFetch` for documentation pages that should use `fetch_and_index`
+   - Playwright snapshots without a file/index/search path
+4. Report only actionable findings. Prefer one-line fixes that route work through:
+   - `batch_execute` for several commands plus searches
+   - `execute` for command/API output that must be analyzed first
+   - `execute_file` for large local files
+   - `fetch_and_index` plus `search` for web documentation
+
+## Output
+
+Use this format:
+
+```md
+## Context-Compress Audit
+
+- [severity] file:line - raw-output risk. Replace with <tool/workflow>.
+- [severity] file:line - missing install/routing coverage. Add <specific fix>.
+
+Summary: <N> findings, estimated impact <low|medium|high>.
+```
+
+Severity:
+- `high`: large output can enter context by default.
+- `medium`: docs/examples teach a wasteful path.
+- `low`: minor wording, missing cross-link, or optional setup gap.
+
+If nothing meaningful is found, say `No raw-output waste found. Routing looks covered.`

package/skills/context-compress-audit/agents/openai.yaml

@@ -0,0 +1,13 @@
+interface:
+  display_name: "Context Compress Audit"
+  short_description: "Find raw-output context waste."
+  default_prompt: "Use $context-compress-audit to audit this project for raw tool output waste and missing routing."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "context-compress"
+      description: "Context-compress MCP server for stats and indexed search."
+
+policy:
+  allow_implicit_invocation: true