# セッショントレース形式

Claude Code、Codex、Pi、Hermes Agent、Factory Droid の Agent traces は、そのままサポートされています（[Agent Traces](./agent-traces)を参照）。独自のハーネスを構築する場合は、以下で説明する**Session Trace Simple Format (STS-Format)**でセッションを書き出すことで、同じビューアでレンダリングできます。

**Session Trace Simple Format (STS-Format)** は、Hugging Face Hub が検出し、トレースビューアでレンダリングする [JSONL](https://jsonlines.org) ファイル（1行に1つのJSONオブジェクト）です。ヘッダー行に続いてメッセージ行が並ぶ形式で、単一のエージェント/チャットセッションを記録します。

## 1. セッションヘッダー（最初の行）

```json
{ "type": "session", "harness": "my-agent", "id": "b1a2c3", "name": "Implementing a new API" }
```

| フィールド     | 必須 | 備考                                             |
| --------- | -------- | ------------------------------------------------- |
| `type`    | はい      | `"session"` である必要があります                               |
| `harness` | はい      | トレースを生成した**ハーネスのID** |
| `id`      | はい      | 一意のセッションID                                 |
| `name`    | いいえ       | 人間が読めるタイトル                              |
| …         | いいえ       | 追加のメタデータは許可されており、無視されます。         |

`harness` が重要なフィールドです。これは**ハーネスの ID**であり、Hub がセッションに対してどのレンダラー、アイコン、ラベルを使用するかを指定します。現在認識されている ID: `llama.app`。ここで新しいハーネス識別子を追加するのは非常に簡単です。

> 独自のハーネスを構築していますか？ご連絡いただければ、アイコンとラベルを追加し、セッションをブランド付きでレンダリングできるようにします。

## 2. メッセージ（以降の各行）

各行はエンベロープ内の1つのメッセージです:

```json
{ "type": "message", "message": { "role": "assistant", "content": "…" } }
```

`message`オブジェクト:

| フィールド              | 必須 | 備考                                                                                                  |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------ |
| `role`             | はい      | `"user"` · `"assistant"` · `"system"` · `"tool"`                                                       |
| `content`          | はい      | テキスト（空の場合あり）                                                                                    |
| `reasoningContent` | いいえ       | モデルの推論は、独立した思考ブロックとして表示されます                                                    |
| `toolCalls`        | いいえ       | アシスタントのツール呼び出し: `[{ "id", "function": { "name", "arguments" } }]` (`arguments` は JSON 文字列です) |
| `toolCallId`       | いいえ       | `role: "tool"` メッセージでは、結果を応答する `toolCalls[].id` にリンクします                       |
| `timestamp`        | いいえ       | エポックミリ秒                                                                                     |
| `model`            | いいえ       | モデル名                                                                                             |

Tool results は `role: "tool"` を持ち、`toolCallId` を含むメッセージです。ビューアは、各結果を生成した呼び出しの隣に配置します。

### 例

```jsonl
{"type":"session","harness":"my-agent","id":"abc123","name":"what time is it"}
{"type":"message","message":{"role":"user","content":"what time is it?"}}
{"type":"message","message":{"role":"assistant","content":"","toolCalls":[{"id":"t1","function":{"name":"get_time","arguments":"{}"}}]}}
{"type":"message","message":{"role":"tool","toolCallId":"t1","content":"2026-07-01T15:00:00Z"}}
{"type":"message","message":{"role":"assistant","content":"it is 15:00 UTC"}}
```

生成された`.jsonl`を[Dataset](https://huggingface.co/datasets)または[Storage Bucket](./storage-buckets)にアップロードして、トレースビューアで開きます。

## 代替案: Piのセッション形式

上記の形式を採用したくない場合は、Hubがすでにサポートしている**Piのセッション形式**（[session-format.md](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/session-format.md)）を出力できます。その場合、Hubがトレースをあなたのハーネスに帰属できるようにするため、Piのセッションヘッダー行にも`harness: "..."`フィールドを追加してください。