@cursor/july 0.1.87 → 0.1.88

package/src/internal/discovery.ts

@@ -436,7 +436,7 @@ async function loadAgent(
   );
   const seedFiles = await loadSeedFiles(ctx, agentDir);
   const subagents = await loadSubagents(ctx, join(agentDir, "subagents"));
-  const runtime = config?.runtime === "cloud" ? "cloud" : "local";
+  const runtime = resolveRuntime(ctx, agentDir, config?.runtime);
   // Keep authored `cloud` even when default runtime is local — per-session
   // `send({ cloud })` merges it under cloudOverride for handoff sessions.
   const cloud = config?.cloud;
@@ -460,29 +460,30 @@ async function loadAgent(
     authoredAllowlist === undefined || authoredAllowlist.includes("mcp")
       ? authoredAllowlist
       : [...authoredAllowlist, "mcp" as const];
-  // The allowlist states runtime-agnostic intent, but the SDK cannot
-  // enforce tool restrictions on cloud agents yet — a cloud-runtime agent
-  // that declares one must fail at serve start, never run unrestricted.
-  // (Hybrid per-send cloud sessions fail closed in the session engine.)
-  if (allowedTools !== undefined && runtime === "cloud") {
+  // The allowlist states runtime-agnostic intent, but only the local
+  // harness can enforce it (the Cursor SDK rejects tool restrictions on
+  // cloud agents, and the Grok Bot harness has its own fixed toolset) — a
+  // non-local agent that declares one must fail at serve start, never run
+  // unrestricted. (Hybrid per-send cloud sessions fail closed in the
+  // session engine.)
+  if (allowedTools !== undefined && runtime !== "local") {
     ctx.diagnostics.push({
       severity: "error",
       path: displayPath(ctx, join(agentDir, "agent.ts")),
-      message:
-        'tools cannot be enforced on runtime: "cloud" yet (the Cursor SDK rejects tool restrictions on cloud agents). Remove `tools` or run the agent on the local runtime.',
+      message: `tools cannot be enforced on runtime: "${runtime}". Remove \`tools\` or run the agent on the local runtime.`,
     });
   }
   // Per-session connection features (defineConnection auth/advertiseTools)
   // only run on local turns: advertised tools are in-process server tools,
   // and per-session headers cannot reach a cloud VM's MCP config. A
-  // cloud-runtime agent that declares them must fail at serve start —
-  // never run without the connection's tools or identity. (Hybrid
-  // per-send cloud sessions fail closed in the session engine.)
+  // non-local agent that declares them must fail at serve start — never
+  // run without the connection's tools or identity. (Hybrid per-send
+  // cloud sessions fail closed in the session engine.)
   const perSessionConnection = connections.find(
     (connection) =>
       connection.advertiseTools === true || connection.auth !== undefined
   );
-  if (perSessionConnection !== undefined && runtime === "cloud") {
+  if (perSessionConnection !== undefined && runtime !== "local") {
     ctx.diagnostics.push({
       severity: "error",
       path: displayPath(ctx, join(agentDir, "agent.ts")),
@@ -532,9 +533,22 @@ async function loadAgent(
       hasCloudOptions: cloud !== undefined,
     });
   }
-
   appendBuiltinTools(ctx, agentDir, tools, config?.builtinTools);
 
+  // After appendBuiltinTools so opted-in built-ins (server-executed) count.
+  if (runtime === "grokbot") {
+    checkGrokBotRuntimeLimitations(ctx, agentDir, {
+      serverTools: tools.filter((tool) => tool.execution === "server").length,
+      agentTools: tools.filter((tool) => tool.execution === "agent").length,
+      skills: skills.length,
+      seedFiles: seedFiles.length,
+      connections: connections.length,
+      subagents: subagents.length,
+      hasCloudOptions: cloud !== undefined,
+      hasLocalSandbox: localSandbox,
+    });
+  }
+
   return {
     name,
     description: config?.description,
@@ -1575,6 +1589,112 @@ function appendBuiltinTools(
   }
 }
 
+/**
+ * Validate the authored runtime. An unrecognized value is an error
+ * diagnostic and falls back to local — a typo must not silently pick a
+ * different harness for every turn.
+ */
+function resolveRuntime(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  runtime: AgentRuntime | undefined
+): AgentRuntime {
+  if (
+    runtime === undefined ||
+    runtime === "local" ||
+    runtime === "cloud" ||
+    runtime === "grokbot"
+  ) {
+    return runtime ?? "local";
+  }
+  ctx.diagnostics.push({
+    severity: "error",
+    path: displayPath(ctx, join(agentDir, "agent.ts")),
+    message: `runtime must be "local", "cloud", or "grokbot"; got ${JSON.stringify(runtime)}.`,
+  });
+  return "local";
+}
+
+/**
+ * Grok Bot turns run on the Sand harness with its own toolset: authored
+ * server tools, MCP connections, and subagents have no path onto that
+ * toolset yet, so an agent declaring them must fail at serve start rather
+ * than run with capabilities silently missing.
+ */
+function checkGrokBotRuntimeLimitations(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  counts: {
+    serverTools: number;
+    agentTools: number;
+    skills: number;
+    seedFiles: number;
+    connections: number;
+    subagents: number;
+    hasCloudOptions: boolean;
+    hasLocalSandbox: boolean;
+  }
+): void {
+  const agentPath = displayPath(ctx, join(agentDir, "agent.ts"));
+  const error = (path: string, message: string): void => {
+    ctx.diagnostics.push({ severity: "error", path, message });
+  };
+  const warn = (path: string, message: string): void => {
+    ctx.diagnostics.push({ severity: "warning", path, message });
+  };
+  if (counts.serverTools > 0) {
+    error(
+      displayPath(ctx, join(agentDir, "tools")),
+      'Server tools (execution: "server", including opted-in builtinTools) are not reachable from grokbot turns yet. Remove them or run the agent on the local runtime.'
+    );
+  }
+  if (counts.connections > 0) {
+    error(
+      displayPath(ctx, join(agentDir, "mcp-connections")),
+      "MCP connections are not wired into grokbot turns yet. Remove them or run the agent on the local runtime."
+    );
+  }
+  if (counts.subagents > 0) {
+    error(
+      displayPath(ctx, join(agentDir, "subagents")),
+      "Authored subagents are not available on grokbot turns (the Grok Bot harness runs its own subagent set). Remove them or run the agent on the local runtime."
+    );
+  }
+  // The remaining declarations mirror the cloud runtime's warnings: the
+  // turn runs on a hosted machine (the account's box), so local-workspace
+  // materialization never reaches it.
+  if (counts.agentTools > 0) {
+    warn(
+      displayPath(ctx, join(agentDir, "tools")),
+      'Agent tools (execution: "agent") are described in the hosted session\'s instructions (with script bodies); they are not written onto the box filesystem automatically.'
+    );
+  }
+  if (counts.skills > 0) {
+    warn(
+      displayPath(ctx, join(agentDir, "skills")),
+      "Authored skills are materialized into the local session workspace only; the hosted Grok Bot box does not see them."
+    );
+  }
+  if (counts.seedFiles > 0) {
+    warn(
+      displayPath(ctx, join(agentDir, "sandbox")),
+      "sandbox/workspace seed files apply to the local session workspace only; grokbot turns run on the account's hosted box."
+    );
+  }
+  if (counts.hasCloudOptions) {
+    warn(
+      agentPath,
+      'The `cloud` block is unused on runtime: "grokbot", and grokbot sessions refuse per-session cloud attach.'
+    );
+  }
+  if (counts.hasLocalSandbox) {
+    warn(
+      agentPath,
+      'local.sandbox does not apply to runtime: "grokbot"; the box is the account\'s Cursor-hosted computer.'
+    );
+  }
+}
+
 function warnCloudRuntimeLimitations(
   ctx: DiscoveryContext,
   agentDir: string,

package/src/internal/docs-site.ts

@@ -6,10 +6,16 @@
  * resolve under the mount). `serve` auto-builds it when the local
  * vitepress toolchain is present (source checkouts); published installs
  * ship the prebuilt site inside `dist/**`.
+ *
+ * Set `AGENT_SERVE_DOCS_DIST` to an overlay directory that contains a built
+ * site (`index.html`). When that path exists, `/docs` is served from it so a
+ * long-lived host (corp ECS) can pick up the published `@cursor/july` docs
+ * without rebuilding the process image. Requests re-read the path, so an
+ * atomic symlink swap is visible without a restart.
  */
 
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, extname, join, normalize, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -21,14 +27,69 @@ const DOCS_DIST_DIR = fileURLToPath(
   new URL("../../dist/docs/", import.meta.url)
 );
 
-/** Absolute path of the built VitePress site shipped in this install. */
+const DOCS_OVERLAY_ENV = "AGENT_SERVE_DOCS_DIST";
+
+function realDir(dir: string): string | undefined {
+  try {
+    return realpathSync(dir);
+  } catch {
+    return undefined;
+  }
+}
+
+function isInsideRoot(fileReal: string, rootReal: string): boolean {
+  const prefix = rootReal.endsWith(sep) ? rootReal : `${rootReal}${sep}`;
+  return fileReal === rootReal || fileReal.startsWith(prefix);
+}
+
+/**
+ * Resolve `candidate` to a regular file whose real path stays under
+ * `rootReal`. Follows overlay / site-root symlinks, but refuses a planted
+ * symlink (or hard-linked path) that escapes the docs tree.
+ */
+function containedFile(
+  candidate: string,
+  rootReal: string
+): string | undefined {
+  try {
+    const real = realpathSync(candidate);
+    if (!isInsideRoot(real, rootReal) || !statSync(real).isFile()) {
+      return undefined;
+    }
+    return real;
+  } catch {
+    return undefined;
+  }
+}
+
+function hasDocsIndex(distDir: string): boolean {
+  const root = realDir(distDir);
+  if (root === undefined) {
+    return false;
+  }
+  return containedFile(join(distDir, "index.html"), root) !== undefined;
+}
+
+/** Absolute path of the VitePress site shipped in this install (ignores overlay). */
+export function shippedDocsDistDir(): string {
+  return DOCS_DIST_DIR;
+}
+
+/**
+ * Directory `/docs` is served from. Prefers `AGENT_SERVE_DOCS_DIST` when that
+ * overlay has a built site; otherwise the install's `dist/docs/`.
+ */
 export function docsDistDir(): string {
+  const overlay = process.env[DOCS_OVERLAY_ENV]?.trim();
+  if (overlay !== undefined && overlay !== "" && hasDocsIndex(overlay)) {
+    return overlay;
+  }
   return DOCS_DIST_DIR;
 }
 
-/** Whether `pnpm run docs:build` has produced the docs site. */
-export function docsSiteExists(distDir: string = DOCS_DIST_DIR): boolean {
-  return existsSync(join(distDir, "index.html"));
+/** Whether a built docs site is available at `distDir` (overlay or shipped). */
+export function docsSiteExists(distDir: string = docsDistDir()): boolean {
+  return hasDocsIndex(distDir);
 }
 
 /**
@@ -39,7 +100,7 @@ export function docsSiteExists(distDir: string = DOCS_DIST_DIR): boolean {
  */
 export function resolveDocsFile(
   requestPath: string,
-  distDir: string = DOCS_DIST_DIR
+  distDir: string = docsDistDir()
 ): string | undefined {
   const decoded = requestPath
     .split("/")
@@ -49,14 +110,19 @@ export function resolveDocsFile(
   if (normalized.startsWith("..") || normalized.includes(`..${sep}`)) {
     return undefined;
   }
+  const rootReal = realDir(distDir);
+  if (rootReal === undefined) {
+    return undefined;
+  }
   const root = distDir.endsWith(sep) ? distDir : `${distDir}${sep}`;
   const base = join(root, normalized);
   if (base !== root.slice(0, -1) && !base.startsWith(root)) {
     return undefined;
   }
   for (const candidate of [base, join(base, "index.html"), `${base}.html`]) {
-    if (existsSync(candidate) && statSync(candidate).isFile()) {
-      return candidate;
+    const file = containedFile(candidate, rootReal);
+    if (file !== undefined) {
+      return file;
     }
   }
   return undefined;
@@ -65,7 +131,7 @@ export function resolveDocsFile(
 /** Serve one path from the built docs site. */
 export function renderDocsFile(
   requestPath: string,
-  distDir: string = DOCS_DIST_DIR
+  distDir: string = docsDistDir()
 ): Response {
   if (!docsSiteExists(distDir)) {
     return new Response(fallbackHtml(), {
@@ -75,9 +141,13 @@ export function renderDocsFile(
   }
   const filePath = resolveDocsFile(requestPath, distDir);
   if (filePath === undefined) {
-    const notFound = join(distDir, "404.html");
+    const root = realDir(distDir);
+    const notFound =
+      root === undefined
+        ? undefined
+        : containedFile(join(distDir, "404.html"), root);
     return new Response(
-      existsSync(notFound) ? readFileSync(notFound, "utf8") : "Not found",
+      notFound !== undefined ? readFileSync(notFound, "utf8") : "Not found",
       {
         status: 404,
         headers: { "content-type": "text/html; charset=utf-8" },
@@ -110,7 +180,7 @@ export function renderDocsFile(
 export async function ensureDocsSiteBundle(
   logger: (line: string) => void = console.log
 ): Promise<void> {
-  if (docsSiteExists()) {
+  if (docsSiteExists(DOCS_DIST_DIR)) {
     return;
   }
   const toolchain = resolveDocsToolchain();
@@ -133,7 +203,7 @@ export async function ensureDocsSiteBundle(
   if (code !== 0) {
     throw new Error(`docs vitepress build failed (exit ${code})`);
   }
-  if (!docsSiteExists()) {
+  if (!docsSiteExists(DOCS_DIST_DIR)) {
     throw new Error(
       "docs vitepress build finished but dist/docs/index.html is missing"
     );