@cursor/july 0.1.88 → 0.1.89

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 }),
         };
       }),
     }));
@@ -707,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
         );
       }

package/src/internal/mcp-endpoint.ts

@@ -318,8 +318,9 @@ function buildConnectionBridgeMcpServer(
     }
     // The one tool path that never reaches `executeServerTool`, so it asks
     // the policy itself.
-    const answer = engine.bridgedCallAnswer({
+    const answer = await engine.bridgedCallAnswer({
       sessionId: sessionId ?? "",
+      connectionName,
       toolName: request.params.name,
     });
     if (answer.answered) {

package/src/internal/session-engine.ts

@@ -55,6 +55,7 @@ import {
   isHostOauthConnectionTransport,
   isSymbolicConnectionTransport,
   type JsonValue,
+  type McpToolAnnotations,
   type PendingApproval,
   type ReceiveInput,
   type ResolvedAgent,
@@ -2480,6 +2481,14 @@ export class SessionEngine {
       const decision = decideToolCall({
         dryRun: args.record.dryRun === true,
         effect: args.tool.definition.effect,
+        ...(args.tool.advertised === true
+          ? {
+              mcpTool: {
+                name: args.tool.name,
+                annotations: args.tool.annotations,
+              },
+            }
+          : {}),
         dryRunResult: args.tool.definition.dryRunResult,
         input: validation.value,
       });
@@ -2490,6 +2499,17 @@ export class SessionEngine {
         );
         return normalizeToolResult(decision.result);
       }
+      if (decision.kind === "refuse") {
+        this.logger(
+          `[session] tool ${args.tool.name} refused, effect unclassified (${toolCallId})`
+        );
+        // The coverage signal: a run reports how much of itself was runnable.
+        args.emit({
+          type: "action.effect_unclassified",
+          data: { callId: toolCallId, toolName: args.tool.name },
+        });
+        return toolErrorResult(decision.message);
+      }
       const needsGate = await evaluateNeedsApproval(
         args.tool.definition.needsApproval,
         validation.value
@@ -2778,6 +2798,9 @@ export class SessionEngine {
     const decision = decideToolCall({
       dryRun: record?.dryRun === true,
       effect: tool.definition.effect,
+      ...(tool.advertised === true
+        ? { mcpTool: { name: tool.name, annotations: tool.annotations } }
+        : {}),
       dryRunResult: tool.definition.dryRunResult,
       input: validation.value,
     });
@@ -2798,7 +2821,17 @@ export class SessionEngine {
             }).catch(() => {});
           };
     try {
-      if (decision.kind === "answer") {
+      if (decision.kind === "refuse") {
+        this.logger(
+          `[session] tool ${toolName} refused, effect unclassified (direct ${callId})`
+        );
+        emit?.({
+          type: "action.effect_unclassified",
+          data: { callId, toolName },
+        });
+        result = normalizeToolResult(toolErrorResult(decision.message));
+        isError = true;
+      } else if (decision.kind === "answer") {
         this.logger(
           `[session] tool ${toolName} answered by host (direct ${callId})`
         );
@@ -2896,28 +2929,75 @@ export class SessionEngine {
    * bridged reads too; resolving effects from a server's own listing is the
    * next unit's work.
    */
-  bridgedCallAnswer(args: {
+  async bridgedCallAnswer(args: {
     sessionId: string;
+    connectionName: string;
     toolName: string;
-  }): { answered: true; result: SDKCustomToolResult } | { answered: false } {
+  }): Promise<
+    { answered: true; result: SDKCustomToolResult } | { answered: false }
+  > {
     // Read off the in-flight turn's context rather than the session store:
     // the bridge already refuses a call with no active turn, so the record is
     // in memory. That keeps this free for the sessions that are not dry runs,
-    // which is every session today.
-    const record = this.activeToolContexts.get(args.sessionId)?.record;
+    // which is every session today — the listing below is only paid inside a
+    // dry run.
+    const context = this.activeToolContexts.get(args.sessionId);
+    if (context?.record.dryRun !== true) {
+      return { answered: false };
+    }
+    // A bridged tool carries no `defineTool`, so its effect comes from the
+    // server's own listing annotations; a tool the listing cannot classify
+    // refuses rather than being stubbed. A failed listing classifies nothing,
+    // which lands on the same refusal — never on a run.
+    const annotations = await this.bridgedToolAnnotations(
+      args.connectionName,
+      args.toolName
+    );
     const decision = decideToolCall({
-      dryRun: record?.dryRun === true,
+      dryRun: true,
       effect: undefined,
+      mcpTool: { name: args.toolName, annotations },
     });
     if (decision.kind === "run") {
       return { answered: false };
     }
+    if (decision.kind === "refuse") {
+      this.logger(
+        `[session] bridged tool ${args.toolName} refused, effect unclassified (${args.sessionId})`
+      );
+      context.emit({
+        type: "action.effect_unclassified",
+        data: {
+          callId: newToolCallId(args.toolName),
+          toolName: args.toolName,
+          connection: args.connectionName,
+        },
+      });
+      return { answered: true, result: toolErrorResult(decision.message) };
+    }
     this.logger(
       `[session] bridged tool ${args.toolName} answered by host (${args.sessionId})`
     );
     return { answered: true, result: normalizeToolResult(decision.result) };
   }
 
+  /**
+   * The bounded annotations a connection's listing declares for one tool, or
+   * undefined when the tool is unlisted, unannotated, or the listing fails —
+   * all of which the policy reads as unclassified, the refusing state.
+   */
+  private async bridgedToolAnnotations(
+    connectionName: string,
+    toolName: string
+  ): Promise<McpToolAnnotations | undefined> {
+    try {
+      const listed = await this.host.mcp.listTools(connectionName);
+      return listed.find((tool) => tool.name === toolName)?.annotations;
+    } catch {
+      return undefined;
+    }
+  }
+
   // ==========================================================================
   // Events: append, dispatch to channel handlers + hooks
   // ==========================================================================

package/src/internal/tool-policy.ts

@@ -10,6 +10,7 @@
  */
 
 import type {
+  McpToolAnnotations,
   ToolEffect,
   ToolEffectDeclaration,
   ToolExecuteResult,
@@ -20,7 +21,14 @@ export type ToolDecision =
   /** Run the tool body. */
   | { kind: "run" }
   /** Do not run it; return this to the model instead. */
-  | { kind: "answer"; result: ToolExecuteResult };
+  | { kind: "answer"; result: ToolExecuteResult }
+  /**
+   * Do not run it; fail the call with this message. Only ever produced in a
+   * dry run, for an MCP tool nothing classifies: stubbing it would let the
+   * run reach a confident conclusion from no data, and running it could leak
+   * a real write — refusing is the one failure that is loud.
+   */
+  | { kind: "refuse"; message: string };
 
 /** What a policy decision needs to know about the call. */
 export interface ToolCallFacts {
@@ -28,6 +36,14 @@ export interface ToolCallFacts {
   dryRun: boolean;
   /** The tool's declaration, if it made one. */
   effect: ToolEffectDeclaration<never> | undefined;
+  /**
+   * Present when the call targets a tool nobody authored — an advertised MCP
+   * passthrough or a bridged MCP call. Consulted only when {@link effect} is
+   * undeclared: the server's own annotations classify the call, and a tool
+   * they cannot classify refuses in a dry run instead of being stubbed as a
+   * write the way an undeclared authored tool is.
+   */
+  mcpTool?: { name: string; annotations?: McpToolAnnotations };
   /** What a stubbed write should answer with, if the tool supplied one. */
   dryRunResult?: ToolExecuteResult | ((input: never) => ToolExecuteResult);
   /**
@@ -64,11 +80,74 @@ export function resolveEffect(
   return declared === "read" ? "read" : "write";
 }
 
+/**
+ * The effect an MCP server's own annotations declare, fail-closed.
+ *
+ * `readOnlyHint: true` without `destructiveHint: true` is a read; either
+ * negative signal is a write; anything else — absent annotations, or
+ * annotations that carry no effect signal (a bare `title`) — is `undefined`,
+ * unclassified. Mirrors `@anysphere/mcp-core/mcp-tool-annotations`
+ * (`classifyMcpToolAnnotationRisk`), which this package cannot import (npm
+ * publish, workspace-only dependency); keep the two in sync.
+ */
+export function classifyAnnotationsEffect(
+  annotations: McpToolAnnotations | undefined
+): ToolEffect | undefined {
+  if (annotations === undefined) {
+    return undefined;
+  }
+  if (
+    annotations.destructiveHint !== true &&
+    annotations.readOnlyHint === true
+  ) {
+    return "read";
+  }
+  if (
+    annotations.readOnlyHint === false ||
+    annotations.destructiveHint === true
+  ) {
+    return "write";
+  }
+  return undefined;
+}
+
+/**
+ * What a dry run answers when nothing classifies an MCP tool. Deliberately
+ * reads as a strict API rather than disclosing the session's posture (see
+ * {@link ACKNOWLEDGED}), and names what is missing so the fix — the server
+ * annotating, or a server-side classification entry — is one step away.
+ */
+function unclassifiedRefusal(toolName: string): string {
+  return (
+    `Tool "${toolName}" is not available in this session: its MCP server ` +
+    `does not declare whether it reads or writes (readOnlyHint/` +
+    `destructiveHint), and no server-side classification exists for it, so ` +
+    `this session cannot tell whether calling it would change anything ` +
+    `outside the session. Use a tool that declares its effect.`
+  );
+}
+
 /** Decide what to do with one tool call. Pure; no I/O, no session state. */
 export function decideToolCall(facts: ToolCallFacts): ToolDecision {
   if (!facts.dryRun) {
     return { kind: "run" };
   }
+  if (facts.effect === undefined && facts.mcpTool !== undefined) {
+    const effect = classifyAnnotationsEffect(facts.mcpTool.annotations);
+    if (effect === undefined) {
+      return {
+        kind: "refuse",
+        message: unclassifiedRefusal(facts.mcpTool.name),
+      };
+    }
+    if (effect === "read") {
+      return { kind: "run" };
+    }
+    return {
+      kind: "answer",
+      result: dryRunAnswer(facts.dryRunResult, facts.input),
+    };
+  }
   if (resolveEffect(facts.effect, facts.input) === "read") {
     return { kind: "run" };
   }

package/src/types.ts

@@ -1439,6 +1439,17 @@ export type SessionEventPayload =
         parentCallId?: string;
       };
     }
+  | {
+      /**
+       * A dry-run call was refused because nothing classifies the tool's
+       * effect: the MCP server sent no readOnlyHint/destructiveHint and no
+       * server-side classification exists for it. The per-run count of these
+       * is the coverage signal — how much of a backtest was actually
+       * runnable, reported rather than assumed.
+       */
+      type: "action.effect_unclassified";
+      data: { callId: string; toolName: string; connection?: string };
+    }
   | {
       type: "subagent.called";
       data: { callId: string; name?: string; description?: string };
@@ -2620,6 +2631,14 @@ export interface DiscoveredTool {
    * classification can read them; absent is the fail-closed state.
    */
   annotations?: McpToolAnnotations;
+  /**
+   * True for a 1:1 MCP passthrough synthesized from an advertised
+   * connection's listing. The policy treats these differently from authored
+   * tools when nothing declares an effect: an undeclared authored tool is
+   * stubbed as a write in a dry run, an unclassifiable advertised tool is
+   * refused — see `decideToolCall`.
+   */
+  advertised?: true;
   /**
    * Agent tools: script body materialized under
    * `.agent-serve/tools/<name>.sh`.