@cursor/july 0.1.101 → 0.1.103

package/dist/internal/discovery/agent.js

@@ -0,0 +1,255 @@
+/**
+ * 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 { withIdentityPreamble } from "../workspace.js";
+import { isValidModelSetting, loadAgentConfig, resolveAgentCwd, resolveArchitecture, resolveConcurrency, resolveHosting, resolveLocalCwd, runtimeArchitectureCompatibilityError, } from "./agent-config.js";
+import { loadConnections, loadHostConnections } from "./connections.js";
+import { displayPath } from "./context.js";
+import { appendExtensions } from "./extensions.js";
+import { sortedEntries } from "./fs.js";
+import { loadInstructions } from "./instructions.js";
+import { checkGrokBotRuntimeLimitations, resolveRuntime, warnCloudRuntimeLimitations, } from "./runtime.js";
+import { loadSeedFiles } from "./seed-files.js";
+import { loadSkills } from "./skills.js";
+import { loadSubagent, loadSubagents } 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;
+        if (!options.isRoot) {
+            return {
+                agent: yield loadSubagent(ctx, agentDir, options.name),
+                projectSlots: {
+                    hooks: [],
+                    channels: [],
+                    schedules: [],
+                    abs: [],
+                    artifacts: undefined,
+                },
+            };
+        }
+        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);
+        const tools = yield loadTools(ctx, join(agentDir, "tools"));
+        const skills = yield loadSkills(ctx, join(agentDir, "skills"));
+        const connections = yield loadConnections(ctx, join(agentDir, "mcp-connections"));
+        const subagents = yield loadSubagents(ctx, join(agentDir, "subagents"));
+        const hostConnections = yield loadHostConnections(ctx, agentDir, connections);
+        const seedFiles = yield loadSeedFiles(ctx, agentDir);
+        const hooks = [];
+        const channels = [];
+        const schedules = [];
+        const abs = [];
+        const instructionParts = [];
+        const contributions = {
+            tools,
+            skills,
+            connections,
+            hostConnections,
+            subagents,
+            hooks,
+            channels,
+            schedules,
+            instructionParts,
+            seedFiles,
+            abs,
+            artifacts: undefined,
+        };
+        const extensions = yield appendExtensions(ctx, join(agentDir, "extensions"), contributions);
+        const promptParts = [...instructionParts];
+        if (authoredInstructions !== undefined && authoredInstructions !== "") {
+            promptParts.unshift(authoredInstructions);
+        }
+        const prompt = promptParts.join("\n\n");
+        // Root agents without authored instructions stay undefined (diagnostic
+        // already recorded) unless an extension contributed a fragment.
+        const instructions = prompt === "" ? undefined : withIdentityPreamble(name, prompt);
+        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 {
+            agent: 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 }),
+            projectSlots: {
+                hooks,
+                channels,
+                schedules,
+                abs,
+                artifacts: contributions.artifacts,
+            },
+        };
+    });
+}
+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",
+            "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, mode?: "agent" | "extension", onDisable?: (id: string, path: string) => void): 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;AAGH,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,EACnB,IAAI,GAAE,OAAO,GAAG,WAAqB,EACrC,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GAC7C,OAAO,CAAC;IACT,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,qBAAqB,EAAE,qBAAqB,GAAG,SAAS,CAAC;CAC1D,CAAC,CAiFD"}

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 { getDefinitionKind } from "../brand.js";
+import { displayPath, errorMessage } from "./context.js";
+import { isDirectory, isModuleFile, moduleStem, sortedEntries } from "./fs.js";
+import { validateName } from "./names.js";
+export function loadChannels(ctx_1, channelsDir_1) {
+    return __awaiter(this, arguments, void 0, function* (ctx, channelsDir, mode = "agent", onDisable) {
+        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 (!validateName(ctx, "channel", id, entryPath)) {
+                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 === "disabled") {
+                onDisable === null || onDisable === void 0 ? void 0 : onDisable(id, entryPath);
+                continue;
+            }
+            if (kind === "http-channel") {
+                if (mode === "extension" || id !== "http") {
+                    ctx.diagnostics.push({
+                        severity: "error",
+                        path: displayPath(ctx, entryPath),
+                        message: mode === "extension"
+                            ? "httpChannel() configures the agent's built-in HTTP channel; an extension cannot contribute it."
+                            : "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" && mode === "agent"
+                        ? "channels/http.ts must default-export httpChannel({ ... })."
+                        : "Channel modules must default-export defineChannel({ ... }).",
+                });
+                continue;
+            }
+            if (id === "http" && mode === "agent") {
+                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,13 @@
+/**
+ * `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;
+export declare function loadHostConnections(ctx: DiscoveryContext, agentDir: string, modelConnections: readonly DiscoveredConnection[]): Promise<DiscoveredConnection[]>;
+export declare function compileHostConnection(ctx: DiscoveryContext, path: string, name: string, definition: ConnectionDefinition): Promise<DiscoveredConnection | undefined>;
+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;AAItB,4DAA4D;AAC5D,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,mBAAmB,GAC7B,MAAM,CAeR;AAkGD,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,SAAS,oBAAoB,EAAE,GAChD,OAAO,CAAC,oBAAoB,EAAE,CAAC,CA4BjC;AAED,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,oBAAoB,GAC/B,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAe3C;AA4BD,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"}