会话树、分支与会话文件格式

~/.pi/agent/sessions/--<path>--/<timestamp>_<session-id>.jsonl

const safePath = `--${resolvedCwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;

const fileTimestamp = timestamp.replace(/[:.]/g, "-");
this.sessionFile = join(this.getSessionDir(), `${fileTimestamp}_${this.sessionId}.jsonl`);

if (!/^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/.test(id)) {

2026-10-23T14-00-00-000Z_0198f3a2-7c41-7b6e-9a12-3d5e8f0b7c22.jsonl

private _hasConversation(): boolean {
    return this.fileEntries.some(
        (e) => e.type === "message" && (e.message.role === "user" || e.message.role === "assistant"),
    );
}

 * Setup entries alone (model, thinking level, system prompt) stay in memory so opening and
 * closing pi without chatting leaves no file behind. Starting at the user message (not the
 * first assistant reply) keeps the prompt on disk if the first turn never completes (#10000).

{
  "sessionDir": "./my-sessions"
}

/**
 * Get all session entries (excludes header). Returns a shallow copy.
 * The session is append-only: use appendXXX() to add entries, branch() to
 * change the leaf pointer. Entries cannot be modified or deleted.
 */

rm ~/.pi/agent/sessions/--Users-me-work-api--/2026-10-23T14-00-00-000Z_0198f3a2.jsonl

# 我知道这个项目最近在做什么
pi --continue

# 我知道项目，但不确定是哪一次
pi --resume        # 交互式里等价于 /resume

# 我知道会话 ID 的开头几个字符
pi --session 0198f3a2

interface SessionEntryBase {
  type: string;
  id: string;
  parentId: string | null;  // 根条目的 parentId 是 null
  timestamp: string;        // ISO 8601
}

for (let i = 0; i < 100; i++) {
    const id = randomUUID().slice(0, 8);
    if (!byId.has(id)) return id;
}
// Fallback to full UUID if somehow we have collisions
return randomUUID();

if (entry.type === "message") { … return [message]; }
if (entry.type === "custom_message") { … }
if (entry.type === "branch_summary" && entry.summary) { … }
if (entry.type === "compaction") { … }
return [];

{"type":"session","version":3,"id":"0198f3a2-7c41-7b6e-9a12-3d5e8f0b7c22","timestamp":"2026-10-23T14:00:00.000Z","cwd":"/Users/me/work/api"}

{"type":"session","version":3,"id":"...","timestamp":"...","cwd":"/Users/me/work/api","parentSession":"/Users/me/.pi/agent/sessions/--Users-me-work-api--/2026-10-23T09-12-00-000Z_0198f1ab....jsonl"}

{"type":"session","version":3,"id":"0198f3a2-…","timestamp":"2026-10-23T14:00:00.000Z","cwd":"/Users/me/work/api"}
{"type":"message","id":"a0b1c2d3","parentId":null,"timestamp":"…T14:00:01.000Z","message":{"role":"system","content":"","sections":{"preamble":"You are an expert coding assistant…","tools":"<tools>\n- read: …\n</tools>","cwd":"/Users/me/work/api"},"toolsAdded":[{"name":"read","description":"…","parameters":{}}],"timestamp":1733234401000}}
{"type":"message","id":"a1b2c3d4","parentId":"a0b1c2d3","timestamp":"…T14:00:02.000Z","message":{"role":"user","content":"把 auth 模块的 refresh token 逻辑抽出来","timestamp":…}}
{"type":"message","id":"b2c3d4e5","parentId":"a1b2c3d4","timestamp":"…T14:00:20.000Z","message":{"role":"assistant","content":[{"type":"toolCall","id":"call_1","name":"read","arguments":{"path":"src/auth/refresh.ts"}}],"api":"anthropic-messages","provider":"anthropic","model":"claude-sonnet-4-5","usage":{…},"stopReason":"toolUse","timestamp":…}}
{"type":"message","id":"c3d4e5f6","parentId":"b2c3d4e5","timestamp":"…T14:00:21.000Z","message":{"role":"toolResult","toolCallId":"call_1","toolName":"read","content":[{"type":"text","text":"export async function refresh() {…}"}],"isError":false,"timestamp":…}}
{"type":"message","id":"d4e5f6a7","parentId":"c3d4e5f6","timestamp":"…T14:00:25.000Z","message":{"role":"assistant","content":[{"type":"text","text":"可以抽成 service，建议先看 tests。"}],"stopReason":"stop","timestamp":…}}
{"type":"message","id":"e5f6a7b8","parentId":"d4e5f6a7","timestamp":"…T14:01:02.000Z","message":{"role":"user","content":"先看看现有测试","timestamp":…}}
{"type":"message","id":"f6a7b8c9","parentId":"e5f6a7b8","timestamp":"…T14:01:10.000Z","message":{"role":"assistant","content":[{"type":"toolCall","id":"call_2","name":"read","arguments":{"path":"tests/auth.test.ts"}}],"stopReason":"toolUse","timestamp":…}}

{"type":"message","id":"1a2b3c4d","parentId":"d4e5f6a7","timestamp":"…T14:03:00.000Z","message":{"role":"user","content":"改成 class 实现，保留现有导出","timestamp":…}}
{"type":"message","id":"2b3c4d5e","parentId":"1a2b3c4d","timestamp":"…T14:03:12.000Z","message":{"role":"assistant","content":[{"type":"text","text":"好，我先看 exports。"}],"stopReason":"stop","timestamp":…}}

type AgentMessage =
  | SystemMessage | UserMessage | AssistantMessage | ToolResultMessage
  | BashExecutionMessage | CustomMessage | BranchSummaryMessage | CompactionSummaryMessage;

interface SystemMessage {
  role: "system";
  content: string | TextContent[];
  sections?: Record<string, string | null>;
  toolsAdded?: Tool[];
  toolsRemoved?: ToolReference[];
  timestamp: number;
}

# 看会话文件在哪、当前多大了
ls -lh ~/.pi/agent/sessions/--Users-me-work-api--/

# 第一行是文件头，看版本和 cwd
head -1 ~/.pi/agent/sessions/--Users-me-work-api--/*.jsonl | tail -1

# 把整个会话摊平成「谁说了什么」，倒序看最新
jq -r 'select(.type=="message")
       | .message
       | select(.role=="user" or .role=="assistant")
       | "\(.role)\t\((.content | if type=="string" then . else ([.[]? | select(.type=="text") | .text] | join(" ")) end) | .[0:120])"'
  ~/.pi/agent/sessions/--Users-me-work-api--/*.jsonl | tail -40

# 看分支结构：id、parentId、类型、摘要首行
jq -r 'select(.type!="session")
       | "\(.id)  ← \(.parentId // "ROOT")  \(.type)\(if .summary then "  " + (.summary[0:60]) else "" end)"' \
  ~/.pi/agent/sessions/--Users-me-work-api--/*.jsonl

/** Start a new branch from an earlier entry.
 *  Moves the leaf pointer to the specified entry. The next appendXXX() call
 *  will create a child of that entry, forming a new branch. */
branch(branchFromId: string): void {
    if (!this.byId.has(branchFromId)) throw new Error(`Entry ${branchFromId} not found`);
    this.leafId = branchFromId;
}

/** Reset the leaf pointer to null (before any entries).
 *  Use this when navigating to re-edit the first user message. */
resetLeaf(): void {
    this.leafId = null;
}

/** Start a new branch with a summary of the abandoned path. */
branchWithSummary(branchFromId, summary, details?, fromHook?, usage?): string

[user msg] ─── [assistant] ─── [user msg] ─── [assistant] ─┬─ [user msg] ← current leaf
                                                            │
                                                            └─ [branch_summary] ─── [user msg] ← alternate branch

Entries normally form one tree, but navigation APIs can create multiple roots:
- A root entry has parentId: null; the first entry is initially the root
- …
- Calling resetLeaf() or branchWithSummary(null, ...) allows a later entry to become another root

/** A well-formed session has exactly one root (first entry with parentId === null).
 *  Orphaned entries (broken parent chain) are also returned as roots. */

for (const entry of this.fileEntries) {
    if (entry.type === "session") continue;
    this.byId.set(entry.id, entry);
    this.leafId = entry.id;   // 每轮都覆盖，最终留下最后一行
    …
}

const path = buildSessionPath(entries, leafId, byId);
let compaction: CompactionEntry | null = null;
for (const entry of path) {
    if (entry.type === "compaction") compaction = entry;   // 取最后一个
}
if (!compaction) return path;

const contextEntries: SessionEntry[] = [compaction];
let foundFirstKept = false;
for (let i = 0; i < compactionIdx; i++) {
    const entry = path[i];
    if (entry.id === compaction.firstKeptEntryId) foundFirstKept = true;
    if (foundFirstKept && !(entry.type === "message" && entry.message.role === "system")) {
        contextEntries.push(entry);
    }
}
contextEntries.push(...path.slice(compactionIdx + 1));

const edits = new Map<string, ContextEditEntry>();
for (const entry of contextEntries) {
    if (entry.type === "context_edit") edits.set(entry.targetId, entry);
}

for (const entry of path) {
    if (entry.type === "thinking_level_change") thinkingLevel = entry.thinkingLevel;
    else if (entry.type === "model_change") model = { provider, modelId };
    else if (entry.type === "message" && entry.message.role === "assistant") {
        model = { provider: entry.message.provider, modelId: entry.message.model };
    }
}

async fork(entryId: string, options?: { position?: "before" | "at"; withSession?: … }): Promise<…>

if (position === "at") {
    targetLeafId = selectedEntry.id;
} else {
    if (selectedEntry.type !== "message" || selectedEntry.message.role !== "user") {
        throw new Error("Invalid entry ID for forking");
    }
    targetLeafId = selectedEntry.parentId;
    selectedText = extractUserMessageText(selectedEntry.message.content);
}

const sessionManager = SessionManager.open(currentSessionFile, sessionDir);
const forkedSessionPath = sessionManager.createBranchedSession(targetLeafId);

// interactive-mode.ts —— /clone
const result = await this.runtimeHost.fork(leafId, { position: "at" });
this.editor.setText("");
this.showStatus("Cloned to new session");

// interactive-mode.ts —— /fork
this.showUserMessageSelector();   // 只列用户消息

/clone  =  fork(currentLeaf,          position: "at")
/fork   =  fork(selectedUserMessage,  position: "before")   ← 默认

const path = this.getBranch(leafId);
…
this.fileEntries = [header, ...pathWithoutLabels, ...labelEntries];
this._rewriteFile();

entry.type === "compaction"
    ? { ...entry, parentId: pathParentId,
        firstKeptEntryId: entry.firstKeptEntryId === entry.id
            ? entry.id
            : (replacementByLabelId.get(entry.firstKeptEntryId) ?? entry.firstKeptEntryId) }
    : { ...entry, parentId: pathParentId },

if (!targetLeafId) {
    const sessionManager = SessionManager.create(this.cwd, sessionDir);
    sessionManager.newSession({ parentSession: currentSessionFile });
    …
    return { cancelled: false, selectedText };
}

// Write new header pointing to source as parent, with updated cwd
const newHeader: SessionHeader = { …, parentSession: resolvedSourcePath };
writeFileSync(newSessionFile, `${JSON.stringify(newHeader)}\n`, { flag: "wx" });

// Copy all non-header entries from source
for (const entry of sourceEntries) {
    if (entry.type !== "session") {
        appendFileSync(newSessionFile, `${JSON.stringify(entry)}\n`);
    }
}

// Summary is attached at the navigation target position (newLeafId), not the old branch
const summaryId = this.sessionManager.branchWithSummary(newLeafId, summaryText, summaryDetails, fromExtension, summaryUsage);

{"type":"branch_summary","id":"g7h8i9j0","parentId":"a1b2c3d4","fromId":"f6g7h8i9","summary":"Branch explored approach A...","details":{"readFiles":[],"modifiedFiles":[]}}

# 从当前会话文件读出 parentSession
jq -r 'select(.type=="session") | .parentSession // "(no parent)"' \
  ~/.pi/agent/sessions/--Users-me-work-api--/*.jsonl

export const CURRENT_SESSION_VERSION = 3;

/** Migrate v1 → v2: add id/parentId tree structure. Mutates in place. */
function migrateV1ToV2(entries: FileEntry[]): void {
    const ids = new Set<string>();
    let prevId: string | null = null;
    for (const entry of entries) {
        if (entry.type === "session") { entry.version = 2; continue; }
        entry.id = generateId(ids);
        entry.parentId = prevId;
        prevId = entry.id;
        if (entry.type === "compaction") {          // 索引改成 id
            const comp = entry as CompactionEntry & { firstKeptEntryIndex?: number };
            if (typeof comp.firstKeptEntryIndex === "number") {
                const targetEntry = entries[comp.firstKeptEntryIndex];
                if (targetEntry && targetEntry.type !== "session") {
                    comp.firstKeptEntryId = targetEntry.id;
                }
                delete comp.firstKeptEntryIndex;
            }
        }
    }
}

/** Migrate v2 → v3: rename hookMessage role to custom. Mutates in place. */
function migrateV2ToV3(entries: FileEntry[]): void {
    for (const entry of entries) {
        if (entry.type === "session") { entry.version = 3; continue; }
        if (entry.type === "message") {
            const msgEntry = entry as SessionMessageEntry;
            if (msgEntry.message && (msgEntry.message as {role: string}).role === "hookMessage") {
                (msgEntry.message as {role: string}).role = "custom";
            }
        }
    }
}

private _loadEntries(entries: FileEntry[], options?: NewSessionOptions): void {
    const header = entries.find((e) => e.type === "session") as SessionHeader | undefined;
    if (header) {
        this.fileEntries = entries;
        this.sessionId = header.id;
        if (migrateToCurrentVersion(this.fileEntries)) {
            this._rewriteFile();          // ← 原地重写磁盘文件
        }
    } else {
        this.newSession(options);
        this.fileEntries = this.fileEntries.concat(entries);
    }
    this._buildIndex();
}

for (const line of lines) {
    if (!line.trim()) continue;
    try {
        entries.push(JSON.parse(line) as FileEntry);
    } catch {
        // Skip malformed lines
    }
}

total=$(wc -l < session.jsonl)
parsed=$(jq -c . session.jsonl 2>/dev/null | wc -l)
echo "文件 $total 行，能解析出 $parsed 行"