test: add coverage for readLastMessagePreviewFromTranscript

Also add CHANGELOG entry and perf docs for session list flags.

CHANGELOG.md

@@ -63,6 +63,7 @@ Docs: https://docs.clawd.bot
 - Usage: add `/usage cost` summaries and macOS menu cost submenu with daily charting.
 - Agents: clarify node_modules read-only guidance in agent instructions.
 - TUI: add syntax highlighting for code blocks. (#1200) — thanks @vignesh07.
+- TUI: session picker shows derived titles, fuzzy search, relative times, and last message preview.
 
 ### Fixes
 - UI: enable shell mode for sync Windows spawns to avoid `pnpm ui:build` EINVAL. (#1212) — thanks @longmaba.

src/gateway/protocol/schema/sessions.ts

@@ -8,7 +8,15 @@ export const SessionsListParamsSchema = Type.Object(
 		activeMinutes: Type.Optional(Type.Integer({ minimum: 1 })),
 		includeGlobal: Type.Optional(Type.Boolean()),
 		includeUnknown: Type.Optional(Type.Boolean()),
+		/**
+		 * Read first 8KB of each session transcript to derive title from first user message.
+		 * Performs a file read per session - use `limit` to bound result set on large stores.
+		 */
 		includeDerivedTitles: Type.Optional(Type.Boolean()),
+		/**
+		 * Read last 16KB of each session transcript to extract most recent message preview.
+		 * Performs a file read per session - use `limit` to bound result set on large stores.
+		 */
 		includeLastMessage: Type.Optional(Type.Boolean()),
 		label: Type.Optional(SessionLabelString),
 		spawnedBy: Type.Optional(NonEmptyString),

src/gateway/session-utils.fs.test.ts

@@ -2,7 +2,10 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, test } from "vitest";
-import { readFirstUserMessageFromTranscript } from "./session-utils.fs.js";
+import {
+	readFirstUserMessageFromTranscript,
+	readLastMessagePreviewFromTranscript,
+} from "./session-utils.fs.js";
 
 describe("readFirstUserMessageFromTranscript", () => {
 	let tmpDir: string;
@@ -112,9 +115,7 @@ describe("readFirstUserMessageFromTranscript", () => {
 	test("trims whitespace from message content", () => {
 		const sessionId = "test-session-7";
 		const transcriptPath = path.join(tmpDir, `${sessionId}.jsonl`);
-    const lines = [
+		const lines = [JSON.stringify({ message: { role: "user", content: "  Padded message  " } })];
-      JSON.stringify({ message: { role: "user", content: "  Padded message  " } }),
-    ];
 		fs.writeFileSync(transcriptPath, lines.join("\n"), "utf-8");
 
 		const result = readFirstUserMessageFromTranscript(sessionId, storePath);
@@ -134,3 +135,176 @@ describe("readFirstUserMessageFromTranscript", () => {
 		expect(result).toBe("Second message");
 	});
 });
+
+describe("readLastMessagePreviewFromTranscript", () => {
+	let tmpDir: string;
+	let storePath: string;
+
+	beforeEach(() => {
+		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "clawdbot-session-fs-test-"));
+		storePath = path.join(tmpDir, "sessions.json");
+	});
+
+	afterEach(() => {
+		fs.rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	test("returns null when transcript file does not exist", () => {
+		const result = readLastMessagePreviewFromTranscript("nonexistent-session", storePath);
+		expect(result).toBeNull();
+	});
+
+	test("returns null for empty file", () => {
+		const sessionId = "test-last-empty";
+		const transcriptPath = path.join(tmpDir, `${sessionId}.jsonl`);
+		fs.writeFileSync(transcriptPath, "", "utf-8");
+
+		const result = readLastMessagePreviewFromTranscript(sessionId, storePath);
+		expect(result).toBeNull();
+	});
+
+	test("returns last user message from transcript", () => {
+		const sessionId = "test-last-user";
+		const transcriptPath = path.join(tmpDir, `${sessionId}.jsonl`);
+		const lines = [
+			JSON.stringify({ message: { role: "user", content: "First user" } }),
+			JSON.stringify({ message: { role: "assistant", content: "First assistant" } }),
+			JSON.stringify({ message: { role: "user", content: "Last user message" } }),
+		];
+		fs.writeFileSync(transcriptPath, lines.join("\n"), "utf-8");
+
+		const result = readLastMessagePreviewFromTranscript(sessionId, storePath);
+		expect(result).toBe("Last user message");
+	});
+
+	test("returns last assistant message from transcript", () => {
+		const sessionId = "test-last-assistant";
+		const transcriptPath = path.join(tmpDir, `${sessionId}.jsonl`);
+		const lines = [
+			JSON.stringify({ message: { role: "user", content: "User question" } }),
+			JSON.stringify({ message: { role: "assistant", content: "Final assistant reply" } }),
+		];
+		fs.writeFileSync(transcriptPath, lines.join("\n"), "utf-8");
+
+		const result = readLastMessagePreviewFromTranscript(sessionId, storePath);
+		expect(result).toBe("Final assistant reply");
+	});
+
+	test("skips system messages to find last user/assistant", () => {
+		const sessionId = "test-last-skip-system";
+		const transcriptPath = path.join(tmpDir, `${sessionId}.jsonl`);
+		const lines = [
+			JSON.stringify({ message: { role: "user", content: "Real last" } }),
+			JSON.stringify({ message: { role: "system", content: "System at end" } }),
+		];
+		fs.writeFileSync(transcriptPath, lines.join("\n"), "utf-8");
+
+		const result = readLastMessagePreviewFromTranscript(sessionId, storePath);
+		expect(result).toBe("Real last");
+	});
+
+	test("returns null when no user/assistant messages exist", () => {
+		const sessionId = "test-last-no-match";
+		const transcriptPath = path.join(tmpDir, `${sessionId}.jsonl`);
+		const lines = [
+			JSON.stringify({ type: "session", version: 1, id: sessionId }),
+			JSON.stringify({ message: { role: "system", content: "Only system" } }),
+		];
+		fs.writeFileSync(transcriptPath, lines.join("\n"), "utf-8");
+
+		const result = readLastMessagePreviewFromTranscript(sessionId, storePath);
+		expect(result).toBeNull();
+	});
+
+	test("handles malformed JSON lines gracefully", () => {
+		const sessionId = "test-last-malformed";
+		const transcriptPath = path.join(tmpDir, `${sessionId}.jsonl`);
+		const lines = [
+			JSON.stringify({ message: { role: "user", content: "Valid first" } }),
+			"not valid json at end",
+		];
+		fs.writeFileSync(transcriptPath, lines.join("\n"), "utf-8");
+
+		const result = readLastMessagePreviewFromTranscript(sessionId, storePath);
+		expect(result).toBe("Valid first");
+	});
+
+	test("handles array content format", () => {
+		const sessionId = "test-last-array";
+		const transcriptPath = path.join(tmpDir, `${sessionId}.jsonl`);
+		const lines = [
+			JSON.stringify({
+				message: {
+					role: "assistant",
+					content: [{ type: "text", text: "Array content response" }],
+				},
+			}),
+		];
+		fs.writeFileSync(transcriptPath, lines.join("\n"), "utf-8");
+
+		const result = readLastMessagePreviewFromTranscript(sessionId, storePath);
+		expect(result).toBe("Array content response");
+	});
+
+	test("uses sessionFile parameter when provided", () => {
+		const sessionId = "test-last-custom";
+		const customPath = path.join(tmpDir, "custom-last.jsonl");
+		const lines = [JSON.stringify({ message: { role: "user", content: "Custom file last" } })];
+		fs.writeFileSync(customPath, lines.join("\n"), "utf-8");
+
+		const result = readLastMessagePreviewFromTranscript(sessionId, storePath, customPath);
+		expect(result).toBe("Custom file last");
+	});
+
+	test("trims whitespace from message content", () => {
+		const sessionId = "test-last-trim";
+		const transcriptPath = path.join(tmpDir, `${sessionId}.jsonl`);
+		const lines = [
+			JSON.stringify({ message: { role: "assistant", content: "  Padded response  " } }),
+		];
+		fs.writeFileSync(transcriptPath, lines.join("\n"), "utf-8");
+
+		const result = readLastMessagePreviewFromTranscript(sessionId, storePath);
+		expect(result).toBe("Padded response");
+	});
+
+	test("skips empty content to find previous message", () => {
+		const sessionId = "test-last-skip-empty";
+		const transcriptPath = path.join(tmpDir, `${sessionId}.jsonl`);
+		const lines = [
+			JSON.stringify({ message: { role: "assistant", content: "Has content" } }),
+			JSON.stringify({ message: { role: "user", content: "" } }),
+		];
+		fs.writeFileSync(transcriptPath, lines.join("\n"), "utf-8");
+
+		const result = readLastMessagePreviewFromTranscript(sessionId, storePath);
+		expect(result).toBe("Has content");
+	});
+
+	test("reads from end of large file (16KB window)", () => {
+		const sessionId = "test-last-large";
+		const transcriptPath = path.join(tmpDir, `${sessionId}.jsonl`);
+		const padding = JSON.stringify({ message: { role: "user", content: "x".repeat(500) } });
+		const lines: string[] = [];
+		for (let i = 0; i < 50; i++) {
+			lines.push(padding);
+		}
+		lines.push(JSON.stringify({ message: { role: "assistant", content: "Last in large file" } }));
+		fs.writeFileSync(transcriptPath, lines.join("\n"), "utf-8");
+
+		const result = readLastMessagePreviewFromTranscript(sessionId, storePath);
+		expect(result).toBe("Last in large file");
+	});
+
+	test("handles valid UTF-8 content", () => {
+		const sessionId = "test-last-utf8";
+		const transcriptPath = path.join(tmpDir, `${sessionId}.jsonl`);
+		const validLine = JSON.stringify({
+			message: { role: "user", content: "Valid UTF-8: 你好世界 🌍" },
+		});
+		fs.writeFileSync(transcriptPath, validLine, "utf-8");
+
+		const result = readLastMessagePreviewFromTranscript(sessionId, storePath);
+		expect(result).toBe("Valid UTF-8: 你好世界 🌍");
+	});
+});

src/tui/components/fuzzy-filter.ts

@@ -101,9 +101,9 @@ export function fuzzyFilterLower<T extends { searchTextLower?: string }>(
 /**
  * Prepare items for fuzzy filtering by pre-computing lowercase search text.
  */
-export function prepareSearchItems<
+export function prepareSearchItems<T extends { label?: string; description?: string; searchText?: string }>(
-	T extends { label?: string; description?: string; searchText?: string },
+	items: T[],
->(items: T[]): (T & { searchTextLower: string })[] {
+): (T & { searchTextLower: string })[] {
 	return items.map((item) => {
 		const parts: string[] = [];
 		if (item.label) parts.push(item.label);