@cursor/july 0.1.84 → 0.1.86

package/src/internal/local-control-plane.ts

@@ -2,15 +2,37 @@
  * In-process control plane started with local `serve`. Owns schedule clocks
  * and reminder documents + clocks, then fires into the kit the same way the
  * Cursor backend does over HTTP when `--no-control-plane` is set.
+ *
+ * v2 ingest lives here: `routeContinuation` stamps the mailbox (July twin
+ * of hosted `routeVerifiedIngressContinuation`), and `attachScmEvents`
+ * owns the `/v0/scm-events` long poll. v1 keeps engine-side scm-events.
+ * Hosted `--no-control-plane` v2 skips that poll — the hosted CP delivers.
  */
 
 import { dirname, join } from "node:path";
 import { type CronExpression, parseCron } from "./cron.js";
+import {
+  type LocalIngressContinuation,
+  type RouteLocalIngressContinuationInput,
+  routeLocalIngressContinuation,
+} from "./local-ingress.js";
 import type { PlatformTimers } from "./platform-timers.js";
 import { MAX_TIMER_MS } from "./reminder-schedule.js";
 import { type ReminderRecord, ReminderStore } from "./reminder-store.js";
 
 export interface LocalControlPlane extends PlatformTimers {
+  /**
+   * Stamp a v2 mailbox from the channel selector + live payload. Same
+   * contract as hosted verified ingress. `/v1` is a no-op.
+   */
+  routeContinuation(
+    input: RouteLocalIngressContinuationInput
+  ): LocalIngressContinuation;
+  /**
+   * Take ownership of the v2 `/v0/scm-events` long poll. Starts the relay.
+   * v1 scm-events stay on the engine serve path.
+   */
+  attachScmEvents(relay: { start(): void; stop(): Promise<void> }): void;
   /** Arm persisted reminder clocks after the kit fire callback is live. */
   startClocks(): void;
   stop(): void;
@@ -40,6 +62,7 @@ export async function createLocalControlPlane(opts: {
   const reminders = new Map<string, ReminderRecord>();
   let scheduleTimer: NodeJS.Timeout | undefined;
   let lastFiredMinute = -1;
+  let scmRelay: { start(): void; stop(): Promise<void> } | undefined;
 
   if (store !== undefined) {
     for (const record of await store.list()) {
@@ -138,6 +161,12 @@ export async function createLocalControlPlane(opts: {
   }
 
   return {
+    routeContinuation: routeLocalIngressContinuation,
+    attachScmEvents(relay) {
+      scmRelay = relay;
+      relay.start();
+      logger("[agent-sdk] cursor-events: control-plane ingest started");
+    },
     async upsertSchedule(input) {
       schedules.set(input.name, parseCron(input.cron));
       armScheduleTicker();
@@ -183,6 +212,10 @@ export async function createLocalControlPlane(opts: {
       for (const id of [...reminderTimers.keys()]) {
         clearReminderTimer(id);
       }
+      if (scmRelay !== undefined) {
+        void scmRelay.stop();
+        scmRelay = undefined;
+      }
     },
   };
 }

package/src/internal/local-ingress.ts

@@ -0,0 +1,90 @@
+/**
+ * Local control-plane ingest for v2 continuation.
+ *
+ * Twin of backend `routeVerifiedIngressContinuation`. Hosted Cursor runs
+ * that copy after the webhook is verified. Self-hosted / `july serve`
+ * runs this copy on the in-process local CP before the channel adapter
+ * `send()`s. Channel adapters do not extract.
+ */
+
+import type { ChannelHandlerArgs } from "../types.js";
+import {
+  bindMailboxContinuationSend,
+  type ContinuationIdentity,
+  continuationSource,
+  type MailboxContinuation,
+  normalizeIdentity,
+  stampMailboxContinuation,
+} from "./continuation-identity.js";
+
+export type LocalIngressContinuation = {
+  explicitContinuationKey?: string;
+  mailboxContinuation?: MailboxContinuation;
+};
+
+export type RouteLocalIngressContinuation = (
+  input: RouteLocalIngressContinuationInput
+) => LocalIngressContinuation;
+
+export type RouteLocalIngressContinuationInput = {
+  identity?: ContinuationIdentity;
+  kind?: string;
+  eventType: string;
+  payload: unknown;
+  deterministicContinuationKey?: string;
+};
+
+/**
+ * Selector + live payload → mailbox stamp. `/v1` and omitted identity
+ * keep the caller-supplied deterministic key and do not stamp a mailbox.
+ */
+export function routeLocalIngressContinuation(
+  input: RouteLocalIngressContinuationInput
+): LocalIngressContinuation {
+  if (input.identity === undefined) {
+    return {
+      ...(input.deterministicContinuationKey === undefined
+        ? {}
+        : { explicitContinuationKey: input.deterministicContinuationKey }),
+    };
+  }
+  const identity = normalizeIdentity(input.identity, input.kind);
+  if (continuationSource(identity, input.kind) !== "control-plane") {
+    return {
+      ...(input.deterministicContinuationKey === undefined
+        ? {}
+        : { explicitContinuationKey: input.deterministicContinuationKey }),
+    };
+  }
+  const mailboxContinuation = stampMailboxContinuation(
+    identity,
+    input.eventType,
+    input.payload,
+    input.kind
+  );
+  if (mailboxContinuation.key.startsWith("cont:")) {
+    return {
+      explicitContinuationKey: mailboxContinuation.key,
+      mailboxContinuation,
+    };
+  }
+  return { mailboxContinuation };
+}
+
+/**
+ * Bind a CP mailbox stamp onto `args.send` so the channel adapter only
+ * calls `send()` — it does not extract. No-op for `/v1`.
+ */
+export function bindLocalIngressSend(
+  args: ChannelHandlerArgs,
+  input: RouteLocalIngressContinuationInput & {
+    routeContinuation?: RouteLocalIngressContinuation;
+  }
+): ChannelHandlerArgs {
+  const route = input.routeContinuation ?? routeLocalIngressContinuation;
+  const routed = route(input);
+  return {
+    ...args,
+    send: bindMailboxContinuationSend(args.send, routed.mailboxContinuation),
+  };
+}

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}`
@@ -2291,7 +2445,7 @@ function collectCursorDeploymentTargets(
       }
       const subscriptions = resolveDeploymentSubscriptions(options);
       if (subscriptions.length === 0) {
-        // Declared the channel but named no repositories — usually an unset
+        // Declared the channel but named no deploy sources — usually an unset
         // env var. Say so rather than starting a relay that receives nothing.
         skipped.push(`${runtime.slug || runtime.project.name}/${channel.id}`);
         continue;
@@ -2305,7 +2459,7 @@ function collectCursorDeploymentTargets(
 /**
  * Cursor deployment-events relay: automatic when a mounted agent authored
  * `deploymentsChannel({ ... })`. One relay per process reads
- * `/v0/deployment-events` for the union of every channel's repositories, and
+ * `/v0/deployment-events` for the union of every channel's deploy sources, and
  * each event is routed to the channels that asked for it — the same ownership
  * `startCursorSlackRelay` and `startCursorEventRelay` have.
  */
@@ -2320,7 +2474,7 @@ function startCursorDeploymentRelay(input: {
   const targets = collectCursorDeploymentTargets(runtimes, skipped);
   if (skipped.length > 0) {
     logger(
-      `[agent-sdk] deployment-events: no repositories declared on ${skipped.join(", ")}; those channels receive nothing`
+      `[agent-sdk] deployment-events: no deploy sources declared on ${skipped.join(", ")}; those channels receive nothing`
     );
   }
   if (targets.length === 0) {
@@ -2328,19 +2482,19 @@ function startCursorDeploymentRelay(input: {
   }
   if (accountKey === undefined) {
     throw new Error(
-      `This project has channels subscribed to deployment events (deploymentsChannel({ repos })) but the host is not signed in to Cursor. ${SIGN_IN_HINT}`
+      `This project has channels subscribed to deployment events (deploymentsChannel({ deploySourceUris })) but the host is not signed in to Cursor. ${SIGN_IN_HINT}`
     );
   }
-  // Union across channels: one registration per repo for the whole process,
-  // however many channels named it. Per-channel environment and event-type
-  // filtering happens at dispatch.
-  const byRepo = new Map<string, ResolvedSubscription>();
+  // Union across channels: one registration per deploy source for the whole
+  // process, however many channels named it. Per-channel environment and
+  // event-type filtering happens at dispatch.
+  const bySource = new Map<string, ResolvedSubscription>();
   for (const target of targets) {
     for (const subscription of target.subscriptions) {
-      const existing = byRepo.get(subscription.repo);
+      const existing = bySource.get(subscription.deploySourceUri);
       if (existing === undefined) {
-        byRepo.set(subscription.repo, {
-          repo: subscription.repo,
+        bySource.set(subscription.deploySourceUri, {
+          deploySourceUri: subscription.deploySourceUri,
           environments: [...subscription.environments],
           events: new Set(subscription.events),
         });
@@ -2369,7 +2523,7 @@ function startCursorDeploymentRelay(input: {
     baseUrl: cursorExternalApiUrl(),
     apiKey: accountKey.apiKey,
     stateDir: join(baseStateRoot, "deployment-events"),
-    subscriptions: [...byRepo.values()],
+    subscriptions: [...bySource.values()],
     logger,
     dispatch: async (event) =>
       fanOutDeploymentEvent({
@@ -2392,7 +2546,7 @@ function startCursorDeploymentRelay(input: {
   });
   relay.start();
   logger(
-    `[agent-sdk] deployment-events: relaying ${byRepo.size} repository subscription(s) to ${targets.length} channel(s)`
+    `[agent-sdk] deployment-events: relaying ${bySource.size} deploy-source subscription(s) to ${targets.length} channel(s)`
   );
   return relay;
 }

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;
   /**