@cursor/july 0.1.20 → 0.1.21

package/src/internal/storage-coordinator.test.ts

@@ -0,0 +1,517 @@
+import { describe, expect, it, vi } from "vitest";
+import type { ABMetricSample } from "../ab.js";
+import type { EvalRunSnapshot } from "../evals.js";
+import type { StorageContext } from "../storage.js";
+import { defineStorage, storageKeys } from "../storage.js";
+import type { JsonValue, SessionEvent, SessionRecord } from "../types.js";
+import type { ABSnapshot } from "./ab-snapshot.js";
+import type { ReminderRecord } from "./reminder-store.js";
+import { StorageCoordinator } from "./storage-coordinator.js";
+
+function makeRecord(
+  sessionId: string,
+  turnCount = 0,
+  continuationKey: string | null = null
+): SessionRecord {
+  const now = new Date().toISOString();
+  return {
+    sessionId,
+    channelId: "http",
+    mode: "chat",
+    continuationKey,
+    auth: null,
+    turnCount,
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+let eventIndex = 0;
+function makeEvent(
+  sessionId: string,
+  type: SessionEvent["type"]
+): SessionEvent {
+  return {
+    sessionId,
+    index: eventIndex++,
+    at: new Date().toISOString(),
+    type,
+    data: {},
+  } as SessionEvent;
+}
+
+interface Call {
+  op: "put" | "delete";
+  key: string;
+  value?: JsonValue;
+  ctx: StorageContext;
+}
+
+function makeCoordinator(options?: {
+  policy?: Parameters<typeof defineStorage>[0]["policy"];
+  put?: (key: string, value: JsonValue) => void | Promise<void>;
+}): {
+  coordinator: StorageCoordinator;
+  calls: Call[];
+  store: Map<string, JsonValue>;
+} {
+  const calls: Call[] = [];
+  const store = new Map<string, JsonValue>();
+  const definition = defineStorage({
+    policy: options?.policy,
+    put: async (key, value, ctx) => {
+      calls.push({ op: "put", key, value, ctx });
+      await options?.put?.(key, value);
+      store.set(key, value);
+    },
+    delete: (key, ctx) => {
+      calls.push({ op: "delete", key, ctx });
+      store.delete(key);
+    },
+    get: (key) => store.get(key),
+    list: (prefix) =>
+      [...store.entries()]
+        .filter(([key]) => key.startsWith(prefix))
+        .sort(([a], [b]) => (a < b ? -1 : 1))
+        .map(([key, value]) => ({ key, value })),
+  });
+  const coordinator = new StorageCoordinator({
+    definition,
+    agentName: "test-agent",
+    projectRoot: "/tmp/test-agent",
+    logger: () => {},
+  });
+  return { coordinator, calls, store };
+}
+
+/**
+ * Append + dispatch-settled, as the engine drives it: the boundary flush
+ * only fires from eventDispatched, after the event's handlers ran.
+ */
+function emit(coordinator: StorageCoordinator, event: SessionEvent): void {
+  coordinator.event(event);
+  coordinator.eventDispatched(event);
+}
+
+describe("StorageCoordinator", () => {
+  it("buffers events and coalesced records until a turn boundary", async () => {
+    const { coordinator, calls } = makeCoordinator();
+
+    coordinator.sessionRecord(makeRecord("s1", 0));
+    const first = makeEvent("s1", "session.started");
+    emit(coordinator, first);
+    emit(coordinator, makeEvent("s1", "message.received"));
+    coordinator.sessionRecord(makeRecord("s1", 1));
+    await coordinator.whenIdle();
+    expect(calls).toHaveLength(0);
+
+    emit(coordinator, makeEvent("s1", "turn.completed"));
+    await coordinator.whenIdle();
+
+    // One chunk put (keyed by the first event's index) + one record put.
+    expect(calls.map((call) => call.key)).toEqual([
+      storageKeys.sessionEvents("test-agent", "s1", first.index),
+      storageKeys.session("test-agent", "s1"),
+    ]);
+    const chunk = calls[0]?.value as unknown as SessionEvent[];
+    expect(chunk.map((event) => event.type)).toEqual([
+      "session.started",
+      "message.received",
+      "turn.completed",
+    ]);
+    // Only the newest record survives coalescing.
+    const record = calls[1]?.value as unknown as SessionRecord;
+    expect(record.turnCount).toBe(1);
+    expect(calls[0]?.ctx).toMatchObject({
+      agentName: "test-agent",
+      projectRoot: "/tmp/test-agent",
+      reason: "policy",
+    });
+  });
+
+  it("keeps sessions independent", async () => {
+    const { coordinator, calls } = makeCoordinator();
+    const s1 = makeEvent("s1", "message.received");
+    emit(coordinator, s1);
+    emit(coordinator, makeEvent("s2", "message.received"));
+    emit(coordinator, makeEvent("s1", "turn.completed"));
+    await coordinator.whenIdle();
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.key).toBe(
+      storageKeys.sessionEvents("test-agent", "s1", s1.index)
+    );
+  });
+
+  it("includes record updates from boundary-event handlers in the flush", async () => {
+    const { coordinator, calls } = makeCoordinator();
+    const boundary = makeEvent("s1", "turn.completed");
+    coordinator.event(boundary);
+    // The boundary event's own handler updates the record (e.g. channel
+    // state or a new continuation token) before dispatch settles.
+    coordinator.sessionRecord(makeRecord("s1", 7));
+    coordinator.eventDispatched(boundary);
+    await coordinator.whenIdle();
+
+    const record = calls.find(
+      (call) => call.key === storageKeys.session("test-agent", "s1")
+    )?.value as unknown as SessionRecord;
+    expect(record.turnCount).toBe(7);
+  });
+
+  it("maintains the continuation index across token changes", async () => {
+    const { coordinator, calls, store } = makeCoordinator();
+
+    coordinator.sessionRecord(makeRecord("s1", 0, "tok-a"));
+    emit(coordinator, makeEvent("s1", "turn.completed"));
+    await coordinator.whenIdle();
+    const keyA = storageKeys.continuation("test-agent", "http", "tok-a");
+    expect(store.get(keyA)).toEqual({ sessionId: "s1" });
+
+    // Token rotates: the stale index entry is deleted, the new one put.
+    coordinator.sessionRecord(makeRecord("s1", 1, "tok-b"));
+    emit(coordinator, makeEvent("s1", "turn.completed"));
+    await coordinator.whenIdle();
+    const keyB = storageKeys.continuation("test-agent", "http", "tok-b");
+    expect(store.has(keyA)).toBe(false);
+    expect(store.get(keyB)).toEqual({ sessionId: "s1" });
+    expect(
+      calls.some((call) => call.op === "delete" && call.key === keyA)
+    ).toBe(true);
+
+    // Unchanged token on the next flush emits no index writes.
+    const before = calls.length;
+    coordinator.sessionRecord(makeRecord("s1", 2, "tok-b"));
+    emit(coordinator, makeEvent("s1", "turn.completed"));
+    await coordinator.whenIdle();
+    const indexWrites = calls
+      .slice(before)
+      .filter((call) => call.key.includes("/continuation/"));
+    expect(indexWrites).toHaveLength(0);
+  });
+
+  it("bounds oversized continuation tokens in keys and round-trips them", async () => {
+    const { coordinator, store } = makeCoordinator();
+    // A hostile caller-supplied token: multi-byte characters inflate the
+    // URI-encoding well past any sane backend key limit.
+    const hugeToken = "TOKEN-\u{1F4A5}".repeat(600);
+    const key = storageKeys.continuation("test-agent", "http", hugeToken);
+    expect(key).toContain("/continuation/http/sha256:");
+    expect(Buffer.byteLength(key, "utf8")).toBeLessThan(512);
+    // Deterministic: the same token always mints the same key.
+    expect(storageKeys.continuation("test-agent", "http", hugeToken)).toBe(key);
+
+    // Write path (flush) and read path (lazy lookup) agree on the key.
+    coordinator.sessionRecord(makeRecord("s1", 0, hugeToken));
+    emit(coordinator, makeEvent("s1", "turn.completed"));
+    await coordinator.whenIdle();
+    expect(store.get(key)).toEqual({ sessionId: "s1" });
+    const record = await coordinator.getSessionByContinuation(
+      "http",
+      hugeToken
+    );
+    expect(record?.sessionId).toBe("s1");
+    await expect(coordinator.getSessionById("s1")).resolves.toMatchObject({
+      sessionId: "s1",
+    });
+    await expect(coordinator.getSessionById("ses_missing")).resolves.toBe(
+      undefined
+    );
+  });
+
+  it("drops writes once the delivery queue is full", async () => {
+    let release: (() => void) | undefined;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const logs: string[] = [];
+    const definition = defineStorage({
+      put: () => gate,
+    });
+    const coordinator = new StorageCoordinator({
+      definition,
+      agentName: "test-agent",
+      projectRoot: "/tmp/test-agent",
+      logger: (line) => logs.push(line),
+    });
+
+    // The first put blocks the queue; well past the bound, later flushes
+    // must be shed instead of growing memory without limit.
+    for (let i = 0; i < 1_200; i += 1) {
+      emit(coordinator, makeEvent(`s${i}`, "turn.completed"));
+    }
+    expect(logs.some((line) => line.includes("storage queue full"))).toBe(true);
+    release?.();
+    await coordinator.whenIdle();
+  });
+
+  it("flushes at the batch cap under a debounce policy", async () => {
+    const { coordinator, calls } = makeCoordinator({
+      policy: { debounceMs: 60_000 },
+    });
+    for (let i = 0; i < 200; i += 1) {
+      emit(coordinator, makeEvent("s1", "message.received"));
+    }
+    await coordinator.whenIdle();
+    expect(calls).toHaveLength(1);
+    expect((calls[0]?.value as unknown as SessionEvent[]).length).toBe(200);
+  });
+
+  it("debounce spans turn boundaries and carries the coalesced record", async () => {
+    vi.useFakeTimers();
+    try {
+      const { coordinator, calls } = makeCoordinator({
+        policy: { debounceMs: 1_000 },
+      });
+      const first = makeEvent("s1", "message.received");
+      emit(coordinator, first);
+      // Boundary events do NOT flush a debounced session.
+      emit(coordinator, makeEvent("s1", "turn.completed"));
+      coordinator.sessionRecord(makeRecord("s1", 1));
+      emit(coordinator, makeEvent("s1", "message.received"));
+      emit(coordinator, makeEvent("s1", "turn.completed"));
+      coordinator.sessionRecord(makeRecord("s1", 2));
+      await coordinator.whenIdle();
+      expect(calls).toHaveLength(0);
+
+      // Quiet period elapses: both turns land in one chunk, one record.
+      await vi.advanceTimersByTimeAsync(1_000);
+      await coordinator.whenIdle();
+      expect(calls.map((call) => call.key)).toEqual([
+        storageKeys.sessionEvents("test-agent", "s1", first.index),
+        storageKeys.session("test-agent", "s1"),
+      ]);
+      expect((calls[0]?.value as unknown as SessionEvent[]).length).toBe(4);
+      expect((calls[1]?.value as unknown as SessionRecord).turnCount).toBe(2);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("close flushes buffered state with reason shutdown", async () => {
+    const { coordinator, calls } = makeCoordinator();
+    coordinator.event(makeEvent("s1", "message.received"));
+    coordinator.sessionRecord(makeRecord("s1", 1));
+    await coordinator.close();
+
+    expect(calls.length).toBe(2);
+    expect(calls.every((call) => call.ctx.reason === "shutdown")).toBe(true);
+    // Writes after close are ignored.
+    emit(coordinator, makeEvent("s1", "turn.completed"));
+    await coordinator.whenIdle();
+    expect(calls.length).toBe(2);
+  });
+
+  it("serializes writes and survives a throwing sink", async () => {
+    const order: string[] = [];
+    const { coordinator, calls } = makeCoordinator({
+      put: async (key) => {
+        order.push(`start ${key}`);
+        if (order.length === 1) {
+          await new Promise((resolve) => setTimeout(resolve, 5));
+          order.push(`end ${key}`);
+          throw new Error("sink down");
+        }
+        order.push(`end ${key}`);
+      },
+    });
+    const first = makeEvent("s1", "turn.completed");
+    emit(coordinator, first);
+    emit(coordinator, makeEvent("s2", "turn.completed"));
+    await coordinator.whenIdle();
+
+    // Serialized (no interleaving), and the throw dropped only its write.
+    expect(order).toEqual([
+      `start ${storageKeys.sessionEvents("test-agent", "s1", first.index)}`,
+      `end ${storageKeys.sessionEvents("test-agent", "s1", first.index)}`,
+      `start ${calls[1]?.key}`,
+      `end ${calls[1]?.key}`,
+    ]);
+    expect(calls).toHaveLength(2);
+  });
+
+  it("mirrors reminders onto the sink and lists them back", async () => {
+    const { coordinator, store } = makeCoordinator();
+    const now = new Date().toISOString();
+    const record: ReminderRecord = {
+      version: 1,
+      id: "rem_1",
+      purpose: "watch",
+      channelId: "drive",
+      continuationToken: "tok",
+      scheduleKind: "every",
+      scheduleValue: "30m",
+      intervalMs: 30 * 60_000,
+      prompt: "check",
+      hasRunHandler: false,
+      hasUntilFn: false,
+      busyPolicy: "skipIfBusy",
+      status: "armed",
+      fireCount: 0,
+      nextFireAtMs: Date.now() + 60_000,
+      createdAt: now,
+      updatedAt: now,
+    };
+    coordinator.reminder(record);
+    await coordinator.whenIdle();
+    expect(store.get(storageKeys.reminder("test-agent", "rem_1"))).toEqual(
+      record
+    );
+    await expect(coordinator.listReminders()).resolves.toEqual([record]);
+
+    store.set(storageKeys.reminder("test-agent", "garbage"), {
+      not: "a reminder",
+    });
+    await expect(coordinator.listReminders()).resolves.toEqual([record]);
+  });
+
+  it("routes eval runs through the dedicated evals table", async () => {
+    const table = new Map<string, EvalRunSnapshot>();
+    const contexts: StorageContext[] = [];
+    const coordinator = new StorageCoordinator({
+      definition: defineStorage({
+        put: () => {},
+        evals: {
+          put: (run, ctx) => {
+            contexts.push(ctx);
+            table.set(run.runId, run);
+          },
+          delete: (runId) => {
+            table.delete(runId);
+          },
+          list: () => [...table.values()],
+        },
+      }),
+      agentName: "test-agent",
+      projectRoot: "/tmp/test-agent",
+      logger: () => {},
+    });
+
+    const storage = coordinator.evalRuns();
+    expect(storage).toBeDefined();
+    const run = { runId: "run-1", status: "running" } as EvalRunSnapshot;
+    storage!.save(run);
+    // Mutations after enqueue must not leak into the delivered snapshot.
+    run.status = "completed";
+    await coordinator.whenIdle();
+    expect(table.get("run-1")?.status).toBe("running");
+    expect(contexts[0]).toMatchObject({
+      agentName: "test-agent",
+      reason: "policy",
+    });
+    await expect(storage!.list()).resolves.toHaveLength(1);
+
+    storage!.delete("run-1");
+    await coordinator.whenIdle();
+    expect(table.has("run-1")).toBe(false);
+  });
+
+  it("routes A/B samples and the throttled snapshot through the abs table", async () => {
+    const samples: ABMetricSample[] = [];
+    let storedSnapshot: ABSnapshot | undefined;
+    let snapshotWrites = 0;
+    const coordinator = new StorageCoordinator({
+      definition: defineStorage({
+        put: () => {},
+        abs: {
+          putSample: (sample) => {
+            samples.push(sample);
+          },
+          putSnapshot: (snapshot) => {
+            snapshotWrites += 1;
+            storedSnapshot = snapshot;
+          },
+          getSnapshot: () => storedSnapshot,
+        },
+      }),
+      agentName: "test-agent",
+      projectRoot: "/tmp/test-agent",
+      logger: () => {},
+    });
+
+    const sample = {
+      experiment: "exp",
+      variant: "a",
+      sessionId: "s1",
+      channelId: "http",
+      metrics: {},
+      reason: "turn.completed",
+      at: "2026-07-15T00:00:00.000Z",
+    } as unknown as ABMetricSample;
+    coordinator.abSample(sample);
+    await coordinator.whenIdle();
+    expect(samples).toEqual([sample]);
+
+    const snapshot = (id: string) =>
+      ({
+        experiments: [],
+        sessions: [],
+        config: { id },
+      }) as unknown as ABSnapshot;
+    coordinator.abSnapshot(snapshot("first"));
+    coordinator.abSnapshot(snapshot("suppressed"));
+    await coordinator.whenIdle();
+    expect(snapshotWrites).toBe(1);
+    await expect(coordinator.getLatestAbSnapshot()).resolves.toEqual(
+      snapshot("first")
+    );
+  });
+
+  it("treats missing evals/abs tables as memory-only", async () => {
+    const { coordinator } = makeCoordinator();
+    expect(coordinator.evalRuns()).toBeUndefined();
+    // No abs table: sample/snapshot writes are dropped, reads are absent.
+    coordinator.abSample({} as ABMetricSample);
+    coordinator.abSnapshot({} as ABSnapshot);
+    await coordinator.whenIdle();
+    await expect(coordinator.getLatestAbSnapshot()).resolves.toBeUndefined();
+  });
+
+  it("reads empty state from a write-only sink", async () => {
+    const definition = defineStorage({ put: () => {} });
+    const coordinator = new StorageCoordinator({
+      definition,
+      agentName: "test-agent",
+      projectRoot: "/tmp/test-agent",
+      logger: () => {},
+    });
+    expect(coordinator.canBulkRestore).toBe(false);
+    expect(coordinator.supportsAuthorKv).toBe(false);
+    await expect(coordinator.listSessions()).resolves.toEqual([]);
+    await expect(coordinator.listSessionEvents("s1")).resolves.toEqual([]);
+    await expect(
+      coordinator.getSessionByContinuation("http", "tok")
+    ).resolves.toBeUndefined();
+    await expect(coordinator.getLatestAbSnapshot()).resolves.toBeUndefined();
+  });
+
+  it("awaits author kv get/put/delete under storageKeys.kv", async () => {
+    const store = new Map<string, unknown>();
+    const coordinator = new StorageCoordinator({
+      definition: defineStorage({
+        put: (key, value) => {
+          store.set(key, value);
+        },
+        get: (key) => store.get(key) as never,
+        delete: (key) => {
+          store.delete(key);
+        },
+      }),
+      agentName: "test-agent",
+      projectRoot: "/tmp/test-agent",
+      logger: () => {},
+    });
+    expect(coordinator.supportsAuthorKv).toBe(true);
+    await coordinator.kvPut("alert-memory/1", { ok: true });
+    expect(store.get(storageKeys.kv("test-agent", "alert-memory/1"))).toEqual({
+      ok: true,
+    });
+    await expect(coordinator.kvGet("alert-memory/1")).resolves.toEqual({
+      ok: true,
+    });
+    await coordinator.kvPut("alert-memory/null", null);
+    await expect(coordinator.kvGet("alert-memory/null")).resolves.toBeNull();
+    await coordinator.kvDelete("alert-memory/1");
+    await expect(coordinator.kvGet("alert-memory/1")).resolves.toBeUndefined();
+  });
+});