Compaction и Context Capsules

Compaction — механизм сжатия контекста для работы с длинными сессиями. Вместо того чтобы терять историю, SOBA создаёт Context Capsules — локальные для сессии сжатые представления рабочего контекста, которые подставляются в системный промпт. Это позволяет агенту «помнить» проект сколь угодно долго — как разработчику, который периодически перечитывает документацию и код, чтобы освежить понимание.

1. Зачем нужен Compaction

Проблема

Модель имеет ограниченное контекстное окно (context window) — типично 64K–128K токенов. Каждый запрос к агенту добавляет сообщения в контекст. Длинная сессия быстро исчерпывает лимит, после чего агент либо теряет начало разговора, либо получает ошибку контекста.

Традиционное решение (плохое)

Простое усечение истории — удаление старых сообщений. Но агент теряет контекст проекта: что уже сделано, какие файлы изменены, какие архитектурные решения приняты.

Решение SOBA (Context Capsules)

Вместо потери истории, агент сжимает её в капсулу — структурированное резюме:

• что было сделано
• какие файлы изменены и почему
• текущее состояние проекта
• ключевые решения и их обоснование
• незавершённые задачи

Капсула занимает ~2-10K токенов вместо 30-100K токенов сырой истории.

2. Как устроены Context Capsules

2.1. Структура капсулы

## SOBA Context Capsule
### Goal
Описание текущей задачи агента.

### Progress
- ✅ Fixed TypeScript errors in src/parser.ts (3 errors)
  - Added return type annotations
  - Fixed generic constraints
- ✅ Added tests for parser (85% coverage)
- 🔄 Working on refactoring utils/validator.ts (in progress)

### Key Decisions
1. Used strict TypeScript mode — rationale: ...
2. Chose Map over Record for parser state

### Current State
- Branch: feat/type-fixes
- Modified files: 5
- Test status: 12 passing, 0 failing

### Blockers
- #42: Need to update API types (blocked by backend deploy)

2.2. Как капсула используется

1. При compaction создаётся новая капсула
2. Старые сообщения (до keepRecentTokens) удаляются из контекста
3. Капсула вставляется в системный промпт
4. Последние keepRecentTokens токенов истории сохраняются для немедленного контекста

2.3. Несколько капсул

При очень длинных сессиях может быть несколько капсул. В model input попадает только последняя капсула и сохранённый свежий хвост. При следующем compaction состояние предыдущей капсулы переносится в новую. Старые капсулы остаются в каноническом JSONL для аудита и rewind, но повторно не расходуют контекст модели.

Автоматические и hard-limit Context Capsules не записываются в долговременную Project Memory: временное состояние текущей работы не должно становиться межсессионным фактом. Явный /compact может зеркалировать валидную portable-капсулу, а для управляемого handoff используйте /capsule create.

2.4. Deferred preflight barrier

SOBA не генерирует summary конкурентно с основным model flow. Мягкие trigger только сохраняют pending intent. Непосредственно перед следующей inference SOBA строит неизменяемый plan, немедленно отправляет compaction_start и ждёт терминального результата.

Model flow ждёт, но TUI остаётся отзывчивым и ставит новый ввод в очередь. Во время barrier показывается live-статус вроде Сжимаю контекст перед ответом · 82%, а после завершения остаётся одна строка с trigger, количеством токенов до/после, экономией и checkpoint ID.

Результат имеет один из статусов: completed, skipped, cancelled, stale или failed. Abort или изменение session leaf никогда не позволяют позднему generator дописать capsule.

3. Триггеры compaction

SOBA использует 7 типов триггеров:

3.1. Hard Limit (блокирующий)

Срабатывает: Когда эффективных токенов больше чем:

hardLimit = contextWindow - maxOutputTokens - safetyReserveTokens

Действие: Блокирующий compaction перед следующим вызовом модели. Нельзя отключить через auto: false. Это аварийный механизм.

В длинном agent turn без новых message boundaries SOBA выбирает границу между завершёнными tool batches или переносит вперёд предыдущую capsule. Tool call и соответствующий output никогда не разделяются между summary и сохранённым хвостом.

Пример: contextWindow=65536, maxOutputTokens=8192, safetyReserveTokens=8192 → hardLimit = 65536 - 8192 - 8192 = 49152 токенов

3.2. Auto Threshold (deferred preflight)

Срабатывает: Перед model call, когда effective context достигает soft limit и проходит ROI-проверку.

Действие: Запускает один soft compact за agent turn. Ошибка или недостаточный фактический ROI не блокируют model call, пока контекст остаётся ниже hard limit.

3.3. Turn Complete (deferred preflight)

Срабатывает: После каждого завершённого хода агента, если:

• auto: true и compactOnTurnComplete: true
• Эффективных токенов ≥ soft limit
• ROI проходит проверку (см. §4)

Действие: Помечает compaction как pending. Перед следующим model call SOBA показывает live-статус и ожидает завершения; TUI продолжает принимать ввод в очередь.

3.4. Milestone (deferred preflight)

Срабатывает: При milestone checkpoint (установленном агентом), если:

• auto: true и compactOnMilestone: true
• ROI проходит проверку

Действие: Помечает milestone intent; compaction выполняется в следующем preflight barrier.

3.5. Plan Pivot (deferred preflight)

Срабатывает: Когда checkpoint фиксирует смену плана.

Действие: Сохраняет pending intent с приоритетом выше turn_complete; compact выполняется в следующем preflight barrier.

3.6. User Request (явный)

Срабатывает: При вызове /compact пользователем.

Действие: Безусловный compaction (ROI-проверка пропускается, но если нечего сжимать — операция no-op).

3.7. Context Overflow (аварийный)

Срабатывает: Когда провайдер возвращает ошибку context overflow.

Действие: Один обязательный recovery compact и не более одного retry за agent turn. При неудаче SOBA не отправляет повторно тот же заведомо oversized request.

4. Метрики и конфигурация

4.1. Параметры в config.json

{
  "compaction": {
    "auto": true,
    "compactOnTurnComplete": true,
    "compactOnMilestone": true,
    "minTokensForAutoCompact": 32000,
    "minReclaimableTokens": 12000,
    "minSavingsRatio": 0.25,
    "keepRecentTokens": 20000,
    "safetyReserveTokens": 8192,
    "autoCompactThresholdRatio": 0.8,
    "timeoutMs": 15000
  }
}

4.2. Описание параметров

Если модель не завершает summary за timeoutMs, SOBA отменяет её запрос и заканчивает compact локальной deterministic-капсулой с качеством degraded. Внешняя отмена turn по-прежнему не создаёт capsule.

4.3. ROI-проверка

Автоматический compaction выполняет две проверки Return on Investment. До генерации используется предварительная оценка:

reclaimable = effectiveTokens - keepRecentTokens
savingsRatio = reclaimable / effectiveTokens

Soft limit вычисляется как:

softLimit = min(hardLimit - 1, max(minTokensForAutoCompact, floor(hardLimit * autoCompactThresholdRatio)))

Генерация начинается, только если:

• reclaimable ≥ minReclaimableTokens (есть что сжимать)
• savingsRatio ≥ minSavingsRatio (сжатие оправдано)

После генерации SOBA повторяет проверку по фактическому размеру полного capsule payload, retained tail и system/tool tokens. Если результат не достигает тех же минимумов, soft capsule не записывается и model call продолжается без изменения session tree. Hard-limit, overflow и явный /compact этой post-generation ROI-проверкой не блокируются.

Пример: 50K эффективных токенов, 20K keepRecent → reclaimable = 30K. savingsRatio = 30/50 = 0.6 (60%) → выше порога 0.25 → OK.

Если эффективных всего 25K → reclaimable = 5K. savingsRatio = 5/25 = 0.2 (20%) → ниже порога → пропускаем.

5. Процесс compaction (пошагово)

1. Триггер — одно из условий §3 срабатывает
2. Сбор контекста — агент собирает все сообщения, результаты инструментов, статус проекта
3. Генерация капсулы — агент создаёт резюме по структуре Context Capsule
4. Проверка результата — валидируется provenance, tool boundaries и фактический ROI soft compact
5. Активация контекста — старые сообщения остаются в каноническом JSONL, но model input строится из капсулы и retained tail
6. Сохранение в сессию — капсула атомарно записывается как "type":"context_capsule" в JSONL

6. Ручное управление

6.1. Команды TUI

# Принудительный compaction
/compact

# Включить/выключить авто-компакт (на лету)
/auto-compact off
/auto-compact on

# Просмотр бюджета
/budget

# Детальная статистика
/budget
/capsule

6.2. Переменная окружения

# Отключить авто-компакт глобально
export SOBA_AUTO_COMPACT=false

6.3. CLI-флаг

# Отключить на один запуск
soba --no-auto-compact

7. Диагностика

7.1. Просмотр состояния контекста

/budget

# Вывод:
# Context Stats:
#   Effective tokens:    38,420
#   Measurement source:  estimated
#   Soft limit:          39,046
#   Hard limit:          48,808
#   Safety reserve:       8,192
#   Keep recent:         20,000
#   Capsules:             2
#   Messages:            47
#   Turns:               12
#   Last capsule:        2m ago (2,840 tokens)
#   Savings ratio:       0.48 (48%)
#   Auto-compact:        ON
#   Next trigger est.:   ~3 turns

7.2. Просмотр капсулы

/capsule

# Показывает последнюю капсулу в читаемом виде

7.3. Валидация конфигурации

При старте SOBA проверяет compaction-инварианты. При нарушении выводит предупреждение:

⚠️  Compaction disabled: config validation failed:
    keepRecentTokens (40000) must be < hard limit (47300)

8. Portable Capsules

Context Capsules внутри JSONL-сессии нужны для compaction и rewind. Portable Capsules — отдельный формат .capsule.md, который можно передать другой сессии, агенту или проекту.

Основные команды:

/capsule create "handoff auth work"
/capsule export ck_abc ./handoff.capsule.md
/capsule load ./handoff.capsule.md

Подробнее: Portable Capsules.

9. Лучшие практики

9.1. Когда отключать auto-compact

• Короткие сессии (1-3 хода) — compaction не нужен
• Тестирование промптов — нужно видеть полную историю
• Дебаггинг — не хотите терять детали

9.2. Когда включать ручной compact

• Перед сменой задачи в рамках одной сессии
• После крупного рефакторинга (сжать старый контекст)
• Перед долгим перерывом (зафиксировать состояние)

9.3. Оптимизация параметров

• Большие проекты (>50 файлов): увеличьте keepRecentTokens до 30000
• Маленькие проекты (<10 файлов): уменьшите minTokensForAutoCompact до 16000
• Модели с большим контекстом (128K+): compaction менее агрессивен — можно увеличить minSavingsRatio до 0.4
• Модели с reasoning (R1, o1): они потребляют больше токенов на thinking — увеличьте safetyReserveTokens до 16000