Skip to content

v1.5.1 — H2 & Verification Pipeline(breaking change!)

Choose a tag to compare

View all tags
@Nefrols Nefrols released this 14 Feb 00:40
· 20 commits to main since this release
v1.5.1
8fca90b

Release Notes

Language / Язык: English | Русский

What's New

Session → Task: Concept Rename (Breaking API Change)

The entire API has been migrated from "session" to "task" terminology across 84 files:

Before After
SessionContext TaskContext
SessionTransactionManager TaskTransactionManager
SessionLineAccessTracker TaskLineAccessTracker
SessionSearchTracker TaskSearchTracker
SessionTool (session package) TaskTool (task package)
TaskTool (system package) ProcessTool (system package)
nts_session nts_task
sessionId taskId

Why: "Task" better reflects the isolated unit of work with its own undo history, checkpoints, and token registry.

H2 Database Persistence

Transaction journal storage migrated from JSON files to embedded H2 database:

  • JournalDatabase — connection pool and schema management
  • JournalRepository — CRUD operations for journal entries
  • Survives server restarts with full transaction history
  • Eliminates JSON serialization overhead and file corruption risks

SmartUndoEngine: In-Memory Snapshots

Undo engine migrated from file-based backups (Map<Path,Path>) to in-memory byte[] snapshots (Map<Path,byte[]>):

  • Faster undo/redo operations (no disk I/O for snapshots)
  • Reduced temporary file clutter
  • File lineage tracking preserved for move/rename recovery

New Tool: nts_verify — Multi-Level Validation

Verification tool with three levels of code correctness checking:

Action Description
syntax Fast tree-sitter AST check (no build needed)
compile Run gradlew build -x test for compilation
test Run gradlew test for full test validation

Powered by SyntaxChecker — tree-sitter based AST parsing for instant syntax validation.

New Tool: nts_workspace_status — Context Recovery

Compact workspace summary for agent re-orientation after context compression:

  • Current task ID and stats
  • TODO progress (if active)
  • Recently modified files
  • Recent journal entries (last 5 operations)
  • Suggested next action

New Tool: nts_process — Background Process Management

Monitor and control long-running background processes:

Action Description
log Retrieve output from async process
kill Terminate running process

Works with nts_gradle_task and nts_git async operations.

EditFileTool: Auto Syntax Verification

After every edit, the tool automatically runs tree-sitter syntax check on the modified file. If syntax errors are detected, the response includes a warning with error details — agent catches mistakes immediately without a separate verification step.

LineAccessTracker: File CRC Token Invalidation

Tokens now track file CRC (fileCrc) in addition to range CRC:

  • registerAccess() requires mandatory fileCrc parameter
  • External file changes invalidate tokens even if the edited range hasn't changed
  • Per-symbol tokens in CodeNavigateTool for precise invalidation

EncodingUtils: ICU4J Multi-Level Detection

Encoding detection migrated from basic charset detection to ICU4J with multi-level strategy:

  1. BOM detection (UTF-8/16/32)
  2. ICU4J CharsetDetector with confidence scoring
  3. Fallback to system default

Handles CRLF normalization, Unicode BOM stripping, and charset-aware text comparison.

TodoTool Enhancements

  • New actions: items and all_items for structured JSON responses
  • FOCUS hint — reminds agent of the current active task
  • Verify reminder — prompts to verify after completing edits
  • Role-aware suggestions — different tips for different agent roles

GradleTool: Project Initialization

  • init action — generate Gradle wrapper for new projects
  • System Gradle fallback when wrapper not present
  • Improved error messages with actionable suggestions

TipFilter: Role-Aware Filtering

Smart contextual tips now filtered based on agent role via ntsAllowedTools:

  • Workers see execution-focused tips
  • Architects see planning tips
  • Scouts see exploration tips

API Consistency Improvements

  • isInternal() method on McpTool — marks tools hidden from external tools/list
  • includeInternal parameter in listTools — allows orchestrator to see all tools
  • ntsAllowedTools metadata — restricts which tools are visible per agent role
  • Lazy Root Refresh in PathSanitizer — retries root resolution on access denial
  • ObjectMapper → JsonMapper.builder() in McpIntegrator

NtsErrorCode: Placeholder Interpolation

Error messages now support %placeholder% interpolation:

TOKEN_EXPIRED: "Token expired for %path%. File was modified externally."

Placeholders are resolved at error creation time with actual values.

Search Improvements

  • BOM-aware text search — handles files with byte order marks
  • CRLF-normalized comparison — consistent matching across line endings
  • Unicode Boyer-Moore-Horspool — optimized for multi-byte characters
  • Encoding-aware containsText — correct matching regardless of file encoding

PathSanitizer: Lazy Root Refresh

When a path access is denied, the sanitizer now retries with refreshed roots before failing — handles cases where roots are updated after server startup.

FileReadTool: Directory Validation

executeRead and executeInfo now validate that the path is a file, not a directory, before attempting to read — prevents confusing error messages.

BatchToolsTool: Copy Path Fix

Fixed path resolution for copy action in nts_file_manage — the destination path is now correctly resolved in batch variable interpolation.

Documentation Updates

README.md

Both English and Russian sections updated:

  • Tool count badge: 15 → 17
  • Server name: NTS-FileSystem → NTS-FileSystem-MCP in all config examples
  • New tools documented: nts_verify, nts_workspace_status, nts_process
  • Refactoring operations: 6 → 10 (added Extract Variable, Wrap, Move, Delete, Batch)
  • Client integrations: 7 clients (Gemini CLI, Claude Code, Qwen CLI, Cursor, LM Studio, Antigravity, Copilot VS Code)
  • Session → Task terminology migration
  • H2 Database persistence documentation
  • In-memory snapshots for undo engine
  • MCP_LOG_FILE environment variable for Docker
  • Discipline loop diagrams updated with Verify and Workspace Status

Breaking Changes

API Migration: Session → Task

Change Impact
sessionId → taskId All nts_init calls must use taskId parameter
nts_session → nts_task Tool name changed
SessionTool → TaskTool Package moved from session to task
TaskTool (old, system) → ProcessTool Background process tool renamed to avoid collision

Migration: Replace sessionId with taskId in all client configurations and API calls.

H2 Database Replaces JSON Journal

  • Old journal.json files are not auto-migrated
  • New tasks use H2 storage automatically
  • Existing task directories with journal.json will start with clean journal state

Upgrade Notes

  1. Update client integrations to use taskId instead of sessionId
  2. The server name in MCP configs is now NTS-FileSystem-MCP
  3. Old JSON journal files can be safely deleted after upgrading
  4. No changes to Docker configuration required

Stats

Metric Value
Commits in release 19
Files changed 89
Lines added +7,148
Lines removed -3,007
Net change +4,141

Примечания к релизу (RU)

Новые возможности

Session → Task: Переименование концепции (Ломающее изменение API)

Весь API мигрирован с терминологии «сессия» на «задача» в 84 файлах:

Было Стало
SessionContext TaskContext
SessionTransactionManager TaskTransactionManager
SessionLineAccessTracker TaskLineAccessTracker
SessionSearchTracker TaskSearchTracker
SessionTool (пакет session) TaskTool (пакет task)
TaskTool (пакет system) ProcessTool (пакет system)
nts_session nts_task
sessionId taskId

Зачем: «Задача» точнее отражает изолированную единицу работы с собственной историей undo, чекпоинтами и реестром токенов.

Персистентность на H2 Database

Хранилище журнала транзакций мигрировано с JSON-файлов на встроенную H2 базу данных:

  • JournalDatabase — пул соединений и управление схемой
  • JournalRepository — CRUD-операции для записей журнала
  • Переживает перезапуски сервера с полной историей транзакций
  • Устраняет накладные расходы JSON-сериализации и риски повреждения файлов

SmartUndoEngine: In-Memory снапшоты

Движок отката мигрирован с файловых бэкапов (Map<Path,Path>) на in-memory byte[] снапшоты (Map<Path,byte[]>):

  • Быстрые операции undo/redo (без дискового I/O для снапшотов)
  • Меньше временных файлов
  • Отслеживание родословной файлов для восстановления после move/rename сохранено

Новый инструмент: nts_verify — Многоуровневая валидация

Инструмент верификации с тремя уровнями проверки корректности кода:

Действие Описание
syntax Быстрая проверка AST через tree-sitter (без сборки)
compile Запуск gradlew build -x test для проверки компиляции
test Запуск gradlew test для полной проверки тестами

Работает на основе SyntaxChecker — парсинг AST через tree-sitter для мгновенной валидации синтаксиса.

Новый инструмент: nts_workspace_status — Восстановление контекста

Компактная сводка рабочего пространства для переориентации агента после сжатия контекста:

  • ID текущей задачи и статистика
  • Прогресс TODO (если активен)
  • Недавно изменённые файлы
  • Последние записи журнала (5 операций)
  • Предложение следующего действия

Новый инструмент: nts_process — Управление фоновыми процессами

Мониторинг и управление долгими фоновыми процессами:

Действие Описание
log Получить вывод асинхронного процесса
kill Остановить работающий процесс

Работает с асинхронными операциями nts_gradle_task и nts_git.

EditFileTool: Автоматическая проверка синтаксиса

После каждой правки инструмент автоматически запускает проверку синтаксиса через tree-sitter. Если обнаружены ошибки синтаксиса, ответ включает предупреждение с деталями — агент ловит ошибки мгновенно без отдельного шага верификации.

LineAccessTracker: Инвалидация токенов по CRC файла

Токены теперь отслеживают CRC файла (fileCrc) в дополнение к CRC диапазона:

  • registerAccess() требует обязательный параметр fileCrc
  • Внешние изменения файла инвалидируют токены, даже если изменённый диапазон не затронут
  • Per-symbol токены в CodeNavigateTool для точной инвалидации

EncodingUtils: ICU4J многоуровневая детекция

Определение кодировки мигрировано на ICU4J с многоуровневой стратегией:

  1. Детекция BOM (UTF-8/16/32)
  2. ICU4J CharsetDetector с оценкой уверенности
  3. Fallback на системную кодировку по умолчанию

Обработка нормализации CRLF, удаления Unicode BOM, сравнения текста с учётом кодировки.

Улучшения TodoTool

  • Новые действия: items и all_items для структурированных JSON-ответов
  • FOCUS hint — напоминает агенту о текущей активной задаче
  • Verify reminder — предлагает проверить после завершения правок
  • Role-aware подсказки — разные советы для разных ролей агентов

GradleTool: Инициализация проектов

  • Действие init — генерация Gradle wrapper для новых проектов
  • Fallback на системный Gradle при отсутствии wrapper
  • Улучшенные сообщения об ошибках с предложениями действий

TipFilter: Role-aware фильтрация

Умные контекстные подсказки теперь фильтруются на основе роли агента через ntsAllowedTools:

  • Workers видят подсказки по выполнению
  • Architects видят подсказки по планированию
  • Scouts видят подсказки по исследованию

Консистентность API

  • Метод isInternal() в McpTool — скрывает инструменты из внешнего tools/list
  • Параметр includeInternal в listTools — позволяет оркестратору видеть все инструменты
  • Метаданные ntsAllowedTools — ограничивает видимость инструментов по роли агента
  • Ленивое обновление Roots в PathSanitizer — повторная попытка при отказе в доступе
  • ObjectMapper → JsonMapper.builder() в McpIntegrator

NtsErrorCode: Интерполяция плейсхолдеров

Сообщения об ошибках теперь поддерживают интерполяцию %placeholder%:

TOKEN_EXPIRED: "Token expired for %path%. File was modified externally."

Плейсхолдеры подставляются при создании ошибки с реальными значениями.

Улучшения поиска

  • Поиск с учётом BOM — корректная обработка файлов с byte order mark
  • Нормализация CRLF — единообразное совпадение вне зависимости от окончаний строк
  • Unicode Boyer-Moore-Horspool — оптимизация для многобайтовых символов
  • containsText с учётом кодировки — корректное совпадение независимо от кодировки файла

PathSanitizer: Ленивое обновление Roots

При отказе в доступе к пути sanitizer теперь обновляет roots и повторяет попытку — обрабатывает случаи, когда roots обновлены после старта сервера.

FileReadTool: Валидация директорий

executeRead и executeInfo теперь проверяют, что путь указывает на файл, а не директорию — предотвращает непонятные сообщения об ошибках.

BatchToolsTool: Исправление пути копирования

Исправлено разрешение path для действия copy в nts_file_manage — путь назначения теперь корректно подставляется при интерполяции переменных батча.

Обновления документации

README.md

Обе версии (EN и RU) обновлены:

  • Бейдж инструментов: 15 → 17
  • Имя сервера: NTS-FileSystem → NTS-FileSystem-MCP во всех конфигурациях
  • Документированы новые инструменты: nts_verify, nts_workspace_status, nts_process
  • Операции рефакторинга: 6 → 10 (добавлены Extract Variable, Wrap, Move, Delete, Batch)
  • Интеграция клиентов: 7 клиентов (Gemini CLI, Claude Code, Qwen CLI, Cursor, LM Studio, Antigravity, Copilot VS Code)
  • Миграция терминологии Session → Task
  • Документация персистентности H2 Database
  • In-memory снапшоты для движка отката
  • Переменная окружения MCP_LOG_FILE для Docker
  • Диаграммы цикла дисциплины обновлены с Verify и Workspace Status

Ломающие изменения

Миграция API: Session → Task

Изменение Влияние
sessionId → taskId Все вызовы nts_init должны использовать параметр taskId
nts_session → nts_task Имя инструмента изменено
SessionTool → TaskTool Пакет перемещён из session в task
TaskTool (старый, system) → ProcessTool Инструмент фоновых процессов переименован во избежание коллизии

Миграция: Замените sessionId на taskId во всех клиентских конфигурациях и API-вызовах.

H2 Database заменяет JSON-журнал

  • Старые файлы journal.json не мигрируются автоматически
  • Новые задачи используют H2 хранилище автоматически
  • Существующие директории задач с journal.json начнут с чистого состояния журнала

Примечания по обновлению

  1. Обновите клиентские интеграции — используйте taskId вместо sessionId
  2. Имя сервера в MCP-конфигурациях теперь NTS-FileSystem-MCP
  3. Старые JSON-файлы журнала можно безопасно удалить после обновления
  4. Изменения в Docker-конфигурации не требуются

Статистика

Метрика Значение
Коммитов в релизе 19
Файлов изменено 89
Строк добавлено +7 148
Строк удалено -3 007
Нетто-изменение +4 141
Assets 3
Loading