@cursor/july 0.1.62 → 0.1.73

package/src/internal/deployment-scm-event-stream.ts

@@ -0,0 +1,593 @@
+/**
+ * Deployment-scoped SCM event intake for hosted multi-tenant agents.
+ *
+ * Instead of receiving HMAC-signed webhook forwards from the backend (which
+ * required a shared `GITHUB_WEBHOOK_SECRET` / forward-secret pair), the
+ * engine pulls its deliveries from the control plane's deployment-scoped
+ * event stream:
+ *
+ *   GET /internal/agent-serve/automation-agent-sdk/events
+ *
+ * authenticated with the engine pod's `CURSOR_API_KEY` — the same
+ * credential (and server-side deployment allowlist) that authorizes the
+ * consuming agent's customer list read. The backend writes each envelope's
+ * `installationId` itself from the verified GitHub delivery, so agent-side
+ * tenant binding does not depend on an HMAC-covered payload.
+ *
+ * Each envelope is stubbed into a GitHub-shaped `pull_request` webhook body
+ * and POSTed to this process's own github channel route over loopback
+ * (admitted by the channel's no-secret `localDevStrict` policy), so the
+ * consuming agent's whole pipeline — Zod parse, cursorAccount credential
+ * lease, customer routing, tools — runs unchanged. Loopback (rather than
+ * the in-process `handleAgentServeTrigger` fan-out the `--cursor-events`
+ * relay uses) is deliberate: this stream is started from a channel's
+ * `onStart`, which cannot reach the serve-level mount/handler wiring.
+ *
+ * Offsets are client-owned (`<ms>-<seq>` Redis stream ids) and persisted
+ * under the state dir so a restart resumes where it left off instead of
+ * dropping deliveries (the old push path was fire-and-forget).
+ *
+ * INTERNAL: first-party host plumbing shared by agents in `factory/*`.
+ * Consumed via relative source imports, following
+ * `tenant-mcp/run-mcp-registry.ts`. Policy (which deliveries to act on,
+ * tenant routing) stays in the consuming agent; this module is transport
+ * only.
+ */
+
+// Node builtins only: hosted engines install the consuming agent's directory
+// alone and load this file as raw TypeScript source, so third-party imports
+// (even zod) do not resolve from here. See the tenant-mcp internals for the
+// same constraint.
+import { createHmac } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const DEFAULT_BASE_URL = "https://api.cursor.com";
+const EVENTS_PATH = "/internal/agent-serve/automation-agent-sdk/events";
+const POLL_WAIT_MS = 20_000;
+const POLL_LIMIT = 100;
+const MIN_BACKOFF_MS = 1_000;
+const MAX_BACKOFF_MS = 30_000;
+// Bounded self-dispatch retry before the offset advances past a delivery
+// (mirrors CursorRelayCore): transient loopback failures (connection
+// reset, channel briefly unavailable at startup) get a few tries; a
+// poison delivery still costs only DISPATCH_ATTEMPTS and is then skipped.
+const DISPATCH_ATTEMPTS = 3;
+const DISPATCH_RETRY_DELAYS_MS = [250, 1_000];
+/** Auth/gate failures (401/403/404) are config problems; poll slowly. */
+const AUTH_FAILURE_BACKOFF_MS = 60_000;
+
+const OFFSET_SNAPSHOT_VERSION = 1 as const;
+
+export interface AgentSdkScmPullRequestMeta {
+  number: number;
+  url: string;
+  title: string;
+  body?: string | null | undefined;
+  draft?: boolean | undefined;
+  merged?: boolean | undefined;
+  authorLogin?: string | undefined;
+  headRef: string;
+  headSha: string;
+  baseRef: string;
+  baseSha?: string | undefined;
+}
+
+/** One entry from the deployment-scoped control-plane event stream. */
+export interface AgentSdkScmEventEnvelope {
+  provider: "github";
+  eventName: string;
+  deliveryId: string;
+  repo: string;
+  receivedAtMs: number;
+  action: string;
+  /** Tenant-binding material, written by the control plane. */
+  installationId: number;
+  pullRequest: AgentSdkScmPullRequestMeta;
+  occurredAtMs?: number | undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function optionalString(value: unknown): value is string | undefined {
+  return value === undefined || typeof value === "string";
+}
+
+function optionalBoolean(value: unknown): value is boolean | undefined {
+  return value === undefined || typeof value === "boolean";
+}
+
+function parsePullRequestMeta(
+  value: unknown
+): AgentSdkScmPullRequestMeta | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  const number = value.number;
+  const url = nonEmptyString(value.url);
+  const headRef = nonEmptyString(value.headRef);
+  const headSha = nonEmptyString(value.headSha);
+  const baseRef = nonEmptyString(value.baseRef);
+  if (
+    typeof number !== "number" ||
+    !Number.isInteger(number) ||
+    number <= 0 ||
+    url === undefined ||
+    typeof value.title !== "string" ||
+    !(
+      value.body === undefined ||
+      value.body === null ||
+      typeof value.body === "string"
+    ) ||
+    !optionalBoolean(value.draft) ||
+    !optionalBoolean(value.merged) ||
+    !optionalString(value.authorLogin) ||
+    headRef === undefined ||
+    headSha === undefined ||
+    baseRef === undefined ||
+    !optionalString(value.baseSha)
+  ) {
+    return undefined;
+  }
+  return {
+    number,
+    url,
+    title: value.title,
+    body: value.body,
+    draft: value.draft,
+    merged: value.merged,
+    authorLogin: value.authorLogin,
+    headRef,
+    headSha,
+    baseRef,
+    baseSha: value.baseSha,
+  };
+}
+
+/** Unknown envelope shapes return undefined (skipped, forward compat). */
+export function parseAgentSdkScmEventEnvelope(
+  value: unknown
+): AgentSdkScmEventEnvelope | undefined {
+  if (!isRecord(value) || value.provider !== "github") {
+    return undefined;
+  }
+  const eventName = nonEmptyString(value.eventName);
+  const deliveryId = nonEmptyString(value.deliveryId);
+  const repo = nonEmptyString(value.repo);
+  const action = nonEmptyString(value.action);
+  const installationId = value.installationId;
+  const pullRequest = parsePullRequestMeta(value.pullRequest);
+  if (
+    eventName === undefined ||
+    deliveryId === undefined ||
+    repo === undefined ||
+    typeof value.receivedAtMs !== "number" ||
+    action === undefined ||
+    typeof installationId !== "number" ||
+    !Number.isInteger(installationId) ||
+    installationId <= 0 ||
+    pullRequest === undefined ||
+    !(
+      value.occurredAtMs === undefined || typeof value.occurredAtMs === "number"
+    )
+  ) {
+    return undefined;
+  }
+  return {
+    provider: "github",
+    eventName,
+    deliveryId,
+    repo,
+    receivedAtMs: value.receivedAtMs,
+    action,
+    installationId,
+    pullRequest,
+    occurredAtMs: value.occurredAtMs,
+  };
+}
+
+type PollResponse = {
+  /** Unknown envelope shapes are skipped, not fatal (forward compat). */
+  events: Array<{ offset: string; envelope: unknown }>;
+  nextOffset: string;
+  gapDetected: boolean;
+};
+
+function parsePollResponse(value: unknown): PollResponse {
+  if (!isRecord(value) || !Array.isArray(value.events)) {
+    throw new Error("malformed poll response");
+  }
+  const events: PollResponse["events"] = [];
+  for (const entry of value.events) {
+    if (!isRecord(entry)) {
+      throw new Error("malformed poll response event");
+    }
+    const offset = nonEmptyString(entry.offset);
+    if (offset === undefined) {
+      throw new Error("malformed poll response event offset");
+    }
+    events.push({ offset, envelope: entry.envelope });
+  }
+  if (
+    typeof value.nextOffset !== "string" ||
+    typeof value.gapDetected !== "boolean"
+  ) {
+    throw new Error("malformed poll response fields");
+  }
+  return {
+    events,
+    nextOffset: value.nextOffset,
+    gapDetected: value.gapDetected,
+  };
+}
+
+/**
+ * Marker key on self-dispatched webhook bodies so the consuming channel can
+ * tell stream deliveries apart from other senders (e.g. the serve host's
+ * cursorAccount SCM relay). Multi-tenant channels treat this stream as the
+ * single source and ignore unmarked deliveries — without that gate, one PR
+ * push reached the channel twice (relay + stream) and double-ran reviews.
+ */
+const EVENT_STREAM_PAYLOAD_MARKER = "cursorDeploymentEventStream";
+
+/** Whether a webhook body was self-dispatched by this event stream. */
+export function isDeploymentEventStreamPayload(payload: unknown): boolean {
+  return isRecord(payload) && payload[EVENT_STREAM_PAYLOAD_MARKER] === true;
+}
+
+/**
+ * Stub a GitHub-shaped `pull_request` webhook body from an envelope —
+ * enough for agent-serve's pull_request Zod schema, plus `installation.id`
+ * so the channel's `ctx.installationId` tenant binding keeps working, plus
+ * the {@link isDeploymentEventStreamPayload} source marker.
+ * Pure — exported for tests.
+ */
+export function envelopeToGitHubPayload(
+  envelope: AgentSdkScmEventEnvelope
+): Record<string, unknown> {
+  const slash = envelope.repo.indexOf("/");
+  const owner = slash === -1 ? "" : envelope.repo.slice(0, slash);
+  const name = slash === -1 ? envelope.repo : envelope.repo.slice(slash + 1);
+  const pr = envelope.pullRequest;
+  return {
+    action: envelope.action,
+    repository: {
+      full_name: envelope.repo,
+      name,
+      html_url: `https://github.com/${envelope.repo}`,
+      owner: { login: owner },
+    },
+    pull_request: {
+      number: pr.number,
+      html_url: pr.url,
+      title: pr.title,
+      body: pr.body,
+      draft: pr.draft,
+      merged: pr.merged,
+      user:
+        pr.authorLogin === undefined ? undefined : { login: pr.authorLogin },
+      head: { ref: pr.headRef, sha: pr.headSha },
+      base: { ref: pr.baseRef, sha: pr.baseSha },
+    },
+    installation: { id: envelope.installationId },
+    [EVENT_STREAM_PAYLOAD_MARKER]: true,
+  };
+}
+
+/** Durable offset snapshot under `<stateDir>/offset.json`. */
+class OffsetStore {
+  constructor(private readonly stateDir: string) {}
+
+  private get filePath(): string {
+    return join(this.stateDir, "offset.json");
+  }
+
+  async load(): Promise<string | undefined> {
+    try {
+      const raw = await readFile(this.filePath, "utf8");
+      const parsed = JSON.parse(raw) as {
+        version?: number;
+        offset?: unknown;
+      };
+      if (
+        parsed.version === OFFSET_SNAPSHOT_VERSION &&
+        typeof parsed.offset === "string" &&
+        parsed.offset !== ""
+      ) {
+        return parsed.offset;
+      }
+      return undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  async save(offset: string): Promise<void> {
+    await mkdir(this.stateDir, { recursive: true });
+    // Write-then-rename so a crash mid-write never corrupts the snapshot.
+    const tmpPath = `${this.filePath}.tmp`;
+    await writeFile(
+      tmpPath,
+      JSON.stringify(
+        {
+          version: OFFSET_SNAPSHOT_VERSION,
+          offset,
+          updatedAt: new Date().toISOString(),
+        },
+        null,
+        2
+      ),
+      "utf8"
+    );
+    await rename(tmpPath, this.filePath);
+  }
+}
+
+export interface AgentSdkEventStreamOptions {
+  logger?: (line: string) => void;
+  env?: NodeJS.ProcessEnv;
+  /** Injected for tests. */
+  fetch?: typeof fetch;
+  /** Injected for tests (default `process.argv`). */
+  argv?: readonly string[];
+  /**
+   * Prefix for the consumer-scoped env overrides
+   * `<prefix>_SELF_WEBHOOK_URL` and `<prefix>_EVENTS_STATE_DIR`
+   * (default `AGENT_SERVE`; e.g. the security reviewer passes
+   * `SECURITY_REVIEWER` to keep its existing deployment env vars working).
+   */
+  envPrefix?: string;
+  /** Log-line prefix (default `agent-sdk/deployment-events`). */
+  logLabel?: string;
+  /**
+   * Offset state directory name under `<cwd>/.agent-serve`
+   * (default `deployment-events`). Consumers with persisted offsets must
+   * keep their historical name or a restart re-anchors at `$`.
+   */
+  stateDirName?: string;
+}
+
+/**
+ * Port the serve process is actually listening on, read from its own argv.
+ *
+ * The channel runs inside the serve process, so `--port <n>` / `--port=<n>`
+ * on the command line is authoritative. Hosted-platform engines start with
+ * `--port 26100` and export no `PORT` env, so guessing a fixed default posts
+ * self-dispatches at a port nothing listens on ("fetch failed" for every
+ * delivery).
+ */
+export function servePortFromArgv(argv: readonly string[]): string | undefined {
+  const flagIndex = argv.lastIndexOf("--port");
+  if (flagIndex !== -1) {
+    const value = argv[flagIndex + 1]?.trim();
+    if (value !== undefined && /^\d+$/.test(value)) {
+      return value;
+    }
+  }
+  for (let i = argv.length - 1; i >= 0; i--) {
+    const arg = argv[i];
+    if (arg !== undefined && arg.startsWith("--port=")) {
+      const value = arg.slice("--port=".length).trim();
+      if (/^\d+$/.test(value)) {
+        return value;
+      }
+    }
+  }
+  return undefined;
+}
+
+export interface AgentSdkEventStream {
+  stop(): Promise<void>;
+}
+
+function delay(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(finish, ms);
+    timer.unref?.();
+    signal.addEventListener("abort", finish, { once: true });
+    function finish(): void {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", finish);
+      resolve();
+    }
+  });
+}
+
+/**
+ * Start the pull loop. Returns undefined (with a log line) when required
+ * config is missing so `serve` still starts — mirroring how other relays
+ * degrade instead of failing the host.
+ */
+export function startAgentSdkEventStream(
+  options: AgentSdkEventStreamOptions = {}
+): AgentSdkEventStream | undefined {
+  const env = options.env ?? process.env;
+  const logLabel = options.logLabel ?? "agent-sdk/deployment-events";
+  const rawLog = options.logger ?? (() => {});
+  const log = (message: string): void => {
+    rawLog(`[${logLabel}] ${message}`);
+  };
+  const doFetch = options.fetch ?? fetch;
+  const envPrefix = options.envPrefix ?? "AGENT_SERVE";
+
+  const apiKey = env.CURSOR_API_KEY?.trim();
+  if (apiKey === undefined || apiKey === "") {
+    log("CURSOR_API_KEY missing; deployment event stream disabled");
+    return undefined;
+  }
+  const baseRaw = (env.CURSOR_API_BASE_URL ?? DEFAULT_BASE_URL).trim();
+  const base = baseRaw.endsWith("/") ? baseRaw.slice(0, -1) : baseRaw;
+  // Loopback self-dispatch into this process's github channel route, single
+  // agent mounting assumed (multi-agent mounts need the slugged path via the
+  // env var override). Port resolution: explicit env override, then `PORT`,
+  // then the serve process's own `--port` argv (hosted-platform engines run
+  // `serve --port 26100` and export no PORT), then the :3000 default of the
+  // corp hosted image.
+  const selfUrl =
+    env[`${envPrefix}_SELF_WEBHOOK_URL`]?.trim() ||
+    `http://127.0.0.1:${
+      env.PORT?.trim() ||
+      servePortFromArgv(options.argv ?? process.argv) ||
+      "3000"
+    }/v1/channels/github`;
+  log(`self-dispatch url: ${selfUrl}`);
+  const stateDir =
+    env[`${envPrefix}_EVENTS_STATE_DIR`]?.trim() ||
+    join(
+      process.cwd(),
+      ".agent-serve",
+      options.stateDirName ?? "deployment-events"
+    );
+  const offsetStore = new OffsetStore(stateDir);
+  const abort = new AbortController();
+
+  // Transition aid: while the deployment still sets GITHUB_WEBHOOK_SECRET,
+  // the channel's auth is HMAC-only (allowAll + signature check), so sign
+  // the self-dispatch with it. Once the secret is removed from the env,
+  // the channel falls back to its loopback policy and the unsigned POST is
+  // admitted — either configuration works, so rollout order doesn't matter.
+  const webhookSecret = env.GITHUB_WEBHOOK_SECRET?.trim();
+
+  async function dispatch(envelope: AgentSdkScmEventEnvelope): Promise<void> {
+    const body = JSON.stringify(envelopeToGitHubPayload(envelope));
+    const headers: Record<string, string> = {
+      "content-type": "application/json",
+      "x-github-event": envelope.eventName,
+      "x-github-delivery": envelope.deliveryId,
+    };
+    if (webhookSecret !== undefined && webhookSecret !== "") {
+      const signature = createHmac("sha256", webhookSecret)
+        .update(body)
+        .digest("hex");
+      headers["x-hub-signature-256"] = `sha256=${signature}`;
+    }
+    const response = await doFetch(selfUrl, {
+      method: "POST",
+      headers,
+      body,
+      signal: AbortSignal.timeout(POLL_WAIT_MS),
+    });
+    void response.body?.cancel().catch(() => {});
+    if (!response.ok) {
+      throw new Error(`self dispatch returned ${response.status}`);
+    }
+  }
+
+  async function run(): Promise<void> {
+    let after = (await offsetStore.load()) ?? "$";
+    let backoffMs = MIN_BACKOFF_MS;
+    log(`pulling ${base}${EVENTS_PATH} (after=${after})`);
+    while (!abort.signal.aborted) {
+      let parsed: PollResponse;
+      try {
+        const query = new URLSearchParams({
+          after,
+          limit: String(POLL_LIMIT),
+          waitMs: String(POLL_WAIT_MS),
+        });
+        const response = await doFetch(`${base}${EVENTS_PATH}?${query}`, {
+          headers: { authorization: `Bearer ${apiKey}` },
+          signal: AbortSignal.any([
+            abort.signal,
+            AbortSignal.timeout(POLL_WAIT_MS + 10_000),
+          ]),
+        });
+        if (!response.ok) {
+          void response.body?.cancel().catch(() => {});
+          const authFailure = [401, 403, 404].includes(response.status);
+          log(`poll failed (${response.status}); backing off`);
+          await delay(
+            authFailure ? AUTH_FAILURE_BACKOFF_MS : backoffMs,
+            abort.signal
+          );
+          backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
+          continue;
+        }
+        parsed = parsePollResponse(await response.json());
+      } catch (error) {
+        if (abort.signal.aborted) return;
+        log(
+          `poll error (${
+            error instanceof Error ? error.message : String(error)
+          }); backing off`
+        );
+        await delay(backoffMs, abort.signal);
+        backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
+        continue;
+      }
+      backoffMs = MIN_BACKOFF_MS;
+      if (parsed.gapDetected) {
+        log(
+          "gap detected: some deliveries were trimmed before this consumer read them"
+        );
+      }
+      for (const entry of parsed.events) {
+        if (abort.signal.aborted) return;
+        const envelope = parseAgentSdkScmEventEnvelope(entry.envelope);
+        if (envelope !== undefined) {
+          for (let attempt = 1; attempt <= DISPATCH_ATTEMPTS; attempt++) {
+            if (abort.signal.aborted) return;
+            try {
+              await dispatch(envelope);
+              log(
+                `dispatched ${envelope.repo}#${envelope.pullRequest.number} (${envelope.action}, delivery=${envelope.deliveryId})`
+              );
+              break;
+            } catch (error) {
+              if (abort.signal.aborted) return;
+              const message =
+                error instanceof Error ? error.message : String(error);
+              if (attempt === DISPATCH_ATTEMPTS) {
+                // Skip, don't wedge: the offset advances so one poison
+                // delivery cannot stall the stream.
+                log(
+                  `dispatch failed for ${envelope.deliveryId} after ${attempt} attempts: ${message}`
+                );
+                break;
+              }
+              log(
+                `dispatch attempt ${attempt} failed for ${envelope.deliveryId}: ${message}; retrying`
+              );
+              await delay(
+                DISPATCH_RETRY_DELAYS_MS[
+                  Math.min(attempt - 1, DISPATCH_RETRY_DELAYS_MS.length - 1)
+                ],
+                abort.signal
+              );
+            }
+          }
+        }
+        after = entry.offset;
+        await offsetStore.save(after).catch(() => {});
+      }
+      if (parsed.events.length === 0 && parsed.nextOffset !== after) {
+        // "$" anchor resolution. An empty stream anchors at "" (read from
+        // the beginning), which is valid in-memory but not worth persisting
+        // (a restart re-anchors at "$" anyway).
+        after = parsed.nextOffset;
+        if (after !== "") {
+          await offsetStore.save(after).catch(() => {});
+        }
+      }
+    }
+  }
+
+  const done = run().catch((error: unknown) => {
+    log(
+      `loop crashed: ${error instanceof Error ? error.message : String(error)}`
+    );
+  });
+
+  return {
+    stop: async () => {
+      abort.abort();
+      await done;
+    },
+  };
+}