Skip to content

A self-improving RLM agent for coding workflows and long-running autonomous tasks.

Rust

[RSI, performance] perf(coding-agent): cache context-tree child parses keyed by file stats (#2477)

Sebastian Müllerab11746ca1d4
diff --git a/packages/coding-agent/.changes/context-tree-cache.md b/packages/coding-agent/.changes/context-tree-cache.md
new file mode 100644
index 0000000000..b06b3e39b5
--- /dev/null
+++ b/packages/coding-agent/.changes/context-tree-cache.md
@@ -0,0 +1 @@
+- Context-tree rebuilds (top-bar cost refresh, /context) now reuse a per-file parse cache keyed by file size and mtime instead of re-reading every finished child session on each refresh.
diff --git a/packages/coding-agent/src/core/agent-session.ts b/packages/coding-agent/src/core/agent-session.ts
index d0536e925c..9ca4390f57 100644
--- a/packages/coding-agent/src/core/agent-session.ts
+++ b/packages/coding-agent/src/core/agent-session.ts
@@ -14503,9 +14503,9 @@ export class AgentSession {
/**
* Build the agent context overview for /context: this session as the root
- * plus one node per RLM sub-agent, recursively. Running children are read
- * from their live sessions; completed children from their persisted session
- * dirs, so the tree survives child disposal and session resume.
+ * plus one node per RLM sub-agent, recursively. Running and resident
+ * finished children come from their live sessions, others from their
+ * persisted session dirs, so the tree survives child disposal and session resume.
*/
getContextTree(): ContextTreeNode {
const resolveContextWindow = this._contextWindowResolver();
@@ -14530,7 +14530,35 @@ export class AgentSession {
status: run.status,
});
}
- children.push(...loadContextTreeChildrenFromDisk(this._rlmSessionDirForReading(), resolveContextWindow, liveIds));
+ // Resident finished children project from their live sessions: usage
+ // reaches their session file only at settle boundaries, so memory is fresher than a re-parse.
+ const residentIds = new Set<string>(liveIds);
+ const rlmSessionDir = this._rlmSessionDirForReading();
+ for (const [childId, retained] of this._rlmChildSessions) {
+ if (
+ residentIds.has(childId) ||
+ this._deletingRlmChildren.has(childId) ||
+ this._deletedRlmChildIds.has(childId)
+ ) {
+ continue;
+ }
+ // Only project children the disk walk would enumerate, so visibility stays identical.
+ const childDir = retained.session._rlmSessionDir ?? retained.session.sessionManager.getSessionDir();
+ if (!rlmSessionDir || basename(childDir) !== childId || dirname(childDir) !== rlmSessionDir) {
+ continue;
+ }
+ residentIds.add(childId);
+ children.push({
+ ...retained.session.getContextTree(),
+ id: childId,
+ label: retained.run ? rlmChildLabel(retained.run.prompt) : (retained.session.sessionName ?? "child agent"),
+ // Without a run, status stays "done", matching _rlmChildSnapshotForSession.
+ status: retained.run?.status ?? "done",
+ });
+ }
+ children.push(
+ ...loadContextTreeChildrenFromDisk(this._rlmSessionDirForReading(), resolveContextWindow, residentIds),
+ );
const model = this.model;
return {
diff --git a/packages/coding-agent/src/core/context-tree.ts b/packages/coding-agent/src/core/context-tree.ts
index 7546f8679c..5f275e427a 100644
--- a/packages/coding-agent/src/core/context-tree.ts
+++ b/packages/coding-agent/src/core/context-tree.ts
@@ -1,10 +1,10 @@
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
import { basename, join } from "node:path";
import type { AssistantMessage, Usage } from "@earendil-works/pi-ai";
import type { RlmChildAgentStatus } from "./agent-session.js";
import { calculateContextTokens, estimateContextTokens } from "./compaction/index.js";
import type { ContextUsage } from "./extensions/index.js";
-import { buildSessionContext, type FileEntry, loadEntriesFromFile, type SessionEntry } from "./session-manager.js";
+import { buildSessionContext, type FileEntry, loadEntriesFromBuffer, type SessionEntry } from "./session-manager.js";
import { addAssistantUsage, cloneUsage, emptyUsage, subtractAssistantUsage } from "./usage.js";
/** Resolves a model's context window so disk-only nodes can report utilization. */
@@ -148,8 +148,24 @@ function computeContextUsageFromEntries(
return { tokens: estimate.tokens, contextWindow, percent: (estimate.tokens / contextWindow) * 100 };
}
-function sessionEntriesFromFile(file: string): SessionEntry[] {
- return loadEntriesFromFile(file).filter((entry: FileEntry): entry is SessionEntry => entry.type !== "session");
+/**
+ * Read and parse a session file, returning the entries plus the byte count
+ * read, which lets the cache verify the read was a complete snapshot.
+ */
+function readSessionFile(file: string): { entries: SessionEntry[]; bytes: number } | undefined {
+ let buffer: Buffer;
+ try {
+ buffer = readFileSync(file);
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+ return undefined;
+ }
+ throw error;
+ }
+ const entries = loadEntriesFromBuffer(buffer).filter(
+ (entry: FileEntry): entry is SessionEntry => entry.type !== "session",
+ );
+ return { entries, bytes: buffer.length };
}
/**
@@ -195,23 +211,31 @@ function statusFromBranch(entries: SessionEntry[]): "done" | "error" | "cancelle
return "done";
}
-function findSessionFile(dir: string): string | undefined {
- let newest: { path: string; mtime: number } | undefined;
+/** Newest session file in a dir plus the stats that key the node cache. */
+interface SessionFile {
+ path: string;
+ size: number;
+ mtimeMs: number;
+}
+
+function findSessionFile(dir: string): SessionFile | undefined {
+ let newest: { file: SessionFile; mtime: number } | undefined;
for (const name of readdirSync(dir)) {
if (!name.endsWith(".jsonl")) {
continue;
}
const path = join(dir, name);
try {
- const mtime = statSync(path).mtime.getTime();
+ const stats = statSync(path);
+ const mtime = stats.mtime.getTime();
if (!newest || mtime > newest.mtime) {
- newest = { path, mtime };
+ newest = { file: { path, size: stats.size, mtimeMs: stats.mtimeMs }, mtime };
}
} catch {
// Skip unreadable files.
}
}
- return newest?.path;
+ return newest?.file;
}
function listChildSessionDirs(rlmSessionDir: string): string[] {
@@ -240,6 +264,71 @@ function listChildSessionDirs(rlmSessionDir: string): string[] {
});
}
+/**
+ * Cache entry for a completed child session dir: the built node plus the
+ * stats it was built from; a changed nested child file invalidates it too.
+ */
+interface ChildNodeCacheEntry {
+ file: SessionFile;
+ childFiles: Map<string, SessionFile | undefined>;
+ contextWindow: number | undefined;
+ node: ContextTreeNode;
+}
+
+/**
+ * Node cache for completed RLM child sessions: every top-bar cost refresh or
+ * /context call rebuilds the whole tree, and re-parsing finished children dominated it.
+ */
+const childNodeCache = new Map<string, ChildNodeCacheEntry>();
+/** Insertion-order cap so a long-lived daemon cannot accumulate entries. */
+const CHILD_NODE_CACHE_MAX = 256;
+
+function listChildSessionFiles(rlmSessionDir: string): Map<string, SessionFile | undefined> {
+ const files = new Map<string, SessionFile | undefined>();
+ for (const childDir of listChildSessionDirs(rlmSessionDir)) {
+ files.set(childDir, findSessionFile(childDir));
+ }
+ return files;
+}
+
+function sameSessionFile(a: SessionFile | undefined, b: SessionFile | undefined): boolean {
+ return a !== undefined && b !== undefined && a.path === b.path && a.size === b.size && a.mtimeMs === b.mtimeMs;
+}
+
+function sameChildFiles(
+ cached: Map<string, SessionFile | undefined>,
+ current: Map<string, SessionFile | undefined>,
+): boolean {
+ if (cached.size !== current.size) {
+ return false;
+ }
+ for (const [dir, file] of cached) {
+ if (!current.has(dir)) {
+ return false;
+ }
+ const other = current.get(dir);
+ if (file === undefined || other === undefined) {
+ if (file !== other) {
+ return false;
+ }
+ } else if (file.path !== other.path || file.size !== other.size || file.mtimeMs !== other.mtimeMs) {
+ return false;
+ }
+ }
+ return true;
+}
+
+/**
+ * The registry can change a model's context window while its session file
+ * stays unchanged, so cache hits compare the resolved value too.
+ */
+function resolvesToSameContextWindow(entry: ChildNodeCacheEntry, resolveContextWindow: ContextWindowResolver): boolean {
+ const contextWindow = entry.node.model
+ ? resolveContextWindow(entry.node.model.provider, entry.node.model.id)
+ : undefined;
+ return contextWindow === entry.contextWindow;
+}
+
/**
* Build a context node for a completed RLM child from its persisted session
* dir (sub-xxxx/). Children that already attributed grandchild usage carry the
@@ -251,11 +340,52 @@ export function loadContextTreeChildFromDisk(
childSessionDir: string,
resolveContextWindow: ContextWindowResolver,
): ContextTreeNode | undefined {
- const sessionFile = findSessionFile(childSessionDir);
- if (!sessionFile) {
+ const file = findSessionFile(childSessionDir);
+ if (!file) {
+ // Never surface a cached node for a dir whose session file is gone.
+ childNodeCache.delete(childSessionDir);
+ return undefined;
+ }
+ const childFiles = listChildSessionFiles(childSessionDir);
+ const cached = childNodeCache.get(childSessionDir);
+ if (
+ cached &&
+ sameSessionFile(cached.file, file) &&
+ sameChildFiles(cached.childFiles, childFiles) &&
+ resolvesToSameContextWindow(cached, resolveContextWindow)
+ ) {
+ const children: ContextTreeNode[] = [];
+ for (const grandchildDir of childFiles.keys()) {
+ const childNode = loadContextTreeChildFromDisk(grandchildDir, resolveContextWindow);
+ if (childNode) {
+ children.push(childNode);
+ }
+ }
+ let changed = children.length !== cached.node.children.length;
+ for (let i = 0; !changed && i < children.length; i++) {
+ if (children[i] !== cached.node.children[i]) {
+ changed = true;
+ }
+ }
+ if (changed) {
+ cached.node = { ...cached.node, children };
+ }
+ return cached.node;
+ }
+ return buildContextTreeChildFromDisk(childSessionDir, file, childFiles, resolveContextWindow);
+}
+
+function buildContextTreeChildFromDisk(
+ childSessionDir: string,
+ file: SessionFile,
+ childFiles: Map<string, SessionFile | undefined>,
+ resolveContextWindow: ContextWindowResolver,
+): ContextTreeNode | undefined {
+ const read = readSessionFile(file.path);
+ if (!read) {
return undefined;
}
- const allEntries = sessionEntriesFromFile(sessionFile);
+ const allEntries = read.entries;
const branch = branchEntries(allEntries);
if (branch.length === 0) {
return undefined;
@@ -282,7 +412,7 @@ export function loadContextTreeChildFromDisk(
const contextWindow = model ? resolveContextWindow(model.provider, model.id) : undefined;
- return {
+ const node: ContextTreeNode = {
id: basename(childSessionDir),
label: label || "child agent",
status: statusFromBranch(branch),
@@ -290,8 +420,50 @@ export function loadContextTreeChildFromDisk(
ownUsage,
totalUsage,
contextUsage: computeContextUsageFromEntries(allEntries, branch, contextWindow),
- children: loadContextTreeChildrenFromDisk(childSessionDir, resolveContextWindow),
+ children: [],
};
+ for (const grandchildDir of childFiles.keys()) {
+ const childNode = loadContextTreeChildFromDisk(grandchildDir, resolveContextWindow);
+ if (childNode) {
+ node.children.push(childNode);
+ }
+ }
+ cacheBuiltChildNode(childSessionDir, file, childFiles, read.bytes, contextWindow, node);
+ return node;
+}
+
+/**
+ * Cache the node only when the read was a stable snapshot: an append or
+ * compaction rewrite that raced the read skips caching, re-parsing next time.
+ */
+function cacheBuiltChildNode(
+ childSessionDir: string,
+ file: SessionFile,
+ childFiles: Map<string, SessionFile | undefined>,
+ bytes: number,
+ contextWindow: number | undefined,
+ node: ContextTreeNode,
+): void {
+ let stable = false;
+ try {
+ const stats = statSync(file.path);
+ stable = stats.size === bytes && stats.size === file.size && stats.mtimeMs === file.mtimeMs;
+ } catch {
+ // The file vanished mid-build; nothing to pin the stats to.
+ }
+ if (!stable) {
+ return;
+ }
+ // Delete first so a re-set entry moves to the end; the cap evicts from the front.
+ childNodeCache.delete(childSessionDir);
+ childNodeCache.set(childSessionDir, { file, childFiles, contextWindow, node });
+ while (childNodeCache.size > CHILD_NODE_CACHE_MAX) {
+ const oldest = childNodeCache.keys().next();
+ if (oldest.done) {
+ break;
+ }
+ childNodeCache.delete(oldest.value);
+ }
}
/**
diff --git a/packages/coding-agent/src/core/session-manager.ts b/packages/coding-agent/src/core/session-manager.ts
index e1220af2a5..156fa29238 100644
--- a/packages/coding-agent/src/core/session-manager.ts
+++ b/packages/coding-agent/src/core/session-manager.ts
@@ -765,6 +765,11 @@ export function loadEntriesFromFile(filePath: string): FileEntry[] {
return finalizeLoadedEntries(parseEntriesFromBuffer(readFileSync(filePath)));
}
+// Buffer variant for callers that must verify the byte count they read (parse caches).
+export function loadEntriesFromBuffer(buffer: Buffer): FileEntry[] {
+ return finalizeLoadedEntries(parseEntriesFromBuffer(buffer));
+}
+
// Async loader for the daemon: reads off the event loop and yields while parsing so a
// large load doesn't freeze other sessions. Large files stream to avoid retaining both
// the full input Buffer and the parsed entry graph at the same time.
diff --git a/packages/coding-agent/test/context-tree.test.ts b/packages/coding-agent/test/context-tree.test.ts
index 42c4598e10..d0b4f84e94 100644
--- a/packages/coding-agent/test/context-tree.test.ts
+++ b/packages/coding-agent/test/context-tree.test.ts
@@ -1,4 +1,4 @@
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, utimesSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { Agent } from "@earendil-works/pi-agent-core";
@@ -306,8 +306,114 @@ describe("loadContextTreeChildrenFromDisk", () => {
});
});
+describe("child node cache", () => {
+ it("reuses the parsed node while the session files are unchanged", () => {
+ const rlmDir = makeTempDir();
+ writeChildSession(join(rlmDir, "sub-cache0001"), "cache me", createUsage(100, 10, 0.01));
+ const first = loadContextTreeChildrenFromDisk(rlmDir, resolveContextWindow);
+ const second = loadContextTreeChildrenFromDisk(rlmDir, resolveContextWindow);
+ expect(second[0]).toBe(first[0]);
+ });
+
+ it("re-parses a child whose session file grew", () => {
+ const rlmDir = makeTempDir();
+ const child = writeChildSession(join(rlmDir, "sub-grow0001"), "grow", createUsage(100, 10, 0.01));
+ loadContextTreeChildrenFromDisk(rlmDir, resolveContextWindow);
+ child.sessionManager.appendMessage(createAssistantMessage("more work", createUsage(400, 40, 0.04)));
+ const second = loadContextTreeChildrenFromDisk(rlmDir, resolveContextWindow);
+ expect(second[0].ownUsage.input).toBe(500);
+ });
+
+ it("re-parses a same-size rewrite when the mtime moves", () => {
+ const rlmDir = makeTempDir();
+ const child = writeChildSession(join(rlmDir, "sub-touch0001"), "same size user text", createUsage(100, 10, 0.01));
+ const sessionFile = child.sessionManager.getSessionFile() ?? "";
+ expect(loadContextTreeChildrenFromDisk(rlmDir, resolveContextWindow)[0].label).toBe("same size user text");
+ writeFileSync(
+ sessionFile,
+ readFileSync(sessionFile, "utf8").replace("same size user text", "same size user teyt"),
+ );
+ utimesSync(sessionFile, new Date(1000_000), new Date(1000_000));
+ const second = loadContextTreeChildrenFromDisk(rlmDir, resolveContextWindow);
+ expect(second[0].label).toBe("same size user teyt");
+ });
+
+ it("drops a child whose session file was deleted", () => {
+ const rlmDir = makeTempDir();
+ const child = writeChildSession(join(rlmDir, "sub-gone0001"), "delete me", createUsage(100, 10, 0.01));
+ const first = loadContextTreeChildrenFromDisk(rlmDir, resolveContextWindow);
+ expect(first).toHaveLength(1);
+ rmSync(child.sessionManager.getSessionFile() ?? "", { force: true });
+ const second = loadContextTreeChildrenFromDisk(rlmDir, resolveContextWindow);
+ expect(second).toEqual([]);
+ });
+
+ it("rebuilds a parent when a grandchild file changes and reuses untouched grandchildren", () => {
+ const rlmDir = makeTempDir();
+ const childDir = join(rlmDir, "sub-par00001");
+ writeChildSession(childDir, "parent work", createUsage(100, 10, 0.01));
+ const changed = writeChildSession(
+ join(childDir, "sub-gc000001"),
+ "changed grandchild",
+ createUsage(200, 20, 0.02),
+ );
+ writeChildSession(join(childDir, "sub-gc000002"), "untouched grandchild", createUsage(50, 5, 0.005));
+
+ const first = loadContextTreeChildrenFromDisk(rlmDir, resolveContextWindow);
+ const firstParent = first[0];
+ expect(firstParent.children.map((node) => node.id)).toEqual(["sub-gc000001", "sub-gc000002"]);
+
+ changed.sessionManager.appendMessage(createAssistantMessage("extra", createUsage(300, 30, 0.03)));
+
+ const second = loadContextTreeChildrenFromDisk(rlmDir, resolveContextWindow);
+ const secondParent = second[0];
+ expect(secondParent.children[0].ownUsage.input).toBe(500);
+ expect(secondParent.children[1]).toBe(firstParent.children[1]);
+ });
+
+ it("2477: revalidates deeper descendants on a cache hit", () => {
+ const rlmDir = makeTempDir();
+ const childDir = join(rlmDir, "sub-cache0002");
+ const grandchildDir = join(childDir, "sub-cache0003");
+ const deepDir = join(grandchildDir, "sub-cache0004");
+ writeChildSession(childDir, "parent work", createUsage(100, 10, 0.01));
+ writeChildSession(grandchildDir, "middle work", createUsage(50, 5, 0.005));
+ const deep = writeChildSession(deepDir, "deep work", createUsage(80, 8, 0.008));
+ loadContextTreeChildrenFromDisk(rlmDir, resolveContextWindow);
+ deep.sessionManager.appendMessage(createAssistantMessage("more", createUsage(400, 40, 0.04)));
+ const second = loadContextTreeChildrenFromDisk(rlmDir, resolveContextWindow);
+ expect(second[0].children[0].children[0].ownUsage.input).toBe(480);
+ const third = loadContextTreeChildrenFromDisk(rlmDir, resolveContextWindow);
+ expect(third[0]).toBe(second[0]);
+ });
+
+ it("picks up a grandchild whose session file appears after the parent was cached", () => {
+ const rlmDir = makeTempDir();
+ const childDir = join(rlmDir, "sub-new00001");
+ writeChildSession(childDir, "parent", createUsage(100, 10, 0.01));
+ const lateDir = join(childDir, "sub-late0001");
+ mkdirSync(lateDir, { recursive: true });
+ const first = loadContextTreeChildrenFromDisk(rlmDir, resolveContextWindow);
+ expect(first[0].children).toEqual([]);
+ writeChildSession(lateDir, "late grandchild", createUsage(60, 6, 0.006));
+ const second = loadContextTreeChildrenFromDisk(rlmDir, resolveContextWindow);
+ expect(second[0].children.map((node) => node.id)).toEqual(["sub-late0001"]);
+ });
+
+ it("recomputes context usage when the model's context window changes", () => {
+ const rlmDir = makeTempDir();
+ writeChildSession(join(rlmDir, "sub-win00001"), "window test", createUsage(1500, 500, 0.02));
+
+ const first = loadContextTreeChildrenFromDisk(rlmDir, () => 200000);
+ expect(first[0].contextUsage).toEqual({ tokens: 2000, contextWindow: 200000, percent: 1 });
+
+ const second = loadContextTreeChildrenFromDisk(rlmDir, () => 100000);
+ expect(second[0].contextUsage).toEqual({ tokens: 2000, contextWindow: 100000, percent: 2 });
+ });
+});
+
describe("AgentSession.getContextTree", () => {
- function createSession() {
+ function createSession(rlmSessionDir?: string) {
const settingsManager = SettingsManager.inMemory();
const sessionManager = SessionManager.inMemory();
const authStorage = AuthStorage.inMemory();
@@ -327,6 +433,7 @@ describe("AgentSession.getContextTree", () => {
cwd: process.cwd(),
modelRegistry: ModelRegistry.inMemory(authStorage),
resourceLoader: createTestResourceLoader(),
+ ...(rlmSessionDir ? { rlmSessionDir } : {}),
});
return { session, sessionManager };
}
@@ -376,6 +483,22 @@ describe("AgentSession.getContextTree", () => {
expect(tree.totalUsage.cost.total).toBeCloseTo(0.52);
expect(tree.ownUsage.input).toBe(5200);
});
+
+ it("projects retained children from their resident sessions instead of disk", () => {
+ const rlmDir = makeTempDir();
+ writeChildSession(join(rlmDir, "sub-res00001"), "persisted child", createUsage(900, 90, 0.09));
+ const { session: parent } = createSession(rlmDir);
+ const { session: childSession, sessionManager: childManager } = createSession(join(rlmDir, "sub-res00001"));
+ childManager.appendModelChange(model.provider, model.id);
+ childManager.appendMessage(createUserMessage("child work"));
+ childManager.appendMessage(createAssistantMessage("child done", createUsage(700, 70, 0.07)));
+ syncAgentMessages(childSession, childManager);
+ expect(parent.registerRlmChildSession("sub-res00001", childSession)).toBe(true);
+ const residentNodes = parent.getContextTree().children.filter((node) => node.id === "sub-res00001");
+ expect(residentNodes).toHaveLength(1);
+ expect(residentNodes[0].ownUsage.input).toBe(700);
+ expect(residentNodes[0]).toMatchObject({ status: "done", label: "child agent" });
+ });
});
describe("formatContextTree", () => {