WIP: Context compaction core logic (#92)

- Add CompactionEntry type with firstKeptEntryIndex
- Add loadSessionFromEntries() for compaction-aware loading
- Add compact() function that returns CompactionEntry
- Add token calculation and cut point detection
- Add tests with real session fixture and LLM integration

Still TODO: settings, /compact and /autocompact commands, auto-trigger in TUI, /branch rework

packages/coding-agent/src/compaction.ts

@@ -0,0 +1,266 @@
+/**
+ * Context compaction for long sessions.
+ *
+ * Pure functions for compaction logic. The session manager handles I/O,
+ * and after compaction the session is reloaded.
+ */
+
+import type { AppMessage } from "@mariozechner/pi-agent-core";
+import type { AssistantMessage, Model, Usage } from "@mariozechner/pi-ai";
+import { complete } from "@mariozechner/pi-ai";
+import { type CompactionEntry, loadSessionFromEntries, type SessionEntry } from "./session-manager.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface CompactionSettings {
+	enabled: boolean;
+	reserveTokens: number;
+	keepRecentTokens: number;
+}
+
+export const DEFAULT_COMPACTION_SETTINGS: CompactionSettings = {
+	enabled: true,
+	reserveTokens: 16384,
+	keepRecentTokens: 20000,
+};
+
+// ============================================================================
+// Token calculation
+// ============================================================================
+
+/**
+ * Calculate total context tokens from usage.
+ */
+export function calculateContextTokens(usage: Usage): number {
+	return usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
+}
+
+/**
+ * Get usage from an assistant message if available.
+ */
+function getAssistantUsage(msg: AppMessage): Usage | null {
+	if (msg.role === "assistant" && "usage" in msg) {
+		const assistantMsg = msg as AssistantMessage;
+		if (assistantMsg.stopReason !== "aborted" && assistantMsg.usage) {
+			return assistantMsg.usage;
+		}
+	}
+	return null;
+}
+
+/**
+ * Find the last non-aborted assistant message usage from session entries.
+ */
+export function getLastAssistantUsage(entries: SessionEntry[]): Usage | null {
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		if (entry.type === "message") {
+			const usage = getAssistantUsage(entry.message);
+			if (usage) return usage;
+		}
+	}
+	return null;
+}
+
+/**
+ * Check if compaction should trigger based on context usage.
+ */
+export function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean {
+	if (!settings.enabled) return false;
+	return contextTokens > contextWindow - settings.reserveTokens;
+}
+
+// ============================================================================
+// Cut point detection
+// ============================================================================
+
+/**
+ * Find indices of message entries that are user messages (turn boundaries).
+ */
+function findTurnBoundaries(entries: SessionEntry[], startIndex: number, endIndex: number): number[] {
+	const boundaries: number[] = [];
+	for (let i = startIndex; i < endIndex; i++) {
+		const entry = entries[i];
+		if (entry.type === "message" && entry.message.role === "user") {
+			boundaries.push(i);
+		}
+	}
+	return boundaries;
+}
+
+/**
+ * Find the cut point in session entries that keeps approximately `keepRecentTokens`.
+ * Returns the entry index of the first message to keep (a user message for turn integrity).
+ *
+ * Only considers entries between `startIndex` and `endIndex` (exclusive).
+ */
+export function findCutPoint(
+	entries: SessionEntry[],
+	startIndex: number,
+	endIndex: number,
+	keepRecentTokens: number,
+): number {
+	const boundaries = findTurnBoundaries(entries, startIndex, endIndex);
+
+	if (boundaries.length === 0) {
+		return startIndex; // No user messages, keep everything in range
+	}
+
+	// Collect assistant usages walking backwards from endIndex
+	const assistantUsages: Array<{ index: number; tokens: number }> = [];
+	for (let i = endIndex - 1; i >= startIndex; i--) {
+		const entry = entries[i];
+		if (entry.type === "message") {
+			const usage = getAssistantUsage(entry.message);
+			if (usage) {
+				assistantUsages.push({
+					index: i,
+					tokens: calculateContextTokens(usage),
+				});
+			}
+		}
+	}
+
+	if (assistantUsages.length === 0) {
+		// No usage info, keep last turn only
+		return boundaries[boundaries.length - 1];
+	}
+
+	// Walk through and find where cumulative token difference exceeds keepRecentTokens
+	const newestTokens = assistantUsages[0].tokens;
+	let cutIndex = startIndex; // Default: keep everything in range
+
+	for (let i = 1; i < assistantUsages.length; i++) {
+		const tokenDiff = newestTokens - assistantUsages[i].tokens;
+		if (tokenDiff >= keepRecentTokens) {
+			// Find the turn boundary at or before the assistant we want to keep
+			const lastKeptAssistantIndex = assistantUsages[i - 1].index;
+
+			for (let b = boundaries.length - 1; b >= 0; b--) {
+				if (boundaries[b] <= lastKeptAssistantIndex) {
+					cutIndex = boundaries[b];
+					break;
+				}
+			}
+			break;
+		}
+	}
+
+	return cutIndex;
+}
+
+// ============================================================================
+// Summarization
+// ============================================================================
+
+const SUMMARIZATION_PROMPT = `You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary for another LLM that will resume the task.
+
+Include:
+- Current progress and key decisions made
+- Important context, constraints, or user preferences
+- Absolute file paths of any relevant files that were read or modified
+- What remains to be done (clear next steps)
+- Any critical data, examples, or references needed to continue
+
+Be concise, structured, and focused on helping the next LLM seamlessly continue the work.`;
+
+/**
+ * Generate a summary of the conversation using the LLM.
+ */
+export async function generateSummary(
+	currentMessages: AppMessage[],
+	model: Model<any>,
+	reserveTokens: number,
+	apiKey: string,
+	signal?: AbortSignal,
+	customInstructions?: string,
+): Promise<string> {
+	const maxTokens = Math.floor(0.8 * reserveTokens);
+
+	const prompt = customInstructions
+		? `${SUMMARIZATION_PROMPT}\n\nAdditional focus: ${customInstructions}`
+		: SUMMARIZATION_PROMPT;
+
+	const summarizationMessages = [
+		...currentMessages,
+		{
+			role: "user" as const,
+			content: prompt,
+			timestamp: Date.now(),
+		},
+	];
+
+	const response = await complete(model, { messages: summarizationMessages }, { maxTokens, signal, apiKey });
+
+	const textContent = response.content
+		.filter((c): c is { type: "text"; text: string } => c.type === "text")
+		.map((c) => c.text)
+		.join("\n");
+
+	return textContent;
+}
+
+// ============================================================================
+// Main compaction function
+// ============================================================================
+
+/**
+ * Calculate compaction and generate summary.
+ * Returns the CompactionEntry to append to the session file.
+ *
+ * @param entries - All session entries
+ * @param model - Model to use for summarization
+ * @param settings - Compaction settings
+ * @param apiKey - API key for LLM
+ * @param signal - Optional abort signal
+ * @param customInstructions - Optional custom focus for the summary
+ */
+export async function compact(
+	entries: SessionEntry[],
+	model: Model<any>,
+	settings: CompactionSettings,
+	apiKey: string,
+	signal?: AbortSignal,
+	customInstructions?: string,
+): Promise<CompactionEntry> {
+	// Reconstruct current messages from entries
+	const { messages: currentMessages } = loadSessionFromEntries(entries);
+
+	// Find previous compaction boundary
+	let prevCompactionIndex = -1;
+	for (let i = entries.length - 1; i >= 0; i--) {
+		if (entries[i].type === "compaction") {
+			prevCompactionIndex = i;
+			break;
+		}
+	}
+	const boundaryStart = prevCompactionIndex + 1;
+	const boundaryEnd = entries.length;
+
+	// Get token count before compaction
+	const lastUsage = getLastAssistantUsage(entries);
+	const tokensBefore = lastUsage ? calculateContextTokens(lastUsage) : 0;
+
+	// Find cut point (entry index) within the valid range
+	const firstKeptEntryIndex = findCutPoint(entries, boundaryStart, boundaryEnd, settings.keepRecentTokens);
+
+	// Generate summary from the full current context
+	const summary = await generateSummary(
+		currentMessages,
+		model,
+		settings.reserveTokens,
+		apiKey,
+		signal,
+		customInstructions,
+	);
+
+	return {
+		type: "compaction",
+		timestamp: new Date().toISOString(),
+		summary,
+		firstKeptEntryIndex,
+		tokensBefore,
+	};
+}

packages/coding-agent/src/session-manager.ts

@@ -12,6 +12,10 @@ function uuidv4(): string {
 	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
 }
 
+// ============================================================================
+// Session entry types
+// ============================================================================
+
 export interface SessionHeader {
 	type: "session";
 	id: string;
@@ -20,7 +24,7 @@ export interface SessionHeader {
 	provider: string;
 	modelId: string;
 	thinkingLevel: string;
-	branchedFrom?: string; // Path to the session file this was branched from
+	branchedFrom?: string;
 }
 
 export interface SessionMessageEntry {
@@ -42,6 +46,129 @@ export interface ModelChangeEntry {
 	modelId: string;
 }
 
+export interface CompactionEntry {
+	type: "compaction";
+	timestamp: string;
+	summary: string;
+	firstKeptEntryIndex: number; // Index into session entries where we start keeping
+	tokensBefore: number;
+}
+
+/** Union of all session entry types */
+export type SessionEntry =
+	| SessionHeader
+	| SessionMessageEntry
+	| ThinkingLevelChangeEntry
+	| ModelChangeEntry
+	| CompactionEntry;
+
+// ============================================================================
+// Session loading with compaction support
+// ============================================================================
+
+export interface LoadedSession {
+	messages: AppMessage[];
+	thinkingLevel: string;
+	model: { provider: string; modelId: string } | null;
+}
+
+const SUMMARY_PREFIX = `Another language model worked on this task and produced a summary. Use this to continue the work without duplicating effort:
+
+`;
+
+/**
+ * Create a user message containing the summary with the standard prefix.
+ */
+export function createSummaryMessage(summary: string): AppMessage {
+	return {
+		role: "user",
+		content: SUMMARY_PREFIX + summary,
+		timestamp: Date.now(),
+	};
+}
+
+/**
+ * Parse session file content into entries.
+ */
+export function parseSessionEntries(content: string): SessionEntry[] {
+	const entries: SessionEntry[] = [];
+	const lines = content.trim().split("\n");
+
+	for (const line of lines) {
+		if (!line.trim()) continue;
+		try {
+			const entry = JSON.parse(line) as SessionEntry;
+			entries.push(entry);
+		} catch {
+			// Skip malformed lines
+		}
+	}
+
+	return entries;
+}
+
+/**
+ * Load session from entries, handling compaction events.
+ *
+ * Algorithm:
+ * 1. Find latest compaction event (if any)
+ * 2. Keep all entries from firstKeptEntryIndex onwards (extracting messages)
+ * 3. Prepend summary as user message
+ */
+export function loadSessionFromEntries(entries: SessionEntry[]): LoadedSession {
+	// Find model and thinking level (always scan all entries)
+	let thinkingLevel = "off";
+	let model: { provider: string; modelId: string } | null = null;
+
+	for (const entry of entries) {
+		if (entry.type === "session") {
+			thinkingLevel = entry.thinkingLevel;
+			model = { provider: entry.provider, modelId: entry.modelId };
+		} else if (entry.type === "thinking_level_change") {
+			thinkingLevel = entry.thinkingLevel;
+		} else if (entry.type === "model_change") {
+			model = { provider: entry.provider, modelId: entry.modelId };
+		}
+	}
+
+	// Find latest compaction event
+	let latestCompactionIndex = -1;
+	for (let i = entries.length - 1; i >= 0; i--) {
+		if (entries[i].type === "compaction") {
+			latestCompactionIndex = i;
+			break;
+		}
+	}
+
+	// No compaction: return all messages
+	if (latestCompactionIndex === -1) {
+		const messages: AppMessage[] = [];
+		for (const entry of entries) {
+			if (entry.type === "message") {
+				messages.push(entry.message);
+			}
+		}
+		return { messages, thinkingLevel, model };
+	}
+
+	const compactionEvent = entries[latestCompactionIndex] as CompactionEntry;
+
+	// Extract messages from firstKeptEntryIndex to end (skipping compaction entries)
+	const keptMessages: AppMessage[] = [];
+	for (let i = compactionEvent.firstKeptEntryIndex; i < entries.length; i++) {
+		const entry = entries[i];
+		if (entry.type === "message") {
+			keptMessages.push(entry.message);
+		}
+	}
+
+	// Build final messages: summary + kept messages
+	const summaryMessage = createSummaryMessage(compactionEvent.summary);
+	const messages = [summaryMessage, ...keptMessages];
+
+	return { messages, thinkingLevel, model };
+}
+
 export class SessionManager {
 	private sessionId!: string;
 	private sessionFile!: string;
@@ -208,77 +335,38 @@ export class SessionManager {
 		}
 	}
 
-	loadMessages(): any[] {
-		if (!existsSync(this.sessionFile)) return [];
-
-		const messages: any[] = [];
-		const lines = readFileSync(this.sessionFile, "utf8").trim().split("\n");
-
-		for (const line of lines) {
-			try {
-				const entry = JSON.parse(line);
-				if (entry.type === "message") {
-					messages.push(entry.message);
-				}
-			} catch {
-				// Skip malformed lines
-			}
-		}
-
-		return messages;
+	saveCompaction(entry: CompactionEntry): void {
+		if (!this.enabled) return;
+		appendFileSync(this.sessionFile, JSON.stringify(entry) + "\n");
 	}
 
+	/**
+	 * Load session data (messages, model, thinking level) with compaction support.
+	 */
+	loadSession(): LoadedSession {
+		const entries = this.loadEntries();
+		return loadSessionFromEntries(entries);
+	}
+
+	/**
+	 * @deprecated Use loadSession().messages instead
+	 */
+	loadMessages(): AppMessage[] {
+		return this.loadSession().messages;
+	}
+
+	/**
+	 * @deprecated Use loadSession().thinkingLevel instead
+	 */
 	loadThinkingLevel(): string {
-		if (!existsSync(this.sessionFile)) return "off";
-
-		const lines = readFileSync(this.sessionFile, "utf8").trim().split("\n");
-
-		// Find the most recent thinking level (from session header or change event)
-		let lastThinkingLevel = "off";
-		for (const line of lines) {
-			try {
-				const entry = JSON.parse(line);
-				if (entry.type === "session" && entry.thinkingLevel) {
-					lastThinkingLevel = entry.thinkingLevel;
-				} else if (entry.type === "thinking_level_change" && entry.thinkingLevel) {
-					lastThinkingLevel = entry.thinkingLevel;
-				}
-			} catch {
-				// Skip malformed lines
-			}
-		}
-
-		return lastThinkingLevel;
+		return this.loadSession().thinkingLevel;
 	}
 
+	/**
+	 * @deprecated Use loadSession().model instead
+	 */
 	loadModel(): { provider: string; modelId: string } | null {
-		if (!existsSync(this.sessionFile)) return null;
-
-		const lines = readFileSync(this.sessionFile, "utf8").trim().split("\n");
-
-		// Find the most recent model (from session header or change event)
-		let lastProvider: string | null = null;
-		let lastModelId: string | null = null;
-
-		for (const line of lines) {
-			try {
-				const entry = JSON.parse(line);
-				if (entry.type === "session" && entry.provider && entry.modelId) {
-					lastProvider = entry.provider;
-					lastModelId = entry.modelId;
-				} else if (entry.type === "model_change" && entry.provider && entry.modelId) {
-					lastProvider = entry.provider;
-					lastModelId = entry.modelId;
-				}
-			} catch {
-				// Skip malformed lines
-			}
-		}
-
-		if (lastProvider && lastModelId) {
-			return { provider: lastProvider, modelId: lastModelId };
-		}
-		return null;
+		return this.loadSession().model;
 	}
 
 	getSessionId(): string {
@@ -289,6 +377,29 @@ export class SessionManager {
 		return this.sessionFile;
 	}
 
+	/**
+	 * Load all entries from the session file.
+	 */
+	loadEntries(): SessionEntry[] {
+		if (!existsSync(this.sessionFile)) return [];
+
+		const content = readFileSync(this.sessionFile, "utf8");
+		const entries: SessionEntry[] = [];
+		const lines = content.trim().split("\n");
+
+		for (const line of lines) {
+			if (!line.trim()) continue;
+			try {
+				const entry = JSON.parse(line) as SessionEntry;
+				entries.push(entry);
+			} catch {
+				// Skip malformed lines
+			}
+		}
+
+		return entries;
+	}
+
 	/**
 	 * Load all sessions for the current directory with metadata
 	 */

packages/coding-agent/test/compaction.test.ts

@@ -0,0 +1,414 @@
+import type { AppMessage } from "@mariozechner/pi-agent-core";
+import type { AssistantMessage, Usage } from "@mariozechner/pi-ai";
+import { getModel } from "@mariozechner/pi-ai";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { describe, expect, it } from "vitest";
+import {
+	type CompactionSettings,
+	calculateContextTokens,
+	compact,
+	DEFAULT_COMPACTION_SETTINGS,
+	findCutPoint,
+	getLastAssistantUsage,
+	shouldCompact,
+} from "../src/compaction.js";
+import {
+	type CompactionEntry,
+	createSummaryMessage,
+	loadSessionFromEntries,
+	parseSessionEntries,
+	type SessionEntry,
+	type SessionMessageEntry,
+} from "../src/session-manager.js";
+
+// ============================================================================
+// Test fixtures
+// ============================================================================
+
+function loadLargeSessionEntries(): SessionEntry[] {
+	const sessionPath = join(__dirname, "fixtures/large-session.jsonl");
+	const content = readFileSync(sessionPath, "utf-8");
+	return parseSessionEntries(content);
+}
+
+function createMockUsage(input: number, output: number, cacheRead = 0, cacheWrite = 0): Usage {
+	return {
+		input,
+		output,
+		cacheRead,
+		cacheWrite,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+	};
+}
+
+function createUserMessage(text: string): AppMessage {
+	return { role: "user", content: text, timestamp: Date.now() };
+}
+
+function createAssistantMessage(text: string, usage?: Usage): AssistantMessage {
+	return {
+		role: "assistant",
+		content: [{ type: "text", text }],
+		usage: usage || createMockUsage(100, 50),
+		stopReason: "stop",
+		timestamp: Date.now(),
+		api: "anthropic-messages",
+		provider: "anthropic",
+		model: "claude-sonnet-4-5",
+	};
+}
+
+function createMessageEntry(message: AppMessage): SessionMessageEntry {
+	return { type: "message", timestamp: new Date().toISOString(), message };
+}
+
+function createCompactionEntry(summary: string, firstKeptEntryIndex: number): CompactionEntry {
+	return {
+		type: "compaction",
+		timestamp: new Date().toISOString(),
+		summary,
+		firstKeptEntryIndex,
+		tokensBefore: 10000,
+	};
+}
+
+// ============================================================================
+// Unit tests
+// ============================================================================
+
+describe("Token calculation", () => {
+	it("should calculate total context tokens from usage", () => {
+		const usage = createMockUsage(1000, 500, 200, 100);
+		expect(calculateContextTokens(usage)).toBe(1800);
+	});
+
+	it("should handle zero values", () => {
+		const usage = createMockUsage(0, 0, 0, 0);
+		expect(calculateContextTokens(usage)).toBe(0);
+	});
+});
+
+describe("getLastAssistantUsage", () => {
+	it("should find the last non-aborted assistant message usage", () => {
+		const entries: SessionEntry[] = [
+			createMessageEntry(createUserMessage("Hello")),
+			createMessageEntry(createAssistantMessage("Hi", createMockUsage(100, 50))),
+			createMessageEntry(createUserMessage("How are you?")),
+			createMessageEntry(createAssistantMessage("Good", createMockUsage(200, 100))),
+		];
+
+		const usage = getLastAssistantUsage(entries);
+		expect(usage).not.toBeNull();
+		expect(usage!.input).toBe(200);
+	});
+
+	it("should skip aborted messages", () => {
+		const abortedMsg: AssistantMessage = {
+			...createAssistantMessage("Aborted", createMockUsage(300, 150)),
+			stopReason: "aborted",
+		};
+
+		const entries: SessionEntry[] = [
+			createMessageEntry(createUserMessage("Hello")),
+			createMessageEntry(createAssistantMessage("Hi", createMockUsage(100, 50))),
+			createMessageEntry(createUserMessage("How are you?")),
+			createMessageEntry(abortedMsg),
+		];
+
+		const usage = getLastAssistantUsage(entries);
+		expect(usage).not.toBeNull();
+		expect(usage!.input).toBe(100);
+	});
+
+	it("should return null if no assistant messages", () => {
+		const entries: SessionEntry[] = [createMessageEntry(createUserMessage("Hello"))];
+		expect(getLastAssistantUsage(entries)).toBeNull();
+	});
+});
+
+describe("shouldCompact", () => {
+	it("should return true when context exceeds threshold", () => {
+		const settings: CompactionSettings = {
+			enabled: true,
+			reserveTokens: 10000,
+			keepRecentTokens: 20000,
+		};
+
+		expect(shouldCompact(95000, 100000, settings)).toBe(true);
+		expect(shouldCompact(89000, 100000, settings)).toBe(false);
+	});
+
+	it("should return false when disabled", () => {
+		const settings: CompactionSettings = {
+			enabled: false,
+			reserveTokens: 10000,
+			keepRecentTokens: 20000,
+		};
+
+		expect(shouldCompact(95000, 100000, settings)).toBe(false);
+	});
+});
+
+describe("findCutPoint", () => {
+	it("should find cut point based on actual token differences", () => {
+		// Create entries with cumulative token counts
+		const entries: SessionEntry[] = [];
+		for (let i = 0; i < 10; i++) {
+			entries.push(createMessageEntry(createUserMessage(`User ${i}`)));
+			entries.push(
+				createMessageEntry(createAssistantMessage(`Assistant ${i}`, createMockUsage(0, 100, (i + 1) * 1000, 0))),
+			);
+		}
+
+		// 20 entries, last assistant has 10000 tokens
+		// keepRecentTokens = 2500: keep entries where diff < 2500
+		const cutPoint = findCutPoint(entries, 0, entries.length, 2500);
+
+		// Should cut at a user message entry
+		expect(entries[cutPoint].type).toBe("message");
+		expect((entries[cutPoint] as SessionMessageEntry).message.role).toBe("user");
+	});
+
+	it("should return startIndex if no user messages in range", () => {
+		const entries: SessionEntry[] = [createMessageEntry(createAssistantMessage("a"))];
+		expect(findCutPoint(entries, 0, entries.length, 1000)).toBe(0);
+	});
+
+	it("should keep everything if all messages fit within budget", () => {
+		const entries: SessionEntry[] = [
+			createMessageEntry(createUserMessage("1")),
+			createMessageEntry(createAssistantMessage("a", createMockUsage(0, 50, 500, 0))),
+			createMessageEntry(createUserMessage("2")),
+			createMessageEntry(createAssistantMessage("b", createMockUsage(0, 50, 1000, 0))),
+		];
+
+		const cutPoint = findCutPoint(entries, 0, entries.length, 50000);
+		expect(cutPoint).toBe(0);
+	});
+});
+
+describe("createSummaryMessage", () => {
+	it("should create user message with prefix", () => {
+		const msg = createSummaryMessage("This is the summary");
+		expect(msg.role).toBe("user");
+		expect(msg.content).toContain("Another language model worked on this task");
+		expect(msg.content).toContain("This is the summary");
+	});
+});
+
+describe("loadSessionFromEntries", () => {
+	it("should load all messages when no compaction", () => {
+		const entries: SessionEntry[] = [
+			{
+				type: "session",
+				id: "1",
+				timestamp: "",
+				cwd: "",
+				provider: "anthropic",
+				modelId: "claude",
+				thinkingLevel: "off",
+			},
+			createMessageEntry(createUserMessage("1")),
+			createMessageEntry(createAssistantMessage("a")),
+			createMessageEntry(createUserMessage("2")),
+			createMessageEntry(createAssistantMessage("b")),
+		];
+
+		const loaded = loadSessionFromEntries(entries);
+		expect(loaded.messages.length).toBe(4);
+		expect(loaded.thinkingLevel).toBe("off");
+		expect(loaded.model).toEqual({ provider: "anthropic", modelId: "claude" });
+	});
+
+	it("should handle single compaction", () => {
+		// indices: 0=session, 1=u1, 2=a1, 3=u2, 4=a2, 5=compaction, 6=u3, 7=a3
+		const entries: SessionEntry[] = [
+			{
+				type: "session",
+				id: "1",
+				timestamp: "",
+				cwd: "",
+				provider: "anthropic",
+				modelId: "claude",
+				thinkingLevel: "off",
+			},
+			createMessageEntry(createUserMessage("1")),
+			createMessageEntry(createAssistantMessage("a")),
+			createMessageEntry(createUserMessage("2")),
+			createMessageEntry(createAssistantMessage("b")),
+			createCompactionEntry("Summary of 1,a,2,b", 3), // keep from index 3 (u2) onwards
+			createMessageEntry(createUserMessage("3")),
+			createMessageEntry(createAssistantMessage("c")),
+		];
+
+		const loaded = loadSessionFromEntries(entries);
+		// summary + kept (u2,a2 from idx 3-4) + after (u3,a3 from idx 6-7) = 5
+		expect(loaded.messages.length).toBe(5);
+		expect(loaded.messages[0].role).toBe("user");
+		expect((loaded.messages[0] as any).content).toContain("Summary of 1,a,2,b");
+	});
+
+	it("should handle multiple compactions (only latest matters)", () => {
+		// indices: 0=session, 1=u1, 2=a1, 3=compact1, 4=u2, 5=b, 6=u3, 7=c, 8=compact2, 9=u4, 10=d
+		const entries: SessionEntry[] = [
+			{
+				type: "session",
+				id: "1",
+				timestamp: "",
+				cwd: "",
+				provider: "anthropic",
+				modelId: "claude",
+				thinkingLevel: "off",
+			},
+			createMessageEntry(createUserMessage("1")),
+			createMessageEntry(createAssistantMessage("a")),
+			createCompactionEntry("First summary", 1), // keep from index 1
+			createMessageEntry(createUserMessage("2")),
+			createMessageEntry(createAssistantMessage("b")),
+			createMessageEntry(createUserMessage("3")),
+			createMessageEntry(createAssistantMessage("c")),
+			createCompactionEntry("Second summary", 6), // keep from index 6 (u3) onwards
+			createMessageEntry(createUserMessage("4")),
+			createMessageEntry(createAssistantMessage("d")),
+		];
+
+		const loaded = loadSessionFromEntries(entries);
+		// summary + kept from idx 6 (u3,c) + after (u4,d) = 5
+		expect(loaded.messages.length).toBe(5);
+		expect((loaded.messages[0] as any).content).toContain("Second summary");
+	});
+
+	it("should clamp firstKeptEntryIndex to valid range", () => {
+		// indices: 0=session, 1=u1, 2=a1, 3=compact1, 4=u2, 5=b, 6=compact2
+		const entries: SessionEntry[] = [
+			{
+				type: "session",
+				id: "1",
+				timestamp: "",
+				cwd: "",
+				provider: "anthropic",
+				modelId: "claude",
+				thinkingLevel: "off",
+			},
+			createMessageEntry(createUserMessage("1")),
+			createMessageEntry(createAssistantMessage("a")),
+			createCompactionEntry("First summary", 1),
+			createMessageEntry(createUserMessage("2")),
+			createMessageEntry(createAssistantMessage("b")),
+			createCompactionEntry("Second summary", 0), // index 0 is before compaction1, should still work
+		];
+
+		const loaded = loadSessionFromEntries(entries);
+		// Keeps from index 0, but compaction entries are skipped, so u1,a1,u2,b = 4 + summary = 5
+		// Actually index 0 is session header, so messages are u1,a1,u2,b
+		expect(loaded.messages.length).toBe(5); // summary + 4 messages
+	});
+
+	it("should track model and thinking level changes", () => {
+		const entries: SessionEntry[] = [
+			{
+				type: "session",
+				id: "1",
+				timestamp: "",
+				cwd: "",
+				provider: "anthropic",
+				modelId: "claude",
+				thinkingLevel: "off",
+			},
+			createMessageEntry(createUserMessage("1")),
+			{ type: "model_change", timestamp: "", provider: "openai", modelId: "gpt-4" },
+			createMessageEntry(createAssistantMessage("a")),
+			{ type: "thinking_level_change", timestamp: "", thinkingLevel: "high" },
+		];
+
+		const loaded = loadSessionFromEntries(entries);
+		expect(loaded.model).toEqual({ provider: "openai", modelId: "gpt-4" });
+		expect(loaded.thinkingLevel).toBe("high");
+	});
+});
+
+// ============================================================================
+// Integration tests with real session data
+// ============================================================================
+
+describe("Large session fixture", () => {
+	it("should parse the large session", () => {
+		const entries = loadLargeSessionEntries();
+		expect(entries.length).toBeGreaterThan(100);
+
+		const messageCount = entries.filter((e) => e.type === "message").length;
+		expect(messageCount).toBeGreaterThan(100);
+	});
+
+	it("should find cut point in large session", () => {
+		const entries = loadLargeSessionEntries();
+		const cutPoint = findCutPoint(entries, 0, entries.length, DEFAULT_COMPACTION_SETTINGS.keepRecentTokens);
+
+		// Cut point should be at a message entry with user role
+		expect(entries[cutPoint].type).toBe("message");
+		expect((entries[cutPoint] as SessionMessageEntry).message.role).toBe("user");
+	});
+
+	it("should load session correctly", () => {
+		const entries = loadLargeSessionEntries();
+		const loaded = loadSessionFromEntries(entries);
+
+		expect(loaded.messages.length).toBeGreaterThan(100);
+		expect(loaded.model).not.toBeNull();
+	});
+});
+
+// ============================================================================
+// LLM integration tests (skipped without API key)
+// ============================================================================
+
+describe.skipIf(!process.env.ANTHROPIC_OAUTH_TOKEN)("LLM summarization", () => {
+	it("should generate a compaction event for the large session", async () => {
+		const entries = loadLargeSessionEntries();
+		const model = getModel("anthropic", "claude-sonnet-4-5")!;
+
+		const compactionEvent = await compact(
+			entries,
+			model,
+			DEFAULT_COMPACTION_SETTINGS,
+			process.env.ANTHROPIC_OAUTH_TOKEN!,
+		);
+
+		expect(compactionEvent.type).toBe("compaction");
+		expect(compactionEvent.summary.length).toBeGreaterThan(100);
+		expect(compactionEvent.firstKeptEntryIndex).toBeGreaterThan(0);
+		expect(compactionEvent.tokensBefore).toBeGreaterThan(0);
+
+		console.log("Summary length:", compactionEvent.summary.length);
+		console.log("First kept entry index:", compactionEvent.firstKeptEntryIndex);
+		console.log("Tokens before:", compactionEvent.tokensBefore);
+		console.log("\n--- SUMMARY ---\n");
+		console.log(compactionEvent.summary);
+	}, 60000);
+
+	it("should produce valid session after compaction", async () => {
+		const entries = loadLargeSessionEntries();
+		const loaded = loadSessionFromEntries(entries);
+		const model = getModel("anthropic", "claude-sonnet-4-5")!;
+
+		const compactionEvent = await compact(
+			entries,
+			model,
+			DEFAULT_COMPACTION_SETTINGS,
+			process.env.ANTHROPIC_OAUTH_TOKEN!,
+		);
+
+		// Simulate appending compaction to entries
+		const newEntries = [...entries, compactionEvent];
+		const reloaded = loadSessionFromEntries(newEntries);
+
+		// Should have summary + kept messages
+		expect(reloaded.messages.length).toBeLessThan(loaded.messages.length);
+		expect(reloaded.messages[0].role).toBe("user");
+		expect((reloaded.messages[0] as any).content).toContain(compactionEvent.summary);
+
+		console.log("Original messages:", loaded.messages.length);
+		console.log("After compaction:", reloaded.messages.length);
+	}, 60000);
+});