Session: cây JSONL, nhánh và context

/** * Manages conversation sessions as append-only trees stored in JSONL files. * * Each session entry has an id and parentId forming a tree structure. The "leaf" * pointer tracks the current position. Appending creates a child of the current leaf. * Branching moves the leaf to an earlier entry, allowing new branches without * modifying history. * * Use buildSessionContext() to get the resolved message list for the LLM, which * handles compaction summaries and follows the path from root to current leaf. */

/** * Compute the default session directory for a cwd. * Encodes cwd into a safe directory name under ~/.pi/agent/sessions/. */function getDefaultSessionDirPath(cwd: string, agentDir: string = getDefaultAgentDir()): string {	const resolvedCwd = resolvePath(cwd);	const resolvedAgentDir = resolvePath(agentDir);	const safePath = `--${resolvedCwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;	return join(resolvedAgentDir, "sessions", safePath);}export function getDefaultSessionDir(cwd: string, agentDir: string = getDefaultAgentDir()): string {	const sessionDir = getDefaultSessionDirPath(cwd, agentDir);	if (!existsSync(sessionDir)) {		mkdirSync(sessionDir, { recursive: true });	}	return sessionDir;}

export const CURRENT_SESSION_VERSION = 3;export interface SessionHeader {	type: "session";	version?: number; // v1 sessions don't have this	id: string;	timestamp: string;	cwd: string;	parentSession?: string;}export interface NewSessionOptions {	id?: string;	parentSession?: string;}export interface SessionEntryBase {	type: string;	id: string;	parentId: string | null;	timestamp: string;}

export interface SessionMessageEntry extends SessionEntryBase {	type: "message";	message: AgentMessage;}export interface ThinkingLevelChangeEntry extends SessionEntryBase {	type: "thinking_level_change";	thinkingLevel: string;}export interface ModelChangeEntry extends SessionEntryBase {	type: "model_change";	provider: string;	modelId: string;}export interface UsageEntry extends SessionEntryBase {	type: "usage";	/** Arbitrary usage category, such as "cache_warm". */	kind: string;	provider: string;	model: string;	usage: Usage;	/** Optional human-readable qualifier for usage notices. */	note?: string;}

export interface CompactionEntry<T = unknown> extends SessionEntryBase {	type: "compaction";	summary: string;	firstKeptEntryId: string;	tokensBefore: number;	/** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */	details?: T;	/** Usage from the LLM call(s) that generated this summary, if available */	usage?: Usage;	/** True if generated by an extension, undefined/false if pi-generated (backward compatible) */	fromHook?: boolean;	/** Complete prompt and tool state at this compaction boundary. */	systemMessage?: SystemMessage;}export interface BranchSummaryEntry<T = unknown> extends SessionEntryBase {	type: "branch_summary";	fromId: string;	summary: string;	/** Extension-specific data (not sent to LLM) */	details?: T;	/** Usage from the LLM call that generated this summary, if available */	usage?: Usage;	/** True if generated by an extension, false if pi-generated */	fromHook?: boolean;}

/** * Custom entry for extensions to store extension-specific data in the session. * Use customType to identify your extension's entries. * * Purpose: Persist extension state across session reloads. On reload, extensions can * scan entries for their customType and reconstruct internal state. * * Does NOT participate in LLM context (ignored by buildSessionContext). * For injecting content into context, see CustomMessageEntry. */export interface CustomEntry<T = unknown> extends SessionEntryBase {	type: "custom";	customType: string;	data?: T;}/** Label entry for user-defined bookmarks/markers on entries. */export interface LabelEntry extends SessionEntryBase {	type: "label";	targetId: string;	label: string | undefined;}/** Session metadata entry (e.g., user-defined display name). */export interface SessionInfoEntry extends SessionEntryBase {	type: "session_info";	name?: string;}

/** * Custom message entry for extensions to inject messages into LLM context. * Use customType to identify your extension's entries. * * Unlike CustomEntry, this DOES participate in LLM context. * The content is converted to a user message in buildSessionContext(). * Use details for extension-specific metadata (not sent to LLM). * * display controls TUI rendering: * - false: hidden entirely * - true: rendered with distinct styling (different from user messages) */export interface CustomMessageEntry<T = unknown> extends SessionEntryBase {	type: "custom_message";	customType: string;	content: string | (TextContent | ImageContent)[];	details?: T;	display: boolean;}/** Content that an append-only context edit may replace without changing message metadata. */export type ContextEditableContent =	| UserMessage["content"]	| AssistantMessage["content"]	| ToolResultMessage["content"]	| CustomMessage["content"];/** Append-only change to one earlier entry's contribution to model context. */export interface ContextEditEntry extends SessionEntryBase {	type: "context_edit";	targetId: string;	/** Null omits the target from model context. A value replaces only its content. */	replacement: { content: ContextEditableContent } | null;}

/** Session entry - has id/parentId for tree structure (returned by "read" methods in SessionManager) */export type SessionEntry =	| SessionMessageEntry	| ThinkingLevelChangeEntry	| ModelChangeEntry	| UsageEntry	| CompactionEntry	| BranchSummaryEntry	| CustomEntry	| CustomMessageEntry	| ContextEditEntry	| LabelEntry	| SessionInfoEntry;/** Raw file entry (includes header) */export type FileEntry = SessionHeader | SessionEntry;

private _appendEntry(entry: SessionEntry): void {	this.fileEntries.push(entry);	this.byId.set(entry.id, entry);	this.leafId = entry.id;	this._persist(entry);}/** Append a message as child of current leaf, then advance leaf. Returns entry id. * Does not allow writing CompactionSummaryMessage and BranchSummaryMessage directly. * Reason: we want these to be top-level entries in the session, not message session entries, * so it is easier to find them. * These need to be appended via appendCompaction() and appendBranchSummary() methods. */appendMessage(message: Message | CustomMessage | BashExecutionMessage): string {	const entry: SessionMessageEntry = {		type: "message",		id: generateId(this.byId),		parentId: this.leafId,		timestamp: new Date().toISOString(),		message,	};	this._appendEntry(entry);	return entry.id;}

/** * A new session file is created only once the session contains a user or assistant message. * 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). */private _hasConversation(): boolean {	return this.fileEntries.some(		(e) => e.type === "message" && (e.message.role === "user" || e.message.role === "assistant"),	);}_persist(entry: SessionEntry): void {	if (!this.persist || !this.sessionFile) return;	if (!this.flushed) {		if (!this._hasConversation()) return;		const fd = openSync(this.sessionFile, "wx");		try {			for (const e of this.fileEntries) {				writeFileSync(fd, `${JSON.stringify(e)}\n`);			}		} finally {			closeSync(fd);		}		this.flushed = true;	} else {		appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`);	}}

	while (true) {		const bytesRead = readSync(fd, buffer, 0, buffer.length, null);		if (bytesRead === 0) break;		pending += decoder.write(buffer.subarray(0, bytesRead));		let lineStart = 0;		let newlineIndex = pending.indexOf("\n", lineStart);		while (newlineIndex !== -1) {			const entry = parseSessionEntryLine(pending.slice(lineStart, newlineIndex));			if (entry) entries.push(entry);			lineStart = newlineIndex + 1;			newlineIndex = pending.indexOf("\n", lineStart);		}		pending = pending.slice(lineStart);	}	pending += decoder.end();	const finalEntry = parseSessionEntryLine(pending);	if (finalEntry) entries.push(finalEntry);} finally {	closeSync(fd);}// Validate session header before repairing the file.if (entries.length === 0) return entries;const header = entries[0];if (header.type !== "session" || typeof (header as { id?: unknown }).id !== "string") {	return [];}if (pending) appendFileSync(resolvedFilePath, "\n");return entries;

private _buildIndex(): void {	this.byId.clear();	this.labelsById.clear();	this.labelTimestampsById.clear();	this.leafId = null;	for (const entry of this.fileEntries) {		if (entry.type === "session") continue;		this.byId.set(entry.id, entry);		this.leafId = entry.id;		if (entry.type === "label") {			if (entry.label) {				this.labelsById.set(entry.targetId, entry.label);				this.labelTimestampsById.set(entry.targetId, entry.timestamp);			} else {				this.labelsById.delete(entry.targetId);				this.labelTimestampsById.delete(entry.targetId);			}		}	}}

/** 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;		// Convert firstKeptEntryIndex to firstKeptEntryId for compaction		if (entry.type === "compaction") {			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;			}		}	}}

/** * Run all necessary migrations to bring entries to current version. * Mutates entries in place. Returns true if any migration was applied. */function migrateToCurrentVersion(entries: FileEntry[]): boolean {	const header = entries.find((e) => e.type === "session") as SessionHeader | undefined;	const version = header?.version ?? 1;	if (version >= CURRENT_SESSION_VERSION) return false;	if (version < 2) migrateV1ToV2(entries);	if (version < 3) migrateV2ToV3(entries);	return true;}

function buildSessionPath(	entries: SessionEntry[],	leafId?: string | null,	byId?: Map<string, SessionEntry>,): SessionEntry[] {	const index = buildEntryIndex(entries, byId);	let leaf: SessionEntry | undefined;	if (leafId === null) {		return [];	}	if (leafId) {		leaf = index.get(leafId);	}	leaf ??= entries[entries.length - 1];	if (!leaf) {		return [];	}	const path: SessionEntry[] = [];	let current: SessionEntry | undefined = leaf;	while (current) {		path.push(current);		current = current.parentId ? index.get(current.parentId) : undefined;	}	path.reverse();	return path;}

export function buildContextEntries(	entries: SessionEntry[],	leafId?: string | null,	byId?: Map<string, SessionEntry>,): SessionEntry[] {	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 compactionIdx = path.findIndex((entry) => entry.id === compaction.id);	if (compactionIdx < 0) {		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));	return contextEntries;}

/** * Project one selected session entry into LLM/runtime messages. * Plain custom entries are display/state entries and do not participate in context. */export function sessionEntryToContextMessages(entry: SessionEntry): AgentMessage[] {	if (entry.type === "message") {		const message = entry.message;		// Session files are parsed without validation; old versions, forks, or		// hand-edited files can contain messages with null/missing content.		if (message.role === "system" && message.content == null) return [{ ...message, content: "" }];		if (			(message.role === "user" || message.role === "assistant" || message.role === "toolResult") &&			message.content == null		) {			return [{ ...message, content: [] }];		}		return [message];	}	if (entry.type === "custom_message") {		return [			createCustomMessage(entry.customType, entry.content ?? [], entry.display, entry.details, entry.timestamp),		];	}	if (entry.type === "branch_summary" && entry.summary) {		return [createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp)];	}	if (entry.type === "compaction") {		const summary = createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp);		return entry.systemMessage ? [entry.systemMessage, summary] : [summary];	}	return [];}

/** Build provenance-preserving, compaction-aware model context. */export function buildSessionProjection(	entries: SessionEntry[],	leafId?: string | null,	byId?: Map<string, SessionEntry>,): SessionProjection {	const path = buildSessionPath(entries, leafId, byId);	const { thinkingLevel, model } = getSessionContextSettings(path);	const contextEntries = buildContextEntries(entries, leafId, byId);	const edits = new Map<string, ContextEditEntry>();	for (const entry of contextEntries) {		if (entry.type === "context_edit") edits.set(entry.targetId, entry);	}	const projectedEntries = contextEntries.map(		(sourceEntry, index): ProjectedSessionEntry => ({			sourceEntry,			// buildContextEntries() may retain an older compaction entry because its			// raw ID lies inside the newest retained range. Only the newest compaction			// at index zero contributes a checkpoint and summary.			messages:				sourceEntry.type === "compaction" && index > 0					? []					: projectContextEntry(sourceEntry, edits.get(sourceEntry.id)),		}),	);	return {		entries: projectedEntries,		messages: projectedEntries.flatMap((entry) => entry.messages),		thinkingLevel,		model,	};}

/** * 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. Existing entries * are not modified or deleted. */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). * The next appendXXX() call will create a new root entry (parentId = null). * Use this when navigating to re-edit the first user message. */resetLeaf(): void {	this.leafId = null;}

branchWithSummary(	branchFromId: string | null,	summary: string,	details?: unknown,	fromHook?: boolean,	usage?: Usage,): string {	if (branchFromId !== null && !this.byId.has(branchFromId)) {		throw new Error(`Entry ${branchFromId} not found`);	}	const fromId = this.leafId ?? "root";	this.leafId = branchFromId;	const entry: BranchSummaryEntry = {		type: "branch_summary",		id: generateId(this.byId),		parentId: branchFromId,		timestamp: new Date().toISOString(),		fromId,		summary,		details,		usage,		fromHook,	};	this._appendEntry(entry);	return entry.id;}

// Determine the new leaf position based on target typelet newLeafId: string | null;let editorText: string | undefined;if (targetEntry.type === "message" && targetEntry.message.role === "user") {	// User message: leaf = parent (null if root), text goes to editor	newLeafId = targetEntry.parentId;	editorText = contentText(targetEntry.message.content, "");} else if (targetEntry.type === "custom_message") {	// Custom message: leaf = parent (null if root), text goes to editor	newLeafId = targetEntry.parentId;	editorText = contentText(targetEntry.content, "");} else {	// Non-user message: leaf = selected node	newLeafId = targetId;}

// Switch leaf (with or without summary)// Summary is attached at the navigation target position (newLeafId), not the old branchlet summaryEntry: BranchSummaryEntry | undefined;if (summaryText) {	// Create summary at target position (can be null for root)	const summaryId = this.sessionManager.branchWithSummary(		newLeafId,		summaryText,		summaryDetails,		fromExtension,		summaryUsage,	);	summaryEntry = this.sessionManager.getEntry(summaryId) as BranchSummaryEntry;	// Attach label to the summary entry	if (label) {		this.sessionManager.appendLabelChange(summaryId, label);	}} else if (newLeafId === null) {	// No summary, navigating to root - reset leaf	this.sessionManager.resetLeaf();} else {	// No summary, navigating to non-root	this.sessionManager.branch(newLeafId);}// Attach label to target entry when not summarizing (no summary entry to label)if (label && !summaryText) {	this.sessionManager.appendLabelChange(targetId, label);}

async fork(	entryId: string,	options?: { position?: "before" | "at"; withSession?: (ctx: ReplacedSessionContext) => Promise<void> },): Promise<{ cancelled: boolean; selectedText?: string }> {	const position = options?.position ?? "before";	const beforeResult = await this.emitBeforeFork(entryId, { position });	if (beforeResult.cancelled) {		return { cancelled: true };	}	let targetLeafId: string | null;	let selectedText: string | undefined;	const selectedEntry = this.session.sessionManager.getEntry(entryId);	if (!selectedEntry) {		throw new Error("Invalid entry ID for forking");	}	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);	}

createBranchedSession(leafId: string): string | undefined {	const previousSessionFile = this.sessionFile;	const path = this.getBranch(leafId);	if (path.length === 0) {		throw new Error(`Entry ${leafId} not found`);	}	// Filter out LabelEntry from path - we'll recreate them from the resolved map.	// Because labels are real tree entries, later entries can be children of labels;	// removing labels requires re-chaining the retained path to avoid orphaned subtrees.	const pathWithoutLabels: SessionEntry[] = [];	const replacementByLabelId = new Map<string, string>();	const pendingLabelIds: string[] = [];	let pathParentId: string | null = null;	for (const entry of path) {		if (entry.type === "label") {			pendingLabelIds.push(entry.id);			continue;		}		for (const labelId of pendingLabelIds) {			replacementByLabelId.set(labelId, entry.id);		}		pendingLabelIds.length = 0;		pathWithoutLabels.push(			entry.type === "compaction"				? {						...entry,						parentId: pathParentId,						firstKeptEntryId:							entry.firstKeptEntryId === entry.id								? entry.id								: (replacementByLabelId.get(entry.firstKeptEntryId) ?? entry.firstKeptEntryId),					}				: { ...entry, parentId: pathParentId },		);		pathParentId = entry.id;	}

// Create new session file with new ID but forked contentif (options?.id !== undefined) {	assertValidSessionId(options.id);}const newSessionId = options?.id ?? createSessionId();const timestamp = new Date().toISOString();const fileTimestamp = timestamp.replace(/[:.]/g, "-");const newSessionFile = join(dir, `${fileTimestamp}_${newSessionId}.jsonl`);// Write new header pointing to source as parent, with updated cwdconst newHeader: SessionHeader = {	type: "session",	version: CURRENT_SESSION_VERSION,	id: newSessionId,	timestamp,	cwd: resolvedTargetCwd,	parentSession: resolvedSourcePath,};writeFileSync(newSessionFile, `${JSON.stringify(newHeader)}\n`, { flag: "wx" });// Copy all non-header entries from sourcefor (const entry of sourceEntries) {	if (entry.type !== "session") {		appendFileSync(newSessionFile, `${JSON.stringify(entry)}\n`);	}}return new SessionManager(resolvedTargetCwd, dir, newSessionFile, true);

appendLabelChange(targetId: string, label: string | undefined): string {	if (!this.byId.has(targetId)) {		throw new Error(`Entry ${targetId} not found`);	}	const entry: LabelEntry = {		type: "label",		id: generateId(this.byId),		parentId: this.leafId,		timestamp: new Date().toISOString(),		targetId,		label,	};	this._appendEntry(entry);	if (label) {		this.labelsById.set(targetId, label);		this.labelTimestampsById.set(targetId, entry.timestamp);	} else {		this.labelsById.delete(targetId);		this.labelTimestampsById.delete(targetId);	}	return entry.id;}

/** Append a session info entry (e.g., display name). Returns entry id. */appendSessionInfo(name: string): string {	const sanitizedName = name.replace(/[\r\n]+/g, " ").trim();	const entry: SessionInfoEntry = {		type: "session_info",		id: generateId(this.byId),		parentId: this.leafId,		timestamp: new Date().toISOString(),		name: sanitizedName,	};	this._appendEntry(entry);	return entry.id;}/** Get the current session name from the latest session_info entry, if any. */getSessionName(): string | undefined {	// Walk entries in reverse to find the latest session_info entry.	// Empty names explicitly clear the session title. Reads fileEntries directly: the footer	// calls this on every frame, and getEntries() copies the whole session.	for (let i = this.fileEntries.length - 1; i >= 0; i--) {		const entry = this.fileEntries[i];		if (entry.type === "session_info") {			return entry.name?.trim() || undefined;		}	}	return undefined;}

async function resolveSessionPath(sessionArg: string, cwd: string, sessionDir?: string): Promise<ResolvedSession> {	// If it looks like a file path, resolve it before handing it to the session manager.	if (sessionArg.includes("/") || sessionArg.includes("\\") || sessionArg.endsWith(".jsonl")) {		return { type: "path", path: resolvePath(sessionArg, cwd) };	}	// Exact IDs only require reading session headers. Fall back to the full	// metadata listing for prefix matches.	const exactLocalMatch = findLocalSessionByExactId(sessionArg, cwd, sessionDir);	if (exactLocalMatch) {		return exactLocalMatch;	}	const localSessions = await SessionManager.list(cwd, sessionDir);	const localMatch = localSessions.find((s) => s.id.startsWith(sessionArg));	if (localMatch) {		return { type: "local", path: localMatch.path };	}	// Try global search across all projects	const allSessions = await SessionManager.listAll(sessionDir);	const globalMatch =		allSessions.find((s) => s.id === sessionArg) ?? allSessions.find((s) => s.id.startsWith(sessionArg));	if (globalMatch) {		return { type: "global", path: globalMatch.path, cwd: globalMatch.cwd };	}	// Not found anywhere	return { type: "not_found", arg: sessionArg };}

export function findMostRecentSession(sessionDir: string, cwd?: string): string | null {	const resolvedSessionDir = normalizePath(sessionDir);	const resolvedCwd = cwd ? resolvePath(cwd) : undefined;	try {		const files = readdirSync(resolvedSessionDir)			.filter((file) => file.endsWith(".jsonl"))			.map((file) => join(resolvedSessionDir, file))			.map((path) => ({ path, mtime: statSync(path).mtimeMs }))			.sort((a, b) => b.mtime - a.mtime);		for (const { path } of files) {			const header = readSessionHeaderForDiscovery(path);			if (header && (!resolvedCwd || sessionCwdMatches(getSessionHeaderCwd(header), resolvedCwd))) return path;		}		return null;	} catch {		// Directory access and stat races make recent-session discovery unavailable.		return null;	}}

export async function exportSessionToHtml(	sm: SessionManager,	state?: AgentState,	options?: ExportOptions | string,): Promise<string> {	const opts: ExportOptions = typeof options === "string" ? { outputPath: options } : options || {};	const sessionFile = sm.getSessionFile();	if (!sessionFile) {		throw new Error("Cannot export in-memory session to HTML");	}	if (!existsSync(sessionFile)) {		throw new Error("Nothing to export yet - start a conversation first");	}	const entries = sm.getEntries();⋯ lược bớt dòng 254–264	const sessionData: SessionData = {		header: sm.getHeader(),		entries,		leafId: sm.getLeafId(),		systemPrompt: state?.systemPrompt,		tools: state?.tools?.map((t) => ({ name: t.name, description: t.description, parameters: t.parameters })),		renderedTools,	};	const html = generateHtml(sessionData, opts.themeName);

export async function shareSession(context: SessionShareContext): Promise<void> {	const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-share-"));	const jsonlFile = path.join(tempDir, "session.jsonl");	const htmlFile = path.join(tempDir, "session.html");	try {		try {			exportSessionForShare(jsonlFile, context.session);		} catch (error: unknown) {			context.showError(`Failed to export session: ${error instanceof Error ? error.message : "Unknown error"}`);			return;		}		const destination = context.session.settingsManager.getSessionShareDestination();		if (destination !== "gist") {			if (await tryShareViaRadius(jsonlFile, context)) return;			if (destination === "radius") {				context.showError("Radius authentication is not configured. Run '/login radius' first.");				return;			}		}⋯ lược bớt dòng 77–88		try {			await context.session.exportToHtml(htmlFile, { themeName: theme.name });		} catch (error: unknown) {			context.showError(`Failed to export session: ${error instanceof Error ? error.message : "Unknown error"}`);			return;		}		await shareViaGist(htmlFile, context);