Portable Capsules

Portable Capsule — это переносимый .capsule.md файл для передачи рабочего контекста между сессиями, агентами или проектами. В отличие от внутренней Context Capsule в JSONL-сессии, portable capsule является отдельным самодостаточным Markdown-файлом и не содержит native continuation провайдера.

Когда использовать

Portable capsules полезны, когда нужно:

• передать текущий контекст другой сессии SOBA;
• сохранить handoff перед длинным рефакторингом;
• передать решения, blockers, изменённые файлы и проверки другому агенту;
• загрузить внешний .capsule.md безопасно, без автоматического исполнения команд.

Для обычного продолжения текущей сессии используйте soba -c, /rewind или session selector. Portable capsules нужны именно для переноса знаний через границу сессии, проекта или агента.

Команды

Список внутренних checkpoints

/capsule

Показывает внутренние context capsules текущей сессии. Это прежнее поведение команды; оно сохранено.

Просмотр внутреннего checkpoint

/capsule <checkpoint-id>

Показывает стратегию, качество, trigger, token metrics и portable state внутреннего checkpoint.

Создание portable capsule

/capsule create "Передать auth decisions"

SOBA берёт последний context checkpoint текущей сессии, строит Quick/Handoff capsule, санитизирует данные, валидирует результат и пишет файл в:

.soba/capsules/*.capsule.md

Файл создаётся эксклюзивно: существующий файл не перезаписывается.

Экспорт конкретного checkpoint

/capsule export ck_abc ./handoff.capsule.md

ck_abc может быть полным checkpoint ID или однозначным prefix. Если prefix неоднозначен или destination уже существует, команда завершится ошибкой без записи файла.

Destination должен заканчиваться на .capsule.md.

Загрузка portable capsule

/capsule load ./handoff.capsule.md

Loader:

1. проверяет размер файла;
2. парсит Markdown;
3. валидирует schema/version;
4. проверяет checksums verbatim payloads;
5. возвращает capsule как untrusted prompt для следующего turn.

Важно: /capsule load не исполняет команды из файла, не применяет patches и не меняет session tree. Любые действия, описанные внутри capsule, проходят обычный workflow разрешений.

Что хранится в файле

Файл .capsule.md содержит:

• scalar frontmatter для быстрого просмотра;
• человекочитаемый briefing;
• fenced block soba-capsule-json с полным machine payload.

Portable schema v1 включает:

• objective, intendedReceiver, tier, category, archetype;
• dispatchSummary и coreContent;
• decisions/patterns, assumptions, signals;
• artifacts: read/modified files, verification commands, verification status;
• integrationPlan для Standard/Deep capsules;
• verbatimPayloads с SHA-256 checksum;
• sanitation report;
• provenance.

Безопасность

Экспорт всегда проходит sanitization. SOBA редактирует:

• API keys и token/secret/password assignments;
• bearer tokens;
• private keys;
• credential URLs;
• absolute home paths;
• session/provider identifiers.

Sanitation report хранит категории и количество redactions, но не исходные секреты.

Импортируемая capsule считается недоверенной. Текст из файла не становится system instruction.

Ручная проверка

Минимальный ручной прогон:

1. Запустите интерактивную сессию:

   bun run dev -i

2. Создайте checkpoint через обычную работу или /compact.

3. Выполните:

   /capsule
   /capsule create "handoff current work"

4. Убедитесь, что появился файл .soba/capsules/*.capsule.md.

5. Экспортируйте конкретный checkpoint:

   /capsule export ck_abc ./handoff.capsule.md

6. Загрузите файл:

   /capsule load ./handoff.capsule.md

7. Следующий turn должен получить контекст как untrusted briefing.

Troubleshooting

Связанные разделы

• Compaction и Context Capsules
• Сессии
• Безопасность