@cursor/july 0.1.101 → 0.1.102

package/src/internal/discovery/agent.ts

@@ -0,0 +1,360 @@
+/**
+ * Compile one `agent/` directory (and its subagents) into a {@link ResolvedAgent}.
+ */
+
+import { join } from "node:path";
+import { DEFAULT_MODEL, type ResolvedAgent } 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 { type DiscoveryContext, 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 async function loadAgent(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  options: { name: string; isRoot: boolean }
+): Promise<ResolvedAgent> {
+  const config = await loadAgentConfig(ctx, agentDir, options.isRoot);
+  const name = config?.name ?? options.name;
+  const authoredInstructions = await 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) {
+    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)
+  );
+  const subagents = await loadSubagents(ctx, join(agentDir, "subagents"));
+  const extensions = await appendExtensions(ctx, join(agentDir, "extensions"), {
+    tools,
+    skills,
+    connections,
+    subagents,
+  });
+  const hostConnections = await loadHostConnections(ctx, agentDir, connections);
+  const seedFiles = await loadSeedFiles(ctx, agentDir);
+  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.
+  const cloud = config?.cloud;
+  const localWorkspaceDir = resolveAgentCwd(ctx, config?.local?.workspaceDir);
+  const localCwd = await resolveLocalCwd(
+    ctx,
+    config?.local?.cwd,
+    config?.local?.workspaceDir
+  );
+  const localSandbox = config?.local?.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?.tools;
+  const allowedTools =
+    authoredAllowlist === undefined || authoredAllowlist.includes("mcp")
+      ? authoredAllowlist
+      : [...authoredAllowlist, "mcp" as const];
+  // 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?.hosting);
+  const concurrency = resolveConcurrency(ctx, agentDir, config?.concurrency);
+  const architecture = resolveArchitecture(ctx, agentDir, 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?.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 {
+    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,
+  };
+}
+
+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
+): Promise<void> {
+  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 await 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/src/internal/discovery/channels.ts

@@ -0,0 +1,103 @@
+/**
+ * `agent/channels/*.ts`: HTTP surfaces beyond the session API.
+ */
+
+import { join } from "node:path";
+import { httpChannel } from "../../channels.js";
+import type {
+  ChannelDefinition,
+  DiscoveredChannel,
+  HttpChannelDefinition,
+} from "../../types.js";
+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";
+
+export async function loadChannels(
+  ctx: DiscoveryContext,
+  channelsDir: string
+): Promise<{
+  channels: DiscoveredChannel[];
+  httpChannelDefinition: HttpChannelDefinition | undefined;
+}> {
+  const channels: DiscoveredChannel[] = [];
+  let httpChannelDefinition: HttpChannelDefinition | undefined;
+  if (!(await isDirectory(channelsDir))) {
+    return { channels, httpChannelDefinition };
+  }
+
+  for (const entry of await 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: Record<string, unknown>;
+    try {
+      mod = await 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 as HttpChannelDefinition;
+      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 as ChannelDefinition;
+    for (const notice of definition.meta?.deprecations ?? []) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, entryPath),
+        message: notice,
+      });
+    }
+    channels.push({ id, definition });
+  }
+  return { channels, httpChannelDefinition };
+}