@cursor/july 0.1.55 → 0.1.61

package/templates/pr-autofixer/agent/lib/start-drive.ts

@@ -0,0 +1,122 @@
+import type { HostContext } from "@cursor/july";
+import type { SendMessageFn, SendMessageOptions } from "@cursor/july/channels";
+import {
+  cloudOptionsFor,
+  continuationTokenFor,
+  driveMessage,
+  parsePrRef,
+} from "./drive.js";
+import { armMergeConflictWatch } from "./merge-watch.js";
+import { lookupPrAgent } from "./affinity.js";
+import { fetchPrState, isTerminalPrState } from "./pr-state.js";
+
+export type StartDriveErrorCode = "missing_pr" | "unrecognized_pr";
+
+export interface StartDriveError {
+  ok: false;
+  code: StartDriveErrorCode;
+  error: string;
+}
+
+export interface StartDriveSuccess {
+  ok: true;
+  pr: string;
+  sessionId: string | null;
+  continuationToken: string | null;
+  bcId: string | null;
+  agentUrl: string | null;
+  status: string;
+  result: string | null;
+  mergeConflictReminderId: string | null;
+}
+
+export type StartDriveResult = StartDriveError | StartDriveSuccess;
+
+export interface StartDriveArgs {
+  pr: string;
+  hint?: string;
+  send: SendMessageFn;
+  host: HostContext;
+}
+
+function agentUrlFor(bcId: string | null): string | null {
+  return bcId === null ? null : `https://cursor.com/agents/${bcId}`;
+}
+
+export async function startDrive(
+  args: StartDriveArgs
+): Promise<StartDriveResult> {
+  const prRaw = args.pr.trim();
+  if (prRaw === "") {
+    return {
+      ok: false,
+      code: "missing_pr",
+      error: 'Body must include "pr": a GitHub PR URL or owner/repo#N.',
+    };
+  }
+  const pr = parsePrRef(prRaw);
+  if (pr === undefined) {
+    return {
+      ok: false,
+      code: "unrecognized_pr",
+      error: `Unrecognized PR reference: ${args.pr}`,
+    };
+  }
+
+  const hint = args.hint?.trim() || undefined;
+  const prState = await fetchPrState({ github: args.host.github, pr });
+
+  if (isTerminalPrState(prState)) {
+    return {
+      ok: true,
+      pr: pr.label,
+      sessionId: null,
+      continuationToken: null,
+      bcId: null,
+      agentUrl: null,
+      status: "finished",
+      result: `PR ${pr.label} is already ${prState.toLowerCase()}. Nothing to drive.`,
+      mergeConflictReminderId: null,
+    };
+  }
+
+  const continuationToken = continuationTokenFor(pr);
+  const boundAgent = await lookupPrAgent(pr, args.host.kv);
+  const sendOptions: SendMessageOptions = {
+    continuationToken,
+    title: `PR ${pr.label}`,
+    cloud: cloudOptionsFor(pr),
+    sdkAgentId: boundAgent,
+  };
+
+  const session = await args.send(driveMessage(pr, { hint }), sendOptions);
+
+  let reminderId: string | null = null;
+  if (args.host.reminders !== undefined) {
+    const reminder = await armMergeConflictWatch({
+      reminders: args.host.reminders,
+      pr,
+      channelId: "drive",
+      continuationToken,
+    }).catch(() => undefined);
+    if (reminder !== undefined) {
+      reminderId = reminder.id;
+    }
+  }
+
+  const bcId = session.info.sdkAgentId?.startsWith("bc-")
+    ? session.info.sdkAgentId
+    : null;
+
+  return {
+    ok: true,
+    pr: pr.label,
+    sessionId: session.id,
+    continuationToken,
+    bcId,
+    agentUrl: agentUrlFor(bcId),
+    status: "started",
+    result: null,
+    mergeConflictReminderId: reminderId,
+  };
+}

package/templates/pr-autofixer/agent/lib/webhook-buffer.ts

@@ -0,0 +1,225 @@
+import type { HostKvApi } from "@cursor/july/kv";
+
+export const WEBHOOK_BUFFER_KV_KEY: string = "webhook-buffer";
+
+export interface BufferedWebhookEvent {
+  eventName: string;
+  action?: string;
+  prUrl: string;
+  owner: string;
+  repo: string;
+  number: number;
+  headSha?: string;
+}
+
+export interface WebhookBufferOptions {
+  debounceMs?: number;
+  onFlush: (event: BufferedWebhookEvent) => void | Promise<void>;
+  kv: HostKvApi;
+}
+
+interface BufferEntry {
+  latest: BufferedWebhookEvent;
+  count: number;
+  timer: ReturnType<typeof setTimeout> | undefined;
+  deadlineMs: number;
+}
+
+interface SnapshotEntry {
+  latest: BufferedWebhookEvent;
+  count: number;
+  deadlineMs: number;
+}
+
+export class WebhookBuffer {
+  private readonly entries = new Map<string, BufferEntry>();
+  private readonly inFlight = new Set<string>();
+  private readonly debounceMs: number;
+  private readonly onFlush: WebhookBufferOptions["onFlush"];
+  private readonly kv: HostKvApi;
+  private persistChain: Promise<void> = Promise.resolve();
+  private generation = 0;
+
+  constructor(options: WebhookBufferOptions) {
+    this.debounceMs = options.debounceMs ?? 3000;
+    this.onFlush = options.onFlush;
+    this.kv = options.kv;
+  }
+
+  static keyFor(
+    event: Pick<BufferedWebhookEvent, "owner" | "repo" | "number">
+  ): string {
+    return `${event.owner}/${event.repo}#${event.number}`;
+  }
+
+  async enqueue(event: BufferedWebhookEvent): Promise<void> {
+    const key = WebhookBuffer.keyFor(event);
+    const existing = this.entries.get(key);
+    if (existing === undefined) {
+      this.entries.set(key, {
+        latest: event,
+        count: 1,
+        timer: undefined,
+        deadlineMs: Date.now() + this.debounceMs,
+      });
+    } else {
+      existing.latest = event;
+      existing.count += 1;
+      existing.deadlineMs = Date.now() + this.debounceMs;
+    }
+    await this.persist();
+    this.schedule(key);
+  }
+
+  async restore(): Promise<number> {
+    const snapshot = await this.kv.get(WEBHOOK_BUFFER_KV_KEY);
+    if (
+      !isJsonObject(snapshot) ||
+      snapshot.version !== 1 ||
+      !isJsonObject(snapshot.entries)
+    ) {
+      return 0;
+    }
+    let restored = 0;
+    for (const [key, entry] of Object.entries(snapshot.entries)) {
+      if (!isValidSnapshotEntry(entry)) {
+        continue;
+      }
+      this.entries.set(key, {
+        latest: entry.latest,
+        count: Math.max(1, entry.count),
+        timer: undefined,
+        deadlineMs: entry.deadlineMs,
+      });
+      this.schedule(key);
+      restored += 1;
+    }
+    return restored;
+  }
+
+  async discard(key: string): Promise<void> {
+    const entry = this.entries.get(key);
+    if (entry === undefined) {
+      return;
+    }
+    clearTimeout(entry.timer);
+    this.entries.delete(key);
+    await this.persist();
+  }
+
+  async clear(): Promise<void> {
+    this.generation += 1;
+    for (const entry of this.entries.values()) {
+      clearTimeout(entry.timer);
+    }
+    this.entries.clear();
+    this.inFlight.clear();
+  }
+
+  private schedule(key: string): void {
+    const entry = this.entries.get(key);
+    if (entry === undefined) {
+      return;
+    }
+    clearTimeout(entry.timer);
+    const delay = Math.max(0, entry.deadlineMs - Date.now());
+    entry.timer = setTimeout(() => {
+      void this.flush(key);
+    }, delay);
+  }
+
+  private async flush(key: string): Promise<void> {
+    const entry = this.entries.get(key);
+    if (entry === undefined) {
+      return;
+    }
+
+    if (this.inFlight.has(key)) {
+      entry.deadlineMs = Date.now() + this.debounceMs;
+      await this.persist();
+      this.schedule(key);
+      return;
+    }
+
+    entry.timer = undefined;
+    this.inFlight.add(key);
+    const generation = this.generation;
+    try {
+      const event = entry.latest;
+      const count = entry.count;
+      await this.onFlush(event);
+      if (generation !== this.generation) {
+        return;
+      }
+      const current = this.entries.get(key);
+      if (
+        current !== undefined &&
+        current.latest === event &&
+        current.count === count
+      ) {
+        this.entries.delete(key);
+      }
+      await this.persist();
+    } catch (error) {
+      if (generation !== this.generation) {
+        throw error;
+      }
+      entry.deadlineMs = Date.now() + this.debounceMs;
+      await this.persist();
+      this.schedule(key);
+      throw error;
+    } finally {
+      if (generation === this.generation) {
+        this.inFlight.delete(key);
+      }
+    }
+  }
+
+  private persist(): Promise<void> {
+    const entries: Record<string, SnapshotEntry> = {};
+    for (const [key, entry] of this.entries) {
+      entries[key] = {
+        latest: entry.latest,
+        count: entry.count,
+        deadlineMs: entry.deadlineMs,
+      };
+    }
+    const write = (): Promise<void> =>
+      this.kv.put(
+        WEBHOOK_BUFFER_KV_KEY,
+        JSON.parse(
+          JSON.stringify({
+            version: 1,
+            updatedAt: new Date().toISOString(),
+            entries,
+          })
+        )
+      );
+    const next = this.persistChain.then(write, write);
+    this.persistChain = next.then(
+      () => undefined,
+      () => undefined
+    );
+    return next;
+  }
+}
+
+function isJsonObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isValidSnapshotEntry(entry: unknown): entry is SnapshotEntry {
+  if (!isJsonObject(entry) || !isJsonObject(entry.latest)) {
+    return false;
+  }
+  const latest = entry.latest;
+  return (
+    typeof latest.eventName === "string" &&
+    typeof latest.prUrl === "string" &&
+    typeof latest.owner === "string" &&
+    typeof latest.repo === "string" &&
+    typeof latest.number === "number" &&
+    typeof entry.count === "number" &&
+    typeof entry.deadlineMs === "number"
+  );
+}

package/templates/pr-autofixer/agent/lib/webhook-routing.ts

@@ -0,0 +1,231 @@
+import type {
+  GitHubCheckRunEvent,
+  GitHubCheckSuiteEvent,
+  GitHubEventContext,
+  GitHubPullRequestEvent,
+  GitHubRawEvent,
+  GitHubStatusEvent,
+} from "@cursor/july/channels/github";
+import type { BufferedWebhookEvent } from "./webhook-buffer.js";
+
+const PULL_REQUEST_ACTIONS = new Set([
+  "reopened",
+  "synchronize",
+  "edited",
+  "ready_for_review",
+  "review_requested",
+  "converted_to_draft",
+]);
+
+const CHECK_SUITE_CONCLUSIONS = new Set([
+  "success",
+  "failure",
+  "timed_out",
+  "action_required",
+  "startup_failure",
+]);
+
+const CHECK_RUN_FAILURE_CONCLUSIONS = new Set([
+  "failure",
+  "timed_out",
+  "action_required",
+  "startup_failure",
+]);
+
+export function shouldBufferPullRequest(pr: GitHubPullRequestEvent): boolean {
+  return PULL_REQUEST_ACTIONS.has(pr.action);
+}
+
+export function shouldBufferStatus(status: GitHubStatusEvent): boolean {
+  return status.state === "failure" || status.state === "error";
+}
+
+function shouldBufferCheckSuite(suite: GitHubCheckSuiteEvent): boolean {
+  return (
+    suite.action === "completed" &&
+    suite.conclusion != null &&
+    CHECK_SUITE_CONCLUSIONS.has(suite.conclusion)
+  );
+}
+
+function shouldBufferCheckRun(run: GitHubCheckRunEvent): boolean {
+  return (
+    run.action === "completed" &&
+    run.conclusion != null &&
+    CHECK_RUN_FAILURE_CONCLUSIONS.has(run.conclusion)
+  );
+}
+
+function shouldBufferRawEvent(event: GitHubRawEvent): boolean {
+  if (event.eventName === "pull_request_review") {
+    return event.action === "submitted" || event.action === "dismissed";
+  }
+  if (event.eventName === "pull_request_review_thread") {
+    return event.action === "resolved" || event.action === "unresolved";
+  }
+  return false;
+}
+
+function fromConversation(
+  ctx: GitHubEventContext,
+  fields: {
+    eventName: string;
+    action?: string;
+    headSha?: string;
+  }
+): BufferedWebhookEvent | null {
+  if (ctx.conversation.kind !== "pull_request") {
+    return null;
+  }
+  if (ctx.conversation.number <= 0) {
+    return null;
+  }
+  return {
+    eventName: fields.eventName,
+    action: fields.action,
+    prUrl: ctx.conversation.url,
+    owner: ctx.repository.owner,
+    repo: ctx.repository.name,
+    number: ctx.conversation.number,
+    headSha: fields.headSha,
+  };
+}
+
+async function resolvePrFromCommitSha(input: {
+  ctx: GitHubEventContext;
+  sha: string;
+}): Promise<{ number: number; url: string } | undefined> {
+  try {
+    const octokit = await input.ctx.github.getOctokit();
+    const { data: pulls } = await octokit.request(
+      "GET /repos/{owner}/{repo}/commits/{commit_sha}/pulls",
+      {
+        owner: input.ctx.repository.owner,
+        repo: input.ctx.repository.name,
+        commit_sha: input.sha,
+      }
+    );
+    const open = pulls.find((pull) => pull.state === "open");
+    if (open === undefined) {
+      return undefined;
+    }
+    return {
+      number: open.number,
+      url: open.html_url,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+async function fromSha(input: {
+  ctx: GitHubEventContext;
+  sha: string;
+  eligible: boolean;
+  eventName: string;
+  action?: string;
+}): Promise<BufferedWebhookEvent | null> {
+  if (!input.eligible) {
+    return null;
+  }
+  const direct = fromConversation(input.ctx, {
+    eventName: input.eventName,
+    action: input.action,
+    headSha: input.sha,
+  });
+  if (direct !== null) {
+    return direct;
+  }
+  const resolved = await resolvePrFromCommitSha({
+    ctx: input.ctx,
+    sha: input.sha,
+  });
+  if (resolved === undefined) {
+    return null;
+  }
+  return {
+    eventName: input.eventName,
+    action: input.action,
+    prUrl: resolved.url,
+    owner: input.ctx.repository.owner,
+    repo: input.ctx.repository.name,
+    number: resolved.number,
+    headSha: input.sha,
+  };
+}
+
+export function bufferedEventFromPr(input: {
+  ctx: GitHubEventContext;
+  pr: GitHubPullRequestEvent;
+}): BufferedWebhookEvent | null {
+  if (!shouldBufferPullRequest(input.pr)) {
+    return null;
+  }
+  return {
+    eventName: "pull_request",
+    action: input.pr.action,
+    prUrl: input.pr.url,
+    owner: input.ctx.repository.owner,
+    repo: input.ctx.repository.name,
+    number: input.pr.number,
+    headSha: input.pr.headSha,
+  };
+}
+
+export function bufferedEventFromComment(input: {
+  ctx: GitHubEventContext;
+  eventName: string;
+}): BufferedWebhookEvent | null {
+  return fromConversation(input.ctx, { eventName: input.eventName });
+}
+
+export function bufferedEventFromCheckSuite(input: {
+  ctx: GitHubEventContext;
+  suite: GitHubCheckSuiteEvent;
+}): Promise<BufferedWebhookEvent | null> {
+  return fromSha({
+    ctx: input.ctx,
+    sha: input.suite.headSha,
+    eligible: shouldBufferCheckSuite(input.suite),
+    eventName: "check_suite",
+    action: input.suite.action,
+  });
+}
+
+export function bufferedEventFromCheckRun(input: {
+  ctx: GitHubEventContext;
+  run: GitHubCheckRunEvent;
+}): Promise<BufferedWebhookEvent | null> {
+  return fromSha({
+    ctx: input.ctx,
+    sha: input.run.headSha,
+    eligible: shouldBufferCheckRun(input.run),
+    eventName: "check_run",
+    action: input.run.action,
+  });
+}
+
+export function bufferedEventFromStatus(input: {
+  ctx: GitHubEventContext;
+  status: GitHubStatusEvent;
+}): Promise<BufferedWebhookEvent | null> {
+  return fromSha({
+    ctx: input.ctx,
+    sha: input.status.sha,
+    eligible: shouldBufferStatus(input.status),
+    eventName: "status",
+  });
+}
+
+export function bufferedEventFromRaw(input: {
+  ctx: GitHubEventContext;
+  event: GitHubRawEvent;
+}): BufferedWebhookEvent | null {
+  if (!shouldBufferRawEvent(input.event)) {
+    return null;
+  }
+  return fromConversation(input.ctx, {
+    eventName: input.event.eventName,
+    action: input.event.action,
+  });
+}

package/templates/pr-autofixer/agent/storage.ts

@@ -0,0 +1,7 @@
+import { defineStorage } from "@cursor/july/storage";
+import { cursorHostedStorage } from "@cursor/july/storage/cursor-hosted";
+
+export default defineStorage({
+  name: "cursor-hosted",
+  ...cursorHostedStorage(),
+});

package/templates/pr-autofixer/agent/tools/drive_pr.ts

@@ -0,0 +1,22 @@
+import { defineTool } from "@cursor/july/tools";
+import type { ToolExecuteResult } from "@cursor/july/tools";
+import { driveStartBodySchema } from "../lib/drive-schemas.js";
+import { startDrive } from "../lib/start-drive.js";
+
+export default defineTool({
+  description:
+    "Start PR autofixer on a GitHub pull request. Attaches the PR to a Cursor cloud agent and returns as soon as the session exists. bcId / agentUrl are included when already bound; otherwise they fill in from agent.bound. Triage continues asynchronously. Call whenever the user wants to drive, triage, or unblock a PR. Do not review the PR yourself from chat; there is no checkout here.",
+  inputSchema: driveStartBodySchema,
+  async execute({ pr, hint }, ctx): Promise<ToolExecuteResult> {
+    const result = await startDrive({
+      pr,
+      hint,
+      send: (message, options) => ctx.send("drive", message, options),
+      host: ctx.host,
+    });
+    if (!result.ok) {
+      return { ok: false, error: result.error, code: result.code };
+    }
+    return result;
+  },
+});

package/templates/pr-autofixer/evals/coordinator.eval.ts

@@ -0,0 +1,16 @@
+import { defineEval } from "@cursor/july/evals";
+
+export default defineEval({
+  tags: ["smoke"],
+  cases: [
+    {
+      id: "no-pr",
+      description: "Chat without a PR does not start a cloud drive.",
+      async test(t) {
+        await t.send("What can you help with?");
+        t.succeeded();
+        t.calledTool("drive_pr", { count: 0 });
+      },
+    },
+  ],
+});

package/templates/pr-autofixer/evals/evals.config.ts

@@ -0,0 +1,5 @@
+import { defineEvalConfig } from "@cursor/july/evals";
+
+export default defineEvalConfig({
+  maxConcurrency: 10,
+});

package/templates/pr-autofixer/init.json

@@ -0,0 +1,25 @@
+{
+  "questions": [
+    {
+      "id": "repos",
+      "prompt": "GitHub repositories Cursor should relay SCM events for",
+      "hint": "Comma-separated owner/repo. One owner. Up to 20.",
+      "placeholder": "acme/widgets, acme/api",
+      "parse": "owner-repo-list"
+    }
+  ],
+  "replace": [
+    {
+      "file": "agent/lib/repos.ts",
+      "find": "[\"owner/repo\"]",
+      "answer": "repos",
+      "as": "json-array"
+    },
+    {
+      "file": "agent/channels/slack.ts",
+      "find": "acme/widgets",
+      "answer": "repos",
+      "as": "first"
+    }
+  ]
+}

package/templates/pr-autofixer/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "pr-autofixer",
+  "private": true,
+  "type": "module",
+  "description": "PR autofixer: attach a pull request to a Cursor cloud agent and keep it moving toward merge.",
+  "scripts": {
+    "check": "tsc --noEmit",
+    "dev": "agent-sdk dev"
+  },
+  "dependencies": {
+    "@cursor/july": "latest",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.0",
+    "typescript": "^5.8.0"
+  }
+}

package/templates/pr-autofixer/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["agent/**/*", "evals/**/*"]
+}