Codex Rollout JSONL スキーマ設計書

概要

このドキュメントは、Codex CLI（v0.77.0）が生成するログファイル ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl の 観測ベース スキーマ定義です。

ファイル形式

形式: JSONL（JSON Lines）
構造: 1行 = 1JSONオブジェクト
エンコーディング: UTF-8

データ構造の全体像

rollout-*.jsonl
├── session_meta (1件)          # セッション開始時のメタ情報
├── turn_context (N件)           # 各ターンの実行コンテキスト
├── event_msg (N件)              # リアルタイムイベント
│   ├── token_count              # トークン使用量
│   ├── agent_reasoning          # エージェントの思考プロセス
│   └── user_message             # ユーザー入力
└── response_item (N件)          # レスポンス要素
    ├── message                  # メッセージ
    ├── reasoning                # 思考要約
    ├── function_call            # ツール呼び出し（開始）
    ├── function_call_output     # ツール呼び出し（終了）
    ├── custom_tool_call         # MCPツール呼び出し（開始）
    ├── custom_tool_call_output  # MCPツール呼び出し（終了）
    └── ghost_snapshot           # Git変更前スナップショット

1. レコード基本構造

すべてのレコードは以下のトップレベル構造を持ちます：

{
  "timestamp": "2026-01-02T21:34:19.350Z",  // ISO 8601形式のタイムスタンプ
  "type": "session_meta" | "turn_context" | "response_item" | "event_msg",
  "payload": {}  // タイプごとに異なる構造
}

フィールド説明

フィールド	型	説明
`timestamp`	string (ISO 8601)	レコード生成時刻
`type`	string (enum)	レコードタイプ（後述）
`payload`	object	タイプ固有のデータ

2. レコードタイプ詳細

2.1. `type: "session_meta"`

用途: セッション開始時に1回だけ記録されるメタ情報

payload構造:

{
  "id": "uuid形式のセッションID",
  "cwd": "/path/to/working/directory",
  "cli_version": "0.77.0",
  "originator": "codex_cli_rs",
  "instructions": "長文の指示テキスト（AGENTS.mdやSkills一覧を含む場合あり）",
  "git": {
    "commit_hash": "abc123...",
    "branch": "main",
    "repository_url": "https://github.com/..."
  }
}

フィールド詳細:

フィールド	型	必須	説明
`id`	string	✓	セッションを一意に識別するUUID
`cwd`	string	✓	セッション開始時の作業ディレクトリ
`cli_version`	string	✓	Codex CLIのバージョン
`originator`	string	✓	実行元（通常は `codex_cli_rs`）
`instructions`	string	△	セッションに適用される指示（長文の場合あり）
`git`	object	△	Gitリポジトリ情報（存在する場合）
`git.commit_hash`	string	△	現在のコミットハッシュ
`git.branch`	string	△	現在のブランチ名
`git.repository_url`	string	△	リポジトリURL

2.2. `type: "turn_context"`

用途: 会話の1ターン（1往復）ごとの実行コンテキスト

payload構造:

{
  "cwd": "/path/to/working/directory",
  "approval_policy": "...",
  "sandbox_policy": "...",
  "model": "claude-3-5-sonnet-20241022",
  "effort": "medium"
}

フィールド詳細:

フィールド	型	必須	説明
`cwd`	string	✓	ターン実行時の作業ディレクトリ
`approval_policy`	string	△	承認ポリシー設定
`sandbox_policy`	string	△	サンドボックスポリシー設定
`model`	string	△	使用するAIモデル名
`effort`	string	△	実行努力レベル（例: `medium`）

2.3. `type: "event_msg"`

用途: リアルタイムで発生するイベント通知

payload.type でイベント種別が分岐します。

2.3.1. `payload.type: "token_count"`

用途: トークン使用量のスナップショット

payload構造:

{
  "type": "token_count",
  "info": {
    "total_token_usage": {
      "input_tokens": 1234,
      "output_tokens": 567,
      "reasoning_output_tokens": 0,
      "total_tokens": 1801
    },
    "model_context_window": 200000
  }
}

フィールド詳細:

フィールド	型	説明
`info.total_token_usage.input_tokens`	number	入力トークン数
`info.total_token_usage.output_tokens`	number	出力トークン数
`info.total_token_usage.reasoning_output_tokens`	number	推論出力トークン数
`info.total_token_usage.total_tokens`	number	合計トークン数
`info.model_context_window`	number	モデルのコンテキストウィンドウサイズ

HUDでの派生値計算:

used = total_token_usage.total_tokens
left = model_context_window - total_token_usage.total_tokens
usagePercent = used / model_context_window * 100

2.3.2. `payload.type: "agent_reasoning"`

用途: エージェントの現在の思考プロセスを表す短い説明テキスト

payload構造:

{
  "type": "agent_reasoning",
  "text": "**Searching for relevant plugin**"
}

フィールド詳細:

フィールド	型	説明
`text`	string	思考プロセスの説明（Markdown形式の場合あり）

HUDでの利用: ステップ表示として使用

2.3.3. `payload.type: "user_message"`

用途: ユーザー入力の別形式記録（メッセージ本文、画像など）

payload構造:

{
  "type": "user_message",
  "message": "ユーザーのメッセージ本文",
  "images": ["base64エンコードされた画像データ..."]
}

フィールド詳細:

フィールド	型	説明
`message`	string	ユーザーのメッセージ本文
`images`	string[]	添付画像（base64エンコード）

2.4. `type: "response_item"`

用途: レスポンスの構成要素

payload.type で要素種別が分岐します。

2.4.1. `payload.type: "message"`

用途: ユーザー/アシスタントのメッセージ

payload構造:

{
  "type": "message",
  "content": [
    {
      "input_text": "メッセージ内容"
    }
  ]
}

フィールド詳細:

フィールド	型	説明
`content`	array	メッセージコンテンツの配列
`content[].input_text`	string	テキストコンテンツ

2.4.2. `payload.type: "reasoning"`

用途: 思考プロセスの要約/スナップショット

payload構造:

{
  "type": "reasoning",
  "summary": [
    {
      "summary_text": "思考の要約テキスト"
    }
  ],
  "encrypted_content": "暗号化された非公開コンテンツ"
}

フィールド詳細:

フィールド	型	説明
`summary`	array	要約の配列
`summary[].summary_text`	string	要約テキスト
`encrypted_content`	string	暗号化された非公開コンテンツ（HUDでは使用しない）

HUDでの利用: ステップ表示として使用

2.4.3. `payload.type: "function_call"` / `"function_call_output"`

用途: 標準ツール（主に shell_command）の呼び出し（開始/終了）

開始イベント (function_call):

{
  "type": "function_call",
  "name": "shell_command",
  "arguments": "{\"command\": \"ls -la\"}",
  "call_id": "unique-call-id-123"
}

終了イベント (function_call_output):

{
  "type": "function_call_output",
  "call_id": "unique-call-id-123",
  "output": "Exit code: 0\nfile1.txt\nfile2.txt",
  "duration_ms": 150
}

フィールド詳細:

フィールド	型	説明
`name`	string	ツール名（例: `shell_command`）
`arguments`	string	引数（JSON文字列の場合あり）
`call_id`	string	呼び出しを一意に識別するID（開始/終了で同一）
`output`	string	実行結果（終了時のみ）
`duration_ms`	number	実行時間（ミリ秒、終了時のみ、付与される場合あり）

HUDでの処理:

call_id をキーに開始/終了イベントを照合
未終了レコード → 「進行中」として表示
完了済みレコード → 「直近完了」として表示
経過時間: 進行中は now - start.timestamp、終了後は duration_ms があれば採用、なければ end.timestamp - start.timestamp を計算
成功/失敗判定: output から Exit code: 0 や Error 文字列を検出

2.4.4. `payload.type: "custom_tool_call"` / `"custom_tool_call_output"`

用途: MCP/拡張ツールの呼び出し（開始/終了）

開始イベント (custom_tool_call):

{
  "type": "custom_tool_call",
  "name": "apply_patch",
  "call_id": "unique-call-id-456",
  "input": {
    "file": "src/main.ts",
    "patch": "..."
  }
}

終了イベント (custom_tool_call_output):

{
  "type": "custom_tool_call_output",
  "call_id": "unique-call-id-456",
  "output": "{\"success\": true, \"message\": \"Patch applied\"}",
  "duration_ms": 200
}

フィールド詳細:

フィールド	型	説明
`name`	string	ツール名（例: `apply_patch`）
`call_id`	string	呼び出しを一意に識別するID（開始/終了で同一）
`input`	object	入力パラメータ（開始時のみ）
`output`	string	実行結果（JSON文字列の場合あり、終了時のみ）
`duration_ms`	number	実行時間（ミリ秒、終了時のみ）

HUDでの処理:

function_call と同様の処理
MCP判定: custom_* 系イベントを検出した場合、🧰 アイコンを付与

2.4.5. `payload.type: "ghost_snapshot"`

用途: Git変更前のスナップショット情報

payload構造:

{
  "type": "ghost_snapshot",
  "ghost_commit": {
    "id": "commit-hash",
    "parent": "parent-commit-hash"
  }
}

フィールド詳細:

フィールド	型	説明
`ghost_commit.id`	string	コミットID
`ghost_commit.parent`	string	親コミットID

3. データフローと関係性

3.1. セッションライフサイクル

1. session_meta (1件)
   ↓
2. turn_context (ターン開始)
   ↓
3. event_msg (各種イベント)
   ├── token_count
   ├── agent_reasoning
   └── user_message
   ↓
4. response_item (レスポンス要素)
   ├── message
   ├── reasoning
   ├── function_call → function_call_output
   ├── custom_tool_call → custom_tool_call_output
   └── ghost_snapshot
   ↓
5. turn_context (次のターン)
   ...

3.2. ツール呼び出しのペアリング

ツール呼び出しは call_id で開始/終了イベントを紐付けます：

function_call (call_id: "abc")
  ↓
[実行中...]
  ↓
function_call_output (call_id: "abc")

並列実行: 異なる call_id のレコードが同時に存在することで並列実行を表現

4. HUD実装上の注意点

4.1. ツール一覧の生成

処理フロー:

call_id をキーに開始/終了イベントを照合
未終了レコード → 「進行中」として表示
完了済みレコード → 「直近完了」として表示

経過時間の計算:

進行中: now - start.timestamp
終了後: payload.duration_ms があれば採用、なければ end.timestamp - start.timestamp を計算

成功/失敗判定:

function_call_output / custom_tool_call_output の payload.output を解析
Exit code: 0 を含む → 成功（✓）
Error を含む → 失敗（×）

MCP判定:

custom_tool_call / custom_tool_call_output を検出 → 🧰 アイコンを付与

4.2. ステップ表示

利用可能な情報源:

event_msg の agent_reasoning.text
response_item の reasoning.summary[].summary_text

注意: ToDoリスト/サブエージェントの明示イベントは存在しないため、上記の情報源を「ステップ」として表示

4.3. 並列実行の表現

異なる call_id のレコードが同時に存在することで並列実行を表現
各アイテムに経過時間を個別表示

5. 既知の制約事項

5.1. 観測ベースのスキーマ

このドキュメントは Codex CLI v0.77.0 の観測結果に基づいています
将来のバージョンで構造が変更される可能性があります

6. 参考情報

6.1. ファイルパス

~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl

6.2. バージョン情報

観測対象バージョン: Codex CLI v0.77.0
ドキュメント更新日: 2026-01-03（観測日時点）

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Codex Rollout JSONL スキーマ設計書

概要

ファイル形式

データ構造の全体像

1. レコード基本構造

フィールド説明

2. レコードタイプ詳細

2.1. `type: "session_meta"`

2.2. `type: "turn_context"`

2.3. `type: "event_msg"`

2.3.1. `payload.type: "token_count"`

2.3.2. `payload.type: "agent_reasoning"`

2.3.3. `payload.type: "user_message"`

2.4. `type: "response_item"`

2.4.1. `payload.type: "message"`

2.4.2. `payload.type: "reasoning"`

2.4.3. `payload.type: "function_call"` / `"function_call_output"`

2.4.4. `payload.type: "custom_tool_call"` / `"custom_tool_call_output"`

2.4.5. `payload.type: "ghost_snapshot"`

3. データフローと関係性

3.1. セッションライフサイクル

3.2. ツール呼び出しのペアリング

4. HUD実装上の注意点

4.1. ツール一覧の生成

4.2. ステップ表示

4.3. 並列実行の表現

5. 既知の制約事項

5.1. 観測ベースのスキーマ

6. 参考情報

6.1. ファイルパス

6.2. バージョン情報

FilesExpand file tree

log-schema.md

Latest commit

History

log-schema.md

File metadata and controls

Codex Rollout JSONL スキーマ設計書

概要

ファイル形式

データ構造の全体像

1. レコード基本構造

フィールド説明

2. レコードタイプ詳細

2.1. type: "session_meta"

2.2. type: "turn_context"

2.3. type: "event_msg"

2.3.1. payload.type: "token_count"

2.3.2. payload.type: "agent_reasoning"

2.3.3. payload.type: "user_message"

2.4. type: "response_item"

2.4.1. payload.type: "message"

2.4.2. payload.type: "reasoning"

2.4.3. payload.type: "function_call" / "function_call_output"

2.4.4. payload.type: "custom_tool_call" / "custom_tool_call_output"

2.4.5. payload.type: "ghost_snapshot"

3. データフローと関係性

3.1. セッションライフサイクル

3.2. ツール呼び出しのペアリング

4. HUD実装上の注意点

4.1. ツール一覧の生成

4.2. ステップ表示

4.3. 並列実行の表現

5. 既知の制約事項

5.1. 観測ベースのスキーマ

6. 参考情報

6.1. ファイルパス

6.2. バージョン情報

2.1. `type: "session_meta"`

2.2. `type: "turn_context"`

2.3. `type: "event_msg"`

2.3.1. `payload.type: "token_count"`

2.3.2. `payload.type: "agent_reasoning"`

2.3.3. `payload.type: "user_message"`

2.4. `type: "response_item"`

2.4.1. `payload.type: "message"`

2.4.2. `payload.type: "reasoning"`

2.4.3. `payload.type: "function_call"` / `"function_call_output"`

2.4.4. `payload.type: "custom_tool_call"` / `"custom_tool_call_output"`

2.4.5. `payload.type: "ghost_snapshot"`