fast-jev-compaction

fast-jev-compaction — плагин для Claude Code (и одновременно npm-библиотека), который меняет саму логику компактизации контекста. Вместо того чтобы просить модель пересказать старую часть диалога, он спрашивает у Jev по каждому незакреплённому вызову инструмента: нужен ли он ещё и нужен ли его результат. Лишнее удаляется или обрезается, а всё, что осталось, лежит в истории дословно и в исходном порядке. Пригодится пользователям Claude Code, которые устали терять из сводки пути к файлам и точные тексты ошибок, и разработчикам на TypeScript/JavaScript, встраивающим компактизацию в свои приложения.

Ключевая идея простая: кандидатами на удаление становятся только вызовы инструментов и их результаты. Текстовые сообщения пользователя и ассистента никогда не удаляются и не сокращаются в выходном транскрипте — они урезаются лишь в том состоянии, которое видит Jev. Каждый tool_use сопоставляется со своим tool_result по tool_use_id, а вызовы из первого сообщения и из последних preserveRecentMessages (по умолчанию 6) закрепляются и не трогаются вовсе. Решение по каждому незакреплённому вызову принимает порог keepThreshold (по умолчанию 0.5): если результат нужен — сохранятся и вызов, и результат; если важен только факт вызова — результат обрежется до первых truncateHeadChars символов (по умолчанию 300) с однострочной пометкой; если не нужен ни тот, ни другой — пара уйдёт целиком.

Состояние, которое отправляется Jev, — это вся беседа целиком, где результаты инструментов заменены короткими пометками вроде «ok, 4213 chars (omitted)». Если оно не влезет в maxStateTokens (по умолчанию 25 000), включится поэтапная подгонка, и каждый следующий шаг применится только тогда, когда предыдущего не хватило:

• входы инструментов обрежутся до 1000, потом до 200, потом до 60 символов;
• длинные тексты сократятся до начала и конца, начиная с самых старых незакреплённых сообщений;
• старые незакреплённые сообщения свернутся в пометку «[… N chars omitted …]»;
• старые вызовы сведутся к одной строке вида «t12 Read file_path=src/a.ts → ok 480ch»;
• старые сообщения без вызовов будут исключены, а серии сообщений только с вызовами сложатся в одну запись.

Вопросы к Jev разобьются на столько запросов, сколько нужно, чтобы уложиться в maxRequestTokens (по умолчанию 30 000 — ниже лимита Jev в 32k); запросы идут параллельно, ответы объединяются. Полное состояние повторяется с каждым запросом, так что длинная история обойдётся дороже по числу обращений. Токены здесь считаются оценочно, по символам, без токенизатора — с небольшим запасом вверх. Если после всех этапов состояние всё равно не поместится, компактизация выбросит ошибку; то же произойдёт при сбое Jev, некорректном ответе или отсутствии ключа. Чем ответить на исключение, решает вызывающая сторона — хук Claude Code в этом случае откатится на встроенную сводку.

Как библиотека это выглядит так: await compactMessages(transcript, options) вернёт messages, decisions и stats, а reductionRatio подскажет, стоило ли вообще компактить — например, при значении ниже 0.25 разумнее оставить исходный транскрипт. Тип Message — подмножество SessionMessage из Claude Code, поэтому транскрипт сессии можно передавать как есть. В stats видно, сколько сообщений и символов было до и после, сколько решений по каждой причине, какой этап подгонки потребовался и сколько ушло запросов. Для своего транспорта хватит реализовать интерфейс JevAsker с единственным методом ask и вызвать compact; отдельно экспортированы buildJevRequest, parseJevResponse, collectToolCalls, fitState, batchCalls, decideCall и applyDecisions.

Установка библиотеки — npm install fast-jev-compaction плюс экспорт TYPESAFE_API_KEY. Плагин ставится через marketplace: «claude plugin marketplace add tamaratran/fast-jev-compaction», затем «claude plugin install fast-jev-compaction@fast-jev-compaction»; можно и запустить из локальной копии командой «CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir .». Function hooks — функция раннего доступа Claude Code (2.1.274 и новее), поэтому opt-in флаг придётся включить там, откуда запускается Claude Code, например в ~/.claude/settings.json. После перезапуска или /reload-plugins и /compact, и автокомпактизация пойдут через Jev, а уведомление покажет либо «kept N/M messages, no summary», либо «fallback to built-in summary», если сократить удалось мало (типично для коротких сессий) или что-то сломалось.

Обращения идут к endpoint System One по адресу https://api.typesafe.ai/v1/systemone, модель по умолчанию jev-latest — и endpoint, и модель задаются опциями, реализацию fetch можно подменить для тестов. Нужен API-ключ TypeSafe в переменной окружения TYPESAFE_API_KEY; в исходниках и коммитах его держать не стоит. Сам проект лежит на GitHub под лицензией MIT. В репозитории есть examples, tests и types, а также анимированное демо demo/JevDemo — небольшое приложение на SwiftUI для macOS, которое проигрывает драматизированный сценарий компактизации в терминале в стиле Claude Code: отбрасываемые результаты краснеют и сворачиваются, остальное остаётся дословным, пробел запускает сценарий заново. К API это демо не обращается — оно только для записи экрана. Юнит-тесты тоже работают с фейковым Jev, живой сетевой проверкой служит npm run demo.