v0.10.1 — code_execute no-return fix + skeleton async dedup

[0.10.1] — 2026-04-22

Patch release — pre-release smoke-test fixes. Two user-facing bugs surfaced
during the v0.10.0 release verification pass, both fixed with regression tests.
No API or contract changes.

Fixed

• code_execute now handles code without an explicit return.
  executeSandbox used to crash with "Cannot read properties of undefined (reading 'match')" when user code had no return value (e.g.
  console.log("hi")). Root cause: JSON.stringify(undefined) returns
  literal undefined (not a string), which then broke
  tiktoken.encode(undefined) inside countTokens. The executor now guards
  the serialization step with ?? "" and skips token counting for empty
  output — so console.log-only scripts (and empty strings) resolve cleanly
  with success: true, tokensUsed: 0, and output "(no output)".
  (src/sandbox/executor.ts:152-153.)
• smart_file_read skeleton no longer emits async async on TypeScript
  functions. The TS signature builder already prefixes async in the
  signature string, but the skeleton renderer used to prepend it a second
  time, producing export async async createServer(...). The renderer now
  checks for a pre-existing \basync\b in the signature before adding the
  modifier. Affects both top-level functions and class methods.
  (src/tools/smart-file-read.ts:395-414.)

Tests

• sandbox.test.ts — new regression test: console.log-only code returns
  success: true with tokensUsed: 0.
• smart-file-read.test.ts — new regression assertion: skeleton output never
  contains /async\s+async/.
• code-execute.test.ts — updated "should handle empty code string gracefully" to assert the new (correct) behaviour: empty code executes as
  a no-op and succeeds.
• Total: 1203 passing (1 skipped) across 46 files. Coverage held within the
  v0.9.2 floors (lines 72.13%, branches 58.62%, functions 73.46%,
  statements 71.32%).

---

v0.10.0 — claude-code alignment (19-story PRD)

[0.10.0] — 2026-04-22

Correctness + native-integration release. Zero changes to the three
tools' contracts (auto_optimize, smart_file_read, code_execute). Zero
changes to the sandbox engine, the AST parsers, or the compression
algorithms. Closes the 19-story v0.10 PRD
(tasks/prd-distill-v010-claude-code-alignment.md), derived from a 5-agent
exploration of /home/arthur/dev/claude-code/ that surfaced four documented
misunderstandings of how Claude Code actually consumes MCP tools and three
high-leverage integration points that Distill was not using.

This is the first release to hit npm since v0.8.1. It consolidates the
previously-draft v0.9.1 and v0.9.2 work (below) into a single published
version; nothing was dropped from those drafts.

Documentation correctness (EP-001)

Every claim below is backed by a claude-code/<path>:<line> citation so
future maintainers can re-verify against a moving upstream in one pass.

• MCP persistence threshold corrected. CLAUDE.md previously claimed
  "tool results > 50K chars are persisted to disk"; the real constraint is
  DEFAULT_MAX_MCP_OUTPUT_TOKENS = 25_000 at
  claude-code/utils/mcpValidation.ts:16, gated by the length/4
  heuristic at :151-163 (≈ 12 500 tokens ≈ 50K chars). Distill's 45K-char
  internal cap survives the heuristic gate by design. (US-001.)
• Autocompact formula corrected. The reserved-tokens value is
  min(maxOutputTokens, 20_000), not a hard-coded 20K —
  claude-code/services/compact/autoCompact.ts:33-48. Haiku's
  max_output = 4 096 therefore gives a higher trigger threshold
  (≈ 91.5%) than Sonnet/Opus (≈ 83.5%). (US-002.)
• outputSchema claim retired. The obsolete Issue #25081 reference is
  replaced with the actual behaviour: outputSchema is silently ignored
  during the tools/list → internal Tool mapping at
  claude-code/services/mcp/client.ts:1754-1813 (neither dropped nor
  rejected — the field is simply not copied). (US-003.)
• Citation appendix added to CLAUDE.md. Eleven verified mechanisms
  (alwaysLoad / searchHint / outputSchema / MCP persistence / autocompact /
  structuredContent drop / PreCompact hook / MCP prompts / custom agent
  loading / readOnlyHint / MCP skills) each pin to a
  claude-code/<path>:<line> anchor with a one-liner reverify script.
  (US-004.)

Code alignment cleanup (EP-002)

• structuredContent removed from the CallTool wire response. The
  three tools still populate it on their internal ToolResult for test
  assertions and non-Claude-Code MCP clients, but server.ts no longer
  emits it. Claude Code stashes structuredContent in mcpMeta and
  explicitly excludes mcpMeta from Anthropic-API blocks — so sending it
  on the wire was pure bandwidth cost for zero model-side value. (US-005.)
• searchHints map deleted from server.ts. The
  anthropic/searchHint key is rendered only for deferred MCP tools —
  Distill sets alwaysLoad: true on all three tools, so the hint was
  unreachable by construction. (US-006.)
• annotations: { readOnlyHint: true } declared on smart_file_read
  and auto_optimize (with matching title + destructiveHint: false +
  idempotentHint: true + openWorldHint: false). Claude Code maps
  readOnlyHint to isConcurrencySafe() at
  claude-code/services/mcp/client.ts:1795-1800, enabling parallel
  dispatch on multi-tool turns. code_execute declares
  readOnlyHint: false, destructiveHint: true — it can mutate via
  ctx.files and git. (US-007.)

PreCompact hook preset (EP-003)

• [DISTILL:COMPRESSED ratio=X.XX method=<name>] marker contract.
  Opt-in wire envelope that lets Claude Code's PreCompact hook preserve
  Distill-compressed regions verbatim during autocompact. Enabled via
  DISTILL_COMPRESSED_MARKERS=1. Thresholds per tool: auto_optimize
  savings ≥ 30%; smart_file_read output < 50% of source and mode ∈
  {skeleton, extract, search}; code_execute's ctx.compress.* helpers
  wrap under the same 30%-savings rule. Collision escape uses
  [DISTILL-USER-TEXT:COMPRESSED …] when the payload already contains
  the literal marker. (US-008.)
• packages/mcp-server/scripts/precompact-hook.sh — shipped
  POSIX-compliant hook that emits stdout guidance merged by Claude Code
  into newCustomInstructions (per
  claude-code/utils/hooks.ts:3991-4024). Exits 0 on every input shape
  (including malformed JSON and unexpected events) so it can never block
  compaction. shellcheck-clean. (US-009.)
• distill-mcp setup --install-precompact-hook — idempotent,
  atomic (tempfile + rename), with --dry-run, --uninstall-precompact-hook,
  and --user-dir=<path> for testing. Aborts on malformed
  ~/.claude/settings.json with a line/column pointer; never overwrites a
  broken file. A __distill_version sentinel on the hook entry enables
  targeted uninstall. (US-010.)
• End-to-end hook validation. Vitest integration test synthesises a
  PreCompact dispatch, pipes a hook-input JSON on stdin to the shipped
  script, and asserts the stdout shape + instruction text. Runs under
  CI's Ubuntu runner to validate POSIX-only shell. (US-011.)

MCP prompts as slash commands (EP-004)

• Three prompts registered via prompts/list:
  /mcp__distill-mcp__compress-session,
  /mcp__distill-mcp__analyze-tokens,
  /mcp__distill-mcp__forget-large-results. Zero-argument by design;
  zero token overhead when unused (prompts are lazy-loaded by Claude
  Code, not injected into the system prompt). Naming convention per
  claude-code/services/mcp/client.ts:2043-2060. (US-012.)
• Vitest coverage on the prompt handlers — every happy and unhappy
  path including the MCP "unknown prompt" error code. (US-013.)
• User docs (apps/web, fr + en) describing each slash command,
  when to use it, and the expected model behaviour. (US-014.)

Custom agent preset (EP-005)

• packages/mcp-server/assets/agents/distill-compressor.md — a
  read-only subagent template with name, description, tools
  (Read, Grep, Glob, Bash + auto_optimize + smart_file_read),
  disallowedTools (code_execute), and requiredMcpServers
  (distill-mcp). Body covers content-aware compression, AST-based
  skeleton reads, summarization of long outputs, and the
  [DISTILL:COMPRESSED] marker contract. (US-015.)
• distill-mcp setup --install-agent — copies the template into
  ~/.claude/agents/ with mode 0644, creates ~/.claude/agents/
  (0755) if missing, uses atomic tempfile + rename. Idempotent,
  --dry-run-aware, with --uninstall-agent and diff-preview on
  existing differing file (requires --force to overwrite). (US-016.)

MCP skills R&D spike (EP-006)

• docs/spikes/mcp-skills-exposure.md — verdict: NO-GO. A
  single-session source-and-binary audit established that external
  MCP servers cannot produce commands with loadedFrom === 'mcp' on
  the currently-shipped Claude Code. Three independent lines of
  evidence: (1) all call sites gated by feature('MCP_SKILLS') from
  bun:bundle at services/mcp/client.ts:117-121, :2174, :2348,
  (2) the producer module skills/mcpSkills.ts is absent from the
  public source tree and conditionally compiled only when the flag is
  true, (3) the installed binary v2.1.117 has zero matches for
  MCP_SKILLS, fetchMcpSkills, getMcpSkillCommands, or
  registerMCPSkill. The spike report documents four upstream
  preconditions that would flip the decision to GO plus three
  strings-based re-verification commands. v0.11 does not include
  MCP skills. (US-017.)

Release coordination (EP-007)

• Version bump from 0.8.1 to 0.10.0. The two [Unreleased]
v0.9.1 and v0.9.2 sections below are rolled into this release —
  every bullet there shipped under 0.10.0. (US-018.)
• PostToolUse matcher docs. The apps/web hooks page now shows
  a "matcher": "mcp__distill-mcp__*" example for auditing or
  post-processing Distill tool calls, referencing the
  updatedMCPToolOutput return channel per
  claude-code/schemas/hooks.ts:19-27. (US-019.)

Upgrade notes

• No migration required. The three tool signatures and output shapes
  are unchanged. The marker contract, the PreCompact hook, the slash
  commands, and the custom agent are all opt-in — existing v0.8.x /
  v0.9.x integrators keep vanilla behaviour.
• structuredContent no longer travels on the MCP wire (US-005). It was
  already dropped before reaching the Anthropic API by Claude Code itself
  (mcpMeta is excluded from API blocks), so no consumer of Claude Code
  loses information. Non-Claude-Code MCP clients that read
  structuredContent via the SDK surface can still do so via the
  ToolResult returned by the internal registry (kept for tests and
  SDK-level integrations).
• Coverage floors ratchet to v0.9.2 baseline −1 pt: Lines 70% / Branches
  56% / Functions 70% / Statements 69%. Current: Lines 72.15 / Branches
  58.6 / Functions 73.48 / Statements 71.34.

---

v0.8.1

🚀 What's New in v0.8.1

CLI Setup Improvements

• Interactive setup no longer pre-selects IDEs - Users now explicitly choose which IDEs to configure instead of having detected ones pre-selected
• CLAUDE.md auto-update - When configuring Claude Code, the setup now automatically adds Distill MCP directives to your existing CLAUDE.md file
  • Requires CLAUDE.md to exist (run /init in Claude Code first)
  • Includes comprehensive SDK documentation in French

IDE Configuration Updates

• Cursor: Now uses npx -y distill-mcp serve (recommended by Cursor docs)
• Windsurf: Now uses npx -y distill-mcp serve (recommended by Windsurf docs)
• Antigravity: Now uses npx -y distill-mcp serve for consistency
• Claude Code: Keeps direct distill-mcp serve command

The npx -y format ensures the package is always available even without global installation.

Documentation

• Updated installation guides for all IDEs (FR/EN)
• Updated CLAUDE.md setup guide with new CLI workflow
• Clarified that /init must be run before setup can update CLAUDE.md

📦 Installation

npm install -g distill-mcp
distill-mcp setup

🔗 Links

• Documentation
• npm package

Distill v0.8.0

Distill v0.8.0 - Release Notes

Vue d'ensemble

Cette version majeure apporte des améliorations significatives sur trois axes principaux : l'analyse de code AST, la sécurité et robustesse du SDK sandbox, et l'intelligence du résumé de logs. Plus de 6 700 lignes de code ajoutées pour une expérience plus fiable et performante.

---

Parsing AST enrichi pour 6 langages

Nouvelles capacités d'extraction

Le parsing de code est maintenant considérablement plus détaillé. Pour tous les langages supportés (TypeScript, Python, Go, Rust, PHP, Swift), l'extraction inclut désormais :

• Visibilité et modificateurs : public/private/protected, static, abstract, final
• Génériques et paramètres de type : support complet des types génériques avec contraintes
• Paramètres détaillés : types, valeurs par défaut, paramètres optionnels, rest parameters
• Décorateurs et attributs : extraction des annotations et métadonnées du code
• Enums : nouveau type d'élément extrait (auparavant manquant)

Améliorations par langage

Rust : Support des lifetimes, clauses where, fonctions async/unsafe/const, attributs #[derive(...)], et ABI extern.

Swift : Support de Swift 6+ avec actors distribués, async/await, Sendable, typed throws, @MainActor, et le nouveau niveau d'accès package.

Python : Extraction améliorée des décorateurs, annotations de type, et classes avec héritage multiple.

Go : Meilleure gestion des interfaces, méthodes de receiver, et types embarqués.

PHP : Support des traits, interfaces, et namespaces amélioré.

---

SDK Sandbox renforcé

Gestion d'erreurs type-safe avec neverthrow

Toutes les API du SDK retournent maintenant des types Result<T, Error> au lieu de lever des exceptions. Cela permet :

• Prévisibilité : Impossible d'oublier de gérer une erreur - le compilateur vous rappelle à l'ordre
• Composition : Chaînage d'opérations avec gestion d'erreurs intégrée
• Rétrocompatibilité : Les anciennes API "legacy" qui lèvent des exceptions restent disponibles

Types marqués (Branded Types)

Introduction de types marqués pour la sécurité à la compilation :

• ValidatedPath : Chemin de fichier validé contre les traversées de répertoire
• SafePattern : Pattern glob vérifié comme sûr
• SanitizedGitArg : Argument git nettoyé contre l'injection de commandes
• SanitizedCode : Code utilisateur ayant passé l'analyse de sécurité

Ces types garantissent au niveau du compilateur TypeScript qu'une valeur a été validée avant utilisation.

Ressources avec nettoyage automatique (Disposables)

Utilisation du nouveau pattern using de TypeScript 5.2+ pour la gestion automatique des ressources :

• Les timers d'exécution sont automatiquement nettoyés
• Les sandboxes libèrent leurs ressources même en cas d'erreur
• Code plus propre et moins de fuites de ressources

Mode QuickJS (expérimental)

Nouveau mode d'exécution optionnel utilisant WebAssembly pour une isolation complète :

• Sandbox véritablement isolée du processus Node.js
• Activable via DISTILL_USE_QUICKJS=true
• Plus sécurisé pour les cas d'usage sensibles

---

Résumé de logs intelligent

Scoring multi-facteurs

Nouveau système de scoring inspiré de BM25/TF-IDF qui prend en compte :

• Niveau de log : Erreurs pondérées plus fortement que les warnings et infos
• Unicité du contenu : Logs uniques valorisés par rapport aux répétitions
• Position : Début et fin de session considérés plus importants
• Rareté : Patterns inhabituels mis en avant

Clustering sémantique

Regroupement automatique des logs similaires :

• Détection de patterns récurrents (ex: "Connection failed to X")
• Sélection du représentant le plus pertinent par cluster
• Réduction significative de la redondance dans les résumés

Extraction de patterns

Identification automatique des templates de logs avec variables :

• Conversion de messages en patterns génériques (ex: Error connecting to <IP>:<PORT>)
• Statistiques sur la fréquence de chaque pattern
• Aide à identifier les problèmes récurrents

Résumé hiérarchique

Nouveau mode de résumé pour les fichiers volumineux :

• Découpage temporel ou par taille en sections
• Résumé de chaque section puis agrégation
• Vision multi-niveaux : vue d'ensemble, sections, entrées critiques

---

Conformité MCP 2025-06-18

Output Schemas

Tous les outils principaux incluent maintenant des schémas de sortie conformes à la spécification MCP 2025-06-18 :

• Validation structurée : Les résultats sont validés contre un schéma défini
• Documentation automatique : Chaque champ de sortie est documenté avec sa description et son type
• Interopérabilité : Meilleure intégration avec les clients MCP conformes

Outils mis à jour : auto_optimize, smart_file_read, discover_tools, code_execute, session_stats, summarize_logs.

Annotations d'outils

Nouveau système d'annotations pour guider les LLMs dans l'utilisation des outils :

• readOnlyHint : Indique que l'outil ne modifie pas l'état du système
• destructiveHint : Avertit des opérations potentiellement destructives
• idempotentHint : Signale que le même input produit toujours le même résultat
• longRunningHint : Prévient que l'exécution peut être longue
• title : Titre lisible pour l'affichage dans les interfaces

Descriptions sémantiques

Les schémas d'entrée incluent maintenant des descriptions détaillées pour chaque propriété :

• Amélioration de la sélection automatique d'outils par les LLMs
• Documentation inline des paramètres avec valeurs par défaut
• Contraintes de validation (minLength, minimum, maximum)

Registre d'outils étendu

Le ToolRegistry supporte maintenant :

• outputSchema optionnel pour chaque outil
• annotations pour les métadonnées comportementales
• Sérialisation complète dans la réponse ListTools

---

Pipeline Builder fluide

Nouvelle API chaînable pour les opérations multi-étapes :

• Interface immutable et type-safe
• Méthodes fluides : glob(), read(), parse(), filter(), map(), compress()
• Présets pour cas courants : analyse de code mort, extraction de signatures

---

Nouvelles dépendances

• neverthrow : Gestion d'erreurs fonctionnelle type-safe
• @jitl/quickjs-ng-wasmfile-release-sync : Sandbox QuickJS WebAssembly
• @sebastianwessel/quickjs : Bridge hôte pour QuickJS

---

Changements notables

• L'option detailed du parsing est maintenant dépréciée - l'extraction détaillée est toujours activée pour une meilleure qualité d'AST
• Les API retournant des Result sont la nouvelle norme ; les versions "legacy" qui lèvent des exceptions restent disponibles pour la rétrocompatibilité

---

Note : Cette release est un travail en cours. D'autres améliorations sont prévues avant la version finale 0.8.0.

v0.7.0-beta - Interactive Setup Wizard & Antigravity Support

What's New

Interactive Setup Wizard

distill-mcp setup now launches a beautiful interactive wizard powered by @clack/prompts:

• Select multiple IDEs with arrow keys and spacebar
• Auto-detects installed IDEs and pre-selects them
• Optional Claude Code hooks installation
• Spinner feedback during configuration

Antigravity (Google) Support

Added support for Google's Antigravity IDE alongside Claude Code, Cursor, and Windsurf.

distill-mcp setup --antigravity  # Non-interactive mode

Backward Compatibility

All existing flags continue to work for non-interactive/scripted setups:

• --claude, --cursor, --windsurf, --antigravity
• --hooks, --force

Installation

npm install -g distill-mcp
distill-mcp setup

Full Changelog

v0.6.0-beta...v0.7.0-beta

v0.6.0-beta - All Phases Complete

Distill v0.6.0-beta

Extract the essence. Compress the context. Save tokens.

Distill is an open-source MCP server for LLM token optimization. Works with Claude Code, Cursor, and Windsurf.

Installation

# Run directly
npx distill-mcp

# Or install globally
npm install -g distill-mcp

# Add to Claude Code
claude mcp add distill -- npx distill-mcp

What's New

This beta release marks the completion of all 6 development phases.

Phase 1: Core Stability

• auto_optimize - Auto-detect and compress (40-95% savings)
• smart_file_read - AST-based file reading (50-70% savings)
• code_execute - TypeScript SDK execution (98% savings)
• Support for 7 languages: TypeScript, JavaScript, Python, Go, Rust, PHP, Swift

Phase 2: Smart Search

• BM25 keyword search for tool discovery
• Semantic search with local embeddings (all-MiniLM-L6-v2)
• Hybrid search combining both approaches

Phase 3: SDK Enhancement

• ctx.git.* - Git operations (diff, log, blame, status)
• ctx.search.* - Code search (grep, symbols, files)
• ctx.analyze.* - Static analysis (dependencies, callGraph)
• ctx.pipeline - Composable data pipelines

Phase 4: Intelligence Layer

• context_budget - Pre-flight token estimation
• detect_retry_loop - Failure pattern detection
• session_stats - Usage analytics and cost tracking

Phase 5: Ecosystem Integration

• One-click setup for Claude Code, Cursor, Windsurf
• GitHub Action for CI/CD token analysis
• Pre-commit hooks for large file warnings
• CLI analyze command

Phase 6: Advanced Compression

• multifile_compress - Cross-file deduplication
• conversation_memory - Long conversation summarization
• TOON format output optimization
• Configurable verbosity levels

Test Results

• 437 tests passing
• TypeScript type checking clean
• Build successful

Known Limitations

• Test coverage at ~21% (expanding in next releases)
• Some ESLint warnings in web app (Three.js properties)

Links

• npm: https://www.npmjs.com/package/distill-mcp
• GitHub: https://github.com/ArthurDEV44/ctxopt