@cursor/july 0.1.12 → 0.1.14

package/src/internal/cursor/backend-client.ts

@@ -85,6 +85,48 @@ const mcpToolSchema = z.object({
   inputSchema: z.unknown().optional(),
 });
 
+const getAvailableMcpServersResponseSchema = z.object({
+  servers: z
+    .array(
+      z.object({
+        id: z.number().optional(),
+        name: z.string().optional(),
+        isTeamServer: z.boolean().optional(),
+        serverIdentifier: z.string().optional(),
+      })
+    )
+    .optional(),
+});
+
+/** One connector row from the account's dashboard MCP listing. */
+export interface AvailableMcpServer {
+  id: number;
+  name: string;
+  isTeamServer: boolean;
+  serverIdentifier?: string;
+}
+
+const checkHttpMcpStatusResponseSchema = z.object({
+  statuses: z
+    .array(
+      z.object({
+        id: z.number().optional(),
+        requiresAuth: z.boolean().optional(),
+        authUrl: z.string().optional(),
+        error: z.string().optional(),
+      })
+    )
+    .optional(),
+});
+
+/** Per-connector OAuth status (SA-scoped when `serviceAccountId` was sent). */
+export interface McpConnectorStatus {
+  id: number;
+  requiresAuth: boolean;
+  authUrl?: string;
+  error?: string;
+}
+
 const listSandMcpToolsResponseSchema = z.object({
   servers: z
     .array(
@@ -180,6 +222,7 @@ async function dashboardRpc(args: {
   bearer: string;
   body: unknown;
   timeoutMs: number;
+  extraHeaders?: Record<string, string>;
 }): Promise<Response> {
   try {
     return await args.fetchImpl(
@@ -193,6 +236,7 @@ async function dashboardRpc(args: {
           "x-cursor-client-version": CLIENT_VERSION,
           "x-cursor-client-type": "agent-serve",
           "x-request-id": randomUUID(),
+          ...args.extraHeaders,
         },
         body: JSON.stringify(args.body ?? {}),
         signal: AbortSignal.timeout(args.timeoutMs),
@@ -309,6 +353,58 @@ export class CursorBackendClient {
     return toCallResult(parsed.result ?? {});
   }
 
+  /**
+   * The account's dashboard MCP connector listing (id + name per server).
+   * `teamId` pins the ambient team so team-scoped connectors resolve for
+   * multi-team accounts.
+   */
+  async getAvailableMcpServers(options?: {
+    teamId?: number;
+  }): Promise<AvailableMcpServer[]> {
+    const raw = await this.rpc("GetAvailableMcpServers", {}, LIST_TIMEOUT_MS, {
+      teamId: options?.teamId,
+    });
+    const parsed = getAvailableMcpServersResponseSchema.parse(raw);
+    return (parsed.servers ?? [])
+      .filter((server) => server.id !== undefined && server.id > 0)
+      .map((server) => ({
+        id: server.id!,
+        name: server.name ?? "",
+        isTeamServer: server.isTeamServer === true,
+        serverIdentifier: server.serverIdentifier,
+      }));
+  }
+
+  /**
+   * Probe connectors for a service account and mint OAuth `authUrl`s where
+   * authorization is needed. This is the dashboard's Authenticate flow: the
+   * caller (a team member) opens the returned URL, the cursor.com callback
+   * stores the token backend-side against the service account, and repeat
+   * probes flip `requiresAuth` off.
+   */
+  async checkHttpMcpStatus(args: {
+    serverIds: number[];
+    oauthRedirectUri: string;
+    serviceAccountId: string;
+  }): Promise<McpConnectorStatus[]> {
+    const raw = await this.rpc(
+      "CheckHttpMcpStatus",
+      {
+        serverIds: args.serverIds,
+        oauthRedirectUri: args.oauthRedirectUri,
+        serviceAccountId: args.serviceAccountId,
+      },
+      LIST_TIMEOUT_MS
+    );
+    const parsed = checkHttpMcpStatusResponseSchema.parse(raw);
+    return (parsed.statuses ?? []).map((status) => ({
+      id: status.id ?? 0,
+      requiresAuth: status.requiresAuth === true,
+      authUrl: status.authUrl,
+      error: status.error,
+    }));
+  }
+
   /** Mint a short-lived GitHub token scoped to the requested repositories. */
   async getGithubToken(
     repos: readonly string[],
@@ -356,8 +452,13 @@ export class CursorBackendClient {
   private async rpc(
     method: string,
     body: unknown,
-    timeoutMs = LIST_TIMEOUT_MS
+    timeoutMs = LIST_TIMEOUT_MS,
+    options?: { teamId?: number }
   ): Promise<unknown> {
+    const extraHeaders =
+      options?.teamId === undefined
+        ? undefined
+        : { "x-cursor-team-id": String(options.teamId) };
     const bearer = await this.getAccessToken();
     const first = await dashboardRpc({
       fetchImpl: this.fetchImpl,
@@ -366,6 +467,7 @@ export class CursorBackendClient {
       bearer,
       body,
       timeoutMs,
+      extraHeaders,
     });
     if (first.status !== 401) {
       return parseRpcResponse(method, first);
@@ -385,6 +487,7 @@ export class CursorBackendClient {
       bearer: retryBearer,
       body,
       timeoutMs,
+      extraHeaders,
     });
     if (second.status === 401 && this.token?.value === retryBearer) {
       // The freshly minted token was rejected too; do not keep serving it.

package/src/internal/cursor/credentials.ts

@@ -26,10 +26,18 @@ export const DEFAULT_CURSOR_BACKEND_URL = "https://api2.cursor.sh";
 export const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
 const DEFAULT_CURSOR_WEBSITE_URL = "https://cursor.com";
 
-/** Backend API base URL (`CURSOR_API_BASE_URL` override for local dev). */
+/**
+ * Base URL for main-backend-only routes (key exchange, DashboardService —
+ * these 404 on api.cursor.com). Hosted pods pin `CURSOR_API_BASE_URL` to the
+ * external API, so `AGENT_SERVE_CURSOR_BACKEND_URL` re-pins this family
+ * there. Deliberately namespaced: pod env propagates to the SDK harness,
+ * which reads the generic `CURSOR_BACKEND_URL` for its own hosts.
+ */
 export function cursorBackendUrl(): string {
   return trimTrailingSlash(
-    process.env.CURSOR_API_BASE_URL ?? DEFAULT_CURSOR_BACKEND_URL
+    process.env.AGENT_SERVE_CURSOR_BACKEND_URL ??
+      process.env.CURSOR_API_BASE_URL ??
+      DEFAULT_CURSOR_BACKEND_URL
   );
 }
 

package/src/internal/cursor-account-mcp-auth.ts

@@ -0,0 +1,241 @@
+/**
+ * Service-account connector authorization for
+ * `defineConnection({ cursorAccount: true })` on hosted deployments.
+ *
+ * Hosted engines authenticate as their deployment's dedicated service
+ * account, whose connector OAuth tokens live backend-side. This flow is the
+ * dashboard's Authenticate button as a CLI loop: probe the connectors via
+ * `CheckHttpMcpStatus` (which mints a complete OAuth `authUrl` per connector
+ * needing auth), open each URL for the human to grant, and poll until the
+ * backend reports the token stored. Nothing token-shaped ever touches this
+ * process — the cursor.com callback stores tokens against the service
+ * account. Used by `agentkit mcp oauth <connection>` and the post-deploy
+ * hook in `cli-deploy.ts`.
+ */
+
+import type {
+  AvailableMcpServer,
+  CursorBackendClient,
+  McpConnectorStatus,
+} from "./cursor/backend-client.js";
+import { LOG_PREFIX } from "./distribution.js";
+import { openBrowser } from "./mcp-oauth.js";
+
+const DEFAULT_POLL_INTERVAL_MS = 3_000;
+const DEFAULT_POLL_TIMEOUT_MS = 5 * 60 * 1000;
+
+/** Same default the dashboard uses; MCP_OAUTH_REDIRECT_URI overrides for dev. */
+export function mcpOauthRedirectUri(): string {
+  const override = process.env.MCP_OAUTH_REDIRECT_URI;
+  if (override !== undefined && override.trim() !== "") {
+    return override.trim();
+  }
+  return "https://www.cursor.com/agents/mcp/oauth/callback";
+}
+
+export interface AuthorizeCursorAccountConnectorsArgs {
+  backendClient: Pick<
+    CursorBackendClient,
+    "getAvailableMcpServers" | "checkHttpMcpStatus"
+  >;
+  teamId: number;
+  slug: string;
+  /** The deployment's dedicated service account (`sa_…`). */
+  serviceAccountId: string;
+  /** Connection name, for log lines. */
+  connectionName: string;
+  /** The connection's `servers` filter; undefined = every team connector. */
+  servers?: string[] | undefined;
+  /** Open auth URLs and poll for completion (TTY); false = report only. */
+  interactive: boolean;
+  out: (text: string) => void;
+  err: (text: string) => void;
+  /** Test seams. */
+  openBrowserImpl?: (url: string) => void;
+  sleep?: (ms: number) => Promise<void>;
+  pollIntervalMs?: number;
+  pollTimeoutMs?: number;
+}
+
+export interface AuthorizeCursorAccountConnectorsResult {
+  /** Connectors with a stored credential after the flow. */
+  authorized: string[];
+  /** Connectors still requiring authorization. */
+  pending: string[];
+  /** Connectors the backend could not probe. */
+  errored: Array<{ name: string; error: string }>;
+}
+
+function sleepMs(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Authorize the deployment service account for the connection's connectors.
+ * Already-authorized connectors are skipped; the rest get a browser OAuth
+ * each (sequentially), polled until the backend stores the token.
+ */
+export async function authorizeCursorAccountConnectors(
+  args: AuthorizeCursorAccountConnectorsArgs
+): Promise<AuthorizeCursorAccountConnectorsResult> {
+  const { backendClient, teamId, serviceAccountId, connectionName, out, err } =
+    args;
+  const open = args.openBrowserImpl ?? openBrowser;
+  const sleep = args.sleep ?? sleepMs;
+  const pollIntervalMs = args.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const pollTimeoutMs = args.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
+  const redirectUri = mcpOauthRedirectUri();
+
+  // Team-scoped connectors only: the hosted bridge resolves the SA's team
+  // servers, so personal connectors can never apply to a deployment.
+  const available = (
+    await backendClient.getAvailableMcpServers({ teamId })
+  ).filter((server) => server.isTeamServer);
+
+  const selected = selectConnectors(available, args.servers);
+  for (const missing of selected.unmatched) {
+    err(
+      `${LOG_PREFIX} Connection "${connectionName}" lists connector ${JSON.stringify(missing)}, but the team has no such connector (dashboard → MCP).\n`
+    );
+  }
+  if (selected.servers.length === 0) {
+    err(
+      `${LOG_PREFIX} No matching team connectors for connection "${connectionName}".\n`
+    );
+    return { authorized: [], pending: [], errored: [] };
+  }
+
+  const nameById = new Map(
+    selected.servers.map((server) => [server.id, server.name])
+  );
+  const statuses = await backendClient.checkHttpMcpStatus({
+    serverIds: selected.servers.map((server) => server.id),
+    oauthRedirectUri: redirectUri,
+    serviceAccountId,
+  });
+
+  const result: AuthorizeCursorAccountConnectorsResult = {
+    authorized: [],
+    pending: [],
+    errored: [],
+  };
+
+  for (const status of statuses) {
+    const name = nameById.get(status.id) ?? `#${status.id}`;
+    if (!status.requiresAuth) {
+      if (status.error !== undefined && status.error !== "") {
+        err(`${LOG_PREFIX} ${name}: ${status.error}\n`);
+        result.errored.push({ name, error: status.error });
+        continue;
+      }
+      out(`${LOG_PREFIX} ${name}: already authorized ✓\n`);
+      result.authorized.push(name);
+      continue;
+    }
+    if (status.authUrl === undefined || status.authUrl === "") {
+      const error = status.error ?? "no authorization URL was minted";
+      err(`${LOG_PREFIX} ${name}: ${error}\n`);
+      result.errored.push({ name, error });
+      continue;
+    }
+    if (!args.interactive) {
+      result.pending.push(name);
+      continue;
+    }
+
+    out(
+      `${LOG_PREFIX} ${name}: authorization needed. You'll authorize ${name} as yourself; ` +
+        `anyone who can talk to this agent can act with that access.\n` +
+        `${LOG_PREFIX} Opening (or open manually):\n  ${status.authUrl}\n`
+    );
+    open(status.authUrl);
+
+    const authorized = await pollUntilAuthorized({
+      backendClient,
+      serverId: status.id,
+      serviceAccountId,
+      redirectUri,
+      sleep,
+      pollIntervalMs,
+      pollTimeoutMs,
+    });
+    if (authorized) {
+      out(`${LOG_PREFIX} ${name}: authorized ✓\n`);
+      result.authorized.push(name);
+    } else {
+      err(
+        `${LOG_PREFIX} ${name}: still waiting on authorization; giving up for now.\n`
+      );
+      result.pending.push(name);
+    }
+  }
+
+  return result;
+}
+
+function selectConnectors(
+  available: AvailableMcpServer[],
+  filter: string[] | undefined
+): { servers: AvailableMcpServer[]; unmatched: string[] } {
+  if (filter === undefined || filter.length === 0) {
+    return { servers: available, unmatched: [] };
+  }
+  const servers: AvailableMcpServer[] = [];
+  const seen = new Set<number>();
+  const unmatched: string[] = [];
+  for (const name of filter) {
+    const wanted = name.trim().toLowerCase();
+    const matches = available.filter(
+      (server) =>
+        server.name.toLowerCase() === wanted ||
+        server.serverIdentifier?.toLowerCase() === wanted
+    );
+    if (matches.length === 0) {
+      unmatched.push(name);
+      continue;
+    }
+    for (const match of matches) {
+      if (!seen.has(match.id)) {
+        seen.add(match.id);
+        servers.push(match);
+      }
+    }
+  }
+  return { servers, unmatched };
+}
+
+async function pollUntilAuthorized(args: {
+  backendClient: Pick<CursorBackendClient, "checkHttpMcpStatus">;
+  serverId: number;
+  serviceAccountId: string;
+  redirectUri: string;
+  sleep: (ms: number) => Promise<void>;
+  pollIntervalMs: number;
+  pollTimeoutMs: number;
+}): Promise<boolean> {
+  const deadline = Date.now() + args.pollTimeoutMs;
+  // Each unauthorized probe is a full backend connect to the provider, so
+  // back off while the human works through the OAuth pages.
+  let intervalMs = args.pollIntervalMs;
+  const maxIntervalMs = Math.max(args.pollIntervalMs, 15_000);
+  while (Date.now() < deadline) {
+    await args.sleep(intervalMs);
+    intervalMs = Math.min(intervalMs * 1.5, maxIntervalMs);
+    let statuses: McpConnectorStatus[];
+    try {
+      statuses = await args.backendClient.checkHttpMcpStatus({
+        serverIds: [args.serverId],
+        oauthRedirectUri: args.redirectUri,
+        serviceAccountId: args.serviceAccountId,
+      });
+    } catch {
+      // Transient probe errors; keep polling until the deadline.
+      continue;
+    }
+    const status = statuses.find((entry) => entry.id === args.serverId);
+    if (status !== undefined && !status.requiresAuth) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/internal/deploy-client.ts

@@ -175,6 +175,22 @@ export interface DeploymentDetail extends Deployment {
   engineAccess?: EngineAccess | null;
 }
 
+/**
+ * The deployment's dedicated service-account id (`sa_…`), or undefined for
+ * legacy rows that predate service-account-backed deploys. Normalizes the
+ * wire shape (string in prod, number in old fixtures, null when unset).
+ */
+export function deploymentServiceAccountId(
+  deployment: Pick<Deployment, "serviceAccountId">
+): string | undefined {
+  const raw = deployment.serviceAccountId;
+  if (raw === null || raw === undefined) {
+    return undefined;
+  }
+  const id = String(raw).trim();
+  return id === "" ? undefined : id;
+}
+
 export interface StopAccepted {
   id: number;
   status: string;

package/src/internal/eval-run-store.ts

@@ -63,10 +63,13 @@ const INTERRUPTED_BATCH_ERROR =
   "Eval run interrupted (serve process exited before completion)";
 const INTERRUPTED_CASE_ERROR =
   "Eval case interrupted (serve process exited before completion)";
+const CANCELLED_BATCH_ERROR = "Eval run cancelled";
+const CANCELLED_CASE_ERROR = "Eval case cancelled";
 
 export class EvalRunStore {
   private readonly runs = new Map<string, EvalRunSnapshot>();
   private activeRunId: string | undefined;
+  private readonly abortByRunId = new Map<string, AbortController>();
   private hydratePromise: Promise<void> | undefined;
   private hydrated = false;
   /** Filled after listen — e.g. `http://127.0.0.1:3000/weather-agent`. */
@@ -178,6 +181,8 @@ export class EvalRunStore {
     };
     this.runs.set(runId, snapshot);
     this.activeRunId = runId;
+    const abort = new AbortController();
+    this.abortByRunId.set(runId, abort);
     this.pruneOldRuns(config);
     this.persist(snapshot);
     this.logger(
@@ -188,6 +193,7 @@ export class EvalRunStore {
       baseUrl: loopbackUrl,
       evals: selected,
       config,
+      signal: abort.signal,
       ...(input.bearerToken === undefined
         ? {}
         : { bearerToken: input.bearerToken }),
@@ -198,6 +204,33 @@ export class EvalRunStore {
     return snapshot;
   }
 
+  /**
+   * Cancel a running batch by Eval ID (`runId`). Stops starting new cases and
+   * aborts in-flight turns. Idempotent when already cancelled.
+   */
+  async cancel(runId: string): Promise<EvalRunSnapshot> {
+    await this.hydrate();
+    const run = this.runs.get(runId);
+    if (run === undefined) {
+      throw new EvalRunUnknownError(runId);
+    }
+    if (run.status === "cancelled") {
+      return run;
+    }
+    if (run.status !== "running") {
+      throw new EvalRunNotRunningError(runId, run.status);
+    }
+    const abort = this.abortByRunId.get(runId);
+    abort?.abort();
+    markCancelledRun(run);
+    this.persist(run);
+    if (this.activeRunId === runId) {
+      this.activeRunId = undefined;
+    }
+    this.logger(`[agentkit] eval run ${runId}: cancelled`);
+    return run;
+  }
+
   private sortedRuns(): EvalRunSnapshot[] {
     return [...this.runs.values()].sort((a, b) =>
       b.startedAt.localeCompare(a.startedAt)
@@ -306,9 +339,11 @@ export class EvalRunStore {
     if (run === undefined || run.status !== "running") {
       return;
     }
+    this.abortByRunId.get(activeRunId)?.abort();
     markInterruptedRun(run);
     this.persist(run);
     this.activeRunId = undefined;
+    this.abortByRunId.delete(activeRunId);
   }
 
   private async execute(
@@ -320,6 +355,7 @@ export class EvalRunStore {
       bearerToken?: string;
       verbose?: boolean;
       timeoutMs?: number;
+      signal: AbortSignal;
     }
   ): Promise<void> {
     if (this.runs.get(runId) === undefined) {
@@ -330,6 +366,7 @@ export class EvalRunStore {
         projectRoot: this.projectRoot,
         baseUrl: opts.baseUrl,
         discovered: { evals: opts.evals, config: opts.config },
+        signal: opts.signal,
         ...(opts.bearerToken === undefined
           ? {}
           : { bearerToken: opts.bearerToken }),
@@ -337,7 +374,7 @@ export class EvalRunStore {
         ...(opts.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
         onCaseStart: (id) => {
           const run = this.runs.get(runId);
-          if (run === undefined) {
+          if (run === undefined || run.status === "cancelled") {
             return;
           }
           const c = run.cases.find((x) => x.id === id);
@@ -387,7 +424,7 @@ export class EvalRunStore {
         },
       });
       const run = this.runs.get(runId);
-      if (run === undefined) {
+      if (run === undefined || run.status === "cancelled") {
         return;
       }
       run.status = "completed";
@@ -398,15 +435,23 @@ export class EvalRunStore {
       );
     } catch (error) {
       const run = this.runs.get(runId);
-      if (run === undefined) {
+      if (run === undefined || run.status === "cancelled") {
+        return;
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      if (opts.signal.aborted || message === "cancelled") {
+        markCancelledRun(run);
+        this.persist(run);
+        this.logger(`[agentkit] eval run ${runId}: cancelled`);
         return;
       }
       run.status = "failed";
       run.finishedAt = new Date().toISOString();
-      run.error = error instanceof Error ? error.message : String(error);
+      run.error = message;
       this.persist(run);
       this.logger(`[agentkit] eval run ${runId}: failed — ${run.error}`);
     } finally {
+      this.abortByRunId.delete(runId);
       if (this.activeRunId === runId) {
         this.activeRunId = undefined;
       }
@@ -422,6 +467,7 @@ export class EvalRunStore {
     if (c === undefined) {
       return;
     }
+    const alreadyCounted = c.status === "done";
     c.status = "done";
     c.ok = result.ok;
     c.assertions = result.assertions;
@@ -443,6 +489,10 @@ export class EvalRunStore {
     if (result.tools !== undefined) {
       c.tools = result.tools;
     }
+    // Batch already finalized by cancel — keep case details, skip recount.
+    if (run.status === "cancelled" || alreadyCounted) {
+      return;
+    }
     run.summary.done += 1;
     if (result.ok) {
       run.summary.passed += 1;
@@ -463,8 +513,24 @@ function markInterruptedRun(run: EvalRunSnapshot): void {
       c.error = c.error ?? INTERRUPTED_CASE_ERROR;
     }
   }
-  // Reconcile the summary with the repaired case rows so a persisted
-  // interrupted batch never claims pre-interruption pass counts.
+  reconcileRunSummary(run);
+}
+
+function markCancelledRun(run: EvalRunSnapshot): void {
+  run.status = "cancelled";
+  run.finishedAt = run.finishedAt ?? new Date().toISOString();
+  run.error = CANCELLED_BATCH_ERROR;
+  for (const c of run.cases) {
+    if (c.status === "pending" || c.status === "running") {
+      c.status = "done";
+      c.ok = false;
+      c.error = CANCELLED_CASE_ERROR;
+    }
+  }
+  reconcileRunSummary(run);
+}
+
+function reconcileRunSummary(run: EvalRunSnapshot): void {
   let passed = 0;
   let failed = 0;
   for (const c of run.cases) {
@@ -536,3 +602,20 @@ export class EvalRunEmptyError extends Error {
     this.name = "EvalRunEmptyError";
   }
 }
+
+export class EvalRunUnknownError extends Error {
+  constructor(readonly runId: string) {
+    super(`Unknown eval run ${runId}`);
+    this.name = "EvalRunUnknownError";
+  }
+}
+
+export class EvalRunNotRunningError extends Error {
+  constructor(
+    readonly runId: string,
+    readonly status: EvalRunSnapshot["status"]
+  ) {
+    super(`Eval run ${runId} is not running (status: ${status})`);
+    this.name = "EvalRunNotRunningError";
+  }
+}