@cursor/july 0.1.87 → 0.1.89

package/src/internal/session-engine.ts

@@ -35,6 +35,7 @@ import {
 } from "../files-backends/cursor-hosted.js";
 import {
   type AgentProject,
+  type AgentRuntime,
   type ApprovalDecision,
   type ArtifactListFilter,
   type ArtifactRecord,
@@ -54,6 +55,7 @@ import {
   isHostOauthConnectionTransport,
   isSymbolicConnectionTransport,
   type JsonValue,
+  type McpToolAnnotations,
   type PendingApproval,
   type ReceiveInput,
   type ResolvedAgent,
@@ -1916,28 +1918,29 @@ export class SessionEngine {
       agentRuntime: agent.runtime,
       cloudOverride: record.cloudOverride,
     });
-    // Fail closed: the SDK cannot enforce the built-in tool allowlist on
-    // cloud agents yet, and a restriction that silently does not apply is
-    // worse than a refused turn. Cloud-runtime agents already fail
-    // discovery; this guards hybrid agents' per-send cloud sessions.
-    if (runtime === "cloud" && agent.allowedTools !== undefined) {
+    // Fail closed: only the local harness can enforce the built-in tool
+    // allowlist, and a restriction that silently does not apply is worse
+    // than a refused turn. Non-local agents already fail discovery; this
+    // guards hybrid agents' per-send cloud sessions.
+    if (runtime !== "local" && agent.allowedTools !== undefined) {
       throw new Error(
-        `Agent "${agent.name}" declares a built-in tool allowlist (tools), which cannot be enforced on cloud turns yet. Refusing the cloud session rather than running it unrestricted.`
+        `Agent "${agent.name}" declares a built-in tool allowlist (tools), which cannot be enforced on ${runtime} turns. Refusing the session rather than running it unrestricted.`
       );
     }
     // Same fail-closed posture for per-session connection features:
     // advertised tools are server tools (in-process, local turns only) and
-    // per-session auth headers cannot reach a cloud VM's MCP config. A turn
-    // that silently runs without its per-session tools or identity is worse
-    // than a refused one. Cloud-runtime agents already fail discovery; this
-    // guards hybrid agents' per-send cloud sessions.
+    // per-session auth headers cannot reach a cloud VM's (or the Grok Bot
+    // harness's) MCP config. A turn that silently runs without its
+    // per-session tools or identity is worse than a refused one. Non-local
+    // agents already fail discovery; this guards hybrid agents' per-send
+    // cloud sessions.
     const perSessionConnection = agent.connections.find(
       (connection) =>
         connection.advertiseTools === true || connection.auth !== undefined
     );
-    if (runtime === "cloud" && perSessionConnection !== undefined) {
+    if (runtime !== "local" && perSessionConnection !== undefined) {
       throw new Error(
-        `Agent "${agent.name}" connection "${perSessionConnection.name}" uses advertiseTools/auth, which only run on local turns. Refusing the cloud session rather than running it without the connection's tools or identity.`
+        `Agent "${agent.name}" connection "${perSessionConnection.name}" uses advertiseTools/auth, which only run on local turns. Refusing the session rather than running it without the connection's tools or identity.`
       );
     }
     const mergedCloud =
@@ -1986,11 +1989,13 @@ export class SessionEngine {
           ? `\n\n${buildCloudMemorySection(this.project.name)}`
           : "";
         turnPrompt = `${preamble}${memorySection}\n\n${turnPrompt}`;
-      } else if (instructionsInvisibleToHarness) {
+      } else if (runtime === "local" && instructionsInvisibleToHarness) {
         // Local workspace whose AGENTS.md the harness will not load. With a
         // borrowed harness cwd, agent tool scripts live only in the durable
         // scaffold dir — embed bodies like cloud. Otherwise the catalog can
-        // reference on-disk paths under the harness cwd.
+        // reference on-disk paths under the harness cwd. Grokbot turns are
+        // excluded: their instructions ride the request's `instructions`
+        // field into the Sand system prompt instead.
         const includeScripts = this.hasBorrowedWorkspace(record);
         const preamble = buildAgentsMdContent(agent, { includeScripts });
         turnPrompt = `${preamble}\n\n${turnPrompt}`;
@@ -2012,7 +2017,17 @@ export class SessionEngine {
       ...(images !== undefined && images.length > 0 ? { images } : {}),
       ...(agent.model === undefined ? {} : { model: agent.model }),
       runtime,
+      agentName: agent.name,
       ...(mergedCloud === undefined ? {} : { cloud: mergedCloud }),
+      // The hosted Grok Bot harness reads no workspace AGENTS.md: grokbot
+      // turns carry the composed instructions into the hosted session,
+      // which surfaces them in the Sand system prompt. The box never sees
+      // the local session workspace, so agent-tool script bodies are
+      // always embedded — same rule as the cloud first-prompt preamble.
+      instructions:
+        runtime === "grokbot"
+          ? buildAgentsMdContent(agent, { includeScripts: true })
+          : undefined,
       ...(runtime === "cloud" && !isCursorHostedFilesAvailable()
         ? { agentServeAgent: this.project.name }
         : {}),
@@ -2135,10 +2150,15 @@ export class SessionEngine {
    * being omitted or failing the turn closed.
    */
   private buildMcpServers(
-    runtime: "local" | "cloud",
+    runtime: AgentRuntime,
     sessionId?: string,
     sessionAuth?: ReadonlyMap<string, Record<string, string>>
   ): Record<string, ConnectionTransport> {
+    // The Grok Bot harness manages its own MCP surface; authored
+    // connections are refused at discovery, so there is nothing to mount.
+    if (runtime === "grokbot") {
+      return {};
+    }
     // Advertised connections surface as named server tools instead of an
     // attached MCP server (each tool appears exactly once), so they are
     // excluded here alongside hostOnly.
@@ -2326,6 +2346,12 @@ export class SessionEngine {
         ...(tool.outputSchema === undefined
           ? {}
           : { outputSchema: tool.outputSchema }),
+        // Same pinned-SDK carry for `SDKCustomTool.annotations`: an advertised
+        // MCP passthrough's server-declared hints (bounded at listing time)
+        // ride into the harness listing once the dependency bumps.
+        ...(tool.annotations === undefined
+          ? {}
+          : { annotations: tool.annotations }),
         execute: async (args, context) => {
           return this.executeServerTool({
             tool,
@@ -2455,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,
       });
@@ -2465,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
@@ -2753,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,
     });
@@ -2773,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})`
         );
@@ -2871,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

@@ -95,9 +95,14 @@ export const DEFAULT_MODEL: ModelSetting = {
 
 /**
  * Where turns execute. `"local"` (default) uses the Cursor SDK local
- * harness on this machine; `"cloud"` runs on Cursor cloud agents.
+ * harness on this machine; `"cloud"` runs on Cursor cloud agents;
+ * `"grokbot"` runs on Cursor's hosted Grok Bot (Sand) harness with the
+ * account's own computer (box) — the SDK is a thin client over the
+ * `/v0/grokbot` session API, and the user-visible reply is whatever the
+ * agent delivers through its SendToUser tool. The hosted harness picks
+ * the model; {@link AgentConfig.model} does not apply to grokbot turns.
  */
-export type AgentRuntime = "local" | "cloud";
+export type AgentRuntime = "local" | "cloud" | "grokbot";
 
 /**
  * Cloud-only options forwarded to the Cursor SDK's `cloud` field on
@@ -473,11 +478,39 @@ export interface HostMcpRegistry {
   ): Promise<HostMcpCallResult>;
 }
 
+/**
+ * MCP spec tool annotations (`Tool.annotations`, 2025-03-26 revision).
+ *
+ * A closed type on purpose: these are exactly the fields listing-time
+ * bounding keeps, so the type matches what a reader can ever see — and the
+ * hints are behavioral, so a misspelled or wrong-typed key must not
+ * masquerade as a declaration.
+ */
+export interface McpToolAnnotations {
+  /** Human-readable display name for the tool, length-capped at listing. */
+  title?: string;
+  /** The tool does not modify its environment. */
+  readOnlyHint?: boolean;
+  /** The tool may perform destructive updates (meaningful when not read-only). */
+  destructiveHint?: boolean;
+  /** Repeated calls with the same arguments have no additional effect. */
+  idempotentHint?: boolean;
+  /** The tool may interact with an open world of external entities. */
+  openWorldHint?: boolean;
+}
+
 export interface HostMcpToolInfo {
   name: string;
   description?: string;
   inputSchema?: JsonObject;
   outputSchema?: JsonObject;
+  /**
+   * MCP spec tool annotations, bounded at listing time to the
+   * {@link McpToolAnnotations} fields. Untrusted server hints — consumers
+   * that classify on them must fail closed when absent, and absent is
+   * exactly what a server that declares nothing produces.
+   */
+  annotations?: McpToolAnnotations;
 }
 
 export interface HostMcpCallResult {
@@ -1406,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 };
@@ -2579,6 +2623,22 @@ export interface DiscoveredTool {
    * declares nothing, which a dry run treats as a write.
    */
   effect?: ToolEffect | "dynamic";
+  /**
+   * MCP spec tool annotations, present only on advertised MCP passthroughs
+   * whose server declared them (see {@link HostMcpToolInfo.annotations}).
+   * Authored tools declare {@link effect} instead. Untrusted hints,
+   * propagated so the harness listing carries them and so effect
+   * 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`.
@@ -2840,8 +2900,22 @@ export interface RunnerTurnRequest {
   images?: Array<{ data: string; mimeType: string }>;
   model?: ModelSetting;
   runtime: AgentRuntime;
+  /**
+   * The agent's display name. Grokbot turns address the caller's hosted
+   * Grok Bot agent of this name: every SDK session of one agent forwards
+   * into the same hosted agent and conversation.
+   */
+  agentName?: string;
   /** Cloud options when {@link runtime} is `"cloud"`. */
   cloud?: AgentCloudOptions;
+  /**
+   * Composed instructions ({@link ResolvedAgent.instructions}) for runtimes
+   * whose harness cannot read the workspace `AGENTS.md` — grokbot turns
+   * carry them into the hosted session so they reach the Sand system
+   * prompt. Local turns read the materialized workspace instead and leave
+   * this unset.
+   */
+  instructions?: string;
   /**
    * defineAgent directory slug for personal-key cloud creates. Injected
    * by the engine — not part of authored {@link AgentCloudOptions}.
@@ -2962,6 +3036,14 @@ export interface ServeOptions {
    * SSO/Okta proxy in front of the host).
    */
   allowAnonymousCursorGithub?: boolean;
+  /**
+   * Allow `--allow-anonymous` together with a `runtime: "grokbot"` mount.
+   * Off by default: grokbot turns execute on the signed-in account's hosted
+   * Grok Bot computer, so an anonymous caller could drive Shell and other
+   * box tools there. Set it only when the network boundary already
+   * authenticates callers (e.g. an SSO/Okta proxy in front of the host).
+   */
+  allowAnonymousGrokbot?: boolean;
   /**
    * Route `githubChannel({ cursorAccount })` API calls through the Cursor
    * backend's GitHub forwarder (`/v0/github-proxy`) instead of minting raw