@cursor/july 0.1.26 → 0.1.28

package/src/internal/session-engine.storage.test.ts

@@ -1,547 +0,0 @@
-import { mkdtemp, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import { httpChannel } from "../channels.js";
-import type { StorageDefinition, StoragePolicy } from "../storage.js";
-import { defineStorage, storageKeys } from "../storage.js";
-import { CURSOR_HOSTED_STORAGE } from "../storage-backends/cursor-hosted.js";
-import type {
-  AgentProject,
-  JsonValue,
-  SessionEvent,
-  SessionRecord,
-  TurnOutcome,
-} from "../types.js";
-import type { AgentRunner } from "./sdk-runner.js";
-import { SessionEngine } from "./session-engine.js";
-
-const AGENT = "storage-test";
-
-function testProject(
-  rootDir: string,
-  storage: StorageDefinition
-): AgentProject {
-  return {
-    rootDir,
-    agentDir: join(rootDir, "agent"),
-    name: AGENT,
-    agent: {
-      name: AGENT,
-      runtime: "local",
-      instructions: "Test agent.",
-      tools: [],
-      skills: [],
-      connections: [],
-      subagents: [],
-      seedFiles: [],
-    },
-    httpChannel: httpChannel(),
-    channels: [],
-    schedules: [],
-    hooks: [],
-    abs: [],
-    storage,
-    diagnostics: [],
-  };
-}
-
-/** In-memory KV stand-in for a DB/S3 sink. */
-function memorySink(options?: {
-  policy?: StoragePolicy;
-  /** Stamp the cursor-hosted marker (for sessions API source selection). */
-  cursorHosted?: boolean;
-}): {
-  definition: StorageDefinition;
-  store: Map<string, JsonValue>;
-  session: (sessionId: string) => SessionRecord | undefined;
-  patchSession: (sessionId: string, patch: Partial<SessionRecord>) => void;
-  events: (sessionId: string) => SessionEvent[];
-} {
-  const store = new Map<string, JsonValue>();
-  const definition = defineStorage({
-    policy: options?.policy,
-    ...(options?.cursorHosted === true
-      ? { [CURSOR_HOSTED_STORAGE]: true as const }
-      : {}),
-    put: (key, value) => {
-      store.set(key, structuredClone(value));
-    },
-    delete: (key) => {
-      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 session = (sessionId: string) =>
-    store.get(storageKeys.session(AGENT, sessionId)) as
-      | SessionRecord
-      | undefined;
-  return {
-    definition,
-    store,
-    session,
-    patchSession: (sessionId, patch) => {
-      const record = session(sessionId);
-      if (record === undefined) {
-        throw new Error(`missing sink record ${sessionId}`);
-      }
-      store.set(storageKeys.session(AGENT, sessionId), {
-        ...record,
-        ...patch,
-      } as unknown as JsonValue);
-    },
-    events: (sessionId) =>
-      [...store.entries()]
-        .filter(([key]) =>
-          key.startsWith(storageKeys.sessionEventsPrefix(AGENT, sessionId))
-        )
-        .sort(([a], [b]) => (a < b ? -1 : 1))
-        .flatMap(([, value]) => value as unknown as SessionEvent[]),
-  };
-}
-
-function echoRunner(prompts: string[]): AgentRunner {
-  return {
-    runTurn: async (request): Promise<TurnOutcome> => {
-      prompts.push(request.prompt);
-      return { status: "finished", result: `echo: ${request.prompt}` };
-    },
-  };
-}
-
-const cleanups: Array<() => Promise<void>> = [];
-
-afterEach(async () => {
-  while (cleanups.length > 0) {
-    await cleanups.pop()?.();
-  }
-});
-
-async function tempStateRoot(): Promise<string> {
-  const dir = await mkdtemp(join(tmpdir(), "agent-serve-persist-"));
-  cleanups.push(() => rm(dir, { recursive: true, force: true }));
-  return dir;
-}
-
-describe("session restore from defineStorage", () => {
-  it("restores sessions and events into a fresh state root and resumes", async () => {
-    const sink = memorySink();
-
-    // ── Host A: run one turn, then drain (shutdown flush). ──
-    const stateRootA = await tempStateRoot();
-    const promptsA: string[] = [];
-    const engineA = new SessionEngine({
-      project: testProject(stateRootA, sink.definition),
-      stateRoot: stateRootA,
-      runner: echoRunner(promptsA),
-    });
-    const session = await engineA.send("http", "hello", { auth: null });
-    await session.waitForCompletion();
-    const eventsA = await engineA.listEvents(session.id);
-    await engineA.close();
-
-    expect(sink.session(session.id)?.turnCount).toBe(1);
-    expect(sink.events(session.id)).toEqual(eventsA);
-    // The continuation index entry points back at the session.
-    const record = sink.session(session.id);
-    expect(
-      sink.store.get(
-        storageKeys.continuation(AGENT, "http", record?.continuationKey ?? "")
-      )
-    ).toEqual({ sessionId: session.id });
-
-    // ── Host B: fresh state root, same sink. ──
-    const stateRootB = await tempStateRoot();
-    const promptsB: string[] = [];
-    const engineB = new SessionEngine({
-      project: testProject(stateRootB, sink.definition),
-      stateRoot: stateRootB,
-      runner: echoRunner(promptsB),
-    });
-    cleanups.push(() => engineB.close());
-    await engineB.restoreStoredSessions();
-
-    // Record restored: same session id, turn counter, continuation key.
-    const restored = await engineB.sessions.get(session.id);
-    expect(restored?.turnCount).toBe(1);
-    expect(restored?.continuationKey).toBe(record?.continuationKey);
-
-    // Event stream restored byte-for-byte (indexes, types, order).
-    const eventsB = await engineB.listEvents(session.id);
-    expect(eventsB).toEqual(eventsA);
-
-    // Continuation token resolves on the restored host: the follow-up is a
-    // resume (not a new session) and the turn counter continues.
-    const follow = await engineB.send("http", "again", {
-      auth: null,
-      continuationToken: session.continuationToken ?? undefined,
-    });
-    expect(follow.id).toBe(session.id);
-    expect(follow.isNew).toBe(false);
-    const outcome = await follow.waitForCompletion();
-    expect(outcome.status).toBe("finished");
-    expect((await engineB.sessions.get(session.id))?.turnCount).toBe(2);
-    // Restored history + the new turn share one contiguous stream.
-    const afterFollow = await engineB.listEvents(session.id);
-    expect(afterFollow.length).toBeGreaterThan(eventsB.length);
-    expect(afterFollow.map((event) => event.index)).toEqual(
-      afterFollow.map((_, index) => index)
-    );
-    // Host B's new events land in the sink as later chunks under the same
-    // stream — no overlap with host A's chunks.
-    await engineB.close();
-    expect(sink.events(session.id)).toEqual(afterFollow);
-  });
-
-  it("prefers local state over the sink and skips broken loads", async () => {
-    const sink = memorySink();
-    const stateRoot = await tempStateRoot();
-    const prompts: string[] = [];
-    const engine = new SessionEngine({
-      project: testProject(stateRoot, sink.definition),
-      stateRoot,
-      runner: echoRunner(prompts),
-    });
-    cleanups.push(() => engine.close());
-
-    const session = await engine.send("http", "hi", { auth: null });
-    await session.waitForCompletion();
-    await engine.storage?.whenIdle();
-
-    // Sink holds a stale copy (pretend another host wrote turnCount 99).
-    sink.patchSession(session.id, { turnCount: 99 });
-    // Plus one garbage row that must not abort the restore pass.
-    sink.store.set(storageKeys.session(AGENT, "garbage"), {
-      sessionId: "",
-    });
-
-    await engine.restoreStoredSessions();
-    expect((await engine.sessions.get(session.id))?.turnCount).toBe(1);
-  });
-
-  it("caps the bulk restore by session count, age, and byte budget", async () => {
-    const sink = memorySink({
-      policy: { restore: { maxSessions: 2, maxAgeMs: 60_000 } },
-    });
-
-    // Host A: three sessions, drained to the sink.
-    const stateRootA = await tempStateRoot();
-    const engineA = new SessionEngine({
-      project: testProject(stateRootA, sink.definition),
-      stateRoot: stateRootA,
-      runner: echoRunner([]),
-    });
-    const ids: string[] = [];
-    for (const prompt of ["one", "two", "three"]) {
-      const session = await engineA.send("http", prompt, { auth: null });
-      await session.waitForCompletion();
-      ids.push(session.id);
-    }
-    await engineA.close();
-
-    // Make the oldest session stale so the age window drops it, and order
-    // the rest deterministically (newest last).
-    const [stale, middle, newest] = ids;
-    if (stale === undefined || middle === undefined || newest === undefined) {
-      throw new Error("expected three sessions");
-    }
-    sink.patchSession(stale, {
-      updatedAt: new Date(Date.now() - 3_600_000).toISOString(),
-    });
-    sink.patchSession(middle, {
-      updatedAt: new Date(Date.now() - 2_000).toISOString(),
-    });
-    sink.patchSession(newest, {
-      updatedAt: new Date(Date.now() - 1_000).toISOString(),
-    });
-
-    // Host B restores under the caps: the stale session is age-filtered.
-    const stateRootB = await tempStateRoot();
-    const engineB = new SessionEngine({
-      project: testProject(stateRootB, sink.definition),
-      stateRoot: stateRootB,
-      runner: echoRunner([]),
-    });
-    cleanups.push(() => engineB.close());
-    await engineB.restoreStoredSessions();
-    expect(await engineB.sessions.get(newest)).toBeDefined();
-    expect(await engineB.sessions.get(middle)).toBeDefined();
-    expect(await engineB.sessions.get(stale)).toBeUndefined();
-
-    // A byte budget sized to exactly the newest session admits it and stops
-    // before anything else is written (budget is checked before write).
-    const sizeOf = (sessionId: string): number => {
-      const record = sink.session(sessionId);
-      const events = sink.events(sessionId);
-      const ndjson = `${events.map((e) => JSON.stringify(e)).join("\n")}\n`;
-      return (
-        Buffer.byteLength(JSON.stringify(record), "utf8") +
-        Buffer.byteLength(ndjson, "utf8")
-      );
-    };
-    const tight = memorySink({
-      policy: { restore: { maxTotalBytes: sizeOf(newest) } },
-    });
-    for (const [key, value] of sink.store) {
-      tight.store.set(key, value);
-    }
-    const stateRootC = await tempStateRoot();
-    const engineC = new SessionEngine({
-      project: testProject(stateRootC, tight.definition),
-      stateRoot: stateRootC,
-      runner: echoRunner([]),
-    });
-    cleanups.push(() => engineC.close());
-    await engineC.restoreStoredSessions();
-    expect(await engineC.sessions.get(newest)).toBeDefined();
-    expect(await engineC.sessions.get(middle)).toBeUndefined();
-  });
-
-  it("lazily restores a session on continuation miss with restore off", async () => {
-    const sink = memorySink({ policy: { restore: "off" } });
-
-    const stateRootA = await tempStateRoot();
-    const engineA = new SessionEngine({
-      project: testProject(stateRootA, sink.definition),
-      stateRoot: stateRootA,
-      runner: echoRunner([]),
-    });
-    const session = await engineA.send("http", "hello", { auth: null });
-    await session.waitForCompletion();
-    await engineA.close();
-
-    // Host B: bulk restore is off, so nothing is materialized at start.
-    const stateRootB = await tempStateRoot();
-    const engineB = new SessionEngine({
-      project: testProject(stateRootB, sink.definition),
-      stateRoot: stateRootB,
-      runner: echoRunner([]),
-    });
-    cleanups.push(() => engineB.close());
-    await engineB.restoreStoredSessions();
-    expect(await engineB.sessions.get(session.id)).toBeUndefined();
-
-    // The follow-up's continuation lookup misses locally, hits the sink,
-    // and resumes the restored session in place.
-    const follow = await engineB.send("http", "again", {
-      auth: null,
-      continuationToken: session.continuationToken ?? undefined,
-    });
-    expect(follow.id).toBe(session.id);
-    expect(follow.isNew).toBe(false);
-    await follow.waitForCompletion();
-    expect((await engineB.sessions.get(session.id))?.turnCount).toBe(2);
-
-    // An unknown token still starts a fresh session (no false resume).
-    const fresh = await engineB.send("http", "new", {
-      auth: null,
-      continuationToken: "unknown-token",
-    });
-    expect(fresh.id).not.toBe(session.id);
-    expect(fresh.isNew).toBe(true);
-    await fresh.waitForCompletion();
-  });
-
-  it("fails the follow-up instead of forking the token when the lazy sink errors", async () => {
-    const broken = defineStorage({
-      put: () => {},
-      get: () => {
-        throw new Error("store down");
-      },
-    });
-    const stateRoot = await tempStateRoot();
-    const engine = new SessionEngine({
-      project: testProject(stateRoot, broken),
-      stateRoot,
-      runner: echoRunner([]),
-    });
-    cleanups.push(() => engine.close());
-
-    // A sink error is not "unknown token": the send must fail (retryable)
-    // rather than mint a new session under the same continuation key.
-    await expect(
-      engine.send("http", "again", {
-        auth: null,
-        continuationToken: "token-behind-broken-store",
-      })
-    ).rejects.toThrow("store down");
-    expect(
-      await engine.sessions.findByContinuation(
-        "http",
-        "token-behind-broken-store"
-      )
-    ).toBeUndefined();
-  });
-
-  it("backfills GET /v1/abs from a persisted snapshot when nothing folds locally", async () => {
-    // Marker value distinguishes the restored aggregate from a live fold.
-    const restoredSnapshot = {
-      experiments: [],
-      sessions: [],
-      config: { maxPlaygroundSessions: 123 },
-    };
-    const definition = defineStorage({
-      put: () => {},
-      abs: {
-        putSample: () => {},
-        putSnapshot: () => {},
-        getSnapshot: () => restoredSnapshot,
-      },
-    });
-    const stateRoot = await tempStateRoot();
-    const engine = new SessionEngine({
-      project: testProject(stateRoot, definition),
-      stateRoot,
-      runner: echoRunner([]),
-    });
-    cleanups.push(() => engine.close());
-
-    // Fresh host, no local sessions: the persisted aggregate is served.
-    await expect(engine.abSnapshot(null)).resolves.toEqual(restoredSnapshot);
-
-    // Once a session exists locally, the live fold wins again (this
-    // project has no experiments, so the fold is empty but freshly built).
-    const session = await engine.send("http", "hello", { auth: null });
-    await session.waitForCompletion();
-    const folded = await engine.abSnapshot(null);
-    expect(folded).not.toEqual(restoredSnapshot);
-    expect(folded.config?.maxPlaygroundSessions).not.toBe(123);
-  });
-
-  it("is a no-op with a write-only sink", async () => {
-    const definition = defineStorage({ put: () => {} });
-    const stateRoot = await tempStateRoot();
-    const engine = new SessionEngine({
-      project: testProject(stateRoot, definition),
-      stateRoot,
-      runner: echoRunner([]),
-    });
-    cleanups.push(() => engine.close());
-    await expect(engine.restoreStoredSessions()).resolves.toBeUndefined();
-  });
-
-  it("lists sessions from cursor-hosted storage and falls back to local", async () => {
-    const sink = memorySink({ cursorHosted: true });
-    const stateRootA = await tempStateRoot();
-    const engineA = new SessionEngine({
-      project: testProject(stateRootA, sink.definition),
-      stateRoot: stateRootA,
-      runner: echoRunner([]),
-    });
-    const session = await engineA.send("http", "hi", { auth: null });
-    await session.waitForCompletion();
-    await engineA.close();
-
-    // Host B: restore off — nothing local, but the durable row remains.
-    const stateRootB = await tempStateRoot();
-    const engineB = new SessionEngine({
-      project: testProject(
-        stateRootB,
-        defineStorage({
-          ...sink.definition,
-          policy: { restore: "off" },
-        })
-      ),
-      stateRoot: stateRootB,
-      runner: echoRunner([]),
-    });
-    cleanups.push(() => engineB.close());
-    await engineB.restoreStoredSessions();
-    expect(await engineB.sessions.get(session.id)).toBeUndefined();
-
-    const fromDb = await engineB.listSessionsWithSource(null, {
-      includeAll: true,
-    });
-    expect(fromDb.source).toBe("cursor-hosted");
-    expect(fromDb.sessions.map((s) => s.sessionId)).toContain(session.id);
-
-    // Broken list → local fallback (empty on this host).
-    const broken = Object.assign(
-      defineStorage({
-        put: () => {},
-        list: () => {
-          throw new Error("store down");
-        },
-      }),
-      { [CURSOR_HOSTED_STORAGE]: true as const }
-    );
-    const stateRootC = await tempStateRoot();
-    const engineC = new SessionEngine({
-      project: testProject(stateRootC, broken),
-      stateRoot: stateRootC,
-      runner: echoRunner([]),
-    });
-    cleanups.push(() => engineC.close());
-    await expect(
-      engineC.listSessionsWithSource(null, { includeAll: true })
-    ).resolves.toEqual({ sessions: [], source: "local" });
-  });
-
-  it("reports local source when storage is not cursor-hosted", async () => {
-    const sink = memorySink();
-    const stateRoot = await tempStateRoot();
-    const engine = new SessionEngine({
-      project: testProject(stateRoot, sink.definition),
-      stateRoot,
-      runner: echoRunner([]),
-    });
-    cleanups.push(() => engine.close());
-    const session = await engine.send("http", "hi", { auth: null });
-    await session.waitForCompletion();
-    const listed = await engine.listSessionsWithSource(null, {
-      includeAll: true,
-    });
-    expect(listed.source).toBe("local");
-    expect(listed.sessions.map((s) => s.sessionId)).toEqual([session.id]);
-  });
-
-  it("lazily restores a durable session by id for playground Open-trace", async () => {
-    const sink = memorySink({ cursorHosted: true });
-    const stateRootA = await tempStateRoot();
-    const engineA = new SessionEngine({
-      project: testProject(stateRootA, sink.definition),
-      stateRoot: stateRootA,
-      runner: echoRunner([]),
-    });
-    const session = await engineA.send("http", "eval case", {
-      auth: null,
-      purpose: "eval",
-    });
-    await session.waitForCompletion();
-    const eventsA = await engineA.listEvents(session.id);
-    expect(eventsA.length).toBeGreaterThan(0);
-    await engineA.close();
-
-    // Replacement host with restore off: listed in durable storage, absent locally.
-    const stateRootB = await tempStateRoot();
-    const engineB = new SessionEngine({
-      project: testProject(
-        stateRootB,
-        defineStorage({
-          ...sink.definition,
-          policy: { restore: "off" },
-        })
-      ),
-      stateRoot: stateRootB,
-      runner: echoRunner([]),
-    });
-    cleanups.push(() => engineB.close());
-    await engineB.restoreStoredSessions();
-    expect(await engineB.sessions.get(session.id)).toBeUndefined();
-
-    const restored = await engineB.getOrRestoreSession(session.id);
-    expect(restored?.sessionId).toBe(session.id);
-    expect(await engineB.sessions.get(session.id)).toBeDefined();
-    expect(await engineB.listEvents(session.id)).toEqual(eventsA);
-
-    // Unknown id stays a definitive miss.
-    await expect(engineB.getOrRestoreSession("ses_missing")).resolves.toBe(
-      undefined
-    );
-  });
-});

package/src/internal/session-urls.test.ts

@@ -1,28 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  eventsUrlForSession,
-  playgroundUrlForSession,
-  sessionUrlsForRequest,
-} from "./session-urls.js";
-
-describe("sessionUrls", () => {
-  it("builds playground and trace URLs for a single-agent mount", () => {
-    const request = new Request("http://127.0.0.1:3000/v1/channels/review");
-    expect(sessionUrlsForRequest(request, "", "ses_abc")).toEqual({
-      playgroundUrl: "http://127.0.0.1:3000/playground?sessionId=ses_abc",
-      traceUrl: "http://127.0.0.1:3000/v1/session/ses_abc/events",
-    });
-  });
-
-  it("prefixes the multi-agent slug mount", () => {
-    const request = new Request(
-      "http://127.0.0.1:3000/bugbot/v1/channels/review"
-    );
-    expect(playgroundUrlForSession(request, "/bugbot", "ses_1")).toBe(
-      "http://127.0.0.1:3000/bugbot/playground?sessionId=ses_1"
-    );
-    expect(eventsUrlForSession(request.url, "bugbot", "ses with spaces")).toBe(
-      "http://127.0.0.1:3000/bugbot/v1/session/ses%20with%20spaces/events"
-    );
-  });
-});