perf(agent): skip session JSONL sanitize when file is unchanged

packages/agent/package.json

@@ -184,6 +184,7 @@
     "fflate": "^0.8.2",
     "hono": "^4.11.7",
     "jsonwebtoken": "^9.0.2",
+    "lru-cache": "^11.1.0",
     "minimatch": "^10.0.3",
     "@modelcontextprotocol/sdk": "1.29.0",
     "tar": "^7.5.0",

packages/agent/src/adapters/claude/session/jsonl-hydration.bench.ts

@@ -0,0 +1,61 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterAll, beforeAll, bench, describe } from "vitest";
+import { sanitizeSessionJsonl } from "./jsonl-hydration";
+
+// Not run in CI (test globs only match *.test.*). Reproduce with:
+//   cd packages/agent && pnpm vitest bench src/adapters/claude/session/jsonl-hydration.bench.ts
+
+const LINES = 50_000;
+
+function makeLine(i: number): string {
+  return JSON.stringify({
+    type: "assistant",
+    uuid: `a-${i}`,
+    parentUuid: i === 0 ? null : `a-${i - 1}`,
+    message: {
+      role: "assistant",
+      content: [
+        {
+          type: "text",
+          text: `chunk ${i}: ${"tracing the residency grace period through the rehydration path ".repeat(8)}`,
+        },
+      ],
+    },
+  });
+}
+
+let dir: string;
+let warmPath: string;
+let grownPath: string;
+
+beforeAll(async () => {
+  dir = await fs.mkdtemp(path.join(os.tmpdir(), "sanitize-bench-"));
+  const content = `${Array.from({ length: LINES }, (_, i) => makeLine(i)).join("\n")}\n`;
+  warmPath = path.join(dir, "warm.jsonl");
+  grownPath = path.join(dir, "grown.jsonl");
+  await fs.writeFile(warmPath, content);
+  await fs.writeFile(grownPath, content);
+  // Prime the stat memo for the unchanged-file case.
+  await sanitizeSessionJsonl(warmPath);
+});
+
+afterAll(async () => {
+  await fs.rm(dir, { recursive: true, force: true });
+});
+
+describe(`sanitizeSessionJsonl, ${LINES} lines`, () => {
+  // Pre-PR behavior on every reconnect, and post-PR behavior whenever the
+  // file changed: full read plus a JSON.parse per line. The append inside
+  // the run keeps the memo invalidated; its own cost is microseconds.
+  bench("file changed since last pass (full read + parse)", async () => {
+    await fs.appendFile(grownPath, `${makeLine(LINES)}\n`);
+    await sanitizeSessionJsonl(grownPath);
+  });
+
+  // This PR: a reconnect against an unchanged file is one fs.stat.
+  bench("unchanged file (stat memo hit)", async () => {
+    await sanitizeSessionJsonl(warmPath);
+  });
+});

packages/agent/src/adapters/claude/session/jsonl-hydration.test.ts

@@ -1390,6 +1390,106 @@ describe("sanitizeSessionJsonl", () => {
     expect(await fs.readFile(file, "utf8")).toBe(before);
   });
 
+  it("skips the parse entirely when the file stat is unchanged since the last clean pass", async () => {
+    // "hello" moves from the text block to the uuid so both lines have the
+    // same byte length; with mtime pinned, the stats are indistinguishable.
+    const clean = {
+      type: "assistant",
+      uuid: "a1",
+      parentUuid: null,
+      message: {
+        role: "assistant",
+        content: [{ type: "text", text: "hello" }],
+      },
+    };
+    const dirty = {
+      type: "assistant",
+      uuid: "a1hello",
+      parentUuid: null,
+      message: { role: "assistant", content: [{ type: "text", text: "" }] },
+    };
+    expect(JSON.stringify(clean).length).toBe(JSON.stringify(dirty).length);
+
+    const pinned = new Date(1700000000000);
+    const file = await writeJsonl([clean]);
+    await fs.utimes(file, pinned, pinned);
+    expect(await sanitizeSessionJsonl(file)).toBe(false);
+
+    // Would be healed if parsed; the stat-based skip must win instead.
+    await fs.writeFile(file, `${JSON.stringify(dirty)}\n`);
+    await fs.utimes(file, pinned, pinned);
+    expect(await sanitizeSessionJsonl(file)).toBe(false);
+    const lines = await readJsonl(file);
+    expect((lines[0].message as { content: unknown[] }).content).toEqual([
+      { type: "text", text: "" },
+    ]);
+  });
+
+  it("re-sanitizes after the file grows past a clean pass", async () => {
+    const file = await writeJsonl([
+      {
+        type: "assistant",
+        uuid: "a1",
+        parentUuid: null,
+        message: { role: "assistant", content: [{ type: "text", text: "ok" }] },
+      },
+    ]);
+    expect(await sanitizeSessionJsonl(file)).toBe(false);
+
+    await fs.appendFile(
+      file,
+      `${JSON.stringify({
+        type: "assistant",
+        uuid: "a2",
+        parentUuid: "a1",
+        message: {
+          role: "assistant",
+          content: [{ type: "thinking", thinking: "" }],
+        },
+      })}\n`,
+    );
+    expect(await sanitizeSessionJsonl(file)).toBe(true);
+    const lines = await readJsonl(file);
+    expect((lines[1].message as { content: unknown[] }).content).toEqual([
+      { type: "text", text: " " },
+    ]);
+  });
+
+  it("re-sanitizes after the file grows past a healed pass", async () => {
+    // The heal path memoizes too; a dirty line appended after a heal must
+    // still be caught on the next pass.
+    const file = await writeJsonl([
+      {
+        type: "assistant",
+        uuid: "a1",
+        parentUuid: null,
+        message: {
+          role: "assistant",
+          content: [{ type: "thinking", thinking: "" }],
+        },
+      },
+    ]);
+    expect(await sanitizeSessionJsonl(file)).toBe(true);
+
+    await fs.appendFile(
+      file,
+      `${JSON.stringify({
+        type: "assistant",
+        uuid: "a2",
+        parentUuid: "a1",
+        message: {
+          role: "assistant",
+          content: [{ type: "thinking", thinking: "" }],
+        },
+      })}\n`,
+    );
+    expect(await sanitizeSessionJsonl(file)).toBe(true);
+    const lines = await readJsonl(file);
+    expect((lines[1].message as { content: unknown[] }).content).toEqual([
+      { type: "text", text: " " },
+    ]);
+  });
+
   it("neutralizes an oversized image nested in a tool_result", async () => {
     // A Read on a big image file lands its bytes inside a tool_result; on
     // resume that block 400s every turn until it is replaced.

packages/agent/src/adapters/claude/session/jsonl-hydration.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { ContentBlock } from "@agentclientprotocol/sdk";
+import { LRUCache } from "lru-cache";
 import { DEFAULT_GATEWAY_MODEL } from "../../../gateway-models";
 import type { PostHogAPIClient } from "../../../posthog-api";
 import type { StoredEntry } from "../../../types";
@@ -601,6 +602,24 @@ interface HydrationLog {
   warn: (msg: string, data?: unknown) => void;
 }
 
+// Every reconnect re-runs sanitize, and the read + per-line parse of a large
+// transcript costs seconds. Files whose stat matches the last clean pass are
+// skipped; the SDK only ever appends, which changes size and mtime.
+const sanitizedFileStats = new LRUCache<
+  string,
+  { mtimeMs: number; size: number }
+>({ max: 256 });
+
+function recordSanitized(
+  jsonlPath: string,
+  stat: { mtimeMs: number; size: number },
+): void {
+  sanitizedFileStats.set(jsonlPath, {
+    mtimeMs: stat.mtimeMs,
+    size: stat.size,
+  });
+}
+
 // Heals a persisted transcript that would otherwise 400 on every resume:
 // empty content blocks, missing tool_use.input, and images the API can't
 // process (unsupported type or over the per-image byte limit). The image case
@@ -613,6 +632,14 @@ export async function sanitizeSessionJsonl(
   let statBefore: { mtimeMs: number; size: number };
   try {
     statBefore = await fs.stat(jsonlPath);
+    const lastClean = sanitizedFileStats.get(jsonlPath);
+    if (
+      lastClean &&
+      lastClean.mtimeMs === statBefore.mtimeMs &&
+      lastClean.size === statBefore.size
+    ) {
+      return false;
+    }
     raw = await fs.readFile(jsonlPath, "utf8");
   } catch {
     return false;
@@ -651,12 +678,19 @@ export async function sanitizeSessionJsonl(
     return JSON.stringify(parsed);
   });
 
-  if (!changed) return false;
+  if (!changed) {
+    recordSanitized(jsonlPath, statBefore);
+    return false;
+  }
 
   const tmpPath = `${jsonlPath}.tmp.${Date.now()}`;
   let renamed = false;
   try {
     await fs.writeFile(tmpPath, sanitized.join("\n"));
+    // Memoize the tmp file's stat: rename preserves it, so recording it after
+    // the rename leaves no window where bytes appended by a concurrent writer
+    // could be certified clean (they would already mismatch this stat).
+    const statTmp = await fs.stat(tmpPath);
     // A concurrent writer may still own the file; abort rather than clobber
     // lines appended since the read. The next resume retries.
     const statNow = await fs.stat(jsonlPath);
@@ -668,6 +702,7 @@ export async function sanitizeSessionJsonl(
     }
     await fs.rename(tmpPath, jsonlPath);
     renamed = true;
+    recordSanitized(jsonlPath, statTmp);
     return true;
   } finally {
     if (!renamed) {