@cursor/july 0.1.20 → 0.1.21

package/src/internal/cursor-event-relay.test.ts

@@ -0,0 +1,746 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { httpChannel } from "../channels.js";
+import type { AgentProject, AgentServeHandle } from "../types.js";
+import {
+  CursorEventRelay,
+  type CursorScmEvent,
+  formatCursorScmEventLog,
+  RelayOffsetStore,
+  scmMetadataToGitHubPayload,
+} from "./cursor-event-relay.js";
+import type { AgentRunner } from "./sdk-runner.js";
+import { startServer } from "./server.js";
+
+interface RecordedRequest {
+  method: string;
+  url: string;
+  body?: unknown;
+}
+
+/**
+ * Minimal fake of the /v0/scm-events surface: records requests and serves a
+ * scripted queue of poll responses (after the queue drains, polls return
+ * empty pages). Registration echoes the requested repos as subscribed;
+ * `registrationFailures` makes the first N registration attempts fail with
+ * a 500.
+ */
+function fakeBackend(script: {
+  anchorOffset?: string;
+  polls?: Array<{
+    events: CursorScmEvent[];
+    nextOffset: string;
+    gapDetected?: boolean;
+  }>;
+  registrationFailures?: number;
+}) {
+  const requests: RecordedRequest[] = [];
+  const polls = [...(script.polls ?? [])];
+  let registrationFailures = script.registrationFailures ?? 0;
+  const fetchImpl: typeof fetch = async (input, init) => {
+    const url = String(input);
+    const method = init?.method ?? "GET";
+    const body =
+      typeof init?.body === "string"
+        ? (JSON.parse(init.body) as unknown)
+        : undefined;
+    requests.push({ method, url, ...(body === undefined ? {} : { body }) });
+
+    if (url.includes("/v0/scm-events/subscriptions")) {
+      if (registrationFailures > 0) {
+        registrationFailures -= 1;
+        return new Response("storage unavailable", { status: 503 });
+      }
+      return jsonResponse({
+        repos: (
+          (body as { subscriptions?: Array<{ repo: string }> })
+            ?.subscriptions ?? []
+        ).map((subscription) => ({
+          provider: "github",
+          repo: subscription.repo,
+          isSubscribed: true,
+        })),
+        expiresAt: new Date().toISOString(),
+      });
+    }
+    if (url.includes("after=%24") || url.includes("after=$")) {
+      return jsonResponse({
+        events: [],
+        nextOffset: script.anchorOffset ?? "",
+        gapDetected: false,
+      });
+    }
+    const page = polls.shift() ?? {
+      events: [],
+      nextOffset: "",
+      gapDetected: false,
+    };
+    return jsonResponse(page);
+  };
+  return { requests, fetchImpl };
+}
+
+function jsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function event(
+  offset: string,
+  eventName: string,
+  repo = "acme/repo"
+): CursorScmEvent {
+  return {
+    offset,
+    provider: "github",
+    eventName,
+    deliveryId: `delivery-${offset}`,
+    repo,
+    receivedAtMs: Date.now(),
+  };
+}
+
+describe("formatCursorScmEventLog", () => {
+  it("includes PR url, action, and timestamps", () => {
+    expect(
+      formatCursorScmEventLog({
+        eventName: "issue_comment",
+        action: "created",
+        repo: "anysphere/everysphere",
+        prNumber: 167588,
+        prUrl: "https://github.com/anysphere/everysphere/pull/167588",
+        receivedAtMs: Date.parse("2026-07-13T16:00:00.000Z"),
+        occurredAtMs: Date.parse("2026-07-13T15:59:00.000Z"),
+        deliveryId: "abc",
+      })
+    ).toBe(
+      "issue_comment.created on https://github.com/anysphere/everysphere/pull/167588 received=2026-07-13T16:00:00.000Z occurred=2026-07-13T15:59:00.000Z (abc)"
+    );
+  });
+});
+
+describe("scmMetadataToGitHubPayload", () => {
+  it("stubs a Zod-complete pull_request when rich meta is present", () => {
+    const payload = scmMetadataToGitHubPayload({
+      repo: "acme/repo",
+      action: "opened",
+      prNumber: 12,
+      prUrl: "https://github.com/acme/repo/pull/12",
+      pullRequest: {
+        number: 12,
+        url: "https://github.com/acme/repo/pull/12",
+        title: "Add widgets",
+        body: null,
+        draft: false,
+        merged: false,
+        authorLogin: "bob",
+        headRef: "feature",
+        headSha: "aaa111",
+        baseRef: "main",
+        baseSha: "bbb222",
+      },
+    });
+    expect(payload).toEqual({
+      action: "opened",
+      repository: {
+        full_name: "acme/repo",
+        name: "repo",
+        html_url: "https://github.com/acme/repo",
+        owner: { login: "acme" },
+      },
+      pull_request: {
+        number: 12,
+        html_url: "https://github.com/acme/repo/pull/12",
+        title: "Add widgets",
+        body: null,
+        draft: false,
+        merged: false,
+        user: { login: "bob" },
+        head: { ref: "feature", sha: "aaa111" },
+        base: { ref: "main", sha: "bbb222" },
+      },
+      issue: {
+        number: 12,
+        html_url: "https://github.com/acme/repo/pull/12",
+        pull_request: {},
+      },
+    });
+  });
+
+  it("stubs merged=true so closed+merged handlers can fire", () => {
+    const payload = scmMetadataToGitHubPayload({
+      repo: "acme/repo",
+      action: "closed",
+      prNumber: 99,
+      pullRequest: {
+        number: 99,
+        url: "https://github.com/acme/repo/pull/99",
+        title: "Ship it",
+        draft: false,
+        merged: true,
+        authorLogin: "alice",
+        headRef: "ship",
+        headSha: "aaa",
+        baseRef: "main",
+        baseSha: "bbb",
+      },
+    });
+    expect(payload.action).toBe("closed");
+    expect(
+      (payload.pull_request as { merged?: boolean } | undefined)?.merged
+    ).toBe(true);
+  });
+
+  it("falls back to identity-only stubs without head/base", () => {
+    expect(
+      scmMetadataToGitHubPayload({
+        repo: "acme/repo",
+        action: "opened",
+        prNumber: 12,
+        prUrl: "https://github.com/acme/repo/pull/12",
+        pullRequest: {
+          number: 12,
+          url: "https://github.com/acme/repo/pull/12",
+        },
+      })
+    ).toEqual({
+      action: "opened",
+      repository: {
+        full_name: "acme/repo",
+        name: "repo",
+        html_url: "https://github.com/acme/repo",
+        owner: { login: "acme" },
+      },
+      pull_request: {
+        number: 12,
+        html_url: "https://github.com/acme/repo/pull/12",
+      },
+      issue: {
+        number: 12,
+        html_url: "https://github.com/acme/repo/pull/12",
+        pull_request: {},
+      },
+    });
+  });
+
+  it("stubs a Zod-complete comment for issue_comment envelopes", () => {
+    const payload = scmMetadataToGitHubPayload({
+      repo: "acme/repo",
+      action: "created",
+      prNumber: 12,
+      prUrl: "https://github.com/acme/repo/pull/12",
+      comment: {
+        id: 5551212,
+        body: "@my-agent rereview",
+        htmlUrl: "https://github.com/acme/repo/pull/12#issuecomment-5551212",
+        authorLogin: "alice",
+        authorType: "User",
+      },
+    });
+    expect(payload.comment).toEqual({
+      id: 5551212,
+      body: "@my-agent rereview",
+      html_url: "https://github.com/acme/repo/pull/12#issuecomment-5551212",
+      user: { login: "alice", type: "User" },
+    });
+    expect(payload.sender).toEqual({ login: "alice", type: "User" });
+    expect(payload.issue).toEqual({
+      number: 12,
+      html_url: "https://github.com/acme/repo/pull/12",
+      pull_request: {},
+    });
+  });
+
+  it("carries review-thread anchors for pull_request_review_comment", () => {
+    const payload = scmMetadataToGitHubPayload({
+      repo: "acme/repo",
+      action: "created",
+      prNumber: 12,
+      comment: {
+        id: 901,
+        body: "nit",
+        htmlUrl: "https://github.com/acme/repo/pull/12#discussion_r901",
+        authorLogin: "bob",
+        path: "src/index.ts",
+        line: 3,
+        pullRequestReviewId: 77,
+        inReplyToId: 900,
+      },
+    });
+    expect(payload.comment).toEqual({
+      id: 901,
+      body: "nit",
+      html_url: "https://github.com/acme/repo/pull/12#discussion_r901",
+      user: { login: "bob" },
+      path: "src/index.ts",
+      line: 3,
+      pull_request_review_id: 77,
+      in_reply_to_id: 900,
+    });
+  });
+});
+
+async function waitFor(
+  predicate: () => boolean,
+  timeoutMs = 2_000
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!predicate()) {
+    if (Date.now() > deadline) {
+      throw new Error("waitFor timed out");
+    }
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+
+describe("RelayOffsetStore", () => {
+  let dir: string;
+
+  afterEach(async () => {
+    if (dir !== undefined) {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("round-trips offsets and tolerates a missing file", async () => {
+    dir = await mkdtemp(join(tmpdir(), "cursor-events-"));
+    const store = new RelayOffsetStore(dir);
+    expect(await store.load()).toBeUndefined();
+    await store.save("123-4");
+    expect(await store.load()).toBe("123-4");
+    const raw = JSON.parse(await readFile(join(dir, "offset.json"), "utf8"));
+    expect(raw.version).toBe(1);
+  });
+});
+
+describe("CursorEventRelay", () => {
+  let dir: string;
+  let relay: CursorEventRelay | undefined;
+
+  afterEach(async () => {
+    await relay?.stop();
+    relay = undefined;
+    if (dir !== undefined) {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  function makeRelay(
+    backend: ReturnType<typeof fakeBackend>,
+    options?: {
+      dispatch?: (e: CursorScmEvent) => Promise<void>;
+      logger?: (line: string) => void;
+      repos?: string[];
+      events?: string[];
+    }
+  ): { dispatched: CursorScmEvent[] } {
+    const dispatched: CursorScmEvent[] = [];
+    relay = new CursorEventRelay({
+      baseUrl: "https://api2.example",
+      apiKey: "key",
+      repos: options?.repos ?? ["acme/repo"],
+      events: options?.events ?? ["pull_request", "issue_comment", "push"],
+      stateDir: dir,
+      dispatch:
+        options?.dispatch ??
+        (async (e) => {
+          dispatched.push(e);
+        }),
+      logger: options?.logger ?? (() => {}),
+      fetchImpl: backend.fetchImpl,
+      pollWaitMs: 0,
+    });
+    relay.start();
+    return { dispatched };
+  }
+
+  it("registers before consuming, anchors at now, dispatches in order, persists offset and consumer id", async () => {
+    dir = await mkdtemp(join(tmpdir(), "cursor-events-"));
+    const backend = fakeBackend({
+      anchorOffset: "100-0",
+      polls: [
+        {
+          events: [
+            event("101-0", "pull_request"),
+            event("102-0", "issue_comment"),
+          ],
+          nextOffset: "102-0",
+        },
+      ],
+    });
+    const { dispatched } = makeRelay(backend);
+
+    await waitFor(() => dispatched.length === 2);
+    expect(dispatched.map((e) => e.eventName)).toEqual([
+      "pull_request",
+      "issue_comment",
+    ]);
+    await waitFor(() =>
+      backend.requests.some((r) => r.url.includes("after=102-0"))
+    );
+    await relay?.stop();
+    relay = undefined;
+
+    const store = new RelayOffsetStore(dir);
+    expect(await store.load()).toBe("102-0");
+
+    // Consumption is registration-gated: the first request is the PUT, and
+    // no GET happens before it.
+    expect(backend.requests[0]?.method).toBe("PUT");
+    const registration = backend.requests[0];
+    expect(registration?.body).toMatchObject({
+      subscriptions: [
+        {
+          provider: "github",
+          repo: "acme/repo",
+          events: ["pull_request", "issue_comment", "push"],
+        },
+      ],
+    });
+    const consumerId = (registration?.body as { consumerId?: string })
+      ?.consumerId;
+    expect(typeof consumerId).toBe("string");
+    expect(consumerId?.length).toBeGreaterThan(0);
+    // The consumer id is durable in the state dir.
+    expect((await readFile(join(dir, "consumer-id"), "utf8")).trim()).toBe(
+      consumerId
+    );
+    // The first poll after anchoring resumes from the anchor offset.
+    expect(
+      backend.requests.some(
+        (r) => r.method === "GET" && r.url.includes("after=100-0")
+      )
+    ).toBe(true);
+  });
+
+  it("retries registration until it succeeds before any consumption", async () => {
+    dir = await mkdtemp(join(tmpdir(), "cursor-events-"));
+    const backend = fakeBackend({
+      anchorOffset: "10-0",
+      polls: [{ events: [event("11-0", "pull_request")], nextOffset: "11-0" }],
+      registrationFailures: 1,
+    });
+    const { dispatched } = makeRelay(backend);
+
+    await waitFor(() => dispatched.length === 1, 10_000);
+    const firstGetIndex = backend.requests.findIndex((r) => r.method === "GET");
+    const successfulPutIndex = backend.requests.findIndex(
+      (r, index) => r.method === "PUT" && index > 0
+    );
+    // Two PUTs (one failed, one ok) happened before the first GET.
+    expect(firstGetIndex).toBeGreaterThan(successfulPutIndex);
+    expect(
+      backend.requests.filter((r) => r.method === "PUT").length
+    ).toBeGreaterThanOrEqual(2);
+  }, 15_000);
+
+  it("deregisters on clean stop so the registration does not linger by TTL", async () => {
+    dir = await mkdtemp(join(tmpdir(), "cursor-events-"));
+    const backend = fakeBackend({ anchorOffset: "1-0" });
+    makeRelay(backend);
+    await waitFor(() => backend.requests.some((r) => r.method === "GET"));
+    const consumerId = (backend.requests[0]?.body as { consumerId?: string })
+      ?.consumerId;
+
+    await relay?.stop();
+    relay = undefined;
+
+    const lastPut = backend.requests.filter((r) => r.method === "PUT").at(-1);
+    expect(lastPut?.body).toEqual({ consumerId, subscriptions: [] });
+  });
+
+  it("does not deregister when registration never succeeded", async () => {
+    dir = await mkdtemp(join(tmpdir(), "cursor-events-"));
+    // Registration keeps failing; stop before it ever succeeds.
+    const backend = fakeBackend({ registrationFailures: 1_000 });
+    makeRelay(backend);
+    await waitFor(() => backend.requests.some((r) => r.method === "PUT"));
+
+    await relay?.stop();
+    relay = undefined;
+
+    expect(
+      backend.requests.some(
+        (r) =>
+          r.method === "PUT" &&
+          Array.isArray(
+            (r.body as { subscriptions?: unknown[] })?.subscriptions
+          ) &&
+          (r.body as { subscriptions: unknown[] }).subscriptions.length === 0
+      )
+    ).toBe(false);
+  });
+
+  it("retries a transiently failing dispatch before advancing the offset", async () => {
+    dir = await mkdtemp(join(tmpdir(), "cursor-events-"));
+    const backend = fakeBackend({
+      anchorOffset: "1-0",
+      polls: [{ events: [event("2-0", "pull_request")], nextOffset: "2-0" }],
+    });
+    const logs: string[] = [];
+    const delivered: CursorScmEvent[] = [];
+    let attempts = 0;
+    makeRelay(backend, {
+      logger: (line) => logs.push(line),
+      dispatch: async (e) => {
+        attempts += 1;
+        if (attempts === 1) {
+          throw new Error("read ECONNRESET");
+        }
+        delivered.push(e);
+      },
+    });
+
+    await waitFor(() => delivered.length === 1, 5_000);
+    expect(attempts).toBe(2);
+    expect(
+      logs.some(
+        (line) =>
+          line.includes("dispatch attempt 1") && line.includes("retrying")
+      )
+    ).toBe(true);
+    await relay?.stop();
+    relay = undefined;
+    const store = new RelayOffsetStore(dir);
+    expect(await store.load()).toBe("2-0");
+  });
+
+  it("resumes from a persisted offset and dedupes replayed events", async () => {
+    dir = await mkdtemp(join(tmpdir(), "cursor-events-"));
+    const store = new RelayOffsetStore(dir);
+    await store.save("200-0");
+
+    const backend = fakeBackend({
+      polls: [
+        {
+          // 200-0 replayed (at-least-once); only 201-0 must dispatch.
+          events: [event("200-0", "pull_request"), event("201-0", "push")],
+          nextOffset: "201-0",
+        },
+      ],
+    });
+    const { dispatched } = makeRelay(backend);
+
+    await waitFor(() => dispatched.length >= 1);
+    // No anchor request: the persisted offset is the resume point.
+    expect(
+      backend.requests.some(
+        (r) => r.method === "GET" && r.url.includes("after=%24")
+      )
+    ).toBe(false);
+    expect(
+      backend.requests.some(
+        (r) => r.method === "GET" && r.url.includes("after=200-0")
+      )
+    ).toBe(true);
+    expect(dispatched.map((e) => e.offset)).toEqual(["201-0"]);
+  });
+
+  it("skips events from sibling consumers (foreign repos and event kinds) while advancing the offset", async () => {
+    dir = await mkdtemp(join(tmpdir(), "cursor-events-"));
+    const backend = fakeBackend({
+      anchorOffset: "0-1",
+      polls: [
+        {
+          events: [
+            // Foreign repo: another consumer of the same key subscribed it.
+            event("1-0", "pull_request", "other/repo"),
+            // Foreign event kind: not declared by this host's channels.
+            event("2-0", "workflow_run"),
+            // Ours.
+            event("3-0", "pull_request"),
+          ],
+          nextOffset: "3-0",
+        },
+      ],
+    });
+    const logs: string[] = [];
+    const { dispatched } = makeRelay(backend, {
+      logger: (line) => logs.push(line),
+    });
+
+    await waitFor(() => dispatched.length === 1);
+    expect(dispatched[0]?.offset).toBe("3-0");
+    await relay?.stop();
+    relay = undefined;
+    // The skipped events still advanced the durable offset.
+    const store = new RelayOffsetStore(dir);
+    expect(await store.load()).toBe("3-0");
+    expect(logs.some((line) => line.includes("other/repo"))).toBe(true);
+  });
+
+  it("keeps consuming when a dispatch throws", async () => {
+    dir = await mkdtemp(join(tmpdir(), "cursor-events-"));
+    const backend = fakeBackend({
+      anchorOffset: "0-1",
+      polls: [
+        {
+          events: [event("1-0", "pull_request"), event("2-0", "push")],
+          nextOffset: "2-0",
+        },
+      ],
+    });
+    const dispatched: string[] = [];
+    const logs: string[] = [];
+    makeRelay(backend, {
+      logger: (line) => logs.push(line),
+      dispatch: async (e) => {
+        if (e.eventName === "pull_request") {
+          throw new Error("hook exploded");
+        }
+        dispatched.push(e.eventName);
+      },
+    });
+
+    await waitFor(() => dispatched.length === 1);
+    expect(dispatched).toEqual(["push"]);
+    expect(logs.some((line) => line.includes("dispatch failed"))).toBe(true);
+    await relay?.stop();
+    relay = undefined;
+    const store = new RelayOffsetStore(dir);
+    // The failed event still advances the offset (webhook semantics: no
+    // infinite retry on a poison delivery).
+    expect(await store.load()).toBe("2-0");
+  });
+
+  it("logs subscription success on a clean first registration", async () => {
+    dir = await mkdtemp(join(tmpdir(), "cursor-events-"));
+    const backend = fakeBackend({ anchorOffset: "1-0" });
+    const logs: string[] = [];
+    makeRelay(backend, { logger: (line) => logs.push(line) });
+    await waitFor(() =>
+      logs.some((line) => line.includes("subscribed to acme/repo"))
+    );
+  });
+
+  it("reuses the persisted consumer id across restarts", async () => {
+    dir = await mkdtemp(join(tmpdir(), "cursor-events-"));
+    const backendA = fakeBackend({ anchorOffset: "1-0" });
+    makeRelay(backendA);
+    await waitFor(() => backendA.requests.some((r) => r.method === "PUT"));
+    await relay?.stop();
+    relay = undefined;
+    const firstConsumerId = (
+      backendA.requests.find((r) => r.method === "PUT")?.body as {
+        consumerId?: string;
+      }
+    )?.consumerId;
+
+    const backendB = fakeBackend({ anchorOffset: "1-0" });
+    makeRelay(backendB);
+    await waitFor(() => backendB.requests.some((r) => r.method === "PUT"));
+    const secondConsumerId = (
+      backendB.requests.find((r) => r.method === "PUT")?.body as {
+        consumerId?: string;
+      }
+    )?.consumerId;
+    expect(firstConsumerId).toBeDefined();
+    expect(secondConsumerId).toBe(firstConsumerId);
+  });
+});
+
+describe("serve({ cursorEvents }) sign-in requirement", () => {
+  const savedEnv: Record<string, string | undefined> = {};
+  let stateRoot: string | undefined;
+  let handle: AgentServeHandle | undefined;
+
+  const runner: AgentRunner = {
+    async runTurn() {
+      return { status: "finished", result: "unused" };
+    },
+  };
+
+  function fixture(): AgentProject {
+    return {
+      rootDir: "/tmp/cursor-events-fixture",
+      agentDir: "/tmp/cursor-events-fixture/agent",
+      name: "relay-fixture",
+      agent: {
+        name: "relay-fixture",
+        runtime: "local",
+        tools: [],
+        skills: [],
+        connections: [],
+        subagents: [],
+        seedFiles: [],
+      },
+      httpChannel: httpChannel(),
+      channels: [],
+      schedules: [],
+      hooks: [],
+      abs: [],
+      diagnostics: [],
+    };
+  }
+
+  beforeEach(() => {
+    for (const key of [
+      "CURSOR_API_KEY",
+      "CURSOR_API_BASE_URL",
+      "AGENT_SERVE_CONFIG_DIR",
+    ]) {
+      savedEnv[key] = process.env[key];
+      delete process.env[key];
+    }
+    // No stored login can leak in from the developer's machine.
+    process.env.AGENT_SERVE_CONFIG_DIR = "/nonexistent-agent-serve-config";
+  });
+
+  afterEach(async () => {
+    await handle?.close();
+    handle = undefined;
+    if (stateRoot !== undefined) {
+      await rm(stateRoot, { recursive: true, force: true });
+      stateRoot = undefined;
+    }
+    for (const [key, value] of Object.entries(savedEnv)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+
+  it("refuses to serve when the host is not signed in to Cursor", async () => {
+    const root = await mkdtemp(join(tmpdir(), "agent-serve-cursor-events-"));
+    stateRoot = root;
+    await expect(
+      startServer([{ slug: "", project: fixture() }], {
+        port: 0,
+        stateRoot: root,
+        playground: false,
+        runner,
+        cursorEvents: { repos: ["acme/repo"] },
+      })
+    ).rejects.toThrow(
+      /--cursor-events[\s\S]*signed-in Cursor account[\s\S]*agentkit login/
+    );
+  });
+
+  it("accepts CURSOR_API_KEY instead of a stored login (CI, hosted hosts)", async () => {
+    const root = await mkdtemp(join(tmpdir(), "agent-serve-cursor-events-"));
+    stateRoot = root;
+    process.env.CURSOR_API_KEY = "crsr_env";
+    const logs: string[] = [];
+    handle = await startServer([{ slug: "", project: fixture() }], {
+      port: 0,
+      stateRoot: root,
+      playground: false,
+      runner,
+      logger: (line) => logs.push(line),
+      cursorEvents: { repos: ["acme/repo"] },
+    });
+    // Credential present, so startup proceeds. This fixture declares no github
+    // channel, so the relay stays off (warn-only path) without polling.
+    expect(
+      logs.some((line) =>
+        line.includes("no mounted agent declares a github channel")
+      )
+    ).toBe(true);
+  });
+});