@drewpayment/mink 0.12.0 → 0.13.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drewpayment/mink",
-  "version": "0.12.0",
+  "version": "0.13.0-beta.2",
   "description": "A hidden presence that moves alongside the developer — token efficiency and cross-project wiki for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -53,6 +53,12 @@ switch (command) {
     break;
   }
 
+  case "post-tool": {
+    const { postTool } = await import("./commands/post-tool");
+    await postTool(cwd);
+    break;
+  }
+
   case "pre-write": {
     const { preWrite } = await import("./commands/pre-write");
     await preWrite(cwd);
@@ -71,6 +77,12 @@ switch (command) {
     break;
   }
 
+  case "retrieve": {
+    const { retrieve } = await import("./commands/retrieve");
+    retrieve(cwd, process.argv.slice(3));
+    break;
+  }
+
   case "cron": {
     const { cron } = await import("./commands/cron");
     await cron(cwd, process.argv.slice(3));
@@ -263,6 +275,7 @@ switch (command) {
     console.log("  restore [backup]        Restore state from a backup");
     console.log("  bug search <term>       Search the bug log");
     console.log("  detect-waste            Detect and flag wasteful patterns");
+    console.log("  retrieve <token>        Return a compressed tool output's original (spec 21)");
     console.log("  reflect                 Generate learning memory reflections");
     console.log("  designqc [target]       Capture design screenshots (spec 13)");
     console.log("  framework-advisor       Generate framework advisor knowledge file (spec 14)");
@@ -272,6 +285,7 @@ switch (command) {
     console.log("  session-stop            Finalize session and log data");
     console.log("  pre-read / post-read    File read hooks");
     console.log("  pre-write / post-write  File write hooks");
+    console.log("  post-tool               Tool-output compression hook (Bash/Grep/MCP, spec 21)");
     break;
 
   default:

package/src/commands/init.ts

@@ -91,6 +91,9 @@ export function buildHooksConfig(cliPath: string): HooksConfig {
       { matcher: "Read", hooks: hook(`${prefix} post-read`) },
       { matcher: "Edit", hooks: hook(`${prefix} post-write`) },
       { matcher: "Write", hooks: hook(`${prefix} post-write`) },
+      // Tool-output compression (spec 21) — a no-op until enabled via config.
+      { matcher: "Bash", hooks: hook(`${prefix} post-tool`) },
+      { matcher: "Grep", hooks: hook(`${prefix} post-tool`) },
     ],
   };
 }
@@ -102,7 +105,8 @@ function isMinkCommand(cmd: string): boolean {
     cmd.includes("pre-read") ||
     cmd.includes("post-read") ||
     cmd.includes("pre-write") ||
-    cmd.includes("post-write");
+    cmd.includes("post-write") ||
+    cmd.includes("post-tool");
   if (!hasMinkSubcommand) return false;
   // Match the new bin-shim format (`mink <subcmd>` or `/abs/path/to/mink <subcmd>`)
   // as well as legacy formats (`bun run .../cli.js ...`, `node .../cli.js ...`,

package/src/commands/post-read.ts

@@ -9,6 +9,8 @@ import { estimateTokens, isBinaryFile } from "../core/token-estimate";
 import { extractDescription } from "../core/description";
 import { createActionLogWriter } from "../core/action-log";
 import { getOrCreateDeviceId } from "../core/device";
+import { compressToolOutput } from "../core/compress-tool-output";
+import { emitUpdatedToolOutput } from "../core/hook-output";
 import type { SessionState } from "../types/session";
 import type { FileIndexEntry, IndexLookup } from "../types/file-index";
 import type { PostToolUseInput } from "../types/hook-input";
@@ -202,6 +204,22 @@ export async function postRead(cwd: string): Promise<void> {
 
     // Persist state
     atomicWriteJson(sessionPath(cwd), state);
+
+    // Tool-output compression (spec 21). Substitute a compact, reversible
+    // summary for a large whole-file read. Skipped for ranged reads (their
+    // output is only a slice) and a no-op unless compression is enabled. Uses
+    // the on-disk content as the canonical original so signature extraction
+    // works on raw source and `mink retrieve` returns the file itself.
+    const isRanged =
+      input.tool_input.offset != null || input.tool_input.limit != null;
+    if (!isRanged && content && content.length > 0) {
+      try {
+        const outcome = compressToolOutput(cwd, "Read", content, filePath);
+        if (outcome) emitUpdatedToolOutput(outcome.updatedToolOutput);
+      } catch {
+        // Compression is advisory — never break the read over it.
+      }
+    }
   } catch {
     // Never crash — exit silently
   } finally {

package/src/commands/post-tool.ts

@@ -0,0 +1,48 @@
+// Generic PostToolUse compression hook (spec 21) for tools that produce large,
+// non-file output — Bash, Grep/Glob, and MCP tools. The Read tool is handled by
+// post-read (which has the on-disk content and ranged-read awareness); this hook
+// compresses the payload text directly.
+//
+// Like every Mink hook: non-blocking, time-boxed, and silent on failure. It is a
+// no-op unless compression is enabled, so wiring it up costs nothing until the
+// user opts in.
+
+import { readStdinJson } from "../core/stdin";
+import { extractToolOutputText, emitUpdatedToolOutput } from "../core/hook-output";
+import { compressToolOutput } from "../core/compress-tool-output";
+import type { PostToolUseInput } from "../types/hook-input";
+
+function isPostToolUseInput(value: unknown): value is PostToolUseInput {
+  if (value === null || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  return typeof obj.tool_name === "string";
+}
+
+// Tools whose output we compress here. Read is excluded (post-read owns it).
+function isCompressibleTool(toolName: string): boolean {
+  return (
+    toolName === "Bash" ||
+    toolName === "Grep" ||
+    toolName === "Glob" ||
+    toolName.startsWith("mcp__")
+  );
+}
+
+export async function postTool(cwd: string): Promise<void> {
+  const timer = setTimeout(() => process.exit(0), 5000);
+  try {
+    const input = await readStdinJson();
+    if (!isPostToolUseInput(input)) return;
+    if (!isCompressibleTool(input.tool_name)) return;
+
+    const output = extractToolOutputText(input);
+    if (!output) return;
+
+    const outcome = compressToolOutput(cwd, input.tool_name, output);
+    if (outcome) emitUpdatedToolOutput(outcome.updatedToolOutput);
+  } catch {
+    // Never crash — exit silently.
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/commands/retrieve.ts

@@ -0,0 +1,32 @@
+// `mink retrieve <token>` — return the byte-exact original of a previously
+// compressed tool output (spec 21 §Reversibility). Prints the original to
+// stdout on a hit; on a miss (unknown or expired token) it prints a short,
+// non-fatal notice to stderr and exits 0 so the assistant is never stranded by
+// an error.
+
+import { CompressionCacheRepo } from "../repositories/compression-cache-repo";
+
+export function retrieve(cwd: string, args: string[]): void {
+  const token = args[0];
+  if (!token) {
+    process.stderr.write("[mink] usage: mink retrieve <token>\n");
+    return;
+  }
+
+  let entry = null;
+  try {
+    entry = CompressionCacheRepo.for(cwd).get(token);
+  } catch {
+    // Treat any storage error as a miss — never throw at the assistant.
+    entry = null;
+  }
+
+  if (!entry) {
+    process.stderr.write(
+      `[mink] no retrievable output for token "${token}" (unknown or expired)\n`
+    );
+    return;
+  }
+
+  process.stdout.write(entry.content);
+}

package/src/core/code-skeleton.ts

@@ -0,0 +1,108 @@
+// Deterministic, dependency-free code skeleton extraction (spec 21 phase 3).
+//
+// Produces a structural outline of source: top-level declarations and the direct
+// members of classes/interfaces, with function/method bodies elided to "{ … }".
+// It is brace-depth aware (with strings and comments masked so stray braces don't
+// desync the depth), which lets it descend into a class to capture method
+// signatures while suppressing the statements inside those methods.
+//
+// This is a heuristic skeleton, not a real parser — Mink stays zero-dependency.
+// Because tool-output compression is reversible (the original is cached), a
+// slightly imperfect skeleton is harmless: the model can always `mink retrieve`.
+// The same extractor is intended to enrich the file index later.
+
+const MAX_SIGNATURES = 80;
+const INDENT = "  ";
+
+// Declarations that always anchor the skeleton.
+const DECL_ALWAYS =
+  /^\s*(?:export\s+)?(?:default\s+)?(?:abstract\s+)?(?:async\s+)?(?:function|class|interface|type|enum|namespace|module|def|fn|func|impl|struct|trait)\b/;
+// Variable declarations only matter to the public surface when exported.
+const DECL_EXPORTED_VAR = /^\s*export\s+(?:default\s+)?(?:const|let|var)\b/;
+// Inside a class/interface body (depth >= 1): method signatures and fields.
+const MEMBER =
+  /^\s*(?:public\s+|private\s+|protected\s+|readonly\s+|static\s+|async\s+|get\s+|set\s+|#)*[\w$]+\??\s*(?:\(|:|=)/;
+// Markdown headings (only honoured for markdown files).
+const HEADING = /^#{1,6}\s+\S/;
+// Keywords whose block we descend into to capture members rather than elide.
+const DESCEND = /\b(?:class|interface|enum|namespace|module|struct|trait|impl)\b/;
+
+function countChar(s: string, c: string): number {
+  let n = 0;
+  for (let i = 0; i < s.length; i++) if (s[i] === c) n++;
+  return n;
+}
+
+// Net brace delta for a line, with strings and comments masked so braces inside
+// them don't affect depth tracking.
+function netBraces(line: string): number {
+  let s = line.replace(/\/\/.*$/, "");
+  s = s.replace(/\/\*.*?\*\//g, "");
+  s = s.replace(/"(?:\\.|[^"\\])*"/g, '""');
+  s = s.replace(/'(?:\\.|[^'\\])*'/g, "''");
+  s = s.replace(/`(?:\\.|[^`\\])*`/g, "``");
+  return countChar(s, "{") - countChar(s, "}");
+}
+
+function stripOpenBrace(sig: string): string {
+  return sig.replace(/\{\s*$/, "").trimEnd();
+}
+
+export interface CodeSkeleton {
+  lines: string[];
+  totalLines: number;
+}
+
+// Extract a skeleton, or null when the content has no recognisable structure
+// (the caller then falls back to a generic text window).
+export function extractCodeSkeleton(
+  content: string,
+  opts: { markdown?: boolean } = {}
+): CodeSkeleton | null {
+  const rawLines = content.split("\n");
+  const totalLines =
+    rawLines.length > 0 && rawLines[rawLines.length - 1] === ""
+      ? rawLines.length - 1
+      : rawLines.length;
+
+  const out: string[] = [];
+  let depth = 0;
+  let suppress = Infinity; // suppress lines while inside an elided function body
+
+  for (const line of rawLines) {
+    if (out.length >= MAX_SIGNATURES) break;
+    const start = depth;
+    const net = netBraces(line);
+
+    if (start < suppress) {
+      const isHeading = opts.markdown === true && HEADING.test(line);
+      const captured =
+        isHeading ||
+        DECL_ALWAYS.test(line) ||
+        DECL_EXPORTED_VAR.test(line) ||
+        (start >= 1 && MEMBER.test(line));
+
+      if (captured) {
+        // Trim the source indentation; we re-indent by structural depth.
+        const sig = line.trim();
+        if (net > 0) {
+          if (DESCEND.test(line) && !isHeading) {
+            out.push(INDENT.repeat(start) + stripOpenBrace(sig) + " {");
+            // descend — keep capturing members at the next depth
+          } else {
+            out.push(INDENT.repeat(start) + stripOpenBrace(sig) + " { … }");
+            suppress = start + 1; // skip this body's contents
+          }
+        } else {
+          out.push(INDENT.repeat(start) + sig);
+        }
+      }
+    }
+
+    depth = Math.max(0, depth + net);
+    if (depth < suppress) suppress = Infinity; // left the elided body
+  }
+
+  if (out.length === 0) return null;
+  return { lines: out, totalLines };
+}

package/src/core/compress-tool-output.ts

@@ -0,0 +1,127 @@
+// Compression pipeline orchestrator (spec 21). Ties together the config/holdout
+// decisions, the pure engine, the reversible cache, and the ledger. Returns the
+// replacement text to emit, or null to pass the original through unchanged.
+//
+// Invariants:
+// - Disabled by default (config gate) → no-op.
+// - Reversible or nothing: the original is stored BEFORE we return a compressed
+//   result; if storage fails we pass the original through, so a compressed
+//   result is never shown without a retrievable original (spec 21 edge case).
+// - Every failure degrades to "no compression" — a hook must never throw.
+// - Holdout arms pass the original through but are still measured.
+
+import {
+  loadCompressionConfig,
+  isEligible,
+  meetsMinSavings,
+  selectHoldout,
+} from "./compression";
+import { countTokens } from "./token-estimate";
+import { compressOutput, detectContentKind } from "./output-compression";
+import type { CompressionResult } from "../types/compression";
+import { CompressionCacheRepo } from "../repositories/compression-cache-repo";
+import { TokenLedgerRepo } from "../repositories/token-ledger-repo";
+
+// Deterministic FNV-1a → hex, used as a stable per-event key so an identical
+// output always lands in the same holdout arm (spec 21 edge case).
+function contentKey(s: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16);
+}
+
+// Render the replacement: stable compressed body first, volatile retrieval
+// footer (random token) last — matching Mink's "volatile at the end" cache
+// discipline so the body forms a stable prefix.
+function render(result: CompressionResult, token: string): string {
+  return (
+    result.compressed +
+    "\n\n" +
+    `— mink: compressed ${result.kind} output (${result.omittedNote}). ` +
+    `Full original: mink retrieve ${token}`
+  );
+}
+
+function safeRecord(
+  cwd: string,
+  toolName: string,
+  contentKind: string,
+  originalTokens: number,
+  compressedTokens: number,
+  holdout: boolean
+): void {
+  try {
+    TokenLedgerRepo.for(cwd).recordCompression({
+      toolName,
+      contentKind,
+      originalTokens,
+      compressedTokens,
+      holdout,
+    });
+  } catch {
+    // Measurement is best-effort — never block the hook over a ledger write.
+  }
+}
+
+export interface CompressOutcome {
+  updatedToolOutput: string;
+  token: string;
+}
+
+export function compressToolOutput(
+  cwd: string,
+  toolName: string,
+  output: string,
+  filePath?: string
+): CompressOutcome | null {
+  let cfg;
+  try {
+    cfg = loadCompressionConfig();
+  } catch {
+    return null;
+  }
+  if (!cfg.enabled) return null;
+  if (typeof output !== "string" || output.length === 0) return null;
+
+  const originalTokens = countTokens(output);
+  if (!isEligible(originalTokens, cfg)) return null;
+
+  const eventKey = contentKey(output);
+
+  // Holdout arm: pass the original through, but record it as a control.
+  if (selectHoldout(eventKey, cfg.holdoutFraction)) {
+    const kind = detectContentKind(toolName, output, filePath);
+    safeRecord(cwd, toolName, kind, originalTokens, originalTokens, true);
+    return null;
+  }
+
+  const result = compressOutput(toolName, output, filePath);
+  if (!result) return null;
+
+  const token = CompressionCacheRepo.newToken();
+  const replacement = render(result, token);
+  const compressedTokens = countTokens(replacement);
+
+  // Discard a weak compression and pass the original through.
+  if (!meetsMinSavings(originalTokens, compressedTokens, cfg)) return null;
+
+  // Store the original FIRST. If we cannot, do not compress — never show a
+  // compressed result without a retrievable original.
+  try {
+    CompressionCacheRepo.for(cwd).store({
+      toolName,
+      contentKind: result.kind,
+      content: output,
+      retentionHours: cfg.retentionHours,
+      token,
+    });
+  } catch {
+    return null;
+  }
+
+  safeRecord(cwd, toolName, result.kind, originalTokens, compressedTokens, false);
+  return { updatedToolOutput: replacement, token };
+}

package/src/core/compression.ts

@@ -0,0 +1,81 @@
+// Tool-output compression — configuration and decision logic (spec 21).
+//
+// This module is pure: it reads config and makes the eligibility / holdout /
+// min-savings decisions. It never touches the database or the tool payload, so
+// it is trivially testable. Phase 2 wires the actual compressors and the
+// reversible cache on top of these decisions; Phase 1 ships the measurement
+// instrument and leaves `enabled` off by default.
+
+import { resolveConfigValue } from "./global-config";
+import type { ConfigKey } from "../types/config";
+
+export interface CompressionConfig {
+  enabled: boolean;
+  thresholdTokens: number;
+  minSavingsRatio: number;
+  holdoutFraction: number;
+  retentionHours: number;
+}
+
+function numberValue(key: ConfigKey, fallback: number, min: number, max: number): number {
+  const raw = resolveConfigValue(key).value;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(max, Math.max(min, n));
+}
+
+export function loadCompressionConfig(): CompressionConfig {
+  return {
+    enabled: resolveConfigValue("compression.enabled").value === "true",
+    thresholdTokens: numberValue("compression.threshold-tokens", 800, 0, Number.MAX_SAFE_INTEGER),
+    minSavingsRatio: numberValue("compression.min-savings-ratio", 0.25, 0, 1),
+    holdoutFraction: numberValue("compression.holdout-fraction", 0.1, 0, 1),
+    retentionHours: numberValue("compression.retention-hours", 168, 0, Number.MAX_SAFE_INTEGER),
+  };
+}
+
+// An output is eligible for compression only once it crosses the size threshold;
+// small outputs are never touched (spec 21 §Eligibility).
+export function isEligible(originalTokens: number, config: CompressionConfig): boolean {
+  return config.enabled && originalTokens >= config.thresholdTokens;
+}
+
+// A compression attempt is kept only if it saves at least the configured
+// fraction of tokens; otherwise the original is used (spec 21 §Thresholds).
+export function meetsMinSavings(
+  originalTokens: number,
+  compressedTokens: number,
+  config: CompressionConfig
+): boolean {
+  if (originalTokens <= 0) return false;
+  const ratio = (originalTokens - compressedTokens) / originalTokens;
+  return ratio >= config.minSavingsRatio;
+}
+
+export function measuredSavings(originalTokens: number, compressedTokens: number): number {
+  return Math.max(0, originalTokens - compressedTokens);
+}
+
+// Deterministic FNV-1a hash → a stable fraction in [0, 1) for a given key. Used
+// so holdout selection is stable per event: the same event always lands in the
+// same arm, which keeps measurement from being double-counted (spec 21 edge
+// case "Holdout selection must be stable for a given event").
+function hashUnitInterval(key: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < key.length; i++) {
+    h ^= key.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  // Map the 32-bit unsigned result into [0, 1).
+  return (h >>> 0) / 0x100000000;
+}
+
+// Decide whether a given event is held out (left uncompressed as a control).
+// Selection is deterministic in `eventKey`, so callers must pass a key that is
+// stable for the event (e.g. a hash of the original output) and not, say, a
+// timestamp.
+export function selectHoldout(eventKey: string, fraction: number): boolean {
+  if (fraction <= 0) return false;
+  if (fraction >= 1) return true;
+  return hashUnitInterval(eventKey) < fraction;
+}

package/src/core/hook-output.ts

@@ -0,0 +1,42 @@
+// Helpers for PostToolUse hooks that replace a tool's result (spec 21). The
+// replacement mechanism is Claude Code's `hookSpecificOutput.updatedToolOutput`
+// (verified against the hooks reference): whatever JSON we print to stdout here
+// substitutes the original output before the model sees it.
+
+import type { PostToolUseInput } from "../types/hook-input";
+
+// Best-effort extraction of the human-visible text from a PostToolUse payload,
+// across the shapes Claude Code uses for different tools (Bash stdout, Grep
+// content, MCP results). Returns null when no text is present, in which case the
+// caller must not compress (there is nothing to safely capture or replace).
+export function extractToolOutputText(input: PostToolUseInput): string | null {
+  const tr = input.tool_response as Record<string, unknown> | undefined;
+  if (tr) {
+    if (typeof tr.content === "string") return tr.content;
+    if (Array.isArray(tr.content)) {
+      const parts = (tr.content as Array<{ text?: unknown }>)
+        .map((p) => (p && typeof p.text === "string" ? p.text : ""))
+        .filter((s) => s.length > 0);
+      if (parts.length > 0) return parts.join("");
+    }
+    if (typeof tr.stdout === "string" && tr.stdout.length > 0) return tr.stdout;
+    if (typeof tr.text === "string") return tr.text;
+    const file = tr.file as { content?: unknown } | undefined;
+    if (file && typeof file.content === "string") return file.content;
+  }
+  const to = input.tool_output;
+  if (to && typeof to.content === "string") return to.content;
+  return null;
+}
+
+// Print the replacement so Claude Code swaps it in for the original output.
+export function emitUpdatedToolOutput(text: string): void {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PostToolUse",
+        updatedToolOutput: text,
+      },
+    })
+  );
+}