@cursor/july 0.1.86 → 0.1.88

package/src/internal/grokbot/runner.ts

@@ -0,0 +1,361 @@
+/**
+ * The grokbot runtime's remote client — a thin client like `"cloud"`.
+ * Turns execute on Cursor's hosted Grok Bot (Sand) harness (the Temporal
+ * turn workflow and the account's own computer), reached through the
+ * public `/v0/grokbot` session API.
+ *
+ * Sand delivery contract, preserved end to end: only content the agent
+ * delivers through SendToUser becomes the user-visible reply. The hosted
+ * transcript exposes those deliveries as `send-message` entries; the
+ * agent's internal monologue never appears in the transcript, so it can
+ * never leak into the session reply.
+ */
+
+import { randomUUID } from "node:crypto";
+import type { RunnerTurnRequest, TurnOutcome } from "../../types.js";
+import { cursorBackendUrl } from "../cursor/credentials.js";
+import type { AgentRunner } from "./../sdk-runner.js";
+
+export interface GrokBotRunnerOptions {
+  /** Cursor API key. Defaults to the `CURSOR_API_KEY` environment variable. */
+  apiKey?: string;
+  /** Test seam. Defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+  /** Test seam. Defaults to {@link cursorBackendUrl}. */
+  backendUrl?: string;
+  /** Test seam. Poll interval while a turn runs. */
+  pollIntervalMs?: number;
+  /** Test seam. Hard turn deadline. */
+  turnTimeoutMs?: number;
+}
+
+/** One transcript entry as `/v0/grokbot/sessions/:id/entries` exposes it. */
+export interface GrokBotEntry {
+  seq: string;
+  updatedSeq: string;
+  kind: string;
+  role?: string;
+  text?: string;
+  createdAtMs: number;
+}
+
+interface GrokBotTurnStatus {
+  idle: boolean;
+  inFlight: boolean;
+  queued: number;
+}
+
+interface EntriesPage {
+  entries: GrokBotEntry[];
+  latestUpdatedSeq: string;
+  turn: GrokBotTurnStatus;
+}
+
+interface HostedAgent {
+  /** The `/v0/grokbot` session id (the hosted agent's durable id). */
+  remoteId: string;
+  /** Transcript cursor: newest `updatedSeq` this client has consumed. */
+  lastUpdatedSeq: bigint;
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 750;
+const DEFAULT_TURN_TIMEOUT_MS = 20 * 60 * 1000;
+
+/**
+ * Idle polls required after a send before the turn is considered settled
+ * when the workflow never reported busy — covers the window between the
+ * accepted dispatch and the workflow picking the signal up.
+ */
+const MIN_IDLE_POLLS_WITHOUT_BUSY = 4;
+
+class GrokBotApiError extends Error {
+  constructor(
+    readonly status: number,
+    readonly path: string,
+    body: string
+  ) {
+    super(
+      `Grok Bot API ${path} failed (HTTP ${status}): ${body.slice(0, 300)}`
+    );
+    this.name = "GrokBotApiError";
+  }
+}
+
+/** Minimal `/v0/grokbot` client: bearer API key, JSON in/out. */
+class GrokBotApiClient {
+  private readonly fetchImpl: typeof fetch;
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+
+  constructor(options: GrokBotRunnerOptions) {
+    this.fetchImpl = options.fetchImpl ?? fetch;
+    this.baseUrl = (options.backendUrl ?? cursorBackendUrl()).replace(
+      /\/$/,
+      ""
+    );
+    const apiKey = options.apiKey ?? process.env.CURSOR_API_KEY;
+    if (apiKey === undefined || apiKey === "") {
+      throw new Error(
+        'runtime: "grokbot" needs a Cursor API key (CURSOR_API_KEY or agent-sdk login) to reach the hosted Grok Bot harness.'
+      );
+    }
+    this.apiKey = apiKey;
+  }
+
+  private async request<T>(args: {
+    method: string;
+    path: string;
+    body?: unknown;
+  }): Promise<T> {
+    const headers: Record<string, string> = {
+      authorization: `Bearer ${this.apiKey}`,
+    };
+    if (args.body !== undefined) {
+      headers["content-type"] = "application/json";
+    }
+    const response = await this.fetchImpl(`${this.baseUrl}${args.path}`, {
+      method: args.method,
+      headers,
+      body: args.body === undefined ? undefined : JSON.stringify(args.body),
+    });
+    if (!response.ok) {
+      throw new GrokBotApiError(
+        response.status,
+        args.path,
+        await response.text().catch(() => "")
+      );
+    }
+    return (await response.json()) as T;
+  }
+
+  async createSession(args: {
+    name: string;
+    instructions: string | undefined;
+  }): Promise<{ id: string; latestUpdatedSeq: string }> {
+    return await this.request({
+      method: "POST",
+      path: "/v0/grokbot/sessions",
+      body: { name: args.name, instructions: args.instructions },
+    });
+  }
+
+  async sendMessage(args: {
+    sessionId: string;
+    text: string;
+  }): Promise<{ messageId: string; delivery: string }> {
+    return await this.request({
+      method: "POST",
+      path: `/v0/grokbot/sessions/${args.sessionId}/messages`,
+      body: { text: args.text, messageId: randomUUID() },
+    });
+  }
+
+  async listEntries(args: {
+    sessionId: string;
+    afterUpdatedSeq: bigint;
+  }): Promise<EntriesPage> {
+    return await this.request({
+      method: "GET",
+      path: `/v0/grokbot/sessions/${args.sessionId}/entries?afterUpdatedSeq=${args.afterUpdatedSeq}`,
+    });
+  }
+
+  async interrupt(args: { sessionId: string; reason: string }): Promise<void> {
+    await this.request({
+      method: "POST",
+      path: `/v0/grokbot/sessions/${args.sessionId}/interrupt`,
+      body: { reason: args.reason },
+    });
+  }
+}
+
+export class GrokBotRunner implements AgentRunner {
+  /**
+   * One hosted Grok Bot agent per SDK agent name — the backend
+   * get-or-creates by name, so every SDK session forwards into the same
+   * hosted agent and conversation, and the Grok Bot app shows one agent
+   * rather than one per session.
+   */
+  private readonly agents = new Map<string, HostedAgent>();
+  /**
+   * Per-hosted-agent turn chain. Sessions share one hosted conversation
+   * and one transcript cursor, so turns run one at a time per agent:
+   * deliveries attribute to the turn that sent them, and an abort only
+   * interrupts its own turn — mirroring the hosted workflow's own queue.
+   */
+  private readonly turns = new Map<string, Promise<unknown>>();
+  private client: GrokBotApiClient | undefined;
+
+  constructor(private readonly options: GrokBotRunnerOptions = {}) {}
+
+  async runTurn(request: RunnerTurnRequest): Promise<TurnOutcome> {
+    if (request.runtime !== "grokbot") {
+      throw new Error(
+        `Session ${request.sessionId} is a ${request.runtime} turn, which the Grok Bot runner cannot execute.`
+      );
+    }
+    if (request.images !== undefined && request.images.length > 0) {
+      // Attachments ride the hosted box's upload path, which the /v0
+      // session API does not expose yet. Refuse rather than silently
+      // dropping what the user attached.
+      throw new Error(
+        "Image attachments are not supported on grokbot turns yet."
+      );
+    }
+    const name = hostedAgentName(request);
+    const previous = this.turns.get(name) ?? Promise.resolve();
+    const run = previous.then(() => this.executeTurn(request));
+    this.turns.set(
+      name,
+      run.catch(() => {})
+    );
+    return await run;
+  }
+
+  private async executeTurn(request: RunnerTurnRequest): Promise<TurnOutcome> {
+    const signal = request.signal;
+    if (signal?.aborted === true) {
+      return { status: "cancelled" };
+    }
+    const client = this.ensureClient();
+    const entry = await this.getAgent(client, request);
+
+    const send = await client.sendMessage({
+      sessionId: entry.remoteId,
+      text: request.prompt,
+    });
+    if (
+      send.delivery !== "accepted_temporal" &&
+      send.delivery !== "duplicate"
+    ) {
+      throw new Error(
+        `The hosted Grok Bot harness did not accept the turn (delivery: ${send.delivery}).`
+      );
+    }
+
+    const pollIntervalMs =
+      this.options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const turnTimeoutMs = this.options.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS;
+    const deadline = Date.now() + turnTimeoutMs;
+    const delivered: string[] = [];
+    let sawBusy = false;
+    let idlePolls = 0;
+
+    while (true) {
+      // On abort: interrupt the hosted run, drain entries once so a reply
+      // that already landed still streams out, then cancel.
+      const aborted = isAborted(signal);
+      if (aborted) {
+        await client
+          .interrupt({
+            sessionId: entry.remoteId,
+            reason: "The user sent a new message.",
+          })
+          .catch(() => {});
+      }
+      const page = await client.listEntries({
+        sessionId: entry.remoteId,
+        afterUpdatedSeq: entry.lastUpdatedSeq,
+      });
+      entry.lastUpdatedSeq = BigInt(page.latestUpdatedSeq);
+      for (const item of page.entries) {
+        if (item.kind !== "send-message" || item.text === undefined) {
+          continue;
+        }
+        const delta = delivered.length === 0 ? item.text : `\n\n${item.text}`;
+        delivered.push(item.text);
+        // The emit callback may be async; a rejection must never escape
+        // the poll loop.
+        void Promise.resolve(
+          request.onUpdate({ type: "text-delta", text: delta })
+        ).catch(() => {});
+      }
+      if (aborted) {
+        return { status: "cancelled" };
+      }
+      if (page.turn.inFlight || page.turn.queued > 0) {
+        sawBusy = true;
+      } else if (page.turn.idle) {
+        idlePolls += 1;
+        if (sawBusy || idlePolls >= MIN_IDLE_POLLS_WITHOUT_BUSY) {
+          return {
+            status: "finished",
+            result: delivered.length === 0 ? undefined : delivered.join("\n\n"),
+          };
+        }
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `The grokbot turn for session ${request.sessionId} did not settle within ${Math.round(turnTimeoutMs / 60_000)} minutes.`
+        );
+      }
+      await this.sleep(pollIntervalMs, signal);
+    }
+  }
+
+  async dispose(): Promise<void> {
+    // Hosted agents live server-side (the account's Grok Bot agents);
+    // nothing in this process holds conversation state.
+    this.agents.clear();
+  }
+
+  private ensureClient(): GrokBotApiClient {
+    this.client ??= new GrokBotApiClient(this.options);
+    return this.client;
+  }
+
+  private async getAgent(
+    client: GrokBotApiClient,
+    request: RunnerTurnRequest
+  ): Promise<HostedAgent> {
+    const name = hostedAgentName(request);
+    const existing = this.agents.get(name);
+    if (existing !== undefined) {
+      return existing;
+    }
+    // Get-or-create: a reconnect (new process, same agent name) lands on
+    // the existing hosted agent. The returned tail seq starts the cursor
+    // after the hosted conversation's history so an old transcript never
+    // replays into this turn's reply.
+    const created = await client.createSession({
+      name,
+      instructions: request.instructions,
+    });
+    const entry: HostedAgent = {
+      remoteId: created.id,
+      lastUpdatedSeq: BigInt(created.latestUpdatedSeq),
+    };
+    this.agents.set(name, entry);
+    return entry;
+  }
+
+  private async sleep(
+    ms: number,
+    signal: AbortSignal | undefined
+  ): Promise<void> {
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+      }, ms);
+      const onAbort = (): void => {
+        clearTimeout(timer);
+        resolve();
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+}
+
+function hostedAgentName(request: RunnerTurnRequest): string {
+  return request.agentName ?? "Agent SDK agent";
+}
+
+/**
+ * `AbortSignal.aborted` is readonly to TypeScript, so an inline recheck
+ * after an await narrows to the stale pre-await value; the function
+ * boundary keeps the recheck honest.
+ */
+function isAborted(signal: AbortSignal | undefined): boolean {
+  return signal?.aborted === true;
+}

package/src/internal/mcp-endpoint.ts

@@ -304,6 +304,10 @@ function buildConnectionBridgeMcpServer(
         ...(tool.outputSchema === undefined
           ? {}
           : { outputSchema: tool.outputSchema }),
+        // Already bounded to the MCP-spec fields at listing time (mcp-host).
+        ...(tool.annotations === undefined
+          ? {}
+          : { annotations: tool.annotations }),
       })),
     };
   });

package/src/internal/mcp-host.ts

@@ -20,6 +20,7 @@ import type {
   HostMcpRegistry,
   HostMcpToolInfo,
   JsonObject,
+  McpToolAnnotations,
 } from "../types.js";
 import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
 import { createHostMcpOAuthProvider } from "./mcp-oauth.js";
@@ -213,12 +214,58 @@ export function isStaleMcpSessionError(error: unknown): boolean {
   return code === 404;
 }
 
+/** Longest server-supplied annotation title carried off a listing. */
+const MAX_TOOL_ANNOTATION_TITLE_LENGTH = 256;
+
+/**
+ * Bound a server's `Tool.annotations` to the MCP-spec fields: the four
+ * boolean hints plus a length-capped `title`. A server cannot stuff
+ * arbitrary payloads into every listing, and malformed values (a non-boolean
+ * hint, a non-object) behave like absent ones so consumers fail closed.
+ *
+ * Mirrors `@anysphere/mcp-core/mcp-tool-annotations` (`toolAnnotationsJsonField`),
+ * which this package cannot import: it publishes to npm and cannot take a
+ * workspace-only runtime dependency. Keep the two in sync.
+ *
+ * Exported for unit tests.
+ */
+export function boundedToolAnnotations(
+  annotations: unknown
+): McpToolAnnotations | undefined {
+  if (
+    typeof annotations !== "object" ||
+    annotations === null ||
+    Array.isArray(annotations)
+  ) {
+    return undefined;
+  }
+  const record = annotations as Record<string, unknown>;
+  const bounded: McpToolAnnotations = {};
+  if (typeof record.title === "string" && record.title.length > 0) {
+    bounded.title = record.title.slice(0, MAX_TOOL_ANNOTATION_TITLE_LENGTH);
+  }
+  for (const key of [
+    "readOnlyHint",
+    "destructiveHint",
+    "idempotentHint",
+    "openWorldHint",
+  ] as const) {
+    const value = record[key];
+    if (typeof value === "boolean") {
+      bounded[key] = value;
+    }
+  }
+  return Object.keys(bounded).length === 0 ? undefined : bounded;
+}
+
 function toToolInfo(tool: {
   name: string;
   description?: string;
   inputSchema?: unknown;
   outputSchema?: unknown;
+  annotations?: unknown;
 }): HostMcpToolInfo {
+  const annotations = boundedToolAnnotations(tool.annotations);
   return {
     name: tool.name,
     ...(tool.description === undefined
@@ -230,6 +277,7 @@ function toToolInfo(tool: {
     ...(tool.outputSchema === undefined
       ? {}
       : { outputSchema: tool.outputSchema as JsonObject }),
+    ...(annotations === undefined ? {} : { annotations }),
   };
 }
 

package/src/internal/runtime-dispatch-runner.ts

@@ -0,0 +1,63 @@
+/**
+ * Routes each turn to the runner that owns its runtime: local and cloud
+ * turns stay on the Cursor SDK runner, grokbot turns go to the Grok Bot
+ * remote client (`internal/grokbot/runner.ts`), which drives the hosted
+ * Grok Bot (Sand) harness through the public `/v0/grokbot` session API.
+ * Both runners ship in the published package.
+ */
+
+import type { RunnerTurnRequest, TurnOutcome } from "../types.js";
+import type { GrokBotRunnerOptions } from "./grokbot/runner.js";
+import { GrokBotRunner } from "./grokbot/runner.js";
+import type {
+  AgentRunner,
+  PrewarmOutcome,
+  RunnerPrewarmRequest,
+} from "./sdk-runner.js";
+
+export interface RuntimeDispatchingRunnerOptions {
+  sdkRunner: AgentRunner;
+  grokbot?: GrokBotRunnerOptions;
+  /** Test seam — replaces the real Grok Bot remote client. */
+  createGrokBotRunner?: (options: GrokBotRunnerOptions) => AgentRunner;
+}
+
+export class RuntimeDispatchingRunner implements AgentRunner {
+  private grokbotRunner: AgentRunner | undefined;
+
+  constructor(private readonly options: RuntimeDispatchingRunnerOptions) {}
+
+  /**
+   * The Grok Bot remote client, created on first use; a missing API key
+   * surfaces on the first grokbot turn, not at serve start.
+   */
+  ensureGrokBotRunner(): AgentRunner {
+    const options = this.options.grokbot ?? {};
+    this.grokbotRunner ??=
+      this.options.createGrokBotRunner?.(options) ?? new GrokBotRunner(options);
+    return this.grokbotRunner;
+  }
+
+  async runTurn(request: RunnerTurnRequest): Promise<TurnOutcome> {
+    if (request.runtime === "grokbot") {
+      return this.ensureGrokBotRunner().runTurn(request);
+    }
+    return this.options.sdkRunner.runTurn(request);
+  }
+
+  async prewarm(request: RunnerPrewarmRequest): Promise<PrewarmOutcome> {
+    // Prewarming is a local-harness concern; the engine only calls it for
+    // local-runtime agents.
+    return (
+      this.options.sdkRunner.prewarm?.(request) ?? {
+        warmed: false,
+        reason: "the Cursor SDK runner does not support prewarming",
+      }
+    );
+  }
+
+  async dispose(): Promise<void> {
+    await this.options.sdkRunner.dispose?.();
+    await this.grokbotRunner?.dispose?.();
+  }
+}

package/src/internal/sdk-runner.ts

@@ -199,6 +199,15 @@ export class CursorSdkRunner implements AgentRunner {
   }
 
   async runTurn(request: RunnerTurnRequest): Promise<TurnOutcome> {
+    // Fail closed: this runner only knows the Cursor SDK's local and cloud
+    // harnesses. A grokbot turn reaching it means the serve wiring skipped
+    // the Grok Bot runner — running it on the local harness would silently
+    // swap the box (and the SendToUser contract) out from under the agent.
+    if (request.runtime === "grokbot") {
+      throw new Error(
+        `Session ${request.sessionId} is a grokbot turn, which the Cursor SDK runner cannot execute. Serve must route grokbot turns to the Grok Bot runner.`
+      );
+    }
     let sawUpdate = false;
     const tracked: RunnerTurnRequest = {
       ...request,

package/src/internal/server.ts

@@ -175,6 +175,7 @@ import {
   validateMountConnectionsConfig,
 } from "./resolved-connections.js";
 import { Router } from "./router.js";
+import { RuntimeDispatchingRunner } from "./runtime-dispatch-runner.js";
 import { ScheduleRunner, UnknownScheduleError } from "./schedule-runner.js";
 import { type AgentRunner, CursorSdkRunner } from "./sdk-runner.js";
 import {
@@ -493,12 +494,39 @@ export async function startServer(
       "[agent-sdk] warning: --allow-anonymous admits every HTTP caller as the same principal; use only on a trusted network (e.g. Tailscale) and prefer --bearer-token for shared hosts"
     );
   }
-  const runner =
+  const sdkRunner =
     options.runner ??
-    new CursorSdkRunner({
-      ...(accountKey === undefined ? {} : { apiKey: accountKey.apiKey }),
-      logger,
+    new CursorSdkRunner({ apiKey: accountKey?.apiKey, logger });
+  // Grok Bot turns run on Cursor's hosted Grok Bot (Sand) harness through
+  // the /v0/grokbot session API; the SDK side is a thin remote client. The
+  // dispatching runner is only interposed when a mount needs it. An
+  // injected test runner receives every turn, grokbot included.
+  const hasGrokBotMounts = mounts.some(
+    (mount) => mount.project.agent.runtime === "grokbot"
+  );
+  // Fail closed like cursor-account GitHub/MCP: grokbot turns execute on the
+  // signed-in account's hosted computer, so anonymous admission needs its
+  // own opt-in.
+  if (hasGrokBotMounts && options.allowAnonymous === true) {
+    if (options.allowAnonymousGrokbot !== true) {
+      throw new Error(
+        'runtime: "grokbot" cannot be served with --allow-anonymous because admitted callers could drive the signed-in account\'s hosted Grok Bot computer. If every admitted caller is trusted (e.g. behind an SSO proxy), opt in with --allow-anonymous-grokbot.'
+      );
+    }
+    logger(
+      "[agent-sdk] warning: --allow-anonymous-grokbot — every admitted HTTP caller can drive turns on the signed-in account's hosted Grok Bot computer; serve this only behind a trusted boundary (e.g. an SSO proxy)"
+    );
+  }
+  let runner: AgentRunner = sdkRunner;
+  if (hasGrokBotMounts && options.runner === undefined) {
+    runner = new RuntimeDispatchingRunner({
+      sdkRunner,
+      grokbot: { apiKey: accountKey?.apiKey },
     });
+    logger(
+      "[agent-sdk] grokbot runtime: remote client (turns run on the hosted Grok Bot harness)"
+    );
+  }
 
   const router = new Router();
   const runtimes: MountedRuntime[] = [];