Skip to content

v1.2.2 — Transaction Journal Persistence & Smart TIPS

Choose a tag to compare

View all tags
@Nefrols Nefrols released this 15 Jan 18:17
· 40 commits to main since this release
v1.2.2
9ae30b1

Release Notes

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

What's New

Transaction Journal Persistence

Undo/redo history is now persisted to disk in JSON format, ensuring no data loss on server restarts:

{
  "version": 1,
  "sessionId": "713a6834-c90a-4645-b441-f25f97a75457",
  "counters": { "totalEdits": 5, "totalUndos": 2 },
  "undoStack": [
    {
      "type": "TRANSACTION",
      "timestamp": "2026-01-15T19:09:25",
      "description": "Edit file: src/main/java/com/test/User.java",
      "instruction": "Add @Entity annotation",
      "status": "COMMITTED",
      "snapshots": [{ "original": "src/main/java/com/test/User.java", "backup": "uuid.bak" }]
    }
  ],
  "redoStack": []
}

Key improvements:

  • Synchronous saving after every commit/undo/redo — fixes async thread race condition on JVM shutdown
  • Relative paths for file references — portable across different machines
  • Snapshot filenames only (uuid.bak) — session directory implicit, no redundant paths

Automatic Session Reactivation

Sessions now automatically restore from disk when the server restarts:

// SessionContext.getOrCreate() now checks disk first:
if (existsOnDisk(sessionId)) {
    ctx = new SessionContext(sessionId, meta.createdAt());
    ctx.transactionManager.loadJournal();  // Restore undo/redo stacks
    return ctx;
}

Reactivation via nts_init:

{ "sessionId": "your-previous-uuid" }

This restores:

  • Full undo/redo history from journal.json
  • Active TODO plan reference
  • Session metadata (creation time, last activity)

Note: File access tokens start fresh (re-read files before editing).

Enhanced TodoTool

New actions for complete task management workflow:

Action Description
create Start new plan with title and checklist
read View current plan (alias: status)
update Mark task done/failed or edit task text
add Append new task to current plan
close Archive completed plan (removes from HUD)
list Show all plans (active and archived)
reopen Reactivate an archived plan

New task text editing:

{ "action": "update", "id": 3, "text": "Updated task description" }

Synchronous Metadata Saving

Session metadata (session.meta) now saved synchronously, eliminating the saveMetadataAsync() virtual thread race condition.

Previous Release

LAT (Line Access Tracker) Improvements

Enhanced range overlap handling:

  • Complex overlapping range cases now handled correctly
  • Prevents CRC comparison errors in edge cases where multiple edits affect adjacent lines

Smart Tips for Tools

Added contextual tips to tool descriptions to guide LLM agents:

  • Optimal workflow suggestions
  • Common mistake prevention
  • Best practices for tool chaining

Bug Fixes

Journal Not Restoring After Reactivation (Critical)

Problem: After server restart, nts_init(sessionId="...") returned empty undo/redo stacks despite journal.json existing on disk.

Root cause: SessionContext.getOrCreate() didn't check disk for existing sessions. After JVM restart, the in-memory sessions map is empty, so it created a NEW empty context instead of reactivating from disk.

Fix: getOrCreate() now calls existsOnDisk() and loadJournal() when session directory exists.

Async Save Race Condition (Critical)

Problem: journal.json sometimes not created despite successful edits.

Root cause: saveJournalAsync() used Thread.startVirtualThread() which didn't complete before JVM shutdown.

Fix: All journal saves are now synchronous. Same fix applied to saveMetadata().

Documentation Updates

README.md

Both English and Russian sections updated with:

  • Session reactivation documentation
  • nts_init(sessionId="...") usage example
  • Explanation of what persists vs. what starts fresh

Breaking Changes

None. All changes are backward compatible.

Upgrade Notes

No action required. Existing sessions on disk will be automatically reactivated when accessed.

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

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

Персистентность журнала транзакций

История undo/redo теперь сохраняется на диск в формате JSON, гарантируя сохранность данных при перезапусках сервера:

{
  "version": 1,
  "sessionId": "713a6834-c90a-4645-b441-f25f97a75457",
  "counters": { "totalEdits": 5, "totalUndos": 2 },
  "undoStack": [
    {
      "type": "TRANSACTION",
      "timestamp": "2026-01-15T19:09:25",
      "description": "Edit file: src/main/java/com/test/User.java",
      "instruction": "Добавление аннотации @Entity",
      "status": "COMMITTED",
      "snapshots": [{ "original": "src/main/java/com/test/User.java", "backup": "uuid.bak" }]
    }
  ],
  "redoStack": []
}

Ключевые улучшения:

  • Синхронное сохранение после каждого commit/undo/redo — исправляет гонку асинхронных потоков при завершении JVM
  • Относительные пути для файлов — портируемость между машинами
  • Только имена снапшотов (uuid.bak) — директория сессии подразумевается, без избыточных путей

Автоматическая реактивация сессий

Сессии автоматически восстанавливаются с диска при перезапуске сервера:

// SessionContext.getOrCreate() теперь сначала проверяет диск:
if (existsOnDisk(sessionId)) {
    ctx = new SessionContext(sessionId, meta.createdAt());
    ctx.transactionManager.loadJournal();  // Восстановление стеков undo/redo
    return ctx;
}

Реактивация через nts_init:

{ "sessionId": "ваш-предыдущий-uuid" }

Восстанавливается:

  • Полная история undo/redo из journal.json
  • Ссылка на активный TODO-план
  • Метаданные сессии (время создания, последняя активность)

Примечание: Токены доступа к файлам начинаются с чистого листа (перечитайте файлы перед редактированием).

Расширенный TodoTool

Новые действия для полного цикла управления задачами:

Действие Описание
create Создать план с заголовком и чек-листом
read Просмотр текущего плана (алиас: status)
update Отметить задачу выполненной/проваленной или изменить текст
add Добавить новую задачу в текущий план
close Архивировать завершённый план (убирает из HUD)
list Показать все планы (активные и архивные)
reopen Реактивировать архивный план

Новое редактирование текста задачи:

{ "action": "update", "id": 3, "text": "Обновлённое описание задачи" }

Синхронное сохранение метаданных

Метаданные сессии (session.meta) теперь сохраняются синхронно, устраняя гонку виртуальных потоков saveMetadataAsync().

Предыдущий релиз

Улучшения LAT (Line Access Tracker)

Улучшенная обработка перекрывающихся диапазонов:

  • Сложные случаи перекрытия диапазонов теперь обрабатываются корректно
  • Предотвращает ошибки сравнения CRC в краевых случаях, когда несколько правок затрагивают соседние строки

Smart Tips для инструментов

Добавлены контекстные подсказки в описания инструментов для направления LLM-агентов:

  • Рекомендации по оптимальному workflow
  • Предотвращение типичных ошибок
  • Лучшие практики связывания инструментов

Исправления ошибок

Журнал не восстанавливается после реактивации (Критично)

Проблема: После перезапуска сервера nts_init(sessionId="...") возвращал пустые стеки undo/redo, хотя journal.json существовал на диске.

Причина: SessionContext.getOrCreate() не проверял диск на существование сессий. После перезапуска JVM in-memory карта sessions пуста, поэтому создавался НОВЫЙ пустой контекст вместо реактивации с диска.

Решение: getOrCreate() теперь вызывает existsOnDisk() и loadJournal() при наличии директории сессии.

Гонка асинхронного сохранения (Критично)

Проблема: journal.json иногда не создавался, несмотря на успешные правки.

Причина: saveJournalAsync() использовал Thread.startVirtualThread(), который не успевал завершиться до выхода JVM.

Решение: Все сохранения журнала теперь синхронные. Аналогичное исправление применено к saveMetadata().

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

README.md

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

  • Документация реактивации сессий
  • Пример использования nts_init(sessionId="...")
  • Объяснение что сохраняется vs. что начинается с чистого листа

Критические изменения

Нет. Все изменения обратно совместимы.

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

Действий не требуется. Существующие сессии на диске будут автоматически реактивированы при обращении.

Assets 3
Loading