@cursor/july 0.1.102 → 0.1.104

package/src/internal/discovery/agent.ts

@@ -3,8 +3,22 @@
  */
 
 import { join } from "node:path";
-import { DEFAULT_MODEL, type ResolvedAgent } from "../../types.js";
-import { builtinTools } from "../builtin-tools/index.js";
+import {
+  canonicalizeFileSystemToolName,
+  FileSystemConfigError,
+  resolveFileSystemTools,
+  resolveRootHarnessAllowlist,
+} from "../../filesystem.js";
+import {
+  type ArtifactsDefinition,
+  DEFAULT_MODEL,
+  type DiscoveredAB,
+  type DiscoveredChannel,
+  type DiscoveredHook,
+  type DiscoveredSchedule,
+  type ResolvedAgent,
+} from "../../types.js";
+import { synthesizedFileSystemToolNames } from "../filesystem/tools.js";
 import { withIdentityPreamble } from "../workspace.js";
 import {
   isValidModelSetting,
@@ -16,16 +30,12 @@ import {
   resolveLocalCwd,
   runtimeArchitectureCompatibilityError,
 } from "./agent-config.js";
-import {
-  loadConnections,
-  loadHostConnections,
-  resolveMcpConnectionsDir,
-} from "./connections.js";
+import { loadConnections, loadHostConnections } from "./connections.js";
 import { type DiscoveryContext, displayPath } from "./context.js";
+import type { ExtensionContributions } from "./extensions.js";
 import { appendExtensions } from "./extensions.js";
-import { findModuleFile, isDirectory, sortedEntries } from "./fs.js";
+import { sortedEntries } from "./fs.js";
 import { loadInstructions } from "./instructions.js";
-import { validateName } from "./names.js";
 import {
   checkGrokBotRuntimeLimitations,
   resolveRuntime,
@@ -33,14 +43,34 @@ import {
 } from "./runtime.js";
 import { loadSeedFiles } from "./seed-files.js";
 import { loadSkills } from "./skills.js";
-import { subagent } from "./subagent.js";
+import { loadSubagent, loadSubagents } from "./subagent.js";
 import { appendBuiltinTools, loadTools } from "./tools.js";
 
+export interface LoadedRootAgent {
+  agent: ResolvedAgent;
+  projectSlots: Pick<
+    ExtensionContributions,
+    "hooks" | "channels" | "schedules" | "abs" | "artifacts"
+  >;
+}
+
 export async function loadAgent(
   ctx: DiscoveryContext,
   agentDir: string,
   options: { name: string; isRoot: boolean }
-): Promise<ResolvedAgent> {
+): Promise<LoadedRootAgent> {
+  if (!options.isRoot) {
+    return {
+      agent: await loadSubagent(ctx, agentDir, options.name),
+      projectSlots: {
+        hooks: [],
+        channels: [],
+        schedules: [],
+        abs: [],
+        artifacts: undefined,
+      },
+    };
+  }
   const config = await loadAgentConfig(ctx, agentDir, options.isRoot);
   const name = config?.name ?? options.name;
   const authoredInstructions = await loadInstructions(
@@ -49,69 +79,49 @@ export async function loadAgent(
     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) {
-    await warnUnsupportedSubagentSlots(ctx, agentDir);
-    if (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?.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?.architecture !== undefined) {
-      ctx.diagnostics.push({
-        severity: "warning",
-        path: displayPath(ctx, join(agentDir, "agent.ts")),
-        message: "architecture is not supported on subagents; ignoring.",
-      });
-    }
-    const artifactsPath = await 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?.description,
-      model: config?.model,
-      prompt: authoredInstructions,
-    });
-  }
 
-  // Root agents without authored instructions stay undefined (diagnostic
-  // already recorded).
-  const instructions =
-    authoredInstructions === undefined
-      ? undefined
-      : withIdentityPreamble(name, authoredInstructions);
   const tools = await loadTools(ctx, join(agentDir, "tools"));
   const skills = await loadSkills(ctx, join(agentDir, "skills"));
   const connections = await loadConnections(
     ctx,
-    await resolveMcpConnectionsDir(ctx, agentDir)
+    join(agentDir, "mcp-connections")
   );
   const subagents = await loadSubagents(ctx, join(agentDir, "subagents"));
-  const extensions = await appendExtensions(ctx, join(agentDir, "extensions"), {
+  const hostConnections = await loadHostConnections(ctx, agentDir, connections);
+  const seedFiles = await loadSeedFiles(ctx, agentDir);
+  const hooks: DiscoveredHook[] = [];
+  const channels: DiscoveredChannel[] = [];
+  const schedules: DiscoveredSchedule[] = [];
+  const abs: DiscoveredAB[] = [];
+  const instructionParts: string[] = [];
+  const contributions = {
     tools,
     skills,
     connections,
+    hostConnections,
     subagents,
-  });
-  const hostConnections = await loadHostConnections(ctx, agentDir, connections);
-  const seedFiles = await loadSeedFiles(ctx, agentDir);
+    hooks,
+    channels,
+    schedules,
+    instructionParts,
+    seedFiles,
+    abs,
+    artifacts: undefined as ArtifactsDefinition | undefined,
+  };
+  const extensions = await 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?.runtime);
   // Keep authored `cloud` even when default runtime is local — per-session
   // `send({ cloud })` merges it under cloudOverride for handoff sessions.
@@ -132,10 +142,88 @@ export async function loadAgent(
   // second layer (authored tools, mcp-connections, the harness cwd's
   // ambient config).
   const authoredAllowlist = config?.tools;
-  const allowedTools =
+  const root = config?.root;
+  const hasRoot = root !== undefined;
+  if (hasRoot) {
+    if (
+      config?.local?.cwd !== undefined ||
+      config?.local?.workspaceDir !== undefined ||
+      config?.local?.sandbox === true
+    ) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(agentDir, "agent.ts")),
+        message:
+          "`root` cannot be combined with `local.cwd`, `local.workspaceDir`, or `local.sandbox`. Those fields configure the host tree the override replaced.",
+      });
+    }
+    if (runtime === "cloud" || runtime === "grokbot") {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(agentDir, "agent.ts")),
+        message: `\`root\` cannot be combined with runtime: "${runtime}".`,
+      });
+    }
+    if (
+      authoredAllowlist?.includes("shell") === true ||
+      authoredAllowlist?.includes("Shell") === true
+    ) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(agentDir, "agent.ts")),
+        message:
+          '`root` cannot be combined with `tools` containing `"shell"`. Shell is not a FileSystem method and must not bind the host shell onto a virtual tree.',
+      });
+    }
+  }
+  const reservedNames = new Set<string>(
+    synthesizedFileSystemToolNames({
+      hasRoot,
+      tools: authoredAllowlist,
+    })
+  );
+  const clash = tools.find((tool) => {
+    if (reservedNames.has(tool.name)) {
+      return true;
+    }
+    const canonical = canonicalizeFileSystemToolName(tool.name);
+    return canonical !== undefined && reservedNames.has(canonical);
+  });
+  if (clash !== undefined) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, join(agentDir, "tools", `${clash.name}.ts`)),
+      message: `agent/tools/${clash.name}.ts: that name is reserved for the synthesized FileSystem tool.`,
+    });
+  }
+  let allowedTools =
     authoredAllowlist === undefined || authoredAllowlist.includes("mcp")
       ? authoredAllowlist
       : [...authoredAllowlist, "mcp" as const];
+  if (hasRoot) {
+    try {
+      if (typeof root !== "function") {
+        resolveFileSystemTools({
+          root,
+          tools: authoredAllowlist,
+        });
+      } else {
+        resolveRootHarnessAllowlist(authoredAllowlist);
+      }
+      allowedTools = authoredAllowlist;
+    } catch (error) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(agentDir, "agent.ts")),
+        message:
+          error instanceof FileSystemConfigError
+            ? error.message
+            : error instanceof Error
+              ? error.message
+              : String(error),
+      });
+    }
+  }
   // 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
@@ -237,79 +325,38 @@ export async function loadAgent(
   }
 
   return {
-    name,
-    description: config?.description,
-    // Root agents always get a concrete model: authored value or DEFAULT_MODEL.
-    model: isValidModelSetting(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,
+    agent: {
+      name,
+      description: config?.description,
+      // Root agents always get a concrete model: authored value or DEFAULT_MODEL.
+      model: isValidModelSetting(config?.model) ? config.model : DEFAULT_MODEL,
+      instructions,
+      runtime,
+      ...(root === undefined ? {} : { root }),
+      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,
+    },
   };
 }
 
-async function loadSubagents(
-  ctx: DiscoveryContext,
-  subagentsDir: string
-): Promise<ResolvedAgent[]> {
-  if (!(await isDirectory(subagentsDir))) {
-    return [];
-  }
-  const subagents: ResolvedAgent[] = [];
-  for (const entry of await sortedEntries(subagentsDir)) {
-    if (!entry.isDirectory()) {
-      continue;
-    }
-    const subagentDir = join(subagentsDir, entry.name);
-    if (!validateName(ctx, "subagent", entry.name, subagentDir)) {
-      continue;
-    }
-    subagents.push(
-      await loadAgent(ctx, subagentDir, { name: entry.name, isRoot: false })
-    );
-  }
-  return subagents;
-}
-
-async function warnUnsupportedSubagentSlots(
-  ctx: DiscoveryContext,
-  subagentDir: string
-): Promise<void> {
-  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"],
-  ] as const;
-  for (const [slot, label] of unsupported) {
-    if (await 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 async function warnUnknownSlots(
   ctx: DiscoveryContext,
   agentDir: string
@@ -322,8 +369,6 @@ export async function warnUnknownSlots(
     "extensions",
     "mcp-connections",
     "host-connections",
-    // Legacy slot name; resolveMcpConnectionsDir warns and still loads it.
-    "connections",
     "subagents",
     "channels",
     "schedules",

package/src/internal/discovery/channels.ts

@@ -3,7 +3,6 @@
  */
 
 import { join } from "node:path";
-import { httpChannel } from "../../channels.js";
 import type {
   ChannelDefinition,
   DiscoveredChannel,
@@ -12,11 +11,13 @@ import type {
 import { getDefinitionKind } from "../brand.js";
 import { type DiscoveryContext, displayPath, errorMessage } from "./context.js";
 import { isDirectory, isModuleFile, moduleStem, sortedEntries } from "./fs.js";
-import { NAME_PATTERN } from "./names.js";
+import { validateName } from "./names.js";
 
 export async function loadChannels(
   ctx: DiscoveryContext,
-  channelsDir: string
+  channelsDir: string,
+  mode: "agent" | "extension" = "agent",
+  onDisable?: (id: string, path: string) => void
 ): Promise<{
   channels: DiscoveredChannel[];
   httpChannelDefinition: HttpChannelDefinition | undefined;
@@ -33,12 +34,7 @@ export async function loadChannels(
       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}.`,
-      });
+    if (!validateName(ctx, "channel", id, entryPath)) {
       continue;
     }
 
@@ -54,14 +50,20 @@ export async function loadChannels(
       continue;
     }
     const kind = getDefinitionKind(mod.default);
+    if (kind === "disabled") {
+      onDisable?.(id, entryPath);
+      continue;
+    }
 
     if (kind === "http-channel") {
-      if (id !== "http") {
+      if (mode === "extension" || 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.",
+            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;
       }
@@ -74,13 +76,13 @@ export async function loadChannels(
         severity: "error",
         path: displayPath(ctx, entryPath),
         message:
-          id === "http"
+          id === "http" && mode === "agent"
             ? "channels/http.ts must default-export httpChannel({ ... })."
             : "Channel modules must default-export defineChannel({ ... }).",
       });
       continue;
     }
-    if (id === "http") {
+    if (id === "http" && mode === "agent") {
       ctx.diagnostics.push({
         severity: "error",
         path: displayPath(ctx, entryPath),

package/src/internal/discovery/connections.ts

@@ -23,7 +23,6 @@ import {
   errorMessage,
   isBlank,
 } from "./context.js";
-import { isDirectory } from "./fs.js";
 import { importDefault, moduleEntries } from "./modules.js";
 import { NAME_PATTERN } from "./names.js";
 
@@ -143,39 +142,6 @@ function connectionTransport(
   return undefined;
 }
 
-/**
- * Prefer `agent/mcp-connections/`. Keep loading `agent/connections/` with a
- * deprecation warning so existing agents keep working during the rename.
- */
-export async function resolveMcpConnectionsDir(
-  ctx: DiscoveryContext,
-  agentDir: string
-): Promise<string> {
-  const preferred = join(agentDir, "mcp-connections");
-  const legacy = join(agentDir, "connections");
-  const hasPreferred = await isDirectory(preferred);
-  const hasLegacy = await isDirectory(legacy);
-  if (hasPreferred && hasLegacy) {
-    ctx.diagnostics.push({
-      severity: "warning",
-      path: displayPath(ctx, legacy),
-      message:
-        "Both agent/mcp-connections/ and agent/connections/ exist; using mcp-connections/ and ignoring connections/. Rename or remove the legacy directory.",
-    });
-    return preferred;
-  }
-  if (hasLegacy) {
-    ctx.diagnostics.push({
-      severity: "warning",
-      path: displayPath(ctx, legacy),
-      message:
-        "agent/connections/ is deprecated; rename it to agent/mcp-connections/. Loading from the legacy path for now.",
-    });
-    return legacy;
-  }
-  return preferred;
-}
-
 export async function loadHostConnections(
   ctx: DiscoveryContext,
   agentDir: string,
@@ -196,22 +162,13 @@ export async function loadHostConnections(
       });
       continue;
     }
-    if (connection.advertiseTools === true) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, join(hostDir, `${connection.name}.ts`)),
-        message:
-          "Host connections are off the model. `advertiseTools` cannot apply. Drop it.",
-      });
-      continue;
-    }
-    if (connection.auth !== undefined) {
-      ctx.diagnostics.push({
-        severity: "error",
-        path: displayPath(ctx, join(hostDir, `${connection.name}.ts`)),
-        message:
-          "Host connections are off the model. `auth` cannot apply. Use static headers or `oauth: true`.",
-      });
+    if (
+      rejectHostConnectionFeatures(
+        ctx,
+        join(hostDir, `${connection.name}.ts`),
+        connection
+      )
+    ) {
       continue;
     }
     hostConnections.push(connection);
@@ -219,6 +176,54 @@ export async function loadHostConnections(
   return hostConnections;
 }
 
+export async function compileHostConnection(
+  ctx: DiscoveryContext,
+  path: string,
+  name: string,
+  definition: ConnectionDefinition
+): Promise<DiscoveredConnection | undefined> {
+  const connection = await compileConnection(
+    ctx,
+    path,
+    name,
+    definition,
+    "host"
+  );
+  if (
+    connection === undefined ||
+    rejectHostConnectionFeatures(ctx, path, connection)
+  ) {
+    return undefined;
+  }
+  return connection;
+}
+
+function rejectHostConnectionFeatures(
+  ctx: DiscoveryContext,
+  path: string,
+  connection: DiscoveredConnection
+): boolean {
+  if (connection.advertiseTools === true) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, path),
+      message:
+        "Host connections are off the model. `advertiseTools` cannot apply. Drop it.",
+    });
+    return true;
+  }
+  if (connection.auth !== undefined) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, path),
+      message:
+        "Host connections are off the model. `auth` cannot apply. Use static headers or `oauth: true`.",
+    });
+    return true;
+  }
+  return false;
+}
+
 export async function loadConnections(
   ctx: DiscoveryContext,
   connectionsDir: string,

package/src/internal/discovery/cursor-plugin.ts

@@ -11,6 +11,7 @@ import type {
   DiscoveredSkill,
 } from "../../types.js";
 import { parseYamlFrontmatter } from "../frontmatter.js";
+import { isRecord } from "../is-record.js";
 import {
   type DiscoveryContext,
   displayPath,
@@ -702,7 +703,3 @@ function firstIssue(error: z.ZodError): string {
 function fileStem(path: string): string {
   return basename(path, extname(path));
 }
-
-function isRecord(value: unknown): value is JsonRecord {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}