@prometheus-ai/agent 0.5.3 → 0.5.8

package/src/session/session-listing.ts

@@ -0,0 +1,588 @@
+import * as os from "node:os";
+import * as path from "node:path";
+import type { Message, TextContent } from "@prometheus-ai/ai";
+import { getAgentDir as getDefaultAgentDir, logger, parseJsonlLenient, toError } from "@prometheus-ai/utils";
+import { computeDefaultSessionDir } from "./session-paths";
+import { FileSessionStorage, type SessionStorage } from "./session-storage";
+
+/**
+ * Coarse lifecycle status of a session, derived from its last persisted message.
+ *
+ * - `complete` — the last assistant turn ended with no unanswered tool calls, i.e.
+ *   the agent yielded control back to the user.
+ * - `interrupted` — work was cut off mid-flight: a trailing assistant turn with
+ *   pending tool calls, a trailing tool result the agent never continued from, or
+ *   a length-truncated turn.
+ * - `aborted` — the last assistant turn was cancelled by the user.
+ * - `error` — the last assistant turn ended in an error.
+ * - `pending` — a trailing user message with no assistant reply persisted after it.
+ * - `unknown` — status could not be determined (empty/header-only session, or the
+ *   final message was larger than the tail window that was read).
+ */
+export type SessionStatus = "complete" | "interrupted" | "aborted" | "error" | "pending" | "unknown";
+
+export interface SessionInfo {
+	path: string;
+	id: string;
+	/** Working directory where the session was started. Empty string for old sessions. */
+	cwd: string;
+	title?: string;
+	/** Path to the parent session (if this session was forked). */
+	parentSessionPath?: string;
+	created: Date;
+	modified: Date;
+	messageCount: number;
+	/** File size in bytes on disk; used for compact list rendering. */
+	size: number;
+	firstMessage: string;
+	allMessagesText: string;
+	/**
+	 * Coarse lifecycle status from the session's last persisted message. Optional:
+	 * synthesized {@link SessionInfo}s (cross-project stubs, tests) leave it unset.
+	 */
+	status?: SessionStatus;
+}
+
+export interface ResolvedSessionMatch {
+	session: SessionInfo;
+	scope: "local" | "global";
+}
+
+/** Lightweight metadata for a recent session, used in welcome/picker UI. */
+export interface RecentSessionInfo {
+	path: string;
+	name: string;
+	timeAgo: string;
+}
+
+const SESSION_LIST_PREFIX_BYTES = 4096;
+/**
+ * Tail window read to derive {@link SessionStatus}. Large enough to capture a
+ * typical final assistant turn (thinking + text); when the final message exceeds
+ * it the status falls back to `unknown` rather than misreporting.
+ */
+const SESSION_LIST_SUFFIX_BYTES = 32_768;
+const SESSION_LIST_PARALLEL_THRESHOLD = 64;
+const SESSION_LIST_MAX_WORKERS = 16;
+
+function sanitizeSessionName(value: string | undefined): string | undefined {
+	if (!value) return undefined;
+	const firstLine = value.split(/\r?\n/)[0] ?? "";
+	const stripped = firstLine.replace(/[\x00-\x1F\x7F]/g, "");
+	const trimmed = stripped.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+/** Format a time difference as a human-readable string */
+function formatTimeAgo(date: Date): string {
+	const now = Date.now();
+	const diffMs = now - date.getTime();
+	const diffMins = Math.floor(diffMs / 60000);
+	const diffHours = Math.floor(diffMs / 3600000);
+	const diffDays = Math.floor(diffMs / 86400000);
+
+	if (diffMins < 1) return "just now";
+	if (diffMins < 60) return `${diffMins}m ago`;
+	if (diffHours < 24) return `${diffHours}h ago`;
+	if (diffDays < 7) return `${diffDays}d ago`;
+	return date.toLocaleDateString();
+}
+
+/**
+ * Friendly display name for a session: explicit title, then first user prompt,
+ * then a timestamp-based label. The raw UUID `id` is intentionally never used —
+ * it is unfriendly and indistinguishable from neighboring sessions in the UI.
+ */
+function sessionDisplayName(info: SessionInfo): string {
+	const title = sanitizeSessionName(info.title);
+	if (title) return title;
+	const first =
+		info.firstMessage && info.firstMessage !== "(no messages)" ? sanitizeSessionName(info.firstMessage) : undefined;
+	if (first) return first;
+	const created = info.created.getTime();
+	const ts = Number.isFinite(created) ? created : info.modified.getTime();
+	const date = new Date(ts);
+	const time = date.toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit" });
+	return `Untitled · ${time}`;
+}
+
+function extractTextFromContent(content: Message["content"]): string {
+	if (typeof content === "string") return content;
+	return content
+		.filter((block): block is TextContent => block.type === "text")
+		.map(block => block.text)
+		.join(" ");
+}
+
+/**
+ * Derive a {@link SessionStatus} from a tail window of a session file. Entries are
+ * newline-terminated on write, so within the window only the first line can be a
+ * partial fragment — it simply fails to parse and is skipped. We walk backwards to
+ * the last `message` entry and classify by its role / stop reason.
+ */
+function deriveSessionStatus(suffix: string): SessionStatus {
+	if (!suffix) return "unknown";
+	const lines = suffix.split("\n");
+	for (let i = lines.length - 1; i >= 0; i--) {
+		const line = lines[i];
+		// Every persisted entry is `JSON.stringify(obj)` → starts with `{`. This
+		// cheaply rejects blank lines and the leading partial fragment without
+		// attempting to parse a multi-KB tail of a truncated line.
+		if (line.charCodeAt(0) !== 123) continue;
+		let entry: { type?: string; message?: TailMessage };
+		try {
+			entry = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		if (entry.type === "message" && entry.message) {
+			return statusFromTailMessage(entry.message);
+		}
+	}
+	return "unknown";
+}
+
+interface TailMessage {
+	role?: string;
+	stopReason?: string;
+	content?: unknown;
+}
+
+function isToolCallBlock(block: unknown): boolean {
+	return typeof block === "object" && block !== null && (block as { type?: unknown }).type === "toolCall";
+}
+
+function statusFromTailMessage(message: TailMessage): SessionStatus {
+	switch (message.role) {
+		case "assistant": {
+			switch (message.stopReason) {
+				case "error":
+					return "error";
+				case "aborted":
+					return "aborted";
+				case "length":
+					return "interrupted";
+			}
+			// A turn that ends without unanswered tool calls means the agent yielded
+			// control back to the user — complete. Trailing tool calls (no tool
+			// results after) mean the loop was cut off before running them.
+			const content = message.content;
+			if (Array.isArray(content) && content.some(isToolCallBlock)) return "interrupted";
+			return "complete";
+		}
+		case "toolResult":
+			// Tools ran but the agent never produced the following assistant turn.
+			return "interrupted";
+		case "user":
+			// User message with no assistant reply persisted after it.
+			return "pending";
+		default:
+			return "unknown";
+	}
+}
+
+function decodeJsonStringFragment(value: string): string {
+	const safeValue = value.endsWith("\\") ? value.slice(0, -1) : value;
+	try {
+		return JSON.parse(`"${safeValue}"`) as string;
+	} catch {
+		return safeValue
+			.replace(/\\n/g, "\n")
+			.replace(/\\r/g, "\r")
+			.replace(/\\t/g, "\t")
+			.replace(/\\"/g, '"')
+			.replace(/\\\\/g, "\\");
+	}
+}
+
+function extractStringProperty(source: string, name: string, startIndex = 0): string | undefined {
+	const propertyIndex = source.indexOf(`"${name}"`, startIndex);
+	if (propertyIndex === -1) return undefined;
+
+	const colonIndex = source.indexOf(":", propertyIndex + name.length + 2);
+	if (colonIndex === -1) return undefined;
+
+	let valueIndex = colonIndex + 1;
+	while (valueIndex < source.length) {
+		const char = source.charCodeAt(valueIndex);
+		if (char !== 32 && char !== 9 && char !== 10 && char !== 13) break;
+		valueIndex++;
+	}
+	if (source.charCodeAt(valueIndex) !== 34) return undefined;
+
+	const valueStart = valueIndex + 1;
+	let escaped = false;
+	for (let i = valueStart; i < source.length; i++) {
+		const char = source.charCodeAt(i);
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (char === 92) {
+			escaped = true;
+			continue;
+		}
+		if (char === 34) {
+			return decodeJsonStringFragment(source.slice(valueStart, i));
+		}
+	}
+
+	return decodeJsonStringFragment(source.slice(valueStart));
+}
+
+function countMessageMarkers(content: string): number {
+	let count = 0;
+	let index = 0;
+	while (index < content.length) {
+		const typeIndex = content.indexOf('"type"', index);
+		if (typeIndex === -1) break;
+		const colonIndex = content.indexOf(":", typeIndex + 6);
+		if (colonIndex === -1) break;
+		const type = extractStringProperty(content, "type", typeIndex);
+		if (type === "message") count++;
+		index = colonIndex + 1;
+	}
+	return count;
+}
+
+function extractFirstUserMessageFromPrefix(content: string): string | undefined {
+	const roleIndex = content.indexOf('"role"');
+	if (roleIndex === -1) return undefined;
+
+	let index = roleIndex;
+	while (index !== -1) {
+		const role = extractStringProperty(content, "role", index);
+		if (role === "user") {
+			return extractStringProperty(content, "content", index) ?? extractStringProperty(content, "text", index);
+		}
+		index = content.indexOf('"role"', index + 6);
+	}
+
+	return undefined;
+}
+
+interface SessionListHeader {
+	type: "session";
+	id: string;
+	cwd?: string;
+	title?: string;
+	parentSession?: string;
+	timestamp?: string;
+}
+
+function parseSessionListHeader(
+	content: string,
+	entries: Array<Record<string, unknown>>,
+): SessionListHeader | undefined {
+	const parsedHeader = entries[0];
+	if (parsedHeader?.type === "session" && typeof parsedHeader.id === "string") {
+		return {
+			type: "session",
+			id: parsedHeader.id,
+			cwd: typeof parsedHeader.cwd === "string" ? parsedHeader.cwd : undefined,
+			title: typeof parsedHeader.title === "string" ? parsedHeader.title : undefined,
+			parentSession: typeof parsedHeader.parentSession === "string" ? parsedHeader.parentSession : undefined,
+			timestamp: typeof parsedHeader.timestamp === "string" ? parsedHeader.timestamp : undefined,
+		};
+	}
+
+	const firstLineEnd = content.indexOf("\n");
+	const firstLine = firstLineEnd === -1 ? content : content.slice(0, firstLineEnd);
+	if (extractStringProperty(firstLine, "type") !== "session") return undefined;
+
+	const id = extractStringProperty(firstLine, "id");
+	if (!id) return undefined;
+
+	return {
+		type: "session",
+		id,
+		cwd: extractStringProperty(firstLine, "cwd"),
+		title: extractStringProperty(firstLine, "title"),
+		parentSession: extractStringProperty(firstLine, "parentSession"),
+		timestamp: extractStringProperty(firstLine, "timestamp"),
+	};
+}
+
+function getSessionListWorkerCount(fileCount: number): number {
+	if (fileCount <= SESSION_LIST_PARALLEL_THRESHOLD) return 1;
+	return Math.min(
+		SESSION_LIST_MAX_WORKERS,
+		os.availableParallelism(),
+		Math.ceil(fileCount / SESSION_LIST_PARALLEL_THRESHOLD),
+	);
+}
+
+/**
+ * Scan a single session file into a {@link SessionInfo}. Always reads the 4 KB
+ * header/first-message prefix; only reads the 32 KB tail window (and derives
+ * {@link SessionStatus}) when `withStatus` is set — the recent/most-recent
+ * lookups skip it.
+ */
+async function scanSessionFile(
+	file: string,
+	storage: SessionStorage,
+	withStatus: boolean,
+): Promise<SessionInfo | undefined> {
+	try {
+		const stat = storage.statSync(file);
+		const [content, suffix] = await storage.readTextSlices(
+			file,
+			SESSION_LIST_PREFIX_BYTES,
+			withStatus ? SESSION_LIST_SUFFIX_BYTES : 0,
+		);
+		const { size, mtime } = stat;
+		const entries = parseJsonlLenient<Record<string, unknown>>(content);
+		const header = parseSessionListHeader(content, entries);
+		if (!header) return undefined;
+
+		let parsedMessageCount = 0;
+		let firstMessage = "";
+		const allMessages: string[] = [];
+		let shortSummary: string | undefined;
+
+		for (let i = 1; i < entries.length; i++) {
+			const entry = entries[i] as { type?: string; message?: Message; shortSummary?: string };
+
+			if (entry.type === "compaction" && typeof entry.shortSummary === "string") {
+				shortSummary = entry.shortSummary;
+			}
+
+			if (entry.type === "message" && entry.message) {
+				parsedMessageCount++;
+
+				if (entry.message.role === "user" || entry.message.role === "assistant") {
+					const textContent = extractTextFromContent(entry.message.content);
+
+					if (textContent) {
+						allMessages.push(textContent);
+
+						if (!firstMessage && entry.message.role === "user") {
+							firstMessage = textContent;
+						}
+					}
+				}
+			}
+		}
+
+		firstMessage ||= extractFirstUserMessageFromPrefix(content) ?? "";
+		const messageCount = Math.max(parsedMessageCount, countMessageMarkers(content));
+		return {
+			path: file,
+			id: header.id,
+			cwd: header.cwd ?? "",
+			title: header.title ?? shortSummary,
+			parentSessionPath: header.parentSession,
+			created: new Date(header.timestamp ?? ""),
+			modified: mtime,
+			messageCount,
+			size,
+			firstMessage: firstMessage || "(no messages)",
+			allMessagesText: allMessages.length > 0 ? allMessages.join(" ") : firstMessage,
+			status: withStatus ? deriveSessionStatus(suffix) : undefined,
+		};
+	} catch {
+		return undefined;
+	}
+}
+
+async function collectSessionsFromFileStride(
+	files: string[],
+	storage: SessionStorage,
+	startIndex: number,
+	stride: number,
+	withStatus: boolean,
+): Promise<SessionInfo[]> {
+	const sessions: SessionInfo[] = [];
+
+	for (let i = startIndex; i < files.length; i += stride) {
+		const session = await scanSessionFile(files[i], storage, withStatus);
+		if (session) sessions.push(session);
+	}
+
+	return sessions;
+}
+
+async function collectSessionsFromFiles(
+	files: string[],
+	storage: SessionStorage,
+	withStatus: boolean,
+): Promise<SessionInfo[]> {
+	const workerCount = getSessionListWorkerCount(files.length);
+	const sessions =
+		workerCount === 1
+			? await collectSessionsFromFileStride(files, storage, 0, 1, withStatus)
+			: (
+					await Promise.all(
+						Array.from({ length: workerCount }, (_, workerIndex) =>
+							collectSessionsFromFileStride(files, storage, workerIndex, workerCount, withStatus),
+						),
+					)
+				).flat();
+
+	sessions.sort((a, b) => b.modified.getTime() - a.modified.getTime());
+	return sessions;
+}
+
+/**
+ * Promote orphaned `<basename>.jsonl.<snowflake>.bak` backups created by the
+ * EPERM-rewrite path back to their primary path when the primary is missing.
+ * This runs once per session-dir scan, before the main `*.jsonl` glob, so a
+ * crash between the two renames in the EPERM-rewrite path does not leave the
+ * user's last good state stranded outside the loader's view.
+ *
+ * Exported for testing.
+ */
+export async function recoverOrphanedBackups(sessionDir: string, storage: SessionStorage): Promise<void> {
+	let backups: string[];
+	try {
+		backups = storage.listFilesSync(sessionDir, "*.bak");
+	} catch {
+		return;
+	}
+	if (backups.length === 0) return;
+	// For each primary path, pick the newest backup (highest mtime) as the recovery source.
+	const candidates = new Map<string, { backup: string; mtimeMs: number }>();
+	for (const backup of backups) {
+		const name = path.basename(backup);
+		// Expect "<primary>.<snowflake>.bak" where <primary> ends in ".jsonl".
+		if (!name.endsWith(".bak")) continue;
+		const trimmed = name.slice(0, -".bak".length);
+		const dotIdx = trimmed.lastIndexOf(".");
+		if (dotIdx <= 0) continue;
+		const primaryName = trimmed.slice(0, dotIdx);
+		if (!primaryName.endsWith(".jsonl")) continue;
+		const primaryPath = path.join(sessionDir, primaryName);
+		let mtimeMs = 0;
+		try {
+			mtimeMs = storage.statSync(backup).mtimeMs;
+		} catch {
+			continue;
+		}
+		const existing = candidates.get(primaryPath);
+		if (!existing || mtimeMs > existing.mtimeMs) {
+			candidates.set(primaryPath, { backup, mtimeMs });
+		}
+	}
+	for (const [primaryPath, { backup }] of candidates) {
+		if (storage.existsSync(primaryPath)) continue;
+		try {
+			await storage.rename(backup, primaryPath);
+			logger.warn("Recovered orphaned session backup", {
+				sessionFile: primaryPath,
+				backupPath: backup,
+			});
+		} catch (err) {
+			logger.warn("Failed to recover orphaned session backup", {
+				sessionFile: primaryPath,
+				backupPath: backup,
+				error: toError(err).message,
+			});
+		}
+	}
+}
+
+async function scanSessionDir(
+	sessionDir: string,
+	storage: SessionStorage,
+	withStatus: boolean,
+): Promise<SessionInfo[]> {
+	try {
+		await recoverOrphanedBackups(sessionDir, storage);
+		const files = storage.listFilesSync(sessionDir, "*.jsonl");
+		return await collectSessionsFromFiles(files, storage, withStatus);
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * List sessions in a resolved session directory (newest first), reading each
+ * file's lifecycle {@link SessionStatus}.
+ */
+export function listSessions(sessionDir: string, storage: SessionStorage): Promise<SessionInfo[]> {
+	return scanSessionDir(sessionDir, storage, true);
+}
+
+/** List all sessions across all project directories (newest first). */
+export async function listAllSessions(storage: SessionStorage = new FileSessionStorage()): Promise<SessionInfo[]> {
+	const sessionsRoot = path.join(getDefaultAgentDir(), "sessions");
+	try {
+		const files = await Array.fromAsync(new Bun.Glob("*/*.jsonl").scan(sessionsRoot), name =>
+			path.join(sessionsRoot, name),
+		);
+		return await collectSessionsFromFiles(files, storage, true);
+	} catch {
+		return [];
+	}
+}
+
+/** Exported for testing */
+export async function findMostRecentSession(
+	sessionDir: string,
+	storage: SessionStorage = new FileSessionStorage(),
+): Promise<string | null> {
+	const sessions = await scanSessionDir(sessionDir, storage, false);
+	return sessions[0]?.path ?? null;
+}
+
+/** Get recent sessions for display in the welcome screen. */
+export async function getRecentSessions(
+	sessionDir: string,
+	limit = 4,
+	storage: SessionStorage = new FileSessionStorage(),
+): Promise<RecentSessionInfo[]> {
+	const sessions = await scanSessionDir(sessionDir, storage, false);
+	const recent: RecentSessionInfo[] = [];
+	for (let i = 0; i < sessions.length && i < limit; i++) {
+		const info = sessions[i];
+		recent.push({ path: info.path, name: sessionDisplayName(info), timeAgo: formatTimeAgo(info.modified) });
+	}
+	return recent;
+}
+
+function sessionMatchesResumeArg(session: SessionInfo, sessionArg: string): boolean {
+	const normalizedArg = sessionArg.toLowerCase();
+	const normalizedId = session.id.toLowerCase();
+	if (normalizedId.startsWith(normalizedArg)) {
+		return true;
+	}
+
+	const fileName = path.basename(session.path, ".jsonl").toLowerCase();
+	if (fileName.startsWith(normalizedArg)) {
+		return true;
+	}
+
+	const separator = fileName.lastIndexOf("_");
+	if (separator < 0) {
+		return false;
+	}
+
+	const fileSessionId = fileName.slice(separator + 1);
+	return fileSessionId.startsWith(normalizedArg);
+}
+
+export async function resolveResumableSession(
+	sessionArg: string,
+	cwd: string,
+	sessionDir?: string,
+	storage: SessionStorage = new FileSessionStorage(),
+): Promise<ResolvedSessionMatch | undefined> {
+	const localSessionDir = sessionDir ?? computeDefaultSessionDir(cwd, storage);
+	const localSessions = await listSessions(localSessionDir, storage);
+	const localMatch = localSessions.find(session => sessionMatchesResumeArg(session, sessionArg));
+	if (localMatch) {
+		return { session: localMatch, scope: "local" };
+	}
+
+	if (sessionDir) {
+		return undefined;
+	}
+
+	const globalSessions = await listAllSessions(storage);
+	const globalMatch = globalSessions.find(session => sessionMatchesResumeArg(session, sessionArg));
+	if (!globalMatch) {
+		return undefined;
+	}
+
+	return { session: globalMatch, scope: "global" };
+}

package/src/session/session-loader.ts

@@ -0,0 +1,106 @@
+import type { AgentMessage } from "@prometheus-ai/agent-core";
+import { getBlobsDir, isEnoent, parseJsonlLenient } from "@prometheus-ai/utils";
+import { BlobStore, isBlobRef, resolveImageData, resolveImageDataUrl } from "./blob-store";
+import { buildSessionContext } from "./session-context";
+import type { FileEntry, SessionEntry, SessionHeader } from "./session-entries";
+import { migrateToCurrentVersion } from "./session-migrations";
+import { isImageBlock } from "./session-persistence";
+import { FileSessionStorage, type SessionStorage } from "./session-storage";
+
+/** Exported for compaction.test.ts */
+export function parseSessionEntries(content: string): FileEntry[] {
+	return parseJsonlLenient<FileEntry>(content);
+}
+
+/** Exported for testing */
+export async function loadEntriesFromFile(
+	filePath: string,
+	storage: SessionStorage = new FileSessionStorage(),
+): Promise<FileEntry[]> {
+	let content: string;
+	try {
+		content = await storage.readText(filePath);
+	} catch (err) {
+		if (isEnoent(err)) return [];
+		throw err;
+	}
+	const entries = parseJsonlLenient<FileEntry>(content);
+
+	// Validate session header
+	if (entries.length === 0) return entries;
+	const header = entries[0] as SessionHeader;
+	if (header.type !== "session" || typeof header.id !== "string") {
+		return [];
+	}
+
+	return entries;
+}
+
+/**
+ * Resolve blob references in loaded entries, restoring both session image blocks and persisted
+ * provider image URLs back to the inline data expected by downstream transports. Mutates entries in place.
+ */
+function hasImageUrl(value: unknown): value is { image_url: string } {
+	return typeof value === "object" && value !== null && "image_url" in value && typeof value.image_url === "string";
+}
+
+async function resolvePersistedImageUrlRefs(value: unknown, blobStore: BlobStore): Promise<void> {
+	if (Array.isArray(value)) {
+		await Promise.all(value.map(item => resolvePersistedImageUrlRefs(item, blobStore)));
+		return;
+	}
+
+	if (typeof value !== "object" || value === null) return;
+
+	if (hasImageUrl(value) && isBlobRef(value.image_url)) {
+		value.image_url = await resolveImageDataUrl(blobStore, value.image_url);
+	}
+
+	await Promise.all(Object.values(value).map(item => resolvePersistedImageUrlRefs(item, blobStore)));
+}
+
+export async function resolveBlobRefsInEntries(entries: FileEntry[], blobStore: BlobStore): Promise<void> {
+	const promises: Promise<void>[] = [];
+
+	for (const entry of entries) {
+		if (entry.type === "session") continue;
+
+		let contentArray: unknown[] | undefined;
+		if (entry.type === "message" && "content" in entry.message && Array.isArray(entry.message.content)) {
+			contentArray = entry.message.content;
+		} else if (entry.type === "custom_message" && Array.isArray(entry.content)) {
+			contentArray = entry.content;
+		}
+
+		if (contentArray) {
+			for (const block of contentArray) {
+				if (isImageBlock(block) && isBlobRef(block.data)) {
+					promises.push(
+						resolveImageData(blobStore, block.data).then(resolved => {
+							block.data = resolved;
+						}),
+					);
+				}
+			}
+		}
+
+		promises.push(resolvePersistedImageUrlRefs(entry, blobStore));
+	}
+
+	await Promise.all(promises);
+}
+
+/**
+ * Read-only message view of a session file: load entries, migrate to the
+ * current version, resolve blob refs, and build the context along the
+ * persisted leaf path (last entry). Does NOT create a writer or take the
+ * session lock — safe to call against a file another session is writing.
+ */
+export async function loadSessionMessagesReadOnly(filePath: string): Promise<AgentMessage[]> {
+	const entries = await loadEntriesFromFile(filePath);
+	if (entries.length === 0) return [];
+	migrateToCurrentVersion(entries);
+	await resolveBlobRefsInEntries(entries, new BlobStore(getBlobsDir()));
+	const sessionEntries = entries.filter((e): e is SessionEntry => e.type !== "session");
+	return buildSessionContext(sessionEntries).messages;
+}