@cursor/july 0.1.51 → 0.1.53

package/src/internal/event-log.ts

@@ -1,20 +1,83 @@
 /**
- * Durable, replayable per-session event log. Events are held in memory for
- * live fan-out and appended to `events.ndjson` for durability; on process
- * restart the file is hydrated back so streams can replay from any
- * `startIndex`.
+ * Durable, replayable per-session event log. `events.ndjson` is the source
+ * of truth. The process keeps `nextIndex`, live subscribers, and a short
+ * unflushed tail — not a cache of the full transcript. Replay reads the
+ * file on demand; live streams subscribe first, then catch up by index.
+ *
+ * Hosted engines mint thousands of sessions (one per PR under
+ * agentic-owners). Retaining every streamed tool output in RAM for the
+ * process lifetime is what OOM'd those engines at the ~4 GB heap cap.
  */
 
-import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { appendFile, type FileHandle, mkdir, open } from "node:fs/promises";
 import { dirname } from "node:path";
+import { createInterface } from "node:readline";
 import type { SessionEvent, SessionEventPayload } from "../types.js";
 
 export type AppendableEvent = SessionEventPayload & { turnId?: string };
 
+function isEnoent(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code: unknown }).code === "ENOENT"
+  );
+}
+
+function parseEventLine(line: string): SessionEvent | undefined {
+  const trimmed = line.trim();
+  if (trimmed === "") {
+    return undefined;
+  }
+  try {
+    return JSON.parse(trimmed) as SessionEvent;
+  } catch {
+    // Skip torn trailing writes from a crashed process.
+    return undefined;
+  }
+}
+
+async function readNdjsonEvents(
+  filePath: string,
+  onEvent: (event: SessionEvent) => void
+): Promise<void> {
+  let fh: FileHandle;
+  try {
+    fh = await open(filePath, "r");
+  } catch (error) {
+    if (isEnoent(error)) {
+      return;
+    }
+    throw error;
+  }
+  const stream = fh.createReadStream({ encoding: "utf8" });
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+  try {
+    for await (const line of rl) {
+      const event = parseEventLine(line);
+      if (event !== undefined) {
+        onEvent(event);
+      }
+    }
+  } finally {
+    rl.close();
+    stream.destroy();
+    await fh.close().catch(() => {});
+  }
+}
+
 export class SessionEventLog {
-  private readonly events: SessionEvent[] = [];
+  private nextIndex = 0;
   private readonly listeners = new Set<(event: SessionEvent) => void>();
   private persistChain: Promise<void> = Promise.resolve();
+  /** Appended events whose `appendFile` has not finished. */
+  private readonly inflight: SessionEvent[] = [];
+  /**
+   * In-process patches (cloud cost backfill) that are not rewritten to
+   * `events.ndjson`. Applied on read.
+   */
+  private readonly replacements = new Map<number, SessionEvent>();
 
   private constructor(
     private readonly sessionId: string,
@@ -32,59 +95,52 @@ export class SessionEventLog {
       args.filePath,
       args.onPersistError ?? (() => {})
     );
-    await log.hydrate();
+    await log.readNextIndex();
     return log;
   }
 
-  private async hydrate(): Promise<void> {
-    let raw: string;
-    try {
-      raw = await readFile(this.filePath, "utf8");
-    } catch {
-      return;
-    }
-    for (const line of raw.split("\n")) {
-      if (line.trim() === "") {
-        continue;
+  private async readNextIndex(): Promise<void> {
+    let next = 0;
+    await readNdjsonEvents(this.filePath, (event) => {
+      if (typeof event.index === "number" && event.index >= next) {
+        next = event.index + 1;
       }
-      try {
-        this.events.push(JSON.parse(line) as SessionEvent);
-      } catch {
-        // Skip torn trailing writes from a crashed process.
-      }
-    }
+    });
+    this.nextIndex = next;
   }
 
   get count(): number {
-    return this.events.length;
+    return this.nextIndex;
   }
 
   /**
-   * In-process residency vs recorded length. Today those are the same
-   * (`events` is the cache). A later change can drop the cache and keep
-   * `eventsTotal` as the durable count while `eventsRetained` shrinks to
-   * the unflushed tail.
+   * In-process residency vs recorded length. `eventsTotal` is the durable
+   * count (`nextIndex`). `eventsRetained` is the unflushed tail — the
+   * transcript is not cached after `appendFile` lands.
    */
   memoryStats(): { eventsRetained: number; eventsTotal: number } {
-    const n = this.events.length;
-    return { eventsRetained: n, eventsTotal: n };
+    return {
+      eventsRetained: this.inflight.length,
+      eventsTotal: this.nextIndex,
+    };
   }
 
   /**
-   * Assign the next index, record the event, and fan out to live
-   * subscribers. Ordering is synchronous; file persistence is chained in
-   * the background and awaited by {@link flush}.
+   * Assign the next index and fan out to live subscribers. Ordering is
+   * synchronous; file persistence is chained in the background and awaited
+   * by {@link flush}. The event is not retained after the write lands.
    */
   append(payload: AppendableEvent): SessionEvent {
     const { turnId, ...rest } = payload;
     const event = {
-      index: this.events.length,
+      index: this.nextIndex,
       sessionId: this.sessionId,
       ...(turnId === undefined ? {} : { turnId }),
       at: new Date().toISOString(),
       ...rest,
     } as SessionEvent;
-    this.events.push(event);
+    this.nextIndex += 1;
+    this.inflight.push(event);
     for (const listener of [...this.listeners]) {
       try {
         listener(event);
@@ -93,35 +149,67 @@ export class SessionEventLog {
       }
     }
     const line = `${JSON.stringify(event)}\n`;
+    const index = event.index;
     this.persistChain = this.persistChain
       .then(() => appendFile(this.filePath, line, "utf8"))
+      .then(() => {
+        this.dropInflight(index);
+      })
       .catch((error) => this.onPersistError(error));
     return event;
   }
 
+  private dropInflight(index: number): void {
+    if (this.inflight[0]?.index === index) {
+      this.inflight.shift();
+      return;
+    }
+    const i = this.inflight.findIndex((event) => event.index === index);
+    if (i >= 0) {
+      this.inflight.splice(i, 1);
+    }
+  }
+
   /** Wait for pending file writes (used on close). */
   async flush(): Promise<void> {
     await this.persistChain;
   }
 
-  snapshot(startIndex = 0): SessionEvent[] {
-    return startIndex <= 0 ? [...this.events] : this.events.slice(startIndex);
+  /**
+   * Read recorded events from `startIndex`. Does not retain the result on
+   * the log; callers own the returned array.
+   */
+  async snapshot(startIndex = 0): Promise<SessionEvent[]> {
+    const byIndex = new Map<number, SessionEvent>();
+    await readNdjsonEvents(this.filePath, (event) => {
+      if (event.index >= startIndex) {
+        byIndex.set(event.index, event);
+      }
+    });
+    for (const event of this.inflight) {
+      if (event.index >= startIndex) {
+        byIndex.set(event.index, event);
+      }
+    }
+    for (const [index, event] of this.replacements) {
+      if (index >= startIndex) {
+        byIndex.set(index, event);
+      }
+    }
+    return [...byIndex.values()].sort((a, b) => a.index - b.index);
   }
 
   /**
-   * Replace one already-recorded event in memory. Used to backfill usage/cost
-   * onto historical `turn.completed` rows without rewriting `events.ndjson`.
-   * Live subscribers are not notified — patch before opening a replay stream.
+   * Replace one already-recorded event in this process. Used to backfill
+   * usage/cost onto historical `turn.completed` rows without rewriting
+   * `events.ndjson`. Live subscribers are not notified — patch before
+   * opening a replay stream.
    */
   replace(index: number, event: SessionEvent): boolean {
-    if (index < 0 || index >= this.events.length) {
+    if (index < 0 || index >= this.nextIndex || event.index !== index) {
       return false;
     }
-    const current = this.events[index];
-    if (current === undefined || current.index !== index) {
-      return false;
-    }
-    this.events[index] = event;
+    this.replacements.set(index, event);
     return true;
   }
 
@@ -135,12 +223,16 @@ export class SessionEventLog {
   /**
    * NDJSON stream: replays recorded events from `startIndex`, then follows
    * live events until the consumer cancels.
+   *
+   * Subscribe first (buffer live events), then read the file, then drain
+   * the buffer by index so an async file read cannot drop or duplicate
+   * events that arrive during catch-up.
    */
   stream(startIndex = 0): ReadableStream<Uint8Array> {
     const encoder = new TextEncoder();
     let unsubscribe: (() => void) | undefined;
     return new ReadableStream<Uint8Array>({
-      start: (controller) => {
+      start: async (controller) => {
         const push = (event: SessionEvent): void => {
           try {
             controller.enqueue(encoder.encode(`${JSON.stringify(event)}\n`));
@@ -148,15 +240,38 @@ export class SessionEventLog {
             unsubscribe?.();
           }
         };
-        // Synchronous snapshot + subscribe: no events can interleave.
-        for (const event of this.snapshot(startIndex)) {
-          push(event);
-        }
+        let following = false;
+        const buffered: SessionEvent[] = [];
         unsubscribe = this.subscribe((event) => {
-          if (event.index >= startIndex) {
+          if (event.index < startIndex) {
+            return;
+          }
+          if (following) {
             push(event);
+          } else {
+            buffered.push(event);
           }
         });
+        try {
+          const prefix = await this.snapshot(startIndex);
+          let maxSeen = startIndex - 1;
+          for (const event of prefix) {
+            push(event);
+            if (event.index > maxSeen) {
+              maxSeen = event.index;
+            }
+          }
+          following = true;
+          for (const event of buffered) {
+            if (event.index > maxSeen) {
+              push(event);
+              maxSeen = event.index;
+            }
+          }
+        } catch (error) {
+          unsubscribe?.();
+          controller.error(error);
+        }
       },
       cancel: () => {
         unsubscribe?.();

package/src/internal/process-memory-telemetry.ts

@@ -8,9 +8,8 @@
  * An optional in-process sampler (`AGENT_SDK_MEMORY_METRICS=1`) still logs
  * and, if a Datadog key happens to be in the pod, posts directly.
  *
- * `event_log.events_retained` is the in-process cache size (the OOM
- * suspect). `event_log.events_total` is the durable recorded count. They
- * are equal today; a later consume-and-drop change should split them.
+ * Event-log residency is `event_log.resident_sessions` (open session
+ * map). Transcripts live on disk; unflushed tails are not a scrape gauge.
  */
 
 import { getHeapStatistics } from "node:v8";
@@ -102,7 +101,7 @@ export function sampleProcessMemory(
 
 export type MemoryHealthFields = {
   memory: ProcessMemorySample & { heapUsedRatio: number };
-  eventLog: EventLogMemoryStats;
+  eventLog: Pick<EventLogMemoryStats, "residentSessions">;
 };
 
 export function heapUsedRatio(memory: ProcessMemorySample): number {
@@ -132,7 +131,7 @@ export function buildMemoryHealthFields(
 ): MemoryHealthFields {
   return {
     memory: { ...sample, heapUsedRatio: heapUsedRatio(sample) },
-    eventLog,
+    eventLog: { residentSessions: eventLog.residentSessions },
   };
 }
 
@@ -167,9 +166,7 @@ export function formatMemoryLogLine(args: {
     ` heap_limit_mb=${mb(args.memory.heapLimitBytes)}` +
     ` heap_used_ratio=${ratio.toFixed(3)}` +
     ` rss_mb=${mb(args.memory.rssBytes)}` +
-    ` event_log.sessions=${args.eventLog.residentSessions}` +
-    ` event_log.retained=${args.eventLog.eventsRetained}` +
-    ` event_log.total=${args.eventLog.eventsTotal}`
+    ` event_log.sessions=${args.eventLog.residentSessions}`
   );
 }
 
@@ -209,14 +206,6 @@ export function buildDatadogGaugeSeries(args: {
       name: `${EVENT_LOG_METRIC_PREFIX}.resident_sessions`,
       value: args.eventLog.residentSessions,
     },
-    {
-      name: `${EVENT_LOG_METRIC_PREFIX}.events_retained`,
-      value: args.eventLog.eventsRetained,
-    },
-    {
-      name: `${EVENT_LOG_METRIC_PREFIX}.events_total`,
-      value: args.eventLog.eventsTotal,
-    },
   ];
   return points.map((point) => ({
     metric: point.name,
@@ -300,14 +289,6 @@ function recordOtel(
     memory.rssBytes,
     attributes
   );
-  histogram(meter, `${EVENT_LOG_METRIC_PREFIX}.events_retained`).record(
-    eventLog.eventsRetained,
-    attributes
-  );
-  histogram(meter, `${EVENT_LOG_METRIC_PREFIX}.events_total`).record(
-    eventLog.eventsTotal,
-    attributes
-  );
   histogram(meter, `${EVENT_LOG_METRIC_PREFIX}.resident_sessions`).record(
     eventLog.residentSessions,
     attributes

package/src/internal/session-engine.ts

@@ -3014,7 +3014,7 @@ export class SessionEngine {
 
   private async runCloudTurnCostBackfill(sessionId: string): Promise<void> {
     const log = await this.logs.get(sessionId);
-    const events = log.snapshot(0);
+    const events = await log.snapshot(0);
     if (!events.some((event) => isUnpricedCompletedTurn(event))) {
       if (
         !this.isTurnRunning(sessionId) &&
@@ -3049,7 +3049,9 @@ export class SessionEngine {
       }
       log.replace(i, next);
     }
-    if (!log.snapshot(0).some((event) => isUnpricedCompletedTurn(event))) {
+    if (
+      !(await log.snapshot(0)).some((event) => isUnpricedCompletedTurn(event))
+    ) {
       this.cloudCostBackfillDone.add(sessionId);
     }
   }