Merge pull request #257 from code-yeongyu/perf/render-hotpath-cache

code-yeongyu · web-flow · commit 23f560c19828 · 2026-07-21T18:32:38.000+09:00
perf(coding-agent): cache materialized session views behind mutation counter
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
@@ -11,6 +11,7 @@
 ### Changed
 
 ### Fixed
+- Fixed the interactive render hot path re-materializing the entire session every frame: `SessionManager.getEntries()`, no-arg `getBranch()`, and `getSessionName()` are now memoized behind a monotonic mutation counter, eliminating repeated deep copies of large sessions at frame rate.
 
 ### Removed
 
diff --git a/packages/coding-agent/src/core/changes.md b/packages/coding-agent/src/core/changes.md
@@ -1,5 +1,24 @@
 # changes
 
+## Memoized materialized session views (2026-07-21)
+
+### What changed
+
+- `session-manager.ts`: added a monotonic `mutationCount` bumped by every mutator (`_appendEntry`, `branch()`,
+  `resetLeaf()`, `setSessionFile`, `newSession`, `createBranchedSession`). `getEntries()` is memoized on
+  `mutationCount`, no-arg `getBranch()` on `(leafId, mutationCount)` (explicit `fromId` bypasses), and
+  `getSessionName()` is O(1) via a cached value maintained on `appendSessionInfo`/`_buildIndex` (empty name still
+  clears the title). `getEntries()` now returns a shared cached array callers must not mutate.
+
+### Why extension system couldn't handle this alone
+
+- The mutation surface and resident-store materialization are private to `SessionManager`; external wrappers cannot
+  observe every invalidation point.
+
+### Expected merge conflict zones
+
+- LOW: private fields and the listed getters; upstream rarely touches `SessionManager` internals.
+
 ## Smooth streaming settings (2026-07-20)
 
 ### What changed
diff --git a/packages/coding-agent/src/core/session-manager.ts b/packages/coding-agent/src/core/session-manager.ts
@@ -50,6 +50,15 @@ import {
 	createCustomMessage,
 } from "./messages.ts";
 
+export interface UsageTotals {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	latestCacheHitRate: number | undefined;
+}
+
 export const CURRENT_SESSION_VERSION = 3;
 
 export interface SessionHeader {
@@ -873,6 +882,24 @@ export class SessionManager {
 	private labelTimestampsById: Map<string, string> = new Map();
 	private leafId: string | null = null;
 	private residentStore = new ResidentStringStore();
+	// Monotonic counter bumped by every mutator; memoized materialized views are
+	// keyed on it so read hot paths (footer, RPC) never re-materialize unchanged sessions.
+	private mutationCount = 0;
+	private entriesCache: { mutation: number; entries: SessionEntry[] } | null = null;
+	private branchCache: { leafId: string | null; mutation: number; entries: SessionEntry[] } | null = null;
+	private sessionNameCache: string | undefined = undefined;
+	// Running usage totals over ALL entries (not branch-scoped), maintained
+	// incrementally on assistant-message append and rebuilt from scratch in
+	// _buildIndex()/newSession. Usage fields are numeric and unaffected by
+	// string externalization, so the resident form can be read directly.
+	private usageTotals: UsageTotals = {
+		input: 0,
+		output: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		cost: 0,
+		latestCacheHitRate: undefined,
+	};
 
 	private constructor(
 		cwd: string,
@@ -925,6 +952,7 @@ export class SessionManager {
 
 			this.fileEntries = this.fileEntries.map((entry) => this.residentStore.externalize(entry));
 			this._buildIndex();
+			this.mutationCount++;
 			this.flushed = true;
 		} else {
 			const explicitPath = this.sessionFile;
@@ -953,6 +981,16 @@ export class SessionManager {
 		this.labelsById.clear();
 		this.labelTimestampsById.clear();
 		this.leafId = null;
+		this.sessionNameCache = undefined;
+		this.usageTotals = {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			cost: 0,
+			latestCacheHitRate: undefined,
+		};
+		this.mutationCount++;
 		this.flushed = false;
 
 		if (this.persist) {
@@ -967,10 +1005,24 @@ export class SessionManager {
 		this.labelsById.clear();
 		this.labelTimestampsById.clear();
 		this.leafId = null;
+		this.sessionNameCache = undefined;
+		this.usageTotals = {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			cost: 0,
+			latestCacheHitRate: undefined,
+		};
 		for (const entry of this.fileEntries) {
 			if (entry.type === "session") continue;
 			this.byId.set(entry.id, entry);
 			this.leafId = entry.id;
+			this._accumulateUsage(entry);
+			if (entry.type === "session_info") {
+				// Empty names explicitly clear the session title.
+				this.sessionNameCache = entry.name?.trim() || undefined;
+			}
 			if (entry.type === "label") {
 				if (entry.label) {
 					this.labelsById.set(entry.targetId, entry.label);
@@ -1058,9 +1110,39 @@ export class SessionManager {
 		this.fileEntries.push(residentEntry);
 		this.byId.set(residentEntry.id, residentEntry);
 		this.leafId = residentEntry.id;
+		this._accumulateUsage(residentEntry);
+		this.mutationCount++;
 		this._persist(residentEntry);
 	}
 
+	/**
+	 * Fold one entry into the running usage totals. Totals iterate ALL entries
+	 * (not branch-scoped), matching the footer hot path's historical semantics.
+	 */
+	private _accumulateUsage(entry: SessionEntry): void {
+		if (entry.type !== "message" || entry.message.role !== "assistant") return;
+		const usage = entry.message.usage;
+		// Assistant messages persisted without usage (e.g. aborted/error turns in
+		// older session files) contribute nothing to the running totals.
+		if (!usage) return;
+		this.usageTotals.input += usage.input;
+		this.usageTotals.output += usage.output;
+		this.usageTotals.cacheRead += usage.cacheRead;
+		this.usageTotals.cacheWrite += usage.cacheWrite;
+		this.usageTotals.cost += usage.cost?.total ?? 0;
+		const latestPromptTokens = usage.input + usage.cacheRead + usage.cacheWrite;
+		this.usageTotals.latestCacheHitRate =
+			latestPromptTokens > 0 ? (usage.cacheRead / latestPromptTokens) * 100 : undefined;
+	}
+
+	/**
+	 * O(1) running usage totals across ALL session entries (not branch-scoped).
+	 * Maintained incrementally; identical to summing usage over getEntries().
+	 */
+	getUsageTotals(): UsageTotals {
+		return this.usageTotals;
+	}
+
 	/** 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,
@@ -1162,22 +1244,17 @@ export class SessionManager {
 			timestamp: new Date().toISOString(),
 			name: sanitizedName,
 		};
+		this.sessionNameCache = sanitizedName || undefined;
 		this._appendEntry(entry);
 		return entry.id;
 	}
 
-	/** Get the current session name from the latest session_info entry, if any. */
+	/**
+	 * Get the current session name from the latest session_info entry, if any.
+	 * O(1): the value is maintained incrementally on appendSessionInfo() and index rebuilds.
+	 */
 	getSessionName(): string | undefined {
-		// Walk entries in reverse to find the latest session_info entry.
-		// Empty names explicitly clear the session title.
-		const entries = this.getEntries();
-		for (let i = entries.length - 1; i >= 0; i--) {
-			const entry = entries[i];
-			if (entry.type === "session_info") {
-				return entry.name?.trim() || undefined;
-			}
-		}
-		return undefined;
+		return this.sessionNameCache;
 	}
 
 	/**
@@ -1280,13 +1357,26 @@ export class SessionManager {
 	 * Use buildSessionContext() to get the resolved messages for the LLM.
 	 */
 	getBranch(fromId?: string): SessionEntry[] {
+		// No-arg reads (the common hot path) are memoized on (leafId, mutationCount);
+		// explicit fromId lookups bypass the cache.
+		if (
+			fromId === undefined &&
+			this.branchCache !== null &&
+			this.branchCache.leafId === this.leafId &&
+			this.branchCache.mutation === this.mutationCount
+		) {
+			return this.branchCache.entries;
+		}
 		const path: SessionEntry[] = [];
 		const startId = fromId ?? this.leafId;
 		let current = startId ? this.byId.get(startId) : undefined;
 		while (current) {
 			path.unshift(this.residentStore.materialize(current));
 			current = current.parentId ? this.byId.get(current.parentId) : undefined;
 		}
+		if (fromId === undefined) {
+			this.branchCache = { leafId: this.leafId, mutation: this.mutationCount, entries: path };
+		}
 		return path;
 	}
 
@@ -1346,14 +1436,24 @@ export class SessionManager {
 	}
 
 	/**
-	 * Get all session entries (excludes header). Returns a shallow copy.
+	 * Get all session entries (excludes header).
 	 * The session is append-only: use appendXXX() to add entries, branch() to
 	 * change the leaf pointer. Entries cannot be modified or deleted.
+	 *
+	 * The result is memoized behind the session mutation counter: repeated calls
+	 * without an intervening mutation return the SAME shared array instance.
+	 * Callers must not mutate the returned array or its entries; copy first if
+	 * you need to filter/reorder.
 	 */
 	getEntries(): SessionEntry[] {
-		return this.fileEntries
+		if (this.entriesCache !== null && this.entriesCache.mutation === this.mutationCount) {
+			return this.entriesCache.entries;
+		}
+		const entries = this.fileEntries
 			.filter((e): e is SessionEntry => e.type !== "session")
 			.map((entry) => this.residentStore.materialize(entry));
+		this.entriesCache = { mutation: this.mutationCount, entries };
+		return entries;
 	}
 
 	/**
@@ -1416,6 +1516,7 @@ export class SessionManager {
 			throw new Error(`Entry ${branchFromId} not found`);
 		}
 		this.leafId = branchFromId;
+		this.mutationCount++;
 	}
 
 	/**
@@ -1425,6 +1526,7 @@ export class SessionManager {
 	 */
 	resetLeaf(): void {
 		this.leafId = null;
+		this.mutationCount++;
 	}
 
 	/**
@@ -1523,6 +1625,7 @@ export class SessionManager {
 			this.sessionId = newSessionId;
 			this.sessionFile = newSessionFile;
 			this._buildIndex();
+			this.mutationCount++;
 
 			// Only write the file now if it contains an assistant message.
 			// Otherwise defer to _persist(), which creates the file on the
@@ -1561,6 +1664,7 @@ export class SessionManager {
 		);
 		this.sessionId = newSessionId;
 		this._buildIndex();
+		this.mutationCount++;
 		return undefined;
 	}
 
diff --git a/packages/coding-agent/src/modes/interactive/components/footer.ts b/packages/coding-agent/src/modes/interactive/components/footer.ts
@@ -106,27 +106,15 @@ export class FooterComponent implements Component {
 	render(width: number): string[] {
 		const state = this.session.state;
 
-		let totalInput = 0;
-		let totalOutput = 0;
-		let totalCacheRead = 0;
-		let totalCacheWrite = 0;
-		let totalCost = 0;
-		let latestCacheHitRate: number | undefined;
-
-		for (const entry of this.session.sessionManager.getEntries()) {
-			if (entry.type === "message" && entry.message.role === "assistant") {
-				totalInput += entry.message.usage.input;
-				totalOutput += entry.message.usage.output;
-				totalCacheRead += entry.message.usage.cacheRead;
-				totalCacheWrite += entry.message.usage.cacheWrite;
-				totalCost += entry.message.usage.cost.total;
-
-				const latestPromptTokens =
-					entry.message.usage.input + entry.message.usage.cacheRead + entry.message.usage.cacheWrite;
-				latestCacheHitRate =
-					latestPromptTokens > 0 ? (entry.message.usage.cacheRead / latestPromptTokens) * 100 : undefined;
-			}
-		}
+		// O(1) running totals maintained by SessionManager (identical to summing
+		// usage over all entries; totals are not branch-scoped).
+		const usageTotals = this.session.sessionManager.getUsageTotals();
+		const totalInput = usageTotals.input;
+		const totalOutput = usageTotals.output;
+		const totalCacheRead = usageTotals.cacheRead;
+		const totalCacheWrite = usageTotals.cacheWrite;
+		const totalCost = usageTotals.cost;
+		const latestCacheHitRate = usageTotals.latestCacheHitRate;
 
 		// Calculate context usage from session (handles compaction correctly).
 		// After compaction, tokens are unknown until the next LLM response.
diff --git a/packages/coding-agent/test/footer-token-format.test.ts b/packages/coding-agent/test/footer-token-format.test.ts
@@ -35,6 +35,14 @@ function createSession(): unknown {
 					},
 				},
 			],
+			getUsageTotals: () => ({
+				input: 49,
+				output: 6_800,
+				cacheRead: 1_500_000,
+				cacheWrite: 44_000,
+				cost: 0,
+				latestCacheHitRate: (1_500_000 / (49 + 1_500_000 + 44_000)) * 100,
+			}),
 			getSessionName: () => "",
 			getCwd: () => "/tmp/project",
 		},
diff --git a/packages/coding-agent/test/footer-width.test.ts b/packages/coding-agent/test/footer-width.test.ts
@@ -48,6 +48,30 @@ function createSession(options: {
 		},
 		sessionManager: {
 			getEntries: () => entries,
+			getUsageTotals: () => {
+				const totals = {
+					input: 0,
+					output: 0,
+					cacheRead: 0,
+					cacheWrite: 0,
+					cost: 0,
+					latestCacheHitRate: undefined as number | undefined,
+				};
+				for (const entry of entries) {
+					if (entry.type === "message" && entry.message.role === "assistant") {
+						totals.input += entry.message.usage.input;
+						totals.output += entry.message.usage.output;
+						totals.cacheRead += entry.message.usage.cacheRead;
+						totals.cacheWrite += entry.message.usage.cacheWrite;
+						totals.cost += entry.message.usage.cost.total;
+						const latestPromptTokens =
+							entry.message.usage.input + entry.message.usage.cacheRead + entry.message.usage.cacheWrite;
+						totals.latestCacheHitRate =
+							latestPromptTokens > 0 ? (entry.message.usage.cacheRead / latestPromptTokens) * 100 : undefined;
+					}
+				}
+				return totals;
+			},
 			getSessionName: () => options.sessionName,
 			getCwd: () => "/tmp/project",
 		},
diff --git a/packages/coding-agent/test/session-manager/materialize-cache.test.ts b/packages/coding-agent/test/session-manager/materialize-cache.test.ts
diff --git a/packages/coding-agent/test/session-manager/usage-totals.test.ts b/packages/coding-agent/test/session-manager/usage-totals.test.ts
