@cursor/july 0.1.102 → 0.1.103

package/src/internal/discovery/extensions.ts

@@ -1,23 +1,48 @@
 /**
- * `agent/extensions/<ns>.ts` | `agent/extensions/<ns>/extension.ts`: agent-shaped trees and Cursor plugins mounted under a namespace.
+ * `agent/extensions/<ns>.ts` | `agent/extensions/<ns>/extension.ts`:
+ * agent-shaped trees and Cursor plugins mounted under a namespace.
  */
 
 import type { Dirent } from "node:fs";
 import { join, resolve } from "node:path";
 import type {
+  ArtifactsDefinition,
   ConnectionDefinition,
+  DiscoveredAB,
+  DiscoveredChannel,
   DiscoveredConnection,
   DiscoveredExtension,
+  DiscoveredHook,
+  DiscoveredSchedule,
   DiscoveredSkill,
   DiscoveredTool,
   ExtensionMount,
   ResolvedAgent,
+  SeedFile,
   ToolDefinition,
 } from "../../types.js";
-import { getDefinitionKind } from "../brand.js";
-import { compileConnection } from "./connections.js";
+import { buildIdentityPreamble, withIdentityPreamble } from "../workspace.js";
+import { loadABs } from "./ab.js";
+import { loadChannels } from "./channels.js";
+import {
+  compileConnection,
+  compileHostConnection,
+  loadConnections,
+  loadHostConnections,
+} from "./connections.js";
 import { type DiscoveryContext, displayPath } from "./context.js";
 import { type CursorPluginAgent, readCursorPlugin } from "./cursor-plugin.js";
+import {
+  overlayAbs,
+  overlayArtifacts,
+  overlayChannels,
+  overlayHooks,
+  overlayInstructionsFragment,
+  overlaySchedules,
+  overlaySkills,
+  overlaySlot,
+  overlaySubagents,
+} from "./extension-overlay.js";
 import {
   findModuleFile,
   isDirectory,
@@ -26,10 +51,15 @@ import {
   moduleStem,
   sortedEntries,
 } from "./fs.js";
-import { helperCall, importDefault, moduleEntries } from "./modules.js";
+import { loadHooks } from "./hooks.js";
+import { loadInstructions } from "./instructions.js";
+import { importDefault, moduleEntries } from "./modules.js";
 import { validateName } from "./names.js";
+import { loadSchedules } from "./schedules.js";
+import { loadSeedFiles } from "./seed-files.js";
+import { loadArtifacts, mergeArtifacts } from "./services.js";
 import { loadSkills } from "./skills.js";
-import { subagent } from "./subagent.js";
+import { loadSubagents, subagent } from "./subagent.js";
 import { compileTool, loadTools } from "./tools.js";
 
 /** The agent's authored slot lists that mounted extensions append to. */
@@ -37,7 +67,15 @@ export interface ExtensionContributions {
   tools: DiscoveredTool[];
   skills: DiscoveredSkill[];
   connections: DiscoveredConnection[];
+  hostConnections: DiscoveredConnection[];
   subagents: ResolvedAgent[];
+  hooks: DiscoveredHook[];
+  channels: DiscoveredChannel[];
+  schedules: DiscoveredSchedule[];
+  instructionParts: string[];
+  seedFiles: SeedFile[];
+  abs: DiscoveredAB[];
+  artifacts: ArtifactsDefinition | undefined;
 }
 
 /**
@@ -83,7 +121,7 @@ interface MountSite {
   ns: string;
   /** The module default-exporting the {@link ExtensionMount}. */
   mountPath: string;
-  /** A directory mount; its `tools/` and `skills/` overlay the extension's. */
+  /** A directory mount; its slots overlay the extension's. */
   overlayDir?: string;
 }
 
@@ -123,14 +161,46 @@ interface ExtensionTree {
   tools: DiscoveredTool[];
   skills: DiscoveredSkill[];
   connections: DiscoveredConnection[];
+  hostConnections: DiscoveredConnection[];
   /** Connection names the tree declares but left to the mount's overlay. */
   overlaidServers: string[];
   agents: CursorPluginAgent[];
+  subagents: ResolvedAgent[];
+  hooks: DiscoveredHook[];
+  channels: DiscoveredChannel[];
+  schedules: DiscoveredSchedule[];
+  instructions?: string;
+  seedFiles: SeedFile[];
+  abs: DiscoveredAB[];
+  artifacts?: ArtifactsDefinition;
+}
+
+function emptyDiscovered(
+  ns: string,
+  description?: string
+): DiscoveredExtension {
+  return {
+    name: ns,
+    description,
+    tools: [],
+    skills: [],
+    connections: [],
+    hostConnections: [],
+    subagents: [],
+    hooks: [],
+    channels: [],
+    schedules: [],
+    instructions: false,
+    seedFiles: [],
+    abs: [],
+    artifactKinds: [],
+  };
 }
 
 /**
  * Read the extension's tree, lay the mount's overlay on top (a same-named
- * file replaces, `disableTool()` removes), then namespace what is left.
+ * file replaces, `disable()` / `disableTool()` removes), then namespace
+ * what is left.
  */
 async function mountExtension(
   ctx: DiscoveryContext,
@@ -138,14 +208,7 @@ async function mountExtension(
   mount: ExtensionMount,
   into: ExtensionContributions
 ): Promise<DiscoveredExtension> {
-  const mounted: DiscoveredExtension = {
-    name: site.ns,
-    description: mount.extension.description,
-    tools: [],
-    skills: [],
-    connections: [],
-    subagents: [],
-  };
+  const mounted = emptyDiscovered(site.ns, mount.extension.description);
   const root = resolve(ctx.rootDir, mount.extension.root);
   if (!(await isDirectory(root))) {
     const hint =
@@ -159,31 +222,36 @@ async function mountExtension(
     });
     return mounted;
   }
-  // The connection overlay is read first so the tree can leave overlaid
-  // servers uncompiled: a plugin server you replace or drop needs no values.
-  const connectionOverlay =
-    site.overlayDir === undefined
-      ? []
-      : await moduleEntries(
-          ctx,
-          join(site.overlayDir, "mcp-connections"),
-          "connection"
-        );
-  const tree = await readExtensionTree(
-    ctx,
-    site,
-    mount,
-    root,
-    new Set(connectionOverlay.map((entry) => entry.name))
-  );
+  const tree = await readExtensionTree(ctx, site, mount, root);
   if (tree === undefined) {
     return mounted;
   }
   mounted.description = mount.extension.description ?? tree.description;
+
   const tools = byName(tree.tools);
   const skills = byName(tree.skills);
   const connections = byName(tree.connections);
+  const hostConnections = byName(tree.hostConnections);
+  const hooks = byName(tree.hooks);
+  const channels = byId(tree.channels);
+  const schedules = byName(tree.schedules);
+  const subagents = byName(tree.subagents);
+  for (const agent of tree.agents) {
+    subagents.set(agent.name, subagent(agent.name, agent));
+  }
+  const seedFiles = new Map(
+    tree.seedFiles.map((seed) => [seed.relativePath, seed])
+  );
+  const abs = byAbSource(tree.abs);
+  let artifacts = tree.artifacts;
+  let instructions = tree.instructions;
+
   if (site.overlayDir !== undefined) {
+    const connectionOverlay = await moduleEntries(
+      ctx,
+      join(site.overlayDir, "mcp-connections"),
+      "connection"
+    );
     await overlaySlot(
       ctx,
       site,
@@ -191,6 +259,8 @@ async function mountExtension(
       await moduleEntries(ctx, join(site.overlayDir, "tools"), "tool"),
       {
         kind: "tool",
+        disabledKind: "disabled-tool",
+        disableHelper: "disableTool",
         declared: new Set(tools.keys()),
         compile: (ctx, path, name, definition) =>
           compileTool(ctx, path, name, definition as ToolDefinition),
@@ -198,6 +268,8 @@ async function mountExtension(
     );
     await overlaySlot(ctx, site, connections, connectionOverlay, {
       kind: "connection",
+      disabledKind: "disabled-connection",
+      disableHelper: "disableConnection",
       declared: new Set([...connections.keys(), ...tree.overlaidServers]),
       compile: (ctx, path, name, definition) =>
         compileConnection(
@@ -208,13 +280,63 @@ async function mountExtension(
           "model"
         ),
     });
-    for (const skill of await loadSkills(
+    await overlaySlot(
       ctx,
-      join(site.overlayDir, "skills")
-    )) {
-      skills.set(skill.name, skill);
+      site,
+      hostConnections,
+      await moduleEntries(
+        ctx,
+        join(site.overlayDir, "host-connections"),
+        "connection"
+      ),
+      {
+        kind: "connection",
+        disabledKind: "disabled-connection",
+        disableHelper: "disableConnection",
+        declared: new Set(hostConnections.keys()),
+        compile: (ctx, path, name, definition) =>
+          compileHostConnection(
+            ctx,
+            path,
+            name,
+            definition as ConnectionDefinition
+          ),
+      }
+    );
+    await overlaySkills(ctx, site, skills, join(site.overlayDir, "skills"));
+    await overlayHooks(ctx, site, hooks, join(site.overlayDir, "hooks"));
+    await overlayChannels(
+      ctx,
+      site,
+      channels,
+      join(site.overlayDir, "channels")
+    );
+    await overlaySchedules(
+      ctx,
+      site,
+      schedules,
+      join(site.overlayDir, "schedules")
+    );
+    await overlaySubagents(
+      ctx,
+      site,
+      subagents,
+      join(site.overlayDir, "subagents")
+    );
+    const overlayInstructions = await overlayInstructionsFragment(
+      ctx,
+      site.overlayDir
+    );
+    if (overlayInstructions !== "keep") {
+      instructions = overlayInstructions;
     }
+    for (const seed of await loadSeedFiles(ctx, site.overlayDir)) {
+      seedFiles.set(seed.relativePath, seed);
+    }
+    await overlayAbs(ctx, site, abs, site.overlayDir);
+    artifacts = await overlayArtifacts(ctx, site.overlayDir, artifacts);
   }
+
   for (const [name, tool] of tools) {
     const composed = `${site.ns}__${name}`;
     into.tools.push({ ...tool, name: composed, extension: site.ns });
@@ -225,16 +347,86 @@ async function mountExtension(
     into.skills.push({ ...skill, name: composed, extension: site.ns });
     mounted.skills.push(composed);
   }
+  const modelNames = new Set<string>();
   for (const [name, connection] of connections) {
     const composed = `${site.ns}__${name}`;
+    modelNames.add(composed);
     into.connections.push({ ...connection, name: composed });
     mounted.connections.push(composed);
   }
-  for (const agent of tree.agents) {
-    const composed = `${site.ns}__${agent.name}`;
-    into.subagents.push(subagent(composed, agent));
+  for (const [name, connection] of hostConnections) {
+    const composed = `${site.ns}__${name}`;
+    if (modelNames.has(composed)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(root, "host-connections", `${name}.ts`)),
+        message: `Host connection "${composed}" collides with MCP connection "${composed}". Rename one of them.`,
+      });
+      continue;
+    }
+    into.hostConnections.push({ ...connection, name: composed });
+    mounted.hostConnections.push(composed);
+  }
+  for (const [name, child] of subagents) {
+    const composed = `${site.ns}__${name}`;
+    into.subagents.push(namespaceSubagent(composed, child));
     mounted.subagents.push(composed);
   }
+  for (const [name, hook] of hooks) {
+    const composed = `${site.ns}__${name}`;
+    into.hooks.push({ ...hook, name: composed });
+    mounted.hooks.push(composed);
+  }
+  for (const [id, channel] of channels) {
+    const composed = `${site.ns}__${id}`;
+    into.channels.push({ ...channel, id: composed });
+    mounted.channels.push(composed);
+  }
+  for (const [name, schedule] of schedules) {
+    const composed = `${site.ns}__${name}`;
+    into.schedules.push({ ...schedule, name: composed });
+    mounted.schedules.push(composed);
+  }
+  if (instructions !== undefined && instructions !== "") {
+    into.instructionParts.push(instructions);
+    mounted.instructions = true;
+  }
+  for (const seed of seedFiles.values()) {
+    if (
+      into.seedFiles.some(
+        (existing) => existing.relativePath === seed.relativePath
+      )
+    ) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, seed.sourcePath),
+        message: `Extension seed "${seed.relativePath}" collides with an existing workspace seed; keeping the first.`,
+      });
+      continue;
+    }
+    into.seedFiles.push(seed);
+    mounted.seedFiles.push(seed.relativePath);
+  }
+  for (const experiment of abs.values()) {
+    const composed = `${site.ns}__${experiment.name}`;
+    into.abs.push({
+      name: composed,
+      definition: experiment.definition,
+    });
+    mounted.abs.push(composed);
+  }
+  if (artifacts !== undefined) {
+    const kinds: NonNullable<ArtifactsDefinition["kinds"]> = {};
+    for (const [kind, config] of Object.entries(artifacts.kinds ?? {})) {
+      const composed = `${site.ns}__${kind}`;
+      kinds[composed] = config;
+      mounted.artifactKinds.push(composed);
+    }
+    into.artifacts = mergeArtifacts(into.artifacts, {
+      ...artifacts,
+      kinds,
+    });
+  }
   return mounted;
 }
 
@@ -242,26 +434,84 @@ async function readExtensionTree(
   ctx: DiscoveryContext,
   site: MountSite,
   mount: ExtensionMount,
-  root: string,
-  overlaidServers: ReadonlySet<string>
+  root: string
 ): Promise<ExtensionTree | undefined> {
   if ("layout" in mount.extension) {
+    const connectionOverlay =
+      site.overlayDir === undefined
+        ? []
+        : await moduleEntries(
+            ctx,
+            join(site.overlayDir, "mcp-connections"),
+            "connection"
+          );
     const plugin = await readCursorPlugin(
       ctx,
       root,
       site.mountPath,
       mount.extension.variables,
-      overlaidServers
+      new Set(connectionOverlay.map((entry) => entry.name))
     );
-    return plugin === undefined ? undefined : { ...plugin, tools: [] };
+    if (plugin === undefined) {
+      return undefined;
+    }
+    return {
+      ...plugin,
+      tools: [],
+      hostConnections: [],
+      subagents: [],
+      hooks: [],
+      channels: [],
+      schedules: [],
+      seedFiles: [],
+      abs: [],
+    };
   }
-  await warnUnsupportedExtensionSlots(ctx, root);
+  return readNativeTree(ctx, root);
+}
+
+async function readNativeTree(
+  ctx: DiscoveryContext,
+  root: string
+): Promise<ExtensionTree> {
+  await warnAgentRootOnlySlots(ctx, root);
+  const connections = await loadConnections(ctx, join(root, "mcp-connections"));
   return {
     tools: await loadTools(ctx, join(root, "tools")),
     skills: await loadSkills(ctx, join(root, "skills")),
-    connections: [],
+    connections,
+    hostConnections: await loadHostConnections(ctx, root, connections),
     overlaidServers: [],
     agents: [],
+    subagents: await loadSubagents(ctx, join(root, "subagents")),
+    hooks: await loadHooks(ctx, join(root, "hooks")),
+    channels: (await loadChannels(ctx, join(root, "channels"), "extension"))
+      .channels,
+    schedules: await loadSchedules(ctx, join(root, "schedules")),
+    instructions: await loadInstructions(ctx, root, undefined, false),
+    seedFiles: await loadSeedFiles(ctx, root),
+    abs: await loadABs(ctx, root),
+    artifacts: await loadArtifacts(ctx, root),
+  };
+}
+
+function namespaceSubagent(
+  composed: string,
+  child: ResolvedAgent
+): ResolvedAgent {
+  const oldPreamble = buildIdentityPreamble(child.name);
+  let body = child.instructions;
+  if (
+    body !== undefined &&
+    oldPreamble !== "" &&
+    body.startsWith(oldPreamble)
+  ) {
+    body = body.slice(oldPreamble.length).replace(/^\n+/, "");
+  }
+  return {
+    ...child,
+    name: composed,
+    instructions: withIdentityPreamble(composed, body),
   };
 }
 
@@ -269,79 +519,54 @@ function byName<T extends { name: string }>(items: T[]): Map<string, T> {
   return new Map(items.map((item) => [item.name, item]));
 }
 
-/** One overlayable slot: what a file may export and how it compiles. */
-interface OverlaySlot<T> {
-  kind: "tool" | "connection";
-  /** Names the extension contributes; a disable marker must name one. */
-  declared: ReadonlySet<string>;
-  compile: (
-    ctx: DiscoveryContext,
-    path: string,
-    name: string,
-    definition: unknown
-  ) => Promise<T | undefined> | T | undefined;
+function byAbSource(items: DiscoveredAB[]): Map<string, DiscoveredAB> {
+  return new Map(items.map((item) => [item.source ?? item.name, item]));
+}
+
+function byId<T extends { id: string }>(items: T[]): Map<string, T> {
+  return new Map(items.map((item) => [item.id, item]));
 }
 
 /**
- * Lay a directory mount's slot over the extension's contributions: a
- * same-named file replaces, a disable marker removes, a new name adds.
+ * Agent-singleton slots: one runtime (`agent.ts`), one storage backend,
+ * one OTLP exporter, one A/B platform config. Playground chips are a
+ * Vite glob of the agent tree, not a discovery walk. Nested
+ * `extensions/` are not mounted.
  */
-async function overlaySlot<T extends { name: string }>(
+async function warnAgentRootOnlySlots(
   ctx: DiscoveryContext,
-  site: MountSite,
-  contributed: Map<string, T>,
-  entries: Array<{ name: string; path: string }>,
-  slot: OverlaySlot<T>
+  root: string
 ): Promise<void> {
-  const disabledKind = `disabled-${slot.kind}` as const;
-  for (const { name, path } of entries) {
-    const definition = await importDefault(ctx, path, [
-      slot.kind,
-      disabledKind,
-    ]);
-    if (definition === undefined) {
-      continue;
-    }
-    if (getDefinitionKind(definition) === disabledKind) {
-      contributed.delete(name);
-      if (!slot.declared.has(name)) {
-        ctx.diagnostics.push({
-          severity: "error",
-          path: displayPath(ctx, path),
-          message: `${helperCall(disabledKind)} targets "${name}", which extension "${site.ns}" does not contribute.`,
-        });
-      }
-      continue;
-    }
-    const item = await slot.compile(ctx, path, name, definition);
-    if (item !== undefined) {
-      contributed.set(name, item);
+  const files = [
+    ["agent.ts", "agent.ts"],
+    ["storage.ts", "storage"],
+    ["otel.ts", "otel"],
+    ["ab.config.ts", "A/B config"],
+  ] as const;
+  for (const [file, label] of files) {
+    const path = join(root, file);
+    if (await isFile(path)) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, path),
+        message: `The agent that mounts this extension owns ${label}; ignoring.`,
+      });
     }
   }
-}
-
-/** Slots an agent has that an extension tree may not contribute (yet). */
-async function warnUnsupportedExtensionSlots(
-  ctx: DiscoveryContext,
-  root: string
-): Promise<void> {
-  const unsupported = [
-    ["instructions.md", "instructions"],
-    ["connections", "connections"],
-    ["mcp-connections", "MCP connections"],
-    ["hooks", "hooks"],
-    ["subagents", "subagents"],
-    ["channels", "channels"],
-    ["schedules", "schedules"],
-    ["extensions", "nested extensions"],
+  const dirs = [
+    [
+      "playground",
+      "Playground chips are a Vite glob of the agent tree, not an extension slot; ignoring.",
+    ],
+    ["extensions", "Nested extensions are not mounted; ignoring."],
   ] as const;
-  for (const [slot, label] of unsupported) {
+  for (const [slot, message] of dirs) {
     const path = join(root, slot);
-    if ((await isDirectory(path)) || (await isFile(path))) {
+    if (await isDirectory(path)) {
       ctx.diagnostics.push({
         severity: "warning",
         path: displayPath(ctx, path),
-        message: `Extension ${label} are not supported yet; only tools/ and skills/ are mounted. Ignoring.`,
+        message,
       });
     }
   }

package/src/internal/discovery/hooks.ts

@@ -4,13 +4,15 @@
 
 import { basename, extname, relative } from "node:path";
 import type { DiscoveredHook, HookDefinition } from "../../types.js";
+import { getDefinitionKind } from "../brand.js";
 import { type DiscoveryContext, displayPath } from "./context.js";
 import { isDirectory, isModuleFile, toPosix, walkFiles } from "./fs.js";
 import { importDefault } from "./modules.js";
 
 export async function loadHooks(
   ctx: DiscoveryContext,
-  hooksDir: string
+  hooksDir: string,
+  onDisable?: (name: string, path: string) => void
 ): Promise<DiscoveredHook[]> {
   if (!(await isDirectory(hooksDir))) {
     return [];
@@ -22,10 +24,26 @@ export async function loadHooks(
     }
     const rel = toPosix(relative(hooksDir, filePath));
     const name = rel.slice(0, -extname(rel).length);
-    const definition = await importDefault(ctx, filePath, "hook");
+    if (name.includes("__")) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, filePath),
+        message: `Hook name "${name}" may not contain "__"; it is reserved for extension contributions (\`<ns>__<name>\`).`,
+      });
+      continue;
+    }
+    const definition = await importDefault(
+      ctx,
+      filePath,
+      onDisable === undefined ? "hook" : ["hook", "disabled"]
+    );
     if (definition === undefined) {
       continue;
     }
+    if (getDefinitionKind(definition) === "disabled") {
+      onDisable?.(name, filePath);
+      continue;
+    }
     const hook = definition as HookDefinition;
     if (
       typeof hook.events !== "object" ||

package/src/internal/discovery/info.ts

@@ -128,6 +128,12 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
         if (meta?.originWebhookEvents !== undefined) {
           info.originWebhookEvents = meta.originWebhookEvents;
         }
+        if (meta?.gitlabWebhookEvents !== undefined) {
+          info.gitlabWebhookEvents = meta.gitlabWebhookEvents;
+        }
+        if (meta?.bitbucketWebhookEvents !== undefined) {
+          info.bitbucketWebhookEvents = meta.bitbucketWebhookEvents;
+        }
         if (meta?.deploymentEventTypes !== undefined) {
           info.deploymentEventTypes = meta.deploymentEventTypes;
         }
@@ -167,6 +173,7 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
             agentTool: project.artifacts.agentTool === true,
             max: resolveArtifactsMax(project.artifacts),
           },
+    result: project.result === undefined ? undefined : true,
     otel:
       project.otel === undefined
         ? undefined

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",
 };