@cursor/july 0.1.19 → 0.1.21

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

@@ -0,0 +1,547 @@
+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-engine.ts

@@ -34,6 +34,7 @@ import {
   type HookHandler,
   type HostContext,
   type HttpChannelDefinition,
+  isHostOauthConnectionTransport,
   isSymbolicConnectionTransport,
   type JsonValue,
   type PendingApproval,
@@ -1312,7 +1313,10 @@ export class SessionEngine {
     };
   }
 
-  /** Authored + resolved MCP servers for a turn; skips `hostOnly`. */
+  /**
+   * Authored + resolved MCP servers for a turn; skips `hostOnly`, and skips
+   * host-OAuth connections on cloud turns (their tokens live on this host).
+   */
   private buildMcpServers(
     runtime: "local" | "cloud"
   ): Record<string, ConnectionTransport> {
@@ -1335,6 +1339,16 @@ export class SessionEngine {
       if (isSymbolicConnectionTransport(connection.transport)) {
         continue;
       }
+      // A cloud VM cannot use a credential that lives on this host, and the
+      // cloud API rejects the `oauth` key outright ("Unrecognized key(s) in
+      // object: 'oauth'"), which fails the whole turn. Omit it there; host
+      // tools (`ctx.host.mcp`) still reach the server over the host client.
+      if (
+        runtime === "cloud" &&
+        isHostOauthConnectionTransport(connection.transport)
+      ) {
+        continue;
+      }
       servers[connection.name] = connection.transport;
     }
     for (const resolved of this.resolvedConnections) {

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

@@ -0,0 +1,28 @@
+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"
+    );
+  });
+});