@cursor/july 0.1.102 → 0.1.103

package/src/internal/discovery/agent.ts

@@ -3,8 +3,15 @@
  */
 
 import { join } from "node:path";
-import { DEFAULT_MODEL, type ResolvedAgent } from "../../types.js";
-import { builtinTools } from "../builtin-tools/index.js";
+import {
+  type ArtifactsDefinition,
+  DEFAULT_MODEL,
+  type DiscoveredAB,
+  type DiscoveredChannel,
+  type DiscoveredHook,
+  type DiscoveredSchedule,
+  type ResolvedAgent,
+} from "../../types.js";
 import { withIdentityPreamble } from "../workspace.js";
 import {
   isValidModelSetting,
@@ -16,16 +23,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 +36,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 +72,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.
@@ -237,79 +240,37 @@ 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,
+      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 +283,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);
-}