@cursor/july 0.1.16 → 0.1.18

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

@@ -18,6 +18,29 @@ import {
 
 export { RelayOffsetStore };
 
+/**
+ * Comment snapshot from scm-events compact metadata. Carries what the GitHub
+ * channel's `issue_comment` / `pull_request_review_comment` Zod schemas
+ * require so relayed comment wakes parse without re-fetching the comment.
+ */
+export type CursorScmCommentMeta = {
+  id: number;
+  body: string;
+  htmlUrl: string;
+  authorLogin?: string;
+  /**
+   * GitHub `user.type` ("User", "Bot", …). Carried onto the stubbed
+   * `comment.user` / `sender` so `isGitHubAppBotAuthor` keeps recognizing
+   * the agent's own comments on the relay path (self/bot-loop gate).
+   */
+  authorType?: string;
+  /** Review comments only. */
+  path?: string;
+  line?: number;
+  pullRequestReviewId?: number;
+  inReplyToId?: number;
+};
+
 /** PR snapshot from scm-events compact metadata (Sand-style; no raw body). */
 export type CursorScmPullRequestMeta = {
   number: number;
@@ -53,6 +76,11 @@ export interface CursorScmEvent {
    * stub a Zod-valid GitHub `pull_request` webhook body.
    */
   pullRequest?: CursorScmPullRequestMeta;
+  /**
+   * Comment snapshot when the backend saw `body.comment`. Enough to stub a
+   * Zod-valid `issue_comment` / `pull_request_review_comment` webhook body.
+   */
+  comment?: CursorScmCommentMeta;
   /** GitHub-side event time from the payload, when present. */
   occurredAtMs?: number;
 }
@@ -114,6 +142,8 @@ export function formatCursorScmEventLog(event: {
  * Minimal GitHub webhook body from an SCM-events metadata envelope.
  * When `pullRequest` has title + head/base refs+shas, emits a Zod-valid
  * `pull_request` object for `onPullRequest`; otherwise identity-only stubs.
+ * When `comment` is present, emits a Zod-valid `comment` object so relayed
+ * `issue_comment` / `pull_request_review_comment` deliveries dispatch.
  */
 export function scmMetadataToGitHubPayload(event: {
   repo: string;
@@ -121,6 +151,7 @@ export function scmMetadataToGitHubPayload(event: {
   prNumber?: number;
   prUrl?: string;
   pullRequest?: CursorScmPullRequestMeta;
+  comment?: CursorScmCommentMeta;
 }): Record<string, unknown> {
   const slash = event.repo.indexOf("/");
   const owner = slash === -1 ? "" : event.repo.slice(0, slash);
@@ -143,6 +174,42 @@ export function scmMetadataToGitHubPayload(event: {
   };
   payload.action = event.action;
 
+  const commentMeta = event.comment;
+  if (commentMeta !== undefined) {
+    const comment: Record<string, unknown> = {
+      id: commentMeta.id,
+      body: commentMeta.body,
+      html_url: commentMeta.htmlUrl,
+    };
+    if (commentMeta.authorLogin !== undefined) {
+      const author: Record<string, unknown> = {
+        login: commentMeta.authorLogin,
+      };
+      if (commentMeta.authorType !== undefined) {
+        // Without user.type the isGitHubAppBotAuthor gate fails open and the
+        // agent's own relayed comments could wake it again (bot loop).
+        author.type = commentMeta.authorType;
+      }
+      comment.user = author;
+      // The comment author is the closest thing the envelope has to the
+      // webhook sender; channels use it for self/bot-loop gates.
+      payload.sender = { ...author };
+    }
+    if (commentMeta.path !== undefined) {
+      comment.path = commentMeta.path;
+    }
+    if (commentMeta.line !== undefined) {
+      comment.line = commentMeta.line;
+    }
+    if (commentMeta.pullRequestReviewId !== undefined) {
+      comment.pull_request_review_id = commentMeta.pullRequestReviewId;
+    }
+    if (commentMeta.inReplyToId !== undefined) {
+      comment.in_reply_to_id = commentMeta.inReplyToId;
+    }
+    payload.comment = comment;
+  }
+
   const title = prMeta?.title;
   const headRef = prMeta?.headRef;
   const headSha = prMeta?.headSha;

package/src/internal/deploy-client.ts

@@ -529,6 +529,16 @@ export class AgentServeDeployClient {
     return `${this.backendUrl}${engineAlias}`;
   }
 
+  /**
+   * Stable remote MCP gateway URL for a deployment, on the user-API-key
+   * surface (headless / CLI, `agentkit login` credential). The gateway
+   * mints/refreshes engineAccess server-side and proxies `/v1/mcp` to the
+   * pod, so a signed-in client never sees a pod hostname or port token.
+   */
+  mcpGatewayUrl(teamId: number, slug: string): string {
+    return `${this.backendUrl}/internal/agent-serve/mcp/${teamId}/${encodeURIComponent(slug)}`;
+  }
+
   private async request(args: {
     method: "GET" | "POST" | "PUT" | "DELETE";
     path: string;

package/src/internal/discovery.ts

@@ -26,9 +26,12 @@ import {
   type AgentHostingOptions,
   type AgentProject,
   type AgentProjectInfo,
+  type AgentRuntime,
+  type BuiltinToolsConfig,
   type ChannelDefinition,
   type ConnectionDefinition,
   type ConnectionTransport,
+  cursorAccountServersHasMixedWildcard,
   DEFAULT_MODEL,
   type Diagnostic,
   type DiscoveredAB,
@@ -43,6 +46,7 @@ import {
   type InstructionsDefinition,
   MAX_RUNNING_TURNS_LIMIT,
   type ModelSetting,
+  normalizeCursorAccountServers,
   type ResolvedAgent,
   type ScheduleDefinition,
   type SeedFile,
@@ -54,6 +58,7 @@ import {
 import { registerAuthoredModuleLoaders } from "./authored-loaders.js";
 import { normalizePositiveInt } from "./bounded-int.js";
 import { getDefinitionKind } from "./brand.js";
+import { builtinTools } from "./builtin-tools/index.js";
 import { isValidCron } from "./cron.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import {
@@ -339,6 +344,13 @@ async function loadAgent(
   // warn that they exist.
   if (!options.isRoot) {
     await warnUnsupportedSubagentSlots(ctx, agentDir);
+    if (config?.builtinTools !== undefined) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, join(agentDir, "agent.ts")),
+        message: "builtinTools is not supported on subagents; ignoring.",
+      });
+    }
     return {
       name,
       ...(config?.description === undefined
@@ -368,11 +380,23 @@ async function loadAgent(
   // `send({ cloud })` merges it under cloudOverride for handoff sessions.
   const cloud = config?.cloud;
   const localCwd = resolveAgentCwd(ctx, config?.local?.cwd);
+  const localWorkspaceDir = resolveAgentCwd(ctx, config?.local?.workspaceDir);
+  const localSandbox = config?.local?.sandbox === true;
+  if (localCwd !== undefined && localWorkspaceDir !== undefined) {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: displayPath(ctx, join(agentDir, "agent.ts")),
+      message:
+        "local.workspaceDir pins every session to one directory, so local.cwd is unused. Drop one of them.",
+    });
+  }
   const local =
-    localCwd === undefined
+    localCwd === undefined && localWorkspaceDir === undefined && !localSandbox
       ? undefined
       : {
           cwd: localCwd,
+          workspaceDir: localWorkspaceDir,
+          sandbox: localSandbox,
         };
   const hosting = resolveHosting(ctx, agentDir, config?.hosting);
   const concurrency = resolveConcurrency(ctx, agentDir, config?.concurrency);
@@ -387,6 +411,8 @@ async function loadAgent(
     });
   }
 
+  appendBuiltinTools(ctx, agentDir, tools, config?.builtinTools, runtime);
+
   return {
     name,
     description: config?.description,
@@ -889,11 +915,10 @@ function connectionTransport(
   connection: ConnectionDefinition
 ): ConnectionTransport | undefined {
   if ("cursorAccount" in connection && connection.cursorAccount === true) {
+    const servers = normalizeCursorAccountServers(connection.servers);
     return {
       cursorAccount: true,
-      ...(connection.servers === undefined
-        ? {}
-        : { servers: connection.servers }),
+      ...(servers === undefined ? {} : { servers }),
     };
   }
   if ("agent" in connection && !isBlank(connection.agent)) {
@@ -1035,6 +1060,19 @@ async function loadConnections(
       });
       continue;
     }
+    if (
+      "cursorAccount" in connection &&
+      connection.cursorAccount === true &&
+      cursorAccountServersHasMixedWildcard(connection.servers)
+    ) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, entryPath),
+        message:
+          'Cursor account MCP connection `servers` cannot mix `"*"` with connector names. Use `"*"` / `["*"]` (or omit `servers`) for every connected server, or list only concrete connector names.',
+      });
+      continue;
+    }
     const transport = connectionTransport(connection);
     if (transport === undefined) {
       ctx.diagnostics.push({
@@ -1055,7 +1093,7 @@ async function loadConnections(
         severity: "error",
         path: displayPath(ctx, entryPath),
         message:
-          "Cursor account MCP connection `servers` must be a non-empty list of connector names (or omitted to expose every connected server).",
+          'Cursor account MCP connection `servers` must be a non-empty list of connector names, `"*"` / `["*"]` for every connected server, or omitted for the same all-connectors behavior.',
       });
       continue;
     }
@@ -1135,6 +1173,46 @@ async function warnUnsupportedSubagentSlots(
   }
 }
 
+/**
+ * Append enabled built-in tools after authored tools. Authored tools with
+ * the same name win; built-ins are server tools, so cloud runtimes get a
+ * warning instead of tools.
+ */
+function appendBuiltinTools(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  tools: DiscoveredTool[],
+  config: BuiltinToolsConfig | undefined,
+  runtime: AgentRuntime
+): void {
+  const builtin = builtinTools(config);
+  if (builtin.length === 0) {
+    return;
+  }
+  const agentPath = displayPath(ctx, join(agentDir, "agent.ts"));
+  if (runtime === "cloud") {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: agentPath,
+      message:
+        "builtinTools are in-process server tools and are not available on cloud agents; they are skipped.",
+    });
+    return;
+  }
+  const authored = new Set(tools.map((tool) => tool.name));
+  for (const tool of builtin) {
+    if (authored.has(tool.name)) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: agentPath,
+        message: `Authored tool "${tool.name}" shadows the built-in tool of the same name; the authored tool wins.`,
+      });
+      continue;
+    }
+    tools.push(tool);
+  }
+}
+
 function warnCloudRuntimeLimitations(
   ctx: DiscoveryContext,
   agentDir: string,

package/src/internal/distribution.ts

@@ -102,6 +102,8 @@ export const AUTHORING_ENTRY_FILES: ReadonlyArray<
   ["hooks", "hooks.js"],
   ["prompt", "prompt.js"],
   ["evals", "evals.js"],
+  ["evals/reporters", "evals/reporters.js"],
+  ["evals/loaders", "evals/loaders.js"],
   ["ab", "ab.js"],
   ["storage", "storage.js"],
   ["storage/file-kv", "storage-backends/file-kv.js"],

package/src/internal/eval-judge-model.ts

@@ -0,0 +1,148 @@
+/**
+ * The model call behind `t.judge.*`.
+ *
+ * Grading is completion-only in intent: the judge reads a prompt and returns a
+ * choice. It is nonetheless a real SDK session, and its prompt embeds output
+ * from the agent under test — attacker-controlled text in exactly the way a
+ * prompt injection needs. A reply that talks the judge into running a tool would
+ * do so on the machine running the eval CLI, under the runner's credentials.
+ *
+ * The session is therefore confined on every axis the SDK exposes:
+ *
+ * - `sandboxOptions.enabled` so any tool call the judge is talked into is
+ *   confined rather than run directly against the host.
+ * - `mcpServers: {}` so no MCP surface is reachable.
+ * - `settingSources: []` plus an empty temp `cwd`, so there is no repo to act on
+ *   and no ambient `AGENTS.md` / `.cursor` rule can steer a verdict.
+ *
+ * The prompt side is hardened separately: `evals/judge.ts` fences untrusted
+ * content behind a per-call boundary. Both halves matter — this one limits blast
+ * radius, that one removes the instruction channel.
+ *
+ * Grading also declines outright when the credential's backend and the SDK's
+ * backend disagree, rather than sending a key somewhere it was not minted for
+ * (see {@link assertJudgeBackendMatch}).
+ */
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { EvalJudgeCaller } from "../evals/judge.js";
+import { EvalJudgeUnavailableError } from "../evals/judge.js";
+import type { ModelSetting } from "../types.js";
+import {
+  DEFAULT_CURSOR_BACKEND_URL,
+  resolveApiKey,
+  SIGN_IN_HINT,
+} from "./cursor/credentials.js";
+
+/** Env override for the default judge model (below `evals.config.ts`). */
+export const EVAL_JUDGE_MODEL_ENV = "AGENTKIT_EVAL_JUDGE_MODEL";
+
+/**
+ * Backend the Cursor SDK will actually talk to.
+ *
+ * `Agent.create` takes a credential but no backend, so the SDK picks its own
+ * host from `CURSOR_API_BASE_URL`. Kept next to {@link assertJudgeBackendMatch}
+ * so the two stay in step if the SDK's resolution changes.
+ */
+function sdkBackendUrl(): string {
+  const configured = process.env.CURSOR_API_BASE_URL?.trim();
+  return trimTrailingSlash(
+    configured === undefined || configured === ""
+      ? DEFAULT_CURSOR_BACKEND_URL
+      : configured
+  );
+}
+
+function trimTrailingSlash(url: string): string {
+  return url.replace(/\/+$/, "");
+}
+
+/**
+ * Refuse to grade when the judge credential belongs to a different backend than
+ * the SDK will send it to.
+ *
+ * `resolveApiKey` resolves against `AGENT_SERVE_CURSOR_BACKEND_URL`, which the
+ * SDK does not read. When only that override is set, the key and the judge
+ * prompt — which embeds agent output — would go to the default host instead of
+ * the intended one. There is no backend field on `AgentOptions` to reconcile
+ * them, so the honest move is to decline rather than send a credential
+ * somewhere it was not minted for.
+ */
+export function assertJudgeBackendMatch(
+  credentialBackendUrl: string,
+  sdkBackend: string = sdkBackendUrl()
+): void {
+  const credentialBackend = trimTrailingSlash(credentialBackendUrl);
+  if (credentialBackend === sdkBackend) {
+    return;
+  }
+  throw new EvalJudgeUnavailableError(
+    `eval judge credential is scoped to ${credentialBackend}, but the Cursor SDK would send it to ${sdkBackend}. ` +
+      "Set CURSOR_API_BASE_URL to the same backend (the SDK does not read AGENT_SERVE_CURSOR_BACKEND_URL)."
+  );
+}
+
+/**
+ * Resolve the judge model, innermost first: per-call → per-eval →
+ * `evals.config.ts` → {@link EVAL_JUDGE_MODEL_ENV}.
+ */
+export function resolveJudgeModel(layers: {
+  call?: ModelSetting;
+  evalLevel?: ModelSetting;
+  config?: ModelSetting;
+  env?: string | undefined;
+}): ModelSetting | undefined {
+  const envModel = layers.env?.trim();
+  return (
+    layers.call ??
+    layers.evalLevel ??
+    layers.config ??
+    (envModel === undefined || envModel === "" ? undefined : envModel)
+  );
+}
+
+/**
+ * Ask the judge model for a grade.
+ *
+ * Throws {@link EvalJudgeUnavailableError} when no credentials are available so
+ * the runner can skip the eval visibly instead of reporting a spurious failure.
+ */
+export const callJudgeModel: EvalJudgeCaller = async ({ prompt, model }) => {
+  const resolved = await resolveApiKey();
+  if (resolved === undefined) {
+    throw new EvalJudgeUnavailableError(
+      `no Cursor credentials for the eval judge. ${SIGN_IN_HINT}`
+    );
+  }
+  assertJudgeBackendMatch(resolved.backendUrl);
+  // Imported lazily so a tree of fully deterministic evals never loads the SDK.
+  const { Agent } = await import("@cursor/sdk");
+  const cwd = await mkdtemp(join(tmpdir(), "agentkit-eval-judge-"));
+  const agent = await Agent.create({
+    apiKey: resolved.apiKey,
+    model: typeof model === "string" ? { id: model } : model,
+    // See the module comment: grading embeds untrusted agent output, so the
+    // session gets no MCP surface, no ambient settings, an empty working
+    // directory, and a sandbox around anything it does attempt.
+    mcpServers: {},
+    local: {
+      cwd,
+      settingSources: [],
+      sandboxOptions: { enabled: true },
+    },
+  });
+  try {
+    const run = await agent.send(prompt);
+    const result = await run.wait();
+    if (result.status === "error" || result.status === "cancelled") {
+      const detail = result.error?.message ?? result.result ?? result.status;
+      throw new Error(`eval judge run failed: ${detail}`);
+    }
+    return result.result ?? "";
+  } finally {
+    agent.close();
+    await rm(cwd, { recursive: true, force: true }).catch(() => undefined);
+  }
+};

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

@@ -173,6 +173,8 @@ export class EvalRunStore {
       summary: {
         passed: 0,
         failed: 0,
+        scored: 0,
+        skipped: 0,
         total: cases.length,
         done: 0,
       },
@@ -474,6 +476,9 @@ export class EvalRunStore {
     const alreadyCounted = c.status === "done";
     c.status = "done";
     c.ok = result.ok;
+    c.verdict = result.verdict;
+    c.skipReason = result.skipReason;
+    c.metadata = result.metadata;
     c.assertions = result.assertions;
     c.durationMs = result.durationMs;
     c.logs = result.logs;
@@ -502,11 +507,8 @@ export class EvalRunStore {
       return;
     }
     run.summary.done += 1;
-    if (result.ok) {
-      run.summary.passed += 1;
-    } else {
-      run.summary.failed += 1;
-    }
+    const verdict = result.verdict ?? (result.ok ? "passed" : "failed");
+    run.summary[verdict] = (run.summary[verdict] ?? 0) + 1;
   }
 }
 
@@ -539,18 +541,12 @@ function markCancelledRun(run: EvalRunSnapshot): void {
 }
 
 function reconcileRunSummary(run: EvalRunSnapshot): void {
-  let passed = 0;
-  let failed = 0;
+  const counts = { passed: 0, failed: 0, scored: 0, skipped: 0 };
   for (const c of run.cases) {
-    if (c.ok === true) {
-      passed += 1;
-    } else {
-      failed += 1;
-    }
+    counts[c.verdict ?? (c.ok === true ? "passed" : "failed")] += 1;
   }
   run.summary = {
-    passed,
-    failed,
+    ...counts,
     total: run.cases.length,
     done: run.cases.length,
   };