21. Формат rollout (JSONL)

Rollout — это полный лог одной сессии в формате JSONL. Каждая строка — один JSON-объект. Файл append-only: события дописываются по мере turn'а. Используется для:

• /resume <id> — восстановление сессии.
• Воспроизведения для отладки.
• Источник для Phase 1 памяти (см. 07-memories.md).
• Аудита.

Реализация — крейт rollout/. Расширенная версия — rollout-trace/.

1. Файл

Имя

rollout-YYYY-MM-DDThh-mm-ss-<uuid>.jsonl

Создаётся в rollout/src/recorder.rs:1372-1393.

Путь

~/.astracode/sessions/YYYY/MM/DD/rollout-<timestamp>-<uuid>.jsonl

Архивированные (/archive через UI) переезжают в:

~/.astracode/archived_sessions/rollout-<timestamp>-<uuid>.jsonl

См. rollout/src/lib.rs:21-22.

Версионирование

Версия схемы хранится в SessionMeta.timestamp неявно (формат RFC3339 указывает дату); явного поля schema_version пока нет. Обратная совместимость обеспечивается через serde(default) на новых полях.

2. Структура

Первая строка — session_meta

{
  "timestamp": "2026-06-01T10-23-45.123Z",
  "item": {
    "type": "session_meta",
    "meta": {
      "id": "9e3b4f12-...-abc",
      "forked_from_id": null,
      "timestamp": "2026-06-01T10:23:45.123Z",
      "cwd": "/home/timur/work/myproject",
      "originator": "astracode-cli/0.4.11",
      "cli_version": "0.4.11",
      "agent_nickname": "cli",
      "agent_role": "assistant",
      "agent_path": null,
      "source": "cli",
      "model_provider": "openai",
      "base_instructions": {...},
      "dynamic_tools": [...]
    },
    "git": {
      "commit_hash": "abc123def",
      "branch": "main",
      "repository_url": "https://github.com/..."
    }
  }
}

Поля SessionMeta см. в protocol/src/protocol.rs (тип SessionMeta).

Последующие строки — RolloutItem

pub enum RolloutItem {
    SessionMeta(SessionMetaLine),   // только первая запись
    ResponseItem(ResponseItem),     // сообщение пользователя/ассистента или tool call
    Compacted(CompactedSummary),    // итог compact'а
    TurnContext(TurnContextLine),   // snapshot контекста turn'а
    EventMsg(EventMsg),             // обёрнутое событие из протокола (turn start/end, tool begin/end, ...)
}

Каждая строка имеет timestamp и поле item.type (или payload.type для event_msg):

{"timestamp":"...", "type":"response_item", "payload":{...}}
{"timestamp":"...", "type":"event_msg", "payload":{"type":"user_message","message_id":"msg_123","text":"hello"}}
{"timestamp":"...", "type":"turn_context", "payload":{...}}
{"timestamp":"...", "type":"compacted", "payload":{...}}

3. Типы событий

session_meta

Только в начале файла. Описана выше.

response_item

Один элемент истории — сообщение, reasoning, tool call, tool output.

{
  "type": "response_item",
  "payload": {
    "type": "message",          // message | reasoning | function_call | function_call_output | ...
    "id": "msg_abc",
    "role": "user",             // user | assistant | system | developer
    "content": [
      { "type": "input_text", "text": "Fix the failing test." }
    ]
  }
}

Полный набор типов в astracode_protocol::models::ResponseItem.

event_msg

Обёрнутые события протокола (стримятся в TUI и пишутся в rollout).

Полный список — astracode_protocol::protocol::EventMsg.

turn_context

Snapshot конфигурации turn'а: модель, reasoning_effort, permission_profile, environments, доступные tools. Пишется при старте каждого turn'а.

{
  "type": "turn_context",
  "payload": {
    "model": "gpt-5",
    "reasoning_effort": "medium",
    "cwd": "/home/timur/work/myproject",
    "approval_policy": "on-failure",
    "permission_profile": "default",
    "environments": [...]
  }
}

compacted

Итог /compact — резюме, заменившее старую историю.

{
  "type": "compacted",
  "payload": {
    "summary": "...",
    "replaced_turn_count": 18,
    "original_tokens": 142000,
    "summary_tokens": 4200
  }
}

4. Запись на диск

Реализация: rollout/src/recorder.rs:1463-1515.

• Асинхронно: команды отправляются в MPSC канал (256 слотов).
• Буферизация: AddItems накапливаются в pending_items, пишутся одним write_all() + flush() либо при explicit flush()/persist(), либо после каждого batch'а.
• Восстановление: при ошибке записи writer закрывает файл, переоткрывает и повторяет.

API: - record_items(items) — не ждёт результата. - flush() — ждёт окончания записи всех pending. - persist() — то же + sync to disk.

5. Чтение

Полная загрузка

let items = RolloutRecorder::load_rollout_items(path).await?;

rollout/src/recorder.rs:854-921 — построчно парсит JSON и собирает Vec<RolloutItem>.

Для resume

let history = RolloutRecorder::get_rollout_history(path).await?;
// → InitialHistory::Resumed(ResumedHistory { conversation_id, items })

rollout/src/recorder.rs:923-938.

Listing

• Файловый scan: рекурсивно по ~/.astracode/sessions/.
• Через state DB: list_threads_db() использует индекс из threads таблицы (быстрее для большого числа сессий). См. 23-state-db.md.

6. Расширенный трейсинг (rollout-trace)

Крейт rollout-trace/ — параллельная система, пишущая trace bundle (директория с дополнительным JSONL + сырыми payload-файлами):

• Используется для multi-agent (агенты v2), code-mode cells, remote compaction.
• Детальный реплей с reduced state.
• Тут — отдельные события (RolloutStarted, InferenceStarted, ToolCallStarted, CodeCellStarted, CompactionRequestStarted, AgentResultObserved и т.п.).

См. rollout-trace/src/raw_event.rs:68-226 для полного списка:

RolloutStarted, RolloutEnded,
ThreadStarted, ThreadEnded,
AstraCodeTurnStarted, AstraCodeTurnEnded,
InferenceStarted, InferenceCompleted, InferenceFailed, InferenceCancelled,
ToolCallStarted, ToolCallRuntimeStarted/Ended, ToolCallEnded,
CodeCellStarted, CodeCellInitialResponse, CodeCellEnded,
CompactionRequestStarted/Completed/Failed,
CompactionInstalled,
AgentResultObserved,
ProtocolEventObserved (обёрнутые UI события),
Other (произвольный payload для расширений)

Включается через rollout_trace_enabled в конфиге (или для всех сессий — в core defaults).

7. Полезные команды

# Найти rollout текущей сессии (debug-режим TUI)
/rollout

# Снаружи — список сессий за день
ls ~/.astracode/sessions/2026/06/01/

# Просмотреть JSONL
jq -c . ~/.astracode/sessions/2026/06/01/rollout-*.jsonl | head -20

# Поиск всех user-сообщений
jq -c 'select(.type=="event_msg" and .payload.type=="user_message") | .payload.text' \
   ~/.astracode/sessions/2026/06/01/rollout-*.jsonl

# Время длительности turn'ов
jq -c 'select(.type=="event_msg" and (.payload.type=="turn_started" or .payload.type=="turn_complete")) | [.timestamp, .payload.type]' \
   ~/.astracode/sessions/2026/06/01/rollout-*.jsonl

8. Размер и ротация

Rollouts могут быстро расти (особенно при extended thinking и подробных tool output'ах). Типично: - Короткая сессия (1-2 turn'а): 5-50 KB. - Средняя (10-30 turn'ов): 100-500 KB. - Длинная (с большим контекстом, многими tool calls): 5-50 MB.

Ротация — нет. Файлы хранятся, пока пользователь не удалит вручную:

find ~/.astracode/sessions -mtime +90 -delete

Архивирование (через /archive) перемещает в archived_sessions/, но не удаляет.

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

• Содержимое rollout не шифруется.
• Сюда попадают полные user prompts, code контент, command output (включая случайные секреты, если они проходили через terminal).
• Сюда НЕ попадают: API-ключи (они никогда не отдаются модели), пароли из secrets/local.age.
• При передаче rollout кому-то — просматривайте на наличие чувствительной информации.

10. Совместимость

11. Файлы

• rollout/src/lib.rs — публичный API.
• rollout/src/recorder.rs — реализация writer'а.
• protocol/src/protocol.rs — RolloutItem, EventMsg.
• rollout-trace/src/raw_event.rs — расширенные trace events.