@cursor/july 0.1.85 → 0.1.86

package/src/internal/server.ts

@@ -129,6 +129,7 @@ import {
   createLocalControlPlane,
   type LocalControlPlane,
 } from "./local-control-plane.js";
+import type { RouteLocalIngressContinuation } from "./local-ingress.js";
 import { createLogRing, type LogRing } from "./log-ring.js";
 import {
   createAgentMcpEndpoint,
@@ -216,6 +217,28 @@ interface MountedRuntime {
   evalRuns: EvalRunStore;
 }
 
+function localControlPlaneRoute(
+  runtimes: readonly MountedRuntime[]
+): RouteLocalIngressContinuation | undefined {
+  for (const runtime of runtimes) {
+    if (runtime.controlPlane !== undefined) {
+      return (input) => runtime.controlPlane!.routeContinuation(input);
+    }
+  }
+  return undefined;
+}
+
+function firstLocalControlPlane(
+  runtimes: readonly MountedRuntime[]
+): LocalControlPlane | undefined {
+  return runtimes.find((runtime) => runtime.controlPlane !== undefined)
+    ?.controlPlane;
+}
+
+function isV2Project(project: { agent: { architecture?: string } }): boolean {
+  return project.agent.architecture === "v2";
+}
+
 /** Internal-only options for {@link startServer} (not on public `serve`). */
 export interface StartServerInternalOptions {
   /** Test seam: replace the Cursor SDK runner (integration tests). */
@@ -317,6 +340,20 @@ export async function startServer(
       ? undefined
       : requireCursorEventsAuth(effectiveCursorEvents, accountKey);
 
+  // Two architectures + local CP + cursor-events would register two
+  // /v0/scm-events consumers (engine offset vs control-plane offset).
+  // Fail before engines or relays start. `--no-control-plane` mixed is one
+  // July consumer (v1 engine); hosted CP owns v2.
+  assertSingleCursorEventsLane({
+    noControlPlane,
+    config: effectiveCursorEvents,
+    auth: cursorEventsAuth,
+    v1Mounts: mounts.filter((mount) => !isV2Project(mount.project)),
+    v2Mounts: mounts.filter((mount) => isV2Project(mount.project)),
+    githubRepos: cursorGithubConfig.cursorEvents?.repos ?? [],
+    originRepos: cursorOriginScope?.repos ?? [],
+  });
+
   let cursorGithubCredentials: CursorGithubCredentialProvider | undefined;
   // Proxy-wired GitHub token resolver for `ctx.host.github` when no startup
   // token mint runs (empty repo scope): host Octokit calls must route
@@ -755,36 +792,46 @@ export async function startServer(
   // job (backend `/github_webhook` already verified); we only admit loopback
   // so this route is not a public unsigned endpoint. Agents decide whether
   // to run via their onPullRequest / onComment / … hooks.
-  const collectGitHubTargets = () =>
+  const collectGitHubTargetsFrom = (selected: readonly MountedRuntime[]) =>
     collectGitHubTriggerTargets({
-      mounts: runtimes.map((runtime) => ({
+      mounts: selected.map((runtime) => ({
         slug: runtime.slug,
         channels: runtime.project.channels,
         buildHandlerArgs: (channelId) =>
           buildChannelHandlerArgs({ runtime, channelId }),
       })),
     });
-  const collectOriginTargets = () =>
+  const collectOriginTargetsFrom = (selected: readonly MountedRuntime[]) =>
     collectOriginTriggerTargets({
-      mounts: runtimes.map((runtime) => ({
+      mounts: selected.map((runtime) => ({
         slug: runtime.slug,
         channels: runtime.project.channels,
         buildHandlerArgs: (channelId) =>
           buildChannelHandlerArgs({ runtime, channelId }),
       })),
     });
+  const collectGitHubTargets = () => collectGitHubTargetsFrom(runtimes);
+  const collectOriginTargets = () => collectOriginTargetsFrom(runtimes);
+  const v1Runtimes = runtimes.filter(
+    (runtime) => !isV2Project(runtime.project)
+  );
+  const v2Runtimes = runtimes.filter((runtime) => isV2Project(runtime.project));
+  const v1Mounts = mounts.filter((mount) => !isV2Project(mount.project));
+  const v2Mounts = mounts.filter((mount) => isV2Project(mount.project));
   router.add({
     method: "POST",
     pattern: "/v1/webhooks/github",
     auth: [localDevStrict()],
     handler: async (request) => {
       const bodyText = await request.text();
+      const routeContinuation = localControlPlaneRoute(runtimes);
       const result = await handleAgentServeTrigger({
         type: "github",
         bodyText,
         eventName: request.headers.get("x-github-event"),
         deliveryId: request.headers.get("x-github-delivery") ?? undefined,
         targets: collectGitHubTargets(),
+        ...(routeContinuation === undefined ? {} : { routeContinuation }),
       });
       const status = result.ok ? 202 : (result.targets[0]?.status ?? 500);
       return jsonResponse(result, { status });
@@ -820,21 +867,48 @@ export async function startServer(
     throw error;
   }
 
-  // Cursor SCM events relay (opt-in: serve({ cursorEvents }) / --cursor-events).
-  const cursorEventRelay = startCursorEventRelay({
+  // Cursor SCM events: v1 stays on the engine poll. v2 ingest is local-CP
+  // only — hosted `--no-control-plane` skips the July poll (hosted CP wakes).
+  const routeContinuation = localControlPlaneRoute(runtimes);
+  const cursorEventsCommon = {
     config: effectiveCursorEvents,
     githubRepos: cursorGithubConfig.cursorEvents?.repos ?? [],
     originRepos: cursorOriginScope?.repos ?? [],
     stateRoot: options.stateRoot,
-    mounts,
     auth: cursorEventsAuth,
     logger,
-    collectGitHubTargets,
-    collectOriginTargets,
     cursorAccountOnly:
       options.cursorEvents === undefined &&
       (cursorGithubTargets.length > 0 || cursorOriginTargets.length > 0),
+  };
+  const cursorEventRelay = startCursorEventRelay({
+    ...cursorEventsCommon,
+    mounts: v1Mounts,
+    collectGitHubTargets: () => collectGitHubTargetsFrom(v1Runtimes),
+    collectOriginTargets: () => collectOriginTargetsFrom(v1Runtimes),
+    lane: "engine",
+    skippedV2: v2Mounts.length > 0,
+  });
+  const controlPlaneScmRelay = startCursorEventRelay({
+    ...cursorEventsCommon,
+    mounts: v2Mounts,
+    collectGitHubTargets: () => collectGitHubTargetsFrom(v2Runtimes),
+    collectOriginTargets: () => collectOriginTargetsFrom(v2Runtimes),
+    ...(routeContinuation === undefined ? {} : { routeContinuation }),
+    lane: "control-plane",
+    start: false,
+    stateDirName: join("control-plane", "cursor-events"),
   });
+  const localCp = firstLocalControlPlane(runtimes);
+  if (controlPlaneScmRelay !== undefined) {
+    if (localCp !== undefined) {
+      localCp.attachScmEvents(controlPlaneScmRelay);
+    } else {
+      logger(
+        "[agent-sdk] cursor-events: skipping v2 scm-events poll (--no-control-plane); hosted CP owns ingest"
+      );
+    }
+  }
 
   // Cursor deployment-events relay: automatic when a mounted agent authored
   // `deploymentsChannel({ ... })`.
@@ -866,6 +940,7 @@ export async function startServer(
   } catch (error) {
     await cursorDeploymentRelay?.stop();
     await cursorEventRelay?.stop();
+    await controlPlaneScmRelay?.stop();
     await cursorSlackRelay?.stop();
     cursorGithubCredentials?.stop();
     await shutdownOtelRuntime(otelRuntime);
@@ -1027,6 +1102,7 @@ export async function startServer(
       playgroundDev?.stop();
       await cursorDeploymentRelay?.stop();
       await cursorEventRelay?.stop();
+      await controlPlaneScmRelay?.stop();
       await cursorSlackRelay?.stop();
       for (const runtime of runtimes) {
         runtime.controlPlane?.stop();
@@ -1878,24 +1954,13 @@ function requireCursorEventsAuth(
  * channels; Origin is subscribed only when an `originChannel({ cursorAccount })`
  * opted in.
  */
-function startCursorEventRelay(input: {
-  config: ServeOptions["cursorEvents"];
+function collectCursorEventSubscriptions(input: {
+  mounts: readonly AgentMount[];
   githubRepos: readonly string[];
   originRepos: readonly string[];
-  stateRoot: string | undefined;
-  mounts: AgentMount[];
-  auth: CursorEventsAuth | undefined;
-  logger: (line: string) => void;
-  collectGitHubTargets: () => ReturnType<typeof collectGitHubTriggerTargets>;
-  collectOriginTargets: () => ReturnType<typeof collectOriginTriggerTargets>;
-  cursorAccountOnly: boolean;
-}): CursorEventRelay | undefined {
-  const { config, stateRoot, mounts, auth, logger } = input;
-  if (config === undefined || auth === undefined) {
-    return undefined;
-  }
-  const githubTargets = findGitHubChannelTargets(mounts);
-  const originTargets = findOriginChannelTargets(mounts);
+}): CursorScmSubscription[] {
+  const githubTargets = findGitHubChannelTargets(input.mounts);
+  const originTargets = findOriginChannelTargets(input.mounts);
   const githubEvents = [
     ...new Set(githubTargets.flatMap((target) => target.events)),
   ];
@@ -1928,8 +1993,88 @@ function startCursorEventRelay(input: {
       });
     }
   }
+  return subscriptions;
+}
+
+/**
+ * Local CP + `--cursor-events` + both architectures would start two
+ * consumers (different offset dirs). Refuse that at serve start.
+ * `--no-control-plane` is one July consumer — hosted CP owns v2.
+ */
+function assertSingleCursorEventsLane(input: {
+  noControlPlane: boolean;
+  config: ServeOptions["cursorEvents"];
+  auth: CursorEventsAuth | undefined;
+  v1Mounts: readonly AgentMount[];
+  v2Mounts: readonly AgentMount[];
+  githubRepos: readonly string[];
+  originRepos: readonly string[];
+}): void {
+  if (
+    input.noControlPlane ||
+    input.config === undefined ||
+    input.auth === undefined
+  ) {
+    return;
+  }
+  const shared = {
+    githubRepos: input.githubRepos,
+    originRepos: input.originRepos,
+  };
+  if (
+    collectCursorEventSubscriptions({ mounts: input.v1Mounts, ...shared })
+      .length === 0 ||
+    collectCursorEventSubscriptions({ mounts: input.v2Mounts, ...shared })
+      .length === 0
+  ) {
+    return;
+  }
+  throw new Error(
+    "[agent-sdk] cursor-events: refusing to serve v1 and v2 github/origin agents in one process — they would open two /v0/scm-events consumers. Serve one architecture per process."
+  );
+}
+
+function startCursorEventRelay(input: {
+  config: ServeOptions["cursorEvents"];
+  githubRepos: readonly string[];
+  originRepos: readonly string[];
+  stateRoot: string | undefined;
+  mounts: AgentMount[];
+  auth: CursorEventsAuth | undefined;
+  logger: (line: string) => void;
+  collectGitHubTargets: () => ReturnType<typeof collectGitHubTriggerTargets>;
+  collectOriginTargets: () => ReturnType<typeof collectOriginTriggerTargets>;
+  routeContinuation?: RouteLocalIngressContinuation;
+  cursorAccountOnly: boolean;
+  /** Engine = v1 poll. Control-plane = v2 poll (started by local CP). */
+  lane: "engine" | "control-plane";
+  /** When the engine lane has no v1 targets, mention skipped v2 mounts. */
+  skippedV2?: boolean;
+  /** When false, return an unstarted relay (local CP calls start). */
+  start?: boolean;
+  /** Offset dir under stateRoot. Defaults to `cursor-events`. */
+  stateDirName?: string;
+}): CursorEventRelay | undefined {
+  const { config, stateRoot, mounts, auth, logger } = input;
+  if (config === undefined || auth === undefined) {
+    return undefined;
+  }
+  const subscriptions = collectCursorEventSubscriptions({
+    mounts,
+    githubRepos: input.githubRepos,
+    originRepos: input.originRepos,
+  });
   if (subscriptions.length === 0) {
-    if (githubRepos.length === 0 && originRepos.length === 0) {
+    if (input.lane === "engine" && input.skippedV2 === true) {
+      logger(
+        "[agent-sdk] cursor-events: no v1 github/origin targets; v2 ingest is control-plane only"
+      );
+    } else if (input.lane === "control-plane") {
+      return undefined;
+    } else if (
+      input.githubRepos.every((repo) => repo.trim() === "") &&
+      input.originRepos.every((repo) => repo.trim() === "")
+    ) {
       logger(
         "[agent-sdk] cursor-events: no repos configured (pass --repo owner/name); relay disabled"
       );
@@ -1947,7 +2092,7 @@ function startCursorEventRelay(input: {
     baseUrl: auth.baseUrl,
     apiKey: auth.apiKey,
     subscriptions,
-    stateDir: join(baseStateRoot, "cursor-events"),
+    stateDir: join(baseStateRoot, input.stateDirName ?? "cursor-events"),
     logger,
     dispatch: async (event) => {
       if (event.provider === "origin") {
@@ -1970,6 +2115,9 @@ function startCursorEventRelay(input: {
           type: "origin",
           bodyText: JSON.stringify(scmMetadataToOriginPayload(event)),
           targets,
+          ...(input.routeContinuation === undefined
+            ? {}
+            : { routeContinuation: input.routeContinuation }),
         });
         logCursorScmDispatch(logger, event, result);
         return;
@@ -1996,10 +2144,16 @@ function startCursorEventRelay(input: {
         eventName: event.eventName,
         deliveryId: event.deliveryId,
         targets,
+        ...(input.routeContinuation === undefined
+          ? {}
+          : { routeContinuation: input.routeContinuation }),
       });
       logCursorScmDispatch(logger, event, result);
     },
   });
+  if (input.start === false) {
+    return relay;
+  }
   relay.start();
   logger(
     `[agent-sdk] cursor-events: relaying ${subscriptions.length} subscription(s) from ${auth.baseUrl}`

package/src/types.ts

@@ -1689,8 +1689,8 @@ export interface SendMessageOptions {
    */
   continuationToken?: string;
   /**
-   * v2 mailbox stamp from the control plane (or the pack's builtin extract
-   * on local serve). Ignored on v1.
+   * v2 mailbox stamp from the control plane (hosted verified ingress or
+   * the local CP). Channel adapters do not extract. Ignored on v1.
    */
   mailboxContinuation?: MailboxContinuation;
   /**