@cursor/july 0.1.87 → 0.1.88

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,
@@ -1916,28 +1917,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 +1988,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 +2016,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 +2149,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 +2345,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,

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 {
@@ -2579,6 +2612,14 @@ 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;
   /**
    * Agent tools: script body materialized under
    * `.agent-serve/tools/<name>.sh`.
@@ -2840,8 +2881,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 +3017,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