distill-mcp 0.8.1 → 0.10.1

package/assets/agents/distill-compressor.md

@@ -0,0 +1,48 @@
+---
+name: distill-compressor
+description: Read-only compression specialist. Delegate long build output, log dumps, verbose diffs, stack traces, and multi-file code skeleton reads to this agent so the parent session keeps its context small. Uses Distill's auto_optimize for content-aware compression and smart_file_read for AST-based code extraction. Not allowed to execute code or mutate state.
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - mcp__distill-mcp__auto_optimize
+  - mcp__distill-mcp__smart_file_read
+disallowedTools:
+  - mcp__distill-mcp__code_execute
+requiredMcpServers:
+  - distill-mcp
+---
+
+You are distill-compressor, a read-only sub-agent whose single job is to shrink large textual payloads — build output, test logs, git diffs, stack traces, configuration dumps, and source code — so they fit inside the parent session's context budget without losing the information the parent actually needs.
+
+Your effectiveness is measured by the token delta between what the parent would have seen raw and what you return. Every extra token you emit is a token the parent loses from its own working memory. Bias hard toward compression: summarize instead of quoting, extract signatures instead of returning whole files, and wrap compressed regions in the Distill marker so Claude Code's compact-summary step preserves them verbatim.
+
+## Content-aware compression with `auto_optimize`
+
+Reach for `mcp__distill-mcp__auto_optimize` whenever you are handed >500 characters of verbose text that came out of a command, a log file, a diff, or a tool result. The tool auto-detects the content type (`build`, `logs`, `diff`, `semantic`, `errors`, `stacktrace`, `config`) and picks the matching compressor — typical savings: build output 95%, logs 80–90%, errors 70–90%, diffs 60–80%, stack traces 50–80%, generic code 40–60%, config 30–60%. If you already know the shape of the input, pass `strategy` explicitly to skip detection. If the caller cares about specific signal — a test name, an error code, a file path — pass `preservePatterns` so those regex matches survive compression. Use `response_format: "minimal"` when the parent only needs the compressed payload and `"detailed"` only when the parent explicitly asked for statistics. Never call `auto_optimize` on inputs shorter than ~500 chars — the helper passes them through unchanged and the round-trip is pure overhead.
+
+## AST-based skeleton reads with `smart_file_read`
+
+Reach for `mcp__distill-mcp__smart_file_read` instead of the built-in `Read` whenever the parent needs structural information from a source file in one of the 7 supported languages (TypeScript, JavaScript, Python, Go, Rust, PHP, Swift). Typical savings vs a full-file read: 50–90%. Four modes cover the common cases:
+
+- `skeleton` with `depth: 1–3` when the parent wants an architectural map (all top-level signatures, optionally nested members).
+- `extract` with `target: { type, name }` when the parent needs exactly one function, class, interface, or type definition.
+- `search` with `query: "<substring>"` when the parent is hunting a symbol by partial name and does not know which file holds it yet (combine with `Glob` to narrow the search surface first).
+- `full` when the file is small enough that a raw read is cheaper than the AST pass — fall back to this rather than invent a skeleton for trivial files.
+
+For unsupported languages the tool returns the raw file with a graceful-fallback note, never an error. When the parent needs a multi-file overview, run `smart_file_read` across each path in parallel via `Glob` + a single Bash for-loop rather than sequential calls.
+
+## Summarizing long outputs you cannot pipe through a tool
+
+When the material you have to condense did not come from a tool you can re-pipe (for example, you read a file with `Read` and it turned out to be a 200 KB log dump, or `Bash` emitted a massive stdout you already captured in your turn), do not echo it back in prose. Either (a) feed the raw text back through `auto_optimize` as the `content` argument, or (b) write a structured summary yourself: lead with a 1–3 sentence conclusion, then a bullet list of the concrete findings — error codes, failing test names, file paths, line numbers, deltas — and stop. No restating the request, no framing paragraphs, no apologies for length. The parent called you to shrink the payload; shrink it.
+
+## The `[DISTILL:COMPRESSED]` marker contract
+
+Distill optionally wraps compressed payloads in `[DISTILL:COMPRESSED ratio=X.XX method=<name>]\n<payload>\n[/DISTILL:COMPRESSED]` when the user has set `DISTILL_COMPRESSED_MARKERS=1` in the Distill server environment. `X.XX` is `compressed_size / original_size` clamped to `[0, 1]`. `<name>` is the compressor or mode that produced the payload (`auto`, `logs`, `diff`, `semantic`, `skeleton`, `extract`, `search`, `build+recompressed`, etc.). Pass marker-wrapped regions through to the parent verbatim — do not unwrap, re-summarize, or edit them. The envelope is the anchor that Distill's PreCompact hook (`packages/mcp-server/scripts/precompact-hook.sh`) points at when it instructs Claude Code's compact-summary LLM to keep the region intact through autocompact; splitting or editing it breaks that contract. If the user text you were handed already contains the literal substring `[DISTILL:COMPRESSED`, Distill falls back to the escape tokens `[DISTILL-USER-TEXT:COMPRESSED … ][/DISTILL-USER-TEXT:COMPRESSED]` — forward those untouched too.
+
+## Operating constraints
+
+You are deliberately read-only. `mcp__distill-mcp__code_execute` is in your `disallowedTools` list because this agent must never run arbitrary JavaScript, invoke git-mutating operations, or touch the filesystem outside of read paths. If the parent's request genuinely needs execution (running a build, applying a patch, writing a file), stop and report back in one sentence that the task is out of scope for distill-compressor so the parent can handle it directly or delegate to a different agent. Do the same if the request requires network access, credential handling, or secrets — your toolset is intentionally narrow.
+
+Return short. When you finish, emit only the compressed payload the parent asked for (plus a single preceding line summarizing what you compressed and by how much, if the savings are noteworthy). No meta-narration. No retelling the plan. The whole value proposition of this sub-agent is token density — honour it on every turn.

package/bin/cli.js

@@ -25,16 +25,20 @@ ${COLORS.bright}Commands:${COLORS.reset}
   analyze           Analyze files for token usage
 
 ${COLORS.bright}Setup Options:${COLORS.reset}
-  --claude          Configure Claude Code only
-  --cursor          Configure Cursor only
-  --windsurf        Configure Windsurf only
-  --antigravity     Configure Antigravity only
-  --hooks           Install project hooks (enforces MCP tool usage)
-  --force, -f       Overwrite existing configuration
+  --claude                        Configure Claude Code only
+  --cursor                        Configure Cursor only
+  --windsurf                      Configure Windsurf only
+  --antigravity                   Configure Antigravity only
+  --hooks                         Install project hooks (enforces MCP tool usage)
+  --install-precompact-hook       Install the Distill PreCompact hook into ~/.claude/settings.json
+  --uninstall-precompact-hook     Remove the Distill PreCompact hook from ~/.claude/settings.json
+  --install-agent                 Copy the distill-compressor agent template into ~/.claude/agents/
+  --uninstall-agent               Remove the installed distill-compressor agent template
+  --dry-run                       Print intended changes; do not mutate the filesystem
+  --user-dir=<path>               Override HOME when locating ~/.claude/settings.json (for testing)
+  --force, -f                     Overwrite existing configuration
 
 ${COLORS.bright}Server Options:${COLORS.reset}
-  --lazy            Enable lazy mode (95% token savings, only 2 meta-tools)
-  --mode <mode>     Loading mode: lazy|core|all (default: core)
   --verbose         Enable verbose logging (shows tool calls, timing, tokens)
 
 ${COLORS.bright}Analyze Options:${COLORS.reset}
@@ -48,18 +52,23 @@ ${COLORS.bright}Other Options:${COLORS.reset}
   --help, -h        Show this help message
 
 ${COLORS.bright}Examples:${COLORS.reset}
-  distill-mcp setup                    Interactive setup wizard
-  distill-mcp setup --claude           Configure Claude Code only
-  distill-mcp setup --antigravity      Configure Antigravity only
-  distill-mcp setup --claude --hooks   Configure Claude Code + install hooks
-  distill-mcp setup --hooks            Install hooks only (current project)
-  distill-mcp setup --force            Overwrite existing configurations
-  distill-mcp doctor                   Verify installation
-  distill-mcp serve                    Start MCP server (used by IDE)
-  distill-mcp serve --lazy             Start with lazy mode (95% savings)
-  distill-mcp serve --verbose          Start with verbose logging
-  distill-mcp analyze                  Analyze token usage in codebase
-  distill-mcp analyze -t 5000 --json   Custom threshold, JSON output
+  distill-mcp setup                              Interactive setup wizard
+  distill-mcp setup --claude                     Configure Claude Code only
+  distill-mcp setup --antigravity                Configure Antigravity only
+  distill-mcp setup --claude --hooks             Configure Claude Code + install hooks
+  distill-mcp setup --hooks                      Install hooks only (current project)
+  distill-mcp setup --install-precompact-hook    Wire PreCompact hook into ~/.claude/settings.json
+  distill-mcp setup --install-precompact-hook --dry-run   Preview the JSON diff
+  distill-mcp setup --uninstall-precompact-hook  Remove the Distill PreCompact entry
+  distill-mcp setup --install-agent              Install the distill-compressor subagent template
+  distill-mcp setup --install-agent --force      Overwrite an existing distill-compressor.md
+  distill-mcp setup --uninstall-agent            Remove the installed distill-compressor subagent
+  distill-mcp setup --force                      Overwrite existing configurations
+  distill-mcp doctor                             Verify installation
+  distill-mcp serve                              Start MCP server (used by IDE)
+  distill-mcp serve --verbose                    Start with verbose logging
+  distill-mcp analyze                            Analyze token usage in codebase
+  distill-mcp analyze -t 5000 --json             Custom threshold, JSON output
 
 ${COLORS.bright}Documentation:${COLORS.reset}
   https://distill-mcp.com/docs
@@ -85,23 +94,7 @@ async function main() {
 
   switch (command) {
     case "serve": {
-      // Parse mode option
-      let mode = "core";
-      const modeIndex = args.indexOf("--mode");
-      if (modeIndex !== -1 && args[modeIndex + 1]) {
-        mode = args[modeIndex + 1];
-      } else if (args.includes("--lazy")) {
-        mode = "lazy";
-      } else if (args.includes("--all")) {
-        mode = "all";
-      }
-
-      const config = {
-        verbose: args.includes("--verbose"),
-        mode,
-      };
-
-      await runServer(config);
+      await runServer({ verbose: args.includes("--verbose") });
       break;
     }
 

package/dist/cli/agent.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Custom agent installer for Distill (US-016).
+ *
+ * Extends `distill-mcp setup` with `--install-agent` and `--uninstall-agent`,
+ * copying the shipped `distill-compressor.md` template (US-015) from the
+ * package `assets/agents/` directory into `<userDir>/.claude/agents/`.
+ *
+ * Design invariants mirror the PreCompact hook installer:
+ *   - Idempotent: installing when the target file already matches the template
+ *     is a no-op; re-running produces no filesystem churn.
+ *   - Atomic: overwrites go through `writeAtomic` (tempfile + rename) so a
+ *     SIGTERM mid-install leaves either the pre-state or the post-state,
+ *     never a half-written file.
+ *   - Non-destructive by default: when the target exists and differs from the
+ *     template, we abort with a line-level diff unless the caller passes
+ *     `force: true`.
+ *   - Dry-run surfaces intended actions without touching disk.
+ *
+ * Per project convention (CLAUDE.md: "Manual process.argv parsing in
+ * bin/cli.js"), this module pulls in no new runtime dependencies.
+ */
+export declare const DISTILL_AGENT_FILENAME = "distill-compressor.md";
+export interface AgentOptions {
+    /** Root dir containing `.claude/` (defaults to OS HOME). Used by tests. */
+    userDir?: string;
+    /** Print intended actions without mutating the filesystem. */
+    dryRun?: boolean;
+    /** Overwrite a differing existing file (install only). */
+    force?: boolean;
+}
+export interface AgentResult {
+    action: "installed" | "uninstalled" | "noop" | "dry-run" | "aborted";
+    /** Absolute path to the agent file that was (or would be) touched. */
+    targetPath: string;
+    /** Human-readable message for CLI output. */
+    message: string;
+    /** Non-empty when `action === "aborted"`. */
+    errorCode?: "differs-without-force" | "asset-missing" | "permission-denied" | "unknown";
+}
+/**
+ * Absolute path to the shipped agent template. Resolves from the compiled
+ * `dist/cli/agent.js` (or `src/cli/agent.ts` under vitest) up to the package
+ * root — both layouts are `<pkg>/<dist|src>/cli/` so two `..` hops land at
+ * the root where `assets/agents/` lives.
+ */
+export declare function getAgentAssetPath(): string;
+export declare function getTargetAgentPath(userDir?: string): string;
+/**
+ * Minimal unified-style diff of two strings, used only to describe the
+ * discrepancy when the caller refuses `--force`. Intentionally naive: a line
+ * in `current` that is missing from `template` shows as `-`, and vice versa.
+ * Output is capped so a massive template drift cannot flood the terminal.
+ */
+export declare function summarizeDiff(current: string, template: string, maxLines?: number): string;
+export declare function installAgent(opts?: AgentOptions): AgentResult;
+export declare function uninstallAgent(opts?: AgentOptions): AgentResult;
+//# sourceMappingURL=agent.d.ts.map

package/dist/cli/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/cli/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAaH,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAE9D,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,WAAW,GAAG,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IACrE,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,uBAAuB,GAAG,eAAe,GAAG,mBAAmB,GAAG,SAAS,CAAC;CACzF;AAMD;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAG1C;AAED,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAG3D;AAMD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAAK,GAAG,MAAM,CAgBtF;AAMD,wBAAgB,YAAY,CAAC,IAAI,GAAE,YAAiB,GAAG,WAAW,CAkEjE;AAED,wBAAgB,cAAc,CAAC,IAAI,GAAE,YAAiB,GAAG,WAAW,CAoCnE"}

package/dist/cli/agent.js

@@ -0,0 +1,181 @@
+/**
+ * Custom agent installer for Distill (US-016).
+ *
+ * Extends `distill-mcp setup` with `--install-agent` and `--uninstall-agent`,
+ * copying the shipped `distill-compressor.md` template (US-015) from the
+ * package `assets/agents/` directory into `<userDir>/.claude/agents/`.
+ *
+ * Design invariants mirror the PreCompact hook installer:
+ *   - Idempotent: installing when the target file already matches the template
+ *     is a no-op; re-running produces no filesystem churn.
+ *   - Atomic: overwrites go through `writeAtomic` (tempfile + rename) so a
+ *     SIGTERM mid-install leaves either the pre-state or the post-state,
+ *     never a half-written file.
+ *   - Non-destructive by default: when the target exists and differs from the
+ *     template, we abort with a line-level diff unless the caller passes
+ *     `force: true`.
+ *   - Dry-run surfaces intended actions without touching disk.
+ *
+ * Per project convention (CLAUDE.md: "Manual process.argv parsing in
+ * bin/cli.js"), this module pulls in no new runtime dependencies.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToLocalPath } from "./utils.js";
+import { writeAtomic } from "./precompact.js";
+// ---------------------------------------------------------------------------
+// Constants & types
+// ---------------------------------------------------------------------------
+export const DISTILL_AGENT_FILENAME = "distill-compressor.md";
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+/**
+ * Absolute path to the shipped agent template. Resolves from the compiled
+ * `dist/cli/agent.js` (or `src/cli/agent.ts` under vitest) up to the package
+ * root — both layouts are `<pkg>/<dist|src>/cli/` so two `..` hops land at
+ * the root where `assets/agents/` lives.
+ */
+export function getAgentAssetPath() {
+    const here = path.dirname(fileURLToLocalPath(import.meta.url));
+    return path.resolve(here, "..", "..", "assets", "agents", DISTILL_AGENT_FILENAME);
+}
+export function getTargetAgentPath(userDir) {
+    const root = userDir ?? os.homedir();
+    return path.join(root, ".claude", "agents", DISTILL_AGENT_FILENAME);
+}
+// ---------------------------------------------------------------------------
+// Diff helper (line-level, zero deps)
+// ---------------------------------------------------------------------------
+/**
+ * Minimal unified-style diff of two strings, used only to describe the
+ * discrepancy when the caller refuses `--force`. Intentionally naive: a line
+ * in `current` that is missing from `template` shows as `-`, and vice versa.
+ * Output is capped so a massive template drift cannot flood the terminal.
+ */
+export function summarizeDiff(current, template, maxLines = 40) {
+    const a = current.split("\n");
+    const b = template.split("\n");
+    const setA = new Set(a);
+    const setB = new Set(b);
+    const lines = [];
+    for (const l of a) {
+        if (!setB.has(l))
+            lines.push(`- ${l}`);
+    }
+    for (const l of b) {
+        if (!setA.has(l))
+            lines.push(`+ ${l}`);
+    }
+    if (lines.length === 0)
+        return "(no line-level differences — only ordering or whitespace changes)";
+    if (lines.length <= maxLines)
+        return lines.join("\n");
+    const head = lines.slice(0, maxLines);
+    return head.join("\n") + `\n… (${lines.length - maxLines} more diff lines omitted)`;
+}
+// ---------------------------------------------------------------------------
+// Public install / uninstall
+// ---------------------------------------------------------------------------
+export function installAgent(opts = {}) {
+    const targetPath = getTargetAgentPath(opts.userDir);
+    const assetPath = getAgentAssetPath();
+    if (!fs.existsSync(assetPath)) {
+        return {
+            action: "aborted",
+            targetPath,
+            message: `Aborted: agent template not found at ${assetPath}. The distill-mcp package may be corrupted — reinstall it.`,
+            errorCode: "asset-missing",
+        };
+    }
+    const templateContent = fs.readFileSync(assetPath, "utf-8");
+    const targetExists = fs.existsSync(targetPath);
+    if (targetExists) {
+        const existingContent = fs.readFileSync(targetPath, "utf-8");
+        if (existingContent === templateContent) {
+            return {
+                action: "noop",
+                targetPath,
+                message: `Agent already installed at ${targetPath} (content matches; no change).`,
+            };
+        }
+        if (!opts.force) {
+            const diff = summarizeDiff(existingContent, templateContent);
+            return {
+                action: "aborted",
+                targetPath,
+                message: `Aborted: ${targetPath} exists and differs from the shipped template.\n` +
+                    `Pass --force to overwrite, or --uninstall-agent first.\n` +
+                    `Diff (existing → template):\n${diff}`,
+                errorCode: "differs-without-force",
+            };
+        }
+    }
+    if (opts.dryRun) {
+        const verb = targetExists ? "overwrite (differs, --force set)" : "create";
+        return {
+            action: "dry-run",
+            targetPath,
+            message: `[dry-run] Would ${verb} ${targetPath} (${templateContent.length} bytes from ${assetPath}).`,
+        };
+    }
+    try {
+        writeAtomic(targetPath, templateContent, 0o644);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            action: "aborted",
+            targetPath,
+            message: `Failed to write ${targetPath}: ${message}`,
+            errorCode: isPermissionError(err) ? "permission-denied" : "unknown",
+        };
+    }
+    const verb = targetExists ? "Overwrote" : "Installed";
+    return {
+        action: "installed",
+        targetPath,
+        message: `${verb} distill-compressor agent → ${targetPath}.`,
+    };
+}
+export function uninstallAgent(opts = {}) {
+    const targetPath = getTargetAgentPath(opts.userDir);
+    if (!fs.existsSync(targetPath)) {
+        return {
+            action: "noop",
+            targetPath,
+            message: `No distill-compressor agent at ${targetPath} — nothing to uninstall.`,
+        };
+    }
+    if (opts.dryRun) {
+        return {
+            action: "dry-run",
+            targetPath,
+            message: `[dry-run] Would delete ${targetPath}.`,
+        };
+    }
+    try {
+        fs.unlinkSync(targetPath);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            action: "aborted",
+            targetPath,
+            message: `Failed to delete ${targetPath}: ${message}`,
+            errorCode: isPermissionError(err) ? "permission-denied" : "unknown",
+        };
+    }
+    return {
+        action: "uninstalled",
+        targetPath,
+        message: `Uninstalled distill-compressor agent from ${targetPath}.`,
+    };
+}
+function isPermissionError(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const code = err.code;
+    return code === "EACCES" || code === "EPERM";
+}

package/dist/cli/hooks.js

@@ -114,7 +114,7 @@ return ctx.code.extract(content, "typescript", { type: "function", name: "handle
 | Lire du code pour exploration | \`mcp__distill__smart_file_read filePath="file.ts"\` |
 | Obtenir une fonction/classe | \`mcp__distill__smart_file_read filePath="file.ts" target={"type":"function","name":"myFunc"}\` |
 | Compresser les erreurs de build | \`mcp__distill__auto_optimize content="..."\` |
-| Résumer les logs | \`mcp__distill__summarize_logs logs="..."\` |
+| Résumer les logs | \`mcp__distill__auto_optimize content="..." strategy="logs"\` |
 | Opérations multi-étapes | \`mcp__distill__code_execute code="return ctx.files.glob('src/**/*.ts')"\` |
 | Avant d'éditer | Utiliser l'outil natif \`Read\` |
 
@@ -176,7 +176,7 @@ if echo "$TOOL_RESPONSE" | grep -qiE "(error TS|warning TS|error\\[E|npm ERR|ERR
 fi
 
 if echo "$TOOL_RESPONSE" | grep -qiE "(\\[INFO\\]|\\[ERROR\\]|\\[WARN\\]|\\[DEBUG\\]|[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2})"; then
-  echo '{"systemMessage": "TIP: Large log output detected. Use mcp__distill__summarize_logs to compress (80-90% reduction)."}'
+  echo '{"systemMessage": "TIP: Large log output detected. Use mcp__distill__auto_optimize with strategy=logs to compress (80-90% reduction)."}'
   exit 0
 fi
 
@@ -192,8 +192,8 @@ cat << 'EOF'
 <user-prompt-submit-hook>
 DISTILL REMINDER: Use MCP tools for token optimization:
 - Code files: mcp__distill__smart_file_read (50-70% savings vs Read)
-- Build/test output: mcp__distill__auto_optimize
-- Session stats: mcp__distill__session_stats
+- Build/test output: mcp__distill__auto_optimize (95%+ reduction)
+- Multi-step ops: mcp__distill__code_execute (98% savings via SDK)
 </user-prompt-submit-hook>
 EOF
 exit 0
@@ -319,7 +319,7 @@ export async function installHooks(options = {}) {
         log(`\n${COLORS.dim}Token savings:${COLORS.reset}`);
         log(`  • smart_file_read:  50-70% reduction vs Read`);
         log(`  • auto_optimize:    95%+ reduction on build errors`);
-        log(`  • summarize_logs:   80-90% reduction on logs\n`);
+        log(`  • auto_optimize:    80-90% reduction on logs\n`);
         return true;
     }
     else {

package/dist/cli/precompact.d.ts

@@ -0,0 +1,101 @@
+/**
+ * PreCompact hook installer for Distill (US-010).
+ *
+ * Extends `distill-mcp setup` with `--install-precompact-hook` and
+ * `--uninstall-precompact-hook`, wiring the shipped POSIX hook
+ * (`scripts/precompact-hook.sh` from US-009) into
+ * `<userDir>/.claude/settings.json` under `hooks.PreCompact`.
+ *
+ * Design invariants:
+ *   - Idempotent: re-running install does not create duplicate entries.
+ *   - Atomic: every write goes through a tempfile + rename (POSIX atomic on
+ *     same filesystem). A SIGTERM mid-install leaves the target in either
+ *     pre-state or post-state — never half-written.
+ *   - Fail-safe: malformed existing JSON aborts without mutating the file;
+ *     the error surfaces with line/column pointer.
+ *   - Targeted: a `__distill_version` sentinel field on our hook entry makes
+ *     uninstall precise (we remove only what we wrote). Path-equality on the
+ *     `command` field is a secondary fallback, in case an upstream Zod parse
+ *     strips the sentinel when Claude Code rewrites settings.
+ *
+ * Per project convention (CLAUDE.md: "Manual process.argv parsing in
+ * bin/cli.js"), this module pulls in no new runtime dependencies.
+ */
+export interface PrecompactOptions {
+    /** Root dir containing `.claude/` (defaults to OS HOME). Used by tests. */
+    userDir?: string;
+    /** Print intended changes without mutating the filesystem. */
+    dryRun?: boolean;
+}
+export interface PrecompactResult {
+    action: "installed" | "uninstalled" | "noop" | "dry-run" | "aborted";
+    /** Absolute path to the settings file that was (or would be) touched. */
+    settingsPath: string;
+    /** Human-readable message for CLI output. */
+    message: string;
+    /** Non-empty when `action === "aborted"`. */
+    errorCode?: "malformed-json" | "permission-denied" | "unknown";
+}
+interface BashCommandHook {
+    type: "command";
+    command: string;
+    [key: string]: unknown;
+}
+interface HookMatcher {
+    matcher?: string;
+    hooks: BashCommandHook[];
+    [key: string]: unknown;
+}
+interface SettingsShape {
+    hooks?: {
+        PreCompact?: HookMatcher[];
+        [event: string]: HookMatcher[] | undefined;
+    };
+    [key: string]: unknown;
+}
+type ReadResult = {
+    state: "missing";
+} | {
+    state: "malformed";
+    error: {
+        line: number;
+        column: number;
+        message: string;
+    };
+} | {
+    state: "ok";
+    data: SettingsShape;
+};
+export declare const DISTILL_SENTINEL_KEY = "__distill_version";
+/**
+ * Absolute path to the shipped PreCompact hook script. Resolves from the
+ * compiled `dist/cli/precompact.js` (or `src/cli/precompact.ts` under vitest)
+ * up to the package root — both layouts are `<pkg>/<dist|src>/cli/` so two
+ * `..` hops land at the root where `scripts/` lives.
+ */
+export declare function getHookScriptPath(): string;
+/**
+ * Returns the `major.minor.x` sentinel derived from the current
+ * `package.json` version. Example: package 0.10.3 → "0.10.x".
+ */
+export declare function getHookSentinelVersion(): string;
+export declare function getSettingsPath(userDir?: string): string;
+/**
+ * Read settings.json with discriminated result. Does NOT swallow JSON parse
+ * errors (unlike `readJSONFile` in utils.ts) — malformed files report
+ * line/column so the caller can surface a clear abort message.
+ */
+export declare function readSettingsStrict(filePath: string): ReadResult;
+/**
+ * Atomic write: tempfile (mode 0600) in the target's directory → rename to
+ * target → chmod to final mode. POSIX guarantees rename atomicity on the
+ * same filesystem. A SIGTERM mid-call leaves either pre-state or post-state.
+ *
+ * Parent directory is created (0755) if missing. Exported for testability —
+ * the install/uninstall paths call this internally.
+ */
+export declare function writeAtomic(filePath: string, content: string, finalMode?: number): void;
+export declare function installPrecompactHook(opts?: PrecompactOptions): PrecompactResult;
+export declare function uninstallPrecompactHook(opts?: PrecompactOptions): PrecompactResult;
+export {};
+//# sourceMappingURL=precompact.d.ts.map

package/dist/cli/precompact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"precompact.d.ts","sourceRoot":"","sources":["../../src/cli/precompact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAaH,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,WAAW,GAAG,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IACrE,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,gBAAgB,GAAG,mBAAmB,GAAG,SAAS,CAAC;CAChE;AAED,UAAU,eAAe;IACvB,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,UAAU,WAAW;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,UAAU,aAAa;IACrB,KAAK,CAAC,EAAE;QACN,UAAU,CAAC,EAAE,WAAW,EAAE,CAAC;QAC3B,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,GAAG,SAAS,CAAC;KAC5C,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,KAAK,UAAU,GACX;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,GACpB;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAChF;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAMzC,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAExD;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAG1C;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAM/C;AAED,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAGxD;AAMD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CA8B/D;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,SAAQ,GAAG,IAAI,CAoBtF;AAmCD,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,iBAAsB,GAAG,gBAAgB,CA4DpF;AAED,wBAAgB,uBAAuB,CAAC,IAAI,GAAE,iBAAsB,GAAG,gBAAgB,CA2FtF"}