@cursor/july 0.1.87 → 0.1.89

package/src/internal/cli-deploy.ts

@@ -5,13 +5,15 @@
  *
  * All intelligence is server-side (backend/server/src/agentServe/); these
  * handlers resolve parameters (credentials, team, slug, the project's
- * `hosting` manifest block), call the management API through
- * `deploy-client.ts`, poll status, and render.
+ * `hosting` / `architecture` manifest block), call the v1 agent-serve or
+ * v2 agentkit management API through `deploy-client.ts`, poll status, and
+ * render.
  */
 
 import { basename, resolve } from "node:path";
 import { isPublicEndpointPolicy } from "../channels.js";
 import {
+  type AgentArchitecture,
   type AgentHostingOptions,
   isCursorAccountTransport,
 } from "../types.js";
@@ -24,18 +26,21 @@ import {
 import { authorizeCursorAccountConnectors } from "./cursor-account-mcp-auth.js";
 import { readDeployTemplate } from "./cursor-agent-template.js";
 import {
+  type AgentkitDeployAccepted,
+  type AgentkitDeployStatus,
   AgentServeDeployClient,
   type DeleteAccepted,
   type DeployAccepted,
   DeployApiError,
   type Deployment,
   type DeploymentDetail,
-  type DeploymentStatus,
+  type DeploymentProgress,
   type DeploySource,
   deploymentServiceAccountId,
   type SecretInfo,
   type StopAccepted,
   slugFromDirectoryName,
+  TERMINAL_AGENTKIT_DEPLOY_STATUSES,
   TERMINAL_DEPLOY_STATUSES,
   validateDeploymentSlug,
 } from "./deploy-client.js";
@@ -648,6 +653,19 @@ async function deployOne(
     );
   }
 
+  if (manifest?.architecture === "v2") {
+    if (!ctx.json) {
+      ctx.err("  architecture: v2\n");
+    }
+    return deployOneAgentkit(ctx, extras, {
+      slug,
+      gitRepoUrl,
+      gitRef,
+      agentPath,
+      repositories: options.cursorEventsRepos,
+    });
+  }
+
   // Today's only source shape: the control plane builds from a git ref.
   // See DeploySource for the artifact seam.
   const source: DeploySource = {
@@ -702,7 +720,9 @@ async function deployOne(
 
   let detail: DeploymentDetail;
   try {
-    detail = await pollUntil(ctx, slug, TERMINAL_DEPLOY_STATUSES);
+    detail = await pollUntil(ctx, slug, TERMINAL_DEPLOY_STATUSES, () =>
+      ctx.client.getDeployment({ teamId: ctx.teamId, slug })
+    );
   } catch (error) {
     return renderApiError(error, ctx.err);
   }
@@ -756,6 +776,85 @@ async function deployOne(
   return 0;
 }
 
+/**
+ * `architecture: "v2"` deploy: POST `/internal/agentkit/deployments` and
+ * poll the matching GET. The v2 accept path starts freeze bake; it does
+ * not mint an engine alias or alias token.
+ */
+async function deployOneAgentkit(
+  ctx: DeployCliContext,
+  extras: { jsonCollect?: unknown[] } | undefined,
+  args: {
+    slug: string;
+    gitRepoUrl: string;
+    gitRef: string | undefined;
+    agentPath: string | undefined;
+    repositories: string[] | undefined;
+  }
+): Promise<number> {
+  const { slug } = args;
+  let accepted: AgentkitDeployAccepted;
+  try {
+    accepted = await ctx.client.deployAgentkit({
+      teamId: ctx.teamId,
+      slug,
+      gitRepoUrl: args.gitRepoUrl,
+      gitRef: args.gitRef,
+      agentPath: args.agentPath,
+      repositories: args.repositories,
+    });
+  } catch (error) {
+    return renderApiError(error, ctx.err);
+  }
+
+  if (ctx.noWait) {
+    if (extras?.jsonCollect !== undefined) {
+      extras.jsonCollect.push(accepted);
+    } else if (ctx.json) {
+      ctx.out(`${JSON.stringify(accepted, null, 2)}\n`);
+    } else {
+      ctx.out(
+        `Deploy accepted: ${slug} (team ${ctx.teamId}, v2)\n` +
+          `  application: ${accepted.applicationId}\n` +
+          `  release:     ${accepted.releaseId}\n`
+      );
+    }
+    return 0;
+  }
+
+  let detail: AgentkitDeployStatus;
+  try {
+    detail = await pollUntil(ctx, slug, TERMINAL_AGENTKIT_DEPLOY_STATUSES, () =>
+      ctx.client.getAgentkitDeploy({ teamId: ctx.teamId, slug })
+    );
+  } catch (error) {
+    return renderApiError(error, ctx.err);
+  }
+
+  if (extras?.jsonCollect !== undefined) {
+    extras.jsonCollect.push(detail);
+    return detail.status === "running" ? 0 : 1;
+  }
+
+  if (ctx.json) {
+    ctx.out(`${JSON.stringify(detail, null, 2)}\n`);
+    return detail.status === "running" ? 0 : 1;
+  }
+
+  if (detail.status !== "running") {
+    ctx.err(`Deployment ${slug} ended ${detail.status}\n`);
+    return 1;
+  }
+  ctx.out(
+    `Deployed ${slug} (team ${ctx.teamId})\n` +
+      `  status:       running\n` +
+      `  architecture: v2\n` +
+      `  application:  ${detail.applicationId}\n` +
+      `  release:      ${detail.releaseId}\n`
+  );
+  return 0;
+}
+
 /**
  * Post-deploy connector authorization for `cursorAccount` connections: the
  * agent's connectors execute with tokens owned by the deployment's service
@@ -845,6 +944,7 @@ async function runPostDeployConnectorAuth(
 
 interface DeployManifest {
   hosting: AgentHostingOptions | undefined;
+  architecture: AgentArchitecture | undefined;
   /** `cursorAccount` connections declared by the agent. */
   cursorAccountConnections: Array<{
     name: string;
@@ -872,6 +972,7 @@ async function readDeployManifest(dir: string): Promise<DeployManifest> {
   const project = await loadAgentProject(dir);
   return {
     hosting: project.agent.hosting,
+    architecture: project.agent.architecture,
     cursorAccountConnections: project.agent.connections.flatMap((connection) =>
       isCursorAccountTransport(connection.transport)
         ? [{ name: connection.name, servers: connection.transport.servers }]
@@ -1102,7 +1203,9 @@ export async function cmdStop(
   }
   let detail: DeploymentDetail;
   try {
-    detail = await pollUntil(ctx, slug, new Set(["stopped"]));
+    detail = await pollUntil(ctx, slug, new Set(["stopped"]), () =>
+      ctx.client.getDeployment({ teamId: ctx.teamId, slug })
+    );
   } catch (error) {
     return renderApiError(error, ctx.err);
   }
@@ -1517,17 +1620,24 @@ export function createLineReader(
  * status so create → checkout → start is visible. Throws DeployApiError
  * on request failures or timeout.
  */
-async function pollUntil(
+async function pollUntil<
+  T extends {
+    status: string;
+    progress?: DeploymentProgress;
+    statusMessage?: string | null;
+  },
+>(
   ctx: DeployCliContext,
   slug: string,
-  terminal: ReadonlySet<DeploymentStatus>
-): Promise<DeploymentDetail> {
+  terminal: ReadonlySet<T["status"]>,
+  fetchDetail: () => Promise<T>
+): Promise<T> {
   const startedAt = Date.now();
   const tty = process.stderr.isTTY === true;
   let lastLabel: string | undefined;
   let sawProgress = false;
 
-  const report = (detail: DeploymentDetail): void => {
+  const report = (detail: T): void => {
     if (ctx.json) {
       return;
     }
@@ -1548,12 +1658,10 @@ async function pollUntil(
   };
 
   for (;;) {
-    const detail = await ctx.client
-      .getDeployment({ teamId: ctx.teamId, slug })
-      .catch((error: unknown) => {
-        finishProgressLine();
-        throw error;
-      });
+    const detail = await fetchDetail().catch((error: unknown) => {
+      finishProgressLine();
+      throw error;
+    });
     report(detail);
     if (terminal.has(detail.status)) {
       finishProgressLine();

package/src/internal/cli-docs.ts

@@ -162,6 +162,17 @@ async function handleDocsRequest(
     res.end();
     return;
   }
+  if (pathname === "/v1/health" || pathname === "/v1/health/") {
+    // Same path the corp ALB / ECS check uses on agent-serve. Static docs
+    // has no runtimes; liveness is "the process accepted HTTP".
+    res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+    if (method === "HEAD") {
+      res.end();
+      return;
+    }
+    res.end(JSON.stringify({ ok: true }));
+    return;
+  }
   let requestPath = "";
   if (pathname === "/docs" || pathname === "/docs/") {
     requestPath = "";

package/src/internal/cloud-merge.ts

@@ -31,11 +31,21 @@ export function mergeCloudOptions(args: {
 
 /**
  * Session turn runtime: a per-session `cloud` attach forces cloud even when
- * the agent defaults to local (chat server tools + Drive handoff).
+ * the agent defaults to local (chat server tools + Drive handoff). A
+ * grokbot agent refuses the attach — silently moving its session onto a
+ * cloud VM would swap the harness (and the box) out from under it.
  */
 export function resolveSessionRuntime(args: {
   agentRuntime: AgentRuntime;
   cloudOverride: AgentCloudOptions | undefined;
 }): AgentRuntime {
-  return args.cloudOverride !== undefined ? "cloud" : args.agentRuntime;
+  if (args.cloudOverride === undefined) {
+    return args.agentRuntime;
+  }
+  if (args.agentRuntime === "grokbot") {
+    throw new Error(
+      'Grok Bot sessions cannot attach cloud agents: per-session `cloud` options are not supported on runtime: "grokbot". Refusing the session rather than moving it onto a cloud VM.'
+    );
+  }
+  return "cloud";
 }

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

@@ -21,7 +21,11 @@ import {
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { bearerAuth } from "../../channels.js";
-import type { AgentProject, AuthPolicy } from "../../types.js";
+import type {
+  AgentProject,
+  AuthPolicy,
+  McpToolAnnotations,
+} from "../../types.js";
 import { isCursorAccountTransport } from "../../types.js";
 import { probeConnectorAuthUrls } from "../cursor-account-mcp-auth.js";
 import { LOG_PREFIX } from "../distribution.js";
@@ -151,6 +155,8 @@ interface CatalogTool {
   inputSchema: Record<string, unknown>;
   /** Present only when the connector's server declares one. */
   outputSchema?: Record<string, unknown>;
+  /** MCP spec annotations, present only when the server declared them. */
+  annotations?: McpToolAnnotations;
 }
 
 interface Catalog {
@@ -335,6 +341,11 @@ export class CursorAccountMcpBridge {
           ...(tool.outputSchema === undefined
             ? {}
             : { outputSchema: tool.outputSchema }),
+          // Already bounded to the MCP-spec fields at the backend-client
+          // parse; absent stays absent so classifiers fail closed.
+          ...(tool.annotations === undefined
+            ? {}
+            : { annotations: tool.annotations }),
         })),
       };
     });
@@ -510,6 +521,9 @@ function buildCatalog(servers: AccountMcpServer[]): Catalog {
         ...(tool.outputSchema === undefined
           ? {}
           : { outputSchema: tool.outputSchema }),
+        ...(tool.annotations === undefined
+          ? {}
+          : { annotations: tool.annotations }),
       };
       tools.push(entry);
       byExposedName.set(entry.exposedName, entry);

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

@@ -15,6 +15,8 @@
 
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
+import type { McpToolAnnotations } from "../../types.js";
+import { boundedToolAnnotations } from "../mcp-host.js";
 
 const CLIENT_VERSION = "agent-serve-0.1.0";
 const EXCHANGE_PATH = "/auth/exchange_user_api_key";
@@ -85,6 +87,8 @@ const mcpToolSchema = z.object({
   inputSchema: z.unknown().optional(),
   /** Flat JSON-string output schema (`output_schema_json` on the proto). */
   outputSchemaJson: z.string().optional(),
+  /** Flat JSON-string MCP annotations (`annotations_json` on the proto). */
+  annotationsJson: z.string().optional(),
 });
 
 const getAvailableMcpServersResponseSchema = z.object({
@@ -154,6 +158,13 @@ export interface AccountMcpTool {
    * matching the optional MCP `Tool.outputSchema` field.
    */
   outputSchema?: Record<string, unknown>;
+  /**
+   * MCP spec tool annotations as the connector's server reported them,
+   * bounded to the spec fields at parse time. Absent stays absent —
+   * untrusted hints, and the fail-closed signal for consumers that classify
+   * on them (dry-run effect resolution).
+   */
+  annotations?: McpToolAnnotations;
 }
 
 export interface AccountMcpServer {
@@ -331,11 +342,13 @@ export class CursorBackendClient {
       status: server.status,
       tools: (server.tools ?? []).map((tool) => {
         const outputSchema = parseOutputSchemaJson(tool.outputSchemaJson);
+        const annotations = parseAnnotationsJson(tool.annotationsJson);
         return {
           name: tool.name,
           description: tool.description ?? "",
           inputSchema: normalizeInputSchema(tool.inputSchema),
           ...(outputSchema === undefined ? {} : { outputSchema }),
+          ...(annotations === undefined ? {} : { annotations }),
         };
       }),
     }));
@@ -507,6 +520,10 @@ export class CursorBackendClient {
     return parseRpcResponse(method, second);
   }
 
+  /**
+   * Serve a cached access token for the account, exchanging the API key
+   * when none is cached or it is near expiry.
+   */
   private getAccessToken(): Promise<string> {
     if (
       this.token !== undefined &&
@@ -703,6 +720,26 @@ function parseOutputSchemaJson(
     : undefined;
 }
 
+/**
+ * Parse the flat JSON-string annotations off the wire and bound them to the
+ * MCP-spec fields. Malformed or non-object payloads behave like absent ones,
+ * so readers fail closed.
+ */
+function parseAnnotationsJson(
+  annotationsJson: string | undefined
+): McpToolAnnotations | undefined {
+  if (annotationsJson === undefined) {
+    return undefined;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(annotationsJson);
+  } catch {
+    return undefined;
+  }
+  return boundedToolAnnotations(parsed);
+}
+
 type McpResultJson = z.infer<typeof mcpResultSchema>;
 
 function toCallResult(result: McpResultJson): AccountMcpCallResult {

package/src/internal/deploy-client.ts

@@ -1,6 +1,7 @@
 /**
  * Thin client for the Agent Serve deployment management API
- * (`/internal/agent-serve/deployments` on the Cursor backend). Pure
+ * (`/internal/agent-serve/deployments` on the Cursor backend) and the v2
+ * AgentSDK accept path (`/internal/agentkit/deployments`). Pure
  * request/response + error mapping — no console I/O, no polling loops;
  * rendering lives in `cli-deploy.ts`.
  *
@@ -212,6 +213,48 @@ export interface StopAccepted {
 
 export type DeleteAccepted = StopAccepted;
 
+/**
+ * `POST /internal/agentkit/deployments` 202 body. Distinct from v1
+ * {@link DeployAccepted}: the v2 control plane returns catalog ids, not
+ * an engine alias or one-shot alias token.
+ */
+export interface AgentkitDeployAccepted {
+  applicationId: string;
+  releaseId: string;
+  status: string;
+}
+
+/** Customer-visible v2 deploy status (`GET /internal/agentkit/deployments/:slug`). */
+export type AgentkitCustomerStatus =
+  | "pending"
+  | "deploying"
+  | "running"
+  | "failed"
+  | "stopped";
+
+export type AgentkitDeployProgress =
+  | "queued"
+  | "creating"
+  | "building"
+  | "starting"
+  | "finalizing"
+  | "running"
+  | "failed"
+  | "stopped";
+
+export interface AgentkitDeployStatus {
+  applicationId: string;
+  releaseId: string;
+  slug: string;
+  teamId: number;
+  status: AgentkitCustomerStatus;
+  progress: AgentkitDeployProgress;
+  statusMessage: string | null;
+}
+
+export const TERMINAL_AGENTKIT_DEPLOY_STATUSES: ReadonlySet<AgentkitCustomerStatus> =
+  new Set(["running", "failed", "stopped"]);
+
 /** One secret's metadata from the list endpoint — names only, never values. */
 export interface SecretInfo {
   name: string;
@@ -260,6 +303,35 @@ const deployAcceptedSchema = z
   })
   .passthrough();
 
+const agentkitDeployAcceptedSchema = z
+  .object({
+    applicationId: z.string().min(1),
+    releaseId: z.string().min(1),
+    status: z.string(),
+  })
+  .passthrough();
+
+const agentkitDeployStatusSchema = z
+  .object({
+    applicationId: z.string().min(1),
+    releaseId: z.string().min(1),
+    slug: z.string().min(1),
+    teamId: z.number(),
+    status: z.enum(["pending", "deploying", "running", "failed", "stopped"]),
+    progress: z.enum([
+      "queued",
+      "creating",
+      "building",
+      "starting",
+      "finalizing",
+      "running",
+      "failed",
+      "stopped",
+    ]),
+    statusMessage: z.string().nullable(),
+  })
+  .passthrough();
+
 const deploymentSchema = z.object({
   id: z.number(),
   slug: z.string(),
@@ -482,6 +554,54 @@ export class AgentServeDeployClient {
     return deployAcceptedSchema.parse(raw);
   }
 
+  /**
+   * Create or redeploy onto the v2 control plane
+   * (`POST /internal/agentkit/deployments`). 202 means accepted; poll
+   * {@link getAgentkitDeploy} until a terminal status.
+   */
+  async deployAgentkit(args: {
+    teamId: number;
+    slug: string;
+    gitRepoUrl: string;
+    gitRef?: string;
+    agentPath?: string;
+    repositories?: string[];
+  }): Promise<AgentkitDeployAccepted> {
+    const slugError = validateDeploymentSlug(args.slug);
+    if (slugError !== undefined) {
+      throw new DeployApiError(slugError, 400);
+    }
+    const raw = await this.request({
+      method: "POST",
+      path: "/internal/agentkit/deployments",
+      body: {
+        teamId: args.teamId,
+        slug: args.slug,
+        gitRepoUrl: args.gitRepoUrl,
+        gitRef: args.gitRef,
+        agentPath: args.agentPath,
+        repositories:
+          args.repositories !== undefined && args.repositories.length > 0
+            ? args.repositories
+            : undefined,
+      },
+      context: { verb: "deploy", slug: args.slug },
+    });
+    return agentkitDeployAcceptedSchema.parse(raw);
+  }
+
+  async getAgentkitDeploy(args: {
+    teamId: number;
+    slug: string;
+  }): Promise<AgentkitDeployStatus> {
+    const raw = await this.request({
+      method: "GET",
+      path: `/internal/agentkit/deployments/${encodeURIComponent(args.slug)}?teamId=${args.teamId}`,
+      context: { verb: "get deployment", slug: args.slug },
+    });
+    return agentkitDeployStatusSchema.parse(raw);
+  }
+
   async listDeployments(args: { teamId: number }): Promise<Deployment[]> {
     const raw = await this.request({
       method: "GET",
@@ -756,7 +876,7 @@ function mapErrorResponse(
       // (api2 vs api.cursor.com), not a missing deployment / closed gate.
       if (/Route \S+ not found/i.test(bodyText)) {
         return new DeployApiError(
-          `Agent Serve deploy API not found on this host — use the default api.cursor.com (unset CURSOR_API_BASE_URL), or point CURSOR_API_BASE_URL at a backend that mounts /internal/agent-serve/*.`,
+          `Agent Serve deploy API not found on this host — use the default api.cursor.com (unset CURSOR_API_BASE_URL), or point CURSOR_API_BASE_URL at a backend that mounts /internal/agent-serve/* and /internal/agentkit/*.`,
           404
         );
       }