@cursor/july 0.1.101 → 0.1.102

package/dist/internal/discovery/agent.js

@@ -0,0 +1,306 @@
+/**
+ * Compile one `agent/` directory (and its subagents) into a {@link ResolvedAgent}.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { join } from "node:path";
+import { DEFAULT_MODEL } from "../../types.js";
+import { builtinTools } from "../builtin-tools/index.js";
+import { withIdentityPreamble } from "../workspace.js";
+import { isValidModelSetting, loadAgentConfig, resolveAgentCwd, resolveArchitecture, resolveConcurrency, resolveHosting, resolveLocalCwd, runtimeArchitectureCompatibilityError, } from "./agent-config.js";
+import { loadConnections, loadHostConnections, resolveMcpConnectionsDir, } from "./connections.js";
+import { displayPath } from "./context.js";
+import { appendExtensions } from "./extensions.js";
+import { findModuleFile, isDirectory, sortedEntries } from "./fs.js";
+import { loadInstructions } from "./instructions.js";
+import { validateName } from "./names.js";
+import { checkGrokBotRuntimeLimitations, resolveRuntime, warnCloudRuntimeLimitations, } from "./runtime.js";
+import { loadSeedFiles } from "./seed-files.js";
+import { loadSkills } from "./skills.js";
+import { subagent } from "./subagent.js";
+import { appendBuiltinTools, loadTools } from "./tools.js";
+export function loadAgent(ctx, agentDir, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d;
+        var _e;
+        const config = yield loadAgentConfig(ctx, agentDir, options.isRoot);
+        const name = (_e = config === null || config === void 0 ? void 0 : config.name) !== null && _e !== void 0 ? _e : options.name;
+        const authoredInstructions = yield loadInstructions(ctx, agentDir, config, options.isRoot);
+        // Subagents run as Cursor SDK custom subagents (prompt + description +
+        // model); their other slots are inert today, so don't load them — just
+        // warn that they exist.
+        if (!options.isRoot) {
+            yield warnUnsupportedSubagentSlots(ctx, agentDir);
+            if ((config === null || config === void 0 ? void 0 : config.builtinTools) !== undefined) {
+                ctx.diagnostics.push({
+                    severity: "warning",
+                    path: displayPath(ctx, join(agentDir, "agent.ts")),
+                    message: "builtinTools is not supported on subagents; ignoring.",
+                });
+            }
+            if ((config === null || config === void 0 ? void 0 : config.tools) !== undefined) {
+                ctx.diagnostics.push({
+                    severity: "warning",
+                    path: displayPath(ctx, join(agentDir, "agent.ts")),
+                    message: "tools is not supported on subagents (they keep the harness task-tool toolset); ignoring.",
+                });
+            }
+            if ((config === null || config === void 0 ? void 0 : config.architecture) !== undefined) {
+                ctx.diagnostics.push({
+                    severity: "warning",
+                    path: displayPath(ctx, join(agentDir, "agent.ts")),
+                    message: "architecture is not supported on subagents; ignoring.",
+                });
+            }
+            const artifactsPath = yield findModuleFile(agentDir, "artifacts");
+            if (artifactsPath !== undefined) {
+                ctx.diagnostics.push({
+                    severity: "warning",
+                    path: displayPath(ctx, artifactsPath),
+                    message: "artifacts are not supported on subagents; ignoring.",
+                });
+            }
+            return subagent(name, {
+                description: config === null || config === void 0 ? void 0 : config.description,
+                model: config === null || config === void 0 ? void 0 : config.model,
+                prompt: authoredInstructions,
+            });
+        }
+        // Root agents without authored instructions stay undefined (diagnostic
+        // already recorded).
+        const instructions = authoredInstructions === undefined
+            ? undefined
+            : withIdentityPreamble(name, authoredInstructions);
+        const tools = yield loadTools(ctx, join(agentDir, "tools"));
+        const skills = yield loadSkills(ctx, join(agentDir, "skills"));
+        const connections = yield loadConnections(ctx, yield resolveMcpConnectionsDir(ctx, agentDir));
+        const subagents = yield loadSubagents(ctx, join(agentDir, "subagents"));
+        const extensions = yield appendExtensions(ctx, join(agentDir, "extensions"), {
+            tools,
+            skills,
+            connections,
+            subagents,
+        });
+        const hostConnections = yield loadHostConnections(ctx, agentDir, connections);
+        const seedFiles = yield loadSeedFiles(ctx, agentDir);
+        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;
+        const localWorkspaceDir = resolveAgentCwd(ctx, (_a = config === null || config === void 0 ? void 0 : config.local) === null || _a === void 0 ? void 0 : _a.workspaceDir);
+        const localCwd = yield resolveLocalCwd(ctx, (_b = config === null || config === void 0 ? void 0 : config.local) === null || _b === void 0 ? void 0 : _b.cwd, (_c = config === null || config === void 0 ? void 0 : config.local) === null || _c === void 0 ? void 0 : _c.workspaceDir);
+        const localSandbox = ((_d = config === null || config === void 0 ? void 0 : config.local) === null || _d === void 0 ? void 0 : _d.sandbox) === true;
+        // Built-in tool allowlist (top-level `tools`). `[]` is meaningful (no
+        // native built-in tools), so presence is keyed on the field, not on
+        // emptiness. "mcp" is always granted alongside a configured allowlist:
+        // it is transport, not capability — this kit's own server tools ride the
+        // SDK custom-tool MCP path, so omitting it silently breaks
+        // `agent/tools/`, and what MCP actually exposes stays controlled by the
+        // second layer (authored tools, mcp-connections, the harness cwd's
+        // ambient config).
+        const authoredAllowlist = config === null || config === void 0 ? void 0 : config.tools;
+        const allowedTools = authoredAllowlist === undefined || authoredAllowlist.includes("mcp")
+            ? authoredAllowlist
+            : [...authoredAllowlist, "mcp"];
+        // 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: "${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
+        // 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 !== "local") {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, join(agentDir, "agent.ts")),
+                message: `MCP connection "${perSessionConnection.name}" uses advertiseTools/auth, which only run on runtime: "local". Remove them or run the agent on the local runtime.`,
+            });
+        }
+        // `execution: "agent"` tool scripts run through the shell tool. Shell is
+        // a real capability, so it is never injected — but an allowlist that
+        // strands authored scripts deserves a loud diagnostic, not silence.
+        if (allowedTools !== undefined &&
+            !allowedTools.includes("shell") &&
+            tools.some((tool) => tool.execution === "agent")) {
+            ctx.diagnostics.push({
+                severity: "warning",
+                path: displayPath(ctx, join(agentDir, "agent.ts")),
+                message: '`tools` omits "shell" but this agent has execution: "agent" tools, which run as shell scripts; the model will not be able to run them.',
+            });
+        }
+        if (localCwd !== undefined && localWorkspaceDir !== undefined) {
+            ctx.diagnostics.push({
+                severity: "warning",
+                path: displayPath(ctx, join(agentDir, "agent.ts")),
+                message: "local.workspaceDir pins every session to one directory, so local.cwd is unused. Drop one of them.",
+            });
+        }
+        const local = localCwd === undefined && localWorkspaceDir === undefined && !localSandbox
+            ? undefined
+            : {
+                cwd: localCwd,
+                workspaceDir: localWorkspaceDir,
+                sandbox: localSandbox,
+            };
+        const hosting = resolveHosting(ctx, agentDir, config === null || config === void 0 ? void 0 : config.hosting);
+        const concurrency = resolveConcurrency(ctx, agentDir, config === null || config === void 0 ? void 0 : config.concurrency);
+        const architecture = resolveArchitecture(ctx, agentDir, config === null || config === void 0 ? void 0 : config.architecture);
+        const runtimeArchitectureError = runtimeArchitectureCompatibilityError({
+            runtime,
+            architecture,
+        });
+        if (runtimeArchitectureError !== undefined) {
+            ctx.diagnostics.push({
+                severity: "error",
+                path: displayPath(ctx, join(agentDir, "agent.ts")),
+                message: runtimeArchitectureError,
+            });
+        }
+        if (runtime === "cloud") {
+            warnCloudRuntimeLimitations(ctx, agentDir, {
+                agentTools: tools.filter((tool) => tool.execution === "agent").length,
+                skills: skills.length,
+                seedFiles: seedFiles.length,
+                hasCloudOptions: cloud !== undefined,
+            });
+        }
+        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 + hostConnections.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,
+            runtime,
+            cloud,
+            local }, (allowedTools === undefined ? {} : { allowedTools })), { hosting,
+            concurrency }), (architecture === undefined ? {} : { architecture })), { tools,
+            skills,
+            extensions,
+            connections,
+            hostConnections,
+            subagents,
+            seedFiles });
+    });
+}
+function loadSubagents(ctx, subagentsDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!(yield isDirectory(subagentsDir))) {
+            return [];
+        }
+        const subagents = [];
+        for (const entry of yield sortedEntries(subagentsDir)) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            const subagentDir = join(subagentsDir, entry.name);
+            if (!validateName(ctx, "subagent", entry.name, subagentDir)) {
+                continue;
+            }
+            subagents.push(yield loadAgent(ctx, subagentDir, { name: entry.name, isRoot: false }));
+        }
+        return subagents;
+    });
+}
+function warnUnsupportedSubagentSlots(ctx, subagentDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const unsupported = [
+            ["tools", "tools"],
+            ["skills", "skills"],
+            ["extensions", "extensions"],
+            ["mcp-connections", "MCP connections"],
+            ["host-connections", "host MCP connections"],
+            ["connections", "MCP connections"],
+            ["subagents", "nested subagents"],
+            ["channels", "channels"],
+            ["schedules", "schedules"],
+            ["hooks", "hooks"],
+            ["sandbox", "sandbox files"],
+        ];
+        for (const [slot, label] of unsupported) {
+            if (yield isDirectory(join(subagentDir, slot))) {
+                ctx.diagnostics.push({
+                    severity: "warning",
+                    path: displayPath(ctx, join(subagentDir, slot)),
+                    message: `Subagent ${label} are not supported on the Cursor harness yet; the subagent runs with the parent's execution surface. Ignoring.`,
+                });
+            }
+        }
+    });
+}
+export function warnUnknownSlots(ctx, agentDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const known = new Set([
+            "agent",
+            "instructions",
+            "tools",
+            "skills",
+            "extensions",
+            "mcp-connections",
+            "host-connections",
+            // Legacy slot name; resolveMcpConnectionsDir warns and still loads it.
+            "connections",
+            "subagents",
+            "channels",
+            "schedules",
+            "hooks",
+            "ab",
+            "sandbox",
+            "lib",
+            // Vite playground custom tool chips (agent/playground/tools).
+            "playground",
+        ]);
+        for (const entry of yield sortedEntries(agentDir)) {
+            if (!entry.isDirectory() || entry.name.startsWith(".")) {
+                continue;
+            }
+            if (entry.name === "node_modules" || known.has(entry.name)) {
+                continue;
+            }
+            // Footgun: evals live at project-root `evals/`, not under `agent/`.
+            if (entry.name === "evals") {
+                ctx.diagnostics.push({
+                    severity: "warning",
+                    path: displayPath(ctx, join(agentDir, entry.name)),
+                    message: 'Directory "evals" under agent/ is ignored — put defineEval files at project-root evals/ instead.',
+                });
+                continue;
+            }
+            ctx.diagnostics.push({
+                severity: "warning",
+                path: displayPath(ctx, join(agentDir, entry.name)),
+                message: `Unrecognized directory "${entry.name}" under agent/ (not an authored slot; use lib/ for shared code).`,
+            });
+        }
+    });
+}

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

@@ -0,0 +1,10 @@
+/**
+ * `agent/channels/*.ts`: HTTP surfaces beyond the session API.
+ */
+import type { DiscoveredChannel, HttpChannelDefinition } from "../../types.js";
+import { type DiscoveryContext } from "./context.js";
+export declare function loadChannels(ctx: DiscoveryContext, channelsDir: string): Promise<{
+    channels: DiscoveredChannel[];
+    httpChannelDefinition: HttpChannelDefinition | undefined;
+}>;
+//# sourceMappingURL=channels.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"channels.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/channels.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAEV,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,KAAK,gBAAgB,EAA6B,MAAM,cAAc,CAAC;AAIhF,wBAAsB,YAAY,CAChC,GAAG,EAAE,gBAAgB,EACrB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IACT,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,qBAAqB,EAAE,qBAAqB,GAAG,SAAS,CAAC;CAC1D,CAAC,CAgFD"}

package/dist/internal/discovery/channels.js

@@ -0,0 +1,97 @@
+/**
+ * `agent/channels/*.ts`: HTTP surfaces beyond the session API.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { join } from "node:path";
+import { httpChannel } from "../../channels.js";
+import { getDefinitionKind } from "../brand.js";
+import { displayPath, errorMessage } from "./context.js";
+import { isDirectory, isModuleFile, moduleStem, sortedEntries } from "./fs.js";
+import { NAME_PATTERN } from "./names.js";
+export function loadChannels(ctx, channelsDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        var _b;
+        const channels = [];
+        let httpChannelDefinition;
+        if (!(yield isDirectory(channelsDir))) {
+            return { channels, httpChannelDefinition };
+        }
+        for (const entry of yield sortedEntries(channelsDir)) {
+            const entryPath = join(channelsDir, entry.name);
+            if (!entry.isFile() || !isModuleFile(entry.name)) {
+                continue;
+            }
+            const id = moduleStem(entry.name);
+            if (!NAME_PATTERN.test(id)) {
+                ctx.diagnostics.push({
+                    severity: "error",
+                    path: displayPath(ctx, entryPath),
+                    message: `Channel id "${id}" must match ${NAME_PATTERN}.`,
+                });
+                continue;
+            }
+            let mod;
+            try {
+                mod = yield ctx.importModule(entryPath);
+            }
+            catch (error) {
+                ctx.diagnostics.push({
+                    severity: "error",
+                    path: displayPath(ctx, entryPath),
+                    message: `Failed to load module: ${errorMessage(error)}`,
+                });
+                continue;
+            }
+            const kind = getDefinitionKind(mod.default);
+            if (kind === "http-channel") {
+                if (id !== "http") {
+                    ctx.diagnostics.push({
+                        severity: "error",
+                        path: displayPath(ctx, entryPath),
+                        message: "httpChannel() configures the built-in HTTP channel and must be authored at channels/http.ts.",
+                    });
+                    continue;
+                }
+                httpChannelDefinition = mod.default;
+                continue;
+            }
+            if (kind !== "channel") {
+                ctx.diagnostics.push({
+                    severity: "error",
+                    path: displayPath(ctx, entryPath),
+                    message: id === "http"
+                        ? "channels/http.ts must default-export httpChannel({ ... })."
+                        : "Channel modules must default-export defineChannel({ ... }).",
+                });
+                continue;
+            }
+            if (id === "http") {
+                ctx.diagnostics.push({
+                    severity: "error",
+                    path: displayPath(ctx, entryPath),
+                    message: "The channel id `http` is reserved for the built-in HTTP channel; use httpChannel() to configure it.",
+                });
+                continue;
+            }
+            const definition = mod.default;
+            for (const notice of (_b = (_a = definition.meta) === null || _a === void 0 ? void 0 : _a.deprecations) !== null && _b !== void 0 ? _b : []) {
+                ctx.diagnostics.push({
+                    severity: "warning",
+                    path: displayPath(ctx, entryPath),
+                    message: notice,
+                });
+            }
+            channels.push({ id, definition });
+        }
+        return { channels, httpChannelDefinition };
+    });
+}

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

@@ -0,0 +1,17 @@
+/**
+ * `agent/mcp-connections/*.ts` and `agent/host-connections/*.ts`: MCP servers for the model and the host.
+ */
+import { type ConnectionDefinition, type ConnectionTransport, type DiscoveredConnection } from "../../types.js";
+import { type DiscoveryContext } from "./context.js";
+/** One-line `/v1/info` label for a connection transport. */
+export declare function connectionTransportLabel(transport: ConnectionTransport): string;
+/**
+ * Prefer `agent/mcp-connections/`. Keep loading `agent/connections/` with a
+ * deprecation warning so existing agents keep working during the rename.
+ */
+export declare function resolveMcpConnectionsDir(ctx: DiscoveryContext, agentDir: string): Promise<string>;
+export declare function loadHostConnections(ctx: DiscoveryContext, agentDir: string, modelConnections: readonly DiscoveredConnection[]): Promise<DiscoveredConnection[]>;
+export declare function loadConnections(ctx: DiscoveryContext, connectionsDir: string, role?: "model" | "host"): Promise<DiscoveredConnection[]>;
+/** Validate one `defineConnection` and resolve its transport. */
+export declare function compileConnection(ctx: DiscoveryContext, entryPath: string, name: string, connection: ConnectionDefinition, role: "model" | "host"): Promise<DiscoveredConnection | undefined>;
+//# sourceMappingURL=connections.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connections.d.ts","sourceRoot":"","sources":["../../../src/internal/discovery/connections.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EAExB,KAAK,oBAAoB,EAQ1B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,KAAK,gBAAgB,EAItB,MAAM,cAAc,CAAC;AAKtB,4DAA4D;AAC5D,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,mBAAmB,GAC7B,MAAM,CAeR;AAkGD;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAwBjB;AAED,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,SAAS,oBAAoB,EAAE,GAChD,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAqCjC;AAED,wBAAsB,eAAe,CACnC,GAAG,EAAE,gBAAgB,EACrB,cAAc,EAAE,MAAM,EACtB,IAAI,GAAE,OAAO,GAAG,MAAgB,GAC/B,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAuBjC;AAED,iEAAiE;AACjE,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,oBAAoB,EAChC,IAAI,EAAE,OAAO,GAAG,MAAM,GACrB,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAuN3C"}