@cursor/july 0.1.74 → 0.1.76

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/deployment-scm-event-stream.ts

@@ -34,10 +34,10 @@
  * 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.
+// Hosted engines install the consuming agent's directory alone and load this
+// file as raw TypeScript source. Relative and `node:` imports resolve here;
+// this package's own npm dependencies retry against the running `@cursor/july`
+// install (authored-alias-hooks). Do not add deps that package does not have.
 import { createHmac } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";

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/review-comments.ts

@@ -110,6 +110,43 @@ export type ReviewCommentReaderImplementation = {
   ) => Promise<ExistingReviewComment[]>;
 };
 
+export type ResolveReviewThreadsArgs = {
+  target: ScmReviewTarget;
+  /** REST comment ids whose threads should be resolved. */
+  commentIds: readonly number[];
+  signal?: AbortSignal;
+};
+
+/**
+ * Outcome of resolving review threads for a set of comment ids. Callers
+ * treat this as best-effort actuation: a failed resolve must not fail the
+ * review that already posted.
+ */
+export type ResolveReviewThreadsResult = {
+  requested: number;
+  resolved: number;
+  alreadyResolved: number;
+  notFound: number;
+  failed: number;
+  detail: string;
+};
+
+/**
+ * Write side of thread resolution, the counterpart of
+ * {@link ReviewCommentReaderImplementation}. Bugbot's equivalent is
+ * `IGitProvider.resolveReviewThreadForComment` / `resolveThreads`.
+ *
+ * GitHub only exposes resolve via GraphQL (`resolveReviewThread`). REST
+ * has no equivalent. The mutation runs as whatever identity minted the
+ * bound GitHub client — for `githubChannel({ cursorAccount })` that is
+ * the Cursor installation, the same identity that posted the comments.
+ */
+export type ReviewThreadResolverImplementation = {
+  resolveReviewThreadsForComments: (
+    args: ResolveReviewThreadsArgs
+  ) => Promise<ResolveReviewThreadsResult>;
+};
+
 /** Parse a PR URL into the SCM target to read comments from. */
 export function resolveScmReviewTarget(
   prUrl: string
@@ -141,9 +178,65 @@ export function createReviewCommentReader(args: {
   }
 }
 
+/**
+ * Resolver for a resolved target. Returns undefined when the host cannot
+ * serve that provider, so callers degrade instead of throwing.
+ */
+export function createReviewThreadResolver(args: {
+  target: ScmReviewTarget;
+  github?: HostGitHubClient;
+}): ReviewThreadResolverImplementation | undefined {
+  switch (args.target.provider) {
+    case "github":
+      return args.github === undefined
+        ? undefined
+        : createHostGithubReviewThreadResolver(args.github);
+  }
+}
+
+/**
+ * Resolve the review threads that own `commentIds` on `prUrl`.
+ *
+ * No-ops (never throws) when the PR is on an SCM this host cannot write,
+ * no client is bound, or `commentIds` is empty. Same degrade-don't-fail
+ * posture as {@link createReviewCommentReader}.
+ */
+export async function resolveReviewThreadsForComments(args: {
+  prUrl: string;
+  commentIds: readonly number[];
+  github?: HostGitHubClient;
+  resolver?: ReviewThreadResolverImplementation;
+  signal?: AbortSignal;
+}): Promise<ResolveReviewThreadsResult> {
+  if (args.commentIds.length === 0) {
+    return skippedResolve("no comments to resolve");
+  }
+  const target = resolveScmReviewTarget(args.prUrl);
+  if (target === undefined) {
+    return skippedResolve("no SCM resolver for this PR URL");
+  }
+  const resolver =
+    args.resolver ??
+    createReviewThreadResolver({
+      target,
+      github: args.github,
+    });
+  if (resolver === undefined) {
+    return skippedResolve("no GitHub client bound to resolve threads");
+  }
+  return resolver.resolveReviewThreadsForComments({
+    target,
+    commentIds: args.commentIds,
+    signal: args.signal,
+  });
+}
+
 /** Cap on pages pulled per PR; GitHub serves 100 comments per page. */
 const REVIEW_COMMENTS_MAX_PAGES = 5;
 const REVIEW_COMMENTS_PAGE_SIZE = 100;
+/** Cap on review-thread pages when mapping comment ids to GraphQL thread ids. */
+const REVIEW_THREADS_MAX_PAGES = 20;
+const REVIEW_THREADS_PAGE_SIZE = 100;
 
 /**
  * Reads inline review comments through the host GitHub client (Cursor
@@ -182,6 +275,188 @@ export function createHostGithubReviewCommentReader(
   };
 }
 
+type GithubReviewThreadNode = {
+  id?: string;
+  isResolved?: boolean;
+  comments?: {
+    nodes?: Array<{ databaseId?: number | null } | null>;
+  };
+};
+
+type GithubReviewThreadsQuery = {
+  repository?: {
+    pullRequest?: {
+      reviewThreads?: {
+        nodes?: Array<GithubReviewThreadNode | null>;
+        pageInfo?: { hasNextPage?: boolean; endCursor?: string | null };
+      };
+    } | null;
+  } | null;
+};
+
+type GithubResolveThreadMutation = {
+  resolveReviewThread?: {
+    thread?: { isResolved?: boolean };
+  };
+};
+
+/**
+ * Resolves inline review threads through the host GitHub client (Cursor
+ * account lease, App installation token, or PAT). GitHub GraphQL has no
+ * comment→thread field, so this pages the PR's review threads and matches
+ * each REST comment id by `databaseId` — the same approach as Bugbot's
+ * `resolveReviewThreadForComment`.
+ */
+export function createHostGithubReviewThreadResolver(
+  github: HostGitHubClient
+): ReviewThreadResolverImplementation {
+  return {
+    async resolveReviewThreadsForComments({ target, commentIds, signal }) {
+      const uniqueIds = [...new Set(commentIds.filter((id) => id > 0))];
+      if (uniqueIds.length === 0) {
+        return skippedResolve("no comments to resolve");
+      }
+      const [owner, repo] = target.repo.split("/", 2);
+      if (owner === undefined || repo === undefined || repo === "") {
+        return skippedResolve("unparseable owner/repo from PR URL");
+      }
+
+      try {
+        const octokit = await github.getOctokit();
+        const wanted = new Set(uniqueIds);
+        const matched = new Map<
+          number,
+          { threadId: string; isResolved: boolean }
+        >();
+
+        let cursor: string | null = null;
+        for (let page = 0; page < REVIEW_THREADS_MAX_PAGES; page++) {
+          signal?.throwIfAborted();
+          const response = (await octokit.graphql(REVIEW_THREADS_FOR_PR_QUERY, {
+            owner,
+            repo,
+            number: target.prNumber,
+            cursor,
+          })) as GithubReviewThreadsQuery;
+          const reviewThreads = response.repository?.pullRequest?.reviewThreads;
+          for (const thread of reviewThreads?.nodes ?? []) {
+            if (thread?.id === undefined || thread.id === "") {
+              continue;
+            }
+            for (const comment of thread.comments?.nodes ?? []) {
+              const databaseId = comment?.databaseId;
+              if (
+                databaseId !== undefined &&
+                databaseId !== null &&
+                wanted.has(databaseId) &&
+                !matched.has(databaseId)
+              ) {
+                matched.set(databaseId, {
+                  threadId: thread.id,
+                  isResolved: thread.isResolved === true,
+                });
+              }
+            }
+          }
+          if (matched.size === wanted.size) {
+            break;
+          }
+          const pageInfo = reviewThreads?.pageInfo;
+          if (pageInfo?.hasNextPage !== true || !pageInfo.endCursor) {
+            break;
+          }
+          cursor = pageInfo.endCursor;
+        }
+
+        const toResolve = [
+          ...new Map(
+            [...matched.values()]
+              .filter((thread) => !thread.isResolved)
+              .map((thread) => [thread.threadId, thread.threadId])
+          ).values(),
+        ];
+        let resolved = 0;
+        let failed = 0;
+        for (const threadId of toResolve) {
+          signal?.throwIfAborted();
+          try {
+            const mutation = (await octokit.graphql(
+              RESOLVE_REVIEW_THREAD_MUTATION,
+              { threadId }
+            )) as GithubResolveThreadMutation;
+            if (mutation.resolveReviewThread?.thread?.isResolved === true) {
+              resolved += 1;
+            } else {
+              failed += 1;
+            }
+          } catch {
+            failed += 1;
+          }
+        }
+
+        const alreadyResolved = new Set(
+          [...matched.values()]
+            .filter((thread) => thread.isResolved)
+            .map((thread) => thread.threadId)
+        ).size;
+        const notFound = wanted.size - matched.size;
+        return {
+          requested: uniqueIds.length,
+          resolved,
+          alreadyResolved,
+          notFound,
+          failed,
+          detail: `resolved ${resolved} of ${toResolve.length} open thread(s) for ${uniqueIds.length} comment(s) via host GitHub (${alreadyResolved} already resolved, ${notFound} not found, ${failed} failed)`,
+        };
+      } catch (error) {
+        if (signal?.aborted) {
+          throw error;
+        }
+        return {
+          requested: uniqueIds.length,
+          resolved: 0,
+          alreadyResolved: 0,
+          notFound: 0,
+          failed: uniqueIds.length,
+          detail: `host GitHub thread resolve failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+      }
+    },
+  };
+}
+
+const REVIEW_THREADS_FOR_PR_QUERY = `
+query ReviewThreadsForPr(
+  $owner: String!
+  $repo: String!
+  $number: Int!
+  $cursor: String
+) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $number) {
+      reviewThreads(first: ${REVIEW_THREADS_PAGE_SIZE}, after: $cursor) {
+        nodes {
+          id
+          isResolved
+          comments(first: ${REVIEW_THREADS_PAGE_SIZE}) {
+            nodes { databaseId }
+          }
+        }
+        pageInfo { hasNextPage endCursor }
+      }
+    }
+  }
+}
+`;
+
+const RESOLVE_REVIEW_THREAD_MUTATION = `
+mutation ResolveReviewThread($threadId: ID!) {
+  resolveReviewThread(input: { threadId: $threadId }) {
+    thread { isResolved }
+  }
+}
+`;
+
 type GithubReviewCommentLike = {
   id: number;
   path: string;
@@ -504,6 +779,17 @@ function skippedHost(detail: string): ReviewCommentPostResult {
   };
 }
 
+function skippedResolve(detail: string): ResolveReviewThreadsResult {
+  return {
+    requested: 0,
+    resolved: 0,
+    alreadyResolved: 0,
+    notFound: 0,
+    failed: 0,
+    detail,
+  };
+}
+
 function parseGithubPrUrl(
   prUrl: string
 ):