utm-auto-compact

Плагин авто-сжатия контекста DSH по абсолютному порогу токенов.

Встроенный dsh-compaction-basic компактит по thresholdRatio (по умолч. 0.8) от окна модели — при огромном окне авто-компакт почти не срабатывает, и пользователь жмёт /compact вручную. Этот плагин зовёт тот же seam (ctx.compaction.compactNow) на событии agent/status → idle, когда surface сессии накопила ≥ maxTokens токенов по ctx.tokenMeter. Порог не зависит от окна модели.

Установка (профиль DSH)

В package.json профиля:

"dependencies": {
  "utm-auto-compact": "file:<путь-к-клонированному-репозиторию>"
}

либо по тегу из GitHub:

"dependencies": {
  "utm-auto-compact": "github:<ваш-логин>/utm-auto-compact"
}

В cordis.patch.yml:

utm-auto-compact:
  config:
    enabled: true
    maxTokens: 45000

Конфиг

Ключ	Тип	По умолчанию	Смысл
enabled	boolean	true	Вкл/выкл
maxTokens	int > 0	30000	Триггер: сжимать, когда surface ≥ этого
maxRetries	int ≥ 0	4	Доп. попытки сверх первой, пока surface ≥ maxTokens (re-measure между попытками)
cooldownMs	int ≥ 0	60000	Пауза после успеха/quiet-неудачи (busy, cancelled) — per agent
failCooldownMs	int ≥ 0	300000	Пауза после НЕ-quiet ошибок (summary/persistence/commit/…)
idleGraceMs	int ≥ 0	0	Debounce: ждать N мс стабильного idle перед стартом
logLevel	enum	info	silent | error | info | debug — детализация файл-лога
dryRun	boolean	false	Логировать решение сжаться, но НЕ вызывать compactNow
excludeSubagents	boolean	false	Не сжимать фоновых субагентов (сессии с header.origin === 'subagent')

Старая конфигурация (enabled + maxTokens) работает без изменений — новые поля с defaults.

excludeSubagents: true полезен, когда основной агент держит много фоновых субагентов (делегирования исследовательских задач): токены тратятся только на скомпакт главной беседы, а короткоживущие субагенты не дёргают суммарайзер без нужды. Детекция по помеченным сессиям DSH (agent.session.header.origin === 'subagent'), безопасна для моков и старых сессий.

Порог лучше ставить ниже желаемого состояния после сжатия: compactNow сжимает один диапазон, и с maxRetries плагин дожимает до < maxTokens, но не перехватывает случай «один гигантский узел — дальше не уменьшается»: будет честный warn и длинный failCooldownMs.

Логи

Диагностический файл-лог: ~/.dsh/logs/utm-auto-compact.log (переопределяется DSH_UTM_AUTO_COMPACT_LOG), ротация ~4 MiB в .old.

Ключевые строки:

• idle agent=… totalTokens=… — замер на idle;
• attempt N/… : … via surface=… — прогресс ретря-цикла;
• compacted agent=…: N nodes (~N tokens) — успех;
• compact FAILED agent=… code=summary: … — классифицированная ошибка;
• still above threshold … after N attempts — исчерпанные ретраи;
• dry-run: would compact … — режим dryRun.

Плюс дублирование в штатный ctx.logger (info — успех, warn — ошибки/выше порога).

Команда /auto-compact

Если в контексте есть ctx.commands, плагин регистрирует команду /auto-compact: показывает конфиг, счётчики по агенту (attempts/compacted/retries/failures) и активный cooldown. Без commands (например, в мок-тестах) — команды нет, плагин это тихо пропускает.

Тесты

Автономный набор в test/run-tests.mjs (24 сценария: порог, параллельность агентов, inflight-per-agent, quiet-коды busy/cancelled, retry-цикл ниже порога, cooldown после успеха/неудачи (summary), idle grace, dry-run, silent-лог, zod-валидация, recovery changed, excludeSubagents вкл/выкл).

Запуск — из папки профиля (runner копируется туда: внутри пакета bare-импорт utm-auto-compact резолвится self-reference на локальный index.js без peer-деп, а в профиле — на установленную копию <профиль>\node_modules\utm-auto-compact):

cd ~/.dsh/profiles/<ваш-профиль>
Copy-Item <путь-к-репо>\test\run-tests.mjs .\_run-tests.mjs
node _run-tests.mjs
Remove-Item .\_run-tests.mjs

Ожидается: 24 passed, 0 failed. Диг-лог тестов уходит во временный файл (DSH_UTM_AUTO_COMPACT_LOG), в реальный ~/.dsh/logs/ ничего не пишется.

Ограничения

• Плагин не выбирает, что сжимать — это решает движок dsh-compaction-basic (compactNow сжимает почти всю историю; удержание хвоста не передаётся).
• Сессионные /compact вручную и авто-плагин делят один seam: ручной компакт во время авто-попытки даст busy — тихо, повторится после cooldownMs.
• «could not produce a smaller summary» — лимит суммарайзера бэкенда, не баг плагина: после failCooldownMs попробуем снова.

License

MIT