@cursor/july 0.1.102 → 0.1.104

package/src/internal/discovery/modules.ts

@@ -71,13 +71,15 @@ export async function importDefault(
     return mod.default;
   }
   const helpers = kinds.map(helperCall).join(" or ");
+  const expectedKinds = kinds.join(" or ");
+  const article = /^[aeiou]/.test(expectedKinds) ? "an" : "a";
   ctx.diagnostics.push({
     severity: "error",
     path: displayPath(ctx, modulePath),
     message:
       kind === undefined
         ? `Module must default-export ${helpers}.`
-        : `Expected a ${kinds.join(" or ")} definition but found "${kind}" (wrong authored slot?).`,
+        : `Expected ${article} ${expectedKinds} definition but found "${kind}" (wrong authored slot?).`,
   });
   return undefined;
 }
@@ -85,7 +87,9 @@ export async function importDefault(
 /** How a definition of `kind` is authored: `defineTool({ ... })`, `disableTool()`. */
 export function helperCall(kind: ImportableKind): string {
   const name = DEFINE_HELPER_NAME[kind];
-  return kind.startsWith("disabled-") ? `${name}()` : `${name}({ ... })`;
+  return kind === "disabled" || kind.startsWith("disabled-")
+    ? `${name}()`
+    : `${name}({ ... })`;
 }
 
 const DEFINE_HELPER_NAME: Record<ImportableKind, string> = {
@@ -95,6 +99,7 @@ const DEFINE_HELPER_NAME: Record<ImportableKind, string> = {
   extension: "defineExtension",
   "disabled-tool": "disableTool",
   "disabled-connection": "disableConnection",
+  disabled: "disable",
   connection: "defineConnection",
   channel: "defineChannel",
   "http-channel": "httpChannel",
@@ -104,4 +109,5 @@ const DEFINE_HELPER_NAME: Record<ImportableKind, string> = {
   storage: "defineStorage",
   artifacts: "defineArtifacts",
   otel: "defineOtel",
+  result: "defineResult",
 };

package/src/internal/discovery/names.ts

@@ -13,7 +13,7 @@ export const NAME_PATTERN: RegExp = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
  */
 export function validateName(
   ctx: DiscoveryContext,
-  kind: "skill" | "tool" | "extension" | "connection" | "subagent",
+  kind: "skill" | "tool" | "extension" | "connection" | "subagent" | "channel",
   name: string,
   entryPath: string
 ): boolean {
@@ -23,6 +23,7 @@ export function validateName(
     extension: "Extension",
     connection: "MCP connection",
     subagent: "Subagent",
+    channel: "Channel",
   }[kind];
   if (!NAME_PATTERN.test(name)) {
     ctx.diagnostics.push({

package/src/internal/discovery/project.ts

@@ -4,15 +4,23 @@
 
 import { basename, join, resolve } from "node:path";
 import { httpChannel } from "../../channels.js";
-import type { AgentProject, Diagnostic } from "../../types.js";
+import type {
+  AgentProject,
+  ArtifactsDefinition,
+  Diagnostic,
+} from "../../types.js";
 import { registerAuthoredModuleLoaders } from "../authored-loaders.js";
-import { applyAgentContinuationDefaults } from "../continuation-channel.js";
+import {
+  applyAgentContinuationDefaults,
+  warnOmittedContinuationDowngrades,
+} from "../continuation-channel.js";
 import { loadABConfig, loadABs } from "./ab.js";
 import { loadAgent, warnUnknownSlots } from "./agent.js";
 import { loadChannels } from "./channels.js";
 import {
   type DiscoveryContext,
   defaultImportModule,
+  displayPath,
   type LoadAgentProjectOptions,
 } from "./context.js";
 import {
@@ -28,7 +36,9 @@ import {
   appendArtifactTool,
   loadArtifacts,
   loadOtel,
+  loadResult,
   loadStorage,
+  mergeArtifacts,
 } from "./services.js";
 
 /**
@@ -170,11 +180,7 @@ function assertSlug(name: string, parentDir: string): string {
 }
 
 /** URL path segments reserved by the server; agents cannot use them as slugs. */
-export const RESERVED_SLUGS: Set<string> = new Set([
-  "v1",
-  "playground",
-  "docs",
-]);
+const RESERVED_SLUGS: Set<string> = new Set(["v1", "playground", "docs"]);
 
 export async function loadAgentProject(
   dir: string,
@@ -208,7 +214,7 @@ export async function loadAgentProject(
   };
 
   const name = (await readPackageName(rootDir)) ?? basename(rootDir);
-  const agent = await loadAgent(ctx, agentDir, {
+  const { agent, projectSlots } = await loadAgent(ctx, agentDir, {
     name,
     isRoot: true,
   });
@@ -217,13 +223,42 @@ export async function loadAgentProject(
     ctx,
     join(agentDir, "channels")
   );
+  for (const channel of projectSlots.channels) {
+    if (channel.id === "http" || channels.some((c) => c.id === channel.id)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(agentDir, "extensions")),
+        message: `Extension channel "${channel.id}" collides with an agent channel.`,
+      });
+      continue;
+    }
+    channels.push(channel);
+  }
   const schedules = await loadSchedules(ctx, join(agentDir, "schedules"));
+  schedules.push(...projectSlots.schedules);
   const hooks = await loadHooks(ctx, join(agentDir, "hooks"));
+  hooks.push(...projectSlots.hooks);
   const abs = await loadABs(ctx, agentDir);
+  for (const experiment of projectSlots.abs) {
+    if (abs.some((existing) => existing.name === experiment.name)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(agentDir, "extensions")),
+        message: `Extension A/B experiment "${experiment.name}" collides with an agent experiment.`,
+      });
+      continue;
+    }
+    abs.push(experiment);
+  }
   const abConfig = await loadABConfig(ctx, agentDir);
   const storage = await loadStorage(ctx, agentDir, agent.architecture);
-  const artifacts = await loadArtifacts(ctx, agentDir);
+  const artifacts = await mergeProjectArtifacts(
+    ctx,
+    agentDir,
+    projectSlots.artifacts
+  );
   const otel = await loadOtel(ctx, agentDir);
+  const result = await loadResult(ctx, agentDir);
   await appendArtifactTool(ctx, agentDir, agent, artifacts);
 
   if (agentDir !== rootDir) {
@@ -231,6 +266,17 @@ export async function loadAgentProject(
   }
 
   const resolvedHttpChannel = httpChannelDefinition ?? httpChannel();
+  warnOmittedContinuationDowngrades({
+    architecture: agent.architecture,
+    channels,
+    warn: (id, message) => {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, join(agentDir, "channels", `${id}.ts`)),
+        message,
+      });
+    },
+  });
   applyAgentContinuationDefaults({
     agent,
     channels,
@@ -250,11 +296,36 @@ export async function loadAgentProject(
     abConfig,
     storage,
     artifacts,
+    result,
     otel,
     diagnostics,
   };
 }
 
+async function mergeProjectArtifacts(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  extra: ArtifactsDefinition | undefined
+): Promise<ArtifactsDefinition | undefined> {
+  const agent = await loadArtifacts(ctx, agentDir);
+  if (extra === undefined) {
+    return agent;
+  }
+  const kinds = { ...extra.kinds };
+  const agentKinds = agent?.kinds;
+  for (const kind of Object.keys(kinds)) {
+    if (agentKinds !== undefined && kind in agentKinds) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(agentDir, "extensions")),
+        message: `Extension artifact kind "${kind}" collides with an agent kind.`,
+      });
+      delete kinds[kind];
+    }
+  }
+  return mergeArtifacts(agent, { ...extra, kinds });
+}
+
 /** True when the project has diagnostics that must block serving. */
 export function hasErrorDiagnostics(project: AgentProject): boolean {
   return project.diagnostics.some((d) => d.severity === "error");

package/src/internal/discovery/runtime.ts

@@ -4,7 +4,6 @@
 
 import { join } from "node:path";
 import type { AgentRuntime } from "../../types.js";
-import { builtinTools } from "../builtin-tools/index.js";
 import { type DiscoveryContext, displayPath } from "./context.js";
 
 /**
@@ -153,7 +152,7 @@ export function warnCloudRuntimeLimitations(
       severity: "warning",
       path: displayPath(ctx, join(agentDir, "sandbox")),
       message:
-        "sandbox/workspace seed files apply to the local session workspace only; cloud agents use the configured cloud repos.",
+        "sandbox/workspace seed files reach cloud agents through the Agent Store, not the checkout: hosted deployments write the deployment store's workspace/ directory; local serve/run with a personal API key writes agent-serve/<agent>/workspace/ on the USER store. The first cloud prompt names the mounted directory. Without a reachable store, cloud turns do not see them.",
     });
   }
 }

package/src/internal/discovery/schedules.ts

@@ -5,6 +5,7 @@
 import { readFile } from "node:fs/promises";
 import { basename, extname, relative } from "node:path";
 import type { DiscoveredSchedule, ScheduleDefinition } from "../../types.js";
+import { getDefinitionKind } from "../brand.js";
 import { isValidCron } from "../cron.js";
 import { parseFrontmatter } from "../frontmatter.js";
 import { type DiscoveryContext, displayPath } from "./context.js";
@@ -13,7 +14,8 @@ import { importDefault } from "./modules.js";
 
 export async function loadSchedules(
   ctx: DiscoveryContext,
-  schedulesDir: string
+  schedulesDir: string,
+  onDisable?: (name: string, path: string) => void
 ): Promise<DiscoveredSchedule[]> {
   if (!(await isDirectory(schedulesDir))) {
     return [];
@@ -23,6 +25,14 @@ export async function loadSchedules(
     const rel = toPosix(relative(schedulesDir, filePath));
     if (rel.endsWith(".md")) {
       const name = rel.slice(0, -".md".length);
+      if (name.includes("__")) {
+        ctx.diagnostics.push({
+          severity: "error",
+          path: displayPath(ctx, filePath),
+          message: `Schedule name "${name}" may not contain "__"; it is reserved for extension contributions (\`<ns>__<name>\`).`,
+        });
+        continue;
+      }
       const { data, body } = parseFrontmatter(await readFile(filePath, "utf8"));
       const cron = data.cron;
       if (cron === undefined || !isValidCron(cron)) {
@@ -62,10 +72,26 @@ export async function loadSchedules(
       continue;
     }
     const name = rel.slice(0, -extname(rel).length);
-    const definition = await importDefault(ctx, filePath, "schedule");
+    if (name.includes("__")) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, filePath),
+        message: `Schedule name "${name}" may not contain "__"; it is reserved for extension contributions (\`<ns>__<name>\`).`,
+      });
+      continue;
+    }
+    const definition = await importDefault(
+      ctx,
+      filePath,
+      onDisable === undefined ? "schedule" : ["schedule", "disabled"]
+    );
     if (definition === undefined) {
       continue;
     }
+    if (getDefinitionKind(definition) === "disabled") {
+      onDisable?.(name, filePath);
+      continue;
+    }
     const schedule = definition as ScheduleDefinition;
     if ((schedule.markdown === undefined) === (schedule.run === undefined)) {
       ctx.diagnostics.push({

package/src/internal/discovery/services.ts

@@ -1,14 +1,17 @@
 /**
- * `agent/storage.ts`, `agent/otel.ts`, `agent/artifacts.ts`: host services the agent configures.
+ * `agent/storage.ts`, `agent/otel.ts`, `agent/artifacts.ts`,
+ * `agent/result.ts`: host services the agent configures.
  */
 
 import { join } from "node:path";
+import { defineArtifacts } from "../../artifacts.js";
 import type { OtelDefinition } from "../../otel.js";
 import type { StorageDefinition } from "../../storage.js";
 import type {
   AgentArchitecture,
   ArtifactsDefinition,
   ResolvedAgent,
+  ResultDefinition,
 } from "../../types.js";
 import {
   artifactBuiltinTool,
@@ -92,6 +95,39 @@ export async function loadArtifacts(
   return definition;
 }
 
+export async function loadResult(
+  ctx: DiscoveryContext,
+  agentDir: string
+): Promise<ResultDefinition | undefined> {
+  const path = await findModuleFile(agentDir, "result");
+  if (path === undefined) {
+    return undefined;
+  }
+  const imported = await importDefault(ctx, path, "result");
+  if (imported === undefined) {
+    return undefined;
+  }
+  return imported as ResultDefinition;
+}
+
+/** Merge namespaced extension kinds onto the agent's artifacts registry. */
+export function mergeArtifacts(
+  agent: ArtifactsDefinition | undefined,
+  extra: ArtifactsDefinition | undefined
+): ArtifactsDefinition | undefined {
+  if (extra === undefined) {
+    return agent;
+  }
+  if (agent === undefined) {
+    return extra;
+  }
+  return defineArtifacts({
+    kinds: { ...agent.kinds, ...extra.kinds },
+    agentTool: agent.agentTool === true || extra.agentTool === true,
+    max: agent.max ?? extra.max,
+  });
+}
+
 /**
  * Materialize the `tag_artifact` built-in when `defineArtifacts` set
  * `agentTool: true`. Appended after `loadAgent` because the tool is

package/src/internal/discovery/skills.ts

@@ -10,6 +10,7 @@ import type {
   SkillDefinition,
   SkillFileSource,
 } from "../../types.js";
+import { getDefinitionKind } from "../brand.js";
 import { parseFrontmatter } from "../frontmatter.js";
 import { type DiscoveryContext, displayPath, isBlank } from "./context.js";
 import {
@@ -53,7 +54,8 @@ export async function skillFiles(
 
 export async function loadSkills(
   ctx: DiscoveryContext,
-  skillsDir: string
+  skillsDir: string,
+  onDisable?: (name: string, path: string) => void
 ): Promise<DiscoveredSkill[]> {
   if (!(await isDirectory(skillsDir))) {
     return [];
@@ -92,10 +94,18 @@ export async function loadSkills(
       if (!validateName(ctx, "skill", name, entryPath)) {
         continue;
       }
-      const definition = await importDefault(ctx, entryPath, "skill");
+      const definition = await importDefault(
+        ctx,
+        entryPath,
+        onDisable === undefined ? "skill" : ["skill", "disabled"]
+      );
       if (definition === undefined) {
         continue;
       }
+      if (getDefinitionKind(definition) === "disabled") {
+        onDisable?.(name, entryPath);
+        continue;
+      }
       skills.push(compileSkill(name, definition as SkillDefinition));
     }
   }
@@ -156,7 +166,7 @@ async function loadPackagedSkill(
  * Advertise the first non-empty, non-code-fence line of the body, with any
  * leading `#`, `>`, `*`, or `-` markers stripped.
  */
-export function deriveSkillDescription(markdown: string): string | undefined {
+function deriveSkillDescription(markdown: string): string | undefined {
   let inFence = false;
   for (const rawLine of markdown.split(/\r?\n/)) {
     const line = rawLine.trim();

package/src/internal/discovery/subagent.ts

@@ -2,8 +2,14 @@
  * A subagent as the Cursor harness runs it: description, model, and prompt. Its other slots are inert.
  */
 
+import { join } from "node:path";
 import type { ModelSetting, ResolvedAgent } from "../../types.js";
 import { withIdentityPreamble } from "../workspace.js";
+import { loadAgentConfig } from "./agent-config.js";
+import { type DiscoveryContext, displayPath } from "./context.js";
+import { findModuleFile, isDirectory, sortedEntries } from "./fs.js";
+import { loadInstructions } from "./instructions.js";
+import { validateName } from "./names.js";
 
 interface SubagentFields {
   description?: string;
@@ -27,3 +33,104 @@ export function subagent(name: string, fields: SubagentFields): ResolvedAgent {
     seedFiles: [],
   };
 }
+
+export 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 loadSubagent(ctx, subagentDir, entry.name));
+  }
+  return subagents;
+}
+
+export async function loadSubagent(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  name: string
+): Promise<ResolvedAgent> {
+  const config = await loadAgentConfig(ctx, agentDir, false);
+  const prompt = await loadInstructions(ctx, agentDir, config, false);
+  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.",
+    });
+  }
+  const resultPath = await findModuleFile(agentDir, "result");
+  if (resultPath !== undefined) {
+    ctx.diagnostics.push({
+      severity: "warning",
+      path: displayPath(ctx, resultPath),
+      message: "result is not supported on subagents; ignoring.",
+    });
+  }
+  return subagent(config?.name ?? name, {
+    description: config?.description,
+    model: config?.model,
+    prompt,
+  });
+}
+
+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"],
+    ["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.`,
+      });
+    }
+  }
+}

package/src/internal/discovery.ts

@@ -20,7 +20,5 @@ export {
   listChildAgentDirs,
   loadAgentProject,
   loadAgentProjects,
-  RESERVED_SLUGS,
   resolveAgentMounts,
 } from "./discovery/project.js";
-export { deriveSkillDescription } from "./discovery/skills.js";