@drewpayment/mink 0.12.0 → 0.13.0-beta.2

package/src/core/output-compression.ts

@@ -0,0 +1,252 @@
+// Tool-output compression engine (spec 21 §Content-Aware Compression).
+//
+// Pure, deterministic, dependency-free. Each compressor takes a tool output
+// string and returns a smaller body plus a note of what was dropped, or null
+// when it has nothing worth substituting. No I/O, no DB, no token counting and
+// no retrieval-affordance text — the pipeline (compress-tool-output.ts) owns
+// eligibility, the holdout, the min-savings gate, the cache, and the
+// "mink retrieve" footer. Keeping this layer pure makes every strategy trivially
+// testable and prompt-cache-stable (identical input → identical output).
+//
+// The "file" strategy does line-based signature extraction; spec 21's phase 3
+// upgrades it to richer AST skeletons behind this same interface.
+
+import type { ContentKind, CompressionResult } from "../types/compression";
+import { extractCodeSkeleton } from "./code-skeleton";
+
+// Tuning constants. Fixed (not config) so output is deterministic and stable.
+const SEARCH_MAX_PER_FILE = 5;
+const LOG_HEAD = 40;
+const LOG_TAIL = 40;
+const TEXT_HEAD = 30;
+const TEXT_TAIL = 20;
+const JSON_ARRAY_HEAD = 20;
+const JSON_ARRAY_TAIL = 5;
+
+// Strip ANSI CSI escape sequences (colour, cursor moves) — pure noise in logs.
+const ANSI = /\[[0-9;?]*[ -/]*[@-~]/g;
+
+function stripAnsi(s: string): string {
+  return s.replace(ANSI, "");
+}
+
+function omittedMarker(n: number): string {
+  return `  … ${n} line${n === 1 ? "" : "s"} omitted — mink retrieve …`;
+}
+
+// Split into lines, dropping a single trailing empty line (from a final newline)
+// so counts and windows aren't skewed by it.
+function toLines(content: string): string[] {
+  const lines = content.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return lines;
+}
+
+// ── Logs / command output ───────────────────────────────────────────────────
+// Strip ANSI, collapse runs of identical lines, then keep a head+tail window.
+function compressLog(content: string): { compressed: string; omittedNote: string } | null {
+  const lines = toLines(stripAnsi(content));
+
+  // Collapse consecutive duplicates into "<line>  (×N)".
+  const collapsed: string[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    let run = 1;
+    while (i + run < lines.length && lines[i + run] === lines[i]) run++;
+    collapsed.push(run > 1 ? `${lines[i]}  (×${run})` : lines[i]);
+    i += run;
+  }
+
+  if (collapsed.length <= LOG_HEAD + LOG_TAIL) {
+    // Only worth substituting if collapsing actually removed lines.
+    if (collapsed.length === lines.length) return null;
+    return {
+      compressed: collapsed.join("\n"),
+      omittedNote: `collapsed ${lines.length - collapsed.length} repeated line(s)`,
+    };
+  }
+
+  const omitted = collapsed.length - LOG_HEAD - LOG_TAIL;
+  const head = collapsed.slice(0, LOG_HEAD);
+  const tail = collapsed.slice(collapsed.length - LOG_TAIL);
+  return {
+    compressed: [...head, omittedMarker(omitted), ...tail].join("\n"),
+    omittedNote: `${omitted} of ${collapsed.length} log line(s) omitted (middle)`,
+  };
+}
+
+// ── Search / match results ──────────────────────────────────────────────────
+// Dedup exact lines and cap matches per file (the file prefix before the first
+// colon), appending a per-file "+K more" tally.
+function compressSearch(content: string): { compressed: string; omittedNote: string } | null {
+  const lines = toLines(content);
+  const seen = new Set<string>();
+  const perFile = new Map<string, number>();
+  const omittedByFile = new Map<string, number>();
+  const out: string[] = [];
+
+  for (const line of lines) {
+    if (seen.has(line)) continue;
+    seen.add(line);
+    const colon = line.indexOf(":");
+    const file = colon > 0 ? line.slice(0, colon) : line;
+    const count = perFile.get(file) ?? 0;
+    if (count < SEARCH_MAX_PER_FILE) {
+      perFile.set(file, count + 1);
+      out.push(line);
+    } else {
+      omittedByFile.set(file, (omittedByFile.get(file) ?? 0) + 1);
+    }
+  }
+
+  let totalOmitted = 0;
+  for (const [file, n] of omittedByFile) {
+    totalOmitted += n;
+    out.push(`  … +${n} more match(es) in ${file} — mink retrieve …`);
+  }
+  const dedupRemoved = lines.length - seen.size;
+
+  // Nothing changed → not worth substituting.
+  if (totalOmitted === 0 && dedupRemoved === 0) return null;
+
+  const notes: string[] = [];
+  if (totalOmitted > 0) notes.push(`${totalOmitted} match(es) capped`);
+  if (dedupRemoved > 0) notes.push(`${dedupRemoved} duplicate(s) removed`);
+  return { compressed: out.join("\n"), omittedNote: notes.join("; ") };
+}
+
+// ── Large file reads ────────────────────────────────────────────────────────
+// Brace-aware structural skeleton (see code-skeleton.ts): declarations and class
+// members with bodies elided. Falls back to a generic text window when the
+// content has no recognisable structure.
+function compressFile(
+  filePath: string,
+  content: string
+): { compressed: string; omittedNote: string } | null {
+  const ext = filePath.slice(filePath.lastIndexOf(".")).toLowerCase();
+  const markdown = ext === ".md" || ext === ".mdx" || ext === ".markdown";
+  const skeleton = extractCodeSkeleton(content, { markdown });
+
+  if (!skeleton) {
+    // No recognisable structure — fall back to a generic text window.
+    return compressText(content);
+  }
+
+  const header =
+    `${filePath} — structural summary ` +
+    `(${skeleton.lines.length} signature(s) of ${skeleton.totalLines} lines)`;
+  return {
+    compressed: [header, ...skeleton.lines].join("\n"),
+    omittedNote: `bodies elided; ${skeleton.totalLines} lines available via mink retrieve`,
+  };
+}
+
+// ── Structured data ─────────────────────────────────────────────────────────
+// Recursively "crush" JSON: sample any over-long array (at any depth), recursing
+// into the elements that are kept. Records how many elements were dropped.
+function crush(value: unknown): { value: unknown; omitted: number } {
+  if (Array.isArray(value)) {
+    let omitted = 0;
+    const mapEl = (el: unknown): unknown => {
+      const r = crush(el);
+      omitted += r.omitted;
+      return r.value;
+    };
+    if (value.length <= JSON_ARRAY_HEAD + JSON_ARRAY_TAIL) {
+      return { value: value.map(mapEl), omitted };
+    }
+    const dropped = value.length - JSON_ARRAY_HEAD - JSON_ARRAY_TAIL;
+    omitted += dropped;
+    const out = [
+      ...value.slice(0, JSON_ARRAY_HEAD).map(mapEl),
+      `… ${dropped} element(s) omitted — mink retrieve …`,
+      ...value.slice(value.length - JSON_ARRAY_TAIL).map(mapEl),
+    ];
+    return { value: out, omitted };
+  }
+  if (value && typeof value === "object") {
+    let omitted = 0;
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      const r = crush(v);
+      omitted += r.omitted;
+      out[k] = r.value;
+    }
+    return { value: out, omitted };
+  }
+  return { value, omitted: 0 };
+}
+
+function compressJson(content: string): { compressed: string; omittedNote: string } | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return null;
+  }
+  const { value, omitted } = crush(parsed);
+  if (omitted === 0) return null;
+  return {
+    compressed: JSON.stringify(value, null, 2),
+    omittedNote: `${omitted} array element(s) sampled out`,
+  };
+}
+
+// ── Generic text ────────────────────────────────────────────────────────────
+function compressText(content: string): { compressed: string; omittedNote: string } | null {
+  const lines = toLines(content);
+  if (lines.length <= TEXT_HEAD + TEXT_TAIL) return null;
+  const omitted = lines.length - TEXT_HEAD - TEXT_TAIL;
+  const head = lines.slice(0, TEXT_HEAD);
+  const tail = lines.slice(lines.length - TEXT_TAIL);
+  return {
+    compressed: [...head, omittedMarker(omitted), ...tail].join("\n"),
+    omittedNote: `${omitted} of ${lines.length} line(s) omitted (middle)`,
+  };
+}
+
+// ── Routing ─────────────────────────────────────────────────────────────────
+
+export function detectContentKind(
+  toolName: string,
+  content: string,
+  filePath?: string
+): ContentKind {
+  const t = toolName.toLowerCase();
+  if (t === "read") return "file";
+  if (t === "grep" || t === "glob") return "search";
+  if (t === "bash") return "log";
+  // Generic / MCP output — sniff for JSON.
+  const head = content.trimStart()[0];
+  if (head === "{" || head === "[") {
+    try {
+      JSON.parse(content);
+      return "json";
+    } catch {
+      // not JSON — fall through
+    }
+  }
+  // A file path with no tool hint still implies a file read.
+  if (filePath) return "file";
+  return "text";
+}
+
+// Compress an output by its detected kind. Returns null when there is nothing
+// worth substituting; the caller then passes the original through unchanged.
+export function compressOutput(
+  toolName: string,
+  content: string,
+  filePath?: string
+): CompressionResult | null {
+  const kind = detectContentKind(toolName, content, filePath);
+  let result: { compressed: string; omittedNote: string } | null;
+  switch (kind) {
+    case "search": result = compressSearch(content); break;
+    case "log":    result = compressLog(content); break;
+    case "file":   result = compressFile(filePath ?? "file", content); break;
+    case "json":   result = compressJson(content); break;
+    case "text":   result = compressText(content); break;
+  }
+  if (!result) return null;
+  return { kind, compressed: result.compressed, omittedNote: result.omittedNote };
+}

package/src/core/token-estimate.ts

@@ -34,3 +34,43 @@ export function estimateTokens(content: string, filePath: string): number {
   }
   return Math.ceil(content.length / ratio);
 }
+
+// A deterministic, dependency-free token counter that segments text the way a
+// BPE tokenizer roughly would — on word, number, and punctuation boundaries —
+// rather than dividing by a single flat character ratio. It is more faithful
+// than `estimateTokens` (which exists for the file-index hot path and is pinned
+// by exact-ratio tests), and crucially it does not need a file extension, so it
+// can score arbitrary tool output (logs, search results, command output).
+//
+// It is intentionally NOT a real BPE vocabulary: Mink ships as a lean CLI with a
+// single runtime dependency, and the compression-measurement use only needs a
+// *consistent* estimator to compute an original-minus-compressed delta. The
+// signature is stable, so a real BPE library can be dropped in behind it later
+// without touching call sites.
+//
+// Segmentation: runs of ASCII letters and runs of digits each collapse to a
+// handful of sub-word tokens; every other character (punctuation, symbols,
+// non-ASCII, whitespace) is scored individually. Whitespace usually merges into
+// an adjacent token in real tokenizers, so spaces and tabs cost nothing and only
+// newlines count.
+export function countTokens(text: string): number {
+  if (!text) return 0;
+  const segments = text.match(/[A-Za-z]+|[0-9]+|[^A-Za-z0-9]/g);
+  if (!segments) return 0;
+  let tokens = 0;
+  for (const seg of segments) {
+    const first = seg.charCodeAt(0);
+    if ((first >= 65 && first <= 90) || (first >= 97 && first <= 122)) {
+      tokens += Math.ceil(seg.length / 4); // word splits into ~4-char sub-words
+    } else if (first >= 48 && first <= 57) {
+      tokens += Math.ceil(seg.length / 3); // digit runs tokenize more finely
+    } else if (seg === "\n") {
+      tokens += 1; // newlines are their own token
+    } else if (seg === " " || seg === "\t" || seg === "\r") {
+      // whitespace merges into the adjacent token — no extra cost
+    } else {
+      tokens += 1; // punctuation / symbol / non-ASCII char
+    }
+  }
+  return tokens;
+}

package/src/repositories/compression-cache-repo.ts

@@ -0,0 +1,97 @@
+// Reversible-compression cache repository (spec 21 §Reversibility). Stores the
+// byte-exact original of a compressed tool output keyed by a short retrieval
+// token, with a TTL. `get` treats an expired row as a miss and evicts it lazily,
+// so a stale token can never return partial or wrong content.
+//
+// This is a local cache — it is never injected into model context and is not
+// part of the cross-device sync surface. device_id is recorded for audit only.
+
+import { randomUUID } from "crypto";
+import type { DbDriver } from "../storage/driver";
+import type { CompressionCacheEntry, ContentKind } from "../types/compression";
+import { openProjectDb } from "../storage/db";
+import { getOrCreateDeviceId } from "../core/device";
+
+export interface StoreInput {
+  toolName: string;
+  contentKind: ContentKind;
+  content: string;
+  retentionHours: number;
+  token?: string;
+  now?: Date;
+}
+
+export class CompressionCacheRepo {
+  constructor(private readonly db: DbDriver) {}
+
+  static for(cwd: string): CompressionCacheRepo {
+    return new CompressionCacheRepo(openProjectDb(cwd));
+  }
+
+  // Short, unambiguous token the model can paste into `mink retrieve`.
+  static newToken(): string {
+    return `mc-${randomUUID().slice(0, 8)}`;
+  }
+
+  // Store an original and return its retrieval token.
+  store(input: StoreInput, deviceId: string = getOrCreateDeviceId()): string {
+    const token = input.token ?? CompressionCacheRepo.newToken();
+    const now = input.now ?? new Date();
+    const createdAt = now.toISOString();
+    const expiresAt = new Date(
+      now.getTime() + Math.max(0, input.retentionHours) * 3_600_000
+    ).toISOString();
+    this.db.prepare(`
+      INSERT OR REPLACE INTO compression_cache
+        (token, created_at, expires_at, tool_name, content_kind,
+         content, size_bytes, device_id)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      token, createdAt, expiresAt, input.toolName, input.contentKind,
+      input.content, Buffer.byteLength(input.content, "utf-8"), deviceId
+    );
+    return token;
+  }
+
+  // Return the stored original, or null if the token is unknown or expired.
+  // An expired row is deleted on the way out (lazy eviction).
+  get(token: string, now: Date = new Date()): CompressionCacheEntry | null {
+    const row = this.db
+      .prepare("SELECT * FROM compression_cache WHERE token = ?")
+      .get(token) as Record<string, unknown> | undefined;
+    if (!row) return null;
+    const expiresAt = String(row.expires_at);
+    if (expiresAt <= now.toISOString()) {
+      try {
+        this.db.prepare("DELETE FROM compression_cache WHERE token = ?").run(token);
+      } catch {
+        // best effort — a failed eviction still reports a miss below
+      }
+      return null;
+    }
+    return {
+      token: String(row.token),
+      createdAt: String(row.created_at),
+      expiresAt,
+      toolName: String(row.tool_name),
+      contentKind: String(row.content_kind) as ContentKind,
+      content: String(row.content),
+      sizeBytes: Number(row.size_bytes),
+    };
+  }
+
+  // Delete every row whose TTL has elapsed. Returns the count removed.
+  evictExpired(now: Date = new Date()): number {
+    const r = this.db
+      .prepare("DELETE FROM compression_cache WHERE expires_at <= ?")
+      .run(now.toISOString());
+    return Number(r.changes);
+  }
+
+  count(): number {
+    const row = this.db
+      .prepare("SELECT COUNT(*) AS n FROM compression_cache")
+      .get() as { n: number };
+    return Number(row.n);
+  }
+}

package/src/repositories/token-ledger-repo.ts

@@ -21,6 +21,9 @@ import type {
   TokenLedger,
   LedgerSession,
   LifetimeCounters,
+  CompressionEvent,
+  CompressionEventInput,
+  CompressionLifetime,
 } from "../types/token-ledger";
 import type { SessionSummary } from "../types/session";
 import type { WasteFlag, WastePattern } from "../types/waste-detection";
@@ -233,6 +236,90 @@ export class TokenLedgerRepo {
     });
   }
 
+  // ── Compression measurement (spec 21) ────────────────────────────────
+
+  // Record one compression decision and fold it into this device's
+  // compression-lifetime aggregates, transactionally so the row and the
+  // aggregate never drift. measured savings credits compressed arms only —
+  // a holdout arm saves nothing by construction.
+  recordCompression(
+    event: CompressionEventInput,
+    deviceId: string = getOrCreateDeviceId()
+  ): void {
+    const id = event.id ?? crypto.randomUUID();
+    const createdAt = event.createdAt ?? new Date().toISOString();
+    const holdout = event.holdout ? 1 : 0;
+    const savings = event.holdout
+      ? 0
+      : Math.max(0, event.originalTokens - event.compressedTokens);
+    this.db.transaction(() => {
+      this.db.prepare(`
+        INSERT OR REPLACE INTO ledger_compressions
+          (id, created_at, tool_name, content_kind,
+           original_tokens, compressed_tokens, holdout, device_id)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        id, createdAt, event.toolName, event.contentKind,
+        event.originalTokens, event.compressedTokens, holdout, deviceId
+      );
+      this.db.prepare(`
+        INSERT INTO ledger_compression_lifetime
+          (device_id, total_events, total_holdout_events,
+           total_original_tokens, total_compressed_tokens, total_measured_savings)
+        VALUES (?, ?, ?, ?, ?, ?)
+        ON CONFLICT(device_id) DO UPDATE SET
+          total_events            = ledger_compression_lifetime.total_events            + excluded.total_events,
+          total_holdout_events    = ledger_compression_lifetime.total_holdout_events    + excluded.total_holdout_events,
+          total_original_tokens   = ledger_compression_lifetime.total_original_tokens   + excluded.total_original_tokens,
+          total_compressed_tokens = ledger_compression_lifetime.total_compressed_tokens + excluded.total_compressed_tokens,
+          total_measured_savings  = ledger_compression_lifetime.total_measured_savings  + excluded.total_measured_savings
+      `).run(
+        deviceId, 1, holdout,
+        event.originalTokens, event.compressedTokens, savings
+      );
+    });
+  }
+
+  // Project-wide compression aggregates — summed across every device's row.
+  compressionLifetime(): CompressionLifetime {
+    const row = this.db.prepare(`
+      SELECT
+        COALESCE(SUM(total_events),            0) AS totalEvents,
+        COALESCE(SUM(total_holdout_events),    0) AS totalHoldoutEvents,
+        COALESCE(SUM(total_original_tokens),   0) AS totalOriginalTokens,
+        COALESCE(SUM(total_compressed_tokens), 0) AS totalCompressedTokens,
+        COALESCE(SUM(total_measured_savings),  0) AS totalMeasuredSavings
+      FROM ledger_compression_lifetime
+    `).get() as Record<string, number> | undefined;
+    return {
+      totalEvents:           Number(row?.totalEvents ?? 0),
+      totalHoldoutEvents:    Number(row?.totalHoldoutEvents ?? 0),
+      totalOriginalTokens:   Number(row?.totalOriginalTokens ?? 0),
+      totalCompressedTokens: Number(row?.totalCompressedTokens ?? 0),
+      totalMeasuredSavings:  Number(row?.totalMeasuredSavings ?? 0),
+    };
+  }
+
+  // Recent compression events, newest first. Primarily for inspection/tests.
+  compressionEvents(limit = 100): CompressionEvent[] {
+    const rows = this.db.prepare(`
+      SELECT id, created_at, tool_name, content_kind,
+             original_tokens, compressed_tokens, holdout
+      FROM ledger_compressions
+      ORDER BY created_at DESC
+      LIMIT ?
+    `).all(limit) as Array<Record<string, unknown>>;
+    return rows.map((r) => ({
+      id:               String(r.id),
+      createdAt:        String(r.created_at),
+      toolName:         String(r.tool_name),
+      contentKind:      String(r.content_kind),
+      originalTokens:   Number(r.original_tokens),
+      compressedTokens: Number(r.compressed_tokens),
+      holdout:          Number(r.holdout) === 1,
+    }));
+  }
+
   // ── Helpers ───────────────────────────────────────────────────────────
 
   private insertSessionRow(

package/src/storage/schema.ts

@@ -12,7 +12,7 @@
 // - `meta(key, value)` holds versioning + migration markers. Keep it small;
 //   per-store counters live in `counters` and `ledger_lifetime`.
 
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 3;
 
 export const INITIAL_SCHEMA = `
 CREATE TABLE IF NOT EXISTS meta (
@@ -176,6 +176,55 @@ CREATE TABLE IF NOT EXISTS counters (
   file_index_hits   INTEGER NOT NULL DEFAULT 0,
   file_index_misses INTEGER NOT NULL DEFAULT 0
 );
+
+-- Tool-output compression measurement (spec 21). One row per compression
+-- decision: either a compressed arm (compressed_tokens < original_tokens) or a
+-- holdout arm (left uncompressed for control, compressed_tokens = original_tokens).
+-- These are append-only telemetry, independent of session lifecycle, written at
+-- the moment a tool output is processed. New table → applied to existing DBs via
+-- IF NOT EXISTS on the next open.
+CREATE TABLE IF NOT EXISTS ledger_compressions (
+  id                TEXT PRIMARY KEY,
+  created_at        TEXT NOT NULL,
+  tool_name         TEXT NOT NULL,
+  content_kind      TEXT NOT NULL,
+  original_tokens   INTEGER NOT NULL DEFAULT 0,
+  compressed_tokens INTEGER NOT NULL DEFAULT 0,
+  holdout           INTEGER NOT NULL DEFAULT 0,
+  device_id         TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_ledger_compressions_created ON ledger_compressions(created_at);
+CREATE INDEX IF NOT EXISTS idx_ledger_compressions_device  ON ledger_compressions(device_id);
+
+-- Per-device compression aggregates, summed across devices like ledger_lifetime.
+-- measured_savings only credits compressed arms (holdout arms save nothing by
+-- construction), so the reported figure is a true measured delta, not an estimate.
+CREATE TABLE IF NOT EXISTS ledger_compression_lifetime (
+  device_id               TEXT PRIMARY KEY,
+  total_events            INTEGER NOT NULL DEFAULT 0,
+  total_holdout_events    INTEGER NOT NULL DEFAULT 0,
+  total_original_tokens   INTEGER NOT NULL DEFAULT 0,
+  total_compressed_tokens INTEGER NOT NULL DEFAULT 0,
+  total_measured_savings  INTEGER NOT NULL DEFAULT 0
+);
+
+-- Reversible-compression cache (spec 21 §Reversibility). When a tool output is
+-- compressed, the original is stored here keyed by a short retrieval token and
+-- embedded in the compressed result; "mink retrieve <token>" returns it
+-- byte-exact. Rows expire after the configured retention window; an expired or
+-- unknown token is a graceful miss. This is a local cache, not synced state, so
+-- (unlike other tables) it carries no merge semantics beyond device_id for audit.
+CREATE TABLE IF NOT EXISTS compression_cache (
+  token        TEXT PRIMARY KEY,
+  created_at   TEXT NOT NULL,
+  expires_at   TEXT NOT NULL,
+  tool_name    TEXT NOT NULL,
+  content_kind TEXT NOT NULL,
+  content      TEXT NOT NULL,
+  size_bytes   INTEGER NOT NULL,
+  device_id    TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_compression_cache_expires ON compression_cache(expires_at);
 `;
 
 export interface DriverForSchema {

package/src/types/compression.ts

@@ -0,0 +1,29 @@
+// Tool-output compression types (spec 21). The decision/config types live in
+// src/core/compression.ts; these describe the reversible cache and the engine's
+// content-aware output.
+
+// What kind of tool output we detected, which selects the compressor and is
+// recorded on the ledger event for later analysis.
+export type ContentKind = "search" | "log" | "file" | "json" | "text";
+
+// One stored original, retrievable byte-exact via `mink retrieve <token>` until
+// it expires.
+export interface CompressionCacheEntry {
+  token: string;
+  createdAt: string;
+  expiresAt: string;
+  toolName: string;
+  contentKind: ContentKind;
+  content: string;
+  sizeBytes: number;
+}
+
+// The result of compressing one output. `compressed` is the body the model will
+// see (sans retrieval affordance, which the pipeline appends); `omittedNote`
+// summarises what was dropped. A compressor returns null when it has nothing
+// worth substituting.
+export interface CompressionResult {
+  kind: ContentKind;
+  compressed: string;
+  omittedNote: string;
+}

package/src/types/config.ts

@@ -18,6 +18,11 @@ export interface GlobalConfig {
   "cli.auto-update-schedule"?: string;
   "cli.auto-update-package-manager"?: string;
   "projects.identity"?: string;
+  "compression.enabled"?: string;
+  "compression.threshold-tokens"?: string;
+  "compression.min-savings-ratio"?: string;
+  "compression.holdout-fraction"?: string;
+  "compression.retention-hours"?: string;
 }
 
 export type ConfigKey = keyof GlobalConfig & string;
@@ -179,6 +184,41 @@ export const CONFIG_KEYS: ConfigKeyMeta[] = [
       "Project identity strategy: path-derived (legacy) or git-remote (stable across machines)",
     scope: "shared",
   },
+  {
+    key: "compression.enabled",
+    default: "false",
+    envVar: "MINK_COMPRESSION_ENABLED",
+    description: "Enable tool-output compression (spec 21). Off until inline compression ships.",
+    scope: "shared",
+  },
+  {
+    key: "compression.threshold-tokens",
+    default: "800",
+    envVar: "MINK_COMPRESSION_THRESHOLD_TOKENS",
+    description: "Minimum estimated token size before a tool output is eligible for compression",
+    scope: "shared",
+  },
+  {
+    key: "compression.min-savings-ratio",
+    default: "0.25",
+    envVar: "MINK_COMPRESSION_MIN_SAVINGS_RATIO",
+    description: "Discard a compression attempt unless it saves at least this fraction of tokens",
+    scope: "shared",
+  },
+  {
+    key: "compression.holdout-fraction",
+    default: "0.1",
+    envVar: "MINK_COMPRESSION_HOLDOUT_FRACTION",
+    description: "Fraction of eligible outputs left uncompressed as a measured control group",
+    scope: "shared",
+  },
+  {
+    key: "compression.retention-hours",
+    default: "168",
+    envVar: "MINK_COMPRESSION_RETENTION_HOURS",
+    description: "How long compressed originals stay retrievable before eviction",
+    scope: "shared",
+  },
 ];
 
 const VALID_KEYS = new Set<string>(CONFIG_KEYS.map((k) => k.key));

package/src/types/hook-input.ts

@@ -19,6 +19,10 @@ export interface PostToolUseInput {
     // Edit tool
     old_string?: string;
     new_string?: string;
+    // Read tool — present for ranged reads; their output is a slice, so we
+    // don't substitute a whole-file summary for them (spec 21 edge case).
+    offset?: number;
+    limit?: number;
   };
   // Legacy / older hook payload shape — kept for backward compatibility.
   tool_output?: {