@cursor/july 0.1.100 → 0.1.102

package/src/internal/discovery/extensions.ts

@@ -0,0 +1,348 @@
+/**
+ * `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 {
+  ConnectionDefinition,
+  DiscoveredConnection,
+  DiscoveredExtension,
+  DiscoveredSkill,
+  DiscoveredTool,
+  ExtensionMount,
+  ResolvedAgent,
+  ToolDefinition,
+} from "../../types.js";
+import { getDefinitionKind } from "../brand.js";
+import { compileConnection } from "./connections.js";
+import { type DiscoveryContext, displayPath } from "./context.js";
+import { type CursorPluginAgent, readCursorPlugin } from "./cursor-plugin.js";
+import {
+  findModuleFile,
+  isDirectory,
+  isFile,
+  isModuleFile,
+  moduleStem,
+  sortedEntries,
+} from "./fs.js";
+import { helperCall, importDefault, moduleEntries } from "./modules.js";
+import { validateName } from "./names.js";
+import { loadSkills } from "./skills.js";
+import { subagent } from "./subagent.js";
+import { compileTool, loadTools } from "./tools.js";
+
+/** The agent's authored slot lists that mounted extensions append to. */
+export interface ExtensionContributions {
+  tools: DiscoveredTool[];
+  skills: DiscoveredSkill[];
+  connections: DiscoveredConnection[];
+  subagents: ResolvedAgent[];
+}
+
+/**
+ * Mount every extension under `agent/extensions/` and append what it
+ * contributes to the authored lists as `<ns>__<name>`, stamped with
+ * `extension`. The namespace is the mount's filename stem or directory name.
+ */
+export async function appendExtensions(
+  ctx: DiscoveryContext,
+  extensionsDir: string,
+  into: ExtensionContributions
+): Promise<DiscoveredExtension[]> {
+  if (!(await isDirectory(extensionsDir))) {
+    return [];
+  }
+  const extensions: DiscoveredExtension[] = [];
+  for (const entry of await sortedEntries(extensionsDir)) {
+    const path = join(extensionsDir, entry.name);
+    const site = await resolveMountSite(ctx, path, entry);
+    if (site === undefined) {
+      continue;
+    }
+    if (extensions.some((extension) => extension.name === site.ns)) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, path),
+        message: `Extension "${site.ns}" is mounted twice (as a file and as a directory).`,
+      });
+      continue;
+    }
+    const mount = await importDefault(ctx, site.mountPath, "extension");
+    if (mount === undefined) {
+      continue;
+    }
+    extensions.push(
+      await mountExtension(ctx, site, mount as ExtensionMount, into)
+    );
+  }
+  return extensions;
+}
+
+interface MountSite {
+  ns: string;
+  /** The module default-exporting the {@link ExtensionMount}. */
+  mountPath: string;
+  /** A directory mount; its `tools/` and `skills/` overlay the extension's. */
+  overlayDir?: string;
+}
+
+async function resolveMountSite(
+  ctx: DiscoveryContext,
+  path: string,
+  entry: Dirent
+): Promise<MountSite | undefined> {
+  if (entry.isDirectory()) {
+    if (!validateName(ctx, "extension", entry.name, path)) {
+      return undefined;
+    }
+    const mountPath = await findModuleFile(path, "extension");
+    if (mountPath === undefined) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, path),
+        message:
+          "A directory mount needs an extension.ts default-exporting the mount (`export default ci({ ... })`).",
+      });
+      return undefined;
+    }
+    return { ns: entry.name, mountPath, overlayDir: path };
+  }
+  if (!entry.isFile() || !isModuleFile(entry.name)) {
+    return undefined;
+  }
+  const ns = moduleStem(entry.name);
+  return validateName(ctx, "extension", ns, path)
+    ? { ns, mountPath: path }
+    : undefined;
+}
+
+/** What a mounted tree contributes, under the tree's own names. */
+interface ExtensionTree {
+  description?: string;
+  tools: DiscoveredTool[];
+  skills: DiscoveredSkill[];
+  connections: DiscoveredConnection[];
+  /** Connection names the tree declares but left to the mount's overlay. */
+  overlaidServers: string[];
+  agents: CursorPluginAgent[];
+}
+
+/**
+ * Read the extension's tree, lay the mount's overlay on top (a same-named
+ * file replaces, `disableTool()` removes), then namespace what is left.
+ */
+async function mountExtension(
+  ctx: DiscoveryContext,
+  site: MountSite,
+  mount: ExtensionMount,
+  into: ExtensionContributions
+): Promise<DiscoveredExtension> {
+  const mounted: DiscoveredExtension = {
+    name: site.ns,
+    description: mount.extension.description,
+    tools: [],
+    skills: [],
+    connections: [],
+    subagents: [],
+  };
+  const root = resolve(ctx.rootDir, mount.extension.root);
+  if (!(await isDirectory(root))) {
+    const hint =
+      "layout" in mount.extension
+        ? "Point `path` at the plugin directory."
+        : "Pass `import.meta.dirname` from extension.ts.";
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, site.mountPath),
+      message: `Extension "${site.ns}" declares root ${root}, which is not a directory. ${hint}`,
+    });
+    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))
+  );
+  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);
+  if (site.overlayDir !== undefined) {
+    await overlaySlot(
+      ctx,
+      site,
+      tools,
+      await moduleEntries(ctx, join(site.overlayDir, "tools"), "tool"),
+      {
+        kind: "tool",
+        declared: new Set(tools.keys()),
+        compile: (ctx, path, name, definition) =>
+          compileTool(ctx, path, name, definition as ToolDefinition),
+      }
+    );
+    await overlaySlot(ctx, site, connections, connectionOverlay, {
+      kind: "connection",
+      declared: new Set([...connections.keys(), ...tree.overlaidServers]),
+      compile: (ctx, path, name, definition) =>
+        compileConnection(
+          ctx,
+          path,
+          name,
+          definition as ConnectionDefinition,
+          "model"
+        ),
+    });
+    for (const skill of await loadSkills(
+      ctx,
+      join(site.overlayDir, "skills")
+    )) {
+      skills.set(skill.name, skill);
+    }
+  }
+  for (const [name, tool] of tools) {
+    const composed = `${site.ns}__${name}`;
+    into.tools.push({ ...tool, name: composed, extension: site.ns });
+    mounted.tools.push(composed);
+  }
+  for (const [name, skill] of skills) {
+    const composed = `${site.ns}__${name}`;
+    into.skills.push({ ...skill, name: composed, extension: site.ns });
+    mounted.skills.push(composed);
+  }
+  for (const [name, connection] of connections) {
+    const composed = `${site.ns}__${name}`;
+    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));
+    mounted.subagents.push(composed);
+  }
+  return mounted;
+}
+
+async function readExtensionTree(
+  ctx: DiscoveryContext,
+  site: MountSite,
+  mount: ExtensionMount,
+  root: string,
+  overlaidServers: ReadonlySet<string>
+): Promise<ExtensionTree | undefined> {
+  if ("layout" in mount.extension) {
+    const plugin = await readCursorPlugin(
+      ctx,
+      root,
+      site.mountPath,
+      mount.extension.variables,
+      overlaidServers
+    );
+    return plugin === undefined ? undefined : { ...plugin, tools: [] };
+  }
+  await warnUnsupportedExtensionSlots(ctx, root);
+  return {
+    tools: await loadTools(ctx, join(root, "tools")),
+    skills: await loadSkills(ctx, join(root, "skills")),
+    connections: [],
+    overlaidServers: [],
+    agents: [],
+  };
+}
+
+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;
+}
+
+/**
+ * Lay a directory mount's slot over the extension's contributions: a
+ * same-named file replaces, a disable marker removes, a new name adds.
+ */
+async function overlaySlot<T extends { name: string }>(
+  ctx: DiscoveryContext,
+  site: MountSite,
+  contributed: Map<string, T>,
+  entries: Array<{ name: string; path: string }>,
+  slot: OverlaySlot<T>
+): 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);
+    }
+  }
+}
+
+/** 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"],
+  ] as const;
+  for (const [slot, label] of unsupported) {
+    const path = join(root, slot);
+    if ((await isDirectory(path)) || (await isFile(path))) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, path),
+        message: `Extension ${label} are not supported yet; only tools/ and skills/ are mounted. Ignoring.`,
+      });
+    }
+  }
+}

package/src/internal/discovery/fs.ts

@@ -0,0 +1,108 @@
+/**
+ * Filesystem primitives discovery walks with: module-file detection, directory listing, and project-root markers.
+ */
+
+import type { Dirent } from "node:fs";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { extname, join } from "node:path";
+
+const MODULE_EXTENSIONS = new Set([".ts", ".mts", ".js", ".mjs"]);
+
+export async function findModuleFile(
+  dir: string,
+  stem: string
+): Promise<string | undefined> {
+  for (const extension of [".ts", ".mts", ".js", ".mjs"]) {
+    const candidate = join(dir, `${stem}${extension}`);
+    if (await isFile(candidate)) {
+      return candidate;
+    }
+  }
+  return undefined;
+}
+
+export function isModuleFile(fileName: string): boolean {
+  if (fileName.endsWith(".d.ts") || fileName.startsWith(".")) {
+    return false;
+  }
+  if (!MODULE_EXTENSIONS.has(extname(fileName))) {
+    return false;
+  }
+  // Colocated unit tests (Vitest/Jest convention) are not definitions.
+  // Without this, `channels/slack.test.ts` is scanned as a channel named
+  // "slack.test", fails NAME_PATTERN, and the whole agent refuses to serve.
+  const stem = moduleStem(fileName);
+  return !stem.endsWith(".test") && !stem.endsWith(".spec");
+}
+
+export function moduleStem(fileName: string): string {
+  return fileName.slice(0, -extname(fileName).length);
+}
+
+export async function sortedEntries(dir: string): Promise<Dirent[]> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  return entries.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export async function walkFiles(dir: string): Promise<string[]> {
+  const files: string[] = [];
+  for (const entry of await sortedEntries(dir)) {
+    if (entry.name.startsWith(".")) {
+      continue;
+    }
+    const entryPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await walkFiles(entryPath)));
+    } else if (entry.isFile()) {
+      files.push(entryPath);
+    }
+  }
+  return files;
+}
+
+export async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export async function isFile(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export function toPosix(path: string): string {
+  return path.split("\\").join("/");
+}
+
+export async function hasFlatLayoutMarkers(rootDir: string): Promise<boolean> {
+  if (await isFile(join(rootDir, "instructions.md"))) {
+    return true;
+  }
+  return (await findModuleFile(rootDir, "agent")) !== undefined;
+}
+
+export async function readPackageName(
+  rootDir: string
+): Promise<string | undefined> {
+  const packageJsonPath = join(rootDir, "package.json");
+  if (!(await isFile(packageJsonPath))) {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(await readFile(packageJsonPath, "utf8")) as {
+      name?: unknown;
+    };
+    if (typeof parsed.name === "string" && parsed.name !== "") {
+      return parsed.name;
+    }
+  } catch {
+    // Malformed package.json falls back to the directory name.
+  }
+  return undefined;
+}

package/src/internal/discovery/hooks.ts

@@ -0,0 +1,45 @@
+/**
+ * `agent/hooks/*.ts`: observe-only event subscribers.
+ */
+
+import { basename, extname, relative } from "node:path";
+import type { DiscoveredHook, HookDefinition } from "../../types.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
+): Promise<DiscoveredHook[]> {
+  if (!(await isDirectory(hooksDir))) {
+    return [];
+  }
+  const hooks: DiscoveredHook[] = [];
+  for (const filePath of await walkFiles(hooksDir)) {
+    if (!isModuleFile(basename(filePath))) {
+      continue;
+    }
+    const rel = toPosix(relative(hooksDir, filePath));
+    const name = rel.slice(0, -extname(rel).length);
+    const definition = await importDefault(ctx, filePath, "hook");
+    if (definition === undefined) {
+      continue;
+    }
+    const hook = definition as HookDefinition;
+    if (
+      typeof hook.events !== "object" ||
+      hook.events === null ||
+      Object.keys(hook.events).length === 0
+    ) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, filePath),
+        message: "Hook declares no event handlers.",
+      });
+      continue;
+    }
+    hooks.push({ name, definition: hook });
+  }
+  return hooks;
+}

package/src/internal/discovery/info.ts

@@ -0,0 +1,179 @@
+/**
+ * The `info` / `GET /v1/info` projection of an {@link AgentProject}.
+ */
+
+import { resolveABMaxPlaygroundSessions } from "../../ab.js";
+import { resolveArtifactsMax } from "../../artifacts.js";
+import {
+  type AgentProject,
+  type AgentProjectInfo,
+  toPublicCloudInfo,
+} from "../../types.js";
+import { toolInputJsonSchema } from "../json-schema.js";
+import { MCP_ENDPOINT_PATH, mcpEndpointToolNames } from "../mcp-endpoint.js";
+import { connectionTransportLabel } from "./connections.js";
+
+export function projectInfo(project: AgentProject): AgentProjectInfo {
+  const agent = project.agent;
+  const httpRoutes: AgentProjectInfo["channels"][number]["routes"] = [
+    { method: "POST", path: "/v1/session", url: "/v1/session" },
+    {
+      method: "POST",
+      path: "/v1/session/:sessionId",
+      url: "/v1/session/:sessionId",
+    },
+    {
+      method: "POST",
+      path: "/v1/session/:sessionId/stop",
+      url: "/v1/session/:sessionId/stop",
+    },
+    {
+      method: "GET",
+      path: "/v1/session/:sessionId/stream",
+      url: "/v1/session/:sessionId/stream",
+    },
+    {
+      method: "GET",
+      path: "/v1/session/:sessionId/approvals",
+      url: "/v1/session/:sessionId/approvals",
+    },
+    {
+      method: "POST",
+      path: "/v1/session/:sessionId/approvals/:callId",
+      url: "/v1/session/:sessionId/approvals/:callId",
+    },
+  ];
+  return {
+    name: project.name,
+    description: agent.description,
+    model: agent.model,
+    runtime: agent.runtime,
+    cloud:
+      agent.cloud === undefined ? undefined : toPublicCloudInfo(agent.cloud),
+    local: agent.local,
+    hosting: agent.hosting,
+    concurrency: agent.concurrency,
+    mcp: { path: MCP_ENDPOINT_PATH, tools: mcpEndpointToolNames(project) },
+    instructions:
+      agent.instructions === undefined
+        ? undefined
+        : {
+            chars: agent.instructions.length,
+            preview:
+              agent.instructions.length > 280
+                ? `${agent.instructions.slice(0, 277)}...`
+                : agent.instructions,
+          },
+    tools: agent.tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      execution: tool.execution,
+      needsApproval: tool.needsApproval,
+      effect: tool.effect,
+      inputSchema: tool.inputSchema,
+    })),
+    skills: agent.skills.map((skill) => ({
+      name: skill.name,
+      description: skill.description,
+    })),
+    extensions: agent.extensions ?? [],
+    connections: agent.connections.map((connection) => ({
+      name: connection.name,
+      transport: connectionTransportLabel(connection.transport),
+      advertiseTools: connection.advertiseTools,
+      effects: connection.effects,
+      tools: connection.tools,
+      disallowedTools: connection.disallowedTools,
+      cursorAccountServers:
+        "cursorAccount" in connection.transport
+          ? (connection.transport.servers ?? "*")
+          : undefined,
+    })),
+    subagents: agent.subagents.map((subagent) => ({
+      name: subagent.name,
+      description: subagent.description,
+      model: subagent.model,
+    })),
+    channels: [
+      { id: "http", routes: httpRoutes },
+      ...project.channels.map((channel) => {
+        const info: AgentProjectInfo["channels"][number] = {
+          id: channel.id,
+          routes: (channel.definition.routes ?? []).map((r) => {
+            const routeInfo: AgentProjectInfo["channels"][number]["routes"][number] =
+              {
+                method: r.method,
+                path: r.path,
+                url: `/v1/channels/${channel.id}${r.path}`,
+              };
+            if (r.description !== undefined) {
+              routeInfo.description = r.description;
+            }
+            if (r.bodySchema !== undefined) {
+              routeInfo.bodySchema = toolInputJsonSchema(r.bodySchema);
+            }
+            if (r.querySchema !== undefined) {
+              routeInfo.querySchema = toolInputJsonSchema(r.querySchema);
+            }
+            return routeInfo;
+          }),
+        };
+        const meta = channel.definition.meta;
+        if (meta?.kind !== undefined) {
+          info.kind = meta.kind;
+        }
+        if (meta?.githubWebhookEvents !== undefined) {
+          info.githubWebhookEvents = meta.githubWebhookEvents;
+        }
+        if (meta?.originWebhookEvents !== undefined) {
+          info.originWebhookEvents = meta.originWebhookEvents;
+        }
+        if (meta?.deploymentEventTypes !== undefined) {
+          info.deploymentEventTypes = meta.deploymentEventTypes;
+        }
+        if (meta?.slackChannelPosts !== undefined) {
+          info.slackChannelPosts = meta.slackChannelPosts;
+        }
+        return info;
+      }),
+    ],
+    schedules: project.schedules.map((schedule) => ({
+      name: schedule.name,
+      cron: schedule.cron,
+      kind: schedule.kind,
+    })),
+    hooks: project.hooks.map((hook) => hook.name),
+    abs: project.abs.map((experiment) => experiment.name),
+    ...(project.abConfig === undefined && project.abs.length === 0
+      ? {}
+      : {
+          abConfig: {
+            maxPlaygroundSessions: resolveABMaxPlaygroundSessions(
+              project.abConfig?.maxPlaygroundSessions
+            ),
+            durableSamples: project.storage?.abs !== undefined,
+            durableSnapshots: project.storage?.abs?.putSnapshot !== undefined,
+          },
+        }),
+    storage:
+      project.storage === undefined
+        ? undefined
+        : { name: project.storage.name },
+    artifacts:
+      project.artifacts === undefined
+        ? undefined
+        : {
+            kinds: Object.keys(project.artifacts.kinds ?? {}),
+            agentTool: project.artifacts.agentTool === true,
+            max: resolveArtifactsMax(project.artifacts),
+          },
+    otel:
+      project.otel === undefined
+        ? undefined
+        : {
+            enabled: true as const,
+            serviceName: project.otel.serviceName,
+          },
+    diagnostics: project.diagnostics,
+  };
+}