@cursor/july 0.1.87 → 0.1.89

package/dist/internal/deploy-client.js

@@ -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`.
  *
@@ -66,6 +67,7 @@ export function deploymentServiceAccountId(deployment) {
     const id = String(raw).trim();
     return id === "" ? undefined : id;
 }
+export const TERMINAL_AGENTKIT_DEPLOY_STATUSES = new Set(["running", "failed", "stopped"]);
 // All response schemas are `.passthrough()`: the backend keeps growing the
 // deployment payload (serviceAccountId, egressAllowedDomains, secret
 // metadata, ...) and unknown fields must flow through untouched — both so
@@ -83,6 +85,33 @@ const deployAcceptedSchema = z
     aliasToken: z.string().optional(),
 })
     .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(),
@@ -263,6 +292,45 @@ 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.
+     */
+    deployAgentkit(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const slugError = validateDeploymentSlug(args.slug);
+            if (slugError !== undefined) {
+                throw new DeployApiError(slugError, 400);
+            }
+            const raw = yield 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);
+        });
+    }
+    getAgentkitDeploy(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const raw = yield 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);
+        });
+    }
     listDeployments(args) {
         return __awaiter(this, void 0, void 0, function* () {
             const raw = yield this.request({
@@ -476,7 +544,7 @@ function mapErrorResponse(response, bodyText, context) {
             // Fastify's route-not-found envelope means we hit the wrong host
             // (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/*.`, 404);
+                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/* and /internal/agentkit/*.`, 404);
             }
             return new DeployApiError(context.slug === undefined
                 ? `Not found — the agent_serve_mvp feature gate may not be enabled for your team.`

package/dist/internal/discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/internal/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkBH,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EASrB,KAAK,UAAU,EAwBhB,MAAM,aAAa,CAAC;AAgCrB,MAAM,WAAW,uBAAuB;IACtC,sDAAsD;IACtD,YAAY,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3E;AAmBD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CASrE;AAED,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,EAAE,CAAC,CA2B1B;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC,CA6BzD;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAAuB,GAAG;IACjC,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;CACtB,GACL,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC,CAgBzD;AAWD,iFAAiF;AACjF,eAAO,MAAM,cAAc,EAAE,GAAG,CAAC,MAAM,CAIrC,CAAC;AAEH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,YAAY,CAAC,CA0EvB;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAElE;AAED,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,MAAM,CAOnE;AAozBD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAiB3E;AAo2BD,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,CA4JnE"}
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/internal/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkBH,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EASrB,KAAK,UAAU,EAwBhB,MAAM,aAAa,CAAC;AAgCrB,MAAM,WAAW,uBAAuB;IACtC,sDAAsD;IACtD,YAAY,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3E;AAmBD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CASrE;AAED,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,EAAE,CAAC,CA2B1B;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC,CA6BzD;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAAuB,GAAG;IACjC,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;CACtB,GACL,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC,CAgBzD;AAWD,iFAAiF;AACjF,eAAO,MAAM,cAAc,EAAE,GAAG,CAAC,MAAM,CAIrC,CAAC;AAEH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,YAAY,CAAC,CA0EvB;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAElE;AAED,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,MAAM,CAOnE;AAk0BD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAiB3E;AA88BD,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,CA4JnE"}

package/dist/internal/discovery.js

@@ -313,7 +313,7 @@ function loadAgent(ctx, agentDir, options) {
         const connections = yield loadConnections(ctx, yield resolveMcpConnectionsDir(ctx, agentDir));
         const seedFiles = yield loadSeedFiles(ctx, agentDir);
         const subagents = yield loadSubagents(ctx, join(agentDir, "subagents"));
-        const runtime = (config === null || config === void 0 ? void 0 : config.runtime) === "cloud" ? "cloud" : "local";
+        const runtime = resolveRuntime(ctx, agentDir, config === null || config === void 0 ? void 0 : 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 === null || config === void 0 ? void 0 : config.cloud;
@@ -332,25 +332,27 @@ function loadAgent(ctx, agentDir, options) {
         const allowedTools = authoredAllowlist === undefined || authoredAllowlist.includes("mcp")
             ? authoredAllowlist
             : [...authoredAllowlist, "mcp"];
-        // 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")),
@@ -395,6 +397,19 @@ function loadAgent(ctx, agentDir, options) {
             });
         }
         appendBuiltinTools(ctx, agentDir, tools, config === null || config === void 0 ? void 0 : 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 Object.assign(Object.assign(Object.assign(Object.assign({ name, description: config === null || config === void 0 ? void 0 : config.description, 
             // Root agents always get a concrete model: authored value or DEFAULT_MODEL.
             model: isValidModelSetting(config === null || config === void 0 ? void 0 : config.model) ? config.model : DEFAULT_MODEL, instructions,
@@ -1263,6 +1278,67 @@ function appendBuiltinTools(ctx, agentDir, tools, config) {
         tools.push(tool);
     }
 }
+/**
+ * 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, agentDir, runtime) {
+    if (runtime === undefined ||
+        runtime === "local" ||
+        runtime === "cloud" ||
+        runtime === "grokbot") {
+        return runtime !== null && runtime !== void 0 ? 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, agentDir, counts) {
+    const agentPath = displayPath(ctx, join(agentDir, "agent.ts"));
+    const error = (path, message) => {
+        ctx.diagnostics.push({ severity: "error", path, message });
+    };
+    const warn = (path, message) => {
+        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, agentDir, counts) {
     const agentPath = displayPath(ctx, join(agentDir, "agent.ts"));
     if (!counts.hasCloudOptions) {

package/dist/internal/docs-site.d.ts

@@ -6,10 +6,21 @@
  * 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.
+ */
+/** Absolute path of the VitePress site shipped in this install (ignores overlay). */
+export declare function shippedDocsDistDir(): string;
+/**
+ * Directory `/docs` is served from. Prefers `AGENT_SERVE_DOCS_DIST` when that
+ * overlay has a built site; otherwise the install's `dist/docs/`.
  */
-/** Absolute path of the built VitePress site shipped in this install. */
 export declare function docsDistDir(): string;
-/** Whether `pnpm run docs:build` has produced the docs site. */
+/** Whether a built docs site is available at `distDir` (overlay or shipped). */
 export declare function docsSiteExists(distDir?: string): boolean;
 /**
  * Resolve a request path under the docs mount to a file inside the built

package/dist/internal/docs-site.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-site.d.ts","sourceRoot":"","sources":["../../src/internal/docs-site.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAeH,yEAAyE;AACzE,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,OAAO,GAAE,MAAsB,GAAG,OAAO,CAEvE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,MAAsB,GAC9B,MAAM,GAAG,SAAS,CAoBpB;AAED,+CAA+C;AAC/C,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,MAAsB,GAC9B,QAAQ,CAiCV;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkB,GAC3C,OAAO,CAAC,IAAI,CAAC,CA8Bf"}
+{"version":3,"file":"docs-site.d.ts","sourceRoot":"","sources":["../../src/internal/docs-site.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA0DH,qFAAqF;AACrF,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAMpC;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,OAAO,GAAE,MAAsB,GAAG,OAAO,CAEvE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,MAAsB,GAC9B,MAAM,GAAG,SAAS,CAyBpB;AAED,+CAA+C;AAC/C,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,MAAsB,GAC9B,QAAQ,CAqCV;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkB,GAC3C,OAAO,CAAC,IAAI,CAAC,CA8Bf"}

package/dist/internal/docs-site.js

@@ -6,6 +6,12 @@
  * 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.
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -17,20 +23,69 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 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";
 import { STATIC_CONTENT_TYPES } from "./playground/static.js";
 // src|dist/internal/docs-site.ts → packages/agent-serve/dist/docs/.
 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) {
+    try {
+        return realpathSync(dir);
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+function isInsideRoot(fileReal, rootReal) {
+    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, rootReal) {
+    try {
+        const real = realpathSync(candidate);
+        if (!isInsideRoot(real, rootReal) || !statSync(real).isFile()) {
+            return undefined;
+        }
+        return real;
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+function hasDocsIndex(distDir) {
+    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() {
+    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() {
+    var _a;
+    const overlay = (_a = process.env[DOCS_OVERLAY_ENV]) === null || _a === void 0 ? void 0 : _a.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 = DOCS_DIST_DIR) {
-    return existsSync(join(distDir, "index.html"));
+/** Whether a built docs site is available at `distDir` (overlay or shipped). */
+export function docsSiteExists(distDir = docsDistDir()) {
+    return hasDocsIndex(distDir);
 }
 /**
  * Resolve a request path under the docs mount to a file inside the built
@@ -38,7 +93,7 @@ export function docsSiteExists(distDir = DOCS_DIST_DIR) {
  * emits one `.html` per page, so clean URLs resolve through the chain:
  * exact file → directory `index.html` → `<path>.html`.
  */
-export function resolveDocsFile(requestPath, distDir = DOCS_DIST_DIR) {
+export function resolveDocsFile(requestPath, distDir = docsDistDir()) {
     const decoded = requestPath
         .split("/")
         .filter((part) => part !== "")
@@ -47,20 +102,25 @@ export function resolveDocsFile(requestPath, distDir = DOCS_DIST_DIR) {
     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;
 }
 /** Serve one path from the built docs site. */
-export function renderDocsFile(requestPath, distDir = DOCS_DIST_DIR) {
+export function renderDocsFile(requestPath, distDir = docsDistDir()) {
     var _a;
     if (!docsSiteExists(distDir)) {
         return new Response(fallbackHtml(), {
@@ -70,8 +130,11 @@ export function renderDocsFile(requestPath, distDir = DOCS_DIST_DIR) {
     }
     const filePath = resolveDocsFile(requestPath, distDir);
     if (filePath === undefined) {
-        const notFound = join(distDir, "404.html");
-        return new Response(existsSync(notFound) ? readFileSync(notFound, "utf8") : "Not found", {
+        const root = realDir(distDir);
+        const notFound = root === undefined
+            ? undefined
+            : containedFile(join(distDir, "404.html"), root);
+        return new Response(notFound !== undefined ? readFileSync(notFound, "utf8") : "Not found", {
             status: 404,
             headers: { "content-type": "text/html; charset=utf-8" },
         });
@@ -98,7 +161,7 @@ export function renderDocsFile(requestPath, distDir = DOCS_DIST_DIR) {
  */
 export function ensureDocsSiteBundle() {
     return __awaiter(this, arguments, void 0, function* (logger = console.log) {
-        if (docsSiteExists()) {
+        if (docsSiteExists(DOCS_DIST_DIR)) {
             return;
         }
         const toolchain = resolveDocsToolchain();
@@ -115,7 +178,7 @@ export 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");
         }
         logger("[agent-sdk] docs site build complete");

package/dist/internal/grokbot/runner.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 type { RunnerTurnRequest, TurnOutcome } from "../../types.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;
+}
+export declare class GrokBotRunner implements AgentRunner {
+    private readonly options;
+    /**
+     * 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;
+    /**
+     * 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;
+    private client;
+    constructor(options?: GrokBotRunnerOptions);
+    runTurn(request: RunnerTurnRequest): Promise<TurnOutcome>;
+    private executeTurn;
+    dispose(): Promise<void>;
+    private ensureClient;
+    private getAgent;
+    private sleep;
+}
+//# sourceMappingURL=runner.d.ts.map

package/dist/internal/grokbot/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/internal/grokbot/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAErE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAoID,qBAAa,aAAc,YAAW,WAAW;IAiBnC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhBpC;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;IAC7D,OAAO,CAAC,MAAM,CAA+B;IAE7C,YAA6B,OAAO,GAAE,oBAAyB,EAAI;IAE7D,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAsB9D;YAEa,WAAW;IAiFnB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAI7B;IAED,OAAO,CAAC,YAAY;YAKN,QAAQ;YAyBR,KAAK;CAgBpB"}