@cursor/july 0.1.74 → 0.1.75

package/src/internal/cursor-deployment-relay.ts

@@ -0,0 +1,274 @@
+/**
+ * Pull relay for `/v0/deployment-events`.
+ *
+ * A {@link RelayAdapter} over {@link CursorRelayCore} — the same engine the
+ * GitHub SCM and Slack relays use, so registration heartbeats, durable
+ * offsets, backoff, and bounded dispatch retry are inherited rather than
+ * reimplemented. Only the subscribe/poll paths, the registration body, and
+ * the per-event filter differ.
+ */
+
+import type {
+  DeploymentEvent,
+  DeploymentEventType,
+  DeploymentSubscription,
+} from "../channels/deployments/types.js";
+import { CursorRelayCore, type RelayAdapter } from "./cursor-relay-core.js";
+
+const DEFAULT_EVENTS: readonly DeploymentEventType[] = ["deployment.succeeded"];
+
+/** One page entry: the event fields plus its stream offset, as the sibling
+ * providers spell it. */
+export type DeploymentRelayEvent = DeploymentEvent & { offset: string };
+
+export interface ResolvedSubscription {
+  repo: string;
+  environments: string[];
+  events: Set<DeploymentEventType>;
+}
+
+interface SubscriptionStatus {
+  repo: string;
+  isSubscribed: boolean;
+  detail?: string;
+}
+
+export interface DeploymentEventRelayOptions {
+  baseUrl: string;
+  apiKey: string;
+  stateDir: string;
+  subscriptions: readonly ResolvedSubscription[];
+  dispatch: (event: DeploymentEvent) => Promise<void>;
+  logger: (line: string) => void;
+  fetchImpl?: typeof fetch;
+  pollWaitMs?: number;
+}
+
+/** Normalize the channel's `repos` option into concrete subscriptions. */
+export function resolveDeploymentSubscriptions(options: {
+  repos: readonly (string | DeploymentSubscription)[];
+  environments?: readonly string[];
+  events?: readonly DeploymentEventType[];
+}): ResolvedSubscription[] {
+  const byRepo = new Map<string, ResolvedSubscription>();
+  for (const entry of options.repos) {
+    const subscription: DeploymentSubscription =
+      typeof entry === "string" ? { repo: entry } : entry;
+    // Case-folded only: `Deployment.repository` has no documented format, and
+    // the server keys subscriptions the same way.
+    const repo = subscription.repo.trim().toLowerCase();
+    if (repo === "") {
+      throw new Error(
+        `deploymentsChannel: invalid repo "${subscription.repo}".`
+      );
+    }
+    const environments = [
+      ...new Set(
+        (subscription.environments ?? options.environments ?? [])
+          .map((value) => value.trim())
+          .filter(Boolean)
+      ),
+    ];
+    const events = new Set(
+      subscription.events ?? options.events ?? DEFAULT_EVENTS
+    );
+    if (events.size === 0) {
+      throw new Error(
+        `deploymentsChannel: repo "${repo}" subscribes to no events.`
+      );
+    }
+    // Later entries for the same repo widen the earlier one rather than
+    // silently replacing it.
+    const existing = byRepo.get(repo);
+    if (existing === undefined) {
+      byRepo.set(repo, { repo, environments, events });
+      continue;
+    }
+    for (const event of events) existing.events.add(event);
+    existing.environments =
+      existing.environments.length === 0 || environments.length === 0
+        ? []
+        : [...new Set([...existing.environments, ...environments])];
+  }
+  // Empty is legal here and means "this channel wants nothing", which is how
+  // an env-configured channel stays inert without a repo list. The wire-level
+  // empty list means deregister, so the host simply never registers it.
+  return [...byRepo.values()];
+}
+
+/** Whether one confirmed subscription wants this event. */
+export function deploymentEventMatches(
+  subscription: ResolvedSubscription,
+  envelope: DeploymentEvent
+): boolean {
+  if (!subscription.events.has(envelope.eventType)) {
+    return false;
+  }
+  return (
+    subscription.environments.length === 0 ||
+    subscription.environments.includes(envelope.environment)
+  );
+}
+
+/** One channel the host can deliver a deployment event to. */
+export interface DeploymentDispatchTarget {
+  /** Display name for logs, e.g. `executor/deployments`. */
+  name: string;
+  subscriptions: readonly ResolvedSubscription[];
+  deliver: (event: DeploymentEvent) => Promise<unknown>;
+}
+
+/**
+ * Deliver one event to every channel subscribed to it.
+ *
+ * Each channel is delivered independently: one channel's handler throwing
+ * must not skip the channels after it, because the relay core retries the
+ * whole dispatch and the channels that already ran would see the event twice.
+ * Throws only when every subscribed channel failed, so a retry cannot
+ * re-deliver to a channel that succeeded.
+ */
+export async function fanOutDeploymentEvent(input: {
+  targets: readonly DeploymentDispatchTarget[];
+  event: DeploymentEvent;
+  logger: (line: string) => void;
+}): Promise<void> {
+  const { event, logger } = input;
+  const matched = input.targets.filter((target) =>
+    target.subscriptions.some(
+      (subscription) =>
+        subscription.repo === event.repo &&
+        deploymentEventMatches(subscription, event)
+    )
+  );
+  const failures: string[] = [];
+  for (const target of matched) {
+    try {
+      await target.deliver(event);
+    } catch (error) {
+      failures.push(target.name);
+      logger(
+        `[agent-sdk] deployment-events: ${target.name} failed on ${event.eventId}: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+  }
+  logger(
+    `[agent-sdk] deployment-events: ${event.eventType} ${event.repo}@${event.sha} (${event.environment}) → ${matched.length - failures.length}/${matched.length} channel(s)`
+  );
+  if (failures.length > 0 && failures.length === matched.length) {
+    throw new Error(
+      `deployment-events: every subscribed channel failed on ${event.eventId} (${failures.join(", ")})`
+    );
+  }
+}
+
+export class DeploymentEventRelay {
+  private readonly core: CursorRelayCore<DeploymentRelayEvent>;
+  private subscribed = new Map<string, ResolvedSubscription>();
+  private readonly loggedSkippedRepos = new Set<string>();
+
+  constructor(private readonly options: DeploymentEventRelayOptions) {
+    const adapter: RelayAdapter<DeploymentRelayEvent> = {
+      logPrefix: "deployment-events",
+      subscribePath: "/v0/deployment-events/subscriptions",
+      pollPath: "/v0/deployment-events",
+      buildRegistrationBody: (consumerId) => ({
+        consumerId,
+        subscriptions: options.subscriptions.map((subscription) => ({
+          repo: subscription.repo,
+          environments: subscription.environments,
+          events: [...subscription.events],
+        })),
+      }),
+      // Empty subscriptions drop this consumer's registration on clean stop
+      // instead of leaving it to lapse by TTL.
+      buildDeregistrationBody: (consumerId) => ({
+        consumerId,
+        subscriptions: [],
+      }),
+      applyRegistrationResponse: (json) => {
+        const result = json as { repos?: SubscriptionStatus[] };
+        this.subscribed = new Map();
+        this.loggedSkippedRepos.clear();
+        const lines: string[] = [];
+        const confirmed: string[] = [];
+        for (const status of result.repos ?? []) {
+          const wanted = options.subscriptions.find(
+            (subscription) => subscription.repo === status.repo
+          );
+          if (!status.isSubscribed || wanted === undefined) {
+            lines.push(
+              `not subscribed to ${status.repo}: ${status.detail ?? "unknown reason"}`
+            );
+            continue;
+          }
+          this.subscribed.set(status.repo, wanted);
+          confirmed.push(status.repo);
+        }
+        if (confirmed.length > 0) {
+          const kinds = [
+            ...new Set(options.subscriptions.flatMap((s) => [...s.events])),
+          ];
+          lines.push(
+            `subscribed to ${confirmed.join(", ")} for events: ${kinds.join(", ")}`
+          );
+        }
+        return lines;
+      },
+      shouldDispatch: (event) => this.shouldDispatch(event),
+      dispatch: ({ offset: _offset, ...envelope }) =>
+        options.dispatch(envelope),
+    };
+    this.core = new CursorRelayCore<DeploymentRelayEvent>({
+      baseUrl: options.baseUrl,
+      apiKey: options.apiKey,
+      stateDir: options.stateDir,
+      adapter,
+      logger: options.logger,
+      ...(options.fetchImpl === undefined
+        ? {}
+        : { fetchImpl: options.fetchImpl }),
+      ...(options.pollWaitMs === undefined
+        ? {}
+        : { pollWaitMs: options.pollWaitMs }),
+    });
+  }
+
+  /**
+   * Whether an event from this principal's stream belongs to THIS relay.
+   * The stream is per-principal, and one API key can back several relays
+   * (other hosts, or an agent running its own alongside the host's), so each
+   * one re-checks the events against the subscriptions the server confirmed
+   * for it.
+   */
+  private shouldDispatch(event: DeploymentRelayEvent): boolean {
+    const envelope = event;
+    if (
+      envelope === null ||
+      typeof envelope !== "object" ||
+      typeof envelope.repo !== "string"
+    ) {
+      return false;
+    }
+    const subscription = this.subscribed.get(envelope.repo);
+    if (subscription === undefined) {
+      if (!this.loggedSkippedRepos.has(envelope.repo)) {
+        this.loggedSkippedRepos.add(envelope.repo);
+        this.options.logger(
+          `[agent-sdk] deployment-events: skipping events for ${envelope.repo}: not in this host's subscription (another consumer of this API key likely subscribed it)`
+        );
+      }
+      return false;
+    }
+    return deploymentEventMatches(subscription, envelope);
+  }
+
+  start(): void {
+    this.core.start();
+  }
+
+  async stop(): Promise<void> {
+    await this.core.stop();
+  }
+}

package/src/internal/distribution.ts

@@ -97,6 +97,7 @@ export const AUTHORING_ENTRY_FILES: ReadonlyArray<
   ["channels/slack", "channels/slack/index.js"],
   ["channels/github", "channels/github/index.js"],
   ["channels/origin", "channels/origin/index.js"],
+  ["channels/deployments", "channels/deployments/index.js"],
   ["skills", "skills.js"],
   ["schedules", "schedules.js"],
   ["reminders", "reminders.js"],

package/src/internal/server.ts

@@ -14,6 +14,11 @@ import {
 } from "node:http";
 import type { AddressInfo } from "node:net";
 import { join } from "node:path";
+import {
+  dispatchDeploymentEvent,
+  getDeploymentsChannelOptions,
+} from "../channels/deployments/deployments-channel.js";
+import type { DeploymentsChannelOptions } from "../channels/deployments/types.js";
 import {
   type CursorGithubRepoScope,
   createCursorAccountGithubTokenResolver,
@@ -62,6 +67,12 @@ import {
   SIGN_IN_HINT,
 } from "./cursor/credentials.js";
 import { CursorGithubCredentialProvider } from "./cursor/github-credentials.js";
+import {
+  DeploymentEventRelay,
+  fanOutDeploymentEvent,
+  type ResolvedSubscription,
+  resolveDeploymentSubscriptions,
+} from "./cursor-deployment-relay.js";
 import {
   CursorEventRelay,
   type CursorScmSubscription,
@@ -774,6 +785,15 @@ export async function startServer(
       (cursorGithubTargets.length > 0 || cursorOriginTargets.length > 0),
   });
 
+  // Cursor deployment-events relay: automatic when a mounted agent authored
+  // `deploymentsChannel({ ... })`.
+  const cursorDeploymentRelay = startCursorDeploymentRelay({
+    options,
+    runtimes,
+    accountKey,
+    logger,
+  });
+
   const server = createServer((req, res) => {
     void instrumentHttp(otelRuntime, req, res, () =>
       handleRequest(router, req, res, logger)
@@ -793,6 +813,7 @@ export async function startServer(
       logger,
     });
   } catch (error) {
+    await cursorDeploymentRelay?.stop();
     await cursorEventRelay?.stop();
     await cursorSlackRelay?.stop();
     cursorGithubCredentials?.stop();
@@ -953,6 +974,7 @@ export async function startServer(
     },
     close: async () => {
       playgroundDev?.stop();
+      await cursorDeploymentRelay?.stop();
       await cursorEventRelay?.stop();
       await cursorSlackRelay?.stop();
       for (const runtime of runtimes) {
@@ -2170,6 +2192,133 @@ function collectCursorSlackTargets(
  * the pack's normal inbound path. Requires a signed-in host — fail serve
  * fast rather than mounting channels that can never hear or speak.
  */
+interface CursorDeploymentTarget {
+  runtime: MountedRuntime;
+  channelId: string;
+  options: DeploymentsChannelOptions;
+  subscriptions: ResolvedSubscription[];
+}
+
+/** Every mounted `deploymentsChannel`, with its resolved subscriptions. */
+function collectCursorDeploymentTargets(
+  runtimes: MountedRuntime[],
+  skipped: string[]
+): CursorDeploymentTarget[] {
+  const targets: CursorDeploymentTarget[] = [];
+  for (const runtime of runtimes) {
+    for (const channel of runtime.project.channels) {
+      const options = getDeploymentsChannelOptions(channel.definition);
+      if (options === undefined) {
+        continue;
+      }
+      const subscriptions = resolveDeploymentSubscriptions(options);
+      if (subscriptions.length === 0) {
+        // Declared the channel but named no repositories — 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;
+      }
+      targets.push({ runtime, channelId: channel.id, options, subscriptions });
+    }
+  }
+  return targets;
+}
+
+/**
+ * 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
+ * each event is routed to the channels that asked for it — the same ownership
+ * `startCursorSlackRelay` and `startCursorEventRelay` have.
+ */
+function startCursorDeploymentRelay(input: {
+  options: ServeOptions;
+  runtimes: MountedRuntime[];
+  accountKey: ResolvedApiKey | undefined;
+  logger: (line: string) => void;
+}): DeploymentEventRelay | undefined {
+  const { options, runtimes, accountKey, logger } = input;
+  const skipped: string[] = [];
+  const targets = collectCursorDeploymentTargets(runtimes, skipped);
+  if (skipped.length > 0) {
+    logger(
+      `[agent-sdk] deployment-events: no repositories declared on ${skipped.join(", ")}; those channels receive nothing`
+    );
+  }
+  if (targets.length === 0) {
+    return undefined;
+  }
+  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}`
+    );
+  }
+  // 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>();
+  for (const target of targets) {
+    for (const subscription of target.subscriptions) {
+      const existing = byRepo.get(subscription.repo);
+      if (existing === undefined) {
+        byRepo.set(subscription.repo, {
+          repo: subscription.repo,
+          environments: [...subscription.environments],
+          events: new Set(subscription.events),
+        });
+        continue;
+      }
+      for (const event of subscription.events) existing.events.add(event);
+      // An empty environment list means "every environment", so it absorbs.
+      existing.environments =
+        existing.environments.length === 0 ||
+        subscription.environments.length === 0
+          ? []
+          : [
+              ...new Set([
+                ...existing.environments,
+                ...subscription.environments,
+              ]),
+            ];
+    }
+  }
+  // Same host split as scm-events and slack-events: `/v0/deployment-events/*`
+  // is on api.cursor.com, not api2.
+  const baseStateRoot =
+    options.stateRoot ??
+    join(targets[0].runtime.project.rootDir, ".agent-serve");
+  const relay = new DeploymentEventRelay({
+    baseUrl: cursorExternalApiUrl(),
+    apiKey: accountKey.apiKey,
+    stateDir: join(baseStateRoot, "deployment-events"),
+    subscriptions: [...byRepo.values()],
+    logger,
+    dispatch: async (event) =>
+      fanOutDeploymentEvent({
+        event,
+        logger,
+        targets: targets.map((target) => ({
+          name: `${target.runtime.slug || target.runtime.project.name}/${target.channelId}`,
+          subscriptions: target.subscriptions,
+          deliver: (delivered) =>
+            dispatchDeploymentEvent({
+              options: target.options,
+              event: delivered,
+              args: buildChannelHandlerArgs({
+                runtime: target.runtime,
+                channelId: target.channelId,
+              }),
+            }),
+        })),
+      }),
+  });
+  relay.start();
+  logger(
+    `[agent-sdk] deployment-events: relaying ${byRepo.size} repository subscription(s) to ${targets.length} channel(s)`
+  );
+  return relay;
+}
+
 async function startCursorSlackRelay(input: {
   options: ServeOptions;
   runtimes: MountedRuntime[];